create-forgeon 0.0.3 → 0.1.0

package/src/cli/add-options.mjs

@@ -0,0 +1,54 @@
+export function parseAddCliArgs(argv) {
+  const args = [...argv];
+  const options = {
+    moduleId: undefined,
+    project: '.',
+    list: false,
+    help: false,
+  };
+  const positional = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === '--') continue;
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '--list') {
+      options.list = true;
+      continue;
+    }
+
+    if (arg.startsWith('--project=')) {
+      options.project = arg.split('=')[1] || '.';
+      continue;
+    }
+
+    if (arg === '--project') {
+      if (args[i + 1] && !args[i + 1].startsWith('-')) {
+        options.project = args[i + 1];
+        i += 1;
+      }
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  if (positional.length > 0) {
+    [options.moduleId] = positional;
+  }
+
+  if (positional.length > 1 && options.project === '.') {
+    options.project = positional[1];
+  }
+
+  return options;
+}

package/src/cli/add-options.test.mjs

@@ -0,0 +1,24 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseAddCliArgs } from './add-options.mjs';
+
+describe('parseAddCliArgs', () => {
+  it('parses module id and explicit project', () => {
+    const options = parseAddCliArgs(['jwt-auth', '--project', './demo']);
+    assert.equal(options.moduleId, 'jwt-auth');
+    assert.equal(options.project, './demo');
+    assert.equal(options.list, false);
+  });
+
+  it('parses --list and --help', () => {
+    const options = parseAddCliArgs(['--list', '--help']);
+    assert.equal(options.list, true);
+    assert.equal(options.help, true);
+  });
+
+  it('uses second positional as project when project flag is absent', () => {
+    const options = parseAddCliArgs(['queue', './my-app']);
+    assert.equal(options.moduleId, 'queue');
+    assert.equal(options.project, './my-app');
+  });
+});

package/src/cli/help.mjs

@@ -0,0 +1,20 @@
+export function printHelp() {
+  console.log(`create-forgeon
+
+Usage:
+  npx create-forgeon@latest <project-name> [options]
+  npx create-forgeon@latest add <module-id> [options]
+  npx create-forgeon@latest add --list
+
+Create options:
+  --i18n <true|false>          Enable i18n (default: true)
+  --proxy <caddy|nginx|none>   Reverse proxy preset (default: caddy)
+  --install                    Run pnpm install after generation
+  -y, --yes                    Skip prompts and use defaults
+  -h, --help                   Show this help
+
+Add options:
+  --project <path>             Target project path (default: current directory)
+  --list                       List available modules
+`);
+}

package/src/cli/options.mjs

@@ -0,0 +1,121 @@
+import readline from 'node:readline/promises';
+import { stdin as input, stdout as output } from 'node:process';
+import { DEFAULT_OPTIONS, DEFAULT_PROXY } from '../constants.mjs';
+import { promptSelect } from './prompt-select.mjs';
+
+const REMOVED_FLAGS = new Set(['frontend', 'db', 'docker']);
+
+export function parseCliArgs(argv) {
+  const args = [...argv];
+  const options = { ...DEFAULT_OPTIONS };
+  const positional = [];
+
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+
+    if (arg === '--') continue;
+
+    if (arg === '-h' || arg === '--help') {
+      options.help = true;
+      continue;
+    }
+
+    if (arg === '-y' || arg === '--yes') {
+      options.yes = true;
+      continue;
+    }
+
+    if (arg === '--install') {
+      options.install = true;
+      continue;
+    }
+
+    if (arg.startsWith('--no-')) {
+      const key = arg.slice(5);
+      if (REMOVED_FLAGS.has(key)) {
+        throw new Error(`Option "--${key}" has been removed. Forgeon now uses a fixed stack.`);
+      }
+      if (key === 'install') options.install = false;
+      if (key === 'i18n') options.i18n = false;
+      continue;
+    }
+
+    if (arg.startsWith('--')) {
+      const [keyRaw, inlineValue] = arg.split('=');
+      const key = keyRaw.slice(2);
+      if (REMOVED_FLAGS.has(key)) {
+        throw new Error(`Option "--${key}" has been removed. Forgeon now uses a fixed stack.`);
+      }
+
+      let value = inlineValue;
+      if (value === undefined && args[i + 1] && !args[i + 1].startsWith('-')) {
+        value = args[i + 1];
+        i += 1;
+      }
+
+      if (Object.prototype.hasOwnProperty.call(options, key)) {
+        options[key] = value;
+      }
+
+      continue;
+    }
+
+    positional.push(arg);
+  }
+
+  return { options, positional };
+}
+
+export async function promptForMissingOptions(options) {
+  const nextOptions = { ...options };
+
+  if (!nextOptions.name) {
+    if (!input.isTTY) {
+      throw new Error('Project name is required in non-interactive mode. Pass it as first argument.');
+    }
+
+    const rl = readline.createInterface({ input, output });
+    try {
+      nextOptions.name = await rl.question('Project name: ');
+    } finally {
+      await rl.close();
+    }
+  }
+
+  if (!nextOptions.yes && nextOptions.i18n === undefined) {
+    nextOptions.i18n = await promptSelect({
+      message: 'Enable i18n:',
+      defaultValue: 'true',
+      choices: [
+        { label: 'true', value: 'true' },
+        { label: 'false', value: 'false' },
+      ],
+    });
+  }
+
+  if (!nextOptions.yes && !nextOptions.proxy) {
+    nextOptions.proxy = await promptSelect({
+      message: 'Reverse proxy preset:',
+      defaultValue: DEFAULT_PROXY,
+      choices: [
+        { label: 'caddy', value: 'caddy' },
+        { label: 'nginx', value: 'nginx' },
+        { label: 'none', value: 'none' },
+      ],
+    });
+  }
+
+  if (nextOptions.yes) {
+    if (nextOptions.i18n === undefined) nextOptions.i18n = 'true';
+    if (!nextOptions.proxy) nextOptions.proxy = DEFAULT_PROXY;
+  }
+
+  if (nextOptions.i18n === undefined) {
+    nextOptions.i18n = 'true';
+  }
+  if (!nextOptions.proxy) {
+    nextOptions.proxy = DEFAULT_PROXY;
+  }
+
+  return nextOptions;
+}

package/src/cli/options.test.mjs

@@ -0,0 +1,41 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { parseCliArgs } from './options.mjs';
+
+describe('parseCliArgs', () => {
+  it('parses positional name and supported inline options', () => {
+    const { options, positional } = parseCliArgs([
+      'demo-app',
+      '--i18n=false',
+      '--proxy=caddy',
+      '--install',
+      '--yes',
+    ]);
+
+    assert.equal(positional[0], 'demo-app');
+    assert.equal(options.i18n, 'false');
+    assert.equal(options.proxy, 'caddy');
+    assert.equal(options.install, true);
+    assert.equal(options.yes, true);
+  });
+
+  it('parses separated option values and negated i18n flag', () => {
+    const { options } = parseCliArgs(['--proxy', 'none', '--no-i18n', '--help']);
+
+    assert.equal(options.proxy, 'none');
+    assert.equal(options.i18n, false);
+    assert.equal(options.help, true);
+  });
+
+  it('throws for removed stack-selection flags', () => {
+    assert.throws(
+      () => parseCliArgs(['demo', '--frontend=react']),
+      /Option "--frontend" has been removed/,
+    );
+    assert.throws(() => parseCliArgs(['demo', '--db=prisma']), /Option "--db" has been removed/);
+    assert.throws(
+      () => parseCliArgs(['demo', '--docker=true']),
+      /Option "--docker" has been removed/,
+    );
+  });
+});

package/src/cli/prompt-select.mjs

@@ -0,0 +1,89 @@
+import readline from 'node:readline';
+import { stdin as input, stdout as output } from 'node:process';
+
+export async function promptSelect({
+  message,
+  choices,
+  defaultValue,
+  inputStream = input,
+  outputStream = output,
+}) {
+  if (!Array.isArray(choices) || choices.length === 0) {
+    throw new Error('promptSelect requires at least one choice.');
+  }
+
+  let index = choices.findIndex((choice) => choice.value === defaultValue);
+  if (index < 0) index = 0;
+
+  if (!inputStream.isTTY || !outputStream.isTTY) {
+    return choices[index].value;
+  }
+
+  readline.emitKeypressEvents(inputStream);
+
+  const canSetRawMode = typeof inputStream.setRawMode === 'function';
+  const wasRawModeEnabled = Boolean(inputStream.isRaw);
+  if (canSetRawMode && !wasRawModeEnabled) {
+    inputStream.setRawMode(true);
+  }
+
+  let renderedLines = 0;
+
+  const render = () => {
+    if (renderedLines > 0) {
+      readline.moveCursor(outputStream, 0, -renderedLines);
+      readline.cursorTo(outputStream, 0);
+      readline.clearScreenDown(outputStream);
+    }
+
+    outputStream.write(`${message}\n`);
+    for (let i = 0; i < choices.length; i += 1) {
+      const marker = i === index ? '>' : ' ';
+      outputStream.write(`${marker} ${choices[i].label}\n`);
+    }
+    outputStream.write('Use Up/Down arrows and Enter.\n');
+
+    renderedLines = choices.length + 2;
+  };
+
+  return new Promise((resolve, reject) => {
+    const cleanup = () => {
+      inputStream.off('keypress', onKeypress);
+      if (canSetRawMode && !wasRawModeEnabled) {
+        inputStream.setRawMode(false);
+      }
+      outputStream.write('\n');
+    };
+
+    const onKeypress = (_str, key) => {
+      if (!key) return;
+
+      if (key.ctrl && key.name === 'c') {
+        cleanup();
+        reject(new Error('Prompt cancelled.'));
+        return;
+      }
+
+      if (key.name === 'up') {
+        index = (index - 1 + choices.length) % choices.length;
+        render();
+        return;
+      }
+
+      if (key.name === 'down') {
+        index = (index + 1) % choices.length;
+        render();
+        return;
+      }
+
+      if (key.name === 'return' || key.name === 'enter') {
+        const selected = choices[index].value;
+        cleanup();
+        resolve(selected);
+      }
+    };
+
+    render();
+    inputStream.on('keypress', onKeypress);
+  });
+}

package/src/cli/prompt-select.test.mjs

@@ -0,0 +1,34 @@
+import { describe, it } from 'node:test';
+import assert from 'node:assert/strict';
+import { promptSelect } from './prompt-select.mjs';
+
+describe('promptSelect', () => {
+  it('returns default choice in non-tty mode', async () => {
+    const value = await promptSelect({
+      message: 'Pick one',
+      defaultValue: 'b',
+      choices: [
+        { label: 'A', value: 'a' },
+        { label: 'B', value: 'b' },
+      ],
+      inputStream: { isTTY: false },
+      outputStream: { isTTY: false },
+    });
+
+    assert.equal(value, 'b');
+  });
+
+  it('throws for empty choices', async () => {
+    await assert.rejects(
+      () =>
+        promptSelect({
+          message: 'Pick one',
+          defaultValue: 'a',
+          choices: [],
+          inputStream: { isTTY: false },
+          outputStream: { isTTY: false },
+        }),
+      /requires at least one choice/,
+    );
+  });
+});

package/src/constants.mjs

@@ -0,0 +1,13 @@
+export const DEFAULT_FRONTEND = 'react';
+export const DEFAULT_DB = 'prisma';
+export const DEFAULT_PROXY = 'caddy';
+export const FIXED_DOCKER_ENABLED = true;
+
+export const DEFAULT_OPTIONS = {
+  name: undefined,
+  i18n: undefined,
+  proxy: undefined,
+  install: false,
+  yes: false,
+  help: false,
+};

package/src/core/docs.mjs

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDatabaseLabel } from '../databases/index.mjs';
+import { getFrontendLabel } from '../frameworks/index.mjs';
+import { getProxyConfigPath } from '../infrastructure/proxy.mjs';
+
+function renderTemplate(content, variables) {
+  return content.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => String(variables[key] ?? ''));
+}
+
+function readFragment(fragmentsRoot, docKey, fragmentName, variables) {
+  const fragmentPath = path.join(fragmentsRoot, docKey, `${fragmentName}.md`);
+  if (!fs.existsSync(fragmentPath)) {
+    throw new Error(`Missing docs fragment: ${fragmentPath}`);
+  }
+
+  const raw = fs.readFileSync(fragmentPath, 'utf8').replace(/\r\n/g, '\n').trim();
+  return renderTemplate(raw, variables).trim();
+}
+
+function writeDocFromFragments({
+  targetRoot,
+  outputPath,
+  fragmentsRoot,
+  docKey,
+  fragmentNames,
+  variables,
+}) {
+  const fragments = fragmentNames
+    .map((fragmentName) => readFragment(fragmentsRoot, docKey, fragmentName, variables))
+    .filter((fragment) => fragment.length > 0);
+
+  const content = `${fragments
+    .join('\n\n')
+    .replace(/\n{2,}(?=- )/g, '\n')
+    .replace(/\n{3,}/g, '\n\n')
+    .trimEnd()}\n`;
+  const absoluteOutputPath = path.join(targetRoot, outputPath);
+  fs.mkdirSync(path.dirname(absoluteOutputPath), { recursive: true });
+  fs.writeFileSync(absoluteOutputPath, content, 'utf8');
+}
+
+export function generateDocs(targetRoot, options, packageRoot) {
+  const fragmentsRoot = path.resolve(packageRoot, 'templates', 'docs-fragments');
+  const variables = {
+    FRONTEND_LABEL: getFrontendLabel(options.frontend),
+    DB_LABEL: getDatabaseLabel(options.db),
+    I18N_STATUS: options.i18nEnabled ? 'enabled' : 'disabled',
+    DOCKER_STATUS: 'enabled',
+    PROXY_LABEL: options.proxy,
+    PROXY_CONFIG_PATH: getProxyConfigPath(options.proxy),
+  };
+
+  const readmeFragments = ['00_title', '10_stack', '20_quick_start_dev_intro'];
+  readmeFragments.push('21_quick_start_dev_db_docker');
+  readmeFragments.push('22_quick_start_dev_outro');
+  readmeFragments.push(
+    options.proxy === 'none' ? '30_quick_start_docker_none' : '30_quick_start_docker',
+  );
+  if (options.proxy === 'caddy') {
+    readmeFragments.push('31_proxy_preset_caddy');
+  } else if (options.proxy === 'nginx') {
+    readmeFragments.push('31_proxy_preset_nginx');
+  } else {
+    readmeFragments.push('31_proxy_preset_none');
+  }
+  readmeFragments.push('32_prisma_container_start');
+  if (options.i18nEnabled) {
+    readmeFragments.push('40_i18n');
+  }
+  readmeFragments.push('90_next_steps');
+
+  const aiProjectFragments = ['00_title', '10_what_is', '20_structure_base'];
+  if (options.i18nEnabled) {
+    aiProjectFragments.push('21_structure_i18n');
+  }
+  aiProjectFragments.push('22_structure_docker', '23_structure_docs', '30_run_dev', '31_run_docker');
+  if (options.proxy === 'none') {
+    aiProjectFragments.push('32_proxy_notes_none');
+  } else {
+    aiProjectFragments.push('32_proxy_notes');
+  }
+  if (options.i18nEnabled) {
+    aiProjectFragments.push('33_i18n_notes');
+  }
+  aiProjectFragments.push('40_change_boundaries_base');
+  if (options.proxy !== 'none') {
+    aiProjectFragments.push('41_change_boundaries_docker');
+  }
+
+  const aiArchitectureFragments = ['00_title', '10_layout_base', '11_layout_infra'];
+  if (options.i18nEnabled) {
+    aiArchitectureFragments.push('12_layout_i18n_resources');
+  }
+  aiArchitectureFragments.push('20_env_base');
+  if (options.i18nEnabled) {
+    aiArchitectureFragments.push('21_env_i18n');
+  }
+  aiArchitectureFragments.push('30_default_db', '31_docker_runtime', '32_scope_freeze');
+  aiArchitectureFragments.push('40_docs_generation', '50_extension_points');
+
+  writeDocFromFragments({
+    targetRoot,
+    outputPath: 'README.md',
+    fragmentsRoot,
+    docKey: 'README',
+    fragmentNames: readmeFragments,
+    variables,
+  });
+
+  writeDocFromFragments({
+    targetRoot,
+    outputPath: path.join('docs', 'AI', 'PROJECT.md'),
+    fragmentsRoot,
+    docKey: 'AI_PROJECT',
+    fragmentNames: aiProjectFragments,
+    variables,
+  });
+
+  writeDocFromFragments({
+    targetRoot,
+    outputPath: path.join('docs', 'AI', 'ARCHITECTURE.md'),
+    fragmentsRoot,
+    docKey: 'AI_ARCHITECTURE',
+    fragmentNames: aiArchitectureFragments,
+    variables,
+  });
+}

package/src/core/docs.test.mjs

@@ -0,0 +1,91 @@
+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 { generateDocs } from './docs.mjs';
+
+function makeTempDir(prefix) {
+  return fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+}
+
+function readFile(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+describe('generateDocs', () => {
+  const thisDir = path.dirname(fileURLToPath(import.meta.url));
+  const packageRoot = path.resolve(thisDir, '..', '..');
+
+  it('generates docs for proxy=none without i18n section', () => {
+    const targetRoot = makeTempDir('forgeon-docs-off-');
+
+    try {
+      generateDocs(
+        targetRoot,
+        {
+          frontend: 'react',
+          db: 'prisma',
+          dockerEnabled: true,
+          i18nEnabled: false,
+          proxy: 'none',
+        },
+        packageRoot,
+      );
+
+      const readme = readFile(path.join(targetRoot, 'README.md'));
+      const projectDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'PROJECT.md'));
+      const architectureDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'ARCHITECTURE.md'));
+
+      assert.match(readme, /Docker\/infra: `enabled`/);
+      assert.match(readme, /Quick Start \(Docker\)/);
+      assert.match(readme, /Proxy Preset: none/);
+      assert.doesNotMatch(readme, /i18n Configuration/);
+
+      assert.match(projectDoc, /### Docker mode/);
+      assert.match(projectDoc, /Active proxy preset: `none`/);
+      assert.doesNotMatch(projectDoc, /packages\/i18n/);
+
+      assert.match(architectureDoc, /infra\/\*/);
+      assert.doesNotMatch(architectureDoc, /I18N_ENABLED/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+
+  it('generates docker and caddy notes when enabled', () => {
+    const targetRoot = makeTempDir('forgeon-docs-on-');
+
+    try {
+      generateDocs(
+        targetRoot,
+        {
+          frontend: 'react',
+          db: 'prisma',
+          dockerEnabled: true,
+          i18nEnabled: true,
+          proxy: 'caddy',
+        },
+        packageRoot,
+      );
+
+      const readme = readFile(path.join(targetRoot, 'README.md'));
+      const projectDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'PROJECT.md'));
+      const architectureDoc = readFile(path.join(targetRoot, 'docs', 'AI', 'ARCHITECTURE.md'));
+
+      assert.match(readme, /Quick Start \(Docker\)/);
+      assert.match(readme, /Proxy Preset: Caddy/);
+      assert.match(readme, /i18n Configuration/);
+
+      assert.match(projectDoc, /`infra` - Docker Compose \(always\) \+ proxy preset \(`caddy`\)/);
+      assert.match(projectDoc, /Main proxy config: `infra\/caddy\/Caddyfile`/);
+
+      assert.match(architectureDoc, /infra\/\*/);
+      assert.match(architectureDoc, /I18N_ENABLED/);
+      assert.match(architectureDoc, /Active reverse proxy preset: `caddy`/);
+    } finally {
+      fs.rmSync(targetRoot, { recursive: true, force: true });
+    }
+  });
+});

package/src/core/install.mjs

@@ -0,0 +1,14 @@
+import { spawnSync } from 'node:child_process';
+
+export function runInstall(targetRoot) {
+  const pnpmCmd = process.platform === 'win32' ? 'pnpm.cmd' : 'pnpm';
+  const result = spawnSync(pnpmCmd, ['install'], {
+    cwd: targetRoot,
+    stdio: 'inherit',
+    shell: false,
+  });
+
+  if (result.status !== 0) {
+    process.exit(result.status ?? 1);
+  }
+}

package/src/core/scaffold.mjs

@@ -0,0 +1,57 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { copyRecursive, writeJson } from '../utils/fs.mjs';
+import { toKebabCase } from '../utils/values.mjs';
+import { applyI18nDisabled, applyProxyPreset, patchDockerEnvForI18n } from '../presets/index.mjs';
+import { generateDocs } from './docs.mjs';
+
+function writeApiEnvExample(targetRoot, i18nEnabled) {
+  const apiEnvExamplePath = path.join(targetRoot, 'apps', 'api', '.env.example');
+  const apiEnvLines = [
+    'PORT=3000',
+    'DATABASE_URL=postgresql://postgres:postgres@localhost:5432/app?schema=public',
+  ];
+
+  if (i18nEnabled) {
+    apiEnvLines.push('I18N_ENABLED=true');
+    apiEnvLines.push('I18N_DEFAULT_LANG=en');
+    apiEnvLines.push('I18N_FALLBACK_LANG=en');
+  }
+
+  fs.writeFileSync(apiEnvExamplePath, `${apiEnvLines.join('\n')}\n`, 'utf8');
+}
+
+function patchRootPackageJson(targetRoot, projectName) {
+  const rootPackageJsonPath = path.join(targetRoot, 'package.json');
+  const rootPackageJson = JSON.parse(fs.readFileSync(rootPackageJsonPath, 'utf8'));
+  rootPackageJson.name = toKebabCase(projectName);
+
+  if (rootPackageJson.scripts) {
+    delete rootPackageJson.scripts['create:forgeon'];
+  }
+
+  writeJson(rootPackageJsonPath, rootPackageJson);
+}
+
+export function scaffoldProject({
+  templateRoot,
+  packageRoot,
+  targetRoot,
+  projectName,
+  frontend,
+  db,
+  i18nEnabled,
+  proxy,
+}) {
+  copyRecursive(templateRoot, targetRoot);
+  patchRootPackageJson(targetRoot, projectName);
+  applyProxyPreset(targetRoot, proxy);
+  patchDockerEnvForI18n(targetRoot, i18nEnabled);
+
+  if (!i18nEnabled) {
+    applyI18nDisabled(targetRoot);
+  }
+
+  writeApiEnvExample(targetRoot, i18nEnabled);
+  generateDocs(targetRoot, { frontend, db, dockerEnabled: true, i18nEnabled, proxy }, packageRoot);
+}