| Dimension | Shared | Only in A | Only in B | Overlap |
|---|---|---|---|---|
| Sections | 0 | 3 | 5 | 0% |
| Commands | 0 | 2 | 0 | 0% |
| Section tags | 0 | 1 | 2 | 0% |
What each file covers
Sections
0 shared · 3 only in A · 5 only in B- − AGENTS.md
- − TypeORM boundary
- − Transactions
- + .github Quick Reference
- + Key Files
- + Workflow Naming
- + Common Tasks
- + Reference
Commands
0 shared · 2 only in A · 0 only in B- − eslint.config.mjs
- − eslint-disable
Section tags
0 shared · 1 only in A · 2 only in B- − lint-format
- + code-style
- + agent-behaviour
Line diff
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
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
@@ −1 +1 @@
1−# AGENTS.md
1+@../AGENTS.md
22
3−Guidance specific to the `cli` package. See the root [AGENTS.md](../../AGENTS.md)
4−for repo-wide conventions.
3+## .github Quick Reference
54
6−## TypeORM boundary
5+This folder contains n8n's GitHub Actions infrastructure.
76
8−TypeORM belongs in the **persistence layer**, not in business logic.
7+### Key Files
98
10−**Allowed to import `@n8n/typeorm`** — entity and repository files, including the
11−ones co-located inside `src/modules/**`:
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 |
1217
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)
18+### Workflow Naming
1719
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).
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 |
2128
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.
29+Reusable workflows: add `-reusable` or `-callable` suffix.
3330
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:
31+### Common Tasks
3832
39−- `src/commands/db/revert.ts` — `MigrationExecutor` (CLI migration tooling)
40−- `src/security-audit/security-audit.repository.ts` — `PackagesRepository`
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.
4139
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.
40+**Add script:** Create `.mjs` in `scripts/`, document in `WORKFLOWS.md`
4941
50−## Transactions
42+### Reference
5143
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.
44+See `WORKFLOWS.md` for:
45+- Architecture diagrams
46+- Workflow call graph
47+- Scheduled jobs & triggers
48+- Runners & secrets
6549
