@iislee/opencodex 2.31.0 → 2.35.0

package/src/cli/dispatch.ts

@@ -9,6 +9,7 @@
  * never needs to import the entry module back (no cycle).
  */
 import { CLI_COMMANDS } from "./registry";
+import { isValidProviderName } from "../config/provider-name";
 import type { CliHead } from "./root";
 import type { ReadyArgs } from "./ready";
 import type { LiveProxy } from "../server/proxy-liveness";
@@ -21,6 +22,7 @@ import { restoreNativeCodexAsync } from "../codex/inject";
 import { stripGrokConfig } from "../grok/inject";
 import { afterCatalogWriteHandleAppServers } from "../codex/app-server-processes";
 import { normalizeUpdateChannel, runGuiUpdateWorker } from "../update/job";
+import { isJsonOption, takeFlag } from "./runtime-api";
 
 export interface CliDispatchDeps {
   args: string[];
@@ -69,33 +71,37 @@ const commandRunners: Record<string, CommandRunner> = {
     return Number(process.exitCode ?? 0);
   },
   restore: async deps => {
-    const restoreJson = deps.args[1] === "--json";
-    if (deps.args[1] === "back") {
+    const restoreArgs = deps.args.slice(1);
+    const restoreJson = takeFlag(restoreArgs, "--json");
+    if (restoreArgs[0] === "back") {
       // Reverse switch: re-point plain `codex` at the RUNNING proxy without touching its
       // lifecycle — the counterpart of `ocx restore`. Start/stop triggers are unchanged;
       // this only re-runs the same inject (config + catalog + history) `ocx start` does.
+      // takeFlag above makes `ocx restore --json back` restore-back, not eject.
+      const { skippedRestoreEnvelope } = await import("../codex/inject");
+      const emitBack = (success: boolean, message: string, code: number): number => {
+        if (restoreJson) console.log(JSON.stringify(skippedRestoreEnvelope(success, message)));
+        else if (code === 0) console.log(message);
+        else console.error(message);
+        return code;
+      };
       const live = await deps.findLiveProxy();
       if (!live) {
-        console.error("No running proxy found. Run 'ocx start' — it injects opencodex automatically.");
-        return 1;
+        return emitBack(false, "No running proxy found. Run 'ocx start' — it injects opencodex automatically.", 1);
       }
       const desired = setIntegrationEnabled("codex", true);
       if (!desired.ok) {
-        console.error(`Codex desired state was not saved (${desired.reason}).`);
-        return desired.reason === "conflict" ? 2 : 1;
+        return emitBack(false, `Codex desired state was not saved (${desired.reason}).`, desired.reason === "conflict" ? 2 : 1);
       }
       const synced = await syncModelsToCodex(live.port);
       if (synced.status === "skipped") {
-        console.error("Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.");
-        return 2;
+        return emitBack(false, "Codex integration is OFF; restore back did not change Codex. Retry after the competing integration change finishes.", 2);
       }
       if (!synced.ok) {
-        console.error("Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.");
-        return 1;
+        return emitBack(false, "Plain `codex` was not switched back to opencodex. Fix the reported Codex config issue and retry.", 1);
       }
       const target = collectOrcaCodexHomeDiagnostic();
-      console.log(`Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`);
-      return 0;
+      return emitBack(true, `Plain \`codex\` now routes through opencodex in ${target.effectiveCodexHome} (undo with: ocx restore).`, 0);
     }
     const desired = setIntegrationEnabled("codex", false);
     if (!desired.ok) {
@@ -172,14 +178,35 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   doctor: async deps => {
     const doctorArgs = deps.args.slice(1);
-    const { RECOVER_ZERO_BYTE_COORDINATOR_FLAG, runDoctor } = await import("./doctor");
+    // `--json` was silently ignored here: runDoctor scans for its own flags and prints human
+    // output regardless, so a caller that asked for JSON got prose and exit 0 -- and the skill
+    // recipes recommended exactly that invocation. Refusing it is worse than supporting it and
+    // better than lying about it.
+    //
+    // Not implemented rather than deferred silently: runDoctor has no report collection at all
+    // (a module-level failure bit plus ~90 direct console emissions), and this runner appends
+    // the Codex Log Guard's human output after it returns, so emitting a JSON document here
+    // would interleave prose with JSON on one stdout -- unparseable, which is worse than the
+    // ignored flag. The structured-report refactor is tracked as its own work-phase.
+    if (doctorArgs.some(isJsonOption)) {
+      console.error("ocx doctor does not support --json yet. Run `ocx doctor` for the human report, or use `ocx status --json` and `ocx ready --json` for machine-readable health.");
+      return 2;
+    }
+    const { RECOVER_ZERO_BYTE_COORDINATOR_FLAG, runDoctor, doctorFailed } = await import("./doctor");
     await runDoctor(doctorArgs);
     if (!doctorArgs.includes("--fix-codex-runtime") && !doctorArgs.includes(RECOVER_ZERO_BYTE_COORDINATOR_FLAG)) {
       console.log("");
       const { printCodexLogGuardDoctor } = await import("./codex-log-guard-doctor");
       printCodexLogGuardDoctor();
     }
-    return 0;
+    // A diagnostic that always exits 0 cannot gate a script. `runDoctor` reports by direct
+    // console.log with no checks collection, and signals its own special-flag failures
+    // through process.exitCode, so honour both: an explicit exitCode wins, otherwise a
+    // FAIL-level check fails the command. This is a BREAKING change for pipelines that ran
+    // `ocx doctor` and ignored the result; a diagnostic that cannot fail is worse.
+    const explicit = Number(process.exitCode ?? 0);
+    if (explicit !== 0) return explicit;
+    return doctorFailed() ? 1 : 0;
   },
   debug: async deps => {
     const { handleDebugCommand } = await import("./debug");
@@ -196,14 +223,69 @@ const commandRunners: Record<string, CommandRunner> = {
     return 0;
   },
   logout: async deps => {
+    // Argv is parsed BEFORE any store access, which is the whole point of this shape.
+    // Previously `args[1]` was taken as the provider name with no parsing, so
+    // `ocx logout --json` called removeCredential("--json"), printed "Logged out of
+    // --json." and exited 0 -- a silent false success, the worst outcome for a caller
+    // that can only see the exit code.
+    //
+    // That is not merely a wasted call. `normalizeAuthStore` copies every top-level key
+    // it finds, so a hand-edited, legacy, or corrupted auth.json containing a `--json`
+    // key would have its active account deleted -- and the key dropped entirely if that
+    // was its last account. A flag must never reach the store as a provider name.
+    const logoutArgs = deps.args.slice(1);
+    const wantsJson = logoutArgs.includes("--json");
+    // Any leading dash is an option, not a provider. Matching only `--` left the same defect
+    // one dash shorter: `ocx logout -j` treated `-j` as the provider name and, with a `-j` key
+    // present in the store, deleted it and exited 0.
+    const isOption = (arg: string): boolean => arg.startsWith("-");
+    const positionals = logoutArgs.filter(arg => !isOption(arg));
+    const unknownFlags = logoutArgs.filter(arg => isOption(arg) && arg !== "--json");
+    const name = (positionals[0] ?? "").trim().toLowerCase();
+
+    // Usage failures exit 2 and touch nothing. A missing provider is a usage error; a
+    // provider that simply has no credential is a not-found (4) further down, because the
+    // vocabulary distinguishes "you called this wrong" from "the thing is not there".
+    //
+    // The shape check is `isValidProviderName`, not another dash test. Rejecting a leading
+    // ASCII `-` fixed `-j` and still let `logout —json` through with a Unicode dash, which is
+    // the same defect a third time: each patch named one spelling instead of the class. The
+    // canonical validator states the rule positively -- start and end alphanumeric, internal
+    // `._-` allowed -- so `github-copilot` and `google-antigravity` pass while every dash
+    // variant, empty string, and reserved name fails. Anything that is not a possible
+    // provider id cannot reach the store at all.
+    const malformedName = Boolean(name) && !isValidProviderName(name);
+    if (unknownFlags.length > 0 || positionals.length > 1 || !name || malformedName) {
+      const problem = unknownFlags.length > 0
+        ? `unknown option ${unknownFlags[0]}`
+        : positionals.length > 1 ? "too many arguments"
+        : malformedName ? `not a valid provider name: ${name}`
+        : "missing provider";
+      console.error(`Usage: ocx logout <provider> [--json]  (${problem})`);
+      return 2;
+    }
+
+    // The disposition comes from inside the store mutation, not from a read-then-remove
+    // preflight. `mutateStore` serializes writes, so a preflight leaves a window where a
+    // concurrent logout removes the same account and BOTH callers exit 0 claiming a removal --
+    // a false success again, just a narrower one than the flag bug above.
     const { removeCredential } = await import("../oauth/store");
-    const name = (deps.args[1] ?? "").trim().toLowerCase();
-    await removeCredential(name);
-    console.log(`Logged out of ${name || "(none)"}.`);
+    const outcome = await removeCredential(name);
+    if (outcome === "not-found") {
+      if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: false, provider: name, removed: false, reason: "not_found" }, null, 2));
+      else console.error(`No stored credential for '${name}'.`);
+      return 4;
+    }
+    if (wantsJson) console.log(JSON.stringify({ schemaVersion: 1, ok: true, provider: name, removed: true }, null, 2));
+    else console.log(`Logged out of ${name}.`);
     return 0;
   },
   sync: async deps => {
-    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const syncArgs = deps.args.slice(1);
+    const restartCodex = syncArgs.includes("--restart-codex");
+    // Separate flag on purpose: --restart-codex promises app-server-only scope,
+    // and quitting the desktop app ends live conversations.
+    const restartDesktopApp = syncArgs.includes("--restart-desktop-app");
     const live = await deps.findLiveProxy();
     const synced = await syncModelsToCodex(
       live?.port,
@@ -229,6 +311,7 @@ const commandRunners: Record<string, CommandRunner> = {
     // exactly when a long-lived app-server is holding the stale list.
     if (synced.catalogWritten || synced.cacheSynced) {
       afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
+      if (restartDesktopApp) await handleDesktopAppRestart(console);
     }
     // `ocx sync` is a direct CLI path; it does not call the management
     // `/api/sync` route. Refresh the already-connected MCode block here too,
@@ -259,21 +342,82 @@ const commandRunners: Record<string, CommandRunner> = {
     return await cmdV2(deps.args.slice(1), {}, async () => (await deps.findLiveProxy())?.port);
   },
   "sync-cache": async deps => {
-    const restartCodex = deps.args.slice(1).includes("--restart-codex");
+    const cacheArgs = deps.args.slice(1);
+    const restartCodex = cacheArgs.includes("--restart-codex");
+    const restartDesktopApp = cacheArgs.includes("--restart-desktop-app");
     const { withCatalogWriteSerialization } = await import("../codex/catalog-write-serialization");
     const { invalidateCodexModelsCacheWithPermit } = await import("../codex/catalog/sync");
     const { getCodexHome } = await import("../codex/paths");
+    const { readCodexCatalogPathForHome } = await import("../codex/catalog/parsing");
+    const { existsSync } = await import("node:fs");
     const owningCodexHome = getCodexHome();
     const desiredDisabled = !shouldSyncCodexOnStart(deps.loadConfig());
     const invalidated = withCatalogWriteSerialization(owningCodexHome, permit =>
       invalidateCodexModelsCacheWithPermit(permit, owningCodexHome, { allowWhenDesiredDisabled: true }));
+    const cacheJson = cacheArgs.includes("--json");
+    const jsonSafeLog = cacheJson
+      ? { log: (...values: unknown[]) => console.error(...values), error: (...values: unknown[]) => console.error(...values) }
+      : console;
     // Only warn/restart when models_cache was actually rewritten from a readable catalog.
     if (invalidated.kind === "completed" && invalidated.value) {
-      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: console });
-    } else if (desiredDisabled) {
-      console.log("Codex integration is OFF; cache sync skipped (no catalog or cache write).");
+      afterCatalogWriteHandleAppServers({ restart: restartCodex, log: jsonSafeLog });
+      if (restartDesktopApp) await handleDesktopAppRestart(jsonSafeLog);
+    } else if (desiredDisabled && !cacheJson) {
+      // Worth saying in the human path, because it explains why nothing was written.
+      // Under --json this belongs on the envelope, not as a second stdout line.
+      console.log("Codex integration is OFF; no catalog or cache write resulted.");
     }
-    return 0;
+    // `completed` with a falsy value means the cache was NOT rewritten. Previously every
+    // outcome exited 0, so a script could not tell a refreshed cache from a skipped one.
+    //
+    // Losing the catalog write lock to another process is a skip, not a failure:
+    // serialization working as designed is the expected outcome under concurrency, and a
+    // proxy startup holding the permit would otherwise make a perfectly healthy
+    // `ocx sync-cache` exit 1 and fail the pipeline that called it -- intermittently, so it
+    // would read as a flake rather than a bug. `codex-retained-root-serialization.test.ts`
+    // pins exactly that: contended lock, no cache write, exit 0.
+    //
+    // `desiredDisabled` is deliberately NOT part of the success test, which is the subtle
+    // part. This call passes `allowWhenDesiredDisabled: true`, so the OFF gate inside the
+    // refresh never fires and the work is genuinely attempted -- an explicit `ocx sync-cache`
+    // means the user asked for it regardless of the toggle. Treating OFF as automatic success
+    // would report exit 0 and `skipped: true` for a refresh that actually failed.
+    //
+    // But `invalidateCodexModelsCacheWithPermit` returns a bare boolean for four different
+    // situations -- wrote it, no catalog file exists, the OFF gate fired, or it threw -- so
+    // `false` alone cannot be read as failure either. `!existsSync(catalogPath)` is a
+    // legitimate nothing-to-do: with no catalog there is no cache to derive, which is the
+    // normal state of a fully native home and the case
+    // `codex-composed-acceptance.test.ts` pins at exit 0. It is checked here rather than by
+    // widening that function's return type, because its boolean is consumed by a dozen
+    // management routes that have no use for the distinction.
+    const wrote = invalidated.kind === "completed" && Boolean(invalidated.value);
+    const contended = invalidated.kind === "unavailable" && invalidated.reason === "busy";
+    const noCatalog = !wrote && !existsSync(readCodexCatalogPathForHome(owningCodexHome));
+    const ok = wrote || contended || noCatalog;
+    if (cacheJson) {
+      console.log(JSON.stringify({
+        schemaVersion: 1,
+        ok,
+        wrote,
+        skipped: contended || noCatalog,
+        outcome: invalidated.kind,
+        // `outcome` alone cannot separate a contended lock from a hard serialization
+        // failure -- both are `unavailable`. Carry the reason so a caller can.
+        reason: invalidated.kind === "unavailable" ? invalidated.reason : undefined,
+        // Which of the two benign skips this was, so `skipped: true` is never opaque.
+        skippedReason: contended ? "contended" : noCatalog ? "no_catalog" : undefined,
+        desiredDisabled,
+        codexHome: owningCodexHome,
+      }, null, 2));
+    } else if (contended) {
+      console.log("Another process owns the catalog write; cache sync skipped.");
+    } else if (noCatalog) {
+      console.log("No Codex catalog to derive a cache from; nothing to sync.");
+    } else if (!ok) {
+      console.error(`Cache refresh did not complete (${invalidated.kind}). The Codex model cache was not rewritten.`);
+    }
+    return ok ? 0 : 1;
   },
   gui: async deps => {
     const config = deps.loadConfig();
@@ -307,8 +451,12 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   tray: async deps => {
     const { windowsTrayCommand } = await import("../tray/windows");
+    // windowsTrayCommand reports failure through process.exitCode (tray/windows.ts sets
+    // it for bad usage and for a failed install/start/stop/uninstall) and returns void,
+    // so a literal 0 here made `ocx tray install` print an error and exit 0 (#2697).
+    process.exitCode = 0;
     await windowsTrayCommand(deps.args.slice(1));
-    return 0;
+    return Number(process.exitCode ?? 0);
   },
   "codex-shim": async deps => {
     const { codexShimStatus, diagnoseCodexShim, installCodexShim, uninstallCodexShim } = await import("../codex/shim");
@@ -387,6 +535,10 @@ const commandRunners: Record<string, CommandRunner> = {
     await deps.handleProxyRestart(deps.handleRestartStartWhenStopped);
     return Number(process.exitCode ?? 0);
   },
+  capabilities: async deps => {
+    const { runCapabilities } = await import("./capabilities-command");
+    return await runCapabilities(deps.args.slice(1));
+  },
   health: async deps => {
     const healthArgs = deps.args.slice(1);
     const wantsHealthJson = healthArgs.includes("--json");
@@ -410,8 +562,15 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   provider: async deps => {
     const { handleProviderCommand } = await import("./provider");
+    // Reset first, like the service runner below: reading process.exitCode only
+    // reports THIS command's outcome if nothing earlier in the process set it.
+    process.exitCode = 0;
     await handleProviderCommand(deps.args.slice(1));
-    return 0;
+    // handleProviderCommand reports failure through process.exitCode, which it sets
+    // from handleProviderRuntimeCommand. Returning a literal 0 here made index.ts
+    // call process.exit(0) and erase it, so `ocx provider quota` against a stopped
+    // proxy printed an error and still exited 0 (#2697).
+    return Number(process.exitCode ?? 0);
   },
   account: async deps => {
     const { cmdAccount } = await import("./account");
@@ -419,8 +578,15 @@ const commandRunners: Record<string, CommandRunner> = {
   },
   models: async deps => {
     const { handleModels } = await import("./models");
+    process.exitCode = 0;
     await handleModels(deps.args.slice(1));
-    return 0;
+    // Same as the provider runner above: handleModels sets process.exitCode from
+    // handleModelsRuntimeCommand, and a literal 0 discarded it (#2697).
+    return Number(process.exitCode ?? 0);
+  },
+  alias: async deps => {
+    const { handleAliasCommand } = await import("./alias");
+    return await handleAliasCommand(deps.args.slice(1));
   },
   combo: async deps => {
     const { handleComboCommand } = await import("./combo");
@@ -447,6 +613,10 @@ const commandRunners: Record<string, CommandRunner> = {
     const { handleObserveCommand } = await import("./observe");
     return await handleObserveCommand(deps.args.slice(1));
   },
+  inspect: async deps => {
+    const { handleInspectCommand } = await import("./inspect");
+    return await handleInspectCommand(deps.args.slice(1));
+  },
   logs: async deps => {
     const { handleObserveCommand } = await import("./observe");
     return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
@@ -456,8 +626,12 @@ const commandRunners: Record<string, CommandRunner> = {
     return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
   },
   storage: async deps => {
-    const { handleObserveCommand } = await import("./observe");
-    return await handleObserveCommand([deps.command!, ...deps.args.slice(1)]);
+    // `ocx storage` used to be a pure alias of `observe storage`, which reached only the report
+    // route. wp7 gave it cleanup, trash, and policy subcommands, so it dispatches to its own
+    // module -- with `report` as the default subcommand, so a bare `ocx storage` still prints
+    // the same thing it printed before.
+    const { handleStorageCommand } = await import("./storage");
+    return await handleStorageCommand(deps.args.slice(1));
   },
   memory: async deps => {
     const { handleObserveCommand } = await import("./observe");
@@ -484,6 +658,12 @@ const commandRunners: Record<string, CommandRunner> = {
     if (integration === "grok") {
       const { handleGrokCommand } = await import("./integrations");
       return await handleGrokCommand(deps.args.slice(2));
+    } else if (integration === "native") {
+      // The native client toggles are a separate server surface from the reversible file
+      // integrations `client` manages, so they get their own subcommand rather than being
+      // folded into one that means something else.
+      const { handleIntegrationCommand } = await import("./inspect");
+      return await handleIntegrationCommand(deps.args.slice(1));
     } else if (integration === "claude") {
       const { handleClaudeConfigCommand } = await import("./integrations");
       return await handleClaudeConfigCommand(deps.args.slice(2));
@@ -591,3 +771,51 @@ export async function dispatchCommand(head: CliHead, deps: CliDispatchDeps): Pro
   }
   return await runner(deps);
 }
+
+/**
+ * Report the outcome of an opt-in desktop-app restart. Kept next to the two
+ * callers so `sync` and `sync-cache` cannot drift in what they tell the user.
+ */
+async function handleDesktopAppRestart(log: Pick<Console, "log" | "error">): Promise<void> {
+  const { restartCodexDesktopApp } = await import("../codex/desktop-app-restart");
+  const result = restartCodexDesktopApp();
+  switch (result.reason) {
+    case "windows_only":
+      log.error("--restart-desktop-app is supported on Windows only; nothing was stopped.");
+      return;
+    case "package_discovery_failed":
+      log.error(
+        "Could not identify the installed Codex desktop package. Quit and relaunch the desktop app "
+        + "manually to refresh the model picker.",
+      );
+      return;
+    case "self_ancestry":
+      log.error(
+        "Refusing to restart the desktop app because this command is running inside it. "
+        + "Run 'ocx sync --restart-desktop-app' from an external terminal instead.",
+      );
+      return;
+    case "process_probe_failed":
+      // Distinct from `no_targets`: we could not look, which is not the same as looking and
+      // finding nothing. Saying "not running" here sent users away believing there was nothing
+      // to restart (#2557).
+      log.error(
+        "Could not enumerate Codex desktop processes, so the app was not restarted. "
+        + "Quit and relaunch the desktop app manually to refresh the model picker.",
+      );
+      return;
+    case "no_targets":
+      log.log("Codex desktop app is not running; nothing to restart.");
+      return;
+    case "targets_survived":
+      log.error(
+        `Codex desktop app PID(s) ${result.surviving.join(", ")} did not exit, so it was not relaunched. `
+        + "Quit the desktop app manually to refresh the model picker.",
+      );
+      return;
+    default:
+      if (result.relaunch === "started") {
+        log.log("Codex desktop app restarted; its model picker will re-read the catalog.");
+      }
+  }
+}