@domain-first/project-structure 6.0.0 → 7.1.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 (53) hide show
  1. package/README.md +20 -19
  2. package/dist/201.js +46 -35
  3. package/dist/287.js +1762 -1250
  4. package/dist/backend-module-move.d.ts +53 -0
  5. package/dist/backend-module-move.spec.d.ts +1 -0
  6. package/dist/config-file.d.ts +2 -2
  7. package/dist/dependency-rules.d.ts +1 -1
  8. package/dist/file-system.d.ts +5 -0
  9. package/dist/in-memory-db.d.ts +9 -0
  10. package/dist/index.cjs +534 -804
  11. package/dist/index.js +9 -47
  12. package/dist/init.cjs +913 -0
  13. package/dist/init.d.ts +2 -0
  14. package/dist/init.js +36 -0
  15. package/dist/integration.cjs +457 -33
  16. package/dist/integration.js +4 -4
  17. package/dist/integrations/in-memory-db.d.ts +6 -0
  18. package/dist/integrations/index.d.ts +2 -0
  19. package/dist/integrations/missing-domain-first-packages.d.ts +8 -0
  20. package/dist/integrations/rest-endpoint-generator.d.ts +18 -0
  21. package/dist/integrations/rest-endpoint-generator.spec.d.ts +1 -0
  22. package/dist/lint.cjs +8 -8
  23. package/dist/lint.js +7 -7
  24. package/dist/module-move.d.ts +58 -0
  25. package/dist/print-next-steps.d.ts +2 -2
  26. package/dist/react-module-move.d.ts +2 -6
  27. package/dist/react.cjs +986 -0
  28. package/dist/react.d.ts +2 -0
  29. package/dist/react.js +73 -0
  30. package/dist/use-cases/index.d.ts +1 -0
  31. package/dist/use-cases/move-backend-unit.d.ts +7 -0
  32. package/dist/use-cases/rest-endpoint-generator.d.ts +1 -1
  33. package/package.json +3 -1
  34. package/skills/df-ps-implement/SKILL.md +11 -56
  35. package/skills/df-ps-plan-feature/SKILL.md +6 -6
  36. package/skills/df-ps-project-scripts/SKILL.md +1 -1
  37. package/skills/df-ps-react/SKILL.md +82 -0
  38. package/skills/df-ps-react/references/generators.md +80 -0
  39. package/skills/df-ps-scaffold/SKILL.md +39 -20
  40. package/skills/df-ps-scaffold/references/choosing-components.md +7 -28
  41. package/skills/df-ps-scaffold/references/generators.md +6 -179
  42. package/skills/df-ps-scaffold/references/units/aggregate.md +47 -0
  43. package/skills/df-ps-scaffold/references/units/bounded-context.md +13 -0
  44. package/skills/df-ps-scaffold/references/units/command-query.md +32 -0
  45. package/skills/df-ps-scaffold/references/units/endpoint.md +28 -0
  46. package/skills/df-ps-scaffold/references/units/entity-value-object.md +27 -0
  47. package/skills/df-ps-scaffold/references/units/errors.md +26 -0
  48. package/skills/df-ps-scaffold/references/units/move-or-rename.md +21 -0
  49. package/skills/df-ps-scaffold/references/units/port.md +23 -0
  50. package/skills/df-ps-scaffold/references/units/services.md +28 -0
  51. package/skills/df-ps-scaffold/references/units/use-case.md +25 -0
  52. package/skills/df-ps-scaffold/references/units/wire-dependency.md +15 -0
  53. package/skills/df-ps-scaffold/scripts/drive.mjs +12 -4
@@ -0,0 +1,26 @@
1
+ # Errors {errors}
2
+
3
+ When: a business failure callers must recognize (`../choosing-components.md`, step 1). Technical, ownerless ones (`unauthorized`) go to the Shared Kernel.
4
+
5
+ ## Generate (context and Shared Kernel)
6
+
7
+ First prompt (select): `New error without namespace` | `New namespace` | `New error in namespace <ns>`, then a name.
8
+
9
+ `… pick:Domain pick:Errors "pick:New namespace" text:order`
10
+ `… pick:Domain pick:Errors "pick:New error in namespace order" text:not-found`
11
+ `… pick:Domain pick:Errors "pick:New error without" text:order-closed`
12
+
13
+ - Without namespace: appends `export class N extends CtxErrors.define('n') {}` to `<C>/domain/errors/index.ts`; the first one also puts `CtxErrors = errorNamespace('ctx')` (with its import) at the top of `index.ts`
14
+ - New namespace: `<C>/domain/errors/ns.ts` (`NsErrors = errorNamespace('ctx').subnamespace('ns')`) + `export * from './ns'` in `index.ts`
15
+ - In namespace: appends `export class NsN extends NsErrors.define('n') {}` to `ns.ts` (namespace first), extending the namespace the file exports
16
+ - Shared Kernel: errors end with `SharedKernelError`, namespaces with `SharedKernelErrors`: `NSharedKernelError`, `NsSharedKernelErrors`, `NsNSharedKernelError`
17
+
18
+ `Ctx` = PascalCase of the context folder (`SharedKernel` in Shared Kernel). Contexts start without errors: `index.ts` appears with the first error or namespace. Re-running is safe: an existing namespace file is kept, and a line already in the file isn't added again.
19
+
20
+ A namespace groups the errors of one area (`order`, `payment`); `New error in namespace` is listed only once the namespace exists, so plan `New namespace` first.
21
+
22
+ ## Implement
23
+
24
+ - Details: `.define<{ orderId: string }>('not-found')`.
25
+ - Throw `new XError({...})`; recognize with `XError.is(e)`, or `XError.matchesCode(data)` after serialization.
26
+ - Import a context's errors from its `domain/errors`. Only `shared-kernel/` may import another context's errors, e.g. to map them to HTTP statuses in the endpoint generator ([endpoint](endpoint.md)).
@@ -0,0 +1,21 @@
1
+ # Move or rename
2
+
3
+ When: a module's name no longer fits, or it belongs elsewhere: another bounded context, the Shared Kernel (entities, value objects, services, ports only), or in or out of an aggregate. Never move, rename or copy module files by hand, and never rename their classes, wires or parameters by hand: the CLI keeps files, names and imports in sync.
4
+
5
+ ## Generate (context and Shared Kernel)
6
+
7
+ Prompts: `Module:` (select, grouped by kind; entities and value objects of an aggregate show it: `order-line (order)`) → `Move to:` (`Bounded Context: <current> (stays)`, other contexts, `Shared Kernel` for the kinds it has) → `Aggregate:` (entities and value objects only, when the target context has aggregates: `No aggregate` or one of them) → `New name:` (default: the current one) → `Apply?`.
8
+
9
+ `… "pick:Move or rename" pick:order "pick:Bounded Context: sales" text:purchase yes`
10
+ `… "pick:Move or rename" pick:money "pick:Shared Kernel" default yes`
11
+ `… "pick:Move or rename" pick:order-line "pick:Bounded Context: sales" "pick:No aggregate" default yes`
12
+
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
+
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.
16
+
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
+
19
+ ## Implement
20
+
21
+ Nothing to fill in. Re-read the moved module's files: names inside method bodies that only resemble the old name (local variables, strings, comments) are not renamed. Run `npx df-lint` and the project's tsc/tests.
@@ -0,0 +1,23 @@
1
+ # Port
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.
4
+
5
+ ## Generate (context and Shared Kernel)
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`).
8
+
9
+ `… pick:Application "pick:New Port" text:payment-gateway default yes default`
10
+
11
+ - `<C>/application/ports/n.ts` (abstract `N`; name it after the capability), spec
12
+ - `<C>/infrastructure/application-adapters/I/I-n.ts` per implementation (`class IN extends N`)
13
+ - {wire} `<C>/wiring/application-ports/wire-n.ts` (env-branched)
14
+
15
+ ## Implement
16
+
17
+ - Abstract members in the port, described in the capability's terms (`charge(amount: Money)`), not the provider's.
18
+ - 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
+ - Use the Shared Kernel `clock` port instead of `new Date()` / `Date.now()` in domain and application code.
20
+
21
+ ## Test
22
+
23
+ `NODE_ENV=test` wires the test implementation, so the logic that uses the port is tested with it.
@@ -0,0 +1,28 @@
1
+ # Services: domain, application, infrastructure, presentation
2
+
3
+ When (`../choosing-components.md`, steps 12–15, "Port or service?"):
4
+
5
+ - **Domain service**: a rule at the junction of several entities / value objects not all belonging to one aggregate, no I/O. It takes the aggregates and values it needs as arguments; loading them is the caller's job. In the Shared Kernel only for junctions of universal types.
6
+ - **Application service**: application logic reused by 2+ use cases, with external interaction or storage access delegated to injected ports, commands or queries. A composition needed by one use case stays in it.
7
+ - **Infrastructure service**: a technical helper used only by infrastructure code; also the home of a value that isn't a wired module (a database or SDK client, a config value), named after the implementation label (`prisma`, `stripe`).
8
+ - **Presentation service**: a helper used only by presentation code.
9
+
10
+ ## Generate (context and Shared Kernel)
11
+
12
+ Prompts: name → {wire} `Dependencies:` (`../generators.md`). `L` = `domain` | `application` | `infrastructure` | `presentation`.
13
+
14
+ `… pick:Application "pick:New Service" text:checkout`
15
+
16
+ - `<C>/L/services/n-L-service.ts` (`class NLService`, e.g. `CheckoutApplicationService`), spec
17
+ - {wire} `<C>/wiring/L-services/wire-n-L-service.ts` (`wireClass(X, [])`)
18
+
19
+ ## Implement
20
+
21
+ - Domain services take and return domain types. Pure: no I/O, ports, or repositories, not even injected ones; they work with the data they are handed. They depend only on other domain services.
22
+ - Application services have no `handle`: a use case is how an endpoint reaches their logic. They call injected ports, commands and queries, never external SDKs, HTTP clients, or another context directly.
23
+ - Infrastructure services: an external client or config value is created or read by the service itself (`readonly client = new PrismaClient()`), with no constructor parameter for it. Implementations get the service through `df-scaffold`, where it shows up under `Suggested`. Wrap its wire in `memoWire(...)` when one instance must be shared (a connection pool, an in-memory store). No `wireValue(...)`.
24
+ - Infrastructure never sees application services. Logic infrastructure needs from one: pure logic without ports → a domain service; logic over ports → call the ports directly; technical (mapping, retries, external API formats) → an infrastructure service.
25
+
26
+ ## Test
27
+
28
+ Test a service's logic with fake dependencies in its generated spec.
@@ -0,0 +1,25 @@
1
+ # Use case
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.
4
+
5
+ ## Generate (context only)
6
+
7
+ Prompts: name → {wire} `Dependencies:` (`../generators.md`; use cases never see use cases by default).
8
+
9
+ `… pick:Application "pick:New Use Case" text:place-order`
10
+
11
+ - `<C>/application/use-cases/n-use-case.ts`: {handlers} schemas + `handle = defineHandler(...)`, else an empty class; spec
12
+ - {wire} `<C>/wiring/use-cases/wire-n-use-case.ts`
13
+
14
+ Generate its dependencies (repositories, ports, commands, queries, application services) first, so `Dependencies:` lists them.
15
+
16
+ ## Implement
17
+
18
+ - {handlers} The member is `handle = defineHandler({ inputSchema, outputSchema, handler })`. Replace the static `{}` schemas with real ones and write the logic in the `handler` callback; dependencies come through the constructor.
19
+ - It composes repositories, ports, commands, queries and domain services: loads aggregates, calls their methods, saves them. Reading the time: the `clock` port, then pass the time into commands and queries in their input.
20
+ - A rule about a set of aggregates: a repository method that queries it, plus a check and a domain error here.
21
+ - Call others' handlers with `x.handle(input)` (returns a result) or `x.handle.unsafe(input)` (throws).
22
+
23
+ ## Test
24
+
25
+ Extend the generated spec with handler tests via `handle(...)`, wired with test implementations (`NODE_ENV=test`).
@@ -0,0 +1,15 @@
1
+ # Wire dependency {wire}
2
+
3
+ When: an existing wired module needs a new dependency (`df-ps-scaffold` `SKILL.md`, rule 3). New modules get theirs in the generator's `Dependencies:` step instead.
4
+
5
+ ## Generate (context and Shared Kernel)
6
+
7
+ Prompts: module (select: wired modules of `<C>`, grouped as in `Dependencies:`, endpoints excluded; an env-branched module is listed once per implementation, e.g. `UserRepository (prisma)`, `UserRepository (in-memory)`) → `Dependencies:`, or `Dependencies for <Implementation>:` for the chosen implementation only (`../generators.md`). Modules already in the wire are not listed. If nothing fits, it prints `No dependencies available for this module.` and changes nothing.
8
+
9
+ `"pick:Bounded Context: users" "pick:Wire dependency" "pick:UserRepository (prisma)" toggle:1`
10
+
11
+ Edits the wire and the implementation classes in place; this never triggers `Overwrite them?`. List it in the plan as a run for the existing module.
12
+
13
+ ## Implement
14
+
15
+ Use the injected dependency in the class body. Don't edit the constructor parameters or the wire list by hand. A dependency the CLI doesn't offer is forbidden by the dependency rules or by context isolation: change the design instead (a port, a query or command, an infrastructure service).
@@ -1,10 +1,11 @@
1
1
  #!/usr/bin/env node
2
2
  /**
3
- * Drives the interactive `df-scaffold` CLI with a scripted list of answers and
3
+ * Drives an interactive CLI of the package (`df-scaffold` by default, or
4
+ * `df-react` / `df-init` with `--bin`) with a scripted list of answers and
4
5
  * prints the files it created or changed.
5
6
  *
6
7
  * Usage:
7
- * node drive.mjs [--cwd <dir>] [--delay <ms>] <step> [<step> ...]
8
+ * node drive.mjs [--bin <name>] [--cwd <dir>] [--delay <ms>] <step> [<step> ...]
8
9
  *
9
10
  * Steps (one per prompt, in the order the CLI asks them):
10
11
  * pick:<label> select prompt: type the choice label (or a unique prefix) and press Enter
@@ -22,10 +23,12 @@ import path from 'node:path';
22
23
  const args = process.argv.slice(2);
23
24
  let cwd = process.cwd();
24
25
  let delay = 600;
26
+ let bin = 'df-scaffold';
25
27
  const steps = [];
26
28
 
27
29
  for (let i = 0; i < args.length; i++) {
28
30
  if (args[i] === '--cwd') cwd = path.resolve(args[++i]);
31
+ else if (args[i] === '--bin') bin = args[++i];
29
32
  else if (args[i] === '--delay') delay = Number(args[++i]);
30
33
  else steps.push(args[i]);
31
34
  }
@@ -87,12 +90,17 @@ const snapshot = () => {
87
90
  return result;
88
91
  };
89
92
 
90
- const localBin = path.join(projectRoot, 'node_modules', '.bin', 'df-scaffold');
93
+ if (!['df-scaffold', 'df-react', 'df-init'].includes(bin)) {
94
+ console.error(`Unknown --bin: ${bin}`);
95
+ process.exit(2);
96
+ }
97
+
98
+ const localBin = path.join(projectRoot, 'node_modules', '.bin', bin);
91
99
  const [command, commandArgs] = fs.existsSync(localBin)
92
100
  ? [localBin, []]
93
101
  : [
94
102
  'npm',
95
- ['exec', '--yes', '--package=@domain-first/project-structure', '--', 'df-scaffold']
103
+ ['exec', '--yes', '--package=@domain-first/project-structure', '--', bin]
96
104
  ];
97
105
 
98
106
  const before = snapshot();