create-forgeon 0.3.14 → 0.3.16

package/src/modules/shared/probes.mjs

@@ -0,0 +1,235 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readJson } from '../../utils/fs.mjs';
+
+const ansi = {
+  reset: '\x1b[0m',
+  yellow: '\x1b[33m',
+};
+
+const MODULE_PROBES_START = '  // forgeon:module-probes:start';
+const MODULE_PROBES_END = '  // forgeon:module-probes:end';
+const probeEntryPattern = /  \/\/ forgeon:probe:([a-z0-9-]+):start\n([\s\S]*?)\n  \/\/ forgeon:probe:\1:end/g;
+
+const probeOrders = {
+  health: 10,
+  error: 20,
+  validation: 30,
+  db: 40,
+  auth: 50,
+  rbac: 60,
+  'rate-limit': 70,
+  files: 80,
+  'files-variants': 81,
+  'files-access': 82,
+  'files-quotas': 83,
+  'files-image': 84,
+  queue: 90,
+  scheduler: 100,
+};
+
+
+function colorize(text) {
+  return `${ansi.yellow}${text}${ansi.reset}`;
+}
+
+function warn(moduleId, message) {
+  console.log(colorize(`[forgeon:probes] ${moduleId}: ${message}`));
+}
+
+function normalize(content) {
+  return content.replace(/\r\n/g, '\n');
+}
+
+function hasProbeContainer(content) {
+  return /id=(['"])probes\1/.test(content);
+}
+
+function getPackageJson(targetRoot) {
+  const packagePath = path.join(targetRoot, 'package.json');
+  if (!fs.existsSync(packagePath)) {
+    return {};
+  }
+
+  return readJson(packagePath);
+}
+
+function getWebRegistryPath(targetRoot) {
+  return path.join(targetRoot, 'apps', 'web', 'src', 'probes.ts');
+}
+
+function getModuleProbeEntries(content) {
+  const entries = new Map();
+  for (const match of content.matchAll(probeEntryPattern)) {
+    const probeId = match[1];
+    const jsonBlock = match[2].trim().replace(/,\s*$/, '');
+    try {
+      entries.set(probeId, JSON.parse(jsonBlock));
+    } catch {
+      continue;
+    }
+  }
+  return entries;
+}
+
+function formatEntry(definition) {
+  const jsonBlock = JSON.stringify(definition, null, 2)
+    .split('\n')
+    .map((line) => `  ${line}`)
+    .join('\n');
+
+  return `  // forgeon:probe:${definition.id}:start\n${jsonBlock},\n  // forgeon:probe:${definition.id}:end`;
+}
+
+function replaceManagedBlock(content, entries) {
+  const sortedDefinitions = [...entries.values()].sort((left, right) => {
+    if (left.order !== right.order) {
+      return left.order - right.order;
+    }
+    return left.id.localeCompare(right.id);
+  });
+
+  const body = sortedDefinitions.map((definition) => formatEntry(definition)).join('\n\n');
+  const nextBlock = body.length > 0
+    ? `${MODULE_PROBES_START}\n${body}\n${MODULE_PROBES_END}`
+    : `${MODULE_PROBES_START}\n${MODULE_PROBES_END}`;
+
+  const blockPattern = new RegExp(
+    `${escapeRegExp(MODULE_PROBES_START)}(?:\\n[\\s\\S]*?)?\\n${escapeRegExp(MODULE_PROBES_END)}`,
+  );
+
+  if (!blockPattern.test(content)) {
+    return content;
+  }
+
+  return content.replace(blockPattern, nextBlock);
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+export function getProbeOrder(probeId) {
+  return probeOrders[probeId] ?? 999;
+}
+
+export function resolveProbeTargets({ targetRoot, moduleId }) {
+  const packageJson = getPackageJson(targetRoot);
+  const probesEnabled = packageJson.forgeon?.diagnostics?.probes?.enabled !== false;
+  if (!probesEnabled) {
+    warn(moduleId, 'probe wiring skipped because forgeon.diagnostics.probes.enabled=false.');
+    return {
+      allowApi: false,
+      allowWeb: false,
+      reason: 'disabled-by-config',
+    };
+  }
+
+  const healthControllerPath = path.join(targetRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts');
+  if (!fs.existsSync(healthControllerPath)) {
+    warn(moduleId, 'probe wiring skipped because apps/api/src/health/health.controller.ts is missing.');
+    return {
+      allowApi: false,
+      allowWeb: false,
+      reason: 'missing-health-surface',
+    };
+  }
+
+  const webAppPath = path.join(targetRoot, 'apps', 'web', 'src', 'App.tsx');
+  if (!fs.existsSync(webAppPath)) {
+    warn(moduleId, 'web probe skipped because apps/web/src/App.tsx is missing.');
+    return {
+      allowApi: true,
+      allowWeb: false,
+      reason: 'missing-web-app',
+      healthControllerPath,
+    };
+  }
+
+  const webAppContent = normalize(fs.readFileSync(webAppPath, 'utf8'));
+  if (!hasProbeContainer(webAppContent)) {
+    warn(moduleId, 'web probe skipped because App.tsx does not expose a #probes container.');
+    return {
+      allowApi: true,
+      allowWeb: false,
+      reason: 'missing-web-probes-container',
+      healthControllerPath,
+      webAppPath,
+    };
+  }
+
+  const probesFilePath = getWebRegistryPath(targetRoot);
+  if (!fs.existsSync(probesFilePath)) {
+    warn(moduleId, 'web probe skipped because apps/web/src/probes.ts is missing.');
+    return {
+      allowApi: true,
+      allowWeb: false,
+      reason: 'missing-web-probes-registry',
+      healthControllerPath,
+      webAppPath,
+    };
+  }
+
+  const probesContent = normalize(fs.readFileSync(probesFilePath, 'utf8'));
+  if (!probesContent.includes(MODULE_PROBES_START) || !probesContent.includes(MODULE_PROBES_END)) {
+    warn(moduleId, 'web probe skipped because apps/web/src/probes.ts is missing managed module markers.');
+    return {
+      allowApi: true,
+      allowWeb: false,
+      reason: 'missing-web-probes-markers',
+      healthControllerPath,
+      webAppPath,
+      probesFilePath,
+    };
+  }
+
+  return {
+    allowApi: true,
+    allowWeb: true,
+    reason: 'ready',
+    healthControllerPath,
+    webAppPath,
+    probesFilePath,
+  };
+}
+
+export function ensureWebProbeDefinition({ targetRoot, probeTargets, definition }) {
+  if (!probeTargets?.allowWeb) {
+    return false;
+  }
+
+  const probesFilePath = probeTargets.probesFilePath ?? getWebRegistryPath(targetRoot);
+  if (!fs.existsSync(probesFilePath)) {
+    return false;
+  }
+
+  const normalizedDefinition = {
+    ...definition,
+    order: definition.order ?? getProbeOrder(definition.id),
+  };
+
+  const content = normalize(fs.readFileSync(probesFilePath, 'utf8'));
+  const entries = getModuleProbeEntries(content);
+  entries.set(normalizedDefinition.id, normalizedDefinition);
+
+  const nextContent = replaceManagedBlock(content, entries);
+  fs.writeFileSync(probesFilePath, `${nextContent.trimEnd()}\n`, 'utf8');
+  return true;
+}
+
+export function readManagedWebProbeDefinitions(targetRoot) {
+  const probesFilePath = getWebRegistryPath(targetRoot);
+  if (!fs.existsSync(probesFilePath)) {
+    return [];
+  }
+
+  const content = normalize(fs.readFileSync(probesFilePath, 'utf8'));
+  return [...getModuleProbeEntries(content).values()].sort((left, right) => {
+    if (left.order !== right.order) {
+      return left.order - right.order;
+    }
+    return left.id.localeCompare(right.id);
+  });
+}
+
+

package/src/modules/sync-integrations.mjs

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { copyRecursive } from '../utils/fs.mjs';
+import { copyRecursive } from '../utils/fs.mjs';
+import { ensureLineAfter } from './shared/patch-utils.mjs';
 
 const PRISMA_AUTH_STORE_TEMPLATE = path.join(
   'templates',
@@ -43,18 +44,34 @@ const AUTH_PERSISTENCE_STRATEGIES = [
   },
 ];
 
-function ensureLineAfter(content, anchorLine, lineToInsert) {
-  if (content.includes(lineToInsert)) {
+const JWT_AUTH_PERSISTENCE_MARKERS = {
+  start: '<!-- forgeon:jwt-auth:persistence:start -->',
+  end: '<!-- forgeon:jwt-auth:persistence:end -->',
+};
+
+const JWT_AUTH_RBAC_MARKERS = {
+  start: '<!-- forgeon:jwt-auth:rbac:start -->',
+  end: '<!-- forgeon:jwt-auth:rbac:end -->',
+};
+
+const JWT_AUTH_DB_PRISMA_PERSISTENCE_BLOCK = [
+  '- refresh token persistence: enabled through the `db-adapter` capability (current provider: `db-prisma`)',
+  '- migration: `apps/api/prisma/migrations/0002_auth_refresh_token_hash`',
+].join('\n');
+
+const JWT_AUTH_RBAC_ENABLED_BLOCK = '- RBAC integration: demo auth tokens include `health.rbac` permission';
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+function replaceReadmeManagedBlock(content, startMarker, endMarker, nextBody) {
+  const pattern = new RegExp(`${escapeRegExp(startMarker)}\\n[\\s\\S]*?\\n${escapeRegExp(endMarker)}`);
+  if (!pattern.test(content)) {
     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)}`;
+  return content.replace(pattern, `${startMarker}\n${nextBody}\n${endMarker}`);
 }
-
 function isAuthPersistencePending(rootDir) {
   const appModulePath = path.join(rootDir, 'apps', 'api', 'src', 'app.module.ts');
   const schemaPath = path.join(rootDir, 'apps', 'api', 'prisma', 'schema.prisma');
@@ -318,14 +335,24 @@ function syncJwtDbPrisma({ rootDir, packageRoot, changedFiles }) {
   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; enable it later through a `db-adapter` provider + integration sync)',
-      '- refresh token persistence: enabled through the `db-adapter` capability (current provider: `db-prisma`)',
-    );
-    readme = readme.replace(
-      /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to wire auth persistence to the active DB adapter implementation\./m,
-      '- migration: `apps/api/prisma/migrations/0002_auth_refresh_token_hash`',
+    const managedReadme = replaceReadmeManagedBlock(
+      readme,
+      JWT_AUTH_PERSISTENCE_MARKERS.start,
+      JWT_AUTH_PERSISTENCE_MARKERS.end,
+      JWT_AUTH_DB_PRISMA_PERSISTENCE_BLOCK,
     );
+    if (managedReadme !== readme) {
+      readme = managedReadme;
+    } else {
+      readme = readme.replace(
+        '- refresh token persistence: disabled by default (stateless mode; enable it later through a `db-adapter` provider + integration sync)',
+        '- refresh token persistence: enabled through the `db-adapter` capability (current provider: `db-prisma`)',
+      );
+      readme = readme.replace(
+        /- to enable persistence later:[\s\S]*?2\. run `pnpm forgeon:sync-integrations` to wire auth persistence to the active DB adapter implementation\./m,
+        '- migration: `apps/api/prisma/migrations/0002_auth_refresh_token_hash`',
+      );
+    }
     if (readme !== originalReadme) {
       fs.writeFileSync(readmePath, `${readme.trimEnd()}\n`, 'utf8');
       changedFiles.add(readmePath);
@@ -418,14 +445,20 @@ function syncJwtRbacClaims({ rootDir, changedFiles }) {
   if (fs.existsSync(readmePath)) {
     let readme = fs.readFileSync(readmePath, 'utf8').replace(/\r\n/g, '\n');
     const originalReadme = readme;
-    if (!readme.includes('- RBAC integration: demo auth tokens include `health.rbac` permission')) {
+    const managedReadme = replaceReadmeManagedBlock(
+      readme,
+      JWT_AUTH_RBAC_MARKERS.start,
+      JWT_AUTH_RBAC_MARKERS.end,
+      JWT_AUTH_RBAC_ENABLED_BLOCK,
+    );
+    if (managedReadme !== readme) {
+      readme = managedReadme;
+    } else if (!readme.includes('- RBAC integration: demo auth tokens include `health.rbac` permission')) {
       const marker = 'Default demo credentials:';
       if (readme.includes(marker)) {
         readme = readme.replace(
           marker,
-          `- RBAC integration: demo auth tokens include \`health.rbac\` permission
-
-Default demo credentials:`,
+          '- RBAC integration: demo auth tokens include `health.rbac` permission\n\nDefault demo credentials:',
         );
       }
     }

package/src/modules/sync-integrations.test.mjs

@@ -0,0 +1,220 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { addModule } from './executor.mjs';
+import { scanIntegrations, syncIntegrations } from './sync-integrations.mjs';
+import { scaffoldProject } from '../core/scaffold.mjs';
+
+function makeTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function scaffoldBaseProject({ packageRoot, targetRoot, projectName, dbPrismaEnabled = false }) {
+  const templateRoot = path.join(packageRoot, 'templates', 'base');
+  scaffoldProject({
+    templateRoot,
+    packageRoot,
+    targetRoot,
+    projectName,
+    frontend: 'react',
+    db: 'prisma',
+    dbPrismaEnabled,
+    i18nEnabled: false,
+    proxy: 'caddy',
+  });
+}
+
+describe('sync integrations', () => {
+  const modulesDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(modulesDir, '..', '..');
+
+  it('does not expose auth persistence integration without a db-adapter provider', () => {
+    const tempRoot = makeTempDir('forgeon-sync-no-provider-');
+    const projectRoot = path.join(tempRoot, 'demo-sync-no-provider');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-sync-no-provider',
+      });
+
+      addModule({ moduleId: 'jwt-auth', targetRoot: projectRoot, packageRoot });
+
+      const scan = scanIntegrations({
+        targetRoot: projectRoot,
+        relatedModuleId: 'jwt-auth',
+      });
+      assert.equal(scan.groups.some((group) => group.id === 'auth-persistence'), false);
+
+      const syncResult = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-persistence'],
+      });
+      assert.deepEqual(syncResult.summary, []);
+      assert.deepEqual(syncResult.changedFiles, []);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('treats auth persistence sync as a no-op after it has already been applied', () => {
+    const tempRoot = makeTempDir('forgeon-sync-db-noop-');
+    const projectRoot = path.join(tempRoot, 'demo-sync-db-noop');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-sync-db-noop',
+        dbPrismaEnabled: true,
+      });
+
+      addModule({ moduleId: 'jwt-auth', targetRoot: projectRoot, packageRoot });
+
+      const firstSync = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-persistence'],
+      });
+      assert.equal(firstSync.summary.length, 1);
+      assert.equal(firstSync.summary[0].id, 'auth-persistence');
+      assert.equal(firstSync.summary[0].result.applied, true);
+
+      const secondScan = scanIntegrations({
+        targetRoot: projectRoot,
+        relatedModuleId: 'jwt-auth',
+      });
+      assert.equal(secondScan.groups.some((group) => group.id === 'auth-persistence'), false);
+
+      const secondSync = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-persistence'],
+      });
+      assert.deepEqual(secondSync.summary, []);
+      assert.deepEqual(secondSync.changedFiles, []);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('treats auth claims sync as a no-op after it has already been applied', () => {
+    const tempRoot = makeTempDir('forgeon-sync-rbac-noop-');
+    const projectRoot = path.join(tempRoot, 'demo-sync-rbac-noop');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-sync-rbac-noop',
+      });
+
+      addModule({ moduleId: 'rbac', targetRoot: projectRoot, packageRoot });
+      addModule({ moduleId: 'jwt-auth', targetRoot: projectRoot, packageRoot });
+
+      const firstSync = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-rbac-claims'],
+      });
+      assert.equal(firstSync.summary.length, 1);
+      assert.equal(firstSync.summary[0].id, 'auth-rbac-claims');
+      assert.equal(firstSync.summary[0].result.applied, true);
+
+      const secondScan = scanIntegrations({
+        targetRoot: projectRoot,
+        relatedModuleId: 'jwt-auth',
+      });
+      assert.equal(secondScan.groups.some((group) => group.id === 'auth-rbac-claims'), false);
+
+      const secondSync = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-rbac-claims'],
+      });
+      assert.deepEqual(secondSync.summary, []);
+      assert.deepEqual(secondSync.changedFiles, []);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+  it('uses persistence markers instead of README prose when auth persistence sync runs', () => {
+    const tempRoot = makeTempDir('forgeon-sync-db-markers-');
+    const projectRoot = path.join(tempRoot, 'demo-sync-db-markers');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-sync-db-markers',
+        dbPrismaEnabled: true,
+      });
+
+      addModule({ moduleId: 'jwt-auth', targetRoot: projectRoot, packageRoot });
+
+      const readmePath = path.join(projectRoot, 'README.md');
+      const customizedReadme = fs
+        .readFileSync(readmePath, 'utf8')
+        .replace('refresh token persistence: disabled by default', 'refresh token persistence: custom local note');
+      fs.writeFileSync(readmePath, customizedReadme, 'utf8');
+
+      const syncResult = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-persistence'],
+      });
+      assert.equal(syncResult.summary.length, 1);
+      assert.equal(syncResult.summary[0].result.applied, true);
+
+      const readme = fs.readFileSync(readmePath, 'utf8');
+      assert.match(readme, /forgeon:jwt-auth:persistence:start/);
+      assert.match(readme, /refresh token persistence: enabled through the `db-adapter` capability/);
+      assert.match(readme, /0002_auth_refresh_token_hash/);
+      assert.doesNotMatch(readme, /custom local note/);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('uses RBAC markers instead of the demo credentials heading when auth claims sync runs', () => {
+    const tempRoot = makeTempDir('forgeon-sync-rbac-markers-');
+    const projectRoot = path.join(tempRoot, 'demo-sync-rbac-markers');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot: projectRoot,
+        projectName: 'demo-sync-rbac-markers',
+      });
+
+      addModule({ moduleId: 'rbac', targetRoot: projectRoot, packageRoot });
+      addModule({ moduleId: 'jwt-auth', targetRoot: projectRoot, packageRoot });
+
+      const readmePath = path.join(projectRoot, 'README.md');
+      const customizedReadme = fs
+        .readFileSync(readmePath, 'utf8')
+        .replace('Default demo credentials:', 'Demo credentials:');
+      fs.writeFileSync(readmePath, customizedReadme, 'utf8');
+
+      const syncResult = syncIntegrations({
+        targetRoot: projectRoot,
+        packageRoot,
+        groupIds: ['auth-rbac-claims'],
+      });
+      assert.equal(syncResult.summary.length, 1);
+      assert.equal(syncResult.summary[0].result.applied, true);
+
+      const readme = fs.readFileSync(readmePath, 'utf8');
+      assert.match(readme, /forgeon:jwt-auth:rbac:start/);
+      assert.match(readme, /RBAC integration: demo auth tokens include `health\.rbac` permission/);
+      assert.match(readme, /Demo credentials:/);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+});