@ttfw/envoi 1.0.0

package/dist/lib/transport.js

@@ -0,0 +1,237 @@
+/**
+ * Transport layer utilities for Claude invocations.
+ *
+ * Provides stall detection and timeout wrapper for reliable
+ * handling of connection issues, timeouts, and transport failures.
+ */
+import { ClaudeError } from '../types/claude.js';
+import { invokeClaudeCode } from './claude.js';
+/**
+ * Maximum length for raw_error in TransportStallError.
+ * Truncates error messages to prevent excessive memory usage.
+ */
+const MAX_RAW_ERROR_LENGTH = 500;
+/**
+ * Patterns that indicate a transport stall.
+ */
+const STALL_PATTERNS = [
+    'Connection stalled',
+    'streamFromAgentBackend',
+    'ECONNRESET',
+    'ETIMEDOUT',
+    'socket hang up',
+];
+/**
+ * Detects transport stall patterns in error output.
+ *
+ * Checks for known patterns that indicate connection issues:
+ * - "Connection stalled" - Cursor/CLI connection issue
+ * - "streamFromAgentBackend" - Backend stream failure
+ * - "ECONNRESET" - Connection reset by peer
+ * - "ETIMEDOUT" - Connection timeout
+ * - "socket hang up" - Socket disconnection
+ *
+ * Also extracts Request ID if present for debugging.
+ *
+ * @param error - Error message or stderr output to analyze
+ * @returns Detection result with stalled flag and optional request_id
+ *
+ * @example
+ * ```typescript
+ * const result = isTransportStall('Connection stalled. Request ID: abc123');
+ * // result.stalled === true
+ * // result.request_id === 'abc123'
+ * ```
+ */
+export function isTransportStall(error) {
+    if (!error) {
+        return { stalled: false, request_id: null, matched_pattern: null };
+    }
+    // Check for stall patterns
+    let matchedPattern = null;
+    for (const pattern of STALL_PATTERNS) {
+        if (error.includes(pattern)) {
+            matchedPattern = pattern;
+            break;
+        }
+    }
+    // Extract Request ID if present
+    // Common formats: "Request ID: xxx", "request_id: xxx", "requestId: xxx"
+    let requestId = null;
+    const requestIdMatch = error.match(/[Rr]equest[_\s]?[Ii][Dd][:\s]+([a-zA-Z0-9_-]+)/);
+    if (requestIdMatch) {
+        requestId = requestIdMatch[1];
+    }
+    return {
+        stalled: matchedPattern !== null,
+        request_id: requestId,
+        matched_pattern: matchedPattern,
+    };
+}
+/**
+ * Creates a TransportStallError from error information.
+ *
+ * @param stage - The stage where the stall occurred (ORCHESTRATE or BUILD)
+ * @param rawError - The raw error message
+ * @param requestId - Optional request ID extracted from error
+ * @returns Structured TransportStallError
+ */
+export function createTransportStallError(stage, rawError, requestId = null) {
+    // Truncate raw_error to prevent excessive length
+    const truncatedError = rawError.length > MAX_RAW_ERROR_LENGTH
+        ? rawError.substring(0, MAX_RAW_ERROR_LENGTH) + '...'
+        : rawError;
+    return {
+        kind: 'transport_stalled',
+        stage,
+        request_id: requestId,
+        raw_error: truncatedError,
+    };
+}
+/**
+ * Invokes Claude Code CLI with stall detection.
+ *
+ * Wraps the standard invokeClaudeCode function and:
+ * 1. Catches timeout errors and converts to TransportStallError
+ * 2. Detects stall patterns in error output
+ * 3. Returns structured error for transport failures
+ *
+ * @param config - Claude Code CLI configuration
+ * @param invocation - Invocation parameters
+ * @param stage - The stage (ORCHESTRATE or BUILD) for error context
+ * @returns InvokeResult with either response or stall error
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeWithStallDetection(config, invocation, 'BUILD');
+ * if (result.ok) {
+ *   console.log('Success:', result.response.result);
+ * } else {
+ *   console.log('Stall:', result.error.raw_error);
+ * }
+ * ```
+ */
+export async function invokeWithStallDetection(config, invocation, stage) {
+    try {
+        const response = await invokeClaudeCode(config, invocation);
+        return { ok: true, response };
+    }
+    catch (error) {
+        // Handle ClaudeError (timeout, process errors, etc.)
+        if (error instanceof ClaudeError) {
+            const errorMessage = error.message + (error.stderr ? `\n${error.stderr}` : '');
+            // Check if this is a timeout (exit code 124 is standard timeout)
+            const isTimeout = error.exitCode === 124 || error.message.includes('timed out');
+            // Check for stall patterns
+            const stallCheck = isTransportStall(errorMessage);
+            // If timeout or stall pattern detected, return TransportStallError
+            if (isTimeout || stallCheck.stalled) {
+                return {
+                    ok: false,
+                    error: createTransportStallError(stage, errorMessage, stallCheck.request_id),
+                };
+            }
+            // For other ClaudeErrors, re-throw (not a transport stall)
+            throw error;
+        }
+        // For unexpected errors, check if they contain stall patterns
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        const stallCheck = isTransportStall(errorMessage);
+        if (stallCheck.stalled) {
+            return {
+                ok: false,
+                error: createTransportStallError(stage, errorMessage, stallCheck.request_id),
+            };
+        }
+        // Re-throw non-transport errors
+        throw error;
+    }
+}
+/**
+ * Normalizes any error type into a consistent format for stall detection.
+ *
+ * Handles:
+ * - ClaudeError: extracts message + stderr, checks for timeout
+ * - Error: extracts message
+ * - string: wraps in Error
+ * - unknown: converts to string and wraps in Error
+ *
+ * @param error - Any error type (ClaudeError, Error, string, unknown)
+ * @param stage - The stage where the error occurred (ORCHESTRATE or BUILD)
+ * @returns Normalized error with stall detection result
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   await invokeClaudeCode(config, invocation);
+ * } catch (error) {
+ *   const normalized = normalizeTransportError(error, 'BUILD');
+ *   if (normalized.isStall) {
+ *     handleStall(normalized.stallError);
+ *   } else {
+ *     throw normalized.originalError;
+ *   }
+ * }
+ * ```
+ */
+/**
+ * Type guard to check if an error is a TransportStallError.
+ *
+ * @param error - Any value to check
+ * @returns True if the error is a TransportStallError
+ *
+ * @example
+ * ```typescript
+ * const result = await invokeWithStallDetection(config, invocation, 'BUILD');
+ * if (!result.ok && isTransportStallError(result.error)) {
+ *   console.log('Stage:', result.error.stage);
+ *   console.log('Request ID:', result.error.request_id);
+ * }
+ * ```
+ */
+export function isTransportStallError(error) {
+    if (typeof error !== 'object' || error === null) {
+        return false;
+    }
+    const obj = error;
+    return (obj.kind === 'transport_stalled' &&
+        (obj.stage === 'ORCHESTRATE' || obj.stage === 'BUILD') &&
+        (typeof obj.request_id === 'string' || obj.request_id === null) &&
+        typeof obj.raw_error === 'string');
+}
+export function normalizeTransportError(error, stage) {
+    let message;
+    let originalError;
+    let isTimeout = false;
+    // Handle different error types
+    if (error instanceof ClaudeError) {
+        message = error.message + (error.stderr ? `\n${error.stderr}` : '');
+        originalError = error;
+        isTimeout = error.exitCode === 124 || error.message.includes('timed out');
+    }
+    else if (error instanceof Error) {
+        message = error.message;
+        originalError = error;
+    }
+    else if (typeof error === 'string') {
+        message = error;
+        originalError = new Error(error);
+    }
+    else {
+        message = String(error);
+        originalError = new Error(message);
+    }
+    // Check for stall patterns
+    const stallCheck = isTransportStall(message);
+    // Determine if this is a stall
+    const isStall = isTimeout || stallCheck.stalled;
+    return {
+        isStall,
+        stallError: isStall
+            ? createTransportStallError(stage, message, stallCheck.request_id)
+            : null,
+        originalError,
+        message,
+    };
+}
+//# sourceMappingURL=transport.js.map

package/dist/lib/transport.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"transport.js","sourceRoot":"","sources":["../../src/lib/transport.ts"],"names":[],"mappings":"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"}

package/dist/lib/verdict_labels.d.ts

@@ -0,0 +1,5 @@
+import type { Verdict } from '../types/report.js';
+export type DisplayState = 'CLEARED' | 'STANDBY' | 'BLOCKED' | 'OUT_OF_BOUNDS' | 'LIMIT_HIT' | 'ROLLED_BACK';
+export declare function toDisplayState(verdict: Verdict, code: string): DisplayState;
+export declare function formatDisplayState(verdict: Verdict, code: string): string;
+//# sourceMappingURL=verdict_labels.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verdict_labels.d.ts","sourceRoot":"","sources":["../../src/lib/verdict_labels.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,MAAM,YAAY,GACpB,SAAS,GACT,SAAS,GACT,SAAS,GACT,eAAe,GACf,WAAW,GACX,aAAa,CAAC;AAclB,wBAAgB,cAAc,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,YAAY,CAO3E;AAED,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,CAEzE"}

package/dist/lib/verdict_labels.js

@@ -0,0 +1,25 @@
+function isOutOfBounds(code) {
+    return (code.startsWith('STOP_SCOPE_VIOLATION') ||
+        code === 'STOP_RUNNER_OWNED_MUTATION' ||
+        code === 'STOP_LOCKFILE_CHANGE_FORBIDDEN');
+}
+function isLimitHit(code) {
+    return code === 'STOP_DIFF_TOO_LARGE' || code.startsWith('BLOCKED_BUDGET_');
+}
+export function toDisplayState(verdict, code) {
+    if (code === 'SUCCESS' || verdict === 'success')
+        return 'CLEARED';
+    if (isOutOfBounds(code))
+        return 'OUT_OF_BOUNDS';
+    if (isLimitHit(code))
+        return 'LIMIT_HIT';
+    if (code === 'STOP_INTERRUPTED' || verdict === 'stop')
+        return 'STANDBY';
+    if (code.startsWith('BLOCKED_') || verdict === 'blocked')
+        return 'BLOCKED';
+    return 'STANDBY';
+}
+export function formatDisplayState(verdict, code) {
+    return `${toDisplayState(verdict, code)} (${code})`;
+}
+//# sourceMappingURL=verdict_labels.js.map

package/dist/lib/verdict_labels.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verdict_labels.js","sourceRoot":"","sources":["../../src/lib/verdict_labels.ts"],"names":[],"mappings":"AAUA,SAAS,aAAa,CAAC,IAAY;IACjC,OAAO,CACL,IAAI,CAAC,UAAU,CAAC,sBAAsB,CAAC;QACvC,IAAI,KAAK,4BAA4B;QACrC,IAAI,KAAK,gCAAgC,CAC1C,CAAC;AACJ,CAAC;AAED,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,KAAK,qBAAqB,IAAI,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;AAC9E,CAAC;AAED,MAAM,UAAU,cAAc,CAAC,OAAgB,EAAE,IAAY;IAC3D,IAAI,IAAI,KAAK,SAAS,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAClE,IAAI,aAAa,CAAC,IAAI,CAAC;QAAE,OAAO,eAAe,CAAC;IAChD,IAAI,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO,WAAW,CAAC;IACzC,IAAI,IAAI,KAAK,kBAAkB,IAAI,OAAO,KAAK,MAAM;QAAE,OAAO,SAAS,CAAC;IACxE,IAAI,IAAI,CAAC,UAAU,CAAC,UAAU,CAAC,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO,SAAS,CAAC;IAC3E,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,OAAgB,EAAE,IAAY;IAC/D,OAAO,GAAG,cAAc,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,IAAI,GAAG,CAAC;AACtD,CAAC"}

package/dist/lib/verify-safety.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Verification parameter safety validation module.
+ *
+ * Provides functions to validate verification parameters against security constraints
+ * to prevent shell injection and other security issues.
+ */
+import type { VerificationConfig } from '../types/config.js';
+/**
+ * Result of parameter validation.
+ */
+export interface ParamValidationResult {
+    /** True if the parameter(s) are valid */
+    ok: boolean;
+    /** Stop code to use if validation fails */
+    stopCode: 'STOP_VERIFY_TAINTED' | null;
+    /** Name of the invalid parameter (if any) */
+    invalidParam: string | null;
+    /** Reason for validation failure */
+    reason: string | null;
+}
+/**
+ * Validates a single verification parameter 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 param - The parameter value to validate
+ * @param config - Verification configuration with validation rules
+ * @returns ParamValidationResult with ok=true if valid, or failure details
+ *
+ * @example
+ * ```typescript
+ * const result = validateVerifyParam('my-value', config);
+ * if (!result.ok) {
+ *   console.error(`Invalid param: ${result.reason}`);
+ * }
+ * ```
+ */
+export declare function validateVerifyParam(param: string, config: VerificationConfig): ParamValidationResult;
+/**
+ * Validates all parameters in a record, returning the first failure.
+ *
+ * Validates each parameter value in the params object against the security
+ * constraints defined in the verification config. Returns the first validation
+ * failure encountered, or success if all parameters are valid.
+ *
+ * @param params - Record mapping parameter names to string values
+ * @param config - Verification configuration with validation rules
+ * @returns ParamValidationResult with ok=true if all params valid, or first failure details
+ *
+ * @example
+ * ```typescript
+ * const result = validateAllParams({ pkg: 'my-package', env: 'prod' }, config);
+ * if (!result.ok) {
+ *   console.error(`Invalid param '${result.invalidParam}': ${result.reason}`);
+ * }
+ * ```
+ */
+export declare function validateAllParams(params: Record<string, string>, config: VerificationConfig): ParamValidationResult;
+//# sourceMappingURL=verify-safety.d.ts.map

package/dist/lib/verify-safety.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-safety.d.ts","sourceRoot":"","sources":["../../src/lib/verify-safety.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAE7D;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,yCAAyC;IACzC,EAAE,EAAE,OAAO,CAAC;IACZ,2CAA2C;IAC3C,QAAQ,EAAE,qBAAqB,GAAG,IAAI,CAAC;IACvC,6CAA6C;IAC7C,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,oCAAoC;IACpC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,MAAM,EACb,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,CA4DvB;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,EAC9B,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,CAkBvB"}

package/dist/lib/verify-safety.js

@@ -0,0 +1,123 @@
+/**
+ * Verification parameter safety validation module.
+ *
+ * Provides functions to validate verification parameters against security constraints
+ * to prevent shell injection and other security issues.
+ */
+/**
+ * Validates a single verification parameter 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 param - The parameter value to validate
+ * @param config - Verification configuration with validation rules
+ * @returns ParamValidationResult with ok=true if valid, or failure details
+ *
+ * @example
+ * ```typescript
+ * const result = validateVerifyParam('my-value', config);
+ * if (!result.ok) {
+ *   console.error(`Invalid param: ${result.reason}`);
+ * }
+ * ```
+ */
+export function validateVerifyParam(param, config) {
+    // Check length
+    if (param.length > config.max_param_len) {
+        return {
+            ok: false,
+            stopCode: 'STOP_VERIFY_TAINTED',
+            invalidParam: null,
+            reason: `Parameter length ${param.length} exceeds maximum ${config.max_param_len}`,
+        };
+    }
+    // Check for whitespace if enabled
+    if (config.reject_whitespace_in_params && /\s/.test(param)) {
+        return {
+            ok: false,
+            stopCode: 'STOP_VERIFY_TAINTED',
+            invalidParam: null,
+            reason: 'Parameter contains whitespace',
+        };
+    }
+    // Check for path traversal '..' if enabled
+    if (config.reject_dotdot && param.includes('..')) {
+        return {
+            ok: false,
+            stopCode: 'STOP_VERIFY_TAINTED',
+            invalidParam: null,
+            reason: "Parameter contains '..' path traversal",
+        };
+    }
+    // Check for shell metacharacters
+    try {
+        const metacharRegex = new RegExp(config.reject_metachars_regex);
+        if (metacharRegex.test(param)) {
+            return {
+                ok: false,
+                stopCode: 'STOP_VERIFY_TAINTED',
+                invalidParam: null,
+                reason: `Parameter matches metacharacter regex: ${config.reject_metachars_regex}`,
+            };
+        }
+    }
+    catch (error) {
+        // If regex is invalid, treat as validation failure
+        // This shouldn't happen with valid config, but be defensive
+        return {
+            ok: false,
+            stopCode: 'STOP_VERIFY_TAINTED',
+            invalidParam: null,
+            reason: `Invalid metacharacter regex in config: ${error instanceof Error ? error.message : String(error)}`,
+        };
+    }
+    // All checks passed
+    return {
+        ok: true,
+        stopCode: null,
+        invalidParam: null,
+        reason: null,
+    };
+}
+/**
+ * Validates all parameters in a record, returning the first failure.
+ *
+ * Validates each parameter value in the params object against the security
+ * constraints defined in the verification config. Returns the first validation
+ * failure encountered, or success if all parameters are valid.
+ *
+ * @param params - Record mapping parameter names to string values
+ * @param config - Verification configuration with validation rules
+ * @returns ParamValidationResult with ok=true if all params valid, or first failure details
+ *
+ * @example
+ * ```typescript
+ * const result = validateAllParams({ pkg: 'my-package', env: 'prod' }, config);
+ * if (!result.ok) {
+ *   console.error(`Invalid param '${result.invalidParam}': ${result.reason}`);
+ * }
+ * ```
+ */
+export function validateAllParams(params, config) {
+    for (const [paramName, paramValue] of Object.entries(params)) {
+        const result = validateVerifyParam(paramValue, config);
+        if (!result.ok) {
+            return {
+                ...result,
+                invalidParam: paramName,
+            };
+        }
+    }
+    // All parameters are valid
+    return {
+        ok: true,
+        stopCode: null,
+        invalidParam: null,
+        reason: null,
+    };
+}
+//# sourceMappingURL=verify-safety.js.map

package/dist/lib/verify-safety.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify-safety.js","sourceRoot":"","sources":["../../src/lib/verify-safety.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAkBH;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB,CACjC,KAAa,EACb,MAA0B;IAE1B,eAAe;IACf,IAAI,KAAK,CAAC,MAAM,GAAG,MAAM,CAAC,aAAa,EAAE,CAAC;QACxC,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,qBAAqB;YAC/B,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,oBAAoB,KAAK,CAAC,MAAM,oBAAoB,MAAM,CAAC,aAAa,EAAE;SACnF,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,IAAI,MAAM,CAAC,2BAA2B,IAAI,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC3D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,qBAAqB;YAC/B,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,+BAA+B;SACxC,CAAC;IACJ,CAAC;IAED,2CAA2C;IAC3C,IAAI,MAAM,CAAC,aAAa,IAAI,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,CAAC;QACjD,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,qBAAqB;YAC/B,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,wCAAwC;SACjD,CAAC;IACJ,CAAC;IAED,iCAAiC;IACjC,IAAI,CAAC;QACH,MAAM,aAAa,GAAG,IAAI,MAAM,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC;QAChE,IAAI,aAAa,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;YAC9B,OAAO;gBACL,EAAE,EAAE,KAAK;gBACT,QAAQ,EAAE,qBAAqB;gBAC/B,YAAY,EAAE,IAAI;gBAClB,MAAM,EAAE,0CAA0C,MAAM,CAAC,sBAAsB,EAAE;aAClF,CAAC;QACJ,CAAC;IACH,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,mDAAmD;QACnD,4DAA4D;QAC5D,OAAO;YACL,EAAE,EAAE,KAAK;YACT,QAAQ,EAAE,qBAAqB;YAC/B,YAAY,EAAE,IAAI;YAClB,MAAM,EAAE,0CAA0C,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,EAAE;SAC3G,CAAC;IACJ,CAAC;IAED,oBAAoB;IACpB,OAAO;QACL,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;QAClB,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA8B,EAC9B,MAA0B;IAE1B,KAAK,MAAM,CAAC,SAAS,EAAE,UAAU,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC,EAAE,CAAC;QAC7D,MAAM,MAAM,GAAG,mBAAmB,CAAC,UAAU,EAAE,MAAM,CAAC,CAAC;QACvD,IAAI,CAAC,MAAM,CAAC,EAAE,EAAE,CAAC;YACf,OAAO;gBACL,GAAG,MAAM;gBACT,YAAY,EAAE,SAAS;aACxB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,2BAA2B;IAC3B,OAAO;QACL,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE,IAAI;QACd,YAAY,EAAE,IAAI;QAClB,MAAM,EAAE,IAAI;KACb,CAAC;AACJ,CAAC"}

package/dist/lib/verify.d.ts

@@ -0,0 +1,139 @@
+/**
+ * Verification command execution module.
+ *
+ * Provides functions to execute verification commands safely using argv arrays
+ * (no shell) with parameter interpolation and timeout handling.
+ */
+import type { VerificationTemplate, VerificationConfig } from '../types/config.js';
+import type { Task } from '../types/task.js';
+/**
+ * Result of a single verification command execution.
+ */
+export interface VerificationRun {
+    /** ID of the verification template */
+    template_id: string;
+    /** Process exit code */
+    exit_code: number;
+    /** Captured stdout */
+    stdout: string;
+    /** Captured stderr */
+    stderr: string;
+    /** Execution time in milliseconds */
+    duration_ms: number;
+    /** Whether the command succeeded (exit_code === 0) */
+    success: boolean;
+}
+/**
+ * Validation error for a single parameter.
+ */
+export interface ParamValidationError {
+    /** Name of the parameter */
+    param_name: string;
+    /** The invalid value */
+    value: string;
+    /** Reason for failure: too_long, whitespace, dotdot, or metachar */
+    reason: 'too_long' | 'whitespace' | 'dotdot' | 'metachar';
+}
+/**
+ * Result of parameter validation.
+ */
+export interface ParamValidationResult {
+    /** True if all parameters are valid */
+    ok: boolean;
+    /** List of validation failures */
+    errors: ParamValidationError[];
+}
+/**
+ * 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 declare function validateParam(paramName: string, value: string | number | boolean | null, config: VerificationConfig): ParamValidationError | 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 declare function validateVerificationParams(task: Task, config: VerificationConfig): ParamValidationResult;
+/**
+ * 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 declare function interpolateArgs(args: string[], params: Record<string, string | number | boolean | null>): string[];
+/**
+ * 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 declare function executeVerification(template: VerificationTemplate, params: Record<string, string | number | boolean | null>, timeoutMs: number): Promise<VerificationRun>;
+/**
+ * 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 declare function runVerifications(templates: Map<string, VerificationTemplate>, task: Task, config: VerificationConfig): Promise<VerificationRun[]>;
+//# sourceMappingURL=verify.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/lib/verify.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,KAAK,EACV,oBAAoB,EACpB,kBAAkB,EACnB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EAAE,IAAI,EAAoB,MAAM,kBAAkB,CAAC;AAE/D;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,sCAAsC;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,wBAAwB;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,sBAAsB;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,WAAW,EAAE,MAAM,CAAC;IACpB,sDAAsD;IACtD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC,4BAA4B;IAC5B,UAAU,EAAE,MAAM,CAAC;IACnB,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,oEAAoE;IACpE,MAAM,EAAE,UAAU,GAAG,YAAY,GAAG,QAAQ,GAAG,UAAU,CAAC;CAC3D;AAED;;GAEG;AACH,MAAM,WAAW,qBAAqB;IACpC,uCAAuC;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,kCAAkC;IAClC,MAAM,EAAE,oBAAoB,EAAE,CAAC;CAChC;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAC3B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,EACvC,MAAM,EAAE,kBAAkB,GACzB,oBAAoB,GAAG,IAAI,CAuD7B;AAED;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,kBAAkB,GACzB,qBAAqB,CAuBvB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAC7B,IAAI,EAAE,MAAM,EAAE,EACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,GACvD,MAAM,EAAE,CAcV;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,oBAAoB,EAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EACxD,SAAS,EAAE,MAAM,GAChB,OAAO,CAAC,eAAe,CAAC,CAgH1B;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,gBAAgB,CACpC,SAAS,EAAE,GAAG,CAAC,MAAM,EAAE,oBAAoB,CAAC,EAC5C,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,kBAAkB,GACzB,OAAO,CAAC,eAAe,EAAE,CAAC,CAsC5B"}