@n8n-as-code/transformer 0.2.0

package/README.md

@@ -0,0 +1,215 @@
+# @n8n-as-code/transformer
+
+> **✨ NEW in v0.2.0**: This package enables the new **TypeScript workflow format** (`.workflow.ts`) that replaces JSON as the default storage format across n8n-as-code.
+
+Bidirectional transformer for n8n workflows: JSON ↔ TypeScript
+
+## Overview
+
+This package provides the core transformation engine that converts:
+- **JSON → TypeScript**: n8n workflow JSON (from API) → TypeScript class with decorators
+- **TypeScript → JSON**: TypeScript workflow class → n8n workflow JSON (for API)
+
+## Features
+
+- ✅ **Bidirectional transformation** with roundtrip support
+- ✅ **TypeScript decorators** for clean, readable workflow definitions
+- ✅ **Auto-layout support** for AI-generated workflows (optional positions)
+- ✅ **Name collision handling** (HttpRequest1, HttpRequest2, ...)
+- ✅ **Prettier integration** for formatted output
+- ✅ **AI dependency injection** syntax for LangChain nodes
+
+## Installation
+
+```bash
+npm install @n8n-as-code/transformer
+```
+
+## Usage
+
+### For Workflow Authors (TypeScript)
+
+```typescript
+import { workflow, node, links } from '@n8n-as-code/transformer';
+
+@workflow({
+    id: "unique-workflow-id",
+    name: "My Workflow",
+    active: true,
+    settings: { executionOrder: "v1" }
+})
+export class MyWorkflow {
+    
+    @node({
+        name: "Schedule Trigger",
+        type: "n8n-nodes-base.scheduleTrigger",
+        version: 1.2,
+        position: [0, 0]
+    })
+    ScheduleTrigger = {
+        rule: {
+            interval: [{
+                field: "cronExpression",
+                expression: "0 9 * * 1-5"
+            }]
+        }
+    };
+    
+    @node({
+        name: "HTTP Request",
+        type: "n8n-nodes-base.httpRequest",
+        version: 4,
+        position: [200, 0]
+    })
+    HttpRequest = {
+        url: "https://api.example.com/data",
+        method: "GET"
+    };
+    
+    @links()
+    defineRouting() {
+        this.ScheduleTrigger.out(0).to(this.HttpRequest.in(0));
+    }
+}
+```
+
+### For Package Developers (Transformation)
+
+```typescript
+import { JsonToAstParser, AstToTypeScriptGenerator } from '@n8n-as-code/transformer';
+
+// JSON → TypeScript
+const parser = new JsonToAstParser();
+const ast = parser.parse(workflowJson);
+
+const generator = new AstToTypeScriptGenerator();
+const tsCode = await generator.generate(ast, {
+    format: true,
+    commentStyle: 'verbose'
+});
+
+console.log(tsCode); // Ready to write to .workflow.ts file
+```
+
+```typescript
+import { TypeScriptParser, WorkflowBuilder } from '@n8n-as-code/transformer';
+
+// TypeScript → JSON (Phase 2 - coming soon)
+const parser = new TypeScriptParser();
+const ast = await parser.parseFile('my-workflow.ts');
+
+const builder = new WorkflowBuilder();
+const workflowJson = builder.build(ast);
+
+console.log(workflowJson); // Ready to push to n8n API
+```
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────┐
+│                                             │
+│  n8n JSON Workflow (API)                   │
+│                                             │
+└──────────────┬──────────────────────────────┘
+               │
+               │ JsonToAstParser
+               ▼
+┌─────────────────────────────────────────────┐
+│                                             │
+│  WorkflowAST (Intermediate)                │
+│  - Normalized structure                     │
+│  - Property names instead of UUIDs          │
+│                                             │
+└──────────────┬──────────────────────────────┘
+               │
+               │ AstToTypeScriptGenerator
+               ▼
+┌─────────────────────────────────────────────┐
+│                                             │
+│  TypeScript Workflow (.workflow.ts)        │
+│  - Decorators (@workflow, @node, @links)   │
+│  - Human-readable property names            │
+│  - Formatted with Prettier                  │
+│                                             │
+└─────────────────────────────────────────────┘
+```
+
+## Status
+
+- ✅ **Phase 1**: Architecture & decorators (COMPLETE)
+- 🚧 **Phase 2**: Core transformation logic (IN PROGRESS)
+- ⏳ **Phase 3**: Integration with @n8n-as-code/sync
+- ⏳ **Phase 4**: Integration with @n8n-as-code/skills
+
+## API Reference
+
+### Decorators
+
+#### `@workflow(metadata)`
+
+Marks a class as an n8n workflow.
+
+**Parameters:**
+- `id`: Workflow ID (UUID)
+- `name`: Workflow name
+- `active`: Whether workflow is active
+- `settings?`: Workflow settings (executionOrder, etc.)
+
+#### `@node(metadata)`
+
+Marks a property as an n8n node.
+
+**Parameters:**
+- `name`: Node display name
+- `type`: Node type (e.g., "n8n-nodes-base.httpRequest")
+- `version`: Node version
+- `position?`: [x, y] coordinates (optional for auto-layout)
+- `credentials?`: Node credentials
+- `onError?`: Error handling behavior
+
+#### `@links()`
+
+Marks the method that defines workflow routing.
+
+### Transformation Classes
+
+#### `JsonToAstParser`
+
+Parses n8n JSON to intermediate AST.
+
+```typescript
+const parser = new JsonToAstParser();
+const ast = parser.parse(workflowJson);
+```
+
+#### `AstToTypeScriptGenerator`
+
+Generates TypeScript code from AST.
+
+```typescript
+const generator = new AstToTypeScriptGenerator();
+const code = await generator.generate(ast, options);
+```
+
+**Options:**
+- `format?: boolean` - Apply Prettier formatting (default: true)
+- `commentStyle?: 'minimal' | 'verbose'` - Comment style (default: 'verbose')
+- `className?: string` - Custom class name
+
+## Development
+
+```bash
+# Build
+npm run build
+
+# Tests
+npm test
+
+# Type check
+npm run typecheck
+```
+
+## License
+
+See LICENSE in repository root.

package/dist/compiler/index.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Compiler exports
+ */
+export { TypeScriptParser } from './typescript-parser.js';
+export { WorkflowBuilder } from './workflow-builder.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/compiler/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/compiler/index.js

@@ -0,0 +1,6 @@
+/**
+ * Compiler exports
+ */
+export { TypeScriptParser } from './typescript-parser.js';
+export { WorkflowBuilder } from './workflow-builder.js';
+//# sourceMappingURL=index.js.map

package/dist/compiler/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/compiler/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC1D,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/compiler/typescript-parser.d.ts

@@ -0,0 +1,87 @@
+/**
+ * TypeScript Parser
+ *
+ * Parses TypeScript workflow files using ts-morph
+ * Extracts metadata from decorators and class structure
+ */
+import { WorkflowAST } from '../types.js';
+/**
+ * Parse TypeScript workflow file
+ */
+export declare class TypeScriptParser {
+    private project;
+    constructor();
+    /**
+     * Parse TypeScript file
+     */
+    parseFile(filePath: string): Promise<WorkflowAST>;
+    /**
+     * Parse TypeScript code string
+     */
+    parseCode(code: string): Promise<WorkflowAST>;
+    /**
+     * Parse source file to AST
+     */
+    private parseSourceFile;
+    /**
+     * Find class decorated with @workflow
+     */
+    private findWorkflowClass;
+    /**
+     * Extract workflow metadata from @workflow decorator
+     */
+    private extractWorkflowMetadata;
+    /**
+     * Extract nodes from class properties with @node decorator
+     */
+    private extractNodes;
+    /**
+     * Extract connections from @links method
+     */
+    private extractConnections;
+    /**
+     * Extract AI dependencies from .uses() calls in @links method
+     *
+     * Example:
+     *   this.AgentIa.uses({
+     *     ai_languageModel: this.OpenaiChatModel.output,
+     *     ai_memory: this.Mmoire.output,
+     *     ai_tool: [this.Tool1.output, this.Tool2.output]
+     *   });
+     */
+    private extractAIDependencies;
+    /**
+     * Parse AI dependencies object from .uses() call
+     *
+     * Input: "ai_languageModel: this.Model.output, ai_memory: this.Memory.output"
+     * Output: { ai_languageModel: "Model", ai_memory: "Memory" }
+     */
+    private parseAIDependencies;
+    /**
+     * Split string by commas, but not inside brackets
+     */
+    private splitByTopLevelCommas;
+    /**
+     * Parse tool array
+     *
+     * Input: "[this.Tool1.output, this.Tool2.output]"
+     * Output: ["Tool1", "Tool2"]
+     */
+    private parseToolArray;
+    /**
+     * Parse a connection statement
+     *
+     * Examples:
+     *   this.ScheduleTrigger.out(0).to(this.HttpRequest.in(0));
+     *   this.GithubCheck.error().to(this.CreateBranch.in(0));
+     */
+    private parseConnectionStatement;
+    /**
+     * Parse object literal string to object
+     *
+     * Uses Function constructor for safe eval of object literals
+     * This is safe because we only parse our own generated code
+     */
+    private parseObjectLiteral;
+}
+//# sourceMappingURL=typescript-parser.d.ts.map

package/dist/compiler/typescript-parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-parser.d.ts","sourceRoot":"","sources":["../../src/compiler/typescript-parser.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAGH,OAAO,EAAE,WAAW,EAA4C,MAAM,aAAa,CAAC;AAEpF;;GAEG;AACH,qBAAa,gBAAgB;IACzB,OAAO,CAAC,OAAO,CAAU;;IAazB;;OAEG;IACG,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAKvD;;OAEG;IACG,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAKnD;;OAEG;IACH,OAAO,CAAC,eAAe;IA2BvB;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAgBzB;;OAEG;IACH,OAAO,CAAC,uBAAuB;IAwB/B;;OAEG;IACH,OAAO,CAAC,YAAY;IA2CpB;;OAEG;IACH,OAAO,CAAC,kBAAkB;IAiD1B;;;;;;;;;OASG;IACH,OAAO,CAAC,qBAAqB;IA2D7B;;;;;OAKG;IACH,OAAO,CAAC,mBAAmB;IAoC3B;;OAEG;IACH,OAAO,CAAC,qBAAqB;IAyB7B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;IAmBtB;;;;;;OAMG;IACH,OAAO,CAAC,wBAAwB;IA2ChC;;;;;OAKG;IACH,OAAO,CAAC,kBAAkB;CAU7B"}

package/dist/compiler/typescript-parser.js

@@ -0,0 +1,379 @@
+/**
+ * TypeScript Parser
+ *
+ * Parses TypeScript workflow files using ts-morph
+ * Extracts metadata from decorators and class structure
+ */
+import { Project, SyntaxKind } from 'ts-morph';
+/**
+ * Parse TypeScript workflow file
+ */
+export class TypeScriptParser {
+    project;
+    constructor() {
+        this.project = new Project({
+            compilerOptions: {
+                target: 99, // ESNext
+                module: 99, // ESNext
+                experimentalDecorators: true,
+                emitDecoratorMetadata: true
+            }
+        });
+    }
+    /**
+     * Parse TypeScript file
+     */
+    async parseFile(filePath) {
+        const sourceFile = this.project.addSourceFileAtPath(filePath);
+        return this.parseSourceFile(sourceFile);
+    }
+    /**
+     * Parse TypeScript code string
+     */
+    async parseCode(code) {
+        const sourceFile = this.project.createSourceFile('temp.ts', code, { overwrite: true });
+        return this.parseSourceFile(sourceFile);
+    }
+    /**
+     * Parse source file to AST
+     */
+    parseSourceFile(sourceFile) {
+        // Find class with @workflow decorator
+        const workflowClass = this.findWorkflowClass(sourceFile);
+        if (!workflowClass) {
+            throw new Error('No class with @workflow decorator found in file');
+        }
+        // Extract workflow metadata
+        const metadata = this.extractWorkflowMetadata(workflowClass);
+        // Extract nodes
+        const nodes = this.extractNodes(workflowClass);
+        // Extract connections
+        const connections = this.extractConnections(workflowClass);
+        // Extract AI dependencies and add them to nodes
+        this.extractAIDependencies(workflowClass, nodes);
+        return {
+            metadata,
+            nodes,
+            connections
+        };
+    }
+    /**
+     * Find class decorated with @workflow
+     */
+    findWorkflowClass(sourceFile) {
+        const classes = sourceFile.getClasses();
+        for (const cls of classes) {
+            const decorators = cls.getDecorators();
+            for (const decorator of decorators) {
+                const decoratorName = decorator.getName();
+                if (decoratorName === 'workflow') {
+                    return cls;
+                }
+            }
+        }
+        return null;
+    }
+    /**
+     * Extract workflow metadata from @workflow decorator
+     */
+    extractWorkflowMetadata(workflowClass) {
+        const decorator = workflowClass.getDecorator('workflow');
+        if (!decorator) {
+            throw new Error('Class missing @workflow decorator');
+        }
+        // Get decorator arguments
+        const args = decorator.getArguments();
+        if (args.length === 0) {
+            throw new Error('@workflow decorator missing metadata argument');
+        }
+        // Parse object literal argument
+        const metadataArg = args[0];
+        const metadataText = metadataArg.getText();
+        // Use eval in a safe context to parse the object literal
+        // This is safe because we're only parsing our own generated code
+        const metadata = this.parseObjectLiteral(metadataText);
+        return metadata;
+    }
+    /**
+     * Extract nodes from class properties with @node decorator
+     */
+    extractNodes(workflowClass) {
+        const nodes = [];
+        const properties = workflowClass.getProperties();
+        for (const prop of properties) {
+            const decorator = prop.getDecorator('node');
+            if (!decorator) {
+                continue; // Skip properties without @node decorator
+            }
+            // Extract node metadata from decorator
+            const args = decorator.getArguments();
+            if (args.length === 0) {
+                continue;
+            }
+            const metadataText = args[0].getText();
+            const metadata = this.parseObjectLiteral(metadataText);
+            // Extract property name
+            const propertyName = prop.getName();
+            // Extract parameters from property initializer
+            const initializer = prop.getInitializer();
+            const parameters = initializer ? this.parseObjectLiteral(initializer.getText()) : {};
+            nodes.push({
+                propertyName,
+                displayName: metadata.name,
+                type: metadata.type,
+                version: metadata.version,
+                position: metadata.position || [0, 0],
+                credentials: metadata.credentials,
+                onError: metadata.onError,
+                parameters
+                // aiDependencies will be added by extractAIDependencies()
+            });
+        }
+        return nodes;
+    }
+    /**
+     * Extract connections from @links method
+     */
+    extractConnections(workflowClass) {
+        const connections = [];
+        // Find method with @links decorator
+        const methods = workflowClass.getMethods();
+        let linksMethod = null;
+        for (const method of methods) {
+            const decorator = method.getDecorator('links');
+            if (decorator) {
+                linksMethod = method;
+                break;
+            }
+        }
+        if (!linksMethod) {
+            return connections; // No connections defined
+        }
+        // Parse method body to extract connections
+        const body = linksMethod.getBody();
+        if (!body || !body.isKind(SyntaxKind.Block)) {
+            return connections;
+        }
+        // Get all statements in the method
+        const statements = body.getStatements();
+        for (const statement of statements) {
+            const text = statement.getText();
+            // Parse connection statements
+            // Format: this.NodeA.out(0).to(this.NodeB.in(0));
+            // Format: this.NodeA.error().to(this.NodeB.in(0));
+            // Skip .uses() calls (handled by extractAIDependencies)
+            if (text.includes('.uses(')) {
+                continue;
+            }
+            const connection = this.parseConnectionStatement(text);
+            if (connection) {
+                connections.push(connection);
+            }
+        }
+        return connections;
+    }
+    /**
+     * Extract AI dependencies from .uses() calls in @links method
+     *
+     * Example:
+     *   this.AgentIa.uses({
+     *     ai_languageModel: this.OpenaiChatModel.output,
+     *     ai_memory: this.Mmoire.output,
+     *     ai_tool: [this.Tool1.output, this.Tool2.output]
+     *   });
+     */
+    extractAIDependencies(workflowClass, nodes) {
+        // Find method with @links decorator
+        const methods = workflowClass.getMethods();
+        let linksMethod = null;
+        for (const method of methods) {
+            const decorator = method.getDecorator('links');
+            if (decorator) {
+                linksMethod = method;
+                break;
+            }
+        }
+        if (!linksMethod) {
+            return; // No links method
+        }
+        // Parse method body
+        const body = linksMethod.getBody();
+        if (!body || !body.isKind(SyntaxKind.Block)) {
+            return;
+        }
+        const statements = body.getStatements();
+        for (const statement of statements) {
+            const text = statement.getText();
+            // Only process .uses() calls
+            if (!text.includes('.uses(')) {
+                continue;
+            }
+            // Parse: this.NodeName.uses({ ... });
+            const usesMatch = text.match(/this\.(\w+)\.uses\s*\(\s*\{([^}]+)\}\s*\)/);
+            if (!usesMatch) {
+                continue;
+            }
+            const targetNodeProperty = usesMatch[1];
+            const depsObjectText = usesMatch[2];
+            // Find the corresponding node
+            const node = nodes.find(n => n.propertyName === targetNodeProperty);
+            if (!node) {
+                console.warn(`Warning: .uses() called on unknown node: ${targetNodeProperty}`);
+                continue;
+            }
+            // Parse dependencies object
+            const aiDependencies = this.parseAIDependencies(depsObjectText);
+            // Add to node
+            if (Object.keys(aiDependencies).length > 0) {
+                node.aiDependencies = aiDependencies;
+            }
+        }
+    }
+    /**
+     * Parse AI dependencies object from .uses() call
+     *
+     * Input: "ai_languageModel: this.Model.output, ai_memory: this.Memory.output"
+     * Output: { ai_languageModel: "Model", ai_memory: "Memory" }
+     */
+    parseAIDependencies(depsText) {
+        const result = {};
+        // Split by comma (but not inside brackets)
+        const entries = this.splitByTopLevelCommas(depsText);
+        for (const entry of entries) {
+            const trimmed = entry.trim();
+            if (!trimmed)
+                continue;
+            // Parse: key: value
+            const colonIndex = trimmed.indexOf(':');
+            if (colonIndex === -1)
+                continue;
+            const key = trimmed.substring(0, colonIndex).trim();
+            const value = trimmed.substring(colonIndex + 1).trim();
+            // Check if it's an array type (ai_tool or ai_document)
+            if ((key === 'ai_tool' || key === 'ai_document') && value.startsWith('[')) {
+                // Parse array: [this.Tool1.output, this.Tool2.output]
+                const itemNames = this.parseToolArray(value);
+                if (itemNames.length > 0) {
+                    result[key] = itemNames;
+                }
+            }
+            else {
+                // Parse single reference: this.NodeName.output
+                const nodeMatch = value.match(/this\.(\w+)\.output/);
+                if (nodeMatch) {
+                    result[key] = nodeMatch[1];
+                }
+            }
+        }
+        return result;
+    }
+    /**
+     * Split string by commas, but not inside brackets
+     */
+    splitByTopLevelCommas(text) {
+        const result = [];
+        let current = '';
+        let bracketDepth = 0;
+        for (const char of text) {
+            if (char === '[') {
+                bracketDepth++;
+            }
+            else if (char === ']') {
+                bracketDepth--;
+            }
+            else if (char === ',' && bracketDepth === 0) {
+                result.push(current);
+                current = '';
+                continue;
+            }
+            current += char;
+        }
+        if (current.trim()) {
+            result.push(current);
+        }
+        return result;
+    }
+    /**
+     * Parse tool array
+     *
+     * Input: "[this.Tool1.output, this.Tool2.output]"
+     * Output: ["Tool1", "Tool2"]
+     */
+    parseToolArray(arrayText) {
+        const result = [];
+        // Remove brackets
+        const content = arrayText.replace(/^\[|\]$/g, '').trim();
+        // Split by comma
+        const items = content.split(',');
+        for (const item of items) {
+            const nodeMatch = item.trim().match(/this\.(\w+)\.output/);
+            if (nodeMatch) {
+                result.push(nodeMatch[1]);
+            }
+        }
+        return result;
+    }
+    /**
+     * Parse a connection statement
+     *
+     * Examples:
+     *   this.ScheduleTrigger.out(0).to(this.HttpRequest.in(0));
+     *   this.GithubCheck.error().to(this.CreateBranch.in(0));
+     */
+    parseConnectionStatement(statement) {
+        // Remove whitespace and semicolon
+        const cleaned = statement.trim().replace(/;$/, '');
+        // Pattern: this.{fromNode}.{output}.to(this.{toNode}.in({input}))
+        const errorPattern = /this\.(\w+)\.error\(\)\.to\(this\.(\w+)\.in\((\d+)\)\)/;
+        const normalPattern = /this\.(\w+)\.out\((\d+)\)\.to\(this\.(\w+)\.in\((\d+)\)\)/;
+        // Try error pattern first
+        let match = cleaned.match(errorPattern);
+        if (match) {
+            return {
+                from: {
+                    node: match[1],
+                    output: 0,
+                    isError: true
+                },
+                to: {
+                    node: match[2],
+                    input: parseInt(match[3])
+                }
+            };
+        }
+        // Try normal pattern
+        match = cleaned.match(normalPattern);
+        if (match) {
+            return {
+                from: {
+                    node: match[1],
+                    output: parseInt(match[2]),
+                    isError: false
+                },
+                to: {
+                    node: match[3],
+                    input: parseInt(match[4])
+                }
+            };
+        }
+        return null;
+    }
+    /**
+     * Parse object literal string to object
+     *
+     * Uses Function constructor for safe eval of object literals
+     * This is safe because we only parse our own generated code
+     */
+    parseObjectLiteral(text) {
+        try {
+            // Wrap in parentheses and use Function constructor
+            const func = new Function(`return (${text})`);
+            return func();
+        }
+        catch (error) {
+            console.error('Failed to parse object literal:', text);
+            throw new Error(`Failed to parse object literal: ${error}`);
+        }
+    }
+}
+//# sourceMappingURL=typescript-parser.js.map