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

package/dist/commands/recipe.js

@@ -0,0 +1,1359 @@
+/**
+ * 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 { defaultDeprecationWarn, normalizeRecipeForRuntime, } from "../recipes/legacyRecipeCompat.js";
+import { tryResolveRecipePath } from "../recipes/resolveRecipePath.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";
+import { findInstalledRecipeEntrypoint } from "./recipeInstall.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://raw.githubusercontent.com/patchworkos/recipes/main/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)) {
+        let found = null;
+        try {
+            found =
+                findYamlRecipePath(RECIPES_DIR, ref) ??
+                    (existsSync(join(RECIPES_DIR, ref)) ? join(RECIPES_DIR, ref) : null);
+        }
+        catch (err) {
+            issues.push({
+                level: "error",
+                message: `Step ${stepLabel}: '${field}: ${ref}' — ${err instanceof Error ? err.message : String(err)}`,
+            });
+            return issues;
+        }
+        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), defaultDeprecationWarn);
+    // 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;
+        // F-07 fix: nested-recipe writes detected via recursion count too.
+        if (step.nestedWriteCount && step.nestedWriteCount > 0)
+            hasWrite = true;
+    }
+    return {
+        connectorNamespaces: [...connectors].sort(),
+        hasWriteSteps: hasWrite,
+    };
+}
+/**
+ * F-07 fix: hard cap on nested-recipe recursion depth used by the dry-plan
+ * write detector. The chained recipe schema's `maxDepth` (default 3) is the
+ * runtime cap; the dry-plan applies `min(recipe.maxDepth ?? 3, MAX_DEPTH)`
+ * so a malicious or buggy recipe can't make the planner walk an unbounded
+ * tree. Per PLAN-MASTER-V2.md (R2-H1), 5 is the hard cap.
+ */
+const F07_MAX_NESTED_DEPTH = 5;
+/**
+ * F-07 fix: resolve a nested-recipe reference (bare name or path-shape)
+ * to an absolute file path the dry-plan can load synchronously. Mirrors
+ * the resolution logic in `yamlRunner.ts`'s async `loadNestedRecipe` but
+ * keeps to the synchronous subset (no symlink walks, no async I/O) since
+ * the dry-plan is itself synchronous after the chained-runner import.
+ *
+ * Returns null if the candidate cannot be resolved within the allowed
+ * roots — the recursion treats null as "unknown writes" (omits the
+ * `nestedWriteCount` field) so a missing reference does not falsely mark
+ * the parent as `hasWriteSteps:false` when it might write.
+ *
+ * Allowed roots:
+ *   - parent recipe's directory (for relative `recipe: ./inner.yaml`)
+ *   - `~/.patchwork/recipes/` (for bare `recipe: branch-health`)
+ *
+ * The bundled-templates dir is intentionally NOT searched here — bundled
+ * templates are vendor-controlled, the dry-plan recursion is for user
+ * recipes that may legitimately reference user-installed sub-recipes.
+ */
+function resolveNestedRecipeForDryPlan(ref, parentRecipePath) {
+    if (typeof ref !== "string" || ref.length === 0)
+        return null;
+    if (ref.includes("\x00"))
+        return null;
+    // node:path / node:os / node:fs are imported at the top of this file
+    // (see resolve, dirname, join above). statSync is not currently in scope
+    // so we re-pull from the already-imported namespace via the bare module
+    // — TS resolves this through the same package that `import os from "node:os"`
+    // uses. No dynamic require: this stays synchronous and ESM-friendly.
+    const parentDir = dirname(parentRecipePath);
+    const userRecipesDir = join(os.homedir(), ".patchwork", "recipes");
+    const pathLike = /^([./]|\.\.[/\\]|[A-Za-z]:[/\\])/.test(ref) ||
+        /[\\/]/.test(ref) ||
+        /\.ya?ml$/i.test(ref);
+    const candidates = [];
+    if (pathLike) {
+        const base = /^([./]|[A-Za-z]:[/\\])/.test(ref)
+            ? resolve(parentDir, ref)
+            : resolve(ref);
+        // resolve() already absolutized; if it was already absolute we re-resolve.
+        const absolute = resolve(base);
+        if (/\.ya?ml$/i.test(absolute)) {
+            candidates.push(absolute);
+        }
+        else {
+            candidates.push(`${absolute}.yaml`, `${absolute}.yml`, absolute);
+        }
+    }
+    else {
+        candidates.push(join(userRecipesDir, `${ref}.yaml`), join(userRecipesDir, `${ref}.yml`));
+    }
+    const allowedRoots = [parentDir, userRecipesDir];
+    const isInside = (file, root) => {
+        const rf = resolve(file);
+        const rr = resolve(root);
+        return rf === rr || rf.startsWith(`${rr}/`) || rf.startsWith(`${rr}\\`);
+    };
+    for (const candidate of candidates) {
+        const inJail = allowedRoots.some((root) => isInside(candidate, root));
+        if (!inJail)
+            continue;
+        try {
+            if (existsSync(candidate)) {
+                const st = statSync(candidate);
+                if (st.isFile())
+                    return candidate;
+            }
+        }
+        catch {
+            /* not found; try next */
+        }
+    }
+    return null;
+}
+/**
+ * F-07 fix: recursively resolve nested-recipe steps in a chained dry-plan
+ * to detect writes. Mutates `steps` in place to set `nestedWriteCount` for
+ * any `type === "recipe"` step whose nested recipe could be loaded.
+ *
+ * Visited set prevents cycles (A → B → A) from looping; cycles count as
+ * 0 writes for the cycle edge so the parent's existing writes still
+ * dominate. Depth cap is `min(recipe.maxDepth ?? 3, F07_MAX_NESTED_DEPTH)`.
+ */
+async function detectNestedRecipeWritesInPlan(steps, parentRecipePath, recipeMaxDepth, visited = new Set(), depth = 0) {
+    const cap = Math.min(recipeMaxDepth, F07_MAX_NESTED_DEPTH);
+    if (depth >= cap)
+        return;
+    for (const step of steps) {
+        if (step.type !== "recipe" || !step.recipe)
+            continue;
+        const nestedPath = resolveNestedRecipeForDryPlan(step.recipe, parentRecipePath);
+        if (!nestedPath)
+            continue;
+        if (visited.has(nestedPath)) {
+            // Cycle — count as 0 writes for this edge to break the loop.
+            step.nestedWriteCount = 0;
+            continue;
+        }
+        let nestedRecipe;
+        try {
+            nestedRecipe = loadYamlRecipe(nestedPath);
+        }
+        catch {
+            // Unparseable / unreadable nested recipe → treat as unknown writes
+            // (omit nestedWriteCount). Don't fail the whole dry-plan over a
+            // single broken sub-recipe.
+            continue;
+        }
+        const nextVisited = new Set(visited);
+        nextVisited.add(nestedPath);
+        // Build dry-run steps for the nested recipe and recurse.
+        const nestedTriggerType = nestedRecipe.trigger?.type;
+        let nestedSteps;
+        let nestedMaxDepth = recipeMaxDepth;
+        if (nestedTriggerType === "chained") {
+            const { generateExecutionPlan } = await import("../recipes/chainedRunner.js");
+            const plan = generateExecutionPlan(nestedRecipe);
+            nestedMaxDepth = plan.maxDepth;
+            nestedSteps = plan.steps.map((s) => {
+                const base = { id: s.id, type: s.type };
+                if (s.tool !== undefined)
+                    base.tool = s.tool;
+                if (s.into !== undefined)
+                    base.into = s.into;
+                if (s.recipe !== undefined)
+                    base.recipe = s.recipe;
+                if (s.optional !== undefined)
+                    base.optional = s.optional;
+                if (s.dependencies)
+                    base.dependencies = s.dependencies;
+                if (s.condition !== undefined)
+                    base.condition = s.condition;
+                if (s.risk !== undefined)
+                    base.risk = s.risk;
+                return enrichStepFromRegistry(base);
+            });
+        }
+        else {
+            nestedSteps = buildSimpleRecipeDryRunSteps(nestedRecipe, {}).map(enrichStepFromRegistry);
+        }
+        // Recurse before counting so deeper nested writes propagate up.
+        await detectNestedRecipeWritesInPlan(nestedSteps, nestedPath, nestedMaxDepth, nextVisited, depth + 1);
+        let count = 0;
+        for (const ns of nestedSteps) {
+            if (ns.isWrite)
+                count += 1;
+            if (ns.nestedWriteCount && ns.nestedWriteCount > 0) {
+                count += ns.nestedWriteCount;
+            }
+        }
+        step.nestedWriteCount = count;
+    }
+}
+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();
+    // Collect lint results for the plan
+    const lintResult = runLint(recipePath);
+    const lint = {
+        errors: lintResult.issues
+            .filter((issue) => issue.level === "error")
+            .map((issue) => issue.message),
+        warnings: lintResult.issues
+            .filter((issue) => issue.level === "warning")
+            .map((issue) => issue.message),
+    };
+    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;
+            // F-07 fix: read tool/into/recipe directly from the now-typed plan
+            // step instead of casting through `unknown`.
+            if (step.tool !== undefined)
+                base.tool = step.tool;
+            if (step.into !== undefined)
+                base.into = step.into;
+            if (step.recipe !== undefined)
+                base.recipe = step.recipe;
+            return enrichStepFromRegistry(base);
+        });
+        // F-07 fix: recurse into nested-recipe steps to detect writes the
+        // top-level enrichment cannot see. Without this, any chained recipe
+        // whose only writes live in a sub-recipe reports `hasWriteSteps:false`.
+        await detectNestedRecipeWritesInPlan(steps, recipePath, plan.maxDepth);
+        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),
+            lint,
+        };
+    }
+    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),
+        lint,
+    };
+}
+/**
+ * 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);
+}
+/**
+ * Exported for the cli-warns-when-out-of-jail.test regression suite —
+ * the warn path is what we assert on, not the path-resolution behaviour.
+ * Internal callers should keep using the local symbol.
+ */
+export function resolveRecipeRefForCli(recipeRef) {
+    return resolveRecipePath(recipeRef);
+}
+function resolveRecipePath(recipeRef) {
+    const directPath = resolve(recipeRef);
+    if (existsSync(directPath) && statSync(directPath).isFile()) {
+        // F-10 CLI warn: a recipe file outside the recipe jail (e.g. a YAML
+        // dragged in from /tmp) still loads — but emit a stderr notice so the
+        // user knows they're loading a recipe whose tool dispatches will hit
+        // the jail check at runtime. The jail roots default to ~/.patchwork +
+        // CWD; /tmp is opt-in via CLAUDE_IDE_BRIDGE_RECIPE_TMP_JAIL=1.
+        if (tryResolveRecipePath(directPath) === null) {
+            console.warn(`warning: recipe file "${directPath}" lives outside the recipe jail (~/.patchwork, workspace). Tool dispatches that touch the filesystem will be rejected unless the path is inside the jail. Set CLAUDE_IDE_BRIDGE_RECIPE_TMP_JAIL=1 to opt /tmp into the jail.`);
+        }
+        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;
+        }
+    }
+    // Install-dir resolution (DB-4): `recipe install` puts each recipe in
+    // its own subdir at `<RECIPES_DIR>/<install-name>/<entrypoint>.yaml`.
+    // Without this fallback, `recipe run <install-name>` errors with
+    // "not found" even though `recipe list` displays the recipe — observed
+    // in the 2026-04-29 dogfood pass.
+    try {
+        const entrypoint = findInstalledRecipeEntrypoint(normalizedRef);
+        if (entrypoint)
+            return entrypoint;
+    }
+    catch {
+        // findInstalledRecipeEntrypoint throws on path-traversal `name`
+        // values via its underlying validator. That's a security boundary,
+        // not a UX one — fall through to the standard "not found" error
+        // rather than leaking the validator message to a normal user typo.
+    }
+    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