@opengsd/gsd-core 1.15.0 → 1.17.0

package/gsd-core/bin/lib/runtime-name-policy.cjs

@@ -15,9 +15,12 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.NO_LOCAL_CONFIG_DIR_SENTINEL = exports.RetiredRuntimeError = exports.RETIRED_RUNTIME_IDS = void 0;
+exports.NO_LOCAL_CONFIG_DIR_SENTINEL = exports.FALLBACK_HOST_BEHAVIORS = exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES = exports.RetiredRuntimeError = exports.UnknownRuntimeError = exports.RETIRED_RUNTIME_IDS = void 0;
 exports.isRetiredRuntimeId = isRetiredRuntimeId;
 exports.assertNotRetiredRuntime = assertNotRetiredRuntime;
+exports.isKnownRuntimeId = isKnownRuntimeId;
+exports.assertKnownRuntime = assertKnownRuntime;
+exports.hostBehaviorsFor = hostBehaviorsFor;
 exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
 exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
 exports.getProjectInstructionFile = getProjectInstructionFile;
@@ -25,7 +28,6 @@ exports.getDirName = getDirName;
 exports.getRuntimeLabel = getRuntimeLabel;
 exports.getGlobalConfigHomeFragment = getGlobalConfigHomeFragment;
 exports.runtimeFlags = runtimeFlags;
-exports.getRuntimeNewProjectCommand = getRuntimeNewProjectCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 /**
@@ -92,6 +94,22 @@ const RETIRED_RUNTIME_SPELLINGS = new Map(Array.from(RETIRED_RUNTIME_DETAILS.key
  * with like.
  */
 exports.RETIRED_RUNTIME_IDS = new Set(RETIRED_RUNTIME_DETAILS.keys());
+/**
+ * Error thrown when a non-empty runtime id that is neither registered nor a
+ * known non-registry host reaches a descriptor accessor (ADR-5057 §5, #5169).
+ * Before this, such an id silently resolved to Claude Code's values.
+ */
+class UnknownRuntimeError extends Error {
+    code = 'GSD_UNKNOWN_RUNTIME';
+    runtimeId;
+    constructor(runtimeId) {
+        super(`Runtime "${runtimeId}" is not registered in the capability registry. `
+            + 'Refusing to resolve it, because the previous behaviour silently returned Claude Code\'s values.');
+        this.name = 'UnknownRuntimeError';
+        this.runtimeId = runtimeId;
+    }
+}
+exports.UnknownRuntimeError = UnknownRuntimeError;
 /** Error thrown when a retired runtime id reaches a resolution accessor. */
 class RetiredRuntimeError extends Error {
     code = 'GSD_RETIRED_RUNTIME';
@@ -127,6 +145,120 @@ function assertNotRetiredRuntime(runtime) {
         return;
     throw new RetiredRuntimeError(id, detail);
 }
+/**
+ * Legacy runtime ids that have a genuine, dedicated resolution branch in
+ * `runtime-homes.cts` but no capability-registry descriptor (#3024). They are
+ * KNOWN ids: every accessor resolves them rather than refusing. Enumerated by
+ * hand and MUST stay in lockstep with `getGlobalConfigDir`'s hardcoded
+ * branches — add an id only after confirming it has a real dedicated branch.
+ */
+exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES = Object.freeze({
+    // Grok's agents home: `GROK_AGENTS_HOME`, else `~/.agents` (dir = path segments under $HOME).
+    grok: Object.freeze({ env: 'GROK_AGENTS_HOME', dir: Object.freeze(['.agents']) }),
+});
+exports.LEGACY_NON_REGISTRY_RUNTIME_IDS = new Set(Object.keys(exports.LEGACY_NON_REGISTRY_RUNTIME_HOMES));
+/** The capability registry's `runtimes` map, or `null` when it fails to load. */
+function loadRegistryRuntimes() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        const reg = require('./capability-registry.cjs');
+        return (reg && reg.runtimes) || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when `runtime` is a registered runtime id (own property of the registry
+ * `runtimes` map — never an inherited key such as `__proto__`/`constructor`)
+ * or one of {@link LEGACY_NON_REGISTRY_RUNTIME_IDS}. Raw-id match: no trimming,
+ * no case folding, no alias expansion.
+ */
+function isKnownRuntimeId(runtime) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return false;
+    const runtimes = loadRegistryRuntimes();
+    if (runtimes && Object.prototype.hasOwnProperty.call(runtimes, runtime))
+        return true;
+    return exports.LEGACY_NON_REGISTRY_RUNTIME_IDS.has(runtime);
+}
+/**
+ * The ONE refusal every descriptor accessor shares (ADR-5057 §5, #5169).
+ * No-op for an absent id (`''`, non-string): that is the documented
+ * "no runtime selected" generic path. A retired id throws
+ * {@link RetiredRuntimeError}; any other non-empty id that is not known throws
+ * {@link UnknownRuntimeError} instead of silently resolving to Claude Code's
+ * values. When the registry itself failed to load, unknown-ness cannot be
+ * proven, so the check degrades to a no-op (the #338 floor in
+ * {@link hostBehaviorsFor} still protects the reference host).
+ */
+function assertKnownRuntime(runtime) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return;
+    assertNotRetiredRuntime(runtime);
+    if (loadRegistryRuntimes() === null)
+        return;
+    if (!isKnownRuntimeId(runtime))
+        throw new UnknownRuntimeError(runtime);
+}
+/**
+ * The #338-privacy fail-safe floor: host behaviors for the two hosts whose
+ * generic fallthrough would be WRONG if the registry failed to load. Moved
+ * here from `bin/install.js` so the registry-load-failure degrade lives in the
+ * single host-behaviors accessor instead of one of three copies (#5169).
+ */
+exports.FALLBACK_HOST_BEHAVIORS = Object.freeze({
+    claude: Object.freeze({
+        settingsFileByScope: Object.freeze({ local: 'settings.local.json', global: 'settings.json' }),
+        permissionsSchema: 'claude',
+        sourceMarkerFile: '.gsd-source',
+        hyphenNameAgentBody: true,
+        legacyCommandsGsdInstallMigration: true,
+        legacyCommandsGsdUninstall: 'global',
+    }),
+    // antigravity's global config dir is resolved dynamically (env-overridable,
+    // multi-segment); this floor keeps that routing intact if the registry fails
+    // to load instead of falling through to the wrong '.claude' fragment (#2096).
+    antigravity: Object.freeze({ globalDirResolver: 'antigravity' }),
+});
+/**
+ * The single accessor for a runtime's host behaviors
+ * (capabilities/<runtime>/capability.json -> runtime.hostBehaviors). Replaces
+ * the three private `_hostBehaviors` copies in `bin/install.js`,
+ * `install-engine.cts` and `runtime-artifact-conversion.cts`.
+ *
+ * - absent id (`''`, non-string) → `{}` (generic path).
+ * - registered id → the descriptor's `hostBehaviors` (or `{}` when it declares
+ *   none).
+ * - known non-registry id (`grok`) → `{}`.
+ * - registry failed to load → the #338 floor for the ids it covers, else `{}`.
+ * - any other id (unregistered, retired, a prototype key) → `{}`: no declared
+ *   behaviors, which is the GENERIC path — never Claude Code's behaviors.
+ *
+ * Unlike the path/label accessors (`getDirName`, `getGlobalConfigDir`, …), whose
+ * fallthrough answer is Claude Code's value and therefore a silent wrong answer
+ * (#4632), an absent behavior is the correct answer for a label GSD does not
+ * know — and this accessor is read by guard and hook code on user-supplied
+ * runtime labels (stale config, a retired id), where a throw would crash the
+ * session rather than skip a behavior. ADR-5057 §5 Phase 10 amendment.
+ *
+ * `registry` is injectable so the load-failure branch is unit-testable.
+ */
+function hostBehaviorsFor(runtime, registry) {
+    if (typeof runtime !== 'string' || runtime.length === 0)
+        return {};
+    const floor = () => Object.prototype.hasOwnProperty.call(exports.FALLBACK_HOST_BEHAVIORS, runtime)
+        ? exports.FALLBACK_HOST_BEHAVIORS[runtime]
+        : {};
+    const runtimes = registry === undefined ? loadRegistryRuntimes() : (registry && registry.runtimes) || null;
+    if (runtimes === null)
+        return floor();
+    if (Object.prototype.hasOwnProperty.call(runtimes, runtime)) {
+        const declared = runtimes[runtime]?.runtime?.hostBehaviors;
+        return declared ? declared : floor();
+    }
+    return {};
+}
 const FALLBACK_ALIASES = {
     claude: ['claude', 'claude-code', 'claude-cli'],
     opencode: ['opencode', 'open-code', 'opencode-cli'],
@@ -302,7 +434,7 @@ exports.NO_LOCAL_CONFIG_DIR_SENTINEL = '(no-local-config-dir)';
 function getDirName(runtime) {
     // Same silent-wrong-answer class as the four accessors AC#1 names: this
     // returned '.claude' for a retired id, and it feeds runtimeConfigDir.
-    assertNotRetiredRuntime(runtime);
+    assertKnownRuntime(runtime);
     if (!runtime)
         return '.claude';
     // eslint-disable-next-line @typescript-eslint/no-require-imports
@@ -373,7 +505,7 @@ const RUNTIME_LABELS = {
  * 'Claude Code'. Sibling to `getDirName`; pure (no I/O).
  */
 function getRuntimeLabel(runtime) {
-    assertNotRetiredRuntime(runtime);
+    assertKnownRuntime(runtime);
     if (!runtime)
         return 'Claude Code';
     const label = RUNTIME_LABELS[runtime];
@@ -429,7 +561,7 @@ const GLOBAL_CONFIG_HOME_FRAGMENTS = {
  * dynamically). Pure: no I/O. Sibling to `getDirName` / `getRuntimeLabel`.
  */
 function getGlobalConfigHomeFragment(runtime) {
-    assertNotRetiredRuntime(runtime);
+    assertKnownRuntime(runtime);
     if (!runtime)
         return DEFAULT_CONFIG_HOME_FRAGMENT;
     const frag = GLOBAL_CONFIG_HOME_FRAGMENTS[runtime];
@@ -475,25 +607,8 @@ function runtimeFlags(runtime) {
     }
     return Object.freeze(flags);
 }
-/**
- * The `/gsd-new-project` invocation syntax per runtime — the post-install
- * "next step" command string. Most runtimes use the default `/gsd-new-project`;
- * a few hosts need a different surface syntax. Collapses the 14-line
- * `if (runtime === 'x') command = ...` chain in bin/install.js's next-step
- * message (ADR-1239 Phase B / #1679 AC2). Pure: no I/O.
- */
-const DEFAULT_NEW_PROJECT_COMMAND = '/gsd-new-project';
-const RUNTIME_NEW_PROJECT_COMMANDS = {
-    codex: '$gsd-new-project',
-    cursor: 'gsd-new-project (mention the skill name)',
-    kimi: '/skill:gsd-new-project',
-};
-function getRuntimeNewProjectCommand(runtime) {
-    // Deliberately NOT retirement-guarded: this value does not vary by runtime
-    // in a way that makes a retired id a WRONG answer, so throwing here would
-    // cost callers a crash without correcting anything.
-    if (!runtime)
-        return DEFAULT_NEW_PROJECT_COMMAND;
-    const c = RUNTIME_NEW_PROJECT_COMMANDS[runtime];
-    return typeof c === 'string' && c.length > 0 ? c : DEFAULT_NEW_PROJECT_COMMAND;
-}
+// The `/gsd-new-project` next-step command is no longer a per-runtime table
+// here: it is generated from the runtime's registered trigger surface by
+// `resolveAdvertisedNewProject` (runtime-artifact-layout.cts, #5215, ADR-5057
+// §5 Phase 12), so what the installer advertises cannot differ from what a
+// runtime registered.

package/gsd-core/bin/lib/runtime-slash.cjs

@@ -34,7 +34,9 @@ exports._setInstallRuntimeMarkerForTests = _setInstallRuntimeMarkerForTests;
 exports._resetInstallRuntimeMarkerCacheForTests = _resetInstallRuntimeMarkerCacheForTests;
 exports.resolveExplicitRuntime = resolveExplicitRuntime;
 exports.resolveRuntime = resolveRuntime;
+exports.resolveActiveRuntime = resolveActiveRuntime;
 exports.formatGsdSlashFor = formatGsdSlashFor;
+exports.runtimeCommand = runtimeCommand;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
@@ -148,31 +150,36 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
     const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME']);
     if (envRuntime)
         return envRuntime;
-    if (projectDir) {
-        try {
-            // Read config.json directly (not via loadConfig). loadConfig has a side
-            // effect of normalizing and re-writing legacy keys back to disk, which
-            // would mutate the project file just to read the runtime name. We only
-            // need the literal `runtime:` value, so a plain JSON read is sufficient
-            // and side-effect-free.
-            const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
-            if (node_fs_1.default.existsSync(configPath)) {
-                const raw = node_fs_1.default.readFileSync(configPath, 'utf-8');
-                const parsed = JSON.parse(raw);
-                if (parsed && typeof parsed === 'object' && 'runtime' in parsed) {
-                    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(parsed['runtime']);
-                    if (configRuntime)
-                        return configRuntime;
-                }
-            }
-        }
-        catch {
-            // Fall through to default — a missing/broken config must not crash
-            // runtime output formatting.
-        }
-    }
+    const config = readProjectConfig(projectDir);
+    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(config ? config['runtime'] : undefined);
+    if (configRuntime)
+        return configRuntime;
     return null;
 }
+/**
+ * Read `<projectDir>/.planning/config.json` as a plain object, or `null` when
+ * there is no project, no file, or it is unreadable or not an object.
+ *
+ * Read directly (not via loadConfig). loadConfig has a side effect of
+ * normalizing and re-writing legacy keys back to disk, which would mutate the
+ * project file just to read the runtime name. A plain JSON read is sufficient
+ * and side-effect-free. A missing or broken config must not crash runtime
+ * output formatting, so every failure degrades to `null`.
+ */
+function readProjectConfig(projectDir) {
+    if (!projectDir)
+        return null;
+    try {
+        const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
+        if (!node_fs_1.default.existsSync(configPath))
+            return null;
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(configPath, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Resolve the effective runtime for a project directory.
  *
@@ -195,13 +202,24 @@ function resolveExplicitRuntime(projectDir, env = process.env) {
  * @returns the resolved runtime name
  */
 function resolveRuntime(projectDir) {
-    const explicit = resolveExplicitRuntime(projectDir);
-    if (explicit)
-        return explicit;
-    const markerRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(readInstallRuntimeMarker());
-    if (markerRuntime)
-        return markerRuntime;
-    return 'claude';
+    // The same chain `resolveActiveRuntime` owns, fed by a project directory:
+    // one implementation, so the two entry points cannot drift (#5169).
+    return resolveActiveRuntime(readProjectConfig(projectDir));
+}
+/**
+ * Resolve the effective runtime from an ALREADY-LOADED config object — the one
+ * chain every consumer of "which runtime is this install" shares (#5169,
+ * ADR-5057 §5, #4690):
+ *
+ *   env.GSD_RUNTIME  >  config.runtime  >  install marker  >  'claude'
+ *
+ * Canonicalized, so an alias or case variant (`claude-code`, `Claude`) cannot
+ * defeat a downstream comparison. `resolveRuntime` above is the same chain for
+ * callers that hold a project directory rather than a parsed config; the marker
+ * is read through `readInstallRuntimeMarker` in both.
+ */
+function resolveActiveRuntime(config, env = process.env) {
+    return (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(env['GSD_RUNTIME'], config ? config['runtime'] : undefined, readInstallRuntimeMarker()) || 'claude';
 }
 /**
  * Convenience: format using the runtime resolved from a project directory.
@@ -210,3 +228,15 @@ function resolveRuntime(projectDir) {
 function formatGsdSlashFor(projectDir, commandName) {
     return formatGsdSlash(commandName, resolveRuntime(projectDir));
 }
+/**
+ * #4859: the command as the project's runtime registers it, typed as a string —
+ * for runtime code that builds user-facing guidance. String literals in compiled
+ * runtime code are printed verbatim (the install-time conversion only rewrites
+ * markdown artifact bodies), so a hard-coded `/gsd:<cmd>` names a command no
+ * install route registers. Route every such reference through here:
+ * `runtimeCommand(cwd, 'plan-phase 3 --research')` → `/gsd-plan-phase 3 --research`
+ * (`$gsd-plan-phase …` on Codex). `commandName` is the bare name plus any argument tail.
+ */
+function runtimeCommand(projectDir, commandName) {
+    return String(formatGsdSlashFor(projectDir, commandName));
+}

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

@@ -64,6 +64,8 @@ const node_fs_1 = __importDefault(require("node:fs"));
 // at load time and become un-mockable.
 const node_child_process_1 = __importDefault(require("node:child_process"));
 const pattern_cjs_1 = require("./pattern.cjs");
+const frontmatter_fence_cjs_1 = require("./frontmatter-fence.cjs");
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
 /**
  * Convert a filesystem path to POSIX form (forward slashes) by translating the
  * platform-native separator. Single seam for native→POSIX conversion.
@@ -146,7 +148,10 @@ function formatHookCommandForRuntime(command, opts = {}) {
 // path missed this guard and reintroduced the #166/#377 failure (#580).
 function shellHookOmitsBashRunner({ platform, runtime = 'generic', isShellHook = false } = {}) {
     const p = platform ?? process.platform;
-    return p === 'win32' && runtime === 'claude' && isShellHook;
+    // #5169: descriptor-declared (`hostBehaviors.omitBashRunnerOnWindows`). The
+    // `'generic'` default and any other non-registered label declares nothing, so
+    // it never omits the runner, exactly as before.
+    return p === 'win32' && isShellHook && (0, runtime_name_policy_cjs_1.hostBehaviorsFor)(runtime).omitBashRunnerOnWindows === true;
 }
 // Builds the command string for a local-install managed `.sh` hook. Mirrors the
 // global buildHookCommand path but uses the $CLAUDE_PROJECT_DIR-anchored prefix
@@ -1033,16 +1038,39 @@ function probeTty(opts = {}) {
     }
 }
 // ─── Platform file I/O ────────────────────────────────────────────────────────
+/**
+ * How many leading lines of LF-only `text` are its closed YAML frontmatter block (opening
+ * fence through closing fence), or 0 when there is none (an unterminated block is not
+ * frontmatter). The fence is `locateFrontmatterFence`'s — the one owner the frontmatter reader
+ * and writer (`frontmatter.cts`) also read — so the normalizer skips exactly the block every
+ * reader sees (found while implementing #5105: this was a private mirror of the reader's
+ * fence rule, because `frontmatter.cts` imports this module, and the two drifted).
+ */
+function leadingFrontmatterLineCount(text) {
+    const fence = (0, frontmatter_fence_cjs_1.locateFrontmatterFence)(text);
+    if (!fence || !fence.closed)
+        return 0;
+    // The lines before the closing fence, plus the closing fence line itself.
+    return text.slice(0, fence.closingStart).split('\n').length;
+}
 function _normalizeMd(content) {
     if (!content || typeof content !== 'string')
         return content;
     let text = content.replace(/\r\n/g, '\n');
     const lines = text.split('\n');
+    // The frontmatter block is YAML, not markdown: its lines are published exactly as written.
+    // A `# comment` is not a heading, and a blank line inserted into a multi-line quoted scalar
+    // or removed from a block scalar changes the value (found while implementing #5105).
+    const frontmatterLines = leadingFrontmatterLineCount(text);
     const result = [];
     const fenceRegex = /^```/;
     const insideFence = new Array(lines.length);
     let fenceOpen = false;
     for (let i = 0; i < lines.length; i++) {
+        if (i < frontmatterLines) {
+            insideFence[i] = false;
+            continue;
+        }
         if (fenceRegex.test(lines[i].trimEnd())) {
             if (fenceOpen) {
                 insideFence[i] = false;
@@ -1059,6 +1087,10 @@ function _normalizeMd(content) {
     }
     for (let i = 0; i < lines.length; i++) {
         const line = lines[i];
+        if (i < frontmatterLines) {
+            result.push(line);
+            continue;
+        }
         const prev = i > 0 ? lines[i - 1] : '';
         const prevTrimmed = prev.trimEnd();
         const trimmed = line.trimEnd();
@@ -1089,8 +1121,11 @@ function _normalizeMd(content) {
                 result.push('');
         }
     }
+    // The frontmatter lines are `result`'s first entries, unchanged; the blank-run collapse
+    // applies from the line ending that closes the block onward.
+    const head = result.slice(0, frontmatterLines).join('\n');
     text = result.join('\n');
-    text = text.replace(/\n{3,}/g, '\n\n');
+    text = head + text.slice(head.length).replace(/\n{3,}/g, '\n\n');
     text = text.replace(/\n*$/, '\n');
     return text;
 }