@limecloud/cli 0.3.0 → 0.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@limecloud/cli",
-  "version": "0.3.0",
+  "version": "0.8.0",
   "description": "Lime Cloud CLI for public identity and delegated platform APIs",
   "type": "module",
   "engines": {
@@ -31,5 +31,8 @@
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org"
+  },
+  "dependencies": {
+    "i18next": "25.8.0"
   }
 }

package/src/cli.mjs

@@ -1,3 +1,4 @@
+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";
@@ -6,56 +7,14 @@ import { CLIError, issuerOrigin, pollDevice, protocolRequest, startDevice, token
 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 = `limecloud-cli — Lime Cloud CLI (@limecloud/cli)
+const help = () => ["help.overview", "help.apiFlags", "help.connectionFlags"].map(key => translate(key)).join("");
 
-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 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) {
@@ -71,31 +30,31 @@ export function parseArguments(args, protocolFields = []) {
     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}`);
+    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(`--${name} does not take a value`);
+    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(`--${name} needs a value`);
+      if (typeof value !== "string" || !value || value.startsWith("--")) fail(message("arguments.optionValueRequired", { name }));
     }
-    if (flags.has(name) && !["param", "param-env", "audience", "header"].includes(name)) fail(`Duplicate option --${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", ...names].includes(key)) fail(`Option --${key} is not supported by this command`);
+  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" ? "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`;
+  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) {
@@ -108,8 +67,8 @@ async function contextFor(parsed, env, settings, saved, management = false) {
 }
 
 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");
+  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;
 }
 
@@ -126,20 +85,29 @@ 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]" } :
+    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, { env = process.env, io = process, store = new CredentialStore(credentialsPath(env)),
+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 } = {}) {
+  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, signal });
+  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; }
@@ -153,21 +121,57 @@ export async function execute(args, { env = process.env, io = process, store = n
   }
   if (command === "docs") {
     allowedFlags(parsed, []);
-    if (target || extra.length || action && !/^[a-z0-9-]{1,80}$/.test(action)) fail("Use docs [article-slug]");
+    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 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);
+      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;
     }
@@ -177,9 +181,9 @@ export async function execute(args, { env = process.env, io = process, store = n
         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>");
+    fail(message("arguments.configUsage"));
   }
-  if (extra.length) fail("Too many arguments; use --help");
+  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;
@@ -189,7 +193,7 @@ export async function execute(args, { env = process.env, io = process, store = n
   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`);
+    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 },
@@ -197,16 +201,15 @@ export async function execute(args, { env = process.env, io = process, store = n
   }
   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 locale = currentLocalizer().locale;
     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))
+    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: locale === "zh-CN" ? operation["x-lime-summary-zh-CN"] ?? operation.summary : operation.summary }))); return;
+        summary: localizeContract(operation) }))); return;
   }
   if (command === "api" && action === "schema") {
     allowedFlags(parsed, []);
-    if (!catalogue.some((operation) => operation.operationId === target)) fail("Choose a public operationId from api list");
+    if (!catalogue.some((operation) => operation.operationId === target)) fail(message("arguments.operationRequired"));
     output(inspectSchema(contract, [target])); return;
   }
   if (operation) {
@@ -217,15 +220,15 @@ export async function execute(args, { env = process.env, io = process, store = n
       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" }) },
+          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", "Set --api-origin, LIMECLOUD_API_ORIGIN or config api_origin before calling a business API");
+      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", "API origin changed or was not bound to this login; run auth login with the intended --api-origin");
+      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", `This method requires explicit login scopes: ${required.join(" ")}`);
+      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;
@@ -241,7 +244,7 @@ export async function execute(args, { env = process.env, io = process, store = n
     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 (!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";
@@ -251,50 +254,50 @@ export async function execute(args, { env = process.env, io = process, store = n
       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");
+  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("Use auth check --scope SCOPES");
+    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 ? "Environment-token scopes are unknown; use a saved login or verify remotely in your application" : `Missing locally granted scopes: ${missing.join(", ")}`);
+    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", "Discovery did not return this issuer and its supported scopes");
+    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("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");
+  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("--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");
+      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", "No pending device authorization; start auth login --no-wait");
+        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", "Invalid pending user code");
+        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("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");
+            (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("Provide a registered public client with --client-id or config init");
+        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("Device sign-in requires the openid scope");
+        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")) {
@@ -312,7 +315,7 @@ export async function execute(args, { env = process.env, io = process, store = n
       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`);
+      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({});
@@ -323,9 +326,9 @@ export async function execute(args, { env = process.env, io = process, store = n
       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");
+      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 });
@@ -356,7 +359,8 @@ export async function run(args, options = {}) {
   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`);
+    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

@@ -1,3 +1,4 @@
+import { localizeContract, message } from "./i18n.mjs";
 import { operations, resolveSchema } from "./contract.mjs";
 import { CLIError } from "./protocol.mjs";
 
@@ -17,7 +18,7 @@ const identityCommands = {
 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");
+    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 };
   });
 }
@@ -39,10 +40,10 @@ function methodSchema(contract, operation) {
   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,
+  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: parameter.description, in: parameter.in, flag: parameterFlag(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) } } : {}),
@@ -65,5 +66,5 @@ export function inspectSchema(contract, segments = []) {
   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`);
+  throw new CLIError("invalid_arguments", message("arguments.unknownSchema", { target }));
 }

package/src/contract.mjs

@@ -1,15 +1,11 @@
+import { message } from "./i18n.mjs";
 import { readFile } from "node:fs/promises";
 import { CLIError } from "./protocol.mjs";
+import { contractURL } from "./resources.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"));
+  return JSON.parse(await readFile(contractURL(name), "utf8"));
 }
 function namespace(value, prefix) {
   if (Array.isArray(value)) return value.map((item) => namespace(item, prefix));
@@ -27,22 +23,22 @@ export async function publicContract() {
     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");
+    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", "Public API security scheme collision");
+      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", "Management contract contains an unexpected public path");
-      if (contract.paths[path]) throw new CLIError("invalid_contract", "Duplicate public API path");
+      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", "Duplicate public operationId");
+  if (new Set(ids).size !== ids.length) throw new CLIError("invalid_contract", message("contract.duplicateOperation"));
   return contract;
 }
 
@@ -55,9 +51,9 @@ export function operations(contract) {
 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");
+  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", "Unknown public schema reference");
+  if (!found) throw new CLIError("invalid_contract", message("contract.referenceUnknown"));
   return found;
 }
 
@@ -67,6 +63,6 @@ export function requestSchema(contract, operation, parameters) {
   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");
+  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];
+}