micro-contracts 0.18.9 → 0.18.11

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 (202) hide show
  1. package/README.md +7 -14
  2. package/cli-contract.yaml +15 -27
  3. package/dist/agents/context-builder.d.ts +5 -0
  4. package/dist/agents/context-builder.d.ts.map +1 -0
  5. package/dist/agents/context-builder.js +239 -0
  6. package/dist/agents/context-builder.js.map +1 -0
  7. package/dist/agents/formatter.d.ts +9 -0
  8. package/dist/agents/formatter.d.ts.map +1 -0
  9. package/dist/agents/formatter.js +124 -0
  10. package/dist/agents/formatter.js.map +1 -0
  11. package/dist/agents/index.d.ts +6 -0
  12. package/dist/agents/index.d.ts.map +1 -0
  13. package/dist/agents/index.js +4 -0
  14. package/dist/agents/index.js.map +1 -0
  15. package/dist/agents/orchestrator.d.ts +5 -0
  16. package/dist/agents/orchestrator.d.ts.map +1 -0
  17. package/dist/agents/orchestrator.js +46 -0
  18. package/dist/agents/orchestrator.js.map +1 -0
  19. package/dist/agents/types.d.ts +29 -0
  20. package/dist/agents/types.d.ts.map +1 -0
  21. package/dist/agents/types.js +7 -0
  22. package/dist/agents/types.js.map +1 -0
  23. package/dist/cli/templates.d.ts +15 -0
  24. package/dist/cli/templates.d.ts.map +1 -0
  25. package/dist/cli/templates.js +445 -0
  26. package/dist/cli/templates.js.map +1 -0
  27. package/dist/cli.d.ts +3 -0
  28. package/dist/cli.d.ts.map +1 -0
  29. package/dist/cli.js +1201 -0
  30. package/dist/cli.js.map +1 -0
  31. package/dist/commands/audit-guardrails.d.ts +15 -0
  32. package/dist/commands/audit-guardrails.d.ts.map +1 -0
  33. package/dist/commands/audit-guardrails.js +33 -0
  34. package/dist/commands/audit-guardrails.js.map +1 -0
  35. package/dist/commands/audit-openapi.d.ts +15 -0
  36. package/dist/commands/audit-openapi.d.ts.map +1 -0
  37. package/dist/commands/audit-openapi.js +33 -0
  38. package/dist/commands/audit-openapi.js.map +1 -0
  39. package/dist/commands/insights.d.ts +8 -0
  40. package/dist/commands/insights.d.ts.map +1 -0
  41. package/dist/commands/insights.js +13 -0
  42. package/dist/commands/insights.js.map +1 -0
  43. package/dist/commands/propose-overlays.d.ts +15 -0
  44. package/dist/commands/propose-overlays.d.ts.map +1 -0
  45. package/dist/commands/propose-overlays.js +33 -0
  46. package/dist/commands/propose-overlays.js.map +1 -0
  47. package/dist/commands/review-published.d.ts +15 -0
  48. package/dist/commands/review-published.d.ts.map +1 -0
  49. package/dist/commands/review-published.js +33 -0
  50. package/dist/commands/review-published.js.map +1 -0
  51. package/dist/external/insight-provider.d.ts.map +1 -0
  52. package/dist/external/insight-provider.js.map +1 -0
  53. package/dist/generated/commands.d.ts +2 -0
  54. package/dist/generated/commands.d.ts.map +1 -0
  55. package/dist/generated/commands.js +2 -0
  56. package/dist/generated/commands.js.map +1 -0
  57. package/dist/generated/contract.d.ts +3 -0
  58. package/dist/generated/contract.d.ts.map +1 -0
  59. package/dist/generated/contract.js +5 -0
  60. package/dist/generated/contract.js.map +1 -0
  61. package/dist/generated/dsl/agents.d.ts +34 -0
  62. package/dist/generated/dsl/agents.d.ts.map +1 -0
  63. package/dist/generated/dsl/agents.js +98 -0
  64. package/dist/generated/dsl/agents.js.map +1 -0
  65. package/dist/generated/dsl/dsl-data.d.ts +7 -0
  66. package/dist/generated/dsl/dsl-data.d.ts.map +1 -0
  67. package/dist/generated/dsl/dsl-data.js +1041 -0
  68. package/dist/generated/dsl/dsl-data.js.map +1 -0
  69. package/dist/generated/dsl/handoffs.d.ts +457 -0
  70. package/dist/generated/dsl/handoffs.d.ts.map +1 -0
  71. package/dist/generated/dsl/handoffs.js +205 -0
  72. package/dist/generated/dsl/handoffs.js.map +1 -0
  73. package/dist/generated/dsl/index.d.ts +14 -0
  74. package/dist/generated/dsl/index.d.ts.map +1 -0
  75. package/dist/generated/dsl/index.js +11 -0
  76. package/dist/generated/dsl/index.js.map +1 -0
  77. package/dist/generated/dsl/tasks.d.ts +28 -0
  78. package/dist/generated/dsl/tasks.d.ts.map +1 -0
  79. package/dist/generated/dsl/tasks.js +137 -0
  80. package/dist/generated/dsl/tasks.js.map +1 -0
  81. package/dist/generated/dsl/workflows.d.ts +34 -0
  82. package/dist/generated/dsl/workflows.d.ts.map +1 -0
  83. package/dist/generated/dsl/workflows.js +84 -0
  84. package/dist/generated/dsl/workflows.js.map +1 -0
  85. package/dist/generated/index.d.ts +8 -0
  86. package/dist/generated/index.d.ts.map +1 -0
  87. package/dist/generated/index.js +8 -0
  88. package/dist/generated/index.js.map +1 -0
  89. package/dist/generated/policy-runtime.d.ts +114 -0
  90. package/dist/generated/policy-runtime.d.ts.map +1 -0
  91. package/dist/generated/policy-runtime.js +195 -0
  92. package/dist/generated/policy-runtime.js.map +1 -0
  93. package/dist/generated/policy.d.ts +658 -0
  94. package/dist/generated/policy.d.ts.map +1 -0
  95. package/dist/generated/policy.js +844 -0
  96. package/dist/generated/policy.js.map +1 -0
  97. package/dist/generated/program.d.ts +120 -0
  98. package/dist/generated/program.d.ts.map +1 -0
  99. package/dist/generated/program.js +370 -0
  100. package/dist/generated/program.js.map +1 -0
  101. package/dist/generated/schemas.d.ts +779 -0
  102. package/dist/generated/schemas.d.ts.map +1 -0
  103. package/dist/generated/schemas.js +1006 -0
  104. package/dist/generated/schemas.js.map +1 -0
  105. package/dist/generated/types.d.ts +786 -0
  106. package/dist/generated/types.d.ts.map +1 -0
  107. package/dist/generated/types.js +3 -0
  108. package/dist/generated/types.js.map +1 -0
  109. package/dist/generator/dependencyGenerator.d.ts +16 -0
  110. package/dist/generator/dependencyGenerator.d.ts.map +1 -0
  111. package/dist/generator/dependencyGenerator.js +25 -0
  112. package/dist/generator/dependencyGenerator.js.map +1 -0
  113. package/dist/generator/index.d.ts +47 -0
  114. package/dist/generator/index.d.ts.map +1 -0
  115. package/dist/generator/index.js +707 -0
  116. package/dist/generator/index.js.map +1 -0
  117. package/dist/generator/inputHash.d.ts +23 -0
  118. package/dist/generator/inputHash.d.ts.map +1 -0
  119. package/dist/generator/inputHash.js +138 -0
  120. package/dist/generator/inputHash.js.map +1 -0
  121. package/dist/generator/linter.d.ts +26 -0
  122. package/dist/generator/linter.d.ts.map +1 -0
  123. package/dist/generator/linter.js +441 -0
  124. package/dist/generator/linter.js.map +1 -0
  125. package/dist/generator/overlayProcessor.d.ts +71 -0
  126. package/dist/generator/overlayProcessor.d.ts.map +1 -0
  127. package/dist/generator/overlayProcessor.js +500 -0
  128. package/dist/generator/overlayProcessor.js.map +1 -0
  129. package/dist/generator/schemaGenerator.d.ts +10 -0
  130. package/dist/generator/schemaGenerator.d.ts.map +1 -0
  131. package/dist/generator/schemaGenerator.js +296 -0
  132. package/dist/generator/schemaGenerator.js.map +1 -0
  133. package/dist/generator/serviceGenerator.d.ts +20 -0
  134. package/dist/generator/serviceGenerator.d.ts.map +1 -0
  135. package/dist/generator/serviceGenerator.js +293 -0
  136. package/dist/generator/serviceGenerator.js.map +1 -0
  137. package/dist/generator/templateProcessor.d.ts +208 -0
  138. package/dist/generator/templateProcessor.d.ts.map +1 -0
  139. package/dist/generator/templateProcessor.js +604 -0
  140. package/dist/generator/templateProcessor.js.map +1 -0
  141. package/dist/generator/typeGenerator.d.ts +22 -0
  142. package/dist/generator/typeGenerator.d.ts.map +1 -0
  143. package/dist/generator/typeGenerator.js +439 -0
  144. package/dist/generator/typeGenerator.js.map +1 -0
  145. package/dist/generator/typeGenerator.test.d.ts +2 -0
  146. package/dist/generator/typeGenerator.test.d.ts.map +1 -0
  147. package/dist/generator/typeGenerator.test.js +155 -0
  148. package/dist/generator/typeGenerator.test.js.map +1 -0
  149. package/dist/glob.d.ts +22 -0
  150. package/dist/glob.d.ts.map +1 -0
  151. package/dist/glob.js +103 -0
  152. package/dist/glob.js.map +1 -0
  153. package/dist/guardrails/allowlist.d.ts +30 -0
  154. package/dist/guardrails/allowlist.d.ts.map +1 -0
  155. package/dist/guardrails/allowlist.js +174 -0
  156. package/dist/guardrails/allowlist.js.map +1 -0
  157. package/dist/guardrails/config.d.ts +40 -0
  158. package/dist/guardrails/config.d.ts.map +1 -0
  159. package/dist/guardrails/config.js +177 -0
  160. package/dist/guardrails/config.js.map +1 -0
  161. package/dist/guardrails/drift.d.ts +19 -0
  162. package/dist/guardrails/drift.d.ts.map +1 -0
  163. package/dist/guardrails/drift.js +115 -0
  164. package/dist/guardrails/drift.js.map +1 -0
  165. package/dist/guardrails/index.d.ts +18 -0
  166. package/dist/guardrails/index.d.ts.map +1 -0
  167. package/dist/guardrails/index.js +21 -0
  168. package/dist/guardrails/index.js.map +1 -0
  169. package/dist/guardrails/lint.d.ts +16 -0
  170. package/dist/guardrails/lint.d.ts.map +1 -0
  171. package/dist/guardrails/lint.js +172 -0
  172. package/dist/guardrails/lint.js.map +1 -0
  173. package/dist/guardrails/manifest.d.ts +63 -0
  174. package/dist/guardrails/manifest.d.ts.map +1 -0
  175. package/dist/guardrails/manifest.js +310 -0
  176. package/dist/guardrails/manifest.js.map +1 -0
  177. package/dist/guardrails/runner.d.ts +53 -0
  178. package/dist/guardrails/runner.d.ts.map +1 -0
  179. package/dist/guardrails/runner.js +387 -0
  180. package/dist/guardrails/runner.js.map +1 -0
  181. package/dist/guardrails/types.d.ts +196 -0
  182. package/dist/guardrails/types.d.ts.map +1 -0
  183. package/dist/guardrails/types.js +8 -0
  184. package/dist/guardrails/types.js.map +1 -0
  185. package/dist/index.d.ts +21 -4
  186. package/dist/index.d.ts.map +1 -0
  187. package/dist/index.js +21 -4
  188. package/dist/index.js.map +1 -0
  189. package/dist/micro-contracts.bundle.mjs +358 -383
  190. package/dist/micro-contracts.bundle.mjs.map +3 -3
  191. package/dist/types.d.ts +502 -0
  192. package/dist/types.d.ts.map +1 -0
  193. package/dist/types.js +409 -0
  194. package/dist/types.js.map +1 -0
  195. package/dist/version.d.ts +10 -0
  196. package/dist/version.d.ts.map +1 -0
  197. package/dist/version.js +31 -0
  198. package/dist/version.js.map +1 -0
  199. package/docs/cli-reference.md +13 -15
  200. package/docs/development-guardrails.md +3 -3
  201. package/docs/screen-spec.md +3 -3
  202. package/package.json +13 -12
package/dist/cli.js ADDED
@@ -0,0 +1,1201 @@
1
+ #!/usr/bin/env node
2
+ import fs from 'fs';
3
+ import path from 'path';
4
+ import yaml from 'yaml';
5
+ import { createProgram } from './generated/program.js';
6
+ import { generate, loadConfig, findConfigFile, loadOpenAPISpec, lintSpec, formatLintResults, computeInputHash } from './generator/index.js';
7
+ import { isMultiModuleConfig } from './types.js';
8
+ import { getStarterTemplates, getScreenStarterTemplates } from './cli/templates.js';
9
+ import { runAllChecks, formatCheckResults, formatSingleCheckResult, formatCheckStart, formatCheckSummary, formatVerdict, getAvailableChecks, createGuardrailsConfig, generateManifest, writeManifest, canSkipGeneration, GATE_DESCRIPTIONS, loadGuardrailsConfigWithPath, } from './guardrails/index.js';
10
+ import { commandAuditOpenapi } from './commands/audit-openapi.js';
11
+ import { commandReviewPublished } from './commands/review-published.js';
12
+ import { commandProposeOverlays } from './commands/propose-overlays.js';
13
+ import { commandAuditGuardrails } from './commands/audit-guardrails.js';
14
+ import { commandInsights } from './commands/insights.js';
15
+ import { VERSION } from './version.js';
16
+ /**
17
+ * True when the run generates only part of the configured output.
18
+ *
19
+ * A partial run must not stamp the manifest with the input hash: the hash says
20
+ * these inputs have been generated from, and a later full run would skip,
21
+ * leaving whatever this run did not generate permanently missing.
22
+ */
23
+ function isPartialGeneration(opts) {
24
+ return Boolean(opts.module ||
25
+ opts.output ||
26
+ opts.contractsOnly ||
27
+ opts.serverOnly ||
28
+ opts.frontendOnly);
29
+ }
30
+ const handlers = {
31
+ // ── generate ──────────────────────────────────────────
32
+ generate: async (opts) => {
33
+ try {
34
+ let config;
35
+ const configPath = opts.config
36
+ ? path.resolve(opts.config)
37
+ : findConfigFile();
38
+ if (!configPath) {
39
+ console.error('Error: No config file found.');
40
+ console.error('Create micro-contracts.config.yaml or use --config <path>');
41
+ process.exit(1);
42
+ }
43
+ if (!fs.existsSync(configPath)) {
44
+ console.error(`Config file not found: ${configPath}`);
45
+ process.exit(1);
46
+ }
47
+ console.log(`Using config: ${configPath}`);
48
+ config = loadConfig(configPath);
49
+ const useCache = opts.cache !== false && !opts.force;
50
+ let inputHash;
51
+ if (isMultiModuleConfig(config)) {
52
+ inputHash = computeInputHash(config, configPath, VERSION);
53
+ if (useCache) {
54
+ const manifestDir = opts.manifestDir || 'packages/';
55
+ const skipCheck = await canSkipGeneration(manifestDir, inputHash);
56
+ if (skipCheck.skip) {
57
+ console.log(`No input changes detected, skipping generation (${skipCheck.reason})`);
58
+ return;
59
+ }
60
+ }
61
+ }
62
+ await generate(config, {
63
+ contractsOnly: opts.contractsOnly,
64
+ serverOnly: opts.serverOnly,
65
+ frontendOnly: opts.frontendOnly,
66
+ skipLint: opts.skipLint,
67
+ modules: opts.module,
68
+ outputs: opts.output,
69
+ });
70
+ if (opts.manifest !== false) {
71
+ const { config: guardrailsConfig } = loadGuardrailsConfigWithPath();
72
+ if (guardrailsConfig?.generated && guardrailsConfig.generated.length > 0) {
73
+ const manifestDir = opts.manifestDir || 'packages/';
74
+ if (fs.existsSync(manifestDir)) {
75
+ const manifestInputHash = (opts.cache !== false && !isPartialGeneration(opts)) ? inputHash : undefined;
76
+ const { manifest, changed } = await generateManifest(manifestDir, {
77
+ generatorVersion: VERSION,
78
+ inputHash: manifestInputHash,
79
+ });
80
+ const fileCount = Object.keys(manifest.files).length;
81
+ if (changed) {
82
+ const manifestPath = writeManifest(manifest, manifestDir);
83
+ console.log(`\nManifest updated: ${manifestPath} (${fileCount} files)`);
84
+ }
85
+ else {
86
+ console.log(`\nManifest unchanged (${fileCount} files)`);
87
+ }
88
+ }
89
+ }
90
+ }
91
+ }
92
+ catch (error) {
93
+ console.error('Generation failed:', error instanceof Error ? error.message : error);
94
+ process.exit(1);
95
+ }
96
+ },
97
+ // ── lint ───────────────────────────────────────────────
98
+ lint: async (input, opts) => {
99
+ try {
100
+ const specPath = path.resolve(input);
101
+ if (!fs.existsSync(specPath)) {
102
+ console.error(`OpenAPI spec not found: ${specPath}`);
103
+ process.exit(1);
104
+ }
105
+ console.log(`Linting: ${specPath}\n`);
106
+ const spec = loadOpenAPISpec(specPath);
107
+ const result = lintSpec(spec, { strict: opts.strict });
108
+ console.log(formatLintResults(result));
109
+ if (!result.valid) {
110
+ process.exit(1);
111
+ }
112
+ }
113
+ catch (error) {
114
+ console.error('Lint failed:', error instanceof Error ? error.message : error);
115
+ process.exit(1);
116
+ }
117
+ },
118
+ // ── init ───────────────────────────────────────────────
119
+ init: async (name, opts) => {
120
+ console.log(`Initializing module "${name}"${opts.screens ? ' (screen spec)' : ''}...\n`);
121
+ const specDirs = [
122
+ 'spec',
123
+ 'spec/default/templates',
124
+ 'spec/_shared/openapi',
125
+ 'spec/_shared/overlays',
126
+ `spec/${name}/openapi`,
127
+ ];
128
+ for (const dir of specDirs) {
129
+ if (!fs.existsSync(dir)) {
130
+ fs.mkdirSync(dir, { recursive: true });
131
+ console.log(`Created: ${dir}/`);
132
+ }
133
+ }
134
+ if (!opts.skipTemplates) {
135
+ const starterTemplates = getStarterTemplates();
136
+ for (const [filename, content] of Object.entries(starterTemplates)) {
137
+ const templatePath = path.join('spec/default/templates', filename);
138
+ if (!fs.existsSync(templatePath)) {
139
+ fs.writeFileSync(templatePath, content);
140
+ console.log(`Created: ${templatePath}`);
141
+ }
142
+ }
143
+ if (opts.screens) {
144
+ const screenTemplates = getScreenStarterTemplates();
145
+ for (const [filename, content] of Object.entries(screenTemplates)) {
146
+ const templatePath = path.join('spec/default/templates', filename);
147
+ if (!fs.existsSync(templatePath)) {
148
+ fs.writeFileSync(templatePath, content);
149
+ console.log(`Created: ${templatePath}`);
150
+ }
151
+ }
152
+ }
153
+ }
154
+ const problemDetailsPath = 'spec/_shared/openapi/problem-details.yaml';
155
+ if (!fs.existsSync(problemDetailsPath)) {
156
+ fs.writeFileSync(problemDetailsPath, generateProblemDetailsSchema());
157
+ console.log(`Created: ${problemDetailsPath}`);
158
+ }
159
+ const spectralPath = 'spec/spectral.yaml';
160
+ if (!fs.existsSync(spectralPath)) {
161
+ fs.writeFileSync(spectralPath, generateSpectralRules());
162
+ console.log(`Created: ${spectralPath}`);
163
+ }
164
+ if (opts.screens) {
165
+ const screenSpecDir = `spec/${name}/openapi`;
166
+ fs.mkdirSync(screenSpecDir, { recursive: true });
167
+ const screenSpecPath = path.join(screenSpecDir, `${name}.yaml`);
168
+ if (!fs.existsSync(screenSpecPath)) {
169
+ fs.writeFileSync(screenSpecPath, generateScreenSpecTemplate(name));
170
+ console.log(`Created: ${screenSpecPath}`);
171
+ }
172
+ }
173
+ const baseDir = path.resolve(opts.dir ?? 'src', name);
174
+ const dirs = [
175
+ baseDir,
176
+ path.join(baseDir, 'services'),
177
+ path.join(baseDir, 'models'),
178
+ ];
179
+ for (const dir of dirs) {
180
+ if (!fs.existsSync(dir)) {
181
+ fs.mkdirSync(dir, { recursive: true });
182
+ console.log(`Created: ${dir}/`);
183
+ }
184
+ }
185
+ const files = [
186
+ [path.join(baseDir, 'db.ts'), generateDbTemplate()],
187
+ [path.join(baseDir, 'container.ts'), generateContainerTemplate(name)],
188
+ [path.join(baseDir, 'services', 'index.ts'), '// Export service classes\n'],
189
+ [path.join(baseDir, 'models', 'index.ts'), '// Export models\n'],
190
+ ];
191
+ for (const [filePath, content] of files) {
192
+ if (!fs.existsSync(filePath)) {
193
+ fs.writeFileSync(filePath, content);
194
+ console.log(`Created: ${filePath}`);
195
+ }
196
+ }
197
+ const configPath = path.resolve('micro-contracts.config.yaml');
198
+ if (!fs.existsSync(configPath)) {
199
+ const configContent = opts.screens
200
+ ? generateScreenConfigTemplate(name)
201
+ : generateConfigTemplate(name);
202
+ fs.writeFileSync(configPath, configContent);
203
+ console.log(`Created: ${configPath}`);
204
+ }
205
+ if (opts.openapi) {
206
+ const openapiPath = path.resolve(opts.openapi);
207
+ if (!fs.existsSync(openapiPath)) {
208
+ console.error(`OpenAPI file not found: ${openapiPath}`);
209
+ process.exit(1);
210
+ }
211
+ const outputPath = opts.output
212
+ ? path.resolve(opts.output)
213
+ : path.resolve(`spec/${name}/openapi/${name}.yaml`);
214
+ fs.mkdirSync(path.dirname(outputPath), { recursive: true });
215
+ console.log(`\nProcessing OpenAPI: ${openapiPath}`);
216
+ const processed = processOpenAPIWithExtensions(openapiPath);
217
+ fs.writeFileSync(outputPath, processed.yaml);
218
+ console.log(`Created: ${outputPath}`);
219
+ console.log(` - Added x-micro-contracts-service to ${processed.stats.servicesAdded} operations`);
220
+ console.log(` - Added x-micro-contracts-method to ${processed.stats.methodsAdded} operations`);
221
+ if (processed.stats.services.length > 0) {
222
+ console.log(` - Detected services: ${processed.stats.services.join(', ')}`);
223
+ }
224
+ }
225
+ console.log(`\nModule "${name}" initialized!`);
226
+ if (opts.screens) {
227
+ console.log(`\nNext steps:`);
228
+ console.log(` 1. Edit spec/${name}/openapi/${name}.yaml with your screen definitions`);
229
+ console.log(` 2. Define ViewModels in components/schemas`);
230
+ console.log(` 3. Add navigation links and x-events`);
231
+ console.log(` 4. Run: npx micro-contracts generate`);
232
+ }
233
+ else if (!opts.openapi) {
234
+ console.log(`\nNext steps:`);
235
+ console.log(` 1. Create spec/${name}/openapi/${name}.yaml with your API spec`);
236
+ console.log(` 2. Add x-micro-contracts-service and x-micro-contracts-method to operations`);
237
+ console.log(` 3. Run: npx micro-contracts generate`);
238
+ console.log(`\nTip: Use --openapi to auto-add extensions:`);
239
+ console.log(` npx micro-contracts init ${name} --openapi path/to/spec.yaml`);
240
+ }
241
+ else {
242
+ console.log(`\nNext steps:`);
243
+ console.log(` 1. Review the generated extensions in spec/${name}/openapi/${name}.yaml`);
244
+ console.log(` 2. Run: npx micro-contracts generate`);
245
+ }
246
+ },
247
+ // ── check ─────────────────────────────────────────────
248
+ check: async (opts) => {
249
+ try {
250
+ if (opts.listGates) {
251
+ console.log('\nAvailable gates:\n');
252
+ for (const [gate, description] of Object.entries(GATE_DESCRIPTIONS)) {
253
+ console.log(` Gate ${gate}: ${description}`);
254
+ }
255
+ console.log('\nUsage: micro-contracts check --gate 1,2,3');
256
+ console.log('');
257
+ return;
258
+ }
259
+ if (opts.list) {
260
+ console.log('\nAvailable checks:\n');
261
+ for (const check of getAvailableChecks({ guardrailsPath: opts.guardrails })) {
262
+ const gateStr = check.gate !== undefined ? `[G${check.gate}]` : ' ';
263
+ console.log(` ${gateStr} ${check.name.padEnd(20)} - ${check.description}`);
264
+ }
265
+ console.log('');
266
+ return;
267
+ }
268
+ let gates;
269
+ if (opts.gate) {
270
+ gates = opts.gate.split(',').map((s) => {
271
+ const num = parseInt(s.trim(), 10);
272
+ if (num < 1 || num > 5 || isNaN(num)) {
273
+ throw new Error(`Invalid gate number: ${s}. Must be 1-5.`);
274
+ }
275
+ return num;
276
+ });
277
+ }
278
+ console.log('');
279
+ console.log('🔍 AI Guardrail Check Results');
280
+ console.log('═'.repeat(50));
281
+ console.log('');
282
+ const isStreaming = process.stdout.isTTY !== false;
283
+ const checkOptions = {
284
+ only: opts.only?.split(',').map((s) => s.trim()),
285
+ skip: opts.skip?.split(',').map((s) => s.trim()),
286
+ gates,
287
+ verbose: opts.verbose,
288
+ fix: opts.fix,
289
+ guardrailsPath: opts.guardrails,
290
+ generatedDir: opts.generatedDir,
291
+ changedFilesPath: opts.changedFiles,
292
+ onCheckStart: isStreaming ? (check) => {
293
+ if (process.stdout.isTTY) {
294
+ process.stdout.write(formatCheckStart(check) + '\r');
295
+ }
296
+ } : undefined,
297
+ onCheckComplete: isStreaming ? (result, check) => {
298
+ if (process.stdout.isTTY) {
299
+ process.stdout.clearLine?.(0);
300
+ process.stdout.cursorTo?.(0);
301
+ }
302
+ console.log(formatSingleCheckResult(result, check, opts.verbose));
303
+ } : undefined,
304
+ };
305
+ const summary = await runAllChecks(checkOptions);
306
+ if (isStreaming) {
307
+ console.log(formatCheckSummary(summary, summary.checks));
308
+ }
309
+ else {
310
+ console.log(formatCheckResults(summary, opts.verbose, summary.checks));
311
+ }
312
+ // A run that verified nothing is not a pass, whatever the reason it had
313
+ // nothing to run.
314
+ if (summary.failed > 0 || summary.passed === 0) {
315
+ process.exit(1);
316
+ }
317
+ }
318
+ catch (error) {
319
+ console.error('Check failed:', error instanceof Error ? error.message : error);
320
+ process.exit(1);
321
+ }
322
+ },
323
+ // ── pipeline ──────────────────────────────────────────
324
+ pipeline: async (opts) => {
325
+ try {
326
+ const startTime = Date.now();
327
+ const verbose = opts.verbose;
328
+ let hasFailure = false;
329
+ let generatePassed = false;
330
+ let generateDuration = 0;
331
+ let generateSkipped = false;
332
+ let generateError = null;
333
+ const allResults = [];
334
+ console.log('');
335
+ console.log('🚀 Running AI Guardrails Pipeline');
336
+ console.log('═'.repeat(50));
337
+ console.log('');
338
+ const skipChecks = opts.skip?.split(',').map((s) => s.trim()) || [];
339
+ const isStreaming = process.stdout.isTTY !== false;
340
+ const baseCheckOptions = {
341
+ verbose,
342
+ skip: skipChecks,
343
+ guardrailsPath: opts.guardrails,
344
+ generatedDir: opts.generatedDir,
345
+ onCheckStart: isStreaming ? (check) => {
346
+ if (process.stdout.isTTY) {
347
+ process.stdout.write(formatCheckStart(check) + '\r');
348
+ }
349
+ } : undefined,
350
+ onCheckComplete: isStreaming ? (result, check) => {
351
+ if (process.stdout.isTTY) {
352
+ process.stdout.clearLine?.(0);
353
+ process.stdout.cursorTo?.(0);
354
+ }
355
+ console.log(formatSingleCheckResult(result, check, verbose));
356
+ } : undefined,
357
+ };
358
+ // Step 1: Gate 1,2
359
+ if (verbose) {
360
+ console.log('┌─────────────────────────────────────────────────┐');
361
+ console.log('│ Step 1: Pre-generation checks (Gate 1, 2) │');
362
+ console.log('└─────────────────────────────────────────────────┘');
363
+ console.log('');
364
+ }
365
+ const gate12Summary = await runAllChecks({ ...baseCheckOptions, gates: [1, 2] });
366
+ allResults.push(...gate12Summary.results);
367
+ if (verbose)
368
+ console.log(formatCheckSummary(gate12Summary, gate12Summary.checks));
369
+ if (gate12Summary.failed > 0) {
370
+ hasFailure = true;
371
+ if (!opts.continueOnError) {
372
+ console.log('');
373
+ console.log('❌ Gate 1,2 failed. Stopping pipeline.');
374
+ console.log(' Use --continue-on-error to continue despite failures.');
375
+ process.exit(1);
376
+ }
377
+ if (verbose)
378
+ console.log('⚠️ Gate 1,2 had failures. Continuing due to --continue-on-error.\n');
379
+ }
380
+ // Step 2: Generate
381
+ let generationCacheSkipped = false;
382
+ if (verbose) {
383
+ console.log('┌─────────────────────────────────────────────────┐');
384
+ console.log('│ Step 2: Generate contracts │');
385
+ console.log('└─────────────────────────────────────────────────┘');
386
+ console.log('');
387
+ }
388
+ const generateStartTime = Date.now();
389
+ if (isStreaming && process.stdout.isTTY) {
390
+ process.stdout.write(' ⋯ Generate running...\r');
391
+ }
392
+ try {
393
+ const configPath = opts.config ? path.resolve(opts.config) : findConfigFile();
394
+ if (!configPath) {
395
+ generateSkipped = true;
396
+ generateDuration = Date.now() - generateStartTime;
397
+ if (isStreaming && process.stdout.isTTY) {
398
+ process.stdout.clearLine?.(0);
399
+ process.stdout.cursorTo?.(0);
400
+ }
401
+ console.log(' ○ Generate SKIP (no config file)');
402
+ }
403
+ else {
404
+ if (verbose)
405
+ console.log(` Using config: ${configPath}`);
406
+ const config = loadConfig(configPath);
407
+ const useCache = opts.cache !== false && !opts.force;
408
+ let inputHash;
409
+ if (isMultiModuleConfig(config)) {
410
+ inputHash = computeInputHash(config, configPath, VERSION);
411
+ if (useCache) {
412
+ const manifestDir = opts.generatedDir || 'packages/';
413
+ const skipCheck = await canSkipGeneration(manifestDir, inputHash);
414
+ if (skipCheck.skip) {
415
+ generationCacheSkipped = true;
416
+ generateSkipped = true;
417
+ generateDuration = Date.now() - generateStartTime;
418
+ if (isStreaming && process.stdout.isTTY) {
419
+ process.stdout.clearLine?.(0);
420
+ process.stdout.cursorTo?.(0);
421
+ }
422
+ console.log(` ○ Generate SKIP (${skipCheck.reason})`);
423
+ }
424
+ }
425
+ }
426
+ if (!generationCacheSkipped) {
427
+ const originalLog = console.log;
428
+ if (!verbose)
429
+ console.log = () => { };
430
+ try {
431
+ await generate(config, {
432
+ skipLint: opts.skipLint,
433
+ contractsOnly: opts.contractsOnly,
434
+ serverOnly: opts.serverOnly,
435
+ frontendOnly: opts.frontendOnly,
436
+ });
437
+ if (opts.manifest !== false) {
438
+ const { config: guardrailsConfig } = loadGuardrailsConfigWithPath(opts.guardrails);
439
+ if (guardrailsConfig?.generated && guardrailsConfig.generated.length > 0) {
440
+ const manifestDir = opts.generatedDir || 'packages/';
441
+ if (fs.existsSync(manifestDir)) {
442
+ const manifestInputHash = (opts.cache !== false && !isPartialGeneration(opts)) ? inputHash : undefined;
443
+ const { manifest, changed } = await generateManifest(manifestDir, {
444
+ generatorVersion: VERSION,
445
+ inputHash: manifestInputHash,
446
+ });
447
+ if (verbose) {
448
+ const fileCount = Object.keys(manifest.files).length;
449
+ if (changed) {
450
+ const mPath = writeManifest(manifest, manifestDir);
451
+ originalLog(` Manifest updated: ${mPath} (${fileCount} files)`);
452
+ }
453
+ else {
454
+ originalLog(` Manifest unchanged (${fileCount} files)`);
455
+ }
456
+ }
457
+ else if (changed) {
458
+ writeManifest(manifest, manifestDir);
459
+ }
460
+ }
461
+ }
462
+ }
463
+ generatePassed = true;
464
+ }
465
+ finally {
466
+ if (!verbose)
467
+ console.log = originalLog;
468
+ }
469
+ generateDuration = Date.now() - generateStartTime;
470
+ if (isStreaming && process.stdout.isTTY) {
471
+ process.stdout.clearLine?.(0);
472
+ process.stdout.cursorTo?.(0);
473
+ }
474
+ console.log(` ✓ Generate PASS (${generateDuration}ms)`);
475
+ if (verbose)
476
+ console.log('');
477
+ }
478
+ }
479
+ }
480
+ catch (error) {
481
+ generateDuration = Date.now() - generateStartTime;
482
+ hasFailure = true;
483
+ generateError = error instanceof Error ? error.message : String(error);
484
+ if (isStreaming && process.stdout.isTTY) {
485
+ process.stdout.clearLine?.(0);
486
+ process.stdout.cursorTo?.(0);
487
+ }
488
+ console.log(` ✗ Generate FAIL (${generateDuration}ms)`);
489
+ console.log(` ${generateError}`);
490
+ if (!opts.continueOnError) {
491
+ console.log('');
492
+ console.log('❌ Generation failed. Stopping pipeline.');
493
+ process.exit(1);
494
+ }
495
+ if (verbose)
496
+ console.log('⚠️ Continuing due to --continue-on-error.');
497
+ }
498
+ // Step 3: Gate 3,4,5
499
+ if (verbose) {
500
+ console.log('');
501
+ console.log('┌─────────────────────────────────────────────────┐');
502
+ console.log('│ Step 3: Post-generation checks (Gate 3, 4, 5) │');
503
+ console.log('└─────────────────────────────────────────────────┘');
504
+ console.log('');
505
+ }
506
+ const gate3Skips = generationCacheSkipped
507
+ ? [...skipChecks, 'drift', 'manifest']
508
+ : skipChecks;
509
+ const gate345Summary = await runAllChecks({
510
+ ...baseCheckOptions,
511
+ skip: gate3Skips,
512
+ gates: [3, 4, 5],
513
+ });
514
+ allResults.push(...gate345Summary.results);
515
+ if (verbose)
516
+ console.log(formatCheckSummary(gate345Summary, gate345Summary.checks));
517
+ if (gate345Summary.failed > 0)
518
+ hasFailure = true;
519
+ // Final Summary
520
+ const totalDuration = Date.now() - startTime;
521
+ const totalPassed = gate12Summary.passed + gate345Summary.passed + (generatePassed ? 1 : 0);
522
+ const totalFailed = gate12Summary.failed + gate345Summary.failed + (generateError ? 1 : 0);
523
+ const totalSkipped = gate12Summary.skipped + gate345Summary.skipped + (generateSkipped ? 1 : 0);
524
+ console.log('');
525
+ console.log('━'.repeat(50));
526
+ console.log('📊 Pipeline Summary');
527
+ console.log('━'.repeat(50));
528
+ console.log('');
529
+ console.log(` Total Passed: ${totalPassed}`);
530
+ console.log(` Total Failed: ${totalFailed}`);
531
+ if (totalSkipped > 0)
532
+ console.log(` Total Skipped: ${totalSkipped}`);
533
+ console.log(` Duration: ${totalDuration}ms`);
534
+ console.log('');
535
+ const verdict = formatVerdict({ failed: totalFailed, passed: totalPassed });
536
+ if (hasFailure) {
537
+ console.log('❌ Pipeline completed with failures.');
538
+ const failedResults = allResults.filter(r => r.status === 'fail' && r.details && r.details.length > 0);
539
+ if (failedResults.length > 0) {
540
+ console.log('');
541
+ console.log('📋 Failed Check Details:');
542
+ for (const result of failedResults) {
543
+ console.log(` ▶ ${result.name}`);
544
+ for (const detail of result.details) {
545
+ console.log(` ${detail}`);
546
+ }
547
+ }
548
+ }
549
+ process.exit(1);
550
+ }
551
+ else if (totalPassed === 0) {
552
+ // Nothing ran, so there is nothing to call successful.
553
+ console.log(verdict);
554
+ process.exit(1);
555
+ }
556
+ else {
557
+ console.log('✅ Pipeline completed successfully!');
558
+ }
559
+ console.log('');
560
+ }
561
+ catch (error) {
562
+ console.error('Pipeline failed:', error instanceof Error ? error.message : error);
563
+ process.exit(1);
564
+ }
565
+ },
566
+ // ── deps ──────────────────────────────────────────────
567
+ deps: async (opts) => {
568
+ try {
569
+ const configPath = opts.config
570
+ ? path.resolve(opts.config)
571
+ : findConfigFile();
572
+ if (!configPath) {
573
+ console.error('Error: No config file found.');
574
+ process.exit(1);
575
+ }
576
+ const config = loadConfig(configPath);
577
+ if (!config.modules) {
578
+ console.error('Error: Config must have modules defined.');
579
+ process.exit(1);
580
+ }
581
+ const moduleDeps = new Map();
582
+ for (const [moduleName, moduleConfig] of Object.entries(config.modules)) {
583
+ if (opts.module && moduleName !== opts.module)
584
+ continue;
585
+ const openapiPath = path.resolve(path.dirname(configPath), moduleConfig.openapi);
586
+ if (!fs.existsSync(openapiPath)) {
587
+ // Skipping the module would present a dependency graph, impact
588
+ // analysis or validation result that silently omits it.
589
+ // Skipping the module would present a dependency graph, impact
590
+ // analysis or validation result that silently omits it.
591
+ throw new Error(`OpenAPI spec not found for module '${moduleName}': ${openapiPath}`);
592
+ }
593
+ const spec = loadOpenAPISpec(openapiPath);
594
+ const openApiDeps = spec.info['x-micro-contracts-depend-on'] || [];
595
+ const configDeps = moduleConfig.dependsOn || [];
596
+ moduleDeps.set(moduleName, { deps: openApiDeps, openApiDeps, configDeps });
597
+ }
598
+ if (opts.graph) {
599
+ outputDependencyGraph(moduleDeps);
600
+ }
601
+ else if (opts.impact) {
602
+ outputImpactAnalysis(moduleDeps, opts.impact);
603
+ }
604
+ else if (opts.whoDependsOn) {
605
+ outputWhoDependsOn(moduleDeps, opts.whoDependsOn);
606
+ }
607
+ else if (opts.validate) {
608
+ validateDependencies(moduleDeps);
609
+ }
610
+ else {
611
+ outputAllDependencies(moduleDeps);
612
+ }
613
+ }
614
+ catch (error) {
615
+ console.error('Deps analysis failed:', error instanceof Error ? error.message : error);
616
+ process.exit(1);
617
+ }
618
+ },
619
+ // ── guardrails-init ───────────────────────────────────
620
+ guardrailsInit: async (opts) => {
621
+ try {
622
+ const outputPath = opts.output;
623
+ if (fs.existsSync(outputPath)) {
624
+ console.error(`File already exists: ${outputPath}`);
625
+ console.error('Use --output to specify a different path.');
626
+ process.exit(1);
627
+ }
628
+ createGuardrailsConfig(outputPath);
629
+ console.log(`Created: ${outputPath}`);
630
+ console.log('\nNext steps:');
631
+ console.log(' 1. Review and customize the guardrails configuration');
632
+ console.log(' 2. Run: micro-contracts generate');
633
+ console.log(' 3. Commit the generated artifacts (drift compares against the commit)');
634
+ console.log(' 4. Run: micro-contracts check');
635
+ }
636
+ catch (error) {
637
+ console.error('Failed to create guardrails config:', error instanceof Error ? error.message : error);
638
+ process.exit(1);
639
+ }
640
+ },
641
+ // ── manifest ──────────────────────────────────────────
642
+ manifest: async (opts) => {
643
+ try {
644
+ const baseDir = opts.dir ?? 'packages/';
645
+ if (!fs.existsSync(baseDir)) {
646
+ console.error(`Directory not found: ${baseDir}`);
647
+ process.exit(1);
648
+ }
649
+ if (opts.verify) {
650
+ const { verifyManifest, formatManifestResult } = await import('./guardrails/index.js');
651
+ const result = await verifyManifest(baseDir);
652
+ console.log(formatManifestResult(result));
653
+ if (!result.valid) {
654
+ process.exit(1);
655
+ }
656
+ }
657
+ else {
658
+ console.log(`Generating manifest for: ${baseDir}`);
659
+ const { manifest, changed } = await generateManifest(baseDir, {
660
+ generatorVersion: VERSION,
661
+ });
662
+ const fileCount = Object.keys(manifest.files).length;
663
+ if (changed) {
664
+ const manifestPath = writeManifest(manifest, baseDir);
665
+ console.log(`Manifest updated: ${manifestPath} (${fileCount} files)`);
666
+ }
667
+ else {
668
+ console.log(`Manifest unchanged (${fileCount} files)`);
669
+ }
670
+ }
671
+ }
672
+ catch (error) {
673
+ console.error('Manifest operation failed:', error instanceof Error ? error.message : error);
674
+ process.exit(1);
675
+ }
676
+ },
677
+ // ── audit-openapi (LLM) ──────────────────────────────
678
+ auditOpenapi: async (opts) => {
679
+ return commandAuditOpenapi({
680
+ config: opts.config,
681
+ module: opts.module,
682
+ adapter: opts.adapter,
683
+ model: opts.model,
684
+ showPrompt: opts.showPrompt,
685
+ failOn: opts.failOn,
686
+ output: opts.output,
687
+ reportFormat: opts.reportFormat,
688
+ logFile: opts.logFile,
689
+ });
690
+ },
691
+ // ── review-published (LLM) ───────────────────────────
692
+ reviewPublished: async (opts) => {
693
+ return commandReviewPublished({
694
+ config: opts.config,
695
+ module: opts.module,
696
+ adapter: opts.adapter,
697
+ model: opts.model,
698
+ showPrompt: opts.showPrompt,
699
+ failOn: opts.failOn,
700
+ output: opts.output,
701
+ reportFormat: opts.reportFormat,
702
+ logFile: opts.logFile,
703
+ });
704
+ },
705
+ // ── propose-overlays (LLM) ───────────────────────────
706
+ proposeOverlays: async (opts) => {
707
+ return commandProposeOverlays({
708
+ config: opts.config,
709
+ module: opts.module,
710
+ adapter: opts.adapter,
711
+ model: opts.model,
712
+ showPrompt: opts.showPrompt,
713
+ failOn: opts.failOn,
714
+ output: opts.output,
715
+ reportFormat: opts.reportFormat,
716
+ logFile: opts.logFile,
717
+ });
718
+ },
719
+ // ── insights ─────────────────────────────────────────
720
+ insights: async (opts) => {
721
+ try {
722
+ await commandInsights({
723
+ format: opts.format,
724
+ projectRoot: opts.projectRoot,
725
+ config: opts.config,
726
+ });
727
+ }
728
+ catch (error) {
729
+ console.error('Insights failed:', error instanceof Error ? error.message : error);
730
+ process.exit(1);
731
+ }
732
+ },
733
+ // ── audit-guardrails (LLM) ───────────────────────────
734
+ auditGuardrails: async (opts) => {
735
+ return commandAuditGuardrails({
736
+ config: opts.config,
737
+ guardrails: opts.guardrails,
738
+ adapter: opts.adapter,
739
+ model: opts.model,
740
+ showPrompt: opts.showPrompt,
741
+ failOn: opts.failOn,
742
+ output: opts.output,
743
+ reportFormat: opts.reportFormat,
744
+ logFile: opts.logFile,
745
+ });
746
+ },
747
+ };
748
+ createProgram(handlers, VERSION).parse();
749
+ // =============================================================================
750
+ // Helper functions (used by init, deps commands)
751
+ // =============================================================================
752
+ function processOpenAPIWithExtensions(openapiPath) {
753
+ const content = fs.readFileSync(openapiPath, 'utf-8');
754
+ const spec = yaml.parse(content);
755
+ const stats = { servicesAdded: 0, methodsAdded: 0, services: new Set() };
756
+ const httpMethods = ['get', 'post', 'put', 'patch', 'delete', 'head', 'options'];
757
+ if (spec.paths) {
758
+ for (const [pathKey, pathItem] of Object.entries(spec.paths)) {
759
+ if (!pathItem || typeof pathItem !== 'object')
760
+ continue;
761
+ const service = inferServiceFromPath(pathKey);
762
+ for (const method of httpMethods) {
763
+ const operation = pathItem[method];
764
+ if (!operation || typeof operation !== 'object')
765
+ continue;
766
+ const op = operation;
767
+ if (!op['x-micro-contracts-service'] && service) {
768
+ op['x-micro-contracts-service'] = service;
769
+ stats.servicesAdded++;
770
+ stats.services.add(service);
771
+ }
772
+ if (!op['x-micro-contracts-method']) {
773
+ const methodName = op.operationId
774
+ ? String(op.operationId)
775
+ : inferMethodName(method, pathKey);
776
+ op['x-micro-contracts-method'] = methodName;
777
+ stats.methodsAdded++;
778
+ }
779
+ }
780
+ }
781
+ }
782
+ const output = yaml.stringify(spec, { indent: 2 });
783
+ return { yaml: output, stats: { ...stats, services: Array.from(stats.services) } };
784
+ }
785
+ function inferServiceFromPath(pathKey) {
786
+ const normalized = pathKey.replace(/^\/api\//, '/').replace(/^\/v\d+\//, '/');
787
+ const segments = normalized.split('/').filter(Boolean);
788
+ if (segments.length === 0)
789
+ return null;
790
+ const firstSegment = segments[0];
791
+ if (firstSegment.startsWith('{'))
792
+ return null;
793
+ const words = firstSegment.replace(/-/g, '_').split('_');
794
+ const pascalCase = words
795
+ .map(word => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
796
+ .join('');
797
+ if (pascalCase.endsWith('s') && !pascalCase.endsWith('ss')) {
798
+ return pascalCase.slice(0, -1);
799
+ }
800
+ return pascalCase;
801
+ }
802
+ function inferMethodName(httpMethod, pathKey) {
803
+ const segments = pathKey
804
+ .replace(/^\/api\//, '/')
805
+ .replace(/^\/v\d+\//, '/')
806
+ .split('/')
807
+ .filter(Boolean);
808
+ const hasIdParam = segments.some(s => s.startsWith('{'));
809
+ const resourceSegments = segments.filter(s => !s.startsWith('{'));
810
+ const resourceName = resourceSegments
811
+ .map((seg) => {
812
+ const words = seg.replace(/-/g, '_').split('_');
813
+ return words
814
+ .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
815
+ .join('');
816
+ })
817
+ .join('');
818
+ const singularName = resourceName.endsWith('s') && !resourceName.endsWith('ss')
819
+ ? resourceName.slice(0, -1)
820
+ : resourceName;
821
+ switch (httpMethod.toLowerCase()) {
822
+ case 'get': return hasIdParam ? `get${singularName}ById` : `get${resourceName}`;
823
+ case 'post': return `create${singularName}`;
824
+ case 'put': return `update${singularName}`;
825
+ case 'patch': return `patch${singularName}`;
826
+ case 'delete': return `delete${singularName}`;
827
+ default: return `${httpMethod.toLowerCase()}${resourceName}`;
828
+ }
829
+ }
830
+ function generateDbTemplate() {
831
+ return `import pg from 'pg';
832
+ import { DBModel, PostgresDriver } from 'litedbmodel';
833
+
834
+ const { Pool } = pg;
835
+
836
+ let pool: pg.Pool | null = null;
837
+
838
+ export function getPool(): pg.Pool {
839
+ if (!pool) {
840
+ pool = new Pool({
841
+ connectionString: process.env.DATABASE_URL,
842
+ max: 20,
843
+ idleTimeoutMillis: 30000,
844
+ connectionTimeoutMillis: 2000,
845
+ });
846
+ }
847
+ return pool;
848
+ }
849
+
850
+ export async function initializeDb(): Promise<void> {
851
+ const p = getPool();
852
+ DBModel.setDriver(new PostgresDriver(p));
853
+ const client = await p.connect();
854
+ try {
855
+ await client.query('SELECT 1');
856
+ } finally {
857
+ client.release();
858
+ }
859
+ }
860
+
861
+ export async function closeDb(): Promise<void> {
862
+ if (pool) {
863
+ await pool.end();
864
+ pool = null;
865
+ }
866
+ }
867
+
868
+ export async function testConnection(): Promise<boolean> {
869
+ try {
870
+ const p = getPool();
871
+ const client = await p.connect();
872
+ try {
873
+ await client.query('SELECT 1');
874
+ return true;
875
+ } finally {
876
+ client.release();
877
+ }
878
+ } catch {
879
+ return false;
880
+ }
881
+ }
882
+ `;
883
+ }
884
+ function generateContainerTemplate(moduleName) {
885
+ const pascalName = moduleName.charAt(0).toUpperCase() + moduleName.slice(1);
886
+ return `import { testConnection, closeDb } from './db.js';
887
+
888
+ export interface ${pascalName}Services {
889
+ // example: ExampleServiceApi;
890
+ }
891
+
892
+ export interface ${pascalName}ModuleContainer {
893
+ services: ${pascalName}Services;
894
+ testConnection: () => Promise<boolean>;
895
+ close: () => Promise<void>;
896
+ }
897
+
898
+ export async function initialize${pascalName}Module(): Promise<${pascalName}ModuleContainer> {
899
+ const services: ${pascalName}Services = {};
900
+
901
+ return {
902
+ services,
903
+ testConnection,
904
+ close: closeDb,
905
+ };
906
+ }
907
+ `;
908
+ }
909
+ function generateConfigTemplate(moduleName) {
910
+ return [
911
+ '# micro-contracts Configuration', '',
912
+ 'defaults:', ' contract:', ' output: packages/contract/{module}', '',
913
+ ' contractPublic:', ' output: packages/contract-published/{module}', '',
914
+ ' outputs:', ' server-routes:', ' output: server/src/{module}/routes.generated.ts',
915
+ ' template: spec/default/templates/fastify-routes.hbs', ' config:',
916
+ ' servicesPath: fastify.services.{module}', '',
917
+ ' frontend-api:', ' output: frontend/src/{module}/api.generated.ts',
918
+ ' template: spec/default/templates/fetch-client.hbs', '',
919
+ ' shared-client:', ' output: frontend/src/shared/{module}.api.generated.ts',
920
+ ' template: spec/default/templates/fetch-client.hbs', ' condition: hasPublicEndpoints', ' config:',
921
+ ' contractPackage: "@project/contract-published/{module}"', '',
922
+ 'modules:', ` ${moduleName}:`, ` openapi: spec/${moduleName}/openapi/${moduleName}.yaml`, '',
923
+ ].join('\n');
924
+ }
925
+ function generateScreenConfigTemplate(moduleName) {
926
+ return [
927
+ '# micro-contracts Configuration (Screen Spec)', '',
928
+ 'defaults:', ' contract:', ' output: packages/contract/{module}', '',
929
+ 'modules:', ` ${moduleName}:`, ` openapi: spec/${moduleName}/openapi/${moduleName}.yaml`,
930
+ ' screen: true', ' outputs:', ' screen-navigation:',
931
+ ` output: frontend/src/screens/navigation.generated.ts`,
932
+ ' template: spec/default/templates/screen-navigation.hbs', ' screen-events:',
933
+ ` output: frontend/src/screens/events.generated.ts`,
934
+ ' template: spec/default/templates/screen-events.hbs', '',
935
+ ].join('\n');
936
+ }
937
+ function generateProblemDetailsSchema() {
938
+ return `# RFC 9457 Problem Details
939
+ components:
940
+ schemas:
941
+ ProblemDetails:
942
+ type: object
943
+ required: [type, title, status]
944
+ properties:
945
+ type:
946
+ type: string
947
+ format: uri
948
+ title:
949
+ type: string
950
+ status:
951
+ type: integer
952
+ detail:
953
+ type: string
954
+ instance:
955
+ type: string
956
+ format: uri
957
+ code:
958
+ type: string
959
+ traceId:
960
+ type: string
961
+ errors:
962
+ type: array
963
+ items:
964
+ type: object
965
+ properties:
966
+ field:
967
+ type: string
968
+ message:
969
+ type: string
970
+ `;
971
+ }
972
+ function generateSpectralRules() {
973
+ return `extends: ["spectral:oas"]
974
+
975
+ rules:
976
+ operation-service:
977
+ description: "Operations must have x-micro-contracts-service"
978
+ severity: error
979
+ given: "$.paths[*][get,post,put,patch,delete]"
980
+ then:
981
+ field: x-micro-contracts-service
982
+ function: truthy
983
+
984
+ operation-method:
985
+ description: "Operations must have x-micro-contracts-method"
986
+ severity: error
987
+ given: "$.paths[*][get,post,put,patch,delete]"
988
+ then:
989
+ field: x-micro-contracts-method
990
+ function: truthy
991
+
992
+ operation-error-responses:
993
+ description: "Operations should have 5XX or default error response"
994
+ severity: warn
995
+ given: "$.paths[*][get,post,put,patch,delete].responses"
996
+ then:
997
+ function: schema
998
+ functionOptions:
999
+ schema:
1000
+ anyOf:
1001
+ - required: ["500"]
1002
+ - required: ["5XX"]
1003
+ - required: ["default"]
1004
+
1005
+ canonical-extension-prefix:
1006
+ description: "Use canonical x-micro-contracts-* extensions"
1007
+ severity: warn
1008
+ given: "$.paths[*][get,post,put,patch,delete]"
1009
+ then:
1010
+ - field: x-service
1011
+ function: falsy
1012
+ - field: x-method
1013
+ function: falsy
1014
+ - field: x-public
1015
+ function: falsy
1016
+ `;
1017
+ }
1018
+ function generateScreenSpecTemplate(moduleName) {
1019
+ const pascalName = moduleName.charAt(0).toUpperCase() + moduleName.slice(1);
1020
+ return `openapi: '3.1.0'
1021
+ info:
1022
+ title: ${pascalName} Screen Specification
1023
+ version: '0.1.0'
1024
+ description: |
1025
+ Screen contract for ${moduleName} domain.
1026
+ servers:
1027
+ - url: /
1028
+ description: Screen routes (client-side)
1029
+ paths:
1030
+ /home:
1031
+ get:
1032
+ operationId: renderHomePage
1033
+ security: [{session: []}]
1034
+ x-screen-const: HOME
1035
+ x-screen-id: SCR-001
1036
+ x-screen-name: HomePage
1037
+ x-back-navigation: false
1038
+ summary: Render home page
1039
+ responses:
1040
+ '200':
1041
+ description: Home page ViewModel
1042
+ content:
1043
+ application/json:
1044
+ schema:
1045
+ \$ref: '#/components/schemas/HomePageViewModel'
1046
+ links:
1047
+ goToSettings:
1048
+ operationId: renderSettingsPage
1049
+ /settings:
1050
+ get:
1051
+ operationId: renderSettingsPage
1052
+ security: [{session: []}]
1053
+ x-screen-const: SETTINGS
1054
+ x-screen-id: SCR-002
1055
+ x-screen-name: SettingsPage
1056
+ x-back-navigation: true
1057
+ summary: Render settings page
1058
+ responses:
1059
+ '200':
1060
+ description: Settings page ViewModel
1061
+ content:
1062
+ application/json:
1063
+ schema:
1064
+ \$ref: '#/components/schemas/SettingsPageViewModel'
1065
+ links:
1066
+ goToHome:
1067
+ operationId: renderHomePage
1068
+ components:
1069
+ securitySchemes:
1070
+ session:
1071
+ type: apiKey
1072
+ in: cookie
1073
+ name: session
1074
+ schemas:
1075
+ HomePageViewModel:
1076
+ type: object
1077
+ required: [greeting]
1078
+ properties:
1079
+ greeting:
1080
+ type: string
1081
+ SettingsPageViewModel:
1082
+ type: object
1083
+ required: [theme]
1084
+ properties:
1085
+ theme:
1086
+ type: string
1087
+ enum: [light, dark]
1088
+ `;
1089
+ }
1090
+ function outputDependencyGraph(moduleDeps) {
1091
+ console.log('```mermaid');
1092
+ console.log('graph LR');
1093
+ for (const [moduleName, { deps }] of moduleDeps) {
1094
+ const moduleTargets = new Set();
1095
+ for (const dep of deps) {
1096
+ const parts = dep.split('.');
1097
+ if (parts.length >= 1)
1098
+ moduleTargets.add(parts[0]);
1099
+ }
1100
+ for (const target of moduleTargets) {
1101
+ console.log(` ${moduleName} --> ${target}`);
1102
+ }
1103
+ }
1104
+ console.log('```');
1105
+ }
1106
+ /**
1107
+ * Does `ref` name this dependency, or something containing it?
1108
+ *
1109
+ * Matching at dot boundaries only: `core` and `core.User` name parts of
1110
+ * `core.User.getUsers`, while `cor` names nothing. Exact-matching turned a
1111
+ * module name into "no impact", and prefix-matching turned a typo into a hit —
1112
+ * both answers a reader would act on.
1113
+ */
1114
+ function dependencyMatches(dep, ref) {
1115
+ return dep === ref || dep.startsWith(`${ref}.`);
1116
+ }
1117
+ /**
1118
+ * Modules whose declared dependencies match `ref`.
1119
+ *
1120
+ * Fails when `ref` names nothing declared: "nothing depends on this" must not be
1121
+ * the answer to a reference that does not exist.
1122
+ */
1123
+ function modulesDependingOn(moduleDeps, ref) {
1124
+ const known = new Set();
1125
+ for (const [moduleName, { deps }] of moduleDeps) {
1126
+ known.add(moduleName);
1127
+ for (const dep of deps) {
1128
+ const [module, service, method] = dep.split('.');
1129
+ known.add(module);
1130
+ if (service)
1131
+ known.add(`${module}.${service}`);
1132
+ if (method)
1133
+ known.add(dep);
1134
+ }
1135
+ }
1136
+ if (!known.has(ref)) {
1137
+ throw new Error(`Unknown module or API reference: '${ref}'. ` +
1138
+ `Known: ${[...known].sort().join(', ')}`);
1139
+ }
1140
+ const dependent = [];
1141
+ for (const [moduleName, { deps }] of moduleDeps) {
1142
+ if (deps.some(dep => dependencyMatches(dep, ref)))
1143
+ dependent.push(moduleName);
1144
+ }
1145
+ return dependent;
1146
+ }
1147
+ function outputImpactAnalysis(moduleDeps, ref) {
1148
+ const impacted = modulesDependingOn(moduleDeps, ref);
1149
+ console.log(`Impacted by changes to ${ref}:\n`);
1150
+ if (impacted.length === 0) {
1151
+ console.log(' No modules depend on this API.');
1152
+ }
1153
+ else {
1154
+ for (const m of impacted)
1155
+ console.log(` - ${m}`);
1156
+ }
1157
+ }
1158
+ function outputWhoDependsOn(moduleDeps, ref) {
1159
+ const dependent = modulesDependingOn(moduleDeps, ref);
1160
+ console.log(`Modules that depend on ${ref}:\n`);
1161
+ if (dependent.length === 0) {
1162
+ console.log(' None found.');
1163
+ }
1164
+ else {
1165
+ for (const m of dependent)
1166
+ console.log(` - ${m}`);
1167
+ }
1168
+ }
1169
+ function validateDependencies(moduleDeps) {
1170
+ let hasErrors = false;
1171
+ for (const [moduleName, { openApiDeps, configDeps }] of moduleDeps) {
1172
+ for (const dep of configDeps) {
1173
+ if (!openApiDeps.includes(dep)) {
1174
+ console.error(`ERROR: ${moduleName}.dependsOn includes '${dep}'`);
1175
+ console.error(` but it's not declared in OpenAPI x-micro-contracts-depend-on`);
1176
+ hasErrors = true;
1177
+ }
1178
+ }
1179
+ }
1180
+ if (!hasErrors) {
1181
+ console.log('✓ All dependencies are valid');
1182
+ }
1183
+ else {
1184
+ process.exit(1);
1185
+ }
1186
+ }
1187
+ function outputAllDependencies(moduleDeps) {
1188
+ console.log('Module Dependencies:\n');
1189
+ for (const [moduleName, { deps }] of moduleDeps) {
1190
+ console.log(`${moduleName}:`);
1191
+ if (deps.length === 0) {
1192
+ console.log(' (no dependencies)');
1193
+ }
1194
+ else {
1195
+ for (const dep of deps)
1196
+ console.log(` - ${dep}`);
1197
+ }
1198
+ console.log();
1199
+ }
1200
+ }
1201
+ //# sourceMappingURL=cli.js.map