@opengsd/gsd-core 1.6.1 → 1.7.0-rc.2

package/gsd-core/bin/lib/install-engine.cjs

@@ -0,0 +1,755 @@
+/* eslint-disable @typescript-eslint/no-explicit-any,
+                  @typescript-eslint/no-unsafe-assignment,
+                  @typescript-eslint/no-unsafe-member-access,
+                  @typescript-eslint/no-unsafe-return,
+                  @typescript-eslint/no-unsafe-call,
+                  @typescript-eslint/no-unsafe-argument,
+                  @typescript-eslint/no-require-imports */
+// Mechanical extraction from bin/install.js; keep behavior parity before typing.
+'use strict';
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+/**
+ * Install Engine Module — ADR-1239 Phase B.
+ *
+ * Runtime-artifact install/uninstall cluster extracted from bin/install.js.
+ * bin/install.js imports this module for the layout-driven install/uninstall
+ * orchestrators and their private helpers. getCommitAttribution STAYS in
+ * bin/install.js (impure install-time config I/O); it is injected via the
+ * `resolveAttribution` parameter at each call site.
+ */
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const runtimeArtifactConversion = require("./runtime-artifact-conversion.cjs");
+const runtimeArtifactLayout = require("./runtime-artifact-layout.cjs");
+const runtimeArtifactInstallPlan = require("./runtime-artifact-install-plan.cjs");
+const runtimeNamePolicy = require("./runtime-name-policy.cjs");
+const { processAttribution } = runtimeArtifactConversion;
+// resolveRuntimeArtifactLayout: accessed via module ref (not destructured) so
+// test stubs that monkeypatch the module's exports are seen at call time.
+const { getDirName } = runtimeNamePolicy;
+// ---------------------------------------------------------------------------
+// USER_OWNED_ARTIFACTS
+// ---------------------------------------------------------------------------
+/**
+ * Single source of truth for user-owned artifacts inside gsd-core/.
+ *
+ * These files are created/refreshed by user-facing workflows (e.g.
+ * /gsd-profile-user) and must be preserved across reinstalls. Critically, they
+ * MUST be excluded from gsd-file-manifest.json — otherwise saveLocalPatches()
+ * will compare a refreshed file against a stale manifest hash and emit a
+ * spurious "locally modified GSD file" warning (bug #2771).
+ *
+ * Invariant: a file is either distribution (manifest-tracked, diff'd against
+ * manifest) or user artifact (preserved across installs, never diff'd). Never
+ * both. Both preserveUserArtifacts call sites and writeManifest must agree on
+ * this list, which is why it lives here as a single constant.
+ *
+ * Paths are relative to the gsd-core/ directory.
+ */
+const USER_OWNED_ARTIFACTS = ['USER-PROFILE.md'];
+// ---------------------------------------------------------------------------
+// Conversion helpers
+// ---------------------------------------------------------------------------
+/**
+ * Apply per-runtime path-prefix rewrites for OpenCode-family skill bodies.
+ * Replaces ~/.claude/, $HOME/.claude/, ./.claude/ and OpenCode-variant paths
+ * with the computed pathPrefix for the install.
+ */
+function applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix) {
+    content = content.replace(/~\/\.claude\//g, pathPrefix);
+    content = content.replace(/\$HOME\/\.claude\//g, pathPrefix);
+    content = content.replace(/\.\/\.claude\//g, `./${getDirName(runtime)}/`);
+    content = content.replace(/~\/\.opencode\//g, pathPrefix);
+    content = content.replace(/~\/\.kilo\//g, pathPrefix);
+    return content;
+}
+/**
+ * Convert a Claude command (.md) to an OpenCode skill (SKILL.md).
+ * The canonical OpenCode-family writer lives in runtime-artifact-conversion.cjs
+ * (single source of truth — avoids a duplicate writer drifting per
+ * DEFECT.GENERATIVE-FIX); this thin wrapper delegates to it.
+ */
+function convertClaudeCommandToOpencodeSkill(content, skillName) {
+    return runtimeArtifactConversion.convertClaudeCommandToOpencodeSkill(content, skillName);
+}
+/**
+ * Convert a Claude command (.md) to a Kilo skill (SKILL.md).
+ * Thin wrapper over the shared OpenCode-family writer (Kilo shares the schema).
+ */
+function convertClaudeCommandToKiloSkill(content, skillName) {
+    return runtimeArtifactConversion.convertClaudeCommandToKiloSkill(content, skillName);
+}
+// ---------------------------------------------------------------------------
+// User-artifact preservation helpers
+// ---------------------------------------------------------------------------
+/**
+ * Save user-generated files from destDir to an in-memory map before a wipe.
+ *
+ * @param destDir - Directory that is about to be wiped
+ * @param fileNames - Relative file names (e.g. ['USER-PROFILE.md']) to preserve
+ * @returns Map of fileName → file content (only entries that existed)
+ */
+function preserveUserArtifacts(destDir, fileNames) {
+    const saved = new Map();
+    for (const name of fileNames) {
+        const fullPath = node_path_1.default.join(destDir, name);
+        if (node_fs_1.default.existsSync(fullPath)) {
+            try {
+                saved.set(name, node_fs_1.default.readFileSync(fullPath, 'utf8'));
+            }
+            catch { /* skip unreadable files */ }
+        }
+    }
+    return saved;
+}
+/**
+ * Restore user-generated files saved by preserveUserArtifacts after a wipe.
+ *
+ * @param destDir - Directory that was wiped and recreated
+ * @param saved - Map returned by preserveUserArtifacts
+ */
+function restoreUserArtifacts(destDir, saved) {
+    for (const [name, content] of saved) {
+        const fullPath = node_path_1.default.join(destDir, name);
+        try {
+            node_fs_1.default.mkdirSync(node_path_1.default.dirname(fullPath), { recursive: true });
+            node_fs_1.default.writeFileSync(fullPath, content, 'utf8');
+        }
+        catch { /* skip unwritable paths */ }
+    }
+}
+// ---------------------------------------------------------------------------
+// Symlink-escape guard
+// ---------------------------------------------------------------------------
+/**
+ * Returns true if any path component between `root` and `fullPath` is a
+ * symbolic link (which could redirect writes outside the install root).
+ */
+function hasExistingSymlinkBetween(root, fullPath) {
+    const resolvedRoot = node_path_1.default.resolve(root);
+    const resolvedFullPath = node_path_1.default.resolve(fullPath);
+    if (resolvedFullPath !== resolvedRoot && !resolvedFullPath.startsWith(resolvedRoot + node_path_1.default.sep)) {
+        return true;
+    }
+    let cursor = resolvedRoot;
+    if (node_fs_1.default.existsSync(cursor) && node_fs_1.default.lstatSync(cursor).isSymbolicLink()) {
+        return true;
+    }
+    const relative = node_path_1.default.relative(resolvedRoot, resolvedFullPath);
+    for (const segment of relative.split(node_path_1.default.sep)) {
+        if (!segment)
+            continue;
+        cursor = node_path_1.default.join(cursor, segment);
+        if (!node_fs_1.default.existsSync(cursor))
+            return false;
+        if (node_fs_1.default.lstatSync(cursor).isSymbolicLink())
+            return true;
+    }
+    return false;
+}
+// ---------------------------------------------------------------------------
+// migrateLegacyDevPreferencesToSkill
+// ---------------------------------------------------------------------------
+/**
+ * Migrate a legacy dev-preferences.md (saved from commands/gsd/) into the
+ * runtime-aware SKILL.md location used by the writer after #2973.
+ *
+ * For runtimes with a nested skills layout (e.g. Hermes: skills/gsd/<stem>/),
+ * the target is <configDir>/skills/gsd/dev-preferences/SKILL.md.
+ * For runtimes with a flat skills layout (prefix='gsd-'), the target is
+ * <configDir>/skills/gsd-dev-preferences/SKILL.md.
+ *
+ * Skips silently if no legacy file was preserved, or if a SKILL.md already
+ * exists at the new location (don't clobber user-customized skill content
+ * — they may have edited the new file directly). Returns true on actual
+ * migration so callers can log a one-line confirmation.
+ *
+ * @param targetDir - Resolved runtime config directory (e.g. ~/.claude)
+ * @param saved - Map returned by preserveUserArtifacts
+ * @param runtime - canonical runtime ID (e.g. 'hermes', 'qwen', 'claude')
+ * @param scope - install scope
+ * @returns true if a file was migrated, false otherwise
+ */
+function migrateLegacyDevPreferencesToSkill(targetDir, saved, runtime, scope = 'global') {
+    if (!saved || !saved.has('dev-preferences.md'))
+        return false;
+    let skillDir;
+    if (runtime) {
+        const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir, scope);
+        const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
+        if (!skillsKindEntry)
+            return false; // runtime has no skills layout at this scope (e.g. cline local)
+        const stemName = skillsKindEntry.prefix === '' ? 'dev-preferences' : 'gsd-dev-preferences';
+        skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath), stemName);
+    }
+    else {
+        // Legacy fallback for callers that have not yet been updated to pass runtime
+        skillDir = node_path_1.default.join(runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, 'skills'), 'gsd-dev-preferences');
+    }
+    const skillFile = node_path_1.default.join(skillDir, 'SKILL.md');
+    if (node_fs_1.default.existsSync(skillFile))
+        return false;
+    // Symlink-escape guard: reject if any path component between targetDir and
+    // skillDir is a symlink that would redirect writes outside the config root.
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(targetDir), skillDir)) {
+        throw new Error(`migrateLegacyDevPreferencesToSkill: skillDir "${skillDir}" contains a symlink escaping the install root "${targetDir}" — refusing to write`);
+    }
+    try {
+        node_fs_1.default.mkdirSync(skillDir, { recursive: true });
+        node_fs_1.default.writeFileSync(skillFile, saved.get('dev-preferences.md'), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// _copyStaged
+// ---------------------------------------------------------------------------
+/**
+ * Copy a staged directory's contents into destDir.
+ * Additive — does not prune (surface.cjs handles pruning).
+ *
+ * For skills kind: each child of stagedDir is a `${prefix}${stem}/` dir; copy
+ *   the whole dir into destDir.
+ * For commands/agents kind: iterate .md files and write them into destDir.
+ *   - commands: write as `${prefix}${stem}.md` unless destSubpath already
+ *     encodes the GSD namespace as its last segment (e.g. `commands/gsd`), in
+ *     which case write as `${stem}.md` (directory IS the namespace).
+ *   - agents: write as-is (files already carry their own `gsd-` prefix).
+ * For kimi-agents kind: recursively copy generated YAML/prompt files.
+ */
+function _copyStaged(stagedDir, destDir, kind, configDir) {
+    // Defense-in-depth: verify destDir is within the install root even if the
+    // upstream assertDestWithinConfigHome check was somehow bypassed. This guards
+    // the actual write site against any future call-site drift.
+    // Fail-closed: every _copyStaged write must declare its install root so the gate
+    // can confine it. All callers pass configDir; an omitted root is a bug, not a copy.
+    if (configDir === undefined) {
+        throw new Error('_copyStaged: configDir (install root) is required to confine writes — refusing to write');
+    }
+    // Strict-subpath + NUL containment via the canonical gate (shared with the
+    // layout-driven install plan); throws if destDir escapes the install root.
+    // destDir here is an absolute path; path.resolve(configDir, absoluteDest) returns it unchanged, so the gate's strict-subpath check still correctly confines it to configDir.
+    const resolvedDest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(configDir, destDir);
+    // Symlink-escape guard: reject if any path component between configDir and
+    // destDir is a symlink that would redirect writes outside configDir.
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), resolvedDest)) {
+        throw new Error(`_copyStaged: destDir "${destDir}" contains a symlink escaping the install root "${configDir}" — refusing to write`);
+    }
+    // Use the validated absolute path for the actual writes below.
+    destDir = resolvedDest;
+    if (!node_fs_1.default.existsSync(stagedDir))
+        return;
+    node_fs_1.default.mkdirSync(destDir, { recursive: true });
+    if (kind.kind === 'skills') {
+        // Each child of stagedDir is a prefixed skill directory: gsd-help/, etc.
+        for (const entry of node_fs_1.default.readdirSync(stagedDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const src = node_path_1.default.join(stagedDir, entry.name);
+            const dest = node_path_1.default.join(destDir, entry.name);
+            node_fs_1.default.cpSync(src, dest, { recursive: true });
+        }
+        return;
+    }
+    if (kind.kind === 'kimi-agents') {
+        node_fs_1.default.cpSync(stagedDir, destDir, { recursive: true });
+        return;
+    }
+    // commands or agents
+    const entries = node_fs_1.default.readdirSync(stagedDir, { withFileTypes: true });
+    // For commands: apply prefix unless the destSubpath's last segment already
+    // represents the GSD namespace (e.g. 'commands/gsd' → last segment 'gsd').
+    const destLast = node_path_1.default.basename(kind.destSubpath);
+    const prefixStem = kind.prefix ? kind.prefix.replace(/-$/, '') : '';
+    const namespacedByDir = kind.kind === 'commands' && destLast === prefixStem;
+    for (const entry of entries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.md'))
+            continue;
+        const stem = entry.name.slice(0, -3); // strip .md
+        let destName;
+        if (kind.kind === 'agents') {
+            // Agent files already carry the gsd- prefix in the source dir
+            destName = entry.name;
+        }
+        else if (namespacedByDir) {
+            // Directory is the namespace; don't double-prefix the filename
+            destName = entry.name;
+        }
+        else {
+            // Flat commands directory (e.g. command/ for opencode/kilo)
+            destName = `${kind.prefix}${stem}.md`;
+        }
+        node_fs_1.default.copyFileSync(node_path_1.default.join(stagedDir, entry.name), node_path_1.default.join(destDir, destName));
+    }
+}
+// ---------------------------------------------------------------------------
+// _removeGsdEntries
+// ---------------------------------------------------------------------------
+/**
+ * Remove GSD-prefixed entries from destDir matching kind.prefix.
+ * For the prefix='' case: the destSubpath IS the namespace — remove the entire
+ * destDir. (No current runtime uses prefix='' after #947 reversed Hermes; kept
+ * as a defensive guard for future runtimes.)
+ */
+function _removeGsdEntries(destDir, kind) {
+    if (!node_fs_1.default.existsSync(destDir))
+        return;
+    if (kind.kind === 'kimi-agents') {
+        for (const fileName of ['gsd.yaml', 'gsd.md']) {
+            node_fs_1.default.rmSync(node_path_1.default.join(destDir, fileName), { force: true });
+        }
+        const subagentsDir = node_path_1.default.join(destDir, 'subagents');
+        if (node_fs_1.default.existsSync(subagentsDir)) {
+            for (const entry of node_fs_1.default.readdirSync(subagentsDir, { withFileTypes: true })) {
+                if (!entry.isFile())
+                    continue;
+                if (!entry.name.startsWith('gsd-'))
+                    continue;
+                if (!entry.name.endsWith('.yaml') && !entry.name.endsWith('.md'))
+                    continue;
+                node_fs_1.default.rmSync(node_path_1.default.join(subagentsDir, entry.name), { force: true });
+            }
+        }
+        return;
+    }
+    if (kind.prefix === '') {
+        // Whole-namespace removal (Hermes nested case — destSubpath is skills/gsd)
+        // The directory itself is the GSD namespace, so remove it entirely.
+        node_fs_1.default.rmSync(destDir, { recursive: true, force: true });
+        return;
+    }
+    for (const entry of node_fs_1.default.readdirSync(destDir, { withFileTypes: true })) {
+        if (!entry.name.startsWith(kind.prefix))
+            continue;
+        node_fs_1.default.rmSync(node_path_1.default.join(destDir, entry.name), { recursive: true, force: true });
+    }
+}
+// ---------------------------------------------------------------------------
+// _snapshotDir / _restoreDir
+// ---------------------------------------------------------------------------
+/**
+ * Deep-snapshot a directory tree into a Map<relPath, Buffer>.
+ * Returns an empty Map if the directory doesn't exist.
+ */
+function _snapshotDir(dir) {
+    const files = new Map();
+    if (!node_fs_1.default.existsSync(dir))
+        return files;
+    const walk = (relPath, absPath) => {
+        for (const e of node_fs_1.default.readdirSync(absPath, { withFileTypes: true })) {
+            const childRel = relPath ? node_path_1.default.join(relPath, e.name) : e.name;
+            const childAbs = node_path_1.default.join(absPath, e.name);
+            if (e.isDirectory())
+                walk(childRel, childAbs);
+            else if (e.isFile())
+                files.set(childRel, node_fs_1.default.readFileSync(childAbs));
+        }
+    };
+    walk('', dir);
+    return files;
+}
+/**
+ * Restore a directory tree from a Map<relPath, Buffer> produced by _snapshotDir.
+ */
+function _restoreDir(dir, snapshot) {
+    for (const [relPath, buf] of snapshot) {
+        const absPath = node_path_1.default.join(dir, relPath);
+        node_fs_1.default.mkdirSync(node_path_1.default.dirname(absPath), { recursive: true });
+        node_fs_1.default.writeFileSync(absPath, buf);
+    }
+}
+// ---------------------------------------------------------------------------
+// _removeHermesBareStemDirs
+// ---------------------------------------------------------------------------
+/**
+ * After the layout-driven install loop writes new gsd-<stem>/ dirs to
+ * skills/gsd/, remove any pre-existing bare-stem dirs (skills/gsd/<stem>/)
+ * that correspond to the newly installed gsd-<stem> entries.
+ *
+ * @param nestedGsdDir  absolute path to skills/gsd/ category dir
+ */
+function _removeHermesBareStemDirs(nestedGsdDir) {
+    if (!node_fs_1.default.existsSync(nestedGsdDir))
+        return;
+    const entries = node_fs_1.default.readdirSync(nestedGsdDir, { withFileTypes: true });
+    // Collect the set of stems that were installed as gsd-<stem>/ this run.
+    const installedStems = new Set();
+    for (const entry of entries) {
+        if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
+            installedStems.add(entry.name.slice('gsd-'.length)); // e.g. 'quick', 'dev-preferences'
+        }
+    }
+    // Remove any bare <stem>/ dir for which gsd-<stem>/ was just installed.
+    for (const entry of entries) {
+        if (entry.isDirectory() && !entry.name.startsWith('gsd-') && installedStems.has(entry.name)) {
+            node_fs_1.default.rmSync(node_path_1.default.join(nestedGsdDir, entry.name), { recursive: true });
+        }
+    }
+}
+// ---------------------------------------------------------------------------
+// Legacy migration helpers
+// ---------------------------------------------------------------------------
+/**
+ * Run legacy install migrations that must execute BEFORE the layout-driven
+ * copy so stale artifacts are cleaned up before new ones are written.
+ *
+ * @param runtime
+ * @param configDir  resolved runtime config directory
+ * @param scope
+ */
+function _runLegacyInstallMigrations(runtime, configDir, scope = 'global') {
+    const legacyCommandsGsd = node_path_1.default.join(configDir, 'commands', 'gsd');
+    // Claude / Qwen / Hermes: clean up legacy commands/gsd/ and preserve dev-preferences
+    // for migration. The actual migration call is deferred to after all layout cleanup so
+    // that for Hermes the flat skills/gsd-*/ removal (below) does not delete the freshly
+    // created skills/gsd-dev-preferences/ skill dir.
+    let savedLegacyArtifacts = null;
+    if (runtime === 'claude' || runtime === 'qwen' || runtime === 'hermes') {
+        if (node_fs_1.default.existsSync(legacyCommandsGsd)) {
+            savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
+            node_fs_1.default.rmSync(legacyCommandsGsd, { recursive: true });
+        }
+    }
+    // Hermes: remove pre-#2841 flat skills/gsd-*/ entries that lived alongside
+    // the new skills/gsd/ nested layout.
+    if (runtime === 'hermes') {
+        const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
+        if (node_fs_1.default.existsSync(flatSkillsDir)) {
+            for (const entry of node_fs_1.default.readdirSync(flatSkillsDir, { withFileTypes: true })) {
+                if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
+                    node_fs_1.default.rmSync(node_path_1.default.join(flatSkillsDir, entry.name), { recursive: true });
+                }
+            }
+        }
+        // Hermes: bare-stem skills/gsd/<stem>/ cleanup is deferred to AFTER the
+        // layout-driven install loop in installRuntimeArtifacts, where the exact set
+        // of staged gsd-<stem>/ dirs is known. Removing here (before staging) would
+        // require readGsdCommandNames() which misses skills like 'dev-preferences'
+        // that are not in the commands directory. See _removeHermesBareStemDirs().
+    }
+    // Migrate dev-preferences.md content → runtime-aware SKILL.md location (#2973).
+    // Done after all layout cleanup so Hermes flat-dir removal does not delete the
+    // newly created skill dir. No-op if skill file already exists.
+    if (savedLegacyArtifacts) {
+        migrateLegacyDevPreferencesToSkill(configDir, savedLegacyArtifacts, runtime, scope);
+    }
+}
+/**
+ * Run legacy uninstall cleanup that must execute BEFORE the layout-driven
+ * removal so old-format entries are also cleaned up.
+ *
+ * @param runtime
+ * @param configDir  resolved runtime config directory
+ * @param scope
+ * @returns saved legacy artifacts for post-removal migration, or null
+ */
+function _runLegacyUninstallCleanup(runtime, configDir, scope = 'global') {
+    // commands/gsd/ is a legacy location for Qwen, Hermes, and all Claude installs.
+    // Prior to #1367 fix, Claude-local used commands/gsd/<cmd>.md (colon-namespaced).
+    // After #1367, Claude-local uses flat commands/gsd-<cmd>.md. The inline uninstall
+    // block (1c) handles removal of flat files; this function handles the legacy
+    // commands/gsd/ directory for all Claude scopes (global was already included,
+    // local is now added since that layout is also legacy post-#1367).
+    // #2973 / Codex review (bd1f06c9): preserve user-owned dev-preferences.md
+    // before destructive wipe. Migration to skills/gsd-dev-preferences/SKILL.md
+    // is deferred and returned so the caller can apply it AFTER layout-driven
+    // removal — this prevents the layout's gsd-* prefix removal from wiping the
+    // freshly created skill dir (same pattern as _runLegacyInstallMigrations).
+    let savedLegacyArtifacts = null;
+    // commands/gsd/ is a legacy location for Qwen, Hermes, and Claude global.
+    // Claude local is intentionally excluded: the inline uninstall block (1c) handles
+    // commands/gsd/ for claude local, preserving dev-preferences.md by restoring it
+    // to the same location (#1423). Using migrateLegacyDevPreferencesToSkill here
+    // (which would redirect to skills/) conflicts with the test contract for local installs.
+    const isLegacyCommandsGsd = runtime === 'qwen' || runtime === 'hermes' || (runtime === 'claude' && scope === 'global');
+    if (isLegacyCommandsGsd) {
+        const legacyCommandsGsd = node_path_1.default.join(configDir, 'commands', 'gsd');
+        if (node_fs_1.default.existsSync(legacyCommandsGsd)) {
+            savedLegacyArtifacts = preserveUserArtifacts(legacyCommandsGsd, ['dev-preferences.md']);
+            node_fs_1.default.rmSync(legacyCommandsGsd, { recursive: true });
+        }
+    }
+    // Hermes: pre-#2841 flat skills/gsd-*/ entries
+    if (runtime === 'hermes') {
+        const flatSkillsDir = node_path_1.default.join(configDir, 'skills');
+        if (node_fs_1.default.existsSync(flatSkillsDir)) {
+            for (const entry of node_fs_1.default.readdirSync(flatSkillsDir, { withFileTypes: true })) {
+                if (entry.isDirectory() && entry.name.startsWith('gsd-')) {
+                    node_fs_1.default.rmSync(node_path_1.default.join(flatSkillsDir, entry.name), { recursive: true });
+                }
+            }
+        }
+        // Hermes: pre-#947 bare-stem skills/gsd/<stem>/ entries (dirs that do NOT
+        // start with 'gsd-') — the #3664 layout used prefix='' so GSD-owned skills
+        // had bare names (e.g. skills/gsd/help/). These are stale on uninstall.
+        const nestedGsdDirForUninstall = node_path_1.default.join(configDir, 'skills', 'gsd');
+        if (node_fs_1.default.existsSync(nestedGsdDirForUninstall)) {
+            for (const entry of node_fs_1.default.readdirSync(nestedGsdDirForUninstall, { withFileTypes: true })) {
+                if (entry.isDirectory() && !entry.name.startsWith('gsd-')) {
+                    node_fs_1.default.rmSync(node_path_1.default.join(nestedGsdDirForUninstall, entry.name), { recursive: true });
+                }
+            }
+        }
+    }
+    // Return saved artifacts so the caller can migrate after layout-driven removal.
+    return savedLegacyArtifacts;
+}
+// ---------------------------------------------------------------------------
+// installRuntimeArtifacts
+// ---------------------------------------------------------------------------
+/**
+ * Layout-driven install orchestrator.
+ * Runs legacy migrations first, then uses resolveRuntimeArtifactLayout to
+ * determine what artifact kinds to write and where.
+ *
+ * @param runtime             canonical runtime ID
+ * @param configDir           resolved runtime config directory
+ * @param scope
+ * @param resolvedProfile     from resolveProfile() / resolveEffectiveProfile()
+ * @param resolveAttribution  injection: (runtime) => attribution string | undefined
+ */
+function installRuntimeArtifacts(runtime, configDir, scope, resolvedProfile, resolveAttribution = () => undefined) {
+    // Legacy cleanup before layout-driven writes
+    _runLegacyInstallMigrations(runtime, configDir, scope);
+    const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope);
+    const planResult = runtimeArtifactInstallPlan.createRuntimeArtifactInstallPlan({
+        // `Layout` is structurally identical across the layout/install-plan .cjs
+        // modules but nominally distinct to tsc (untyped .cjs boundary) — bridge it.
+        layout: layout,
+        resolvedProfile,
+        homedir: () => node_os_1.default.homedir(),
+        platform: process.platform,
+        resolveAttribution,
+    });
+    const cleanupDirs = planResult.ok ? planResult.plan.cleanupDirs : planResult.cleanupDirs;
+    try {
+        if (!planResult.ok) {
+            throw new Error(planResult.message);
+        }
+        const kindsByName = new Map(layout.kinds.map((kind) => [kind.kind, kind]));
+        for (const item of planResult.plan.items) {
+            const kind = kindsByName.get(item.kind);
+            if (!kind)
+                throw new Error(`Install plan returned unknown artifact kind: ${item.kind}`);
+            const dest = item.destDir;
+            // Symlink-escape guard: reject before mkdir if dest (or any component
+            // between configDir and dest) is a symlink pointing outside configDir.
+            // mkdirSync follows symlinks, so this must run BEFORE the mkdir call.
+            if (hasExistingSymlinkBetween(node_path_1.default.resolve(configDir), dest)) {
+                throw new Error(`installRuntimeArtifacts: destDir "${dest}" contains a symlink escaping the install root "${configDir}" — refusing to create`);
+            }
+            node_fs_1.default.mkdirSync(dest, { recursive: true });
+            if (kind.kind === 'skills' && node_fs_1.default.existsSync(dest)) {
+                // Pre-prune: snapshot user-owned content before _removeGsdEntries wipes it,
+                // then restore after. This preserves user dirs across a wipe-and-replace
+                // install (#2973 / #3664).
+                //
+                // All runtimes (incl. Hermes after #947) use prefix='gsd-'.
+                // _removeGsdEntries removes only gsd-* entries; non-gsd-* user dirs are
+                // untouched. Preserve the explicit user-owned GSD-prefixed skill
+                // gsd-dev-preferences, which GSD does not reinstall from source but must
+                // survive the prune (#2973).
+                const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
+                {
+                    // Preserve explicitly user-owned GSD-prefixed skill dirs.
+                    // gsd-dev-preferences is the sole user-customisable skill in this category.
+                    const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
+                    for (const dirName of USER_OWNED_SKILL_DIRS) {
+                        const skillDir = node_path_1.default.join(dest, dirName);
+                        if (!node_fs_1.default.existsSync(skillDir))
+                            continue;
+                        const snap = _snapshotDir(skillDir);
+                        if (snap.size > 0)
+                            toPreserve.set(dirName, snap);
+                    }
+                }
+                _removeGsdEntries(dest, kind);
+                _copyStaged(item.sourceDir, dest, kind, configDir);
+                // Restore user-owned dirs after the prune+copy
+                for (const [dirName, snap] of toPreserve) {
+                    _restoreDir(node_path_1.default.join(dest, dirName), snap);
+                }
+            }
+            else {
+                // For non-skills kinds (commands, agents): no user content to preserve;
+                // just prune stale gsd-* entries and copy new ones.
+                _removeGsdEntries(dest, kind);
+                _copyStaged(item.sourceDir, dest, kind, configDir);
+            }
+        }
+    }
+    finally {
+        for (const dir of cleanupDirs) {
+            try {
+                node_fs_1.default.rmSync(dir, { recursive: true, force: true });
+            }
+            catch { /* best-effort */ }
+        }
+    }
+    // Hermes: after the install loop has written all gsd-<stem>/ dirs to
+    // skills/gsd/, remove any stale bare-stem dirs (skills/gsd/<stem>/) that
+    // correspond to the newly installed gsd-<stem> entries. This is the robust
+    // replacement for the readGsdCommandNames()-based pre-install cleanup that
+    // missed skills like 'dev-preferences' (#947 adversarial review).
+    //
+    // We run this AFTER the install loop so the installed set is authoritative:
+    // every gsd-<stem>/ present now was written this run (or was there before
+    // with the same prefix). User-owned bare dirs with no gsd-<stem> counterpart
+    // are untouched.
+    if (runtime === 'hermes') {
+        const nestedGsdDirForCleanup = node_path_1.default.join(configDir, 'skills', 'gsd');
+        _removeHermesBareStemDirs(nestedGsdDirForCleanup);
+    }
+}
+// ---------------------------------------------------------------------------
+// installOpencodeFamilySkills
+// ---------------------------------------------------------------------------
+/**
+ * Install the skills layout kind for an OpenCode-family runtime (OpenCode/Kilo).
+ *
+ * These runtimes do NOT go through installRuntimeArtifacts (their commands use a
+ * bespoke flattened-command writer), so this writes ONLY the skills kind
+ * alongside their existing command/ + agents/ surfaces. Uninstall is already
+ * layout-driven (uninstallRuntimeArtifacts iterates layout.kinds), so the
+ * skills/ dir is cleaned up automatically once the layout declares it.
+ *
+ * @param runtime - 'opencode' or 'kilo'
+ * @param targetDir - resolved runtime config directory
+ * @param rawCommandsDir - staged RAW Claude command dir (caller's _stageSkills output)
+ * @param pathPrefix - computed config-path prefix for body rewrites
+ * @param resolveAttribution - injection: (runtime) => attribution string | undefined
+ * @returns number of gsd-* skill directories written
+ */
+function installOpencodeFamilySkills(runtime, targetDir, rawCommandsDir, pathPrefix, resolveAttribution = () => undefined) {
+    const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, targetDir);
+    const skillsKindEntry = layout.kinds.find((k) => k.kind === 'skills');
+    if (!skillsKindEntry)
+        return 0;
+    const rawDir = rawCommandsDir;
+    if (!rawDir || !node_fs_1.default.existsSync(rawDir))
+        return 0;
+    const converter = runtime === 'kilo'
+        ? convertClaudeCommandToKiloSkill
+        : convertClaudeCommandToOpencodeSkill;
+    const dest = runtimeArtifactInstallPlan.assertDestWithinConfigHome(targetDir, skillsKindEntry.destSubpath);
+    // Symlink-escape guard: reject if any path component between targetDir and
+    // dest is a symlink that would redirect writes outside the config root.
+    if (hasExistingSymlinkBetween(node_path_1.default.resolve(targetDir), dest)) {
+        throw new Error(`installOpencodeFamilySkills: destDir "${dest}" contains a symlink escaping the install root "${targetDir}" — refusing to write`);
+    }
+    node_fs_1.default.mkdirSync(dest, { recursive: true });
+    // Preserve user-owned GSD-prefixed skill dirs across the gsd-* prune.
+    // gsd-dev-preferences is generated by the user (via generate-dev-preferences)
+    // and lives at <configDir>/skills/gsd-dev-preferences — _removeGsdEntries
+    // would otherwise wipe it. Mirrors the preservation in installRuntimeArtifacts
+    // (#2973).
+    const USER_OWNED_SKILL_DIRS = ['gsd-dev-preferences'];
+    const toPreserve = new Map(); // dirName -> Map<relPath, Buffer>
+    for (const dirName of USER_OWNED_SKILL_DIRS) {
+        const skillDir = node_path_1.default.join(dest, dirName);
+        if (!node_fs_1.default.existsSync(skillDir))
+            continue;
+        const snap = _snapshotDir(skillDir);
+        if (snap.size > 0)
+            toPreserve.set(dirName, snap);
+    }
+    _removeGsdEntries(dest, skillsKindEntry);
+    let count = 0;
+    for (const entry of node_fs_1.default.readdirSync(rawDir, { withFileTypes: true })) {
+        if (!entry.isFile() || !entry.name.endsWith('.md'))
+            continue;
+        const stem = entry.name.slice(0, -3);
+        const skillName = `${skillsKindEntry.prefix}${stem}`;
+        let content = node_fs_1.default.readFileSync(node_path_1.default.join(rawDir, entry.name), 'utf8');
+        content = applyOpencodeFamilyPathPrefix(content, runtime, pathPrefix);
+        content = processAttribution(content, resolveAttribution(runtime));
+        content = converter(content, skillName);
+        const skillDir = node_path_1.default.join(dest, skillName);
+        node_fs_1.default.mkdirSync(skillDir, { recursive: true });
+        node_fs_1.default.writeFileSync(node_path_1.default.join(skillDir, 'SKILL.md'), content);
+        count++;
+    }
+    // Restore user-owned dirs after the prune+copy.
+    for (const [dirName, snap] of toPreserve) {
+        _restoreDir(node_path_1.default.join(dest, dirName), snap);
+    }
+    return count;
+}
+// ---------------------------------------------------------------------------
+// uninstallRuntimeArtifacts
+// ---------------------------------------------------------------------------
+/**
+ * Layout-driven uninstall orchestrator.
+ * Runs legacy cleanup first, then uses resolveRuntimeArtifactLayout to
+ * determine which GSD-owned entries to remove.
+ *
+ * @param runtime             canonical runtime ID
+ * @param configDir           resolved runtime config directory
+ * @param scope
+ */
+function uninstallRuntimeArtifacts(runtime, configDir, scope) {
+    // Legacy cleanup before layout-driven removal (scope-aware to avoid
+    // removing Claude local commands/gsd/ which is the primary install dir).
+    // Returns saved user artifacts so we can migrate AFTER layout removal
+    // (the layout's gsd-* prefix pass would wipe a skill dir created here).
+    const savedLegacyArtifacts = _runLegacyUninstallCleanup(runtime, configDir, scope);
+    const layout = runtimeArtifactLayout.resolveRuntimeArtifactLayout(runtime, configDir, scope);
+    const plan = runtimeArtifactInstallPlan.createRuntimeArtifactUninstallPlan(layout);
+    const kindsByName = new Map(layout.kinds.map((kind) => [kind.kind, kind]));
+    for (const item of plan.items) {
+        const kind = kindsByName.get(item.kind);
+        if (!kind) {
+            throw new Error(`Runtime artifact uninstall plan referenced unknown kind: ${item.kind}`);
+        }
+        _removeGsdEntries(item.destDir, kind);
+    }
+    // Hermes: after removing gsd-* skill dirs from skills/gsd/, also remove
+    // the GSD-managed DESCRIPTION.md and then the category dir itself if it
+    // contains no user content (#947). _removeGsdEntries removed gsd-* dirs
+    // but left the category container and DESCRIPTION.md intact.
+    if (runtime === 'hermes') {
+        const nestedGsdDir = node_path_1.default.join(configDir, 'skills', 'gsd');
+        if (node_fs_1.default.existsSync(nestedGsdDir)) {
+            // Remove GSD-owned DESCRIPTION.md (written by writeHermesCategoryDescription)
+            node_fs_1.default.rmSync(node_path_1.default.join(nestedGsdDir, 'DESCRIPTION.md'), { force: true });
+            // Remove the category dir if empty (no user content remaining)
+            const remaining = node_fs_1.default.readdirSync(nestedGsdDir, { withFileTypes: true });
+            if (remaining.length === 0) {
+                node_fs_1.default.rmSync(nestedGsdDir, { recursive: true, force: true });
+            }
+        }
+    }
+    // #2973 / Codex review (bd1f06c9): migrate dev-preferences.md to the
+    // runtime-aware SKILL.md location after all layout-driven removal is
+    // complete. Do NOT restore to commands/gsd/ — the user is uninstalling.
+    if (savedLegacyArtifacts) {
+        migrateLegacyDevPreferencesToSkill(configDir, savedLegacyArtifacts, runtime, scope);
+    }
+}
+module.exports = {
+    installRuntimeArtifacts,
+    uninstallRuntimeArtifacts,
+    installOpencodeFamilySkills,
+    _copyStaged,
+    hasExistingSymlinkBetween,
+    preserveUserArtifacts,
+    restoreUserArtifacts,
+    migrateLegacyDevPreferencesToSkill,
+    applyOpencodeFamilyPathPrefix,
+    convertClaudeCommandToOpencodeSkill,
+    convertClaudeCommandToKiloSkill,
+    USER_OWNED_ARTIFACTS,
+    _runLegacyInstallMigrations,
+    _runLegacyUninstallCleanup,
+    _removeGsdEntries,
+    _snapshotDir,
+    _restoreDir,
+    _removeHermesBareStemDirs,
+};