CLAUDE.md

1# n8n-packages module — Agent Guidelines
2 
3This module powers package **import/export** (`.n8np`). The feature is
4**public-API-first; the CLI wraps the API.** A single import/export option
5therefore lives in up to four layers across three packages.
6 
7## ⚠️ Propagate new properties through every layer
8 
9**When you add, rename, or remove a property on the import or export request,
10carry it through all four layers below.** A property that stops at the module
11is invisible to public-API and CLI users — and an out-of-date OpenAPI spec or
12CLI flag is a silent bug, not a compile error.
13 
14```mermaid
15flowchart LR
16  M["1. Module<br/>(this package)"] --> D["2. DTO<br/>@n8n/api-types"]
17  D --> A["3. Public API<br/>handler + OpenAPI spec"]
18  A --> C["4. CLI<br/>@n8n/cli"]
19```
20 
21### Importer rules
22- Importers **plan and decide**; they must never touch a repository directly. All persistence and
23  lookups go through a **service**.
24- Prefer an **existing** domain service from the main n8n codebase (`FolderService`, `ProjectService`,
25  `WorkflowService`, …). When the importer needs a capability the service lacks — reusing a source id,
26  or a fetch-by-ids for matching — **extend that existing service with a general method** rather than
27  reaching for the repository or spinning up an import-only service. Canonical examples:
28  `ProjectService.createTeamProject(data, overrides)` (preset id + description) and
29  `FolderService.createFolder(dto, projectId, id?)` / `FolderService.getFoldersByIds(ids)`.
30- `N8nPackagesService.importPackage` is a thin **dispatcher**: it builds the reader, reads the manifest,
31  and delegates to a per-package-shape importer. Shapes mirror export's mutual exclusivity — a **project
32  package** (projects defined by the package) → `ProjectPackageImporter`, or a **workflow package** (loose
33  workflows + their folder shells + credential deps into a target project) → `WorkflowPackageImporter`.
34- `WorkflowPackageImporter` resolves the target scope from the request, then delegates the plan/gate/apply
35  work to `ImportOrchestrator` (brings folders + workflows + credential deps into one project scope).
36  `ProjectPackageImporter` creates the project shells, then reuses `ImportOrchestrator` per project to
37  bring each one's own folders + workflows + credential deps into scope. Don't split folder vs workflow:
38  they share target resolution, credential resolution, and publishing.
39 
40### Adding an IMPORT property
41 
421. **Module** (here)
43   - `n8n-packages.types.ts` — add the field to `ImportPackageRequest`
44     (or `ImportWorkflowProperties` / `ImportCredentialProperties`). For a new
45     enum, add a `XxxPolicy` / `XxxMode` const **and** its derived type
46     (follow `WorkflowIdPolicy`). New single-value modes are RFC seams — keep
47     the function-table convention (`workflow-conflict-policy.ts` etc.), don't
48     add handler classes for pure logic.
49   - Implement the behaviour (e.g. `entities/workflow/workflow-importer.ts`)
50     and thread it through `n8n-packages.service.ts` `importPackage`.
512. **DTO** — `@n8n/api-types/src/dto/packages/import-package-request.dto.ts`
52   - Add the field to `ImportPackageRequestDto` (zod), **and** add its name to
53     `IMPORT_PACKAGE_REQUEST_FORM_FIELDS` (multipart text fields).
54   - Update `__tests__/import-package-request.dto.test.ts`.
553. **Public API** — `packages/cli/src/public-api/v1/handlers/n8n-packages/`
56   - `n8n-packages.handler.ts` — pass `payload.data.<field>` into the service.
57   - `spec/paths/n8n-packages.import.yml` — add the property to the inline
58     `multipart/form-data` request schema (type/enum/description; update
59     `required` if needed). **Easy to forget — the spec is hand-written.**
604. **CLI** — `packages/@n8n/cli/`
61   - `src/client.ts` — add to `ImportPackageFields`.
62   - `src/commands/package/import.ts` — add a `Flags.string({...})` (with a
63     kebab-case alias) and pass it into `client.importPackage(...)`.
64   - `docs/commands/package.md` + the `README.md` flag table.
65 
66### Adding an EXPORT property
67 
681. **Module** — `n8n-packages.types.ts` `ExportPackageRequest`; implement in
69   `n8n-packages.service.ts` `exportPackage` (+ `io/` writer or
70   `entities/*/` exporter as needed).
712. **DTO** — `@n8n/api-types/src/dto/packages/export-package-request.dto.ts`
72   (`ExportPackageRequestDto`, zod).
733. **Public API** — `n8n-packages.handler.ts` `exportPackage` reads from
74   `payload.data`; update the **separate** schema file
75   `spec/schemas/exportPackageRequest.yml` (export's request schema is a
76   `$ref`, unlike import's inline schema).
774. **CLI** — `src/client.ts` `exportPackage(...)`,
78   `src/commands/package/export.ts` flag, and the docs/README.
79 
80## Reference: the `workflowIdPolicy` change
81 
82The in-tree addition of `workflowIdPolicy` is the canonical example — it landed
83in the module types + importer, the DTO (+ form-fields list), the handler, and
84the CLI. Grep `workflowIdPolicy` to see every site a new import knob must touch.
85