quilltap 4.10.0-dev.18 → 4.10.0-dev.184

package/lib/__tests__/memories-maintain-command.test.js

@@ -0,0 +1,276 @@
+/**
+ * `quilltap memories maintain` and `validate --repair`: flag parsing, phase
+ * validation, request bodies, report rendering, and the integrity scan.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const { parseFlags, renderRepairText } = require('../memories-commands');
+const {
+  parsePhases,
+  buildMaintainBody,
+  renderMaintenanceReport,
+  renderReportsTable,
+} = require('../memories-maintain-command');
+const { scanDigestIntegrity } = require('../graph-integrity');
+
+const ID = '11111111-2222-3333-4444-555555555555';
+
+describe('memories maintain flags', () => {
+  it('parses verb, character, phases, dry-run, max, threshold, cap and port', () => {
+    const { flags, positional } = parseFlags([
+      'maintain', '--instance', 'Friday', '--character', 'Friday', '--phases', 'consolidate,demote',
+      '--dry-run', '--max', '12', '--threshold', '0.8', '--cap', '500', '--port', '3005', '--json',
+    ]);
+    expect(positional).toEqual(['maintain']);
+    expect(flags).toMatchObject({
+      instance: 'Friday', character: 'Friday', phases: 'consolidate,demote', dryRun: true,
+      max: 12, threshold: 0.8, cap: 500, port: 3005, json: true,
+    });
+  });
+
+  it('leaves the port undefined so the instance lock can supply it', () => {
+    expect(parseFlags(['maintain', '--character', 'X']).flags.port).toBeUndefined();
+    expect(parseFlags(['maintain', '-p', '3007']).flags.port).toBe(3007);
+  });
+
+  it('parses --repair and --write for validate', () => {
+    const { flags } = parseFlags(['validate', '--repair', '--write']);
+    expect(flags).toMatchObject({ repair: true, write: true });
+  });
+});
+
+describe('parsePhases', () => {
+  it('returns null for every phase', () => {
+    expect(parsePhases('')).toBeNull();
+    expect(parsePhases(undefined)).toBeNull();
+  });
+
+  it('trims and drops duplicates, leaving names and order to the server', () => {
+    expect(parsePhases('mirror, demote,fold-near-duplicates,demote')).toEqual(['mirror', 'demote', 'fold-near-duplicates']);
+    // No local phase list: an unknown name is the server's 400 to report.
+    expect(parsePhases('consolidate,housekeep')).toEqual(['consolidate', 'housekeep']);
+  });
+});
+
+describe('buildMaintainBody', () => {
+  it('defaults to a real run of every phase with no overrides', () => {
+    const { flags } = parseFlags(['maintain', '--character', 'X']);
+    expect(buildMaintainBody(ID, flags)).toEqual({ characterId: ID, dryRun: false });
+  });
+
+  it('maps the knobs onto settings', () => {
+    const { flags } = parseFlags([
+      'maintain', '--dry-run', '--phases', 'consolidate', '--max', '5', '--threshold', '0.65', '--cap', '300',
+    ]);
+    expect(buildMaintainBody(ID, flags)).toEqual({
+      characterId: ID,
+      dryRun: true,
+      phases: ['consolidate'],
+      settings: { maxClustersPerRun: 5, consolidation: { clusterThreshold: 0.65 }, cap: 300 },
+    });
+  });
+
+  it('omits characterId for a user-wide run', () => {
+    const { flags } = parseFlags(['maintain', '--character', 'all']);
+    expect(buildMaintainBody(null, flags)).toEqual({ dryRun: false });
+  });
+
+  it('allows a user-wide dry run of the model-free phases', () => {
+    const { flags } = parseFlags(['maintain', '--dry-run', '--phases', 'demote,retire']);
+    expect(buildMaintainBody(null, flags)).toEqual({ dryRun: true, phases: ['demote', 'retire'] });
+  });
+
+  it('passes bounds through for the server to judge (no local copy of its limits)', () => {
+    expect(buildMaintainBody(ID, parseFlags(['maintain', '--cap', '50']).flags)).toMatchObject({ settings: { cap: 50 } });
+    expect(buildMaintainBody(ID, parseFlags(['maintain', '--max', '5000']).flags)).toMatchObject({ settings: { maxClustersPerRun: 5000 } });
+    expect(buildMaintainBody(null, parseFlags(['maintain', '--dry-run']).flags)).toEqual({ dryRun: true });
+  });
+});
+
+describe('renderMaintenanceReport', () => {
+  function capture(fn) {
+    let out = '';
+    fn((s) => { out += s; });
+    return out.replace(/\x1b\[[0-9;]*m/g, '');
+  }
+
+  it('prints phase lines and every phase detail', () => {
+    const out = capture((write) => renderMaintenanceReport({
+      characterId: ID, characterName: 'Ariadne', dryRun: true, durationMs: 2500,
+      phases: [
+        { phase: 'fold-near-duplicates', status: 'ran', durationMs: 10 },
+        { phase: 'consolidate', status: 'ran', durationMs: 2000 },
+        { phase: 'demote', status: 'ran', durationMs: 5 },
+        { phase: 'retire', status: 'skipped', skippedBecause: 'no-retention-window', durationMs: 0 },
+        { phase: 'mirror', status: 'ran', durationMs: 3 },
+      ],
+      fold: {
+        eligible: 80, deferred: 0, groupsDeferred: 0, folded: 2, groupsFailed: 0,
+        groups: [{ survivorId: 'aaaaaaaa-1', absorbedIds: ['bbbbbbbb-2', 'cccccccc-3'], minCosine: 0.97 }],
+      },
+      consolidation: {
+        dryRun: true,
+        clusters: [{
+          bucket: { kind: 'other', subjectName: 'Calvin', subjectCharacterId: 'c' },
+          clusterKind: 'semantic', status: 'planned',
+          memberIds: ['aaaaaaaa-1', 'bbbbbbbb-2'], memberContents: ['Calvin likes tea', 'Calvin drinks tea daily'],
+          keepStandalone: ['bbbbbbbb-2'], contradictions: [{ olderId: 'aaaaaaaa-1', newerId: 'bbbbbbbb-2', note: 'tea vs coffee' }],
+          digests: [{ id: 'd1', action: 'create', content: 'Calvin is a devoted tea drinker', importance: 0.6, memberIds: ['aaaaaaaa-1'] }],
+        }],
+        stats: { candidates: 40, clustersFound: 3, clustersAttempted: 1, clustersDeferred: 2, durationMs: 1500 },
+      },
+      demote: {
+        cap: 1000, hotTotal: 1300, demotable: 1200, protected: 100, excess: 200, demoted: 200,
+        demotedIds: [], highestScoreDemoted: 0.4,
+      },
+      mirror: { subjects: ['self', 'Calvin'], filesWritten: 0, deferredToCommit: false },
+    }, write));
+    expect(out).toContain('Maintenance dry run');
+    expect(out).toContain('Ariadne');
+    expect(out).toContain('no-retention-window');
+    expect(out).toContain('aaaaaaaa <=');
+    expect(out).toContain('folded 2');
+    expect(out).toContain('about Calvin');
+    expect(out).toContain('Calvin likes tea');
+    expect(out).toContain('[kept standalone]');
+    expect(out).toContain('Calvin is a devoted tea drinker');
+    expect(out).toContain('tea vs coffee');
+    expect(out).toContain('candidates 40');
+    expect(out).toContain('cap 1000');
+    expect(out).toContain('demotable 1200');
+    expect(out).toContain('excess 200');
+    expect(out).toContain('self, Calvin');
+  });
+
+  it('reports a skipped run', () => {
+    const out = capture((write) => renderMaintenanceReport({
+      characterId: ID, characterName: null, dryRun: true, skippedReason: 'archived', phases: [],
+    }, write));
+    expect(out).toContain('Skipped: archived');
+  });
+
+  it('reports a skipped consolidation', () => {
+    const out = capture((write) => renderMaintenanceReport({
+      characterId: ID, characterName: 'A', dryRun: true, phases: [],
+      consolidation: { dryRun: true, skippedReason: 'no-llm', clusters: [], stats: {} },
+    }, write));
+    expect(out).toContain('Skipped: no-llm');
+  });
+});
+
+describe('renderReportsTable', () => {
+  it('prints one row per character', () => {
+    let out = '';
+    renderReportsTable([
+      {
+        characterId: ID, characterName: 'Ariadne', dryRun: true,
+        phases: [{ phase: 'demote', status: 'ran', durationMs: 1 }, { phase: 'retire', status: 'ran', durationMs: 1 }],
+        demote: { cap: 1000, hotTotal: 10, demotable: 10, protected: 0, excess: 0, demoted: 0, demotedIds: [], highestScoreDemoted: null },
+        retire: { retentionDays: 90, retired: 3, retiredIds: [] },
+      },
+      { characterId: 'ffffffff-0', characterName: null, dryRun: true, skippedReason: 'archived', phases: [] },
+    ], (s) => { out += s; });
+    out = out.replace(/\x1b\[[0-9;]*m/g, '');
+    expect(out).toContain('across 2 characters');
+    expect(out).toMatch(/Ariadne\s+demote,retire\s+-\s+10\/1000 -0\s+3/);
+    expect(out).toContain('ffffffff');
+    expect(out).toContain('skipped: archived');
+  });
+});
+
+describe('scanDigestIntegrity', () => {
+  // better-sqlite3 is mocked under jest, so drive the scanner with a fake
+  // that answers the handful of queries it issues.
+  function fakeDb(rows, columns) {
+    const has = new Set(columns);
+    const scoped = (sql, params) => (sql.includes('characterId = ?') ? rows.filter((r) => r.characterId === params[0]) : rows);
+    return {
+      prepare(sql) {
+        return {
+          all: (...params) => {
+            if (sql.startsWith('PRAGMA')) return [...has].map((name) => ({ name }));
+            if (sql.trim() === 'SELECT id FROM memories') return rows.map((r) => ({ id: r.id }));
+            if (sql.includes('consolidatedFrom FROM')) {
+              return scoped(sql, params).filter((r) => r.consolidatedFrom && r.consolidatedFrom !== '[]');
+            }
+            if (sql.includes('supersededById FROM')) return scoped(sql, params).filter((r) => r.supersededById != null);
+            throw new Error(`unexpected query: ${sql}`);
+          },
+          get: (...params) => {
+            if (sql.includes('embedding IS NULL')) return { n: scoped(sql, params).filter((r) => r.embedding == null).length };
+            throw new Error(`unexpected query: ${sql}`);
+          },
+        };
+      },
+    };
+  }
+
+  const ALL_COLUMNS = ['id', 'characterId', 'relatedMemoryIds', 'consolidatedFrom', 'supersededById', 'embedding'];
+
+  it('counts dangling digest members, dangling supersededById and missing embeddings', () => {
+    const db = fakeDb([
+      { id: 'digest', characterId: 'c1', consolidatedFrom: JSON.stringify(['m1', 'gone1', 'gone2']), supersededById: null, embedding: 'x' },
+      { id: 'm1', characterId: 'c1', consolidatedFrom: '[]', supersededById: 'digest', embedding: 'x' },
+      { id: 'm2', characterId: 'c1', consolidatedFrom: '[]', supersededById: 'gone-digest', embedding: null },
+      { id: 'other', characterId: 'c2', consolidatedFrom: JSON.stringify(['gone3']), supersededById: null, embedding: null },
+    ], ALL_COLUMNS);
+
+    const one = scanDigestIntegrity(db, { characterId: 'c1', includePairs: true });
+    expect(one.consolidatedFrom).toEqual({ links: 2, digests: 1 });
+    expect(one.supersededBy).toBe(1);
+    expect(one.missingEmbeddings).toBe(1);
+    expect(one.consolidatedFromPairs).toEqual([{ digestId: 'digest', characterId: 'c1', memberIds: ['gone1', 'gone2'] }]);
+    expect(one.supersededByPairs).toEqual([{ memberId: 'm2', characterId: 'c1', digestId: 'gone-digest' }]);
+
+    const all = scanDigestIntegrity(db);
+    expect(all.consolidatedFrom).toEqual({ links: 3, digests: 2 });
+    expect(all.missingEmbeddings).toBe(2);
+  });
+
+  it('reads an instance without the tier-era columns as nothing to scan', () => {
+    const db = fakeDb([{ id: 'm1', characterId: 'c1', embedding: null }], ['id', 'characterId', 'relatedMemoryIds', 'embedding']);
+    expect(scanDigestIntegrity(db)).toEqual({
+      consolidatedFrom: { links: 0, digests: 0 }, supersededBy: 0, missingEmbeddings: 1,
+    });
+  });
+});
+
+describe('renderRepairText', () => {
+  function captureLog(fn) {
+    const lines = [];
+    const spy = jest.spyOn(console, 'log').mockImplementation((...args) => { lines.push(args.join(' ')); });
+    try { fn(); } finally { spy.mockRestore(); }
+    return lines.join('\n').replace(/\x1b\[[0-9;]*m/g, '');
+  }
+  const found = {
+    related: { links: 3, rows: 2 }, consolidatedFrom: { links: 1, digests: 1 }, supersededBy: 2, missingEmbeddings: 4,
+  };
+
+  it('prints a dry run with the --write hint', () => {
+    const out = captureLog(() => renderRepairText({ dryRun: true, characterId: null, found }));
+    expect(out).toContain('dry run, every memory');
+    expect(out).toContain('3 dangling related link(s) on 2 row(s)');
+    expect(out).toContain('1 dangling consolidatedFrom member(s) on 1 digest(s)');
+    expect(out).toContain('2 dangling supersededById');
+    expect(out).toContain('4 row(s) without an embedding');
+    expect(out).toContain('Add --write');
+  });
+
+  it('prints the repaired counts and a skipped embedding pass', () => {
+    const out = captureLog(() => renderRepairText({
+      dryRun: false, characterId: ID, found,
+      repaired: {
+        relatedRowsTouched: 2, digestsTouched: 1, membersCut: 2, charactersAffected: 1,
+        embeddingJobsQueued: 0, embeddingSkippedReason: 'no-embedding-profile',
+      },
+    }));
+    expect(out).toContain('(applied)');
+    expect(out).toContain('2 row(s) relinked, 1 digest(s) touched, 2 member(s) cut loose');
+    expect(out).toContain('0 embedding job(s) queued');
+    expect(out).toContain('no-embedding-profile');
+    expect(out).not.toContain('Add --write');
+  });
+});

package/lib/__tests__/migrations-source-ids.test.js

@@ -0,0 +1,54 @@
+/**
+ * `quilltap migrations status` compares the ledger against the ids it reads
+ * out of `migrations/scripts/*.ts`. Most migrations declare their id through a
+ * `MIGRATION_ID` constant rather than a string literal; when the reader only
+ * understood literals, every one of those vanished from "source" and showed up
+ * as "retired" on any instance that had run it.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const { extractMigrationId } = require('../migrations-commands');
+
+describe('extractMigrationId', () => {
+  it('reads a string-literal id', () => {
+    expect(extractMigrationId(`export const m = {\n  id: 'foo-v1',\n};`)).toBe('foo-v1');
+  });
+
+  it('resolves an id declared through MIGRATION_ID', () => {
+    const src = `const MIGRATION_ID = 'bar-v1';\nexport const m = {\n  id: MIGRATION_ID,\n};`;
+    expect(extractMigrationId(src)).toBe('bar-v1');
+  });
+
+  it('accepts a typed MIGRATION_ID constant', () => {
+    const src = `const MIGRATION_ID: string = 'baz-v1'\nexport const m = {\n  id: MIGRATION_ID,\n};`;
+    expect(extractMigrationId(src)).toBe('baz-v1');
+  });
+
+  it('returns null when no id is declared', () => {
+    expect(extractMigrationId('export const nothing = 1;')).toBeNull();
+  });
+});
+
+describe('every migration script yields an id', () => {
+  const scriptsDir = path.join(__dirname, '..', '..', '..', '..', 'migrations', 'scripts');
+  const files = fs.existsSync(scriptsDir)
+    ? fs.readdirSync(scriptsDir).filter((f) => f.endsWith('.ts') && f !== 'index.ts')
+    : [];
+
+  it('finds the migration scripts', () => {
+    expect(files.length).toBeGreaterThan(100);
+  });
+
+  it('extracts an id from each one', () => {
+    const missing = files.filter(
+      (f) => !extractMigrationId(fs.readFileSync(path.join(scriptsDir, f), 'utf8'))
+    );
+    expect(missing).toEqual([]);
+  });
+});

package/lib/__tests__/server-port-resolution.test.js

@@ -0,0 +1,122 @@
+/**
+ * Universal-flag parsing and server-port resolution for the HTTP diagnostic
+ * tools (anchor-probe, recall-replay, memory-diff).
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+
+const { resolveServerPort } = require('../lock-helpers');
+const tools = {
+  'anchor-probe': require('../anchor-probe-command').parseFlags,
+  'recall-replay': require('../recall-replay-command').parseFlags,
+  'memory-diff': require('../memory-diff-command').parseFlags,
+};
+
+describe.each(Object.keys(tools))('%s flag parsing', (name) => {
+  const parseFlags = tools[name];
+
+  it.each([
+    [['--instance', 'V4test', 'ID']],
+    [['ID', '--instance', 'V4test']],
+    [['-i', 'V4test', 'ID']],
+    [['ID', '-i', 'V4test']],
+  ])('accepts the instance flag around the positional id (%j)', (args) => {
+    const { flags, positional } = parseFlags(args);
+    expect(flags.instance).toBe('V4test');
+    expect(positional).toEqual(['ID']);
+  });
+
+  it.each([
+    [['--data-dir', '/x/y', 'ID']],
+    [['ID', '-d', '/x/y']],
+  ])('accepts the data-dir flag (%j)', (args) => {
+    const { flags, positional } = parseFlags(args);
+    expect(flags.dataDir).toBe('/x/y');
+    expect(positional).toEqual(['ID']);
+  });
+
+  it('accepts --passphrase without treating its value as the id', () => {
+    const { positional } = parseFlags(['--passphrase', 'hunter2', 'ID']);
+    expect(positional).toEqual(['ID']);
+    expect(parseFlags(['ID', '--passphrase', 'hunter2']).positional).toEqual(['ID']);
+  });
+
+  it('leaves the port undefined unless --port is given', () => {
+    expect(parseFlags(['ID']).flags.port).toBeUndefined();
+    expect(parseFlags(['ID', '--port', '3005']).flags.port).toBe(3005);
+  });
+});
+
+describe('resolveServerPort', () => {
+  let root;
+  let lockPath;
+
+  function writeLock(overrides = {}) {
+    const now = new Date().toISOString();
+    fs.writeFileSync(lockPath, JSON.stringify({
+      pid: process.pid,
+      hostname: os.hostname(),
+      startedAt: now,
+      lastHeartbeat: now,
+      environment: 'local',
+      processTitle: 'node',
+      processArgv0: process.argv[0],
+      history: [],
+      ...overrides,
+    }));
+  }
+
+  beforeEach(() => {
+    root = fs.mkdtempSync(path.join(os.tmpdir(), 'qtap-port-test-'));
+    fs.mkdirSync(path.join(root, 'data'));
+    lockPath = path.join(root, 'data', 'quilltap.lock');
+  });
+
+  afterEach(() => fs.rmSync(root, { recursive: true, force: true }));
+
+  it('defaults to 3000 with no flags at all', () => {
+    expect(resolveServerPort({})).toMatchObject({ port: 3000, source: 'default', note: null });
+  });
+
+  it('lets an explicit --port win over a live lock', () => {
+    writeLock({ port: 3005 });
+    expect(resolveServerPort({ port: 4000, dataDir: root })).toMatchObject({ port: 4000, source: 'flag' });
+  });
+
+  it('uses the port from a live lock and says so', () => {
+    writeLock({ port: 3005 });
+    const r = resolveServerPort({ dataDir: root });
+    expect(r).toMatchObject({ port: 3005, source: 'lock' });
+    expect(r.note).toContain('3005');
+  });
+
+  it('falls back to 3000 when the live lock records no port', () => {
+    writeLock();
+    const r = resolveServerPort({ dataDir: root });
+    expect(r).toMatchObject({ port: 3000, source: 'default', note: null });
+    expect(r.hint).toContain('records no port');
+  });
+
+  it('ignores the port of a stale lock', () => {
+    writeLock({ pid: 2 ** 22 + 12345, port: 3005 });
+    const r = resolveServerPort({ dataDir: root });
+    expect(r.port).toBe(3000);
+    expect(r.hint).toContain('stale');
+  });
+
+  it('falls back to 3000 when there is no lock', () => {
+    const r = resolveServerPort({ dataDir: root });
+    expect(r.port).toBe(3000);
+    expect(r.hint).toContain('no instance lock');
+  });
+
+  it('rejects --instance together with --data-dir', () => {
+    expect(() => resolveServerPort({ instance: 'x', dataDir: root })).toThrow(/not both/);
+  });
+});

package/lib/__tests__/sync-report.test.js

@@ -0,0 +1,158 @@
+/**
+ * How `quilltap sync` renders a plan.
+ *
+ * The formatter is the operator's whole view of what the verb did, and its
+ * two load-bearing claims are easy to get subtly wrong: the second column is
+ * the side that CHANGES (so `modify store` means the store is rewritten from
+ * disk, not the other way round), and the exit code distinguishes "an
+ * unresolved conflict" from "something failed" so a script can tell them apart.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const {
+  formatActionLine,
+  formatActionLines,
+  formatSummary,
+  exitCodeFor,
+  displayPath,
+  formatBytes,
+} = require('../sync-report');
+
+function action(over = {}) {
+  return { kind: 'create', side: 'disk', relativePath: 'a.md', entryKind: 'file', ...over };
+}
+
+function summary(over = {}) {
+  return {
+    created: 0, modified: 0, deleted: 0, touched: 0,
+    described: 0, conflicts: 0, skipped: 0, failed: 0, ...over,
+  };
+}
+
+describe('one action, one line', () => {
+  it('puts the action first and the side that changes second', () => {
+    expect(formatActionLine(action({ kind: 'modify', side: 'store', relativePath: 'ch.md' }), false))
+      .toBe('modify   store  ch.md');
+  });
+
+  it('pads the columns so paths line up under each other', () => {
+    const lines = formatActionLines([
+      action({ kind: 'mkdir', side: 'disk', relativePath: 'lore', entryKind: 'folder' }),
+      action({ kind: 'conflict', side: null, relativePath: 'ch.md' }),
+    ], false);
+    const column = lines.map((l) => l.indexOf(l.trim().split(/\s+/)[2] || ''));
+    expect(new Set(column).size).toBe(1);
+  });
+
+  it('marks a folder with a trailing slash so it cannot be mistaken for a file', () => {
+    expect(displayPath(action({ entryKind: 'folder', relativePath: 'drafts' }))).toBe('drafts/');
+    expect(displayPath(action({ entryKind: 'file', relativePath: 'drafts' }))).toBe('drafts');
+  });
+
+  it('writes an em dash where no side changes', () => {
+    expect(formatActionLine(action({ kind: 'conflict', side: null }), false))
+      .toContain('conflict —');
+  });
+
+  it('appends the engine’s reason in parentheses', () => {
+    expect(formatActionLine(action({ kind: 'modify', side: 'store', reason: 'disk newer by 2h 14m' }), false))
+      .toContain('(disk newer by 2h 14m)');
+  });
+
+  it('shows the sha and size on a line that moved bytes', () => {
+    const line = formatActionLine(
+      action({ sha256: '3f9a' + '0'.repeat(60), sizeBytes: 421888 }), false
+    );
+    expect(line).toContain('sha 3f9a…');
+    expect(line).toContain('412.0 KB');
+  });
+
+  it('says nothing about bytes on a delete', () => {
+    expect(formatActionLine(action({ kind: 'delete', side: 'store', sha256: 'x'.repeat(64) }), false))
+      .not.toContain('sha');
+  });
+
+  it('leads with the error when an action failed', () => {
+    const line = formatActionLine(
+      action({ outcome: 'failed', error: 'EACCES', reason: 'store newer' }), false
+    );
+    expect(line).toContain('FAILED: EACCES');
+    expect(line).not.toContain('store newer');
+  });
+
+  it('emits no escape codes when colour is off', () => {
+    const lines = formatActionLines(
+      [action(), action({ kind: 'conflict', side: null }), action({ kind: 'delete', side: 'store' })],
+      false
+    );
+    expect(lines.join('\n')).not.toMatch(/\x1b\[/);
+  });
+
+  it('tints the line when colour is on', () => {
+    expect(formatActionLine(action({ kind: 'conflict', side: null }), true)).toMatch(/\x1b\[31m/);
+  });
+
+  it('caps the path column so one long path does not push every detail off screen', () => {
+    const lines = formatActionLines([
+      action({ relativePath: 'a/'.repeat(60) + 'deep.md', reason: 'why' }),
+      action({ relativePath: 'b.md', reason: 'why' }),
+    ], false);
+    expect(lines[1].indexOf('(why)')).toBeLessThan(80);
+  });
+});
+
+describe('the summary', () => {
+  it('names only the categories that actually happened', () => {
+    expect(formatSummary(summary({ created: 3, modified: 1 }), 800, false))
+      .toBe('3 created, 1 modified — 0.8 s');
+  });
+
+  it('says so plainly when there was nothing to do', () => {
+    expect(formatSummary(summary(), 120, false)).toBe('Already in step — 0.1 s');
+  });
+
+  it('speaks in the conditional under --dry-run', () => {
+    expect(formatSummary(summary({ created: 2 }), 300, true)).toBe('Would do: 2 created — 0.3 s');
+    expect(formatSummary(summary(), 300, true)).toBe('Nothing to do — 0.3 s');
+  });
+
+  it('pluralises conflicts', () => {
+    expect(formatSummary(summary({ conflicts: 1 }), 0, false)).toContain('1 conflict —');
+    expect(formatSummary(summary({ conflicts: 2 }), 0, false)).toContain('2 conflicts');
+  });
+
+  it('reports failures last, where they are hardest to miss', () => {
+    const line = formatSummary(summary({ created: 1, failed: 2 }), 0, false);
+    expect(line.indexOf('2 failed')).toBeGreaterThan(line.indexOf('1 created'));
+  });
+});
+
+describe('the exit code', () => {
+  it('is 0 when the run was clean', () => {
+    expect(exitCodeFor(summary({ created: 5, touched: 2 }))).toBe(0);
+  });
+
+  it('is 2 for an unresolved conflict', () => {
+    expect(exitCodeFor(summary({ conflicts: 1 }))).toBe(2);
+  });
+
+  it('is 1 when something failed outright, even alongside a conflict', () => {
+    expect(exitCodeFor(summary({ conflicts: 1, failed: 1 }))).toBe(1);
+  });
+});
+
+describe('byte formatting', () => {
+  it('scales through the units', () => {
+    expect(formatBytes(512)).toBe('512 B');
+    expect(formatBytes(2048)).toBe('2.0 KB');
+    expect(formatBytes(5 * 1024 * 1024)).toBe('5.0 MB');
+    expect(formatBytes(3 * 1024 ** 3)).toBe('3.00 GB');
+  });
+
+  it('says nothing for a size it was not given', () => {
+    expect(formatBytes(undefined)).toBe('');
+  });
+});