AGENTS.md

1# AGENTS.md
2 
3Guidance specific to the `cli` package. See the root [AGENTS.md](../../AGENTS.md)
4for repo-wide conventions.
5 
6## TypeORM boundary
7 
8TypeORM belongs in the **persistence layer**, not in business logic.
9 
10**Allowed to import `@n8n/typeorm`** — entity and repository files, including the
11ones co-located inside `src/modules/**`:
12 
13- `src/databases/**`
14- a module's `database/entities/**` and `database/repositories/**`
15- files named `*.entity.ts` or `*.repository.ts` (some modules keep these at the
16  module root)
17 
18These are exempted in `eslint.config.mjs` **by location**, so a genuine `@Entity`
19or repository class is never flagged — including the few entity files that lack
20the `.entity.ts` suffix (they live in a `database/entities/` folder).
21 
22**Not allowed** — business logic (services, controllers, public-api handlers,
23commands, factories) must not import `@n8n/typeorm` or `@n8n/typeorm/...`
24subpaths. The `misplaced-n8n-typeorm-import` lint rule enforces this; a new
25import — or an inline `eslint-disable` of the rule — fails CI. The same rule also
26catches the **relabel dodge**: importing a TypeORM operator/driver type (`In`,
27`Not`, `FindOptionsWhere`, `EntityManager`, …) from `@n8n/db`, which
28re-exports them from `@n8n/typeorm` — that silences the direct-import check
29without decoupling anything. Existing leaks of both kinds are tracked in two
30`files`-scoped allowlists in `eslint.config.mjs` (direct `@n8n/typeorm` imports,
31and `@n8n/db` relabels) that only ever shrink: never add to them, and never
32suppress the rule inline.
33 
34Distinct from that shrink-only ratchet, two files are **permanently** exempted in
35`eslint.config.mjs` for legitimate TypeORM use outside the persistence tree —
36these are sanctioned, not migration targets, so don't try to relocate them or
37suppress the rule:
38 
39- `src/commands/db/revert.ts` — `MigrationExecutor` (CLI migration tooling)
40- `src/security-audit/security-audit.repository.ts` — `PackagesRepository`
41 
42Need an operator query (`In`, `IsNull`, `FindOptionsWhere`, …)? Add a
43use-case-named repository method (plain parameters, domain-shaped return) rather
44than importing the operator into business logic. Relabeling the import to
45`@n8n/db` is lint-enforced against, not just convention (see above); likewise
46don't string-match `QueryFailedError` or push `.manager` / `createQueryBuilder`
47into business logic to dodge the rule. See the root "Persistence layer & the
48TypeORM boundary" section for the full rationale.
49 
50## Transactions
51 
52Three patterns coexist while the persistence layer is migrated — new code uses
53only the third:
54 
551. **`manager.transaction(...)`** — raw TypeORM, leaks the ORM into business
56   logic. Anti-pattern; being removed.
572. **`withTransaction(...)`** (`@n8n/db`) — deprecated helper that still hands an
58   `EntityManager` to its callback. Removed as call sites migrate.
593. **`TransactionRunner.run(ctx, fn)`** (`@n8n/db`) — the target. Inject the
60   `TransactionRunner` port and thread the `OperationContext`; the driver handle
61   never reaches business logic. Use this for new work.
62 
63See the root AGENTS.md "Transactions" bullet for the full API and a worked
64example.
65