create-forgeon 0.2.2 → 0.2.4

package/bin/create-forgeon.mjs

@@ -1,14 +1,17 @@
 #!/usr/bin/env node
-import { runCreateForgeon } from '../src/run-create-forgeon.mjs';
-import { runAddModule } from '../src/run-add-module.mjs';
+import { runCreateForgeon } from '../src/run-create-forgeon.mjs';
+import { runAddModule } from '../src/run-add-module.mjs';
+import { runScanIntegrations } from '../src/run-scan-integrations.mjs';
 
 const args = process.argv.slice(2);
 const command = args[0];
 
-const task =
-  command === 'add'
-    ? runAddModule(args.slice(1))
-    : runCreateForgeon(args);
+const task =
+  command === 'add'
+    ? runAddModule(args.slice(1))
+    : command === 'scan-integrations'
+      ? runScanIntegrations(args.slice(1))
+    : runCreateForgeon(args);
 
 task.then(() => {
   if (typeof process.stdin.pause === 'function') {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-forgeon",
-  "version": "0.2.2",
+  "version": "0.2.4",
   "description": "Forgeon project generator CLI",
   "license": "MIT",
   "author": "Forgeon",

package/src/cli/add-help.mjs

@@ -4,9 +4,13 @@ export function printAddHelp() {
 Usage:
   npx create-forgeon@latest add <module-id> [options]
 
-Options:
-  --project <path>   Target project path (default: current directory)
-  --list             List available modules
-  -h, --help         Show this help
-`);
-}
+Options:
+  --project <path>   Target project path (default: current directory)
+  --list             List available modules
+  -h, --help         Show this help
+
+Note:
+  Pair integrations are explicit.
+  Run "pnpm forgeon:sync-integrations" in the target project after add-module steps.
+`);
+}

package/src/cli/help.mjs

@@ -1,10 +1,11 @@
 export function printHelp() {
   console.log(`create-forgeon
 
-Usage:
-  npx create-forgeon@latest <project-name> [options]
-  npx create-forgeon@latest add <module-id> [options]
-  npx create-forgeon@latest add --list
+Usage:
+  npx create-forgeon@latest <project-name> [options]
+  npx create-forgeon@latest add <module-id> [options]
+  npx create-forgeon@latest add --list
+  npx create-forgeon@latest scan-integrations [options]
 
 Create options:
   --db-prisma <true|false>     Enable db-prisma module (default: true)
@@ -14,8 +15,11 @@ Create options:
   -y, --yes                    Skip prompts and use defaults
   -h, --help                   Show this help
 
-Add options:
-  --project <path>             Target project path (default: current directory)
-  --list                       List available modules
-`);
-}
+Add options:
+  --project <path>             Target project path (default: current directory)
+  --list                       List available modules
+
+Scan options:
+  --project <path>             Target project path (default: current directory)
+`);
+}

package/src/integrations/flow.mjs

@@ -0,0 +1,118 @@
+import { promptSelect } from '../cli/prompt-select.mjs';
+import { scanIntegrations, syncIntegrations } from '../modules/sync-integrations.mjs';
+
+const ansi = {
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  dim: '\x1b[2m',
+};
+
+function colorize(color, text) {
+  return `${ansi[color]}${text}${ansi.reset}`;
+}
+
+function printGroup(group) {
+  console.log(`\n${colorize('yellow', `▶ ${group.title}`)}`);
+  group.modules.forEach((moduleId, index) => {
+    const branch = index === group.modules.length - 1 ? '└─' : '├─';
+    console.log(`   ${branch} ${colorize('cyan', moduleId)}`);
+  });
+  console.log('   This will:');
+  for (const line of group.description) {
+    console.log(`   • ${line}`);
+  }
+}
+
+async function chooseGroupSelection(groups) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return { kind: 'skip', ids: [] };
+  }
+
+  if (groups.length === 1) {
+    const picked = await promptSelect({
+      message: 'Apply now?',
+      defaultValue: 'skip',
+      choices: [
+        { label: 'No, skip for now', value: 'skip' },
+        { label: `Yes, apply "${groups[0].title}"`, value: groups[0].id },
+      ],
+    });
+    if (picked === 'skip') {
+      return { kind: 'skip', ids: [] };
+    }
+    return { kind: 'single', ids: [picked] };
+  }
+
+  const choices = groups.map((group) => ({
+    label: group.title,
+    value: group.id,
+  }));
+  choices.push({ label: 'Skip for now', value: '__skip' });
+  choices.push({ label: 'Sync all pending integrations', value: '__all' });
+
+  const picked = await promptSelect({
+    message: 'Select integration to apply now',
+    defaultValue: '__skip',
+    choices,
+  });
+
+  if (picked === '__skip') {
+    return { kind: 'skip', ids: [] };
+  }
+  if (picked === '__all') {
+    return { kind: 'all', ids: groups.map((group) => group.id) };
+  }
+  return { kind: 'single', ids: [picked] };
+}
+
+export async function runIntegrationFlow({
+  targetRoot,
+  packageRoot,
+  relatedModuleId = null,
+  scanMessage = 'Scanning for integrations...',
+}) {
+  console.log(scanMessage);
+  const scan = scanIntegrations({ targetRoot, relatedModuleId });
+  if (scan.groups.length === 0) {
+    console.log('No integration groups found.');
+    return { scanned: true, applied: false, groups: [] };
+  }
+
+  const groupWord = scan.groups.length === 1 ? 'group' : 'groups';
+  console.log(colorize('yellow', `Found ${scan.groups.length} integration ${groupWord}:`));
+  for (const group of scan.groups) {
+    printGroup(group);
+  }
+
+  console.log(colorize('dim', 'Command: pnpm forgeon:sync-integrations'));
+  const selection = await chooseGroupSelection(scan.groups);
+  if (selection.kind === 'skip') {
+    console.log('Integration skipped.');
+    console.log('Run later with: pnpm forgeon:sync-integrations');
+    return { scanned: true, applied: false, groups: scan.groups };
+  }
+
+  const sync = syncIntegrations({ targetRoot, packageRoot, groupIds: selection.ids });
+  console.log('[forgeon:sync-integrations] done');
+  for (const item of sync.summary) {
+    if (item.result.applied) {
+      console.log(`- ${item.title}: applied`);
+    } else {
+      console.log(`- ${item.title}: skipped (${item.result.reason})`);
+    }
+  }
+  if (sync.changedFiles.length > 0) {
+    console.log('- changed files:');
+    for (const filePath of sync.changedFiles) {
+      console.log(`  - ${filePath}`);
+    }
+  }
+  return { scanned: true, applied: true, groups: scan.groups, sync };
+}
+
+export function printModuleAdded(moduleId, docsPath) {
+  console.log(colorize('green', `✔ Module added: ${moduleId}`));
+  console.log(`- docs: ${docsPath}`);
+}

package/src/modules/db-prisma.mjs

@@ -1,6 +1,20 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { copyRecursive, writeJson } from '../utils/fs.mjs';
+import {
+  ensureBuildSteps,
+  ensureClassMember,
+  ensureDependency,
+  ensureDevDependency,
+  ensureImportLine,
+  ensureLineAfter,
+  ensureLineBefore,
+  ensureLoadItem,
+  ensureNestCommonImport,
+  ensureScript,
+  ensureValidatorSchema,
+  upsertEnvLines,
+} from './shared/patch-utils.mjs';
 
 function copyFromPreset(packageRoot, targetRoot, relativePath) {
   const source = path.join(packageRoot, 'templates', 'module-presets', 'db-prisma', relativePath);
@@ -11,167 +25,6 @@ function copyFromPreset(packageRoot, targetRoot, relativePath) {
   copyRecursive(source, destination);
 }
 
-function ensureDependency(packageJson, name, version) {
-  if (!packageJson.dependencies) {
-    packageJson.dependencies = {};
-  }
-  packageJson.dependencies[name] = version;
-}
-
-function ensureDevDependency(packageJson, name, version) {
-  if (!packageJson.devDependencies) {
-    packageJson.devDependencies = {};
-  }
-  packageJson.devDependencies[name] = version;
-}
-
-function ensureScript(packageJson, name, command) {
-  if (!packageJson.scripts) {
-    packageJson.scripts = {};
-  }
-  packageJson.scripts[name] = command;
-}
-
-function ensureBuildSteps(packageJson, scriptName, requiredCommands) {
-  if (!packageJson.scripts) {
-    packageJson.scripts = {};
-  }
-
-  const current = packageJson.scripts[scriptName];
-  const steps =
-    typeof current === 'string' && current.trim().length > 0
-      ? current
-          .split('&&')
-          .map((item) => item.trim())
-          .filter(Boolean)
-      : [];
-
-  for (const command of requiredCommands) {
-    if (!steps.includes(command)) {
-      steps.push(command);
-    }
-  }
-
-  if (steps.length > 0) {
-    packageJson.scripts[scriptName] = steps.join(' && ');
-  }
-}
-
-function ensureLineAfter(content, anchorLine, lineToInsert) {
-  if (content.includes(lineToInsert)) {
-    return content;
-  }
-
-  const index = content.indexOf(anchorLine);
-  if (index < 0) {
-    return `${content.trimEnd()}\n${lineToInsert}\n`;
-  }
-
-  const insertAt = index + anchorLine.length;
-  return `${content.slice(0, insertAt)}\n${lineToInsert}${content.slice(insertAt)}`;
-}
-
-function ensureLineBefore(content, anchorLine, lineToInsert) {
-  if (content.includes(lineToInsert)) {
-    return content;
-  }
-
-  const index = content.indexOf(anchorLine);
-  if (index < 0) {
-    return `${content.trimEnd()}\n${lineToInsert}\n`;
-  }
-
-  return `${content.slice(0, index)}${lineToInsert}\n${content.slice(index)}`;
-}
-
-function ensureNestCommonImport(content, importName) {
-  const pattern = /import\s*\{([^}]*)\}\s*from '@nestjs\/common';/m;
-  const match = content.match(pattern);
-  if (!match) {
-    return `import { ${importName} } from '@nestjs/common';\n${content}`;
-  }
-
-  const names = match[1]
-    .split(',')
-    .map((item) => item.trim())
-    .filter(Boolean);
-
-  if (!names.includes(importName)) {
-    names.push(importName);
-  }
-
-  const replacement = `import { ${names.join(', ')} } from '@nestjs/common';`;
-  return content.replace(pattern, replacement);
-}
-
-function upsertEnvLines(filePath, lines) {
-  let content = '';
-  if (fs.existsSync(filePath)) {
-    content = fs.readFileSync(filePath, 'utf8').replace(/\r\n/g, '\n');
-  }
-
-  const keys = new Set(
-    content
-      .split('\n')
-      .filter(Boolean)
-      .map((line) => line.split('=')[0]),
-  );
-
-  const append = [];
-  for (const line of lines) {
-    const key = line.split('=')[0];
-    if (!keys.has(key)) {
-      append.push(line);
-    }
-  }
-
-  const next =
-    append.length > 0 ? `${content.trimEnd()}\n${append.join('\n')}\n` : `${content.trimEnd()}\n`;
-  fs.writeFileSync(filePath, next.replace(/^\n/, ''), 'utf8');
-}
-
-function ensureLoadItem(content, itemName) {
-  const pattern = /load:\s*\[([^\]]*)\]/m;
-  const match = content.match(pattern);
-  if (!match) {
-    return content;
-  }
-
-  const rawList = match[1];
-  const items = rawList
-    .split(',')
-    .map((item) => item.trim())
-    .filter(Boolean);
-
-  if (!items.includes(itemName)) {
-    items.push(itemName);
-  }
-
-  const next = `load: [${items.join(', ')}]`;
-  return content.replace(pattern, next);
-}
-
-function ensureValidatorSchema(content, schemaName) {
-  const pattern = /validate:\s*createEnvValidator\(\[([^\]]*)\]\)/m;
-  const match = content.match(pattern);
-  if (!match) {
-    return content;
-  }
-
-  const rawList = match[1];
-  const items = rawList
-    .split(',')
-    .map((item) => item.trim())
-    .filter(Boolean);
-
-  if (!items.includes(schemaName)) {
-    items.push(schemaName);
-  }
-
-  const next = `validate: createEnvValidator([${items.join(', ')}])`;
-  return content.replace(pattern, next);
-}
-
 function patchApiPackage(targetRoot) {
   const packagePath = path.join(targetRoot, 'apps', 'api', 'package.json');
   if (!fs.existsSync(packagePath)) {
@@ -267,11 +120,7 @@ function patchHealthController(targetRoot) {
   content = ensureNestCommonImport(content, 'Post');
 
   if (!content.includes("from '@forgeon/db-prisma';")) {
-    const nestCommonImport = content.match(/import\s*\{[^}]*\}\s*from '@nestjs\/common';/m)?.[0];
-    const anchor = content.includes("import { I18nService } from 'nestjs-i18n';")
-      ? "import { I18nService } from 'nestjs-i18n';"
-      : nestCommonImport;
-    content = ensureLineAfter(content, anchor, "import { PrismaService } from '@forgeon/db-prisma';");
+    content = ensureImportLine(content, "import { PrismaService } from '@forgeon/db-prisma';");
   }
 
   if (!content.includes('private readonly prisma: PrismaService')) {
@@ -285,6 +134,16 @@ function patchHealthController(targetRoot) {
     private readonly prisma: PrismaService,
   ) {`;
       content = content.replace(original, next);
+    } else {
+      const classAnchor = 'export class HealthController {';
+      if (content.includes(classAnchor)) {
+        content = content.replace(
+          classAnchor,
+          `${classAnchor}
+  constructor(private readonly prisma: PrismaService) {}
+`,
+        );
+      }
     }
   }
 
@@ -306,12 +165,7 @@ function patchHealthController(targetRoot) {
     };
   }
 `;
-    const translateIndex = content.indexOf('private translate(');
-    if (translateIndex > -1) {
-      content = `${content.slice(0, translateIndex).trimEnd()}\n\n${dbMethod}\n${content.slice(translateIndex)}`;
-    } else {
-      content = `${content.trimEnd()}\n${dbMethod}\n`;
-    }
+    content = ensureClassMember(content, 'HealthController', dbMethod, { beforeNeedle: 'private translate(' });
   }
 
   fs.writeFileSync(filePath, `${content.trimEnd()}\n`, 'utf8');

package/src/modules/executor.test.mjs

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { addModule } from './executor.mjs';
+import { syncIntegrations } from './sync-integrations.mjs';
 import { scaffoldProject } from '../core/scaffold.mjs';
 
 function mkTmp(prefix) {
@@ -400,7 +401,6 @@ describe('addModule', () => {
       assert.match(rootPackage, /"i18n:check"/);
       assert.match(rootPackage, /"i18n:types"/);
       assert.match(rootPackage, /"i18n:add"/);
-      assert.match(rootPackage, /"ts-morph":/);
 
       const i18nAddScriptPath = path.join(projectRoot, 'scripts', 'i18n-add.mjs');
       assert.equal(fs.existsSync(i18nAddScriptPath), true);
@@ -893,7 +893,7 @@ describe('addModule', () => {
     }
   });
 
-  it('applies jwt-auth with db-prisma adapter and wires persistent token store', () => {
+  it('applies jwt-auth with db-prisma as stateless first, then wires persistence via explicit sync', () => {
     const targetRoot = mkTmp('forgeon-module-jwt-db-');
     const projectRoot = path.join(targetRoot, 'demo-jwt-db');
     const templateRoot = path.join(packageRoot, 'templates', 'base');
@@ -918,6 +918,14 @@ describe('addModule', () => {
       });
 
       assert.equal(result.applied, true);
+      assertJwtAuthWiring(projectRoot, false);
+
+      const syncResult = syncIntegrations({ targetRoot: projectRoot, packageRoot });
+      const dbPair = syncResult.summary.find((item) => item.id === 'auth-persistence');
+      assert.ok(dbPair);
+      assert.equal(dbPair.result.applied, true);
+      assert.equal(syncResult.changedFiles.length > 0, true);
+
       assertJwtAuthWiring(projectRoot, true);
 
       const storeFile = path.join(
@@ -955,15 +963,11 @@ describe('addModule', () => {
     }
   });
 
-  it('applies jwt-auth without db and prints warning with stateless fallback', () => {
+  it('applies jwt-auth without db and keeps stateless fallback until pair sync is available', () => {
     const targetRoot = mkTmp('forgeon-module-jwt-nodb-');
     const projectRoot = path.join(targetRoot, 'demo-jwt-nodb');
     const templateRoot = path.join(packageRoot, 'templates', 'base');
 
-    const originalError = console.error;
-    const warnings = [];
-    console.error = (...args) => warnings.push(args.join(' '));
-
     try {
       scaffoldProject({
         templateRoot,
@@ -996,10 +1000,146 @@ describe('addModule', () => {
       assert.match(readme, /refresh token persistence: disabled/);
       assert.match(readme, /create-forgeon add db-prisma/);
 
-      assert.equal(warnings.length > 0, true);
-      assert.match(warnings.join('\n'), /jwt-auth installed without persistent refresh token store/);
     } finally {
-      console.error = originalError;
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('applies logger then jwt-auth on db/i18n-disabled scaffold without breaking health controller syntax', () => {
+    const targetRoot = mkTmp('forgeon-module-jwt-nodb-noi18n-');
+    const projectRoot = path.join(targetRoot, 'demo-jwt-nodb-noi18n');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-jwt-nodb-noi18n',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      addModule({
+        moduleId: 'logger',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+      addModule({
+        moduleId: 'jwt-auth',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      const healthController = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+        'utf8',
+      );
+      assert.match(healthController, /constructor\(private readonly authService: AuthService\)/);
+      assert.match(healthController, /@Get\('auth'\)/);
+      assert.match(healthController, /return this\.authService\.getProbeStatus\(\);/);
+
+      const classStart = healthController.indexOf('export class HealthController {');
+      const classEnd = healthController.lastIndexOf('\n}');
+      const authProbe = healthController.indexOf("@Get('auth')");
+      assert.equal(classStart > -1, true);
+      assert.equal(classEnd > classStart, true);
+      assert.equal(authProbe > classStart && authProbe < classEnd, true);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('keeps health controller valid for add sequence jwt-auth -> logger -> swagger -> i18n -> db-prisma on db/i18n-disabled scaffold', () => {
+    const targetRoot = mkTmp('forgeon-module-seq-health-valid-');
+    const projectRoot = path.join(targetRoot, 'demo-seq-health-valid');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-seq-health-valid',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      for (const moduleId of ['jwt-auth', 'logger', 'swagger', 'i18n', 'db-prisma']) {
+        addModule({ moduleId, targetRoot: projectRoot, packageRoot });
+      }
+
+      const healthController = fs.readFileSync(
+        path.join(projectRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'),
+        'utf8',
+      );
+
+      const classStart = healthController.indexOf('export class HealthController {');
+      const classEnd = healthController.lastIndexOf('\n}');
+      assert.equal(classStart > -1, true);
+      assert.equal(classEnd > classStart, true);
+
+      const imports = [...healthController.matchAll(/^import\s.+;$/gm)];
+      assert.equal(imports.length > 0, true);
+      for (const importLine of imports) {
+        assert.equal(importLine.index < classStart, true);
+      }
+
+      const authProbe = healthController.indexOf("@Get('auth')");
+      const dbProbe = healthController.indexOf("@Post('db')");
+      const translateMethod = healthController.indexOf('private translate(');
+      assert.equal(authProbe > classStart && authProbe < classEnd, true);
+      assert.equal(dbProbe > classStart && dbProbe < classEnd, true);
+      assert.equal(translateMethod > classStart && translateMethod < classEnd, true);
+
+      assert.match(healthController, /private readonly authService: AuthService/);
+      assert.match(healthController, /private readonly i18n: I18nService/);
+      assert.match(healthController, /private readonly prisma: PrismaService/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('applies swagger then jwt-auth without forcing swagger dependency in auth-api', () => {
+    const targetRoot = mkTmp('forgeon-module-jwt-swagger-');
+    const projectRoot = path.join(targetRoot, 'demo-jwt-swagger');
+    const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+    try {
+      scaffoldProject({
+        templateRoot,
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-jwt-swagger',
+        frontend: 'react',
+        db: 'prisma',
+        dbPrismaEnabled: false,
+        i18nEnabled: false,
+        proxy: 'caddy',
+      });
+
+      addModule({
+        moduleId: 'swagger',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+      addModule({
+        moduleId: 'jwt-auth',
+        targetRoot: projectRoot,
+        packageRoot,
+      });
+
+      const authApiPackage = JSON.parse(
+        fs.readFileSync(path.join(projectRoot, 'packages', 'auth-api', 'package.json'), 'utf8'),
+      );
+      assert.equal(Object.hasOwn(authApiPackage.dependencies ?? {}, '@nestjs/swagger'), false);
+    } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
   });