unbound-cli 0.5.1 → 0.7.0

package/src/commands/setup.js

@@ -1,11 +1,21 @@
-const { execSync, spawn } = require('child_process');
+const { execSync, spawn, spawnSync } = require('child_process');
 const { Option } = require('commander');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const https = require('https');
 const config = require('../config');
 const output = require('../output');
 const { ensureLoggedIn } = require('../auth');
 
 const SETUP_BASE_URL = 'https://raw.githubusercontent.com/websentry-ai/setup/refs/heads/main';
 
+// WSL reports as Linux via uname; only native Windows (cmd.exe / PowerShell)
+// takes the Windows code path. WSL keeps using the Linux curl|python3 pipe.
+function isWindowsNative() {
+  return process.platform === 'win32';
+}
+
 const SETUP_TOOLS = [
   { label: 'Cursor', value: 'cursor', script: 'cursor/setup.py' },
   { label: 'Claude Code \u2014 subscription (hooks)', value: 'claude-sub', script: 'claude-code/hooks/setup.py', group: 'claude-code' },
@@ -81,21 +91,134 @@ function shellEscape(str) {
 
 /**
  * Builds a shell command that curls a setup script and pipes it to python3.
+ * Used on macOS/Linux/WSL. Native Windows takes the runPythonScriptWindows path.
  */
 function buildSetupCommand(scriptPath, args) {
   const url = `${SETUP_BASE_URL}/${scriptPath}`;
   return `curl -fsSL "${url}" | python3 - ${args}`;
 }
 
+/**
+ * Reverses shellEscape back into an argv list so the Windows path can call
+ * spawn() directly without going through a shell. Handles unquoted tokens and
+ * single-quoted strings with '\'' for embedded quotes (the exact format
+ * shellEscape produces).
+ */
+function parsePosixArgs(s) {
+  const out = [];
+  let cur = '', inQ = false, i = 0;
+  while (i < s.length) {
+    const c = s[i];
+    if (inQ) {
+      if (c === "'" && s.substr(i, 4) === "'\\''") { cur += "'"; i += 4; continue; }
+      if (c === "'") { inQ = false; i++; continue; }
+      cur += c; i++;
+    } else {
+      if (c === ' ') { if (cur) { out.push(cur); cur = ''; } i++; continue; }
+      if (c === "'") { inQ = true; i++; continue; }
+      cur += c; i++;
+    }
+  }
+  if (cur) out.push(cur);
+  return out;
+}
+
+/**
+ * Downloads a URL to a local file. Follows one level of redirect (GitHub raw
+ * occasionally 302s). Used only by the Windows execution path.
+ */
+function downloadToFile(url, destPath) {
+  return new Promise((resolve, reject) => {
+    const request = (u, remaining) => {
+      https.get(u, (res) => {
+        if ([301, 302, 303, 307, 308].includes(res.statusCode) && res.headers.location && remaining > 0) {
+          res.resume();
+          return request(res.headers.location, remaining - 1);
+        }
+        if (res.statusCode !== 200) {
+          res.resume();
+          return reject(new Error(`Failed to download ${u}: HTTP ${res.statusCode}`));
+        }
+        const file = fs.createWriteStream(destPath);
+        res.pipe(file);
+        file.on('finish', () => file.close(resolve));
+        file.on('error', reject);
+      }).on('error', reject);
+    };
+    request(url, 3);
+  });
+}
+
+/**
+ * Resolves the Python launcher to use on native Windows.
+ * Prefers the `py` launcher (installed by python.org at C:\Windows\py.exe —
+ * no spaces in PATH), falls back to `python` on PATH.
+ */
+function resolveWindowsPython() {
+  const probe = (cmd, args) => {
+    try {
+      const r = spawnSync(cmd, args, { stdio: 'ignore', shell: false, windowsHide: true });
+      return r.status === 0;
+    } catch { return false; }
+  };
+  if (probe('py', ['-3', '--version'])) return { cmd: 'py', prefix: ['-3'] };
+  if (probe('python', ['--version'])) return { cmd: 'python', prefix: [] };
+  if (probe('python3', ['--version'])) return { cmd: 'python3', prefix: [] };
+  throw new Error(
+    'Python 3 not found. Install Python 3 from https://www.python.org/downloads/ ' +
+    'and make sure the "Add python.exe to PATH" option is checked during install.'
+  );
+}
+
+/**
+ * Windows counterpart to the curl|python3 pipe. Downloads the script to a
+ * temp file and invokes Python directly — no shell required.
+ */
+async function runPythonScriptWindows(scriptPath, args, { capture }) {
+  const url = `${SETUP_BASE_URL}/${scriptPath}`;
+  const tmp = path.join(os.tmpdir(), `unbound-${Date.now()}-${Math.random().toString(36).slice(2)}.py`);
+  await downloadToFile(url, tmp);
+  const py = resolveWindowsPython();
+  try {
+    await new Promise((resolve, reject) => {
+      const child = spawn(py.cmd, [...py.prefix, tmp, ...parsePosixArgs(args)], {
+        stdio: capture ? ['pipe', 'pipe', 'pipe'] : 'inherit',
+        shell: false,
+        windowsHide: true,
+      });
+      let out = '';
+      if (capture) {
+        child.stdin.on('error', () => {});
+        child.stdin.end();
+        child.stdout.on('data', (d) => { out += d.toString(); });
+        child.stderr.on('data', (d) => { out += d.toString(); });
+      }
+      child.on('close', (code) => {
+        if (code === 0) return resolve();
+        const err = new Error(out.trim() || `Setup script failed with exit code ${code}`);
+        if (capture) err.setupOutput = out.trim();
+        reject(err);
+      });
+      child.on('error', reject);
+    });
+  } finally {
+    try { fs.unlinkSync(tmp); } catch { /* best-effort */ }
+  }
+}
+
 /**
  * Runs a Python setup script from the setup repo with inherited stdio (live output).
  */
-function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl } = {}) {
+async function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, frontendUrl } = {}) {
   let args = `--api-key ${shellEscape(apiKey)}`;
   if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
   if (frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   if (clear) args += ' --clear';
   console.log('');
+  if (isWindowsNative()) {
+    await runPythonScriptWindows(scriptPath, args, { capture: false });
+    return;
+  }
   try {
     execSync(buildSetupCommand(scriptPath, args), { stdio: 'inherit' });
   } catch (err) {
@@ -108,6 +231,9 @@ function runSetupScript(scriptPath, apiKey, { clear = false, backendUrl, fronten
  * Returns a promise that resolves on success, rejects with captured output on failure.
  */
 function runScriptPiped(scriptPath, args) {
+  if (isWindowsNative()) {
+    return runPythonScriptWindows(scriptPath, args, { capture: true });
+  }
   return new Promise((resolve, reject) => {
     const child = spawn(buildSetupCommand(scriptPath, args), {
       shell: true,
@@ -326,13 +452,13 @@ automatically to authenticate before proceeding.
           const toolName = tools[0];
 
           if (SETUP_TOOL_MAP[toolName]) {
-            runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
+            await runSetupScript(SETUP_TOOL_MAP[toolName].script, apiKey, { clear: opts.clear, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
           } else if (MODE_TOOLS[toolName]) {
             const mode = MODE_TOOLS[toolName];
             if (opts.clear) {
               // Clear both modes
-              runSetupScript(SETUP_TOOL_MAP[mode.subscription].script, apiKey, { clear: true, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
-              runSetupScript(SETUP_TOOL_MAP[mode.gateway].script, apiKey, { clear: true, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
+              await runSetupScript(SETUP_TOOL_MAP[mode.subscription].script, apiKey, { clear: true, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
+              await runSetupScript(SETUP_TOOL_MAP[mode.gateway].script, apiKey, { clear: true, backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
             } else {
               let useSubscription = opts.subscription;
               if (!opts.subscription && !opts.gateway) {
@@ -340,7 +466,7 @@ automatically to authenticate before proceeding.
                 useSubscription = choice === 'subscription';
               }
               const resolved = useSubscription ? mode.subscription : mode.gateway;
-              runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
+              await runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, { backendUrl: opts.backendUrl, frontendUrl: opts.frontendUrl });
             }
           } else if (INSTRUCTION_TOOLS[toolName]) {
             output.keyValue(INSTRUCTION_TOOLS[toolName].values(apiKey, frontendUrl));

package/src/index.js

@@ -115,6 +115,14 @@ TOOL CONNECTIONS
   $ unbound tools connect <type>           Connect a new tool
   $ unbound tools approved                 List approved tool types
 
+CHAT (Admin/Manager)
+  $ unbound chat                           Interactive REPL (multi-turn, in-memory history)
+  $ unbound chat -m "show cost by provider for the last 30 days"
+                                           One-shot: render a chart in the terminal
+  $ unbound chat -m "..." --json           One-shot: write the raw JSON response to stdout
+  $ unbound chat -m "..." -o report.json   One-shot: write the raw JSON response to a file
+  See "unbound chat --help" for the response shape and REPL slash commands.
+
 CONFIGURATION
   $ unbound config show                    Show all settings
 
@@ -138,6 +146,7 @@ require('./commands/tools').register(program);
 require('./commands/setup').register(program);
 require('./commands/discover').register(program);
 require('./commands/onboard').register(program);
+require('./commands/chat').register(program);
 
 // config command for managing CLI settings
 const configCmd = program

package/test/chart-render.test.js

@@ -0,0 +1,205 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const chart = require('../src/chartRender');
+
+const stripAnsi = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
+
+test('reconstructRows: bar chart with single series', () => {
+  const chart_option = {
+    xAxis: { type: 'category', data: ['A', 'B', 'C'] },
+    yAxis: { type: 'value' },
+    series: [{ name: 'cost', type: 'bar', data: [10, 20, 30] }],
+  };
+  const chart_meta = { chart_type: 'bar', x: 'department', y: ['cost'] };
+  const { columns, rows } = chart.reconstructRows(chart_option, chart_meta);
+  assert.deepEqual(columns, ['department', 'cost']);
+  assert.deepEqual(rows, [
+    { department: 'A', cost: 10 },
+    { department: 'B', cost: 20 },
+    { department: 'C', cost: 30 },
+  ]);
+});
+
+test('reconstructRows: multi-series bar chart', () => {
+  const chart_option = {
+    xAxis: { data: ['A', 'B'] },
+    series: [
+      { name: 'opus', data: [10, 20] },
+      { name: 'sonnet', data: [5, 15] },
+    ],
+  };
+  const chart_meta = { chart_type: 'bar', x: 'department', y: ['opus', 'sonnet'] };
+  const { columns, rows } = chart.reconstructRows(chart_option, chart_meta);
+  assert.deepEqual(columns, ['department', 'opus', 'sonnet']);
+  assert.deepEqual(rows, [
+    { department: 'A', opus: 10, sonnet: 5 },
+    { department: 'B', opus: 20, sonnet: 15 },
+  ]);
+});
+
+test('reconstructRows: donut/pie with {name,value} data', () => {
+  const chart_option = {
+    series: [{
+      type: 'pie',
+      data: [
+        { name: 'Engineering', value: 100 },
+        { name: 'Sales', value: 50 },
+      ],
+    }],
+  };
+  const chart_meta = { chart_type: 'donut', x: 'department', y: ['cost'] };
+  const { columns, rows } = chart.reconstructRows(chart_option, chart_meta);
+  assert.deepEqual(columns, ['department', 'cost']);
+  assert.deepEqual(rows, [
+    { department: 'Engineering', cost: 100 },
+    { department: 'Sales', cost: 50 },
+  ]);
+});
+
+test('reconstructRows: dataset.source with header row (array of arrays)', () => {
+  const chart_option = {
+    dataset: {
+      source: [
+        ['provider', 'cost'],
+        ['anthropic', 1234],
+        ['openai', 567],
+      ],
+    },
+  };
+  const { columns, rows } = chart.reconstructRows(chart_option, { chart_type: 'table' });
+  assert.deepEqual(columns, ['provider', 'cost']);
+  assert.deepEqual(rows, [
+    { provider: 'anthropic', cost: 1234 },
+    { provider: 'openai', cost: 567 },
+  ]);
+});
+
+test('reconstructRows: dataset.source as array of objects', () => {
+  const chart_option = {
+    dataset: {
+      source: [
+        { provider: 'anthropic', cost: 1234 },
+        { provider: 'openai', cost: 567 },
+      ],
+    },
+  };
+  const { columns, rows } = chart.reconstructRows(chart_option, { chart_type: 'table' });
+  assert.deepEqual(columns, ['provider', 'cost']);
+  assert.equal(rows.length, 2);
+});
+
+test('reconstructRows: missing chart_option returns empty', () => {
+  assert.deepEqual(chart.reconstructRows(null, null), { columns: [], rows: [] });
+  assert.deepEqual(chart.reconstructRows(undefined, {}), { columns: [], rows: [] });
+  assert.deepEqual(chart.reconstructRows({}, {}), { columns: [], rows: [] });
+});
+
+test('reconstructRows: strips ANSI / control chars from backend-provided labels', () => {
+  const chart_option = {
+    xAxis: { data: ['\x1b]0;pwned\x07Anthropic', 'Open\nAI'] },
+    series: [{ name: 'cost', data: [100, 200] }],
+  };
+  const { rows, columns } = chart.reconstructRows(chart_option, { chart_type: 'bar', x: 'provider', y: ['cost'] });
+  assert.deepEqual(columns, ['provider', 'cost']);
+  assert.equal(rows[0].provider, 'Anthropic');
+  assert.equal(rows[1].provider, 'Open AI');
+});
+
+test('reconstructRows: dataset.source array-of-objects is capped at MAX_RECONSTRUCT_ROWS', () => {
+  const source = Array.from({ length: chart.MAX_RECONSTRUCT_ROWS + 10 }, (_, i) => ({ k: i, v: i * 2 }));
+  const { rows } = chart.reconstructRows({ dataset: { source } }, { chart_type: 'table' });
+  assert.equal(rows.length, chart.MAX_RECONSTRUCT_ROWS);
+});
+
+test('reconstructRows: caps allocation at MAX_RECONSTRUCT_ROWS', () => {
+  const huge = Array.from({ length: chart.MAX_RECONSTRUCT_ROWS + 5000 }, (_, i) => `row${i}`);
+  const hugeVals = huge.map((_, i) => i);
+  const chart_option = {
+    xAxis: { data: huge },
+    series: [{ name: 'v', data: hugeVals }],
+  };
+  const { rows } = chart.reconstructRows(chart_option, { chart_type: 'bar', x: 'p', y: ['v'] });
+  assert.equal(rows.length, chart.MAX_RECONSTRUCT_ROWS);
+});
+
+test('summarizeChart: bar with single y', () => {
+  const s = stripAnsi(chart.summarizeChart({ chart_type: 'bar', x: 'provider', y: ['cost'] }, 4));
+  assert.equal(s, 'Bar chart, x=provider, y=cost, 4 rows');
+});
+
+test('summarizeChart: handles singular row + multi y', () => {
+  const s = stripAnsi(chart.summarizeChart({ chart_type: 'line', x: 'date', y: ['cost', 'tokens'] }, 1));
+  assert.equal(s, 'Line chart, x=date, y=cost+tokens, 1 row');
+});
+
+test('summarizeChart: missing meta degrades gracefully', () => {
+  assert.equal(chart.summarizeChart({}, 0), 'Unknown chart, 0 rows');
+  assert.equal(chart.summarizeChart(null), 'Unknown chart');
+});
+
+test('renderBarChart: lines respect requested width', () => {
+  const rows = [
+    { dept: 'Engineering', cost: 30000 },
+    { dept: 'Sales', cost: 10000 },
+    { dept: 'Marketing', cost: 5000 },
+  ];
+  const out = chart.renderBarChart(rows, 'dept', 'cost', { width: 80 });
+  assert.ok(out.length > 0);
+  for (const line of out.split('\n')) {
+    assert.ok(stripAnsi(line).length <= 80, `line too long: ${stripAnsi(line)}`);
+  }
+});
+
+test('renderBarChart: empty rows returns empty string', () => {
+  assert.equal(chart.renderBarChart([], 'x', 'y'), '');
+  assert.equal(chart.renderBarChart(null, 'x', 'y'), '');
+});
+
+test('renderBarChart: scales the largest value to the full bar area', () => {
+  const rows = [{ x: 'A', y: 100 }, { x: 'B', y: 50 }];
+  const out = stripAnsi(chart.renderBarChart(rows, 'x', 'y', { width: 60 }));
+  const lines = out.split('\n');
+  const blocksA = (lines[0].match(/\u2588/g) || []).length;
+  const blocksB = (lines[1].match(/\u2588/g) || []).length;
+  assert.ok(blocksA > blocksB, 'larger value should produce more blocks');
+  assert.equal(blocksB, Math.max(1, Math.round(blocksA * 50 / 100)));
+});
+
+test('renderBarChart: all-zero values do not crash and produce empty bars', () => {
+  const rows = [{ x: 'A', y: 0 }, { x: 'B', y: 0 }];
+  const out = stripAnsi(chart.renderBarChart(rows, 'x', 'y', { width: 80 }));
+  assert.ok(out.length > 0);
+  assert.equal((out.match(/\u2588/g) || []).length, 0);
+});
+
+test('renderGroupedBarChart: emits a legend and one row per series per label', () => {
+  const rows = [
+    { dept: 'Eng', opus: 100, sonnet: 50 },
+    { dept: 'Sales', opus: 20, sonnet: 80 },
+  ];
+  const out = stripAnsi(chart.renderGroupedBarChart(rows, 'dept', ['opus', 'sonnet'], { width: 80 }));
+  assert.match(out, /Legend:/);
+  assert.match(out, /opus/);
+  assert.match(out, /sonnet/);
+  assert.match(out, /Eng/);
+  assert.match(out, /Sales/);
+});
+
+test('renderSparkline: returns a single-line braille bar between min and max', () => {
+  const out = stripAnsi(chart.renderSparkline([1, 2, 3, 4, 5, 4, 3], { width: 20 }));
+  assert.ok(out.includes('1'));
+  assert.ok(out.includes('5'));
+  assert.equal(out.split('\n').length, 1);
+});
+
+test('renderSparkline: too few points returns empty string', () => {
+  assert.equal(chart.renderSparkline([1]), '');
+  assert.equal(chart.renderSparkline([]), '');
+});
+
+test('formatNumber: integer thousands separator, decimal capped', () => {
+  assert.equal(chart.formatNumber(1234567), '1,234,567');
+  assert.equal(chart.formatNumber(12.3456), '12.35');
+  assert.equal(chart.formatNumber(0), '0');
+});

package/test/chat-internals.test.js

@@ -0,0 +1,144 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const chat = require('../src/commands/chat');
+const { sanitizeForTerminal } = require('../src/chartRender');
+
+const { safeWriteFile, expandPath, normalizeAssistantTurn, friendlyChatError } = chat._internals;
+
+function tmpFile(name) {
+  return path.join(os.tmpdir(), `unbound-cli-test-${process.pid}-${Date.now()}-${name}`);
+}
+
+test('sanitizeForTerminal: strips CSI, OSC, clipboard, title, hyperlink sequences', () => {
+  assert.equal(sanitizeForTerminal('\x1b[31mred\x1b[0m'), 'red');
+  assert.equal(sanitizeForTerminal('\x1b]0;PWNED\x07hi'), 'hi');
+  assert.equal(sanitizeForTerminal('\x1b]52;c;Y3VybHxzaA==\x07ok'), 'ok');
+  assert.equal(sanitizeForTerminal('\x1b]8;;https://evil/\x07click\x1b]8;;\x07'), 'click');
+  assert.equal(sanitizeForTerminal('a\x1bPdata\x1b\\b'), 'ab');
+  assert.equal(sanitizeForTerminal('plain text'), 'plain text');
+});
+
+test('sanitizeForTerminal: strips 8-bit C1 control bytes', () => {
+  // \x9b = 8-bit CSI, \x9d = 8-bit OSC, \x90 = 8-bit DCS. Stripping the
+  // trigger byte neutralizes the sequence; residual parameter text is
+  // harmless without the preceding control byte.
+  const a = sanitizeForTerminal('\x9b31mhello\x9b0m');
+  assert.ok(!/[\x80-\x9f]/.test(a), 'should not contain any C1 bytes');
+  assert.ok(a.includes('hello'));
+  const b = sanitizeForTerminal('a\x9dtitle\x07b');
+  assert.ok(!/[\x80-\x9f]/.test(b));
+  for (let code = 0x80; code <= 0x9f; code++) {
+    assert.equal(sanitizeForTerminal(String.fromCharCode(code)), '');
+  }
+});
+
+test('sanitizeForTerminal: removes control chars but preserves tab; collapses newlines', () => {
+  assert.equal(sanitizeForTerminal('a\x00b\x07c\x7fd'), 'abcd');
+  assert.equal(sanitizeForTerminal('line1\nline2\r\nline3'), 'line1 line2 line3');
+  assert.equal(sanitizeForTerminal('tab\there'), 'tab\there');
+});
+
+test('sanitizeForTerminal: handles non-string inputs safely', () => {
+  assert.equal(sanitizeForTerminal(null), '');
+  assert.equal(sanitizeForTerminal(undefined), '');
+  assert.equal(sanitizeForTerminal(42), '42');
+  assert.equal(sanitizeForTerminal({ a: 1 }), '[object Object]');
+});
+
+test('expandPath: expands leading ~/ to homedir, passes through absolute paths', () => {
+  assert.equal(expandPath('~'), os.homedir());
+  assert.equal(expandPath('~/foo/bar'), path.join(os.homedir(), 'foo/bar'));
+  assert.equal(expandPath('/etc/passwd'), '/etc/passwd');
+});
+
+test('safeWriteFile: happy path writes a new file with mode 0600', () => {
+  const target = tmpFile('happy.json');
+  try {
+    const resolved = safeWriteFile(target, '{"ok":true}\n');
+    assert.equal(resolved, path.resolve(target));
+    assert.equal(fs.readFileSync(target, 'utf8'), '{"ok":true}\n');
+    const stat = fs.statSync(target);
+    assert.equal(stat.mode & 0o777, 0o600);
+  } finally {
+    try { fs.unlinkSync(target); } catch { /* ignore */ }
+  }
+});
+
+test('safeWriteFile: refuses to overwrite existing file', () => {
+  const target = tmpFile('noclobber.json');
+  try {
+    fs.writeFileSync(target, 'original');
+    assert.throws(() => safeWriteFile(target, 'hijacked'), /Refusing to overwrite/);
+    assert.equal(fs.readFileSync(target, 'utf8'), 'original');
+  } finally {
+    try { fs.unlinkSync(target); } catch { /* ignore */ }
+  }
+});
+
+test('safeWriteFile: refuses to follow a symlink', () => {
+  const realTarget = tmpFile('real.txt');
+  const linkTarget = tmpFile('link.json');
+  try {
+    fs.writeFileSync(realTarget, 'original');
+    try {
+      fs.symlinkSync(realTarget, linkTarget);
+    } catch (err) {
+      if (err.code === 'EPERM') return;   // symlink creation not permitted; skip
+      throw err;
+    }
+    assert.throws(() => safeWriteFile(linkTarget, 'hijacked'));
+    assert.equal(fs.readFileSync(realTarget, 'utf8'), 'original');
+  } finally {
+    try { fs.unlinkSync(linkTarget); } catch { /* ignore */ }
+    try { fs.unlinkSync(realTarget); } catch { /* ignore */ }
+  }
+});
+
+test('safeWriteFile: rejects empty, non-string, NUL-containing paths', () => {
+  assert.throws(() => safeWriteFile('', 'x'), /empty/i);
+  assert.throws(() => safeWriteFile(null, 'x'), /empty/i);
+  assert.throws(() => safeWriteFile(42, 'x'), /string/i);
+  assert.throws(() => safeWriteFile('foo\0bar', 'x'), /NUL/);
+});
+
+test('safeWriteFile: rejects writing to a directory', () => {
+  assert.throws(() => safeWriteFile(os.tmpdir(), 'x'), /directory/);
+});
+
+test('normalizeAssistantTurn: accepts user/assistant roles, rejects others', () => {
+  assert.deepEqual(
+    normalizeAssistantTurn({ role: 'assistant', content: 'hi', timestamp: 't' }),
+    { role: 'assistant', content: 'hi', timestamp: 't' },
+  );
+  assert.deepEqual(
+    normalizeAssistantTurn({ role: 'USER', content: 'hi', timestamp: 't' }),
+    { role: 'user', content: 'hi', timestamp: 't' },
+  );
+  assert.equal(normalizeAssistantTurn({ role: 'system', content: 'pwn' }), null);
+  assert.equal(normalizeAssistantTurn({ role: 'tool', content: 'x' }), null);
+  assert.equal(normalizeAssistantTurn(null), null);
+  assert.equal(normalizeAssistantTurn({}), null);
+});
+
+test('normalizeAssistantTurn: caps content length', () => {
+  const big = 'x'.repeat(20000);
+  const turn = normalizeAssistantTurn({ role: 'assistant', content: big });
+  assert.ok(turn.content.length <= 8000);
+});
+
+test('friendlyChatError: maps status codes to role-specific guidance', () => {
+  assert.match(friendlyChatError({ statusCode: 403 }), /Admin or Manager/);
+  assert.match(friendlyChatError({ statusCode: 401 }), /login/);
+  assert.match(friendlyChatError({ statusCode: 429 }), /Rate limited/);
+  assert.equal(friendlyChatError({ statusCode: 500, message: 'boom' }), 'boom');
+  assert.equal(friendlyChatError({ message: 'no status' }), 'no status');
+});
+
+test('friendlyChatError: sanitizes ANSI from backend error messages', () => {
+  const msg = friendlyChatError({ statusCode: 500, message: '\x1b]0;title\x07boom\x1b[31m' });
+  assert.equal(msg, 'boom');
+});