@slicedearth/whoisleuth-cli 1.32.2 → 1.34.0

package/cli/doctor.mjs

@@ -1,4 +1,4 @@
-import { resolvePublicAddresses } from "../lib/safe-fetch.mjs";
+import { resolvePublicAddresses, safeFetch } from "../lib/safe-fetch.mjs";
 import { withTimeout } from "../lib/abort.mjs";
 import { whoisQuery } from "../lib/whois-transport.mjs";
 const DOCTOR_SCHEMA = 'whoisleuth.cli.doctor';
@@ -6,6 +6,7 @@ const DOCTOR_VERSION = 1;
 const MINIMUM_NODE_MAJOR = 24;
 const NETWORK_HOST = 'whois.iana.org';
 const NETWORK_QUERY = 'example.com';
+const NETWORK_HTTPS_URL = 'https://data.iana.org/rdap/dns.json';
 const NETWORK_TIMEOUT_MS = 6_000;
 const MAX_DOCTOR_DETAIL_LENGTH = 180;
 function boundedDetail(value, fallback) {
@@ -57,58 +58,92 @@ async function buildDoctorReport(options) {
             id: 'network',
             label: 'Network checks',
             state: 'skipped',
-            detail: 'Not requested. Run doctor --network to test bounded public DNS and WHOIS connectivity.',
+            detail: 'Not requested. Run doctor --network to test bounded public DNS, HTTPS, and WHOIS connectivity.',
         }));
     }
     else {
         const resolve = options.resolveAddresses || resolvePublicAddresses;
+        const fetchHttps = options.fetchHttps || safeFetch;
         const query = options.queryWhois || whoisQuery;
         const networkTimeoutMs = Number.isSafeInteger(options.networkTimeoutMs)
             && Number(options.networkTimeoutMs) >= 1
             && Number(options.networkTimeoutMs) <= NETWORK_TIMEOUT_MS
             ? Number(options.networkTimeoutMs)
             : NETWORK_TIMEOUT_MS;
-        try {
-            const addresses = await withTimeout(() => resolve(NETWORK_HOST), networkTimeoutMs, `Public DNS check timed out after ${networkTimeoutMs} ms.`);
-            checks.push(Object.freeze({
-                id: 'public_dns',
-                label: 'Public DNS',
-                state: addresses.length > 0 ? 'pass' : 'partial',
-                detail: addresses.length > 0
-                    ? `${addresses.length} public address${addresses.length === 1 ? '' : 'es'} validated; addresses were not retained.`
-                    : 'The fixed diagnostic host returned no validated public addresses.',
-            }));
-        }
-        catch (error) {
-            checks.push(Object.freeze({
-                id: 'public_dns',
-                label: 'Public DNS',
-                state: 'partial',
-                detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'Public DNS check failed.'),
-            }));
-        }
-        try {
-            const response = await query(NETWORK_HOST, NETWORK_QUERY, {
-                timeoutMs: Math.max(1, networkTimeoutMs - 1_000),
-                totalDeadlineMs: networkTimeoutMs,
-            });
-            checks.push(Object.freeze({
-                id: 'whois_transport',
-                label: 'WHOIS transport',
-                state: response.trim() ? 'pass' : 'partial',
-                detail: response.trim()
-                    ? 'A bounded port 43 response was received; response content was not retained.'
-                    : 'The fixed diagnostic query returned an empty response.',
-            }));
-        }
-        catch (error) {
-            checks.push(Object.freeze({
-                id: 'whois_transport',
-                label: 'WHOIS transport',
-                state: 'partial',
-                detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'WHOIS transport check failed.'),
-            }));
-        }
+        const networkChecks = await Promise.all([
+            (async () => {
+                try {
+                    const addresses = await withTimeout(() => resolve(NETWORK_HOST), networkTimeoutMs, `Public DNS check timed out after ${networkTimeoutMs} ms.`);
+                    return Object.freeze({
+                        id: 'public_dns',
+                        label: 'Public DNS',
+                        state: addresses.length > 0 ? 'pass' : 'partial',
+                        detail: addresses.length > 0
+                            ? `${addresses.length} public address${addresses.length === 1 ? '' : 'es'} validated; addresses were not retained.`
+                            : 'The fixed diagnostic host returned no validated public addresses.',
+                    });
+                }
+                catch (error) {
+                    return Object.freeze({
+                        id: 'public_dns',
+                        label: 'Public DNS',
+                        state: 'partial',
+                        detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'Public DNS check failed.'),
+                    });
+                }
+            })(),
+            (async () => {
+                try {
+                    const response = await withTimeout(() => fetchHttps(NETWORK_HTTPS_URL, {
+                        headers: { accept: 'application/json' },
+                        signal: AbortSignal.timeout(networkTimeoutMs),
+                    }), networkTimeoutMs, `HTTPS check timed out after ${networkTimeoutMs} ms.`);
+                    const status = response.status;
+                    await response.body?.cancel().catch(() => { });
+                    return Object.freeze({
+                        id: 'https_transport',
+                        label: 'HTTPS transport',
+                        state: response.ok ? 'pass' : 'partial',
+                        detail: response.ok
+                            ? `The fixed IANA RDAP bootstrap endpoint returned HTTP ${status}; response content was not retained.`
+                            : `The fixed IANA RDAP bootstrap endpoint returned HTTP ${status}.`,
+                    });
+                }
+                catch (error) {
+                    return Object.freeze({
+                        id: 'https_transport',
+                        label: 'HTTPS transport',
+                        state: 'partial',
+                        detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'HTTPS transport check failed.'),
+                    });
+                }
+            })(),
+            (async () => {
+                try {
+                    const response = await withTimeout(() => query(NETWORK_HOST, NETWORK_QUERY, {
+                        timeoutMs: Math.max(1, networkTimeoutMs - 1_000),
+                        totalDeadlineMs: networkTimeoutMs,
+                    }), networkTimeoutMs, `WHOIS check timed out after ${networkTimeoutMs} ms.`);
+                    return Object.freeze({
+                        id: 'whois_transport',
+                        label: 'WHOIS transport',
+                        state: response.trim() ? 'pass' : 'partial',
+                        detail: response.trim()
+                            ? 'A bounded port 43 response was received; response content was not retained.'
+                            : 'The fixed diagnostic query returned an empty response.',
+                    });
+                }
+                catch (error) {
+                    return Object.freeze({
+                        id: 'whois_transport',
+                        label: 'WHOIS transport',
+                        state: 'partial',
+                        detail: boundedDetail(error && typeof error === 'object' && 'message' in error ? error.message : error, 'WHOIS transport check failed.'),
+                    });
+                }
+            })(),
+        ]);
+        checks.push(...networkChecks);
     }
     const state = checks.some((check) => check.state === 'partial') ? 'partial' : 'pass';
     return Object.freeze({

package/cli/formatters/html.mjs

@@ -28,7 +28,7 @@ function renderRegistrarComparison(comparison) {
 }
 function formatLookupEvidenceHtml(document) {
     const report = buildLookupEvidenceReport(document);
-    const title = `Lookup evidence report — ${report.title}`;
+    const title = `Lookup evidence report: ${report.title}`;
     return `<!doctype html>
 <html lang="en">
 <head>

package/cli/formatters/terminal.mjs

@@ -284,12 +284,12 @@ function formatTerminalRegistrySupport(document) {
 function formatTerminalBulk(items, metadata) {
     const lines = items.map((item) => {
         if (!item.ok)
-            return `! ${safeTerminalValue(item.query)} — ${safeTerminalValue(item.error, 'Lookup failed')}`;
+            return `! ${safeTerminalValue(item.query)}: ${safeTerminalValue(item.error, 'Lookup failed')}`;
         const result = terminalRecord(item.result);
         const availability = terminalRecord(result.availability);
         const state = titleCase(availability.state);
         const confidence = titleCase(availability.confidence);
-        return `✓ ${safeTerminalValue(item.query)} — ${state} (${confidence} confidence)`;
+        return `✓ ${safeTerminalValue(item.query)}: ${state} (${confidence} confidence)`;
     });
     const succeeded = items.filter((item) => item.ok).length;
     lines.push('');
@@ -367,7 +367,7 @@ function formatTerminalDiscover(document, mutationLabels = {}) {
         const unicodeDetail = unicodeDomain && unicodeDomain !== candidateDomain
             ? ` [Unicode: ${safeTerminalValue(unicodeDomain)}]`
             : '';
-        lines.push(`${safeTerminalValue(candidateDomain)}${unicodeDetail} — ${labels.join(', ') || 'Generated variant'}`);
+        lines.push(`${safeTerminalValue(candidateDomain)}${unicodeDetail}: ${labels.join(', ') || 'Generated variant'}`);
     }
     if (!visible.length)
         lines.push('No candidates were generated.');
@@ -396,7 +396,7 @@ function formatTerminalPosture(document) {
     ];
     for (const value of checks) {
         const item = terminalRecord(value);
-        lines.push(`[${safeTerminalValue(item.status, 'info').toUpperCase()}] ${safeTerminalValue(item.label)} — ${safeTerminalValue(item.summary)}`);
+        lines.push(`[${safeTerminalValue(item.status, 'info').toUpperCase()}] ${safeTerminalValue(item.label)}: ${safeTerminalValue(item.summary)}`);
         if (item.detail)
             lines.push(`  Detail  ${safeTerminalValue(item.detail)}`);
         if (item.remediation)
@@ -444,7 +444,7 @@ function formatTerminalHttp(document) {
     for (const value of attempts) {
         const attempt = terminalRecord(value);
         const outcome = attempt.httpStatus ? `HTTP ${attempt.httpStatus}` : attempt.error || attempt.outcome;
-        lines.push(`Attempt        ${safeTerminalValue(attempt.url)} — ${safeTerminalValue(outcome)}`);
+        lines.push(`Attempt        ${safeTerminalValue(attempt.url)}: ${safeTerminalValue(outcome)}`);
     }
     for (const limitation of limitations)
         lines.push(`Limitation     ${safeTerminalValue(limitation)}`);
@@ -535,7 +535,7 @@ function formatTerminalTls(document) {
         lines.push(`Error          ${safeTerminalValue(diagnostics.error)}`);
     for (const value of findings) {
         const finding = terminalRecord(value);
-        lines.push(`Finding        ${safeTerminalValue(finding.label)} — ${safeTerminalValue(finding.detail)}`);
+        lines.push(`Finding        ${safeTerminalValue(finding.label)}: ${safeTerminalValue(finding.detail)}`);
     }
     for (const limitation of limitations)
         lines.push(`Limitation     ${safeTerminalValue(limitation)}`);

package/cli/lookup-command-runner.mjs

@@ -8,6 +8,7 @@ import { formatLookupEvidenceHtml } from "./formatters/html.mjs";
 import { buildCliLookupDocument, formatJsonDocument } from "./formatters/json.mjs";
 import { formatLookupEvidenceMarkdown } from "./formatters/markdown.mjs";
 import { formatTerminalLookup } from "./formatters/terminal.mjs";
+import { buildCliLookupPlan, formatCliLookupPlan } from "./lookup-plan.mjs";
 import { createCliProgressEvents } from "./progress-events.mjs";
 import { lookupStrictExitFindings } from "./strict-exit.mjs";
 async function runLookupCommand(args, dependencies, context) {
@@ -33,6 +34,13 @@ async function runLookupCommand(args, dependencies, context) {
     if ((args.output === 'markdown' || args.output === 'html') && classified.type !== 'domain') {
         throw new CliUsageError('Markdown and HTML reports support domain lookups only.');
     }
+    if (args.plan) {
+        const plan = buildCliLookupPlan(query, classified, args.deep);
+        context.writeStdout(args.output === 'json'
+            ? formatJsonDocument(plan)
+            : context.terminal(formatCliLookupPlan(plan), args.color));
+        return EXIT_CODES.SUCCESS;
+    }
     const indicator = context.beginProgress(args.deep
         ? 'Collecting deep Lookup evidence'
         : 'Collecting registration evidence');

package/cli/lookup-diff.mjs

@@ -119,13 +119,20 @@ function lookupComparisonInput(document) {
         sourceCoverage: sourceCoverage(document, availability),
     };
 }
-function buildCliLookupDiff(leftText, rightText, generatedAt = new Date().toISOString()) {
+function buildCliLookupDiff(leftText, rightText, generatedAt = new Date().toISOString(), options = {}) {
     const left = parseSavedLookupDocument(leftText, { label: 'Left lookup input' });
     const right = parseSavedLookupDocument(rightText, { label: 'Right lookup input' });
-    if (left.registrableDomain === right.registrableDomain) {
+    const domainMode = options.domainMode ?? 'different';
+    if (domainMode === 'different' && left.registrableDomain === right.registrableDomain) {
         throw new CliUsageError('Lookup diff requires documents for two different domains.');
     }
-    const comparison = buildBulkDomainComparison(lookupComparisonInput(left), lookupComparisonInput(right), null);
+    if (domainMode === 'same' && left.registrableDomain !== right.registrableDomain) {
+        throw new CliUsageError('Lookup history requires observations for the same domain.');
+    }
+    const comparison = buildBulkDomainComparison(lookupComparisonInput(left), lookupComparisonInput(right), domainMode === 'same' ? right.generatedAt : null, {
+        allowSameDomain: domainMode === 'same',
+        ...(domainMode === 'same' ? { now: Date.parse(right.generatedAt) } : {}),
+    });
     if (!comparison)
         throw new CliUsageError('Lookup documents could not be compared.');
     return {
@@ -136,9 +143,13 @@ function buildCliLookupDiff(leftText, rightText, generatedAt = new Date().toISOS
         right: { domain: right.registrableDomain, generatedAt: right.generatedAt, mode: right.mode },
         comparison,
         limitations: [
-            'This command compares bounded observations already present in two saved Lookup documents and makes no network request.',
+            domainMode === 'same'
+                ? 'This comparison uses bounded observations already present in two saved Lookup documents for the same domain and makes no network request.'
+                : 'This command compares bounded observations already present in two saved Lookup documents and makes no network request.',
             'A missing value remains distinct from unavailable collection and from an observed difference.',
-            'Shared infrastructure or matching values do not establish common ownership, control, intent, safety, or maliciousness.',
+            domainMode === 'same'
+                ? 'An observed difference can reflect a domain change or changed collection conditions and does not by itself establish current state, intent, safety, or maliciousness.'
+                : 'Shared infrastructure or matching values do not establish common ownership, control, intent, safety, or maliciousness.',
         ],
     };
 }

package/cli/lookup-plan.mjs

@@ -0,0 +1,99 @@
+export const CLI_LOOKUP_PLAN_SCHEMA = 'whoisleuth.cli.lookup-plan';
+export const CLI_LOOKUP_PLAN_VERSION = 1;
+const RDAP = Object.freeze({
+    source: 'rdap',
+    purpose: 'Collect authoritative registration or allocation evidence where supported.',
+    disclosure: 'The normalized target is sent to the applicable RDAP bootstrap and service endpoints.',
+    conditional: false,
+});
+const WHOIS = Object.freeze({
+    source: 'whois',
+    purpose: 'Collect separately attributed registry and referral publications.',
+    disclosure: 'The normalized target is sent over bounded TCP connections to applicable WHOIS services.',
+    conditional: false,
+});
+const FAST_DOMAIN_EVIDENCE = Object.freeze({
+    source: 'domain_evidence',
+    purpose: 'Derive a registration state from RDAP, with bounded DNS delegation fallback when needed.',
+    disclosure: 'DNS resolvers may receive the registrable domain when RDAP does not provide a usable record.',
+    conditional: true,
+});
+const DEEP_DOMAIN_EVIDENCE = Object.freeze({
+    source: 'domain_evidence',
+    purpose: 'Collect bounded DNS, HTTP, TLS, page-identity, technology, and security-posture evidence.',
+    disclosure: 'DNS resolvers and the target website infrastructure receive the hostname through bounded probes.',
+    conditional: false,
+});
+const REGISTRAR_RDAP = Object.freeze({
+    source: 'registrar_rdap',
+    purpose: 'Collect a separately attributed registrar RDAP publication when registry evidence advertises one.',
+    disclosure: 'The registrable domain is sent to the advertised registrar RDAP service.',
+    conditional: true,
+});
+const NETWORK_CONTEXT = Object.freeze({
+    source: 'network_context',
+    purpose: 'Add allocation and routing context for public addresses observed during domain collection.',
+    disclosure: 'Observed public addresses may be sent to applicable RDAP services.',
+    conditional: true,
+});
+const REVERSE_DNS = Object.freeze({
+    source: 'reverse_dns',
+    purpose: 'Collect operator-published reverse-DNS context for a public IP address.',
+    disclosure: 'A DNS resolver receives the reverse lookup for the normalized IP address.',
+    conditional: false,
+});
+function plannedSources(classified, deep) {
+    if (!deep) {
+        return Object.freeze(classified.type === 'domain' ? [RDAP, FAST_DOMAIN_EVIDENCE] : [RDAP]);
+    }
+    if (classified.type === 'domain') {
+        return Object.freeze([RDAP, WHOIS, DEEP_DOMAIN_EVIDENCE, REGISTRAR_RDAP, NETWORK_CONTEXT]);
+    }
+    if (classified.type === 'ipv4' || classified.type === 'ipv6') {
+        return Object.freeze([RDAP, WHOIS, REVERSE_DNS]);
+    }
+    return Object.freeze([RDAP, WHOIS]);
+}
+function buildCliLookupPlan(query, classified, deep) {
+    return Object.freeze({
+        schema: CLI_LOOKUP_PLAN_SCHEMA,
+        version: CLI_LOOKUP_PLAN_VERSION,
+        mode: deep ? 'deep' : 'fast',
+        target: Object.freeze({
+            query,
+            type: classified.type,
+            normalized: classified.value,
+            ...(classified.inputHostname ? { inputHostname: classified.inputHostname } : {}),
+            ...(classified.registrableDomain ? { registrableDomain: classified.registrableDomain } : {}),
+        }),
+        planning: Object.freeze({
+            networkRequestsMade: false,
+            collectionRequiresNetwork: true,
+            sources: plannedSources(classified, deep),
+        }),
+        limitations: Object.freeze([
+            'This is a local preflight. It does not test source availability, feature configuration, cache state, redirects, referrals, or the exact number of requests a completed lookup may require.',
+            'Conditional sources may be skipped when prerequisite evidence is absent, unsupported, disabled, or unavailable.',
+        ]),
+    });
+}
+function formatCliLookupPlan(plan) {
+    const lines = [
+        'WHOISleuth lookup preflight',
+        `Target: ${plan.target.normalized}`,
+        `Type: ${plan.target.type}`,
+        `Mode: ${plan.mode}`,
+        'Network requests made: no',
+        '',
+        'Planned collection:',
+    ];
+    for (const source of plan.planning.sources) {
+        lines.push(`  ${source.source}${source.conditional ? ' (conditional)' : ''}`);
+        lines.push(`    ${source.purpose}`);
+        lines.push(`    Disclosure: ${source.disclosure}`);
+    }
+    for (const limitation of plan.limitations)
+        lines.push('', `Limitation: ${limitation}`);
+    return `${lines.join('\n')}\n`;
+}
+export { buildCliLookupPlan, formatCliLookupPlan };

package/cli/lookup-timeline.mjs

@@ -0,0 +1,123 @@
+import { Buffer } from 'node:buffer';
+import { CliUsageError } from "./errors.mjs";
+import { buildCliLookupDiff } from "./lookup-diff.mjs";
+import { parseSavedLookupDocument } from "./saved-lookup.mjs";
+export const CLI_LOOKUP_TIMELINE_SCHEMA = 'whoisleuth.cli.lookup-timeline';
+export const CLI_LOOKUP_TIMELINE_VERSION = 1;
+export const MAX_LOOKUP_TIMELINE_OBSERVATIONS = 20;
+export const MAX_LOOKUP_TIMELINE_INPUT_BYTES = 32 * 1024 * 1024;
+function buildCliLookupTimeline(inputs, generatedAt = new Date().toISOString()) {
+    if (inputs.length < 2 || inputs.length > MAX_LOOKUP_TIMELINE_OBSERVATIONS) {
+        throw new CliUsageError(`Lookup timeline requires from 2 to ${MAX_LOOKUP_TIMELINE_OBSERVATIONS} saved Lookup documents.`);
+    }
+    const totalBytes = inputs.reduce((total, input) => total + Buffer.byteLength(input, 'utf8'), 0);
+    if (totalBytes > MAX_LOOKUP_TIMELINE_INPUT_BYTES) {
+        throw new CliUsageError(`Lookup timeline input is limited to ${MAX_LOOKUP_TIMELINE_INPUT_BYTES} bytes in total.`);
+    }
+    const normalized = inputs.map((input, index) => ({
+        input,
+        document: parseSavedLookupDocument(input, { label: `Lookup timeline input ${index + 1}` }),
+        inputIndex: index,
+    }));
+    const domain = normalized[0]?.document.registrableDomain;
+    if (!domain || normalized.some((item) => item.document.registrableDomain !== domain)) {
+        throw new CliUsageError('Lookup timeline requires observations for exactly one domain.');
+    }
+    normalized.sort((left, right) => (Date.parse(left.document.generatedAt) - Date.parse(right.document.generatedAt)
+        || left.inputIndex - right.inputIndex));
+    for (let index = 1; index < normalized.length; index++) {
+        if (normalized[index - 1]?.document.generatedAt === normalized[index]?.document.generatedAt) {
+            throw new CliUsageError('Lookup timeline observation times must be unique.');
+        }
+    }
+    const observations = normalized.map((item, index) => ({
+        index,
+        generatedAt: item.document.generatedAt,
+        mode: item.document.mode,
+    }));
+    const transitions = normalized.slice(1).map((current, index) => {
+        const previous = normalized[index];
+        if (!previous)
+            throw new TypeError('Lookup timeline ordering failed.');
+        const diff = buildCliLookupDiff(previous.input, current.input, generatedAt, { domainMode: 'same' });
+        return {
+            index,
+            fromObservation: index,
+            toObservation: index + 1,
+            comparison: diff.comparison,
+        };
+    });
+    const fields = {
+        conflicting: 0,
+        different: 0,
+        equal: 0,
+        missing: 0,
+        notRecorded: 0,
+        unavailable: 0,
+    };
+    let transitionsWithObservedChanges = 0;
+    for (const transition of transitions) {
+        const counts = transition.comparison.counts;
+        fields.conflicting += counts.conflicting;
+        fields.different += counts.different;
+        fields.equal += counts.equal;
+        fields.missing += counts.missing;
+        fields.notRecorded += counts.not_recorded;
+        fields.unavailable += counts.unavailable;
+        if (counts.conflicting + counts.different > 0)
+            transitionsWithObservedChanges += 1;
+    }
+    return {
+        schema: CLI_LOOKUP_TIMELINE_SCHEMA,
+        version: CLI_LOOKUP_TIMELINE_VERSION,
+        generatedAt,
+        domain,
+        observations,
+        transitions,
+        summary: {
+            observationCount: observations.length,
+            transitionCount: transitions.length,
+            transitionsWithObservedChanges,
+            fields,
+        },
+        privacy: {
+            filenamesRetained: 0,
+            rawRegistryPayloadsCopied: 0,
+        },
+        limitations: [
+            'The timeline compares only bounded normalized fields already present in the selected saved Lookup documents and makes no network request.',
+            'Input filenames and raw registry payloads are not copied into the timeline output.',
+            'Missing, unavailable, and not-recorded evidence remain separate from an observed difference.',
+            'A difference can reflect a domain change or changed collection conditions and does not by itself establish current state, ownership, intent, safety, or maliciousness.',
+        ],
+    };
+}
+function formatCliLookupTimeline(document) {
+    const output = [
+        'Same-domain observation timeline',
+        `Domain             ${document.domain}`,
+        `Observations       ${document.summary.observationCount}`,
+        `First observed     ${document.observations[0]?.generatedAt || 'Unavailable'}`,
+        `Last observed      ${document.observations.at(-1)?.generatedAt || 'Unavailable'}`,
+        `Changed transitions ${document.summary.transitionsWithObservedChanges}`,
+    ];
+    for (const transition of document.transitions) {
+        const from = document.observations[transition.fromObservation];
+        const to = document.observations[transition.toObservation];
+        const counts = transition.comparison.counts;
+        const changedRows = transition.comparison.rows.filter((row) => (row.state === 'conflicting' || row.state === 'different' || row.state === 'missing'));
+        output.push('', `${from?.generatedAt || 'Unavailable'} to ${to?.generatedAt || 'Unavailable'}`, `  Observed changes ${counts.conflicting + counts.different}`, `  One-sided fields ${counts.missing}`, `  Unavailable      ${counts.unavailable + counts.not_recorded}`);
+        if (!changedRows.length)
+            output.push('  No observed field changes in comparable evidence.');
+        for (const row of changedRows.slice(0, 10)) {
+            output.push(`  ${row.label} [${row.state.replaceAll('_', ' ')}]: ${row.left} -> ${row.right}`);
+        }
+        if (changedRows.length > 10)
+            output.push(`  ${changedRows.length - 10} additional changed fields omitted; use --json for the complete bounded comparison.`);
+    }
+    output.push('', 'Limitations:');
+    for (const limitation of document.limitations)
+        output.push(`  - ${limitation}`);
+    return `${output.join('\n')}\n`;
+}
+export { buildCliLookupTimeline, formatCliLookupTimeline };

package/cli/manual.mjs

@@ -7,7 +7,8 @@ function roffText(value) {
 function buildCliManual(options) {
     const commands = options.commands.map((command) => {
         const detail = options.details[command];
-        return `.SS ${roffText(command)}\n${roffText(detail.description)}\n.PP\n.B ${roffText(options.usage[command])}\n.PP\nExample: ${roffText(detail.example)}\n.PP\nBoundary: ${roffText(detail.boundary)}`;
+        const collection = options.collections[command];
+        return `.SS ${roffText(command)}\n${roffText(detail.description)}\n.PP\n.B ${roffText(options.usage[command])}\n.PP\nExample: ${roffText(detail.example)}\n.PP\nCollection: ${roffText(collection.mode)}. ${roffText(collection.scope)}\n.PP\nBoundary: ${roffText(detail.boundary)}`;
     }).join('\n');
     return `.TH WHOISLEUTH 1 "" "WHOISleuth ${roffText(options.version)}" "User Commands"
 .SH NAME