create-lumen 2.0.0-beta.1 → 2.0.0-beta.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lumen",
-  "version": "2.0.0-beta.1",
+  "version": "2.0.0-beta.2",
   "description": "Scaffold a React + Vite project with architecture choice: feature-based, type-based, hybrid, or none.",
   "type": "module",
   "bin": {

package/schema/lumen.config.v2.json

@@ -247,6 +247,35 @@
       ],
       "additionalProperties": false
     },
+    "database": {
+      "type": "object",
+      "properties": {
+        "orm": {
+          "type": "string",
+          "enum": [
+            "prisma",
+            "none"
+          ]
+        },
+        "provider": {
+          "default": "postgresql",
+          "type": "string",
+          "enum": [
+            "postgresql"
+          ]
+        }
+      },
+      "required": [
+        "orm"
+      ],
+      "additionalProperties": false
+    },
+    "docker": {
+      "type": "boolean"
+    },
+    "routeGroups": {
+      "type": "boolean"
+    },
     "reactCompiler": {
       "type": "boolean"
     },

package/src/agent-context.js

@@ -19,17 +19,19 @@ function resolveManifest(manifestOrResponses) {
 }
 
 /**
- * Render the short agent conventions markdown from a manifest.
- * Deterministic: derived only from stable manifest fields.
+ * Render the root AGENTS.md document from a manifest.
+ * Single Source of Truth (SSOT): references `lumen.config.json` directly.
+ * Byte-deterministic: derived only from stable manifest fields (no timestamps).
  * @param {object} manifest - validated manifest v2
  * @returns {string}
  */
-export function renderConventions(manifest) {
+export function renderAgentsMd(manifest) {
   const preset = manifest.architecture?.preset ?? manifest.architecture?.type ?? "feature-based";
   const validation = manifest.architecture?.validation ?? "strict";
   const paths = manifest.paths ?? {};
   const harness = manifest.harness ?? { commands: [] };
   const barrelFile = manifest.tooling?.language === "js" ? "index.js" : "index.ts";
+  const isNext = manifest.framework?.name === "next";
 
   const pathLines = Object.entries(paths)
     .map(([key, value]) => `- ${key}: \`${value}\``)
@@ -41,74 +43,96 @@ export function renderConventions(manifest) {
 
   const harnessSummary = (harness.commands ?? []).map((c) => `\`${c.command}\``).join(", ");
 
+  let nextSection = "";
+  if (isNext) {
+    nextSection =
+      `<!-- BEGIN:nextjs-agent-rules -->\n` +
+      `## This is NOT the Next.js you know\n` +
+      `This version has breaking changes — APIs, conventions, and file structure may all differ from your training data. Read the relevant guide in node_modules/next/dist/docs/ (resolved from this file's directory...) before writing any code. Heed deprecation notices.\n` +
+      `<!-- END:nextjs-agent-rules -->\n` +
+      `\n` +
+      `### Next.js Component Rules\n` +
+      `\n` +
+      `- By default, all components in the App Router are React Server Components (RSC).\n` +
+      `- Use the \`"use client"\` directive only at the top of files that require browser APIs, React state, or event handlers.\n` +
+      `- Never import server-only modules or secrets into client components.\n` +
+      `\n`;
+  }
+
+  const uiPath = paths.ui ?? "@/components/ui";
+  const componentsPath = paths.components ?? "@/components";
+
   return (
-    `# Lumen Agent Conventions\n` +
+    `# AGENTS.md\n` +
+    `\n` +
+    `> **Single Source of Truth (SSOT)**: Project configuration, paths, and harness definitions are defined in \`lumen.config.json\`. Consult \`lumen.config.json\` for the authoritative settings.\n` +
     `\n` +
-    `Generated from \`lumen.config.json\`. Resolve every file location via \`paths.*\` in \`.lumen/architecture.json\` (preset: \`${preset}\`, validation: \`${validation}\`).\n` +
+    `${nextSection}` +
+    `## Architecture & Conventions\n` +
     `\n` +
-    `## Rules\n` +
+    `- **Architecture Preset**: \`${preset}\`\n` +
+    `- **Validation Mode**: \`${validation}\` (${VALIDATION_NOTES[validation] ?? VALIDATION_NOTES.strict})\n` +
+    `- **Paths Resolution**: Resolve file locations via \`paths.*\` defined in \`lumen.config.json\` — never hardcode arbitrary alternative locations.\n` +
+    `- **Feature Barrels**: Every feature directory (under \`${paths.features ?? "src/features"}/<feature>/\`) must re-export its public API via \`${barrelFile}\`.\n` +
+    `- **Shared Imports**: Import shared utilities via \`@/shared\` (plus path aliases configured in tsconfig/jsconfig).\n` +
     `\n` +
-    `- Resolve all paths via \`paths.*\` — never hardcode alternative \`src/...\` locations.\n` +
-    `- Feature barrel: every \`src/features/<feature>/\` must re-export its public API via \`${barrelFile}\`.\n` +
-    `- Shared code: import shared utilities via \`@/shared\` (plus the \`@/...\` aliases from tsconfig/jsconfig).\n` +
-    `- Harness: before finishing, run each command in \`.lumen/project.json\` \`harness.commands\` in order (${harnessSummary}).\n` +
-    `- Validation mode \`${validation}\`: ${VALIDATION_NOTES[validation] ?? VALIDATION_NOTES.strict}\n` +
+    `## Component Taxonomy\n` +
     `\n` +
-    `## Paths\n` +
+    `Components must be organized strictly according to \`lumen.config.json\` path mappings:\n` +
+    `- **Atomic UI Primitives**: Base atoms and UI primitives (e.g. shadcn components) belong in \`paths.ui\` (\`${uiPath}\`).\n` +
+    `- **Compound Components**: Shared composite components belong in \`paths.components\` (\`${componentsPath}\`).\n` +
+    `- **Feature Components**: Domain-specific components belong inside their respective feature folder (e.g. \`${paths.features ?? "src/features"}/<feature>/components\`).\n` +
+    `\n` +
+    `Lumen CLI and AI agents must place primitive UI atoms under \`paths.ui\`, global compound components under \`paths.components\`, and feature-scoped components in their respective feature folders.\n` +
+    `\n` +
+    `## Path Mappings\n` +
     `\n` +
     `${pathLines}\n` +
     `\n` +
-    `## Harness\n` +
+    `## Validation Harness\n` +
+    `\n` +
+    `Before finishing work, run each harness command defined in \`lumen.config.json\` \`harness.commands\` in order (${harnessSummary}):\n` +
     `\n` +
     `${harnessLines}\n`
   );
 }
 
 /**
- * Build the deterministic agent-context payload from a validated manifest v2.
- * No timestamps — output must be byte-stable.
+ * Backward compatibility alias for renderAgentsMd.
+ * @param {object} manifest - validated manifest v2
+ * @returns {string}
+ */
+export function renderConventions(manifest) {
+  return renderAgentsMd(manifest);
+}
+
+/**
+ * Build deterministic agent context metadata.
+ * Retained for backwards compatibility with tests and callers.
  * @param {object} manifest - validated manifest v2
- * @returns {{ project: object, architecture: object, conventionsMd: string }}
+ * @returns {{ agentsMd: string, conventionsMd: string }}
  */
 export function buildAgentContext(manifest) {
-  const project = {
-    manifestVersion: manifest.manifestVersion,
-    framework: manifest.framework,
-    styling: manifest.styling,
-    tooling: manifest.tooling,
-    harness: manifest.harness,
-    docs: manifest.docs,
-  };
-  const architecture = {
-    preset: manifest.architecture?.preset ?? manifest.architecture?.type,
-    validation: manifest.architecture?.validation ?? "strict",
-    paths: manifest.paths,
+  const agentsMd = renderAgentsMd(manifest);
+  return {
+    agentsMd,
+    conventionsMd: agentsMd,
   };
-  const conventionsMd = renderConventions(manifest);
-  return { project, architecture, conventionsMd };
-}
-
-function writeJson(filePath, value) {
-  return fsp.writeFile(filePath, JSON.stringify(value, null, 2) + "\n", "utf8");
 }
 
 /**
- * Emit the .lumen agent context dir into a scaffolded project.
- * Accepts either a validated manifest v2 or scaffolder responses
- * (uses responses._manifestSource when present, else buildManifest).
- * Writes .lumen/project.json, .lumen/architecture.json, .lumen/conventions.md
- * with 2-space indent + trailing newline. Byte-deterministic (no timestamps).
+ * Emit AGENTS.md directly into project root.
+ * Accepts either a validated manifest v2 or scaffolder responses.
+ * Writes ${projectPath}/AGENTS.md with trailing newline. Byte-deterministic.
+ * Does not emit duplicate JSON files or .lumen/ directory.
  * @param {string} projectPath - absolute path to scaffolded project
  * @param {object} manifestOrResponses
- * @returns {Promise<string>} absolute path to the .lumen dir
+ * @returns {Promise<string>} absolute path to AGENTS.md
  */
 export async function emitAgentContext(projectPath, manifestOrResponses) {
   const manifest = resolveManifest(manifestOrResponses);
-  const { project, architecture, conventionsMd } = buildAgentContext(manifest);
-  const dir = path.join(projectPath, ".lumen");
-  await fsp.mkdir(dir, { recursive: true });
-  await writeJson(path.join(dir, "project.json"), project);
-  await writeJson(path.join(dir, "architecture.json"), architecture);
-  await fsp.writeFile(path.join(dir, "conventions.md"), conventionsMd, "utf8");
-  return dir;
+  const content = renderAgentsMd(manifest);
+  const filePath = path.join(projectPath, "AGENTS.md");
+  await fsp.writeFile(filePath, content, "utf8");
+  return filePath;
 }

package/src/cleanup.js

@@ -1,7 +1,25 @@
 import { deleteIfExists } from "@/utils/fs.js";
+import { promises as fsp } from "fs";
+import path from "path";
 
-export async function cleanupBoilerplate(projectPath) {
+export async function cleanupBoilerplate(projectPath, responses = {}) {
   await deleteIfExists(`${projectPath}/public`);
   await deleteIfExists(`${projectPath}/src/assets`);
   await deleteIfExists(`${projectPath}/.oxlintrc.json`);
+  await deleteIfExists(`${projectPath}/.provenance.json`);
+
+  const isNext =
+    responses?.framework?.name === "next" ||
+    responses?.frameworkName === "next" ||
+    (await fsp.stat(path.join(projectPath, "next.config.ts")).catch(() => false)) ||
+    (await fsp.stat(path.join(projectPath, "next.config.mjs")).catch(() => false)) ||
+    (await fsp.stat(path.join(projectPath, "next.config.js")).catch(() => false));
+
+  if (isNext) {
+    await deleteIfExists(`${projectPath}/src/app/App.tsx`);
+    await deleteIfExists(`${projectPath}/src/app/App.jsx`);
+    await deleteIfExists(`${projectPath}/src/app/hooks`);
+    await deleteIfExists(`${projectPath}/src/app/contexts`);
+    await deleteIfExists(`${projectPath}/src/app/providers`);
+  }
 }

package/src/cli-args.js

@@ -280,10 +280,15 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
       architecture: { type: "string" },
       bundler: { type: "string", short: "b" },
       adapter: { type: "string" },
+      database: { type: "string" },
+      db: { type: "string" },
       "react-compiler": { type: "boolean" },
       reactCompiler: { type: "boolean" },
+      "route-groups": { type: "boolean" },
+      routeGroups: { type: "boolean" },
       "agent-docs": { type: "boolean" },
       agentDocs: { type: "boolean" },
+      docker: { type: "boolean" },
       linter: { type: "string" },
       help: { type: "boolean", short: "h", default: false },
       version: { type: "boolean", short: "v", default: false },
@@ -303,8 +308,14 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
 
   const bundler = values.bundler ? values.bundler.trim().toLowerCase() : null;
   const adapter = values.adapter ? values.adapter.trim().toLowerCase() : null;
+  let database = values.database || values.db || null;
+  if (database) {
+    database = database.trim().toLowerCase();
+  }
   const reactCompiler = values["react-compiler"] ?? values.reactCompiler ?? null;
+  const routeGroups = values["route-groups"] ?? values.routeGroups ?? null;
   const agentDocs = values["agent-docs"] ?? values.agentDocs ?? null;
+  const docker = Boolean(values.docker);
   const linter = values.linter ? values.linter.trim().toLowerCase() : null;
 
   return {
@@ -316,8 +327,11 @@ export function parseCliArgs(argv = process.argv.slice(2)) {
     arch,
     bundler,
     adapter,
+    database,
     reactCompiler,
+    routeGroups,
     agentDocs,
+    docker,
     linter,
     help: Boolean(values.help),
     version: Boolean(values.version),
@@ -368,7 +382,10 @@ export function manifestToResponses(manifest, projectName) {
   const canClientRoute = isPromptVisible(framework, "router");
   const supportsBundler = isPromptVisible(framework, "bundler");
   const supportsAdapter = isPromptVisible(framework, "adapter");
+  const supportsDatabase = isPromptVisible(framework, "database");
   const supportsCompiler = isPromptVisible(framework, "reactCompiler");
+  const supportsRouteGroups = isPromptVisible(framework, "routeGroups");
+  const supportsDocker = isPromptVisible(framework, "docker");
 
   return {
     projectName,
@@ -382,6 +399,10 @@ export function manifestToResponses(manifest, projectName) {
       supportsAdapter && manifest.framework?.adapter
         ? manifest.framework.adapter
         : undefined,
+    database:
+      supportsDatabase && manifest.database?.orm
+        ? manifest.database.orm
+        : "none",
     architecture: manifest.architecture?.type || "feature-based",
     language: manifest.tooling?.language || "ts",
     cssFramework: manifest.styling?.engine || "tailwind",
@@ -390,7 +411,9 @@ export function manifestToResponses(manifest, projectName) {
     uiKit: manifest.ui?.kit || "none",
     docsLanguage: manifest.docs?.language || "en",
     reactCompiler: supportsCompiler ? manifest.reactCompiler : undefined,
+    routeGroups: supportsRouteGroups ? manifest.routeGroups : undefined,
     agentDocs: manifest.agentDocs,
+    docker: supportsDocker ? (manifest.docker ?? false) : false,
     // Sensible defaults for scaffolder conditional passes (Next.js ships no
     // verified test-runner overlay yet, so it defaults to none; explicit
     // vitest/jest selection still applies the standard overlays)
@@ -421,6 +444,9 @@ ${chalk.bold("OPTIONS")}
   ${chalk.yellow("-m, --manifest")} <path>  Drive scaffolding from a lumen.config.json or inline JSON
   ${chalk.yellow("-t, --template")} <name>  Scaffold using a preset (${Object.keys(PRESETS).join(", ")})
   ${chalk.yellow("-f, --framework")} <name> Target framework (react, next, react:vite, next:app-router, etc.)
+  ${chalk.yellow("--db, --database")} <orm> Database ORM (prisma, none)
+  ${chalk.yellow("    --docker")}           Include multi-stage Dockerfile & docker-compose for Next.js standalone
+  ${chalk.yellow("--route-groups")}         Include Next.js route groups preset (public, auth, private, admin)
   ${chalk.yellow("-h, --help")}             Show this help message
   ${chalk.yellow("-v, --version")}          Show version number
 

package/src/dependencies.js

@@ -1,4 +1,5 @@
 import { execa } from "execa";
+import { normalizeFramework } from "./engine/capabilities.js";
 
 export async function installDeps(pkgManager, dev, packages, cwd) {
   let cmd, args;
@@ -40,11 +41,15 @@ export async function installAllDeps(responses, pkg, cwd) {
 // the conditional wiring stays verifiable without a network install.
 export function computeDeps(responses) {
   const deps = [];
-  const fwName =
-    typeof responses.framework === "string"
-      ? responses.framework
-      : (responses.framework?.name ?? responses.frameworkName ?? "react");
+  const fw = normalizeFramework(
+    responses.framework || {
+      name: responses.frameworkName,
+      variant: responses.frameworkVariant,
+    }
+  );
+  const fwName = fw.name;
   const cssDevDeps = [];
+  const databaseDevDeps = [];
   const testingDevDeps = [];
   const linterDevDeps = [];
   const formatterDevDeps = [];
@@ -83,6 +88,15 @@ export function computeDeps(responses) {
     deps.push("axios");
   }
 
+  // Database
+  if (responses.database === "prisma") {
+    deps.push("@prisma/client");
+    databaseDevDeps.push("prisma");
+    if (responses.language === "ts") {
+      databaseDevDeps.push("tsx");
+    }
+  }
+
   // Testing
   if (responses.testing === "vitest") {
     testingDevDeps.push(
@@ -92,17 +106,29 @@ export function computeDeps(responses) {
       "jsdom"
     );
   } else if (responses.testing === "jest") {
-    testingDevDeps.push(
-      "jest",
-      "jest-environment-jsdom",
-      "@testing-library/react",
-      "@testing-library/jest-dom",
-      "jsdom",
-      "babel-jest",
-      "@babel/preset-env",
-      "@babel/preset-react",
-      "@babel/preset-typescript"
-    );
+    if (fwName === "next") {
+      testingDevDeps.push(
+        "jest",
+        "jest-environment-jsdom",
+        "@testing-library/react",
+        "@testing-library/jest-dom"
+      );
+      if (responses.language === "ts") {
+        testingDevDeps.push("@types/jest");
+      }
+    } else {
+      testingDevDeps.push(
+        "jest",
+        "jest-environment-jsdom",
+        "@testing-library/react",
+        "@testing-library/jest-dom",
+        "jsdom",
+        "babel-jest",
+        "@babel/preset-env",
+        "@babel/preset-react",
+        "@babel/preset-typescript"
+      );
+    }
   }
 
   // Linter
@@ -136,6 +162,7 @@ export function computeDeps(responses) {
 
   const devDepBatches = [
     cssDevDeps,
+    databaseDevDeps,
     testingDevDeps,
     linterDevDeps,
     formatterDevDeps,

package/src/engine/capabilities.js

@@ -18,6 +18,9 @@ export const CAPABILITIES = {
   NEXT_IMAGE: "next-image",
   SPA_FALLBACK: "spa-fallback",
   AGENT_DOCS: "agent-docs",
+  DATABASE: "database",
+  DOCKER: "docker",
+  ROUTE_GROUPS: "route-groups",
 };
 
 export const FRAMEWORK_CAPABILITIES = {
@@ -37,6 +40,7 @@ export const FRAMEWORK_CAPABILITIES = {
     allowedFormatters: ["prettier", "oxfmt", "none"],
     allowedBundlers: [],
     allowedAdapters: [],
+    allowedDatabases: [],
     supportsRouterPrompt: true,
   },
   "next:app-router": {
@@ -52,6 +56,9 @@ export const FRAMEWORK_CAPABILITIES = {
       CAPABILITIES.NEXT_FONT,
       CAPABILITIES.NEXT_IMAGE,
       CAPABILITIES.AGENT_DOCS,
+      CAPABILITIES.DATABASE,
+      CAPABILITIES.DOCKER,
+      CAPABILITIES.ROUTE_GROUPS,
     ],
     allowedArchitectures: ["feature-based", "hybrid", "none"],
     allowedStyling: ["tailwind", "none"],
@@ -61,6 +68,7 @@ export const FRAMEWORK_CAPABILITIES = {
     allowedFormatters: ["prettier", "none"],
     allowedBundlers: ["turbopack", "webpack"],
     allowedAdapters: ["node", "vercel", "cloudflare", "static"],
+    allowedDatabases: ["prisma", "none"],
     supportsRouterPrompt: false, // filesystem routing is built-in
   },
   "next:pages-router": {
@@ -74,6 +82,8 @@ export const FRAMEWORK_CAPABILITIES = {
       CAPABILITIES.NEXT_FONT,
       CAPABILITIES.NEXT_IMAGE,
       CAPABILITIES.AGENT_DOCS,
+      CAPABILITIES.DATABASE,
+      CAPABILITIES.DOCKER,
     ],
     allowedArchitectures: ["feature-based", "hybrid", "none"],
     allowedStyling: ["tailwind", "none"],
@@ -83,6 +93,7 @@ export const FRAMEWORK_CAPABILITIES = {
     allowedFormatters: ["prettier", "none"],
     allowedBundlers: ["turbopack", "webpack"],
     allowedAdapters: ["node", "vercel", "cloudflare", "static"],
+    allowedDatabases: ["prisma", "none"],
     supportsRouterPrompt: false, // filesystem routing is built-in
   },
 };
@@ -168,6 +179,22 @@ export function isOptionCompatible(framework, optionKey, optionValue) {
         return hasCapability(framework, CAPABILITIES.REACT_COMPILER);
       }
       return true;
+    case "database":
+    case "db":
+      if (!desc.allowedDatabases || desc.allowedDatabases.length === 0) {
+        return optionValue === "none" || !optionValue;
+      }
+      return desc.allowedDatabases.includes(optionValue);
+    case "docker":
+      if (optionValue === true) {
+        return hasCapability(framework, CAPABILITIES.DOCKER);
+      }
+      return true;
+    case "routeGroups":
+      if (optionValue === true) {
+        return hasCapability(framework, CAPABILITIES.ROUTE_GROUPS);
+      }
+      return true;
     default:
       return true;
   }
@@ -192,6 +219,7 @@ export function getCompatibleOptions(framework) {
     formatters: [...desc.allowedFormatters],
     bundlers: [...desc.allowedBundlers],
     adapters: [...desc.allowedAdapters],
+    databases: [...(desc.allowedDatabases || [])],
     supportsRouterPrompt: desc.supportsRouterPrompt,
   };
 }
@@ -289,6 +317,12 @@ export function isPromptVisible(framework, promptName) {
       return hasCapability(fw, CAPABILITIES.ADAPTERS);
     case "reactCompiler":
       return hasCapability(fw, CAPABILITIES.REACT_COMPILER);
+    case "database":
+      return hasCapability(fw, CAPABILITIES.DATABASE);
+    case "docker":
+      return hasCapability(fw, CAPABILITIES.DOCKER);
+    case "routeGroups":
+      return hasCapability(fw, CAPABILITIES.ROUTE_GROUPS);
     default:
       return true;
   }
@@ -334,6 +368,9 @@ export function getDefaultResponses(framework, { projectName = "my-app" } = {})
       stateManagement: "none",
       iconLibrary: "none",
       apiClient: "none",
+      database: "none",
+      docker: false,
+      routeGroups: false,
       linter: "eslint",
       formatter: "prettier",
       docsLanguage: "en",
@@ -355,6 +392,9 @@ export function getDefaultResponses(framework, { projectName = "my-app" } = {})
     stateManagement: "none",
     iconLibrary: "none",
     apiClient: "none",
+    database: "none",
+    docker: false,
+    routeGroups: false,
     linter: "eslint",
     formatter: "prettier",
     docsLanguage: "en",
@@ -390,6 +430,15 @@ export function sanitizeResponsesForFramework(framework, responses = {}) {
       sanitized.reactCompiler = false;
     }
   }
+  if (!isPromptVisible(fw, "database")) {
+    sanitized.database = "none";
+  }
+  if (!isPromptVisible(fw, "docker")) {
+    sanitized.docker = false;
+  }
+  if (!isPromptVisible(fw, "routeGroups")) {
+    sanitized.routeGroups = false;
+  }
 
   for (const [key, val] of Object.entries(sanitized)) {
     if (val === undefined || val === null) continue;