@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/runtime-name-policy.cjs

@@ -0,0 +1,97 @@
+"use strict";
+/**
+ * Runtime name policy — alias resolution and canonicalization for GSD runtime
+ * identifiers (ADR-457 build-at-publish: the hand-written
+ * bin/lib/runtime-name-policy.cjs collapsed to a TypeScript source of truth).
+ * Behaviour is preserved byte-for-behaviour from the prior hand-written .cjs;
+ * only types are added.
+ *
+ * Group C cross-import candidate: no bin/lib sibling dependencies; only
+ * node:fs and node:path. Once this module is migrated, runtime-slash.cjs
+ * (which imports runtime-name-policy.cjs) becomes the first true cross-import
+ * proof candidate.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.canonicalizeRuntimeName = canonicalizeRuntimeName;
+exports.resolveRuntimeNameFromCandidates = resolveRuntimeNameFromCandidates;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const FALLBACK_ALIASES = {
+    claude: ['claude', 'claude-code', 'claude-cli'],
+    opencode: ['opencode', 'open-code', 'opencode-cli'],
+    kilo: ['kilo', 'kilo-cli'],
+    gemini: ['gemini', 'gemini-cli', 'gemini-code'],
+    codex: ['codex', 'codex-app', 'codex-cli', 'codex_desktop', 'codex-desktop'],
+    copilot: ['copilot', 'copilot-cli', 'github-copilot'],
+    antigravity: ['antigravity', 'antigravity-cli', 'antigravity-agent'],
+    cursor: ['cursor', 'cursor-cli', 'cursor-nightly'],
+    windsurf: ['windsurf', 'windsurf-cli', 'windsurf-next', 'devin-desktop'],
+    augment: ['augment', 'augment-code', 'augment-cli'],
+    trae: ['trae', 'trae-cli'],
+    qwen: ['qwen', 'qwen-code', 'qwen-cli'],
+    hermes: ['hermes', 'hermes-agent', 'hermes-cli'],
+    kimi: ['kimi'],
+    codebuddy: ['codebuddy', 'codebuddy-cli'],
+    cline: ['cline', 'cline-cli'],
+};
+function normalizeRuntimeToken(value) {
+    return String(value).trim().toLowerCase().replace(/[_\s]+/g, '-');
+}
+function loadAliasManifest() {
+    const manifestCandidates = [
+        node_path_1.default.resolve(__dirname, '..', 'shared', 'runtime-aliases.manifest.json'),
+        node_path_1.default.resolve(__dirname, '../../../sdk/shared/runtime-aliases.manifest.json'),
+    ];
+    for (const manifestPath of manifestCandidates) {
+        try {
+            const parsed = JSON.parse(node_fs_1.default.readFileSync(manifestPath, 'utf8'));
+            if (parsed && typeof parsed === 'object')
+                return parsed;
+        }
+        catch {
+            // Try next candidate.
+        }
+    }
+    return { ...FALLBACK_ALIASES };
+}
+const aliasManifest = loadAliasManifest();
+const aliasToCanonical = new Map();
+for (const [canonical, aliases] of Object.entries(aliasManifest)) {
+    if (typeof canonical !== 'string' || !Array.isArray(aliases))
+        continue;
+    aliasToCanonical.set(normalizeRuntimeToken(canonical), normalizeRuntimeToken(canonical));
+    for (const alias of aliases) {
+        if (typeof alias !== 'string')
+            continue;
+        aliasToCanonical.set(normalizeRuntimeToken(alias), normalizeRuntimeToken(canonical));
+    }
+}
+function canonicalizeRuntimeName(value) {
+    if (typeof value !== 'string')
+        return null;
+    return aliasToCanonical.get(normalizeRuntimeToken(value)) || null;
+}
+/**
+ * Resolve runtime from a precedence list of candidate values.
+ *
+ * - First non-empty string candidate wins.
+ * - Known aliases are canonicalized (codex-cli -> codex).
+ * - Unknown values are normalized and returned (future-runtime tolerance).
+ *
+ * @param candidates - string candidates in precedence order
+ * @returns the resolved runtime name, or null if no valid candidate
+ */
+function resolveRuntimeNameFromCandidates(...candidates) {
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'string')
+            continue;
+        const normalized = normalizeRuntimeToken(candidate);
+        if (!normalized)
+            continue;
+        return canonicalizeRuntimeName(normalized) || normalized;
+    }
+    return null;
+}

package/pp-core/bin/lib/runtime-slash.cjs

@@ -0,0 +1,137 @@
+"use strict";
+/**
+ * runtime-slash.cts — single source of truth for emitting pp slash-command
+ * references in user-facing runtime output (recommended-actions JSON, persisted
+ * ROADMAP.md entries, verify/validate fix hints, error messages, etc.).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/runtime-slash.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour from
+ * the prior hand-written .cjs; only types are added.
+ *
+ * Background: #2808 unified all pp-core skill installs to register under the hyphen
+ * form (`name: pp-<cmd>`). The legacy colon form `/pp:<cmd>` is no longer
+ * routable by Claude Code skill installs, but ~50 runtime emissions in
+ * bin/lib/*.cjs still hardcoded it (#3584). Codex installs need the shell-var
+ * `$pp-<cmd>` form. This module is the only place the runtime should decide
+ * which shape to emit.
+ *
+ *   - codex:                                   $pp-<cmd>   (shell-var syntax)
+ *   - claude, cursor, opencode, kilo, etc.:    /pp-<cmd>
+ *
+ * The colon form is never emitted.
+ *
+ * SOURCE CONTRACT: source command frontmatter uses `name: pp:<cmd>` (colon) and
+ * source prose uses `/pp:<cmd>` (colon). This module converts that colon source
+ * form into the INSTALLED hyphen form `/pp-<cmd>` (and codex `$pp-<cmd>`).
+ * Legacy `/gsd:` / `/gsd-` / `$gsd-` input is tolerated for backward compatibility
+ * while EMITTING only the pp form — satisfying RENAME-05.
+ *
+ * Cross-import proof candidate (ADR-457): this is the first TS source that
+ * imports a sibling TS-migrated module. The import specifier uses the .cjs
+ * extension per nodenext convention; tsc resolves it to src/runtime-name-policy.cts.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatPpSlashFor = exports.formatPpSlash = void 0;
+exports.formatGsdSlash = formatGsdSlash;
+exports.resolveRuntime = resolveRuntime;
+exports.formatGsdSlashFor = formatGsdSlashFor;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const runtime_name_policy_cjs_1 = require("./runtime-name-policy.cjs");
+function formatGsdSlash(commandName, runtime) {
+    if (typeof commandName !== 'string')
+        return commandName;
+    if (commandName === '')
+        return commandName;
+    // Strip any existing leading prefix so the helper is idempotent and accepts
+    // both canonical pp forms (`/pp:<name>`, `/pp-<name>`, `$pp-<name>`) and
+    // legacy gsd forms (`/gsd:<name>`, `/gsd-<name>`, `$gsd-<name>`) for
+    // backward compatibility. The bare shorthand forms (e.g. `pp:<name>`,
+    // `gsd:<name>`) are also accepted without a leading slash.
+    const stripped = commandName.replace(/^[/$]?(?:pp|gsd)[-:]/i, '');
+    // If the regex matched nothing (no prefix), the input is already a bare name.
+    const bare = stripped === commandName ? commandName : stripped;
+    // Defensive: a degenerate input like `/pp:`, `pp-`, `/gsd:`, `gsd-`, or whitespace-only
+    // normalizes to empty. Returning the original colon-form would re-emit the
+    // deprecated shape that this module exists to suppress (#3584). Return an
+    // empty string so callers see "no command" rather than the broken input.
+    if (bare === '' || bare.trim() === '')
+        return '';
+    // Split on the first whitespace so only the command token is rewritten —
+    // anything after the first space is caller-supplied arguments (phase
+    // numbers, --flags, --paths C:\\Users\\Me, etc.) that must round-trip
+    // untouched. Codex lowercases only the command token; preserving the
+    // argument tail prevents path/flag corruption on case-sensitive systems.
+    const wsMatch = bare.match(/^(\S+)(\s[\s\S]*)?$/);
+    const token = wsMatch ? wsMatch[1] : bare;
+    const tail = wsMatch && wsMatch[2] ? wsMatch[2] : '';
+    const runtimeText = (typeof runtime === 'string' && runtime ? runtime : 'claude').toLowerCase();
+    const rt = (0, runtime_name_policy_cjs_1.canonicalizeRuntimeName)(runtimeText) || runtimeText;
+    // Descriptor-driven: look up commandStyle from the capability registry.
+    // Mirrors the lazy-require pattern from runtime-homes.cts §getGlobalConfigDir.
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { runtimes } = require('./capability-registry.cjs');
+    const style = runtimes[rt]?.runtime?.commandStyle;
+    if (style === 'shell-var') {
+        // shell-var runtimes (currently: codex) use $pp-<cmd> syntax. The command
+        // token is lowercased because shell-var identifiers are conventionally
+        // lowercase; matches the convertCodexSlash() projection in bin/install.js.
+        return `$pp-${token.toLowerCase()}${tail}`;
+    }
+    return `/pp-${token}${tail}`;
+}
+/**
+ * Resolve the effective runtime for a project directory.
+ *
+ *   process.env.GSD_RUNTIME  >  config.runtime  >  'claude'
+ *
+ * Mirrors the precedence already used by profile-output.cjs and the rest of
+ * the runtime resolution chain. Returns a lowercased string so downstream
+ * comparisons can be case-blind.
+ *
+ * @param projectDir - path to the project directory, or null/undefined
+ * @returns the resolved runtime name
+ */
+function resolveRuntime(projectDir) {
+    const envRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(process.env['GSD_RUNTIME']);
+    if (envRuntime)
+        return envRuntime;
+    if (projectDir) {
+        try {
+            // Read config.json directly (not via loadConfig). loadConfig has a side
+            // effect of normalizing and re-writing legacy keys back to disk, which
+            // would mutate the project file just to read the runtime name. We only
+            // need the literal `runtime:` value, so a plain JSON read is sufficient
+            // and side-effect-free.
+            const configPath = node_path_1.default.join(projectDir, '.planning', 'config.json');
+            if (node_fs_1.default.existsSync(configPath)) {
+                const raw = node_fs_1.default.readFileSync(configPath, 'utf-8');
+                const parsed = JSON.parse(raw);
+                if (parsed && typeof parsed === 'object' && 'runtime' in parsed) {
+                    const configRuntime = (0, runtime_name_policy_cjs_1.resolveRuntimeNameFromCandidates)(parsed['runtime']);
+                    if (configRuntime)
+                        return configRuntime;
+                }
+            }
+        }
+        catch {
+            // Fall through to default — a missing/broken config must not crash
+            // runtime output formatting.
+        }
+    }
+    return 'claude';
+}
+/**
+ * Convenience: format using the runtime resolved from a project directory.
+ * Equivalent to `formatGsdSlash(name, resolveRuntime(projectDir))`.
+ */
+function formatGsdSlashFor(projectDir, commandName) {
+    return formatGsdSlash(commandName, resolveRuntime(projectDir));
+}
+// Back-compat alias — retained so existing consumers of `formatGsdSlash` continue to work.
+// Forwards to formatGsdSlash which now emits pp- forms.
+exports.formatPpSlash = formatGsdSlash;
+exports.formatPpSlashFor = formatGsdSlashFor;

package/pp-core/bin/lib/schema-detect.cjs

@@ -0,0 +1,159 @@
+"use strict";
+/**
+ * Schema Drift Detection — detects schema-relevant file changes and verifies
+ * that the appropriate database push command was executed during a phase
+ * (ADR-457 build-at-publish: the hand-written bin/lib/schema-detect.cjs
+ * collapsed to a TypeScript source of truth). Behaviour is preserved
+ * byte-for-behaviour from the prior hand-written .cjs; only types are added.
+ *
+ * This module does not read the filesystem directly.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ORM_INFO = exports.SCHEMA_PATTERNS = void 0;
+exports.detectSchemaFiles = detectSchemaFiles;
+exports.detectSchemaOrm = detectSchemaOrm;
+exports.checkSchemaDrift = checkSchemaDrift;
+exports.SCHEMA_PATTERNS = [
+    { pattern: /^src\/collections\/.*\.ts$/, orm: 'payload' },
+    { pattern: /^src\/globals\/.*\.ts$/, orm: 'payload' },
+    { pattern: /^prisma\/schema\.prisma$/, orm: 'prisma' },
+    { pattern: /^prisma\/schema\/.*\.prisma$/, orm: 'prisma' },
+    { pattern: /^drizzle\/schema\.ts$/, orm: 'drizzle' },
+    { pattern: /^src\/db\/schema\.ts$/, orm: 'drizzle' },
+    { pattern: /^drizzle\/.*\.ts$/, orm: 'drizzle' },
+    { pattern: /^supabase\/migrations\/.*\.sql$/, orm: 'supabase' },
+    { pattern: /^src\/entities\/.*\.ts$/, orm: 'typeorm' },
+    { pattern: /^src\/migrations\/.*\.ts$/, orm: 'typeorm' },
+];
+exports.ORM_INFO = {
+    payload: {
+        pushCommand: 'npx payload migrate',
+        envHint: 'CI=true PAYLOAD_MIGRATING=true npx payload migrate',
+        interactiveWarning: 'Payload migrate may require interactive prompts — use CI=true PAYLOAD_MIGRATING=true to suppress',
+        evidencePatterns: [/payload\s+migrate/i, /PAYLOAD_MIGRATING/],
+    },
+    prisma: {
+        pushCommand: 'npx prisma db push',
+        envHint: 'npx prisma db push --accept-data-loss (if destructive changes are intended)',
+        interactiveWarning: 'Prisma db push may prompt for confirmation on destructive changes — use --accept-data-loss to bypass',
+        evidencePatterns: [/prisma\s+db\s+push/i, /prisma\s+migrate\s+deploy/i, /prisma\s+migrate\s+dev/i],
+    },
+    drizzle: {
+        pushCommand: 'npx drizzle-kit push',
+        envHint: 'npx drizzle-kit push',
+        interactiveWarning: null,
+        evidencePatterns: [/drizzle-kit\s+push/i, /drizzle-kit\s+migrate/i],
+    },
+    supabase: {
+        pushCommand: 'supabase db push',
+        envHint: 'supabase db push',
+        interactiveWarning: 'Supabase db push may require authentication — ensure SUPABASE_ACCESS_TOKEN is set',
+        evidencePatterns: [/supabase\s+db\s+push/i, /supabase\s+migration\s+up/i],
+    },
+    typeorm: {
+        pushCommand: 'npx typeorm migration:run',
+        envHint: 'npx typeorm migration:run -d src/data-source.ts',
+        interactiveWarning: null,
+        evidencePatterns: [/typeorm\s+migration:run/i, /typeorm\s+schema:sync/i],
+    },
+};
+function detectSchemaFiles(files) {
+    const matches = [];
+    const orms = new Set();
+    for (const rawFile of files) {
+        const file = rawFile.replace(/\\/g, '/');
+        for (const { pattern, orm } of exports.SCHEMA_PATTERNS) {
+            if (pattern.test(file)) {
+                matches.push(rawFile);
+                orms.add(orm);
+                break;
+            }
+        }
+    }
+    return {
+        detected: matches.length > 0,
+        matches,
+        orms: [...orms],
+    };
+}
+function detectSchemaOrm(ormName) {
+    return exports.ORM_INFO[ormName] || null;
+}
+function checkSchemaDrift(changedFiles, executionLog, options = {}) {
+    const { skipCheck = false } = options;
+    const detection = detectSchemaFiles(changedFiles);
+    if (!detection.detected) {
+        return {
+            driftDetected: false,
+            blocking: false,
+            schemaFiles: [],
+            orms: [],
+            unpushedOrms: [],
+            message: '',
+        };
+    }
+    const pushedOrms = new Set();
+    const unpushedOrms = [];
+    for (const orm of detection.orms) {
+        const info = exports.ORM_INFO[orm];
+        if (!info)
+            continue;
+        const hasPushEvidence = info.evidencePatterns.some(p => p.test(executionLog));
+        if (hasPushEvidence) {
+            pushedOrms.add(orm);
+        }
+        else {
+            unpushedOrms.push(orm);
+        }
+    }
+    // Suppress unused variable warning — pushedOrms tracks for conceptual clarity
+    void pushedOrms;
+    const driftDetected = unpushedOrms.length > 0;
+    if (!driftDetected) {
+        return {
+            driftDetected: false,
+            blocking: false,
+            schemaFiles: detection.matches,
+            orms: detection.orms,
+            unpushedOrms: [],
+            message: '',
+        };
+    }
+    const pushCommands = unpushedOrms
+        .map(orm => {
+        const info = exports.ORM_INFO[orm];
+        return info ? `  ${orm}: ${info.envHint || info.pushCommand}` : null;
+    })
+        .filter((x) => x !== null)
+        .join('\n');
+    const message = [
+        'Schema drift detected: schema-relevant files changed but no database push was executed.',
+        '',
+        `Schema files changed: ${detection.matches.join(', ')}`,
+        `ORMs requiring push: ${unpushedOrms.join(', ')}`,
+        '',
+        'Required push commands:',
+        pushCommands,
+        '',
+        'Run the appropriate push command, or set GSD_SKIP_SCHEMA_CHECK=true to bypass this gate.',
+    ].join('\n');
+    if (skipCheck) {
+        return {
+            driftDetected: true,
+            blocking: false,
+            skipped: true,
+            schemaFiles: detection.matches,
+            orms: detection.orms,
+            unpushedOrms,
+            message: 'Schema drift detected but check was skipped (GSD_SKIP_SCHEMA_CHECK=true).',
+        };
+    }
+    return {
+        driftDetected: true,
+        blocking: true,
+        schemaFiles: detection.matches,
+        orms: detection.orms,
+        unpushedOrms,
+        message,
+    };
+}

package/pp-core/bin/lib/secrets.cjs

@@ -0,0 +1,34 @@
+"use strict";
+/**
+ * Secrets handling — masking convention for API keys and other
+ * credentials managed via /gsd-settings-integrations (ADR-457 build-at-publish:
+ * the hand-written bin/lib/secrets.cjs collapsed to a TypeScript source of
+ * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
+ * .cjs; only types are added.
+ *
+ * This module does not read the filesystem.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SECRET_CONFIG_KEYS = void 0;
+exports.isSecretKey = isSecretKey;
+exports.maskSecret = maskSecret;
+exports.maskIfSecret = maskIfSecret;
+exports.SECRET_CONFIG_KEYS = new Set([
+    'brave_search',
+    'firecrawl',
+    'exa_search',
+]);
+function isSecretKey(keyPath) {
+    return exports.SECRET_CONFIG_KEYS.has(keyPath);
+}
+function maskSecret(value) {
+    if (value === null || value === undefined || value === '')
+        return '(unset)';
+    const s = String(value);
+    if (s.length < 8)
+        return '****';
+    return '****' + s.slice(-4);
+}
+function maskIfSecret(keyPath, value) {
+    return isSecretKey(keyPath) ? maskSecret(value) : value;
+}