@nkmc/gateway 0.1.0

package/src/onboard/apis-guru.ts

@@ -0,0 +1,64 @@
+import type { ManifestEntry } from "./types.js";
+
+const APIS_GURU_LIST = "https://api.apis.guru/v2/list.json";
+
+export interface ApisGuruOptions {
+  /** Max number of APIs to return */
+  limit?: number;
+  /** Filter by keyword in API title/description */
+  filter?: string;
+  /** Custom fetch function */
+  fetchFn?: typeof globalThis.fetch;
+}
+
+interface ApisGuruEntry {
+  preferred: string;
+  versions: Record<string, {
+    swaggerUrl?: string;
+    openapiVer?: string;
+    info?: { title?: string; description?: string; "x-logo"?: { url?: string } };
+  }>;
+}
+
+/**
+ * Discover APIs from the apis.guru public directory.
+ * Returns ManifestEntry[] ready for the onboard pipeline.
+ */
+export async function discoverFromApisGuru(options?: ApisGuruOptions): Promise<ManifestEntry[]> {
+  const fetchFn = options?.fetchFn ?? globalThis.fetch.bind(globalThis);
+  const limit = options?.limit ?? 100;
+  const filter = options?.filter?.toLowerCase();
+
+  const resp = await fetchFn(APIS_GURU_LIST);
+  if (!resp.ok) throw new Error(`apis.guru fetch failed: ${resp.status}`);
+  const catalog = (await resp.json()) as Record<string, ApisGuruEntry>;
+
+  const entries: ManifestEntry[] = [];
+
+  for (const [key, api] of Object.entries(catalog)) {
+    if (entries.length >= limit) break;
+
+    const version = api.versions[api.preferred];
+    if (!version?.swaggerUrl) continue;
+
+    const title = version.info?.title ?? key;
+    const desc = version.info?.description ?? "";
+
+    // Filter by keyword if provided
+    if (filter) {
+      const text = `${key} ${title} ${desc}`.toLowerCase();
+      if (!text.includes(filter)) continue;
+    }
+
+    // Extract domain from the key (format: "domain.com:version" or "domain.com")
+    const domain = key.split(":")[0];
+
+    entries.push({
+      domain,
+      specUrl: version.swaggerUrl,
+      tags: ["apis-guru", "public"],
+    });
+  }
+
+  return entries;
+}

package/src/onboard/index.ts

@@ -0,0 +1,4 @@
+export { OnboardPipeline, type PipelineOptions } from "./pipeline.js";
+export { discoverFromApisGuru, type ApisGuruOptions } from "./apis-guru.js";
+export { ALL_APIS, FREE_APIS, FREEMIUM_APIS, getSpecOnlyApis } from "./manifest.js";
+export type { ManifestEntry, ManifestAuth, OnboardResult, OnboardReport } from "./types.js";

package/src/onboard/manifest.ts

@@ -0,0 +1,362 @@
+import type { ManifestEntry, RpcManifestDef } from "./types.js";
+
+/**
+ * Curated manifest of major public APIs with verified OpenAPI spec URLs.
+ *
+ * Categories:
+ * - free: No auth needed, all endpoints public
+ * - freemium: Some endpoints public, auth optional
+ * - auth-required: Auth needed for all API calls
+ *
+ * All spec URLs verified reachable as of 2026-02.
+ */
+
+// ── Free / No-Auth APIs ──────────────────────────────────────────────
+
+export const FREE_APIS: ManifestEntry[] = [
+  {
+    domain: "petstore3.swagger.io",
+    specUrl: "https://petstore3.swagger.io/api/v3/openapi.json",
+    tags: ["demo", "free"],
+  },
+  {
+    domain: "api.weather.gov",
+    specUrl: "https://api.weather.gov/openapi.json",
+    tags: ["weather", "government", "free"],
+  },
+  {
+    domain: "en.wikipedia.org",
+    specUrl: "https://en.wikipedia.org/api/rest_v1/?spec",
+    tags: ["knowledge", "encyclopedia", "free"],
+  },
+];
+
+// ── Freemium APIs (public read, auth optional) ──────────────────────
+
+export const FREEMIUM_APIS: ManifestEntry[] = [
+  {
+    domain: "api.github.com",
+    specUrl:
+      "https://raw.githubusercontent.com/github/rest-api-description/main/descriptions/api.github.com/api.github.com.2022-11-28.json",
+    auth: { type: "bearer", token: "${GITHUB_TOKEN}" },
+    tags: ["developer-tools", "vcs", "freemium"],
+  },
+  {
+    domain: "huggingface.co",
+    specUrl: "https://huggingface.co/.well-known/openapi.json",
+    auth: { type: "bearer", token: "${HF_TOKEN}" },
+    tags: ["ai", "ml", "models", "freemium"],
+  },
+];
+
+// ── Auth-Required APIs (Developer Tools) ─────────────────────────────
+
+export const DEVELOPER_TOOL_APIS: ManifestEntry[] = [
+  {
+    domain: "gitlab.com",
+    specUrl:
+      "https://gitlab.com/gitlab-org/gitlab/-/raw/master/doc/api/openapi/openapi.yaml",
+    auth: { type: "bearer", token: "${GITLAB_TOKEN}" },
+    tags: ["developer-tools", "vcs"],
+  },
+  {
+    domain: "api.vercel.com",
+    specUrl: "https://openapi.vercel.sh",
+    auth: { type: "bearer", token: "${VERCEL_TOKEN}" },
+    tags: ["developer-tools", "hosting"],
+  },
+  {
+    domain: "sentry.io",
+    specUrl:
+      "https://raw.githubusercontent.com/getsentry/sentry-api-schema/main/openapi-derefed.json",
+    auth: { type: "bearer", token: "${SENTRY_AUTH_TOKEN}" },
+    tags: ["developer-tools", "monitoring"],
+  },
+  {
+    domain: "api.pagerduty.com",
+    specUrl:
+      "https://raw.githubusercontent.com/PagerDuty/api-schema/main/reference/REST/openapiv3.json",
+    auth: { type: "bearer", token: "${PAGERDUTY_TOKEN}" },
+    tags: ["developer-tools", "incident-management"],
+  },
+];
+
+// ── AI / ML APIs ─────────────────────────────────────────────────────
+
+export const AI_APIS: ManifestEntry[] = [
+  {
+    domain: "api.mistral.ai",
+    specUrl:
+      "https://raw.githubusercontent.com/mistralai/platform-docs-public/main/openapi.yaml",
+    auth: { type: "bearer", token: "${MISTRAL_API_KEY}" },
+    tags: ["ai", "llm"],
+    disabled: true, // upstream YAML spec has unescaped quotes in example data
+  },
+  {
+    domain: "api.openai.com",
+    specUrl:
+      "https://raw.githubusercontent.com/openai/openai-openapi/manual_spec/openapi.yaml",
+    auth: { type: "bearer", token: "${OPENAI_API_KEY}" },
+    tags: ["ai", "llm"],
+  },
+  {
+    domain: "openrouter.ai",
+    specUrl: "https://openrouter.ai/openapi.json",
+    auth: { type: "bearer", token: "${OPENROUTER_API_KEY}" },
+    tags: ["ai", "llm", "gateway"],
+  },
+];
+
+// ── Cloud / Infrastructure APIs ──────────────────────────────────────
+
+export const CLOUD_APIS: ManifestEntry[] = [
+  {
+    domain: "api.cloudflare.com",
+    specUrl:
+      "https://raw.githubusercontent.com/cloudflare/api-schemas/main/openapi.yaml",
+    auth: { type: "bearer", token: "${CLOUDFLARE_API_TOKEN}" },
+    tags: ["cloud", "cdn", "dns"],
+  },
+  {
+    domain: "api.digitalocean.com",
+    specUrl:
+      "https://raw.githubusercontent.com/digitalocean/openapi/main/specification/DigitalOcean-public.v2.yaml",
+    auth: { type: "bearer", token: "${DIGITALOCEAN_TOKEN}" },
+    tags: ["cloud", "infrastructure"],
+  },
+  {
+    domain: "fly.io",
+    specUrl: "https://docs.machines.dev/spec/openapi3.json",
+    auth: { type: "bearer", token: "${FLY_API_TOKEN}" },
+    tags: ["cloud", "deployment"],
+  },
+  {
+    domain: "api.render.com",
+    specUrl:
+      "https://api-docs.render.com/v1.0/openapi/render-public-api-1.json",
+    auth: { type: "bearer", token: "${RENDER_API_KEY}" },
+    tags: ["cloud", "deployment"],
+  },
+];
+
+// ── Productivity / Project Management ────────────────────────────────
+
+export const PRODUCTIVITY_APIS: ManifestEntry[] = [
+  {
+    domain: "api.notion.com",
+    specUrl:
+      "https://raw.githubusercontent.com/makenotion/notion-mcp-server/main/scripts/notion-openapi.json",
+    auth: { type: "bearer", token: "${NOTION_API_KEY}" },
+    tags: ["productivity", "database"],
+  },
+  {
+    domain: "app.asana.com",
+    specUrl:
+      "https://raw.githubusercontent.com/Asana/openapi/master/defs/asana_oas.yaml",
+    auth: { type: "bearer", token: "${ASANA_ACCESS_TOKEN}" },
+    tags: ["productivity", "project-management"],
+  },
+  {
+    domain: "jira.atlassian.com",
+    specUrl:
+      "https://developer.atlassian.com/cloud/jira/platform/swagger-v3.v3.json",
+    auth: { type: "bearer", token: "${ATLASSIAN_API_TOKEN}" },
+    tags: ["productivity", "project-management"],
+  },
+  {
+    domain: "api.spotify.com",
+    specUrl:
+      "https://raw.githubusercontent.com/sonallux/spotify-web-api/main/fixed-spotify-open-api.yml",
+    auth: { type: "bearer", token: "${SPOTIFY_ACCESS_TOKEN}" },
+    tags: ["media", "music"],
+  },
+  {
+    domain: "api.getpostman.com",
+    specUrl:
+      "https://api.apis.guru/v2/specs/getpostman.com/1.20.0/openapi.json",
+    auth: { type: "api-key", header: "X-Api-Key", key: "${POSTMAN_API_KEY}" },
+    tags: ["developer-tools", "api-testing"],
+  },
+];
+
+// ── DevOps / CI/CD ──────────────────────────────────────────────────
+
+export const DEVOPS_APIS: ManifestEntry[] = [
+  {
+    domain: "circleci.com",
+    specUrl: "https://circleci.com/api/v2/openapi.json",
+    auth: { type: "bearer", token: "${CIRCLECI_TOKEN}" },
+    tags: ["devops", "ci-cd"],
+  },
+  {
+    domain: "api.datadoghq.com",
+    specUrl:
+      "https://raw.githubusercontent.com/DataDog/datadog-api-client-python/master/.generator/schemas/v2/openapi.yaml",
+    auth: { type: "api-key", header: "DD-API-KEY", key: "${DATADOG_API_KEY}" },
+    tags: ["devops", "monitoring"],
+  },
+];
+
+// ── Database / BaaS ─────────────────────────────────────────────────
+
+export const DATABASE_APIS: ManifestEntry[] = [
+  {
+    domain: "api.supabase.com",
+    specUrl:
+      "https://raw.githubusercontent.com/supabase/supabase/master/apps/docs/spec/api_v1_openapi.json",
+    auth: { type: "bearer", token: "${SUPABASE_ACCESS_TOKEN}" },
+    tags: ["database", "baas"],
+  },
+  {
+    domain: "api.turso.tech",
+    specUrl:
+      "https://raw.githubusercontent.com/tursodatabase/turso-docs/main/api-reference/openapi.json",
+    auth: { type: "bearer", token: "${TURSO_API_TOKEN}" },
+    tags: ["database", "edge"],
+  },
+  {
+    domain: "console.neon.tech",
+    specUrl:
+      "https://raw.githubusercontent.com/neondatabase/neon-api-python/main/v2.json",
+    auth: { type: "bearer", token: "${NEON_API_KEY}" },
+    tags: ["database", "serverless-postgres"],
+  },
+];
+
+// ── Commerce / Payments ──────────────────────────────────────────────
+
+export const COMMERCE_APIS: ManifestEntry[] = [
+  {
+    domain: "api.stripe.com",
+    specUrl:
+      "https://raw.githubusercontent.com/stripe/openapi/master/openapi/spec3.json",
+    auth: { type: "bearer", token: "${STRIPE_SECRET_KEY}" },
+    tags: ["commerce", "payments"],
+  },
+];
+
+// ── Communication APIs ───────────────────────────────────────────────
+
+export const COMMUNICATION_APIS: ManifestEntry[] = [
+  {
+    domain: "slack.com",
+    specUrl:
+      "https://raw.githubusercontent.com/slackapi/slack-api-specs/master/web-api/slack_web_openapi_v2.json",
+    auth: { type: "bearer", token: "${SLACK_BOT_TOKEN}" },
+    tags: ["communication", "messaging"],
+  },
+  {
+    domain: "discord.com",
+    specUrl:
+      "https://raw.githubusercontent.com/discord/discord-api-spec/main/specs/openapi.json",
+    auth: { type: "bearer", token: "${DISCORD_BOT_TOKEN}", prefix: "Bot" },
+    tags: ["communication", "messaging"],
+  },
+  {
+    domain: "api.twilio.com",
+    specUrl:
+      "https://raw.githubusercontent.com/twilio/twilio-oai/main/spec/json/twilio_api_v2010.json",
+    auth: { type: "basic", token: "${TWILIO_ACCOUNT_SID}:${TWILIO_AUTH_TOKEN}" },
+    tags: ["communication", "sms", "voice"],
+  },
+  {
+    domain: "api.resend.com",
+    specUrl:
+      "https://raw.githubusercontent.com/resendlabs/resend-openapi/main/resend.yaml",
+    auth: { type: "bearer", token: "${RESEND_API_KEY}" },
+    tags: ["communication", "email"],
+  },
+];
+
+// ── JSON-RPC APIs ───────────────────────────────────────────────────
+
+/** Standard EVM methods shared across all Ethereum-compatible RPC providers */
+const EVM_METHODS: RpcManifestDef["methods"] = [
+  { rpcMethod: "eth_blockNumber", description: "Returns the latest block number", resource: "blocks", fsOp: "list" },
+  { rpcMethod: "eth_getBlockByNumber", description: "Returns block by number", resource: "blocks", fsOp: "read" },
+  { rpcMethod: "eth_getBalance", description: "Returns account balance in wei", resource: "balances", fsOp: "read" },
+  { rpcMethod: "eth_getTransactionByHash", description: "Returns transaction by hash", resource: "transactions", fsOp: "read" },
+  { rpcMethod: "eth_getTransactionReceipt", description: "Returns transaction receipt", resource: "receipts", fsOp: "read" },
+  { rpcMethod: "eth_call", description: "Executes a call without creating a transaction", resource: "calls", fsOp: "read" },
+  { rpcMethod: "eth_estimateGas", description: "Estimates gas needed for a transaction", resource: "gas", fsOp: "read" },
+  { rpcMethod: "eth_gasPrice", description: "Returns current gas price in wei" },
+  { rpcMethod: "eth_chainId", description: "Returns the chain ID" },
+  { rpcMethod: "eth_getCode", description: "Returns contract bytecode at address", resource: "code", fsOp: "read" },
+  { rpcMethod: "eth_getLogs", description: "Returns logs matching a filter", resource: "logs", fsOp: "list" },
+  { rpcMethod: "eth_getTransactionCount", description: "Returns the number of transactions sent from an address", resource: "nonces", fsOp: "read" },
+  { rpcMethod: "net_version", description: "Returns the network ID" },
+];
+
+export const RPC_APIS: ManifestEntry[] = [
+  // ── Free / Public RPC Providers ──────────────────────────────────
+  {
+    domain: "rpc.ankr.com",
+    rpcDef: { url: "https://rpc.ankr.com/eth", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "ethereum", "free"],
+  },
+  {
+    domain: "cloudflare-eth.com",
+    rpcDef: { url: "https://cloudflare-eth.com", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "ethereum", "free"],
+  },
+  {
+    domain: "ethereum-rpc.publicnode.com",
+    rpcDef: { url: "https://ethereum-rpc.publicnode.com", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "ethereum", "free"],
+  },
+
+  // ── Auth-Required RPC Providers ──────────────────────────────────
+  {
+    domain: "eth-mainnet.g.alchemy.com",
+    rpcDef: { url: "https://eth-mainnet.g.alchemy.com/v2/${ALCHEMY_API_KEY}", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "ethereum"],
+  },
+  {
+    domain: "mainnet.infura.io",
+    rpcDef: { url: "https://mainnet.infura.io/v3/${INFURA_API_KEY}", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "ethereum"],
+  },
+
+  // ── L2 / Alt Chains (Free) ───────────────────────────────────────
+  {
+    domain: "arb1.arbitrum.io",
+    rpcDef: { url: "https://arb1.arbitrum.io/rpc", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "arbitrum", "l2", "free"],
+  },
+  {
+    domain: "mainnet.optimism.io",
+    rpcDef: { url: "https://mainnet.optimism.io", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "optimism", "l2", "free"],
+  },
+  {
+    domain: "mainnet.base.org",
+    rpcDef: { url: "https://mainnet.base.org", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "base", "l2", "free"],
+  },
+  {
+    domain: "polygon-rpc.com",
+    rpcDef: { url: "https://polygon-rpc.com", convention: "evm", methods: EVM_METHODS },
+    tags: ["blockchain", "polygon", "free"],
+  },
+];
+
+// ── All APIs combined ────────────────────────────────────────────────
+
+export const ALL_APIS: ManifestEntry[] = [
+  ...FREE_APIS,
+  ...FREEMIUM_APIS,
+  ...DEVELOPER_TOOL_APIS,
+  ...AI_APIS,
+  ...CLOUD_APIS,
+  ...PRODUCTIVITY_APIS,
+  ...DEVOPS_APIS,
+  ...DATABASE_APIS,
+  ...COMMERCE_APIS,
+  ...COMMUNICATION_APIS,
+  ...RPC_APIS,
+];
+
+/** Get APIs that can be onboarded without any credentials (spec is public) */
+export function getSpecOnlyApis(): ManifestEntry[] {
+  return ALL_APIS.map((e) => ({ ...e, auth: undefined }));
+}

package/src/onboard/pipeline.ts

@@ -0,0 +1,214 @@
+import type { HttpAuth } from "@nkmc/agent-fs";
+import { AgentFs } from "@nkmc/agent-fs";
+import type { RegistryStore } from "../registry/types.js";
+import type { CredentialVault } from "../credential/types.js";
+import { compileOpenApiSpec, fetchAndCompile } from "../registry/openapi-compiler.js";
+import { parseSkillMd } from "../registry/skill-parser.js";
+import { compileRpcDef } from "../registry/rpc-compiler.js";
+import { createRegistryResolver } from "../registry/resolver.js";
+import type { ManifestEntry, ManifestAuth, OnboardResult, OnboardReport } from "./types.js";
+
+export interface PipelineOptions {
+  store: RegistryStore;
+  vault?: CredentialVault;
+  /** Run smoke tests after registration (default true) */
+  smokeTest?: boolean;
+  /** Concurrency limit for parallel onboarding (default 5) */
+  concurrency?: number;
+  /** Custom fetch function */
+  fetchFn?: typeof globalThis.fetch;
+  /** Progress callback */
+  onProgress?: (result: OnboardResult, index: number, total: number) => void;
+}
+
+export class OnboardPipeline {
+  private store: RegistryStore;
+  private vault?: CredentialVault;
+  private smokeTest: boolean;
+  private concurrency: number;
+  private fetchFn: typeof globalThis.fetch;
+  private onProgress?: PipelineOptions["onProgress"];
+
+  constructor(options: PipelineOptions) {
+    this.store = options.store;
+    this.vault = options.vault;
+    this.smokeTest = options.smokeTest !== false;
+    this.concurrency = options.concurrency ?? 5;
+    this.fetchFn = options.fetchFn ?? globalThis.fetch.bind(globalThis);
+    this.onProgress = options.onProgress;
+  }
+
+  /** Onboard a single service */
+  async onboardOne(entry: ManifestEntry): Promise<OnboardResult> {
+    const start = Date.now();
+    const base: Omit<OnboardResult, "status" | "durationMs"> = {
+      domain: entry.domain,
+      source: "none",
+      endpoints: 0,
+      resources: 0,
+      hasCredentials: false,
+    };
+
+    if (entry.disabled) {
+      return { ...base, status: "skipped", durationMs: Date.now() - start };
+    }
+
+    try {
+      // Step 1: Compile/parse the service definition
+      if (entry.specUrl) {
+        const result = await fetchAndCompile(entry.specUrl, { domain: entry.domain }, this.fetchFn);
+        await this.store.put(entry.domain, result.record);
+        base.source = "openapi";
+        base.endpoints = result.record.endpoints.length;
+        base.resources = result.resources.length;
+      } else if (entry.skillMdUrl) {
+        const resp = await this.fetchFn(entry.skillMdUrl);
+        if (!resp.ok) throw new Error(`Failed to fetch skill.md: ${resp.status}`);
+        const md = await resp.text();
+        const record = parseSkillMd(entry.domain, md);
+        await this.store.put(entry.domain, record);
+        base.source = "wellknown";
+        base.endpoints = record.endpoints.length;
+      } else if (entry.skillMd) {
+        const record = parseSkillMd(entry.domain, entry.skillMd);
+        await this.store.put(entry.domain, record);
+        base.source = "skillmd";
+        base.endpoints = record.endpoints.length;
+      } else if (entry.rpcDef) {
+        const { record } = compileRpcDef(entry.domain, entry.rpcDef);
+        await this.store.put(entry.domain, record);
+        base.source = "jsonrpc";
+        base.endpoints = record.endpoints.length;
+        base.resources = record.source?.rpc?.resources.length ?? 0;
+      } else {
+        return { ...base, status: "skipped", error: "No spec, skillMdUrl, or skillMd provided", durationMs: Date.now() - start };
+      }
+
+      // Step 2: Store credentials if provided
+      if (entry.auth && this.vault) {
+        const auth = resolveAuth(entry.auth);
+        await this.vault.putPool(entry.domain, auth);
+        base.hasCredentials = true;
+      }
+
+      // Step 3: Smoke test
+      if (this.smokeTest) {
+        base.smokeTest = await this.runSmokeTest(entry.domain, base.hasCredentials);
+      }
+
+      return { ...base, status: "ok", durationMs: Date.now() - start };
+    } catch (err) {
+      return {
+        ...base,
+        status: "failed",
+        error: err instanceof Error ? err.message : String(err),
+        durationMs: Date.now() - start,
+      };
+    }
+  }
+
+  /** Onboard many services with controlled concurrency */
+  async onboardMany(entries: ManifestEntry[]): Promise<OnboardReport> {
+    const start = Date.now();
+    const results: OnboardResult[] = [];
+    let index = 0;
+
+    // Process in batches
+    for (let i = 0; i < entries.length; i += this.concurrency) {
+      const batch = entries.slice(i, i + this.concurrency);
+      const batchResults = await Promise.all(
+        batch.map(async (entry) => {
+          const result = await this.onboardOne(entry);
+          const idx = index++;
+          this.onProgress?.(result, idx, entries.length);
+          return result;
+        }),
+      );
+      results.push(...batchResults);
+    }
+
+    return {
+      total: results.length,
+      ok: results.filter((r) => r.status === "ok").length,
+      failed: results.filter((r) => r.status === "failed").length,
+      skipped: results.filter((r) => r.status === "skipped").length,
+      results,
+      durationMs: Date.now() - start,
+    };
+  }
+
+  private async runSmokeTest(domain: string, hasCredentials: boolean): Promise<OnboardResult["smokeTest"]> {
+    const resolverOpts = this.vault
+      ? { store: this.store, vault: this.vault, wrapVirtualFiles: false }
+      : { store: this.store, wrapVirtualFiles: false };
+
+    const { onMiss, listDomains } = createRegistryResolver(resolverOpts);
+    const fs = new AgentFs({ mounts: [], onMiss, listDomains });
+
+    const test: NonNullable<OnboardResult["smokeTest"]> = { ls: false, cat: false };
+
+    // Test ls
+    const lsResult = await fs.execute(`ls /${domain}/`);
+    test.ls = lsResult.ok === true;
+
+    // Test cat — only if ls succeeded and we found something to read
+    if (test.ls && lsResult.ok) {
+      const entries = lsResult.data as string[];
+      // Find a readable resource or endpoint
+      const resource = entries.find((e) => e.endsWith("/") && !e.startsWith("_"));
+      if (resource) {
+        // Try to list the resource — this makes a real HTTP call
+        const catResult = await fs.execute(`ls /${domain}/${resource}`);
+        test.cat = catResult.ok === true;
+        test.catEndpoint = `ls /${domain}/${resource}`;
+      } else if (entries.includes("_api/")) {
+        // Just verify _api listing works
+        const apiResult = await fs.execute(`ls /${domain}/_api/`);
+        test.cat = apiResult.ok === true;
+        test.catEndpoint = `ls /${domain}/_api/`;
+      }
+    }
+
+    return test;
+  }
+}
+
+/** Resolve ${ENV_VAR} references in auth values and return HttpAuth */
+function resolveAuth(auth: ManifestAuth): HttpAuth {
+  const resolve = (val?: string): string | undefined => {
+    if (!val) return undefined;
+    const match = val.match(/^\$\{(\w+)\}$/);
+    if (match) {
+      const envVal = process.env[match[1]];
+      if (!envVal) throw new Error(`Environment variable ${match[1]} is not set`);
+      return envVal;
+    }
+    return val;
+  };
+
+  if (auth.type === "bearer") {
+    const token = resolve(auth.token);
+    if (!token) throw new Error("Bearer auth requires token");
+    return { type: "bearer", token, ...(auth.prefix ? { prefix: auth.prefix } : {}) };
+  }
+  if (auth.type === "api-key") {
+    const header = resolve(auth.header);
+    const key = resolve(auth.key);
+    if (!header || !key) throw new Error("API key auth requires header and key");
+    return { type: "api-key", header, key };
+  }
+  if (auth.type === "basic") {
+    const username = resolve(auth.username);
+    const password = resolve(auth.password);
+    if (!username || !password) throw new Error("Basic auth requires username and password");
+    return { type: "basic", username, password };
+  }
+  if (auth.type === "oauth2") {
+    const tokenUrl = resolve(auth.tokenUrl);
+    const clientId = resolve(auth.clientId);
+    const clientSecret = resolve(auth.clientSecret);
+    if (!tokenUrl || !clientId || !clientSecret) throw new Error("OAuth2 auth requires tokenUrl, clientId, and clientSecret");
+    return { type: "oauth2", tokenUrl, clientId, clientSecret, ...(auth.scope ? { scope: auth.scope } : {}) };
+  }
+  throw new Error(`Unknown auth type: ${auth.type}`);
+}