@opengsd/gsd-core 1.2.0-rc.1

package/get-shit-done/bin/lib/runtime-artifact-layout.cjs

@@ -0,0 +1,301 @@
+'use strict';
+
+/**
+ * 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.
+ */
+
+const path = require('path');
+const fs = require('fs');
+
+const {
+  stageSkillsForProfile,
+  stageAgentsForProfile,
+  stageSkillsForRuntimeAsSkills,
+} = require('./install-profiles.cjs');
+
+// ---------------------------------------------------------------------------
+// Lazy installer exports (avoids GSD_TEST_MODE env mutation at module load)
+// ---------------------------------------------------------------------------
+
+/**
+ * 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;
+}
+
+/**
+ * @typedef {'commands'|'agents'|'skills'} ArtifactKindName
+ * @typedef {Object} ArtifactKind
+ * @property {ArtifactKindName} kind
+ * @property {string} destSubpath
+ * @property {string} prefix
+ * @property {(resolvedProfile: Object) => string} stage
+ * @typedef {Object} Layout
+ * @property {string} runtime
+ * @property {string} configDir
+ * @property {ArtifactKind[]} kinds
+ */
+
+// ---------------------------------------------------------------------------
+// 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.
+ *
+ * @param {string} [runtimeConfigDir] optional runtime config directory
+ * @returns {string}
+ */
+function findInstallSourceRoot(runtimeConfigDir) {
+  // Step 1: marker check
+  if (runtimeConfigDir) {
+    const markerPath = path.join(runtimeConfigDir, '.gsd-source');
+    if (fs.existsSync(markerPath)) {
+      try {
+        const src = fs.readFileSync(markerPath, 'utf8').trim();
+        if (src && fs.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 = path.join(dir, 'commands', 'gsd');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.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.
+ *
+ * @param {string} [runtimeConfigDir] optional runtime config directory
+ * @returns {string}
+ */
+function findAgentsSourceRoot(runtimeConfigDir) {
+  // Step 1: marker check
+  if (runtimeConfigDir) {
+    const markerPath = path.join(runtimeConfigDir, '.gsd-source');
+    if (fs.existsSync(markerPath)) {
+      try {
+        const src = fs.readFileSync(markerPath, 'utf8').trim();
+        if (src && fs.existsSync(src)) {
+          // Marker points to commands/gsd; agents/ is a sibling of commands/
+          const agentsCandidate = path.resolve(path.dirname(src), '..', 'agents');
+          if (fs.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 = path.join(dir, 'agents');
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.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 {string} destSubpath
+ * @param {string} prefix
+ * @param {string} converterName  name of converter function in bin/install.js exports
+ * @param {string} runtime        canonical runtime ID (gates Hermes/Qwen branding in converter)
+ * @param {string} 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.
+ *
+ * @param {string} runtime
+ * @param {string} configDir
+ * @param {'local'|'global'} [scope]
+ * @returns {Layout}
+ */
+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/get-shit-done/bin/lib/runtime-homes.cjs

@@ -0,0 +1,222 @@
+'use strict';
+
+/**
+ * runtime-homes.cjs — 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.
+ *
+ * Mirrors the logic in bin/install.js getGlobalDir() but as a pure,
+ * side-effect-free module safe to require() at any point without triggering
+ * the installer. bin/install.js is the authoritative source — keep in sync.
+ *
+ * Runtime-specific notes:
+ *   hermes  — GSD skills nest under skills/gsd/<skillName>/ (not the flat
+ *             skills/<skillName>/ layout used by all other runtimes). This
+ *             collapses 86 skill entries into one category in Hermes' system
+ *             prompt (#2841).
+ *   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.
+ */
+
+const os = require('os');
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Expand a leading ~ to os.homedir().
+ * @param {string} p
+ * @returns {string}
+ */
+function expandTilde(p) {
+  if (!p) return p;
+  if (p.startsWith('~/') || p === '~') return path.join(os.homedir(), p.slice(1));
+  return p;
+}
+
+/**
+ * Resolve Antigravity global config dir across 1.x and 2.x layouts.
+ *
+ * Order:
+ * 1) ANTIGRAVITY_CONFIG_DIR override
+ * 2) Existing legacy/new runtime directories under ~/.gemini/
+ *    - antigravity (1.x + documented baseline)
+ *    - antigravity-ide (2.x IDE split)
+ *    - antigravity-cli (2.x CLI split)
+ * 3) Legacy default (~/.gemini/antigravity) for backward compatibility
+ *
+ * @param {object} [opts]
+ * @param {Record<string, string | undefined>} [opts.env]
+ * @param {string} [opts.home]
+ * @param {(p: string) => boolean} [opts.existsSync]
+ * @returns {string}
+ */
+function resolveAntigravityGlobalDir(opts = {}) {
+  const env = opts.env || process.env;
+  const home = opts.home || os.homedir();
+  const existsSyncFn = opts.existsSync || fs.existsSync;
+
+  if (env.ANTIGRAVITY_CONFIG_DIR) return expandTilde(env.ANTIGRAVITY_CONFIG_DIR);
+
+  const base = path.join(home, '.gemini');
+  const candidates = [
+    path.join(base, 'antigravity'),
+    path.join(base, 'antigravity-ide'),
+    path.join(base, 'antigravity-cli'),
+  ];
+  for (const candidate of candidates) {
+    if (existsSyncFn(candidate)) return candidate;
+  }
+
+  return path.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 {string} runtime
+ * @returns {string} Absolute path to the runtime's global config directory
+ */
+function getGlobalConfigDir(runtime) {
+  const home = os.homedir();
+  const env = process.env;
+
+  switch (runtime) {
+    // ── Claude Code ──────────────────────────────────────────────────────────
+    case 'claude':
+      return env.CLAUDE_CONFIG_DIR ? expandTilde(env.CLAUDE_CONFIG_DIR) : path.join(home, '.claude');
+
+    // ── Cursor ───────────────────────────────────────────────────────────────
+    case 'cursor':
+      return env.CURSOR_CONFIG_DIR ? expandTilde(env.CURSOR_CONFIG_DIR) : path.join(home, '.cursor');
+
+    // ── Gemini CLI ───────────────────────────────────────────────────────────
+    case 'gemini':
+      return env.GEMINI_CONFIG_DIR ? expandTilde(env.GEMINI_CONFIG_DIR) : path.join(home, '.gemini');
+
+    // ── Codex ────────────────────────────────────────────────────────────────
+    case 'codex':
+      return env.CODEX_HOME ? expandTilde(env.CODEX_HOME) : path.join(home, '.codex');
+
+    // ── Grok Build ───────────────────────────────────────────────────────────
+    // Uses the unified ~/.agents layout (skills + agents + engine) shared with
+    // Codex-style harnesses. This is the pragmatic primary target for users
+    // running GSD inside Grok Build.
+    case 'grok':
+      return env.GROK_AGENTS_HOME ? expandTilde(env.GROK_AGENTS_HOME) : path.join(home, '.agents');
+
+    // ── Copilot (VS Code) ────────────────────────────────────────────────────
+    case 'copilot':
+      return env.COPILOT_CONFIG_DIR ? expandTilde(env.COPILOT_CONFIG_DIR) : path.join(home, '.copilot');
+
+    // ── Antigravity ──────────────────────────────────────────────────────────
+    case 'antigravity':
+      return resolveAntigravityGlobalDir({ env, home });
+
+    // ── Windsurf ─────────────────────────────────────────────────────────────
+    case 'windsurf':
+      return env.WINDSURF_CONFIG_DIR
+        ? expandTilde(env.WINDSURF_CONFIG_DIR)
+        : path.join(home, '.codeium', 'windsurf');
+
+    // ── Augment ──────────────────────────────────────────────────────────────
+    case 'augment':
+      return env.AUGMENT_CONFIG_DIR ? expandTilde(env.AUGMENT_CONFIG_DIR) : path.join(home, '.augment');
+
+    // ── Trae ─────────────────────────────────────────────────────────────────
+    case 'trae':
+      return env.TRAE_CONFIG_DIR ? expandTilde(env.TRAE_CONFIG_DIR) : path.join(home, '.trae');
+
+    // ── Qwen Code ────────────────────────────────────────────────────────────
+    case 'qwen':
+      return env.QWEN_CONFIG_DIR ? expandTilde(env.QWEN_CONFIG_DIR) : path.join(home, '.qwen');
+
+    // ── Hermes Agent ─────────────────────────────────────────────────────────
+    // Note: skills use a nested layout (skills/gsd/<skill>/) — see getGlobalSkillDir().
+    case 'hermes':
+      return env.HERMES_HOME ? expandTilde(env.HERMES_HOME) : path.join(home, '.hermes');
+
+    // ── CodeBuddy ────────────────────────────────────────────────────────────
+    case 'codebuddy':
+      return env.CODEBUDDY_CONFIG_DIR ? expandTilde(env.CODEBUDDY_CONFIG_DIR) : path.join(home, '.codebuddy');
+
+    // ── Cline ────────────────────────────────────────────────────────────────
+    // Note: Cline is rules-based (.clinerules) — no skills/ directory.
+    // getGlobalSkillDir() returns null for cline.
+    case 'cline':
+      return env.CLINE_CONFIG_DIR ? expandTilde(env.CLINE_CONFIG_DIR) : path.join(home, '.cline');
+
+    // ── OpenCode (XDG) ───────────────────────────────────────────────────────
+    case 'opencode': {
+      if (env.OPENCODE_CONFIG_DIR) return expandTilde(env.OPENCODE_CONFIG_DIR);
+      if (env.XDG_CONFIG_HOME) return path.join(expandTilde(env.XDG_CONFIG_HOME), 'opencode');
+      return path.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 path.join(expandTilde(env.XDG_CONFIG_HOME), 'kilo');
+      return path.join(home, '.config', 'kilo');
+    }
+
+    // ── Default (Claude fallback) ─────────────────────────────────────────────
+    default:
+      return env.CLAUDE_CONFIG_DIR ? expandTilde(env.CLAUDE_CONFIG_DIR) : path.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)
+ *
+ * @param {string} runtime
+ * @returns {string|null}
+ */
+function getGlobalSkillsBase(runtime) {
+  if (runtime === 'cline') return null;
+  const configDir = getGlobalConfigDir(runtime);
+  if (runtime === 'hermes') return path.join(configDir, 'skills', 'gsd');
+  return path.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).
+ *
+ * @param {string} runtime
+ * @param {string} skillName - e.g. 'gsd-executor'
+ * @returns {string|null}
+ */
+function getGlobalSkillDir(runtime, skillName) {
+  const base = getGlobalSkillsBase(runtime);
+  if (base === null) return null;
+  return path.join(base, skillName);
+}
+
+/**
+ * Return a human-readable display path for a global skill (for log messages).
+ *
+ * @param {string} runtime
+ * @param {string} skillName
+ * @returns {string}
+ */
+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 = os.homedir();
+  return dir.startsWith(home) ? '~' + dir.slice(home.length) : dir;
+}
+
+module.exports = {
+  getGlobalConfigDir,
+  getGlobalSkillsBase,
+  getGlobalSkillDir,
+  getGlobalSkillDisplayPath,
+  resolveAntigravityGlobalDir,
+};

package/get-shit-done/bin/lib/runtime-name-policy.cjs

@@ -0,0 +1,83 @@
+'use strict';
+
+const fs = require('node:fs');
+const path = 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 = [
+    path.resolve(__dirname, '..', 'shared', 'runtime-aliases.manifest.json'),
+    path.resolve(__dirname, '../../../sdk/shared/runtime-aliases.manifest.json'),
+  ];
+  for (const manifestPath of manifestCandidates) {
+    try {
+      const parsed = JSON.parse(fs.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 {...string} candidates
+ * @returns {string|null}
+ */
+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;
+}
+
+module.exports = {
+  canonicalizeRuntimeName,
+  resolveRuntimeNameFromCandidates,
+};