diff --git a/src/cli/commandRegistry.ts b/src/cli/commandRegistry.ts index d246683945..5f162f5b4b 100644 --- a/src/cli/commandRegistry.ts +++ b/src/cli/commandRegistry.ts @@ -165,3 +165,31 @@ export const distinctOperations = ( const seen = new Set(); return operations.filter(({ name }) => !seen.has(name) && seen.add(name)); }; + +/** + * Contract operations the command itself answers, excluding the session-target + * opener and any Evidence-target source operation it runs first. + */ +export const commandOwnOperations = ( + entry: CliCommandEntry, +): readonly CliCommandOperation[] => { + const { source, operations } = entry; + if (source.kind === "contract") { + const opening = source.description.sessionTarget?.opening; + const targetSource = source.description.evidenceTargets?.source; + return operations.filter( + ({ name }) => name !== opening && name !== targetSource, + ); + } + if (source.kind === "routed") { + const own = new Set( + source.descriptions.map((description) => description.contract.name), + ); + return operations.filter(({ name }) => own.has(name)); + } + if (source.kind === "document") { + const opening = source.description.sessionTarget?.opening; + return operations.filter(({ name }) => name !== opening); + } + return operations; +}; diff --git a/src/cli/environmentCommands.ts b/src/cli/environmentCommands.ts index 4664b9d353..f2990f6075 100644 --- a/src/cli/environmentCommands.ts +++ b/src/cli/environmentCommands.ts @@ -483,71 +483,94 @@ const registerBuildCommand = ( logger: Logger, environment: Readonly, ): void => { - registerCliCommand(cli, CLI_COMMANDS.environmentBuild, { - description: - "Build an agent environment bundle from a recorded capture in one offline step: inspect a HAR (or read capture Evidence), project the environment manifest, derive the state, report which tools the environment answers from state, which replay and why each write is withheld, then write the bundle environment-export writes", - args: z.object({ - capture: localPathStringSchema.describe( - "A .har file, or capture Evidence JSON from inspect-web-network-capture (HAR) or capture-browser-scenario", - ), - directory: localPathStringSchema - .optional() - .describe( - "Bundle directory to create; must be absent or empty, nothing is overwritten; omit only with --dry-run", + registerCliCommand( + cli, + CLI_COMMANDS.environmentBuild, + { + description: + "Build an agent environment bundle from a recorded capture in one offline step: inspect a HAR (or read capture Evidence), project the environment manifest, derive the state, report which tools the environment answers from state, which replay and why each write is withheld, then write the bundle environment-export writes", + args: z.object({ + capture: localPathStringSchema.describe( + "A .har file, or capture Evidence JSON from inspect-web-network-capture (HAR) or capture-browser-scenario", ), - }), - options: z.object({ - name: z - .string() - .optional() - .describe( - "Env folder and env id (kebab-case); default the manifest's name, or the capture file's name when the origin is a loopback or IP address", + directory: localPathStringSchema + .optional() + .describe( + "Bundle directory to create; must be absent or empty, nothing is overwritten; omit only with --dry-run", + ), + }), + options: z.object({ + name: z + .string() + .optional() + .describe( + "Env folder and env id (kebab-case); default the manifest's name, or the capture file's name when the origin is a loopback or IP address", + ), + templateRule: z + .array(z.enum(TEMPLATE_RULES)) + .optional() + .describe( + "Opt-in template rule; repeat to select several. Replaces the default after-uid-literal, opaque-token, sibling-variance and prefix-variance", + ), + formatRulesOnly: z + .boolean() + .default(false) + .describe("Apply only the four format rules, the views' own default"), + packageTarball: localPathStringSchema + .optional() + .describe( + "Packed rea-agents tarball (npm pack) copied into the env folder and installed by the Dockerfile instead of the registry package pinned to this version", + ), + dryRun: z + .boolean() + .default(false) + .describe("Run every stage and report, but write nothing"), + // Decimal tokens only: numeric coercion would read "0x1" as 1 ms. + captureTimeoutMs: cliDecimalField( + inspectWebNetworkCaptureInputSchema.shape.capture_timeout_ms, ), - templateRule: z - .array(z.enum(TEMPLATE_RULES)) - .optional() - .describe( - "Opt-in template rule; repeat to select several. Replaces the default after-uid-literal, opaque-token, sibling-variance and prefix-variance", - ), - formatRulesOnly: z - .boolean() - .default(false) - .describe("Apply only the four format rules, the views' own default"), - packageTarball: localPathStringSchema - .optional() - .describe( - "Packed rea-agents tarball (npm pack) copied into the env folder and installed by the Dockerfile instead of the registry package pinned to this version", - ), - dryRun: z - .boolean() - .default(false) - .describe("Run every stage and report, but write nothing"), - // Decimal tokens only: numeric coercion would read "0x1" as 1 ms. - captureTimeoutMs: cliDecimalField( - inspectWebNetworkCaptureInputSchema.shape.capture_timeout_ms, - ), - }), - run: ({ args, options }) => - withCommandCancellation((signal) => - logCliCommand(logger, CLI_COMMANDS.environmentBuild, () => - buildEnvironmentCommand( - { - capture: args.capture, - directory: args.directory, - name: options.name, - templateRule: options.templateRule, - formatRulesOnly: options.formatRulesOnly, - packageTarball: options.packageTarball, - dryRun: options.dryRun, - captureTimeoutMs: options.captureTimeoutMs, - }, - environment, - logger, - signal, + }), + run: ({ args, options }) => + withCommandCancellation((signal) => + logCliCommand(logger, CLI_COMMANDS.environmentBuild, () => + buildEnvironmentCommand( + { + capture: args.capture, + directory: args.directory, + name: options.name, + templateRule: options.templateRule, + formatRulesOnly: options.formatRulesOnly, + packageTarball: options.packageTarball, + dryRun: options.dryRun, + captureTimeoutMs: options.captureTimeoutMs, + }, + environment, + logger, + signal, + ), ), ), - ), - }); + }, + { + operations: [ + { + name: "export_environment_bundle", + flags: { + name: "--name", + template_rules: "--template-rule", + package_tarball: "--package-tarball", + dry_run: "--dry-run", + }, + }, + { + name: "inspect_web_network_capture", + flags: { + capture_timeout_ms: "--capture-timeout-ms", + }, + }, + ], + }, + ); }; const manifestArgument = z diff --git a/src/cli/guidanceCommands.ts b/src/cli/guidanceCommands.ts index fcea407406..411dd35e42 100644 --- a/src/cli/guidanceCommands.ts +++ b/src/cli/guidanceCommands.ts @@ -52,86 +52,110 @@ export const registerGuidanceCommands = ( logger: Logger, resources: CliGuidanceResources = processGuidanceResources, ): void => { - registerCliCommand(cli, CLI_COMMANDS.guidance, { - description: "Search or read the installed REA workflow guidance", - args: z.object({}), - options: z - .object({ - action: z - .enum(["search", "read"]) - .default("search") - .describe("Guidance action to perform: search or read"), - query: searchGuidanceInputSchema.shape.query - .optional() - .describe( - "Required with search; all non-generic query words must match", + registerCliCommand( + cli, + CLI_COMMANDS.guidance, + { + description: "Search or read the installed REA workflow guidance", + args: z.object({}), + options: z + .object({ + action: z + .enum(["search", "read"]) + .default("search") + .describe("Guidance action to perform: search or read"), + query: searchGuidanceInputSchema.shape.query + .optional() + .describe( + "Required with search; all non-generic query words must match", + ), + locator: readGuidanceSectionInputSchema.shape.locator + .optional() + .describe( + "Required with --action read; locator returned by search", + ), + // Decimal tokens only: numeric coercion would read "0x2" as 2. + limit: cliDecimalField(searchGuidanceLimitSchema.optional()).describe( + "Maximum search matches; search only, defaults to 8", ), - locator: readGuidanceSectionInputSchema.shape.locator - .optional() - .describe("Required with --action read; locator returned by search"), - // Decimal tokens only: numeric coercion would read "0x2" as 2. - limit: cliDecimalField(searchGuidanceLimitSchema.optional()).describe( - "Maximum search matches; search only, defaults to 8", - ), - cursor: searchGuidanceInputSchema.shape.cursor - .optional() - .describe("Continue a search page; search only"), - }) - .superRefine((options, context) => { - if (options.action === "search") { - if (options.query === undefined) - context.addIssue({ - code: "custom", - path: ["query"], - message: "--query is required with --action search", - }); - if (options.locator !== undefined) - context.addIssue({ - code: "custom", - path: ["locator"], - message: "--locator can only be used with --action read", - }); - } else { - if (options.locator === undefined) - context.addIssue({ - code: "custom", - path: ["locator"], - message: "--locator is required with --action read", - }); - for (const option of ["query", "limit", "cursor"] as const) - if (options[option] !== undefined) + cursor: searchGuidanceInputSchema.shape.cursor + .optional() + .describe("Continue a search page; search only"), + }) + .superRefine((options, context) => { + if (options.action === "search") { + if (options.query === undefined) context.addIssue({ code: "custom", - path: [option], - message: `--${option} can only be used with --action search`, + path: ["query"], + message: "--query is required with --action search", }); - } - }), - run: ({ options }) => - logCliCommand(logger, CLI_COMMANDS.guidance, async () => { - const result = - options.action === "search" - ? await searchGuidance( - { - ...(options.query === undefined - ? {} - : { query: options.query }), - ...(options.limit === undefined - ? {} - : { limit: options.limit }), - ...(options.cursor === undefined - ? {} - : { cursor: options.cursor }), - }, - resources.resources(), - ) - : await readGuidanceSection( - { - locator: options.locator, - }, - resources.resources(), - ); - return result.ok ? result.value : projectAnalysisError(result.error); - }), - }); + if (options.locator !== undefined) + context.addIssue({ + code: "custom", + path: ["locator"], + message: "--locator can only be used with --action read", + }); + } else { + if (options.locator === undefined) + context.addIssue({ + code: "custom", + path: ["locator"], + message: "--locator is required with --action read", + }); + for (const option of ["query", "limit", "cursor"] as const) + if (options[option] !== undefined) + context.addIssue({ + code: "custom", + path: [option], + message: `--${option} can only be used with --action search`, + }); + } + }), + run: ({ options }) => + logCliCommand(logger, CLI_COMMANDS.guidance, async () => { + const result = + options.action === "search" + ? await searchGuidance( + { + ...(options.query === undefined + ? {} + : { query: options.query }), + ...(options.limit === undefined + ? {} + : { limit: options.limit }), + ...(options.cursor === undefined + ? {} + : { cursor: options.cursor }), + }, + resources.resources(), + ) + : await readGuidanceSection( + { + locator: options.locator, + }, + resources.resources(), + ); + return result.ok ? result.value : projectAnalysisError(result.error); + }), + }, + { + operations: [ + { + name: "search_guidance", + flags: { + query: "--query", + limit: "--limit", + cursor: "--cursor", + }, + }, + { + name: "read_guidance_section", + flags: { + locator: "--locator", + }, + }, + ], + }, + ); }; diff --git a/src/cli/processCommands.ts b/src/cli/processCommands.ts index 8d5631393f..188b68743d 100644 --- a/src/cli/processCommands.ts +++ b/src/cli/processCommands.ts @@ -27,20 +27,29 @@ export const registerProcessCommands = ( logger: Logger, environment: Readonly>, ): void => { - registerCliCommand(cli, CLI_COMMANDS.captureProcess, { - description: "Capture one caller-selected process scenario", - args: z.object({ - scenario: localPathStringSchema.describe("Scenario JSON path"), - }), - run: ({ args }) => - withCommandCancellation((signal) => - logCliCommand(logger, "capture-process", () => - captureProcessScenarioFile(args.scenario, environment, signal).catch( - projectProcessCliInputCleanupError, + registerCliCommand( + cli, + CLI_COMMANDS.captureProcess, + { + description: "Capture one caller-selected process scenario", + args: z.object({ + scenario: localPathStringSchema.describe("Scenario JSON path"), + }), + run: ({ args }) => + withCommandCancellation((signal) => + logCliCommand(logger, "capture-process", () => + captureProcessScenarioFile( + args.scenario, + environment, + signal, + ).catch(projectProcessCliInputCleanupError), ), ), - ), - }); + }, + { + operations: [{ name: "capture_process_scenario", flags: {} }], + }, + ); registerContractCommand( cli as CliInstance, logger, diff --git a/src/cli/reverseEngineeringCommands.ts b/src/cli/reverseEngineeringCommands.ts index 0f693736e7..5271c76476 100644 --- a/src/cli/reverseEngineeringCommands.ts +++ b/src/cli/reverseEngineeringCommands.ts @@ -233,163 +233,178 @@ export const registerReverseEngineeringCommands = ( ), ), ); - registerCliCommand(cli, CLI_COMMANDS.debugWithGdb, { - description: - "Run one unrestricted GDB console command in an ephemeral MI session; provide an inferior TTY so a live target can be safely detached", - args: z.object({ - command: z - .string() - .min(1) - .describe("One unrestricted GDB console command."), - }), - options: z.object({ - executable: z - .string() - .min(1) - .optional() - .describe( - "Initial local file to hash and load without running it; command Evidence retains this initial selection.", - ), - inferiorTty: z - .string() - .min(1) - .describe( - "Caller-selected durable TTY for output from a live GDB inferior.", - ), - ...analysisEvidenceDeliveryOptions, - }), - run: ({ args, options }) => - withCommandCancellation((signal) => - logCliCommand(logger, CLI_COMMANDS.debugWithGdb, async () => { - const delivery = { - providerId: "gdb", - operation: "gdb_console", - signal, - detail: options.detail, - evidenceOutput: options.evidence_output, - }; - const inputError = cliEvidenceDeliveryInputError(delivery); - if (inputError !== undefined) return projectAnalysisError(inputError); - if (gdbOneShotCommandMayInvalidateDetachProof(args.command)) - return projectAnalysisError( - new AnalysisInputError("gdb_console", undefined, [ - { - path: ["command"], - reason: "invalid_value", - message: - "This command can invalidate the verified inferior output route; use the persistent GDB session workflow.", - }, - ]), - ); - const manager = createGdbManager(environment); - let sessionId: string | undefined; - return deliverCliAnalysisEvidence({ - ...delivery, - run: async () => { - const started = await manager.start(signal, { - inferiorTty: options.inferiorTty, - ...(options.executable === undefined - ? {} - : { executable: options.executable }), - }); - if (!started.ok) return started; - sessionId = started.value.session_id; - const executed = await manager.execute( - sessionId, - args.command, - signal, + registerCliCommand( + cli, + CLI_COMMANDS.debugWithGdb, + { + description: + "Run one unrestricted GDB console command in an ephemeral MI session; provide an inferior TTY so a live target can be safely detached", + args: z.object({ + command: z + .string() + .min(1) + .describe("One unrestricted GDB console command."), + }), + options: z.object({ + executable: z + .string() + .min(1) + .optional() + .describe( + "Initial local file to hash and load without running it; command Evidence retains this initial selection.", + ), + inferiorTty: z + .string() + .min(1) + .describe( + "Caller-selected durable TTY for output from a live GDB inferior.", + ), + ...analysisEvidenceDeliveryOptions, + }), + run: ({ args, options }) => + withCommandCancellation((signal) => + logCliCommand(logger, CLI_COMMANDS.debugWithGdb, async () => { + const delivery = { + providerId: "gdb", + operation: "gdb_console", + signal, + detail: options.detail, + evidenceOutput: options.evidence_output, + }; + const inputError = cliEvidenceDeliveryInputError(delivery); + if (inputError !== undefined) + return projectAnalysisError(inputError); + if (gdbOneShotCommandMayInvalidateDetachProof(args.command)) + return projectAnalysisError( + new AnalysisInputError("gdb_console", undefined, [ + { + path: ["command"], + reason: "invalid_value", + message: + "This command can invalidate the verified inferior output route; use the persistent GDB session workflow.", + }, + ]), ); - return executed.ok ? ok(executed.value.evidence) : executed; - }, - service: { - close: () => - closeDebuggerCommandSession( - manager, - sessionId, - "gdb", - "gdb_console", - (cleanup) => - logger.error( - { command: CLI_COMMANDS.debugWithGdb, cleanup }, - "GDB cleanup failed after collecting command output", - ), - ), - }, - }); - }), - ), - }); - registerCliCommand(cli, CLI_COMMANDS.debugWithRizin, { - description: - "Run one unrestricted Rizin debugger command in an ephemeral session", - args: z.object({ - path: localPathStringSchema.describe( - "Path to the local artifact to debug.", - ), - command: z - .string() - .min(1) - .describe("One unrestricted Rizin debugger command.") - .refine((value) => !/[\r\n]/u.test(value)), - }), - options: z.object({ - inferiorTty: z - .string() - .min(1) - .describe( - "Caller-selected Linux TTY for inferior stdin, stdout and stderr.", - ), - backend: z - .string() - .min(1) - .optional() - .describe("Optional Rizin IO debugger backend name."), - }), - run: ({ args, options }) => - withCommandCancellation((signal) => - logCliCommand(logger, CLI_COMMANDS.debugWithRizin, async () => { - const manager = createRizinDebugSessionManager(environment); - let sessionId: string | undefined; - return finishAnalysisCommand( - async () => { - const started = await manager.start( - { - ...args, - inferior_tty: options.inferiorTty, - ...(options.backend === undefined + const manager = createGdbManager(environment); + let sessionId: string | undefined; + return deliverCliAnalysisEvidence({ + ...delivery, + run: async () => { + const started = await manager.start(signal, { + inferiorTty: options.inferiorTty, + ...(options.executable === undefined ? {} - : { backend: options.backend }), - }, - signal, - ); - if (!started.ok) return started; - sessionId = started.value.session_id; - const executed = await manager.execute( - sessionId, - args.command, - signal, - ); - return executed.ok ? ok(executed.value.evidence) : executed; - }, - { - close: () => - closeDebuggerCommandSession( - manager, + : { executable: options.executable }), + }); + if (!started.ok) return started; + sessionId = started.value.session_id; + const executed = await manager.execute( sessionId, - "rizin", - "rizin_debug_command", - (cleanup) => - logger.error( - { command: CLI_COMMANDS.debugWithRizin, cleanup }, - "Rizin cleanup failed after collecting command output", - ), - ), - }, - "rizin", - "rizin_debug_command", - signal, - ).then(projectCliAnalysisResult); - }), - ), - }); + args.command, + signal, + ); + return executed.ok ? ok(executed.value.evidence) : executed; + }, + service: { + close: () => + closeDebuggerCommandSession( + manager, + sessionId, + "gdb", + "gdb_console", + (cleanup) => + logger.error( + { command: CLI_COMMANDS.debugWithGdb, cleanup }, + "GDB cleanup failed after collecting command output", + ), + ), + }, + }); + }), + ), + }, + { + operations: [{ name: "gdb_console", flags: {} }], + }, + ); + registerCliCommand( + cli, + CLI_COMMANDS.debugWithRizin, + { + description: + "Run one unrestricted Rizin debugger command in an ephemeral session", + args: z.object({ + path: localPathStringSchema.describe( + "Path to the local artifact to debug.", + ), + command: z + .string() + .min(1) + .describe("One unrestricted Rizin debugger command.") + .refine((value) => !/[\r\n]/u.test(value)), + }), + options: z.object({ + inferiorTty: z + .string() + .min(1) + .describe( + "Caller-selected Linux TTY for inferior stdin, stdout and stderr.", + ), + backend: z + .string() + .min(1) + .optional() + .describe("Optional Rizin IO debugger backend name."), + }), + run: ({ args, options }) => + withCommandCancellation((signal) => + logCliCommand(logger, CLI_COMMANDS.debugWithRizin, async () => { + const manager = createRizinDebugSessionManager(environment); + let sessionId: string | undefined; + return finishAnalysisCommand( + async () => { + const started = await manager.start( + { + ...args, + inferior_tty: options.inferiorTty, + ...(options.backend === undefined + ? {} + : { backend: options.backend }), + }, + signal, + ); + if (!started.ok) return started; + sessionId = started.value.session_id; + const executed = await manager.execute( + sessionId, + args.command, + signal, + ); + return executed.ok ? ok(executed.value.evidence) : executed; + }, + { + close: () => + closeDebuggerCommandSession( + manager, + sessionId, + "rizin", + "rizin_debug_command", + (cleanup) => + logger.error( + { command: CLI_COMMANDS.debugWithRizin, cleanup }, + "Rizin cleanup failed after collecting command output", + ), + ), + }, + "rizin", + "rizin_debug_command", + signal, + ).then(projectCliAnalysisResult); + }), + ), + }, + { + operations: [{ name: "rizin_debug_command", flags: {} }], + }, + ); }; diff --git a/src/cliEvidenceCommands.ts b/src/cliEvidenceCommands.ts index 12ad614842..d18cf6b35d 100644 --- a/src/cliEvidenceCommands.ts +++ b/src/cliEvidenceCommands.ts @@ -62,55 +62,69 @@ export const registerEvidenceCommands = ( }), ), }); - registerCliCommand(cli, CLI_COMMANDS.compare, { - description: - "Compare two canonical Evidence bundles by record identity; use compare-artifacts for artifact inventory contents", - args: z.object({ - left: localPathStringSchema.describe("Left Evidence bundle JSON path"), - right: localPathStringSchema.describe("Right Evidence bundle JSON path"), - }), - options: z.object({ - record_pairs: z - .string() - .optional() - .describe( - "Inline JSON array or local JSON file of left_evidence_id/right_evidence_id pairs", + registerCliCommand( + cli, + CLI_COMMANDS.compare, + { + description: + "Compare two canonical Evidence bundles by record identity; use compare-artifacts for artifact inventory contents", + args: z.object({ + left: localPathStringSchema.describe("Left Evidence bundle JSON path"), + right: localPathStringSchema.describe( + "Right Evidence bundle JSON path", ), - }), - run: ({ args, options }) => - withCommandCancellation((signal) => - logCliCommand(logger, "compare", async () => { - const decoded = - options.record_pairs === undefined - ? { ok: true as const, value: [] } - : await parseCliJsonInput( - options.record_pairs, + }), + options: z.object({ + record_pairs: z + .string() + .optional() + .describe( + "Inline JSON array or local JSON file of left_evidence_id/right_evidence_id pairs", + ), + }), + run: ({ args, options }) => + withCommandCancellation((signal) => + logCliCommand(logger, "compare", async () => { + const decoded = + options.record_pairs === undefined + ? { ok: true as const, value: [] } + : await parseCliJsonInput( + options.record_pairs, + "compare_bundles", + signal, + ); + if (!decoded.ok) return decoded.error; + const input = { record_pairs: decoded.value }; + const selected = bundleComparisonInputSchema + .pick({ record_pairs: true }) + .safeParse(input); + if (!selected.success) + return cliError( + analysisInputErrorFromIssues( "compare_bundles", - signal, - ); - if (!decoded.ok) return decoded.error; - const input = { record_pairs: decoded.value }; - const selected = bundleComparisonInputSchema - .pick({ record_pairs: true }) - .safeParse(input); - if (!selected.success) - return cliError( - analysisInputErrorFromIssues( - "compare_bundles", - selected.error.issues, - input, - ), - ); - const compared = await compareEvidenceBundlesCommand({ - leftPath: args.left, - rightPath: args.right, - recordPairs: selected.data.record_pairs, - signal, - }); - return compared.ok ? compared.value : cliError(compared.error); - }), - ), - }); + selected.error.issues, + input, + ), + ); + const compared = await compareEvidenceBundlesCommand({ + leftPath: args.left, + rightPath: args.right, + recordPairs: selected.data.record_pairs, + signal, + }); + return compared.ok ? compared.value : cliError(compared.error); + }), + ), + }, + { + operations: [ + { + name: "compare_bundles", + flags: { record_pairs: "--record_pairs" }, + }, + ], + }, + ); }; const cliError = (error: AnalysisError): JsonValue => ({ diff --git a/tests/boundary/cli/cliCommandRegistry.test.ts b/tests/boundary/cli/cliCommandRegistry.test.ts index 8b8cffdc05..7138361294 100644 --- a/tests/boundary/cli/cliCommandRegistry.test.ts +++ b/tests/boundary/cli/cliCommandRegistry.test.ts @@ -91,10 +91,31 @@ describe("REA's CLI command table", () => { }); }); - it("lists host commands without operations", () => { - for (const name of ["setup", "doctor", "guidance", "capture-process"]) { + it("distinguishes host commands without operations from host commands that bind contract operations", () => { + for (const name of ["setup", "doctor"]) { expect(entry(name).source).toEqual({ kind: "host" }); expect(entry(name).operations).toEqual([]); } + expect(entry("guidance").source).toEqual({ kind: "host" }); + expect(entry("guidance").operations).toEqual([ + { + name: "search_guidance", + flags: { + query: "--query", + limit: "--limit", + cursor: "--cursor", + }, + }, + { + name: "read_guidance_section", + flags: { + locator: "--locator", + }, + }, + ]); + expect(entry("capture-process").source).toEqual({ kind: "host" }); + expect(entry("capture-process").operations).toEqual([ + { name: "capture_process_scenario", flags: {} }, + ]); }); }); diff --git a/tests/boundary/cli/cliContractAliases.ts b/tests/boundary/cli/cliContractAliases.ts deleted file mode 100644 index e15b0556da..0000000000 --- a/tests/boundary/cli/cliContractAliases.ts +++ /dev/null @@ -1,17 +0,0 @@ -/** Canonical MCP operations reached by CLI commands with different names. */ -export const CLI_COMMAND_TOOL_ALIASES = Object.freeze({ - "environment-build": ["export_environment_bundle"], - guidance: ["search_guidance", "read_guidance_section"], - analyze: ["binary_overview"], - inspect: ["binary_overview"], - decompile: ["procedure_pseudo_code"], - function: ["analyze_function"], - instructions: ["read_function_instructions"], - trace: ["trace_feature"], - search: ["search_strings", "search_procedures"], - "capture-process": ["capture_process_scenario"], - compare: ["compare_bundles"], - "list-objdump-architectures": ["inspect_with_objdump"], - "debug-with-gdb": ["gdb_console"], - "debug-with-rizin": ["rizin_debug_command"], -}); diff --git a/tests/boundary/cli/cliContractSchemaParity.test.ts b/tests/boundary/cli/cliContractSchemaParity.test.ts index 1134a2722c..9a79194711 100644 --- a/tests/boundary/cli/cliContractSchemaParity.test.ts +++ b/tests/boundary/cli/cliContractSchemaParity.test.ts @@ -1,11 +1,13 @@ import { readFileSync } from "node:fs"; -import { cliCommands } from "../../../src/cli/commandRegistry.js"; +import { + cliCommands, + commandOwnOperations, +} from "../../../src/cli/commandRegistry.js"; import { describe, expect, it } from "vitest"; import { z } from "zod"; import { createCli } from "../../../src/cli.js"; import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js"; -import { CLI_COMMAND_TOOL_ALIASES } from "./cliContractAliases.js"; /** * Report-only parity between each CLI command's own field schemas and the MCP @@ -184,10 +186,13 @@ const collectParity = () => { let compared = 0; let commandsCompared = 0; let unmatchedFields = 0; - for (const { name, definition: entry } of commands) { - const contractNames: readonly string[] = CLI_COMMAND_TOOL_ALIASES[ - name as keyof typeof CLI_COMMAND_TOOL_ALIASES - ] ?? [snake(name)]; + for (const command of commands) { + const { name, definition: entry } = command; + const ownOperations = commandOwnOperations(command); + const contractNames: readonly string[] = + ownOperations.length > 0 + ? ownOperations.map((operation) => operation.name) + : [snake(name)]; for (const contractName of contractNames) { const contract = contracts.get(contractName); if (contract === undefined) { diff --git a/tests/boundary/cli/cliContractSchemaParity.uncomparable.json b/tests/boundary/cli/cliContractSchemaParity.uncomparable.json index bce0cc09ae..c862abd3c0 100644 --- a/tests/boundary/cli/cliContractSchemaParity.uncomparable.json +++ b/tests/boundary/cli/cliContractSchemaParity.uncomparable.json @@ -8,7 +8,6 @@ "import-reference-source: no contract import_reference_source", "project-managed-application-graph: no object shape project_managed_application_graph", "compare-web-captures: no object shape compare_web_captures", - "validate-browser-scenario: no contract validate_browser_scenario", "guided-workflows: no object shape guided_workflows", "inspect-evidence-bundle: no contract inspect_evidence_bundle", "evidence-import: no contract evidence_import", diff --git a/tests/boundary/cli/cliToolCoverage.test.ts b/tests/boundary/cli/cliToolCoverage.test.ts index 44ff009e56..10150c6db2 100644 --- a/tests/boundary/cli/cliToolCoverage.test.ts +++ b/tests/boundary/cli/cliToolCoverage.test.ts @@ -2,26 +2,121 @@ import { describe, expect, it } from "vitest"; import { z } from "zod"; import { createCli } from "../../../src/cli.js"; -import { cliCommands } from "../../../src/cli/commandRegistry.js"; +import { + cliCommands, + commandOwnOperations, + type CliCommandEntry, +} from "../../../src/cli/commandRegistry.js"; +import { optionFlagName } from "../../../src/cli/optionFields.js"; import { createCliInventory } from "../../../scripts/lib/catalog-cli.mjs"; import { TOOL_CONTRACTS } from "../../../src/contracts/toolContracts.js"; +import { cliCommandFor } from "../../../src/contracts/cliCommandNames.js"; import { CLI_COMMAND_NAMES, cliCommandNames, } from "../../../src/contracts/catalog/catalogIdentity.js"; import { describeContractCommand } from "../../../src/cli/contractCliDescription.js"; -import { CLI_COMMAND_TOOL_ALIASES } from "./cliContractAliases.js"; +const coverageViolations = ( + entries: readonly CliCommandEntry[], + contracts: readonly { readonly name: string; readonly cli?: boolean }[], +): readonly string[] => { + const violations: string[] = []; + const contractNames = new Set(contracts.map(({ name }) => name)); + const byName = new Map(entries.map((entry) => [entry.name, entry])); + + for (const contract of contracts) { + if (contract.cli !== true) continue; + const command = cliCommandFor(contract.name); + const entry = byName.get(command); + if (entry === undefined) { + violations.push(`missing CLI command ${command} for ${contract.name}`); + continue; + } + if (!commandOwnOperations(entry).some(({ name }) => name === contract.name)) + violations.push( + `command ${command} does not bind primary operation ${contract.name}`, + ); + } + + for (const entry of entries) { + const optionKeys = + entry.definition.options === undefined + ? [] + : Object.keys(entry.definition.options.shape); + const validFlags = new Set( + optionKeys.map((key) => `--${optionFlagName(key)}`), + ); + for (const operation of entry.operations) { + if (!contractNames.has(operation.name)) + violations.push( + `command ${entry.name} binds unknown contract ${operation.name}`, + ); + for (const [field, flag] of Object.entries(operation.flags)) { + if (!validFlags.has(flag)) + violations.push( + `command ${entry.name} binds ${operation.name}.${field} to undeclared flag ${flag}`, + ); + } + } + } + return violations; +}; describe("CLI canonical tool coverage", () => { - it("registers every derived command and every alias of an MCP tool", () => { - const registered = createCliInventory(cliCommands(createCli())); + it("registers every derived command and binds every command operation and flag to its contract", () => { + const entries = cliCommands(createCli()); + const registered = createCliInventory(entries); expect(registered.primary).toEqual([...CLI_COMMAND_NAMES].sort()); - const names = new Set(TOOL_CONTRACTS.map(({ name }) => name)); - for (const [command, tools] of Object.entries(CLI_COMMAND_TOOL_ALIASES)) { - expect(registered.primary).toContain(command); - for (const tool of tools) expect(names.has(tool)).toBe(true); - } + expect(coverageViolations(entries, TOOL_CONTRACTS)).toEqual([]); + + const aliasedCommands = entries.filter((entry) => { + const own = commandOwnOperations(entry); + return ( + own.length > 0 && + own.every(({ name }) => cliCommandFor(name) !== entry.name) + ); + }); + expect(aliasedCommands.length).toBeGreaterThanOrEqual(14); + }); + + it("rejects an unmapped cli: true contract or invalid operation/flag registration", () => { + const entries = cliCommands(createCli()); + expect( + coverageViolations(entries, [ + ...TOOL_CONTRACTS, + { name: "inspect_unmapped_probe", cli: true }, + ]), + ).toEqual([ + "missing CLI command inspect-unmapped-probe for inspect_unmapped_probe", + ]); + const withoutBinding = entries.map((entry) => + entry.name === "inspect-plist" ? { ...entry, operations: [] } : entry, + ); + expect(coverageViolations(withoutBinding, TOOL_CONTRACTS)).toEqual([ + "command inspect-plist does not bind primary operation inspect_plist", + ]); + const withoutRoutedBinding = entries.map((entry) => + entry.name === "compare-web-captures" + ? { ...entry, operations: [] } + : entry, + ); + expect(coverageViolations(withoutRoutedBinding, TOOL_CONTRACTS)).toEqual([ + "command compare-web-captures does not bind primary operation compare_web_captures", + ]); + const badFlag = entries.map((entry) => + entry.name === "guidance" + ? { + ...entry, + operations: [ + { name: "search_guidance", flags: { query: "--nonexistent" } }, + ], + } + : entry, + ); + expect(coverageViolations(badFlag, TOOL_CONTRACTS)).toEqual([ + "command guidance binds search_guidance.query to undeclared flag --nonexistent", + ]); }); it("names a contract's command from its declaration alone", () => {