create-forgeon 0.0.3 → 0.1.0

package/src/core/validate.mjs

@@ -0,0 +1,12 @@
+import { ensureDatabaseSupported } from '../databases/index.mjs';
+import { ensureFrontendSupported } from '../frameworks/index.mjs';
+import { ensureProxySupported } from '../infrastructure/proxy.mjs';
+
+export function validatePresetSupport({ frontend, db, dockerEnabled, proxy }) {
+  ensureFrontendSupported(frontend);
+  ensureDatabaseSupported(db);
+
+  if (dockerEnabled) {
+    ensureProxySupported(proxy);
+  }
+}

package/src/core/validate.test.mjs

@@ -0,0 +1,73 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { validatePresetSupport } from './validate.mjs';
+
+describe('validatePresetSupport', () => {
+  it('accepts current supported presets', () => {
+    assert.doesNotThrow(() =>
+      validatePresetSupport({
+        frontend: 'react',
+        db: 'prisma',
+        dockerEnabled: true,
+        proxy: 'caddy',
+      }),
+    );
+
+    assert.doesNotThrow(() =>
+      validatePresetSupport({
+        frontend: 'react',
+        db: 'prisma',
+        dockerEnabled: true,
+        proxy: 'none',
+      }),
+    );
+  });
+
+  it('throws for angular not-yet-implemented preset', () => {
+    assert.throws(
+      () =>
+        validatePresetSupport({
+          frontend: 'angular',
+          db: 'prisma',
+          dockerEnabled: false,
+          proxy: 'none',
+        }),
+      /Frontend preset "angular" is not implemented yet/,
+    );
+  });
+
+  it('throws for unsupported db preset', () => {
+    assert.throws(
+      () =>
+        validatePresetSupport({
+          frontend: 'react',
+          db: 'mongo',
+          dockerEnabled: false,
+          proxy: 'none',
+        }),
+      /Unsupported db preset: mongo/,
+    );
+  });
+
+  it('throws for unsupported proxy only when docker is enabled', () => {
+    assert.throws(
+      () =>
+        validatePresetSupport({
+          frontend: 'react',
+          db: 'prisma',
+          dockerEnabled: true,
+          proxy: 'traefik',
+        }),
+      /Unsupported proxy preset: traefik/,
+    );
+
+    assert.doesNotThrow(() =>
+      validatePresetSupport({
+        frontend: 'react',
+        db: 'prisma',
+        dockerEnabled: false,
+        proxy: 'traefik',
+      }),
+    );
+  });
+});

package/src/databases/index.mjs

@@ -0,0 +1,26 @@
+const DATABASE_PRESETS = {
+  prisma: {
+    id: 'prisma',
+    label: 'Prisma + PostgreSQL',
+    implemented: true,
+  },
+};
+
+export function getDatabasePreset(db) {
+  return DATABASE_PRESETS[db] ?? null;
+}
+
+export function getDatabaseLabel(db) {
+  return getDatabasePreset(db)?.label ?? db;
+}
+
+export function ensureDatabaseSupported(db) {
+  const preset = getDatabasePreset(db);
+  if (!preset) {
+    throw new Error(`Unsupported db preset: ${db}. Currently implemented: prisma.`);
+  }
+
+  if (!preset.implemented) {
+    throw new Error(`DB preset "${db}" is not implemented yet.`);
+  }
+}

package/src/frameworks/index.mjs

@@ -0,0 +1,32 @@
+const FRONTEND_PRESETS = {
+  react: {
+    id: 'react',
+    label: 'React + Vite + TypeScript',
+    implemented: true,
+  },
+  angular: {
+    id: 'angular',
+    label: 'Angular',
+    implemented: false,
+    message: 'Frontend preset "angular" is not implemented yet. Use --frontend react.',
+  },
+};
+
+export function getFrontendPreset(frontend) {
+  return FRONTEND_PRESETS[frontend] ?? null;
+}
+
+export function getFrontendLabel(frontend) {
+  return getFrontendPreset(frontend)?.label ?? frontend;
+}
+
+export function ensureFrontendSupported(frontend) {
+  const preset = getFrontendPreset(frontend);
+  if (!preset) {
+    throw new Error(`Unsupported frontend preset: ${frontend}`);
+  }
+
+  if (!preset.implemented) {
+    throw new Error(preset.message ?? `Frontend preset "${frontend}" is not implemented yet.`);
+  }
+}

package/src/infrastructure/proxy.mjs

@@ -0,0 +1,12 @@
+const SUPPORTED_PROXIES = ['caddy', 'nginx', 'none'];
+
+export function ensureProxySupported(proxy) {
+  if (!SUPPORTED_PROXIES.includes(proxy)) {
+    throw new Error(`Unsupported proxy preset: ${proxy}. Use caddy, nginx, or none.`);
+  }
+}
+
+export function getProxyConfigPath(proxy) {
+  if (proxy === 'none') return 'n/a';
+  return proxy === 'caddy' ? 'infra/caddy/Caddyfile' : 'infra/nginx/nginx.conf';
+}

package/src/modules/docs.mjs

@@ -0,0 +1,70 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function renderTemplate(content, variables) {
+  return content.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => String(variables[key] ?? ''));
+}
+
+function readModuleFragment(packageRoot, moduleId, fragmentName, variables) {
+  const fragmentPath = path.join(
+    packageRoot,
+    'templates',
+    'module-fragments',
+    moduleId,
+    `${fragmentName}.md`,
+  );
+  if (!fs.existsSync(fragmentPath)) {
+    throw new Error(`Missing module docs fragment: ${fragmentPath}`);
+  }
+  const raw = fs.readFileSync(fragmentPath, 'utf8').replace(/\r\n/g, '\n').trim();
+  return renderTemplate(raw, variables).trim();
+}
+
+function ensureModuleIndex(targetRoot) {
+  const indexPath = path.join(targetRoot, 'docs', 'AI', 'MODULES', 'README.md');
+  if (!fs.existsSync(indexPath)) {
+    fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+    fs.writeFileSync(
+      indexPath,
+      '# MODULES\n\nGenerated notes for module presets added via `create-forgeon add`.\n',
+      'utf8',
+    );
+  }
+  return indexPath;
+}
+
+function updateModuleIndex(indexPath, preset) {
+  const relativePath = `${preset.id}.md`;
+  const nextLine = `- \`${preset.id}\` - ${preset.label} (${preset.implemented ? 'implemented' : 'planned'})`;
+  const current = fs.readFileSync(indexPath, 'utf8').replace(/\r\n/g, '\n');
+
+  if (current.includes(`\`${preset.id}\``)) {
+    return;
+  }
+
+  const content = `${current.trimEnd()}\n${nextLine}\n`;
+  fs.writeFileSync(indexPath, content, 'utf8');
+}
+
+export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
+  const variables = {
+    MODULE_ID: preset.id,
+    MODULE_LABEL: preset.label,
+    MODULE_CATEGORY: preset.category,
+    MODULE_STATUS: preset.implemented ? 'implemented' : 'planned',
+    MODULE_DESCRIPTION: preset.description,
+  };
+
+  const sections = preset.docFragments
+    .map((fragmentName) => readModuleFragment(packageRoot, preset.id, fragmentName, variables))
+    .filter(Boolean);
+
+  const outputPath = path.join(targetRoot, 'docs', 'AI', 'MODULES', `${preset.id}.md`);
+  fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+  fs.writeFileSync(outputPath, `${sections.join('\n\n').trimEnd()}\n`, 'utf8');
+
+  const indexPath = ensureModuleIndex(targetRoot);
+  updateModuleIndex(indexPath, preset);
+
+  return outputPath;
+}

package/src/modules/executor.mjs

@@ -0,0 +1,40 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { ensureModuleExists } from './registry.mjs';
+import { writeModuleDocs } from './docs.mjs';
+
+function ensureForgeonLikeProject(targetRoot) {
+  const requiredPaths = [
+    path.join(targetRoot, 'package.json'),
+    path.join(targetRoot, 'pnpm-workspace.yaml'),
+    path.join(targetRoot, 'apps', 'api'),
+  ];
+
+  for (const requiredPath of requiredPaths) {
+    if (!fs.existsSync(requiredPath)) {
+      throw new Error(
+        `Target path does not look like a Forgeon project: missing ${path.relative(targetRoot, requiredPath)}`,
+      );
+    }
+  }
+}
+
+export function addModule({ moduleId, targetRoot, packageRoot }) {
+  ensureForgeonLikeProject(targetRoot);
+
+  const preset = ensureModuleExists(moduleId);
+  const docsPath = writeModuleDocs({
+    packageRoot,
+    targetRoot,
+    preset,
+  });
+
+  return {
+    preset,
+    docsPath,
+    applied: preset.implemented,
+    message: preset.implemented
+      ? `Module "${preset.id}" applied.`
+      : `Module "${preset.id}" is planned; docs note created only.`,
+  };
+}

package/src/modules/executor.test.mjs

@@ -0,0 +1,62 @@
+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';
+
+function mkTmp(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function createMinimalForgeonProject(targetRoot) {
+  fs.mkdirSync(path.join(targetRoot, 'apps', 'api'), { recursive: true });
+  fs.writeFileSync(path.join(targetRoot, 'package.json'), '{"name":"demo"}\n', 'utf8');
+  fs.writeFileSync(path.join(targetRoot, 'pnpm-workspace.yaml'), 'packages:\n  - apps/*\n', 'utf8');
+}
+
+describe('addModule', () => {
+  const modulesDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(modulesDir, '..', '..');
+
+  it('creates module docs note for planned module', () => {
+    const targetRoot = mkTmp('forgeon-module-');
+    try {
+      createMinimalForgeonProject(targetRoot);
+      const result = addModule({
+        moduleId: 'jwt-auth',
+        targetRoot,
+        packageRoot,
+      });
+
+      assert.equal(result.applied, false);
+      assert.match(result.message, /planned/);
+      assert.equal(fs.existsSync(result.docsPath), true);
+
+      const note = fs.readFileSync(result.docsPath, 'utf8');
+      assert.match(note, /JWT Auth/);
+      assert.match(note, /Status: planned/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('throws for unknown module id', () => {
+    const targetRoot = mkTmp('forgeon-module-unknown-');
+    try {
+      createMinimalForgeonProject(targetRoot);
+      assert.throws(
+        () =>
+          addModule({
+            moduleId: 'unknown-module',
+            targetRoot,
+            packageRoot,
+          }),
+        /Unknown module/,
+      );
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+});

package/src/modules/registry.mjs

@@ -0,0 +1,37 @@
+const MODULE_PRESETS = {
+  'jwt-auth': {
+    id: 'jwt-auth',
+    label: 'JWT Auth',
+    category: 'auth-security',
+    implemented: false,
+    description: 'JWT auth preset with guards and passport strategy wiring.',
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_planned'],
+  },
+  queue: {
+    id: 'queue',
+    label: 'Queue Worker',
+    category: 'background-jobs',
+    implemented: false,
+    description: 'Queue processing preset (BullMQ-style app wiring).',
+    docFragments: ['00_title', '10_overview', '20_scope', '90_status_planned'],
+  },
+};
+
+export function listModulePresets() {
+  return Object.values(MODULE_PRESETS);
+}
+
+export function getModulePreset(moduleId) {
+  return MODULE_PRESETS[moduleId] ?? null;
+}
+
+export function ensureModuleExists(moduleId) {
+  const preset = getModulePreset(moduleId);
+  if (!preset) {
+    const available = listModulePresets()
+      .map((item) => item.id)
+      .join(', ');
+    throw new Error(`Unknown module "${moduleId}". Available modules: ${available}`);
+  }
+  return preset;
+}

package/src/presets/i18n.mjs

@@ -0,0 +1,203 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { removeIfExists, writeJson } from '../utils/fs.mjs';
+
+export function applyI18nDisabled(targetRoot) {
+  removeIfExists(path.join(targetRoot, 'packages', 'i18n'));
+  removeIfExists(path.join(targetRoot, 'resources', 'i18n'));
+
+  const apiPackagePath = path.join(targetRoot, 'apps', 'api', 'package.json');
+  if (fs.existsSync(apiPackagePath)) {
+    const apiPackage = JSON.parse(fs.readFileSync(apiPackagePath, 'utf8'));
+
+    if (apiPackage.scripts) {
+      delete apiPackage.scripts.predev;
+    }
+
+    if (apiPackage.dependencies) {
+      delete apiPackage.dependencies['@forgeon/i18n'];
+      delete apiPackage.dependencies['nestjs-i18n'];
+    }
+
+    writeJson(apiPackagePath, apiPackage);
+  }
+
+  const apiDockerfile = path.join(targetRoot, 'apps', 'api', 'Dockerfile');
+  if (fs.existsSync(apiDockerfile)) {
+    let content = fs.readFileSync(apiDockerfile, 'utf8');
+    content = content
+      .replace(/^COPY packages\/i18n\/package\.json packages\/i18n\/package\.json\r?\n/gm, '')
+      .replace(/^COPY packages\/i18n packages\/i18n\r?\n/gm, '')
+      .replace(/^RUN pnpm --filter @forgeon\/i18n build\r?\n/gm, '');
+    fs.writeFileSync(apiDockerfile, content, 'utf8');
+  }
+
+  const appModulePath = path.join(targetRoot, 'apps', 'api', 'src', 'app.module.ts');
+  fs.writeFileSync(
+    appModulePath,
+    `import { Module } from '@nestjs/common';
+import { ConfigModule } from '@nestjs/config';
+import appConfig from './config/app.config';
+import { HealthController } from './health/health.controller';
+import { PrismaModule } from './prisma/prisma.module';
+import { AppExceptionFilter } from './common/filters/app-exception.filter';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot({
+      isGlobal: true,
+      load: [appConfig],
+      envFilePath: '.env',
+    }),
+    PrismaModule,
+  ],
+  controllers: [HealthController],
+  providers: [AppExceptionFilter],
+})
+export class AppModule {}
+`,
+    'utf8',
+  );
+
+  const healthControllerPath = path.join(
+    targetRoot,
+    'apps',
+    'api',
+    'src',
+    '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',
+  );
+
+  const filterPath = path.join(
+    targetRoot,
+    'apps',
+    'api',
+    'src',
+    'common',
+    'filters',
+    'app-exception.filter.ts',
+  );
+  fs.writeFileSync(
+    filterPath,
+    `import {
+  ArgumentsHost,
+  Catch,
+  ExceptionFilter,
+  HttpException,
+  HttpStatus,
+  Injectable,
+} from '@nestjs/common';
+import { Response } from 'express';
+
+@Injectable()
+@Catch()
+export class AppExceptionFilter implements ExceptionFilter {
+  catch(exception: unknown, host: ArgumentsHost): void {
+    const context = host.switchToHttp();
+    const response = context.getResponse<Response>();
+
+    const status =
+      exception instanceof HttpException
+        ? exception.getStatus()
+        : HttpStatus.INTERNAL_SERVER_ERROR;
+
+    const payload =
+      exception instanceof HttpException
+        ? exception.getResponse()
+        : { message: 'Internal server error' };
+
+    const message =
+      typeof payload === 'object' && payload !== null && 'message' in payload
+        ? Array.isArray((payload as { message?: unknown }).message)
+          ? String((payload as { message: unknown[] }).message[0] ?? 'Internal server error')
+          : String((payload as { message?: unknown }).message ?? 'Internal server error')
+        : typeof payload === 'string'
+          ? payload
+          : 'Internal server error';
+
+    response.status(status).json({
+      error: {
+        code: this.resolveCode(status),
+        message,
+      },
+    });
+  }
+
+  private resolveCode(status: number): string {
+    switch (status) {
+      case HttpStatus.BAD_REQUEST:
+        return 'validation_error';
+      case HttpStatus.UNAUTHORIZED:
+        return 'unauthorized';
+      case HttpStatus.FORBIDDEN:
+        return 'forbidden';
+      case HttpStatus.NOT_FOUND:
+        return 'not_found';
+      case HttpStatus.CONFLICT:
+        return 'conflict';
+      default:
+        return 'internal_error';
+    }
+  }
+}
+`,
+    'utf8',
+  );
+
+  const appConfigPath = path.join(targetRoot, 'apps', 'api', 'src', 'config', 'app.config.ts');
+  fs.writeFileSync(
+    appConfigPath,
+    `import { registerAs } from '@nestjs/config';
+
+export default registerAs('app', () => ({
+  port: Number(process.env.PORT ?? 3000),
+}));
+`,
+    'utf8',
+  );
+}
+
+export function patchDockerEnvForI18n(targetRoot, i18nEnabled) {
+  const dockerEnvPath = path.join(targetRoot, 'infra', 'docker', '.env.example');
+  if (fs.existsSync(dockerEnvPath) && !i18nEnabled) {
+    const content = fs
+      .readFileSync(dockerEnvPath, 'utf8')
+      .replace(/^I18N_ENABLED=.*\r?\n/gm, '')
+      .replace(/^I18N_DEFAULT_LANG=.*\r?\n/gm, '')
+      .replace(/^I18N_FALLBACK_LANG=.*\r?\n/gm, '');
+    fs.writeFileSync(dockerEnvPath, content.trimEnd() + '\n', 'utf8');
+  }
+
+  const composePath = path.join(targetRoot, 'infra', 'docker', 'compose.yml');
+  if (fs.existsSync(composePath) && !i18nEnabled) {
+    const content = fs
+      .readFileSync(composePath, 'utf8')
+      .replace(/^\s+I18N_ENABLED:.*\r?\n/gm, '')
+      .replace(/^\s+I18N_DEFAULT_LANG:.*\r?\n/gm, '')
+      .replace(/^\s+I18N_FALLBACK_LANG:.*\r?\n/gm, '');
+    fs.writeFileSync(composePath, content, 'utf8');
+  }
+}

package/src/presets/index.mjs

@@ -0,0 +1,2 @@
+export { applyProxyPreset } from './proxy.mjs';
+export { applyI18nDisabled, patchDockerEnvForI18n } from './i18n.mjs';

package/src/presets/proxy.mjs

@@ -0,0 +1,32 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { removeIfExists } from '../utils/fs.mjs';
+
+export function applyProxyPreset(targetRoot, proxy) {
+  const dockerDir = path.join(targetRoot, 'infra', 'docker');
+  const composeTarget = path.join(dockerDir, 'compose.yml');
+  const composeSource = path.join(dockerDir, `compose.${proxy}.yml`);
+
+  if (!fs.existsSync(composeSource)) {
+    throw new Error(`Missing proxy compose preset: ${composeSource}`);
+  }
+
+  fs.copyFileSync(composeSource, composeTarget);
+
+  removeIfExists(path.join(dockerDir, 'compose.nginx.yml'));
+  removeIfExists(path.join(dockerDir, 'compose.caddy.yml'));
+  removeIfExists(path.join(dockerDir, 'compose.none.yml'));
+
+  if (proxy === 'nginx') {
+    removeIfExists(path.join(dockerDir, 'caddy.Dockerfile'));
+    removeIfExists(path.join(targetRoot, 'infra', 'caddy'));
+  } else if (proxy === 'caddy') {
+    removeIfExists(path.join(dockerDir, 'nginx.Dockerfile'));
+    removeIfExists(path.join(targetRoot, 'infra', 'nginx'));
+  } else if (proxy === 'none') {
+    removeIfExists(path.join(dockerDir, 'nginx.Dockerfile'));
+    removeIfExists(path.join(dockerDir, 'caddy.Dockerfile'));
+    removeIfExists(path.join(targetRoot, 'infra', 'nginx'));
+    removeIfExists(path.join(targetRoot, 'infra', 'caddy'));
+  }
+}

package/src/run-add-module.mjs

@@ -0,0 +1,47 @@
+import path from 'node:path';
+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';
+
+function printModuleList() {
+  const modules = listModulePresets();
+  console.log('Available modules:');
+  for (const moduleItem of modules) {
+    const status = moduleItem.implemented ? 'implemented' : 'planned';
+    console.log(`- ${moduleItem.id} (${status}) - ${moduleItem.description}`);
+  }
+}
+
+export async function runAddModule(argv = process.argv.slice(2)) {
+  const options = parseAddCliArgs(argv);
+
+  if (options.help) {
+    printAddHelp();
+    return;
+  }
+
+  if (options.list) {
+    printModuleList();
+    return;
+  }
+
+  if (!options.moduleId) {
+    throw new Error('Module id is required. Use `create-forgeon add --list` to see available modules.');
+  }
+
+  const srcDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(srcDir, '..');
+  const targetRoot = path.resolve(process.cwd(), options.project);
+
+  const result = addModule({
+    moduleId: options.moduleId,
+    targetRoot,
+    packageRoot,
+  });
+
+  console.log(result.message);
+  console.log(`- module: ${result.preset.id}`);
+  console.log(`- docs: ${result.docsPath}`);
+}