refactor(3664): migrate bin/install.js install/uninstall to Runtime Artifact Layout Module (#3674)

Phase 2 of #3660 / ADR-3660. Routes both lifecycle verbs through the
Runtime Artifact Layout Module landed in Phase 1 (#3663):

- Add installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile)
  and uninstallRuntimeArtifacts(runtime, configDir, scope) as the public
  orchestrators. Both pre-prune stale gsd-* entries before staged copy;
  installRuntimeArtifacts brackets the prune+copy with preserveUserArtifacts /
  restoreUserArtifacts so user-owned content (e.g. gsd-dev-preferences) survives
  wipe-and-replace for claude/qwen/hermes runtimes.
- Add applyRuntimeContentRewritesInPlace as the per-runtime path/branding
  post-stage step (preserves byte-output equivalence with the legacy
  copyCommandsAs* pipeline, including Qwen/Hermes branding rewrites).
- Add _copyStaged, _removeGsdEntries kind-aware filesystem helpers.
- Add _runLegacyInstallMigrations, _runLegacyUninstallCleanup as thin
  dispatchers over existing ADR-0008 legacy migrations (Hermes flat->nested
  per #2841, dev-preferences-as-skill per #2973). For Hermes, also clean up
  the intermediate skills/gsd/gsd-*/ layout that pre-Phase-2 installs left
  on disk.
- Delete the 9 copyCommandsAs*Skills functions (Codex / Cursor / Windsurf /
  Trae / CodeBuddy / Copilot / Claude / Antigravity / Augment) and the
  _copyCommandsAsSkillsViaConverter helper. All test entry points migrated
  to call installRuntimeArtifacts directly through the unified seam.
- Collapse the 9-branch uninstall ladder to one uninstallRuntimeArtifacts
  call plus preserved non-layout side-effects (Codex TOML, Copilot
  instructions, hooks).
- Unify install dispatcher: a single _isSkillsRuntime gate routes all 11
  skills runtimes through installRuntimeArtifacts for both full and core/
  minimal profiles. Removes 11 per-runtime if-else branches (3 minimal-mode
  shim branches + 8 dead after-the-gate branches).

Net delta on bin/install.js: 11,495 -> 11,174 (-321 LOC).

New tests:
- tests/install-uninstall-layout-loop.test.cjs (34 tests) - per-runtime
  fixture assertions on install/uninstall/legacy-migration ordering.
- tests/install-hermes-regressions.test.cjs (6 tests) - covers the six
  defects surfaced by iterative review: Hermes upgrade leaves stale dirs,
  --hermes --profile=core fall-through, --qwen --profile=core fall-through,
  minimal-mode dev-preferences migration skipped (Hermes/Qwen/Claude-global),
  and ordering bug in _runLegacyInstallMigrations.

Existing tests (10,038 prior + 40 new) all green: 10,078/10,078 pass.

Refs #3664

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-05-17 12:00:59 -04:00
committed by GitHub
parent 812f9258e4
commit f970c09bf3
16 changed files with 2316 additions and 1335 deletions

View File

@@ -19,12 +19,41 @@ const path = require('path');
const os = require('os');
const fs = require('fs');
const ROOT = path.join(__dirname, '..');
const {
convertClaudeCommandToClaudeSkill,
copyCommandsAsClaudeSkills,
writeManifest,
install,
} = require('../bin/install.js');
installRuntimeArtifacts,
uninstallRuntimeArtifacts,
} = require(path.join(ROOT, 'bin', 'install.js'));
const {
loadSkillsManifest,
resolveProfile,
} = require(path.join(ROOT, 'get-shit-done', 'bin', 'lib', 'install-profiles.cjs'));
// Shared resolved profile (full — installs all skills from srcDir)
const _manifest = loadSkillsManifest();
const resolvedProfileFull = resolveProfile({ modes: [], manifest: _manifest });
/**
* Set up a configDir backed by a custom srcDir via .gsd-source marker.
* Returns { configDir, srcDir } both under tmpDir.
*/
function setupConfigDir(tmpDir, commandFiles) {
const srcDir = path.join(tmpDir, 'commands', 'gsd');
fs.mkdirSync(srcDir, { recursive: true });
for (const [name, content] of Object.entries(commandFiles)) {
fs.writeFileSync(path.join(srcDir, name), content);
}
const configDir = path.join(tmpDir, 'config');
fs.mkdirSync(configDir, { recursive: true });
// .gsd-source marker tells findInstallSourceRoot to use our custom srcDir
fs.writeFileSync(path.join(configDir, '.gsd-source'), srcDir + '\n');
return { configDir, srcDir };
}
// ─── convertClaudeCommandToClaudeSkill ──────────────────────────────────────
@@ -162,9 +191,9 @@ describe('convertClaudeCommandToClaudeSkill', () => {
});
});
// ─── copyCommandsAsClaudeSkills ─────────────────────────────────────────────
// ─── installRuntimeArtifacts (claude global) — skill layout ─────────────────
describe('copyCommandsAsClaudeSkills', () => {
describe('installRuntimeArtifacts (claude global) — skill layout', () => {
let tmpDir;
beforeEach(() => {
@@ -176,22 +205,14 @@ describe('copyCommandsAsClaudeSkills', () => {
});
test('creates correct directory structure skills/gsd-xxx/SKILL.md', () => {
// Create source commands
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'next.md'),
'---\nname: gsd:next\ndescription: Advance\nallowed-tools:\n - Read\n---\n\nBody.'
);
fs.writeFileSync(
path.join(srcDir, 'health.md'),
'---\nname: gsd:health\ndescription: Check health\n---\n\nHealth body.'
);
const { configDir } = setupConfigDir(tmpDir, {
'next.md': '---\nname: gsd:next\ndescription: Advance\nallowed-tools:\n - Read\n---\n\nBody.',
'health.md': '---\nname: gsd:health\ndescription: Check health\n---\n\nHealth body.',
});
const skillsDir = path.join(tmpDir, 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.claude/', 'claude', true);
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
// Verify directory structure
const skillsDir = path.join(configDir, 'skills');
assert.ok(
fs.existsSync(path.join(skillsDir, 'gsd-next', 'SKILL.md')),
'skills/gsd-next/SKILL.md exists'
@@ -202,28 +223,27 @@ describe('copyCommandsAsClaudeSkills', () => {
);
});
test('cleans up old skills before installing new ones', () => {
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'next.md'),
'---\nname: gsd:next\ndescription: Advance\n---\n\nBody.'
);
test('cleans up old skills before installing new ones (uninstall+install cycle)', () => {
const { configDir } = setupConfigDir(tmpDir, {
'next.md': '---\nname: gsd:next\ndescription: Advance\n---\n\nBody.',
});
const skillsDir = path.join(tmpDir, 'skills');
// Create a stale skill that should be removed
const skillsDir = path.join(configDir, 'skills');
// Create a stale skill that should be removed by the uninstall step
const staleDir = path.join(skillsDir, 'gsd-old-command');
fs.mkdirSync(staleDir, { recursive: true });
fs.writeFileSync(path.join(staleDir, 'SKILL.md'), 'stale content');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.claude/', 'claude', true);
// Production sequence: uninstall wipes gsd-* entries, install writes fresh ones
uninstallRuntimeArtifacts('claude', configDir, 'global');
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
// Stale skill removed
// Stale skill removed by uninstall
assert.ok(
!fs.existsSync(staleDir),
'stale skill directory removed'
);
// New skill created
// New skill created by install
assert.ok(
fs.existsSync(path.join(skillsDir, 'gsd-next', 'SKILL.md')),
'new skill created'
@@ -231,64 +251,63 @@ describe('copyCommandsAsClaudeSkills', () => {
});
test('does not remove non-GSD skills', () => {
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'next.md'),
'---\nname: gsd:next\ndescription: Advance\n---\n\nBody.'
);
const { configDir } = setupConfigDir(tmpDir, {
'next.md': '---\nname: gsd:next\ndescription: Advance\n---\n\nBody.',
});
const skillsDir = path.join(tmpDir, 'skills');
// Create a non-GSD skill
const skillsDir = path.join(configDir, 'skills');
// Create a non-GSD skill before install
const otherDir = path.join(skillsDir, 'my-custom-skill');
fs.mkdirSync(otherDir, { recursive: true });
fs.writeFileSync(path.join(otherDir, 'SKILL.md'), 'custom content');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.claude/', 'claude', true);
// Install (no pre-uninstall: uninstall only removes gsd-* prefixed entries)
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
// Non-GSD skill preserved
assert.ok(
fs.existsSync(otherDir),
'non-GSD skill preserved'
);
});
test('handles recursive subdirectories', () => {
const srcDir = path.join(tmpDir, 'src');
const subDir = path.join(srcDir, 'wired');
fs.mkdirSync(subDir, { recursive: true });
fs.writeFileSync(
path.join(subDir, 'ready.md'),
'---\nname: gsd-wired:ready\ndescription: Show ready tasks\n---\n\nBody.'
'non-GSD skill preserved after install'
);
const skillsDir = path.join(tmpDir, 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.claude/', 'claude', true);
// Also survives uninstall (uninstall only removes gsd-* prefixed entries)
uninstallRuntimeArtifacts('claude', configDir, 'global');
assert.ok(
fs.existsSync(path.join(skillsDir, 'gsd-wired-ready', 'SKILL.md')),
'nested command creates gsd-wired-ready/SKILL.md'
fs.existsSync(otherDir),
'non-GSD skill preserved after uninstall'
);
});
test('no-ops when source directory does not exist', () => {
const skillsDir = path.join(tmpDir, 'skills');
// NOTE: Recursive subdirectory support was removed when the shim was replaced.
// stageSkillsForRuntimeAsSkills only processes top-level .md files.
// No subdirectories exist under commands/gsd/ in production.
// The subdir-recursion test has been deleted (option a per #3664 brief).
test('no-ops on install when source directory has no .md files', () => {
// Create an empty (but existing) commands/gsd dir with no .md files.
// stageSkillsForRuntimeAsSkills loops over entries, finds none, and stages
// an empty dir — _copyStaged then copies nothing into skills/.
const emptySrc = path.join(tmpDir, 'empty-commands', 'gsd');
fs.mkdirSync(emptySrc, { recursive: true });
const configDir = path.join(tmpDir, 'config-empty');
fs.mkdirSync(configDir, { recursive: true });
fs.writeFileSync(path.join(configDir, '.gsd-source'), emptySrc + '\n');
// Should not throw
copyCommandsAsClaudeSkills(
path.join(tmpDir, 'nonexistent'),
skillsDir,
'gsd',
'$HOME/.claude/',
'claude',
true
);
assert.ok(!fs.existsSync(skillsDir), 'skills dir not created when src missing');
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
const skillsDir = path.join(configDir, 'skills');
// If skills dir was created it must contain no gsd-* entries
if (fs.existsSync(skillsDir)) {
const gsdEntries = fs.readdirSync(skillsDir).filter(n => n.startsWith('gsd-'));
assert.strictEqual(gsdEntries.length, 0, 'no gsd-* skills created when src has no .md files');
}
});
});
// ─── Path replacement in Claude skills (#1653) ────────────────────────────────
describe('copyCommandsAsClaudeSkills path replacement (#1653)', () => {
describe('installRuntimeArtifacts path replacement in Claude global skills (#1653)', () => {
let tmpDir;
beforeEach(() => {
@@ -299,12 +318,13 @@ describe('copyCommandsAsClaudeSkills path replacement (#1653)', () => {
fs.rmSync(tmpDir, { recursive: true, force: true });
});
test('replaces ~/.claude/ paths with pathPrefix on local install', () => {
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'manager.md'),
[
test('replaces ~/.claude/ and $HOME/.claude/ paths with absolute configDir prefix on global install', () => {
// Global install: configDir IS the runtime config directory.
// computePathPrefix(isGlobal=true) → resolvedTarget + '/'.
// applyRuntimeContentRewritesInPlace rewrites ~/.claude/ and $HOME/.claude/
// to the absolute configDir path so skills work from any machine.
const { configDir } = setupConfigDir(tmpDir, {
'manager.md': [
'---',
'name: gsd:manager',
'description: Manager command',
@@ -312,52 +332,66 @@ describe('copyCommandsAsClaudeSkills path replacement (#1653)', () => {
'',
'<execution_context>',
'@~/.claude/get-shit-done/workflows/manager.md',
'@~/.claude/get-shit-done/references/ui-brand.md',
'@$HOME/.claude/get-shit-done/references/ui-brand.md',
'</execution_context>',
].join('\n')
].join('\n'),
});
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
const content = fs.readFileSync(
path.join(configDir, 'skills', 'gsd-manager', 'SKILL.md'), 'utf8'
);
const skillsDir = path.join(tmpDir, 'skills');
const localPrefix = '/Users/test/myproject/.claude/';
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', localPrefix, 'claude', false);
const content = fs.readFileSync(path.join(skillsDir, 'gsd-manager', 'SKILL.md'), 'utf8');
assert.ok(!content.includes('~/.claude/'), 'no hardcoded ~/.claude/ paths remain');
assert.ok(content.includes(localPrefix + 'get-shit-done/workflows/manager.md'), 'path rewritten to local prefix');
assert.ok(content.includes(localPrefix + 'get-shit-done/references/ui-brand.md'), 'reference path rewritten');
});
test('replaces $HOME/.claude/ paths with pathPrefix', () => {
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'debug.md'),
'---\nname: gsd:debug\ndescription: Debug\n---\n\n@$HOME/.claude/get-shit-done/workflows/debug.md'
);
const skillsDir = path.join(tmpDir, 'skills');
const localPrefix = '/tmp/project/.claude/';
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', localPrefix, 'claude', false);
const content = fs.readFileSync(path.join(skillsDir, 'gsd-debug', 'SKILL.md'), 'utf8');
assert.ok(!content.includes('$HOME/.claude/'), 'no $HOME/.claude/ paths remain');
assert.ok(content.includes(localPrefix + 'get-shit-done/workflows/debug.md'), 'path rewritten');
// Paths are rewritten to the absolute configDir prefix
const expectedPrefix = path.resolve(configDir).replace(/\\/g, '/') + '/';
assert.ok(
content.includes(expectedPrefix + 'get-shit-done/workflows/manager.md'),
'tilde path rewritten to absolute configDir prefix'
);
assert.ok(
content.includes(expectedPrefix + 'get-shit-done/references/ui-brand.md'),
'HOME path rewritten to absolute configDir prefix'
);
});
test('global install preserves $HOME/.claude/ when pathPrefix matches', () => {
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'next.md'),
'---\nname: gsd:next\ndescription: Next\n---\n\n@~/.claude/get-shit-done/workflows/next.md'
test('replaces $HOME/.claude/ paths with absolute configDir prefix on global install', () => {
const { configDir } = setupConfigDir(tmpDir, {
'debug.md': '---\nname: gsd:debug\ndescription: Debug\n---\n\n@$HOME/.claude/get-shit-done/workflows/debug.md',
});
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
const content = fs.readFileSync(
path.join(configDir, 'skills', 'gsd-debug', 'SKILL.md'), 'utf8'
);
assert.ok(!content.includes('$HOME/.claude/'), 'no $HOME/.claude/ paths remain');
const expectedPrefix = path.resolve(configDir).replace(/\\/g, '/') + '/';
assert.ok(
content.includes(expectedPrefix + 'get-shit-done/workflows/debug.md'),
'path rewritten to absolute configDir prefix'
);
});
const skillsDir = path.join(tmpDir, 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.claude/', 'claude', true);
test('global install rewrites ~/.claude/ paths to absolute configDir form', () => {
// For global installs, computePathPrefix returns the absolute configDir path.
// Both ~/.claude/ and $HOME/.claude/ are normalized to the same absolute prefix.
const { configDir } = setupConfigDir(tmpDir, {
'next.md': '---\nname: gsd:next\ndescription: Next\n---\n\n@~/.claude/get-shit-done/workflows/next.md',
});
const content = fs.readFileSync(path.join(skillsDir, 'gsd-next', 'SKILL.md'), 'utf8');
assert.ok(content.includes('$HOME/.claude/get-shit-done/workflows/next.md'), 'global paths use $HOME form');
assert.ok(!content.includes('~/.claude/'), '~/ form replaced with $HOME/ form');
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
const content = fs.readFileSync(
path.join(configDir, 'skills', 'gsd-next', 'SKILL.md'), 'utf8'
);
const expectedPrefix = path.resolve(configDir).replace(/\\/g, '/') + '/';
assert.ok(
content.includes(expectedPrefix + 'get-shit-done/workflows/next.md'),
'global tilde path rewritten to absolute configDir prefix'
);
assert.ok(!content.includes('~/.claude/'), 'tilde form is replaced');
});
});
@@ -375,31 +409,22 @@ describe('Legacy commands/gsd/ cleanup', () => {
});
test('install removes legacy commands/gsd/ directory when present', () => {
// Create a mock legacy commands/gsd/ directory
const legacyDir = path.join(tmpDir, 'commands', 'gsd');
const { configDir } = setupConfigDir(tmpDir, {
'next.md': '---\nname: gsd:next\ndescription: Advance\n---\n\nBody.',
});
// Create a mock legacy commands/gsd/ directory inside configDir
const legacyDir = path.join(configDir, 'commands', 'gsd');
fs.mkdirSync(legacyDir, { recursive: true });
fs.writeFileSync(path.join(legacyDir, 'next.md'), 'legacy content');
// Create source commands for the installer to read
const srcDir = path.join(tmpDir, 'src');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(
path.join(srcDir, 'next.md'),
'---\nname: gsd:next\ndescription: Advance\n---\n\nBody.'
);
const skillsDir = path.join(tmpDir, 'skills');
// Install skills
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.claude/', 'claude', true);
// Simulate the legacy cleanup that install() does after copyCommandsAsClaudeSkills
if (fs.existsSync(legacyDir)) {
fs.rmSync(legacyDir, { recursive: true });
}
// installRuntimeArtifacts calls _runLegacyInstallMigrations which removes
// commands/gsd/ for claude runtime (it's the legacy location for global).
installRuntimeArtifacts('claude', configDir, 'global', resolvedProfileFull);
assert.ok(!fs.existsSync(legacyDir), 'legacy commands/gsd/ removed');
assert.ok(
fs.existsSync(path.join(skillsDir, 'gsd-next', 'SKILL.md')),
fs.existsSync(path.join(configDir, 'skills', 'gsd-next', 'SKILL.md')),
'new skill installed'
);
});
@@ -461,7 +486,7 @@ describe('Claude skills migration exports', () => {
assert.strictEqual(typeof convertClaudeCommandToClaudeSkill, 'function');
});
test('copyCommandsAsClaudeSkills is exported', () => {
assert.strictEqual(typeof copyCommandsAsClaudeSkills, 'function');
test('installRuntimeArtifacts is exported', () => {
assert.strictEqual(typeof installRuntimeArtifacts, 'function');
});
});