@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
173 lines (168 loc) • 8.55 kB
text/typescript
/**
* CLI head: version/help early exits, ready/resolve pre-parse, lifecycle version
* notice, then bounded Codex-shim auto-restore preflight (Phase 1 of the CLI
* deepening — moved out of src/cli/index.ts).
*
* `parseCliHead` is pure (no I/O, no process access) so the ordering and the
* single-parse contract are unit-testable without a subprocess. `runCli` owns
* the exit paths and the shim preflight, then returns the dispatchable head
* for the command switch in src/cli/index.ts.
*/
import { printFullUsage, printSubcommandUsage, printUsage, printVersion } from "./help";
import { parseReadyArgs, type ReadyArgs } from "./ready";
import { parseResolveArgs, type ResolveArgs } from "./resolve";
import { parseStopApproval } from "./stop-approval";
import { parseSyncExpectation, SYNC_EXPECTATION_USAGE_EXIT } from "./sync-expectation";
import { parseSyncFanoutFlags } from "./sync-flags";
import { maybeAutoRestoreCodexShimAsync } from "./codex-shim-autorestore";
import { findCommand } from "./registry";
import { printUnknownCommand } from "./help-recovery";
import { noteCredentialArgv, redactSecretArgs } from "./secret-args";
import { maybeNoticeVersionSkew } from "./version-skew-notice";
import { settleConfigRootForCli } from "./config-root-startup";
import { isOrchestratedUpdateArgv } from "../update/orchestrated-arguments.mjs";
export interface CliHead {
kind: "version" | "help" | "ready" | "resolve" | "command";
command: string | undefined;
args: string[];
/** For kind "help": the subcommand whose usage should print, if any. */
helpTarget?: string;
/** Explicit multi-token help topic; never passed to command execution. */
helpPath?: string[];
/** Complete static reference requested from root help. */
helpAll?: boolean;
/** Present only for `ready`; undefined when the ready args failed to parse. */
readyArgs?: ReadyArgs;
/** Present only for `resolve`; undefined when the resolve args failed to parse. */
resolveArgs?: ResolveArgs;
}
export function parseCliHead(argv: string[]): CliHead {
const command = argv[0];
const args = argv;
// Codex owns its forwarded grammar; wrapper documentation is `ocx help codex`.
if (command === "codex") return { kind: "command", command, args };
if (command === "update" && isOrchestratedUpdateArgv(args.slice(1))) return { kind: "command", command, args };
if (command === "--version" || command === "-v" || command === "version") {
return { kind: "version", command, args };
}
const boundary = argv.indexOf("--");
const prefix = boundary < 0 ? argv : argv.slice(0, boundary);
const rootHelp = command === undefined || command === "help" || command === "--help" || command === "-h";
const commandHelp = prefix[1] === "help";
if (rootHelp || commandHelp || prefix.slice(1).some(value => value === "--help" || value === "-h")) {
const topic = rootHelp ? prefix.slice(1)
: commandHelp ? [command!, ...prefix.slice(2)] : prefix;
// Options and their operands are not part of a help topic. Keep argv intact.
const option = topic.findIndex((value, index) => value.startsWith("-")
&& (index > 0 || (rootHelp && ["--all", "--help", "-h"].includes(value))));
const path = option < 0 ? topic : topic.slice(0, option);
return {
kind: "help",
command,
args,
...(path.length ? { helpTarget: path[0] } : {}),
...(path.length > 1 ? { helpPath: path } : {}),
...(rootHelp && path.length === 0 && prefix.includes("--all") ? { helpAll: true } : {}),
};
}
// P1: pre-parse `ocx ready` and reject invalid arguments with exit 64 BEFORE
// maybeAutoRestoreCodexShimAsync (or any discovery/probe/filesystem-capable global
// preflight) runs. `ready --help` / `help ready` already exited above, so this
// only sees ready args without a help flag. Valid args are stashed so the
// switch dispatch can call runReady without a second parse.
if (command === "ready") {
const parsed = parseReadyArgs(args.slice(1));
if (!parsed.ok) return { kind: "ready", command, args, readyArgs: undefined };
return { kind: "ready", command, args, readyArgs: parsed.args };
}
// Same ordering contract as `ready`: `ocx resolve` rejects any argument with exit
// 64 BEFORE maybeAutoRestoreCodexShimAsync (or any other preflight with side effects) runs.
if (command === "resolve") {
const parsed = parseResolveArgs(args.slice(1));
if (!parsed.ok) return { kind: "resolve", command, args, resolveArgs: undefined };
return { kind: "resolve", command, args, resolveArgs: parsed.args };
}
return { kind: "command", command, args };
}
export function uninstallArgsError(command: string | undefined, args: string[]): string | undefined {
if ((command !== "uninstall" && command !== "remove") || args.length <= 1) return undefined;
return `ocx ${command} does not accept arguments (got: ${redactSecretArgs(args.slice(1)).join(" ")}). No changes were made. See: ocx help ${command}`;
}
export async function runCli(argv: string[]): Promise<CliHead> {
noteCredentialArgv(argv);
const head = parseCliHead(argv);
switch (head.kind) {
case "version":
printVersion();
process.exit(0);
case "help": {
if (head.helpAll) printFullUsage();
else if (head.helpTarget) printSubcommandUsage(head.helpTarget, head.helpPath, {
fallbackToParent: head.command !== "help" && head.command !== "--help"
&& head.command !== "-h" && head.args[1] !== "help",
});
else printUsage();
process.exit(0);
}
case "ready": {
// Fail-closed impossible-state guard: parseCliHead already ran the
// pre-parse before any shim/preflight side effect, so reaching here
// without readyArgs means dispatch diverged. Refuse with code 64 and
// perform NO I/O (no discovery/probe).
if (!head.readyArgs) {
console.error("Usage: ocx ready [--json] [--wait [--timeout <seconds>]]");
console.error(" --timeout requires --wait; <seconds> must be a positive integer (1..300).");
console.error(" Default wait timeout is 45 seconds.");
process.exit(64);
}
await maybeAutoRestoreCodexShimAsync(head.command, head.args);
return head;
}
case "resolve": {
// Fail-closed impossible-state guard, mirroring ready: the pre-parse above already
// rejected invalid arguments before any preflight, so a missing resolveArgs means
// dispatch diverged. Refuse with code 64 and perform NO I/O.
if (!head.resolveArgs) {
console.error("Usage: ocx resolve [--json]");
console.error(" --json prints one JSON document: the config home, the effective port,");
console.error(" and the identity-checked liveness verdict.");
process.exit(64);
}
await maybeAutoRestoreCodexShimAsync(head.command, head.args);
return head;
}
case "command":
if (head.command !== "internal" && !findCommand(head.command ?? "")) {
printUnknownCommand(head.command);
process.exit(1);
}
if (head.command === "stop" && !parseStopApproval(head.args.slice(1)).ok) {
console.error("Usage: ocx stop [--deadline-ms <ms>] [--json [--expect-pid <pid> --expect-port <port> --expect-hostname <host> --expect-config-home <home> --expect-cli-version <version> --expect-compatibility-token <hex>]]");
process.exit(64);
}
const uninstallError = uninstallArgsError(head.command, head.args);
if (uninstallError) {
console.error(uninstallError);
process.exit(2);
}
// #7694: a malformed pinned sync is refused before any preflight reads or repairs anything.
if (head.command === "sync") {
const flags = parseSyncFanoutFlags(head.args.slice(1));
if (!flags.ok) {
console.error(flags.message);
process.exit(SYNC_EXPECTATION_USAGE_EXIT);
}
const pinned = parseSyncExpectation(head.args.slice(1));
if (!pinned.ok) {
console.error(pinned.message);
process.exit(SYNC_EXPECTATION_USAGE_EXIT);
}
}
// Before any preflight or command write: wait once for the config-root ACL flight (#7815).
// Commands skipsCodexShimAutoRestore exempts are skipped there too; see config-root-startup.
await settleConfigRootForCli(head.command, head.args);
await maybeNoticeVersionSkew(head.command, head.args);
await maybeAutoRestoreCodexShimAsync(head.command, head.args);
return head;
}
}