spec-controller 0.1.0-alpha.9 → 0.1.0

package/dist/cli.js

@@ -1,88 +1,4 @@
 #!/usr/bin/env node
-/**
- * The `spec-controller` binary — the top-level command host + dispatcher.
- *
- * Usage:
- *   spec-controller [--store <root>] [--run-id <id>] <command> [command-args]
- *
- * Commands: `balance` — the deterministic reconciliation of scenarios against
- * observed evidence, standalone on the public core + app layer (no engine); `tags` — the
- * @SCN scheme policing itself over the same corpus, which is a fault about the corpus rather
- * than a verdict about its evidence, and so has its own status ladder rather than a fifth
- * meaning on balance's. The `analyse` / `migrate` capabilities are a separate, closed offering
- * built on the same core.
- *
- * Storage is a CROSS-CUTTING host modifier, not a command. A leading `--store <root>`
- * turns any command into a STORED run: the host wraps the command via the kept-run
- * scaffold — a named `<root>/<target>/<run-id>/` directory, the command's outputs routed
- * in, and a `run.yaml` manifest — and hands the command its own clean args, unchanged. So
- * `balance` stays emit-only (its default, no-store output is byte-identical); the store
- * opinion lives at the host, injected via `--store` (required — there is no default, a
- * default would write inside the repo). `--run-id` defaults to a timestamp.
- */
-import { dirname } from "node:path";
-import { runBalance } from "./cli-balance/cli.js";
-import { runTags } from "./corpus/cli.js";
-import { resolveSourceSha, resolveToolIdentity } from "./run-management/resolveRunInputs.js";
-import { executeKeptRun, resolveRunId, } from "./run-management/keptRun.js";
-import { parseHostInvocation, wrapCommandArgv, peekFlag } from "./host.js";
-import { cliRegistry, renderTopLevelHelp } from "./cli-registry.js";
-/** Dispatch a command to its handler with the given (clean or store-wrapped) argv. */
-function runCommand(command, argv) {
-    switch (command) {
-        case "balance":
-            runBalance(argv);
-            return;
-        case "tags":
-            runTags(argv);
-            return;
-        default:
-            process.stderr.write(`spec-controller: unknown command "${command}".\n\n${renderTopLevelHelp(cliRegistry)}\n`);
-            process.exit(1);
-    }
-}
-function main(hostArgv) {
-    const inv = parseHostInvocation(hostArgv);
-    const command = inv.command;
-    if (command === undefined || command === "help" || command === "--help" || command === "-h") {
-        process.stdout.write(renderTopLevelHelp(cliRegistry) + "\n");
-        return;
-    }
-    // No store directive → dispatch the command directly; its output is unchanged.
-    if (inv.store === undefined) {
-        runCommand(command, inv.commandArgs);
-        return;
-    }
-    // Store directive → wrap the command via keptRun. The scaffold makes the run dir, hands
-    // the injected route the two store-dir `--format` specs, and stamps run.yaml. The route
-    // dispatches the command with its own clean args PLUS those specs, so the command's own
-    // writer produces the stored artefacts (byte-identical to a bare `--format` run). The
-    // host peeks the conventional provenance flags off the command args to name the dir +
-    // stamp the manifest, without consuming them (the command still sees them).
-    const runId = resolveRunId({ runId: inv.runId, now: new Date() });
-    const target = peekFlag(inv.commandArgs, "target") ?? "unknown-target";
-    const features = peekFlag(inv.commandArgs, "features");
-    const sourceSha = resolveSourceSha({
-        sourceSha: peekFlag(inv.commandArgs, "source-sha"),
-        targetDir: features !== undefined ? dirname(features) : undefined,
-    }) ?? "unknown";
-    const spec = { storeRoot: inv.store, target, runId };
-    // `mode` is the command's run kind; only `balance` ships today (analyse/migrate are the
-    // private engine's, added when it lands).
-    // The TOOL's own identity (3F-1916) — which spec-controller produced this run, read
-    // from the tool's OWN dir (never cwd, which is the target). "unknown" for a null SHA,
-    // matching sourceSha's own fallback so run.yaml is internally consistent.
-    const toolIdentity = resolveToolIdentity();
-    const meta = {
-        sourceSha,
-        toolSha: toolIdentity.toolSha ?? "unknown",
-        toolVersion: toolIdentity.toolVersion,
-        mode: "balance",
-        date: new Date().toISOString(),
-    };
-    const plan = executeKeptRun(spec, meta, (formatSpecs) => runCommand(command, wrapCommandArgv(inv.commandArgs, [...formatSpecs])));
-    // The command's stdout was routed into the run dir, so tell the operator where it landed.
-    process.stdout.write(plan.runDir + "\n");
-}
+import { main } from "./main.js";
 main(process.argv.slice(2));
 //# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -1 +1 @@
-{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AACjC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC"}

package/dist/deferralTags.d.ts

@@ -1,16 +1,2 @@
-/**
- * The single-sourced STARTER set of recognised community deferral tags — bare names
- * (the `@` is tag-line syntax). A scenario whose tag block carries one of these DEFERS
- * every obligation it raises to a Pending Item (scenario-scope). These are the
- * established Cucumber deferral conventions.
- *
- * This is **product policy, not a core-domain invariant** — an evolvable list of tag
- * strings, so it lives in the application layer, NOT on the v1 core barrel.
- * The core `parseScenarios` recognises only the deferral set it is
- * handed (its default is `[]`, a policy-free pure core); the app is the single source
- * of the starter policy and always passes the resolved set (starter ∪ configured) into
- * the parser at the ingest edge. Both `resolveDeferralTags` (the `@SCN-PND-021` config
- * union) and `renderCommandHelp`'s `--help` listing source this constant.
- */
 export declare const DEFAULT_DEFERRAL_TAGS: readonly string[];
 //# sourceMappingURL=deferralTags.d.ts.map

package/dist/deferralTags.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"deferralTags.d.ts","sourceRoot":"","sources":["../src/deferralTags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAMlD,CAAC"}
+{"version":3,"file":"deferralTags.d.ts","sourceRoot":"","sources":["../src/deferralTags.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,qBAAqB,EAAE,SAAS,MAAM,EAMlD,CAAC"}

package/dist/deferralTags.js

@@ -1,17 +1,3 @@
-/**
- * The single-sourced STARTER set of recognised community deferral tags — bare names
- * (the `@` is tag-line syntax). A scenario whose tag block carries one of these DEFERS
- * every obligation it raises to a Pending Item (scenario-scope). These are the
- * established Cucumber deferral conventions.
- *
- * This is **product policy, not a core-domain invariant** — an evolvable list of tag
- * strings, so it lives in the application layer, NOT on the v1 core barrel.
- * The core `parseScenarios` recognises only the deferral set it is
- * handed (its default is `[]`, a policy-free pure core); the app is the single source
- * of the starter policy and always passes the resolved set (starter ∪ configured) into
- * the parser at the ingest edge. Both `resolveDeferralTags` (the `@SCN-PND-021` config
- * union) and `renderCommandHelp`'s `--help` listing source this constant.
- */
 export const DEFAULT_DEFERRAL_TAGS = [
     "wip",
     "ignore",

package/dist/deferralTags.js.map

@@ -1 +1 @@
-{"version":3,"file":"deferralTags.js","sourceRoot":"","sources":["../src/deferralTags.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,KAAK;IACL,QAAQ;IACR,MAAM;IACN,MAAM;IACN,SAAS;CACV,CAAC"}
+{"version":3,"file":"deferralTags.js","sourceRoot":"","sources":["../src/deferralTags.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,qBAAqB,GAAsB;IACtD,KAAK;IACL,QAAQ;IACR,MAAM;IACN,MAAM;IACN,SAAS;CACV,CAAC"}

package/dist/host.d.ts

@@ -1,50 +1,19 @@
-/**
- * The host-invocation parse — the pure half of the `spec-controller` command host.
- *
- * The shipped binary is `spec-controller [--store <root>] [--run-id <id>] <command>
- * [command-args]`. `--store` / `--run-id` are CROSS-CUTTING host options recognised
- * ONLY in leading position, before the command: storage applies across balance /
- * analyse / migrate, so it belongs at the host (wrapping any command via the kept-run
- * scaffold), not as a peer command and never as a flag inside `balance`. This module
- * holds the pure rules the impure dispatcher (`cli.ts`) drives — parsing the leading
- * options, building the wrapped command argv, and peeking the conventional provenance
- * flags — so the whole host contract is `@unit`-testable with no IO.
- *
- * @SCN-RMG-004 — features/run-management.feature.
- */
-/** A parsed host invocation: leading global options, then the command and its clean args. */
+import { type CommandSpec, type FlagSpec } from "./cli-registry.js";
 export interface HostInvocation {
-    /** The injected store root from a leading `--store <root>`, or undefined (no store). */
     store?: string;
-    /** The mnemonic from a leading `--run-id <id>`, or undefined (→ the timestamp default). */
     runId?: string;
-    /** The command token (e.g. "balance"), or undefined when none was given. */
     command?: string;
-    /** The command's own args — everything after the command token, verbatim. */
     commandArgs: string[];
+    refusal?: string;
 }
-/**
- * Parse the host argv into its leading global options (`--store`, `--run-id`) and the
- * command + its clean args. Global options are recognised ONLY before the command: the
- * first token that is not a consumed global option (or its value) is the command, and
- * everything after it is the command's own args, verbatim. So `--store /s balance
- * --features f` yields the store + `balance` + `[--features, f]`, while `balance --store
- * /s` leaves `--store` in the command's args (a `--store` AFTER the command is the
- * command's own arg, never a host store directive) — the "global before command" contract.
- */
-export declare function parseHostInvocation(argv: readonly string[]): HostInvocation;
-/**
- * Build the wrapped command argv: the command's clean args followed by a repeated
- * `--format <spec>` per store-dir output spec. Pure — the impure runner hands the result
- * straight to the command, so the command's OWN writer produces the stored artefacts
- * (byte-identical to a bare `--format` run; no writer duplication).
- */
+export declare function parseHostInvocation(argv: readonly string[], globalFlags?: readonly FlagSpec[], commands?: readonly string[]): HostInvocation;
 export declare function wrapCommandArgv(commandArgs: readonly string[], formatSpecs: readonly string[]): string[];
-/**
- * Read a `--<name> <value>` flag's value from an arg list WITHOUT consuming it — the host
- * peeks the conventional cross-cutting provenance flags (`--target`, `--features`,
- * `--source-sha`) to name the run dir + stamp run.yaml, while the command still receives
- * them in its own args. Returns undefined when the flag is absent or has no value.
- */
 export declare function peekFlag(argv: readonly string[], name: string): string | undefined;
+export interface UnknownCommandAnswer {
+    exitCode: number;
+    stderr: string;
+}
+export declare function answerUnknownCommand(command: string, help: string): UnknownCommandAnswer;
+export declare function modifiersNotTakenRefusal(inv: HostInvocation, commands?: readonly CommandSpec[]): string | undefined;
+export declare function formatFilePaths(argv: readonly string[]): string[];
 //# sourceMappingURL=host.d.ts.map

package/dist/host.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,6FAA6F;AAC7F,MAAM,WAAW,cAAc;IAC7B,wFAAwF;IACxF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,2FAA2F;IAC3F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4EAA4E;IAC5E,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,EAAE,CAAC;CACvB;AAED;;;;;;;;GAQG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAmB3E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAExG;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlF"}
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAUA,OAAO,EAAe,KAAK,WAAW,EAAE,KAAK,QAAQ,EAAE,MAAM,mBAAmB,CAAC;AAGjF,MAAM,WAAW,cAAc;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,wBAAgB,mBAAmB,CACjC,IAAI,EAAE,SAAS,MAAM,EAAE,EACvB,WAAW,GAAE,SAAS,QAAQ,EAAuB,EACrD,QAAQ,GAAE,SAAS,MAAM,EAAwD,GAChF,cAAc,CAIhB;AA+FD,wBAAgB,eAAe,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,EAAE,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CAExG;AAED,wBAAgB,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CASlF;AAED,MAAM,WAAW,oBAAoB;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,oBAAoB,CAKxF;AAED,wBAAgB,wBAAwB,CACtC,GAAG,EAAE,cAAc,EACnB,QAAQ,GAAE,SAAS,WAAW,EAAyB,GACtD,MAAM,GAAG,SAAS,CASpB;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,EAAE,CASjE"}

package/dist/host.js

@@ -1,61 +1,82 @@
-/**
- * The host-invocation parse — the pure half of the `spec-controller` command host.
- *
- * The shipped binary is `spec-controller [--store <root>] [--run-id <id>] <command>
- * [command-args]`. `--store` / `--run-id` are CROSS-CUTTING host options recognised
- * ONLY in leading position, before the command: storage applies across balance /
- * analyse / migrate, so it belongs at the host (wrapping any command via the kept-run
- * scaffold), not as a peer command and never as a flag inside `balance`. This module
- * holds the pure rules the impure dispatcher (`cli.ts`) drives — parsing the leading
- * options, building the wrapped command argv, and peeking the conventional provenance
- * flags — so the whole host contract is `@unit`-testable with no IO.
- *
- * @SCN-RMG-004 — features/run-management.feature.
- */
-/**
- * Parse the host argv into its leading global options (`--store`, `--run-id`) and the
- * command + its clean args. Global options are recognised ONLY before the command: the
- * first token that is not a consumed global option (or its value) is the command, and
- * everything after it is the command's own args, verbatim. So `--store /s balance
- * --features f` yields the store + `balance` + `[--features, f]`, while `balance --store
- * /s` leaves `--store` in the command's args (a `--store` AFTER the command is the
- * command's own arg, never a host store directive) — the "global before command" contract.
- */
-export function parseHostInvocation(argv) {
-    let store;
-    let runId;
+import { asksForHelp, equalsFormRefusal, givenTwiceRefusal, givenValue, isEqualsForm, missingValueRefusal, valueFlagsOf, } from "./cli-args.js";
+import { cliRegistry } from "./cli-registry.js";
+import { APP_MESSAGES, AppMessage } from "./messages.js";
+export function parseHostInvocation(argv, globalFlags = cliRegistry.global, commands = cliRegistry.commands.map((command) => command.name)) {
+    const read = readHostTokens(argv, globalFlags, commands);
+    const help = argv.slice(0, hostTokenCount(argv, read)).find((token) => TOP_LEVEL_HELP.has(token));
+    return help === undefined ? read : { command: help, commandArgs: [] };
+}
+function hostTokenCount(argv, read) {
+    if (read.refusal !== undefined || read.command === undefined)
+        return argv.length;
+    return argv.length - read.commandArgs.length - 1;
+}
+function readHostTokens(argv, globalFlags, commands) {
+    const modifiers = valueFlagsOf(globalFlags);
+    const values = new Map();
     let i = 0;
     for (; i < argv.length; i++) {
-        const token = argv[i];
-        if (token === "--store" && i + 1 < argv.length) {
-            store = argv[i + 1];
-            i++;
-            continue;
+        const token = argv[i] ?? "";
+        const modifier = modifiers.get(token);
+        if (modifier === undefined) {
+            const refusal = leadingFlagRefusal(token, modifiers, globalFlags);
+            if (refusal !== undefined)
+                return { commandArgs: [], refusal };
+            break;
         }
-        if (token === "--run-id" && i + 1 < argv.length) {
-            runId = argv[i + 1];
-            i++;
-            continue;
-        }
-        break; // first non-global-option token is the command
+        const read = readModifier(token, modifier, argv.slice(i + 1, i + 3), { values, commands });
+        if ("refusal" in read)
+            return { commandArgs: [], refusal: read.refusal };
+        values.set(modifier.name, read.value);
+        i++;
     }
-    return { store, runId, command: argv[i], commandArgs: argv.slice(i + 1) };
+    if (i === argv.length && values.size > 0)
+        return { commandArgs: [], refusal: noCommandRefusal([...values.keys()]) };
+    return {
+        store: values.get("--store"),
+        runId: values.get("--run-id"),
+        command: argv[i],
+        commandArgs: argv.slice(i + 1),
+    };
+}
+function readModifier(token, modifier, [next, after], read) {
+    if (read.values.has(modifier.name))
+        return { refusal: givenTwiceRefusal(token, "spec-controller") };
+    const value = givenValue(next);
+    if (value === undefined)
+        return { refusal: missingValueRefusal(token, modifier, "spec-controller") };
+    if (read.commands.includes(value) && (after === undefined || after.startsWith("-"))) {
+        return { refusal: commandAsValueRefusal(token, modifier, value) };
+    }
+    return { value };
+}
+function noCommandRefusal(given) {
+    return (`${APP_MESSAGES[AppMessage.NoCommandAfterModifiers](given.join(", "))}\n` +
+        APP_MESSAGES[AppMessage.SeeCommandsAndModifiers]());
+}
+function commandAsValueRefusal(token, modifier, command) {
+    return (`${APP_MESSAGES[AppMessage.ModifierTookCommand](token, command)}\n` +
+        `${APP_MESSAGES[AppMessage.GiveModifierItsOwnValue](token, modifier.arg, command)} ` +
+        APP_MESSAGES[AppMessage.SeeCommandsAndModifiers]());
+}
+function leadingFlagRefusal(token, modifiers, globalFlags) {
+    if (isEqualsForm(token))
+        return equalsFormRefusal(token, modifiers, "spec-controller");
+    if (isFlagOutOfPlace(token))
+        return flagBeforeCommandRefusal(token, globalFlags);
+    return undefined;
+}
+const TOP_LEVEL_HELP = new Set(["--help", "-h"]);
+function isFlagOutOfPlace(token) {
+    return token.length > 1 && token.startsWith("-") && !TOP_LEVEL_HELP.has(token);
+}
+function flagBeforeCommandRefusal(flag, globalFlags) {
+    const modifiers = globalFlags.map((modifier) => modifier.name).join(", ");
+    return `${APP_MESSAGES[AppMessage.FlagBeforeCommand](flag, modifiers)}\n${APP_MESSAGES[AppMessage.SeeCommandsAndModifiers]()}`;
 }
-/**
- * Build the wrapped command argv: the command's clean args followed by a repeated
- * `--format <spec>` per store-dir output spec. Pure — the impure runner hands the result
- * straight to the command, so the command's OWN writer produces the stored artefacts
- * (byte-identical to a bare `--format` run; no writer duplication).
- */
 export function wrapCommandArgv(commandArgs, formatSpecs) {
     return [...commandArgs, ...formatSpecs.flatMap((spec) => ["--format", spec])];
 }
-/**
- * Read a `--<name> <value>` flag's value from an arg list WITHOUT consuming it — the host
- * peeks the conventional cross-cutting provenance flags (`--target`, `--features`,
- * `--source-sha`) to name the run dir + stamp run.yaml, while the command still receives
- * them in its own args. Returns undefined when the flag is absent or has no value.
- */
 export function peekFlag(argv, name) {
     const flag = `--${name}`;
     for (let i = 0; i < argv.length; i++) {
@@ -66,4 +87,32 @@ export function peekFlag(argv, name) {
     }
     return undefined;
 }
+export function answerUnknownCommand(command, help) {
+    return {
+        exitCode: 2,
+        stderr: `spec-controller: ${APP_MESSAGES[AppMessage.UnknownCommand](command)}\n\n${help}\n`,
+    };
+}
+export function modifiersNotTakenRefusal(inv, commands = cliRegistry.commands) {
+    const entry = commands.find((command) => command.name === inv.command);
+    if (entry?.acceptsHostModifiers !== false || asksForHelp(inv.commandArgs))
+        return undefined;
+    const given = [inv.store === undefined ? [] : ["--store"], inv.runId === undefined ? [] : ["--run-id"]].flat();
+    if (given.length === 0)
+        return undefined;
+    return (`${APP_MESSAGES[AppMessage.HostUsageError](APP_MESSAGES[AppMessage.ModifiersNotTaken](entry.name, given.join(", ")))}\n` +
+        APP_MESSAGES[AppMessage.RunWithoutModifiers](entry.name));
+}
+export function formatFilePaths(argv) {
+    const paths = [];
+    argv.forEach((token, index) => {
+        const value = argv[index + 1];
+        if (token !== "--format" || value === undefined)
+            return;
+        const colon = value.indexOf(":");
+        if (colon !== -1)
+            paths.push(value.slice(colon + 1));
+    });
+    return paths;
+}
 //# sourceMappingURL=host.js.map

package/dist/host.js.map

@@ -1 +1 @@
-{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAcH;;;;;;;;GAQG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAuB;IACzD,IAAI,KAAyB,CAAC;IAC9B,IAAI,KAAyB,CAAC;IAC9B,IAAI,CAAC,GAAG,CAAC,CAAC;IACV,OAAO,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QAC5B,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,CAAC,CAAC;QACtB,IAAI,KAAK,KAAK,SAAS,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAC/C,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,IAAI,KAAK,KAAK,UAAU,IAAI,CAAC,GAAG,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC;YAChD,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YACpB,CAAC,EAAE,CAAC;YACJ,SAAS;QACX,CAAC;QACD,MAAM,CAAC,+CAA+C;IACxD,CAAC;IACD,OAAO,EAAE,KAAK,EAAE,KAAK,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,CAAC,EAAE,CAAC;AAC5E,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,WAA8B,EAAE,WAA8B;IAC5F,OAAO,CAAC,GAAG,WAAW,EAAE,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,UAAU,EAAE,IAAI,CAAC,CAAC,CAAC,CAAC;AAChF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAuB,EAAE,IAAY;IAC5D,MAAM,IAAI,GAAG,KAAK,IAAI,EAAE,CAAC;IACzB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,IAAI,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACrC,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;YACrB,MAAM,KAAK,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;YAC1B,OAAO,KAAK,KAAK,SAAS,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,CAAC;IACH,CAAC;IACD,OAAO,SAAS,CAAC;AACnB,CAAC"}
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"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"}

package/dist/ingest/ciSourcePaths.d.ts

@@ -1,46 +1,7 @@
-/**
- * Resolve a CI input to the workflow files it names (@SCN-USG-006, 3F-2497).
- *
- * A target's pipeline is routinely split across files — a nightly sweep, a security
- * scan — and reading one of them scores the rest against the target twice over: a
- * NAMED check enforced elsewhere is called a watermelon it is not, an UNNAMED one
- * never reaches the books at all (3F-2238).
- *
- * THIS IS THE ONLY PLACE THAT KNOWS A CI INPUT CAN BE A DIRECTORY. The core takes
- * anonymous source strings so a second ecosystem can supply its own; teaching it to
- * walk a folder would import a filesystem and one provider's layout into a pure
- * parser and close that seam for good. So the walk lives here, at the edge that
- * already resolved `.github/workflows/ci.yml`, and the edge knows exactly as much
- * about GitHub after this slice as it did before.
- *
- * Pure, with the filesystem injected — the resolution rules are the part worth
- * asserting directly, and a fixture tree can only show one of them going wrong at a
- * time.
- */
-/** The filesystem reads the resolution needs, injected so the rules stay pure. */
 export interface CiPathReader {
     exists(path: string): boolean;
     isDirectory(path: string): boolean;
     readDir(path: string): string[];
 }
-/** The real filesystem, for the CLI edge. */
-export declare const NODE_CI_PATH_READER: CiPathReader;
-/**
- * The workflow files a CI input names: every workflow in a directory, or the single
- * file itself.
- *
- * Sorted, so two runs over one tree cannot differ and a diff of two reports never
- * turns on `readdir` ordering.
- *
- * A FILE RESOLVES TO ITSELF ALONE. Sweeping its parent directory would silently widen
- * a caller's deliberate scope, which is the promise @SCN-USG-008 pins at the report level.
- *
- * An absent path resolves to nothing — no sources, no commands, every static check
- * read as unenforced. That over-reports gaps and hides none, the same fail-safe
- * direction `ciRunCommands` takes on a document it cannot parse. The HARD error for a
- * path the caller SUPPLIED and that does not exist is @SCN-CLI-002's, raised upstream;
- * reaching here with nothing means the DEFAULT found no workflows, which is a fact
- * about the target rather than a mistake by its author.
- */
 export declare function ciSourcePathsOf(ciPath: string, reader?: CiPathReader): string[];
 //# sourceMappingURL=ciSourcePaths.d.ts.map

package/dist/ingest/ciSourcePaths.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ciSourcePaths.d.ts","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAKH,kFAAkF;AAClF,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAED,6CAA6C;AAC7C,eAAO,MAAM,mBAAmB,EAAE,YAIjC,CAAC;AAKF;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,YAAkC,GACzC,MAAM,EAAE,CAQV"}
+{"version":3,"file":"ciSourcePaths.d.ts","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,YAAY;IAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAC9B,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;CACjC;AAUD,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,MAAM,GAAE,YAAkC,GACzC,MAAM,EAAE,CAQV"}

package/dist/ingest/ciSourcePaths.js

@@ -1,49 +1,11 @@
-/**
- * Resolve a CI input to the workflow files it names (@SCN-USG-006, 3F-2497).
- *
- * A target's pipeline is routinely split across files — a nightly sweep, a security
- * scan — and reading one of them scores the rest against the target twice over: a
- * NAMED check enforced elsewhere is called a watermelon it is not, an UNNAMED one
- * never reaches the books at all (3F-2238).
- *
- * THIS IS THE ONLY PLACE THAT KNOWS A CI INPUT CAN BE A DIRECTORY. The core takes
- * anonymous source strings so a second ecosystem can supply its own; teaching it to
- * walk a folder would import a filesystem and one provider's layout into a pure
- * parser and close that seam for good. So the walk lives here, at the edge that
- * already resolved `.github/workflows/ci.yml`, and the edge knows exactly as much
- * about GitHub after this slice as it did before.
- *
- * Pure, with the filesystem injected — the resolution rules are the part worth
- * asserting directly, and a fixture tree can only show one of them going wrong at a
- * time.
- */
 import { existsSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
-/** The real filesystem, for the CLI edge. */
-export const NODE_CI_PATH_READER = {
+const NODE_CI_PATH_READER = {
     exists: existsSync,
     isDirectory: (path) => statSync(path).isDirectory(),
     readDir: readdirSync,
 };
-/** Both YAML spellings: a target picks one, and the tool does not get to mind which. */
 const WORKFLOW_EXTENSIONS = [".yml", ".yaml"];
-/**
- * The workflow files a CI input names: every workflow in a directory, or the single
- * file itself.
- *
- * Sorted, so two runs over one tree cannot differ and a diff of two reports never
- * turns on `readdir` ordering.
- *
- * A FILE RESOLVES TO ITSELF ALONE. Sweeping its parent directory would silently widen
- * a caller's deliberate scope, which is the promise @SCN-USG-008 pins at the report level.
- *
- * An absent path resolves to nothing — no sources, no commands, every static check
- * read as unenforced. That over-reports gaps and hides none, the same fail-safe
- * direction `ciRunCommands` takes on a document it cannot parse. The HARD error for a
- * path the caller SUPPLIED and that does not exist is @SCN-CLI-002's, raised upstream;
- * reaching here with nothing means the DEFAULT found no workflows, which is a fact
- * about the target rather than a mistake by its author.
- */
 export function ciSourcePathsOf(ciPath, reader = NODE_CI_PATH_READER) {
     if (!reader.exists(ciPath))
         return [];

package/dist/ingest/ciSourcePaths.js.map

@@ -1 +1 @@
-{"version":3,"file":"ciSourcePaths.js","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AASjC,6CAA6C;AAC7C,MAAM,CAAC,MAAM,mBAAmB,GAAiB;IAC/C,MAAM,EAAE,UAAU;IAClB,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;IACnD,OAAO,EAAE,WAAW;CACrB,CAAC;AAEF,wFAAwF;AACxF,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,SAAuB,mBAAmB;IAE1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,MAAM;SACV,OAAO,CAAC,MAAM,CAAC;SACf,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;SACvE,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC"}
+{"version":3,"file":"ciSourcePaths.js","sourceRoot":"","sources":["../../src/ingest/ciSourcePaths.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAC5D,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQjC,MAAM,mBAAmB,GAAiB;IACxC,MAAM,EAAE,UAAU;IAClB,WAAW,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,WAAW,EAAE;IACnD,OAAO,EAAE,WAAW;CACrB,CAAC;AAEF,MAAM,mBAAmB,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE9C,MAAM,UAAU,eAAe,CAC7B,MAAc,EACd,SAAuB,mBAAmB;IAE1C,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC;QAAE,OAAO,EAAE,CAAC;IACtC,IAAI,CAAC,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;QAAE,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,OAAO,MAAM;SACV,OAAO,CAAC,MAAM,CAAC;SACf,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC;SACvE,IAAI,EAAE;SACN,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC,CAAC;AACvC,CAAC"}

package/dist/ingest/gherkinValidation.d.ts

@@ -1,93 +1,13 @@
-/**
- * The Gherkin VALIDATOR — the feature corpus's integrity checkpoint (@SCN-CLI-016, 3F-1767).
- *
- * WHY THIS EXISTS. The feature corpus is the ledger's DEBIT side, and it was read by a
- * hand-rolled TAG-LINE SCAN (`parseScenarios`) that never looked for a `Scenario:` header at
- * all: a scenario EXISTED purely because an `@SCN-FFF-NNN` tag line did. So a
- * malformed tag line simply STOPPED BEING A TAG LINE, and its scenario ceased to exist —
- * silently. One stray character, in a file cucumber itself rejects, deleted a failing row and
- * turned an out-of-balance run (exit 1) into a clean BALANCED (exit 0). A dropped scenario
- * cannot even reconcile `missing`, because it was never raised to be missing: the run reads
- * CLEANER THAN REALITY. That is the false-green this tool exists to prevent, aimed at itself.
- *
- * THE FIX (this slice). VALIDATE every feature file with the REAL Gherkin parser — the same one
- * cucumber uses. A file the parser rejects is an input the tool CANNOT READ, and the CLI refuses
- * it: exit 2, halting before reconciling (@SCN-CLI-014/015's Rule — "an input the tool cannot read
- * is a usage error, never a verdict" — extended from the OBSERVATION side to the OBLIGATION side).
- *
- * VALIDATION IS HALF THE STORY. This decides whether a feature file can be READ at all; the corpus
- * is then EXTRACTED from the same real AST by `parseScenarios` (@SCN-LDG-020, 3F-1775), so the
- * scenarios spec-controller reconciles carry exactly the tags cucumber gives them — Feature/Rule
- * tag inheritance included. One reading of the file, not two.
- *
- * PURE: `string → parse errors`. No fs, no process — the file READ lives beside it at the ingest
- * edge, as it does for every other input.
- *
- * WHY IT LIVES IN THE APP, NOT CORE. Core's barrel is the v1 contract surface downstream consumers
- * build on. Since 3F-3449 nothing reds when a symbol is added there — the guard that reconciled it
- * both directions is gone — so keeping it narrow is a discipline rather than a gate. This validator
- * is an INGEST concern (it decides whether an input can be read at all), not part of the
- * reconciliation contract, so it belongs with the other readers at the app edge and the v1 surface
- * stays untouched.
- */
-/** A Gherkin parse failure: the file could not be read as Gherkin at all. */
 export interface GherkinParseError {
-    /** The offending file, as supplied (the operator's locator — what to go and fix). */
     file: string;
-    /** The parser's own message, verbatim — WHAT broke, in the parser's words. */
     message: string;
 }
-/**
- * Validate one `.feature` source with the real Gherkin parser. Returns the parse errors it
- * reports — empty when the file is well-formed Gherkin.
- *
- * The parser is authoritative BY CONSTRUCTION: it is cucumber's own. A file it rejects is one
- * cucumber would refuse to RUN, so a scenario corpus built from it would be a FICTION — which is
- * precisely how a corrupt spec used to read balanced.
- *
- * A parse failure is reported, never thrown: the CLI edge routes it to stderr + exit 2 (the
- * shared typed-error surface), so it can never reach Node's default exit 1 and masquerade as an
- * out-of-balance verdict (@SCN-CLI-014's collision, on the obligation side).
- *
- * @SCN-CLI-016 (3F-1773).
- */
 export declare function parseErrorsIn(file: string, source: string): GherkinParseError[];
-/**
- * The corpus-level REFUSAL (@SCN-GPG-001, 3F-2817). A parse failure is reported per file by
- * `parseErrorsIn` above; this is how a reader of the WHOLE corpus says no.
- *
- * WHY IT CARRIES EVERY FILE. The balance CLI already names every unparseable file it found
- * (@SCN-CLI-016), and a refusal raised at the first bad one would silently narrow that message —
- * a behaviour change dressed as an implementation detail. So the discovery collects the corpus
- * and refuses ONCE, carrying the lot in discovery order.
- *
- * The rendered message is the parser's words, per file, verbatim: a reader must be told WHAT
- * broke by the parser rather than by our paraphrase of it.
- */
 export declare class UnreadableFeatureCorpusError extends Error {
     readonly errors: readonly GherkinParseError[];
     constructor(errors: readonly GherkinParseError[]);
 }
-/**
- * The corpus-level ABSENCE refusal (@SCN-CLI-017, 3F-3345) — sibling to the parse refusal above,
- * and deliberately the same shape: the reader refuses ONCE, and each command decides what the
- * refusal means for it.
- *
- * WHY A TYPED ERROR RATHER THAN AN EMPTY CORPUS. The obvious fix is for `discoverFeatures` to hand
- * back `[]` when the directory is not there. Measured, that would ship a NEW false green in a
- * second command: `spec-controller tags` reaches the same reader through `readCorpusInputs`, whose
- * GENERIC catch is the only thing turning an absent corpus — and, since `tags` carries no
- * `checkInputsExist`, a supplied-but-absent `--features` too — into `The corpus could not be
- * read: …` at exit 2. Tolerance at the reader turns both into `tags: OK …` at exit 0, inside the
- * slice whose whole purpose is killing a vacuous certification. Typed, both survive untouched:
- * this IS an `Error`, so it still lands in that generic catch.
- *
- * IT CARRIES THE DIRECTORY because the report is owed the name of what it examined — "I found no
- * record" and "I found no regression" must never wear one word (3F-2947), and a consumer told
- * their corpus is empty deserves to know which directory was read to reach that.
- */
 export declare class MissingFeatureCorpusError extends Error {
-    /** The directory that is not there — as resolved, so a reader can print the path examined. */
     readonly directory: string;
     constructor(directory: string);
 }

package/dist/ingest/gherkinValidation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"gherkinValidation.d.ts","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAKH,6EAA6E;AAC7E,MAAM,WAAW,iBAAiB;IAChC,qFAAqF;IACrF,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAa/E;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;gBAElC,MAAM,EAAE,SAAS,iBAAiB,EAAE;CAUjD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,8FAA8F;IAC9F,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAK9B"}
+{"version":3,"file":"gherkinValidation.d.ts","sourceRoot":"","sources":["../../src/ingest/gherkinValidation.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,iBAAiB,EAAE,CAU/E;AAED,qBAAa,4BAA6B,SAAQ,KAAK;IACrD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;gBAElC,MAAM,EAAE,SAAS,iBAAiB,EAAE;CAUjD;AAED,qBAAa,yBAA0B,SAAQ,KAAK;IAClD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;gBAEf,SAAS,EAAE,MAAM;CAK9B"}