@cellajs/create-cella 0.2.1 → 0.2.3

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.1",
+  version: "0.2.3",
   private: false,
   license: "MIT",
   description: "Cella is a TypeScript template to create web apps with sync and offline capabilities.",
@@ -45,6 +45,7 @@ var package_default = {
   },
   scripts: {
     start: "tsx ./src/create-cella-cli.ts",
+    try: "tsx ./src/create-cella-cli.ts ../../../cella-try-app --template ../.. --skip-install",
     clean: "rimraf ./dist",
     build: "tsup",
     "test-build": "pnpm run build && node index.js",
@@ -54,26 +55,26 @@ 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",
+    "test:release": "pnpm run build && vitest run tests/release-smoke.test.ts",
     "test:watch": "vitest"
   },
   dependencies: {
     "@inquirer/prompts": "^8.5.2",
-    axios: "^1.17.0",
     commander: "^15.0.0",
-    giget: "^3.1.2",
+    giget: "^3.3.0",
     "nano-spawn": "^2.0.0",
-    ora: "^9.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:",
+    "@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",
+    tsup: "^8.5.1",
+    tsx: "^4.22.4",
+    typescript: "^6.0.3",
+    vitest: "^4.1.9"
   }
 };
 
@@ -84,15 +85,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"];
@@ -101,12 +99,12 @@ var TO_COPY = {
   "./frontend/.env.example": "./frontend/.env",
   "./info/QUICKSTART.md": "README.md"
 };
-var PLACEHOLDER_CONFIG = "./cli/create-cella/configs/default-config.ts.template";
+var PLACEHOLDER_CONFIG = "configs/default-config.ts.template";
 async function generateEnvFromExample(examplePath, replacements) {
-  const { readFile: readFile2 } = await import("fs/promises");
+  const { readFile: readFile3 } = await import("fs/promises");
   let content;
   try {
-    content = await readFile2(examplePath, "utf8");
+    content = await readFile3(examplePath, "utf8");
   } catch {
     return null;
   }
@@ -115,16 +113,12 @@ async function generateEnvFromExample(examplePath, replacements) {
     return match;
   });
 }
-function getRootEnvReplacements(slug, portOffset) {
-  return {
-    PROJECT_SLUG: slug,
-    DB_PORT: String(5432 + portOffset),
-    DB_TEST_PORT: String(5434 + portOffset)
-  };
-}
-function getBackendEnvReplacements(adminEmail, portOffset) {
+function getBackendEnvReplacements(slug, adminEmail, portOffset) {
   const db = 5432 + portOffset;
   return {
+    PROJECT_SLUG: slug,
+    DB_PORT: String(db),
+    DB_TEST_PORT: String(5434 + portOffset),
     DATABASE_URL: `postgres://runtime_role:dev_password@0.0.0.0:${db}/postgres`,
     DATABASE_ADMIN_URL: `postgres://postgres:postgres@0.0.0.0:${db}/postgres`,
     DATABASE_CDC_URL: `postgres://admin_role:dev_password@0.0.0.0:${db}/postgres`,
@@ -135,12 +129,11 @@ function getBackendEnvReplacements(adminEmail, portOffset) {
 function generateEnvConfigs(slug, name, portOffset) {
   const fe = 3e3 + portOffset;
   const be = 4e3 + portOffset;
-  const header = "import type { DeepPartial } from '../src/builder/types';\nimport type _default from './config.default';\n";
+  const header = "import type { DeepPartial } from '../src/config-builder/types';\nimport type _default from './config.default';\n";
   const envs = {
     development: {
       props: {
         slug: `${slug}-development`,
-        debug: false,
         domain: "",
         frontendUrl: `http://localhost:${fe}`,
         backendUrl: `http://localhost:${be}`,
@@ -150,7 +143,6 @@ function generateEnvConfigs(slug, name, portOffset) {
     staging: {
       props: {
         slug: `${slug}-staging`,
-        debug: false,
         domain: `${slug}.example.com`,
         frontendUrl: `https://staging.${slug}.example.com`,
         backendUrl: `https://api-staging.${slug}.example.com`,
@@ -167,7 +159,6 @@ function generateEnvConfigs(slug, name, portOffset) {
     test: {
       imports: "import development from './config.development';\n",
       props: {
-        debug: false,
         domain: "",
         frontendUrl: "=development.frontendUrl",
         backendUrl: "=development.backendUrl",
@@ -197,10 +188,13 @@ ${nameEntry}${body}
 }
 
 // src/create.ts
+import { execFileSync } from "child_process";
 import { existsSync } from "fs";
-import { cp, mkdir } from "fs/promises";
-import { join, relative, resolve as resolve2 } from "path";
+import { cp, mkdir, rm } from "fs/promises";
+import { dirname as dirname2, isAbsolute, join as join2, relative as relative2, resolve as resolve2 } from "path";
+import { checkbox } from "@inquirer/prompts";
 import { downloadTemplate } from "giget";
+import pc5 from "picocolors";
 
 // src/utils/git/command.ts
 import { execFile } from "child_process";
@@ -223,13 +217,7 @@ async function gitAddAll(repoPath) {
   return runGitCommand(["add", "."], repoPath);
 }
 async function gitCommit(repoPath, message) {
-  return runGitCommand(["commit", "-m", message], repoPath);
-}
-async function gitBranch(repoPath, branchName) {
-  return runGitCommand(["branch", branchName], repoPath);
-}
-async function gitCheckout(repoPath, branchName) {
-  return runGitCommand(["checkout", branchName], repoPath);
+  return runGitCommand(["commit", "--quiet", "--no-verify", "-m", message], repoPath);
 }
 async function gitRemoteGetUrl(repoPath, remoteName) {
   return runGitCommand(["remote", "get-url", remoteName], repoPath);
@@ -286,10 +274,19 @@ function validateProjectName(name) {
 }
 
 // src/modules/cli/commands.ts
+function parsePortOffset(value) {
+  const parsed = Number(value);
+  if (!Number.isInteger(parsed) || parsed < 0 || parsed > 490) {
+    throw new InvalidArgumentError("Port offset must be an integer between 0 and 490");
+  }
+  if (parsed % 10 !== 0) {
+    throw new InvalidArgumentError("Port offset must be a multiple of 10");
+  }
+  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)").action((name) => {
+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").option("--skip-install", "scaffold only: skip dependency installation and migration generation").action((name) => {
   const trimmedName = typeof name === "string" ? name.trim() : name;
   if (trimmedName) {
     const validation = validateProjectName(basename(resolve(trimmedName)));
@@ -305,7 +302,6 @@ function runCli() {
     options,
     args: command.args,
     directory,
-    newBranchName,
     packageManager
   };
 }
@@ -329,32 +325,47 @@ 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.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 path from "path";
+import { fileURLToPath } from "url";
 import pc3 from "picocolors";
 var warningMark = pc3.yellow("\u26A0");
+async function resolvePlaceholderConfigPath() {
+  const here = path.dirname(fileURLToPath(import.meta.url));
+  const candidates = [path.resolve(here, "../..", PLACEHOLDER_CONFIG), path.resolve(here, "..", PLACEHOLDER_CONFIG)];
+  for (const candidate of candidates) {
+    try {
+      await fs.access(candidate);
+      return candidate;
+    } catch {
+    }
+  }
+  return candidates[0];
+}
 async function cleanTemplate({
   targetFolder,
   projectName,
@@ -374,14 +385,7 @@ async function cleanTemplate({
           await copyFile(srcAbsolutePath, destAbsolutePath);
         }
         await applyPlaceholderConfig(targetFolder, projectName);
-        const rootReplacements = getRootEnvReplacements(projectName, portOffset);
-        const rootEnv = await generateEnvFromExample(path.resolve(targetFolder, ".env.example"), rootReplacements);
-        await fs.writeFile(
-          path.resolve(targetFolder, ".env"),
-          rootEnv ?? Object.entries(rootReplacements).map(([k, v]) => `${k}=${v}`).join("\n"),
-          "utf8"
-        );
-        const backendReplacements = getBackendEnvReplacements(adminEmail, portOffset);
+        const backendReplacements = getBackendEnvReplacements(projectName, adminEmail, portOffset);
         const backendEnv = await generateEnvFromExample(
           path.resolve(targetFolder, "backend/.env.example"),
           backendReplacements
@@ -447,7 +451,7 @@ ${warningMark} Source file "${src}" does not exist > Skip copy`);
 }
 async function applyPlaceholderConfig(targetFolder, projectName) {
   const displayName = projectName.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
-  const src = path.resolve(targetFolder, PLACEHOLDER_CONFIG);
+  const src = await resolvePlaceholderConfigPath();
   const dest = path.resolve(targetFolder, "./shared/config/config.default.ts");
   try {
     let content = await fs.readFile(src, "utf8");
@@ -468,6 +472,16 @@ ${warningMark} Placeholder config "${src}" not found > Skip`);
 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({
@@ -506,22 +520,6 @@ 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;
-      }
     }
   };
 }
@@ -550,18 +548,62 @@ async function generate(packageManager2) {
   });
 }
 
+// src/utils/scan-optional-modules.ts
+import { readdir, readFile } from "fs/promises";
+import { dirname, join, 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 readFile(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, dirname(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 readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    if (entry.isDirectory()) {
+      if (SKIP_DIRS.has(entry.name)) continue;
+      await collectModuleFiles(join(dir, entry.name), out);
+    } else if (entry.name.endsWith("-module.ts")) {
+      out.push(join(dir, entry.name));
+    }
+  }
+}
+
 // src/create.ts
 function isLocalPath(path2) {
   return path2.startsWith("/") || path2.startsWith("./") || path2.startsWith("../");
 }
+function shouldSkipStep(name) {
+  return process.env[`CREATE_CELLA_SKIP_${name.toUpperCase()}`] === "true";
+}
 async function create({
   projectName,
   targetFolder,
-  newBranchName: newBranchName2,
   packageManager: packageManager2,
   templateUrl,
+  templateRef,
   portOffset,
   adminEmail,
+  skipInstall = false,
   silent = false
 }) {
   const originalCwd = process.cwd();
@@ -575,72 +617,121 @@ async function create({
     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")
-      });
+      let tracked = [];
+      try {
+        tracked = execFileSync("git", ["ls-files", "--cached", "--others", "--exclude-standard", "-z"], {
+          cwd: sourcePath
+        }).toString().split("\0").filter(Boolean);
+      } catch {
+      }
+      if (tracked.length > 0) {
+        for (const rel2 of tracked) {
+          const src = join2(sourcePath, rel2);
+          if (!existsSync(src)) continue;
+          const dest = join2(targetFolder, rel2);
+          await mkdir(dirname2(dest), { recursive: true });
+          await cp(src, dest);
+        }
+      } else {
+        await cp(sourcePath, targetFolder, {
+          recursive: true,
+          filter: (src) => !src.includes("node_modules") && !src.includes(".git")
+        });
+      }
     } else {
-      progress.step("downloading cella template");
-      await downloadTemplate(template, {
+      const downloadId = templateRef ? `${template}#${templateRef}` : template;
+      progress.step(`downloading cella template${templateRef ? ` (${templateRef})` : ""}`);
+      await downloadTemplate(downloadId, {
         cwd: process.cwd(),
         dir: targetFolder,
         force: true,
         provider: "github"
       });
     }
+    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 });
-    progress.step("installing dependencies");
-    await install(packageManager2);
-    progress.step("generating migrations");
-    await generate(packageManager2);
-    const gitFolderPath = join(targetFolder, ".git");
-    if (!existsSync(gitFolderPath)) {
+    if (!skipInstall && !shouldSkipStep("install")) {
+      progress.step("installing dependencies");
+      await install(packageManager2);
+    }
+    if (!skipInstall && !shouldSkipStep("generate")) {
+      progress.step("generating migrations");
+      await generate(packageManager2);
+    }
+    const gitFolderPath = join2(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);
-      }
     }
-    progress.step("adding upstream remote");
-    await addRemote({ targetFolder, silent: true });
-    progress.done(`created ${projectName}`);
+    if (!shouldSkipStep("remote")) {
+      progress.step("adding upstream remote");
+      await addRemote({ targetFolder, silent: true });
+    }
+    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(join2(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 readdir2, readFile as readFile2 } from "fs/promises";
+import { dirname as dirname3, join as join3 } from "path";
 async function detectUsedPorts(targetFolder) {
-  const parentDir = dirname(targetFolder);
+  const parentDir = dirname3(targetFolder);
   const used = [];
   let siblings;
   try {
-    siblings = await readdir(parentDir);
+    siblings = await readdir2(parentDir);
   } catch {
     return used;
   }
   for (const name of siblings) {
-    const configPath = join2(parentDir, name, "shared/config/config.development.ts");
+    const configPath = join3(parentDir, name, "shared/config/config.development.ts");
     try {
-      const content = await readFile(configPath, "utf8");
+      const content = await readFile2(configPath, "utf8");
       const feMatch = content.match(/frontendUrl:\s*'http:\/\/localhost:(\d+)'/);
       const beMatch = content.match(/backendUrl:\s*'http:\/\/localhost:(\d+)'/);
       if (feMatch && beMatch) {
@@ -667,23 +758,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 readdir3 } from "fs/promises";
 async function isEmptyDirectory(path2) {
-  const files = await readdir2(path2);
+  const files = await readdir3(path2);
   return files.length === 0 || files.length === 1 && files[0] === ".git";
 }
 
@@ -693,6 +824,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(
       {
@@ -707,9 +839,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)) {
@@ -730,45 +859,86 @@ async function main() {
       process.exit(1);
     }
   }
-  const portOffset = await promptPortOffset(targetFolder, promptTheme, promptContext);
-  const adminEmail = await input(
+  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
+    adminEmail,
+    skipInstall: cli.options.skipInstall
   };
   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 },