@idapt/cli 1.9.0 → 1.10.0

package/dist/index.d.cts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HttpContext } from '@idapt/sdk';
 
 /**
  * v1 contract framework — the SINGLE SOURCE of truth for the public API surface.
@@ -91,6 +92,17 @@ interface V1CommandDocFields {
     readonly requestExample?: unknown;
     /** Inline example for the success-response body. */
     readonly responseExample?: unknown;
+    /**
+     * Agent-invocation examples — concrete `{action, args}` calls surfaced in the
+     * command catalog + `help`. Distinct from `requestExample`/`responseExample`
+     * (which document the HTTP bodies for OpenAPI). Helps the model produce
+     * well-formed calls (the Anthropic `input_examples` affordance).
+     */
+    readonly examples?: readonly {
+        readonly title?: string;
+        readonly action: string;
+        readonly args?: Record<string, unknown>;
+    }[];
     /** For `binary` responses — the media types served (+ optional example/description). */
     readonly binary?: {
         readonly contentTypes: readonly string[];
@@ -193,16 +205,26 @@ 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
+ * sends HTTP **through `@idapt/sdk`'s low-level `requestRaw()`** (bearer auth, URL
+ * + body building, fetch-error mapping); 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.
+ * This is the single seam where the cli, MCP, and in-app dispatcher (which all
+ * consume this transport) share ONE HTTP layer with the SDK instead of
+ * duplicating fetch — the JS twin of the Go daemon routing through one client.
+ *
+ * The {@link AgentToolsRequest}/{@link AgentToolsResponse} interface is kept
+ * byte-stable so `execute.ts` / MCP / the dispatcher are unaffected: the
+ * transport still NEVER throws on an HTTP status — every status (incl. 4xx/5xx)
+ * comes back as `{ status, json | text | blob }`. The SDK's `requestRaw()` throws
+ * a typed `IdaptError` on non-2xx, so we catch it and rebuild that flat shape
+ * from the error's preserved `.status` + `.body`. Only a transport-level failure
+ * (network error / abort) propagates as a thrown error, exactly as before.
  */
+
 interface AgentToolsRequest {
-    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
     /** Absolute-from-origin path, e.g. "/api/v1/drive/files/file_abc". */
     readonly path: string;
     readonly query?: Record<string, string | number | boolean | undefined>;
@@ -225,6 +247,15 @@ interface AgentToolsResponse {
 }
 interface AgentToolsTransport {
     request(req: AgentToolsRequest): Promise<AgentToolsResponse>;
+    /**
+     * The underlying SDK {@link HttpContext} this transport sends through, when it
+     * is the default fetch transport. The spec executor delegates request
+     * assembly, the HTTP call, envelope unwrap, and operation polling to the SDK's
+     * `executeCommand` over THIS context — so the CLI and SDK share ONE executor
+     * with zero duplicated logic. Absent only on bespoke (non-fetch) transports,
+     * in which case the executor reports the command is not runnable.
+     */
+    readonly ctx?: HttpContext;
 }
 interface FetchTransportOptions {
     /** Origin, e.g. "https://idapt.app" or "http://localhost:3000". */
@@ -241,17 +272,21 @@ interface FetchTransportOptions {
      */
     readonly userAgent?: string;
 }
-/** Default bearer-auth fetch transport. */
+/** Default bearer-auth transport — sends through the SDK's `requestRaw()`. */
 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.
+ * The CLI is the **spec/positional/validation/render adapter** around the SINGLE
+ * spec executor that lives in `@idapt/sdk` (`executeCommand`): it resolves the
+ * command spec, binds path params from positionals + named args, validates the
+ * remaining args against the contract's request schema, then DELEGATES request
+ * assembly, the HTTP call, envelope unwrap, and async-operation polling to the
+ * SDK over the transport's shared {@link HttpContext}. The CLI layers on what is
+ * its own — positional binding, pre-flight validation with repair hints, binary
+ * text-detection, render mode, and the soft `ExecuteResult` (it never throws on
+ * an HTTP status). One executor, zero duplicated transport logic.
  */
 
 interface ExecuteOptions {

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { HttpContext } from '@idapt/sdk';
 
 /**
  * v1 contract framework — the SINGLE SOURCE of truth for the public API surface.
@@ -91,6 +92,17 @@ interface V1CommandDocFields {
     readonly requestExample?: unknown;
     /** Inline example for the success-response body. */
     readonly responseExample?: unknown;
+    /**
+     * Agent-invocation examples — concrete `{action, args}` calls surfaced in the
+     * command catalog + `help`. Distinct from `requestExample`/`responseExample`
+     * (which document the HTTP bodies for OpenAPI). Helps the model produce
+     * well-formed calls (the Anthropic `input_examples` affordance).
+     */
+    readonly examples?: readonly {
+        readonly title?: string;
+        readonly action: string;
+        readonly args?: Record<string, unknown>;
+    }[];
     /** For `binary` responses — the media types served (+ optional example/description). */
     readonly binary?: {
         readonly contentTypes: readonly string[];
@@ -193,16 +205,26 @@ 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
+ * sends HTTP **through `@idapt/sdk`'s low-level `requestRaw()`** (bearer auth, URL
+ * + body building, fetch-error mapping); 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.
+ * This is the single seam where the cli, MCP, and in-app dispatcher (which all
+ * consume this transport) share ONE HTTP layer with the SDK instead of
+ * duplicating fetch — the JS twin of the Go daemon routing through one client.
+ *
+ * The {@link AgentToolsRequest}/{@link AgentToolsResponse} interface is kept
+ * byte-stable so `execute.ts` / MCP / the dispatcher are unaffected: the
+ * transport still NEVER throws on an HTTP status — every status (incl. 4xx/5xx)
+ * comes back as `{ status, json | text | blob }`. The SDK's `requestRaw()` throws
+ * a typed `IdaptError` on non-2xx, so we catch it and rebuild that flat shape
+ * from the error's preserved `.status` + `.body`. Only a transport-level failure
+ * (network error / abort) propagates as a thrown error, exactly as before.
  */
+
 interface AgentToolsRequest {
-    readonly method: "GET" | "POST" | "PATCH" | "DELETE";
+    readonly method: "GET" | "POST" | "PATCH" | "PUT" | "DELETE";
     /** Absolute-from-origin path, e.g. "/api/v1/drive/files/file_abc". */
     readonly path: string;
     readonly query?: Record<string, string | number | boolean | undefined>;
@@ -225,6 +247,15 @@ interface AgentToolsResponse {
 }
 interface AgentToolsTransport {
     request(req: AgentToolsRequest): Promise<AgentToolsResponse>;
+    /**
+     * The underlying SDK {@link HttpContext} this transport sends through, when it
+     * is the default fetch transport. The spec executor delegates request
+     * assembly, the HTTP call, envelope unwrap, and operation polling to the SDK's
+     * `executeCommand` over THIS context — so the CLI and SDK share ONE executor
+     * with zero duplicated logic. Absent only on bespoke (non-fetch) transports,
+     * in which case the executor reports the command is not runnable.
+     */
+    readonly ctx?: HttpContext;
 }
 interface FetchTransportOptions {
     /** Origin, e.g. "https://idapt.app" or "http://localhost:3000". */
@@ -241,17 +272,21 @@ interface FetchTransportOptions {
      */
     readonly userAgent?: string;
 }
-/** Default bearer-auth fetch transport. */
+/** Default bearer-auth transport — sends through the SDK's `requestRaw()`. */
 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.
+ * The CLI is the **spec/positional/validation/render adapter** around the SINGLE
+ * spec executor that lives in `@idapt/sdk` (`executeCommand`): it resolves the
+ * command spec, binds path params from positionals + named args, validates the
+ * remaining args against the contract's request schema, then DELEGATES request
+ * assembly, the HTTP call, envelope unwrap, and async-operation polling to the
+ * SDK over the transport's shared {@link HttpContext}. The CLI layers on what is
+ * its own — positional binding, pre-flight validation with repair hints, binary
+ * text-detection, render mode, and the soft `ExecuteResult` (it never throws on
+ * an HTTP status). One executor, zero duplicated transport logic.
  */
 
 interface ExecuteOptions {

package/dist/index.js

@@ -1,3 +1,3 @@
-export { VERB_OVERRIDES, autoMode, commandsForResource, createFetchTransport, execute, executeCommand, findCommand, getResourcePlaybook, listCommands, listResources, mapArgsToV1, parseInvocation, reconcileToV1, render, renderHelp, renderInstructions, resolveCommand, toSnakeKey } from './chunk-TYSHO65D.js';
+export { VERB_OVERRIDES, autoMode, commandsForResource, createFetchTransport, execute, executeCommand, findCommand, getResourcePlaybook, listCommands, listResources, mapArgsToV1, parseInvocation, reconcileToV1, render, renderHelp, renderInstructions, resolveCommand, toSnakeKey } from './chunk-CX7FTE47.js';
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@idapt/cli",
-  "version": "1.9.0",
+  "version": "1.10.0",
   "description": "The idapt CLI — the `idapt <resource> <verb>` grammar, command→REST translation, help/instructions, output formatting, SOTA auth (OAuth 2.1 + PKCE / device-code / API-key) and self-update, over the public v1 API. One implementation shared by the in-chat dispatcher, MCP, and the `idapt` CLI binary.",
   "license": "Apache-2.0",
   "homepage": "https://idapt.app/cli",
@@ -31,6 +31,7 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@idapt/sdk": "*",
     "zod": "^4.1.12"
   },
   "devDependencies": {