@opengsd/gsd-core 1.2.0 → 1.3.0

package/gsd-core/bin/lib/runtime-artifact-layout.cjs

@@ -0,0 +1,254 @@
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * Runtime artifact layout module — resolves the artifact directory shapes
+ * (commands, agents, skills) for each supported runtime.
+ *
+ * grok is intentionally absent: it is in runtime-homes.cjs but not wired
+ * here. The TypeError on unknown runtime is the loud-fail signal that a
+ * runtime was added to the homes list without a layout entry.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/runtime-artifact-layout.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const installProfiles = require("./install-profiles.cjs");
+const { stageSkillsForProfile, stageAgentsForProfile, stageSkillsForRuntimeAsSkills, } = installProfiles;
+// In .cts (CommonJS output) files, `require` is available as a global.
+const _require = require;
+/**
+ * Load bin/install.js exports in a test-safe way.
+ * Sets GSD_TEST_MODE only for the duration of the require() call and only if
+ * it was not already set, restoring the original value in a finally block so
+ * the module-level environment is never permanently mutated.
+ */
+function loadInstallExports() {
+    const savedTestMode = process.env['GSD_TEST_MODE'];
+    if (savedTestMode === undefined)
+        process.env['GSD_TEST_MODE'] = '1';
+    try {
+        return _require('../../../bin/install.js');
+    }
+    finally {
+        if (savedTestMode === undefined)
+            delete process.env['GSD_TEST_MODE'];
+        else
+            process.env['GSD_TEST_MODE'] = savedTestMode;
+    }
+}
+/** Cache after first successful load. */
+let _installExports = null;
+function getInstallExports() {
+    if (!_installExports)
+        _installExports = loadInstallExports();
+    return _installExports;
+}
+// ---------------------------------------------------------------------------
+// Source root finders
+// ---------------------------------------------------------------------------
+/**
+ * Locate the GSD commands/gsd source directory.
+ *
+ * Resolution order:
+ * 1. If runtimeConfigDir provided, check <runtimeConfigDir>/.gsd-source marker.
+ * 2. Walk up from __dirname using path.dirname (no literal .. segments).
+ * 3. Throw a descriptive error if neither succeeds.
+ */
+function findInstallSourceRoot(runtimeConfigDir) {
+    // Step 1: marker check
+    if (runtimeConfigDir) {
+        const markerPath = node_path_1.default.join(runtimeConfigDir, '.gsd-source');
+        if (node_fs_1.default.existsSync(markerPath)) {
+            try {
+                const src = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+                if (src && node_fs_1.default.existsSync(src))
+                    return src;
+            }
+            catch { /* fall through */ }
+        }
+    }
+    // Step 2: walk up from __dirname
+    let dir = __dirname;
+    for (let i = 0; i < 6; i++) {
+        const candidate = node_path_1.default.join(dir, 'commands', 'gsd');
+        if (node_fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`findInstallSourceRoot: could not locate commands/gsd from ${__dirname}`);
+}
+/**
+ * Locate the GSD agents source directory.
+ *
+ * Resolution order:
+ * 1. If runtimeConfigDir provided, check <runtimeConfigDir>/.gsd-source marker.
+ * 2. Walk up from __dirname using path.dirname (no literal .. segments).
+ * 3. Throw a descriptive error if neither succeeds.
+ */
+function findAgentsSourceRoot(runtimeConfigDir) {
+    // Step 1: marker check
+    if (runtimeConfigDir) {
+        const markerPath = node_path_1.default.join(runtimeConfigDir, '.gsd-source');
+        if (node_fs_1.default.existsSync(markerPath)) {
+            try {
+                const src = node_fs_1.default.readFileSync(markerPath, 'utf8').trim();
+                if (src && node_fs_1.default.existsSync(src)) {
+                    // Marker points to commands/gsd; agents/ is a sibling of commands/
+                    const agentsCandidate = node_path_1.default.resolve(node_path_1.default.dirname(src), '..', 'agents');
+                    if (node_fs_1.default.existsSync(agentsCandidate))
+                        return agentsCandidate;
+                }
+            }
+            catch { /* fall through */ }
+        }
+    }
+    // Step 2: walk up from __dirname
+    let dir = __dirname;
+    for (let i = 0; i < 6; i++) {
+        const candidate = node_path_1.default.join(dir, 'agents');
+        if (node_fs_1.default.existsSync(candidate))
+            return candidate;
+        const parent = node_path_1.default.dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    throw new Error(`findAgentsSourceRoot: could not locate agents/ from ${__dirname}`);
+}
+// ---------------------------------------------------------------------------
+// Allowlisted runtimes
+// ---------------------------------------------------------------------------
+const ALLOWED_RUNTIMES = new Set([
+    'claude', 'cursor', 'gemini', 'codex', 'copilot', 'antigravity',
+    'windsurf', 'augment', 'trae', 'qwen', 'hermes', 'codebuddy',
+    'cline', 'opencode', 'kilo',
+]);
+// ---------------------------------------------------------------------------
+// Layout table builders
+// ---------------------------------------------------------------------------
+function commandsKind(destSubpath, prefix, configDir) {
+    return {
+        kind: 'commands',
+        destSubpath,
+        prefix,
+        stage: (resolved) => stageSkillsForProfile(findInstallSourceRoot(configDir), resolved),
+    };
+}
+function agentsKind(destSubpath, prefix, configDir) {
+    return {
+        kind: 'agents',
+        destSubpath,
+        prefix,
+        stage: (resolved) => stageAgentsForProfile(findAgentsSourceRoot(configDir), resolved),
+    };
+}
+/**
+ * Build a skills kind descriptor.
+ *
+ * @param destSubpath
+ * @param prefix
+ * @param converterName  name of converter function in bin/install.js exports
+ * @param runtime        canonical runtime ID (gates Hermes/Qwen branding in converter)
+ * @param configDir      runtime config dir (for .gsd-source marker resolution)
+ */
+function skillsKind(destSubpath, prefix, converterName, runtime, configDir) {
+    return {
+        kind: 'skills',
+        destSubpath,
+        prefix,
+        stage: (resolved) => {
+            const installExports = getInstallExports();
+            const realConverter = installExports[converterName];
+            // Compute cmdNames once per stage call for performance (#3583).
+            // Extra args are ignored by converters that don't need runtime/cmdNames.
+            const cmdNames = installExports.readGsdCommandNames();
+            const wrappedConverter = (content, skillName) => realConverter(content, skillName, runtime, cmdNames);
+            return stageSkillsForRuntimeAsSkills(findInstallSourceRoot(configDir), resolved, wrappedConverter, prefix);
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the artifact layout for a given runtime and config directory.
+ */
+function resolveRuntimeArtifactLayout(runtime, configDir, scope = 'global') {
+    if (typeof configDir !== 'string' || configDir === '') {
+        throw new TypeError('configDir must be a non-empty string');
+    }
+    if (scope !== 'local' && scope !== 'global') {
+        throw new TypeError('scope must be "local" or "global"');
+    }
+    if (!ALLOWED_RUNTIMES.has(runtime)) {
+        throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
+    }
+    let kinds;
+    switch (runtime) {
+        case 'claude':
+            if (scope === 'local') {
+                kinds = [
+                    commandsKind('commands/gsd', 'gsd-', configDir),
+                    agentsKind('agents', 'gsd-', configDir),
+                ];
+            }
+            else {
+                kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'claude', configDir)];
+            }
+            break;
+        case 'cursor':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCursorSkill', 'cursor', configDir)];
+            break;
+        case 'gemini':
+            kinds = [commandsKind('commands/gsd', 'gsd-', configDir)];
+            break;
+        case 'codex':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodexSkill', 'codex', configDir)];
+            break;
+        case 'copilot':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCopilotSkill', 'copilot', configDir)];
+            break;
+        case 'antigravity':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToAntigravitySkill', 'antigravity', configDir)];
+            break;
+        case 'windsurf':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToWindsurfSkill', 'windsurf', configDir)];
+            break;
+        case 'augment':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToAugmentSkill', 'augment', configDir)];
+            break;
+        case 'trae':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToTraeSkill', 'trae', configDir)];
+            break;
+        case 'qwen':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClaudeSkill', 'qwen', configDir)];
+            break;
+        case 'hermes':
+            kinds = [skillsKind('skills/gsd', '', 'convertClaudeCommandToClaudeSkill', 'hermes', configDir)];
+            break;
+        case 'codebuddy':
+            kinds = [skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodebuddySkill', 'codebuddy', configDir)];
+            break;
+        case 'cline':
+            kinds = [];
+            break;
+        case 'opencode':
+            kinds = [commandsKind('command', 'gsd-', configDir)];
+            break;
+        case 'kilo':
+            kinds = [commandsKind('command', 'gsd-', configDir)];
+            break;
+        default:
+            throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
+    }
+    return { runtime, configDir, kinds };
+}
+module.exports = { resolveRuntimeArtifactLayout, findInstallSourceRoot };

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

@@ -0,0 +1,169 @@
+"use strict";
+/**
+ * runtime-homes.cts — canonical runtime → global config/skills directory mapping.
+ *
+ * Single source of truth for resolving the global config base directory and
+ * the correct global skills directory for every GSD-supported runtime.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/runtime-homes.cjs
+ * collapsed to a TypeScript source of truth. Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ *
+ * Runtime-specific notes:
+ *   hermes  — GSD skills nest under skills/gsd/<skillName>/ (not the flat
+ *             skills/<skillName>/ layout used by all other runtimes).
+ *   cline   — Rules-based; commands are embedded in .clinerules. Cline does
+ *             not use a skills/ directory. getGlobalSkillDir() returns null
+ *             for cline so the caller can emit an appropriate warning.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAntigravityGlobalDir = resolveAntigravityGlobalDir;
+exports.getGlobalConfigDir = getGlobalConfigDir;
+exports.getGlobalSkillsBase = getGlobalSkillsBase;
+exports.getGlobalSkillDir = getGlobalSkillDir;
+exports.getGlobalSkillDisplayPath = getGlobalSkillDisplayPath;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+/**
+ * Expand a leading ~ to os.homedir().
+ */
+function expandTilde(p) {
+    if (!p)
+        return p;
+    if (p.startsWith('~/') || p === '~')
+        return node_path_1.default.join(node_os_1.default.homedir(), p.slice(1));
+    return p;
+}
+/**
+ * Resolve Antigravity global config dir across 1.x and 2.x layouts.
+ */
+function resolveAntigravityGlobalDir(opts = {}) {
+    const env = opts.env ?? process.env;
+    const home = opts.home ?? node_os_1.default.homedir();
+    const existsSyncFn = opts.existsSync ?? node_fs_1.default.existsSync;
+    if (env['ANTIGRAVITY_CONFIG_DIR'])
+        return expandTilde(env['ANTIGRAVITY_CONFIG_DIR']);
+    const base = node_path_1.default.join(home, '.gemini');
+    const candidates = [
+        node_path_1.default.join(base, 'antigravity'),
+        node_path_1.default.join(base, 'antigravity-ide'),
+        node_path_1.default.join(base, 'antigravity-cli'),
+    ];
+    for (const candidate of candidates) {
+        if (existsSyncFn(candidate))
+            return candidate;
+    }
+    return node_path_1.default.join(base, 'antigravity');
+}
+/**
+ * Return the global config base directory for the given runtime.
+ * Respects the same env-var overrides as bin/install.js getGlobalDir().
+ */
+function getGlobalConfigDir(runtime) {
+    const home = node_os_1.default.homedir();
+    const env = process.env;
+    switch (runtime) {
+        // ── Claude Code ──────────────────────────────────────────────────────────
+        case 'claude':
+            return env['CLAUDE_CONFIG_DIR'] ? expandTilde(env['CLAUDE_CONFIG_DIR']) : node_path_1.default.join(home, '.claude');
+        // ── Cursor ───────────────────────────────────────────────────────────────
+        case 'cursor':
+            return env['CURSOR_CONFIG_DIR'] ? expandTilde(env['CURSOR_CONFIG_DIR']) : node_path_1.default.join(home, '.cursor');
+        // ── Gemini CLI ───────────────────────────────────────────────────────────
+        case 'gemini':
+            return env['GEMINI_CONFIG_DIR'] ? expandTilde(env['GEMINI_CONFIG_DIR']) : node_path_1.default.join(home, '.gemini');
+        // ── Codex ────────────────────────────────────────────────────────────────
+        case 'codex':
+            return env['CODEX_HOME'] ? expandTilde(env['CODEX_HOME']) : node_path_1.default.join(home, '.codex');
+        // ── Grok Build ───────────────────────────────────────────────────────────
+        case 'grok':
+            return env['GROK_AGENTS_HOME'] ? expandTilde(env['GROK_AGENTS_HOME']) : node_path_1.default.join(home, '.agents');
+        // ── Copilot (VS Code) ────────────────────────────────────────────────────
+        case 'copilot':
+            return env['COPILOT_CONFIG_DIR'] ? expandTilde(env['COPILOT_CONFIG_DIR']) : node_path_1.default.join(home, '.copilot');
+        // ── Antigravity ──────────────────────────────────────────────────────────
+        case 'antigravity':
+            return resolveAntigravityGlobalDir({ env, home });
+        // ── Windsurf ─────────────────────────────────────────────────────────────
+        case 'windsurf':
+            return env['WINDSURF_CONFIG_DIR']
+                ? expandTilde(env['WINDSURF_CONFIG_DIR'])
+                : node_path_1.default.join(home, '.codeium', 'windsurf');
+        // ── Augment ──────────────────────────────────────────────────────────────
+        case 'augment':
+            return env['AUGMENT_CONFIG_DIR'] ? expandTilde(env['AUGMENT_CONFIG_DIR']) : node_path_1.default.join(home, '.augment');
+        // ── Trae ─────────────────────────────────────────────────────────────────
+        case 'trae':
+            return env['TRAE_CONFIG_DIR'] ? expandTilde(env['TRAE_CONFIG_DIR']) : node_path_1.default.join(home, '.trae');
+        // ── Qwen Code ────────────────────────────────────────────────────────────
+        case 'qwen':
+            return env['QWEN_CONFIG_DIR'] ? expandTilde(env['QWEN_CONFIG_DIR']) : node_path_1.default.join(home, '.qwen');
+        // ── Hermes Agent ─────────────────────────────────────────────────────────
+        case 'hermes':
+            return env['HERMES_HOME'] ? expandTilde(env['HERMES_HOME']) : node_path_1.default.join(home, '.hermes');
+        // ── CodeBuddy ────────────────────────────────────────────────────────────
+        case 'codebuddy':
+            return env['CODEBUDDY_CONFIG_DIR'] ? expandTilde(env['CODEBUDDY_CONFIG_DIR']) : node_path_1.default.join(home, '.codebuddy');
+        // ── Cline ────────────────────────────────────────────────────────────────
+        case 'cline':
+            return env['CLINE_CONFIG_DIR'] ? expandTilde(env['CLINE_CONFIG_DIR']) : node_path_1.default.join(home, '.cline');
+        // ── OpenCode (XDG) ───────────────────────────────────────────────────────
+        case 'opencode': {
+            if (env['OPENCODE_CONFIG_DIR'])
+                return expandTilde(env['OPENCODE_CONFIG_DIR']);
+            if (env['XDG_CONFIG_HOME'])
+                return node_path_1.default.join(expandTilde(env['XDG_CONFIG_HOME']), 'opencode');
+            return node_path_1.default.join(home, '.config', 'opencode');
+        }
+        // ── Kilo (XDG) ───────────────────────────────────────────────────────────
+        case 'kilo': {
+            if (env['KILO_CONFIG_DIR'])
+                return expandTilde(env['KILO_CONFIG_DIR']);
+            if (env['XDG_CONFIG_HOME'])
+                return node_path_1.default.join(expandTilde(env['XDG_CONFIG_HOME']), 'kilo');
+            return node_path_1.default.join(home, '.config', 'kilo');
+        }
+        // ── Default (Claude fallback) ─────────────────────────────────────────────
+        default:
+            return env['CLAUDE_CONFIG_DIR'] ? expandTilde(env['CLAUDE_CONFIG_DIR']) : node_path_1.default.join(home, '.claude');
+    }
+}
+/**
+ * Return the global skills base directory for the given runtime.
+ * Most runtimes: <configDir>/skills
+ * Hermes: <configDir>/skills/gsd  (nested category layout — #2841)
+ * Cline:  null (rules-based, no skills directory)
+ */
+function getGlobalSkillsBase(runtime) {
+    if (runtime === 'cline')
+        return null;
+    const configDir = getGlobalConfigDir(runtime);
+    if (runtime === 'hermes')
+        return node_path_1.default.join(configDir, 'skills', 'gsd');
+    return node_path_1.default.join(configDir, 'skills');
+}
+/**
+ * Return the full path to a specific skill's directory for the given runtime.
+ * Returns null for runtimes that don't use a skills directory (cline).
+ */
+function getGlobalSkillDir(runtime, skillName) {
+    const base = getGlobalSkillsBase(runtime);
+    if (base === null)
+        return null;
+    return node_path_1.default.join(base, skillName);
+}
+/**
+ * Return a human-readable display path for a global skill (for log messages).
+ */
+function getGlobalSkillDisplayPath(runtime, skillName) {
+    const dir = getGlobalSkillDir(runtime, skillName);
+    if (!dir)
+        return `(${runtime} does not use a skills directory)`;
+    // Replace homedir prefix with ~ for readability
+    const home = node_os_1.default.homedir();
+    return dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
+}

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

@@ -0,0 +1,96 @@
+"use strict";
+/**
+ * Runtime name policy — alias resolution and canonicalization for GSD runtime
+ * identifiers (ADR-457 build-at-publish: the hand-written
+ * bin/lib/runtime-name-policy.cjs collapsed to a TypeScript source of truth).
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * Group C cross-import candidate: no bin/lib sibling dependencies; only
+ * node:fs and node:path. Once this module is migrated, runtime-slash.cjs
+ * (which imports runtime-name-policy.cjs) becomes the first true cross-import
+ * proof candidate.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
+exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const FALLBACK_ALIASES = {
+    claude: ['claude', 'claude-code', 'claude-cli'],
+    opencode: ['opencode', 'open-code', 'opencode-cli'],
+    kilo: ['kilo', 'kilo-cli'],
+    gemini: ['gemini', 'gemini-cli', 'gemini-code'],
+    codex: ['codex', 'codex-app', 'codex-cli', 'codex_desktop', 'codex-desktop'],
+    copilot: ['copilot', 'copilot-cli', 'github-copilot'],
+    antigravity: ['antigravity', 'antigravity-cli', 'antigravity-agent'],
+    cursor: ['cursor', 'cursor-cli', 'cursor-nightly'],
+    windsurf: ['windsurf', 'windsurf-cli', 'windsurf-next'],
+    augment: ['augment', 'augment-code', 'augment-cli'],
+    trae: ['trae', 'trae-cli'],
+    qwen: ['qwen', 'qwen-code', 'qwen-cli'],
+    hermes: ['hermes', 'hermes-agent', 'hermes-cli'],
+    codebuddy: ['codebuddy', 'codebuddy-cli'],
+    cline: ['cline', 'cline-cli'],
+};
+function normalizeRuntimeToken(value) {
+    return String(value).trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+function loadAliasManifest() {
+    const manifestCandidates = [
+        node_path_1.default.resolve(__dirname, '..', 'shared', 'runtime-aliases.manifest.json'),
+        node_path_1.default.resolve(__dirname, '../../../sdk/shared/runtime-aliases.manifest.json'),
+    ];
+    for (const manifestPath of manifestCandidates) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf8'));
+            if (parsed && typeof parsed === 'object')
+                return parsed;
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return { ...FALLBACK_ALIASES };
+}
+const aliasManifest = loadAliasManifest();
+const aliasToCanonical = new Map();
+for (const [canonical, aliases] of Object.entries(aliasManifest)) {
+    if (typeof canonical !== 'string' || !Array.isArray(aliases))
+        continue;
+    aliasToCanonical.set(normalizeRuntimeToken(canonical), normalizeRuntimeToken(canonical));
+    for (const alias of aliases) {
+        if (typeof alias !== 'string')
+            continue;
+        aliasToCanonical.set(normalizeRuntimeToken(alias), normalizeRuntimeToken(canonical));
+    }
+}
+function canonicalizeRuntimeName(value) {
+    if (typeof value !== 'string')
+        return null;
+    return aliasToCanonical.get(normalizeRuntimeToken(value)) || null;
+}
+/**
+ * Resolve runtime from a precedence list of candidate values.
+ *
+ * - First non-empty string candidate wins.
+ * - Known aliases are canonicalized (codex-cli -> codex).
+ * - Unknown values are normalized and returned (future-runtime tolerance).
+ *
+ * @param candidates - string candidates in precedence order
+ * @returns the resolved runtime name, or null if no valid candidate
+ */
+function resolveRuntimeNameFromCandidates(...candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'string')
+            continue;
+        const normalized = normalizeRuntimeToken(candidate);
+        if (!normalized)
+            continue;
+        return canonicalizeRuntimeName(normalized) || normalized;
+    }
+    return null;
+}

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

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * runtime-slash.cts — single source of truth for emitting GSD slash-command
+ * references in user-facing runtime output (recommended-actions JSON, persisted
+ * ROADMAP.md entries, verify/validate fix hints, error messages, etc.).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/runtime-slash.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ *
+ * Background: #2808 unified all GSD skill installs to register under the hyphen
+ * form (`name: gsd-<cmd>`). The legacy colon form `/gsd:<cmd>` is no longer
+ * routable by Claude Code skill installs, but ~50 runtime emissions in
+ * bin/lib/*.cjs still hardcoded it (#3584). Codex installs need the shell-var
+ * `$gsd-<cmd>` form. This module is the only place the runtime should decide
+ * which shape to emit.
+ *
+ *   - codex:                                   $gsd-<cmd>   (shell-var syntax)
+ *   - claude, cursor, opencode, kilo, etc.:    /gsd-<cmd>
+ *
+ * The colon form is never emitted.
+ *
+ * Cross-import proof candidate (ADR-457): this is the first TS source that
+ * imports a sibling TS-migrated module. The import specifier uses the .cjs
+ * extension per nodenext convention; tsc resolves it to src/runtime-name-policy.cts.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatGsdSlash = formatGsdSlash;
+exports.resolveRuntime = resolveRuntime;
+exports.formatGsdSlashFor = formatGsdSlashFor;
+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");
+function formatGsdSlash(commandName, runtime) {
+    if (typeof commandName !== 'string')
+        return commandName;
+    if (commandName === '')
+        return commandName;
+    // Strip any existing leading prefix so the helper is idempotent and accepts
+    // both legacy `/gsd:<name>` and canonical hyphen-form input (plus the bare
+    // `gsd:<name>` shorthand and codex `$gsd-<name>` shell-var input).
+    const stripped = commandName.replace(/^[/$]?gsd[-:]/i, '');
+    // If the regex matched nothing (no prefix), the input is already a bare name.
+    const bare = stripped === commandName ? commandName : stripped;
+    // Defensive: a degenerate input like `/gsd:`, `gsd-`, or whitespace-only
+    // normalizes to empty. Returning the original colon-form would re-emit the
+    // deprecated shape that this module exists to suppress (#3584). Return an
+    // empty string so callers see "no command" rather than the broken input.
+    if (bare === '' || bare.trim() === '')
+        return '';
+    // Split on the first whitespace so only the command token is rewritten —
+    // anything after the first space is caller-supplied arguments (phase
+    // numbers, --flags, --paths C:\\Users\\Me, etc.) that must round-trip
+    // untouched. Codex lowercases only the command token; preserving the
+    // argument tail prevents path/flag corruption on case-sensitive systems.
+    const wsMatch = bare.match(/^(\S+)(\s[\s\S]*)?$/);
+    const token = wsMatch ? wsMatch[1] : bare;
+    const tail = wsMatch && wsMatch[2] ? wsMatch[2] : '';
+    const runtimeText = (typeof runtime === 'string' && runtime ? runtime : 'claude').toLowerCase();
+    const rt = (0, runtime_name_policy_cjs_1.canonicalizeRuntimeName)(runtimeText) || runtimeText;
+    if (rt === 'codex') {
+        // Codex skills are invoked as $gsd-<cmd> (shell-var syntax). The command
+        // token is lowercased because shell-var identifiers are conventionally
+        // lowercase; matches the convertCodexSlash() projection in bin/install.js.
+        return `$gsd-${token.toLowerCase()}${tail}`;
+    }
+    return `/gsd-${token}${tail}`;
+}
+/**
+ * Resolve the effective runtime for a project directory.
+ *
+ *   process.env.GSD_RUNTIME  >  config.runtime  >  'claude'
+ *
+ * Mirrors the precedence already used by profile-output.cjs and the rest of
+ * the runtime resolution chain. Returns a lowercased string so downstream
+ * comparisons can be case-blind.
+ *
+ * @param projectDir - path to the project directory, or null/undefined
+ * @returns the resolved runtime name
+ */
+function resolveRuntime(projectDir) {
+    const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.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.
+        }
+    }
+    return 'claude';
+}
+/**
+ * Convenience: format using the runtime resolved from a project directory.
+ * Equivalent to `formatGsdSlash(name, resolveRuntime(projectDir))`.
+ */
+function formatGsdSlashFor(projectDir, commandName) {
+    return formatGsdSlash(commandName, resolveRuntime(projectDir));
+}