@hegemonart/get-design-done 1.28.6 → 1.28.7

package/scripts/lib/install/runtime-homes.cjs

@@ -0,0 +1,225 @@
+'use strict';
+
+/**
+ * scripts/lib/install/runtime-homes.cjs — Phase 28.7 (Plan 28.7-01).
+ *
+ * Pure config-dir + skills-base resolver per runtime. Returns absolute paths
+ * to each runtime's global config directory and global skills directory,
+ * respecting env-var overrides + XDG conventions.
+ *
+ * Architecture ported from gsd-build/get-shit-done (MIT) — per Phase 28.7 D-02
+ * (port architecture, not source). See NOTICE for upstream attribution.
+ *
+ * Scope: the 14 GDD runtimes locked by Phase 24 D-02. Phase 28.7 D-03 + D-10
+ * keep `hermes` OUT of scope; the upstream `hermes` and `grok` branches are
+ * deliberately NOT ported.
+ *
+ * Pure / side-effect-free: no `fs.*` calls at any time, no `process.env`
+ * writes, no top-level work beyond `require('os')` + `require('path')`.
+ * Safe to require() at module-load time.
+ *
+ * Runtime-specific notes:
+ *   opencode + kilo — XDG: honor `XDG_CONFIG_HOME` when the runtime's own
+ *                     env var is unset. Default: `~/.config/<runtime>`.
+ *   antigravity   — Nested under Gemini's home (`~/.gemini/antigravity`).
+ *   windsurf      — Nested under Codeium's home (`~/.codeium/windsurf`).
+ *   cline         — Rules-based runtime (D-09). `getGlobalSkillsBase('cline')`
+ *                   returns `null` so callers can route to the `.clinerules`
+ *                   embedding path instead of a skills/ tree.
+ */
+
+const os = require('os');
+const path = require('path');
+
+/**
+ * Expand a leading `~` to `os.homedir()`. Returns the input unchanged if no
+ * leading tilde is present (including `null`/`undefined`/empty).
+ *
+ * @param {string} p
+ * @returns {string}
+ */
+function expandTilde(p) {
+  if (!p) return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) {
+    return path.join(os.homedir(), p.slice(2));
+  }
+  return p;
+}
+
+/**
+ * Return the global config base directory for the given runtime.
+ *
+ * Precedence per branch:
+ *   1. Runtime's dedicated env var (e.g. `CLAUDE_CONFIG_DIR`, `CODEX_HOME`),
+ *      tilde-expanded if present.
+ *   2. XDG path for opencode + kilo (when `XDG_CONFIG_HOME` is set).
+ *   3. Home-relative default (`~/.claude`, `~/.codex`, etc.).
+ *
+ * Throws `RangeError` on unknown runtime IDs (loud-fail — typos in caller
+ * code should fail at the resolver, not silently fall back to Claude paths).
+ *
+ * @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');
+
+    // ── 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');
+    }
+
+    // ── Gemini CLI ───────────────────────────────────────────────────────────
+    case 'gemini':
+      return env.GEMINI_CONFIG_DIR
+        ? expandTilde(env.GEMINI_CONFIG_DIR)
+        : path.join(home, '.gemini');
+
+    // ── Kilo Code (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');
+    }
+
+    // ── Codex ────────────────────────────────────────────────────────────────
+    case 'codex':
+      return env.CODEX_HOME
+        ? expandTilde(env.CODEX_HOME)
+        : path.join(home, '.codex');
+
+    // ── Copilot (VS Code / CLI) ──────────────────────────────────────────────
+    case 'copilot':
+      return env.COPILOT_CONFIG_DIR
+        ? expandTilde(env.COPILOT_CONFIG_DIR)
+        : path.join(home, '.copilot');
+
+    // ── Cursor ───────────────────────────────────────────────────────────────
+    case 'cursor':
+      return env.CURSOR_CONFIG_DIR
+        ? expandTilde(env.CURSOR_CONFIG_DIR)
+        : path.join(home, '.cursor');
+
+    // ── Windsurf (nested under Codeium home) ─────────────────────────────────
+    case 'windsurf':
+      return env.WINDSURF_CONFIG_DIR
+        ? expandTilde(env.WINDSURF_CONFIG_DIR)
+        : path.join(home, '.codeium', 'windsurf');
+
+    // ── Antigravity (nested under Gemini home) ───────────────────────────────
+    case 'antigravity':
+      return env.ANTIGRAVITY_CONFIG_DIR
+        ? expandTilde(env.ANTIGRAVITY_CONFIG_DIR)
+        : path.join(home, '.gemini', 'antigravity');
+
+    // ── 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');
+
+    // ── CodeBuddy ────────────────────────────────────────────────────────────
+    case 'codebuddy':
+      return env.CODEBUDDY_CONFIG_DIR
+        ? expandTilde(env.CODEBUDDY_CONFIG_DIR)
+        : path.join(home, '.codebuddy');
+
+    // ── Cline (rules-based — see getGlobalSkillsBase) ────────────────────────
+    case 'cline':
+      return env.CLINE_CONFIG_DIR
+        ? expandTilde(env.CLINE_CONFIG_DIR)
+        : path.join(home, '.cline');
+
+    // ── Unknown ──────────────────────────────────────────────────────────────
+    default:
+      throw new RangeError(
+        `Unknown runtime "${runtime}". Known: claude, opencode, gemini, kilo, ` +
+          'codex, copilot, cursor, windsurf, antigravity, augment, trae, qwen, ' +
+          'codebuddy, cline.'
+      );
+  }
+}
+
+/**
+ * Return the global skills base directory for the given runtime.
+ *
+ * - `cline` → `null` (Phase 28.7 D-09: rules-based, no skills dir; caller
+ *             routes to the `.clinerules` embedding path).
+ * - All other 13 runtimes → `<configDir>/skills`.
+ *
+ * Note: gsd-build's upstream nests Hermes skills under `skills/gsd/<name>/`
+ * (their #2841). Hermes is NOT in our 14-runtime set (D-03 + D-10), so the
+ * nested layout is NOT ported.
+ *
+ * @param {string} runtime
+ * @returns {string|null} Absolute path to skills base, or `null` for cline.
+ */
+function getGlobalSkillsBase(runtime) {
+  if (runtime === 'cline') return null;
+  const configDir = getGlobalConfigDir(runtime);
+  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. `'gdd-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).
+ * Replaces the home-directory prefix with `~` for readability.
+ *
+ * @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)`;
+  const home = os.homedir();
+  if (dir === home) return '~';
+  if (dir.startsWith(home + path.sep)) {
+    return '~' + dir.slice(home.length);
+  }
+  return dir;
+}
+
+module.exports = {
+  expandTilde,
+  getGlobalConfigDir,
+  getGlobalSkillsBase,
+  getGlobalSkillDir,
+  getGlobalSkillDisplayPath,
+};

package/scripts/lib/install/runtime-slash.cjs

@@ -0,0 +1,172 @@
+'use strict';
+
+/**
+ * scripts/lib/install/runtime-slash.cjs — Phase 28.7 (Plan 28.7-03).
+ *
+ * Per-runtime slash-command surface emitter. Maps a bare command name
+ * (e.g. `'explore'`) to the runtime's expected slash-command shape:
+ *   codex → `$gdd-explore`     (shell-variable form)
+ *   all other 13 runtimes → `/gdd-explore`
+ *
+ * The legacy colon form `/gdd:explore` is NEVER emitted — Phase 28.7
+ * standardizes on the dash form across the GDD brand. Inputs in legacy
+ * colon shape are accepted (and normalized) for backward compatibility.
+ *
+ * Architecture ported from gsd-build/get-shit-done (MIT) — per Phase
+ * 28.7 D-02 (port architecture, not source). See NOTICE for upstream
+ * attribution. Per Phase 28.7 D-11 this is the v1 surface; future
+ * per-runtime variations beyond codex shell-var may extend the switch.
+ *
+ * Idempotency: any prior shape (`/gdd-x`, `gdd-x`, `/gdd:x`, `gdd:x`,
+ * `$gdd-x`, `$gdd:x`) is stripped and re-emitted in canonical form for
+ * the target runtime. Argument tails (whitespace + remainder) round-trip
+ * untouched — this preserves Windows paths verbatim (Phase 28.6 lesson).
+ *
+ * Pure / side-effect-free at module load: only `require('fs')` and
+ * `require('path')` are taken at top level. `fs.readFileSync` is the
+ * sole `fs.*` caller, invoked exclusively from `resolveRuntime` when a
+ * project directory is provided — and wrapped in try/catch so malformed
+ * `.planning/config.json` cannot throw.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// formatGddSlash — pure rewrite of a single command token
+// ---------------------------------------------------------------------------
+
+/**
+ * Strip any known GDD prefix from the head of `s`.
+ *
+ * Matches (case-insensitive):
+ *   `/gdd-`, `/gdd:`, `gdd-`, `gdd:`, `$gdd-`, `$gdd:`
+ *
+ * Returns the substring after the matched prefix, or the original string
+ * unchanged if no prefix matches.
+ *
+ * @param {string} s
+ * @returns {string}
+ */
+function stripGddPrefix(s) {
+  const m = s.match(/^[/$]?gdd[-:]/i);
+  if (m) return s.slice(m[0].length);
+  return s;
+}
+
+/**
+ * Rewrite a command name to the slash-command shape for `runtime`.
+ *
+ * Behavior:
+ *   - Non-string `commandName` returned unchanged (type-guard).
+ *   - Empty string returned as `''`.
+ *   - Any of `/gdd-`, `/gdd:`, `gdd-`, `gdd:`, `$gdd-`, `$gdd:` is
+ *     stripped first (case-insensitive). Bare names pass through.
+ *   - If the stripped result is empty / whitespace-only, return `''`
+ *     (never re-emit `/gdd-` or `$gdd-` with no token — degenerate input).
+ *   - Split on the first whitespace: the leading token is rewritten,
+ *     everything after the first space (the argument tail) round-trips
+ *     untouched. This preserves Windows paths in argument position.
+ *   - codex → `$gdd-<token-lowercased><tail>`
+ *   - all other runtimes → `/gdd-<token><tail>`
+ *   - Unknown / falsy runtime → defaults to `'claude'` shape (`/gdd-`).
+ *
+ * @param {string} commandName  e.g. `'explore'`, `'/gdd-debug'`, `'do x y'`.
+ * @param {string} [runtime]    runtime ID; defaults to `'claude'`.
+ * @returns {string}
+ */
+function formatGddSlash(commandName, runtime) {
+  // Type-guard: only operate on strings; pass everything else through.
+  if (typeof commandName !== 'string') return commandName;
+  if (commandName === '') return '';
+
+  // 1. Strip any prior GDD prefix (idempotent normalization).
+  const bare = stripGddPrefix(commandName);
+
+  // 2. Defensive: empty / whitespace-only token → empty (never `/gdd-`).
+  if (bare === '' || /^\s+$/.test(bare)) return '';
+
+  // 3. Split into leading token + argument tail. The tail (including its
+  //    leading whitespace) round-trips untouched for Windows-path safety.
+  const m = bare.match(/^(\S+)(\s[\s\S]*)?$/);
+  /* istanbul ignore next — `bare` is non-empty + non-whitespace-only, so
+     this regex always matches; defensive fallback only. */
+  if (!m) return '';
+  const token = m[1];
+  const tail = m[2] || '';
+
+  // 4. Runtime-specific emission.
+  const rt = String(runtime || 'claude').toLowerCase();
+  if (rt === 'codex') {
+    return '$gdd-' + token.toLowerCase() + tail;
+  }
+  return '/gdd-' + token + tail;
+}
+
+// ---------------------------------------------------------------------------
+// resolveRuntime — read-only runtime ID resolution
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the active runtime ID for the given project directory.
+ *
+ * Precedence:
+ *   1. `process.env.GDD_RUNTIME` (lowercased) if truthy.
+ *   2. `<projectDir>/.planning/config.json#runtime` (lowercased) if the
+ *      file exists, parses as JSON, and contains a non-empty `runtime`
+ *      string. Malformed JSON, missing file, or missing key all fall
+ *      through silently — this function MUST NOT throw on bad config.
+ *   3. Default `'claude'`.
+ *
+ * Side-effect-free: only `fs.readFileSync` (wrapped in try/catch), no
+ * env mutation, no writes.
+ *
+ * @param {string} [projectDir]  absolute path to project root.
+ * @returns {string}  runtime ID, always lowercase.
+ */
+function resolveRuntime(projectDir) {
+  // 1. Env-var override
+  if (process.env.GDD_RUNTIME) {
+    return String(process.env.GDD_RUNTIME).toLowerCase();
+  }
+
+  // 2. .planning/config.json#runtime
+  if (projectDir) {
+    try {
+      const cfgPath = path.join(projectDir, '.planning', 'config.json');
+      const raw = fs.readFileSync(cfgPath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed.runtime === 'string' && parsed.runtime) {
+        return String(parsed.runtime).toLowerCase();
+      }
+    } catch {
+      /* fall through — malformed JSON / missing file / missing key */
+    }
+  }
+
+  // 3. Default
+  return 'claude';
+}
+
+// ---------------------------------------------------------------------------
+// formatGddSlashFor — convenience that combines the two
+// ---------------------------------------------------------------------------
+
+/**
+ * Resolve the runtime for `projectDir` and rewrite `commandName` accordingly.
+ * Convenience wrapper for callers that already have a project directory in
+ * hand and don't want to wire `resolveRuntime` themselves.
+ *
+ * @param {string} projectDir
+ * @param {string} commandName
+ * @returns {string}
+ */
+function formatGddSlashFor(projectDir, commandName) {
+  return formatGddSlash(commandName, resolveRuntime(projectDir));
+}
+
+module.exports = {
+  formatGddSlash,
+  resolveRuntime,
+  formatGddSlashFor,
+};

package/scripts/lib/install/runtimes.cjs

@@ -7,15 +7,21 @@
 // (Phase 24 D-02). Two `kind`s exist:
 //
 //   - `claude-marketplace` — register a marketplace entry + flip
-//     `enabledPlugins[<name>@<marketplace>]` in settings.json. Today only
-//     Claude Code uses this.
+//     `enabledPlugins[<plugin>@<marketplace>]` in settings.json. Claude
+//     Code only.
 //
-//   - `agents-md` — drop a runtime-specific instructions file (AGENTS.md /
-//     GEMINI.md) into the runtime's config directory. Most modern AI coding
-//     CLIs follow this convention.
+//   - `multi-artifact` — per Phase 28.7: install one or more artifact kinds
+//     (skills, commands, agents) using runtime-artifact-layout.cjs +
+//     per-runtime converters at scripts/lib/install/converters/<runtime>.cjs.
+//     Replaces the broken Phase 24 `agents-md` placeholder which dropped a
+//     single AGENTS.md file per runtime (Phase 28.7 D-02 + D-08). The actual
+//     install logic now lives in installer.cjs → runtime-artifact-layout.cjs;
+//     `files:` is intentionally absent on these entries because destination
+//     paths are computed by the artifact-layout resolver.
 //
 // Adding a new runtime: append to RUNTIMES below, append the same id to the
-// alphabetised baseline at test-fixture/baselines/phase-24/runtimes.txt.
+// alphabetised baseline at test-fixture/baselines/phase-24/runtimes.txt,
+// and add a matching branch in runtime-artifact-layout.cjs (Phase 28.7).
 
 const REPO = 'hegemonart/get-design-done';
 const MARKETPLACE_NAME = 'get-design-done';
@@ -40,16 +46,14 @@ const RUNTIMES = Object.freeze([
     displayName: 'OpenCode',
     configDirEnv: 'OPENCODE_CONFIG_DIR',
     configDirFallback: '.config/opencode',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'gemini',
     displayName: 'Gemini CLI',
     configDirEnv: 'GEMINI_CONFIG_DIR',
     configDirFallback: '.gemini',
-    kind: 'agents-md',
-    files: ['GEMINI.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'gemini.cmd' : 'gemini',
   },
@@ -58,16 +62,14 @@ const RUNTIMES = Object.freeze([
     displayName: 'Kilo Code',
     configDirEnv: 'KILO_CONFIG_DIR',
     configDirFallback: '.kilo',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'codex',
     displayName: 'OpenAI Codex CLI',
     configDirEnv: 'CODEX_HOME',
     configDirFallback: '.codex',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ASP protocol.
     peerBinary: process.platform === 'win32' ? 'codex.cmd' : 'codex',
   },
@@ -76,8 +78,7 @@ const RUNTIMES = Object.freeze([
     displayName: 'GitHub Copilot CLI',
     configDirEnv: 'COPILOT_CONFIG_DIR',
     configDirFallback: '.copilot',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'copilot.cmd' : 'copilot',
   },
@@ -86,8 +87,7 @@ const RUNTIMES = Object.freeze([
     displayName: 'Cursor',
     configDirEnv: 'CURSOR_CONFIG_DIR',
     configDirFallback: '.cursor',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'cursor-agent.cmd' : 'cursor-agent',
   },
@@ -96,40 +96,35 @@ const RUNTIMES = Object.freeze([
     displayName: 'Windsurf',
     configDirEnv: 'WINDSURF_CONFIG_DIR',
     configDirFallback: '.windsurf',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'antigravity',
     displayName: 'Antigravity',
     configDirEnv: 'ANTIGRAVITY_CONFIG_DIR',
     configDirFallback: '.antigravity',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'augment',
     displayName: 'Augment',
     configDirEnv: 'AUGMENT_CONFIG_DIR',
     configDirFallback: '.augment',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'trae',
     displayName: 'Trae',
     configDirEnv: 'TRAE_CONFIG_DIR',
     configDirFallback: '.trae',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'qwen',
     displayName: 'Qwen Code',
     configDirEnv: 'QWEN_CONFIG_DIR',
     configDirFallback: '.qwen',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
     // Phase 27 (Plan 27-11): peer-CLI delegation binary, ACP protocol.
     peerBinary: process.platform === 'win32' ? 'qwen.cmd' : 'qwen',
   },
@@ -138,16 +133,14 @@ const RUNTIMES = Object.freeze([
     displayName: 'CodeBuddy',
     configDirEnv: 'CODEBUDDY_CONFIG_DIR',
     configDirFallback: '.codebuddy',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
   {
     id: 'cline',
     displayName: 'Cline',
     configDirEnv: 'CLINE_CONFIG_DIR',
     configDirFallback: '.cline',
-    kind: 'agents-md',
-    files: ['AGENTS.md'],
+    kind: 'multi-artifact',
   },
 ]);