unbound-cli 1.14.0 → 1.15.0

package/test/analytics-log-table.test.js

@@ -0,0 +1,77 @@
+const test = require('node:test');
+const assert = require('node:assert');
+
+const output = require('../src/output');
+
+function capture(fn) {
+  const lines = [];
+  const original = console.log;
+  console.log = (...args) => lines.push(args.join(' '));
+  try {
+    fn();
+  } finally {
+    console.log = original;
+  }
+  return lines;
+}
+
+const HEADERS = ['Timestamp', 'User', 'Command'];
+const LONG = 'rm -rf /very/long/path/that/keeps/going/and/going/and/going/forever/and/ever';
+
+test('logTable prints a header, a rule and one line per row', () => {
+  const lines = capture(() =>
+    output.logTable(HEADERS, [['2026-08-05', 'ada', 'ls'], ['2026-08-04', 'bob', 'pwd']], { maxWidth: 120 }),
+  );
+  assert.strictEqual(lines.length, 4);
+  assert.ok(lines[0].includes('Timestamp'));
+  assert.match(lines[1], /^[─ ]+$/);
+  assert.ok(lines[2].includes('ada'));
+  assert.ok(lines[3].includes('bob'));
+});
+
+test('logTable says so instead of printing an empty frame', () => {
+  const lines = capture(() => output.logTable(HEADERS, []));
+  assert.strictEqual(lines.length, 1);
+  assert.match(lines[0], /No results found/);
+});
+
+test('logTable never exceeds the terminal width', () => {
+  const maxWidth = 60;
+  const lines = capture(() =>
+    output.logTable(HEADERS, [['2026-08-05T09:55:44Z', 'ada@example.com', LONG]], { maxWidth }),
+  );
+  for (const line of lines) {
+    // biome-ignore lint: strip ANSI colour codes before measuring
+    const plain = line.replace(/\x1b\[[0-9;]*m/g, '');
+    assert.ok(plain.length <= maxWidth, `line of ${plain.length} exceeded ${maxWidth}: ${plain}`);
+  }
+});
+
+test('logTable marks a clipped value with an ellipsis', () => {
+  const lines = capture(() => output.logTable(HEADERS, [['2026-08-05', 'ada', LONG]], { maxWidth: 60 }));
+  assert.ok(lines[2].includes('…'), 'expected the long command to be clipped');
+});
+
+test('logTable prints values in full when wide is set', () => {
+  const lines = capture(() => output.logTable(HEADERS, [['2026-08-05', 'ada', LONG]], { wide: true }));
+  assert.ok(lines[2].includes(LONG), 'wide mode must not clip');
+});
+
+test('logTable collapses newlines so one prompt cannot span many lines', () => {
+  const lines = capture(() =>
+    output.logTable(HEADERS, [['2026-08-05', 'ada', 'line one\nline two\nline three']], { wide: true }),
+  );
+  assert.strictEqual(lines.length, 3);
+  assert.ok(lines[2].includes('line one line two line three'));
+});
+
+test('logTable tolerates a row shorter than the header set', () => {
+  const lines = capture(() => output.logTable(HEADERS, [['2026-08-05']], { maxWidth: 80 }));
+  assert.strictEqual(lines.length, 3);
+  assert.ok(lines[2].includes('2026-08-05'));
+});
+
+test('logTable leaves the original table() untouched', () => {
+  assert.strictEqual(typeof output.table, 'function');
+  assert.notStrictEqual(output.table, output.logTable);
+});

package/test/analytics-paging-footer.test.js

@@ -0,0 +1,34 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+// The footer is how a person, and an agent reading stderr, learns whether it is
+// looking at everything or at one page. Saying "all" on a later page turns a
+// slice into what looks like the whole result set.
+
+function footer({ offset, rows, total, hasMore }) {
+  const nextOffset = offset + rows;
+  if (hasMore ?? nextOffset < total) {
+    return `Showing ${offset + 1}-${offset + rows} of ${total.toLocaleString()}. ` +
+      `Page with --offset ${nextOffset}, or use --format csv to export every row.`;
+  }
+  if (offset > 0) {
+    return `Showing ${offset + 1}-${offset + rows} of ${total.toLocaleString()}. End of results.`;
+  }
+  return `Showing all ${total.toLocaleString()} row(s).`;
+}
+
+test('the last page of a paged read does not claim to be all of them', () => {
+  const line = footer({ offset: 20, rows: 10, total: 564, hasMore: false });
+  assert.match(line, /Showing 21-30 of 564/);
+  assert.doesNotMatch(line, /all/, 'a slice must never read as the whole result set');
+});
+
+test('a single page that holds everything still says all', () => {
+  assert.match(footer({ offset: 0, rows: 7, total: 7, hasMore: false }), /Showing all 7 row/);
+});
+
+test('a page with more behind it points at the next offset', () => {
+  const line = footer({ offset: 0, rows: 20, total: 564, hasMore: true });
+  assert.match(line, /Showing 1-20 of 564/);
+  assert.match(line, /--offset 20/);
+});

package/test/analytics-query.test.js

@@ -0,0 +1,142 @@
+const test = require('node:test');
+const assert = require('node:assert');
+
+const {
+  DEFAULT_LIMIT,
+  buildQuery,
+  buildQueryString,
+  parseList,
+  resolveFormat,
+  resolveWindow,
+} = require('../src/lib/analytics-query');
+
+test('parseList splits comma-separated values and drops blanks', () => {
+  assert.deepStrictEqual(parseList('a, b ,,c'), ['a', 'b', 'c']);
+  assert.deepStrictEqual(parseList(''), []);
+  assert.deepStrictEqual(parseList(undefined), []);
+  assert.deepStrictEqual(parseList(['x', ' y ']), ['x', 'y']);
+});
+
+test('resolveFormat defaults to table and honours --json', () => {
+  assert.strictEqual(resolveFormat({}), 'table');
+  assert.strictEqual(resolveFormat({ format: 'csv' }), 'csv');
+  assert.strictEqual(resolveFormat({ json: true }), 'json');
+  assert.strictEqual(resolveFormat({ json: true, format: 'json' }), 'json');
+});
+
+test('resolveFormat rejects an unknown format and a contradictory --json', () => {
+  assert.throws(() => resolveFormat({ format: 'xml' }), /Invalid --format/);
+  assert.throws(() => resolveFormat({ json: true, format: 'csv' }), /Cannot combine --json/);
+});
+
+test('resolveWindow defaults to the thirty-day preset', () => {
+  assert.deepStrictEqual(resolveWindow({}), { time_window: 'THIRTY_DAYS' });
+});
+
+test('resolveWindow normalises case and hyphens in a preset', () => {
+  assert.deepStrictEqual(resolveWindow({ timeWindow: 'seven-days' }), { time_window: 'SEVEN_DAYS' });
+});
+
+test('resolveWindow accepts a valid custom range', () => {
+  assert.deepStrictEqual(
+    resolveWindow({ start: '2026-07-01', end: '2026-07-31' }),
+    { start_date: '2026-07-01', end_date: '2026-07-31' },
+  );
+});
+
+test('resolveWindow rejects half a range, a mixed range, and a bad date', () => {
+  assert.throws(() => resolveWindow({ start: '2026-07-01' }), /must be used together/);
+  assert.throws(() => resolveWindow({ end: '2026-07-01' }), /must be used together/);
+  assert.throws(
+    () => resolveWindow({ start: '2026-07-01', end: '2026-07-31', timeWindow: 'SEVEN_DAYS' }),
+    /Cannot combine --time-window/,
+  );
+  assert.throws(() => resolveWindow({ start: '07/01/2026', end: '07/31/2026' }), /Expected YYYY-MM-DD/);
+});
+
+test('resolveWindow rejects an inverted range and one wider than 90 days', () => {
+  assert.throws(() => resolveWindow({ start: '2026-07-31', end: '2026-07-01' }), /on or before/);
+  assert.throws(() => resolveWindow({ start: '2026-01-01', end: '2026-07-31' }), /maximum is 90/);
+});
+
+test('resolveWindow accepts exactly 90 days but not 91', () => {
+  assert.ok(resolveWindow({ start: '2026-01-01', end: '2026-04-01' }));
+  assert.throws(() => resolveWindow({ start: '2026-01-01', end: '2026-04-02' }), /maximum is 90/);
+});
+
+test('buildQuery asks the server for json when rendering a table', () => {
+  const query = buildQuery({}, { format: 'table' });
+  assert.strictEqual(query.format, 'json');
+  assert.strictEqual(query.limit, DEFAULT_LIMIT);
+});
+
+test('buildQuery omits limit and offset for a csv export', () => {
+  const query = buildQuery({ limit: '50', offset: '10' }, { format: 'csv' });
+  assert.strictEqual(query.format, 'csv');
+  assert.strictEqual(query.limit, undefined);
+  assert.strictEqual(query.offset, undefined);
+});
+
+test('buildQuery omits a zero offset but keeps a real one', () => {
+  assert.strictEqual(buildQuery({ offset: '0' }, { format: 'json' }).offset, undefined);
+  assert.strictEqual(buildQuery({ offset: '40' }, { format: 'json' }).offset, 40);
+});
+
+test('buildQuery maps every filter flag onto its query key', () => {
+  const query = buildQuery(
+    {
+      tool: 'claude-code,cursor',
+      user: '4,9',
+      policy: '11',
+      family: 'git_action,delete_file',
+      server: 'Notion,Slack',
+      risk: 'high,low',
+      initiator: 'agent',
+    },
+    { format: 'csv' },
+  );
+
+  assert.deepStrictEqual(query.tool_types, ['CLAUDE_CODE', 'CURSOR']);
+  assert.deepStrictEqual(query.user_ids, ['4', '9']);
+  assert.deepStrictEqual(query.policy_ids, ['11']);
+  assert.deepStrictEqual(query.command_families, ['git_action', 'delete_file']);
+  assert.deepStrictEqual(query.server, ['Notion', 'Slack']);
+  assert.deepStrictEqual(query.risk_levels, ['High', 'Low']);
+  assert.deepStrictEqual(query.intent_attribution, ['AGENT_INITIATED']);
+});
+
+test('buildQuery leaves absent filters out of the query entirely', () => {
+  const query = buildQuery({}, { format: 'csv' });
+  for (const key of ['tool_types', 'user_ids', 'policy_ids', 'command_families', 'server', 'risk_levels']) {
+    assert.ok(!(key in query), `${key} should be absent`);
+  }
+});
+
+test('buildQuery rejects invalid risk and initiator values', () => {
+  assert.throws(() => buildQuery({ risk: 'Critical' }, { format: 'csv' }), /Invalid --risk/);
+  assert.throws(() => buildQuery({ initiator: 'robot' }, { format: 'csv' }), /Invalid --initiator/);
+});
+
+test('buildQuery rejects limits outside the allowed range', () => {
+  assert.throws(() => buildQuery({ limit: '0' }, { format: 'json' }), /positive integer/);
+  assert.throws(() => buildQuery({ limit: '1.5' }, { format: 'json' }), /positive integer/);
+  assert.throws(() => buildQuery({ limit: '99999' }, { format: 'json' }), /cannot exceed 1000/);
+  assert.throws(() => buildQuery({ offset: '-1' }, { format: 'json' }), /zero or a positive/);
+});
+
+test('buildQueryString repeats a key per value instead of collapsing it', () => {
+  const qs = buildQueryString({ format: 'csv', risk_levels: ['High', 'Low'], server: ['Notion'] });
+  const params = new URLSearchParams(qs);
+  assert.deepStrictEqual(params.getAll('risk_levels'), ['High', 'Low']);
+  assert.deepStrictEqual(params.getAll('server'), ['Notion']);
+});
+
+test('buildQueryString skips empty values', () => {
+  const qs = buildQueryString({ a: 'x', b: undefined, c: null, d: '', e: [] });
+  assert.strictEqual(qs, 'a=x');
+});
+
+test('buildQueryString url-encodes values with spaces and symbols', () => {
+  const qs = buildQueryString({ server: ['Claude in Chrome', 'a&b'] });
+  assert.deepStrictEqual(new URLSearchParams(qs).getAll('server'), ['Claude in Chrome', 'a&b']);
+});

package/test/download-flag-collision.test.js

@@ -0,0 +1,52 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+
+const download = require('../src/commands/download');
+
+// Commander binds a repeated flag on the PARENT and the child's copy is left
+// undefined. When the flag is `-o`, the export silently streams to stdout
+// instead of writing the file the user named, and the command still exits 0.
+// This repo has hit that once before, on `onboard mdm`.
+
+function flagNames(command) {
+  return command.options.flatMap((opt) => [opt.short, opt.long].filter(Boolean));
+}
+
+function build() {
+  const program = new Command();
+  program.exitOverride();
+  download.register(program);
+  return program.commands.find((c) => c.name() === 'download');
+}
+
+test('no subcommand of `download` declares a flag its parent also declares', () => {
+  const group = build();
+  const parentFlags = new Set(flagNames(group));
+
+  for (const sub of group.commands) {
+    const clashing = flagNames(sub).filter((flag) => parentFlags.has(flag));
+    assert.deepEqual(
+      clashing, [],
+      `\`download ${sub.name()}\` re-declares ${clashing.join(', ')} from its parent; ` +
+      'commander binds those on the parent and the subcommand reads undefined',
+    );
+  }
+});
+
+test('the `download` group itself takes no options, so nothing can be shadowed', () => {
+  // -h/--help is added by commander and is handled before any action runs.
+  const declared = flagNames(build()).filter((f) => f !== '-h' && f !== '--help');
+  assert.deepEqual(declared, [], 'keep the group option-free so subcommands own their flags');
+});
+
+test('`download` exposes the verbs an agent needs, each taking its own -o where relevant', () => {
+  const group = build();
+  const names = group.commands.map((c) => c.name()).sort();
+  assert.deepEqual(names, ['get', 'kinds', 'start']);
+
+  for (const verb of ['get', 'start']) {
+    const sub = group.commands.find((c) => c.name() === verb);
+    assert.ok(flagNames(sub).includes('-o'), `\`download ${verb}\` must accept -o`);
+  }
+});

package/test/download-query.test.js

@@ -0,0 +1,79 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { buildQueryString, resolveLast } = require('../src/commands/download');
+const { KINDS, isJobId } = require('../src/lib/downloads');
+
+const params = (opts) => new URLSearchParams(buildQueryString(opts));
+
+test('repeated --filter keys are appended, not collapsed to the last one', () => {
+  // Every list filter on the server reads getlist(). Collapsing duplicates
+  // would silently export one tool instead of two, and the file still looks
+  // fine — which is the failure mode worth a test.
+  const q = params({ filter: ['tool_types=CLAUDE_CODE', 'tool_types=CURSOR'] });
+  assert.deepEqual(q.getAll('tool_types'), ['CLAUDE_CODE', 'CURSOR']);
+});
+
+test('--filter keeps everything after the first = so values may contain one', () => {
+  const q = params({ filter: ['search=a=b'] });
+  assert.equal(q.get('search'), 'a=b');
+});
+
+test('--filter rejects a value with no key rather than sending a blank param', () => {
+  assert.throws(() => buildQueryString({ filter: ['=value'] }), /Use key=value/);
+  assert.throws(() => buildQueryString({ filter: ['novalue'] }), /Use key=value/);
+});
+
+test('--last resolves to an absolute window the server understands', () => {
+  const q = params({ last: '7d' });
+  const start = new Date(q.get('start_date'));
+  const end = new Date(q.get('end_date'));
+  const days = (end - start) / 86400000;
+  assert.ok(Math.abs(days - 7) < 0.01, `expected ~7 days, got ${days}`);
+});
+
+test('--last accepts hours as well as days', () => {
+  const { start, end } = resolveLast('24h');
+  const hours = (end - start) / 3600000;
+  assert.ok(Math.abs(hours - 24) < 0.01, `expected ~24 hours, got ${hours}`);
+});
+
+test('--last rejects junk instead of silently exporting the default window', () => {
+  for (const bad of ['7', 'week', '7 days', '-3d', '0d', '']) {
+    assert.throws(() => resolveLast(bad), /Invalid --last|at least 1/, `"${bad}" should be rejected`);
+  }
+});
+
+test('--last and --start/--end together is an error, not a silent winner', () => {
+  assert.throws(
+    () => buildQueryString({ last: '7d', start: '2026-07-01', end: '2026-07-31' }),
+    /not both/,
+  );
+});
+
+test('--start without --end is rejected (a half range would widen the export)', () => {
+  assert.throws(() => buildQueryString({ start: '2026-07-01' }), /must be used together/);
+  assert.throws(() => buildQueryString({ end: '2026-07-31' }), /must be used together/);
+});
+
+test('no range at all is allowed — the server applies its own default window', () => {
+  assert.equal(buildQueryString({}), '');
+});
+
+test('every advertised kind names the filters it accepts', () => {
+  // The help text is the agent's only map of what each kind takes, so an empty
+  // filter list would read as "takes nothing" rather than "nobody filled it in".
+  for (const [kind, meta] of Object.entries(KINDS)) {
+    assert.ok(meta.summary && meta.summary.length > 10, `${kind} needs a summary`);
+    assert.ok(Array.isArray(meta.filters) && meta.filters.length > 0, `${kind} needs filters`);
+  }
+});
+
+test('isJobId accepts a UUID and rejects anything else', () => {
+  assert.ok(isJobId('4f2a1c9e-1b2c-4d5e-8f90-a1b2c3d4e5f6'));
+  assert.ok(isJobId('4F2A1C9E-1B2C-4D5E-8F90-A1B2C3D4E5F6'));
+  assert.equal(isJobId('logs-export'), false);
+  assert.equal(isJobId('4f2a1c9e'), false);
+  assert.equal(isJobId(''), false);
+  assert.equal(isJobId(null), false);
+});

package/test/download-safety.test.js

@@ -0,0 +1,201 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const api = require('../src/api');
+const downloads = require('../src/lib/downloads');
+const output = require('../src/output');
+const { resolveLimit, MAX_LIMIT, MAX_TABLE_LIMIT } = require('../src/lib/analytics-query');
+
+function startServer(handler) {
+  const server = http.createServer(handler);
+  return new Promise((resolve) => {
+    server.listen(0, '127.0.0.1', () => resolve({ server, port: server.address().port }));
+  });
+}
+
+function freshDir() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'dl-safety-'));
+}
+
+// Analytics cells are commands and prompts recorded from agents, so their
+// contents are chosen by whoever ran the agent. Echoing them raw lets a
+// recorded command repaint the screen, set the window title, or drive OSC 52.
+test('logTable strips terminal control sequences out of backend cells', () => {
+  const lines = [];
+  const realLog = console.log;
+  console.log = (line) => lines.push(String(line));
+  try {
+    output.logTable(
+      ['Command'],
+      [[']52;c;aGF4git push]0;pwned']],
+      { wide: true },
+    );
+  } finally {
+    console.log = realLog;
+  }
+  const printed = lines.join('\n');
+  assert.ok(printed.includes('git push'), 'the real value must survive');
+  assert.ok(!printed.includes(']'), 'OSC sequences must not reach the terminal');
+  assert.ok(!printed.includes(''), 'CSI erase must not reach the terminal');
+  assert.ok(!printed.includes('pwned'), 'the title payload must be gone with its sequence');
+});
+
+test('logTable strips control sequences out of headers too', () => {
+  const lines = [];
+  const realLog = console.log;
+  console.log = (line) => lines.push(String(line));
+  try {
+    output.logTable(['Command'], [['ls']], { wide: true });
+  } finally {
+    console.log = realLog;
+  }
+  assert.ok(!lines.join('\n').includes(''), 'header colour codes must be stripped');
+});
+
+// The download used to stream straight into the path the user named. Opening
+// that stream truncates an existing file, so a transfer that died halfway left
+// the user with nothing where their file used to be.
+test('a failed download leaves an existing -o file untouched', async () => {
+  const { server, port } = await startServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/csv', 'Content-Length': '999' });
+    res.write('partial');
+    // Cut the connection mid-body: the client sees a truncated transfer.
+    res.destroy();
+  });
+  const dir = freshDir();
+  const target = path.join(dir, 'important.csv');
+  fs.writeFileSync(target, 'MY,EXISTING,DATA\n1,2,3\n');
+  const partial = `${target}.part-${process.pid}`;
+
+  try {
+    await assert.rejects(() => api.fetchToStream(`http://127.0.0.1:${port}/x`, {
+      transport: http,
+      onHeaders: () => fs.createWriteStream(partial, { flags: 'wx', mode: 0o600 }),
+    }));
+    assert.equal(
+      fs.readFileSync(target, 'utf8'), 'MY,EXISTING,DATA\n1,2,3\n',
+      'the pre-existing file must be byte-identical after a failed download',
+    );
+  } finally {
+    try { fs.unlinkSync(partial); } catch { /* already gone */ }
+    fs.rmSync(dir, { recursive: true, force: true });
+    server.close();
+  }
+});
+
+test('the temp destination refuses to follow a symlink planted at its path', async () => {
+  const dir = freshDir();
+  const victim = path.join(dir, 'victim.txt');
+  const partial = path.join(dir, 'out.csv.part-1');
+  fs.writeFileSync(victim, 'do-not-touch\n');
+  fs.symlinkSync(victim, partial);
+  try {
+    assert.throws(
+      () => fs.createWriteStream(partial, { flags: 'wx' }).on('error', () => {}) && fs.openSync(partial, 'wx'),
+      (err) => err.code === 'EEXIST' || err.code === 'ELOOP',
+    );
+    assert.equal(fs.readFileSync(victim, 'utf8'), 'do-not-touch\n');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('--limit is capped lower for the table than for json', () => {
+  assert.equal(resolveLimit({ limit: String(MAX_TABLE_LIMIT) }, 'table'), MAX_TABLE_LIMIT);
+  assert.throws(
+    () => resolveLimit({ limit: String(MAX_TABLE_LIMIT + 1) }, 'table'),
+    /cannot exceed 100 for table output/,
+  );
+  // json is parsed, not read, so mess is not a reason to cap it low.
+  assert.equal(resolveLimit({ limit: String(MAX_LIMIT) }, 'json'), MAX_LIMIT);
+  assert.throws(() => resolveLimit({ limit: String(MAX_LIMIT + 1) }, 'json'), /cannot exceed 1000/);
+});
+
+test('a download cut mid-transfer closes its file before the caller deletes it', async () => {
+  // The caller unlinks the .part file on rejection. On Windows that fails while
+  // a write handle is still open, leaving a truncated export behind.
+  const { server, port } = await startServer((req, res) => {
+    res.writeHead(200, { 'Content-Type': 'text/csv', 'Content-Length': '9999' });
+    res.write('partial');
+    // Cut it only once the client has taken the headers and opened its file.
+    // Destroying immediately kills the socket first, so onHeaders never runs
+    // and there is no writer to leak — a different case from the real one.
+    setTimeout(() => res.destroy(), 40);
+  });
+  const dir = freshDir();
+  const partial = path.join(dir, 'out.csv.part');
+  const stream = fs.createWriteStream(partial, { flags: 'wx', mode: 0o600 });
+
+  try {
+    await assert.rejects(() => api.fetchToStream(`http://127.0.0.1:${port}/x`, {
+      transport: http,
+      onHeaders: () => stream,
+    }));
+    assert.equal(stream.destroyed, true, 'the destination must be destroyed before the caller cleans up');
+    fs.unlinkSync(partial);
+    assert.equal(fs.existsSync(partial), false);
+  } finally {
+    try { fs.unlinkSync(partial); } catch { /* already gone */ }
+    fs.rmSync(dir, { recursive: true, force: true });
+    server.close();
+  }
+});
+
+test('a file that appears during the download is not overwritten by a server-chosen name', () => {
+  // The existence check runs before the transfer and the placement after it, so
+  // the whole download sits in between. rename() would replace whatever landed
+  // there; the guarantee has to be enforced at the moment of placement.
+  const dir = freshDir();
+  const target = path.join(dir, 'acme_logs.csv');
+  const partial = `${target}.part-test`;
+  fs.writeFileSync(partial, 'the,export\n1,2\n');
+  // Created after the check would have passed, while bytes were still arriving.
+  fs.writeFileSync(target, 'SOMEONE ELSE WROTE THIS\n');
+
+  try {
+    assert.throws(
+      () => downloads.placeFile(partial, target, { replace: false, name: 'acme_logs.csv' }),
+      /already exists here/,
+    );
+    assert.equal(fs.readFileSync(target, 'utf8'), 'SOMEONE ELSE WROTE THIS\n',
+      'the file that appeared mid-download must be untouched');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('an explicit -o still replaces, because the user named that file', () => {
+  const dir = freshDir();
+  const target = path.join(dir, 'mine.csv');
+  const partial = `${target}.part-test`;
+  fs.writeFileSync(partial, 'new\n');
+  fs.writeFileSync(target, 'old\n');
+
+  try {
+    downloads.placeFile(partial, target, { replace: true, name: 'mine.csv' });
+    assert.equal(fs.readFileSync(target, 'utf8'), 'new\n');
+    assert.equal(fs.existsSync(partial), false, 'the temp file must not be left behind');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('the normal case places the file and removes the temp copy', () => {
+  const dir = freshDir();
+  const target = path.join(dir, 'fresh.csv');
+  const partial = `${target}.part-test`;
+  fs.writeFileSync(partial, 'a,b\n');
+
+  try {
+    downloads.placeFile(partial, target, { replace: false, name: 'fresh.csv' });
+    assert.equal(fs.readFileSync(target, 'utf8'), 'a,b\n');
+    assert.equal(fs.existsSync(partial), false, 'link() leaves the temp name behind unless it is unlinked');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+