patchwork-os 0.2.0-alpha.3 → 0.2.0-alpha.30

package/dist/commands/recipe.js

@@ -0,0 +1,1130 @@
+/**
+ * Recipe CLI commands — new, lint, test, watch, record, fmt
+ *
+ * Implements the A2 CLI UX milestone for recipe authoring.
+ */
+import { existsSync, mkdirSync, readFileSync, statSync, watch, writeFileSync, } from "node:fs";
+import os from "node:os";
+import { basename, dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import "../recipes/tools/index.js";
+import { loadFixtureLibrary } from "../connectors/fixtureLibrary.js";
+import { MockConnector } from "../connectors/mockConnector.js";
+import { normalizeRecipeForRuntime } from "../recipes/legacyRecipeCompat.js";
+import { generateSchemaSet, writeSchemas } from "../recipes/schemaGenerator.js";
+import { getTool, isConnectorNamespace, seedToolOutputPreviewContext, } from "../recipes/toolRegistry.js";
+import { validateRecipeDefinition, } from "../recipes/validation.js";
+import { buildChainedDeps, dispatchRecipe, loadYamlRecipe, render, runYamlRecipe, } from "../recipes/yamlRunner.js";
+import { findYamlRecipePath } from "../recipesHttp.js";
+const RECIPES_DIR = join(os.homedir(), ".patchwork", "recipes");
+const FIXTURES_DIR = join(os.homedir(), ".patchwork", "fixtures");
+const RECIPE_SCHEMA_HEADER = "# yaml-language-server: $schema=https://patchworkos.com/schema/recipe.v1.json";
+const RECIPE_API_VERSION = "patchwork.sh/v1";
+// ============================================================================
+// patchwork recipe new
+// ============================================================================
+const TEMPLATES = {
+    minimal: `apiVersion: ${RECIPE_API_VERSION}
+name: {{name}}
+description: {{description}}
+trigger:
+  type: manual
+steps:
+  - tool: file.write
+    path: ~/.patchwork/inbox/{{name}}.md
+    content: "Hello from {{name}}\\n"
+`,
+    daily: `apiVersion: ${RECIPE_API_VERSION}
+name: {{name}}
+description: {{description}}
+trigger:
+  type: cron
+  at: "0 9 * * 1-5"
+steps:
+  - tool: git.log_since
+    since: "24h"
+    into: commits
+  - agent:
+      prompt: |
+        Summarize these commits for a daily standup:
+        {{commits}}
+      into: summary
+  - tool: file.write
+    path: ~/.patchwork/inbox/{{name}}-{{date}}.md
+    content: "# {{name}}\\n\\n{{summary}}\\n"
+`,
+    inbox: `apiVersion: ${RECIPE_API_VERSION}
+name: {{name}}
+description: {{description}}
+trigger:
+  type: manual
+steps:
+  - tool: gmail.fetch_unread
+    since: "24h"
+    max: 20
+    into: unread
+  - tool: github.list_issues
+    assignee: "@me"
+    max: 10
+    into: issues
+  - agent:
+      prompt: |
+        Summarize my inbox. Unread emails: {{unread}}.
+        Assigned issues: {{issues}}.
+      into: summary
+  - tool: file.write
+    path: ~/.patchwork/inbox/{{name}}-{{date}}.md
+    content: "# {{name}}\\n\\n{{summary}}\\n"
+`,
+};
+export function runNew(options) {
+    if (!options.name) {
+        throw new Error("Recipe name is required");
+    }
+    if (!options.description) {
+        throw new Error("Recipe description is required");
+    }
+    const templateKey = options.template ?? "minimal";
+    const template = TEMPLATES[templateKey];
+    if (!template) {
+        throw new Error(`Unknown template: "${templateKey}". ` +
+            `Available: ${Object.keys(TEMPLATES).join(", ")}`);
+    }
+    const today = new Date().toISOString().split("T")[0] ?? "";
+    const body = template
+        .replace(/\{\{name\}\}/g, options.name)
+        .replace(/\{\{description\}\}/g, options.description)
+        .replace(/\{\{date\}\}/g, today);
+    const content = `${RECIPE_SCHEMA_HEADER}\n${body}`;
+    const outputDir = options.outputDir ?? RECIPES_DIR;
+    if (!existsSync(outputDir)) {
+        mkdirSync(outputDir, { recursive: true });
+    }
+    const outputPath = join(outputDir, `${options.name}.yaml`);
+    if (existsSync(outputPath)) {
+        throw new Error(`Recipe already exists: ${outputPath}`);
+    }
+    writeFileSync(outputPath, content);
+    return { path: outputPath, content };
+}
+export function listTemplates() {
+    return Object.keys(TEMPLATES);
+}
+export async function runSchema(outputDir) {
+    const resolvedOutputDir = resolve(outputDir);
+    const schemas = generateSchemaSet();
+    const filesWritten = [];
+    await writeSchemas(resolvedOutputDir, schemas, (filePath, content) => {
+        const dir = dirname(filePath);
+        if (!existsSync(dir)) {
+            mkdirSync(dir, { recursive: true });
+        }
+        writeFileSync(filePath, content);
+        filesWritten.push(filePath);
+    });
+    return {
+        outputDir: resolvedOutputDir,
+        filesWritten,
+    };
+}
+/**
+ * Lint a recipe file against the schema.
+ * Falls back to basic YAML parsing if schema linting is disabled.
+ */
+export function runLint(recipePath) {
+    // Check file exists
+    if (!existsSync(recipePath)) {
+        return {
+            valid: false,
+            issues: [{ level: "error", message: `File not found: ${recipePath}` }],
+            warnings: 0,
+            errors: 1,
+        };
+    }
+    let content;
+    try {
+        content = readFileSync(recipePath, "utf-8");
+    }
+    catch (err) {
+        return {
+            valid: false,
+            issues: [
+                {
+                    level: "error",
+                    message: `Failed to read file: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            warnings: 0,
+            errors: 1,
+        };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(content);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            issues: [
+                {
+                    level: "error",
+                    message: `YAML parse error: ${err instanceof Error ? err.message : String(err)}`,
+                },
+            ],
+            warnings: 0,
+            errors: 1,
+        };
+    }
+    const result = validateRecipeDefinition(parsed);
+    // For chained recipes, check that chain: file references resolve on disk.
+    const chainIssues = lintChainRefs(parsed, recipePath);
+    if (chainIssues.length > 0) {
+        result.issues.push(...chainIssues);
+        result.errors += chainIssues.filter((i) => i.level === "error").length;
+        result.warnings += chainIssues.filter((i) => i.level === "warning").length;
+        if (result.errors > 0) {
+            result.valid = false;
+        }
+    }
+    return result;
+}
+/**
+ * Walk chained recipe steps, check that chain:/recipe: refs resolve on disk,
+ * and recursively lint any child recipe that does resolve.
+ *
+ * `visited` tracks absolute paths already linted in this call chain to prevent
+ * infinite recursion when two recipes chain each other.
+ */
+function lintChainRefs(parsed, recipePath, visited = new Set()) {
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed))
+        return [];
+    const r = parsed;
+    const trigger = r.trigger && typeof r.trigger === "object"
+        ? r.trigger
+        : undefined;
+    if (trigger?.type !== "chained")
+        return [];
+    const steps = Array.isArray(r.steps)
+        ? r.steps
+        : [];
+    const recipeDir = dirname(recipePath);
+    const issues = [];
+    // Mark the current recipe as visited before descending.
+    const absPath = resolve(recipePath);
+    visited.add(absPath);
+    for (let i = 0; i < steps.length; i++) {
+        const step = steps[i];
+        if (!step)
+            continue;
+        issues.push(...lintStep(step, i + 1, recipeDir, visited));
+    }
+    return issues;
+}
+/**
+ * Check a single step (or recurse into its parallel: children).
+ * `stepLabel` is the 1-based position string used in issue messages.
+ */
+function lintStep(step, stepLabel, recipeDir, visited) {
+    const issues = [];
+    // Recurse into parallel: groups — each child is checked independently.
+    if (Array.isArray(step.parallel)) {
+        for (let j = 0; j < step.parallel.length; j++) {
+            const child = step.parallel[j];
+            if (!child || typeof child !== "object" || Array.isArray(child))
+                continue;
+            issues.push(...lintStep(child, stepLabel, recipeDir, visited));
+        }
+        return issues;
+    }
+    const ref = typeof step.chain === "string"
+        ? step.chain
+        : typeof step.recipe === "string"
+            ? step.recipe
+            : null;
+    if (!ref)
+        return issues;
+    const field = typeof step.chain === "string" ? "chain" : "recipe";
+    // Refs that look like file paths (extension or separator) → resolve relative to recipe dir.
+    const looksLikePath = /\.ya?ml$/i.test(ref) ||
+        ref.startsWith("./") ||
+        ref.startsWith("../") ||
+        /[\\/]/.test(ref);
+    if (looksLikePath) {
+        const resolved = /^\//.test(ref) ? ref : resolve(recipeDir, ref);
+        const candidates = /\.ya?ml$/i.test(resolved)
+            ? [resolved]
+            : [`${resolved}.yaml`, `${resolved}.yml`, resolved];
+        const childPath = candidates.find(existsSync) ?? null;
+        if (!childPath) {
+            issues.push({
+                level: "error",
+                message: `Step ${stepLabel}: '${field}: ${ref}' — file not found relative to recipe directory (${recipeDir})`,
+            });
+            return issues;
+        }
+        issues.push(...lintChildRecipe(childPath, field, ref, stepLabel, visited));
+        return issues;
+    }
+    // Named ref (no extension, no separator) → check ~/.patchwork/recipes/.
+    // Emit a warning rather than error: the recipe may be installed on the
+    // deploy target but not the author's machine.
+    if (existsSync(RECIPES_DIR)) {
+        const found = findYamlRecipePath(RECIPES_DIR, ref) ??
+            (existsSync(join(RECIPES_DIR, ref)) ? join(RECIPES_DIR, ref) : null);
+        if (!found) {
+            issues.push({
+                level: "warning",
+                message: `Step ${stepLabel}: '${field}: ${ref}' — recipe not found in ${RECIPES_DIR}`,
+            });
+        }
+        else {
+            issues.push(...lintChildRecipe(found, field, ref, stepLabel, visited));
+        }
+    }
+    return issues;
+}
+/**
+ * Read, parse, and validate a resolved child recipe path. Skips the file if
+ * it has already been visited (cycle). Issues are prefixed with the parent
+ * step context so the author knows where the problem originates.
+ */
+function lintChildRecipe(childPath, field, ref, stepNumber, visited) {
+    const absChild = resolve(childPath);
+    if (visited.has(absChild))
+        return []; // cycle — already linted
+    let childParsed;
+    try {
+        childParsed = parseYaml(readFileSync(childPath, "utf-8"));
+    }
+    catch (err) {
+        return [
+            {
+                level: "error",
+                message: `Step ${stepNumber}: '${field}: ${ref}' — could not read child recipe: ${err instanceof Error ? err.message : String(err)}`,
+            },
+        ];
+    }
+    const childResult = validateRecipeDefinition(childParsed);
+    const childChainIssues = lintChainRefs(childParsed, childPath, visited);
+    return [
+        ...childResult.issues.map((issue) => ({
+            ...issue,
+            message: `Step ${stepNumber}: '${field}: ${ref}' — child recipe invalid: ${issue.message}`,
+        })),
+        ...childChainIssues.map((issue) => ({
+            ...issue,
+            message: `Step ${stepNumber}: '${field}: ${ref}' — ${issue.message}`,
+        })),
+    ];
+}
+/**
+ * Format/normalize a recipe file.
+ * - Normalizes YAML formatting
+ * - Sorts keys in consistent order
+ * - Validates and re-serializes
+ */
+export function runFmt(recipePath, options = {}) {
+    const content = readFileSync(recipePath, "utf-8");
+    const { header: schemaHeader } = extractSchemaHeader(content);
+    const recipe = normalizeRecipeForRuntime(parseYaml(content), console.warn);
+    // Normalize key order
+    const normalized = {};
+    const keyOrder = [
+        "apiVersion",
+        "version",
+        "name",
+        "description",
+        "trigger",
+        "context",
+        "steps",
+        "expect",
+        "output",
+        "on_error",
+    ];
+    for (const key of keyOrder) {
+        if (key in recipe) {
+            normalized[key] = recipe[key];
+        }
+    }
+    // Add any extra keys at the end
+    for (const key of Object.keys(recipe)) {
+        if (!keyOrder.includes(key)) {
+            normalized[key] = recipe[key];
+        }
+    }
+    // Re-serialize with consistent formatting
+    const formattedBody = stringifyYaml(normalized, {
+        indent: 2,
+        lineWidth: 100,
+    });
+    const formatted = schemaHeader
+        ? `${schemaHeader}\n${formattedBody}`
+        : formattedBody;
+    const changed = formatted.trim() !== content.trim();
+    if (!options.check) {
+        writeFileSync(recipePath, formatted);
+    }
+    return { formatted, changed };
+}
+/**
+ * Watch a recipe file and re-run `runFmt` on every save (debounced).
+ * Mirrors runPreflightWatch / runTestWatch — composes runWatch + runFmt.
+ * Returns a stop function.
+ */
+export function runFmtWatch(options) {
+    const { recipePath, check, onResult, onError, debounceMs, watchFactory } = options;
+    return runWatch({
+        recipePath,
+        onChange: async () => {
+            const result = runFmt(recipePath, { check });
+            await onResult(result);
+        },
+        ...(onError ? { onError } : {}),
+        ...(debounceMs !== undefined ? { debounceMs } : {}),
+        ...(watchFactory ? { watchFactory } : {}),
+    });
+}
+function extractSchemaHeader(content) {
+    if (content.startsWith(`${RECIPE_SCHEMA_HEADER}\n`)) {
+        return { header: RECIPE_SCHEMA_HEADER };
+    }
+    return {};
+}
+export async function runRecipe(recipeRef, options = {}) {
+    const recipePath = resolveRecipePath(recipeRef);
+    const recipe = loadYamlRecipe(recipePath);
+    const triggerType = recipe.trigger?.type;
+    if (options.step && triggerType === "chained") {
+        throw new Error(`Single-step execution is not supported for chained recipes: ${recipe.name}`);
+    }
+    const selection = options.step
+        ? selectRecipeStep(recipe, options.step)
+        : undefined;
+    const recipeToRun = selection
+        ? { ...recipe, steps: [selection.step] }
+        : recipe;
+    const runnerDeps = {
+        ...options.deps,
+        workdir: options.workdir ?? options.deps?.workdir ?? process.cwd(),
+    };
+    if (options.dryRun) {
+        throw new Error("runRecipeDryPlan must be used for dry-run execution");
+    }
+    const result = await dispatchRecipe(recipeToRun, {
+        ...runnerDeps,
+        chainedDeps: buildChainedDeps(runnerDeps),
+        chainedOptions: { sourcePath: recipePath },
+    }, options.vars ?? {});
+    return {
+        recipe,
+        recipePath,
+        result,
+        ...(selection
+            ? {
+                stepSelection: {
+                    query: selection.query,
+                    matchedBy: selection.matchedBy,
+                    matchedValue: selection.matchedValue,
+                },
+            }
+            : {}),
+    };
+}
+export function summarizeRecipeExecution(result) {
+    if ("stepsRun" in result) {
+        return {
+            ok: !result.errorMessage,
+            steps: result.stepsRun,
+            outputs: result.outputs,
+            ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
+        };
+    }
+    return {
+        ok: result.success,
+        steps: result.summary.total,
+        outputs: [],
+        ...(result.errorMessage ? { errorMessage: result.errorMessage } : {}),
+        failed: result.summary.failed,
+        skipped: result.summary.skipped,
+    };
+}
+/**
+ * Normalize either a yamlRunner RunResult or a chainedRunner ChainedRunResult
+ * into the RunStepResult[] shape expected by RecipeRunLog.appendDirect.
+ * Returns undefined when the result has no step-level detail.
+ */
+export function extractRunLogStepResults(result) {
+    if ("stepsRun" in result) {
+        // yamlRunner: stepResults is already StepResult[]
+        if (!Array.isArray(result.stepResults))
+            return undefined;
+        return result.stepResults.map((s) => ({
+            id: s.id,
+            ...(s.tool ? { tool: s.tool } : {}),
+            status: s.status,
+            ...(s.error ? { error: s.error } : {}),
+            durationMs: s.durationMs,
+        }));
+    }
+    // chainedRunner: stepResults is Map<string, ChainedStepRunResult>
+    return [...result.stepResults.entries()].map(([id, s]) => ({
+        id,
+        status: s.skipped ? "skipped" : s.success ? "ok" : "error",
+        durationMs: s.durationMs ?? 0,
+        ...(s.error ? { error: s.error.message } : {}),
+    }));
+}
+export function formatRunReport(result, recipeName) {
+    const lines = [];
+    const hr = "─".repeat(48);
+    if ("stepsRun" in result) {
+        // Simple (non-chained) recipe — compact summary
+        const ok = !result.errorMessage;
+        lines.push(`${ok ? "✓" : "✗"} ${recipeName} — ${result.stepsRun} step(s)`);
+        if (result.outputs.length > 0) {
+            for (const o of result.outputs)
+                lines.push(`  → ${o}`);
+        }
+        if (result.errorMessage)
+            lines.push(`  Error: ${result.errorMessage}`);
+        return lines.join("\n");
+    }
+    // Chained recipe — per-step table
+    const { stepResults, summary } = result;
+    const overallOk = result.success;
+    lines.push(hr);
+    lines.push(`Recipe: ${recipeName}`);
+    lines.push(hr);
+    for (const [id, step] of stepResults) {
+        const icon = step.skipped ? "↷" : step.success ? "✓" : "✗";
+        const dur = step.durationMs !== undefined ? ` (${step.durationMs}ms)` : "";
+        const err = step.error ? `  → ${step.error.message}` : "";
+        lines.push(`  ${icon} ${id}${dur}${err}`);
+    }
+    lines.push(hr);
+    const parts = [`${summary.succeeded} ok`];
+    if (summary.skipped > 0)
+        parts.push(`${summary.skipped} skipped`);
+    if (summary.failed > 0)
+        parts.push(`${summary.failed} failed`);
+    lines.push(`${overallOk ? "✓" : "✗"} ${parts.join(" · ")}`);
+    return lines.join("\n");
+}
+export async function runWatchedRecipe(recipePath, options = {}) {
+    const lint = runLint(recipePath);
+    if (!lint.valid) {
+        return { lint };
+    }
+    const run = await runRecipe(recipePath, options);
+    return {
+        lint,
+        run,
+        summary: summarizeRecipeExecution(run.result),
+    };
+}
+/**
+ * Stable JSON schema version for machine-readable dry-run plans.
+ * Bump on breaking shape changes; consumers (dashboard run timeline, external tools)
+ * should gate on this field.
+ */
+export const DRY_RUN_PLAN_SCHEMA_VERSION = 1;
+function enrichStepFromRegistry(step) {
+    if (step.type !== "tool" || !step.tool) {
+        return step;
+    }
+    const namespace = step.tool.split(".")[0];
+    const registered = getTool(step.tool);
+    const enriched = { ...step };
+    if (namespace)
+        enriched.namespace = namespace;
+    enriched.resolved = Boolean(registered);
+    if (registered) {
+        enriched.isWrite = registered.isWrite;
+        enriched.isConnector = registered.isConnector === true;
+        if (enriched.risk === undefined) {
+            enriched.risk = registered.riskDefault;
+        }
+    }
+    return enriched;
+}
+function summarizePlanSteps(steps) {
+    const connectors = new Set();
+    let hasWrite = false;
+    for (const step of steps) {
+        if (step.isConnector && step.namespace)
+            connectors.add(step.namespace);
+        if (step.isWrite)
+            hasWrite = true;
+    }
+    return {
+        connectorNamespaces: [...connectors].sort(),
+        hasWriteSteps: hasWrite,
+    };
+}
+export async function runRecipeDryPlan(recipeRef, options = {}) {
+    const recipePath = resolveRecipePath(recipeRef);
+    const recipe = loadYamlRecipe(recipePath);
+    const triggerType = recipe.trigger?.type;
+    const selection = options.step
+        ? selectRecipeStep(recipe, options.step)
+        : undefined;
+    const recipeToPlan = selection
+        ? { ...recipe, steps: [selection.step] }
+        : recipe;
+    const generatedAt = new Date().toISOString();
+    if (triggerType === "chained") {
+        const { generateExecutionPlan } = await import("../recipes/chainedRunner.js");
+        const plan = generateExecutionPlan(recipeToPlan);
+        const steps = plan.steps.map((step) => {
+            const base = { id: step.id, type: step.type };
+            if (step.optional !== undefined)
+                base.optional = step.optional;
+            if (step.dependencies)
+                base.dependencies = step.dependencies;
+            if (step.condition !== undefined)
+                base.condition = step.condition;
+            if (step.risk !== undefined)
+                base.risk = step.risk;
+            const raw = step;
+            if (typeof raw.tool === "string")
+                base.tool = raw.tool;
+            if (typeof raw.into === "string")
+                base.into = raw.into;
+            return enrichStepFromRegistry(base);
+        });
+        return {
+            schemaVersion: DRY_RUN_PLAN_SCHEMA_VERSION,
+            generatedAt,
+            recipe: recipe.name,
+            mode: "dry-run",
+            triggerType,
+            ...(selection ? { stepSelection: toStepSelection(selection) } : {}),
+            steps,
+            parallelGroups: plan.parallelGroups,
+            maxDepth: plan.maxDepth,
+            ...summarizePlanSteps(steps),
+        };
+    }
+    const steps = buildSimpleRecipeDryRunSteps(recipeToPlan, options.vars ?? {}).map(enrichStepFromRegistry);
+    return {
+        schemaVersion: DRY_RUN_PLAN_SCHEMA_VERSION,
+        generatedAt,
+        recipe: recipe.name,
+        mode: "dry-run",
+        triggerType: typeof triggerType === "string" ? triggerType : "manual",
+        ...(selection ? { stepSelection: toStepSelection(selection) } : {}),
+        steps,
+        ...summarizePlanSteps(steps),
+    };
+}
+/**
+ * Static policy check over a recipe: lint + dry-plan + unresolved/write/fixture checks.
+ * No connector calls, no agent calls — safe to run in CI.
+ */
+export async function runPreflight(recipeRef, options = {}) {
+    const recipePath = resolveRecipePath(recipeRef);
+    const issues = [];
+    const lint = runLint(recipePath);
+    for (const issue of lint.issues) {
+        issues.push({
+            level: issue.level,
+            code: issue.level === "error" ? "lint-error" : "lint-warning",
+            message: issue.message,
+        });
+    }
+    const plan = await runRecipeDryPlan(recipeRef, options);
+    const requireWriteAck = options.requireWriteAck ?? true;
+    const allowlist = new Set(options.allowWrites ?? []);
+    for (const step of plan.steps) {
+        if (step.type === "tool" && step.tool && step.resolved === false) {
+            issues.push({
+                level: "error",
+                code: "unresolved-tool",
+                message: `Tool "${step.tool}" is not registered`,
+                stepId: step.id,
+                tool: step.tool,
+                ...(step.namespace ? { namespace: step.namespace } : {}),
+            });
+        }
+        if (requireWriteAck &&
+            step.isWrite === true &&
+            step.tool &&
+            !allowlist.has(step.tool) &&
+            !(step.namespace && allowlist.has(step.namespace))) {
+            issues.push({
+                level: "error",
+                code: "unacknowledged-write",
+                message: `Step "${step.id}" performs a write via "${step.tool}" but is not acknowledged via allowWrites`,
+                stepId: step.id,
+                tool: step.tool,
+                ...(step.namespace ? { namespace: step.namespace } : {}),
+            });
+        }
+    }
+    if (options.requireFixtures && plan.connectorNamespaces) {
+        const fixturesDir = options.fixturesDir ?? FIXTURES_DIR;
+        for (const ns of plan.connectorNamespaces) {
+            const library = loadFixtureLibrary(join(fixturesDir, `${ns}.json`));
+            if (!library) {
+                issues.push({
+                    level: "error",
+                    code: "missing-fixture",
+                    message: `Missing fixture library for connector "${ns}" at ${fixturesDir}/${ns}.json`,
+                    namespace: ns,
+                });
+            }
+        }
+    }
+    const ok = !issues.some((issue) => issue.level === "error");
+    return { ok, recipe: plan.recipe, issues, plan };
+}
+/**
+ * Watch a recipe file and run preflight on every save (debounced). Composes
+ * runWatch + runPreflight so editor integrations get live policy feedback
+ * without spawning the CLI per keystroke.
+ *
+ * Returns a stop function. If a preflight is in-flight when a new save lands,
+ * at most one rerun is queued (matches runWatch semantics).
+ */
+export function runPreflightWatch(options) {
+    const { recipePath, onResult, onError, debounceMs, watchFactory, ...preflightOptions } = options;
+    const watchOptions = {
+        recipePath,
+        onChange: async () => {
+            const result = await runPreflight(recipePath, preflightOptions);
+            await onResult(result);
+        },
+        ...(onError ? { onError } : {}),
+        ...(debounceMs !== undefined ? { debounceMs } : {}),
+        ...(watchFactory ? { watchFactory } : {}),
+    };
+    return runWatch(watchOptions);
+}
+function resolveRecipePath(recipeRef) {
+    const directPath = resolve(recipeRef);
+    if (existsSync(directPath) && statSync(directPath).isFile()) {
+        return directPath;
+    }
+    const bundledDir = fileURLToPath(new URL("../../templates/recipes", import.meta.url));
+    const normalizedRef = recipeRef.replace(/\.(yaml|yml|json)$/i, "");
+    const candidates = [
+        join(RECIPES_DIR, `${normalizedRef}.yaml`),
+        join(RECIPES_DIR, `${normalizedRef}.yml`),
+        join(RECIPES_DIR, `${normalizedRef}.json`),
+        join(bundledDir, `${normalizedRef}.yaml`),
+        join(bundledDir, `${normalizedRef}.yml`),
+    ];
+    for (const candidate of candidates) {
+        if (existsSync(candidate) && statSync(candidate).isFile()) {
+            return candidate;
+        }
+    }
+    throw new Error(`recipe "${basename(recipeRef)}" not found in ${RECIPES_DIR}`);
+}
+function selectRecipeStep(recipe, query) {
+    const matches = recipe.steps
+        .map((step) => {
+        const match = matchRecipeStep(step, query);
+        return match ? { ...match, query, step } : undefined;
+    })
+        .filter((match) => Boolean(match));
+    if (matches.length === 0) {
+        throw new Error(`Step "${query}" not found in recipe "${recipe.name}"`);
+    }
+    if (matches.length > 1) {
+        const labels = matches
+            .map((match) => `${match.matchedBy}:${match.matchedValue}`)
+            .join(", ");
+        throw new Error(`Step "${query}" is ambiguous in recipe "${recipe.name}": ${labels}`);
+    }
+    const [match] = matches;
+    if (!match) {
+        throw new Error(`Step "${query}" not found in recipe "${recipe.name}"`);
+    }
+    return match;
+}
+function matchRecipeStep(step, query) {
+    const id = typeof step.id === "string" ? step.id : undefined;
+    if (id === query) {
+        return { matchedBy: "id", matchedValue: id };
+    }
+    const into = getStepInto(step);
+    if (into === query) {
+        return { matchedBy: "into", matchedValue: into };
+    }
+    const tool = typeof step.tool === "string" ? step.tool : undefined;
+    if (tool === query) {
+        return { matchedBy: "tool", matchedValue: tool };
+    }
+    return null;
+}
+function getStepInto(step) {
+    if (typeof step.into === "string" && step.into) {
+        return step.into;
+    }
+    if (step.agent &&
+        typeof step.agent === "object" &&
+        typeof step.agent.into === "string" &&
+        step.agent.into) {
+        return step.agent.into;
+    }
+    return undefined;
+}
+function toStepSelection(selection) {
+    return {
+        query: selection.query,
+        matchedBy: selection.matchedBy,
+        matchedValue: selection.matchedValue,
+    };
+}
+function buildSimpleRecipeDryRunSteps(recipe, vars) {
+    const now = new Date();
+    const ctx = {
+        date: now.toISOString().slice(0, 10),
+        time: now.toTimeString().slice(0, 5),
+        ...vars,
+    };
+    return recipe.steps.map((step, index) => {
+        const id = (typeof step.id === "string" && step.id) ||
+            getStepInto(step) ||
+            step.tool ||
+            `step_${index}`;
+        if (step.agent) {
+            const prompt = render(step.agent.prompt, ctx);
+            const into = getStepInto(step);
+            if (into) {
+                ctx[into] = `[dry-run:${id}]`;
+            }
+            return {
+                id,
+                type: "agent",
+                into,
+                optional: step.optional,
+                prompt,
+            };
+        }
+        const params = {};
+        for (const [key, value] of Object.entries(step)) {
+            if (key === "tool" || key === "agent" || key === "into" || key === "id") {
+                continue;
+            }
+            params[key] = typeof value === "string" ? render(value, ctx) : value;
+        }
+        const into = getStepInto(step);
+        if (into) {
+            ctx[into] = `[dry-run:${id}]`;
+            if (step.tool) {
+                seedToolOutputPreviewContext(step.tool, into, id, ctx);
+            }
+        }
+        return {
+            id,
+            type: "tool",
+            tool: step.tool,
+            into,
+            optional: step.optional,
+            params,
+        };
+    });
+}
+export async function runRecord(recipePath, options = {}) {
+    const lint = runLint(recipePath);
+    const issues = [...lint.issues];
+    const fixturesDir = options.fixturesDir ?? FIXTURES_DIR;
+    let recordedFixtures = [];
+    let stepsRun = 0;
+    let outputs = [];
+    if (issues.every((issue) => issue.level !== "error")) {
+        try {
+            const recipe = loadYamlRecipe(recipePath);
+            recordedFixtures = getRequiredFixtureNamespaces(recipe.steps);
+            const run = await runYamlRecipe(recipe, {
+                ...options.deps,
+                recordFixturesDir: fixturesDir,
+            });
+            stepsRun = run.stepsRun;
+            outputs = run.outputs;
+            if (run.errorMessage) {
+                issues.push({
+                    level: "error",
+                    message: run.errorMessage,
+                });
+            }
+        }
+        catch (err) {
+            issues.push({
+                level: "error",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const errors = issues.filter((issue) => issue.level === "error").length;
+    const warnings = issues.filter((issue) => issue.level === "warning").length;
+    return {
+        valid: errors === 0,
+        issues,
+        warnings,
+        errors,
+        recordedFixtures,
+        stepsRun,
+        outputs,
+    };
+}
+export async function runTest(recipePath, options = {}) {
+    const lint = runLint(recipePath);
+    const fixturesDir = options.fixturesDir ?? FIXTURES_DIR;
+    const issues = [...lint.issues];
+    let requiredFixtures = [];
+    let stepsRun = 0;
+    let outputs = [];
+    let assertionFailures = [];
+    if (existsSync(recipePath)) {
+        try {
+            const recipe = parseYaml(readFileSync(recipePath, "utf-8"));
+            requiredFixtures = getRequiredFixtureNamespaces(recipe.steps ?? []);
+        }
+        catch {
+            requiredFixtures = [];
+        }
+    }
+    const missingFixtures = requiredFixtures.filter((provider) => !existsSync(join(fixturesDir, `${provider}.json`)));
+    for (const provider of missingFixtures) {
+        issues.push({
+            level: "error",
+            message: `Missing fixture library for connector '${provider}' at ${join(fixturesDir, `${provider}.json`)}`,
+        });
+    }
+    if (issues.every((issue) => issue.level !== "error")) {
+        try {
+            const recipe = loadYamlRecipe(recipePath);
+            const triggerType = recipe.trigger?.type;
+            if (triggerType === "chained") {
+                // Chained recipes: run through chainedRunner with mocked tool + agent executors
+                const { runChainedRecipe } = await import("../recipes/chainedRunner.js");
+                const { evaluateExpect } = await import("../recipes/yamlRunner.js");
+                const chainedRecipe = recipe;
+                const recipeRecord = recipe;
+                const run = await runChainedRecipe(chainedRecipe, {
+                    env: process.env,
+                    maxConcurrency: recipeRecord.maxConcurrency ?? 4,
+                    maxDepth: recipeRecord.maxDepth ?? 3,
+                    dryRun: false,
+                    sourcePath: recipePath,
+                }, {
+                    executeTool: async (tool) => `[mock:${tool}]`,
+                    executeAgent: async () => "[mock agent output]",
+                    loadNestedRecipe: async () => null,
+                });
+                stepsRun = run.summary.total;
+                if (run.errorMessage) {
+                    issues.push({ level: "error", message: run.errorMessage });
+                }
+                // Evaluate expect: block against chained run results
+                const expectBlock = recipeRecord.expect;
+                if (expectBlock) {
+                    const failures = evaluateExpect({
+                        stepsRun: run.summary.total,
+                        outputs: [],
+                        context: run.context,
+                        errorMessage: run.errorMessage,
+                    }, expectBlock);
+                    assertionFailures = failures;
+                    for (const failure of failures) {
+                        issues.push({ level: "error", message: failure.message });
+                    }
+                }
+            }
+            else {
+                const mockConnectors = createMockToolConnectors(recipe.steps, fixturesDir);
+                const run = await runYamlRecipe(recipe, {
+                    testMode: true,
+                    mockConnectors,
+                    readFile: (filePath) => readFileSync(filePath, "utf-8"),
+                    writeFile: () => { },
+                    appendFile: () => { },
+                    mkdir: () => { },
+                    gitLogSince: () => "[mock git log]",
+                    gitStaleBranches: () => "[mock stale branches]",
+                    getDiagnostics: () => "[mock diagnostics]",
+                    claudeFn: async () => "[mock agent output]",
+                    claudeCodeFn: async () => "[mock agent output]",
+                    providerDriverFn: async () => "[mock agent output]",
+                });
+                stepsRun = run.stepsRun;
+                outputs = run.outputs;
+                if (run.assertionFailures && run.assertionFailures.length > 0) {
+                    assertionFailures = run.assertionFailures;
+                    for (const failure of run.assertionFailures) {
+                        issues.push({ level: "error", message: failure.message });
+                    }
+                }
+                if (run.errorMessage) {
+                    issues.push({ level: "error", message: run.errorMessage });
+                }
+            }
+        }
+        catch (err) {
+            issues.push({
+                level: "error",
+                message: err instanceof Error ? err.message : String(err),
+            });
+        }
+    }
+    const errors = issues.filter((issue) => issue.level === "error").length;
+    const warnings = issues.filter((issue) => issue.level === "warning").length;
+    return {
+        valid: errors === 0,
+        issues,
+        warnings,
+        errors,
+        requiredFixtures,
+        missingFixtures,
+        stepsRun,
+        outputs,
+        assertionFailures,
+    };
+}
+/**
+ * Watch a recipe file and re-run `patchwork recipe test` on every save (debounced).
+ * Mirrors runPreflightWatch — composes runWatch + runTest.
+ * Returns a stop function.
+ */
+export function runTestWatch(options) {
+    const { recipePath, fixturesDir, onResult, onError, debounceMs, watchFactory, } = options;
+    return runWatch({
+        recipePath,
+        onChange: async () => {
+            const result = await runTest(recipePath, { fixturesDir });
+            await onResult(result);
+        },
+        ...(onError ? { onError } : {}),
+        ...(debounceMs !== undefined ? { debounceMs } : {}),
+        ...(watchFactory ? { watchFactory } : {}),
+    });
+}
+function getRequiredFixtureNamespaces(steps) {
+    const namespaces = new Set();
+    for (const step of steps) {
+        const tool = step.tool;
+        if (typeof tool !== "string") {
+            continue;
+        }
+        const namespace = tool.split(".")[0];
+        if (namespace && isConnectorNamespace(namespace)) {
+            namespaces.add(namespace);
+        }
+    }
+    return [...namespaces].sort();
+}
+function createMockToolConnectors(steps, fixturesDir) {
+    const providerConnectors = new Map();
+    const toolConnectors = {};
+    for (const step of steps) {
+        const tool = step.tool;
+        if (typeof tool !== "string") {
+            continue;
+        }
+        const [namespace, operation] = tool.split(".");
+        if (!namespace || !operation || !isConnectorNamespace(namespace)) {
+            continue;
+        }
+        let connector = providerConnectors.get(namespace);
+        if (!connector) {
+            connector = new MockConnector(namespace, {
+                fixturePath: join(fixturesDir, `${namespace}.json`),
+            });
+            providerConnectors.set(namespace, connector);
+        }
+        toolConnectors[tool] = {
+            invoke: async (_unusedOperation, input) => {
+                const output = await connector.invoke(operation, input);
+                return (typeof output === "string" ? output : JSON.stringify(output));
+            },
+        };
+    }
+    return toolConnectors;
+}
+function normalizeChangedFile(changedFile) {
+    if (typeof changedFile === "string") {
+        return changedFile;
+    }
+    if (changedFile instanceof Buffer) {
+        return changedFile.toString();
+    }
+    return null;
+}
+export function runWatch(options) {
+    const dir = dirname(resolve(options.recipePath));
+    const filename = basename(options.recipePath);
+    const debounceMs = options.debounceMs ?? 300;
+    const watchFactory = options.watchFactory ??
+        ((watchPath, watchOptions, listener) => watch(watchPath, watchOptions, listener));
+    let debounceTimer = null;
+    let running = false;
+    let rerunQueued = false;
+    let stopped = false;
+    const handleError = (err) => {
+        options.onError?.(err instanceof Error ? err : new Error(String(err)));
+    };
+    const finishChange = () => {
+        running = false;
+        if (stopped || !rerunQueued) {
+            return;
+        }
+        rerunQueued = false;
+        executeChange();
+    };
+    const executeChange = () => {
+        if (stopped) {
+            return;
+        }
+        if (running) {
+            rerunQueued = true;
+            return;
+        }
+        running = true;
+        try {
+            const changeResult = options.onChange();
+            void Promise.resolve(changeResult)
+                .catch(handleError)
+                .finally(finishChange);
+        }
+        catch (err) {
+            handleError(err);
+            finishChange();
+        }
+    };
+    const scheduleChange = () => {
+        if (stopped) {
+            return;
+        }
+        if (running) {
+            rerunQueued = true;
+            return;
+        }
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+        }
+        debounceTimer = setTimeout(() => {
+            debounceTimer = null;
+            executeChange();
+        }, debounceMs);
+    };
+    const watcher = watchFactory(dir, { recursive: false }, (_eventType, changedFile) => {
+        const changedName = normalizeChangedFile(changedFile);
+        if (changedName === filename) {
+            scheduleChange();
+        }
+    });
+    // Return cleanup function
+    return () => {
+        stopped = true;
+        if (debounceTimer) {
+            clearTimeout(debounceTimer);
+            debounceTimer = null;
+        }
+        watcher.close();
+    };
+}
+//# sourceMappingURL=recipe.js.map