@iislee/opencodex 2.11.0

package/src/cli/claude.ts

@@ -0,0 +1,286 @@
+/**
+ * `ocx claude [claude args...]` — launch Claude Code wired to the local proxy.
+ *
+ * Mirrors `ccr code` UX (devlog/260711_claude_inbound/020, 003 E1/E2/E5/G1):
+ * ensures the proxy is running, injects the Anthropic env slots, then execs the
+ * `claude` CLI with stdio inherited. User-exported env wins except when a stale
+ * loopback opencodex base URL points at a different proxy port.
+ */
+import { spawn } from "node:child_process";
+import { loadConfig } from "../config";
+import { injectClaudeAgentDefs } from "../claude/agents-inject";
+import { effectiveModelEnv, resolveAutoContext } from "../claude/context-windows";
+import { refreshGatewayModelCacheFromProxy } from "../claude/gateway-cache";
+import { commandInvocation } from "../lib/win-exec";
+import { findLiveProxy } from "../server/proxy-liveness";
+import type { OcxConfig } from "../types";
+import { configuredAdminToken } from "../lib/admin-secrets";
+import { PROXY_MARKER, ownAdmissionTokens, defaultAuthDetectDeps, detectClaudeAuth, type AuthDetectDeps } from "../claude/auth-detect";
+import { resolveClaudeAuthMode } from "../claude/auth-mode";
+
+export interface ClaudeLaunchEnv {
+  [key: string]: string | undefined;
+}
+
+/**
+ * Injectable IO for tests. `env` is deliberately NOT injectable: it is bound to the
+ * launch base so detection and the spawned process can never disagree (audit R3-3).
+ */
+export type ClaudeEnvDeps = { authDetect?: Omit<Partial<AuthDetectDeps>, "env" | "ownTokens"> };
+
+/**
+ * Pure env assembly (unit-tested): never sets ANTHROPIC_API_KEY (setting both
+ * token vars triggers Claude Code's auth-conflict warning, 003 E1), and never
+ * overrides variables the user already exported, apart from stale loopback
+ * ANTHROPIC_BASE_URL values owned by a previous opencodex launch.
+ */
+export function buildClaudeEnv(
+  config: OcxConfig,
+  port: number,
+  base: ClaudeLaunchEnv,
+  contextWindows: Record<string, number> = {},
+  deps: ClaudeEnvDeps = {},
+): ClaudeLaunchEnv {
+  const env: ClaudeLaunchEnv = { ...base };
+  // Step 1 — strip OUR OWN dummy from the inherited environment before anything reads
+  // or writes the token slot. setDefault below preserves any non-empty value, so a
+  // stale marker left in place would suppress the admission key and then be removed,
+  // leaving the child with no token at all (audit R2-1). It is opencodex state, never
+  // user auth, so dropping it unconditionally is safe.
+  if (env.ANTHROPIC_AUTH_TOKEN === PROXY_MARKER) delete env.ANTHROPIC_AUTH_TOKEN;
+  // Step 1b — drop Anthropic credentials that the bundled Bun runtime synthesized from a
+  // project `.env`/`.env.local` (issue #701). Claude Code disables claude.ai connectors the
+  // moment either token slot is populated, so an ambient project file silently moved a
+  // subscriber onto API billing while their OAuth login stayed healthy. The npm launcher
+  // runs under Node, which does NOT auto-load dotenv, so it records the slots that existed
+  // before Bun started; anything populated now but absent then came from the working
+  // directory, not from the user. A genuine shell export is still honored, which keeps
+  // auto-mode API-key auth working. An ABSENT marker means provenance is unknowable
+  // (a direct `bun src/cli/index.ts` run, a test, or an older launcher), and then we
+  // change nothing rather than guess — an EMPTY marker is different: the launcher ran
+  // and saw no pre-existing slots.
+  const preBunSlots = base.OCX_PRE_BUN_ANTHROPIC_ENV;
+  if (preBunSlots !== undefined) {
+    const exported = new Set(preBunSlots.split(",").filter(name => name.length > 0));
+    for (const name of ["ANTHROPIC_API_KEY", "ANTHROPIC_AUTH_TOKEN"] as const) {
+      const value = env[name];
+      if (value !== undefined && value !== "" && !exported.has(name)) delete env[name];
+    }
+  }
+  // Never forward the seam itself to Claude Code.
+  delete env.OCX_PRE_BUN_ANTHROPIC_ENV;
+  const setDefault = (name: string, value: string | undefined) => {
+    if (value === undefined || value.length === 0) return;
+    if (env[name] !== undefined && env[name] !== "") return; // user wins
+    env[name] = value;
+  };
+  setDefault("ANTHROPIC_BASE_URL", `http://127.0.0.1:${port}`);
+  const existingBaseUrl = env.ANTHROPIC_BASE_URL;
+  if (existingBaseUrl) {
+    try {
+      const parsed = new URL(existingBaseUrl);
+      const isLoopback = parsed.hostname === "localhost" || parsed.hostname === "127.0.0.1";
+      if (isLoopback && parsed.port !== "" && Number(parsed.port) !== port) {
+        const replacement = `http://127.0.0.1:${port}`;
+        console.error(`⚠ Replacing stale opencodex ANTHROPIC_BASE_URL ${existingBaseUrl} with ${replacement}.`);
+        env.ANTHROPIC_BASE_URL = replacement;
+      }
+    } catch {
+      // Preserve user-provided values that are not parseable URLs.
+    }
+  }
+  // Subscription-preserving default (teamclaude --no-mitm / Vercel gateway pattern):
+  // setting ANTHROPIC_AUTH_TOKEN/API_KEY disables claude.ai connectors and overrides
+  // the user's Claude login. Only inject a token when the proxy actually requires an
+  // admission key; otherwise Claude Code keeps its own OAuth and sends it to us —
+  // native claude models then pass through verbatim (see server/claude-messages.ts).
+  if ((config.apiKeys?.length ?? 0) > 0) {
+    setDefault("ANTHROPIC_AUTH_TOKEN", config.apiKeys![0].key);
+  }
+  // Detection reads the SANITIZED launch env — the exact object spawned below — so the
+  // resolver and the spawned process cannot disagree. It deliberately does NOT read the
+  // raw base: the provenance strip above already removed dotenv-only credentials, and
+  // letting a value the child never receives decide the marker left an auto-mode user
+  // with neither the credential NOR the proxy marker (#701 audit round 2). Injected deps
+  // are spread FIRST and `env` bound LAST, and the injection type excludes `env`, so a
+  // test fake cannot break that. `ownTokens` is bound last for the same reason: it is
+  // config-derived, and a fake that replaced it could make our own admission key look
+  // like user auth.
+  const resolved = resolveClaudeAuthMode(config, detectClaudeAuth({
+    ...defaultAuthDetectDeps(env as NodeJS.ProcessEnv),
+    ...(deps.authDetect ?? {}),
+    env: () => env as NodeJS.ProcessEnv,
+    ownTokens: ownAdmissionTokens(config),
+  }));
+  if (!env.ANTHROPIC_AUTH_TOKEN && resolved.markerMode === "proxy") {
+    env.ANTHROPIC_AUTH_TOKEN = PROXY_MARKER;
+  }
+  if (resolved.origin === "auto-unknown") {
+    console.error("⚠ Claude 인증을 확인하지 못했습니다 — 구독 방식으로 진행합니다. GUI에서 인증 모드를 직접 지정하면 이 판단을 덮어쓸 수 있습니다.");
+  }
+  // NOTE: do NOT set _CLAUDE_CODE_ASSUME_FIRST_PARTY_BASE_URL here. While it enables
+  // Design/Remote Control, it DISABLES gateway model discovery (Claude Code's eligibility
+  // check returns false when isFirstPartyBaseUrl() is true). Model routing through the
+  // proxy is essential; Design/Remote Control are secondary features.
+  // Connectors still work because they check OAuth state ($o()), not base URL (Gd()).
+  // Native /model picker discovery ("From gateway", Claude Code >= 2.1.129).
+  setDefault("CLAUDE_CODE_ENABLE_GATEWAY_MODEL_DISCOVERY", "1");
+  // Host-managed routing guard (devlog 260720_claude_authmode_persist/020): with
+  // this flag in the spawn env, Claude Code strips provider-managed vars
+  // (ANTHROPIC_BASE_URL/AUTH_TOKEN/API_KEY, model slots) from settings-sourced
+  // env (managedEnv.ts), so a leftover cc-switch/CCR ~/.claude/settings.json
+  // env block cannot silently hijack proxy routing away from opencodex.
+  // setDefault: an explicit user export (e.g. =0, isEnvTruthy-false) still wins.
+  // Intentional contract change: settings.env model slots are also stripped in
+  // ocx claude runs — use the top-level settings "model" field or opt out.
+  // Claude Code 2.1.206+ also treats this as a host-auth assertion. Injecting it
+  // without a host token makes a valid claude.ai subscription look logged out,
+  // so the guard is only safe when opencodex actually owns authentication.
+  if (env.ANTHROPIC_AUTH_TOKEN) {
+    setDefault("CLAUDE_CODE_PROVIDER_MANAGED_BY_HOST", "1");
+  }
+  // Opt-in effort forcing (devlog 136 B6): opus-shaped aliases already carry
+  // output_config.effort, so this is OFF unless the user enables it in config.
+  if (config.claudeCode?.alwaysEnableEffort === true) {
+    setDefault("CLAUDE_CODE_ALWAYS_ENABLE_EFFORT", "1");
+  }
+  // Context-window override: the official pair — MAX_CONTEXT_TOKENS alone is ignored
+  // for recognized claude-shaped ids unless DISABLE_COMPACT=1 rides along (devlog 135).
+  const maxCtx = config.claudeCode?.maxContextTokens;
+  if (typeof maxCtx === "number" && Number.isFinite(maxCtx) && maxCtx > 0) {
+    setDefault("CLAUDE_CODE_MAX_CONTEXT_TOKENS", String(Math.floor(maxCtx)));
+    setDefault("DISABLE_COMPACT", "1");
+  }
+  // Auto-context (devlog 260712 020): min(believed window, env) inside the CLI means
+  // one global env acts as a per-model floor — [1m]-marked models compact here while
+  // unmarked (200k-accounted) models keep their default behavior. Inert when the
+  // legacy maxContextTokens pair above is set (resolveAutoContext handles that).
+  // A user-exported value drives the marking predicate too (audit 021 #2) so the
+  // [1m] marker and the compaction threshold can never separate.
+  const userAutoCompact = typeof base.CLAUDE_CODE_AUTO_COMPACT_WINDOW === "string" && base.CLAUDE_CODE_AUTO_COMPACT_WINDOW !== ""
+    ? base.CLAUDE_CODE_AUTO_COMPACT_WINDOW
+    : undefined;
+  const auto = resolveAutoContext(config.claudeCode, userAutoCompact);
+  if (auto.enabled) {
+    setDefault("CLAUDE_CODE_AUTO_COMPACT_WINDOW", String(auto.compactWindow));
+  }
+  // Model slots (devlog 260712 B2): default + four tier defaults + legacy small-fast,
+  // with automatic [1m] context-variant marking when the slot's target model has an
+  // authoritative >=1M window (Claude Code then accounts 1M, compaction preserved).
+  for (const [name, value] of Object.entries(effectiveModelEnv(config.claudeCode, contextWindows, auto))) {
+    setDefault(name, value);
+  }
+  return env;
+}
+
+/**
+ * Context-window map from the RUNNING proxy's management API (warm TTL cache; the
+ * daemon registers every selector form — audit R3#1). 3s bound + management auth header.
+ * (no [1m] marking, conservative).
+ */
+export async function fetchClaudeContextWindows(config: OcxConfig, port: number, timeoutMs = 3_000): Promise<Record<string, number>> {
+  try {
+    const headers = new Headers();
+    const token = configuredAdminToken();
+    if (token) headers.set("x-opencodex-api-key", token);
+    const res = await fetch(`http://127.0.0.1:${port}/api/claude-code`, {
+      headers,
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    if (!res.ok) return {};
+    const body = await res.json() as { contextWindows?: Record<string, number> };
+    return body.contextWindows && typeof body.contextWindows === "object" ? body.contextWindows : {};
+  } catch {
+    console.error("⚠ 모델 컨텍스트 정보를 불러오지 못했습니다 — 1M 자동 표시는 이번 실행에서 생략됩니다.");
+    return {};
+  }
+}
+
+async function ensureProxyForClaude(): Promise<number | null> {
+  const live = await findLiveProxy();
+  if (live) return live.port;
+  const cfgPort = loadConfig().port;
+  const pinPort = typeof cfgPort === "number" && cfgPort > 0 ? cfgPort : 10100;
+  const child = spawn(process.execPath, [process.argv[1], "start", "--port", String(pinPort)], {
+    detached: true,
+    stdio: "ignore",
+    windowsHide: true,
+    env: { ...process.env, OCX_SERVICE: "1" },
+  });
+  child.unref();
+  const deadline = Date.now() + 8_000;
+  while (Date.now() < deadline) {
+    const started = await findLiveProxy();
+    if (started) return started.port;
+    await new Promise(resolve => setTimeout(resolve, 250));
+  }
+  return null;
+}
+
+const CLAUDE_INSTALL_HINT = "❌ `claude` CLI not found. Install it first: npm install -g @anthropic-ai/claude-code";
+
+/**
+ * cmd.exe reports command-not-found as exit 9009 (the win32 launcher routes `.cmd`
+ * shims through cmd.exe, so ENOENT never fires there). Signal exits are not hints.
+ * Devlog 260715_cross_platform_audit/020.
+ */
+export function claudeNotFoundHint(
+  code: number | null,
+  signal: NodeJS.Signals | null,
+  platform: NodeJS.Platform = process.platform,
+): string | null {
+  return platform === "win32" && code === 9009 && !signal ? CLAUDE_INSTALL_HINT : null;
+}
+
+export async function cmdClaude(args: string[]): Promise<number> {
+  const config = loadConfig();
+  if (config.claudeCode?.enabled === false) {
+    console.error("Claude inbound is disabled (config.claudeCode.enabled=false — flip the Claude ON toggle in the GUI or edit config).");
+    return 1;
+  }
+  const port = await ensureProxyForClaude();
+  if (!port) {
+    console.error("❌ Proxy did not become healthy after starting.");
+    return 1;
+  }
+  const contextWindows = await fetchClaudeContextWindows(config, port);
+  const env = buildClaudeEnv(config, port, process.env, contextWindows);
+  // Pre-write the CLI's gateway-model cache (devlog 030): without a token the CLI
+  // never refreshes it, so the picker would keep showing yesterday's aliases.
+  try {
+    const cachePath = await refreshGatewayModelCacheFromProxy(port);
+    if (cachePath === null) {
+      console.error("⚠ Gateway model cache could not be refreshed; the model picker may be stale.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Gateway model cache could not be refreshed: ${message}`);
+  }
+  // Sync roster agents (devlog 070): subagentModels + self -> ~/.claude/agents/ocx-*.md.
+  try {
+    const written = injectClaudeAgentDefs(config, contextWindows);
+    if (written === null) {
+      console.error("⚠ Claude agent definitions could not be synced; check ~/.claude/agents permissions.");
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    console.error(`⚠ Claude agent definitions could not be synced: ${message}`);
+  }
+  return await new Promise<number>(resolve => {
+    const inv = commandInvocation("claude", args);
+    const child = spawn(inv.file, inv.args, { stdio: "inherit", env: env as NodeJS.ProcessEnv, ...inv.options });
+    child.on("error", (err: NodeJS.ErrnoException) => {
+      if (err.code === "ENOENT") {
+        console.error(CLAUDE_INSTALL_HINT);
+      } else {
+        console.error(`❌ Failed to launch claude: ${err.message}`);
+      }
+      resolve(1);
+    });
+    child.on("exit", (code, signal) => {
+      const hint = claudeNotFoundHint(code, signal);
+      if (hint) console.error(hint);
+      resolve(signal ? 1 : code ?? 0);
+    });
+  });
+}

package/src/cli/codex-shim-autorestore.ts

@@ -0,0 +1,45 @@
+import { autoRestoreCodexShim } from "../codex/shim";
+import { codexShimAutoRestoreEnabled, readConfigDiagnostics } from "../config";
+
+export interface CodexShimAutoRestoreCliDeps {
+  env: NodeJS.ProcessEnv;
+  warn: (message: string) => void;
+  restore: typeof autoRestoreCodexShim;
+  readConfig: typeof readConfigDiagnostics;
+}
+
+const DEFAULT_DEPS: CodexShimAutoRestoreCliDeps = {
+  env: process.env,
+  warn: message => console.warn(message),
+  restore: autoRestoreCodexShim,
+  readConfig: readConfigDiagnostics,
+};
+
+export function skipsCodexShimAutoRestore(command: string | undefined, args: string[]): boolean {
+  if (command === "uninstall" || command === "remove") return true;
+  return command === "codex-shim" && ["install", "uninstall", "remove"].includes(args[1] ?? "");
+}
+
+export function maybeAutoRestoreCodexShim(
+  command: string | undefined,
+  args: string[],
+  deps: CodexShimAutoRestoreCliDeps = DEFAULT_DEPS,
+): void {
+  if (skipsCodexShimAutoRestore(command, args)) return;
+  try {
+    const result = deps.restore({
+      enabled: () => codexShimAutoRestoreEnabled(deps.readConfig().config, deps.env),
+    });
+    if (result.status === "restored") {
+      deps.warn(`⚠️  ${result.message} (automatic repair after Codex update)`);
+    } else if ((result.status === "deferred" || result.status === "ineligible") && result.message) {
+      deps.warn(`⚠️  ${result.message}`);
+    }
+  } catch (error) {
+    deps.warn(
+      `⚠️  Codex shim auto-restore failed; continuing without it: ${
+        error instanceof Error ? error.message : String(error)
+      }. Run 'ocx codex-shim install' after the Codex update finishes.`,
+    );
+  }
+}

package/src/cli/combo.ts

@@ -0,0 +1,119 @@
+import {
+  CliUsageError,
+  printData,
+  rejectArgs,
+  runCliAction,
+  runtimeRequest,
+  takeFlag,
+  takeIntegerOption,
+  takeOption,
+  type RuntimeApiDeps,
+} from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx combo [list] [--json]
+  ocx combo show <id> [--json]
+  ocx combo set <id> --targets <provider/model[:weight],...>
+      [--strategy <failover|round-robin>] [--sticky <1-100>]
+      [--effort <low|medium|high|xhigh|max|ultra|->] [--alias <name|->]
+      [--rename-from <id>] [--json]
+  ocx combo remove <id> --yes [--json]`;
+
+type ComboRow = Record<string, unknown> & { id?: string; model?: string };
+
+function parseTargets(value: string): Array<{ provider: string; model: string; weight?: number }> {
+  const targets = value.split(",").map(part => part.trim()).filter(Boolean).map(part => {
+    const colon = part.lastIndexOf(":");
+    let selector = part;
+    let weight: number | undefined;
+    if (colon > part.indexOf("/")) {
+      const maybeWeight = Number(part.slice(colon + 1));
+      if (Number.isInteger(maybeWeight)) {
+        selector = part.slice(0, colon);
+        weight = maybeWeight;
+      }
+    }
+    const slash = selector.indexOf("/");
+    if (slash <= 0 || slash === selector.length - 1) throw new CliUsageError(`invalid target "${part}"; use provider/model[:weight]`, USAGE);
+    const target = { provider: selector.slice(0, slash), model: selector.slice(slash + 1), ...(weight !== undefined ? { weight } : {}) };
+    if (weight !== undefined && (weight < 1 || weight > 10_000)) throw new CliUsageError(`target weight must be 1-10000: ${part}`, USAGE);
+    return target;
+  });
+  if (targets.length === 0) throw new CliUsageError("--targets requires at least one provider/model", USAGE);
+  return targets;
+}
+
+async function list(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const wantsJson = takeFlag(args, "--json");
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const rows = result.combos ?? [];
+  printData(result, wantsJson, rows.length ? rows.map(row => `${String(row.id)}  ${String(row.model ?? `combo/${row.id}`)}`) : ["No combos configured."]);
+}
+
+async function show(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest<{ combos?: ComboRow[] }>("/api/combos", {}, deps);
+  const combo = (result.combos ?? []).find(row => row.id === id);
+  if (!combo) throw new CliUsageError(`unknown combo ${id}`);
+  printData(combo, wantsJson);
+}
+
+async function set(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  const targetsRaw = takeOption(args, "--targets");
+  if (!targetsRaw) throw new CliUsageError("--targets is required", USAGE);
+  const strategy = takeOption(args, "--strategy") ?? "failover";
+  if (strategy !== "failover" && strategy !== "round-robin") throw new CliUsageError("--strategy must be failover or round-robin", USAGE);
+  const stickyLimit = takeIntegerOption(args, "--sticky", { min: 1 }) ?? 1;
+  if (stickyLimit > 100) throw new CliUsageError("--sticky must be <= 100", USAGE);
+  const effort = takeOption(args, "--effort");
+  const alias = takeOption(args, "--alias");
+  const renameFrom = takeOption(args, "--rename-from");
+  rejectArgs(args, USAGE);
+  const combo: Record<string, unknown> = {
+    strategy,
+    stickyLimit,
+    targets: parseTargets(targetsRaw),
+  };
+  if (effort !== undefined) combo.defaultEffort = effort === "-" ? null : effort;
+  if (alias !== undefined) combo.alias = alias === "-" ? "" : alias;
+  const result = await runtimeRequest("/api/combos", {
+    method: "PUT",
+    body: JSON.stringify({ id, combo, ...(renameFrom ? { renameFrom } : {}) }),
+  }, deps);
+  printData(result, wantsJson, [`Saved combo ${id}.`]);
+}
+
+async function remove(argv: string[], deps: RuntimeApiDeps): Promise<void> {
+  const args = [...argv];
+  const id = args.shift()?.trim();
+  const wantsJson = takeFlag(args, "--json");
+  const yes = takeFlag(args, "--yes");
+  if (!id) throw new CliUsageError("combo id is required", USAGE);
+  if (!yes) throw new CliUsageError("remove requires --yes", USAGE);
+  rejectArgs(args, USAGE);
+  const result = await runtimeRequest(`/api/combos?id=${encodeURIComponent(id)}`, { method: "DELETE" }, deps);
+  printData(result, wantsJson, [`Removed combo ${id}.`]);
+}
+
+export async function handleComboCommand(argv: string[], deps: RuntimeApiDeps = {}): Promise<number> {
+  return runCliAction(async () => {
+    const [sub = "list", ...rest] = argv;
+    if (sub === "list") await list(rest, deps);
+    else if (sub === "show") await show(rest, deps);
+    else if (sub === "set" || sub === "create" || sub === "update") await set(rest, deps);
+    else if (sub === "remove" || sub === "delete") await remove(rest, deps);
+    else throw new CliUsageError(`unknown combo command ${sub}`, USAGE);
+  });
+}
+
+export const COMBO_USAGE = USAGE;

package/src/cli/config-command.ts

@@ -0,0 +1,145 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { getConfigPath, readConfigDiagnostics, saveConfig, validateConfigCandidate } from "../config";
+import type { OcxConfig } from "../types";
+import { CliUsageError, printData, rejectArgs, runCliAction, takeFlag } from "./runtime-api";
+
+const USAGE = `Usage:
+  ocx config [show] [--json] [--source]
+  ocx config get <dot.path> [--json]
+  ocx config set <dot.path> <json-or-string> [--json]
+  ocx config unset <dot.path> [--json]
+  ocx config validate [path|-] [--json]
+  ocx config export <path|->
+  ocx config import <path|-> --yes [--json]`;
+
+const SECRET_KEYS = /^(apiKey|key|accessToken|refreshToken|idToken|token|password|clientSecret)$/i;
+const BLOCKED_SEGMENTS = new Set(["__proto__", "prototype", "constructor"]);
+
+function redact(value: unknown, key = ""): unknown {
+  if (SECRET_KEYS.test(key) && typeof value === "string") return value ? "********" : value;
+  if (Array.isArray(value)) return value.map(item => redact(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value as Record<string, unknown>).map(([childKey, child]) => [childKey, redact(child, childKey)]));
+  }
+  return value;
+}
+
+function pathSegments(path: string): string[] {
+  const segments = path.split(".").map(part => part.trim()).filter(Boolean);
+  if (segments.length === 0 || segments.some(part => BLOCKED_SEGMENTS.has(part))) throw new CliUsageError("invalid config path", USAGE);
+  return segments;
+}
+
+function getPath(root: unknown, path: string): unknown {
+  let current = root;
+  for (const segment of pathSegments(path)) {
+    if (!current || typeof current !== "object" || !Object.hasOwn(current, segment)) throw new CliUsageError(`config path not found: ${path}`);
+    current = (current as Record<string, unknown>)[segment];
+  }
+  return current;
+}
+
+function setPath(root: Record<string, unknown>, path: string, value: unknown, remove = false): void {
+  const segments = pathSegments(path);
+  let current = root;
+  for (const segment of segments.slice(0, -1)) {
+    const next = current[segment];
+    if (!next || typeof next !== "object" || Array.isArray(next)) throw new CliUsageError(`config parent path not found: ${segment}`, USAGE);
+    current = next as Record<string, unknown>;
+  }
+  const leaf = segments.at(-1)!;
+  if (remove && !Object.hasOwn(current, leaf)) throw new CliUsageError(`config path not found: ${path}`);
+  if (remove) delete current[leaf];
+  else current[leaf] = value;
+}
+
+function parseValue(raw: string): unknown {
+  try { return JSON.parse(raw); }
+  catch { return raw; }
+}
+
+function loadInput(path: string): unknown {
+  const raw = path === "-" ? readFileSync(0, "utf8") : readFileSync(path, "utf8");
+  try { return JSON.parse(raw); }
+  catch { throw new CliUsageError(`invalid JSON in ${path}`); }
+}
+
+function validate(value: unknown): OcxConfig {
+  const result = validateConfigCandidate(value);
+  if (!result.ok) throw new CliUsageError(result.error);
+  return result.config;
+}
+
+export async function handleConfigCommand(argv: string[]): Promise<number> {
+  return runCliAction(async () => {
+    const args = [...argv];
+    const action = (args.shift() ?? "show").toLowerCase();
+    const wantsJson = takeFlag(args, "--json");
+    if (action === "show") {
+      const source = takeFlag(args, "--source");
+      rejectArgs(args, USAGE);
+      const diagnostics = readConfigDiagnostics();
+      const config = redact(diagnostics.config);
+      const result = source ? { config, source: diagnostics.source, error: diagnostics.error, warnings: diagnostics.warnings ?? [] } : config;
+      printData(result, true);
+      return;
+    }
+    if (action === "get") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("config path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const value = redact(getPath(readConfigDiagnostics().config, path), path.split(".").at(-1));
+      if (wantsJson || typeof value === "object") console.log(JSON.stringify(value, null, 2));
+      else console.log(String(value));
+      return;
+    }
+    if (action === "set" || action === "unset") {
+      const path = args.shift();
+      const raw = action === "set" ? args.shift() : undefined;
+      if (!path || (action === "set" && raw === undefined)) throw new CliUsageError("config path and value are required", USAGE);
+      rejectArgs(args, USAGE);
+      const candidate = structuredClone(readConfigDiagnostics().config) as unknown as Record<string, unknown>;
+      setPath(candidate, path, raw === undefined ? undefined : parseValue(raw), action === "unset");
+      const config = validate(candidate);
+      const savedValue = action === "unset" ? null : getPath(config, path);
+      saveConfig(config);
+      printData({ ok: true, path, value: redact(savedValue, path.split(".").at(-1)) }, wantsJson,
+        [`${action === "unset" ? "Unset" : "Set"} ${path}.`]);
+      return;
+    }
+    if (action === "validate") {
+      const path = args.shift();
+      rejectArgs(args, USAGE);
+      const result = path ? validateConfigCandidate(loadInput(path)) : (() => {
+        const diagnostics = readConfigDiagnostics();
+        return diagnostics.error ? { ok: false as const, error: diagnostics.error } : { ok: true as const, config: diagnostics.config };
+      })();
+      printData(result.ok ? { ok: true, source: path ?? getConfigPath() } : result, wantsJson,
+        [result.ok ? "Config is valid." : `Config is invalid: ${result.error}`]);
+      if (!result.ok) process.exitCode = 1;
+      return;
+    }
+    if (action === "export") {
+      const path = args.shift();
+      if (!path) throw new CliUsageError("export path is required", USAGE);
+      rejectArgs(args, USAGE);
+      const content = `${JSON.stringify(readConfigDiagnostics().config, null, 2)}\n`;
+      if (path === "-") process.stdout.write(content);
+      else { writeFileSync(path, content, { encoding: "utf8", mode: 0o600 }); console.log(`Exported config to ${path}.`); }
+      return;
+    }
+    if (action === "import") {
+      const path = args.shift();
+      const yes = takeFlag(args, "--yes");
+      if (!path) throw new CliUsageError("import path is required", USAGE);
+      if (!yes) throw new CliUsageError("import requires --yes", USAGE);
+      rejectArgs(args, USAGE);
+      saveConfig(validate(loadInput(path)));
+      printData({ ok: true, source: path }, wantsJson, [`Imported config from ${path}. Restart or run ocx sync if needed.`]);
+      return;
+    }
+    throw new CliUsageError(`unknown config command ${action}`, USAGE);
+  });
+}
+
+export const CONFIG_USAGE = USAGE;