@settlemint/dalp-cli 3.1.32-main.42202049300 → 3.1.32-main.42217736252

package/src/lib/register-operations.ts

@@ -0,0 +1,631 @@
+import type { DalpClient } from "@settlemint/dalp-sdk";
+import { Cli, z } from "incur";
+import { buildErrorCta, buildSuccessCtaFromResult, type CliCtaBlock } from "./cli-cta.ts";
+import { createCliStatus } from "./cli-status.ts";
+import { renderSdkErrorForCli } from "./errors.ts";
+import { INDEX_COMMAND } from "@settlemint/dalp-sdk/routes";
+import { listCliOperations, operationHintKey, type OperationDescriptor } from "./operation-inventory.ts";
+import { tagDescription, type SurfaceOperation } from "./openapi-surface.ts";
+import { runCommand } from "./run-command.ts";
+import {
+  buildArgsFromSdkPath,
+  buildOptionsFromSdk,
+  collectBodyBag,
+  collectPathBag,
+  collectQueryBag,
+  type LooseBag,
+  parseLooseBag,
+  parseWithSdkSchema,
+} from "./sdk-cli-schema.ts";
+import { cliVars } from "./vars.ts";
+
+function readOkHelper<T extends object>(
+  context: T
+): ((data: unknown, meta?: { cta?: CliCtaBlock }) => unknown) | undefined {
+  const ok = Reflect.get(context, "ok");
+  return typeof ok === "function" ? (ok as (data: unknown, meta?: { cta?: CliCtaBlock }) => unknown) : undefined;
+}
+
+function withSuccessCta<T extends object>(context: T, data: unknown): unknown {
+  const cta = buildSuccessCtaFromResult(data);
+  const ok = readOkHelper(context);
+  if (ok === undefined || cta === undefined) {
+    return data;
+  }
+  return ok(data, { cta });
+}
+
+export type ApiBag = LooseBag;
+
+interface McpAnnotations {
+  readonly readOnlyHint: boolean;
+  readonly destructiveHint?: boolean;
+  readonly idempotentHint?: boolean;
+}
+
+export const REGISTERED_OPERATIONS: ReadonlySet<string> = new Set(
+  listCliOperations().map((descriptor) => descriptor.name)
+);
+
+export interface CommandTreeNode {
+  readonly children: Map<string, CommandTreeNode>;
+  operations: Array<OperationDescriptor>;
+}
+
+const isSseResult = (value: unknown): value is { readonly stream: AsyncIterable<unknown> } => {
+  if (typeof value !== "object" || value === null || !("stream" in value)) {
+    return false;
+  }
+  const stream = Reflect.get(value, "stream");
+  return typeof stream === "object" && stream !== null && Symbol.asyncIterator in stream;
+};
+
+function pickPrimaryOp(ops: ReadonlyArray<OperationDescriptor>): OperationDescriptor {
+  return [...ops].sort((left, right) => right.surface.pathParams.length - left.surface.pathParams.length)[0]!;
+}
+
+function combinedHelp(ops: ReadonlyArray<OperationDescriptor>): string {
+  const helps = ops.map((op) => op.help).filter((help) => help.trim().length > 0);
+  if (helps.length === 0) {
+    return ops.map((op) => `${op.method} ${op.url}`).join("; ");
+  }
+  if (helps.length === 1) {
+    return helps[0]!;
+  }
+  const byPathParams = [...ops].sort((left, right) => left.surface.pathParams.length - right.surface.pathParams.length);
+  return byPathParams.map((op) => op.help).join("\n\n");
+}
+
+function buildHint(ops: ReadonlyArray<OperationDescriptor>): string {
+  return ops.map((op) => operationHintKey(op.method, op.url)).join(" · ");
+}
+
+function buildExamples(ops: ReadonlyArray<OperationDescriptor>, surface: SurfaceOperation) {
+  const examples: Array<{
+    description: string;
+    args?: Record<string, string>;
+    options?: Record<string, string | boolean | number>;
+  }> = [];
+
+  for (const example of surface.examples) {
+    examples.push({
+      description: example.description,
+      ...(example.path !== undefined ? { args: example.path } : {}),
+      ...(example.query !== undefined ? { options: example.query } : {}),
+    });
+  }
+
+  if (examples.length === 0) {
+    examples.push({
+      description: ops[0]?.help.split("\n")[0] ?? ops[0]?.name ?? "call",
+    });
+  }
+  return examples.slice(0, 5);
+}
+
+function selectOperation(ops: ReadonlyArray<OperationDescriptor>, path: ApiBag | undefined): OperationDescriptor {
+  if (ops.length === 1) {
+    return ops[0]!;
+  }
+  const ranked = ops
+    .map((op) => ({
+      op,
+      required: op.surface.pathParams.filter((param) => param.required).map((param) => param.name),
+      total: op.surface.pathParams.length,
+    }))
+    .sort((left, right) => right.total - left.total);
+
+  for (const candidate of ranked) {
+    if (candidate.required.length === 0) {
+      continue;
+    }
+    if (path !== undefined && candidate.required.every((name) => path[name] !== undefined && path[name] !== "")) {
+      return candidate.op;
+    }
+  }
+  return [...ranked].sort((left, right) => left.total - right.total)[0]!.op;
+}
+
+function headerOptionName(name: string): string {
+  return name
+    .replaceAll(/([a-z0-9])([A-Z])/gu, "$1-$2")
+    .replaceAll("_", "-")
+    .replaceAll(/-+/gu, "-")
+    .toLowerCase();
+}
+
+function collectHeaders(surface: SurfaceOperation, options: ApiBag): Headers | undefined {
+  const headers = new Headers();
+  let any = false;
+  for (const param of surface.headerParams) {
+    const value = options[headerOptionName(param.name)] ?? options[param.name];
+    if (typeof value === "string" && value !== "") {
+      headers.set(param.name, value);
+      any = true;
+    }
+  }
+  return any ? headers : undefined;
+}
+
+async function invokeOperation(
+  descriptor: OperationDescriptor,
+  client: DalpClient,
+  input: {
+    readonly path?: ApiBag;
+    readonly query?: unknown;
+    readonly body?: unknown;
+    readonly headers?: Headers;
+    readonly settlementTimeoutMs?: number;
+  },
+  signal?: AbortSignal
+): Promise<unknown> {
+  const flat = {
+    ...(input.body !== null && typeof input.body === "object" ? input.body : {}),
+    ...(input.query !== null && typeof input.query === "object" ? input.query : {}),
+    ...input.path,
+  };
+  return client.execute(descriptor.name, flat, {
+    ...(signal === undefined ? {} : { signal }),
+    ...(input.settlementTimeoutMs === undefined ? {} : { settlementTimeoutMs: input.settlementTimeoutMs }),
+    ...(input.headers === undefined ? {} : { headers: Object.fromEntries(input.headers) }),
+  });
+}
+
+function isMutationMethod(method: string): boolean {
+  return method !== "GET";
+}
+
+function listsPreferHeader(surface: SurfaceOperation): boolean {
+  return surface.headerParams.some((param) => param.name.toLowerCase() === "prefer");
+}
+
+function isHeldForApproval(result: unknown): boolean {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    "data" in result &&
+    typeof result.data === "object" &&
+    result.data !== null &&
+    "approvalId" in result.data &&
+    "state" in result.data &&
+    result.data.state === "proposed"
+  );
+}
+
+function describeMutationOutcome(result: unknown): string {
+  if (isHeldForApproval(result)) {
+    return "Request held for a second approver";
+  }
+  if (typeof result !== "object" || result === null || !("statusUrl" in result)) {
+    return "Request settled";
+  }
+  if ("transactionId" in result) {
+    return "Request accepted; the transaction is still settling";
+  }
+  if ("requestId" in result && "state" in result) {
+    return "Request accepted; the custody lifecycle is still settling";
+  }
+  return "Request settled";
+}
+
+const ANNOTATIONS_BY_METHOD: Readonly<Record<string, McpAnnotations>> = {
+  GET: { readOnlyHint: true, destructiveHint: false, idempotentHint: true },
+  DELETE: { readOnlyHint: false, destructiveHint: true },
+};
+const WRITE_ANNOTATIONS: McpAnnotations = { readOnlyHint: false };
+
+function mcpMetadataFor(ops: ReadonlyArray<OperationDescriptor>) {
+  const primary = pickPrimaryOp(ops);
+  return { annotations: ANNOTATIONS_BY_METHOD[primary.method.toUpperCase()] ?? WRITE_ANNOTATIONS };
+}
+
+function makeLeafHandler(ops: ReadonlyArray<OperationDescriptor>) {
+  const primary = pickPrimaryOp(ops);
+  const { surface } = primary;
+  const hasListSibling = ops.some((op) => op.pathSchema === undefined);
+  const makePathOptional = hasListSibling && ops.length > 1;
+  const mutation = ops.some((op) => isMutationMethod(op.method));
+
+  const pathSchema = ops.map((op) => op.pathSchema).find((schema) => schema !== undefined);
+  const querySchema = ops.map((op) => op.querySchema).find((schema) => schema !== undefined);
+  const bodySchema = ops.map((op) => op.bodySchema).find((schema) => schema !== undefined);
+
+  const argsSchema = buildArgsFromSdkPath(pathSchema ?? primary.pathSchema, surface, makePathOptional);
+  const optionsSchema = buildOptionsFromSdk(querySchema, bodySchema, surface, {
+    ...(mutation
+      ? {
+          wait: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe(
+              "Ask the platform to wait for settlement before it answers (default: true). Pass --no-wait to take the handle back immediately and follow its statusUrl yourself."
+            ),
+        }
+      : {}),
+    ...(mutation && !ops.some((op) => listsPreferHeader(op.surface))
+      ? {
+          prefer: z
+            .string()
+            .optional()
+            .describe(
+              "Accepted and ignored: this operation does not read the Prefer header, so the CLI does not send it."
+            ),
+        }
+      : {}),
+  });
+  const help = combinedHelp(ops);
+
+  return {
+    description: help,
+    mcp: mcpMetadataFor(ops),
+    hint: buildHint(ops),
+    ...(argsSchema === undefined ? {} : { args: argsSchema }),
+    ...(optionsSchema === undefined ? {} : { options: optionsSchema }),
+    examples: buildExamples(ops, surface),
+    async *run(c: {
+      var: { client?: DalpClient };
+      args?: unknown;
+      options?: unknown;
+      request?: Request;
+      agent?: boolean;
+      error: (error: {
+        code: string;
+        message: string;
+        retryable?: boolean;
+        exitCode?: number;
+        cta?: CliCtaBlock;
+      }) => unknown;
+    }) {
+      const { client } = c.var;
+      if (client === undefined) {
+        return c.error({
+          code: "NOT_AUTHENTICATED",
+          message: "Not logged in. Run 'dalp login' to authenticate.",
+          retryable: true,
+          cta: buildErrorCta({
+            why: "No stored DALP credentials were found for this CLI command.",
+            fix: "Run 'dalp login' against the DALP instance you want to manage, then retry the command.",
+            code: "NOT_AUTHENTICATED",
+            category: "auth",
+          }),
+        });
+      }
+
+      const argsBag = parseLooseBag(c.args ?? {});
+      const optionsBag = parseLooseBag(c.options ?? {});
+      const agent = c.agent === true;
+      const status = createCliStatus({ agent });
+
+      const label = ops.map((op) => op.commandPath.join(" ")).join(" | ");
+
+      try {
+        const prepareEvent = status.update({
+          phase: "prepare",
+          message: `Preparing ${label}…`,
+        });
+        if (prepareEvent !== undefined) {
+          yield prepareEvent;
+        }
+
+        const path = collectPathBag(argsBag);
+        const descriptor = selectOperation(ops, path);
+
+        let validatedPath: ApiBag | undefined = path;
+        if (descriptor.pathSchema !== undefined) {
+          if (path === undefined || Object.keys(path).length === 0) {
+            const requiresPath = descriptor.surface.pathParams.some((param) => param.required);
+            if (requiresPath) {
+              const failedEvent = status.fail("Missing path parameters");
+              if (failedEvent !== undefined) {
+                yield failedEvent;
+              }
+              return c.error({
+                code: "kit.cli.MISSING_PATH",
+                message: `Operation ${descriptor.name} requires path parameters.`,
+                retryable: true,
+                cta: buildErrorCta({
+                  why: "This operation needs resource identifiers from the URL path.",
+                  fix: "Pass the required path arguments (see --help) and retry.",
+                  code: "kit.cli.MISSING_PATH",
+                  category: "client",
+                }),
+              });
+            }
+            validatedPath = undefined;
+          } else {
+            try {
+              validatedPath = parseWithSdkSchema<ApiBag>(descriptor.pathSchema, path, "path");
+            } catch (error) {
+              const failedEvent = status.fail("Invalid path parameters");
+              if (failedEvent !== undefined) {
+                yield failedEvent;
+              }
+              const message = error instanceof Error ? error.message : "Invalid path parameters";
+              return c.error({
+                code: "kit.cli.INVALID_PATH",
+                message,
+                retryable: true,
+                cta: buildErrorCta({
+                  why: "One or more path arguments failed SDK schema validation.",
+                  fix: "Correct the path arguments to match the API schema (see --help), then retry.",
+                  code: "kit.cli.INVALID_PATH",
+                  category: "client",
+                }),
+              });
+            }
+          }
+        }
+
+        let validatedQuery: unknown;
+        try {
+          const rawQuery = collectQueryBag(optionsBag, descriptor.querySchema);
+          validatedQuery =
+            rawQuery !== undefined && descriptor.querySchema !== undefined
+              ? parseWithSdkSchema(descriptor.querySchema, rawQuery, "query")
+              : rawQuery;
+        } catch (error) {
+          const failedEvent = status.fail("Invalid query parameters");
+          if (failedEvent !== undefined) {
+            yield failedEvent;
+          }
+          const message = error instanceof Error ? error.message : "Invalid query parameters";
+          return c.error({
+            code: "kit.cli.INVALID_QUERY",
+            message,
+            retryable: true,
+            cta: buildErrorCta({
+              why: "One or more query options failed SDK schema validation.",
+              fix: "Correct the query options to match the API schema (see --help), then retry.",
+              code: "kit.cli.INVALID_QUERY",
+              category: "client",
+            }),
+          });
+        }
+
+        let validatedBody: unknown;
+        try {
+          const rawBody = collectBodyBag(optionsBag, descriptor.bodySchema);
+          validatedBody =
+            rawBody !== undefined && descriptor.bodySchema !== undefined
+              ? parseWithSdkSchema(descriptor.bodySchema, rawBody, "body")
+              : rawBody;
+        } catch (error) {
+          const failedEvent = status.fail("Invalid request body");
+          if (failedEvent !== undefined) {
+            yield failedEvent;
+          }
+          const message = error instanceof Error ? error.message : "Invalid request body";
+          return c.error({
+            code: "kit.cli.INVALID_BODY",
+            message,
+            retryable: true,
+            cta: buildErrorCta({
+              why: "The request body failed SDK schema validation.",
+              fix: "Correct --body (or body field options) to match the API schema (see --help), then retry.",
+              code: "kit.cli.INVALID_BODY",
+              category: "client",
+            }),
+          });
+        }
+
+        const headers = collectHeaders(descriptor.surface, optionsBag);
+        const settlementTimeoutMs = mutation && optionsBag["wait"] === false ? 0 : undefined;
+        const submitEvent = status.update({
+          phase: "submit",
+          message: `Submitting ${descriptor.method} ${descriptor.url}…`,
+        });
+        if (submitEvent !== undefined) {
+          yield submitEvent;
+        }
+
+        const result = await runCommand(
+          c,
+          invokeOperation(
+            descriptor,
+            client,
+            {
+              path: validatedPath,
+              query: validatedQuery,
+              body: validatedBody,
+              headers,
+              ...(settlementTimeoutMs === undefined ? {} : { settlementTimeoutMs }),
+            },
+            c.request?.signal
+          ),
+          {
+            code: "API_OPERATION_FAILED",
+            fallbackMessage: "Operation failed.",
+            fallbackWhy: "The DALP API rejected the request or the network call failed.",
+            fallbackFix: "Verify authentication, organization context, and args/options, then retry.",
+          }
+        );
+
+        if (typeof result === "object" && result !== null && "code" in result && !("data" in result)) {
+          const failedEvent = status.fail("Request failed");
+          if (failedEvent !== undefined) {
+            const reason: unknown = Reflect.get(result, "message");
+            yield typeof reason === "string" && reason !== "" ? { ...failedEvent, message: reason } : failedEvent;
+          }
+          return result;
+        }
+
+        if (isSseResult(result)) {
+          const streamEvent = status.update({
+            phase: "stream",
+            message: "Streaming response…",
+          });
+          if (streamEvent !== undefined) {
+            yield streamEvent;
+          }
+          try {
+            for await (const chunk of result.stream) {
+              yield chunk;
+            }
+          } catch (streamError) {
+            if (streamError instanceof DOMException && streamError.name === "AbortError") {
+              throw streamError;
+            }
+            const rendered = renderSdkErrorForCli(streamError, {
+              code: "API_STREAM_FAILED",
+              fallbackMessage: "SSE stream failed",
+              fallbackWhy: "The Server-Sent Events stream ended with an error before a terminal event.",
+              fallbackFix: "Retry the stream command, or poll the matching status endpoint.",
+            });
+            const failed = status.fail(rendered.message);
+            if (failed !== undefined) {
+              yield failed;
+            }
+            return c.error({
+              ...rendered,
+              exitCode: 1,
+            });
+          }
+          const done = status.succeed("Stream finished");
+          if (done !== undefined) {
+            yield done;
+          }
+          return;
+        }
+
+        const submittedEvent = status.update({
+          phase: "submitted",
+          message: "Request accepted by API",
+        });
+        if (submittedEvent !== undefined) {
+          yield submittedEvent;
+        }
+
+        const done = status.succeed(mutation ? describeMutationOutcome(result) : "Done");
+        if (done !== undefined) {
+          yield done;
+        }
+        yield result;
+        return withSuccessCta(c, result);
+      } catch (error) {
+        const rendered = renderSdkErrorForCli(error, {
+          code: "API_OPERATION_FAILED",
+          fallbackMessage: "Command failed",
+          fallbackWhy: "The DALP API rejected the request or the network call failed.",
+          fallbackFix: "Verify authentication, organization context, and args/options, then retry.",
+        });
+        const failed = status.fail(rendered.message);
+        if (failed !== undefined) {
+          yield failed;
+        }
+        return c.error({
+          ...rendered,
+          exitCode: 1,
+        });
+      } finally {
+        status.stop();
+      }
+    },
+  };
+}
+
+function ensureChild(parent: CommandTreeNode, name: string): CommandTreeNode {
+  const existing = parent.children.get(name);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const created: CommandTreeNode = { children: new Map(), operations: [] };
+  parent.children.set(name, created);
+  return created;
+}
+
+function insertOperation(root: CommandTreeNode, descriptor: OperationDescriptor): void {
+  let node = root;
+  for (const segment of descriptor.commandPath) {
+    node = ensureChild(node, segment);
+  }
+  node.operations.push(descriptor);
+}
+
+const VERB_DESCRIPTIONS: Readonly<Record<string, string>> = {
+  get: "Read and list resources (maps from GET).",
+  create: "Create resources and run POST actions (maps from POST).",
+  delete: "Delete resources (maps from DELETE).",
+  patch: "Partially update resources (maps from PATCH).",
+  replace: "Replace resources (maps from PUT).",
+};
+
+function groupDescription(pathPrefix: ReadonlyArray<string>, node: CommandTreeNode): string {
+  if (pathPrefix.length === 1) {
+    const verb = pathPrefix[0]!;
+    if (VERB_DESCRIPTIONS[verb] !== undefined) {
+      return VERB_DESCRIPTIONS[verb];
+    }
+  }
+
+  const queue: Array<CommandTreeNode> = [node];
+  const seenTags = new Set<string>();
+  while (queue.length > 0) {
+    const current = queue.shift()!;
+    for (const op of current.operations) {
+      for (const tag of op.surface.tags) {
+        if (seenTags.has(tag)) {
+          continue;
+        }
+        seenTags.add(tag);
+        const desc = tagDescription(tag);
+        if (desc !== undefined) {
+          return desc;
+        }
+      }
+    }
+    for (const child of current.children.values()) {
+      queue.push(child);
+    }
+  }
+
+  return pathPrefix.join(" ");
+}
+
+function mountTree(
+  parent: Cli.Cli<Record<string, never>, typeof cliVars>,
+  nodes: Map<string, CommandTreeNode>,
+  pathPrefix: ReadonlyArray<string>
+): void {
+  for (const [name, node] of [...nodes.entries()].sort(([left], [right]) => left.localeCompare(right))) {
+    const pathHere = [...pathPrefix, name];
+    const hasChildren = node.children.size > 0;
+    const hasOps = node.operations.length > 0;
+
+    if (hasOps && !hasChildren) {
+      parent.command(name, makeLeafHandler(node.operations));
+      continue;
+    }
+
+    const group = Cli.create(name, {
+      description: groupDescription(pathHere, node),
+      vars: cliVars,
+    });
+
+    if (hasOps) {
+      group.command(INDEX_COMMAND, makeLeafHandler(node.operations));
+    }
+
+    if (hasChildren) {
+      mountTree(group, node.children, pathHere);
+    }
+
+    parent.command(group);
+  }
+}
+
+export function registerGeneratedOperations(
+  root: Cli.Cli<Record<string, never>, typeof cliVars>,
+  operations: ReadonlyArray<OperationDescriptor> = listCliOperations()
+): void {
+  const tree: CommandTreeNode = { children: new Map(), operations: [] };
+
+  for (const descriptor of operations) {
+    insertOperation(tree, descriptor);
+  }
+
+  mountTree(root, tree.children, []);
+  if (tree.operations.length > 0) {
+    root.command(INDEX_COMMAND, makeLeafHandler(tree.operations));
+  }
+}

package/src/lib/run-command.ts

@@ -0,0 +1,38 @@
+import type { CliCtaBlock } from "./cli-cta.ts";
+import { renderSdkErrorForCli, type CliErrorContext } from "./errors.ts";
+
+const UNKNOWN_COMMAND_ERROR: CliErrorContext = {
+  code: "UNKNOWN_ERROR",
+  fallbackMessage: "The CLI command failed unexpectedly.",
+  fallbackWhy: "The command encountered an unexpected internal failure.",
+  fallbackFix: "Retry the command. If the problem persists, report the error details to support.",
+};
+
+export interface IncurErrorContext<ErrorResult = never> {
+  readonly error: (error: {
+    code: string;
+    message: string;
+    retryable?: boolean;
+    exitCode?: number;
+    cta?: CliCtaBlock;
+  }) => ErrorResult;
+  readonly request?: Request;
+}
+
+export async function runCommand<A, ErrorResult = never>(
+  context: IncurErrorContext<ErrorResult>,
+  operation: Promise<A>,
+  errorContext: CliErrorContext = UNKNOWN_COMMAND_ERROR
+): Promise<A | ErrorResult> {
+  try {
+    return await operation;
+  } catch (error) {
+    if (error instanceof DOMException && error.name === "AbortError") {
+      throw error;
+    }
+    return context.error({
+      ...renderSdkErrorForCli(error, errorContext),
+      exitCode: 1,
+    });
+  }
+}