@dungle-scrubs/harness-cli-normalizer 0.3.1 → 0.4.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@dungle-scrubs/harness-cli-normalizer",
-  "version": "0.3.1",
-  "description": "One stable interface to four coding-agent CLIs.",
+  "version": "0.4.1",
+  "description": "One stable CLI to four coding-agent harnesses: normalized flags, defaults, and events.",
   "license": "MIT",
   "author": "Kevin Frilot",
   "repository": {
@@ -13,27 +13,6 @@
   "bin": {
     "hcn": "./dist/cli.js"
   },
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./knowledge": {
-      "types": "./dist/knowledge/index.d.ts",
-      "import": "./dist/knowledge/index.js"
-    },
-    "./interpretation": {
-      "types": "./dist/interpretation/index.d.ts",
-      "import": "./dist/interpretation/index.js"
-    },
-    "./execution": {
-      "types": "./dist/execution/index.d.ts",
-      "import": "./dist/execution/index.js"
-    },
-    "./package.json": "./package.json"
-  },
   "files": [
     "dist",
     "src"

package/src/cli/args.ts

@@ -162,6 +162,15 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
     const raw = String(values.tools);
     opts.tools = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
   }
+  if (values["exclude-tools"] !== undefined) {
+    const raw = String(values["exclude-tools"]);
+    opts.excludeTools = raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
+  }
+  if (values.skills !== undefined) {
+    const raw = String(values.skills);
+    (opts as Record<string, unknown>).skills =
+      raw.length === 0 ? [] : raw.split(",").map((s) => s.trim());
+  }
   if (values.autonomy === true) opts.autonomy = true;
   else if (values["no-autonomy"] === true) opts.autonomy = false;
   else if (values.autonomy === false) opts.autonomy = false; // for completeness
@@ -212,8 +221,31 @@ export const parseTurnOptions = (values: Record<string, unknown>): TurnOptions =
 
 export const parseRunExtra = (
   values: Record<string, unknown>,
-): { cwd?: string; env?: Record<string, string>; resume?: string } => {
-  const extra: { cwd?: string; env?: Record<string, string>; resume?: string } = {};
+): {
+  cwd?: string;
+  env?: Record<string, string>;
+  resume?: string;
+  timeoutSeconds?: number;
+} => {
+  const extra: {
+    cwd?: string;
+    env?: Record<string, string>;
+    resume?: string;
+    timeoutSeconds?: number;
+  } = {};
+  if (values.timeout !== undefined) {
+    const n = Number(values.timeout);
+    if (!Number.isFinite(n) || n < 0 || !Number.isInteger(n)) {
+      throw new ArgvRefusalError({
+        issue: "invalid-option-value",
+        harness: "claude",
+        option: "maxSteps",
+        supported: ["whole seconds, >= 0 (0 disables)"],
+        detail: String(values.timeout),
+      });
+    }
+    extra.timeoutSeconds = n;
+  }
   if (values.cwd !== undefined) extra.cwd = String(values.cwd);
   if (values.resume !== undefined) extra.resume = String(values.resume);
   if (values["session-id"] !== undefined) extra.resume = String(values["session-id"]);
@@ -238,6 +270,7 @@ const KNOWN_FLAGS = new Set([
   "--sandbox",
   "--provider",
   "--tools",
+  "--exclude-tools",
   "--autonomy",
   "--no-autonomy",
   "--write",
@@ -269,11 +302,13 @@ const FLAGS_WITH_VALUE = new Set([
   "--sandbox",
   "--provider",
   "--tools",
+  "--exclude-tools",
   "--max-steps",
   "--cwd",
   "--env",
   "--resume",
   "--session-id",
+  "--timeout",
 ]);
 
 export const detectPositionalPromptInjection = (argv: string[]): string | null => {
@@ -339,11 +374,34 @@ const preprocessPromptArgs = (argv: string[]): string[] => {
  * Wrapper around node:util parseArgs for the common flag table.
  * Throws with exit code 2 on unknown flag.
  */
+export interface SplitPassthrough {
+  /** Tokens before the separator - hcn's normalized surface. */
+  readonly normalized: string[];
+  /** Tokens after the separator - verbatim passthrough to the harness,
+   * empty when no separator was present. */
+  readonly passthrough: readonly string[];
+}
+
+/** D6: split argv at the first bare `--`. Everything after it belongs to
+ * the harness, not to hcn - wrong-harness flags there fail in the harness
+ * itself and surface as native errors, never as hcn refusals. */
+export const splitPassthrough = (argv: readonly string[]): SplitPassthrough => {
+  const idx = argv.indexOf("--");
+  if (idx === -1) return { normalized: [...argv], passthrough: [] };
+  return {
+    normalized: argv.slice(0, idx),
+    passthrough: argv.slice(idx + 1),
+  };
+};
+
 export const parseCommonFlags = (
   argv: string[],
   opts: { strict?: boolean } = {},
 ): ReturnType<typeof parseArgs> => {
-  const normalized = preprocessPromptArgs(argv);
+  // The separator itself never reaches parseArgs: passthrough tokens may
+  // be unknown to hcn by design (that is their purpose).
+  const { normalized: withoutPassthrough } = splitPassthrough(argv);
+  const normalized = preprocessPromptArgs(withoutPassthrough);
   const config = {
     allowPositionals: true,
     strict: opts.strict ?? true,
@@ -355,6 +413,8 @@ export const parseCommonFlags = (
       sandbox: { type: "string" as const },
       provider: { type: "string" as const },
       tools: { type: "string" as const },
+      "exclude-tools": { type: "string" as const },
+      skills: { type: "string" as const },
       autonomy: { type: "boolean" as const },
       "no-autonomy": { type: "boolean" as const },
       write: { type: "boolean" as const },
@@ -370,6 +430,7 @@ export const parseCommonFlags = (
       env: { type: "string" as const, multiple: true },
       resume: { type: "string" as const },
       "session-id": { type: "string" as const },
+      timeout: { type: "string" as const },
       json: { type: "boolean" as const },
       argv: { type: "boolean" as const },
       help: { type: "boolean" as const },

package/src/cli/config.ts

@@ -0,0 +1,176 @@
+/**
+ * User-level config: ~/.config/hcn/config.json (or $HCN_CONFIG_DIR for
+ * tests). Hard-fail discipline: unknown keys, malformed JSON, and schema
+ * version mismatches exit 2 naming the offender - a config that silently
+ * no-ops is a safety hole in a tool whose config can tighten a sandbox.
+ *
+ * Schema is intentionally minimal and mirrors the normalized option
+ * surface; it grows as dimensions ratify. The parser validates SHAPE
+ * (key known, value type plausible); value legality (effort in ladder,
+ * model in vocabulary) is enforced by the same renderers as args, so
+ * config and CLI can never disagree about what is legal.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import type { TurnOptions } from "../interpretation/argv.js";
+
+const SCHEMA_VERSION = 1;
+
+export class ConfigError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ConfigError";
+  }
+}
+
+export const userConfigPath = (): string =>
+  join(
+    process.env.HCN_CONFIG_DIR ??
+      join(process.env.XDG_CONFIG_HOME ?? join(homedir(), ".config"), "hcn"),
+    "config.json",
+  );
+
+/** Project config: `.hcn/config.json` at the git root (P4 ratified as A -
+ * auto-discover, no trust gate; the config is code-reviewed like AGENTS.md
+ * and every project-tier provenance line names its path). Null outside a
+ * repo or when the repo declares none. */
+export const projectConfigPath = (startDir: string = process.cwd()): string | null => {
+  let dir = resolve(startDir);
+  for (;;) {
+    if (existsSync(join(dir, ".hcn", "config.json"))) return join(dir, ".hcn", "config.json");
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    // stop at the git root: above it is not this project
+    if (existsSync(join(dir, ".git")) && !existsSync(join(parent, ".git"))) {
+      return null;
+    }
+    dir = parent;
+  }
+};
+
+type MutableTurnOptions = {
+  [K in keyof TurnOptions]?: TurnOptions[K];
+};
+
+const KNOWN_KEYS = new Set([
+  "effort",
+  "model",
+  "provider",
+  "sandbox",
+  "tools",
+  "excludeTools",
+  "autonomy",
+  "write",
+  "shell",
+  "maxSteps",
+  "toolsets",
+  "timeout",
+]);
+
+const LIST_KEYS = new Set(["tools", "excludeTools"]);
+const BOOL_KEYS = new Set(["autonomy", "write", "shell"]);
+
+/** Parse + validate config text. Throws ConfigError with the offending key
+ * named on any violation - never warns and continues. */
+export const parseUserConfig = (text: string): Partial<TurnOptions> => {
+  let raw: unknown;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new ConfigError(`config is not valid JSON: ${(e as Error).message}`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new ConfigError("config root must be a JSON object");
+  }
+  const obj = raw as Record<string, unknown>;
+
+  if (obj.version === undefined) {
+    throw new ConfigError("config missing required field: version");
+  }
+  if (obj.version !== SCHEMA_VERSION) {
+    throw new ConfigError(
+      `config version ${JSON.stringify(obj.version)} not supported (expected ${SCHEMA_VERSION})`,
+    );
+  }
+  delete obj.version;
+
+  const out: MutableTurnOptions = {};
+  for (const [key, value] of Object.entries(obj)) {
+    if (!KNOWN_KEYS.has(key)) {
+      throw new ConfigError(`unknown config key: ${JSON.stringify(key)}`);
+    }
+    if (key === "toolsets") {
+      if (
+        typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        Object.entries(value).some(
+          ([, v]) => !Array.isArray(v) || v.some((t) => typeof t !== "string" || t.trim() === ""),
+        )
+      ) {
+        throw new ConfigError(
+          'config key "toolsets" must be an object of name -> non-empty string array',
+        );
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (key === "timeout") {
+      if (typeof value !== "number" || !Number.isInteger(value) || value < 0) {
+        throw new ConfigError(
+          'config key "timeout" must be a whole number of seconds, >= 0 (0 disables)',
+        );
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (LIST_KEYS.has(key)) {
+      if (!Array.isArray(value) || value.some((v) => typeof v !== "string")) {
+        throw new ConfigError(`config key ${JSON.stringify(key)} must be an array of strings`);
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (BOOL_KEYS.has(key)) {
+      if (typeof value !== "boolean") {
+        throw new ConfigError(`config key ${JSON.stringify(key)} must be a boolean`);
+      }
+      (out as Record<string, unknown>)[key] = value;
+      continue;
+    }
+    if (typeof value !== "string" && typeof value !== "number") {
+      throw new ConfigError(
+        `config key ${JSON.stringify(key)} must be a string or number, got ${typeof value}`,
+      );
+    }
+    (out as Record<string, unknown>)[key] = value;
+  }
+  return out as Partial<TurnOptions>;
+};
+
+/** Load the user config if the file exists; absent file is an empty config
+ * (no tiers engaged), unreadable or invalid file is a hard error. */
+export const loadUserConfig = (): { config: Partial<TurnOptions>; path: string } | null =>
+  loadConfigAt(userConfigPath());
+
+/** Load the project config (git-root auto-discovery, ratified A). */
+export const loadProjectConfig = (
+  startDir?: string,
+): { config: Partial<TurnOptions>; path: string } | null => {
+  const path = projectConfigPath(startDir);
+  if (path === null) return null;
+  return loadConfigAt(path);
+};
+
+const loadConfigAt = (path: string): { config: Partial<TurnOptions>; path: string } | null => {
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (e) {
+    const code = (e as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") return null;
+    throw new ConfigError(`cannot read config at ${path}: ${(e as Error).message}`);
+  }
+  return { config: parseUserConfig(text), path };
+};

package/src/cli/help.ts

@@ -32,7 +32,10 @@ Options:
   --effort <value>          Effort level (validated per harness/model)
   --sandbox <value>         Sandbox mode (codex only)
   --provider <value>        Provider (pi only)
-  --tools <a,b>             Tool grants (claude only, comma-separated)
+  --tools <a,b>             Tool grant allowlist (claude, pi; a bare name
+                            matching a configured toolset expands to it)
+  --exclude-tools <a,b>     Complement over known tools (claude, pi;
+                            mutually exclusive with --tools)
   --autonomy                Enable autonomy flag (claude/codex/muse)
   --no-autonomy             Disable autonomy
   --write                   Enable write (muse)
@@ -40,6 +43,8 @@ Options:
   --shell                   Enable shell (muse)
   --no-shell                Disable shell
   --max-steps <n>           Max steps (muse, 1-10000)
+  --timeout <seconds>       Wall-clock budget for the run (all harnesses,
+                            hcn-enforced; 0 disables; no default)
   --no-tools                Disable tools discovery facet
   --no-instruction-files    Disable instructionFiles discovery facet
   --no-extensions           Disable extensions discovery facet
@@ -47,9 +52,20 @@ Options:
   --cwd <path>              Working directory for spawn
   --env KEY=VAL             Environment (repeatable; KEY= deletes)
   --resume <uuid>           Resume session id (UUID)
+  --                        Passthrough: native harness args verbatim
+                            (failures surface as labeled native errors)
   --json                    NDJSON HarnessEvent to stdout
   -h, --help                Show help
   -V, --version             Show version
+
+Defaults with no flags:
+  Every launch resolves args > project config (.hcn/config.json at the
+  git root) > user config (~/.config/hcn/config.json) > built-in profile
+  > harness default. The profile pins: effort medium, sandbox
+  workspace-write (codex only; other harnesses report divergence),
+  discovery on, autonomy off, write/shell on. timeout and max-steps have
+  no default. Provenance prints to stderr on every run; see
+  'hcn inspect <harness>' for the resolved argv of a bare run.
 `;
 
 export const SESSION_HELP = `hcn session - Interactive session (Claude-only)

package/src/cli/inspect.ts

@@ -1,6 +1,7 @@
 import { redactArgv } from "../execution/stream-turn.js";
 import { buildLaunchArgv } from "../interpretation/argv.js";
 import { ArgvRefusalError } from "../interpretation/refusal.js";
+import { FloorExceededError, resolveEffectiveOptions } from "../interpretation/resolve-options.js";
 import { parseTurnOptions, resolvePromptAsync } from "./args.js";
 import { resolveHarness } from "./resolve-harness.js";
 
@@ -123,8 +124,40 @@ export const inspect = async (harnessName: string, rawArgs: string[]): Promise<v
     throw err;
   }
 
+  // Inspect resolves exactly as a launch would: profile + user config,
+  // launch-only semantics, so --argv previews the truth of a bare run.
+  const { loadUserConfig, loadProjectConfig, ConfigError } = await import("./config.js");
+  const tiers: {
+    user?: Partial<ReturnType<typeof parseTurnOptions>>;
+    project?: Partial<ReturnType<typeof parseTurnOptions>>;
+  } = {};
+  try {
+    const loaded = loadUserConfig();
+    if (loaded !== null) tiers.user = loaded.config;
+    const proj = loadProjectConfig();
+    if (proj !== null) tiers.project = proj.config;
+  } catch (configErr) {
+    if (configErr instanceof ConfigError) {
+      process.stderr.write(`config error: ${(configErr as Error).message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw configErr;
+  }
+  let resolved: ReturnType<typeof resolveEffectiveOptions>;
+  try {
+    resolved = resolveEffectiveOptions(h, { ...turnOpts, prompt } as never, tiers);
+  } catch (resErr) {
+    if (resErr instanceof FloorExceededError) {
+      process.stderr.write(`${(resErr as Error).message}\n`);
+      process.exitCode = 2;
+      return;
+    }
+    throw resErr;
+  }
+  const { prompt: _p, ...effectiveRest } = resolved.options as { prompt: string };
   const fullOpts = {
-    ...turnOpts,
+    ...(effectiveRest as object),
     prompt,
     ...(promptSource !== "positional" ? { __explicitPrompt: true as const } : {}),
   } as Parameters<typeof buildLaunchArgv>[1];

package/src/cli/render.ts

@@ -41,7 +41,16 @@ export const renderEvent = (event: HarnessEvent, state: RenderState): void => {
       break;
     case "failure": {
       const detail = event.message ?? `${event.class}`;
-      process.stdout.write(red(`\n  ✗ failure ${event.class}: ${detail}`));
+      // D6: native failures get an unmistakable prefix and the native exit
+      // code shown as data, so a human never reads a harness error as an
+      // hcn error.
+      if (event.class === "native") {
+        const nat =
+          event.nativeExitCode !== undefined ? ` [native exit ${event.nativeExitCode}]` : "";
+        process.stdout.write(red(`\n  ✗ NATIVE${nat} ${detail}`));
+      } else {
+        process.stdout.write(red(`\n  ✗ failure ${event.class}: ${detail}`));
+      }
       break;
     }
     case "done": {