@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/install-scope.cjs

@@ -0,0 +1,270 @@
+"use strict";
+/**
+ * install-scope.cts — Install Scope Module (#2870, ADR-2866, governed by
+ * ADR-2866, Phase 0 PR #3265).
+ *
+ * `resolveScope()` turns a bare `'global' | 'local'` string — previously
+ * re-derived at 12 `isGlobal ? 'global' : 'local'` sites in `bin/install.js`
+ * plus several downstream consumers — into ONE resolved value produced by
+ * ONE module. See `.gsd/phase/feat-2870-install-scope-module/40-design.md`
+ * for the full behavior table and rationale; the summary that matters for
+ * future readers is captured in the comments below.
+ *
+ * This module OWNS the `InstallScope` type name. It was previously declared
+ * (as a private, non-exported `TypeAlias`) inside
+ * `runtime-artifact-install-plan.cts`; that module now imports it from here
+ * instead of re-declaring it, so the codebase has one spelling of "install
+ * scope" instead of a fifth one appearing alongside the three that already
+ * existed (`'local' | 'global'` in the layout module, `'global' | 'project'`
+ * in capability-lifecycle, and the single literal `'project'` in
+ * capability-consent).
+ *
+ * ── Compose, never modify, resolveConfigHomeFromDescriptor ─────────────────
+ * `resolveConfigHomeFromDescriptor` (`runtime-homes.cts`) is rated CRITICAL
+ * blast radius: 60 dependents across 13 files and 2 process flows. Adding a
+ * `scope` parameter to it — the "obvious" refactor — would touch all 60 for
+ * no reason this module needs: it already resolves the GLOBAL config home
+ * correctly today. So this module calls it as-is for the global scope and
+ * derives the LOCAL scope's config dir independently (see
+ * `resolveScopeConfigHome` below) — genuine composition, not a rename. Every
+ * one of those 60 call sites stays byte-identical.
+ *
+ * ── Why `settingsFile: null` is correct, not a bug ──────────────────────────
+ * Only `claude` declares `hostBehaviors.settingsFileByScope` in the
+ * capability registry; the other 18 registered runtimes do not have a
+ * per-scope settings file at all. Returning `null` for them is honest —
+ * substituting `'settings.json'` (or any other Claude-shaped default) would
+ * invent a fact for every non-Claude runtime that asked. Callers that
+ * legitimately want a Claude-specific fallback (there is exactly one today,
+ * `bin/install.js:550`) apply it themselves; this module does not.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SCOPE_ORDER = void 0;
+exports.validateScopeId = validateScopeId;
+exports.isInstallScopeId = isInstallScopeId;
+exports.resolveScope = resolveScope;
+exports.isGlobalScope = isGlobalScope;
+exports.scopeRank = scopeRank;
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const runtime_homes_cjs_1 = require("./runtime-homes.cjs");
+// In .cts (CommonJS output) files, `require` is available as a global.
+const _require = require;
+// ── The `local` / `project` boundary (see CONTEXT.md glossary entry) ──────
+//
+// `ConsentRecord.scope: 'project'` (capability-consent.cts) and
+// `capability-lifecycle.cts:163`'s `'global' | 'project'` are NOT renamed to
+// match this module's `'local'` spelling. `ConsentRecord.scope` is persisted
+// on disk in user-owned consent records outside this repo; renaming that
+// literal would silently invalidate every existing project-scoped consent
+// record on a user's machine the next time it is read back. The
+// reconciliation is a documented boundary mapping, not a rename sweep:
+//   install scope 'local'  ⇄  consent scope 'project'
+//   install scope 'global' ⇄  no consent record at all
+// `consentRequired` above reports the install-scope side of that mapping;
+// it is deliberately still the CLI's own vocabulary.
+const VALID_SCOPE_IDS = new Set(['global', 'local']);
+/**
+ * Single owner of the `'global' | 'local'` membership check. `resolveScope`,
+ * `isGlobalScope`, `scopeRank`, and `resolveTriggerSurface`
+ * (`runtime-artifact-layout.cts`, #2871 Phase 2) all call this instead of
+ * each carrying its own copy of the rule — one validator every scope-typed
+ * seam reads, not N validators that could silently diverge. Exported so a
+ * sibling module can reuse it directly rather than re-deriving the same
+ * membership check a second time.
+ */
+function validateScopeId(id, caller) {
+    if (typeof id !== 'string' || !VALID_SCOPE_IDS.has(id)) {
+        throw new TypeError(`${caller}: id must be one of 'global' | 'local', got ${JSON.stringify(id)}`);
+    }
+    return id;
+}
+/**
+ * Non-throwing sibling of {@link validateScopeId}, for readers that must
+ * report an unrecognized scope as a value rather than fail (#2872). Reads the
+ * same `VALID_SCOPE_IDS` set, so the two can never disagree about what a
+ * scope is.
+ */
+function isInstallScopeId(value) {
+    return typeof value === 'string' && VALID_SCOPE_IDS.has(value);
+}
+// Higher wins. Not exported as a public constant — only the resulting
+// `hostPrecedenceRank` field on `ResolvedScope` is public API, so a future
+// re-basing of the literal values (Phase 2, #2871) never requires touching
+// an exported symbol.
+const HOST_PRECEDENCE_RANK = {
+    global: 2,
+    local: 1,
+};
+/** Lazy registry accessor — mirrors the pattern in runtime-homes.cts /
+ *  runtime-artifact-layout.cts (5b/5c/5d). */
+function getRegistry() {
+    return _require('./capability-registry.cjs');
+}
+/**
+ * Normalize path separators UNCONDITIONALLY (never gated on `path.sep` /
+ * `process.platform`). A Windows-shaped `home` (`C:\Users\x`) can arrive on
+ * any host — via an injected test fixture, a cross-platform config sync, or
+ * a value copied from a Windows machine — so the normalization must not
+ * depend on which OS this process happens to be running on.
+ */
+function normalizeSeparators(p) {
+    return p.replace(/\\/g, '/');
+}
+/**
+ * Minimal leading-`~` expansion for `explicitDir`. `runtime-homes.cts`'s own
+ * `expandTilde` is NOT exported (it is a private helper), and this module
+ * must not add exports to that CRITICAL-blast-radius file just to reuse
+ * three lines — so this is an intentionally small, independent
+ * reimplementation, not a fork of shared logic.
+ */
+function expandTildeForExplicitDir(p, home) {
+    const resolvedHome = home ?? node_os_1.default.homedir();
+    if (p === '~')
+        return resolvedHome;
+    if (p.startsWith('~/'))
+        return node_path_1.default.join(resolvedHome, p.slice(2));
+    return p;
+}
+/**
+ * Resolve the config-home directory for one scope. `explicitDir` short-
+ * circuits both scopes identically (matches `getGlobalConfigDir`'s existing
+ * override behavior — the module must not regress it). Otherwise:
+ *   - `global`: delegates entirely to `resolveConfigHomeFromDescriptor`
+ *     (composition — see the module-level comment).
+ *   - `local`: joins the registry's `localConfigDir` onto `cwd` (defaulting
+ *     to the real process cwd) — the project-local dir, independent of
+ *     `home`/`env`.
+ */
+function resolveScopeConfigHome(id, descriptor, input) {
+    const explicitDir = input.explicitDir;
+    if (typeof explicitDir === 'string' && explicitDir.trim() !== '') {
+        return normalizeSeparators(expandTildeForExplicitDir(explicitDir, input.home));
+    }
+    if (id === 'local') {
+        // localConfigDir is guaranteed non-null here: the only registered
+        // runtime with `localConfigDir: null` is vscode, and vscode's
+        // `configHome.kind === 'none'` already causes resolveScope to throw
+        // before this function is ever called (see the 'none' guard below).
+        const localConfigDir = descriptor.localConfigDir;
+        const cwd = input.cwd ?? process.cwd();
+        return normalizeSeparators(node_path_1.default.join(cwd, localConfigDir));
+    }
+    return normalizeSeparators((0, runtime_homes_cjs_1.resolveConfigHomeFromDescriptor)(descriptor.configHome, {
+        env: input.env,
+        home: input.home,
+        existsSync: input.existsSync,
+    }));
+}
+/**
+ * Resolve a bare `'global' | 'local'` scope id plus a runtime into a single
+ * `ResolvedScope` value: the config directory, the per-scope settings
+ * filename (or `null`), whether the scope requires a consent record, and a
+ * precedence rank (data only this phase — see `hostPrecedenceRank` above).
+ *
+ * Pure: performs no writes and no I/O of its own beyond what
+ * `resolveConfigHomeFromDescriptor` already performs via the injected
+ * `existsSync` (for `global`) or the injected `cwd`, defaulting to
+ * `process.cwd()` (for `local`). Never mutates `input`. The returned object
+ * is frozen so a caller mutating the result cannot corrupt a subsequent
+ * call.
+ *
+ * Throws `TypeError` for:
+ *   - an `id` outside `'global' | 'local'` — including wrong case, empty,
+ *     missing, or any non-string value (no coercion, ever);
+ *   - an unknown `runtime` (no matching capability-registry entry);
+ *   - a `runtime` whose descriptor has `configHome.kind === 'none'`
+ *     (vscode) — there is no installable config directory to resolve, so
+ *     inventing one (or silently returning `configHome: null`) would be
+ *     dishonest. All three cases share one catch shape (`instanceof
+ *     TypeError`) with `resolveRuntimeArtifactLayout`'s existing contract
+ *     for unknown runtimes, so callers of both never need two different
+ *     catch blocks.
+ */
+function resolveScope(input) {
+    const scopeId = validateScopeId(input?.id, 'resolveScope');
+    const runtime = input.runtime;
+    const registryEntry = typeof runtime === 'string'
+        ? getRegistry().runtimes[runtime]
+        : undefined;
+    const descriptor = registryEntry?.runtime;
+    if (!descriptor) {
+        throw new TypeError(`resolveScope: unknown runtime '${String(runtime)}' — not present in the capability registry`);
+    }
+    if (descriptor.configHome.kind === 'none') {
+        // #2103: vscode-shaped runtimes (Marketplace/VSIX, installSurface:
+        // 'none') have no file-projected config directory at all — the same
+        // carve-out tests/runtime-flags.test.cjs's NON_INSTALLABLE_RUNTIMES
+        // already documents. Throwing here matches
+        // resolveConfigHomeFromDescriptor's own deliberate throw on this kind,
+        // rather than silently inventing an install scope for a runtime that
+        // cannot be installed.
+        throw new TypeError(`resolveScope: runtime '${runtime}' has no installable config directory (configHome.kind === 'none')`);
+    }
+    const configHome = resolveScopeConfigHome(scopeId, descriptor, input);
+    const settingsFile = descriptor.hostBehaviors?.settingsFileByScope?.[scopeId] ?? null;
+    const consentRequired = scopeId === 'local';
+    const hostPrecedenceRank = HOST_PRECEDENCE_RANK[scopeId];
+    return Object.freeze({
+        id: scopeId,
+        configHome,
+        settingsFile,
+        consentRequired,
+        hostPrecedenceRank,
+    });
+}
+/**
+ * Project an `InstallScope` down to the boolean shape some downstream APIs
+ * still require. Four call sites (both kind-builder closures in
+ * `runtime-artifact-layout.cts`, plus one each in
+ * `runtime-artifact-install-plan.cts` and `surface.cts`) were each
+ * independently re-deriving this same `scope === 'global'` comparison — four
+ * copies of one rule that could silently drift apart (#2870). They exist
+ * because `runtime-artifact-conversion.cts`'s `_computePathPrefix` takes
+ * `isGlobal: boolean` at its API boundary, and that boundary is not changing
+ * here, so the boolean projection cannot be eliminated — only centralized to
+ * the one place below.
+ *
+ * Throws the same `TypeError`, with the same message shape, as
+ * `resolveScope` throws for an `id` outside `'global' | 'local'` — both call
+ * `validateScopeId` above, so the two error contracts cannot diverge.
+ *
+ * Deliberately throws, rather than returning `false`, for an out-of-union
+ * value — unlike the inline `scope === 'global'` comparison it replaced,
+ * which silently returned `false` for anything unrecognized. The
+ * alternative is silently treating an unknown scope as "not global" and
+ * writing artifacts to the wrong place, which is worse than failing loud.
+ * A caller holding an optional `scope` (e.g. a raw `Layout.scope`) must
+ * default it before calling this — see `surface.cts` for the pattern.
+ */
+function isGlobalScope(scope) {
+    return validateScopeId(scope, 'isGlobalScope') === 'global';
+}
+/**
+ * Project a bare `InstallScope` down to its `hostPrecedenceRank` — the SAME
+ * `HOST_PRECEDENCE_RANK` table `resolveScope`'s `ResolvedScope.hostPrecedenceRank`
+ * field reads, exposed standalone so a caller that only needs the ranking (not a
+ * full config-home resolution, which touches the filesystem via
+ * `resolveConfigHomeFromDescriptor`) never has to re-derive `{global: 2, local:
+ * 1}` as a second copy of the same fact. First consumer: `resolveTriggerSurface`
+ * (`runtime-artifact-layout.cts`, #2871 Phase 2), which is documented pure — no
+ * filesystem — so it cannot call `resolveScope` itself. Same validation/error
+ * contract as `resolveScope` / `isGlobalScope`: all three share `validateScopeId`,
+ * so an out-of-union `id` throws the same `TypeError` shape everywhere.
+ */
+function scopeRank(id) {
+    return HOST_PRECEDENCE_RANK[validateScopeId(id, 'scopeRank')];
+}
+/**
+ * Both scope ids, highest host precedence first. The ONE ordering of the
+ * install-scope axis: `runtime-artifact-layout.cts`'s trigger resolution and
+ * `installed-surface-resolver.cts`'s scope-record construction both consume
+ * this rather than each re-declaring `['global','local']` (#2872 review
+ * finding — this repo's recorded "generative fix divergence" class). Frozen so
+ * a caller cannot reorder it for everyone else. Ordering is not arbitrary: it
+ * is `scopeRank` descending, and a test locks that so the two cannot drift.
+ */
+exports.SCOPE_ORDER = Object.freeze(['global', 'local']);

package/gsd-core/bin/lib/install-shadow-report.cjs

@@ -0,0 +1,385 @@
+"use strict";
+/**
+ * install-shadow-report.cts — Cross-Scope Shadow Report Module (#2873, epic
+ * #2866 Phase 4a — governed by
+ * `.gsd/phase/feat-2873-cross-scope-shadowing/40-design.md`).
+ *
+ * A read-only PROJECTION over `resolveInstalledSurfaces`
+ * (`installed-surface-resolver.cts`, #2872 Phase 3). That module answers
+ * "what is installed"; it is documented there as read-only, and rendering
+ * plus sanitization are a different concern with a different consumer set
+ * (installer + `/gsd-health`) — the design doc's "Rejected" #5 is why this is
+ * a separate leaf module rather than a second export bolted onto the
+ * resolver.
+ *
+ * ── What "shadowed" means here ──────────────────────────────────────────────
+ * A trigger is shadowed when `resolveTriggerSurface` (via the resolver)
+ * recorded a non-null `shadowedBy` for it: two scopes both installed a
+ * trigger-bearing artifact under the SAME trigger name, and only one wins.
+ * For claude (`skills`@global vs `commands`@local) the KINDS differ, so the
+ * loser's entire spec tree becomes unreachable through the trigger — the bug
+ * #2218 diagnosed. For the 12 both-scopes-`skills` runtimes the kinds are the
+ * SAME on both sides, so the loser is merely overridden, not vanished
+ * (design row #5 / "Not-corruption"). `kindsDiffer` on `ShadowReport` is what
+ * lets `renderShadowReport` word the two cases correctly.
+ *
+ * ── Report, don't correct (mirrors the resolver's own law) ─────────────────
+ * `mismatches` surfaces a declared runtime/scope that disagrees with the
+ * probed one (Postel's Law, design doc: liberal in what is accepted, but the
+ * mismatch is never silently absorbed). This module never substitutes a
+ * declared value for a probed one; it only reports the disagreement the
+ * resolver already computed.
+ *
+ * ── Sanitize at the render seam ─────────────────────────────────────────────
+ * `declaredRuntime` is attacker-influenceable (it comes from a manifest that
+ * may live inside a merely-cloned repository) and length-bounded but
+ * deliberately NOT charset-gated by the reader (`declaredRuntimeMatchesProbe`
+ * needs the raw value there). THIS module is what renders it to an operator,
+ * so this module owns the guard — `sanitizeForRender` strips ANSI escapes,
+ * C0/C1 controls, and Unicode bidi overrides/isolates, then collapses
+ * whitespace. It never truncates: `readInstallManifest` already caps at 64
+ * chars, and a second truncation here would double-truncate.
+ *
+ * Trigger names, by contrast, are already `SAFE_STEM`-gated upstream
+ * (`installed-surface-resolver.cts`'s `deriveStemsForKindEntry`) before they
+ * ever reach a `TriggerSurface` — this module does not re-gate them.
+ *
+ * ── Per-scope truth filter (why this lives HERE, not in the resolver) ──────
+ * `resolveOneRuntime` (`installed-surface-resolver.cts`) builds ONE union of
+ * every installed scope's `stems` and hands that single list to
+ * `resolveTriggerSurface`, which then synthesizes a candidate trigger for
+ * EVERY stem at EVERY installed scope's trigger-bearing kind entry —
+ * regardless of whether that specific scope's own manifest actually shipped
+ * that stem. Concretely: a global `full`-profile install (stems a, b, c)
+ * alongside a local `core`-profile install (stem a only) unions to
+ * `{a, b, c}`, and `resolveTriggerSurface` then reports `commands@local`
+ * candidates for b and c too — trigger names for artifacts that do not exist
+ * on disk at that scope. Left unfiltered, this module would tell the user
+ * `/gsd-b` and `/gsd-c` are shadowed local commands when there is no local
+ * artifact for either at all — over-reporting that is not cosmetic, since
+ * the whole point of this report is to make a real failure legible.
+ *
+ * `resolveTriggerSurface`'s API takes ONE stem list shared by every scope it
+ * is asked about, so per-scope truth cannot be expressed through it without
+ * either widening a shipped Phase-2 contract other callers may depend on, or
+ * calling it once per scope and re-implementing its winner computation
+ * (`isHigherPriority`) here as a second, driftable copy. `resolveOneRuntime`
+ * / `resolveInstalledSurfaces` (Phase 3, #2872) is likewise a shipped module
+ * this task deliberately leaves untouched. This module already receives the
+ * full `InstalledRuntimeSurface`, including each scope's own REAL `stems`
+ * list (`installed-surface-resolver.cts`'s `deriveStemsFromManifest`) — so
+ * the correction belongs here, as a filter over `resolveTriggerSurface`'s
+ * already-computed `shadowedBy` groups: a trigger is reported as shadowed
+ * only when its underlying stem is present in BOTH the winner's scope's own
+ * `stems` AND the shadowed side's scope's own `stems` — i.e. an artifact
+ * genuinely exists at both scopes, not merely "some stem exists somewhere in
+ * the union".
+ *
+ * `TriggerSurface` does not carry the originating stem OR the composing
+ * prefix on its output — only the already-composed `trigger` string
+ * (`${prefix}${stem}`) — so the stem cannot be read off it directly. Rather
+ * than hand-roll a fixed-offset `trigger.slice(4)` (which would silently
+ * assume every runtime's prefix is exactly `gsd-` — true today, but not a
+ * contract this module owns), the prefix is recovered the honest way: by
+ * re-resolving that scope's `ArtifactKind` layout (`resolveRuntimeArtifactLayout`
+ * / `resolveRuntimeArtifactLayoutFromRegistry`, the SAME layout descriptor
+ * `resolveTriggerSurface` itself reads its `entry.prefix` from) for the
+ * winner's and shadowed side's own `(scope, kind)`, and reading `.prefix`
+ * off the matching kind entry. This is metadata-only (constructing an
+ * `ArtifactKind` never touches the filesystem — see
+ * `runtime-artifact-layout.cts`'s kind-builder functions), so it costs
+ * nothing beyond a small per-`(scope,kind)` memo. If a prefix cannot be
+ * resolved at all (a `TypeError` from an unexpected registry shape), the
+ * trigger is conservatively DROPPED rather than kept — the same
+ * report-nothing-you-cannot-prove posture as the rest of this filter.
+ *
+ * ── Pure with respect to caller-visible state ───────────────────────────────
+ * `buildShadowReport` builds a fresh `ShadowReport` (fresh arrays, fresh
+ * objects) on every call, exactly as the resolver documents for itself
+ * (`installed-surface-resolver.cts`'s "Pure with respect to caller-visible
+ * state" paragraph) — no shared or cached state between calls.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SHADOW_REASON = void 0;
+exports.sanitizeForRender = sanitizeForRender;
+exports.buildShadowReport = buildShadowReport;
+exports.renderShadowReport = renderShadowReport;
+const installed_surface_resolver_cjs_1 = require("./installed-surface-resolver.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const runtimeArtifactLayoutMod = require("./runtime-artifact-layout.cjs");
+const { resolveRuntimeArtifactLayout, resolveRuntimeArtifactLayoutFromRegistry } = runtimeArtifactLayoutMod;
+// ── Reason enum ─────────────────────────────────────────────────────────
+exports.SHADOW_REASON = Object.freeze({
+    NOT_SHADOWED: 'not_shadowed',
+    SCOPE_SHADOWED: 'scope_shadowed',
+    RESOLVER_UNAVAILABLE: 'resolver_unavailable',
+});
+// ── Sanitization ────────────────────────────────────────────────────────
+/** CSI (`\x1b[...final`) and OSC (`\x1b]...BEL-or-ST`) sequences. An
+ *  unterminated/malformed sequence is left for the C0-control strip below to
+ *  remove the bare `\x1b` byte — liberal, never a throw. */
+const ANSI_RE = /\x1b(?:\[[0-?]*[ -/]*[@-~]|\][^\x07\x1b]*(?:\x07|\x1b\\))/g;
+/** C0 controls (`\x00`-`\x1f`, including any `\x1b` the ANSI strip above did
+ *  not consume) and DEL/C1 (`\x7f`-`\x9f`). */
+const CONTROL_RE = /[\x00-\x1f\x7f-\x9f]/g;
+/** Unicode bidi embedding/override controls (U+202A-U+202E) and bidi
+ *  isolates (U+2066-U+2069) — the RTL-spoofing class the design doc's row
+ *  #13 names. */
+const BIDI_RE = /[\u{202A}-\u{202E}\u{2066}-\u{2069}]/gu;
+/** Combining marks (U+0300-U+036F) — "zalgo" text. Stacked onto the
+ *  preceding base character, an unbounded run visually overflows into
+ *  adjacent terminal cells/rows even though the string stays within the
+ *  64-char cap `readInstallManifest` enforces. Written as `\u{...}` escapes
+ *  (not literal combining characters) so the source itself stays plain
+ *  ASCII and does not visually combine in editors/diffs. */
+const COMBINING_MARK_RE = /[\u{0300}-\u{036F}]/gu;
+/** Zero-width characters: ZWSP (U+200B), ZWNJ (U+200C), ZWJ (U+200D), and
+ *  BOM/ZWNBSP (U+FEFF). None of these are JS `\s`, so they survive both the
+ *  char-count cap and the whitespace-collapse step below undetected. */
+const ZERO_WIDTH_RE = /[\u{200B}-\u{200D}\u{FEFF}]/gu;
+/**
+ * Sanitize a `declaredRuntime` (or any similarly attacker-influenceable
+ * string) for terminal/console rendering. `null` passes through as `null`;
+ * `''` passes through as `''`. Strips ANSI escapes, C0/C1 controls, Unicode
+ * bidi overrides/isolates, combining marks (zalgo), and zero-width
+ * characters (replacing each stripped run with nothing — never a space),
+ * then collapses any remaining whitespace run (including adjacent spaces
+ * left behind by a removed newline) to a single space and trims.
+ *
+ * Idempotent by construction: once ANSI/control/bidi/combining/zero-width
+ * bytes are gone and whitespace is collapsed to single internal spaces with
+ * no leading/trailing space, a second pass finds nothing left to strip or
+ * collapse. Pure character-class filter — never truncates; `readInstallManifest`
+ * already caps at 64 chars.
+ */
+function sanitizeForRender(value) {
+    if (value === null)
+        return null;
+    const stripped = value
+        .replace(ANSI_RE, '')
+        .replace(CONTROL_RE, '')
+        .replace(BIDI_RE, '')
+        .replace(COMBINING_MARK_RE, '')
+        .replace(ZERO_WIDTH_RE, '');
+    return stripped.replace(/\s+/g, ' ').trim();
+}
+// ── Per-scope truth filter helpers ─────────────────────────────────────
+/**
+ * Build a `(scope, kind) -> prefix | null` lookup for one runtime, memoized
+ * per call to `buildShadowReport` (never shared across calls — matches this
+ * module's "fresh objects on every call" contract). `null` means "could not
+ * be resolved" (unknown scope record, or a `TypeError` from the layout
+ * resolver) — the caller treats that as "cannot honestly attribute this
+ * trigger to a real stem here", not as "assume it is fine".
+ */
+function buildPrefixLookup(runtime, scopeRecords, opts) {
+    const cache = new Map();
+    return (scope, kind) => {
+        const key = `${scope}:${kind}`;
+        if (cache.has(key))
+            return cache.get(key);
+        const record = scopeRecords.get(scope);
+        let prefix = null;
+        if (record) {
+            try {
+                const layout = opts.registry !== undefined
+                    ? resolveRuntimeArtifactLayoutFromRegistry(opts.registry, runtime, record.configHome, record.scope)
+                    : resolveRuntimeArtifactLayout(runtime, record.configHome, record.scope);
+                const kindEntry = layout.kinds.find((k) => k.kind === kind);
+                prefix = kindEntry ? kindEntry.prefix : null;
+            }
+            catch {
+                // Unknown runtime / malformed registry — degrade to "cannot resolve",
+                // never throw out of a report builder (matches this module's own
+                // RESOLVER_UNAVAILABLE degrade-not-propagate posture above).
+                prefix = null;
+            }
+        }
+        cache.set(key, prefix);
+        return prefix;
+    };
+}
+/** `trigger` minus `prefix`, or `null` when `prefix` is unknown, does not
+ *  actually prefix `trigger`, or the remainder would be empty (a `prefix`
+ *  covering the whole trigger string is not a real stem). */
+function stemFromTrigger(trigger, prefix) {
+    if (prefix === null || !trigger.startsWith(prefix))
+        return null;
+    const stem = trigger.slice(prefix.length);
+    return stem === '' ? null : stem;
+}
+/**
+ * True when `t` (a `resolveTriggerSurface`-reported shadowed trigger) is a
+ * REAL cross-scope shadow: its stem is present in the winner's OWN scope
+ * `stems` and, independently, in the shadowed side's OWN scope `stems`. See
+ * the module-level "Per-scope truth filter" comment for why this check
+ * exists and why it lives here rather than in the resolver.
+ */
+function isGenuinelyShadowed(t, scopeRecords, prefixFor) {
+    if (t.shadowedBy === null)
+        return false;
+    const winnerRecord = scopeRecords.get(t.shadowedBy.scope);
+    const shadowedRecord = scopeRecords.get(t.scope);
+    const winnerStem = stemFromTrigger(t.trigger, prefixFor(t.shadowedBy.scope, t.shadowedBy.kind));
+    const shadowedStem = stemFromTrigger(t.trigger, prefixFor(t.scope, t.kind));
+    if (winnerStem === null || shadowedStem === null)
+        return false;
+    return (winnerRecord?.stems ?? []).includes(winnerStem) && (shadowedRecord?.stems ?? []).includes(shadowedStem);
+}
+// ── Report builder ──────────────────────────────────────────────────────
+/**
+ * Build a shadow report for one runtime. `opts` is forwarded VERBATIM to
+ * `resolveInstalledSurfaces` — this function adds no option of its own.
+ * Production call shape: `buildShadowReport('claude', { home, cwd })`.
+ *
+ * A `resolveInstalledSurfaces` `TypeError` (unknown runtime, or
+ * `configHome.kind === 'none'`, e.g. vscode — design row #7) degrades to
+ * `reason: RESOLVER_UNAVAILABLE` rather than propagating: an install-time or
+ * `/gsd-health` caller must never crash because a runtime has no installable
+ * config directory. Any other error type is rethrown — mirrors the
+ * resolver's own `TypeError` narrowing (`resolveInstalledSurfaces`'s sweep
+ * catch, and `buildScopeRecord`'s stem-derivation catch) so the two cannot
+ * drift apart.
+ */
+function buildShadowReport(runtime, opts = {}) {
+    let surfaces;
+    try {
+        surfaces = (0, installed_surface_resolver_cjs_1.resolveInstalledSurfaces)(runtime, opts);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        return {
+            runtime,
+            reason: exports.SHADOW_REASON.RESOLVER_UNAVAILABLE,
+            shadowed: false,
+            winner: null,
+            shadowedSide: null,
+            kindsDiffer: false,
+            triggers: [],
+            mismatches: [],
+        };
+    }
+    // resolveInstalledSurfaces(runtime, opts) with an explicit string `runtime`
+    // always returns exactly one element (see its own doc comment).
+    const surface = surfaces[0];
+    // Per-scope truth filter (see module comment): `surface.triggers` may
+    // contain candidates synthesized from the CROSS-SCOPE stem union
+    // (`installed-surface-resolver.cts`'s `stemUnion`) that do not correspond
+    // to a real artifact at one or both scopes. Only a trigger whose stem is
+    // provably present in BOTH the winner's own `stems` and the shadowed
+    // side's own `stems` is reported.
+    const scopeRecords = new Map(surface.scopes.map((r) => [r.scope, r]));
+    const prefixFor = buildPrefixLookup(runtime, scopeRecords, opts);
+    const shadowedSurfaces = surface.triggers.filter((t) => isGenuinelyShadowed(t, scopeRecords, prefixFor));
+    const triggers = shadowedSurfaces
+        .map((t) => ({
+        trigger: t.trigger,
+        // `shadowedBy` is non-null by construction of the filter above.
+        winnerKind: t.shadowedBy.kind,
+        winnerScope: t.shadowedBy.scope,
+        shadowedKind: t.kind,
+        shadowedScope: t.scope,
+    }))
+        .sort((a, b) => (a.trigger < b.trigger ? -1 : a.trigger > b.trigger ? 1 : 0));
+    const mismatches = [];
+    for (const record of surface.scopes) {
+        if (record.declaredRuntimeMatchesProbe === false || record.declaredScopeMatchesProbe === false) {
+            mismatches.push({
+                scope: record.scope,
+                // Postel's Law (design doc): sanitized here because this is the
+                // render seam — never silently absorbed, always surfaced.
+                declaredRuntime: sanitizeForRender(record.declaredRuntime),
+                declaredRuntimeMatchesProbe: record.declaredRuntimeMatchesProbe,
+                declaredScope: record.declaredScope,
+                declaredScopeMatchesProbe: record.declaredScopeMatchesProbe,
+            });
+        }
+    }
+    if (triggers.length === 0) {
+        return {
+            runtime,
+            reason: exports.SHADOW_REASON.NOT_SHADOWED,
+            shadowed: false,
+            winner: null,
+            shadowedSide: null,
+            kindsDiffer: false,
+            triggers: [],
+            mismatches,
+        };
+    }
+    // Winner/shadowedSide are the (kind,scope) pair of the FIRST shadowed
+    // trigger (post-sort, for the same determinism reason the array itself is
+    // sorted). They are asserted-by-construction uniform across the whole set
+    // for every runtime this module has seen (every trigger shadowed by the
+    // SAME scope, with the SAME two kinds, on one machine) — but if a future
+    // registry shape ever produced a non-uniform set, this still returns the
+    // first pair rather than throwing; every distinct (kind,scope) pair is
+    // already visible per-entry in `triggers` itself, so nothing is lost.
+    const first = triggers[0];
+    const winner = { kind: first.winnerKind, scope: first.winnerScope };
+    const shadowedSide = { kind: first.shadowedKind, scope: first.shadowedScope };
+    return {
+        runtime,
+        reason: exports.SHADOW_REASON.SCOPE_SHADOWED,
+        shadowed: true,
+        winner,
+        shadowedSide,
+        kindsDiffer: winner.kind !== shadowedSide.kind,
+        triggers,
+        mismatches,
+    };
+}
+// ── Renderer ────────────────────────────────────────────────────────────
+/**
+ * Render a `ShadowReport` to plain lines — no ANSI, no color, no leading
+ * indent. The caller (installer console output, `/gsd-health` text mode)
+ * owns terminal formatting; this keeps the module free of terminal concerns
+ * and testable without a spawned process. Structured (`--json`) health
+ * output (design row #17) consumes the typed `ShadowReport` directly and
+ * never calls this function.
+ *
+ * `reason !== SCOPE_SHADOWED` renders nothing — there is nothing to report
+ * (design rows #1, #2, #6, #7, #8, #11).
+ */
+function renderShadowReport(report, opts = {}) {
+    if (report.reason !== exports.SHADOW_REASON.SCOPE_SHADOWED || report.winner === null || report.shadowedSide === null) {
+        return [];
+    }
+    const sampleLimit = opts.sampleLimit ?? 5;
+    const count = report.triggers.length;
+    const plural = count === 1 ? '' : 's';
+    const { winner, shadowedSide, kindsDiffer } = report;
+    const lines = [];
+    lines.push(kindsDiffer
+        ? `${count} trigger${plural} shadowed: the ${shadowedSide.scope} ${shadowedSide.kind} surface is unreachable through ${count === 1 ? 'that trigger' : 'those triggers'} — ${winner.scope} ${winner.kind} wins instead.`
+        : `${count} trigger${plural} shadowed: the ${shadowedSide.scope} ${shadowedSide.kind} ${count === 1 ? 'entry is' : 'entries are'} overridden by ${winner.scope} ${winner.kind}.`);
+    // Trigger names in `report.triggers` are already SAFE_STEM-gated upstream
+    // (installed-surface-resolver.cts's deriveStemsForKindEntry) — no re-gating
+    // needed here.
+    const sample = report.triggers.slice(0, sampleLimit);
+    for (const t of sample) {
+        lines.push(`  - ${t.trigger}: ${t.shadowedScope}/${t.shadowedKind} shadowed by ${t.winnerScope}/${t.winnerKind}`);
+    }
+    const remaining = count - sample.length;
+    if (remaining > 0) {
+        lines.push(`  ...and ${remaining} more`);
+    }
+    for (const m of report.mismatches) {
+        // Re-sanitized defensively: `buildShadowReport` already sanitizes
+        // `declaredRuntime` before it reaches a `ShadowReport`, and
+        // `sanitizeForRender` is idempotent, so this is a no-op in the normal
+        // path and a real guard against a hand-built `ShadowReport` (e.g. a
+        // renderer-only test) that skipped it.
+        const declaredRuntime = sanitizeForRender(m.declaredRuntime);
+        const parts = [];
+        if (m.declaredRuntimeMatchesProbe === false) {
+            parts.push(`declared runtime "${declaredRuntime}" does not match this runtime`);
+        }
+        if (m.declaredScopeMatchesProbe === false) {
+            parts.push(`declared scope "${m.declaredScope}" does not match the probed ${m.scope} scope`);
+        }
+        lines.push(`Note: ${m.scope} scope manifest mismatch — ${parts.join('; ')}.`);
+    }
+    return lines;
+}