create-zenith 1.3.18 → 1.3.20

package/README.md

@@ -17,7 +17,8 @@ The official CLI for scaffolding new Zenith applications. Fast, animated, and de
 - **Interactive UX**: Built with `@clack/prompts` for intuitive arrow-key navigation and clear visual indicators.
 - **Reliable Fallbacks**: Automatically detects CI environments and non-TTY pipes to provide clean, static output.
 - **Smart Detection**: automatically detects your preferred package manager (Bun, pnpm, Yarn, or npm).
-- **Batteries Included**: Optional setup for ESLint, Prettier, and TypeScript path aliases.
+- **Template Authority**: Scaffold generation now reads only from `templates/` (`basic`, `css`, `tailwind`), which is the single source of truth for starter projects.
+- **Tool-Agnostic Output**: ESLint, Prettier, and TypeScript path aliases are opt-in. If you answer `No`, the generated project contains no scripts, dependencies, config files, or ignore files for that tool.
 
 ## Quick Start
 
@@ -40,6 +41,21 @@ pnpm create zenith
 | `-h, --help` | Show usage information |
 | `-v, --version` | Show version number |
 
+## Optional Tooling Contract
+
+During scaffold, `create-zenith` asks whether to include:
+
+- ESLint
+- Prettier
+- TypeScript path aliases
+
+Tooling behavior is strict:
+
+- If you enable ESLint, the project gets `eslint.config.js`, lint scripts, and matching ESLint dependencies.
+- If you disable ESLint, the project contains zero ESLint references.
+- If you enable Prettier, the project gets `.prettierrc`, `.prettierignore`, a format script, and the Prettier dependency.
+- If you disable Prettier, the project contains zero Prettier references.
+
 ## Beta Version Pinning
 
 Zenith beta currently pins `@zenithbuild/core` to `0.5.0-beta.2.20` and leaf packages (compiler, cli, runtime, router, bundler) to `0.5.0-beta.2.20`. This is intentional — core contains the CLI entry point and may bump independently for bin/CLI fixes without touching the engine.
@@ -50,8 +66,15 @@ If you see version mismatches after install, delete `node_modules` and `package-
 
 - Generated apps now depend on `@zenithbuild/core@latest` so new installs track the current stable framework release.
 - Template downloads now resolve from `zenithbuild/framework`, which is the active monorepo source of truth.
+- Starter templates now live under `templates/`, and the scaffolder no longer depends on `examples/`.
+- ESLint and Prettier are now feature overlays, so opting out leaves no stray config or dependency references in the scaffolded app.
 - Verified scaffold → install → build coverage lives in `tests/template-regression.spec.mjs`.
 
+## Templates vs Examples
+
+- `templates/` is authoritative for scaffolding.
+- `examples/` is demo-only when present and is not part of the scaffold source of truth.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -2553,6 +2553,33 @@ class dD extends x {
 }
 var A;
 A = new WeakMap;
+var OD = Object.defineProperty;
+var PD = (e, u, t) => (u in e) ? OD(e, u, { enumerable: true, configurable: true, writable: true, value: t }) : e[u] = t;
+var J = (e, u, t) => (PD(e, typeof u != "symbol" ? u + "" : u, t), t);
+
+class LD extends x {
+  constructor(u) {
+    super(u, false), J(this, "options"), J(this, "cursor", 0), this.options = u.options, this.cursor = this.options.findIndex(({ value: t }) => t === u.initialValue), this.cursor === -1 && (this.cursor = 0), this.changeValue(), this.on("cursor", (t) => {
+      switch (t) {
+        case "left":
+        case "up":
+          this.cursor = this.cursor === 0 ? this.options.length - 1 : this.cursor - 1;
+          break;
+        case "down":
+        case "right":
+          this.cursor = this.cursor === this.options.length - 1 ? 0 : this.cursor + 1;
+          break;
+      }
+      this.changeValue();
+    });
+  }
+  get _value() {
+    return this.options[this.cursor];
+  }
+  changeValue() {
+    this.value = this._value.value;
+  }
+}
 class RD extends x {
   get valueWithCursor() {
     if (this.state === "submit")
@@ -2615,6 +2642,16 @@ var b2 = (t) => {
       return import_picocolors3.default.green(C);
   }
 };
+var G2 = (t) => {
+  const { cursor: n, options: r2, style: i } = t, s = t.maxItems ?? Number.POSITIVE_INFINITY, c = Math.max(process.stdout.rows - 4, 0), a = Math.min(c, Math.max(s, 5));
+  let l2 = 0;
+  n >= l2 + a - 3 ? l2 = Math.max(Math.min(n - a + 3, r2.length - a), 0) : n < l2 + 2 && (l2 = Math.max(n - 2, 0));
+  const $2 = a < r2.length && l2 > 0, g2 = a < r2.length && l2 + a < r2.length;
+  return r2.slice(l2, l2 + a).map((p2, v2, f) => {
+    const j2 = v2 === 0 && $2, E = v2 === f.length - 1 && g2;
+    return j2 || E ? import_picocolors3.default.dim("...") : i(p2, v2 + l2 === n);
+  });
+};
 var he = (t) => new RD({ validate: t.validate, placeholder: t.placeholder, defaultValue: t.defaultValue, initialValue: t.initialValue, render() {
   const n = `${import_picocolors3.default.gray(o)}
 ${b2(this.state)}  ${t.message}
@@ -2655,6 +2692,38 @@ ${import_picocolors3.default.cyan(d2)}
     }
   } }).prompt();
 };
+var ve = (t) => {
+  const n = (r2, i) => {
+    const s = r2.label ?? String(r2.value);
+    switch (i) {
+      case "selected":
+        return `${import_picocolors3.default.dim(s)}`;
+      case "active":
+        return `${import_picocolors3.default.green(k2)} ${s} ${r2.hint ? import_picocolors3.default.dim(`(${r2.hint})`) : ""}`;
+      case "cancelled":
+        return `${import_picocolors3.default.strikethrough(import_picocolors3.default.dim(s))}`;
+      default:
+        return `${import_picocolors3.default.dim(P2)} ${import_picocolors3.default.dim(s)}`;
+    }
+  };
+  return new LD({ options: t.options, initialValue: t.initialValue, render() {
+    const r2 = `${import_picocolors3.default.gray(o)}
+${b2(this.state)}  ${t.message}
+`;
+    switch (this.state) {
+      case "submit":
+        return `${r2}${import_picocolors3.default.gray(o)}  ${n(this.options[this.cursor], "selected")}`;
+      case "cancel":
+        return `${r2}${import_picocolors3.default.gray(o)}  ${n(this.options[this.cursor], "cancelled")}
+${import_picocolors3.default.gray(o)}`;
+      default:
+        return `${r2}${import_picocolors3.default.cyan(o)}  ${G2({ cursor: this.cursor, options: this.options, maxItems: t.maxItems, style: (i, s) => n(i, s ? "active" : "inactive") }).join(`
+${import_picocolors3.default.cyan(o)}  `)}
+${import_picocolors3.default.cyan(d2)}
+`;
+    }
+  } }).prompt();
+};
 var xe = (t = "") => {
   process.stdout.write(`${import_picocolors3.default.gray(d2)}  ${import_picocolors3.default.red(t)}
 
@@ -2687,7 +2756,7 @@ var M2 = { message: (t = "", { symbol: n = import_picocolors3.default.gray(o) }
 }, error: (t) => {
   M2.message(t, { symbol: import_picocolors3.default.red(K2) });
 } };
-var J = `${import_picocolors3.default.gray(o)}  `;
+var J2 = `${import_picocolors3.default.gray(o)}  `;
 var Y2 = ({ indicator: t = "dots" } = {}) => {
   const n = V2 ? ["◒", "◐", "◓", "◑"] : ["•", "o", "O", "0"], r2 = V2 ? 80 : 120, i = process.env.CI === "true";
   let s, c, a = false, l2 = "", $2, g2 = performance.now();
@@ -2777,6 +2846,12 @@ async function confirm(opts) {
     initialValue: opts.initialValue ?? true
   });
 }
+async function select(opts) {
+  if (!isTTY()) {
+    return opts.initialValue || opts.options[0]?.value;
+  }
+  return await ve(opts);
+}
 function isCancel(value) {
   return pD(value);
 }
@@ -2819,10 +2894,124 @@ var log = {
   message: (message) => getUiMode(process).plain ? console.log(message) : M2.message(message)
 };
 
+// src/template-features.ts
+var FEATURE_DEFINITIONS = {
+  eslint: {
+    templatePath: "templates/features/eslint",
+    packagePatch: {
+      scripts: {
+        lint: "eslint ."
+      },
+      devDependencies: {
+        eslint: "^9.39.2",
+        "@typescript-eslint/eslint-plugin": "^8.53.0",
+        "@typescript-eslint/parser": "^8.53.0"
+      }
+    }
+  },
+  prettier: {
+    templatePath: "templates/features/prettier",
+    packagePatch: {
+      scripts: {
+        format: "prettier --write ."
+      },
+      devDependencies: {
+        prettier: "^3.7.4"
+      }
+    }
+  }
+};
+function mergeRecord(target, patch) {
+  if (!patch) {
+    return target;
+  }
+  return { ...target || {}, ...patch };
+}
+function selectedTemplateFeaturePaths(options) {
+  const paths = [];
+  if (options.eslint) {
+    paths.push(FEATURE_DEFINITIONS.eslint.templatePath);
+  }
+  if (options.prettier) {
+    paths.push(FEATURE_DEFINITIONS.prettier.templatePath);
+  }
+  return paths;
+}
+function applyPackageFeatures(manifest, options) {
+  const nextManifest = {
+    ...manifest,
+    scripts: { ...manifest.scripts || {} },
+    devDependencies: { ...manifest.devDependencies || {} }
+  };
+  for (const featureName of Object.keys(FEATURE_DEFINITIONS)) {
+    if (!options[featureName]) {
+      continue;
+    }
+    const patch = FEATURE_DEFINITIONS[featureName].packagePatch;
+    nextManifest.scripts = mergeRecord(nextManifest.scripts, patch.scripts);
+    nextManifest.devDependencies = mergeRecord(nextManifest.devDependencies, patch.devDependencies);
+  }
+  if (nextManifest.scripts && Object.keys(nextManifest.scripts).length === 0) {
+    delete nextManifest.scripts;
+  }
+  if (nextManifest.devDependencies && Object.keys(nextManifest.devDependencies).length === 0) {
+    delete nextManifest.devDependencies;
+  }
+  return nextManifest;
+}
+
+// src/templates.ts
+var DEFAULT_TEMPLATE = "css";
+var TEMPLATE_DEFINITIONS = {
+  basic: {
+    name: "basic",
+    label: "Basic",
+    hint: "Blank starter with a single page and minimal CSS",
+    templatePath: "templates/basic",
+    usesTailwind: false
+  },
+  css: {
+    name: "css",
+    label: "CSS",
+    hint: "Multi-page starter with a small curated CSS setup",
+    templatePath: "templates/css",
+    usesTailwind: false
+  },
+  tailwind: {
+    name: "tailwind",
+    label: "Tailwind",
+    hint: "Multi-page starter with Tailwind enabled",
+    templatePath: "templates/tailwind",
+    usesTailwind: true
+  }
+};
+var TEMPLATE_ALIASES = {
+  starter: "css",
+  "starter-tailwindcss": "tailwind"
+};
+function resolveTemplateName(value) {
+  const normalized = String(value || "").trim().toLowerCase();
+  if (!normalized) {
+    return null;
+  }
+  if (normalized in TEMPLATE_DEFINITIONS) {
+    return normalized;
+  }
+  return TEMPLATE_ALIASES[normalized] || null;
+}
+function getTemplateDefinition(templateName) {
+  return TEMPLATE_DEFINITIONS[templateName];
+}
+function templateSelectOptions() {
+  return Object.values(TEMPLATE_DEFINITIONS).map((definition) => ({
+    value: definition.name,
+    label: definition.label,
+    hint: definition.hint
+  }));
+}
+
 // src/index.ts
 var GITHUB_REPO = "zenithbuild/framework";
-var DEFAULT_TEMPLATE = "examples/starter";
-var TAILWIND_TEMPLATE = "examples/starter-tailwindcss";
 var __filename2 = fileURLToPath(import.meta.url);
 var __dirname2 = path.dirname(__filename2);
 function getCliVersion() {
@@ -2845,6 +3034,15 @@ function resolveLocalTemplatePath(templatePath) {
   const candidate = path.resolve(__dirname2, "..", templatePath);
   return fs.existsSync(candidate) ? candidate : null;
 }
+function copyDirectoryContents(sourceDir, targetDir) {
+  fs.mkdirSync(targetDir, { recursive: true });
+  for (const entry of fs.readdirSync(sourceDir)) {
+    fs.cpSync(path.join(sourceDir, entry), path.join(targetDir, entry), {
+      recursive: true,
+      force: true
+    });
+  }
+}
 function detectPackageManager() {
   const userAgent = process.env.npm_config_user_agent || "";
   if (userAgent.includes("bun"))
@@ -2875,16 +3073,22 @@ function hasGit() {
     return false;
   }
 }
-async function downloadTemplate(targetDir, templatePath) {
-  const localTemplatePath = resolveLocalTemplatePath(templatePath);
+async function downloadTemplate(targetDir, templatePaths) {
+  const localTemplatePaths = templatePaths.map((templatePath) => ({
+    templatePath,
+    localPath: resolveLocalTemplatePath(templatePath)
+  }));
   const forceLocal = process.env.CREATE_ZENITH_TEMPLATE_MODE === "local" || flagEnabled2(process.env.CREATE_ZENITH_OFFLINE);
   const preferLocal = process.env.CREATE_ZENITH_PREFER_LOCAL !== "0";
-  if (localTemplatePath && (forceLocal || preferLocal)) {
-    fs.cpSync(localTemplatePath, targetDir, { recursive: true });
+  if (localTemplatePaths.every((entry) => entry.localPath) && (forceLocal || preferLocal)) {
+    for (const entry of localTemplatePaths) {
+      copyDirectoryContents(entry.localPath, targetDir);
+    }
     return;
   }
-  if (forceLocal && !localTemplatePath) {
-    throw new Error(`Local template not found: ${templatePath}`);
+  if (forceLocal) {
+    const missingPath = localTemplatePaths.find((entry) => !entry.localPath)?.templatePath;
+    throw new Error(`Local template not found: ${missingPath}`);
   }
   const tempDir = path.join(os2.tmpdir(), `zenith-template-${Date.now()}`);
   try {
@@ -2892,13 +3096,15 @@ async function downloadTemplate(targetDir, templatePath) {
       execSync(`git clone --depth 1 --filter=blob:none --sparse https://github.com/${GITHUB_REPO}.git "${tempDir}"`, {
         stdio: "pipe"
       });
-      const repoTemplatePath = `packages/create-zenith/${templatePath}`;
-      execSync(`git sparse-checkout set ${repoTemplatePath}`, {
+      const repoTemplatePaths = templatePaths.map((templatePath) => `packages/create-zenith/${templatePath}`);
+      execSync(`git sparse-checkout set ${repoTemplatePaths.join(" ")}`, {
         cwd: tempDir,
         stdio: "pipe"
       });
-      const templateSource = path.join(tempDir, repoTemplatePath);
-      fs.cpSync(templateSource, targetDir, { recursive: true });
+      for (const repoTemplatePath of repoTemplatePaths) {
+        const templateSource = path.join(tempDir, repoTemplatePath);
+        copyDirectoryContents(templateSource, targetDir);
+      }
     } else {
       const tarballUrl = `https://github.com/${GITHUB_REPO}/archive/refs/heads/main.tar.gz`;
       const tarballPath = path.join(os2.tmpdir(), `zenith-${Date.now()}.tar.gz`);
@@ -2909,8 +3115,10 @@ async function downloadTemplate(targetDir, templatePath) {
       if (!extractedDir) {
         throw new Error("Failed to extract template from GitHub");
       }
-      const templateSource = path.join(tempDir, extractedDir, "packages/create-zenith", templatePath);
-      fs.cpSync(templateSource, targetDir, { recursive: true });
+      for (const templatePath of templatePaths) {
+        const templateSource = path.join(tempDir, extractedDir, "packages/create-zenith", templatePath);
+        copyDirectoryContents(templateSource, targetDir);
+      }
       fs.unlinkSync(tarballPath);
     }
   } finally {
@@ -2919,7 +3127,30 @@ async function downloadTemplate(targetDir, templatePath) {
     }
   }
 }
-async function gatherOptions(providedName, withTailwind) {
+function readOptionOverride(name) {
+  const value = process.env[name];
+  if (value == null || value.trim() === "") {
+    return;
+  }
+  return flagEnabled2(value);
+}
+function readTemplateOverride(name) {
+  const value = process.env[name];
+  if (value == null || value.trim() === "") {
+    return;
+  }
+  const templateName = resolveTemplateName(value);
+  if (!templateName) {
+    throw new Error(`Unsupported template "${value}". Use basic, css, or tailwind.`);
+  }
+  return templateName;
+}
+async function gatherOptions(providedName, requestedTemplate) {
+  const eslintOverride = readOptionOverride("CREATE_ZENITH_ESLINT");
+  const prettierOverride = readOptionOverride("CREATE_ZENITH_PRETTIER");
+  const pathAliasOverride = readOptionOverride("CREATE_ZENITH_PATH_ALIAS");
+  const templateOverride = readTemplateOverride("CREATE_ZENITH_TEMPLATE");
+  const selectedTemplate = requestedTemplate || templateOverride || DEFAULT_TEMPLATE;
   let name = providedName;
   if (!name) {
     const nameResult = await text({
@@ -2957,72 +3188,56 @@ async function gatherOptions(providedName, withTailwind) {
     log.info("Non-interactive mode detected, using defaults...");
     return {
       name,
-      eslint: true,
-      prettier: true,
-      pathAlias: true,
-      tailwind: withTailwind ?? false
+      eslint: eslintOverride ?? true,
+      prettier: prettierOverride ?? true,
+      pathAlias: pathAliasOverride ?? true,
+      template: selectedTemplate
     };
   }
-  const tailwindResult = withTailwind !== undefined ? withTailwind : await confirm({
-    message: "Add Tailwind CSS for styling?",
-    initialValue: true
+  const templateResult = requestedTemplate ?? templateOverride ?? await select({
+    message: "Choose a starter template",
+    options: templateSelectOptions(),
+    initialValue: DEFAULT_TEMPLATE
   });
-  if (isCancel(tailwindResult))
+  if (requestedTemplate === undefined && templateOverride === undefined && isCancel(templateResult)) {
     handleCancel();
-  const eslintResult = await confirm({
+  }
+  const eslintResult = eslintOverride ?? await confirm({
     message: "Add ESLint for code linting?",
     initialValue: true
   });
-  if (isCancel(eslintResult))
+  if (eslintOverride === undefined && isCancel(eslintResult))
     handleCancel();
-  const prettierResult = await confirm({
+  const prettierResult = prettierOverride ?? await confirm({
     message: "Add Prettier for code formatting?",
     initialValue: true
   });
-  if (isCancel(prettierResult))
+  if (prettierOverride === undefined && isCancel(prettierResult))
     handleCancel();
-  const pathAliasResult = await confirm({
+  const pathAliasResult = pathAliasOverride ?? await confirm({
     message: "Add TypeScript path alias (@/*)?",
     initialValue: true
   });
-  if (isCancel(pathAliasResult))
+  if (pathAliasOverride === undefined && isCancel(pathAliasResult))
     handleCancel();
   return {
     name,
     eslint: eslintResult,
     prettier: prettierResult,
     pathAlias: pathAliasResult,
-    tailwind: tailwindResult
+    template: templateResult
   };
 }
 async function createProject(options) {
   const targetDir = path.resolve(process.cwd(), options.name);
-  const templatePath = options.tailwind ? TAILWIND_TEMPLATE : DEFAULT_TEMPLATE;
-  await downloadTemplate(targetDir, templatePath);
+  const templatePath = getTemplateDefinition(options.template).templatePath;
+  const templateFeaturePaths = selectedTemplateFeaturePaths(options);
+  await downloadTemplate(targetDir, [templatePath, ...templateFeaturePaths]);
   const pkgPath = path.join(targetDir, "package.json");
   if (fs.existsSync(pkgPath)) {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
+    const pkg = applyPackageFeatures(JSON.parse(fs.readFileSync(pkgPath, "utf8")), options);
     pkg.name = options.name;
     pkg.version = "0.1.0";
-    if (!options.eslint) {
-      delete pkg.devDependencies?.["eslint"];
-      delete pkg.devDependencies?.["@typescript-eslint/eslint-plugin"];
-      delete pkg.devDependencies?.["@typescript-eslint/parser"];
-      delete pkg.scripts?.lint;
-      const eslintPath = path.join(targetDir, ".eslintrc.json");
-      if (fs.existsSync(eslintPath))
-        fs.unlinkSync(eslintPath);
-    }
-    if (!options.prettier) {
-      delete pkg.devDependencies?.["prettier"];
-      delete pkg.scripts?.format;
-      const prettierRc = path.join(targetDir, ".prettierrc");
-      const prettierIgnore = path.join(targetDir, ".prettierignore");
-      if (fs.existsSync(prettierRc))
-        fs.unlinkSync(prettierRc);
-      if (fs.existsSync(prettierIgnore))
-        fs.unlinkSync(prettierIgnore);
-    }
     fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 4));
   }
   const tsconfigPath = path.join(targetDir, "tsconfig.json");
@@ -3040,10 +3255,10 @@ async function createProject(options) {
     fs.writeFileSync(tsconfigPath, JSON.stringify(tsconfig, null, 4));
   }
 }
-async function create(appName, withTailwind) {
+async function create(appName, requestedTemplate) {
   await intro();
-  const options = await gatherOptions(appName, withTailwind);
-  const templateLabel = options.tailwind ? "starter-tailwindcss" : "starter";
+  const options = await gatherOptions(appName, requestedTemplate);
+  const templateLabel = getTemplateDefinition(options.template).name;
   showScaffoldSummary(options.name, templateLabel);
   console.log("");
   log.step(`Creating ${bold(options.name)}...`);
@@ -3088,7 +3303,8 @@ if (args.includes("--help") || args.includes("-h")) {
   console.log("Options:");
   console.log("  -h, --help           Show this help message");
   console.log("  -v, --version        Show version number");
-  console.log("  --with-tailwind      Initialize with Tailwind CSS v4 template");
+  console.log("  --template <name>    Choose template: basic, css, or tailwind");
+  console.log("  --with-tailwind      Alias for --template tailwind");
   console.log("");
   console.log("Examples:");
   console.log("  npx create-zenith my-app");
@@ -3101,9 +3317,30 @@ if (args.includes("--version") || args.includes("-v")) {
   console.log(`create-zenith ${VERSION}`);
   process.exit(0);
 }
-var projectName = args.find((arg) => !arg.startsWith("-"));
-var withTailwind = args.includes("--with-tailwind") ? true : undefined;
-create(projectName, withTailwind).catch((err) => {
+var projectName;
+var requestedTemplate;
+for (let index = 0;index < args.length; index += 1) {
+  const arg = args[index];
+  if (arg === "--with-tailwind") {
+    requestedTemplate = "tailwind";
+    continue;
+  }
+  if (arg === "--template") {
+    const templateValue = args[index + 1];
+    const templateName = resolveTemplateName(templateValue);
+    if (!templateName) {
+      error(`Unsupported template "${templateValue || ""}". Use basic, css, or tailwind.`);
+      process.exit(1);
+    }
+    requestedTemplate = templateName;
+    index += 1;
+    continue;
+  }
+  if (!arg.startsWith("-") && !projectName) {
+    projectName = arg;
+  }
+}
+create(projectName, requestedTemplate).catch((err) => {
   const mode = getUiMode(process);
   if (mode.plain) {
     console.log("ERROR: SCAFFOLD_ERROR");