create-lumen 1.2.0-beta.1 → 2.0.0-alpha.0

package/src/cli-args.js

@@ -0,0 +1,294 @@
+import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import chalk from "chalk";
+import { parseManifest } from "./manifest/schema.js";
+
+export const PRESETS = {
+  "react-ts": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "feature-based",
+    language: "ts",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-vite-ts": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "feature-based",
+    language: "ts",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-js": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "feature-based",
+    language: "js",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-vite-js": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "feature-based",
+    language: "js",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-type-ts": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "type-based",
+    language: "ts",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-type-js": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "type-based",
+    language: "js",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-component-ts": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "type-based",
+    language: "ts",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+  "react-component-js": {
+    frameworkName: "react",
+    frameworkVariant: "vite",
+    architecture: "type-based",
+    language: "js",
+    cssFramework: "tailwind",
+    testing: "vitest",
+    router: true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    linter: "eslint",
+    formatter: "prettier",
+    docsLanguage: "en",
+    gitInit: true,
+    readme: true,
+  },
+};
+
+/**
+ * Parse CLI arguments using standard node:util parseArgs.
+ * @param {string[]} [argv]
+ * @returns {{
+ *   projectName: string | null,
+ *   quickSetup: boolean,
+ *   manifest: string | null,
+ *   template: string | null,
+ *   help: boolean,
+ *   version: boolean,
+ *   positionals: string[]
+ * }}
+ */
+export function parseCliArgs(argv = process.argv.slice(2)) {
+  const { values, positionals } = parseArgs({
+    args: argv,
+    options: {
+      yes: { type: "boolean", short: "y", default: false },
+      manifest: { type: "string", short: "m" },
+      template: { type: "string", short: "t" },
+      help: { type: "boolean", short: "h", default: false },
+      version: { type: "boolean", short: "v", default: false },
+    },
+    allowPositionals: true,
+    strict: false,
+  });
+
+  const projectName = positionals[0] ? positionals[0].trim() : null;
+
+  return {
+    projectName,
+    quickSetup: Boolean(values.yes),
+    manifest: values.manifest || null,
+    template: values.template || null,
+    help: Boolean(values.help),
+    version: Boolean(values.version),
+    positionals,
+  };
+}
+
+/**
+ * Load and validate a manifest from a file path or raw inline JSON string.
+ * @param {string} source - file path or inline JSON
+ * @param {string} [cwd=process.cwd()]
+ * @returns {object} validated manifest v2 object
+ */
+export function loadManifestSource(source, cwd = process.cwd()) {
+  const trimmed = source.trim();
+  let parsed;
+
+  if (trimmed.startsWith("{") && trimmed.endsWith("}")) {
+    try {
+      parsed = JSON.parse(trimmed);
+    } catch (err) {
+      throw new Error(`Failed to parse inline manifest JSON: ${err.message}`, { cause: err });
+    }
+  } else {
+    const filePath = path.isAbsolute(trimmed) ? trimmed : path.resolve(cwd, trimmed);
+    try {
+      const content = readFileSync(filePath, "utf8");
+      parsed = JSON.parse(content);
+    } catch (err) {
+      throw new Error(`Failed to read manifest file "${filePath}": ${err.message}`, { cause: err });
+    }
+  }
+
+  // Validate strictly against schema v2; throws if v1 or invalid
+  return parseManifest(parsed);
+}
+
+/**
+ * Map a validated v2 manifest into scaffolder response options.
+ * @param {object} manifest - validated manifest v2
+ * @param {string} projectName
+ * @returns {object} scaffolder response set
+ */
+export function manifestToResponses(manifest, projectName) {
+  const frameworkName = manifest.framework?.name || "react";
+  const frameworkVariant = manifest.framework?.variant || "vite";
+  const isNext = frameworkName === "next";
+
+  return {
+    projectName,
+    frameworkName,
+    frameworkVariant,
+    bundler: manifest.framework?.bundler,
+    adapter: manifest.framework?.adapter,
+    architecture: manifest.architecture?.type || "feature-based",
+    language: manifest.tooling?.language || "ts",
+    cssFramework: manifest.styling?.engine || "tailwind",
+    linter: manifest.tooling?.linter || "eslint",
+    formatter: manifest.tooling?.formatter || "prettier",
+    uiKit: manifest.ui?.kit || "none",
+    docsLanguage: manifest.docs?.language || "en",
+    reactCompiler: manifest.reactCompiler,
+    agentDocs: manifest.agentDocs,
+    // Sensible defaults for scaffolder conditional passes
+    testing: "vitest",
+    router: isNext ? false : true,
+    stateManagement: "none",
+    iconLibrary: "none",
+    apiClient: "none",
+    gitInit: true,
+    readme: true,
+    _manifestSource: manifest,
+  };
+}
+
+/**
+ * Print styled CLI help message.
+ */
+export function printHelp() {
+  console.log(`
+${chalk.bold.cyan("  create-lumen")} — Scaffold a React + Vite project with architecture choice
+
+${chalk.bold("USAGE")}
+  ${chalk.green("$")} ${chalk.bold("create-lumen")} [project-name] [options]
+
+${chalk.bold("OPTIONS")}
+  ${chalk.yellow("-y, --yes")}              Quick setup with recommended defaults (TS + Tailwind + Router + ESLint + Prettier)
+  ${chalk.yellow("-m, --manifest")} <path>  Drive scaffolding from a lumen.config.json or inline JSON
+  ${chalk.yellow("-t, --template")} <name>  Scaffold using a preset (${Object.keys(PRESETS).join(", ")})
+  ${chalk.yellow("-h, --help")}             Show this help message
+  ${chalk.yellow("-v, --version")}          Show version number
+
+${chalk.bold("PRESETS")}
+  ${chalk.cyan("react-ts")}       React + Vite + TypeScript (feature-based)
+  ${chalk.cyan("react-js")}       React + Vite + JavaScript (feature-based)
+  ${chalk.cyan("react-type-ts")}  React + Vite + TypeScript (type-based)
+  ${chalk.cyan("react-type-js")}  React + Vite + JavaScript (type-based)
+
+${chalk.bold("EXAMPLES")}
+  ${chalk.gray("# Interactive setup")}
+  ${chalk.green("$")} create-lumen my-app
+
+  ${chalk.gray("# Non-interactive quick setup")}
+  ${chalk.green("$")} create-lumen my-app -y
+  ${chalk.green("$")} create-lumen -y my-app
+
+  ${chalk.gray("# Scaffold from a template preset")}
+  ${chalk.green("$")} create-lumen my-app --template react-ts
+
+  ${chalk.gray("# Scaffold from a manifest file")}
+  ${chalk.green("$")} create-lumen my-app --manifest ./lumen.config.json
+
+  ${chalk.gray("# Scaffold from inline JSON manifest")}
+  ${chalk.green("$")} create-lumen my-app -m '{"manifestVersion":2,"framework":{"name":"react","variant":"vite"},...}'
+`);
+}

package/src/css.js

@@ -9,12 +9,13 @@ export async function setupCssFramework({
   cssFramework,
   architecture,
   ext,
-  pkg,
+  pkg: _pkg,
+  framework = "vite",
 }) {
   process.chdir(projectPath);
   const cssDir = path.join(templatesDir, "css");
   // Feature-based main.* imports ./shared/styles/globals.css (or main.css when
-  // framework is "none"); component-based imports ./styles/globals.css (or
+  // framework is "none"); type-based imports ./styles/globals.css (or
   // main.css). The chosen framework's styles land in the file the architecture
   // actually imports.
   const stylesDir =
@@ -31,13 +32,23 @@ export async function setupCssFramework({
   }
 
   if (cssFramework === "tailwind") {
-    const viteConfigFile = `vite.config.${language === "ts" ? "ts" : "js"}`;
-    const viteConfigTarget = path.join(projectPath, viteConfigFile);
-    const viteConfigContent = await fsp.readFile(
-      path.join(cssDir, "tailwind", viteConfigFile),
-      "utf8"
-    );
-    await fsp.writeFile(viteConfigTarget, viteConfigContent, "utf8");
+    if (framework === "next") {
+      const postcssConfigFile = "postcss.config.mjs";
+      const postcssConfigTarget = path.join(projectPath, postcssConfigFile);
+      const postcssConfigContent = await fsp.readFile(
+        path.join(cssDir, "tailwind", postcssConfigFile),
+        "utf8"
+      );
+      await fsp.writeFile(postcssConfigTarget, postcssConfigContent, "utf8");
+    } else {
+      const viteConfigFile = `vite.config.${language === "ts" ? "ts" : "js"}`;
+      const viteConfigTarget = path.join(projectPath, viteConfigFile);
+      const viteConfigContent = await fsp.readFile(
+        path.join(cssDir, "tailwind", viteConfigFile),
+        "utf8"
+      );
+      await fsp.writeFile(viteConfigTarget, viteConfigContent, "utf8");
+    }
 
     const globalsContent = await fsp.readFile(
       path.join(cssDir, "tailwind", "src", "globals.css"),

package/src/dependencies.js

@@ -25,12 +25,30 @@ export async function installDeps(pkgManager, dev, packages, cwd) {
 }
 
 export async function installAllDeps(responses, pkg, cwd) {
+  const { deps, devDeps } = computeDeps(responses);
+
+  if (deps.length > 0) {
+    await installDeps(pkg, false, deps, cwd);
+  }
+  if (devDeps.length > 0) {
+    await installDeps(pkg, true, devDeps, cwd);
+  }
+}
+
+// Pure dependency computation — the package list for a given matrix cell,
+// independent of any package manager or filesystem. Unit-tested directly so
+// the conditional wiring stays verifiable without a network install.
+export function computeDeps(responses) {
   const deps = [];
   const devDeps = [];
 
   // CSS framework
   if (responses.cssFramework === "tailwind") {
-    devDeps.push("tailwindcss", "@tailwindcss/vite");
+    if (responses.framework === "next") {
+      devDeps.push("tailwindcss", "@tailwindcss/postcss", "postcss");
+    } else {
+      devDeps.push("tailwindcss", "@tailwindcss/vite");
+    }
     deps.push("clsx", "tailwind-merge");
   } else if (responses.cssFramework === "bootstrap") {
     deps.push("bootstrap", "react-bootstrap");
@@ -84,11 +102,13 @@ export async function installAllDeps(responses, pkg, cwd) {
 
   // Linter
   if (responses.linter === "eslint") {
-    devDeps.push("eslint", "@eslint/js", "eslint-plugin-react-hooks", "eslint-plugin-react-refresh", "globals");
-    if (responses.language === "ts") {
-      devDeps.push("typescript-eslint");
-      // ESLint >= 10 loads TS config files (eslint.config.ts) via jiti.
-      devDeps.push("jiti");
+    if (responses.framework === "next") {
+      devDeps.push("eslint", "eslint-config-next");
+    } else {
+      devDeps.push("eslint", "@eslint/js", "eslint-plugin-react-hooks", "eslint-plugin-react-refresh", "globals");
+      if (responses.language === "ts") {
+        devDeps.push("typescript-eslint", "jiti");
+      }
     }
   } else if (responses.linter === "oxlint") {
     devDeps.push("oxlint");
@@ -107,10 +127,5 @@ export async function installAllDeps(responses, pkg, cwd) {
   // Always re-install react + react-dom for consistency
   deps.push("react", "react-dom");
 
-  if (deps.length > 0) {
-    await installDeps(pkg, false, deps, cwd);
-  }
-  if (devDeps.length > 0) {
-    await installDeps(pkg, true, devDeps, cwd);
-  }
+  return { deps, devDeps };
 }

package/src/engine/capabilities.js

@@ -0,0 +1,218 @@
+/**
+ * Capability declaration model for create-lumen v2 generator engine.
+ * Decouples option compatibility from hardcoded generator checks.
+ * Covered under create-lumen#25 (ADR 0001).
+ */
+
+export const CAPABILITIES = {
+  CLIENT_ROUTING: "client-routing",
+  FILESYSTEM_ROUTING: "filesystem-routing",
+  SERVER_COMPONENTS: "server-components",
+  CLIENT_COMPONENTS: "client-components",
+  ROUTE_HANDLERS: "route-handlers",
+  API_ROUTES: "api-routes",
+  ADAPTERS: "adapters",
+  BUNDLER_SELECTION: "bundler-selection",
+  REACT_COMPILER: "react-compiler",
+  NEXT_FONT: "next-font",
+  NEXT_IMAGE: "next-image",
+  SPA_FALLBACK: "spa-fallback",
+  AGENT_DOCS: "agent-docs",
+};
+
+export const FRAMEWORK_CAPABILITIES = {
+  "react:vite": {
+    framework: { name: "react", variant: "vite" },
+    capabilities: [
+      CAPABILITIES.CLIENT_ROUTING,
+      CAPABILITIES.CLIENT_COMPONENTS,
+      CAPABILITIES.SPA_FALLBACK,
+      CAPABILITIES.AGENT_DOCS,
+    ],
+    allowedArchitectures: ["feature-based", "type-based", "none"],
+    allowedStyling: ["tailwind", "bootstrap", "none"],
+    allowedUiKits: ["shadcn", "none"],
+    allowedLanguages: ["ts", "js"],
+    allowedLinters: ["eslint", "oxlint", "biome", "none"],
+    allowedFormatters: ["prettier", "oxfmt", "none"],
+    allowedBundlers: [],
+    allowedAdapters: [],
+    supportsRouterPrompt: true,
+  },
+  "next:app-router": {
+    framework: { name: "next", variant: "app-router" },
+    capabilities: [
+      CAPABILITIES.FILESYSTEM_ROUTING,
+      CAPABILITIES.SERVER_COMPONENTS,
+      CAPABILITIES.CLIENT_COMPONENTS,
+      CAPABILITIES.ROUTE_HANDLERS,
+      CAPABILITIES.ADAPTERS,
+      CAPABILITIES.BUNDLER_SELECTION,
+      CAPABILITIES.REACT_COMPILER,
+      CAPABILITIES.NEXT_FONT,
+      CAPABILITIES.NEXT_IMAGE,
+      CAPABILITIES.AGENT_DOCS,
+    ],
+    allowedArchitectures: ["feature-based", "hybrid", "none"],
+    allowedStyling: ["tailwind", "none"],
+    allowedUiKits: ["shadcn", "none"],
+    allowedLanguages: ["ts", "js"],
+    allowedLinters: ["eslint", "biome", "none"],
+    allowedFormatters: ["prettier", "none"],
+    allowedBundlers: ["turbopack", "webpack"],
+    allowedAdapters: ["node", "vercel", "cloudflare", "static"],
+    supportsRouterPrompt: false, // filesystem routing is built-in
+  },
+  "next:pages-router": {
+    framework: { name: "next", variant: "pages-router" },
+    capabilities: [
+      CAPABILITIES.FILESYSTEM_ROUTING,
+      CAPABILITIES.CLIENT_COMPONENTS,
+      CAPABILITIES.API_ROUTES,
+      CAPABILITIES.ADAPTERS,
+      CAPABILITIES.BUNDLER_SELECTION,
+      CAPABILITIES.NEXT_FONT,
+      CAPABILITIES.NEXT_IMAGE,
+      CAPABILITIES.AGENT_DOCS,
+    ],
+    allowedArchitectures: ["feature-based", "hybrid", "none"],
+    allowedStyling: ["tailwind", "bootstrap", "none"],
+    allowedUiKits: ["shadcn", "none"],
+    allowedLanguages: ["ts", "js"],
+    allowedLinters: ["eslint", "biome", "none"],
+    allowedFormatters: ["prettier", "none"],
+    allowedBundlers: ["turbopack", "webpack"],
+    allowedAdapters: ["node", "vercel", "cloudflare", "static"],
+    supportsRouterPrompt: false, // filesystem routing is built-in
+  },
+};
+
+/**
+ * Get canonical framework lookup key.
+ * @param {string} name
+ * @param {string} variant
+ * @returns {string}
+ */
+export function getFrameworkKey(name, variant) {
+  return `${name}:${variant}`;
+}
+
+/**
+ * Retrieve capability descriptor for a framework/variant pair.
+ * @param {{ name: string, variant: string }} framework
+ * @returns {object | null}
+ */
+export function getFrameworkDescriptor(framework) {
+  if (!framework || !framework.name || !framework.variant) return null;
+  const key = getFrameworkKey(framework.name, framework.variant);
+  return FRAMEWORK_CAPABILITIES[key] || null;
+}
+
+/**
+ * Check if a framework has a declared capability.
+ * @param {{ name: string, variant: string }} framework
+ * @param {string} capability
+ * @returns {boolean}
+ */
+export function hasCapability(framework, capability) {
+  const desc = getFrameworkDescriptor(framework);
+  if (!desc) return false;
+  return desc.capabilities.includes(capability);
+}
+
+/**
+ * Check whether an option value is compatible with the framework's capabilities.
+ * @param {{ name: string, variant: string }} framework
+ * @param {string} optionKey
+ * @param {*} optionValue
+ * @returns {boolean}
+ */
+export function isOptionCompatible(framework, optionKey, optionValue) {
+  const desc = getFrameworkDescriptor(framework);
+  if (!desc) return false;
+
+  switch (optionKey) {
+    case "architecture":
+      return desc.allowedArchitectures.includes(optionValue);
+    case "styling":
+    case "cssFramework":
+      return desc.allowedStyling.includes(optionValue);
+    case "uiKit":
+    case "ui":
+      return desc.allowedUiKits.includes(optionValue);
+    case "language":
+      return desc.allowedLanguages.includes(optionValue);
+    case "linter":
+      return desc.allowedLinters.includes(optionValue);
+    case "formatter":
+      return desc.allowedFormatters.includes(optionValue);
+    case "bundler":
+      return desc.allowedBundlers.includes(optionValue);
+    case "adapter":
+      return desc.allowedAdapters.includes(optionValue);
+    case "router":
+      // If framework has filesystem routing, external router options (true) are incompatible
+      if (hasCapability(framework, CAPABILITIES.FILESYSTEM_ROUTING)) {
+        return optionValue === false || optionValue === "none";
+      }
+      return true;
+    default:
+      return true;
+  }
+}
+
+/**
+ * Return all compatible option domains for a framework.
+ * @param {{ name: string, variant: string }} framework
+ * @returns {object | null}
+ */
+export function getCompatibleOptions(framework) {
+  const desc = getFrameworkDescriptor(framework);
+  if (!desc) return null;
+
+  return {
+    capabilities: [...desc.capabilities],
+    architectures: [...desc.allowedArchitectures],
+    styling: [...desc.allowedStyling],
+    uiKits: [...desc.allowedUiKits],
+    languages: [...desc.allowedLanguages],
+    linters: [...desc.allowedLinters],
+    formatters: [...desc.allowedFormatters],
+    bundlers: [...desc.allowedBundlers],
+    adapters: [...desc.allowedAdapters],
+    supportsRouterPrompt: desc.supportsRouterPrompt,
+  };
+}
+
+/**
+ * Validate a set of options against framework capabilities.
+ * Returns { valid: true } or { valid: false, errors: string[] }
+ * @param {{ name: string, variant: string }} framework
+ * @param {object} options
+ * @returns {{ valid: boolean, errors: string[] }}
+ */
+export function validateCompatibility(framework, options = {}) {
+  const desc = getFrameworkDescriptor(framework);
+  if (!desc) {
+    return {
+      valid: false,
+      errors: [`Unsupported framework "${framework?.name}:${framework?.variant}"`],
+    };
+  }
+
+  const errors = [];
+
+  for (const [key, val] of Object.entries(options)) {
+    if (val === undefined || val === null) continue;
+    if (!isOptionCompatible(framework, key, val)) {
+      errors.push(
+        `Option "${key}" with value "${val}" is incompatible with framework "${framework.name}:${framework.variant}"`
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}

package/src/engine/index.js

@@ -0,0 +1,2 @@
+export * from "./capabilities.js";
+export * from "./providers/base-provider.js";