@therocketcode/gsd-core 1.4.0

package/gsd-core/bin/lib/installer-migrations/000-first-time-baseline.cjs

@@ -0,0 +1,218 @@
+"use strict";
+/**
+ * Installer migration: record first-time installer migration baseline.
+ *
+ * ADR-457 build-at-publish: the hand-written
+ * bin/lib/installer-migrations/000-first-time-baseline.cjs collapsed to a
+ * TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const BASELINE_MIGRATION_ID = '2026-05-11-first-time-baseline-scan';
+// Runtime install surfaces must stay aligned with:
+// - docs/installer-migrations.md#runtime-configuration-contract-registry
+// - docs/ARCHITECTURE.md#runtime-install-contract-matrix
+const RUNTIME_SURFACES = {
+    claude: ['gsd-core', 'commands/gsd', 'skills', 'agents', 'hooks', 'settings.json'],
+    codex: ['gsd-core', 'skills', 'agents', 'hooks', 'config.toml', 'hooks.json'],
+    gemini: ['gsd-core', 'commands/gsd', 'hooks'],
+    opencode: ['gsd-core', 'command', 'skills', 'agents'],
+    kilo: ['gsd-core', 'command', 'skills', 'agents'],
+    copilot: ['gsd-core', 'skills', 'agents'],
+    antigravity: ['gsd-core', 'skills', 'agents'],
+    cursor: ['gsd-core', 'skills', 'agents', 'hooks', 'hooks.json'],
+    windsurf: ['gsd-core', 'skills', 'agents', 'rules'],
+    augment: ['gsd-core', 'skills', 'agents'],
+    trae: ['gsd-core', 'skills', 'agents', 'rules'],
+    qwen: ['gsd-core', 'skills', 'agents'],
+    hermes: ['gsd-core', 'skills/gsd', 'agents'],
+    cline: ['gsd-core', 'skills', 'agents'],
+    codebuddy: ['gsd-core', 'skills', 'agents'],
+};
+const COMMON_SURFACES = ['gsd-core', 'skills', 'agents', 'hooks'];
+const INTERNAL_TOP_LEVEL_NAMES = new Set([
+    'gsd-file-manifest.json',
+    'gsd-install-state.json',
+    'gsd-migration-backups',
+    'gsd-migration-journal',
+]);
+const USER_OWNED_PATHS = new Set([
+    'gsd-core/USER-PROFILE.md',
+    'commands/gsd/dev-preferences.md',
+    'skills/gsd-dev-preferences/SKILL.md',
+]);
+let knownGeneratedAgentNames = null;
+function normalizeRelPath(relPath) {
+    return relPath.replace(/\\/g, '/').replace(/^\/+/, '');
+}
+function baselineInstallSurfaces(runtime) {
+    if (runtime && RUNTIME_SURFACES[runtime])
+        return RUNTIME_SURFACES[runtime];
+    return COMMON_SURFACES;
+}
+function walkFiles(root, relDir, files) {
+    const dir = node_path_1.default.join(root, relDir);
+    if (!node_fs_1.default.existsSync(dir))
+        return;
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        if (relDir === '' && INTERNAL_TOP_LEVEL_NAMES.has(entry.name))
+            continue;
+        if (entry.isDirectory()) {
+            walkFiles(root, relPath, files);
+        }
+        else if (entry.isFile()) {
+            files.add(normalizeRelPath(relPath));
+        }
+    }
+}
+function scanBaselineFiles(configDir, runtime) {
+    const relPaths = new Set();
+    for (const surface of baselineInstallSurfaces(runtime)) {
+        const normalized = normalizeRelPath(surface);
+        const fullPath = node_path_1.default.join(configDir, normalized);
+        if (!node_fs_1.default.existsSync(fullPath))
+            continue;
+        const stat = node_fs_1.default.statSync(fullPath);
+        if (stat.isDirectory()) {
+            walkFiles(configDir, normalized, relPaths);
+        }
+        else if (stat.isFile() && !INTERNAL_TOP_LEVEL_NAMES.has(normalized)) {
+            relPaths.add(normalized);
+        }
+    }
+    return [...relPaths];
+}
+function isUserOwnedBaselinePath(relPath) {
+    if (USER_OWNED_PATHS.has(relPath))
+        return true;
+    const parts = relPath.split('/');
+    if (parts[0] === 'skills' && parts[1] && !parts[1].startsWith('gsd-'))
+        return true;
+    if (parts[0] === 'agents' && parts[1] && !parts[1].startsWith('gsd-'))
+        return true;
+    return false;
+}
+function listKnownGeneratedAgentNames() {
+    if (knownGeneratedAgentNames)
+        return knownGeneratedAgentNames;
+    knownGeneratedAgentNames = new Set();
+    const agentsDir = node_path_1.default.resolve(__dirname, '..', '..', '..', '..', 'agents');
+    try {
+        for (const entry of node_fs_1.default.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (entry.isFile() && entry.name.startsWith('gsd-') && entry.name.endsWith('.md')) {
+                knownGeneratedAgentNames.add(entry.name.replace(/\.md$/, ''));
+            }
+        }
+    }
+    catch {
+        // If the source agent directory is unavailable, fail closed and treat
+        // GSD-looking agent files as user-choice artifacts.
+    }
+    return knownGeneratedAgentNames;
+}
+function isKnownGeneratedAgentPath(relPath, runtime) {
+    const parts = relPath.split('/');
+    if (parts.length !== 2 || parts[0] !== 'agents')
+        return false;
+    const fileName = parts[1];
+    const extension = node_path_1.default.posix.extname(fileName);
+    if (extension !== '.md' && !(runtime === 'codex' && extension === '.toml'))
+        return false;
+    const agentName = fileName.slice(0, -extension.length);
+    return listKnownGeneratedAgentNames().has(agentName);
+}
+function isStaleGsdLookingPath(relPath) {
+    const baseName = node_path_1.default.posix.basename(relPath);
+    if (/^gsd[-_]/.test(baseName))
+        return true;
+    const parts = relPath.split('/');
+    if ((parts[0] === 'skills' || parts[0] === 'agents') && parts[1] && parts[1].startsWith('gsd-')) {
+        return true;
+    }
+    return false;
+}
+function baselineActionRank(action) {
+    if (action.type === 'record-baseline')
+        return 0;
+    if (action.type === 'baseline-preserve-user')
+        return 1;
+    return 2;
+}
+const migration = {
+    id: BASELINE_MIGRATION_ID,
+    title: 'Record first-time installer migration baseline',
+    description: 'Classify existing install surfaces before destructive installer migrations run.',
+    introducedIn: '1.50.0',
+    scopes: ['global', 'local'],
+    destructive: false,
+    plan: ({ configDir, runtime, baselineScan, classifyArtifact }) => {
+        if (!baselineScan)
+            return [];
+        const actions = [];
+        for (const relPath of scanBaselineFiles(configDir, runtime)) {
+            // docs/installer-migrations.md#baseline-preserve-user keeps user-owned
+            // artifacts out of destructive migration flow.
+            if (isUserOwnedBaselinePath(relPath)) {
+                actions.push({
+                    type: 'baseline-preserve-user',
+                    relPath,
+                    reason: 'known user-owned artifact preserved by first-time migration baseline',
+                    classification: 'user-owned',
+                    originalHash: null,
+                    currentHash: null,
+                });
+                continue;
+            }
+            const artifact = classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine' || artifact.classification === 'managed-modified') {
+                actions.push({
+                    type: 'record-baseline',
+                    relPath,
+                    reason: 'existing manifest-managed file included in first-time migration baseline',
+                });
+                continue;
+            }
+            const currentHash = artifact.currentHash ?? null;
+            if (isKnownGeneratedAgentPath(relPath, runtime)) {
+                actions.push({
+                    type: 'record-baseline',
+                    relPath,
+                    reason: 'known installer-generated agent included in first-time migration baseline',
+                    classification: artifact.classification,
+                    originalHash: artifact.originalHash ?? null,
+                    currentHash,
+                });
+                continue;
+            }
+            if (isStaleGsdLookingPath(relPath)) {
+                actions.push({
+                    type: 'prompt-user',
+                    relPath,
+                    reason: 'GSD-looking file is not proven manifest-managed and needs explicit user choice',
+                    classification: 'stale-gsd-looking',
+                    originalHash: artifact.originalHash ?? null,
+                    currentHash,
+                    prompt: 'Choose whether to remove this stale-looking GSD artifact or keep it as user-owned.',
+                    choices: ['keep', 'remove'],
+                });
+                continue;
+            }
+            actions.push({
+                type: 'baseline-preserve-user',
+                relPath,
+                reason: 'unknown install-surface file preserved by first-time migration baseline',
+                classification: artifact.classification,
+                originalHash: artifact.originalHash ?? null,
+                currentHash,
+            });
+        }
+        return actions.sort((left, right) => baselineActionRank(left) - baselineActionRank(right) || left.relPath.localeCompare(right.relPath));
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/001-legacy-orphan-files.cjs

@@ -0,0 +1,48 @@
+"use strict";
+/**
+ * Installer migration: remove manifest-managed legacy orphan hook files
+ * (ADR-457 build-at-publish: the hand-written
+ * bin/lib/installer-migrations/001-legacy-orphan-files.cjs collapsed to a
+ * TypeScript source of truth). Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+const LEGACY_ORPHAN_FILES = [
+    'hooks/gsd-notify.sh',
+    'hooks/statusline.js',
+];
+const migration = {
+    id: '2026-05-11-legacy-orphan-files',
+    title: 'Remove manifest-managed legacy orphan hook files',
+    description: 'Remove legacy orphan hook files that are still manifest-managed.',
+    introducedIn: '1.50.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    // Retired generated hook files are removed only with manifest-managed
+    // evidence. This follows docs/installer-migrations.md#ownership and avoids
+    // relying on whether a runtime currently registers host hook config in the
+    // runtime contract registry.
+    plan: (ctx) => {
+        const actions = [];
+        for (const relPath of LEGACY_ORPHAN_FILES) {
+            const artifact = ctx.classifyArtifact(relPath);
+            if (artifact.classification === 'managed-pristine') {
+                actions.push({
+                    type: 'remove-managed',
+                    relPath,
+                    reason: 'legacy orphan hook file retired by installer migration',
+                    ownershipEvidence: 'legacy hook path is manifest-managed in gsd-file-manifest.json',
+                });
+            }
+            else if (artifact.classification === 'managed-modified') {
+                actions.push({
+                    type: 'backup-and-remove',
+                    relPath,
+                    reason: 'legacy orphan hook file retired by installer migration',
+                    ownershipEvidence: 'legacy hook path is manifest-managed in gsd-file-manifest.json',
+                });
+            }
+        }
+        return actions;
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/002-codex-legacy-hooks-json.cjs

@@ -0,0 +1,94 @@
+"use strict";
+/**
+ * Installer migration: remove legacy Codex hooks.json GSD hook registrations.
+ *
+ * ADR-457 build-at-publish: the hand-written
+ * bin/lib/installer-migrations/002-codex-legacy-hooks-json.cjs collapsed to a
+ * TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ */
+const shell_command_projection_cjs_1 = require("../shell-command-projection.cjs");
+function isStructurallyEmpty(value) {
+    if (value === null || value === undefined)
+        return true;
+    if (Array.isArray(value))
+        return value.length === 0;
+    if (typeof value !== 'object')
+        return false;
+    for (const _key in value)
+        return false;
+    return true;
+}
+function isManagedCodexHookCommand(command, configDir) {
+    return (0, shell_command_projection_cjs_1.isManagedHookCommand)(command, {
+        surface: 'codex-hooks-json',
+        includeLegacyAliases: true,
+        configDir,
+    });
+}
+function pruneLegacyCodexHooksJsonValue(value, configDir) {
+    if (Array.isArray(value)) {
+        let changed = false;
+        const next = [];
+        for (const item of value) {
+            const pruned = pruneLegacyCodexHooksJsonValue(item, configDir);
+            if (pruned.changed)
+                changed = true;
+            if (pruned.changed && isStructurallyEmpty(pruned.value))
+                changed = true;
+            else
+                next.push(pruned.value);
+        }
+        return { value: next, changed };
+    }
+    if (value && typeof value === 'object' && !Array.isArray(value)) {
+        const valueObj = value;
+        const command = valueObj['command'];
+        if (isManagedCodexHookCommand(command, configDir)) {
+            return { value: null, changed: true };
+        }
+        let changed = false;
+        const next = {};
+        for (const [key, child] of Object.entries(valueObj)) {
+            const pruned = pruneLegacyCodexHooksJsonValue(child, configDir);
+            if (pruned.changed)
+                changed = true;
+            if (pruned.changed && isStructurallyEmpty(pruned.value))
+                changed = true;
+            else
+                next[key] = pruned.value;
+        }
+        return { value: next, changed };
+    }
+    return { value, changed: false };
+}
+const migration = {
+    id: '2026-05-11-codex-legacy-hooks-json',
+    title: 'Remove legacy Codex hooks.json GSD hook registrations',
+    description: 'Remove legacy Codex hooks.json GSD hook registrations after config.toml migration.',
+    introducedIn: '1.50.0',
+    runtimes: ['codex'],
+    scopes: ['global', 'local'],
+    destructive: true,
+    runtimeContract: 'docs/installer-migrations.md#runtime-configuration-contract-registry Codex row',
+    plan: (ctx) => {
+        const { configDir } = ctx;
+        const hooksJson = ctx.readJson('hooks.json');
+        if (!hooksJson.exists || hooksJson.error)
+            return [];
+        const pruned = pruneLegacyCodexHooksJsonValue(hooksJson.value, configDir);
+        if (!pruned.changed)
+            return [];
+        return [
+            {
+                type: 'rewrite-json',
+                relPath: 'hooks.json',
+                value: pruned.value,
+                deleteIfEmpty: true,
+                reason: 'legacy Codex hooks.json GSD registration retired by installer migration',
+                ownershipEvidence: 'pruned command matches generated GSD hook command under the install hooks directory',
+            },
+        ];
+    },
+};
+module.exports = migration;

package/gsd-core/bin/lib/installer-migrations/003-rename-get-shit-done-to-gsd-core.cjs

@@ -0,0 +1,108 @@
+"use strict";
+/**
+ * Installer migration 003: remove stale legacy get-shit-done/ runtime directory // gsd-allow-legacy-name
+ * files after the rename to gsd-core/ (#604).
+ *
+ * Background: the GSD runtime config subdirectory was renamed from
+ * get-shit-done/ to gsd-core/ in #604. On upgrade, both directories can exist // gsd-allow-legacy-name
+ * simultaneously. This migration removes prior-manifest-managed files from the
+ * legacy get-shit-done/ directory during install. Migrations run BEFORE the new // gsd-allow-legacy-name
+ * runtime is materialized, so gsd-core/ will not yet exist on the first upgrade
+ * run — the migration must not gate on its presence. If the install fails after
+ * migrations apply, the framework rolls back by restoring files from rollback
+ * storage (copied before deletion), so removing legacy files pre-materialization
+ * is safe.
+ *
+ * Per-file approach: the migration framework has no recursive directory-removal
+ * primitive — all actions operate on individual files identified by relPath. As
+ * a result, any empty subdirectory shells left under the legacy tree after all
+ * files are removed will remain on disk. Users can remove them manually if
+ * desired. This is a known, intentional limitation of the ADR-0008 design: the
+ * framework never removes directories, only files.
+ *
+ * User file preservation: files classified 'unknown' (not in the prior manifest)
+ * receive a 'baseline-preserve-user' action and are explicitly NOT removed.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+function walkLegacyFiles(root, relDir, baseResolved, results) {
+    const dir = node_path_1.default.join(root, relDir);
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Do not follow symlinks — skip them entirely to avoid out-of-tree traversal.
+        if (entry.isSymbolicLink())
+            continue; // gsd-allow-legacy-name (entry under legacy get-shit-done/ dir)
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        // Bounds check: ensure the resolved path stays under configDir.
+        const resolved = node_path_1.default.resolve(root, relPath);
+        if (resolved !== baseResolved && !resolved.startsWith(baseResolved + node_path_1.default.sep))
+            continue;
+        if (entry.isDirectory()) {
+            walkLegacyFiles(root, relPath, baseResolved, results);
+        }
+        else if (entry.isFile()) {
+            results.push(relPath);
+        }
+    }
+}
+const REASON = 'legacy runtime directory renamed to gsd-core (#604)';
+const migration = {
+    id: '2026-06-02-rename-get-shit-done-to-gsd-core', // gsd-allow-legacy-name
+    title: 'Remove stale legacy get-shit-done/ runtime directory files (#604)', // gsd-allow-legacy-name
+    description: 'After the config dir rename from get-shit-done/ to gsd-core/ (#604), remove prior-manifest-managed files ' + // gsd-allow-legacy-name
+        'from the stale legacy directory during install (framework rollback restores them if install fails). User-added files are preserved.',
+    introducedIn: '1.2.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan(ctx) {
+        const legacyRoot = node_path_1.default.join(ctx.configDir, 'get-shit-done'); // gsd-allow-legacy-name
+        // Idempotency: if the legacy directory doesn't exist, nothing to do.
+        if (!node_fs_1.default.existsSync(legacyRoot))
+            return [];
+        // Safety: if the legacy root itself is a symlink to an out-of-tree location,
+        // do not process it — walking a symlinked dir could emit removes outside configDir.
+        if (node_fs_1.default.lstatSync(legacyRoot).isSymbolicLink())
+            return []; // gsd-allow-legacy-name
+        const baseResolved = node_path_1.default.resolve(ctx.configDir);
+        const relPaths = [];
+        walkLegacyFiles(ctx.configDir, 'get-shit-done', baseResolved, relPaths); // gsd-allow-legacy-name
+        const actions = [];
+        for (const relPath of relPaths) {
+            // Bounds-check each relPath before emitting any action.
+            const resolved = node_path_1.default.resolve(ctx.configDir, relPath);
+            if (resolved !== baseResolved && !resolved.startsWith(baseResolved + node_path_1.default.sep))
+                continue;
+            const { classification } = ctx.classifyArtifact(relPath);
+            if (classification === 'managed-pristine') {
+                actions.push({
+                    type: 'remove-managed',
+                    relPath,
+                    reason: REASON,
+                    ownershipEvidence: 'present in prior install manifest as a managed GSD runtime file',
+                });
+            }
+            else if (classification === 'managed-modified') {
+                actions.push({
+                    type: 'backup-and-remove',
+                    relPath,
+                    reason: REASON,
+                    ownershipEvidence: 'managed GSD runtime file, locally modified; backed up before removal',
+                });
+            }
+            else if (classification === 'unknown') {
+                actions.push({
+                    type: 'baseline-preserve-user',
+                    relPath,
+                    reason: 'user-added file under legacy runtime dir; preserved per ADR-0008',
+                    ownershipEvidence: 'file is not present in the prior install manifest; treated as user-owned',
+                });
+            }
+            // 'managed-missing', 'missing', and any other classification: skip (no action)
+        }
+        return actions;
+    },
+};
+module.exports = migration;