@lhi/n8m 0.3.2 → 1.0.0

package/dist/services/ai.service.js

@@ -6,6 +6,23 @@ import { fileURLToPath } from 'url';
 import { jsonrepair } from 'jsonrepair';
 import { NodeDefinitionsService } from './node-definitions.service.js';
 import { Spinner } from '../utils/spinner.js';
+/**
+ * Build a credential-awareness section for AI prompts.
+ * Returns an empty string when no credentials are provided so
+ * offline / unconfigured usage is completely unaffected.
+ */
+export function buildCredentialContext(credentials) {
+    if (!credentials || credentials.length === 0)
+        return '';
+    const list = credentials.map(c => `- "${c.name}" (type: ${c.type})`).join('\n');
+    return `
+
+AVAILABLE CREDENTIALS ON TARGET INSTANCE:
+${list}
+
+IMPORTANT: Only generate nodes whose credential type matches one of the types listed above.
+If the goal requires a service not in this list, use the HTTP Request node with generic authentication instead of a dedicated service node.`;
+}
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 export const PROVIDER_PRESETS = {
@@ -171,14 +188,16 @@ export class AIService {
     }
     getDefaultModel() { return this.model; }
     getDefaultProvider() { return this.defaultProvider; }
-    async generateSpec(goal) {
+    async generateSpec(goal, availableCredentials = []) {
         const nodeService = NodeDefinitionsService.getInstance();
         const staticRef = nodeService.getStaticReference();
+        const credentialContext = buildCredentialContext(availableCredentials);
         const prompt = `You are an n8n Solution Architect.
        Create a technical specification for an n8n workflow that fulfills the following goal: "${goal}".
-       
+
        [N8N NODE REFERENCE GUIDE]
        ${staticRef}
+       ${credentialContext}
 
        Your output must be a JSON object with this structure:
        {
@@ -189,7 +208,7 @@ export class AIService {
          ],
          "questions": ["Any clarification questions for the user"]
        }
-       
+
        Use ONLY standard n8n node types (e.g. n8n-nodes-base.httpRequest, n8n-nodes-base.slack).
        Output ONLY the JSON object. No commentary.`;
         const response = await this.generateContent(prompt);
@@ -251,15 +270,17 @@ Output ONLY valid JSON. No markdown.`;
             throw new Error(`invalid JSON: ${cleanJson}`);
         }
     }
-    async generateAlternativeSpec(goal, primarySpec) {
+    async generateAlternativeSpec(goal, primarySpec, availableCredentials = []) {
         const nodeService = NodeDefinitionsService.getInstance();
         const staticRef = nodeService.getStaticReference();
-        const prompt = `You are a Senior n8n Engineer. 
+        const credentialContext = buildCredentialContext(availableCredentials);
+        const prompt = `You are a Senior n8n Engineer.
        Given the goal: "${goal}" and a primary strategy: ${JSON.stringify(primarySpec)},
        design an ALTERNATIVE strategy (different approach or set of nodes) that achieves the same goal.
-       
+
        [N8N NODE REFERENCE GUIDE]
        ${staticRef}
+       ${credentialContext}
 
        Your output must be a JSON object with the same WorkflowSpec structure.
        Output ONLY the JSON object. No commentary.`;

package/dist/services/git.service.d.ts

@@ -0,0 +1,52 @@
+export interface GitCommit {
+    hash: string;
+    message: string;
+}
+export interface WorkflowDiff {
+    added: string[];
+    removed: string[];
+    unchanged: number;
+}
+/**
+ * Parse the output of `git log --oneline` into structured commits.
+ * Pure function — safe to unit test without I/O.
+ */
+export declare function parseGitLog(raw: string): GitCommit[];
+/**
+ * Format a commit for display in an interactive select list.
+ * Shows the 7-char short hash followed by the commit message.
+ */
+export declare function formatCommitChoice(commit: GitCommit): string;
+/**
+ * Diff two workflow JSON objects by node names.
+ * Returns which node names were added, removed, and how many are unchanged.
+ */
+export declare function diffWorkflowNodes(oldJson: any, newJson: any): WorkflowDiff;
+export declare class GitService {
+    private cwd;
+    constructor(cwd?: string);
+    /**
+     * Parse the raw stdout of `git log --oneline` into GitCommit objects.
+     * Static so it can be called without instantiation in tests.
+     */
+    static parseGitLog(raw: string): GitCommit[];
+    /** Returns true if `cwd` is inside a git repository. */
+    isGitRepo(): Promise<boolean>;
+    /** Returns the absolute path to the repository root. */
+    getRepoRoot(): Promise<string>;
+    /**
+     * Converts an absolute path to a path relative to the repo root.
+     * Returns null if the path is outside the repository.
+     */
+    getRelativePath(absolutePath: string): Promise<string | null>;
+    /**
+     * Returns git commit history for a file (newest first).
+     * Returns [] if the file is untracked or has no commits.
+     */
+    getFileHistory(relativePath: string): Promise<GitCommit[]>;
+    /**
+     * Retrieves the content of a file at a specific git commit.
+     * Throws if the hash is invalid or the file did not exist at that commit.
+     */
+    getFileAtCommit(hash: string, relativePath: string): Promise<string>;
+}

package/dist/services/git.service.js

@@ -0,0 +1,110 @@
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import path from 'node:path';
+const execFileAsync = promisify(execFile);
+/**
+ * Parse the output of `git log --oneline` into structured commits.
+ * Pure function — safe to unit test without I/O.
+ */
+export function parseGitLog(raw) {
+    return GitService.parseGitLog(raw);
+}
+/**
+ * Format a commit for display in an interactive select list.
+ * Shows the 7-char short hash followed by the commit message.
+ */
+export function formatCommitChoice(commit) {
+    return `${commit.hash.slice(0, 7)}  ${commit.message}`;
+}
+/**
+ * Diff two workflow JSON objects by node names.
+ * Returns which node names were added, removed, and how many are unchanged.
+ */
+export function diffWorkflowNodes(oldJson, newJson) {
+    const oldNodes = (oldJson?.nodes ?? []).map((n) => n.name);
+    const newNodes = (newJson?.nodes ?? []).map((n) => n.name);
+    const oldSet = new Set(oldNodes);
+    const newSet = new Set(newNodes);
+    const added = newNodes.filter(n => !oldSet.has(n));
+    const removed = oldNodes.filter(n => !newSet.has(n));
+    const unchanged = newNodes.filter(n => oldSet.has(n)).length;
+    return { added, removed, unchanged };
+}
+export class GitService {
+    cwd;
+    constructor(cwd = process.cwd()) {
+        this.cwd = cwd;
+    }
+    /**
+     * Parse the raw stdout of `git log --oneline` into GitCommit objects.
+     * Static so it can be called without instantiation in tests.
+     */
+    static parseGitLog(raw) {
+        return raw
+            .split('\n')
+            .map(line => line.trim())
+            .filter(line => line.length > 0)
+            .flatMap(line => {
+            const spaceIdx = line.indexOf(' ');
+            if (spaceIdx === -1)
+                return [];
+            const hash = line.slice(0, spaceIdx).trim();
+            const message = line.slice(spaceIdx + 1).trim();
+            if (!hash || !message)
+                return [];
+            return [{ hash, message }];
+        });
+    }
+    /** Returns true if `cwd` is inside a git repository. */
+    async isGitRepo() {
+        try {
+            await execFileAsync('git', ['rev-parse', '--git-dir'], { cwd: this.cwd });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /** Returns the absolute path to the repository root. */
+    async getRepoRoot() {
+        const { stdout } = await execFileAsync('git', ['rev-parse', '--show-toplevel'], { cwd: this.cwd });
+        return stdout.trim();
+    }
+    /**
+     * Converts an absolute path to a path relative to the repo root.
+     * Returns null if the path is outside the repository.
+     */
+    async getRelativePath(absolutePath) {
+        try {
+            const root = await this.getRepoRoot();
+            const rel = path.relative(root, absolutePath);
+            if (rel.startsWith('..'))
+                return null;
+            return rel;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Returns git commit history for a file (newest first).
+     * Returns [] if the file is untracked or has no commits.
+     */
+    async getFileHistory(relativePath) {
+        try {
+            const { stdout } = await execFileAsync('git', ['log', '--oneline', '--', relativePath], { cwd: this.cwd });
+            return GitService.parseGitLog(stdout);
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Retrieves the content of a file at a specific git commit.
+     * Throws if the hash is invalid or the file did not exist at that commit.
+     */
+    async getFileAtCommit(hash, relativePath) {
+        const { stdout } = await execFileAsync('git', ['show', `${hash}:${relativePath}`], { cwd: this.cwd });
+        return stdout;
+    }
+}

package/dist/services/mcp.service.d.ts

@@ -5,5 +5,6 @@ export declare class MCPService {
     private server;
     constructor();
     private setupTools;
+    private getN8nClient;
     start(): Promise<void>;
 }

package/dist/services/mcp.service.js

@@ -3,6 +3,9 @@ import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js"
 import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import { runAgenticWorkflow } from "../agentic/graph.js";
 import { theme } from "../utils/theme.js";
+import { N8nClient } from "../utils/n8nClient.js";
+import { ConfigManager } from "../utils/config.js";
+import { DocService } from "../services/doc.service.js";
 /**
  * MCP Service for exposing n8m agentic capabilities as tools.
  */
@@ -55,6 +58,93 @@ export class MCPService {
                             required: ["workflowJson", "goal"],
                         },
                     },
+                    {
+                        name: "modify_workflow",
+                        description: "Modify an existing n8n workflow JSON based on natural language instructions using the AI agent.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                workflowJson: {
+                                    type: "object",
+                                    description: "The existing workflow JSON to modify",
+                                },
+                                instruction: {
+                                    type: "string",
+                                    description: "Natural language description of the modifications to apply",
+                                },
+                            },
+                            required: ["workflowJson", "instruction"],
+                        },
+                    },
+                    {
+                        name: "deploy_workflow",
+                        description: "Deploy a workflow JSON to the configured n8n instance. Creates a new workflow or updates an existing one if the workflow has an ID.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                workflowJson: {
+                                    type: "object",
+                                    description: "The workflow JSON to deploy",
+                                },
+                                forceCreate: {
+                                    type: "boolean",
+                                    description: "Always create as a new workflow, ignoring any existing ID (default: false)",
+                                },
+                            },
+                            required: ["workflowJson"],
+                        },
+                    },
+                    {
+                        name: "get_workflow",
+                        description: "Fetch a workflow from the configured n8n instance by its ID.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                workflowId: {
+                                    type: "string",
+                                    description: "The n8n workflow ID to fetch",
+                                },
+                            },
+                            required: ["workflowId"],
+                        },
+                    },
+                    {
+                        name: "list_workflows",
+                        description: "List all workflows on the configured n8n instance.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {},
+                            required: [],
+                        },
+                    },
+                    {
+                        name: "delete_workflow",
+                        description: "Delete a workflow from the configured n8n instance by its ID.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                workflowId: {
+                                    type: "string",
+                                    description: "The n8n workflow ID to delete",
+                                },
+                            },
+                            required: ["workflowId"],
+                        },
+                    },
+                    {
+                        name: "generate_docs",
+                        description: "Generate a Mermaid diagram and README documentation for a workflow JSON.",
+                        inputSchema: {
+                            type: "object",
+                            properties: {
+                                workflowJson: {
+                                    type: "object",
+                                    description: "The workflow JSON to document",
+                                },
+                            },
+                            required: ["workflowJson"],
+                        },
+                    },
                 ],
             };
         });
@@ -87,6 +177,108 @@ export class MCPService {
                         ],
                     };
                 }
+                else if (name === "modify_workflow") {
+                    const workflowJson = args.workflowJson;
+                    const instruction = String(args.instruction);
+                    const goal = `Modify the provided workflow based on these instructions: ${instruction}`;
+                    const result = await runAgenticWorkflow(goal, { workflowJson });
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(result.workflowJson || result, null, 2),
+                            },
+                        ],
+                    };
+                }
+                else if (name === "deploy_workflow") {
+                    const workflowJson = args.workflowJson;
+                    const forceCreate = Boolean(args.forceCreate ?? false);
+                    const client = await this.getN8nClient();
+                    let deployedId;
+                    if (workflowJson.id && !forceCreate) {
+                        let exists = false;
+                        try {
+                            await client.getWorkflow(workflowJson.id);
+                            exists = true;
+                        }
+                        catch { /* not found */ }
+                        if (exists) {
+                            await client.updateWorkflow(workflowJson.id, workflowJson);
+                            deployedId = workflowJson.id;
+                        }
+                        else {
+                            const r = await client.createWorkflow(workflowJson.name || "n8m-workflow", workflowJson);
+                            deployedId = r.id;
+                        }
+                    }
+                    else {
+                        const r = await client.createWorkflow(workflowJson.name || "n8m-workflow", workflowJson);
+                        deployedId = r.id;
+                    }
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ id: deployedId, link: client.getWorkflowLink(deployedId) }),
+                            },
+                        ],
+                    };
+                }
+                else if (name === "get_workflow") {
+                    const workflowId = String(args.workflowId);
+                    const client = await this.getN8nClient();
+                    const workflow = await client.getWorkflow(workflowId);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(workflow, null, 2),
+                            },
+                        ],
+                    };
+                }
+                else if (name === "list_workflows") {
+                    const client = await this.getN8nClient();
+                    const workflows = await client.getWorkflows();
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify(workflows, null, 2),
+                            },
+                        ],
+                    };
+                }
+                else if (name === "delete_workflow") {
+                    const workflowId = String(args.workflowId);
+                    const client = await this.getN8nClient();
+                    await client.deleteWorkflow(workflowId);
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ deleted: true, workflowId }),
+                            },
+                        ],
+                    };
+                }
+                else if (name === "generate_docs") {
+                    const workflowJson = args.workflowJson;
+                    const docService = DocService.getInstance();
+                    const mermaid = docService.generateMermaid(workflowJson);
+                    const readme = await docService.generateReadme(workflowJson);
+                    const workflowName = workflowJson.name || "Workflow";
+                    const fullDoc = `# ${workflowName}\n\n## Visual Flow\n\n\`\`\`mermaid\n${mermaid}\`\`\`\n\n${readme}`;
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: fullDoc,
+                            },
+                        ],
+                    };
+                }
                 throw new Error(`Tool not found: ${name}`);
             }
             catch (error) {
@@ -102,6 +294,15 @@ export class MCPService {
             }
         });
     }
+    async getN8nClient() {
+        const config = await ConfigManager.load();
+        const n8nUrl = config.n8nUrl || process.env.N8N_API_URL;
+        const n8nKey = config.n8nKey || process.env.N8N_API_KEY;
+        if (!n8nUrl || !n8nKey) {
+            throw new Error("Missing n8n credentials. Run 'n8m config' to set them.");
+        }
+        return new N8nClient({ apiUrl: n8nUrl, apiKey: n8nKey });
+    }
     async start() {
         const transport = new StdioServerTransport();
         await this.server.connect(transport);

package/dist/services/node-definitions.service.js

@@ -166,7 +166,7 @@ export class NodeDefinitionsService {
                     if (seen.has(file))
                         continue; // user pattern overrides built-in of same name
                     const content = fs.readFileSync(path.join(dir, file), 'utf-8');
-                    const keywordsMatch = content.match(/<!--\s*keywords:\s*([^\-]+)-->/i);
+                    const keywordsMatch = content.match(/<!--\s*keywords:\s*([^-]+)-->/i);
                     if (!keywordsMatch)
                         continue;
                     seen.add(file);

package/dist/utils/config.js

@@ -2,11 +2,13 @@ import fs from 'fs/promises';
 import path from 'path';
 import os from 'os';
 import dotenv from 'dotenv';
+// Load .env once at module initialisation. Dotenv skips vars already present
+// in the environment, so this never overwrites values set by the shell or CI.
+dotenv.config({ quiet: true });
 export class ConfigManager {
     static configDir = path.join(os.homedir(), '.n8m');
     static configFile = path.join(os.homedir(), '.n8m', 'config.json');
     static async load() {
-        dotenv.config({ quiet: true }); // Load .env from cwd if present (no-op if already loaded or file missing)
         try {
             const data = await fs.readFile(this.configFile, 'utf-8');
             return JSON.parse(data);

package/dist/utils/n8nClient.d.ts

@@ -2,6 +2,11 @@ export interface N8nClientConfig {
     apiUrl?: string;
     apiKey?: string;
 }
+export interface N8nCredential {
+    id: string;
+    name: string;
+    type: string;
+}
 export interface WorkflowExecutionResult {
     executionId: string;
     finished: boolean;
@@ -72,6 +77,12 @@ export declare class N8nClient {
      * Handles paginated responses and returns the full node type objects.
      */
     getNodeTypes(): Promise<any[]>;
+    /**
+     * Get all credentials configured on the n8n instance.
+     * Returns [] gracefully on 401/403/network errors so missing permissions
+     * never block workflow generation.
+     */
+    getCredentials(): Promise<N8nCredential[]>;
     /**
      * Get all workflows
      */

package/dist/utils/n8nClient.js

@@ -283,6 +283,45 @@ export class N8nClient {
             return [];
         }
     }
+    /**
+     * Get all credentials configured on the n8n instance.
+     * Returns [] gracefully on 401/403/network errors so missing permissions
+     * never block workflow generation.
+     */
+    async getCredentials() {
+        try {
+            let all = [];
+            let cursor = undefined;
+            do {
+                const url = new URL(`${this.apiUrl}/credentials`);
+                if (cursor)
+                    url.searchParams.set('cursor', cursor);
+                const response = await fetch(url.toString(), {
+                    headers: this.headers,
+                    method: 'GET',
+                });
+                if (!response.ok) {
+                    return [];
+                }
+                const result = await response.json();
+                if (Array.isArray(result)) {
+                    all = [...all, ...result];
+                    cursor = undefined;
+                }
+                else if (result.data && Array.isArray(result.data)) {
+                    all = [...all, ...result.data];
+                    cursor = result.nextCursor ?? undefined;
+                }
+                else {
+                    break;
+                }
+            } while (cursor);
+            return all.map((c) => ({ id: String(c.id), name: String(c.name), type: String(c.type) }));
+        }
+        catch {
+            return [];
+        }
+    }
     /**
      * Get all workflows
      */

package/docs/CNAME

@@ -0,0 +1 @@
+n8m.run

package/docs/DEVELOPER_GUIDE.md

@@ -1,3 +1,7 @@
+<div align="center">
+  <img src="../n8m-logo-v2.png" alt="n8m" width="160" />
+</div>
+
 # n8m Developer Guide
 
 > A deep-dive into the internals of `n8m` for contributors and developers who
@@ -47,25 +51,31 @@ n8m/
 │   │   ├── fixture.ts        # capture/init sub-commands for offline fixtures
 │   │   ├── learn.ts          # extract pattern knowledge from validated workflows
 │   │   ├── mcp.ts            # MCP server entry point
+│   │   ├── rollback.ts       # restore workflow to a previous git-tracked version
 │   │   ├── resume.ts
 │   │   ├── prune.ts
 │   │   └── config.ts
 │   ├── services/             # Core business logic services
 │   │   ├── ai.service.ts     # LLM abstraction layer
 │   │   ├── doc.service.ts    # Documentation generation
+│   │   ├── git.service.ts    # Git operations (history, diff, file-at-commit)
 │   │   ├── n8n.service.ts    # n8n API helpers
 │   │   ├── mcp.service.ts    # MCP server integration
 │   │   └── node-definitions.service.ts  # RAG for n8n node schemas
 │   ├── utils/
 │   │   ├── n8nClient.ts      # n8n REST API client
-│   │   ├── config.ts         # Config file management
+│   │   ├── config.ts         # Config file management (~/.n8m/config.json)
 │   │   ├── theme.ts          # CLI formatting/theming
+│   │   ├── spinner.ts        # Ora spinner wrapper
+│   │   ├── multilinePrompt.tsx  # Ink-based multiline input component
 │   │   ├── fixtureManager.ts # Read/write .n8m/fixtures/ (single-file + directory)
 │   │   └── sandbox.ts        # Isolated script runner for custom QA tools
 │   └── resources/
 │       └── node-definitions-fallback.json  # Static node schema fallback
 ├── docs/
-│   └── N8N_NODE_REFERENCE.md # Human-readable node reference (for LLM context)
+│   ├── DEVELOPER_GUIDE.md    # This file
+│   ├── N8N_NODE_REFERENCE.md # Human-readable node reference (for LLM context)
+│   └── patterns/             # AI-generated reusable workflow patterns
 ├── test/                     # Mocha unit tests
 └── workflows/                # Local workflow project folders
     └── <slug>/

package/docs/favicon.svg

@@ -0,0 +1,4 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="6" fill="#0b0d14"/>
+  <text x="16" y="23" font-family="'JetBrains Mono', 'Courier New', monospace" font-size="22" font-weight="700" fill="#22c55e" text-anchor="middle">8</text>
+</svg>