mirror of
https://github.com/morluto/rea.git
synced 2026-11-18 20:53:00 +00:00
Add offline ELF dependency, search-path, symbol-version and import inspection with retained Evidence summaries and pages. Bound GNU-hash work and preserve cancellation, stable identity and caller-selected parameters across CLI/MCP. Assisted-by: Suika (gensokyo-skills:suika-scatter-gather-planning) Co-authored-by: gensokyo-dev <342580529+gensokyo-dev@users.noreply.github.com>
2825 lines
103 KiB
TypeScript
2825 lines
103 KiB
TypeScript
import { z } from "zod";
|
|
|
|
import { cliCommandFor } from "../contracts/cliCommandNames.js";
|
|
|
|
import type { AnalysisError } from "../domain/analysisErrorBase.js";
|
|
import { AnalysisInputError } from "../domain/analysisErrorCore.js";
|
|
import type { AnalysisViewRequest } from "../domain/analysisView/analysisViewRequest.js";
|
|
import type { CallerInputPaths } from "../domain/evidence.js";
|
|
import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
|
|
import { localPathStringSchema } from "../domain/localPath.js";
|
|
import { schemaAnnotations } from "../domain/schemaAnnotations.js";
|
|
import { isRecord } from "../kernel/isRecord.js";
|
|
import { err, ok, type Result } from "../domain/result.js";
|
|
import { absoluteCallerPath } from "../filesystem/callerPath.js";
|
|
import {
|
|
analysisEvidenceDeliveryOptions,
|
|
cliEvidenceDeliveryInputError,
|
|
} from "./analysisEvidenceDelivery.js";
|
|
import { parseCliJsonOption } from "./cliJsonOption.js";
|
|
import { getEvidenceInputContract } from "../domain/evidenceInputContract.js";
|
|
import { cliJsonCallerPathSchema } from "./cliJsonInput.js";
|
|
import { safeParseJson } from "../domain/safeJson.js";
|
|
import { cliDecimalField, cliDecimalShape } from "./options.js";
|
|
import {
|
|
selectCliAnalysisSelector,
|
|
type CliSelectorKind,
|
|
} from "./analysisSelector.js";
|
|
import { optionFlagName } from "./optionFields.js";
|
|
|
|
/**
|
|
* Framework-neutral CLI description of a tool contract. This module owns
|
|
* which contract fields become positionals and options, their spellings,
|
|
* help and argv admission, and the mapping back to contract input. A CLI
|
|
* framework adapter (today `contractCommand.ts` for Incur) only renders it.
|
|
*/
|
|
|
|
/**
|
|
* The parts of a tool contract that a CLI projection reads. A union input
|
|
* shares every field except those the CLI delivery owns, such as a
|
|
* `detail`-discriminated delivery.
|
|
*/
|
|
export interface ProjectedContract<Name extends string = string> {
|
|
readonly name: Name;
|
|
/** The contract names its own CLI command; see `ToolContract.cli`. */
|
|
readonly cli?: true;
|
|
readonly inputSchema:
|
|
| z.ZodObject
|
|
| z.ZodDiscriminatedUnion<readonly z.ZodObject[]>
|
|
| z.ZodUnion<readonly z.ZodObject[]>;
|
|
/**
|
|
* The result schema. It declares which result positions are controls REA
|
|
* recorded; without it the CLI renders no result controls.
|
|
*/
|
|
readonly outputSchema?: z.ZodType;
|
|
}
|
|
|
|
/** A contract whose whole input a CLI command takes as one JSON document. */
|
|
export interface DocumentContract<Name extends string = string> {
|
|
readonly name: Name;
|
|
/** The contract names its own CLI command; see `ToolContract.cli`. */
|
|
readonly cli?: true;
|
|
readonly inputSchema: z.ZodType;
|
|
}
|
|
|
|
/**
|
|
* The command a projection registers: the contract's own command, which the
|
|
* contract declares with `cli: true` so the CLI inventory can be derived from
|
|
* the registry, or the command a route names.
|
|
*/
|
|
const projectedCommand = (
|
|
contract: DocumentContract,
|
|
command: string | undefined,
|
|
): string => {
|
|
if (command !== undefined) return command;
|
|
if (contract.cli !== true)
|
|
throw new Error(`${contract.name} does not declare its CLI command`);
|
|
return cliCommandFor(contract.name);
|
|
};
|
|
|
|
/** A contract input field name, from any of its input branches. */
|
|
export type ContractField<Contract extends DocumentContract> =
|
|
| (keyof z.input<Contract["inputSchema"]> & string)
|
|
| (BranchKey<z.input<Contract["inputSchema"]>> & string);
|
|
|
|
type BranchKey<Input> = Input extends unknown ? keyof Input : never;
|
|
|
|
/** Check one decoded JSON input before the next input is read. */
|
|
export type CliJsonInputCheck = (
|
|
value: unknown,
|
|
) => Result<unknown, AnalysisError>;
|
|
|
|
/** The value each JSON input check admitted, by contract field. */
|
|
export type CliCheckedJsonInputs<Checks> = {
|
|
readonly [Key in keyof Checks]?: Checks[Key] extends (
|
|
value: unknown,
|
|
) => Result<infer Value, AnalysisError>
|
|
? Value
|
|
: never;
|
|
};
|
|
|
|
/** How one contract field is spelled on the CLI. */
|
|
export interface CliFieldProjection {
|
|
/** Parameter key, in camelCase. Omit to use the camelCase contract field. */
|
|
readonly name?: string;
|
|
/** Single-character short flag. */
|
|
readonly alias?: string;
|
|
/** CLI help, when it differs from the contract field's description. */
|
|
readonly description?: string;
|
|
}
|
|
|
|
/** How one member of a flattened object field is spelled on the CLI. */
|
|
export interface CliMemberProjection extends CliFieldProjection {
|
|
/**
|
|
* An absolute-path member the caller may spell relative to the working
|
|
* directory. It is resolved before the contract sees it and kept as the
|
|
* caller spelled it in `callerInputs`, under its dotted member path.
|
|
*/
|
|
readonly callerPath?: true;
|
|
}
|
|
|
|
/**
|
|
* The members of one flattened object: each an option, or a nested optional
|
|
* object whose members are flattened in turn.
|
|
*/
|
|
export interface CliFlattenedMembers {
|
|
readonly [member: string]:
|
|
| CliMemberProjection
|
|
| { readonly flatten: CliFlattenedMembers };
|
|
}
|
|
|
|
/** How one top-level contract field is spelled on the CLI. */
|
|
export interface CliContractFieldProjection extends CliFieldProjection {
|
|
/**
|
|
* The value an omitted option takes on the CLI, for a contract field that
|
|
* has no default, such as the input branch a bare command selects. The
|
|
* field must admit it.
|
|
*/
|
|
readonly default?: string | number | boolean;
|
|
}
|
|
|
|
/**
|
|
* The CLI spelling of one contract. Everything not listed here is derived
|
|
* from the contract input schema: each field keeps its own schema, so the
|
|
* CLI admits what the contract admits.
|
|
*/
|
|
export interface CliContractProjection<
|
|
Field extends string,
|
|
CliOptions extends CliOptionShape = CliOptionShape,
|
|
> {
|
|
/**
|
|
* Omitted for the contract's own command (`cli: true`), named after the
|
|
* contract. A command routed to several contracts names itself here.
|
|
*/
|
|
readonly command?: string;
|
|
readonly description: string;
|
|
/**
|
|
* The input branches of a union contract this command takes, by the text
|
|
* values of the field that tells them apart, such as the `operation`s a
|
|
* sibling command runs instead. Each selected branch must be taken whole.
|
|
* When one value is selected, the command fixes that field: argv does not
|
|
* take it, and the contract input receives the value.
|
|
*/
|
|
readonly inputBranches?: CliInputBranches<Field>;
|
|
/** Fields taken as positional arguments, in argv order. */
|
|
readonly positionals?: readonly Field[];
|
|
/**
|
|
* Positional selectors the caller may instead give with a named option,
|
|
* for values that begin with a dash. The positional becomes optional;
|
|
* equal values agree and different ones are refused before the target is
|
|
* opened, as is neither when the field is required. The contract field
|
|
* must refuse an empty selector.
|
|
*/
|
|
readonly selectorOptions?: { readonly [Key in Field]?: CliSelectorOption };
|
|
/**
|
|
* Absolute-path fields, or lists of them, the caller may spell relative to
|
|
* the working directory. The CLI admits each nonempty, NUL-free,
|
|
* well-formed path, then resolves it with `absoluteCallerPath` before the
|
|
* contract sees it.
|
|
*/
|
|
readonly callerPaths?: readonly Field[];
|
|
/**
|
|
* Structured fields taken as one JSON text argument. The text is decoded
|
|
* at argv parsing and then admitted by the contract field's own schema.
|
|
*/
|
|
readonly jsonText?: readonly Field[];
|
|
/**
|
|
* Structured fields taken as JSON text that is decoded when the command
|
|
* runs, each with its refusal when the text is not JSON. A required field
|
|
* is a required option. The decoded input is then admitted by the
|
|
* contract input before any target is opened.
|
|
*/
|
|
readonly runtimeJson?: { readonly [Key in Field]?: string };
|
|
/**
|
|
* Structured fields taken as inline JSON or a JSON file path (`-` reads
|
|
* stdin), for values that can exceed the host's command-line limit. The
|
|
* command reads and decodes each when it runs, with its refusal when inline
|
|
* text is not JSON; a file that cannot be read keeps its own failure. The
|
|
* decoded input is then admitted by the contract input, as for
|
|
* `runtimeJson`, before any target is opened.
|
|
*/
|
|
readonly jsonInputs?: { readonly [Key in Field]?: string };
|
|
/**
|
|
* Checks of `jsonInputs` fields, run on each decoded input as soon as it
|
|
* is read, in argv order, so a refused input stops the command before the
|
|
* next input is read. Each check's value reaches the handler as
|
|
* `checked`; the contract then admits the remaining input, so a checked
|
|
* document is not walked and copied twice.
|
|
*/
|
|
readonly jsonInputChecks?: { readonly [Key in Field]?: CliJsonInputCheck };
|
|
/**
|
|
* Nullable limits whose null ("all remaining") is spelled by a bare flag,
|
|
* keyed by contract field. The limit option takes only a value; the flag
|
|
* and the limit are mutually exclusive.
|
|
*/
|
|
readonly nullFlags?: { readonly [Key in Field]?: CliNullFlag };
|
|
/**
|
|
* The operation analyzes the target an MCP session holds open, so the
|
|
* target is not a contract field. The CLI takes it as the first positional,
|
|
* `path`, and opens it before the operation runs on the contract input.
|
|
*/
|
|
readonly sessionTarget?: CliSessionTarget;
|
|
/**
|
|
* Required contract fields that each take the Evidence a source contract
|
|
* produces for one target, such as the two sides of a comparison. The CLI
|
|
* takes each target as a positional, in this order, and runs the source on
|
|
* every target with the same source options before the contract runs.
|
|
*/
|
|
readonly evidenceTargets?: CliEvidenceTargets<Field>;
|
|
/**
|
|
* Object fields taken as one parameter per member, keyed by contract field
|
|
* and then member; a member that is itself an object may be flattened in
|
|
* turn. A member is required when it and each enclosing object are. Any
|
|
* member given supplies each enclosing object with only the given members,
|
|
* so the contract reports a missing companion member and an omitted
|
|
* optional member stays omitted. A flattened field listed in `positionals`
|
|
* takes its members as positionals there, in member order; it and each of
|
|
* its members must be required.
|
|
*/
|
|
readonly flatten?: { readonly [Key in Field]?: CliFlattenedMembers };
|
|
readonly fields?: { readonly [Key in Field]?: CliContractFieldProjection };
|
|
/**
|
|
* Optional fields this one-shot command does not expose, each with the
|
|
* reason. The contract's own default applies.
|
|
*/
|
|
readonly omit?: { readonly [Key in Field]?: string };
|
|
/**
|
|
* Where the contract's cross-field rules first refuse a combination.
|
|
* `argv` reports them as CLI validation errors naming CLI keys; by default
|
|
* the service's contract parse reports them as an `invalid_request`.
|
|
*/
|
|
readonly crossFieldRules?: "argv";
|
|
/**
|
|
* The command delivers complete Evidence or a summary saved beside a
|
|
* bundle: it adds `--detail` and `--evidence_output`. A contract `detail`
|
|
* field selects that delivery and is not passed to the analysis.
|
|
*/
|
|
readonly evidenceDelivery?: true;
|
|
/**
|
|
* With `evidenceDelivery`, the contract `view` field selects the delivered
|
|
* page. `--view` takes JSON text that is decoded when the command runs, and
|
|
* the delivery is then checked against the contract input before any
|
|
* target is opened.
|
|
*/
|
|
readonly viewDelivery?: CliViewDelivery;
|
|
/**
|
|
* Options no contract field owns, keyed by their CLI key. Each is admitted
|
|
* by its own schema and takes effect in the command handler, never in the
|
|
* contract input; for example, an exit status chosen from the result.
|
|
*/
|
|
readonly cliOptions?: CliOptions;
|
|
/**
|
|
* CLI-only options taken as positional arguments after the contract's
|
|
* positionals, in this order, such as one target text the handler reads
|
|
* as one of several contract fields. Their values reach the handler with
|
|
* the other CLI-only values.
|
|
*/
|
|
readonly cliPositionals?: readonly (keyof CliOptions & string)[];
|
|
/**
|
|
* Contract fields argv never supplies because the handler fills them from
|
|
* CLI-only values, including required ones. The handler admits its
|
|
* completed input with the contract, so the contract's own rules apply.
|
|
*/
|
|
readonly handlerFields?: readonly Field[];
|
|
/**
|
|
* `dependentRequired` entries over CLI keys that the CLI-only options add
|
|
* to the contract's own. Help and `--schema` advertise them; the handler
|
|
* enforces them.
|
|
*/
|
|
readonly cliOptionDependencies?: Readonly<
|
|
Partial<Record<keyof CliOptions & string, readonly string[]>>
|
|
>;
|
|
/**
|
|
* A CLI-only option whose values select another contract with the same
|
|
* CLI projection, such as `--kind` choosing which inventory to search.
|
|
* Other values, including the option's default, select the registered
|
|
* contract.
|
|
*/
|
|
readonly operationBy?: CliOperationChoice<keyof CliOptions & string>;
|
|
/**
|
|
* Optional top-level fields taken together as one JSON object option,
|
|
* keyed by the option's CLI key, such as a selection whose members are
|
|
* each a contract field. The text is decoded when the command runs, with
|
|
* the group's refusal when it is not a JSON object; a member must be one
|
|
* of the group's fields, and the contract admits each member's value as
|
|
* that field. The grouped fields are not otherwise exposed.
|
|
*/
|
|
readonly fieldGroups?: Readonly<Record<string, CliFieldGroup<Field>>>;
|
|
}
|
|
|
|
/** Contract fields one CLI option takes as the members of a JSON object. */
|
|
export interface CliFieldGroup<Field extends string = string> {
|
|
readonly fields: readonly [Field, ...Field[]];
|
|
readonly description: string;
|
|
/** The refusal for text that is not a JSON object. */
|
|
readonly invalidJson: string;
|
|
}
|
|
|
|
/** The input branches one command takes, by their discriminating values. */
|
|
export interface CliInputBranches<Field extends string = string> {
|
|
readonly field: Field;
|
|
readonly values: readonly [string, ...string[]];
|
|
}
|
|
|
|
/** Contracts a CLI-only option selects in place of the registered one. */
|
|
export interface CliOperationChoice<Option extends string = string> {
|
|
readonly option: Option;
|
|
readonly contracts: Readonly<Record<string, ProjectedContract>>;
|
|
}
|
|
|
|
/** Schemas of the CLI-only options of one command, keyed by CLI key. */
|
|
export type CliOptionShape = Readonly<Record<string, z.ZodType>>;
|
|
|
|
/** Parsed values of the CLI-only options of one command. */
|
|
export type CliOptionValues<CliOptions extends CliOptionShape> = {
|
|
readonly [Key in keyof CliOptions]: z.output<CliOptions[Key]>;
|
|
};
|
|
|
|
/** The target an operation runs on, which an MCP session holds open. */
|
|
export interface CliSessionTarget {
|
|
/** Help for the target positional. */
|
|
readonly description: string;
|
|
/**
|
|
* Fields of the contract an MCP client opens the target with, taken as
|
|
* options. They are admitted by that contract's input, with the target as
|
|
* its `path`, before the target is opened.
|
|
*/
|
|
readonly open?: CliTargetOpening;
|
|
}
|
|
|
|
/** The opening contract's fields a command takes as options. */
|
|
export interface CliTargetOpening {
|
|
readonly contract: {
|
|
readonly name: string;
|
|
readonly inputSchema: z.ZodObject;
|
|
};
|
|
readonly fields: Readonly<Record<string, CliOpeningFieldProjection>>;
|
|
}
|
|
|
|
/** How one opening field is spelled on the CLI. */
|
|
export interface CliOpeningFieldProjection extends CliFieldProjection {
|
|
/** The values this command admits: a subset of the field's enum. */
|
|
readonly values?: readonly [string, ...string[]];
|
|
/**
|
|
* A local path the caller may spell relative to the working directory.
|
|
* It is admitted resolved and passed on as the caller spelled it, like the
|
|
* target itself.
|
|
*/
|
|
readonly callerPath?: true;
|
|
}
|
|
|
|
/** An option that supplies one field of the opening contract. */
|
|
export interface ContractCliOpeningOption {
|
|
readonly field: string;
|
|
readonly key: string;
|
|
readonly description: string | undefined;
|
|
readonly schema: z.ZodType;
|
|
/** Passed on as the caller spelled it once its resolved form is admitted. */
|
|
readonly callerPath: boolean;
|
|
}
|
|
|
|
/** The described session target of a contract command. */
|
|
export interface ContractCliSessionTarget {
|
|
/** The positional key, taken before every other positional. */
|
|
readonly key: string;
|
|
readonly schema: z.ZodType;
|
|
/** The contract that opens the target, when the command takes its fields. */
|
|
readonly opening: string | undefined;
|
|
/** Options that supply fields of the opening contract. */
|
|
readonly options: readonly ContractCliOpeningOption[];
|
|
/**
|
|
* The opening fields the parsed options select, in contract spelling,
|
|
* admitted by the opening contract with the target as its `path`.
|
|
* Issues name CLI keys.
|
|
*/
|
|
readonly admitOpening: (
|
|
operation: string,
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Result<Readonly<Record<string, unknown>>, AnalysisInputError>;
|
|
}
|
|
|
|
/** The CLI key of a session target, which no contract field supplies. */
|
|
const SESSION_TARGET_KEY = "path";
|
|
|
|
/**
|
|
* Contract fields each supplied by the source contract's Evidence for one
|
|
* target. The source fields are its options; each target is admitted by the
|
|
* source input as its `path`.
|
|
*/
|
|
export interface CliEvidenceTargets<Field extends string> {
|
|
/** The target positional of each field, in argv order. */
|
|
readonly fields: {
|
|
readonly [Key in Field]?: CliFieldProjection & {
|
|
/** Help for the target positional. */
|
|
readonly description: string;
|
|
};
|
|
};
|
|
readonly source: CliTargetOpening;
|
|
}
|
|
|
|
/** One described Evidence target positional. */
|
|
export interface ContractCliEvidenceTarget {
|
|
/** The contract field its source Evidence supplies. */
|
|
readonly field: string;
|
|
readonly key: string;
|
|
readonly schema: z.ZodType;
|
|
}
|
|
|
|
/** The described Evidence targets of a contract command. */
|
|
export interface ContractCliEvidenceTargets {
|
|
/** The source contract each target runs. */
|
|
readonly source: string;
|
|
readonly targets: readonly ContractCliEvidenceTarget[];
|
|
/** Options that supply fields of the source contract. */
|
|
readonly options: readonly ContractCliOpeningOption[];
|
|
/**
|
|
* Each source contract field this command takes as an option, with that
|
|
* option's flag, so a source failure's control names it.
|
|
*/
|
|
readonly sourceFlags: Readonly<Record<string, string>>;
|
|
/**
|
|
* The source fields the parsed options select, in contract spelling,
|
|
* admitted by the source input with each target as its `path`. Issues
|
|
* name CLI keys.
|
|
*/
|
|
readonly admitSource: (
|
|
operation: string,
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Result<Readonly<Record<string, unknown>>, AnalysisInputError>;
|
|
}
|
|
|
|
/** A bare flag that sets a nullable contract field to null. */
|
|
export interface CliNullFlag {
|
|
readonly key: string;
|
|
readonly description: string;
|
|
}
|
|
|
|
/** How a contract command takes its `view` selection. */
|
|
export interface CliViewDelivery {
|
|
/** The refusal when `--view` is not JSON. */
|
|
readonly invalidJson: string;
|
|
/** Added to the selection when the contract's view does not name its kind. */
|
|
readonly kind?: AnalysisViewRequest["kind"];
|
|
/**
|
|
* `--detail` has no default: a view selects summary delivery, and complete
|
|
* applies otherwise, as in the contract.
|
|
*/
|
|
readonly viewSelectsSummary?: true;
|
|
}
|
|
|
|
/** Help for `--view`, which names the delivery it needs. */
|
|
const viewOptionHelp = (viewDelivery: CliViewDelivery): string =>
|
|
viewDelivery.viewSelectsSummary === true
|
|
? "JSON page selection; selects summary delivery, which requires --evidence_output"
|
|
: "JSON page selection; requires --detail summary and --evidence_output";
|
|
|
|
/** A CLI option with no contract field, such as `--evidence_output`. */
|
|
export interface CliOnlyOption {
|
|
readonly key: string;
|
|
readonly description: string | undefined;
|
|
readonly schema: z.ZodType;
|
|
}
|
|
|
|
/** The Evidence delivery a command invocation selected. */
|
|
export interface CliEvidenceDeliveryChoice {
|
|
readonly detail: "complete" | "summary";
|
|
readonly evidenceOutput: string | undefined;
|
|
/** The admitted view, for a projection with `viewDelivery`. */
|
|
readonly view?: AnalysisViewRequest;
|
|
}
|
|
|
|
/** The named option of a positional selector. */
|
|
export interface CliSelectorOption {
|
|
/** The option key; its flag is the kebab-case spelling. */
|
|
readonly name: string;
|
|
readonly description: string;
|
|
/** How the two spellings agree; `text` by default. */
|
|
readonly kind?: CliSelectorKind;
|
|
/**
|
|
* The command needs a selector although the contract admits omission,
|
|
* such as a one-shot command that has no current position to fall back on.
|
|
*/
|
|
readonly required?: true;
|
|
/**
|
|
* A second named option that spells the same selector in another
|
|
* coordinate system, such as a file offset for a procedure. Its value is
|
|
* mapped to the selector's text and must agree with the other spellings.
|
|
*/
|
|
readonly alternative?: CliSelectorAlternative;
|
|
}
|
|
|
|
/** Another option spelling a selector, mapped to the selector's text. */
|
|
export interface CliSelectorAlternative {
|
|
/** The option key; its flag is the kebab-case spelling. */
|
|
readonly name: string;
|
|
readonly description: string;
|
|
/** The option's own argv grammar. */
|
|
readonly schema: z.ZodType<string>;
|
|
/** The selector text this value selects. */
|
|
readonly selects: (value: string) => string;
|
|
}
|
|
|
|
/** The described alternative option of a positional selector. */
|
|
export interface ContractCliSelectorAlternative {
|
|
readonly key: string;
|
|
/** The key of the option's parsed value. */
|
|
readonly valueKey: string;
|
|
readonly schema: z.ZodType;
|
|
readonly selects: (value: string) => string;
|
|
}
|
|
|
|
/** The described named option of a positional selector. */
|
|
export interface ContractCliSelectorOption {
|
|
readonly key: string;
|
|
/**
|
|
* The key of the option's parsed value, beside the positional's own
|
|
* value, which may share the option's key.
|
|
*/
|
|
readonly valueKey: string;
|
|
readonly description: string;
|
|
readonly schema: z.ZodType;
|
|
readonly kind: CliSelectorKind;
|
|
/** Neither spelling may be omitted. */
|
|
readonly required: boolean;
|
|
/** Another option spelling the same selector, if any. */
|
|
readonly alternative: ContractCliSelectorAlternative | undefined;
|
|
}
|
|
|
|
/** One positional argument or option of a contract command. */
|
|
export interface ContractCliParameter {
|
|
/** The contract input field this parameter supplies. */
|
|
readonly field: string;
|
|
/** camelCase key; an option's flag is its kebab-case spelling. */
|
|
readonly key: string;
|
|
readonly positional: boolean;
|
|
readonly alias: string | undefined;
|
|
readonly description: string | undefined;
|
|
/**
|
|
* Admission of the parsed argv value: the contract field's own schema,
|
|
* with decimal integer tokens and caller-relative paths admitted.
|
|
*/
|
|
readonly schema: z.ZodType;
|
|
/**
|
|
* The contract transforms this field; argv admits its inbound text and
|
|
* the contract refuses or normalizes it on admission.
|
|
*/
|
|
readonly inbound: boolean;
|
|
/** A bare flag sets true; it takes no value. */
|
|
readonly booleanFlag: boolean;
|
|
/** The value an omitted option takes on the CLI where the contract has no default. */
|
|
readonly cliDefault: string | number | boolean | undefined;
|
|
/** The option may repeat; each occurrence adds one array element. */
|
|
readonly repeatable: boolean;
|
|
/** Integer values are spelled as decimal digits only. */
|
|
readonly decimal: boolean;
|
|
/** Resolved with `absoluteCallerPath` before the contract sees it. */
|
|
readonly callerPath: boolean;
|
|
/** The value is JSON text decoded into the contract field. */
|
|
readonly jsonText: boolean;
|
|
/** Selects CLI Evidence delivery and is not analysis input. */
|
|
readonly delivery: boolean;
|
|
/**
|
|
* A delivery view as JSON text, decoded when the command runs and admitted
|
|
* with the delivery by the contract input.
|
|
*/
|
|
readonly viewSelection: boolean;
|
|
/**
|
|
* The refusal for text that is not JSON, when the value is JSON text
|
|
* decoded when the command runs; undefined otherwise.
|
|
*/
|
|
readonly runtimeJson: string | undefined;
|
|
/**
|
|
* The text may name a JSON file, which the command reads before the
|
|
* parameters are admitted, so `admit` receives the decoded value.
|
|
*/
|
|
readonly jsonInput: boolean;
|
|
/** Checks the decoded JSON input as soon as it is read, if declared. */
|
|
readonly checkJsonInput: CliJsonInputCheck | undefined;
|
|
/** The bare flag that sets this nullable field to null, if any. */
|
|
readonly nullFlag: string | undefined;
|
|
/**
|
|
* The member path within the object field this option supplies, if
|
|
* flattened: one member, or more for a nested object.
|
|
*/
|
|
readonly member: readonly string[] | undefined;
|
|
/** The named option of a positional selector, if any. */
|
|
readonly selectorOption: ContractCliSelectorOption | undefined;
|
|
/**
|
|
* The top-level contract fields this JSON object option supplies as its
|
|
* members, for a field group; `field` is then the group's CLI key, not a
|
|
* contract field. Undefined otherwise.
|
|
*/
|
|
readonly group: readonly string[] | undefined;
|
|
}
|
|
|
|
/** The contract input and delivery one invocation selected. */
|
|
export interface ContractCliAdmission {
|
|
readonly input: Record<string, unknown>;
|
|
/**
|
|
* The contract's parse of the whole input, when admission decoded JSON at
|
|
* run time or argv supplied every contract field and the input conforms;
|
|
* undefined otherwise.
|
|
*/
|
|
readonly parsed: unknown;
|
|
/**
|
|
* The contract's parse of an argv-supplied whole input, or its refusal,
|
|
* computed on first call and then reused. Admission leaves a refusal to
|
|
* the handler, whose workflow owns how a nonconforming input is reported;
|
|
* undefined when argv does not supply the whole input.
|
|
*/
|
|
readonly parseWholeInput:
|
|
| (() => Result<unknown, AnalysisInputError>)
|
|
| undefined;
|
|
/** The admitted delivery, for a projection with `evidenceDelivery`. */
|
|
readonly delivery: CliEvidenceDeliveryChoice | undefined;
|
|
}
|
|
|
|
/** One cross-field refusal, naming CLI keys. */
|
|
export interface ContractCliIssue {
|
|
readonly path: readonly PropertyKey[];
|
|
readonly message: string;
|
|
readonly issue: z.core.$ZodIssue;
|
|
}
|
|
|
|
/** A complete, framework-neutral CLI command derived from one contract. */
|
|
export interface ContractCliDescription {
|
|
readonly command: string;
|
|
readonly description: string;
|
|
readonly contract: ProjectedContract;
|
|
/**
|
|
* Each contract input field's own schema. In a union input, a field the
|
|
* delivery owns admits the value of any branch.
|
|
*/
|
|
readonly fields: Readonly<Record<string, z.ZodType>>;
|
|
readonly parameters: readonly ContractCliParameter[];
|
|
/** Options after the contract parameters that no contract field owns. */
|
|
readonly cliOnlyOptions: readonly CliOnlyOption[];
|
|
/** Positionals after the contract's own that no contract field owns. */
|
|
readonly cliPositionals: readonly CliOnlyOption[];
|
|
/** Contract fields the command does not expose, with the reason. */
|
|
readonly omitted: Readonly<Record<string, string>>;
|
|
/** Contract fields the handler fills from CLI-only values. */
|
|
readonly handlerFields: readonly string[];
|
|
/** Contract fields the selected input branch fixes, with their values. */
|
|
readonly fixedFields: Readonly<Record<string, string>>;
|
|
/** Object-level JSON Schema constraints, renamed to CLI keys. */
|
|
readonly optionConstraints: Readonly<Record<string, unknown>> | undefined;
|
|
/**
|
|
* The contract's cross-field rules over parsed option values, when the
|
|
* projection refuses them at argv parsing; undefined otherwise.
|
|
*/
|
|
readonly checkOptions:
|
|
| ((
|
|
options: Readonly<Record<string, unknown>>,
|
|
) => readonly ContractCliIssue[])
|
|
| undefined;
|
|
/**
|
|
* Map parsed values, keyed by parameter key, to the contract input. Values
|
|
* of run-time JSON parameters must already be decoded.
|
|
*/
|
|
readonly toContractInput: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Record<string, unknown>;
|
|
/** Each caller-path field as the caller spelled it, before resolution. */
|
|
readonly callerInputs: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => CallerInputPaths;
|
|
/** The parsed values of the projection's CLI-only options. */
|
|
readonly cliOptionValues: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Readonly<Record<string, unknown>>;
|
|
/**
|
|
* The session target positional, taken before the contract positionals,
|
|
* when the operation runs on a target the CLI opens; undefined otherwise.
|
|
*/
|
|
readonly sessionTarget: ContractCliSessionTarget | undefined;
|
|
/**
|
|
* The Evidence target positionals, taken before the contract positionals,
|
|
* when source Evidence supplies contract fields; undefined otherwise.
|
|
*/
|
|
readonly evidenceTargets: ContractCliEvidenceTargets | undefined;
|
|
/**
|
|
* Contract fields the CLI spells differently, so input issues reported
|
|
* after argv parsing can name the CLI key, and the flag of each contract
|
|
* field (or `field.member`) the command takes as an option, so a failure
|
|
* that names a per-call control can name the flag that sets it. Each field
|
|
* of a field group maps to the group's option, and a positional selector
|
|
* to its named option.
|
|
*/
|
|
readonly inputBinding: {
|
|
readonly operation: string;
|
|
readonly fields: Readonly<Record<string, string>>;
|
|
readonly flags: Readonly<Record<string, string>>;
|
|
};
|
|
/** The command adds `--detail` and `--evidence_output`. */
|
|
readonly evidenceDelivery: boolean;
|
|
/**
|
|
* Decode run-time JSON, then map parsed values to the contract input and
|
|
* the selected delivery. An input or delivery that is not admitted is
|
|
* refused before any target is opened.
|
|
*/
|
|
readonly admit: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Result<ContractCliAdmission, AnalysisInputError>;
|
|
/**
|
|
* Refuse inline JSON options and a delivery the options cannot select,
|
|
* before any JSON input is read, so an invalid invocation never waits on a
|
|
* file or stdin. `admit` still checks the admitted view with the input.
|
|
*/
|
|
readonly admitDeliveryOptions: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Result<void, AnalysisInputError>;
|
|
}
|
|
|
|
/** One contract from a contract group, keeping its exact schema types. */
|
|
export const contractNamed = <
|
|
Contracts extends readonly { readonly name: string }[],
|
|
Name extends Contracts[number]["name"],
|
|
>(
|
|
contracts: Contracts,
|
|
name: Name,
|
|
): Extract<Contracts[number], { readonly name: Name }> => {
|
|
const contract = contracts.find(
|
|
(
|
|
candidate,
|
|
): candidate is Extract<Contracts[number], { readonly name: Name }> =>
|
|
candidate.name === name,
|
|
);
|
|
if (contract === undefined) throw new Error(`Missing tool contract: ${name}`);
|
|
return contract;
|
|
};
|
|
|
|
const camelCase = (field: string): string =>
|
|
field.replaceAll(/_([a-z0-9])/gu, (_, letter: string) =>
|
|
letter.toUpperCase(),
|
|
);
|
|
|
|
/** The contract object admits this field's key being absent. */
|
|
const admitsOmission = (field: z.ZodType): boolean =>
|
|
z.object({ value: field }).safeParse({}).success;
|
|
|
|
const isWrapper = (value: z.ZodType) =>
|
|
value instanceof z.ZodOptional ||
|
|
value instanceof z.ZodExactOptional ||
|
|
value instanceof z.ZodDefault ||
|
|
value instanceof z.ZodPrefault ||
|
|
value instanceof z.ZodNullable ||
|
|
value instanceof z.ZodReadonly;
|
|
|
|
const core = (value: z.ZodType): z.ZodType => {
|
|
let current = value;
|
|
while (isWrapper(current)) current = current.unwrap() as z.ZodType;
|
|
return current;
|
|
};
|
|
|
|
/**
|
|
* The description of a field, read through wrappers such as `.optional()`:
|
|
* zod does not carry a wrapped schema's description to its wrapper, and the
|
|
* advertised JSON Schema shows the wrapped description.
|
|
*/
|
|
const describedThroughWrappers = (value: z.ZodType): string | undefined => {
|
|
let current = value;
|
|
while (current.description === undefined && isWrapper(current))
|
|
current = current.unwrap() as z.ZodType;
|
|
return current.description;
|
|
};
|
|
|
|
/**
|
|
* JSON text for a structured contract field. Argv carries text; the decoded
|
|
* value is admitted by the contract field itself, so `--schema` advertises
|
|
* the contract's structure.
|
|
*/
|
|
const jsonTextField = (declared: z.ZodType, flag: string): z.ZodType => {
|
|
const value =
|
|
declared instanceof z.ZodOptional || declared instanceof z.ZodExactOptional
|
|
? (declared.unwrap() as z.ZodType)
|
|
: declared;
|
|
const expected =
|
|
core(value) instanceof z.ZodObject ? "a JSON object" : "valid JSON";
|
|
const decoded = z
|
|
.string()
|
|
.transform((text, context) => {
|
|
const parsed = safeParseJson(text);
|
|
if (parsed.ok) return parsed.value;
|
|
context.addIssue({
|
|
code: "custom",
|
|
message: `${flag} must be ${expected}`,
|
|
});
|
|
return z.NEVER;
|
|
})
|
|
.pipe(value);
|
|
const admitted = admitsOmission(declared) ? decoded.optional() : decoded;
|
|
return declared.description === undefined
|
|
? admitted
|
|
: admitted.describe(declared.description);
|
|
};
|
|
|
|
const assertArgvField = (
|
|
contract: string,
|
|
field: string,
|
|
schema: z.ZodType,
|
|
) => {
|
|
const current = core(schema);
|
|
// A union of text forms, such as `auto` or a provider ID, is one token.
|
|
const text = (member: z.ZodType): boolean =>
|
|
member instanceof z.ZodString ||
|
|
member instanceof z.ZodEnum ||
|
|
(member instanceof z.ZodLiteral &&
|
|
[...member.values].every((value) => typeof value === "string"));
|
|
const scalar =
|
|
current instanceof z.ZodString ||
|
|
current instanceof z.ZodNumber ||
|
|
current instanceof z.ZodBoolean ||
|
|
current instanceof z.ZodEnum ||
|
|
(current instanceof z.ZodUnion &&
|
|
(current.options as readonly z.ZodType[]).every(text));
|
|
const element =
|
|
current instanceof z.ZodArray ? core(current.element as z.ZodType) : null;
|
|
if (
|
|
!scalar &&
|
|
!(
|
|
element instanceof z.ZodString ||
|
|
element instanceof z.ZodEnum ||
|
|
element instanceof z.ZodNumber
|
|
)
|
|
)
|
|
throw new Error(
|
|
`${contract}.${field} has no argv projection; declare one before exposing it on the CLI`,
|
|
);
|
|
};
|
|
|
|
/**
|
|
* Argv cannot carry an explicit undefined, so an exact-optional field admits
|
|
* the same values as an optional one. Renderers such as Incur's help read
|
|
* boolean flags and enum choices only through `optional`.
|
|
*/
|
|
/**
|
|
* The inbound view of a transformed contract field, such as an endpoint or
|
|
* an origin list the contract normalizes: argv carries the text the
|
|
* contract transforms when it admits the input, as tools/list advertises
|
|
* it. Undefined when the field has no transform.
|
|
*/
|
|
const inboundView = (field: z.ZodType): z.ZodType | undefined => {
|
|
const inbound = (schema: z.ZodType): z.ZodType | undefined => {
|
|
if (schema instanceof z.ZodPipe && schema.out instanceof z.ZodTransform)
|
|
return inbound(schema.in as z.ZodType) ?? (schema.in as z.ZodType);
|
|
if (schema instanceof z.ZodArray) {
|
|
const element = inbound(schema.element as z.ZodType);
|
|
return element === undefined
|
|
? undefined
|
|
: (schema.clone({ ...schema.def, element }) as z.ZodType);
|
|
}
|
|
return undefined;
|
|
};
|
|
const view = inbound(core(field));
|
|
if (view === undefined) return undefined;
|
|
// The contract applies its own default when it admits the input.
|
|
const optional = admitsOmission(field) ? view.optional() : view;
|
|
const description = field.description ?? view.description;
|
|
return description === undefined ? optional : optional.describe(description);
|
|
};
|
|
|
|
/**
|
|
* The argv schema of a field: a number, or each element of an array of
|
|
* numbers, takes decimal tokens only. An array keeps its own bounds.
|
|
*/
|
|
const argvDecimal = (field: z.ZodType): z.ZodType => {
|
|
const array = core(field);
|
|
if (
|
|
!(array instanceof z.ZodArray) ||
|
|
!(core(array.element as z.ZodType) instanceof z.ZodNumber)
|
|
)
|
|
return cliDecimalShape({ field }).field;
|
|
if (field instanceof z.ZodDefault)
|
|
throw new Error("A defaulted number array has no argv projection");
|
|
const decimal = new z.ZodArray({
|
|
...array._zod.def,
|
|
element: cliDecimalField(array.element as z.ZodType),
|
|
});
|
|
const admitted = admitsOmission(field) ? decimal.optional() : decimal;
|
|
return field.description === undefined
|
|
? admitted
|
|
: admitted.describe(field.description);
|
|
};
|
|
|
|
const argvOptional = (field: z.ZodType): z.ZodType => {
|
|
if (!(field instanceof z.ZodExactOptional)) return field;
|
|
const optional = (field.unwrap() as z.ZodType).optional();
|
|
return field.description === undefined
|
|
? optional
|
|
: optional.describe(field.description);
|
|
};
|
|
|
|
const OBJECT_CONSTRAINTS = ["dependentRequired", "if", "then", "else"] as const;
|
|
|
|
/** Contract-level presentation that CLI help states in its own words. */
|
|
const ROOT_ANNOTATIONS: ReadonlySet<string> = new Set([
|
|
"description",
|
|
"title",
|
|
"examples",
|
|
]);
|
|
|
|
/** Rename the field names inside the object constraints the contract advertises. */
|
|
const renameConstraint = (
|
|
contract: string,
|
|
value: unknown,
|
|
rename: (field: string) => string,
|
|
): unknown => {
|
|
if (typeof value !== "object" || value === null || Array.isArray(value))
|
|
throw new Error(`${contract} has an unsupported object constraint`);
|
|
return Object.fromEntries(
|
|
Object.entries(value).map(([keyword, inner]) => {
|
|
if (keyword === "required" && Array.isArray(inner))
|
|
return [keyword, inner.map((field: string) => rename(field))];
|
|
if (keyword === "properties" && typeof inner === "object" && inner)
|
|
return [
|
|
keyword,
|
|
Object.fromEntries(
|
|
Object.entries(inner).map(([field, schema]) => [
|
|
rename(field),
|
|
schema,
|
|
]),
|
|
),
|
|
];
|
|
throw new Error(
|
|
`${contract} object constraint keyword ${keyword} has no CLI projection`,
|
|
);
|
|
}),
|
|
);
|
|
};
|
|
|
|
const projectObjectConstraints = (
|
|
contract: ProjectedContract,
|
|
rename: (field: string) => string,
|
|
discriminatorFields: ReadonlySet<string>,
|
|
cliOptionDependencies: Readonly<Record<string, readonly string[]>>,
|
|
nullFlagLimits: readonly (readonly [flag: string, limit: string])[],
|
|
): Record<string, unknown> | undefined => {
|
|
const metadata = contract.inputSchema.meta() ?? {};
|
|
for (const keyword of Object.keys(metadata))
|
|
if (
|
|
!ROOT_ANNOTATIONS.has(keyword) &&
|
|
!(OBJECT_CONSTRAINTS as readonly string[]).includes(keyword)
|
|
)
|
|
throw new Error(
|
|
`${contract.name} input keyword ${keyword} has no CLI projection`,
|
|
);
|
|
// A root discriminator is checked with the delivery, left to the contract
|
|
// when the projection omits the discriminator, or is the option that
|
|
// selects the input branch.
|
|
const { rootDiscriminator } = schemaAnnotations(contract.inputSchema) ?? {};
|
|
if (
|
|
rootDiscriminator !== undefined &&
|
|
!discriminatorFields.has(rootDiscriminator)
|
|
)
|
|
throw new Error(
|
|
`${contract.name} root discriminator ${rootDiscriminator} has no CLI projection`,
|
|
);
|
|
const projected: Record<string, unknown> = {};
|
|
for (const keyword of OBJECT_CONSTRAINTS) {
|
|
const value = metadata[keyword];
|
|
if (value === undefined) continue;
|
|
projected[keyword] =
|
|
keyword === "dependentRequired"
|
|
? Object.fromEntries(
|
|
Object.entries(value as Record<string, readonly string[]>).map(
|
|
([field, required]) => [rename(field), required.map(rename)],
|
|
),
|
|
)
|
|
: renameConstraint(contract.name, value, rename);
|
|
}
|
|
if (Object.keys(cliOptionDependencies).length > 0)
|
|
projected.dependentRequired = {
|
|
...(projected.dependentRequired as object | undefined),
|
|
...cliOptionDependencies,
|
|
};
|
|
if (nullFlagLimits.length > 1)
|
|
throw new Error(`${contract.name} has more than one null flag`);
|
|
for (const [flag, limit] of nullFlagLimits)
|
|
projected.not = {
|
|
required: [flag, limit],
|
|
properties: { [flag]: { const: true } },
|
|
};
|
|
return Object.keys(projected).length === 0 ? undefined : projected;
|
|
};
|
|
|
|
/**
|
|
* Each input field's schema. Branches of a union input must share each field
|
|
* the CLI takes as an argument; only delivery-owned fields, and omitted
|
|
* fields the CLI never supplies, may differ, and they admit any branch's
|
|
* value here. The delivery is then checked against the whole union.
|
|
*/
|
|
/**
|
|
* A boolean whose `true` and `false` literals each select one input branch,
|
|
* such as whether to capture script sources, is one flag. Omission takes the
|
|
* default of the branch that admits it; the contract selects the branch when
|
|
* it admits the input.
|
|
*/
|
|
const branchSelectingFlag = (
|
|
branches: readonly (z.ZodType | undefined)[],
|
|
): z.ZodType | undefined => {
|
|
const values = branches.map((branch) => {
|
|
const value = branch === undefined ? undefined : core(branch);
|
|
return value instanceof z.ZodLiteral && value.values.size === 1
|
|
? [...value.values][0]
|
|
: undefined;
|
|
});
|
|
if (
|
|
values.some((value) => typeof value !== "boolean") ||
|
|
new Set(values).size !== 2
|
|
)
|
|
return undefined;
|
|
const omissions = branches.filter((branch) => admitsOmission(branch!));
|
|
if (omissions.length > 1) return undefined;
|
|
const flag = z.boolean();
|
|
return omissions.length === 0
|
|
? flag
|
|
: flag.default(omissions[0]!.parse(undefined) as boolean);
|
|
};
|
|
|
|
/** The text values a literal or enum field admits, or undefined for other fields. */
|
|
const textValues = (
|
|
field: z.ZodType | undefined,
|
|
): readonly string[] | undefined => {
|
|
const value = field === undefined ? undefined : core(field);
|
|
const values =
|
|
value instanceof z.ZodLiteral
|
|
? [...value.values]
|
|
: value instanceof z.ZodEnum
|
|
? value.options
|
|
: undefined;
|
|
return values?.every((entry) => typeof entry === "string")
|
|
? values
|
|
: undefined;
|
|
};
|
|
|
|
/**
|
|
* A field every input branch declares as distinct text values, a literal in
|
|
* one branch or an enum in another, such as `action` or `operation`: the
|
|
* option names the branch it selects. Omission takes the default of the one
|
|
* branch that admits it.
|
|
*/
|
|
const branchSelectingChoice = (
|
|
branches: readonly (z.ZodType | undefined)[],
|
|
): z.ZodType | undefined => {
|
|
const valueSets = branches.map(textValues);
|
|
if (valueSets.some((values) => values === undefined)) return undefined;
|
|
const values = valueSets.flatMap((values) => values!);
|
|
const omissions = branches.filter((branch) => admitsOmission(branch!));
|
|
if (new Set(values).size !== values.length || omissions.length > 1)
|
|
return undefined;
|
|
const choice = z.enum(values as [string, ...string[]]);
|
|
const omitted = omissions[0]?.parse(undefined) as string | undefined;
|
|
const chosen =
|
|
omissions.length === 0
|
|
? choice
|
|
: omitted === undefined
|
|
? choice.optional()
|
|
: choice.default(omitted);
|
|
const described = branches.find((branch) => branch!.description);
|
|
return described === undefined
|
|
? chosen
|
|
: chosen.describe(described.description!);
|
|
};
|
|
|
|
/**
|
|
* A field only some input branches declare, with one schema there. The CLI
|
|
* takes it as an optional option without a parse-time default, so another
|
|
* branch never receives it; the selected branch's contract parse applies
|
|
* its default, or refuses the field when that branch does not declare it.
|
|
*/
|
|
const branchOnlyField = (
|
|
branches: readonly (z.ZodType | undefined)[],
|
|
): z.ZodType | undefined => {
|
|
const declared = branches.filter(
|
|
(branch): branch is z.ZodType => branch !== undefined,
|
|
);
|
|
const [first] = declared;
|
|
if (
|
|
first === undefined ||
|
|
declared.length === branches.length ||
|
|
declared.some((branch) => branch !== first)
|
|
)
|
|
return undefined;
|
|
if (admitsOmission(first)) return withoutDefault(first);
|
|
const optional = first.optional();
|
|
return first.description === undefined
|
|
? optional
|
|
: optional.describe(first.description);
|
|
};
|
|
|
|
/**
|
|
* An option that must stay omitted when the caller omits it, because the
|
|
* input branch or route the caller selects applies its own default on
|
|
* admission. Help and `--schema` still state the default through the
|
|
* schema metadata.
|
|
*/
|
|
export const withoutDefault = (schema: z.ZodType): z.ZodType => {
|
|
if (!(schema instanceof z.ZodDefault)) return schema;
|
|
const value: unknown = schema.parse(undefined);
|
|
const omittable = (schema.removeDefault() as z.ZodType).optional();
|
|
return omittable.meta({ ...schema.meta(), default: value });
|
|
};
|
|
|
|
/**
|
|
* The union branches a projection takes, and the field it fixes when it
|
|
* selects one value.
|
|
*/
|
|
const selectInputBranches = (
|
|
contract: ProjectedContract,
|
|
selection: CliInputBranches | undefined,
|
|
): {
|
|
readonly inputSchema: ProjectedContract["inputSchema"];
|
|
readonly fixed: readonly [field: string, value: string] | undefined;
|
|
} => {
|
|
const schema = contract.inputSchema;
|
|
if (selection === undefined) return { inputSchema: schema, fixed: undefined };
|
|
const { field, values } = selection;
|
|
if (schema instanceof z.ZodObject)
|
|
throw new Error(`${contract.name} has one input branch`);
|
|
const covered = new Set<string>();
|
|
const selected = schema.options.filter((branch) => {
|
|
const admitted = textValues(
|
|
(branch.shape as Record<string, z.ZodType>)[field],
|
|
);
|
|
if (admitted === undefined)
|
|
throw new Error(`${contract.name}.${field} does not tell branches apart`);
|
|
const chosen = admitted.filter((value) => values.includes(value));
|
|
if (chosen.length > 0 && chosen.length !== admitted.length)
|
|
throw new Error(`${contract.name}.${field} would narrow an input branch`);
|
|
for (const value of chosen) covered.add(value);
|
|
return chosen.length > 0;
|
|
});
|
|
if (covered.size !== new Set(values).size)
|
|
throw new Error(`${contract.name}.${field} selects no branch for a value`);
|
|
return {
|
|
inputSchema: selected.length === 1 ? selected[0]! : z.union(selected),
|
|
fixed: values.length === 1 ? [field, values[0]] : undefined,
|
|
};
|
|
};
|
|
|
|
const inputFields = (
|
|
contract: ProjectedContract,
|
|
unprojectedFields: ReadonlySet<string>,
|
|
): {
|
|
readonly shape: Record<string, z.ZodType>;
|
|
/** Fields whose value selects an input branch. */
|
|
readonly selectors: ReadonlySet<string>;
|
|
} => {
|
|
const schema = contract.inputSchema;
|
|
if (schema instanceof z.ZodObject)
|
|
return {
|
|
shape: schema.shape as Record<string, z.ZodType>,
|
|
selectors: new Set(),
|
|
};
|
|
const shapes = schema.options.map(
|
|
(option) => option.shape as Record<string, z.ZodType>,
|
|
);
|
|
const names = new Set(shapes.flatMap((shape) => Object.keys(shape)));
|
|
const selectors = new Set<string>();
|
|
const shape = Object.fromEntries(
|
|
[...names].map((field) => {
|
|
const branches = shapes.map((shape) => shape[field]);
|
|
const [first] = branches;
|
|
if (branches.every((branch) => branch === first)) return [field, first!];
|
|
const selector =
|
|
branchSelectingFlag(branches) ?? branchSelectingChoice(branches);
|
|
if (selector !== undefined) {
|
|
selectors.add(field);
|
|
return [field, selector];
|
|
}
|
|
const branchOnly = branchOnlyField(branches);
|
|
if (branchOnly !== undefined) return [field, branchOnly];
|
|
if (
|
|
!unprojectedFields.has(field) ||
|
|
branches.some((branch) => branch === undefined)
|
|
)
|
|
throw new Error(
|
|
`${contract.name}.${field} differs between input branches and has no argv projection`,
|
|
);
|
|
return [field, z.union(branches as z.ZodType[])];
|
|
}),
|
|
);
|
|
return { shape, selectors };
|
|
};
|
|
|
|
/**
|
|
* The CLI spelling of a contract whose whole input is one JSON document:
|
|
* inline JSON, a JSON file path, or `-` for standard input.
|
|
*/
|
|
export interface CliDocumentProjection<
|
|
Field extends string,
|
|
CliOptions extends CliOptionShape = CliOptionShape,
|
|
> {
|
|
/** Omitted for the contract's own command; see `CliContractProjection`. */
|
|
readonly command?: string;
|
|
readonly description: string;
|
|
/** Help for the document argument. */
|
|
readonly document: string;
|
|
/**
|
|
* Property paths of caller paths inside the document. Each nonblank string
|
|
* there that is not a URL is resolved against the working directory.
|
|
*/
|
|
readonly callerPaths?: readonly (readonly string[])[];
|
|
/**
|
|
* Optional top-level fields this one-shot command does not admit, each with
|
|
* the reason; `--schema` leaves them out of the document.
|
|
*/
|
|
readonly omit?: { readonly [Key in Field]?: string };
|
|
/** Options no contract field owns, keyed by their CLI key. */
|
|
readonly cliOptions?: CliOptions;
|
|
/**
|
|
* The operation runs on the target an MCP session holds open. The CLI takes
|
|
* it as the `path` positional before the document.
|
|
*/
|
|
readonly sessionTarget?: CliSessionTarget;
|
|
/**
|
|
* The contract's optional `detail` field is taken as `--detail` beside the
|
|
* document, with `--evidence_output`: the command delivers complete
|
|
* Evidence or a summary saved beside a bundle. The document refuses
|
|
* `detail`.
|
|
*/
|
|
readonly evidenceDelivery?: true;
|
|
/**
|
|
* With `evidenceDelivery`, the contract's optional `view` field is taken as
|
|
* `--view` JSON text beside the document and admitted by the contract
|
|
* field's schema before the handler runs. The document refuses `view`.
|
|
*/
|
|
readonly viewDelivery?: CliViewDelivery;
|
|
}
|
|
|
|
/** A complete, framework-neutral CLI command whose input is one JSON document. */
|
|
export interface ContractCliDocumentDescription {
|
|
readonly command: string;
|
|
readonly description: string;
|
|
readonly contract: DocumentContract;
|
|
/** The argument key, which no option shares. */
|
|
readonly key: string;
|
|
/** Help for the document argument. */
|
|
readonly documentDescription: string;
|
|
/**
|
|
* What the document admits as `--schema` advertises it: the contract input
|
|
* without omitted fields, with each Evidence carrier left to its owner.
|
|
*/
|
|
readonly content: z.ZodType;
|
|
/** Property paths of caller paths inside the document. */
|
|
readonly callerPaths: readonly (readonly string[])[];
|
|
/** Contract fields the command does not admit, with the reason. */
|
|
readonly omitted: Readonly<Record<string, string>>;
|
|
/** Contract fields taken as options beside the document, keyed by field. */
|
|
readonly flagged: Readonly<Record<string, string>>;
|
|
/**
|
|
* The refusal of each top-level document field the command does not take
|
|
* in the document: omitted fields and fields taken as options.
|
|
*/
|
|
readonly documentRefusals: Readonly<Record<string, string>>;
|
|
/** The session target positional, taken before the document, if any. */
|
|
readonly sessionTarget: ContractCliSessionTarget | undefined;
|
|
/** Options that select Evidence delivery, for `evidenceDelivery`. */
|
|
readonly deliveryOptions: readonly CliOnlyOption[];
|
|
/**
|
|
* The delivery the parsed options select, admitted before the handler
|
|
* runs; undefined without `evidenceDelivery`.
|
|
*/
|
|
readonly admitDelivery: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Result<CliEvidenceDeliveryChoice | undefined, AnalysisInputError>;
|
|
readonly cliOnlyOptions: readonly CliOnlyOption[];
|
|
/** The parsed values of the projection's CLI-only options. */
|
|
readonly cliOptionValues: (
|
|
values: Readonly<Record<string, unknown>>,
|
|
) => Readonly<Record<string, unknown>>;
|
|
}
|
|
|
|
/**
|
|
* The document field at `path` as the CLI admits it: a caller path the
|
|
* command resolves against the working directory, so a relative spelling is
|
|
* admitted where the contract requires an absolute one. Unions and wrappers
|
|
* keep their other branches; clones keep the source's registry metadata.
|
|
*/
|
|
const admitDocumentCallerPath = (
|
|
schema: z.ZodType,
|
|
path: readonly string[],
|
|
): z.ZodType => {
|
|
const [head, ...tail] = path;
|
|
if (head === undefined) {
|
|
const admitted =
|
|
core(schema) instanceof z.ZodArray
|
|
? z.array(cliJsonCallerPathSchema)
|
|
: cliJsonCallerPathSchema;
|
|
const field = admitsOmission(schema) ? admitted.optional() : admitted;
|
|
return schema.description === undefined
|
|
? field
|
|
: field.describe(schema.description);
|
|
}
|
|
if (
|
|
schema instanceof z.ZodOptional ||
|
|
schema instanceof z.ZodExactOptional ||
|
|
schema instanceof z.ZodDefault ||
|
|
schema instanceof z.ZodPrefault ||
|
|
schema instanceof z.ZodNullable ||
|
|
schema instanceof z.ZodReadonly
|
|
)
|
|
return z.clone(
|
|
schema,
|
|
{
|
|
...schema.def,
|
|
innerType: admitDocumentCallerPath(schema.unwrap() as z.ZodType, path),
|
|
},
|
|
{ parent: true },
|
|
);
|
|
if (schema instanceof z.ZodUnion)
|
|
return z.clone(
|
|
schema,
|
|
{
|
|
...schema.def,
|
|
options: schema.options.map((option) =>
|
|
admitDocumentCallerPath(option as z.ZodType, path),
|
|
),
|
|
},
|
|
{ parent: true },
|
|
);
|
|
if (schema instanceof z.ZodObject && Object.hasOwn(schema.shape, head))
|
|
return z.clone(
|
|
schema,
|
|
{
|
|
...schema.def,
|
|
shape: {
|
|
...schema.shape,
|
|
[head]: admitDocumentCallerPath(
|
|
schema.shape[head] as z.ZodType,
|
|
tail,
|
|
),
|
|
},
|
|
},
|
|
{ parent: true },
|
|
);
|
|
return schema;
|
|
};
|
|
|
|
/** The CLI key of a JSON input document. */
|
|
const DOCUMENT_KEY = "inputJson";
|
|
|
|
/**
|
|
* Describe the options that supply fields of an opening or source contract,
|
|
* and admit what the caller selected with a target as that contract's
|
|
* `path`. Each option admits its field's own schema, narrowed to the
|
|
* projected values.
|
|
*/
|
|
const describeTargetOpening = (
|
|
opening: CliTargetOpening | undefined,
|
|
): {
|
|
readonly options: readonly ContractCliOpeningOption[];
|
|
readonly admit: (
|
|
operation: string,
|
|
values: Readonly<Record<string, unknown>>,
|
|
target: string,
|
|
) => Result<Readonly<Record<string, unknown>>, AnalysisInputError>;
|
|
} => {
|
|
const opener = opening?.contract.name ?? "";
|
|
const shape = (opening?.contract.inputSchema.shape ?? {}) as Record<
|
|
string,
|
|
z.ZodType
|
|
>;
|
|
const options: readonly ContractCliOpeningOption[] = Object.entries(
|
|
opening?.fields ?? {},
|
|
).map(([field, projected]) => {
|
|
const declared = shape[field];
|
|
if (declared === undefined || field === SESSION_TARGET_KEY)
|
|
throw new Error(`${opener} has no option field ${field}`);
|
|
if (!admitsOmission(declared))
|
|
throw new Error(`${opener}.${field} is required`);
|
|
let schema: z.ZodType;
|
|
if (projected.callerPath === true) {
|
|
if (!(core(declared) instanceof z.ZodString))
|
|
throw new Error(`${opener}.${field} is not a path`);
|
|
schema = localPathStringSchema.optional();
|
|
} else if (projected.values === undefined) {
|
|
assertArgvField(opener, field, declared);
|
|
schema = argvDecimal(argvOptional(declared));
|
|
} else {
|
|
for (const value of projected.values)
|
|
if (!declared.safeParse(value).success)
|
|
throw new Error(`${opener}.${field} does not admit ${value}`);
|
|
schema = z.enum(projected.values).optional();
|
|
}
|
|
const description =
|
|
projected.description ?? describedThroughWrappers(declared);
|
|
if (description !== undefined) schema = schema.describe(description);
|
|
return {
|
|
field,
|
|
key: projected.name ?? camelCase(field),
|
|
description,
|
|
schema,
|
|
callerPath: projected.callerPath === true,
|
|
};
|
|
});
|
|
const keyOf = new Map(options.map(({ field, key }) => [field, key]));
|
|
const callerPaths: ReadonlySet<string> = new Set(
|
|
options.flatMap(({ field, callerPath }) => (callerPath ? [field] : [])),
|
|
);
|
|
return {
|
|
options,
|
|
admit: (operation, values, target) => {
|
|
if (opening === undefined) return ok({});
|
|
const selected = Object.fromEntries(
|
|
options.flatMap(({ field, key }) =>
|
|
values[key] === undefined ? [] : [[field, values[key]]],
|
|
),
|
|
);
|
|
// The target itself was admitted as its positional.
|
|
if (Object.keys(selected).length === 0) return ok({});
|
|
const candidate = {
|
|
...Object.fromEntries(
|
|
Object.entries(selected).map(([field, value]) => [
|
|
field,
|
|
callerPaths.has(field)
|
|
? absoluteCallerPath(value as string)
|
|
: value,
|
|
]),
|
|
),
|
|
[SESSION_TARGET_KEY]: absoluteCallerPath(target),
|
|
};
|
|
const admitted = opening.contract.inputSchema.safeParse(candidate);
|
|
if (!admitted.success)
|
|
return err(
|
|
analysisInputErrorFromIssues(
|
|
operation,
|
|
admitted.error.issues.map((issue) => {
|
|
const [field, ...rest] = issue.path;
|
|
const key =
|
|
typeof field === "string" ? keyOf.get(field) : undefined;
|
|
return key === undefined
|
|
? issue
|
|
: { ...issue, path: [key, ...rest] };
|
|
}),
|
|
selected,
|
|
),
|
|
);
|
|
const data = admitted.data as Readonly<Record<string, unknown>>;
|
|
return ok(
|
|
Object.fromEntries(
|
|
Object.keys(selected).map((field) => [
|
|
field,
|
|
callerPaths.has(field) ? selected[field] : data[field],
|
|
]),
|
|
),
|
|
);
|
|
},
|
|
};
|
|
};
|
|
|
|
/** Describe the target positional and its opening options. */
|
|
const describeSessionTarget = (
|
|
target: CliSessionTarget | undefined,
|
|
): ContractCliSessionTarget | undefined => {
|
|
if (target === undefined) return undefined;
|
|
const { options, admit } = describeTargetOpening(target.open);
|
|
return {
|
|
key: SESSION_TARGET_KEY,
|
|
schema: localPathStringSchema.describe(target.description),
|
|
opening: target.open?.contract.name,
|
|
options,
|
|
admitOpening: (operation, values) =>
|
|
admit(operation, values, values[SESSION_TARGET_KEY] as string),
|
|
};
|
|
};
|
|
|
|
/**
|
|
* Describe the Evidence target positionals of required contract fields and
|
|
* the options of their shared source contract. Every target is admitted by
|
|
* the source input, so a source option holds for each one.
|
|
*/
|
|
const describeEvidenceTargets = (
|
|
contract: ProjectedContract,
|
|
shape: Readonly<Record<string, z.ZodType>>,
|
|
targets: CliEvidenceTargets<string> | undefined,
|
|
): ContractCliEvidenceTargets | undefined => {
|
|
if (targets === undefined) return undefined;
|
|
const { options, admit } = describeTargetOpening(targets.source);
|
|
const described = Object.entries(targets.fields).flatMap(
|
|
([field, projected]) => {
|
|
if (projected === undefined) return [];
|
|
const declared = shape[field];
|
|
if (declared === undefined)
|
|
throw new Error(`${contract.name} has no input field ${field}`);
|
|
if (admitsOmission(declared))
|
|
throw new Error(`${contract.name}.${field} is not a required field`);
|
|
return [
|
|
{
|
|
field,
|
|
key: projected.name ?? camelCase(field),
|
|
schema: localPathStringSchema.describe(projected.description),
|
|
},
|
|
];
|
|
},
|
|
);
|
|
if (described.length === 0)
|
|
throw new Error(`${contract.name} declares no Evidence target`);
|
|
return {
|
|
source: targets.source.contract.name,
|
|
targets: described,
|
|
options,
|
|
sourceFlags: Object.fromEntries(
|
|
options.map(({ field, key }) => [field, `--${optionFlagName(key)}`]),
|
|
),
|
|
admitSource: (operation, values) => {
|
|
let admitted: Result<
|
|
Readonly<Record<string, unknown>>,
|
|
AnalysisInputError
|
|
> = ok({});
|
|
for (const { key } of described) {
|
|
admitted = admit(operation, values, values[key] as string);
|
|
if (!admitted.ok) return admitted;
|
|
}
|
|
return admitted;
|
|
},
|
|
};
|
|
};
|
|
|
|
/**
|
|
* The delivery `--detail`, `--evidence_output` and `--view` select beside a
|
|
* JSON document. The view is admitted by the contract's own `view` field; a
|
|
* page is selected from a retained summary, so it needs summary delivery.
|
|
*/
|
|
const admitDocumentDelivery = (
|
|
operation: string,
|
|
viewDelivery: (CliViewDelivery & { readonly schema: z.ZodType }) | undefined,
|
|
values: Readonly<Record<string, unknown>>,
|
|
): Result<CliEvidenceDeliveryChoice, AnalysisInputError> => {
|
|
let view: AnalysisViewRequest | undefined;
|
|
if (viewDelivery !== undefined) {
|
|
const decoded = parseCliJsonOption(
|
|
operation,
|
|
"view",
|
|
values.view as string | undefined,
|
|
viewDelivery.invalidJson,
|
|
);
|
|
if (!decoded.ok) return decoded;
|
|
if (decoded.value !== undefined) {
|
|
const candidate = { view: decoded.value };
|
|
const parsed = z
|
|
.object({ view: viewDelivery.schema })
|
|
.safeParse(candidate);
|
|
if (!parsed.success)
|
|
return err(
|
|
analysisInputErrorFromIssues(
|
|
operation,
|
|
parsed.error.issues,
|
|
candidate,
|
|
),
|
|
);
|
|
const selected = parsed.data.view as object;
|
|
view = (
|
|
viewDelivery.kind === undefined
|
|
? selected
|
|
: { kind: viewDelivery.kind, ...selected }
|
|
) as AnalysisViewRequest;
|
|
}
|
|
}
|
|
const detail =
|
|
(values.detail as "complete" | "summary" | undefined) ??
|
|
(view === undefined ? "complete" : "summary");
|
|
const delivery: CliEvidenceDeliveryChoice = {
|
|
detail,
|
|
evidenceOutput: values.evidence_output as string | undefined,
|
|
...(view === undefined ? {} : { view }),
|
|
};
|
|
const refused = cliEvidenceDeliveryInputError({ ...delivery, operation });
|
|
return refused === undefined ? ok(delivery) : err(refused);
|
|
};
|
|
|
|
/**
|
|
* Describe a contract command that takes its whole input as one JSON
|
|
* document. The handler admits the decoded document with the contract's
|
|
* owner, which borrows Evidence carriers rather than parsing them here.
|
|
*/
|
|
export const describeContractDocumentCommand = <
|
|
Contract extends DocumentContract,
|
|
CliOptions extends CliOptionShape = CliOptionShape,
|
|
>(
|
|
contract: Contract,
|
|
projection: CliDocumentProjection<ContractField<Contract>, CliOptions>,
|
|
): ContractCliDocumentDescription => {
|
|
const omitted: Readonly<Record<string, string>> = Object.fromEntries(
|
|
Object.entries(projection.omit ?? {}).filter(
|
|
(entry): entry is [string, string] => typeof entry[1] === "string",
|
|
),
|
|
);
|
|
const evidenceDelivery = projection.evidenceDelivery === true;
|
|
const { viewDelivery } = projection;
|
|
if (viewDelivery !== undefined && !evidenceDelivery)
|
|
throw new Error(`${contract.name} view delivery requires evidenceDelivery`);
|
|
// Delivery fields keep their contract names as CLI keys.
|
|
const flagged: Readonly<Record<string, string>> = Object.fromEntries(
|
|
(evidenceDelivery
|
|
? viewDelivery === undefined
|
|
? ["detail"]
|
|
: ["detail", "view"]
|
|
: []
|
|
).map((field) => [field, field]),
|
|
);
|
|
for (const field of Object.keys(flagged))
|
|
if (Object.hasOwn(omitted, field))
|
|
throw new Error(
|
|
`${contract.name}.${field} is both omitted and an option`,
|
|
);
|
|
const removed = [...Object.keys(omitted), ...Object.keys(flagged)];
|
|
let admitted: z.ZodType = contract.inputSchema;
|
|
let viewSchema: z.ZodType = z.never();
|
|
if (removed.length > 0) {
|
|
const schema = contract.inputSchema;
|
|
if (!(schema instanceof z.ZodObject))
|
|
throw new Error(`${contract.name} omits fields from a union input`);
|
|
const shape = schema.shape as Record<string, z.ZodType>;
|
|
for (const field of removed)
|
|
if (!Object.hasOwn(shape, field) || !admitsOmission(shape[field]!))
|
|
throw new Error(`${contract.name}.${field} is not an optional field`);
|
|
if (viewDelivery !== undefined) viewSchema = shape.view!;
|
|
admitted = schema.omit(
|
|
Object.fromEntries(removed.map((field) => [field, true])) as never,
|
|
);
|
|
}
|
|
const callerPaths = projection.callerPaths ?? [];
|
|
for (const path of callerPaths)
|
|
admitted = admitDocumentCallerPath(admitted, path);
|
|
const cliOptions: CliOptionShape = projection.cliOptions ?? {};
|
|
const deliveryOptions: readonly CliOnlyOption[] = Object.entries({
|
|
...(evidenceDelivery
|
|
? {
|
|
detail:
|
|
viewDelivery?.viewSelectsSummary === true
|
|
? analysisEvidenceDeliveryOptions.detail.unwrap().optional()
|
|
: analysisEvidenceDeliveryOptions.detail,
|
|
evidence_output: analysisEvidenceDeliveryOptions.evidence_output,
|
|
}
|
|
: {}),
|
|
...(viewDelivery === undefined
|
|
? {}
|
|
: {
|
|
view: z.string().optional().describe(viewOptionHelp(viewDelivery)),
|
|
}),
|
|
}).map(([key, schema]: [string, z.ZodType]) => ({
|
|
key,
|
|
description: schema.description,
|
|
schema,
|
|
}));
|
|
const sessionTarget = describeSessionTarget(projection.sessionTarget);
|
|
const keys = [
|
|
DOCUMENT_KEY,
|
|
...(sessionTarget === undefined
|
|
? []
|
|
: [sessionTarget.key, ...sessionTarget.options.map(({ key }) => key)]),
|
|
...Object.keys(cliOptions),
|
|
...deliveryOptions.map(({ key }) => key),
|
|
];
|
|
if (new Set(keys).size !== keys.length)
|
|
throw new Error(`${contract.name} projects two fields to one CLI key`);
|
|
const documentRefusals: Readonly<Record<string, string>> = {
|
|
...Object.fromEntries(
|
|
Object.entries(omitted).map(([field, reason]) => [
|
|
field,
|
|
`${field} is not accepted by this command: ${reason}`,
|
|
]),
|
|
),
|
|
...Object.fromEntries(
|
|
Object.entries(flagged).map(([field, key]) => [
|
|
field,
|
|
`${field} is not accepted in the document: pass --${key} beside it`,
|
|
]),
|
|
),
|
|
};
|
|
return {
|
|
command: projectedCommand(contract, projection.command),
|
|
description: projection.description,
|
|
contract,
|
|
key: DOCUMENT_KEY,
|
|
documentDescription: projection.document,
|
|
content: getEvidenceInputContract(admitted).frameSchema,
|
|
callerPaths,
|
|
omitted,
|
|
flagged,
|
|
documentRefusals,
|
|
deliveryOptions,
|
|
admitDelivery: (values) =>
|
|
evidenceDelivery
|
|
? admitDocumentDelivery(
|
|
contract.name,
|
|
viewDelivery === undefined
|
|
? undefined
|
|
: { ...viewDelivery, schema: viewSchema },
|
|
values,
|
|
)
|
|
: ok(undefined),
|
|
sessionTarget,
|
|
cliOnlyOptions: Object.entries(cliOptions).map(([key, schema]) => ({
|
|
key,
|
|
description: schema.description,
|
|
schema,
|
|
})),
|
|
cliOptionValues: (values) =>
|
|
Object.fromEntries(
|
|
Object.keys(cliOptions).flatMap((key) =>
|
|
values[key] === undefined ? [] : [[key, values[key]]],
|
|
),
|
|
),
|
|
};
|
|
};
|
|
|
|
/** Derive the CLI parameters of one contract from its input schema and projection. */
|
|
export const describeContractCommand = <
|
|
Contract extends ProjectedContract,
|
|
CliOptions extends CliOptionShape = CliOptionShape,
|
|
>(
|
|
contract: Contract,
|
|
projection: CliContractProjection<ContractField<Contract>, CliOptions>,
|
|
): ContractCliDescription => {
|
|
const evidenceDelivery = projection.evidenceDelivery === true;
|
|
const { viewDelivery } = projection;
|
|
if (viewDelivery !== undefined && !evidenceDelivery)
|
|
throw new Error(`${contract.name} view delivery requires evidenceDelivery`);
|
|
const deliveryFields: ReadonlySet<string> = new Set(
|
|
evidenceDelivery
|
|
? viewDelivery === undefined
|
|
? ["detail"]
|
|
: ["detail", "view"]
|
|
: [],
|
|
);
|
|
if (
|
|
projection.sessionTarget !== undefined &&
|
|
projection.evidenceTargets !== undefined
|
|
)
|
|
throw new Error(
|
|
`${contract.name} takes both a session target and Evidence targets`,
|
|
);
|
|
const targetFields: ReadonlySet<string> = new Set(
|
|
Object.keys(projection.evidenceTargets?.fields ?? {}),
|
|
);
|
|
const handlerFields: readonly string[] = projection.handlerFields ?? [];
|
|
const branches = selectInputBranches(contract, projection.inputBranches);
|
|
const fixedFields: ReadonlyMap<string, string> = new Map(
|
|
branches.fixed === undefined ? [] : [branches.fixed],
|
|
);
|
|
// Fields argv never supplies: the delivery's, the omitted ones, those the
|
|
// handler supplies with each target's source Evidence, those it fills
|
|
// from CLI-only values, and the one the selected branch fixes.
|
|
const unprojectedFields: ReadonlySet<string> = new Set([
|
|
...deliveryFields,
|
|
...Object.keys(projection.omit ?? {}),
|
|
...targetFields,
|
|
...handlerFields,
|
|
...fixedFields.keys(),
|
|
]);
|
|
const { shape, selectors } = inputFields(
|
|
{ name: contract.name, inputSchema: branches.inputSchema },
|
|
unprojectedFields,
|
|
);
|
|
if (viewDelivery !== undefined && !admitsOmission(shape.view ?? z.never()))
|
|
throw new Error(`${contract.name} has no optional input field view`);
|
|
const positionals: readonly string[] = projection.positionals ?? [];
|
|
const selectorOptions: Readonly<
|
|
Record<string, CliSelectorOption | undefined>
|
|
> = projection.selectorOptions ?? {};
|
|
for (const field of Object.keys(selectorOptions))
|
|
if (!positionals.includes(field))
|
|
throw new Error(`${contract.name}.${field} is not a positional selector`);
|
|
const callerPaths: ReadonlySet<string> = new Set(
|
|
projection.callerPaths ?? [],
|
|
);
|
|
const fieldProjections: Readonly<
|
|
Record<string, CliContractFieldProjection | undefined>
|
|
> = projection.fields ?? {};
|
|
const jsonTextFields: ReadonlySet<string> = new Set(
|
|
projection.jsonText ?? [],
|
|
);
|
|
const jsonInputFields: Readonly<Record<string, string | undefined>> =
|
|
projection.jsonInputs ?? {};
|
|
for (const field of Object.keys(jsonInputFields))
|
|
if (Object.hasOwn(projection.runtimeJson ?? {}, field))
|
|
throw new Error(`${contract.name}.${field} is JSON text and JSON input`);
|
|
const jsonInputChecks: Readonly<
|
|
Record<string, CliJsonInputCheck | undefined>
|
|
> = projection.jsonInputChecks ?? {};
|
|
for (const field of Object.keys(jsonInputChecks))
|
|
if (!Object.hasOwn(jsonInputFields, field))
|
|
throw new Error(
|
|
`${contract.name}.${field} is checked but not a JSON input`,
|
|
);
|
|
const runtimeJsonFields: Readonly<Record<string, string | undefined>> = {
|
|
...projection.runtimeJson,
|
|
...jsonInputFields,
|
|
};
|
|
const nullFlags: Readonly<Record<string, CliNullFlag | undefined>> =
|
|
projection.nullFlags ?? {};
|
|
const omitted: Readonly<Record<string, string>> = Object.fromEntries(
|
|
Object.entries(projection.omit ?? {}).filter(
|
|
(entry): entry is [string, string] => typeof entry[1] === "string",
|
|
),
|
|
);
|
|
for (const field of [
|
|
...positionals,
|
|
...callerPaths,
|
|
...jsonTextFields,
|
|
...Object.keys(runtimeJsonFields),
|
|
...Object.keys(nullFlags),
|
|
...Object.keys(projection.flatten ?? {}),
|
|
...Object.keys(fieldProjections),
|
|
...Object.keys(omitted),
|
|
]) {
|
|
if (!Object.hasOwn(shape, field))
|
|
throw new Error(`${contract.name} has no input field ${field}`);
|
|
if (targetFields.has(field))
|
|
throw new Error(`${contract.name}.${field} is an Evidence target`);
|
|
if (handlerFields.includes(field))
|
|
throw new Error(`${contract.name}.${field} is filled by the handler`);
|
|
if (fixedFields.has(field))
|
|
throw new Error(`${contract.name}.${field} is fixed by its input branch`);
|
|
}
|
|
const fieldGroups: Readonly<Record<string, CliFieldGroup | undefined>> =
|
|
projection.fieldGroups ?? {};
|
|
const groupedFields = new Set<string>();
|
|
const projectedFields = new Set([
|
|
...positionals,
|
|
...callerPaths,
|
|
...jsonTextFields,
|
|
...Object.keys(runtimeJsonFields),
|
|
...Object.keys(nullFlags),
|
|
...Object.keys(projection.flatten ?? {}),
|
|
...Object.keys(fieldProjections),
|
|
...Object.keys(omitted),
|
|
...unprojectedFields,
|
|
]);
|
|
for (const group of Object.values(fieldGroups))
|
|
for (const field of group?.fields ?? []) {
|
|
if (!Object.hasOwn(shape, field))
|
|
throw new Error(`${contract.name} has no input field ${field}`);
|
|
if (projectedFields.has(field) || groupedFields.has(field))
|
|
throw new Error(`${contract.name}.${field} is projected twice`);
|
|
// The option may be omitted, so each member may be.
|
|
if (!admitsOmission(shape[field]!))
|
|
throw new Error(`${contract.name}.${field} is a required group member`);
|
|
groupedFields.add(field);
|
|
}
|
|
for (const field of handlerFields) {
|
|
if (!Object.hasOwn(shape, field))
|
|
throw new Error(`${contract.name} has no input field ${field}`);
|
|
if (targetFields.has(field))
|
|
throw new Error(`${contract.name}.${field} is an Evidence target`);
|
|
}
|
|
for (const field of Object.keys(omitted))
|
|
if (!admitsOmission(shape[field]!))
|
|
throw new Error(`${contract.name}.${field} is required on the CLI`);
|
|
|
|
const parameter = (field: string): ContractCliParameter => {
|
|
const inbound = inboundView(shape[field]!);
|
|
const declared = inbound ?? shape[field]!;
|
|
const projected = fieldProjections[field];
|
|
const callerPath = callerPaths.has(field);
|
|
const delivery = deliveryFields.has(field);
|
|
const viewSelection = delivery && field === "view";
|
|
const jsonText = jsonTextFields.has(field);
|
|
const runtimeJson = viewSelection
|
|
? viewDelivery?.invalidJson
|
|
: runtimeJsonFields[field];
|
|
const jsonInput = !viewSelection && Object.hasOwn(jsonInputFields, field);
|
|
const nullFlag = nullFlags[field]?.key;
|
|
const key = projected?.name ?? camelCase(field);
|
|
let schema: z.ZodType;
|
|
if (runtimeJson !== undefined) {
|
|
// Argv requires the text of a required field; the contract admits
|
|
// what it decodes to. Help and `--schema` show a contract default as
|
|
// the JSON text that decodes to it. Empty text is neither JSON nor a
|
|
// file path, so a JSON input refuses it before any input is read.
|
|
const text = jsonInput ? z.string().min(1) : z.string();
|
|
schema =
|
|
declared instanceof z.ZodDefault
|
|
? text.default(JSON.stringify(declared.parse(undefined)))
|
|
: admitsOmission(declared)
|
|
? text.optional()
|
|
: text;
|
|
if (viewSelection && viewDelivery !== undefined)
|
|
schema = schema.describe(viewOptionHelp(viewDelivery));
|
|
} else if (nullFlag !== undefined) {
|
|
// The flag spells null, so the option itself takes only a value.
|
|
if (!declared.safeParse(null).success)
|
|
throw new Error(`${contract.name}.${field} does not admit null`);
|
|
assertArgvField(contract.name, field, declared);
|
|
schema = argvDecimal(core(declared).optional());
|
|
} else if (delivery)
|
|
schema =
|
|
viewDelivery?.viewSelectsSummary === true
|
|
? analysisEvidenceDeliveryOptions.detail.unwrap().optional()
|
|
: analysisEvidenceDeliveryOptions.detail;
|
|
else if (jsonText) schema = jsonTextField(declared, optionFlagName(key));
|
|
else if (callerPath) {
|
|
const admitted =
|
|
core(declared) instanceof z.ZodArray
|
|
? z.array(localPathStringSchema)
|
|
: localPathStringSchema;
|
|
schema = admitsOmission(declared) ? admitted.optional() : admitted;
|
|
} else {
|
|
assertArgvField(contract.name, field, declared);
|
|
schema = argvDecimal(argvOptional(declared));
|
|
}
|
|
if (projected?.default !== undefined) {
|
|
if (
|
|
admitsOmission(declared) ||
|
|
!declared.safeParse(projected.default).success
|
|
)
|
|
throw new Error(
|
|
`${contract.name}.${field} cannot take the CLI default ${String(projected.default)}`,
|
|
);
|
|
const described = schema.description;
|
|
schema = schema.default(projected.default as never);
|
|
if (described !== undefined) schema = schema.describe(described);
|
|
}
|
|
const described =
|
|
projected?.description ??
|
|
schema.description ??
|
|
describedThroughWrappers(declared);
|
|
if (described !== undefined && described !== schema.description)
|
|
schema = schema.describe(described);
|
|
if (!delivery && projected?.default === undefined)
|
|
schema = withoutDefault(schema);
|
|
const description = schema.description ?? described;
|
|
const value = core(declared);
|
|
const selector = selectorOptions[field];
|
|
let selectorOption: ContractCliSelectorOption | undefined;
|
|
if (selector !== undefined) {
|
|
if (!(value instanceof z.ZodString))
|
|
throw new Error(`${contract.name}.${field} is not a text selector`);
|
|
// A selector names one object. Its contract refuses an empty one, so
|
|
// the CLI and MCP agree without a CLI-only rule.
|
|
if (value.safeParse("").success)
|
|
throw new Error(`${contract.name}.${field} admits an empty selector`);
|
|
// Either spelling may supply the selector.
|
|
schema = schema.optional();
|
|
if (description !== undefined) schema = schema.describe(description);
|
|
selectorOption = {
|
|
key: selector.name,
|
|
valueKey: `--${selector.name}`,
|
|
description: selector.description,
|
|
schema: schema.describe(selector.description),
|
|
kind: selector.kind ?? "text",
|
|
required: selector.required === true || !admitsOmission(declared),
|
|
alternative:
|
|
selector.alternative === undefined
|
|
? undefined
|
|
: {
|
|
key: selector.alternative.name,
|
|
valueKey: `--${selector.alternative.name}`,
|
|
schema: selector.alternative.schema
|
|
.optional()
|
|
.describe(selector.alternative.description),
|
|
selects: selector.alternative.selects,
|
|
},
|
|
};
|
|
}
|
|
return {
|
|
field,
|
|
key,
|
|
positional: positionals.includes(field),
|
|
alias: projected?.alias,
|
|
description,
|
|
schema,
|
|
inbound: inbound !== undefined,
|
|
booleanFlag: value instanceof z.ZodBoolean,
|
|
cliDefault: projected?.default,
|
|
repeatable: value instanceof z.ZodArray,
|
|
decimal: value instanceof z.ZodNumber,
|
|
callerPath,
|
|
delivery,
|
|
jsonText,
|
|
viewSelection,
|
|
runtimeJson,
|
|
jsonInput,
|
|
checkJsonInput: jsonInputChecks[field],
|
|
nullFlag,
|
|
member: undefined,
|
|
selectorOption,
|
|
group: undefined,
|
|
};
|
|
};
|
|
const flattened: Readonly<Record<string, CliFlattenedMembers | undefined>> =
|
|
projection.flatten ?? {};
|
|
const memberParameters = (
|
|
field: string,
|
|
path: readonly string[],
|
|
declared: z.ZodType,
|
|
members: CliFlattenedMembers,
|
|
enclosingRequired: boolean,
|
|
): ContractCliParameter[] => {
|
|
const object = core(declared);
|
|
const name = [field, ...path].join(".");
|
|
if (!(object instanceof z.ZodObject))
|
|
throw new Error(`${contract.name}.${name} is not an object`);
|
|
// A member is required when it and every enclosing object are.
|
|
const required = enclosingRequired && !admitsOmission(declared);
|
|
// A flattened positional field takes each member as a positional, in
|
|
// member order, so every member must be required.
|
|
const positional = path.length === 0 && positionals.includes(field);
|
|
if (positional && !required)
|
|
throw new Error(
|
|
`${contract.name}.${name} is an optional positional object`,
|
|
);
|
|
const memberShape = object.shape as Record<string, z.ZodType>;
|
|
if (
|
|
Object.keys(members).toSorted().join() !==
|
|
Object.keys(memberShape).toSorted().join()
|
|
)
|
|
throw new Error(`${contract.name}.${name} flattens other members`);
|
|
const memberParameterList = Object.entries(memberShape).flatMap(
|
|
([member, memberDeclared]) => {
|
|
const projected = members[member]!;
|
|
const memberPath = [...path, member];
|
|
const memberName = [field, ...memberPath].join(".");
|
|
if ("flatten" in projected) {
|
|
if (positional)
|
|
throw new Error(
|
|
`${contract.name}.${memberName} is a positional object`,
|
|
);
|
|
return memberParameters(
|
|
field,
|
|
memberPath,
|
|
memberDeclared,
|
|
projected.flatten,
|
|
required,
|
|
);
|
|
}
|
|
const memberRequired = required && !admitsOmission(memberDeclared);
|
|
if (positional && !memberRequired)
|
|
throw new Error(
|
|
`${contract.name}.${memberName} is an optional positional`,
|
|
);
|
|
const omittable = (schema: z.ZodType) =>
|
|
memberRequired ? schema : schema.optional();
|
|
const callerPath = projected.callerPath === true;
|
|
let schema: z.ZodType;
|
|
if (callerPath) {
|
|
if (!(core(memberDeclared) instanceof z.ZodString))
|
|
throw new Error(`${contract.name}.${memberName} is not a path`);
|
|
schema = omittable(localPathStringSchema);
|
|
} else {
|
|
assertArgvField(contract.name, memberName, memberDeclared);
|
|
// An omitted member stays omitted; the contract applies its default.
|
|
schema = argvDecimal(omittable(withoutDefault(memberDeclared)));
|
|
}
|
|
const description =
|
|
projected.description ?? describedThroughWrappers(memberDeclared);
|
|
if (description !== undefined) schema = schema.describe(description);
|
|
const value = core(memberDeclared);
|
|
return [
|
|
{
|
|
field,
|
|
key: projected.name ?? camelCase(member),
|
|
positional,
|
|
alias: projected.alias,
|
|
description,
|
|
schema,
|
|
inbound: false,
|
|
booleanFlag: value instanceof z.ZodBoolean,
|
|
cliDefault: undefined,
|
|
repeatable: value instanceof z.ZodArray,
|
|
decimal: value instanceof z.ZodNumber,
|
|
callerPath,
|
|
delivery: false,
|
|
jsonText: false,
|
|
viewSelection: false,
|
|
runtimeJson: undefined,
|
|
jsonInput: false,
|
|
checkJsonInput: undefined,
|
|
nullFlag: undefined,
|
|
member: memberPath,
|
|
selectorOption: undefined,
|
|
group: undefined,
|
|
},
|
|
];
|
|
},
|
|
);
|
|
// Argv supplies an object only through its given members, so a required
|
|
// object needs a required member; otherwise omitting them all drops it.
|
|
if (
|
|
required &&
|
|
memberParameterList.every(
|
|
({ schema }) => schema.safeParse(undefined).success,
|
|
)
|
|
)
|
|
throw new Error(`${contract.name}.${name} has no required member`);
|
|
return memberParameterList;
|
|
};
|
|
const parameters: ContractCliParameter[] = [
|
|
...positionals,
|
|
...Object.keys(shape).filter(
|
|
(field) =>
|
|
!positionals.includes(field) &&
|
|
!Object.hasOwn(omitted, field) &&
|
|
!targetFields.has(field) &&
|
|
!handlerFields.includes(field) &&
|
|
!fixedFields.has(field) &&
|
|
!groupedFields.has(field),
|
|
),
|
|
].flatMap((field) =>
|
|
flattened[field] === undefined
|
|
? [parameter(field)]
|
|
: memberParameters(field, [], shape[field]!, flattened[field], true),
|
|
);
|
|
for (const [key, group] of Object.entries(fieldGroups))
|
|
if (group !== undefined)
|
|
parameters.push({
|
|
field: key,
|
|
key,
|
|
positional: false,
|
|
alias: undefined,
|
|
description: group.description,
|
|
schema: z.string().optional().describe(group.description),
|
|
inbound: false,
|
|
booleanFlag: false,
|
|
cliDefault: undefined,
|
|
repeatable: false,
|
|
decimal: false,
|
|
callerPath: false,
|
|
delivery: false,
|
|
jsonText: false,
|
|
viewSelection: false,
|
|
runtimeJson: group.invalidJson,
|
|
jsonInput: false,
|
|
checkJsonInput: undefined,
|
|
nullFlag: undefined,
|
|
member: undefined,
|
|
selectorOption: undefined,
|
|
group: group.fields,
|
|
});
|
|
const cliOptions: CliOptionShape = projection.cliOptions ?? {};
|
|
const cliPositionalKeys: readonly string[] = projection.cliPositionals ?? [];
|
|
for (const key of cliPositionalKeys)
|
|
if (!Object.hasOwn(cliOptions, key))
|
|
throw new Error(`${contract.name} has no CLI option ${key}`);
|
|
const cliPositionals: readonly CliOnlyOption[] = cliPositionalKeys.map(
|
|
(key) => ({
|
|
key,
|
|
description: cliOptions[key]!.description,
|
|
schema: cliOptions[key]!,
|
|
}),
|
|
);
|
|
const cliOnlyOptions: readonly CliOnlyOption[] = [
|
|
...Object.values(nullFlags).flatMap((flag) =>
|
|
flag === undefined
|
|
? []
|
|
: [
|
|
[
|
|
flag.key,
|
|
z.boolean().default(false).describe(flag.description),
|
|
] satisfies [string, z.ZodType],
|
|
],
|
|
),
|
|
...Object.entries(
|
|
evidenceDelivery
|
|
? Object.hasOwn(shape, "detail")
|
|
? { evidence_output: analysisEvidenceDeliveryOptions.evidence_output }
|
|
: analysisEvidenceDeliveryOptions
|
|
: {},
|
|
),
|
|
...Object.entries(cliOptions).filter(
|
|
([key]) => !cliPositionalKeys.includes(key),
|
|
),
|
|
].map(([key, schema]: [string, z.ZodType]) => ({
|
|
key,
|
|
description: schema.description,
|
|
schema,
|
|
}));
|
|
const sessionTarget = describeSessionTarget(projection.sessionTarget);
|
|
const evidenceTargets = describeEvidenceTargets(
|
|
contract,
|
|
shape,
|
|
projection.evidenceTargets,
|
|
);
|
|
// Keys the command adds beside the contract parameters.
|
|
const sessionTargetKeys = [
|
|
...(sessionTarget === undefined
|
|
? []
|
|
: [sessionTarget.key, ...sessionTarget.options.map(({ key }) => key)]),
|
|
...(evidenceTargets === undefined
|
|
? []
|
|
: [
|
|
...evidenceTargets.targets.map(({ key }) => key),
|
|
...evidenceTargets.options.map(({ key }) => key),
|
|
]),
|
|
];
|
|
const selectorKeys = parameters.flatMap(({ selectorOption }) =>
|
|
selectorOption === undefined
|
|
? []
|
|
: [
|
|
selectorOption.key,
|
|
...(selectorOption.alternative === undefined
|
|
? []
|
|
: [selectorOption.alternative.key]),
|
|
],
|
|
);
|
|
// A selector option may share its positional's key: argv keeps them apart.
|
|
const keys = new Set([
|
|
...sessionTargetKeys,
|
|
...parameters.map(({ key }) => key),
|
|
...cliOnlyOptions.map(({ key }) => key),
|
|
...cliPositionalKeys,
|
|
]);
|
|
const optionKeys = new Set([
|
|
...sessionTargetKeys,
|
|
...parameters.flatMap(({ key, positional }) => (positional ? [] : [key])),
|
|
...cliOnlyOptions.map(({ key }) => key),
|
|
...selectorKeys,
|
|
]);
|
|
if (
|
|
keys.size !==
|
|
sessionTargetKeys.length +
|
|
parameters.length +
|
|
cliOnlyOptions.length +
|
|
cliPositionalKeys.length ||
|
|
optionKeys.size !==
|
|
sessionTargetKeys.length +
|
|
parameters.filter(({ positional }) => !positional).length +
|
|
cliOnlyOptions.length +
|
|
selectorKeys.length
|
|
)
|
|
throw new Error(`${contract.name} projects two fields to one CLI key`);
|
|
const cliOptionDependencies = Object.fromEntries(
|
|
Object.entries(projection.cliOptionDependencies ?? {}).filter(
|
|
(entry): entry is [string, readonly string[]] => entry[1] !== undefined,
|
|
),
|
|
);
|
|
for (const [key, required] of Object.entries(cliOptionDependencies))
|
|
for (const dependency of [key, ...required])
|
|
if (!keys.has(dependency))
|
|
throw new Error(`${contract.name} has no CLI option ${dependency}`);
|
|
const keyOf = new Map(
|
|
parameters.flatMap(({ field, key, member }) =>
|
|
member === undefined ? [[field, key] as const] : [],
|
|
),
|
|
);
|
|
const rename = (field: string): string => keyOf.get(field) ?? field;
|
|
|
|
const toContractInput = (
|
|
values: Readonly<Record<string, unknown>>,
|
|
): Record<string, unknown> => {
|
|
const input: Record<string, unknown> = Object.fromEntries(fixedFields);
|
|
for (const {
|
|
field,
|
|
key,
|
|
callerPath,
|
|
delivery,
|
|
member,
|
|
selectorOption,
|
|
group,
|
|
} of parameters) {
|
|
// The named spelling is preserved when both agree.
|
|
const value =
|
|
(selectorOption === undefined
|
|
? undefined
|
|
: values[selectorOption.valueKey]) ?? values[key];
|
|
if (value === undefined || delivery || member !== undefined) continue;
|
|
if (group !== undefined) {
|
|
// A decoded group supplies each member it names as that field.
|
|
if (isRecord(value))
|
|
for (const grouped of group)
|
|
if (Object.hasOwn(value, grouped)) input[grouped] = value[grouped];
|
|
continue;
|
|
}
|
|
input[field] = !callerPath
|
|
? value
|
|
: Array.isArray(value)
|
|
? value.map((path: string) => absoluteCallerPath(path))
|
|
: absoluteCallerPath(value as string);
|
|
}
|
|
// Any member given supplies each enclosing object, so the contract names
|
|
// a missing companion; an omitted member stays omitted, not undefined.
|
|
for (const { field, key, member, callerPath } of parameters) {
|
|
const value = values[key];
|
|
if (member === undefined || value === undefined) continue;
|
|
let object = (input[field] ??= {}) as Record<string, unknown>;
|
|
for (const enclosing of member.slice(0, -1))
|
|
object = (object[enclosing] ??= {}) as Record<string, unknown>;
|
|
object[member.at(-1)!] = callerPath
|
|
? absoluteCallerPath(value as string)
|
|
: value;
|
|
}
|
|
for (const { field, nullFlag } of parameters)
|
|
if (nullFlag !== undefined && values[nullFlag] === true)
|
|
input[field] = null;
|
|
return input;
|
|
};
|
|
const nullFlagLimits = parameters.flatMap(({ key, nullFlag }) =>
|
|
nullFlag === undefined ? [] : [[nullFlag, key] as const],
|
|
);
|
|
|
|
// Cross-field rules belong to the contract: run its own object checks on
|
|
// the options mapped to contract names, then name CLI keys. Positional
|
|
// values are not visible here; the service's contract parse still
|
|
// enforces every rule.
|
|
const checks =
|
|
projection.crossFieldRules === "argv"
|
|
? (contract.inputSchema._zod.def.checks ?? [])
|
|
: [];
|
|
if (
|
|
checks.length > 0 &&
|
|
parameters.some(({ runtimeJson }) => runtimeJson !== undefined)
|
|
)
|
|
throw new Error(
|
|
`${contract.name} decodes JSON when it runs, after argv cross-field rules`,
|
|
);
|
|
const contractChecks = z
|
|
.object({})
|
|
.loose()
|
|
.check(...(checks as z.core.$ZodCheck<Record<string, unknown>>[]));
|
|
const checkOptions =
|
|
checks.length === 0 && nullFlagLimits.length === 0
|
|
? undefined
|
|
: (options: Readonly<Record<string, unknown>>) => {
|
|
const conflicts = nullFlagLimits.flatMap(([flag, limit]) => {
|
|
if (options[flag] !== true || options[limit] === undefined)
|
|
return [];
|
|
const message = `${flag} and ${limit} are mutually exclusive`;
|
|
const issue: z.core.$ZodIssueCustom = {
|
|
code: "custom",
|
|
path: [flag],
|
|
message,
|
|
input: undefined,
|
|
};
|
|
return [{ path: [flag], message, issue }];
|
|
});
|
|
// Checks observe execution defaults, while the command retains the
|
|
// caller's raw selections. Resolve only omitted fields: supplied
|
|
// options have already passed argv admission, and JSON text is not
|
|
// decoded until the command runs.
|
|
const checkInput = toContractInput(options);
|
|
if (checks.length > 0)
|
|
for (const [field, declared] of Object.entries(shape)) {
|
|
if (Object.hasOwn(checkInput, field)) continue;
|
|
const omitted = declared.safeParse(undefined);
|
|
if (omitted.success && omitted.data !== undefined)
|
|
checkInput[field] = omitted.data;
|
|
}
|
|
const result = contractChecks.safeParse(checkInput);
|
|
return result.success
|
|
? conflicts
|
|
: [
|
|
...conflicts,
|
|
...result.error.issues.map((issue) => {
|
|
const [field, ...rest] = issue.path;
|
|
return {
|
|
path:
|
|
typeof field === "string"
|
|
? [rename(field), ...rest]
|
|
: issue.path,
|
|
message: issue.message,
|
|
issue,
|
|
};
|
|
}),
|
|
];
|
|
};
|
|
|
|
return {
|
|
command: projectedCommand(contract, projection.command),
|
|
description: projection.description,
|
|
contract,
|
|
parameters,
|
|
cliOnlyOptions,
|
|
cliPositionals,
|
|
omitted,
|
|
handlerFields,
|
|
fixedFields: Object.fromEntries(fixedFields),
|
|
fields: shape,
|
|
optionConstraints: projectObjectConstraints(
|
|
contract,
|
|
// A grouped field is a JSON member, not an option, so an object rule
|
|
// naming it has no CLI projection.
|
|
(field) => {
|
|
if (groupedFields.has(field))
|
|
throw new Error(
|
|
`${contract.name}.${field} is grouped but named by an input rule`,
|
|
);
|
|
return rename(field);
|
|
},
|
|
new Set([...unprojectedFields, ...selectors]),
|
|
cliOptionDependencies,
|
|
nullFlagLimits,
|
|
),
|
|
checkOptions,
|
|
toContractInput,
|
|
callerInputs: (values) =>
|
|
Object.fromEntries(
|
|
parameters.flatMap(({ field, key, callerPath, member }) => {
|
|
const value = values[key];
|
|
return callerPath && value !== undefined
|
|
? [
|
|
[
|
|
[field, ...(member ?? [])].join("."),
|
|
value as string | readonly string[],
|
|
],
|
|
]
|
|
: [];
|
|
}),
|
|
),
|
|
cliOptionValues: (values) =>
|
|
Object.fromEntries(
|
|
Object.keys(cliOptions).flatMap((key) =>
|
|
values[key] === undefined ? [] : [[key, values[key]]],
|
|
),
|
|
),
|
|
sessionTarget,
|
|
evidenceTargets,
|
|
inputBinding: {
|
|
operation: contract.name,
|
|
fields: Object.fromEntries(
|
|
[
|
|
// A selector field is named by its own option: its positional may
|
|
// share another key, and selection issues already use the option.
|
|
...parameters.flatMap(({ field, key, member, selectorOption }) =>
|
|
member === undefined
|
|
? [{ field, key: selectorOption?.key ?? key }]
|
|
: [],
|
|
),
|
|
...(evidenceTargets?.targets ?? []),
|
|
].flatMap(({ field, key }) => (key === field ? [] : [[field, key]])),
|
|
),
|
|
flags: Object.fromEntries(
|
|
parameters.flatMap(
|
|
({
|
|
field,
|
|
key,
|
|
member,
|
|
positional,
|
|
delivery,
|
|
group,
|
|
selectorOption,
|
|
}) => {
|
|
if (delivery) return [];
|
|
// A positional selector is also set by its named option.
|
|
if (positional)
|
|
return selectorOption === undefined
|
|
? []
|
|
: [[field, `--${optionFlagName(selectorOption.key)}`] as const];
|
|
const flag = `--${optionFlagName(key)}`;
|
|
// A field group's option supplies each of its contract fields.
|
|
if (group !== undefined)
|
|
return group.map((grouped) => [grouped, flag] as const);
|
|
return [
|
|
[
|
|
member === undefined ? field : [field, ...member].join("."),
|
|
flag,
|
|
] as const,
|
|
];
|
|
},
|
|
),
|
|
),
|
|
},
|
|
evidenceDelivery,
|
|
admit: (values) => {
|
|
const selectedValues: Record<string, unknown> = { ...values };
|
|
for (const { key, selectorOption } of parameters) {
|
|
if (selectorOption === undefined) continue;
|
|
const selected = selectSpelledSelector(
|
|
contract.name,
|
|
selectorOption,
|
|
values[key] as string | undefined,
|
|
values,
|
|
);
|
|
if (!selected.ok) return selected;
|
|
selectedValues[selectorOption.valueKey] = selected.value;
|
|
}
|
|
return admitInvocation(
|
|
contract,
|
|
{
|
|
evidenceDelivery,
|
|
viewDelivery,
|
|
parameters,
|
|
shape,
|
|
wholeInput:
|
|
sessionTarget === undefined &&
|
|
evidenceTargets === undefined &&
|
|
handlerFields.length === 0,
|
|
checkedFields: Object.keys(jsonInputChecks),
|
|
},
|
|
selectedValues,
|
|
toContractInput,
|
|
rename,
|
|
);
|
|
},
|
|
admitDeliveryOptions: (values) => {
|
|
const decoded = decodeInlineJson(contract.name, parameters, values);
|
|
if (!decoded.ok) return decoded;
|
|
if (!evidenceDelivery) return ok(undefined);
|
|
const view =
|
|
viewDelivery === undefined
|
|
? undefined
|
|
: (decoded.value[rename("view")] as AnalysisViewRequest | undefined);
|
|
// The view's own refusal comes first, as in full admission, where the
|
|
// contract admits the view before the delivery rules apply.
|
|
if (view !== undefined) {
|
|
const checked = shape.view!.safeParse(view);
|
|
if (!checked.success)
|
|
return err(
|
|
analysisInputErrorFromIssues(
|
|
contract.name,
|
|
checked.error.issues.map((issue) => ({
|
|
...issue,
|
|
path: ["view", ...issue.path],
|
|
})),
|
|
{ view },
|
|
),
|
|
);
|
|
}
|
|
const detail = decoded.value[rename("detail")] as
|
|
| "complete"
|
|
| "summary"
|
|
| undefined;
|
|
const refused = cliEvidenceDeliveryInputError({
|
|
operation: contract.name,
|
|
detail: detail ?? (view === undefined ? "complete" : "summary"),
|
|
evidenceOutput: decoded.value.evidence_output as string | undefined,
|
|
view,
|
|
});
|
|
return refused === undefined ? ok(undefined) : err(refused);
|
|
},
|
|
};
|
|
};
|
|
|
|
/**
|
|
* Decode each inline run-time JSON option. JSON inputs, which may name a
|
|
* file, are read and decoded by the command before admission.
|
|
*/
|
|
const decodeInlineJson = (
|
|
operation: string,
|
|
parameters: readonly ContractCliParameter[],
|
|
values: Readonly<Record<string, unknown>>,
|
|
): Result<Record<string, unknown>, AnalysisInputError> => {
|
|
const decoded: Record<string, unknown> = { ...values };
|
|
for (const { key, runtimeJson, jsonInput, group } of parameters) {
|
|
if (runtimeJson === undefined || jsonInput) continue;
|
|
const parsed = parseCliJsonOption(
|
|
operation,
|
|
key,
|
|
values[key] as string | undefined,
|
|
runtimeJson,
|
|
);
|
|
if (!parsed.ok) return parsed;
|
|
if (group !== undefined && parsed.value !== undefined) {
|
|
const members = admitGroupMembers(
|
|
operation,
|
|
key,
|
|
group,
|
|
runtimeJson,
|
|
parsed.value,
|
|
);
|
|
if (!members.ok) return members;
|
|
}
|
|
decoded[key] = parsed.value;
|
|
}
|
|
return ok(decoded);
|
|
};
|
|
|
|
/** A group is a JSON object whose members are its own fields. */
|
|
const admitGroupMembers = (
|
|
operation: string,
|
|
key: string,
|
|
group: readonly string[],
|
|
invalidJson: string,
|
|
value: unknown,
|
|
): Result<void, AnalysisInputError> => {
|
|
if (!isRecord(value))
|
|
return err(
|
|
new AnalysisInputError(operation, undefined, [
|
|
{
|
|
path: [key],
|
|
reason: "invalid_format",
|
|
expected: "JSON",
|
|
message: invalidJson,
|
|
},
|
|
]),
|
|
);
|
|
const members = z.strictObject(
|
|
Object.fromEntries(group.map((field) => [field, z.unknown().optional()])),
|
|
);
|
|
const admitted = members.safeParse(value);
|
|
return admitted.success
|
|
? ok(undefined)
|
|
: err(
|
|
analysisInputErrorFromIssues(
|
|
operation,
|
|
admitted.error.issues.map((issue) => ({
|
|
...issue,
|
|
path: [key, ...issue.path],
|
|
})),
|
|
{ [key]: value },
|
|
),
|
|
);
|
|
};
|
|
|
|
/**
|
|
* Select one selector from its positional, its named option and any
|
|
* alternative option. The named option and the alternative agree only as
|
|
* text; the positional then agrees with either as the selector's kind, and
|
|
* a conflict names the option the caller used.
|
|
*/
|
|
const selectSpelledSelector = (
|
|
operation: string,
|
|
selector: ContractCliSelectorOption,
|
|
positional: string | undefined,
|
|
values: Readonly<Record<string, unknown>>,
|
|
): Result<string | undefined, AnalysisInputError> => {
|
|
const { alternative } = selector;
|
|
let named = values[selector.valueKey] as string | undefined;
|
|
let option = selector.key;
|
|
const otherSpelling =
|
|
alternative === undefined
|
|
? undefined
|
|
: (values[alternative.valueKey] as string | undefined);
|
|
if (alternative !== undefined && otherSpelling !== undefined) {
|
|
const merged = selectCliAnalysisSelector(
|
|
named,
|
|
alternative.selects(otherSpelling),
|
|
{ option: alternative.key, operation, kind: "text", required: false },
|
|
);
|
|
if (!merged.ok) return merged;
|
|
named = merged.value;
|
|
option = alternative.key;
|
|
}
|
|
const selected = selectCliAnalysisSelector(positional, named, {
|
|
option,
|
|
operation,
|
|
kind: selector.kind,
|
|
required: selector.required,
|
|
});
|
|
// The named spelling is preserved when both agree.
|
|
return selected.ok ? ok(named ?? positional) : selected;
|
|
};
|
|
|
|
/**
|
|
* Decode run-time JSON, then map the values to the contract input and the
|
|
* selected delivery. When the projection decodes JSON at run time, the
|
|
* decoded input, delivery and view are admitted together by the contract
|
|
* input schema, so the contract's own rules and messages apply. When argv
|
|
* supplies the whole contract input, it is parsed once the same way and the
|
|
* handler receives the parse or the refusal.
|
|
*/
|
|
const admitInvocation = (
|
|
contract: ProjectedContract,
|
|
command: {
|
|
readonly evidenceDelivery: boolean;
|
|
readonly viewDelivery: CliViewDelivery | undefined;
|
|
readonly parameters: readonly ContractCliParameter[];
|
|
readonly shape: Readonly<Record<string, z.ZodType>>;
|
|
/**
|
|
* Argv supplies every contract field: no session target, Evidence
|
|
* target or handler fills one.
|
|
*/
|
|
readonly wholeInput: boolean;
|
|
/**
|
|
* `jsonInputChecks` fields. Their checks already admitted the decoded
|
|
* documents, so the whole-input parse does not walk and copy them again.
|
|
*/
|
|
readonly checkedFields: readonly string[];
|
|
},
|
|
values: Readonly<Record<string, unknown>>,
|
|
toContractInput: ContractCliDescription["toContractInput"],
|
|
rename: (field: string) => string,
|
|
): Result<ContractCliAdmission, AnalysisInputError> => {
|
|
const {
|
|
evidenceDelivery,
|
|
viewDelivery,
|
|
parameters,
|
|
shape,
|
|
wholeInput,
|
|
checkedFields,
|
|
} = command;
|
|
const inline = decodeInlineJson(contract.name, parameters, values);
|
|
if (!inline.ok) return inline;
|
|
const decoded = inline.value;
|
|
const input = toContractInput(decoded);
|
|
const detail = evidenceDelivery
|
|
? (decoded[rename("detail")] as "complete" | "summary" | undefined)
|
|
: undefined;
|
|
let view: object | undefined;
|
|
let parsed: unknown;
|
|
let parseWholeInput: ContractCliAdmission["parseWholeInput"];
|
|
const runtimeJson = parameters.some(
|
|
({ runtimeJson }) => runtimeJson !== undefined,
|
|
);
|
|
const selected =
|
|
viewDelivery === undefined ? undefined : decoded[rename("view")];
|
|
const candidate = {
|
|
...input,
|
|
...(detail === undefined || !Object.hasOwn(shape, "detail")
|
|
? {}
|
|
: { detail }),
|
|
...(selected === undefined ? {} : { view: selected }),
|
|
};
|
|
const schema = contract.inputSchema;
|
|
const unchecked =
|
|
checkedFields.length > 0 && schema instanceof z.ZodObject
|
|
? schema.omit(
|
|
Object.fromEntries(
|
|
checkedFields.map((field) => [field, true]),
|
|
) as Record<string, true> & Record<number, never>,
|
|
)
|
|
: undefined;
|
|
const parseCandidate = (): Result<unknown, AnalysisInputError> => {
|
|
if (unchecked !== undefined) {
|
|
const rest: Record<string, unknown> = { ...candidate };
|
|
const documents: Record<string, unknown> = {};
|
|
for (const field of checkedFields)
|
|
if (Object.hasOwn(rest, field)) {
|
|
documents[field] = rest[field];
|
|
delete rest[field];
|
|
}
|
|
const admitted = unchecked.safeParse(rest);
|
|
return admitted.success
|
|
? ok({ ...admitted.data, ...documents })
|
|
: err(
|
|
analysisInputErrorFromIssues(
|
|
contract.name,
|
|
admitted.error.issues,
|
|
candidate,
|
|
),
|
|
);
|
|
}
|
|
const admitted = schema.safeParse(candidate);
|
|
return admitted.success
|
|
? ok(admitted.data)
|
|
: err(
|
|
analysisInputErrorFromIssues(
|
|
contract.name,
|
|
admitted.error.issues,
|
|
candidate,
|
|
),
|
|
);
|
|
};
|
|
if (runtimeJson || (wholeInput && viewDelivery !== undefined)) {
|
|
// The delivery needs the admitted view, and run-time JSON is refused
|
|
// here, so these parse now.
|
|
const admitted = parseCandidate();
|
|
if (admitted.ok) {
|
|
parsed = admitted.value;
|
|
if (viewDelivery !== undefined)
|
|
({ view } = admitted.value as { readonly view?: object });
|
|
} else if (runtimeJson) return admitted;
|
|
else parseWholeInput = () => admitted;
|
|
} else if (wholeInput) {
|
|
// Only a handler that reads the parse pays for it, once.
|
|
let memo: Result<unknown, AnalysisInputError> | undefined;
|
|
parseWholeInput = () => (memo ??= parseCandidate());
|
|
}
|
|
if (!evidenceDelivery)
|
|
return ok({ input, parsed, parseWholeInput, delivery: undefined });
|
|
const delivery: CliEvidenceDeliveryChoice = {
|
|
detail: detail ?? (view === undefined ? "complete" : "summary"),
|
|
evidenceOutput: decoded.evidence_output as string | undefined,
|
|
...(view === undefined
|
|
? {}
|
|
: {
|
|
view: (viewDelivery?.kind === undefined
|
|
? view
|
|
: { kind: viewDelivery.kind, ...view }) as AnalysisViewRequest,
|
|
}),
|
|
};
|
|
const refused = cliEvidenceDeliveryInputError({
|
|
...delivery,
|
|
operation: contract.name,
|
|
});
|
|
return refused === undefined
|
|
? ok({ input, parsed, parseWholeInput, delivery })
|
|
: err(refused);
|
|
};
|
|
|
|
/**
|
|
* Describe each contract an operation option selects. Each must project to
|
|
* the registered command's exact arguments, options and object-level option
|
|
* rules, so the help and schema the registered contract advertises hold for
|
|
* every choice.
|
|
*/
|
|
export const describeOperationChoices = (
|
|
description: ContractCliDescription,
|
|
projection: CliContractProjection<string, CliOptionShape>,
|
|
): ReadonlyMap<unknown, ContractCliDescription> => {
|
|
const choices = new Map<unknown, ContractCliDescription>();
|
|
const signature = (described: ContractCliDescription): string =>
|
|
JSON.stringify([
|
|
described.parameters.map(({ key, positional, schema }) => [
|
|
key,
|
|
positional,
|
|
z.toJSONSchema(schema, { unrepresentable: "any" }),
|
|
]),
|
|
described.optionConstraints ?? null,
|
|
]);
|
|
const expected = signature(description);
|
|
for (const [value, contract] of Object.entries(
|
|
projection.operationBy?.contracts ?? {},
|
|
)) {
|
|
const described = describeContractCommand(contract, projection);
|
|
if (signature(described) !== expected)
|
|
throw new Error(
|
|
`${contract.name} does not project to ${description.command}'s options`,
|
|
);
|
|
choices.set(value, described);
|
|
}
|
|
return choices;
|
|
};
|