@domain-first/project-structure 8.6.1 → 8.7.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.
Files changed (51) hide show
  1. package/README.md +1 -1
  2. package/bin/df-skills.mjs +55 -9
  3. package/dist/287.js +44 -138
  4. package/dist/38.js +36 -0
  5. package/dist/561.js +9 -1
  6. package/dist/947.js +11 -1
  7. package/dist/agent-cli.d.ts +9 -2
  8. package/dist/agent-principles.cjs +116 -0
  9. package/dist/agent-principles.d.ts +9 -0
  10. package/dist/agent-principles.js +64 -0
  11. package/dist/agent-principles.spec.d.ts +1 -0
  12. package/dist/agent-requests.d.ts +16 -2
  13. package/dist/graph.cjs +10 -0
  14. package/dist/in-memory-db.d.ts +1 -6
  15. package/dist/index.cjs +64 -137
  16. package/dist/index.js +4 -1
  17. package/dist/init.cjs +12 -21
  18. package/dist/integration.cjs +61 -137
  19. package/dist/lint.cjs +46 -0
  20. package/dist/react.cjs +61 -137
  21. package/dist/use-cases/add-integration.d.ts +1 -1
  22. package/dist/use-cases/index.d.ts +1 -0
  23. package/dist/use-cases/scaffold-new-infrastructure-helper.d.ts +7 -0
  24. package/dist/wiring.d.ts +2 -2
  25. package/package.json +3 -2
  26. package/principles/df-principles.md +33 -0
  27. package/skills/df-ps-implement/SKILL.md +26 -1
  28. package/skills/df-ps-plan-feature/SKILL.md +22 -18
  29. package/skills/df-ps-react/SKILL.md +2 -9
  30. package/skills/df-ps-react/references/generators.md +9 -9
  31. package/skills/df-ps-scaffold/SKILL.md +20 -126
  32. package/skills/df-ps-scaffold/references/agent-mode.md +2 -2
  33. package/skills/df-ps-scaffold/references/agent-operations.md +1 -0
  34. package/skills/df-ps-scaffold/references/choosing-components.md +65 -49
  35. package/skills/df-ps-scaffold/references/generators.md +33 -11
  36. package/skills/df-ps-scaffold/references/units/aggregate.md +3 -5
  37. package/skills/df-ps-scaffold/references/units/bounded-context.md +1 -1
  38. package/skills/df-ps-scaffold/references/units/command-query.md +6 -8
  39. package/skills/df-ps-scaffold/references/units/delete.md +0 -2
  40. package/skills/df-ps-scaffold/references/units/endpoint.md +1 -4
  41. package/skills/df-ps-scaffold/references/units/entity-value-object.md +0 -4
  42. package/skills/df-ps-scaffold/references/units/errors.md +0 -4
  43. package/skills/df-ps-scaffold/references/units/helper.md +30 -0
  44. package/skills/df-ps-scaffold/references/units/implementation.md +1 -5
  45. package/skills/df-ps-scaffold/references/units/move-or-rename.md +0 -4
  46. package/skills/df-ps-scaffold/references/units/port.md +3 -6
  47. package/skills/df-ps-scaffold/references/units/services.md +4 -6
  48. package/skills/df-ps-scaffold/references/units/use-case.md +1 -2
  49. package/skills/df-ps-scaffold/references/units/wire-dependency.md +0 -2
  50. package/skills/df-ps-scaffold/references/work-plan.md +73 -0
  51. package/skills/df-ps-scaffold/scripts/drive.mjs +0 -252
package/dist/react.cjs CHANGED
@@ -641,7 +641,17 @@ const findWiredModules = (contextPath)=>{
641
641
  const moduleKindOf = (module)=>wiredModuleKind(module.kind);
642
642
  const layerRule = (consumer, candidate)=>visibleLayers[consumer.implementationsLayer].includes(candidate.layer) && ('infrastructure' !== consumer.implementationsLayer || 'application' !== candidate.layer || 'application-ports' === candidate.kind);
643
643
  const wiring_implementationType = (consumer, implementation)=>consumer.branched ? external_node_path_default().basename(external_node_path_default().dirname(implementation.file)) : void 0;
644
- const isSuggestedFor = (candidate, implementation)=>'infrastructure' === candidate.layer && `-${external_node_path_default().basename(candidate.typeFile, '.ts')}-`.includes(`-${implementation}-`);
644
+ const systemInfrastructureServices = new Map([
645
+ [
646
+ 'prisma',
647
+ 'prisma-infrastructure-service'
648
+ ],
649
+ [
650
+ 'in-memory',
651
+ 'in-memory-db-infrastructure-service'
652
+ ]
653
+ ]);
654
+ const isSuggestedFor = (candidate, implementation)=>'infrastructure' === candidate.layer && external_node_path_default().basename(candidate.typeFile, '.ts') === systemInfrastructureServices.get(implementation);
645
655
  const canDependOn = (consumer, candidate, rules = defaultDependencyRules, implementation = consumer.implementations[0])=>{
646
656
  const crossContext = crossContextImportAllowed(consumer.wireFile, candidate.wireFile);
647
657
  if (void 0 !== crossContext) return crossContext && 'infrastructure' === consumer.implementationsLayer && 'application' === candidate.layer && !!implementation && true === crossContextImportAllowed(implementation.file, candidate.typeFile);
@@ -1013,23 +1023,6 @@ export const wireInMemoryDbInfrastructureService = wireClass(
1013
1023
  []
1014
1024
  );
1015
1025
  `;
1016
- const inMemoryDbSpec = (testingLibrary, withWiring)=>`
1017
- import { describe, test, expect, beforeEach } from '${testingLibrary}'
1018
- ${withWiring ? `import { type InMemoryDbInfrastructureService } from './in-memory-db-infrastructure-service'
1019
- import { wireInMemoryDbInfrastructureService } from '../../wiring/infrastructure-services/wire-in-memory-db-infrastructure-service'` : "import { InMemoryDbInfrastructureService } from './in-memory-db-infrastructure-service'"}
1020
-
1021
- let inMemoryDbInfrastructureService: InMemoryDbInfrastructureService
1022
-
1023
- beforeEach(() => {
1024
- inMemoryDbInfrastructureService = ${withWiring ? 'wireInMemoryDbInfrastructureService()' : 'new InMemoryDbInfrastructureService()'}
1025
- })
1026
-
1027
- describe('in memory db', () => {
1028
- test('can be ${withWiring ? 'wired' : 'created'}', () => {
1029
- expect(inMemoryDbInfrastructureService).toBeDefined()
1030
- })
1031
- })
1032
- `.trim();
1033
1026
  const in_memory_db_withWiring = ()=>config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
1034
1027
  const in_memory_db_sharedFolder = ()=>new file_system_Folder(new project_root_ProjectRoot().path).subitem([
1035
1028
  config_file_ConfigFile.Instance.data.project.rootFolder,
@@ -1046,13 +1039,11 @@ const in_memory_db_wireFile = ()=>new file_system_File(in_memory_db_sharedFolder
1046
1039
  'wire-in-memory-db-infrastructure-service.ts'
1047
1040
  ]);
1048
1041
  const in_memory_db_scaffoldInMemoryDb = (shared)=>{
1049
- const { testingLibrary } = config_file_ConfigFile.backend;
1050
1042
  const servicesFolder = shared.subitem([
1051
1043
  'infrastructure',
1052
1044
  'services'
1053
1045
  ]);
1054
1046
  servicesFolder.createFile('in-memory-db-infrastructure-service.ts', inMemoryDbService);
1055
- if (testingLibrary) servicesFolder.createFile('in-memory-db-infrastructure-service.spec.ts', inMemoryDbSpec(testingLibrary, in_memory_db_withWiring()));
1056
1047
  if (in_memory_db_withWiring()) shared.subitem([
1057
1048
  'wiring',
1058
1049
  'infrastructure-services'
@@ -1114,9 +1105,6 @@ const wireInMemoryDb = (consumerWireFile, implementationName)=>{
1114
1105
  in_memory_db_wireName
1115
1106
  ]));
1116
1107
  };
1117
- const passInMemoryDb = (specFile, implementationName)=>{
1118
- specFile.update(addImport(specFile.data, `import { ${in_memory_db_className} } from '${relativeImport(specFile.path, serviceFile().path)}'`).replace(`new ${implementationName}()`, `new ${implementationName}(new ${in_memory_db_className}())`));
1119
- };
1120
1108
  const addInMemoryDb = ()=>{
1121
1109
  const config = config_file_ConfigFile.Instance.data;
1122
1110
  if (!config_file_ConfigFile.backend.withInMemoryDb) config_file_ConfigFile.update({
@@ -3176,6 +3164,12 @@ const scaffoldRequestSchema = external_zod_default().discriminatedUnion('operati
3176
3164
  ...named,
3177
3165
  ...agent_requests_wired
3178
3166
  }),
3167
+ agent_requests_operation('helper', {
3168
+ ...common,
3169
+ ...agent_requests_owner,
3170
+ name: agent_requests_nestedName.describe('Kebab-case, folders split by "/": mappers/social-network-type.'),
3171
+ implementationType: agent_requests_name.describe('A saved or system implementation type: a helper belongs to one.')
3172
+ }),
3179
3173
  agent_requests_operation('presentation-service', {
3180
3174
  ...named,
3181
3175
  ...agent_requests_wired
@@ -4697,29 +4691,6 @@ describe('${aggregateNaming.withSpaces}', () => {
4697
4691
  labels: []
4698
4692
  };
4699
4693
  for (const implementation of implementationTypes)createImplementation(boundedContextFolder, repository, new UnknownFormatNaming(implementation).fileName);
4700
- if (scaffoldUnitTests) {
4701
- const implementationNaming = new UnknownFormatNaming(infrastructureImplementationType);
4702
- const specFile = aggregatesFolder.createFile(`${aggregateNaming.fileName}-repository.spec.ts`, `
4703
- import { describe, test, expect, beforeEach } from '${config_file_ConfigFile.backend.testingLibrary}'
4704
- ${config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') ? `import { wire${aggregateNaming.ClassName}Repository } from '../../../wiring/repositories/wire-${aggregateNaming.fileName}-repository'
4705
- import type { ${aggregateNaming.ClassName}Repository } from './${aggregateNaming.fileName}-repository'` : `import { ${implementationNaming.ClassName}${aggregateNaming.ClassName}Repository } from '../../../infrastructure/repositories/${implementationNaming.fileName}/${implementationNaming.fileName}-${aggregateNaming.fileName}-repository'
4706
-
4707
- type ${aggregateNaming.ClassName}Repository = ${implementationNaming.ClassName}${aggregateNaming.ClassName}Repository`}
4708
-
4709
- let ${aggregateNaming.variableName}Repository: ${aggregateNaming.ClassName}Repository
4710
-
4711
- beforeEach(() => {
4712
- ${aggregateNaming.variableName}Repository = ${config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') ? `wire${aggregateNaming.ClassName}Repository()` : `new ${implementationNaming.ClassName}${aggregateNaming.ClassName}Repository()`}
4713
- })
4714
-
4715
- describe('${aggregateNaming.withSpaces} repository', () => {
4716
- test('can be ${config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') ? 'wired' : 'created via constructor'}', () => {
4717
- expect(${aggregateNaming.variableName}Repository).toBeDefined()
4718
- })
4719
- })
4720
- `.trim());
4721
- if (!config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') && usesInMemoryDb(infrastructureImplementationType)) passInMemoryDb(specFile, `${implementationNaming.ClassName}${aggregateNaming.ClassName}Repository`);
4722
- }
4723
4694
  if (config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire')) {
4724
4695
  const implementationNaming = new UnknownFormatNaming(infrastructureImplementationType);
4725
4696
  const testImplementationNaming = new UnknownFormatNaming(testImplementationType);
@@ -4745,7 +4716,6 @@ const scaffoldNewApplicationPort = async (boundedContextFolder)=>{
4745
4716
  message: 'Name: '
4746
4717
  });
4747
4718
  const naming = new UnknownFormatNaming(name);
4748
- const scaffoldUnitTests = Boolean(config_file_ConfigFile.backend.testingLibrary);
4749
4719
  const wiringFolder = boundedContextFolder.subitem([
4750
4720
  'wiring',
4751
4721
  'application-ports'
@@ -4785,28 +4755,6 @@ export abstract class ${naming.ClassName} {
4785
4755
  ownerPath: boundedContextFolder.path,
4786
4756
  labels: []
4787
4757
  }, implementation);
4788
- if (scaffoldUnitTests) {
4789
- const implementationNaming = new UnknownFormatNaming(implementationType);
4790
- applicationPortsFolder.createFile(`${naming.fileName}.spec.ts`, `
4791
- import { describe, test, expect, beforeEach } from '${config_file_ConfigFile.backend.testingLibrary}'
4792
- ${config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') ? `import { type ${naming.ClassName} } from './${naming.fileName}'
4793
- import { wire${naming.ClassName} } from '../../wiring/application-ports/wire-${naming.fileName}'` : `import { ${implementationNaming.ClassName}${naming.ClassName} } from '../../infrastructure/application-adapters/${implementationNaming.fileName}/${implementationNaming.fileName}-${naming.fileName}'
4794
-
4795
- type ${naming.ClassName} = ${implementationNaming.ClassName}${naming.ClassName}`}
4796
-
4797
- let ${naming.variableName}: ${naming.ClassName}
4798
-
4799
- beforeEach(() => {
4800
- ${naming.variableName} = ${config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') ? `wire${naming.ClassName}()` : `new ${implementationNaming.ClassName}${naming.ClassName}()`}
4801
- })
4802
-
4803
- describe('${naming.withSpaces}', () => {
4804
- test('can be ${config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') ? 'wired' : 'created via constructor'}', () => {
4805
- expect(${naming.variableName}).toBeDefined()
4806
- })
4807
- })
4808
- `.trim());
4809
- }
4810
4758
  if (config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire')) {
4811
4759
  const wireFile = wiringFolder.createFile(`wire-${naming.fileName}.ts`, `
4812
4760
  import { wireClass } from '@domain-first/wire'
@@ -4902,9 +4850,7 @@ const scaffoldNewCommand = async (boundedContextFolder)=>{
4902
4850
  key: 'name',
4903
4851
  message: 'Name: '
4904
4852
  });
4905
- const scaffoldUnitTests = Boolean(config_file_ConfigFile.backend.testingLibrary);
4906
4853
  const naming = new UnknownFormatNaming(commandName);
4907
- const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
4908
4854
  const { label: implementationType } = await promptImplementationType('Command infrastructure implementation type:', 'commands');
4909
4855
  let addTestImplementation = false;
4910
4856
  let testImplementationType = '';
@@ -4942,29 +4888,6 @@ export abstract class ${naming.ClassName}Command {
4942
4888
  export abstract class ${naming.ClassName}Command {
4943
4889
 
4944
4890
  }`.trim());
4945
- if (scaffoldUnitTests) {
4946
- const implementationNaming = new UnknownFormatNaming(implementationType);
4947
- const specFile = commandsFolder.createFile(`${naming.fileName}-command.spec.ts`, `
4948
- import { describe, test, expect, beforeEach } from '${config_file_ConfigFile.backend.testingLibrary}'
4949
- ${withWiring ? `import { type ${naming.ClassName}Command } from './${naming.fileName}-command'
4950
- import { wire${naming.ClassName}Command } from '../../wiring/commands/wire-${naming.fileName}-command'` : `import { ${implementationNaming.ClassName}${naming.ClassName}Command } from '../../infrastructure/commands/${implementationNaming.fileName}/${implementationNaming.fileName}-${naming.fileName}-command'
4951
-
4952
- type ${naming.ClassName}Command = ${implementationNaming.ClassName}${naming.ClassName}Command`}
4953
-
4954
- let ${naming.variableName}Command: ${naming.ClassName}Command
4955
-
4956
- beforeEach(() => {
4957
- ${naming.variableName}Command = ${withWiring ? `wire${naming.ClassName}Command()` : `new ${implementationNaming.ClassName}${naming.ClassName}Command()`}
4958
- })
4959
-
4960
- describe('${naming.withSpaces} command', () => {
4961
- test('can be ${withWiring ? 'wired' : 'created via constructor'}', () => {
4962
- expect(${naming.variableName}Command).toBeDefined()
4963
- })
4964
- })
4965
- `.trim());
4966
- if (!withWiring && usesInMemoryDb(implementationType)) passInMemoryDb(specFile, `${implementationNaming.ClassName}${naming.ClassName}Command`);
4967
- }
4968
4891
  if (config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire')) {
4969
4892
  const implementationNaming = new UnknownFormatNaming(implementationType);
4970
4893
  const testImplementationNaming = new UnknownFormatNaming(testImplementationType);
@@ -5414,13 +5337,54 @@ const scaffoldNewImplementation = async (ownerFolder)=>{
5414
5337
  for (const implementation of unused)report(`${implementation.className} is no longer used in any environment.`);
5415
5338
  await wireNewImplementationDependencies(ownerFolder, wireFile, className, inMemoryRepositoryWiring(ownerFolder, unit, wireFile));
5416
5339
  };
5340
+ const helperImplementationTypes = ()=>[
5341
+ ...new Set(implementationKinds.flatMap((kind)=>[
5342
+ ...savedImplementations(kind, 'primary'),
5343
+ ...savedImplementations(kind, 'test'),
5344
+ ...systemImplementationChoices(kind).map(({ value })=>value)
5345
+ ]))
5346
+ ].filter((label)=>label !== crossContextImplementation);
5347
+ const validateName = (value)=>{
5348
+ const valid = NestedName.validate(value);
5349
+ if (true !== valid) return valid;
5350
+ const { folders, folderName } = new NestedName(value);
5351
+ return [
5352
+ ...folders,
5353
+ folderName
5354
+ ].every((part)=>kebabName.test(part)) ? true : 'Use lowercase kebab-case split by "/", e.g. mappers/social-network-type';
5355
+ };
5356
+ const scaffoldNewInfrastructureHelper = async (ownerFolder)=>{
5357
+ const types = helperImplementationTypes();
5358
+ if (!types.length) return void report('No implementation types yet: a helper belongs to one, so add an implementation first.');
5359
+ const name = new NestedName(await interaction_input({
5360
+ key: 'name',
5361
+ message: 'Name (folders split by "/"): ',
5362
+ validate: validateName
5363
+ }));
5364
+ const label = await interaction_select({
5365
+ key: 'implementationType',
5366
+ message: 'Implementation:',
5367
+ choices: types.map((value)=>({
5368
+ name: value,
5369
+ value
5370
+ }))
5371
+ });
5372
+ const fileName = name.folderName.startsWith(`${label}-`) ? name.folderName : `${label}-${name.folderName}`;
5373
+ const naming = new UnknownFormatNaming(fileName);
5374
+ const folder = ownerFolder.subitem([
5375
+ 'infrastructure',
5376
+ 'helpers',
5377
+ label,
5378
+ ...name.folders
5379
+ ]);
5380
+ folder.createFile(`${fileName}.ts`, `export const ${naming.variableName} = () => {}`);
5381
+ };
5417
5382
  const scaffoldNewInfrastructureService = async (boundedContextFolder)=>{
5418
5383
  const name = await interaction_input({
5419
5384
  key: 'name',
5420
5385
  message: 'Name: '
5421
5386
  });
5422
5387
  const naming = new UnknownFormatNaming(name);
5423
- const scaffoldUnitTests = Boolean(config_file_ConfigFile.backend.testingLibrary);
5424
5388
  const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
5425
5389
  const wiringFolder = boundedContextFolder.subitem([
5426
5390
  'wiring',
@@ -5435,23 +5399,6 @@ export class ${naming.ClassName}InfrastructureService {
5435
5399
 
5436
5400
  }
5437
5401
  `.trim());
5438
- if (scaffoldUnitTests) infrastructureServicesFolder.createFile(`${naming.fileName}-infrastructure-service.spec.ts`, `
5439
- import { describe, test, expect, beforeEach } from '${config_file_ConfigFile.backend.testingLibrary}'
5440
- ${withWiring ? `import { type ${naming.ClassName}InfrastructureService } from './${naming.fileName}-infrastructure-service'
5441
- import { wire${naming.ClassName}InfrastructureService } from '../../wiring/infrastructure-services/wire-${naming.fileName}-infrastructure-service'` : `import { ${naming.ClassName}InfrastructureService } from './${naming.fileName}-infrastructure-service'`}
5442
-
5443
- let ${naming.variableName}InfrastructureService: ${naming.ClassName}InfrastructureService
5444
-
5445
- beforeEach(() => {
5446
- ${naming.variableName}InfrastructureService = ${withWiring ? `wire${naming.ClassName}InfrastructureService()` : `new ${naming.ClassName}InfrastructureService()`}
5447
- })
5448
-
5449
- describe('${naming.withSpaces}', () => {
5450
- test('can be ${withWiring ? 'wired' : 'created'}', () => {
5451
- expect(${naming.variableName}InfrastructureService).toBeDefined()
5452
- })
5453
- })
5454
- `.trim());
5455
5402
  if (withWiring) {
5456
5403
  const wireFile = wiringFolder.createFile(`wire-${naming.fileName}-infrastructure-service.ts`, `
5457
5404
  import { wireClass } from '@domain-first/wire'
@@ -5474,9 +5421,7 @@ const scaffoldNewQuery = async (boundedContextFolder)=>{
5474
5421
  key: 'name',
5475
5422
  message: 'Name: '
5476
5423
  });
5477
- const scaffoldUnitTests = Boolean(config_file_ConfigFile.backend.testingLibrary);
5478
5424
  const naming = new UnknownFormatNaming(queryName);
5479
- const withWiring = config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire');
5480
5425
  const { label: implementationType } = await promptImplementationType('Query infrastructure implementation type:', 'queries');
5481
5426
  let addTestImplementation = false;
5482
5427
  let testImplementationType = '';
@@ -5514,29 +5459,6 @@ export abstract class ${naming.ClassName}Query {
5514
5459
  export abstract class ${naming.ClassName}Query {
5515
5460
 
5516
5461
  }`.trim());
5517
- if (scaffoldUnitTests) {
5518
- const implementationNaming = new UnknownFormatNaming(implementationType);
5519
- const specFile = queriesFolder.createFile(`${naming.fileName}-query.spec.ts`, `
5520
- import { describe, test, expect, beforeEach } from '${config_file_ConfigFile.backend.testingLibrary}'
5521
- ${withWiring ? `import { type ${naming.ClassName}Query } from './${naming.fileName}-query'
5522
- import { wire${naming.ClassName}Query } from '../../wiring/queries/wire-${naming.fileName}-query'` : `import { ${implementationNaming.ClassName}${naming.ClassName}Query } from '../../infrastructure/queries/${implementationNaming.fileName}/${implementationNaming.fileName}-${naming.fileName}-query'
5523
-
5524
- type ${naming.ClassName}Query = ${implementationNaming.ClassName}${naming.ClassName}Query`}
5525
-
5526
- let ${naming.variableName}Query: ${naming.ClassName}Query
5527
-
5528
- beforeEach(() => {
5529
- ${naming.variableName}Query = ${withWiring ? `wire${naming.ClassName}Query()` : `new ${implementationNaming.ClassName}${naming.ClassName}Query()`}
5530
- })
5531
-
5532
- describe('${naming.withSpaces} query', () => {
5533
- test('can be ${withWiring ? 'wired' : 'created via constructor'}', () => {
5534
- expect(${naming.variableName}Query).toBeDefined()
5535
- })
5536
- })
5537
- `.trim());
5538
- if (!withWiring && usesInMemoryDb(implementationType)) passInMemoryDb(specFile, `${implementationNaming.ClassName}${naming.ClassName}Query`);
5539
- }
5540
5462
  if (config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire')) {
5541
5463
  const implementationNaming = new UnknownFormatNaming(implementationType);
5542
5464
  const testImplementationNaming = new UnknownFormatNaming(testImplementationType);
@@ -5986,6 +5908,7 @@ const executeScaffold = async (request, owner)=>{
5986
5908
  ]).content.fileNames.includes(request.namespace)) throw new RequestError('TARGET_NOT_FOUND', `Unknown namespace: ${request.namespace}.`);
5987
5909
  if ('implementation' === request.operation && !findContracts(owner.path).length) throw new RequestError('TARGET_NOT_FOUND', 'No contracts in this context.');
5988
5910
  if (('move' === request.operation || 'delete' === request.operation) && !findBackendUnits(owner.path).length) throw new RequestError('TARGET_NOT_FOUND', 'No modules in this context.');
5911
+ if ('helper' === request.operation && !helperImplementationTypes().length) throw new RequestError('TARGET_NOT_FOUND', 'No implementation types yet: add an implementation first.');
5989
5912
  if ('wire-dependency' === request.operation && (!config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/wire') || !findWiredModules(owner.path).length)) throw new RequestError('TARGET_NOT_FOUND', 'No wired modules in this context.');
5990
5913
  if ('endpoint' === request.operation) {
5991
5914
  if (!config_file_ConfigFile.backend.domainFirstPackages.includes('@domain-first/handlers-rest') || !findRestEndpointGenerator(new file_system_Folder(requireProject()).subitem([
@@ -6006,6 +5929,7 @@ const executeScaffold = async (request, owner)=>{
6006
5929
  'domain-service': ()=>scaffoldNewDomainService(owner),
6007
5930
  'application-service': ()=>scaffoldNewApplicationService(owner),
6008
5931
  'infrastructure-service': ()=>scaffoldNewInfrastructureService(owner),
5932
+ helper: ()=>scaffoldNewInfrastructureHelper(owner),
6009
5933
  'presentation-service': ()=>scaffoldNewPresentationService(owner),
6010
5934
  'use-case': ()=>scaffoldNewUseCase(owner),
6011
5935
  command: ()=>scaffoldNewCommand(owner),
@@ -9,7 +9,7 @@ export declare const addIntegration: ({ save }?: {
9
9
  save?: boolean;
10
10
  }) => Promise<string[]>;
11
11
  export declare const integrationDescriptions: () => {
12
- id: "openapi" | "orval" | "prisma" | "rest-endpoint-generator" | "storybook" | "vitest" | "testcontainers" | "in-memory-db" | "playwright";
12
+ id: "prisma" | "openapi" | "orval" | "rest-endpoint-generator" | "storybook" | "vitest" | "testcontainers" | "in-memory-db" | "playwright";
13
13
  name: string;
14
14
  group: "backend" | "frontend";
15
15
  available: boolean;
@@ -14,6 +14,7 @@ export * from './scaffold-new-domain-service';
14
14
  export * from './scaffold-new-error';
15
15
  export * from './scaffold-new-handlers-rest-endpoint';
16
16
  export * from './scaffold-new-implementation';
17
+ export * from './scaffold-new-infrastructure-helper';
17
18
  export * from './scaffold-new-infrastructure-service';
18
19
  export * from './scaffold-new-presentation-service';
19
20
  export * from './scaffold-new-query';
@@ -0,0 +1,7 @@
1
+ import type { Folder } from '../file-system';
2
+ /**
3
+ * Every implementation type the project knows, of any kind: a helper is
4
+ * shared between the repositories, commands, queries and ports of a type.
5
+ */
6
+ export declare const helperImplementationTypes: () => string[];
7
+ export declare const scaffoldNewInfrastructureHelper: (ownerFolder: Folder) => Promise<void>;
package/dist/wiring.d.ts CHANGED
@@ -55,8 +55,8 @@ export declare const moduleKindOf: (module: WiredModule) => "queries" | "command
55
55
  */
56
56
  export declare const implementationType: (consumer: WiredModule, implementation: WiredClass) => string | undefined;
57
57
  /**
58
- * An infrastructure module whose file name has the implementation label
59
- * as whole words: `in-memory-db-infrastructure-service` for `in-memory`.
58
+ * Only the system service of the implementation is suggested: any other
59
+ * service is chosen by hand, whatever its name says.
60
60
  */
61
61
  export declare const isSuggestedFor: (candidate: WiredModule, implementation: string) => boolean;
62
62
  export declare const canDependOn: (consumer: WiredModule, candidate: WiredModule, rules?: DependencyRules, implementation?: WiredClass) => boolean;
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.6.1",
4
+ "version": "8.7.1",
5
5
  "type": "module",
6
6
  "repository": {
7
7
  "type": "git",
@@ -31,7 +31,8 @@
31
31
  "files": [
32
32
  "dist",
33
33
  "bin",
34
- "skills"
34
+ "skills",
35
+ "principles"
35
36
  ],
36
37
  "publishConfig": {
37
38
  "access": "public"
@@ -0,0 +1,33 @@
1
+ # Programming principles
2
+
3
+ ## Naming instead of comments
4
+
5
+ Code documents itself through names. If something is unclear without a comment, rename or restructure the code first.
6
+
7
+ Keep a comment only for non-standard behavior the code can't show: a non-obvious decision, a workaround for a library quirk, a security requirement.
8
+
9
+ ```ts
10
+ // Bad: the comment restates the name
11
+ /** Domain social network → database enum value */
12
+ socialNetworkIdToPrisma(x: SocialNetworkId) { … }
13
+
14
+ // Good: explains a decision the code doesn't show
15
+ // Another author's post is reported as missing so we don't reveal that it exists
16
+ if (!post || !post.isAuthoredBy(requesterId)) { … }
17
+ ```
18
+
19
+ A `TODO(...)` is a task, not an explanation: keep it.
20
+
21
+ The one exception: modules of the application layer have a required JSDoc block on the class, in the format of the `df-ps-implement` skill.
22
+
23
+ ## Code reads like plain English
24
+
25
+ Read a line aloud: it should sound like a sentence about the domain, not a puzzle. Spell words out (`requesterId`, not `reqId`; `id` and `url` are fine), name a boolean state with a plain adjective (`enabled`, `published`) and use `has` or `can` where the meaning needs a verb (`hasPosts`, `canEdit`), name functions with verbs, and give a complex condition a name of its own. Prefer a getter for a synchronous check without side effects: `order.hasItems`, not `order.hasItems()`. A check that takes an argument stays a method: `post.hasAuthor(requesterId)`.
26
+
27
+ ```ts
28
+ // Bad
29
+ if (p.uid === rid && !p.del && p.pubAt) { … }
30
+
31
+ // Good
32
+ if (post.hasAuthor(requesterId) && post.published) { … }
33
+ ```
@@ -43,7 +43,7 @@ Run it from the project root; `rootFolder` defaults to the config's. It resolves
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
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
+ - `process.env` / `import.meta.env` in domain or application (use the `application-config` port).
47
47
 
48
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.
49
49
 
@@ -51,6 +51,31 @@ It exits with 1 when anything is found. Checks turned off in the config (`backen
51
51
 
52
52
  How to fill in each unit (aggregate, entity, value object, errors, services, use case, command, query, port, endpoint) is in the "Implement" and "Test" sections of `df-ps-scaffold/references/units/<unit>.md`. Read the files of the units you implement; the rules below apply to all of them.
53
53
 
54
+ ## Application modules get a summary and a description
55
+
56
+ Every scaffolded module of the application layer gets a JSDoc block on its class: application services, ports, commands, queries and use cases. For commands, queries and ports it goes on the abstract contract. The block is required even when the summary stays close to the name.
57
+
58
+ Other layers don't need one. Domain modules, repository contracts included, document themselves through their names and schemas; infrastructure and presentation modules follow the contracts documented in the application layer. Anything non-standard there gets a regular comment.
59
+
60
+ The block:
61
+
62
+ - Summary: the first line, without a tag. Says **what** the module is for, not how it works. One sentence.
63
+ - `@description`: its own section after the summary, only when there are extra details: edge cases, non-obvious decisions, errors with a special meaning. The tag stands on its own line, the text starts on the next one.
64
+
65
+ ```ts
66
+ /**
67
+ * Obtains a whole post of the requesting author.
68
+ *
69
+ * @description
70
+ * Throws `ItemNotFoundSharedKernelError` both when the post doesn't exist and
71
+ * when its author isn't the requester: for security, posts of other users must
72
+ * not be revealed.
73
+ */
74
+ export abstract class OwnPostQuery { … }
75
+ ```
76
+
77
+ What the description says doesn't need to be repeated in a comment inside the class.
78
+
54
79
  ## Wiring ({wire})
55
80
 
56
81
  Dependencies (constructor parameters and their wires) are added only by `df-scaffold` (`df-ps-scaffold`, rule 3): the generator's `Dependencies:` step or `Wire dependency`. It keeps each `wireClass(X, [...])` in the order of the constructor, which TypeScript checks:
@@ -5,7 +5,7 @@ description: Turn an abstract feature request into a Domain-First plan for a pro
5
5
 
6
6
  # Plan a feature
7
7
 
8
- Understand → decompose → assign → get approval → hand off. A feature creates files, so nothing is generated or written before approval (`df-ps-scaffold`, rule 1).
8
+ Understand → decompose → assign → get approval → hand off. A feature creates files, so nothing is generated or written before approval (`df-ps-scaffold`, rule 1). Only the user's literal request to skip the plan ("skip the plan", "with plan skipped", etc.) removes this step. However direct or urgent any other wording sounds, it is a request to write the plan.
9
9
 
10
10
  ## 1. Understand what exists
11
11
 
@@ -33,12 +33,13 @@ Split the request into pieces of logic and choose each piece's component with `d
33
33
  2. Extend an existing context when the concept fits its language and lifecycle (the normal case).
34
34
  3. Create a new context only for a concept with its own lifecycle and vocabulary, or a different business owner. Never one context per feature.
35
35
  4. Domain and application stay isolated. Every need for another context's data or behavior is an **application port** in the consuming context, with its own duplicated models. The implementation can be replaced when a context becomes a separate service. Choose the simplest available way, respecting the user's requested transport:
36
- - Both contexts run in the same application → a port adapter with the reserved type `cross-context`. It may inject the neighboring context's queries, commands and use cases. Only the adapter imports the handler type; its wiring imports the handler factory. No transport or endpoint is needed. Check that the providing handler exists; plan it if missing.
37
- - A direct handler call is unavailable or a database integration is requested, and both contexts use the same database → query it directly (the persistence label, e.g. `prisma`).
38
- - Otherwise, look for the ways the project already reaches a context besides its REST endpoints: message queue, RPC, events, generated API clients. Several options (REST counts) → ask the user which one in "Decisions for you", with a recommendation. Never pick silently.
39
- - Nothing besides REST → the providing context's REST endpoint (`http`).
36
+ - Both contexts run in the same application → a port adapter with the reserved type `cross-context`. It may inject the neighboring context's queries, commands and use cases. Only the adapter imports the handler type; its wiring imports the handler factory. No transport or endpoint is needed. Check that the providing handler exists; plan it if missing.
37
+ - A direct handler call is unavailable or a database integration is requested, and both contexts use the same database → query it directly (the persistence label, e.g. `prisma`).
38
+ - Otherwise, look for the ways the project already reaches a context besides its REST endpoints: message queue, RPC, events, generated API clients. Several options (REST counts) → ask the user which one in "Decisions for you", with a recommendation. Never pick silently.
39
+ - Nothing besides REST → the providing context's REST endpoint (`http`).
40
+
41
+ For transport implementations, plan **both sides**: check that the providing context exposes what the call needs (endpoint, queue consumer…). If not, add it (and the handler behind it: a query or command, or a use case only when one query or command isn't enough) to the plan.
40
42
 
41
- For transport implementations, plan **both sides**: check that the providing context exposes what the call needs (endpoint, queue consumer…). If not, add it (and the handler behind it: a query or command, or a use case only when one query or command isn't enough) to the plan.
42
43
  5. `shared-kernel/` holds technical, ownerless pieces and universal entities / value objects (`money`, `email`): the same meaning in every context, owned by none. Never a concept with one context's meaning or rules.
43
44
  6. Names: kebab-case, in the context's language. Contexts are business areas (`sales`, `reviews`), not features.
44
45
 
@@ -56,7 +57,7 @@ Never: pick silently, put one context's domain logic in `shared-kernel/`, create
56
57
 
57
58
  ## 4. Present the plan
58
59
 
59
- One message in the `df-ps-scaffold` rule 1 format, then stop. The architecture lives in it: each context block's "Why here" is the ownership decision of step 3, each row's Why the component choice of step 2, and open decisions go to Question.
60
+ One message in the format of `df-ps-scaffold/references/work-plan.md`, then stop. The architecture lives in it: each context block's "Why here" is the ownership decision of step 3, each row's Why the component choice of step 2, and open decisions go to Question.
60
61
 
61
62
  ```markdown
62
63
  **Plan: product reviews**
@@ -69,13 +70,13 @@ Why here: reviews have their own lifecycle and moderation; no context owns them.
69
70
 
70
71
  What will be scaffolded:
71
72
 
72
- | Layer | Type | Name | Details | Why |
73
- | --- | --- | --- | --- | --- |
74
- | **domain** | aggregate | review | repository prisma, in-memory in tests | consistency boundary with moderation |
75
- | | error | not-a-buyer | | only buyers may review |
76
- | **application** | port | customer-purchases | prisma (same database) | purchases live in sales |
77
- | | use case | submit-review | deps: ReviewRepository, CustomerPurchases | checks purchase, then saves |
78
- | **presentation** | endpoint | POST products/:id/reviews | → submit-review | UI calls it over HTTP |
73
+ | Layer | Type | Name | Details | Why |
74
+ | ---------------- | --------- | ------------------------- | ----------------------------------------- | ------------------------------------ |
75
+ | **domain** | aggregate | review | repository prisma, in-memory in tests | consistency boundary with moderation |
76
+ | | error | not-a-buyer | | only buyers may review |
77
+ | **application** | port | customer-purchases | prisma (same database) | purchases live in sales |
78
+ | | use case | submit-review | deps: ReviewRepository, CustomerPurchases | checks purchase, then saves |
79
+ | **presentation** | endpoint | POST products/:id/reviews | → submit-review | UI calls it over HTTP |
79
80
 
80
81
  **React**
81
82
 
@@ -83,21 +84,24 @@ Why here: buyers write a review on the product page.
83
84
 
84
85
  What will be scaffolded:
85
86
 
86
- | Layer | Type | Name | Details | Why |
87
- | --- | --- | --- | --- | --- |
88
- | **presentation** | widget | products/review-form | with separated ui | form has its own state |
89
- | | page | products/details | add the widget | form goes on this screen |
87
+ | Layer | Type | Name | Details | Why |
88
+ | ---------------- | ------ | -------------------- | ----------------- | ------------------------ |
89
+ | **presentation** | widget | products/review-form | with separated ui | form has its own state |
90
+ | | page | products/details | add the widget | form goes on this screen |
90
91
 
91
92
  **Writing by hand**
93
+
92
94
  - review: schema (id, productId, authorId, rating, text, status), method publish()
93
95
  - customer-purchases adapter: purchases query → HasPurchased
94
96
  - submit-review: input { productId, rating, text }, NotABuyer when no purchase
95
97
 
96
98
  **Running**
99
+
97
100
  - after domain: npm run prisma:migration:plan -- --name add-reviews (applied by the user)
98
101
  - after the endpoint: npm run openapi && npm run client:orval
99
102
 
100
103
  **Question**
104
+
101
105
  1. Separate reviews context (recommended) or part of catalog?
102
106
  2. Must reviews be moderated before publishing?
103
107
 
@@ -12,7 +12,7 @@ React modules live in `<rootFolder>/presentation/react/` (`…/react/` below) an
12
12
  1. Read `domain-first.project-structure.config.json`: source root is `project.rootFolder`; React is enabled by `frontend.react`; `frontend.react.framework` is `react` or `next`, and both use `df-react`. Stories use `frontend.react.storybookFramework` (initialization uses `@storybook/react-vite` for both React and Next.js via the shared Storybook integration). A config of an earlier major version (`CONFIG_OUTDATED`): ask the user to run `npx df-upgrade`; never run it yourself. Without the config, tell the user to run `npx df-init`; without React configured, tell them to run `npx df-init --section frontend`. Initialization and configuration belong to the human: do not run `df-init` or edit these settings yourself.
13
13
  2. A feature that also needs backend work → plan it with `df-ps-plan-feature`; React runs come last in the plan.
14
14
  3. Choose a module for each piece of UI ("Choosing the module").
15
- 4. Show the work plan in the `df-ps-scaffold` rule 1 format (the React block) and **stop until it's approved**. Type is page, widget, ui-kit component, hook, page move or widget move; Details holds the widget type and, for a page move with Next.js, whether the route moves.
15
+ 4. Show the work plan in the format of `df-ps-scaffold/references/work-plan.md` (the React block) and **stop until it's approved**. Type is page, widget, ui-kit component, hook, page move or widget move; Details holds the widget type and, for a page move with Next.js, whether the route moves.
16
16
  5. Run the generators with `df-react --request` JSON in plan order (shared hooks → UI-kit → widgets → pages); check each output.
17
17
  6. Implement ("Implementing"), after the backend and the regenerated API client.
18
18
  7. Run `npx df-lint` and the project's tsc/lint/tests. Report against the plan.
@@ -49,14 +49,7 @@ npx df-react --request '{"operation":"widget","name":"cart","widgetType":"separa
49
49
 
50
50
  Read `df-ps-scaffold` [agent-mode.md](../df-ps-scaffold/references/agent-mode.md) for previews, overwrite control and JSON result checks; [agent-operations.md](../df-ps-scaffold/references/agent-operations.md#react-operations-df-react) covers all React operations and naming conditions. Initialization remains a human task. For older CLI versions without JSON support, use the interactive driver with `--bin df-react`:
51
51
 
52
- ```bash
53
- node <df-ps-scaffold-skill-dir>/scripts/drive.mjs --bin df-react [--cwd <dir>] [--delay <ms>] <step>...
54
- node <df-ps-scaffold-skill-dir>/scripts/drive.mjs --bin df-react "pick:New widget" text:cart "pick:with separated ui"
55
- ```
56
-
57
- Steps and checks are the same as for `df-scaffold` ("Legacy interactive driver" in `df-ps-scaffold`). Its menu: `New widget`, `New page`, `New UI-kit component`, `New shared hook`, `Move or rename widget`, `Move or rename page`, `Move or rename UI-kit component`, `Move or rename shared hook`, `Delete widget`, `Delete page`, `Delete UI-kit component`, `Delete shared hook`. Prompts and output of each: `references/generators.md`.
58
-
59
- If the CLI cannot run, report the failure and give the user the prepared JSON command (a menu path only for a legacy CLI). Never hand-write its output.
52
+ If the CLI cannot run, report the failure and give the user the prepared JSON command. Never hand-write its output.
60
53
 
61
54
  ### Moving and renaming
62
55