@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
714 lines (672 loc) • 32.7 kB
text/typescript
import { hasHumanDashboardSession } from "./consent-session";
/**
* /api/codex-prompt — the Codex prompt-layer surface.
*
* This route is an adapter over `src/codex/prompt-layers.ts`. It owns three
* things the core module deliberately does not: the projection of
* `LAYER_INVENTORY` into a DTO, request-shape and size policy, and the
* translation of a `WriteError` into an HTTP status. It owns no file access of
* its own and defines no second inventory.
*
* Privacy: the snapshot carries file paths and the user's own prompt text —
* text they typed into this same dashboard. It carries no token, API key, or
* account identifier, and nothing here is written to a log sink.
*
* Auth: the standard management gate covers /api/**, and unsafe methods already
* require Origin + CSRF. This is a local-config write, not an action that spends
* the user's GitHub identity, so it does NOT carry the `agent_consent_required`
* treatment `sidebar-routes.ts` applies to starring.
*
* Plan: devlog/_plan/260802_codex_set_prompt_composer/020 + 021 (021 supersedes
* 020 wherever the landed WP1 module moved).
*/
import { jsonResponse } from "../auth-cors";
import { readFileSync } from "node:fs";
import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
import type { ManagementContext } from "./context";
import {
LAYER_INVENTORY,
MAX_BASE_VARIANTS,
adoptDeveloperInstructions,
composeProjection,
computePromptProbeStateFingerprint,
findInvalidCharacter,
importBaseVariant,
inspectOwnership,
normalizeBody,
previewAdopt,
previewBaseImport,
previewSalvage,
readPromptLayers,
recoverPromptJournal,
salvageProjection,
selectBaseVariant,
setToggle,
writeBaseVariant,
writeCustomLayers,
type BaseSelection,
type CustomLayer,
type Paths,
type PromptLayerSnapshot,
type WriteError,
type WriteResult,
} from "../../codex/prompt-layers";
/**
* Third-party extension layers cannot be enumerated (devlog 001 class E), and no
* WP1 export can say so — it is a statement about what opencodex can know, not
* about the user's file. Stating it explicitly beats implying the inventory is
* exhaustive. If class E ever becomes enumerable, this constant is what changes.
*/
const EXTENSION_LAYERS_ENUMERABLE = false;
/** Route policy, not a Codex limit: Codex validates nothing beyond readable-and-non-empty. */
const MAX_LAYERS = 32;
const MAX_TITLE_CHARS = 80;
const MAX_BODY_BYTES = 64 * 1024;
const MAX_COMPOSED_BYTES = 128 * 1024;
const LAYER_ID = /^[a-z0-9]{6}$/;
/**
* Every WriteError gets a status. This is a Record, not a switch with a default:
* a variant added to the union upstream breaks `bun run typecheck` here instead
* of silently becoming a 500 in front of a user.
*/
const WRITE_ERROR_STATUS: Record<WriteError, number> = {
config_unreadable: 409,
stale_revision: 409,
developer_instructions_not_owned: 409,
unknown_layer: 400,
store_unreadable: 409,
invalid_characters: 400,
body_too_large: 400,
write_superseded: 409,
// Not the caller's fault and not a race: the filesystem refused the write and the
// transaction rolled itself back. 500 rather than 409 — retrying the same request
// unchanged will fail the same way until the disk or the path is fixed.
write_failed: 500,
recovery_required: 409,
locked: 409,
unsafe: 422,
import_body_changed: 409,
unsupported_form: 409,
};
/** Read-only view for the route test that asserts every mapping is a client error. */
export const WRITE_ERROR_STATUS_FOR_TESTS: Readonly<Record<WriteError, number>> = WRITE_ERROR_STATUS;
function fail(ctx: ManagementContext, code: string, status: number, message?: string, extra?: Record<string, unknown>): Response {
return jsonResponse({ ok: false, code, ...(message ? { message } : {}), ...(extra ?? {}) }, status, ctx.req, ctx.config);
}
function failWrite(ctx: ManagementContext, result: Extract<WriteResult, { ok: false }>): Response {
return fail(ctx, result.error, WRITE_ERROR_STATUS[result.error], result.detail);
}
function paths(ctx: ManagementContext): Paths | undefined {
return ctx.deps.codexPromptPaths;
}
function utf8Bytes(value: string): number {
return Buffer.byteLength(value, "utf8");
}
/** The DTO. `inventory` is `LAYER_INVENTORY` serialized — never a second table. */
function serialize(snapshot: PromptLayerSnapshot, configBytes: string | null): Record<string, unknown> {
return {
configPath: snapshot.configPath,
storePath: snapshot.storePath,
configExists: snapshot.configExists,
readable: snapshot.readable,
developerInstructionsOwned: snapshot.developerInstructionsOwned,
/**
* `developerInstructionsOwned: false` conflates two very different states: the
* key is ABSENT (an ordinary first run - the first write creates it) and the key
* is EXTERNAL (someone else wrote it, and we must not overwrite it). A GUI that
* cannot tell them apart hides its own create affordance from every new user,
* which is exactly what happened. The state is named here rather than guessed
* there.
*/
developerInstructionsState: inspectOwnership(configBytes).state,
drift: snapshot.drift,
revision: snapshot.revision,
inventory: LAYER_INVENTORY.map(d => ({
id: d.id,
class: d.class,
key: d.key,
default: d.default,
order: d.order,
})),
toggles: snapshot.toggles,
extensionLayersEnumerable: EXTENSION_LAYERS_ENUMERABLE,
custom: snapshot.custom,
modelInstructionsFile: snapshot.modelInstructionsFile,
baseVariants: snapshot.baseVariants,
/**
* Three-valued on purpose. `external` is not folded into `default`: the key being
* set to somebody else's file means the base prompt IS replaced, and reporting that
* as "Codex's own prompt" would be a lie the GUI then repeats to the user.
*/
baseSelection: snapshot.baseSelection,
maxBaseVariants: MAX_BASE_VARIANTS,
};
}
/** Re-read the bytes the snapshot was derived from, so the DTO can name the ownership state. */
function configBytesOf(snapshot: PromptLayerSnapshot): string | null {
if (!snapshot.configExists) return null;
try {
return readFileSync(snapshot.configPath, "utf8");
} catch {
return null;
}
}
function ok(ctx: ManagementContext, changed: boolean, snapshot: PromptLayerSnapshot): Response {
return jsonResponse({ ok: true, changed, snapshot: serialize(snapshot, configBytesOf(snapshot)) }, 200, ctx.req, ctx.config);
}
/** Re-read after a mutation so the GUI can publish server truth, not optimistic state. */
function settle(ctx: ManagementContext, result: WriteResult): Response {
return result.ok ? ok(ctx, result.changed, result.snapshot) : failWrite(ctx, result);
}
type ValidationError = { code: string; message: string; extra?: Record<string, unknown> };
/**
* Request validation, entirely before any file access. WP1 validates characters
* and normalizes; shape and size policy is the route's, and the GUI's identical
* client-side rules are courtesy — this is the boundary.
*/
function validateLayers(raw: unknown): { layers: CustomLayer[] } | { error: ValidationError } {
if (!Array.isArray(raw)) return { error: { code: "invalid_body", message: "layers must be an array" } };
if (raw.length > MAX_LAYERS) {
return { error: { code: "too_many_layers", message: `at most ${MAX_LAYERS} layers` } };
}
const seen = new Set<string>();
const layers: CustomLayer[] = [];
for (const entry of raw) {
if (!entry || typeof entry !== "object" || Array.isArray(entry)) {
return { error: { code: "invalid_body", message: "each layer must be an object" } };
}
const v = entry as Record<string, unknown>;
if (typeof v.id !== "string" || !LAYER_ID.test(v.id)) {
return { error: { code: "invalid_layer_id", message: "id must be six lowercase alphanumerics" } };
}
if (seen.has(v.id)) {
return { error: { code: "duplicate_layer_id", message: `duplicate id ${v.id}` } };
}
seen.add(v.id);
if (typeof v.title !== "string" || v.title.trim().length === 0
|| v.title.length > MAX_TITLE_CHARS || /[\r\n]/.test(v.title)) {
return { error: { code: "invalid_title", message: "title must be 1-80 characters on a single line" } };
}
if (typeof v.body !== "string") {
return { error: { code: "invalid_body", message: "body must be a string" } };
}
if (typeof v.enabled !== "boolean") {
return { error: { code: "invalid_body", message: "enabled must be a boolean" } };
}
// Normalize first, then measure and scan: tabs and CRLF are normalized rather
// than rejected, so the cap must apply to what would actually be stored.
const body = normalizeBody(v.body);
if (utf8Bytes(body) > MAX_BODY_BYTES) {
return { error: { code: "body_too_large", message: `layer ${v.id} exceeds ${MAX_BODY_BYTES} bytes` } };
}
const invalid = findInvalidCharacter(body);
if (invalid !== null) {
return {
error: {
code: "invalid_characters",
message: `layer ${v.id}: code point ${invalid.position} is a ${invalid.reason}`,
extra: { layerId: v.id, position: invalid.position, reason: invalid.reason },
},
};
}
layers.push({ id: v.id, title: v.title, body, enabled: v.enabled });
}
const composed = composeProjection(layers);
if (utf8Bytes(composed) > MAX_COMPOSED_BYTES) {
return { error: { code: "composed_too_large", message: `composed prompt exceeds ${MAX_COMPOSED_BYTES} bytes` } };
}
return { layers };
}
function revisionOf(body: Record<string, unknown>): string | null {
return typeof body.revision === "string" && body.revision.length > 0 ? body.revision : null;
}
/**
* Adopt-shaped size policy, applied wherever a config value is imported as a
* layer. The `owned-malformed` repair branch imports through the same WP1 call
* as `/adopt`, so it must pass the same caps: a route that enforces a limit on
* one path and not the other does not have a limit.
*
* Runs AFTER the read-only preview and BEFORE any write. The value being
* measured lives in config.toml, so it cannot be checked before a read; both
* limits are UTF-8 byte length, and the composed cap measures what
* `composeProjection` will actually produce — the imported layer plus every
* already-enabled custom layer.
*/
function adoptCapFailure(ctx: ManagementContext, decoded: string): Response | null {
if (utf8Bytes(decoded) > MAX_BODY_BYTES) {
return fail(ctx, "body_too_large", 400, `the existing value exceeds ${MAX_BODY_BYTES} bytes`);
}
const existing = readPromptLayers(paths(ctx)).custom;
const composed = composeProjection([
{ id: "adopted", title: "Imported from config.toml", body: decoded, enabled: true },
...existing,
]);
if (utf8Bytes(composed) > MAX_COMPOSED_BYTES) {
return fail(ctx, "composed_too_large", 400, `the composed prompt would exceed ${MAX_COMPOSED_BYTES} bytes`);
}
return null;
}
/**
* Malformed JSON must be a 400, never an empty object. Swallowing a parse error
* into `{}` made a syntactically invalid adopt or repair request return a
* successful PREVIEW, and an invalid custom request return `stale_revision` —
* two answers that describe neither the request nor the file.
*/
async function readBody(ctx: ManagementContext): Promise<Record<string, unknown> | null> {
try {
const parsed: unknown = await readManagementJsonBody(ctx.req);
return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
? parsed as Record<string, unknown>
: null;
} catch (error) {
rethrowManagementBodyTooLarge(error);
return null;
}
}
export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<Response | null> {
const { req, url } = ctx;
if (!url.pathname.startsWith("/api/codex-prompt")) return null;
// Every mutating verb on this surface requires a MINTED GUI SESSION, not merely a
// request that passed the auth gate. The gate accepts the raw admin token before
// it consults the session table (management-auth.ts:462), and this endpoint writes
// the user's `$CODEX_HOME/config.toml` — the file that decides what the model
// reads. A token any local process can read off disk is the wrong credential for
// rewriting a prompt.
//
// Same principal check and the same honest limit as the star endpoint
// (sidebar-routes.ts:42): a process running as the user can mint its own session
// from the loopback dashboard bootstrap, and can edit config.toml directly without
// this proxy at all. So this is not a technical barrier against a determined local
// agent. What it removes is the CASUAL path — an agent that would have PUT here
// because the endpoint existed and the token was lying in `~/.opencodex` — and it
// makes the refusal legible instead of silent. The real boundary is normative and
// lives in AGENTS.md.
//
// Reads stay open to the admin token: describing the prompt stack changes nothing,
// and the dashboard's own cold load needs it.
if (req.method !== "GET" && req.method !== "HEAD" && !hasHumanDashboardSession(ctx)) {
return fail(
ctx,
"dashboard_session_required",
403,
"prompt layers are written from the dashboard; an admin token alone cannot rewrite config.toml",
);
}
if (url.pathname === "/api/codex-prompt" && req.method === "GET") {
// Pure read. A GET must never repair drift — it is reported here and
// resolved only by an explicit, revision-checked POST.
const snapshot = readPromptLayers(paths(ctx));
return jsonResponse(serialize(snapshot, configBytesOf(snapshot)), 200, req, ctx.config);
}
if (url.pathname === "/api/codex-prompt/text" && req.method === "GET") {
// The dialog used to claim Codex does not expose layer text. It does:
// `codex debug prompt-input` renders the model-visible input list, and this
// reads it. Bounded and fail-soft - an unavailable probe degrades to "we could
// not read it", never to an error page.
// No caller-supplied directory: the probe reads CODEX_HOME and nothing else.
// A `cwd` parameter would have let any authenticated request read an arbitrary
// folder's AGENTS.md through this endpoint.
const { probePromptText } = await import("../../codex/prompt-text-probe");
// A write can complete while an older probe is still running. Admission uses
// a prompt-state fingerprint rather than the transaction revision: editing
// the selected base variant changes its separate .md file without moving the
// optimistic-concurrency revision.
const promptStateFingerprint = computePromptProbeStateFingerprint(paths(ctx));
return jsonResponse(await probePromptText(15_000, req.signal, promptStateFingerprint), 200, req, ctx.config);
}
if (url.pathname === "/api/codex-prompt/toggle" && req.method === "PUT") {
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
const id = body.id;
if (typeof id !== "string") return fail(ctx, "invalid_body", 400, "id must be a string");
// `null` is the restore-the-default verb: it deletes the line instead of
// writing the documented default back as a literal, so a later upstream
// change to the default still reaches this file.
if (typeof body.enabled !== "boolean" && body.enabled !== null) {
return fail(ctx, "invalid_body", 400, "enabled must be a boolean or null");
}
const revision = revisionOf(body);
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
// Derived from the inventory, not a hand-maintained deny-list: classes base,
// feature-gated, runtime-conditional and extension-unknown are all covered by
// one rule, and a new upstream layer is protected the day WP1 lists it. The
// check must precede setToggle, which collapses every non-toggle id into
// unknown_layer.
const descriptor = LAYER_INVENTORY.find(d => d.id === id);
if (!descriptor) return fail(ctx, "unknown_layer", 400, `no layer ${id}`);
if (descriptor.class !== "config-toggle") {
return fail(ctx, "layer_not_toggleable", 409, `${id} is ${descriptor.class} and has no switch`, {
layerClass: descriptor.class,
});
}
return settle(ctx, setToggle(id, body.enabled, revision, paths(ctx)));
}
if (url.pathname === "/api/codex-prompt/custom" && req.method === "PUT") {
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
const revision = revisionOf(body);
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
const validated = validateLayers(body.layers);
if ("error" in validated) {
const status = validated.error.code === "invalid_characters" ? 400 : 400;
return fail(ctx, validated.error.code, status, validated.error.message, validated.error.extra);
}
return settle(ctx, writeCustomLayers(validated.layers, revision, paths(ctx)));
}
if (url.pathname === "/api/codex-prompt/base/select" && req.method === "PUT") {
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
const revision = revisionOf(body);
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
const kind = body.kind;
// `external` is a state we REPORT, never one a caller may ask for: selecting it
// would mean writing a path we do not own.
if (kind !== "default" && kind !== "variant") {
return fail(ctx, "invalid_body", 400, 'kind must be "default" or "variant"');
}
let selection: BaseSelection;
if (kind === "default") {
selection = { kind: "default" };
} else {
if (typeof body.id !== "string") return fail(ctx, "invalid_body", 400, "id must be a string");
selection = { kind: "variant", id: body.id };
}
return settle(ctx, selectBaseVariant(selection, revision, paths(ctx)));
}
if (url.pathname === "/api/codex-prompt/base/import" && req.method === "POST") {
// The adopt flow for `model_instructions_file`: preview first, write only on
// confirmation. The verb exists because /base/select refuses the `external`
// state by design — that refusal is about SILENT retargeting, and an
// explicit, previewed import is precisely the opt-in it protects.
//
// The preview carries the SERIALIZED variant file — `# {title}\n{body}` —
// not just the body: the heading is part of what Codex will read, so the
// thing confirmed must be the whole stored text, title included. Both byte
// counts are reported and separately named: `bodyBytes` is the budget the
// 64 KiB cap applies to, `serializedBytes` is the complete file.
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
const readState = readPromptLayers(paths(ctx));
if (!readState.readable) {
return fail(ctx, "config_unreadable", 409, "the configuration file exists but could not be read", { path: readState.configPath });
}
// The title is validated before anything is previewed or written: a caller
// that supplies one gets the same contract as a custom-layer title —
// 1-80 characters on a single line.
if (body.title !== undefined) {
const t = body.title;
if (typeof t !== "string" || t.trim().length === 0
|| t.length > MAX_TITLE_CHARS || /[\r\n]/.test(t)) {
return fail(ctx, "invalid_title", 400, "title must be 1-80 characters on a single line");
}
}
const preview = previewBaseImport(paths(ctx), typeof body.title === "string" ? body.title : undefined);
if (preview.reason === "nothing_to_import") {
return fail(ctx, "nothing_to_import", 409,
"model_instructions_file is absent or already points at a managed variant");
}
if (preview.reason === "unsupported_form") {
return fail(ctx, "import_unsupported_form", 409, preview.detail, {
path: preview.rawPath,
});
}
if (preview.reason === "file_unreadable") {
return fail(ctx, "import_file_unreadable", 409, preview.detail, {
path: preview.resolvedPath ?? preview.rawPath,
});
}
if (preview.reason === "invalid_characters") {
return fail(ctx, "invalid_characters", 400, preview.detail, { path: preview.resolvedPath });
}
// Same boundary as every other write to this key: the 64 KiB cap applies to
// the BODY alone — the title heading lives outside that budget, unchanged
// from the managed-variant contract.
if (preview.reason === "body_too_large" || utf8Bytes(preview.body!) > MAX_BODY_BYTES) {
return fail(ctx, "body_too_large", 400, `the file body exceeds ${MAX_BODY_BYTES} bytes`, {
path: preview.resolvedPath,
});
}
if (preview.reason === "slots_full") {
return fail(ctx, "variant_slots_full", 409,
`at most ${MAX_BASE_VARIANTS} base variants; delete one first`, {
maxBaseVariants: MAX_BASE_VARIANTS,
serialized: preview.serialized,
resolvedPath: preview.resolvedPath,
});
}
if (body.confirm !== true) {
// Preview writes nothing, by construction: previewBaseImport is a pure read.
return jsonResponse({
ok: true,
changed: false,
preview: {
rawPath: preview.rawPath,
resolvedPath: preview.resolvedPath,
serialized: preview.serialized,
serializedBytes: utf8Bytes(preview.serialized!),
bodyBytes: utf8Bytes(preview.body!),
suggestedTitle: preview.suggestedTitle,
effectiveTitle: preview.effectiveTitle,
previewSha256: preview.previewSha256,
},
}, 200, req, ctx.config);
}
const revision = revisionOf(body);
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
// The preview hash is REQUIRED — a confirm that does not name exactly what
// was previewed (serialized text, title included) cannot be checked against
// it and is refused without writing.
const previewSha256 = body.previewSha256;
if (typeof previewSha256 !== "string" || !/^[0-9a-f]{64}$/.test(previewSha256)) {
return fail(ctx, "import_preview_required", 400,
"confirm requires the previewSha256 returned by a preview of the same title");
}
if (previewSha256 !== preview.previewSha256) {
// The file or the selected title moved between preview and confirm. Refuse
// rather than import a serialization nobody previewed.
return fail(ctx, "import_body_changed", 409,
"the preview no longer matches; preview it again", {
resolvedPath: preview.resolvedPath,
});
}
return settle(ctx, importBaseVariant(
{ title: typeof body.title === "string" ? body.title : undefined, previewSha256 },
revision,
paths(ctx),
));
}
if (url.pathname === "/api/codex-prompt/base" && req.method === "PUT") {
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
const revision = revisionOf(body);
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
// A null id CREATES; a string id edits. `default` is not an id, and the writer
// rejects it independently - this check only makes the refusal legible.
const id = body.id === null || body.id === undefined ? null : body.id;
if (id !== null && typeof id !== "string") return fail(ctx, "invalid_body", 400, "id must be a string or null");
if (id === "default") return fail(ctx, "unknown_layer", 400, "the default variant has no stored body");
if (body.delete === true) {
if (typeof id !== "string") return fail(ctx, "invalid_body", 400, "delete requires an id");
return settle(ctx, writeBaseVariant({ id, delete: true }, revision, paths(ctx)));
}
if (typeof body.title !== "string") return fail(ctx, "invalid_body", 400, "title must be a string");
if (typeof body.body !== "string") return fail(ctx, "invalid_body", 400, "body must be a string");
const normalized = normalizeBody(body.body);
if (utf8Bytes(normalized) > MAX_BODY_BYTES) {
return fail(ctx, "body_too_large", 400, `base variant exceeds ${MAX_BODY_BYTES} bytes`);
}
return settle(ctx, writeBaseVariant({ id, title: body.title, body: normalized }, revision, paths(ctx)));
}
if (url.pathname === "/api/codex-prompt/adopt" && req.method === "POST") {
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
// An unreadable file must say so. Both adopt and repair inspect read-derived
// state before ever reaching WP1's own `config_unreadable`, so without this
// the user was told "nothing to adopt" about a file we could not open.
const readState = readPromptLayers(paths(ctx));
if (!readState.readable) {
return fail(ctx, "config_unreadable", 409, "the configuration file exists but could not be read", {
path: readState.configPath,
});
}
const preview = previewAdopt(paths(ctx));
if (preview.reason === "nothing_to_adopt") {
return fail(ctx, "nothing_to_adopt", 409, "developer_instructions is absent or already owned", {
path: preview.path,
});
}
if (preview.reason === "unsupported_form") {
// Translated here because adoptDeveloperInstructions collapses this into
// developer_instructions_not_owned, which would tell the user nothing about
// where their text is or why it cannot be imported.
return fail(ctx, "adopt_unsupported_form", 409, preview.detail, {
path: preview.path,
line: preview.line,
rawLine: preview.rawLine,
});
}
if (preview.reason === "invalid_characters") {
return fail(ctx, "invalid_characters", 400, preview.detail, { path: preview.path, line: preview.line });
}
const capFailure = adoptCapFailure(ctx, preview.decodedBody ?? "");
if (capFailure) return capFailure;
if (body.confirm !== true) {
// Preview writes nothing, by construction: previewAdopt is a pure read.
return jsonResponse({
ok: true,
changed: false,
preview: {
rawLine: preview.rawLine,
decodedBody: preview.decodedBody,
path: preview.path,
line: preview.line,
},
}, 200, req, ctx.config);
}
const revision = revisionOf(body);
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
return settle(ctx, adoptDeveloperInstructions(revision, paths(ctx)));
}
if (url.pathname === "/api/codex-prompt/repair" && req.method === "POST") {
const body = await readBody(ctx);
if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
const snapshot = readPromptLayers(paths(ctx));
const drift = snapshot.drift;
if (!snapshot.readable) {
return fail(ctx, "config_unreadable", 409, "the configuration file exists but could not be read", {
path: snapshot.configPath,
});
}
if (drift === null) return fail(ctx, "nothing_to_repair", 409, "no drift is present");
const confirm = body.confirm === true;
const revision = revisionOf(body);
if (drift === "projection-stale") {
if (!confirm) {
return jsonResponse({
ok: true,
changed: false,
preview: { drift, projection: composeProjection(snapshot.custom) },
}, 200, req, ctx.config);
}
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
return settle(ctx, writeCustomLayers(snapshot.custom, revision, paths(ctx)));
}
if (drift === "store-missing") {
const preview = previewSalvage(paths(ctx));
if (preview.reason !== "ok") {
return fail(ctx, "nothing_to_repair", 409, "no live projection to salvage");
}
if (!confirm) {
// backupDir, not a filename: a read-only preview must not reserve one.
return jsonResponse({
ok: true,
changed: false,
preview: {
drift,
body: preview.body,
backupDir: preview.backupDir,
unrecoverable: preview.unrecoverable,
},
}, 200, req, ctx.config);
}
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
// Pre-check the revision against the snapshot we just read.
// `salvageProjection` writes its durable backup BEFORE entering the
// transaction that validates the revision (prompt-layers.ts:942-955), so a
// stale tab would otherwise leave an orphan .salvage-*.txt behind on a
// request that changes nothing. This closes the ordinary path; the narrow
// race between this check and WP1's own is documented in devlog 021 §8.1
// and is deliberately NOT fixed by reaching into WP1's write path.
if (revision !== snapshot.revision) {
return fail(ctx, "stale_revision", 409, "the configuration moved since it was read");
}
return settle(ctx, salvageProjection(revision, paths(ctx)));
}
if (drift === "owned-malformed") {
const mode = body.mode;
// Whitelist, not a single-value denial: an arbitrary or missing mode used to
// fall through to adopt, so a client that sent `mode: "reset"` mutated the
// file through a verb the contract never offered.
if (mode !== undefined && mode !== "adopt" && mode !== "replace") {
return fail(ctx, "invalid_body", 400, "mode must be \"adopt\" or \"replace\"", { drift });
}
if (mode === "replace") {
// No WP1 export performs this. Writing one here would put a second write
// path beside the journal transaction, in the one place in this unit where
// a bug destroys a user's configuration.
return fail(ctx, "repair_unsupported", 409,
"replacing a reshaped developer_instructions is not supported from this route; edit the line by hand or adopt it", {
drift, path: snapshot.configPath,
});
}
const preview = previewAdopt(paths(ctx));
if (preview.reason === "unsupported_form") {
return fail(ctx, "adopt_unsupported_form", 409, preview.detail, {
drift, path: preview.path, line: preview.line, rawLine: preview.rawLine,
});
}
if (preview.reason !== "ok") {
return fail(ctx, "nothing_to_repair", 409, "nothing to adopt", { drift });
}
if (!confirm) {
return jsonResponse({
ok: true,
changed: false,
preview: { drift, rawLine: preview.rawLine, decodedBody: preview.decodedBody, line: preview.line },
}, 200, req, ctx.config);
}
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
// Same import, same caps. This branch reaches adoptDeveloperInstructions
// exactly as /adopt does, so skipping the size policy here would mean the
// policy is bypassable by choosing the other endpoint. Proven by driving
// the "BOTH import paths" test red with this call deleted.
const capFailure = adoptCapFailure(ctx, preview.decodedBody ?? "");
if (capFailure) return capFailure;
return settle(ctx, adoptDeveloperInstructions(revision, paths(ctx)));
}
if (drift === "journal-present") {
// Recovery as its own locked operation — never a disguised layers write.
// The GUI used to replay recovery through a byte-identical custom PUT,
// which projected custom=[] over a config still carrying instructions
// whenever the store file was missing.
if (!confirm) {
return jsonResponse({
ok: true,
changed: false,
preview: { drift, storePath: snapshot.storePath },
}, 200, req, ctx.config);
}
if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
if (revision !== snapshot.revision) {
return fail(ctx, "stale_revision", 409, "the configuration moved since it was read");
}
return settle(ctx, recoverPromptJournal(paths(ctx)));
}
// A drift kind this build does not repair: name it rather than guess.
return fail(ctx, "repair_unsupported", 409,
"this drift has no repair on this route", {
drift, storePath: snapshot.storePath,
});
}
return null;
}