| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 5 | 3 | 0% |
| Commands | 0 | 0 | 2 | 0% |
| Section tags | 0 | 2 | 1 | 0% |
What each file covers
Sections
0 shared · 5 only in A · 3 only in B- − .github Quick Reference
- − Key Files
- − Workflow Naming
- − Common Tasks
- − Reference
- + AGENTS.md
- + TypeORM boundary
- + Transactions
Commands
0 shared · 0 only in A · 2 only in B- + eslint.config.mjs
- + eslint-disable
Section tags
0 shared · 2 only in A · 1 only in B- − code-style
- − agent-behaviour
- + lint-format
Line diff
n8n-io/n8n · .github/CLAUDE.md
@@ −1 @@
1@../AGENTS.md
2
3## .github Quick Reference
4
5This folder contains n8n's GitHub Actions infrastructure.
6
7### Key Files
8
9| File/Folder | Purpose |
10|-------------|---------|
11| `WORKFLOWS.md` | Complete CI/CD documentation |
12| `DEVELOPING_V3.md` | How to develop v3 features (master + 3.x branch model, opt-in flags) |
13| `workflows/` | GitHub Actions workflows |
14| `actions/` | Reusable composite actions |
15| `scripts/` | Release & Docker automation |
16| `CODEOWNERS` | Team review ownership |
17
18### Workflow Naming
19
20| Prefix | Purpose |
21|--------|---------|
22| `test-` | Testing (unit, E2E, visual) |
23| `ci-` | Continuous integration |
24| `util-` | Utilities (notifications) |
25| `build-` | Build processes |
26| `release-` | Release automation |
27| `sec-` | Security scanning |
28
29Reusable workflows: add `-reusable` or `-callable` suffix.
30
31### Common Tasks
32
33**Add workflow:** Create in `workflows/`, document in `WORKFLOWS.md`.
34Always declare a least-privilege top-level `permissions:` block (usually
35`contents: read`) — without one the workflow runs with the repo's broad
36default token and review flags it. Jobs needing more override at job level;
37a job calling a reusable workflow must grant at least what that workflow
38declares.
39
40**Add script:** Create `.mjs` in `scripts/`, document in `WORKFLOWS.md`
41
42### Reference
43
44See `WORKFLOWS.md` for:
45- Architecture diagrams
46- Workflow call graph
47- Scheduled jobs & triggers
48- Runners & secrets
49
n8n-io/n8n · packages/cli/AGENTS.md
@@ +1 @@
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
@@ −1 +1 @@
1−@../AGENTS.md
1+# AGENTS.md
22
3−## .github Quick Reference
3+Guidance specific to the `cli` package. See the root [AGENTS.md](../../AGENTS.md)
4+for repo-wide conventions.
45
5−This folder contains n8n's GitHub Actions infrastructure.
6+## TypeORM boundary
67
7−### Key Files
8+TypeORM belongs in the **persistence layer**, not in business logic.
89
9−| File/Folder | Purpose |
10−|-------------|---------|
11−| `WORKFLOWS.md` | Complete CI/CD documentation |
12−| `DEVELOPING_V3.md` | How to develop v3 features (master + 3.x branch model, opt-in flags) |
13−| `workflows/` | GitHub Actions workflows |
14−| `actions/` | Reusable composite actions |
15−| `scripts/` | Release & Docker automation |
16−| `CODEOWNERS` | Team review ownership |
10+**Allowed to import `@n8n/typeorm`** — entity and repository files, including the
11+ones co-located inside `src/modules/**`:
1712
18−### Workflow Naming
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)
1917
20−| Prefix | Purpose |
21−|--------|---------|
22−| `test-` | Testing (unit, E2E, visual) |
23−| `ci-` | Continuous integration |
24−| `util-` | Utilities (notifications) |
25−| `build-` | Build processes |
26−| `release-` | Release automation |
27−| `sec-` | Security scanning |
18+These are exempted in `eslint.config.mjs` **by location**, so a genuine `@Entity`
19+or repository class is never flagged — including the few entity files that lack
20+the `.entity.ts` suffix (they live in a `database/entities/` folder).
2821
29−Reusable workflows: add `-reusable` or `-callable` suffix.
22+**Not allowed** — business logic (services, controllers, public-api handlers,
23+commands, factories) must not import `@n8n/typeorm` or `@n8n/typeorm/...`
24+subpaths. The `misplaced-n8n-typeorm-import` lint rule enforces this; a new
25+import — or an inline `eslint-disable` of the rule — fails CI. The same rule also
26+catches the **relabel dodge**: importing a TypeORM operator/driver type (`In`,
27+`Not`, `FindOptionsWhere`, `EntityManager`, …) from `@n8n/db`, which
28+re-exports them from `@n8n/typeorm` — that silences the direct-import check
29+without decoupling anything. Existing leaks of both kinds are tracked in two
30+`files`-scoped allowlists in `eslint.config.mjs` (direct `@n8n/typeorm` imports,
31+and `@n8n/db` relabels) that only ever shrink: never add to them, and never
32+suppress the rule inline.
3033
31−### Common Tasks
34+Distinct from that shrink-only ratchet, two files are **permanently** exempted in
35+`eslint.config.mjs` for legitimate TypeORM use outside the persistence tree —
36+these are sanctioned, not migration targets, so don't try to relocate them or
37+suppress the rule:
3238
33−**Add workflow:** Create in `workflows/`, document in `WORKFLOWS.md`.
34−Always declare a least-privilege top-level `permissions:` block (usually
35−`contents: read`) — without one the workflow runs with the repo's broad
36−default token and review flags it. Jobs needing more override at job level;
37−a job calling a reusable workflow must grant at least what that workflow
38−declares.
39+- `src/commands/db/revert.ts` — `MigrationExecutor` (CLI migration tooling)
40+- `src/security-audit/security-audit.repository.ts` — `PackagesRepository`
3941
40−**Add script:** Create `.mjs` in `scripts/`, document in `WORKFLOWS.md`
42+Need an operator query (`In`, `IsNull`, `FindOptionsWhere`, …)? Add a
43+use-case-named repository method (plain parameters, domain-shaped return) rather
44+than importing the operator into business logic. Relabeling the import to
45+`@n8n/db` is lint-enforced against, not just convention (see above); likewise
46+don't string-match `QueryFailedError` or push `.manager` / `createQueryBuilder`
47+into business logic to dodge the rule. See the root "Persistence layer & the
48+TypeORM boundary" section for the full rationale.
4149
42−### Reference
50+## Transactions
4351
44−See `WORKFLOWS.md` for:
45−- Architecture diagrams
46−- Workflow call graph
47−- Scheduled jobs & triggers
48−- Runners & secrets
52+Three patterns coexist while the persistence layer is migrated — new code uses
53+only the third:
54+
55+1. **`manager.transaction(...)`** — raw TypeORM, leaks the ORM into business
56+ logic. Anti-pattern; being removed.
57+2. **`withTransaction(...)`** (`@n8n/db`) — deprecated helper that still hands an
58+ `EntityManager` to its callback. Removed as call sites migrate.
59+3. **`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+
63+See the root AGENTS.md "Transactions" bullet for the full API and a worked
64+example.
4965
