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

@@ -21,11 +21,19 @@ const fs = require('fs');
const {
convertClaudeCommandToClaudeSkill,
copyCommandsAsClaudeSkills,
installRuntimeArtifacts,
} = require('../bin/install.js');
const { parseFrontmatter } = require('./helpers.cjs');
const pkg = require('../package.json');
const {
loadSkillsManifest,
resolveProfile,
} = require('../get-shit-done/bin/lib/install-profiles.cjs');
const manifest = loadSkillsManifest();
const resolvedProfileFull = resolveProfile({ modes: [], manifest });
// ─── convertClaudeCommandToClaudeSkill (used by Hermes via copyCommandsAsClaudeSkills) ──
describe('Hermes Agent: convertClaudeCommandToClaudeSkill', () => {
@@ -120,9 +128,9 @@ describe('Hermes Agent: convertClaudeCommandToClaudeSkill', () => {
});
});
// ─── copyCommandsAsClaudeSkills (used for Hermes skills install) ─────────────
// ─── installRuntimeArtifacts (used for Hermes skills install) ────────────────
describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
describe('Hermes Agent: installRuntimeArtifacts', () => {
let tmpDir;
beforeEach(() => {
@@ -135,7 +143,7 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
}
});
test('creates skills/gsd-xxx/SKILL.md directory structure', () => {
test('creates skills/gsd/quick/SKILL.md directory structure (Hermes bare-stem layout)', () => {
// Create source command files
const srcDir = path.join(tmpDir, 'src', 'commands', 'gsd');
fs.mkdirSync(srcDir, { recursive: true });
@@ -151,17 +159,22 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
'<objective>Quick task body</objective>',
].join('\n'));
const skillsDir = path.join(tmpDir, 'dest', 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '/test/prefix/', 'hermes', false);
const configDir = path.join(tmpDir, 'dest');
fs.mkdirSync(configDir, { recursive: true });
// Redirect findInstallSourceRoot to the test's custom srcDir
fs.writeFileSync(path.join(configDir, '.gsd-source'), srcDir);
// Verify SKILL.md was created
const skillPath = path.join(skillsDir, 'gsd-quick', 'SKILL.md');
assert.ok(fs.existsSync(skillPath), 'gsd-quick/SKILL.md exists');
installRuntimeArtifacts('hermes', configDir, 'global', resolvedProfileFull);
// Hermes layout: skills/gsd/<bare-stem>/SKILL.md (ADR-3660)
const skillPath = path.join(configDir, 'skills', 'gsd', 'quick', 'SKILL.md');
assert.ok(fs.existsSync(skillPath), 'skills/gsd/quick/SKILL.md exists');
// Verify content (structural — parse frontmatter, don't substring-grep)
// Hermes bare-stem: prefix='', so skillName passed to converter = 'quick' (not 'gsd-quick')
const content = fs.readFileSync(skillPath, 'utf8');
const fm = parseFrontmatter(content);
assert.strictEqual(fm.name, 'gsd-quick', 'frontmatter name uses hyphen form (#2808)');
assert.strictEqual(fm.name, 'quick', 'frontmatter name is bare stem for Hermes nested layout');
assert.ok(fm.description && fm.description.length > 0, 'description present and non-empty');
assert.strictEqual(fm.version, pkg.version,
`Hermes SKILL.md must declare version (got ${JSON.stringify(fm.version)})`);
@@ -170,7 +183,7 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
assert.ok(content.includes('<objective>'), 'body content preserved');
});
test('replaces ~/.claude/ paths with pathPrefix', () => {
test('replaces ~/.claude/ paths via applyRuntimeContentRewritesInPlace', () => {
const srcDir = path.join(tmpDir, 'src', 'commands', 'gsd');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(path.join(srcDir, 'next.md'), [
@@ -182,15 +195,19 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
'Reference: @~/.claude/get-shit-done/workflows/next.md',
].join('\n'));
const skillsDir = path.join(tmpDir, 'dest', 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.hermes/', 'hermes', false);
const configDir = path.join(tmpDir, 'dest');
fs.mkdirSync(configDir, { recursive: true });
fs.writeFileSync(path.join(configDir, '.gsd-source'), srcDir);
const content = fs.readFileSync(path.join(skillsDir, 'gsd-next', 'SKILL.md'), 'utf8');
assert.ok(content.includes('$HOME/.hermes/'), 'path replaced to .hermes/');
assert.ok(!content.includes('~/.claude/'), 'old claude path removed');
installRuntimeArtifacts('hermes', configDir, 'global', resolvedProfileFull);
// Hermes layout: skills/gsd/<bare-stem>/SKILL.md
const content = fs.readFileSync(path.join(configDir, 'skills', 'gsd', 'next', 'SKILL.md'), 'utf8');
assert.ok(!content.includes('~/.claude/'), 'old claude tilde-path removed');
assert.ok(!content.includes('$HOME/.claude/'), 'old claude $HOME-path not present');
});
test('replaces $HOME/.claude/ paths with pathPrefix', () => {
test('replaces $HOME/.claude/ paths via applyRuntimeContentRewritesInPlace', () => {
const srcDir = path.join(tmpDir, 'src', 'commands', 'gsd');
fs.mkdirSync(srcDir, { recursive: true });
fs.writeFileSync(path.join(srcDir, 'plan.md'), [
@@ -202,12 +219,16 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
'Reference: $HOME/.claude/get-shit-done/workflows/plan.md',
].join('\n'));
const skillsDir = path.join(tmpDir, 'dest', 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '$HOME/.hermes/', 'hermes', false);
const configDir = path.join(tmpDir, 'dest');
fs.mkdirSync(configDir, { recursive: true });
fs.writeFileSync(path.join(configDir, '.gsd-source'), srcDir);
const content = fs.readFileSync(path.join(skillsDir, 'gsd-plan', 'SKILL.md'), 'utf8');
assert.ok(content.includes('$HOME/.hermes/'), 'path replaced to .hermes/');
assert.ok(!content.includes('$HOME/.claude/'), 'old claude path removed');
installRuntimeArtifacts('hermes', configDir, 'global', resolvedProfileFull);
// Hermes layout: skills/gsd/<bare-stem>/SKILL.md
const content = fs.readFileSync(path.join(configDir, 'skills', 'gsd', 'plan', 'SKILL.md'), 'utf8');
assert.ok(!content.includes('$HOME/.claude/'), 'old claude $HOME-path removed');
assert.ok(!content.includes('~/.claude/'), 'old claude tilde-path not present');
});
test('removes stale gsd- skills before installing new ones', () => {
@@ -222,15 +243,21 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
'Body',
].join('\n'));
const skillsDir = path.join(tmpDir, 'dest', 'skills');
// Pre-create a stale skill
fs.mkdirSync(path.join(skillsDir, 'gsd-old-skill'), { recursive: true });
fs.writeFileSync(path.join(skillsDir, 'gsd-old-skill', 'SKILL.md'), 'old');
const configDir = path.join(tmpDir, 'dest');
fs.mkdirSync(configDir, { recursive: true });
fs.writeFileSync(path.join(configDir, '.gsd-source'), srcDir);
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '/test/', 'hermes', false);
// Pre-create a stale flat skill (skills/gsd-old-skill) — legacy Hermes layout
const staleFlatSkillDir = path.join(configDir, 'skills', 'gsd-old-skill');
fs.mkdirSync(staleFlatSkillDir, { recursive: true });
fs.writeFileSync(path.join(staleFlatSkillDir, 'SKILL.md'), 'old');
assert.ok(!fs.existsSync(path.join(skillsDir, 'gsd-old-skill')), 'stale skill removed');
assert.ok(fs.existsSync(path.join(skillsDir, 'gsd-quick', 'SKILL.md')), 'new skill installed');
installRuntimeArtifacts('hermes', configDir, 'global', resolvedProfileFull);
// _runLegacyInstallMigrations removes skills/gsd-* flat dirs for hermes
assert.ok(!fs.existsSync(staleFlatSkillDir), 'stale flat gsd- skill removed');
// New Hermes layout: skills/gsd/<bare-stem>/SKILL.md
assert.ok(fs.existsSync(path.join(configDir, 'skills', 'gsd', 'quick', 'SKILL.md')), 'new skill installed at skills/gsd/quick/SKILL.md');
});
test('preserves agent field in frontmatter', () => {
@@ -250,10 +277,14 @@ describe('Hermes Agent: copyCommandsAsClaudeSkills', () => {
'Execute body',
].join('\n'));
const skillsDir = path.join(tmpDir, 'dest', 'skills');
copyCommandsAsClaudeSkills(srcDir, skillsDir, 'gsd', '/test/', 'hermes', false);
const configDir = path.join(tmpDir, 'dest');
fs.mkdirSync(configDir, { recursive: true });
fs.writeFileSync(path.join(configDir, '.gsd-source'), srcDir);
const content = fs.readFileSync(path.join(skillsDir, 'gsd-execute', 'SKILL.md'), 'utf8');
installRuntimeArtifacts('hermes', configDir, 'global', resolvedProfileFull);
// Hermes layout: skills/gsd/<bare-stem>/SKILL.md
const content = fs.readFileSync(path.join(configDir, 'skills', 'gsd', 'execute', 'SKILL.md'), 'utf8');
const fm = parseFrontmatter(content);
assert.strictEqual(fm.agent, 'gsd-executor', 'agent field preserved');
});