create-forgeon 0.0.3 → 0.1.0

package/src/run-create-forgeon.mjs

@@ -0,0 +1,72 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { printHelp } from './cli/help.mjs';
+import { parseCliArgs, promptForMissingOptions } from './cli/options.mjs';
+import { DEFAULT_DB, DEFAULT_FRONTEND, DEFAULT_PROXY, FIXED_DOCKER_ENABLED } from './constants.mjs';
+import { runInstall } from './core/install.mjs';
+import { scaffoldProject } from './core/scaffold.mjs';
+import { validatePresetSupport } from './core/validate.mjs';
+import { parseBoolean } from './utils/values.mjs';
+
+export async function runCreateForgeon(argv = process.argv.slice(2)) {
+  const { options: parsedOptions, positional } = parseCliArgs(argv);
+  const options = { ...parsedOptions };
+
+  if (options.help) {
+    printHelp();
+    return;
+  }
+
+  if (!options.name && positional.length > 0) {
+    [options.name] = positional;
+  }
+
+  const promptedOptions = await promptForMissingOptions(options);
+
+  if (!promptedOptions.name || promptedOptions.name.trim().length === 0) {
+    throw new Error('Project name is required.');
+  }
+
+  const frontend = (promptedOptions.frontend ?? DEFAULT_FRONTEND).toString().toLowerCase();
+  const db = (promptedOptions.db ?? DEFAULT_DB).toString().toLowerCase();
+  const i18nEnabled = parseBoolean(promptedOptions.i18n, true);
+  const dockerEnabled = FIXED_DOCKER_ENABLED;
+  const proxy = (promptedOptions.proxy ?? DEFAULT_PROXY).toString().toLowerCase();
+  const installEnabled = parseBoolean(promptedOptions.install, false);
+
+  validatePresetSupport({ frontend, db, dockerEnabled, proxy });
+
+  const projectName = promptedOptions.name.trim();
+  const targetRoot = path.resolve(process.cwd(), projectName);
+  if (fs.existsSync(targetRoot)) {
+    throw new Error(`Target directory already exists: ${targetRoot}`);
+  }
+
+  const srcDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(srcDir, '..');
+  const templateRoot = path.join(packageRoot, 'templates', 'base');
+
+  scaffoldProject({
+    templateRoot,
+    packageRoot,
+    targetRoot,
+    projectName,
+    frontend,
+    db,
+    i18nEnabled,
+    proxy,
+  });
+
+  if (installEnabled) {
+    runInstall(targetRoot);
+  }
+
+  console.log('Forgeon scaffold generated.');
+  console.log(`- path: ${targetRoot}`);
+  console.log(`- frontend: ${frontend}`);
+  console.log(`- db: ${db}`);
+  console.log(`- i18n: ${i18nEnabled}`);
+  console.log(`- docker: ${dockerEnabled}`);
+  console.log(`- proxy: ${proxy}`);
+}

package/src/utils/fs.mjs

@@ -0,0 +1,26 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+export function copyRecursive(source, destination) {
+  const stat = fs.statSync(source);
+
+  if (stat.isDirectory()) {
+    fs.mkdirSync(destination, { recursive: true });
+    for (const entry of fs.readdirSync(source)) {
+      copyRecursive(path.join(source, entry), path.join(destination, entry));
+    }
+    return;
+  }
+
+  fs.copyFileSync(source, destination);
+}
+
+export function writeJson(filePath, data) {
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+export function removeIfExists(targetPath) {
+  if (fs.existsSync(targetPath)) {
+    fs.rmSync(targetPath, { recursive: true, force: true });
+  }
+}

package/src/utils/values.mjs

@@ -0,0 +1,20 @@
+export function parseBoolean(value, fallback) {
+  if (value === undefined) return fallback;
+  if (typeof value === 'boolean') return value;
+
+  const normalized = String(value).trim().toLowerCase();
+  if (['true', '1', 'yes', 'y'].includes(normalized)) return true;
+  if (['false', '0', 'no', 'n'].includes(normalized)) return false;
+
+  throw new Error(`Invalid boolean value: ${value}`);
+}
+
+export function toKebabCase(value) {
+  return (
+    value
+      .trim()
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'forgeon-app'
+  );
+}

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

@@ -0,0 +1,56 @@
+# MODULE SPEC
+
+## Goal
+
+Define one repeatable fullstack pattern for Forgeon add-modules.
+
+Each feature module should be split into:
+
+1. `@forgeon/<feature>-contracts`
+2. `@forgeon/<feature>-api`
+3. `@forgeon/<feature>-web`
+
+## 1) Contracts Package
+
+Single source of truth shared by backend and frontend.
+
+Must contain:
+
+- DTO/request/response types
+- route constants (`API.<feature>.*`)
+- error codes (`<FEATURE>_*`)
+- shared constants (header/cookie names)
+
+Should contain:
+
+- zod schemas + inferred TS types
+
+## 2) API Package
+
+NestJS module integrating contracts into backend runtime.
+
+Must contain:
+
+- module/service/controller
+- guards/strategies (if auth/security related)
+- config keys
+- minimal e2e test path
+- integration with `@forgeon/core` errors/logging
+
+## 3) Web Package
+
+React integration layer for the same feature.
+
+Must contain:
+
+- provider/hooks/store
+- route guard (if feature requires auth/access)
+- API client helpers using contracts route constants/types
+- token/header/cookie wiring where relevant
+
+## Acceptance Criteria
+
+- No duplicate route strings across api/web.
+- No duplicate error-code enums across api/web.
+- Contracts package can be imported from both sides without circular dependencies.
+- Module has docs under `docs/AI/MODULES/<module-id>.md`.

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

@@ -38,11 +38,21 @@ Run build checks and show changed files.
 ## Generate Preset
 
 ```text
-Create a new preset flow for create-forgeon:
-- add new flag(s)
-- update interactive questions
-- update generated files
-- keep defaults: Prisma + Postgres, React + Vite + TS
-- update docs/AI/ARCHITECTURE.md
-```
+Create or update create-forgeon preset flow:
+- keep canonical stack fixed: NestJS + React + Prisma/Postgres + Docker
+- allow only runtime proxy choice: caddy/nginx/none
+- update generated docs fragments
+- update docs/AI/ARCHITECTURE.md and docs/AI/MODULE_SPEC.md when scope changes
+```
+
+## 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
+```
 

package/templates/base/docs/README.md

@@ -2,4 +2,5 @@
 
 - `AI/PROJECT.md` - project overview and run modes
 - `AI/ARCHITECTURE.md` - monorepo design and extension model
-- `AI/TASKS.md` - ready-to-use Codex prompts
+- `AI/MODULE_SPEC.md` - fullstack module contract (`contracts/api/web`)
+- `AI/TASKS.md` - ready-to-use Codex prompts

package/templates/base/infra/caddy/Caddyfile

@@ -1,11 +1,15 @@
 :80 {
   encode gzip zstd
 
-  handle /api/* {
-    reverse_proxy api:3000
-  }
+  route {
+    handle /api/* {
+      reverse_proxy api:3000
+    }
 
-  root * /srv
-  try_files {path} /index.html
-  file_server
-}
+    handle {
+      root * /srv
+      try_files {path} /index.html
+      file_server
+    }
+  }
+}

package/templates/base/infra/docker/compose.none.yml

@@ -0,0 +1,37 @@
+services:
+  db:
+    image: postgres:16-alpine
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: ${POSTGRES_USER}
+      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
+      POSTGRES_DB: ${POSTGRES_DB}
+    ports:
+      - "5432:5432"
+    volumes:
+      - db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+
+  api:
+    build:
+      context: ../..
+      dockerfile: apps/api/Dockerfile
+    restart: unless-stopped
+    environment:
+      PORT: ${PORT}
+      DATABASE_URL: ${DATABASE_URL}
+      I18N_ENABLED: ${I18N_ENABLED}
+      I18N_DEFAULT_LANG: ${I18N_DEFAULT_LANG}
+      I18N_FALLBACK_LANG: ${I18N_FALLBACK_LANG}
+    depends_on:
+      db:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+
+volumes:
+  db_data:

package/templates/docs-fragments/AI_ARCHITECTURE/00_title.md

@@ -0,0 +1 @@
+# ARCHITECTURE

package/templates/docs-fragments/AI_ARCHITECTURE/10_layout_base.md

@@ -0,0 +1,6 @@
+## Monorepo Layout
+
+- `apps/*` - deployable apps
+- `packages/*` - reusable modules and presets
+
+Canonical stack is fixed for now: NestJS API + React web + Prisma/Postgres + Docker.

package/templates/docs-fragments/AI_ARCHITECTURE/11_layout_infra.md

@@ -0,0 +1 @@
+- `infra/*` - runtime infrastructure (compose, proxy, env examples)

package/templates/docs-fragments/AI_ARCHITECTURE/12_layout_i18n_resources.md

@@ -0,0 +1 @@
+- `resources/*` - static assets (includes translation dictionaries when i18n is enabled)

package/templates/docs-fragments/AI_ARCHITECTURE/20_env_base.md

@@ -0,0 +1,4 @@
+## Environment Flags
+
+- `PORT` - API port (default 3000)
+- `DATABASE_URL` - DB connection string for Prisma

package/templates/docs-fragments/AI_ARCHITECTURE/21_env_i18n.md

@@ -0,0 +1,3 @@
+- `I18N_ENABLED` - toggles i18n package wiring
+- `I18N_DEFAULT_LANG` - default language
+- `I18N_FALLBACK_LANG` - fallback language

package/templates/docs-fragments/AI_ARCHITECTURE/30_default_db.md

@@ -0,0 +1,7 @@
+## Default DB Stack
+
+Current default stack is `{{DB_LABEL}}`.
+
+- Prisma schema and migrations live in `apps/api/prisma`
+- DB access is encapsulated via `PrismaModule` (`apps/api/src/prisma`)
+- Additional DB presets are intentionally out of scope for the current milestone.

package/templates/docs-fragments/AI_ARCHITECTURE/31_docker_runtime.md

@@ -0,0 +1,5 @@
+## Docker Runtime Flow
+
+- Compose file: `infra/docker/compose.yml`
+- API starts through migration deploy, then NestJS server boot.
+- Active reverse proxy preset: `{{PROXY_LABEL}}` (`{{PROXY_CONFIG_PATH}}`)

package/templates/docs-fragments/AI_ARCHITECTURE/32_scope_freeze.md

@@ -0,0 +1,5 @@
+## Scope Freeze (Current)
+
+- Frontend preset selection is disabled (React is fixed).
+- DB preset selection is disabled (Prisma/Postgres is fixed).
+- Docker is always generated; runtime proxy is selectable (`caddy|nginx|none`).

package/templates/docs-fragments/AI_ARCHITECTURE/40_docs_generation.md

@@ -0,0 +1,9 @@
+## Docs Generation Pipeline
+
+Project docs are assembled from markdown fragments in:
+
+- `packages/create-forgeon/templates/docs-fragments/README`
+- `packages/create-forgeon/templates/docs-fragments/AI_PROJECT`
+- `packages/create-forgeon/templates/docs-fragments/AI_ARCHITECTURE`
+
+During scaffold generation, the CLI selects fragments based on chosen flags and writes final docs into project root and `docs/AI`.

package/templates/docs-fragments/AI_ARCHITECTURE/50_extension_points.md

@@ -0,0 +1,8 @@
+## Extension Points
+
+Future presets should extend both code and docs in parallel:
+
+1. Add or update fullstack module templates (`contracts/api/web`).
+2. Register modules in `create-forgeon add` registry.
+3. Add module docs fragments and update module spec docs.
+4. Keep canonical core stack stable unless a major version changes it.

package/templates/docs-fragments/AI_PROJECT/00_title.md

@@ -0,0 +1 @@
+# PROJECT

package/templates/docs-fragments/AI_PROJECT/10_what_is.md

@@ -0,0 +1,3 @@
+## What This Repository Is
+
+A canonical fullstack monorepo scaffold intended to be reused as a project starter.

package/templates/docs-fragments/AI_PROJECT/20_structure_base.md

@@ -0,0 +1,5 @@
+## Structure
+
+- `apps/api` - NestJS backend
+- `apps/web` - React frontend (`{{FRONTEND_LABEL}}`, fixed)
+- `packages/core` - shared backend core placeholder

package/templates/docs-fragments/AI_PROJECT/21_structure_i18n.md

@@ -0,0 +1,2 @@
+- `packages/i18n` - reusable nestjs-i18n integration package
+- `resources/i18n` - translation dictionaries

package/templates/docs-fragments/AI_PROJECT/22_structure_docker.md

@@ -0,0 +1 @@
+- `infra` - Docker Compose (always) + proxy preset (`{{PROXY_LABEL}}`)

package/templates/docs-fragments/AI_PROJECT/23_structure_docs.md

@@ -0,0 +1 @@
+- `docs` - documentation, AI prompts, and module spec contracts

package/templates/docs-fragments/AI_PROJECT/30_run_dev.md

@@ -0,0 +1,8 @@
+## Run Modes
+
+### Dev mode
+
+```bash
+pnpm install
+pnpm dev
+```

package/templates/docs-fragments/AI_PROJECT/31_run_docker.md

@@ -0,0 +1,5 @@
+### Docker mode
+
+```bash
+docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
+```

package/templates/docs-fragments/AI_PROJECT/32_proxy_notes.md

@@ -0,0 +1,5 @@
+### Proxy Notes
+
+- Active proxy preset: `{{PROXY_LABEL}}`
+- Main proxy config: `{{PROXY_CONFIG_PATH}}`
+- Keep service names `api` and `db` stable unless you update compose and proxy config together.

package/templates/docs-fragments/AI_PROJECT/32_proxy_notes_none.md

@@ -0,0 +1,5 @@
+### Proxy Notes
+- Active proxy preset: `none`
+- No proxy config file is used.
+- API is exposed directly from compose on `localhost:3000`.
+- For OAuth/SSL test scenarios, switch to `proxy=caddy`.

package/templates/docs-fragments/AI_PROJECT/33_i18n_notes.md

@@ -0,0 +1,4 @@
+### i18n Notes
+
+- Toggle via `I18N_ENABLED`.
+- Default/fallback are controlled by `I18N_DEFAULT_LANG` and `I18N_FALLBACK_LANG`.

package/templates/docs-fragments/AI_PROJECT/40_change_boundaries_base.md

@@ -0,0 +1,3 @@
+## Change Boundaries
+
+- Safe to change first: env files, host ports, and app code under `apps/*`.

package/templates/docs-fragments/AI_PROJECT/41_change_boundaries_docker.md

@@ -0,0 +1 @@
+- Change carefully: proxy config and docker service names because routing depends on them.

package/templates/docs-fragments/README/00_title.md

@@ -0,0 +1,3 @@
+# Forgeon Fullstack Scaffold
+
+Canonical monorepo scaffold for NestJS + frontend with shared packages and generated docs.

package/templates/docs-fragments/README/10_stack.md

@@ -0,0 +1,8 @@
+## Generated Preset
+
+- Stack: `NestJS + React + Prisma/Postgres + Docker`
+- Frontend: `{{FRONTEND_LABEL}}` (fixed)
+- Database: `{{DB_LABEL}}` (fixed)
+- i18n: `{{I18N_STATUS}}`
+- Docker/infra: `enabled` (fixed)
+- Reverse proxy: `{{PROXY_LABEL}}` (`caddy|nginx|none`)

package/templates/docs-fragments/README/20_quick_start_dev_intro.md

@@ -0,0 +1,6 @@
+## Quick Start (Dev)
+
+1. Install dependencies:
+   ```bash
+   pnpm install
+   ```

package/templates/docs-fragments/README/21_quick_start_dev_db_docker.md

@@ -0,0 +1,4 @@
+2. Start local Postgres (Docker):
+   ```bash
+   docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up db -d
+   ```

package/templates/docs-fragments/README/21_quick_start_dev_db_local.md

@@ -0,0 +1 @@
+2. Ensure PostgreSQL is running locally and configure `DATABASE_URL` in `apps/api/.env`.

package/templates/docs-fragments/README/22_quick_start_dev_outro.md

@@ -0,0 +1,7 @@
+3. Run API + web in dev mode:
+   ```bash
+   pnpm dev
+   ```
+4. Open:
+   - Web: `http://localhost:5173`
+   - API health: `http://localhost:3000/api/health`

package/templates/docs-fragments/README/30_quick_start_docker.md

@@ -0,0 +1,7 @@
+## Quick Start (Docker)
+
+```bash
+docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
+```
+
+Open `http://localhost:8080`.

package/templates/docs-fragments/README/30_quick_start_docker_none.md

@@ -0,0 +1,9 @@
+## Quick Start (Docker)
+
+```bash
+docker compose --env-file infra/docker/.env.example -f infra/docker/compose.yml up --build
+```
+
+Open API at `http://localhost:3000/api/health`.
+
+Frontend is not served by Docker in `proxy=none` mode. Use `pnpm dev` for web.

package/templates/docs-fragments/README/31_proxy_preset_caddy.md

@@ -0,0 +1,9 @@
+### Proxy Preset: Caddy
+
+- `/api/*` is proxied to `api:3000`.
+- Static frontend build is served by Caddy.
+- Main proxy config: `infra/caddy/Caddyfile`.
+- Compose service wiring: `infra/docker/compose.yml` (`caddy` service).
+- Safe to edit: host ports and env values in `infra/docker/.env.example`.
+- Avoid renaming service hosts (`api`, `db`) unless you also update proxy/compose config.
+- Recommended preset for local SSL/OAuth-style testing.

package/templates/docs-fragments/README/31_proxy_preset_nginx.md

@@ -0,0 +1,8 @@
+### Proxy Preset: Nginx
+
+- `/api/*` is proxied to `api:3000`.
+- Static frontend build is served by Nginx.
+- Main proxy config: `infra/nginx/nginx.conf`.
+- Compose service wiring: `infra/docker/compose.yml` (`nginx` service).
+- Safe to edit: host ports and env values in `infra/docker/.env.example`.
+- Avoid renaming service hosts (`api`, `db`) unless you also update proxy/compose config.

package/templates/docs-fragments/README/31_proxy_preset_none.md

@@ -0,0 +1,6 @@
+### Proxy Preset: none
+
+- No reverse proxy container is started.
+- API is exposed directly on `http://localhost:3000`.
+- Useful for minimal local backend testing.
+- For OAuth/SSL-style local tests, prefer `proxy=caddy`.

package/templates/docs-fragments/README/32_prisma_container_start.md

@@ -0,0 +1,5 @@
+### Prisma In Container Start
+
+API container starts with:
+1. `pnpm --filter @forgeon/api prisma:migrate:deploy`
+2. `node apps/api/dist/main.js`

package/templates/docs-fragments/README/40_i18n.md

@@ -0,0 +1,10 @@
+## i18n Configuration
+
+Environment keys:
+- `I18N_ENABLED=true|false`
+- `I18N_DEFAULT_LANG=en`
+- `I18N_FALLBACK_LANG=en`
+
+Resources location: `resources/i18n`.
+
+When `I18N_ENABLED=false`, API starts without loading `@forgeon/i18n`.

package/templates/docs-fragments/README/90_next_steps.md

@@ -0,0 +1,7 @@
+## Next Steps
+
+- Backend entrypoint: `apps/api/src/main.ts`
+- Frontend entrypoint: `apps/web/src/main.tsx`
+- Project docs index: `docs/README.md`
+- AI workflow docs: `docs/AI/*`
+- Module contract spec: `docs/AI/MODULE_SPEC.md`

package/templates/module-fragments/jwt-auth/00_title.md

@@ -0,0 +1 @@
+# MODULE: {{MODULE_LABEL}}

package/templates/module-fragments/jwt-auth/10_overview.md

@@ -0,0 +1,6 @@
+## Overview
+
+- Id: `{{MODULE_ID}}`
+- Category: `{{MODULE_CATEGORY}}`
+- Status: {{MODULE_STATUS}}
+- Description: {{MODULE_DESCRIPTION}}

package/templates/module-fragments/jwt-auth/20_scope.md

@@ -0,0 +1,7 @@
+## Scope (Planned)
+
+Planned implementation target:
+
+1. Add reusable auth package wiring under `packages/*`.
+2. Add NestJS guard + strategy integration in `apps/api`.
+3. Add env docs and usage examples.

package/templates/module-fragments/jwt-auth/90_status_planned.md

@@ -0,0 +1,3 @@
+## Current State
+
+This module is registered but not implemented yet.

package/templates/module-fragments/queue/00_title.md

@@ -0,0 +1 @@
+# MODULE: {{MODULE_LABEL}}

package/templates/module-fragments/queue/10_overview.md

@@ -0,0 +1,6 @@
+## Overview
+
+- Id: `{{MODULE_ID}}`
+- Category: `{{MODULE_CATEGORY}}`
+- Status: {{MODULE_STATUS}}
+- Description: {{MODULE_DESCRIPTION}}

package/templates/module-fragments/queue/20_scope.md

@@ -0,0 +1,7 @@
+## Scope (Planned)
+
+Planned implementation target:
+
+1. Add queue package preset (worker + producer abstractions).
+2. Wire module imports and config in `apps/api`.
+3. Document runtime and deployment notes.

package/templates/module-fragments/queue/90_status_planned.md

@@ -0,0 +1,3 @@
+## Current State
+
+This module is registered but not implemented yet.