create-daloy 0.1.17 → 0.1.19

package/bin/create-daloy.mjs

@@ -56,6 +56,10 @@ const RENAME_ON_COPY = new Map([
   ["_gitignore", ".gitignore"],
   ["_npmrc", ".npmrc"],
   ["_env.example", ".env.example"],
+  // Directory: holds skill files for AI coding agents under
+  // `.agents/skills/<skill-name>/SKILL.md`. Templates author this as
+  // `_agents/` so npm pack does not drop the dotfolder during publish.
+  ["_agents", ".agents"],
 ]);
 
 // Templates that target a runtime instead of an npm package manager.
@@ -69,48 +73,261 @@ const NO_PACKAGE_JSON_TEMPLATES = new Set(["deno-basic"]);
 // sentinels.
 const MINIMAL_STRIP_EXTENSIONS = new Set([".ts", ".tsx", ".js", ".mjs", ".cjs", ".md"]);
 
-const COLORS = process.stdout.isTTY
+// ----------------------------------------------------------------------------
+// Terminal capability detection + style primitives.
+//
+// Zero runtime dependencies: we hand-roll color, Unicode, and box-drawing
+// helpers so the CLI ships fast and stays auditable.
+// ----------------------------------------------------------------------------
+
+const SUPPORTS_COLOR = process.stdout.isTTY && !process.env.NO_COLOR && process.env.TERM !== "dumb";
+const SUPPORTS_TRUECOLOR =
+  SUPPORTS_COLOR && (process.env.COLORTERM === "truecolor" || process.env.COLORTERM === "24bit");
+const SUPPORTS_UNICODE =
+  process.platform !== "win32" ||
+  Boolean(process.env.WT_SESSION) ||
+  process.env.TERM_PROGRAM === "vscode" ||
+  process.env.TERM === "xterm-256color";
+
+const COLORS = SUPPORTS_COLOR
   ? {
       reset: "\x1b[0m",
       bold: "\x1b[1m",
       dim: "\x1b[2m",
+      italic: "\x1b[3m",
+      underline: "\x1b[4m",
+      inverse: "\x1b[7m",
       cyan: "\x1b[36m",
       green: "\x1b[32m",
       red: "\x1b[31m",
       yellow: "\x1b[33m",
+      magenta: "\x1b[35m",
+      gray: "\x1b[90m",
+      white: "\x1b[97m",
     }
-  : { reset: "", bold: "", dim: "", cyan: "", green: "", red: "", yellow: "" };
+  : {
+      reset: "",
+      bold: "",
+      dim: "",
+      italic: "",
+      underline: "",
+      inverse: "",
+      cyan: "",
+      green: "",
+      red: "",
+      yellow: "",
+      magenta: "",
+      gray: "",
+      white: "",
+    };
 
 function color(code, s) {
   return `${code}${s}${COLORS.reset}`;
 }
 
+function rgb(r, g, b) {
+  if (!SUPPORTS_TRUECOLOR) return "";
+  return `\x1b[38;2;${r};${g};${b}m`;
+}
+
+function stringWidth(s) {
+  let width = 0;
+  for (const char of s.replace(/\x1b\[[0-9;]*m/g, "")) {
+    const code = char.codePointAt(0) ?? 0;
+    if (code < 0x20 || (code >= 0x7f && code < 0xa0)) continue;
+    if (
+      code >= 0x1100 &&
+      (code <= 0x115f ||
+        code === 0x2329 ||
+        code === 0x232a ||
+        (code >= 0x2e80 && code <= 0xa4cf && code !== 0x303f) ||
+        (code >= 0xac00 && code <= 0xd7a3) ||
+        (code >= 0xf900 && code <= 0xfaff) ||
+        (code >= 0xfe10 && code <= 0xfe19) ||
+        (code >= 0xfe30 && code <= 0xfe6f) ||
+        (code >= 0xff00 && code <= 0xff60) ||
+        (code >= 0xffe0 && code <= 0xffe6) ||
+        (code >= 0x1f300 && code <= 0x1faff))
+    ) {
+      width += 2;
+    } else {
+      width += 1;
+    }
+  }
+  return width;
+}
+
+// Unicode/ASCII glyphs used throughout the prompt UI. Symbols mirror Clack
+// and Astro's `create` flows so users get the familiar vertical-rail
+// experience, with safe ASCII fallbacks for legacy terminals.
+const SYMBOLS = SUPPORTS_UNICODE
+  ? {
+      stepActive: "\u25C6", // ◆
+      stepDone: "\u25C7", // ◇
+      radioOff: "\u25CB", // ○
+      radioOn: "\u25C9", // ◉
+      success: "\u2714", // ✔
+      warn: "\u26A0", // ⚠
+      error: "\u2716", // ✖
+      info: "\u2139", // ℹ
+      bar: "\u2502", // │
+      arrow: "\u2192", // →
+      pointer: "\u276F", // ❯
+      sparkle: "\u2728", // ✨
+      star: "\u2605", // ★
+      cornerTL: "\u256D", // ╭
+      cornerTR: "\u256E", // ╮
+      cornerBL: "\u2570", // ╰
+      cornerBR: "\u256F", // ╯
+      lineH: "\u2500", // ─
+      lineV: "\u2502", // │
+    }
+  : {
+      stepActive: "*",
+      stepDone: "o",
+      radioOff: "( )",
+      radioOn: "(*)",
+      success: "v",
+      warn: "!",
+      error: "x",
+      info: "i",
+      bar: "|",
+      arrow: ">",
+      pointer: ">",
+      sparkle: "*",
+      star: "*",
+      cornerTL: "+",
+      cornerTR: "+",
+      cornerBL: "+",
+      cornerBR: "+",
+      lineH: "-",
+      lineV: "|",
+    };
+
+// Pretty rail-printer. All interactive prompts and status lines flow through
+// these helpers so the column with the vertical bar stays aligned.
+const BAR = color(COLORS.gray, SYMBOLS.bar);
+
+function printIntro(title) {
+  console.log(`${color(COLORS.cyan, SYMBOLS.cornerTL + SYMBOLS.lineH)}  ${color(COLORS.bold, title)}`);
+  console.log(BAR);
+}
+
+function printOutro(text) {
+  console.log(`${color(COLORS.cyan, SYMBOLS.cornerBL + SYMBOLS.lineH)}  ${text}`);
+}
+
+function printRailLine(text = "") {
+  console.log(`${BAR}  ${text}`);
+}
+
+function printRailGap() {
+  console.log(BAR);
+}
+
+// Render a horizontally-bounded box with a title bar. Used for the welcome
+// banner and the final "Next steps" outro.
+function renderBox(lines, options = {}) {
+  const innerPadding = 2;
+  const contentWidth = Math.max(40, ...lines.map((line) => stringWidth(line)));
+  const horizontal = SYMBOLS.lineH.repeat(contentWidth + innerPadding * 2);
+  const accent = options.accent ?? COLORS.cyan;
+  const top = color(accent, `${SYMBOLS.cornerTL}${horizontal}${SYMBOLS.cornerTR}`);
+  const bottom = color(accent, `${SYMBOLS.cornerBL}${horizontal}${SYMBOLS.cornerBR}`);
+  const out = [top];
+  for (const line of lines) {
+    const padding = " ".repeat(Math.max(0, contentWidth - stringWidth(line)));
+    out.push(`${color(accent, SYMBOLS.lineV)}${" ".repeat(innerPadding)}${line}${padding}${" ".repeat(innerPadding)}${color(accent, SYMBOLS.lineV)}`);
+  }
+  out.push(bottom);
+  return out.join("\n");
+}
+
+// Block-letter "DALOY" banner with a left-to-right cyan→magenta gradient when
+// the terminal supports truecolor. Falls back to a single bold-cyan line on
+// non-truecolor TTYs and to plain text in dumb terminals. The shape is built
+// from half-block characters so it stays compact (2 lines tall).
+const LOGO_LINES = [
+  " \u2588\u2580\u2584    \u2584\u2580\u2588    \u2588      \u2588\u2580\u2588   \u2588   \u2588 ",
+  " \u2588\u2584\u2580    \u2588\u2580\u2588    \u2588\u2584\u2584   \u2588\u2584\u2588    \u2580\u2584\u2580 ",
+];
+
+function gradientLine(line, startRgb, endRgb) {
+  if (!SUPPORTS_TRUECOLOR) return color(COLORS.cyan, line);
+  const chars = [...line];
+  const max = Math.max(1, chars.length - 1);
+  let out = "";
+  for (let i = 0; i < chars.length; i += 1) {
+    const ratio = i / max;
+    const r = Math.round(startRgb[0] + (endRgb[0] - startRgb[0]) * ratio);
+    const g = Math.round(startRgb[1] + (endRgb[1] - startRgb[1]) * ratio);
+    const b = Math.round(startRgb[2] + (endRgb[2] - startRgb[2]) * ratio);
+    out += `${rgb(r, g, b)}${chars[i]}`;
+  }
+  return `${out}${COLORS.reset}`;
+}
+
+function printBanner(version) {
+  if (!SUPPORTS_UNICODE) {
+    console.log(`\n${color(COLORS.bold, "create-daloy")}  ${color(COLORS.dim, `v${version}`)}`);
+    console.log(color(COLORS.dim, "Contract-first REST APIs for Node, Bun, Deno, Vercel Edge, and Workers"));
+    console.log(color(COLORS.dim, "https://daloyjs.dev\n"));
+    return;
+  }
+  const start = [56, 189, 248]; // sky-400
+  const end = [217, 70, 239]; // fuchsia-500
+  console.log("");
+  for (const line of LOGO_LINES) {
+    console.log(` ${gradientLine(line, start, end)}`);
+  }
+  // Build the welcome content lines (each contains its own ANSI color codes).
+  const headline = `${color(COLORS.bold, "Welcome to DaloyJS")}  ${color(COLORS.gray, `\u2014 v${version}`)}`;
+  const subline = color(COLORS.dim, "Contract-first REST APIs for Node, Bun, Deno, Vercel Edge, and Workers.");
+  const docs = `${color(COLORS.gray, "docs:")} ${color(COLORS.cyan, "https://daloyjs.dev/docs")}`;
+  console.log("");
+  console.log(renderBox([headline, subline, "", docs]));
+  console.log("");
+}
+
+
 function printHelp() {
-  console.log(`${color(COLORS.bold, "create-daloy")} - scaffold a DaloyJS project
-
-Usage:
-  pnpm create daloy@latest [project-name] [options]
-  npm  create daloy@latest [project-name] [options]
-
-Options:
-  --template <name>          ${TEMPLATES.join(" | ")}  (default: node-basic)
-  --package-manager <pm>     ${PACKAGE_MANAGERS.join(" | ")}  (default: pnpm)
-  --list-templates           Print available templates and exit.
-  --install / --no-install   Install dependencies after scaffolding.
-  --git / --no-git           Initialize a git repository.
-  --minimal                  Strip the bookstore + Swagger/OpenAPI demo routes.
-  --force                    Overwrite an existing non-empty directory.
-  --yes, -y                  Accept all defaults; never prompt.
-  --help, -h                 Print this help.
-  --version, -v              Print version.
+  const heading = (text) => color(COLORS.bold + COLORS.cyan, text);
+  console.log(`
+${color(COLORS.bold, "create-daloy")}  ${color(COLORS.dim, "\u2014 scaffold a DaloyJS project")}
+
+${heading("Usage")}
+  ${color(COLORS.cyan, "pnpm")} create daloy@latest ${color(COLORS.dim, "[project-name] [options]")}
+  ${color(COLORS.cyan, "npm")}  create daloy@latest ${color(COLORS.dim, "[project-name] [options]")}
+  ${color(COLORS.cyan, "yarn")} create daloy       ${color(COLORS.dim, "[project-name] [options]")}
+  ${color(COLORS.cyan, "bun")}  create daloy       ${color(COLORS.dim, "[project-name] [options]")}
+
+${heading("Options")}
+  ${color(COLORS.green, "--template <name>")}          ${TEMPLATES.join(" | ")}  ${color(COLORS.dim, "(default: node-basic)")}
+  ${color(COLORS.green, "--package-manager <pm>")}     ${PACKAGE_MANAGERS.join(" | ")}  ${color(COLORS.dim, "(default: pnpm)")}
+  ${color(COLORS.green, "--list-templates")}           Print available templates and exit.
+  ${color(COLORS.green, "--install / --no-install")}   Install dependencies after scaffolding.
+  ${color(COLORS.green, "--git / --no-git")}           Initialize a git repository.
+  ${color(COLORS.green, "--minimal")}                  Strip the bookstore + Swagger/OpenAPI demo routes.
+  ${color(COLORS.green, "--force")}                    Overwrite an existing non-empty directory.
+  ${color(COLORS.green, "--yes, -y")}                  Accept all defaults; never prompt.
+  ${color(COLORS.green, "--help, -h")}                 Print this help.
+  ${color(COLORS.green, "--version, -v")}              Print version.
+
+${heading("Docs")}  ${color(COLORS.cyan, "https://daloyjs.dev/docs")}
 `);
 }
 
 function printTemplates() {
-  console.log(color(COLORS.bold, "Available DaloyJS templates\n"));
+  console.log("");
+  console.log(`${color(COLORS.cyan, SYMBOLS.sparkle)}  ${color(COLORS.bold, "Available DaloyJS templates")}`);
+  console.log("");
+  const valueWidth = Math.max(...TEMPLATE_OPTIONS.map((option) => option.value.length));
   for (const option of TEMPLATE_OPTIONS) {
-    console.log(`  ${color(COLORS.cyan, option.value.padEnd(18))} ${option.title}`);
-    console.log(color(COLORS.dim, `  ${" ".repeat(18)} ${option.description}\n`));
+    const value = color(COLORS.cyan, option.value.padEnd(valueWidth));
+    const title = color(COLORS.bold, option.title);
+    console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${value}  ${title}`);
+    console.log(`    ${color(COLORS.dim, option.description)}`);
+    console.log("");
   }
 }
 
@@ -157,7 +374,7 @@ function parseArgs(argv) {
     else if (a?.startsWith("--pm=")) out.packageManager = a.slice("--pm=".length);
     else if (a && !a.startsWith("-") && out.projectName === undefined) out.projectName = a;
     else if (a) {
-      console.error(color(COLORS.red, `Unknown argument: ${a}`));
+      logError(`Unknown argument: ${a}`);
       process.exit(1);
     }
   }
@@ -223,7 +440,16 @@ async function patchPackageJson(dir, projectName, packageManager) {
 
 async function patchTemplateTextFiles(dir, packageManager) {
   if (packageManager === "pnpm") return;
-  for (const fileName of ["README.md", "AGENTS.md", "SKILL.md"]) {
+  // README.md and AGENTS.md sit at the repo root; SKILL.md lives under
+  // `.agents/skills/daloyjs-best-practices/` so it follows the open
+  // "agents/skills" convention. After copyTemplate runs, the `_agents`
+  // template folder has already been renamed to `.agents`.
+  const targets = [
+    "README.md",
+    "AGENTS.md",
+    path.join(".agents", "skills", "daloyjs-best-practices", "SKILL.md"),
+  ];
+  for (const fileName of targets) {
     const file = path.join(dir, fileName);
     if (!existsSync(file)) continue;
     const raw = await readFile(file, "utf8");
@@ -360,17 +586,59 @@ function run(cmd, args, cwd) {
   });
 }
 
+// Same as `run`, but captures output so the spinner can stay clean. The
+// transcript tail is returned so callers can replay useful failure context
+// without buffering unbounded package-manager output in memory.
+function runQuiet(cmd, args, cwd) {
+  return new Promise((resolve) => {
+    const maxOutputBytes = 64 * 1024;
+    let output = "";
+    const appendOutput = (chunk) => {
+      output += chunk.toString("utf8");
+      if (output.length > maxOutputBytes) output = output.slice(-maxOutputBytes);
+    };
+    const proc = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], shell: process.platform === "win32" });
+    proc.stdout.on("data", appendOutput);
+    proc.stderr.on("data", appendOutput);
+    proc.on("exit", (code) => resolve({ code: code ?? 0, output }));
+    proc.on("error", (err) => resolve({ code: 1, output: String(err?.message ?? err) }));
+  });
+}
+
+// ----------------------------------------------------------------------------
+// Prompt primitives.
+//
+// `ask`/`askYesNo` use readline for resilience (paste, history, multi-line
+// input). `askChoice` upgrades to raw-mode arrow-key navigation when stdin is
+// a TTY, with a numbered fallback used by the readline-driven tests.
+// ----------------------------------------------------------------------------
+
+function printPromptHeader(question) {
+  console.log(`${color(COLORS.cyan, SYMBOLS.stepActive)}  ${color(COLORS.bold, question)}`);
+}
+
+function printPromptResult(question, value) {
+  console.log(`${color(COLORS.green, SYMBOLS.stepDone)}  ${question}  ${color(COLORS.dim, SYMBOLS.arrow)} ${color(COLORS.cyan, value)}`);
+}
+
 async function ask(rl, question, defaultValue) {
-  const suffix = defaultValue !== undefined ? color(COLORS.dim, ` (${defaultValue})`) : "";
-  const answer = (await rl.question(`${color(COLORS.cyan, "?")} ${question}${suffix} `)).trim();
-  return answer.length === 0 ? defaultValue : answer;
+  printPromptHeader(question);
+  const hint = defaultValue !== undefined ? color(COLORS.dim, ` (default: ${defaultValue})`) : "";
+  const answer = (await rl.question(`${BAR}  ${color(COLORS.gray, SYMBOLS.pointer)}${hint} `)).trim();
+  const value = answer.length === 0 ? defaultValue : answer;
+  // readline already echoed the prompt + answer line; emit a final summary
+  // line on the rail so the transcript reads cleanly after scroll-back.
+  printRailGap();
+  return value;
 }
 
 async function askYesNo(rl, question, defaultYes) {
+  printPromptHeader(question);
   const def = defaultYes ? "Y/n" : "y/N";
-  const answer = (await rl.question(`${color(COLORS.cyan, "?")} ${question} ${color(COLORS.dim, `(${def})`)} `))
+  const answer = (await rl.question(`${BAR}  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, `(${def})`)} `))
     .trim()
     .toLowerCase();
+  printRailGap();
   if (answer.length === 0) return defaultYes;
   return answer === "y" || answer === "yes";
 }
@@ -379,68 +647,264 @@ function optionValue(option) {
   return typeof option === "string" ? option : option.value;
 }
 
-function optionLabel(option) {
-  return typeof option === "string" ? option : `${option.title} ${color(COLORS.dim, `(${option.value})`)}`;
+function optionTitle(option) {
+  return typeof option === "string" ? option : option.title;
 }
 
+function optionDescription(option) {
+  return typeof option === "string" ? "" : option.description ?? "";
+}
+
+// Arrow-key powered choice prompt. Falls back to numbered input whenever raw
+// mode is unavailable (CI, piped stdin, integration tests).
 async function askChoice(rl, question, choices, defaultChoice) {
-  const nameWidth = Math.max(...choices.map((choice) => optionLabel(choice).replace(/\x1b\[[0-9;]*m/g, "").length));
-  const list = choices
-    .map((choice, i) => {
-      const value = optionValue(choice);
-      const label = optionLabel(choice).padEnd(nameWidth);
-      const description = typeof choice === "string" ? "" : color(COLORS.dim, `  ${choice.description}`);
-      const defaultMarker = value === defaultChoice ? color(COLORS.green, "  recommended") : "";
-      return `  ${color(COLORS.dim, `${i + 1})`)} ${label}${description}${defaultMarker}`;
-    })
-    .join("\n");
-  console.log(`${color(COLORS.cyan, "?")} ${question}\n${list}`);
-  const raw = (await rl.question(`  > `)).trim();
+  const canRawMode = process.stdin.isTTY && typeof process.stdin.setRawMode === "function";
+  if (!canRawMode) return askChoiceNumbered(rl, question, choices, defaultChoice);
+
+  printPromptHeader(question);
+  printRailLine(color(COLORS.dim, `Use \u2191 \u2193 to navigate, Enter to confirm, type a number to jump.`));
+
+  let index = Math.max(
+    0,
+    choices.findIndex((choice) => optionValue(choice) === defaultChoice),
+  );
+  const titleWidth = Math.max(...choices.map((choice) => optionTitle(choice).length));
+  const valueWidth = Math.max(...choices.map((choice) => optionValue(choice).length));
+
+  function render(active) {
+    return choices
+      .map((choice, i) => {
+        const isActive = i === active;
+        const isDefault = optionValue(choice) === defaultChoice;
+        const marker = isActive ? color(COLORS.cyan, SYMBOLS.radioOn) : color(COLORS.gray, SYMBOLS.radioOff);
+        const titleRaw = optionTitle(choice).padEnd(titleWidth);
+        const valueRaw = optionValue(choice).padEnd(valueWidth);
+        const title = isActive ? color(COLORS.bold + COLORS.cyan, titleRaw) : color(COLORS.white, titleRaw);
+        const value = color(COLORS.dim, `(${valueRaw})`);
+        const description = optionDescription(choice);
+        const descColored = isActive ? color(COLORS.cyan, description) : color(COLORS.dim, description);
+        const recommended = isDefault ? color(COLORS.green, `  ${SYMBOLS.star} recommended`) : "";
+        return `${BAR}  ${marker} ${title}  ${value}  ${descColored}${recommended}`;
+      })
+      .join("\n");
+  }
+
+  // Pause readline so it doesn't fight us for stdin while we're in raw mode.
+  rl.pause();
+  process.stdin.setRawMode(true);
+  process.stdin.resume();
+  process.stdin.setEncoding("utf8");
+
+  // Initial render
+  process.stdout.write(render(index) + "\n");
+
+  const result = await new Promise((resolve, reject) => {
+    function rerender(newIndex) {
+      // Move cursor up `choices.length` lines, clear them, redraw.
+      process.stdout.write(`\x1b[${choices.length}A`);
+      for (let i = 0; i < choices.length; i += 1) process.stdout.write("\x1b[2K\n");
+      process.stdout.write(`\x1b[${choices.length}A`);
+      process.stdout.write(render(newIndex) + "\n");
+    }
+    function cleanup() {
+      process.stdin.removeListener("data", onData);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+    }
+    function onData(chunk) {
+      const data = chunk.toString();
+      // Ctrl+C / Ctrl+D — abort cleanly
+      if (data === "\u0003" || data === "\u0004") {
+        cleanup();
+        process.stdout.write("\n");
+        reject(new Error("Cancelled"));
+        return;
+      }
+      // Enter
+      if (data === "\r" || data === "\n") {
+        cleanup();
+        resolve(optionValue(choices[index]));
+        return;
+      }
+      // Number shortcut (1..9)
+      if (/^[1-9]$/.test(data)) {
+        const n = Number.parseInt(data, 10);
+        if (n >= 1 && n <= choices.length) {
+          index = n - 1;
+          rerender(index);
+        }
+        return;
+      }
+      // Arrow keys / vim keys
+      if (data === "\u001b[A" || data === "k") {
+        index = (index - 1 + choices.length) % choices.length;
+        rerender(index);
+      } else if (data === "\u001b[B" || data === "j") {
+        index = (index + 1) % choices.length;
+        rerender(index);
+      } else if (data === "\u001b[H") {
+        index = 0;
+        rerender(index);
+      } else if (data === "\u001b[F") {
+        index = choices.length - 1;
+        rerender(index);
+      }
+    }
+    process.stdin.on("data", onData);
+  });
+
+  // Replace the rendered list with a single confirmation line.
+  // Rendered block was choices.length lines; we also printed the hint line
+  // above the list. Move up and clear them.
+  const linesToClear = choices.length + 1; // hint + list
+  process.stdout.write(`\x1b[${linesToClear}A`);
+  for (let i = 0; i < linesToClear; i += 1) process.stdout.write("\x1b[2K\n");
+  process.stdout.write(`\x1b[${linesToClear}A`);
+
+  // Also clear the prompt header we printed at the very top.
+  process.stdout.write("\x1b[1A\x1b[2K");
+
+  printPromptResult(question, result);
+  printRailGap();
+  rl.resume();
+  return result;
+}
+
+async function askChoiceNumbered(rl, question, choices, defaultChoice) {
+  printPromptHeader(question);
+  const titleWidth = Math.max(...choices.map((choice) => optionTitle(choice).length));
+  for (let i = 0; i < choices.length; i += 1) {
+    const choice = choices[i];
+    const isDefault = optionValue(choice) === defaultChoice;
+    const idx = color(COLORS.dim, `${String(i + 1).padStart(2, " ")})`);
+    const title = color(COLORS.white, optionTitle(choice).padEnd(titleWidth));
+    const value = color(COLORS.dim, `(${optionValue(choice)})`);
+    const description = color(COLORS.dim, optionDescription(choice));
+    const recommended = isDefault ? color(COLORS.green, `  ${SYMBOLS.star} recommended`) : "";
+    printRailLine(`${idx} ${title}  ${value}  ${description}${recommended}`);
+  }
+  const raw = (await rl.question(`${BAR}  ${color(COLORS.gray, SYMBOLS.pointer)} `)).trim();
+  printRailGap();
   if (raw.length === 0) return defaultChoice;
   const asNumber = Number.parseInt(raw, 10);
   if (Number.isInteger(asNumber) && asNumber >= 1 && asNumber <= choices.length) {
     return optionValue(choices[asNumber - 1]);
   }
   if (choices.some((choice) => optionValue(choice) === raw)) return raw;
-  console.error(color(COLORS.red, `Invalid choice. Pick one of: ${choices.map(optionValue).join(", ")}`));
-  return askChoice(rl, question, choices, defaultChoice);
+  console.error(`${BAR}  ${color(COLORS.red, `Invalid choice. Pick one of: ${choices.map(optionValue).join(", ")}`)}`);
+  return askChoiceNumbered(rl, question, choices, defaultChoice);
 }
 
 function logStep(message, detail) {
-  const suffix = detail ? color(COLORS.dim, ` ${detail}`) : "";
-  console.log(`${color(COLORS.green, "  [ok]")} ${message}${suffix}`);
+  const suffix = detail ? color(COLORS.dim, ` \u2014 ${detail}`) : "";
+  console.log(`${color(COLORS.green, SYMBOLS.success)}  ${message}${suffix}`);
 }
 
 function logWarn(message) {
-  console.warn(`${color(COLORS.yellow, "  [warn]")} ${message}`);
+  console.warn(`${color(COLORS.yellow, SYMBOLS.warn)}  ${color(COLORS.yellow, message)}`);
+}
+
+function logError(message) {
+  console.error(`${color(COLORS.red, SYMBOLS.error)}  ${color(COLORS.red, message)}`);
+}
+
+// ----------------------------------------------------------------------------
+// Spinner — tiny braille animation for long-running steps (e.g. install).
+// ----------------------------------------------------------------------------
+
+const SPINNER_FRAMES = SUPPORTS_UNICODE
+  ? ["\u280B", "\u2819", "\u2839", "\u2838", "\u283C", "\u2834", "\u2826", "\u2827", "\u2807", "\u280F"]
+  : ["|", "/", "-", "\\"];
+
+function createSpinner(initialMessage) {
+  let message = initialMessage;
+  let frame = 0;
+  let timer = null;
+  let active = false;
+  function render() {
+    if (!process.stdout.isTTY) return;
+    process.stdout.write(`\r\x1b[2K${color(COLORS.cyan, SPINNER_FRAMES[frame])}  ${message}`);
+    frame = (frame + 1) % SPINNER_FRAMES.length;
+  }
+  return {
+    start(text) {
+      if (text) message = text;
+      active = true;
+      if (process.stdout.isTTY) {
+        timer = setInterval(render, 80);
+        render();
+      } else {
+        console.log(`${color(COLORS.cyan, SYMBOLS.stepActive)}  ${message}`);
+      }
+    },
+    update(text) {
+      message = text;
+      if (active && process.stdout.isTTY) render();
+    },
+    stop(text, ok = true) {
+      if (timer) clearInterval(timer);
+      timer = null;
+      active = false;
+      const symbol = ok
+        ? color(COLORS.green, SYMBOLS.success)
+        : color(COLORS.red, SYMBOLS.error);
+      const finalMessage = text ?? message;
+      if (process.stdout.isTTY) {
+        process.stdout.write(`\r\x1b[2K${symbol}  ${finalMessage}\n`);
+      } else {
+        console.log(`${symbol}  ${finalMessage}`);
+      }
+    },
+  };
 }
 
 function printSummary({ projectName, template, packageManager, installDeps, skipPackageManager }) {
-  console.log(color(COLORS.green, "\nCreated a new DaloyJS project."));
-  console.log(`\n  ${color(COLORS.bold, "Project")}   ${projectName}`);
-  console.log(`  ${color(COLORS.bold, "Template")}  ${template}`);
+  const templateMeta = TEMPLATE_OPTIONS.find((option) => option.value === template);
+  const templateLabel = templateMeta ? `${templateMeta.title} ${color(COLORS.dim, `(${template})`)}` : template;
+  const summaryLines = [
+    `${color(COLORS.green, SYMBOLS.sparkle)}  ${color(COLORS.bold, "Your DaloyJS project is ready!")}`,
+    "",
+    `${color(COLORS.gray, "Project   ")} ${color(COLORS.bold, projectName)}`,
+    `${color(COLORS.gray, "Template  ")} ${templateLabel}`,
+  ];
+  if (skipPackageManager) {
+    summaryLines.push(`${color(COLORS.gray, "Runtime   ")} ${color(COLORS.cyan, template === "deno-basic" ? "Deno" : "runtime")}`);
+  } else {
+    summaryLines.push(`${color(COLORS.gray, "Manager   ")} ${color(COLORS.cyan, packageManager)}`);
+  }
+  console.log("");
+  console.log(renderBox(summaryLines, { accent: COLORS.green }));
+  console.log("");
+
+  const arrow = color(COLORS.cyan, SYMBOLS.arrow);
+  console.log(`${color(COLORS.bold, "Next steps")}`);
+  console.log(`  ${arrow} ${color(COLORS.cyan, `cd ${projectName}`)}`);
+  if (skipPackageManager) {
+    console.log(`  ${arrow} ${color(COLORS.cyan, "deno task dev")}`);
+  } else {
+    if (!installDeps) console.log(`  ${arrow} ${color(COLORS.cyan, `${packageManager} install`)}`);
+    console.log(`  ${arrow} ${color(COLORS.cyan, `${packageManager} run dev`)}`);
+  }
+
+  console.log("");
+  console.log(`${color(COLORS.bold, "Useful commands")}`);
   if (skipPackageManager) {
-    console.log(`  ${color(COLORS.bold, "Runtime")}   ${template === "deno-basic" ? "Deno" : "runtime"}`);
-    console.log(`\n  ${color(COLORS.bold, "Next steps")}`);
-    console.log(`    cd ${projectName}`);
-    console.log(`    deno task dev`);
-    console.log(`\n  ${color(COLORS.bold, "Useful commands")}`);
-    console.log(`    deno task typecheck`);
-    console.log(`    deno task test`);
-    console.log(`    deno task gen:openapi`);
+    console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "deno task typecheck")}`);
+    console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "deno task test")}`);
+    console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, "deno task gen:openapi")}`);
   } else {
-    console.log(`  ${color(COLORS.bold, "Manager")}   ${packageManager}`);
-    console.log(`\n  ${color(COLORS.bold, "Next steps")}`);
-    console.log(`    cd ${projectName}`);
-    if (!installDeps) console.log(`    ${packageManager} install`);
-    console.log(`    ${packageManager} run dev`);
-    console.log(`\n  ${color(COLORS.bold, "Useful commands")}`);
-    console.log(`    ${packageManager} run typecheck`);
-    console.log(`    ${packageManager} test`);
-    if (template === "node-basic" || template === "bun-basic") console.log(`    ${packageManager} run gen`);
+    console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, `${packageManager} run typecheck`)}`);
+    console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, `${packageManager} test`)}`);
+    if (template === "node-basic" || template === "bun-basic") {
+      console.log(`  ${color(COLORS.gray, SYMBOLS.pointer)} ${color(COLORS.dim, `${packageManager} run gen`)}`);
+    }
   }
-  console.log(`\n  ${color(COLORS.dim, "Docs: https://daloyjs.dev/docs")}`);
-  console.log(color(COLORS.dim, "  Issues: https://github.com/daloyjs/daloy/issues\n"));
+
+  console.log("");
+  console.log(`${color(COLORS.gray, "Docs:")}   ${color(COLORS.cyan, "https://daloyjs.dev/docs")}`);
+  console.log(`${color(COLORS.gray, "Issues:")} ${color(COLORS.cyan, "https://github.com/daloyjs/daloy/issues")}`);
+  console.log("");
+  console.log(`${color(COLORS.magenta, SYMBOLS.sparkle)}  ${color(COLORS.bold, "Happy shipping!")}\n`);
 }
 
 async function main() {
@@ -459,14 +923,16 @@ async function main() {
     process.exit(0);
   }
 
-  console.log(color(COLORS.bold, "\ncreate-daloy"));
-  console.log(color(COLORS.dim, "Contract-first REST APIs for Node, Vercel Edge, and Workers"));
-  console.log(color(COLORS.dim, "https://daloyjs.dev\n"));
+  printBanner(await readPkgVersion());
 
   const detectedPm = detectPackageManager();
   const interactive = !opts.yes && process.stdin.isTTY && process.stdout.isTTY;
   const rl = interactive ? createInterface({ input, output }) : null;
 
+  if (interactive) {
+    printIntro("Let's set up your DaloyJS project");
+  }
+
   try {
     let projectName = opts.projectName;
     if (!projectName) {
@@ -478,7 +944,7 @@ async function main() {
             projectName = candidate;
             break;
           }
-          console.error(color(COLORS.red, `  ${valid}`));
+          logError(valid);
         }
       } else {
         projectName = "my-daloy-app";
@@ -486,7 +952,7 @@ async function main() {
     }
     const nameCheck = validateProjectName(projectName);
     if (nameCheck !== true) {
-      console.error(color(COLORS.red, nameCheck));
+      logError(nameCheck);
       process.exit(1);
     }
 
@@ -495,13 +961,13 @@ async function main() {
       template = rl ? await askChoice(rl, "Choose a starter template:", TEMPLATE_OPTIONS, "node-basic") : "node-basic";
     }
     if (!TEMPLATES.includes(template)) {
-      console.error(color(COLORS.red, `Unknown template "${template}". Available: ${TEMPLATES.join(", ")}`));
+      logError(`Unknown template "${template}". Available: ${TEMPLATES.join(", ")}`);
       process.exit(1);
     }
 
     const templateDir = path.join(TEMPLATES_DIR, template);
     if (!existsSync(templateDir)) {
-      console.error(color(COLORS.red, `Template "${template}" is missing from this CLI build.`));
+      logError(`Template "${template}" is missing from this CLI build.`);
       process.exit(1);
     }
 
@@ -509,12 +975,7 @@ async function main() {
     if (existsSync(targetDir)) {
       const empty = await isDirEmpty(targetDir);
       if (!empty && !opts.force) {
-        console.error(
-          color(
-            COLORS.red,
-            `Directory ${projectName} is not empty. Re-run with --force to overwrite.`,
-          ),
-        );
+        logError(`Directory ${projectName} is not empty. Re-run with --force to overwrite.`);
         process.exit(1);
       }
     }
@@ -531,9 +992,7 @@ async function main() {
       }
     }
     if (!PACKAGE_MANAGERS.includes(packageManager)) {
-      console.error(
-        color(COLORS.red, `Unknown --package-manager "${packageManager}". Use one of: ${PACKAGE_MANAGERS.join(", ")}`),
-      );
+      logError(`Unknown --package-manager "${packageManager}". Use one of: ${PACKAGE_MANAGERS.join(", ")}`);
       process.exit(1);
     }
 
@@ -553,7 +1012,12 @@ async function main() {
 
     rl?.close();
 
-    console.log(color(COLORS.bold, "\nScaffolding"));
+    if (interactive) {
+      printOutro(color(COLORS.dim, "Configuration locked in. Building your project\u2026"));
+    }
+    console.log("");
+    console.log(`${color(COLORS.cyan, SYMBOLS.sparkle)}  ${color(COLORS.bold, "Scaffolding your project")}`);
+    console.log("");
 
     await mkdir(targetDir, { recursive: true });
     await copyTemplate(templateDir, targetDir);
@@ -582,19 +1046,31 @@ async function main() {
     }
 
     if (installDeps) {
-      console.log(color(COLORS.dim, `  Installing dependencies with ${packageManager}...`));
-      const code = await run(packageManager, ["install"], targetDir);
+      const spinner = createSpinner(`Installing dependencies with ${color(COLORS.cyan, packageManager)}\u2026`);
+      spinner.start();
+      const { code, output: installOutput } = await runQuiet(packageManager, ["install"], targetDir);
       if (code !== 0) {
-        logWarn(`${packageManager} install exited with code ${code}; you can retry inside ${projectName}.`);
+        spinner.stop(`${packageManager} install failed (exit ${code})`, false);
+        // Replay the captured output so the user can see what went wrong.
+        const tail = installOutput.split(/\r?\n/).slice(-40).join("\n");
+        if (tail.trim().length > 0) {
+          console.error(color(COLORS.dim, tail));
+        }
+        logWarn(`Retry inside ${projectName} with: ${packageManager} install`);
       } else {
-        logStep("Dependencies installed", packageManager);
+        spinner.stop(`Installed dependencies with ${color(COLORS.cyan, packageManager)}`);
       }
     }
 
     printSummary({ projectName, template, packageManager, installDeps, skipPackageManager });
   } catch (err) {
     rl?.close();
-    console.error(color(COLORS.red, `\n  Failed: ${(err && err.message) || err}`));
+    if (err && err.message === "Cancelled") {
+      console.log("");
+      logWarn("Cancelled. No project was created.");
+      process.exit(130);
+    }
+    logError(`Failed: ${(err && err.message) || err}`);
     process.exit(1);
   }
 }