create-lumen 1.2.0 → 2.0.0-alpha.1

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",
+  };
+}

package/src/manifest/schema.js

@@ -0,0 +1,270 @@
+import { z } from "zod";
+import { fromZodError } from "zod-validation-error";
+
+// ---------------------------------------------------------------------------
+// Constants - keep in sync with docs/manifest-v2.md and ROADMAP
+// ---------------------------------------------------------------------------
+export const MANIFEST_VERSION = 2;
+export const SCHEMA_URL = "https://lumen-sh.github.io/create-lumen/schema/lumen.config.v2.json";
+
+export const FRAMEWORK_NAMES = ["react", "next"];
+export const FRAMEWORK_VARIANTS = ["vite", "app-router", "pages-router"];
+export const FRAMEWORK_BUNDLERS = ["turbopack", "webpack"];
+export const FRAMEWORK_ADAPTERS = ["node", "vercel", "cloudflare", "static"];
+
+export const STYLING_ENGINES = ["tailwind", "bootstrap", "none"];
+export const ARCHITECTURE_PRESETS = ["feature-based", "type-based", "hybrid", "none"];
+// Legacy alias: docs used architecture.type, canonical is architecture.preset.
+// Keep both in sync; parseManifest normalizes to expose both keys.
+export const ARCHITECTURE_TYPES = ARCHITECTURE_PRESETS;
+export const ARCHITECTURE_VALIDATIONS = ["strict", "relaxed", "none"];
+export const UI_KITS = ["shadcn", "none"];
+export const DOCS_LANGUAGES = ["en", "es"];
+export const TOOLING_LANGUAGES = ["ts", "js"];
+export const TOOLING_LINTERS = ["eslint", "oxlint", "biome", "none"];
+export const TOOLING_FORMATTERS = ["prettier", "oxfmt", "none"];
+
+// ---------------------------------------------------------------------------
+// Sub-schemas
+// ---------------------------------------------------------------------------
+const frameworkSchema = z
+  .object({
+    name: z.enum(FRAMEWORK_NAMES),
+    variant: z.enum(FRAMEWORK_VARIANTS),
+    bundler: z.enum(FRAMEWORK_BUNDLERS).optional(),
+    adapter: z.enum(FRAMEWORK_ADAPTERS).optional(),
+  })
+  .strict();
+
+const stylingSchema = z
+  .object({
+    engine: z.enum(STYLING_ENGINES),
+  })
+  .strict();
+
+const architectureSchema = z
+  .object({
+    // Canonical key per docs/manifest-v2.md; legacy `type` kept as alias.
+    preset: z.enum(ARCHITECTURE_PRESETS).optional(),
+    type: z.enum(ARCHITECTURE_TYPES).optional(),
+    validation: z.enum(ARCHITECTURE_VALIDATIONS).optional().default("strict"),
+  })
+  .strict()
+  .superRefine((val, ctx) => {
+    if (!val.preset && !val.type) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["preset"],
+        message: 'architecture must define "preset" or legacy "type"',
+      });
+    }
+    if (val.preset && val.type && val.preset !== val.type) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["preset"],
+        message: `architecture.preset "${val.preset}" must match architecture.type "${val.type}"`,
+      });
+    }
+  });
+
+export const HARNESS_DEFAULT_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 },
+];
+
+const harnessCommandSchema = z
+  .object({
+    name: z.string().min(1),
+    command: z.string().min(1),
+    required: z.boolean().optional().default(true),
+    description: z.string().optional(),
+  })
+  .strict();
+
+const harnessSchema = z
+  .object({
+    commands: z.array(harnessCommandSchema).min(1),
+  })
+  .strict();
+
+const uiSchema = z
+  .object({
+    kit: z.enum(UI_KITS),
+  })
+  .strict();
+
+const docsSchema = z
+  .object({
+    language: z.enum(DOCS_LANGUAGES),
+  })
+  .strict();
+
+const pathsSchema = z
+  .object({
+    features: z.string().min(1),
+    components: z.string().min(1),
+    services: z.string().min(1),
+    hooks: z.string().min(1),
+    pages: z.string().min(1),
+    ui: z.string().min(1),
+  })
+  .strict();
+
+const toolingSchema = z
+  .object({
+    language: z.enum(TOOLING_LANGUAGES),
+    linter: z.enum(TOOLING_LINTERS),
+    formatter: z.enum(TOOLING_FORMATTERS),
+  })
+  .strict();
+
+// ---------------------------------------------------------------------------
+// Top-level manifest v2 - strict, no extra keys except $schema
+// ---------------------------------------------------------------------------
+export const manifestSchemaV2 = z
+  .object({
+    $schema: z.string().url().optional().default(SCHEMA_URL),
+    manifestVersion: z.literal(MANIFEST_VERSION),
+    framework: frameworkSchema,
+    styling: stylingSchema,
+    architecture: architectureSchema,
+    harness: harnessSchema.optional(),
+    ui: uiSchema,
+    docs: docsSchema,
+    paths: pathsSchema,
+    tooling: toolingSchema,
+    reactCompiler: z.boolean().optional(),
+    agentDocs: z.boolean().optional(),
+  })
+  .strict()
+  .superRefine((val, ctx) => {
+    const { framework, architecture, styling, ui } = val;
+
+    // framework.variant must match framework.name
+    if (framework.name === "react" && framework.variant !== "vite") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["framework", "variant"],
+        message: `framework.variant must be "vite" when framework.name is "react" (got "${framework.variant}")`,
+      });
+    }
+    if (framework.name === "next" && framework.variant === "vite") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["framework", "variant"],
+        message: `framework.variant must be "app-router" or "pages-router" when framework.name is "next" (got "vite")`,
+      });
+    }
+
+    // bundler only for Next.js
+    if (framework.bundler !== undefined && framework.name !== "next") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["framework", "bundler"],
+        message: `framework.bundler is only valid when framework.name is "next"`,
+      });
+    }
+
+    // adapter only for Next.js (behavior in #22)
+    if (framework.adapter !== undefined && framework.name !== "next") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["framework", "adapter"],
+        message: `framework.adapter is only valid when framework.name is "next"`,
+      });
+    }
+
+    // architecture scoping per framework (#34) — canonical `preset`, legacy `type` fallback
+    const archValue = architecture.preset ?? architecture.type;
+    const allowedByFramework =
+      framework.name === "react"
+        ? ["feature-based", "type-based", "none"]
+        : ["feature-based", "hybrid", "none"];
+    if (!allowedByFramework.includes(archValue)) {
+      ctx.addIssue({
+        code: "custom",
+        path: ["architecture", "type"],
+        message: `architecture.type "${archValue}" is not valid for framework "${framework.name}" (allowed: ${allowedByFramework.join(", ")})`,
+      });
+    }
+
+    // shadcn requires tailwind (#33)
+    if (ui.kit === "shadcn" && styling.engine !== "tailwind") {
+      ctx.addIssue({
+        code: "custom",
+        path: ["ui", "kit"],
+        message: `ui.kit "shadcn" requires styling.engine "tailwind" (got "${styling.engine}")`,
+      });
+    }
+  });
+
+// ---------------------------------------------------------------------------
+// v1 detection - flat shape from create-lumen 1.x
+// ---------------------------------------------------------------------------
+const V1_FLAT_KEYS = ["css", "cssFramework", "architecture", "language", "router", "stateManagement", "iconLibrary", "apiClient", "testing"];
+
+export function isV1Manifest(raw) {
+  if (!raw || typeof raw !== "object") return false;
+  // v1 had framework as string or missing manifestVersion
+  if (raw.manifestVersion === 1) return true;
+  if (typeof raw.framework === "string") return true;
+  if (raw.framework === undefined && V1_FLAT_KEYS.some((k) => k in raw)) return true;
+  // flat config without nested framework object but with css/architecture as string
+  if (typeof raw.architecture === "string" && typeof raw.framework !== "object") return true;
+  return false;
+}
+
+export function formatZodError(error) {
+  try {
+    const ve = fromZodError(error, {
+      prefix: "Manifest validation failed",
+      prefixSeparator: ": ",
+      issueSeparator: "; ",
+    });
+    return ve.message;
+  } catch {
+    return error.message;
+  }
+}
+
+/**
+ * Parse and validate a manifest v2 object.
+ * - Throws with migration-oriented message for v1 manifests (#14 AC)
+ * - Throws with user-friendly field path + expected shape for malformed v2
+ * @param {unknown} raw
+ * @returns {import("zod").infer<typeof manifestSchemaV2>}
+ */
+export function parseManifest(raw) {
+  if (isV1Manifest(raw)) {
+    throw new Error(
+      `Manifest v1 detected (flat config). create-lumen v2 uses a nested manifest (manifestVersion: 2).\n` +
+        `Please migrate: delete the old config and re-run create-lumen, or see the migration guide (docs/migration/v1-to-v2.md).\n` +
+        `Raw keys: ${Object.keys(raw || {}).join(", ")}`
+    );
+  }
+
+  const result = manifestSchemaV2.safeParse(raw);
+  if (!result.success) {
+    const msg = formatZodError(result.error);
+    const err = new Error(msg);
+    err.cause = result.error;
+    throw err;
+  }
+  // Normalize: always expose architecture.preset + architecture.type (synced)
+  // + architecture.validation default, for backward/forward compat.
+  const data = result.data;
+  const preset = data.architecture.preset ?? data.architecture.type;
+  const type = data.architecture.type ?? data.architecture.preset;
+  data.architecture = {
+    preset,
+    type,
+    validation: data.architecture.validation ?? "strict",
+  };
+  return data;
+}
+
+// Re-export type helper for JSDoc (z.infer)
+// /** @typedef {z.infer<typeof manifestSchemaV2>} ManifestV2 */

package/src/prompts.js

@@ -1,4 +1,4 @@
-import { cancel, confirm, isCancel, note, select, text } from "@clack/prompts";
+import { confirm, isCancel, note, select } from "@clack/prompts";
 import chalk from "chalk";
 import { configExists, loadConfig, saveConfig } from "@/config-cache.js";
 
@@ -12,7 +12,9 @@ function formatConfig(responses) {
   const arch =
     responses.architecture === "feature-based"
       ? "Feature-based"
-      : "Component-based";
+      : responses.architecture === "type-based" || responses.architecture === "component-based"
+      ? "Type-based"
+      : responses.architecture;
   const css =
     responses.cssFramework === "none"
       ? "None"
@@ -32,6 +34,7 @@ function formatConfig(responses) {
       ? "Redux Toolkit"
       : "Zustand";
 
+  const docsLang = responses.docsLanguage === "es" ? "ES" : responses.docsLanguage === "en" ? "EN" : "—";
   return [
     `• ${chalk.bold("Architecture:")} ${chalk.green(arch)}`,
     `• ${chalk.bold("Language:")} ${chalk.green(lang)}`,
@@ -43,14 +46,15 @@ function formatConfig(responses) {
     `• ${chalk.bold("API Client:")} ${responses.apiClient === "axios" ? chalk.green("Axios") : responses.apiClient === "fetch" ? chalk.yellow("Fetch") : chalk.red("None")}`,
     `• ${chalk.bold("Linter:")} ${responses.linter === "oxlint" ? chalk.green("Oxlint") : responses.linter === "eslint" ? chalk.yellow("ESLint") : chalk.red("None")}`,
     `• ${chalk.bold("Formatter:")} ${responses.formatter === "oxfmt" ? chalk.green("Oxfmt") : responses.formatter === "prettier" ? chalk.yellow("Prettier") : chalk.red("None")}`,
+    `• ${chalk.bold("Docs:")} ${chalk.cyan(docsLang)}`,
     `• ${chalk.bold("Git:")} ${responses.gitInit ? chalk.green("Yes") : chalk.red("No")}`,
     `• ${chalk.bold("README:")} ${responses.readme ? chalk.green("Yes") : chalk.red("No")}`,
   ].join("\n");
 }
 
 export async function getUserInputs(projectName, { quickSetup = false } = {}) {
-  let oldConfig = {};
-  let useOldConfig = false;
+  let oldConfig;
+  let useOldConfig;
 
   // Non-interactive quick setup: apply defaults without prompting.
   if (quickSetup) {
@@ -66,6 +70,7 @@ export async function getUserInputs(projectName, { quickSetup = false } = {}) {
       apiClient: "none",
       linter: "eslint",
       formatter: "prettier",
+      docsLanguage: "en",
       gitInit: true,
       readme: true,
     };
@@ -101,6 +106,9 @@ export async function getUserInputs(projectName, { quickSetup = false } = {}) {
       if (oldConfig.formatter === undefined) {
         oldConfig.formatter = "none";
       }
+      if (oldConfig.docsLanguage === undefined) {
+        oldConfig.docsLanguage = "en";
+      }
       return { ...oldConfig, projectName };
     }
   }
@@ -126,6 +134,7 @@ export async function getUserInputs(projectName, { quickSetup = false } = {}) {
       apiClient: "none",
       linter: "eslint",
       formatter: "prettier",
+      docsLanguage: "en",
       gitInit: true,
       readme: true,
     };
@@ -143,8 +152,8 @@ export async function getUserInputs(projectName, { quickSetup = false } = {}) {
         hint: "Scales to large apps — code grouped by business domain",
       },
       {
-        label: "Component-based",
-        value: "component-based",
+        label: "Type-based",
+        value: "type-based",
         hint: "Small apps / component libraries — code grouped by UI type",
       },
     ],
@@ -261,6 +270,16 @@ export async function getUserInputs(projectName, { quickSetup = false } = {}) {
     if (isCancel(formatter)) onCancel();
   }
 
+  const docsLanguage = await select({
+    message: "Which docs language do you want?",
+    options: [
+      { label: "English", value: "en" },
+      { label: "Español", value: "es" },
+    ],
+    initialValue: "en",
+  });
+  if (isCancel(docsLanguage)) onCancel();
+
   const readme = await confirm({
     message: "Would you like to generate a README.md and LICENSE?",
     initialValue: true,
@@ -279,6 +298,7 @@ export async function getUserInputs(projectName, { quickSetup = false } = {}) {
     apiClient,
     linter,
     formatter,
+    docsLanguage,
     gitInit,
     readme,
   };

package/templates/conditional/linting/eslint/next/eslint.config.mjs

@@ -0,0 +1,16 @@
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { FlatCompat } from "@eslint/eslintrc";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const compat = new FlatCompat({
+  baseDirectory: __dirname,
+});
+
+const eslintConfig = [
+  ...compat.extends("next/core-web-vitals"),
+];
+
+export default eslintConfig;

package/templates/css/tailwind/postcss.config.mjs

@@ -0,0 +1,5 @@
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};