@idapt/cli 1.8.0

package/dist/index.d.cts

@@ -0,0 +1,380 @@
+import { z } from 'zod';
+
+/**
+ * v1 contract framework — the SINGLE SOURCE of truth for the public API surface.
+ *
+ * Each endpoint is described once as a {@link V1CommandSpec}: its zod request +
+ * response schemas (snake_case, matching the wire), its HTTP binding, the
+ * `idapt <resource> <verb>` grammar it maps to, and the surface flags that
+ * decide whether it appears in the public OpenAPI spec and/or as an agent tool.
+ *
+ * Consumers (all derive from these specs — nothing is hand-maintained twice):
+ *  - v1 route handlers      → import the request/response schemas for validation
+ *  - `@idapt/sdk`           → derives wire TYPES via `z.infer` (type-only import)
+ *  - `shared/api/v1/openapi` → GENERATED from the `public` specs
+ *  - `@idapt/cli`   → builds its command catalog (grammar + HTTP binding
+ *                             + docs) from the `agentExposed` specs
+ *
+ * Wire convention: every request/response schema is **snake_case**, because the
+ * v1 response boundary runs `deepSnakeCase()` and request bodies/queries arrive
+ * snake_case. Backend transforms emit camelCase and are snake-cased at the
+ * envelope; the response schema here describes the POST-snake_case shape.
+ */
+
+type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
+/** Where the non-path request fields are carried. */
+type ArgLocation = "path" | "query" | "body" | "multipart";
+/**
+ * Shape of the response `data` payload.
+ * - `single`   → `{ data: T }`
+ * - `list`     → `{ data: T[], pagination }`
+ * - `created`  → `{ data: T }` with 201
+ * - `deleted`  → `{ deleted: true, id }`
+ * - `binary`   → raw bytes / stream (no JSON envelope; `response` is null)
+ */
+type ResponseKind = "single" | "list" | "created" | "deleted" | "binary";
+/** Wire auth mode — drives the OpenAPI `security` requirement + whether 401 is documented. */
+type V1AuthMode = "standard" | "optional" | "public" | "bearer-only";
+/** HTTP error statuses the v1 surface documents. */
+type V1ErrorStatus = 401 | 402 | 403 | 404 | 409 | 422 | 429 | 500 | 503;
+/**
+ * A bespoke error response. Use instead of a bare {@link V1ErrorStatus} when an
+ * op documents an error with op-specific prose / example / headers that the
+ * shared `components.responses` entry would not convey (e.g. the settings
+ * slug-cooldown 429 carrying a `Retry-After` header), OR to point a non-default
+ * status at a named shared response (`ref`, e.g. the `ModelNotAvailableForTier`
+ * 403 returned by image/speech generation).
+ */
+interface V1ErrorOverride {
+    readonly status: number;
+    /** Name of a shared `components.responses` entry to $ref (XOR `description`). */
+    readonly ref?: string;
+    /** Inline response description (XOR `ref`). */
+    readonly description?: string;
+    readonly example?: unknown;
+    readonly headers?: Readonly<Record<string, {
+        readonly description?: string;
+        readonly schema: unknown;
+    }>>;
+}
+type V1OpError = V1ErrorStatus | V1ErrorOverride;
+/**
+ * Optional documentation + binding metadata carried by every command. These
+ * feed the GENERATED OpenAPI spec (`scripts/generate-openapi.ts`); none affect
+ * runtime behaviour. Keeping them on the spec keeps the contract the single
+ * source for the public API surface (no second hand-maintained doc).
+ */
+interface V1CommandDocFields {
+    /** Tier-2a contract help; falls back to schema-derived rendering when absent. */
+    readonly help?: string;
+    /** Human-CLI table columns; `field` is a dotted path into the `data` row. */
+    readonly columns?: readonly {
+        readonly header: string;
+        readonly field: string;
+    }[];
+    /** Per-op behavioural prose → the OpenAPI operation `description` (Markdown). */
+    readonly description?: string;
+    /** OpenAPI tag names; defaults to the resource→tag map when omitted. */
+    readonly tags?: readonly string[];
+    /** Stable OpenAPI `operationId`; defaults to camelCase(verb + Resource). */
+    readonly operationId?: string;
+    /** Wire auth mode (default `"standard"`). */
+    readonly auth?: V1AuthMode;
+    /**
+     * Documented error responses BEYOND the derived baseline (the generator adds
+     * 401 when authed, 404 when path-scoped, 422 when the op has a validated
+     * body/query). A number refs the shared `components.responses` entry; an
+     * object inlines a bespoke response.
+     */
+    readonly errors?: readonly V1OpError[];
+    /** Inline example for the OpenAPI `requestBody`. */
+    readonly requestExample?: unknown;
+    /** Inline example for the success-response body. */
+    readonly responseExample?: unknown;
+    /** For `binary` responses — the media types served (+ optional example/description). */
+    readonly binary?: {
+        readonly contentTypes: readonly string[];
+        readonly description?: string;
+        readonly example?: string;
+    };
+    /** A `created` op that is idempotent also documents a `200` (already-existed). */
+    readonly idempotent?: boolean;
+    /** Marks the operation `deprecated` in the spec. */
+    readonly deprecated?: boolean;
+}
+interface V1CommandSpec extends V1CommandDocFields {
+    /** Resource group, e.g. "drive". */
+    readonly resource: string;
+    /** Verb in the `idapt` grammar, e.g. "read", "list". */
+    readonly verb: string;
+    /** `${resource} ${verb}` — the canonical command string. */
+    readonly command: string;
+    readonly method: HttpMethod;
+    /** Path relative to `/api/v1`, with `:param` placeholders, e.g. `/drive/files/:id`. */
+    readonly path: string;
+    /** Request fields that fill `:param` placeholders (resourceIds). */
+    readonly pathParams: readonly string[];
+    /** Where the remaining request fields are carried. */
+    readonly argLocation: ArgLocation;
+    /** Request schema (snake_case). For multipart, describes the form fields. */
+    readonly request: z.ZodTypeAny;
+    /** Response `data` schema (snake_case), or null for `binary`. */
+    readonly response: z.ZodTypeAny | null;
+    readonly responseKind: ResponseKind;
+    /** Authorization gate — mirrors `defineRouteAuth`: canonical action id. */
+    readonly permission: readonly [string, string];
+    /** Appears in the curated public OpenAPI spec. */
+    readonly public: boolean;
+    /** Exposed as an agent tool (dispatcher / MCP / `idapt`). */
+    readonly agentExposed: boolean;
+    /** Long-running → goes through the async-operation layer. */
+    readonly async: boolean;
+    /** Tier-1 one-line decision hint (≤200 chars). */
+    readonly summary: string;
+}
+/**
+ * Resource-level playbook (tier-2b instructions) — the cross-cutting "when /
+ * why / anti-patterns" prose that no schema can hold. Hand-authored per
+ * resource and surfaced verbatim by `idapt instructions <resource>`.
+ */
+interface V1ResourcePlaybook {
+    readonly resource: string;
+    readonly instructions: string;
+}
+
+/**
+ * v1 contract registry — the aggregated single source consumed by routes, the
+ * SDK (types), the OpenAPI generator, and `@idapt/cli`.
+ *
+ * As resources are migrated, add their `*Commands` / `*Playbook` exports here.
+ */
+
+/** The playbook for one resource, if authored. */
+declare function getResourcePlaybook(resource: string): V1ResourcePlaybook | undefined;
+
+/**
+ * The cli command catalog — derived entirely from the shared v1
+ * contracts. Nothing here is hand-maintained; adding an `agentExposed` command
+ * to `shared/api/v1/contracts` makes it appear in the CLI, the dispatcher, and
+ * MCP automatically.
+ */
+
+/** Every command exposed as an agent tool. */
+declare function listCommands(): readonly V1CommandSpec[];
+/** Distinct resource names, sorted. */
+declare function listResources(): string[];
+/** Commands for one resource. */
+declare function commandsForResource(resource: string): readonly V1CommandSpec[];
+/** Exact command lookup, e.g. "drive read". */
+declare function findCommand(command: string): V1CommandSpec | undefined;
+/**
+ * Resolve the longest catalog command that prefixes the given path tokens.
+ * Returns the matched spec and the leftover tokens (positional path-param
+ * values). E.g. ["drive","read","file_abc"] → { spec: drive read, rest:
+ * ["file_abc"] }.
+ */
+declare function resolveCommand(pathTokens: readonly string[]): {
+    spec: V1CommandSpec;
+    rest: string[];
+} | undefined;
+
+/**
+ * Output formatting — one mode-parameterized renderer shared by every consumer.
+ * The CLI uses `auto`/`table`/`json`; the in-chat dispatcher uses `llm`
+ * (truncated for the model's context); MCP uses `json`. Per-command table
+ * columns come from the spec, so this stays generic.
+ */
+
+type RenderMode = "json" | "jsonl" | "quiet" | "table" | "llm";
+declare function render(data: unknown, spec: V1CommandSpec, mode: RenderMode): string;
+/** Resolve the effective mode for a TTY/pipe context (CLI `auto` default). */
+declare function autoMode(isTty: boolean, requested?: RenderMode): RenderMode;
+
+/**
+ * Transport seam. `execute()` builds a neutral {@link AgentToolsRequest} from a
+ * command spec and hands it to a transport. The default {@link createFetchTransport}
+ * is a thin bearer-auth fetch wrapper; in the in-chat worker / MCP it is given a
+ * transport that injects the minted agent-principal token, and tests inject a
+ * mock.
+ *
+ * This is the single seam where the `@idapt/sdk` low-level `request()` will be
+ * plugged in once the SDK exports it — so cli reuses the SDK's HTTP
+ * behaviour instead of duplicating it long-term.
+ */
+interface AgentToolsRequest {
+    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    /** Absolute-from-origin path, e.g. "/api/v1/drive/files/file_abc". */
+    readonly path: string;
+    readonly query?: Record<string, string | number | boolean | undefined>;
+    /** JSON body (mutually exclusive with `multipart`). */
+    readonly body?: Record<string, unknown>;
+    /** Multipart form fields (for uploads). */
+    readonly multipart?: Record<string, string | Blob>;
+    /** Expect raw bytes/stream rather than a JSON envelope. */
+    readonly expectBinary?: boolean;
+    readonly signal?: AbortSignal;
+}
+interface AgentToolsResponse {
+    readonly status: number;
+    /** Parsed JSON body, when the response was JSON. */
+    readonly json?: unknown;
+    /** Raw text body, when not JSON. */
+    readonly text?: string;
+    /** Binary body, when `expectBinary` was requested. */
+    readonly blob?: Blob;
+}
+interface AgentToolsTransport {
+    request(req: AgentToolsRequest): Promise<AgentToolsResponse>;
+}
+interface FetchTransportOptions {
+    /** Origin, e.g. "https://idapt.app" or "http://localhost:3000". */
+    readonly baseUrl: string;
+    /** Bearer token (user API key, or a minted agent-principal token). */
+    readonly token: string;
+    /** Custom fetch (tests / non-browser runtimes). */
+    readonly fetch?: typeof fetch;
+    /**
+     * User-Agent to advertise (e.g. `idapt-cli/1.2.0`). Lets the server classify
+     * the caller (route-policy + analytics) and is the JS-client twin of the Go
+     * daemon's `idapt-computer/<v>` UA. Optional so the in-chat dispatcher / MCP
+     * transports stay unaffected.
+     */
+    readonly userAgent?: string;
+}
+/** Default bearer-auth fetch transport. */
+declare function createFetchTransport(opts: FetchTransportOptions): AgentToolsTransport;
+
+/**
+ * Execute an `idapt <resource> <verb> …` command against the v1 API.
+ *
+ * Pure translation: resolve the command spec, bind path params, validate the
+ * remaining args against the contract's request schema, build the REST request
+ * per the spec's `argLocation`, call the transport, unwrap the envelope by
+ * `responseKind`, and render per the chosen mode. No per-verb code — the spec
+ * (from `shared/api/v1/contracts`) drives everything.
+ */
+
+interface ExecuteOptions {
+    readonly transport: AgentToolsTransport;
+    /** Render mode for `rendered`. Default "json". The in-chat dispatcher uses "llm". */
+    readonly mode?: RenderMode;
+    readonly signal?: AbortSignal;
+    /**
+     * For `async` verbs: when true, return the operation handle immediately
+     * instead of polling to completion. Defaults to the command's `--background`
+     * flag.
+     */
+    readonly background?: boolean;
+    /** Poll cadence for async operations (default 1500ms). */
+    readonly pollIntervalMs?: number;
+    /** Max poll attempts before giving up and returning the handle (default 120). */
+    readonly maxPollAttempts?: number;
+    /** Injectable delay (tests pass a no-op); defaults to real setTimeout. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+interface ExecuteResult {
+    readonly ok: boolean;
+    readonly command: string;
+    readonly status: number;
+    /** Unwrapped payload (single row, array, deleted marker, text, or blob). */
+    readonly data: unknown;
+    /** Pagination, for list responses. */
+    readonly pagination?: {
+        has_more: boolean;
+        next_cursor: string | null;
+    };
+    /** Output rendered per `mode`. */
+    readonly rendered: string;
+    /** Error message when `ok` is false. */
+    readonly error?: string;
+    /** Set when an async verb returned (or is still running on) an operation. */
+    readonly operationId?: string;
+    /** True when a `--background` async verb returned a still-running handle. */
+    readonly pending?: boolean;
+}
+declare function execute(cmd: string, opts: ExecuteOptions): Promise<ExecuteResult>;
+/**
+ * Execute a command addressed by its `"<resource> <verb>"` name with an already
+ * parsed args object — the seam the in-chat dispatcher uses (it resolves the
+ * agent's command + path args itself, then hands the v1 command + args here),
+ * and a first-class entry for SDK/programmatic callers who don't want to build
+ * a CLI string. Same translation as {@link execute}, minus the string parse.
+ */
+declare function executeCommand(commandName: string, args: Record<string, unknown>, opts: ExecuteOptions): Promise<ExecuteResult>;
+
+/**
+ * Contract help (tier-2a) and playbook (tier-2b) rendering.
+ *
+ * `help` is derived from the command spec (args/types/required, method, path).
+ * `instructions` is the hand-authored resource playbook from the contracts —
+ * the cross-cutting "when / why" prose no schema can hold.
+ */
+
+declare function renderHelp(spec: V1CommandSpec): string;
+declare function renderInstructions(resource: string): string;
+
+/**
+ * Parse a model/CLI-facing `idapt <resource> <verb> …` command string into a
+ * neutral invocation. Reuses the shell-injection-safe tokenizer from
+ * `@idapt/api-contracts/idapt-command` (shared with the in-app dispatcher and the Go
+ * CLI), then normalizes flag keys to the **snake_case** the v1 contracts use.
+ *
+ * Positionals after the verb are preserved (command resolution binds them to a
+ * spec's path params), so both `idapt drive read file_abc` and
+ * `idapt drive read --id file_abc` work.
+ */
+interface ParsedInvocation {
+    /** Path tokens after `idapt`, e.g. ["drive","read","file_abc"]. */
+    readonly pathTokens: readonly string[];
+    /** Flag + merged `--json` args, keys normalized to snake_case. */
+    readonly args: Record<string, unknown>;
+    readonly background: boolean;
+    readonly timeoutSeconds?: number;
+    readonly help: boolean;
+    readonly instructions: boolean;
+}
+type ParseResult = {
+    ok: true;
+    invocation: ParsedInvocation;
+} | {
+    ok: false;
+    message: string;
+};
+/** kebab-case and camelCase → snake_case (the v1 wire convention). */
+declare function toSnakeKey(key: string): string;
+declare function parseInvocation(cmd: string): ParseResult;
+
+/**
+ * Agent-grammar → v1-command reconciliation — SHARED by every consumer of the
+ * `idapt <resource> <verb>` grammar (the in-chat dispatcher and the MCP server).
+ *
+ * Callers emit the agent/skill grammar (e.g. `"drive read"`, `"computer
+ * tmux-run"`). Most paths already match a v1 catalog command 1:1; the rest are
+ * reconciled here (verb renames, op-collapsed verbs). `reconcileToV1` maps the
+ * verb; `mapArgsToV1` shapes the already-resolved args onto the v1 contract
+ * (snake_case, op injection, path-param filling). Both are pure functions with no
+ * runtime dependency on any product package, which is exactly why they live in
+ * the shared client: the dispatcher (worker) and MCP (gateway) reconcile
+ * identically without importing each other.
+ *
+ * (Carve-out detection — which verbs run locally vs over REST — is consumer-
+ * specific and stays with each consumer.)
+ */
+/**
+ * Agent command `path` → v1 catalog command, where they differ. Identity is
+ * assumed when a path is absent here (e.g. `"drive read"` → `"drive read"`).
+ * Op-collapsed verbs (tmux-*, file-*) point at the single v1 verb that takes the
+ * operation as an argument — `mapArgsToV1` injects the op.
+ */
+declare const VERB_OVERRIDES: Record<string, string>;
+/** Resolve an agent command path to its v1 catalog command (or itself). */
+declare function reconcileToV1(path: string): string;
+/**
+ * Shape already-path-resolved args into the v1 command's args: snake_case the
+ * keys, inject the collapsed-verb `op`, and fill each of the v1 spec's path
+ * params from an alias key. `executeCommand`'s `bindPath` then consumes the
+ * path-param values + validates the rest against the contract.
+ */
+declare function mapArgsToV1(path: string, pathParams: readonly string[], args: Record<string, unknown>): Record<string, unknown>;
+
+export { type AgentToolsRequest, type AgentToolsResponse, type AgentToolsTransport, type ExecuteOptions, type ExecuteResult, type FetchTransportOptions, type ParsedInvocation, type RenderMode, type V1CommandSpec, VERB_OVERRIDES, autoMode, commandsForResource, createFetchTransport, execute, executeCommand, findCommand, getResourcePlaybook, listCommands, listResources, mapArgsToV1, parseInvocation, reconcileToV1, render, renderHelp, renderInstructions, resolveCommand, toSnakeKey };