@bitkyc08/opencodex 2.8.0 → 2.9.0

package/src/cli/export-command.ts

@@ -0,0 +1,187 @@
+/**
+ * `ocx export --client <opencode|pi>` — print a client config for the live proxy.
+ *
+ * Two consumers, one payload (devlog 260731_client_config_export/020):
+ *
+ * - **Agent** (`--json`): stdout is exactly the client config JSON and nothing else, so
+ *   `ocx export --client pi --json > models.json` is safe to pipe. Every diagnostic —
+ *   including the `--out` write note — goes to stderr.
+ * - **Human** (no flag): the JSON leads, then the destination path, the merge warning,
+ *   the env export line, and the model/degraded counts.
+ *
+ * The command never writes the user's real config path. `--out` is an explicit target and
+ * refuses to clobber an existing file without `--force`, because the common mistake
+ * (`--out ~/.config/opencode/opencode.json`) would silently destroy other providers.
+ *
+ * Serialization itself belongs to src/clients/config-export.ts; this module only resolves
+ * the base URL, filters the catalog, and renders. No secret is ever serialized: the config
+ * carries the client's documented env reference and the real key stays in the environment.
+ */
+import { writeFileSync } from "node:fs";
+import { loadConfig } from "../config";
+import {
+  EXPORT_CLIENTS,
+  EXPORT_CLIENT_IDS,
+  buildClientConfig,
+  isExportClientId,
+  opencodeProxyBaseUrl,
+  type ExportClientId,
+  type ExportModel,
+} from "../clients/config-export";
+import { opencodeCatalogFromProxyRows, type OpencodeProxyModelRow } from "./opencode";
+import type { OcxConfig } from "../types";
+import {
+  CliUsageError,
+  RuntimeApiError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeBaseUrl,
+  runtimeRequest,
+  takeFlag,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx export --client <${EXPORT_CLIENT_IDS.join("|")}> [--json] [--out <path>] [--force]`;
+
+export interface ExportCommandDeps extends RuntimeApiDeps {
+  /** Live config seam; tests inject a fixture instead of reading the user's config. */
+  configImpl?: () => OcxConfig;
+}
+
+/**
+ * `/api/models` row plus the modality list Pi consumes. The launcher's row type predates
+ * the Pi exporter and stops at the fields OpenCode needs.
+ */
+type ExportProxyModelRow = OpencodeProxyModelRow & { inputModalities?: string[] };
+
+/** Same authoritativeness rule the serializers apply, for the degraded-count line. */
+function hasContextLimit(model: ExportModel): boolean {
+  return typeof model.contextWindow === "number"
+    && Number.isFinite(model.contextWindow)
+    && model.contextWindow > 0;
+}
+
+/**
+ * Export rows from proxy `/api/models` rows.
+ *
+ * `opencodeCatalogFromProxyRows` owns the visibility rules (drop `disabled`, drop dupes,
+ * drop native under Codex Direct) — the export core does none of that, so a row filtered
+ * here is the only thing keeping a disabled model out of a client's picker. Modalities are
+ * re-joined by `namespaced` because the launcher's catalog type does not carry them.
+ */
+export function exportModelsFromProxyRows(
+  rows: readonly ExportProxyModelRow[],
+  config: OcxConfig,
+): ExportModel[] {
+  const modalities = new Map<string, string[]>();
+  for (const row of rows) {
+    const namespaced = row.namespaced?.trim();
+    if (namespaced && Array.isArray(row.inputModalities) && row.inputModalities.length > 0) {
+      if (!modalities.has(namespaced)) modalities.set(namespaced, [...row.inputModalities]);
+    }
+  }
+  return opencodeCatalogFromProxyRows(rows, config).map(entry => {
+    const model: ExportModel = {
+      namespaced: entry.namespaced,
+      provider: entry.provider ?? (entry.native ? "openai" : "routed"),
+      id: entry.id ?? entry.namespaced,
+    };
+    if (entry.native) model.native = true;
+    if (entry.displayName) model.displayName = entry.displayName;
+    if (entry.contextWindow !== undefined) model.contextWindow = entry.contextWindow;
+    const input = modalities.get(entry.namespaced);
+    if (input) model.inputModalities = input;
+    return model;
+  });
+}
+
+/**
+ * `http://host:port/v1` for the proxy that is actually listening.
+ *
+ * `runtimeBaseUrl` is the identity-checked `findLiveProxy` probe the launcher uses, and it
+ * already throws the "Start it with: ocx start" error when nothing answers — so a config
+ * with an empty models block can never be emitted.
+ *
+ * Resolved ONCE and handed back to `runtimeRequest` as `baseUrl`, so the catalog and the
+ * exported endpoint can never come from two different probes.
+ */
+function proxyV1BaseUrl(root: string): string {
+  const url = new URL(root);
+  const port = url.port ? Number(url.port) : url.protocol === "https:" ? 443 : 80;
+  return opencodeProxyBaseUrl(port, url.hostname);
+}
+
+function parseClient(args: string[]): ExportClientId {
+  const raw = takeOption(args, "--client");
+  if (raw === undefined) {
+    throw new CliUsageError(`--client is required (${EXPORT_CLIENT_IDS.join(", ")})`, USAGE);
+  }
+  const client = raw.trim().toLowerCase();
+  if (!isExportClientId(client)) {
+    throw new CliUsageError(`--client must be one of: ${EXPORT_CLIENT_IDS.join(", ")}`, USAGE);
+  }
+  return client;
+}
+
+/**
+ * Write the config, refusing to replace an existing file without `--force`.
+ *
+ * The `wx` flag does the refusal in the kernel rather than after an `existsSync` check, so
+ * a file created between the two can never be truncated. Nothing is printed before this
+ * runs: a refusal leaves both the target bytes and stdout untouched.
+ */
+function writeExport(path: string, text: string, force: boolean): void {
+  try {
+    writeFileSync(path, text, force ? { encoding: "utf8" } : { encoding: "utf8", flag: "wx" });
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "EEXIST") {
+      throw new CliUsageError(
+        `${path} already exists. Re-run with --force to replace it, or print the config and merge it yourself.`,
+        USAGE,
+      );
+    }
+    throw error;
+  }
+}
+
+export async function handleExportCommand(argv: string[], deps: ExportCommandDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const client = parseClient(args);
+    const wantsJson = takeFlag(args, "--json");
+    const force = takeFlag(args, "--force");
+    const out = takeOption(args, "--out");
+    rejectArgs(args, USAGE);
+
+    const spec = EXPORT_CLIENTS[client];
+    const config = (deps.configImpl ?? loadConfig)();
+    const root = await runtimeBaseUrl(deps);
+    const rows = await runtimeRequest<ExportProxyModelRow[]>("/api/models", {}, { ...deps, baseUrl: root });
+    if (!Array.isArray(rows)) {
+      throw new RuntimeApiError("Management API returned an unexpected /api/models payload.", 502, rows);
+    }
+    const models = exportModelsFromProxyRows(rows, config);
+    const clientConfig = buildClientConfig(client, { baseUrl: proxyV1BaseUrl(root), models, config });
+    const text = JSON.stringify(clientConfig, null, 2);
+
+    if (out !== undefined) writeExport(out, `${text}\n`, force);
+    // stderr, so `--json` stdout stays byte-exact for a redirect.
+    if (out !== undefined && wantsJson) console.error(`Wrote ${out}`);
+
+    const degraded = models.filter(model => !hasContextLimit(model)).length;
+    printData(clientConfig, wantsJson, [
+      text,
+      "",
+      ...(out !== undefined ? [`Wrote ${out}`] : []),
+      `Destination: ${spec.destination(process.env)}`,
+      "Merge this provider block into that file; do not replace it.",
+      `Before launching: ${spec.exportHint}`,
+      `${models.length} model${models.length === 1 ? "" : "s"}; ${degraded} omit context limits (the client applies its own defaults).`,
+    ]);
+  });
+}
+
+export const EXPORT_USAGE = USAGE;

package/src/cli/help.ts

@@ -169,6 +169,16 @@ const helpEntries: Record<string, HelpEntry> = {
     summary: "Manage OpenCodex admission API keys and inspect external endpoints.",
   },
   "api-key": { usage: "ocx api-key <list|create|remove> ...", summary: "Alias of ocx access key." },
+  export: {
+    usage: "ocx export --client <opencode|pi> [--json] [--out <path>] [--force]",
+    summary: "Print a client config (opencode, Pi) wired to the running proxy.",
+    details: [
+      "--json prints only the config JSON on stdout, so it is safe to redirect to a file.",
+      "--out <path> writes the config there and refuses to replace an existing file without --force.",
+      "The config never contains a key; it references the client's env var, which you export before launching.",
+      "The destination path is printed for merging by hand — ocx never writes your real client config.",
+    ],
+  },
   grok: { usage: "ocx grok <status|exclude|include|set|clear|apply> ...", summary: "Manage and apply the Grok Build model fence." },
   integration: { usage: "ocx integration <claude|grok> ...", summary: "Manage supported client integrations." },
   system: {
@@ -286,6 +296,7 @@ Usage:
   ocx agent <sub>             Subagents, injection, effort caps, and sidecars
   ocx observe <sub>           Logs, usage, storage, memory, and debug data
   ocx access <sub>            External API keys and endpoint information
+  ocx export --client <id>    Print an opencode/Pi config wired to the running proxy
   ocx grok <sub>              Grok Build model selection and apply
   ocx system <sub>            Runtime settings, startup, sync, and updates
   ocx config <sub>            Validated configuration show/get/set/import/export

package/src/cli/index.ts

@@ -129,16 +129,21 @@ async function chooseListenPort(requestedPort?: number): Promise<number> {
   if (hardPin && preferred > 0) {
     const { reclaimListenPort } = await import("../server/port-reclaim");
     await reclaimListenPort(preferred, config.hostname ?? "127.0.0.1", {
-      timeoutMs: 30_000,
+      // Ghost LISTEN rows with a dead PID can outlive the process for a while.
+      // SetTcpEntry(DELETE_TCB) needs elevation (often returns 317), so the only
+      // reliable non-admin recovery is to wait for the OS to release the TCB.
+      timeoutMs: 60_000,
       intervalMs: 100,
       scanIntervalMs: 500,
       killOcxHolders: false,
-      dropTcpRows: false,
+      dropTcpRows: true,
     });
   }
   try {
     const selected = await findAvailablePort(preferred, config.hostname ?? "127.0.0.1", {
-      preferRetryMs: hardPin ? 0 : 750,
+      // After reclaim, keep probing briefly — ghost rows sometimes clear between
+      // the reclaim deadline and the final listen. Still never hop off `--port`.
+      preferRetryMs: hardPin ? 5_000 : 750,
       preferRetryIntervalMs: 50,
       allowEphemeralFallback: !hardPin,
     });
@@ -1031,6 +1036,11 @@ switch (command) {
     process.exitCode = await handleAccessCommand(["key", ...args.slice(1)]);
     break;
   }
+  case "export": {
+    const { handleExportCommand } = await import("./export-command");
+    process.exitCode = await handleExportCommand(args.slice(1));
+    break;
+  }
   case "grok": {
     const { handleGrokCommand } = await import("./integrations");
     process.exitCode = await handleGrokCommand(args.slice(1));

package/src/cli/init.ts

@@ -8,11 +8,28 @@ import type { OcxConfig, OcxProviderConfig } from "../types";
 
 function createPrompt(): { ask(question: string): Promise<string>; close(): void } {
   const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  let closed = false;
+  rl.on("close", () => { closed = true; });
   return {
     ask(question: string): Promise<string> {
-      return new Promise(resolve => rl.question(question, resolve));
+      return new Promise((resolve, reject) => {
+        if (closed) {
+          reject(new Error("stdin closed before the prompt could be answered"));
+          return;
+        }
+        const onClose = () => {
+          reject(new Error("stdin reached EOF while waiting for input"));
+        };
+        rl.once("close", onClose);
+        rl.question(question, answer => {
+          rl.off("close", onClose);
+          resolve(answer);
+        });
+      });
+    },
+    close() {
+      if (!closed) rl.close();
     },
-    close() { rl.close(); },
   };
 }
 
@@ -83,115 +100,125 @@ export function cleanupOpenAiTierBackupAfterInit(configPath = getConfigPath()):
 
 export async function runInit(): Promise<void> {
   const prompt = createPrompt();
-  console.log("\n🔧 opencodex (ocx) setup\n");
-
-  const providers = buildInitProviders();
-  printMenu(providers);
-
-  const choice = await prompt.ask("\nSelect default provider (number): ");
-  const idx = parseInt(choice, 10) - 1;
-
-  let providerName: string;
-  let providerConfig: OcxProviderConfig;
-  let oauthHint = false;
-
-  if (idx >= 0 && idx < providers.length) {
-    const p = providers[idx];
-    providerName = p.id;
-    console.log(`\n📡 ${p.label}`);
-    console.log(`   Base URL: ${p.baseUrl}`);
-
-    if (p.kind === "forward") {
-      providerConfig = { adapter: p.adapter, baseUrl: p.baseUrl, authMode: "forward" };
-      console.log("   No API key needed — forwards your existing `codex login`.");
-    } else if (p.kind === "oauth") {
-      providerConfig = { adapter: p.adapter, baseUrl: p.baseUrl, authMode: "oauth", ...(p.defaultModel ? { defaultModel: p.defaultModel } : {}) };
-      oauthHint = true;
-    } else {
-      // key + local: collect a key (local usually blank).
-      if (p.dashboardUrl) console.log(`   🔑 Get your key: ${p.dashboardUrl}`);
-      // Template URL with placeholders (e.g. Cloudflare's {account_id}) needs a resolved value.
-      let baseUrl = p.baseUrl;
-      if (/\{[^}]*\}/.test(baseUrl)) {
-        const resolved = (await prompt.ask(`   Your endpoint URL (${baseUrl}): `)).trim();
-        if (!resolved) {
-          console.error("   A resolved URL is required — replace the {placeholder} with your actual value.");
-          process.exit(1);
+  try {
+    console.log("\n🔧 opencodex (ocx) setup\n");
+
+    const providers = buildInitProviders();
+    printMenu(providers);
+
+    const choice = await prompt.ask("\nSelect default provider (number): ");
+    const idx = parseInt(choice, 10) - 1;
+
+    let providerName: string;
+    let providerConfig: OcxProviderConfig;
+    let oauthHint = false;
+
+    if (idx >= 0 && idx < providers.length) {
+      const p = providers[idx];
+      providerName = p.id;
+      console.log(`\n📡 ${p.label}`);
+      console.log(`   Base URL: ${p.baseUrl}`);
+
+      if (p.kind === "forward") {
+        providerConfig = { adapter: p.adapter, baseUrl: p.baseUrl, authMode: "forward" };
+        console.log("   No API key needed — forwards your existing `codex login`.");
+      } else if (p.kind === "oauth") {
+        providerConfig = { adapter: p.adapter, baseUrl: p.baseUrl, authMode: "oauth", ...(p.defaultModel ? { defaultModel: p.defaultModel } : {}) };
+        oauthHint = true;
+      } else {
+        // key + local: collect a key (local usually blank).
+        if (p.dashboardUrl) console.log(`   🔑 Get your key: ${p.dashboardUrl}`);
+        // Template URL with placeholders (e.g. Cloudflare's {account_id}) needs a resolved value.
+        let baseUrl = p.baseUrl;
+        if (/\{[^}]*\}/.test(baseUrl)) {
+          const resolved = (await prompt.ask(`   Your endpoint URL (${baseUrl}): `)).trim();
+          if (!resolved) {
+            console.error("   A resolved URL is required — replace the {placeholder} with your actual value.");
+            process.exit(1);
+          }
+          baseUrl = resolved;
         }
-        baseUrl = resolved;
+        const env = envKeyFor(p.id);
+        const hint = p.kind === "local" ? "API key (usually blank — press Enter): " : `API key (paste, or env var $${env}): `;
+        const apiKey = (await prompt.ask(`\n${hint}`)).trim();
+        const modelChoice = (await prompt.ask(`Default model${p.defaultModel ? ` [${p.defaultModel}]` : " (optional)"}: `)).trim();
+        const defaultModel = modelChoice || p.defaultModel;
+        providerConfig = {
+          adapter: p.adapter,
+          baseUrl,
+          ...(p.kind === "key" ? { apiKey: apiKey || `\${${env}}` } : apiKey ? { apiKey } : {}),
+          ...(defaultModel ? { defaultModel } : {}),
+        };
+        // Apply the catalog's models / vision classification (same enrichment as the GUI).
+        enrichProviderFromCatalog(p.id, providerConfig);
+      }
+    } else {
+      providerName = (await prompt.ask("Provider name: ")).trim();
+      if (!isValidProviderName(providerName)) {
+        console.error("Provider name must use letters, numbers, dot, underscore, or hyphen and cannot be a reserved object key.");
+        process.exit(1);
       }
-      const env = envKeyFor(p.id);
-      const hint = p.kind === "local" ? "API key (usually blank — press Enter): " : `API key (paste, or env var $${env}): `;
-      const apiKey = (await prompt.ask(`\n${hint}`)).trim();
-      const modelChoice = (await prompt.ask(`Default model${p.defaultModel ? ` [${p.defaultModel}]` : " (optional)"}: `)).trim();
-      const defaultModel = modelChoice || p.defaultModel;
+      const baseUrl = await prompt.ask("Base URL (e.g. http://localhost:11434/v1): ");
+      const adapter = await prompt.ask("Adapter [openai-chat]: ") || "openai-chat";
+      const apiKey = await prompt.ask("API key (optional): ");
+      const defaultModel = await prompt.ask("Default model: ");
       providerConfig = {
-        adapter: p.adapter,
-        baseUrl,
-        ...(p.kind === "key" ? { apiKey: apiKey || `\${${env}}` } : apiKey ? { apiKey } : {}),
-        ...(defaultModel ? { defaultModel } : {}),
+        adapter: adapter.trim(),
+        baseUrl: baseUrl.trim(),
+        ...(apiKey.trim() ? { apiKey: apiKey.trim() } : {}),
+        ...(defaultModel.trim() ? { defaultModel: defaultModel.trim() } : {}),
       };
-      // Apply the catalog's models / vision classification (same enrichment as the GUI).
-      enrichProviderFromCatalog(p.id, providerConfig);
-    }
-  } else {
-    providerName = (await prompt.ask("Provider name: ")).trim();
-    if (!isValidProviderName(providerName)) {
-      console.error("Provider name must use letters, numbers, dot, underscore, or hyphen and cannot be a reserved object key.");
-      prompt.close();
-      process.exit(1);
     }
-    const baseUrl = await prompt.ask("Base URL (e.g. http://localhost:11434/v1): ");
-    const adapter = await prompt.ask("Adapter [openai-chat]: ") || "openai-chat";
-    const apiKey = await prompt.ask("API key (optional): ");
-    const defaultModel = await prompt.ask("Default model: ");
-    providerConfig = {
-      adapter: adapter.trim(),
-      baseUrl: baseUrl.trim(),
-      ...(apiKey.trim() ? { apiKey: apiKey.trim() } : {}),
-      ...(defaultModel.trim() ? { defaultModel: defaultModel.trim() } : {}),
-    };
-  }
 
-  const portStr = await prompt.ask("\nProxy port [10100]: ");
-  const port = parseInt(portStr, 10) || 10100;
+    const portStr = await prompt.ask("\nProxy port [10100]: ");
+    const port = parseInt(portStr, 10) || 10100;
 
-  const config: OcxConfig = {
-    ...getDefaultConfig(),
-    port,
-    providers: { [providerName]: providerConfig },
-    defaultProvider: providerName,
-  };
+    const config: OcxConfig = {
+      ...getDefaultConfig(),
+      port,
+      providers: { [providerName]: providerConfig },
+      defaultProvider: providerName,
+    };
 
-  saveConfig(config);
-  // Init writes a fresh config, so a stale pre-migration backup from a previous
-  // installation would make the next `ocx start` crash on a stale-backup
-  // collision (issue #257). But only a STALE backup (unparseable, or already a
-  // post-migration v2 snapshot) may be deleted; a backup that still parses as a
-  // valid pre-migration (v1) config is a user-intentional rollback point and is
-  // preserved by renaming it out of the collision path (sol review 260722).
-  cleanupOpenAiTierBackupAfterInit();
-  console.log(`\n✅ Config saved to ~/.opencodex/config.json`);
-  if (oauthHint) console.log(`🔐 Authenticate this provider with:  ocx login ${providerName}`);
-
-  const injectAnswer = await prompt.ask("Inject into Codex config.toml? [Y/n]: ");
-  if (injectAnswer.trim().toLowerCase() !== "n") {
-    console.log("Fetching available models from provider...");
-    const result = await injectCodexConfig(port, config);
-    console.log(result.success ? `✅ ${result.message}` : `⚠️  ${result.message}`);
-  }
+    saveConfig(config);
+    // Init writes a fresh config, so a stale pre-migration backup from a previous
+    // installation would make the next `ocx start` crash on a stale-backup
+    // collision (issue #257). But only a STALE backup (unparseable, or already a
+    // post-migration v2 snapshot) may be deleted; a backup that still parses as a
+    // valid pre-migration (v1) config is a user-intentional rollback point and is
+    // preserved by renaming it out of the collision path (sol review 260722).
+    cleanupOpenAiTierBackupAfterInit();
+    console.log(`\n✅ Config saved to ~/.opencodex/config.json`);
+    if (oauthHint) console.log(`🔐 Authenticate this provider with:  ocx login ${providerName}`);
+
+    const injectAnswer = await prompt.ask("Inject into Codex config.toml? [Y/n]: ");
+    if (injectAnswer.trim().toLowerCase() !== "n") {
+      console.log("Fetching available models from provider...");
+      const result = await injectCodexConfig(port, config);
+      console.log(result.success ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+    }
 
-  const shimAnswer = await prompt.ask("Install Codex autostart shim? [Y/n]: ");
-  if (shimAnswer.trim().toLowerCase() !== "n") {
-    try {
-      const { installCodexShim } = await import("../codex/shim");
-      const result = installCodexShim();
-      console.log(result.installed ? `✅ ${result.message}` : `⚠️  ${result.message}`);
-    } catch (err) {
-      console.log(`⚠️  Codex autostart shim skipped: ${err instanceof Error ? err.message : String(err)}`);
+    const shimAnswer = await prompt.ask("Install Codex autostart shim? [Y/n]: ");
+    if (shimAnswer.trim().toLowerCase() !== "n") {
+      try {
+        const { installCodexShim } = await import("../codex/shim");
+        const result = installCodexShim();
+        console.log(result.installed ? `✅ ${result.message}` : `⚠️  ${result.message}`);
+      } catch (err) {
+        console.log(`⚠️  Codex autostart shim skipped: ${err instanceof Error ? err.message : String(err)}`);
+      }
     }
-  }
 
-  console.log(`\n🚀 Setup complete! Run 'ocx start' to start the proxy.`);
-  prompt.close();
+    console.log(`\n🚀 Setup complete! Run 'ocx start' to start the proxy.`);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (/stdin (closed|reached EOF)/i.test(message)) {
+      console.error(`\n❌ ${message}. Re-run \`ocx init\` in an interactive terminal.`);
+      process.exitCode = 1;
+      return;
+    }
+    throw error;
+  } finally {
+    prompt.close();
+  }
 }