@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/surface.cjs

@@ -43,6 +43,11 @@ const { readActiveProfile, resolveProfile, loadSkillsManifest,
 // below can never drift from what the stage-time writer actually wrote.
 CAPABILITY_SKILL_MARKER, } = installProfiles;
 const clusters_cjs_1 = require("./clusters.cjs");
+// #2870: `isGlobalScope` centralizes the `scope === 'global'` boolean
+// projection `applySurface` needs at `_computePathPrefix`'s `isGlobal:
+// boolean` boundary (see its doc comment in install-scope.cts for why the
+// projection is centralized rather than eliminated).
+const install_scope_cjs_1 = require("./install-scope.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
 const { findInstallSourceRoot } = runtimeArtifactLayout;
@@ -50,6 +55,8 @@ const { findInstallSourceRoot } = runtimeArtifactLayout;
 const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const retiredArtifactCleanup = require("./retired-artifact-cleanup.cjs");
 const { assertDestWithinConfigHome } = runtimeArtifactInstallPlan;
 const SURFACE_FILE_NAME = '.gsd-surface.json';
 /**
@@ -302,6 +309,9 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     }
     const skillManifest = normalizeSkillManifest(layout.configDir, manifest);
     const resolved = resolveSurface(layout.configDir, skillManifest, clusterMap, registry);
+    // Profile toggles must converge retired surfaces too. Once a kind disappears
+    // from artifactLayout there is no normal sync pass left to prune it (#2644).
+    retiredArtifactCleanup.pruneRetiredRuntimeArtifacts(layout.runtime, layout.configDir);
     // #1575: agents kind now mirrors createRuntimeArtifactInstallPlan — build
     // agentCtx (pathPrefix + attribution) and pass it to kind.stage() so
     // stageAgentsForRuntimeWithConverter applies the full inline-loop pipeline
@@ -311,12 +321,23 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
     const _homedirFn = opts?.homedir ?? (() => node_os_1.default.homedir());
     const _resolvedTarget = (0, shell_command_projection_cjs_1.posixNormalize)(node_path_1.default.resolve(layout.configDir));
     const _homeDir = (0, shell_command_projection_cjs_1.posixNormalize)(_homedirFn());
-    const _isGlobal = (layout.scope ?? 'global') === 'global';
+    // #2870: same judgment as createRuntimeArtifactInstallPlan's identical
+    // line — `layout.scope` is already the resolved scope value on the
+    // `Layout` this function received. `layout.scope` is optional, so the
+    // pre-existing `?? 'global'` default is kept ahead of the call: it must
+    // run BEFORE `isGlobalScope`, because `isGlobalScope(undefined)` throws
+    // (unlike the old inline `undefined === 'global'`, which silently
+    // evaluated to `false`) — the default is what makes an undefined scope
+    // resolve to `'global'` here, exactly as it did before. `isGlobalScope`
+    // then projects the defaulted value to the boolean `_computePathPrefix`'s
+    // existing `isGlobal: boolean` API requires.
+    const _isGlobal = (0, install_scope_cjs_1.isGlobalScope)(layout.scope ?? 'global');
     const _isOpencode = layout.runtime === 'opencode';
     const _isWindowsHost = (opts?.platform ?? process.platform) === 'win32';
     const _pathPrefix = runtimeArtifactConversion._computePathPrefix({ isGlobal: _isGlobal, isOpencode: _isOpencode, isWindowsHost: _isWindowsHost, resolvedTarget: _resolvedTarget, homeDir: _homeDir });
     const _attribution = opts?.resolveAttribution ? opts.resolveAttribution(layout.runtime) : undefined;
-    const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution };
+    // #2875 Part 2 (row I1): layout.configDir is this call's install root.
+    const agentCtx = { runtime: layout.runtime, pathPrefix: _pathPrefix, attribution: _attribution, targetDir: layout.configDir };
     const tempDirsToClean = [];
     // #1575: When the surface has no state modifications AND the base profile is
     // 'full', pass the '*' sentinel for agents staging so ALL agents are staged —
@@ -360,7 +381,13 @@ function applySurface(runtimeConfigDir, layout, manifest, clusterMap, registry,
                     tempDirsToClean.push(rewritten);
                 }
             }
-            const dest = assertDestWithinConfigHome(layout.configDir, kind.destSubpath);
+            // #2911: honor kind.home as a FALLBACK-preferred override (e.g. Codex
+            // skills -> $HOME/.agents), never a blanket replacement — kinds without
+            // a `home` must keep resolving against layout.configDir. This must stay
+            // in lockstep with _copyStaged's root selection in src/install-engine.cts;
+            // the parity test in tests/runtime-artifact-layout-surface.test.cjs
+            // enforces that the two writers never diverge again.
+            const dest = assertDestWithinConfigHome(kind.home ?? layout.configDir, kind.destSubpath);
             _syncGsdDir(staged, dest, kind, skillManifest, layout.runtime);
         }
     }
@@ -546,13 +573,11 @@ function _syncGsdDir(stagedDir, destDir, kind, manifest, runtime) {
         // from install and orphaned the installed gsd-*.md files, and the unscoped
         // prune deleted user-owned command files.
         //
-        // NOTE: the destName rule below intentionally mirrors bin/install.js
-        // `_copyStaged` (the `namespacedByDir` decision). Keep them in sync.
-        const destLast = (typeof kind === 'object' && kind !== null && kind.destSubpath)
-            ? node_path_1.default.basename(kind.destSubpath)
-            : '';
-        const prefixStem = kindPrefix ? kindPrefix.replace(/-$/, '') : '';
-        const namespacedByDir = kindName === 'commands' && destLast === prefixStem;
+        // Single source of truth: runtimeArtifactLayout.isNamespacedByDir (#2871
+        // Phase 2 review finding — this rule previously drifted independently
+        // across install-engine.cts / surface.cts / runtime-artifact-layout.cts).
+        const kindDestSubpath = (typeof kind === 'object' && kind !== null && kind.destSubpath) ? kind.destSubpath : '';
+        const namespacedByDir = runtimeArtifactLayout.isNamespacedByDir(kindName, kindDestSubpath, kindPrefix);
         const stagedFiles = node_fs_1.default.readdirSync(stagedDir).filter(f => f.endsWith('.md'));
         const stagedDestNames = new Set();
         for (const file of stagedFiles) {

package/gsd-core/bin/lib/text-lines.cjs

@@ -0,0 +1,80 @@
+"use strict";
+/**
+ * text-lines.cts — the line-terminator seam (ADR-3212 §3, epic #3212 Phase 2,
+ * #3413).
+ *
+ * Source in src/text-lines.cts, compiled to gsd-core/bin/lib/text-lines.cjs
+ * (gitignored), per the repo's ADR-457 build-at-publish convention.
+ *
+ * Sole owner of `\r?\n` splitting and CRLF normalization. Closes #3360: a
+ * regex anchored on `^`/`$` under `/m` against a whole multi-line string is
+ * exposed to `\r` being its own LineTerminator (ECMA-262), so a greedy `\s*`
+ * can cross a CRLF boundary and inflate a captured indent by one character.
+ * Split-then-match — call `splitLines` first, then match per already-split
+ * line — is immune by construction, because a single split line can never
+ * contain the delimiter that produced it. This module exists so that shape
+ * is the easy, obvious way to write indentation-sensitive parsing, per the
+ * design doc (.gsd/phase/chore-3413-text-lines-seam/40-design.md).
+ *
+ * A "genuine leaf" module (CONTEXT.md's term, shared with Phase 1's sibling
+ * seam `src/pattern.cts`): zero I/O, zero imports from other `src/*.cts`
+ * modules, pure string functions only.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitLines = splitLines;
+exports.normalizeEol = normalizeEol;
+exports.detectEol = detectEol;
+exports.joinLines = joinLines;
+/**
+ * Split document content into lines on `\r\n` or `\n`. A lone `\r` (bare CR,
+ * no following `\n`) is NOT a delimiter — this matches every existing
+ * `\r?\n` call site in the repo and is intentionally narrower than "treat
+ * any LineTerminator as a break." Matches `String.prototype.split`'s own
+ * contract for a trailing terminator (a trailing empty element) and for the
+ * empty string (`[""]`).
+ */
+function splitLines(content) {
+    if (typeof content !== 'string') {
+        throw new TypeError(`splitLines: expected a string, got ${typeof content}`);
+    }
+    return content.split(/\r?\n/);
+}
+/**
+ * Normalize all line endings to LF by stripping every `\r` character — not
+ * only `\r\n` pairs. This is byte-for-byte the same operation as the 4
+ * `scripts/gen-*.cjs` copies of `normalizeLineEndings` this module
+ * consolidates (`content.replace(/\r/g, '')`), so a lone/unpaired `\r` (old
+ * Mac-style content) is stripped too. Deliberately a different contract from
+ * `splitLines`, which does NOT treat a bare `\r` as a delimiter (row 6) —
+ * these are two different operations kept as two separate functions rather
+ * than one "handle all CR-ish things" primitive.
+ */
+function normalizeEol(content) {
+    return content.replace(/\r/g, '');
+}
+/**
+ * Detect the dominant line-terminator in `content`: `'\r\n'` when CRLF pairs
+ * outnumber bare LFs, `'\n'` when bare LFs outnumber CRLF pairs, and `'\r\n'`
+ * as the default when there is no bare LF at all (all-CRLF content, or no
+ * terminator present whatsoever — an empty or single-line input). See the
+ * design doc's Rejected section for why the tie/empty default is `'\r\n'`
+ * rather than `'\n'`: this function exists to PRESERVE whatever a file
+ * already uses, not to bias toward LF the way a write-time normalizer would.
+ */
+function detectEol(content) {
+    const crlfCount = (content.match(/\r\n/g) || []).length;
+    const totalLfCount = (content.match(/\n/g) || []).length;
+    const bareLfCount = totalLfCount - crlfCount;
+    if (bareLfCount === 0 || crlfCount >= bareLfCount)
+        return '\r\n';
+    return '\n';
+}
+/**
+ * Join lines back into a single string with `eol` (default `'\n'`) between
+ * each pair — the inverse of `splitLines`. `joinLines(splitLines(x),
+ * detectEol(x))` reproduces `x` byte-for-byte for any `x` already in
+ * canonical (single-terminator) form (ADR-3212 §3's round-trip property).
+ */
+function joinLines(lines, eol) {
+    return lines.join(eol ?? '\n');
+}

package/gsd-core/bin/lib/token-scanner.cjs

@@ -0,0 +1,76 @@
+"use strict";
+/**
+ * token-scanner.cts — the tokenizer-first seam for stateful grammars (ADR-3212
+ * §4, epic #3212 Phase 3, #3414).
+ *
+ * Source in src/token-scanner.cts, compiled to gsd-core/bin/lib/token-scanner.cjs
+ * (gitignored), per the repo's ADR-457 build-at-publish convention.
+ *
+ * Generalizes the proven `hooks/lib/git-cmd.js` token-walk (#3129 — "has not
+ * re-opened") into a primitive other stateful-grammar consumers can share.
+ * `git-cmd.js` migrates onto `tokenizeShellLike` with zero behavior change
+ * (ADR §6); its own env-prefix/flag/subcommand walk logic stays put — only
+ * the character-level tokenizer moves here.
+ *
+ * `indentWidth` is the primitive `src/decisions.cts`'s #3169 fix needs: a
+ * decision-bullet list can NEST (a bullet elaborating on an already-open
+ * decision, indented deeper than it), and a per-line regex cannot see that
+ * nesting — only tracking indentation relative to the currently-open
+ * decision can (ADR §4 criterion 1). See
+ * .gsd/phase/chore-3414-tokenizer-first-seam/40-design.md §1.3 for the
+ * disproven bold-run-content-classification alternative and why nesting
+ * depth, not bullet content, is the actual distinguishing signal.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tokenizeShellLike = tokenizeShellLike;
+exports.indentWidth = indentWidth;
+/**
+ * Tokenize a shell-like command string: whitespace-split, with single- and
+ * double-quoted spans taken as one token each. No escape handling, no
+ * brace/variable expansion — matches `hooks/lib/git-cmd.js`'s original
+ * `tokenize()` exactly (parity-asserted in tests/token-scanner.test.cjs).
+ */
+function tokenizeShellLike(cmd) {
+    const tokens = [];
+    let i = 0;
+    const len = cmd.length;
+    while (i < len) {
+        while (i < len && /\s/.test(cmd[i]))
+            i++;
+        if (i >= len)
+            break;
+        let token = '';
+        while (i < len && !/\s/.test(cmd[i])) {
+            if (cmd[i] === "'") {
+                i++;
+                while (i < len && cmd[i] !== "'")
+                    token += cmd[i++];
+                if (i < len)
+                    i++;
+            }
+            else if (cmd[i] === '"') {
+                i++;
+                while (i < len && cmd[i] !== '"')
+                    token += cmd[i++];
+                if (i < len)
+                    i++;
+            }
+            else {
+                token += cmd[i++];
+            }
+        }
+        if (token)
+            tokens.push(token);
+    }
+    return tokens;
+}
+/**
+ * Count a line's leading whitespace width. Tabs count as one column each
+ * (not expanded) — matches `src/decisions.cts`'s existing continuation-line
+ * check (`/^[ \t]/`), which never expanded tabs either; this function does
+ * not introduce a new tab-width policy.
+ */
+function indentWidth(line) {
+    const match = line.match(/^[ \t]*/);
+    return match ? match[0].length : 0;
+}

package/gsd-core/bin/lib/uat-predicate.cjs

@@ -25,6 +25,9 @@ const { stripFencedCode } = markdownSectionizer;
 // eslint-disable-next-line @typescript-eslint/no-require-imports
 const verification = require("./verification.cjs");
 const { readVerificationStatus } = verification;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const phaseIdMod = require("./phase-id.cjs");
+const { scopeToPhase } = phaseIdMod;
 // ─── Blocking state sets (documented for maintainability) ─────────────────────
 // UAT file frontmatter `status` values that indicate the file is not fully done
 const BLOCKING_UAT_FM_STATUSES = new Set([
@@ -186,11 +189,16 @@ function evaluateUatPassed(phaseFullDir, opts) {
             blockers,
             no_uat_artifacts,
             policy: { require_verification: requireVerification },
+            // readVerificationStatus was never reached on this early-return path.
+            verification_stale_check_indeterminate: false,
         };
     }
-    // Filter UAT and VERIFICATION files using the same filter as cmdPhaseComplete
-    const uatFileNames = dirEntries.filter(f => f.includes('-UAT') && f.endsWith('.md'));
-    const verFileNames = dirEntries.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'));
+    // Filter UAT and VERIFICATION files using the same filter as cmdPhaseComplete,
+    // scoped to THIS phase's own token (#3511) — a stray, cross-phase, or ad-hoc
+    // file can no longer contribute a blocker to a phase it does not belong to.
+    const phaseDirBaseName = node_path_1.default.basename(phaseFullDir);
+    const uatFileNames = scopeToPhase(dirEntries.filter(f => f.includes('-UAT') && f.endsWith('.md')), phaseDirBaseName);
+    const verFileNames = scopeToPhase(dirEntries.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md')), phaseDirBaseName);
     // ── Process UAT files ──────────────────────────────────────────────────────
     for (const file of uatFileNames) {
         uatFiles.push(file);
@@ -263,8 +271,15 @@ function evaluateUatPassed(phaseFullDir, opts) {
         // (handled by the requireVerification policy check below if needed)
     }
     // ── Policy: requireVerification ───────────────────────────────────────────
+    // #3057 B3: routing here is UNCHANGED — an indeterminate staleness check
+    // still falls through to the same `verificationStatus !== 'passed'` branch
+    // it always did (the pre-existing fail-open contract). `verificationStaleCheckIndeterminate`
+    // only records the fact for the report below; it never itself gates `blockers`.
+    let verificationStaleCheckIndeterminate = false;
     if (requireVerification) {
-        const verificationStatus = readVerificationStatus(phaseFullDir).status;
+        const verificationResult = readVerificationStatus(phaseFullDir);
+        const verificationStatus = verificationResult.status;
+        verificationStaleCheckIndeterminate = verificationResult.staleCheckIndeterminate === true;
         if (verificationStatus === 'stale') {
             blockers.push('policy: verification status=stale');
         }
@@ -288,6 +303,7 @@ function evaluateUatPassed(phaseFullDir, opts) {
         policy: {
             require_verification: requireVerification,
         },
+        verification_stale_check_indeterminate: verificationStaleCheckIndeterminate,
     };
 }
 module.exports = {