@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.
Files changed (71) hide show
  1. package/README.md +128 -25
  2. package/dist/201.js +146 -342
  3. package/dist/287.js +1304 -568
  4. package/dist/561.js +518 -0
  5. package/dist/711.js +22 -0
  6. package/dist/870.js +438 -0
  7. package/dist/agent-cli.d.ts +378 -0
  8. package/dist/agent-cli.spec.d.ts +1 -0
  9. package/dist/agent-identifiers.d.ts +4 -0
  10. package/dist/agent-requests.d.ts +488 -0
  11. package/dist/backend-module-move.d.ts +1 -0
  12. package/dist/config-file.d.ts +231 -26
  13. package/dist/config-file.spec.d.ts +1 -0
  14. package/dist/context-dependencies.d.ts +16 -0
  15. package/dist/dependency-rules.d.ts +17 -17
  16. package/dist/file-system.d.ts +10 -1
  17. package/dist/implementation-choices.d.ts +8 -0
  18. package/dist/implementation-choices.spec.d.ts +1 -0
  19. package/dist/implementation-options-schema.d.ts +14 -0
  20. package/dist/implementations.d.ts +48 -0
  21. package/dist/index.cjs +3768 -574
  22. package/dist/index.js +25 -9
  23. package/dist/init.cjs +717 -122
  24. package/dist/init.js +24 -12
  25. package/dist/integration.cjs +3737 -186
  26. package/dist/integration.js +29 -17
  27. package/dist/integrations/rest-endpoint-generator.d.ts +4 -2
  28. package/dist/integrations/storybook.d.ts +1 -0
  29. package/dist/interaction.d.ts +41 -0
  30. package/dist/lint.cjs +173 -46
  31. package/dist/lint.js +22 -7
  32. package/dist/next-app.d.ts +7 -0
  33. package/dist/react.cjs +5128 -414
  34. package/dist/react.js +72 -60
  35. package/dist/system-implementations.d.ts +6 -0
  36. package/dist/upgrade-steps.d.ts +81 -0
  37. package/dist/upgrade-steps.spec.d.ts +1 -0
  38. package/dist/upgrade.cjs +593 -0
  39. package/dist/upgrade.d.ts +2 -0
  40. package/dist/upgrade.js +235 -0
  41. package/dist/use-cases/add-integration.d.ts +16 -1
  42. package/dist/use-cases/cross-context-dependencies.spec.d.ts +1 -0
  43. package/dist/use-cases/index.d.ts +1 -0
  44. package/dist/use-cases/initialize.d.ts +4 -4
  45. package/dist/use-cases/initialize.spec.d.ts +1 -0
  46. package/dist/use-cases/prompt-implementation-type.d.ts +20 -0
  47. package/dist/use-cases/scaffold-new-aggregate.d.ts +1 -1
  48. package/dist/use-cases/scaffold-new-implementation.d.ts +6 -0
  49. package/dist/use-cases/scaffold-new-implementation.spec.d.ts +1 -0
  50. package/dist/use-cases/scaffold-react-page.d.ts +3 -1
  51. package/dist/use-cases/wire-dependency.d.ts +5 -0
  52. package/dist/wire-branches.d.ts +26 -0
  53. package/dist/wiring.d.ts +24 -2
  54. package/package.json +3 -2
  55. package/skills/df-ps-implement/SKILL.md +9 -8
  56. package/skills/df-ps-plan-feature/SKILL.md +8 -7
  57. package/skills/df-ps-react/SKILL.md +13 -7
  58. package/skills/df-ps-react/references/generators.md +6 -2
  59. package/skills/df-ps-scaffold/SKILL.md +31 -19
  60. package/skills/df-ps-scaffold/references/agent-mode.md +72 -0
  61. package/skills/df-ps-scaffold/references/agent-operations.md +155 -0
  62. package/skills/df-ps-scaffold/references/choosing-components.md +14 -13
  63. package/skills/df-ps-scaffold/references/generators.md +20 -3
  64. package/skills/df-ps-scaffold/references/units/aggregate.md +4 -3
  65. package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
  66. package/skills/df-ps-scaffold/references/units/command-query.md +12 -12
  67. package/skills/df-ps-scaffold/references/units/implementation.md +20 -0
  68. package/skills/df-ps-scaffold/references/units/move-or-rename.md +1 -1
  69. package/skills/df-ps-scaffold/references/units/port.md +7 -4
  70. package/skills/df-ps-scaffold/references/units/use-case.md +1 -1
  71. 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
- ### How to initialize a project
30
+ ### Non-interactive mode for agents
31
31
 
32
- Run `df-init` in a project with a `package.json`. It asks for the source folder, the `@domain-first` packages you use, the default persistence implementation, whether to scaffold a shared in-memory DB for test implementations, React, Storybook and the testing library, then writes `domain-first.project-structure.config.json` and the Shared Kernel files these answers need. With `@domain-first/handlers-rest`, it also scaffolds the [endpoint generator](#how-to-add-a-rest-endpoint); if `next` is among your dependencies, it offers to connect `nextAdapter` from `@domain-first/handlers-next` right away and adds the catch-all route `app/api/[...path]/route.ts`. Finally it prints one command that installs the missing packages.
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
- "domainFirstPackages": [
42
- "@domain-first/types",
43
- "@domain-first/errors",
44
- "@domain-first/handlers",
45
- "@domain-first/wire"
46
- ],
47
- "defaultPersistenceLayerImplementation": "prisma",
48
- "withInMemoryDb": true,
49
- "useReact": false,
50
- "testingLibrary": "vitest"
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` runs once: with a config in place it exits with an error. Change the config by hand; add the endpoint generator or the in-memory DB later with [`df-integration`](#how-to-add-tooling). The other commands need the config and point to `df-init` without it. Every `df-scaffold` run performs one operation from the menu.
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 make one context import another is refused, with the list of imports that would cross the boundary.
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
- Bounded contexts don't import each other. Put cross-context errors, entities, value objects, ports and services into the **Shared Kernel** (`src/shared-kernel`). Its modules are offered as dependencies in every context.
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 `useReact`, 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:
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
- The rules are a default. Teams that work differently change them in the config: what each kind of module may depend on (`rules.dependencies`) and which checks run (`rules.lint`). `df-scaffold` offers dependencies by the same rules. Without `rules`, the defaults apply and every check runs; kinds and checks you don't mention keep their defaults.
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
- "rules": {
215
- "dependencies": { "use-cases": { "add": ["use-cases"] } },
216
- "lint": { "clock": false }
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.