@zintrust/core 0.1.18 → 0.1.20

package/src/cli/scaffolding/ControllerGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ControllerGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ControllerGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE/F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAgChG;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA2CjG;AA4bD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAEpD;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;EAI9B,CAAC"}
+{"version":3,"file":"ControllerGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/ControllerGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,KAAK,GAAG,SAAS,GAAG,WAAW,GAAG,SAAS,CAAC;AAE/F,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,cAAc,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,yBAAyB;IACxC,OAAO,EAAE,OAAO,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB;AAcD;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,iBAAiB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAgChG;AAED;;GAEG;AAEH,wBAAgB,kBAAkB,CAAC,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,yBAAyB,CAAC,CA2CjG;AA8eD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,cAAc,EAAE,CAEpD;AAED;;GAEG;AACH,eAAO,MAAM,mBAAmB;;;;EAI9B,CAAC"}

package/src/cli/scaffolding/ControllerGenerator.js

@@ -125,7 +125,7 @@ function handleError(res: IResponse, error: unknown): void {
   res.setStatus(500).json({ error: message });
 }
 
-export const ${className} = Object.freeze({
+const controller = Object.freeze({
   ...Controller,
 ${buildIndexMethod(modelName)},
 
@@ -137,6 +137,16 @@ ${buildUpdateMethod(modelName)},
 
 ${buildDestroyMethod(modelName)},
 });
+
+export type ${className}Api = typeof controller;
+
+export const ${className} = Object.freeze({
+  create(): ${className}Api {
+    return controller;
+  },
+});
+
+export default ${className};
 `;
 }
 /**
@@ -283,16 +293,26 @@ function handleError(res: IResponse, error: unknown): void {
   res.setStatus(500).json({ error: message });
 }
 
-export const ${className} = {\n  ...Controller,
-${buildApiControllerBody(className)},
-};
+const controller = Object.freeze({\n  ...Controller,
+${buildApiControllerBody()},
+});
+
+export type ${className}Api = typeof controller;
+
+export const ${className} = Object.freeze({
+  create(): ${className}Api {
+    return controller;
+  },
+});
+
+export default ${className};
 `;
 }
 /**
  * Build API controller body
  */
-function buildApiControllerBody(className) {
-    return `${buildApiMainHandler(className)},
+function buildApiControllerBody() {
+    return `${buildApiMainHandler()},
 
 ${buildApiMethodHandlers()},
 `;
@@ -300,7 +320,7 @@ ${buildApiMethodHandlers()},
 /**
  * Build API main handler
  */
-function buildApiMainHandler(className) {
+function buildApiMainHandler() {
     return `  /**
    * API endpoint template
    */
@@ -310,13 +330,13 @@ function buildApiMainHandler(className) {
 
       // Route to appropriate handler
       if (method === 'GET') {
-        await ${className}.handleGet(req, res);
+        await controller.handleGet(req, res);
       } else if (method === 'POST') {
-        await ${className}.handlePost(req, res);
+        await controller.handlePost(req, res);
       } else if (method === 'PUT') {
-        await ${className}.handlePut(req, res);
+        await controller.handlePut(req, res);
       } else if (method === 'DELETE') {
-        await ${className}.handleDelete(req, res);
+        await controller.handleDelete(req, res);
       } else {
         res.setStatus(405).json({ error: 'Method not allowed' });
       }
@@ -374,7 +394,7 @@ function handleError(res: IResponse, error: unknown): void {
   res.setStatus(500).json({ errors: [{ message }] });
 }
 
-export const ${className} = {\n  ...Controller,
+const controller = Object.freeze({\n  ...Controller,
   /**
    * GraphQL endpoint
    */
@@ -389,7 +409,7 @@ export const ${className} = {\n  ...Controller,
       const query = body.query as string;
 
       // TODO: Execute GraphQL query
-      const result = await ${className}.executeQuery(query);
+      const result = await controller.executeQuery(query);
 
       res.json(result);
     } catch (error) {
@@ -404,7 +424,17 @@ export const ${className} = {\n  ...Controller,
     // TODO: Implement GraphQL execution
     return { data: null };
   },
-};
+});
+
+export type ${className}Api = typeof controller;
+
+export const ${className} = Object.freeze({
+  create(): ${className}Api {
+    return controller;
+  },
+});
+
+export default ${className};
 `;
 }
 /**
@@ -419,7 +449,7 @@ function generateWebSocketController(options) {
 
 import { Logger } from '../../config/logger';
 
-export const ${className} = {
+const controller = Object.freeze({
   /**
    * Handle WebSocket connection
    */
@@ -441,7 +471,17 @@ export const ${className} = {
   async onDisconnect(socket: { id: string }): Promise<void> {
     Logger.info('Client disconnected:', { socketId: socket.id });
   },
-};
+});
+
+export type ${className}Api = typeof controller;
+
+export const ${className} = Object.freeze({
+  create(): ${className}Api {
+    return controller;
+  },
+});
+
+export default ${className};
 `;
 }
 /**
@@ -462,15 +502,25 @@ function handleError(res: IResponse, error: unknown): void {
   res.setStatus(500).json({ error: message });
 }
 
-export const ${className} = {\n  ...Controller,
-${buildWebhookControllerBody(className)},
-};
+const controller = Object.freeze({\n  ...Controller,
+${buildWebhookControllerBody()},
+});
+
+export type ${className}Api = typeof controller;
+
+export const ${className} = Object.freeze({
+  create(): ${className}Api {
+    return controller;
+  },
+});
+
+export default ${className};
 `;
 }
 /**
  * Build Webhook controller body
  */
-function buildWebhookControllerBody(className) {
+function buildWebhookControllerBody() {
     return `  /**
    * Handle incoming webhook
    */
@@ -478,13 +528,13 @@ function buildWebhookControllerBody(className) {
     try {
       // Verify webhook signature
       const signature = req.getHeader('x-webhook-signature');
-      if (${className}.verifySignature(req, signature as string) === false) {
+      if (controller.verifySignature(req, signature as string) === false) {
         res.setStatus(401).json({ error: 'Invalid signature' });
         return;
       }
 
       const body = req.getBody();
-      await ${className}.processWebhook(body);
+      await controller.processWebhook(body);
 
       res.json({ success: true });
     } catch (error) {

package/src/cli/scaffolding/FactoryGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"FactoryGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/FactoryGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AAEH;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B5E;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAyB9F;AA+SD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;EAI3B,CAAC"}
+{"version":3,"file":"FactoryGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/FactoryGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AASH,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,GACT,MAAM,GACN,UAAU,GACV,MAAM,GACN,OAAO,GACP,OAAO,CAAC;AAEZ,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,cAAc;IAC7B,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,MAAM,CAAC;IAClB,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,EAAE,YAAY,EAAE,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;GAEG;AAEH;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CA6B5E;AAED;;GAEG;AACH,wBAAsB,eAAe,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAyB9F;AAiTD;;GAEG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,EAAE,CAE5C;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;EAI3B,CAAC"}

package/src/cli/scaffolding/FactoryGenerator.js

@@ -156,8 +156,10 @@ ${statePatterns}
 
         return result;
       }
+    };
+
     return factory;
-  }`;
+  },`;
 }
 /**
  * Build import statements

package/src/cli/scaffolding/GovernanceScaffolder.d.ts

@@ -0,0 +1,23 @@
+/**
+ * GovernanceScaffolder
+ *
+ * Adds optional governance tooling to a generated app:
+ * - ESLint config + scripts
+ * - Architecture tests (Vitest)
+ */
+export type GovernanceScaffoldOptions = Readonly<{
+    writeEslintConfig?: boolean;
+    writeArchTests?: boolean;
+    install?: boolean;
+    packageManager?: string;
+}>;
+export type GovernanceScaffoldResult = Readonly<{
+    success: boolean;
+    filesCreated: string[];
+    message: string;
+}>;
+export declare const GovernanceScaffolder: Readonly<{
+    scaffold(projectRoot: string, options?: GovernanceScaffoldOptions): Promise<GovernanceScaffoldResult>;
+}>;
+export default GovernanceScaffolder;
+//# sourceMappingURL=GovernanceScaffolder.d.ts.map

package/src/cli/scaffolding/GovernanceScaffolder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"GovernanceScaffolder.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/GovernanceScaffolder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAmBH,MAAM,MAAM,yBAAyB,GAAG,QAAQ,CAAC;IAC/C,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,CAAC;IAC9C,OAAO,EAAE,OAAO,CAAC;IACjB,YAAY,EAAE,MAAM,EAAE,CAAC;IACvB,OAAO,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AA8RH,eAAO,MAAM,oBAAoB;0BAEhB,MAAM,YACV,yBAAyB,GACjC,OAAO,CAAC,wBAAwB,CAAC;EA+DpC,CAAC;AAEH,eAAe,oBAAoB,CAAC"}

package/src/cli/scaffolding/GovernanceScaffolder.js

@@ -0,0 +1,327 @@
+/**
+ * GovernanceScaffolder
+ *
+ * Adds optional governance tooling to a generated app:
+ * - ESLint config + scripts
+ * - Architecture tests (Vitest)
+ */
+import { FileGenerator } from '../scaffolding/FileGenerator.js';
+import { SpawnUtil } from '../utils/spawn.js';
+import { resolvePackageManager } from '../../common/index.js';
+import { Logger } from '../../config/logger.js';
+import { ErrorFactory } from '../../exceptions/ZintrustError.js';
+import * as path from '../../node-singletons/path.js';
+const getStringRecord = (value) => {
+    if (typeof value !== 'object' || value === null)
+        return undefined;
+    const obj = value;
+    const out = {};
+    for (const [k, v] of Object.entries(obj)) {
+        if (typeof v === 'string')
+            out[k] = v;
+    }
+    return out;
+};
+const readPackageJsonOrThrow = (projectRoot) => {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    if (!FileGenerator.fileExists(pkgPath)) {
+        throw ErrorFactory.createValidationError(`package.json not found at ${pkgPath}`);
+    }
+    const raw = FileGenerator.readFile(pkgPath);
+    const parsed = JSON.parse(raw);
+    if (typeof parsed !== 'object' || parsed === null) {
+        throw ErrorFactory.createValidationError('package.json is not a JSON object');
+    }
+    return parsed;
+};
+const writePackageJson = (projectRoot, pkg) => {
+    const pkgPath = path.join(projectRoot, 'package.json');
+    const content = `${JSON.stringify(pkg, null, 2)}\n`;
+    FileGenerator.writeFile(pkgPath, content, { overwrite: true });
+};
+const upsertScript = (scripts, name, value) => {
+    if (typeof scripts[name] !== 'string' || scripts[name] === '') {
+        scripts[name] = value;
+    }
+};
+const ensureDevDependency = (devDependencies, name, version) => {
+    if (typeof devDependencies[name] !== 'string' || devDependencies[name] === '') {
+        devDependencies[name] = version;
+    }
+};
+const inferGovernanceVersion = (pkg) => {
+    const deps = getStringRecord(pkg.dependencies);
+    const core = deps?.['@zintrust/core'];
+    if (typeof core === 'string' && core.trim() !== '')
+        return core;
+    return '^0.1.0';
+};
+const writeEslintConfig = (projectRoot) => {
+    const eslintConfigPath = path.join(projectRoot, 'eslint.config.mjs');
+    const content = `import { zintrustAppEslintConfig } from '@zintrust/governance';
+
+export default zintrustAppEslintConfig({
+  tsconfigRootDir: import.meta.dirname,
+});
+`;
+    const wrote = FileGenerator.writeFile(eslintConfigPath, content, { overwrite: false });
+    return wrote ? [eslintConfigPath] : [];
+};
+const IMPORT_BOUNDARIES_ARCH_TEST_CONTENT = `import * as fs from 'node:fs/promises';
+import * as path from 'node:path';
+import * as ts from 'typescript';
+import { describe, expect, it } from 'vitest';
+
+type ImportHit = {
+  specifier: string;
+  line: string;
+};
+
+type Violation = {
+  file: string;
+  reason: string;
+  hit: ImportHit;
+};
+
+const repoRoot = process.cwd();
+
+const isTsFile = (filePath: string): boolean => {
+  if (!filePath.endsWith('.ts')) return false;
+  if (filePath.endsWith('.d.ts')) return false;
+  return true;
+};
+
+const walkTsFiles = async (dir: string): Promise<string[]> => {
+  const entries = await fs.readdir(dir, { withFileTypes: true });
+
+  const files = entries
+    .filter((ent) => ent.isFile())
+    .map((ent) => path.join(dir, ent.name))
+    .filter(isTsFile);
+
+  const subDirs = entries.filter((ent) => ent.isDirectory()).map((ent) => path.join(dir, ent.name));
+  const nested = await Promise.all(subDirs.map((subDir) => walkTsFiles(subDir)));
+
+  return [...files, ...nested.flat()];
+};
+
+const extractImportSpecifiers = (source: string, filePath: string): ImportHit[] => {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    source,
+    ts.ScriptTarget.ESNext,
+    true,
+    ts.ScriptKind.TS
+  );
+  const lines = source.split(/\r?\n/);
+  const hits: ImportHit[] = [];
+
+  const addHit = (specifier: string, pos: number) => {
+    const { line } = sourceFile.getLineAndCharacterOfPosition(pos);
+    hits.push({
+      specifier,
+      line: (lines[line] ?? '').trim(),
+    });
+  };
+
+  const visit = (node: ts.Node) => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      const moduleSpecifier = node.moduleSpecifier;
+      if (moduleSpecifier && ts.isStringLiteral(moduleSpecifier)) {
+        addHit(moduleSpecifier.text, moduleSpecifier.getStart(sourceFile));
+      }
+    }
+
+    if (ts.isCallExpression(node) && node.expression.kind === ts.SyntaxKind.ImportKeyword) {
+      const arg = node.arguments.at(0);
+      if (arg && ts.isStringLiteral(arg)) {
+        addHit(arg.text, arg.getStart(sourceFile));
+      }
+    }
+
+    ts.forEachChild(node, visit);
+  };
+
+  visit(sourceFile);
+  return hits.filter((h) => h.specifier.trim() !== '');
+};
+
+const relFromRoot = (absPath: string): string => path.relative(repoRoot, absPath).replaceAll('\\\\', '/');
+
+const startsWithAny = (value: string, prefixes: readonly string[]): boolean => {
+  for (const p of prefixes) {
+    if (value.startsWith(p)) return true;
+  }
+  return false;
+};
+
+const findViolations = async (
+  files: string[],
+  disallowedPrefixes: readonly string[],
+  reasonPrefix: string
+): Promise<Violation[]> => {
+  const perFile = await Promise.all(
+    files.map(async (file): Promise<Violation[]> => {
+      const contents = await fs.readFile(file, 'utf-8');
+      const imports = extractImportSpecifiers(contents, file);
+
+      return imports
+        .filter((hit) => startsWithAny(hit.specifier, disallowedPrefixes))
+        .map((hit) => ({
+          file: relFromRoot(file),
+          reason: reasonPrefix + ' ' + hit.specifier,
+          hit,
+        }));
+    })
+  );
+
+  return perFile.flat();
+};
+
+describe('Architecture: import boundaries', () => {
+  it('prevents src/ from importing app/routes', async () => {
+    const srcDir = path.join(repoRoot, 'src');
+    const files = await walkTsFiles(srcDir);
+
+    const violations = await findViolations(files, ['@app/', '@routes/'], 'src/ must not import');
+
+    expect(violations).toEqual([]);
+  });
+
+  it('prevents app/ from importing routes', async () => {
+    const appDir = path.join(repoRoot, 'app');
+    const files = await walkTsFiles(appDir);
+
+    const violations = await findViolations(files, ['@routes/'], 'app/ must not import');
+
+    expect(violations).toEqual([]);
+  });
+});
+`;
+const ROUTE_MIDDLEWARE_REGISTRY_ARCH_TEST_CONTENT = `import { middlewareConfigObj } from '../../config/middleware';
+import { registerRoutes } from '../../../routes/api';
+import { RouteRegistry, Router } from '@zintrust/core';
+import { beforeEach, describe, expect, it } from 'vitest';
+
+describe('Architecture: route middleware registry', () => {
+  beforeEach(() => {
+    RouteRegistry.clear();
+  });
+
+  it('ensures all route middleware names exist in middlewareConfigObj', () => {
+    const router = Router.createRouter();
+    registerRoutes(router);
+
+    const allowed = new Set(Object.keys(middlewareConfigObj));
+    const unknown: Array<{ method: string; path: string; middleware: string }> = [];
+
+    for (const route of RouteRegistry.list()) {
+      for (const name of route.middleware ?? []) {
+        if (!allowed.has(name)) {
+          unknown.push({ method: route.method, path: route.path, middleware: name });
+        }
+      }
+    }
+
+    expect(unknown).toEqual([]);
+  });
+});
+`;
+const writeArchTests = (projectRoot) => {
+    const files = [
+        {
+            rel: 'tests/unit/architecture/ImportBoundaries.arch.test.ts',
+            content: IMPORT_BOUNDARIES_ARCH_TEST_CONTENT,
+        },
+        {
+            rel: 'tests/unit/architecture/RouteMiddlewareRegistry.arch.test.ts',
+            content: ROUTE_MIDDLEWARE_REGISTRY_ARCH_TEST_CONTENT,
+        },
+    ];
+    const created = [];
+    for (const file of files) {
+        const abs = path.join(projectRoot, file.rel);
+        const wrote = FileGenerator.writeFile(abs, file.content, {
+            overwrite: false,
+            createDirs: true,
+        });
+        if (wrote)
+            created.push(abs);
+    }
+    return created;
+};
+const installGovernanceDeps = async (projectRoot, pm, packages) => {
+    if (packages.length === 0)
+        return;
+    let command = pm;
+    let args;
+    switch (pm) {
+        case 'pnpm':
+            args = ['add', '-D', ...packages];
+            break;
+        case 'yarn':
+            args = ['add', '--dev', ...packages];
+            break;
+        case 'npm':
+        default:
+            command = 'npm';
+            args = ['install', '--save-dev', ...packages];
+            break;
+    }
+    const exit = await SpawnUtil.spawnAndWait({ command, args, cwd: projectRoot });
+    if (exit !== 0) {
+        throw ErrorFactory.createCliError(`Failed to install governance dependencies (exit ${exit})`);
+    }
+};
+export const GovernanceScaffolder = Object.freeze({
+    async scaffold(projectRoot, options = {}) {
+        try {
+            const pkg = readPackageJsonOrThrow(projectRoot);
+            const scripts = typeof pkg.scripts === 'object' && pkg.scripts !== null ? pkg.scripts : {};
+            pkg.scripts = scripts;
+            upsertScript(scripts, 'lint', 'eslint .');
+            upsertScript(scripts, 'test:coverage', 'vitest run --coverage');
+            upsertScript(scripts, 'sonarqube', 'node -e "console.log(\'SonarQube not configured for this project; skipping.\');"');
+            const devDeps = typeof pkg.devDependencies === 'object' && pkg.devDependencies !== null
+                ? pkg.devDependencies
+                : {};
+            pkg.devDependencies = devDeps;
+            const govVersion = inferGovernanceVersion(pkg);
+            ensureDevDependency(devDeps, 'eslint', '^9.0.0');
+            ensureDevDependency(devDeps, '@zintrust/governance', govVersion);
+            writePackageJson(projectRoot, pkg);
+            const filesCreated = [];
+            if (options.writeEslintConfig !== false) {
+                filesCreated.push(...writeEslintConfig(projectRoot));
+            }
+            if (options.writeArchTests !== false) {
+                filesCreated.push(...writeArchTests(projectRoot));
+            }
+            if (options.install === true) {
+                const pm = typeof options.packageManager === 'string' && options.packageManager.trim() !== ''
+                    ? options.packageManager.trim()
+                    : resolvePackageManager();
+                Logger.info(`Installing governance devDependencies using ${pm}...`);
+                await installGovernanceDeps(projectRoot, pm, [
+                    'eslint',
+                    `@zintrust/governance@${govVersion}`,
+                ]);
+            }
+            return {
+                success: true,
+                filesCreated,
+                message: 'Governance installed successfully',
+            };
+        }
+        catch (error) {
+            Logger.error('Governance scaffolding failed', error);
+            const msg = error instanceof Error ? error.message : String(error);
+            return {
+                success: false,
+                filesCreated: [],
+                message: msg,
+            };
+        }
+    },
+});
+export default GovernanceScaffolder;

package/src/cli/scaffolding/MigrationGenerator.d.ts

@@ -7,6 +7,16 @@ export interface MigrationOptions {
     name: string;
     migrationsPath: string;
     type?: MigrationType;
+    /**
+     * Optional explicit table name to use in generated content.
+     * When provided, the generator will use it instead of inferring from the migration name.
+     */
+    table?: string;
+    /**
+     * Optional column name hint for alter migrations.
+     * When provided, the generator will use it in the example placeholder.
+     */
+    column?: string;
 }
 export interface MigrationScaffoldResult {
     success: boolean;

package/src/cli/scaffolding/MigrationGenerator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"MigrationGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/MigrationGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,aAAa,CAAC;CACtB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmB/F;AAED;;GAEG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAwD7F;AAqLD;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;EAG7B,CAAC"}
+{"version":3,"file":"MigrationGenerator.d.ts","sourceRoot":"","sources":["../../../../src/cli/scaffolding/MigrationGenerator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAOH,MAAM,MAAM,aAAa,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,CAAC;AAExD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,IAAI,CAAC,EAAE,aAAa,CAAC;IACrB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,gBAAgB,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,CAmB/F;AAED;;GAEG;AAEH,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,uBAAuB,CAAC,CAwE7F;AAoRD;;GAEG;AACH,eAAO,MAAM,kBAAkB;;;EAG7B,CAAC"}