@velaro/cli 1.4.53 → 1.4.55

package/lib/pdf/billing-document.test.js

@@ -0,0 +1,349 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs';
+import PDFDocument from 'pdfkit';
+import { computeTotalsLayout, generateBillingDocument, money, PAGE_MARGIN, pickPatternIndex, pickPatternFile, PATTERN_FILES, PATTERN_DIR } from './billing-document.js';
+
+const PRINTABLE_WIDTH = 612 - PAGE_MARGIN * 2; // US Letter minus both margins, same as the real generator
+
+function makeDoc() {
+  // No destination needed -- widthOfString() works on an in-memory doc with the standard fonts.
+  return new PDFDocument({ size: 'LETTER', margin: PAGE_MARGIN });
+}
+
+// ── computeTotalsLayout: the printable-width assertion ──────────────────────────────────────
+
+test('computeTotalsLayout fits a normal invoice totals block within the real printable width', () => {
+  const doc = makeDoc();
+  const rows = [
+    { label: 'Invoice Amount', value: money(735739700) },
+    { label: 'Amount Paid', value: money(0) },
+    { label: 'Balance Due', value: money(735739700) },
+  ];
+  const layout = computeTotalsLayout(doc, rows, PRINTABLE_WIDTH);
+  assert.ok(layout.totalWidth <= PRINTABLE_WIDTH, `layout width ${layout.totalWidth} must not exceed ${PRINTABLE_WIDTH}`);
+});
+
+test('computeTotalsLayout shrinks the value font to fit a huge amount in a constrained width before giving up', () => {
+  const doc = makeDoc();
+  // A synthetic, deliberately huge amount ($999,999,999,999.99) -- larger than any real invoice
+  // this system would generate, exactly the kind of case that overflowed the hand-built fpdf2
+  // receipt this feature replaces. Paired with a narrower-than-usual printable width (e.g. a
+  // tighter layout variant) so the default 13pt value font genuinely does not fit and the
+  // fallback ladder has to do real work, rather than trivially fitting on a full 512pt page.
+  const hugeValue = money(99999999999999);
+  const rows = [
+    { label: 'Invoice Amount', value: hugeValue },
+    { label: 'Amount Paid', value: money(0) },
+    { label: 'Balance Due', value: hugeValue },
+  ];
+  const constrainedWidth = 190;
+  const layout = computeTotalsLayout(doc, rows, constrainedWidth);
+  assert.ok(layout.totalWidth <= constrainedWidth, `layout width ${layout.totalWidth} must not exceed ${constrainedWidth}`);
+  // It should have had to shrink below the default largest size to make this fit.
+  assert.ok(layout.valueFontSize < 13, `expected the value font to shrink below 13pt, got ${layout.valueFontSize}`);
+});
+
+test('computeTotalsLayout: a huge amount at the real page width still fits without needing to shrink (sanity check)', () => {
+  const doc = makeDoc();
+  const hugeValue = money(99999999999999);
+  const rows = [
+    { label: 'Invoice Amount', value: hugeValue },
+    { label: 'Balance Due', value: hugeValue },
+  ];
+  const layout = computeTotalsLayout(doc, rows, PRINTABLE_WIDTH);
+  assert.ok(layout.totalWidth <= PRINTABLE_WIDTH);
+});
+
+test('computeTotalsLayout throws a clear error instead of silently overflowing when nothing fits', () => {
+  const doc = makeDoc();
+  const hugeValue = money(99999999999999);
+  const rows = [
+    { label: 'A Label So Absurdly Long It Cannot Possibly Share A Line With Anything Else', value: hugeValue },
+  ];
+  // A printable width far narrower than any real page could produce -- guarantees every font
+  // size in the fallback ladder still overflows, so the assertion MUST throw rather than return
+  // a layout wider than the page.
+  assert.throws(
+    () => computeTotalsLayout(doc, rows, 40),
+    /would overflow the printable width/,
+  );
+});
+
+test('computeTotalsLayout never returns a layout wider than printableWidth, across a range of widths', () => {
+  const doc = makeDoc();
+  const rows = [
+    { label: 'Invoice Amount', value: money(123456789) },
+    { label: 'Balance Due', value: money(123456789) },
+  ];
+  for (const printableWidth of [512, 300, 200, 150]) {
+    try {
+      const layout = computeTotalsLayout(doc, rows, printableWidth);
+      assert.ok(layout.totalWidth <= printableWidth);
+    } catch (err) {
+      // Throwing is an acceptable outcome (never silently overflowing is the actual contract) --
+      // but if it doesn't throw, the returned layout must genuinely fit.
+      assert.match(err.message, /would overflow the printable width/);
+    }
+  }
+});
+
+// ── Background pattern selection: deterministic, full-set rotation ──────────────────────────
+
+test('pickPatternIndex/pickPatternFile is deterministic — the same invoice number always picks the same pattern', () => {
+  const seeds = ['INV-50042', 'INV-50999', 4242, 'INV-00001'];
+  for (const seed of seeds) {
+    const first = pickPatternIndex(seed);
+    for (let i = 0; i < 10; i++) {
+      assert.equal(pickPatternIndex(seed), first, `pickPatternIndex(${seed}) must be stable across repeated calls`);
+    }
+    assert.equal(pickPatternFile(seed), PATTERN_FILES[first]);
+  }
+});
+
+test('pickPatternIndex covers the full pattern set (not always index 0) across a range of invoice numbers', () => {
+  const seen = new Set();
+  for (let i = 1; i <= 500; i++) {
+    seen.add(pickPatternIndex(`INV-${50000 + i}`));
+  }
+  assert.equal(seen.size, PATTERN_FILES.length, `expected all ${PATTERN_FILES.length} patterns to be hit across 500 invoice numbers, saw indices: ${[...seen].sort().join(',')}`);
+});
+
+test('pickPatternIndex always returns a valid index into PATTERN_FILES', () => {
+  const seeds = ['INV-50042', 0, 1, -5, '', null, undefined, 99999999999999, 'a very long invoice number formatted string INV-000123456'];
+  for (const seed of seeds) {
+    const idx = pickPatternIndex(seed);
+    assert.ok(Number.isInteger(idx) && idx >= 0 && idx < PATTERN_FILES.length, `pickPatternIndex(${seed}) returned out-of-range index ${idx}`);
+  }
+});
+
+test('every file in PATTERN_FILES exists on disk and is a valid, non-trivial PNG', () => {
+  for (const filename of PATTERN_FILES) {
+    const filePath = path.join(PATTERN_DIR, filename);
+    assert.ok(fs.existsSync(filePath), `missing pattern asset: ${filePath}`);
+    const buf = fs.readFileSync(filePath);
+    assert.ok(buf.length > 1000, `${filename} is suspiciously small (${buf.length} bytes) to be a real pattern image`);
+    assert.equal(buf.toString('ascii', 1, 4), 'PNG', `${filename} does not look like a valid PNG`);
+  }
+});
+
+test('two invoices that resolve to different pattern indices produce PDFs (sanity: generation succeeds regardless of which pattern is picked)', async () => {
+  // Pick two invoice numbers known to land on different pattern indices so this test actually
+  // exercises pattern variety, not just re-running the same one twice.
+  let seedA = null, seedB = null;
+  for (let i = 1; i <= 1000 && (seedA === null || seedB === null); i++) {
+    const seed = `INV-${60000 + i}`;
+    if (seedA === null) { seedA = seed; continue; }
+    if (pickPatternIndex(seed) !== pickPatternIndex(seedA)) seedB = seed;
+  }
+  assert.ok(seedA && seedB, 'test setup: could not find two invoice numbers with different pattern indices');
+  assert.notEqual(pickPatternIndex(seedA), pickPatternIndex(seedB));
+
+  for (const invoiceNumberFormatted of [seedA, seedB]) {
+    const invoice = baseInvoice({ invoiceNumberFormatted });
+    const balance = { appliedCents: 0, totalCents: invoice.totalCents, remainingCents: invoice.totalCents, paidInFull: false };
+    const tmpFile = path.join(os.tmpdir(), `billing-doc-test-pattern-${invoiceNumberFormatted}-${Date.now()}.pdf`);
+    const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance, type: 'invoice', outPath: tmpFile });
+    assert.ok(buffer.length > 0);
+    assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-');
+    fs.unlinkSync(tmpFile);
+  }
+});
+
+// ── generateBillingDocument: receipt guard + real PDF output ────────────────────────────────
+
+function baseInvoice(overrides = {}) {
+  return {
+    id: 4242,
+    subscriptionId: 7,
+    invoiceNumber: 50042,
+    invoiceNumberFormatted: 'INV-50042',
+    poNumber: 'PO-TEST-001',
+    customerName: 'Test Customer LLC',
+    invoiceDate: '2026-09-01T00:00:00Z',
+    dueDate: '2026-10-01T00:00:00Z',
+    servicePeriodStart: '2026-09-01T00:00:00Z',
+    servicePeriodEnd: '2027-08-31T00:00:00Z',
+    totalCents: 735739700,
+    status: 'sent',
+    lineItems: [
+      { description: 'Annual subscription — Professional tier', amountCents: 735739700, sortOrder: 0 },
+    ],
+    ...overrides,
+  };
+}
+
+const baseSubscription = { id: 7, customerName: 'Test Customer LLC', netTermsDays: 30, billingCadence: 'annual', paymentMethod: 'ach' };
+
+test('generateBillingDocument refuses --type receipt for an invoice that is not paid in full', async () => {
+  const invoice = baseInvoice();
+  const unpaidBalance = { appliedCents: 0, totalCents: invoice.totalCents, remainingCents: invoice.totalCents, paidInFull: false };
+
+  await assert.rejects(
+    () => generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance: unpaidBalance, type: 'receipt' }),
+    /not recorded as paid in full/,
+  );
+});
+
+test('generateBillingDocument refuses --type receipt when balance data is missing entirely', async () => {
+  const invoice = baseInvoice();
+  await assert.rejects(
+    () => generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance: undefined, type: 'receipt' }),
+    /not recorded as paid in full/,
+  );
+});
+
+test('generateBillingDocument refuses --type receipt for a PARTIALLY paid invoice (paidInFull=false even with some payment)', async () => {
+  const invoice = baseInvoice();
+  const partialBalance = { appliedCents: 100000, totalCents: invoice.totalCents, remainingCents: invoice.totalCents - 100000, paidInFull: false };
+  const payments = [{ id: 1, amountCents: 100000, method: 'ach', paymentDate: '2026-09-05T00:00:00Z', status: 'applied' }];
+
+  await assert.rejects(
+    () => generateBillingDocument({ invoice, subscription: baseSubscription, payments, balance: partialBalance, type: 'receipt' }),
+    /not recorded as paid in full/,
+  );
+});
+
+test('generateBillingDocument produces a real, non-empty PDF for --type invoice', async () => {
+  const invoice = baseInvoice();
+  const balance = { appliedCents: 0, totalCents: invoice.totalCents, remainingCents: invoice.totalCents, paidInFull: false };
+
+  const tmpFile = path.join(os.tmpdir(), `billing-doc-test-invoice-${Date.now()}.pdf`);
+  const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance, type: 'invoice', outPath: tmpFile });
+
+  assert.ok(buffer.length > 0, 'PDF buffer must not be empty');
+  assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-', 'buffer must start with a valid PDF header');
+
+  const fileBytes = fs.readFileSync(tmpFile);
+  assert.ok(fileBytes.length > 0);
+  assert.equal(fileBytes.subarray(0, 5).toString('latin1'), '%PDF-');
+  fs.unlinkSync(tmpFile);
+});
+
+test('generateBillingDocument produces a real, non-empty PDF for --type receipt on a paid-in-full invoice', async () => {
+  const invoice = baseInvoice();
+  const balance = { appliedCents: invoice.totalCents, totalCents: invoice.totalCents, remainingCents: 0, paidInFull: true };
+  const payments = [
+    { id: 1, amountCents: invoice.totalCents, method: 'ach', paymentDate: '2026-09-10T00:00:00Z', status: 'applied' },
+  ];
+
+  const tmpFile = path.join(os.tmpdir(), `billing-doc-test-receipt-${Date.now()}.pdf`);
+  const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments, balance, type: 'receipt', outPath: tmpFile });
+
+  assert.ok(buffer.length > 0, 'PDF buffer must not be empty');
+  assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-', 'buffer must start with a valid PDF header');
+
+  const fileBytes = fs.readFileSync(tmpFile);
+  assert.ok(fileBytes.length > 0);
+  assert.equal(fileBytes.subarray(0, 5).toString('latin1'), '%PDF-');
+  fs.unlinkSync(tmpFile);
+});
+
+test('generateBillingDocument handles a synthetic huge invoice amount without overflowing (invoice type)', async () => {
+  const invoice = baseInvoice({ totalCents: 99999999999999, lineItems: [{ description: 'Synthetic overflow test line item', amountCents: 99999999999999, sortOrder: 0 }] });
+  const balance = { appliedCents: 0, totalCents: invoice.totalCents, remainingCents: invoice.totalCents, paidInFull: false };
+
+  const tmpFile = path.join(os.tmpdir(), `billing-doc-test-overflow-${Date.now()}.pdf`);
+  const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance, type: 'invoice', outPath: tmpFile });
+
+  assert.ok(buffer.length > 0);
+  assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-');
+  fs.unlinkSync(tmpFile);
+});
+
+test('generateBillingDocument rejects an unknown --type value', async () => {
+  const invoice = baseInvoice();
+  await assert.rejects(
+    () => generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance: null, type: 'statement' }),
+    /type must be "invoice", "receipt", or "quote"/,
+  );
+});
+
+// NOTE: pdfkit's content streams are FlateDecode-compressed with indirect (object-referenced)
+// /Length values, so a raw regex/inflate-based text search over the buffer is not reliable here
+// (tried and confirmed brittle -- it fails to find even a real invoice's own INV- number, a false
+// negative). The identifier-leak behavior below (title/ref text, no due-date framing) was verified
+// by generating a real quote PDF from a live invoice record and visually inspecting the rendered
+// page -- see the PR description. These tests assert only what's reliably checkable from outside
+// the PDF's compressed byte stream: that quote generation succeeds and produces a structurally
+// valid, non-empty PDF, same bar as the existing invoice/receipt tests above.
+test('generateBillingDocument accepts --type quote and produces a valid, non-empty PDF', async () => {
+  const invoice = baseInvoice();
+  const tmpFile = path.join(os.tmpdir(), `billing-doc-test-quote-${Date.now()}.pdf`);
+  const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance: null, type: 'quote', outPath: tmpFile });
+
+  assert.ok(buffer.length > 0);
+  assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-');
+  const fileBytes = fs.readFileSync(tmpFile);
+  assert.equal(fileBytes.subarray(0, 5).toString('latin1'), '%PDF-');
+  fs.unlinkSync(tmpFile);
+});
+
+// ── Regressions found in review: long customer name / many line items ───────────────────────
+
+test('a long customer name is bounded to wrap before the dates column instead of overflowing into it', () => {
+  // Regression check for the fix in generateBillingDocument: the customer-name text call must
+  // pass an explicit `width` bounded by where the dates column starts, not the full page width.
+  // This asserts the actual math used for that width leaves real room short of the printable
+  // right edge (i.e. it is bounded to roughly half the page, not left unbounded).
+  const doc = makeDoc();
+  const leftEdge = PAGE_MARGIN;
+  const rightEdge = 612 - PAGE_MARGIN;
+  const printableWidth = rightEdge - leftEdge;
+  const datesX = leftEdge + printableWidth / 2;
+  const nameColWidth = datesX - (leftEdge + 12) - 10;
+
+  assert.ok(nameColWidth < printableWidth, 'the bounded name column must be narrower than the full printable width');
+  assert.ok(nameColWidth > 0);
+
+  // A realistic long legal entity name should wrap (need more than one line) at this width and
+  // font, rather than being drawn on a single line wide enough to run past datesX.
+  doc.font('Helvetica-Bold').fontSize(11);
+  const longName = 'Consolidated International Holdings and Logistics Partners, LLC';
+  const singleLineWidth = doc.widthOfString(longName);
+  assert.ok(singleLineWidth > nameColWidth, 'test name must actually be wide enough to require wrapping at this column width for this assertion to be meaningful');
+  const wrappedHeight = doc.heightOfString(longName, { width: nameColWidth });
+  const singleLineHeight = doc.heightOfString('X', { width: nameColWidth });
+  assert.ok(wrappedHeight > singleLineHeight, 'a long name must wrap to multiple lines within the bounded width instead of overflowing on one line');
+});
+
+test('generateBillingDocument does not throw for a very long customer name and produces a valid PDF', async () => {
+  const invoice = baseInvoice({ customerName: 'Consolidated International Holdings and Logistics Partners, LLC (Formerly Trading As Northbridge Freight Solutions)' });
+  const balance = { appliedCents: 0, totalCents: invoice.totalCents, remainingCents: invoice.totalCents, paidInFull: false };
+
+  const tmpFile = path.join(os.tmpdir(), `billing-doc-test-longname-${Date.now()}.pdf`);
+  const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance, type: 'invoice', outPath: tmpFile });
+
+  assert.ok(buffer.length > 0);
+  assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-');
+  fs.unlinkSync(tmpFile);
+});
+
+test('generateBillingDocument paginates instead of overflowing when an invoice has many line items', async () => {
+  // Regression check for the pagination bug found in review: a heavily itemized invoice used to
+  // push the totals/status/footer past the bottom of a single page with nothing to catch it.
+  const manyLineItems = Array.from({ length: 60 }, (_, i) => ({
+    description: `Adjustment line item number ${i + 1} — service usage overage for period`,
+    amountCents: 12345 + i,
+  }));
+  const totalCents = manyLineItems.reduce((sum, li) => sum + li.amountCents, 0);
+  const invoice = baseInvoice({ lineItems: manyLineItems, totalCents });
+  const balance = { appliedCents: 0, totalCents, remainingCents: totalCents, paidInFull: false };
+
+  const tmpFile = path.join(os.tmpdir(), `billing-doc-test-manylines-${Date.now()}.pdf`);
+  const buffer = await generateBillingDocument({ invoice, subscription: baseSubscription, payments: [], balance, type: 'invoice', outPath: tmpFile });
+
+  assert.ok(buffer.length > 0);
+  assert.equal(buffer.subarray(0, 5).toString('latin1'), '%PDF-');
+
+  // Count real page objects (/Type /Page, not /Type /Pages) in the raw PDF body -- pdfkit does
+  // not compress these dictionary objects, so a plain substring count is a reliable enough proxy
+  // for "did this actually paginate" without pulling in a full PDF parser as a dependency.
+  const raw = buffer.toString('latin1');
+  const pageObjectCount = (raw.match(/\/Type\s*\/Page(?!s)/g) || []).length;
+  assert.ok(pageObjectCount > 1, `expected more than one page for a 60-line-item invoice, found ${pageObjectCount}`);
+
+  fs.unlinkSync(tmpFile);
+});

package/lib/site-flags.js

@@ -0,0 +1,71 @@
+// Pure logic for `velaro subscription set-flags` (no I/O), so it can be unit tested.
+// Only Enable* boolean entitlement flags on ONE site's Subscriptions row may be flipped.
+// Billing, package, price, limit (Max*/Retention) and identity fields are never allowed.
+
+export const FLAG_PATTERN = /^enable[A-Za-z0-9]+$/i;
+
+// Belt and braces: even if an Enable* column ever gets added that touches money/plan state,
+// these substrings keep it off the allowlist until someone deliberately edits this file.
+export const DENY_SUBSTRINGS = ['billing', 'stripe', 'package', 'price', 'payment', 'plan', 'trial', 'invoice', 'quickbooks', 'expir', 'autoupgrade'];
+
+export function findKey(row, name) {
+  const want = String(name).toLowerCase();
+  return Object.keys(row || {}).find(k => k.toLowerCase() === want);
+}
+
+export function parseFlagList(v) {
+  if (v === undefined || v === null || v === true || v === '') return [];
+  return String(v).split(',').map(s => s.trim()).filter(Boolean);
+}
+
+// Returns { ok, errors, changes: [{flag, key, before, after}], body }
+export function planChanges(row, enable, disable) {
+  const errors = [];
+  const all = [...enable, ...disable];
+  if (all.length === 0) errors.push('Nothing to do: pass --enable and/or --disable.');
+  const lower = all.map(f => f.toLowerCase());
+  const dup = all.filter((f, i) => lower.indexOf(f.toLowerCase()) !== i);
+  if (dup.length) errors.push(`Flag(s) listed more than once (or in both --enable and --disable): ${[...new Set(dup)].join(', ')}`);
+
+  const changes = [];
+  const body = {};
+  for (const [flags, after] of [[enable, true], [disable, false]]) {
+    for (const flag of flags) {
+      if (!FLAG_PATTERN.test(flag)) { errors.push(`${flag}: not allowed. Only boolean Enable* flags may be set (no billing, package or limit fields).`); continue; }
+      const low = flag.toLowerCase();
+      const bad = DENY_SUBSTRINGS.find(s => low.includes(s));
+      if (bad) { errors.push(`${flag}: denied (matches billing/package guard "${bad}").`); continue; }
+      const key = findKey(row, flag);
+      if (!key) { errors.push(`${flag}: no such column on this site's subscription row.`); continue; }
+      if (typeof row[key] !== 'boolean') { errors.push(`${flag}: current value is not a boolean (${JSON.stringify(row[key])}); refusing.`); continue; }
+      changes.push({ flag, key, before: row[key], after });
+      body[flag] = after;
+    }
+  }
+  return { ok: errors.length === 0, errors, changes, body };
+}
+
+// Every field whose value differs between two rows.
+export function diffRows(before, after) {
+  const out = [];
+  const keys = new Set([...Object.keys(before || {}), ...Object.keys(after || {})]);
+  for (const k of keys) {
+    const b = before?.[k], a = after?.[k];
+    if (JSON.stringify(b) !== JSON.stringify(a)) out.push({ key: k, before: b, after: a });
+  }
+  return out.sort((x, y) => x.key.localeCompare(y.key));
+}
+
+// Fields the server legitimately rewrites on any update.
+const AUDIT_FIELDS = ['updatedat', 'modifiedat', 'lastmodified', 'updatedby', 'modifiedby', 'rowversion', 'timestamp'];
+
+export function verifyOnlyIntendedChanged(before, after, changes) {
+  const intended = new Set(changes.map(c => c.key.toLowerCase()));
+  const diff = diffRows(before, after);
+  const unexpected = diff.filter(d => !intended.has(d.key.toLowerCase()) && !AUDIT_FIELDS.includes(d.key.toLowerCase()));
+  const missing = changes.filter(c => {
+    const k = findKey(after, c.key);
+    return !k || after[k] !== c.after;
+  });
+  return { ok: unexpected.length === 0 && missing.length === 0, unexpected, missing, diff };
+}

package/lib/site-flags.test.js

@@ -0,0 +1,57 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { planChanges, parseFlagList, diffRows, verifyOnlyIntendedChanged } from './site-flags.js';
+
+const row = { siteId: 20365, enableAgentDashboard: false, enableCustomDashboards: false, enableAI: true, maxCustomDashboards: 3, billingEnabled: true, packageId: 4 };
+
+test('parseFlagList splits, trims, drops empties', () => {
+  assert.deepEqual(parseFlagList(' a, b ,,c'), ['a', 'b', 'c']);
+  assert.deepEqual(parseFlagList(undefined), []);
+});
+
+test('plans an enable/disable and builds the request body', () => {
+  const p = planChanges(row, ['EnableAgentDashboard', 'enableCustomDashboards'], ['EnableAI']);
+  assert.equal(p.ok, true);
+  assert.deepEqual(p.body, { EnableAgentDashboard: true, enableCustomDashboards: true, EnableAI: false });
+  assert.deepEqual(p.changes.map(c => [c.key, c.before, c.after]),
+    [['enableAgentDashboard', false, true], ['enableCustomDashboards', false, true], ['enableAI', true, false]]);
+});
+
+test('refuses limit, billing, package and identity fields', () => {
+  for (const f of ['MaxCustomDashboards', 'BillingEnabled', 'PackageId', 'SiteId']) {
+    assert.equal(planChanges(row, [f], []).ok, false, f);
+  }
+});
+
+test('refuses Enable* flags matching the billing/package deny guard', () => {
+  const r = { ...row, enableStripePayments: false, enablePackageAutoUpgrade: false };
+  assert.equal(planChanges(r, ['EnableStripePayments'], []).ok, false);
+  assert.equal(planChanges(r, ['EnablePackageAutoUpgrade'], []).ok, false);
+});
+
+test('refuses unknown column, non-boolean column, duplicates and empty request', () => {
+  assert.equal(planChanges(row, ['EnableNope'], []).ok, false);
+  assert.equal(planChanges({ ...row, enableWeird: 5 }, ['EnableWeird'], []).ok, false);
+  assert.equal(planChanges(row, ['EnableAI'], ['EnableAI']).ok, false);
+  assert.equal(planChanges(row, [], []).ok, false);
+});
+
+test('diffRows lists only changed keys', () => {
+  assert.deepEqual(diffRows({ a: 1, b: 2 }, { a: 1, b: 3 }), [{ key: 'b', before: 2, after: 3 }]);
+});
+
+test('verify passes when only intended flags (plus audit fields) changed', () => {
+  const p = planChanges(row, ['EnableAgentDashboard'], []);
+  const after = { ...row, enableAgentDashboard: true, updatedAt: 'x' };
+  assert.equal(verifyOnlyIntendedChanged(row, after, p.changes).ok, true);
+});
+
+test('verify fails on an unexpected changed field or an unapplied flag', () => {
+  const p = planChanges(row, ['EnableAgentDashboard'], []);
+  const v1 = verifyOnlyIntendedChanged(row, { ...row, enableAgentDashboard: true, maxCustomDashboards: 9 }, p.changes);
+  assert.equal(v1.ok, false);
+  assert.equal(v1.unexpected[0].key, 'maxCustomDashboards');
+  const v2 = verifyOnlyIntendedChanged(row, { ...row }, p.changes);
+  assert.equal(v2.ok, false);
+  assert.equal(v2.missing.length, 1);
+});

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@velaro/cli",
-  "version": "1.4.53",
+  "version": "1.4.55",
   "description": "Velaro Workspace v20 — command-line interface for managing bots, knowledge base ingestion, MCP API keys, search indexes, and ops health.",
   "type": "module",
   "bin": {
     "velaro": "bin/velaro.js"
   },
   "scripts": {
-    "postinstall": "node scripts/postinstall.js"
+    "postinstall": "node scripts/postinstall.js",
+    "test": "node --test lib/*.test.js"
   },
   "engines": {
     "node": ">=18.0.0"
@@ -16,6 +17,7 @@
     "@azure/identity": "^4.4.1",
     "@azure/keyvault-secrets": "^4.9.0",
     "mssql": "^12.7.0",
+    "pdfkit": "^0.15.2",
     "yargs": "^17.7.2"
   },
   "optionalDependencies": {
@@ -29,6 +31,7 @@
   "files": [
     "bin/",
     "lib/",
-    "scripts/"
+    "scripts/",
+    "assets/"
   ]
 }