@bjoernrochel/sevro 0.1.0-rc.8 → 1.0.0

package/src/{cli-invocation.ts → cli/invocation.ts}

@@ -1,26 +1,24 @@
-import { parseArgs } from "node:util";
-import { isAbsolute } from "node:path";
+import { join, resolve } from "node:path";
+import { validQualifiedId } from "../value-guards";
+import { canonicalRuntimeRoot } from "../runtime/paths";
+import {
+  PATH_OPTIONS,
+  PATH_LIST_OPTIONS,
+  EXTENSION_OPTIONS,
+  RUN_OPTIONS,
+  optionsWith,
+  runArguments,
+} from "./run-options";
+import { savedRunValues } from "./run-manifest";
 
 export class InvocationError extends Error {}
 
 function requiredOption(value: string | undefined, name: string): string {
-  if (!value) throw new InvocationError(`missing ${name}`);
+  if (!value)
+    throw new InvocationError(`missing ${name}; supply ${name} with a value`);
   return value;
 }
 
-function absoluteOption(value: string | undefined, name: string): string {
-  const path = requiredOption(value, name);
-  if (!isAbsolute(path)) throw new InvocationError(`${name} must be absolute`);
-  return path;
-}
-
-function optionalAbsolute(
-  value: string | undefined,
-  name: string,
-): string | undefined {
-  return value ? absoluteOption(value, name) : undefined;
-}
-
 function optionalDigest(value: string | undefined, name: string) {
   if (value !== undefined && !/^[a-f0-9]{64}$/.test(value))
     throw new InvocationError(`${name} must be a 64-character SHA-256 digest`);
@@ -30,71 +28,16 @@ function optionalDigest(value: string | undefined, name: string) {
 function conditionOption(value: string | undefined): "passive" | "enforced" {
   const condition = requiredOption(value, "--condition");
   if (condition !== "passive" && condition !== "enforced")
-    throw new InvocationError("invalid --condition");
+    throw new InvocationError("invalid --condition; use passive or enforced");
   return condition;
 }
 
-const RUN_OPTIONS = {
-  json: { type: "boolean" },
-  dry: { type: "boolean" },
-  "case-file": { type: "string" },
-  "case-id": { type: "string" },
-  "extension-command-file": { type: "string" },
-  "extension-source-file": { type: "string", multiple: true },
-  "extension-configuration-file": { type: "string" },
-  "extension-redacted-configuration-file": { type: "string" },
-  "task-verdict-policy": { type: "string" },
-  "replace-builtin-grader": { type: "string", multiple: true },
-  "case-source-root": { type: "string" },
-  "case-source-map-file": { type: "string" },
-  "adapter-module": { type: "string" },
-  "semantic-adapter-module": { type: "string" },
-  "semantic-host": { type: "string" },
-  "semantic-model": { type: "string" },
-  "semantic-effort": { type: "string" },
-  "advisory-adapter-module": { type: "string" },
-  "advisory-host": { type: "string" },
-  "advisory-model": { type: "string" },
-  "advisory-effort": { type: "string" },
-  "advisory-exclude": { type: "string", multiple: true },
-  host: { type: "string" },
-  "codex-bin": { type: "string" },
-  "codex-entrypoint": { type: "string" },
-  "codex-timeout-ms": { type: "string" },
-  "codex-auth-file": { type: "string" },
-  "claude-bin": { type: "string" },
-  "claude-credential-file": { type: "string" },
-  "claude-uv-cache-dir": { type: "string" },
-  "claude-project-settings": { type: "boolean" },
-  "toolchain-bin-dir": { type: "string" },
-  model: { type: "string" },
-  effort: { type: "string" },
-  "shell-isolation": { type: "boolean" },
-  "protected-root": { type: "string", multiple: true },
-  "project-root": { type: "string" },
-  "config-root": { type: "string" },
-  "runtime-config-file": { type: "string" },
-  "results-root": { type: "string" },
-  "run-state-root": { type: "string" },
-  "runner-build-digest": { type: "string" },
-  "runner-checkout-root": { type: "string" },
-  "project-digest": { type: "string" },
-  condition: { type: "string" },
-  trials: { type: "string" },
-  jobs: { type: "string", default: "3" },
-  threshold: { type: "string" },
-} as const;
-
 function cliArguments(argv: string[]) {
   try {
-    return parseArgs({
-      args: argv,
-      allowPositionals: true,
-      strict: true,
-      options: RUN_OPTIONS,
-    });
+    return runArguments(argv);
   } catch (cause) {
-    throw new InvocationError("invalid CLI arguments", { cause });
+    const detail = cause instanceof Error ? `: ${cause.message}` : "";
+    throw new InvocationError(`invalid CLI arguments${detail}`, { cause });
   }
 }
 
@@ -112,24 +55,29 @@ function trialParameters(values: Values) {
     passThreshold <= 0 ||
     passThreshold > 1
   )
-    throw new InvocationError("invalid --threshold");
+    throw new InvocationError(
+      "invalid --threshold; supply a number greater than 0 and at most 1",
+    );
   return { condition, trialCount, jobs, passThreshold };
 }
 
 function positiveInteger(value: number, option: string): void {
   if (!Number.isSafeInteger(value) || value < 1)
-    throw new InvocationError(`invalid ${option}`);
+    throw new InvocationError(`invalid ${option}; supply a positive integer`);
 }
 
 function hostRoutes(values: Values) {
   const codex = values.host === "codex";
   const claude = values.host === "claude";
+  const semanticCodex = values["semantic-host"] === "codex";
+  const advisoryCodex = values["advisory-host"] === "codex";
   return {
     codex,
     claude,
     builtinHost: codex || claude,
-    semanticCodex: values["semantic-host"] === "codex",
-    advisoryCodex: values["advisory-host"] === "codex",
+    semanticCodex,
+    advisoryCodex,
+    anyCodex: codex || semanticCodex || advisoryCodex,
   };
 }
 
@@ -147,15 +95,15 @@ const HOST_COMPATIBILITY: CompatibilityRule[] = [
   },
   {
     invalid: (v, r) => v.host && !r.builtinHost,
-    message: "unsupported --host",
+    message: "unsupported --host; use codex or claude",
   },
   {
     invalid: (v, r) => v["semantic-host"] && !r.semanticCodex,
-    message: "unsupported --semantic-host",
+    message: "unsupported --semantic-host; use codex",
   },
   {
     invalid: (v, r) => v["advisory-host"] && !r.advisoryCodex,
-    message: "unsupported --advisory-host",
+    message: "unsupported --advisory-host; use codex",
   },
   {
     invalid: (v, r) => r.semanticCodex && v["semantic-adapter-module"],
@@ -195,24 +143,11 @@ const HOST_COMPATIBILITY: CompatibilityRule[] = [
     message: "--advisory-exclude requires an advisory route",
   },
   {
-    invalid: (v, r) =>
-      !r.codex &&
-      !r.semanticCodex &&
-      !r.advisoryCodex &&
-      [
-        v["codex-bin"],
-        v["codex-auth-file"],
-        v["codex-timeout-ms"] !== undefined,
-      ].some(Boolean),
+    invalid: (v, r) => !r.anyCodex && hasRouteOptions(v, "codex"),
     message: "Codex options require a Codex host route",
   },
   {
-    invalid: (v, r) =>
-      !r.claude &&
-      (v["claude-bin"] ||
-        v["claude-credential-file"] ||
-        v["claude-uv-cache-dir"] ||
-        v["claude-project-settings"]),
+    invalid: (v, r) => !r.claude && hasRouteOptions(v, "claude"),
     message: "Claude options require --host claude",
   },
   {
@@ -226,6 +161,13 @@ const HOST_COMPATIBILITY: CompatibilityRule[] = [
   },
 ];
 
+function hasRouteOptions(values: Values, route: "codex" | "claude"): boolean {
+  return optionsWith("route", route).some((name) => {
+    if (RUN_OPTIONS[name].kind === "number") return values[name] !== undefined;
+    return Boolean(values[name]);
+  });
+}
+
 function validateHostCompatibility(
   values: Values,
   routes: Routes,
@@ -237,24 +179,20 @@ function validateHostCompatibility(
 }
 
 function rootParameters(values: Values) {
-  const projectRoot = absoluteOption(values["project-root"], "--project-root");
+  const projectRoot = requiredOption(values["project-root"], "--project-root");
   const configRoot =
     values["config-root"] !== undefined
-      ? absoluteOption(values["config-root"], "--config-root")
+      ? requiredOption(values["config-root"], "--config-root")
       : projectRoot;
-  const resultsRoot = absoluteOption(values["results-root"], "--results-root");
+  const resultsRoot = requiredOption(values["results-root"], "--results-root");
   const runStateRoot = values["run-state-root"]
-    ? absoluteOption(values["run-state-root"], "--run-state-root")
+    ? requiredOption(values["run-state-root"], "--run-state-root")
     : resultsRoot;
   return { projectRoot, configRoot, resultsRoot, runStateRoot };
 }
 
 type Roots = ReturnType<typeof rootParameters>;
 
-function validQualifiedId(id: string): boolean {
-  return /^[a-z][a-z0-9]*(?:[.-][a-z0-9]+)+$/.test(id);
-}
-
 function validateExtensionSelection(values: Values): void {
   const policy = values["task-verdict-policy"];
   if (policy !== undefined && !validQualifiedId(policy))
@@ -280,24 +218,18 @@ function validateReplacements(replacements: string[]): void {
 }
 
 function hasExtensionArguments(values: Values): boolean {
-  return (
-    [
-      values["case-id"],
-      values["extension-source-file"],
-      values["extension-configuration-file"],
-      values["extension-redacted-configuration-file"],
-    ].some(Boolean) ||
-    values["task-verdict-policy"] !== undefined ||
-    (values["replace-builtin-grader"] ?? []).length > 0
-  );
+  return EXTENSION_OPTIONS.some((name) => {
+    const value = values[name];
+    if (Array.isArray(value)) return value.length > 0;
+    if (name === "task-verdict-policy") return value !== undefined;
+    return Boolean(value);
+  });
 }
 
 function extensionSources(values: Values): string[] {
   const sources = values["extension-source-file"];
   if (!sources?.length)
     throw new InvocationError("missing --extension-source-file");
-  if (sources.some((path) => !isAbsolute(path)))
-    throw new InvocationError("--extension-source-file must be absolute");
   return sources;
 }
 
@@ -334,42 +266,36 @@ function privateRootDeclarations(
   return [
     configRoot,
     ...protectedRoots,
-    values["claude-credential-file"],
-    values["codex-auth-file"],
-    values["runtime-config-file"],
-    values["case-file"],
-    values["extension-command-file"],
-    ...(values["extension-source-file"] ?? []),
-    values["extension-configuration-file"],
-    values["extension-redacted-configuration-file"],
-    values["case-source-root"],
-    values["case-source-map-file"],
-    values["semantic-adapter-module"],
-    values["advisory-adapter-module"],
+    ...optionsWith("private", true).flatMap((name) => values[name] ?? []),
   ].filter((value): value is string => Boolean(value));
 }
 
 function commonCodexOptions(
   values: Values,
-  routes: Routes,
   roots: Roots,
   privateRoots: string[],
 ) {
-  if (![routes.codex, routes.semanticCodex, routes.advisoryCodex].some(Boolean))
-    return undefined;
   return {
-    binary: absoluteOption(values["codex-bin"], "--codex-bin"),
-    authFile: absoluteOption(values["codex-auth-file"], "--codex-auth-file"),
-    timeoutMs:
-      values["codex-timeout-ms"] === undefined
-        ? undefined
-        : Number(values["codex-timeout-ms"]),
+    binary: requiredOption(values["codex-bin"], "--codex-bin"),
+    authFile: requiredOption(values["codex-auth-file"], "--codex-auth-file"),
+    retainHostDiagnostics: values["retain-host-diagnostics"] === true,
+    timeoutMs: codexTimeout(values["codex-timeout-ms"]),
     projectRoot: roots.projectRoot,
     resultsRoot: roots.resultsRoot,
     additionalProtectedRoots: [...privateRoots, roots.runStateRoot],
   };
 }
 
+function codexTimeout(value: string | undefined): number | undefined {
+  if (value === undefined) return undefined;
+  const timeout = Number(value);
+  if (!Number.isSafeInteger(timeout) || timeout < 1 || timeout > 30 * 60_000)
+    throw new InvocationError(
+      "invalid --codex-timeout-ms; supply a positive integer at most 1800000 (30 minutes)",
+    );
+  return timeout;
+}
+
 function claudeHostOptions(
   values: Values,
   routes: Routes,
@@ -379,10 +305,11 @@ function claudeHostOptions(
 ) {
   if (!routes.claude) return undefined;
   return {
-    binary: absoluteOption(values["claude-bin"], "--claude-bin"),
+    retainHostDiagnostics: values["retain-host-diagnostics"] === true,
+    binary: requiredOption(values["claude-bin"], "--claude-bin"),
     ...(values["claude-credential-file"]
       ? {
-          credentialFile: absoluteOption(
+          credentialFile: requiredOption(
             values["claude-credential-file"],
             "--claude-credential-file",
           ),
@@ -390,7 +317,7 @@ function claudeHostOptions(
       : {}),
     ...(values["claude-uv-cache-dir"]
       ? {
-          uvCacheDir: absoluteOption(
+          uvCacheDir: requiredOption(
             values["claude-uv-cache-dir"],
             "--claude-uv-cache-dir",
           ),
@@ -410,17 +337,11 @@ function extensionInvocation(values: Values) {
   const command = values["extension-command-file"];
   if (!command) return undefined;
   return {
-    commandFile: absoluteOption(command, "--extension-command-file"),
+    commandFile: requiredOption(command, "--extension-command-file"),
     sourceFiles: extensionSources(values),
     caseId: requiredOption(values["case-id"], "--case-id"),
-    configurationFile: optionalAbsolute(
-      values["extension-configuration-file"],
-      "--extension-configuration-file",
-    ),
-    redactedConfigurationFile: optionalAbsolute(
-      values["extension-redacted-configuration-file"],
-      "--extension-redacted-configuration-file",
-    ),
+    configurationFile: values["extension-configuration-file"],
+    redactedConfigurationFile: values["extension-redacted-configuration-file"],
     taskVerdictPolicy: values["task-verdict-policy"],
     replaceBuiltinGraders: values["replace-builtin-grader"] ?? [],
   };
@@ -435,16 +356,15 @@ const CODEX_MODEL_KEYS = {
 function codexRoleOptions(
   values: Values,
   common: ReturnType<typeof commonCodexOptions>,
-  enabled: boolean,
   role: keyof typeof CODEX_MODEL_KEYS,
 ) {
-  if (!enabled) return undefined;
-  if (!common)
-    throw new InvocationError("Codex options require a Codex host route");
   const [modelKey, effortKey] = CODEX_MODEL_KEYS[role];
   return {
     ...(role === "candidate"
-      ? { entrypoint: codexEntrypoint(values["codex-entrypoint"]) }
+      ? {
+          entrypoint: values["codex-entrypoint"] as
+            "exec" | "app-server" | undefined,
+        }
       : {}),
     ...common,
     model: requiredOption(values[modelKey], `--${modelKey}`),
@@ -452,15 +372,25 @@ function codexRoleOptions(
   };
 }
 
-function codexEntrypoint(
-  value: string | undefined,
-): "exec" | "app-server" | undefined {
-  if (value === undefined) return undefined;
-  if (value !== "exec" && value !== "app-server")
-    throw new InvocationError(
-      "--codex-entrypoint requires --host codex and exec or app-server",
-    );
-  return value;
+function selectedCodexOptions(
+  values: Values,
+  routes: Routes,
+  roots: Roots,
+  privateRoots: string[],
+) {
+  if (!routes.anyCodex) return {};
+  const common = commonCodexOptions(values, roots, privateRoots);
+  return {
+    codex: routes.codex
+      ? codexRoleOptions(values, common, "candidate")
+      : undefined,
+    semanticCodex: routes.semanticCodex
+      ? codexRoleOptions(values, common, "semantic")
+      : undefined,
+    advisoryCodex: routes.advisoryCodex
+      ? codexRoleOptions(values, common, "advisory")
+      : undefined,
+  };
 }
 
 function invocationInputs(
@@ -472,55 +402,30 @@ function invocationInputs(
     roots,
     privateRoots,
     toolchainBinDir,
-    codexCommon,
+    codexOptions,
     claudeOptions,
     trials,
   } = context;
   return {
     json: values.json ?? false,
-    deprecatedRuntimeOptions: (
-      ["toolchain-bin-dir", "claude-uv-cache-dir"] as const
-    ).filter((name) => values[name] !== undefined),
-    dry: values.dry ?? false,
-    runtimeConfigFile: optionalAbsolute(
-      values["runtime-config-file"],
-      "--runtime-config-file",
+    runManifestFile: values["run-manifest-file"],
+    protectedRoots: context.protectedRoots,
+    deprecatedRuntimeOptions: optionsWith("section", "deprecated").filter(
+      (name) => values[name] !== undefined,
     ),
-    caseFile: optionalAbsolute(values["case-file"], "--case-file"),
+    dry: values.dry ?? false,
+    runtimeConfigFile: values["runtime-config-file"],
+    caseFile: values["case-file"],
     extension: extensionInvocation(values),
-    caseSourceRoot: optionalAbsolute(
-      values["case-source-root"],
-      "--case-source-root",
-    ),
-    caseSourceMapFile: optionalAbsolute(
-      values["case-source-map-file"],
-      "--case-source-map-file",
-    ),
+    caseSourceRoot: values["case-source-root"],
+    caseSourceMapFile: values["case-source-map-file"],
     adapterModule: routes.builtinHost
       ? undefined
-      : absoluteOption(values["adapter-module"], "--adapter-module"),
-    semanticAdapterModule: optionalAbsolute(
-      values["semantic-adapter-module"],
-      "--semantic-adapter-module",
-    ),
-    semanticCodex: codexRoleOptions(
-      values,
-      codexCommon,
-      routes.semanticCodex,
-      "semantic",
-    ),
-    advisoryAdapterModule: optionalAbsolute(
-      values["advisory-adapter-module"],
-      "--advisory-adapter-module",
-    ),
-    advisoryCodex: codexRoleOptions(
-      values,
-      codexCommon,
-      routes.advisoryCodex,
-      "advisory",
-    ),
+      : requiredOption(values["adapter-module"], "--adapter-module"),
+    semanticAdapterModule: values["semantic-adapter-module"],
+    advisoryAdapterModule: values["advisory-adapter-module"],
     advisoryExcludedPaths: values["advisory-exclude"] ?? [],
-    codex: codexRoleOptions(values, codexCommon, routes.codex, "candidate"),
+    ...codexOptions,
     claude: claudeOptions,
     shellIsolation: shellIsolationOptions(
       values,
@@ -532,10 +437,7 @@ function invocationInputs(
       values["runner-build-digest"],
       "--runner-build-digest",
     ),
-    runnerCheckoutRoot: optionalAbsolute(
-      values["runner-checkout-root"],
-      "--runner-checkout-root",
-    ),
+    runnerCheckoutRoot: values["runner-checkout-root"],
     projectDigest: optionalDigest(values["project-digest"], "--project-digest"),
     ...trials,
   };
@@ -558,14 +460,8 @@ function shellIsolationOptions(
 function invocationContext(values: Values) {
   const trials = trialParameters(values);
   const protectedRoots = values["protected-root"] ?? [];
-  if (protectedRoots.some((path) => !isAbsolute(path)))
-    throw new InvocationError("--protected-root must be absolute");
-  const toolchainBinDir = optionalAbsolute(
-    values["toolchain-bin-dir"],
-    "--toolchain-bin-dir",
-  );
+  const toolchainBinDir = values["toolchain-bin-dir"];
   const routes = hostRoutes(values);
-  validateHostCompatibility(values, routes, protectedRoots);
   const roots = rootParameters(values);
   validateExtensionSelection(values);
   const privateRoots = privateRootDeclarations(
@@ -573,7 +469,12 @@ function invocationContext(values: Values) {
     roots.configRoot,
     protectedRoots,
   );
-  const codexCommon = commonCodexOptions(values, routes, roots, privateRoots);
+  const codexOptions = selectedCodexOptions(
+    values,
+    routes,
+    roots,
+    privateRoots,
+  );
   const claudeOptions = claudeHostOptions(
     values,
     routes,
@@ -584,18 +485,113 @@ function invocationContext(values: Values) {
   return {
     routes,
     roots,
+    protectedRoots,
     privateRoots,
     toolchainBinDir,
-    codexCommon,
+    codexOptions,
     claudeOptions,
     trials,
   };
 }
 
 /** Decode CLI flags in their documented validation order. */
-export function parseInvocation(argv: string[]) {
+export async function parseInvocation(argv: string[]) {
+  if (argv[0] !== "run")
+    throw new InvocationError(
+      "unknown command; available commands: demo, init, run, report, prune; run sevro --help",
+    );
   const parsed = cliArguments(argv);
-  if (parsed.positionals.length !== 1 || parsed.positionals[0] !== "run")
+  if (parsed.positionals.length !== 1)
     throw new InvocationError("expected the run command");
+  parsed.values = await savedRunValues(parsed.values);
+  applyRunDefaults(parsed.values);
+  validateHostCompatibility(
+    parsed.values,
+    hostRoutes(parsed.values),
+    parsed.values["protected-root"] ?? [],
+  );
+  applyRootDefaults(parsed.values);
+  resolveNativeBinaries(parsed.values);
+  await canonicalizePaths(parsed.values);
   return invocationInputs(parsed.values, invocationContext(parsed.values));
 }
+
+function resolveNativeBinaries(values: Values): void {
+  const routes = hostRoutes(values);
+  if (routes.anyCodex) values["codex-bin"] ??= nativeBinary("codex");
+  if (routes.claude) values["claude-bin"] ??= nativeBinary("claude");
+}
+
+function nativeBinary(host: "codex" | "claude"): string {
+  const binary = Bun.which(host);
+  if (!binary)
+    throw new InvocationError(
+      `selected ${host} executable was not found on PATH; install ${host} or supply --${host}-bin <path>`,
+    );
+  return binary;
+}
+
+export type Invocation = Awaited<ReturnType<typeof parseInvocation>>;
+
+/** Keep all selected native roles visible to protection and evidence callers. */
+export function nativeRoutes(
+  invocation: Pick<
+    Invocation,
+    "codex" | "claude" | "semanticCodex" | "advisoryCodex"
+  >,
+) {
+  return [
+    invocation.codex,
+    invocation.claude,
+    invocation.semanticCodex,
+    invocation.advisoryCodex,
+  ].filter((host) => host !== undefined);
+}
+
+function applyRunDefaults(values: Values): void {
+  values.condition ??= "passive";
+  values.trials ??= "1";
+  values.jobs ??= "3";
+  values.threshold ??= "1";
+}
+
+function applyRootDefaults(values: Values): void {
+  values["project-root"] ??= process.cwd();
+  values["results-root"] ??= join(
+    resolve(values["project-root"]),
+    ".sevro",
+    "results",
+  );
+}
+
+async function canonicalOption(path: string, option: string): Promise<string> {
+  try {
+    return await canonicalRuntimeRoot(resolve(path));
+  } catch (cause) {
+    const error = cause as NodeJS.ErrnoException;
+    throw new InvocationError(
+      `--${option} cannot be resolved at ${path}: filesystem ${error.syscall ?? "realpath"} failed (${error.code ?? "unknown"}); supply a usable file or directory path`,
+      { cause },
+    );
+  }
+}
+
+async function canonicalizePaths(values: Values): Promise<void> {
+  for (const name of PATH_OPTIONS) {
+    const value = values[name];
+    if (value !== undefined)
+      values[name] = await canonicalOption(
+        requiredOption(value, `--${name}`),
+        name,
+      );
+  }
+  for (const name of PATH_LIST_OPTIONS) {
+    const paths = values[name];
+    if (paths)
+      values[name] = await Promise.all(
+        paths.map((path) =>
+          canonicalOption(requiredOption(path, `--${name}`), name),
+        ),
+      );
+  }
+}