Code To Workflow

Code2n8n — Code → n8n Workflow

The marquee Code2n8n skill. Input: an existing program or system (Python / TypeScript / Apps Script / Netlify Functions / Express / Flask / shell pipelines / Lambda). Output: an n8n workflow (or set of workflows) that performs the same behaviour, plus the SDD / FIELD-MAPPING / PROVENANCE / CREDITS / install docs that make it deployable, auditable, and handover-ready.

This skill encodes the methodology proven by the three case studies in this pack:

Read at least one before using this skill — they are the empirical ground truth behind every step below.

When to trigger

Hard rules

1. Never strip the upstream license / attribution. Code2n8n is a derivative-work pattern. Always copy LICENSE, write a CREDITS.md, and record the attribution chain (upstream → derivative changes → this pack). The MIT case study (line-ai-customer-service-onprem) is the template.
2. Scrub secrets before commit. Real API keys, JWTs, OAuth tokens, hard-coded passwords in .env* / docker-compose.yml / config.*.json / source code must be replaced with env-var placeholders. Do a grep -rn "sk-[a-zA-Z0-9]\{20,\}\|ghp_\|AIza\|password.*=.*[a-zA-Z0-9]\{8,\}" pass before staging.
3. Audit auth + injection before calling the port "enterprise-grade". Most AI-coded POCs ship with /me-always-returns-true style auth stubs, plaintext passwords, missing middleware, and identifier-injection patterns (raw req.body keys concatenated into SQL). The real-world example line-ai-customer-service-onprem has all of these — see its SECURITY-CAVEATS.md. If you find these and don't fix them, you MUST publish a SECURITY-CAVEATS.md (or equivalent), downgrade any "enterprise-ready" / "production" wording, and tell the reader exactly what to harden before deploying. Disclose, don't silently patch — silent patching misrepresents the case study and lets the next porter inherit the same blind spot.
4. Don't claim n8n can replace a UI. If the input has a React SPA / admin dashboard / interactive console, n8n cannot host that natively. Use the frontend portability decision tree (Step 4 below) and document the choice honestly in the SDD.
5. Preserve fidelity. If the upstream has "10 default tasks" / "14 dropdown choices" / "5 reminder offsets", the port keeps those exactly — and PROVENANCE.md maps each preserved item to the upstream line number, pinned to a specific commit SHA.
6. Always validate before declaring done. Run the 3-layer funnel (Step 6 below) — especially the local n8n REST import. Lint passing alone is not enough.
7. Tag local imports. Any workflow imported into the user's local n8n must carry [Claude YYYY-MM-DD] name prefix + claude-import-YYYY-MM-DD tag + active: false. See the memory note n8n-local-import-marking.
8. Security review is a real gate, not a caption. Run n8n-security-governance during Step 1.5. Record evidence, severity, status, owner, target version, and a PASS / CONDITIONAL / BLOCKED decision.
9. Every release must be traceable and reversible. The reviewed workflow JSON, SDD, security artifacts, tests, Git commit SHA, workflow internal version, n8n release tag, and rollback target must describe the same release.

The 7-step methodology

Step 1 — Source inventory

Read the upstream repo and list:

Step 1.5 — Security audit (mandatory before any "enterprise" claim)

Run n8n-security-governance for the full security, version-control, CI/CD, and rollback gate. Most AI-coded POCs ship with severe auth / injection holes that you MUST detect before you tell the user the port is deployable. Minimum checklist:

If any check fails and you do not fix it, you MUST publish a SECURITY-CAVEATS.md-style file in the example folder with: the file/line of each issue, repro instructions, the correct fix pattern, and a "DO NOT DEPLOY AS-IS" banner in the README. The on-prem LINE CS case in this pack is the template — read it before doing your own audit so you know what the artifact looks like.

If you do fix something the upstream had wrong, the patches must show up in your CREDITS.md as your contribution, separate from the upstream's design.

For a small repo (<2000 lines) this fits in one Python snippet:

pythonCopy code
import json, glob, re
for f in sorted(glob.glob("src/**/*.*", recursive=True)):
    body = open(f, encoding="utf-8", errors="ignore").read()
    entries = re.findall(r"(app|router)\.(get|post|put|delete)\(['\"]([^'\"]+)", body)
    fetches = re.findall(r"fetch\(['\"]([^'\"]+)", body)
    if entries or fetches:
        print(f, "::", entries, "::", fetches[:3])

Output: a markdown table that becomes the basis of docs/field-mapping.md.

Step 2 — Partition decision (the rubric)

For each piece of logic, decide one of three fates:

Write the decisions into the SDD before opening n8n. Don't decide on the canvas.

Step 3 — Architecture: core + entry pattern

For systems with one logical "do the work" path that may be triggered by multiple sources (LINE webhook today, WhatsApp tomorrow, Telegram next quarter, CLI for testing), split:

Copy code
[Entry / LINE]      ←┐
[Entry / WhatsApp]  ←┼→  [Core / Message Router]  → [shared business logic]
[Entry / Web Form]  ←┘

• Entries are thin adapters: they receive the platform-specific payload, verify signature, respond fast (2xx within the platform's timeout), normalize the message into {userId, text, eventId, replyToken, channel}, and call the core via Execute Workflow.
• Core is the heavy logic, invoked by Execute Workflow Trigger. It does dedup, state, AI calls, side effects, reply dispatch. The core does not know which channel it came from.

This is proven in both LINE CS examples (cloud + on-prem). Adding a new channel is one new entry workflow, zero changes to the core. The Google Workspace example used the same core + entry split: 2 core sub-workflows × 4 entries (Form Trigger × 2 + Google Forms webhook × 2).

Step 4 — Frontend portability decision tree

n8n is not a web framework. If the upstream has a SPA / admin dashboard / interactive console, pick one of three paths and document it:

Document the choice explicitly in FRONTEND-SDD.md or the main SDD.md, including which UI features didn't survive (e.g., conversation history needs a messages DB table the on-prem version has but the cloud one didn't).

Step 5 — Workflow design (native first)

Build the workflow with n8n native nodes by default, HTTP Request only when the native node doesn't expose what you need. The sibling skill n8n-code-to-native has the in-place rubric. Three places it's legitimate to fall back to HTTP Request:

1. Operations the native node literally doesn't support (e.g., setDataValidation for Google Sheets dropdowns, paragraph styles for Google Docs headings, batchUpdate-only formats).
2. APIs with no native n8n node at all (LINE Messaging API, Google Gemini at the moment).
3. Multi-resource batch operations where the native node would require 5+ chained nodes when 1 HTTP call does the same.

Mark every HTTP fallback with a 🟡 sticky note explaining why — it's the difference between "I lazily reached for HTTP" and "this is the only correct path." The Google Workspace example has 3 sticky-noted HTTP fallbacks; everything else is native.

Step 6 — 3-layer validation funnel

Copy code
Layer 1  ──  Static lint (JSON structure, JS in Code nodes parses, expression syntax, IF-operator
            sanitisation, Gmail required fields, connections, orphan check)
            └─ _audit.mjs                                                          ✅ Tier
Layer 2  ──  Local n8n REST import roundtrip — POST each workflow to /api/v1/workflows;
            n8n's own schema validator runs; DELETE on success
            └─ _n8n_import_test.mjs                                                ✅ Tier
Layer 3  ──  Live execution — real credentials, real LINE/Supabase/AI; run all the
            test cases listed in the SDD
            └─ Manual (you can prep the script; user runs it)                      🟡 Tier (needs creds)

Copy _audit.mjs and _n8n_import_test.mjs from any existing example. Update ALLOWED_NODE_TYPES if you introduce a new node type (e.g., n8n-nodes-base.supabase, n8n-nodes-base.crypto).

Do not declare done until Layer 1 + 2 both pass 0/0. Mention explicitly in the README that Layer 3 is pending user credentials.

Step 7 — Documentation outputs (the recipe)

Every Code2n8n port ships with these documents. They are not optional — they are the deliverable.

Every preserved data item (subfolder names, sheet headers, default rows, dropdown choices) goes into PROVENANCE.md with the upstream line number, pinned to a specific commit SHA. This is the difference between "we ported it" and "we ported it and can prove it."

Real-world gotchas catalogue

Every Code2n8n port has encountered some subset of these. Check them off as you go.

Network / deployment

Node / build

LINE / messaging

Google Workspace

AI / RAG

Companion skills

This skill is the orchestrator. Lean on these siblings when their specific domain comes up:

• n8n-code-to-native — once the Code → Workflow translation produces Code nodes inside the n8n workflow, run this skill to declarativise them where it's safe and helpful
• sticky-note-to-workflow — for the rare case where the input is intent (not code), use this instead
• tigerai-enterprise-patterns — for the governance overlay (login, audit trail, version, handover, cross-system) once the workflow exists
• n8n-api-bridge — for the REST-only path: import / validate / activate / list / delete workflows programmatically (used by the _n8n_import_test.mjs Layer 2 validation)

Closing line

AI Coding solves "how is the function built"; Code2n8n (this skill) solves "how is the capability modularised"; n8n solves "how the modules cooperate across the whole enterprise."

Read CODE2N8N.md for the full thesis.