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

package/dist/index.js

@@ -3,7 +3,7 @@
 // Uses Node 20.6+ native dotenv loader; falls back to manual parse for older Node.
 {
     const { fileURLToPath: _fileURLToPath } = await import("node:url");
-    const envPath = _fileURLToPath(new URL("../../.env", import.meta.url));
+    const envPath = _fileURLToPath(new URL("../.env", import.meta.url));
     try {
         const { readFileSync, existsSync } = await import("node:fs");
         if (existsSync(envPath)) {
@@ -35,8 +35,24 @@ import { getAnalyticsPref, setAnalyticsPref } from "./analyticsPrefs.js";
 import { Bridge } from "./bridge.js";
 import { isBridgeToolsFileValid, repairBridgeToolsRulesIfStale, } from "./bridgeToolsRules.js";
 import { findEditor, parseConfig } from "./config.js";
+import { detectWorkspaceSymlinkInstall, PATCHWORK_PACKAGE_NAME, SYMLINK_INSTALL_FIX, } from "./installGuard.js";
 import { PACKAGE_VERSION, semverGt } from "./version.js";
 const __dirnameTop = path.dirname(fileURLToPath(import.meta.url));
+// Warn when a symlinked global install is detected (`npm install -g .`).
+// launchctl / sandbox environments can fail through that link with EPERM.
+// Warn only — do not crash interactive or dev flows.
+{
+    const _symlinkInfo = detectWorkspaceSymlinkInstall();
+    if (_symlinkInfo) {
+        process.stderr.write(`\n⚠️  Detected a symlinked global ${PATCHWORK_PACKAGE_NAME} install.\n` +
+            `   Logical root: ${_symlinkInfo.logicalRoot}\n` +
+            `   Real path:    ${_symlinkInfo.realRoot}\n\n` +
+            "   LaunchAgent startup can fail with EPERM when the macOS sandbox\n" +
+            "   cannot access workspace files under ~/Documents through that link.\n\n" +
+            SYMLINK_INSTALL_FIX +
+            "\n");
+    }
+}
 const OPEN_VSX_PUBLISHER = "oolab-labs";
 const OPEN_VSX_NAME = "claude-ide-bridge-extension";
 // CLAUDE.md versioned-block patching moved to ./claudeMdPatch.ts so tests
@@ -570,20 +586,9 @@ export function register(ctx) {
 // Patchwork: `patchwork recipe list` — enumerate installed recipes.
 if (process.argv[2] === "recipe" && process.argv[3] === "list") {
     (async () => {
-        const { listYamlRecipes } = await import("./recipes/yamlRunner.js");
-        const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
-        const recipes = listYamlRecipes(recipesDir);
-        if (recipes.length === 0) {
-            process.stdout.write("No recipes installed. Run `patchwork-os patchwork-init` to install the starter set.\n");
-        }
-        else {
-            process.stdout.write(`Installed recipes (${recipes.length}):\n\n`);
-            for (const r of recipes) {
-                const desc = r.description ? `  ${r.description}` : "";
-                process.stdout.write(`  ${r.name.padEnd(28)} [${r.trigger}]${desc}\n`);
-            }
-            process.stdout.write(`\nRun a recipe: patchwork-os recipe run <name>\n`);
-        }
+        const { listInstalledRecipes, printInstalledList } = await import("./commands/recipeInstall.js");
+        const entries = listInstalledRecipes();
+        printInstalledList(entries);
         process.exit(0);
     })();
 }
@@ -591,25 +596,94 @@ if (process.argv[2] === "recipe" && process.argv[3] === "list") {
 // a running bridge's /recipes/run endpoint if one is available.
 if (process.argv[2] === "recipe" && process.argv[3] === "run") {
     const args = process.argv.slice(4);
-    const localFlag = args.includes("--local");
-    const name = args.find((a) => !a.startsWith("--"));
-    if (!name) {
-        process.stderr.write("Usage: patchwork recipe run <name> [--local]\n");
+    const usage = "Usage: patchwork recipe run <name-or-file> [--local] [--dry-run] [--step <id>] [--var KEY=VALUE]\n";
+    let localFlag = false;
+    let dryRun = false;
+    let recipeRef;
+    let step;
+    const vars = {};
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined) {
+            continue;
+        }
+        const currentArg = arg;
+        if (currentArg === "--local") {
+            localFlag = true;
+            continue;
+        }
+        if (currentArg === "--dry-run") {
+            dryRun = true;
+            continue;
+        }
+        if (currentArg === "--step" || currentArg.startsWith("--step=")) {
+            const value = currentArg === "--step"
+                ? args[++i]
+                : currentArg.slice("--step=".length);
+            if (!value) {
+                process.stderr.write(`Error: --step requires a value\n${usage}`);
+                process.exit(1);
+            }
+            step = value;
+            continue;
+        }
+        if (currentArg === "--var" || currentArg.startsWith("--var=")) {
+            const assignment = currentArg === "--var" ? args[++i] : currentArg.slice("--var=".length);
+            if (!assignment) {
+                process.stderr.write(`Error: --var requires KEY=VALUE\n${usage}`);
+                process.exit(1);
+            }
+            const eqIndex = assignment.indexOf("=");
+            if (eqIndex <= 0) {
+                process.stderr.write(`Error: invalid --var assignment "${assignment}" (expected KEY=VALUE)\n${usage}`);
+                process.exit(1);
+            }
+            const key = assignment.slice(0, eqIndex);
+            const value = assignment.slice(eqIndex + 1);
+            vars[key] = value;
+            continue;
+        }
+        if (currentArg.startsWith("--")) {
+            process.stderr.write(`Error: unknown option ${currentArg}\n${usage}`);
+            process.exit(1);
+        }
+        if (!recipeRef) {
+            recipeRef = currentArg;
+            continue;
+        }
+        process.stderr.write(`Error: unexpected argument ${currentArg}\n${usage}`);
         process.exit(1);
     }
+    if (!recipeRef) {
+        process.stderr.write(usage);
+        process.exit(1);
+    }
+    const recipeArg = recipeRef;
     (async () => {
         try {
-            // Try bridge first (requires --claude-driver subprocess).
+            const seedVars = Object.keys(vars).length > 0 ? vars : undefined;
+            const explicitFile = (() => {
+                try {
+                    const resolved = path.resolve(recipeArg);
+                    return existsSync(resolved) && statSync(resolved).isFile();
+                }
+                catch {
+                    return false;
+                }
+            })();
             const { findBridgeLock } = await import("./bridgeLockDiscovery.js");
             const lock = localFlag ? null : findBridgeLock();
-            if (lock) {
+            if (lock && !dryRun && !step && !explicitFile) {
                 const res = await fetch(`http://127.0.0.1:${lock.port}/recipes/run`, {
                     method: "POST",
                     headers: {
                         Authorization: `Bearer ${lock.authToken}`,
                         "Content-Type": "application/json",
                     },
-                    body: JSON.stringify({ name }),
+                    body: JSON.stringify({
+                        name: recipeArg,
+                        ...(seedVars ? { vars: seedVars } : {}),
+                    }),
                 });
                 const body = (await res.json());
                 if (!body.ok) {
@@ -622,43 +696,64 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
                     // else: fall through to local runner below
                 }
                 else {
-                    process.stdout.write(`  ✓ enqueued recipe "${name}" as task ${(body.taskId ?? "").slice(0, 8)}\n` +
+                    process.stdout.write(`  ✓ enqueued recipe "${recipeArg}" as task ${(body.taskId ?? "").slice(0, 8)}\n` +
                         "    Watch progress on the dashboard Tasks page or via listClaudeTasks.\n");
                     process.exit(0);
                     return;
                 }
             }
-            // No bridge — run locally using the YAML runner.
-            const { loadYamlRecipe, runYamlRecipe } = await import("./recipes/yamlRunner.js");
-            const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
-            const bundledDir = fileURLToPath(new URL("../templates/recipes", import.meta.url));
-            const candidates = [
-                path.join(recipesDir, `${name}.yaml`),
-                path.join(recipesDir, `${name}.yml`),
-                path.join(recipesDir, `${name}.json`),
-                path.join(bundledDir, `${name}.yaml`),
-                path.join(bundledDir, `${name}.yml`),
-            ];
-            let recipePath;
-            for (const c of candidates) {
-                if (existsSync(c)) {
-                    recipePath = c;
-                    break;
-                }
-            }
-            if (!recipePath) {
-                process.stderr.write(`Error: recipe "${name}" not found in ${recipesDir}\n` +
-                    "  Run `patchwork-os recipe list` to see available recipes.\n");
-                process.exit(1);
+            const { runRecipe, runRecipeDryPlan, summarizeRecipeExecution, formatRunReport, extractRunLogStepResults, } = await import("./commands/recipe.js");
+            if (dryRun) {
+                const plan = await runRecipeDryPlan(recipeArg, {
+                    ...(step ? { step } : {}),
+                    ...(seedVars ? { vars: seedVars } : {}),
+                });
+                process.stdout.write(`${JSON.stringify(plan, null, 2)}\n`);
+                process.exit(0);
                 return;
             }
-            process.stdout.write(`  Running recipe "${name}" locally…\n`);
-            const recipe = loadYamlRecipe(recipePath);
+            process.stdout.write(step
+                ? `  Running step "${step}" from recipe "${recipeArg}" locally…\n`
+                : `  Running recipe "${recipeArg}" locally…\n`);
             const workdir = lock?.workspace || process.cwd();
-            const result = await runYamlRecipe(recipe, { workdir });
-            process.stdout.write(`  ✓ ${result.stepsRun} step(s) completed\n`);
-            if (result.outputs.length > 0) {
-                process.stdout.write(`  Output written to:\n${result.outputs.map((o) => `    ${o}`).join("\n")}\n`);
+            const run = await runRecipe(recipeArg, {
+                ...(step ? { step } : {}),
+                ...(seedVars ? { vars: seedVars } : {}),
+                workdir,
+            });
+            if (run.stepSelection) {
+                process.stdout.write(`  Selected step via ${run.stepSelection.matchedBy}: ${run.stepSelection.matchedValue}\n`);
+            }
+            const summary = summarizeRecipeExecution(run.result);
+            process.stdout.write(`${formatRunReport(run.result, run.recipe.name)}\n`);
+            if (summary.errorMessage) {
+                process.stderr.write(`  Error: ${summary.errorMessage}\n`);
+            }
+            // Append to run log so CLI runs appear in ctxQueryTraces + dashboard /runs
+            try {
+                const { RecipeRunLog } = await import("./runLog.js");
+                const runLog = new RecipeRunLog({
+                    dir: path.join(os.homedir(), ".patchwork"),
+                });
+                const startedAt = Date.now();
+                const stepResultsForLog = extractRunLogStepResults(run.result);
+                runLog.appendDirect({
+                    taskId: `cli-${Date.now()}`,
+                    recipeName: run.recipe.name,
+                    trigger: "recipe",
+                    status: summary.ok ? "done" : "error",
+                    createdAt: startedAt,
+                    startedAt,
+                    doneAt: Date.now(),
+                    durationMs: 0,
+                    ...(summary.errorMessage
+                        ? { errorMessage: summary.errorMessage }
+                        : {}),
+                    ...(stepResultsForLog ? { stepResults: stepResultsForLog } : {}),
+                });
+            }
+            catch {
+                // Non-fatal — run log write failure must not abort the CLI
             }
             process.exit(0);
         }
@@ -669,24 +764,324 @@ if (process.argv[2] === "recipe" && process.argv[3] === "run") {
     })();
 }
 // Handle init subcommand — one-command setup: install extension + write CLAUDE.md + print next steps
-// Patchwork: `patchwork recipe install <file.json>` subcommand.
+// Patchwork: `patchwork recipe install <source>` subcommand.
+// Supports: github:owner/repo, github:owner/repo/subdir, https://github.com/owner/repo,
+//           ./local/path, or legacy <file.json> (single-recipe install).
 if (process.argv[2] === "recipe" && process.argv[3] === "install") {
+    const source = process.argv[4];
+    if (!source) {
+        process.stderr.write("Usage: patchwork recipe install <source>\n" +
+            "  <source> can be:\n" +
+            "    github:owner/repo\n" +
+            "    github:owner/repo/subdir\n" +
+            "    https://github.com/owner/repo\n" +
+            "    ./local/path\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            // Legacy path: bare .json file argument → single-file installer
+            if (source.endsWith(".json") &&
+                !source.startsWith("github:") &&
+                !source.startsWith("http")) {
+                const { installRecipeFromFile } = await import("./recipes/installer.js");
+                const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
+                const result = installRecipeFromFile(path.resolve(source), {
+                    recipesDir,
+                });
+                process.stdout.write(`  ✓ ${result.action} ${result.installedPath}\n` +
+                    `  ℹ permissions snippet written to ${result.installedPath}.permissions.json\n` +
+                    `    Review + merge into ~/.claude/settings.json to pre-approve recipe steps.\n`);
+            }
+            else {
+                // Marketplace install: github:, https://, ./local/
+                const { runRecipeInstall, printInstallResult } = await import("./commands/recipeInstall.js");
+                const result = await runRecipeInstall(source);
+                printInstallResult(result);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe schema [outputDir]` — write generated recipe schemas to disk.
+if (process.argv[2] === "recipe" && process.argv[3] === "schema") {
+    const outputDir = process.argv[4] ?? path.join(process.cwd(), "schemas");
+    (async () => {
+        try {
+            const { runSchema } = await import("./commands/recipe.js");
+            const result = await runSchema(path.resolve(outputDir));
+            process.stdout.write(`  ✓ Wrote schemas to ${result.outputDir}\n`);
+            for (const file of result.filesWritten) {
+                process.stdout.write(`    ${file}\n`);
+            }
+            process.exit(0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe new <name>` — scaffold a new recipe from template.
+if (process.argv[2] === "recipe" && process.argv[3] === "new") {
+    const args = process.argv.slice(4);
+    const recipeName = args[0];
+    if (!recipeName) {
+        process.stderr.write("Usage: patchwork recipe new <name> [--template <name>] [--desc <description>]\n");
+        process.stderr.write("\nTemplates:\n");
+        (async () => {
+            const { listTemplates } = await import("./commands/recipe.js");
+            for (const t of listTemplates()) {
+                process.stderr.write(`  ${t}\n`);
+            }
+            process.exit(1);
+        })();
+    }
+    else {
+        (async () => {
+            try {
+                const { runNew } = await import("./commands/recipe.js");
+                const templateIdx = args.indexOf("--template");
+                const template = templateIdx >= 0 ? args[templateIdx + 1] : undefined;
+                const descIdx = args.indexOf("--desc");
+                const description = (descIdx >= 0 ? args[descIdx + 1] : undefined) ??
+                    `Recipe: ${recipeName}`;
+                const result = runNew({
+                    name: recipeName,
+                    description,
+                    ...(template ? { template } : {}),
+                });
+                process.stdout.write(`  ✓ Created ${result.path}\n`);
+                process.exit(0);
+            }
+            catch (err) {
+                process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+                process.exit(1);
+            }
+        })();
+    }
+}
+// Patchwork: `patchwork recipe lint <file.yaml>` — validate recipe against schema.
+if (process.argv[2] === "recipe" && process.argv[3] === "lint") {
     const file = process.argv[4];
     if (!file) {
-        process.stderr.write("Usage: patchwork recipe install <file.json>\n");
+        process.stderr.write("Usage: patchwork recipe lint <file.yaml>\n");
+        process.exit(1);
+    }
+    (async () => {
+        try {
+            const { runLint } = await import("./commands/recipe.js");
+            const result = runLint(path.resolve(file));
+            for (const issue of result.issues) {
+                const prefix = issue.level === "error" ? "✗" : "⚠";
+                process.stderr.write(`  ${prefix} ${issue.message}\n`);
+            }
+            if (result.valid) {
+                process.stdout.write(`  ✓ Valid recipe (${result.warnings} warnings)\n`);
+                process.exit(0);
+            }
+            else {
+                process.stdout.write(`\n  ${result.errors} error(s), ${result.warnings} warning(s)\n`);
+                process.exit(1);
+            }
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe preflight <file.yaml>` — static policy check (lint + plan + writes + fixtures).
+if (process.argv[2] === "recipe" && process.argv[3] === "preflight") {
+    const args = process.argv.slice(4);
+    const usage = "Usage: patchwork recipe preflight <file.yaml> [--json] [--watch] [--require-fixtures] [--no-require-write-ack] [--allow-write <tool-or-ns>]\n";
+    let json = false;
+    let watchMode = false;
+    let requireFixtures = false;
+    let requireWriteAck = true;
+    const allowWrites = [];
+    let file;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === undefined)
+            continue;
+        if (arg === "--json") {
+            json = true;
+            continue;
+        }
+        if (arg === "--watch") {
+            watchMode = true;
+            continue;
+        }
+        if (arg === "--require-fixtures") {
+            requireFixtures = true;
+            continue;
+        }
+        if (arg === "--no-require-write-ack") {
+            requireWriteAck = false;
+            continue;
+        }
+        if (arg === "--allow-write" || arg.startsWith("--allow-write=")) {
+            const value = arg === "--allow-write"
+                ? args[++i]
+                : arg.slice("--allow-write=".length);
+            if (!value) {
+                process.stderr.write(`Error: --allow-write requires a value\n${usage}`);
+                process.exit(1);
+            }
+            allowWrites.push(value);
+            continue;
+        }
+        if (!arg.startsWith("--")) {
+            file = arg;
+        }
+    }
+    if (!file) {
+        process.stderr.write(usage);
+        process.exit(1);
+    }
+    const renderResult = (result) => {
+        if (json) {
+            process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+            return;
+        }
+        for (const issue of result.issues) {
+            const prefix = issue.level === "error" ? "✗" : "⚠";
+            const where = issue.stepId ? ` [${issue.stepId}]` : "";
+            process.stderr.write(`  ${prefix} ${issue.code}${where}: ${issue.message}\n`);
+        }
+        if (result.ok) {
+            process.stdout.write(`  ✓ Preflight passed for ${result.recipe} (${result.plan.steps.length} steps)\n`);
+        }
+        else {
+            const errorCount = result.issues.filter((i) => i.level === "error").length;
+            process.stdout.write(`\n  ${errorCount} error(s) — preflight failed\n`);
+        }
+    };
+    (async () => {
+        try {
+            const { runPreflight, runPreflightWatch } = await import("./commands/recipe.js");
+            const resolvedPath = path.resolve(file);
+            if (watchMode) {
+                process.stdout.write(`  Watching ${resolvedPath} — preflight on save…\n`);
+                const stop = runPreflightWatch({
+                    recipePath: resolvedPath,
+                    requireWriteAck,
+                    requireFixtures,
+                    allowWrites,
+                    onResult: (result) => renderResult(result),
+                    onError: (err) => {
+                        process.stderr.write(`Error: ${err.message}\n`);
+                    },
+                });
+                process.on("SIGINT", () => {
+                    stop();
+                    process.exit(0);
+                });
+                return;
+            }
+            const result = await runPreflight(resolvedPath, {
+                requireWriteAck,
+                requireFixtures,
+                allowWrites,
+            });
+            renderResult(result);
+            process.exit(result.ok ? 0 : 1);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe fmt <file.yaml>` — format/normalize recipe.
+if (process.argv[2] === "recipe" && process.argv[3] === "fmt") {
+    const args = process.argv.slice(4);
+    const check = args.includes("--check");
+    const watchMode = args.includes("--watch");
+    const file = args.find((arg) => !arg.startsWith("--"));
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe fmt <file.yaml> [--check] [--watch]\n");
+        process.exit(1);
+    }
+    const renderResult = (result, filePath) => {
+        if (check) {
+            process.stdout.write(result.changed
+                ? "  ✗ File would be reformatted\n"
+                : "  ✓ File is already formatted\n");
+        }
+        else {
+            process.stdout.write(result.changed
+                ? `  ✓ Formatted ${filePath}\n`
+                : `  ✓ Already formatted ${filePath}\n`);
+        }
+    };
+    (async () => {
+        try {
+            const { runFmt, runFmtWatch } = await import("./commands/recipe.js");
+            const resolvedPath = path.resolve(file);
+            if (watchMode) {
+                process.stdout.write(`  Watching ${resolvedPath} — fmt on save…\n`);
+                const stop = runFmtWatch({
+                    recipePath: resolvedPath,
+                    check,
+                    onResult: (result) => {
+                        process.stdout.write(`\n[${new Date().toLocaleTimeString()}] ${resolvedPath}\n`);
+                        renderResult(result, resolvedPath);
+                    },
+                    onError: (err) => {
+                        process.stderr.write(`Error: ${err.message}\n`);
+                    },
+                });
+                process.on("SIGINT", () => {
+                    stop();
+                    process.exit(0);
+                });
+                return;
+            }
+            const result = runFmt(resolvedPath, { check });
+            renderResult(result, file);
+            process.exit(check && result.changed ? 1 : 0);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe record <file.yaml>` — execute live and record connector fixtures.
+if (process.argv[2] === "recipe" && process.argv[3] === "record") {
+    const args = process.argv.slice(4);
+    const file = args.find((arg) => !arg.startsWith("--"));
+    const fixturesIdx = args.indexOf("--fixtures");
+    const fixturesDir = fixturesIdx >= 0 ? args[fixturesIdx + 1] : undefined;
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe record <file.yaml> [--fixtures <dir>]\n");
         process.exit(1);
     }
     (async () => {
         try {
-            const { installRecipeFromFile } = await import("./recipes/installer.js");
-            const recipesDir = path.join(os.homedir(), ".patchwork", "recipes");
-            const result = installRecipeFromFile(path.resolve(file), {
-                recipesDir,
+            const { runRecord } = await import("./commands/recipe.js");
+            const result = await runRecord(path.resolve(file), {
+                ...(fixturesDir ? { fixturesDir: path.resolve(fixturesDir) } : {}),
             });
-            process.stdout.write(`  ✓ ${result.action} ${result.installedPath}\n` +
-                `  ℹ permissions snippet written to ${result.installedPath}.permissions.json\n` +
-                `    Review + merge into ~/.claude/settings.json to pre-approve recipe steps.\n`);
-            process.exit(0);
+            for (const issue of result.issues) {
+                const prefix = issue.level === "error" ? "✗" : "⚠";
+                process.stderr.write(`  ${prefix} ${issue.message}\n`);
+            }
+            if (result.recordedFixtures.length > 0) {
+                process.stdout.write(`  ℹ Recorded fixture libraries: ${result.recordedFixtures.join(", ")}\n`);
+            }
+            if (result.valid) {
+                process.stdout.write("  ✓ Recipe fixtures recorded\n");
+                process.exit(0);
+            }
+            process.stdout.write(`\n  ${result.errors} error(s), ${result.warnings} warning(s)\n`);
+            process.exit(1);
         }
         catch (err) {
             process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
@@ -694,6 +1089,153 @@ if (process.argv[2] === "recipe" && process.argv[3] === "install") {
         }
     })();
 }
+// Patchwork: `patchwork recipe test <file.yaml>` — validate fixture coverage for mocked execution.
+if (process.argv[2] === "recipe" && process.argv[3] === "test") {
+    const args = process.argv.slice(4);
+    const file = args.find((arg) => !arg.startsWith("--"));
+    const fixturesIdx = args.indexOf("--fixtures");
+    const fixturesDir = fixturesIdx >= 0 ? args[fixturesIdx + 1] : undefined;
+    const watchMode = args.includes("--watch");
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe test <file.yaml> [--fixtures <dir>] [--watch]\n");
+        process.exit(1);
+    }
+    const renderResult = (result) => {
+        for (const issue of result.issues) {
+            const prefix = issue.level === "error" ? "✗" : "⚠";
+            process.stderr.write(`  ${prefix} ${issue.message}\n`);
+        }
+        if (result.requiredFixtures.length > 0) {
+            process.stdout.write(`  ℹ Required fixtures: ${result.requiredFixtures.join(", ")}\n`);
+        }
+        if (result.valid) {
+            process.stdout.write("  ✓ Test passed\n");
+        }
+        else {
+            process.stdout.write(`\n  ${result.errors} error(s), ${result.warnings} warning(s)\n`);
+        }
+    };
+    (async () => {
+        try {
+            const { runTest, runTestWatch } = await import("./commands/recipe.js");
+            const resolvedPath = path.resolve(file);
+            const resolvedFixtures = fixturesDir
+                ? path.resolve(fixturesDir)
+                : undefined;
+            if (watchMode) {
+                process.stdout.write(`  Watching ${resolvedPath} — test on save…\n`);
+                const stop = runTestWatch({
+                    recipePath: resolvedPath,
+                    ...(resolvedFixtures ? { fixturesDir: resolvedFixtures } : {}),
+                    onResult: (result) => {
+                        process.stdout.write(`\n[${new Date().toLocaleTimeString()}] ${resolvedPath}\n`);
+                        renderResult(result);
+                    },
+                    onError: (err) => {
+                        process.stderr.write(`Error: ${err.message}\n`);
+                    },
+                });
+                process.on("SIGINT", () => {
+                    stop();
+                    process.exit(0);
+                });
+                return;
+            }
+            const result = await runTest(resolvedPath, {
+                ...(resolvedFixtures ? { fixturesDir: resolvedFixtures } : {}),
+            });
+            renderResult(result);
+            process.exit(result.valid ? 0 : 1);
+        }
+        catch (err) {
+            process.stderr.write(`Error: ${err instanceof Error ? err.message : String(err)}\n`);
+            process.exit(1);
+        }
+    })();
+}
+// Patchwork: `patchwork recipe watch <file.yaml>` — watch for changes and validate.
+if (process.argv[2] === "recipe" && process.argv[3] === "watch") {
+    const file = process.argv[4];
+    if (!file) {
+        process.stderr.write("Usage: patchwork recipe watch <file.yaml>\n");
+        process.exit(1);
+    }
+    (async () => {
+        const { findBridgeLock } = await import("./bridgeLockDiscovery.js");
+        const { runWatch, runLint, runWatchedRecipe, formatRunReport, summarizeRecipeExecution, extractRunLogStepResults, } = await import("./commands/recipe.js");
+        const filePath = path.resolve(file);
+        const lock = findBridgeLock();
+        const workdir = lock?.workspace || process.cwd();
+        const initial = runLint(filePath);
+        if (!initial.valid) {
+            process.stderr.write("  ✗ Recipe has errors - fix before watching\n");
+            for (const issue of initial.issues) {
+                process.stderr.write(`    ${issue.level}: ${issue.message}\n`);
+            }
+        }
+        else {
+            process.stdout.write(`  ✓ Watching ${file} for changes...\n`);
+        }
+        const stop = runWatch({
+            recipePath: filePath,
+            onChange: async () => {
+                process.stdout.write(`\n  Change detected, running...\n`);
+                const watched = await runWatchedRecipe(filePath, { workdir });
+                if (!watched.lint.valid) {
+                    process.stderr.write(`  ✗ Invalid (${watched.lint.errors} errors)\n`);
+                    for (const issue of watched.lint.issues) {
+                        process.stderr.write(`    ${issue.level}: ${issue.message}\n`);
+                    }
+                    return;
+                }
+                if (watched.run?.stepSelection) {
+                    process.stdout.write(`  Selected step via ${watched.run.stepSelection.matchedBy}: ${watched.run.stepSelection.matchedValue}\n`);
+                }
+                if (watched.run) {
+                    process.stdout.write(`${formatRunReport(watched.run.result, watched.run.recipe.name)}\n`);
+                    const summary = summarizeRecipeExecution(watched.run.result);
+                    if (summary.errorMessage) {
+                        process.stderr.write(`  Error: ${summary.errorMessage}\n`);
+                    }
+                    // Append to run log
+                    try {
+                        const { RecipeRunLog } = await import("./runLog.js");
+                        const runLog = new RecipeRunLog({
+                            dir: path.join(os.homedir(), ".patchwork"),
+                        });
+                        const now = Date.now();
+                        const stepResultsForLog = extractRunLogStepResults(watched.run.result);
+                        runLog.appendDirect({
+                            taskId: `watch-${now}`,
+                            recipeName: watched.run.recipe.name,
+                            trigger: "recipe",
+                            status: summary.ok ? "done" : "error",
+                            createdAt: now,
+                            startedAt: now,
+                            doneAt: now,
+                            durationMs: 0,
+                            ...(summary.errorMessage
+                                ? { errorMessage: summary.errorMessage }
+                                : {}),
+                            ...(stepResultsForLog ? { stepResults: stepResultsForLog } : {}),
+                        });
+                    }
+                    catch {
+                        // non-fatal
+                    }
+                }
+            },
+            onError: (err) => {
+                process.stderr.write(`  Error: ${err.message}\n`);
+            },
+        });
+        process.on("SIGINT", () => {
+            process.stdout.write("\n  Stopping watch...\n");
+            stop();
+            process.exit(0);
+        });
+    })();
+}
 if (process.argv[2] === "init") {
     const argv = process.argv.slice(3);
     // Handle init --help
@@ -1383,6 +1925,23 @@ Options:
     }
     process.exit(0);
 }
+// Handle launchd subcommand — install/uninstall macOS LaunchAgent for auto-start
+if (process.argv[2] === "launchd") {
+    const sub = process.argv[3];
+    if (sub === "install") {
+        const { runLaunchdInstall } = await import("./commands/launchd.js");
+        await runLaunchdInstall(process.argv.slice(4));
+    }
+    else if (sub === "uninstall") {
+        const { runLaunchdUninstall } = await import("./commands/launchd.js");
+        await runLaunchdUninstall(process.argv.slice(4));
+    }
+    else {
+        process.stderr.write("Usage: patchwork-os launchd install|uninstall\n");
+        process.exit(1);
+    }
+    process.exit(0);
+}
 // F6: "Did you mean?" for unknown CLI subcommands
 // Patchwork: no-args → terminal dashboard (when invoked as patchwork-os or patchwork).
 {
@@ -1413,6 +1972,7 @@ Options:
         "shim",
         "recipe",
         "dashboard",
+        "launchd",
     ];
     const unknownSub = process.argv[2];
     if (unknownSub &&