@yansigit/opencodex 2.31.0

package/src/cli/ensure-desired-integrations.ts

@@ -0,0 +1,152 @@
+/**
+ * Align Grok and Claude Desktop files with the durable switches during `ocx ensure`.
+ *
+ * handleEnsure used to load config once, then health-probe / model-sync / spawn,
+ * and only afterwards mutate ~/.grok/config.toml and the Desktop library from
+ * that snapshot. An OFF→ON flip in that window stripped a freshly enabled fence
+ * or deleted a freshly applied Desktop profile; ON→OFF rewrote the files the
+ * user had just turned off. Re-read persisted desired state immediately before
+ * each external-file mutation, and use that current config for sync inputs.
+ */
+import { loadConfig } from "../config";
+import { stripGrokConfig, type GrokInjectResult } from "../grok/inject";
+import { removeDesktop3pStandardPivot } from "../claude/desktop-3p";
+import {
+  claudeDesktopIntegrationEnabled,
+  shouldSyncGrokOnStart,
+} from "../codex/desired-state";
+import type { OcxConfig } from "../types";
+
+export function grokSyncFailureMessage(err: unknown): string {
+  const detail = err instanceof Error ? err.message : String(err);
+  return `Grok Build config sync failed: ${detail}. `
+    + "~/.grok/config.toml may still point at a previous proxy port — "
+    + "run 'ocx ensure' (or apply from the dashboard's Grok page) to repoint it.";
+}
+
+export interface EnsureDesiredIntegrationsDeps {
+  loadConfig: () => OcxConfig;
+  stripGrokConfig: typeof stripGrokConfig;
+  syncGrokConfig: (
+    port: number,
+    config: OcxConfig,
+    opts?: { hostname?: string },
+  ) => Promise<GrokInjectResult>;
+  removeDesktop3pStandardPivot: typeof removeDesktop3pStandardPivot;
+  log?: (message: string) => void;
+  error?: (message: string) => void;
+}
+
+async function defaultSyncGrokConfig(
+  port: number,
+  config: OcxConfig,
+  opts: { hostname?: string } = {},
+): Promise<GrokInjectResult> {
+  const { syncGrokConfig } = await import("../grok/sync");
+  return syncGrokConfig(port, config, opts);
+}
+
+const productionDeps: EnsureDesiredIntegrationsDeps = {
+  loadConfig,
+  stripGrokConfig,
+  syncGrokConfig: defaultSyncGrokConfig,
+  removeDesktop3pStandardPivot,
+};
+
+function io(deps: EnsureDesiredIntegrationsDeps): {
+  log: (message: string) => void;
+  error: (message: string) => void;
+} {
+  return {
+    log: deps.log ?? (message => console.log(message)),
+    error: deps.error ?? (message => console.error(message)),
+  };
+}
+
+/**
+ * Keep ~/.grok/config.toml aligned with the durable Grok switch.
+ *
+ * `handleStart` already gates inject on `shouldSyncGrokOnStart`. `ocx ensure`
+ * used to call `syncGrokConfig` unconditionally, so a dashboard/update/restart
+ * path that lands in ensure rewrote the fence while the switch stayed OFF.
+ * When the switch is OFF, strip any leftover managed block instead of injecting.
+ */
+export async function ensureGrokFenceMatchesDesired(
+  port: number,
+  opts: { hostname?: string } = {},
+  deps: EnsureDesiredIntegrationsDeps = productionDeps,
+): Promise<void> {
+  const config = deps.loadConfig();
+  const { log, error } = io(deps);
+  if (!shouldSyncGrokOnStart(config)) {
+    try {
+      const grok = deps.stripGrokConfig();
+      if (grok.changed) log(`   ↩️  ${grok.message}`);
+      else if (!grok.ok) error(`⚠️  ${grok.message}`);
+    } catch (err) {
+      error(`⚠️  ${grokSyncFailureMessage(err)}`);
+    }
+    return;
+  }
+  try {
+    const hostname = opts.hostname ?? config.hostname;
+    const g = await deps.syncGrokConfig(
+      port,
+      config,
+      hostname !== undefined ? { hostname } : {},
+    );
+    if (g.changed) log("   + Grok Build config updated (~/.grok/config.toml)");
+    else if (!g.ok) error(`⚠️  ${g.message}`);
+  } catch (err) {
+    error(`⚠️  ${grokSyncFailureMessage(err)}`);
+  }
+}
+
+/**
+ * When Claude Desktop is durably OFF, clear any leftover owned gateway profile.
+ * ensure/update used to leave Claude-3p residue in place after a failed disable
+ * (drifted fingerprint), so the Integrations card kept looking applied/stale.
+ */
+export function ensureClaudeDesktopMatchesDesired(
+  deps: EnsureDesiredIntegrationsDeps = productionDeps,
+): void {
+  const config = deps.loadConfig();
+  const { log, error } = io(deps);
+  if (claudeDesktopIntegrationEnabled(config)) return;
+  try {
+    const removed = deps.removeDesktop3pStandardPivot({
+      appliedFingerprint: config.claudeCode?.desktopProfile?.appliedFingerprint ?? null,
+    });
+    if (removed.ok && removed.changed) {
+      log("   ↩️  Claude Desktop integration residue removed.");
+    } else if (!removed.ok) {
+      error(`⚠️  Claude Desktop cleanup skipped: ${removed.reason ?? removed.kind}.`);
+    }
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    error(`⚠️  Claude Desktop cleanup failed: ${detail}.`);
+  }
+}
+
+export type EnsureDesiredIntegrationsBranch =
+  | { kind: "live"; hostname?: string }
+  | { kind: "spawned" };
+
+/**
+ * Reconcile the two external integration files after either ensure race window.
+ * Only the live proxy's observed bind host crosses this boundary; persisted
+ * config is deliberately loaded inside each mutation helper.
+ */
+export async function reconcileEnsureDesiredIntegrations(
+  port: number,
+  branch: EnsureDesiredIntegrationsBranch,
+  deps: EnsureDesiredIntegrationsDeps = productionDeps,
+): Promise<void> {
+  const liveHost = branch.kind === "live" ? branch.hostname : undefined;
+  await ensureGrokFenceMatchesDesired(
+    port,
+    liveHost ? { hostname: liveHost } : {},
+    deps,
+  );
+  ensureClaudeDesktopMatchesDesired(deps);
+}

package/src/cli/export-command.ts

@@ -0,0 +1,213 @@
+/**
+ * `ocx export --client <id>` — print a client config for the live proxy.
+ *
+ * Eight clients, four formats: OpenCode and Pi are JSON; OMP, Hermes, Gajae and
+ * MiniMax Code are YAML; OpenClaw is JSON5; Kimi is TOML.
+ *
+ * Two consumers, one payload (devlog 260731_client_config_export/020):
+ *
+ * - **Agent** (`--json`): stdout is exactly the client config as JSON and nothing else,
+ *   so `ocx export --client pi --json > models.json` is safe to pipe. This is JSON for
+ *   every client, including the YAML/JSON5/TOML ones — the flag is about machine
+ *   readability, not the client's native format. Every diagnostic — including the
+ *   `--out` write note — goes to stderr.
+ * - **Human** (no flag) and `--out`: the client's NATIVE serialization 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 — or, for Kimi, which cannot hold one, a
+ * loopback placeholder — and the real key stays in the environment.
+ */
+import { writeFileSync } from "node:fs";
+import { loadConfig } from "../config";
+import {
+  EXPORT_CLIENTS,
+  EXPORT_CLIENT_IDS,
+  buildClientConfigText,
+  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[];
+  reasoningEfforts?: string[];
+  defaultReasoningEffort?: 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 metadata = new Map<string, Pick<ExportModel, "inputModalities" | "reasoningEfforts" | "defaultReasoningEffort">>();
+  for (const row of rows) {
+    const namespaced = row.namespaced?.trim();
+    if (!namespaced || metadata.has(namespaced)) continue;
+    metadata.set(namespaced, {
+      ...(Array.isArray(row.inputModalities) && row.inputModalities.length > 0
+        ? { inputModalities: [...row.inputModalities] }
+        : {}),
+      ...(Array.isArray(row.reasoningEfforts) && row.reasoningEfforts.length > 0
+        ? { reasoningEfforts: [...row.reasoningEfforts] }
+        : {}),
+      ...(typeof row.defaultReasoningEffort === "string" && row.defaultReasoningEffort.length > 0
+        ? { defaultReasoningEffort: row.defaultReasoningEffort }
+        : {}),
+    });
+  }
+  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;
+    Object.assign(model, metadata.get(entry.namespaced));
+    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);
+    // The text is the client's OWN format — YAML, TOML and JSON5 clients would
+    // otherwise receive a JSON rendering their parser reads differently.
+    const built = buildClientConfigText(client, { baseUrl: proxyV1BaseUrl(root), models, config });
+    const clientConfig = built.document;
+    const text = built.text;
+
+    // Every serializer already ends with exactly one newline.
+    if (out !== undefined) writeExport(out, text, force);
+    // stderr, so `--json` stdout stays a standalone JSON document.
+    if (out !== undefined && wantsJson) console.error(`Wrote ${out}`);
+
+    const degraded = models.filter(model => !hasContextLimit(model)).length;
+    // `--json` keeps emitting the DOCUMENT at the top level as JSON for scripts;
+    // `--out` is the path that writes the selected client's native format.
+    // Format metadata rides in the human lines below.
+    printData(clientConfig, wantsJson, [
+      text.trimEnd(),
+      "",
+      ...(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

@@ -0,0 +1,101 @@
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findCommand } from "./registry";
+
+const repoRoot = dirname(fileURLToPath(new URL("../../package.json", import.meta.url)));
+
+function packageVersion(): string {
+  const raw = readFileSync(join(repoRoot, "package.json"), "utf8");
+  const parsed = JSON.parse(raw) as { version?: unknown };
+  return typeof parsed.version === "string" ? parsed.version : "unknown";
+}
+
+export function printVersion(): void {
+  console.log(`opencodex ${packageVersion()}`);
+}
+
+export function printUsage(): void {
+  console.log(`opencodex (ocx) — Universal provider proxy for Codex
+
+Usage:
+  ocx setup                   Interactive setup (alias: init)
+  ocx start [--port <port>]   Start the proxy server (auto-syncs models to Codex)
+  ocx stop                    Stop the proxy AND restore native Codex (plain codex works again)
+  ocx restore                 Restore native Codex without stopping (alias: eject)
+  ocx restore back            Re-point codex at the running proxy (undo restore)
+  ocx recover-history --legacy-openai
+                               Explicitly recover pre-backup syncResumeHistory rows
+  ocx uninstall               Remove service/shim/config and restore native Codex (alias: remove)
+  ocx service [sub]           Run as a background service (default: install/update/start)
+  ocx codex-shim <sub>        Auto-start proxy when \`codex\` launches (install|status|uninstall|remove)
+  ocx tray <sub>              Windows status tray (install|start|stop|status|uninstall)
+  ocx ensure                  Ensure the proxy is running and Codex config/cache are current
+  ocx sync [--restart-codex]  Fetch models from providers and inject into Codex config
+  ocx sync-cache [--restart-codex]
+                              Refresh Codex's model cache from the active catalog
+  ocx status                  Check proxy server status
+  ocx doctor                  Diagnose environment/network issues (WSL, proxy, ChatGPT reachability)
+  ocx doctor --reclaim-response-temps
+                              Reclaim abandoned response-state temp files (works without a running proxy)
+  ocx doctor --recover-zero-byte-coordinator --yes
+                              Back up a proven zero-byte Codex coordinator after stopping the proxy
+  ocx debug <scope>           provider/usage/injection/claude on|off|status|reset
+  ocx login <provider>        OAuth or API-key provider login
+  ocx logout <provider>       Remove a stored OAuth login
+  ocx gui                     Open the opencodex dashboard
+  ocx update [--tag <tag>]    Update opencodex (keeps preview installs on @preview)
+  ocx restart                  Stop and restart the proxy
+  ocx v2 <sub>                multi_agent_v2 surface (status|on|off|mode|keep-native-v1|threads|mode-hint)
+  ocx health [--json]          Check proxy health (exit 0=healthy, 1=not)
+  ocx ready [--json] [--wait [--timeout <s>]]  Check post-sync readiness (exit 0 only when ready)
+  ocx provider <sub>          Providers, connectivity, quota, and selected models
+  ocx account <sub>           Accounts, login/reauth, key pools, and quota controls
+  ocx models <sub>            Live/custom models, visibility, context, and shadow calls
+  ocx combo <sub>             Combo failover/round-robin routing
+  ocx agent <sub>             Subagents, roles, injection, effort caps, and sidecars
+  ocx observe <sub>           Logs, usage, storage, memory, and debug data
+  ocx route <sub>             Routing features (combo, policy)
+  ocx logs [filters]          Alias of ocx observe logs
+  ocx usage [--range <7d|30d|all>]  Alias of ocx observe usage
+  ocx storage [--json]        Alias of ocx observe storage
+  ocx memory [--json]         Alias of ocx observe memory
+  ocx api-key <sub>           Alias of ocx access key
+  ocx access <sub>            External API keys and endpoint information
+  ocx export --client <id>    Print a client config wired to the running proxy (11 clients)
+  ocx integration client <sub> Enable, disable, inspect or roll back a client integration
+  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
+  ocx lab <sub>               Read-only Compatibility Lab projection inspection
+  ocx claude [args...]        Launch Claude Code wired to the proxy (model discovery on)
+  ocx claude desktop [sub]    Manage and apply Claude Desktop's four-family profile
+  ocx opencode [args...]      Launch opencode wired to the proxy (runtime provider config)
+  ocx mcode [args...]         Launch MiniMax Code through its managed provider
+  ocx mmx text <sub> [args]   Launch MiniMax CLI text through the proxy
+  ocx zcode [sub]             Connect ZCode to the proxy (managed provider)
+  ocx help [command]          Show help
+  ocx --version | -v          Print version
+
+Examples:
+  ocx init                    Set up provider and inject into Codex
+  ocx start                   Start on default port (10100)
+  ocx start --port 8080       Start on custom port
+  ocx help service            Show service command help
+  ocx sync                    Sync available models to Codex`);
+}
+
+export function hasHelpFlag(values: string[]): boolean {
+  return values.some(value => value === "--help" || value === "-h" || value === "help");
+}
+
+export function printSubcommandUsage(name: string | undefined): void {
+  const entry = name ? findCommand(name) : undefined;
+  if (!entry) {
+    console.error(`Unknown command: ${name ?? ""}`.trim());
+    printUsage();
+    process.exit(1);
+  }
+  console.log(`Usage: ${entry.usage}\n\n${entry.summary}`);
+  if (entry.details?.length) console.log(`\n${entry.details.join("\n")}`);
+}