@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
|
@@ -1,31 +1,31 @@
|
|
|
1
1
|
# Command and query
|
|
2
2
|
|
|
3
|
-
When (`../choosing-components.md`,
|
|
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
|
-
-
|
|
6
|
-
- A query only reads: it never changes any state, not even idempotently
|
|
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
|
|
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
|
|
14
|
-
`… pick:Application "pick:New Query" text:order-summary
|
|
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
|
-
-
|
|
26
|
-
-
|
|
27
|
-
-
|
|
28
|
-
-
|
|
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
|
|
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:
|
|
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
|
|
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
|
|
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';
|