@utdk/cli 0.1.0-dev.646adf4

package/dist/providers.js

@@ -0,0 +1,317 @@
+/**
+ * Provider and operation discovery for @utdk/cli.
+ *
+ * Scans the utdk package directory for providers and reads their OpenAPI
+ * specifications to enumerate operations. Name transformations mirror
+ * those in packages/utdk/client.ts so CLI operation names match the
+ * accessor paths on the created client.
+ *
+ * Also builds ToolRuntimeMetadataMap entries for path/query/header/body
+ * parameter routing, so the generated client can correctly assemble HTTP
+ * requests even when the provider's hand-written metadata.ts is empty.
+ */
+import { existsSync, readdirSync, readFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// Compiled to packages/utdk-cli/dist/; navigate to packages/utdk/
+export const UTDK_ROOT = resolve(__dirname, "..", "..", "utdk");
+// ---------------------------------------------------------------------------
+// Name transformation (mirrors client.ts identically)
+// ---------------------------------------------------------------------------
+function sanitizeIdentifier(name) {
+    return name.replace(/[^a-zA-Z0-9_]/g, "_").replace(/^[0-9]/, "_$&");
+}
+function splitIdentifierWords(name) {
+    return name
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+        .replace(/([A-Za-z])([0-9])/g, "$1 $2")
+        .replace(/([0-9])([A-Za-z])/g, "$1 $2")
+        .replace(/[^a-zA-Z0-9]+/g, " ")
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean);
+}
+export function toCamelCase(name) {
+    const cleaned = splitIdentifierWords(name);
+    if (cleaned.length === 0)
+        return "_";
+    const [first = "_", ...rest] = cleaned;
+    return sanitizeIdentifier(first.toLowerCase() +
+        rest.map((s) => s.charAt(0).toUpperCase() + s.slice(1).toLowerCase()).join(""));
+}
+/** Converts an OpenAPI operationId to a client access path (same logic as client.ts). */
+function operationIdToBasePath(operationId) {
+    const segments = operationId.split("/").filter(Boolean);
+    const path = (segments.length > 0 ? segments : [operationId]).map(toCamelCase);
+    // Collapse duplicate consecutive leaf (e.g. a/a → ['a','call'])
+    if (path.length > 1 && path[path.length - 1] === path[path.length - 2]) {
+        path[path.length - 1] = "call";
+    }
+    return path;
+}
+function hasPathConflict(candidate, used) {
+    const key = candidate.join(".");
+    for (const u of used) {
+        if (u === key || u.startsWith(`${key}.`) || key.startsWith(`${u}.`))
+            return true;
+    }
+    return false;
+}
+function resolveAccessPath(basePath, used) {
+    const baseLeaf = basePath[basePath.length - 1] ?? "_";
+    let path = [...basePath];
+    let suffix = 2;
+    while (hasPathConflict(path, used)) {
+        path = [...basePath.slice(0, -1), `${baseLeaf}_${suffix}`];
+        suffix++;
+    }
+    used.add(path.join("."));
+    return path;
+}
+// ---------------------------------------------------------------------------
+// Provider listing
+// ---------------------------------------------------------------------------
+/** Returns all provider names found in the utdk package directory. */
+export function listProviders() {
+    if (!existsSync(UTDK_ROOT))
+        return [];
+    const entries = readdirSync(UTDK_ROOT, { withFileTypes: true });
+    return entries
+        .filter((e) => e.isDirectory() && existsSync(join(UTDK_ROOT, e.name, "openapi.json")))
+        .map((e) => e.name)
+        .sort();
+}
+/** Returns metadata for a single provider, or undefined if not found. */
+export function getProviderInfo(providerName) {
+    const providerDir = join(UTDK_ROOT, providerName);
+    if (!existsSync(providerDir))
+        return undefined;
+    const pkgPath = join(providerDir, "package.json");
+    try {
+        const pkg = JSON.parse(readFileSync(pkgPath, "utf-8"));
+        return {
+            name: providerName,
+            description: pkg.description ?? pkg.utdk?.openapi?.title,
+            auth: pkg.utdk?.auth ?? [],
+        };
+    }
+    catch {
+        return { name: providerName, auth: [] };
+    }
+}
+const HTTP_METHODS = new Set(["get", "post", "put", "patch", "delete", "head", "options"]);
+const JSON_CONTENT_TYPES = new Set([
+    "application/json",
+    "application/json-patch+json",
+    "application/merge-patch+json",
+    "application/vnd.api+json",
+]);
+/** Resolve a JSON $ref to a schema object within the document. */
+function resolveRef(doc, ref) {
+    if (!ref.startsWith("#/"))
+        return undefined;
+    const parts = ref.slice(2).split("/");
+    let current = doc;
+    for (const part of parts) {
+        if (current == null || typeof current !== "object")
+            return undefined;
+        current = current[part.replace(/~1/g, "/").replace(/~0/g, "~")];
+    }
+    return current;
+}
+function resolveSchemaRef(doc, schema) {
+    if (schema.$ref) {
+        return resolveRef(doc, schema.$ref) ?? schema;
+    }
+    return schema;
+}
+/** Resolve a $ref parameter to a concrete OpenApiParameter, or return the input if already concrete. */
+function resolveParameter(doc, param) {
+    if (!("name" in param)) {
+        // It's a $ref
+        const resolved = resolveRef(doc, param.$ref);
+        if (resolved && "name" in resolved) {
+            return resolved;
+        }
+        return undefined;
+    }
+    return param;
+}
+/** Extract BodyInfo from an OpenAPI 3.x requestBody or Swagger 2 body param. */
+function extractBodyInfo(doc, operation) {
+    // Check requestBody (OpenAPI 3.x)
+    if (operation.requestBody) {
+        let rb = operation.requestBody;
+        if ("$ref" in rb) {
+            const resolved = resolveRef(doc, rb.$ref);
+            if (resolved)
+                rb = resolved;
+            else
+                return { kind: "none", propertyKeys: [] };
+        }
+        const content = rb.content;
+        if (!content)
+            return { kind: "raw", propertyKeys: [] };
+        // Prefer JSON content types
+        const jsonEntry = Object.entries(content).find(([ct]) => JSON_CONTENT_TYPES.has(ct) || ct.includes("json"));
+        const [contentType, mediaType] = jsonEntry ?? Object.entries(content)[0] ?? [];
+        if (!contentType || !mediaType)
+            return { kind: "none", propertyKeys: [] };
+        const rawSchema = mediaType.schema;
+        if (!rawSchema)
+            return { kind: "raw", propertyKeys: [], contentType };
+        const schema = resolveSchemaRef(doc, rawSchema);
+        if (schema.type === "object" || schema.properties) {
+            const keys = Object.keys(schema.properties ?? {});
+            const allowsAdditional = schema.additionalProperties === true ||
+                (typeof schema.additionalProperties === "object" && schema.additionalProperties !== null);
+            return {
+                kind: "properties",
+                propertyKeys: keys,
+                contentType,
+                allowsAdditionalProperties: allowsAdditional || undefined,
+            };
+        }
+        return { kind: "raw", propertyKeys: [], contentType };
+    }
+    // Swagger 2: check for body or formData parameters
+    const params = (operation.parameters ?? []);
+    const bodyParam = params.find((p) => "name" in p && (p.in === "body" || p.in === "formData"));
+    if (!bodyParam)
+        return { kind: "none", propertyKeys: [] };
+    const schema = bodyParam.schema ? resolveSchemaRef(doc, bodyParam.schema) : undefined;
+    if (!schema)
+        return { kind: "raw", propertyKeys: [], contentType: "application/json" };
+    if (schema.type === "object" || schema.properties) {
+        const keys = Object.keys(schema.properties ?? {});
+        return { kind: "properties", propertyKeys: keys, contentType: "application/json" };
+    }
+    return { kind: "raw", propertyKeys: [], contentType: "application/json" };
+}
+// ---------------------------------------------------------------------------
+// Operation listing
+// ---------------------------------------------------------------------------
+/** Parses the OpenAPI spec for a provider and returns all operations with their metadata. */
+export function listOperations(providerName) {
+    const openApiPath = join(UTDK_ROOT, providerName, "openapi.json");
+    if (!existsSync(openApiPath))
+        return [];
+    let doc;
+    try {
+        doc = JSON.parse(readFileSync(openApiPath, "utf-8"));
+    }
+    catch {
+        return [];
+    }
+    const operations = [];
+    const usedPaths = new Set();
+    for (const [apiPath, pathItem] of Object.entries(doc.paths ?? {})) {
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (!HTTP_METHODS.has(method) || !operation)
+                continue;
+            const operationId = operation.operationId ??
+                `${method}${apiPath.replace(/[^a-zA-Z0-9]/g, "_")}`;
+            const basePath = operationIdToBasePath(operationId);
+            const accessPath = resolveAccessPath(basePath, usedPaths);
+            // Merge path-item-level params (shared across all methods) with operation params.
+            // Operation params override path-item params with the same name.
+            const pathItemParams = pathItem["parameters"] ?? [];
+            const rawParams = [
+                ...pathItemParams,
+                ...(operation.parameters ?? []),
+            ];
+            // Deduplicate: operation-level params override path-level params of the same name.
+            const seen = new Set();
+            const dedupedParams = [];
+            // Process operation params first (higher priority), then path params.
+            const operationParams = (operation.parameters ?? []);
+            for (const p of [...operationParams, ...pathItemParams]) {
+                const resolved = resolveParameter(doc, p);
+                if (!resolved)
+                    continue;
+                if (!seen.has(resolved.name)) {
+                    seen.add(resolved.name);
+                    dedupedParams.push(resolved);
+                }
+            }
+            const parameters = dedupedParams
+                .map((p) => resolveParameter(doc, p))
+                .filter((p) => p !== undefined && p.in !== "body" && p.in !== "formData")
+                .map((p) => ({
+                name: p.name,
+                in: p.in ?? "query",
+                required: p.required ?? false,
+                description: p.description,
+                type: p.schema?.type,
+            }));
+            void rawParams; // used above via pathItemParams/operationParams
+            const body = extractBodyInfo(doc, operation);
+            operations.push({
+                accessPath,
+                operationId,
+                method: method.toUpperCase(),
+                path: apiPath,
+                summary: operation.summary,
+                description: operation.description,
+                parameters,
+                body,
+            });
+        }
+    }
+    return operations;
+}
+/** Returns the OperationInfo for a specific access-path string like "users.getByUsername". */
+export function findOperation(providerName, operationPath) {
+    const ops = listOperations(providerName);
+    return ops.find((op) => op.accessPath.join(".") === operationPath ||
+        op.accessPath.join(".").toLowerCase() === operationPath.toLowerCase() ||
+        op.operationId === operationPath);
+}
+// ---------------------------------------------------------------------------
+// Tool metadata builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a ToolRuntimeMetadataMap from the provider's OpenAPI spec.
+ *
+ * The map keys equal the bare operationId (which is what OpenApiConverter
+ * uses as tool.name).  Providing this map to createClient() gives the
+ * request assembler correct path/query/header/body routing without
+ * relying on the provider's (often empty) hand-written metadata.ts.
+ */
+export function buildToolMetadata(ops) {
+    const map = {};
+    for (const op of ops) {
+        // tool.name from OpenApiConverter equals the bare operationId (no provider prefix).
+        const toolName = op.operationId;
+        const pathKeys = op.parameters
+            .filter((p) => p.in === "path")
+            .map((p) => p.name);
+        const queryKeys = op.parameters
+            .filter((p) => p.in === "query")
+            .map((p) => p.name);
+        const headerKeys = op.parameters
+            .filter((p) => p.in === "header")
+            .map((p) => p.name);
+        const meta = {
+            accessPath: op.accessPath,
+            bodyKind: op.body.kind,
+            bodyPropertyKeys: op.body.propertyKeys,
+            ...(op.body.allowsAdditionalProperties
+                ? { bodyAllowsAdditionalProperties: true }
+                : {}),
+            ...(op.body.contentType ? { contentType: op.body.contentType } : {}),
+            headerParameterKeys: headerKeys,
+            method: op.method,
+            routeTemplate: op.path,
+            pathConflictKeys: [],
+            pathParameterKeys: pathKeys,
+            queryConflictKeys: [],
+            queryParameterKeys: queryKeys,
+        };
+        map[toolName] = meta;
+    }
+    return map;
+}
+//# sourceMappingURL=providers.js.map

package/dist/providers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.js","sourceRoot":"","sources":["../src/providers.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@utdk/cli",
+  "version": "0.1.0-dev.646adf4",
+  "type": "module",
+  "description": "Agent-native CLI wrapper for all @utdk provider operations",
+  "keywords": [
+    "utdk",
+    "cli",
+    "agent",
+    "openapi"
+  ],
+  "license": "MIT",
+  "bin": {
+    "utdk": "./dist/bin.js"
+  },
+  "dependencies": {
+    "utdk": "0.1.0-dev.646adf4"
+  },
+  "devDependencies": {
+    "@types/node": "^25.5.0",
+    "typescript": "^5.7.3"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "clean": "rm -rf dist"
+  }
+}

package/src/auth.ts

@@ -0,0 +1,123 @@
+/**
+ * Auth resolution for @utdk/cli.
+ *
+ * Reads a provider's `utdk.auth` config from its package.json and resolves
+ * credentials from environment variables.  Resolution order:
+ *   1. UTDK_GATEWAY_URL + UTDK_GATEWAY_TOKEN  (gateway proxy mode)
+ *   2. api_key template env var  (e.g. GITHUB_TOKEN from "Bearer ${GITHUB_TOKEN}")
+ *   3. ${PROVIDER_NAME}_TOKEN   (generic bearer fallback, also covers oauth2 flows)
+ */
+
+import type { AuthConfig } from "./providers.js";
+
+/** Minimal interface matching AuthProvider in @utdk/common/auth */
+export type AuthProvider = {
+  authenticate(headers: Record<string, string>): Promise<void>;
+};
+
+function bearerAuth(token: string): AuthProvider {
+  return {
+    async authenticate(headers: Record<string, string>): Promise<void> {
+      headers["Authorization"] = `Bearer ${token}`;
+    },
+  };
+}
+
+function apiKeyAuth(headerName: string, value: string): AuthProvider {
+  return {
+    async authenticate(headers: Record<string, string>): Promise<void> {
+      headers[headerName] = value;
+    },
+  };
+}
+
+/** Extract the first `${VAR_NAME}` placeholder from a template string. */
+function extractEnvVar(template: string): string | undefined {
+  const m = /\$\{([^}]+)\}/.exec(template);
+  return m?.[1];
+}
+
+/** Substitute `${VAR_NAME}` placeholders in a template with their env values. */
+function resolveTemplate(template: string): string | undefined {
+  return template.replace(/\$\{([^}]+)\}/g, (_, varName: string) => {
+    const val = process.env[varName];
+    if (!val) throw new Error(`missing`);
+    return val;
+  });
+}
+
+/**
+ * Build an AuthProvider from the provider's auth configs and env vars.
+ * Returns undefined if no credentials are available (unauthenticated request).
+ */
+export function resolveAuth(
+  providerName: string,
+  authConfigs: AuthConfig[],
+): AuthProvider | undefined {
+  // 1. Gateway proxy mode
+  const gatewayUrl = process.env["UTDK_GATEWAY_URL"];
+  const gatewayToken = process.env["UTDK_GATEWAY_TOKEN"];
+  if (gatewayUrl && gatewayToken) {
+    return bearerAuth(gatewayToken);
+  }
+
+  // 2. Per-config resolution
+  for (const config of authConfigs) {
+    if (config.auth_type === "api_key") {
+      const template = config.api_key ?? "";
+      const varName = config.var_name ?? "Authorization";
+
+      try {
+        const resolved = resolveTemplate(template);
+        if (resolved) {
+          if (resolved.startsWith("Bearer ")) {
+            return bearerAuth(resolved.slice(7));
+          }
+          return apiKeyAuth(varName, resolved);
+        }
+      } catch {
+        // env var not set — try next config
+      }
+    } else if (config.auth_type === "oauth2") {
+      // CLI can't drive an interactive OAuth flow; accept a pre-issued token.
+      const clientIdEnv = config.client_id ? extractEnvVar(config.client_id) : undefined;
+      const prefix = clientIdEnv
+        ? clientIdEnv.replace(/_CLIENT_ID$/i, "")
+        : providerName.toUpperCase().replace(/-/g, "_");
+      const token = process.env[`${prefix}_TOKEN`] ?? process.env[`${prefix}_ACCESS_TOKEN`];
+      if (token) return bearerAuth(token);
+    }
+  }
+
+  // 3. Generic fallback: ${PROVIDER}_TOKEN
+  const upperProvider = providerName.toUpperCase().replace(/-/g, "_");
+  const fallback =
+    process.env[`${upperProvider}_TOKEN`] ??
+    process.env[`${upperProvider}_ACCESS_TOKEN`] ??
+    process.env[`${upperProvider}_API_KEY`];
+  if (fallback) return bearerAuth(fallback);
+
+  return undefined;
+}
+
+/**
+ * Returns the list of env var names a user should set for this provider.
+ * Used in the --help output.
+ */
+export function authEnvVars(providerName: string, authConfigs: AuthConfig[]): string[] {
+  const vars: string[] = [];
+  for (const config of authConfigs) {
+    if (config.auth_type === "api_key" && config.api_key) {
+      const v = extractEnvVar(config.api_key);
+      if (v) vars.push(v);
+    } else if (config.auth_type === "oauth2") {
+      const upper = providerName.toUpperCase().replace(/-/g, "_");
+      vars.push(`${upper}_TOKEN`);
+    }
+  }
+  // Also add the generic fallback so help is always useful even for unknown configs
+  const upper = providerName.toUpperCase().replace(/-/g, "_");
+  const generic = `${upper}_TOKEN`;
+  if (!vars.includes(generic)) vars.push(generic);
+  return [...new Set(vars)];
+}

package/src/bin.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * @utdk/cli entry point
+ *
+ * Thin shim that boots the CLI and maps the resolved exit code to
+ * process.exit().  All logic lives in cli.ts.
+ */
+import { runCli } from "./cli.js";
+
+const exitCode = await runCli(process.argv.slice(2));
+process.exit(exitCode);