@limecloud/cli 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "@limecloud/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.0",
+  "description": "Lime Cloud CLI for public identity and delegated platform APIs",
+  "type": "module",
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "bin": {
+    "limecloud-cli": "./bin/limecloud-cli.mjs",
+    "limecloud": "./bin/limecloud-cli.mjs"
+  },
+  "files": [
+    "bin",
+    "src",
+    "dist/*.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "node scripts/build.mjs",
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/limecloud/cloud.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,362 @@
+import { setTimeout } from "node:timers/promises";
+import { publicContract, resolveSchema } from "./contract.mjs";
+import { commandOperations, inspectSchema } from "./commands.mjs";
+import { CredentialStore, PrivateJSONStore, SettingsStore, credentialsPath, settingsPath, validateSettings } from "./storage.mjs";
+import { CLIError, issuerOrigin, pollDevice, protocolRequest, startDevice, tokenRecord, verificationURI } from "./protocol.mjs";
+import { parametersFor, scopeList, validateParameters } from "./input.mjs";
+import { errorEnvelope, outputOptions, success } from "./output.mjs";
+import { flagName, matchHTTP, prepareManagement } from "./management.mjs";
+
+export { validateParameters } from "./input.mjs";
+
+const help = `limecloud-cli — Lime Cloud CLI (@limecloud/cli)
+
+Usage:
+  limecloud-cli <command> [resource] [method] [flags]
+  limecloud-cli identity +login | +whoami
+  limecloud-cli identity token exchange --data <json>
+  limecloud-cli api <METHOD> <contract-path> [--params <json>] [--data <json>]
+  limecloud-cli schema [service.resource.method | service resource method]
+
+Identity:
+  identity    Public OAuth / OpenID Connect operations and +shortcuts
+
+CLI management:
+  config      init | show | set: local public-client configuration
+  auth        login | status | whoami | refresh | logout | scopes | check
+  whoami      Show the local effective identity and token state
+  doctor      Check local configuration and contract (--offline; no network)
+  docs        Print a documentation URL
+
+API tools:
+  api         Call a contract HTTP path; list/schema/call also accept operationId
+  schema      Inspect public methods, parameters, responses and authentication
+
+API flags:
+  --params JSON       Query JSON; supports @file or - for stdin
+  --data JSON         OAuth form input as JSON; supports @file or - for stdin
+  --dry-run           Print a redacted request without executing or changing state
+  --format FORMAT     json (default), ndjson, table or csv
+  --fields PATHS      Comma-separated data field paths
+  --json              Shorthand for --format json
+  --param name=value  Repeat a non-sensitive protocol parameter
+  --param-env name=ENV Read a sensitive protocol parameter from an environment variable
+  --header name=value Set a contract-declared HTTP header
+  --file PATH         Binary body for image/png methods; - reads stdin
+  --show-secrets      Explicitly include API response credentials in stdout
+
+Connection flags:
+  --issuer ORIGIN     Auth origin (HTTPS; HTTP only on loopback)
+  --api-origin ORIGIN Explicit business API origin, bound to the saved login
+  --client-id ID      Already registered sign-in client ID
+  --auth-client-id ID Override the OAuth client context for a business API call
+
+Run limecloud-cli <command> --help or schema identity before calling a method.
+`;
+
+const booleanFlags = new Set(["help", "version", "json", "show-secrets", "local-only", "dry-run", "no-wait", "resume", "offline"]);
+const valueFlags = new Set(["issuer", "api-origin", "client-id", "auth-client-id", "scope", "installation-id", "space-id", "locale", "param", "param-env", "params", "data", "format", "fields", "header", "file"]);
+const fail = (message) => { throw new CLIError("invalid_arguments", message); };
+
+function fieldNames(contract, operation) {
+  const schema = resolveSchema(contract, operation.requestBody?.content["application/x-www-form-urlencoded"]?.schema ?? operation.requestBody?.content["application/json"]?.schema);
+  const variants = schema?.oneOf?.map((item) => resolveSchema(contract, item)) ?? (schema ? [schema] : []);
+  return [...new Set([...variants.flatMap((item) => Object.keys(item.properties ?? {})), ...(operation.parameters ?? []).map((parameter) => parameter.name)])];
+}
+
+export function parseArguments(args, protocolFields = []) {
+  const positionals = [], flags = new Map();
+  const dynamic = new Set(protocolFields.map(flagName));
+  for (let index = 0; index < args.length; index++) {
+    const item = args[index] === "-h" ? "--help" : args[index] === "-v" ? "--version" : args[index];
+    if (!item.startsWith("--")) { positionals.push(item); continue; }
+    const [name, ...rest] = item.slice(2).split("=");
+    if (!booleanFlags.has(name) && !valueFlags.has(name) && !dynamic.has(name)) fail(`Unknown option --${name}`);
+    let value = true;
+    if (booleanFlags.has(name) && rest.length) fail(`--${name} does not take a value`);
+    if (!booleanFlags.has(name)) {
+      value = rest.length ? rest.join("=") : args[++index];
+      if (typeof value !== "string" || !value || value.startsWith("--")) fail(`--${name} needs a value`);
+    }
+    if (flags.has(name) && !["param", "param-env", "audience", "header"].includes(name)) fail(`Duplicate option --${name}`);
+    flags.set(name, [...(flags.get(name) ?? []), value]);
+  }
+  return { positionals, flags, get: (name) => flags.get(name)?.[0] };
+}
+
+function allowedFlags(parsed, names) {
+  for (const key of parsed.flags.keys()) if (!["help", "json", ...names].includes(key)) fail(`Option --${key} is not supported by this command`);
+}
+
+function commandHelp(command, contract) {
+  const serviceMethods = commandOperations(contract).filter((operation) => operation.command.startsWith(`${command}.`));
+  if (serviceMethods.length) return `${command === "identity" ? "Identity shortcuts:\n  identity +login [--scope SCOPES] [--no-wait | --resume]\n  identity +whoami\n\n" : ""}Typed API commands:\n${serviceMethods.map((operation) => `  ${operation.command.replaceAll(".", " ")}  (${operation.method} ${operation.path})`).join("\n")}\n\nUse schema ${command}.<resource>.<method> for parameters. --dry-run executes nothing.\n`;
+  if (command === "auth") return `Usage: auth <login|status|whoami|refresh|logout|scopes|check> [flags]\n\nlogin --client-id ID [--scope "openid profile"] [--installation-id ID --space-id ID]\n      --no-wait: return a verification URL and save private pending state\n      --resume: complete the saved authorization without exposing its device code\nstatus: local state; whoami: remote UserInfo; refresh: rotate stored credentials\nlogout [--local-only]: revoke, then forget; --local-only forgets without revocation\nscopes: read supported OIDC scopes and report locally granted scopes\ncheck --scope SCOPES: check unexpired local granted scopes (no network)\n\nAuth commands use an already registered public client. --dry-run previews login, refresh, logout or scopes without execution.\n`;
+  if (command === "config") return `Usage:\n  config init --issuer ORIGIN --client-id ID [--api-origin ORIGIN] [--scope SCOPES]\n  config show\n  config set <issuer|api_origin|client_id|scope> <value>\n\nConfiguration stores public client settings only. Business API origin must be explicit; changing it requires a new login binding.\n`;
+  if (command === "schema") return "Usage: schema [identity | identity.resource | identity.resource.method | identity resource method]\nReturns public inputSchema, outputSchema and _meta derived from the OpenAPI contract. Risk: read.\n";
+  if (command === "api") return `${help.slice(help.indexOf("API flags:"), help.indexOf("Connection flags:"))}\nUsage: api GET <path> --params JSON\n       api POST <path> --data JSON\n       api list [query] [--locale en|zh-CN]\n       api schema <operationId>\n       api call <operationId> [flags]\n\nOnly exact public contract paths are callable. Arbitrary URLs and management BFF paths are rejected.\n`;
+  return `${help}\nAvailable services: ${[...new Set(commandOperations(contract).map((operation) => operation.command.split(".")[0]))].join(", ")}\n`;
+}
+
+async function contextFor(parsed, env, settings, saved, management = false) {
+  const issuer = issuerOrigin(parsed.get("issuer") ?? env.LIMECLOUD_ISSUER ?? settings.issuer ?? saved?.issuer ?? "https://auth.limeai.run");
+  const apiValue = parsed.get("api-origin") ?? env.LIMECLOUD_API_ORIGIN ?? settings.api_origin;
+  const apiOrigin = apiValue ? issuerOrigin(apiValue) : undefined;
+  const clientID = parsed.get("auth-client-id") ?? (management ? undefined : parsed.get("client-id")) ?? env.LIMECLOUD_CLIENT_ID ?? settings.client_id ?? (saved?.issuer === issuer ? saved.client_id : undefined);
+  const matching = saved && saved.issuer === issuer && saved.client_id === clientID ? saved : null;
+  return { issuer, apiOrigin, clientID, saved: matching, accessToken: env.LIMECLOUD_ACCESS_TOKEN || matching?.access_token };
+}
+
+function usableAccess(context, env, now) {
+  if (!context.accessToken) throw new CLIError("login_required", "Run auth login or set LIMECLOUD_ACCESS_TOKEN");
+  if (!env.LIMECLOUD_ACCESS_TOKEN && Date.parse(context.saved.expires_at) <= now()) throw new CLIError("token_expired", "Run auth refresh or start auth login again");
+  return context.accessToken;
+}
+
+function localIdentity(context, env, now) {
+  const external = Boolean(env.LIMECLOUD_ACCESS_TOKEN);
+  return { identity: context.accessToken ? "user" : "public", authenticated: Boolean(context.accessToken) && (external || Date.parse(context.saved.expires_at) > now()),
+    source: external ? "environment" : context.saved ? "credentials" : null, issuer: context.issuer, api_origin: context.apiOrigin ?? null, client_id: context.clientID ?? null,
+    bound_api_origin: external ? null : context.saved?.api_origin ?? null,
+    expires_at: external ? null : context.saved?.expires_at ?? null, expired: external ? null : context.saved ? Date.parse(context.saved.expires_at) <= now() : null,
+    refresh_requires_login: context.saved?.refresh_pending === true, scope: external ? null : context.saved?.scope ?? null };
+}
+
+function preview(operation, context, form, authentication) {
+  const body = {};
+  for (const key of new Set(form.keys())) body[key] = form.getAll(key).length > 1 ? form.getAll(key) : form.get(key);
+  return { dry_run: true, command: operation.command, operationId: operation.operationId, request: { method: operation.method,
+    url: `${context.issuer}${operation.path}`, headers: { Accept: "application/json", ...(authentication === "user" ? { Authorization: "Bearer [REDACTED]" } :
+      authentication === "client" ? { Authorization: "Basic [REDACTED]" } : {}), ...(operation.method === "POST" ? { "Content-Type": "application/x-www-form-urlencoded" } : {}) },
+    ...(operation.method === "GET" ? { params: body } : { data: body }) } };
+}
+
+export async function execute(args, { env = process.env, io = process, store = new CredentialStore(credentialsPath(env)),
+  settingsStore = new SettingsStore(settingsPath(env)), pendingStore = new PrivateJSONStore(`${store.path ?? credentialsPath(env)}.pending.json`),
+  request: requestImpl = protocolRequest, wait = setTimeout, now = Date.now, signal, readInput, readBinary, contract: suppliedContract } = {}) {
+  const contract = suppliedContract ?? await publicContract();
+  const catalogue = commandOperations(contract);
+  const parsed = parseArguments(args, catalogue.flatMap((operation) => fieldNames(contract, operation)));
+  let [command, action, target, ...extra] = parsed.positionals;
+  const get = parsed.get;
+  const request = (input) => requestImpl({ ...input, signal });
+  const pause = (ms) => wait(ms, undefined, signal ? { signal } : undefined);
+  const output = (value, options = {}) => success(io, value, { ...outputOptions(parsed), ...options });
+  if (get("help") || !args.length) { io.stdout.write(commandHelp(command, contract)); return; }
+  if (get("version")) { io.stdout.write(`${contract.info.version}\n`); return; }
+  // 在任何读取凭据或发请求前验证输出选项。
+  outputOptions(parsed);
+  if (command === "identity" && ["+login", "+whoami"].includes(action) && !target) { command = "auth"; action = action.slice(1); }
+  if (command === "schema") {
+    allowedFlags(parsed, []);
+    output(inspectSchema(contract, parsed.positionals.slice(1))); return;
+  }
+  if (command === "docs") {
+    allowedFlags(parsed, []);
+    if (target || extra.length || action && !/^[a-z0-9-]{1,80}$/.test(action)) fail("Use docs [article-slug]");
+    output({ url: `https://open.limeai.run/docs${action ? `/${action}` : ""}` }); return;
+  }
+  if (command === "config") {
+    allowedFlags(parsed, action === "init" ? ["issuer", "api-origin", "client-id", "scope"] : []);
+    if (action === "show" && !target) { output({ settings: await settingsStore.read(), path: settingsStore.path ?? null }, { identity: "local" }); return; }
+    if (action === "init" && !target) {
+      await settingsStore.withLock(async () => {
+        const old = await settingsStore.read() ?? {};
+        const apiOrigin = get("api-origin") ?? env.LIMECLOUD_API_ORIGIN ?? old.api_origin;
+        const settings = validateSettings({ issuer: get("issuer") ?? env.LIMECLOUD_ISSUER ?? old.issuer ?? "https://auth.limeai.run",
+          ...(apiOrigin ? { api_origin: apiOrigin } : {}), client_id: get("client-id") ?? env.LIMECLOUD_CLIENT_ID ?? old.client_id,
+          scope: get("scope") ?? old.scope ?? "openid profile email offline_access" });
+        if (!settings.client_id) fail("Provide the already registered public client with --client-id");
+        await settingsStore.write(settings);
+        output({ settings, path: settingsStore.path ?? null }, { identity: "local" });
+      }); return;
+    }
+    if (action === "set" && target && extra.length === 1) {
+      await settingsStore.withLock(async () => {
+        const settings = validateSettings({ ...await settingsStore.read(), [target]: extra[0] });
+        await settingsStore.write(settings); output({ settings }, { identity: "local" });
+      }); return;
+    }
+    fail("Use config init, config show or config set <issuer|api_origin|client_id|scope> <value>");
+  }
+  if (extra.length) fail("Too many arguments; use --help");
+  let operation = catalogue.find((item) => item.command === [command, action, target].join("."));
+  if (command === "api" && action === "call") operation = catalogue.find((item) => item.operationId === target);
+  const raw = command === "api" ? matchHTTP(catalogue, action, target) : null;
+  if (raw) operation = raw.operation;
+  const settings = await settingsStore.read() ?? {};
+  const management = operation?.["x-lime-cli-origin"] === "api";
+  const context = await contextFor(parsed, env, settings, await store.read(), management);
+  if (["whoami", "doctor"].includes(command)) {
+    allowedFlags(parsed, ["issuer", "api-origin", "client-id", "auth-client-id", ...(command === "doctor" ? ["offline"] : [])]);
+    if (action) fail(`Use ${command} without positional arguments`);
+    const state = localIdentity(context, env, now);
+    output(command === "whoami" ? state : { offline: true, checks: { public_contract: true, version: contract.info.version,
+      issuer: context.issuer, configured_client: Boolean(context.clientID), credentials_readable: true, token_unexpired: state.authenticated },
+      configuration: { settings: settingsStore.path ?? null, credentials: store.path ?? null } }, { identity: "local" }); return;
+  }
+  if (command === "api" && action === "list") {
+    allowedFlags(parsed, ["locale", "format", "fields"]);
+    const locale = get("locale") ?? "en";
+    if (!["en", "zh-CN"].includes(locale)) fail("--locale must be en or zh-CN");
+    const needle = target?.toLocaleLowerCase(locale) ?? "";
+    output(catalogue.filter((operation) => `${operation.operationId} ${operation.path} ${operation.summary} ${operation["x-lime-summary-zh-CN"]}`.toLocaleLowerCase(locale).includes(needle))
+      .map((operation) => ({ command: operation.command, operationId: operation.operationId, method: operation.method, path: operation.path,
+        summary: locale === "zh-CN" ? operation["x-lime-summary-zh-CN"] ?? operation.summary : operation.summary }))); return;
+  }
+  if (command === "api" && action === "schema") {
+    allowedFlags(parsed, []);
+    if (!catalogue.some((operation) => operation.operationId === target)) fail("Choose a public operationId from api list");
+    output(inspectSchema(contract, [target])); return;
+  }
+  if (operation) {
+    const fields = fieldNames(contract, operation);
+    allowedFlags(parsed, ["issuer", "api-origin", ...(management ? [] : ["client-id"]), "auth-client-id", "param", "param-env", "params", "data", ...(management ? ["header", "file"] : []), "show-secrets", "dry-run", "format", "fields", ...fields.map(flagName)]);
+    if (management) {
+      const input = await prepareManagement(contract, operation, parsed, env, readInput, raw?.bindings, readBinary);
+      if (get("dry-run")) {
+        output({ dry_run: true, command: operation.command, operationId: operation.operationId, request: { method: operation.method,
+          url: `${context.apiOrigin ?? "<api-origin>"}${input.path}`, params: Object.fromEntries(input.query),
+          headers: { ...input.extraHeaders, Authorization: "Bearer [REDACTED]", ...(input.binaryType ? { "Content-Type": input.binaryType } : input.jsonBody === undefined ? {} : { "Content-Type": "application/json" }) },
+          ...(input.binarySummary ? { file: input.binarySummary } : input.jsonBody === undefined ? {} : { data: input.jsonBody }) } }, { identity: "user" }); return;
+      }
+      if (!context.apiOrigin) throw new CLIError("api_origin_required", "Set --api-origin, LIMECLOUD_API_ORIGIN or config api_origin before calling a business API");
+      const token = usableAccess(context, env, now);
+      if (!env.LIMECLOUD_ACCESS_TOKEN && context.saved.api_origin !== context.apiOrigin) throw new CLIError("login_required", "API origin changed or was not bound to this login; run auth login with the intended --api-origin");
+      const granted = new Set(context.saved?.scope.split(/\s+/) ?? []);
+      const required = operation["x-lime-required-scopes"] ?? [];
+      if (!env.LIMECLOUD_ACCESS_TOKEN && required.some((scope) => !granted.has(scope))) throw new CLIError("missing_scopes", `This method requires explicit login scopes: ${required.join(" ")}`);
+      const result = await request({ issuer: context.issuer, origin: context.apiOrigin, method: operation.method, ...input, accessToken: token });
+      const response = resolveSchema(contract, operation.responses["200"]?.content?.["application/json"]?.schema ?? operation.responses["201"]?.content?.["application/json"]?.schema);
+      output(response?.properties?.data && result && Object.hasOwn(result, "data") ? result.data : result ?? { accepted: true }, { identity: "user", raw: Boolean(get("show-secrets")) }); return;
+    }
+    const form = await parametersFor(parsed, env, operation.method, readInput);
+    // 与参考 typed commands 一致：显式字段参数覆盖同名 JSON 参数。
+    for (const name of fields) if (get(flagName(name)) !== undefined) {
+      const single = { flags: new Map([["param", (parsed.flags.get(flagName(name)) ?? []).map((value) => `${name}=${value}`)]]), get: () => undefined };
+      const override = await parametersFor(single, env, operation.method, readInput);
+      form.delete(name);
+      for (const value of override.getAll(name)) form.append(name, value);
+    }
+    const basic = Boolean(operation.security?.some((item) => Object.hasOwn(item, "ClientSecretBasic")) && env.LIMECLOUD_CLIENT_SECRET);
+    const bearer = operation.security?.some((item) => Object.hasOwn(item, "Bearer"));
+    const requiresBasic = operation.path === "/oauth/introspect" || operation.path === "/oauth/token" && form.get("grant_type") === "client_credentials";
+    if (!get("dry-run") && (requiresBasic && !basic || basic && !context.clientID)) fail("This request requires LIMECLOUD_CLIENT_ID and LIMECLOUD_CLIENT_SECRET");
+    if (!basic && !requiresBasic && context.clientID && ["/oauth/token", "/oauth/device/authorization", "/oauth/revoke"].includes(operation.path) && !form.has("client_id")) form.set("client_id", context.clientID);
+    validateParameters(contract, operation, form, basic || requiresBasic, Boolean(get("dry-run")));
+    const identity = basic || requiresBasic ? "client" : bearer ? "user" : "public";
+    if (get("dry-run")) { output(preview(operation, context, form, identity), { identity }); return; }
+    const result = await request({ issuer: context.issuer, path: operation.path, method: operation.method, parameters: form,
+      clientID: context.clientID, clientSecret: basic ? env.LIMECLOUD_CLIENT_SECRET : undefined,
+      accessToken: bearer ? usableAccess(context, env, now) : undefined });
+    output(result ?? { accepted: true }, { identity, raw: Boolean(get("show-secrets")) }); return;
+  }
+  if (command !== "auth" || !["login", "status", "whoami", "refresh", "logout", "scopes", "check"].includes(action) || target) fail("Unknown command or public method; use --help or schema identity");
+  allowedFlags(parsed, ["issuer", "api-origin", "client-id", "auth-client-id", ...(action === "login" ? ["scope", "installation-id", "space-id", "no-wait", "resume", "dry-run"] : []),
+    ...(["refresh", "logout", "scopes"].includes(action) ? ["dry-run"] : []), ...(action === "logout" ? ["local-only"] : []), ...(action === "check" ? ["scope"] : [])]);
+  if (action === "status") { output(localIdentity(context, env, now), { identity: "user" }); return; }
+  if (action === "whoami") { output(await request({ issuer: context.issuer, path: "/oauth/userinfo", accessToken: usableAccess(context, env, now) }), { identity: "user" }); return; }
+  if (action === "check") {
+    if (!get("scope")) fail("Use auth check --scope SCOPES");
+    const required = scopeList(get("scope"));
+    const granted = new Set((context.saved?.scope ?? "").split(/\s+/));
+    const missing = required.filter((scope) => !granted.has(scope));
+    usableAccess(context, env, now);
+    if (env.LIMECLOUD_ACCESS_TOKEN || missing.length) throw new CLIError("missing_scopes", env.LIMECLOUD_ACCESS_TOKEN ? "Environment-token scopes are unknown; use a saved login or verify remotely in your application" : `Missing locally granted scopes: ${missing.join(", ")}`);
+    output({ checked: true, source: "local_grant", scopes: required }, { identity: "user" }); return;
+  }
+  if (action === "scopes") {
+    const method = catalogue.find((item) => item.operationId === "identity_discovery");
+    if (get("dry-run")) { output(preview(method, context, new URLSearchParams(), "public")); return; }
+    const metadata = await request({ issuer: context.issuer, path: method.path });
+    if (metadata?.issuer !== context.issuer || !Array.isArray(metadata.scopes_supported) || metadata.scopes_supported.some((scope) => typeof scope !== "string")) throw new CLIError("invalid_response", "Discovery did not return this issuer and its supported scopes");
+    output({ supported_scopes: metadata.scopes_supported, granted_scopes: context.saved?.scope.split(/\s+/).filter(Boolean) ?? [], source: "oidc_discovery",
+      client_enabled_scopes: null }); return;
+  }
+  if (["login", "refresh", "logout"].includes(action) && env.LIMECLOUD_CLIENT_SECRET) fail("Auth commands require a public client; unset LIMECLOUD_CLIENT_SECRET");
+  if (["login", "refresh", "logout"].includes(action) && env.LIMECLOUD_ACCESS_TOKEN) fail("Unset LIMECLOUD_ACCESS_TOKEN before managing saved credentials; revoke environment tokens explicitly with api");
+  async function auth() {
+    const current = await contextFor(parsed, env, settings, await store.read());
+    if (action === "login") {
+      if (get("no-wait") && get("resume")) fail("--no-wait and --resume cannot be combined");
+      if (get("resume") && ["scope", "installation-id", "space-id"].some((name) => get(name))) fail("A resumed authorization keeps its original scope and installation context");
+      if (Boolean(get("installation-id")) !== Boolean(get("space-id"))) fail("--installation-id and --space-id must be supplied together");
+      let pending;
+      if (get("resume")) {
+        pending = await pendingStore.read();
+        if (!pending?.device_code) throw new CLIError("login_required", "No pending device authorization; start auth login --no-wait");
+        issuerOrigin(pending.issuer);
+        verificationURI(pending.verification_uri, pending.issuer);
+        if (!/^[A-Z2-7]{4}-[A-Z2-7]{4}$/.test(pending.user_code)) throw new CLIError("invalid_credentials", "Invalid pending user code");
+        if ((get("issuer") ?? env.LIMECLOUD_ISSUER ?? pending.issuer) !== pending.issuer ||
+            (get("client-id") ?? env.LIMECLOUD_CLIENT_ID ?? pending.client_id) !== pending.client_id) fail("Resume issuer and client ID must match the saved device authorization");
+        if ((get("api-origin") ?? env.LIMECLOUD_API_ORIGIN ?? settings.api_origin ?? pending.api_origin) !== pending.api_origin) fail("Resume API origin must match the original device authorization");
+      } else {
+        if (!current.clientID && !get("dry-run")) fail("Provide a registered public client with --client-id or config init");
+        const scopes = scopeList(get("scope") ?? settings.scope ?? "openid profile email offline_access");
+        if (!scopes.includes("openid")) fail("Device sign-in requires the openid scope");
+        const form = new URLSearchParams({ scope: scopes.join(" ") });
+        if (get("installation-id")) { form.set("installation_id", get("installation-id")); form.set("space_id", get("space-id")); }
+        if (get("dry-run")) {
+          if (current.clientID) form.set("client_id", current.clientID);
+          output(preview(catalogue.find((item) => item.operationId === "identity_device_authorization"), current, form, "public")); return;
+        }
+        pending = await startDevice({ context: { issuer: current.issuer, apiOrigin: current.apiOrigin, clientID: current.clientID }, parameters: form, request, now });
+        await pendingStore.write(pending);
+      }
+      if (get("dry-run")) {
+        output(preview(catalogue.find((item) => item.operationId === "identity_token"), { issuer: pending.issuer }, new URLSearchParams({
+          client_id: pending.client_id, grant_type: "urn:ietf:params:oauth:grant-type:device_code", device_code: pending.device_code,
+        }), "public")); return;
+      }
+      const notice = { authorization_pending: true, verification_uri: pending.verification_uri, user_code: pending.user_code,
+        expires_at: pending.expires_at, resume_command: "limecloud-cli auth login --resume" };
+      if (get("no-wait")) { output(notice); return; }
+      io.stderr.write(`Open ${notice.verification_uri}\nConfirm code: ${notice.user_code}\n`);
+      const saved = await pollDevice({ pending, request, wait: pause, now, persist: (value) => pendingStore.write(value) });
+      await store.write(saved);
+      await pendingStore.write({});
+      output({ authenticated: true, issuer: saved.issuer, client_id: saved.client_id, expires_at: saved.expires_at, scope: saved.scope }, { identity: "user" }); return;
+    }
+    if (!current.saved) {
+      if (action === "logout" && !get("dry-run")) await pendingStore.write({});
+      output({ authenticated: false }, { identity: "user" }); return;
+    }
+    if (action === "refresh") {
+      if (current.saved.refresh_pending) throw new CLIError("login_required", "A previous refresh has an unknown result; start auth login again");
+      if (!current.saved.refresh_token) throw new CLIError("login_required", "No refresh token is saved; start auth login again");
+      if (current.apiOrigin && current.saved.api_origin !== current.apiOrigin) throw new CLIError("login_required", "API origin changed; refreshing cannot bind an existing grant to another API. Start auth login again");
+      const form = new URLSearchParams({ client_id: current.clientID, grant_type: "refresh_token", refresh_token: current.saved.refresh_token });
+      if (get("dry-run")) { output(preview(catalogue.find((item) => item.operationId === "identity_token"), current, form, "public")); return; }
+      await store.write({ ...current.saved, refresh_pending: true });
+      const tokens = await request({ issuer: current.issuer, path: "/oauth/token", method: "POST", parameters: form });
+      const saved = tokenRecord(tokens, { ...current, apiOrigin: current.saved.api_origin }, now());
+      await store.write(saved);
+      output({ authenticated: true, expires_at: saved.expires_at, scope: saved.scope }, { identity: "user" }); return;
+    }
+    const form = new URLSearchParams({ client_id: current.clientID, token: current.saved.refresh_token ?? current.saved.access_token,
+      token_type_hint: current.saved.refresh_token ? "refresh_token" : "access_token" });
+    if (get("dry-run")) {
+      output(get("local-only") ? { dry_run: true, local_credentials: "would_forget", remote_revocation: false } :
+        preview(catalogue.find((item) => item.operationId === "identity_revoke"), current, form, "public")); return;
+    }
+    if (!get("local-only")) await request({ issuer: current.issuer, path: "/oauth/revoke", method: "POST", parameters: form });
+    await store.write({}); await pendingStore.write({});
+    output({ authenticated: false, revoked: !get("local-only") }, { identity: "user" });
+  }
+  if (get("dry-run")) await auth();
+  else await store.withLock(auth);
+}
+
+export async function run(args, options = {}) {
+  const controller = new AbortController();
+  let cancelled;
+  const interrupt = () => { cancelled = "SIGINT"; controller.abort(); };
+  const terminate = () => { cancelled = "SIGTERM"; controller.abort(); };
+  process.once("SIGINT", interrupt); process.once("SIGTERM", terminate);
+  try { await execute(args, { ...options, signal: controller.signal }); }
+  catch (error) {
+    (options.io ?? process).stderr.write(`${JSON.stringify(errorEnvelope(error, cancelled))}\n`);
+    process.exitCode = cancelled === "SIGINT" ? 130 : cancelled === "SIGTERM" ? 143 : error.code === "invalid_arguments" || error.code === "invalid_issuer" ? 2 : 1;
+  } finally { process.removeListener("SIGINT", interrupt); process.removeListener("SIGTERM", terminate); }
+}

package/src/commands.mjs

@@ -0,0 +1,69 @@
+import { operations, resolveSchema } from "./contract.mjs";
+import { CLIError } from "./protocol.mjs";
+
+// 缺省映射兼容现有身份合同。新增公共领域可在合同中显式声明 x-lime-cli。
+const identityCommands = {
+  identity_discovery: "identity.discovery.get",
+  identity_authorize: "identity.authorization.authorize",
+  identity_token: "identity.token.exchange",
+  identity_device_authorization: "identity.device.authorize",
+  identity_userinfo: "identity.userinfo.get",
+  identity_userinfo_post: "identity.userinfo.post",
+  identity_jwks: "identity.keys.list",
+  identity_revoke: "identity.token.revoke",
+  identity_introspect: "identity.token.introspect",
+};
+
+export function commandOperations(contract) {
+  return operations(contract).map((operation) => {
+    const command = operation["x-lime-cli"] ?? identityCommands[operation.operationId];
+    if (!command || !/^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*){2}$/.test(command)) throw new CLIError("invalid_contract", "Every public CLI operation needs an explicit service.resource.method mapping");
+    return { ...operation, command };
+  });
+}
+
+function expanded(contract, input, depth = 0) {
+  if (!input || depth > 20) return input;
+  const schema = resolveSchema(contract, input);
+  if (Array.isArray(schema)) return schema.map((item) => expanded(contract, item, depth + 1));
+  if (typeof schema !== "object") return schema;
+  return Object.fromEntries(Object.entries(schema).map(([key, value]) => [key,
+    key === "properties" ? Object.fromEntries(Object.entries(value).map(([name, field]) => [name, expanded(contract, field, depth + 1)])) :
+    ["items", "oneOf", "anyOf", "allOf", "additionalProperties", "not"].includes(key) && typeof value === "object" ? expanded(contract, value, depth + 1) : value]));
+}
+
+function methodSchema(contract, operation) {
+  const params = operation.parameters?.filter((parameter) => ["query", "path"].includes(parameter.in)) ?? [];
+  const headers = operation.parameters?.filter((parameter) => parameter.in === "header") ?? [];
+  const content = operation.requestBody?.content;
+  const encoding = content && Object.keys(content)[0];
+  const response = operation.responses["200"]?.content?.["application/json"]?.schema ?? operation.responses["201"]?.content?.["application/json"]?.schema;
+  const access = operation.security?.flatMap((item) => Object.keys(item)) ?? [];
+  return { name: operation.command.replaceAll(".", " "), description: operation.description ?? operation.summary,
+    inputSchema: { type: "object", properties: {
+      ...(params.length ? { params: { type: "object", carrier: "--params", properties: Object.fromEntries(params.map((parameter) => [parameter.name,
+        { ...expanded(contract, parameter.schema), description: parameter.description, in: parameter.in, flag: parameterFlag(parameter.name) }])),
+        required: params.filter((parameter) => parameter.required).map((parameter) => parameter.name) } } : {}),
+      ...(headers.length ? { headers: { type: "object", carrier: "--header", properties: Object.fromEntries(headers.map((parameter) => [parameter.name,
+        { ...expanded(contract, parameter.schema), flag: parameterFlag(parameter.name) }])), required: headers.filter((parameter) => parameter.required).map((parameter) => parameter.name) } } : {}),
+      ...(encoding ? encoding === "image/png" ? { file: { ...expanded(contract, content[encoding].schema), carrier: "--file", encoding } } :
+        { data: { ...expanded(contract, content[encoding].schema), carrier: "--data", encoding } } : {}),
+    } }, outputSchema: response ? expanded(contract, response) : { type: "null" },
+    _meta: { envelope_version: "1.0", command: operation.command, operationId: operation.operationId, method: operation.method, path: operation.path,
+      access_tokens: access.includes("Bearer") ? ["user"] : access.includes("ClientSecretBasic") ? ["client"] : [],
+      required_scopes: operation["x-lime-required-scopes"] ?? (operation.path === "/oauth/userinfo" ? ["openid"] : []),
+      origin: operation["x-lime-cli-origin"], risk: operation.method === "GET" ? "read" : "write", doc_url: `https://open.limeai.run/docs/api?operation=${operation.operationId}` } };
+}
+
+const parameterFlag = (name) => `--${name.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/([A-Z])([A-Z][a-z])/g, "$1-$2").replaceAll("_", "-").toLowerCase()}`;
+
+export function inspectSchema(contract, segments = []) {
+  const target = segments.join(".");
+  const methods = commandOperations(contract);
+  if (!target) return methods.map((operation) => methodSchema(contract, operation));
+  const operation = methods.find((item) => item.command === target || item.operationId === target);
+  if (operation) return methodSchema(contract, operation);
+  const matching = methods.filter((item) => item.command.startsWith(`${target}.`));
+  if (matching.length) return matching.map((item) => methodSchema(contract, item));
+  throw new CLIError("invalid_arguments", `Unknown schema path: ${target}; start with schema`);
+}

package/src/contract.mjs

@@ -0,0 +1,72 @@
+import { readFile } from "node:fs/promises";
+import { CLIError } from "./protocol.mjs";
+
+let contract;
+let workspaceSource;
+async function load(name) {
+  if (workspaceSource === undefined) {
+    try { workspaceSource = JSON.parse(await readFile(new URL("../../../package.json", import.meta.url), "utf8")).name === "lime-cloud"; }
+    catch (error) { if (error.code !== "ENOENT") throw error; workspaceSource = false; }
+  }
+  const path = workspaceSource ? `../../../contracts/openapi/${name}.json` : `../dist/${name}.json`;
+  return JSON.parse(await readFile(new URL(path, import.meta.url), "utf8"));
+}
+function namespace(value, prefix) {
+  if (Array.isArray(value)) return value.map((item) => namespace(item, prefix));
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).map(([key, item]) => [key,
+    key === "$ref" && typeof item === "string" && item.startsWith("#/components/schemas/") ? item.replace("#/components/schemas/", `#/components/schemas/${prefix}`) : namespace(item, prefix)]));
+}
+
+export async function publicContract() {
+  if (contract) return contract;
+  const identity = await load("identity");
+  const management = await load("management");
+  contract = { ...identity, paths: {}, components: { ...identity.components, schemas: { ...identity.components.schemas }, securitySchemes: { ...identity.components.securitySchemes } } };
+  for (const [path, methods] of Object.entries(identity.paths)) {
+    contract.paths[path] = Object.fromEntries(Object.entries(methods).map(([method, operation]) => [method, { ...operation, "x-lime-cli-origin": "auth" }]));
+  }
+  if (management) {
+    if (management.info.version !== identity.info.version) throw new CLIError("invalid_contract", "Public API contract versions must match");
+    for (const [name, schema] of Object.entries(management.components?.schemas ?? {})) contract.components.schemas[`Management_${name}`] = namespace(schema, "Management_");
+    for (const [name, scheme] of Object.entries(management.components?.securitySchemes ?? {})) {
+      const existing = contract.components.securitySchemes[name];
+      if (existing && (existing.type !== scheme.type || existing.scheme !== scheme.scheme)) throw new CLIError("invalid_contract", "Public API security scheme collision");
+      contract.components.securitySchemes[name] = scheme;
+    }
+    for (const [path, methods] of Object.entries(management.paths)) {
+      if (!/^\/api\/v1\/(open|account|operations|admin)(\/|$)/.test(path)) throw new CLIError("invalid_contract", "Management contract contains an unexpected public path");
+      if (contract.paths[path]) throw new CLIError("invalid_contract", "Duplicate public API path");
+      contract.paths[path] = Object.fromEntries(Object.entries(methods).map(([method, operation]) => [method,
+        { ...namespace(operation, "Management_"), "x-lime-cli-origin": "api" }]));
+    }
+  }
+  const ids = operations(contract).map((operation) => operation.operationId);
+  if (new Set(ids).size !== ids.length) throw new CLIError("invalid_contract", "Duplicate public operationId");
+  return contract;
+}
+
+export function operations(contract) {
+  return Object.entries(contract.paths).flatMap(([path, methods]) => Object.entries(methods)
+    .filter(([method]) => ["get", "post", "put", "patch", "delete", "head", "options"].includes(method))
+    .map(([method, definition]) => ({ path, method: method.toUpperCase(), ...definition })));
+}
+
+export function resolveSchema(contract, schema) {
+  if (!schema?.$ref) return schema;
+  const prefix = "#/components/schemas/";
+  if (!schema.$ref.startsWith(prefix)) throw new CLIError("invalid_contract", "Unsupported public schema reference");
+  const found = contract.components.schemas[schema.$ref.slice(prefix.length)];
+  if (!found) throw new CLIError("invalid_contract", "Unknown public schema reference");
+  return found;
+}
+
+export function requestSchema(contract, operation, parameters) {
+  const input = operation.requestBody?.content["application/x-www-form-urlencoded"]?.schema;
+  const schema = resolveSchema(contract, input);
+  if (!schema?.oneOf) return schema;
+  const candidates = schema.oneOf.map((item) => resolveSchema(contract, item));
+  const matching = candidates.find((item) => item.properties?.grant_type?.const === parameters.get("grant_type"));
+  if (!matching) throw new CLIError("invalid_arguments", "Choose a supported grant_type; use schema identity.token.exchange");
+  return matching;
+}