UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

226 lines (212 loc) • 14.7 kB
/** Preview and explicitly bound mutations use the existing management authority. */ import type { IntegrationMutationPlan, IntegrationPlanOperation } from "../integrations/mutation-plan"; import type { IntegrationClientId } from "../integrations/registry"; import { redactSecretString, redactUserPath } from "../lib/redact"; import { CliUsageError, RuntimeApiError, printData, runtimeRequest, terminalSafeText, type RuntimeApiDeps, } from "./runtime-api"; import { clientIntegrationPath, validateAsideProfile, integrationOption, integrationFlag, integrationFingerprint, integrationDroidDefaults, integrationModelNames, } from "./integration-input"; import { decodeIntegrationPlan, FILE_INTEGRATION_CLIENTS, INTEGRATION_STATES, INTEGRATION_REFUSAL_REASONS } from "./integration-plan-dto"; const USAGE = `Usage: ocx integration client preview --client ID --operation <apply|overwrite|disable> [--profile N] [--json] ocx integration client restore --op ID --preview [--client aside --profile N] [--confirm-drift] [--json] ocx integration client <enable|disable> --client ID [--profile N] [--overwrite-conflict] [--plan-fingerprint TOKEN] [--json] ocx integration client restore --op ID [--client aside --profile N] [--confirm-drift] [--plan-fingerprint TOKEN] [--json] Droid apply/overwrite: [--reasoning-default MODEL=EFFORT ... | --clear-reasoning-defaults] Hermes/Command Code enable and apply/overwrite preview: [--model-names <alias|routed>]`; type Intent = { preview: boolean; json: boolean; client?: string; profile?: string; operation: IntegrationPlanOperation; path: string; body: Record<string, unknown>; }; function parseIntent(argv: string[]): Intent { const args = [...argv]; const action = args.shift(); if (!["preview", "enable", "disable", "restore"].includes(action ?? "")) throw new CliUsageError("Expected preview, enable, disable or restore", USAGE); const json = integrationFlag(args, "--json"); const client = integrationOption(args, "--client"); const profile = integrationOption(args, "--profile"); validateAsideProfile(profile, client, USAGE); if (client !== undefined && !FILE_INTEGRATION_CLIENTS.some(id => id === client)) throw new CliUsageError("Unknown integration client", USAGE); const previewFlag = integrationFlag(args, "--preview"); const token = integrationFingerprint(args); const defaults = integrationDroidDefaults(args); const overwrite = integrationFlag(args, "--overwrite-conflict"); const confirmDrift = integrationFlag(args, "--confirm-drift"); const op = integrationOption(args, "--op"); const opAlias = integrationOption(args, "--op-id"); const selectedOperation = integrationOption(args, "--operation"); if (op !== undefined && opAlias !== undefined) throw new CliUsageError("Use only one of --op and --op-id", USAGE); const opId = op ?? opAlias; if (previewFlag && action !== "restore") throw new CliUsageError("--preview applies only to restore; use the preview command", USAGE); const preview = action === "preview" || previewFlag; if (preview && token !== undefined) throw new CliUsageError("Preview cannot be combined with --plan-fingerprint", USAGE); if (selectedOperation !== undefined && action !== "preview") throw new CliUsageError("--operation applies only to preview", USAGE); if (overwrite && action !== "enable") throw new CliUsageError("--overwrite-conflict applies only to enable", USAGE); if ((opId !== undefined || confirmDrift) && action !== "restore") throw new CliUsageError("--op and --confirm-drift apply only to restore", USAGE); let operation: IntegrationPlanOperation; if (action === "preview") { if (selectedOperation !== "apply" && selectedOperation !== "overwrite" && selectedOperation !== "disable") throw new CliUsageError("--operation must be apply, overwrite or disable", USAGE); operation = selectedOperation; } else operation = action === "restore" ? "restore" : action === "disable" ? "disable" : overwrite ? "overwrite" : "apply"; const modelNames = integrationModelNames(args, client, operation, USAGE); if (args.length) throw new CliUsageError("Unexpected integration argument(s)", USAGE); if (action !== "restore" && !client) throw new CliUsageError("--client is required", USAGE); if (action === "restore" && (!opId?.trim() || (client !== undefined && (client !== "aside" || profile === undefined)))) { throw new CliUsageError("restore requires --op; its optional target is --client aside --profile N", USAGE); } if (client === "aside" && profile === undefined) throw new CliUsageError("A preview or bound operation requires one Aside --profile", USAGE); if (defaults !== undefined && (client !== "droid" || !["apply", "overwrite"].includes(operation))) throw new CliUsageError("Reasoning defaults apply only to Droid apply or overwrite", USAGE); let path: string; let body: Record<string, unknown>; if (action === "restore") { path = profile === undefined ? `/api/client-integrations/restore${preview ? "/preview" : ""}` : `${clientIntegrationPath("aside", profile)}/${preview ? "preview" : "restore"}`; body = { opId, confirmDrift, ...(preview && profile !== undefined ? { operation } : {}) }; } else if (preview) { path = client === "aside" ? `${clientIntegrationPath(client, profile)}/preview` : "/api/client-integrations/preview"; body = { ...(client === "aside" ? {} : { clientId: client }), operation }; } else { path = clientIntegrationPath(client!, profile); body = { enabled: action === "enable", ...(overwrite ? { overwriteConflict: true } : {}) }; } if (defaults !== undefined) body.droidReasoningDefaults = defaults; if (modelNames !== undefined) body.modelNames = modelNames; if (token !== undefined) { body.operation = operation; body.planFingerprint = token; } return { preview, json, client, profile, operation, path, body }; } function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); } function checkIdentity(value: { clientId: string; profileId?: number }, intent: Intent): void { if ((intent.client !== undefined && value.clientId !== intent.client) || (intent.client === undefined && value.clientId === "aside") || (intent.profile === undefined ? value.profileId !== undefined : value.profileId !== Number(intent.profile))) { throw new Error("Invalid integration target response"); } } interface Receipt { ok: boolean; clientId: string; state: string; operation: IntegrationPlanOperation; profileId?: number; changed?: boolean; opId?: string; reason?: string; residual?: boolean; snapshotPath?: string; } function recoveryFields(value: Record<string, unknown>): { residual?: boolean; snapshotPath?: string } { if ((value.residual !== undefined && typeof value.residual !== "boolean") || (value.snapshotPath !== undefined && (typeof value.snapshotPath !== "string" || value.snapshotPath.length > 32768))) { throw new Error("Invalid integration recovery response"); } return { ...(typeof value.residual === "boolean" ? { residual: value.residual } : {}), ...(typeof value.snapshotPath === "string" ? { snapshotPath: redactSecretString(redactUserPath(value.snapshotPath)) } : {}), }; } function mutationReceipt(value: unknown, intent: Intent): Receipt { if (!record(value) || typeof value.ok !== "boolean" || !FILE_INTEGRATION_CLIENTS.some(id => id === value.clientId) || typeof value.state !== "string" || !INTEGRATION_STATES.has(value.state) || (value.ok ? typeof value.changed !== "boolean" : typeof value.reason !== "string" || !INTEGRATION_REFUSAL_REASONS.has(value.reason)) || (value.profileId !== undefined && (typeof value.profileId !== "number" || !Number.isSafeInteger(value.profileId) || value.profileId < 0)) || (value.opId !== undefined && (typeof value.opId !== "string" || !/^[A-Za-z0-9_-]{1,256}$/.test(value.opId)))) { throw new Error("Invalid integration mutation response"); } const result: Receipt = { ok: value.ok, clientId: value.clientId as string, state: value.state, operation: intent.operation, ...(typeof value.profileId === "number" ? { profileId: value.profileId } : {}), ...(typeof value.changed === "boolean" ? { changed: value.changed } : {}), ...(typeof value.opId === "string" ? { opId: value.opId } : {}), ...(typeof value.reason === "string" && INTEGRATION_REFUSAL_REASONS.has(value.reason) ? { reason: value.reason } : {}), ...recoveryFields(value), }; checkIdentity(result, intent); return result; } function recoveryLines(value: { residual?: boolean; snapshotPath?: string }): string[] { return [ ...(value.residual === true ? ["Automatic recovery did not finish; inspect the client configuration before retrying."] : []), ...(value.snapshotPath ? [`Backup (redacted path): ${value.snapshotPath}`] : []), ]; } const REFUSAL_GUIDANCE: Readonly<Record<string, string>> = { not_installed: "Install or locate the client before applying its integration.", conflict: "Inspect the conflicting client configuration; review an overwrite preview before choosing --overwrite-conflict.", unsafe: "Inspect the client configuration and resolve its unsafe path or contents before retrying.", non_loopback: "This integration requires a loopback proxy listener.", superseded_store: "Inspect integration status for the configuration store the client now reads.", drift_requires_confirm: "The client file changed. Review restore --preview --confirm-drift before explicitly confirming drift.", snapshot_expired: "The operation backup is no longer available; inspect integration history for another recovery point.", write_failed: "Inspect the client configuration and any recovery backup before retrying.", }; /** A missing store is fixed by hand, so its refusal says with what; the path is on the status row. */ function refusalGuidance(plan: IntegrationMutationPlan): string { if (plan.supersededReason === "missing-store" && plan.missingStoreDocument !== undefined) { return `The provider store this client reads is missing. Create it containing \`${plan.missingStoreDocument}\` ` + `(its path is supersededBy in \`ocx integration client status --client ${plan.clientId}\`), then apply again.`; } return REFUSAL_GUIDANCE[plan.refusalReason!]!; } function reportError(error: unknown): number { if (error instanceof CliUsageError) { console.error(`Error: ${error.message}`); console.error(USAGE); return 2; } if (error instanceof RuntimeApiError) { const body = record(error.body) ? error.body : {}; const stale = body.code === "integration_preview_stale"; const unavailable = body.code === "integration_preview_unavailable"; // Local discovery found no proxy: nothing was sent, so name the start command instead of // the generic management-host guidance. Server 503s always carry a body; this one has none. const stopped = error.status === 503 && error.body === null && error.message.startsWith("Proxy is not running"); console.error(stale ? "Error: Integration preview is stale. Run the explicit preview again and review its changes before retrying." : unavailable ? "Error: Integration preview is unavailable. Load the model catalog, then run the preview again." : stopped ? "Error: Proxy is not running. Start the intended proxy with: ocx start. No request was sent." : error.status === 404 ? "Error: Integration operation or profile was not found. Inspect integration history and the selected profile." : error.status === 409 ? "Error: Integration change was refused. Inspect integration status and preview before retrying." : error.status === 503 ? "Error: Management API is unavailable. Check the proxy and run this command on its management host." : "Error: Integration request failed. Inspect integration status before retrying."); if (!stale) { if (typeof body.reason === "string" && INTEGRATION_REFUSAL_REASONS.has(body.reason)) { console.error(`Refused (${body.reason}): ${REFUSAL_GUIDANCE[body.reason]}`); } // Recovery is separate from arbitrary server messages and nested replacement plans. try { for (const line of recoveryLines(recoveryFields(body))) console.error(terminalSafeText(line)); } catch { /* Invalid recovery data is not printable. */ } } return error.status === 404 ? 4 : error.status === 409 ? 5 : 1; } console.error("Error: Invalid integration response. Check the proxy version and inspect integration status."); return 1; } export async function handleIntegrationPreviewCommand(argv: string[], deps: RuntimeApiDeps = {}, expectedClientId?: IntegrationClientId): Promise<number> { try { const intent = parseIntent(argv); if (expectedClientId !== undefined && intent.operation === "restore") { if (intent.client !== undefined || intent.profile !== undefined) throw new CliUsageError("client-specific restore does not accept --client or --profile", USAGE); intent.client = expectedClientId; intent.path = `${clientIntegrationPath(expectedClientId)}/restore${intent.preview ? "/preview" : ""}`; intent.body.expectedClientId = expectedClientId; } const result = await runtimeRequest(intent.path, { method: intent.preview || intent.operation === "restore" ? "POST" : "PUT", redirect: "error", body: JSON.stringify(intent.body), }, deps); if (intent.preview) { const plan = decodeIntegrationPlan(result); checkIdentity(plan, intent); if (plan.operation !== intent.operation) throw new Error("Invalid integration operation response"); printData(plan, intent.json, [ `${plan.clientId}${plan.profileId === undefined ? "" : `:${plan.profileId}`} ${plan.operation}: ${!plan.canApply ? `refused (${plan.refusalReason})` : !plan.willChange ? "no changes needed" : "ready for review"}`, ...plan.changes.map(change => ` ${change.kind} ${change.path}`), ...(plan.canApply ? [`Fingerprint: ${plan.fingerprint}`] : [refusalGuidance(plan)]), ]); return 0; } const receipt = mutationReceipt(result, intent); printData(receipt, intent.json, [ `${receipt.clientId}${receipt.profileId === undefined ? "" : `:${receipt.profileId}`} ${receipt.operation}: ${!receipt.ok ? `refused (${receipt.reason})` : receipt.changed ? "updated" : "no changes needed"}.`, ...(receipt.opId ? [`Operation: ${receipt.opId}`] : []), ...(receipt.reason ? [REFUSAL_GUIDANCE[receipt.reason]!] : []), ...recoveryLines(receipt), ]); return receipt.ok ? 0 : 1; } catch (error) { return reportError(error); } }