@weftlet/toolkit 0.6.1 → 0.7.1

package/dist/interfaces/code-coverage.d.ts

@@ -0,0 +1,46 @@
+import type { CodeCoverageService } from '@weftlet/core';
+export declare const graphCoverageTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            projectRoot: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            maxItems: {
+                type: string;
+                minimum: number;
+                maximum: number;
+                default: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleCodeCoverage(service: CodeCoverageService, value: unknown): Promise<import("@weftlet/core").CodeCoverageReport>;
+export declare function codeCoverageRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    projectRoot?: string | undefined;
+    snapshotId: string;
+    maxItems: number;
+};

package/dist/interfaces/code-coverage.js

@@ -0,0 +1,18 @@
+import { parseCodeCoverageRequest } from '../graph/code-coverage-request.js';
+import { parseGraphQueryArgs } from './graph-query-args.js';
+export const graphCoverageTool = {
+    name: 'graph.coverage',
+    description: 'Inspect saved TypeScript-family source coverage. Page package boundaries, then select an exact projectRoot to page files. Distinguishes code-root selection, requested index entries, observed SCIP documents, cross-package references and unresolved evidence. Missing or zero observations never prove no impact. Does not rebuild evidence.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['snapshotId'], properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 }, projectRoot: { type: 'string', minLength: 1, maxLength: 8192 },
+            maxItems: { type: 'integer', minimum: 1, maximum: 200, default: 50 }, continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        } }, annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleCodeCoverage(service, value) {
+    return service.coverage(parseCodeCoverageRequest(value));
+}
+export function codeCoverageRequestFromArgs(args) {
+    return parseCodeCoverageRequest(parseGraphQueryArgs(args, 'coverage', {
+        '--snapshot': 'snapshotId', '--project': 'projectRoot', '--max-items': 'maxItems', '--continuation': 'continuation',
+    }));
+}

package/dist/interfaces/graph-compatibility.d.ts

@@ -0,0 +1,35 @@
+import type { ContractCompatibilityService } from '@weftlet/core';
+export declare const graphCompatibilityTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            producerFactId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            consumerFactId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphCompatibility(service: ContractCompatibilityService, value: unknown): Promise<import("@weftlet/core").ContractCompatibilityReport>;
+export declare function graphCompatibilityRequestFromArgs(args: readonly string[]): import("@weftlet/core").ContractCompatibilityRequest;

package/dist/interfaces/graph-compatibility.js

@@ -0,0 +1,21 @@
+import { parseContractCompatibilityRequest } from '../graph/compatibility-request.js';
+import { parseGraphQueryArgs } from './graph-query-args.js';
+export const graphCompatibilityTool = {
+    name: 'graph.compatibility',
+    description: 'Compare two exact cited producer/consumer numeric obligations from a saved snapshot. Reports subset, insufficient guarantee, disjoint constraints, required revalidation or unknown. Advisory only: never proves implementation, current-diff validity or a CI policy violation. Discover assertion IDs with graph.neighbors.',
+    inputSchema: { type: 'object', additionalProperties: false,
+        required: ['snapshotId', 'producerFactId', 'consumerFactId'], properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            producerFactId: { type: 'string', minLength: 1, maxLength: 8192 },
+            consumerFactId: { type: 'string', minLength: 1, maxLength: 8192 },
+        } },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphCompatibility(service, value) {
+    return service.assess(parseContractCompatibilityRequest(value));
+}
+export function graphCompatibilityRequestFromArgs(args) {
+    return parseContractCompatibilityRequest(parseGraphQueryArgs(args, 'compatibility', {
+        '--snapshot': 'snapshotId', '--producer-fact': 'producerFactId', '--consumer-fact': 'consumerFactId',
+    }));
+}

package/dist/interfaces/graph-exploration.d.ts

@@ -0,0 +1,59 @@
+import { type GraphExplorationService } from '@weftlet/core';
+export declare const graphNeighborsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            nodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            direction: {
+                type: string;
+                enum: string[];
+            };
+            predicates: {
+                type: string;
+                maxItems: 16;
+                items: {
+                    type: string;
+                    enum: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+                };
+            };
+            maxFacts: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphNeighbors(service: GraphExplorationService, value: unknown): Promise<import("@weftlet/core").GraphNeighborhood>;
+export declare function graphNeighborsRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    nodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxFacts: number;
+};

package/dist/interfaces/graph-exploration.js

@@ -0,0 +1,27 @@
+import { parseGraphQueryArgs } from './graph-query-args.js';
+import { graphPredicates } from '@weftlet/core';
+import { parseGraphNeighborsRequest } from '../graph/neighborhood-request.js';
+export const graphNeighborsTool = {
+    name: 'graph.neighbors',
+    description: 'Look up an exact node ID in an explicit saved snapshot and page through its cited one-hop relationships. Follow returned neighbor IDs to explore further; no hydration or model calls.',
+    inputSchema: {
+        type: 'object', additionalProperties: false, required: ['snapshotId', 'nodeId'],
+        properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            nodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            direction: { type: 'string', enum: ['incoming', 'outgoing', 'both'] },
+            predicates: { type: 'array', maxItems: graphPredicates.length, items: { type: 'string', enum: [...graphPredicates] } },
+            maxFacts: { type: 'integer', minimum: 1, maximum: 200 },
+            continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        },
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphNeighbors(service, value) {
+    return service.neighbors(parseGraphNeighborsRequest(value));
+}
+export function graphNeighborsRequestFromArgs(args) {
+    const flags = { '--snapshot': 'snapshotId', '--node': 'nodeId',
+        '--direction': 'direction', '--predicate': 'predicates', '--max-facts': 'maxFacts', '--continuation': 'continuation' };
+    return parseGraphNeighborsRequest(parseGraphQueryArgs(args, 'neighbors', flags));
+}

package/dist/interfaces/graph-paths.d.ts

@@ -0,0 +1,77 @@
+import { type GraphPathQueryService } from '@weftlet/core';
+export declare const graphPathsTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            fromNodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            toNodeId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            direction: {
+                type: string;
+                enum: string[];
+            };
+            predicates: {
+                type: string;
+                maxItems: 16;
+                items: {
+                    type: string;
+                    enum: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+                };
+            };
+            maxDepth: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxPaths: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxSteps: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            continuation: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function handleGraphPaths(service: GraphPathQueryService, value: unknown): Promise<import("@weftlet/core").GraphPaths>;
+export declare function graphPathsRequestFromArgs(args: readonly string[]): {
+    continuation?: string | undefined;
+    snapshotId: string;
+    fromNodeId: string;
+    toNodeId: string;
+    direction: "incoming" | "outgoing" | "both";
+    predicates: ("references" | "realizes" | "implementedBy" | "consumes" | "emits" | "persistsTo" | "governedBy" | "definedBy" | "verifiedBy" | "operationallyOwnedBy" | "decisionAuthority" | "routesThrough" | "authorizedBy" | "sourcedFrom" | "contains" | "calls")[];
+    maxDepth: number;
+    maxPaths: number;
+    maxSteps: number;
+};

package/dist/interfaces/graph-paths.js

@@ -0,0 +1,31 @@
+import { parseGraphQueryArgs } from './graph-query-args.js';
+import { graphPredicates } from '@weftlet/core';
+import { parseGraphPathsRequest } from '../graph/path-request.js';
+export const graphPathsTool = {
+    name: 'graph.paths',
+    description: 'Explore simple cited paths between exact node IDs in an explicit saved snapshot. Depth-first assertion order, not shortest/causal paths. Follow continuation with identical selectors; inspect depth/work limits and unexplored frontier. No hydration or model calls.',
+    inputSchema: {
+        type: 'object', additionalProperties: false, required: ['snapshotId', 'fromNodeId', 'toNodeId'],
+        properties: {
+            snapshotId: { type: 'string', minLength: 1, maxLength: 256 },
+            fromNodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            toNodeId: { type: 'string', minLength: 1, maxLength: 8192 },
+            direction: { type: 'string', enum: ['incoming', 'outgoing', 'both'] },
+            predicates: { type: 'array', maxItems: graphPredicates.length, items: { type: 'string', enum: [...graphPredicates] } },
+            maxDepth: { type: 'integer', minimum: 1, maximum: 32 },
+            maxPaths: { type: 'integer', minimum: 1, maximum: 20 },
+            maxSteps: { type: 'integer', minimum: 1, maximum: 10000 },
+            continuation: { type: 'string', minLength: 1, maxLength: 2048 },
+        },
+    },
+    annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false },
+};
+export function handleGraphPaths(service, value) {
+    return service.paths(parseGraphPathsRequest(value));
+}
+export function graphPathsRequestFromArgs(args) {
+    const flags = { '--snapshot': 'snapshotId', '--from': 'fromNodeId', '--to': 'toNodeId',
+        '--direction': 'direction', '--predicate': 'predicates', '--max-depth': 'maxDepth', '--max-paths': 'maxPaths',
+        '--max-steps': 'maxSteps', '--continuation': 'continuation' };
+    return parseGraphPathsRequest(parseGraphQueryArgs(args, 'paths', flags));
+}

package/dist/interfaces/graph-query-args.d.ts

@@ -0,0 +1,2 @@
+/** Shared flag grammar for exact-ID graph queries; semantic validation stays in the query layer. */
+export declare function parseGraphQueryArgs(args: readonly string[], operation: string, flags: Readonly<Record<string, string>>): Record<string, unknown>;

package/dist/interfaces/graph-query-args.js

@@ -0,0 +1,25 @@
+/** Shared flag grammar for exact-ID graph queries; semantic validation stays in the query layer. */
+export function parseGraphQueryArgs(args, operation, flags) {
+    const values = {};
+    for (let index = 0; index < args.length; index++) {
+        const flag = args[index];
+        if (flag === '--json')
+            continue;
+        if (flag !== '--config' && !Object.hasOwn(flags, flag))
+            throw new Error(`Unknown graph ${operation} argument: ${flag}`);
+        const value = args[++index];
+        if (value === undefined || value.startsWith('--'))
+            throw new Error(`Missing value for ${flag}`);
+        if (flag === '--config')
+            continue;
+        const key = flags[flag];
+        if (key === 'predicates')
+            values[key] = [...(values[key] ?? []), value];
+        else {
+            if (Object.hasOwn(values, key))
+                throw new Error(`Repeated graph ${operation} argument: ${flag}`);
+            values[key] = key.startsWith('max') ? Number(value) : value;
+        }
+    }
+    return values;
+}

package/dist/interfaces/mapping-proposals.d.ts

@@ -0,0 +1,204 @@
+import type { MappingProposalService } from '../application/mapping-proposals.js';
+export declare const mappingPlanTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                maxLength: number;
+                type: string;
+                minLength: number;
+            };
+            ruleId: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            documentPath: {
+                type: string;
+                minLength: number;
+                maxLength: number;
+            };
+            files: {
+                type: string;
+                minItems: number;
+                maxItems: number;
+                uniqueItems: boolean;
+                items: {
+                    type: string;
+                    minLength: number;
+                    maxLength: number;
+                };
+            };
+            maxCandidates: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+            maxInputBytes: {
+                type: string;
+                minimum: number;
+                maximum: number;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare const mappingReadTool: {
+    name: string;
+    description: string;
+    inputSchema: {
+        type: "object";
+        additionalProperties: boolean;
+        required: string[];
+        properties: {
+            snapshotId: {
+                maxLength: number;
+                type: string;
+                minLength: number;
+            };
+            key: {
+                type: string;
+                pattern: string;
+            };
+        };
+    };
+    annotations: {
+        readOnlyHint: boolean;
+        destructiveHint: boolean;
+        idempotentHint: boolean;
+        openWorldHint: boolean;
+    };
+};
+export declare function parseMappingRead(value: unknown): {
+    snapshotId: string;
+    key: string;
+};
+export declare function handleMappingTool(service: MappingProposalService, name: string, value: unknown): Promise<{
+    evidenceState: {
+        readonly currentCommit?: string;
+        readonly excludedWorkingChanges: readonly string[];
+        readonly capturedWorkingChanges?: readonly string[];
+        readonly changedSinceCapture?: readonly string[];
+        readonly overlayFreshness?: "current" | "stale" | "unknown";
+        readonly stale: boolean;
+        readonly configurationMatches: boolean;
+        readonly extractionCompatible?: boolean;
+        readonly incompatibleExtractors?: readonly string[];
+        readonly eligibleForCurrentDiffValidation: false;
+    };
+    key: string;
+    cached: boolean;
+    expectedModelRequests: number;
+    timeoutMs: number;
+    automaticRetries: number;
+    markdown: string;
+    ready: boolean;
+    issues: {
+        readonly code: string;
+        readonly path?: string;
+    }[];
+    version: "mapping-proposal-v1";
+    request: Required<import("@weftlet/core").MappingProposalRequest>;
+    snapshot: import("@weftlet/core").ContextPack["snapshot"];
+    snapshotDigest: string;
+    subjectEvidence: readonly import("@weftlet/core").GraphFact[];
+    associations: readonly import("@weftlet/core").GraphFact[];
+    candidates: readonly import("@weftlet/core").MappingCandidate[];
+    candidateEnumeration: {
+        readonly complete: boolean;
+        readonly observed: number;
+        readonly returned: number;
+    };
+    excluded: readonly {
+        readonly path: string;
+        readonly reason: string;
+        readonly count: number;
+    }[];
+    inputBytes: number;
+    inputDigest: string;
+} | {
+    artifact: import("@weftlet/core").MappingProposalArtifact;
+    reused: boolean;
+    evidenceState: {
+        readonly currentCommit?: string;
+        readonly excludedWorkingChanges: readonly string[];
+        readonly capturedWorkingChanges?: readonly string[];
+        readonly changedSinceCapture?: readonly string[];
+        readonly overlayFreshness?: "current" | "stale" | "unknown";
+        readonly stale: boolean;
+        readonly configurationMatches: boolean;
+        readonly extractionCompatible?: boolean;
+        readonly incompatibleExtractors?: readonly string[];
+        readonly eligibleForCurrentDiffValidation: false;
+    } | undefined;
+    markdown: string;
+}>;
+export declare function runMappingsCommand(service: MappingProposalService, args: readonly string[]): Promise<{
+    evidenceState: {
+        readonly currentCommit?: string;
+        readonly excludedWorkingChanges: readonly string[];
+        readonly capturedWorkingChanges?: readonly string[];
+        readonly changedSinceCapture?: readonly string[];
+        readonly overlayFreshness?: "current" | "stale" | "unknown";
+        readonly stale: boolean;
+        readonly configurationMatches: boolean;
+        readonly extractionCompatible?: boolean;
+        readonly incompatibleExtractors?: readonly string[];
+        readonly eligibleForCurrentDiffValidation: false;
+    };
+    key: string;
+    cached: boolean;
+    expectedModelRequests: number;
+    timeoutMs: number;
+    automaticRetries: number;
+    markdown: string;
+    ready: boolean;
+    issues: {
+        readonly code: string;
+        readonly path?: string;
+    }[];
+    version: "mapping-proposal-v1";
+    request: Required<import("@weftlet/core").MappingProposalRequest>;
+    snapshot: import("@weftlet/core").ContextPack["snapshot"];
+    snapshotDigest: string;
+    subjectEvidence: readonly import("@weftlet/core").GraphFact[];
+    associations: readonly import("@weftlet/core").GraphFact[];
+    candidates: readonly import("@weftlet/core").MappingCandidate[];
+    candidateEnumeration: {
+        readonly complete: boolean;
+        readonly observed: number;
+        readonly returned: number;
+    };
+    excluded: readonly {
+        readonly path: string;
+        readonly reason: string;
+        readonly count: number;
+    }[];
+    inputBytes: number;
+    inputDigest: string;
+} | {
+    artifact: import("@weftlet/core").MappingProposalArtifact;
+    reused: boolean;
+    evidenceState: {
+        readonly currentCommit?: string;
+        readonly excludedWorkingChanges: readonly string[];
+        readonly capturedWorkingChanges?: readonly string[];
+        readonly changedSinceCapture?: readonly string[];
+        readonly overlayFreshness?: "current" | "stale" | "unknown";
+        readonly stale: boolean;
+        readonly configurationMatches: boolean;
+        readonly extractionCompatible?: boolean;
+        readonly incompatibleExtractors?: readonly string[];
+        readonly eligibleForCurrentDiffValidation: false;
+    } | undefined;
+    markdown: string;
+}>;

package/dist/interfaces/mapping-proposals.js

@@ -0,0 +1,74 @@
+import { readFile, stat } from 'node:fs/promises';
+import { parseMappingRequest } from '../extraction/mapping-request.js';
+const string = { type: 'string', minLength: 1, maxLength: 8192 };
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false };
+export const mappingPlanTool = { name: 'mapping.plan',
+    description: 'Preview an opt-in mapping proposal against saved committed evidence. Requires an exact rule, approved source document and 1–4 already-linked files. Reports coverage/budget blockers and cache reuse. Never calls a model or changes evidence.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['snapshotId', 'ruleId', 'documentPath', 'files'], properties: {
+            snapshotId: { ...string, maxLength: 256 }, ruleId: string, documentPath: string,
+            files: { type: 'array', minItems: 1, maxItems: 4, uniqueItems: true, items: string },
+            maxCandidates: { type: 'integer', minimum: 1, maximum: 20 }, maxInputBytes: { type: 'integer', minimum: 1, maximum: 131072 },
+        } }, annotations };
+export const mappingReadTool = { name: 'mapping.proposals',
+    description: 'Read one saved mapping proposal or abstention by exact snapshot and artifact key. Proposals are inferred/unreviewed, never approval or proof of compliance. Rationale is untrusted model content. Follow exact symbol IDs using graph.neighbors. Never calls providers or refreshes evidence.',
+    inputSchema: { type: 'object', additionalProperties: false, required: ['snapshotId', 'key'], properties: {
+            snapshotId: { ...string, maxLength: 256 }, key: { type: 'string', pattern: '^[a-f0-9]{64}$' },
+        } }, annotations };
+export function parseMappingRead(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw Error('Mapping read requires snapshotId and key');
+    const r = value;
+    if (Object.keys(r).sort().join(',') !== 'key,snapshotId' || typeof r.snapshotId !== 'string' || !r.snapshotId.trim() || r.snapshotId.length > 256 ||
+        typeof r.key !== 'string' || !/^[a-f0-9]{64}$/.test(r.key))
+        throw Error('Mapping read requires an exact snapshotId and 64-character artifact key');
+    return { snapshotId: r.snapshotId, key: r.key };
+}
+export async function handleMappingTool(service, name, value) {
+    if (name === mappingPlanTool.name)
+        return service.plan(parseMappingRequest(value));
+    if (name !== mappingReadTool.name)
+        throw Error('Unknown mapping tool');
+    const request = parseMappingRead(value);
+    return service.read(request.snapshotId, request.key);
+}
+export async function runMappingsCommand(service, args) {
+    const [operation, ...flags] = args;
+    if (!['plan', 'propose', 'read'].includes(operation ?? ''))
+        throw Error('Usage: weftlet mappings plan|propose --request request.json; mappings read --snapshot ID --key KEY');
+    const values = new Map();
+    const allowed = operation === 'read' ? ['--snapshot', '--key', '--config', '--json'] : ['--request', '--config', '--json', ...(operation === 'propose' ? ['--allow-model', '--quiet'] : [])];
+    for (let i = 0; i < flags.length; i++) {
+        const flag = flags[i];
+        if (!allowed.includes(flag) || values.has(flag))
+            throw Error('Unknown or repeated mappings argument');
+        if (['--json', '--quiet', '--allow-model'].includes(flag))
+            values.set(flag, true);
+        else {
+            const value = flags[++i];
+            if (!value || value.startsWith('--'))
+                throw Error('Missing mappings argument');
+            values.set(flag, value);
+        }
+    }
+    if (operation === 'read') {
+        const r = parseMappingRead({ snapshotId: values.get('--snapshot'), key: values.get('--key') });
+        return service.read(r.snapshotId, r.key);
+    }
+    const path = values.get('--request');
+    if (typeof path !== 'string' || (await stat(path)).size > 65536)
+        throw Error('A request JSON file of at most 64 KiB is required');
+    const request = parseMappingRequest(JSON.parse(await readFile(path, 'utf8')));
+    if (operation === 'plan')
+        return service.plan(request);
+    const controller = new AbortController(), cancel = () => controller.abort();
+    process.once('SIGINT', cancel);
+    process.once('SIGTERM', cancel);
+    try {
+        return await service.propose(request, { allowModel: values.has('--allow-model'), signal: controller.signal,
+            onProgress: values.has('--quiet') ? undefined : event => process.stderr.write(`${JSON.stringify(event)}\n`) });
+    }
+    finally {
+        process.removeListener('SIGINT', cancel);
+        process.removeListener('SIGTERM', cancel);
+    }
+}