@pareto4/pp-core 1.5.0

package/pp-core/bin/lib/state-command-router.cjs

@@ -0,0 +1,172 @@
+"use strict";
+/**
+ * Manifest-backed state subcommand router.
+ * Keeps gsd-tools.cjs thin while preserving existing command semantics.
+ *
+ * Phase 5.1: handlers that have SDK equivalents are dispatched via
+ * executeForCjs (the sync bridge). CJS fallback is retained for:
+ * - complete-phase: no SDK counterpart.
+ * - Any command when GSD_WORKSTREAM is active (GSDTransport forces subprocess
+ *   for workstream requests; subprocess is disabled in the sync bridge worker).
+ * - Any command when the SDK is not available (build not present).
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/state-command-router.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 command_aliases_cjs_1 = require("./command-aliases.cjs");
+// eslint-disable-next-line @typescript-eslint/no-require-imports
+const cjsCommandRouterAdapter = require("./cjs-command-router-adapter.cjs");
+const { routeHubCommandFamily } = cjsCommandRouterAdapter;
+const command_arg_projection_cjs_1 = require("./command-arg-projection.cjs");
+// ─── Types ────────────────────────────────────────────────────────────────────
+// Helper: extract string-only named arg value (value flags never return boolean).
+function strArg(opts, key) {
+    const v = opts[key];
+    if (typeof v === 'boolean')
+        return undefined;
+    return v;
+}
+// ─── Implementation ───────────────────────────────────────────────────────────
+function routeStateCommand({ state, args, cwd, raw, error }) {
+    const parsePlans = (plans) => {
+        const parsedPlans = plans == null ? null : Number.parseInt(plans, 10);
+        if (plans != null && Number.isNaN(parsedPlans)) {
+            error('Invalid --plans value. Expected an integer.');
+            return null;
+        }
+        return parsedPlans;
+    };
+    routeHubCommandFamily({
+        family: 'state',
+        args,
+        subcommands: ['load', 'complete-phase', ...command_aliases_cjs_1.STATE_SUBCOMMANDS.filter((s) => s !== 'load')],
+        defaultSubcommand: 'load',
+        // No SDK-only state subcommands remain: add-roadmap-evolution was the last
+        // holdout after the SDK retirement (ADR-0174) and is now implemented in CJS
+        // (handler below). See #1140.
+        unsupported: {},
+        error,
+        cwd,
+        raw,
+        unknownMessage: (subcommand, available) => `Unknown state subcommand: "${subcommand}". Available: ${available.join(', ')}`,
+        handlers: {
+            load: () => state.cmdStateLoad(cwd, raw),
+            json: () => state.cmdStateJson(cwd, raw),
+            get: () => state.cmdStateGet(cwd, args[2], raw),
+            update: () => state.cmdStateUpdate(cwd, args[2], args[3]),
+            patch: () => {
+                const patches = {};
+                if (args.length === 3 && typeof args[2] === 'string' && args[2].trim().startsWith('{')) {
+                    let parsed;
+                    try {
+                        parsed = JSON.parse(args[2]);
+                    }
+                    catch (err) {
+                        error(`state patch: invalid JSON object: ${err.message}`);
+                        return;
+                    }
+                    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+                        error('state patch: JSON input must be an object of field/value pairs.');
+                        return;
+                    }
+                    for (const [key, value] of Object.entries(parsed)) {
+                        if (key && value !== undefined) {
+                            // eslint-disable-next-line @typescript-eslint/no-base-to-string
+                            patches[key] = String(value);
+                        }
+                    }
+                }
+                else {
+                    for (let i = 2; i < args.length; i += 2) {
+                        const key = args[i].replace(/^--/, '');
+                        const value = args[i + 1];
+                        if (key && value !== undefined) {
+                            patches[key] = value;
+                        }
+                    }
+                }
+                state.cmdStatePatch(cwd, patches, raw);
+            },
+            'advance-plan': () => state.cmdStateAdvancePlan(cwd, raw),
+            'record-metric': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'plan', 'duration', 'tasks', 'files']);
+                state.cmdStateRecordMetric(cwd, {
+                    phase: strArg(a, 'phase'),
+                    plan: strArg(a, 'plan'),
+                    duration: strArg(a, 'duration'),
+                    tasks: strArg(a, 'tasks'),
+                    files: strArg(a, 'files'),
+                }, raw);
+            },
+            'update-progress': () => state.cmdStateUpdateProgress(cwd, raw),
+            'add-decision': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'summary', 'summary-file', 'rationale', 'rationale-file']);
+                state.cmdStateAddDecision(cwd, {
+                    phase: strArg(a, 'phase'),
+                    summary: strArg(a, 'summary'),
+                    summary_file: strArg(a, 'summary-file'),
+                    rationale: strArg(a, 'rationale') || '',
+                    rationale_file: strArg(a, 'rationale-file'),
+                }, raw);
+            },
+            'add-blocker': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text', 'text-file']);
+                state.cmdStateAddBlocker(cwd, { text: strArg(a, 'text'), text_file: strArg(a, 'text-file') }, raw);
+            },
+            'add-roadmap-evolution': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'action', 'after', 'note', 'note-file'], ['urgent']);
+                state.cmdStateAddRoadmapEvolution(cwd, {
+                    phase: strArg(a, 'phase'),
+                    action: strArg(a, 'action'),
+                    after: strArg(a, 'after'),
+                    note: strArg(a, 'note'),
+                    note_file: strArg(a, 'note-file'),
+                    urgent: a['urgent'] === true,
+                }, raw);
+            },
+            'resolve-blocker': () => state.cmdStateResolveBlocker(cwd, strArg((0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['text']), 'text'), raw),
+            'record-session': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['stopped-at', 'resume-file']);
+                // Pass resume_file as-is (undefined when --resume-file was not provided) so
+                // cmdStateRecordSession can distinguish "caller explicitly passed a value" from
+                // "option was not supplied" and apply the template-default-only replacement guard.
+                state.cmdStateRecordSession(cwd, { stopped_at: strArg(a, 'stopped-at'), resume_file: strArg(a, 'resume-file') }, raw);
+            },
+            'begin-phase': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                state.cmdStateBeginPhase(cwd, strArg(a, 'phase'), strArg(a, 'name'), parsePlans(strArg(a, 'plans')), raw);
+            },
+            'signal-waiting': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['type', 'question', 'options', 'phase']);
+                state.cmdSignalWaiting(cwd, strArg(a, 'type'), strArg(a, 'question'), strArg(a, 'options'), strArg(a, 'phase'), raw);
+            },
+            'signal-resume': () => state.cmdSignalResume(cwd, raw),
+            'planned-phase': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase', 'name', 'plans']);
+                state.cmdStatePlannedPhase(cwd, strArg(a, 'phase'), parsePlans(strArg(a, 'plans')), raw);
+            },
+            validate: () => state.cmdStateValidate(cwd, raw),
+            sync: () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, [], ['verify']);
+                state.cmdStateSync(cwd, { verify: a['verify'] }, raw);
+            },
+            prune: () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['keep-recent'], ['dry-run']);
+                state.cmdStatePrune(cwd, { keepRecent: strArg(a, 'keep-recent') || '3', dryRun: a['dry-run'] === true }, raw);
+            },
+            // complete-phase: CJS-only — no SDK counterpart.
+            'complete-phase': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['phase']);
+                state.cmdStateCompletePhase(cwd, raw, strArg(a, 'phase') || args[2]);
+            },
+            'milestone-switch': () => {
+                const a = (0, command_arg_projection_cjs_1.parseNamedArgs)(args, ['milestone', 'name']);
+                state.cmdStateMilestoneSwitch(cwd, strArg(a, 'milestone'), strArg(a, 'name'), raw);
+            },
+        },
+    });
+}
+module.exports = {
+    routeStateCommand,
+};

package/pp-core/bin/lib/state-document.cjs

@@ -0,0 +1,312 @@
+"use strict";
+/**
+ * STATE.md Document Module — pure transforms for STATE.md text.
+ * This module does not read the filesystem and does not own persistence or locking.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/state-document.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_STATUS_PATTERNS = exports.KNOWN_TEMPLATE_DEFAULTS = void 0;
+exports.stateExtractField = stateExtractField;
+exports.stateReplaceField = stateReplaceField;
+exports.stateReplaceFieldWithFallback = stateReplaceFieldWithFallback;
+exports.normalizeStateStatus = normalizeStateStatus;
+exports.computeProgressPercent = computeProgressPercent;
+exports.shouldPreserveExistingProgress = shouldPreserveExistingProgress;
+exports.normalizeProgressNumbers = normalizeProgressNumbers;
+exports.isStateTemplateDefault = isStateTemplateDefault;
+exports.stateReplaceFieldIfTemplate = stateReplaceFieldIfTemplate;
+// Internal helpers
+function escapeRegex(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function toFiniteNumber(value) {
+    const number = Number(value);
+    return Number.isFinite(number) ? number : null;
+}
+function existingProgressExceedsDerived(existingProgress, derivedProgress, key) {
+    const existing = toFiniteNumber(existingProgress[key]);
+    const derived = toFiniteNumber(derivedProgress[key]);
+    return existing !== null && derived !== null && existing > derived;
+}
+/**
+ * Return true if a pipe-table row's first cell is a separator cell (`---`
+ * variants) rather than a field name.  Prevents the separator row
+ * `| --- | --- |` from being treated as a field named "---".
+ */
+function isTableSeparatorRow(firstCell) {
+    // A separator cell contains only dashes, colons (alignment hints), and whitespace.
+    return /^[\s\-:]+$/.test(firstCell.trim());
+}
+/**
+ * Build a regex that matches a pipe-table row `| FieldName | value |` for the
+ * given (already-escaped) field name.  The match is case-insensitive and
+ * tolerates variable amounts of whitespace around the cell contents.
+ *
+ * Capture group 1: leading pipe + whitespace before the field cell
+ * Capture group 2: the field name cell text (trimmed)
+ * Capture group 3: whitespace between field cell and separator pipe
+ * Capture group 4: the value cell text (trimmed)
+ * Capture group 5: trailing whitespace + closing pipe(s)
+ *
+ * We use a single-line match (`m` flag so ^ anchors work on each line) to
+ * avoid cross-row replacement.
+ */
+function tableRowPattern(escapedFieldName) {
+    return new RegExp(`^(\\|[ \\t]*)(${escapedFieldName})([ \\t]*\\|[ \\t]*)([^|\\n]*?)([ \\t]*\\|[ \\t]*)$`, 'im');
+}
+function stateExtractField(content, fieldName) {
+    const escaped = escapeRegex(fieldName);
+    // Bold inline format: **FieldName:** value
+    const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
+    const boldMatch = content.match(boldPattern);
+    if (boldMatch)
+        return boldMatch[1].trim();
+    // Plain line-start format: FieldName: value
+    const plainPattern = new RegExp(`^${escaped}:[ \\t]*(.+)`, 'im');
+    const plainMatch = content.match(plainPattern);
+    if (plainMatch)
+        return plainMatch[1].trim();
+    // Pipe-table format: | FieldName | value |
+    // (Separator rows such as `| --- | --- |` are excluded.)
+    const tableMatch = content.match(tableRowPattern(escaped));
+    if (tableMatch && !isTableSeparatorRow(tableMatch[2]))
+        return tableMatch[4].trim();
+    return null;
+}
+function stateReplaceField(content, fieldName, newValue) {
+    const escaped = escapeRegex(fieldName);
+    // Bold inline format: **FieldName:** value
+    const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
+    if (boldPattern.test(content)) {
+        return content.replace(boldPattern, (_match, prefix) => `${prefix}${newValue}`);
+    }
+    // Plain line-start format: FieldName: value
+    const plainPattern = new RegExp(`(^${escaped}:\\s*)(.*)`, 'im');
+    if (plainPattern.test(content)) {
+        return content.replace(plainPattern, (_match, prefix) => `${prefix}${newValue}`);
+    }
+    // Pipe-table format: | FieldName | value |
+    // Preserve the surrounding pipe/whitespace structure; only swap the value cell.
+    const tblPat = tableRowPattern(escaped);
+    const tblMatch = content.match(tblPat);
+    if (tblMatch && !isTableSeparatorRow(tblMatch[2])) {
+        // Reconstruct the row, preserving the original surrounding whitespace/pipes.
+        return content.replace(tblPat, (_m, leadPipe, fieldCell, midPipe, _oldVal, trailPipe) => `${leadPipe}${fieldCell}${midPipe}${newValue}${trailPipe}`);
+    }
+    return null;
+}
+function stateReplaceFieldWithFallback(content, primary, fallback, value) {
+    let result = stateReplaceField(content, primary, value);
+    if (result)
+        return result;
+    if (fallback) {
+        result = stateReplaceField(content, fallback, value);
+        if (result)
+            return result;
+    }
+    return content;
+}
+function normalizeStateStatus(status, pausedAt) {
+    let normalizedStatus = status || 'unknown';
+    const statusLower = (status || '').toLowerCase();
+    if (statusLower.includes('paused') || statusLower.includes('stopped') || pausedAt) {
+        normalizedStatus = 'paused';
+    }
+    else if (statusLower.includes('executing') || statusLower.includes('in progress')) {
+        normalizedStatus = 'executing';
+    }
+    else if (statusLower.includes('planning') || statusLower.includes('ready to plan')) {
+        normalizedStatus = 'planning';
+    }
+    else if (statusLower.includes('discussing')) {
+        normalizedStatus = 'discussing';
+    }
+    else if (statusLower.includes('verif')) {
+        normalizedStatus = 'verifying';
+    }
+    else if (statusLower.includes('complete') || statusLower.includes('done')) {
+        normalizedStatus = 'completed';
+    }
+    else if (statusLower.includes('ready to execute')) {
+        normalizedStatus = 'executing';
+    }
+    return normalizedStatus;
+}
+function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
+    const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
+    const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
+    if (!hasPlanData && !hasPhaseData)
+        return null;
+    // Use nullish coalescing to avoid non-null assertion operators (flow narrowing
+    // cannot track through intermediate boolean variables).
+    const planFraction = hasPlanData ? (completedPlans ?? 0) / (totalPlans ?? 1) : 1;
+    const phaseFraction = hasPhaseData ? (completedPhases ?? 0) / (totalPhases ?? 1) : 1;
+    return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
+}
+function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
+    if (!existingProgress || typeof existingProgress !== 'object')
+        return false;
+    if (!derivedProgress || typeof derivedProgress !== 'object')
+        return false;
+    const existing = existingProgress;
+    const derived = derivedProgress;
+    return (existingProgressExceedsDerived(existing, derived, 'total_phases') ||
+        existingProgressExceedsDerived(existing, derived, 'completed_phases') ||
+        existingProgressExceedsDerived(existing, derived, 'total_plans') ||
+        existingProgressExceedsDerived(existing, derived, 'completed_plans'));
+}
+function normalizeProgressNumbers(progress) {
+    if (!progress || typeof progress !== 'object')
+        return progress;
+    const normalized = { ...progress };
+    for (const key of ['total_phases', 'completed_phases', 'total_plans', 'completed_plans', 'percent']) {
+        const number = toFiniteNumber(normalized[key]);
+        if (number !== null)
+            normalized[key] = number;
+    }
+    return normalized;
+}
+/**
+ * KNOWN_TEMPLATE_DEFAULTS — per-field table of string values that were written
+ * by a GSD handler (not by an executor / human).  A value that appears in this
+ * list is safe to overwrite on the next handler call.  Any other value was
+ * authored by the executor and must be preserved (Knuth invariant:
+ * handler-owns-transition-between-known-template-defaults).
+ *
+ * Keys must match the canonical field name as it appears in STATE.md.
+ * Comparison is case-insensitive so "None" and "none" both match.
+ *
+ * For Status, exact strings are supplemented by a pattern list
+ * (KNOWN_STATUS_PATTERNS) that matches handler-generated values whose exact
+ * text is variable (e.g. "Executing Phase 5").
+ */
+exports.KNOWN_TEMPLATE_DEFAULTS = {
+    'Resume File': ['None'],
+    'Status': [
+        'Ready to execute',
+        'Phase complete — ready for verification',
+        'Ready to plan',
+        'Defining requirements',
+        'Planning complete',
+        // Legacy / abbreviated handler values present in older STATE.md files
+        'Executing',
+        'In progress',
+        'Planning',
+        'Verifying',
+        'Completed',
+        'Done',
+        'Active',
+        'Paused',
+        'unknown',
+    ],
+    // Last Activity is a date field; ISO date-only strings (YYYY-MM-DD) are the
+    // handler-generated form.  We detect them by shape rather than an exhaustive
+    // list because the date changes every day.
+    // NOTE: entries here are matched by isStateTemplateDefault using the date regex
+    // in addition to exact string equality.
+    'Last Activity': [],
+    'Last activity': [],
+};
+/**
+ * Regex patterns that match handler-generated Status values whose text includes
+ * a variable component (e.g. phase number).  Checked after the KNOWN_TEMPLATE_DEFAULTS
+ * exact-match list in isStateTemplateDefault.
+ */
+exports.KNOWN_STATUS_PATTERNS = [
+    /^Executing Phase\s+\d+/i,
+    /^Planning Phase\s+\d+/i,
+    /^Phase\s+\d+\s+complete/i,
+    /^Verifying Phase\s+\d+/i,
+    /^Phase complete/i,
+    // #1070: LLM executors (e.g. OpenCode) may write "Complete ✓" or bare "Complete"
+    // when finishing a phase.  Only bare terminal markers yield to the next phase's
+    // "Ready to execute" during planned-phase.  The pattern is anchored at both ends
+    // so that statuses with trailing prose (e.g. "Complete but needs manual QA",
+    // "Complete — ready for verification") are NOT matched and are preserved as
+    // executor-authored values.  Only exact forms like "Complete", "Complete ✓",
+    // "Complete✓", or "Complete ☑ " (trailing whitespace) match.
+    /^Complete\s*[✓✔✅☑]?\s*$/i,
+];
+/**
+ * Returns true when the given value is a known template default for the field,
+ * meaning a GSD handler wrote it and a subsequent handler may replace it.
+ *
+ * A value is considered a template default when:
+ *   (a) it appears in KNOWN_TEMPLATE_DEFAULTS[field] (exact, case-insensitive), OR
+ *   (b) it matches the ISO date-only shape (YYYY-MM-DD) for Last Activity fields
+ *       (handlers always write bare dates; executors write narrative prose).
+ *
+ * @param field  - Canonical field name (case-sensitive key lookup attempted
+ *                  first, then case-insensitive fallback).
+ * @param value  - The current value extracted from STATE.md.
+ * @returns boolean
+ */
+function isStateTemplateDefault(field, value) {
+    if (value === null || value === undefined)
+        return true; // absent → initial write
+    // Narrow to string: callers pass string values extracted from STATE.md.
+    const v = (typeof value === 'string' ? value : `${value}`).trim();
+    if (v === '')
+        return true; // blank → treat as absent
+    // Look up the defaults list, trying exact key first then case-insensitive.
+    let defaults = exports.KNOWN_TEMPLATE_DEFAULTS[field];
+    if (!defaults) {
+        const fieldLower = field.toLowerCase();
+        const matchKey = Object.keys(exports.KNOWN_TEMPLATE_DEFAULTS).find(k => k.toLowerCase() === fieldLower);
+        defaults = matchKey ? exports.KNOWN_TEMPLATE_DEFAULTS[matchKey] : null;
+    }
+    if (defaults && defaults.some(d => d.toLowerCase() === v.toLowerCase())) {
+        return true;
+    }
+    const fieldLower = field.toLowerCase();
+    // Status: also check pattern list for variable handler-generated values
+    // (e.g. "Executing Phase 5", "Planning Phase 3").
+    if (fieldLower === 'status') {
+        if (exports.KNOWN_STATUS_PATTERNS.some(p => p.test(v)))
+            return true;
+    }
+    // Last Activity / Last activity: bare ISO date (YYYY-MM-DD) is handler-generated.
+    if (fieldLower === 'last activity') {
+        if (/^\d{4}-\d{2}-\d{2}$/.test(v))
+            return true;
+    }
+    return false;
+}
+/**
+ * Replaces a field in STATE.md content only when the existing value is a known
+ * template default (or the field is absent).  If the existing value is
+ * executor-authored, the content is returned unchanged.
+ *
+ * When `newValue` is null or undefined the function is a no-op (returns content).
+ *
+ * @param content       - Full STATE.md text.
+ * @param field         - Field name as it appears in STATE.md.
+ * @param knownDefaults - The defaults list to check against (typically
+ *                         KNOWN_TEMPLATE_DEFAULTS[field]).
+ * @param newValue      - Value to write when replacement is permitted.
+ * @returns Updated content (or original if skipped).
+ */
+function stateReplaceFieldIfTemplate(content, field, knownDefaults, newValue) {
+    if (newValue === null || newValue === undefined)
+        return content;
+    const existing = stateExtractField(content, field);
+    // Inline check: absent/blank → always write; in list → write; else → skip.
+    if (existing === null || existing === undefined || existing.trim() === '') {
+        return stateReplaceField(content, field, newValue) || content;
+    }
+    const v = existing.trim();
+    const inList = (knownDefaults || []).some(d => d.toLowerCase() === v.toLowerCase());
+    const fieldLower = field.toLowerCase();
+    // Special-case: Status pattern list for variable handler-generated values.
+    const matchesStatusPattern = (fieldLower === 'status') && exports.KNOWN_STATUS_PATTERNS.some(p => p.test(v));
+    // Special-case: Last Activity bare ISO date (YYYY-MM-DD) is handler-generated.
+    const isDateShape = (fieldLower === 'last activity') && /^\d{4}-\d{2}-\d{2}$/.test(v);
+    if (inList || matchesStatusPattern || isDateShape) {
+        return stateReplaceField(content, field, newValue) || content;
+    }
+    // Executor-authored — preserve.
+    return content;
+}