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

package/dist/recipesHttp.js

@@ -1,8 +1,272 @@
-import { mkdirSync, readdirSync, readFileSync, statSync, writeFileSync, } from "node:fs";
-import path from "node:path";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync, } from "node:fs";
+import { homedir } from "node:os";
+import * as path from "node:path";
+import { parse as parseYaml, stringify as stringifyYaml } from "yaml";
+import { loadConfig, saveConfig as savePatchworkConfig, } from "./patchworkConfig.js";
+import { disabledMarkerPath, getConfigDisabledNames, isInstallDirDisabled, } from "./recipes/disabledMarkers.js";
+import { RECIPE_NAME_RE } from "./recipes/names.js";
+import { validateRecipeDefinition } from "./recipes/validation.js";
+/**
+ * Returns true unless `filePath` lives inside an install dir whose
+ * `.disabled` marker is present. Top-level legacy recipes (direct children
+ * of `recipesDir`) are always considered enabled — there's no install dir
+ * to put a marker in. Used by every trigger surface (webhook, manual fire,
+ * automation) so the marker means the same thing everywhere.
+ */
+export function isRecipeFileEnabled(filePath, recipesDir) {
+    const rel = path.relative(recipesDir, filePath);
+    // Top-level file in recipesDir → no install dir → enabled by default.
+    if (rel === "" || rel.startsWith("..") || !rel.includes(path.sep)) {
+        return true;
+    }
+    const installDirName = rel.split(path.sep)[0];
+    if (!installDirName)
+        return true;
+    const installDir = path.join(recipesDir, installDirName);
+    return !isInstallDirDisabled(installDir);
+}
+/**
+ * Iterate one level of subdirectories under `recipesDir` that look like
+ * install dirs (directory containing `recipe.json` or at least one `.yaml`).
+ * Skips dirs whose `.disabled` marker is present so callers automatically
+ * honor the marker without having to remember.
+ *
+ * Yields `{ installDir, entrypointPath }` pairs where `entrypointPath` is the
+ * file the caller should parse:
+ *   - `recipe.json`'s `recipes.main` if a manifest exists
+ *   - otherwise the first `*.yaml` / `*.yml` in the dir
+ *
+ * Used by webhook + manual-fire path resolvers to find recipes installed
+ * via `runRecipeInstall`.
+ */
+function* iterateInstallDirs(recipesDir, options = {}) {
+    const includeDisabled = options.includeDisabled === true;
+    let entries;
+    try {
+        entries = readdirSync(recipesDir);
+    }
+    catch {
+        return;
+    }
+    for (const f of entries) {
+        // Skip dotfile-prefixed dirs (`.archive/`, `.disabled/`, …). Conventionally
+        // hidden; reserves the namespace for archive/recovery features.
+        if (f.startsWith("."))
+            continue;
+        const fullPath = path.join(recipesDir, f);
+        let isDir = false;
+        try {
+            isDir = statSync(fullPath).isDirectory();
+        }
+        catch {
+            continue;
+        }
+        if (!isDir)
+            continue;
+        const enabled = !isInstallDirDisabled(fullPath);
+        if (!enabled && !includeDisabled)
+            continue;
+        let entrypoint = null;
+        const manifestPath = path.join(fullPath, "recipe.json");
+        if (existsSync(manifestPath)) {
+            try {
+                const m = JSON.parse(readFileSync(manifestPath, "utf-8"));
+                if (m.recipes?.main) {
+                    const candidate = path.join(fullPath, m.recipes.main);
+                    if (existsSync(candidate))
+                        entrypoint = candidate;
+                }
+            }
+            catch {
+                // malformed manifest — fall through to first-yaml fallback
+            }
+        }
+        if (!entrypoint) {
+            try {
+                const yaml = readdirSync(fullPath).find((x) => /\.ya?ml$/i.test(x));
+                if (yaml)
+                    entrypoint = path.join(fullPath, yaml);
+            }
+            catch {
+                // unreadable
+            }
+        }
+        if (entrypoint) {
+            yield { installDir: fullPath, entrypointPath: entrypoint, enabled };
+        }
+    }
+}
+/**
+ * Locate an install dir by the *recipe name* declared inside its entrypoint
+ * (not the directory name). The dashboard reports recipes by the parsed
+ * `name` field, while `runRecipeEnable` looks them up by dir name —
+ * the two are usually different (`morning-pkg` vs `morning-brief`). Includes
+ * disabled dirs so re-enabling actually finds them.
+ */
+function findInstallDirByRecipeName(recipesDir, name) {
+    for (const { installDir, entrypointPath } of iterateInstallDirs(recipesDir, {
+        includeDisabled: true,
+    })) {
+        try {
+            const ext = path.extname(entrypointPath).toLowerCase();
+            const raw = readFileSync(entrypointPath, "utf-8");
+            const parsed = (ext === ".json" ? JSON.parse(raw) : parseYaml(raw));
+            if (parsed.name === name)
+                return installDir;
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return null;
+}
+/**
+ * Unified enable/disable for install-dir AND legacy top-level recipes.
+ *
+ * Routing:
+ *   1. Try to find an install dir whose entrypoint declares this `name`.
+ *      If found, write/remove the `.disabled` marker on that dir. This
+ *      matches CLI `recipe enable/disable` and the trigger-side
+ *      enforcement landed in PRs #43 / #49.
+ *   2. Otherwise the recipe is a top-level legacy file — fall back to
+ *      the legacy `cfg.recipes.disabled` config-file array, which the
+ *      scheduler already honors as a parallel mechanism (it checks both).
+ *
+ * Replaces the old dashboard-only `setRecipeEnabledFn` that wrote ONLY to
+ * the legacy config — which silently did nothing for install-dir recipes.
+ */
+export function setRecipeEnabled(name, enabled, options = {}) {
+    const recipesDir = options.recipesDir ?? path.join(homedir(), ".patchwork", "recipes");
+    try {
+        const installDir = findInstallDirByRecipeName(recipesDir, name);
+        if (installDir) {
+            const markerPath = disabledMarkerPath(installDir);
+            if (enabled) {
+                if (existsSync(markerPath))
+                    rmSync(markerPath);
+            }
+            else {
+                writeFileSync(markerPath, "");
+            }
+            return { ok: true };
+        }
+        // Legacy top-level path — fall back to config-file disabled list
+        const cfg = (options.loadConfigFn ?? loadConfig)();
+        const disabled = getConfigDisabledNames(cfg);
+        if (enabled)
+            disabled.delete(name);
+        else
+            disabled.add(name);
+        const next = {
+            ...cfg,
+            recipes: {
+                ...(cfg.recipes ?? {}),
+                disabled: [...disabled],
+            },
+        };
+        if (options.saveConfigFn)
+            options.saveConfigFn(next);
+        else
+            savePatchworkConfig(next);
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+function normalizeRecipeDraftTrigger(trigger) {
+    if (trigger.type === "schedule" || trigger.type === "cron") {
+        const schedule = typeof trigger.schedule === "string" && trigger.schedule.trim()
+            ? trigger.schedule.trim()
+            : typeof trigger.cron === "string" && trigger.cron.trim()
+                ? trigger.cron.trim()
+                : "";
+        return {
+            type: "cron",
+            ...(schedule ? { schedule } : {}),
+        };
+    }
+    if (trigger.type === "webhook") {
+        const pathValue = typeof trigger.path === "string" ? trigger.path.trim() : "";
+        return {
+            type: "webhook",
+            ...(pathValue ? { path: pathValue } : {}),
+        };
+    }
+    return { type: "manual" };
+}
+function validateRecipeDraft(draft) {
+    if (!draft || typeof draft !== "object") {
+        return "Invalid recipe draft";
+    }
+    if (!draft.trigger || typeof draft.trigger !== "object") {
+        return "trigger required";
+    }
+    if (draft.trigger.type !== "manual" &&
+        draft.trigger.type !== "webhook" &&
+        draft.trigger.type !== "schedule" &&
+        draft.trigger.type !== "cron") {
+        return "Invalid trigger type";
+    }
+    const normalizedTrigger = normalizeRecipeDraftTrigger(draft.trigger);
+    if (normalizedTrigger.type === "webhook") {
+        if (typeof normalizedTrigger.path !== "string" ||
+            !normalizedTrigger.path.startsWith("/")) {
+            return "webhook trigger requires a path starting with /";
+        }
+    }
+    if (normalizedTrigger.type === "cron") {
+        if (typeof normalizedTrigger.schedule !== "string" ||
+            !normalizedTrigger.schedule.trim()) {
+            return "cron trigger requires a schedule";
+        }
+    }
+    if (!Array.isArray(draft.steps) || draft.steps.length === 0) {
+        return "Recipe must have at least one step";
+    }
+    const stepIds = new Set();
+    for (let i = 0; i < draft.steps.length; i++) {
+        const step = draft.steps[i];
+        const index = i + 1;
+        const id = typeof step?.id === "string" ? step.id.trim() : "";
+        if (!id) {
+            return `Step ${index} is missing an id`;
+        }
+        if (stepIds.has(id)) {
+            return `Step ${index} has a duplicate id`;
+        }
+        stepIds.add(id);
+        if (typeof step?.prompt !== "string" || !step.prompt.trim()) {
+            return `Step ${index} is missing a prompt`;
+        }
+    }
+    if (draft.vars !== undefined) {
+        if (!Array.isArray(draft.vars)) {
+            return "vars must be an array";
+        }
+        const varNames = new Set();
+        for (let i = 0; i < draft.vars.length; i++) {
+            const item = draft.vars[i];
+            const index = i + 1;
+            const name = typeof item?.name === "string" ? item.name.trim() : "";
+            if (!name) {
+                return `Variable ${index} is missing a name`;
+            }
+            if (varNames.has(name)) {
+                return `Variable ${index} has a duplicate name`;
+            }
+            varNames.add(name);
+        }
+    }
+    return null;
+}
 export function saveRecipe(recipesDir, draft) {
     const safeName = draft.name.toLowerCase().replace(/\s+/g, "-");
-    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(safeName)) {
+    if (!RECIPE_NAME_RE.test(safeName)) {
         return { ok: false, error: "Invalid recipe name" };
     }
     const candidate = path.resolve(recipesDir, `${safeName}.json`);
@@ -10,20 +274,46 @@ export function saveRecipe(recipesDir, draft) {
     if (!candidate.startsWith(base + path.sep)) {
         return { ok: false, error: "Invalid path" };
     }
+    const validationError = validateRecipeDraft(draft);
+    if (validationError) {
+        return { ok: false, error: validationError };
+    }
     try {
         mkdirSync(recipesDir, { recursive: true });
+        // Nest `vars` under `trigger.vars` (validator only reads it there;
+        // top-level was the same shape bug PR #259 fixed for the YAML path).
+        const baseTrigger = normalizeRecipeDraftTrigger(draft.trigger);
+        const trigger = draft.vars && draft.vars.length > 0
+            ? {
+                ...baseTrigger,
+                vars: draft.vars.map((item) => ({
+                    ...item,
+                    name: item.name.trim(),
+                })),
+            }
+            : baseTrigger;
         const payload = {
             name: safeName,
             description: draft.description,
-            trigger: draft.trigger,
+            trigger,
             steps: draft.steps.map((s) => ({
-                id: s.id,
+                id: s.id.trim(),
                 agent: s.agent,
                 prompt: s.prompt,
             })),
-            ...(draft.vars && draft.vars.length > 0 ? { vars: draft.vars } : {}),
             createdAt: Date.now(),
         };
+        // Surface the FIRST error from `validateRecipeDefinition` — earlier
+        // versions filtered to only "Unknown template reference" issues,
+        // which silently bypassed cron validation, var-name regex, and
+        // reserved-name shadowing on this legacy JSON path. Anyone scripting
+        // against the bridge's `POST /recipes` endpoint was getting much
+        // weaker validation than the dashboard's YAML PUT path.
+        const deepValidation = validateRecipeDefinition(payload);
+        const deepError = deepValidation.issues.find((issue) => issue.level === "error");
+        if (deepError) {
+            return { ok: false, error: deepError.message };
+        }
         writeFileSync(candidate, JSON.stringify(payload, null, 2), "utf-8");
         return { ok: true, path: candidate };
     }
@@ -34,6 +324,480 @@ export function saveRecipe(recipesDir, draft) {
         };
     }
 }
+function resolveJsonRecipePathByName(recipesDir, safeName) {
+    const candidate = path.resolve(recipesDir, `${safeName}.json`);
+    const base = path.resolve(recipesDir);
+    if (!candidate.startsWith(base + path.sep))
+        return null;
+    if (existsSync(candidate))
+        return candidate;
+    try {
+        for (const entry of readdirSync(recipesDir)) {
+            if (!entry.endsWith(".json") || entry.endsWith(".permissions.json")) {
+                continue;
+            }
+            const entryPath = path.join(recipesDir, entry);
+            try {
+                const entryRaw = readFileSync(entryPath, "utf-8");
+                const entryParsed = JSON.parse(entryRaw);
+                if (entryParsed.name?.toLowerCase() !== safeName) {
+                    continue;
+                }
+                return entryPath;
+            }
+            catch {
+                // skip malformed candidate
+            }
+        }
+    }
+    catch {
+        return null;
+    }
+    // Also search install dirs from `recipeInstall`. Skips dirs with
+    // `.disabled` marker so the manual-fire / orchestrator path can't
+    // resolve a recipe the user has explicitly disabled.
+    for (const { entrypointPath } of iterateInstallDirs(recipesDir)) {
+        if (!entrypointPath.endsWith(".json"))
+            continue;
+        try {
+            const parsed = JSON.parse(readFileSync(entrypointPath, "utf-8"));
+            if (parsed.name?.toLowerCase() === safeName) {
+                return entrypointPath;
+            }
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    return null;
+}
+export function loadRecipeContent(recipesDir, name) {
+    const safeName = name.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeName))
+        return null;
+    const yamlPath = findYamlRecipePath(recipesDir, safeName);
+    if (yamlPath) {
+        try {
+            return {
+                content: readFileSync(yamlPath, "utf-8"),
+                path: yamlPath,
+            };
+        }
+        catch {
+            return null;
+        }
+    }
+    const jsonPath = resolveJsonRecipePathByName(recipesDir, safeName);
+    if (!jsonPath) {
+        return null;
+    }
+    try {
+        return {
+            content: readFileSync(jsonPath, "utf-8"),
+            path: jsonPath,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function saveRecipeContent(recipesDir, name, content) {
+    const safeName = name.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeName)) {
+        return { ok: false, error: "Invalid recipe name" };
+    }
+    if (!content.trim()) {
+        return { ok: false, error: "Recipe content is required" };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(content);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+    const validation = validateRecipeDefinition(parsed);
+    const warnings = validation.issues
+        .filter((issue) => issue.level === "warning")
+        .map((issue) => issue.message);
+    const validationError = validation.issues.find((issue) => issue.level === "error");
+    if (validationError) {
+        return {
+            ok: false,
+            error: validationError.message,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    // If the parsed body's `name:` field disagrees with the filename
+    // (e.g. caller PUT to /recipes/myrecipe with a body whose `name:` is
+    // `MyRecipe`), rewrite it to match. The filename is the source of
+    // truth for routing, dashboard list keys, and webhook resolution;
+    // body drift just causes silent confusion.
+    //
+    // Earlier versions used a `^name:\s*.+$/m` text replace, but that:
+    //   (a) only handled the FIRST top-level `name:` (YAML duplicate keys
+    //       — which the parser resolves to the LAST — would survive in
+    //       the file even after rewrite), and
+    //   (b) didn't recognize quoted forms like `name: "MyRecipe"` cleanly
+    //       across all whitespace shapes.
+    // Parse → mutate → stringify is robust against both: the YAML
+    // serializer normalizes the entire document, so any duplicate/quoted
+    // name disappears.
+    let normalizedContent = content;
+    if (parsed &&
+        typeof parsed === "object" &&
+        !Array.isArray(parsed) &&
+        typeof parsed.name === "string" &&
+        parsed.name !== safeName) {
+        const oldName = parsed.name;
+        const recipe = { ...parsed, name: safeName };
+        try {
+            normalizedContent = stringifyYaml(recipe);
+            warnings.push(`Recipe body name "${oldName}" was rewritten to "${safeName}" to match the filename.`);
+        }
+        catch {
+            // Re-stringify failed (e.g. cyclic structure); fall back to the
+            // text replace so save still succeeds. Safe because the parse
+            // above already validated the document.
+            normalizedContent = content.replace(/^name:\s*.+$/m, `name: ${safeName}`);
+            warnings.push(`Recipe body name "${oldName}" was rewritten to "${safeName}" to match the filename (text-replace fallback).`);
+        }
+    }
+    try {
+        mkdirSync(recipesDir, { recursive: true });
+        const base = path.resolve(recipesDir);
+        const candidate = findYamlRecipePath(recipesDir, safeName) ??
+            path.resolve(recipesDir, `${safeName}.yaml`);
+        if (!candidate.startsWith(base + path.sep)) {
+            return { ok: false, error: "Invalid path" };
+        }
+        writeFileSync(candidate, normalizedContent.endsWith("\n")
+            ? normalizedContent
+            : `${normalizedContent}\n`, "utf-8");
+        return {
+            ok: true,
+            path: candidate,
+            ...(warnings.length > 0 ? { warnings } : {}),
+        };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Deletes a recipe file (yaml/yml or json) plus any sidecar permissions file.
+ * Returns ok=false with a 404-style error when the recipe cannot be located.
+ */
+export function deleteRecipeContent(recipesDir, name) {
+    const safeName = name.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeName)) {
+        return { ok: false, error: "Invalid recipe name" };
+    }
+    const base = path.resolve(recipesDir);
+    const target = findYamlRecipePath(recipesDir, safeName) ??
+        resolveJsonRecipePathByName(recipesDir, safeName);
+    if (!target) {
+        return { ok: false, error: "Recipe not found" };
+    }
+    const resolved = path.resolve(target);
+    if (!resolved.startsWith(base + path.sep)) {
+        return { ok: false, error: "Invalid path" };
+    }
+    try {
+        rmSync(resolved, { force: true });
+        const sidecar = `${resolved}.permissions.json`;
+        if (existsSync(sidecar)) {
+            try {
+                rmSync(sidecar, { force: true });
+            }
+            catch {
+                // sidecar removal best-effort
+            }
+        }
+        return { ok: true, path: resolved };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Archives a recipe by moving its file (and sidecar `.permissions.json`)
+ * into `<recipesDir>/.archive/`. The archive directory is created on demand.
+ * On filename collision the moved file is suffixed with the current
+ * timestamp so historical archives never overwrite each other.
+ *
+ * Returns the absolute archived path on success, ok=false with a 404-style
+ * error when the recipe cannot be located.
+ */
+export function archiveRecipe(recipesDir, name) {
+    const safeName = name.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeName)) {
+        return { ok: false, error: "Invalid recipe name" };
+    }
+    const base = path.resolve(recipesDir);
+    const target = findYamlRecipePath(recipesDir, safeName) ??
+        resolveJsonRecipePathByName(recipesDir, safeName);
+    if (!target) {
+        return { ok: false, error: "Recipe not found" };
+    }
+    const resolved = path.resolve(target);
+    if (!resolved.startsWith(base + path.sep)) {
+        return { ok: false, error: "Invalid path" };
+    }
+    const archiveDir = path.join(base, ".archive");
+    try {
+        mkdirSync(archiveDir, { recursive: true });
+        const basename = path.basename(resolved);
+        let dest = path.join(archiveDir, basename);
+        if (existsSync(dest)) {
+            const ext = path.extname(basename);
+            const stem = basename.slice(0, basename.length - ext.length);
+            const stamp = new Date().toISOString().replace(/[:.]/g, "-");
+            dest = path.join(archiveDir, `${stem}.${stamp}${ext}`);
+        }
+        renameSync(resolved, dest);
+        const sidecar = `${resolved}.permissions.json`;
+        if (existsSync(sidecar)) {
+            try {
+                renameSync(sidecar, `${dest}.permissions.json`);
+            }
+            catch {
+                // sidecar move best-effort — primary archive already succeeded
+            }
+        }
+        return { ok: true, path: dest };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
+/**
+ * Duplicate a recipe as a variant. Copies the source YAML, rewrites the
+ * `name:` field to `<original>-v<N>` (first available suffix), and writes
+ * the copy to disk. Returns the new variant name and path on success.
+ *
+ * The variant name follows the same validation rules as recipe names.
+ * Suffixes v2..v9 are tried before returning an error.
+ */
+export function duplicateRecipe(recipesDir, sourceName) {
+    const safeName = sourceName.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeName)) {
+        return { ok: false, error: "Invalid recipe name" };
+    }
+    const source = loadRecipeContent(recipesDir, safeName);
+    if (!source) {
+        return { ok: false, error: "Recipe not found" };
+    }
+    if (!/\.ya?ml$/i.test(source.path)) {
+        return {
+            ok: false,
+            error: "Recipe variants are only supported for YAML recipes",
+        };
+    }
+    if (!/^name:\s*.+$/m.test(source.content)) {
+        return {
+            ok: false,
+            error: "Source recipe is missing a top-level 'name:' field",
+        };
+    }
+    // Determine next available variant name: strip any existing -vN suffix,
+    // then try -v2 through -v9.
+    const base = safeName.replace(/-v\d+$/, "");
+    let variantName = null;
+    for (let n = 2; n <= 9; n++) {
+        const candidate = `${base}-v${n}`;
+        if (!findYamlRecipePath(recipesDir, candidate)) {
+            variantName = candidate;
+            break;
+        }
+    }
+    if (!variantName) {
+        return {
+            ok: false,
+            error: "Too many variants already exist (v2–v9 taken)",
+        };
+    }
+    // Rewrite the name: field in the YAML. Simple line-by-line replacement
+    // is safe here: the name field is always a scalar on its own line.
+    const newContent = source.content.replace(/^name:\s*.+$/m, `name: ${variantName}`);
+    const saveResult = saveRecipeContent(recipesDir, variantName, newContent);
+    if (!saveResult.ok) {
+        return { ok: false, error: saveResult.error };
+    }
+    return { ok: true, variantName, path: saveResult.path };
+}
+/**
+ * Promote a variant recipe to become the canonical name.
+ *
+ * Steps:
+ *   1. Load the variant's YAML.
+ *   2. Rewrite its `name:` field to `targetName`.
+ *   3. Save under `targetName` (overwrites any existing file at that name).
+ *   4. Delete the variant file so only one copy exists.
+ *
+ * The caller supplies `variantName` (e.g. "morning-brief-v2") and
+ * `targetName` (e.g. "morning-brief"). Both must pass the recipe name
+ * validation regex. Returns `{ ok, path }` on success.
+ */
+export async function promoteRecipeVariant(recipesDir, variantName, targetName, options) {
+    const safeVariant = variantName.toLowerCase();
+    const safeTarget = targetName.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeVariant) || !RECIPE_NAME_RE.test(safeTarget)) {
+        return { ok: false, error: "Invalid recipe name" };
+    }
+    if (safeVariant === safeTarget) {
+        return { ok: false, error: "Variant and target names must differ" };
+    }
+    const source = loadRecipeContent(recipesDir, safeVariant);
+    if (!source) {
+        return { ok: false, error: "Variant recipe not found" };
+    }
+    if (!/\.ya?ml$/i.test(source.path)) {
+        return {
+            ok: false,
+            error: "Recipe variants are only supported for YAML recipes",
+        };
+    }
+    if (!/^name:\s*.+$/m.test(source.content)) {
+        return {
+            ok: false,
+            error: "Variant recipe is missing a top-level 'name:' field",
+        };
+    }
+    // Guard against silent overwrites: if the target already exists the caller
+    // must pass force:true. We also capture the prior content hash for audit.
+    const existing = loadRecipeContent(recipesDir, safeTarget);
+    if (existing && !options?.force) {
+        return {
+            ok: false,
+            targetExists: true,
+            error: `Recipe "${safeTarget}" already exists. Pass force:true to overwrite.`,
+        };
+    }
+    // Write audit log entry before the overwrite so the replaced content is
+    // traceable even if the variant file is deleted in the next step.
+    if (existing) {
+        try {
+            const priorHash = createHash("sha256")
+                .update(existing.content)
+                .digest("hex");
+            const auditPath = existing.path.replace(/\.ya?ml$/, ".promote-audit.json");
+            writeFileSync(auditPath, JSON.stringify({
+                ts: new Date().toISOString(),
+                action: "promote_overwrite",
+                variantName: safeVariant,
+                targetName: safeTarget,
+                priorContentHash: priorHash,
+                priorContentPath: existing.path,
+            }, null, 2), "utf-8");
+        }
+        catch {
+            // Audit log failure must not block the promote — log and continue.
+        }
+    }
+    const newContent = source.content.replace(/^name:\s*.+$/m, `name: ${safeTarget}`);
+    const saveResult = saveRecipeContent(recipesDir, safeTarget, newContent);
+    if (!saveResult.ok) {
+        return { ok: false, error: saveResult.error };
+    }
+    // Delete the variant file — best-effort; don't fail the promote if cleanup fails.
+    deleteRecipeContent(recipesDir, safeVariant);
+    return { ok: true, path: saveResult.path };
+}
+/**
+ * Lints raw YAML/JSON recipe content without writing to disk. Used by the
+ * dashboard edit UI to surface validateRecipeDefinition warnings live, in
+ * addition to the warnings returned by saveRecipeContent on save.
+ */
+export function lintRecipeContent(content) {
+    if (!content.trim()) {
+        return { ok: false, errors: ["Recipe content is required"], warnings: [] };
+    }
+    let parsed;
+    try {
+        parsed = parseYaml(content);
+    }
+    catch (err) {
+        return {
+            ok: false,
+            errors: [err instanceof Error ? err.message : String(err)],
+            warnings: [],
+        };
+    }
+    const validation = validateRecipeDefinition(parsed);
+    const errors = [];
+    const warnings = [];
+    for (const issue of validation.issues) {
+        if (issue.level === "error")
+            errors.push(issue.message);
+        else
+            warnings.push(issue.message);
+    }
+    return { ok: errors.length === 0, errors, warnings };
+}
+// ---------------------------------------------------------------------------
+// Recipe trust levels
+// ---------------------------------------------------------------------------
+export const TRUST_LEVELS = [
+    "draft",
+    "manual_run",
+    "ask_every_time",
+    "ask_novel",
+    "mostly_trusted",
+    "fully_trusted",
+];
+const TRUST_LEVELS_FILE = "trust_levels.json";
+function trustLevelsPath(recipesDir) {
+    return path.join(recipesDir, TRUST_LEVELS_FILE);
+}
+function loadTrustLevels(recipesDir) {
+    const p = trustLevelsPath(recipesDir);
+    try {
+        const raw = readFileSync(p, "utf-8");
+        return JSON.parse(raw);
+    }
+    catch {
+        return {};
+    }
+}
+function saveTrustLevels(recipesDir, levels) {
+    const p = trustLevelsPath(recipesDir);
+    mkdirSync(recipesDir, { recursive: true });
+    writeFileSync(p, JSON.stringify(levels, null, 2), "utf-8");
+}
+export function getTrustLevel(recipesDir, name) {
+    const levels = loadTrustLevels(recipesDir);
+    return levels[name] ?? "draft";
+}
+export function setTrustLevel(recipesDir, name, level) {
+    if (!TRUST_LEVELS.includes(level)) {
+        return { ok: false, error: `Invalid trust level: ${level}` };
+    }
+    try {
+        const levels = loadTrustLevels(recipesDir);
+        levels[name] = level;
+        saveTrustLevels(recipesDir, levels);
+        return { ok: true };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            error: err instanceof Error ? err.message : String(err),
+        };
+    }
+}
 export function listInstalledRecipes(recipesDir) {
     let entries;
     try {
@@ -42,24 +806,20 @@ export function listInstalledRecipes(recipesDir) {
     catch {
         return { recipesDir, recipes: [] };
     }
+    const cfg = loadConfig();
+    const disabledSet = new Set(cfg.recipes?.disabled ?? []);
+    const trustLevels = loadTrustLevels(recipesDir);
     const recipes = [];
     for (const f of entries) {
-        if (!f.endsWith(".json") || f.endsWith(".permissions.json"))
+        const isYaml = f.endsWith(".yaml") || f.endsWith(".yml");
+        const isJson = f.endsWith(".json") && !f.endsWith(".permissions.json");
+        if (!isYaml && !isJson)
             continue;
         const fullPath = path.join(recipesDir, f);
         try {
             const raw = readFileSync(fullPath, "utf-8");
-            const parsed = JSON.parse(raw);
+            const parsed = (isYaml ? parseYaml(raw) : JSON.parse(raw));
             const stat = statSync(fullPath);
-            const permsPath = `${fullPath}.permissions.json`;
-            let hasPermissions = false;
-            try {
-                statSync(permsPath);
-                hasPermissions = true;
-            }
-            catch {
-                // no permissions sidecar
-            }
             const resolvedRecipesDir = path.resolve(recipesDir);
             let source;
             if (fullPath.startsWith(resolvedRecipesDir + path.sep) ||
@@ -72,27 +832,205 @@ export function listInstalledRecipes(recipesDir) {
             else {
                 source = "unknown";
             }
+            const ext = isYaml ? (f.endsWith(".yml") ? ".yml" : ".yaml") : ".json";
+            const parsedName = parsed.name ?? path.basename(f, ext);
+            const lintRes = validateRecipeDefinition(parsed);
+            let errCount = 0;
+            let warnCount = 0;
+            let firstError;
+            for (const issue of lintRes.issues) {
+                if (issue.level === "error") {
+                    errCount++;
+                    if (!firstError)
+                        firstError = issue.message;
+                }
+                else {
+                    warnCount++;
+                }
+            }
+            const webhookPath = parsed.trigger?.type === "webhook" &&
+                typeof parsed.trigger?.path === "string"
+                ? parsed.trigger.path
+                : undefined;
             recipes.push({
-                name: parsed.name ?? path.basename(f, ".json"),
+                name: parsedName,
                 description: parsed.description,
                 trigger: parsed.trigger?.type,
+                ...(webhookPath ? { webhookPath } : {}),
                 stepCount: Array.isArray(parsed.steps) ? parsed.steps.length : 0,
                 path: fullPath,
                 installedAt: stat.mtimeMs,
-                hasPermissions,
                 source,
+                // Top-level legacy recipes don't have install dirs to put a marker
+                // in, so the `enabled` field still comes from the legacy config list.
+                enabled: !disabledSet.has(parsedName),
+                trustLevel: (trustLevels[parsedName] ?? "draft"),
                 ...(Array.isArray(parsed.vars) && parsed.vars.length > 0
                     ? { vars: parsed.vars }
                     : {}),
+                lint: {
+                    ok: errCount === 0,
+                    errorCount: errCount,
+                    warningCount: warnCount,
+                    ...(firstError ? { firstError } : {}),
+                },
             });
         }
         catch {
             // skip malformed recipe file
         }
     }
+    // Second pass — recipes installed via `runRecipeInstall` into subdirs.
+    // `enabled` reflects the per-install `.disabled` marker; the legacy
+    // config disabled list is a top-level concern (we still apply it as a
+    // safety belt in case a name collides).
+    for (const { installDir, entrypointPath, enabled: installEnabled, } of iterateInstallDirs(recipesDir, { includeDisabled: true })) {
+        try {
+            const ext = path.extname(entrypointPath).toLowerCase();
+            const isYaml = ext === ".yaml" || ext === ".yml";
+            const isJson = ext === ".json";
+            if (!isYaml && !isJson)
+                continue;
+            const raw = readFileSync(entrypointPath, "utf-8");
+            const parsed = (isYaml ? parseYaml(raw) : JSON.parse(raw));
+            const stat = statSync(entrypointPath);
+            const parsedName = parsed.name ??
+                path.basename(entrypointPath, path.extname(entrypointPath));
+            const lintRes = validateRecipeDefinition(parsed);
+            let errCount = 0;
+            let warnCount = 0;
+            let firstError;
+            for (const issue of lintRes.issues) {
+                if (issue.level === "error") {
+                    errCount++;
+                    if (!firstError)
+                        firstError = issue.message;
+                }
+                else {
+                    warnCount++;
+                }
+            }
+            const webhookPath = parsed.trigger?.type === "webhook" &&
+                typeof parsed.trigger?.path === "string"
+                ? parsed.trigger.path
+                : undefined;
+            recipes.push({
+                name: parsedName,
+                description: parsed.description,
+                trigger: parsed.trigger?.type,
+                ...(webhookPath ? { webhookPath } : {}),
+                stepCount: Array.isArray(parsed.steps) ? parsed.steps.length : 0,
+                path: entrypointPath,
+                installedAt: stat.mtimeMs,
+                source: "user",
+                // Disabled if EITHER the install marker is set OR the legacy config
+                // names this recipe — defence-in-depth so a stale config entry can't
+                // accidentally re-enable a recipe the user explicitly disabled, and
+                // the dashboard can't accidentally enable one disabled by an admin
+                // through the legacy file.
+                enabled: installEnabled && !disabledSet.has(parsedName),
+                trustLevel: (trustLevels[parsedName] ?? "draft"),
+                ...(Array.isArray(parsed.vars) && parsed.vars.length > 0
+                    ? { vars: parsed.vars }
+                    : {}),
+                lint: {
+                    ok: errCount === 0,
+                    errorCount: errCount,
+                    warningCount: warnCount,
+                    ...(firstError ? { firstError } : {}),
+                },
+            });
+            void installDir;
+        }
+        catch {
+            // skip malformed install dir
+        }
+    }
     recipes.sort((a, b) => a.name.localeCompare(b.name));
     return { recipesDir, recipes };
 }
+/**
+ * Thrown by `findYamlRecipePath` (and listing/lint paths that surface this)
+ * when more than one enabled YAML recipe declares the same `name`. Callers
+ * must surface this loudly rather than silently picking the first match —
+ * dashboard run buttons, scheduler fires, and webhook resolution would all
+ * be ambiguous otherwise.
+ */
+export class RecipeNameConflictError extends Error {
+    recipeName;
+    paths;
+    constructor(recipeName, paths) {
+        super(`Multiple YAML recipes declare name "${recipeName}": ${paths
+            .map((p) => path.basename(p))
+            .join(", ")}`);
+        this.name = "RecipeNameConflictError";
+        this.recipeName = recipeName;
+        this.paths = paths;
+    }
+}
+export function findYamlRecipePath(recipesDir, name) {
+    const safeName = name.toLowerCase();
+    if (!RECIPE_NAME_RE.test(safeName))
+        return null;
+    const base = path.resolve(recipesDir);
+    const matches = new Set();
+    // Exact-filename matches (top-level legacy layout). The parsed `name`
+    // field is allowed to differ from the filename, so we still scan below.
+    for (const ext of [".yaml", ".yml"]) {
+        const candidate = path.resolve(recipesDir, `${safeName}${ext}`);
+        if (!candidate.startsWith(base + path.sep))
+            return null;
+        if (existsSync(candidate))
+            matches.add(candidate);
+    }
+    let entries = [];
+    try {
+        entries = readdirSync(recipesDir);
+    }
+    catch {
+        // recipesDir missing — fall through; matches may still be empty
+    }
+    for (const entry of entries) {
+        if (!entry.endsWith(".yaml") && !entry.endsWith(".yml"))
+            continue;
+        const entryPath = path.join(recipesDir, entry);
+        if (matches.has(entryPath))
+            continue;
+        try {
+            const entryParsed = parseYaml(readFileSync(entryPath, "utf-8"));
+            if (entryParsed.name?.toLowerCase() === safeName) {
+                matches.add(entryPath);
+            }
+        }
+        catch {
+            // skip malformed candidate
+        }
+    }
+    // Install dirs from `recipeInstall`. iterateInstallDirs skips dirs with
+    // `.disabled` marker so the manual-fire / orchestrator path can't
+    // resolve a recipe the user has explicitly disabled.
+    for (const { entrypointPath } of iterateInstallDirs(recipesDir)) {
+        if (!/\.ya?ml$/i.test(entrypointPath))
+            continue;
+        if (matches.has(entrypointPath))
+            continue;
+        try {
+            const parsed = parseYaml(readFileSync(entrypointPath, "utf-8"));
+            if (parsed.name?.toLowerCase() === safeName) {
+                matches.add(entrypointPath);
+            }
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    if (matches.size === 0)
+        return null;
+    if (matches.size > 1) {
+        throw new RecipeNameConflictError(safeName, [...matches].sort());
+    }
+    return [...matches][0] ?? null;
+}
 /**
  * Scan recipes and return the first webhook-triggered recipe whose
  * trigger.path matches the requested path. Returns null on miss.
@@ -106,18 +1044,50 @@ export function findWebhookRecipe(recipesDir, requestPath) {
     catch {
         return null;
     }
+    // Pass 1 — top-level files (legacy)
     for (const f of entries) {
-        if (!f.endsWith(".json") || f.endsWith(".permissions.json"))
+        const isYaml = f.endsWith(".yaml") || f.endsWith(".yml");
+        const isJson = f.endsWith(".json") && !f.endsWith(".permissions.json");
+        if (!isYaml && !isJson)
+            continue;
+        try {
+            const filePath = path.join(recipesDir, f);
+            const raw = readFileSync(filePath, "utf-8");
+            const parsed = (isYaml ? parseYaml(raw) : JSON.parse(raw));
+            if (parsed.trigger?.type !== "webhook")
+                continue;
+            if (parsed.trigger.path === requestPath) {
+                return {
+                    name: parsed.name ?? path.basename(f, path.extname(f)),
+                    path: requestPath,
+                    filePath,
+                    format: isYaml ? "yaml" : "json",
+                };
+            }
+        }
+        catch {
+            // skip malformed
+        }
+    }
+    // Pass 2 — install dirs (skips dirs marked .disabled).
+    for (const { entrypointPath } of iterateInstallDirs(recipesDir)) {
+        const ext = path.extname(entrypointPath).toLowerCase();
+        const isYaml = ext === ".yaml" || ext === ".yml";
+        const isJson = ext === ".json";
+        if (!isYaml && !isJson)
             continue;
         try {
-            const raw = readFileSync(path.join(recipesDir, f), "utf-8");
-            const parsed = JSON.parse(raw);
+            const raw = readFileSync(entrypointPath, "utf-8");
+            const parsed = (isYaml ? parseYaml(raw) : JSON.parse(raw));
             if (parsed.trigger?.type !== "webhook")
                 continue;
             if (parsed.trigger.path === requestPath) {
                 return {
-                    name: parsed.name ?? path.basename(f, ".json"),
+                    name: parsed.name ??
+                        path.basename(entrypointPath, path.extname(entrypointPath)),
                     path: requestPath,
+                    filePath: entrypointPath,
+                    format: isYaml ? "yaml" : "json",
                 };
             }
         }
@@ -134,15 +1104,15 @@ export function findWebhookRecipe(recipesDir, requestPath) {
  */
 export function loadRecipePrompt(recipesDir, name) {
     const safeName = name.toLowerCase();
-    if (!/^[a-z0-9][a-z0-9_-]{0,63}$/.test(safeName))
+    if (!RECIPE_NAME_RE.test(safeName))
         return null;
-    const candidate = path.resolve(recipesDir, `${safeName}.json`);
-    const base = path.resolve(recipesDir);
-    if (!candidate.startsWith(base + path.sep))
+    const recipePath = resolveJsonRecipePathByName(recipesDir, safeName);
+    if (!recipePath) {
         return null;
+    }
     let raw;
     try {
-        raw = readFileSync(candidate, "utf-8");
+        raw = readFileSync(recipePath, "utf-8");
     }
     catch {
         return null;
@@ -166,7 +1136,7 @@ export function loadRecipePrompt(recipesDir, name) {
         }
     }
     lines.push("\nWhen finished, print a one-line summary prefixed with 'RECIPE DONE:'.");
-    return { prompt: lines.join("\n"), path: candidate };
+    return { prompt: lines.join("\n"), path: recipePath };
 }
 /**
  * Append a webhook payload to a base prompt so the agent can reference