create-forgeon 0.3.14 → 0.3.16

package/src/run-add-module.test.mjs

@@ -0,0 +1,153 @@
+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 { scaffoldProject } from './core/scaffold.mjs';
+import { runAddModule } from './run-add-module.mjs';
+
+function makeTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function readFile(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+function writeJson(filePath, value) {
+  fs.writeFileSync(filePath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+}
+
+function scaffoldBaseProject({ packageRoot, targetRoot, projectName, proxy }) {
+  const templateRoot = path.join(packageRoot, 'templates', 'base');
+  scaffoldProject({
+    templateRoot,
+    packageRoot,
+    targetRoot,
+    projectName,
+    frontend: 'react',
+    db: 'prisma',
+    dbPrismaEnabled: false,
+    i18nEnabled: false,
+    proxy,
+  });
+}
+
+function stripSyncTooling(targetRoot) {
+  const packagePath = path.join(targetRoot, 'package.json');
+  const packageJson = JSON.parse(readFile(packagePath));
+  if (packageJson.scripts) {
+    delete packageJson.scripts['forgeon:sync-integrations'];
+  }
+  writeJson(packagePath, packageJson);
+
+  fs.rmSync(path.join(targetRoot, 'scripts', 'forgeon-sync-integrations.mjs'), { force: true });
+}
+
+async function captureLogs(work) {
+  const lines = [];
+  const originalLog = console.log;
+  console.log = (...args) => {
+    lines.push(args.join(' '));
+  };
+
+  try {
+    await work(lines);
+  } finally {
+    console.log = originalLog;
+  }
+
+  return lines.join('\n');
+}
+
+describe('runAddModule', () => {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(thisDir, '..');
+
+  it('installs files stack non-interactively with provider selection and restores sync tooling', async () => {
+    const tempRoot = makeTempDir('forgeon-run-add-files-');
+    const targetRoot = path.join(tempRoot, 'demo-run-add-files');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot,
+        projectName: 'demo-run-add-files',
+        proxy: 'nginx',
+      });
+      stripSyncTooling(targetRoot);
+
+      const output = await captureLogs(async () => {
+        await runAddModule([
+          'files',
+          '--project',
+          targetRoot,
+          '--with-required',
+          '--provider',
+          'files-storage-adapter=files-local',
+        ]);
+      });
+
+      assert.equal(fs.existsSync(path.join(targetRoot, 'packages', 'db-prisma', 'package.json')), true);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'packages', 'files-local', 'package.json')), true);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'packages', 'files', 'package.json')), true);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'scripts', 'forgeon-sync-integrations.mjs')), true);
+
+      const packageJson = JSON.parse(readFile(path.join(targetRoot, 'package.json')));
+      assert.equal(packageJson.scripts['forgeon:sync-integrations'], 'node scripts/forgeon-sync-integrations.mjs');
+
+      const compose = readFile(path.join(targetRoot, 'infra', 'docker', 'compose.yml'));
+      assert.match(compose, /^\s{2}nginx:\s*$/m);
+      assert.doesNotMatch(compose, /^\s{2}caddy:\s*$/m);
+
+      const apiEnv = readFile(path.join(targetRoot, 'apps', 'api', '.env.example'));
+      assert.match(apiEnv, /DATABASE_URL=postgresql:\/\/postgres:postgres@localhost:5432\/app\?schema=public/);
+      assert.match(apiEnv, /FILES_STORAGE_DRIVER=local/);
+
+      const healthController = readFile(path.join(targetRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'));
+      assert.match(healthController, /@Post\('files'\)/);
+
+      assert.match(output, /Recommended companion modules are available:/);
+      assert.match(output, /No integration groups found\./);
+      assert.match(output, /Next: run pnpm install/);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('installs scheduler with required queue on proxy=none scaffold', async () => {
+    const tempRoot = makeTempDir('forgeon-run-add-scheduler-');
+    const targetRoot = path.join(tempRoot, 'demo-run-add-scheduler');
+
+    try {
+      scaffoldBaseProject({
+        packageRoot,
+        targetRoot,
+        projectName: 'demo-run-add-scheduler',
+        proxy: 'none',
+      });
+
+      const output = await captureLogs(async () => {
+        await runAddModule(['scheduler', '--project', targetRoot, '--with-required']);
+      });
+
+      assert.equal(fs.existsSync(path.join(targetRoot, 'packages', 'queue', 'package.json')), true);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'packages', 'scheduler', 'package.json')), true);
+
+      const compose = readFile(path.join(targetRoot, 'infra', 'docker', 'compose.yml'));
+      assert.match(compose, /^\s{2}redis:\s*$/m);
+      assert.doesNotMatch(compose, /^\s{2}caddy:\s*$/m);
+      assert.doesNotMatch(compose, /^\s{2}nginx:\s*$/m);
+
+      const healthController = readFile(path.join(targetRoot, 'apps', 'api', 'src', 'health', 'health.controller.ts'));
+      assert.match(healthController, /@Get\('queue'\)/);
+      assert.match(healthController, /@Get\('scheduler'\)/);
+
+      assert.match(output, /No integration groups found\./);
+      assert.match(output, /Next: run pnpm install/);
+    } finally {
+      fs.rmSync(tempRoot, { recursive: true, force: true });
+    }
+  });
+});

package/templates/base/README.md

@@ -1,58 +1,10 @@
-# Forgeon Fullstack Scaffold
-
-Canonical monorepo scaffold for NestJS + frontend with shared packages, built-in docs, optional i18n (enabled by default), and default DB stack Prisma + Postgres.
-
-## Quick Start (Dev)
-
-1. Install dependencies:
-   ```bash
-   pnpm install
-   ```
-2. Start local Postgres (Docker):
-   ```bash
-   docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up db -d
-   ```
-3. Run API + web in dev mode:
-   ```bash
-   pnpm dev
-   ```
-4. Open:
-   - Web: `http://localhost:5173`
-   - API health: `http://localhost:3000/api/health`
-
-## Quick Start (Docker)
-
-```bash
-docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
-```
-
-Open `http://localhost:8080`.
+# Forgeon Base Template
 
-## Integration Sync
+Internal scaffold substrate copied before presets and generated docs are applied.
 
-Use integration sync to reconcile module cross-wiring when modules are installed in any order.
+Notes for Forgeon development:
 
-```bash
-pnpm forgeon:sync-integrations
-```
-
-Current sync coverage:
-- `jwt-auth + rbac`: extends demo auth tokens with the `health.rbac` permission.
-- `jwt-auth + db-adapter` (current provider: `db-prisma`): wires persistent refresh-token storage for auth.
-
-`create-forgeon add <module>` scans for relevant integration groups and can apply them immediately.
-
-## i18n Configuration
-
-Set in env (when i18n module is installed):
-- `I18N_DEFAULT_LANG=en`
-- `I18N_FALLBACK_LANG=en`
-
-## Prisma In Docker Start
-
-API container starts with:
-1. `prisma migrate deploy`
-2. `node apps/api/dist/main.js`
-
-This keeps container startup production-like while still simple.
-
+- the final generated project `README.md` is produced from `templates/docs-fragments/README/*`
+- module notes are produced under `modules/<module-id>/README.md` from `templates/module-fragments/*`
+- this file is a temporary template placeholder and is normally overwritten during scaffold
+- generated-project commands such as `pnpm forgeon:sync-integrations` belong to scaffolded output, not to the root development repo

package/templates/base/apps/web/src/App.tsx

@@ -1,21 +1,29 @@
-import { useState } from 'react';
+import { useState } from 'react';
+import { probeDefinitions, type ProbeDefinition, type ProbeResult } from './probes';
 import './styles.css';
 
-type ProbeResult = {
-  statusCode: number;
-  body: unknown;
+type ProbeState = {
+  result: ProbeResult | null;
+  error: string | null;
+  loading: boolean;
+};
+
+const emptyProbeState: ProbeState = {
+  result: null,
+  error: null,
+  loading: false,
 };
 
 export default function App() {
-  const [healthResult, setHealthResult] = useState<ProbeResult | null>(null);
-  const [errorProbeResult, setErrorProbeResult] = useState<ProbeResult | null>(null);
-  const [validationProbeResult, setValidationProbeResult] = useState<ProbeResult | null>(null);
-  const [networkError, setNetworkError] = useState<string | null>(null);
+  const [probeState, setProbeState] = useState<Record<string, ProbeState>>({});
 
-  const requestProbe = async (url: string, init?: RequestInit): Promise<ProbeResult> => {
-    const response = await fetch(url, {
-      ...(init ?? {}),
+  const requestProbe = async (probe: ProbeDefinition): Promise<ProbeResult> => {
+    const response = await fetch(`/api${probe.path}`, {
+      ...(probe.request ?? {}),
       cache: 'no-store',
+      headers: {
+        ...(probe.request?.headers ?? {}),
+      },
     });
     let body: unknown = null;
 
@@ -31,46 +39,66 @@ export default function App() {
     };
   };
 
-  const runProbe = async (
-    setter: (value: ProbeResult | null) => void,
-    url: string,
-    init?: RequestInit,
-  ) => {
-    setNetworkError(null);
+  const runProbe = async (probe: ProbeDefinition) => {
+    setProbeState((current) => ({
+      ...current,
+      [probe.id]: {
+        ...(current[probe.id] ?? emptyProbeState),
+        error: null,
+        loading: true,
+      },
+    }));
+
     try {
-      const result = await requestProbe(url, init);
-      setter(result);
+      const result = await requestProbe(probe);
+      setProbeState((current) => ({
+        ...current,
+        [probe.id]: {
+          result,
+          error: null,
+          loading: false,
+        },
+      }));
     } catch (err) {
-      setNetworkError(err instanceof Error ? err.message : 'Unknown error');
+      setProbeState((current) => ({
+        ...current,
+        [probe.id]: {
+          result: current[probe.id]?.result ?? null,
+          error: err instanceof Error ? err.message : 'Unknown error',
+          loading: false,
+        },
+      }));
     }
   };
 
-  const renderResult = (title: string, result: ProbeResult | null) => (
-    <section>
-      <h3>{title}</h3>
-      {result ? <pre>{JSON.stringify(result, null, 2)}</pre> : null}
-    </section>
-  );
-
   return (
     <main className="page">
       <h1>Forgeon Fullstack Scaffold</h1>
       <p>Default frontend preset: React + Vite + TypeScript.</p>
-      <div className="actions">
-        <button onClick={() => runProbe(setHealthResult, '/api/health')}>Check API health</button>
-        <button onClick={() => runProbe(setErrorProbeResult, '/api/health/error')}>
-          Check error envelope
-        </button>
-        <button onClick={() => runProbe(setValidationProbeResult, '/api/health/validation')}>
-          Check validation (expect 400)
-        </button>
+      <div id="probes" className="probes">
+        {probeDefinitions.map((probe) => {
+          const current = probeState[probe.id] ?? emptyProbeState;
+
+          return (
+            <section key={probe.id} className="probe">
+              <div className="probe-header">
+                <h2>{probe.title}</h2>
+                <button type="button" onClick={() => runProbe(probe)} disabled={current.loading}>
+                  {current.loading ? 'Running...' : probe.buttonLabel}
+                </button>
+              </div>
+              <div className="probe-output">
+                <h3>{probe.resultTitle}</h3>
+                {current.error ? <p className="error">{current.error}</p> : null}
+                {current.result ? <pre>{JSON.stringify(current.result, null, 2)}</pre> : null}
+                {!current.error && !current.result ? (
+                  <p className="placeholder">No probe result yet.</p>
+                ) : null}
+              </div>
+            </section>
+          );
+        })}
       </div>
-      {renderResult('Health response', healthResult)}
-      {renderResult('Error probe response', errorProbeResult)}
-      {renderResult('Validation probe response', validationProbeResult)}
-      {networkError ? <p className="error">{networkError}</p> : null}
     </main>
   );
-}
-
-
+}

package/templates/base/apps/web/src/probes.ts

@@ -0,0 +1,61 @@
+export type ProbeResult = {
+  statusCode: number;
+  body: unknown;
+};
+
+export type ProbeRequest = {
+  method?: 'GET' | 'POST';
+  headers?: Record<string, string>;
+};
+
+export type ProbeDefinition = {
+  id: string;
+  order: number;
+  title: string;
+  buttonLabel: string;
+  resultTitle: string;
+  path: string;
+  request?: ProbeRequest;
+};
+
+const baseProbeDefinitions: ProbeDefinition[] = [
+  {
+    id: 'health',
+    order: 10,
+    title: 'API Health',
+    buttonLabel: 'Check API health',
+    resultTitle: 'Health response',
+    path: '/health',
+  },
+  {
+    id: 'error',
+    order: 20,
+    title: 'Error Envelope',
+    buttonLabel: 'Check error envelope',
+    resultTitle: 'Error probe response',
+    path: '/health/error',
+  },
+  {
+    id: 'validation',
+    order: 30,
+    title: 'Validation',
+    buttonLabel: 'Check validation (expect 400)',
+    resultTitle: 'Validation probe response',
+    path: '/health/validation',
+  },
+];
+
+const moduleProbeDefinitions: ProbeDefinition[] = [
+  // forgeon:module-probes:start
+  // forgeon:module-probes:end
+];
+
+function compareProbeOrder(left: ProbeDefinition, right: ProbeDefinition): number {
+  if (left.order !== right.order) {
+    return left.order - right.order;
+  }
+
+  return left.id.localeCompare(right.id);
+}
+
+export const probeDefinitions = [...baseProbeDefinitions, ...moduleProbeDefinitions].sort(compareProbeOrder);

package/templates/base/apps/web/src/styles.css

@@ -1,45 +1,106 @@
-:root {
-  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
-}
-
-body {
-  margin: 0;
-  background: #f8fafc;
-  color: #0f172a;
-}
-
+:root {
+  font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
+}
+
+body {
+  margin: 0;
+  background: #f8fafc;
+  color: #0f172a;
+}
+
 .page {
-  max-width: 720px;
+  max-width: 1120px;
   margin: 3rem auto;
-  padding: 0 1rem;
+  padding: 0 1rem 4rem;
+}
+
+.probes {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
+  gap: 1rem;
+  margin-top: 1.5rem;
+}
+
+.probe {
+  display: grid;
+  gap: 0.9rem;
+  padding: 1rem;
+  border: 1px solid #cbd5e1;
+  border-radius: 0.9rem;
+  background: #ffffff;
+  box-shadow: 0 14px 30px rgba(15, 23, 42, 0.06);
+}
+
+.probe-header {
+  display: grid;
+  gap: 0.75rem;
+}
+
+.probe-header h2 {
+  margin: 0;
+  font-size: 1rem;
 }
 
-.actions {
+.probe-output {
   display: grid;
-  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
-  gap: 0.6rem;
-  margin: 1rem 0 1.25rem;
+  gap: 0.5rem;
 }
 
 button {
-  padding: 0.6rem 1rem;
+  padding: 0.7rem 1rem;
   border: 0;
-  border-radius: 0.5rem;
+  border-radius: 0.65rem;
   cursor: pointer;
+  background: #0f172a;
+  color: #f8fafc;
+  font-weight: 600;
+}
+
+button:disabled {
+  opacity: 0.7;
+  cursor: progress;
 }
 
 h3 {
-  margin: 1rem 0 0.5rem;
-  font-size: 1rem;
+  margin: 0;
+  font-size: 0.95rem;
 }
 
 pre {
+  margin: 0;
   background: #e2e8f0;
   padding: 1rem;
+  border-radius: 0.65rem;
+  overflow: auto;
+}
+
+label {
+  display: inline-block;
+  margin-top: 1rem;
+  margin-right: 0.5rem;
+}
+
+select {
+  min-width: 140px;
+  padding: 0.55rem 0.7rem;
   border-radius: 0.5rem;
-  overflow: auto;
-}
-
-.error {
-  color: #b91c1c;
+  border: 1px solid #cbd5e1;
+  background: #ffffff;
+}
+
+.error {
+  margin: 0;
+  color: #b91c1c;
+}
+
+.placeholder {
+  margin: 0;
+  color: #475569;
+}
+
+@media (min-width: 640px) {
+  .probe-header {
+    grid-template-columns: 1fr auto;
+    align-items: start;
+  }
 }

package/templates/base/package.json

@@ -1,8 +1,8 @@
-{
-  "name": "forgeon",
-  "version": "0.1.0",
-  "private": true,
-  "packageManager": "pnpm@10.0.0",
+{
+  "name": "forgeon",
+  "version": "0.1.0",
+  "private": true,
+  "packageManager": "pnpm@10.0.0",
   "scripts": {
     "dev": "pnpm --parallel --filter @forgeon/api --filter @forgeon/web dev",
     "build": "pnpm -r build",
@@ -12,13 +12,19 @@
     "docker:down": "docker compose -f infra/docker/compose.yml down -v"
   },
   "pnpm": {
-    "onlyBuiltDependencies": [
-      "@nestjs/core",
-      "@prisma/client",
-      "@prisma/engines",
-      "esbuild",
-      "prisma"
-    ]
-  }
-}
-
+    "onlyBuiltDependencies": [
+      "@nestjs/core",
+      "@prisma/client",
+      "@prisma/engines",
+      "esbuild",
+      "prisma"
+    ]
+  },
+  "forgeon": {
+    "diagnostics": {
+      "probes": {
+        "enabled": true
+      }
+    }
+  }
+}

package/templates/base/scripts/forgeon-sync-integrations.mjs

@@ -83,6 +83,34 @@ function ensureLineAfter(content, anchorLine, lineToInsert) {
   return `${content.slice(0, insertAt)}\n${lineToInsert}${content.slice(insertAt)}`;
 }
 
+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;
+  }
+  return content.replace(pattern, `${startMarker}\n${nextBody}\n${endMarker}`);
+}
 function resolveAuthPersistenceStrategy(detected) {
   const matched = AUTH_PERSISTENCE_STRATEGIES.filter((strategy) => strategy.isDetected(detected));
   if (matched.length === 0) {
@@ -181,14 +209,24 @@ function syncJwtDbPrisma({ rootDir, 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);
@@ -281,14 +319,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:',
         );
       }
     }