@slicedearth/whoisleuth-cli 1.32.0

package/cli/bulk.mjs

@@ -0,0 +1,133 @@
+import { Buffer } from 'node:buffer';
+import { abortable } from "../lib/abort.mjs";
+import { CliUsageError } from "./arguments.mjs";
+const MAX_BULK_INPUT_BYTES = 1024 * 1024;
+const MAX_FAST_BULK_QUERIES = 500;
+const MAX_DEEP_BULK_QUERIES = 50;
+async function readTextStreamBounded(stream, limit = MAX_BULK_INPUT_BYTES) {
+    if (!stream || stream.isTTY)
+        return '';
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limit)
+            throw new CliUsageError(`Bulk input is limited to ${limit} bytes.`);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function parseBulkQueries(text, { deep = false } = {}) {
+    if (typeof text !== 'string')
+        throw new CliUsageError('Bulk input must be newline-delimited text.');
+    if (Buffer.byteLength(text, 'utf8') > MAX_BULK_INPUT_BYTES) {
+        throw new CliUsageError(`Bulk input is limited to ${MAX_BULK_INPUT_BYTES} bytes.`);
+    }
+    const limit = deep ? MAX_DEEP_BULK_QUERIES : MAX_FAST_BULK_QUERIES;
+    const seen = new Set();
+    const queries = [];
+    let duplicates = 0;
+    const lines = text.replace(/^\uFEFF/, '').split(/\r?\n/);
+    for (const line of lines) {
+        const query = line.trim();
+        if (!query)
+            continue;
+        if (query.length > 1024 || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(query)) {
+            throw new CliUsageError('Bulk input contains an overlong query or unsupported control character.');
+        }
+        const key = query.toLowerCase();
+        if (seen.has(key)) {
+            duplicates++;
+            continue;
+        }
+        seen.add(key);
+        queries.push(query);
+        if (queries.length > limit) {
+            throw new CliUsageError(`${deep ? 'Deep' : 'Fast'} bulk mode is limited to ${limit} unique queries.`);
+        }
+    }
+    if (!queries.length)
+        throw new CliUsageError('Bulk input did not contain any queries.');
+    return { queries, duplicates, limit };
+}
+function boundedLookupError(error) {
+    const message = error && typeof error === 'object' && 'message' in error ? error.message : undefined;
+    return String(message || 'Lookup failed')
+        .replace(/[\x00-\x1f\x7f]+/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 300) || 'Lookup failed';
+}
+async function runBulkLookups(queries, options = {}) {
+    const classify = options.classifyQuery;
+    const executeLookup = options.runUnifiedLookup;
+    if (typeof classify !== 'function' || typeof executeLookup !== 'function') {
+        throw new TypeError('Bulk lookup dependencies are required.');
+    }
+    const classifyQuery = classify;
+    const runUnifiedLookup = executeLookup;
+    const concurrency = options.concurrency;
+    if (!Number.isSafeInteger(concurrency) || concurrency < 1 || concurrency > 8) {
+        throw new TypeError('Bulk concurrency is invalid.');
+    }
+    const results = new Array(queries.length);
+    for (const result of options.initialResults || []) {
+        if (!Number.isSafeInteger(result.index) || result.index < 0 || result.index >= queries.length
+            || queries[result.index] !== result.query || results[result.index]) {
+            throw new TypeError('Initial Bulk results are invalid.');
+        }
+        results[result.index] = result;
+    }
+    const lookupPromises = new Map();
+    let cursor = 0;
+    function notify(result) {
+        try {
+            options.onItemSettled?.(result);
+        }
+        catch {
+            // Presentation callbacks must never change collection results.
+        }
+    }
+    async function worker() {
+        while (true) {
+            options.signal?.throwIfAborted();
+            const index = cursor++;
+            if (index >= queries.length)
+                return;
+            if (results[index])
+                continue;
+            const query = queries[index];
+            if (query === undefined)
+                return;
+            try {
+                const classified = classifyQuery(query);
+                const lookupKey = `${classified.type}:${classified.value}`;
+                let lookupPromise = lookupPromises.get(lookupKey);
+                if (!lookupPromise) {
+                    lookupPromise = Promise.resolve().then(() => runUnifiedLookup(classified, {
+                        fast: options.deep !== true,
+                        compact: true,
+                        ...(options.signal ? { signal: options.signal } : {}),
+                        ...(options.dnsResolverServers?.length ? { dnsResolverServers: options.dnsResolverServers } : {}),
+                    }));
+                    lookupPromises.set(lookupKey, lookupPromise);
+                }
+                const result = await abortable(() => lookupPromise, options.signal);
+                const item = { index, query, ok: true, classified, result };
+                results[index] = item;
+                notify(item);
+            }
+            catch (error) {
+                if (options.signal?.aborted)
+                    throw options.signal.reason || new DOMException('Aborted', 'AbortError');
+                const item = { index, query, ok: false, error: boundedLookupError(error) };
+                results[index] = item;
+                notify(item);
+            }
+        }
+    }
+    await Promise.all(Array.from({ length: Math.min(concurrency, Math.max(1, queries.length - (options.initialResults?.length || 0))) }, () => worker()));
+    return results;
+}
+export { MAX_BULK_INPUT_BYTES, MAX_DEEP_BULK_QUERIES, MAX_FAST_BULK_QUERIES, parseBulkQueries, readTextStreamBounded, runBulkLookups, };

package/cli/compare.mjs

@@ -0,0 +1,238 @@
+import { CliUsageError } from "./arguments.mjs";
+import { isRdapRegistryAccessProfile, isWhoisRegistryAccessProfile, } from "./registry-access.mjs";
+import { MAX_SAVED_LOOKUP_INPUT_BYTES, MAX_SAVED_LOOKUP_STRING_LENGTH, SAVED_LOOKUP_SCHEMA, SAVED_LOOKUP_SCHEMA_VERSION, parseSavedLookupDocument, readSavedLookupInputBounded, } from "./saved-lookup.mjs";
+const MAX_COMPARE_INPUT_BYTES = MAX_SAVED_LOOKUP_INPUT_BYTES;
+// Covers the largest scalar accepted by the normalized WHOIS parser while
+// preventing a saved document from inflating the derived comparison output.
+const MAX_COMPARE_STRING_LENGTH = MAX_SAVED_LOOKUP_STRING_LENGTH;
+const MAX_COMPARE_LIST_ITEMS = 200;
+const MAX_COMPARE_EVENTS = 100;
+const MAX_COMPARE_REGISTRY_ACCESS_LIMITATION_LENGTH = MAX_COMPARE_STRING_LENGTH;
+const MAX_COMPARE_REGISTRY_ACCESS_SUFFIX_LENGTH = 63;
+const REGISTRAR_RDAP_STATUSES = new Set([
+    'success', 'partial', 'error', 'unsupported', 'not_found', 'skipped', 'disabled',
+]);
+const LOOKUP_SCHEMA = SAVED_LOOKUP_SCHEMA;
+const LOOKUP_SCHEMA_VERSION = SAVED_LOOKUP_SCHEMA_VERSION;
+async function readCompareInputBounded(stream, limit = MAX_COMPARE_INPUT_BYTES) {
+    return readSavedLookupInputBounded(stream, { limit, label: 'Comparison input' });
+}
+function objectOrNull(value) {
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+}
+function boundedSourceString(value, field) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        throw new CliUsageError(`${field} must be text when present.`);
+    if (value.length > MAX_COMPARE_STRING_LENGTH) {
+        throw new CliUsageError(`${field} exceeds the comparison value limit.`);
+    }
+    return value;
+}
+function boundedSourceList(value, field) {
+    if (value === null || value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new CliUsageError(`${field} must be an array when present.`);
+    if (value.length > MAX_COMPARE_LIST_ITEMS) {
+        throw new CliUsageError(`${field} exceeds the comparison item limit.`);
+    }
+    return value
+        .map((item, index) => boundedSourceString(item, `${field}[${index}]`))
+        .filter((item) => item !== null);
+}
+function projectRegistryAccessContext(diagnostics) {
+    const value = diagnostics.registryAccess;
+    if (value === null || value === undefined)
+        return null;
+    if (![5, 6, 7, 8].includes(Number(diagnostics.version)))
+        return null;
+    const context = objectOrNull(value);
+    if (!context)
+        throw new CliUsageError('diagnostics.registryAccess must be an object when present.');
+    if (context.authority !== 'context_only') {
+        throw new CliUsageError('diagnostics.registryAccess.authority is unsupported.');
+    }
+    if (context.coverageState !== 'access_documented') {
+        throw new CliUsageError('diagnostics.registryAccess.coverageState is unsupported.');
+    }
+    if (typeof context.suffix !== 'string'
+        || context.suffix.length > MAX_COMPARE_REGISTRY_ACCESS_SUFFIX_LENGTH
+        || !/^(?=.*[a-z])[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/.test(context.suffix)) {
+        throw new CliUsageError('diagnostics.registryAccess.suffix is invalid.');
+    }
+    if (!isWhoisRegistryAccessProfile(context.whoisAccessProfile)) {
+        throw new CliUsageError('diagnostics.registryAccess.whoisAccessProfile is unsupported.');
+    }
+    if (!isRdapRegistryAccessProfile(context.rdapAccessProfile)) {
+        throw new CliUsageError('diagnostics.registryAccess.rdapAccessProfile is unsupported.');
+    }
+    if (typeof context.limitation !== 'string' || !context.limitation.trim()
+        || context.limitation.length > MAX_COMPARE_REGISTRY_ACCESS_LIMITATION_LENGTH) {
+        throw new CliUsageError('diagnostics.registryAccess.limitation is invalid.');
+    }
+    return {
+        suffix: context.suffix,
+        coverageState: context.coverageState,
+        whoisAccessProfile: context.whoisAccessProfile,
+        rdapAccessProfile: context.rdapAccessProfile,
+        limitation: context.limitation,
+        authority: context.authority,
+    };
+}
+function projectLifecycle(value, prefix) {
+    if (value !== null && value !== undefined && !objectOrNull(value)) {
+        throw new CliUsageError(`${prefix} must be an object when present.`);
+    }
+    const lifecycle = objectOrNull(value) || {};
+    return {
+        createdDate: boundedSourceString(lifecycle.createdDate, `${prefix}.createdDate`),
+        createdDateIso: boundedSourceString(lifecycle.createdDateIso, `${prefix}.createdDateIso`),
+        expiryDate: boundedSourceString(lifecycle.expiryDate, `${prefix}.expiryDate`),
+        expiryDateIso: boundedSourceString(lifecycle.expiryDateIso, `${prefix}.expiryDateIso`),
+        updatedDate: boundedSourceString(lifecycle.updatedDate, `${prefix}.updatedDate`),
+        updatedDateIso: boundedSourceString(lifecycle.updatedDateIso, `${prefix}.updatedDateIso`),
+    };
+}
+function projectRdapSource(value, prefix = 'rdap.parsed') {
+    const source = objectOrNull(value) || {};
+    const registrar = objectOrNull(source.registrar);
+    const events = source.events === null || source.events === undefined ? [] : source.events;
+    if (!Array.isArray(events))
+        throw new CliUsageError(`${prefix}.events must be an array when present.`);
+    if (events.length > MAX_COMPARE_EVENTS) {
+        throw new CliUsageError(`${prefix}.events exceeds the comparison item limit.`);
+    }
+    return {
+        domain: boundedSourceString(source.domain, `${prefix}.domain`),
+        handle: boundedSourceString(source.handle, `${prefix}.handle`),
+        registrar: registrar ? {
+            name: boundedSourceString(registrar.name, `${prefix}.registrar.name`),
+            org: boundedSourceString(registrar.org, `${prefix}.registrar.org`),
+            handle: boundedSourceString(registrar.handle, `${prefix}.registrar.handle`),
+        } : boundedSourceString(source.registrar, `${prefix}.registrar`),
+        registrarIanaId: boundedSourceString(source.registrarIanaId, `${prefix}.registrarIanaId`),
+        lifecycle: projectLifecycle(source.lifecycle, `${prefix}.lifecycle`),
+        events: events.map((event, index) => {
+            const item = objectOrNull(event);
+            if (!item)
+                throw new CliUsageError(`${prefix}.events[${index}] must be an object.`);
+            return {
+                action: boundedSourceString(item.action, `${prefix}.events[${index}].action`),
+                date: boundedSourceString(item.date, `${prefix}.events[${index}].date`),
+            };
+        }),
+        dnssec: boundedSourceString(source.dnssec, `${prefix}.dnssec`),
+        statuses: boundedSourceList(source.statuses, `${prefix}.statuses`),
+        nameservers: boundedSourceList(source.nameservers, `${prefix}.nameservers`),
+    };
+}
+function projectCliRegistrarPublicationInput(document) {
+    const rdap = objectOrNull(document.rdap);
+    const registrar = objectOrNull(rdap?.registrarRdap);
+    const rdapDiagnostics = objectOrNull(document.diagnostics?.rdap);
+    const registrarDiagnostics = objectOrNull(rdapDiagnostics?.registrar);
+    if (!registrar && !registrarDiagnostics) {
+        return { represented: false, status: null, parsed: {} };
+    }
+    const sourceStatus = registrar?.status;
+    const diagnosticStatus = registrarDiagnostics?.status;
+    if (sourceStatus !== undefined && diagnosticStatus !== undefined && sourceStatus !== diagnosticStatus) {
+        throw new CliUsageError('Registrar RDAP source and diagnostic statuses do not match.');
+    }
+    const status = sourceStatus ?? diagnosticStatus;
+    if (typeof status !== 'string' || !REGISTRAR_RDAP_STATUSES.has(status)) {
+        throw new CliUsageError('rdap.registrarRdap.status is unsupported.');
+    }
+    if (registrar?.parsed !== null && registrar?.parsed !== undefined && !objectOrNull(registrar.parsed)) {
+        throw new CliUsageError('rdap.registrarRdap.parsed must be an object when present.');
+    }
+    const parsed = objectOrNull(registrar?.parsed);
+    if (status === 'success' && !parsed) {
+        throw new CliUsageError('Successful registrar RDAP input is missing normalized parsed data.');
+    }
+    const projected = projectRdapSource(parsed, 'rdap.registrarRdap.parsed');
+    delete projected.handle;
+    const projectedRegistrar = objectOrNull(projected.registrar);
+    if (projectedRegistrar)
+        delete projectedRegistrar.handle;
+    return {
+        represented: true,
+        status,
+        parsed: projected,
+    };
+}
+function projectWhoisSource(value) {
+    const source = objectOrNull(value) || {};
+    return {
+        domainName: boundedSourceString(source.domainName, 'whois.parsed.domainName'),
+        registryDomainId: boundedSourceString(source.registryDomainId, 'whois.parsed.registryDomainId'),
+        registrar: boundedSourceString(source.registrar, 'whois.parsed.registrar'),
+        registrarIanaId: boundedSourceString(source.registrarIanaId, 'whois.parsed.registrarIanaId'),
+        createdDate: boundedSourceString(source.createdDate, 'whois.parsed.createdDate'),
+        createdDateIso: boundedSourceString(source.createdDateIso, 'whois.parsed.createdDateIso'),
+        expiryDate: boundedSourceString(source.expiryDate, 'whois.parsed.expiryDate'),
+        expiryDateIso: boundedSourceString(source.expiryDateIso, 'whois.parsed.expiryDateIso'),
+        updatedDate: boundedSourceString(source.updatedDate, 'whois.parsed.updatedDate'),
+        updatedDateIso: boundedSourceString(source.updatedDateIso, 'whois.parsed.updatedDateIso'),
+        lifecycle: projectLifecycle(source.lifecycle, 'whois.parsed.lifecycle'),
+        dnssec: boundedSourceString(source.dnssec, 'whois.parsed.dnssec'),
+        statuses: boundedSourceList(source.statuses, 'whois.parsed.statuses'),
+        nameservers: boundedSourceList(source.nameservers, 'whois.parsed.nameservers'),
+    };
+}
+function parseCliLookupDocument(text) {
+    const document = parseSavedLookupDocument(text, { label: 'Comparison input' });
+    return projectCliLookupComparisonInput(document);
+}
+function projectCliLookupComparisonInput(document) {
+    const diagnostics = document.diagnostics;
+    const rdapStatus = document.diagnostics.rdap.status;
+    const whoisStatus = document.diagnostics.whois.status;
+    const rdapParsed = objectOrNull(document.rdap?.parsed);
+    const whoisParsed = objectOrNull(document.whois?.parsed);
+    const registrarPublication = projectCliRegistrarPublicationInput(document);
+    return {
+        query: document.query,
+        registrableDomain: document.registrableDomain,
+        lookupGeneratedAt: document.generatedAt,
+        lookupMode: document.mode,
+        rdapStatus,
+        whoisStatus,
+        rdapParsed: projectRdapSource(rdapParsed),
+        whoisParsed: projectWhoisSource(whoisParsed),
+        registrarRdapRepresented: registrarPublication.represented,
+        registrarRdapStatus: registrarPublication.status,
+        registrarRdapParsed: registrarPublication.parsed,
+        registryAccess: projectRegistryAccessContext(diagnostics),
+    };
+}
+function compareLookupDocument(input, compareRegistrySources, compareRdapPublications) {
+    if (typeof compareRegistrySources !== 'function') {
+        throw new TypeError('Registry comparison dependency is required.');
+    }
+    const comparison = compareRegistrySources(input.rdapParsed, input.whoisParsed, {
+        rdapStatus: input.rdapStatus,
+        whoisStatus: input.whoisStatus,
+    });
+    if (input.registrarRdapRepresented && typeof compareRdapPublications !== 'function') {
+        throw new TypeError('Registrar RDAP comparison dependency is required.');
+    }
+    const registrarPublicationComparison = input.registrarRdapRepresented
+        ? compareRdapPublications(input.rdapParsed, input.registrarRdapParsed, {
+            registryStatus: input.rdapStatus,
+            registrarStatus: input.registrarRdapStatus,
+        })
+        : null;
+    return {
+        query: input.query,
+        registrableDomain: input.registrableDomain,
+        lookupGeneratedAt: input.lookupGeneratedAt,
+        lookupMode: input.lookupMode,
+        ...comparison,
+        registrarPublicationComparison,
+        ...(input.registryAccess ? { registryAccess: input.registryAccess } : {}),
+    };
+}
+export { LOOKUP_SCHEMA, LOOKUP_SCHEMA_VERSION, MAX_COMPARE_EVENTS, MAX_COMPARE_INPUT_BYTES, MAX_COMPARE_LIST_ITEMS, MAX_COMPARE_REGISTRY_ACCESS_LIMITATION_LENGTH, MAX_COMPARE_REGISTRY_ACCESS_SUFFIX_LENGTH, MAX_COMPARE_STRING_LENGTH, compareLookupDocument, parseCliLookupDocument, projectCliLookupComparisonInput, readCompareInputBounded, };

package/cli/completion.mjs

@@ -0,0 +1,175 @@
+import { CLI_COMMANDS } from "./arguments.mjs";
+const COMMON_OPTIONS = Object.freeze(['--help', '--output', '--force']);
+const OPTIONS_BY_COMMAND = Object.freeze({
+    lookup: ['--json', '--markdown', '--html', '--fast', '--deep', '--summary', '--verbose', '--strict-exit', '--events', '--quiet', '--no-color'],
+    bulk: ['--json', '--jsonl', '--csv', '--domains', '--registered-only', '--inconclusive-only', '--fast', '--deep', '--concurrency', '--checkpoint', '--resume', '--events', '--quiet', '--no-color'],
+    'ct-search': ['--json', '--quiet', '--no-color'],
+    discover: ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--snapshot', '--json', '--jsonl', '--domains', '--quiet', '--no-color'],
+    'discover-scan': ['--tlds', '--preset', '--families', '--keyboard', '--dictionary', '--fast', '--deep', '--scan-limit', '--chunk-size', '--concurrency', '--resolver', '--allowlist', '--checkpoint', '--resume', '--observation-snapshot', '--registered-only', '--inconclusive-only', '--acquisition-only', '--suppressed-only', '--events', '--json', '--jsonl', '--csv', '--domains', '--quiet', '--no-color'],
+    posture: ['--selectors', '--retired-selectors', '--mail-profile', '--json', '--quiet', '--no-color'],
+    http: ['--json', '--quiet', '--no-color'],
+    tls: ['--json', '--quiet', '--no-color'],
+    'registry-support': ['--json', '--quiet', '--no-color'],
+    'risk-calibrate': ['--json', '--quiet', '--no-color'],
+    'verify-artifact': ['--passphrase-file', '--json', '--quiet', '--no-color'],
+    'inspect-archive': ['--passphrase-file', '--search', '--require-match', '--reveal', '--json', '--quiet', '--no-color'],
+    'sign-artifact': ['--private-key-file'],
+    'verify-signature': ['--public-key-file', '--json', '--quiet', '--no-color'],
+    'source-report': ['--json', '--quiet', '--no-color'],
+    compare: ['--json', '--quiet', '--no-color'],
+    'page-compare': ['--json', '--quiet', '--no-color'],
+    'mail-review': ['--json', '--quiet', '--no-color'],
+    diff: ['--json', '--quiet', '--no-color'],
+    export: ['--markdown', '--html', '--compact'],
+    completion: [],
+    doctor: ['--network', '--json', '--quiet', '--no-color'],
+    manual: [],
+});
+const COMMAND_DESCRIPTIONS = Object.freeze({
+    lookup: 'Collect one domain, IP, or ASN',
+    bulk: 'Run bounded multi-target collection',
+    'ct-search': 'Search certificate observations',
+    discover: 'Generate lookalike candidates offline',
+    'discover-scan': 'Collect a supervised candidate review queue',
+    posture: 'Review DNS and mail posture',
+    http: 'Inspect one homepage request',
+    tls: 'Inspect one TLS connection',
+    'registry-support': 'Explain local registry coverage',
+    'risk-calibrate': 'Replay reviewed Risk labels offline',
+    'verify-artifact': 'Validate an evidence artifact offline',
+    'inspect-archive': 'Inspect an archive locally',
+    'sign-artifact': 'Sign a reviewed artifact locally',
+    'verify-signature': 'Verify a signed evidence package',
+    'source-report': 'Build a target-free source report',
+    compare: 'Compare registry publications in one lookup',
+    'page-compare': 'Compare saved static page evidence',
+    'mail-review': 'Review saved passive mail evidence',
+    diff: 'Compare two saved domain lookups',
+    export: 'Convert a lookup to an evidence report',
+    completion: 'Print shell completion',
+    doctor: 'Check the local CLI runtime',
+    manual: 'Print the generated manual page',
+});
+const VALUE_OPTIONS = Object.freeze({
+    '--preset': ['common', 'impersonation', 'all'],
+    '--keyboard': ['qwerty', 'azerty', 'qwertz', 'all'],
+    '--mail-profile': ['standard', 'defensive-no-mail', 'parked'],
+    '--concurrency': ['1', '2', '3', '4', '5', '6', '7', '8'],
+});
+const FILE_OPTIONS = Object.freeze([
+    '--checkpoint',
+    '--allowlist',
+    '--dictionary',
+    '--output',
+    '--passphrase-file',
+    '--private-key-file',
+    '--public-key-file',
+    '--snapshot',
+    '--observation-snapshot',
+]);
+const TEXT_OPTIONS = Object.freeze([
+    '--families',
+    '--resolver',
+    '--retired-selectors',
+    '--search',
+    '--selectors',
+    '--tlds',
+]);
+function commandOptions(command) {
+    return [...COMMON_OPTIONS, ...(OPTIONS_BY_COMMAND[command] || [])].join(' ');
+}
+function bashCompletion() {
+    const cases = CLI_COMMANDS.map((command) => `    ${command}) options="${commandOptions(command)}" ;;`).join('\n');
+    const valueCases = Object.entries(VALUE_OPTIONS).map(([option, values]) => `    ${option}) COMPREPLY=( $(compgen -W "${values.join(' ')}" -- "\${current}") ); return ;;`).join('\n');
+    return `# WHOISleuth bash completion
+_whoisleuth_completion() {
+  local current previous command options
+  current="\${COMP_WORDS[COMP_CWORD]}"
+  previous="\${COMP_WORDS[COMP_CWORD-1]}"
+  command="\${COMP_WORDS[1]}"
+  if [[ \${COMP_CWORD} -eq 1 ]]; then
+    COMPREPLY=( $(compgen -W "${CLI_COMMANDS.join(' ')} --help --version" -- "\${current}") )
+    return
+  fi
+  if [[ "\${command}" == "completion" && \${COMP_CWORD} -eq 2 ]]; then
+    COMPREPLY=( $(compgen -W "bash zsh fish" -- "\${current}") )
+    return
+  fi
+  case "\${previous}" in
+${valueCases}
+    ${FILE_OPTIONS.join('|')}) COMPREPLY=( $(compgen -f -- "\${current}") ); return ;;
+    ${TEXT_OPTIONS.join('|')}) COMPREPLY=(); return ;;
+  esac
+  case "\${command}" in
+${cases}
+    *) options="--help" ;;
+  esac
+  COMPREPLY=( $(compgen -W "\${options}" -- "\${current}") )
+}
+complete -F _whoisleuth_completion whoisleuth
+`;
+}
+function zshCompletion() {
+    const commandEntries = CLI_COMMANDS.map((command) => `'${command}:${COMMAND_DESCRIPTIONS[command] || command}'`).join(' ');
+    const cases = CLI_COMMANDS.map((command) => `    ${command}) options=(${commandOptions(command)}) ;;`).join('\n');
+    const valueCases = Object.entries(VALUE_OPTIONS).map(([option, values]) => `    ${option}) compadd -- ${values.join(' ')}; return ;;`).join('\n');
+    return `#compdef whoisleuth
+_whoisleuth() {
+  local command previous
+  local -a options commands
+  commands=(${commandEntries})
+  if (( CURRENT == 2 )); then
+    _describe 'command' commands
+    return
+  fi
+  command="\${words[2]}"
+  previous="\${words[CURRENT-1]}"
+  if [[ "\${command}" == "completion" && CURRENT -eq 3 ]]; then
+    compadd -- bash zsh fish
+    return
+  fi
+  case "\${previous}" in
+${valueCases}
+    ${FILE_OPTIONS.join('|')}) _files; return ;;
+    ${TEXT_OPTIONS.join('|')}) _message 'value'; return ;;
+  esac
+  case "\${command}" in
+${cases}
+    *) options=(--help) ;;
+  esac
+  compadd -- \${options[@]}
+}
+if [[ "\${funcstack[1]}" == "_whoisleuth" ]]; then
+  _whoisleuth "\$@"
+else
+  compdef _whoisleuth whoisleuth
+fi
+`;
+}
+function fishCompletion() {
+    const commandLines = CLI_COMMANDS.map((command) => (`complete -c whoisleuth -n '__fish_use_subcommand' -a '${command}' -d '${COMMAND_DESCRIPTIONS[command] || command}'`));
+    const optionLines = Object.entries(OPTIONS_BY_COMMAND).flatMap(([command, options]) => ([...COMMON_OPTIONS, ...options].map((option) => {
+        const name = option.replace(/^--/u, '');
+        const fileValue = FILE_OPTIONS.includes(option);
+        const requiresValue = fileValue || [...Object.keys(VALUE_OPTIONS), ...TEXT_OPTIONS].includes(option);
+        return `complete -c whoisleuth -n '__fish_seen_subcommand_from ${command}' -l ${name}${requiresValue ? ' -r' : ''}${fileValue ? ' -F' : ''}`;
+    })));
+    const valueLines = Object.entries(VALUE_OPTIONS).flatMap(([option, values]) => (values.map((value) => `complete -c whoisleuth -n '__fish_prev_arg_in ${option}' -a '${value}'`)));
+    return `# WHOISleuth fish completion
+complete -c whoisleuth -f
+complete -c whoisleuth -n '__fish_use_subcommand' -l help
+complete -c whoisleuth -n '__fish_use_subcommand' -l version
+${commandLines.join('\n')}
+complete -c whoisleuth -n '__fish_seen_subcommand_from completion' -a 'bash zsh fish'
+${optionLines.join('\n')}
+${valueLines.join('\n')}
+`;
+}
+function buildShellCompletion(shell) {
+    if (shell === 'bash')
+        return bashCompletion();
+    if (shell === 'zsh')
+        return zshCompletion();
+    return fishCompletion();
+}
+export { buildShellCompletion, };

package/cli/csv.mjs

@@ -0,0 +1 @@
+export { serializeCsvCell as cliCsvCell } from "../lib/csv.mjs";

package/cli/discover.mjs

@@ -0,0 +1,50 @@
+import { Buffer } from 'node:buffer';
+import { CliUsageError } from "./arguments.mjs";
+const DEFAULT_DISCOVERY_TLDS = Object.freeze(['com', 'net', 'org']);
+const MAX_DISCOVERY_TLD_TEXT_LENGTH = 1024;
+const MAX_DISCOVERY_TLD_TOKENS_INSPECTED = 80;
+const MAX_DISCOVERY_DICTIONARY_BYTES = 4_096;
+async function readDiscoveryDictionaryBounded(stream, limit = MAX_DISCOVERY_DICTIONARY_BYTES) {
+    if (!stream || stream.isTTY)
+        return '';
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of stream) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        total += buffer.length;
+        if (total > limit)
+            throw new CliUsageError(`Discovery dictionary input is limited to ${limit} bytes.`);
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function normalizeDiscoveryTlds(raw, maximum) {
+    if (!Number.isSafeInteger(maximum) || maximum < 1) {
+        throw new TypeError('A valid discovery TLD limit is required.');
+    }
+    if (typeof raw !== 'string' || raw.length === 0 || raw.length > MAX_DISCOVERY_TLD_TEXT_LENGTH) {
+        throw new CliUsageError(`--tlds must contain at most ${MAX_DISCOVERY_TLD_TEXT_LENGTH} characters.`);
+    }
+    const tokens = raw.split(/[;,\s]+/).filter(Boolean);
+    if (!tokens.length)
+        throw new CliUsageError('--tlds did not contain any values.');
+    if (tokens.length > MAX_DISCOVERY_TLD_TOKENS_INSPECTED) {
+        throw new CliUsageError(`--tlds may inspect at most ${MAX_DISCOVERY_TLD_TOKENS_INSPECTED} values.`);
+    }
+    const values = [];
+    const seen = new Set();
+    for (const token of tokens) {
+        const value = token.toLowerCase().replace(/^\./, '');
+        if (!/^[a-z]{2,63}$/.test(value))
+            throw new CliUsageError(`Invalid TLD "${token}".`);
+        if (seen.has(value))
+            continue;
+        seen.add(value);
+        values.push(value);
+        if (values.length > maximum) {
+            throw new CliUsageError(`At most ${maximum} unique TLDs are supported.`);
+        }
+    }
+    return values;
+}
+export { DEFAULT_DISCOVERY_TLDS, MAX_DISCOVERY_DICTIONARY_BYTES, MAX_DISCOVERY_TLD_TEXT_LENGTH, MAX_DISCOVERY_TLD_TOKENS_INSPECTED, normalizeDiscoveryTlds, readDiscoveryDictionaryBounded, };

package/cli/discovery-command-runner.mjs

@@ -0,0 +1,36 @@
+import { generateDiscoveryCandidates } from "./discovery-workflow.mjs";
+import EXIT_CODES from "./exit-codes.mjs";
+import { buildCliDiscoverDocument, formatDiscoverDomainList, formatDiscoverJsonLines, formatJsonDocument, } from "./formatters/json.mjs";
+import { updateDiscoverySnapshot } from "./discovery-snapshot.mjs";
+import { formatTerminalDiscover } from "./formatters/terminal.mjs";
+async function runDiscoveryCommand(args, dependencies, context) {
+    const { dictionaryDigestSha256, generator, metadata, result } = await generateDiscoveryCandidates(args, dependencies, context);
+    const { seed } = metadata;
+    const snapshot = args.snapshotSource
+        ? await updateDiscoverySnapshot(args.snapshotSource, result.candidates.map((candidate) => candidate.domain), {
+            seed,
+            preset: args.preset,
+            keyboardLayout: args.keyboardLayout,
+            tlds: metadata.tlds,
+            mutationFamilies: metadata.mutationFamilies,
+            dictionaryDigestSha256,
+        }, metadata.generatedAt)
+        : null;
+    const baseDocument = buildCliDiscoverDocument(seed, result, metadata);
+    const document = snapshot ? { ...baseDocument, snapshot } : baseDocument;
+    if (!args.quiet) {
+        if (args.output === 'json')
+            context.writeStdout(formatJsonDocument(document));
+        else if (args.output === 'jsonl')
+            context.writeStdout(formatDiscoverJsonLines(result.candidates, metadata));
+        else if (args.output === 'domains')
+            context.writeStdout(formatDiscoverDomainList(result.candidates));
+        else
+            context.writeStdout(context.terminal(formatTerminalDiscover(document, generator.MUTATION_LABELS), args.color));
+    }
+    if (snapshot && ['domains', 'jsonl'].includes(args.output)) {
+        context.writeStderr(`Discovery snapshot: ${snapshot.baselineCreated ? 'baseline created' : `${snapshot.added.length} added, ${snapshot.removed.length} removed`} (${snapshot.currentCandidateCount} current).\n`);
+    }
+    return EXIT_CODES.SUCCESS;
+}
+export { runDiscoveryCommand };