@ttfw/envoi 1.0.0

package/dist/lib/verify.js

@@ -0,0 +1,311 @@
+/**
+ * Verification command execution module.
+ *
+ * Provides functions to execute verification commands safely using argv arrays
+ * (no shell) with parameter interpolation and timeout handling.
+ */
+import { spawn } from 'node:child_process';
+/**
+ * Validates a single parameter value against security constraints.
+ *
+ * Checks for:
+ * - Length exceeding max_param_len
+ * - Whitespace (if reject_whitespace_in_params is true)
+ * - Path traversal '..' (if reject_dotdot is true)
+ * - Shell metacharacters (using reject_metachars_regex)
+ *
+ * @param paramName - Name of the parameter being validated
+ * @param value - The parameter value to validate (converted to string)
+ * @param config - Verification configuration with validation rules
+ * @returns ParamValidationError if validation fails, null if valid
+ */
+export function validateParam(paramName, value, config) {
+    // Convert value to string for validation
+    const strValue = value === null ? '' : String(value);
+    // Check length
+    if (strValue.length > config.max_param_len) {
+        return {
+            param_name: paramName,
+            value: strValue,
+            reason: 'too_long',
+        };
+    }
+    // Check for whitespace if enabled
+    if (config.reject_whitespace_in_params && /\s/.test(strValue)) {
+        return {
+            param_name: paramName,
+            value: strValue,
+            reason: 'whitespace',
+        };
+    }
+    // Check for path traversal '..' if enabled
+    if (config.reject_dotdot) {
+        // Match: ../, ^..$, /..$
+        if (/\.\.\/|^\.\.$|\/\.\.$/.test(strValue)) {
+            return {
+                param_name: paramName,
+                value: strValue,
+                reason: 'dotdot',
+            };
+        }
+    }
+    // Check for shell metacharacters
+    try {
+        const metacharRegex = new RegExp(config.reject_metachars_regex);
+        if (metacharRegex.test(strValue)) {
+            return {
+                param_name: paramName,
+                value: strValue,
+                reason: 'metachar',
+            };
+        }
+    }
+    catch (error) {
+        // If regex is invalid, treat as validation failure
+        // This shouldn't happen with valid config, but be defensive
+        return {
+            param_name: paramName,
+            value: strValue,
+            reason: 'metachar',
+        };
+    }
+    return null;
+}
+/**
+ * Validates all verification parameters for a task.
+ *
+ * Validates all parameters in task.verification.params against the security
+ * constraints defined in the verification config.
+ *
+ * @param task - Task containing verification configuration and parameters
+ * @param config - Verification configuration with validation rules
+ * @returns ParamValidationResult with ok=true if all params valid, errors otherwise
+ *
+ * @example
+ * ```typescript
+ * const result = validateVerificationParams(task, config.verification);
+ * if (!result.ok) {
+ *   // Handle validation errors
+ *   console.error('Invalid parameters:', result.errors);
+ * }
+ * ```
+ */
+export function validateVerificationParams(task, config) {
+    const errors = [];
+    const verification = task.verification;
+    const params = verification.params ?? {};
+    // Validate all parameters for all templates
+    for (const [templateId, templateParams] of Object.entries(params)) {
+        for (const [paramName, paramValue] of Object.entries(templateParams)) {
+            const error = validateParam(paramName, paramValue, config);
+            if (error) {
+                // Prefix param name with template ID for clarity
+                errors.push({
+                    ...error,
+                    param_name: `${templateId}.${error.param_name}`,
+                });
+            }
+        }
+    }
+    return {
+        ok: errors.length === 0,
+        errors,
+    };
+}
+/**
+ * Interpolates parameter placeholders in command arguments.
+ *
+ * Replaces {{param_name}} placeholders with values from the params object.
+ *
+ * @param args - Array of command arguments that may contain {{param}} placeholders
+ * @param params - Object mapping parameter names to values
+ * @returns Array of arguments with placeholders replaced
+ *
+ * @example
+ * ```typescript
+ * interpolateArgs(['--filter', '{{pkg}}'], { pkg: 'my-package' })
+ * // Returns: ['--filter', 'my-package']
+ * ```
+ */
+export function interpolateArgs(args, params) {
+    return args.map((arg) => {
+        // Replace {{param_name}} placeholders
+        return arg.replace(/\{\{(\w+)\}\}/g, (match, paramName) => {
+            const value = params[paramName];
+            if (value === undefined) {
+                throw new Error(`Missing parameter '${paramName}' for template argument '${arg}'`);
+            }
+            // Convert to string, handling null explicitly
+            return value === null ? '' : String(value);
+        });
+    });
+}
+/**
+ * Executes a single verification command.
+ *
+ * Runs the command using spawn with shell:false for security. Captures stdout
+ * and stderr, enforces timeout, and returns execution results.
+ *
+ * @param template - Verification template containing cmd and args
+ * @param params - Parameters for template argument interpolation
+ * @param timeoutMs - Timeout in milliseconds (0 means no timeout)
+ * @returns Promise resolving to VerificationRun result
+ *
+ * @example
+ * ```typescript
+ * const result = await executeVerification(
+ *   { id: 'lint', cmd: 'pnpm', args: ['-w', 'lint'] },
+ *   {},
+ *   90000
+ * );
+ * ```
+ */
+export async function executeVerification(template, params, timeoutMs) {
+    const startTime = Date.now();
+    let stdout = '';
+    let stderr = '';
+    // Interpolate parameters in args
+    const args = interpolateArgs(template.args, params);
+    return new Promise((resolve, reject) => {
+        let timeoutId = null;
+        let child = null;
+        // Set up timeout handler
+        const handleTimeout = () => {
+            if (child) {
+                child.kill('SIGTERM');
+                // Give it a moment to terminate gracefully, then force kill
+                setTimeout(() => {
+                    if (child && !child.killed) {
+                        child.kill('SIGKILL');
+                    }
+                }, 1000);
+            }
+            const durationMs = Date.now() - startTime;
+            resolve({
+                template_id: template.id,
+                exit_code: 124, // Standard timeout exit code
+                stdout,
+                stderr: stderr + '\n[Command timed out]',
+                duration_ms: durationMs,
+                success: false,
+            });
+        };
+        // Set up timeout if specified
+        if (timeoutMs > 0) {
+            timeoutId = setTimeout(handleTimeout, timeoutMs);
+        }
+        try {
+            // Spawn the process with shell:false for security
+            child = spawn(template.cmd, args, {
+                shell: false,
+                stdio: ['pipe', 'pipe', 'pipe'],
+            });
+            // Capture stdout
+            child.stdout?.on('data', (data) => {
+                stdout += data.toString();
+            });
+            // Capture stderr
+            child.stderr?.on('data', (data) => {
+                stderr += data.toString();
+            });
+            // Handle process completion
+            child.on('close', (code) => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                const durationMs = Date.now() - startTime;
+                const exitCode = code ?? 0;
+                // If process was killed by timeout, result was already resolved
+                if (code === null && timeoutId) {
+                    return;
+                }
+                resolve({
+                    template_id: template.id,
+                    exit_code: exitCode,
+                    stdout,
+                    stderr,
+                    duration_ms: durationMs,
+                    success: exitCode === 0,
+                });
+            });
+            // Handle process errors
+            child.on('error', (error) => {
+                if (timeoutId) {
+                    clearTimeout(timeoutId);
+                }
+                const durationMs = Date.now() - startTime;
+                resolve({
+                    template_id: template.id,
+                    exit_code: 1,
+                    stdout,
+                    stderr: stderr + `\n[Process error: ${error.message}]`,
+                    duration_ms: durationMs,
+                    success: false,
+                });
+            });
+        }
+        catch (error) {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+            }
+            const durationMs = Date.now() - startTime;
+            resolve({
+                template_id: template.id,
+                exit_code: 1,
+                stdout,
+                stderr: stderr + `\n[Failed to spawn process: ${error instanceof Error ? error.message : String(error)}]`,
+                duration_ms: durationMs,
+                success: false,
+            });
+        }
+    });
+}
+/**
+ * Runs verification commands for a task.
+ *
+ * Executes fast verifications first, then slow verifications. Each verification
+ * uses the appropriate timeout from config. Parameters are taken from the task's
+ * verification.params object, keyed by template ID.
+ *
+ * @param templates - Map of template ID to VerificationTemplate
+ * @param task - Task containing verification configuration
+ * @param config - Verification configuration with timeouts
+ * @returns Promise resolving to array of VerificationRun results
+ *
+ * @example
+ * ```typescript
+ * const templates = new Map([
+ *   ['lint', { id: 'lint', cmd: 'pnpm', args: ['-w', 'lint'] }]
+ * ]);
+ * const runs = await runVerifications(templates, task, config.verification);
+ * ```
+ */
+export async function runVerifications(templates, task, config) {
+    const results = [];
+    const verification = task.verification;
+    const params = verification.params ?? {};
+    // Run fast verifications first
+    for (const templateId of verification.fast) {
+        const template = templates.get(templateId);
+        if (!template) {
+            throw new Error(`Verification template '${templateId}' not found in config`);
+        }
+        const templateParams = params[templateId] ?? {};
+        const timeoutMs = config.timeout_fast_seconds * 1000;
+        const result = await executeVerification(template, templateParams, timeoutMs);
+        results.push(result);
+    }
+    // Then run slow verifications
+    for (const templateId of verification.slow) {
+        const template = templates.get(templateId);
+        if (!template) {
+            throw new Error(`Verification template '${templateId}' not found in config`);
+        }
+        const templateParams = params[templateId] ?? {};
+        const timeoutMs = config.timeout_slow_seconds * 1000;
+        const result = await executeVerification(template, templateParams, timeoutMs);
+        results.push(result);
+    }
+    return results;
+}
+//# sourceMappingURL=verify.js.map

package/dist/lib/verify.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.js","sourceRoot":"","sources":["../../src/lib/verify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAgB,MAAM,oBAAoB,CAAC;AA+CzD;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,aAAa,CAC3B,SAAiB,EACjB,KAAuC,EACvC,MAA0B;IAE1B,yCAAyC;IACzC,MAAM,QAAQ,GAAG,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;IAErD,eAAe;IACf,IAAI,QAAQ,CAAC,MAAM,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QAC3C,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,KAAK,EAAE,QAAQ;YACf,MAAM,EAAE,UAAU;SACnB,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,IAAI,MAAM,CAAC,2BAA2B,IAAI,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC9D,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,KAAK,EAAE,QAAQ;YACf,MAAM,EAAE,YAAY;SACrB,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACzB,yBAAyB;QACzB,IAAI,uBAAuB,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YAC3C,OAAO;gBACL,UAAU,EAAE,SAAS;gBACrB,KAAK,EAAE,QAAQ;gBACf,MAAM,EAAE,QAAQ;aACjB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAChE,IAAI,aAAa,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC;YACjC,OAAO;gBACL,UAAU,EAAE,SAAS;gBACrB,KAAK,EAAE,QAAQ;gBACf,MAAM,EAAE,UAAU;aACnB,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mDAAmD;QACnD,4DAA4D;QAC5D,OAAO;YACL,UAAU,EAAE,SAAS;YACrB,KAAK,EAAE,QAAQ;YACf,MAAM,EAAE,UAAU;SACnB,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,0BAA0B,CACxC,IAAU,EACV,MAA0B;IAE1B,MAAM,MAAM,GAA2B,EAAE,CAAC;IAC1C,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,IAAI,EAAE,CAAC;IAEzC,4CAA4C;IAC5C,KAAK,MAAM,CAAC,UAAU,EAAE,cAAc,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAClE,KAAK,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,cAAc,CAAC,EAAE,CAAC;YACrE,MAAM,KAAK,GAAG,aAAa,CAAC,SAAS,EAAE,UAAU,EAAE,MAAM,CAAC,CAAC;YAC3D,IAAI,KAAK,EAAE,CAAC;gBACV,iDAAiD;gBACjD,MAAM,CAAC,IAAI,CAAC;oBACV,GAAG,KAAK;oBACR,UAAU,EAAE,GAAG,UAAU,IAAI,KAAK,CAAC,UAAU,EAAE;iBAChD,CAAC,CAAC;YACL,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO;QACL,EAAE,EAAE,MAAM,CAAC,MAAM,KAAK,CAAC;QACvB,MAAM;KACP,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAC7B,IAAc,EACd,MAAwD;IAExD,OAAO,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE;QACtB,sCAAsC;QACtC,OAAO,GAAG,CAAC,OAAO,CAAC,gBAAgB,EAAE,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE;YACxD,MAAM,KAAK,GAAG,MAAM,CAAC,SAAS,CAAC,CAAC;YAChC,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;gBACxB,MAAM,IAAI,KAAK,CACb,sBAAsB,SAAS,4BAA4B,GAAG,GAAG,CAClE,CAAC;YACJ,CAAC;YACD,8CAA8C;YAC9C,OAAO,KAAK,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC;QAC7C,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACvC,QAA8B,EAC9B,MAAwD,EACxD,SAAiB;IAEjB,MAAM,SAAS,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;IAC7B,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAEhB,iCAAiC;IACjC,MAAM,IAAI,GAAG,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAEpD,OAAO,IAAI,OAAO,CAAkB,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACtD,IAAI,SAAS,GAA0B,IAAI,CAAC;QAC5C,IAAI,KAAK,GAAwB,IAAI,CAAC;QAEtC,yBAAyB;QACzB,MAAM,aAAa,GAAG,GAAG,EAAE;YACzB,IAAI,KAAK,EAAE,CAAC;gBACV,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;gBACtB,4DAA4D;gBAC5D,UAAU,CAAC,GAAG,EAAE;oBACd,IAAI,KAAK,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,CAAC;wBAC3B,KAAK,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;oBACxB,CAAC;gBACH,CAAC,EAAE,IAAI,CAAC,CAAC;YACX,CAAC;YACD,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,OAAO,CAAC;gBACN,WAAW,EAAE,QAAQ,CAAC,EAAE;gBACxB,SAAS,EAAE,GAAG,EAAE,6BAA6B;gBAC7C,MAAM;gBACN,MAAM,EAAE,MAAM,GAAG,uBAAuB;gBACxC,WAAW,EAAE,UAAU;gBACvB,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;QACL,CAAC,CAAC;QAEF,8BAA8B;QAC9B,IAAI,SAAS,GAAG,CAAC,EAAE,CAAC;YAClB,SAAS,GAAG,UAAU,CAAC,aAAa,EAAE,SAAS,CAAC,CAAC;QACnD,CAAC;QAED,IAAI,CAAC;YACH,kDAAkD;YAClD,KAAK,GAAG,KAAK,CAAC,QAAQ,CAAC,GAAG,EAAE,IAAI,EAAE;gBAChC,KAAK,EAAE,KAAK;gBACZ,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC;aAChC,CAAC,CAAC;YAEH,iBAAiB;YACjB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBACxC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;YAEH,iBAAiB;YACjB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,IAAY,EAAE,EAAE;gBACxC,MAAM,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAC5B,CAAC,CAAC,CAAC;YAEH,4BAA4B;YAC5B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAmB,EAAE,EAAE;gBACxC,IAAI,SAAS,EAAE,CAAC;oBACd,YAAY,CAAC,SAAS,CAAC,CAAC;gBAC1B,CAAC;gBAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;gBAC1C,MAAM,QAAQ,GAAG,IAAI,IAAI,CAAC,CAAC;gBAE3B,gEAAgE;gBAChE,IAAI,IAAI,KAAK,IAAI,IAAI,SAAS,EAAE,CAAC;oBAC/B,OAAO;gBACT,CAAC;gBAED,OAAO,CAAC;oBACN,WAAW,EAAE,QAAQ,CAAC,EAAE;oBACxB,SAAS,EAAE,QAAQ;oBACnB,MAAM;oBACN,MAAM;oBACN,WAAW,EAAE,UAAU;oBACvB,OAAO,EAAE,QAAQ,KAAK,CAAC;iBACxB,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;YAEH,wBAAwB;YACxB,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,KAAY,EAAE,EAAE;gBACjC,IAAI,SAAS,EAAE,CAAC;oBACd,YAAY,CAAC,SAAS,CAAC,CAAC;gBAC1B,CAAC;gBAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;gBAC1C,OAAO,CAAC;oBACN,WAAW,EAAE,QAAQ,CAAC,EAAE;oBACxB,SAAS,EAAE,CAAC;oBACZ,MAAM;oBACN,MAAM,EAAE,MAAM,GAAG,qBAAqB,KAAK,CAAC,OAAO,GAAG;oBACtD,WAAW,EAAE,UAAU;oBACvB,OAAO,EAAE,KAAK;iBACf,CAAC,CAAC;YACL,CAAC,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,SAAS,EAAE,CAAC;gBACd,YAAY,CAAC,SAAS,CAAC,CAAC;YAC1B,CAAC;YAED,MAAM,UAAU,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,SAAS,CAAC;YAC1C,OAAO,CAAC;gBACN,WAAW,EAAE,QAAQ,CAAC,EAAE;gBACxB,SAAS,EAAE,CAAC;gBACZ,MAAM;gBACN,MAAM,EAAE,MAAM,GAAG,+BAA+B,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG;gBACzG,WAAW,EAAE,UAAU;gBACvB,OAAO,EAAE,KAAK;aACf,CAAC,CAAC;QACL,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,CAAC,KAAK,UAAU,gBAAgB,CACpC,SAA4C,EAC5C,IAAU,EACV,MAA0B;IAE1B,MAAM,OAAO,GAAsB,EAAE,CAAC;IACtC,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,CAAC;IACvC,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,IAAI,EAAE,CAAC;IAEzC,+BAA+B;IAC/B,KAAK,MAAM,UAAU,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,0BAA0B,UAAU,uBAAuB,CAC5D,CAAC;QACJ,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;QAErD,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;QAC9E,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,8BAA8B;IAC9B,KAAK,MAAM,UAAU,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC;QAC3C,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,UAAU,CAAC,CAAC;QAC3C,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,MAAM,IAAI,KAAK,CACb,0BAA0B,UAAU,uBAAuB,CAC5D,CAAC;QACJ,CAAC;QAED,MAAM,cAAc,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,EAAE,CAAC;QAChD,MAAM,SAAS,GAAG,MAAM,CAAC,oBAAoB,GAAG,IAAI,CAAC;QAErD,MAAM,MAAM,GAAG,MAAM,mBAAmB,CAAC,QAAQ,EAAE,cAAc,EAAE,SAAS,CAAC,CAAC;QAC9E,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IACvB,CAAC;IAED,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/lib/workspace_state.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Workspace state persistence library.
+ *
+ * Manages reading and writing STATE.json to track milestone progress
+ * and budget consumption across restarts.
+ *
+ * @see docs/NEW-PLAN.md lines 48-59
+ */
+import type { WorkspaceState, BudgetDeltas, IdeaTestabilityNeed } from '../types/workspace_state.js';
+import type { PerMilestoneBudgets } from '../types/config.js';
+/**
+ * Creates a default empty WorkspaceState.
+ *
+ * @returns Default state with null milestone_id, zero budgets, false budget_warning
+ */
+export declare function createDefaultState(): WorkspaceState;
+/**
+ * Reads and parses STATE.json from workspaceDir.
+ *
+ * Returns default state if file doesn't exist.
+ *
+ * @param workspaceDir - The workspace directory containing STATE.json
+ * @returns Parsed WorkspaceState or default if file doesn't exist
+ */
+export declare function readWorkspaceState(workspaceDir: string): Promise<WorkspaceState>;
+/**
+ * Writes WorkspaceState to STATE.json atomically.
+ *
+ * Uses atomic write pattern for crash safety.
+ *
+ * @param workspaceDir - The workspace directory to write STATE.json to
+ * @param state - The WorkspaceState to persist
+ */
+export declare function writeWorkspaceState(workspaceDir: string, state: WorkspaceState): Promise<void>;
+/**
+ * Ensures state has the given milestone_id.
+ *
+ * If milestone changes, resets budgets to zero.
+ *
+ * @param state - Current WorkspaceState
+ * @param milestoneId - Milestone ID to ensure
+ * @returns Updated state and whether milestone changed
+ */
+export declare function ensureMilestone(state: WorkspaceState, milestoneId: string): {
+    state: WorkspaceState;
+    changed: boolean;
+};
+/**
+ * Applies incremental budget changes to state.
+ *
+ * Creates new state with updated budgets (immutable update).
+ *
+ * @param state - Current WorkspaceState
+ * @param deltas - Partial budget counts to add
+ * @returns New state with updated budgets
+ */
+export declare function applyDeltas(state: WorkspaceState, deltas: BudgetDeltas): WorkspaceState;
+export interface NewIdeaInput {
+    text: string;
+    source: 'interactive' | 'cli' | 'api';
+    target_by?: string | null;
+    testability_need?: IdeaTestabilityNeed;
+}
+/**
+ * Appends a new idea entry to workspace state.
+ */
+export declare function appendIdeaEntry(state: WorkspaceState, input: NewIdeaInput): WorkspaceState;
+/**
+ * Checks if any budget is approaching its limit.
+ *
+ * Returns true if any budget count >= max * warnAtFraction.
+ *
+ * @param state - Current WorkspaceState
+ * @param perMilestone - Per-milestone budget limits
+ * @param warnAtFraction - Fraction (0-1) at which to warn
+ * @returns True if any budget is at warning level
+ */
+export declare function computeBudgetWarning(state: WorkspaceState, perMilestone: PerMilestoneBudgets, warnAtFraction: number): boolean;
+//# sourceMappingURL=workspace_state.d.ts.map

package/dist/lib/workspace_state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"workspace_state.d.ts","sourceRoot":"","sources":["../../src/lib/workspace_state.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,KAAK,EACV,cAAc,EAEd,YAAY,EAGZ,mBAAmB,EAEpB,MAAM,6BAA6B,CAAC;AACrC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,oBAAoB,CAAC;AAE9D;;;;GAIG;AACH,wBAAgB,kBAAkB,IAAI,cAAc,CAgBnD;AA2GD;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CA4BtF;AAED;;;;;;;GAOG;AACH,wBAAsB,mBAAmB,CACvC,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,cAAc,GACpB,OAAO,CAAC,IAAI,CAAC,CAGf;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,KAAK,EAAE,cAAc,EACrB,WAAW,EAAE,MAAM,GAClB;IAAE,KAAK,EAAE,cAAc,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,CAmB7C;AAED;;;;;;;;GAQG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,cAAc,EAAE,MAAM,EAAE,YAAY,GAAG,cAAc,CAYvF;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,aAAa,GAAG,KAAK,GAAG,KAAK,CAAC;IACtC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,gBAAgB,CAAC,EAAE,mBAAmB,CAAC;CACxC;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,EAAE,KAAK,EAAE,YAAY,GAAG,cAAc,CAqB1F;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,cAAc,EACrB,YAAY,EAAE,mBAAmB,EACjC,cAAc,EAAE,MAAM,GACrB,OAAO,CAsBT"}

package/dist/lib/workspace_state.js

@@ -0,0 +1,283 @@
+/**
+ * Workspace state persistence library.
+ *
+ * Manages reading and writing STATE.json to track milestone progress
+ * and budget consumption across restarts.
+ *
+ * @see docs/NEW-PLAN.md lines 48-59
+ */
+import { join } from 'node:path';
+import { atomicReadJson, atomicWriteJson, AtomicFsError } from './fs.js';
+/**
+ * Creates a default empty WorkspaceState.
+ *
+ * @returns Default state with null milestone_id, zero budgets, false budget_warning
+ */
+export function createDefaultState() {
+    return {
+        milestone_id: null,
+        budgets: {
+            ticks: 0,
+            orchestrator_calls: 0,
+            builder_calls: 0,
+            verify_runs: 0,
+        },
+        budget_warning: false,
+        last_run_id: null,
+        last_verdict: null,
+        idea_inbox: [],
+        planning_digest: null,
+        open_product_questions: [],
+    };
+}
+/**
+ * Runtime shape guard for idea status values.
+ */
+function isIdeaStatus(value) {
+    return value === 'new' || value === 'triaged' || value === 'scheduled' || value === 'deferred' || value === 'done';
+}
+/**
+ * Runtime shape guard for idea testability values.
+ */
+function isIdeaTestabilityNeed(value) {
+    return value === 'soon' || value === 'later' || value === 'unknown';
+}
+function normalizeIdeaInboxEntry(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const candidate = value;
+    if (typeof candidate.id !== 'string' || candidate.id.length === 0)
+        return null;
+    if (typeof candidate.text !== 'string' || candidate.text.length === 0)
+        return null;
+    if (typeof candidate.submitted_at !== 'string' || candidate.submitted_at.length === 0)
+        return null;
+    if (candidate.source !== 'interactive' && candidate.source !== 'cli' && candidate.source !== 'api')
+        return null;
+    if (!isIdeaStatus(candidate.status))
+        return null;
+    return {
+        id: candidate.id,
+        text: candidate.text,
+        submitted_at: candidate.submitted_at,
+        source: candidate.source,
+        status: candidate.status,
+        target_by: typeof candidate.target_by === 'string' ? candidate.target_by : null,
+        testability_need: isIdeaTestabilityNeed(candidate.testability_need) ? candidate.testability_need : undefined,
+        triaged_by_task_id: typeof candidate.triaged_by_task_id === 'string' ? candidate.triaged_by_task_id : undefined,
+        triaged_at: typeof candidate.triaged_at === 'string' ? candidate.triaged_at : undefined,
+    };
+}
+function normalizeOpenProductQuestion(value) {
+    if (typeof value !== 'object' || value === null)
+        return null;
+    const candidate = value;
+    if (typeof candidate.id !== 'string' || candidate.id.length === 0)
+        return null;
+    if (typeof candidate.prompt !== 'string' || candidate.prompt.length === 0)
+        return null;
+    if (typeof candidate.created_at !== 'string' || candidate.created_at.length === 0)
+        return null;
+    if (typeof candidate.resolved !== 'boolean')
+        return null;
+    const choices = Array.isArray(candidate.choices)
+        ? candidate.choices.filter((entry) => typeof entry === 'string' && entry.length > 0)
+        : undefined;
+    return {
+        id: candidate.id,
+        prompt: candidate.prompt,
+        choices,
+        created_at: candidate.created_at,
+        resolved: candidate.resolved,
+        resolved_at: typeof candidate.resolved_at === 'string' ? candidate.resolved_at : undefined,
+        resolution: typeof candidate.resolution === 'string' ? candidate.resolution : undefined,
+    };
+}
+/**
+ * Normalizes persisted state to include optional modern planning fields while
+ * preserving legacy fields present in older STATE.json files.
+ */
+function normalizeWorkspaceState(rawState) {
+    const source = rawState;
+    const ideaInbox = Array.isArray(source.idea_inbox)
+        ? source.idea_inbox
+            .map((entry) => normalizeIdeaInboxEntry(entry))
+            .filter((entry) => entry !== null)
+        : [];
+    const openQuestions = Array.isArray(source.open_product_questions)
+        ? source.open_product_questions
+            .map((entry) => normalizeOpenProductQuestion(entry))
+            .filter((entry) => entry !== null)
+        : [];
+    const planningDigestRaw = source.planning_digest;
+    const planningDigest = typeof planningDigestRaw === 'object' &&
+        planningDigestRaw !== null &&
+        typeof planningDigestRaw.updated_at === 'string' &&
+        typeof planningDigestRaw.summary === 'string'
+        ? {
+            updated_at: String(planningDigestRaw.updated_at),
+            summary: String(planningDigestRaw.summary),
+            last_task_id: typeof planningDigestRaw.last_task_id === 'string'
+                ? String(planningDigestRaw.last_task_id)
+                : undefined,
+            suggested_milestone: typeof planningDigestRaw.suggested_milestone === 'string'
+                ? String(planningDigestRaw.suggested_milestone)
+                : undefined,
+        }
+        : null;
+    return {
+        ...source,
+        idea_inbox: ideaInbox,
+        planning_digest: planningDigest,
+        open_product_questions: openQuestions,
+    };
+}
+/**
+ * Reads and parses STATE.json from workspaceDir.
+ *
+ * Returns default state if file doesn't exist.
+ *
+ * @param workspaceDir - The workspace directory containing STATE.json
+ * @returns Parsed WorkspaceState or default if file doesn't exist
+ */
+export async function readWorkspaceState(workspaceDir) {
+    const filePath = join(workspaceDir, 'STATE.json');
+    try {
+        const state = await atomicReadJson(filePath);
+        // Validate shape matches WorkspaceState interface
+        // TypeScript will catch type mismatches, but we ensure required fields exist
+        if (typeof state === 'object' &&
+            state !== null &&
+            'milestone_id' in state &&
+            'budgets' in state &&
+            'budget_warning' in state &&
+            'last_run_id' in state &&
+            'last_verdict' in state) {
+            return normalizeWorkspaceState(state);
+        }
+        // If shape doesn't match, return default
+        return createDefaultState();
+    }
+    catch (error) {
+        // If file doesn't exist or can't be read, return default state
+        if (error instanceof AtomicFsError) {
+            return createDefaultState();
+        }
+        // Re-throw unexpected errors
+        throw error;
+    }
+}
+/**
+ * Writes WorkspaceState to STATE.json atomically.
+ *
+ * Uses atomic write pattern for crash safety.
+ *
+ * @param workspaceDir - The workspace directory to write STATE.json to
+ * @param state - The WorkspaceState to persist
+ */
+export async function writeWorkspaceState(workspaceDir, state) {
+    const filePath = join(workspaceDir, 'STATE.json');
+    await atomicWriteJson(filePath, state);
+}
+/**
+ * Ensures state has the given milestone_id.
+ *
+ * If milestone changes, resets budgets to zero.
+ *
+ * @param state - Current WorkspaceState
+ * @param milestoneId - Milestone ID to ensure
+ * @returns Updated state and whether milestone changed
+ */
+export function ensureMilestone(state, milestoneId) {
+    if (state.milestone_id === milestoneId) {
+        return { state, changed: false };
+    }
+    // Milestone is different or null - create new state with reset budgets
+    const newState = {
+        ...state,
+        milestone_id: milestoneId,
+        budgets: {
+            ticks: 0,
+            orchestrator_calls: 0,
+            builder_calls: 0,
+            verify_runs: 0,
+        },
+        budget_warning: false,
+    };
+    return { state: newState, changed: true };
+}
+/**
+ * Applies incremental budget changes to state.
+ *
+ * Creates new state with updated budgets (immutable update).
+ *
+ * @param state - Current WorkspaceState
+ * @param deltas - Partial budget counts to add
+ * @returns New state with updated budgets
+ */
+export function applyDeltas(state, deltas) {
+    const newBudgets = {
+        ticks: state.budgets.ticks + (deltas.ticks ?? 0),
+        orchestrator_calls: state.budgets.orchestrator_calls + (deltas.orchestrator_calls ?? 0),
+        builder_calls: state.budgets.builder_calls + (deltas.builder_calls ?? 0),
+        verify_runs: state.budgets.verify_runs + (deltas.verify_runs ?? 0),
+    };
+    return {
+        ...state,
+        budgets: newBudgets,
+    };
+}
+/**
+ * Appends a new idea entry to workspace state.
+ */
+export function appendIdeaEntry(state, input) {
+    const trimmedText = input.text.trim();
+    if (!trimmedText)
+        return state;
+    const now = new Date().toISOString();
+    const nextId = `idea-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    const entry = {
+        id: nextId,
+        text: trimmedText,
+        submitted_at: now,
+        source: input.source,
+        status: 'new',
+        target_by: input.target_by ?? null,
+        testability_need: input.testability_need ?? 'unknown',
+    };
+    const inbox = [...(state.idea_inbox ?? []), entry];
+    return {
+        ...state,
+        idea_inbox: inbox,
+    };
+}
+/**
+ * Checks if any budget is approaching its limit.
+ *
+ * Returns true if any budget count >= max * warnAtFraction.
+ *
+ * @param state - Current WorkspaceState
+ * @param perMilestone - Per-milestone budget limits
+ * @param warnAtFraction - Fraction (0-1) at which to warn
+ * @returns True if any budget is at warning level
+ */
+export function computeBudgetWarning(state, perMilestone, warnAtFraction) {
+    // Check ticks
+    if (state.budgets.ticks >= perMilestone.max_ticks * warnAtFraction) {
+        return true;
+    }
+    // Check orchestrator_calls
+    if (state.budgets.orchestrator_calls >= perMilestone.max_orchestrator_calls * warnAtFraction) {
+        return true;
+    }
+    // Check builder_calls
+    if (state.budgets.builder_calls >= perMilestone.max_builder_calls * warnAtFraction) {
+        return true;
+    }
+    // Check verify_runs
+    if (state.budgets.verify_runs >= perMilestone.max_verify_runs * warnAtFraction) {
+        return true;
+    }
+    return false;
+}
+//# sourceMappingURL=workspace_state.js.map