create-lumen 2.0.0-alpha.0 → 2.0.0-alpha.2

package/README.md

@@ -1,6 +1,6 @@
 # create-lumen
 
-A scaffolder that generates production-ready React + Vite projects (feature-based or type-based).
+A scaffolder that generates production-ready React + Vite projects (feature-based, type-based, hybrid, or none).
 
 Note: this repository is the CLI scaffolder itself, not a generated app. Generated projects live in the target folder you create.
 
@@ -34,6 +34,12 @@ npm create lumen my-app -- --template react-ts
 npm create lumen my-app -- -t react-type-js
 ```
 
+Choose framework and architecture directly:
+
+```bash
+npm create lumen my-app -- --framework react --arch none
+```
+
 Drive scaffolding directly from a manifest file or inline JSON (manifest v2):
 
 ```bash
@@ -64,15 +70,15 @@ create-lumen my-app      # after npm link
 
 ## Features
 
-- Architecture choice: feature-based or type-based (with Next.js hybrid/none in v2)
+- Architecture choice: feature-based, type-based, hybrid, or none (per-framework availability)
 - TypeScript or JavaScript output
-- CSS frameworks: Tailwind CSS v4 (CSS-first `@theme`, v3 dropped), Bootstrap 5.3+, or none
+- CSS frameworks: Tailwind CSS v4 (CSS-first `@theme`, v3 dropped) or none
 - Optional state management: Zustand or Redux Toolkit
 - Optional router (React Router)
 - Optional testing: Vitest or Jest
 - 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` validated against JSON Schema Draft 2020-12
+- 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`
@@ -148,8 +154,8 @@ src/
     ├── layouts
     ├── stores
     ├── styles
-    │   ├── globals.css      # Tailwind/Bootstrap directives (or main.css for vanilla)
-    │   └── themes.css       # Theme tokens (Tailwind @theme / Bootstrap data-bs-theme / CSS vars)
+    │   ├── globals.css      # Tailwind directives (or main.css for vanilla)
+    │   └── themes.css       # Theme tokens (Tailwind @theme / CSS vars)
     ├── types
     └── utils
 ```
@@ -177,8 +183,8 @@ src/
 ├── services
 ├── store
 ├── styles
-│   ├── globals.css      # Tailwind/Bootstrap directives (or main.css for vanilla)
-│   └── themes.css       # Theme tokens (Tailwind @theme / Bootstrap data-bs-theme / CSS vars)
+│   ├── globals.css      # Tailwind directives (or main.css for vanilla)
+│   └── themes.css       # Theme tokens (Tailwind @theme / CSS vars)
 ├── test
 └── utils
 ```
@@ -187,15 +193,32 @@ src/
 
 `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.
-- **`lumen-cli`:** The companion developer CLI that reads `lumen.config.json` to generate components, features, hooks, and services at the paths declared in `manifest.paths`.
+- **`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 and validation behavior.
-- **[Shared Contract: `create-lumen` ↔ `lumen-cli`](./docs/contracts/manifest-v2-contract.md):** The agreed contract for path mapping, barrel conventions, and version negotiation.
+- **[Documentation Index](./docs/README.md):** Complete overview of specifications, ADRs, and developer guides.
+- **[Generator Engine & Capabilities Guide (M2)](./docs/engine-capabilities.md):** Capability model, template composition, shadcn/ui on Tailwind v4, architecture presets, and Bootstrap removal.
+- **[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
 
 - **Changelog:** Notable changes are documented in [`docs/CHANGELOG.md`](./docs/CHANGELOG.md) (Keep a Changelog format).

package/bin/cli.js

@@ -36,6 +36,7 @@ main({
   projectName: cliArgs.projectName,
   manifest: cliArgs.manifest,
   template: cliArgs.template,
+  arch: cliArgs.arch,
 }).catch((e) => {
   console.error(chalk.red("\nError:"), e.message || e);
   process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "create-lumen",
-  "version": "2.0.0-alpha.0",
-  "description": "Scaffold a React + Vite project with architecture choice: feature-based or type-based.",
+  "version": "2.0.0-alpha.2",
+  "description": "Scaffold a React + Vite project with architecture choice: feature-based, type-based, hybrid, or none.",
   "type": "module",
   "bin": {
     "create-lumen": "bin/cli.js"
@@ -15,6 +15,7 @@
     "register.js",
     "src/",
     "templates/",
+    "skills/",
     "schema/",
     "README.md",
     "LICENSE"

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-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/shadcn-without-tailwind.json

@@ -6,7 +6,7 @@
     "variant": "vite"
   },
   "styling": {
-    "engine": "bootstrap"
+    "engine": "none"
   },
   "architecture": {
     "type": "feature-based"

package/schema/fixtures/v2/valid/harness-full.json

@@ -0,0 +1,44 @@
+{
+  "$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": "feature-based",
+    "validation": "strict"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "command": "oxlint .", "required": true },
+      { "name": "format", "command": "oxfmt --check .", "required": true },
+      { "name": "types", "command": "tsc -b", "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/valid/react-vite-type-based.json

@@ -6,7 +6,7 @@
     "variant": "vite"
   },
   "styling": {
-    "engine": "bootstrap"
+    "engine": "none"
   },
   "architecture": {
     "type": "type-based"

package/schema/fixtures/v2/valid/validation-none.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": "none"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "command": "oxlint .", "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/valid/validation-relaxed.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": "relaxed"
+  },
+  "harness": {
+    "commands": [
+      { "name": "lint", "command": "oxlint .", "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/lumen.config.v2.json

@@ -62,7 +62,6 @@
           "type": "string",
           "enum": [
             "tailwind",
-            "bootstrap",
             "none"
           ]
         }
@@ -75,6 +74,15 @@
     "architecture": {
       "type": "object",
       "properties": {
+        "preset": {
+          "type": "string",
+          "enum": [
+            "feature-based",
+            "type-based",
+            "hybrid",
+            "none"
+          ]
+        },
         "type": {
           "type": "string",
           "enum": [
@@ -83,10 +91,54 @@
             "hybrid",
             "none"
           ]
+        },
+        "validation": {
+          "default": "strict",
+          "type": "string",
+          "enum": [
+            "strict",
+            "relaxed",
+            "none"
+          ]
+        }
+      },
+      "additionalProperties": false
+    },
+    "harness": {
+      "type": "object",
+      "properties": {
+        "commands": {
+          "minItems": 1,
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "name": {
+                "type": "string",
+                "minLength": 1
+              },
+              "command": {
+                "type": "string",
+                "minLength": 1
+              },
+              "required": {
+                "default": true,
+                "type": "boolean"
+              },
+              "description": {
+                "type": "string"
+              }
+            },
+            "required": [
+              "name",
+              "command"
+            ],
+            "additionalProperties": false
+          }
         }
       },
       "required": [
-        "type"
+        "commands"
       ],
       "additionalProperties": false
     },

package/skills/create-lumen/SKILL.md

@@ -0,0 +1,110 @@
+---
+name: create-lumen
+description: Scaffold and extend a lumen v2 project (manifestVersion 2). Read lumen.config.json, resolve generator paths via manifest.paths, respect feature barrels, @/* alias, harness commands, and validation modes.
+---
+
+# create-lumen
+
+## When to use
+
+Use this skill when the working directory contains (or should contain) a
+`lumen.config.json` with `manifestVersion: 2`: scaffolding follow-ups,
+`lumen g` generation, `lumen doctor` / `lumen harness` diagnostics.
+
+Do NOT guess layout. Every target directory comes from the manifest.
+
+## 1. Read `lumen.config.json`
+
+```bash
+cat lumen.config.json
+```
+
+Required top-level keys: `manifestVersion: 2`, `framework`, `styling`,
+`architecture`, `ui`, `docs`, `paths`, `tooling`, `harness`.
+Source of truth: `src/manifest/schema.js` (`parseManifest`, Zod strict).
+Full spec: `docs/contracts/manifest-v2-contract.md`, `docs/manifest-v2.md`.
+
+If `manifestVersion` is missing / `framework` is a string → **v1 manifest**:
+fail fast (exit 1), generate nothing, point to
+`docs/migration/v1-to-v2.md`.
+
+## 2. Resolve paths via `manifest.paths` (never hardcode)
+
+Generators MUST do `<root>/<manifest.paths.<key>>`. POSIX `/` separators.
+
+| Framework | Preset | features | components | services | hooks | pages | ui |
+|---|---|---|---|---|---|---|---|
+| React+Vite | `feature-based` | `src/features` | `src/shared/components` | `src/shared/services` | `src/shared/hooks` | `src/app/router` | `src/shared/components/ui` |
+| React+Vite | `type-based` | `src/features` | `src/components` | `src/services` | `src/hooks` | `src/pages` | `src/ui` |
+| Next App | `feature-based`/`hybrid` | `src/features` | `src/shared/components` | `src/shared/services` | `src/shared/hooks` | `app` | `src/shared/components/ui` |
+| Next Pages | `feature-based` | `src/features` | `src/shared/components` | `src/shared/services` | `src/shared/hooks` | `pages` | `src/shared/components/ui` |
+| Any | `none` | `src` | `src` (`components/` for Next) | `src/services` | `src/hooks` | per framework | `src…/ui` |
+
+Resolver: `src/manifest/paths.js` (`resolvePaths`). Fixtures:
+`schema/fixtures/v2/valid/react-vite-feature-based.json`,
+`full-kitchen-sink.json`.
+
+## 3. Feature structure + barrels
+
+New feature at `<paths.features>/<name>/` (e.g. `src/features/billing`):
+
+```bash
+lumen g feature billing
+lumen g component billing/InvoiceCard --feature billing
+lumen g hook useBilling --feature billing
+lumen g service billing-api --feature billing
+```
+
+Rules:
+
+- Private subfolders: `components/ hooks/ layouts/ pages/ services/ store/ types/`.
+- Public barrel required: `<feature>/index.ts` (or `.js` when
+  `tooling.language === "js"`). External code imports only the barrel:
+  `import { InvoiceCard } from "@/features/billing"`.
+- Extensions: `.tsx`/`.jsx` for JSX components, `.ts`/`.js` for pure logic,
+  per `tooling.language`.
+
+## 4. Path alias `@/*`
+
+`@/*` → `<root>/src/*` (guaranteed by `tsconfig` + Vite/Next config).
+Feature-based: shared imports via `@/shared/...`.
+Type-based: `@/components/...`, `@/hooks/...`, `@/services/...`.
+
+```ts
+import { Button } from "@/shared/components/ui/button";
+import { useBilling } from "@/features/billing";
+```
+
+## 5. `harness.commands` execution
+
+`lumen harness` runs each entry in order; `required: true` (default) fails
+the run on error, `required: false` warns and continues.
+
+```json
+{ "name": "lint", "command": "oxlint .", "required": true }
+```
+
+Defaults: `lint (oxlint .)`, `format (oxfmt --check .)`, `types (tsc -b)`,
+`test (vitest run)`, `build (npm run build)`.
+
+## 6. `architecture.validation` modes
+
+| Mode | Behavior |
+|---|---|
+| `strict` | Enforce barrels, encapsulation, path rules; fail on violation. |
+| `relaxed` | Warn on violation, still generate. |
+| `none` | Skip architecture checks. |
+
+Note: `architecture.preset` is canonical; legacy `type` is accepted as an
+alias (`parseManifest` normalizes both). Valid presets: React →
+`feature-based|type-based|none`; Next → `feature-based|hybrid|none`.
+
+## 7. Common errors — reject, don't patch around
+
+- **v1 rejection:** flat config (`css`, string `framework`/`architecture`) →
+  exit 1 + migration pointer. Never partially generate.
+- **`shadcn` → `tailwind`:** `ui.kit: "shadcn"` requires
+  `styling.engine: "tailwind"` (v4 CSS-first, no `tailwind.config.js`).
+- **`bundler`/`adapter` Next-only:** `framework.bundler` (`turbopack|webpack`)
+  and `adapter` (`node|vercel|cloudflare|static`) are prohibited on `react`.
+  `react` variant MUST be `vite`; `next` MUST be `app-router|pages-router`.

package/skills/create-lumen/references/manifest-v2.md

@@ -0,0 +1,9 @@
+# manifest-v2 pointer
+
+Canonical spec lives in `docs/` — do not duplicate it here.
+
+- Contract: `docs/contracts/manifest-v2-contract.md`
+- Shape / v1→v2 diff: `docs/manifest-v2.md`
+- Zod source of truth: `src/manifest/schema.js`
+- Path resolver: `src/manifest/paths.js`
+- Valid fixtures: `schema/fixtures/v2/valid/`