@domain-first/project-structure 2.11.0 → 2.13.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 CHANGED
@@ -161,7 +161,18 @@ With `@domain-first/wire`, generators create `wireClass` factories. Repositories
161
161
  | `development` | The primary implementation. Also used when `NODE_ENV` is unset. |
162
162
  | `production` | The primary implementation. |
163
163
 
164
- Implementation names such as `prisma`, `api`, `in-memory`, and `mock` determine names and locations for generated classes. Add the database queries, API calls, or in-memory behavior yourself. Fill in the dependency lists in wiring factories as you implement constructors.
164
+ Implementation names such as `prisma`, `api`, `in-memory`, and `mock` determine names and locations for generated classes. Add the database queries, API calls, or in-memory behavior yourself. As the last step, generators that create a wiring factory offer to pick its dependencies from wired modules of the same bounded context and the Shared Layer. Each selected module is added to the factory's dependency list and to the constructor, for example `private readonly userRepository: UserRepository`. Environment-branched factories (repositories, execution commands and queries, ports) wire each implementation in isolation: you pick dependencies separately for each one, for example for `PrismaUserRepository` and then for `InMemoryUserRepository`. Each list starts with a **Suggested** group when infrastructure modules match the implementation name: `prisma-infrastructure-service` for a `prisma` implementation, or `in-memory-db-infrastructure-service` for an `in-memory` one. To add dependencies to an existing module later, select **Wire dependency** in the bounded context or Shared Layer menu. Environment-branched modules are listed there once per implementation, such as `UserRepository (prisma)` and `UserRepository (in-memory)`, and only the chosen one is changed.
165
+
166
+ The list depends on the layer of the class being built:
167
+
168
+ | Layer | Can depend on |
169
+ | -------------- | -------------------------------------------- |
170
+ | Domain | Domain |
171
+ | Application | Domain, application |
172
+ | Infrastructure | Domain, infrastructure |
173
+ | Presentation | Application, presentation |
174
+
175
+ Some kinds of modules have narrower rules. From the application layer, application services can use only ports. Use cases can't use other use cases, and repository implementations can't use other repositories. Execution commands and queries can't use other commands or queries. From the application layer, orchestration commands and queries can use only execution commands and queries. Repository, execution command, execution query, and port implementations belong to infrastructure: they implement application modules but can't take them as dependencies. REST endpoints are not offered as dependencies. Their dependencies are chosen when they are generated (see REST endpoints) and are not available in **Wire dependency**.
165
176
 
166
177
  When `testingLibrary` is configured, supported generators always add `.spec.ts` files. These start with construction or wiring checks; extend them with tests for your business behavior. Repository, command, query, and port test templates reference wiring factories, so use the wiring integration or adapt those tests to your own construction setup.
167
178
 
@@ -173,7 +184,7 @@ Select an existing controller or create one, choose `get`, `post`, `patch`, `del
173
184
  src/bounded-contexts/sales/presentation/rest/orders/recent/GET.ts
174
185
  ```
175
186
 
176
- The route metadata uses `/sales/orders/recent`. Connect the endpoint to an application handler and provide its `EndpointGenerator`; the generated handler dependency starts as a `never` placeholder.
187
+ The route metadata uses `/sales/orders/recent`. With `@domain-first/wire`, the generator then asks for the endpoint generator, picked from presentation services of the bounded context and the Shared Layer (services with `endpoint` in the name are suggested first), and for the handler, picked from queries, commands, and use cases of the bounded context. The endpoint's constructor gets the chosen types, and its wiring factory gets their factories. In `get handle()`, call the generating method of the chosen service yourself, for example `this.endpointGenerator.generate(...)` for `readonly generate = createEndpoint(...)(adapter)`. Without wiring, or when there is nothing to pick, the endpoint keeps the `EndpointGenerator` type and a `never` handler placeholder for you to replace.
177
188
 
178
189
  With wiring enabled, the generator also adds endpoint factories and exports collected as `restHandlers` in `<rootFolder>/presentation/rest/index.ts`. Connect these handlers to your HTTP server.
179
190
 
@@ -192,6 +203,82 @@ Enable `useReact` and choose **Scaffold React module** from the main menu. Modul
192
203
 
193
204
  Page and widget names can include folders split by `/`. For example, a page named `admin/panel/users` is created at `pages/admin/panel/users-page.tsx` as `AdminPanelUsersPage`, and a widget with the same name at `widgets/admin/panel/users/` as `AdminPanelUsersWidget` with the story title `Widgets/Admin/Panel/Users`. File names use only the last segment; code names use the whole path.
194
205
 
206
+ ### Project integrations
207
+
208
+ Choose **Add integration → Storybook (React + Vite)** to configure Storybook.
209
+ The integration creates `main.ts` and `preview.ts` under
210
+ `<rootFolder>/presentation/react/.storybook`, enables React scaffolding and sets
211
+ `storybookFramework` to `@storybook/react-vite` for future generated stories.
212
+ It uses relative story paths and configures the Vite alias `@` to the absolute
213
+ project root (the directory containing `package.json`), computed at runtime
214
+ from the config location. Add project CSS to `preview.ts` with relative imports
215
+ or `@/` imports. The setup includes `@vitejs/plugin-react`.
216
+
217
+ It adds these package scripts, with paths adjusted to your `rootFolder`:
218
+
219
+ ```json
220
+ {
221
+ "storybook": "storybook dev -p 6006 -c \"src/presentation/react/.storybook\"",
222
+ "build-storybook": "storybook build -c \"src/presentation/react/.storybook\" -o \"src/presentation/react/storybook-static\""
223
+ }
224
+ ```
225
+
226
+ Existing unrelated scripts and package fields are preserved. If a script name
227
+ already has a different command, choose to keep it, replace it, or use another
228
+ name. Identical generated configs and scripts are skipped on subsequent runs;
229
+ changed config files use the usual overwrite confirmation. Cancelling before
230
+ writing leaves all files unchanged.
231
+
232
+ After writing, the CLI prints npm commands for missing dependencies and the
233
+ selected scripts. It does not install packages or execute scripts. Install commands omit version constraints for Storybook, its React + Vite
234
+ framework, Vite and the React plugin; existing dependency versions are preserved
235
+ and must be compatible with those packages. Generate a
236
+ UI-kit component or a widget with separated UI to add your first story. The
237
+ static build goes to `<rootFolder>/presentation/react/storybook-static`.
238
+
239
+ ### Missing domain-first packages
240
+
241
+ Choose **Add integration → Missing domain-first packages** to compare
242
+ `domainFirstPackages` in the configuration with `dependencies`, `devDependencies`
243
+ and `optionalDependencies` in the project's `package.json`. The CLI prints one
244
+ `npm i` command for missing packages, without version constraints. If none are
245
+ missing, it reports that all configured packages are already declared. This
246
+ checks declared dependencies, not the contents of `node_modules`, and does not
247
+ modify files or install packages.
248
+
249
+ ### Prisma 8 (PostgreSQL)
250
+
251
+ Choose **Add integration → Prisma 8 (PostgreSQL, RC)**. The preset creates
252
+ `<rootFolder>/shared/infrastructure/prisma/prisma.config.ts` and a starter
253
+ `contract.prisma`. Existing contracts are preserved, including your models.
254
+
255
+ You can optionally create `PrismaInfrastructureService` in
256
+ `shared/infrastructure/services`; it exposes `orm`, uses the Temporal polyfill,
257
+ and reuses the client across development hot reloads. When `@domain-first/wire`
258
+ is enabled, the integration also creates its wiring factory. A separate prompt
259
+ lets you make `prisma` the default persistence implementation.
260
+
261
+ The integration adds three scripts, all pointing to the generated config:
262
+
263
+ - `prisma:emit`: emit `contract.json` and `contract.d.ts`.
264
+ - `prisma:migration:plan`: emit the contract, then plan a migration.
265
+ - `prisma:migration:apply`: apply migrations and advance the `db` ref.
266
+
267
+ Script conflicts use the same keep/replace/rename flow as Storybook. File changes
268
+ are staged until overwrite confirmation; no packages are installed and no
269
+ commands connect to the database during scaffolding.
270
+
271
+ The printed install commands omit version constraints for `prisma`,
272
+ `@prisma/cli-engine`, `@prisma/orm-postgres`, `temporal-polyfill`, and `dotenv`. Already declared dependencies are kept. This is a PostgreSQL
273
+ preset for Prisma 8 RC, not a Prisma 7 migration tool.
274
+
275
+ After installing dependencies, configure `DATABASE_URL` (the CLI loads `.env`;
276
+ your application must load its runtime environment), add your models to the
277
+ contract and run the emit script before compiling or importing the service.
278
+ Use Node.js 22.18+, TypeScript 5.9+, ESM and JSON import support. Review planned
279
+ migrations before running the apply script. Generated contract files and
280
+ migration history are managed by Prisma, not by this scaffolder.
281
+
195
282
  ## Configuration
196
283
 
197
284
  The project configuration is stored in `domain-first.project-structure.config.json`. Commit it to share generation settings with your team. For example:
@@ -2,6 +2,7 @@
2
2
  * Existing files a full rewrite would replace, whatever their content.
3
3
  */
4
4
  export declare const filesToOverwrite: () => string[];
5
+ export declare const discardPendingChanges: () => void;
5
6
  export declare const writePendingChanges: () => void;
6
7
  declare class FileSystemItem {
7
8
  readonly path: string;
@@ -23,6 +24,11 @@ export declare class File extends FileSystemItem {
23
24
  get exists(): boolean;
24
25
  get data(): string;
25
26
  set data(content: string);
27
+ /**
28
+ * Changes the content without marking a full rewrite, so editing an
29
+ * existing file doesn't ask to overwrite it.
30
+ */
31
+ update: (content: string) => void;
26
32
  addLine: (newLine: string, separator?: string) => void;
27
33
  /**
28
34
  * Re-running a generator for the same name must not duplicate the line.