@cellajs/create-cella 0.2.2 → 0.3.0

package/dist/index.js

@@ -4,7 +4,7 @@
 import { existsSync as existsSync2 } from "fs";
 import { basename as basename2, resolve as resolve3 } from "path";
 import { input, select } from "@inquirer/prompts";
-import pc5 from "picocolors";
+import pc6 from "picocolors";
 
 // src/constants.ts
 import pc from "picocolors";
@@ -12,7 +12,7 @@ import pc from "picocolors";
 // package.json
 var package_default = {
   name: "@cellajs/create-cella",
-  version: "0.2.2",
+  version: "0.3.0",
   private: false,
   license: "MIT",
   description: "Cella is a TypeScript template to create web apps with sync and offline capabilities.",
@@ -21,8 +21,7 @@ var package_default = {
   },
   repository: {
     type: "git",
-    url: "https://github.com/cellajs/cella",
-    directory: "cli/create-cella"
+    url: "https://github.com/cellajs/create-cella"
   },
   homepage: "https://cellajs.com",
   author: "CellaJS <info@cellajs.com>",
@@ -45,6 +44,7 @@ var package_default = {
   },
   scripts: {
     start: "tsx ./src/create-cella-cli.ts",
+    try: "tsx ./src/create-cella-cli.ts ../cella-try-app",
     clean: "rimraf ./dist",
     build: "tsup",
     "test-build": "pnpm run build && node index.js",
@@ -54,26 +54,58 @@ var package_default = {
     lint: "biome check .",
     "lint:fix": "biome check --write .",
     test: "vitest run",
-    "test:release": "pnpm run build && vitest run tests/release-artifact.test.ts tests/release-smoke.test.ts",
-    "test:watch": "vitest"
+    "test:release": "pnpm run build && vitest run --config vitest.release.config.ts",
+    "test:watch": "vitest",
+    prepare: "lefthook install"
   },
   dependencies: {
     "@inquirer/prompts": "^8.5.2",
-    axios: "^1.17.0",
     commander: "^15.0.0",
-    giget: "^3.1.2",
-    "nano-spawn": "^2.0.0",
-    ora: "^9.3.0",
+    ignore: "^7.0.5",
+    "isomorphic-git": "^1.38.5",
+    nanotar: "^0.3.0",
+    ora: "^9.4.1",
     picocolors: "^1.1.1",
     "validate-npm-package-name": "^8.0.0"
   },
   devDependencies: {
-    "@types/node": "catalog:",
-    "@typescript/native-preview": "catalog:",
+    "@biomejs/biome": "^2.5.1",
+    "@commitlint/cli": "^21.1.0",
+    "@commitlint/config-conventional": "^21.1.0",
+    "@evilmartians/lefthook": "^2.1.9",
+    "@types/node": "24.10.13",
     "@types/validate-npm-package-name": "^4.0.2",
-    tsup: "catalog:",
-    tsx: "catalog:",
-    vitest: "catalog:"
+    "@typescript/native-preview": "7.0.0-dev.20260628.1",
+    rimraf: "^6.1.3",
+    tsup: "^8.5.1",
+    tsx: "^4.22.4",
+    typescript: "^6.0.3",
+    vitest: "^4.1.9"
+  },
+  packageManager: "pnpm@11.8.0",
+  commitlint: {
+    extends: [
+      "@commitlint/config-conventional"
+    ],
+    rules: {
+      "type-enum": [
+        2,
+        "always",
+        [
+          "feat",
+          "fix",
+          "perf",
+          "refactor",
+          "revert",
+          "docs",
+          "chore",
+          "build",
+          "ci",
+          "style",
+          "test"
+        ]
+      ]
+    }
   }
 };
 
@@ -84,15 +116,12 @@ var TEMPLATE_URL = "github:cellajs/cella";
 var CELLA_REMOTE_URL = "git@github.com:cellajs/cella.git";
 var DESCRIPTION = package_default.description;
 var VERSION = package_default.version;
-var AUTHOR = package_default.author;
 var WEBSITE = package_default.homepage;
-var GITHUB = package_default.repository.url;
 function getHeaderLine(templateVersion) {
-  const leftText = `\u29C8 ${NAME} \xB7 v${VERSION} \xB7 cella v${templateVersion}`;
-  const rightText = package_default.homepage.replace("https://", "");
-  const left = `${pc.cyan(`\u29C8 ${NAME}`)} ${pc.dim(`\xB7 v${VERSION} \xB7 cella v${templateVersion}`)}`;
-  const right = pc.cyan(rightText);
-  const padding = Math.max(1, 60 - leftText.length - rightText.length);
+  const leftText = `\u29C8 ${NAME} \xB7 ${VERSION} \xB7 cella ${templateVersion}`;
+  const left = `${pc.cyan(`\u29C8 ${NAME}`)} ${pc.dim(`\xB7 ${VERSION} \xB7 cella ${templateVersion}`)}`;
+  const right = pc.cyan(WEBSITE);
+  const padding = Math.max(1, 60 - leftText.length - WEBSITE.length);
   return `${left}${" ".repeat(padding)}${right}`;
 }
 var TO_REMOVE = ["./cli/create", "./info/QUICKSTART.md"];
@@ -103,10 +132,10 @@ var TO_COPY = {
 };
 var PLACEHOLDER_CONFIG = "configs/default-config.ts.template";
 async function generateEnvFromExample(examplePath, replacements) {
-  const { readFile: readFile2 } = await import("fs/promises");
+  const { readFile: readFile4 } = await import("fs/promises");
   let content;
   try {
-    content = await readFile2(examplePath, "utf8");
+    content = await readFile4(examplePath, "utf8");
   } catch {
     return null;
   }
@@ -191,47 +220,35 @@ ${nameEntry}${body}
 
 // src/create.ts
 import { existsSync } from "fs";
-import { cp, mkdir } from "fs/promises";
-import { join, relative, resolve as resolve2 } from "path";
-import { downloadTemplate } from "giget";
+import { cp, mkdir as mkdir2, rm } from "fs/promises";
+import { dirname as dirname3, isAbsolute, join as join4, relative as relative2, resolve as resolve2 } from "path";
+import { checkbox } from "@inquirer/prompts";
+import pc5 from "picocolors";
 
 // src/utils/git/command.ts
-import { execFile } from "child_process";
-import { promisify } from "util";
-var execFileAsync = promisify(execFile);
-async function runGitCommand(args, repoPath, options2 = {}) {
-  const gitArgs = repoPath ? ["-C", repoPath, ...args] : args;
-  const env = {
-    ...process.env,
-    ...options2.skipEditor ? { GIT_EDITOR: "true" } : {}
-  };
-  const maxBuffer = options2.maxBuffer ?? 10 * 1024 * 1024;
-  const { stdout } = await execFileAsync("git", gitArgs, { env, maxBuffer });
-  return stdout.trim();
-}
+import fs from "fs";
+import git from "isomorphic-git";
+var INITIAL_AUTHOR = { name: "cella", email: "info@cellajs.com" };
 async function gitInit(repoPath) {
-  return runGitCommand(["init"], repoPath);
+  await git.init({ fs, dir: repoPath, defaultBranch: "main" });
 }
 async function gitAddAll(repoPath) {
-  return runGitCommand(["add", "."], repoPath);
+  await git.add({ fs, dir: repoPath, filepath: "." });
 }
 async function gitCommit(repoPath, message) {
-  return runGitCommand(["commit", "--quiet", "--no-verify", "-m", message], repoPath);
-}
-async function gitBranch(repoPath, branchName) {
-  return runGitCommand(["branch", branchName], repoPath);
-}
-async function gitCheckout(repoPath, branchName) {
-  return runGitCommand(["checkout", branchName], repoPath);
+  return git.commit({ fs, dir: repoPath, message, author: INITIAL_AUTHOR });
 }
 async function gitRemoteGetUrl(repoPath, remoteName) {
-  return runGitCommand(["remote", "get-url", remoteName], repoPath);
+  const remotes = await git.listRemotes({ fs, dir: repoPath });
+  const match = remotes.find((r) => r.remote === remoteName);
+  if (!match) throw new Error(`No such remote '${remoteName}'`);
+  return match.url;
 }
 async function gitRemoteAdd(repoPath, remoteName, remoteUrl) {
-  return runGitCommand(["remote", "add", remoteName, remoteUrl], repoPath);
+  await git.addRemote({ fs, dir: repoPath, remote: remoteName, url: remoteUrl });
 }
 async function gitRemoteRemove(repoPath, remoteName) {
-  return runGitCommand(["remote", "remove", remoteName], repoPath);
+  await git.deleteRemote({ fs, dir: repoPath, remote: remoteName });
 }
 
 // src/add-remote.ts
@@ -290,7 +307,6 @@ function parsePortOffset(value) {
   return parsed;
 }
 var directory = null;
-var newBranchName = null;
 var packageManager = "pnpm";
 var command = new Command(NAME).version(VERSION, "-v, --version", `output the current version of ${NAME}`).argument("[directory]", "the directory name for the new project").usage("[directory] [options]").helpOption("-h, --help", "display this help message").option("--template <path>", "use a custom template (local path or github:user/repo)").option("--port-offset <number>", "set the port offset (0-490 in steps of 10)", parsePortOffset).option("--admin-email <email>", "set the admin email for the initial seed user").action((name) => {
   const trimmedName = typeof name === "string" ? name.trim() : name;
@@ -308,7 +324,6 @@ function runCli() {
     options,
     args: command.args,
     directory,
-    newBranchName,
     packageManager
   };
 }
@@ -332,29 +347,33 @@ function showWelcome(templateVersion) {
   console.info(getHeaderLine(templateVersion));
   console.info(DIVIDER);
 }
+function confirmChoice(label, value) {
+  console.info(`${pc2.green("\u2713")} ${label} \xB7 ${value}`);
+  console.info();
+}
 function showSuccess(projectName, _targetFolder, relativePath, needsCd, packageManager2) {
+  console.info();
+  console.info(pc2.bold("Next steps"));
   console.info(DIVIDER);
   console.info();
   if (needsCd) {
-    console.info(`${pc2.green("\u2192")} cd ${pc2.cyan(relativePath)}`);
-    console.info();
+    console.info(`${pc2.dim("$")} cd ${pc2.cyan(relativePath)}`);
   }
-  console.info(`${pc2.green("\u2192")} ${pc2.cyan(`${packageManager2} quick`)}       ${pc2.gray("(pglite, no docker)")}`);
-  console.info();
-  console.info(pc2.gray("or, for full setup:"));
-  console.info();
+  console.info(`${pc2.dim("$")} ${pc2.cyan(`${packageManager2} install`)}`);
+  console.info(`${pc2.dim("$")} ${pc2.cyan(`${packageManager2} generate`)}`);
   console.info(
-    `${pc2.green("\u2192")} ${pc2.cyan(`${packageManager2} docker`)} ${pc2.dim("&&")} ${pc2.cyan(`${packageManager2} seed`)} ${pc2.dim("&&")} ${pc2.cyan(`${packageManager2} dev`)}`
+    `${pc2.dim("$")} ${pc2.cyan(`${packageManager2} docker`)} ${pc2.dim("&&")} ${pc2.cyan(`${packageManager2} seed`)} ${pc2.dim("&&")} ${pc2.cyan(`${packageManager2} dev`)}`
   );
   console.info();
-  console.info(`sign in: ${pc2.gray("admin-test@cellajs.com / 12345678")}`);
+  const readmePath = relativePath ? `${relativePath}/README.md` : "README.md";
+  console.info(`${pc2.gray("To get started building, please read:")} ${pc2.cyan(readmePath)}`);
   console.info();
-  console.info(`enjoy building ${pc2.green(projectName)} with cella!`);
+  console.info(`\u{1F973} enjoy building ${pc2.green(projectName)} with cella!`);
   console.info();
 }
 
 // src/utils/clean-template.ts
-import fs from "fs/promises";
+import fs2 from "fs/promises";
 import path from "path";
 import { fileURLToPath } from "url";
 import pc3 from "picocolors";
@@ -364,7 +383,7 @@ async function resolvePlaceholderConfigPath() {
   const candidates = [path.resolve(here, "../..", PLACEHOLDER_CONFIG), path.resolve(here, "..", PLACEHOLDER_CONFIG)];
   for (const candidate of candidates) {
     try {
-      await fs.access(candidate);
+      await fs2.access(candidate);
       return candidate;
     } catch {
     }
@@ -396,12 +415,12 @@ async function cleanTemplate({
           backendReplacements
         );
         if (backendEnv) {
-          await fs.writeFile(path.resolve(targetFolder, "backend/.env"), backendEnv, "utf8");
+          await fs2.writeFile(path.resolve(targetFolder, "backend/.env"), backendEnv, "utf8");
         }
         const envConfigs = generateEnvConfigs(projectName, displayName, portOffset);
         await Promise.all(
           Object.entries(envConfigs).map(
-            ([filePath, content]) => fs.writeFile(path.resolve(targetFolder, filePath), content, "utf8")
+            ([filePath, content]) => fs2.writeFile(path.resolve(targetFolder, filePath), content, "utf8")
           )
         );
         await Promise.all(
@@ -424,27 +443,27 @@ async function cleanTemplate({
   });
 }
 async function removeFolderContents(folderPath) {
-  const files = await fs.readdir(folderPath);
+  const files = await fs2.readdir(folderPath);
   await Promise.all(
     files.map(async (file) => {
       const filePath = path.join(folderPath, file);
-      const stat = await fs.lstat(filePath);
+      const stat = await fs2.lstat(filePath);
       if (stat.isDirectory()) {
-        await fs.rm(filePath, { recursive: true, force: true });
+        await fs2.rm(filePath, { recursive: true, force: true });
       } else {
-        await fs.rm(filePath);
+        await fs2.rm(filePath);
       }
     })
   );
 }
 async function removeFileOrFolder(pathToRemove) {
-  await fs.rm(pathToRemove, { recursive: true, force: true });
+  await fs2.rm(pathToRemove, { recursive: true, force: true });
 }
 async function copyFile(src, dest) {
   try {
-    await fs.access(src);
-    await fs.mkdir(path.dirname(dest), { recursive: true });
-    await fs.copyFile(src, dest);
+    await fs2.access(src);
+    await fs2.mkdir(path.dirname(dest), { recursive: true });
+    await fs2.copyFile(src, dest);
   } catch (err) {
     if (err.code === "ENOENT") {
       console.info(`
@@ -459,10 +478,10 @@ async function applyPlaceholderConfig(targetFolder, projectName) {
   const src = await resolvePlaceholderConfigPath();
   const dest = path.resolve(targetFolder, "./shared/config/config.default.ts");
   try {
-    let content = await fs.readFile(src, "utf8");
+    let content = await fs2.readFile(src, "utf8");
     content = content.replaceAll("__project_name__", displayName);
     content = content.replaceAll("__project_slug__", projectName);
-    await fs.writeFile(dest, content, "utf8");
+    await fs2.writeFile(dest, content, "utf8");
   } catch (err) {
     if (err.code === "ENOENT") {
       console.info(`
@@ -473,10 +492,75 @@ ${warningMark} Placeholder config "${src}" not found > Skip`);
   }
 }
 
+// src/utils/download-template.ts
+import { mkdir, writeFile } from "fs/promises";
+import { dirname, join } from "path";
+import { parseTarGzip } from "nanotar";
+function parseGithubRepo(template) {
+  const [owner, repo] = template.replace(/^github:/, "").split("/");
+  if (!owner || !repo) {
+    throw new Error(`Invalid template '${template}'. Expected 'github:owner/repo'.`);
+  }
+  return { owner, repo };
+}
+async function downloadGithubTemplate(template, ref, targetFolder) {
+  const { owner, repo } = parseGithubRepo(template);
+  const url = `https://codeload.github.com/${owner}/${repo}/tar.gz/${ref}`;
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error(`Failed to download template ${owner}/${repo}@${ref}: ${response.status} ${response.statusText}`);
+  }
+  const archive = new Uint8Array(await response.arrayBuffer());
+  const entries = await parseTarGzip(archive);
+  for (const entry of entries) {
+    if (entry.type !== "file" || !entry.data) continue;
+    const relativePath = entry.name.replace(/^[^/]+\//, "");
+    if (!relativePath) continue;
+    const dest = join(targetFolder, relativePath);
+    await mkdir(dirname(dest), { recursive: true });
+    const mode = entry.attrs?.mode ? Number.parseInt(entry.attrs.mode, 8) : void 0;
+    await writeFile(dest, entry.data, mode ? { mode } : void 0);
+  }
+}
+
+// src/utils/list-template-files.ts
+import { readdir, readFile } from "fs/promises";
+import { join as join2 } from "path";
+import ignore from "ignore";
+async function listTemplateFiles(root) {
+  const ig = ignore().add([".git", "node_modules"]);
+  try {
+    ig.add(await readFile(join2(root, ".gitignore"), "utf8"));
+  } catch {
+  }
+  const files = [];
+  async function walk(relDir) {
+    const entries = await readdir(relDir ? join2(root, relDir) : root, { withFileTypes: true });
+    for (const entry of entries) {
+      const rel = relDir ? `${relDir}/${entry.name}` : entry.name;
+      if (ig.ignores(entry.isDirectory() ? `${rel}/` : rel)) continue;
+      if (entry.isDirectory()) await walk(rel);
+      else if (entry.isFile()) files.push(rel);
+    }
+  }
+  await walk("");
+  return files;
+}
+
 // src/utils/progress.ts
 import ora from "ora";
 import pc4 from "picocolors";
 var activeSpinner = null;
+function pauseSpinner() {
+  if (activeSpinner) {
+    activeSpinner.stop();
+  }
+}
+function resumeSpinner() {
+  if (activeSpinner) {
+    activeSpinner.start();
+  }
+}
 function createProgress(title, silent = false) {
   const completedSteps = [];
   const spinner = ora({
@@ -515,48 +599,48 @@ function createProgress(title, silent = false) {
       spinner.stop();
       activeSpinner = null;
       log(`${pc4.red("\u2717")} ${pc4.red(message)}`);
-    },
-    wrap: async (fn) => {
-      try {
-        return await fn();
-      } catch (error) {
-        const errorMessage = error instanceof Error ? error.message : String(error);
-        spinner.stop();
-        activeSpinner = null;
-        log(pc4.cyan(`
-${title}`));
-        for (const step of completedSteps) {
-          log(pc4.gray(`  \u251C\u2500 ${step}`));
-        }
-        log(pc4.red(`  \u2514\u2500 \u2717 ${errorMessage}`));
-        throw error;
-      }
     }
   };
 }
 
-// src/utils/run-package-manager-command.ts
-import spawn from "nano-spawn";
-async function runPackageManagerCommand(packageManager2, args, env = {}) {
-  try {
-    await spawn(packageManager2, args, {
-      env: { ...process.env, ...env },
-      stdio: ["pipe", "pipe", "pipe"]
-    });
-  } catch (error) {
-    const err = error;
-    throw new Error(`"${packageManager2} ${args.join(" ")}" failed ${err.stdout || ""} ${err.stderr || ""}`);
+// src/utils/scan-optional-modules.ts
+import { readdir as readdir2, readFile as readFile2 } from "fs/promises";
+import { dirname as dirname2, join as join3, relative } from "path";
+var SKIP_DIRS = /* @__PURE__ */ new Set(["node_modules", ".git", "dist", "build", ".turbo", "coverage"]);
+async function scanOptionalModules(targetFolder) {
+  const files = [];
+  await collectModuleFiles(targetFolder, files);
+  const modules = [];
+  for (const file of files) {
+    const src = await readFile2(file, "utf8");
+    if (!/optional:\s*true/.test(src)) continue;
+    const name = src.match(/name:\s*['"]([^'"]+)['"]/)?.[1];
+    const description = src.match(/description:\s*['"]([^'"]+)['"]/)?.[1] ?? "";
+    if (!name) continue;
+    modules.push({ name, description, folder: relative(targetFolder, dirname2(file)) });
+  }
+  return modules.sort((a, b) => a.name.localeCompare(b.name));
+}
+function optionalModuleFolders({ name, folder }) {
+  return [
+    folder,
+    `frontend/src/routes/_public/_${name}`,
+    `frontend/src/routes/_public/${name}`,
+    `frontend/src/routes/_app/_${name}`,
+    `frontend/src/routes/_app/${name}`,
+    `frontend/public/static/${name}`
+  ];
+}
+async function collectModuleFiles(dir, out) {
+  const entries = await readdir2(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await collectModuleFiles(join3(dir, entry.name), out);
+    } else if (entry.name.endsWith("-module.ts")) {
+      out.push(join3(dir, entry.name));
+    }
   }
-}
-async function install(packageManager2) {
-  return runPackageManagerCommand(packageManager2, ["install"], {
-    NODE_ENV: "development"
-  });
-}
-async function generate(packageManager2) {
-  return runPackageManagerCommand(packageManager2, ["generate"], {
-    NODE_ENV: "development"
-  });
 }
 
 // src/create.ts
@@ -569,9 +653,9 @@ function shouldSkipStep(name) {
 async function create({
   projectName,
   targetFolder,
-  newBranchName: newBranchName2,
   packageManager: packageManager2,
   templateUrl,
+  templateRef,
   portOffset,
   adminEmail,
   silent = false
@@ -582,83 +666,100 @@ async function create({
   const progress = createProgress("creating project", silent);
   try {
     progress.step("creating project folder");
-    await mkdir(targetFolder, { recursive: true });
+    await mkdir2(targetFolder, { recursive: true });
     process.chdir(targetFolder);
     if (isLocalTemplate) {
       progress.step("copying local template");
       const sourcePath = resolve2(originalCwd, templateUrl);
-      if (targetFolder.startsWith(sourcePath)) {
+      const rel = relative2(sourcePath, targetFolder);
+      const targetInsideTemplate = rel === "" || !rel.startsWith("..") && !isAbsolute(rel);
+      if (targetInsideTemplate) {
         throw new Error(
           `Cannot create project inside the template directory.
   Run from outside: cd ~ && pnpm create @cellajs/cella ${projectName} --template ${templateUrl}`
         );
       }
-      await cp(sourcePath, targetFolder, {
-        recursive: true,
-        filter: (src) => !src.includes("node_modules") && !src.includes(".git")
-      });
+      const tracked = await listTemplateFiles(sourcePath);
+      for (const rel2 of tracked) {
+        const src = join4(sourcePath, rel2);
+        if (!existsSync(src)) continue;
+        const dest = join4(targetFolder, rel2);
+        await mkdir2(dirname3(dest), { recursive: true });
+        await cp(src, dest);
+      }
     } else {
-      progress.step("downloading cella template");
-      await downloadTemplate(template, {
-        cwd: process.cwd(),
-        dir: targetFolder,
-        force: true,
-        provider: "github"
-      });
+      const ref = templateRef ?? "main";
+      progress.step(`downloading cella template${templateRef ? ` (${templateRef})` : ""}`);
+      await downloadGithubTemplate(template, ref, targetFolder);
     }
+    if (!silent) await promptOptionalModules(targetFolder);
     progress.step("cleaning template");
     const displayName = projectName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
     await cleanTemplate({ targetFolder, projectName, displayName, portOffset, adminEmail });
-    if (!shouldSkipStep("install")) {
-      progress.step("installing dependencies");
-      await install(packageManager2);
-    }
-    if (!shouldSkipStep("generate")) {
-      progress.step("generating migrations");
-      await generate(packageManager2);
-    }
-    const gitFolderPath = join(targetFolder, ".git");
+    const gitFolderPath = join4(targetFolder, ".git");
     if (!shouldSkipStep("git") && !existsSync(gitFolderPath)) {
       progress.step("initializing git");
       await gitInit(targetFolder);
       await gitAddAll(targetFolder);
       await gitCommit(targetFolder, "Initial commit");
-      if (newBranchName2) {
-        progress.step(`creating branch '${newBranchName2}'`);
-        await gitBranch(targetFolder, newBranchName2);
-        await gitCheckout(targetFolder, newBranchName2);
-      }
     }
     if (!shouldSkipStep("remote")) {
       progress.step("adding upstream remote");
       await addRemote({ targetFolder, silent: true });
     }
-    progress.done(`created ${projectName}`);
+    progress.done(pc5.bold(`created ${projectName}`));
   } catch (error) {
     progress.fail(error instanceof Error ? error.message : String(error));
-    process.exit(1);
+    throw error;
   }
   const needsCd = originalCwd !== targetFolder;
-  const relativePath = relative(originalCwd, targetFolder);
+  const relativePath = relative2(originalCwd, targetFolder);
   showSuccess(projectName, targetFolder, relativePath, needsCd, packageManager2);
 }
+async function promptOptionalModules(targetFolder) {
+  const modules = await scanOptionalModules(targetFolder);
+  if (modules.length === 0) return;
+  if (!process.stdin.isTTY) return;
+  pauseSpinner();
+  console.info();
+  const keep = await checkbox(
+    {
+      message: "Optional modules to include",
+      // Leading space on the radio icons adds a gap after the cursor (inquirer renders
+      // `${cursor}${checkbox} ${name}` with no space between cursor and checkbox).
+      theme: { icon: { checked: ` ${pc5.green("\u25C9")}`, unchecked: " \u25EF" } },
+      choices: modules.map((m) => ({
+        name: `${m.name} ${pc5.dim(`\xB7 ${m.description}`)}`,
+        value: m.name,
+        checked: true
+      }))
+    },
+    // Clear the answered prompt so we can print a compact, non-bold summary that lists
+    // only the kept module names (not their descriptions).
+    { clearPromptOnDone: true }
+  );
+  confirmChoice("Optional modules", keep.length ? keep.join(", ") : pc5.dim("none"));
+  resumeSpinner();
+  const folders = modules.filter((m) => !keep.includes(m.name)).flatMap(optionalModuleFolders);
+  await Promise.all(folders.map((f) => rm(join4(targetFolder, f), { recursive: true, force: true })));
+}
 
 // src/utils/detect-used-ports.ts
-import { readdir, readFile } from "fs/promises";
-import { dirname, join as join2 } from "path";
+import { readdir as readdir3, readFile as readFile3 } from "fs/promises";
+import { dirname as dirname4, join as join5 } from "path";
 async function detectUsedPorts(targetFolder) {
-  const parentDir = dirname(targetFolder);
+  const parentDir = dirname4(targetFolder);
   const used = [];
   let siblings;
   try {
-    siblings = await readdir(parentDir);
+    siblings = await readdir3(parentDir);
   } catch {
     return used;
   }
   for (const name of siblings) {
-    const configPath = join2(parentDir, name, "shared/config/config.development.ts");
+    const configPath = join5(parentDir, name, "shared/config/config.development.ts");
     try {
-      const content = await readFile(configPath, "utf8");
+      const content = await readFile3(configPath, "utf8");
       const feMatch = content.match(/frontendUrl:\s*'http:\/\/localhost:(\d+)'/);
       const beMatch = content.match(/backendUrl:\s*'http:\/\/localhost:(\d+)'/);
       if (feMatch && beMatch) {
@@ -685,23 +786,63 @@ function findNextOffset(usedPorts) {
 }
 
 // src/utils/extract-package-json-version-from-uri.ts
-import axios from "axios";
 async function extractPackageJsonVersionFromUri(repositoryUrl, branch = "main") {
   const [owner, repo] = repositoryUrl.replace("github:", "").split("/");
-  const packageJsonUrl = `https://raw.githubusercontent.com/${owner}/${repo}/${branch}/package.json`;
+  const apiUrl = `https://api.github.com/repos/${owner}/${repo}/contents/package.json?ref=${branch}`;
   try {
-    const response = await axios.get(packageJsonUrl);
-    const packageJson = response.data;
+    const response = await fetch(apiUrl, {
+      headers: { Accept: "application/vnd.github.raw+json" }
+    });
+    if (!response.ok) return "unknown";
+    const packageJson = await response.json();
     return packageJson.version || "unknown";
-  } catch (error) {
+  } catch {
     return "unknown";
   }
 }
 
+// src/utils/fetch-template-metadata.ts
+function parseRepo(repositoryUrl) {
+  const [owner, repo] = repositoryUrl.replace("github:", "").split("/");
+  return [owner, repo];
+}
+function toDate(iso) {
+  return iso ? iso.slice(0, 10) : "unknown";
+}
+var GITHUB_HEADERS = { Accept: "application/vnd.github+json" };
+async function fetchLatestRelease(repositoryUrl) {
+  const [owner, repo] = parseRepo(repositoryUrl);
+  const apiUrl = `https://api.github.com/repos/${owner}/${repo}/releases?per_page=30`;
+  try {
+    const response = await fetch(apiUrl, { headers: GITHUB_HEADERS });
+    if (!response.ok) return null;
+    const releases = await response.json();
+    const release = releases.find((r) => !r.draft && !r.prerelease && /^v\d/.test(r.tag_name ?? ""));
+    if (!release?.tag_name) return null;
+    return { tag: release.tag_name, date: toDate(release.published_at) };
+  } catch {
+    return null;
+  }
+}
+async function fetchLatestCommit(repositoryUrl, branch = "main") {
+  const [owner, repo] = parseRepo(repositoryUrl);
+  const apiUrl = `https://api.github.com/repos/${owner}/${repo}/commits/${branch}`;
+  try {
+    const response = await fetch(apiUrl, { headers: GITHUB_HEADERS });
+    if (!response.ok) return null;
+    const data = await response.json();
+    if (!data.sha) return null;
+    const message = (data.commit?.message ?? "").split("\n")[0];
+    return { sha: data.sha, shortSha: data.sha.slice(0, 7), message, date: toDate(data.commit?.author?.date) };
+  } catch {
+    return null;
+  }
+}
+
 // src/utils/is-empty-directory.ts
-import { readdir as readdir2 } from "fs/promises";
+import { readdir as readdir4 } from "fs/promises";
 async function isEmptyDirectory(path2) {
-  const files = await readdir2(path2);
+  const files = await readdir4(path2);
   return files.length === 0 || files.length === 1 && files[0] === ".git";
 }
 
@@ -711,6 +852,7 @@ async function main() {
   showWelcome(templateVersion);
   const promptTheme = { prefix: "", style: { answer: (text) => text } };
   const promptContext = { clearPromptOnDone: true };
+  const templateRef = cli.options.template ? void 0 : await promptTemplateRef(promptTheme, promptContext);
   if (!cli.directory) {
     cli.directory = await input(
       {
@@ -725,9 +867,6 @@ async function main() {
       promptContext
     );
   }
-  if (!cli.newBranchName) {
-    cli.newBranchName = "development";
-  }
   const targetFolder = resolve3(cli.directory);
   const projectName = basename2(targetFolder)?.toLowerCase() || "project";
   if (existsSync2(targetFolder) && !await isEmptyDirectory(targetFolder)) {
@@ -749,44 +888,84 @@ async function main() {
     }
   }
   const portOffset = cli.options.portOffset ?? await promptPortOffset(targetFolder, promptTheme, promptContext);
+  confirmChoice("Port offset", formatOffset(portOffset));
   const adminEmail = cli.options.adminEmail ?? await input(
     {
       message: "Admin email for initial seed user",
-      default: `admin@${projectName}.com`,
+      default: "admin@example.com",
       theme: promptTheme
     },
     promptContext
   );
+  confirmChoice("Admin email", adminEmail);
   const createOptions = {
     projectName,
     targetFolder,
-    newBranchName: cli.newBranchName,
     packageManager: cli.packageManager,
     templateUrl: cli.options.template,
+    templateRef,
     portOffset,
     adminEmail
   };
   await create(createOptions);
 }
-main().catch(console.error);
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});
+async function promptTemplateRef(theme, context) {
+  const [release, commit] = await Promise.all([fetchLatestRelease(TEMPLATE_URL), fetchLatestCommit(TEMPLATE_URL)]);
+  if (!release && !commit) return void 0;
+  console.info(pc6.dim("You are about to install the Cella template."));
+  console.info();
+  if (release) console.info(`  Latest release:  ${release.tag} ${pc6.dim(`\xB7 ${release.date}`)}`);
+  if (commit) {
+    console.info(`  Latest commit:  ${commit.shortSha} ${pc6.dim(`\xB7 ${commit.message} \xB7 ${commit.date}`)}`);
+    const repo = TEMPLATE_URL.replace("github:", "");
+    console.info(`  ${pc6.gray(`https://github.com/${repo}/commit/${commit.sha}`)}`);
+  }
+  console.info();
+  if (!release) return commit?.sha;
+  if (!commit) return release.tag;
+  const choice = await select(
+    {
+      message: "Start from",
+      theme,
+      choices: [
+        { name: "Latest release", value: "release" },
+        { name: "Latest commit", value: "commit" }
+      ]
+    },
+    context
+  );
+  if (choice === "release") {
+    confirmChoice("Latest release", release.tag);
+    return release.tag;
+  }
+  confirmChoice("Latest commit", commit.shortSha);
+  return commit.sha;
+}
 function formatOffset(o, suffix = "") {
   return `${o} \u2192 :${3e3 + o} / :${4e3 + o} / :${5432 + o}${suffix}`;
 }
 async function promptPortOffset(targetFolder, theme, context) {
   const usedPorts = await detectUsedPorts(targetFolder);
   const suggested = findNextOffset(usedPorts);
+  let message = `${pc6.bold("Port offset")} ${pc6.dim("\xB7 to avoid conflicts with other forks/clones")}`;
   if (usedPorts.length > 0) {
-    console.info(pc5.dim("\nDetected cella forks in sibling directories:"));
-    for (const p of usedPorts) {
-      console.info(pc5.dim(`  ${p.project}: frontend :${p.frontend}, backend :${p.backend} (offset ${p.offset})`));
-    }
-    console.info();
+    const count = usedPorts.length;
+    message += pc6.dim(`
+Detected ${count} sibling fork${count === 1 ? "" : "s"} \xB7 suggested offset ${suggested}`);
   }
-  const presets = [0, 10, 20, 30].filter((o) => o !== suggested);
+  const portTheme = {
+    ...theme,
+    style: { ...theme.style ?? {}, message: (text) => text }
+  };
+  const presets = [10, 20, 30].filter((o) => o !== suggested);
   const choice = await select(
     {
-      message: "Port offset (avoids conflicts with sibling forks)",
-      theme,
+      message,
+      theme: portTheme,
       choices: [
         ...suggested > 0 ? [{ name: formatOffset(suggested, " (suggested)"), value: suggested }] : [],
         { name: formatOffset(0, " (default)"), value: 0 },