create-lumen 1.2.0 → 2.0.0-alpha.1

package/schema/lumen.config.v2.json

@@ -0,0 +1,269 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+  "title": "Lumen manifest v2",
+  "description": "Schema for lumen.config.json v2 - emitted by create-lumen, consumed by lumen-cli. See docs/manifest-v2.md",
+  "type": "object",
+  "properties": {
+    "$schema": {
+      "default": "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json",
+      "type": "string",
+      "format": "uri"
+    },
+    "manifestVersion": {
+      "type": "number",
+      "const": 2
+    },
+    "framework": {
+      "type": "object",
+      "properties": {
+        "name": {
+          "type": "string",
+          "enum": [
+            "react",
+            "next"
+          ]
+        },
+        "variant": {
+          "type": "string",
+          "enum": [
+            "vite",
+            "app-router",
+            "pages-router"
+          ]
+        },
+        "bundler": {
+          "type": "string",
+          "enum": [
+            "turbopack",
+            "webpack"
+          ]
+        },
+        "adapter": {
+          "type": "string",
+          "enum": [
+            "node",
+            "vercel",
+            "cloudflare",
+            "static"
+          ]
+        }
+      },
+      "required": [
+        "name",
+        "variant"
+      ],
+      "additionalProperties": false
+    },
+    "styling": {
+      "type": "object",
+      "properties": {
+        "engine": {
+          "type": "string",
+          "enum": [
+            "tailwind",
+            "bootstrap",
+            "none"
+          ]
+        }
+      },
+      "required": [
+        "engine"
+      ],
+      "additionalProperties": false
+    },
+    "architecture": {
+      "type": "object",
+      "properties": {
+        "preset": {
+          "type": "string",
+          "enum": [
+            "feature-based",
+            "type-based",
+            "hybrid",
+            "none"
+          ]
+        },
+        "type": {
+          "type": "string",
+          "enum": [
+            "feature-based",
+            "type-based",
+            "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": [
+        "commands"
+      ],
+      "additionalProperties": false
+    },
+    "ui": {
+      "type": "object",
+      "properties": {
+        "kit": {
+          "type": "string",
+          "enum": [
+            "shadcn",
+            "none"
+          ]
+        }
+      },
+      "required": [
+        "kit"
+      ],
+      "additionalProperties": false
+    },
+    "docs": {
+      "type": "object",
+      "properties": {
+        "language": {
+          "type": "string",
+          "enum": [
+            "en",
+            "es"
+          ]
+        }
+      },
+      "required": [
+        "language"
+      ],
+      "additionalProperties": false
+    },
+    "paths": {
+      "type": "object",
+      "properties": {
+        "features": {
+          "type": "string",
+          "minLength": 1
+        },
+        "components": {
+          "type": "string",
+          "minLength": 1
+        },
+        "services": {
+          "type": "string",
+          "minLength": 1
+        },
+        "hooks": {
+          "type": "string",
+          "minLength": 1
+        },
+        "pages": {
+          "type": "string",
+          "minLength": 1
+        },
+        "ui": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "required": [
+        "features",
+        "components",
+        "services",
+        "hooks",
+        "pages",
+        "ui"
+      ],
+      "additionalProperties": false
+    },
+    "tooling": {
+      "type": "object",
+      "properties": {
+        "language": {
+          "type": "string",
+          "enum": [
+            "ts",
+            "js"
+          ]
+        },
+        "linter": {
+          "type": "string",
+          "enum": [
+            "eslint",
+            "oxlint",
+            "biome",
+            "none"
+          ]
+        },
+        "formatter": {
+          "type": "string",
+          "enum": [
+            "prettier",
+            "oxfmt",
+            "none"
+          ]
+        }
+      },
+      "required": [
+        "language",
+        "linter",
+        "formatter"
+      ],
+      "additionalProperties": false
+    },
+    "reactCompiler": {
+      "type": "boolean"
+    },
+    "agentDocs": {
+      "type": "boolean"
+    }
+  },
+  "required": [
+    "manifestVersion",
+    "framework",
+    "styling",
+    "architecture",
+    "ui",
+    "docs",
+    "paths",
+    "tooling"
+  ],
+  "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/`

package/src/agent-context.js

@@ -0,0 +1,114 @@
+import { promises as fsp } from "node:fs";
+import path from "node:path";
+import { buildManifest } from "./manifest/emit.js";
+
+const VALIDATION_NOTES = {
+  strict: "strict: architecture boundaries are enforced — do not import across features except via barrels or shared paths; violations must be fixed.",
+  relaxed: "relaxed: architecture boundaries are advisory — prefer barrels and shared paths, but cross-imports only warn.",
+  none: "none: no architecture validation — paths are still the canonical locations.",
+};
+
+function resolveManifest(manifestOrResponses) {
+  if (manifestOrResponses && typeof manifestOrResponses.manifestVersion !== "undefined") {
+    return manifestOrResponses;
+  }
+  if (manifestOrResponses && manifestOrResponses._manifestSource) {
+    return manifestOrResponses._manifestSource;
+  }
+  return buildManifest(manifestOrResponses);
+}
+
+/**
+ * Render the short agent conventions markdown from a manifest.
+ * Deterministic: derived only from stable manifest fields.
+ * @param {object} manifest - validated manifest v2
+ * @returns {string}
+ */
+export function renderConventions(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 pathLines = Object.entries(paths)
+    .map(([key, value]) => `- ${key}: \`${value}\``)
+    .join("\n");
+
+  const harnessLines = (harness.commands ?? [])
+    .map((c) => `- \`${c.name}\`: \`${c.command}\` (${c.required === false ? "optional" : "required"})`)
+    .join("\n");
+
+  const harnessSummary = (harness.commands ?? []).map((c) => `\`${c.command}\``).join(", ");
+
+  return (
+    `# Lumen Agent Conventions\n` +
+    `\n` +
+    `Generated from \`lumen.config.json\`. Resolve every file location via \`paths.*\` in \`.lumen/architecture.json\` (preset: \`${preset}\`, validation: \`${validation}\`).\n` +
+    `\n` +
+    `## Rules\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` +
+    `\n` +
+    `## Paths\n` +
+    `\n` +
+    `${pathLines}\n` +
+    `\n` +
+    `## Harness\n` +
+    `\n` +
+    `${harnessLines}\n`
+  );
+}
+
+/**
+ * Build the deterministic agent-context payload from a validated manifest v2.
+ * No timestamps — output must be byte-stable.
+ * @param {object} manifest - validated manifest v2
+ * @returns {{ project: object, architecture: object, 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 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).
+ * @param {string} projectPath - absolute path to scaffolded project
+ * @param {object} manifestOrResponses
+ * @returns {Promise<string>} absolute path to the .lumen dir
+ */
+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;
+}