patchwork-os 0.2.0-alpha.9 → 0.2.0-beta.0

package/dist/recipes/stepObservation.d.ts

@@ -0,0 +1,44 @@
+/**
+ * stepObservation — observability shims for recipe step execution.
+ *
+ * Bundles two independent concerns that both wrap step output for the
+ * runner / runlog / dashboard. They live together because they're both
+ * "what the runtime sees of a step's result," not because they share
+ * data — the two functions don't call each other and don't share types.
+ *
+ *   1. detectSilentFail(result) — recognize tool-output strings or shapes
+ *      that indicate a tool silently failed but reported "success" to
+ *      the runner. Used by yamlRunner to flag steps as `error` even when
+ *      the tool returned `ok:true`. Per-step opt-out via
+ *      `silentFailDetection: false`.
+ *
+ *   2. captureForRunlog(value) — sanitize + cap a step value for
+ *      persistence. Redacts known sensitive keys, handles cycles /
+ *      BigInt / undefined, and truncates JSON over 8 KB with a clear
+ *      `[truncated]` marker. Used by chainedRunner + approvalHttp.
+ *
+ * Both replace the previous `detectSilentFail.ts` and `captureForRunlog.ts`
+ * files (issue #252). Behavior is unchanged — the merge is organizational.
+ */
+export interface SilentFailMatch {
+    reason: string;
+    /** Slice of the result that triggered the match (for the error msg). */
+    matched: string;
+}
+/**
+ * Returns a `SilentFailMatch` if `result` looks like a silent-fail
+ * placeholder, else `null`. JSON `{ok:false}` detection stays in the
+ * runner — this module only handles the string + JSON-shape patterns
+ * the runner doesn't already catch.
+ */
+export declare function detectSilentFail(result: unknown): SilentFailMatch | null;
+/**
+ * Capture a value for inclusion in `RunStepResult`. Returns undefined if
+ * the value is `undefined` (don't bloat the log row for steps that
+ * produced nothing).
+ *
+ * Throws nothing — sanitize/serialize errors are caught and replaced with
+ * a small placeholder so a malformed step output never breaks the log
+ * write.
+ */
+export declare function captureForRunlog(value: unknown): unknown | undefined;

package/dist/recipes/stepObservation.js

@@ -0,0 +1,232 @@
+/**
+ * stepObservation — observability shims for recipe step execution.
+ *
+ * Bundles two independent concerns that both wrap step output for the
+ * runner / runlog / dashboard. They live together because they're both
+ * "what the runtime sees of a step's result," not because they share
+ * data — the two functions don't call each other and don't share types.
+ *
+ *   1. detectSilentFail(result) — recognize tool-output strings or shapes
+ *      that indicate a tool silently failed but reported "success" to
+ *      the runner. Used by yamlRunner to flag steps as `error` even when
+ *      the tool returned `ok:true`. Per-step opt-out via
+ *      `silentFailDetection: false`.
+ *
+ *   2. captureForRunlog(value) — sanitize + cap a step value for
+ *      persistence. Redacts known sensitive keys, handles cycles /
+ *      BigInt / undefined, and truncates JSON over 8 KB with a clear
+ *      `[truncated]` marker. Used by chainedRunner + approvalHttp.
+ *
+ * Both replace the previous `detectSilentFail.ts` and `captureForRunlog.ts`
+ * files (issue #252). Behavior is unchanged — the merge is organizational.
+ */
+/**
+ * Patterns that indicate a tool silently failed.
+ *
+ * The patterns are intentionally narrow — string-typed tool outputs are
+ * a rich surface and we don't want false positives. Each pattern
+ * corresponds to a known antipattern caught in the wild; bare prose is
+ * NOT flagged.
+ */
+const SILENT_FAIL_PATTERNS = [
+    // Placeholder strings emitted by `defaultGitLogSince`,
+    // `defaultGitStaleBranches` (pre-PR-70), and similar tools that
+    // catch all errors and return a parens-wrapped "unavailable" string.
+    // Match: anywhere on a single line, parens around a phrase containing
+    // "unavailable" / "not available" / "not configured" / "error" /
+    // "failed" — any of those wrapped in parens at the start of the line
+    // is a strong signal.
+    {
+        regex: /^\s*\(([^()]*?)(unavailable|not available|not configured|no data|error|failed)\)/i,
+        reason: "tool returned a parens-wrapped placeholder",
+    },
+    // Agent-step short-circuit: agentExecutor's own error/skip strings.
+    // Used by `executeAgent` when an API key is missing or the LLM
+    // returns nothing. Not surfaced as JSON, so the runner never saw it.
+    {
+        regex: /^\s*\[agent step (skipped|failed):/i,
+        reason: "agent step skipped or failed (string placeholder)",
+    },
+    // Generic step-skipped marker in case more callers adopt it.
+    {
+        regex: /^\s*\[step (skipped|failed):/i,
+        reason: "step skipped or failed (string placeholder)",
+    },
+];
+/**
+ * Returns a `SilentFailMatch` if `result` looks like a silent-fail
+ * placeholder, else `null`. JSON `{ok:false}` detection stays in the
+ * runner — this module only handles the string + JSON-shape patterns
+ * the runner doesn't already catch.
+ */
+export function detectSilentFail(result) {
+    if (result === null || result === undefined)
+        return null;
+    if (typeof result === "string") {
+        for (const { regex, reason } of SILENT_FAIL_PATTERNS) {
+            const m = regex.exec(result);
+            if (m) {
+                // Cap the matched fragment so error messages stay readable.
+                const matched = m[0].slice(0, 120);
+                return { reason, matched };
+            }
+        }
+        // String result that LOOKS like JSON — try parsing and recursing.
+        if (result.startsWith("{") || result.startsWith("[")) {
+            try {
+                return detectSilentFail(JSON.parse(result));
+            }
+            catch {
+                return null;
+            }
+        }
+        return null;
+    }
+    if (typeof result === "object" && !Array.isArray(result)) {
+        const obj = result;
+        // List-tool antipattern: `{count: 0, error: "..."}`. Tools that
+        // catch errors and return an empty list with an `error` field
+        // succeed-with-zero from the runner's view. Specifically targets
+        // `github.listIssues`, `linear.listIssues`, etc. flagged in the
+        // tool audit.
+        if (typeof obj.error === "string" &&
+            obj.error.length > 0 &&
+            (obj.count === 0 ||
+                (Array.isArray(obj.items) && obj.items.length === 0) ||
+                (Array.isArray(obj.results) && obj.results.length === 0))) {
+            return {
+                reason: "list-tool returned empty with error field",
+                matched: obj.error.slice(0, 120),
+            };
+        }
+    }
+    return null;
+}
+// ---------------------------------------------------------------------------
+// captureForRunlog
+//
+// VD-2 captures `resolvedParams`, `output`, and `registrySnapshot` per step
+// so the dashboard can show diff hovers + replay. These can carry secrets
+// (auth headers, API keys, passwords) and arbitrary user data, so we:
+//
+//   1. Redact known sensitive keys before serialization.
+//   2. JSON-stringify defensively (handle cycles, BigInt, undefined).
+//   3. Cap the JSON-encoded form at MAX_BYTES. Larger values are
+//      truncated with a clear `[truncated]` marker so the dashboard can
+//      tell users the value didn't fit, rather than guessing why it's
+//      missing.
+//
+// Bytes are JSON-string bytes, not the in-memory size — safe upper bound
+// since serialization is what the runlog persists.
+// ---------------------------------------------------------------------------
+const MAX_BYTES = 8 * 1024;
+// Case-insensitive substring match. Order: most specific first to avoid
+// accidentally matching narrower strings (none currently overlap, but
+// this is the convention).
+const SENSITIVE_KEY_PATTERNS = [
+    "authorization",
+    "x-api-key",
+    "api-key",
+    "apikey",
+    "password",
+    "passwd",
+    "secret",
+    "token",
+    "cookie",
+    "session",
+    "private-key",
+    "privatekey",
+    "client-secret",
+    "client_secret",
+    "refresh-token",
+    "refresh_token",
+    "access-token",
+    "access_token",
+];
+const REDACTED = "[REDACTED]";
+const TRUNCATED = "[truncated]";
+function isSensitiveKey(key) {
+    const lower = key.toLowerCase();
+    for (const pattern of SENSITIVE_KEY_PATTERNS) {
+        if (lower.includes(pattern))
+            return true;
+    }
+    return false;
+}
+/**
+ * Walk a value and replace any property whose key matches a sensitive
+ * pattern. Arrays + nested objects walked recursively. Cycles handled by
+ * tracking seen objects. Non-objects pass through unchanged.
+ */
+function redactSensitive(value, seen = new WeakSet()) {
+    if (value === null || typeof value !== "object")
+        return value;
+    if (seen.has(value))
+        return "[circular]";
+    seen.add(value);
+    if (Array.isArray(value)) {
+        return value.map((v) => redactSensitive(v, seen));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (isSensitiveKey(k)) {
+            out[k] = REDACTED;
+        }
+        else {
+            out[k] = redactSensitive(v, seen);
+        }
+    }
+    return out;
+}
+/**
+ * Capture a value for inclusion in `RunStepResult`. Returns undefined if
+ * the value is `undefined` (don't bloat the log row for steps that
+ * produced nothing).
+ *
+ * Throws nothing — sanitize/serialize errors are caught and replaced with
+ * a small placeholder so a malformed step output never breaks the log
+ * write.
+ */
+export function captureForRunlog(value) {
+    if (value === undefined)
+        return undefined;
+    let redacted;
+    try {
+        redacted = redactSensitive(value);
+    }
+    catch {
+        return { error: "[capture-redact-failed]" };
+    }
+    let json;
+    try {
+        json = JSON.stringify(redacted, (_key, v) => {
+            if (typeof v === "bigint")
+                return `${v}n`;
+            if (typeof v === "function")
+                return "[function]";
+            if (typeof v === "symbol")
+                return v.toString();
+            return v;
+        });
+    }
+    catch {
+        return { error: "[capture-serialize-failed]" };
+    }
+    // JSON.stringify returns undefined for certain top-level values (e.g.
+    // bare `undefined`). Already excluded above, but guard for safety.
+    if (typeof json !== "string")
+        return undefined;
+    if (Buffer.byteLength(json, "utf8") <= MAX_BYTES) {
+        return redacted;
+    }
+    // Over the cap. Don't try to walk + trim — that gets messy fast. Just
+    // slice the JSON string to the budget and reattach a clear marker.
+    // Re-parse may fail (we cut mid-key); if so, return a string envelope.
+    const slice = json.slice(0, MAX_BYTES);
+    return {
+        [TRUNCATED]: true,
+        bytes: Buffer.byteLength(json, "utf8"),
+        preview: slice,
+    };
+}
+//# sourceMappingURL=stepObservation.js.map

package/dist/recipes/stepObservation.js.map

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

package/dist/recipes/templateEngine.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Template Engine — safe template resolution for recipe step outputs.
+ *
+ * Replaces the deprecated `vm2` approach with a pure AST-based evaluator.
+ * Supports: `{{steps.X.data}}`, `{{steps.X.data.field.subfield}}`, `{{env.Y}}`
+ *
+ * Security: No eval, no Function constructor, no VM. Just path walking.
+ */
+export interface TemplateContext {
+    steps: Record<string, StepOutput>;
+    env: Record<string, string | undefined>;
+}
+export interface StepOutput {
+    status: "success" | "error" | "skipped";
+    data: unknown;
+    metadata?: {
+        startedAt: Date;
+        completedAt: Date;
+        model?: string;
+        tokenUsage?: number;
+    };
+}
+export interface TemplateCompileError {
+    type: "compile_error";
+    template: string;
+    message: string;
+}
+export interface TemplateEvalError {
+    type: "eval_error";
+    template: string;
+    path: string;
+    message: string;
+}
+export type TemplateError = TemplateCompileError | TemplateEvalError;
+export interface CompiledTemplate {
+    readonly source: string;
+    readonly hasTemplates: boolean;
+    evaluate(context: TemplateContext): {
+        value: string;
+    } | {
+        error: TemplateError;
+    };
+}
+/**
+ * Compile a template string into an executable form.
+ * Parses `{{...}}` expressions once, not per-evaluation.
+ */
+export declare function compileTemplate(template: string): CompiledTemplate;
+/**
+ * Convenience: compile and evaluate in one call.
+ * Prefer pre-compilation for repeated evaluations.
+ */
+export declare function evaluateTemplate(template: string, context: TemplateContext): {
+    value: string;
+} | {
+    error: TemplateError;
+};
+/**
+ * Validate all templates in a recipe at load time.
+ * Returns array of errors, empty if all valid.
+ */
+export declare function validateRecipeTemplates(templates: string[]): TemplateError[];

package/dist/recipes/templateEngine.js

@@ -0,0 +1,201 @@
+/**
+ * Template Engine — safe template resolution for recipe step outputs.
+ *
+ * Replaces the deprecated `vm2` approach with a pure AST-based evaluator.
+ * Supports: `{{steps.X.data}}`, `{{steps.X.data.field.subfield}}`, `{{env.Y}}`
+ *
+ * Security: No eval, no Function constructor, no VM. Just path walking.
+ */
+/**
+ * Compile a template string into an executable form.
+ * Parses `{{...}}` expressions once, not per-evaluation.
+ */
+export function compileTemplate(template) {
+    const parts = [];
+    // Match {{expression}} — non-greedy, no nesting
+    const regex = /\{\{([^{}]+)\}\}/g;
+    let lastIndex = 0;
+    let match;
+    while ((match = regex.exec(template)) !== null) {
+        // Add literal text before this match
+        if (match.index > lastIndex) {
+            parts.push(template.slice(lastIndex, match.index));
+        }
+        const expression = match[1]?.trim();
+        if (!expression) {
+            // Whitespace-only expression like `{{ }}` — preserve as literal so the
+            // surrounding text isn't duplicated on the next iteration. Without
+            // advancing lastIndex, the next slice(lastIndex, match.index) would
+            // re-emit text we already pushed above.
+            parts.push(match[0]);
+            lastIndex = regex.lastIndex;
+            continue;
+        }
+        const parsed = parseExpression(expression);
+        if (!parsed) {
+            return {
+                source: template,
+                hasTemplates: true,
+                evaluate: () => ({
+                    error: {
+                        type: "compile_error",
+                        template,
+                        message: `Invalid expression: ${expression}`,
+                    },
+                }),
+            };
+        }
+        parts.push(parsed);
+        lastIndex = regex.lastIndex;
+    }
+    // Add remaining literal text
+    if (lastIndex < template.length) {
+        parts.push(template.slice(lastIndex));
+    }
+    return {
+        source: template,
+        hasTemplates: parts.some((p) => typeof p !== "string"),
+        evaluate: (context) => evaluateCompiled(parts, context),
+    };
+}
+/**
+ * Parse an expression like "steps.X.data.field" or "env.HOME"
+ * Returns null if invalid syntax.
+ */
+function parseExpression(expr) {
+    const parts = expr.split(".");
+    if (parts.length < 2)
+        return null;
+    const root = parts[0];
+    const rest = parts.slice(1);
+    if (root === "steps" && rest.length >= 2) {
+        // steps.X.data or steps.X.data.field
+        return { path: expr, type: "step" };
+    }
+    if (root === "env" && rest.length === 1) {
+        // env.HOME
+        return { path: expr, type: "env" };
+    }
+    return null;
+}
+function evaluateCompiled(parts, context) {
+    const values = [];
+    for (const part of parts) {
+        if (typeof part === "string") {
+            values.push(part);
+            continue;
+        }
+        const result = evaluateExpression(part, context);
+        if ("error" in result) {
+            return result;
+        }
+        values.push(result.value);
+    }
+    return { value: values.join("") };
+}
+function evaluateExpression(expr, context) {
+    const parts = expr.path.split(".");
+    if (expr.type === "env") {
+        const key = parts[1];
+        if (!key)
+            return { value: "" };
+        // Object.hasOwn guards against prototype keys ("toString", "constructor",
+        // etc.) which would otherwise resolve to Object.prototype members.
+        const value = Object.hasOwn(context.env, key)
+            ? context.env[key]
+            : undefined;
+        return {
+            value: value ?? "",
+        };
+    }
+    // steps.X.data.path...
+    const stepId = parts[1];
+    const dataKey = parts[2];
+    const pathRest = parts.slice(3);
+    if (!stepId || !dataKey) {
+        return { value: "" };
+    }
+    const step = Object.hasOwn(context.steps, stepId)
+        ? context.steps[stepId]
+        : undefined;
+    if (!step) {
+        return {
+            error: {
+                type: "eval_error",
+                template: `{{${expr.path}}}`,
+                path: expr.path,
+                message: `Step '${stepId}' not found`,
+            },
+        };
+    }
+    if (dataKey !== "data" && dataKey !== "status" && dataKey !== "metadata") {
+        return {
+            error: {
+                type: "eval_error",
+                template: `{{${expr.path}}}`,
+                path: expr.path,
+                message: `Invalid step accessor '${dataKey}', expected 'data', 'status', or 'metadata'`,
+            },
+        };
+    }
+    let value = step[dataKey];
+    // Walk the rest of the path
+    for (const key of pathRest) {
+        if (value === null || value === undefined) {
+            return { value: "" }; // Missing path resolves to empty string
+        }
+        if (Array.isArray(value)) {
+            const index = parseInt(key, 10);
+            if (Number.isNaN(index) || index < 0 || index >= value.length) {
+                return { value: "" };
+            }
+            value = value[index];
+        }
+        else if (typeof value === "object") {
+            // Object.hasOwn guards against prototype keys leaking Object.prototype
+            // members (constructor, toString, valueOf, etc.) into the path walk.
+            const obj = value;
+            value = Object.hasOwn(obj, key) ? obj[key] : undefined;
+        }
+        else {
+            return { value: "" };
+        }
+    }
+    // Serialize to string
+    if (value === null || value === undefined) {
+        return { value: "" };
+    }
+    if (typeof value === "string") {
+        return { value };
+    }
+    // Functions and other non-JSON-serializable values stringify to undefined,
+    // which would silently violate the { value: string } contract. Coerce to "".
+    const serialized = JSON.stringify(value);
+    return { value: serialized ?? "" };
+}
+/**
+ * Convenience: compile and evaluate in one call.
+ * Prefer pre-compilation for repeated evaluations.
+ */
+export function evaluateTemplate(template, context) {
+    return compileTemplate(template).evaluate(context);
+}
+/**
+ * Validate all templates in a recipe at load time.
+ * Returns array of errors, empty if all valid.
+ */
+export function validateRecipeTemplates(templates) {
+    const errors = [];
+    for (const template of templates) {
+        const compiled = compileTemplate(template);
+        if (!compiled.hasTemplates)
+            continue; // literal — valid
+        // Probe with empty context: compile_error surfaces regardless of runtime values
+        const result = compiled.evaluate({ steps: {}, env: {} });
+        if ("error" in result && result.error.type === "compile_error") {
+            errors.push(result.error);
+        }
+    }
+    return errors;
+}
+//# sourceMappingURL=templateEngine.js.map

package/dist/recipes/templateEngine.js.map

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