@opengsd/gsd-core 1.11.0 → 1.13.0

package/gsd-core/bin/lib/command-arg-projection.cjs

@@ -2,41 +2,171 @@
 /**
  * Command Argument Projection Module (ADR-457 build-at-publish: the
  * hand-written bin/lib/command-arg-projection.cjs collapsed to a TypeScript
- * source of truth). Behaviour is preserved byte-for-behaviour from the prior
- * hand-written .cjs; only types are added.
+ * source of truth).
+ *
+ * ADR-3473 §8.4 ("failure is a value"): `parseNamedArgs` is now strict and
+ * returns a `Result` instead of silently accepting unrecognized or stray
+ * positional tokens. See .gsd/phase/feat-3884-failure-is-a-value/40-design.md
+ * for the full behavior table (A1-A18) and negative-space section (N1-N8).
  *
  * Shared helpers for command-family adapters to project argv tokens into
  * typed named values and multi-word segments.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.isFlagToken = isFlagToken;
 exports.parseNamedArgs = parseNamedArgs;
+exports.parseNamedArgsOrExit = parseNamedArgsOrExit;
 exports.parseMultiwordArg = parseMultiwordArg;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { ERROR_REASON, formatDiagnosticToken } = io;
+// ─── Internal helpers ─────────────────────────────────────────────────────────
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
 /**
- * Extract named --flag <value> pairs from an args array.
- * Returns an object mapping flag names to their values (null if absent).
- * Flags listed in `booleanFlags` are treated as booleans.
+ * ADR-3473 Decision 2: both ends of this seam are gsd-core's own source, so a
+ * malformed spec (a stale call site still using the legacy
+ * `parseNamedArgs(args, valueFlags, booleanFlags)` shape, or a missing spec
+ * entirely) is an internal invariant violation, not user input — it throws
+ * loudly instead of destructuring `undefined` off a Result.
+ */
+function assertValidSpec(spec) {
+    if (!isPlainObject(spec)) {
+        throw new TypeError('parseNamedArgs: spec must be an object of shape ' +
+            '{ valueFlags?: string[], booleanFlags?: string[], positionals: number | "rest" }. ' +
+            'Received a missing, array, or non-object value — this is the legacy ' +
+            'parseNamedArgs(args, valueFlags, booleanFlags) call shape, retired by ADR-3473 §8.4.');
+    }
+    const positionals = spec.positionals;
+    const positionalsValid = positionals === 'rest' ||
+        (typeof positionals === 'number' && Number.isInteger(positionals) && positionals >= 0);
+    if (!positionalsValid) {
+        throw new TypeError('parseNamedArgs: spec.positionals must be a non-negative integer or the literal "rest" ' +
+            `— received ${JSON.stringify(positionals)}.`);
+    }
+}
+// Single predicate reused for both extraction (a value beginning with a
+// single `-` is a value, not a flag) and validation (negative space N5).
+// Exported for init-command-router's #3865 --phase alias normalization,
+// which needs the same flag-shape test before deciding whether args[2] is a
+// phase positional or a flag token.
+function isFlagToken(tok) {
+    return tok.startsWith('--');
+}
+// ─── parseNamedArgs ───────────────────────────────────────────────────────────
+/**
+ * Project argv tokens into typed named values, then strictly validate every
+ * token past the caller's declared positional boundary.
+ *
+ * Extraction (unchanged semantics, #312): first occurrence wins; a value
+ * flag whose next token is absent or starts with `--` yields `null` (this is
+ * NOT a validation error — see the value-flag branch below); boolean flags
+ * and optional-value flags (`optionalValueFlags`, #2932's `--wave` shape) are
+ * presence tests. Kept as a single first-index Map so the flag loops don't
+ * each re-scan argv — O(argv + flags) instead of O(flags * argv).
+ *
+ * Validation (skipped entirely when `positionals === 'rest'`): a single
+ * left-to-right cursor walk from `spec.positionals`, per the design doc's
+ * Kernighan's Law note — debuggable over clever, never a set-difference.
  */
-function parseNamedArgs(args, valueFlags = [], booleanFlags = []) {
-    // Index each token's first position once (firstIndex.get(t) ?? -1 === args.indexOf(t),
-    // firstIndex.has(t) === args.includes(t)) so the flag loops below don't each re-scan
-    // argv — O(argv + flags) instead of O(flags * argv). Semantics are unchanged. (#312)
+function parseNamedArgs(args, spec) {
+    assertValidSpec(spec);
+    const valueFlags = spec.valueFlags ?? [];
+    const booleanFlags = spec.booleanFlags ?? [];
+    const optionalValueFlags = spec.optionalValueFlags ?? [];
     const firstIndex = new Map();
     for (let i = 0; i < args.length; i++) {
         if (!firstIndex.has(args[i]))
             firstIndex.set(args[i], i);
     }
-    const result = {};
+    const data = {};
     for (const flag of valueFlags) {
         const idx = firstIndex.has(`--${flag}`) ? firstIndex.get(`--${flag}`) : -1;
-        result[flag] =
-            idx !== -1 && args[idx + 1] !== undefined && !args[idx + 1].startsWith('--')
+        data[flag] =
+            idx !== -1 && args[idx + 1] !== undefined && !isFlagToken(args[idx + 1])
                 ? args[idx + 1]
                 : null;
     }
     for (const flag of booleanFlags) {
-        result[flag] = firstIndex.has(`--${flag}`);
+        data[flag] = firstIndex.has(`--${flag}`);
+    }
+    // Optional-value flags (#2932: `--wave`-shaped) — presence-only, exactly
+    // like booleanFlags. The value (if any) is deliberately not surfaced here;
+    // see the NamedArgSpec.optionalValueFlags JSDoc.
+    for (const flag of optionalValueFlags) {
+        data[flag] = firstIndex.has(`--${flag}`);
+    }
+    if (spec.positionals === 'rest') {
+        return { ok: true, data };
+    }
+    const valueFlagSet = new Set(valueFlags);
+    const booleanFlagSet = new Set(booleanFlags);
+    const optionalValueFlagSet = new Set(optionalValueFlags);
+    const flagList = [
+        ...valueFlags.map((f) => `--${f} <value>`),
+        ...booleanFlags.map((f) => `--${f}`),
+        ...optionalValueFlags.map((f) => `--${f} [value]`),
+    ];
+    let i = spec.positionals;
+    while (i < args.length) {
+        const tok = args[i];
+        if (isFlagToken(tok)) {
+            const name = tok.slice(2);
+            if (valueFlagSet.has(name)) {
+                // A value flag whose next token is absent or flag-shaped resolves to
+                // `null` in `data` (see the extraction loop above) — this is NOT an
+                // error (#3180/behavior-lock: emptyPrdValueIsFalsyAndTreatedAsAbsent,
+                // section-manifest-init-facts.test.cjs "flag-shaped value"). Advance
+                // by 1 so the following flag token is validated on its own merits on
+                // the next iteration.
+                const next = args[i + 1];
+                i += next !== undefined && !isFlagToken(next) ? 2 : 1;
+                continue;
+            }
+            if (booleanFlagSet.has(name)) {
+                i += 1;
+                continue;
+            }
+            if (optionalValueFlagSet.has(name)) {
+                const next = args[i + 1];
+                i += next !== undefined && !isFlagToken(next) ? 2 : 1;
+                continue;
+            }
+            const reason = flagList.length > 0
+                ? `unknown flag ${formatDiagnosticToken(tok)}; accepted: ${flagList.join(', ')}`
+                : `unknown flag ${formatDiagnosticToken(tok)}; this command accepts no flags`;
+            return { ok: false, kind: 'InvalidArgs', arg: tok, reason, exitReason: ERROR_REASON.USAGE };
+        }
+        return {
+            ok: false,
+            kind: 'InvalidArgs',
+            arg: tok,
+            reason: `unexpected positional argument ${formatDiagnosticToken(tok)}`,
+            exitReason: ERROR_REASON.USAGE,
+        };
+    }
+    return { ok: true, data };
+}
+/**
+ * Thin projection over `parseNamedArgs`: on `ok:false` it calls
+ * `fail(result.reason, result.exitReason)` and then throws.
+ *
+ * The trailing throw exists for two reasons: (1) TypeScript's control-flow
+ * analysis needs a `never`-returning path so callers can destructure the
+ * return value without a null check; (2) it is a fail-closed backstop — the
+ * `fail` callbacks in this repo are `never`-returning at runtime (`io.error`
+ * calls `process.exit(1)`) but are typed `void`, so if a caller ever passes a
+ * `fail` that actually returns, this still halts instead of falling through
+ * with a half-built `ParsedNamedArgs`.
+ */
+function parseNamedArgsOrExit(args, spec, fail) {
+    const result = parseNamedArgs(args, spec);
+    if (!result.ok) {
+        fail(result.reason, result.exitReason);
+        throw new Error(`parseNamedArgsOrExit: fail() returned instead of exiting (arg: ${result.arg})`);
     }
-    return result;
+    return result.data;
 }
 /**
  * Collect all tokens after --flag until the next --flag or end of args.

package/gsd-core/bin/lib/command-routing-hub.cjs

@@ -19,8 +19,16 @@
  * Invariants:
  *   - Hub always routes through CJS handlers. There is no SDK path (#175).
  *   - Hub never prints to stdout/stderr, never calls process.exit.
- *   - Hub never throws — all internal throws are caught and converted to
- *     { ok: false, kind: 'HandlerFailure', message, cause }.
+ *   - Hub never throws for an ordinary handler exception — those are caught
+ *     and converted to { ok: false, kind: 'HandlerFailure', message, cause }.
+ *   - EXCEPTION (ADR-3889): a thrown ExitError (the process-exit seam in
+ *     src/cli-exit.cts, e.g. from io.cts's error()) is deliberately
+ *     RE-THROWN, never converted — the throwing handler has already written
+ *     its own stderr and is terminating with a specific exit code; wrapping
+ *     it as a HandlerFailure would re-derive a generic message from
+ *     ExitError's constructor default and print a second, wrong stderr line.
+ *     It propagates through every caller up to the runMain() at the CLI
+ *     entrypoint, the only place ExitError is meant to be caught.
  *   - The kind taxonomy is closed. Callers switch on ERROR_KINDS values.
  *   - Each error variant carries ONLY its own typed payload (#176).
  *     No cross-variant `message`/`details` escape hatches.
@@ -33,6 +41,9 @@ const event_cjs_1 = require("./observability/event.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const observabilityLogger = require("./observability/logger.cjs");
 const { createNoOpLogger } = observabilityLogger;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { ExitError } = cliExitModule;
 // ─── Error kind constants ─────────────────────────────────────────────────────
 /**
  * Closed error-kind enum. Export as a frozen object so callers can switch on
@@ -233,6 +244,24 @@ function createHub({ cjsRegistry, manifest, logger } = {}) {
             result = _dispatch(req);
         }
         catch (err) {
+            // ADR-3889: a handler that calls io.cts's error() (or otherwise throws
+            // ExitError directly) is deliberately terminating the CLI with a
+            // specific exit code and a stderr write it has ALREADY performed
+            // itself. Swallowing that into a HandlerFailure and re-deriving a
+            // message from err.message (ExitError's generic "process exit N"
+            // constructor default, since error() passes no message) would both
+            // duplicate the stderr output and discard the real exit code — this
+            // was invisible before ADR-3889 because io.cts's error() called
+            // process.exit() directly, which this try/catch could never observe
+            // (a process.exit() call terminates synchronously; it does not throw
+            // and unwind through here). Re-throwing preserves that same
+            // non-observability now that the termination mechanism is a throw:
+            // it propagates past this hub, past every non-family-router caller,
+            // up to the runMain() at the CLI entrypoint, which is the ONLY place
+            // ExitError is meant to be caught.
+            if (err instanceof ExitError) {
+                throw err;
+            }
             if (err instanceof Error) {
                 result = makeHandlerFailure(err.message, err);
             }