acuvo-code 0.6.4 → 0.6.6

package/ENTERPRISE.md

@@ -188,7 +188,7 @@ copy, but it *is* a place a process starts, and this is a list of those. Six and
 are the numbers to quote. Counting is the first thing a reviewer does.
 
 ⚠️ **This said "18 shipped files", then "41", then "90", then "101", then "108", and every
-one went stale in turn.** The package ships **121 files — 119 in `lib/`, 2 in
+one went stale in turn.** The package ships **122 files — 120 in `lib/`, 2 in
 `bin/` — about 78511 lines**, with **238 test files** beside them (counted 2026-08-22).
 
 ⭐ **AND THE 108 WENT STALE IN THE MOST INSTRUCTIVE WAY POSSIBLE: THREE OF THE FILES IT
@@ -892,7 +892,7 @@ For completeness, the properties none of them offers:
   (`lib/media.mjs`), and generates imagery with no configuration and no account
   (`lib/imagegen.mjs`) — critiqued before it is accepted, and reported as unreviewed when
   no critic is available.
-- ⭐ **Zero dependencies.** The entire auditable surface is 121 files and 79376 lines,
+- ⭐ **Zero dependencies.** The entire auditable surface is 122 files and 79582 lines,
   and there is no `node_modules` behind it. (Counted 2026-08-22 from
   `lib/*.mjs` + `bin/*.mjs`; `test/docs-truth.test.mjs` fails the build if this number
   drifts, which is why it went 18 → 41 → 46 → 52 → 53 → 57 → 60 → 61 → 62 → 65 → 66 → 69 → 70 → 71 → 72 → 73 → 80 → 84 → 90 → 100 → 101 → 102 → 103 → 107 → 108 → 111 as modules landed (111 = the three that were WRITTEN and imported by nothing — `python.mjs`, `cache-floor.mjs`, `plan-coherence.mjs`; 108 = `warm-provider.mjs`, which keeps a session on the upstream that holds its prompt cache; 107 = `login.mjs`, the command that stores an Acuvo credential — until it existed, `writeAccount` was called by nothing and every user fell through to BYOK). ⚠️ Two of those three landed on this count while remaining UNREACHABLE, which is the sharpest illustration this document has that a file count is a claim about bytes, never about capability. ⭐ A

package/bin/acuvo.mjs

@@ -143,6 +143,23 @@ const asker = createAsker();
  * word "compaction" to stop paying for a transcript they cannot see.
  */
 import { runDoctor, formatDoctor } from '../lib/doctor.mjs';
+
+/**
+ * The package version, readable from anywhere in this file.
+ *
+ * ⚠️ THE LOCAL `pkgVersion` IS DECLARED 300 LINES BELOW ITS FIRST USE and is a
+ * `const`, so reaching for it earlier is a temporal-dead-zone ReferenceError
+ * rather than an undefined — which is how `--render-report` crashed the moment
+ * it was wired in. A second reader is the small fix; hoisting the const would
+ * move a declaration other code depends on being late.
+ */
+function readPkgVersion() {
+  try {
+    return JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;
+  } catch {
+    return '';
+  }
+}
 /**
  * ── ⭐ SHELL COMPLETION — built, tested, and reachable from nothing until now ──
  * `lib/completion.mjs` is 509 lines that generate bash, zsh and fish scripts
@@ -309,6 +326,7 @@ const LIFECYCLE_USAGE = [
    * sentence changed.
    */
   '  --doctor              Say what is actually working here: key, model chain, media',
+  '  --render-report       Print how this terminal draws the opening screen, to paste back',
   '                        endpoints, which tools would be offered, git. Every dark or',
   '                        broken line names the exact variable that fixes it. Exits 0',
   '                        when nothing is broken. ⚠️ It VERIFIES over the network: your',
@@ -351,7 +369,7 @@ const VALUED_LIFECYCLE_FLAGS = new Map([
 function extractLifecycleFlags(argv) {
   const flags = {
     sessions: false, resume: null, continueLatest: false, save: true, audit: true,
-    doctor: false, replay: null, diff: null, only: null, design: null,
+    doctor: false, renderReport: false, replay: null, diff: null, only: null, design: null,
     login: false, loginToken: null, logout: false, whoami: false,
   };
   const rest = [];
@@ -359,6 +377,13 @@ function extractLifecycleFlags(argv) {
     const arg = argv[i];
     if (arg === '--sessions') { flags.sessions = true; continue; }
     if (arg === '--doctor') { flags.doctor = true; continue; }
+    /**
+     * ⭐ THE INSTRUMENT FOR A SCREEN I CANNOT SEE. Five reports, four fixes,
+     * and every one reasoned from bytes that render perfectly on my machine.
+     * This prints the facts that decide the layout so the next round is
+     * arithmetic instead of inference.
+     */
+    if (arg === '--render-report' || arg === '--render') { flags.renderReport = true; continue; }
     if (arg === '--logout') { flags.logout = true; continue; }
     if (arg === '--whoami') { flags.whoami = true; continue; }
     /**
@@ -1185,6 +1210,22 @@ ${formatBoard(listed)}
     return EXIT_OK;
   }
 
+  /**
+   * ⚠️ BEFORE `--doctor`, AND BEFORE ANYTHING THAT PRINTS. This report is about
+   * how the terminal DRAWS, so nothing may have written to the screen ahead of
+   * it — a banner above the ruler would be measuring a screen we had already
+   * disturbed.
+   */
+  if (life.renderReport) {
+    const { renderReport, formatRenderReport } = await import('../lib/render-report.mjs');
+    const rep = await renderReport({ input: process.stdin, output: process.stdout, env: process.env, version: readPkgVersion() });
+    if (opts.json) process.stdout.write(`${JSON.stringify(rep, null, 2)}
+`);
+    else process.stdout.write(`${formatRenderReport(rep)}
+`);
+    return EXIT_OK;
+  }
+
   if (life.doctor) {
     const report = await runDoctor({ root, allowRun: opts.allowRun, maxRounds: opts.maxRounds, skipNetwork: opts.offline === true });
     if (opts.json) process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);

package/lib/render-report.mjs

@@ -0,0 +1,136 @@
+/**
+ * ── ⭐⭐⭐ STOP GUESSING AT SOMEBODY ELSE'S SCREEN ───────────────────────────
+ *
+ * Roman has now reported this screen wrong five times: "not opening as a
+ * typable terminal", "you have to scroll down", "now it's just the box,
+ * everything else is gone", "I can't even see our logo, it doesn't fit", and
+ * "CLI structure is still cooked, it's not loading like our Claude reference."
+ *
+ * ⚠️ FIVE REPORTS, FOUR FIXES, AND I HAVE NEVER ONCE SEEN THE THING I AM
+ * FIXING. Every attempt was reasoned from byte sequences that render perfectly
+ * here, and the only instrument that has ever caught a defect was him opening a
+ * terminal and describing it in words. That is a slow, lossy channel, and after
+ * four rounds it is plainly not converging.
+ *
+ * ⭐ SO THIS IS THE INSTRUMENT. One command prints every fact that determines
+ * how the opening screen draws — the emulator's identity, its real size, the
+ * MEASURED cell width of the glyphs the logo is built from, which layout that
+ * selects, and then the banner itself under a column ruler. Paste it back and
+ * the diagnosis is arithmetic instead of inference.
+ *
+ * ⚠️ IT PRINTS FACTS, NOT A VERDICT. A report that says "looks fine to me" when
+ * the user is staring at a broken screen is worse than no report — it argues
+ * with them. Every line here is something observed, and where nothing could be
+ * observed it says so.
+ */
+
+import { openingScreen } from './banner.mjs';
+import { measureCellWidth, bannerStyle } from './glyph-width.mjs';
+
+/** The environment variables that actually change how this draws. */
+const RELEVANT_ENV = [
+  'TERM', 'TERM_PROGRAM', 'TERM_PROGRAM_VERSION', 'COLORTERM',
+  'WT_SESSION', 'ConEmuANSI', 'SESSIONNAME',
+  'NO_COLOR', 'FORCE_COLOR', 'CI',
+  'ACUVO_BANNER', 'ACUVO_PIN', 'LANG', 'LC_ALL',
+];
+
+/**
+ * Gather everything, measuring what can be measured.
+ *
+ * @param {object} o
+ * @param {NodeJS.ReadStream} o.input
+ * @param {NodeJS.WriteStream} o.output
+ * @param {Record<string,string|undefined>} [o.env]
+ * @param {string} [o.version]
+ */
+export async function renderReport({ input, output, env = process.env, version = '' }) {
+  /**
+   * ⚠️ MEASURED, NOT ASSUMED — and the ASCII fallback glyphs are measured too.
+   * If a terminal renders `/` or `\` at anything other than one cell we would
+   * want to know, because the "safe" fallback would not be safe either and the
+   * whole strategy needs rethinking rather than another patch.
+   */
+  const block = await measureCellWidth({ glyph: '█', input, output });
+  const slash = await measureCellWidth({ glyph: '/', input, output });
+
+  const style = bannerStyle({ cellWidth: block, env });
+
+  return {
+    columns: output?.columns ?? null,
+    rows: output?.rows ?? null,
+    isTTY: Boolean(output?.isTTY),
+    stdinIsTTY: Boolean(input?.isTTY),
+    blockCellWidth: block,
+    asciiCellWidth: slash,
+    style,
+    env: Object.fromEntries(RELEVANT_ENV.map((k) => [k, env[k] ?? null])),
+    version,
+  };
+}
+
+/** A ruler that makes an off-by-N obvious at a glance. */
+export function ruler(width) {
+  const w = Math.max(1, Math.min(400, Number(width) || 80));
+  let out = '';
+  for (let i = 1; i <= w; i += 1) {
+    out += i % 10 === 0 ? String((i / 10) % 10) : i % 5 === 0 ? '+' : '.';
+  }
+  return out;
+}
+
+/**
+ * Render the report as text safe to paste into a chat.
+ *
+ * ⚠️ NO COLOUR ANYWHERE IN THIS OUTPUT. It exists to be copied into a message,
+ * and escape codes pasted into a chat window arrive as visual noise that hides
+ * the very alignment the report is about.
+ */
+export function formatRenderReport(r) {
+  const say = (v) => (v === null || v === undefined ? 'unknown' : String(v));
+  const lines = [];
+
+  lines.push('ACUVO RENDER REPORT' + (r.version ? `  ${r.version}` : ''));
+  lines.push('');
+  lines.push(`terminal size      ${say(r.columns)} x ${say(r.rows)}`);
+  lines.push(`stdout is a TTY    ${r.isTTY}`);
+  lines.push(`stdin is a TTY     ${r.stdinIsTTY}`);
+  lines.push('');
+
+  /**
+   * ⭐ THE TWO LINES THE WHOLE INVESTIGATION TURNS ON. A block width of 2 means
+   * the half-block logo CANNOT be drawn correctly here, and no amount of layout
+   * work will fix it — the answer is the ASCII mark. A width of 1 rules that
+   * out entirely and points the search somewhere else.
+   */
+  lines.push(`block glyph width  ${say(r.blockCellWidth)} cell(s)   <- 1 = safe, 2 = the logo tears`);
+  lines.push(`ascii glyph width  ${say(r.asciiCellWidth)} cell(s)   <- must be 1, or the fallback is unsafe too`);
+  lines.push(`chosen mark        ${r.style}`);
+  lines.push('');
+
+  const envLines = Object.entries(r.env).filter(([, v]) => v !== null);
+  lines.push(envLines.length ? 'environment' : 'environment        (none of the relevant variables are set)');
+  for (const [k, v] of envLines) lines.push(`  ${k.padEnd(20)} ${v}`);
+  lines.push('');
+
+  const width = r.columns ?? 80;
+  lines.push(`ruler (${width} columns) — the banner below must never reach the end of this line:`);
+  lines.push(ruler(width));
+  lines.push('');
+  lines.push(openingScreen({
+    version: r.version || '0.0.0',
+    workspace: 'C:/example/workspace',
+    model: 'Acuvo Flash 1',
+    billing: 'Acuvo account',
+    canRun: 'read + write + shell',
+    interactive: true,
+    style: r.style,
+    columns: r.columns,
+  }));
+  lines.push(ruler(width));
+  lines.push('');
+  lines.push('If the mark above looks torn or the rows do not line up, paste this whole');
+  lines.push('report back. Every number needed to diagnose it is in here.');
+
+  return lines.join('\n');
+}

package/lib/self-update.mjs

@@ -28,8 +28,22 @@ import { accountDir } from './account.mjs';
 
 export const PACKAGE_NAME = 'acuvo-code';
 
-/** How long between registry checks. A day is plenty and keeps npm quiet. */
-export const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+/**
+ * How long between registry checks.
+ *
+ * ⚠️ WAS 24 HOURS, AND THAT NUMBER COST US FIVE ROUNDS OF A BUG REPORT.
+ * Measured on Roman's machine 2026-08-22: the cache read
+ * `{"at":13:47,"latest":"0.2.1"}`. It was correct when written. Four hours
+ * later 0.6.5 was out, and his install would not look again until the
+ * following afternoon — so three consecutive fixes to the opening screen were
+ * invisible to him and he kept reporting a defect that had already been fixed
+ * twice. "Users get updates as soon as we ship" was false by up to a day.
+ *
+ * ⭐ Six hours, so a fix shipped in the morning lands the same working day.
+ * The registry call is one HTTP request with a 3s timeout, at EXIT — four a
+ * day is not rude, and being a day stale on a young product is expensive.
+ */
+export const CHECK_INTERVAL_MS = 6 * 60 * 60 * 1000;
 
 /**
  * Compare two semver-ish strings.
@@ -96,7 +110,22 @@ export async function checkForUpdate({
   force = false,
 } = {}) {
   const cached = readCache(cachePath);
-  if (!force && cached && now() - (cached.at ?? 0) < intervalMs) {
+  /**
+   * ── ⭐⭐⭐ A CACHE THAT CLAIMS AN OLDER VERSION IS "LATEST" IS PROVABLY WRONG
+   *
+   * If we are RUNNING 0.6.2 and the cache says the newest published version is
+   * 0.2.1, then the cache is stale — no reasoning about clocks required, it is
+   * contradicted by the file we are executing from. This is exactly the state
+   * Roman's machine was in: he had manually installed a newer build, which left
+   * a throttle entry insisting on a version four minors behind it, and that
+   * entry then suppressed every check for the rest of the day.
+   *
+   * ⭐ It costs one comparison and it converts the worst failure mode of a
+   * throttle — silently pinning somebody to an answer that is already known to
+   * be wrong — into a single extra HTTP request.
+   */
+  const cacheIsStale = cached && compareVersions(current, cached.latest) > 0;
+  if (!force && !cacheIsStale && cached && now() - (cached.at ?? 0) < intervalMs) {
     return { latest: cached.latest ?? current, isNewer: compareVersions(cached.latest, current) > 0, checked: false };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acuvo-code",
-  "version": "0.6.4",
+  "version": "0.6.6",
   "description": "Acuvo Code — the terminal client for the Acuvo capability registry. Zero dependencies, by design.",
   "type": "module",
   "bin": {