@lhi/n8m 0.2.0 → 0.2.2

package/dist/commands/doc.js

@@ -22,7 +22,7 @@ export default class Doc extends Command {
         }),
     };
     async run() {
-        const { args, flags } = await this.parse(Doc);
+        const { args } = await this.parse(Doc);
         this.log(theme.brand());
         this.log(theme.header('WORKFLOW DOCUMENTATION'));
         // 1. Load Credentials & Client

package/dist/commands/fixture.d.ts

@@ -0,0 +1,12 @@
+import { Command } from '@oclif/core';
+export default class Fixture extends Command {
+    static args: {
+        action: import("@oclif/core/interfaces").Arg<string, Record<string, unknown>>;
+        workflowId: import("@oclif/core/interfaces").Arg<string | undefined, Record<string, unknown>>;
+    };
+    static description: string;
+    static examples: string[];
+    run(): Promise<void>;
+    private initFixture;
+    private captureFixture;
+}

package/dist/commands/fixture.js

@@ -0,0 +1,258 @@
+import { Args, Command } from '@oclif/core';
+import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import { existsSync } from 'node:fs';
+import inquirer from 'inquirer';
+import { theme } from '../utils/theme.js';
+import { N8nClient } from '../utils/n8nClient.js';
+import { ConfigManager } from '../utils/config.js';
+import { FixtureManager } from '../utils/fixtureManager.js';
+export default class Fixture extends Command {
+    static args = {
+        action: Args.string({
+            description: 'Action to perform (init, capture)',
+            required: true,
+            options: ['init', 'capture'],
+        }),
+        workflowId: Args.string({
+            description: 'n8n workflow ID (optional — omit to browse and select)',
+            required: false,
+        }),
+    };
+    static description = 'Manage n8m workflow fixtures for offline testing';
+    static examples = [
+        '<%= config.bin %> fixture init abc123       # scaffold an empty fixture template',
+        '<%= config.bin %> fixture capture           # browse local files + n8n instance to pick a workflow',
+        '<%= config.bin %> fixture capture abc123    # pull latest real execution for a specific workflow ID',
+    ];
+    async run() {
+        const { args } = await this.parse(Fixture);
+        if (args.action === 'init') {
+            await this.initFixture(args.workflowId);
+        }
+        else if (args.action === 'capture') {
+            await this.captureFixture(args.workflowId);
+        }
+    }
+    async initFixture(workflowId) {
+        if (!workflowId) {
+            this.log(theme.fail('Usage: n8m fixture init <workflowId>'));
+            return;
+        }
+        const fixturesDir = path.join(process.cwd(), '.n8m', 'fixtures');
+        const fixturePath = path.join(fixturesDir, `${workflowId}.json`);
+        if (existsSync(fixturePath)) {
+            const { overwrite } = await inquirer.prompt([{
+                    type: 'confirm',
+                    name: 'overwrite',
+                    message: `Fixture already exists at ${fixturePath}. Overwrite?`,
+                    default: false,
+                }]);
+            if (!overwrite) {
+                this.log(theme.muted('Aborted.'));
+                return;
+            }
+        }
+        const schemaPath = '../../node_modules/n8m/dist/fixture-schema.json';
+        const capturedAt = new Date().toISOString();
+        const template = {
+            $schema: schemaPath,
+            version: '1.0',
+            capturedAt,
+            workflowId,
+            workflowName: 'My Workflow',
+            workflow: {
+                name: 'My Workflow',
+                nodes: [],
+                connections: {},
+            },
+            execution: {
+                status: 'success',
+                data: {
+                    resultData: {
+                        error: null,
+                        runData: {
+                            'Your Node Name': [
+                                { json: { key: 'value' } },
+                            ],
+                        },
+                    },
+                },
+            },
+        };
+        await fs.mkdir(fixturesDir, { recursive: true });
+        await fs.writeFile(fixturePath, JSON.stringify(template, null, 2), 'utf-8');
+        this.log(theme.success(`Created ${fixturePath}`));
+        this.log('');
+        this.log(theme.muted('  Fill in each node\'s output under execution.data.resultData.runData.'));
+        this.log(theme.muted('  Keys must match exact node names in your workflow.'));
+        this.log('');
+        this.log(theme.muted('  To test with this fixture:'));
+        this.log(theme.muted(`    n8m test --fixture ${fixturePath}`));
+        this.log(theme.muted(`  Or n8m will auto-detect it when you run: n8m test (workflow ID: ${workflowId})`));
+    }
+    async captureFixture(workflowId) {
+        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) {
+            this.log(theme.fail('n8n instance not configured. Run: n8m config --n8n-url <url> --n8n-key <key>'));
+            return;
+        }
+        const client = new N8nClient({ apiUrl: n8nUrl, apiKey: n8nKey });
+        // If no workflowId provided, show interactive picker (local + remote)
+        let resolvedId = workflowId;
+        let resolvedName;
+        if (!resolvedId) {
+            this.log(theme.info('Searching for local and remote workflows...'));
+            const localChoices = [];
+            const workflowsDir = path.join(process.cwd(), 'workflows');
+            const searchDirs = [workflowsDir, process.cwd()];
+            for (const dir of searchDirs) {
+                if (existsSync(dir)) {
+                    const files = await fs.readdir(dir);
+                    for (const file of files) {
+                        if (file.endsWith('.json')) {
+                            try {
+                                const raw = await fs.readFile(path.join(dir, file), 'utf-8');
+                                const parsed = JSON.parse(raw);
+                                if (parsed.id) {
+                                    localChoices.push({
+                                        name: `${theme.value('[LOCAL]')} ${parsed.name ?? file} (${parsed.id})`,
+                                        value: { type: 'local', id: parsed.id, name: parsed.name ?? file },
+                                    });
+                                }
+                            }
+                            catch {
+                                // skip unparseable files
+                            }
+                        }
+                    }
+                }
+            }
+            let remoteChoices = [];
+            try {
+                const remoteWorkflows = await client.getWorkflows();
+                remoteChoices = remoteWorkflows
+                    .filter((w) => !w.name.startsWith('[TEST'))
+                    .map((w) => ({
+                    name: `${theme.info('[n8n]')} ${w.name} (${w.id})${w.active ? ' [Active]' : ''}`,
+                    value: { type: 'remote', id: w.id, name: w.name },
+                }));
+            }
+            catch (e) {
+                this.log(theme.warn(`Could not fetch remote workflows: ${e.message}`));
+            }
+            const choices = [
+                ...(localChoices.length > 0 ? [new inquirer.Separator('--- Local Files ---'), ...localChoices] : []),
+                ...(remoteChoices.length > 0 ? [new inquirer.Separator('--- n8n Instance ---'), ...remoteChoices] : []),
+            ];
+            if (choices.length === 0) {
+                this.log(theme.fail('No workflows found locally or on your n8n instance.'));
+                return;
+            }
+            const { selection } = await inquirer.prompt([{
+                    type: 'select',
+                    name: 'selection',
+                    message: 'Select a workflow to capture:',
+                    choices,
+                    pageSize: 15,
+                }]);
+            resolvedId = selection.id;
+            resolvedName = selection.name;
+        }
+        if (!resolvedId)
+            return;
+        this.log(theme.agent(`Fetching workflow ${resolvedId} from n8n...`));
+        let workflow;
+        try {
+            workflow = await client.getWorkflow(resolvedId);
+        }
+        catch (e) {
+            this.log(theme.fail(`Could not fetch workflow: ${e.message}`));
+            return;
+        }
+        resolvedName = resolvedName ?? workflow.name ?? resolvedId;
+        this.log(theme.agent(`Fetching executions for workflow ${resolvedId}...`));
+        let executions;
+        try {
+            executions = await client.getWorkflowExecutions(resolvedId);
+        }
+        catch (e) {
+            this.log(theme.fail(`Could not fetch executions: ${e.message}`));
+            return;
+        }
+        if (!executions?.length) {
+            this.log(theme.warn('No executions found for this workflow. Run it in n8n first, then capture.'));
+            return;
+        }
+        const executionChoices = executions.map((ex) => {
+            const date = ex.startedAt ? new Date(ex.startedAt).toLocaleString() : 'unknown time';
+            const rawStatus = ex.status ?? (ex.finished === true ? 'success' : ex.finished === false ? 'running' : undefined);
+            const statusLabel = rawStatus === 'success' ? theme.success(rawStatus)
+                : rawStatus ? theme.fail(rawStatus)
+                    : theme.muted('unknown');
+            return {
+                name: `#${ex.id}  ${statusLabel}  ${theme.muted(date)}`,
+                value: ex,
+            };
+        });
+        const { selectedExecution } = await inquirer.prompt([{
+                type: 'select',
+                name: 'selectedExecution',
+                message: 'Select an execution to capture:',
+                choices: executionChoices,
+                pageSize: 15,
+            }]);
+        const latest = selectedExecution;
+        this.log(theme.muted(`  Selected execution ${latest.id} (${latest.status}, ${latest.startedAt})`));
+        let fullExec;
+        try {
+            fullExec = await client.getExecution(latest.id);
+        }
+        catch (e) {
+            this.log(theme.fail(`Could not fetch execution data: ${e.message}`));
+            return;
+        }
+        const fixtureManager = new FixtureManager();
+        const fixturePath = path.join(process.cwd(), '.n8m', 'fixtures', `${resolvedId}.json`);
+        if (existsSync(fixturePath)) {
+            const { overwrite } = await inquirer.prompt([{
+                    type: 'confirm',
+                    name: 'overwrite',
+                    message: `Fixture already exists for workflow ${resolvedId}. Overwrite?`,
+                    default: true,
+                }]);
+            if (!overwrite) {
+                this.log(theme.muted('Aborted.'));
+                return;
+            }
+        }
+        await fixtureManager.save({
+            version: '1.0',
+            capturedAt: new Date().toISOString(),
+            workflowId: resolvedId,
+            workflowName: resolvedName ?? resolvedId,
+            workflow,
+            execution: {
+                id: fullExec.id,
+                status: fullExec.status,
+                startedAt: fullExec.startedAt,
+                data: {
+                    resultData: {
+                        error: fullExec.data?.resultData?.error ?? null,
+                        runData: fullExec.data?.resultData?.runData ?? {},
+                    },
+                },
+            },
+        });
+        const nodeCount = Object.keys(fullExec.data?.resultData?.runData ?? {}).length;
+        this.log(theme.success(`Fixture saved to .n8m/fixtures/${resolvedId}.json`));
+        this.log(theme.muted(`  Workflow: ${resolvedName}`));
+        this.log(theme.muted(`  Execution: ${fullExec.status} · ${nodeCount} node(s) captured`));
+        this.log('');
+        this.log(theme.muted('  To test with this fixture:'));
+        this.log(theme.muted(`    n8m test --fixture .n8m/fixtures/${resolvedId}.json`));
+        this.log(theme.muted(`  Or just run: n8m test  (auto-detected by workflow ID)`));
+    }
+}

package/dist/commands/test.d.ts

@@ -10,19 +10,78 @@ export default class Test extends Command {
         'no-brand': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'validate-only': import("@oclif/core/interfaces").BooleanFlag<boolean>;
         'ai-scenarios': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        fixture: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
     };
     run(): Promise<void>;
     /**
      * Extract clean error message from n8n API responses
      */
     private cleanErrorMsg;
-    /**
-     * Normalize error messages to catch "similar" errors (masking IDs/numbers)
-     */
-    private normalizeError;
     private sanitizeWorkflow;
     private stripShim;
     private saveWorkflows;
     private handlePostTestActions;
+    /**
+     * Test a workflow that already exists on the n8n instance, using its real credentials
+     * and configured triggers — no ephemeral copy, no credential stripping, no shim injection.
+     */
+    private testRemoteWorkflowDirectly;
+    /**
+     * Scan a workflow's expressions to find all field names accessed via $json.body.FIELD.
+     * These become required keys in the test POST payload because n8n wraps the body
+     * automatically — a downstream expression $json.body.content needs {"content": ...} in the POST.
+     */
+    private extractRequiredBodyFields;
+    /**
+     * Load a pre-defined test payload fixture for a specific workflow.
+     * Checks (in order): ./workflow-test-fixtures.json, ./workflows/test-fixtures.json,
+     * and the bundled src/resources/workflow-test-fixtures.json.
+     * Returns null if no matching fixture is found.
+     */
+    private loadWorkflowFixture;
+    /**
+     * Load node-test-hints.json and build a context string describing what
+     * data format each node type in the workflow expects.  Used to inform
+     * generateMockData so the AI sends correctly-shaped values (e.g. Block Kit
+     * JSON for a Slack blocksUi parameter instead of a plain string).
+     */
+    private extractNodeTypeHints;
+    /**
+     * Find nodes that feed binary data into upload-type nodes.
+     * Returns node names whose outputs should be pinned with a test binary
+     * so downstream file-upload steps receive real content instead of empty buffers.
+     */
+    private findBinarySourceNodes;
+    /**
+     * Detect webhook body fields that are used as image/file URLs by HTTP Request
+     * nodes that sit immediately upstream of binary-upload nodes.
+     *
+     * When n8n fetches a real image URL (supplied via the webhook payload) it gets
+     * actual binary bytes, which then flow into the upload step.  Returning these
+     * field names lets the prompt instruct the AI to use a real hosted image URL
+     * (e.g. placehold.co) instead of a placeholder string — so the upload step
+     * receives real binary data without needing pinData API support.
+     */
+    private findBinaryUrlFields;
+    /**
+     * Deep-scan all node parameter values and strip control characters
+     * (U+0000–U+001F, U+007F).  Returns the sanitized nodes array and a flag
+     * indicating whether any changes were made.
+     *
+     * Control chars in node params (e.g. a literal newline inside a Slack
+     * blocksUi JSON string) are workflow configuration bugs — they cause n8n to
+     * throw "could not be parsed" at execution time regardless of the test payload.
+     */
+    private sanitizeWorkflowNodeParams;
+    /**
+     * Strip control characters (U+0000–U+001F, except tab/LF/CR) from all
+     * string values in a generated mock payload.  AI-generated Block Kit JSON
+     * and other rich-text fields sometimes contain raw control chars that cause
+     * n8n's parameter parser to throw "Bad control character in string literal".
+     */
+    private sanitizeMockPayload;
     private deployWorkflows;
+    private offerSaveFixture;
+    private testWithFixture;
+    private findPredecessorNode;
 }