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

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;