unbound-cli 0.5.0 → 0.6.0

package/src/commands/setup.js

@@ -90,8 +90,11 @@ function buildSetupCommand(scriptPath, args) {
 /**
  * Runs a Python setup script from the setup repo with inherited stdio (live output).
  */
-function runSetupScript(scriptPath, apiKey, { clear = false } = {}) {
-  const args = `--api-key ${shellEscape(apiKey)}${clear ? ' --clear' : ''}`;
+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('');
   try {
     execSync(buildSetupCommand(scriptPath, args), { stdio: 'inherit' });
@@ -177,6 +180,8 @@ function register(program) {
     .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
     .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
     .option('--all', 'Set up the default bundle: Cursor, Claude Code (hooks), Codex (hooks)')
+    .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
+    .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -252,8 +257,11 @@ automatically to authenticate before proceeding.
           const selectedTools = SETUP_TOOLS.filter(t => selected.includes(t.value));
           console.log('');
 
+          let interactiveArgs = `--api-key ${shellEscape(apiKey)}`;
+          if (opts.backendUrl) interactiveArgs += ` --backend-url ${shellEscape(opts.backendUrl)}`;
+          if (opts.frontendUrl) interactiveArgs += ` --domain ${shellEscape(opts.frontendUrl)}`;
           const ok = await runBatch(selectedTools, (tool) =>
-            runScriptPiped(tool.script, `--api-key ${shellEscape(apiKey)}`)
+            runScriptPiped(tool.script, interactiveArgs)
           );
           if (!ok) return;
 
@@ -318,13 +326,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 });
+            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 });
-              runSetupScript(SETUP_TOOL_MAP[mode.gateway].script, apiKey, { clear: true });
+              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 });
             } else {
               let useSubscription = opts.subscription;
               if (!opts.subscription && !opts.gateway) {
@@ -332,7 +340,7 @@ automatically to authenticate before proceeding.
                 useSubscription = choice === 'subscription';
               }
               const resolved = useSubscription ? mode.subscription : mode.gateway;
-              runSetupScript(SETUP_TOOL_MAP[resolved].script, apiKey, {});
+              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));
@@ -370,7 +378,10 @@ automatically to authenticate before proceeding.
         // Run automated tools with spinners
         if (resolvedScripts.length > 0) {
           console.log('');
-          const args = `--api-key ${shellEscape(apiKey)}${opts.clear ? ' --clear' : ''}`;
+          let args = `--api-key ${shellEscape(apiKey)}`;
+          if (opts.backendUrl) args += ` --backend-url ${shellEscape(opts.backendUrl)}`;
+          if (opts.frontendUrl) args += ` --domain ${shellEscape(opts.frontendUrl)}`;
+          if (opts.clear) args += ' --clear';
           const ok = await runBatch(resolvedScripts, (tool) =>
             runScriptPiped(tool.script, args)
           , { clear: opts.clear });
@@ -409,7 +420,6 @@ automatically to authenticate before proceeding.
     .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
     .option('--clear', 'Remove Unbound configuration for the specified tools')
     .option('--all', 'Set up all available tools')
-    .addOption(new Option('--url <url>', 'Override backend URL').hideHelp())
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
@@ -429,18 +439,22 @@ Examples:
   $ sudo unbound setup mdm --admin-api-key KEY --all
   $ sudo unbound setup mdm --admin-api-key KEY --clear cursor codex-subscription
 `)
-    .action(async (tools, opts) => {
+    .action(async (tools, opts, command) => {
       try {
         checkRoot();
+        // --all and --clear are defined on both this command and the parent `setup` command;
+        // --backend-url and --frontend-url are defined only on the parent `setup` command.
+        // Use optsWithGlobals() so all four work regardless of position relative to `mdm`.
+        const globalOpts = command.optsWithGlobals();
 
-        if (opts.all && tools.length > 0) {
+        if (globalOpts.all && tools.length > 0) {
           output.error('Cannot combine --all with specific tool names. Use one or the other.');
           process.exitCode = 1;
           return;
         }
 
         let toolNames;
-        if (opts.all) {
+        if (globalOpts.all) {
           toolNames = MDM_ALL_TOOLS;
         } else if (tools.length > 0) {
           toolNames = tools;
@@ -476,20 +490,21 @@ Examples:
 
         const mdmArgs = (tool) => {
           let args = `--api-key ${shellEscape(opts.adminApiKey)}`;
-          if (opts.url) args += ` --url ${shellEscape(opts.url)}`;
-          if (opts.clear) args += ' --clear';
+          if (globalOpts.backendUrl) args += ` --backend-url ${shellEscape(globalOpts.backendUrl)}`;
+          if (globalOpts.frontendUrl) args += ` --domain ${shellEscape(globalOpts.frontendUrl)}`;
+          if (globalOpts.clear) args += ' --clear';
           return args;
         };
 
         const ok = await runBatch(
           resolvedTools,
           (tool) => runScriptPiped(tool.script, mdmArgs(tool)),
-          { clear: opts.clear }
+          { clear: globalOpts.clear }
         );
         if (!ok) return;
 
         console.log('');
-        output.success(opts.clear ? 'All tools cleared' : 'All tools configured');
+        output.success(globalOpts.clear ? 'All tools cleared' : 'All tools configured');
       } catch (err) {
         output.error(err.message);
         process.exitCode = 1;
@@ -502,9 +517,11 @@ Examples:
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
-async function runSetupAllBundle(apiKey) {
+async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl } = {}) {
   const resolvedTools = ALL_TOOLS.map(name => ({ name, ...SETUP_TOOL_MAP[name] }));
-  const args = `--api-key ${shellEscape(apiKey)}`;
+  let args = `--api-key ${shellEscape(apiKey)}`;
+  if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
+  if (frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
 }
 
@@ -513,10 +530,11 @@ async function runSetupAllBundle(apiKey) {
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
-async function runMdmSetupAllBundle(adminApiKey, { url } = {}) {
+async function runMdmSetupAllBundle(adminApiKey, { backendUrl, frontendUrl } = {}) {
   const resolvedTools = MDM_ALL_TOOLS.map(name => ({ name, ...MDM_TOOLS[name] }));
   let args = `--api-key ${shellEscape(adminApiKey)}`;
-  if (url) args += ` --url ${shellEscape(url)}`;
+  if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
+  if (frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   return runBatch(resolvedTools, (tool) => runScriptPiped(tool.script, args));
 }
 

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');
+});