@opengsd/gsd-core 1.11.0 → 1.12.0

package/gsd-core/bin/lib/ui-consideration-probe.cjs

@@ -32,6 +32,9 @@ exports.analyzeCoverage = analyzeCoverage;
 exports.proposeElements = proposeElements;
 exports.autoResolve = autoResolve;
 const probe_core_cjs_1 = require("./probe-core.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cliExitModule = require("./cli-exit.cjs");
+const { runMain } = cliExitModule;
 /**
  * Word-boundary cues mapping element prose -> UI element kind.
  * Heuristic and intentionally lossy; an authored `elements` array overrides it. Every pattern is a
@@ -245,5 +248,10 @@ function autoResolve(items) {
  * so it runs only when the compiled `.cjs` is executed directly.
  */
 if (require.main === module) {
-    (0, probe_core_cjs_1.runProbeCli)((elements, resolutions) => analyzeCoverage(elements, resolutions), { usage: 'ui-consideration-probe.cjs <elements.json> [resolutions.json]' });
+    // runProbeCli's default `exit` now throws ExitError (src/probe-core.cts) rather
+    // than calling process.exit directly, so this entry point must run under
+    // runMain to translate that throw into process.exitCode.
+    runMain(() => {
+        (0, probe_core_cjs_1.runProbeCli)((elements, resolutions) => analyzeCoverage(elements, resolutions), { usage: 'ui-consideration-probe.cjs <elements.json> [resolutions.json]' });
+    });
 }

package/gsd-core/bin/lib/ui-safety-gate.cjs

@@ -1,7 +1,7 @@
 "use strict";
 /**
  * UI Safety Gate — shell-free implementation (ADR-457 build-at-publish: the
- * hand-written bin/lib/ui-safety-gate.cjs collapsed to a TypeScript source of
+ * hand-written root copy of this file collapsed to a TypeScript source of
  * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
  * .cjs; only types are added.
  *
@@ -22,13 +22,17 @@
  *
  * CLI usage — reads phase-section text from STDIN to avoid ARG_MAX limits:
  *   echo "$PHASE_SECTION" | node gsd-core/bin/lib/ui-safety-gate.cjs
- *   echo $?   → 0 if UI tokens found, 1 if not, 2 on usage error
+ *   echo $?   → 0 if UI tokens found, 1 if not (real input, none found),
+ *              NO_INPUT (registry, src/cli-exit.cts) if stdin was empty or
+ *              whitespace-only, UNAVAILABLE (registry) if stdin read failed
+ *              (ADR-3889 Phase 3, #3907)
  *
- * Exit codes mirror grep: 0 = match found, 1 = no match, 2 = usage error.
  *
  * Canonical location: gsd-core/bin/lib/ui-safety-gate.cjs (#448)
  * This path is deployed by the GSD installer to $RUNTIME_DIR/gsd-core/bin/lib/.
- * bin/lib/ui-safety-gate.cjs (root) is retained for source-repo and npm usage.
+ * The former root-level copy of this file (outside gsd-core/) was removed in
+ * #3907 as dead code: no installer reference, no workflow invocation, and no
+ * fallback chain in shipped content ever pointed at it. Do not re-create it.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.UI_TOKENS = void 0;
@@ -111,19 +115,45 @@ function checkUiPresence(text) {
 // ── CLI entry point ─────────────────────────────────────────────────────────
 // Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
 // Invoked by workflow .md bash blocks as: echo "$PHASE_SECTION" | node .../ui-safety-gate.cjs
-// Exit 0 = UI found, 1 = no UI, 2 = startup error.
+//
+// Exit codes (ADR-3889 Phase 3, #3907): 0 = UI found, 1 = no UI (real input,
+// examined, nothing found), NO_INPUT (registry — see src/cli-exit.cts) = stdin
+// closed with zero bytes (or whitespace-only), UNAVAILABLE (registry) = stdin
+// read failed. The prior single "2 = startup error" arm conflated "I was
+// handed nothing" with "the phase says it has no UI" — those are different
+// answers; only the former is new here. `hint === 'no'` on REAL input still
+// exits 1 — that is the author's own declaration, not an empty-input
+// artifact.
+//
+// Terminates via terminateNow (src/cli-exit.cts), not raw process.exit: these
+// exits fire from inside a stdin event handler, which is exactly what
+// terminateNow (write-then-terminate) exists for, and it is total (cannot
+// throw or return). This module never emits --json, so every payload here is
+// `undefined` — terminateNow's JSON.stringify(undefined) is not a valid
+// Buffer source and is swallowed by its own emission-failure guard, so
+// nothing is written to stdout, preserving this CLI's historical contract of
+// silence.
 if (require.main === module) {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const cliExit = require('./cli-exit.cjs');
     // Collect stdin chunks asynchronously.
     const chunks = [];
     process.stdin.setEncoding('utf-8');
     process.stdin.on('data', (chunk) => chunks.push(chunk));
     process.stdin.on('end', () => {
         const input = chunks.join('');
+        // Whitespace-only counts as empty (ADR-3889 §1's NO_INPUT: "zero units
+        // were in scope, and that emptiness is known to be genuine"). Real input
+        // — including a lone NUL byte, which .trim() does not strip — always
+        // falls through to the detector.
+        if (input.trim().length === 0) {
+            cliExit.terminateNow('NO_INPUT', undefined);
+        }
         const result = checkUiPresence(input);
-        process.exit(result.hasUI ? 0 : 1);
+        cliExit.terminateNow(result.hasUI ? 'PASS' : 'FAIL', undefined);
     });
     process.stdin.on('error', (err) => {
         process.stderr.write(`ERROR: ui-safety-gate.cjs stdin read failed: ${err.message}\n`);
-        process.exit(2);
+        cliExit.terminateNow('UNAVAILABLE', undefined);
     });
 }

package/gsd-core/bin/lib/unusable-input.cjs

@@ -79,6 +79,18 @@ const UNUSABLE_REASON = Object.freeze({
      * planning-snapshot's projectSections field)
      */
     PROJECT_UNREADABLE: 'project_unreadable',
+    /**
+     * A config.json parsed cleanly, but a section that a legacy-key migration needed to write
+     * into (`git`, `planning`) holds something that is not an object — a string, number, boolean
+     * or array. Distinct from the section being absent: absence is the ordinary path and the
+     * migration simply creates the section. Only a PRESENT non-object is corruption, and it is
+     * exactly the ADR-227 "shape, not just parseability" class one level down from the top-level
+     * document check `_readConfigFile` already performs. The migration is refused rather than
+     * applied — spreading the value would enumerate a string into character keys, and a number
+     * or boolean into nothing at all — so the section, the legacy key, and the file on disk are
+     * all left exactly as the user wrote them. (#3760, tenth #1879 site)
+     */
+    CONFIG_SECTION_NOT_OBJECT: 'config_section_not_object',
 });
 /** One human-readable clause per reason. Prose lives here, never in a test assertion. */
 const REASON_PROSE = Object.freeze({
@@ -88,6 +100,7 @@ const REASON_PROSE = Object.freeze({
     [UNUSABLE_REASON.STATE_UNREADABLE]: 'STATE.md exists but could not be read; the current-phase label fell back to unavailable',
     [UNUSABLE_REASON.CONFIG_UNREADABLE]: 'config.json exists but could not be read or parsed; the config field fell back to unavailable',
     [UNUSABLE_REASON.PROJECT_UNREADABLE]: 'PROJECT.md exists but could not be read; the projectSections field fell back to unavailable',
+    [UNUSABLE_REASON.CONFIG_SECTION_NOT_OBJECT]: 'a config section that a legacy-key migration targets holds a non-object value; the migration was SKIPPED and both the section and the legacy key were left unchanged — fix the section by hand, or the legacy key will never migrate',
 });
 // ─── Dedup state ──────────────────────────────────────────────────────────────
 /**

package/gsd-core/bin/lib/validate-command-router.cjs

@@ -47,7 +47,7 @@ function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error
             // context: CJS-only — complex inline logic using classifyContextUtilization
             // with custom output formatting that has no direct SDK counterpart.
             context: () => {
-                const opts = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['tokens-used', 'context-window']);
+                const opts = (0, command_arg_projection_cjs_1.parseNamedArgsOrExit)(args, { valueFlags: ['tokens-used', 'context-window'], booleanFlags: ['json'], positionals: 2 }, error);
                 if (opts['tokens-used'] === null) {
                     error('--tokens-used <integer> is required for `validate context`');
                     return;
@@ -73,7 +73,7 @@ function routeValidateCommand({ verify, args, cwd, raw, output: outputFn, error
                     return;
                 }
                 const result = { ...classified, recommendation: RECOMMENDATIONS[classified.state] };
-                if (args.includes('--json')) {
+                if (opts['json'] === true) {
                     outputFn(result, raw);
                 }
                 else {

package/gsd-core/bin/lib/vendor/README.md

@@ -21,17 +21,55 @@ in-tree instead of depending on it being installed as an npm package.
   `gsd-core/bin/lib/pattern.cjs`) for linear-time RE2 pattern compilation.
 - `re2js.d.cts` — verbatim copy of `node_modules/re2js/build/index.d.cts`,
   so TypeScript resolves types for the relative import from `src/pattern.cts`.
+- `js-yaml.cjs` — verbatim copy of `node_modules/js-yaml/dist/js-yaml.js`
+  (upstream package `js-yaml`, pinned version see `package.json`
+  `devDependencies.js-yaml`). ADR-3473 §8.1 (#3881): the single YAML parser
+  this repo standardizes on. The `dist` UMD bundle is the vendorable
+  artifact — js-yaml's `exports.require` entry (`index.js`) is *not*
+  self-contained; `dist/js-yaml.js` loads under `require()`, contains zero
+  `require()` calls of its own, and exposes `load`/`dump`/`FAILSAFE_SCHEMA`/
+  `YAMLException`.
+
+## Two kinds of type twin
+
+Each vendored package needs a `.d.cts` under `src/vendor/` so TypeScript can
+resolve types for a relative `./vendor/<pkg>.cjs` import from `src/**`
+(module resolution for a `.cts` source is relative to `src/`, not the
+compiled output dir). There are two kinds:
+
+- **upstream-verbatim** (`re2js.d.cts`) — a byte-for-byte copy of an
+  upstream `.d.cts`/`.d.ts` that ships with the package. Both the
+  `gsd-core/bin/lib/vendor/` copy and the `src/vendor/` copy are checked by
+  `scripts/lint-vendored-deps.cjs` against `node_modules` and against each
+  other.
+- **hand-authored** (`js-yaml.d.cts`) — js-yaml ships **no** type
+  declarations upstream and `@types/js-yaml` is not installed, so there is
+  nothing to copy verbatim. `src/vendor/js-yaml.d.cts` is written by hand,
+  declares only the symbols actually used (`load`, `dump`,
+  `FAILSAFE_SCHEMA`, `YAMLException`), and is **excluded** from
+  `lint-vendored-deps.cjs`'s byte-compare — there is no upstream file to
+  compare it against. The narrowness is deliberate: anchors, aliases,
+  custom types and `loadAll` are unreachable from typed code, which is a
+  compile-time enforcement of ADR-3473 §8.1's refusal to expand them.
 
 ## Do not hand-edit
 
-These files are **verbatim** copies of the upstream build output. Never
-edit them directly — refresh them from `node_modules` instead:
+These files are **verbatim** copies of upstream build output. Never edit
+them directly — refresh them from `node_modules` instead:
 
 ```
 cp node_modules/re2js/build/index.cjs gsd-core/bin/lib/vendor/re2js.cjs
 cp node_modules/re2js/build/index.d.cts gsd-core/bin/lib/vendor/re2js.d.cts
+cp node_modules/re2js/build/index.d.cts src/vendor/re2js.d.cts
+
+cp node_modules/js-yaml/dist/js-yaml.js gsd-core/bin/lib/vendor/js-yaml.cjs
+# js-yaml.d.cts has no upstream counterpart — update src/vendor/js-yaml.d.cts
+# by hand if the js-yaml API surface this repo depends on changes.
 ```
 
-`node scripts/lint-vendored-deps.cjs` fails CI if the vendored copy drifts
-byte-for-byte from `node_modules/re2js/build/` or from the `re2js` version
-pinned in `package.json` `devDependencies`.
+`node scripts/lint-vendored-deps.cjs` fails CI if any vendored copy drifts
+byte-for-byte from its `node_modules` upstream, from its own source-side
+type twin (upstream-verbatim twins only), or from the version pinned in
+`package.json` `devDependencies`. It is table-driven (`VENDORED` in that
+script) — adding a third vendored package means adding a row, not a second
+hardcoded check block (ADR-3473 §8.3, "one implementation per rule").