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

package/dist/commands/patchworkInit.js

@@ -3,29 +3,50 @@ import { homedir } from "node:os";
 import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { loadConfig, saveConfig, } from "../patchworkConfig.js";
+import { registerPreToolUseHook } from "../preToolUseHook.js";
 function parseArgs(argv) {
     if (argv.includes("--help") || argv.includes("-h"))
         return { help: true };
     return {
         force: argv.includes("--force"),
         skipOllama: argv.includes("--no-ollama"),
+        withConnectors: argv.includes("--with-connectors"),
     };
 }
+// Recipes that run with no external service credentials (local file/git only).
+// Anything not in this set requires a connector (gmail, github, linear, slack,
+// sentry, calendar, …) and is skipped on first init unless --with-connectors.
+const LOCAL_ONLY_RECIPES = new Set([
+    "ambient-journal.yaml",
+    "daily-status.yaml",
+    "lint-on-save.yaml",
+    "stale-branches.yaml",
+    "watch-failing-tests.yaml",
+]);
+// Dev/dogfood fixtures that aren't user-facing and shouldn't be seeded by
+// either init mode. Skipped silently regardless of --with-connectors.
+const DEV_FIXTURE_RECIPES = new Set([
+    "ctx-loop-test.yaml",
+]);
 function printHelp() {
     process.stdout.write(`patchwork-os init — Set up ~/.patchwork on this machine
 
 Usage: patchwork-os init [options]
 
 Options:
-  --force      Overwrite existing config (default: merge, preserve)
-  --no-ollama  Skip Ollama detection
-  --help, -h   Show this help
+  --force             Overwrite existing config (default: merge, preserve)
+  --no-ollama         Skip Ollama detection
+  --with-connectors   Also copy connector-dependent recipes (gmail, github, …)
+  --help, -h          Show this help
 
 What it does:
   1. Create ~/.patchwork/{config.json,recipes,inbox,journal}
-  2. Copy 5 local-only recipe templates to ~/.patchwork/recipes/
+  2. Copy local-only recipe templates to ~/.patchwork/recipes/
+     (add --with-connectors to also copy gmail/github/etc. recipes)
   3. Detect Ollama at localhost:11434 → set provider to ollama-local
-  4. Print next steps
+  4. Register the Patchwork PreToolUse hook in ~/.claude/settings.json
+     so Claude Code routes tool calls through your delegation policy
+  5. Print next steps
 `);
 }
 function findTemplatesDir() {
@@ -76,10 +97,17 @@ export async function runPatchworkInit(argv, opts = {}) {
     const templatesDir = findTemplatesDir();
     let recipesCopied = 0;
     let recipesSkipped = 0;
+    let recipesGated = 0;
     if (templatesDir) {
         for (const name of readdirSync(templatesDir)) {
             if (!name.endsWith(".yaml"))
                 continue;
+            if (DEV_FIXTURE_RECIPES.has(name))
+                continue;
+            if (!parsed.withConnectors && !LOCAL_ONLY_RECIPES.has(name)) {
+                recipesGated++;
+                continue;
+            }
             const dest = join(recipesDir, name);
             if (existsSync(dest) && !parsed.force) {
                 recipesSkipped++;
@@ -88,7 +116,10 @@ export async function runPatchworkInit(argv, opts = {}) {
             copyFileSync(join(templatesDir, name), dest);
             recipesCopied++;
         }
-        log(`  ✓ recipes: ${recipesCopied} copied, ${recipesSkipped} preserved\n`);
+        const gatedNote = recipesGated
+            ? ` (${recipesGated} connector-recipes skipped — re-run with --with-connectors)`
+            : "";
+        log(`  ✓ recipes: ${recipesCopied} copied, ${recipesSkipped} preserved${gatedNote}\n`);
     }
     else {
         log(`  ! recipe templates not found (expected templates/recipes/)\n`);
@@ -127,7 +158,7 @@ export async function runPatchworkInit(argv, opts = {}) {
             model: ollamaDetected ? "local" : "claude",
             recipesDir,
             dashboard: {
-                port: 3000,
+                port: 3200,
                 requireApproval: ["high"],
                 pushNotifications: false,
             },
@@ -139,10 +170,44 @@ export async function runPatchworkInit(argv, opts = {}) {
             existsSync(configPath) && parsed.force ? "overwritten" : "created";
     }
     log(`  ✓ config ${configAction}: ${configPath}\n`);
-    log(`\nNext:
-  1. patchwork-os recipe run ambient-journal   # try a local recipe
-  2. patchwork-os                              # launch terminal dashboard
-  3. Connect Gmail (coming in W2) — see docs/adr/0008-connector-scope-decision.md\n`);
+    // Register the Patchwork PreToolUse hook in Claude Code's settings.json
+    // so CC actually routes tool calls through the bridge's approval queue.
+    // Without this, `--approval-gate` is silently inert and the entire
+    // personalSignals catalog has no input data — exactly the foot-gun
+    // PR #150 added a startup warning for. Now `patchwork-init` fixes it
+    // at the source rather than just warning about it later.
+    const ccSettingsDir = process.env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
+    mkdirSync(ccSettingsDir, { recursive: true });
+    const ccSettingsPath = join(ccSettingsDir, "settings.json");
+    const hookResult = registerPreToolUseHook(ccSettingsPath);
+    let preToolUseHook;
+    if (hookResult.action === "added") {
+        log(`  ✓ Claude Code PreToolUse hook registered: ${ccSettingsPath}\n`);
+        preToolUseHook = "added";
+    }
+    else if (hookResult.action === "already-wired") {
+        log(`  ✓ Claude Code PreToolUse hook already registered\n`);
+        preToolUseHook = "already-wired";
+    }
+    else {
+        log(`  ! Could not register Claude Code PreToolUse hook: ${hookResult.error ?? "unknown"}\n` +
+            `    Delegation policy will not see traffic until you add the hook manually.\n`);
+        preToolUseHook = "error";
+    }
+    // CC reads hooks at session start, so the registration we just did
+    // (or confirmed) only takes effect for *future* sessions. Without
+    // this prompt, users follow the docs, run init, and the delegation policy
+    // still appears inert — the trap that wasted hours of investigation
+    // during dogfood verification on 2026-05-03.
+    const restartLine = preToolUseHook === "added"
+        ? `\n  ⚠  Restart Claude Code so the new PreToolUse hook takes effect.\n     (CC reads hooks at session start — existing sessions won't see the change.)\n`
+        : "";
+    log(`${restartLine}\nNext:
+  1. patchwork start                           # launch bridge + Claude + dashboard (one command)
+  2. patchwork-os recipe run daily-status      # zero-config: yesterday's commits + today's hints
+  3. patchwork-os                              # terminal dashboard (TUI, alternative to web)
+  4. patchwork-os recipe list                  # browse installed recipes
+  5. patchwork-os init --with-connectors       # add gmail/github/linear/etc. recipes\n`);
     return {
         configPath,
         recipesDir,
@@ -150,6 +215,7 @@ export async function runPatchworkInit(argv, opts = {}) {
         recipesSkipped,
         ollamaDetected,
         configAction,
+        preToolUseHook,
     };
 }
 //# sourceMappingURL=patchworkInit.js.map

package/dist/commands/patchworkInit.js.map

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

package/dist/commands/recipe.d.ts

@@ -0,0 +1,289 @@
+/**
+ * Recipe CLI commands — new, lint, test, watch, record, fmt
+ *
+ * Implements the A2 CLI UX milestone for recipe authoring.
+ */
+import "../recipes/tools/index.js";
+import { type LintIssue, type LintResult } from "../recipes/validation.js";
+import { type RunnerDeps, type RunResult, type YamlRecipe } from "../recipes/yamlRunner.js";
+export interface NewOptions {
+    name: string;
+    description: string;
+    template?: string;
+    outputDir?: string;
+}
+export declare function runNew(options: NewOptions): {
+    path: string;
+    content: string;
+};
+export declare function listTemplates(): string[];
+export interface SchemaWriteResult {
+    outputDir: string;
+    filesWritten: string[];
+}
+export declare function runSchema(outputDir: string): Promise<SchemaWriteResult>;
+export type { LintIssue, LintResult };
+/**
+ * Lint a recipe file against the schema.
+ * Falls back to basic YAML parsing if schema linting is disabled.
+ */
+export declare function runLint(recipePath: string): LintResult;
+export interface FmtResult {
+    formatted: string;
+    changed: boolean;
+}
+/**
+ * Format/normalize a recipe file.
+ * - Normalizes YAML formatting
+ * - Sorts keys in consistent order
+ * - Validates and re-serializes
+ */
+export declare function runFmt(recipePath: string, options?: {
+    check?: boolean;
+}): FmtResult;
+export interface FmtWatchOptions {
+    recipePath: string;
+    check?: boolean;
+    onResult: (result: FmtResult) => void | Promise<void>;
+    onError?: (err: Error) => void;
+    debounceMs?: number;
+    watchFactory?: WatchFactory;
+}
+/**
+ * Watch a recipe file and re-run `runFmt` on every save (debounced).
+ * Mirrors runPreflightWatch / runTestWatch — composes runWatch + runFmt.
+ * Returns a stop function.
+ */
+export declare function runFmtWatch(options: FmtWatchOptions): () => void;
+export interface RunRecipeOptions {
+    dryRun?: boolean;
+    step?: string;
+    vars?: Record<string, string>;
+    workdir?: string;
+    deps?: Partial<RunnerDeps>;
+}
+export interface RunRecipeStepSelection {
+    query: string;
+    matchedBy: "id" | "into" | "tool";
+    matchedValue: string;
+}
+export interface RunRecipeResult {
+    recipe: YamlRecipe;
+    recipePath: string;
+    result: RunResult | import("../recipes/chainedRunner.js").ChainedRunResult;
+    stepSelection?: RunRecipeStepSelection;
+}
+export interface RecipeExecutionSummary {
+    ok: boolean;
+    steps: number;
+    outputs: string[];
+    errorMessage?: string;
+    failed?: number;
+    skipped?: number;
+}
+export interface WatchedRecipeRunResult {
+    lint: LintResult;
+    run?: RunRecipeResult;
+    summary?: RecipeExecutionSummary;
+}
+export declare function runRecipe(recipeRef: string, options?: RunRecipeOptions): Promise<RunRecipeResult>;
+export declare function summarizeRecipeExecution(result: RunRecipeResult["result"]): RecipeExecutionSummary;
+/**
+ * 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 declare function extractRunLogStepResults(result: RunRecipeResult["result"]): Array<{
+    id: string;
+    tool?: string;
+    status: "ok" | "skipped" | "error";
+    error?: string;
+    durationMs: number;
+}> | undefined;
+export declare function formatRunReport(result: RunRecipeResult["result"], recipeName: string): string;
+export declare function runWatchedRecipe(recipePath: string, options?: Pick<RunRecipeOptions, "workdir" | "deps" | "vars">): Promise<WatchedRecipeRunResult>;
+/**
+ * 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 declare const DRY_RUN_PLAN_SCHEMA_VERSION = 1;
+export interface RecipeDryRunPlanStep {
+    id: string;
+    type: "tool" | "agent" | "recipe";
+    tool?: string;
+    /** Namespace derived from tool id (e.g. "gmail" from "gmail.fetch_unread"). */
+    namespace?: string;
+    into?: string;
+    optional?: boolean;
+    prompt?: string;
+    params?: Record<string, unknown>;
+    dependencies?: string[];
+    condition?: string;
+    /** Explicit risk on the step, or registry default when absent. */
+    risk?: "low" | "medium" | "high";
+    /** Registry metadata — true if the tool mutates external state. */
+    isWrite?: boolean;
+    /** Registry metadata — true if the tool calls an external SaaS connector. */
+    isConnector?: boolean;
+    /** True if the tool id is known to the registry (false → unresolved at plan time). */
+    resolved?: boolean;
+    /**
+     * Nested-recipe reference for `step.type === "recipe"` (chained recipes
+     * with `recipe:` or `chain:` field). Bare name (e.g. `branch-health`) or
+     * relative/absolute path. F-07 fix: this is now part of the plan-step
+     * shape so write-detection can recurse into nested recipes.
+     */
+    recipe?: string;
+    /**
+     * F-07 fix: when this step is a nested recipe and its writes were
+     * detected via recursion, this is the count of write-tagged tool steps
+     * inside the nested recipe (transitively). 0 if the recurse depth was
+     * hit before any writes were found, undefined for non-recipe steps.
+     */
+    nestedWriteCount?: number;
+}
+export interface RecipeDryRunPlan {
+    /** Stable schema version for consumers. */
+    schemaVersion: typeof DRY_RUN_PLAN_SCHEMA_VERSION;
+    recipe: string;
+    mode: "dry-run";
+    triggerType: string;
+    /** ISO-8601 generation timestamp. */
+    generatedAt: string;
+    stepSelection?: RunRecipeStepSelection;
+    steps: RecipeDryRunPlanStep[];
+    parallelGroups?: string[][];
+    maxDepth?: number;
+    /** Distinct connector namespaces referenced by the plan. */
+    connectorNamespaces?: string[];
+    /** True if any step is registry-tagged as a write/mutation. */
+    hasWriteSteps?: boolean;
+    /**
+     * Static lint pass over the recipe definition (validateRecipeDefinition).
+     * Surfaces error- and warning-level issues — including dotted-ref / output
+     * schema warnings — so editors and dashboards consuming the plan see the
+     * same signal as the CLI lint and the dashboard editor. Always present;
+     * arrays may be empty when the recipe is clean.
+     */
+    lint: {
+        errors: string[];
+        warnings: string[];
+    };
+}
+export declare function runRecipeDryPlan(recipeRef: string, options?: RunRecipeOptions): Promise<RecipeDryRunPlan>;
+export type PreflightIssueCode = "unresolved-tool" | "unacknowledged-write" | "missing-fixture" | "lint-error" | "lint-warning" | "into-shadows-builtin" | "into-duplicate";
+export interface PreflightIssue {
+    level: "error" | "warning";
+    code: PreflightIssueCode;
+    message: string;
+    stepId?: string;
+    tool?: string;
+    namespace?: string;
+}
+export interface PreflightResult {
+    ok: boolean;
+    recipe: string;
+    issues: PreflightIssue[];
+    plan: RecipeDryRunPlan;
+}
+export interface PreflightOptions extends RunRecipeOptions {
+    /**
+     * If true, steps tagged `isWrite: true` fail preflight unless the recipe opts in
+     * via a matching `allowWrites` entry (tool id or namespace). Default: true.
+     */
+    requireWriteAck?: boolean;
+    /**
+     * Explicit allowlist of tool ids or namespaces the caller acknowledges as writes.
+     * Example: `["slack.post_message", "github"]`.
+     */
+    allowWrites?: string[];
+    /**
+     * If true, missing fixture libraries for connector namespaces become errors.
+     * Default: false — preflight is a policy check, not a mock-run.
+     */
+    requireFixtures?: boolean;
+    /** Override fixtures dir (defaults to ~/.patchwork/fixtures). */
+    fixturesDir?: string;
+}
+/**
+ * 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 declare function runPreflight(recipeRef: string, options?: PreflightOptions): Promise<PreflightResult>;
+export interface PreflightWatchOptions extends PreflightOptions {
+    recipePath: string;
+    onResult: (result: PreflightResult) => void | Promise<void>;
+    onError?: (err: Error) => void;
+    debounceMs?: number;
+    watchFactory?: WatchFactory;
+}
+/**
+ * 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 declare function runPreflightWatch(options: PreflightWatchOptions): () => void;
+/**
+ * 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 declare function resolveRecipeRefForCli(recipeRef: string): string;
+export interface RecipeTestResult {
+    valid: boolean;
+    issues: LintIssue[];
+    warnings: number;
+    errors: number;
+    requiredFixtures: string[];
+    missingFixtures: string[];
+    stepsRun: number;
+    outputs: string[];
+    assertionFailures: import("../recipes/yamlRunner.js").AssertionFailure[];
+}
+export interface RecipeRecordResult {
+    valid: boolean;
+    issues: LintIssue[];
+    warnings: number;
+    errors: number;
+    recordedFixtures: string[];
+    stepsRun: number;
+    outputs: string[];
+}
+export declare function runRecord(recipePath: string, options?: {
+    fixturesDir?: string;
+    deps?: Partial<RunnerDeps>;
+}): Promise<RecipeRecordResult>;
+export declare function runTest(recipePath: string, options?: {
+    fixturesDir?: string;
+}): Promise<RecipeTestResult>;
+export interface TestWatchOptions {
+    recipePath: string;
+    fixturesDir?: string;
+    onResult: (result: RecipeTestResult) => void | Promise<void>;
+    onError?: (err: Error) => void;
+    debounceMs?: number;
+    watchFactory?: WatchFactory;
+}
+/**
+ * Watch a recipe file and re-run `patchwork recipe test` on every save (debounced).
+ * Mirrors runPreflightWatch — composes runWatch + runTest.
+ * Returns a stop function.
+ */
+export declare function runTestWatch(options: TestWatchOptions): () => void;
+type WatchFactory = (path: string, options: {
+    recursive: boolean;
+}, listener: (eventType: string, changedFile: string | Buffer | null) => void) => {
+    close(): void;
+};
+export interface WatchOptions {
+    recipePath: string;
+    onChange: () => void | Promise<void>;
+    onError?: (err: Error) => void;
+    debounceMs?: number;
+    watchFactory?: WatchFactory;
+}
+export declare function runWatch(options: WatchOptions): () => void;