create-lumen 1.2.0 → 2.0.0-alpha.0

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,24 @@ 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 { 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 +42,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 +75,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 +135,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 +236,17 @@ 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;
+  }
+
   // 13. Generate README.md + LICENSE (if requested)
   if (responses.readme) {
     const readmeSpin = spinner();
@@ -234,7 +276,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,120 @@
+import { promises as fsp } from "fs";
+import path from "path";
+import { parseManifest, SCHEMA_URL, MANIFEST_VERSION } from "./schema.js";
+import { resolvePaths } from "./paths.js";
+
+/**
+ * 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.architecture || "feature-based";
+  const architecture = {
+    type: rawArch === "component-based" ? "type-based" : rawArch,
+  };
+
+  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 manifest = {
+    $schema: SCHEMA_URL,
+    manifestVersion: MANIFEST_VERSION,
+    framework,
+    styling,
+    architecture,
+    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",
+    "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";

package/src/manifest/paths.js

@@ -0,0 +1,128 @@
+/**
+ * Path mapping for lumen.config.json — #15
+ * Resolves the 6 generator target directories from framework + architecture.
+ * Paths are relative to project root and use posix separators.
+ */
+
+export const PATH_KEYS = ["features", "components", "services", "hooks", "pages", "ui"];
+
+/**
+ * @param {{ architecture: string, framework?: { name?: string, variant?: string } }} opts
+ * @returns {{ features: string, components: string, services: string, hooks: string, pages: string, ui: string }}
+ */
+export function resolvePaths({ architecture, framework = {} } = {}) {
+  const arch = architecture || "feature-based";
+  const fwName = framework.name || "react";
+  const variant = framework.variant || (fwName === "next" ? "app-router" : "vite");
+
+  // Helper to pick Next.js pages root based on variant
+  const nextPagesForVariant = (v) => (v === "pages-router" ? "pages" : "app");
+  const isNext = fwName === "next";
+
+  // -- feature-based (React + Vite canonical, also Next feature-based)
+  if (arch === "feature-based") {
+    if (isNext) {
+      const nextRoot = nextPagesForVariant(variant);
+      // Next keeps features in src/features, shared code in src/shared, routing in app/ or pages/
+      // Use posix paths regardless of OS
+      return {
+        features: "src/features",
+        components: "src/shared/components",
+        services: "src/shared/services",
+        hooks: "src/shared/hooks",
+        pages: nextRoot, // app/ or pages/ at project root for Next
+        ui: "src/shared/components/ui",
+      };
+    }
+    return {
+      features: "src/features",
+      components: "src/shared/components",
+      services: "src/shared/services",
+      hooks: "src/shared/hooks",
+      pages: "src/app/router",
+      ui: "src/shared/components/ui",
+    };
+  }
+
+  // -- type-based (React + Vite only; component-based supported as legacy alias)
+  if (arch === "type-based" || arch === "component-based") {
+    if (isNext) {
+      // Not a valid combo per schema, but provide a deterministic fallback
+      // to keep resolver total (hybrid should be used for Next)
+      const nextRoot = nextPagesForVariant(variant);
+      return {
+        features: "src/components",
+        components: "src/components",
+        services: "src/services",
+        hooks: "src/hooks",
+        pages: nextRoot,
+        ui: "src/components/ui",
+      };
+    }
+    return {
+      features: "src/features",
+      components: "src/components",
+      services: "src/services",
+      hooks: "src/hooks",
+      pages: "src/pages",
+      ui: "src/ui",
+    };
+  }
+
+  // -- hybrid (Next.js: feature + shared). For React, fallback to feature-based
+  if (arch === "hybrid") {
+    if (isNext) {
+      const nextRoot = nextPagesForVariant(variant);
+      return {
+        features: "src/features",
+        components: "src/shared/components",
+        services: "src/shared/services",
+        hooks: "src/shared/hooks",
+        pages: nextRoot,
+        ui: "src/shared/components/ui",
+      };
+    }
+    // React hybrid = hybrid not valid, but map to feature-based for determinism
+    return {
+      features: "src/features",
+      components: "src/shared/components",
+      services: "src/shared/services",
+      hooks: "src/shared/hooks",
+      pages: "src/app/router",
+      ui: "src/shared/components/ui",
+    };
+  }
+
+  // -- none (minimal flat src/ — no imposed convention)
+  if (arch === "none") {
+    if (isNext) {
+      const nextRoot = nextPagesForVariant(variant);
+      return {
+        features: "src",
+        components: "src/components",
+        services: "src/services",
+        hooks: "src/hooks",
+        pages: nextRoot,
+        ui: "src/components/ui",
+      };
+    }
+    return {
+      features: "src",
+      components: "src/components",
+      services: "src/services",
+      hooks: "src/hooks",
+      pages: "src/pages",
+      ui: "src/components/ui",
+    };
+  }
+
+  // Fallback: treat unknown as feature-based
+  return {
+    features: "src/features",
+    components: "src/shared/components",
+    services: "src/shared/services",
+    hooks: "src/shared/hooks",
+    pages: isNext ? nextPagesForVariant(variant) : "src/app/router",
+    ui: "src/shared/components/ui",
+  };
+}