commitshow 0.2.6 → 0.3.0

package/dist/commands/audit.js

@@ -2,6 +2,7 @@ import { resolveTarget, TargetError } from '../lib/target.js';
 import { findProjectByGithubUrl, fetchLatestSnapshot, fetchStanding, runPreviewAudit, waitForPreviewSnapshot, } from '../lib/api.js';
 import { renderAudit, renderMarkdown, renderJson, renderUpsell, renderQuotaFooter, renderRateLimitDeny, renderAuditError, writeAuditMarkdown, writeAuditJson, } from '../lib/render.js';
 import { c } from '../lib/colors.js';
+import { Spinner } from '../lib/spinner.js';
 export async function audit(args) {
     const asJson = args.includes('--json');
     const force = args.includes('--refresh') || args.includes('--force');
@@ -129,13 +130,24 @@ export async function audit(args) {
         emitError(asJson, err.error, err.message ?? 'Preview audit failed.', target.github_url);
         return 1;
     }
-    // Background job — poll until the snapshot lands.
+    // Background job — poll until the snapshot lands. While polling, run
+    // a TTY spinner with phase labels + elapsed time so the user sees
+    // continuous feedback during the 60-90s wait. Skipped in --json mode
+    // so machine consumers see clean output. Falls back to phase-boundary
+    // line prints in non-TTY contexts (CI · redirected stderr).
     let envelope;
     if ('status' in result && result.status === 'running') {
         const pending = result;
+        const spinner = new Spinner();
         if (!asJson)
-            console.log(c.dim('  This runs the full Claude audit · ~60-90 seconds. Hang tight.'));
-        const waited = await waitForPreviewSnapshot(pending.project_id, refreshBaseline);
+            spinner.start(`Auditing ${target.slug}`);
+        let waited;
+        try {
+            waited = await waitForPreviewSnapshot(pending.project_id, refreshBaseline);
+        }
+        finally {
+            spinner.stop();
+        }
         if (!waited) {
             emitError(asJson, 'timeout', 'Preview audit is taking longer than expected. Try `commitshow status <repo>` in a minute.', target.github_url);
             return 1;

package/dist/index.js

@@ -5,7 +5,8 @@ import { status } from './commands/status.js';
 import { login } from './commands/login.js';
 import { whoami } from './commands/whoami.js';
 import { c } from './lib/colors.js';
-const VERSION = '0.2.0';
+import { checkLatestVersion, formatUpdateBanner } from './lib/version-check.js';
+const VERSION = '0.2.11';
 const USAGE = `
 ${c.bold(c.gold('commit.show'))} ${c.dim(`v${VERSION}`)}  ${c.muted('—')} ${c.cream('audit any vibe-coded project from your terminal.')}
 ${c.muted('the')} ${c.gold('walk-on')} ${c.muted('lane: drop in, get scored, leave · no signup, no audition, no league entry.')}
@@ -41,6 +42,12 @@ ${c.muted('LEARN MORE')}
 `;
 export async function main(argv) {
     const [cmd, ...rest] = argv;
+    // Background version check · 24h cached · 2s timeout · failure-tolerant.
+    // Runs in parallel with the actual command so a slow npm registry
+    // doesn't gate audit results. Banner prints to stderr (won't pollute
+    // --json stdout) AFTER the command finishes.
+    const isJson = rest.includes('--json');
+    const versionCheck = checkLatestVersion('commitshow', VERSION).catch(() => null);
     let code = 0;
     try {
         switch (cmd) {
@@ -84,5 +91,18 @@ export async function main(argv) {
         console.error(c.scarlet(`\n  ${msg}`));
         code = 1;
     }
+    // Print update banner LAST so the audit output stays the focal point.
+    // Skip in --json mode so machine consumers see clean JSON.
+    if (!isJson) {
+        try {
+            const ck = await versionCheck;
+            if (ck && ck.outdated) {
+                process.stderr.write(formatUpdateBanner(ck));
+            }
+        }
+        catch {
+            // never block exit on version-check failure
+        }
+    }
     process.exit(code);
 }

package/dist/lib/render.js

@@ -138,10 +138,40 @@ export function renderAudit(view) {
     const slug = p.github_url?.replace(/^https?:\/\//, '') ?? '';
     lines.push('  ' + c.bold(c.cream(name)) + '   ' + c.muted(slug));
     lines.push('');
+    // ── 3 strengths + 2 concerns box · errors-first reorder (2026-04-30) ──
+    // CONCERNS render before STRENGTHS · the value prop is "what your AI
+    // missed", so they lead. Score follows as the receipt below.
+    const strengths = asStringArray(snapshot?.rich_analysis?.scout_brief?.strengths, 3);
+    const concerns = asStringArray(snapshot?.rich_analysis?.scout_brief?.weaknesses, 2);
+    if (strengths.length > 0 || concerns.length > 0) {
+        const bulletWidth = CONTENT_W - 2;
+        lines.push('  ' + boxTop());
+        // Heading row inside the box · "What this build missed" lead.
+        if (concerns.length > 0) {
+            const heading = 'What this build missed';
+            lines.push('  ' + boxRow(heading.length, c.bold(c.scarlet(heading))));
+        }
+        for (const s of concerns) {
+            const txt = truncate(s, bulletWidth);
+            lines.push('  ' + boxRow(2 + txt.length, c.scarlet('↓ ') + c.cream(txt)));
+        }
+        if (strengths.length > 0) {
+            if (concerns.length > 0)
+                lines.push('  ' + boxBlank());
+            const heading = 'What it got right';
+            lines.push('  ' + boxRow(heading.length, c.bold(c.teal(heading))));
+        }
+        for (const s of strengths) {
+            const txt = truncate(s, bulletWidth);
+            lines.push('  ' + boxRow(2 + txt.length, c.teal('↑ ') + c.cream(txt)));
+        }
+        lines.push('  ' + boxBottom());
+        lines.push('');
+    }
     // Hero score · big-digit ASCII for X-share screenshots.
-    // Always brand gold (slightly deeper tone for screenshot legibility) so
-    // the wordmark + score read as one cohesive brand mark. Band info is
-    // surfaced in the small caption underneath instead of via color.
+    // Now positioned AFTER concerns/strengths · the score is the receipt
+    // for the findings above, not the lead. Always brand gold for cohesive
+    // wordmark + score brand mark.
     const bigRows = bigText(String(total));
     const bigWidth = bigRows[0].length;
     const leftPad = Math.floor((58 - bigWidth) / 2);
@@ -149,8 +179,10 @@ export function renderAudit(view) {
         lines.push('  ' + ' '.repeat(leftPad) + c.goldDeep(row));
     }
     // Caption · small "/ 100 · band" · band tinted so the signal lives there.
-    // Walk-on track gets an extra middle segment so the score is read in the
-    // right context (88 walk-on ≠ 88 league).
+    // Walk-on track gets an extra middle segment + a sub-line surfacing the
+    // 95 max so users read the score in the right context (88 walk-on ≠ 88
+    // league · perfect walk-on caps at 95 because Scout+Community pillars
+    // structurally unevaluated).
     const band = total >= 75 ? 'strong' : total >= 50 ? 'mid' : 'weak';
     const bandTone = scoreTone(total);
     const captionVisible = isWalkOn
@@ -160,6 +192,10 @@ export function renderAudit(view) {
     if (isWalkOn) {
         lines.push('  ' + ' '.repeat(capPad)
             + c.muted('/ 100 · ') + c.gold('walk-on') + c.muted(' · ') + bandTone(band));
+        // Sub-caption explaining the 5pt headroom · centered, dim
+        const subVisible = 'audition unlocks final 5 · max walk-on score 95';
+        const subPad = Math.floor((58 - subVisible.length) / 2);
+        lines.push('  ' + ' '.repeat(subPad) + c.muted(subVisible));
     }
     else {
         lines.push('  ' + ' '.repeat(capPad) + c.muted('/ 100 · ') + bandTone(band));
@@ -183,26 +219,39 @@ export function renderAudit(view) {
         lines.push('  ' + `  Comm.  ${pad(`${p.score_community}/20`, 7)}  ${scoreBar(p.score_community, 20)}`);
     }
     lines.push('');
-    // 3 strengths + 2 concerns from scout_brief · §15-C.2 content contract.
-    // Web surfaces the full 5+3; the CLI keeps it tight for terminal screenshots.
-    const strengths = asStringArray(snapshot?.rich_analysis?.scout_brief?.strengths, 3);
-    const concerns = asStringArray(snapshot?.rich_analysis?.scout_brief?.weaknesses, 2);
-    if (strengths.length > 0 || concerns.length > 0) {
-        // strengths/concerns each render as `↑ ` (2 visible) + truncated line.
-        // Total visible-line budget inside the box is CONTENT_W chars; reserve
-        // 2 for the arrow + space, leaving CONTENT_W - 2 for the bullet text.
-        const bulletWidth = CONTENT_W - 2;
-        lines.push('  ' + boxTop());
-        for (const s of strengths) {
-            const txt = truncate(s, bulletWidth);
-            lines.push('  ' + boxRow(2 + txt.length, c.teal('↑ ') + c.cream(txt)));
-        }
-        for (const s of concerns) {
-            const txt = truncate(s, bulletWidth);
-            lines.push('  ' + boxRow(2 + txt.length, c.scarlet('↓ ') + c.cream(txt)));
+    // (concerns/strengths block moved above the score · errors-first 2026-04-30)
+    // ─── Vibe Coder Checklist · 7-category framework ───
+    // Render only the categories that produced an actionable status (fail /
+    // warn / pass when meaningful). N/A categories are dropped to keep the
+    // terminal output compact. Helps beginners see "the 7 things AI-coded
+    // projects miss" framework directly in the report.
+    const vc = snapshot?.github_signals?.vibe_concerns;
+    if (vc) {
+        const items = vibeChecklistLines(vc);
+        const actionable = items.filter(i => i.status !== 'na');
+        if (actionable.length > 0) {
+            lines.push('  ' + boxTop());
+            lines.push('  ' + boxRow('Vibe Coder Checklist · 7 things AI-coded projects miss'.length, c.bold(c.gold('Vibe Coder Checklist')) + c.muted(' · 7 things AI-coded projects miss')));
+            lines.push('  ' + boxBlank());
+            for (const it of actionable.slice(0, 7)) {
+                const tone = it.status === 'fail' ? c.scarlet : it.status === 'warn' ? c.gold : c.teal;
+                const dot = it.status === 'fail' ? '✕' : it.status === 'warn' ? '⚠' : '✓';
+                const labelVisible = `${dot} ${it.label}`;
+                const detailVisible = it.detail;
+                // First line: dot + label (status colored)
+                lines.push('  ' + boxRow(labelVisible.length, tone(`${dot} `) + c.cream(it.label)));
+                // Second line: indented detail
+                const detailTrunc = truncate(detailVisible, 50);
+                lines.push('  ' + boxRow(2 + detailTrunc.length, c.muted('  ') + c.muted(detailTrunc)));
+                // Third line: evidence (if any) · only on fail/warn so success cases stay compact
+                if (it.evidence && (it.status === 'fail' || it.status === 'warn')) {
+                    const evTrunc = truncate(it.evidence, 50);
+                    lines.push('  ' + boxRow(2 + evTrunc.length, c.muted('  → ') + c.muted(evTrunc)));
+                }
+            }
+            lines.push('  ' + boxBottom());
+            lines.push('');
         }
-        lines.push('  ' + boxBottom());
-        lines.push('');
     }
     // Standings + delta
     if (standing) {
@@ -225,6 +274,110 @@ export function renderAudit(view) {
     lines.push(' '.repeat(footerPad) + c.gold('commit.show'));
     return lines.join('\n');
 }
+function vibeChecklistLines(vc) {
+    const out = [];
+    // 1. Webhook idempotency
+    {
+        const w = vc?.webhook_idempotency;
+        if (w && w.handlers_seen > 0) {
+            const ev = w.sample_files?.[0];
+            out.push(w.gap
+                ? { key: 'webhook', status: 'fail', label: 'Webhook idempotency', detail: `${w.handlers_seen} handler${w.handlers_seen > 1 ? 's' : ''} · 0 idempotency-key check found`, evidence: ev }
+                : { key: 'webhook', status: 'pass', label: 'Webhook idempotency', detail: `${w.idempotency_signal_seen}/${w.handlers_seen} handler${w.handlers_seen > 1 ? 's' : ''} dedupe by event id`, evidence: ev });
+        }
+        else {
+            out.push({ key: 'webhook', status: 'na', label: 'Webhook idempotency', detail: 'no webhook handler files detected' });
+        }
+    }
+    // 2. RLS gaps
+    {
+        const r = vc?.rls_gaps;
+        if (r && r.tables > 0) {
+            const evList = r.tables_uncovered ?? [];
+            const ev = evList.length > 0 ? `tables: ${evList.slice(0, 3).join(', ')}${evList.length > 3 ? ` +${evList.length - 3}` : ''}` : undefined;
+            if (!r.has_rls_intent)
+                out.push({ key: 'rls', status: 'fail', label: 'RLS coverage', detail: `${r.tables} tables · 0 row-level-security policies`, evidence: ev });
+            else if (r.gap_estimate >= 3)
+                out.push({ key: 'rls', status: 'warn', label: 'RLS coverage', detail: `${r.tables} tables · ${r.policies} policies · ${r.gap_estimate} uncovered`, evidence: ev });
+            else if (r.gap_estimate > 0)
+                out.push({ key: 'rls', status: 'warn', label: 'RLS coverage', detail: `${r.tables} tables · ${r.policies} policies · ${r.gap_estimate} uncovered`, evidence: ev });
+            else
+                out.push({ key: 'rls', status: 'pass', label: 'RLS coverage', detail: `${r.tables} tables · ${r.policies} policies · all covered` });
+        }
+        else {
+            out.push({ key: 'rls', status: 'na', label: 'RLS coverage', detail: 'no SQL migrations detected' });
+        }
+    }
+    // 3. Secret exposure
+    {
+        const s = vc?.secret_exposure;
+        if (s && s.total > 0) {
+            const first = s.client_violations[0];
+            const ev = first ? `${first.file} · ${first.reason ?? first.pattern}` : undefined;
+            out.push({ key: 'secrets', status: 'fail', label: 'Secret in client code', detail: `${s.total} file${s.total > 1 ? 's' : ''} · e.g. ${first?.pattern ?? '?'}`, evidence: ev });
+        }
+        else {
+            out.push({ key: 'secrets', status: 'pass', label: 'Secret in client code', detail: 'no service-role keys in client paths' });
+        }
+    }
+    // 4. DB indexes
+    {
+        const d = vc?.db_indexes;
+        if (d && d.fk_columns_seen > 0) {
+            const sample = d.unindexed_samples?.[0];
+            const ev = sample
+                ? (sample.references ? `${sample.file} · ${sample.column} → ${sample.references}` : `${sample.file} · ${sample.column}`)
+                : undefined;
+            if (d.gap_estimate >= 3)
+                out.push({ key: 'indexes', status: 'warn', label: 'Database indexes', detail: `${d.fk_columns_seen} FK columns · ${d.indexes_seen} indexes · ${d.gap_estimate} unindexed`, evidence: ev });
+            else if (d.gap_estimate > 0)
+                out.push({ key: 'indexes', status: 'warn', label: 'Database indexes', detail: `${d.fk_columns_seen} FK · ${d.indexes_seen} idx · ${d.gap_estimate} unindexed`, evidence: ev });
+            else
+                out.push({ key: 'indexes', status: 'pass', label: 'Database indexes', detail: `${d.fk_columns_seen} FK columns · ${d.indexes_seen} indexes · healthy` });
+        }
+        else {
+            out.push({ key: 'indexes', status: 'na', label: 'Database indexes', detail: 'no SQL migrations detected' });
+        }
+    }
+    // 5. Observability
+    {
+        const o = vc?.observability;
+        if (o?.detected)
+            out.push({ key: 'observability', status: 'pass', label: 'Error tracking', detail: o.libs.join(' · ') });
+        else
+            out.push({ key: 'observability', status: 'fail', label: 'Error tracking', detail: 'no sentry / datadog / pino / winston / otel lib in package.json' });
+    }
+    // 6. Rate limiting
+    {
+        const r = vc?.rate_limit;
+        if (r) {
+            if (!r.has_api_routes)
+                out.push({ key: 'rate_limit', status: 'na', label: 'API rate limiting', detail: 'no API routes detected' });
+            else if (r.lib_detected)
+                out.push({ key: 'rate_limit', status: 'pass', label: 'API rate limiting', detail: r.lib_detected });
+            else if (r.middleware_detected)
+                out.push({ key: 'rate_limit', status: 'pass', label: 'API rate limiting', detail: 'custom middleware detected' });
+            else if (r.needs_attention)
+                out.push({ key: 'rate_limit', status: 'fail', label: 'API rate limiting', detail: 'API routes · 0 rate-limit lib or middleware' });
+        }
+        else {
+            out.push({ key: 'rate_limit', status: 'na', label: 'API rate limiting', detail: 'unknown' });
+        }
+    }
+    // 7. Prompt injection
+    {
+        const p = vc?.prompt_injection;
+        if (!p?.uses_ai_sdk)
+            out.push({ key: 'prompt_injection', status: 'na', label: 'Prompt injection risk', detail: 'no AI SDK detected' });
+        else if (p.suspicious)
+            out.push({ key: 'prompt_injection', status: 'warn', label: 'Prompt injection risk', detail: `${p.raw_input_to_prompt_files.length} file${p.raw_input_to_prompt_files.length > 1 ? 's' : ''} pipe user input into prompt` });
+        else
+            out.push({ key: 'prompt_injection', status: 'pass', label: 'Prompt injection risk', detail: 'AI SDK in use · no obvious raw-input patterns' });
+    }
+    // Sort fail → warn → pass → na
+    const order = { fail: 0, warn: 1, pass: 2, na: 3 };
+    return out.sort((a, b) => order[a.status] - order[b.status]);
+}
 function truncate(s, w) {
     const vl = s.length;
     if (vl <= w)
@@ -255,6 +408,21 @@ export function renderMarkdown(view) {
     if (p.github_url)
         lines.push(`_${p.github_url}_`);
     lines.push('');
+    // errors-first markdown order (2026-04-30) · concerns + strengths
+    // BEFORE the score so the AI agent reading audit.md picks up the
+    // actionable items in its first pass.
+    if (concerns.length > 0) {
+        lines.push(`## What this build missed`);
+        for (const s of concerns)
+            lines.push(`- ${s}`);
+        lines.push('');
+    }
+    if (strengths.length > 0) {
+        lines.push(`## What it got right`);
+        for (const s of strengths)
+            lines.push(`- ${s}`);
+        lines.push('');
+    }
     lines.push(`## Score · ${p.score_total} / 100`);
     lines.push('');
     lines.push(`- Audit:      ${p.score_auto}/50`);
@@ -267,20 +435,8 @@ export function renderMarkdown(view) {
         lines.push(`- Ranked #${standing.rank} of ${standing.total_in_season} — projected **${standing.projected_tier ?? '—'}** (top ${Math.round(standing.percentile)}%)`);
     }
     lines.push('');
-    if (strengths.length > 0) {
-        lines.push(`## Strengths`);
-        for (const s of strengths)
-            lines.push(`- ${s}`);
-        lines.push('');
-    }
-    if (concerns.length > 0) {
-        lines.push(`## Concerns`);
-        for (const s of concerns)
-            lines.push(`- ${s}`);
-        lines.push('');
-    }
     lines.push(`---`);
-    lines.push(`Auditioned on commit.show · https://commit.show/projects/${p.id}`);
+    lines.push(`Audited on commit.show · https://commit.show/projects/${p.id}`);
     lines.push('');
     return lines.join('\n');
 }

package/dist/lib/spinner.js

@@ -0,0 +1,116 @@
+// Spinner — simple progress indicator for long-running CLI ops (the
+// preview audit poll, ~60-90s of Claude time). Renders to stderr so
+// stdout stays clean for --json / pipe consumers. Animates only when
+// stderr is a real TTY; in CI / redirected output we fall back to
+// phase-change line prints (one line per ~15s milestone) so logs
+// don't drown in spinner frames but still show progress.
+//
+// Phase heuristic is time-based (server doesn't currently expose
+// staged progress over HTTP). The labels approximate what's actually
+// happening server-side:
+//   0–12 s   fetching repo signals (GitHub API · package.json · paths)
+//  12–25 s   probing live URL · Lighthouse · completeness signals
+//  25–55 s   running Claude audit · scout brief generation
+//  55–90 s   finalizing report
+//  90 s+     waiting on retry / Anthropic rate-limit recovery
+import { c } from './colors.js';
+const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
+const DEFAULT_PHASES = [
+    { until: 12, label: 'fetching repo signals' },
+    { until: 25, label: 'probing live URL · Lighthouse' },
+    { until: 55, label: 'running audit · scout brief' },
+    { until: 90, label: 'finalizing report' },
+    { until: Infinity, label: 'still cooking · larger repos can take 2–3 min' },
+];
+export class Spinner {
+    frame = 0;
+    startMs = 0;
+    timer = null;
+    label = '';
+    isTty = false;
+    active = false;
+    // Track the last phase index we printed in non-TTY mode so we only
+    // emit a new line on phase boundary (not every interval tick).
+    lastNonTtyPhase = -1;
+    start(label) {
+        if (this.active)
+            return;
+        this.label = label;
+        this.startMs = Date.now();
+        this.isTty = !!process.stderr.isTTY;
+        this.active = true;
+        if (this.isTty) {
+            // Hide cursor for cleaner animation. Restored on stop().
+            process.stderr.write('\x1b[?25l');
+            this.timer = setInterval(() => this.tickTty(), 90);
+        }
+        else {
+            // Non-TTY: print phase boundaries on a slower pulse so CI logs
+            // get a heartbeat without spinner spam.
+            this.timer = setInterval(() => this.tickPlain(), 1000);
+        }
+    }
+    /** Update the static label (e.g., switching from 'Auditing X' to
+     *  'Polling for snapshot…'). Phase label keeps its own clock. */
+    setLabel(label) {
+        this.label = label;
+    }
+    elapsedSec() {
+        return Math.floor((Date.now() - this.startMs) / 1000);
+    }
+    phaseFor(s) {
+        for (let i = 0; i < DEFAULT_PHASES.length; i++) {
+            if (s < DEFAULT_PHASES[i].until)
+                return { idx: i, label: DEFAULT_PHASES[i].label };
+        }
+        return { idx: DEFAULT_PHASES.length - 1, label: DEFAULT_PHASES[DEFAULT_PHASES.length - 1].label };
+    }
+    tickTty() {
+        const s = this.elapsedSec();
+        const ph = this.phaseFor(s);
+        const f = FRAMES[this.frame % FRAMES.length];
+        this.frame++;
+        // \r returns to column 0 · \x1b[K erases to end of line. The trailing
+        // erase is needed so a previous longer line doesn't leave a tail.
+        const line = `\r  ${c.gold(f)} ${c.cream(this.label)} ${c.muted('·')} ${c.muted(ph.label)} ${c.dim(`${s}s`)}\x1b[K`;
+        process.stderr.write(line);
+    }
+    tickPlain() {
+        const s = this.elapsedSec();
+        const ph = this.phaseFor(s);
+        if (ph.idx !== this.lastNonTtyPhase) {
+            this.lastNonTtyPhase = ph.idx;
+            process.stderr.write(`  · ${ph.label}${s > 0 ? ` (${s}s)` : ''}\n`);
+        }
+    }
+    /** Stop the spinner and (optionally) replace the line with a final
+     *  status. Final text is printed without the spinner glyph and ends
+     *  with a newline so subsequent output starts on a clean line. */
+    stop(finalText) {
+        if (!this.active)
+            return;
+        if (this.timer)
+            clearInterval(this.timer);
+        this.timer = null;
+        if (this.isTty) {
+            // Erase line, restore cursor.
+            process.stderr.write('\r\x1b[K\x1b[?25h');
+        }
+        if (finalText)
+            process.stderr.write(`  ${finalText}\n`);
+        this.active = false;
+    }
+}
+// Module-level helper · ensure we always restore the cursor even if
+// the user hits Ctrl+C while the spinner is animating. Idempotent.
+let sigintWired = false;
+function wireSigintCleanup() {
+    if (sigintWired)
+        return;
+    sigintWired = true;
+    process.on('SIGINT', () => {
+        process.stderr.write('\r\x1b[K\x1b[?25h');
+        process.exit(130);
+    });
+}
+wireSigintCleanup();

package/dist/lib/version-check.js

@@ -0,0 +1,106 @@
+// CLI auto-update detection — npx caches the resolved package version
+// for up to 24h+, so users running `npx commitshow audit` keep getting
+// a stale binary even after we publish 0.2.X+1. Asking them to clear
+// `~/.npm/_npx/` is a UX failure. Instead we check the npm registry
+// in the background, cache the answer for 24h, and surface a single
+// clear warning line + update command.
+//
+// We never block · never auto-update · just inform.
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const CACHE_DIR = join(homedir(), '.commitshow');
+const CACHE_PATH = join(CACHE_DIR, 'version-cache.json');
+const TTL_MS = 24 * 60 * 60 * 1000;
+function readCache() {
+    if (!existsSync(CACHE_PATH))
+        return null;
+    try {
+        const raw = readFileSync(CACHE_PATH, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+function writeCache(c) {
+    try {
+        if (!existsSync(CACHE_DIR))
+            mkdirSync(CACHE_DIR, { recursive: true, mode: 0o700 });
+        writeFileSync(CACHE_PATH, JSON.stringify(c), { mode: 0o600 });
+    }
+    catch {
+        // Cache write failures are non-fatal — version check just runs
+        // every invocation instead of once per 24h.
+    }
+}
+/** Compare semver-ish strings · returns >0 if a > b, 0 if equal, <0 if a < b.
+ *  Tolerates pre-release suffixes by ignoring them (best-effort, not full semver). */
+function semverCompare(a, b) {
+    const pa = a.split('.').map(s => parseInt(s, 10) || 0);
+    const pb = b.split('.').map(s => parseInt(s, 10) || 0);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const ai = pa[i] ?? 0;
+        const bi = pb[i] ?? 0;
+        if (ai !== bi)
+            return ai - bi;
+    }
+    return 0;
+}
+/** Fetch latest version from npm registry · returns null on any failure
+ *  (offline · DNS · timeout · 404). Non-blocking — caller decides if it
+ *  matters. 2s timeout cap so a slow registry doesn't gate the audit. */
+async function fetchLatestFromNpm(packageName) {
+    try {
+        const ctrl = new AbortController();
+        const timer = setTimeout(() => ctrl.abort(), 2000);
+        const res = await fetch(`https://registry.npmjs.org/${packageName}/latest`, {
+            signal: ctrl.signal,
+            headers: { accept: 'application/json' },
+        });
+        clearTimeout(timer);
+        if (!res.ok)
+            return null;
+        const j = await res.json();
+        return typeof j.version === 'string' ? j.version : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Check whether the running CLI is the latest published version.
+ *  Hits cache first (24h TTL) · falls back to npm registry GET.
+ *  Returns synchronously-ish from cache · async-fetches in the background
+ *  ONLY when cache is stale.
+ *
+ *  Caller pattern:
+ *    const ck = await checkLatestVersion('commitshow', '0.2.9')
+ *    if (ck.outdated) console.error(formatUpdateBanner(ck))
+ */
+export async function checkLatestVersion(packageName, currentVersion) {
+    const cache = readCache();
+    const fresh = cache && (Date.now() - cache.checked_at) < TTL_MS;
+    let latest = fresh ? (cache?.latest ?? null) : null;
+    if (!fresh) {
+        latest = await fetchLatestFromNpm(packageName);
+        if (latest)
+            writeCache({ checked_at: Date.now(), latest });
+    }
+    const outdated = !!(latest && semverCompare(currentVersion, latest) < 0);
+    return { current: currentVersion, latest, outdated };
+}
+/** Single-line warning banner for stale-CLI users. Goes to stderr so
+ *  it doesn't pollute --json stdout. */
+export function formatUpdateBanner(ck) {
+    if (!ck.outdated || !ck.latest)
+        return '';
+    const lines = [
+        '',
+        `⚠  A newer commitshow is available · ${ck.current} → ${ck.latest}`,
+        `   Update with:  npm install -g commitshow@latest`,
+        `   Or run once:  npx commitshow@latest <command>`,
+        `   (npx caches the binary for ~24h · @latest forces a fresh resolve)`,
+        '',
+    ];
+    return lines.join('\n');
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "commitshow",
-  "version": "0.2.6",
+  "version": "0.3.0",
   "description": "commit.show CLI — audit any vibe-coded project from your terminal.",
   "type": "module",
   "bin": {