create-lumen 1.2.0 → 2.0.0-alpha.1

package/README.md

@@ -1,6 +1,6 @@
 # create-lumen
 
-A scaffolder that generates production-ready React + Vite projects (feature-based or component-based).
+A scaffolder that generates production-ready React + Vite projects (feature-based or type-based).
 
 Note: this repository is the CLI scaffolder itself, not a generated app. Generated projects live in the target folder you create.
 
@@ -14,15 +14,44 @@ cd my-app
 npm run dev
 ```
 
-Non-interactive Quick Setup (TypeScript + Tailwind + Feature-based + Router + ESLint + Prettier + Vitest), no prompts:
+### Non-interactive flags
+
+Quick Setup (TypeScript + Tailwind + Feature-based + Router + ESLint + Prettier + Vitest), no prompts:
 
 ```bash
 npm create lumen my-app -- -y
 # or
 npm create lumen -- -y my-app
+# or
+npm create lumen my-app -- --yes
+```
+
+Scaffold using a template preset (`react-ts`, `react-js`, `react-type-ts`, `react-type-js`):
+
+```bash
+npm create lumen my-app -- --template react-ts
+# or
+npm create lumen my-app -- -t react-type-js
 ```
 
-The CLI ignores flag arguments when resolving the project name, so `-y` can appear before or after the app name without being mistaken for the folder name.
+Drive scaffolding directly from a manifest file or inline JSON (manifest v2):
+
+```bash
+# From file
+npm create lumen my-app -- --manifest ./lumen.config.json
+
+# From inline JSON
+npm create lumen my-app -- -m '{"manifestVersion":2,"framework":{"name":"react","variant":"vite"},...}'
+```
+
+The CLI parses options cleanly regardless of flag ordering, so flags can appear before or after the project name.
+
+Display help and version:
+
+```bash
+npm create lumen -- --help
+npm create lumen -- --version
+```
 
 Run the scaffolder locally (development / testing the generator):
 
@@ -35,14 +64,16 @@ create-lumen my-app      # after npm link
 
 ## Features
 
-- Architecture choice: feature-based or component-based
+- Architecture choice: feature-based or type-based (with Next.js hybrid/none in v2)
 - TypeScript or JavaScript output
-- CSS frameworks: Tailwind, Bootstrap, or none
+- CSS frameworks: Tailwind CSS v4 (CSS-first `@theme`, v3 dropped), Bootstrap 5.3+, or none
 - Optional state management: Zustand or Redux Toolkit
 - Optional router (React Router)
 - Optional testing: Vitest or Jest
-- Linting: ESLint (default) or Oxlint
+- Linting: ESLint (default), Oxlint, or Biome
 - Code formatter: Prettier or Oxfmt (chosen after the linter; `eslint-config-prettier` is auto-wired for the ESLint + Prettier combo)
+- Manifest v2: Emits a deterministic `lumen.config.json` (optional but recommended) validated against JSON Schema Draft 2020-12, including architecture validation modes and harness command configuration.
+- Explicit path mapping: Target directories declared for `lumen-cli` code generation
 - Optional Axios setup and icon libraries
 - Auto `git init`, generated `README` (with a project description reflecting the chosen tooling) and `LICENSE`
 - `.env.example` scaffolded, and the generated `.gitignore` excludes env files (`.env`, `.env.*`) while keeping `.env.example`
@@ -123,7 +154,7 @@ src/
     └── utils
 ```
 
-Component-based (example):
+Type-based (example):
 
 ```
 src/
@@ -152,9 +183,40 @@ src/
 └── utils
 ```
 
-## Roadmap
+## Manifest v2 & Ecosystem Architecture
+
+`create-lumen` is part of the Lumen ecosystem alongside **`lumen-cli`**:
+
+- **`create-lumen` (this repo):** The bootstrap scaffolder that initializes project repositories and writes an explicit, strictly validated `lumen.config.json` manifest (`manifestVersion: 2`) into the project root. The manifest is **optional but highly recommended** for full editor integration and agent interoperability. If omitted, `lumen-cli` will attempt to infer a basic configuration, but advanced features (like configurable harness and architecture validation) require the manifest.
+- **`lumen-cli`:** The companion developer CLI that reads `lumen.config.json` to generate components, features, hooks, services, and run diagnostics (harness and doctor) at the paths declared in `manifest.paths`. It also provides commands to inspect and update the manifest.
+
+### Manifest v2 Schema (v2.0.0-alpha.1+)
+
+The manifest now includes:
+- **`architecture.preset`**: The base architecture (`feature-based`, `type-based`, `hybrid`, `none`).
+- **`architecture.validation`**: Validation mode for `lumen doctor` (`strict`, `relaxed`, `none`).
+- **`harness.commands`**: An array of commands to run with `lumen harness` (e.g., lint, format, types, test, build), each with a name, shell command, required flag, and description.
+
+### Ecosystem Documentation & Contracts
+
+- **[Manifest v2 Overview](./docs/manifest-v2.md):** Specification of the nested schema, validation behavior, and the new harness and architecture validation fields.
+- **[Shared Contract: `create-lumen` ↔ `lumen-cli`](./docs/contracts/manifest-v2-contract.md):** The agreed contract for path mapping, barrel conventions, version negotiation, and the harness/configuration interface.
+- **[v1 to v2 Migration Guide](./docs/migration/v1-to-v2.md):** Complete guide for migrating generated projects and legacy flat configs to v2.
+
+### Agent Interoperability
+
+Lumen is designed for both people and agents. When `agentDocs: true` is set in the manifest (or via the `--agent-docs` flag), `create-lumen` generates a `.lumen/` directory in the project root containing:
+- `project.json`: The resolved manifest.
+- `architecture.json`: The effective architecture preset and validation mode.
+- `conventions.md`: A markdown file documenting project-specific conventions (e.g., component naming, file organization).
+These files enable agents to understand the project without parsing the source code.
+
+## Roadmap & Planning
 
-Released versions live in [`docs/CHANGELOG.md`](./docs/CHANGELOG.md); planned work is tracked in [`docs/ROADMAP.md`](./docs/ROADMAP.md).
+- **Changelog:** Notable changes are documented in [`docs/CHANGELOG.md`](./docs/CHANGELOG.md) (Keep a Changelog format).
+- **Roadmap:** Milestones (M1 through M5) are tracked in [`docs/ROADMAP.md`](./docs/ROADMAP.md).
+- **Visual Plan:** Dependency graphs and parallel wave execution plans live in [`docs/PLAN.md`](./docs/PLAN.md).
+- **Branching Workflow:** Guide for branch conventions and PR checklist in [`docs/BRANCHING.md`](./docs/BRANCHING.md).
 
 ## Requirements
 

package/bin/cli.js

@@ -3,14 +3,23 @@
 import { readFile } from "node:fs/promises";
 import chalk from "chalk";
 import "../register.js";
+import { parseCliArgs, printHelp } from "../src/cli-args.js";
 
 const { version } = JSON.parse(
   await readFile(new URL("../package.json", import.meta.url), "utf8")
 );
 
-const args = process.argv.slice(2);
-const quickSetup = args.includes("-y");
-const projectName = args.find((a) => !a.startsWith("-"));
+const cliArgs = parseCliArgs(process.argv.slice(2));
+
+if (cliArgs.help) {
+  printHelp();
+  process.exit(0);
+}
+
+if (cliArgs.version) {
+  console.log(version);
+  process.exit(0);
+}
 
 console.log(
   chalk.bold.cyan("\n  ✦ LUMEN") +
@@ -22,7 +31,12 @@ console.log(
 
 const { main } = await import("@/main.js");
 
-main({ quickSetup, projectName }).catch((e) => {
+main({
+  quickSetup: cliArgs.quickSetup,
+  projectName: cliArgs.projectName,
+  manifest: cliArgs.manifest,
+  template: cliArgs.template,
+}).catch((e) => {
   console.error(chalk.red("\nError:"), e.message || e);
   process.exit(1);
 });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-lumen",
-  "version": "1.2.0",
-  "description": "Scaffold a React + Vite project with architecture choice: feature-based or component-based.",
+  "version": "2.0.0-alpha.1",
+  "description": "Scaffold a React + Vite project with architecture choice: feature-based or type-based.",
   "type": "module",
   "bin": {
     "create-lumen": "bin/cli.js"
@@ -15,10 +15,13 @@
     "register.js",
     "src/",
     "templates/",
+    "skills/",
+    "schema/",
     "README.md",
     "LICENSE"
   ],
   "scripts": {
+    "gen:schema": "node scripts/generate-schema.mjs",
     "test": "node --import ./register.js --test \"tests/unit/*.test.mjs\" \"tests/smoke/*.test.mjs\"",
     "verify:vendor": "node --import ./register.js tests/verify/install-vendor.mjs",
     "verify:offline": "node --import ./register.js tests/verify/verify-offline.mjs",
@@ -35,7 +38,7 @@
     "react",
     "typescript",
     "feature-based",
-    "component-based",
+    "type-based",
     "architecture",
     "starter",
     "boilerplate"
@@ -45,9 +48,17 @@
   "dependencies": {
     "@clack/prompts": "^0.11.0",
     "chalk": "^5.6.2",
-    "execa": "^9.6.0"
+    "execa": "^9.6.0",
+    "zod": "4.6.5",
+    "zod-validation-error": "4.0.0"
   },
   "engines": {
     "node": ">=18"
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@microsoft/eslint-formatter-sarif": "^3.1.0",
+    "eslint": "^10.10.0",
+    "globals": "^17.12.0"
   }
 }

package/schema/fixtures/index.js

@@ -0,0 +1,62 @@
+import { readdir, readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+export const FIXTURES_DIR = __dirname;
+export const VALID_FIXTURES_DIR = path.join(__dirname, "v2", "valid");
+export const INVALID_FIXTURES_DIR = path.join(__dirname, "v2", "invalid");
+
+/**
+ * Loads all valid manifest fixtures as an array of { name, filename, manifest }.
+ * @returns {Promise<Array<{ name: string, filename: string, manifest: object }>>}
+ */
+export async function loadValidFixtures() {
+  const files = (await readdir(VALID_FIXTURES_DIR)).filter((f) => f.endsWith(".json"));
+  const fixtures = [];
+  for (const filename of files) {
+    const filePath = path.join(VALID_FIXTURES_DIR, filename);
+    const content = await readFile(filePath, "utf8");
+    fixtures.push({
+      name: path.basename(filename, ".json"),
+      filename,
+      manifest: JSON.parse(content),
+    });
+  }
+  return fixtures;
+}
+
+/**
+ * Loads all invalid manifest fixtures as an array of { name, filename, manifest }.
+ * @returns {Promise<Array<{ name: string, filename: string, manifest: object }>>}
+ */
+export async function loadInvalidFixtures() {
+  const files = (await readdir(INVALID_FIXTURES_DIR)).filter((f) => f.endsWith(".json"));
+  const fixtures = [];
+  for (const filename of files) {
+    const filePath = path.join(INVALID_FIXTURES_DIR, filename);
+    const content = await readFile(filePath, "utf8");
+    fixtures.push({
+      name: path.basename(filename, ".json"),
+      filename,
+      manifest: JSON.parse(content),
+    });
+  }
+  return fixtures;
+}
+
+/**
+ * Loads a single fixture by category ('valid' | 'invalid') and fixture name.
+ * @param {'valid' | 'invalid'} category
+ * @param {string} name
+ * @returns {Promise<object>}
+ */
+export async function getFixture(category, name) {
+  const dir = category === "valid" ? VALID_FIXTURES_DIR : INVALID_FIXTURES_DIR;
+  const filename = name.endsWith(".json") ? name : `${name}.json`;
+  const filePath = path.join(dir, filename);
+  const content = await readFile(filePath, "utf8");
+  return JSON.parse(content);
+}

package/schema/fixtures/v2/invalid/architecture-preset-type-mismatch.json

@@ -0,0 +1,35 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "type": "type-based",
+    "validation": "strict"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/harness-empty-commands.json

@@ -0,0 +1,37 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "strict"
+  },
+  "harness": {
+    "commands": []
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/harness-missing-command.json

@@ -0,0 +1,41 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "strict"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "required": true },
+      { "name": "test", "command": "vitest run", "required": true },
+      { "name": "build", "command": "npm run build", "required": true }
+    ]
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/invalid-manifest-version.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 3,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "feature-based"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/invalid-validation-mode.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "preset": "feature-based",
+    "validation": "super-strict"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/malformed-paths.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "feature-based"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/missing-required-fields.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "feature-based"
+  },
+  "ui": {
+    "kit": "none"
+  }
+}

package/schema/fixtures/v2/invalid/next-type-based.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "next",
+    "variant": "app-router"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "type-based"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/components",
+    "components": "src/components",
+    "services": "src/services",
+    "hooks": "src/hooks",
+    "pages": "app",
+    "ui": "src/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/next-vite.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "next",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "feature-based"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "app",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/react-bundler.json

@@ -0,0 +1,34 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite",
+    "bundler": "turbopack"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "feature-based"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}

package/schema/fixtures/v2/invalid/react-hybrid.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "manifestVersion": 2,
+  "framework": {
+    "name": "react",
+    "variant": "vite"
+  },
+  "styling": {
+    "engine": "tailwind"
+  },
+  "architecture": {
+    "type": "hybrid"
+  },
+  "ui": {
+    "kit": "none"
+  },
+  "docs": {
+    "language": "en"
+  },
+  "paths": {
+    "features": "src/features",
+    "components": "src/shared/components",
+    "services": "src/shared/services",
+    "hooks": "src/shared/hooks",
+    "pages": "src/app/router",
+    "ui": "src/shared/components/ui"
+  },
+  "tooling": {
+    "language": "ts",
+    "linter": "eslint",
+    "formatter": "prettier"
+  }
+}