@lhi/n8m 0.2.4 → 0.3.1

package/README.md

@@ -198,15 +198,18 @@ Two ways to create a fixture:
 # Pull real execution data from n8n (no test run required)
 n8m fixture capture <workflowId>
 
+# Browse local files + remote instance interactively
+n8m fixture capture
+
 # 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.
+**`capture`** connects to your n8n instance, fetches the most recent executions
+for the workflow, and presents an interactive menu to pick which one to save.
+You'll be prompted for a fixture name (e.g. `happy-path`, `missing-field`) and
+expected outcome (`pass` or `fail`). Fixtures are saved to
+`.n8m/fixtures/<workflowId>/<name>.json`.
 
 ```bash
 n8m fixture capture abc123
@@ -215,12 +218,21 @@ n8m fixture capture abc123
 # →   #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
+# → Name this fixture (e.g. happy-path, missing-field, bad-auth): error-case
+# → Expected test outcome: fail
+# → Fixture saved to .n8m/fixtures/abc123/error-case.json
 # →   Workflow: My Workflow
 # →   Execution: error · 5 node(s) captured
 ```
 
+Multiple named fixtures per workflow let you test different scenarios (happy
+path, edge cases, error handling) with one command:
+
+```bash
+n8m test --fixture .n8m/fixtures/abc123           # run ALL fixtures for a workflow
+n8m test --fixture .n8m/fixtures/abc123/error-case.json  # run one specific fixture
+```
+
 **`init`** creates an empty template when you want to define the fixture data
 yourself, without needing a live execution first.
 
@@ -230,6 +242,8 @@ yourself, without needing a live execution first.
   "version": "1.0",
   "workflowId": "abc123",
   "workflowName": "My Workflow",
+  "description": "happy-path",
+  "expectedOutcome": "pass",
   "workflow": { "name": "My Workflow", "nodes": [], "connections": {} },
   "execution": {
     "status": "success",
@@ -249,7 +263,7 @@ 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
+n8m test --fixture .n8m/fixtures/abc123/happy-path.json
 ```
 
 Fixture files are project-local (`.n8m/fixtures/`) and should be committed to
@@ -271,6 +285,117 @@ n8m deploy ./workflows/my-flow.json --activate
 
 ---
 
+### `n8m learn` — Build the pattern library
+
+Extract reusable engineering knowledge from validated workflows and store it so
+the AI engineer applies the same proven techniques in future generations.
+
+```bash
+# Interactive: pick a workflow from ./workflows/
+n8m learn
+
+# Learn from a specific workflow
+n8m learn ./workflows/my-flow/workflow.json
+
+# Batch-generate patterns for every workflow in the directory
+n8m learn --all
+
+# Import patterns from a GitHub archive (awesome-n8n style)
+n8m learn --github owner/repo
+n8m learn --github owner/repo@main --github-path patterns/google
+n8m learn --github owner/repo --token ghp_xxx   # or set GITHUB_TOKEN env var
+```
+
+**How it works:**
+
+- **Local mode**: The AI reads a validated workflow JSON, identifies the
+  techniques it demonstrates, extracts critical rules (including gotchas to
+  avoid), and writes a `.md` pattern file to `.n8m/patterns/`.
+- **GitHub mode**: Fetches `.md` pattern files from any public GitHub repo via
+  the GitHub API. Shows a checkbox menu so you choose exactly which patterns to
+  import. Recurses into subdirectories automatically.
+
+Patterns are Markdown files with a `<!-- keywords: ... -->` comment. When you
+run `n8m create`, the engineer searches all pattern files and injects any that
+match the workflow's goal into the prompt — teaching it to reproduce proven
+approaches exactly.
+
+```
+.n8m/patterns/          ← your project-local library (user patterns)
+docs/patterns/          ← built-in patterns shipped with n8m
+```
+
+User patterns in `.n8m/patterns/` take priority over built-in patterns. A
+pattern file with the same filename overrides the built-in version, so you can
+customize any default.
+
+**Contributing default patterns** (for n8m maintainers):
+
+```bash
+# Generate docs/patterns/ from every workflow in ./workflows/
+npm run generate-patterns
+
+# Overwrite any already-existing pattern files
+npm run generate-patterns -- --overwrite
+
+# Preview what would be written without touching the filesystem
+npm run generate-patterns -- --dry-run
+```
+
+The script scans `workflows/` recursively, calls the AI on each `workflow.json`,
+and writes the result to `docs/patterns/<slug>.md`. Patterns in `docs/patterns/`
+are included in the npm package and available to all users automatically.
+
+**Pattern file format:**
+
+```markdown
+<!-- keywords: bigquery, google bigquery, sql, merge, http request -->
+
+# Pattern: BigQuery Operations via HTTP Request
+
+## Critical Rules
+- NEVER use n8n-nodes-base.googleBigQuery — it returns no output for DDL/DML.
+  Always use n8n-nodes-base.httpRequest with the BigQuery REST API.
+
+## DDL / DML Queries
+...
+```
+
+---
+
+### `n8m mcp` — Launch the MCP server
+
+Expose `n8m`'s agentic capabilities as tools to any
+[Model Context Protocol](https://modelcontextprotocol.io/) client (Claude
+Desktop, Cursor, etc.).
+
+```bash
+n8m mcp
+# → Starting n8m MCP Server...
+```
+
+The server runs over stdio and registers two tools:
+
+| Tool | Description |
+|---|---|
+| `create_workflow` | Generate an n8n workflow from a natural-language goal |
+| `test_workflow` | Deploy a workflow ephemerally to n8n and validate it |
+
+Add it to your MCP client config (e.g. Claude Desktop's `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "n8m": {
+      "command": "npx",
+      "args": ["n8m", "mcp"]
+    }
+  }
+}
+```
+
+---
+
 ### `n8m resume` — Resume a paused session
 
 The agent can pause mid-run for human review (HITL). Resume it with its thread
@@ -330,8 +455,8 @@ n8m config
 Developer → n8m create "..."
                │
                ▼
-        ┌─────────────┐
-        │  Architect  │  Designs the workflow blueprint
+        ┌─────────────┐      .n8m/patterns/    docs/patterns/
+        │  Architect  │  ◄── RAG: node defs + matched patterns
         └──────┬──────┘
                │
                ▼
@@ -345,10 +470,18 @@ Developer → n8m create "..."
         └──────┬──────┘       └─────────────┘
                │ passed
                ▼
-                ▼
         ./workflows/<slug>/
            ├── workflow.json
            └── README.md (with Mermaid diagram)
+
+
+Developer → n8m learn <workflow.json>
+               │
+               ▼
+          AI analyzes validated workflow
+               │
+               ▼
+        .n8m/patterns/<slug>.md  ← feeds back into Engineer on next create
 ```
 
 - **Local first**: credentials and workflow files live on your machine
@@ -358,6 +491,8 @@ Developer → n8m create "..."
 - **HITL pauses**: the agent stops for your review before committing
 - **Bring your own AI**: works with OpenAI, Claude, Gemini, Ollama, or any
   OpenAI-compatible API
+- **Self-improving**: every validated workflow you `learn` from strengthens
+  future generations
 
 > **For developers**: See the [Developer Guide](docs/DEVELOPER_GUIDE.md) for a
 > deep-dive into the agentic graph internals, RAG implementation, how to add new
@@ -391,13 +526,14 @@ npm run dev
 
 ## Roadmap
 
+### Shipped
+
 - [x] Agentic graph (Architect → Engineer → QA)
 - [x] SQLite session persistence
 - [x] HITL interrupts and resume
 - [x] Sub-workflow dependency resolution in tests
 - [x] Open source — no account required
-- [x] Multi-provider AI support (OpenAI, Claude, Gemini, Ollama, any
-      OpenAI-compatible API)
+- [x] Multi-provider AI support (OpenAI, Claude, Gemini, Ollama, any OpenAI-compatible API)
 - [x] Automatic documentation generation (Mermaid + AI Summary)
 - [x] Project-based folder organization
 - [x] AI-driven test scenario generation (`--ai-scenarios`)
@@ -405,5 +541,30 @@ npm run dev
 - [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
+- [x] Pattern library — extract & reuse knowledge from validated workflows (`n8m learn`)
+- [x] GitHub pattern archive import (`n8m learn --github owner/repo`)
+- [x] MCP server — expose n8m as tools for Claude Desktop and other MCP clients
+
+### Near-term
+
+- [ ] **`n8m watch`** — file-system watcher that auto-deploys on save with live reload in the n8n editor
+- [ ] **`n8m diff`** — human-readable structural diff between two versions of a workflow (nodes added/removed/changed)
+- [ ] **`n8m rollback`** — restore a workflow to a previous git-tracked version with a single command
+- [ ] **Credential awareness** — AI consults available credential types on the target instance so it stops generating nodes it can't authenticate
+- [ ] **Parallel test runs** — fire multiple fixture payloads concurrently and report aggregate pass/fail
+
+### Medium-term
+
+- [ ] **`n8m debug`** — attach to a running execution and stream node-by-node output to the terminal in real time
+- [ ] **`n8m chat`** — interactive REPL where every message applies an incremental AI edit and immediately re-tests
+- [ ] **Workflow linter** — static analysis before deploy: dead branches, missing error handlers, unconnected nodes, credential gaps
+- [ ] **`n8m learn --from-executions`** — scrape recent successful executions and distil reusable patterns into `.n8m/patterns/` automatically
+- [ ] **Multi-instance deploy** — deploy the same workflow to staging and production in one command with environment-variable substitution
+
+### Longer-term
+
+- [ ] **Visual diff** — `n8m diff --ui` opens a side-by-side workflow comparison in the n8n canvas
+- [ ] **Workflow marketplace** — `n8m publish` / `n8m install <slug>` to share and consume community patterns with version pinning
+- [ ] **Execution replay** — record a live execution and automatically promote it to a fixture, closing the capture loop entirely
+- [ ] **Agent memory across sessions** — the engineer remembers which node patterns worked well for a given integration and prefers them on future builds
+- [ ] **LangGraph trace export** — export the full agentic reasoning trace (Architect → Engineer → Reviewer → QA) as a structured log for debugging and auditing

package/dist/agentic/graph.d.ts

@@ -157,10 +157,10 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
     maxRevisions: import("@langchain/langgraph").BinaryOperatorAggregate<number, number>;
 }, import("@langchain/langgraph").StateDefinition, {
     architect: {
-        spec?: undefined;
+        spec: any;
+        collaborationLog: string[];
         strategies?: undefined;
         needsClarification?: undefined;
-        collaborationLog?: undefined;
     } | {
         spec: import("../services/ai.service.js").WorkflowSpec;
         strategies: {
@@ -197,6 +197,12 @@ export declare const graph: import("@langchain/langgraph").CompiledStateGraph<{
         validationErrors?: undefined;
         workflowJson?: undefined;
         candidates?: undefined;
+    } | {
+        workflowJson: any;
+        revisionCount?: undefined;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
+        candidates?: undefined;
     } | {
         candidates: any[];
         revisionCount?: undefined;
@@ -411,10 +417,10 @@ 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;
+        spec: any;
+        collaborationLog: string[];
         strategies?: undefined;
         needsClarification?: undefined;
-        collaborationLog?: undefined;
     } | {
         spec: import("../services/ai.service.js").WorkflowSpec;
         strategies: {
@@ -451,6 +457,12 @@ export declare const runAgenticWorkflowStream: (goal: string, threadId?: string)
         validationErrors?: undefined;
         workflowJson?: undefined;
         candidates?: undefined;
+    } | {
+        workflowJson: any;
+        revisionCount?: undefined;
+        validationStatus?: undefined;
+        validationErrors?: undefined;
+        candidates?: undefined;
     } | {
         candidates: any[];
         revisionCount?: undefined;

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

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

package/dist/agentic/nodes/architect.js

@@ -10,7 +10,11 @@ export const architectNode = async (state) => {
     // 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 {};
+        const plan = await aiService.generateModificationPlan(state.userGoal, state.workflowJson);
+        return {
+            spec: plan,
+            collaborationLog: [`Architect: Modification plan — ${plan.description}`],
+        };
     }
     try {
         const spec = await aiService.generateSpec(state.userGoal);

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

@@ -17,6 +17,12 @@ export declare const engineerNode: (state: typeof TeamState.State) => Promise<{
     validationErrors?: undefined;
     workflowJson?: undefined;
     candidates?: undefined;
+} | {
+    workflowJson: any;
+    revisionCount?: undefined;
+    validationStatus?: undefined;
+    validationErrors?: undefined;
+    candidates?: undefined;
 } | {
     candidates: any[];
     revisionCount?: undefined;

package/dist/agentic/nodes/engineer.js

@@ -12,8 +12,13 @@ export const engineerNode = async (state) => {
     // Search for relevant nodes (limit 8 to save context)
     const relevantDefs = nodeService.search(queryText, 8);
     const staticRef = nodeService.getStaticReference();
-    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)}`
+    // Search pattern library for proven working examples
+    const matchedPatterns = nodeService.searchPatterns(queryText);
+    const patternsContext = matchedPatterns.length > 0
+        ? `\n\n[PROVEN WORKFLOW PATTERNS - FOLLOW THESE EXACTLY]\n${matchedPatterns.join('\n\n---\n\n')}`
+        : "";
+    const ragContext = (relevantDefs.length > 0 || staticRef || matchedPatterns.length > 0)
+        ? `\n\n[N8N NODE REFERENCE GUIDE]\n${staticRef}\n\n[AVAILABLE NODE SCHEMAS - USE THESE EXACT PARAMETERS]\n${nodeService.formatForLLM(relevantDefs)}${patternsContext}`
         : "";
     // Self-Correction Loop Check
     if (state.validationErrors && state.validationErrors.length > 0) {
@@ -57,9 +62,13 @@ export const engineerNode = async (state) => {
             throw error;
         }
     }
-    // Pass-through if workflow exists and no errors (Initial pass for existing workflow)
+    // Modification mode: existing workflow + spec from architect
     if (state.workflowJson) {
-        return {};
+        if (!state.spec) {
+            return {}; // No plan — nothing to do
+        }
+        const modifiedWorkflow = await aiService.applyModification(state.workflowJson, state.userGoal, state.spec, state.userFeedback, state.availableNodeTypes || []);
+        return { workflowJson: modifiedWorkflow };
     }
     // Standard Creation Flow
     // console.log("⚙️  Engineer is building the workflow...");
@@ -88,6 +97,31 @@ export const engineerNode = async (state) => {
           - Use "n8n-nodes-base.htmlExtract" for HTML/Cheerio extraction.
        6. Connections Structure: The "connections" object keys MUST BE THE SOURCE NODE NAME. The "node" field inside the connection array MUST BE THE TARGET NODE NAME.
        7. Connection Nesting: Ensure the correct n8n connection structure: "SourceNodeName": { "main": [ [ { "node": "TargetNodeName", "type": "main", "index": 0 } ] ] }.
+       8. Error Connections: In addition to "main", nodes support an "error" output that fires when a node fails. Use this for error handling and cleanup flows. Example:
+          "NodeThatMightFail": {
+            "main": [ [ { "node": "NextNode", "type": "main", "index": 0 } ] ],
+            "error": [ [ { "node": "CleanupOrErrorHandler", "type": "main", "index": 0 } ] ]
+          }
+          Any node that could fail mid-workflow AND where partial execution would leave side effects (e.g. temporary DB tables, uploaded files, open transactions) MUST have an error connection to a cleanup node.
+       9. HTTP Request Configuration: The method determines required fields.
+          - GET/DELETE: only "url" (and optional "sendQuery"/"sendHeaders") are needed — do NOT include "sendBody".
+          - POST/PUT/PATCH: MUST include "sendBody": true AND a "body" object:
+            { "method": "POST", "url": "...", "sendBody": true, "specifyBody": "json", "jsonBody": "={{ JSON.stringify($json) }}" }
+          - Authentication: use "authentication": "predefinedCredentialType" + "nodeCredentialType": "<CredentialTypeName>" for service credentials.
+          - Minimal config: only include fields relevant to the method. Do not add empty optional fields.
+       10. Resource/Operation Nodes (Slack, Google Sheets, Airtable, Gmail, etc.): The "resource" + "operation" pair together determine which parameters are required. Different operations need different fields:
+          - post/create operations typically need target identifiers (channel, spreadsheetId, etc.) and content fields.
+          - update/patch operations typically need a record ID (messageId, rowId, etc.) and the fields to update.
+          - get/list operations typically need filter/search parameters, not content fields.
+          Always set both "resource" and "operation" first, then configure only the fields that operation requires.
+       11. Credentials Format: Credential references must follow this structure:
+          "credentials": { "<credentialTypeName>": { "id": "CREDENTIAL_ID", "name": "Human Readable Name" } }
+          Use the exact credential type name that matches the node (e.g. "slackApi", "googleSheetsOAuth2Api", "googleBigQueryOAuth2Api").
+          For Google services, prefer service account credentials over OAuth2 when available:
+          - BigQuery: use "googleApi" (service account) instead of "googleBigQueryOAuth2Api"
+          - Google Sheets: use "googleSheetsServiceAccountApi" instead of "googleSheetsOAuth2Api"
+          - Google Drive: use "googleDriveServiceAccountApi" instead of "googleDriveOAuth2Api"
+          - Other Google nodes: check if a service account variant exists (typically named "<serviceName>ServiceAccountApi")
 
        Output a JSON object with this structure:
        {
@@ -114,7 +148,7 @@ export const engineerNode = async (state) => {
             throw new Error("AI generated invalid JSON for workflow from spec");
         }
         if (result.workflows && Array.isArray(result.workflows)) {
-            result.workflows = result.workflows.map((wf) => aiService.fixHallucinatedNodes(wf));
+            result.workflows = result.workflows.map((wf) => aiService.wireOrphanedErrorHandlers(aiService.fixHallucinatedNodes(wf)));
         }
         return {
             // Only push to candidates — the Supervisor sets workflowJson after fan-in.

package/dist/commands/create.js

@@ -10,6 +10,7 @@ import { promptMultiline } from '../utils/multilinePrompt.js';
 import { DocService } from '../services/doc.service.js';
 import { ConfigManager } from '../utils/config.js';
 import { N8nClient } from '../utils/n8nClient.js';
+import { AIService } from '../services/ai.service.js';
 export default class Create extends Command {
     static args = {
         description: Args.string({
@@ -147,6 +148,11 @@ export default class Create extends Command {
                             });
                         }
                         choices.push(new inquirer.Separator());
+                        choices.push({
+                            name: 'Discuss details with the Engineer',
+                            value: { type: 'chat' },
+                            short: 'Discuss',
+                        });
                         choices.push({
                             name: 'Add feedback before building',
                             value: { type: 'feedback' },
@@ -171,7 +177,38 @@ export default class Create extends Command {
                         }
                         let chosenSpec = choice.strategy ?? spec;
                         let stateUpdate = { spec: chosenSpec, userFeedback: undefined };
-                        if (choice.type === 'feedback') {
+                        if (choice.type === 'chat') {
+                            const aiService = AIService.getInstance();
+                            const chatHistory = [];
+                            let currentSpec = chosenSpec ?? strategies[0] ?? spec;
+                            this.log(theme.header('\nCHATTING WITH THE ENGINEER'));
+                            this.log(theme.muted(`  Plan: ${currentSpec?.suggestedName}`));
+                            this.log(theme.muted(`  Type your question or request. Enter "done" when ready to build.\n`));
+                            // eslint-disable-next-line no-constant-condition
+                            while (true) {
+                                const { message } = await inquirer.prompt([{
+                                        type: 'input',
+                                        name: 'message',
+                                        message: 'You:',
+                                    }]);
+                                const trimmed = message.trim();
+                                if (!trimmed || /^(done|build|approve|go|ok|yes)$/i.test(trimmed)) {
+                                    this.log(theme.agent(`Understood. Building "${currentSpec?.suggestedName}"...\n`));
+                                    break;
+                                }
+                                const { reply, updatedSpec } = await aiService.chatAboutSpec(currentSpec, chatHistory, trimmed);
+                                chatHistory.push({ role: 'user', content: trimmed });
+                                chatHistory.push({ role: 'assistant', content: reply });
+                                currentSpec = updatedSpec;
+                                this.log(`\n${theme.agent('Engineer:')} ${reply}\n`);
+                                if (updatedSpec.suggestedName !== (chosenSpec ?? spec)?.suggestedName) {
+                                    this.log(theme.muted(`  (Plan updated: ${updatedSpec.suggestedName})`));
+                                }
+                            }
+                            chosenSpec = currentSpec;
+                            stateUpdate = { spec: chosenSpec, userFeedback: undefined };
+                        }
+                        else if (choice.type === 'feedback') {
                             const { feedback } = await inquirer.prompt([{
                                     type: 'input',
                                     name: 'feedback',

package/dist/commands/deploy.d.ts

@@ -1,13 +1,14 @@
 import { Command } from '@oclif/core';
 export default class Deploy extends Command {
     static args: {
-        workflow: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        workflow: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
     };
     static description: string;
     static examples: string[];
     static flags: {
         instance: import("@oclif/core/interfaces").OptionFlag<string, import("@oclif/core/interfaces").CustomOptions>;
         activate: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        dir: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
 }