@settlemint/dalp-cli 3.1.32-main.42194559254 → 3.1.32-main.42209626311

package/src/lib/coverage.ts

@@ -0,0 +1,41 @@
+export interface CoverageOperation {
+  readonly name: string;
+  readonly hintKey: string;
+}
+
+export function findSurfaceGaps(
+  sdkOperations: ReadonlyArray<string>,
+  hasSurface: (name: string) => boolean
+): Array<string> {
+  return sdkOperations.filter((name) => !hasSurface(name));
+}
+
+const MANIFEST_HINT_KEY = /\b[A-Z]+ \/\S+/g;
+
+export function findMountGaps(operations: ReadonlyArray<CoverageOperation>, manifest: string): Array<string> {
+  const mounted = new Set(manifest.match(MANIFEST_HINT_KEY));
+  return operations.filter((operation) => !mounted.has(operation.hintKey)).map((operation) => operation.name);
+}
+
+export interface ExemptionGaps {
+  readonly stale: ReadonlyArray<string>;
+  readonly reasonless: ReadonlyArray<string>;
+}
+
+export function findExemptionGaps(
+  exemptions: ReadonlyMap<string, string>,
+  sdkOperations: ReadonlyArray<string>
+): ExemptionGaps {
+  const live = new Set(sdkOperations);
+  const stale: Array<string> = [];
+  const reasonless: Array<string> = [];
+  for (const [name, reason] of exemptions) {
+    if (!live.has(name)) {
+      stale.push(name);
+    }
+    if (reason.trim().length === 0) {
+      reasonless.push(name);
+    }
+  }
+  return { stale, reasonless };
+}

package/src/lib/credential-store.ts

@@ -0,0 +1,222 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { z } from "zod";
+import { getConfigDir } from "./cli-config.ts";
+import { makeCliError, isCliFailure } from "./errors.ts";
+
+const SERVICE_NAME = "dalp-cli";
+
+const StoredCredentialsSchema = z.object({
+  apiKey: z.string().min(1),
+  apiKeyId: z.string().min(1),
+  userEmail: z.string().min(1),
+  userId: z.string().min(1),
+  activeOrgId: z.string().min(1).optional(),
+  apiUrl: z.url(),
+});
+
+export type StoredCredentials = z.infer<typeof StoredCredentialsSchema>;
+
+export interface CredentialStoreOptions {
+  readonly configDir?: string;
+  readonly platform?: NodeJS.Platform;
+  readonly runSecurity?: (
+    args: ReadonlyArray<string>
+  ) => Promise<{ readonly exitCode: number; readonly stdout: string }>;
+}
+
+const defaultRunSecurity = async (
+  args: ReadonlyArray<string>
+): Promise<{ readonly exitCode: number; readonly stdout: string }> => {
+  const proc = Bun.spawn(["security", ...args], { stdout: "pipe", stderr: "pipe" });
+  const [stdout, exitCode] = await Promise.all([new Response(proc.stdout).text(), proc.exited]);
+  return { exitCode, stdout };
+};
+
+function credentialsFile(configDir: string): string {
+  return path.join(configDir, "credentials.json");
+}
+
+async function keychainAccounts(
+  runSecurity: NonNullable<CredentialStoreOptions["runSecurity"]>
+): Promise<Array<string>> {
+  const dump = await runSecurity(["dump-keychain"]);
+  if (dump.exitCode !== 0) {
+    throw makeCliError({
+      code: "kit.cli.CREDENTIAL_STORE_FAILED",
+      message: `Keychain dump failed with exit code ${dump.exitCode}`,
+    });
+  }
+  const accounts = new Set<string>();
+  for (const entry of dump.stdout.split(/\n(?=keychain:)/u)) {
+    if (!entry.includes(`"svce"<blob>="${SERVICE_NAME}"`)) {
+      continue;
+    }
+    const account = entry.match(/"acct"<blob>="([^"]*)"/u)?.[1];
+    if (account !== undefined) {
+      accounts.add(account);
+    }
+  }
+  return [...accounts];
+}
+
+async function deleteKeychainAccount(
+  runSecurity: NonNullable<CredentialStoreOptions["runSecurity"]>,
+  account: string
+): Promise<void> {
+  const result = await runSecurity(["delete-generic-password", "-s", SERVICE_NAME, "-a", account]);
+  if (result.exitCode !== 0) {
+    throw makeCliError({
+      code: "kit.cli.CREDENTIAL_STORE_FAILED",
+      message: `Keychain delete failed for ${account} with exit code ${result.exitCode}`,
+    });
+  }
+}
+
+function resolvePlatform(options: CredentialStoreOptions): NodeJS.Platform {
+  if (options.platform !== undefined) {
+    return options.platform;
+  }
+  const override = process.env.DALP_CREDENTIAL_PLATFORM;
+  if (override === "darwin" || override === "linux" || override === "win32") {
+    return override;
+  }
+  return process.platform;
+}
+
+export async function saveCredentials(
+  credentials: StoredCredentials,
+  options: CredentialStoreOptions = {}
+): Promise<void> {
+  const parsed = StoredCredentialsSchema.parse(credentials);
+  const configDir = options.configDir ?? getConfigDir();
+  const platform = resolvePlatform(options);
+  const runSecurity = options.runSecurity ?? defaultRunSecurity;
+  const encoded = JSON.stringify(parsed);
+
+  if (platform === "darwin") {
+    const existing = await keychainAccounts(runSecurity);
+    const result = await runSecurity([
+      "add-generic-password",
+      "-s",
+      SERVICE_NAME,
+      "-a",
+      parsed.userEmail,
+      "-w",
+      encoded,
+      "-U",
+    ]);
+    if (result.exitCode !== 0) {
+      throw makeCliError({
+        code: "kit.cli.CREDENTIAL_STORE_FAILED",
+        message: `Keychain save failed with exit code ${result.exitCode}`,
+      });
+    }
+    try {
+      for (const account of existing.filter((name) => name !== parsed.userEmail)) {
+        await deleteKeychainAccount(runSecurity, account);
+      }
+    } catch (error) {
+      if (!existing.includes(parsed.userEmail)) {
+        await runSecurity(["delete-generic-password", "-s", SERVICE_NAME, "-a", parsed.userEmail]);
+      }
+      throw error;
+    }
+    return;
+  }
+
+  await mkdir(configDir, { recursive: true, mode: 0o700 });
+  const file = credentialsFile(configDir);
+  await writeFile(file, encoded, { mode: 0o600 });
+  await chmod(file, 0o600);
+}
+
+export async function loadCredentials(options: CredentialStoreOptions = {}): Promise<StoredCredentials | undefined> {
+  const configDir = options.configDir ?? getConfigDir();
+  const platform = resolvePlatform(options);
+  const runSecurity = options.runSecurity ?? defaultRunSecurity;
+
+  let encoded: string;
+  if (platform === "darwin") {
+    const accounts = await keychainAccounts(runSecurity);
+    if (accounts.length === 0) {
+      return undefined;
+    }
+    if (accounts.length > 1) {
+      throw makeCliError({
+        code: "kit.cli.CREDENTIAL_STORE_FAILED",
+        message: `Multiple ${SERVICE_NAME} keychain accounts found (${accounts.join(", ")}). Remove the stale account or keep exactly one DALP CLI login before retrying.`,
+      });
+    }
+    const result = await runSecurity(["find-generic-password", "-s", SERVICE_NAME, "-a", accounts[0]!, "-w"]);
+    if (result.exitCode !== 0) {
+      throw makeCliError({
+        code: "kit.cli.CREDENTIAL_STORE_FAILED",
+        message: `The ${SERVICE_NAME} keychain item for ${accounts[0]!} could not be read (exit code ${result.exitCode}). Run 'dalp logout' to remove it, then 'dalp login'.`,
+      });
+    }
+    encoded = result.stdout.trim();
+  } else {
+    const file = credentialsFile(configDir);
+    try {
+      const stats = await Bun.file(file).stat();
+      if ((stats.mode & 0o077) !== 0) {
+        throw makeCliError({
+          code: "kit.cli.CREDENTIAL_STORE_FAILED",
+          message: `Credentials file has insecure permissions: ${(stats.mode & 0o777).toString(8)}. Run 'chmod 600 ${file}' to fix.`,
+        });
+      }
+      encoded = await readFile(file, "utf8");
+    } catch (error) {
+      if (isCliFailure(error)) {
+        throw error;
+      }
+      if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+        return undefined;
+      }
+      throw makeCliError({
+        code: "kit.cli.CREDENTIAL_STORE_FAILED",
+        message: error instanceof Error ? error.message : "Failed to load credentials",
+        cause: error,
+      });
+    }
+  }
+
+  try {
+    return StoredCredentialsSchema.parse(JSON.parse(encoded));
+  } catch (error) {
+    throw makeCliError({
+      code: "kit.cli.CREDENTIAL_STORE_FAILED",
+      message: "Stored credentials are invalid or corrupt.",
+      why: "The credential payload failed Zod validation.",
+      fix: "Run 'dalp logout' then 'dalp login' to refresh credentials.",
+      cause: error,
+    });
+  }
+}
+
+export async function deleteCredentials(options: CredentialStoreOptions = {}): Promise<void> {
+  const configDir = options.configDir ?? getConfigDir();
+  const platform = resolvePlatform(options);
+  const runSecurity = options.runSecurity ?? defaultRunSecurity;
+
+  if (platform === "darwin") {
+    for (const account of await keychainAccounts(runSecurity)) {
+      await deleteKeychainAccount(runSecurity, account);
+    }
+    return;
+  }
+
+  try {
+    await unlink(credentialsFile(configDir));
+  } catch (error) {
+    if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+      return;
+    }
+    throw makeCliError({
+      code: "kit.cli.CREDENTIAL_STORE_FAILED",
+      message: error instanceof Error ? error.message : "Failed to delete credentials",
+      cause: error,
+    });
+  }
+}

package/src/lib/errors.ts

@@ -0,0 +1,188 @@
+import { findDalpSdkError, isDalpApiError } from "@settlemint/dalp-sdk";
+import { buildErrorCta, extractResourceLinks, type CliCtaBlock, type ResourceLinks } from "./cli-cta.ts";
+
+export interface CliErrorContext {
+  readonly code: string;
+  readonly fallbackMessage: string;
+  readonly fallbackWhy: string;
+  readonly fallbackFix: string;
+}
+
+export interface RenderedCliError {
+  readonly code: string;
+  readonly message: string;
+  readonly retryable: boolean;
+  readonly cta: CliCtaBlock;
+}
+
+export class CliError extends Error {
+  override readonly name = "CliError";
+  readonly code: string;
+  readonly retryable: boolean;
+  readonly why: string;
+  readonly fix: string;
+  readonly links?: ResourceLinks;
+  readonly category?: string;
+
+  constructor(options: {
+    readonly message: string;
+    readonly code: string;
+    readonly retryable?: boolean;
+    readonly why?: string;
+    readonly fix?: string;
+    readonly cause?: unknown;
+    readonly links?: ResourceLinks;
+    readonly category?: string;
+  }) {
+    super(options.message, options.cause === undefined ? undefined : { cause: options.cause });
+    this.code = options.code;
+    this.retryable = options.retryable ?? false;
+    this.why = options.why ?? "The CLI operation failed.";
+    this.fix = options.fix ?? "Correct the input or environment, then retry.";
+    if (options.links !== undefined) {
+      this.links = options.links;
+    }
+    if (options.category !== undefined) {
+      this.category = options.category;
+    }
+  }
+}
+
+export function makeCliError(options: ConstructorParameters<typeof CliError>[0]): CliError {
+  return new CliError(options);
+}
+
+export function isCliFailure(error: unknown): error is CliError {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    Reflect.get(error, "name") === "CliError" &&
+    typeof Reflect.get(error, "code") === "string" &&
+    typeof Reflect.get(error, "message") === "string"
+  );
+}
+
+export interface NormalizedFailure {
+  readonly code: string;
+  readonly message: string;
+  readonly why: string;
+  readonly fix: string;
+  readonly retryable: boolean;
+  readonly category?: string;
+  readonly links?: ResourceLinks;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function extractWireFailure(error: unknown): NormalizedFailure | undefined {
+  if (!isRecord(error)) {
+    return undefined;
+  }
+  const message = typeof error.message === "string" ? error.message : undefined;
+  const code = typeof error.code === "string" ? error.code : undefined;
+  const data = isRecord(error.data) ? error.data : undefined;
+
+  const whyFromData = data !== undefined && typeof data.why === "string" ? data.why : undefined;
+  const fixFromData = data !== undefined && typeof data.fix === "string" ? data.fix : undefined;
+  const whyTop = typeof error.why === "string" ? error.why : undefined;
+  const fixTop = typeof error.fix === "string" ? error.fix : undefined;
+  const why = whyFromData ?? whyTop;
+  const fix = fixFromData ?? fixTop;
+
+  if (message === undefined && why === undefined && code === undefined) {
+    return undefined;
+  }
+  if (code === undefined && why === undefined) {
+    return undefined;
+  }
+
+  const retryableFromData = data !== undefined && typeof data.retryable === "boolean" ? data.retryable : undefined;
+  const retryableTop = typeof error.retryable === "boolean" ? error.retryable : undefined;
+  const categoryFromData = data !== undefined && typeof data.category === "string" ? data.category : undefined;
+  const categoryTop = typeof error.category === "string" ? error.category : undefined;
+  const idFromData = data !== undefined && typeof data.id === "string" ? data.id : undefined;
+
+  const links = extractResourceLinks(error) ?? (data !== undefined ? extractResourceLinks(data) : undefined);
+
+  return {
+    code: code ?? idFromData ?? "API_ERROR",
+    message: message ?? code ?? "Request failed",
+    why: why ?? "The DALP API rejected the request.",
+    fix: fix ?? "Correct the input or environment, then retry.",
+    retryable: retryableFromData ?? retryableTop ?? false,
+    ...(categoryFromData !== undefined || categoryTop !== undefined
+      ? { category: categoryFromData ?? categoryTop }
+      : {}),
+    ...(links === undefined ? {} : { links }),
+  };
+}
+
+function normalizeFailure(error: unknown, context: CliErrorContext): NormalizedFailure {
+  if (isDalpApiError(error)) {
+    return {
+      code: error.code,
+      message: error.message,
+      why: error.why,
+      fix: error.fix,
+      retryable: error.retryable,
+      category: error.category,
+      ...(extractResourceLinks(error) === undefined ? {} : { links: extractResourceLinks(error) }),
+    };
+  }
+
+  const sdkError = findDalpSdkError(error);
+  if (sdkError !== undefined) {
+    return {
+      code: sdkError.code,
+      message: sdkError.message,
+      why: sdkError.why,
+      fix: sdkError.fix,
+      retryable: sdkError.retryable,
+      category: sdkError.category,
+    };
+  }
+
+  if (isCliFailure(error)) {
+    return {
+      code: error.code,
+      message: error.message,
+      why: error.why,
+      fix: error.fix,
+      retryable: error.retryable,
+      ...(error.category === undefined ? {} : { category: error.category }),
+      ...(error.links === undefined ? {} : { links: error.links }),
+    };
+  }
+
+  const wire = extractWireFailure(error);
+  if (wire !== undefined) {
+    return wire;
+  }
+
+  const message = error instanceof Error ? error.message : context.fallbackMessage;
+  return {
+    code: context.code,
+    message,
+    why: context.fallbackWhy,
+    fix: context.fallbackFix,
+    retryable: false,
+  };
+}
+
+export function renderSdkErrorForCli(error: unknown, context: CliErrorContext): RenderedCliError {
+  const failure = normalizeFailure(error, context);
+  return {
+    code: failure.code,
+    message: failure.message,
+    retryable: failure.retryable,
+    cta: buildErrorCta({
+      why: failure.why,
+      fix: failure.fix,
+      code: failure.code,
+      ...(failure.category === undefined ? {} : { category: failure.category }),
+      ...(failure.links === undefined ? {} : { links: failure.links }),
+    }),
+  };
+}

package/src/lib/openapi-surface-types.ts

@@ -0,0 +1,41 @@
+export interface SurfaceParam {
+  readonly name: string;
+  readonly in: "path" | "query" | "header";
+  readonly required: boolean;
+  readonly description: string | null;
+  readonly type: string | null;
+  readonly enum: ReadonlyArray<string> | null;
+  readonly pattern: string | null;
+  readonly examples: ReadonlyArray<string>;
+  readonly default: unknown;
+  readonly fields: ReadonlyArray<SurfaceParam>;
+}
+
+export interface SurfaceOperation {
+  readonly name: string;
+  readonly method: string;
+  readonly url: string;
+  readonly summary: string | null;
+  readonly description: string | null;
+  readonly help: string;
+  readonly tags: ReadonlyArray<string>;
+  readonly pathParams: ReadonlyArray<SurfaceParam>;
+  readonly queryParams: ReadonlyArray<SurfaceParam>;
+  readonly headerParams: ReadonlyArray<SurfaceParam>;
+  readonly requestBodyDescription: string | null;
+  readonly hasRequestBody: boolean;
+  readonly bodyIsComplex: boolean;
+  readonly bodyFields: ReadonlyArray<SurfaceParam>;
+  readonly examples: ReadonlyArray<{
+    readonly description: string;
+    readonly path?: Record<string, string>;
+    readonly query?: Record<string, string>;
+  }>;
+}
+
+export interface OpenApiSurface {
+  readonly openapiSource: string;
+  readonly sdkSource: string;
+  readonly operations: Record<string, SurfaceOperation>;
+  readonly tags: Record<string, string>;
+}

package/src/lib/openapi-surface.ts

@@ -0,0 +1,17 @@
+import path from "node:path";
+import surfaceAssetPath from "../generated/openapi-surface.json" with { type: "file" };
+import type { OpenApiSurface, SurfaceOperation } from "./openapi-surface-types.ts";
+
+export type { OpenApiSurface, SurfaceOperation, SurfaceParam } from "./openapi-surface-types.ts";
+
+const surfaceFile = path.resolve(import.meta.dir, surfaceAssetPath);
+const openApiSurface = (await Bun.file(surfaceFile).json()) as OpenApiSurface;
+
+export function surfaceFor(operationName: string): SurfaceOperation | undefined {
+  return openApiSurface.operations[operationName];
+}
+
+export function tagDescription(tag: string): string | undefined {
+  const value = openApiSurface.tags[tag];
+  return value !== undefined && value.trim() !== "" ? value : undefined;
+}

package/src/lib/operation-inventory.ts

@@ -0,0 +1,69 @@
+import type { z } from "zod";
+import { commandPathForUrl, isNonCliOperation, routeIds, staticUrlSegments } from "@settlemint/dalp-sdk/routes";
+import type { DalpRouteId } from "@settlemint/dalp-sdk/types";
+import { zodForRequestBody, zodFromSurfaceParams } from "./sdk-cli-schema.ts";
+import { surfaceFor, type SurfaceOperation } from "./openapi-surface.ts";
+export interface OperationDescriptor {
+  readonly name: DalpRouteId;
+  readonly url: string;
+  readonly method: string;
+  readonly group: string;
+  readonly commandPath: ReadonlyArray<string>;
+  readonly pathSchema?: z.ZodType;
+  readonly querySchema?: z.ZodType;
+  readonly bodySchema?: z.ZodType;
+  readonly surface: SurfaceOperation;
+  readonly help: string;
+}
+
+function groupForUrl(url: string): string {
+  const segments = staticUrlSegments(url);
+  return segments[0] ?? "api";
+}
+
+export function operationHintKey(method: string, url: string): string {
+  return `${method} ${url}`;
+}
+
+export function listSdkOperationNames(): Array<DalpRouteId> {
+  return [...routeIds];
+}
+
+function buildGeneratedOperations(): Array<OperationDescriptor> {
+  const descriptors: Array<OperationDescriptor> = [];
+  for (const name of listSdkOperationNames()) {
+    const surface = surfaceFor(name);
+    if (surface === undefined) {
+      continue;
+    }
+    const { url, method } = surface;
+    descriptors.push({
+      name,
+      url,
+      method,
+      group: groupForUrl(url),
+      commandPath: commandPathForUrl(method, url),
+      pathSchema: zodFromSurfaceParams(surface.pathParams) as z.ZodType | undefined,
+      querySchema: zodFromSurfaceParams(surface.queryParams) as z.ZodType | undefined,
+      bodySchema: zodForRequestBody(surface),
+      surface,
+      help: surface.help,
+    });
+  }
+  return descriptors.sort((left, right) => left.name.localeCompare(right.name));
+}
+
+let generatedOperations: ReadonlyArray<OperationDescriptor> | undefined;
+
+export function listGeneratedOperations(): Array<OperationDescriptor> {
+  generatedOperations ??= buildGeneratedOperations();
+  return [...generatedOperations];
+}
+
+export function listCliOperations(): Array<OperationDescriptor> {
+  return listGeneratedOperations().filter((descriptor) => !isNonCliOperation(descriptor.name));
+}
+
+export function listGeneratedOperationNames(): Array<string> {
+  return listGeneratedOperations().map((descriptor) => descriptor.name);
+}