@therocketcode/gsd-core 1.4.0

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

@@ -0,0 +1,312 @@
+'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, stageCommandsForRuntimeFlat, } = 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);
+        },
+    };
+}
+/**
+ * Build a converted-commands kind descriptor for runtimes that use a flat
+ * commands directory with per-file conversion (e.g. Cursor 1.6 slash commands).
+ *
+ * Unlike `commandsKind` (which passes raw source files through), this kind
+ * applies `converterName` from bin/install.js exports to each file during
+ * staging, writing flat `${prefix}${stem}.md` files to the staged directory.
+ *
+ * The staged files are then written by `_copyStaged` (commands branch) which
+ * handles prefix logic via the existing layout machinery.
+ *
+ * @param destSubpath   destination subpath within configDir (e.g. 'commands')
+ * @param prefix        filename prefix, e.g. 'gsd-'
+ * @param converterName name of converter function in bin/install.js exports
+ * @param configDir     runtime config dir (for .gsd-source marker resolution)
+ */
+function convertedCommandsKind(destSubpath, prefix, converterName, configDir) {
+    return {
+        kind: 'commands',
+        destSubpath,
+        prefix,
+        stage: (resolved) => {
+            const installExports = getInstallExports();
+            const converter = installExports[converterName];
+            return stageCommandsForRuntimeFlat(findInstallSourceRoot(configDir), resolved, converter, 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':
+            // Cursor 1.6+ supports two artifact surfaces:
+            //   1. skills/gsd-<name>/SKILL.md  — rich skills with frontmatter + adapter header
+            //   2. commands/gsd-<name>.md      — plain markdown slash commands (no frontmatter)
+            //      accessed via '/' in the Agent input (#785)
+            kinds = [
+                skillsKind('skills', 'gsd-', 'convertClaudeCommandToCursorSkill', 'cursor', configDir),
+                convertedCommandsKind('commands', 'gsd-', 'convertClaudeCommandToCursorCommand', 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 = [
+                commandsKind('commands', 'gsd-', configDir),
+                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':
+            // CodeBuddy (Tencent) reads two user-level surfaces (codebuddy.ai/docs/cli):
+            //   1. commands/gsd-<name>.md      — slash commands shown in the '/' menu (#789)
+            //   2. skills/gsd-<name>/SKILL.md  — model-invocable skills, emitted with
+            //      user-invocable:false so they stay OUT of '/' (the commands surface is
+            //      the sole '/' entry point) — avoids a duplicated /gsd-* per workflow.
+            // Subagents (~/.codebuddy/agents/) are already emitted by the generic agents
+            // block in bin/install.js; MCP is excluded (gsd ships no MCP server).
+            kinds = [
+                convertedCommandsKind('commands', 'gsd-', 'convertClaudeCommandToCodebuddyCommand', configDir),
+                skillsKind('skills', 'gsd-', 'convertClaudeCommandToCodebuddySkill', 'codebuddy', configDir),
+            ];
+            break;
+        case 'cline':
+            kinds = scope === 'global' ? [skillsKind('skills', 'gsd-', 'convertClaudeCommandToClineSkill', 'cline', configDir)] : [];
+            break;
+        case 'opencode':
+            // OpenCode reads flat slash commands from command/ and on-demand skills
+            // from skills/<name>/SKILL.md (https://opencode.ai/docs/skills). Emit both.
+            kinds = [
+                commandsKind('command', 'gsd-', configDir),
+                skillsKind('skills', 'gsd-', 'convertClaudeCommandToOpencodeSkill', 'opencode', configDir),
+            ];
+            break;
+        case 'kilo':
+            // Kilo derives from OpenCode and shares the skills/<name>/SKILL.md layout
+            // (https://kilo.ai/docs/customize/skills). Emit flat commands + skills.
+            kinds = [
+                commandsKind('command', 'gsd-', configDir),
+                skillsKind('skills', 'gsd-', 'convertClaudeCommandToKiloSkill', 'kilo', configDir),
+            ];
+            break;
+        default:
+            throw new TypeError(`Unknown runtime: '${runtime}' — add to runtime-artifact-layout.cjs table`);
+    }
+    return { runtime, configDir, scope, kinds };
+}
+module.exports = { resolveRuntimeArtifactLayout, findInstallSourceRoot, getInstallExports };

package/gsd-core/bin/lib/runtime-config-adapter-registry.cjs

@@ -0,0 +1,56 @@
+'use strict';
+// ---------------------------------------------------------------------------
+// Registry
+// ---------------------------------------------------------------------------
+const REGISTRY = Object.freeze({
+    claude: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    gemini: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    antigravity: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    augment: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    qwen: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    hermes: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    codebuddy: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: null }),
+    opencode: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: true, finishPermissionWriter: 'opencode' }),
+    kilo: Object.freeze({ installSurface: 'settings-json', writesSharedSettings: false, finishPermissionWriter: 'kilo' }),
+    codex: Object.freeze({ installSurface: 'codex-toml', writesSharedSettings: false, finishPermissionWriter: null }),
+    copilot: Object.freeze({ installSurface: 'copilot-instructions', writesSharedSettings: false, finishPermissionWriter: null }),
+    cline: Object.freeze({ installSurface: 'cline-rules', writesSharedSettings: false, finishPermissionWriter: null }),
+    cursor: Object.freeze({ installSurface: 'cursor-hooks-json', writesSharedSettings: false, finishPermissionWriter: null }),
+    windsurf: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
+    trae: Object.freeze({ installSurface: 'profile-marker-only', writesSharedSettings: false, finishPermissionWriter: null }),
+});
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+/** The complete set of 15 supported runtimes for config-adapter dispatch. */
+const ALLOWED_CONFIG_RUNTIMES = new Set(Object.keys(REGISTRY));
+/** All valid installSurface values. */
+const INSTALL_SURFACES = Object.freeze([
+    'settings-json',
+    'codex-toml',
+    'copilot-instructions',
+    'cline-rules',
+    'cursor-hooks-json',
+    'profile-marker-only',
+]);
+/**
+ * Resolve the config adapter intent for a given runtime.
+ *
+ * Returns a fresh object each call so callers cannot poison the registry by
+ * mutating the returned value.
+ *
+ * @throws {TypeError} if runtime is not a known supported runtime.
+ */
+function resolveRuntimeConfigIntent(runtime) {
+    if (!Object.hasOwn(REGISTRY, runtime)) {
+        throw new TypeError(`Unknown runtime for config adapter: ${runtime}`);
+    }
+    const entry = REGISTRY[runtime];
+    return {
+        runtime,
+        installSurface: entry.installSurface,
+        writesSharedSettings: entry.writesSharedSettings,
+        finishPermissionWriter: entry.finishPermissionWriter,
+    };
+}
+module.exports = { resolveRuntimeConfigIntent, ALLOWED_CONFIG_RUNTIMES, INSTALL_SURFACES };

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

@@ -0,0 +1,190 @@
+"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   — Skills-capable since v3.48.0 (#782). SKILL.md files live at
+ *             ~/.cline/skills/<skillName>/SKILL.md (same flat layout as cursor/codex).
+ *             .clinerules is also emitted (rules-based compatibility layer).
+ */
+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().
+ *
+ * @param runtime   - The runtime identifier (e.g. 'claude', 'opencode').
+ * @param explicitDir - If provided and non-empty, returned immediately after
+ *   tilde-expansion, overriding all env-var and default logic. This matches
+ *   the behaviour of bin/install.js getGlobalDir(runtime, explicitDir).
+ */
+function getGlobalConfigDir(runtime, explicitDir) {
+    if (explicitDir)
+        return expandTilde(explicitDir);
+    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':
+            if (env['COPILOT_CONFIG_DIR'])
+                return expandTilde(env['COPILOT_CONFIG_DIR']);
+            if (env['COPILOT_HOME'])
+                return expandTilde(env['COPILOT_HOME']);
+            return 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['OPENCODE_CONFIG'])
+                return node_path_1.default.dirname(expandTilde(env['OPENCODE_CONFIG']));
+            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['KILO_CONFIG'])
+                return node_path_1.default.dirname(expandTilde(env['KILO_CONFIG']));
+            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 ≥ v3.48.0: <configDir>/skills  (SKILL.md-based global skills — #782)
+ */
+function getGlobalSkillsBase(runtime) {
+    if (runtime === 'hermes') {
+        const configDir = getGlobalConfigDir(runtime);
+        return node_path_1.default.join(configDir, 'skills', 'gsd');
+    }
+    // Kilo Code discovers global skills from ~/.kilo/skills/ (HOME-relative),
+    // independent of the XDG-based config dir (~/.config/kilo) used for commands.
+    // See: https://kilo.ai/docs/customize/skills
+    // "Global skills are located in the `.kilo` directory within your Home
+    //  directory: ~/.kilo/skills/"
+    if (runtime === 'kilo')
+        return node_path_1.default.join(node_os_1.default.homedir(), '.kilo', 'skills');
+    const configDir = getGlobalConfigDir(runtime);
+    return node_path_1.default.join(configDir, 'skills');
+}
+/**
+ * Return the full path to a specific skill's directory for the given runtime.
+ */
+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;
+}