@domain-first/project-structure 7.1.1 → 8.0.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +128 -25
- package/dist/201.js +146 -342
- package/dist/287.js +1304 -568
- package/dist/561.js +518 -0
- package/dist/711.js +22 -0
- package/dist/870.js +438 -0
- package/dist/agent-cli.d.ts +378 -0
- package/dist/agent-cli.spec.d.ts +1 -0
- package/dist/agent-identifiers.d.ts +4 -0
- package/dist/agent-requests.d.ts +488 -0
- package/dist/backend-module-move.d.ts +1 -0
- package/dist/config-file.d.ts +231 -26
- package/dist/config-file.spec.d.ts +1 -0
- package/dist/context-dependencies.d.ts +16 -0
- package/dist/dependency-rules.d.ts +17 -17
- package/dist/file-system.d.ts +10 -1
- package/dist/implementation-choices.d.ts +8 -0
- package/dist/implementation-choices.spec.d.ts +1 -0
- package/dist/implementation-options-schema.d.ts +14 -0
- package/dist/implementations.d.ts +48 -0
- package/dist/index.cjs +3768 -574
- package/dist/index.js +25 -9
- package/dist/init.cjs +717 -122
- package/dist/init.js +24 -12
- package/dist/integration.cjs +3737 -186
- package/dist/integration.js +29 -17
- package/dist/integrations/rest-endpoint-generator.d.ts +4 -2
- package/dist/integrations/storybook.d.ts +1 -0
- package/dist/interaction.d.ts +41 -0
- package/dist/lint.cjs +173 -46
- package/dist/lint.js +22 -7
- package/dist/next-app.d.ts +7 -0
- package/dist/react.cjs +5128 -414
- package/dist/react.js +72 -60
- package/dist/system-implementations.d.ts +6 -0
- package/dist/upgrade-steps.d.ts +81 -0
- package/dist/upgrade-steps.spec.d.ts +1 -0
- package/dist/upgrade.cjs +593 -0
- package/dist/upgrade.d.ts +2 -0
- package/dist/upgrade.js +235 -0
- package/dist/use-cases/add-integration.d.ts +16 -1
- package/dist/use-cases/cross-context-dependencies.spec.d.ts +1 -0
- package/dist/use-cases/index.d.ts +1 -0
- package/dist/use-cases/initialize.d.ts +4 -4
- package/dist/use-cases/initialize.spec.d.ts +1 -0
- package/dist/use-cases/prompt-implementation-type.d.ts +20 -0
- package/dist/use-cases/scaffold-new-aggregate.d.ts +1 -1
- package/dist/use-cases/scaffold-new-implementation.d.ts +6 -0
- package/dist/use-cases/scaffold-new-implementation.spec.d.ts +1 -0
- package/dist/use-cases/scaffold-react-page.d.ts +3 -1
- package/dist/use-cases/wire-dependency.d.ts +5 -0
- package/dist/wire-branches.d.ts +26 -0
- package/dist/wiring.d.ts +24 -2
- package/package.json +3 -2
- package/skills/df-ps-implement/SKILL.md +9 -8
- package/skills/df-ps-plan-feature/SKILL.md +8 -7
- package/skills/df-ps-react/SKILL.md +13 -7
- package/skills/df-ps-react/references/generators.md +6 -2
- package/skills/df-ps-scaffold/SKILL.md +31 -19
- package/skills/df-ps-scaffold/references/agent-mode.md +72 -0
- package/skills/df-ps-scaffold/references/agent-operations.md +155 -0
- package/skills/df-ps-scaffold/references/choosing-components.md +14 -13
- package/skills/df-ps-scaffold/references/generators.md +20 -3
- package/skills/df-ps-scaffold/references/units/aggregate.md +4 -3
- package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
- package/skills/df-ps-scaffold/references/units/command-query.md +12 -12
- package/skills/df-ps-scaffold/references/units/implementation.md +20 -0
- package/skills/df-ps-scaffold/references/units/move-or-rename.md +1 -1
- package/skills/df-ps-scaffold/references/units/port.md +7 -4
- package/skills/df-ps-scaffold/references/units/use-case.md +1 -1
- package/skills/df-ps-scaffold/scripts/drive.mjs +9 -1
package/README.md
CHANGED
|
@@ -27,31 +27,95 @@ The full technical specification lives in [API.md](./API.md).
|
|
|
27
27
|
|
|
28
28
|
## Guide
|
|
29
29
|
|
|
30
|
-
###
|
|
30
|
+
### Non-interactive mode for agents
|
|
31
31
|
|
|
32
|
-
|
|
32
|
+
`df-scaffold`, `df-react` and `df-integration` accept JSON requests. Humans can keep using the interactive menus. Agents can discover schemas and project IDs first:
|
|
33
33
|
|
|
34
|
+
```bash
|
|
35
|
+
npx df-scaffold --describe
|
|
36
|
+
npx df-scaffold --request '{"operation":"query","context":"sales","name":"orders","implementation":{"type":"prisma","save":false},"dependencies":{"PrismaOrdersQuery":["shared-kernel:PrismaInfrastructureService"]}}'
|
|
37
|
+
npx df-react --request '{"operation":"widget","name":"admin/orders","widgetType":"separated"}'
|
|
38
|
+
npx df-integration --request '{"operation":"add","integrations":["storybook"]}'
|
|
34
39
|
```
|
|
40
|
+
|
|
41
|
+
`--request -` reads JSON from stdin. `dryRun: true` previews changes without writing; `overwrite: true` explicitly allows replacing changed existing generated files. Responses are JSON with file lists, next steps and diagnostics. Errors return `ok: false` and a nonzero exit code without falling back to prompts; invalid requests discard staged changes. Initialization stays with the human through `df-init`.
|
|
42
|
+
|
|
43
|
+
The [API reference](API.md#non-interactive-json-mode) describes request fields, discovery IDs and result semantics.
|
|
44
|
+
|
|
45
|
+
### How to initialize a project
|
|
46
|
+
|
|
47
|
+
Run `df-init` in a project with a `package.json`. Setup visits **Project → Backend → Frontend** in order. Each section asks whether to configure it now: answer No to configure it later. Skipping Project keeps the source folder `src`; skipping Backend or Frontend leaves that section absent.
|
|
48
|
+
|
|
49
|
+
```bash
|
|
35
50
|
npx df-init
|
|
51
|
+
# Return to one section later:
|
|
52
|
+
npx df-init --section backend
|
|
53
|
+
npx df-init --section frontend
|
|
36
54
|
```
|
|
37
55
|
|
|
56
|
+
Project asks for the source folder. Backend asks for the `@domain-first` packages, the [`envBranchedWire` branches](#how-to-switch-implementations) with `wire`, shared in-memory DB and testing library, then adds the required Shared Kernel files. With `@domain-first/handlers-rest`, it adds the [endpoint generator](#how-to-add-a-rest-endpoint). Frontend offers **React** or **Next.js**, then Storybook. Enabling Storybook runs the existing React + Vite integration: it creates `.storybook` configs, package scripts and the build-output `.gitignore` entry. Selecting Next.js with a configured backend asks **Use @domain-first/handlers-next for REST endpoints** once. Yes adds `handlers-rest` to the backend packages if needed, connects `nextAdapter` and creates the catch-all route. This works before `next` is installed. With backend deferred, REST setup waits until backend configuration. Missing packages are printed as an install command; nothing is installed automatically.
|
|
57
|
+
|
|
58
|
+
All settings and saved implementation types live in `domain-first.project-structure.config.json`:
|
|
59
|
+
|
|
38
60
|
```json
|
|
39
61
|
{
|
|
40
|
-
"rootFolder": "src",
|
|
41
|
-
"
|
|
42
|
-
"@domain-first/
|
|
43
|
-
"
|
|
44
|
-
"
|
|
45
|
-
"
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
62
|
+
"project": { "rootFolder": "src" },
|
|
63
|
+
"backend": {
|
|
64
|
+
"domainFirstPackages": ["@domain-first/wire", "@domain-first/handlers"],
|
|
65
|
+
"withInMemoryDb": true,
|
|
66
|
+
"testingLibrary": "vitest",
|
|
67
|
+
"implementations": {
|
|
68
|
+
"repositories": { "primary": ["prisma", "mongo"], "test": ["stub"] },
|
|
69
|
+
"commands": { "primary": ["sql"], "test": [] },
|
|
70
|
+
"queries": { "primary": ["elastic"], "test": ["fake"] },
|
|
71
|
+
"ports": { "primary": ["s3"], "test": [] }
|
|
72
|
+
},
|
|
73
|
+
"rules": {
|
|
74
|
+
"dependencies": {
|
|
75
|
+
"domain-services": ["domain-services"],
|
|
76
|
+
"repositories": ["domain-services", "application-ports", "infrastructure-services"],
|
|
77
|
+
"application-ports": ["repositories", "domain-services", "application-ports", "infrastructure-services"],
|
|
78
|
+
"application-services": ["repositories", "domain-services", "application-ports", "commands", "queries"],
|
|
79
|
+
"use-cases": ["repositories", "domain-services", "application-ports", "application-services", "commands", "queries"],
|
|
80
|
+
"commands": ["infrastructure-services"],
|
|
81
|
+
"queries": ["infrastructure-services"],
|
|
82
|
+
"infrastructure-services": ["repositories", "domain-services", "application-ports", "infrastructure-services"],
|
|
83
|
+
"presentation-services": ["application-ports", "application-services", "use-cases", "commands", "queries", "presentation-services"]
|
|
84
|
+
},
|
|
85
|
+
"lint": {
|
|
86
|
+
"context-isolation": true,
|
|
87
|
+
"shared-kernel": true,
|
|
88
|
+
"layers": true,
|
|
89
|
+
"dependencies": true,
|
|
90
|
+
"react": true,
|
|
91
|
+
"clock": true
|
|
92
|
+
}
|
|
93
|
+
}
|
|
94
|
+
},
|
|
95
|
+
"frontend": {
|
|
96
|
+
"react": { "framework": "react", "storybookFramework": "@storybook/react-vite" }
|
|
97
|
+
}
|
|
51
98
|
}
|
|
52
99
|
```
|
|
53
100
|
|
|
54
|
-
Commit the config to share it with your team. `df-init`
|
|
101
|
+
Commit the config to share it with your team. Rerunning `df-init` offers **Project**, **Backend**, **Frontend** and **All sections**, using current values as defaults. A single-section update keeps the other sections and saved choices. Backend setup writes all standard dependency lists and enabled lint checks into `backend.rules`, so they can be edited directly. On reconfiguration, only missing rules are filled; existing lists, `add`/`remove` patches and disabled checks are preserved. Backend setup preserves existing support files and restores missing ones. Changing the source folder affects future generation; existing source is not moved. React is enabled by the presence of `frontend.react`; its `framework` is `react` or `next`, so Next.js uses the same React generators. Frontend selection is prefilled from the saved value, falling back to Next.js when `next` is declared in `package.json`. Both choices use `@storybook/react-vite` from the Storybook integration; there is no separate Storybook framework prompt. Framework settings remain grouped under `frontend.<framework>`.
|
|
102
|
+
|
|
103
|
+
A config of an earlier major version is not read: commands stop and ask you to run [`df-upgrade`](#how-to-upgrade-to-a-new-major-version). An absent backend or React section produces a message pointing to the corresponding `df-init --section` command. Initialization and configuration are performed by the project owner; agent skills only read these settings and ask the owner to configure missing sections.
|
|
104
|
+
|
|
105
|
+
### Saved implementation types
|
|
106
|
+
|
|
107
|
+
Repository, command, query and port generators offer a menu of implementation types. **Enter implementation type and save for future use** accepts a new kebab-case name and saves it under `backend.implementations` in the shared config. **Enter implementation type for this run only** generates code without adding a saved choice. Both actions apply to primary and test implementations, including additions to existing contracts.
|
|
108
|
+
|
|
109
|
+
Each category and its primary/test choices are separate and shared by all contexts in the project. Ordinary types such as `api` and `mock` are not presets: enter them manually or save them for later. Menus contain saved choices, available system implementations and the two manual-entry actions.
|
|
110
|
+
|
|
111
|
+
System implementations are marked explicitly:
|
|
112
|
+
|
|
113
|
+
- **System: cross-context (calls handlers in another bounded context)** — port adapters, only when another bounded context exists.
|
|
114
|
+
- **System: in-memory (uses the shared in-memory database)** — repositories, commands and queries, only when the shared in-memory DB integration is enabled and its files are ready.
|
|
115
|
+
|
|
116
|
+
The first available saved type is selected by default, then an available system type; otherwise the save-entry action is selected and its name input is empty. Adding an implementation to an existing contract shows both primary and test choices. With the save action, ordinary types are remembered according to their selected environments; the run-only action never registers them.
|
|
117
|
+
|
|
118
|
+
Updates to `backend.implementations` preserve all other config sections and are saved together with generated files; cancellation discards both. Prisma integration adds `prisma` to repository, command and query choices. There is no global persistence-default setting.
|
|
55
119
|
|
|
56
120
|
### How to create a bounded context
|
|
57
121
|
|
|
@@ -114,9 +178,11 @@ export const wireOrderRepository = envBranchedWire({
|
|
|
114
178
|
|
|
115
179
|
Tests get the test implementation, everything else gets the primary one.
|
|
116
180
|
|
|
181
|
+
Your environments may differ: choose **Custom branches** during backend setup and enter them, e.g. `local, staging, production`, then pick the test branch, let `df-init` add `test`, or go without one: then every branch gets the primary implementation and no test implementations are asked for. Generated wires use these branches. How the current branch is chosen is yours: `env-branched-wire.ts` gets an empty `currentBranch` function that doesn't compile until you write it.
|
|
182
|
+
|
|
117
183
|
### How to wire dependencies
|
|
118
184
|
|
|
119
|
-
As the last step, generators with wiring offer the modules the new one may depend on, from the same bounded context and the Shared Kernel. Each choice is added to the factory and to the constructor:
|
|
185
|
+
As the last step, generators with wiring offer the modules the new one may depend on, from the same bounded context and the Shared Kernel. Cross-context port adapters also see the application handlers of neighboring contexts. Each choice is added to the factory and to the constructor:
|
|
120
186
|
|
|
121
187
|
```ts
|
|
122
188
|
export class PlaceOrderUseCase {
|
|
@@ -130,9 +196,13 @@ export const wirePlaceOrderUseCase = wireClass(PlaceOrderUseCase, [
|
|
|
130
196
|
|
|
131
197
|
Only the dependencies that respect the layers are offered: a use case can't take another use case, the domain can't take the application. To add a dependency later, choose **Wire dependency** in the context menu.
|
|
132
198
|
|
|
199
|
+
### How to add an implementation
|
|
200
|
+
|
|
201
|
+
Choose **Infrastructure → New Implementation** to give an existing repository, command, query or port one more implementation, say a `local` adapter of a `FileStorage` port next to `s3` and `in-memory`. With `wire`, pick the environments that use it: `test` stays on `in-memory`, `development` moves to `local`, `production` stays on `s3`.
|
|
202
|
+
|
|
133
203
|
### How to move or rename a module
|
|
134
204
|
|
|
135
|
-
Choose **Move or rename** in the context menu: rename an aggregate, entity, value object, service, port, query, command or use case, move it to another bounded context or to the Shared Kernel, or move an entity in or out of an aggregate. Its files, implementations, wire, specs and every import and derived name in the project follow it: `OrderRepository`, `PrismaOrderRepository`, `wireOrderRepository`, the `orderRepository` parameter of a use case, the in-memory DB section. A move that would
|
|
205
|
+
Choose **Move or rename** in the context menu: rename an aggregate, entity, value object, service, port, query, command or use case, move it to another bounded context or to the Shared Kernel, or move an entity in or out of an aggregate. Its files, implementations, wire, specs and every import and derived name in the project follow it: `OrderRepository`, `PrismaOrderRepository`, `wireOrderRepository`, the `orderRepository` parameter of a use case, the in-memory DB section. A move that would introduce a forbidden import between contexts is refused, with the list of imports that would cross the boundary.
|
|
136
206
|
|
|
137
207
|
### How to add errors
|
|
138
208
|
|
|
@@ -146,7 +216,15 @@ Names don't repeat the context: an error of the `payment` namespace in `sales` i
|
|
|
146
216
|
|
|
147
217
|
### How to share code between contexts
|
|
148
218
|
|
|
149
|
-
|
|
219
|
+
Keep each context's domain and application models local. For another context's data or behavior, create an **application port** in the consuming context (**Application → New Port**) and choose **System: cross-context (calls handlers in another bounded context)** for its adapter. No transport or endpoint is required.
|
|
220
|
+
|
|
221
|
+
Port adapter menus contain saved port types and both manual-entry actions, plus **System: cross-context (calls handlers in another bounded context)** when another bounded context exists. There are no automatic `api`, `mock` or `in-memory` port choices. Saved primary and test port types remain separate; adding another adapter shows both lists. Choices from repositories, commands and queries are not added to port menus.
|
|
222
|
+
|
|
223
|
+
With `wire`, **Dependencies for CrossContext…** and **Wire dependency** offer queries, commands and use cases from every neighboring context, labelled with their context, such as `InvoiceQuery (billing)`. The CLI injects each handler into the adapter and imports its factory in wiring. Names include the context to avoid collisions: `BillingInvoiceQuery`, `wireBillingInvoiceQuery`.
|
|
224
|
+
|
|
225
|
+
Define the capability's methods in your port and implement them in the adapter: map your input, call the injected handler, and map its result and errors to your own models. Keep a separate `mock` or `stub` test adapter so tests do not run the neighboring context. Without `wire`, inject the handlers through the constructor and compose them in wiring yourself.
|
|
226
|
+
|
|
227
|
+
Only port adapters under `infrastructure/application-adapters/cross-context/` may import neighboring handlers. Wiring may inject them only into those adapters; query/command implementations and other adapter types remain isolated. The `cross-context` type is unavailable for Shared Kernel ports. Shared universal models, technical ports and services belong in the **Shared Kernel** (`src/shared-kernel`).
|
|
150
228
|
|
|
151
229
|
### How to add a REST endpoint
|
|
152
230
|
|
|
@@ -179,12 +257,14 @@ With wiring, the endpoint takes the generator and a handler you pick from the co
|
|
|
179
257
|
|
|
180
258
|
### How to scaffold React modules
|
|
181
259
|
|
|
182
|
-
With `
|
|
260
|
+
With `frontend.react` configured, run `npx df-react`: pages, widgets (monolithic, with separated UI, or headless), UI-kit components with Storybook stories, and shared hooks. Names may include folders:
|
|
183
261
|
|
|
184
262
|
```text
|
|
185
263
|
admin/panel/users → pages/admin/panel/admin-panel-users-page.tsx (AdminPanelUsersPage)
|
|
186
264
|
```
|
|
187
265
|
|
|
266
|
+
With Next.js, a new page also gets its App Router route, `app/admin/panel/users/page.tsx`, which renders `AdminPanelUsersPage`. An existing route is never overwritten.
|
|
267
|
+
|
|
188
268
|
**Move or rename page** and **Move or rename widget** move the files and update every import in the project.
|
|
189
269
|
|
|
190
270
|
### How to add tooling
|
|
@@ -199,25 +279,48 @@ The endpoint generator and the in-memory DB are what `df-init` scaffolds; as int
|
|
|
199
279
|
npx df-lint
|
|
200
280
|
```
|
|
201
281
|
|
|
202
|
-
It reports what breaks the Domain-First rules: imports between bounded contexts, imports against the layers, modules using kinds the dependency rules don't allow (in imports and in wiring), React modules importing what they shouldn't, and reading the time without the clock port. It exits with 1 when something is found, so you can run it in CI.
|
|
282
|
+
It reports what breaks the Domain-First rules: forbidden imports between bounded contexts, imports against the layers, modules using kinds the dependency rules don't allow (in imports and in wiring), React modules importing what they shouldn't, and reading the time without the clock port. It exits with 1 when something is found, so you can run it in CI.
|
|
203
283
|
|
|
204
|
-
|
|
284
|
+
`df-init` scaffolds all standard rules into `backend.rules` during backend setup. Teams can edit these entries directly: what each kind of module may depend on (`backend.rules.dependencies`) and which checks run (`backend.rules.lint`). `df-scaffold` offers dependencies by the same rules. For older or manually shortened configs without `backend.rules`, the defaults apply and every check runs; kinds and checks you don't mention keep their defaults.
|
|
205
285
|
|
|
206
|
-
- Kinds in `rules.dependencies` (as keys and in lists): `repositories`, `domain-services`, `application-ports`, `application-services`, `use-cases`, `commands`, `queries`, `infrastructure-services`, `presentation-services`.
|
|
286
|
+
- Kinds in `backend.rules.dependencies` (as keys and in lists): `repositories`, `domain-services`, `application-ports`, `application-services`, `use-cases`, `commands`, `queries`, `infrastructure-services`, `presentation-services`.
|
|
207
287
|
- A kind's value: a list that replaces its defaults, or `{ "add": [...], "remove": [...] }`.
|
|
208
|
-
- Checks in `rules.lint`: `context-isolation`, `shared-kernel`, `layers`, `dependencies`, `react`, `clock`.
|
|
288
|
+
- Checks in `backend.rules.lint`: `context-isolation`, `shared-kernel`, `layers`, `dependencies`, `react`, `clock`.
|
|
209
289
|
|
|
210
290
|
Defaults and details: [Dependency rules](API.md#dependency-rules), [`df-lint`](API.md#df-lint).
|
|
211
291
|
|
|
212
292
|
```json
|
|
213
293
|
{
|
|
214
|
-
"
|
|
215
|
-
"
|
|
216
|
-
|
|
294
|
+
"backend": {
|
|
295
|
+
"rules": {
|
|
296
|
+
"dependencies": {
|
|
297
|
+
"use-cases": {
|
|
298
|
+
"add": [
|
|
299
|
+
"use-cases"
|
|
300
|
+
]
|
|
301
|
+
}
|
|
302
|
+
},
|
|
303
|
+
"lint": {
|
|
304
|
+
"clock": false
|
|
305
|
+
}
|
|
306
|
+
}
|
|
217
307
|
}
|
|
218
308
|
}
|
|
219
309
|
```
|
|
220
310
|
|
|
311
|
+
### How to upgrade to a new major version
|
|
312
|
+
|
|
313
|
+
After upgrading the package to a new major version, run:
|
|
314
|
+
|
|
315
|
+
```bash
|
|
316
|
+
npx df-upgrade --dry-run # review the plan
|
|
317
|
+
npx df-upgrade
|
|
318
|
+
```
|
|
319
|
+
|
|
320
|
+
It finds what the project needs, shows every change and applies them together after one confirmation; `--yes` skips the question. Until then, the other commands, `df-lint` included, stop with `run npx df-upgrade`. Running it again prints `Everything is up to date.`
|
|
321
|
+
|
|
322
|
+
From 7.x it splits the config into `project`, `backend` and `frontend`, records `frontend.react.framework` explicitly (`next` when `next` is in `package.json`, otherwise `react`), and moves `defaultPersistenceLayerImplementation` to the first saved primary type of repositories, commands and queries. Then update the agent skills with `npx df-skills`.
|
|
323
|
+
|
|
221
324
|
### How to teach your coding agent
|
|
222
325
|
|
|
223
326
|
The package ships skills that teach coding agents to plan features, scaffold with `df-scaffold`, build the React part with `df-react` and implement the generated code.
|