Files
reverse-engineering-anything/src/cli/contractCommand.ts
T
morluto b51ed4c3ec refactor(kernel): migrate the remaining SHA-256 hex digests to sha256Hex and move isRecord into src/kernel (#11571)
* refactor(kernel): migrate the remaining one-shot SHA-256 hex digests to sha256Hex

* refactor(kernel): move isRecord into src/kernel and replace its inline copies (#11574)

* fix(scripts): import isRecord from src/kernel in the managed manifest parser
2026-11-15 20:53:36 -05:00

1357 lines
48 KiB
TypeScript

import { z } from "incur";
import { invariantViolation } from "../domain/internalInvariant.js";
import type { Logger } from "pino";
import { logCliCommand } from "../cliLogging.js";
import type { AnalysisError } from "../domain/analysisErrorBase.js";
import {
AnalysisInputError,
AnalysisOutputError,
} from "../domain/analysisErrorCore.js";
import type { AnalysisProviderSelector } from "../domain/providerSelection.js";
import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
import type { DirectAnalysis } from "../composition/directAnalysis.js";
import type { CallerInputPaths, Evidence } from "../domain/evidence.js";
import type { JsonValue } from "../domain/jsonValue.js";
import { err, ok, type Result } from "../domain/result.js";
import type { ArtifactAnalysisOperation } from "../contracts/artifactToolContracts.js";
import { openBinaryTargetSelection } from "../contracts/sessionLifecycleInputs.js";
import {
deliverCliAnalysisEvidence,
publishCliAnalysisEvidence,
} from "./analysisEvidenceDelivery.js";
import { finishCliEvidenceCommand } from "./cliEvidenceCallerPath.js";
import { finishAnalysisCommand } from "./finishAnalysisCommand.js";
import { withCommandCancellation } from "./commandCancellation.js";
import { dispatchQueuedInterrupts } from "../process/queuedInterrupts.js";
import { finalizedResult, runOwned } from "../providers/runOwned.js";
import { parseCliJsonInput, resolveCliJsonPaths } from "./cliJsonInput.js";
import { jsonInputArgument } from "./jsonInputArgument.js";
import {
describeContractCommand,
describeContractDocumentCommand,
type CliDocumentProjection,
type DocumentContract,
type ContractCliDocumentDescription,
type CliContractProjection,
describeOperationChoices,
type CliEvidenceDeliveryChoice,
type CliOptionShape,
type CliOptionValues,
type ContractCliDescription,
type ContractCliEvidenceTargets,
type ContractCliSessionTarget,
type ContractField,
type ProjectedContract,
type CliCheckedJsonInputs,
type CliJsonInputCheck,
withoutDefault,
} from "./contractCliDescription.js";
import {
cliDeliveredEvidence,
recordCliResultControls,
} from "./cliResultControls.js";
import {
cliResultControlsIn,
failurePartialObservation,
projectCliAnalysisResult,
projectCliInputFields,
} from "./projectCliAnalysisResult.js";
import type { CliInstance } from "./types.js";
import { isRecord } from "../kernel/isRecord.js";
/**
* Incur adapter for contract commands. The command itself is described in
* `contractCliDescription.ts`; this module only renders that description as
* Incur args and options and runs the handler.
*/
/** What a contract command's handler receives besides the contract input. */
export interface ContractCommandContext<
CliOptions extends Readonly<Record<string, unknown>> = Readonly<
Record<string, unknown>
>,
Parsed = unknown,
Checked extends Readonly<Record<string, unknown>> = Readonly<
Record<string, unknown>
>,
> {
readonly signal: AbortSignal;
/** The contract name, which is the canonical operation. */
readonly operation: string;
/** Each caller-path field as the caller spelled it, before resolution. */
readonly callerInputs: CallerInputPaths;
/**
* The session target as the caller spelled it, for a projection with
* `sessionTarget`; undefined otherwise.
*/
readonly sessionTarget: string | undefined;
/**
* The source contract and each Evidence target as the caller spelled it,
* in argv order, for a projection with `evidenceTargets`; undefined
* otherwise.
*/
readonly evidenceTargets: CliEvidenceTargetSelection | undefined;
/**
* The session target's opening fields, or the Evidence targets' source
* fields, the caller selected, in that contract's spelling; empty when the
* projection declares none.
*/
readonly opening: Readonly<Record<string, unknown>>;
/** The admitted delivery, for a projection with `evidenceDelivery`. */
readonly delivery: CliEvidenceDeliveryChoice | undefined;
/**
* The contract's parse of the input, when admission parsed the whole
* input: the projection decodes JSON at run time, or argv supplies every
* contract field. Undefined when a session target, Evidence target or the
* handler supplies part of the input.
*/
readonly parsed: Parsed | undefined;
/**
* The contract's parse of an argv-supplied whole input, or its refusal,
* which the handler reports in its own workflow's shape. It parses on
* first call and reuses the result; undefined when argv does not supply
* the whole input. Read it through `admittedContractInput`.
*/
readonly parseWholeInput:
| (() => Result<Parsed, AnalysisInputError>)
| undefined;
/** What each `jsonInputChecks` check admitted, by contract field. */
readonly checked: Checked;
/** The projection's CLI-only options, whose effect the handler owns. */
readonly cliOptions: CliOptions;
}
/**
* The contract's parse of a projection whose admission parses the whole
* input, or its refusal. Neither means the projection supplies part of the
* input elsewhere, which is a defect in that command's registration.
*/
export const admittedContractInput = <Parsed>(context: {
readonly operation: string;
readonly parsed: Parsed | undefined;
readonly parseWholeInput:
| (() => Result<Parsed, AnalysisInputError>)
| undefined;
}): Result<Parsed, AnalysisInputError> => {
if (context.parsed !== undefined) return ok(context.parsed);
if (context.parseWholeInput === undefined)
throw invariantViolation(
`${context.operation} does not admit its whole contract input on the CLI`,
);
return context.parseWholeInput();
};
/** The Evidence targets one invocation selected. */
export interface CliEvidenceTargetSelection {
/** The source contract each target runs. */
readonly source: string;
/** Source contract fields this command takes as options, with their flags. */
readonly sourceFlags: Readonly<Record<string, string>>;
readonly targets: readonly {
/** The contract field the target's source Evidence supplies. */
readonly field: string;
/** The target's positional key. */
readonly key: string;
/** The target as the caller spelled it. */
readonly target: string;
}[];
}
/** A closeable one-shot service that inspects one contract input. */
export interface EvidenceInspectionService {
inspect(
input: unknown,
options: { readonly signal: AbortSignal },
): Promise<Result<Evidence, AnalysisError>>;
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 the primary caller-path field (`path` unless the
* command names another), and of each other caller-path field keyed by its
* contract field name.
*/
const callerSpellings = (
context: ContractCommandContext,
primary = "path",
): {
readonly path: string;
readonly others: CallerInputPaths | undefined;
} => {
const { [primary]: path, ...others } = context.callerInputs;
if (typeof path !== "string")
throw new Error(
`${context.operation} has no caller path field named ${primary}`,
);
return {
path,
others: Object.keys(others).length === 0 ? undefined : others,
};
};
/**
* Inspect through a closeable service, finish its cleanup, and record the
* caller's spelling of each selected path in the Evidence; `primary` names
* the contract field recorded as the Evidence's caller input path.
*/
export const inspectWithService =
(
service: () => EvidenceInspectionService,
providerId: string,
primary = "path",
) =>
(input: unknown, context: ContractCommandContext) => {
const spellings = callerSpellings(context, primary);
const owned = service();
return finishCliEvidenceCommand(
spellings.path,
() => owned.inspect(input, { signal: context.signal }),
owned,
providerId,
context.operation,
context.signal,
spellings.others,
).then(projectCliAnalysisResult);
};
/**
* Open the session target as an MCP session would hold it, with the opening
* fields the caller selected, and run the contract operation on the
* remaining input. A projection with `evidenceDelivery` delivers complete
* Evidence or a summary beside its bundle.
*/
export const runOnSessionTarget =
(
runProviderAnalysis: DirectAnalysis["runProviderAnalysis"],
logger: Logger,
) =>
async (input: object, context: ContractCommandContext) => {
const { sessionTarget, operation, signal, delivery, opening } = context;
if (sessionTarget === undefined)
throw new Error(`${operation} declares no session target`);
// Argv values are decoded text, and absent options are left out.
const values = input as Readonly<Record<string, JsonValue>>;
const result = await (Object.keys(opening).length === 0
? runProviderAnalysis(
sessionTarget,
operation as SessionTargetOperation,
values,
logger,
signal,
)
: runProviderAnalysis(
sessionTarget,
// Only artifact operations take an opening selection.
operation as ArtifactAnalysisOperation,
values,
logger,
signal,
openBinaryTargetSelection(opening),
));
if (delivery === undefined) return projectCliAnalysisResult(result);
return publishCliAnalysisEvidence(result, {
operation,
signal,
detail: delivery.detail,
evidenceOutput: delivery.evidenceOutput,
...(delivery.view === undefined ? {} : { view: delivery.view }),
});
};
/** Operations `runProviderAnalysis` runs on an opened session target. */
type SessionTargetOperation = Parameters<
DirectAnalysis["runProviderAnalysis"]
>[1];
/** Operations `runDirectAnalysis` runs on a target it opens. */
type DirectAnalysisOperation = Parameters<
DirectAnalysis["runDirectAnalysis"]
>[1];
/**
* The one-shot open the caller selected with `open_binary` fields: its
* target interpretation, provider and analysis snapshot.
*/
const directAnalysisOpening = ({
provider_id: providerId,
snapshot_path: snapshotPath,
...selection
}: Readonly<Record<string, unknown>>) => ({
...openBinaryTargetSelection(selection),
...(providerId === undefined
? {}
: { providerId: providerId as AnalysisProviderSelector }),
...(snapshotPath === undefined
? {}
: { snapshotPath: snapshotPath as string }),
});
/**
* Open the session target for one operation with the `open_binary` fields
* the caller selected, run it, and release the provider. A projection with
* `evidenceDelivery` delivers complete Evidence or a summary beside its
* bundle. `requireSourceEvidence` refuses a bundle whose composed result did
* not return the source Evidence it cites.
*/
export const runDirectOnTarget =
(
runDirectAnalysis: DirectAnalysis["runDirectAnalysis"],
logger: Logger,
options: { readonly requireSourceEvidence?: true } = {},
) =>
async (input: object, context: ContractCommandContext) => {
const { sessionTarget, operation, signal, delivery, opening } = context;
if (sessionTarget === undefined)
throw new Error(`${operation} declares no session target`);
const evidenceOutput = delivery?.evidenceOutput;
const result = await runDirectAnalysis(
sessionTarget,
operation as DirectAnalysisOperation,
// Argv values are decoded text, and absent options are left out.
input as Readonly<Record<string, JsonValue>>,
{
logger,
signal,
...directAnalysisOpening(opening),
...(evidenceOutput === undefined
? {}
: { includeEvidenceSources: true }),
},
);
if (delivery === undefined) return projectCliAnalysisResult(result);
if (
options.requireSourceEvidence === true &&
result.ok &&
evidenceOutput !== undefined &&
result.sourceEvidence === undefined
)
return projectAnalysisError(
new AnalysisOutputError(
operation,
"The CLI session did not return its source Evidence.",
).retainPartialObservation(result.value),
);
return publishCliAnalysisEvidence(result, {
operation,
signal,
detail: delivery.detail,
evidenceOutput,
});
};
/**
* A command's output named for the CLI: renamed issue paths and failure
* flags (`projectCliInputFields`), and the flags of controls its result
* records, which the CLI renders in its own envelope.
*/
const projectCliResult = <Output>(
output: Output,
outputSchema: z.ZodType | undefined,
binding: Parameters<typeof projectCliInputFields>[1],
): Output => {
// A command without flags, or without a result schema that declares
// recorded controls, has no control to render.
if (outputSchema !== undefined && Object.keys(binding.flags).length > 0)
recordCliResultControls(() =>
// A wrapped delivery recorded its complete Evidence, which the
// contract's output schema describes; so does a failure's partial
// Evidence of the same operation.
cliResultControlsIn(
cliDeliveredEvidence() ??
failurePartialObservation(output, binding.operation) ??
output,
outputSchema,
binding,
),
);
return projectCliInputFields(output, binding);
};
/**
* Run the source contract on each Evidence target in argv order with the
* source fields the caller selected, then compose the contract from that
* Evidence. A target's failure names its positional; any failure retains
* each completed target's Evidence under its contract field beside the
* failure's own partial observation.
*/
export const runOnEvidenceTargets =
(
runSource: (
target: string,
parameters: Readonly<Record<string, JsonValue>>,
signal: AbortSignal,
) => Promise<Result<Evidence, AnalysisError>>,
compose: (
input: Readonly<Record<string, unknown>>,
context: ContractCommandContext & {
readonly evidenceTargets: CliEvidenceTargetSelection;
},
) => Promise<Result<Evidence, AnalysisError>>,
) =>
async (input: object, context: ContractCommandContext) => {
const { evidenceTargets, operation, signal } = context;
if (evidenceTargets === undefined)
throw new Error(`${operation} declares no Evidence targets`);
// Argv values are decoded text, and absent options are left out.
const parameters = context.opening as Readonly<Record<string, JsonValue>>;
const sources: Record<string, Evidence> = {};
const retainSources = (failure: AnalysisError) => {
for (const [field, evidence] of Object.entries(sources))
failure.retainArgumentObservation(field, evidence);
return failure;
};
for (const { field, key, target } of evidenceTargets.targets) {
const source = await runSource(target, parameters, signal);
if (!source.ok)
return projectCliInputFields(
{
error: "Analysis failed",
...projectAnalysisError(retainSources(source.error), "invocation"),
},
{
operation: evidenceTargets.source,
fields: { path: key },
flags: evidenceTargets.sourceFlags,
},
);
sources[field] = source.value;
}
// A cancellation that arrives as the composition settles keeps its
// most complete Evidence. The composition owns no resource of its own,
// so its close only lets queued interrupts reach the signal first.
const result = finalizedResult(
await runOwned(
async (): Promise<Result<Evidence, AnalysisError>> => {
try {
return await compose(
{ ...input, ...sources },
{ ...context, evidenceTargets },
);
} catch (cause: unknown) {
// The completed source Evidence outlives a defect in the composition.
return {
ok: false,
error: new AnalysisOutputError(
operation,
`${operation} produced invalid output`,
{ cause },
),
};
}
},
{
providerId: evidenceTargets.source,
operation,
signal,
close: dispatchQueuedInterrupts,
partial: (value) => value,
},
),
);
if (result.ok) return result.value;
return {
error: "Analysis failed",
...projectAnalysisError(retainSources(result.error), "invocation"),
};
};
/**
* Run an analysis that selects no target path through a closeable service
* and finish its cleanup.
*/
export const analyzeWithService =
(service: () => EvidenceInspectionService, providerId: string) =>
(input: unknown, context: ContractCommandContext) => {
if (Object.keys(context.callerInputs).length > 0)
throw new Error(`${context.operation} selects a caller path`);
const owned = service();
return finishAnalysisCommand(
() => owned.inspect(input, { signal: context.signal }),
owned,
providerId,
context.operation,
context.signal,
).then(projectCliAnalysisResult);
};
/**
* Inspect through a closeable service, then deliver complete Evidence or a
* summary with its bundle, recording the caller's spelling of each selected
* path.
*/
export const deliverWithService =
(service: () => EvidenceInspectionService, providerId: string) =>
(input: unknown, context: ContractCommandContext) => {
const spellings = callerSpellings(context);
const { delivery } = context;
if (delivery === undefined)
throw new Error(`${context.operation} does not declare evidenceDelivery`);
const owned = service();
return deliverCliAnalysisEvidence({
callerInputPath: spellings.path,
...(spellings.others === undefined
? {}
: { callerInputPaths: spellings.others }),
run: () => owned.inspect(input, { signal: context.signal }),
service: owned,
providerId,
operation: context.operation,
signal: context.signal,
detail: delivery.detail,
evidenceOutput: delivery.evidenceOutput,
...(delivery.view === undefined ? {} : { view: delivery.view }),
});
};
/**
* The session target's opening fields, or the Evidence targets' source
* fields, when the command declares any.
*/
const admitOpening = (
description: {
readonly contract: { readonly name: string };
readonly sessionTarget: ContractCliSessionTarget | undefined;
readonly evidenceTargets?: ContractCliEvidenceTargets | undefined;
},
values: Readonly<Record<string, unknown>>,
): Result<Readonly<Record<string, unknown>>, AnalysisError> =>
description.sessionTarget !== undefined
? description.sessionTarget.admitOpening(description.contract.name, values)
: description.evidenceTargets !== undefined
? description.evidenceTargets.admitSource(
description.contract.name,
values,
)
: { ok: true, value: {} };
/** Target positionals, the contract's own, then CLI-only ones, in argv order. */
const commandPositionals = (
description: ContractCliDescription,
): readonly { readonly key: string; readonly schema: z.ZodType }[] => [
...(description.sessionTarget === undefined
? []
: [description.sessionTarget]),
...(description.evidenceTargets?.targets ?? []),
...description.parameters.filter(({ positional }) => positional),
...description.cliPositionals,
];
const descriptions = new WeakMap<CliInstance, ContractCliDescription[]>();
/** Commands registered on this CLI through `registerContractCommand`. */
export const contractCommandDescriptions = (
cli: CliInstance,
): readonly ContractCliDescription[] => descriptions.get(cli) ?? [];
const incurOptions = (description: ContractCliDescription): z.ZodType => {
const object = z.object(
Object.fromEntries([
...description.parameters
.filter(({ positional }) => !positional)
.map(({ key, schema }) => [key, schema] as const),
...[
...(description.sessionTarget?.options ?? []),
...(description.evidenceTargets?.options ?? []),
].map(({ key, schema }) => [key, schema] as const),
...description.cliOnlyOptions.map(
({ key, schema }) => [key, schema] as const,
),
...description.parameters.flatMap(({ selectorOption }) =>
[selectorOption, selectorOption?.alternative].flatMap((option) =>
option === undefined ? [] : [[option.key, option.schema] as const],
),
),
]),
);
const constrained =
description.optionConstraints === undefined
? object
: object.meta(description.optionConstraints);
const { checkOptions } = description;
return checkOptions === undefined
? constrained
: constrained.superRefine((parsed, context) => {
for (const { path, issue } of checkOptions(parsed))
context.addIssue({ ...issue, path: [...path] } as never);
});
};
/**
* Register one CLI command described from a tool contract. The handler
* receives the contract input, with caller paths made absolute.
*/
export const registerContractCommand = <
Contract extends ProjectedContract,
Value,
CliOptions extends CliOptionShape = Record<never, z.ZodType>,
Checks extends {
readonly [Key in ContractField<Contract>]?: CliJsonInputCheck;
} = Record<never, CliJsonInputCheck>,
>(
cli: CliInstance,
logger: Logger,
contract: Contract,
projection: CliContractProjection<ContractField<Contract>, CliOptions> & {
readonly jsonInputChecks?: Checks;
},
run: (
input: z.input<Contract["inputSchema"]>,
context: ContractCommandContext<
CliOptionValues<CliOptions>,
z.output<Contract["inputSchema"]>,
CliCheckedJsonInputs<Checks>
>,
) => Promise<Value>,
): void => {
const description = describeContractCommand(contract, projection);
const chosen = describeOperationChoices(description, projection);
const positionals = commandPositionals(description);
const alias = Object.fromEntries(
description.parameters.flatMap(({ key, alias: short, positional }) =>
short === undefined || positional ? [] : [[key, short]],
),
);
cli.command(description.command, {
description: description.description,
...(positionals.length === 0
? {}
: {
args: z.object(
Object.fromEntries(
positionals.map(({ key, schema }) => [key, schema]),
),
),
}),
options: incurOptions(description),
...(Object.keys(alias).length === 0 ? {} : { alias }),
run: ({
args,
options,
}: {
readonly args?: Readonly<Record<string, unknown>>;
readonly options: Readonly<Record<string, unknown>>;
}) => {
const values: Record<string, unknown> = { ...options, ...args };
// A selector's positional and named option may share one key.
for (const { key, selectorOption } of description.parameters)
if (selectorOption !== undefined) {
values[key] = args?.[key];
for (const option of [selectorOption, selectorOption.alternative])
if (option !== undefined)
values[option.valueKey] = options[option.key];
}
const selected =
projection.operationBy === undefined
? description
: (chosen.get(values[projection.operationBy.option]) ?? description);
return withCommandCancellation((signal) =>
logCliCommand(logger, description.command, async () => {
const options = selected.admitDeliveryOptions(values);
if (!options.ok) return projectAnalysisError(options.error);
const read = await readJsonInputs(selected, values, signal);
if (!read.ok) return read.error;
const admitted = selected.admit(read.value);
// Admission and handler issues alike name renamed fields by CLI key.
if (!admitted.ok)
return projectCliInputFields(
projectAnalysisError(admitted.error),
selected.inputBinding,
);
const opening = admitOpening(selected, values);
if (!opening.ok) return projectAnalysisError(opening.error);
// A composed command also takes its sources' options; a control
// its result records from a source is set by that option.
const resultBinding =
description.evidenceTargets === undefined
? selected.inputBinding
: {
...selected.inputBinding,
flags: {
...description.evidenceTargets.sourceFlags,
...selected.inputBinding.flags,
},
};
return projectCliResult(
await run(
admitted.value.input as z.input<Contract["inputSchema"]>,
{
signal,
operation: selected.contract.name,
callerInputs: selected.callerInputs(values),
sessionTarget:
description.sessionTarget === undefined
? undefined
: (values[description.sessionTarget.key] as string),
evidenceTargets:
description.evidenceTargets === undefined
? undefined
: {
source: description.evidenceTargets.source,
sourceFlags: description.evidenceTargets.sourceFlags,
targets: description.evidenceTargets.targets.map(
({ field, key }) => ({
field,
key,
target: values[key] as string,
}),
),
},
opening: opening.value,
delivery: admitted.value.delivery,
parsed: admitted.value.parsed as
| z.output<Contract["inputSchema"]>
| undefined,
parseWholeInput: admitted.value.parseWholeInput as
| (() => Result<
z.output<Contract["inputSchema"]>,
AnalysisInputError
>)
| undefined,
checked: read.checked as CliCheckedJsonInputs<Checks>,
cliOptions: selected.cliOptionValues(
values,
) as CliOptionValues<CliOptions>,
},
),
selected.contract.outputSchema,
resultBinding,
);
}),
);
},
} as never);
const registered = descriptions.get(cli) ?? [];
registered.push(description);
descriptions.set(cli, registered);
};
/** One contract input a routed command runs, with the inputs it takes. */
export interface CliCommandRoute {
readonly description: ContractCliDescription;
/**
* Whether this route takes the given input. Only a route that owns every
* option the caller gave is asked; the last route takes every other input.
*/
readonly takes: ((values: RouteValues) => Promise<boolean>) | undefined;
/**
* What this route's input is, named when an option the caller gave belongs
* to another route.
*/
readonly requirement: string;
readonly run: (
input: unknown,
context: ContractCommandContext,
) => Promise<unknown>;
}
/**
* The parsed arguments and options of a routed command, keyed by CLI key.
* JSON inputs that every route takes are already decoded, so a route can be
* chosen by document content.
*/
export type RouteValues = Readonly<Record<string, unknown>>;
/** Describe one route of a routed command from its contract input. */
export const commandRoute = <
Contract extends ProjectedContract,
CliOptions extends CliOptionShape = Record<never, z.ZodType>,
>(
contract: Contract,
projection: CliContractProjection<ContractField<Contract>, CliOptions>,
run: (
input: z.input<Contract["inputSchema"]>,
context: ContractCommandContext<
CliOptionValues<CliOptions>,
z.output<Contract["inputSchema"]>
>,
) => Promise<unknown>,
route: {
readonly takes?: (values: RouteValues) => Promise<boolean>;
readonly requirement: string;
},
): CliCommandRoute => {
if (projection.operationBy !== undefined)
throw new Error(`${contract.name} routes by target and by an option`);
return {
description: describeContractCommand(contract, projection),
takes: route.takes,
requirement: route.requirement,
run: run as CliCommandRoute["run"],
};
};
/**
* The input shape of a union contract that has `field`, as a contract a
* route can project: the same operation, admitted by that shape alone.
*/
export const contractInputBranch = <
Name extends string,
Branches extends readonly z.ZodObject[],
Field extends string,
>(
contract: {
readonly name: Name;
readonly cli?: true;
readonly inputSchema: z.ZodUnion<Branches>;
},
field: Field,
): {
readonly name: Name;
readonly cli?: true;
readonly inputSchema: Extract<
Branches[number],
{ readonly shape: { readonly [Key in Field]: z.ZodType } }
>;
} => {
const branches = contract.inputSchema.options.filter((branch) =>
Object.hasOwn(branch.shape, field),
);
if (branches.length !== 1)
throw new Error(`${contract.name} has no single input shape with ${field}`);
return {
name: contract.name,
...(contract.cli === undefined ? {} : { cli: contract.cli }),
inputSchema: branches[0] as Extract<
Branches[number],
{ readonly shape: { readonly [Key in Field]: z.ZodType } }
>,
};
};
/** The argv arguments and options one description takes, keyed by CLI key. */
const commandShape = (description: ContractCliDescription) => ({
args: commandPositionals(description).map(
({ key, schema }) => [key, schema] as const,
),
// Routed descriptions declare no object-level rules, so this is the object.
options: Object.fromEntries(
Object.entries(
(incurOptions(description) as z.ZodObject).shape as Readonly<
Record<string, z.ZodType>
>,
).map(([key, schema]) => [key, withoutDefault(schema)]),
),
});
const schemaSignature = (schema: z.ZodType): string =>
JSON.stringify(z.toJSONSchema(schema, { unrepresentable: "any" }));
const routedDescriptions = new WeakMap<CliInstance, ContractCliDescription[]>();
/** Route descriptions of commands registered through `registerRoutedCommand`. */
export const routedCommandDescriptions = (
cli: CliInstance,
): readonly ContractCliDescription[] => routedDescriptions.get(cli) ?? [];
/**
* Register one CLI command whose input chooses the contract input it runs,
* such as `analyze` running static JavaScript analysis on an application
* archive and the binary overview on a program, or `compare-web-captures`
* comparing recorded scenarios or passive captures by what the documents
* hold. Each route is projected from its own contract input; the command
* takes the union of their options, which must agree on every shared key.
* The first route that owns every given option and takes the input runs; an
* option the chosen route does not own is refused naming its CLI key and the
* route that takes it.
*/
export const registerRoutedCommand = (
cli: CliInstance,
logger: Logger,
command: { readonly description: string },
routes: readonly [...CliCommandRoute[], CliCommandRoute],
): void => {
// Every route projects the same command, which names itself or is the own
// command of one route's contract.
const name = routes[0]!.description.command;
const shapes = routes.map(({ description }) => {
if (
description.command !== name ||
description.optionConstraints !== undefined ||
description.checkOptions !== undefined ||
description.evidenceTargets !== undefined ||
description.parameters.some(
({ selectorOption }) => selectorOption !== undefined,
)
)
throw new Error(
`${description.contract.name} cannot be routed by ${name}`,
);
return commandShape(description);
});
const args = shapes[0]!.args;
const options = new Map<string, z.ZodType>();
const owners = new Map<string, CliCommandRoute>();
for (const [index, shape] of shapes.entries()) {
if (
shape.args.length !== args.length ||
shape.args.some(
([key, schema], position) =>
key !== args[position]![0] ||
schemaSignature(schema) !== schemaSignature(args[position]![1]),
)
)
throw new Error(`${name} routes take different arguments`);
for (const [key, schema] of Object.entries(shape.options)) {
const shared = options.get(key);
if (
shared !== undefined &&
schemaSignature(shared) !== schemaSignature(schema)
)
throw new Error(`${name} routes disagree on --${key}`);
options.set(key, schema);
owners.set(key, routes[index]!);
}
}
const owns = (route: CliCommandRoute, key: string): boolean =>
args.some(([argument]) => argument === key) ||
Object.hasOwn(shapes[routes.indexOf(route)]!.options, key);
// Only JSON inputs every route takes alike are decoded before routing.
const sharedJson = sharedJsonInputs(name, routes);
cli.command(name, {
description: command.description,
args: z.object(Object.fromEntries(args)),
options: z.object(Object.fromEntries(options)),
run: ({
args: given,
options: chosen,
}: {
readonly args: Readonly<Record<string, unknown>>;
readonly options: Readonly<Record<string, unknown>>;
}) => {
const values: Record<string, unknown> = { ...chosen, ...given };
const supplied = Object.keys(values).filter(
(key) => values[key] !== undefined,
);
return withCommandCancellation((signal) =>
logCliCommand(logger, name, async () => {
const shared = await readJsonInputs(
routes[0]!.description,
values,
signal,
sharedJson,
);
if (!shared.ok) return shared.error;
let route = routes.at(-1)!;
for (const candidate of routes)
if (
candidate.takes !== undefined &&
supplied.every((key) => owns(candidate, key)) &&
(await candidate.takes(shared.value))
) {
route = candidate;
break;
}
const { description } = route;
const refused = supplied.filter((key) => !owns(route, key));
if (refused.length > 0)
return projectAnalysisError(
new AnalysisInputError(
description.contract.name,
undefined,
refused.map((key) => ({
path: [key],
reason: "invalid_value" as const,
message: `--${kebabCase(key)} requires ${owners.get(key)!.requirement}; the given input selects ${route.requirement}, which does not take it.`,
})),
),
);
const options = description.admitDeliveryOptions(shared.value);
if (!options.ok) return projectAnalysisError(options.error);
const read = await readJsonInputs(
description,
shared.value,
signal,
ownJsonInputs(description, sharedJson),
);
if (!read.ok) return read.error;
const admitted = description.admit(read.value);
if (!admitted.ok)
return projectCliInputFields(
projectAnalysisError(admitted.error),
description.inputBinding,
);
const opening = admitOpening(description, values);
if (!opening.ok) return projectAnalysisError(opening.error);
return projectCliResult(
await route.run(admitted.value.input, {
signal,
operation: description.contract.name,
callerInputs: description.callerInputs(values),
sessionTarget:
description.sessionTarget === undefined
? undefined
: (values[description.sessionTarget.key] as string),
evidenceTargets: undefined,
opening: opening.value,
delivery: admitted.value.delivery,
parsed: admitted.value.parsed,
parseWholeInput: admitted.value.parseWholeInput,
checked: { ...shared.checked, ...read.checked },
cliOptions: description.cliOptionValues(
withCliOnlyDefaults(description, values),
),
}),
description.contract.outputSchema,
description.inputBinding,
);
}),
);
},
} as never);
const registered = routedDescriptions.get(cli) ?? [];
registered.push(...routes.map(({ description }) => description));
routedDescriptions.set(cli, registered);
};
/**
* Routing saw CLI-only options without their defaults; the chosen route's
* handler receives each omitted one's default, which no contract parse
* would otherwise restore.
*/
const withCliOnlyDefaults = (
description: ContractCliDescription,
values: Readonly<Record<string, unknown>>,
): Readonly<Record<string, unknown>> => ({
...values,
...Object.fromEntries(
description.cliOnlyOptions.flatMap(({ key, schema }) =>
values[key] === undefined ? [[key, schema.parse(undefined)]] : [],
),
),
});
const kebabCase = (key: string): string =>
key.replaceAll(/[A-Z]/gu, (letter) => `-${letter.toLowerCase()}`);
/** What a JSON-document command's handler receives besides the document. */
export interface ContractDocumentContext<
CliOptions extends Readonly<Record<string, unknown>> = Readonly<
Record<string, unknown>
>,
Parsed = unknown,
> {
readonly signal: AbortSignal;
/** The contract name, which is the canonical operation. */
readonly operation: string;
/** The document as decoded, before its caller paths were resolved. */
readonly spelled: unknown;
/** A document is never parsed at admission; see `parseWholeInput`. */
readonly parsed: undefined;
/**
* The contract's parse of the document, with caller paths resolved, as
* the whole contract input, or its refusal (issues name the caller's
* spelling). It parses on first call and reuses the result, so a handler
* whose document is not the whole input never parses it here. Read it
* through `admittedContractInput`.
*/
readonly parseWholeInput: () => Result<Parsed, AnalysisInputError>;
/**
* The document's transport frame as `--schema` advertises it. A handler
* that reads other inputs first, such as an Evidence bundle, admits the
* document with it beforehand; Evidence carriers stay with their owner.
*/
readonly frame: z.ZodType;
/** The admitted delivery, for a projection with `evidenceDelivery`. */
readonly delivery: CliEvidenceDeliveryChoice | undefined;
/** The projection's CLI-only options, whose effect the handler owns. */
readonly cliOptions: CliOptions;
/**
* The session target as the caller spelled it, for a projection with
* `sessionTarget`; undefined otherwise.
*/
readonly sessionTarget: string | undefined;
/**
* The session target's opening fields the caller selected, in the opening
* contract's spelling; empty without `sessionTarget.open`.
*/
readonly opening: Readonly<Record<string, unknown>>;
}
const documentDescriptions = new WeakMap<
CliInstance,
ContractCliDocumentDescription[]
>();
/** Commands registered on this CLI through `registerContractDocumentCommand`. */
export const contractDocumentCommandDescriptions = (
cli: CliInstance,
): readonly ContractCliDocumentDescription[] =>
documentDescriptions.get(cli) ?? [];
/**
* A document field the projection omits or takes as an option is refused
* with its reason rather than passed to an owner that would act on it.
*/
const refusedDocumentFieldError = (
operation: string,
refusals: Readonly<Record<string, string>>,
document: object,
): AnalysisError | undefined => {
const issues = Object.entries(refusals)
.filter(([field]) => Object.hasOwn(document, field))
.map(([field, message]) => ({
code: "custom" as const,
path: [field],
message,
input: (document as Readonly<Record<string, unknown>>)[field],
}));
return issues.length === 0
? undefined
: analysisInputErrorFromIssues(operation, issues, document);
};
/** The CLI keys of a description's JSON inputs. */
const jsonInputKeys = (
description: ContractCliDescription,
): ReadonlySet<string> =>
new Set(
description.parameters
.filter(({ jsonInput }) => jsonInput)
.map(({ key }) => key),
);
/**
* The JSON inputs every route takes under the same key, with the same
* refusal, so they can be decoded once before a route is chosen.
*/
const sharedJsonInputs = (
command: string,
routes: readonly CliCommandRoute[],
): ReadonlySet<string> => {
const keys = routes.map(({ description }) => jsonInputKeys(description));
const shared = new Set(
[...keys[0]!].filter((key) => keys.every((own) => own.has(key))),
);
for (const key of shared) {
const parameters = routes.map(({ description }) =>
description.parameters.find((parameter) => parameter.key === key)!,
);
if (new Set(parameters.map(({ runtimeJson }) => runtimeJson)).size !== 1)
throw new Error(`${command} routes refuse --${key} differently`);
// A shared input is checked before the route is chosen, so every route
// must check it the same way.
if (
new Set(parameters.map(({ checkJsonInput }) => checkJsonInput)).size !== 1
)
throw new Error(`${command} routes check --${key} differently`);
}
return shared;
};
/** The chosen route's JSON inputs that were not decoded before routing. */
const ownJsonInputs = (
description: ContractCliDescription,
decoded: ReadonlySet<string>,
): ReadonlySet<string> =>
new Set([...jsonInputKeys(description)].filter((key) => !decoded.has(key)));
/**
* Read and decode each JSON input the caller gave, inline or from a file,
* before the parameters are admitted; `keys` limits which are read. A file
* that cannot be read keeps its own failure; inline text that is not JSON is
* refused under its CLI key.
*/
const readJsonInputs = async (
description: ContractCliDescription,
values: Readonly<Record<string, unknown>>,
signal: AbortSignal,
keys: ReadonlySet<string> = jsonInputKeys(description),
): Promise<
| {
readonly ok: true;
readonly value: Readonly<Record<string, unknown>>;
readonly checked: Readonly<Record<string, unknown>>;
}
| { readonly ok: false; readonly error: JsonValue }
> => {
const decoded: Record<string, unknown> = { ...values };
const checked: Record<string, unknown> = {};
for (const {
field,
key,
runtimeJson,
checkJsonInput,
} of description.parameters) {
const text = values[key];
if (!keys.has(key) || typeof text !== "string") continue;
const parsed = await parseCliJsonInput(
text,
description.contract.name,
signal,
);
if (!parsed.ok)
return {
ok: false,
error: keepsOwnFailure(parsed.error)
? parsed.error
: projectAnalysisError(
new AnalysisInputError(description.contract.name, undefined, [
{
path: [key],
reason: "invalid_format",
expected: "JSON",
...(runtimeJson === undefined
? {}
: { message: runtimeJson }),
},
]),
),
};
decoded[key] = parsed.value;
if (checkJsonInput === undefined) continue;
// Refuse this input before the next one is read.
const admitted = checkJsonInput(parsed.value);
if (!admitted.ok)
return {
ok: false,
error: projectCliInputFields(
projectAnalysisError(admitted.error),
description.inputBinding,
),
};
checked[field] = admitted.value;
}
return { ok: true, value: decoded, checked };
};
/** A file failure names the selected path, and a cancellation is its own. */
const keepsOwnFailure = (error: JsonValue): boolean =>
isRecord(error) &&
("input_path" in error ||
(error as { readonly code?: unknown }).code === "cancelled");
/**
* Register one CLI command whose whole contract input is one JSON document.
* The handler receives the decoded document with its caller paths made
* absolute, and admits it with the contract's owner.
*/
export const registerContractDocumentCommand = <
Contract extends DocumentContract,
Value,
CliOptions extends CliOptionShape = Record<never, z.ZodType>,
>(
cli: CliInstance,
logger: Logger,
contract: Contract,
projection: CliDocumentProjection<ContractField<Contract>, CliOptions>,
run: (
document: unknown,
context: ContractDocumentContext<
CliOptionValues<CliOptions>,
z.output<Contract["inputSchema"]>
>,
) => Promise<Value>,
): void => {
const description = describeContractDocumentCommand(contract, projection);
const options = Object.fromEntries(
[
...(description.sessionTarget?.options ?? []),
...description.deliveryOptions,
...description.cliOnlyOptions,
].map(({ key, schema }) => [key, schema]),
);
cli.command(description.command, {
description: description.description,
args: z.object({
...(description.sessionTarget === undefined
? {}
: {
[description.sessionTarget.key]: description.sessionTarget.schema,
}),
[description.key]: jsonInputArgument(
description.documentDescription,
description.content,
),
}),
...(Object.keys(options).length === 0
? {}
: { options: z.object(options) }),
run: ({
args,
options: values,
}: {
readonly args: Readonly<Record<string, string>>;
readonly options: Readonly<Record<string, unknown>>;
}) =>
withCommandCancellation((signal) =>
logCliCommand(logger, description.command, async () => {
// Delivery options are checked before the document is read.
const delivery = description.admitDelivery(values);
if (!delivery.ok) return projectAnalysisError(delivery.error);
const opening = admitOpening(description, { ...values, ...args });
if (!opening.ok) return projectAnalysisError(opening.error);
const decoded = await parseCliJsonInput(
args[description.key]!,
contract.name,
signal,
);
if (!decoded.ok) return decoded.error;
// A document that is not an object has no fields to refuse; the
// contract refuses it.
const refused =
typeof decoded.value === "object" && decoded.value !== null
? refusedDocumentFieldError(
contract.name,
description.documentRefusals,
decoded.value,
)
: undefined;
if (refused !== undefined) return projectAnalysisError(refused);
const document = resolveCliJsonPaths(
decoded.value,
description.callerPaths,
);
let admitted:
| Result<z.output<Contract["inputSchema"]>, AnalysisInputError>
| undefined;
const parseWholeInput = () =>
(admitted ??= (() => {
const parsed = contract.inputSchema.safeParse(document);
return parsed.success
? ok(parsed.data as z.output<Contract["inputSchema"]>)
: err(
analysisInputErrorFromIssues(
contract.name,
parsed.error.issues,
decoded.value,
),
);
})());
return run(document, {
signal,
operation: contract.name,
spelled: decoded.value,
parsed: undefined,
parseWholeInput,
frame: description.content,
delivery: delivery.value,
opening: opening.value,
sessionTarget:
description.sessionTarget === undefined
? undefined
: args[description.sessionTarget.key],
cliOptions: description.cliOptionValues(
values,
) as CliOptionValues<CliOptions>,
});
}),
),
} as never);
const registered = documentDescriptions.get(cli) ?? [];
registered.push(description);
documentDescriptions.set(cli, registered);
};