@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
@@ -1,31 +1,31 @@
1
1
  # Command and query
2
2
 
3
- When (`../choosing-components.md`, steps 9 and 11): data or behavior of **another context**, or one atomic read/write on this context's own storage that isn't "load/save one aggregate" (read model, report, bulk update). A query reads, a command writes.
3
+ When (`../choosing-components.md`, step 11): one atomic read/write on this context's own storage that is not "load/save one aggregate" (read model, report, bulk update). Another context or external system is reached through a port (`port.md`).
4
4
 
5
- - **One atomic operation of one kind of implementation**: one database operation (several statements in one transaction count as one), one request to another context's endpoint, one message sent to another context (an external API is never a query or command: it's a port). Several operations, a mix of storages, or logic between the steps → several queries/commands, composed in a use case.
6
- - A query only reads: it never changes any state, not even idempotently (no cache filling, no default settings created if missing), and never calls a command. A command returns nothing or only the minimum needed to use its result later (the created order's ID), never the changed data: read that with a query.
7
- - Another context: input/output are this context's own models, duplicated in its terms. The implementation reaches it the simplest available way: a shared database → directly (the persistence label, e.g. `prisma`); otherwise the way chosen in the plan (`df-ps-plan-feature`, step 3, rule 4), by default its REST endpoint (`http`). No imports from the other context.
5
+ - One atomic operation of one kind of storage implementation: several statements in one transaction count as one. Several operations, a mix of storages, or logic between steps → several queries/commands, composed in a use case.
6
+ - A query only reads: it never changes any state, not even idempotently, and never calls a command. A command returns nothing or the minimum needed to use its result later (e.g. a created ID); read changed data with a query.
8
7
 
9
8
  ## Generate (context only)
10
9
 
11
- Prompts: name → implementation (default = config persistence label) → `Add a test implementation` → if yes: test implementation (default `in-memory`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
10
+ Prompts: name → primary implementation select → `Add a test implementation` → test implementation select if yes → {wire} dependencies per implementation. Menus contain saved types from `commands` or `queries` for the selected role, active system types and both manual-entry actions (`../generators.md`). Only `System: in-memory (uses the shared in-memory database)` can be automatic here, when its integration is ready. `api` and `mock` must be saved or entered manually. The first saved/system choice is the default, otherwise manual entry without a suggested name. Saving stages the new ordinary label for that category/role; run-only input leaves the catalog unchanged.
12
11
 
13
- `… pick:Application "pick:New Command" text:place-order default yes default`
14
- `… pick:Application "pick:New Query" text:order-summary default no`
12
+ `… pick:Application "pick:New Command" text:place-order "pick:Enter implementation type and save for future use" text:prisma yes "pick:System: in-memory"` (with the shared DB ready).
13
+ `… pick:Application "pick:New Query" text:order-summary "pick:Enter implementation type for this run only" text:sql no`
15
14
 
16
15
  - `<C>/application/commands/n-command.ts`: abstract `NCommand` ({handlers} schemas + abstract `handle: Handler<…>`), spec
17
16
  - `<C>/infrastructure/commands/I/I-n-command.ts` per implementation (`extends NCommand`, implements `handle`)
18
17
  - {wire} `<C>/wiring/commands/wire-n-command.ts` (env-branched)
19
- - With `withInMemoryDb` in the config, the `in-memory` implementation can get the whole DB: `constructor(private readonly inMemoryDbInfrastructureService: InMemoryDbInfrastructureService)`. No section is added. Without {wire} this always happens; {wire} it is the checked `Suggested` choice of `Dependencies for InMemoryN<Suffix>:`, and unchecking it leaves the implementation empty.
18
+ - With `backend.withInMemoryDb` in the config, the `in-memory` implementation can get the whole DB: `constructor(private readonly inMemoryDbInfrastructureService: InMemoryDbInfrastructureService)`. No section is added. Without {wire} this always happens; {wire} it is the checked `Suggested` choice of `Dependencies for InMemoryN<Suffix>:`, and unchecking it leaves the implementation empty.
20
19
 
21
20
  Queries: the same with `query` / `queries`.
22
21
 
23
22
  ## Implement
24
23
 
25
- - {handlers} The abstract contract holds the static schemas and `abstract handle`; replace the `{}` schemas with real ones. Each infrastructure implementation defines `handle` with the contract's schemas and writes only its `handler` callback.
26
- - An implementation performs its one operation: no business logic, no steps around it. Its only wired dependencies are infrastructure services (the client it runs on); repositories, ports, domain services and other commands and queries stay with the use case. Needing more → it's several commands/queries.
27
- - It uses domain models in its input/output; the time comes in the input, never from the `clock` port.
28
- - The test implementation returns fixed data (another context) or works on the in-memory DB (own storage), so tests never run another context.
24
+ - Queries and commands never import neighboring contexts. `cross-context` is reserved for port adapters and is unavailable here, including as a custom label.
25
+ - {handlers} The abstract contract holds static schemas and `abstract handle`; replace the `{}` schemas with real ones. Each infrastructure implementation defines `handle` with the contract's schemas and writes its `handler` callback.
26
+ - An implementation performs its one operation with no business logic or surrounding steps. Its wired dependencies are infrastructure services (the database client it runs on); repositories, ports, domain services and other queries/commands stay with the consuming use case.
27
+ - Input/output use this context's domain models; time comes through input, never through the clock port.
28
+ - An `in-memory` implementation works on the in-memory DB when configured; `mock`/`stub` implementations may return fixed data.
29
29
 
30
30
  ## Test
31
31
 
@@ -0,0 +1,20 @@
1
+ # Implementation of an existing contract
2
+
3
+ When: a repository, command, query or port already exists and needs one more implementation, e.g. a third adapter of a port so that test, development and production each use their own. A new contract is its own generator (`aggregate.md`, `command-query.md`, `port.md`); never copy an implementation file by hand.
4
+
5
+ ## Generate (context and Shared Kernel)
6
+
7
+ Prompts: `Contract:` → `Implementation type:` → {wire} `Environments:` (at least one) → {wire} dependencies for the new implementation. The type menu merges the category's primary/test history with active system choices and both manual-entry actions (`../generators.md`); it has no ordinary `api`, `mock` or `in-memory` presets. System choices are explicitly marked and conditional: cross-context for ports with a neighbor, shared in-memory DB for repositories/commands/queries with that integration ready. Existing types are disabled. Saving a new ordinary label registers it under `test` and/or `primary` according to selected environments (primary without usable wiring). The run-only action registers nothing.
8
+
9
+ `… pick:Infrastructure "pick:New Implementation" pick:file-storage "pick:Enter implementation type and save for future use" text:local toggle:2`
10
+
11
+ `toggle:` numbers the environments top to bottom: 1 `test`, 2 `development`, 3 `production`.
12
+
13
+ - `<C>/infrastructure/<kind>/I/I-n….ts` as the contract's generator creates it (in-memory DB included)
14
+ - {wire} `~ <C>/wiring/<kind>/wire-n….ts`: import, `const wireIImplementation = wireClass(IN…, [])` before the module's wire, the chosen environments of `envBranchedWire` point at it
15
+
16
+ An implementation left without environments stays in the wire file; the CLI prints `<Class> is no longer used in any environment.` Specs don't change.
17
+
18
+ ## Implement and test
19
+
20
+ As the implementations of the contract's unit file. The spec of the contract wires what `NODE_ENV=test` uses: only a new `test` implementation changes what it tests.
@@ -12,7 +12,7 @@ Prompts: `Module:` (select, grouped by kind; entities and value objects of an ag
12
12
 
13
13
  Every file of the module moves (contract, implementations, wire, specs; an aggregate with its whole folder), every import of it follows, and derived names change in the module and its importers: `OrderRepository`, `PrismaOrderRepository`, `wireOrderRepository`, dependents' `orderRepository` parameters, an aggregate's in-memory DB section. An entity leaving its aggregate is no longer re-exported there; its importers import its file.
14
14
 
15
- Before `Apply?` the CLI lists the files to move and to update: check them against the plan. A move that would make a context import another one prints `Nothing was moved: these imports would cross a bounded context boundary.` with the imports: nothing changed. Fix the design instead (`../choosing-components.md`, step 9: the other context gets its own query or command), or move the dependency first.
15
+ Before `Apply?` the CLI lists the files to move and to update: check them against the plan. A move that would introduce a forbidden context import prints `Nothing was moved: these imports would cross a bounded context boundary.` with the imports: nothing changed. Fix the design instead (`../choosing-components.md`, step 9: the consuming context gets a port with a cross-context adapter), or move the dependency first.
16
16
 
17
17
  In the plan, list a move as a run: old → new place and name, the files to move (`→`) and the files whose imports or names change (`~`).
18
18
 
@@ -1,12 +1,13 @@
1
1
  # Port
2
2
 
3
- When: something that leaves this context's code and storage: an external system or time (`../choosing-components.md`, step 10, "Port or service?"). Own storage → repository, command or query; another context → a query or command, never a port. One method is enough: a single read from an external system is still a port. Another context is only a folder in `bounded-contexts/`; any other service (another team's API, a SaaS) is external. Wanting to mock a class or imagining multiple implementations is not enough. The `clock` port is always a port, usually in the Shared Kernel.
3
+ When: a capability across this context's boundary: another bounded context, an external system, or time (`../choosing-components.md`, steps 9–10). Own aggregate persistence → repository; atomic operations on this context's own storage → command/query. One method is enough. Wanting to mock a class or imagining multiple implementations does not by itself establish a boundary. The `clock` port usually belongs in the Shared Kernel.
4
4
 
5
5
  ## Generate (context and Shared Kernel)
6
6
 
7
- Prompts: name → adapter implementation (default `api`) → `With test implementation` → if yes: test implementation (default `mock`) → {wire} `Dependencies for <Implementation>:` per implementation (`../generators.md`).
7
+ Prompts: name → primary adapter select → `With test implementation` → test adapter select if yes → {wire} dependencies per adapter. Both selects show saved port types for their role, active system types and both manual-entry actions (`../generators.md`). The only automatic system choice is `System: cross-context (calls handlers in another bounded context)`, conditional on a neighboring context and unavailable in the Shared Kernel. No `api`, `mock` or `in-memory` presets are inserted for ports. The first saved/system choice is the default; manual input is empty without saved choices. Existing labels are disabled. Saved ordinary port types are isolated from other categories. Save-entry updates `ports` history; run-only entry generates the adapter without updating the catalog.
8
8
 
9
- `… pick:Application "pick:New Port" text:payment-gateway default yes default`
9
+ `… pick:Application "pick:New Port" text:payment-gateway "pick:Enter implementation type and save for future use" text:api yes "pick:Enter implementation type and save for future use" text:mock`
10
+ `… pick:Application "pick:New Port" text:billing-gateway "pick:System: cross-context" yes "pick:Enter implementation type for this run only" text:mock`
10
11
 
11
12
  - `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
12
13
  - `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
@@ -15,9 +16,11 @@ Prompts: name → adapter implementation (default `api`) → `With test implemen
15
16
  ## Implement
16
17
 
17
18
  - Abstract members in the port, described in the capability's terms (`charge(amount: Money)`), not the provider's.
19
+ - For another context, define the port in the consuming context with its own models and errors. A `cross-context` adapter can inject queries, commands and use cases from any neighboring context; choices are labelled `(<context>)` and names get context-qualified aliases. Only this adapter imports neighboring handler types, and only its matching wiring imports their factories. Never import foreign models, errors, repositories, ports, services, infrastructure or barrels.
20
+ - Implement the capability's methods by mapping input, invoking injected handlers, and mapping results/errors. The CLI creates the contract, adapters and dependencies; it does not generate methods or delegation. Keep business coordination in the consuming use case.
18
21
  - One implementation per adapter: `api` performs the real interaction (an SDK or HTTP client, through an [infrastructure service](services.md) for the client); `mock`/`fake` is deterministic.
19
22
  - Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code.
20
23
 
21
24
  ## Test
22
25
 
23
- `NODE_ENV=test` wires the test implementation, so the logic that uses the port is tested with it.
26
+ Use a deterministic `mock`/`stub` adapter so tests do not run neighboring contexts. `NODE_ENV=test` wires the test implementation, so the logic that uses the port is tested with it.
@@ -1,6 +1,6 @@
1
1
  # Use case
2
2
 
3
- When: one business action a user or system triggers that doesn't fit into a single query or command (`../choosing-components.md`, step 8). **No proxy use cases**: an action that is exactly one query or command gets none, because every query and command is a handler an endpoint can use directly. A use case whose logic lives in an application service is not a proxy.
3
+ When: one business action a user or system triggers that doesn't fit into a single query or command (`../choosing-components.md`, step 8). **No proxy use cases**: an action that is exactly one query or command gets none, because every query and command is a handler an endpoint can use directly. A use case is also the handler for an action that calls a port: the port has capability methods, not `handle`. A use case whose logic lives in an application service is not a proxy.
4
4
 
5
5
  ## Generate (context only)
6
6
 
@@ -6,15 +6,23 @@
6
6
  *
7
7
  * Usage:
8
8
  * node drive.mjs [--bin <name>] [--cwd <dir>] [--delay <ms>] <step> [<step> ...]
9
+ * node drive.mjs "pick:Bounded Context: sales" pick:Application "pick:New Port" text:billing-gateway "pick:System: cross-context" no toggle:1
10
+ * (when the dependency list has the desired neighboring handler at item 1)
9
11
  *
10
12
  * Steps (one per prompt, in the order the CLI asks them):
11
13
  * pick:<label> select prompt: type the choice label (or a unique prefix) and press Enter
12
14
  * text:<value> input prompt: type the value and press Enter
13
- * default input prompt: accept the suggested default (press Enter)
15
+ * default input/select prompt: accept the suggested default (press Enter)
14
16
  * yes | no confirm prompt
15
17
  * toggle:<n,..> checkbox prompt: toggle 1-based items (headers not counted),
16
18
  * moving with the arrow keys, then press Enter
17
19
  * none checkbox prompt: submit as is (pre-checked items stay checked)
20
+ *
21
+ * Implementation menus use the same pick:<label> steps as any select:
22
+ * a saved implementation label or an available System: implementation,
23
+ * or either manual-entry action followed by a separate text:<type> step:
24
+ * "pick:Enter implementation type and save for future use" text:redis
25
+ * "pick:Enter implementation type for this run only" text:redis
18
26
  */
19
27
  import { spawn } from 'node:child_process';
20
28
  import fs from 'node:fs';