@limecloud/cli 0.0.0-stage → 0.6.0

package/package.json

@@ -1,6 +1,38 @@
 {
   "name": "@limecloud/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.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"
+  },
+  "dependencies": {
+    "i18next": "25.8.0"
+  }
+}

package/src/cli.mjs

@@ -0,0 +1,366 @@
+import { createLocalizer, currentLocalizer, localizeContract, locales, message, normalizeLocale, requestedLocale, translate, withLocalizer } from "./i18n.mjs";
+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";
+import { configureInitialSettings, discoverCLISettings, initialSettings, installationPlan, installRuntime, withSetupPrompt } from "./install.mjs";
+
+export { validateParameters } from "./input.mjs";
+
+const help = () => ["help.overview", "help.apiFlags", "help.connectionFlags"].map(key => translate(key)).join("");
+
+const booleanFlags = new Set(["help", "version", "json", "show-secrets", "local-only", "dry-run", "no-wait", "resume", "offline", "no-config", "skip-login", "login"]);
+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", "prefix"]);
+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(message("arguments.unknownOption", { name }));
+    let value = true;
+    if (booleanFlags.has(name) && rest.length) fail(message("arguments.booleanOptionValue", { name }));
+    if (!booleanFlags.has(name)) {
+      value = rest.length ? rest.join("=") : args[++index];
+      if (typeof value !== "string" || !value || value.startsWith("--")) fail(message("arguments.optionValueRequired", { name }));
+    }
+    if (flags.has(name) && !["param", "param-env", "audience", "header"].includes(name)) fail(message("arguments.duplicateOption", { 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", "locale", ...names].includes(key)) fail(message("arguments.optionUnsupported", { name: key }));
+}
+
+function commandHelp(command, contract) {
+  const serviceMethods = commandOperations(contract).filter(operation => operation.command.startsWith(command + "."));
+  if (serviceMethods.length) return (command === "identity" ? translate("help.identityShortcuts") : "") +
+    translate("help.typedMethods", { service: command, methods: serviceMethods.map(operation =>
+      "  " + operation.command.replaceAll(".", " ") + "  (" + operation.method + " " + operation.path + ")").join("\n") });
+  if (["auth", "config", "schema", "install"].includes(command)) return translate("help." + command);
+  if (command === "api") return translate("help.apiFlags") + translate("help.api");
+  return help() + "\n" + translate("help.services", { services: [...new Set(commandOperations(contract).map(operation => operation.command.split(".")[0]))].join(", ") });
+}
+
+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", message("auth.loginRequired"));
+  if (!env.LIMECLOUD_ACCESS_TOKEN && Date.parse(context.saved.expires_at) <= now()) throw new CLIError("token_expired", message("auth.tokenExpired"));
+  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", "Accept-Language": currentLocalizer().locale, ...(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, options = {}) {
+  const requested = requestedLocale(args, options.env ?? process.env);
+  return withLocalizer(createLocalizer(requested.locale), async () => {
+    if (requested.explicit !== undefined && !normalizeLocale(requested.explicit)) fail(message("arguments.unsupportedLocale", { locales: locales.join(", ") }));
+    return executeCommand(args, options);
+  });
+}
+
+async function executeCommand(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,
+  installer = installRuntime, prompt } = {}) {
+  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, extraHeaders: { ...input.extraHeaders, "Accept-Language": currentLocalizer().locale }, 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(message("arguments.docsUsage"));
+    output({ url: `https://open.limeai.run/docs${action ? `/${action}` : ""}` }); return;
+  }
+  if (command === "install") {
+    allowedFlags(parsed, ["prefix", "issuer", "api-origin", "client-id", "scope", "no-config", "skip-login", "login", "dry-run"]);
+    if (action || get("login") && (get("skip-login") || get("no-config"))) fail(message("install.usage"));
+    const plan = installationPlan(contract.info.version, get("prefix"), env);
+    let prepared = get("no-config") ? null : await initialSettings(parsed, env, await settingsStore.read() ?? {});
+    let discovery = { status: "not_needed" };
+    if (get("dry-run")) {
+      output({ dry_run: true, installation: plan, configuration: { status: get("no-config") ? "skipped" : prepared.client_id ? "planned" : "pending", settings: prepared },
+        discovery: { status: "not_started" }, authorization: { status: "not_started" } }, { identity: "local" }); return;
+    }
+    if (prepared && !prepared.client_id) {
+      try {
+        prepared = await discoverCLISettings(prepared, request);
+        discovery = { status: "available", url: `${prepared.issuer}/runtime/v1/cli` };
+      } catch (error) {
+        if (signal?.aborted) throw error;
+        discovery = { status: "unavailable", error_code: "cli_metadata_unavailable", message: translate("install.discoveryUnavailable") };
+      }
+    }
+    if (get("login") && !prepared.client_id && !prompt && !io.stdin?.isTTY) fail(message("arguments.publicClientRequired"));
+    if (get("login") && env.LIMECLOUD_CLIENT_SECRET) fail(message("arguments.publicClientOnly"));
+    if (get("login") && env.LIMECLOUD_ACCESS_TOKEN) fail(message("arguments.externalTokenActive"));
+    await installer(plan, { env, io, signal });
+    await withSetupPrompt({ io, prompt, signal, interactive: !get("json") }, async ask => {
+      const configured = get("no-config") ? null : await configureInitialSettings(settingsStore, parsed, env, ask, true, prepared);
+      let authorization = { status: "not_started" };
+      const beginLogin = configured && (get("login") || ask && !get("skip-login") && /^(y|yes)$/i.test(await ask("install.promptLogin", "n")));
+      if (beginLogin) {
+        const chunks = [];
+        await execute(["auth", "login", "--no-wait", "--json", "--locale", currentLocalizer().locale], {
+          env, io: { stdin: io.stdin, stderr: io.stderr, stdout: { write: value => chunks.push(value) } }, store, settingsStore, pendingStore,
+          request: requestImpl, wait, now, signal, contract,
+        });
+        authorization = { status: "pending", ...JSON.parse(chunks.join("")).data };
+      }
+      output({ installation: { ...plan, installed: true }, configuration: { status: get("no-config") ? "skipped" : configured ? "configured" : "pending", path: settingsStore.path ?? null, settings: configured },
+        discovery, authorization, next_steps: [translate("install.pathHint", { directory: plan.bin_directory }),
+          ...(!configured ? ["limecloud-cli config init"] : []),
+          authorization.status === "pending" ? "limecloud-cli auth login --resume" : "limecloud-cli auth login",
+          "limecloud-cli doctor --offline", "limecloud-cli schema"] }, { identity: "local" });
+    }); 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 withSetupPrompt({ io, prompt, signal, interactive: !get("json") }, async ask => {
+        const settings = await configureInitialSettings(settingsStore, parsed, env, ask);
+        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(message("arguments.configUsage"));
+  }
+  if (extra.length) fail(message("arguments.tooMany"));
+  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(message("arguments.noPositionals", { command }));
+    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 = currentLocalizer().locale;
+    const needle = target?.toLocaleLowerCase(locale) ?? "";
+    output(catalogue.filter((operation) => `${operation.operationId} ${operation.path} ${operation.summary} ${localizeContract(operation)}`.toLocaleLowerCase(locale).includes(needle))
+      .map((operation) => ({ command: operation.command, operationId: operation.operationId, method: operation.method, path: operation.path,
+        summary: localizeContract(operation) }))); return;
+  }
+  if (command === "api" && action === "schema") {
+    allowedFlags(parsed, []);
+    if (!catalogue.some((operation) => operation.operationId === target)) fail(message("arguments.operationRequired"));
+    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, "Accept-Language": currentLocalizer().locale, 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", message("auth.apiOriginRequired"));
+      const token = usableAccess(context, env, now);
+      if (!env.LIMECLOUD_ACCESS_TOKEN && context.saved.api_origin !== context.apiOrigin) throw new CLIError("login_required", message("auth.apiBindingChanged"));
+      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", message("auth.requiredScopes", { 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(message("arguments.basicCredentialsRequired"));
+    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(message("arguments.unknownCommand"));
+  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(message("arguments.scopeCheckUsage"));
+    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 ? message("auth.externalScopesUnknown") : message("auth.missingScopes", { 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", message("auth.discoveryInvalid"));
+    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(message("arguments.publicClientOnly"));
+  if (["login", "refresh", "logout"].includes(action) && env.LIMECLOUD_ACCESS_TOKEN) fail(message("arguments.externalTokenActive"));
+  async function auth() {
+    const current = await contextFor(parsed, env, settings, await store.read());
+    if (action === "login") {
+      if (get("no-wait") && get("resume")) fail(message("arguments.deviceModeConflict"));
+      if (get("resume") && ["scope", "installation-id", "space-id"].some((name) => get(name))) fail(message("arguments.resumeContextImmutable"));
+      if (Boolean(get("installation-id")) !== Boolean(get("space-id"))) fail(message("arguments.installationContextPair"));
+      let pending;
+      if (get("resume")) {
+        pending = await pendingStore.read();
+        if (!pending?.device_code) throw new CLIError("login_required", message("auth.pendingMissing"));
+        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", message("auth.pendingCodeInvalid"));
+        if ((get("issuer") ?? env.LIMECLOUD_ISSUER ?? pending.issuer) !== pending.issuer ||
+            (get("client-id") ?? env.LIMECLOUD_CLIENT_ID ?? pending.client_id) !== pending.client_id) fail(message("arguments.resumeIdentityMismatch"));
+        if ((get("api-origin") ?? env.LIMECLOUD_API_ORIGIN ?? settings.api_origin ?? pending.api_origin) !== pending.api_origin) fail(message("arguments.resumeOriginMismatch"));
+      } else {
+        if (!current.clientID && !get("dry-run")) fail(message("arguments.registeredClientRequired"));
+        const scopes = scopeList(get("scope") ?? settings.scope ?? "openid profile email offline_access");
+        if (!scopes.includes("openid")) fail(message("arguments.openidRequired"));
+        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(translate("auth.deviceNotice", { uri: notice.verification_uri, code: notice.user_code }));
+      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", message("auth.refreshUncertain"));
+      if (!current.saved.refresh_token) throw new CLIError("login_required", message("auth.refreshMissing"));
+      if (current.apiOrigin && current.saved.api_origin !== current.apiOrigin) throw new CLIError("login_required", message("auth.refreshBindingChanged"));
+      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) {
+    const localizer = createLocalizer(requestedLocale(args, options.env ?? process.env).locale);
+    (options.io ?? process).stderr.write(`${JSON.stringify(errorEnvelope(error, cancelled, localizer))}\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,70 @@
+import { localizeContract, message } from "./i18n.mjs";
+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", message("contract.commandMappingRequired"));
+    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: localizeContract(operation, "description") ?? localizeContract(operation),
+    inputSchema: { type: "object", properties: {
+      ...(params.length ? { params: { type: "object", carrier: "--params", properties: Object.fromEntries(params.map((parameter) => [parameter.name,
+        { ...expanded(contract, parameter.schema), description: localizeContract(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", message("arguments.unknownSchema", { target }));
+}

package/src/contract.mjs

@@ -0,0 +1,68 @@
+import { message } from "./i18n.mjs";
+import { readFile } from "node:fs/promises";
+import { CLIError } from "./protocol.mjs";
+import { contractURL } from "./resources.mjs";
+
+let contract;
+async function load(name) {
+  return JSON.parse(await readFile(contractURL(name), "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", message("contract.versionMismatch"));
+    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", message("contract.securityCollision"));
+      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", message("contract.unexpectedPath"));
+      if (contract.paths[path]) throw new CLIError("invalid_contract", message("contract.duplicatePath"));
+      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", message("contract.duplicateOperation"));
+  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", message("contract.referenceUnsupported"));
+  const found = contract.components.schemas[schema.$ref.slice(prefix.length)];
+  if (!found) throw new CLIError("invalid_contract", message("contract.referenceUnknown"));
+  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", message("arguments.grantTypeRequired"));
+  return matching;
+}

package/src/i18n.mjs

@@ -0,0 +1,68 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { readFileSync } from "node:fs";
+import { createInstance } from "i18next";
+import { localeRegistryURL } from "./resources.mjs";
+
+// 构建时从唯一登记复制；外部语言输入从不参与资源文件路径。
+export const localeRegistry = JSON.parse(readFileSync(localeRegistryURL, "utf8"));
+export const defaultLocale = localeRegistry.defaultLocale;
+export const localeOptions = localeRegistry.locales;
+export const locales = localeOptions.map(({ code }) => code);
+const resources = Object.fromEntries(locales.map(code => [code, {
+  cli: JSON.parse(readFileSync(new URL(`./locales/${code}.json`, import.meta.url), "utf8")),
+}]));
+const contexts = new AsyncLocalStorage();
+
+export function normalizeLocale(input) {
+  if (typeof input !== "string" || input.length > 64) return undefined;
+  try {
+    const tag = Intl.getCanonicalLocales(input)[0];
+    return localeOptions.find(item => item.code === tag)?.code ??
+      localeOptions.find(item => item.aliases.includes(tag))?.code ??
+      localeOptions.find(item => item.prefixes.some(prefix => tag?.startsWith(prefix)))?.code;
+  } catch { return undefined; }
+}
+
+function environmentLocale(env) {
+  // POSIX 的编码/修饰后缀不属于语言标签；只在环境变量入口转换。
+  for (const input of [env.LIMECLOUD_LOCALE, env.LC_ALL, env.LC_MESSAGES, env.LANG]) {
+    const locale = normalizeLocale(input?.split(/[.@]/)[0].replaceAll("_", "-"));
+    if (locale) return locale;
+    if (input) return defaultLocale;
+  }
+  return defaultLocale;
+}
+
+export function requestedLocale(args, env = process.env) {
+  for (let index = 0; index < args.length; index++) {
+    if (args[index] === "--locale") return { explicit: args[index + 1], locale: normalizeLocale(args[index + 1]) ?? environmentLocale(env) };
+    if (args[index].startsWith("--locale=")) {
+      const explicit = args[index].slice(9);
+      return { explicit, locale: normalizeLocale(explicit) ?? environmentLocale(env) };
+    }
+  }
+  return { locale: environmentLocale(env) };
+}
+
+export function createLocalizer(locale = defaultLocale) {
+  const instance = createInstance();
+  void instance.init({ lng: normalizeLocale(locale) ?? defaultLocale, fallbackLng: defaultLocale,
+    supportedLngs: locales, load: "currentOnly", resources, ns: ["cli"], defaultNS: "cli",
+    interpolation: { escapeValue: false }, initImmediate: false, keySeparator: false });
+  return { locale: instance.resolvedLanguage ?? defaultLocale, t: (key, values = {}) => {
+    // 缺失消息安全回退，不能把原始翻译键展示给用户。
+    return instance.exists(key) ? instance.t(key, values) : instance.t("errors.failed");
+  } };
+}
+
+const fallback = createLocalizer();
+export const currentLocalizer = () => contexts.getStore() ?? fallback;
+export const withLocalizer = (localizer, operation) => contexts.run(localizer, operation);
+export const translate = (key, values) => currentLocalizer().t(key, values);
+export const message = (key, values = {}) => ({ key, values });
+
+export function localizeContract(value, field = "summary") {
+  const locale = currentLocalizer().locale;
+  // 新合同使用语言映射，旧合同扩展只作读取兼容。
+  return value?.["x-lime-localizations"]?.[locale]?.[field] ?? value?.[`x-lime-${field}-${locale}`] ?? value?.[field];
+}