@slicedearth/whoisleuth-cli 1.47.4 → 2.0.0

package/cli/arguments.mjs

@@ -1,71 +1,22 @@
 import { parseInspectArchiveArguments, parseSignArtifactArguments, parseVerifySignatureArguments, } from "./evidence-command-arguments.mjs";
-import { CliUsageError } from "./errors.mjs";
-import { INVESTIGATION_PLAN_RECIPES, } from "./investigation-plan.mjs";
+import { CliUsageError, hasUnsafeCliText } from "./errors.mjs";
+import { INVESTIGATION_PLAN_RECIPES, RUNNABLE_INVESTIGATION_PLAN_RECIPES, } from "./investigation-plan.mjs";
 import { parseCliFailPolicies } from "./fail-policy.mjs";
+import { isDirectLookupTarget } from "../lib/classify.mjs";
+import { CLI_COMMANDS, cliMetaActionForInvocation, isCliCommand, } from "./command-reference.mjs";
 const MAX_CLI_ARGUMENTS = 32;
 const MAX_CLI_ARGUMENT_LENGTH = 1024;
-const CLI_COMMANDS = [
-    'completion',
-    'doctor',
-    'commands',
-    'manual',
-    'manifest',
-    'map-observations',
-    'oam-export',
-    'lookup',
-    'bulk',
-    'ct-search',
-    'ct-intake',
-    'discover',
-    'discover-scan',
-    'posture',
-    'http',
-    'tls',
-    'dnssec-validate',
-    'mail-transport',
-    'registry-support',
-    'registry-doctor',
-    'registry-cohort',
-    'registry-scaffold',
-    'risk-calibrate',
-    'lookalike-calibrate',
-    'verify-artifact',
-    'interchange-report',
-    'inspect-archive',
-    'sign-artifact',
-    'verify-signature',
-    'source-report',
-    'compare',
-    'page-compare',
-    'mail-review',
-    'review-evidence',
-    'brief',
-    'case-pack',
-    'domain-control',
-    'monitor-once',
-    'assurance',
-    'change-packet',
-    'sharing-review',
-    'workflow-plan',
-    'workflow-run',
-    'diff',
-    'reconcile',
-    'timeline',
-    'export',
-];
 function boundedArgument(value) {
-    if (typeof value !== 'string' || value.length > MAX_CLI_ARGUMENT_LENGTH || /[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/.test(value)) {
+    if (typeof value !== 'string' || value.length > MAX_CLI_ARGUMENT_LENGTH || hasUnsafeCliText(value)) {
         throw new CliUsageError('Arguments must be bounded text without control characters.');
     }
     return value;
 }
-function isCliCommand(value) {
-    return CLI_COMMANDS.includes(value);
-}
 function extractFileOutputArguments(argv) {
     const retained = [];
     let destination = null;
     let force = false;
+    let palette = null;
     for (let index = 0; index < argv.length; index++) {
         const argument = argv[index];
         if (argument === undefined)
@@ -83,19 +34,32 @@ function extractFileOutputArguments(argv) {
                 throw new CliUsageError('--force may be supplied only once.');
             force = true;
         }
+        else if (index > 0 && argument === '--palette') {
+            if (palette !== null)
+                throw new CliUsageError('--palette may be supplied only once.');
+            const value = argv[++index];
+            if (value !== 'auto' && value !== 'light' && value !== 'dark') {
+                throw new CliUsageError('--palette requires auto, light, or dark.');
+            }
+            palette = value;
+        }
         else {
             retained.push(argument);
         }
     }
     if (force && destination === null)
         throw new CliUsageError('--force requires --output.');
-    return { argv: retained, destination, force };
+    return { argv: retained, destination, force, palette };
 }
 function parseCliArguments(rawArgv) {
     if (!Array.isArray(rawArgv) || rawArgv.length > MAX_CLI_ARGUMENTS) {
         throw new CliUsageError(`At most ${MAX_CLI_ARGUMENTS} command arguments are supported.`);
     }
-    const extracted = extractFileOutputArguments(rawArgv.map(boundedArgument));
+    const boundedArguments = rawArgv.map(boundedArgument);
+    const metaAction = cliMetaActionForInvocation(boundedArguments);
+    if (metaAction)
+        return parseCliArgumentsCore(boundedArguments);
+    const extracted = extractFileOutputArguments(boundedArguments);
     const parsed = parseCliArgumentsCore(extracted.argv);
     if ('quiet' in parsed && parsed.quiet && extracted.destination !== null) {
         throw new CliUsageError('--quiet cannot be combined with --output.');
@@ -103,124 +67,53 @@ function parseCliArguments(rawArgv) {
     if ('events' in parsed && parsed.events && extracted.destination !== null) {
         throw new CliUsageError('--events cannot be combined with --output because completion must describe the final output delivery.');
     }
-    return extracted.destination === null
-        ? parsed
-        : { ...parsed, destination: extracted.destination, ...(extracted.force ? { force: true } : {}) };
+    if ('browse' in parsed && parsed.browse === true && extracted.destination !== null) {
+        throw new CliUsageError('--browse cannot be combined with --output because it requires an interactive terminal.');
+    }
+    return {
+        ...parsed,
+        ...(extracted.destination !== null ? { destination: extracted.destination } : {}),
+        ...(extracted.force ? { force: true } : {}),
+        ...(extracted.palette ? { palette: extracted.palette } : {}),
+    };
 }
 function parseCliArgumentsCore(argv) {
     if (!argv.length)
         return { action: 'help' };
     const firstArgument = argv[0] ?? '';
-    const helpRequested = argv.includes('--help') || argv.includes('-h');
-    if (helpRequested) {
+    const metaAction = cliMetaActionForInvocation(argv);
+    if (metaAction?.id === 'help') {
         if (argv.length === 1)
             return { action: 'help' };
-        if (argv.length === 2 && isCliCommand(firstArgument))
-            return { action: 'help', command: firstArgument };
+        if (argv.length === 2 && (isCliCommand(firstArgument) || isDirectLookupTarget(firstArgument))) {
+            return { action: 'help', command: isCliCommand(firstArgument) ? firstArgument : 'lookup' };
+        }
         throw new CliUsageError('Help accepts only an optional command name.');
     }
-    if (firstArgument === '--version' || firstArgument === '-V') {
+    if (metaAction?.id === 'version') {
         if (argv.length !== 1)
             throw new CliUsageError('--version does not accept other arguments.');
         return { action: 'version' };
     }
-    const command = firstArgument;
-    if (!isCliCommand(command)) {
-        const displayedCommand = command.length > 80 ? `${command.slice(0, 79)}…` : command;
+    let command;
+    let directLookup = false;
+    if (isCliCommand(firstArgument))
+        command = firstArgument;
+    else if (isDirectLookupTarget(firstArgument)) {
+        command = 'lookup';
+        directLookup = true;
+    }
+    else {
+        const displayedCommand = firstArgument.length > 80 ? `${firstArgument.slice(0, 79)}…` : firstArgument;
         throw new CliUsageError(`Unknown command "${displayedCommand}". Run "whoisleuth commands" to list supported commands.`);
     }
-    if (command === 'bulk')
-        return parseBulkArguments(argv.slice(1));
-    if (command === 'completion')
-        return parseCompletionArguments(argv.slice(1));
-    if (command === 'doctor')
-        return parseDoctorArguments(argv.slice(1));
-    if (command === 'commands')
-        return parseCommandsArguments(argv.slice(1));
-    if (command === 'manual')
-        return parseManualArguments(argv.slice(1));
-    if (command === 'manifest')
-        return parseManifestArguments(argv.slice(1));
-    if (command === 'map-observations')
-        return parseOfflineImportArguments('map-observations', argv.slice(1));
-    if (command === 'oam-export')
-        return parseOfflineImportArguments('oam-export', argv.slice(1));
-    if (command === 'ct-search')
-        return parseCtSearchArguments(argv.slice(1));
-    if (command === 'ct-intake')
-        return parseCtIntakeArguments(argv.slice(1));
-    if (command === 'discover')
-        return parseDiscoverArguments(argv.slice(1));
-    if (command === 'discover-scan')
-        return parseDiscoverScanArguments(argv.slice(1));
-    if (command === 'posture')
-        return parsePostureArguments(argv.slice(1));
-    if (command === 'http')
-        return parseHttpArguments(argv.slice(1));
-    if (command === 'tls')
-        return parseTlsArguments(argv.slice(1));
-    if (command === 'dnssec-validate')
-        return parseDnssecValidateArguments(argv.slice(1));
-    if (command === 'mail-transport')
-        return parseMailTransportArguments(argv.slice(1));
-    if (command === 'registry-support')
-        return parseRegistrySupportArguments(argv.slice(1));
-    if (command === 'registry-doctor')
-        return parseRegistryDoctorArguments(argv.slice(1));
-    if (command === 'registry-cohort')
-        return parseRegistryCohortArguments(argv.slice(1));
-    if (command === 'registry-scaffold')
-        return parseRegistryScaffoldArguments(argv.slice(1));
-    if (command === 'risk-calibrate')
-        return parseRiskCalibrateArguments(argv.slice(1));
-    if (command === 'lookalike-calibrate')
-        return parseLookalikeCalibrateArguments(argv.slice(1));
-    if (command === 'verify-artifact')
-        return parseVerifyArtifactArguments(argv.slice(1));
-    if (command === 'interchange-report')
-        return parseInterchangeReportArguments(argv.slice(1));
-    if (command === 'inspect-archive')
-        return parseInspectArchiveArguments(argv.slice(1));
-    if (command === 'sign-artifact')
-        return parseSignArtifactArguments(argv.slice(1));
-    if (command === 'verify-signature')
-        return parseVerifySignatureArguments(argv.slice(1));
-    if (command === 'source-report')
-        return parseSourceReportArguments(argv.slice(1));
-    if (command === 'compare')
-        return parseCompareArguments(argv.slice(1));
-    if (command === 'page-compare')
-        return parsePageCompareArguments(argv.slice(1));
-    if (command === 'mail-review')
-        return parseMailReviewArguments(argv.slice(1));
-    if (command === 'review-evidence')
-        return parseReviewEvidenceArguments(argv.slice(1));
-    if (command === 'brief')
-        return parseBriefArguments(argv.slice(1));
-    if (command === 'case-pack')
-        return parseCasePackArguments(argv.slice(1));
-    if (command === 'domain-control')
-        return parseDomainControlArguments(argv.slice(1));
-    if (command === 'monitor-once')
-        return parseMonitorOnceArguments(argv.slice(1));
-    if (command === 'assurance')
-        return parseAssuranceArguments(argv.slice(1));
-    if (command === 'change-packet')
-        return parseChangePacketArguments(argv.slice(1));
-    if (command === 'sharing-review')
-        return parseSharingReviewArguments(argv.slice(1));
-    if (command === 'workflow-plan')
-        return parseWorkflowPlanArguments(argv.slice(1));
-    if (command === 'workflow-run')
-        return parseWorkflowRunArguments(argv.slice(1));
-    if (command === 'diff')
-        return parseDiffArguments(argv.slice(1));
-    if (command === 'reconcile')
-        return parseReconcileArguments(argv.slice(1));
-    if (command === 'timeline')
-        return parseTimelineArguments(argv.slice(1));
-    if (command === 'export')
-        return parseExportArguments(argv.slice(1));
+    const parsed = CLI_PARSERS[command](directLookup ? argv : argv.slice(1));
+    if (parsed.action !== command) {
+        throw new Error(`CLI parser contract mismatch for ${command}.`);
+    }
+    return parsed;
+}
+function parseLookupArguments(lookupArguments) {
     let query = null;
     let output = 'terminal';
     let deep = false;
@@ -232,11 +125,12 @@ function parseCliArgumentsCore(argv) {
     let strictExit = false;
     let events = false;
     let plan = false;
+    let browse = false;
     let includeAttribution = true;
     let failOn = null;
     let observerLabel = null;
     let vantageLabel = null;
-    const lookupArguments = argv.slice(1);
+    let saveLookup = null;
     for (let index = 0; index < lookupArguments.length; index++) {
         const argument = lookupArguments[index];
         if (argument === undefined)
@@ -289,6 +183,19 @@ function parseCliArgumentsCore(argv) {
                 throw new CliUsageError('--plan may be supplied only once.');
             plan = true;
         }
+        else if (argument === '--browse') {
+            if (browse)
+                throw new CliUsageError('--browse may be supplied only once.');
+            browse = true;
+        }
+        else if (argument === '--save-lookup') {
+            if (saveLookup !== null)
+                throw new CliUsageError('--save-lookup may be supplied only once.');
+            const value = lookupArguments[++index];
+            if (!value || value.startsWith('-'))
+                throw new CliUsageError('--save-lookup requires one bounded file path.');
+            saveLookup = value;
+        }
         else if (argument === '--no-attribution') {
             if (!includeAttribution)
                 throw new CliUsageError('--no-attribution may be supplied only once.');
@@ -330,6 +237,17 @@ function parseCliArgumentsCore(argv) {
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
     if (detailSet && output !== 'terminal')
         throw new CliUsageError('--summary and --verbose apply only to terminal output.');
+    if (browse && output !== 'terminal')
+        throw new CliUsageError('--browse applies only to terminal output.');
+    if (browse && (detailSet || events || plan || quiet)) {
+        throw new CliUsageError('--browse cannot be combined with detail, event, plan, or quiet options.');
+    }
+    if (browse && query === null) {
+        throw new CliUsageError('--browse requires a positional target because interactive stdin is reserved for navigation.');
+    }
+    if (saveLookup !== null && !browse) {
+        throw new CliUsageError('--save-lookup requires --browse so the exact completed Lookup document is saved after the browser closes.');
+    }
     if (!includeAttribution && output !== 'markdown' && output !== 'html') {
         throw new CliUsageError('--no-attribution applies only to Markdown or HTML reports.');
     }
@@ -338,7 +256,7 @@ function parseCliArgumentsCore(argv) {
     if (plan && (detailSet || strictExit || events || quiet || failOn !== null)) {
         throw new CliUsageError('--plan cannot be combined with detail, strict-exit, event, or quiet options.');
     }
-    return { action: 'lookup', query, output, deep, detail, strictExit, events, plan, includeAttribution, observerLabel, vantageLabel, quiet, color, ...(failOn ? { failOn } : {}) };
+    return { action: 'lookup', query, output, deep, detail, strictExit, events, plan, includeAttribution, observerLabel, vantageLabel, quiet, color, ...(browse ? { browse: true } : {}), ...(saveLookup ? { saveLookup } : {}), ...(failOn ? { failOn } : {}) };
 }
 function parseCompletionArguments(argv) {
     if (argv.length !== 1 || !['bash', 'zsh', 'fish', 'powershell'].includes(argv[0] || '')) {
@@ -431,14 +349,41 @@ function parseOfflineImportArguments(action, argv) {
 }
 function parseCommandsArguments(argv) {
     let output = 'terminal';
+    let common = false;
+    let group = null;
+    let mode = null;
     let quiet = false;
     let color = true;
-    for (const argument of argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
         if (argument === '--json') {
             if (output !== 'terminal')
                 throw new CliUsageError('--json may be supplied only once.');
             output = 'json';
         }
+        else if (argument === '--common') {
+            if (common)
+                throw new CliUsageError('--common may be supplied only once.');
+            common = true;
+        }
+        else if (argument === '--group') {
+            if (group !== null)
+                throw new CliUsageError('--group may be supplied only once.');
+            const value = argv[++index];
+            if (!['investigate', 'respond', 'assure', 'utilities'].includes(value ?? '')) {
+                throw new CliUsageError('--group requires investigate, respond, assure, or utilities.');
+            }
+            group = value;
+        }
+        else if (argument === '--mode') {
+            if (mode !== null)
+                throw new CliUsageError('--mode may be supplied only once.');
+            const value = argv[++index];
+            if (value !== 'offline' && value !== 'network') {
+                throw new CliUsageError('--mode requires offline or network.');
+            }
+            mode = value;
+        }
         else if (argument === '--quiet')
             quiet = true;
         else if (argument === '--no-color')
@@ -448,7 +393,7 @@ function parseCommandsArguments(argv) {
     }
     if (quiet && output !== 'terminal')
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
-    return { action: 'commands', output, quiet, color };
+    return { action: 'commands', output, common, group, mode, quiet, color };
 }
 function parseDoctorArguments(argv) {
     let network = false;
@@ -1225,9 +1170,11 @@ function parseCasePackArguments(argv) {
     }
     if (audience === null)
         throw new CliUsageError('case-pack requires --audience internal, trusted, or public.');
+    if (!reviewed)
+        throw new CliUsageError('case-pack requires --reviewed to confirm deliberate analyst review.');
     if (quiet && output !== 'terminal')
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
-    return { action: 'case-pack', source, output, audience, reviewed, quiet, color };
+    return { action: 'case-pack', source, output, audience, reviewed: true, quiet, color };
 }
 function parseMonitorOnceArguments(argv) {
     let source = null;
@@ -1235,6 +1182,8 @@ function parseMonitorOnceArguments(argv) {
     let output = 'terminal';
     let limit = 20;
     let concurrency = 2;
+    let limitSupplied = false;
+    let concurrencySupplied = false;
     let failOn = null;
     let quiet = false;
     let color = true;
@@ -1261,14 +1210,21 @@ function parseMonitorOnceArguments(argv) {
             previousSource = value;
         }
         else if (argument === '--limit' || argument === '--concurrency') {
+            if (argument === '--limit' ? limitSupplied : concurrencySupplied) {
+                throw new CliUsageError(`${argument} may be supplied only once.`);
+            }
             const value = Number(argv[++index]);
             const maximum = argument === '--limit' ? 20 : 3;
             if (!Number.isSafeInteger(value) || value < 1 || value > maximum)
                 throw new CliUsageError(`${argument} requires an integer from 1 to ${maximum}.`);
-            if (argument === '--limit')
+            if (argument === '--limit') {
                 limit = value;
-            else
+                limitSupplied = true;
+            }
+            else {
                 concurrency = value;
+                concurrencySupplied = true;
+            }
         }
         else if (argument === '--fail-on') {
             if (failOn !== null)
@@ -1380,15 +1336,33 @@ function parseSharingReviewArguments(argv) {
 }
 function parseWorkflowPlanArguments(argv) {
     const positional = [];
+    let discovery = null;
+    let explainedRecipe = null;
     let output = 'terminal';
     let quiet = false;
     let color = true;
-    for (const argument of argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = argv[index];
         if (argument === '--json') {
             if (output !== 'terminal')
                 throw new CliUsageError('--json may be supplied only once.');
             output = 'json';
         }
+        else if (argument === '--list') {
+            if (discovery !== null)
+                throw new CliUsageError('--list and --explain are mutually exclusive and may be supplied only once.');
+            discovery = 'list';
+        }
+        else if (argument === '--explain') {
+            if (discovery !== null)
+                throw new CliUsageError('--list and --explain are mutually exclusive and may be supplied only once.');
+            const value = argv[++index];
+            if (!INVESTIGATION_PLAN_RECIPES.includes(value)) {
+                throw new CliUsageError(`--explain recipe must be one of: ${INVESTIGATION_PLAN_RECIPES.join(', ')}.`);
+            }
+            discovery = 'explain';
+            explainedRecipe = value;
+        }
         else if (argument === '--quiet')
             quiet = true;
         else if (argument === '--no-color')
@@ -1398,14 +1372,21 @@ function parseWorkflowPlanArguments(argv) {
         else
             positional.push(argument);
     }
+    if (quiet && output !== 'terminal')
+        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
+    if (discovery !== null) {
+        if (positional.length !== 0)
+            throw new CliUsageError('workflow-plan discovery options do not accept a subject.');
+        if (discovery === 'list')
+            return { action: 'workflow-plan', discovery, output, quiet, color };
+        return { action: 'workflow-plan', discovery, recipe: explainedRecipe, output, quiet, color };
+    }
     if (positional.length !== 2)
-        throw new CliUsageError('workflow-plan requires one fixed recipe and one subject.');
+        throw new CliUsageError('workflow-plan requires one fixed recipe and one subject, --list, or --explain <recipe>.');
     const recipe = positional[0];
     if (!INVESTIGATION_PLAN_RECIPES.includes(recipe)) {
         throw new CliUsageError(`workflow-plan recipe must be one of: ${INVESTIGATION_PLAN_RECIPES.join(', ')}.`);
     }
-    if (quiet && output !== 'terminal')
-        throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
     return { action: 'workflow-plan', recipe: recipe, subject: positional[1], output, quiet, color };
 }
 function parseWorkflowRunArguments(argv) {
@@ -1449,8 +1430,8 @@ function parseWorkflowRunArguments(argv) {
     if (positional.length !== 2)
         throw new CliUsageError('workflow-run requires one fixed recipe and one subject.');
     const recipe = positional[0];
-    if (!INVESTIGATION_PLAN_RECIPES.includes(recipe)) {
-        throw new CliUsageError(`workflow-run recipe must be one of: ${INVESTIGATION_PLAN_RECIPES.join(', ')}.`);
+    if (!RUNNABLE_INVESTIGATION_PLAN_RECIPES.includes(recipe)) {
+        throw new CliUsageError(`workflow-run recipe must be one of: ${RUNNABLE_INVESTIGATION_PLAN_RECIPES.join(', ')}.`);
     }
     if (quiet && output !== 'terminal')
         throw new CliUsageError('--quiet cannot be combined with machine-readable output.');
@@ -1774,4 +1755,53 @@ function parseExportArguments(argv) {
         throw new CliUsageError('--no-attribution applies only to Markdown or HTML reports.');
     return { action: 'export', source, format, compact, includeAttribution };
 }
-export { CLI_COMMANDS, CliUsageError, MAX_CLI_ARGUMENTS, MAX_CLI_ARGUMENT_LENGTH, parseCliArguments };
+const CLI_PARSERS = Object.freeze({
+    completion: parseCompletionArguments,
+    doctor: parseDoctorArguments,
+    commands: parseCommandsArguments,
+    manual: parseManualArguments,
+    manifest: parseManifestArguments,
+    'map-observations': (argv) => parseOfflineImportArguments('map-observations', argv),
+    'oam-export': (argv) => parseOfflineImportArguments('oam-export', argv),
+    lookup: parseLookupArguments,
+    bulk: parseBulkArguments,
+    'ct-search': parseCtSearchArguments,
+    'ct-intake': parseCtIntakeArguments,
+    discover: parseDiscoverArguments,
+    'discover-scan': parseDiscoverScanArguments,
+    posture: parsePostureArguments,
+    http: parseHttpArguments,
+    tls: parseTlsArguments,
+    'dnssec-validate': parseDnssecValidateArguments,
+    'mail-transport': parseMailTransportArguments,
+    'registry-support': parseRegistrySupportArguments,
+    'registry-doctor': parseRegistryDoctorArguments,
+    'registry-cohort': parseRegistryCohortArguments,
+    'registry-scaffold': parseRegistryScaffoldArguments,
+    'risk-calibrate': parseRiskCalibrateArguments,
+    'lookalike-calibrate': parseLookalikeCalibrateArguments,
+    'verify-artifact': parseVerifyArtifactArguments,
+    'interchange-report': parseInterchangeReportArguments,
+    'inspect-archive': parseInspectArchiveArguments,
+    'sign-artifact': parseSignArtifactArguments,
+    'verify-signature': parseVerifySignatureArguments,
+    'source-report': parseSourceReportArguments,
+    compare: parseCompareArguments,
+    'page-compare': parsePageCompareArguments,
+    'mail-review': parseMailReviewArguments,
+    'review-evidence': parseReviewEvidenceArguments,
+    brief: parseBriefArguments,
+    'case-pack': parseCasePackArguments,
+    'domain-control': parseDomainControlArguments,
+    'monitor-once': parseMonitorOnceArguments,
+    assurance: parseAssuranceArguments,
+    'change-packet': parseChangePacketArguments,
+    'sharing-review': parseSharingReviewArguments,
+    'workflow-plan': parseWorkflowPlanArguments,
+    'workflow-run': parseWorkflowRunArguments,
+    diff: parseDiffArguments,
+    reconcile: parseReconcileArguments,
+    timeline: parseTimelineArguments,
+    export: parseExportArguments,
+});
+export { CLI_COMMANDS, CLI_PARSERS, CliUsageError, MAX_CLI_ARGUMENTS, MAX_CLI_ARGUMENT_LENGTH, parseCliArguments };