karajan-code 1.58.2 → 1.59.1

package/src/proxy/proxy-server.js

@@ -0,0 +1,239 @@
+import http from "node:http";
+import https from "node:https";
+import { isRequestTooLarge } from "./security.js";
+
+/**
+ * Create a lightweight HTTP forward proxy with middleware pipeline.
+ *
+ * The proxy receives plain HTTP on localhost, detects the AI provider from the
+ * Host header, runs the middleware chain, then forwards the request as HTTPS
+ * (or HTTP for testing) to the real API endpoint.
+ *
+ * @param {object} options
+ * @param {number} options.port - Port to listen on (0 = OS-assigned)
+ * @param {Record<string, string>} options.targetHosts - Map host → provider name
+ * @param {object} [options._testTarget] - Override target for testing (hostname, port, protocol)
+ * @returns {ProxyServer}
+ */
+export function createProxyServer({ port = 0, targetHosts = {}, _testTarget } = {}) {
+  const middlewares = [];
+  const startTime = Date.now();
+  const stats = { requests: 0, bytes_in: 0, bytes_out: 0 };
+  let activeConnections = 0;
+  let closing = false;
+  let closeResolve = null;
+
+  function detectProvider(host) {
+    // Strip port from host if present
+    const hostname = (host || "").split(":")[0];
+    return targetHosts[hostname] || "unknown";
+  }
+
+  /**
+   * Compose middlewares into a single function using Koa-style next() chaining.
+   */
+  function compose(mws, finalHandler) {
+    return function run(ctx) {
+      let index = -1;
+      function dispatch(i) {
+        if (i <= index) return Promise.reject(new Error("next() called multiple times"));
+        index = i;
+        const fn = i < mws.length ? mws[i] : finalHandler;
+        if (!fn) return Promise.resolve();
+        return Promise.resolve(fn(ctx, () => dispatch(i + 1)));
+      }
+      return dispatch(0);
+    };
+  }
+
+  /**
+   * Forward the request to the upstream target and stream the response back.
+   */
+  function forwardRequest(ctx) {
+    return new Promise((resolve, reject) => {
+      const { req, res } = ctx;
+      const host = (req.headers.host || "").split(":")[0];
+      const body = ctx.modifiedBody != null ? ctx.modifiedBody : ctx.body;
+
+      // Determine target
+      let targetHostname, targetPort, useHttps;
+      if (_testTarget) {
+        targetHostname = _testTarget.hostname;
+        targetPort = _testTarget.port;
+        useHttps = _testTarget.protocol === "https:";
+      } else {
+        targetHostname = host;
+        targetPort = 443;
+        useHttps = true;
+      }
+
+      const transport = useHttps ? https : http;
+
+      // Clone headers, remove hop-by-hop headers, update content-length
+      const headers = { ...req.headers };
+      delete headers["transfer-encoding"];
+      delete headers["connection"];
+      delete headers["proxy-connection"];
+      delete headers["keep-alive"];
+      if (body != null) {
+        headers["content-length"] = String(Buffer.byteLength(body));
+      }
+
+      const proxyReq = transport.request(
+        {
+          hostname: targetHostname,
+          port: targetPort,
+          path: req.url,
+          method: req.method,
+          headers,
+        },
+        (proxyRes) => {
+          // Track bytes out by instrumenting the response
+          proxyRes.on("data", (chunk) => {
+            stats.bytes_out += chunk.length;
+          });
+
+          // Stream the response back — write head then pipe
+          res.writeHead(proxyRes.statusCode, proxyRes.headers);
+          proxyRes.pipe(res);
+          proxyRes.on("end", resolve);
+          proxyRes.on("error", reject);
+        },
+      );
+
+      proxyReq.on("error", (err) => {
+        if (!res.headersSent) {
+          res.writeHead(502, { "content-type": "application/json" });
+          res.end(JSON.stringify({ error: "Bad Gateway", message: err.message }));
+        }
+        resolve(); // Don't reject — we handled the error via 502
+      });
+
+      if (body) {
+        proxyReq.write(body);
+      }
+      proxyReq.end();
+    });
+  }
+
+  function handleRequest(req, res) {
+    // Health check — bypass middleware and proxy
+    if (req.url === "/_kj/health") {
+      res.writeHead(200, { "content-type": "application/json" });
+      res.end(
+        JSON.stringify({
+          status: "ok",
+          uptime: Math.round((Date.now() - startTime) / 1000),
+          requests: stats.requests,
+        }),
+      );
+      return;
+    }
+
+    // Reject oversized requests early (50 MB default)
+    const MAX_BODY_BYTES = 50 * 1024 * 1024;
+    if (isRequestTooLarge(req.headers["content-length"], MAX_BODY_BYTES)) {
+      res.writeHead(413, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: "Payload Too Large", maxBytes: MAX_BODY_BYTES }));
+      return;
+    }
+
+    activeConnections++;
+    stats.requests++;
+
+    // Collect body — enforce streaming size limit even without Content-Length
+    let bodySize = 0;
+    const chunks = [];
+    req.on("data", (c) => {
+      bodySize += c.length;
+      if (bodySize > MAX_BODY_BYTES) {
+        res.writeHead(413, { "content-type": "application/json" });
+        res.end(JSON.stringify({ error: "Payload Too Large", maxBytes: MAX_BODY_BYTES }));
+        req.destroy();
+        return;
+      }
+      chunks.push(c);
+      stats.bytes_in += c.length;
+    });
+    req.on("end", () => {
+      const body = Buffer.concat(chunks).toString();
+      const provider = detectProvider(req.headers.host);
+
+      const ctx = {
+        req,
+        res,
+        body,
+        provider,
+        modifiedBody: null,
+      };
+
+      const chain = compose(middlewares, (c) => forwardRequest(c));
+      chain(ctx)
+        .catch((err) => {
+          if (!res.headersSent) {
+            res.writeHead(500, { "content-type": "application/json" });
+            res.end(JSON.stringify({ error: "Internal Server Error", message: err.message }));
+          }
+        })
+        .finally(() => {
+          activeConnections--;
+          if (closing && activeConnections === 0 && closeResolve) {
+            closeResolve();
+          }
+        });
+    });
+  }
+
+  const server = http.createServer(handleRequest);
+
+  const instance = {
+    get port() {
+      const addr = server.address();
+      return addr ? addr.port : port;
+    },
+
+    get stats() {
+      return { ...stats };
+    },
+
+    /**
+     * Register a middleware function.
+     * @param {(ctx: object, next: () => Promise<void>) => Promise<void>} fn
+     */
+    use(fn) {
+      middlewares.push(fn);
+      return instance;
+    },
+
+    /**
+     * Start listening on the configured port.
+     * @returns {Promise<void>}
+     */
+    listen() {
+      return new Promise((resolve, reject) => {
+        server.on("error", reject);
+        server.listen(port, "127.0.0.1", () => resolve());
+      });
+    },
+
+    /**
+     * Graceful shutdown — stop accepting new connections,
+     * drain active ones, then resolve.
+     * @returns {Promise<void>}
+     */
+    close() {
+      closing = true;
+      return new Promise((resolve) => {
+        server.close(() => {
+          if (activeConnections === 0) {
+            resolve();
+          } else {
+            closeResolve = resolve;
+          }
+        });
+      });
+    },
+  };
+
+  return instance;
+}

package/src/proxy/security.js

@@ -0,0 +1,45 @@
+/**
+ * Security utilities for the proxy layer.
+ *
+ * - sanitizeHeaders: strips sensitive values before logging
+ * - isRequestTooLarge: checks Content-Length against a limit
+ *
+ * @module proxy/security
+ */
+
+/** Headers whose values must never appear in logs. */
+const SENSITIVE_HEADERS = new Set([
+  "authorization",
+  "x-api-key",
+  "x-goog-api-key",
+]);
+
+/**
+ * Return a shallow copy of `headers` with sensitive values replaced by "[REDACTED]".
+ *
+ * @param {Record<string, string>} headers
+ * @returns {Record<string, string>}
+ */
+export function sanitizeHeaders(headers) {
+  if (!headers || typeof headers !== "object") return {};
+
+  const result = {};
+  for (const [key, value] of Object.entries(headers)) {
+    result[key] = SENSITIVE_HEADERS.has(key.toLowerCase()) ? "[REDACTED]" : value;
+  }
+  return result;
+}
+
+/**
+ * Check whether the declared Content-Length exceeds the allowed maximum.
+ *
+ * @param {number|string|undefined} contentLength - Value of the content-length header
+ * @param {number} maxBytes - Maximum allowed body size in bytes (default 50 MB)
+ * @returns {boolean} true if the request is too large
+ */
+export function isRequestTooLarge(contentLength, maxBytes = 50 * 1024 * 1024) {
+  if (contentLength == null) return false;
+  const len = Number(contentLength);
+  if (Number.isNaN(len)) return false;
+  return len > maxBytes;
+}

package/src/review/diff-generator.js

@@ -19,14 +19,16 @@ function run(command, args, ...rest) {
 export async function computeBaseRef({ baseBranch = "main", baseRef = null }) {
   if (baseRef) return baseRef;
   const mergeBase = await run("git", ["merge-base", "HEAD", `origin/${baseBranch}`]);
-  if (mergeBase.exitCode !== 0) {
-    const fallback = await run("git", ["rev-parse", "HEAD~1"]);
-    if (fallback.exitCode !== 0) {
-      throw new Error("Could not compute diff base reference");
-    }
-    return fallback.stdout.trim();
-  }
-  return mergeBase.stdout.trim();
+  if (mergeBase.exitCode === 0) return mergeBase.stdout.trim();
+
+  const fallback = await run("git", ["rev-parse", "HEAD~1"]);
+  if (fallback.exitCode === 0) return fallback.stdout.trim();
+
+  // Empty repo (zero commits): diff against the empty tree
+  const emptyTree = await run("git", ["hash-object", "-t", "tree", "/dev/null"]);
+  if (emptyTree.exitCode === 0) return emptyTree.stdout.trim();
+
+  throw new Error("Could not compute diff base reference");
 }
 
 export async function generateDiff({ baseRef, stageNewFiles = false }) {

package/src/roles/coder-role.js

@@ -43,6 +43,7 @@ export class CoderRole extends BaseRole {
       methodology: this.config?.development?.methodology || "tdd",
       serenaEnabled: Boolean(this.config?.serena?.enabled),
       rtkAvailable: Boolean(this.config?.rtk?.available),
+      proxyEnabled: Boolean(this.config?.proxy?.enabled),
       productContext: this.config?.productContext || null,
       domainContext: this.config?.domainContext || null
     });

package/src/roles/impeccable-role.js

@@ -1,6 +1,7 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
 import { isDevToolsMcpAvailable, ensureWebPerfSkills } from "../webperf/devtools-detect.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -35,10 +36,7 @@ function buildPrompt({ task, diff, instructions }) {
 }
 
 function parseImpeccableOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
+  return extractFirstJson(raw);
 }
 
 function buildSummary(parsed) {

package/src/roles/researcher-role.js

@@ -1,5 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -34,10 +35,7 @@ function buildPrompt({ task, instructions }) {
 }
 
 function parseResearchOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
+  return extractFirstJson(raw);
 }
 
 function buildSummary(parsed) {

package/src/roles/reviewer-role.js

@@ -1,6 +1,7 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
-import { RTK_INSTRUCTIONS } from "../prompts/rtk-snippet.js";
+import { buildRtkInstructions } from "../prompts/rtk-snippet.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const MAX_DIFF_LENGTH = 12000;
 
@@ -25,7 +26,7 @@ function truncateDiff(diff) {
     : diff;
 }
 
-function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false, productContext = null, domainContext = null }) {
+function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAvailable = false, proxyEnabled = false, productContext = null, domainContext = null }) {
   const sections = [];
 
   sections.push(SUBAGENT_PREAMBLE);
@@ -50,8 +51,9 @@ function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAva
     sections.push(`## Domain Context\n${domainContext}`);
   }
 
-  if (rtkAvailable) {
-    sections.push(RTK_INSTRUCTIONS);
+  const rtkSnippet = buildRtkInstructions({ rtkAvailable, proxyEnabled });
+  if (rtkSnippet) {
+    sections.push(rtkSnippet);
   }
 
   if (reviewRules) {
@@ -64,12 +66,11 @@ function buildPrompt({ task, diff, reviewRules, reviewMode, instructions, rtkAva
 }
 
 function parseReviewOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) {
+  const parsed = extractFirstJson(raw);
+  if (!parsed) {
     throw new Error(`Failed to parse reviewer output: no JSON found`);
   }
-  return JSON.parse(jsonMatch[0]);
+  return parsed;
 }
 
 export class ReviewerRole extends BaseRole {
@@ -93,6 +94,7 @@ export class ReviewerRole extends BaseRole {
       reviewMode: this.config?.review_mode || "standard",
       instructions: this.instructions,
       rtkAvailable: Boolean(this.config?.rtk?.available),
+      proxyEnabled: Boolean(this.config?.proxy?.enabled),
       productContext: this.config?.productContext || null,
       domainContext: this.config?.domainContext || null
     });

package/src/roles/solomon-role.js

@@ -1,5 +1,6 @@
 import { BaseRole } from "./base-role.js";
 import { createAgent as defaultCreateAgent } from "../agents/index.js";
+import { extractFirstJson } from "../utils/json-extract.js";
 
 const SUBAGENT_PREAMBLE = [
   "IMPORTANT: You are running as a Karajan sub-agent.",
@@ -98,10 +99,7 @@ function buildPrompt({ conflict, task, instructions }) {
 }
 
 function parseSolomonOutput(raw) {
-  const text = raw?.trim() || "";
-  const jsonMatch = /\{[\s\S]*\}/.exec(text);
-  if (!jsonMatch) return null;
-  return JSON.parse(jsonMatch[0]);
+  return extractFirstJson(raw);
 }
 
 function buildSummary(parsed) {

package/src/session-cleanup.js

@@ -15,25 +15,31 @@ import path from "node:path";
 import { getSessionRoot } from "./utils/paths.js";
 
 const ONE_DAY_MS = 24 * 60 * 60 * 1000;
+const DEFAULT_APPROVED_EXPIRY_DAYS = 7;
 
-const POLICY = {
-  failed:   { expiryMs: ONE_DAY_MS },
-  stopped:  { expiryMs: ONE_DAY_MS },
-  running:  { expiryMs: ONE_DAY_MS },   // stale — crashed without marking failed
-  approved: { expiryMs: 7 * ONE_DAY_MS },
-  paused:   null                          // never auto-delete
-};
+function buildPolicy(expiryDays) {
+  const approvedMs = (expiryDays ?? DEFAULT_APPROVED_EXPIRY_DAYS) * ONE_DAY_MS;
+  return {
+    failed:   { expiryMs: ONE_DAY_MS },
+    stopped:  { expiryMs: ONE_DAY_MS },
+    running:  { expiryMs: ONE_DAY_MS },   // stale — crashed without marking failed
+    approved: { expiryMs: approvedMs },
+    paused:   null                          // never auto-delete
+  };
+}
+
+const POLICY = buildPolicy();
 
-function shouldRemove(session) {
+function shouldRemove(session, policy = POLICY) {
   const status = session.status || "unknown";
-  const policy = POLICY[status];
-  if (!policy) return false;
+  const entry = policy[status];
+  if (!entry) return false;
 
   const updatedAt = new Date(session.updated_at || session.created_at).getTime();
-  return Date.now() - updatedAt > policy.expiryMs;
+  return Date.now() - updatedAt > entry.expiryMs;
 }
 
-async function tryCleanupSession({ sessionDir, dirName, removed, errors, logger }) {
+async function tryCleanupSession({ sessionDir, dirName, removed, errors, logger, policy }) {
   const sessionFile = path.join(sessionDir, "session.json");
   let session;
   try {
@@ -54,7 +60,7 @@ async function tryCleanupSession({ sessionDir, dirName, removed, errors, logger
     return;
   }
 
-  if (!shouldRemove(session)) return;
+  if (!shouldRemove(session, policy)) return;
 
   try {
     await fs.rm(sessionDir, { recursive: true, force: true });
@@ -65,7 +71,9 @@ async function tryCleanupSession({ sessionDir, dirName, removed, errors, logger
   }
 }
 
-export async function cleanupExpiredSessions({ logger } = {}) {
+export async function cleanupExpiredSessions({ logger, config } = {}) {
+  const expiryDays = config?.session?.expiry_days;
+  const policy = expiryDays ? buildPolicy(expiryDays) : POLICY;
   const sessionRoot = getSessionRoot();
 
   let entries;
@@ -81,12 +89,28 @@ export async function cleanupExpiredSessions({ logger } = {}) {
 
   for (const dir of dirs) {
     const sessionDir = path.join(sessionRoot, dir.name);
-    await tryCleanupSession({ sessionDir, dirName: dir.name, removed, errors, logger });
+    await tryCleanupSession({ sessionDir, dirName: dir.name, removed, errors, logger, policy });
   }
 
   if (removed.length > 0) {
     logger?.info?.(`Cleaned up ${removed.length} expired session(s)`);
   }
 
+  // Truncate oversized project run logs
+  const maxLogSizeMb = config?.output?.max_log_size_mb ?? 50;
+  await truncateOversizedLog(path.join(process.cwd(), ".kj", "run.log"), maxLogSizeMb, logger);
+
   return { removed: removed.length, errors };
 }
+
+async function truncateOversizedLog(logPath, maxSizeMb, logger) {
+  if (maxSizeMb <= 0) return;
+  try {
+    const stat = await fs.stat(logPath);
+    const maxBytes = maxSizeMb * 1024 * 1024;
+    if (stat.size > maxBytes) {
+      await fs.truncate(logPath, 0);
+      logger?.info?.(`Truncated oversized log ${logPath} (was ${(stat.size / 1024 / 1024).toFixed(1)}MB, limit ${maxSizeMb}MB)`);
+    }
+  } catch { /* file doesn't exist or can't be read */ }
+}

package/src/sonar/cloud-scanner.js

@@ -13,7 +13,7 @@ function buildCloudScannerArgs(projectKey, config) {
     `-Dsonar.projectKey=${projectKey}`
   ];
 
-  if (token) args.push(`-Dsonar.token=${token}`);
+  // Token passed via SONAR_TOKEN env var, not CLI args (invisible in `ps aux`)
   if (organization) args.push(`-Dsonar.organization=${organization}`);
   if (scanner.sources) args.push(`-Dsonar.sources=${scanner.sources}`);
   if (scanner.exclusions) args.push(`-Dsonar.exclusions=${scanner.exclusions}`);
@@ -63,8 +63,11 @@ export async function runSonarCloudScan(config, projectKey = null) {
   const scannerTimeout = 15 * 60 * 1000;
   const args = buildCloudScannerArgs(effectiveProjectKey, config);
 
-  // Use npx @sonar/scan (no Docker needed)
-  const result = await runCommand("npx", ["@sonar/scan", ...args], { timeout: scannerTimeout });
+  // Pass token via process env, not CLI args — invisible in `ps aux`
+  const env = { ...process.env };
+  if (token) env.SONAR_TOKEN = token;
+
+  const result = await runCommand("npx", ["@sonar/scan", ...args], { timeout: scannerTimeout, env });
 
   return {
     ok: result.exitCode === 0,

package/src/sonar/scanner.js

@@ -243,16 +243,21 @@ export async function runSonarScan(config, projectKey = null) {
     `${process.cwd()}:/usr/src`,
     ...(isLocalHost ? ["--add-host", "host.docker.internal:host-gateway"] : []),
     ...(isLocalHost || isExternalSonar ? [] : ["--network", sonarNetwork]),
-    "-e",
-    `SONAR_HOST_URL=${host}`,
-    "-e",
-    `SONAR_TOKEN=${token || ""}`,
-    "-e",
-    `SONAR_SCANNER_OPTS=${buildScannerOpts(effectiveProjectKey, scannerConfig)}`,
+    "-e", "SONAR_HOST_URL",
+    "-e", "SONAR_TOKEN",
+    "-e", "SONAR_SCANNER_OPTS",
     "sonarsource/sonar-scanner-cli"
   ];
 
-  const result = await runCommand("docker", args, { timeout: scannerTimeout });
+  // Pass secrets via process env, not CLI args — invisible in `ps aux`
+  const env = {
+    ...process.env,
+    SONAR_HOST_URL: host,
+    SONAR_TOKEN: token || "",
+    SONAR_SCANNER_OPTS: buildScannerOpts(effectiveProjectKey, scannerConfig)
+  };
+
+  const result = await runCommand("docker", args, { timeout: scannerTimeout, env });
   return {
     ok: result.exitCode === 0,
     projectKey: effectiveProjectKey,

package/src/utils/banner.js

@@ -0,0 +1,66 @@
+/**
+ * Karajan Code ASCII banner with brand colors.
+ *
+ * Brand palette:
+ *   #AACCEE  steel blue (primary text)
+ *   #88CC88  green (accents, robot eyes)
+ *   #464000  dark olive
+ *   #444411  charcoal (secondary text)
+ */
+
+const C = {
+  blue:     "\x1b[38;2;170;204;238m",  // #AACCEE
+  green:    "\x1b[38;2;100;190;100m",   // green accents
+  gray:     "\x1b[38;2;140;140;140m",   // borders/dim
+  white:    "\x1b[38;2;220;220;220m",   // bright text
+  charcoal: "\x1b[38;2;100;100;80m",    // #444411 approx
+  bold:     "\x1b[1m",
+  dim:      "\x1b[2m",
+  reset:    "\x1b[0m"
+};
+
+const R = C.reset;
+
+const BANNER_LINES = [
+  ``,
+  `${C.gray}        ╭───────────╮`,
+  `${C.gray}        │  ${C.green}~${C.gray}        │`,
+  `${C.gray}        │  ${C.green}|${C.gray}     ${C.green}|${C.gray}  │  ${C.charcoal}|`,
+  `${C.gray}        |     ${C.green}v${C.gray}     │ ${C.charcoal}/`,
+  `${C.gray}      ${C.charcoal}\\${C.gray} ╰───────────╯${C.charcoal}/`,
+  `${C.charcoal}       \\${C.gray} ╭───${C.white}⋈${C.gray}───╮ ${C.charcoal}/`,
+  `${C.charcoal}        \\${C.gray}        ${C.charcoal}/`,
+  `${C.gray}         ╰───────╯`,
+  ``,
+  `  ${C.bold}${C.blue}╦╔═ ╔═╗ ╦═╗ ╔═╗  ╦ ╔═╗ ╔╗╔${R}`,
+  `  ${C.bold}${C.blue}╠╩╗ ╠═╣ ╠╦╝ ╠═╣  ║ ╠═╣ ║║║${R}`,
+  `  ${C.bold}${C.blue}╩ ╩ ╩ ╩ ╩╚═ ╩ ╩ ╚╝ ╩ ╩ ╝╚╝${R}`,
+  `  ${C.bold}${C.white}        C O D E${R}  %%VERSION%%`,
+  `  ${C.charcoal}multiagent coding orchestrator${R}`,
+  ``,
+];
+
+/**
+ * Print the Karajan Code ASCII banner.
+ * @param {string} version - Package version to display
+ * @param {object} [opts]
+ * @param {boolean} [opts.compact] - Skip mascot, show only text
+ * @param {boolean} [opts.force] - Print even without TTY
+ */
+export function printBanner(version, opts = {}) {
+  if (!opts.force && !process.stdout.isTTY) return;
+
+  const versionTag = `${C.dim}v${version}${R}`;
+
+  if (opts.compact) {
+    console.log();
+    for (const line of BANNER_LINES.slice(10)) {
+      console.log(line.replace("%%VERSION%%", versionTag));
+    }
+    return;
+  }
+
+  for (const line of BANNER_LINES) {
+    console.log(line.replace("%%VERSION%%", versionTag));
+  }
+}