create-forgeon 0.1.25 → 0.1.26

package/package.json

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

package/src/presets/i18n.mjs

@@ -142,29 +142,70 @@ export class AppModule {}
     'health',
     'health.controller.ts',
   );
-  fs.writeFileSync(
-    healthControllerPath,
-    `import { Controller, Get, Query } from '@nestjs/common';
-import { EchoQueryDto } from '../common/dto/echo-query.dto';
-
-@Controller('health')
-export class HealthController {
-  @Get()
-  getHealth(@Query('lang') _lang?: string) {
-    return {
-      status: 'ok',
-      message: 'OK',
-    };
-  }
-
-  @Get('echo')
-  getEcho(@Query() query: EchoQueryDto) {
-    return { value: query.value };
-  }
-}
-`,
-    'utf8',
-  );
+  fs.writeFileSync(
+    healthControllerPath,
+    `import { ConflictException, Controller, Get, Post, Query } from '@nestjs/common';
+import { PrismaService } from '@forgeon/db-prisma';
+import { EchoQueryDto } from '../common/dto/echo-query.dto';
+
+@Controller('health')
+export class HealthController {
+  constructor(private readonly prisma: PrismaService) {}
+
+  @Get()
+  getHealth(@Query('lang') lang?: string) {
+    const locale = this.resolveLocale(lang);
+    return {
+      status: 'ok',
+      message: 'OK',
+      i18n: locale === 'uk' ? 'Ukrainian' : 'English',
+    };
+  }
+
+  @Get('error')
+  getErrorProbe() {
+    throw new ConflictException({
+      message: 'Email already exists',
+      details: {
+        feature: 'core-errors',
+        probe: 'health.error',
+      },
+    });
+  }
+
+  @Get('validation')
+  getValidationProbe(@Query() query: EchoQueryDto) {
+    return {
+      status: 'ok',
+      validated: true,
+      value: query.value,
+    };
+  }
+
+  @Post('db')
+  async getDbProbe() {
+    const token = \`\${Date.now()}-\${Math.floor(Math.random() * 1_000_000)}\`;
+    const email = \`health-probe-\${token}@example.local\`;
+    const user = await this.prisma.user.create({
+      data: { email },
+      select: { id: true, email: true, createdAt: true },
+    });
+
+    return {
+      status: 'ok',
+      feature: 'db-prisma',
+      user,
+    };
+  }
+
+  private resolveLocale(lang?: string): 'en' | 'uk' {
+    const normalized = (lang ?? '').toLowerCase();
+    return normalized.startsWith('uk') ? 'uk' : 'en';
+  }
+}
+`,
+    'utf8',
+  );
 
   removeIfExists(
     path.join(targetRoot, 'apps', 'api', 'src', 'common', 'filters', 'app-exception.filter.ts'),

package/templates/base/apps/api/src/health/health.controller.ts

@@ -1,10 +1,14 @@
-import { Controller, Get, Optional, Query } from '@nestjs/common';
+import { ConflictException, Controller, Get, Optional, Post, Query } from '@nestjs/common';
+import { PrismaService } from '@forgeon/db-prisma';
 import { I18nService } from 'nestjs-i18n';
 import { EchoQueryDto } from '../common/dto/echo-query.dto';
 
 @Controller('health')
 export class HealthController {
-  constructor(@Optional() private readonly i18n?: I18nService) {}
+  constructor(
+    private readonly prisma: PrismaService,
+    @Optional() private readonly i18n?: I18nService,
+  ) {}
 
   @Get()
   getHealth(@Query('lang') lang?: string) {
@@ -16,16 +20,45 @@ export class HealthController {
     };
   }
 
-  @Get('echo')
-  getEcho(@Query() query: EchoQueryDto) {
-    return { value: query.value };
+  @Get('error')
+  getErrorProbe() {
+    throw new ConflictException({
+      message: 'Email already exists',
+      details: {
+        feature: 'core-errors',
+        probe: 'health.error',
+      },
+    });
   }
 
-  private translate(key: string, lang?: string): string {
+  @Get('validation')
+  getValidationProbe(@Query() query: EchoQueryDto) {
+    return {
+      status: 'ok',
+      validated: true,
+      value: query.value,
+    };
+  }
+
+  @Post('db')
+  async getDbProbe() {
+    const token = `${Date.now()}-${Math.floor(Math.random() * 1_000_000)}`;
+    const email = `health-probe-${token}@example.local`;
+    const user = await this.prisma.user.create({
+      data: { email },
+      select: { id: true, email: true, createdAt: true },
+    });
+
+    return {
+      status: 'ok',
+      feature: 'db-prisma',
+      user,
+    };
+  }
+
+  private translate(key: string, lang?: string): string {
     if (!this.i18n) {
       if (key === 'common.ok') return 'OK';
-      if (key === 'common.checkApiHealth') return 'Check API health';
-      if (key === 'common.language') return 'Language';
       if (key === 'common.languages.english') return 'English';
       if (key === 'common.languages.ukrainian') return 'Ukrainian';
       return key;

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

@@ -1,37 +1,78 @@
-import { useState } from 'react';
-import './styles.css';
+import { useState } from 'react';
+import './styles.css';
+
+type ProbeResult = {
+  statusCode: number;
+  body: unknown;
+};
+
+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 [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);
+  const [networkError, setNetworkError] = useState<string | null>(null);
+
+  const requestProbe = async (url: string, init?: RequestInit): Promise<ProbeResult> => {
+    const response = await fetch(url, init);
+    let body: unknown = null;
+
+    try {
+      body = await response.json();
+    } catch {
+      body = { message: 'Non-JSON response' };
+    }
+
+    return {
+      statusCode: response.status,
+      body,
+    };
+  };
+
+  const runProbe = async (
+    setter: (value: ProbeResult | null) => void,
+    url: string,
+    init?: RequestInit,
+  ) => {
+    setNetworkError(null);
+    try {
+      const result = await requestProbe(url, init);
+      setter(result);
+    } catch (err) {
+      setNetworkError(err instanceof Error ? err.message : 'Unknown error');
+    }
+  };
+
+  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>
+        <button onClick={() => runProbe(setDbProbeResult, '/api/health/db', { method: 'POST' })}>
+          Check database (create user)
+        </button>
+      </div>
+      {renderResult('Health response', healthResult)}
+      {renderResult('Error probe response', errorProbeResult)}
+      {renderResult('Validation probe response', validationProbeResult)}
+      {renderResult('DB probe response', dbProbeResult)}
+      {networkError ? <p className="error">{networkError}</p> : null}
+    </main>
+  );
+}
 
-type HealthResponse = {
-  status: string;
-  message: string;
-};
-
-export default function App() {
-  const [data, setData] = useState<HealthResponse | null>(null);
-  const [error, setError] = useState<string | null>(null);
-
-  const checkApi = async () => {
-    setError(null);
-    try {
-      const response = await fetch('/api/health');
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`);
-      }
-      const payload = (await response.json()) as HealthResponse;
-      setData(payload);
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Unknown error');
-    }
-  };
-
-  return (
-    <main className="page">
-      <h1>Forgeon Fullstack Scaffold</h1>
-      <p>Default frontend preset: React + Vite + TypeScript.</p>
-      <button onClick={checkApi}>Check API health</button>
-      {data ? <pre>{JSON.stringify(data, null, 2)}</pre> : null}
-      {error ? <p className="error">{error}</p> : null}
-    </main>
-  );
-}
 

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

@@ -8,23 +8,35 @@ body {
   color: #0f172a;
 }
 
-.page {
-  max-width: 720px;
-  margin: 3rem auto;
-  padding: 0 1rem;
-}
-
-button {
-  padding: 0.6rem 1rem;
-  border: 0;
-  border-radius: 0.5rem;
-  cursor: pointer;
-}
-
-pre {
-  background: #e2e8f0;
-  padding: 1rem;
-  border-radius: 0.5rem;
+.page {
+  max-width: 720px;
+  margin: 3rem auto;
+  padding: 0 1rem;
+}
+
+.actions {
+  display: grid;
+  grid-template-columns: repeat(auto-fit, minmax(220px, 1fr));
+  gap: 0.6rem;
+  margin: 1rem 0 1.25rem;
+}
+
+button {
+  padding: 0.6rem 1rem;
+  border: 0;
+  border-radius: 0.5rem;
+  cursor: pointer;
+}
+
+h3 {
+  margin: 1rem 0 0.5rem;
+  font-size: 1rem;
+}
+
+pre {
+  background: #e2e8f0;
+  padding: 1rem;
+  border-radius: 0.5rem;
   overflow: auto;
 }
 

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

@@ -0,0 +1,25 @@
+# MODULE CHECKS
+
+## Purpose
+
+Define mandatory runtime verification hooks for Forgeon modules.
+
+If a module can be validated through a safe API call, it must provide:
+
+1. A probe endpoint in API (`/api/health/*`).
+2. A probe trigger on default web page (`apps/web/src/App.tsx`).
+3. A visible result block in UI with HTTP status and JSON body.
+
+## Current Baseline Probes
+
+- `core-errors`: `GET /api/health/error` (returns error envelope, expected `409`)
+- `core-validation`: `GET /api/health/validation` without `value` (expected `400`)
+- `db-prisma`: `POST /api/health/db` (creates probe user and returns it, expected `201`)
+
+## Rules For Future Modules
+
+- Probe path should be explicit and feature-scoped (`/api/health/<feature>`).
+- Probe must be deterministic and documented (expected status + payload shape).
+- If probe writes data, it must use clearly marked probe/test records.
+- Probe should not require hidden setup beyond documented env/dependencies.
+- `create-forgeon add <module>` must wire both API probe and web probe UI when feasible.

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

@@ -63,3 +63,4 @@ Must contain:
 - Contracts package can be imported from both sides without circular dependencies.
 - Contracts package exports are stable from `dist/index` entrypoint.
 - Module has docs under `docs/AI/MODULES/<module-id>.md`.
+- If module behavior can be runtime-checked, it also includes API+Web probe hooks (see `docs/AI/MODULE_CHECKS.md`).

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

@@ -48,11 +48,12 @@ Create or update create-forgeon preset flow:
 ## Add Fullstack Module
 
 ```text
-Implement `create-forgeon add <module-id>` for a fullstack feature.
-Requirements:
-- split module into contracts/api/web packages
-- contracts is source of truth for routes, DTOs, errors
-- add docs note under docs/AI/MODULES/<module-id>.md
-- keep backward compatibility
-```
+Implement `create-forgeon add <module-id>` for a fullstack feature.
+Requirements:
+- split module into contracts/api/web packages
+- contracts is source of truth for routes, DTOs, errors
+- if feasible, add module probe hooks in API (`/api/health/*`) and web diagnostics UI
+- add docs note under docs/AI/MODULES/<module-id>.md
+- keep backward compatibility
+```
 

package/templates/base/docs/README.md

@@ -3,5 +3,6 @@
 - `AI/PROJECT.md` - project overview and run modes
 - `AI/ARCHITECTURE.md` - monorepo design and extension model
 - `AI/MODULE_SPEC.md` - fullstack module contract (`contracts/api/web`)
+- `AI/MODULE_CHECKS.md` - required runtime probe hooks for modules
 - `AI/VALIDATION.md` - DTO/env validation standards
 - `AI/TASKS.md` - ready-to-use Codex prompts

package/templates/base/resources/i18n/en/common.json

@@ -1,6 +1,9 @@
 {
   "ok": "OK",
   "checkApiHealth": "Check API health",
+  "checkErrorEnvelope": "Check error envelope",
+  "checkValidation": "Check validation (expect 400)",
+  "checkDatabase": "Check database (create user)",
   "language": "Language",
   "languages": {
     "english": "English",

package/templates/base/resources/i18n/uk/common.json

@@ -1,6 +1,9 @@
 {
   "ok": "OK",
   "checkApiHealth": "Перевірити API health",
+  "checkErrorEnvelope": "Перевірити error envelope",
+  "checkValidation": "Перевірити валідацію (очікуємо 400)",
+  "checkDatabase": "Перевірити базу даних (створити користувача)",
   "language": "Мова",
   "languages": {
     "english": "Англійська",

package/templates/module-presets/i18n/apps/web/src/App.tsx

@@ -5,10 +5,9 @@ import * as i18nWeb from '@forgeon/i18n-web';
 import type { I18nLocale } from '@forgeon/i18n-web';
 import './styles.css';
 
-type HealthResponse = {
-  status: string;
-  message: string;
-  i18n: string;
+type ProbeResult = {
+  statusCode: number;
+  body: unknown;
 };
 
 function localeLabelKey(locale: I18nLocale): string {
@@ -19,8 +18,11 @@ export default function App() {
   const { t } = useTranslation(['common']);
   const { I18N_LOCALES, getInitialLocale, persistLocale, toLangQuery } = i18nWeb;
   const [locale, setLocale] = useState<I18nLocale>(getInitialLocale);
-  const [data, setData] = useState<HealthResponse | null>(null);
-  const [error, setError] = useState<string | null>(null);
+  const [healthResult, setHealthResult] = useState<ProbeResult | null>(null);
+  const [errorProbeResult, setErrorProbeResult] = useState<ProbeResult | null>(null);
+  const [validationProbeResult, setValidationProbeResult] = useState<ProbeResult | null>(null);
+  const [dbProbeResult, setDbProbeResult] = useState<ProbeResult | null>(null);
+  const [networkError, setNetworkError] = useState<string | null>(null);
 
   const changeLocale = (nextLocale: I18nLocale) => {
     setLocale(nextLocale);
@@ -28,24 +30,49 @@ export default function App() {
     void i18n.changeLanguage(nextLocale);
   };
 
-  const checkApi = async () => {
-    setError(null);
+  const requestProbe = async (path: string, init?: RequestInit): Promise<ProbeResult> => {
+    const response = await fetch(`/api${path}${toLangQuery(locale)}`, {
+      ...init,
+      headers: {
+        ...(init?.headers ?? {}),
+        'Accept-Language': locale,
+      },
+    });
+
+    let body: unknown = null;
+    try {
+      body = await response.json();
+    } catch {
+      body = { message: 'Non-JSON response' };
+    }
+
+    return {
+      statusCode: response.status,
+      body,
+    };
+  };
+
+  const runProbe = async (
+    setter: (value: ProbeResult | null) => void,
+    path: string,
+    init?: RequestInit,
+  ) => {
+    setNetworkError(null);
     try {
-      const response = await fetch(`/api/health${toLangQuery(locale)}`, {
-        headers: {
-          'Accept-Language': locale,
-        },
-      });
-      if (!response.ok) {
-        throw new Error(`HTTP ${response.status}`);
-      }
-      const payload = (await response.json()) as HealthResponse;
-      setData(payload);
+      const result = await requestProbe(path, init);
+      setter(result);
     } catch (err) {
-      setError(err instanceof Error ? err.message : 'Unknown error');
+      setNetworkError(err instanceof Error ? err.message : 'Unknown error');
     }
   };
 
+  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>
@@ -62,9 +89,23 @@ export default function App() {
           </option>
         ))}
       </select>
-      <button onClick={checkApi}>{t('common:checkApiHealth')}</button>
-      {data ? <pre>{JSON.stringify(data, null, 2)}</pre> : null}
-      {error ? <p className="error">{error}</p> : null}
+      <div className="actions">
+        <button onClick={() => runProbe(setHealthResult, '/health')}>{t('common:checkApiHealth')}</button>
+        <button onClick={() => runProbe(setErrorProbeResult, '/health/error')}>
+          {t('common:checkErrorEnvelope')}
+        </button>
+        <button onClick={() => runProbe(setValidationProbeResult, '/health/validation')}>
+          {t('common:checkValidation')}
+        </button>
+        <button onClick={() => runProbe(setDbProbeResult, '/health/db', { method: 'POST' })}>
+          {t('common:checkDatabase')}
+        </button>
+      </div>
+      {renderResult('Health response', healthResult)}
+      {renderResult('Error probe response', errorProbeResult)}
+      {renderResult('Validation probe response', validationProbeResult)}
+      {renderResult('DB probe response', dbProbeResult)}
+      {networkError ? <p className="error">{networkError}</p> : null}
     </main>
   );
 }