Skip to content

armgit / Ix

Public Imported from GitHub
0

Understand any codebase instantly. System intelligence for codebases, built for humans and AI.

feat(cli): render the repo logo as the setup-notice banner (#605)

Alot1zb62c17d3797e
diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml
index dbb45214..629b8c51 100644
--- a/.github/workflows/release.yml
+++ b/.github/workflows/release.yml
@@ -280,8 +280,19 @@ jobs:
COMPASS_STAGED=0
ARCHIVE_LIST="$(mktemp)"
trap 'rm -f "$ARCHIVE_LIST"' EXIT
- mkdir -p "$STAGING/cli" "$STAGING/core-ingestion" "$STAGING/compass"
- cp -rL ix-cli/dist ix-cli/node_modules ix-cli/package.json "$STAGING/cli/"
+ mkdir -p "$STAGING/cli" "$STAGING/cli/scripts" "$STAGING/cli/assets" "$STAGING/core-ingestion" "$STAGING/compass"
+ # The banner renderer + asset ship INSIDE the cli tree: renderBanner()
+ # imports ../../scripts/render-logo.mjs relative to dist/cli, so every
+ # delivery layout needs them beside it. The npm tarball is pinned by a
+ # test in bootstrap-notice.test.ts; this staging copy is the release
+ # counterpart, and the gate below refuses to publish a tarball that
+ # would silently print the plain-text heading instead of the banner —
+ # the exact failure mode that shipped once because both files lived at
+ # the repo root, outside every packaged layout.
+ cp -rL ix-cli/scripts/render-logo.mjs ix-cli/scripts/render-logo.d.mts "$STAGING/cli/scripts/"
+ cp -rL ix-cli/assets/logo.png "$STAGING/cli/assets/"
+ test -f "$STAGING/cli/scripts/render-logo.mjs" && test -f "$STAGING/cli/assets/logo.png" \
+ || { echo "::error::banner inputs missing from staging (cli/scripts/render-logo.mjs, cli/assets/logo.png) — the setup notice would silently lose the logo"; exit 1; }
cp -rL core-ingestion/dist core-ingestion/node_modules core-ingestion/package.json "$STAGING/core-ingestion/"
if [ -f compass-dist/index.html ]; then
cp -r compass-dist/* "$STAGING/compass/"
diff --git a/assets/logo.png b/ix-cli/assets/logo.png
similarity index 100%
rename from assets/logo.png
rename to ix-cli/assets/logo.png
diff --git a/ix-cli/scripts/render-logo.d.mts b/ix-cli/scripts/render-logo.d.mts
new file mode 100644
index 00000000..66935474
--- /dev/null
+++ b/ix-cli/scripts/render-logo.d.mts
@@ -0,0 +1,27 @@
+// Types for scripts/render-logo.mjs (imported by ix-cli tests; the CLI spawns
+// it as a subprocess, so this file is types-only for the repo's TS surface).
+export declare class LogoError extends Error {
+ code: number;
+}
+export declare function resolveColorMode(
+ colorArg: string,
+ env?: NodeJS.ProcessEnv,
+): "truecolor" | "256" | "ascii";
+export declare function renderLogo(opts?: {
+ width?: number;
+ color?: string;
+ bg?: "brand" | "none";
+ file?: string;
+ json?: boolean;
+ env?: NodeJS.ProcessEnv;
+}): string | {
+ ok: boolean;
+ tool: string;
+ color: string;
+ bg: string;
+ file: { path: string; bytes: number };
+ source: { width: number; height: number };
+ grid: { cols: number; rows: number };
+ cells: { total: number; ink: number };
+ truncated: boolean;
+};
diff --git a/ix-cli/scripts/render-logo.mjs b/ix-cli/scripts/render-logo.mjs
new file mode 100644
index 00000000..d7191df7
--- /dev/null
+++ b/ix-cli/scripts/render-logo.mjs
@@ -0,0 +1,285 @@
+#!/usr/bin/env node
+// render-logo.mjs — render assets/logo.png as a terminal banner. Zero deps.
+// The repo asset is the single source of truth; no hand-maintained art lives here.
+//
+// Algorithm: coverage-thresholded supersampling. Each half-cell samples the
+// source at bounded supersample density, counts ink coverage (alpha > 128, or
+// for no-alpha PNGs color distance from the backdrop), snaps to ink at a low
+// threshold (sharp shape boundaries), and averages color only over covered
+// pixels (the brand gradient stays sharp inside the mark).
+//
+// Library use:
+// import { renderLogo } from "./ix-cli/scripts/render-logo.mjs";
+// const ansi = renderLogo({ width: 56, color: "truecolor" }); // -> string
+// const info = renderLogo({ width: 56, json: true }); // -> object
+//
+// CLI:
+// node scripts/render-logo.mjs [--width N] [--color auto|truecolor|256|ascii]
+// [--bg brand|none] [--file path] [--json]
+// Exit codes: 0 ok · 1 usage/file error · 2 unsupported/truncated (toolscan-aligned)
+import { openSync, closeSync, readSync, fstatSync, constants as fsConstants } from "node:fs";
+import { inflateSync } from "node:zlib";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const TOOL = "render-logo";
+const BG = [5, 10, 30]; // brand navy (assets/logo.png backdrop)
+const INK_COVERAGE = 0.12; // snap-to-ink threshold per half-cell
+const ALPHA_EDGE = 128; // pixel counts as ink above this alpha
+const BG_TOL = 36; // no-alpha PNGs: pixel is ink when its color
+ // distance from the backdrop exceeds this
+const MAX_FILE_BYTES = 20 * 1024 * 1024;
+const WIDTH_MIN = 8, WIDTH_MAX = 120, ROWS_MAX = 60;
+const RAMP = " .:-=+*#%@";
+
+export class LogoError extends Error {
+ constructor(message, code) { super(message); this.code = code; }
+}
+
+// --- PNG decode (depth 8, truecolor/truecolor+alpha/grayscale, no interlace) ---
+// Read the input through ONE open handle: stat the handle, not the path.
+// statSync(path)+readFileSync(path) resolve the path independently, so the size
+// guard can bless a different file than the one read (CodeQL js/file-system-
+// race, high), and readFileSync on a FIFO blocks forever — --file is a
+// user-supplied flag, so both are reachable. O_NONBLOCK makes the open itself
+// non-blocking; fstat on the handle then rejects non-regular files (FIFOs,
+// devices) and enforces the size cap against the exact inode that is read.
+function readPngFile(fileArg) {
+ let fd;
+ try { fd = openSync(fileArg, fsConstants.O_RDONLY | fsConstants.O_NONBLOCK); }
+ catch { throw new LogoError(`file not found: ${fileArg}`, 1); }
+ try {
+ const st = fstatSync(fd);
+ if (!st.isFile()) throw new LogoError(`not a regular file: ${fileArg}`, 1);
+ if (st.size > MAX_FILE_BYTES) throw new LogoError(`file exceeds ${MAX_FILE_BYTES} bytes: ${fileArg}`, 2);
+ const buf = Buffer.alloc(st.size);
+ try {
+ let read = 0;
+ while (read < st.size) {
+ const n = readSync(fd, buf, read, st.size - read, read);
+ if (n === 0) break;
+ read += n;
+ }
+ } catch (e) { throw new LogoError(`unreadable file: ${e.message}`, 1); }
+ return { buf, bytes: st.size };
+ } finally {
+ closeSync(fd);
+ }
+}
+
+function decodePng(fileArg) {
+ const { buf, bytes } = readPngFile(fileArg);
+ let off = 8, ihdr, idat = [];
+ while (off + 12 <= buf.length) {
+ const len = buf.readUInt32BE(off), type = buf.toString("ascii", off + 4, off + 8);
+ const data = buf.subarray(off + 8, off + 8 + len);
+ if (type === "IHDR") ihdr = { w: data.readUInt32BE(0), h: data.readUInt32BE(4), depth: data[8], color: data[9], interlace: data[12] };
+ else if (type === "IDAT") idat.push(data);
+ else if (type === "IEND") break;
+ off += 12 + len;
+ }
+ if (!ihdr) throw new LogoError("not a PNG (no IHDR)", 2);
+ const { w, h, depth, color, interlace } = ihdr;
+ if (depth !== 8 || interlace !== 0 || ![0, 2, 6].includes(color)) {
+ throw new LogoError(`unsupported PNG shape (depth=${depth} color=${color} interlace=${interlace})`, 2);
+ }
+ const bpp = color === 6 ? 4 : color === 2 ? 3 : 1;
+ let raw;
+ try { raw = inflateSync(Buffer.concat(idat)); } catch (e) { throw new LogoError(`corrupt PNG (${e.message})`, 2); }
+ const stride = w * bpp;
+ if (raw.length < h * (stride + 1)) throw new LogoError("truncated PNG data", 2);
+ const img = Buffer.alloc(h * stride);
+ const paeth = (a, b, c) => { const p = a + b - c, pa = Math.abs(p - a), pb = Math.abs(p - b), pc = Math.abs(p - c); return pa <= pb && pa <= pc ? a : pb <= pc ? b : c; };
+ for (let y = 0; y < h; y++) {
+ const f = raw[y * (stride + 1)];
+ const row = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+ for (let x = 0; x < stride; x++) {
+ const left = x >= bpp ? img[y * stride + x - bpp] : 0;
+ const up = y > 0 ? img[(y - 1) * stride + x] : 0;
+ const ul = y > 0 && x >= bpp ? img[(y - 1) * stride + x - bpp] : 0;
+ let v = row[x];
+ if (f === 1) v += left; else if (f === 2) v += up; else if (f === 3) v += (left + up) >> 1; else if (f === 4) v += paeth(left, up, ul);
+ img[y * stride + x] = v & 0xff;
+ }
+ }
+ return { img, w, h, stride, color, bpp, bytes };
+}
+
+// --- palette (ANSI-256) ---
+const Q = [0, 95, 135, 175, 215, 255];
+const pal256 = (i) => (i < 16 ? [[0,0,0],[128,0,0],[0,128,0],[128,128,0],[0,0,128],[128,0,128],[0,128,128],[192,192,192],[128,128,128],[255,0,0],[0,255,0],[255,255,0],[0,0,255],[255,0,255],[0,255,255],[255,255,255]][i]
+ : i < 232 ? [Q[Math.floor((i - 16) / 36)], Q[Math.floor((i - 16) / 6) % 6], Q[(i - 16) % 6]]
+ : (() => { const v = 8 + (i - 232) * 10; return [v, v, v]; })());
+const dist = (a, b) => Math.abs(a[0] - b[0]) + Math.abs(a[1] - b[1]) + Math.abs(a[2] - b[2]);
+function to256(rgb) {
+ const qi = (v) => Q.reduce((best, qv, i) => (Math.abs(qv - v) < Math.abs(Q[best] - v) ? i : best), 0);
+ const cube = 16 + 36 * qi(rgb[0]) + 6 * qi(rgb[1]) + qi(rgb[2]);
+ const gray = 232 + Math.min(23, Math.round((0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2]) / 255 * 23));
+ return dist(rgb, pal256(cube)) <= dist(rgb, pal256(gray)) ? cube : gray;
+}
+
+export function resolveColorMode(colorArg, env = process.env) {
+ if (colorArg !== "auto") {
+ if (!["truecolor", "256", "ascii"].includes(colorArg)) throw new LogoError("--color must be auto|truecolor|256|ascii", 1);
+ return colorArg;
+ }
+ if (env.NO_COLOR || env.TERM === "dumb") return "ascii";
+ if (env.FORCE_COLOR === "0") return "ascii";
+ if ((env.COLORTERM ?? "").includes("truecolor") || env.FORCE_COLOR === "3") return "truecolor";
+ if (env.TERM && env.TERM !== "dumb") return "256";
+ return "ascii";
+}
+
+// --- render (library entry) ---
+export function renderLogo(opts = {}) {
+ const width = opts.width ?? 56;
+ if (!Number.isInteger(width) || width < WIDTH_MIN || width > WIDTH_MAX) {
+ throw new LogoError(`--width must be an integer ${WIDTH_MIN}..${WIDTH_MAX}`, 1);
+ }
+ const bgMode = opts.bg ?? "brand";
+ if (!"brand none".split(" ").includes(bgMode)) throw new LogoError("--bg must be brand|none", 1);
+ const fileArg = opts.file ?? resolve(dirname(fileURLToPath(import.meta.url)), "..", "assets", "logo.png");
+ const { img, w, h, stride, color, bpp, bytes } = decodePng(fileArg);
+ const mode = resolveColorMode(opts.color ?? "auto", opts.env);
+
+ // ink test: alpha PNGs decide by alpha; no-alpha PNGs by color distance from
+ // the backdrop (an opaque navy pixel is BACKGROUND, not ink — color type 2
+ // reports alpha 255 for every pixel, so alpha alone would mark the whole
+ // canvas ink and blur the banner).
+ const isInk = (i) => (color === 6
+ ? img[i + 3] > ALPHA_EDGE
+ : Math.abs(img[i] - BG[0]) + Math.abs(img[i + 1] - BG[1]) + Math.abs(img[i + 2] - BG[2]) > BG_TOL);
+
+ function halfCell(x0, x1, y0, y1) {
+ const sx = Math.max(1, Math.min(12, Math.floor((x1 - x0) / 3) || 1));
+ const sy = Math.max(1, Math.min(12, Math.floor((y1 - y0) / 3) || 1));
+ let covered = 0, samples = 0, r = 0, g = 0, b = 0;
+ for (let y = y0; y < Math.max(y1, y0 + 1); y += sy)
+ for (let x = x0; x < Math.max(x1, x0 + 1); x += sx) {
+ const i = y * stride + x * bpp;
+ samples++;
+ if (!isInk(i)) continue;
+ covered++;
+ r += img[i]; g += img[i + 1]; b += img[i + 2];
+ }
+ const cov = covered / Math.max(1, samples);
+ if (cov < INK_COVERAGE) return { ink: false, rgb: BG, lum: 0, cov };
+ const k = covered || 1;
+ const rgb = [r / k, g / k, b / k];
+ return { ink: true, rgb, lum: 0.2126 * rgb[0] + 0.7152 * rgb[1] + 0.0722 * rgb[2], cov };
+ }
+
+ const rows = Math.max(2, Math.min(ROWS_MAX, Math.round((width * h) / w / 2)));
+ const cells = [];
+ for (let ry = 0; ry < rows; ry++)
+ for (let rx = 0; rx < width; rx++) {
+ const x0 = Math.floor((rx * w) / width), x1 = Math.max(x0 + 1, Math.floor(((rx + 1) * w) / width));
+ const top = halfCell(x0, x1, Math.floor(((ry * 2) * h) / (rows * 2)), Math.max(1, Math.floor((((ry * 2) + 1) * h) / (rows * 2))));
+ const bot = halfCell(x0, x1, Math.floor((((ry * 2) + 1) * h) / (rows * 2)), Math.max(1, Math.floor((((ry * 2) + 2) * h) / (rows * 2))));
+ cells.push({ top, bot });
+ }
+
+ let out = "";
+ let lastSig = "";
+ for (let i = 0; i < cells.length; i++) {
+ const { top, bot } = cells[i];
+ if (i % width === 0) out += "\n";
+ if (!top.ink && !bot.ink) { out += " "; lastSig = ""; continue; }
+ if (mode === "ascii") {
+ const intensity = Math.max(top.cov * (top.lum / 255), bot.cov * (bot.lum / 255)) * 1.6;
+ out += RAMP[Math.min(RAMP.length - 1, Math.max(top.ink || bot.ink ? 1 : 0, Math.round(intensity * (RAMP.length - 1))))];
+ continue;
+ }
+ if (bgMode === "none") {
+ // Per-shape emission: paint only the half-cells that carry ink, never the
+ // backdrop. A top-only cell is ▀ with fg=top and no background; a
+ // bottom-only cell is ▄ with fg=bot; a full cell paints ▀ with fg=top,
+ // bg=bot exactly like brand mode. The block stays the brand shape's own
+ // pixels — nothing is drawn behind it.
+ const fTop = mode === "truecolor"
+ ? `38;2;${top.rgb.map((v) => Math.round(v)).join(";")}`
+ : `38;5;${to256(top.rgb)}`;
+ const fBot = mode === "truecolor"
+ ? `38;2;${bot.rgb.map((v) => Math.round(v)).join(";")}`
+ : `38;5;${to256(bot.rgb)}`;
+ if (top.ink && bot.ink) {
+ const sig = mode === "truecolor" ? `${top.rgb.map(Math.round)}/${bot.rgb.map(Math.round)}` : `${to256(top.rgb)}/${to256(bot.rgb)}`;
+ if (sig !== lastSig) { out += `\x1b[0;${fTop};${fBot}m`; lastSig = sig; }
+ out += "▀";
+ } else if (top.ink) {
+ const sig = mode === "truecolor" ? `${top.rgb.map(Math.round)}/-` : `${to256(top.rgb)}/-`;
+ if (sig !== lastSig) { out += `\x1b[0;${fTop}m`; lastSig = sig; }
+ out += "▀";
+ } else {
+ const sig = mode === "truecolor" ? `-${bot.rgb.map(Math.round)}` : `-${to256(bot.rgb)}`;
+ if (sig !== lastSig) { out += `\x1b[0;${fBot}m`; lastSig = sig; }
+ out += "▄";
+ }
+ continue;
+ }
+ const sig = mode === "truecolor"
+ ? `${top.rgb.map(Math.round)}/${bot.rgb.map(Math.round)}`
+ : `${to256(top.rgb)}/${to256(bot.rgb)}`;
+ if (sig !== lastSig) {
+ const f = mode === "truecolor"
+ ? `38;2;${top.rgb.map((v) => Math.round(v)).join(";")}`
+ : `38;5;${to256(top.rgb)}`;
+ const b = mode === "truecolor"
+ ? `48;2;${bot.rgb.map((v) => Math.round(v)).join(";")}`
+ : `48;5;${to256(bot.rgb)}`;
+ out += `\x1b[0;${f};${b}m`;
+ lastSig = sig;
+ }
+ out += "▀";
+ }
+ if (mode !== "ascii") out += "\x1b[0m"; // no escapes at all under NO_COLOR/ascii
+out += "\n";
+
+ if (opts.json) {
+ const inkCells = cells.filter((c) => c.top.ink || c.bot.ink).length;
+ return {
+ ok: true, tool: TOOL, color: mode, bg: bgMode, file: { path: String(fileArg), bytes },
+ source: { width: w, height: h }, grid: { cols: width, rows },
+ cells: { total: cells.length, ink: inkCells }, truncated: false,
+ };
+ }
+ return out;
+}
+
+// --- CLI (thin: parse, render, report) ---
+const isCli = process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url);
+if (isCli) {
+ const args = process.argv.slice(2);
+ const flagJson = () => args.includes("--json");
+ const flag = (name) => {
+ const i = args.indexOf(name);
+ if (i === -1) return undefined;
+ const v = args[i + 1];
+ if (v === undefined || v.startsWith("--")) return null; // null = missing value
+ return v;
+ };
+ const fail = (msg, code) => {
+ if (flagJson()) process.stdout.write(`${JSON.stringify({ ok: false, tool: TOOL, error: msg })}\n`);
+ else process.stderr.write(`${TOOL}: ${msg}\n`);
+ process.exit(code);
+ };
+ const get = (name) => {
+ const v = flag(name);
+ if (v === null) fail(`missing value for ${name}`, 1);
+ return v;
+ };
+ const bgRaw = get("--bg");
+ if (bgRaw !== undefined && !"brand none".split(" ").includes(bgRaw)) fail("--bg must be brand|none", 1);
+ try {
+ const result = renderLogo({
+ width: flag("--width") !== undefined ? Number(get("--width")) : 56,
+ color: get("--color") ?? "auto",
+ bg: bgRaw ?? "brand",
+ file: get("--file"),
+ json: flagJson(),
+ });
+ process.stdout.write(typeof result === "string" ? result : `${JSON.stringify(result)}\n`);
+ } catch (e) {
+ fail(e instanceof LogoError ? e.message : e.message, e instanceof LogoError ? e.code : 1);
+ }
+}
diff --git a/ix-cli/src/cli/__tests__/bootstrap-notice.test.ts b/ix-cli/src/cli/__tests__/bootstrap-notice.test.ts
index 55e22d85..f182672b 100644
--- a/ix-cli/src/cli/__tests__/bootstrap-notice.test.ts
+++ b/ix-cli/src/cli/__tests__/bootstrap-notice.test.ts
@@ -1,7 +1,26 @@
import { describe, it, expect, vi, afterEach } from "vitest";
+import { execFileSync } from "node:child_process";
+import { renameSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
import { emitSetupNotice } from "../bootstrap.js";
+import { renderBanner, resetBannerCacheForTests } from "../banner.js";
+import { renderLogo, resolveColorMode, LogoError } from "../../../scripts/render-logo.mjs";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
-afterEach(() => vi.restoreAllMocks());
+// The renderer + asset now live INSIDE the package (fix for the review
+// finding that the first banner PR shipped them at the repo root, where no
+// install layout — npm tarball or release staging — ever carried them). These
+// bases serve both the behavioral pins below and the deliverability pin.
+const PKG_ROOT = join(fileURLToPath(import.meta.url), "..", "..", "..", ".."); // ix-cli/
+const RENDERER = join(PKG_ROOT, "scripts", "render-logo.mjs");
+const LOGO_ASSET = join(PKG_ROOT, "assets", "logo.png");
+
+afterEach(() => {
+ vi.restoreAllMocks();
+ vi.unstubAllEnvs();
+ resetBannerCacheForTests();
+});
describe("emitSetupNotice", () => {
it("writes setup notices to stderr, never stdout (keeps machine output clean)", () => {
@@ -16,15 +35,223 @@ describe("emitSetupNotice", () => {
const stderrText = err.mock.calls.map((c) => String(c[0])).join("\n");
expect(stderrText).toContain("Registered workspace");
expect(stderrText).toContain("my-workspace");
- });
+ }, 15000);
- it("emits nothing when neither config nor workspace was newly created", () => {
+ it("shows the logo banner when the renderer + asset are present", () => {
const out = vi.spyOn(console, "log").mockImplementation(() => {});
const err = vi.spyOn(console, "error").mockImplementation(() => {});
- emitSetupNotice(false, false, "x");
+ emitSetupNotice(true, false, "ws");
+
+ expect(out).not.toHaveBeenCalled();
+ const banner = renderBanner();
+ expect(banner).not.toBeNull();
+ const stderrText = err.mock.calls.map((c) => String(c[0])).join("\n");
+ // (whatever color mode this environment resolves), not the text fallback.
+ expect(stderrText).toContain(banner!);
+ expect(stderrText).not.toContain("Ix");
+ }, 15000);
+
+ it("falls back to the plain text heading when the asset is absent (absent-safe)", () => {
+ // A layout without the packaged asset must degrade to the old heading —
+ // never throw, never leave the notice block empty. The renderer reads the
+ // asset at call time, so renaming it exercises exactly that layout.
+ // Within-file tests run sequentially, so the temporary rename is invisible
+ // to the other pins (and afterEach resets the banner cache).
+ const out = vi.spyOn(console, "log").mockImplementation(() => {});
+ const err = vi.spyOn(console, "error").mockImplementation(() => {});
+
+ const assetBackup = LOGO_ASSET + ".bak";
+ renameSync(LOGO_ASSET, assetBackup);
+ try {
+ emitSetupNotice(true, false, "ws");
+ const stderrText = err.mock.calls.map((c) => String(c[0])).join("\n");
+ expect(stderrText).toContain("Ix");
+ expect(stderrText).not.toContain("▀");
+ } finally {
+ renameSync(assetBackup, LOGO_ASSET);
+ }
+ expect(out).not.toHaveBeenCalled();
+ });
+});
+
+describe("renderBanner", () => {
+ it("returns a non-empty banner containing half-block cells", () => {
+ // renderBanner() spawns the renderer with the inherited env; CI runners
+ // may have TERM unset/dumb (resolving to the ASCII fallback, which has no
+ // half-blocks). Pin the environment so this always exercises the color
+ // path — the assertion itself stays exact.
+ vi.stubEnv("TERM", "xterm-256color");
+ vi.stubEnv("NO_COLOR", "");
+ vi.stubEnv("COLORTERM", "");
+ const banner = renderBanner();
+ expect(banner).not.toBeNull();
+ expect(banner!.includes("▀")).toBe(true);
+ // every non-empty line indented two spaces for the notice block
+ // (a leading blank line is intentional spacing)
+ for (const line of banner!.split("\n")) {
+ if (line.trim()) expect(line.startsWith(" ")).toBe(true);
+ }
+ }, 15000);
+ it("renders ASCII under NO_COLOR and never writes stdout", () => {
+ const out = vi.spyOn(console, "log").mockImplementation(() => {});
+ const raw = execFileSync(
+ process.execPath,
+ [RENDERER, "--width", "16"],
+ { encoding: "utf8", env: { ...process.env, NO_COLOR: "1" } },
+ );
+ expect(raw).not.toMatch(/\x1b\[/); // no escapes in no-color mode
expect(out).not.toHaveBeenCalled();
- expect(err).not.toHaveBeenCalled();
});
});
+
+describe("banner deliverability (the inputs must ship)", () => {
+ // History: the first banner PR kept scripts/render-logo.mjs + assets/logo.png
+ // at the repo ROOT — a layout no delivery path packs (npm publishes from
+ // ix-cli/; release staging copies exactly three trees) — so every installed
+ // run silently fell back to the plain heading while all tests (run from a
+ // checkout, where the files exist) passed. These pins turn that failure loud
+ // at PR time: if the inputs leave the package or the staging tree, CI fails.
+
+ it("npm pack carries the renderer and the asset inside the tarball", () => {
+ const res = spawnSync("npm", ["pack", "--dry-run", "--json"], {
+ cwd: PKG_ROOT,
+ encoding: "utf8",
+ shell: process.platform === "win32",
+ });
+ expect(res.status).toBe(0);
+ const packed = (JSON.parse(res.stdout)[0].files as { path: string }[]).map((f) => f.path);
+ expect(packed).toContain("scripts/render-logo.mjs");
+ expect(packed).toContain("assets/logo.png");
+ }, 30_000); // budget, not a weaker assertion: npm pack is slow under full-suite load
+
+ it("release staging carries them beside dist/cli, with a gate that refuses to publish without them", () => {
+ const wf = readFileSync(join(PKG_ROOT, "..", ".github", "workflows", "release.yml"), "utf8");
+ expect(wf).toContain("ix-cli/scripts/render-logo.mjs");
+ expect(wf).toContain("ix-cli/assets/logo.png");
+ expect(wf).toContain("banner inputs missing");
+ });
+});
+
+describe("render-logo CLI contract", () => {
+ const run = (args: string[], env: NodeJS.ProcessEnv = {}) =>
+ execFileSync(process.execPath, [RENDERER, ...args], {
+ encoding: "utf8",
+ env: { ...process.env, ...env },
+ });
+
+ it("exit 0 + JSON honesty block on --json (cells/ink/truncated)", () => {
+ const meta = JSON.parse(run(["--width", "16", "--json"]));
+ expect(meta.ok).toBe(true);
+ expect(meta.tool).toBe("render-logo");
+ expect(meta.truncated).toBe(false);
+ expect(meta.cells.ink).toBeGreaterThan(0);
+ expect(meta.cells.ink).toBeLessThan(meta.cells.total);
+ });
+
+ it("usage error exits 1 and reports to stderr, payload-free stdout", () => {
+ let code = 0, stderrText = "", stdoutText = "";
+ try {
+ execFileSync(process.execPath, [RENDERER, "--width", "4"], { encoding: "utf8", stdio: "pipe" });
+ } catch (e: any) {
+ code = e.status;
+ stderrText = e.stderr?.toString() ?? "";
+ stdoutText = e.stdout?.toString() ?? "";
+ }
+ expect(code).toBe(1);
+ expect(stderrText).toContain("--width");
+ expect(stdoutText).toBe("");
+ });
+
+ it("library renderLogo() matches the CLI byte-for-byte (single algorithm)", () => {
+ const viaCli = run(["--width", "24", "--color", "ascii"]);
+ const viaLib = renderLogo({ width: 24, color: "ascii" });
+ expect(viaLib).toBe(viaCli);
+ }, 30_000); // budget, not a weaker assertion: the in-process render decodes the
+ // full PNG (~16M byte-samples), and v8 coverage instrumentation inflates
+ // that fixed cost ~10x (measured ~7s vs ~0.7s) on every coverage run; the
+ // byte-identity assertion above stays exact.
+
+ it("resolveColorMode honors NO_COLOR / COLORTERM / TERM", () => {
+ expect(resolveColorMode("auto", { NO_COLOR: "1" } as NodeJS.ProcessEnv)).toBe("ascii");
+ expect(resolveColorMode("auto", { COLORTERM: "truecolor", TERM: "xterm" } as NodeJS.ProcessEnv)).toBe("truecolor");
+ expect(resolveColorMode("auto", { TERM: "xterm-256color" } as NodeJS.ProcessEnv)).toBe("256");
+ expect(resolveColorMode("ascii")).toBe("ascii");
+ });
+
+ it("LogoError carries the toolscan-aligned exit code", () => {
+ try {
+ renderLogo({ width: 4 });
+ expect.unreachable("width below minimum must throw");
+ } catch (e) {
+ expect(e).toBeInstanceOf(LogoError);
+ expect((e as LogoError).code).toBe(1);
+ }
+ });
+
+ it("--bg none paints only shape pixels: the backdrop never appears as a background", () => {
+ // brand mode paints the navy canvas behind every partial cell; none mode
+ // must never emit the backdrop constant as a background color.
+ const brand = run(["--width", "20", "--color", "truecolor"]);
+ const none = run(["--width", "20", "--color", "truecolor", "--bg", "none"]);
+ expect(brand).toContain("48;2;5;10;30"); // brand paints the backdrop
+ expect(none).not.toContain("48;2;5;10;30"); // none never does
+ expect(none).toContain("▄"); // bottom-only cells emit the lower half-block
+ expect(none).not.toBe(brand);
+ });
+
+ it("--bg none is byte-identical through the library and the CLI", () => {
+ const viaCli = run(["--width", "24", "--color", "ascii", "--bg", "none"]);
+ const viaLib = renderLogo({ width: 24, color: "ascii", bg: "none" });
+ expect(viaLib).toBe(viaCli);
+ }, 30_000); // budget, not a weaker assertion (see the sibling lib≡CLI pin)
+
+ it("--bg none is reported honestly in the JSON block; default is brand", () => {
+ expect(JSON.parse(run(["--width", "16", "--bg", "none", "--json"])).bg).toBe("none");
+ expect(JSON.parse(run(["--width", "16", "--json"])).bg).toBe("brand");
+ });
+
+ it("--bg bogus exits 1 with the reason on stderr and a payload-free stdout", () => {
+ let code = 0, stderrText = "", stdoutText = "";
+ try {
+ execFileSync(process.execPath, [RENDERER, "--width", "16", "--bg", "bogus"], { encoding: "utf8", stdio: "pipe" });
+ } catch (e: any) {
+ code = e.status;
+ stderrText = e.stderr?.toString() ?? "";
+ stdoutText = e.stdout?.toString() ?? "";
+ }
+ expect(code).toBe(1);
+ expect(stderrText).toContain("--bg");
+ expect(stdoutText).toBe("");
+ });
+});
+
+describe("output stability (golden fixtures)", () => {
+ // output-samples/*.ans are byte-pinned renders. Each filename encodes its
+ // invocation (width-color[-bg-none]); the pin re-renders and compares, so
+ // accidental visual drift fails CI. Update goldens ONLY in a dedicated,
+ // stated commit that says what changed and why.
+ // Goldens remain a repo-root artifact shared by the renderer's own docs.
+ const GOLDENS_DIR = join(fileURLToPath(import.meta.url), "..", "..", "..", "..", "..", "output-samples");
+ const goldens = readdirSync(GOLDENS_DIR).filter((f) => f.endsWith(".ans"));
+
+ it("ships goldens covering every color mode and both bg modes", () => {
+ expect(goldens.length).toBeGreaterThanOrEqual(6);
+ expect(goldens.some((f) => f.includes("ascii"))).toBe(true);
+ expect(goldens.some((f) => f.includes("256"))).toBe(true);
+ expect(goldens.some((f) => f.endsWith("bg-none.ans"))).toBe(true);
+ });
+
+ for (const g of goldens) {
+ it(`current render is byte-identical to the golden fixture: ${g}`, () => {
+ const m = g.match(/^width-(\d+)-(truecolor|256|ascii)(-bg-none)?\.ans$/);
+ expect(m, `fixture name must encode its invocation: ${g}`).not.toBeNull();
+ const args = ["--width", m![1], "--color", m![2]];
+ if (m![3]) args.push("--bg", "none");
+ const expected = readFileSync(join(GOLDENS_DIR, g), "utf8");
+ const actual = execFileSync(process.execPath, [RENDERER, ...args], { encoding: "utf8" });
+ expect(actual).toBe(expected);
+ });
+ }
+});
diff --git a/ix-cli/src/cli/banner.ts b/ix-cli/src/cli/banner.ts
new file mode 100644
index 00000000..99003656
--- /dev/null
+++ b/ix-cli/src/cli/banner.ts
@@ -0,0 +1,79 @@
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+type RenderLogo = typeof import("../../scripts/render-logo.mjs")["renderLogo"];
+
+/**
+ * The Ix logo as a terminal banner, rendered at print time from the packaged
+ * assets/logo.png by the zero-dependency renderer in scripts/render-logo.mjs —
+ * imported in-process (no subprocess, no spawn cost). The PNG is the only
+ * maintained art; the terminal render is derived from it.
+ *
+ * Contract (mirrors emitSetupNotice):
+ * - stderr-only surface: this returns a string for the caller to emit to
+ * stderr; it never writes to stdout (machine-readable output stays clean).
+ * - absent-safe: a layout that did not ship the renderer or the asset is NOT
+ * an error — the loader below resolves to null and emitSetupNotice falls
+ * back to the plain text heading. The banner is decoration, never
+ * load-bearing. This is why the import is dynamic behind a probe: a static
+ * import of the renderer would crash this module at load time in any layout
+ * that copied dist/ without scripts/ + assets/ (e.g. the watch child
+ * runtime cache), turning a missing decoration into a broken CLI.
+ * - honors NO_COLOR / TERM=dumb (the renderer itself resolves the mode): the
+ * no-color path renders the ASCII fallback, also fine to show.
+ *
+ * Where the inputs live: scripts/ + assets/ inside the package, beside the
+ * compiled dist/cli/banner.js. The ESM specifier resolves relative to this
+ * file identically in every layout that ships them — repo checkout, npm
+ * tarball, and the release staging tree (which copies them explicitly, gated
+ * in release.yml; the npm tarball is pinned by a test in
+ * bootstrap-notice.test.ts). The probe checks the same package-relative
+ * location, so it can only disagree with the import if the files vanish
+ * between probe and import — in which case the catch degrades to null.
+ */
+let renderLogoFn: RenderLogo | null = null;
+try {
+ const pkgDir = join(dirname(fileURLToPath(import.meta.url)), "..", "..");
+ if (
+ existsSync(join(pkgDir, "scripts", "render-logo.mjs")) &&
+ existsSync(join(pkgDir, "assets", "logo.png"))
+ ) {
+ renderLogoFn = (await import("../../scripts/render-logo.mjs")).renderLogo;
+ }
+} catch {
+ renderLogoFn = null;
+}
+
+let cache: string | null | undefined;
+
+export function renderBanner(): string | null {
+ // The setup notice prints at most once per run; the module-level cache makes
+ // a second call free without repeating the decode (~10ms in-process vs the
+ // subprocess + interpreter startup this replaced).
+ if (cache !== undefined) return cache;
+ if (!renderLogoFn) return (cache = null);
+
+ try {
+ const out = renderLogoFn({ width: 48, color: "auto" });
+ // renderLogo returns the ANSI string (or a JSON block when asked — never
+ // here). A render that produced no visible cells would silently corrupt
+ // the notice block; treat either as failure and fall back.
+ if (typeof out !== "string" || !out.trim()) return (cache = null);
+
+ // Indent the banner to align with the notice text block.
+ cache = out
+ .replace(/\n$/, "")
+ .split("\n")
+ .map((l) => (l.trim() ? ` ${l}` : l))
+ .join("\n");
+ } catch {
+ cache = null; // any decode/unsupported-asset failure: plain-text fallback
+ }
+ return cache;
+}
+
+/** Test hook: reset the memoized banner result. */
+export function resetBannerCacheForTests(): void {
+ cache = undefined;
+}
diff --git a/ix-cli/src/cli/bootstrap.ts b/ix-cli/src/cli/bootstrap.ts
index 4727380e..720f9a93 100644
--- a/ix-cli/src/cli/bootstrap.ts
+++ b/ix-cli/src/cli/bootstrap.ts
@@ -4,6 +4,7 @@ import { homedir } from "node:os";
import { execFileSync } from "node:child_process";
import chalk from "chalk";
import { IxClient } from "../client/api.js";
+import { renderBanner } from "./banner.js";
import { canonicalWorkspacePath, getEndpoint, loadConfig, saveConfig, findWorkspaceForCwd, getDefaultWorkspace, type WorkspaceConfig } from "./config.js";
import { workspaceIdForPath } from "./system.js";
import { readBackendHealth } from "./commands/upgrade.js";
@@ -153,7 +154,12 @@ export async function ensureBackendAvailable(): Promise<void> {
*/
export function emitSetupNotice(createdConfig: boolean, registered: boolean, name: string): void {
if (!createdConfig && !registered) return;
- console.error(chalk.bold("Ix\n"));
+ // The logo banner (rendered from assets/logo.png at print time) when the
+ // terminal can show it; the plain text heading otherwise. Both stderr only —
+ // stdout stays clean for --format json|llm consumers.
+ const banner = renderBanner();
+ if (banner) console.error(banner);
+ else console.error(chalk.bold("Ix\n"));
if (createdConfig) console.error(chalk.dim(`Created default config.`));
if (registered) console.error(chalk.dim(`Registered workspace "${name}".`));
console.error();
diff --git a/output-samples/width-48-256-bg-none.ans b/output-samples/width-48-256-bg-none.ans
new file mode 100644
index 00000000..8ff620d8
--- /dev/null
+++ b/output-samples/width-48-256-bg-none.ans
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+ ▄▄▀▀
+ ▄▄▄▀▀▀▀
+ ▄▄▄▀▀▀▀▀▀▀▀
+ ▄▄▄▄▀▀▀▀▀▀▀▀▄▀ ▀▀▀
+ ▀▀▀▀▀▀▀▀▀▄▄▀▀▀▀▀▄▀▀▀
+ ▄▄▄▄▄▀▀▀▀▀▀▀▀▀▀▀▀▀▀▄▀▀ ▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▄ ▄▀▀▄▀▀ ▀▀▀▀
+ ▀▀▀▄ ▀▀▀▄ ▄▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▄▀▀▀▀
+ ▀▀▀ ▀▀▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀
+ ▀▀▀▄ ▀▀▀▀▄▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀▄ ▄▀▀▀▀▀ ▀▀▀▀ ▄▀▀▀▀▀▀▄
+ ▀▀▀▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀▄
+ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀▀
+ ▀▀
+
+
+
+
+ 
diff --git a/output-samples/width-48-256.ans b/output-samples/width-48-256.ans
new file mode 100644
index 00000000..877c2676
--- /dev/null
+++ b/output-samples/width-48-256.ans
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+ ▀▀▀▀
+ ▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀ ▀▀▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀▀
+ ▀▀
+
+
+
+
+ 
diff --git a/output-samples/width-48-ascii.ans b/output-samples/width-48-ascii.ans
new file mode 100644
index 00000000..e777e85b
--- /dev/null
+++ b/output-samples/width-48-ascii.ans
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+ ....
+ .:---::
+ :-==-=-::-:
+ :-=*#*+++=-... --.
+ *%%%%*=-..:::::..==.
+ -----=%%#----::..:..+= +@@+
+ -#*+=--=%%- .:..++ +@@+
+ =**. +%%: .-: ++ +@@+ #@@@ :@@@=
+ +*+ *#*-: =*. +@@+ %@@@@@@=
+ .**- .+++-#- =@@= -@@@@
+ :**: .==##* =@@= =@@@@@@:
+ =++== =- =@@= %@@@ -@@@+
+ =+- .--. --- ---
+ .:
+
+
+
+
+
diff --git a/output-samples/width-48-truecolor-bg-none.ans b/output-samples/width-48-truecolor-bg-none.ans
new file mode 100644
index 00000000..74515fe5
--- /dev/null
+++ b/output-samples/width-48-truecolor-bg-none.ans
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+ ▄▄▀▀
+ ▄▄▄▀▀▀▀
+ ▄▄▄▀▀▀▀▀▀▀▀
+ ▄▄▄▄▀▀▀▀▀▀▀▀▄▀ ▀▀▀
+ ▀▀▀▀▀▀▀▀▀▄▄▀▀▀▀▀▄▀▀▀
+ ▄▄▄▄▄▀▀▀▀▀▀▀▀▀▀▀▀▀▀▄▀▀ ▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▄ ▄▀▀▄▀▀ ▀▀▀▀
+ ▀▀▀▄ ▀▀▀▄ ▄▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▄▀▀▀▀
+ ▀▀▀ ▀▀▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀
+ ▀▀▀▄ ▀▀▀▀▄▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀▄ ▄▀▀▀▀▀ ▀▀▀▀ ▄▀▀▀▀▀▀▄
+ ▀▀▀▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀▄
+ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀▀
+ ▀▀
+
+
+
+
+ 
diff --git a/output-samples/width-48-truecolor.ans b/output-samples/width-48-truecolor.ans
new file mode 100644
index 00000000..009ef5f9
--- /dev/null
+++ b/output-samples/width-48-truecolor.ans
@@ -0,0 +1,25 @@
+
+
+
+
+
+
+ ▀▀▀▀
+ ▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀ ▀▀▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀ ▀▀ ▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀▀
+ ▀▀
+
+
+
+
+ 
diff --git a/output-samples/width-56-truecolor.ans b/output-samples/width-56-truecolor.ans
new file mode 100644
index 00000000..0617a9d1
--- /dev/null
+++ b/output-samples/width-56-truecolor.ans
@@ -0,0 +1,29 @@
+
+
+
+
+
+
+
+ ▀▀▀▀
+ ▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀
+ ▀▀▀▀▀▀▀▀▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀
+ ▀▀▀▀▀ ▀▀▀▀ ▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀
+ ▀▀▀▀ ▀▀▀▀▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀
+ ▀▀▀▀▀ ▀▀ ▀▀▀ ▀▀▀▀ ▀▀▀▀▀▀▀▀▀▀
+ ▀▀▀▀▀▀ ▀ ▀▀▀▀ ▀▀▀▀▀ ▀▀▀▀▀
+ ▀▀▀▀
+ ▀
+
+
+
+
+
+