@opengsd/gsd-core 1.10.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-frontend-evidence.cjs

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Static frontend-evidence detector — plan-time structural corroboration for the
+ * UI plan gate (#3312).
+ *
+ * `checkUiPresence` (ui-safety-gate.cjs) is a *vocabulary* signal: a hyphen is a
+ * word boundary, so a phase section naming the repo `dashboard-financeiro` matches
+ * the token `dashboard` exactly like the real UI compound `micro-frontend` does.
+ * That boundary rule is intentional (#3718) and must not be weakened — instead,
+ * the plan gate (`computeUiPlanGate` in check-command-router.cjs) corroborates the
+ * token match against the static repo tree before blocking.
+ *
+ * This mirrors what the sibling post-wave gate (`computeUiSafetyGate`) already
+ * does dynamically: it blocks only when `git diff HEAD~1 HEAD` touches UI files.
+ * Plan time has no diff to inspect, so the corroboration here is static:
+ *
+ *   (a) a `package.json` (root) with a known UI-framework dependency — a project
+ *       that ships react/vue/svelte/... in its manifest is a frontend regardless
+ *       of file layout;
+ *   (b) any `*.tsx` / `*.jsx` / `*.vue` / `*.svelte` file in the tree — the
+ *       component-framework subset of `UI_FILE_EXTENSIONS_RE`
+ *       (check-command-router.cjs). The weaker members of that list (css, scss,
+ *       html, ...) are deliberately NOT static evidence: docs sites and
+ *       markdown/bash/config repos routinely carry stray `.html`/`.css`, which
+ *       is precisely the false-positive class #3312 reports.
+ *
+ * All I/O failures degrade to `false` (no evidence) — never throw.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_COMPONENT_FILE_RE = void 0;
+exports.hasStaticFrontendEvidence = hasStaticFrontendEvidence;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+/** Component-framework file extensions — the static-evidence subset of UI_FILE_EXTENSIONS_RE. */
+exports.UI_COMPONENT_FILE_RE = /\.(tsx|jsx|vue|svelte)$/i;
+/**
+ * UI-framework package.json dependencies (dependencies OR devDependencies).
+ * Component frameworks/renderers only — deliberately excludes meta tooling
+ * (typescript, eslint, ...) that non-frontend Node projects also carry.
+ */
+const UI_FRAMEWORK_DEPS = new Set([
+    'react',
+    'react-dom',
+    'vue',
+    'svelte',
+    '@sveltejs/kit',
+    'angular',
+    '@angular/core',
+    'preact',
+    'solid-js',
+    'lit',
+    'lit-element',
+    'ember-source',
+    '@remix-run/react',
+    'react-native',
+    'expo',
+    'next',
+    'nuxt',
+    'gatsby',
+    'astro',
+    '@ionic/react',
+    '@ionic/vue',
+    '@ionic/angular',
+]);
+/** Directories never walked — dependencies, VCS data, build output, GSD planning state. */
+const SKIP_DIRS = new Set([
+    'node_modules',
+    '.git',
+    '.planning',
+    'dist',
+    'build',
+    'out',
+    '.next',
+    '.nuxt',
+    '.output',
+    'coverage',
+    'vendor',
+    '.cache',
+]);
+/** Walk safety cap — beyond this the tree is treated as scanned (evidence decided by then). */
+const MAX_WALK_ENTRIES = 10_000;
+function packageJsonHasUiFramework(projectDir) {
+    let raw;
+    try {
+        raw = node_fs_1.default.readFileSync(node_path_1.default.join(projectDir, 'package.json'), 'utf8');
+    }
+    catch {
+        return false; // no/unreadable package.json → no evidence from this signal
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return false; // malformed package.json → no evidence from this signal
+    }
+    if (parsed === null || typeof parsed !== 'object')
+        return false;
+    const pkg = parsed;
+    for (const field of ['dependencies', 'devDependencies', 'peerDependencies']) {
+        const deps = pkg[field];
+        if (deps === null || typeof deps !== 'object')
+            continue;
+        for (const name of Object.keys(deps)) {
+            if (UI_FRAMEWORK_DEPS.has(name))
+                return true;
+        }
+    }
+    return false;
+}
+function treeHasComponentFile(projectDir) {
+    // Iterative BFS — bounded by MAX_WALK_ENTRIES so a pathological tree cannot
+    // stall the gate. Symlinks are never followed (withFileTypes + isDirectory).
+    const queue = [projectDir];
+    let visited = 0;
+    while (queue.length > 0 && visited < MAX_WALK_ENTRIES) {
+        const dir = queue.shift();
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            continue; // unreadable directory → skip it
+        }
+        for (const entry of entries) {
+            visited++;
+            if (visited >= MAX_WALK_ENTRIES)
+                return false;
+            if (entry.isDirectory()) {
+                if (!SKIP_DIRS.has(entry.name))
+                    queue.push(node_path_1.default.join(dir, entry.name));
+            }
+            else if (entry.isFile() && exports.UI_COMPONENT_FILE_RE.test(entry.name)) {
+                return true;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Does the project tree carry static evidence of a frontend?
+ *
+ * @param projectDir - Absolute path to the project root (the gate's cwd).
+ * @returns true when package.json declares a UI-framework dependency or the
+ *          tree contains a component-framework file; false otherwise (including
+ *          on any I/O failure — evidence must be affirmative).
+ */
+function hasStaticFrontendEvidence(projectDir) {
+    if (typeof projectDir !== 'string' || projectDir === '')
+        return false;
+    if (packageJsonHasUiFramework(projectDir))
+        return true;
+    return treeHasComponentFile(projectDir);
+}

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.
  *
@@ -17,17 +17,22 @@
  * matched; "micro-frontend" and "micro frontend" ARE matched).
  *
  * Public API:
- *   checkUiPresence(text: string): { hasUI: boolean, tokens: string[] }
+ *   checkUiPresence(text: string): { hasUI: boolean, tokens: string[],
+ *                                    matchedToken: string|null, matchedLine: string|null }
  *
  * 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;
@@ -63,7 +68,7 @@ const UI_GATE_PATTERN_GLOBAL = new RegExp(UI_GATE_PATTERN.source, 'gi');
  */
 function checkUiPresence(text) {
     if (typeof text !== 'string') {
-        return { hasUI: false, tokens: [] };
+        return { hasUI: false, tokens: [], matchedToken: null, matchedLine: null };
     }
     // Normalise CRLF so the pattern sees consistent line boundaries.
     const normalised = text.replace(/\r\n/g, '\n');
@@ -84,37 +89,71 @@ function checkUiPresence(text) {
         .filter((line) => !/^\s*\*\*UI hint\*\*\s*:/i.test(line))
         .join('\n');
     const found = new Set();
+    let matchedToken = null;
+    let matchedLine = null;
     for (const line of sniffable.split('\n')) {
         // Reset lastIndex before each line so the global pattern restarts from 0.
         UI_GATE_PATTERN_GLOBAL.lastIndex = 0;
         for (const m of line.matchAll(UI_GATE_PATTERN_GLOBAL)) {
+            if (matchedToken === null) {
+                // #3312: record the FIRST match so gate consumers can surface the
+                // triggering token/line for one-second operator triage.
+                matchedToken = m[2].toLowerCase();
+                matchedLine = line;
+            }
             found.add(m[2].toLowerCase());
         }
     }
     if (hint === 'no') {
-        return { hasUI: false, tokens: [] };
+        return { hasUI: false, tokens: [], matchedToken: null, matchedLine: null };
     }
     if (hint === 'yes') {
-        return { hasUI: true, tokens: [...found] };
+        return { hasUI: true, tokens: [...found], matchedToken, matchedLine };
     }
-    return { hasUI: found.size > 0, tokens: [...found] };
+    return { hasUI: found.size > 0, tokens: [...found], matchedToken, matchedLine };
 }
 // ── 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

@@ -58,12 +58,49 @@ const UNUSABLE_REASON = Object.freeze({
      * silent degradation is visible. (#3099, sixth #1879 site)
      */
     LAST_ACTIVITY_UNPARSEABLE: 'last_activity_unparseable',
+    /**
+     * A STATE.md exists but could not be read (EACCES/EIO/…). Distinct from a project that has
+     * not run `state.init` yet: absence returns the same non-answer, silently — only an
+     * exists-but-unreadable STATE.md is corruption. (#3308, seventh #1879 site —
+     * planning-snapshot's current-phase field)
+     */
+    STATE_UNREADABLE: 'state_unreadable',
+    /**
+     * A config.json exists but could not be read/parsed (EACCES/EIO/malformed JSON/…).
+     * Distinct from a project that has not run any config-writing command yet: absence
+     * returns the same non-answer, silently — only an exists-but-unreadable config.json
+     * is corruption. (#3309, eighth #1879 site — planning-snapshot's config field)
+     */
+    CONFIG_UNREADABLE: 'config_unreadable',
+    /**
+     * A PROJECT.md exists but could not be read (EACCES/EIO/…). Distinct from a project that has
+     * not run any project-writing command yet: absence returns the same non-answer, silently —
+     * only an exists-but-unreadable PROJECT.md is corruption. (#3309, ninth #1879 site —
+     * 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({
     [UNUSABLE_REASON.FRONTMATTER_UNTERMINATED]: 'frontmatter opens with "---" but never closes; metadata was NOT applied',
     [UNUSABLE_REASON.ROADMAP_UNREADABLE]: 'ROADMAP.md exists but could not be read; phase and milestone lookups fell back to defaults',
     [UNUSABLE_REASON.LAST_ACTIVITY_UNPARSEABLE]: 'last_activity in STATE.md is present but unparseable as a date; stale_activity fell back to false (idle-stranded suppressed)',
+    [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/update-context.cjs

@@ -10,7 +10,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIME_DIRS = void 0;
+exports.CODEX_CONFIG_MARKER = exports.RUNTIME_DIRS = void 0;
 exports.inferPreferredRuntime = inferPreferredRuntime;
 exports.envRuntimeDirs = envRuntimeDirs;
 exports.resolveUpdateContext = resolveUpdateContext;
@@ -38,6 +38,12 @@ exports.RUNTIME_DIRS = [
     ['codex', '.codex'],
 ];
 const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+// Shared Codex config-root marker filename. Single-sourced here (this module
+// is the pre-existing, dependency-free owner) and re-exported by
+// host-runtime-detection.cts, whose detection rung reuses this exact probe
+// filename (though NOT the truthiness rule below — see that module's header
+// comment for the deliberate divergence).
+exports.CODEX_CONFIG_MARKER = 'config.toml';
 function expandHome(p, home) {
     if (!p)
         return '';
@@ -72,7 +78,7 @@ function inferPreferredRuntime({ fs, env, preferredConfigDir }) {
         if (fs.exists(node_path_1.default.join(preferredConfigDir, 'opencode.json')) ||
             fs.exists(node_path_1.default.join(preferredConfigDir, 'opencode.jsonc')))
             return 'opencode';
-        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'config.toml')))
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, exports.CODEX_CONFIG_MARKER)))
             return 'codex';
     }
     if (env['CODEX_HOME'])