@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/installer-migrations/005-rename-gsd-core-to-pp-core.cjs

@@ -0,0 +1,109 @@
+"use strict";
+/**
+ * Installer migration 005: remove stale gsd-core/ runtime directory files
+ * after the rename to pp-core/.
+ *
+ * Background: the pp-core runtime config subdirectory was renamed from
+ * gsd-core/ to pp-core/ when @opengsd/gsd-core was forked and rebranded
+ * as @pareto4/pp-core. On upgrade, both directories can exist simultaneously.
+ * This migration removes prior-manifest-managed files from the stale legacy
+ * gsd-core/ directory during install. Migrations run BEFORE the new runtime
+ * is materialized, so pp-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;
+        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 = 'runtime directory renamed to pp-core';
+const migration = {
+    id: '2026-06-24-rename-gsd-core-to-pp-core',
+    title: 'Remove stale gsd-core/ runtime directory files after rename to pp-core/',
+    description: 'After the config dir rename from gsd-core/ to pp-core/, remove prior-manifest-managed files ' +
+        'from the stale legacy directory during install (framework rollback restores them if install fails). User-added files are preserved.',
+    introducedIn: '1.0.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan(ctx) {
+        const legacyRoot = node_path_1.default.join(ctx.configDir, 'gsd-core');
+        // 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 [];
+        const baseResolved = node_path_1.default.resolve(ctx.configDir);
+        const relPaths = [];
+        walkLegacyFiles(ctx.configDir, 'gsd-core', baseResolved, relPaths);
+        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 runtime file',
+                });
+            }
+            else if (classification === 'managed-modified') {
+                actions.push({
+                    type: 'backup-and-remove',
+                    relPath,
+                    reason: REASON,
+                    ownershipEvidence: 'managed 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;

package/pp-core/bin/lib/installer-migrations/006-rename-gsd-command-namespace.cjs

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Installer migration 006: remove stale commands/gsd/ (and skills/gsd/) entries
+ * after the flat-hyphen namespace rename (D-12).
+ *
+ * Background: prior to pp-core 1.5.x, Claude Code local installs wrote command
+ * files as .claude/commands/gsd/<cmd>.md, and Gemini installs wrote them as
+ * .gemini/commands/gsd/<cmd>.toml.  After the D-12 flat-hyphen rename, the
+ * installer writes pp-<cmd>.md / pp-<cmd>.toml directly into commands/ with no
+ * gsd/ subdirectory.  On upgrade, the legacy commands/gsd/ directory may still
+ * exist alongside the new pp-* files.  This migration removes prior-manifest-
+ * managed files from the stale commands/gsd/ directory so there is no namespace
+ * collision (INST-04) and the runtime no longer offers the old /gsd:* slash
+ * commands (SC1 / INST-01 remediation).
+ *
+ * Scope: both 'global' and 'local' installs — the legacy sub-directory can exist
+ * in either the user-scope ($HOME/.claude, $HOME/.gemini) or the project-local
+ * (.claude, .gemini) config directories.
+ *
+ * Per-file approach: all actions target individual files.  Empty directory shells
+ * (the gsd/ subdirectory itself) may remain after all files are removed; users
+ * can remove them manually if desired.  The framework never removes directories
+ * — this is a known, intentional limitation of ADR-0008.
+ *
+ * User file preservation: files not in the prior install manifest receive a
+ * 'baseline-preserve-user' action and are NOT removed.  The migration never
+ * touches a file the user created themselves.
+ *
+ * skills/gsd/: some early Hermes/Codex installs wrote GSD skills under
+ * skills/gsd/<skill>/.  The migration also cleans those up when present.
+ */
+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"));
+/**
+ * Recursively enumerate files under root/relDir, skipping symlinks and
+ * any path that resolves outside baseResolved (bounds-check).
+ */
+function walkLegacyFiles(root, relDir, baseResolved, results) {
+    const dir = node_path_1.default.join(root, relDir);
+    // Guard: directory may have been removed between the existsSync check and the walk.
+    if (!node_fs_1.default.existsSync(dir))
+        return;
+    const entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+        // Skip symlinks — avoid traversing out-of-tree targets.
+        if (entry.isSymbolicLink())
+            continue;
+        const relPath = node_path_1.default.posix.join(relDir, entry.name);
+        // Bounds check: every resolved path must stay within 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);
+        }
+    }
+}
+/**
+ * Collect migration actions for a single legacy root directory (e.g. commands/gsd
+ * or skills/gsd).  Returns an empty array if the root does not exist.
+ */
+function collectActionsForLegacyRoot(ctx, legacyRelDir, reason) {
+    const legacyRoot = node_path_1.default.join(ctx.configDir, legacyRelDir);
+    // Idempotency: nothing to do when the legacy directory is absent.
+    if (!node_fs_1.default.existsSync(legacyRoot))
+        return [];
+    // Symlink safety: do not walk a symlinked directory — it might point outside configDir.
+    if (node_fs_1.default.lstatSync(legacyRoot).isSymbolicLink())
+        return [];
+    const baseResolved = node_path_1.default.resolve(ctx.configDir);
+    const relPaths = [];
+    walkLegacyFiles(ctx.configDir, legacyRelDir, baseResolved, relPaths);
+    const actions = [];
+    for (const relPath of relPaths) {
+        // Bounds-check each relPath before emitting any action (defence-in-depth).
+        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,
+                ownershipEvidence: 'present in prior install manifest as a managed runtime file',
+            });
+        }
+        else if (classification === 'managed-modified') {
+            actions.push({
+                type: 'backup-and-remove',
+                relPath,
+                reason,
+                ownershipEvidence: 'managed 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 ${legacyRelDir} directory; 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: no action.
+    }
+    return actions;
+}
+const COMMANDS_GSD_REASON = 'command namespace renamed from commands/gsd/<cmd>.md to commands/pp-<cmd>.md (flat-hyphen, D-12)';
+const SKILLS_GSD_REASON = 'skills namespace migrated from skills/gsd/ to flat skills/ (D-12 follow-on cleanup)';
+const migration = {
+    id: '2026-06-26-rename-gsd-command-namespace',
+    title: 'Remove stale commands/gsd/ after flat-hyphen namespace rename to pp-*',
+    description: 'After the D-12 flat-hyphen rename, Claude Code and Gemini installs write command files as ' +
+        'commands/pp-<cmd>.md (flat) instead of commands/gsd/<cmd>.md. This migration removes ' +
+        'prior-manifest-managed files from the stale commands/gsd/ (and skills/gsd/ if present) ' +
+        'directories to eliminate the /gsd:* namespace collision (INST-04 / SC1 remediation). ' +
+        'User-added files are always preserved.',
+    introducedIn: '1.5.0',
+    scopes: ['global', 'local'],
+    destructive: true,
+    plan(ctx) {
+        const actions = [
+            ...collectActionsForLegacyRoot(ctx, 'commands/gsd', COMMANDS_GSD_REASON),
+            ...collectActionsForLegacyRoot(ctx, 'skills/gsd', SKILLS_GSD_REASON),
+        ];
+        return actions;
+    },
+};
+module.exports = migration;