refactor(cli): project WASM inspection and firmware commands from their contracts (#10648)

* refactor(cli): project WASM inspection and firmware commands from their contracts

The contract command description gains lists of caller paths and optional object fields flattened into one option per member. inspect-wasm-artifact, inspect-firmware-regions and extract-firmware are derived from their contracts. extract-firmware now records the caller's output_directory spelling in Evidence, like every other caller-path field.

* refactor(cli): project Apple bundle commands onto a declared session target (#10656)

Session-scoped operations take their target from the MCP session, so the CLI's target positional is not a contract field. The contract command description declares a session target: the CLI takes it as the first positional, opens it through runProviderAnalysis as the hand-written commands did, and passes the rest of the contract input. Input issues reported after argv parsing name renamed fields by their CLI key. inspect-keyed-archive, trace-dylib-resolution, inspect-asset-catalog and decode-interface-builder are the pilot; trace-dylib-resolution --root now admits only the roots its contract admits.
This commit is contained in:
morluto authored and GitHub committed 2026-11-15 17:45:33 +08:00
1 parent 26520bd290
commit a761efda70
9 files changed
+592 -404

No files matched your search

+65 -12
View File
@@ -4,7 +4,9 @@ import type { Logger } from "pino";
import { logCliCommand } from "../cliLogging.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import type { DirectAnalysis } from "../composition/directAnalysis.js";
import type { CallerInputPaths, Evidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import type { Result } from "../domain/result.js";
import { deliverCliAnalysisEvidence } from "./analysisEvidenceDelivery.js";
import { finishCliEvidenceCommand } from "./cliEvidenceCallerPath.js";
@@ -39,7 +41,14 @@ export interface ContractCommandContext<
/** The contract name, which is the canonical operation. */
readonly operation: string;
/** Each caller-path field as the caller spelled it, before resolution. */
readonly callerInputs: Readonly<Record<string, string>>;
readonly callerInputs: CallerInputPaths;
/**
* The session target as the caller spelled it, for a projection with
* `sessionTarget`; undefined otherwise.
*/
readonly sessionTarget: string | undefined;
/** Contract fields the CLI spells differently, for input issue paths. */
readonly inputBinding: ContractCliDescription["inputBinding"];
/** The admitted delivery, for a projection with `evidenceDelivery`. */
readonly delivery: CliEvidenceDeliveryChoice | undefined;
/** The projection's CLI-only options, whose effect the handler owns. */
@@ -55,22 +64,30 @@ export interface EvidenceInspectionService {
close(): Promise<void>;
}
/** The caller's spelling of the selected target `path`. */
export const callerTargetPath = ({
operation,
callerInputs,
}: ContractCommandContext): string => {
const { path } = callerInputs;
if (typeof path !== "string")
throw new Error(`${operation} has no caller path field named path`);
return path;
};
/**
* The caller's spelling of `path`, and of each other caller-path field keyed
* by its contract field name.
*/
const callerSpellings = ({
operation,
callerInputs,
}: ContractCommandContext): {
const callerSpellings = (
context: ContractCommandContext,
): {
readonly path: string;
readonly others: CallerInputPaths | undefined;
} => {
const { path, ...others } = callerInputs;
if (path === undefined)
throw new Error(`${operation} has no caller path field named path`);
const { path: _path, ...others } = context.callerInputs;
return {
path,
path: callerTargetPath(context),
others: Object.keys(others).length === 0 ? undefined : others,
};
};
@@ -95,6 +112,34 @@ export const inspectWithService =
).then(projectCliAnalysisResult);
};
/**
* Open the session target as an MCP session would hold it, run the contract
* operation on the remaining input, and name renamed fields by their CLI key
* in input issues.
*/
export const runOnSessionTarget =
(
runProviderAnalysis: DirectAnalysis["runProviderAnalysis"],
logger: Logger,
) =>
(input: object, context: ContractCommandContext) => {
if (context.sessionTarget === undefined)
throw new Error(`${context.operation} declares no session target`);
return runProviderAnalysis(
context.sessionTarget,
context.operation as SessionTargetOperation,
// Argv values are decoded text, and absent options are left out.
input as Readonly<Record<string, JsonValue>>,
logger,
context.signal,
).then((result) => projectCliAnalysisResult(result, context.inputBinding));
};
/** Operations `runProviderAnalysis` runs on an opened session target. */
type SessionTargetOperation = Parameters<
DirectAnalysis["runProviderAnalysis"]
>[1];
/**
* Run an analysis that selects no target path through a closeable service
* and finish its cleanup.
@@ -193,9 +238,12 @@ export const registerContractCommand = <
) => Promise<Value>,
): void => {
const description = describeContractCommand(contract, projection);
const positionals = description.parameters.filter(
({ positional }) => positional,
);
const positionals = [
...(description.sessionTarget === undefined
? []
: [description.sessionTarget]),
...description.parameters.filter(({ positional }) => positional),
];
const alias = Object.fromEntries(
description.parameters.flatMap(({ key, alias: short, positional }) =>
short === undefined || positional ? [] : [[key, short]],
@@ -230,6 +278,11 @@ export const registerContractCommand = <
signal,
operation: contract.name,
callerInputs: description.callerInputs(values),
sessionTarget:
description.sessionTarget === undefined
? undefined
: (values[description.sessionTarget.key] as string),
inputBinding: description.inputBinding,
delivery: admitted.value.delivery,
cliOptions: description.cliOptionValues(
values,