@polderlabs/bizar 5.4.0 → 5.5.0

package/bizar-dash/tests/mobile-layout.test.tsx

@@ -293,4 +293,40 @@ describe('MobileLayout', () => {
     );
     expect(screen.getByTestId('child')).toBeInTheDocument();
   });
+
+  it('layout has correct CSS class applied', () => {
+    const { container } = render(
+      <MobileLayout
+        activeTab="activity"
+        onTabChange={vi.fn()}
+        tabs={TABS}
+        fullTabs={TABS}
+      >
+        <div>Child content</div>
+      </MobileLayout>,
+    );
+    // Verify the layout and content elements exist with correct class names
+    const layout = container.querySelector('.mobile-layout');
+    expect(layout).toBeInTheDocument();
+    const main = container.querySelector('.mobile-content');
+    expect(main).toBeInTheDocument();
+    const header = container.querySelector('.mobile-header');
+    expect(header).toBeInTheDocument();
+  });
+
+  it('renders exactly one header and one main inside the layout', () => {
+    const { container } = render(
+      <MobileLayout
+        activeTab="activity"
+        onTabChange={vi.fn()}
+        tabs={TABS}
+        fullTabs={TABS}
+      >
+        <div>Child content</div>
+      </MobileLayout>,
+    );
+    const layout = container.querySelector('.mobile-layout');
+    expect(layout!.querySelectorAll('header').length).toBe(1);
+    expect(layout!.querySelectorAll('main').length).toBe(1);
+  });
 });

package/bizar-dash/tests/settings-layout.test.tsx

@@ -57,7 +57,7 @@ describe('Sidebar — settingsMode', () => {
     // Should NOT show the normal tab rail
     expect(screen.queryByRole('tablist')).not.toBeInTheDocument();
     // Should show the back button
-    expect(screen.getByRole('button', { name: /back/i })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /exit settings/i })).toBeInTheDocument();
     // Should show section groups (use selector to avoid duplicate text matches)
     expect(screen.getByText('General', { selector: '.settings-nav-group-label' })).toBeInTheDocument();
     expect(screen.getByText('Core', { selector: '.settings-nav-group-label' })).toBeInTheDocument();
@@ -109,8 +109,8 @@ describe('Sidebar — settingsMode', () => {
         onExitSettings={onExitSettings}
       />,
     );
-    await user.click(screen.getByRole('button', { name: /memory/i }));
-    expect(onSettingsSectionChange).toHaveBeenCalledWith('memory');
+    await user.click(screen.getByRole('button', { name: /env vars/i }));
+    expect(onSettingsSectionChange).toHaveBeenCalledWith('env-vars');
   });
 
   it('calls onTabChange when a normal sidebar tab is clicked', async () => {

package/bizar-dash/tests/settings-nav.test.tsx

@@ -25,7 +25,7 @@ describe('SettingsNav', () => {
         onExitSettings={onExitSettings}
       />,
     );
-    expect(screen.getByRole('button', { name: /back/i })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /exit settings/i })).toBeInTheDocument();
   });
 
   it('calls onExitSettings when back button is clicked', async () => {
@@ -52,7 +52,7 @@ describe('SettingsNav', () => {
     expect(screen.getByText('General', { selector: '.settings-nav-group-label' })).toBeInTheDocument();
     expect(screen.getByText('Core', { selector: '.settings-nav-group-label' })).toBeInTheDocument();
     expect(screen.getByText('Experience', { selector: '.settings-nav-group-label' })).toBeInTheDocument();
-    expect(screen.getByText('Data', { selector: '.settings-nav-group-label' })).toBeInTheDocument();
+    // Data group was removed - no longer exists in SettingsNav
   });
 
   it('renders section items within each group', () => {
@@ -63,14 +63,16 @@ describe('SettingsNav', () => {
         onExitSettings={onExitSettings}
       />,
     );
+    // General group
     expect(screen.getByRole('button', { name: /theme/i })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /layout/i })).toBeInTheDocument();
+    expect(screen.getByRole('button', { name: /general/i })).toBeInTheDocument();
+    // Core group
     expect(screen.getByRole('button', { name: /env vars/i })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: /memory/i })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: /system llm/i })).toBeInTheDocument();
+    // Experience group
     expect(screen.getByRole('button', { name: /updates/i })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: /skills/i })).toBeInTheDocument();
     expect(screen.getByRole('button', { name: /headroom/i })).toBeInTheDocument();
-    expect(screen.getByRole('button', { name: /backup/i })).toBeInTheDocument();
   });
 
   it('calls onSectionChange with correct id when a section is clicked', async () => {

package/cli/bin.mjs

@@ -101,6 +101,7 @@ function showHelp() {
     dash <subcommand>   Manage the dashboard (start/stop/status/cleanup/tui)
     memory <subcommand> Manage project memory (Bizar Memory Service)
     headroom <subcommand> Manage Headroom context compression
+    lightrag <subcommand> Manage the LightRAG knowledge-graph server (status/start/autostart)
     minimax <subcommand>   Manage MiniMax Token Plan integration
     tailscale <subcommand> Manage Tailscale integration (auth, serve, status)
     mod <subcommand>       Manage mods (install/upgrade/list via the dashboard API)
@@ -284,6 +285,21 @@ async function main() {
       break;
     }
 
+    case 'lightrag': {
+      // v5.x — LightRAG management CLI (issue #6).
+      // Subcommands: status, start, autostart.
+      const mod = await importCommand('lightrag');
+      if (!mod) {
+        console.error(chalk.red(`  ✗ Could not load lightrag command module`));
+        process.exit(EXIT_ERROR);
+        return;
+      }
+      dbg('loaded command module:', 'lightrag');
+      await mod.run(cmd, cmdArgs, isHelpRequest);
+      dbg('command returned:', cmd);
+      break;
+    }
+
     case 'mod': {
       const mod = await importCommand('mod');
       if (!mod) {

package/cli/commands/deploy/docker.mjs

@@ -46,7 +46,8 @@ function generateComposeScaffold(outDir, opts) {
     '      - .env',
     '    volumes:',
     '      - bizar-config:/home/bizar/.config/bizar',
-    '      - bizar-memory:/home/bizar/.local/share/bizar/memory',
+    // v5.x — default memory vault relocated to ~/.bizar_memory
+    '      - bizar-memory:/home/bizar/.bizar_memory',
     '',
     'volumes:',
     '  bizar-config:',

package/cli/commands/lightrag.mjs

@@ -0,0 +1,171 @@
+/**
+ * cli/commands/lightrag.mjs
+ *
+ * v5.x — LightRAG management CLI (issue #6).
+ *
+ * Subcommands:
+ *   autostart          Trigger the dashboard's lightragStartupHook() against
+ *                      the current working directory's project. Used by
+ *                      `install.sh` and by operators who want to manually
+ *                      start LightRAG without opening the dashboard.
+ *   start              Alias for `autostart` (matches `headroom start`).
+ *   status             Print whether the LightRAG server is running.
+ *
+ * The dashboard server already auto-invokes `lightragStartupHook()` on
+ * boot, so this CLI is mostly for ops/debugging. The `autostart` form is
+ * the one called by `install.sh` and `bizar update` flows.
+ */
+import chalk from 'chalk';
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { process } from 'node:process';
+
+export function showLightragHelp() {
+  console.log(`
+  bizar lightrag — Manage the LightRAG knowledge graph server
+
+  Usage:
+    bizar lightrag status              Show whether LightRAG is running
+    bizar lightrag start               Start LightRAG for the current project
+    bizar lightrag autostart           Same as \`start\` — runs the startup hook
+    bizar lightrag autostart --no-dashboard  Run hook without touching the
+                                            running dashboard (skips status check)
+
+  Description:
+    LightRAG is the knowledge-graph indexer for the project's memory vault.
+    The dashboard server auto-starts LightRAG on boot (when
+    .bizar/memory.json#lightrag.enabled is true). Use this command to:
+      - manually trigger the startup hook against the current project
+      - check whether the LightRAG server is up
+
+  Environment:
+    BIZAR_LIGHTRAG_AUTOSTART=0|false|no   Disable auto-start (default: enabled)
+    BIZAR_MEMORY_VAULT=/path/to/vault     Override the memory vault location
+  `);
+}
+
+/**
+ * Resolve the project root for the lightrag command. We use `process.cwd()`
+ * — the user is expected to run this from inside a Bizar project. If
+ * `.bizar/memory.json` is missing, we still pass the cwd through and let
+ * the hook's `resolveLightRAGConfig` fall back to defaults.
+ */
+function resolveProjectRoot() {
+  return process.cwd();
+}
+
+async function runLightragCommand(lightragArgs) {
+  const sub = lightragArgs[0];
+  const flags = new Set(lightragArgs.slice(1).filter((a) => a.startsWith('-')));
+
+  if (!sub || sub === '--help' || sub === '-h' || flags.has('--help') || flags.has('-h')) {
+    showLightragHelp();
+    return;
+  }
+
+  if (sub === 'autostart' || sub === 'start') {
+    // Lazy import so the help text doesn't pay the cost of pulling in
+    // memory-lightrag (and its transitive deps) on every command.
+    const { lightragStartupHook, isRunning, resolveLightRAGConfig } = await import('../../bizar-dash/src/server/memory-lightrag.mjs');
+    const projectRoot = resolveProjectRoot();
+    console.log(chalk.dim(`  lightrag autostart: project=${projectRoot}`));
+
+    // If the dashboard is running, prefer its endpoint (it owns the
+    // server's lifecycle). Fall back to a direct hook call otherwise.
+    if (!flags.has('--no-dashboard')) {
+      try {
+        const dashboardResult = await callDashboardAutostart();
+        if (dashboardResult && dashboardResult.started) {
+          console.log(chalk.green(`  ✓ lightrag auto-started via dashboard (pid=${dashboardResult.pid || '?'})`));
+          return;
+        }
+        if (dashboardResult && dashboardResult.ok && !dashboardResult.started) {
+          console.log(chalk.dim(`  · lightrag: ${dashboardResult.reason || 'already running'}`));
+          return;
+        }
+      } catch (err) {
+        // Dashboard unreachable — fall through to direct call. Common
+        // case: user ran `bizar lightrag autostart` from a fresh shell
+        // without the dashboard running.
+        console.log(chalk.dim(`  · dashboard not reachable, running hook locally: ${err?.message || err}`));
+      }
+    }
+
+    const r = await lightragStartupHook(projectRoot);
+    if (r.ok && r.started) {
+      console.log(chalk.green(`  ✓ lightrag started (pid=${r.pid || '?'})`));
+    } else if (r.ok) {
+      console.log(chalk.dim(`  · lightrag: ${r.reason || 'not started'}`));
+    } else {
+      console.log(chalk.yellow(`  ! lightrag autostart: ${r.error || r.reason || 'failed'}`));
+      process.exitCode = 1;
+    }
+    return;
+  }
+
+  if (sub === 'status') {
+    const { isRunning, resolveLightRAGConfig } = await import('../../bizar-dash/src/server/memory-lightrag.mjs');
+    const projectRoot = resolveProjectRoot();
+    const cfg = resolveLightRAGConfig(projectRoot);
+    const running = await isRunning(cfg);
+    console.log('');
+    console.log(chalk.bold('  LightRAG status'));
+    console.log('');
+    console.log(`    ${chalk.dim('running:')}     ${running ? chalk.green('yes') : chalk.yellow('no')}`);
+    console.log(`    ${chalk.dim('host:')}        ${cfg.host}:${cfg.port}`);
+    console.log(`    ${chalk.dim('enabled:')}     ${cfg.enabled ? chalk.green('yes') : chalk.yellow('no')}`);
+    console.log(`    ${chalk.dim('workingDir:')}  ${cfg.workingDir}`);
+    console.log(`    ${chalk.dim('llmBinding:')}  ${cfg.llmBinding} (${cfg.llmModel})`);
+    console.log(`    ${chalk.dim('embedding:')}   ${cfg.embeddingBinding} (${cfg.embeddingModel})`);
+    console.log('');
+    return;
+  }
+
+  console.error(chalk.red(`  ✗ Unknown lightrag subcommand: ${sub}`));
+  showLightragHelp();
+  process.exit(1);
+}
+
+/**
+ * Call the dashboard's startup-hook endpoint if the dashboard is up.
+ * Returns the JSON body on success, null if the dashboard is unreachable
+ * (so the caller can fall back to a direct hook call).
+ */
+async function callDashboardAutostart() {
+  // Read dashboard connection from the same files the other CLI commands use.
+  const HOME = process.env.HOME || '/';
+  const portFile = join(HOME, '.config', 'bizar', 'dashboard.port');
+  const authFile = join(HOME, '.config', 'bizar', 'dash-auth.json');
+  let port = 4321;
+  let secret = '';
+  try {
+    if (existsSync(portFile)) {
+      const parsed = parseInt(readFileSync(portFile, 'utf8').trim(), 10);
+      if (Number.isFinite(parsed) && parsed > 0) port = parsed;
+    }
+  } catch { /* ignore */ }
+  try {
+    if (existsSync(authFile)) {
+      const raw = JSON.parse(readFileSync(authFile, 'utf8'));
+      secret = raw?.password || '';
+    }
+  } catch { /* ignore */ }
+  const url = `http://127.0.0.1:${port}/api/lightrag/autostart`;
+  const headers = { 'content-type': 'application/json', accept: 'application/json' };
+  if (secret) headers.authorization = `Basic ${Buffer.from(`opencode:${secret}`).toString('base64')}`;
+  const res = await fetch(url, {
+    method: 'POST',
+    headers,
+    body: JSON.stringify({}),
+    signal: AbortSignal.timeout(2000),
+  });
+  if (!res.ok) {
+    return null;
+  }
+  const text = await res.text();
+  try { return text ? JSON.parse(text) : null; } catch { return null; }
+}
+
+export async function run(name, args, isHelpRequest) {
+  await runLightragCommand(args);
+}

package/cli/commands/service.mjs

@@ -35,6 +35,8 @@ export function showServiceHelp() {
     bizar service follow           Follow the service log until Ctrl-C
     bizar service install          Register with systemd / launchd / scheduled task
     bizar service install --force  Re-install even when the unit matches
+    bizar service restart          Stop, reinstall unit, start (used by update)
+    bizar service restart --force  Reinstall the unit before starting
     bizar service uninstall        Remove the OS-level autostart
     bizar service uninstall --force  Force-uninstall even when nothing is registered
 
@@ -50,6 +52,11 @@ export function showServiceHelp() {
     install, a normal user does not need to run \`bizar service start\`
     for the dashboard background process — the OS does it at login.
 
+    restart stops the running daemon, reinstalls the unit (so the
+    freshly-installed code is loaded), and starts it again. This is
+    what \`bizar update\` uses to pick up the new binary without leaving
+    the old one running.
+
   Tailscale Integration (v5.2):
     TAILSCALE_AUTHKEY=${tsAuthkey}
     BIZAR_TAILSCALE_AUTOSETUP=${tsAuto}

package/cli/commands/util.mjs

@@ -265,8 +265,15 @@ export async function run(name, args, isHelpRequest) {
     case 'doctor':
       if (isHelpRequest) showDoctorHelp();
       else {
-        const { runDoctor } = await import('../doctor.mjs');
         const wantJson = args.includes('--json');
+        if (args[0] === 'smoke') {
+          // `bizar doctor smoke` — run post-install smoke test
+          const { runSmokeTest } = await import('../post-install-smoke.mjs');
+          const result = await runSmokeTest();
+          if (wantJson) process.stdout.write(JSON.stringify(result) + '\n');
+          process.exit(result.ok ? 0 : 1);
+        }
+        const { runDoctor } = await import('../doctor.mjs');
         const result = await runDoctor({ silent: wantJson, json: wantJson });
         if (wantJson) process.stdout.write(JSON.stringify(result) + '\n');
         if (result.failed > 0) process.exit(1);

package/cli/init.mjs

@@ -260,7 +260,7 @@ ${stack.runner ? `- Dev: \`${stack.runner}\`` : ''}
             name: 'memoryMode',
             message: 'Memory backend',
             choices: [
-              { name: 'managed (shared user-level repo at ~/.local/share/bizar/memory/bizar-memory/)', value: 'managed' },
+              { name: 'managed (shared user-level repo at ~/.bizar_memory/bizar-memory/)', value: 'managed' },
               { name: 'local-only (vault stays in this project at .obsidian/)', value: 'local-only' },
             ],
             default: 'managed',

package/cli/post-install-smoke.mjs

@@ -0,0 +1,230 @@
+/**
+ * cli/post-install-smoke.mjs
+ *
+ * v5.x — Post-install smoke test for BizarHarness.
+ *
+ * Verifies the installation is functional by checking:
+ *   1. Memory vault exists and is git-initialized
+ *   2. `bizar doctor` exits 0
+ *   3. Dashboard HTTP responds 200
+ *   4. WebSocket connects to dashboard
+ *   5. `bizar bg list` returns (even if empty)
+ *   6. lightrag-server --version works
+ *
+ * Each check has a 30s timeout. Exits 0 if all pass, 1 otherwise.
+ *
+ * Public API:
+ *   runSmokeTest({ bizarHome, repoPath })
+ *     → Promise<{ ok: boolean, checks: CheckResult[] }>
+ *
+ *   CheckResult: { name: string, ok: boolean, message: string }
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { execSync } from 'node:child_process';
+import { execFileSync } from 'node:child_process';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+const HOME = homedir();
+const DEFAULT_BIZAR_HOME = join(HOME, '.config', 'bizar');
+const DEFAULT_MEMORY_VAULT = join(HOME, '.bizar_memory');
+const DEFAULT_DASHBOARD_PORT = 4097;
+
+/**
+ * @param {object} opts
+ * @param {string} [opts.bizarHome]
+ * @param {string} [opts.repoPath]
+ * @param {number} [opts.timeoutMs]
+ */
+export async function runSmokeTest({ bizarHome, repoPath, timeoutMs = DEFAULT_TIMEOUT_MS } = {}) {
+  const bh = bizarHome || DEFAULT_BIZAR_HOME;
+  const mv = process.env.BIZAR_MEMORY_VAULT || DEFAULT_MEMORY_VAULT;
+  const port = parseInt(process.env.BIZAR_DASHBOARD_PORT || String(DEFAULT_DASHBOARD_PORT), 10) || DEFAULT_DASHBOARD_PORT;
+  const checks = [];
+
+  function check(name, fn) {
+    try {
+      const result = fn();
+      checks.push({ name, ok: result.ok, message: result.message || '' });
+    } catch (err) {
+      checks.push({ name, ok: false, message: err instanceof Error ? err.message : String(err) });
+    }
+  }
+
+  // ── 1. Memory vault exists and is git-initialised ───────────────────────
+  check('memory vault exists', () => {
+    if (!existsSync(mv)) {
+      return { ok: false, message: `${mv} does not exist` };
+    }
+    const gitDir = join(mv, '.git');
+    if (!existsSync(gitDir)) {
+      return { ok: false, message: `${mv} is not git-initialized (run: git init)` };
+    }
+    return { ok: true, message: `${mv} present and git-initialized` };
+  });
+
+  // ── 2. `bizar doctor` exits 0 ────────────────────────────────────────────
+  check('bizar doctor', () => {
+    try {
+      execSync('bizar doctor', {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+        encoding: 'utf8',
+      });
+      return { ok: true, message: 'bizar doctor passed' };
+    } catch (err) {
+      const status = err.status;
+      const msg = err.stderr || err.message;
+      if (status === 0) return { ok: true, message: 'bizar doctor passed' };
+      return { ok: false, message: `bizar doctor failed (exit ${status}): ${msg}`.slice(0, 200) };
+    }
+  });
+
+  // ── 3. Dashboard HTTP responds 200 ─────────────────────────────────────────
+  check('dashboard HTTP', async () => {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const res = await fetch(`http://127.0.0.1:${port}/`, {
+          signal: controller.signal,
+          method: 'GET',
+        });
+        clearTimeout(timer);
+        if (res.ok) return { ok: true, message: `HTTP ${res.status} on port ${port}` };
+        return { ok: false, message: `HTTP ${res.status} on port ${port} (expected 200)` };
+      } catch (err) {
+        clearTimeout(timer);
+        if (err.name === 'AbortError') {
+          return { ok: false, message: `dashboard not responding on port ${port} (timeout)` };
+        }
+        return { ok: false, message: `dashboard unreachable on port ${port}: ${err.message}` };
+      }
+    } catch (err) {
+      return { ok: false, message: `fetch not available: ${err.message}` };
+    }
+  });
+
+  // ── 4. WebSocket connects ──────────────────────────────────────────────────
+  check('dashboard WebSocket', async () => {
+    try {
+      const { WebSocket } = await import('ws' in globalThis
+        ? { ws: globalThis.ws, WebSocket: globalThis.WebSocket }
+        : await import(`ws`).then(m => ({ ws: m, WebSocket: m.WebSocket || m.default }))
+      );
+      const url = `ws://127.0.0.1:${port}/ws`;
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), timeoutMs);
+      try {
+        const ws = new WebSocket(url);
+        await new Promise((resolve, reject) => {
+          ws.on('open', resolve);
+          ws.on('error', reject);
+          ws.on('close', () => reject(new Error('closed before open')));
+          controller.signal.addEventListener('abort', () => {
+            ws.close();
+            reject(new Error('timeout'));
+          });
+        });
+        clearTimeout(timer);
+        ws.close();
+        return { ok: true, message: `WebSocket connected at ${url}` };
+      } catch (err) {
+        clearTimeout(timer);
+        if (err.message === 'timeout') {
+          return { ok: false, message: `WebSocket timeout on ${url}` };
+        }
+        return { ok: false, message: `WebSocket failed on ${url}: ${err.message}` };
+      }
+    } catch (err) {
+      // ws module not available in this environment — skip
+      if (err.code === 'MODULE_NOT_FOUND' || err.message?.includes('ws')) {
+        return { ok: true, message: 'ws module not available — skipping WebSocket check' };
+      }
+      return { ok: false, message: `WebSocket check failed: ${err.message}` };
+    }
+  });
+
+  // ── 5. `bizar bg list` returns ────────────────────────────────────────────
+  check('background agents', () => {
+    try {
+      execSync('bizar bg list', {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: timeoutMs,
+        encoding: 'utf8',
+      });
+      return { ok: true, message: 'bizar bg list succeeded' };
+    } catch (err) {
+      return { ok: false, message: `bizar bg list failed: ${(err.stderr || err.message || '').slice(0, 200)}` };
+    }
+  });
+
+  // ── 6. lightrag-server --version ──────────────────────────────────────────
+  check('lightrag-server', () => {
+    const candidates = ['lightrag-server'];
+    if (process.env.HOME) {
+      candidates.push(join(process.env.HOME, '.local', 'bin', 'lightrag-server'));
+    }
+    let found = false;
+    for (const cmd of candidates) {
+      try {
+        const out = execFileSync(cmd, ['--version'], {
+          encoding: 'utf8',
+          timeout: 5000,
+          stdio: ['ignore', 'pipe', 'ignore'],
+        });
+        found = true;
+        return { ok: true, message: `${cmd} responds: ${(out || '').trim().slice(0, 100)}` };
+      } catch { /* try next */ }
+    }
+    return { ok: false, message: 'lightrag-server not found in PATH or ~/.local/bin/' };
+  });
+
+  // ── Summary ───────────────────────────────────────────────────────────────
+  const passed = checks.filter(c => c.ok).length;
+  const failed = checks.filter(c => !c.ok).length;
+  const allOk = failed === 0;
+
+  for (const c of checks) {
+    const marker = c.ok ? '✓' : '✗';
+    const msg = c.message ? `  ${marker} ${c.name}: ${c.message}` : `  ${marker} ${c.name}`;
+    if (c.ok) {
+      console.log(`\x1b[32m${msg}\x1b[0m`);
+    } else {
+      console.log(`\x1b[31m${msg}\x1b[0m`);
+    }
+  }
+
+  console.log(`\nSmoke test: ${passed} passed, ${failed} failed`);
+  return { ok: allOk, checks, passed, failed };
+}
+
+// ── CLI entry ─────────────────────────────────────────────────────────────────
+
+const isMain = Boolean(process.argv[1]) && process.argv[1].endsWith('post-install-smoke.mjs');
+if (isMain) {
+  const args = process.argv.slice(2);
+  const dryRun = args.includes('--dry-run');
+  const json = args.includes('--json');
+
+  if (dryRun) {
+    console.log('[dry-run] would run smoke test');
+    process.exit(0);
+  }
+
+  runSmokeTest().then(result => {
+    if (json) {
+      process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    }
+    process.exit(result.ok ? 0 : 1);
+  }).catch(err => {
+    if (json) {
+      console.error(JSON.stringify({ error: err.message }));
+    } else {
+      console.error(`Smoke test error: ${err.message}`);
+    }
+    process.exit(1);
+  });
+}