create-forgeon 0.2.2 → 0.2.3

package/src/modules/sync-integrations.mjs

@@ -0,0 +1,269 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive } from '../utils/fs.mjs';
+
+const PRISMA_AUTH_STORE_TEMPLATE = path.join(
+  'templates',
+  'module-presets',
+  'jwt-auth',
+  'apps',
+  'api',
+  'src',
+  'auth',
+  'prisma-auth-refresh-token.store.ts',
+);
+
+const PRISMA_AUTH_MIGRATION_TEMPLATE = path.join(
+  'templates',
+  'module-presets',
+  'jwt-auth',
+  'apps',
+  'api',
+  'prisma',
+  'migrations',
+  '0002_auth_refresh_token_hash',
+);
+
+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 isAuthPersistencePending(rootDir) {
+  const appModulePath = path.join(rootDir, 'apps', 'api', 'src', 'app.module.ts');
+  const schemaPath = path.join(rootDir, 'apps', 'api', 'prisma', 'schema.prisma');
+  const storePath = path.join(rootDir, 'apps', 'api', 'src', 'auth', 'prisma-auth-refresh-token.store.ts');
+  const migrationPath = path.join(
+    rootDir,
+    'apps',
+    'api',
+    'prisma',
+    'migrations',
+    '0002_auth_refresh_token_hash',
+    'migration.sql',
+  );
+
+  if (!fs.existsSync(appModulePath) || !fs.existsSync(schemaPath)) {
+    return false;
+  }
+
+  const appModule = fs.readFileSync(appModulePath, 'utf8');
+  const schema = fs.readFileSync(schemaPath, 'utf8');
+
+  const hasModuleWiring =
+    appModule.includes('refreshTokenStoreProvider') &&
+    appModule.includes('PrismaAuthRefreshTokenStore') &&
+    appModule.includes('AUTH_REFRESH_TOKEN_STORE');
+  const hasSchema = schema.includes('refreshTokenHash');
+  const hasStoreFile = fs.existsSync(storePath);
+  const hasMigration = fs.existsSync(migrationPath);
+
+  return !(hasModuleWiring && hasSchema && hasStoreFile && hasMigration);
+}
+
+const INTEGRATION_GROUPS = [
+  {
+    id: 'auth-persistence',
+    title: 'Auth Persistence Integration',
+    modules: ['jwt-auth', 'db-prisma', 'core-config'],
+    description: [
+      'Register Prisma refresh-token store in AuthModule',
+      'Wire AUTH_REFRESH_TOKEN_STORE provider to Prisma store',
+      'Extend Prisma User model with refreshTokenHash',
+      'Add auth persistence migration and update README note',
+    ],
+    isAvailable: (detected) => detected.jwtAuth && detected.dbPrisma,
+    isPending: (rootDir) => isAuthPersistencePending(rootDir),
+    apply: syncJwtDbPrisma,
+  },
+];
+
+function detectModules(rootDir) {
+  const appModulePath = path.join(rootDir, 'apps', 'api', 'src', 'app.module.ts');
+  const appModuleText = fs.existsSync(appModulePath) ? fs.readFileSync(appModulePath, 'utf8') : '';
+
+  return {
+    jwtAuth:
+      fs.existsSync(path.join(rootDir, 'packages', 'auth-api', 'package.json')) ||
+      appModuleText.includes("from '@forgeon/auth-api'"),
+    dbPrisma:
+      fs.existsSync(path.join(rootDir, 'packages', 'db-prisma', 'package.json')) ||
+      appModuleText.includes("from '@forgeon/db-prisma'"),
+  };
+}
+
+function syncJwtDbPrisma({ rootDir, packageRoot, changedFiles }) {
+  const appModulePath = path.join(rootDir, 'apps', 'api', 'src', 'app.module.ts');
+  const schemaPath = path.join(rootDir, 'apps', 'api', 'prisma', 'schema.prisma');
+  const readmePath = path.join(rootDir, 'README.md');
+  const storePath = path.join(rootDir, 'apps', 'api', 'src', 'auth', 'prisma-auth-refresh-token.store.ts');
+  const migrationPath = path.join(
+    rootDir,
+    'apps',
+    'api',
+    'prisma',
+    'migrations',
+    '0002_auth_refresh_token_hash',
+    'migration.sql',
+  );
+
+  if (!fs.existsSync(appModulePath) || !fs.existsSync(schemaPath)) {
+    return { applied: false, reason: 'app module or prisma schema is missing' };
+  }
+
+  let touched = false;
+
+  if (!fs.existsSync(storePath)) {
+    const storeSource = path.join(packageRoot, PRISMA_AUTH_STORE_TEMPLATE);
+    if (!fs.existsSync(storeSource)) {
+      return { applied: false, reason: 'jwt-auth prisma store template is missing' };
+    }
+    fs.mkdirSync(path.dirname(storePath), { recursive: true });
+    copyRecursive(storeSource, storePath);
+    changedFiles.add(storePath);
+    touched = true;
+  }
+
+  let appModule = fs.readFileSync(appModulePath, 'utf8').replace(/\r\n/g, '\n');
+  const originalAppModule = appModule;
+
+  if (!appModule.includes("AUTH_REFRESH_TOKEN_STORE, authConfig")) {
+    appModule = appModule.replace(
+      /import\s*\{\s*authConfig,\s*authEnvSchema,\s*ForgeonAuthModule\s*\}\s*from '@forgeon\/auth-api';/m,
+      "import { AUTH_REFRESH_TOKEN_STORE, authConfig, authEnvSchema, ForgeonAuthModule } from '@forgeon/auth-api';",
+    );
+  }
+
+  const storeImportLine = "import { PrismaAuthRefreshTokenStore } from './auth/prisma-auth-refresh-token.store';";
+  if (!appModule.includes(storeImportLine)) {
+    appModule = ensureLineAfter(
+      appModule,
+      "import { HealthController } from './health/health.controller';",
+      storeImportLine,
+    );
+  }
+
+  if (!appModule.includes('refreshTokenStoreProvider')) {
+    appModule = appModule.replace(
+      /ForgeonAuthModule\.register\(\),/m,
+      `ForgeonAuthModule.register({
+      imports: [DbPrismaModule],
+      refreshTokenStoreProvider: {
+        provide: AUTH_REFRESH_TOKEN_STORE,
+        useClass: PrismaAuthRefreshTokenStore,
+      },
+    }),`,
+    );
+  }
+
+  if (appModule !== originalAppModule) {
+    fs.writeFileSync(appModulePath, `${appModule.trimEnd()}\n`, 'utf8');
+    changedFiles.add(appModulePath);
+    touched = true;
+  }
+
+  let schema = fs.readFileSync(schemaPath, 'utf8').replace(/\r\n/g, '\n');
+  const originalSchema = schema;
+  if (!schema.includes('refreshTokenHash')) {
+    schema = schema.replace(/email\s+String\s+@unique/g, 'email            String   @unique\n  refreshTokenHash String?');
+  }
+  if (schema !== originalSchema) {
+    fs.writeFileSync(schemaPath, `${schema.trimEnd()}\n`, 'utf8');
+    changedFiles.add(schemaPath);
+    touched = true;
+  }
+
+  if (!fs.existsSync(migrationPath)) {
+    const migrationSource = path.join(packageRoot, PRISMA_AUTH_MIGRATION_TEMPLATE);
+    if (!fs.existsSync(migrationSource)) {
+      return { applied: false, reason: 'jwt-auth migration template is missing' };
+    }
+    const migrationDir = path.dirname(migrationPath);
+    fs.mkdirSync(path.dirname(migrationDir), { recursive: true });
+    copyRecursive(migrationSource, migrationDir);
+    changedFiles.add(migrationPath);
+    touched = true;
+  }
+
+  if (fs.existsSync(readmePath)) {
+    let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
+    const originalReadme = readme;
+    readme = readme.replace(
+      '- refresh token persistence: disabled by default (stateless mode)',
+      '- refresh token persistence: enabled (`db-prisma` adapter)',
+    );
+    readme = readme.replace(
+      /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to auto-wire pair integrations\./m,
+      '- migration: `apps/api/prisma/migrations/0002_auth_refresh_token_hash`',
+    );
+    if (readme !== originalReadme) {
+      fs.writeFileSync(readmePath, `${readme.trimEnd()}\n`, 'utf8');
+      changedFiles.add(readmePath);
+      touched = true;
+    }
+  }
+
+  if (!touched) {
+    return { applied: false, reason: 'already synced' };
+  }
+  return { applied: true };
+}
+
+export function syncIntegrations({ targetRoot, packageRoot, groupIds = null }) {
+  const rootDir = path.resolve(targetRoot);
+  const changedFiles = new Set();
+  const detected = detectModules(rootDir);
+  const summary = [];
+  const available = INTEGRATION_GROUPS.filter(
+    (group) => group.isAvailable(detected) && group.isPending(rootDir),
+  );
+  const selected = Array.isArray(groupIds)
+    ? available.filter((group) => groupIds.includes(group.id))
+    : available;
+
+  for (const group of selected) {
+    summary.push({
+      id: group.id,
+      title: group.title,
+      modules: group.modules,
+      result: group.apply({ rootDir, packageRoot, changedFiles }),
+    });
+  }
+
+  return {
+    summary,
+    availableGroups: available.map((group) => ({
+      id: group.id,
+      title: group.title,
+      modules: [...group.modules],
+      description: [...group.description],
+    })),
+    changedFiles: [...changedFiles].sort().map((filePath) => path.relative(rootDir, filePath)),
+  };
+}
+
+export function scanIntegrations({ targetRoot, relatedModuleId = null }) {
+  const rootDir = path.resolve(targetRoot);
+  const detected = detectModules(rootDir);
+  const available = INTEGRATION_GROUPS.filter(
+    (group) =>
+      group.isAvailable(detected) &&
+      group.isPending(rootDir) &&
+      (!relatedModuleId || group.modules.includes(relatedModuleId)),
+  );
+  return {
+    groups: available.map((group) => ({
+      id: group.id,
+      title: group.title,
+      modules: [...group.modules],
+      description: [...group.description],
+    })),
+  };
+}

package/src/run-add-module.mjs

@@ -1,11 +1,11 @@
 import path from 'node:path';
 import fs from 'node:fs';
-import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { printAddHelp } from './cli/add-help.mjs';
 import { parseAddCliArgs } from './cli/add-options.mjs';
 import { addModule } from './modules/executor.mjs';
 import { listModulePresets } from './modules/registry.mjs';
+import { printModuleAdded, runIntegrationFlow } from './integrations/flow.mjs';
 import { writeJson } from './utils/fs.mjs';
 
 function printModuleList() {
@@ -41,47 +41,12 @@ function ensureSyncTooling({ packageRoot, targetRoot }) {
   if (!packageJson.scripts) {
     packageJson.scripts = {};
   }
-  if (!packageJson.devDependencies) {
-    packageJson.devDependencies = {};
-  }
 
   packageJson.scripts['forgeon:sync-integrations'] = 'node scripts/forgeon-sync-integrations.mjs';
-  if (!packageJson.devDependencies['ts-morph']) {
-    packageJson.devDependencies['ts-morph'] = '^24.0.0';
-  }
 
   writeJson(packagePath, packageJson);
 }
 
-function runIntegrationSync(targetRoot) {
-  const scriptPath = path.join(targetRoot, 'scripts', 'forgeon-sync-integrations.mjs');
-  if (!fs.existsSync(scriptPath)) {
-    return;
-  }
-
-  const tsMorphPackagePath = path.join(targetRoot, 'node_modules', 'ts-morph', 'package.json');
-  if (!fs.existsSync(tsMorphPackagePath)) {
-    console.warn(
-      '[create-forgeon add] sync-integrations skipped (dependencies are not installed yet). ' +
-        'Run `pnpm install` then `pnpm forgeon:sync-integrations` inside the project.',
-    );
-    return;
-  }
-
-  const result = spawnSync(process.execPath, [scriptPath], {
-    cwd: targetRoot,
-    stdio: 'inherit',
-    env: process.env,
-  });
-
-  if (result.status !== 0) {
-    console.warn(
-      '[create-forgeon add] sync-integrations failed. ' +
-        'Run `pnpm install` then `pnpm forgeon:sync-integrations` inside the project.',
-    );
-  }
-}
-
 export async function runAddModule(argv = process.argv.slice(2)) {
   const options = parseAddCliArgs(argv);
 
@@ -109,9 +74,10 @@ export async function runAddModule(argv = process.argv.slice(2)) {
     packageRoot,
   });
   ensureSyncTooling({ packageRoot, targetRoot });
-  runIntegrationSync(targetRoot);
-
-  console.log(result.message);
-  console.log(`- module: ${result.preset.id}`);
-  console.log(`- docs: ${result.docsPath}`);
-}
+  printModuleAdded(result.preset.id, result.docsPath);
+  await runIntegrationFlow({
+    targetRoot,
+    packageRoot,
+    relatedModuleId: result.preset.id,
+  });
+}

package/src/run-scan-integrations.mjs

@@ -0,0 +1,93 @@
+import path from 'node:path';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { runIntegrationFlow } from './integrations/flow.mjs';
+import { writeJson } from './utils/fs.mjs';
+
+function parseScanArgs(argv) {
+  const options = {
+    project: '.',
+    help: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === '--') continue;
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+    if (arg.startsWith('--project=')) {
+      options.project = arg.split('=')[1] || '.';
+      continue;
+    }
+    if (arg === '--project') {
+      if (argv[i + 1] && !argv[i + 1].startsWith('-')) {
+        options.project = argv[i + 1];
+        i += 1;
+      }
+    }
+  }
+
+  return options;
+}
+
+function printScanHelp() {
+  console.log(`create-forgeon scan-integrations
+
+Usage:
+  npx create-forgeon@latest scan-integrations [options]
+
+Options:
+  --project <path>   Target project path (default: current directory)
+  -h, --help         Show this help
+`);
+}
+
+function ensureSyncTooling({ packageRoot, targetRoot }) {
+  const sourceScript = path.join(
+    packageRoot,
+    'templates',
+    'base',
+    'scripts',
+    'forgeon-sync-integrations.mjs',
+  );
+  const targetScript = path.join(targetRoot, 'scripts', 'forgeon-sync-integrations.mjs');
+
+  if (fs.existsSync(sourceScript) && !fs.existsSync(targetScript)) {
+    fs.mkdirSync(path.dirname(targetScript), { recursive: true });
+    fs.copyFileSync(sourceScript, targetScript);
+  }
+
+  const packagePath = path.join(targetRoot, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return;
+  }
+
+  const packageJson = JSON.parse(fs.readFileSync(packagePath, 'utf8'));
+  if (!packageJson.scripts) {
+    packageJson.scripts = {};
+  }
+  packageJson.scripts['forgeon:sync-integrations'] = 'node scripts/forgeon-sync-integrations.mjs';
+  writeJson(packagePath, packageJson);
+}
+
+export async function runScanIntegrations(argv = process.argv.slice(2)) {
+  const options = parseScanArgs(argv);
+  if (options.help) {
+    printScanHelp();
+    return;
+  }
+
+  const srcDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(srcDir, '..');
+  const targetRoot = path.resolve(process.cwd(), options.project);
+
+  ensureSyncTooling({ packageRoot, targetRoot });
+  await runIntegrationFlow({
+    targetRoot,
+    packageRoot,
+    relatedModuleId: null,
+    scanMessage: 'Scanning for pending integrations...',
+  });
+}

package/templates/base/docs/AI/ARCHITECTURE.md

@@ -46,6 +46,23 @@ Reusable features should be added as fullstack add-modules:
 
 Reference: `docs/AI/MODULE_SPEC.md`.
 
+## Integration Sync Strategy
+
+- Integration orchestration is a default project toolchain command:
+  - `pnpm forgeon:sync-integrations`
+- Purpose:
+  - keep add-modules composable when installed in arbitrary order;
+  - apply module-to-module integration patches idempotently.
+- Rule:
+  - each add-module patches only itself;
+  - cross-module changes are allowed only in integration sync rules.
+- Current integration:
+  - `jwt-auth + db-prisma` (persistent refresh-token store wiring + schema/migration sync).
+- Pair sync is explicit (opt-in), not automatic after `add`.
+- Run `pnpm forgeon:sync-integrations` when you want to apply module-pair integrations.
+- Swagger auth decorators are intentionally not auto-patched.
+- Future option: this may return as an explicit optional command (not default automatic behavior).
+
 ## TypeScript Module Format Policy
 
 - `apps/api`, `packages/core`, and backend runtime packages use Node-oriented config:

package/templates/base/docs/AI/MODULE_SPEC.md

@@ -66,3 +66,7 @@ Must contain:
 - If module behavior can be runtime-checked, it also includes API+Web probe hooks (see `docs/AI/MODULE_CHECKS.md`).
 - If i18n is enabled, module-specific namespaces must be created and wired for both API and web.
 - If module is added before i18n, namespace templates must still be prepared and applied when i18n is installed later.
+- Module integration with other modules must be represented as idempotent sync rules and runnable via `pnpm forgeon:sync-integrations`.
+- `create-forgeon add <module-id>` does not auto-apply pair integrations.
+- Pair integrations are applied explicitly via `pnpm forgeon:sync-integrations`.
+- Modules must not assume `db-prisma` is present unless they explicitly require it; DB integrations should be optional and synced when DB is added later.

package/templates/base/package.json

@@ -11,9 +11,6 @@
     "docker:up": "docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build",
     "docker:down": "docker compose -f infra/docker/compose.yml down -v"
   },
-  "devDependencies": {
-    "ts-morph": "^24.0.0"
-  },
   "pnpm": {
     "onlyBuiltDependencies": [
       "@nestjs/core",