create-lumen 1.1.3 → 1.2.0-beta.1

package/README.md

@@ -17,9 +17,9 @@ npm run dev
 Non-interactive Quick Setup (TypeScript + Tailwind + Feature-based + Router + ESLint + Prettier + Vitest), no prompts:
 
 ```bash
-npm create lumen my-app -y
+npm create lumen my-app -- -y
 # or
-npm create lumen -y my-app
+npm create lumen -- -y my-app
 ```
 
 The CLI ignores flag arguments when resolving the project name, so `-y` can appear before or after the app name without being mistaken for the folder name.
@@ -87,36 +87,40 @@ Feature-based (example):
 
 ```
 src/
-├── app
+├── app               # App shell and global providers
 │   ├── App.tsx
+│   ├── contexts
+│   │   └── themecontext.ts   # createContext + ThemeContextValue
 │   ├── providers
-│   │   └── ThemeProvider.tsx
-│   └── router.tsx
-├── components
-│   └── ui
-├── config
-│   └── constants.ts
-├── features
-│   └── logout
+│   │   └── ThemeProvider.tsx # Provider component
+│   ├── hooks
+│   │   └── useTheme.ts       # Hook that reads ThemeContext
+│   └── router        # Data router (per feature area)
+│       ├── guards    # AuthGuard, RoleGuard
+│       ├── routes    # home.routes, auth.routes
+│       └── index.tsx # createBrowserRouter init
+├── features           # Feature modules (business logic owned per feature)
+│   └── home
 │       ├── components
-│       ├── interfaces
+│       ├── hooks
+│       ├── index.ts    # public feature barrel
 │       ├── layouts
 │       ├── pages
 │       ├── services
-│       └── store
-├── hooks
-│   ├── index.ts
-│   └── useLocalStorage.ts
-├── index.css
-├── lib
-├── main.tsx
-├── stores
-├── styles
-│   └── globals.css
-├── test
-│   └── setup.ts
-├── types
-└── utils
+│       ├── store
+│       └── types
+└── shared             # Reusable, business-agnostic resources
+    ├── api/lib        # fetch client → api/; axios init → lib/axios/ (per choice)
+    ├── components
+    │   └── ui
+    ├── hooks
+    ├── layouts
+    ├── stores
+    ├── styles
+    │   ├── globals.css      # Tailwind/Bootstrap directives (or main.css for vanilla)
+    │   └── themes.css       # Theme tokens (Tailwind @theme / Bootstrap data-bs-theme / CSS vars)
+    ├── types
+    └── utils
 ```
 
 Component-based (example):
@@ -126,28 +130,32 @@ src/
 ├── App.tsx
 ├── components
 │   ├── common
-│   ├── form
-│   └── layout
-├── config
-│   ├── constants.ts
-│   └── routes.ts
-├── context
+│   └── form
+├── config             # API config (when an axios/fetch client is chosen)
 ├── hooks
-├── index.css
 ├── layouts
 ├── main.tsx
 ├── pages
-├── routes
+├── providers          # Provider components (createContext + Provider in separate files inside providers/)
+│   ├── appcontext.ts      # createContext + AppContextValue
+│   └── AppProvider.tsx    # Provider component
+├── hooks
+│   └── useApp.ts           # Hook that reads AppContext
+├── router             # Centralized data router
+│   ├── guards         # AuthGuard, GuestGuard
+│   └── index.tsx      # Single source of truth for all routes
 ├── services
 ├── store
 ├── styles
+│   ├── globals.css      # Tailwind/Bootstrap directives (or main.css for vanilla)
+│   └── themes.css       # Theme tokens (Tailwind @theme / Bootstrap data-bs-theme / CSS vars)
 ├── test
 └── utils
 ```
 
 ## Roadmap
 
-See `docs/ROADMAP.md` for planned features and upcoming releases.
+Released versions live in [`docs/CHANGELOG.md`](./docs/CHANGELOG.md); planned work is tracked in [`docs/ROADMAP.md`](./docs/ROADMAP.md).
 
 ## Requirements
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-lumen",
-  "version": "1.1.3",
+  "version": "1.2.0-beta.1",
   "description": "Scaffold a React + Vite project with architecture choice: feature-based or component-based.",
   "type": "module",
   "bin": {
@@ -15,7 +15,13 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --import ./register.js --test \"tests/unit/*.test.mjs\" \"tests/smoke/*.test.mjs\""
+    "test": "node --import ./register.js --test \"tests/unit/*.test.mjs\" \"tests/smoke/*.test.mjs\"",
+    "verify:vendor": "node --import ./register.js tests/verify/install-vendor.mjs",
+    "verify:offline": "node --import ./register.js tests/verify/verify-offline.mjs",
+    "verify:installed": "node --import ./register.js tests/verify/verify-installed.mjs",
+    "verify": "npm run verify:vendor && npm run verify:offline",
+    "verify:full": "npm run verify:vendor && npm run verify:offline && npm run verify:installed",
+    "verify:matrix": "FULL=1 npm run verify:offline"
   },
   "keywords": [
     "scaffold",

package/src/configure.js

@@ -19,7 +19,7 @@ export async function configureProject(projectPath, language, cssFramework) {
   }
 
   // Add scripts to package.json
-  await configurePackageJson(projectPath);
+  await configurePackageJson(projectPath, language);
 }
 
 async function configureTsconfig(projectPath) {
@@ -31,8 +31,13 @@ async function configureTsconfig(projectPath) {
     const config = JSON.parse(content);
 
     if (!config.compilerOptions) config.compilerOptions = {};
-    config.compilerOptions.baseUrl = ".";
+    config.compilerOptions.strict = true;
     config.compilerOptions.paths = paths;
+    if (config.compilerOptions.types?.length && !config.compilerOptions.types.includes("vite/client")) {
+      config.compilerOptions.types.push("vite/client");
+    } else if (!config.compilerOptions.types) {
+      config.compilerOptions.types = ["vite/client"];
+    }
 
     await fsp.writeFile(
       tsconfigAppPath,
@@ -58,7 +63,7 @@ async function configureTsconfig(projectPath) {
         noUnusedLocals: true,
         noUnusedParameters: true,
         noFallthroughCasesInSwitch: true,
-        baseUrl: ".",
+        types: ["vite/client"],
         paths,
       },
       include: ["src"],
@@ -70,11 +75,19 @@ async function configureTsconfig(projectPath) {
     );
   }
 
-  // Create/update root tsconfig.json with references
+  // Create/update root tsconfig.json with references.
+  // Preserve the ./tsconfig.node.json reference (Vite config) when present.
   const rootTsconfigPath = path.join(projectPath, "tsconfig.json");
+  const nodeConfigPath = path.join(projectPath, "tsconfig.node.json");
+  const references = [{ path: "./tsconfig.app.json" }];
+  try {
+    await fsp.access(nodeConfigPath);
+    references.push({ path: "./tsconfig.node.json" });
+  } catch {}
+
   const rootTsconfig = {
     files: [],
-    references: [{ path: "./tsconfig.app.json" }],
+    references,
   };
   await fsp.writeFile(
     rootTsconfigPath,
@@ -100,7 +113,7 @@ async function addPathAliasesToViteConfig(projectPath, ext) {
   try {
     let content = await readFileContent(viteConfigPath);
 
-    if (content.includes("tsconfigPaths")) return;
+    if (content.includes("find: '@'")) return;
 
     const lines = content.split("\n");
 
@@ -112,8 +125,8 @@ async function addPathAliasesToViteConfig(projectPath, ext) {
 
     // Insert path/fileURLToPath imports after last import
     const newImports = [
-      'import path from "path";',
-      'import { fileURLToPath } from "url";',
+      "import path from 'path';",
+      "import { fileURLToPath } from 'url';",
       "const __dirname = path.dirname(fileURLToPath(import.meta.url));",
     ];
     lines.splice(lastImportIdx + 1, 0, ...newImports);
@@ -121,13 +134,10 @@ async function addPathAliasesToViteConfig(projectPath, ext) {
     let result = lines.join("\n");
 
     const aliasArray = getViteAliases()
-      .map(
-        (a) =>
-          `{ find: "${a.find}", replacement: ${a.replacement} }`
-      )
-      .join(",\n              ");
+      .map((a) => `{ find: '${a.find}', replacement: ${a.replacement} }`)
+      .join(",\n      ");
 
-    const resolveBlock = `resolve: {\n    tsconfigPaths: true,\n    alias: [\n              ${aliasArray}\n    ],\n  }`;
+    const resolveBlock = `resolve: {\n    alias: [\n      ${aliasArray},\n    ],\n  }`;
 
     if (result.includes("resolve:")) {
       result = result.replace(/resolve:\s*\{/, resolveBlock);
@@ -144,7 +154,7 @@ async function addPathAliasesToViteConfig(projectPath, ext) {
   }
 }
 
-async function configurePackageJson(projectPath) {
+async function configurePackageJson(projectPath, language) {
   const pkgPath = path.join(projectPath, "package.json");
   try {
     const content = await readFileContent(pkgPath);
@@ -156,6 +166,10 @@ async function configurePackageJson(projectPath) {
     pkg.scripts.build = "vite build";
     pkg.scripts.preview = "vite preview";
 
+    if (language === "ts") {
+      pkg.scripts.typecheck = "tsc -b";
+    }
+
     await fsp.writeFile(pkgPath, JSON.stringify(pkg, null, 2) + "\n", "utf8");
   } catch {
     // file doesn't exist, skip

package/src/css.js

@@ -1,4 +1,3 @@
-import fs from "fs";
 import { promises as fsp } from "fs";
 import path from "path";
 import { deleteIfExists } from "@/utils/fs.js";
@@ -8,12 +7,28 @@ export async function setupCssFramework({
   templatesDir,
   language,
   cssFramework,
+  architecture,
   ext,
   pkg,
 }) {
   process.chdir(projectPath);
   const cssDir = path.join(templatesDir, "css");
-  const indexCssPath = path.join(projectPath, "src", "index.css");
+  // Feature-based main.* imports ./shared/styles/globals.css (or main.css when
+  // framework is "none"); component-based imports ./styles/globals.css (or
+  // main.css). The chosen framework's styles land in the file the architecture
+  // actually imports.
+  const stylesDir =
+    architecture === "feature-based"
+      ? path.join(projectPath, "src", "shared", "styles")
+      : path.join(projectPath, "src", "styles");
+
+  // Vanilla CSS gets a stylesheet named main.css; tailwind/bootstrap keep
+  // globals.css (their idiomatic name — they inject framework directives).
+  const mainFileName = cssFramework === "none" ? "main.css" : "globals.css";
+
+  async function writeCss(content, fileName) {
+    await fsp.writeFile(path.join(stylesDir, fileName), content, "utf8");
+  }
 
   if (cssFramework === "tailwind") {
     const viteConfigFile = `vite.config.${language === "ts" ? "ts" : "js"}`;
@@ -24,14 +39,19 @@ export async function setupCssFramework({
     );
     await fsp.writeFile(viteConfigTarget, viteConfigContent, "utf8");
 
-    const indexCssContent = await fsp.readFile(
-      path.join(cssDir, "tailwind", "src", "index.css"),
+    const globalsContent = await fsp.readFile(
+      path.join(cssDir, "tailwind", "src", "globals.css"),
       "utf8"
     );
-    await fsp.writeFile(indexCssPath, indexCssContent, "utf8");
+    const themesContent = await fsp.readFile(
+      path.join(cssDir, "tailwind", "src", "themes.css"),
+      "utf8"
+    );
+    await writeCss(globalsContent, "globals.css");
+    await writeCss(themesContent, "themes.css");
   } else if (cssFramework === "bootstrap") {
     const mainFile = path.join(projectPath, "src", `main.${ext}`);
-    if (fs.existsSync(mainFile)) {
+    try {
       let mainContent = await fsp.readFile(mainFile, "utf8");
       if (
         !mainContent.includes("bootstrap/dist/css/bootstrap.min.css")
@@ -40,20 +60,59 @@ export async function setupCssFramework({
           "import 'bootstrap/dist/css/bootstrap.min.css';\n" + mainContent;
         await fsp.writeFile(mainFile, mainContent, "utf8");
       }
-    }
-    const indexCssContent = await fsp.readFile(
-      path.join(cssDir, "bootstrap", "src", "index.css"),
+    } catch {}
+
+    const globalsContent = await fsp.readFile(
+      path.join(cssDir, "bootstrap", "src", "globals.css"),
+      "utf8"
+    );
+    const themesContent = await fsp.readFile(
+      path.join(cssDir, "bootstrap", "src", "themes.css"),
       "utf8"
     );
-    await fsp.writeFile(indexCssPath, indexCssContent, "utf8");
+    await writeCss(globalsContent, "globals.css");
+    await writeCss(themesContent, "themes.css");
   } else {
-    const indexCssContent = await fsp.readFile(
-      path.join(cssDir, "none", "src", "index.css"),
+    const mainContent = await fsp.readFile(
+      path.join(cssDir, "none", "src", "main.css"),
+      "utf8"
+    );
+    const themesContent = await fsp.readFile(
+      path.join(cssDir, "none", "src", "themes.css"),
       "utf8"
     );
-    await fsp.writeFile(indexCssPath, indexCssContent, "utf8");
+    await writeCss(mainContent, "main.css");
+    await writeCss(themesContent, "themes.css");
   }
 
-  // Clean up Vite's default App.css
+  // Ensure main.{ext} imports the correct stylesheet name for this framework.
+  await syncMainCssImport(projectPath, ext, architecture, mainFileName);
+
+  // Ensure the styles dir exists (for the .gitkeep placeholder when no real
+  // file lives there yet — pruneRedundantGitkeeps removes it after overlays).
+  await fsp.mkdir(stylesDir, { recursive: true });
+
+  // Clean up Vite's default CSS files; src/index.css is the framework-agnostic
+  // leftover Vite scaffolds and is never imported in our generated projects.
   await deleteIfExists(path.join(projectPath, "src", "App.css"));
+  await deleteIfExists(path.join(projectPath, "src", "index.css"));
+}
+
+// Rewrite the CSS import in main.{ext} so it matches the file the framework
+// actually wrote (main.css for "none", globals.css for tailwind/bootstrap).
+async function syncMainCssImport(projectPath, ext, architecture, mainFileName) {
+  const mainPath = path.join(projectPath, "src", `main.${ext}`);
+  try {
+    let content = await fsp.readFile(mainPath, "utf8");
+    const expected =
+      architecture === "feature-based"
+        ? `./shared/styles/${mainFileName}`
+        : `./styles/${mainFileName}`;
+    const wrong =
+      architecture === "feature-based"
+        ? /import ['"]\.\/shared\/styles\/(globals|main)\.css['"]/
+        : /import ['"]\.\/styles\/(globals|main)\.css['"]/;
+    content = content.replace(wrong, `import '${expected}'`);
+    await fsp.writeFile(mainPath, content, "utf8");
+  } catch {}
 }

package/src/dependencies.js

@@ -71,11 +71,14 @@ export async function installAllDeps(responses, pkg, cwd) {
   } else if (responses.testing === "jest") {
     devDeps.push(
       "jest",
-      "ts-jest",
-      "@types/jest",
+      "jest-environment-jsdom",
       "@testing-library/react",
       "@testing-library/jest-dom",
-      "jsdom"
+      "jsdom",
+      "babel-jest",
+      "@babel/preset-env",
+      "@babel/preset-react",
+      "@babel/preset-typescript"
     );
   }
 
@@ -84,6 +87,8 @@ export async function installAllDeps(responses, pkg, cwd) {
     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");
     }
   } else if (responses.linter === "oxlint") {
     devDeps.push("oxlint");

package/src/format.js

@@ -0,0 +1,28 @@
+import path from "path";
+import { execa } from "execa";
+import { promises as fsp } from "fs";
+
+async function exists(p) {
+  try {
+    await fsp.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Runs the project-local formatter (installed as a devDependency) so a freshly
+// generated project is canonical under its chosen formatter by construction.
+// Falls back to the bare command name so the same helper works when the binary
+// is already on PATH (e.g. verification harnesses resolving from a vendored
+// node_modules symlink).
+export async function runProjectFormat(projectPath, responses) {
+  if (!responses.formatter || responses.formatter === "none") return;
+
+  const formatter = responses.formatter;
+  const bin = path.join(projectPath, "node_modules", ".bin", formatter);
+  const command = (await exists(bin)) ? bin : formatter;
+  const args = formatter === "prettier" ? ["--write", "."] : ["."];
+
+  await execa(command, args, { cwd: projectPath, stdio: "pipe" });
+}