@bastani/atomic 0.5.3-0 → 0.5.3-1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bastani/atomic",
-  "version": "0.5.3-0",
+  "version": "0.5.3-1",
   "description": "Configuration management CLI and SDK for coding agents",
   "type": "module",
   "license": "MIT",

package/src/commands/cli/init/index.ts

@@ -44,107 +44,7 @@ import {
   applyManagedOnboardingFiles,
   hasProjectOnboardingFiles,
 } from "./onboarding.ts";
-import { supportsTrueColor, supports256Color, supportsColor } from "@/services/system/detect.ts";
-
-const ATOMIC_BLOCK_LOGO = [
-  "█▀▀█ ▀▀█▀▀ █▀▀█ █▀▄▀█ ▀█▀ █▀▀",
-  "█▄▄█   █   █  █ █ ▀ █  █  █  ",
-  "▀  ▀   ▀   ▀▀▀▀ ▀   ▀ ▀▀▀ ▀▀▀",
-];
-
-// Catppuccin-inspired gradient (dark terminal)
-const GRADIENT_DARK = [
-  "#f5e0dc", "#f2cdcd", "#f5c2e7", "#cba6f7",
-  "#b4befe", "#89b4fa", "#74c7ec", "#89dceb", "#94e2d5",
-];
-
-// Catppuccin-inspired gradient (light terminal)
-const GRADIENT_LIGHT = [
-  "#dc8a78", "#dd7878", "#ea76cb", "#8839ef",
-  "#7287fd", "#1e66f5", "#209fb5", "#04a5e5", "#179299",
-];
-
-// 256-color approximation of the gradient
-const GRADIENT_256 = [224, 218, 219, 183, 147, 111, 117, 159, 115];
-
-function hexToRgb(hex: string): [number, number, number] {
-  const h = hex.replace("#", "");
-  return [
-    parseInt(h.substring(0, 2), 16),
-    parseInt(h.substring(2, 4), 16),
-    parseInt(h.substring(4, 6), 16),
-  ];
-}
-
-function interpolateHex(gradient: string[], t: number): [number, number, number] {
-  const pos = Math.max(0, Math.min(1, t)) * (gradient.length - 1);
-  const lo = Math.floor(pos);
-  const hi = Math.min(lo + 1, gradient.length - 1);
-  const frac = pos - lo;
-  const [r1, g1, b1] = hexToRgb(gradient[lo]!);
-  const [r2, g2, b2] = hexToRgb(gradient[hi]!);
-  return [
-    Math.round(r1 + (r2 - r1) * frac),
-    Math.round(g1 + (g2 - g1) * frac),
-    Math.round(b1 + (b2 - b1) * frac),
-  ];
-}
-
-function interpolate256(gradient: number[], t: number): number {
-  const pos = Math.max(0, Math.min(1, t)) * (gradient.length - 1);
-  const lo = Math.floor(pos);
-  return gradient[lo]!;
-}
-
-function colorizeLineTrueColor(line: string, gradient: string[]): string {
-  let out = "";
-  const len = line.length;
-  for (let i = 0; i < len; i++) {
-    const ch = line[i]!;
-    if (ch === " ") {
-      out += ch;
-      continue;
-    }
-    const [r, g, b] = interpolateHex(gradient, len > 1 ? i / (len - 1) : 0);
-    out += `\x1b[38;2;${r};${g};${b}m${ch}`;
-  }
-  return out + "\x1b[0m";
-}
-
-function colorizeLine256(line: string, gradient: number[]): string {
-  let out = "";
-  const len = line.length;
-  for (let i = 0; i < len; i++) {
-    const ch = line[i]!;
-    if (ch === " ") {
-      out += ch;
-      continue;
-    }
-    const code = interpolate256(gradient, len > 1 ? i / (len - 1) : 0);
-    out += `\x1b[38;5;${code}m${ch}`;
-  }
-  return out + "\x1b[0m";
-}
-
-function displayBlockBanner(): void {
-  const isDark = !(process.env.COLORFGBG ?? "").startsWith("0;");
-  const truecolor = supportsTrueColor();
-  const color256 = supports256Color();
-  const hasColor = supportsColor();
-
-  console.log();
-  for (const line of ATOMIC_BLOCK_LOGO) {
-    if (truecolor) {
-      const gradient = isDark ? GRADIENT_DARK : GRADIENT_LIGHT;
-      console.log(`  ${colorizeLineTrueColor(line, gradient)}`);
-    } else if (color256 && hasColor) {
-      console.log(`  ${colorizeLine256(line, GRADIENT_256)}`);
-    } else {
-      console.log(`  ${line}`);
-    }
-  }
-  console.log();
-}
+import { displayBlockBanner } from "@/theme/logo.ts";
 
 /**
  * Thrown when the user cancels an interactive prompt during init.

package/src/commands/cli/workflow.ts

@@ -238,26 +238,20 @@ function createPainter(): Paint {
  * Layout:
  *   N workflows
  *
- *
  *   local (.atomic/workflows)
  *
  *     Claude
- *
  *       <name>
  *       <name>
  *
  *     OpenCode
- *
  *       <name>
  *
- *
  *   global (~/.atomic/workflows)
  *
  *     Claude
- *
  *       <name>
  *
- *
  *   run: atomic workflow -n <name> -a <agent>
  */
 function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
@@ -309,15 +303,13 @@ function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
 
   // One stanza per source section, with nested provider sub-groups inside.
   // Rhythm:
-  //   2 blanks before each source heading  (major break)
-  //   1 blank before each provider heading (tight, they're nested)
-  //   1 blank before each provider's entries
+  //   1 blank before each source heading  (section break)
+  //   1 blank before each provider heading (grouped with its entries)
   for (const source of SOURCE_ORDER) {
     const byAgent = bySource.get(source);
     if (!byAgent || byAgent.size === 0) continue;
 
-    // Major break before the source section.
-    lines.push("");
+    // Section break before the source section.
     lines.push("");
 
     // Source heading: bold semantic colour + dim inline directory hint.
@@ -338,7 +330,6 @@ function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
       lines.push(
         "    " + paint("accent", AGENT_DISPLAY_NAMES[agent], { bold: true }),
       );
-      lines.push("");
 
       for (const name of names) {
         lines.push("      " + paint("text", name));
@@ -346,8 +337,7 @@ function renderWorkflowList(workflows: DiscoveredWorkflow[]): string {
     }
   }
 
-  // Footer — dim run hint, separated by the same major-break rhythm.
-  lines.push("");
+  // Footer — dim run hint, separated by a section break.
   lines.push("");
   lines.push(
     "  " + paint("dim", "run: atomic workflow -n <name> -a <agent>"),

package/src/sdk/runtime/executor.ts

@@ -455,7 +455,7 @@ async function initProviderClientAndSession(
       const { CopilotClient, approveAll } = await import("@github/copilot-sdk");
       const copilotClientOpts = clientOpts as StageClientOptions<"copilot">;
       const copilotSessionOpts = sessionOpts as StageSessionOptions<"copilot">;
-      const client = new CopilotClient({ cliUrl: serverUrl, ...copilotClientOpts });
+      const client = new CopilotClient({ ...copilotClientOpts, cliUrl: serverUrl });
       await client.start();
       const session = await client.createSession({
         onPermissionRequest: approveAll,
@@ -468,7 +468,7 @@ async function initProviderClientAndSession(
       const { createOpencodeClient } = await import("@opencode-ai/sdk/v2");
       const ocClientOpts = clientOpts as StageClientOptions<"opencode">;
       const ocSessionOpts = sessionOpts as StageSessionOptions<"opencode">;
-      const client = createOpencodeClient({ baseUrl: serverUrl, ...ocClientOpts });
+      const client = createOpencodeClient({ ...ocClientOpts, baseUrl: serverUrl });
       const sessionResult = await client.session.create(ocSessionOpts);
       await client.tui.selectSession({ sessionID: sessionResult.data!.id });
       return { client, session: sessionResult.data! };

package/src/services/system/auto-sync.ts

@@ -10,21 +10,25 @@
  * Instead, we detect a fresh install or upgrade lazily on CLI startup by
  * comparing the bundled `VERSION` constant against a marker file at
  * `~/.atomic/.synced-version`. On a mismatch we run the same setup the
- * production bootstrap installers (`install.sh` / `install.ps1`) provide:
+ * production bootstrap installers (`install.sh` / `install.ps1`) provide,
+ * grouped into two parallel phases:
  *
- *   1. Node.js / npm           (gates everything that needs npm/npx)
- *   2. tmux / psmux            (terminal multiplexer for `chat` and `workflow`)
- *   3. @playwright/cli         (global npm package used by skills)
- *   4. @llamaindex/liteparse   (global npm package used by skills)
- *   5. global agent configs    (~/.claude/agents, ~/.opencode/agents, ~/.copilot/agents, lsp-config.json)
- *   6. global workflows        (~/.atomic/workflows/{hello,hello-parallel,ralph,...})
- *   7. global skills           (npx skills add ...)
+ *   Phase 1 (parallel — no inter-dependencies):
+ *     1. Node.js / npm           (installed via fnm, no system pkg-mgr)
+ *     2. tmux / psmux            (terminal multiplexer for `chat` / `workflow`)
+ *     3. global agent configs    (file copies — no network)
  *
- * Each step runs sequentially. Failures are collected and reported as a
- * summary at the end, but never abort the run — partial setup matches the
- * production installer's "best-effort" semantics. The marker is written
- * after every run (success or partial) so we don't re-attempt the whole
- * setup on every subsequent launch.
+ *   Phase 2 (parallel — all need npm from Phase 1):
+ *     4. @playwright/cli         (npm install -g)
+ *     5. @llamaindex/liteparse   (npm install -g)
+ *     6. global skills           (npx skills add ...)
+ *
+ * Steps within each phase run concurrently; phases run sequentially.
+ * Failures are collected and reported as a summary at the end, but never
+ * abort the run — partial setup matches the production installer's
+ * "best-effort" semantics. The marker is written after every run (success
+ * or partial) so we don't re-attempt the whole setup on every subsequent
+ * launch.
  */
 
 import { join } from "path";
@@ -40,6 +44,7 @@ import {
 import { installGlobalAgents } from "@/services/system/agents.ts";
 import { installGlobalSkills } from "@/services/system/skills.ts";
 import { runSteps, printSummary } from "@/services/system/install-ui.ts";
+import { displayBlockBanner } from "@/theme/logo.ts";
 
 /** Path to the version marker. Honors ATOMIC_SETTINGS_HOME for tests. */
 function syncMarkerPath(): string {
@@ -88,26 +93,34 @@ export async function autoSyncIfStale(): Promise<void> {
     `\n  ${COLORS.dim}Setting up atomic ${COLORS.reset}${COLORS.bold}v${VERSION}${COLORS.reset}${COLORS.dim}…${COLORS.reset}\n`,
   );
 
-  // Ordering notes:
-  //  - Phase 1 (npm, tmux): core tools. npm comes first because
-  //    @playwright/cli, @llamaindex/liteparse, and `npx skills` all need it.
-  //    tmux/psmux is independent but installed sequentially to avoid
-  //    contention with system package-manager locks (apt-get, dnf, etc).
-  //  - Phase 2 (global npm packages): will fail loudly if Phase 1's npm
-  //    install failed, which is fine — the spinner summary records their
-  //    failure too.
-  //  - Phase 3 (bundled atomic content): file copies + npx skills install.
+  // Steps are split into two parallel phases:
+  //
+  //  Phase 1 — core tools + file copies (no inter-dependencies):
+  //    npm is installed via fnm (not a system package manager), so it
+  //    won't contend with tmux's apt-get/dnf install. Agent config
+  //    copies are pure file I/O with no network or npm dependency.
+  //
+  //  Phase 2 — npm-dependent tasks (run after Phase 1):
+  //    @playwright/cli, @llamaindex/liteparse, and `npx skills` all
+  //    need npm/npx. They install independent packages, so they can
+  //    run concurrently.
   //
   // Each step's failure is caught inside `runSteps` (not thrown), so
   // subsequent steps still run even if one fails — matches install.sh's
   // best-effort contract.
   const results = await runSteps([
-    { label: "Node.js / npm",      fn: () => ensureNpmInstalled({ quiet: true }) },
-    { label: "tmux / psmux",       fn: () => ensureTmuxInstalled({ quiet: true }) },
-    { label: "@playwright/cli",    fn: upgradePlaywrightCli },
-    { label: "@llamaindex/liteparse", fn: upgradeLiteparse },
-    { label: "global agent configs",  fn: installGlobalAgents },
-    { label: "global skills",         fn: installGlobalSkills },
+    // Phase 1 — parallel
+    [
+      { label: "Node.js / npm",        fn: () => ensureNpmInstalled({ quiet: true }) },
+      { label: "tmux / psmux",         fn: () => ensureTmuxInstalled({ quiet: true }) },
+      { label: "global agent configs", fn: installGlobalAgents },
+    ],
+    // Phase 2 — parallel, after Phase 1
+    [
+      { label: "@playwright/cli",       fn: upgradePlaywrightCli },
+      { label: "@llamaindex/liteparse", fn: upgradeLiteparse },
+      { label: "global skills",         fn: installGlobalSkills },
+    ],
   ]);
 
   // Always write the marker — partial setup is the production-installer
@@ -115,7 +128,7 @@ export async function autoSyncIfStale(): Promise<void> {
   // @bastani/atomic` is the recovery path for a failed setup.
   await markSynced();
 
-  console.log();
+  displayBlockBanner();
   printSummary(results);
 
   const failures = results.filter((r) => !r.ok);
@@ -124,6 +137,8 @@ export async function autoSyncIfStale(): Promise<void> {
       `\n  ${COLORS.dim}Re-run \`bun install -g @bastani/atomic\` after resolving the issues to retry.${COLORS.reset}\n`,
     );
   } else {
-    console.log();
+    console.log(
+      `\n  ${COLORS.dim}Learn more at ${COLORS.reset}${COLORS.blue}https://deepwiki.com/flora131/atomic${COLORS.reset}\n`,
+    );
   }
 }

package/src/services/system/install-ui.ts

@@ -1,12 +1,21 @@
 /**
  * Progress UI primitives for the first-run install flow (auto-sync).
  *
- * Renders a single persistent line:
+ * Renders an OpenCode-inspired single-line progress bar:
  *
- *     ⠋ [██████▒▒▒▒▒▒] 3/7  tmux / psmux
+ *     ⠋ ■■■■■■■■■■■■■■■■■■････････････  50%  tmux / psmux
+ *
+ * where the braille spinner is provided by `@clack/prompts` and the bar
+ * uses Catppuccin Mocha accent colors (Blue for progress, Green for
+ * success, Red for error) with true-color → 256-color → basic ANSI
+ * fallback.
+ *
+ * Steps are grouped into **phases**. Steps within a phase run in parallel
+ * (via `Promise.all`); phases themselves run sequentially so later phases
+ * can depend on earlier ones (e.g. npm must be available before
+ * `npm install -g` tasks). The progress bar advances and the label
+ * updates in real-time as individual steps complete within a phase.
  *
- * where the braille spinner animation is provided by `@clack/prompts`
- * and the bracketed bar tracks overall step progress (completed / total).
  * A final summary (✓/✗ per step) is printed after all steps finish, and
  * any captured stderr/stdout from a failed step is shown beneath it.
  *
@@ -16,16 +25,20 @@
 
 import { spinner } from "@clack/prompts";
 import { COLORS } from "@/theme/colors.ts";
+import {
+  supportsTrueColor,
+  supports256Color,
+} from "@/services/system/detect.ts";
 
-const BAR_WIDTH = 18;
-const BAR_FILLED = "█";
-const BAR_EMPTY = "░";
+const BAR_WIDTH = 30;
+const BAR_FILLED = "■";
+const BAR_EMPTY = "･";
 
 /**
- * Semantic bar states:
- *   progress → blue (Catppuccin accent; "in flight")
- *   success  → green (universal "completed")
- *   error    → red   (universal "failed")
+ * Semantic bar states mapped to Catppuccin Mocha colors:
+ *   progress → Blue  #89b4fa (accent; "in flight")
+ *   success  → Green #a6e3a1 (universal "completed")
+ *   error    → Red   #f38ba8 (universal "failed")
  *
  * The empty track stays dim regardless — only the filled portion carries
  * the status signal, which keeps the bar legible while still telegraphing
@@ -34,6 +47,28 @@ const BAR_EMPTY = "░";
 type BarState = "progress" | "success" | "error";
 
 function fillColor(state: BarState): string {
+  if (supportsTrueColor()) {
+    switch (state) {
+      case "success":
+        return "\x1b[38;2;166;227;161m"; // Catppuccin Green #a6e3a1
+      case "error":
+        return "\x1b[38;2;243;139;168m"; // Catppuccin Red   #f38ba8
+      case "progress":
+      default:
+        return "\x1b[38;2;137;180;250m"; // Catppuccin Blue  #89b4fa
+    }
+  }
+  if (supports256Color()) {
+    switch (state) {
+      case "success":
+        return "\x1b[38;5;150m";
+      case "error":
+        return "\x1b[38;5;211m";
+      case "progress":
+      default:
+        return "\x1b[38;5;111m";
+    }
+  }
   switch (state) {
     case "success":
       return COLORS.green;
@@ -45,7 +80,7 @@ function fillColor(state: BarState): string {
   }
 }
 
-/** Render a bracketed step-progress bar. `completed` is capped at `total`. */
+/** Render a progress bar: colored filled ■ + dim empty ･ */
 function renderBar(
   completed: number,
   total: number,
@@ -56,7 +91,6 @@ function renderBar(
   const filled = Math.round(ratio * BAR_WIDTH);
   const empty = BAR_WIDTH - filled;
   return (
-    COLORS.bold +
     fillColor(state) +
     BAR_FILLED.repeat(filled) +
     COLORS.reset +
@@ -73,8 +107,12 @@ function formatLine(
   state: BarState = "progress",
 ): string {
   const bar = renderBar(completed, total, state);
-  const counter = `${COLORS.dim}${completed}/${total}${COLORS.reset}`;
-  return `${bar}  ${counter}  ${label}`;
+  const safeTotal = Math.max(1, total);
+  const pct = Math.round(
+    Math.max(0, Math.min(1, completed / safeTotal)) * 100,
+  );
+  const percent = `${COLORS.dim}${String(pct).padStart(3)}%${COLORS.reset}`;
+  return `${bar}  ${percent}  ${label}`;
 }
 
 export interface StepResult {
@@ -84,48 +122,80 @@ export interface StepResult {
   error?: string;
 }
 
+export interface Step {
+  label: string;
+  fn: () => Promise<unknown>;
+}
+
+/** A phase is a group of steps that run in parallel. */
+export type Phase = Step[];
+
 /**
- * Runs a sequence of async steps with a single persistent spinner line
- * showing stepped progress. Each step's failure is collected rather than
- * thrown, mirroring auto-sync's "best-effort" contract.
+ * Runs phases of async steps with a single persistent spinner line
+ * showing stepped progress. Steps within each phase run in parallel;
+ * phases run sequentially so later phases can depend on earlier ones.
  *
- * Returns the per-step results in submission order so the caller can
- * render a summary.
+ * Each step's failure is collected rather than thrown, mirroring
+ * auto-sync's "best-effort" contract.
+ *
+ * Returns the per-step results in phase/submission order so the caller
+ * can render a summary.
  */
-export async function runSteps(
-  steps: Array<{ label: string; fn: () => Promise<unknown> }>,
-): Promise<StepResult[]> {
-  const total = steps.length;
+export async function runSteps(phases: Phase[]): Promise<StepResult[]> {
+  const total = phases.reduce((n, phase) => n + phase.length, 0);
   const results: StepResult[] = [];
   const s = spinner();
+  let completed = 0;
 
   // Start with 0/total so the user sees the bar immediately.
-  s.start(formatLine(0, total, steps[0]?.label ?? ""));
-
-  for (let i = 0; i < steps.length; i++) {
-    const step = steps[i]!;
-    s.message(formatLine(i, total, step.label));
-
-    try {
-      await step.fn();
-      results.push({ label: step.label, ok: true });
-    } catch (error) {
-      const message = error instanceof Error ? error.message : String(error);
-      results.push({ label: step.label, ok: false, error: message });
-    }
+  s.start(formatLine(0, total, phases[0]?.[0]?.label ?? ""));
+
+  for (const phase of phases) {
+    // Show all in-flight labels for this phase.
+    const inFlight = new Set(phase.map((step) => step.label));
+    s.message(formatLine(completed, total, [...inFlight].join(", ")));
+
+    // Run every step in this phase concurrently.
+    const phaseResults = await Promise.all(
+      phase.map(async (step): Promise<StepResult> => {
+        try {
+          await step.fn();
+          completed++;
+          inFlight.delete(step.label);
+          if (inFlight.size > 0) {
+            s.message(
+              formatLine(completed, total, [...inFlight].join(", ")),
+            );
+          }
+          return { label: step.label, ok: true };
+        } catch (error) {
+          const message =
+            error instanceof Error ? error.message : String(error);
+          completed++;
+          inFlight.delete(step.label);
+          if (inFlight.size > 0) {
+            s.message(
+              formatLine(completed, total, [...inFlight].join(", ")),
+            );
+          }
+          return { label: step.label, ok: false, error: message };
+        }
+      }),
+    );
+
+    results.push(...phaseResults);
   }
 
-  // Stop with a filled bar + final label so the user sees we reached the
-  // end rather than leaving the last in-flight step pinned. Bar color
-  // flips to the universal status colors: green when every step
-  // succeeded, red when any step failed. The per-step ✓/✗ rows printed
-  // afterwards provide the detailed breakdown.
+  // Stop with a filled bar + final label. Bar color flips to the
+  // universal status colors: green when every step succeeded, red when
+  // any step failed.
   const okCount = results.filter((r) => r.ok).length;
   const allOk = okCount === total;
+  const finalState: BarState = allOk ? "success" : "error";
   const finalLabel = allOk
-    ? `${COLORS.green}Setup complete${COLORS.reset}`
-    : `${COLORS.red}Setup finished with errors${COLORS.reset}`;
-  s.stop(formatLine(total, total, finalLabel, allOk ? "success" : "error"));
+    ? `${fillColor("success")}Setup complete${COLORS.reset}`
+    : `${fillColor("error")}Setup finished with errors${COLORS.reset}`;
+  s.stop(formatLine(total, total, finalLabel, finalState));
 
   return results;
 }

package/src/theme/logo.ts

@@ -0,0 +1,112 @@
+/**
+ * Atomic ASCII-art logo and Catppuccin gradient colorization.
+ *
+ * Shared between the init banner and the post-install completion screen.
+ */
+
+import {
+  supportsTrueColor,
+  supports256Color,
+  supportsColor,
+} from "@/services/system/detect.ts";
+
+export const ATOMIC_BLOCK_LOGO = [
+  "█▀▀█ ▀▀█▀▀ █▀▀█ █▀▄▀█ ▀█▀ █▀▀",
+  "█▄▄█   █   █  █ █ ▀ █  █  █  ",
+  "▀  ▀   ▀   ▀▀▀▀ ▀   ▀ ▀▀▀ ▀▀▀",
+];
+
+/** Catppuccin-inspired gradient (dark terminal). */
+export const GRADIENT_DARK = [
+  "#f5e0dc", "#f2cdcd", "#f5c2e7", "#cba6f7",
+  "#b4befe", "#89b4fa", "#74c7ec", "#89dceb", "#94e2d5",
+];
+
+/** Catppuccin-inspired gradient (light terminal). */
+export const GRADIENT_LIGHT = [
+  "#dc8a78", "#dd7878", "#ea76cb", "#8839ef",
+  "#7287fd", "#1e66f5", "#209fb5", "#04a5e5", "#179299",
+];
+
+/** 256-color approximation of the gradient. */
+export const GRADIENT_256 = [224, 218, 219, 183, 147, 111, 117, 159, 115];
+
+function hexToRgb(hex: string): [number, number, number] {
+  const h = hex.replace("#", "");
+  return [
+    parseInt(h.substring(0, 2), 16),
+    parseInt(h.substring(2, 4), 16),
+    parseInt(h.substring(4, 6), 16),
+  ];
+}
+
+function interpolateHex(gradient: string[], t: number): [number, number, number] {
+  const pos = Math.max(0, Math.min(1, t)) * (gradient.length - 1);
+  const lo = Math.floor(pos);
+  const hi = Math.min(lo + 1, gradient.length - 1);
+  const frac = pos - lo;
+  const [r1, g1, b1] = hexToRgb(gradient[lo]!);
+  const [r2, g2, b2] = hexToRgb(gradient[hi]!);
+  return [
+    Math.round(r1 + (r2 - r1) * frac),
+    Math.round(g1 + (g2 - g1) * frac),
+    Math.round(b1 + (b2 - b1) * frac),
+  ];
+}
+
+function interpolate256(gradient: number[], t: number): number {
+  const pos = Math.max(0, Math.min(1, t)) * (gradient.length - 1);
+  const lo = Math.floor(pos);
+  return gradient[lo]!;
+}
+
+export function colorizeLineTrueColor(line: string, gradient: string[]): string {
+  let out = "";
+  const len = line.length;
+  for (let i = 0; i < len; i++) {
+    const ch = line[i]!;
+    if (ch === " ") {
+      out += ch;
+      continue;
+    }
+    const [r, g, b] = interpolateHex(gradient, len > 1 ? i / (len - 1) : 0);
+    out += `\x1b[38;2;${r};${g};${b}m${ch}`;
+  }
+  return out + "\x1b[0m";
+}
+
+export function colorizeLine256(line: string, gradient: number[]): string {
+  let out = "";
+  const len = line.length;
+  for (let i = 0; i < len; i++) {
+    const ch = line[i]!;
+    if (ch === " ") {
+      out += ch;
+      continue;
+    }
+    const code = interpolate256(gradient, len > 1 ? i / (len - 1) : 0);
+    out += `\x1b[38;5;${code}m${ch}`;
+  }
+  return out + "\x1b[0m";
+}
+
+/** Print the Atomic block logo with Catppuccin gradient colorization. */
+export function displayBlockBanner(): void {
+  const isDark = !(process.env.COLORFGBG ?? "").startsWith("0;");
+  const truecolor = supportsTrueColor();
+  const color256 = supports256Color();
+  const hasColor = supportsColor();
+
+  console.log();
+  for (const line of ATOMIC_BLOCK_LOGO) {
+    if (truecolor) {
+      const gradient = isDark ? GRADIENT_DARK : GRADIENT_LIGHT;
+      console.log(`  ${colorizeLineTrueColor(line, gradient)}`);
+    } else if (color256 && hasColor) {
+      console.log(`  ${colorizeLine256(line, GRADIENT_256)}`);
+    } else {
+      console.log(`  ${line}`);
+    }
+  }
+  console.log();
+}