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> = Readonly< Record >, Parsed = unknown, Checked extends Readonly> = Readonly< Record >, > { 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>; /** 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) | 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 = (context: { readonly operation: string; readonly parsed: Parsed | undefined; readonly parseWholeInput: | (() => Result) | undefined; }): Result => { 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>; 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>; close(): Promise; } /** 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>; 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>) => ({ ...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>, { 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, outputSchema: z.ZodType | undefined, binding: Parameters[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>, signal: AbortSignal, ) => Promise>, compose: ( input: Readonly>, context: ContractCommandContext & { readonly evidenceTargets: CliEvidenceTargetSelection; }, ) => Promise>, ) => 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>; const sources: Record = {}; 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> => { 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>, ): Result>, 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(); /** 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, Checks extends { readonly [Key in ContractField]?: CliJsonInputCheck; } = Record, >( cli: CliInstance, logger: Logger, contract: Contract, projection: CliContractProjection, CliOptions> & { readonly jsonInputChecks?: Checks; }, run: ( input: z.input, context: ContractCommandContext< CliOptionValues, z.output, CliCheckedJsonInputs >, ) => Promise, ): 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>; readonly options: Readonly>; }) => { const values: Record = { ...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, { 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 | undefined, parseWholeInput: admitted.value.parseWholeInput as | (() => Result< z.output, AnalysisInputError >) | undefined, checked: read.checked as CliCheckedJsonInputs, cliOptions: selected.cliOptionValues( values, ) as CliOptionValues, }, ), 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) | 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; } /** * 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>; /** Describe one route of a routed command from its contract input. */ export const commandRoute = < Contract extends ProjectedContract, CliOptions extends CliOptionShape = Record, >( contract: Contract, projection: CliContractProjection, CliOptions>, run: ( input: z.input, context: ContractCommandContext< CliOptionValues, z.output >, ) => Promise, route: { readonly takes?: (values: RouteValues) => Promise; 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; }, 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 >, ).map(([key, schema]) => [key, withoutDefault(schema)]), ), }); const schemaSignature = (schema: z.ZodType): string => JSON.stringify(z.toJSONSchema(schema, { unrepresentable: "any" })); const routedDescriptions = new WeakMap(); /** 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(); const owners = new Map(); 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>; readonly options: Readonly>; }) => { const values: Record = { ...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>, ): Readonly> => ({ ...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> = Readonly< Record >, 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; /** * 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>; } 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>, 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>)[field], })); return issues.length === 0 ? undefined : analysisInputErrorFromIssues(operation, issues, document); }; /** The CLI keys of a description's JSON inputs. */ const jsonInputKeys = ( description: ContractCliDescription, ): ReadonlySet => 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 => { 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, ): ReadonlySet => 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>, signal: AbortSignal, keys: ReadonlySet = jsonInputKeys(description), ): Promise< | { readonly ok: true; readonly value: Readonly>; readonly checked: Readonly>; } | { readonly ok: false; readonly error: JsonValue } > => { const decoded: Record = { ...values }; const checked: Record = {}; 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, >( cli: CliInstance, logger: Logger, contract: Contract, projection: CliDocumentProjection, CliOptions>, run: ( document: unknown, context: ContractDocumentContext< CliOptionValues, z.output >, ) => Promise, ): 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>; readonly options: Readonly>; }) => 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, AnalysisInputError> | undefined; const parseWholeInput = () => (admitted ??= (() => { const parsed = contract.inputSchema.safeParse(document); return parsed.success ? ok(parsed.data as z.output) : 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, }); }), ), } as never); const registered = documentDescriptions.get(cli) ?? []; registered.push(description); documentDescriptions.set(cli, registered); };