@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
1,010 lines (956 loc) • 42.4 kB
text/typescript
/**
* Management routes for the client-integration toggle.
*
* This module is an HTTP adapter and nothing more: every policy decision —
* what counts as ownership, when a mutation is refused, what gets journaled —
* belongs to src/integrations/writer.ts. Duplicating any of it here is how the
* API and the writer would start disagreeing about what happened to a file.
*
* Design of record: devlog/_fin/260802_client_toggle_api/040_wp4_management_api.md.
*/
import { readFileSync } from "node:fs";
import { saveConfigPreservingClaudeCode } from "../../config";
import { listAsideProfileStates, type AsideProfilesInput } from "../../integrations/aside-profiles";
import {
handleAsideProfileRoutes, asideJournalResponse, asideRestoreResponse,
asideJournalDeleteResponse, type AsideProfileRouteOptions,
} from "./aside-profile-routes";
import type { IntegrationIO } from "../../integrations/config-io";
import { createClineIO } from "../../integrations/cline-io";
import { matchesOperationResult } from "../../integrations/journal";
import {
INTEGRATION_CLIENT_IDS,
isIntegrationClientId,
type IntegrationClientId,
} from "../../integrations/registry";
import { detectRaycast, type RaycastInstall } from "../../integrations/raycast-detect";
import { readIntegrationState } from "../../integrations/state";
import { createIntegrationStateStore, type IntegrationStateStore } from "../../integrations/store";
import {
applyIntegrationCoordinated,
disableIntegrationCoordinated,
overwriteIntegrationCoordinated,
restoreIntegrationCoordinated,
type CoordinatedIntegrationOptions,
type IntegrationRestoreInput,
type IntegrationWriteInput,
type WriteRefused,
} from "../../integrations/writer";
import { IntegrationWriterLockBusyError, type IntegrationWriterLockSeams } from "../../integrations/writer-lock";
import {
INTEGRATION_MUTATION_TERMINAL_MS,
IntegrationMutationBusyError,
runIntegrationMutationFlight,
setIntegrationMutationFlightTestHook,
} from "../../integrations/mutation-flight";
import { jsonResponse } from "../auth-cors";
import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
import type { ManagementContext } from "./context";
import { exportSnapshotIdentity, loadExportModels, previewExportSnapshot } from "./model-rows";
import {
previewIntegration,
type IntegrationMutationPlan,
type IntegrationPlanOperation,
type PreviewRequest,
} from "../../integrations/mutation-plan";
const INTEGRATION_ROUTE_PREFIX = "/api/client-integrations/";
const INTEGRATION_COLLECTION_PATH = "/api/client-integrations";
const INTEGRATION_HISTORY_PATHS = ["/api/client-integrations/journal", "/api/client-integrations/restore"];
export { INTEGRATION_MUTATION_TERMINAL_MS };
type IntegrationStateRecord = Awaited<ReturnType<typeof readIntegrationState>>;
type ApplyResult = Awaited<ReturnType<typeof applyIntegrationCoordinated>>;
type DisableResult = Awaited<ReturnType<typeof disableIntegrationCoordinated>>;
type RestoreResult = Awaited<ReturnType<typeof restoreIntegrationCoordinated>>;
export type IntegrationStateEnvelope = {
clientId: IntegrationClientId;
/**
* Raycast only, and only on the single-client read. Custom Providers is a
* Pro feature, so a file that is `current` can still be one Raycast ignores;
* this is the fact that lets status and the GUI say so. It is not part of
* the shared `IntegrationStatus`, which describes the file, not the app.
*/
raycast?: RaycastInstall;
} & IntegrationStateRecord;
export interface IntegrationStateListEnvelope {
clients: IntegrationStateEnvelope[];
}
export type IntegrationToggleEnvelope =
| ({ clientId: IntegrationClientId } & ApplyResult)
| ({ clientId: IntegrationClientId } & DisableResult);
export type IntegrationRestoreEnvelope = {
clientId: IntegrationClientId;
} & RestoreResult;
export interface IntegrationJournalEnvelope {
operations: IntegrationJournalRow[];
}
export interface IntegrationJournalRow {
opId: string;
clientId: IntegrationClientId;
kind: "apply" | "disable" | "refresh" | "restore" | "overwrite";
at: string;
configPath: string;
snapshot: "none" | "stored" | "expired";
undoable: boolean;
/**
* May the operator retire this row?
*
* Computed HERE, not in the GUI, because the DELETE route enforces the same
* rule and two copies of it would drift. False for a client newest row: it
* is the undo entry point (`undoable` above keys off exactly this), and it
* is what a user reaches for right after the mistake.
*/
deletable: boolean;
profileId?: number;
}
export interface IntegrationToggleBody {
enabled: boolean;
/**
* Opt in to replacing a conflicted block with the one opencodex would write.
*
* Absent and `false` behave identically and are the only states a caller
* reaches by accident, which is the point: the conflict refusal protects work
* we did not author, so it can only be waived by asking for it by name.
*/
overwriteConflict?: boolean;
}
export interface IntegrationRestoreBody {
opId: string;
confirmDrift?: boolean;
}
let integrationMutationTestHooks: {
io?: IntegrationIO;
lockSeams?: IntegrationWriterLockSeams;
/**
* Bind every read and write in the request to one store. Without this a
* route test could isolate the writer but not the journal listing or the
* restore preflight (A-gate round 12).
*/
store?: IntegrationStateStore;
run?: (operation: () => Promise<unknown>) => Promise<unknown>;
} | null = null;
/**
* Home and environment overrides for tests.
*
* Bun's `os.homedir()` snapshots the real home at startup and ignores a later
* `process.env.HOME` assignment, so a test that only rewrites `HOME` still
* resolves the DEVELOPER'S client configs — which is exactly how a route test
* wrote a real `~/.hermes/config.yaml` during this work package. The writer
* and the state reader both already take `env`/`home` explicitly; the route
* simply had no way to pass them. It does now, and production leaves it unset.
*/
let integrationPathTestHooks: { env?: NodeJS.ProcessEnv; home?: string } | null = null;
export function setIntegrationPathTestHooks(hooks: { env?: NodeJS.ProcessEnv; home?: string } | null): void {
integrationPathTestHooks = hooks;
}
/**
* Raycast detection override for tests. The real detector spawns `defaults` and
* reads the developer's own subscription state, which is exactly the kind of
* host fact a route test must not depend on.
*/
let raycastDetectTestHook: (() => RaycastInstall) | null = null;
export function setRaycastDetectTestHook(hook: (() => RaycastInstall) | null): void {
raycastDetectTestHook = hook;
}
/** The `env`/`home` overrides, spread into every registry-resolving call. */
function pathOverrides(): { env?: NodeJS.ProcessEnv; home?: string } {
return {
...(integrationPathTestHooks?.env ? { env: integrationPathTestHooks.env } : {}),
...(integrationPathTestHooks?.home ? { home: integrationPathTestHooks.home } : {}),
};
}
function isPlainRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function decodeClientPath(pathname: string): string | null {
if (!pathname.startsWith(INTEGRATION_ROUTE_PREFIX)) return null;
const encoded = pathname.slice(INTEGRATION_ROUTE_PREFIX.length);
if (!encoded || encoded.includes("/")) return null;
try {
return decodeURIComponent(encoded);
} catch {
return encoded;
}
}
export function setIntegrationMutationFlightTestHooks(
hooks: {
io?: IntegrationIO;
lockSeams?: IntegrationWriterLockSeams;
/** Binds the WHOLE request — reads, writes and journal — to one store. */
store?: IntegrationStateStore;
run?: (operation: () => Promise<unknown>) => Promise<unknown>;
} | null,
): void {
integrationMutationTestHooks = hooks;
setIntegrationMutationFlightTestHook(hooks?.run ?? null);
// Path overrides are part of the same isolation contract: clearing flights
// while leaving a temp home bound would let the next suite write real files.
if (hooks === null) {
integrationPathTestHooks = null;
raycastDetectTestHook = null;
}
}
/**
* ONE store per request, used by every read and every write in that request.
* The route previously called module-level `listOperations`/`readSnapshot`
* while handing the writer a separate default store, so a test could not bind
* the whole operation to a temp root (A-gate round 12).
*/
function integrationStore(): IntegrationStateStore {
return integrationMutationTestHooks?.store ?? createIntegrationStateStore();
}
function asideOptions(ctx: ManagementContext): AsideProfileRouteOptions {
let input: AsideProfilesInput | undefined;
return {
input: () => input ??= {
config: ctx.config,
port: Number(ctx.url.port) || ctx.config.port,
models: () => loadExportModels(ctx.config),
store: integrationStore(),
...pathOverrides(),
io: integrationMutationTestHooks?.io,
lockSeams: integrationMutationTestHooks?.lockSeams,
persistConfig: ctx.deps.saveConfigPreservingClaudeCode ?? saveConfigPreservingClaudeCode,
},
failure: result => writerFailureResponse("aside", result, ctx),
};
}
async function buildIntegrationWriteInput(
clientId: IntegrationClientId,
ctx: ManagementContext,
store: IntegrationStateStore,
): Promise<IntegrationWriteInput> {
return {
clientId,
models: await loadExportModels(ctx.config),
config: ctx.config,
port: Number(ctx.url.port) || ctx.config.port,
store,
io: integrationMutationTestHooks?.io,
...pathOverrides(),
};
}
/**
* The same input a mutation would build, from the read-only roster.
*
* It differs from the mutation's in exactly one way, and the difference is deliberate: the roster
* comes from `previewExportModels`, which gathers without running the initial-selection finalizer
* that persists configuration. Everything else is shared, so a preview and the commit that follows
* it cannot disagree for any reason except the state genuinely moving.
*/
async function buildIntegrationPreviewInput(
clientId: IntegrationClientId,
ctx: ManagementContext,
store: IntegrationStateStore,
): Promise<{ input: IntegrationWriteInput; identity: string } | null> {
const snapshot = previewExportSnapshot(ctx.config);
// No cached roster means no honest snapshot to plan against. Gathering one here would make a
// read refresh credentials and write the provider cache, which is the thing preview must not do.
if (snapshot === null) return null;
return {
identity: snapshot.identity,
input: {
clientId,
models: snapshot.models,
config: ctx.config,
port: Number(ctx.url.port) || ctx.config.port,
store,
io: integrationMutationTestHooks?.io,
...pathOverrides(),
},
};
}
/**
* The file's current bytes, or `null` when it is missing.
*
* `null` is NOT the same as `""`: an absent file and an empty one are
* different states, and collapsing them is what made this route disagree with
* the writer about whether an absence-result operation had drifted.
* `undefined` means we could not read it at all, which is neither.
*/
function currentConfigText(configPath: string): string | null | undefined {
try {
return readFileSync(configPath, "utf8");
} catch (error) {
if (isPlainRecord(error) && error.code === "ENOENT") return null;
return undefined;
}
}
function invalidClientResponse(ctx: ManagementContext): Response {
return jsonResponse({
error: "invalid integration client",
code: "invalid_integration_client",
validClients: INTEGRATION_CLIENT_IDS,
}, 400, ctx.req, ctx.config);
}
/**
* No cached model roster, so there is nothing honest to plan against.
*
* Answered as a bounded refusal rather than by gathering one: discovery refreshes credentials and
* writes the provider cache, and a preview that did either would be a write wearing a read's name.
* The caller opens the models view or performs the mutation directly.
*/
function previewUnavailableResponse(ctx: ManagementContext): Response {
return jsonResponse({
error: "no model roster is cached yet, so this change cannot be planned",
code: "integration_preview_unavailable",
}, 409, ctx.req, ctx.config);
}
/**
* A confirmed plan, or a reason the request cannot carry one.
*
* Both fields or neither. A half-bound request is rejected rather than quietly treated as
* unbound, because dropping one half would answer 200 to a caller who believed their
* confirmation was being checked.
*/
function planBindingOf(
body: Record<string, unknown>,
): { operation: IntegrationPlanOperation; fingerprint: string } | "none" | "half" | "unknown-operation" {
const { operation, planFingerprint } = body;
if (operation === undefined && planFingerprint === undefined) return "none";
if (operation === undefined || typeof planFingerprint !== "string" || planFingerprint.length === 0) return "half";
if (operation !== "apply" && operation !== "overwrite" && operation !== "disable" && operation !== "restore") {
return "unknown-operation";
}
return { operation, fingerprint: planFingerprint };
}
function halfBoundResponse(ctx: ManagementContext): Response {
return jsonResponse({
error: "operation and planFingerprint must be sent together",
code: "invalid_preview_binding",
}, 400, ctx.req, ctx.config);
}
/**
* Re-plan and compare before the mutation runs.
*
* The fingerprint is an optimistic token, never authorization: management authentication and
* every ownership rule still apply. What it adds is that a confirmation stops meaning anything
* the moment the state it described moved, and the refusal carries a fresh plan so the operator
* decides again against what is true now.
*/
function stalePlanGuard(
clientId: IntegrationClientId,
ctx: ManagementContext,
store: IntegrationStateStore,
request: PreviewRequest,
fingerprint: string,
capturedIdentity: string | null,
): {
revalidate: NonNullable<CoordinatedIntegrationOptions["revalidate"]>;
response: () => Response | null;
} {
let stale: IntegrationMutationPlan | "unavailable" | null = null;
return {
revalidate: async frozen => {
/*
* Plan the coordinator's OWN frozen input, never a freshly built one. Rebuilding here let
* the check validate against one roster while the mutation wrote from another, because an
* ordinary load can replace the snapshot at any time and nothing serialises that against
* this lock. The captured identity is verified separately, so a replacement is detected
* without ever swapping the roster this mutation is about to use.
*/
if (exportSnapshotIdentity(ctx.config) !== capturedIdentity) {
const refreshed = await buildIntegrationPreviewInput(clientId, ctx, store);
stale = refreshed === null ? "unavailable" : previewIntegration(refreshed.input, request);
return { ok: false, reason: "conflict", state: "conflict", clientId, message: "the model roster changed while confirming" };
}
const plan = previewIntegration(frozen, request);
if (plan.canApply && plan.fingerprint === fingerprint) return null;
stale = plan;
return { ok: false, reason: "conflict", state: plan.state, clientId, message: "that confirmation no longer describes this file" };
},
response: () => {
if (stale === null) return null;
if (stale === "unavailable") return previewUnavailableResponse(ctx);
return jsonResponse({
error: "integration preview is stale",
code: "integration_preview_stale",
plan: stale,
}, 409, ctx.req, ctx.config);
},
};
}
function internalErrorResponse(error: unknown, ctx: ManagementContext): Response {
return jsonResponse({
error: error instanceof Error ? error.message : String(error),
code: "integration_internal_error",
}, 500, ctx.req, ctx.config);
}
async function readJsonBody(ctx: ManagementContext): Promise<unknown | Response> {
try {
return await readManagementJsonBody(ctx.req);
} catch (error) {
rethrowManagementBodyTooLarge(error);
return jsonResponse({
error: "invalid JSON body",
code: "invalid_json_body",
}, 400, ctx.req, ctx.config);
}
}
function writerFailureResponse(
clientId: IntegrationClientId,
/*
* The writer's own refusal type, not a structural echo of it.
*
* A local shape with an optional `message` accepted a refusal that had lost
* its message on the way here, which is exactly how the drift branch shipped
* without one. `WriteRefused` requires it, so the compiler now objects.
*/
result: WriteRefused,
ctx: ManagementContext,
): Response {
/*
* Routed by `reason`, never by `state` (006 §5). A `write_failed` that
* happens to occur while the file is in a `conflict` state is still a write
* failure, and mapping on state first silently dropped its message,
* snapshotPath, and residual — the recovery information the flag exists to
* carry (A-gate round 5, blocker 3).
*/
const recovery = {
message: result.message,
...(result.snapshotPath ? { snapshotPath: result.snapshotPath } : {}),
...(result.residual ? { residual: true } : {}),
};
if (result.reason === "unsafe") {
return jsonResponse({
error: "integration config is unsafe",
code: "integration_unsafe",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 409, ctx.req, ctx.config);
}
if (result.reason === "conflict") {
return jsonResponse({
error: "integration config conflicts with ownership record",
code: "integration_conflict",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 409, ctx.req, ctx.config);
}
if (result.reason === "drift_requires_confirm") {
return jsonResponse({
error: "restore requires drift confirmation",
code: "integration_drift_confirmation_required",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 409, ctx.req, ctx.config);
}
if (result.reason === "snapshot_expired") {
return jsonResponse({
error: "integration snapshot expired",
code: "integration_snapshot_expired",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 410, ctx.req, ctx.config);
}
// not_installed, non_loopback, write_failed — always carry recovery fields.
return jsonResponse({
error: "integration mutation failed",
code: "integration_mutation_failed",
clientId, state: result.state, reason: result.reason, ...recovery,
}, 500, ctx.req, ctx.config);
}
/**
* Who asked for this deletion, as an audit value that is safe to persist.
*
* The tombstone lives in an append-only log the user can read, so this must be
* a principal NAME and nothing else -- never the admin token, a session id, or
* a filesystem path. `principal` is undefined only in direct-dispatch tests,
* which the auth gate documents as the untrusted admin-token case.
*/
function journalDeletePrincipal(ctx: ManagementContext): string {
return ctx.principal ?? "admin-token";
}
/**
* Retire one journal row at the operator request.
*
* The opId travels in the QUERY STRING, matching DELETE
* /api/codex-auth/accounts?id= -- the repository other DELETE-by-identifier. A
* body on DELETE is legal but unevenly handled by intermediaries, and there is
* nothing here a query cannot carry.
*/
async function handleJournalDelete(ctx: ManagementContext): Promise<Response> {
const { req, url } = ctx;
const opId = url.searchParams.get("opId")?.trim();
if (!opId) {
return jsonResponse({
error: "opId must be a non-empty string",
code: "invalid_op_id",
}, 400, req, ctx.config);
}
const aside = await asideJournalDeleteResponse(ctx, opId, asideOptions(ctx));
if (aside) return aside;
try {
const store = integrationStore();
const operation = store.findOperation(opId);
if (!operation) {
// Already retired, or never existed. Both are 404: the tombstone hides
// the row from findOperation, so a double-click is idempotent here
// rather than a second deletion of something.
return jsonResponse({
error: "integration operation not found",
code: "integration_operation_not_found",
opId,
}, 404, req, ctx.config);
}
/*
* The newest row per client is refused, and refused by the SERVER even
* though the GUI already hides its button. The button is a courtesy; this
* is the rule. An admin-token caller has no GUI at all.
*
* Re-read immediately before the write: a restore that landed while the
* dialog was open appends a new row and changes which opId is newest.
*/
const newest = store.listOperations(operation.clientId, 1)[0];
if (newest?.opId === opId) {
return jsonResponse({
error: "the newest operation for a client cannot be deleted",
code: "integration_journal_newest_protected",
clientId: operation.clientId,
opId,
}, 409, req, ctx.config);
}
store.retireOperation({
tombstone: opId,
at: new Date().toISOString(),
by: journalDeletePrincipal(ctx),
});
/*
* Snapshot bytes go too, and go AFTER the tombstone -- the same post-commit
* ordering appendOperation uses (journal.ts rule 1). If this fails, the row
* is still retired and retentionDegraded discloses the leftover file; the
* reverse order would delete a user backup for a deletion that then failed
* to record.
*/
const pruned = store.pruneSnapshots(operation.clientId);
if (pruned.ok) store.clearPruneFailure(operation.clientId);
else store.markPruneFailure(operation.clientId, pruned.error);
return jsonResponse({
ok: true,
opId,
clientId: operation.clientId,
snapshotRemoved: pruned.ok,
}, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
export async function handleIntegrationRoutes(ctx: ManagementContext): Promise<Response | null> {
const { req, url } = ctx;
const profileOptions = asideOptions(ctx);
const aside = await handleAsideProfileRoutes(ctx, profileOptions);
if (aside) return aside;
if (url.searchParams.has("profile")
&& (url.pathname === INTEGRATION_COLLECTION_PATH || url.pathname.startsWith(INTEGRATION_ROUTE_PREFIX))
&& !INTEGRATION_HISTORY_PATHS.includes(url.pathname)) {
return jsonResponse({ error: "profile applies only to Aside", code: "invalid_aside_profile" }, 400, req, ctx.config);
}
if (url.pathname === "/api/client-integrations" && req.method === "GET") {
try {
const models = await loadExportModels(ctx.config);
const port = Number(url.port) || ctx.config.port;
// One store for the whole collection read: without it this route retried
// maintenance and counted snapshots in the default store even when the
// caller had bound everything else to a temp root (A-gate round 13).
const store = integrationStore();
/*
* The envelope carries `clientId`, but it is not restated here: WP2 and
* WP3 both echo `input.clientId` back in their result, and `input`
* IS this route's client. Writing it twice made the compiler pick the
* later one silently — a duplicate that could only ever hide a
* disagreement, never surface it.
*/
const clients = await Promise.all(INTEGRATION_CLIENT_IDS.map(async clientId => {
if (clientId === "aside") {
try { return await listAsideProfileStates({ ...profileOptions.input(), models }); }
catch { /* Existing status projection retains a safe unresolved-path diagnostic. */ }
}
return readIntegrationState({ clientId, models, config: ctx.config, port, store, ...pathOverrides() });
}));
return jsonResponse({ clients } satisfies IntegrationStateListEnvelope, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/journal" && req.method === "DELETE") {
return handleJournalDelete(ctx);
}
if (url.pathname === "/api/client-integrations/journal") {
if (req.method !== "GET") return null;
const requestedClient = url.searchParams.get("client");
if (requestedClient !== null && !isIntegrationClientId(requestedClient)) {
return invalidClientResponse(ctx);
}
const asideJournal = await asideJournalResponse(ctx, requestedClient, profileOptions);
if (asideJournal) return asideJournal;
try {
const store = integrationStore();
const storedOperations = store.listOperations(requestedClient ?? undefined);
const newestByClient = new Map<IntegrationClientId, string>();
for (const operation of storedOperations) {
if (!newestByClient.has(operation.clientId)) {
newestByClient.set(operation.clientId, operation.opId);
}
}
let operations: IntegrationJournalRow[] = storedOperations.map(operation => {
/*
* Resolved against the DISK, not read off the row.
*
* Retention deletes snapshot files and deliberately leaves the row's
* persisted tag saying `stored`, so copying that tag advertised undo
* for bytes that no longer exist — the GUI would offer the button and
* the restore route would answer 410. `readSnapshot` is the same
* resolver that preflight uses, which is what keeps the two agreeing.
*/
const snapshot = store.readSnapshot(operation).kind;
return {
opId: operation.opId,
clientId: operation.clientId,
kind: operation.kind,
at: operation.at,
configPath: operation.configPath,
snapshot,
/*
* The SAME resolution decides `undoable`. Reporting the tag honestly
* and then offering undo anyway is the identical defect one field
* over: restore would answer 410 for a row the GUI drew a button on.
* `none` stays undoable — restoring an op that created a file means
* deleting it, and that needs no snapshot bytes.
*/
/*
* Eligibility goes through the SAME matcher restore uses. This route
* used to represent a missing file as `""` and call that a match,
* while restore hashed `""` into a real digest — so the row was
* offered as Undo and then refused as drift.
*/
undoable: (() => {
if (snapshot === "expired") return false;
if (newestByClient.get(operation.clientId) !== operation.opId) return false;
const current = operation.clientId === "cline" ? (() => {
const io = createClineIO(integrationMutationTestHooks?.io ?? store.io(), operation.configPath, store);
const read = io.readText(operation.configPath);
return read.kind === "text" ? read.text : read.kind === "missing" ? null : undefined;
})() : currentConfigText(operation.configPath);
return current === undefined ? false : matchesOperationResult(operation, current);
})(),
/*
* Deliberately NOT an `undoable` derivative. The two axes are
* independent: an expired row is undoable-false and deletable-true,
* which is the pairing this route exists to produce -- a row whose
* bytes are gone previously carried no action at all.
*/
deletable: newestByClient.get(operation.clientId) !== operation.opId,
};
});
if (requestedClient === null) {
const profiles = await asideJournalResponse(ctx, "aside", profileOptions);
if (profiles?.ok) {
const body = await profiles.json() as IntegrationJournalEnvelope;
operations = [...operations.filter(row => row.clientId !== "aside"), ...body.operations]
.sort((a, b) => b.at.localeCompare(a.at));
}
}
return jsonResponse({ operations } satisfies IntegrationJournalEnvelope, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/preview") {
if (req.method !== "POST") return null;
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (!isPlainRecord(parsed)) {
return jsonResponse({ error: "preview body must be an object", code: "invalid_preview_body" }, 400, req, ctx.config);
}
const previewClient = parsed.clientId;
if (typeof previewClient !== "string"
|| !(INTEGRATION_CLIENT_IDS as readonly string[]).includes(previewClient)) {
return invalidClientResponse(ctx);
}
/*
* Aside is a set of profiles, not one file, and every mutation it has requires a profile. A
* plan built here would describe the legacy single-account location and no bound mutation
* would accept it, so an operator could confirm something nothing can carry out. The canonical
* per-profile preview answers this question properly, and the mutation routes already refuse
* the unscoped spelling the same way.
*/
if (previewClient === "aside") {
return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
}
const operation = parsed.operation;
if (operation !== "apply" && operation !== "overwrite" && operation !== "disable") {
return jsonResponse({
error: "operation must be apply, overwrite or disable",
code: "invalid_preview_operation",
}, 400, req, ctx.config);
}
try {
const captured = await buildIntegrationPreviewInput(previewClient as IntegrationClientId, ctx, integrationStore());
if (!captured) return previewUnavailableResponse(ctx);
return jsonResponse(previewIntegration(captured.input, { operation }), 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/restore/preview") {
if (req.method !== "POST") return null;
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (!isPlainRecord(parsed) || typeof parsed.opId !== "string" || parsed.opId.trim().length === 0) {
return jsonResponse({ error: "opId must be a non-empty string", code: "invalid_op_id" }, 400, req, ctx.config);
}
if (parsed.confirmDrift !== undefined && typeof parsed.confirmDrift !== "boolean") {
return jsonResponse({ error: "confirmDrift must be a boolean", code: "invalid_confirm_drift" }, 400, req, ctx.config);
}
const opId = parsed.opId.trim();
try {
const store = integrationStore();
const operation = store.findOperation(opId);
/*
* Answered as "not found" rather than by reading the row back to the caller. A preview is
* reached before any confirmation, so it is the cheapest place to probe journal contents,
* and it declines to be one.
*/
if (!operation) {
return jsonResponse({
error: "integration operation not found",
code: "integration_operation_not_found",
opId,
}, 404, req, ctx.config);
}
// Same rule, decided after the row is found so an unscoped undo of an Aside operation is
// refused for what it is rather than answered as a missing operation.
if (operation.clientId === "aside") {
return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
}
const captured = await buildIntegrationPreviewInput(operation.clientId, ctx, store);
if (!captured) return previewUnavailableResponse(ctx);
const plan = previewIntegration(captured.input, {
operation: "restore",
opId,
confirmDrift: parsed.confirmDrift ?? false,
});
return jsonResponse(plan, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
if (url.pathname === "/api/client-integrations/restore") {
if (req.method !== "POST") return null;
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (!isPlainRecord(parsed) || typeof parsed.opId !== "string" || parsed.opId.trim().length === 0) {
return jsonResponse({
error: "opId must be a non-empty string",
code: "invalid_op_id",
}, 400, req, ctx.config);
}
if (parsed.confirmDrift !== undefined && typeof parsed.confirmDrift !== "boolean") {
return jsonResponse({
error: "confirmDrift must be a boolean",
code: "invalid_confirm_drift",
}, 400, req, ctx.config);
}
const opId = parsed.opId.trim();
const confirmDrift = parsed.confirmDrift ?? false;
const restoreBinding = planBindingOf(parsed);
if (restoreBinding === "half") return halfBoundResponse(ctx);
if (restoreBinding === "unknown-operation" || (restoreBinding !== "none" && restoreBinding.operation !== "restore")) {
return jsonResponse({
error: "operation does not match the requested change",
code: "invalid_preview_operation",
}, 400, req, ctx.config);
}
// The binding travels with the request. Dropping it here routed a bound Aside restore into
// the unbound path, which executed the mutation while its confirmation went unexamined.
const asideRestore = await asideRestoreResponse(ctx, {
opId,
confirmDrift,
...(parsed.operation === undefined ? {} : { operation: parsed.operation }),
...(parsed.planFingerprint === undefined ? {} : { planFingerprint: parsed.planFingerprint }),
}, profileOptions);
if (asideRestore) return asideRestore;
let restoreClientId: IntegrationClientId | undefined;
try {
const store = integrationStore();
const operation = store.findOperation(opId);
if (!operation) {
return jsonResponse({
error: "integration operation not found",
code: "integration_operation_not_found",
opId,
}, 404, req, ctx.config);
}
restoreClientId = operation.clientId;
const snapshot = store.readSnapshot(operation);
if (snapshot.kind === "expired") {
return jsonResponse({
error: "integration snapshot expired",
code: "integration_snapshot_expired",
opId,
}, 410, req, ctx.config);
}
const boundRestore = restoreBinding === "none"
? null
: await buildIntegrationPreviewInput(operation.clientId, ctx, store);
if (restoreBinding !== "none" && boundRestore === null) return previewUnavailableResponse(ctx);
const writeInput = boundRestore
? boundRestore.input
: await buildIntegrationWriteInput(operation.clientId, ctx, store);
const restoreGuard = restoreBinding === "none" ? null : stalePlanGuard(
operation.clientId,
ctx,
store,
{ operation: "restore", opId, confirmDrift },
restoreBinding.fingerprint,
boundRestore === null ? null : boundRestore.identity,
);
const restoreInput: IntegrationRestoreInput = {
...writeInput,
opId,
confirmDrift,
};
const result = await runIntegrationMutationFlight(
operation.clientId,
`restore:${opId}:${confirmDrift}`,
writeInput.io?.now ?? Date.now,
() => restoreIntegrationCoordinated(restoreInput, {
lockSeams: integrationMutationTestHooks?.lockSeams,
...(restoreGuard ? { revalidate: restoreGuard.revalidate } : {}),
}),
);
const restoreStale = restoreGuard?.response();
if (restoreStale) return restoreStale;
if (!result.ok) {
/*
* Drift is NOT special-cased here.
*
* It used to be, and the hand-written branch dropped the writer's
* `message` — which is the only thing that tells the user WHICH file
* drifted and where its backup went. Every refusal leaves through the
* one serializer, so a refusal cannot lose its recovery fields by
* being routed through a shorter path.
*/
return writerFailureResponse(operation.clientId, result, ctx);
}
return jsonResponse(result satisfies IntegrationRestoreEnvelope, 200, req, ctx.config);
} catch (error) {
if (error instanceof IntegrationMutationBusyError || error instanceof IntegrationWriterLockBusyError) {
return jsonResponse({
error: "integration mutation busy",
code: "integration_mutation_busy",
clientId: restoreClientId ?? (error instanceof IntegrationMutationBusyError ? error.clientId : undefined),
}, 409, req, ctx.config);
}
return internalErrorResponse(error, ctx);
}
}
if (req.method !== "GET" && req.method !== "PUT") return null;
const requestedClient = decodeClientPath(url.pathname);
if (requestedClient === null) return null;
if (!isIntegrationClientId(requestedClient)) return invalidClientResponse(ctx);
// Canonical Aside paths are owned above. Never decode an alternate spelling
// into the legacy single-account writer or bypass profile policy/guards.
if (requestedClient === "aside") {
return jsonResponse({ error: "Use the canonical Aside profile path", code: "invalid_aside_profile_path" }, 400, req, ctx.config);
}
if (req.method === "GET") {
try {
const input = await buildIntegrationWriteInput(requestedClient, ctx, integrationStore());
const state = readIntegrationState(input);
// Detection runs only for the client that needs it: `defaults` is a
// process spawn, and no other client's read should pay for it.
const envelope: IntegrationStateEnvelope = requestedClient === "raycast"
? { ...state, raycast: (raycastDetectTestHook ?? detectRaycast)() }
: state;
return jsonResponse(envelope, 200, req, ctx.config);
} catch (error) {
return internalErrorResponse(error, ctx);
}
}
const parsed = await readJsonBody(ctx);
if (parsed instanceof Response) return parsed;
if (!isPlainRecord(parsed) || typeof parsed.enabled !== "boolean") {
return jsonResponse({
error: "enabled must be a boolean",
code: "invalid_enabled",
}, 400, req, ctx.config);
}
if (parsed.overwriteConflict !== undefined && typeof parsed.overwriteConflict !== "boolean") {
return jsonResponse({
error: "overwriteConflict must be a boolean",
code: "invalid_overwrite_conflict",
}, 400, req, ctx.config);
}
/*
* Rejected rather than ignored. Disabling a block we do not own is precisely
* the deletion this subsystem exists to prevent, so a caller sending this
* combination has misunderstood the field, and silently dropping it would
* answer 200 for a request whose intent we refused.
*/
if (parsed.overwriteConflict === true && parsed.enabled === false) {
return jsonResponse({
error: "overwriteConflict applies only to enabling an integration",
code: "invalid_overwrite_conflict",
}, 400, req, ctx.config);
}
const requestedOperation: IntegrationPlanOperation = parsed.enabled
? (parsed.overwriteConflict === true ? "overwrite" : "apply")
: "disable";
const binding = planBindingOf(parsed);
if (binding === "half") return halfBoundResponse(ctx);
if (binding === "unknown-operation" || (binding !== "none" && binding.operation !== requestedOperation)) {
// A confirmation that names a different operation than the request performs is not a
// confirmation of this request.
return jsonResponse({
error: "operation does not match the requested change",
code: "invalid_preview_operation",
}, 400, req, ctx.config);
}
try {
/*
* A bound request is built from the same passive roster the guard re-plans against, and an
* unbound one keeps its existing refreshing path. Building the refreshing input first would
* have had the mutation and its own confirmation check disagree about the roster by
* construction, which is the disagreement this binding exists to detect.
*/
const boundToggle = binding === "none"
? null
: await buildIntegrationPreviewInput(requestedClient, ctx, integrationStore());
if (binding !== "none" && boundToggle === null) return previewUnavailableResponse(ctx);
const input = boundToggle
? boundToggle.input
: await buildIntegrationWriteInput(requestedClient, ctx, integrationStore());
const guard = binding === "none" ? null : stalePlanGuard(
requestedClient,
ctx,
integrationStore(),
{ operation: binding.operation },
binding.fingerprint,
boundToggle === null ? null : boundToggle.identity,
);
const result = await runIntegrationMutationFlight(
requestedClient,
parsed.enabled ? (parsed.overwriteConflict === true ? "overwrite" : "apply") : "disable",
input.io?.now ?? Date.now,
() => {
const options = {
lockSeams: integrationMutationTestHooks?.lockSeams,
...(guard ? { revalidate: guard.revalidate } : {}),
};
if (!parsed.enabled) return disableIntegrationCoordinated(input, options);
return parsed.overwriteConflict === true
? overwriteIntegrationCoordinated(input, options)
: applyIntegrationCoordinated(input, options);
},
);
const stale = guard?.response();
if (stale) return stale;
if (!result.ok) return writerFailureResponse(requestedClient, result, ctx);
return jsonResponse(result satisfies IntegrationToggleEnvelope, 200, req, ctx.config);
} catch (error) {
if (error instanceof IntegrationMutationBusyError || error instanceof IntegrationWriterLockBusyError) {
return jsonResponse({
error: "integration mutation busy",
code: "integration_mutation_busy",
clientId: requestedClient,
}, 409, req, ctx.config);
}
return internalErrorResponse(error, ctx);
}
}