@slicedearth/whoisleuth-cli 2.0.0 → 2.1.0

package/cli/completion.mjs

@@ -52,9 +52,32 @@ function maximumFilePositionals(command) {
 function positionalEnumValues(command) {
     return positionalValues(command, 1);
 }
-const VALUE_OPTIONS = Object.freeze(Object.fromEntries(CLI_COMMAND_REGISTRY.flatMap((definition) => definition.grammar.options)
+const VALUE_OPTION_DEFINITIONS = Object.freeze(CLI_COMMAND_REGISTRY.flatMap((definition) => definition.grammar.options
     .filter((option) => option.values.length > 0)
-    .map((option) => [option.option, option.values])));
+    .map((option) => Object.freeze({ command: definition.command, option: option.option, values: option.values }))));
+const COMMAND_SPECIFIC_VALUE_OPTION_NAMES = new Set(VALUE_OPTION_DEFINITIONS
+    .filter((entry, _index, entries) => new Set(entries
+    .filter((candidate) => candidate.option === entry.option)
+    .map((candidate) => JSON.stringify(candidate.values))).size > 1)
+    .map((entry) => entry.option));
+const VALUE_OPTIONS = Object.freeze(Object.fromEntries(VALUE_OPTION_DEFINITIONS
+    .filter((entry) => !COMMAND_SPECIFIC_VALUE_OPTION_NAMES.has(entry.option))
+    .map((entry) => [entry.option, entry.values])));
+const VALUE_OPTIONS_BY_COMMAND = Object.freeze(Object.fromEntries(VALUE_OPTION_DEFINITIONS
+    .filter((entry) => COMMAND_SPECIFIC_VALUE_OPTION_NAMES.has(entry.option))
+    .map((entry) => [`${entry.command}:${entry.option}`, entry.values])));
+const commandValueOptionGroups = new Map();
+for (const entry of VALUE_OPTION_DEFINITIONS.filter((candidate) => COMMAND_SPECIFIC_VALUE_OPTION_NAMES.has(candidate.option))) {
+    const key = `${entry.option}\u0000${JSON.stringify(entry.values)}`;
+    const group = commandValueOptionGroups.get(key) ?? { option: entry.option, values: entry.values, commands: [] };
+    group.commands.push(entry.command);
+    commandValueOptionGroups.set(key, group);
+}
+const COMMAND_VALUE_OPTION_GROUPS = Object.freeze([...commandValueOptionGroups.values()].map((group) => Object.freeze({
+    option: group.option,
+    values: group.values,
+    commands: Object.freeze([...group.commands]),
+})));
 function integerValues(command, option, whenOptionPresent) {
     const range = commandOptionSpec(command, option)?.integerRanges
         .find((candidate) => candidate.whenOptionPresent === whenOptionPresent);
@@ -71,6 +94,7 @@ function commandOptionPatterns(kinds) {
 }
 function bashCompletion() {
     const cases = CLI_COMMANDS.map((command) => `    ${command}) options="${commandOptions(command)}"; value_options="${optionNamesByKind(command, ['enum', 'file', 'integer', 'policy_list', 'text']).join(' ')}"; file_limit=${maximumFilePositionals(command)} ;;`).join('\n');
+    const commandValueCases = COMMAND_VALUE_OPTION_GROUPS.map((group) => `    ${group.commands.map((command) => `${command}:${group.option}`).join('|')}) COMPREPLY=( $(compgen -W "${group.values.join(' ')}" -- "\${current}") ); return ;;`).join('\n');
     const valueCases = Object.entries(VALUE_OPTIONS).map(([option, values]) => `    ${option}) COMPREPLY=( $(compgen -W "${values.join(' ')}" -- "\${current}") ); return ;;`).join('\n');
     const integerCases = CLI_COMMAND_REGISTRY.flatMap((definition) => definition.grammar.options
         .filter((option) => option.valueKind === 'integer')
@@ -128,6 +152,9 @@ ${cases}
     fi
   done
   if [[ " \${options} " == *" \${previous} "* ]]; then
+    case "\${command}:\${previous}" in
+${commandValueCases}
+    esac
     case "\${previous}" in
 ${valueCases}
     esac
@@ -152,6 +179,7 @@ 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)}); value_options=(${optionNamesByKind(command, ['enum', 'file', 'integer', 'policy_list', 'text']).join(' ')}); file_limit=${maximumFilePositionals(command)} ;;`).join('\n');
+    const commandValueCases = COMMAND_VALUE_OPTION_GROUPS.map((group) => `    ${group.commands.map((command) => `${command}:${group.option}`).join('|')}) compadd -- ${group.values.join(' ')}; return ;;`).join('\n');
     const valueCases = Object.entries(VALUE_OPTIONS).map(([option, values]) => `    ${option}) compadd -- ${values.join(' ')}; return ;;`).join('\n');
     const integerCases = CLI_COMMAND_REGISTRY.flatMap((definition) => definition.grammar.options
         .filter((option) => option.valueKind === 'integer')
@@ -209,6 +237,9 @@ ${cases}
     fi
   done
   if [[ " \${options[*]} " == *" \${previous} "* ]]; then
+    case "\${command}:\${previous}" in
+${commandValueCases}
+    esac
     case "\${previous}" in
 ${valueCases}
     esac
@@ -255,6 +286,15 @@ function fishCompletion() {
             + (group.commands.includes('lookup') ? '; or __whoisleuth_direct_lookup_target' : '');
         return `complete -c whoisleuth -n '${condition}'${group.option === HELP_LONG_ALIAS ? ` -s ${HELP_SHORT_ALIAS.slice(1)}` : ''} -l ${group.option.slice(2)}${group.arity === 1 ? ' -r' : ''}${group.file ? ' -F' : ''}`;
     });
+    const commandValueLines = COMMAND_VALUE_OPTION_GROUPS.flatMap((group) => {
+        const lines = [
+            `complete -c whoisleuth -n '__whoisleuth_command_is ${group.commands.join(' ')}; and __fish_prev_arg_in ${group.option}' -a '${group.values.join(' ')}'`,
+        ];
+        if (group.commands.includes('lookup')) {
+            lines.push(`complete -c whoisleuth -n '__whoisleuth_direct_lookup_target; and __fish_prev_arg_in ${group.option}' -a '${group.values.join(' ')}'`);
+        }
+        return lines;
+    });
     const valueLines = Object.entries(VALUE_OPTIONS).flatMap(([option, values]) => {
         const commands = CLI_COMMANDS.filter((command) => commandOptionSpec(command, option) !== null);
         const namedCondition = commands.length === CLI_COMMANDS.length
@@ -305,7 +345,7 @@ function fishCompletion() {
             ? [`complete -c whoisleuth -n '__whoisleuth_position_is 0 ${command}' -a '${values.join(' ')}'`]
             : [];
     });
-    return `# WHOISleuth fish completion
+    return `# WHOISleuth fish
 function __whoisleuth_clear_direct_lookup_cache --on-event fish_prompt
     set -e __whoisleuth_direct_lookup_cache_key
     set -e __whoisleuth_direct_lookup_cache_status
@@ -322,7 +362,7 @@ function __whoisleuth_direct_lookup_target
     if test "\$__whoisleuth_direct_lookup_cache_key" = "\$cache_key"
         return \$__whoisleuth_direct_lookup_cache_status
     end
-    \$words[1] \$first --plan --json >/dev/null 2>/dev/null
+    \$words[1] \$first --plan --json >/dev/null 2>&1
     set -l result \$status
     set -g __whoisleuth_direct_lookup_cache_key \$cache_key
     set -g __whoisleuth_direct_lookup_cache_status \$result
@@ -398,6 +438,7 @@ ${positionalEnumLines.join('\n')}
 complete -c whoisleuth -n '__whoisleuth_file_position' -F
 ${optionLines.join('\n')}
 ${valueLines.join('\n')}
+${commandValueLines.join('\n')}
 ${integerLines.join('\n')}
 `;
 }
@@ -439,7 +480,10 @@ Register-ArgumentCompleter -Native -CommandName whoisleuth -ScriptBlock {
 ${Object.entries(commandOptions).map(([command, options]) => `    '${command}' = @(${options.map((option) => `'${option}'`).join(', ')})`).join('\n')}
   }
   $values = @{
-${Object.entries(VALUE_OPTIONS).map(([option, values]) => `    '${option}' = @(${values.map((value) => `'${value}'`).join(', ')})`).join('\n')}
+${[
+        ...Object.entries(VALUE_OPTIONS).map(([option, values]) => `    '${option}' = @(${values.map((value) => `'${value}'`).join(', ')})`),
+        ...Object.entries(VALUE_OPTIONS_BY_COMMAND).map(([key, values]) => `    '${key}' = @(${values.map((value) => `'${value}'`).join(', ')})`),
+    ].join('\n')}
   }
   $fileOptions = @{
 ${CLI_COMMANDS.map((command) => `    '${command}' = @(${optionNamesByKind(command, ['file']).map((option) => `'${option}'`).join(', ')})`).join('\n')}
@@ -528,9 +572,11 @@ ${Object.entries(conditionalIntegerRanges).map(([key, range]) => `    '${key}' =
     if (-not $matched) { & $noMatch }
     return
   }
-  if ($previousOwned -and $values.ContainsKey($previous)) {
+  $valueKey = "${'$'}{command}:${'$'}previous"
+  if (-not $values.ContainsKey($valueKey)) { $valueKey = $previous }
+  if ($previousOwned -and $values.ContainsKey($valueKey)) {
     $matched = $false
-    foreach ($candidate in $values[$previous]) {
+    foreach ($candidate in $values[$valueKey]) {
       if ($candidate.StartsWith($wordToComplete, [System.StringComparison]::OrdinalIgnoreCase)) {
         [System.Management.Automation.CompletionResult]::new($candidate, $candidate, 'ParameterValue', $candidate)
         $matched = $true
@@ -585,8 +631,9 @@ function buildShellCompletion(shell) {
             : shell === 'fish'
                 ? fishCompletion()
                 : powershellCompletion();
-    if (Buffer.byteLength(script, 'utf8') > MAX_CLI_COMPLETION_BYTES) {
-        throw new RangeError(`Generated completion is limited to ${MAX_CLI_COMPLETION_BYTES} UTF-8 bytes.`);
+    const byteLength = Buffer.byteLength(script, 'utf8');
+    if (byteLength > MAX_CLI_COMPLETION_BYTES) {
+        throw new RangeError(`Generated ${shell} completion is ${byteLength} UTF-8 bytes; the limit is ${MAX_CLI_COMPLETION_BYTES}.`);
     }
     return script;
 }

package/cli/discriminated-command-handlers.mjs

@@ -0,0 +1,11 @@
+function runDiscriminatedCommandHandler(handlers, args, ...tail) {
+    // TypeScript cannot retain the correlation between a discriminated union and
+    // an indexed mapped type. The map's public type proves that correlation;
+    // this local cast only performs the already-checked lookup.
+    const handler = handlers[args.action];
+    if (typeof handler !== 'function') {
+        throw new Error(`No command handler is registered for ${String(args.action)}.`);
+    }
+    return handler(args, ...tail);
+}
+export { runDiscriminatedCommandHandler };

package/cli/doctor.mjs

@@ -27,8 +27,8 @@ async function buildDoctorReport(options) {
             label: 'Node runtime',
             state: nodeSupported ? 'pass' : 'partial',
             detail: nodeSupported
-                ? `Node ${nodeVersion} satisfies the supported Node ${MINIMUM_NODE_MAJOR}+ runtime.`
-                : `Node ${nodeVersion} is below the supported Node ${MINIMUM_NODE_MAJOR}+ runtime.`,
+                ? `Node ${nodeVersion} meets the minimum Node ${MINIMUM_NODE_MAJOR} runtime requirement.`
+                : `Node ${nodeVersion} is below the minimum Node ${MINIMUM_NODE_MAJOR} runtime requirement.`,
         }),
         Object.freeze({
             id: 'platform',

package/cli/evidence-command-runner.mjs

@@ -5,6 +5,7 @@ import { boundedCliErrorMessage, CliUsageError } from "./errors.mjs";
 import EXIT_CODES from "./exit-codes.mjs";
 import { formatJsonDocument } from "./formatters/json.mjs";
 import { readCliTextInput } from "./input.mjs";
+import { runDiscriminatedCommandHandler } from "./discriminated-command-handlers.mjs";
 export function isEvidenceCommand(args) {
     return args.action === 'inspect-archive'
         || args.action === 'sign-artifact'
@@ -63,39 +64,39 @@ async function readPassphrase(source, dependencies) {
     }
     return passphrase;
 }
-export async function runEvidenceCommand(args, dependencies) {
-    if (args.action === 'inspect-archive') {
-        const input = await readArtifact(args.source, 'Archive input', dependencies);
-        if (!input.trim()) {
-            throw new CliUsageError('inspect-archive requires one workspace archive file or an archive on stdin.');
-        }
-        const passphrase = args.passphraseSource
-            ? await readPassphrase(args.passphraseSource, dependencies)
-            : null;
-        const report = await inspectWorkspaceArchive(input, {
-            passphrase,
-            search: args.search,
-            reveal: args.reveal,
-            requireMatch: args.requireMatch,
-            expectedContentDigest: args.expectedContentDigest,
-        });
-        if (!args.quiet) {
-            dependencies.stdout.write(args.output === 'json'
-                ? formatJsonDocument(report)
-                : formatArchiveInspection(report));
-        }
-        return EXIT_CODES.SUCCESS;
+async function runInspectArchiveCommand(args, dependencies) {
+    const input = await readArtifact(args.source, 'Archive input', dependencies);
+    if (!input.trim()) {
+        throw new CliUsageError('inspect-archive requires one workspace archive file or an archive on stdin.');
     }
-    if (args.action === 'sign-artifact') {
-        const input = await readArtifact(args.source, 'Evidence artefact input', dependencies);
-        if (!input.trim()) {
-            throw new CliUsageError('sign-artifact requires one reviewed artefact file or an artefact on stdin.');
-        }
-        const privateKey = await readKey(args.privateKeySource, 'Private key file', dependencies.readPrivateKeyFile, dependencies);
-        const signed = await signEvidencePackage(input, privateKey, dependencies.now ? dependencies.now() : new Date().toISOString());
-        dependencies.stdout.write(formatJsonDocument(signed));
-        return EXIT_CODES.SUCCESS;
+    const passphrase = args.passphraseSource
+        ? await readPassphrase(args.passphraseSource, dependencies)
+        : null;
+    const report = await inspectWorkspaceArchive(input, {
+        passphrase,
+        search: args.search,
+        reveal: args.reveal,
+        requireMatch: args.requireMatch,
+        expectedContentDigest: args.expectedContentDigest,
+    });
+    if (!args.quiet) {
+        dependencies.stdout.write(args.output === 'json'
+            ? formatJsonDocument(report)
+            : formatArchiveInspection(report));
     }
+    return EXIT_CODES.SUCCESS;
+}
+async function runSignArtifactCommand(args, dependencies) {
+    const input = await readArtifact(args.source, 'Evidence artefact input', dependencies);
+    if (!input.trim()) {
+        throw new CliUsageError('sign-artifact requires one reviewed artefact file or an artefact on stdin.');
+    }
+    const privateKey = await readKey(args.privateKeySource, 'Private key file', dependencies.readPrivateKeyFile, dependencies);
+    const signed = await signEvidencePackage(input, privateKey, dependencies.now ? dependencies.now() : new Date().toISOString());
+    dependencies.stdout.write(formatJsonDocument(signed));
+    return EXIT_CODES.SUCCESS;
+}
+async function runVerifySignatureCommand(args, dependencies) {
     const input = await readArtifact(args.source, 'Signed evidence package input', dependencies);
     if (!input.trim()) {
         throw new CliUsageError('verify-signature requires one signed package file or a package on stdin.');
@@ -111,3 +112,12 @@ export async function runEvidenceCommand(args, dependencies) {
     }
     return EXIT_CODES.SUCCESS;
 }
+const EVIDENCE_COMMAND_HANDLERS = Object.freeze({
+    'inspect-archive': runInspectArchiveCommand,
+    'sign-artifact': runSignArtifactCommand,
+    'verify-signature': runVerifySignatureCommand,
+});
+function runEvidenceCommand(args, dependencies) {
+    return runDiscriminatedCommandHandler(EVIDENCE_COMMAND_HANDLERS, args, dependencies);
+}
+export { EVIDENCE_COMMAND_HANDLERS, runEvidenceCommand };

package/cli/export-evidence.mjs

@@ -1,6 +1,6 @@
 import { projectCliLookupComparisonInput } from "./compare.mjs";
 import { parseSavedLookupDocument } from "./saved-lookup.mjs";
-import { validateLookupEvidenceArtifactStructure } from "./artifact-structure.mjs";
+import { validateLookupEvidenceArtifactStructure } from "./offline-artifact-validation.mjs";
 import { WHOISLEUTH_APPLICATION_VERSION } from "../lib/application-version.mjs";
 import { LOOKUP_EVIDENCE_PORTABLE_MAX_BYTES, serializeLookupEvidence, } from "../lib/evidence-export.mjs";
 const APPLICATION_VERSION = WHOISLEUTH_APPLICATION_VERSION;

package/cli/fail-policy.mjs

@@ -1,27 +1,42 @@
 import { lookupStrictExitFindings } from "./strict-exit.mjs";
 import { CliUsageError } from "./errors.mjs";
 export const CLI_FAIL_POLICIES = ['source-failure', 'inconclusive', 'danger', 'material-drift'];
+export const CLI_FAIL_POLICIES_BY_COMMAND = Object.freeze({
+    lookup: Object.freeze(['source-failure', 'inconclusive', 'danger']),
+    bulk: Object.freeze(['source-failure', 'inconclusive', 'danger']),
+    'discover-scan': Object.freeze(['source-failure', 'inconclusive', 'danger']),
+    'monitor-once': Object.freeze(['source-failure', 'inconclusive', 'material-drift']),
+});
 function record(value) {
     return value && typeof value === 'object' && !Array.isArray(value) ? value : {};
 }
-export function parseCliFailPolicies(value) {
+export function parseCliFailPolicies(value, command) {
     if (typeof value !== 'string' || !value || value.length > 100)
         throw new CliUsageError('--fail-on requires a comma-separated policy list.');
     const policies = [...new Set(value.split(',').map((item) => item.trim().toLowerCase()).filter(Boolean))];
-    if (!policies.length || policies.some((item) => !CLI_FAIL_POLICIES.includes(item))) {
-        throw new CliUsageError(`--fail-on supports: ${CLI_FAIL_POLICIES.join(', ')}.`);
+    const supported = CLI_FAIL_POLICIES_BY_COMMAND[command];
+    if (!policies.length || policies.some((item) => !supported.includes(item))) {
+        throw new CliUsageError(`--fail-on for ${command} supports: ${supported.join(', ')}.`);
     }
     return policies;
 }
 function availabilityStates(document) {
     const direct = String(record(document.availability).state || '').toLowerCase();
+    const review = String(record(document.review).state || '').toLowerCase();
     const results = Array.isArray(document.results) ? document.results : [];
     const resultStates = results.flatMap((value) => {
         const item = record(value);
         const state = item.availabilityState ?? record(item.availability).state;
         return typeof state === 'string' ? [state.toLowerCase()] : [];
     });
-    return [direct, ...resultStates].filter(Boolean);
+    return [direct, review, ...resultStates].filter(Boolean);
+}
+function riskScore(value) {
+    const raw = record(value.risk).score ?? value.riskScore;
+    if (raw === null || raw === undefined || raw === '')
+        return null;
+    const parsed = Number(raw);
+    return Number.isFinite(parsed) ? parsed : null;
 }
 export function evaluateCliFailPolicies(document, policies) {
     const root = record(document);
@@ -44,10 +59,20 @@ export function evaluateCliFailPolicies(document, policies) {
                 findings.push({ policy, reason: `${count} authority or availability state(s) remained inconclusive` });
         }
         else if (policy === 'danger') {
-            const risk = Number(record(root.risk).score ?? root.riskScore);
-            const severity = String(root.severity || record(root.review).severity || '').toLowerCase();
-            if ((Number.isFinite(risk) && risk >= 70) || severity === 'danger' || severity === 'critical') {
-                findings.push({ policy, reason: Number.isFinite(risk) ? `risk score ${risk} met the 70 review threshold` : `explicit ${severity} severity was present` });
+            const documents = [root, ...(Array.isArray(root.results) ? root.results.map(record) : [])];
+            const risks = documents.map(riskScore).filter((score) => score !== null);
+            const severities = documents
+                .flatMap((item) => [item.severity, record(item.review).severity])
+                .map((severity) => String(severity || '').toLowerCase())
+                .filter((severity) => severity === 'danger' || severity === 'critical');
+            const highestRisk = risks.length ? Math.max(...risks) : null;
+            if ((highestRisk !== null && highestRisk >= 70) || severities.length) {
+                findings.push({
+                    policy,
+                    reason: highestRisk !== null && highestRisk >= 70
+                        ? `risk score ${highestRisk} met the 70 review threshold`
+                        : `explicit ${severities[0]} severity was present`,
+                });
             }
         }
         else {