@utdk/cli 0.1.0-dev.646adf4

package/src/cli.ts

@@ -0,0 +1,451 @@
+/**
+ * Core CLI logic for @utdk/cli.
+ *
+ * Usage:
+ *   utdk [--output json|table] [--agent] <provider> <operation> [--flag value…]
+ *   utdk --help
+ *   utdk --version
+ *   utdk <provider> --help
+ *
+ * Exit codes (matching cli-printing-press):
+ *   0  success
+ *   2  usage error  (unknown provider / operation, bad args)
+ *   3  not found    (HTTP 404)
+ *   4  auth failure (HTTP 401/403)
+ *   5  API error    (HTTP 5xx)
+ *   7  rate limited (HTTP 429)
+ */
+
+import { readFileSync } from "fs";
+import { join } from "path";
+import { createClient } from "utdk/client";
+
+import { resolveAuth, authEnvVars } from "./auth.js";
+import {
+  defaultOutputMode,
+  renderHelpList,
+  writeOutput,
+  type OutputMode,
+} from "./format.js";
+import {
+  buildToolMetadata,
+  findOperation,
+  getProviderInfo,
+  listOperations,
+  listProviders,
+  UTDK_ROOT,
+  type OperationInfo,
+} from "./providers.js";
+
+// ---------------------------------------------------------------------------
+// CLI version
+// ---------------------------------------------------------------------------
+
+const VERSION = "0.1.0";
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+type ParsedArgs = {
+  output: OutputMode | undefined;
+  agent: boolean;
+  help: boolean;
+  version: boolean;
+  provider: string | undefined;
+  operation: string | undefined;
+  params: Record<string, unknown>;
+};
+
+function coerceValue(raw: string): unknown {
+  if (raw === "true") return true;
+  if (raw === "false") return false;
+  if (/^-?\d+(\.\d+)?$/.test(raw)) return Number(raw);
+  return raw;
+}
+
+export function parseArgs(argv: string[]): ParsedArgs {
+  const result: ParsedArgs = {
+    output: undefined,
+    agent: false,
+    help: false,
+    version: false,
+    provider: undefined,
+    operation: undefined,
+    params: {},
+  };
+
+  const positionals: string[] = [];
+
+  let i = 0;
+  while (i < argv.length) {
+    const arg = argv[i] as string;
+
+    if (arg === "--help" || arg === "-h") {
+      result.help = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--version" || arg === "-v") {
+      result.version = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--agent") {
+      result.agent = true;
+      i++;
+      continue;
+    }
+
+    if (arg === "--output" || arg === "-o") {
+      const val = argv[i + 1];
+      if (val === "json" || val === "table" || val === "agent") {
+        result.output = val;
+        i += 2;
+      } else {
+        i++;
+      }
+      continue;
+    }
+
+    if (arg.startsWith("--output=")) {
+      const val = arg.slice(9);
+      if (val === "json" || val === "table" || val === "agent") result.output = val;
+      i++;
+      continue;
+    }
+
+    if (arg.startsWith("--") && arg.length > 2) {
+      const key = arg.slice(2);
+      const nextArg = argv[i + 1];
+      if (nextArg !== undefined && !nextArg.startsWith("--")) {
+        const existing = result.params[key];
+        const coerced = coerceValue(nextArg);
+        if (existing !== undefined) {
+          result.params[key] = Array.isArray(existing)
+            ? [...existing, coerced]
+            : [existing, coerced];
+        } else {
+          result.params[key] = coerced;
+        }
+        i += 2;
+      } else {
+        result.params[key] = true;
+        i++;
+      }
+      continue;
+    }
+
+    positionals.push(arg);
+    i++;
+  }
+
+  result.provider = positionals[0];
+  result.operation = positionals[1];
+
+  return result;
+}
+
+// ---------------------------------------------------------------------------
+// Error → exit code mapping
+// ---------------------------------------------------------------------------
+
+function exitCodeForError(error: unknown): number {
+  const msg = error instanceof Error ? error.message : String(error);
+  const m = /Request failed: (\d+)/.exec(msg);
+  if (!m) return 1;
+  const status = parseInt(m[1] ?? "0", 10);
+  if (status === 404) return 3;
+  if (status === 401 || status === 403) return 4;
+  if (status === 429) return 7;
+  if (status >= 500) return 5;
+  return 2;
+}
+
+// ---------------------------------------------------------------------------
+// Help text builders
+// ---------------------------------------------------------------------------
+
+function printGlobalHelp(): void {
+  const providers = listProviders();
+  process.stdout.write(
+    [
+      `utdk v${VERSION} — agent-native CLI for @utdk providers`,
+      "",
+      "Usage:",
+      "  utdk [--output json|table] [--agent] <provider> <operation> [--flag value…]",
+      "  utdk <provider> --help",
+      "  utdk --help",
+      "",
+      "Global flags:",
+      "  --output json|table  Output format (default: table in TTY, json when piped)",
+      "  --agent              Compact JSON output optimised for agent parsing",
+      "  --help, -h           Show this help or provider/operation help",
+      "  --version, -v        Print version",
+      "",
+      "Providers:",
+    ].join("\n"),
+  );
+  process.stdout.write("\n");
+  if (providers.length === 0) {
+    process.stdout.write("  (none found — is the utdk package built?)\n");
+  } else {
+    const items = providers.map((name): [string, string] => {
+      const info = getProviderInfo(name);
+      return [name, info?.description?.slice(0, 70) ?? ""];
+    });
+    process.stdout.write(renderHelpList(items, 20));
+    process.stdout.write("\n");
+  }
+  process.stdout.write("\n");
+}
+
+function printProviderHelp(providerName: string): void {
+  const info = getProviderInfo(providerName);
+  if (!info) {
+    process.stderr.write(`Provider "${providerName}" not found.\n`);
+    process.exitCode = 2;
+    return;
+  }
+
+  const ops = listOperations(providerName);
+  const envVars = authEnvVars(providerName, info.auth);
+
+  process.stdout.write(
+    [
+      `utdk ${providerName} — ${info.description ?? ""}`,
+      "",
+      "Usage:",
+      `  utdk ${providerName} <operation> [--flag value…]`,
+      "",
+      "Auth environment variables:",
+      envVars.map((v) => `  ${v}`).join("\n"),
+      "",
+      `Operations (${ops.length} total):`,
+    ].join("\n"),
+  );
+  process.stdout.write("\n");
+
+  const items: Array<[string, string]> = ops.slice(0, 100).map((op) => [
+    op.accessPath.join("."),
+    op.summary?.slice(0, 60) ?? `${op.method} ${op.path}`,
+  ]);
+  process.stdout.write(renderHelpList(items, 40));
+  process.stdout.write("\n");
+
+  if (ops.length > 100) {
+    process.stdout.write(
+      `\n  … and ${ops.length - 100} more. Filter with: utdk ${providerName} --help | grep <term>\n`,
+    );
+  }
+  process.stdout.write("\n");
+}
+
+function printOperationHelp(providerName: string, op: OperationInfo): void {
+  const info = getProviderInfo(providerName);
+  const envVars = authEnvVars(providerName, info?.auth ?? []);
+
+  process.stdout.write(
+    [
+      `utdk ${providerName} ${op.accessPath.join(".")}`,
+      "",
+      `${op.method} ${op.path}`,
+      op.summary ? `Summary: ${op.summary}` : "",
+      op.description ? `\n${op.description.slice(0, 300)}` : "",
+      "",
+      "Parameters:",
+    ]
+      .filter((l) => l !== "")
+      .join("\n"),
+  );
+  process.stdout.write("\n");
+
+  if (op.parameters.length === 0) {
+    process.stdout.write("  (none)\n");
+  } else {
+    const items: Array<[string, string]> = op.parameters.map((p) => [
+      `--${p.name}${p.required ? " *" : ""}`,
+      [p.in, p.type, p.description?.slice(0, 50)].filter(Boolean).join(" · "),
+    ]);
+    process.stdout.write(renderHelpList(items, 30));
+    process.stdout.write("\n");
+    process.stdout.write("\n  * = required\n");
+  }
+
+  process.stdout.write("\nAuth:\n");
+  process.stdout.write(envVars.map((v) => `  ${v}`).join("\n"));
+  process.stdout.write("\n\n");
+}
+
+// ---------------------------------------------------------------------------
+// Operation executor
+// ---------------------------------------------------------------------------
+
+/** Navigate a nested object using a dot-path. */
+function getNestedValue(obj: unknown, path: string[]): unknown {
+  return path.reduce<unknown>((current, key) => {
+    if (current !== null && typeof current === "object") {
+      return (current as Record<string, unknown>)[key];
+    }
+    return undefined;
+  }, obj);
+}
+
+async function executeOperation(
+  providerName: string,
+  op: OperationInfo,
+  params: Record<string, unknown>,
+  outputMode: OutputMode,
+): Promise<number> {
+  // Load the OpenAPI document for this provider
+  const openApiPath = join(UTDK_ROOT, providerName, "openapi.json");
+  let openApiDocument: object;
+  try {
+    openApiDocument = JSON.parse(readFileSync(openApiPath, "utf-8")) as object;
+  } catch {
+    process.stderr.write(`Failed to load OpenAPI spec for "${providerName}".\n`);
+    return 2;
+  }
+
+  // Resolve auth
+  const info = getProviderInfo(providerName);
+  const auth = resolveAuth(providerName, info?.auth ?? []);
+
+  // Build tool metadata from the OpenAPI spec so path/query/header/body
+  // params are routed correctly (provider metadata.ts files are often empty).
+  const allOps = listOperations(providerName);
+  const toolMetadata = buildToolMetadata(allOps);
+
+  // Create the client
+  let client: unknown;
+  try {
+    client = await createClient({
+      name: providerName,
+      openApiDocument,
+      toolMetadata,
+      ...(auth ? { auth } : {}),
+    });
+  } catch (err) {
+    process.stderr.write(
+      `Failed to create client for "${providerName}": ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 2;
+  }
+
+  // Navigate to the operation function
+  const fn = getNestedValue(client, op.accessPath);
+  if (typeof fn !== "function") {
+    process.stderr.write(
+      `Operation "${op.accessPath.join(".")}" not found on the ${providerName} client.\n`,
+    );
+    return 2;
+  }
+
+  // Call it
+  let result: unknown;
+  try {
+    result = await (fn as (params: Record<string, unknown>) => Promise<unknown>)(params);
+  } catch (err) {
+    const code = exitCodeForError(err);
+    const msg = err instanceof Error ? err.message : String(err);
+    if (outputMode === "json" || outputMode === "agent") {
+      writeOutput({ ok: false, error: msg, exitCode: code }, outputMode);
+    } else {
+      process.stderr.write(`Error: ${msg}\n`);
+    }
+    return code;
+  }
+
+  writeOutput(result, outputMode);
+  return 0;
+}
+
+// ---------------------------------------------------------------------------
+// Main entry
+// ---------------------------------------------------------------------------
+
+export async function runCli(argv: string[]): Promise<number> {
+  const args = parseArgs(argv);
+
+  // Determine output mode: --agent overrides --output
+  const outputMode: OutputMode = args.agent
+    ? "agent"
+    : (args.output ?? defaultOutputMode());
+
+  // --version
+  if (args.version) {
+    process.stdout.write(`@utdk/cli v${VERSION}\n`);
+    return 0;
+  }
+
+  // utdk --help
+  if (args.help && !args.provider) {
+    printGlobalHelp();
+    return 0;
+  }
+
+  // No provider — show global help
+  if (!args.provider) {
+    printGlobalHelp();
+    return 0;
+  }
+
+  // Validate provider
+  const providers = listProviders();
+  if (!providers.includes(args.provider)) {
+    if (outputMode === "json" || outputMode === "agent") {
+      writeOutput(
+        {
+          ok: false,
+          error: `Unknown provider: ${args.provider}`,
+          available: providers,
+        },
+        outputMode,
+      );
+    } else {
+      process.stderr.write(
+        `Unknown provider: "${args.provider}"\nAvailable: ${providers.join(", ")}\n`,
+      );
+    }
+    return 2;
+  }
+
+  // utdk <provider> --help or utdk <provider> (no operation)
+  if (args.help || !args.operation) {
+    printProviderHelp(args.provider);
+    return 0;
+  }
+
+  // Find the operation
+  const op = findOperation(args.provider, args.operation);
+  if (!op) {
+    // Maybe the user wants help on what they typed
+    if (outputMode === "json" || outputMode === "agent") {
+      writeOutput(
+        {
+          ok: false,
+          error: `Unknown operation: ${args.operation}`,
+          provider: args.provider,
+        },
+        outputMode,
+      );
+    } else {
+      process.stderr.write(
+        `Unknown operation "${args.operation}" for provider "${args.provider}".\n` +
+          `Run "utdk ${args.provider} --help" to list available operations.\n`,
+      );
+    }
+    return 2;
+  }
+
+  // utdk <provider> <operation> --help
+  if (args.help) {
+    printOperationHelp(args.provider, op);
+    return 0;
+  }
+
+  // Execute
+  return executeOperation(args.provider, op, args.params, outputMode);
+}

package/src/format.ts

@@ -0,0 +1,127 @@
+/**
+ * Output formatting for @utdk/cli.
+ *
+ * Supports three modes:
+ *   - json   : pretty-printed JSON (default when stdout is not a TTY)
+ *   - table  : padded text table (default when stdout is a TTY)
+ *   - agent  : compact single-line JSON with no ANSI escapes
+ */
+
+export type OutputMode = "json" | "table" | "agent";
+
+/** Detect the default output mode based on whether stdout is a TTY. */
+export function defaultOutputMode(): OutputMode {
+  return process.stdout.isTTY ? "table" : "json";
+}
+
+// ---------------------------------------------------------------------------
+// JSON output
+// ---------------------------------------------------------------------------
+
+export function formatJson(data: unknown, compact = false): string {
+  return compact ? JSON.stringify(data) : JSON.stringify(data, null, 2);
+}
+
+// ---------------------------------------------------------------------------
+// Table output
+// ---------------------------------------------------------------------------
+
+/** Render a two-column key/value table for a plain object. */
+function renderObjectTable(obj: Record<string, unknown>): string {
+  const entries = Object.entries(obj);
+  const keyWidth = Math.min(
+    40,
+    Math.max(4, ...entries.map(([k]) => k.length)),
+  );
+  const lines: string[] = [];
+  for (const [key, value] of entries) {
+    const k = key.padEnd(keyWidth);
+    const v = valueToCell(value);
+    lines.push(`${k}  ${v}`);
+  }
+  return lines.join("\n");
+}
+
+/** Render an array of objects as a columnar table. */
+function renderArrayTable(items: Record<string, unknown>[]): string {
+  if (items.length === 0) return "(empty)";
+  // Collect all column names from the first item (limit to 8 columns for readability)
+  const allKeys = Object.keys(items[0] ?? {});
+  const keys = allKeys.slice(0, 8);
+
+  const widths: number[] = keys.map((k) => {
+    const maxValue = Math.max(...items.map((r) => valueToCell(r[k]).length));
+    return Math.min(60, Math.max(k.length, maxValue));
+  });
+
+  const header = keys.map((k, i) => k.padEnd(widths[i] ?? k.length)).join("  ");
+  const divider = widths.map((w) => "─".repeat(w)).join("  ");
+  const rows = items.map((item) =>
+    keys
+      .map((k, i) => valueToCell(item[k]).slice(0, widths[i] ?? 60).padEnd(widths[i] ?? 0))
+      .join("  "),
+  );
+
+  return [header, divider, ...rows].join("\n");
+}
+
+function valueToCell(v: unknown): string {
+  if (v === null || v === undefined) return "";
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  if (Array.isArray(v)) return `[${v.length} items]`;
+  if (typeof v === "object") return "{…}";
+  return String(v);
+}
+
+function isObjectArray(data: unknown): data is Record<string, unknown>[] {
+  return (
+    Array.isArray(data) &&
+    data.length > 0 &&
+    typeof data[0] === "object" &&
+    data[0] !== null &&
+    !Array.isArray(data[0])
+  );
+}
+
+function isPlainObject(data: unknown): data is Record<string, unknown> {
+  return typeof data === "object" && data !== null && !Array.isArray(data);
+}
+
+export function formatTable(data: unknown): string {
+  if (isObjectArray(data)) return renderArrayTable(data);
+  if (isPlainObject(data)) return renderObjectTable(data);
+  if (Array.isArray(data)) return data.map((item) => valueToCell(item)).join("\n");
+  return valueToCell(data);
+}
+
+// ---------------------------------------------------------------------------
+// Unified output writer
+// ---------------------------------------------------------------------------
+
+export function writeOutput(data: unknown, mode: OutputMode): void {
+  let out: string;
+  switch (mode) {
+    case "json":
+      out = formatJson(data, false);
+      break;
+    case "agent":
+      out = formatJson(data, true);
+      break;
+    case "table":
+      out = formatTable(data);
+      break;
+  }
+  process.stdout.write(`${out}\n`);
+}
+
+// ---------------------------------------------------------------------------
+// Help table helpers
+// ---------------------------------------------------------------------------
+
+/** Render a two-column list with fixed-width left column. */
+export function renderHelpList(items: Array<[string, string]>, leftWidth = 30): string {
+  return items
+    .map(([left, right]) => `  ${left.padEnd(leftWidth)}  ${right}`)
+    .join("\n");
+}