@domain-first/project-structure 8.4.0 → 8.5.1

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.
@@ -369,7 +369,8 @@ const lintChecks = [
369
369
  'layers',
370
370
  'dependencies',
371
371
  'react',
372
- 'clock'
372
+ 'clock',
373
+ 'config'
373
374
  ];
374
375
  const config_file_configFileName = 'domain-first.project-structure.config.json';
375
376
  const projectConfigSchema = external_zod_default().object({
@@ -1530,10 +1531,11 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
1530
1531
  path: readonly string[];
1531
1532
  }): OpenApiData | undefined => {
1532
1533
  try {
1533
- const [currentBoundedContext, controller, ...relativePath] =
1534
- routeMetadata.path;
1534
+ // The controller, if any, is the first folder of the path:
1535
+ // context-root endpoints live right in presentation/rest.
1536
+ const [currentBoundedContext, ...relativePath] = routeMetadata.path;
1535
1537
 
1536
- if (!currentBoundedContext || !controller) {
1538
+ if (!currentBoundedContext) {
1537
1539
  return undefined;
1538
1540
  }
1539
1541
 
@@ -1543,7 +1545,6 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
1543
1545
  currentBoundedContext,
1544
1546
  'presentation',
1545
1547
  'rest',
1546
- controller,
1547
1548
  ...relativePath.map(pathParameterAsName),
1548
1549
  \`\${routeMetadata.method.toUpperCase()}.ts\`
1549
1550
  )
@@ -3199,7 +3200,7 @@ const scaffoldRequestSchema = external_zod_default().discriminatedUnion('operati
3199
3200
  agent_requests_operation('endpoint', {
3200
3201
  ...common,
3201
3202
  ...agent_requests_owner,
3202
- controller: agent_requests_name,
3203
+ controller: agent_requests_name.optional().describe('Omit for an endpoint at the context root (`/<context>`); then path is empty or starts with a :param.'),
3203
3204
  method: external_zod_default()["enum"]([
3204
3205
  'get',
3205
3206
  'post',
@@ -5129,46 +5130,45 @@ export const ${names.namespace(ClassName)} = errorNamespace('${boundedContextFol
5129
5130
  const namespaceFile = currentErrorFolder.file(`${namespace}.ts`);
5130
5131
  namespaceFile.addLineIfMissing(errorClass(names.error(`${namespaceNaming.ClassName}${ClassName}`), exportedNamespace(namespaceFile, names.namespace(namespaceNaming.ClassName)), fileName), '\n\n');
5131
5132
  };
5133
+ const newController = 'New controller';
5134
+ const withoutController = 'No controller (context root)';
5135
+ const pathParameterAsName = (segment)=>segment.startsWith(':') ? `_${segment.slice(1)}_` : segment;
5136
+ const isPathParameterName = (name)=>name.startsWith(':') || /^_.+_$/.test(name);
5137
+ const sharedRestFolder = (boundedContextFolder)=>boundedContextFolder.subitem([
5138
+ '..',
5139
+ '..',
5140
+ 'presentation',
5141
+ 'rest'
5142
+ ]);
5132
5143
  const scaffoldNewHandlersRestEndpoint = async (boundedContextFolder)=>{
5133
5144
  const restPresentationFolder = boundedContextFolder.subitem([
5134
5145
  'presentation',
5135
5146
  'rest'
5136
5147
  ]);
5137
- const controllers = restPresentationFolder.content.subfolderNames;
5138
- let controller = await interaction_select({
5148
+ const controllers = restPresentationFolder.content.subfolderNames.filter((x)=>!isPathParameterName(x));
5149
+ let controllerChoice = await interaction_select({
5139
5150
  key: 'controllerSelection',
5140
5151
  message: 'Controller: ',
5141
5152
  choices: [
5142
5153
  ...controllers,
5143
- 'New controller'
5154
+ newController,
5155
+ withoutController
5144
5156
  ]
5145
5157
  });
5146
- if ('New controller' === controller) {
5147
- controller = await interaction_input({
5148
- key: 'controllerName',
5149
- message: 'Name: '
5150
- });
5151
- if (config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire')) {
5152
- boundedContextFolder.subitem([
5153
- 'wiring',
5154
- 'presentation',
5155
- 'rest'
5156
- ]).file('index.ts').addLine(`export * from './${controller}'`);
5157
- const sharedRestFolder = boundedContextFolder.subitem([
5158
- '..',
5159
- '..',
5160
- 'presentation',
5161
- 'rest'
5162
- ]);
5163
- sharedRestFolder.file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
5164
- if (!sharedRestFolder.file('index.ts').exists) sharedRestFolder.createFile('index.ts', `
5165
- import * as wires from './wires'
5166
-
5167
- const restWires = Object.values(wires)
5168
-
5169
- export const restHandlers = restWires.map(x => x().handle)
5170
- `.trim());
5171
- }
5158
+ if (controllerChoice === newController) controllerChoice = await interaction_input({
5159
+ key: 'controllerName',
5160
+ message: 'Name: ',
5161
+ validate: (value)=>value.trim() ? isPathParameterName(value) || value.includes('/') ? 'A controller is one static path segment' : true : `Name is required; pick "${withoutController}" for an endpoint at the context root`
5162
+ });
5163
+ const controller = controllerChoice === withoutController ? void 0 : controllerChoice;
5164
+ const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
5165
+ if (controller && !controllers.includes(controller) && withWiring) {
5166
+ boundedContextFolder.subitem([
5167
+ 'wiring',
5168
+ 'presentation',
5169
+ 'rest'
5170
+ ]).file('index.ts').addLine(`export * from './${controller}'`);
5171
+ sharedRestFolder(boundedContextFolder).file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
5172
5172
  }
5173
5173
  const method = await interaction_select({
5174
5174
  key: 'method',
@@ -5183,21 +5183,32 @@ export const restHandlers = restWires.map(x => x().handle)
5183
5183
  });
5184
5184
  const routeSegments = (await interaction_input({
5185
5185
  key: 'path',
5186
- message: 'Relative path (split by "/"):'
5186
+ message: 'Relative path (split by "/"):',
5187
+ validate: (value)=>{
5188
+ const [first] = value.split('/').filter((x)=>!!x);
5189
+ return controller || !first || first.startsWith(':') ? true : `Without a controller, the path is empty or starts with a path parameter; "${first}" is a controller`;
5190
+ }
5187
5191
  })).split('/').filter((x)=>!!x);
5188
- const pathParameterAsName = (segment)=>segment.startsWith(':') ? `_${segment.slice(1)}_` : segment;
5189
- const controllerFolder = restPresentationFolder.subitem([
5190
- controller
5191
- ]);
5192
- const endpointFolder = controllerFolder.subitem(routeSegments.map(pathParameterAsName));
5193
- const nameBase = `${controller}-${routeSegments.length ? `${routeSegments.map(pathParameterAsName).join('-')}-` : ''}${method}-endpoint`;
5192
+ const folderSegments = [
5193
+ ...controller ? [
5194
+ controller
5195
+ ] : [],
5196
+ ...routeSegments
5197
+ ];
5198
+ const endpointFolder = restPresentationFolder.subitem(folderSegments.map(pathParameterAsName));
5199
+ const nameSegments = [
5200
+ controller ?? boundedContextFolder.name,
5201
+ ...routeSegments
5202
+ ];
5203
+ const nameBase = `${[
5204
+ ...nameSegments.map(pathParameterAsName),
5205
+ method
5206
+ ].join('-')}-endpoint`;
5194
5207
  const endpointClassName = [
5195
- controller,
5196
- ...routeSegments,
5208
+ ...nameSegments,
5197
5209
  method,
5198
5210
  'endpoint'
5199
5211
  ].map((segment)=>segment.startsWith(':') ? pathParameterAsName(segment) : new UnknownFormatNaming(segment).ClassName).join('');
5200
- const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
5201
5212
  const endpointGenerator = findRestEndpointGenerator(boundedContextFolder.subitem([
5202
5213
  '..',
5203
5214
  '..',
@@ -5217,8 +5228,11 @@ export class ${endpointClassName} {
5217
5228
 
5218
5229
  get handle() {
5219
5230
  return this.endpointGenerator(this.handler.handle, {
5220
- route: { method: '${method}', path: ['${boundedContextFolder.name}', '${controller}'${routeSegments.length ? `, ${routeSegments.map((x)=>`'${x}'`).join(', ')}` : ''}] },
5221
- tags: ['${boundedContextFolder.name}: ${controller}'],
5231
+ route: { method: '${method}', path: [${[
5232
+ boundedContextFolder.name,
5233
+ ...folderSegments
5234
+ ].map((x)=>`'${x}'`).join(', ')}] },
5235
+ tags: ['${boundedContextFolder.name}${controller ? `: ${controller}` : ''}'],
5222
5236
  })
5223
5237
  }
5224
5238
  }
@@ -5228,7 +5242,9 @@ export class ${endpointClassName} {
5228
5242
  'wiring',
5229
5243
  'presentation',
5230
5244
  'rest',
5231
- controller
5245
+ ...controller ? [
5246
+ controller
5247
+ ] : []
5232
5248
  ]);
5233
5249
  const wireNameBase = `wire-${nameBase}`;
5234
5250
  const wireNaming = new UnknownFormatNaming(wireNameBase);
@@ -5248,6 +5264,15 @@ export const wire${endpointClassName} = wireClass(
5248
5264
  )
5249
5265
  `.trim());
5250
5266
  wiringFolder.file('index.ts').addLineIfMissing(`export * from './${wireNaming.fileName}'`);
5267
+ if (!controller) sharedRestFolder(boundedContextFolder).file('wires.ts').addLineIfMissing(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${wireNaming.fileName}'`);
5268
+ const restHandlersFile = sharedRestFolder(boundedContextFolder).file('index.ts');
5269
+ if (!restHandlersFile.exists) sharedRestFolder(boundedContextFolder).createFile('index.ts', `
5270
+ import * as wires from './wires'
5271
+
5272
+ const restWires = Object.values(wires)
5273
+
5274
+ export const restHandlers = restWires.map(x => x().handle)
5275
+ `.trim());
5251
5276
  }
5252
5277
  };
5253
5278
  const scaffold_new_implementation_kindTitles = {
@@ -5887,12 +5912,15 @@ const answersFor = (command, request, owner)=>{
5887
5912
  if ('error' === request.operation || 'error-namespace' === request.operation) defaults.errorAction = 'error-namespace' === request.operation ? 'New namespace' : request.namespace ? `New error in namespace ${request.namespace}` : 'New error without namespace';
5888
5913
  if ('endpoint' === request.operation) {
5889
5914
  delete answers.controller;
5890
- const existing = owner.subitem([
5891
- 'presentation',
5892
- 'rest'
5893
- ]).content.subfolderNames.includes(request.controller);
5894
- answers.controllerSelection = existing ? request.controller : 'New controller';
5895
- if (!existing) answers.controllerName = request.controller;
5915
+ if (void 0 === request.controller) answers.controllerSelection = 'No controller (context root)';
5916
+ else {
5917
+ const existing = owner.subitem([
5918
+ 'presentation',
5919
+ 'rest'
5920
+ ]).content.subfolderNames.includes(request.controller);
5921
+ answers.controllerSelection = existing ? request.controller : 'New controller';
5922
+ if (!existing) answers.controllerName = request.controller;
5923
+ }
5896
5924
  }
5897
5925
  if ('move' === request.operation) defaults.targetContext = request.context;
5898
5926
  }
package/dist/lint.cjs CHANGED
@@ -238,7 +238,8 @@ const lintChecks = [
238
238
  'layers',
239
239
  'dependencies',
240
240
  'react',
241
- 'clock'
241
+ 'clock',
242
+ 'config'
242
243
  ];
243
244
  const configFileName = 'domain-first.project-structure.config.json';
244
245
  const projectConfigSchema = external_zod_default().object({
@@ -891,7 +892,19 @@ const wiringViolations = (projectRoot, rootFolder, rules)=>{
891
892
  }
892
893
  return violations;
893
894
  };
894
- const clockViolations = (projectRoot, rootFolder)=>{
895
+ const directReadChecks = [
896
+ {
897
+ check: 'clock',
898
+ pattern: /\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g,
899
+ rule: 'domain or application reads the current time directly (use the clock port):'
900
+ },
901
+ {
902
+ check: 'config',
903
+ pattern: /\bprocess\s*\??\.\s*env\b|\bprocess\s*\[\s*(['"`])env\1\s*\]|\bimport\.meta\.env\b/g,
904
+ rule: 'domain or application reads environment variables directly (use the config port):'
905
+ }
906
+ ];
907
+ const directReadViolations = (projectRoot, rootFolder)=>{
895
908
  const root = external_node_path_default().resolve(projectRoot, rootFolder);
896
909
  const folders = [
897
910
  external_node_path_default().join(root, 'shared-kernel'),
@@ -902,21 +915,21 @@ const clockViolations = (projectRoot, rootFolder)=>{
902
915
  ]);
903
916
  return folders.flatMap(sourceFiles).filter((file)=>!isSpec(file)).flatMap((file)=>{
904
917
  const source = external_node_fs_default().readFileSync(file, 'utf8');
905
- return [
906
- ...source.matchAll(/\bnew\s+Date\s*\(\s*\)|\bDate\.now\s*\(/g)
907
- ].map((match)=>({
908
- check: 'clock',
909
- rule: 'domain or application reads the current time directly (use the clock port):',
910
- file,
911
- line: lineAt(source, match.index),
912
- text: match[0]
913
- }));
918
+ return directReadChecks.flatMap(({ check, pattern, rule })=>[
919
+ ...source.matchAll(pattern)
920
+ ].map((match)=>({
921
+ check,
922
+ rule,
923
+ file,
924
+ line: lineAt(source, match.index),
925
+ text: match[0]
926
+ })));
914
927
  });
915
928
  };
916
929
  const lintProject = (projectRoot, rootFolder, { rules = defaultDependencyRules, checks = {} } = {})=>[
917
930
  ...importViolations(projectRoot, rootFolder, rules),
918
931
  ...wiringViolations(projectRoot, rootFolder, rules),
919
- ...clockViolations(projectRoot, rootFolder)
932
+ ...directReadViolations(projectRoot, rootFolder)
920
933
  ].filter((x)=>false !== checks[x.check]);
921
934
  const formatViolations = (violations, projectRoot)=>{
922
935
  const groups = new Map();
@@ -935,7 +948,8 @@ const help = `Usage: df-lint [rootFolder]
935
948
 
936
949
  Reports what breaks the Domain-First rules in the project:
937
950
  bounded context isolation, layers, dependency rules (imports and wiring),
938
- React modules, and reading the time without the clock port.
951
+ React modules, and reading the time or environment variables without
952
+ the clock and config ports.
939
953
  rootFolder defaults to the one in domain-first.project-structure.config.json,
940
954
  whose optional \`backend.rules\` change the dependency rules and turn checks off.
941
955
  Exits with 1 when something is found.
package/dist/lint.js CHANGED
@@ -6,7 +6,8 @@ const help = `Usage: df-lint [rootFolder]
6
6
 
7
7
  Reports what breaks the Domain-First rules in the project:
8
8
  bounded context isolation, layers, dependency rules (imports and wiring),
9
- React modules, and reading the time without the clock port.
9
+ React modules, and reading the time or environment variables without
10
+ the clock and config ports.
10
11
  rootFolder defaults to the one in domain-first.project-structure.config.json,
11
12
  whose optional \`backend.rules\` change the dependency rules and turn checks off.
12
13
  Exits with 1 when something is found.
package/dist/react.cjs CHANGED
@@ -370,7 +370,8 @@ const lintChecks = [
370
370
  'layers',
371
371
  'dependencies',
372
372
  'react',
373
- 'clock'
373
+ 'clock',
374
+ 'config'
374
375
  ];
375
376
  const config_file_configFileName = 'domain-first.project-structure.config.json';
376
377
  const projectConfigSchema = external_zod_default().object({
@@ -1530,10 +1531,11 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
1530
1531
  path: readonly string[];
1531
1532
  }): OpenApiData | undefined => {
1532
1533
  try {
1533
- const [currentBoundedContext, controller, ...relativePath] =
1534
- routeMetadata.path;
1534
+ // The controller, if any, is the first folder of the path:
1535
+ // context-root endpoints live right in presentation/rest.
1536
+ const [currentBoundedContext, ...relativePath] = routeMetadata.path;
1535
1537
 
1536
- if (!currentBoundedContext || !controller) {
1538
+ if (!currentBoundedContext) {
1537
1539
  return undefined;
1538
1540
  }
1539
1541
 
@@ -1543,7 +1545,6 @@ export const createOpenApiDataFromEndpointLogicExtractor = ({
1543
1545
  currentBoundedContext,
1544
1546
  'presentation',
1545
1547
  'rest',
1546
- controller,
1547
1548
  ...relativePath.map(pathParameterAsName),
1548
1549
  \`\${routeMetadata.method.toUpperCase()}.ts\`
1549
1550
  )
@@ -3199,7 +3200,7 @@ const scaffoldRequestSchema = external_zod_default().discriminatedUnion('operati
3199
3200
  agent_requests_operation('endpoint', {
3200
3201
  ...common,
3201
3202
  ...agent_requests_owner,
3202
- controller: agent_requests_name,
3203
+ controller: agent_requests_name.optional().describe('Omit for an endpoint at the context root (`/<context>`); then path is empty or starts with a :param.'),
3203
3204
  method: external_zod_default()["enum"]([
3204
3205
  'get',
3205
3206
  'post',
@@ -5129,46 +5130,45 @@ export const ${names.namespace(ClassName)} = errorNamespace('${boundedContextFol
5129
5130
  const namespaceFile = currentErrorFolder.file(`${namespace}.ts`);
5130
5131
  namespaceFile.addLineIfMissing(errorClass(names.error(`${namespaceNaming.ClassName}${ClassName}`), exportedNamespace(namespaceFile, names.namespace(namespaceNaming.ClassName)), fileName), '\n\n');
5131
5132
  };
5133
+ const newController = 'New controller';
5134
+ const withoutController = 'No controller (context root)';
5135
+ const pathParameterAsName = (segment)=>segment.startsWith(':') ? `_${segment.slice(1)}_` : segment;
5136
+ const isPathParameterName = (name)=>name.startsWith(':') || /^_.+_$/.test(name);
5137
+ const sharedRestFolder = (boundedContextFolder)=>boundedContextFolder.subitem([
5138
+ '..',
5139
+ '..',
5140
+ 'presentation',
5141
+ 'rest'
5142
+ ]);
5132
5143
  const scaffoldNewHandlersRestEndpoint = async (boundedContextFolder)=>{
5133
5144
  const restPresentationFolder = boundedContextFolder.subitem([
5134
5145
  'presentation',
5135
5146
  'rest'
5136
5147
  ]);
5137
- const controllers = restPresentationFolder.content.subfolderNames;
5138
- let controller = await interaction_select({
5148
+ const controllers = restPresentationFolder.content.subfolderNames.filter((x)=>!isPathParameterName(x));
5149
+ let controllerChoice = await interaction_select({
5139
5150
  key: 'controllerSelection',
5140
5151
  message: 'Controller: ',
5141
5152
  choices: [
5142
5153
  ...controllers,
5143
- 'New controller'
5154
+ newController,
5155
+ withoutController
5144
5156
  ]
5145
5157
  });
5146
- if ('New controller' === controller) {
5147
- controller = await interaction_input({
5148
- key: 'controllerName',
5149
- message: 'Name: '
5150
- });
5151
- if (config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire')) {
5152
- boundedContextFolder.subitem([
5153
- 'wiring',
5154
- 'presentation',
5155
- 'rest'
5156
- ]).file('index.ts').addLine(`export * from './${controller}'`);
5157
- const sharedRestFolder = boundedContextFolder.subitem([
5158
- '..',
5159
- '..',
5160
- 'presentation',
5161
- 'rest'
5162
- ]);
5163
- sharedRestFolder.file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
5164
- if (!sharedRestFolder.file('index.ts').exists) sharedRestFolder.createFile('index.ts', `
5165
- import * as wires from './wires'
5166
-
5167
- const restWires = Object.values(wires)
5168
-
5169
- export const restHandlers = restWires.map(x => x().handle)
5170
- `.trim());
5171
- }
5158
+ if (controllerChoice === newController) controllerChoice = await interaction_input({
5159
+ key: 'controllerName',
5160
+ message: 'Name: ',
5161
+ validate: (value)=>value.trim() ? isPathParameterName(value) || value.includes('/') ? 'A controller is one static path segment' : true : `Name is required; pick "${withoutController}" for an endpoint at the context root`
5162
+ });
5163
+ const controller = controllerChoice === withoutController ? void 0 : controllerChoice;
5164
+ const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
5165
+ if (controller && !controllers.includes(controller) && withWiring) {
5166
+ boundedContextFolder.subitem([
5167
+ 'wiring',
5168
+ 'presentation',
5169
+ 'rest'
5170
+ ]).file('index.ts').addLine(`export * from './${controller}'`);
5171
+ sharedRestFolder(boundedContextFolder).file('wires.ts').addLine(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${controller}'`);
5172
5172
  }
5173
5173
  const method = await interaction_select({
5174
5174
  key: 'method',
@@ -5183,21 +5183,32 @@ export const restHandlers = restWires.map(x => x().handle)
5183
5183
  });
5184
5184
  const routeSegments = (await interaction_input({
5185
5185
  key: 'path',
5186
- message: 'Relative path (split by "/"):'
5186
+ message: 'Relative path (split by "/"):',
5187
+ validate: (value)=>{
5188
+ const [first] = value.split('/').filter((x)=>!!x);
5189
+ return controller || !first || first.startsWith(':') ? true : `Without a controller, the path is empty or starts with a path parameter; "${first}" is a controller`;
5190
+ }
5187
5191
  })).split('/').filter((x)=>!!x);
5188
- const pathParameterAsName = (segment)=>segment.startsWith(':') ? `_${segment.slice(1)}_` : segment;
5189
- const controllerFolder = restPresentationFolder.subitem([
5190
- controller
5191
- ]);
5192
- const endpointFolder = controllerFolder.subitem(routeSegments.map(pathParameterAsName));
5193
- const nameBase = `${controller}-${routeSegments.length ? `${routeSegments.map(pathParameterAsName).join('-')}-` : ''}${method}-endpoint`;
5192
+ const folderSegments = [
5193
+ ...controller ? [
5194
+ controller
5195
+ ] : [],
5196
+ ...routeSegments
5197
+ ];
5198
+ const endpointFolder = restPresentationFolder.subitem(folderSegments.map(pathParameterAsName));
5199
+ const nameSegments = [
5200
+ controller ?? boundedContextFolder.name,
5201
+ ...routeSegments
5202
+ ];
5203
+ const nameBase = `${[
5204
+ ...nameSegments.map(pathParameterAsName),
5205
+ method
5206
+ ].join('-')}-endpoint`;
5194
5207
  const endpointClassName = [
5195
- controller,
5196
- ...routeSegments,
5208
+ ...nameSegments,
5197
5209
  method,
5198
5210
  'endpoint'
5199
5211
  ].map((segment)=>segment.startsWith(':') ? pathParameterAsName(segment) : new UnknownFormatNaming(segment).ClassName).join('');
5200
- const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
5201
5212
  const endpointGenerator = findRestEndpointGenerator(boundedContextFolder.subitem([
5202
5213
  '..',
5203
5214
  '..',
@@ -5217,8 +5228,11 @@ export class ${endpointClassName} {
5217
5228
 
5218
5229
  get handle() {
5219
5230
  return this.endpointGenerator(this.handler.handle, {
5220
- route: { method: '${method}', path: ['${boundedContextFolder.name}', '${controller}'${routeSegments.length ? `, ${routeSegments.map((x)=>`'${x}'`).join(', ')}` : ''}] },
5221
- tags: ['${boundedContextFolder.name}: ${controller}'],
5231
+ route: { method: '${method}', path: [${[
5232
+ boundedContextFolder.name,
5233
+ ...folderSegments
5234
+ ].map((x)=>`'${x}'`).join(', ')}] },
5235
+ tags: ['${boundedContextFolder.name}${controller ? `: ${controller}` : ''}'],
5222
5236
  })
5223
5237
  }
5224
5238
  }
@@ -5228,7 +5242,9 @@ export class ${endpointClassName} {
5228
5242
  'wiring',
5229
5243
  'presentation',
5230
5244
  'rest',
5231
- controller
5245
+ ...controller ? [
5246
+ controller
5247
+ ] : []
5232
5248
  ]);
5233
5249
  const wireNameBase = `wire-${nameBase}`;
5234
5250
  const wireNaming = new UnknownFormatNaming(wireNameBase);
@@ -5248,6 +5264,15 @@ export const wire${endpointClassName} = wireClass(
5248
5264
  )
5249
5265
  `.trim());
5250
5266
  wiringFolder.file('index.ts').addLineIfMissing(`export * from './${wireNaming.fileName}'`);
5267
+ if (!controller) sharedRestFolder(boundedContextFolder).file('wires.ts').addLineIfMissing(`export * from '../../bounded-contexts/${boundedContextFolder.name}/wiring/presentation/rest/${wireNaming.fileName}'`);
5268
+ const restHandlersFile = sharedRestFolder(boundedContextFolder).file('index.ts');
5269
+ if (!restHandlersFile.exists) sharedRestFolder(boundedContextFolder).createFile('index.ts', `
5270
+ import * as wires from './wires'
5271
+
5272
+ const restWires = Object.values(wires)
5273
+
5274
+ export const restHandlers = restWires.map(x => x().handle)
5275
+ `.trim());
5251
5276
  }
5252
5277
  };
5253
5278
  const scaffold_new_implementation_kindTitles = {
@@ -5887,12 +5912,15 @@ const answersFor = (command, request, owner)=>{
5887
5912
  if ('error' === request.operation || 'error-namespace' === request.operation) defaults.errorAction = 'error-namespace' === request.operation ? 'New namespace' : request.namespace ? `New error in namespace ${request.namespace}` : 'New error without namespace';
5888
5913
  if ('endpoint' === request.operation) {
5889
5914
  delete answers.controller;
5890
- const existing = owner.subitem([
5891
- 'presentation',
5892
- 'rest'
5893
- ]).content.subfolderNames.includes(request.controller);
5894
- answers.controllerSelection = existing ? request.controller : 'New controller';
5895
- if (!existing) answers.controllerName = request.controller;
5915
+ if (void 0 === request.controller) answers.controllerSelection = 'No controller (context root)';
5916
+ else {
5917
+ const existing = owner.subitem([
5918
+ 'presentation',
5919
+ 'rest'
5920
+ ]).content.subfolderNames.includes(request.controller);
5921
+ answers.controllerSelection = existing ? request.controller : 'New controller';
5922
+ if (!existing) answers.controllerName = request.controller;
5923
+ }
5896
5924
  }
5897
5925
  if ('move' === request.operation) defaults.targetContext = request.context;
5898
5926
  }
@@ -65,7 +65,7 @@ export declare const planUpgrade: (config: unknown, acceptOptional?: (step: Plan
65
65
  add?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
66
66
  remove?: ("queries" | "commands" | "use-cases" | "application-ports" | "repositories" | "domain-services" | "application-services" | "infrastructure-services" | "presentation-services")[] | undefined;
67
67
  }>> | undefined;
68
- lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock", boolean>> | undefined;
68
+ lint?: Partial<Record<"context-isolation" | "shared-kernel" | "layers" | "dependencies" | "react" | "clock" | "config", boolean>> | undefined;
69
69
  } | undefined;
70
70
  } | undefined;
71
71
  frontend?: {
package/dist/upgrade.cjs CHANGED
@@ -249,7 +249,8 @@ const lintChecks = [
249
249
  'layers',
250
250
  'dependencies',
251
251
  'react',
252
- 'clock'
252
+ 'clock',
253
+ 'config'
253
254
  ];
254
255
  const configFileName = 'domain-first.project-structure.config.json';
255
256
  const projectConfigSchema = external_zod_default().object({
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@domain-first/project-structure",
3
3
  "description": "Build and manage your Domain-First project structure with CLI",
4
- "version": "8.4.0",
4
+ "version": "8.5.1",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -42,7 +42,8 @@ Run it from the project root; `rootFolder` defaults to the config's. It resolves
42
42
  - imports against the layers ("Ground rules"; specs excluded);
43
43
  - module files importing kinds the project's dependency rules don't allow (a use case importing a use case, a query importing a command, …), and wired dependencies they don't allow ("Wiring" below, `df-ps-scaffold` rule 3); an implementation importing its own contract is fine;
44
44
  - a widget importing another widget (a widget = the nearest folder under `presentation/react/widgets/` with a `*-widget.tsx`, nested widgets included), UI-kit importing widgets, pages or contexts, shared hooks importing UI-kit, widgets, pages or contexts;
45
- - `new Date()` / `Date.now()` in domain or application (use the `clock` port).
45
+ - `new Date()` / `Date.now()` in domain or application (use the `clock` port);
46
+ - `process.env` / `import.meta.env` in domain or application (use the `config` port).
46
47
 
47
48
  It exits with 1 when anything is found. Checks turned off in the config (`backend.rules.lint`) aren't reported; don't turn checks off yourself.
48
49
 
@@ -40,7 +40,7 @@ npx df-integration --request '{"operation":"add","integrations":["storybook"]}'
40
40
  - `dependencies`: implementation/class name → array of qualified module IDs. Omitted entries keep the generator's checked suggestions; `[]` explicitly selects none when that selection applies. When wiring is off or no candidates exist, omit the group; see the [dependency conditions](agent-operations.md#dependency-keys-and-system-implementations). Every supplied dependency group must apply to the operation. Different primary/test implementations have independent lists.
41
41
  - Aggregate repositories require `withRepository: true` and an `implementation`. Without it, aggregate creation makes no repository.
42
42
  - New implementations use a `contract` ID and, with a branched wire, an explicit `environments` array. Moves use a `module` unit ID and optional `targetContext`, `aggregate` and `name`. `wire-dependency` uses a wiring target ID in `module` plus its `dependencies` entry.
43
- - Endpoints use `controller`, lowercase `method`, relative `path` and a qualified `handler` ID when a wired handler is available. A new controller is created when its name does not exist.
43
+ - Endpoints use `controller`, lowercase `method`, relative `path` and a qualified `handler` ID when a wired handler is available. A new controller is created when its name does not exist; omit `controller` for an endpoint at the context root (`/<context>`, `/<context>/:id`).
44
44
  - Integration-specific fields and script conflict decisions are in the integration request schema. Conflicts require explicit decisions, e.g. `"scriptConflicts": { "storybook": "keep" }`. Configuration changes that require confirmation interactively also require their explicit request field.
45
45
 
46
46
  ## Check the result
@@ -25,7 +25,7 @@ All operations support `dryRun` and `overwrite`. Except `bounded-context`, they
25
25
  | `query` | `name`, `implementation` | `testImplementation`, `dependencies`. Bounded contexts only. |
26
26
  | `port` | `name`, `implementation` | `testImplementation`, `dependencies`. `cross-context` is available only with a neighboring context, never in Shared Kernel. |
27
27
  | `implementation` | `contract`, `implementation` | For a usable branched wire, `environments` is required and nonempty; otherwise omit it. `dependencies` is available for the newly added implementation when wiring applies. |
28
- | `endpoint` | `controller`, `method`, `path` | REST package and generator must exist. With wiring and selectable handlers, provide `handler`. Without selectable handlers, omit it; the generated handler remains `never` and needs a later approved generator rerun. |
28
+ | `endpoint` | `method`, `path`, optional `controller` (omit for the context root; `path` then empty or starting with `:param`) | REST package and generator must exist. With wiring and selectable handlers, provide `handler`. Without selectable handlers, omit it; the generated handler remains `never` and needs a later approved generator rerun. |
29
29
  | `wire-dependency` | `module`, `dependencies` | `module` is a wiring target ID, not a contract/unit ID. Adds only eligible dependencies not already wired to that implementation. |
30
30
  | `move` | `module` | `module` is a unit ID. Optional `name`, `targetContext`, `aggregate`; omitted name/context keep the existing ones. A same-owner entity/value-object keeps its aggregate by default. The target aggregate must exist; the target context must be a discovered, allowed destination for that unit kind. Illegal cross-context imports reject the move. |
31
31
  | `delete` | `module` | `module` is a unit ID. Deletes every file of the unit and its generated references (aggregate barrel re-export, in-memory DB section). Refused with `DELETE_NOT_ALLOWED` and `details.usedBy` while other files import it; nothing changes. |
@@ -57,11 +57,12 @@ Example: `order-confirmation` prepares a message and calls the injected `mailer`
57
57
  | Application / infrastructure service | Used by use cases → application. Only by adapters/repositories → infrastructure. |
58
58
  | Logic infrastructure needs from an application service | Infrastructure never sees application services. Pure logic without ports → domain service. Logic over ports → infrastructure calls the ports directly. Technical (mapping, retries, external API formats) → infrastructure service. |
59
59
  | Clock | Always a port (`clock`, usually in Shared Kernel). A command or query never uses it: the use case reads the time and passes it in the input. |
60
+ | Configuration | Values application logic needs (limits, feature flags) → a port (`config`, usually in Shared Kernel), with methods in the application's terms. Settings only an adapter needs (connection strings, API keys) → that adapter or its infrastructure service reads them; no port. |
60
61
 
61
62
  ## Where it goes
62
63
 
63
64
  - Default: the context that owns the data and rules (`df-ps-plan-feature`, step 3).
64
- - Shared Kernel: technical, ownerless pieces (`clock`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
65
+ - Shared Kernel: technical, ownerless pieces (`clock`, `config`, `mailer` ports, shared HTTP client, errors like `unauthorized`) and **universal** entities / value objects: the same meaning and rules in every context, owned by none (`money`, `email`, `address`). A Shared Kernel domain service holds rules at the junction of these universal types only. Anything with one context's meaning or rules (`order-status`, `customer`) stays in that context, even if other contexts need it; they duplicate it in the models of their own ports.
65
66
  - Another context's data or behavior → an application port in the consuming context (step 9).
66
67
 
67
68
  ## Example
@@ -4,7 +4,7 @@ When: an HTTP entry point (`../choosing-components.md`, step 2). It exposes a qu
4
4
 
5
5
  ## Generate (context only)
6
6
 
7
- Prompts: controller (select: existing | `New controller` → name) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
7
+ Prompts: controller (select: existing | `New controller` → name | `No controller (context root)`) → method (`get` `post` `patch` `delete` `put`) → relative path (may be empty: `default`) → {wire} `Handler:` (select: queries, commands, and use cases of `<C>`, grouped; skipped if there are none).
8
8
 
9
9
  `… pick:Presentation "pick:New Handlers" "pick:New controller" text:orders pick:get text:recent pick:RecentOrdersQuery`
10
10
  `… pick:Presentation "pick:New Handlers" pick:orders pick:post default pick:PlaceOrder`
@@ -15,6 +15,8 @@ For `sales`, `orders`, `get`, `recent`:
15
15
  - {wire} `<C>/wiring/presentation/rest/orders/wire-orders-recent-get-endpoint.ts` (`[wireRestEndpointGeneratorPresentationService, wireRecentOrdersQuery]`; `[]` without the generator file) + a line in that folder's `index.ts`
16
16
  - {wire}, new controller only: `<C>/wiring/presentation/rest/index.ts`, `<rootFolder>/presentation/rest/wires.ts` (lines appended), `<rootFolder>/presentation/rest/index.ts` (`restHandlers`, created once)
17
17
 
18
+ - No controller, context `social-networks`, `get`, empty path: `<C>/presentation/rest/GET.ts`, `class SocialNetworksGetEndpoint`, route `['social-networks']`, tag `'social-networks'`; {wire} `<C>/wiring/presentation/rest/wire-social-networks-get-endpoint.ts`, a line in `<C>/wiring/presentation/rest/index.ts` and one in `<rootFolder>/presentation/rest/wires.ts`. Use it for collection endpoints of the context (`GET /social-networks`, `POST /social-networks`, `GET /social-networks/:id`) instead of a `list` controller or `/social-networks/social-networks`. Its path is empty or starts with `:param`: a static first segment is a controller.
19
+
18
20
  The same controller, path, and method replace the existing endpoint (after `Overwrite them?`). Generate the exposed handler first, so `Handler:` lists it. If `handler: never` is left, re-run the endpoint generator once the handler exists, as an approved overwrite; don't replace it by hand.
19
21
 
20
22
  ## Implement