create-lumen 1.2.0 → 2.0.0-alpha.1

package/src/engine/providers/base-provider.js

@@ -0,0 +1,219 @@
+import path from "node:path";
+import {
+  FRAMEWORK_CAPABILITIES,
+  getFrameworkKey,
+} from "../capabilities.js";
+
+/**
+ * Abstract BaseProvider seam (ADR 0001 / create-lumen#25).
+ * Encapsulates framework capabilities, base template file plans,
+ * default package sets, and post-write lifecycle hooks.
+ */
+export class BaseProvider {
+  /**
+   * @param {object} config
+   * @param {string} config.name - framework name (e.g. "react", "next")
+   * @param {string} config.variant - framework variant (e.g. "vite", "app-router", "pages-router")
+   * @param {string[]} [config.capabilities]
+   */
+  constructor({ name, variant, capabilities = [] }) {
+    if (new.target === BaseProvider) {
+      throw new TypeError("Cannot instantiate abstract BaseProvider directly");
+    }
+    this.name = name;
+    this.variant = variant;
+    this.capabilities = new Set(capabilities);
+  }
+
+  /**
+   * Return array of declared capabilities.
+   * @returns {string[]}
+   */
+  getCapabilities() {
+    return Array.from(this.capabilities);
+  }
+
+  /**
+   * Check if provider has a capability.
+   * @param {string} capability
+   * @returns {boolean}
+   */
+  hasCapability(capability) {
+    return this.capabilities.has(capability);
+  }
+
+  /**
+   * Return relative file path pattern to the base template directory.
+   * Pattern: templates/bases/<provider>/<variant>/<lang>/
+   * @param {{ lang?: string }} [opts]
+   * @returns {string}
+   */
+  getFilePlan({ lang = "ts" } = {}) {
+    return path.posix.join("templates", "bases", this.name, this.variant, lang);
+  }
+
+  /**
+   * Return base package dependencies and devDependencies.
+   * @param {object} [_options]
+   * @returns {{ dependencies: Record<string, string>, devDependencies: Record<string, string> }}
+   */
+  getPackageSet(_options = {}) {
+    return {
+      dependencies: {},
+      devDependencies: {},
+    };
+  }
+
+  /**
+   * Return post-write hooks to execute after files are written.
+   * @param {object} [_options]
+   * @returns {Array<{ name: string, run: (context: object) => Promise<void> | void }>}
+   */
+  getPostWriteHooks(_options = {}) {
+    return [];
+  }
+}
+
+/**
+ * React + Vite concrete provider.
+ */
+export class ViteReactProvider extends BaseProvider {
+  constructor() {
+    const desc = FRAMEWORK_CAPABILITIES["react:vite"];
+    super({
+      name: "react",
+      variant: "vite",
+      capabilities: desc.capabilities,
+    });
+  }
+
+  getPackageSet({ options = {} } = {}) {
+    const isTs = options.language === "ts";
+    const deps = {
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
+    };
+    const devDeps = {
+      vite: "^6.0.0",
+      "@vitejs/plugin-react": "^4.3.0",
+    };
+    if (isTs) {
+      devDeps.typescript = "^5.7.0";
+      devDeps["@types/react"] = "^19.0.0";
+      devDeps["@types/react-dom"] = "^19.0.0";
+    }
+    return {
+      dependencies: deps,
+      devDependencies: devDeps,
+    };
+  }
+}
+
+/**
+ * Next.js App Router concrete provider.
+ */
+export class NextAppRouterProvider extends BaseProvider {
+  constructor() {
+    const desc = FRAMEWORK_CAPABILITIES["next:app-router"];
+    super({
+      name: "next",
+      variant: "app-router",
+      capabilities: desc.capabilities,
+    });
+  }
+
+  getPackageSet({ options = {} } = {}) {
+    const isTs = options.language === "ts";
+    const deps = {
+      next: "^15.0.0",
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
+    };
+    const devDeps = {};
+    if (isTs) {
+      devDeps.typescript = "^5.7.0";
+      devDeps["@types/react"] = "^19.0.0";
+      devDeps["@types/react-dom"] = "^19.0.0";
+      devDeps["@types/node"] = "^20.0.0";
+    }
+    return {
+      dependencies: deps,
+      devDependencies: devDeps,
+    };
+  }
+}
+
+/**
+ * Next.js Pages Router concrete provider.
+ */
+export class NextPagesRouterProvider extends BaseProvider {
+  constructor() {
+    const desc = FRAMEWORK_CAPABILITIES["next:pages-router"];
+    super({
+      name: "next",
+      variant: "pages-router",
+      capabilities: desc.capabilities,
+    });
+  }
+
+  getPackageSet({ options = {} } = {}) {
+    const isTs = options.language === "ts";
+    const deps = {
+      next: "^15.0.0",
+      react: "^19.0.0",
+      "react-dom": "^19.0.0",
+    };
+    const devDeps = {};
+    if (isTs) {
+      devDeps.typescript = "^5.7.0";
+      devDeps["@types/react"] = "^19.0.0";
+      devDeps["@types/react-dom"] = "^19.0.0";
+      devDeps["@types/node"] = "^20.0.0";
+    }
+    return {
+      dependencies: deps,
+      devDependencies: devDeps,
+    };
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Provider Registry
+// ---------------------------------------------------------------------------
+const providerRegistry = new Map();
+
+/**
+ * Register a BaseProvider instance in the registry.
+ * @param {BaseProvider} provider
+ */
+export function registerProvider(provider) {
+  if (!(provider instanceof BaseProvider)) {
+    throw new TypeError("provider must be an instance of BaseProvider");
+  }
+  const key = getFrameworkKey(provider.name, provider.variant);
+  providerRegistry.set(key, provider);
+}
+
+/**
+ * Retrieve registered provider by framework name and variant.
+ * @param {string} name
+ * @param {string} variant
+ * @returns {BaseProvider | null}
+ */
+export function getProvider(name, variant) {
+  const key = getFrameworkKey(name, variant);
+  return providerRegistry.get(key) || null;
+}
+
+/**
+ * List all registered providers.
+ * @returns {BaseProvider[]}
+ */
+export function listProviders() {
+  return Array.from(providerRegistry.values());
+}
+
+// Auto-register default providers
+registerProvider(new ViteReactProvider());
+registerProvider(new NextAppRouterProvider());
+registerProvider(new NextPagesRouterProvider());

package/src/injector.js

@@ -118,12 +118,12 @@ export async function injectFormatter(projectPath, templatesDir, responses) {
 
   // Wire eslint-config-prettier only for the eslint + prettier combination
   if (responses.linter === "eslint" && responses.formatter === "prettier") {
-    await wireEslintPrettier(projectPath, responses.language);
+    await wireEslintPrettier(projectPath, responses.language, responses.framework);
   }
 }
 
-async function wireEslintPrettier(projectPath, language) {
-  const ext = language === "ts" ? "ts" : "js";
+async function wireEslintPrettier(projectPath, language, framework) {
+  const ext = framework === "next" ? "mjs" : language === "ts" ? "ts" : "js";
   const eslintConfigPath = path.join(projectPath, `eslint.config.${ext}`);
   try {
     let content = await fsp.readFile(eslintConfigPath, "utf8");
@@ -158,6 +158,11 @@ async function wireEslintPrettier(projectPath, language) {
         /(export default tseslint\.config\([\s\S]*?)(\n\s*\);)/,
         pushLast
       );
+    } else if (result.includes("const eslintConfig = [")) {
+      result = result.replace(
+        /(const eslintConfig = \[[\s\S]*?)(\n\s*\];)/,
+        pushLast
+      );
     } else {
       result = result.replace(
         /(export default \[[\s\S]*?)(\n\s*\];)/,
@@ -238,9 +243,9 @@ export async function injectConditionals(projectPath, templatesDir, responses, a
 
   // 6. Linter
   if (responses.linter === "eslint") {
-    await injectLinter(projectPath, templatesDir, "eslint", language);
+    await injectLinter(projectPath, templatesDir, "eslint", language, responses.framework);
   } else if (responses.linter === "oxlint") {
-    await injectLinter(projectPath, templatesDir, "oxlint", language);
+    await injectLinter(projectPath, templatesDir, "oxlint", language, responses.framework);
   }
 
   // 7. Create feature script (feature-based only)
@@ -254,7 +259,7 @@ export async function injectConditionals(projectPath, templatesDir, responses, a
 }
 
 // Remove .gitkeep placeholders from src/ directories that now contain real
-// files (e.g. component-based `services/.gitkeep` after the axios/fetch client
+// files (e.g. type-based `services/.gitkeep` after the axios/fetch client
 // overlay lands). A folder with nothing but its placeholder keeps it.
 async function pruneRedundantGitkeeps(projectPath) {
   const walk = async (dir) => {
@@ -378,16 +383,24 @@ async function injectTesting(projectPath, templatesDir, framework, language, arc
   } catch {}
 }
 
-async function injectLinter(projectPath, templatesDir, linter, language) {
+export async function injectLinter(projectPath, templatesDir, linter, language, framework) {
   const lintingDir = path.join(templatesDir, "conditional", "linting", linter);
 
   if (linter === "eslint") {
-    const configExt = language === "ts" ? "ts" : "js";
-    const configSrc = path.join(lintingDir, `eslint.config.${configExt}`);
-    try {
-      await fsp.access(configSrc);
-      await fsp.copyFile(configSrc, path.join(projectPath, `eslint.config.${configExt}`));
-    } catch {}
+    if (framework === "next") {
+      const configSrc = path.join(lintingDir, "next", "eslint.config.mjs");
+      try {
+        await fsp.access(configSrc);
+        await fsp.copyFile(configSrc, path.join(projectPath, "eslint.config.mjs"));
+      } catch {}
+    } else {
+      const configExt = language === "ts" ? "ts" : "js";
+      const configSrc = path.join(lintingDir, `eslint.config.${configExt}`);
+      try {
+        await fsp.access(configSrc);
+        await fsp.copyFile(configSrc, path.join(projectPath, `eslint.config.${configExt}`));
+      } catch {}
+    }
   } else if (linter === "oxlint") {
     const configSrc = path.join(lintingDir, "oxlintrc.json");
     try {

package/src/main.js

@@ -16,21 +16,25 @@ import { runBaseInstall, runGitInit, runViteCreate } from "@/scaffold.js";
 import { installAllDeps } from "@/dependencies.js";
 import { generateReadme } from "@/readme.js";
 import { runProjectFormat } from "@/format.js";
+import { emitManifest } from "@/manifest/emit.js";
+import { emitAgentContext } from "@/agent-context.js";
+
+import { parseCliArgs, loadManifestSource, manifestToResponses, PRESETS } from "@/cli-args.js";
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const TEMPLATES_DIR = path.join(__dirname, "../templates");
 const CURRENT_DIR = process.cwd();
 
-export function resolveProjectName({ quickSetup = false, projectName: nameArg, cwd = CURRENT_DIR } = {}) {
-  const cliArgs = (process.argv.slice(2) ?? []).filter((arg) => arg && !arg.startsWith("-"));
-  const cliArg = nameArg || cliArgs[0] || null;
+export function resolveProjectName({ quickSetup = false, projectName: nameArg, cwd = CURRENT_DIR, rawArgs } = {}) {
+  const cli = parseCliArgs(rawArgs || process.argv.slice(2));
+  const cliArg = nameArg || cli.projectName || null;
 
   if (cliArg && cliArg.trim()) {
     return cliArg.trim();
   }
 
-  if (quickSetup) {
+  if (quickSetup || cli.quickSetup || cli.manifest || cli.template) {
     const defaultName = path.basename(cwd).trim() || "my-app";
     return defaultName === "." ? "my-app" : defaultName;
   }
@@ -39,11 +43,22 @@ export function resolveProjectName({ quickSetup = false, projectName: nameArg, c
 }
 
 export async function main(options = {}) {
-  const { quickSetup = false, projectName: nameArg } = options;
+  const {
+    quickSetup = false,
+    projectName: nameArg,
+    manifest: manifestSource,
+    template: templateName,
+  } = options;
   const pkg = getPkgManager();
 
+  const isNonInteractive = Boolean(quickSetup || manifestSource || templateName);
+
   // 1. Project name
-  let projectName = resolveProjectName({ quickSetup, projectName: nameArg, cwd: CURRENT_DIR });
+  let projectName = resolveProjectName({
+    quickSetup: isNonInteractive,
+    projectName: nameArg,
+    cwd: CURRENT_DIR,
+  });
 
   if (projectName) {
     log.step(chalk.gray(`Project name: ${chalk.bold(projectName)}`));
@@ -61,8 +76,25 @@ export async function main(options = {}) {
   // 2. Handle existing folder
   await confirmEmptyFolder(projectName);
 
-  // 3. Collect user preferences
-  const responses = await getUserInputs(projectName, { quickSetup });
+  // 3. Collect user preferences (interactive or non-interactive)
+  let responses;
+  if (manifestSource) {
+    const manifestObj = loadManifestSource(manifestSource, CURRENT_DIR);
+    responses = manifestToResponses(manifestObj, projectName);
+  } else if (templateName) {
+    const preset = PRESETS[templateName];
+    if (!preset) {
+      throw new Error(
+        `Unknown template preset "${templateName}". Available presets: ${Object.keys(PRESETS).join(", ")}`
+      );
+    }
+    responses = {
+      projectName,
+      ...preset,
+    };
+  } else {
+    responses = await getUserInputs(projectName, { quickSetup });
+  }
 
   const projectPath = path.resolve(CURRENT_DIR, projectName);
 
@@ -104,7 +136,7 @@ export async function main(options = {}) {
   // 7. Inject architecture templates
   const archSpin = spinner();
   archSpin.start(
-    `Setting up ${responses.architecture === "feature-based" ? "feature-based" : "component-based"} architecture...`
+    `Setting up ${responses.architecture === "feature-based" ? "feature-based" : "type-based"} architecture...`
   );
   try {
     await injectArchitecture(
@@ -205,6 +237,30 @@ export async function main(options = {}) {
   // 12.5 Copy .env.example into the project
   await copyEnvExample(projectPath, TEMPLATES_DIR);
 
+  // 12.6 Emit lumen.config.json (manifest v2) — byte-deterministic, Zod-validated
+  const manifestSpin = spinner();
+  manifestSpin.start("Writing lumen.config.json...");
+  try {
+    await emitManifest(projectPath, responses);
+    manifestSpin.stop(chalk.green("lumen.config.json written."));
+  } catch (err) {
+    manifestSpin.stop(chalk.red("Failed to write lumen.config.json."));
+    throw err;
+  }
+
+  // 12.7 Emit .lumen agent context dir (only when agentDocs is enabled)
+  if (responses.agentDocs === true || responses._manifestSource?.agentDocs === true) {
+    const agentSpin = spinner();
+    agentSpin.start("Writing .lumen agent context...");
+    try {
+      await emitAgentContext(projectPath, responses._manifestSource ?? responses);
+      agentSpin.stop(chalk.green(".lumen agent context written."));
+    } catch (err) {
+      agentSpin.stop(chalk.red("Failed to write .lumen agent context."));
+      throw err;
+    }
+  }
+
   // 13. Generate README.md + LICENSE (if requested)
   if (responses.readme) {
     const readmeSpin = spinner();
@@ -234,7 +290,7 @@ export async function main(options = {}) {
   log.step(chalk.green("\nProject setup complete!"));
   log.message(
     chalk.gray(
-      `  Architecture: ${responses.architecture === "feature-based" ? "Feature-based" : "Component-based"}`
+      `  Architecture: ${responses.architecture === "feature-based" ? "Feature-based" : "Type-based"}`
     )
   );
 

package/src/manifest/emit.js

@@ -0,0 +1,166 @@
+import { promises as fsp } from "fs";
+import path from "path";
+import { parseManifest, SCHEMA_URL, MANIFEST_VERSION, HARNESS_DEFAULT_COMMANDS } from "./schema.js";
+import { resolvePaths } from "./paths.js";
+
+const LINT_COMMANDS = {
+  eslint: "eslint .",
+  oxlint: "oxlint .",
+  biome: "biome check .",
+};
+
+const FORMAT_COMMANDS = {
+  prettier: "prettier --check .",
+  oxfmt: "oxfmt --check .",
+};
+
+/**
+ * Build default harness commands from tooling choices.
+ * Skips lint/format when tooling is "none"; skips types when language is not "ts".
+ * Test + build are always included so commands.length >= 1.
+ * @param {{ linter?: string, formatter?: string, language?: string }} tooling
+ * @returns {Array<{ name: string, command: string, required: boolean }>}
+ */
+export function defaultHarnessCommands(tooling = {}) {
+  const { linter = "none", formatter = "none", language = "ts" } = tooling;
+  const commands = [];
+  if (linter && linter !== "none" && LINT_COMMANDS[linter]) {
+    commands.push({ name: "lint", command: LINT_COMMANDS[linter], required: true });
+  }
+  if (formatter && formatter !== "none" && FORMAT_COMMANDS[formatter]) {
+    commands.push({ name: "format", command: FORMAT_COMMANDS[formatter], required: true });
+  }
+  if (language === "ts") {
+    commands.push({ name: "types", command: "tsc -b", required: true });
+  }
+  commands.push({ name: "test", command: "vitest run", required: true });
+  commands.push({ name: "build", command: "npm run build", required: true });
+  return commands.length > 0 ? commands : [...HARNESS_DEFAULT_COMMANDS];
+}
+
+/**
+ * Build an ordered manifest v2 object from scaffolder responses.
+ * Stable key ordering for byte-determinism.
+ * @param {object} responses - result from getUserInputs (includes docsLanguage, cssFramework, etc.)
+ * @param {object} [opts]
+ * @param {string} [opts.frameworkName] - default "react"
+ * @param {string} [opts.frameworkVariant] - default "vite" or derived from framework
+ * @returns {object} ordered manifest object ready to JSON.stringify
+ */
+export function buildManifest(responses, opts = {}) {
+  if (responses.rawManifest) {
+    return parseManifest(responses.rawManifest);
+  }
+
+  const frameworkName = opts.frameworkName || responses.frameworkName || "react";
+  const frameworkVariant =
+    opts.frameworkVariant ||
+    responses.frameworkVariant ||
+    (frameworkName === "next" ? "app-router" : "vite");
+
+  const framework = {
+    name: frameworkName,
+    variant: frameworkVariant,
+  };
+  // Include optional axes only if present in responses (future overlays)
+  if (responses.bundler) framework.bundler = responses.bundler;
+  if (responses.adapter) framework.adapter = responses.adapter;
+
+  const styling = {
+    engine: responses.cssFramework || "tailwind",
+  };
+
+  const rawArch =
+    responses.architecturePreset || responses.architecture || "feature-based";
+  const normalizedArch = rawArch === "component-based" ? "type-based" : rawArch;
+  const architecture = {
+    preset: normalizedArch,
+    type: normalizedArch,
+    validation:
+      responses.architectureValidation || responses.validation || "strict",
+  };
+
+  const ui = {
+    kit: responses.uiKit || responses.ui || "none",
+  };
+
+  const docs = {
+    language: responses.docsLanguage || "en",
+  };
+
+  const paths = resolvePaths({
+    architecture: architecture.type,
+    framework,
+  });
+
+  const tooling = {
+    language: responses.language || "ts",
+    linter: responses.linter || "none",
+    formatter: responses.formatter || "none",
+  };
+
+  const harness = responses.harness ?? {
+    commands: defaultHarnessCommands(tooling),
+  };
+
+  const manifest = {
+    $schema: SCHEMA_URL,
+    manifestVersion: MANIFEST_VERSION,
+    framework,
+    styling,
+    architecture,
+    harness,
+    ui,
+    docs,
+    paths,
+    tooling,
+  };
+
+  // Optional cross-cutting flags — only include if explicitly set (keeps minimal manifest byte-stable)
+  if (typeof responses.reactCompiler === "boolean") manifest.reactCompiler = responses.reactCompiler;
+  if (typeof responses.agentDocs === "boolean") manifest.agentDocs = responses.agentDocs;
+
+  // Enforce stable top-level key order for determinism (like formatter pass)
+  const ordered = {};
+  const topOrder = [
+    "$schema",
+    "manifestVersion",
+    "framework",
+    "styling",
+    "architecture",
+    "harness",
+    "ui",
+    "docs",
+    "paths",
+    "tooling",
+    "reactCompiler",
+    "agentDocs",
+  ];
+  for (const k of topOrder) {
+    if (k in manifest) ordered[k] = manifest[k];
+  }
+  // Include any extra keys not in order (should be none, but for forward compat)
+  for (const k of Object.keys(manifest)) {
+    if (!(k in ordered)) ordered[k] = manifest[k];
+  }
+
+  // Validate via Zod before returning (throws with user-friendly message on invalid)
+  // Use parse to apply defaults ($schema) and ensure strictness
+  return parseManifest(ordered);
+}
+
+/**
+ * Emit lumen.config.json to projectPath.
+ * Validates via Zod, writes with 2-space indent + trailing newline.
+ * @param {string} projectPath - absolute path to scaffolded project
+ * @param {object} responses
+ * @param {object} [opts] - same as buildManifest opts
+ * @returns {Promise<string>} absolute path to written file
+ */
+export async function emitManifest(projectPath, responses, opts = {}) {
+  const manifest = responses._manifestSource || buildManifest(responses, opts);
+  const outPath = path.join(projectPath, "lumen.config.json");
+  const content = JSON.stringify(manifest, null, 2) + "\n";
+  await fsp.writeFile(outPath, content, "utf8");
+  return outPath;
+}

package/src/manifest/index.js

@@ -0,0 +1,11 @@
+export {
+  manifestSchemaV2,
+  parseManifest,
+  isV1Manifest,
+  formatZodError,
+  MANIFEST_VERSION,
+  SCHEMA_URL,
+} from "./schema.js";
+
+export { resolvePaths, PATH_KEYS } from "./paths.js";
+export { buildManifest, emitManifest } from "./emit.js";