patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.100

package/dist/commands/recipe.d.ts

@@ -4,6 +4,7 @@
  * Implements the A2 CLI UX milestone for recipe authoring.
  */
 import "../recipes/tools/index.js";
+import { type HaltCategory } from "../recipes/haltCategory.js";
 import { type LintIssue, type LintResult } from "../recipes/validation.js";
 import { type RunnerDeps, type RunResult, type YamlRecipe } from "../recipes/yamlRunner.js";
 export interface NewOptions {
@@ -17,6 +18,43 @@ export declare function runNew(options: NewOptions): {
     content: string;
 };
 export declare function listTemplates(): string[];
+export interface InteractivePromptDeps {
+    /** Free-text prompt. Returns the user's trimmed answer. */
+    ask: (question: string) => Promise<string>;
+    /**
+     * List-select prompt. Returns the 1-based index of the choice the
+     * user picked. Implementations must reject 0 / out-of-range / NaN.
+     */
+    pickFromList: (question: string, options: string[]) => Promise<number>;
+    /** Y/N prompt. Returns true on yes. */
+    confirm: (question: string) => Promise<boolean>;
+    /** Optional preview hook — called once before the final write confirm. */
+    preview?: (yaml: string) => void;
+}
+export interface InteractiveNewOptions {
+    outputDir?: string;
+    deps: InteractivePromptDeps;
+    /**
+     * AI-suggest path. Injected so tests can stub the bridge-discovery +
+     * fetch pair without touching the network or the lock-file dir. When
+     * omitted, runNewInteractive uses the production defaults (findBridgeLock
+     * + global fetch). The CLI dispatch passes nothing.
+     */
+    aiSuggest?: {
+        findBridge?: () => {
+            port: number;
+            authToken: string;
+        } | null;
+        fetch?: typeof globalThis.fetch;
+    };
+}
+export interface InteractiveNewResult {
+    path: string;
+    content: string;
+    /** Lint issues surfaced by validateRecipeDefinition (warnings only — write proceeds). */
+    warnings: LintIssue[];
+}
+export declare function runNewInteractive(options: InteractiveNewOptions): Promise<InteractiveNewResult>;
 export interface SchemaWriteResult {
     outputDir: string;
     filesWritten: string[];
@@ -61,6 +99,20 @@ export interface RunRecipeOptions {
     vars?: Record<string, string>;
     workdir?: string;
     deps?: Partial<RunnerDeps>;
+    /**
+     * PR5c — stable id for one *logical* execution attempt. Forwarded to
+     * RunnerDeps so the runner constructs a disk-backed WriteEffectLedger
+     * scoped by `${recipe.name}:${manualRunId}`. Re-using the same id on
+     * a retry replays prior dedup records and skips already-completed
+     * write tools (resume semantics).
+     */
+    manualRunId?: string;
+    /**
+     * PR5c — directory holding `effect_ledger.jsonl`. Required for the
+     * disk-backed ledger; without it the ledger stays in-memory even
+     * when manualRunId is set.
+     */
+    ledgerDir?: string;
 }
 export interface RunRecipeStepSelection {
     query: string;
@@ -227,6 +279,105 @@ export interface PreflightWatchOptions extends PreflightOptions {
  * at most one rerun is queued (matches runWatch semantics).
  */
 export declare function runPreflightWatch(options: PreflightWatchOptions): () => void;
+/** Recent runtime halts for one recipe — the shape of `/runs/halt-summary`. */
+export interface DoctorRuntimeHalts {
+    total: number;
+    byCategory: Partial<Record<HaltCategory, number>>;
+    recent: Array<{
+        reason: string;
+        category: string;
+        runSeq: number;
+    }>;
+}
+/** One connection-status entry as reported by the bridge `/connections` list. */
+export interface DoctorConnectionEntry {
+    id?: string;
+    status?: string;
+}
+export interface RecipeDoctorOptions extends PreflightOptions {
+    /**
+     * Fetches recent runtime halts for the recipe by name. Returns null when
+     * no bridge is reachable (doctor degrades to static-only). Injected so
+     * the bridge walk lives in the CLI layer and the command stays testable.
+     */
+    fetchHalts?: (recipeName: string) => Promise<DoctorRuntimeHalts | null>;
+    /**
+     * Fetches the current connector statuses (`/connections` payload — the
+     * same `handleConnectionsList` source the dashboard install preflight
+     * uses). Returns null when no bridge is reachable, in which case doctor
+     * reports the *required* connectors statically but skips the
+     * authorized/missing classification. Injected for the same reason as
+     * `fetchHalts`: the bridge walk stays in the CLI layer and the command
+     * stays testable.
+     *
+     * "Connector not authorized" is the #1 runtime-halt class — surfacing the
+     * unauthenticated connectors a recipe needs (with the one-command fix)
+     * turns the most common silent first-run failure into an up-front
+     * diagnosis.
+     */
+    fetchConnections?: () => Promise<DoctorConnectionEntry[] | null>;
+}
+/**
+ * Static half of the doctor report. A lighter projection of
+ * `PreflightResult` (drops the plan, which the report doesn't render) so
+ * doctor can also represent the lint-only fallback path — when a recipe
+ * is too broken to even load/plan, `runPreflight` throws, and we still
+ * want a clean diagnosis rather than a stack trace.
+ */
+export interface DoctorStaticResult {
+    ok: boolean;
+    recipe: string;
+    issues: PreflightIssue[];
+    /** True when the recipe couldn't be planned (load threw) — lint-only. */
+    planSkipped?: boolean;
+}
+/**
+ * Connector authorization diagnosis. `required` is always populated (static
+ * detection over the recipe's steps — no bridge needed). `missing` /
+ * `authorized` are only meaningful when `connectionsChecked` is true; when no
+ * bridge was reachable we still tell the user which connectors the recipe
+ * needs but can't say which are authorized.
+ */
+export interface DoctorConnectorsResult {
+    /** Connector ids the recipe requires (static detection). Sorted. */
+    required: string[];
+    /** Required connectors that are NOT in a "connected" state. */
+    missing: string[];
+    /** Required connectors that ARE connected. */
+    authorized: string[];
+    /** True when live connection statuses were fetched and classified. */
+    connectionsChecked: boolean;
+    /** Why the auth check was skipped (no bridge / not requested), if applicable. */
+    note?: string;
+}
+export interface RecipeDoctorResult {
+    recipe: string;
+    recipePath: string;
+    /** Static analysis: lint + write-policy + dry-plan (lint-only on load failure). */
+    static: DoctorStaticResult;
+    /** Required connectors + (when a bridge was reachable) their auth state. */
+    connectors: DoctorConnectorsResult;
+    /** Recent runtime halts, or null when no bridge was reachable. */
+    runtime: DoctorRuntimeHalts | null;
+    /** Why runtime is null (e.g. "no running bridge"), when applicable. */
+    runtimeNote?: string;
+    /** True when static passed, no required connectors are missing, AND no runtime halts were seen. */
+    ok: boolean;
+}
+/**
+ * `recipe doctor` — one-screen "why is this recipe unhealthy + how do I
+ * fix it" diagnosis. Composes the static `preflight` check (lint + policy
+ * + plan) and static connector detection with the recipe-scoped runtime
+ * halt summary, mapping every finding to an actionable hint. Fail-soft: a
+ * missing bridge degrades to static-only rather than erroring.
+ */
+export declare function runRecipeDoctor(recipeRef: string, options?: RecipeDoctorOptions): Promise<RecipeDoctorResult>;
+/**
+ * Render a `RecipeDoctorResult` as a one-screen human report. Returns the
+ * text so the CLI handler can write it (and tests can assert on it)
+ * without coupling to process.stdout.
+ */
+export declare function formatRecipeDoctorReport(result: RecipeDoctorResult): string;
 /**
  * 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.