zuora-cli 0.0.1-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Li, Jianfeng
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# Zuora CLI
+
+Command-line interface for Zuora.
+
+`zuora-cli` discovers the capabilities visible to your configured credentials and exposes them as domain-oriented commands.
+
+Status: alpha, version `0.0.1-alpha.0`. Command coverage and generated command names can change while the CLI is still in alpha.
+
+## Requirements
+
+Node.js `18` or newer.
+
+## Install
+
+For the current alpha, install from this repository:
+
+```bash
+npm install
+npm run build
+npm link
+```
+
+This exposes the `zuora-cli` command on your PATH.
+
+## Configure
+
+Set the Zuora base URL and choose one authentication method.
+
+Client credentials:
+
+```bash
+export ZUORA_BASE_URL="https://rest.apisandbox.zuora.com"
+export ZUORA_CLIENT_ID="..."
+export ZUORA_CLIENT_SECRET="..."
+```
+
+Bearer token:
+
+```bash
+export ZUORA_BASE_URL="https://rest.apisandbox.zuora.com"
+export ZUORA_ACCESS_TOKEN="..."
+```
+
+The `Bearer ` prefix is optional. You can also pass a token as a global option:
+
+```bash
+zuora-cli --access-token "$ZUORA_ACCESS_TOKEN" list
+```
+
+Optional environment variables:
+
+| Variable | Purpose |
+| --- | --- |
+| `ZUORA_BEARER_TOKEN` | Alias for `ZUORA_ACCESS_TOKEN`. |
+| `ZUORA_ENTITY_IDS` | Sets the Zuora entity scope header. |
+| `ZUORA_ORG_IDS` | Sets the Zuora org scope header. |
+| `ZUORA_VERSION` | Sets the Zuora API version header. |
+| `ZUORA_CLI_TIMEOUT_MS` | Request timeout in milliseconds. Default: `120000`. |
+| `ZUORA_CLI_SCHEMA_CACHE_TTL_MS` | Command metadata cache TTL in milliseconds. Default: `86400000`. |
+| `ZUORA_CLI_CACHE_DIR` | Cache directory. Default: `~/.zuora-cli/cache`. |
+| `ZUORA_CLI_DISABLE_TOKEN_CACHE` | Set to `true` to disable token cache reads and writes. |
+
+Run `zuora-cli --help` to see the same environment variable list in the CLI.
+
+## Quick Start
+
+List commands visible to your credentials:
+
+```bash
+zuora-cli list
+```
+
+Print command metadata as JSON:
+
+```bash
+zuora-cli list --json
+```
+
+Refresh command metadata:
+
+```bash
+zuora-cli refresh
+```
+
+Clear cached credentials and command metadata:
+
+```bash
+zuora-cli cache clear
+```
+
+Run a generated command:
+
+```bash
+zuora-cli product create \
+  --name aaa \
+  --effective-start-date 2026-01-01 \
+  --effective-end-date 2099-12-31
+```
+
+Query an object:
+
+```bash
+zuora-cli object query --object-type account --page-size 1
+```
+
+## Command Shape
+
+Generated commands follow an AWS-style shape:
+
+```text
+zuora-cli <domain> <operation> [options]
+```
+
+Examples:
+
+| Command | Purpose |
+| --- | --- |
+| `zuora-cli account summary ...` | Retrieve account summary data. |
+| `zuora-cli object query --object-type account` | Query Zuora object records. |
+| `zuora-cli product create ...` | Create a product. |
+| `zuora-cli commerce-product create ...` | Create a commerce product. |
+
+The naming layer is dynamic:
+
+* Repeated entity names are removed from operations. For example, commerce product creation appears as `commerce-product create`, not `commerce-product create-product`.
+* Multi-operation capabilities are split into subcommands. For example, order management operations become commands such as `order get` and `order activate`.
+
+## Input Flags
+
+Primitive fields use normal options:
+
+```bash
+zuora-cli object query --object-type account --page-size 1
+```
+
+Object and array fields use JSON options:
+
+```bash
+zuora-cli some-domain some-operation --payload-json '{"name":"example"}'
+```
+
+Use command help to inspect available options:
+
+```bash
+zuora-cli <domain> <operation> --help
+```
+
+## Output
+
+Command output defaults to the response returned by Zuora.
+
+`zuora-cli list --json` is available for scripts that need command metadata. Generated business commands do not require a separate `--json` flag.
+
+## Caching
+
+`zuora-cli` caches command metadata and generated access tokens locally so each command does not need to rediscover capabilities or request a new token.
+
+The cache is stored under `~/.zuora-cli/cache` by default. Set `ZUORA_CLI_CACHE_DIR` to override it.
+
+Access tokens are cached as local plaintext credential material. Cache directories and files are restricted to the current OS user where supported.
+
+* Access tokens are reused until shortly before expiry.
+* Changing the client secret creates a new token cache entry.
+* Command metadata is cached for 24 hours by default.
+* Run `zuora-cli refresh` to force command metadata refresh.
+* Run `zuora-cli cache clear` to remove cached tokens and command metadata.
+* Set `ZUORA_CLI_DISABLE_TOKEN_CACHE=true` to disable token cache reads and writes. Command metadata caching remains enabled.
+
+## Exit Codes
+
+Commands exit with a nonzero status for parser errors, transport errors, and business validation failures returned by Zuora.
+
+## Troubleshooting
+
+If a command is missing, run:
+
+```bash
+zuora-cli refresh
+zuora-cli list
+```
+
+If authentication or command discovery behaves unexpectedly, clear local cache:
+
+```bash
+zuora-cli cache clear
+```
+
+If you are using a bearer token and also have client credential variables set, the explicit bearer token takes precedence.

package/dist/index.js

@@ -0,0 +1,690 @@
+#!/usr/bin/env node
+
+// src/index.ts
+import { Command as Command2 } from "commander";
+
+// src/cache.ts
+import { createHash } from "crypto";
+import { chmod, mkdir, readFile, rm, writeFile } from "fs/promises";
+import { homedir } from "os";
+import { dirname, join } from "path";
+function cacheRoot() {
+  return process.env.ZUORA_CLI_CACHE_DIR || join(homedir(), ".zuora-cli", "cache");
+}
+function digest(value) {
+  return createHash("sha256").update(JSON.stringify(value)).digest("hex").slice(0, 24);
+}
+function secretFingerprint(secret) {
+  return secret ? digest({ clientSecret: secret }) : void 0;
+}
+function bearerFingerprint(accessToken) {
+  return accessToken ? digest({ accessToken }) : void 0;
+}
+function isTokenCacheDisabled() {
+  return process.env.ZUORA_CLI_DISABLE_TOKEN_CACHE?.toLowerCase() === "true";
+}
+function tokenCachePath(config) {
+  return join(cacheRoot(), "tokens", `${digest({
+    restBaseUrl: config.restBaseUrl,
+    clientId: config.clientId,
+    clientSecretFingerprint: secretFingerprint(config.clientSecret)
+  })}.json`);
+}
+function toolsCachePath(config) {
+  return join(cacheRoot(), "tools", `${digest({
+    mcpUrl: config.mcpUrl,
+    auth: config.accessToken ? `bearer:${bearerFingerprint(config.accessToken)}` : `client:${config.clientId}`,
+    entityIds: config.entityIds,
+    orgIds: config.orgIds,
+    zuoraVersion: config.zuoraVersion
+  })}.json`);
+}
+async function readJson(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return void 0;
+    return void 0;
+  }
+}
+async function writeJson(path, value) {
+  const dir = dirname(path);
+  await mkdir(dir, { recursive: true, mode: 448 });
+  await chmod(dir, 448);
+  await writeFile(path, `${JSON.stringify(value, null, 2)}
+`, { mode: 384 });
+  await chmod(path, 384);
+}
+async function readCachedToken(config) {
+  if (isTokenCacheDisabled()) return void 0;
+  const cached = await readJson(tokenCachePath(config));
+  if (!cached || cached.expiresAt <= Date.now()) return void 0;
+  return cached.accessToken;
+}
+async function writeCachedToken(config, accessToken, expiresInSeconds) {
+  if (isTokenCacheDisabled()) return;
+  const safeExpiresInSeconds = Number.isFinite(expiresInSeconds) ? expiresInSeconds : 3600;
+  const skewSeconds = Math.min(300, Math.floor(safeExpiresInSeconds / 2));
+  const expiresAt = Date.now() + Math.max(1, safeExpiresInSeconds - skewSeconds) * 1e3;
+  await writeJson(tokenCachePath(config), { accessToken, expiresAt });
+}
+async function readCachedTools(config) {
+  const cached = await readJson(toolsCachePath(config));
+  if (!cached || cached.expiresAt <= Date.now()) return void 0;
+  return cached.tools;
+}
+async function writeCachedTools(config, tools) {
+  await writeJson(toolsCachePath(config), {
+    tools,
+    expiresAt: Date.now() + config.schemaCacheTtlMs
+  });
+}
+async function clearCache() {
+  const root = cacheRoot();
+  await Promise.all([
+    rm(join(root, "tokens"), { recursive: true, force: true }),
+    rm(join(root, "tools"), { recursive: true, force: true })
+  ]);
+}
+
+// src/config.ts
+function resolveZuoraUrls(rawUrl) {
+  const trimmed = rawUrl.trim().replace(/\/+$/, "");
+  if (!trimmed) {
+    throw new Error("ZUORA_BASE_URL is required.");
+  }
+  const parsed = new URL(trimmed);
+  const isMcpEndpoint = parsed.pathname.replace(/\/+$/, "") === "/mcp";
+  let restBaseUrl;
+  if (!isMcpEndpoint) {
+    restBaseUrl = trimmed;
+  } else if (parsed.hostname.startsWith("rest.") || parsed.hostname.startsWith("rest-")) {
+    restBaseUrl = `${parsed.protocol}//${parsed.host}`;
+  } else {
+    const stagingMatch = parsed.hostname.match(/^staging(\d+)\.zuora\.com$/);
+    const restHost = stagingMatch ? `rest-staging${stagingMatch[1]}.zuora.com` : `rest.${parsed.hostname}`;
+    restBaseUrl = `${parsed.protocol}//${restHost}`;
+  }
+  return {
+    restBaseUrl,
+    mcpUrl: `${restBaseUrl}/mcp`
+  };
+}
+function readOptionalEnv(name) {
+  const value = process.env[name]?.trim();
+  return value || void 0;
+}
+function normalizeAccessToken(rawToken) {
+  const token = rawToken?.trim();
+  if (!token) return void 0;
+  return token.replace(/^Bearer\s+/i, "").trim();
+}
+function loadConfig(overrides = {}) {
+  const baseUrl = process.env.ZUORA_BASE_URL || process.env.BASE_URL;
+  if (!baseUrl) {
+    throw new Error("ZUORA_BASE_URL is required.");
+  }
+  const accessToken = normalizeAccessToken(
+    overrides.accessToken || readOptionalEnv("ZUORA_ACCESS_TOKEN") || readOptionalEnv("ZUORA_BEARER_TOKEN")
+  );
+  const clientId = readOptionalEnv("ZUORA_CLIENT_ID");
+  const clientSecret = readOptionalEnv("ZUORA_CLIENT_SECRET");
+  if (!accessToken && (!clientId || !clientSecret)) {
+    throw new Error("Provide ZUORA_ACCESS_TOKEN or both ZUORA_CLIENT_ID and ZUORA_CLIENT_SECRET.");
+  }
+  const { restBaseUrl, mcpUrl } = resolveZuoraUrls(baseUrl);
+  const timeoutMs = Number(process.env.ZUORA_CLI_TIMEOUT_MS || process.env.REMOTE_MCP_TIMEOUT_MS || 12e4);
+  if (!Number.isFinite(timeoutMs) || timeoutMs <= 0) {
+    throw new Error("ZUORA_CLI_TIMEOUT_MS must be a positive number.");
+  }
+  const schemaCacheTtlMs = Number(process.env.ZUORA_CLI_SCHEMA_CACHE_TTL_MS || 24 * 60 * 60 * 1e3);
+  if (!Number.isFinite(schemaCacheTtlMs) || schemaCacheTtlMs <= 0) {
+    throw new Error("ZUORA_CLI_SCHEMA_CACHE_TTL_MS must be a positive number.");
+  }
+  return {
+    restBaseUrl,
+    mcpUrl,
+    clientId,
+    clientSecret,
+    accessToken,
+    timeoutMs,
+    schemaCacheTtlMs,
+    entityIds: readOptionalEnv("ZUORA_ENTITY_IDS"),
+    orgIds: readOptionalEnv("ZUORA_ORG_IDS"),
+    zuoraVersion: readOptionalEnv("ZUORA_VERSION")
+  };
+}
+
+// src/mcpClient.ts
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+
+// src/http.ts
+function createTimedFetch(timeoutMs) {
+  return async (input, init = {}) => {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), timeoutMs);
+    const abortFromCaller = () => controller.abort();
+    init.signal?.addEventListener("abort", abortFromCaller, { once: true });
+    try {
+      return await fetch(input, {
+        ...init,
+        signal: controller.signal
+      });
+    } finally {
+      clearTimeout(timeout);
+      init.signal?.removeEventListener("abort", abortFromCaller);
+    }
+  };
+}
+
+// src/auth.ts
+function oneIdTokenUrl(restBaseUrl) {
+  const host = new URL(restBaseUrl).hostname.toLowerCase();
+  const isStaging = host.includes("staging") || host.includes(".stg.") || host.includes("-stg");
+  return isStaging ? "https://one.stg.na.zuora.com/oauth2/token" : "https://one.zuora.com/oauth2/token";
+}
+async function requestToken(url, config) {
+  if (!config.clientId || !config.clientSecret) {
+    throw new Error("ZUORA_CLIENT_ID and ZUORA_CLIENT_SECRET are required to generate an access token.");
+  }
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: config.clientId,
+    client_secret: config.clientSecret
+  });
+  const response = await createTimedFetch(config.timeoutMs)(url, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/x-www-form-urlencoded"
+    },
+    body
+  });
+  if (!response.ok) {
+    const responseBody = await response.text().catch(() => "");
+    throw new Error(`${response.status} ${response.statusText}${responseBody ? `: ${responseBody}` : ""}`);
+  }
+  const payload = await response.json();
+  if (!payload.access_token) {
+    throw new Error("OAuth response did not include access_token.");
+  }
+  return {
+    accessToken: payload.access_token,
+    expiresIn: payload.expires_in || 3600
+  };
+}
+async function getAccessToken(config) {
+  if (config.accessToken) return config.accessToken;
+  const cachedToken = await readCachedToken(config);
+  if (cachedToken) return cachedToken;
+  const endpoints = [
+    `${config.restBaseUrl}/oauth/token`,
+    oneIdTokenUrl(config.restBaseUrl)
+  ];
+  let lastError;
+  for (const endpoint of endpoints) {
+    try {
+      const token = await requestToken(endpoint, config);
+      await writeCachedToken(config, token.accessToken, token.expiresIn);
+      return token.accessToken;
+    } catch (error) {
+      lastError = error;
+    }
+  }
+  const message = lastError instanceof Error ? lastError.message : String(lastError);
+  throw new Error(`Authentication failed: ${message}`);
+}
+
+// src/version.ts
+var VERSION = "0.0.1-alpha.0";
+
+// src/mcpClient.ts
+function requestHeaders(config, token) {
+  return {
+    Authorization: `Bearer ${token}`,
+    "User-Agent": `zuora-cli/${VERSION} (Node/${process.version})`,
+    ...config.entityIds ? { "Zuora-Entity-Ids": config.entityIds } : {},
+    ...config.orgIds ? { "Zuora-Org-Ids": config.orgIds } : {},
+    ...config.zuoraVersion ? { "Zuora-Version": config.zuoraVersion } : {}
+  };
+}
+async function withClient(config, callback) {
+  const token = await getAccessToken(config);
+  const transport = new StreamableHTTPClientTransport(new URL(config.mcpUrl), {
+    requestInit: {
+      headers: requestHeaders(config, token)
+    },
+    fetch: createTimedFetch(config.timeoutMs)
+  });
+  const client = new Client({ name: "zuora-cli", version: VERSION });
+  try {
+    await client.connect(transport, { timeout: config.timeoutMs });
+    return await callback(client);
+  } finally {
+    await client.close().catch(() => void 0);
+  }
+}
+async function fetchTools(config) {
+  return withClient(config, async (client) => {
+    const result = await client.listTools(void 0, { timeout: config.timeoutMs });
+    return result.tools;
+  });
+}
+async function listTools(config, options = {}) {
+  if (!options.refresh) {
+    const cachedTools = await readCachedTools(config);
+    if (cachedTools) return cachedTools;
+  }
+  const tools = await fetchTools(config);
+  await writeCachedTools(config, tools);
+  return tools;
+}
+async function callTool(config, name, args) {
+  return withClient(config, async (client) => {
+    return client.callTool(
+      { name, arguments: args },
+      void 0,
+      { timeout: config.timeoutMs }
+    );
+  });
+}
+
+// src/schemaCli.ts
+import { Option } from "commander";
+var LEADING_VERBS = /* @__PURE__ */ new Set([
+  "activate",
+  "add",
+  "apply",
+  "ask",
+  "cancel",
+  "close",
+  "collect",
+  "create",
+  "deactivate",
+  "delete",
+  "download",
+  "email",
+  "export",
+  "explain",
+  "generate",
+  "get",
+  "import",
+  "list",
+  "manage",
+  "match",
+  "pending",
+  "post",
+  "preview",
+  "query",
+  "read",
+  "regenerate",
+  "renew",
+  "reopen",
+  "reverse",
+  "run",
+  "search",
+  "skip",
+  "submit",
+  "sync",
+  "transfer",
+  "unapply",
+  "update",
+  "upload",
+  "validate",
+  "write"
+]);
+function kebab(value) {
+  return value.replace(/([a-z\d])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").replace(/[^a-zA-Z\d-]/g, "-").replace(/-+/g, "-").replace(/^-|-$/g, "").toLowerCase();
+}
+function tokens(value) {
+  return kebab(value).split("-").filter(Boolean);
+}
+function camelFromKebab(value) {
+  return value.replace(/-([a-z\d])/g, (_, char) => char.toUpperCase());
+}
+function singularToken(token) {
+  if (token.endsWith("ies") && token.length > 3) return `${token.slice(0, -3)}y`;
+  if (token.endsWith("s") && !token.endsWith("ss")) return token.slice(0, -1);
+  return token;
+}
+function singularPhrase(parts) {
+  if (!parts.length) return "tool";
+  return [...parts.slice(0, -1), singularToken(parts.at(-1))].join("-");
+}
+function oneLineDescription(description) {
+  if (!description) return "";
+  return description.replace(/\s+/g, " ").trim().slice(0, 180);
+}
+function schemaType(schema) {
+  if (Array.isArray(schema.type)) {
+    return schema.type.find((type) => type !== "null");
+  }
+  return schema.type;
+}
+function optionValueType(schema) {
+  const type = schemaType(schema);
+  if (type === "boolean") return "boolean";
+  if (type === "integer" || type === "number") return "number";
+  if (type === "object" || type === "array" || schema.properties || schema.items) return "json";
+  return "string";
+}
+function optionPlans(tool, injectedArgNames = /* @__PURE__ */ new Set()) {
+  const properties = tool.inputSchema?.properties ?? {};
+  const required = new Set(tool.inputSchema?.required ?? []);
+  const usedFlagNames = /* @__PURE__ */ new Set();
+  return Object.entries(properties).filter(([sourceName]) => !injectedArgNames.has(sourceName)).map(([sourceName, schema], index) => {
+    const valueType = optionValueType(schema);
+    const baseFlagName = kebab(sourceName);
+    let flagName = valueType === "json" && !baseFlagName.endsWith("-json") ? `${baseFlagName}-json` : baseFlagName;
+    if (usedFlagNames.has(flagName)) {
+      const fallbackFlagName = `${baseFlagName}-value`;
+      flagName = usedFlagNames.has(fallbackFlagName) ? `${baseFlagName}-${index + 1}` : fallbackFlagName;
+    }
+    usedFlagNames.add(flagName);
+    const flags = valueType === "boolean" ? `--${flagName}` : `--${flagName} <value>`;
+    const choices = schema.enum?.filter((value) => value !== null && value !== void 0).map(String);
+    return {
+      sourceName,
+      flagName,
+      commanderKey: camelFromKebab(flagName),
+      flags,
+      description: schema.description || (valueType === "json" ? `JSON value for ${sourceName}.` : sourceName),
+      required: required.has(sourceName),
+      valueType,
+      choices: choices?.length ? choices : void 0
+    };
+  });
+}
+function parseOptionValue(plan, value) {
+  if (plan.valueType === "boolean") return Boolean(value);
+  if (plan.valueType === "number") {
+    const numberValue = Number(value);
+    if (!Number.isFinite(numberValue)) {
+      throw new Error(`--${plan.flagName} must be a number.`);
+    }
+    return numberValue;
+  }
+  if (plan.valueType === "json") {
+    try {
+      return typeof value === "string" ? JSON.parse(value) : value;
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      throw new Error(`--${plan.flagName} must be valid JSON: ${message}`);
+    }
+  }
+  return value;
+}
+function argumentsFromOptions(tool, options, injectedArgs = {}) {
+  const injectedArgNames = new Set(Object.keys(injectedArgs));
+  const args = { ...injectedArgs };
+  for (const plan of optionPlans(tool, injectedArgNames)) {
+    const value = options[plan.commanderKey];
+    if (value !== void 0) {
+      args[plan.sourceName] = parseOptionValue(plan, value);
+    }
+  }
+  return args;
+}
+function stripLeadingVerb(parts) {
+  const [first, ...rest] = parts;
+  return first && LEADING_VERBS.has(first) ? { verb: first, rest } : { rest: parts };
+}
+function routeFromToolName(toolName) {
+  const parsed = stripLeadingVerb(tokens(toolName));
+  const verb = parsed.verb || "run";
+  const rest = parsed.rest.length ? parsed.rest : tokens(toolName);
+  if (verb === "get" && rest.length > 1) {
+    return {
+      group: singularPhrase([rest[0]]),
+      operation: rest.slice(1).join("-"),
+      toolName,
+      description: ""
+    };
+  }
+  if (verb === "query") {
+    return {
+      group: singularPhrase(rest),
+      operation: "query",
+      toolName,
+      description: ""
+    };
+  }
+  return {
+    group: singularPhrase(rest),
+    operation: verb,
+    toolName,
+    description: ""
+  };
+}
+function removeMatchingEntityFromOperation(operationParts, entityParts) {
+  const singularEntity = entityParts.map(singularToken);
+  const normalizedOperation = operationParts.map(singularToken);
+  for (let i = 0; i <= normalizedOperation.length - singularEntity.length; i += 1) {
+    const matches = singularEntity.every((part, offset) => normalizedOperation[i + offset] === part);
+    if (matches) {
+      return [
+        ...operationParts.slice(0, i),
+        ...operationParts.slice(i + singularEntity.length)
+      ];
+    }
+  }
+  for (let length = Math.min(singularEntity.length, normalizedOperation.length - 1); length > 0; length -= 1) {
+    const entitySuffix = singularEntity.slice(-length);
+    for (let i = 1; i <= normalizedOperation.length - length; i += 1) {
+      const matches = entitySuffix.every((part, offset) => normalizedOperation[i + offset] === part);
+      if (matches) {
+        return [
+          ...operationParts.slice(0, i),
+          ...operationParts.slice(i + length)
+        ];
+      }
+    }
+  }
+  return operationParts;
+}
+function routeFromOperationEnum(tool, operationValue) {
+  const base = routeFromToolName(tool.name);
+  const groupParts = tokens(base.group);
+  const rawOperationParts = tokens(operationValue);
+  const cleanedParts = removeMatchingEntityFromOperation(rawOperationParts, groupParts);
+  const operation = cleanedParts.length ? cleanedParts.join("-") : base.operation;
+  return {
+    group: base.group,
+    operation,
+    toolName: tool.name,
+    description: oneLineDescription(tool.description),
+    injectedArgs: { operation: operationValue }
+  };
+}
+function operationEnumValues(tool) {
+  const operationSchema = tool.inputSchema?.properties?.operation;
+  if (!operationSchema?.enum?.length) return [];
+  return operationSchema.enum.filter((value) => typeof value === "string" && value.length > 0);
+}
+function routesForTool(tool) {
+  const enumValues = operationEnumValues(tool);
+  if (enumValues.length) {
+    return enumValues.map((operationValue) => routeFromOperationEnum(tool, operationValue));
+  }
+  const route = routeFromToolName(tool.name);
+  return [{
+    ...route,
+    description: oneLineDescription(tool.description)
+  }];
+}
+function routeRows(tools) {
+  return tools.flatMap(routesForTool).map((route) => ({
+    command: `${route.group} ${route.operation}`,
+    description: route.description
+  })).sort((a, b) => a.command.localeCompare(b.command));
+}
+function commandDescription(route) {
+  return route.description || `Run ${route.group} ${route.operation}`;
+}
+function registerToolCommands(program, tools, runner) {
+  const groups = /* @__PURE__ */ new Map();
+  const registeredPaths = /* @__PURE__ */ new Set();
+  for (const tool of tools) {
+    for (const route of routesForTool(tool)) {
+      let groupCommand = groups.get(route.group);
+      if (!groupCommand) {
+        groupCommand = program.command(route.group).description(`${route.group} commands`);
+        groups.set(route.group, groupCommand);
+      }
+      const path = `${route.group} ${route.operation}`;
+      const operationName = registeredPaths.has(path) ? `${route.operation}-${kebab(route.toolName)}` : route.operation;
+      registeredPaths.add(`${route.group} ${operationName}`);
+      const injectedArgs = route.injectedArgs ?? {};
+      const injectedArgNames = new Set(Object.keys(injectedArgs));
+      const command = groupCommand.command(operationName).description(commandDescription(route));
+      for (const plan of optionPlans(tool, injectedArgNames)) {
+        const option = new Option(plan.flags, plan.description);
+        if (plan.required) option.makeOptionMandatory();
+        if (plan.choices) option.choices(plan.choices);
+        command.addOption(option);
+      }
+      command.action(async (options) => {
+        const args = argumentsFromOptions(tool, options, injectedArgs);
+        await runner(tool.name, args);
+      });
+    }
+  }
+}
+function shouldLoadDynamicCommands(argv, staticCommands) {
+  const command = argv.find((arg) => !arg.startsWith("-"));
+  return !!command && command !== "help" && !staticCommands.has(command);
+}
+
+// src/output.ts
+function isObject(value) {
+  return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function textContent(result) {
+  const content = result.content;
+  if (!Array.isArray(content) || content.length === 0) return void 0;
+  const textParts = content.filter((item) => item.type === "text" && typeof item.text === "string").map((item) => item.text);
+  return textParts.length ? textParts.join("\n") : void 0;
+}
+function parseJsonText(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return void 0;
+  }
+}
+function isFailurePayload(value) {
+  if (!isObject(value)) return false;
+  if (value.success === false) return true;
+  if (value.error === true) return true;
+  if (value.type === "http_error" || value.type === "network_error") return true;
+  if (typeof value.status === "number" && value.status >= 400) return true;
+  const nested = [value.data, value.result, value.response, value.body];
+  return nested.some((nestedValue) => isFailurePayload(nestedValue));
+}
+function getToolResultExitCode(result) {
+  if (result.isError) return 1;
+  if (isFailurePayload(result.structuredContent)) return 1;
+  const text = textContent(result);
+  const parsedText = text ? parseJsonText(text) : void 0;
+  if (isFailurePayload(parsedText)) return 1;
+  return 0;
+}
+function printToolResult(result) {
+  const text = textContent(result);
+  if (text) {
+    console.log(text);
+    return getToolResultExitCode(result);
+  }
+  console.log(JSON.stringify(result, null, 2));
+  return getToolResultExitCode(result);
+}
+function printRows(rows) {
+  console.table(rows);
+}
+function printRowsJson(rows) {
+  console.log(JSON.stringify(rows, null, 2));
+}
+
+// src/index.ts
+var STATIC_COMMANDS = /* @__PURE__ */ new Set(["list", "refresh", "cache"]);
+var ENVIRONMENT_HELP = `
+Environment variables:
+  ZUORA_BASE_URL                    Zuora REST base URL, for example https://rest.apisandbox.zuora.com
+  ZUORA_CLIENT_ID                   Client credentials auth: OAuth client id
+  ZUORA_CLIENT_SECRET               Client credentials auth: OAuth client secret
+  ZUORA_ACCESS_TOKEN                Bearer token auth; also accepted as --access-token
+  ZUORA_BEARER_TOKEN                Alias for ZUORA_ACCESS_TOKEN
+  ZUORA_ENTITY_IDS                  Optional Zuora entity scope header
+  ZUORA_ORG_IDS                     Optional Zuora org scope header
+  ZUORA_VERSION                     Optional Zuora API version header
+  ZUORA_CLI_TIMEOUT_MS              Request timeout in milliseconds
+  ZUORA_CLI_SCHEMA_CACHE_TTL_MS     Command metadata cache TTL in milliseconds
+  ZUORA_CLI_CACHE_DIR               Cache directory; defaults to ~/.zuora-cli/cache
+  ZUORA_CLI_DISABLE_TOKEN_CACHE     Set to true to disable token cache reads and writes
+
+Authentication requires either ZUORA_ACCESS_TOKEN/ZUORA_BEARER_TOKEN or both
+ZUORA_CLIENT_ID and ZUORA_CLIENT_SECRET.`;
+function readAccessTokenOption(argv) {
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--access-token") {
+      return argv[i + 1];
+    }
+    if (arg.startsWith("--access-token=")) {
+      return arg.slice("--access-token=".length);
+    }
+  }
+  return void 0;
+}
+function createProgram(argv) {
+  const program = new Command2();
+  program.name("zuora-cli").description("Command-line interface for Zuora").version(VERSION).option("--access-token <token>", "Bearer access token; can also use ZUORA_ACCESS_TOKEN").showHelpAfterError().addHelpText("after", `${ENVIRONMENT_HELP}
+
+Commands are generated from the capabilities visible to your configured credentials.
+Use "zuora-cli list" to list available commands.`);
+  program.command("list").description("List available commands").option("--json", "Print available commands as JSON").action(async (options) => {
+    const config = loadConfig({ accessToken: readAccessTokenOption(argv) });
+    const tools = await listTools(config);
+    const rows = routeRows(tools);
+    if (options.json) {
+      printRowsJson(rows);
+    } else {
+      printRows(rows);
+    }
+  });
+  program.command("refresh").description("Refresh available command metadata").action(async () => {
+    const config = loadConfig({ accessToken: readAccessTokenOption(argv) });
+    const tools = await listTools(config, { refresh: true });
+    console.log(`Refreshed ${routeRows(tools).length} commands.`);
+  });
+  const cache = program.command("cache").description("Manage local cache");
+  cache.command("clear").description("Clear cached credentials and command metadata").action(async () => {
+    await clearCache();
+    console.log("Cache cleared.");
+  });
+  return program;
+}
+async function main(argv = process.argv) {
+  const program = createProgram(argv);
+  if (shouldLoadDynamicCommands(argv.slice(2), STATIC_COMMANDS)) {
+    const config = loadConfig({ accessToken: readAccessTokenOption(argv) });
+    const tools = await listTools(config);
+    registerToolCommands(program, tools, async (toolName, args) => {
+      const result = await callTool(config, toolName, args);
+      const exitCode = printToolResult(result);
+      if (exitCode !== 0) {
+        process.exitCode = exitCode;
+      }
+    });
+  }
+  await program.parseAsync(argv);
+}
+main().catch((error) => {
+  const message = error instanceof Error ? error.message : String(error);
+  console.error(`Error: ${message}`);
+  process.exit(1);
+});
+export {
+  main
+};
+//# sourceMappingURL=index.js.map

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "zuora-cli",
+  "version": "0.0.1-alpha.0",
+  "description": "Command-line interface for Zuora",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "zuora-cli": "dist/index.js"
+  },
+  "files": [
+    "dist/index.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "postbuild": "chmod +x dist/index.js",
+    "check": "tsc --noEmit",
+    "test": "vitest run",
+    "validate": "npm run check && npm test && npm run build"
+  },
+  "keywords": [
+    "zuora",
+    "cli"
+  ],
+  "license": "MIT",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.0",
+    "commander": "^14.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsup": "^8.4.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4"
+  }
+}