create-forgeon 0.2.8 → 0.2.9

package/README.md

@@ -37,4 +37,4 @@ pnpm forgeon:sync-integrations
 - `add i18n` is implemented and applies backend/frontend i18n wiring.
 - `add jwt-auth` is implemented and auto-detects DB adapter support for refresh-token persistence.
 - Integration sync is bundled by default and runs after `add` commands (best-effort).
-- Planned modules write docs notes under `docs/AI/MODULES/`.
+- Module notes are written under `modules/<module-id>/README.md`.

package/package.json

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

package/src/core/docs.mjs

@@ -1,10 +1,9 @@
-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) {
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDatabaseLabel } from '../databases/index.mjs';
+import { getFrontendLabel } from '../frameworks/index.mjs';
+
+function renderTemplate(content, variables) {
   return content.replace(/\{\{([A-Z0-9_]+)\}\}/g, (_, key) => String(variables[key] ?? ''));
 }
 
@@ -50,7 +49,6 @@ export function generateDocs(targetRoot, options, packageRoot) {
     DB_PRISMA_STATUS: options.dbPrismaEnabled ? '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'];
@@ -78,76 +76,13 @@ export function generateDocs(targetRoot, options, packageRoot) {
   }
   readmeFragments.push('41_error_handling');
   readmeFragments.push('90_next_steps');
-
-  const aiProjectFragments = ['00_title', '10_what_is', '20_structure_base'];
-  if (options.dbPrismaEnabled) {
-    aiProjectFragments.push('20b_structure_db_prisma');
-  } else {
-    aiProjectFragments.push('20b_structure_db_none');
-  }
-  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('34_error_handling');
-  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.dbPrismaEnabled) {
-    aiArchitectureFragments.push('20b_env_db_prisma');
-  }
-  if (options.i18nEnabled) {
-    aiArchitectureFragments.push('21_env_i18n');
-  }
-  aiArchitectureFragments.push('22_ts_module_policy');
-  aiArchitectureFragments.push('23_error_handling');
-  if (options.dbPrismaEnabled) {
-    aiArchitectureFragments.push('30_default_db');
-  } else {
-    aiArchitectureFragments.push('30_default_db_none');
-  }
-  aiArchitectureFragments.push('31_docker_runtime', '32_scope_freeze');
-  aiArchitectureFragments.push('40_docs_generation', '50_extension_points');
-
-  writeDocFromFragments({
-    targetRoot,
+
+  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,
-  });
-}
+    docKey: 'README',
+    fragmentNames: readmeFragments,
+    variables,
+  });
+}

package/src/core/docs.test.mjs

@@ -18,7 +18,7 @@ describe('generateDocs', () => {
   const thisDir = path.dirname(fileURLToPath(import.meta.url));
   const packageRoot = path.resolve(thisDir, '..', '..');
 
-  it('generates docs for proxy=none without i18n section', () => {
+  it('generates docs for proxy=none without i18n section', () => {
     const targetRoot = makeTempDir('forgeon-docs-off-');
 
     try {
@@ -34,31 +34,18 @@ describe('generateDocs', () => {
         },
         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'));
-
+
+      const readme = readFile(path.join(targetRoot, 'README.md'));
+
       assert.match(readme, /db-prisma`: `disabled`/);
       assert.match(readme, /No DB module is enabled by default/);
       assert.match(readme, /Quick Start \(Docker\)/);
       assert.match(readme, /Proxy Preset: none/);
       assert.match(readme, /Error Handling \(`core-errors`\)/);
+      assert.match(readme, /Module notes index: `modules\/README\.md`/);
       assert.doesNotMatch(readme, /i18n Configuration/);
       assert.doesNotMatch(readme, /Prisma In Container Start/);
-
-      assert.match(projectDoc, /### Docker mode/);
-      assert.match(projectDoc, /Active proxy preset: `none`/);
-      assert.match(projectDoc, /CoreErrorsModule/);
-      assert.doesNotMatch(projectDoc, /packages\/i18n/);
-
-      assert.match(architectureDoc, /generated without `db-prisma`/);
-      assert.doesNotMatch(architectureDoc, /I18N_ENABLED/);
-      assert.match(architectureDoc, /API_PREFIX/);
-      assert.match(architectureDoc, /Config Strategy/);
-      assert.match(architectureDoc, /TypeScript Module Policy/);
-      assert.match(architectureDoc, /tsconfig\.base\.esm\.json/);
-      assert.doesNotMatch(architectureDoc, /DbPrismaModule/);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'docs')), false);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }
@@ -80,29 +67,17 @@ describe('generateDocs', () => {
         },
         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'));
-
+
+      const readme = readFile(path.join(targetRoot, 'README.md'));
+
       assert.match(readme, /Quick Start \(Docker\)/);
       assert.match(readme, /Proxy Preset: Caddy/);
       assert.match(readme, /i18n Configuration/);
       assert.match(readme, /db-prisma`: `enabled`/);
       assert.match(readme, /Prisma In Container Start/);
       assert.match(readme, /Error Handling \(`core-errors`\)/);
-
-      assert.match(projectDoc, /`infra` - Docker Compose \(always\) \+ proxy preset \(`caddy`\)/);
-      assert.match(projectDoc, /Main proxy config: `infra\/caddy\/Caddyfile`/);
-      assert.match(projectDoc, /CoreExceptionFilter/);
-
-      assert.match(architectureDoc, /infra\/\*/);
-      assert.match(architectureDoc, /I18N_DEFAULT_LANG/);
-      assert.doesNotMatch(architectureDoc, /I18N_ENABLED/);
-      assert.match(architectureDoc, /Active reverse proxy preset: `caddy`/);
-      assert.match(architectureDoc, /TypeScript Module Policy/);
-      assert.match(architectureDoc, /tsconfig\.base\.node\.json/);
-      assert.match(architectureDoc, /DbPrismaModule/);
+      assert.match(readme, /Module-specific notes: `modules\/<module-id>\/README\.md`/);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'docs')), false);
     } finally {
       fs.rmSync(targetRoot, { recursive: true, force: true });
     }

package/src/core/scaffold.mjs

@@ -38,7 +38,7 @@ function patchRootPackageJson(targetRoot, projectName) {
   writeJson(rootPackageJsonPath, rootPackageJson);
 }
 
-export function scaffoldProject({
+export function scaffoldProject({
   templateRoot,
   packageRoot,
   targetRoot,
@@ -50,6 +50,10 @@ export function scaffoldProject({
   proxy,
 }) {
   copyRecursive(templateRoot, targetRoot);
+  const generatedDocsPath = path.join(targetRoot, 'docs');
+  if (fs.existsSync(generatedDocsPath)) {
+    fs.rmSync(generatedDocsPath, { recursive: true, force: true });
+  }
   patchRootPackageJson(targetRoot, projectName);
   applyProxyPreset(targetRoot, proxy);
 

package/src/integrations/flow.mjs

@@ -114,5 +114,5 @@ export async function runIntegrationFlow({
 
 export function printModuleAdded(moduleId, docsPath) {
   console.log(colorize('green', `✔ Module added: ${moduleId}`));
-  console.log(`- docs: ${docsPath}`);
+  console.log(`- readme: ${docsPath}`);
 }

package/src/modules/docs.mjs

@@ -20,25 +20,25 @@ function readModuleFragment(packageRoot, moduleId, fragmentName, variables) {
   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}\``)) {
+function ensureModuleIndex(targetRoot) {
+  const indexPath = path.join(targetRoot, 'modules', 'README.md');
+  if (!fs.existsSync(indexPath)) {
+    fs.mkdirSync(path.dirname(indexPath), { recursive: true });
+    fs.writeFileSync(
+      indexPath,
+      '# Modules\n\nUser-facing notes for modules added via `create-forgeon add`.\n',
+      'utf8',
+    );
+  }
+  return indexPath;
+}
+
+function updateModuleIndex(indexPath, preset) {
+  const relativePath = `./${preset.id}/README.md`;
+  const nextLine = `- [\`${preset.id}\`](${relativePath}) - ${preset.label} (${preset.implemented ? 'implemented' : 'planned'})`;
+  const current = fs.readFileSync(indexPath, 'utf8').replace(/\r\n/g, '\n');
+
+  if (current.includes(`\`${preset.id}\``)) {
     return;
   }
 
@@ -46,7 +46,7 @@ function updateModuleIndex(indexPath, preset) {
   fs.writeFileSync(indexPath, content, 'utf8');
 }
 
-export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
+export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
   const variables = {
     MODULE_ID: preset.id,
     MODULE_LABEL: preset.label,
@@ -59,9 +59,9 @@ export function writeModuleDocs({ packageRoot, targetRoot, preset }) {
     .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 outputPath = path.join(targetRoot, 'modules', preset.id, 'README.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);

package/src/modules/executor.mjs

@@ -57,7 +57,7 @@ export function addModule({ moduleId, targetRoot, packageRoot, writeDocs = true
         targetRoot,
         preset,
       })
-    : path.join(targetRoot, 'docs', 'AI', 'MODULES', `${preset.id}.md`);
+    : path.join(targetRoot, 'modules', preset.id, 'README.md');
 
   return {
     preset,

package/src/modules/executor.test.mjs

@@ -289,11 +289,13 @@ describe('addModule', () => {
         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.equal(result.applied, false);
+      assert.match(result.message, /planned/);
+      assert.equal(fs.existsSync(result.docsPath), true);
+      assert.match(result.docsPath, /modules[\\/].+[\\/]README\.md$/);
+      assert.equal(fs.existsSync(path.join(targetRoot, 'modules', 'README.md')), true);
+
+      const note = fs.readFileSync(result.docsPath, 'utf8');
       assert.match(note, /Queue Worker/);
       assert.match(note, /Status: planned/);
     } finally {
@@ -337,6 +339,8 @@ describe('addModule', () => {
         proxy: 'caddy',
       });
 
+      assert.equal(fs.existsSync(path.join(projectRoot, 'docs')), false);
+
       const result = addModule({
         moduleId: 'i18n',
         targetRoot: projectRoot,

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

@@ -1,9 +1,11 @@
-## 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`.
+## 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 currently writes the generated project `README.md` from these fragments.
+
+Internal architecture fragments remain in the Forgeon repository as generator source material and are not emitted into generated projects by default.

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

@@ -1,7 +1,6 @@
-## 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`
+## Next Steps
+
+- Backend entrypoint: `apps/api/src/main.ts`
+- Frontend entrypoint: `apps/web/src/main.tsx`
+- Module notes index: `modules/README.md`
+- Module-specific notes: `modules/<module-id>/README.md`