@ai-substrate/engineering-harness 0.2.0

package/harness/cli/dist/acts/verb.js

@@ -0,0 +1,56 @@
+import { exitWithEnvelope } from '../output/exit.js';
+import { createOutputPort } from '../output/output-port.js';
+import { buildVerbContext, runVerb } from '../services/extensions/verb-context.js';
+/**
+ * Register ONE extension verb as a top-level `harness <verb>` subcommand. Thin:
+ * it maps the declarative `HarnessVerb` onto commander (name, description,
+ * options, args), and its action parses opts/args → builds the `VerbContext`
+ * (cwd from the process port) → `await runVerb` → exits via the kernel (so the
+ * status→exit mapping + `process.exit` confinement are unchanged). No business
+ * logic lives here. Returns the created Command (usage is inspectable).
+ */
+export function registerVerbAct(program, verb, deps, io) {
+    const command = program.command(verb.name);
+    command.description(verb.description ?? verb.summary);
+    command.summary(verb.summary);
+    // Group every contributed verb under its own `--help` heading so the dynamic,
+    // extension-owned surface reads separately from the fixed core commands.
+    command.helpGroup('Extensions:');
+    const args = verb.args ?? [];
+    for (const arg of args) {
+        command.argument(arg.name, arg.description);
+    }
+    for (const option of verb.options ?? []) {
+        if (option.defaultValue !== undefined) {
+            command.option(option.flags, option.description, option.defaultValue);
+        }
+        else {
+            command.option(option.flags, option.description);
+        }
+    }
+    command.action(async (...callArgs) => {
+        const cmd = callArgs[callArgs.length - 1];
+        const positionals = callArgs.slice(0, args.length);
+        const ctx = buildVerbContext(deps, {
+            cwd: deps.proc.cwd(),
+            args: buildArgMap(args, positionals),
+            options: cmd.opts(),
+        });
+        const envelope = await runVerb(verb, ctx, deps.clock);
+        exitWithEnvelope(envelope, createOutputPort(io.mode, io.writers));
+    });
+    return command;
+}
+/** Map declared args (`<name>`, `[env]`, `<files...>`) to a `{argKey: value}` record. */
+function buildArgMap(args, positionals) {
+    const result = {};
+    args.forEach((arg, index) => {
+        result[argKey(arg.name)] = positionals[index];
+    });
+    return result;
+}
+/** Strip commander placeholder punctuation: `<files...>` → `files`. */
+function argKey(name) {
+    return name.replace(/[<>[\].]/g, '').trim();
+}
+//# sourceMappingURL=verb.js.map

package/harness/cli/dist/acts/verb.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verb.js","sourceRoot":"","sources":["../../src/acts/verb.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,EAAc,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAExE,OAAO,EAAE,gBAAgB,EAAE,OAAO,EAAE,MAAM,wCAAwC,CAAC;AAYnF;;;;;;;GAOG;AACH,MAAM,UAAU,eAAe,CAC7B,OAAgB,EAChB,IAAiB,EACjB,IAAiB,EACjB,EAAS;IAET,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC3C,OAAO,CAAC,WAAW,CAAC,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC;IACtD,OAAO,CAAC,OAAO,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IAC9B,8EAA8E;IAC9E,yEAAyE;IACzE,OAAO,CAAC,SAAS,CAAC,aAAa,CAAC,CAAC;IAEjC,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,IAAI,EAAE,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,WAAW,CAAC,CAAC;IAC9C,CAAC;IACD,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,OAAO,IAAI,EAAE,EAAE,CAAC;QACxC,IAAI,MAAM,CAAC,YAAY,KAAK,SAAS,EAAE,CAAC;YACtC,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,EAAE,MAAM,CAAC,YAAY,CAAC,CAAC;QACxE,CAAC;aAAM,CAAC;YACN,OAAO,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,WAAW,CAAC,CAAC;QACnD,CAAC;IACH,CAAC;IAED,OAAO,CAAC,MAAM,CAAC,KAAK,EAAE,GAAG,QAAmB,EAAE,EAAE;QAC9C,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAY,CAAC;QACrD,MAAM,WAAW,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,IAAI,CAAC,MAAM,CAA2B,CAAC;QAC7E,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,EAAE;YACjC,GAAG,EAAE,IAAI,CAAC,IAAI,CAAC,GAAG,EAAE;YACpB,IAAI,EAAE,WAAW,CAAC,IAAI,EAAE,WAAW,CAAC;YACpC,OAAO,EAAE,GAAG,CAAC,IAAI,EAAE;SACpB,CAAC,CAAC;QACH,MAAM,QAAQ,GAAG,MAAM,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC;QACtD,gBAAgB,CAAC,QAAQ,EAAE,gBAAgB,CAAC,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,CAAC,CAAC;IACpE,CAAC,CAAC,CAAC;IAEH,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,yFAAyF;AACzF,SAAS,WAAW,CAClB,IAAwB,EACxB,WAAmC;IAEnC,MAAM,MAAM,GAAuC,EAAE,CAAC;IACtD,IAAI,CAAC,OAAO,CAAC,CAAC,GAAG,EAAE,KAAK,EAAE,EAAE;QAC1B,MAAM,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,GAAG,WAAW,CAAC,KAAK,CAAC,CAAC;IAChD,CAAC,CAAC,CAAC;IACH,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,uEAAuE;AACvE,SAAS,MAAM,CAAC,IAAY;IAC1B,OAAO,IAAI,CAAC,OAAO,CAAC,WAAW,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;AAC9C,CAAC"}

package/harness/cli/dist/adapters/clock/clock-port.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Clock port — the kernel's only side-effect dependency.
+ *
+ * Injected (never `new Date()` inside services/kernel) so envelope timestamps
+ * are deterministic in unit tests. See workshop 001 + plan Finding 04.
+ */
+export interface Clock {
+    /** Current instant as an ISO-8601 string, e.g. "2026-06-08T07:20:00.000Z". */
+    nowIso(): string;
+}

package/harness/cli/dist/adapters/clock/clock-port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=clock-port.js.map

package/harness/cli/dist/adapters/clock/clock-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock-port.js","sourceRoot":"","sources":["../../../src/adapters/clock/clock-port.ts"],"names":[],"mappings":""}

package/harness/cli/dist/adapters/clock/fake-clock.d.ts

@@ -0,0 +1,15 @@
+import type { Clock } from './clock-port.js';
+/**
+ * Deterministic Clock for tests. Returns a fixed instant until advanced/set,
+ * and records its call history (fakes over mocks — assert on `calls`).
+ */
+export declare class FakeClock implements Clock {
+    private current;
+    readonly calls: string[];
+    constructor(start?: string | number | Date);
+    nowIso(): string;
+    /** Advance the fake clock forward by `ms` milliseconds. */
+    advance(ms: number): void;
+    /** Jump the fake clock to an absolute instant. */
+    set(instant: string | number | Date): void;
+}

package/harness/cli/dist/adapters/clock/fake-clock.js

@@ -0,0 +1,25 @@
+/**
+ * Deterministic Clock for tests. Returns a fixed instant until advanced/set,
+ * and records its call history (fakes over mocks — assert on `calls`).
+ */
+export class FakeClock {
+    current;
+    calls = [];
+    constructor(start = '2026-06-08T07:20:00.000Z') {
+        this.current = new Date(start).getTime();
+    }
+    nowIso() {
+        const iso = new Date(this.current).toISOString();
+        this.calls.push(iso);
+        return iso;
+    }
+    /** Advance the fake clock forward by `ms` milliseconds. */
+    advance(ms) {
+        this.current += ms;
+    }
+    /** Jump the fake clock to an absolute instant. */
+    set(instant) {
+        this.current = new Date(instant).getTime();
+    }
+}
+//# sourceMappingURL=fake-clock.js.map

package/harness/cli/dist/adapters/clock/fake-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-clock.js","sourceRoot":"","sources":["../../../src/adapters/clock/fake-clock.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,SAAS;IACZ,OAAO,CAAS;IACf,KAAK,GAAa,EAAE,CAAC;IAE9B,YAAY,QAAgC,0BAA0B;QACpE,IAAI,CAAC,OAAO,GAAG,IAAI,IAAI,CAAC,KAAK,CAAC,CAAC,OAAO,EAAE,CAAC;IAC3C,CAAC;IAED,MAAM;QACJ,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;QACjD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACrB,OAAO,GAAG,CAAC;IACb,CAAC;IAED,2DAA2D;IAC3D,OAAO,CAAC,EAAU;QAChB,IAAI,CAAC,OAAO,IAAI,EAAE,CAAC;IACrB,CAAC;IAED,kDAAkD;IAClD,GAAG,CAAC,OAA+B;QACjC,IAAI,CAAC,OAAO,GAAG,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,EAAE,CAAC;IAC7C,CAAC;CACF"}

package/harness/cli/dist/adapters/clock/system-clock.d.ts

@@ -0,0 +1,5 @@
+import type { Clock } from './clock-port.js';
+/** Real clock — the only place wall-clock time is read. */
+export declare class SystemClock implements Clock {
+    nowIso(): string;
+}

package/harness/cli/dist/adapters/clock/system-clock.js

@@ -0,0 +1,7 @@
+/** Real clock — the only place wall-clock time is read. */
+export class SystemClock {
+    nowIso() {
+        return new Date().toISOString();
+    }
+}
+//# sourceMappingURL=system-clock.js.map

package/harness/cli/dist/adapters/clock/system-clock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-clock.js","sourceRoot":"","sources":["../../../src/adapters/clock/system-clock.ts"],"names":[],"mappings":"AAEA,2DAA2D;AAC3D,MAAM,OAAO,WAAW;IACtB,MAAM;QACJ,OAAO,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAClC,CAAC;CACF"}

package/harness/cli/dist/adapters/env/env-port.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Environment port — reads process environment variables behind an interface.
+ *
+ * Lets services read/report env (e.g. `HARNESS_JSON`) without touching
+ * `process.env` directly, so they stay unit-testable with `FakeEnv`.
+ */
+export interface EnvPort {
+    /** Value of an env var, or undefined if unset. */
+    get(name: string): string | undefined;
+    /**
+     * Absolute path to the user's home directory (`$HOME` / `%USERPROFILE%`), or
+     * undefined if it cannot be resolved. Lets services place user-global state
+     * (e.g. the update-check cache under `~/.harness/`) without reading
+     * `os.homedir()` directly — keeping them free of `node:*` (P2).
+     */
+    home(): string | undefined;
+}

package/harness/cli/dist/adapters/env/env-port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=env-port.js.map

package/harness/cli/dist/adapters/env/env-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-port.js","sourceRoot":"","sources":["../../../src/adapters/env/env-port.ts"],"names":[],"mappings":""}

package/harness/cli/dist/adapters/env/fake-env.d.ts

@@ -0,0 +1,15 @@
+import type { EnvPort } from './env-port.js';
+/**
+ * Deterministic environment for tests. Seeded with a `{name: value}` map;
+ * records every requested name on `gets` (fakes over mocks).
+ */
+export declare class FakeEnv implements EnvPort {
+    private readonly vars;
+    private readonly homeDir?;
+    readonly gets: string[];
+    /** How many times home() was called (fakes over mocks — assert on history). */
+    homeCalls: number;
+    constructor(vars?: Record<string, string>, homeDir?: string | undefined);
+    get(name: string): string | undefined;
+    home(): string | undefined;
+}

package/harness/cli/dist/adapters/env/fake-env.js

@@ -0,0 +1,24 @@
+/**
+ * Deterministic environment for tests. Seeded with a `{name: value}` map;
+ * records every requested name on `gets` (fakes over mocks).
+ */
+export class FakeEnv {
+    vars;
+    homeDir;
+    gets = [];
+    /** How many times home() was called (fakes over mocks — assert on history). */
+    homeCalls = 0;
+    constructor(vars = {}, homeDir) {
+        this.vars = vars;
+        this.homeDir = homeDir;
+    }
+    get(name) {
+        this.gets.push(name);
+        return this.vars[name];
+    }
+    home() {
+        this.homeCalls++;
+        return this.homeDir;
+    }
+}
+//# sourceMappingURL=fake-env.js.map

package/harness/cli/dist/adapters/env/fake-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-env.js","sourceRoot":"","sources":["../../../src/adapters/env/fake-env.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,OAAO,OAAO;IAMC;IACA;IANV,IAAI,GAAa,EAAE,CAAC;IAC7B,+EAA+E;IAC/E,SAAS,GAAG,CAAC,CAAC;IAEd,YACmB,OAA+B,EAAE,EACjC,OAAgB;QADhB,SAAI,GAAJ,IAAI,CAA6B;QACjC,YAAO,GAAP,OAAO,CAAS;IAChC,CAAC;IAEJ,GAAG,CAAC,IAAY;QACd,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACrB,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACzB,CAAC;IAED,IAAI;QACF,IAAI,CAAC,SAAS,EAAE,CAAC;QACjB,OAAO,IAAI,CAAC,OAAO,CAAC;IACtB,CAAC;CACF"}

package/harness/cli/dist/adapters/env/node-env.d.ts

@@ -0,0 +1,6 @@
+import type { EnvPort } from './env-port.js';
+/** Real environment — wraps `process.env`. */
+export declare class NodeEnv implements EnvPort {
+    get(name: string): string | undefined;
+    home(): string | undefined;
+}

package/harness/cli/dist/adapters/env/node-env.js

@@ -0,0 +1,16 @@
+import { homedir } from 'node:os';
+/** Real environment — wraps `process.env`. */
+export class NodeEnv {
+    get(name) {
+        return process.env[name];
+    }
+    home() {
+        // Prefer the explicit env vars ($HOME on POSIX, %USERPROFILE% on Windows),
+        // then fall back to os.homedir(). `||` (not `??`) so an EMPTY string falls
+        // through to the next source rather than being treated as a resolved value
+        // (companion F001). Empty after all sources ⇒ unresolved ⇒ undefined.
+        const resolved = process.env.HOME || process.env.USERPROFILE || homedir();
+        return resolved ? resolved : undefined;
+    }
+}
+//# sourceMappingURL=node-env.js.map

package/harness/cli/dist/adapters/env/node-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-env.js","sourceRoot":"","sources":["../../../src/adapters/env/node-env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,SAAS,CAAC;AAGlC,8CAA8C;AAC9C,MAAM,OAAO,OAAO;IAClB,GAAG,CAAC,IAAY;QACd,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IAC3B,CAAC;IAED,IAAI;QACF,2EAA2E;QAC3E,2EAA2E;QAC3E,2EAA2E;QAC3E,sEAAsE;QACtE,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,OAAO,EAAE,CAAC;QAC1E,OAAO,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IACzC,CAAC;CACF"}

package/harness/cli/dist/adapters/exec/exec-port.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Exec port — runs a REAL repo command (the P8 "wrap, don't rebuild" capability).
+ *
+ * Verbs invoke this through `ctx.exec` to wrap existing project commands (build,
+ * lint, test…). Injected so verb/loader logic stays unit-testable with `FakeExec`
+ * and never spawns a child directly — `NodeExec` is the only place a child is
+ * spawned for the verb path (KF-06 adapter discipline).
+ */
+export interface ExecResult {
+    /** Child process exit code (127 when the binary could not be spawned). */
+    code: number;
+    stdout: string;
+    stderr: string;
+    /** Convenience: `code === 0`. */
+    ok: boolean;
+}
+export interface ExecPort {
+    /** Spawn `command args` in `opts.cwd` (no shell), capturing code/stdout/stderr. */
+    run(command: string, args: string[], opts: {
+        cwd: string;
+    }): Promise<ExecResult>;
+}

package/harness/cli/dist/adapters/exec/exec-port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=exec-port.js.map

package/harness/cli/dist/adapters/exec/exec-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-port.js","sourceRoot":"","sources":["../../../src/adapters/exec/exec-port.ts"],"names":[],"mappings":""}

package/harness/cli/dist/adapters/exec/fake-exec.d.ts

@@ -0,0 +1,25 @@
+import type { ExecPort, ExecResult } from './exec-port.js';
+/** A scripted result — `ok` is derived from `code`, so callers script only the facts. */
+export interface ExecScript {
+    code: number;
+    stdout?: string;
+    stderr?: string;
+}
+/**
+ * Deterministic exec for tests. Seeded with `{ 'cmd a b': {code,stdout?,stderr?} }`
+ * keyed by full command line; records each `{command,args,cwd}` on `calls` (fakes
+ * over mocks). An unscripted command resolves to a benign success (absent ≠ error,
+ * mirroring FakeFs/FakeProcess); `ok` is always computed from `code`.
+ */
+export declare class FakeExec implements ExecPort {
+    private readonly scripts;
+    readonly calls: {
+        command: string;
+        args: string[];
+        cwd: string;
+    }[];
+    constructor(scripts?: Record<string, ExecScript>);
+    run(command: string, args: string[], opts: {
+        cwd: string;
+    }): Promise<ExecResult>;
+}

package/harness/cli/dist/adapters/exec/fake-exec.js

@@ -0,0 +1,25 @@
+/**
+ * Deterministic exec for tests. Seeded with `{ 'cmd a b': {code,stdout?,stderr?} }`
+ * keyed by full command line; records each `{command,args,cwd}` on `calls` (fakes
+ * over mocks). An unscripted command resolves to a benign success (absent ≠ error,
+ * mirroring FakeFs/FakeProcess); `ok` is always computed from `code`.
+ */
+export class FakeExec {
+    scripts;
+    calls = [];
+    constructor(scripts = {}) {
+        this.scripts = scripts;
+    }
+    run(command, args, opts) {
+        this.calls.push({ command, args, cwd: opts.cwd });
+        const key = [command, ...args].join(' ');
+        const script = this.scripts[key] ?? this.scripts[command] ?? { code: 0 };
+        return Promise.resolve({
+            code: script.code,
+            stdout: script.stdout ?? '',
+            stderr: script.stderr ?? '',
+            ok: script.code === 0,
+        });
+    }
+}
+//# sourceMappingURL=fake-exec.js.map

package/harness/cli/dist/adapters/exec/fake-exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-exec.js","sourceRoot":"","sources":["../../../src/adapters/exec/fake-exec.ts"],"names":[],"mappings":"AASA;;;;;GAKG;AACH,MAAM,OAAO,QAAQ;IAGU;IAFpB,KAAK,GAAuD,EAAE,CAAC;IAExE,YAA6B,UAAsC,EAAE;QAAxC,YAAO,GAAP,OAAO,CAAiC;IAAG,CAAC;IAEzE,GAAG,CAAC,OAAe,EAAE,IAAc,EAAE,IAAqB;QACxD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;QAClD,MAAM,GAAG,GAAG,CAAC,OAAO,EAAE,GAAG,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QACzC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC;QACzE,OAAO,OAAO,CAAC,OAAO,CAAC;YACrB,IAAI,EAAE,MAAM,CAAC,IAAI;YACjB,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,MAAM,EAAE,MAAM,CAAC,MAAM,IAAI,EAAE;YAC3B,EAAE,EAAE,MAAM,CAAC,IAAI,KAAK,CAAC;SACtB,CAAC,CAAC;IACL,CAAC;CACF"}

package/harness/cli/dist/adapters/exec/node-exec.d.ts

@@ -0,0 +1,14 @@
+import type { ExecPort, ExecResult } from './exec-port.js';
+/**
+ * Real process execution — the only place a child is spawned for the verb path.
+ * `shell: false` + an args array means no shell-injection surface (KF-06). Never
+ * rejects: a spawn error or non-zero exit resolves to an `ExecResult` so the verb
+ * handler can map it to an Envelope rather than throwing through the kernel. This
+ * includes a SYNCHRONOUS spawn throw (e.g. a null byte in the command), which is
+ * caught and resolved as code 127 rather than rejecting the promise.
+ */
+export declare class NodeExec implements ExecPort {
+    run(command: string, args: string[], opts: {
+        cwd: string;
+    }): Promise<ExecResult>;
+}

package/harness/cli/dist/adapters/exec/node-exec.js

@@ -0,0 +1,38 @@
+import { spawn } from 'node:child_process';
+/**
+ * Real process execution — the only place a child is spawned for the verb path.
+ * `shell: false` + an args array means no shell-injection surface (KF-06). Never
+ * rejects: a spawn error or non-zero exit resolves to an `ExecResult` so the verb
+ * handler can map it to an Envelope rather than throwing through the kernel. This
+ * includes a SYNCHRONOUS spawn throw (e.g. a null byte in the command), which is
+ * caught and resolved as code 127 rather than rejecting the promise.
+ */
+export class NodeExec {
+    run(command, args, opts) {
+        return new Promise((resolve) => {
+            let stdout = '';
+            let stderr = '';
+            try {
+                const child = spawn(command, args, { cwd: opts.cwd, shell: false });
+                child.stdout?.on('data', (chunk) => {
+                    stdout += chunk.toString();
+                });
+                child.stderr?.on('data', (chunk) => {
+                    stderr += chunk.toString();
+                });
+                child.on('error', (err) => {
+                    resolve({ code: 127, stdout, stderr: stderr + String(err.message ?? err), ok: false });
+                });
+                child.on('close', (code) => {
+                    const exitCode = code ?? 1;
+                    resolve({ code: exitCode, stdout, stderr, ok: exitCode === 0 });
+                });
+            }
+            catch (err) {
+                const message = err instanceof Error ? err.message : String(err);
+                resolve({ code: 127, stdout, stderr: stderr + message, ok: false });
+            }
+        });
+    }
+}
+//# sourceMappingURL=node-exec.js.map

package/harness/cli/dist/adapters/exec/node-exec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-exec.js","sourceRoot":"","sources":["../../../src/adapters/exec/node-exec.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C;;;;;;;GAOG;AACH,MAAM,OAAO,QAAQ;IACnB,GAAG,CAAC,OAAe,EAAE,IAAc,EAAE,IAAqB;QACxD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;YAC7B,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,MAAM,GAAG,EAAE,CAAC;YAChB,IAAI,CAAC;gBACH,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,EAAE,IAAI,EAAE,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,KAAK,EAAE,KAAK,EAAE,CAAC,CAAC;gBACpE,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;oBACjC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAC7B,CAAC,CAAC,CAAC;gBACH,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE;oBACjC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC;gBAC7B,CAAC,CAAC,CAAC;gBACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAG,EAAE,EAAE;oBACxB,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,IAAI,GAAG,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;gBACzF,CAAC,CAAC,CAAC;gBACH,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE;oBACzB,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,CAAC;oBAC3B,OAAO,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,QAAQ,KAAK,CAAC,EAAE,CAAC,CAAC;gBAClE,CAAC,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,MAAM,OAAO,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBACjE,OAAO,CAAC,EAAE,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC,CAAC;YACtE,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/harness/cli/dist/adapters/fs/fake-fs.d.ts

@@ -0,0 +1,22 @@
+import type { FsPort } from './fs-port.js';
+/**
+ * Deterministic filesystem for tests. Seeded with a `{path: contents}` map and
+ * an optional `{dir: entryNames[]}` map; records every probed path on `reads`,
+ * every written path on `writes`, and every `mkdirp` on `mkdirs` (fakes over
+ * mocks — assert on history). Writes mutate the in-memory file map so a later
+ * `exists`/`readText` sees what was written.
+ */
+export declare class FakeFs implements FsPort {
+    private readonly files;
+    private readonly dirs;
+    readonly reads: string[];
+    readonly writes: string[];
+    readonly mkdirs: string[];
+    private readonly madeDirs;
+    constructor(files?: Record<string, string>, dirs?: Record<string, string[]>);
+    exists(path: string): boolean;
+    readText(path: string): string | null;
+    readdir(path: string): string[];
+    mkdirp(path: string): void;
+    writeText(path: string, contents: string): void;
+}

package/harness/cli/dist/adapters/fs/fake-fs.js

@@ -0,0 +1,63 @@
+/**
+ * Deterministic filesystem for tests. Seeded with a `{path: contents}` map and
+ * an optional `{dir: entryNames[]}` map; records every probed path on `reads`,
+ * every written path on `writes`, and every `mkdirp` on `mkdirs` (fakes over
+ * mocks — assert on history). Writes mutate the in-memory file map so a later
+ * `exists`/`readText` sees what was written.
+ */
+export class FakeFs {
+    files;
+    dirs;
+    reads = [];
+    writes = [];
+    mkdirs = [];
+    madeDirs = new Set();
+    constructor(files = {}, dirs = {}) {
+        this.files = files;
+        this.dirs = dirs;
+    }
+    exists(path) {
+        this.reads.push(path);
+        return path in this.files || this.madeDirs.has(path);
+    }
+    readText(path) {
+        this.reads.push(path);
+        return this.files[path] ?? null;
+    }
+    readdir(path) {
+        this.reads.push(path);
+        // Seeded names first, then immediate child dirs created via mkdirp — so a
+        // dir made DURING the test is visible to a later listing, as NodeFs would
+        // be (plan 015: capture mkdirps a bucket; a later sweep readdirs its parent).
+        // Probes tolerate Windows-shaped paths; registered state is canonical
+        // POSIX (plan 017 — Windows-shaped-input sensors run on every OS).
+        const posixPath = path.replace(/\\/g, '/');
+        const names = [...(this.dirs[path] ?? this.dirs[posixPath] ?? [])];
+        const prefix = posixPath.endsWith('/') ? posixPath : `${posixPath}/`;
+        for (const dir of this.madeDirs) {
+            if (dir.startsWith(prefix)) {
+                const name = dir.slice(prefix.length).split(/[\\/]/)[0];
+                if (name && !names.includes(name))
+                    names.push(name);
+            }
+        }
+        return names;
+    }
+    mkdirp(path) {
+        this.mkdirs.push(path);
+        // Register each ancestor segment so exists() models a recursive create
+        // (matches NodeFs.mkdirSync({ recursive: true }); F001). Segments split on
+        // either separator and are stored in canonical POSIX form (plan 017).
+        const parts = path.split(/[\\/]/);
+        for (let i = 1; i <= parts.length; i++) {
+            const seg = parts.slice(0, i).join('/');
+            if (seg)
+                this.madeDirs.add(seg);
+        }
+    }
+    writeText(path, contents) {
+        this.writes.push(path);
+        this.files[path] = contents;
+    }
+}
+//# sourceMappingURL=fake-fs.js.map

package/harness/cli/dist/adapters/fs/fake-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-fs.js","sourceRoot":"","sources":["../../../src/adapters/fs/fake-fs.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,MAAM,OAAO,MAAM;IAOE;IACA;IAPV,KAAK,GAAa,EAAE,CAAC;IACrB,MAAM,GAAa,EAAE,CAAC;IACtB,MAAM,GAAa,EAAE,CAAC;IACd,QAAQ,GAAG,IAAI,GAAG,EAAU,CAAC;IAE9C,YACmB,QAAgC,EAAE,EAClC,OAAiC,EAAE;QADnC,UAAK,GAAL,KAAK,CAA6B;QAClC,SAAI,GAAJ,IAAI,CAA+B;IACnD,CAAC;IAEJ,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;IACvD,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;IAClC,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACtB,0EAA0E;QAC1E,0EAA0E;QAC1E,8EAA8E;QAC9E,sEAAsE;QACtE,mEAAmE;QACnE,MAAM,SAAS,GAAG,IAAI,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;QACnE,MAAM,MAAM,GAAG,SAAS,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,SAAS,GAAG,CAAC;QACrE,KAAK,MAAM,GAAG,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAChC,IAAI,GAAG,CAAC,UAAU,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;gBACxD,IAAI,IAAI,IAAI,CAAC,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC;oBAAE,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACtD,CAAC;QACH,CAAC;QACD,OAAO,KAAK,CAAC;IACf,CAAC;IAED,MAAM,CAAC,IAAY;QACjB,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,uEAAuE;QACvE,2EAA2E;QAC3E,sEAAsE;QACtE,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QAClC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,IAAI,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;YACvC,MAAM,GAAG,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;YACxC,IAAI,GAAG;gBAAE,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,CAAC;IACH,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,QAAgB;QACtC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QACvB,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,QAAQ,CAAC;IAC9B,CAAC;CACF"}

package/harness/cli/dist/adapters/fs/fs-port.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Filesystem port — the side effect `doctor`/config reads sit behind, plus the
+ * writes the scaffolder (`harness new`, plan 006) needs.
+ *
+ * Reads (`exists`/`readText`/`readdir`) and writes (`mkdirp`/`writeText`) are
+ * injected so services stay unit-testable with `FakeFs` and never import
+ * `node:fs`.
+ */
+export interface FsPort {
+    /** True if a path exists on disk. */
+    exists(path: string): boolean;
+    /** File contents as UTF-8, or null if missing/unreadable (never throws). */
+    readText(path: string): string | null;
+    /** Entry names directly inside a directory, or `[]` if missing/unreadable (never throws). */
+    readdir(path: string): string[];
+    /** Recursively create a directory (no-op if it already exists). For the scaffolder. */
+    mkdirp(path: string): void;
+    /** Write UTF-8 text to a path, overwriting. Caller ensures the parent dir exists (mkdirp). */
+    writeText(path: string, contents: string): void;
+}

package/harness/cli/dist/adapters/fs/fs-port.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=fs-port.js.map

package/harness/cli/dist/adapters/fs/fs-port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fs-port.js","sourceRoot":"","sources":["../../../src/adapters/fs/fs-port.ts"],"names":[],"mappings":""}

package/harness/cli/dist/adapters/fs/node-fs.d.ts

@@ -0,0 +1,9 @@
+import type { FsPort } from './fs-port.js';
+/** Real filesystem — the only place `node:fs` is touched. */
+export declare class NodeFs implements FsPort {
+    exists(path: string): boolean;
+    readText(path: string): string | null;
+    readdir(path: string): string[];
+    mkdirp(path: string): void;
+    writeText(path: string, contents: string): void;
+}

package/harness/cli/dist/adapters/fs/node-fs.js

@@ -0,0 +1,30 @@
+import { existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+/** Real filesystem — the only place `node:fs` is touched. */
+export class NodeFs {
+    exists(path) {
+        return existsSync(path);
+    }
+    readText(path) {
+        try {
+            return readFileSync(path, 'utf8');
+        }
+        catch {
+            return null;
+        }
+    }
+    readdir(path) {
+        try {
+            return readdirSync(path);
+        }
+        catch {
+            return [];
+        }
+    }
+    mkdirp(path) {
+        mkdirSync(path, { recursive: true });
+    }
+    writeText(path, contents) {
+        writeFileSync(path, contents, 'utf8');
+    }
+}
+//# sourceMappingURL=node-fs.js.map

package/harness/cli/dist/adapters/fs/node-fs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"node-fs.js","sourceRoot":"","sources":["../../../src/adapters/fs/node-fs.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAG1F,6DAA6D;AAC7D,MAAM,OAAO,MAAM;IACjB,MAAM,CAAC,IAAY;QACjB,OAAO,UAAU,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED,QAAQ,CAAC,IAAY;QACnB,IAAI,CAAC;YACH,OAAO,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QACpC,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,IAAI,CAAC;QACd,CAAC;IACH,CAAC;IAED,OAAO,CAAC,IAAY;QAClB,IAAI,CAAC;YACH,OAAO,WAAW,CAAC,IAAI,CAAC,CAAC;QAC3B,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,EAAE,CAAC;QACZ,CAAC;IACH,CAAC;IAED,MAAM,CAAC,IAAY;QACjB,SAAS,CAAC,IAAI,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACvC,CAAC;IAED,SAAS,CAAC,IAAY,EAAE,QAAgB;QACtC,aAAa,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,CAAC;IACxC,CAAC;CACF"}

package/harness/cli/dist/adapters/git/exec-git.d.ts

@@ -0,0 +1,6 @@
+import type { GitPort } from './git-port.js';
+/** Real git access — wraps `git rev-parse` (read-only, informational). */
+export declare class ExecGit implements GitPort {
+    isRepo(): boolean;
+    currentBranch(): string | null;
+}

package/harness/cli/dist/adapters/git/exec-git.js

@@ -0,0 +1,21 @@
+import { spawnSync } from 'node:child_process';
+/** Real git access — wraps `git rev-parse` (read-only, informational). */
+export class ExecGit {
+    isRepo() {
+        const result = spawnSync('git', ['rev-parse', '--is-inside-work-tree'], {
+            encoding: 'utf8',
+        });
+        return result.status === 0 && result.stdout.trim() === 'true';
+    }
+    currentBranch() {
+        const result = spawnSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], {
+            encoding: 'utf8',
+        });
+        if (result.status !== 0) {
+            return null;
+        }
+        const branch = result.stdout.trim();
+        return branch && branch !== 'HEAD' ? branch : null;
+    }
+}
+//# sourceMappingURL=exec-git.js.map

package/harness/cli/dist/adapters/git/exec-git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"exec-git.js","sourceRoot":"","sources":["../../../src/adapters/git/exec-git.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAG/C,0EAA0E;AAC1E,MAAM,OAAO,OAAO;IAClB,MAAM;QACJ,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,uBAAuB,CAAC,EAAE;YACtE,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QACH,OAAO,MAAM,CAAC,MAAM,KAAK,CAAC,IAAI,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,MAAM,CAAC;IAChE,CAAC;IAED,aAAa;QACX,MAAM,MAAM,GAAG,SAAS,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,cAAc,EAAE,MAAM,CAAC,EAAE;YACrE,QAAQ,EAAE,MAAM;SACjB,CAAC,CAAC;QACH,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YACxB,OAAO,IAAI,CAAC;QACd,CAAC;QACD,MAAM,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;QACpC,OAAO,MAAM,IAAI,MAAM,KAAK,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;IACrD,CAAC;CACF"}

package/harness/cli/dist/adapters/git/fake-git.d.ts

@@ -0,0 +1,15 @@
+import type { GitPort } from './git-port.js';
+/**
+ * Deterministic git for tests. Seeded with repo/branch state; records each
+ * method called on `calls` (fakes over mocks).
+ */
+export declare class FakeGit implements GitPort {
+    private readonly state;
+    readonly calls: string[];
+    constructor(state?: {
+        isRepo?: boolean;
+        branch?: string | null;
+    });
+    isRepo(): boolean;
+    currentBranch(): string | null;
+}