@lhi/n8m 0.2.1 → 0.2.3

package/README.md

@@ -142,23 +142,120 @@ n8m doc
 
 ### `n8m test` — Validate and auto-repair a workflow
 
-Deploys a workflow ephemerally to your instance, validates it, and purges it
-when done. If validation fails, the repair loop kicks in automatically.
+Validates a workflow against your n8n instance. If it fails, the AI repair loop
+kicks in — analyzing the error, applying fixes, and retrying automatically.
 
 ```bash
-# Test a local file
+# Test a local file or remote workflow (browse to select)
 n8m test ./workflows/my-flow.json
-
-# Browse and pick from local files + instance workflows
 n8m test
+
+# Generate 3 diverse AI test scenarios (happy path, edge case, error)
+n8m test --ai-scenarios
+
+# Use a specific fixture file for offline testing
+n8m test --fixture .n8m/fixtures/abc123.json
+n8m test -f ./my-fixture.json
 ```
 
 - Resolves and deploys sub-workflow dependencies automatically
-- Patches node IDs after ephemeral deployment
+- After a passing live test, prompts to **save a fixture** for future offline runs
+- When a fixture exists for a workflow, prompts to **run offline** (no n8n calls)
 - After a passing test, prompts to deploy or save the validated/repaired version
 - **Auto-documents**: Generates or updates the project `README.md` upon saving.
 - All temporary assets are deleted on exit
 
+#### Offline testing with fixtures
+
+n8m can capture real execution data from n8n and replay it offline — no live
+instance, credentials, or external API calls needed.
+
+**First run — capture a fixture:**
+```bash
+n8m test                          # runs live against your n8n instance
+# → Save fixture for future offline runs? [Y/n]  ← answer Y
+# → .n8m/fixtures/<workflowId>.json created
+```
+
+**Subsequent runs — replay offline:**
+```bash
+n8m test
+# → Fixture found from Mar 4, 2026, 10:30 AM. Run offline? [Y/n]
+```
+
+The offline mode uses your real node-by-node execution data, so the AI evaluator
+works with actual production outputs rather than mocked data. The AI healing loop
+still runs — if the captured execution shows an error, n8m will try to fix it and
+evaluate the fix against the real fixture data.
+
+---
+
+### `n8m fixture` — Manage test fixtures
+
+Two ways to create a fixture:
+
+```bash
+# Pull real execution data from n8n (no test run required)
+n8m fixture capture <workflowId>
+
+# Scaffold an empty template to fill in by hand
+n8m fixture init <workflowId>
+```
+
+**`capture`** connects to your n8n instance, fetches the 25 most recent
+executions for the workflow, and presents an interactive menu to pick which one
+to save as a fixture — no tests run. Use this when you have a workflow that
+already ran successfully in n8n and you want to lock in that execution data for
+offline testing going forward.
+
+```bash
+n8m fixture capture abc123
+# → Fetching executions for workflow abc123...
+# → ? Select an execution to capture:
+# →   #177916  success  3/4/2026, 10:48:47 AM
+# →   #177914  success  3/4/2026, 10:48:23 AM
+# → ❯ #177913  error    3/4/2026, 10:47:59 AM
+# → Selected execution 177913
+# → Fixture saved to .n8m/fixtures/abc123.json
+# →   Workflow: My Workflow
+# →   Execution: error · 5 node(s) captured
+```
+
+**`init`** creates an empty template when you want to define the fixture data
+yourself, without needing a live execution first.
+
+```json
+{
+  "$schema": "../../node_modules/n8m/dist/fixture-schema.json",
+  "version": "1.0",
+  "workflowId": "abc123",
+  "workflowName": "My Workflow",
+  "workflow": { "name": "My Workflow", "nodes": [], "connections": {} },
+  "execution": {
+    "status": "success",
+    "data": {
+      "resultData": {
+        "error": null,
+        "runData": {
+          "Your Node Name": [{ "json": { "key": "value" } }]
+        }
+      }
+    }
+  }
+}
+```
+
+Fill in `execution.data.resultData.runData` with the actual output of each node
+(keyed by exact node name). Then test against it:
+
+```bash
+n8m test --fixture .n8m/fixtures/abc123.json
+```
+
+Fixture files are project-local (`.n8m/fixtures/`) and should be committed to
+your repo so your team can run the same offline tests. Add the `$schema` field to
+get autocomplete and validation in any editor that supports JSON Schema.
+
 ---
 
 ### `n8m deploy` — Push a workflow to n8n
@@ -306,5 +403,7 @@ npm run dev
 - [x] AI-driven test scenario generation (`--ai-scenarios`)
 - [x] Static node type reference & fallback mechanism
 - [x] Multi-workflow project generation support
+- [x] Fixture record & replay — offline testing with real execution data
+- [x] Hand-crafted fixture scaffolding (`n8m fixture init`) with JSON Schema
 - [ ] Native n8n canvas integration
 - [ ] Multi-agent collaboration on a single goal

package/dist/agentic/graph.d.ts

@@ -15,6 +15,7 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
     collaborationLog: string[];
     userFeedback: string;
     testScenarios: any[];
+    maxRevisions: number;
 }, {
     userGoal?: string | undefined;
     spec?: any;
@@ -31,6 +32,7 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
     collaborationLog?: string[] | undefined;
     userFeedback?: string | undefined;
     testScenarios?: any[] | undefined;
+    maxRevisions?: number | undefined;
 }, "__start__" | "architect" | "engineer" | "reviewer" | "supervisor" | "qa", {
     userGoal: {
         (): import("@langchain/langgraph").LastValue<string>;
@@ -91,6 +93,7 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
         (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
         Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
     };
+    maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
 }, {
     userGoal: {
         (): import("@langchain/langgraph").LastValue<string>;
@@ -151,8 +154,14 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
         (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
         Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
     };
+    maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
 }, import("@langchain/langgraph").StateDefinition, {
     architect: {
+        spec?: undefined;
+        strategies?: undefined;
+        needsClarification?: undefined;
+        collaborationLog?: undefined;
+    } | {
         spec: import("../services/ai.service.js").WorkflowSpec;
         strategies: {
             strategyName: string;
@@ -171,13 +180,28 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
         collaborationLog: string[];
     };
     engineer: {
+        revisionCount: number;
+        validationStatus: "failed";
+        validationErrors: string[];
+        workflowJson?: undefined;
+        candidates?: undefined;
+    } | {
         workflowJson: any;
+        revisionCount: number;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
         candidates?: undefined;
     } | {
+        revisionCount?: undefined;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
         workflowJson?: undefined;
         candidates?: undefined;
     } | {
         candidates: any[];
+        revisionCount?: undefined;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
         workflowJson?: undefined;
     };
     reviewer: import("@langchain/langgraph").UpdateType<{
@@ -240,6 +264,7 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
             (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
             Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
         };
+        maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
     }>;
     supervisor: {
         workflowJson?: undefined;
@@ -308,6 +333,7 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
             (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
             Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
         };
+        maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
     }>;
 }, unknown, unknown>;
 /**
@@ -376,6 +402,7 @@ export declare const runAgenticWorkflow: (goal: string, initialState?: Partial<t
         (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
         Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
     };
+    maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
 }>>;
 /**
  * Run the Agentic Workflow with Streaming
@@ -384,6 +411,11 @@ export declare const runAgenticWorkflow: (goal: string, initialState?: Partial<t
  */
 export declare const runAgenticWorkflowStream: (goal: string, threadId?: string) => Promise<import("@langchain/core/utils/stream").IterableReadableStream<{
     architect?: {
+        spec?: undefined;
+        strategies?: undefined;
+        needsClarification?: undefined;
+        collaborationLog?: undefined;
+    } | {
         spec: import("../services/ai.service.js").WorkflowSpec;
         strategies: {
             strategyName: string;
@@ -402,13 +434,28 @@ export declare const runAgenticWorkflowStream: (goal: string, threadId?: string)
         collaborationLog: string[];
     } | undefined;
     engineer?: {
+        revisionCount: number;
+        validationStatus: "failed";
+        validationErrors: string[];
+        workflowJson?: undefined;
+        candidates?: undefined;
+    } | {
         workflowJson: any;
+        revisionCount: number;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
         candidates?: undefined;
     } | {
+        revisionCount?: undefined;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
         workflowJson?: undefined;
         candidates?: undefined;
     } | {
         candidates: any[];
+        revisionCount?: undefined;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
         workflowJson?: undefined;
     } | undefined;
     reviewer?: import("@langchain/langgraph").UpdateType<{
@@ -471,6 +518,7 @@ export declare const runAgenticWorkflowStream: (goal: string, threadId?: string)
             (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
             Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
         };
+        maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
     }> | undefined;
     supervisor?: {
         workflowJson?: undefined;
@@ -539,6 +587,7 @@ export declare const runAgenticWorkflowStream: (goal: string, threadId?: string)
             (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
             Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
         };
+        maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
     }> | undefined;
 }>>;
 /**
@@ -604,4 +653,5 @@ export declare const resumeAgenticWorkflow: (threadId: string, input?: any) => P
         (annotation: import("@langchain/langgraph").SingleReducer<any[], any[]>): import("@langchain/langgraph").BinaryOperatorAggregate<any[], any[]>;
         Root: <S extends import("@langchain/langgraph").StateDefinition>(sd: S) => import("@langchain/langgraph").AnnotationRoot<S>;
     };
+    maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
 }>>;

package/dist/agentic/graph.js

@@ -1,4 +1,4 @@
-import { StateGraph, START, END, Send } from "@langchain/langgraph";
+import { StateGraph, START, END } from "@langchain/langgraph";
 import { checkpointer } from "./checkpointer.js";
 import { architectNode } from "./nodes/architect.js";
 import { engineerNode } from "./nodes/engineer.js";
@@ -15,14 +15,8 @@ const workflow = new StateGraph(TeamState)
     .addNode("qa", qaNode)
     // Edges
     .addEdge(START, "architect")
-    // Parallel Fan-Out: Architect -> Multiple Engineers (via Send)
-    .addConditionalEdges("architect", (state) => {
-    if (state.strategies && state.strategies.length > 0) {
-        return state.strategies.map(s => new Send("engineer", { spec: s }));
-    }
-    // Fallback for linear path
-    return "engineer";
-}, ["engineer"]) // We must declare valid destination nodes for visualization/compilation
+    // Architect -> Engineer (spec is chosen interactively in create.ts before resuming)
+    .addEdge("architect", "engineer")
     // Fan-In: Engineer -> Supervisor (Wait for all to finish) or route to Reviewer (if fixing)
     .addConditionalEdges("engineer", (state) => {
     // If we have errors, we are in "Repair Mode" -> Skip Supervisor (which only handles fresh candidates)
@@ -62,7 +56,6 @@ export const graph = workflow.compile({
  * @returns The final state of the graph
  */
 export const runAgenticWorkflow = async (goal, initialState = {}, threadId = "default_session") => {
-    console.log(`🚀 Starting Agentic Workflow for goal: "${goal}" (Thread: ${threadId})`);
     const result = await graph.invoke({
         userGoal: goal,
         messages: [],
@@ -93,7 +86,6 @@ export const runAgenticWorkflowStream = async (goal, threadId = "default_session
  * Resume the Agentic Workflow from an interrupted state
  */
 export const resumeAgenticWorkflow = async (threadId, input) => {
-    console.log(`▶️ Resuming Agentic Workflow (Thread: ${threadId})`);
     return await graph.invoke(input, {
         configurable: { thread_id: threadId }
     });

package/dist/agentic/nodes/architect.d.ts

@@ -1,5 +1,10 @@
 import { TeamState } from "../state.js";
 export declare const architectNode: (state: typeof TeamState.State) => Promise<{
+    spec?: undefined;
+    strategies?: undefined;
+    needsClarification?: undefined;
+    collaborationLog?: undefined;
+} | {
     spec: import("../../services/ai.service.js").WorkflowSpec;
     strategies: {
         strategyName: string;

package/dist/agentic/nodes/architect.js

@@ -4,27 +4,14 @@ export const architectNode = async (state) => {
     if (!state.userGoal) {
         throw new Error("User goal is missing from state.");
     }
-    // Pass-through if we already have a workflow (Repairs/Testing mode)
-    // BUT if we have a goal that implies modification, we should probably still generate a spec?
-    // For now, let's allow spec generation even if workflowJson exists, so the Engineer can use the spec + old workflow to make new one.
-    // The logic in Architect assumes "generateSpec" creates a NEW spec from scratch.
-    // We might need a "modifySpec" or just rely on the Engineer to interpret the goal + existing workflow.
-    // If we skip the architect, we go straight to Engineer?
-    // The graph edges are: START -> architect -> engineer.
-    // If we return empty here, 'spec' is undefined in state.
-    // Engineer checks state.spec.
-    // If we want to support modification, the Architect should probably analyze the request vs the current workflow.
-    // However, for the first MVP, if we return empty, the Engineer will run.
-    // Does Engineer handle "no spec" but "has workflowJson" + "userGoal"?
-    // Let's assume we want the Architect to generate a plan (Spec) for the modification.
-    // So we REMOVE this early return, or condition it on "isRepair" vs "isModify".
-    // Since we don't have an explicit flag, we can just let it run.
-    // The prompt for generateSpec might need to know about the existing workflow?
-    // Currently generateSpec only sees the goal.
-    // Let's comment it out for now to allow Architect to run.
-    // if (state.workflowJson) {
-    //     return {};
-    // }
+    // Validation / repair mode: an existing workflow was supplied.
+    // Skip spec generation entirely — the engineer and reviewer operate directly
+    // on the existing workflowJson.  Generating a brand-new spec here causes the
+    // parallel engineers (via Send) to rebuild the workflow from scratch, which
+    // produces very large JSON that is error-prone and throws away the user's work.
+    if (state.workflowJson) {
+        return {};
+    }
     try {
         const spec = await aiService.generateSpec(state.userGoal);
         // Check if the spec requires clarification
@@ -47,7 +34,6 @@ export const architectNode = async (state) => {
             },
         ];
         const logEntry = `Architect: Generated 2 strategies — "${strategies[0].suggestedName}" (primary) and "${strategies[1].suggestedName}" (alternative)`;
-        console.log(`[Architect] ${logEntry}`);
         return {
             spec,
             strategies,

package/dist/agentic/nodes/engineer.d.ts

@@ -1,11 +1,26 @@
 import { TeamState } from "../state.js";
 export declare const engineerNode: (state: typeof TeamState.State) => Promise<{
+    revisionCount: number;
+    validationStatus: "failed";
+    validationErrors: string[];
+    workflowJson?: undefined;
+    candidates?: undefined;
+} | {
     workflowJson: any;
+    revisionCount: number;
+    validationStatus?: undefined;
+    validationErrors?: undefined;
     candidates?: undefined;
 } | {
+    revisionCount?: undefined;
+    validationStatus?: undefined;
+    validationErrors?: undefined;
     workflowJson?: undefined;
     candidates?: undefined;
 } | {
     candidates: any[];
+    revisionCount?: undefined;
+    validationStatus?: undefined;
+    validationErrors?: undefined;
     workflowJson?: undefined;
 }>;

package/dist/agentic/nodes/engineer.js

@@ -1,6 +1,7 @@
 import { AIService } from "../../services/ai.service.js";
 import { NodeDefinitionsService } from "../../services/node-definitions.service.js";
 import { jsonrepair } from "jsonrepair";
+import { theme } from "../../utils/theme.js";
 export const engineerNode = async (state) => {
     const aiService = AIService.getInstance();
     // RAG: Load and Search Node Definitions
@@ -14,12 +15,31 @@ export const engineerNode = async (state) => {
     const ragContext = (relevantDefs.length > 0 || staticRef)
         ? `\n\n[N8N NODE REFERENCE GUIDE]\n${staticRef}\n\n[AVAILABLE NODE SCHEMAS - USE THESE EXACT PARAMETERS]\n${nodeService.formatForLLM(relevantDefs)}`
         : "";
-    if (relevantDefs.length > 0) {
-        console.log(`[Engineer] RAG: Found ${relevantDefs.length} relevant node schemas.`);
-    }
     // Self-Correction Loop Check
     if (state.validationErrors && state.validationErrors.length > 0) {
-        console.log("🔧 Engineer is fixing the workflow based on QA feedback...");
+        const currentRevision = (state.revisionCount || 0) + 1;
+        const maxRevisions = state.maxRevisions || 3;
+        if (currentRevision > maxRevisions) {
+            console.log(theme.fail(`Max self-healing revisions (${maxRevisions}) reached. Manual intervention required.`));
+            return {
+                revisionCount: currentRevision,
+                validationStatus: 'failed',
+                validationErrors: [
+                    `Self-healing limit (${maxRevisions} revisions) exceeded. Remaining issues:`,
+                    ...state.validationErrors,
+                ],
+            };
+        }
+        const errCount = state.validationErrors.length;
+        console.log(theme.agent(`Repairing workflow — revision ${currentRevision}/${maxRevisions} (${errCount} issue${errCount === 1 ? '' : 's'})...`));
+        const MAX_SHOWN = 4;
+        state.validationErrors.slice(0, MAX_SHOWN).forEach(e => {
+            const truncated = e.length > 110 ? e.substring(0, 110) + '…' : e;
+            console.log(theme.muted(`  ↳ ${truncated}`));
+        });
+        if (errCount > MAX_SHOWN) {
+            console.log(theme.muted(`  ↳ +${errCount - MAX_SHOWN} more`));
+        }
         try {
             // We pass the entire list of errors as context
             const errorContext = state.validationErrors.join('\n');
@@ -28,6 +48,7 @@ export const engineerNode = async (state) => {
             false, state.availableNodeTypes || []);
             return {
                 workflowJson: fixedWorkflow,
+                revisionCount: currentRevision,
                 // validationErrors will be overwritten by next QA run
             };
         }

package/dist/agentic/nodes/qa.d.ts

@@ -1,5 +1,6 @@
 import { TeamState } from "../state.js";
 export declare const qaNode: (state: typeof TeamState.State) => Promise<{
+    workflowJson?: any;
     validationStatus: string;
     validationErrors: string[];
 }>;