@pareto4/pp-core 1.5.0

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

@@ -0,0 +1,359 @@
+"use strict";
+/**
+ * UAT Audit — Cross-phase UAT/VERIFICATION scanner
+ *
+ * Reads all *-UAT.md and *-VERIFICATION.md files across all phases.
+ * Extracts non-passing items. Returns structured JSON for workflow consumption.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/uat.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only strict 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"));
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const io = require("./io.cjs");
+const { output, error } = io;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const roadmapParser = require("./roadmap-parser.cjs");
+const { getMilestonePhaseFilter } = roadmapParser;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const coreUtils = require("./core-utils.cjs");
+const { toPosixPath } = coreUtils;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const planningWorkspace = require("./planning-workspace.cjs");
+const { planningDir } = planningWorkspace;
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const frontmatter = require("./frontmatter.cjs");
+const { extractFrontmatter } = frontmatter;
+const security_cjs_1 = require("./security.cjs");
+// ─── cmdAuditUat ─────────────────────────────────────────────────────────────
+function cmdAuditUat(cwd, raw) {
+    const phasesDir = node_path_1.default.join(planningDir(cwd), 'phases');
+    if (!node_fs_1.default.existsSync(phasesDir)) {
+        error('No phases directory found in planning directory');
+    }
+    const isDirInMilestone = getMilestonePhaseFilter(cwd);
+    const results = [];
+    // Scan all phase directories
+    const dirs = node_fs_1.default.readdirSync(phasesDir, { withFileTypes: true })
+        .filter(e => e.isDirectory())
+        .map(e => e.name)
+        .filter(isDirInMilestone)
+        .sort();
+    for (const dir of dirs) {
+        const phaseMatch = dir.match(/^(\d+[A-Z]?(?:\.\d+)*)/i);
+        const phaseNum = phaseMatch ? phaseMatch[1] : dir;
+        const phaseDir = node_path_1.default.join(phasesDir, dir);
+        const files = node_fs_1.default.readdirSync(phaseDir);
+        // Process UAT files
+        for (const file of files.filter(f => f.includes('-UAT') && f.endsWith('.md'))) {
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, file), 'utf-8');
+            const items = parseUatItems(content);
+            if (items.length > 0) {
+                results.push({
+                    phase: phaseNum,
+                    phase_dir: dir,
+                    file,
+                    file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, file))),
+                    type: 'uat',
+                    status: (extractFrontmatter(content).status || 'unknown'),
+                    items,
+                });
+            }
+        }
+        // Process VERIFICATION files
+        for (const file of files.filter(f => f.includes('-VERIFICATION') && f.endsWith('.md'))) {
+            const content = node_fs_1.default.readFileSync(node_path_1.default.join(phaseDir, file), 'utf-8');
+            const status = extractFrontmatter(content).status || 'unknown';
+            if (status === 'human_needed' || status === 'gaps_found') {
+                const items = parseVerificationItems(content, status);
+                if (items.length > 0) {
+                    results.push({
+                        phase: phaseNum,
+                        phase_dir: dir,
+                        file,
+                        file_path: toPosixPath(node_path_1.default.relative(cwd, node_path_1.default.join(phaseDir, file))),
+                        type: 'verification',
+                        status,
+                        items,
+                    });
+                }
+            }
+        }
+    }
+    // Compute summary
+    const summary = {
+        total_files: results.length,
+        total_items: results.reduce((sum, r) => sum + r.items.length, 0),
+        by_category: {},
+        by_phase: {},
+    };
+    for (const r of results) {
+        if (!summary.by_phase[r.phase])
+            summary.by_phase[r.phase] = 0;
+        for (const item of r.items) {
+            summary.by_phase[r.phase]++;
+            const cat = item.category || 'unknown';
+            summary.by_category[cat] = (summary.by_category[cat] || 0) + 1;
+        }
+    }
+    output({ results, summary }, raw, undefined);
+}
+// ─── cmdRenderCheckpoint ──────────────────────────────────────────────────────
+function cmdRenderCheckpoint(cwd, options = {}, raw) {
+    const filePath = options.file;
+    if (!filePath) {
+        error('UAT file required: use uat render-checkpoint --file <path>');
+    }
+    const resolvedPath = (0, security_cjs_1.requireSafePath)(filePath, cwd, 'UAT file', { allowAbsolute: true });
+    if (!node_fs_1.default.existsSync(resolvedPath)) {
+        error(`UAT file not found: ${filePath}`);
+    }
+    const content = node_fs_1.default.readFileSync(resolvedPath, 'utf-8');
+    const currentTest = parseCurrentTest(content);
+    if (currentTest.complete) {
+        error('UAT session is already complete; no pending checkpoint to render');
+    }
+    const checkpoint = buildCheckpoint(currentTest);
+    output({
+        file_path: toPosixPath(node_path_1.default.relative(cwd, resolvedPath)),
+        test_number: currentTest.number,
+        test_name: currentTest.name,
+        checkpoint,
+    }, raw, checkpoint);
+}
+// ─── parseCurrentTest ─────────────────────────────────────────────────────────
+function parseCurrentTest(content) {
+    const currentTestMatch = content.match(/##\s*Current Test\s*(?:\n<!--[\s\S]*?-->)?\n([\s\S]*?)(?=\n##\s|$)/i);
+    if (!currentTestMatch) {
+        error('UAT file is missing a Current Test section');
+    }
+    const section = currentTestMatch[1].trimEnd();
+    if (!section.trim()) {
+        error('Current Test section is empty');
+    }
+    if (/\[testing complete\]/i.test(section)) {
+        return { complete: true };
+    }
+    const numberMatch = section.match(/^number:\s*(\d+)\s*$/m);
+    const nameMatch = section.match(/^name:\s*(.+)\s*$/m);
+    const expectedBlockMatch = section.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m)
+        || section.match(/^expected:\s*\|\n([\s\S]+)/m);
+    const expectedInlineMatch = section.match(/^expected:\s*(.+)\s*$/m);
+    if (!numberMatch || !nameMatch || (!expectedBlockMatch && !expectedInlineMatch)) {
+        if (!numberMatch && !nameMatch && !expectedBlockMatch && !expectedInlineMatch) {
+            const pendingTest = parseFirstPendingTest(content);
+            if (pendingTest) {
+                return pendingTest;
+            }
+            error('Current Test section is non-structured and no pending UAT test remains to resume');
+        }
+        error('Current Test section is malformed');
+    }
+    let expected;
+    if (expectedBlockMatch) {
+        expected = expectedBlockMatch[1]
+            .split('\n')
+            .map((line) => line.replace(/^ {2}/, ''))
+            .join('\n')
+            .trim();
+    }
+    else {
+        expected = expectedInlineMatch[1].trim();
+    }
+    return {
+        complete: false,
+        number: parseInt(numberMatch[1], 10),
+        name: (0, security_cjs_1.sanitizeForDisplay)(nameMatch[1].trim()),
+        expected: (0, security_cjs_1.sanitizeForDisplay)(expected),
+    };
+}
+function parseFirstPendingTest(content) {
+    const testsMatch = content.match(/##\s*Tests\s*\n([\s\S]*?)(?=\n##\s|$)/i);
+    if (!testsMatch) {
+        return null;
+    }
+    const testsSection = testsMatch[1];
+    const headingPattern = /^###\s*(\d+)\.\s*([^\n]+)\s*$/gm;
+    const headings = [];
+    let headingMatch;
+    while ((headingMatch = headingPattern.exec(testsSection)) !== null) {
+        headings.push({
+            index: headingMatch.index,
+            number: parseInt(headingMatch[1], 10),
+            name: headingMatch[2].trim(),
+        });
+    }
+    for (let i = 0; i < headings.length; i += 1) {
+        const current = headings[i];
+        const next = headings[i + 1];
+        const block = testsSection.slice(current.index, next ? next.index : undefined);
+        if (!/^result:\s*\[?pending\]?\s*$/im.test(block)) {
+            continue;
+        }
+        const expected = parseExpectedFromTestBlock(block);
+        if (!expected) {
+            error(`Pending UAT test ${current.number} is missing an expected field`);
+        }
+        return {
+            complete: false,
+            number: current.number,
+            name: (0, security_cjs_1.sanitizeForDisplay)(current.name),
+            expected: (0, security_cjs_1.sanitizeForDisplay)(expected),
+        };
+    }
+    return null;
+}
+function parseExpectedFromTestBlock(block) {
+    const expectedBlockMatch = block.match(/^expected:\s*\|\n([\s\S]*?)(?=^\w[\w-]*:\s)/m)
+        || block.match(/^expected:\s*\|\n([\s\S]+)/m);
+    if (expectedBlockMatch) {
+        return expectedBlockMatch[1]
+            .split('\n')
+            .map((line) => line.replace(/^ {2}/, ''))
+            .join('\n')
+            .trim();
+    }
+    const expectedInlineMatch = block.match(/^expected:\s*(.+)\s*$/m);
+    return expectedInlineMatch ? expectedInlineMatch[1].trim() : null;
+}
+// ─── buildCheckpoint ──────────────────────────────────────────────────────────
+function buildCheckpoint(currentTest) {
+    return [
+        '╔══════════════════════════════════════════════════════════════╗',
+        '║  CHECKPOINT: Verification Required                           ║',
+        '╚══════════════════════════════════════════════════════════════╝',
+        '',
+        `**Test ${currentTest.number}: ${currentTest.name}**`,
+        '',
+        currentTest.expected,
+        '',
+        '──────────────────────────────────────────────────────────────',
+        'Type `pass` or describe what\'s wrong.',
+        '──────────────────────────────────────────────────────────────',
+    ].join('\n');
+}
+// ─── parseUatItems ────────────────────────────────────────────────────────────
+function parseUatItems(content) {
+    const items = [];
+    // Match test blocks: ### N. Name\nexpected: ...\nresult: ...\n
+    // Accept both bare (result: pending) and bracketed (result: [pending]) formats (#2273)
+    const testPattern = /###\s*(\d+)\.\s*([^\n]+)\nexpected:\s*([^\n]+)\nresult:\s*\[?(\w+)\]?(?:\n(?:reported|reason|blocked_by):\s*[^\n]*)?/g;
+    let match;
+    while ((match = testPattern.exec(content)) !== null) {
+        const [, num, name, expected, result] = match;
+        if (result === 'pending' || result === 'skipped' || result === 'blocked') {
+            // Extract optional fields — limit to current test block (up to next ### or EOF)
+            const afterMatch = content.slice(match.index);
+            const nextHeading = afterMatch.indexOf('\n###', 1);
+            const blockText = nextHeading > 0 ? afterMatch.slice(0, nextHeading) : afterMatch;
+            const reasonMatch = blockText.match(/reason:\s*(.+)/);
+            const blockedByMatch = blockText.match(/blocked_by:\s*(.+)/);
+            const item = {
+                test: parseInt(num, 10),
+                name: name.trim(),
+                expected: expected.trim(),
+                result,
+                category: categorizeItem(result, reasonMatch?.[1], blockedByMatch?.[1]),
+            };
+            if (reasonMatch)
+                item.reason = reasonMatch[1].trim();
+            if (blockedByMatch)
+                item.blocked_by = blockedByMatch[1].trim();
+            items.push(item);
+        }
+    }
+    return items;
+}
+// ─── parseVerificationItems ───────────────────────────────────────────────────
+function parseVerificationItems(content, status) {
+    const items = [];
+    if (status === 'human_needed') {
+        // Extract from human_verification section — look for numbered items or table rows
+        const hvSection = content.match(/##\s*Human Verification.*?\n([\s\S]*?)(?=\n##\s|\n---\s|$)/i);
+        if (hvSection) {
+            const lines = hvSection[1].split('\n');
+            for (const line of lines) {
+                // Match table rows: | N | description | ... |
+                const tableMatch = line.match(/\|\s*(\d+)\s*\|\s*([^|]+)/);
+                // Match bullet items: - description
+                const bulletMatch = line.match(/^[-*]\s+(.+)/);
+                // Match numbered items: 1. description
+                const numberedMatch = line.match(/^(\d+)\.\s+(.+)/);
+                if (tableMatch) {
+                    // Skip rows that already have a passing result (PASS, pass, resolved, etc.)
+                    const rowRemainder = line.slice(tableMatch.index + tableMatch[0].length);
+                    const cellValues = rowRemainder.split('|').map(c => c.trim());
+                    const hasPassResult = cellValues.some(c => /^pass$/i.test(c) || /^resolved$/i.test(c));
+                    if (hasPassResult)
+                        continue;
+                    items.push({
+                        test: parseInt(tableMatch[1], 10),
+                        name: tableMatch[2].trim(),
+                        result: 'human_needed',
+                        category: 'human_uat',
+                    });
+                }
+                else if (numberedMatch) {
+                    items.push({
+                        test: parseInt(numberedMatch[1], 10),
+                        name: numberedMatch[2].trim(),
+                        result: 'human_needed',
+                        category: 'human_uat',
+                    });
+                }
+                else if (bulletMatch && bulletMatch[1].length > 10) {
+                    items.push({
+                        name: bulletMatch[1].trim(),
+                        result: 'human_needed',
+                        category: 'human_uat',
+                    });
+                }
+            }
+        }
+    }
+    // gaps_found items are already handled by plan-phase --gaps pipeline
+    return items;
+}
+// ─── categorizeItem ───────────────────────────────────────────────────────────
+function categorizeItem(result, reason, blockedBy) {
+    if (result === 'blocked' || blockedBy) {
+        if (blockedBy) {
+            if (/server/i.test(blockedBy))
+                return 'server_blocked';
+            if (/device|physical/i.test(blockedBy))
+                return 'device_needed';
+            if (/build|release|preview/i.test(blockedBy))
+                return 'build_needed';
+            if (/third.party|twilio|stripe/i.test(blockedBy))
+                return 'third_party';
+        }
+        return 'blocked';
+    }
+    if (result === 'skipped') {
+        if (reason) {
+            if (/server|not running|not available/i.test(reason))
+                return 'server_blocked';
+            if (/simulator|physical|device/i.test(reason))
+                return 'device_needed';
+            if (/build|release|preview/i.test(reason))
+                return 'build_needed';
+        }
+        return 'skipped_unresolved';
+    }
+    if (result === 'pending')
+        return 'pending';
+    if (result === 'human_needed')
+        return 'human_uat';
+    return 'unknown';
+}
+module.exports = {
+    cmdAuditUat,
+    cmdRenderCheckpoint,
+    parseCurrentTest,
+    buildCheckpoint,
+};

package/pp-core/bin/lib/ui-safety-gate.cjs

@@ -0,0 +1,98 @@
+"use strict";
+/**
+ * UI Safety Gate — shell-free implementation (ADR-457 build-at-publish: the
+ * hand-written bin/lib/ui-safety-gate.cjs collapsed to a TypeScript source of
+ * truth). Behaviour is preserved byte-for-behaviour from the prior hand-written
+ * .cjs; only types are added.
+ *
+ * Replaces the bash shell-based one-liner that silently degraded on Windows
+ * PowerShell / cmd.exe because the locale env-var prefix was not recognised.
+ * This module runs inside Node.js — no shell dependency, works identically
+ * on bash, Git-Bash, PowerShell, and cmd.exe.
+ *
+ * Word-boundary anchoring:
+ *   (^|[^a-zA-Z0-9])(TOKEN)([^a-zA-Z0-9]|$)
+ * Equivalent to POSIX ERE [^[:alnum:]] — matches tokens only when they are not
+ * interior substrings of alphanumeric compound words (e.g. "microfrontend" is NOT
+ * matched; "micro-frontend" and "micro frontend" ARE matched).
+ *
+ * Public API:
+ *   checkUiPresence(text: string): { hasUI: boolean, tokens: string[] }
+ *
+ * CLI usage — reads phase-section text from STDIN to avoid ARG_MAX limits:
+ *   echo "$PHASE_SECTION" | node gsd-core/bin/lib/ui-safety-gate.cjs
+ *   echo $?   → 0 if UI tokens found, 1 if not, 2 on usage error
+ *
+ * Exit codes mirror grep: 0 = match found, 1 = no match, 2 = usage error.
+ *
+ * Canonical location: gsd-core/bin/lib/ui-safety-gate.cjs (#448)
+ * This path is deployed by the GSD installer to $RUNTIME_DIR/gsd-core/bin/lib/.
+ * bin/lib/ui-safety-gate.cjs (root) is retained for source-repo and npm usage.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UI_TOKENS = void 0;
+exports.checkUiPresence = checkUiPresence;
+exports.UI_TOKENS = [
+    'UI',
+    'interface',
+    'frontend',
+    'component',
+    'layout',
+    'page',
+    'screen',
+    'view',
+    'form',
+    'dashboard',
+    'widget',
+];
+/**
+ * Built once at module load — no per-call compilation overhead.
+ * ASCII word boundaries — matches the original ASCII-grep intent of #3706.
+ * Note: JS [a-zA-Z0-9] is ASCII-only and NOT equivalent to POSIX [[:alnum:]],
+ * which is locale-sensitive and includes accented characters.
+ */
+const UI_GATE_PATTERN = new RegExp('(^|[^a-zA-Z0-9])(' + exports.UI_TOKENS.join('|') + ')([^a-zA-Z0-9]|$)', 'i');
+// Global-flagged variant for extracting ALL matches per line (matchAll).
+const UI_GATE_PATTERN_GLOBAL = new RegExp(UI_GATE_PATTERN.source, 'gi');
+/**
+ * Check a roadmap phase section string for frontend UI indicators.
+ *
+ * @param text - The roadmap phase section content (may be multi-line, CRLF or LF).
+ * @returns hasUI — true if any UI token was matched as a standalone word;
+ *          tokens — matched token strings (lowercased), deduplicated.
+ */
+function checkUiPresence(text) {
+    if (typeof text !== 'string') {
+        return { hasUI: false, tokens: [] };
+    }
+    // Normalise CRLF so the pattern sees consistent line boundaries.
+    const normalised = text.replace(/\r\n/g, '\n');
+    const found = new Set();
+    for (const line of normalised.split('\n')) {
+        // Reset lastIndex before each line so the global pattern restarts from 0.
+        UI_GATE_PATTERN_GLOBAL.lastIndex = 0;
+        for (const m of line.matchAll(UI_GATE_PATTERN_GLOBAL)) {
+            found.add(m[2].toLowerCase());
+        }
+    }
+    return { hasUI: found.size > 0, tokens: [...found] };
+}
+// ── CLI entry point ─────────────────────────────────────────────────────────
+// Reads phase-section text from STDIN (not argv) to avoid OS ARG_MAX limits.
+// Invoked by workflow .md bash blocks as: echo "$PHASE_SECTION" | node .../ui-safety-gate.cjs
+// Exit 0 = UI found, 1 = no UI, 2 = startup error.
+if (require.main === module) {
+    // Collect stdin chunks asynchronously.
+    const chunks = [];
+    process.stdin.setEncoding('utf-8');
+    process.stdin.on('data', (chunk) => chunks.push(chunk));
+    process.stdin.on('end', () => {
+        const input = chunks.join('');
+        const result = checkUiPresence(input);
+        process.exit(result.hasUI ? 0 : 1);
+    });
+    process.stdin.on('error', (err) => {
+        process.stderr.write(`ERROR: ui-safety-gate.cjs stdin read failed: ${err.message}\n`);
+        process.exit(2);
+    });
+}

package/pp-core/bin/lib/update-context.cjs

@@ -0,0 +1,221 @@
+"use strict";
+/**
+ * Update-context resolver (issue #498, candidate 3).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/update-context.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 };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_DIRS = void 0;
+exports.inferPreferredRuntime = inferPreferredRuntime;
+exports.envRuntimeDirs = envRuntimeDirs;
+exports.resolveUpdateContext = resolveUpdateContext;
+exports.loadUpdateContext = loadUpdateContext;
+const node_path_1 = __importDefault(require("node:path"));
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_os_1 = __importDefault(require("node:os"));
+// Runtime -> candidate relative dir. Order matters: it is the probe order, and
+// mirrors the RUNTIME_DIRS array the bash used (a runtime may have several
+// candidate dirs). Kept here, not derived from the installer's getDirName,
+// because update detection probes ALL historical dirs per runtime.
+exports.RUNTIME_DIRS = [
+    ['claude', '.claude'],
+    ['opencode', '.config/opencode'],
+    ['opencode', '.opencode'],
+    ['antigravity', '.gemini/antigravity-ide'],
+    ['antigravity', '.gemini/antigravity-cli'],
+    ['antigravity', '.gemini/antigravity'],
+    ['antigravity', '.agents'], // local Antigravity install dir canonical (#791; bin/install.js getDirName('antigravity'))
+    ['antigravity', '.agent'], // local Antigravity install dir legacy (#503; backward-compat with pre-#791 installs)
+    ['windsurf', '.devin'], // local Windsurf/Devin Desktop install dir canonical (#1085; bin/install.js getDirName('windsurf'))
+    ['windsurf', '.windsurf'], // local Windsurf install dir legacy (#1085; backward-compat with pre-#1085 installs)
+    ['gemini', '.gemini'],
+    ['kilo', '.config/kilo'],
+    ['kilo', '.kilo'],
+    ['codex', '.codex'],
+];
+const SEMVER_PREFIX = /^\d+\.\d+\.\d+/;
+function expandHome(p, home) {
+    if (!p)
+        return '';
+    return p.startsWith('~/') ? node_path_1.default.join(home, p.slice(2)) : p;
+}
+function versionFile(dir) { return node_path_1.default.join(dir, 'pp-core', 'VERSION'); }
+function markerFile(dir) { return node_path_1.default.join(dir, 'pp-core', 'workflows', 'update.md'); }
+// Detection: a dir "has GSD" if it carries a VERSION file or the update.md
+// workflow marker.
+function hasInstall(fs, dir) {
+    return fs.exists(versionFile(dir)) || fs.exists(markerFile(dir));
+}
+// Read VERSION at dir; return a trimmed semver string, or null if missing/invalid.
+function validVersionAt(fs, dir) {
+    const raw = fs.readFile(versionFile(dir));
+    if (raw == null)
+        return null;
+    const trimmed = String(raw).trim();
+    return SEMVER_PREFIX.test(trimmed) ? trimmed : null;
+}
+// A version is TRUSTED only when BOTH the VERSION file and the update.md marker
+// exist (and VERSION is valid semver).
+function trustedVersionAt(fs, dir) {
+    return dir && fs.exists(markerFile(dir)) ? validVersionAt(fs, dir) : null;
+}
+// Infer the preferred runtime from preferredConfigDir config files, then env.
+function inferPreferredRuntime({ fs, env, preferredConfigDir }) {
+    if (preferredConfigDir) {
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'kilo.json')) ||
+            fs.exists(node_path_1.default.join(preferredConfigDir, 'kilo.jsonc')))
+            return 'kilo';
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'opencode.json')) ||
+            fs.exists(node_path_1.default.join(preferredConfigDir, 'opencode.jsonc')))
+            return 'opencode';
+        if (fs.exists(node_path_1.default.join(preferredConfigDir, 'config.toml')))
+            return 'codex';
+    }
+    if (env['CODEX_HOME'])
+        return 'codex';
+    if (env['ANTIGRAVITY_CONFIG_DIR'])
+        return 'antigravity';
+    if (env['GEMINI_CONFIG_DIR'])
+        return 'gemini';
+    if (env['KILO_CONFIG_DIR'] || env['KILO_CONFIG'])
+        return 'kilo';
+    if (env['OPENCODE_CONFIG_DIR'] || env['OPENCODE_CONFIG'])
+        return 'opencode';
+    if (env['CLAUDE_CONFIG_DIR'])
+        return 'claude';
+    return 'claude';
+}
+// Absolute env-override candidates, mirroring the bash ENV_RUNTIME_DIRS block.
+function envRuntimeDirs({ env, home }) {
+    const out = [];
+    const ex = (v) => expandHome(v, home);
+    if (env['CLAUDE_CONFIG_DIR'])
+        out.push(['claude', ex(env['CLAUDE_CONFIG_DIR'])]);
+    if (env['ANTIGRAVITY_CONFIG_DIR'])
+        out.push(['antigravity', ex(env['ANTIGRAVITY_CONFIG_DIR'])]);
+    if (env['GEMINI_CONFIG_DIR'])
+        out.push(['gemini', ex(env['GEMINI_CONFIG_DIR'])]);
+    if (env['KILO_CONFIG_DIR'])
+        out.push(['kilo', ex(env['KILO_CONFIG_DIR'])]);
+    else if (env['KILO_CONFIG'])
+        out.push(['kilo', node_path_1.default.dirname(ex(env['KILO_CONFIG']))]);
+    else if (env['XDG_CONFIG_HOME'])
+        out.push(['kilo', node_path_1.default.join(ex(env['XDG_CONFIG_HOME']), 'kilo')]);
+    if (env['OPENCODE_CONFIG_DIR'])
+        out.push(['opencode', ex(env['OPENCODE_CONFIG_DIR'])]);
+    else if (env['OPENCODE_CONFIG'])
+        out.push(['opencode', node_path_1.default.dirname(ex(env['OPENCODE_CONFIG']))]);
+    else if (env['XDG_CONFIG_HOME'])
+        out.push(['opencode', node_path_1.default.join(ex(env['XDG_CONFIG_HOME']), 'opencode')]);
+    if (env['CODEX_HOME'])
+        out.push(['codex', ex(env['CODEX_HOME'])]);
+    return out;
+}
+// Stable reorder: entries whose runtime === preferred first, original order kept.
+function preferFirst(entries, preferred) {
+    const pref = entries.filter(([rt]) => rt === preferred);
+    const rest = entries.filter(([rt]) => rt !== preferred);
+    return [...pref, ...rest];
+}
+/**
+ * Pure resolver. Returns { installedVersion, scope, runtime, gsdDir }.
+ */
+function resolveUpdateContext({ home, cwd, env = {}, fs, preferredConfigDir = '', preferredRuntime = '', }) {
+    // Expand a leading `~/` before any probe.
+    preferredConfigDir = expandHome(preferredConfigDir, home);
+    const preferred = preferredRuntime || inferPreferredRuntime({ fs, env, preferredConfigDir });
+    // Fast path: a validated preferredConfigDir (custom --config-dir install).
+    if (preferredConfigDir && hasInstall(fs, preferredConfigDir)) {
+        const resolvedPref = node_path_1.default.resolve(preferredConfigDir);
+        let scope = 'GLOBAL';
+        for (const [, reldir] of exports.RUNTIME_DIRS) {
+            if (node_path_1.default.resolve(cwd, reldir) === resolvedPref) {
+                scope = 'LOCAL';
+                break;
+            }
+        }
+        return {
+            installedVersion: trustedVersionAt(fs, preferredConfigDir) ?? '0.0.0',
+            scope,
+            runtime: preferred,
+            gsdDir: preferredConfigDir,
+        };
+    }
+    const orderedEnv = preferFirst(envRuntimeDirs({ env, home }), preferred);
+    const orderedRuntime = preferFirst(exports.RUNTIME_DIRS, preferred);
+    // LOCAL probe (relative to cwd).
+    let localRuntime = '', localDir = '';
+    for (const [rt, reldir] of orderedRuntime) {
+        const cand = node_path_1.default.resolve(cwd, reldir);
+        if (hasInstall(fs, cand)) {
+            localRuntime = rt;
+            localDir = cand;
+            break;
+        }
+    }
+    // GLOBAL probe: absolute env candidates first, then $HOME-relative.
+    let globalRuntime = '', globalDir = '';
+    for (const [rt, absdir] of orderedEnv) {
+        if (hasInstall(fs, absdir)) {
+            globalRuntime = rt;
+            globalDir = node_path_1.default.resolve(absdir);
+            break;
+        }
+    }
+    if (!globalRuntime) {
+        for (const [rt, reldir] of orderedRuntime) {
+            const cand = node_path_1.default.resolve(home, reldir);
+            if (hasInstall(fs, cand)) {
+                globalRuntime = rt;
+                globalDir = cand;
+                break;
+            }
+        }
+    }
+    const localValid = trustedVersionAt(fs, localDir);
+    const isLocal = !!localValid && (!globalDir || localDir !== globalDir);
+    if (isLocal) {
+        return { installedVersion: localValid, scope: 'LOCAL', runtime: localRuntime, gsdDir: localDir };
+    }
+    const globalValid = trustedVersionAt(fs, globalDir);
+    if (globalValid) {
+        return { installedVersion: globalValid, scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
+    }
+    // A runtime dir was detected (VERSION or marker present) but is not a
+    // complete, valid install: keep scope/runtime/dir and report 0.0.0 so the
+    // caller re-installs.
+    if (localRuntime && (!globalDir || localDir !== globalDir)) {
+        return { installedVersion: '0.0.0', scope: 'LOCAL', runtime: localRuntime, gsdDir: localDir };
+    }
+    if (globalRuntime) {
+        return { installedVersion: '0.0.0', scope: 'GLOBAL', runtime: globalRuntime, gsdDir: globalDir };
+    }
+    return { installedVersion: '0.0.0', scope: 'UNKNOWN', runtime: 'claude', gsdDir: '' };
+}
+/**
+ * CLI wiring: resolve against the real filesystem.
+ */
+function loadUpdateContext(opts = {}) {
+    const fs = {
+        exists: (p) => node_fs_1.default.existsSync(p),
+        readFile: (p) => { try {
+            return node_fs_1.default.readFileSync(p, 'utf8');
+        }
+        catch {
+            return null;
+        } },
+    };
+    return resolveUpdateContext({
+        home: opts.home ?? node_os_1.default.homedir(),
+        cwd: opts.cwd ?? process.cwd(),
+        env: opts.env ?? process.env,
+        fs,
+        preferredConfigDir: opts.preferredConfigDir ?? '',
+        preferredRuntime: opts.preferredRuntime ?? '',
+    });
+}