jumbo-toast-cli 0.0.0-stage → 0.1.0

package/LICENSE

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

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
+<!-- INPUT: npm package jumbo-toast-cli, Node.js 22+, protected Jumbo Toast API and operator credentials. -->
+<!-- OUTPUT: Standalone installation, login, query and controlled-update instructions without requiring repository files. -->
+<!-- POS: Public npm package README; downloading the client does not grant backend permissions. -->
+<!-- PROTOCOL: Sync package.json and docs/operations/JUMBO_CLI_FEISHU.md when install, auth or safety boundaries change. -->
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Jumbo Toast CLI
+
+`jumbo` 是 Jumbo Toast 后台的命令行客户端，供授权运营人员或 AI 查询数据、预览并执行受控更新。需要 Node.js 22 或更高版本。
+
+## 安装与更新
+
+```bash
+npm install -g jumbo-toast-cli@latest
+jumbo --version
+jumbo help
+jumbo capabilities
+```
+
+更新使用同一条安装命令；本机保存的 profile 不在安装目录内，升级时会保留。
+
+## 登录
+
+把地址换成实际后台 origin。远程地址必须 HTTPS；本机开发允许 localhost/127.0.0.1 HTTP。
+
+```bash
+jumbo --profile production --base-url https://your-backend.example \
+  auth login --email operator@example.com
+
+jumbo --profile production doctor
+jumbo --profile production auth whoami
+```
+
+交互终端会隐藏密码输入。自动化可使用 `--password-stdin`、`--password-env ENV_NAME` 或仓库外 `0600` 权限的 `--password-file`。禁止把密码或 token 写到命令参数中。
+
+profile 默认保存在 `~/.config/jumbo-toast/credentials.json`，目录权限 `0700`、文件权限 `0600`；token 只发给其绑定的后台地址。`auth logout` 删除本机 profile，不撤销其他已签发的服务端 token。
+
+## 查询
+
+```bash
+jumbo --profile production products list --status on --page-size 20
+jumbo --profile production orders list --status active --limit 20
+jumbo --profile production stores list
+jumbo --profile production inventory alerts --threshold 10
+jumbo --profile production business daily --days 7
+jumbo --profile production reminders status
+jumbo --profile production reminders history --limit 20
+```
+
+输出为 JSON，权限由服务器校验，金额单位为整数分。用 `jumbo <command> --help` 查看参数。
+
+## 受控更新
+
+```bash
+jumbo --profile production control export \
+  --kind product --id YOUR_PRODUCT_ID --out ./product.json
+
+# 编辑 product.json 的 patch 字段，再预览
+jumbo --profile production control preview --file ./product.json
+
+jumbo --profile production control apply --file ./product.json \
+  --reason "更新商品说明" --idempotency-key "product-copy-20261009-0001" --apply
+```
+
+可写种类：`product`、`store-availability`、`store-hours`、`home-bulletins`、`banner`、`feishu-rules`。商品写入限内容、上下架和排序；没有价格、库存数量、付款、退款、储值、角色权限或任意 URL 写入口。
+
+服务器校验 revision、权限、原因和幂等键；CLI 在成功回执后必须回读核对。409 时重新导出并检查差异；`APPLY_RESULT_UNKNOWN` 时使用同一文件、原因和幂等键重试；`READBACK_FAILED` 表示不能确认最终状态。
+
+## 飞书与后端兼容性
+
+安装 CLI 不会部署后台或启动自动提醒。目标后台必须部署兼容的 control-plane/reminder API；旧后台可能返回 404。飞书 Webhook/签名密钥仅配置在服务器，CLI 只查询状态或修改业务提醒规则，不持有机器人密钥，也没有本地常驻转发命令。
+
+默认关闭的后台通知任务负责新订单、低库存与每日摘要。真实群消息送达需在服务器配置后单独验证；客户端安装成功不等于飞书已绑定。
+
+## 许可
+
+客户端代码采用 MIT，见包内 LICENSE。包不包含门店品牌图片、数据库、`.env`、profile 或后台源码。

package/bin/jumbo.mjs

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+// INPUT: Process argv/env/stdin/stdout and the Jumbo Toast CLI core.
+// OUTPUT: One structured JSON command result and a stable process exit code.
+// POS: Executable `jumbo` bin; all parsing, networking and credential policy stays in src/core.mjs.
+// PROTOCOL: Sync ../package.json and ../src/core.mjs when executable invocation changes.
+
+import { runCli } from '../src/core.mjs';
+
+process.exitCode = await runCli();

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "jumbo-toast-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "private": false,
+  "type": "module",
+  "bin": {
+    "jumbo": "./bin/jumbo.mjs"
+  },
+  "scripts": {
+    "check": "node --check bin/jumbo.mjs && node --check src/errors.mjs && node --check src/credentials.mjs && node --check src/http.mjs && node --check src/capabilities.mjs && node --check src/core.mjs",
+    "test": "node --test test/*.test.mjs",
+    "prepublishOnly": "npm run check && npm test"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "description": "Jumbo Toast 后台的受控 HTTP 运维 CLI",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wlct517/Jumbotoast.git",
+    "directory": "apps/cli"
+  },
+  "keywords": [
+    "jumbotoast",
+    "admin",
+    "cli"
+  ],
+  "files": [
+    "README.md",
+    "LICENSE",
+    "bin/jumbo.mjs",
+    "src/errors.mjs",
+    "src/credentials.mjs",
+    "src/http.mjs",
+    "src/capabilities.mjs",
+    "src/core.mjs"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/capabilities.mjs

@@ -0,0 +1,62 @@
+// INPUT: Authorized CLI scope, real API filters/RBAC and narrow control-plane resource kinds.
+// OUTPUT: Immutable command metadata used by help/capabilities and checked alongside dispatch options.
+// POS: Human/machine discovery contract; listing a capability never grants its server permission.
+// PROTOCOL: Sync core.mjs, apps/api/src/routes/control-plane.ts and docs/operations/JUMBO_CLI_FEISHU.md when commands, filters or permissions change.
+
+export const CLI_VERSION = '0.1.0';
+
+export const CONTROL_KINDS = Object.freeze([
+  'product',
+  'store-availability',
+  'store-hours',
+  'home-bulletins',
+  'banner',
+  'feishu-rules',
+]);
+
+export const CLI_CAPABILITIES = Object.freeze([
+  { command: 'version', mode: 'local', permission: null, options: [] },
+  { command: 'auth login', mode: 'auth', permission: null, options: ['email', 'password-stdin', 'password-file', 'password-env'] },
+  { command: 'auth whoami', mode: 'read', permission: 'active staff', options: [] },
+  { command: 'auth logout', mode: 'local', permission: null, options: [] },
+  { command: 'doctor', mode: 'read', permission: null, options: [] },
+  { command: 'capabilities', mode: 'local', permission: null, options: [] },
+  { command: 'catalog show', mode: 'read', permission: 'orders.read', options: [] },
+  { command: 'products list', mode: 'read', permission: 'orders.read', options: ['store-id', 'status', 'q', 'page', 'page-size'] },
+  { command: 'products get', mode: 'read', permission: 'orders.read', options: ['<id>'] },
+  { command: 'orders list', mode: 'read', permission: 'orders.read', options: ['status', 'store-id', 'q', 'limit', 'cursor'] },
+  { command: 'orders get', mode: 'read', permission: 'orders.read', options: ['<id>'] },
+  { command: 'stores list', mode: 'read', permission: 'stores.read', options: [] },
+  { command: 'store status', mode: 'read', permission: 'stores.read', options: ['<store-id>'] },
+  { command: 'inventory alerts', mode: 'read', permission: 'dashboard.read', options: ['store-id', 'threshold'] },
+  { command: 'business summary', mode: 'read', permission: 'dashboard.read', options: [] },
+  { command: 'business daily', mode: 'read', permission: 'analytics.read', options: ['days'] },
+  { command: 'reminders status', mode: 'read', permission: 'settings.read', options: [] },
+  { command: 'reminders history', mode: 'read', permission: 'settings.read', options: ['limit'] },
+  { command: 'control export', mode: 'local-file/read', permission: 'per-kind write permission', options: ['kind', 'id', 'out'] },
+  { command: 'control preview', mode: 'dry-run', permission: 'per-kind write permission', options: ['file'] },
+  { command: 'control apply', mode: 'controlled-write', permission: 'per-kind write permission', options: ['file', 'reason', 'idempotency-key', 'apply'] },
+]);
+
+export const HELP = Object.freeze({
+  name: 'jumbo',
+  version: CLI_VERSION,
+  globalOptions: {
+    profile: 'Local profile name (default: default)',
+    'base-url': 'Loopback HTTP or remote HTTPS origin; stored tokens remain origin-bound',
+    'timeout-ms': '500-30000, default 15000',
+    pretty: 'Pretty-print the JSON envelope',
+  },
+  authSafety: {
+    forbiddenArgv: ['password', 'token'],
+    passwordSources: ['--password-stdin', '--password-file <0600 file>', '--password-env <name>', 'hidden TTY prompt'],
+  },
+  controlKinds: CONTROL_KINDS,
+  examples: [
+    'jumbo --base-url http://127.0.0.1:8787 auth login --email admin@jumbotoast.local --password-stdin',
+    'jumbo orders list --status active --limit 20',
+    'jumbo control export --kind product --id p_club --out ./product.json',
+    'jumbo control preview --file ./product.json',
+    'jumbo control apply --file ./product.json --reason "更新商品文案" --idempotency-key product-copy-20261009-0001 --apply',
+  ],
+});

package/src/core.mjs

@@ -0,0 +1,576 @@
+// INPUT: Process argv/env/stdin (including pnpm's leading -- separator), fixed capability metadata, secure profile store and bounded JSON HTTP client.
+// OUTPUT: runCli/executeCommand with stable JSON envelopes for secret-safe auth, diagnostics, real filtered reads, and file preview/apply/read-back verification.
+// POS: `jumbo` command dispatcher; it cannot address arbitrary API paths, databases, payment writes, deployments or Feishu test sends.
+// PROTOCOL: Sync capabilities.mjs, apps/api/src/routes/control-plane.ts, tests and docs/operations/JUMBO_CLI_FEISHU.md when commands/options/output change.
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createCredentialStore, readSecretFile, validateProfileName } from './credentials.mjs';
+import { CLI_CAPABILITIES, CLI_VERSION, CONTROL_KINDS, HELP } from './capabilities.mjs';
+import { asCliError, CliError, EXIT } from './errors.mjs';
+import { normalizeBaseUrl, requestJson, resolveProfileTarget } from './http.mjs';
+
+const BOOLEAN_OPTIONS = new Set(['pretty', 'apply', 'password-stdin', 'help', 'version']);
+const GLOBAL_OPTIONS = new Set(['profile', 'base-url', 'timeout-ms', 'pretty', 'help', 'version']);
+const COMMAND_OPTIONS = Object.freeze({
+  help: [],
+  version: [],
+  capabilities: [],
+  doctor: [],
+  'auth login': ['email', 'password-stdin', 'password-file', 'password-env'],
+  'auth whoami': [],
+  'auth logout': [],
+  'catalog show': [],
+  'products list': ['store-id', 'status', 'q', 'page', 'page-size'],
+  'products get': [],
+  'orders list': ['status', 'store-id', 'q', 'limit', 'cursor'],
+  'orders get': [],
+  'stores list': [],
+  'store status': [],
+  'inventory alerts': ['store-id', 'threshold'],
+  'business summary': [],
+  'business daily': ['days'],
+  'reminders status': [],
+  'reminders history': ['limit'],
+  'control export': ['kind', 'id', 'out'],
+  'control preview': ['file'],
+  'control apply': ['file', 'reason', 'idempotency-key', 'apply'],
+});
+
+const ORDER_STATUSES = new Set([
+  'active', 'making', 'history', 'refunding', 'refunded',
+  'created', 'awaiting_payment', 'paid', 'accepted', 'preparing', 'ready',
+  'completed', 'cancelled',
+]);
+
+function parseArgv(argv) {
+  if (argv[0] === '--') argv = argv.slice(1);
+  for (const token of argv) {
+    if (token === '--password' || token.startsWith('--password=') || token === '--token' || token.startsWith('--token=')) {
+      throw new CliError(
+        'SECRET_IN_ARGV',
+        'Passwords and tokens are forbidden in argv; use stdin/file/prompt/env',
+        EXIT.USAGE
+      );
+    }
+  }
+  const options = {};
+  const positionals = [];
+  for (let index = 0; index < argv.length; index += 1) {
+    const token = argv[index];
+    if (!token.startsWith('--')) {
+      positionals.push(token);
+      continue;
+    }
+    const eq = token.indexOf('=');
+    const key = token.slice(2, eq === -1 ? undefined : eq);
+    if (!key) throw new CliError('INVALID_ARGUMENT', 'Empty option name', EXIT.USAGE);
+    if (Object.hasOwn(options, key)) throw new CliError('DUPLICATE_OPTION', `Duplicate --${key}`, EXIT.USAGE);
+    if (BOOLEAN_OPTIONS.has(key)) {
+      if (eq !== -1) throw new CliError('INVALID_ARGUMENT', `--${key} does not accept a value`, EXIT.USAGE);
+      options[key] = true;
+      continue;
+    }
+    let value = eq === -1 ? argv[++index] : token.slice(eq + 1);
+    if (value === undefined || value.startsWith('--')) {
+      throw new CliError('MISSING_OPTION_VALUE', `--${key} requires a value`, EXIT.USAGE);
+    }
+    options[key] = value;
+  }
+  return { options, positionals };
+}
+
+function resolveCommand(positionals) {
+  if (!positionals.length) return { command: 'help', args: [] };
+  const one = positionals[0];
+  if (['help', 'version', 'doctor', 'capabilities'].includes(one)) {
+    return { command: one, args: positionals.slice(1) };
+  }
+  const two = positionals.slice(0, 2).join(' ');
+  if (Object.hasOwn(COMMAND_OPTIONS, two)) return { command: two, args: positionals.slice(2) };
+  throw new CliError('UNKNOWN_COMMAND', `Unknown command: ${positionals.slice(0, 2).join(' ')}`, EXIT.USAGE);
+}
+
+function validateOptions(command, options) {
+  const allowed = new Set([...GLOBAL_OPTIONS, ...(COMMAND_OPTIONS[command] || [])]);
+  for (const key of Object.keys(options)) {
+    if (!allowed.has(key)) throw new CliError('UNKNOWN_OPTION', `Unknown option for ${command}: --${key}`, EXIT.USAGE);
+  }
+}
+
+function requireNoArgs(command, args) {
+  if (args.length) throw new CliError('UNEXPECTED_ARGUMENT', `${command} accepts no positional arguments`, EXIT.USAGE);
+}
+
+function requireOneArg(command, args, label) {
+  if (args.length !== 1 || !args[0]) {
+    throw new CliError('INVALID_ARGUMENT', `${command} requires exactly one ${label}`, EXIT.USAGE);
+  }
+  return args[0];
+}
+
+function integerOption(options, key, { min, max } = {}) {
+  if (options[key] === undefined) return undefined;
+  const value = Number(options[key]);
+  if (!Number.isInteger(value) || (min !== undefined && value < min) || (max !== undefined && value > max)) {
+    const range = min !== undefined || max !== undefined ? ` (${min ?? '-∞'}..${max ?? '∞'})` : '';
+    throw new CliError('INVALID_ARGUMENT', `--${key} must be an integer${range}`, EXIT.USAGE);
+  }
+  return value;
+}
+
+function queryPath(base, pairs) {
+  const query = new URLSearchParams();
+  for (const [key, value] of pairs) {
+    if (value !== undefined && value !== null && value !== '') query.set(key, String(value));
+  }
+  const suffix = query.toString();
+  return suffix ? `${base}?${suffix}` : base;
+}
+
+async function readStdinSecret(stream) {
+  let value = '';
+  for await (const chunk of stream) {
+    value += String(chunk);
+    if (Buffer.byteLength(value, 'utf8') > 64 * 1024) {
+      throw new CliError('SECRET_TOO_LARGE', 'Password input is too large', EXIT.AUTH);
+    }
+  }
+  value = value.replace(/[\r\n]+$/, '');
+  if (!value) throw new CliError('SECRET_REQUIRED', 'Password is empty', EXIT.AUTH);
+  return value;
+}
+
+async function promptHidden(input, output) {
+  if (!input?.isTTY || typeof input.setRawMode !== 'function') {
+    throw new CliError(
+      'SECRET_SOURCE_REQUIRED',
+      'Use --password-stdin, --password-file, --password-env or an interactive TTY',
+      EXIT.AUTH
+    );
+  }
+  output.write('Password: ');
+  input.setRawMode(true);
+  input.resume();
+  return new Promise((resolve, reject) => {
+    let value = '';
+    const finish = (error) => {
+      input.off('data', onData);
+      input.setRawMode(false);
+      output.write('\n');
+      if (error) reject(error);
+      else if (!value) reject(new CliError('SECRET_REQUIRED', 'Password is empty', EXIT.AUTH));
+      else resolve(value);
+    };
+    const onData = (chunk) => {
+      const text = String(chunk);
+      for (const character of text) {
+        if (character === '\u0003') return finish(new CliError('CANCELLED', 'Login cancelled', EXIT.AUTH));
+        if (character === '\r' || character === '\n') return finish();
+        if (character === '\u007f' || character === '\b') value = value.slice(0, -1);
+        else if (character >= ' ') value += character;
+      }
+    };
+    input.on('data', onData);
+  });
+}
+
+async function resolvePassword(options, io) {
+  const explicit = ['password-stdin', 'password-file', 'password-env'].filter((key) => options[key] !== undefined);
+  if (explicit.length > 1) {
+    throw new CliError('SECRET_SOURCE_CONFLICT', 'Choose exactly one password source', EXIT.USAGE);
+  }
+  if (options['password-stdin']) return readStdinSecret(io.stdin);
+  if (options['password-file']) return readSecretFile(options['password-file']);
+  if (options['password-env']) {
+    const name = String(options['password-env']);
+    if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name)) {
+      throw new CliError('INVALID_ENV_NAME', 'password-env must name an environment variable', EXIT.USAGE);
+    }
+    const value = io.env[name];
+    if (!value) throw new CliError('SECRET_REQUIRED', 'Password environment variable is empty', EXIT.AUTH);
+    return value;
+  }
+  if (io.env.JUMBO_PASSWORD) return io.env.JUMBO_PASSWORD;
+  if (typeof io.promptSecret === 'function') return io.promptSecret();
+  return promptHidden(io.stdin, io.stderr);
+}
+
+function readControlFile(fileRaw) {
+  const file = path.resolve(String(fileRaw || ''));
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch {
+    throw new CliError('CONTROL_FILE', 'Control file could not be read', EXIT.USAGE);
+  }
+  if (stat.isSymbolicLink() || !stat.isFile() || stat.size > 1024 * 1024) {
+    throw new CliError('CONTROL_FILE', 'Control file must be a regular JSON file under 1 MiB', EXIT.USAGE);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    throw new CliError('CONTROL_FILE', 'Control file is invalid JSON', EXIT.USAGE);
+  }
+}
+
+function writeControlFile(fileRaw, document) {
+  const file = path.resolve(String(fileRaw || ''));
+  try {
+    fs.writeFileSync(file, `${JSON.stringify(document, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    fs.chmodSync(file, 0o600);
+  } catch (error) {
+    if (error?.code === 'EEXIST') {
+      throw new CliError('OUTPUT_EXISTS', 'Refusing to overwrite the output file', EXIT.USAGE);
+    }
+    throw new CliError('OUTPUT_WRITE', 'Could not write the output file', EXIT.USAGE);
+  }
+  return file;
+}
+
+function outputEnvelope(stream, value, pretty) {
+  stream.write(`${JSON.stringify(value, null, pretty ? 2 : 0)}\n`);
+}
+
+function commandHelp(command) {
+  const capability = CLI_CAPABILITIES.find((item) => item.command === command);
+  return capability ? { ...HELP, command: capability } : HELP;
+}
+
+function authContext(options, io, store) {
+  const profile = validateProfileName(options.profile || io.env.JUMBO_PROFILE || 'default');
+  const storedProfile = store.get(profile);
+  const target = resolveProfileTarget({
+    optionBaseUrl: options['base-url'],
+    envBaseUrl: io.env.JUMBO_BASE_URL,
+    envToken: io.env.JUMBO_TOKEN,
+    storedProfile,
+  });
+  const timeoutMs = integerOption(options, 'timeout-ms', { min: 500, max: 30_000 }) ?? 15_000;
+  return { profile, storedProfile, ...target, timeoutMs };
+}
+
+async function authenticatedRequest(context, io, input) {
+  if (!context.token) {
+    throw new CliError('AUTH_REQUIRED', 'Login first or provide JUMBO_TOKEN', EXIT.AUTH);
+  }
+  return requestJson({
+    ...input,
+    baseUrl: context.baseUrl,
+    token: context.token,
+    timeoutMs: context.timeoutMs,
+    fetchImpl: io.fetch,
+  });
+}
+
+export async function executeCommand({ command, args, options }, io) {
+  if (options.version || command === 'version') {
+    requireNoArgs(command, args);
+    return { version: CLI_VERSION };
+  }
+  if (options.help) return commandHelp(command);
+  if (command === 'help') {
+    requireNoArgs(command, args);
+    return HELP;
+  }
+  if (command === 'capabilities') {
+    requireNoArgs(command, args);
+    return { version: CLI_VERSION, capabilities: CLI_CAPABILITIES, controlKinds: CONTROL_KINDS };
+  }
+
+  const store = createCredentialStore({ env: io.env });
+  const profile = validateProfileName(options.profile || io.env.JUMBO_PROFILE || 'default');
+
+  if (command === 'auth logout') {
+    requireNoArgs(command, args);
+    return { profile, removed: store.remove(profile) };
+  }
+
+  if (command === 'auth login') {
+    requireNoArgs(command, args);
+    const email = String(options.email || io.env.JUMBO_EMAIL || '').trim();
+    if (!email || email.length > 200) {
+      throw new CliError('EMAIL_REQUIRED', 'auth login requires --email or JUMBO_EMAIL', EXIT.USAGE);
+    }
+    const stored = store.get(profile);
+    const baseUrl = normalizeBaseUrl(
+      options['base-url'] || io.env.JUMBO_BASE_URL || stored?.baseUrl || 'http://127.0.0.1:8787'
+    );
+    const timeoutMs = integerOption(options, 'timeout-ms', { min: 500, max: 30_000 }) ?? 15_000;
+    let password = await resolvePassword(options, io);
+    try {
+      const data = await requestJson({
+        baseUrl,
+        path: '/api/auth/staff/login',
+        method: 'POST',
+        body: { email, password },
+        timeoutMs,
+        fetchImpl: io.fetch,
+      });
+      if (!data || typeof data.token !== 'string' || !data.token || !data.staff) {
+        throw new CliError('INVALID_RESPONSE', 'Login response did not contain a staff session', EXIT.NETWORK);
+      }
+      store.set(profile, { baseUrl, token: data.token, staff: data.staff });
+      return { profile, baseUrl, staff: data.staff, permissions: data.permissions || [] };
+    } finally {
+      password = '';
+    }
+  }
+
+  const context = authContext(options, io, store);
+
+  if (command === 'doctor') {
+    requireNoArgs(command, args);
+    const health = await requestJson({
+      baseUrl: context.baseUrl,
+      path: '/api/health',
+      timeoutMs: context.timeoutMs,
+      fetchImpl: io.fetch,
+      allowBare: true,
+    });
+    let identity = null;
+    if (context.token) {
+      identity = await authenticatedRequest(context, io, { path: '/api/admin/me' });
+    }
+    return {
+      profile: context.profile,
+      baseUrl: context.baseUrl,
+      health,
+      authenticated: Boolean(identity),
+      identity,
+    };
+  }
+
+  if (command === 'auth whoami') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, { path: '/api/admin/me' });
+  }
+
+  if (command === 'catalog show') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, { path: '/api/admin/catalog' });
+  }
+
+  if (command === 'products list') {
+    requireNoArgs(command, args);
+    const status = options.status;
+    if (status && !['all', 'on', 'off'].includes(status)) {
+      throw new CliError('INVALID_ARGUMENT', '--status must be all, on or off', EXIT.USAGE);
+    }
+    return authenticatedRequest(context, io, {
+      path: queryPath('/api/admin/control-plane/products', [
+        ['storeId', options['store-id']], ['status', status], ['q', options.q],
+        ['page', integerOption(options, 'page', { min: 1 })],
+        ['pageSize', integerOption(options, 'page-size', { min: 1, max: 100 })],
+      ]),
+    });
+  }
+
+  if (command === 'products get') {
+    const id = requireOneArg(command, args, 'product id');
+    return authenticatedRequest(context, io, {
+      path: `/api/admin/control-plane/products/${encodeURIComponent(id)}`,
+    });
+  }
+
+  if (command === 'orders list') {
+    requireNoArgs(command, args);
+    if (options.status && !ORDER_STATUSES.has(options.status)) {
+      throw new CliError('INVALID_ARGUMENT', 'Unsupported order status filter', EXIT.USAGE);
+    }
+    return authenticatedRequest(context, io, {
+      path: queryPath('/api/admin/orders', [
+        ['status', options.status], ['storeId', options['store-id']], ['q', options.q],
+        ['limit', integerOption(options, 'limit', { min: 1, max: 100 })], ['cursor', options.cursor],
+      ]),
+    });
+  }
+
+  if (command === 'orders get') {
+    const id = requireOneArg(command, args, 'order id');
+    return authenticatedRequest(context, io, { path: `/api/admin/orders/${encodeURIComponent(id)}` });
+  }
+
+  if (command === 'stores list') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, { path: '/api/admin/stores' });
+  }
+
+  if (command === 'store status') {
+    const id = requireOneArg(command, args, 'store id');
+    return authenticatedRequest(context, io, {
+      path: `/api/admin/control-plane/store-status/${encodeURIComponent(id)}`,
+    });
+  }
+
+  if (command === 'inventory alerts') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, {
+      path: queryPath('/api/admin/control-plane/inventory-alerts', [
+        ['storeId', options['store-id']],
+        ['threshold', integerOption(options, 'threshold', { min: 0, max: 1_000_000 })],
+      ]),
+    });
+  }
+
+  if (command === 'business summary') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, { path: '/api/admin/dashboard' });
+  }
+
+  if (command === 'business daily') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, {
+      path: queryPath('/api/admin/analytics/daily', [
+        ['days', integerOption(options, 'days', { min: 1, max: 90 })],
+      ]),
+    });
+  }
+
+  if (command === 'reminders status') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, { path: '/api/admin/reminders/status' });
+  }
+
+  if (command === 'reminders history') {
+    requireNoArgs(command, args);
+    return authenticatedRequest(context, io, {
+      path: queryPath('/api/admin/reminders/history', [
+        ['limit', integerOption(options, 'limit', { min: 1, max: 100 })],
+      ]),
+    });
+  }
+
+  if (command === 'control export') {
+    requireNoArgs(command, args);
+    const kind = String(options.kind || '');
+    if (!CONTROL_KINDS.includes(kind)) {
+      throw new CliError('INVALID_ARGUMENT', `--kind must be one of: ${CONTROL_KINDS.join(', ')}`, EXIT.USAGE);
+    }
+    if (!options.id || !options.out) {
+      throw new CliError('INVALID_ARGUMENT', 'control export requires --kind, --id and --out', EXIT.USAGE);
+    }
+    const document = await authenticatedRequest(context, io, {
+      path: `/api/admin/control-plane/resources/${encodeURIComponent(kind)}/${encodeURIComponent(options.id)}`,
+    });
+    const file = writeControlFile(options.out, document);
+    return { file, document };
+  }
+
+  if (command === 'control preview') {
+    requireNoArgs(command, args);
+    if (!options.file) throw new CliError('INVALID_ARGUMENT', 'control preview requires --file', EXIT.USAGE);
+    const document = readControlFile(options.file);
+    return authenticatedRequest(context, io, {
+      path: '/api/admin/control-plane/preview',
+      method: 'POST',
+      body: document,
+    });
+  }
+
+  if (command === 'control apply') {
+    requireNoArgs(command, args);
+    if (!options.apply) {
+      throw new CliError('APPLY_REQUIRED', 'control apply requires explicit --apply', EXIT.USAGE);
+    }
+    if (!options.file || !options.reason || !options['idempotency-key']) {
+      throw new CliError(
+        'INVALID_ARGUMENT',
+        'control apply requires --file, --reason, --idempotency-key and --apply',
+        EXIT.USAGE
+      );
+    }
+    const document = readControlFile(options.file);
+    let result;
+    try {
+      result = await authenticatedRequest(context, io, {
+        path: '/api/admin/control-plane/apply',
+        method: 'POST',
+        body: {
+          document,
+          reason: options.reason,
+          idempotencyKey: options['idempotency-key'],
+        },
+      });
+    } catch (error) {
+      if (error instanceof CliError && error.exitCode === EXIT.NETWORK) {
+        throw new CliError(
+          'APPLY_RESULT_UNKNOWN',
+          'Apply result is unknown; retry the same file and idempotency key',
+          EXIT.CONFLICT
+        );
+      }
+      throw error;
+    }
+    const resource = result?.resource;
+    if (!resource?.kind || !resource?.targetId || !resource?.expectedRevision) {
+      throw new CliError('READBACK_FAILED', 'Apply receipt is missing its resource revision', EXIT.CONFLICT);
+    }
+    let readBack;
+    try {
+      readBack = await authenticatedRequest(context, io, {
+        path: `/api/admin/control-plane/resources/${encodeURIComponent(resource.kind)}/${encodeURIComponent(resource.targetId)}`,
+      });
+    } catch {
+      throw new CliError(
+        'READBACK_FAILED',
+        'Apply returned a receipt but the mandatory read-back could not be completed',
+        EXIT.CONFLICT
+      );
+    }
+    if (readBack?.expectedRevision !== resource.expectedRevision) {
+      throw new CliError(
+        'READBACK_FAILED',
+        'Server read-back revision does not match the apply receipt',
+        EXIT.CONFLICT,
+        { expectedRevision: resource.expectedRevision, actualRevision: readBack?.expectedRevision ?? null }
+      );
+    }
+    return { ...result, verifiedRevision: readBack.expectedRevision };
+  }
+
+  throw new CliError('UNKNOWN_COMMAND', `Unknown command: ${command}`, EXIT.USAGE);
+}
+
+export async function runCli(
+  argv = process.argv.slice(2),
+  overrides = {}
+) {
+  const io = {
+    env: process.env,
+    stdin: process.stdin,
+    stdout: process.stdout,
+    stderr: process.stderr,
+    fetch: globalThis.fetch,
+    promptSecret: undefined,
+    ...overrides,
+  };
+  let pretty = false;
+  let command = 'unknown';
+  try {
+    const parsed = parseArgv(argv);
+    const resolved = resolveCommand(parsed.positionals);
+    command = parsed.options.version ? 'version' : resolved.command;
+    pretty = Boolean(parsed.options.pretty);
+    validateOptions(command, parsed.options);
+    const data = await executeCommand({ ...resolved, options: parsed.options }, io);
+    outputEnvelope(io.stdout, { ok: true, command, data }, pretty);
+    return EXIT.OK;
+  } catch (unknownError) {
+    const error = asCliError(unknownError);
+    outputEnvelope(io.stderr, {
+      ok: false,
+      command,
+      error: {
+        code: error.code,
+        message: error.message,
+        ...(error.details === undefined ? {} : { details: error.details }),
+      },
+    }, pretty);
+    return error.exitCode;
+  }
+}

package/src/credentials.mjs

@@ -0,0 +1,185 @@
+// INPUT: OS home/XDG or JUMBO_CONFIG_DIR, profile names, staff tokens returned by the API, and optional password files.
+// OUTPUT: Symlink-resistant 0700 directory/0600 atomic credential storage plus permission-checked secret-file reads.
+// POS: Local trust boundary for `jumbo`; passwords are never persisted and Feishu secrets never enter this store.
+// PROTOCOL: Sync core.mjs, tests and docs/operations/JUMBO_CLI_FEISHU.md when path, format or permission rules change.
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomBytes } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { CliError, EXIT } from './errors.mjs';
+
+const STORE_VERSION = 1;
+const PROFILE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+const REPOSITORY_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../..');
+const REPOSITORY_ROOT_REAL = fs.realpathSync(REPOSITORY_ROOT);
+
+export function validateProfileName(raw) {
+  const value = String(raw || '').trim();
+  if (!PROFILE_RE.test(value)) {
+    throw new CliError('INVALID_PROFILE', 'Profile must use 1-64 safe characters', EXIT.USAGE);
+  }
+  return value;
+}
+
+export function resolveConfigDir(env = process.env) {
+  if (env.JUMBO_CONFIG_DIR) return path.resolve(env.JUMBO_CONFIG_DIR);
+  if (env.XDG_CONFIG_HOME) return path.resolve(env.XDG_CONFIG_HOME, 'jumbo-toast');
+  return path.join(os.homedir(), '.config', 'jumbo-toast');
+}
+
+function assertOwned(stat, label) {
+  if (typeof process.getuid === 'function' && stat.uid !== process.getuid()) {
+    throw new CliError('CREDENTIAL_OWNER', `${label} must be owned by the current user`, EXIT.AUTH);
+  }
+}
+
+function ensureDirectory(directory) {
+  fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+  const stat = fs.lstatSync(directory);
+  if (stat.isSymbolicLink() || !stat.isDirectory()) {
+    throw new CliError('CREDENTIAL_PATH', 'Credential directory must be a real directory', EXIT.AUTH);
+  }
+  assertOwned(stat, 'Credential directory');
+  fs.chmodSync(directory, 0o700);
+}
+
+function assertOutsideRepository(directory) {
+  const real = fs.realpathSync(directory);
+  if (real === REPOSITORY_ROOT_REAL || real.startsWith(`${REPOSITORY_ROOT_REAL}${path.sep}`)) {
+    throw new CliError(
+      'CREDENTIAL_LOCATION',
+      'Credential storage must stay outside the repository',
+      EXIT.AUTH
+    );
+  }
+}
+
+function safeReadJson(file) {
+  if (!fs.existsSync(file)) return { version: STORE_VERSION, profiles: {} };
+  const stat = fs.lstatSync(file);
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new CliError('CREDENTIAL_PATH', 'Credential file must be a regular file', EXIT.AUTH);
+  }
+  assertOwned(stat, 'Credential file');
+  if ((stat.mode & 0o077) !== 0) {
+    throw new CliError(
+      'CREDENTIAL_PERMISSIONS',
+      'Credential file permissions must be 0600',
+      EXIT.AUTH
+    );
+  }
+  if (stat.size > 1024 * 1024) {
+    throw new CliError('CREDENTIAL_FORMAT', 'Credential file is unexpectedly large', EXIT.AUTH);
+  }
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (parsed?.version !== STORE_VERSION || !parsed.profiles || typeof parsed.profiles !== 'object') {
+      throw new Error('shape');
+    }
+    return parsed;
+  } catch {
+    throw new CliError('CREDENTIAL_FORMAT', 'Credential file is invalid', EXIT.AUTH);
+  }
+}
+
+function atomicWrite(file, value) {
+  const directory = path.dirname(file);
+  ensureDirectory(directory);
+  const temp = path.join(directory, `.credentials.${process.pid}.${randomBytes(6).toString('hex')}.tmp`);
+  try {
+    fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, {
+      encoding: 'utf8',
+      mode: 0o600,
+      flag: 'wx',
+    });
+    fs.chmodSync(temp, 0o600);
+    fs.renameSync(temp, file);
+    fs.chmodSync(file, 0o600);
+  } finally {
+    if (fs.existsSync(temp)) fs.unlinkSync(temp);
+  }
+}
+
+export function createCredentialStore({ env = process.env } = {}) {
+  const directory = resolveConfigDir(env);
+  if (directory === REPOSITORY_ROOT || directory.startsWith(`${REPOSITORY_ROOT}${path.sep}`)) {
+    throw new CliError(
+      'CREDENTIAL_LOCATION',
+      'Credential storage must stay outside the repository',
+      EXIT.AUTH
+    );
+  }
+  const file = path.join(directory, 'credentials.json');
+
+  function readStore() {
+    ensureDirectory(directory);
+    // Resolve parent symlinks after creation; a lexically external path must not land in the repo.
+    assertOutsideRepository(directory);
+    return safeReadJson(file);
+  }
+
+  return Object.freeze({
+    directory,
+    file,
+    get(profileRaw) {
+      const profile = validateProfileName(profileRaw);
+      const value = readStore().profiles[profile];
+      if (!value || typeof value !== 'object') return null;
+      if (typeof value.baseUrl !== 'string' || typeof value.token !== 'string') {
+        throw new CliError('CREDENTIAL_FORMAT', 'Stored profile is invalid', EXIT.AUTH);
+      }
+      return { ...value };
+    },
+    set(profileRaw, value) {
+      const profile = validateProfileName(profileRaw);
+      if (!value || typeof value.baseUrl !== 'string' || typeof value.token !== 'string' || !value.token) {
+        throw new CliError('CREDENTIAL_FORMAT', 'Refusing to store an invalid profile', EXIT.AUTH);
+      }
+      const store = readStore();
+      store.profiles[profile] = {
+        baseUrl: value.baseUrl,
+        token: value.token,
+        staff: value.staff ?? null,
+        updatedAt: new Date().toISOString(),
+      };
+      atomicWrite(file, store);
+    },
+    remove(profileRaw) {
+      const profile = validateProfileName(profileRaw);
+      const store = readStore();
+      if (!Object.hasOwn(store.profiles, profile)) return false;
+      delete store.profiles[profile];
+      atomicWrite(file, store);
+      return true;
+    },
+  });
+}
+
+export function readSecretFile(fileRaw) {
+  const file = path.resolve(String(fileRaw || ''));
+  let stat;
+  try {
+    stat = fs.lstatSync(file);
+  } catch {
+    throw new CliError('SECRET_FILE', 'Password file could not be read', EXIT.AUTH);
+  }
+  if (stat.isSymbolicLink() || !stat.isFile()) {
+    throw new CliError('SECRET_FILE', 'Password file must be a regular file', EXIT.AUTH);
+  }
+  const real = fs.realpathSync(file);
+  if (real === REPOSITORY_ROOT_REAL || real.startsWith(`${REPOSITORY_ROOT_REAL}${path.sep}`)) {
+    throw new CliError('SECRET_FILE_LOCATION', 'Password file must stay outside the repository', EXIT.AUTH);
+  }
+  assertOwned(stat, 'Password file');
+  if ((stat.mode & 0o077) !== 0) {
+    throw new CliError('SECRET_FILE_PERMISSIONS', 'Password file permissions must be 0600', EXIT.AUTH);
+  }
+  if (stat.size < 1 || stat.size > 64 * 1024) {
+    throw new CliError('SECRET_FILE', 'Password file size is invalid', EXIT.AUTH);
+  }
+  const value = fs.readFileSync(file, 'utf8').replace(/[\r\n]+$/, '');
+  if (!value) throw new CliError('SECRET_REQUIRED', 'Password is empty', EXIT.AUTH);
+  return value;
+}

package/src/errors.mjs

@@ -0,0 +1,29 @@
+// INPUT: Usage, credential, HTTP, RBAC, conflict and verification failures.
+// OUTPUT: CliError carrying a stable machine code, safe message, exit code and optional non-secret details.
+// POS: Shared error taxonomy for every `jumbo` command and JSON envelope.
+// PROTOCOL: Sync capabilities.mjs, core.mjs tests and docs/operations/JUMBO_CLI_FEISHU.md when exit meanings change.
+
+export const EXIT = Object.freeze({
+  OK: 0,
+  USAGE: 2,
+  AUTH: 3,
+  FORBIDDEN: 4,
+  NETWORK: 5,
+  CONFLICT: 6,
+  INTERNAL: 70,
+});
+
+export class CliError extends Error {
+  constructor(code, message, exitCode = EXIT.INTERNAL, details = undefined) {
+    super(message);
+    this.name = 'CliError';
+    this.code = code;
+    this.exitCode = exitCode;
+    this.details = details;
+  }
+}
+
+export function asCliError(error) {
+  if (error instanceof CliError) return error;
+  return new CliError('INTERNAL_ERROR', 'Unexpected CLI failure', EXIT.INTERNAL);
+}

package/src/http.mjs

@@ -0,0 +1,181 @@
+// INPUT: Fixed relative API paths, validated profile origin, optional staff token, JSON body, timeout and injected/global fetch.
+// OUTPUT: Parsed API data with loopback-HTTP/remote-HTTPS enforcement, manual redirect rejection and safe status-to-exit mapping.
+// POS: Network trust boundary; credentials are scoped to one normalized origin and are never forwarded to redirects or caller-selected endpoints.
+// PROTOCOL: Sync core.mjs, capabilities.mjs, security tests and docs/operations/JUMBO_CLI_FEISHU.md when URL or error behavior changes.
+
+import { CliError, EXIT } from './errors.mjs';
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '::1', '[::1]']);
+const MAX_RESPONSE_BYTES = 5 * 1024 * 1024;
+
+export function normalizeBaseUrl(raw) {
+  let url;
+  try {
+    url = new URL(String(raw || ''));
+  } catch {
+    throw new CliError('INVALID_BASE_URL', 'Base URL is invalid', EXIT.USAGE);
+  }
+  if (url.username || url.password || url.search || url.hash) {
+    throw new CliError('INVALID_BASE_URL', 'Base URL cannot contain credentials, query or fragment', EXIT.USAGE);
+  }
+  if (url.pathname !== '/' && url.pathname !== '') {
+    throw new CliError('INVALID_BASE_URL', 'Base URL must be an origin without a path', EXIT.USAGE);
+  }
+  const loopback = LOOPBACK_HOSTS.has(url.hostname.toLowerCase());
+  if (url.protocol === 'http:' && !loopback) {
+    throw new CliError('HTTPS_REQUIRED', 'Remote targets require HTTPS; HTTP is loopback-only', EXIT.USAGE);
+  }
+  if (url.protocol !== 'https:' && url.protocol !== 'http:') {
+    throw new CliError('PROTOCOL_FORBIDDEN', 'Only HTTPS and loopback HTTP are allowed', EXIT.USAGE);
+  }
+  return url.origin;
+}
+
+export function resolveEndpoint(baseUrl, relativePath) {
+  const origin = normalizeBaseUrl(baseUrl);
+  if (typeof relativePath !== 'string' || !relativePath.startsWith('/api/') || relativePath.includes('://')) {
+    throw new CliError('ENDPOINT_FORBIDDEN', 'CLI endpoint is not allowlisted', EXIT.INTERNAL);
+  }
+  const pathOnly = relativePath.split('?', 1)[0];
+  if (pathOnly.split('/').includes('..')) {
+    throw new CliError('ENDPOINT_FORBIDDEN', 'CLI endpoint is not allowlisted', EXIT.INTERNAL);
+  }
+  const endpoint = new URL(relativePath, `${origin}/`);
+  if (endpoint.origin !== origin || !endpoint.pathname.startsWith('/api/')) {
+    throw new CliError('ENDPOINT_FORBIDDEN', 'CLI endpoint is not allowlisted', EXIT.INTERNAL);
+  }
+  return endpoint.toString();
+}
+
+async function readBoundedText(response) {
+  if (!response.body || typeof response.body.getReader !== 'function') {
+    const value = await response.text();
+    if (Buffer.byteLength(value, 'utf8') > MAX_RESPONSE_BYTES) {
+      throw new CliError('RESPONSE_TOO_LARGE', 'API response is too large', EXIT.NETWORK);
+    }
+    return value;
+  }
+  const reader = response.body.getReader();
+  const decoder = new TextDecoder();
+  let bytes = 0;
+  let value = '';
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) break;
+      bytes += chunk.value.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        await reader.cancel().catch(() => undefined);
+        throw new CliError('RESPONSE_TOO_LARGE', 'API response is too large', EXIT.NETWORK);
+      }
+      value += decoder.decode(chunk.value, { stream: true });
+    }
+    value += decoder.decode();
+    return value;
+  } finally {
+    reader.releaseLock();
+  }
+}
+
+function apiFailure(status, payload) {
+  const serverCode = typeof payload?.error === 'string' ? payload.error : `HTTP_${status}`;
+  const message = typeof payload?.message === 'string' ? payload.message : 'API request failed';
+  if (status === 401) return new CliError(serverCode, message, EXIT.AUTH);
+  if (status === 403) return new CliError(serverCode, message, EXIT.FORBIDDEN);
+  if (status === 409) return new CliError(serverCode, message, EXIT.CONFLICT);
+  if (status >= 400 && status < 500) {
+    return new CliError(serverCode, message, EXIT.USAGE, payload?.details);
+  }
+  return new CliError('SERVER_ERROR', 'Server request failed', EXIT.NETWORK, { status });
+}
+
+export async function requestJson({
+  baseUrl,
+  path,
+  method = 'GET',
+  token = '',
+  body,
+  timeoutMs = 15_000,
+  fetchImpl = globalThis.fetch,
+  allowBare = false,
+}) {
+  const endpoint = resolveEndpoint(baseUrl, path);
+  if (typeof fetchImpl !== 'function') {
+    throw new CliError('FETCH_UNAVAILABLE', 'Node fetch is unavailable', EXIT.INTERNAL);
+  }
+  if (!Number.isInteger(timeoutMs) || timeoutMs < 500 || timeoutMs > 30_000) {
+    throw new CliError('INVALID_TIMEOUT', 'timeout-ms must be between 500 and 30000', EXIT.USAGE);
+  }
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const headers = { accept: 'application/json' };
+    if (token) headers.authorization = `Bearer ${token}`;
+    if (body !== undefined) headers['content-type'] = 'application/json';
+    let response;
+    try {
+      response = await fetchImpl(endpoint, {
+        method,
+        headers,
+        body: body === undefined ? undefined : JSON.stringify(body),
+        signal: controller.signal,
+        redirect: 'manual',
+      });
+    } catch (error) {
+      if (error?.name === 'AbortError') {
+        throw new CliError('TIMEOUT', 'API request timed out', EXIT.NETWORK);
+      }
+      throw new CliError('NETWORK_ERROR', 'API request failed before a response', EXIT.NETWORK);
+    }
+    if (response.status >= 300 && response.status < 400) {
+      throw new CliError(
+        'REDIRECT_FORBIDDEN',
+        'API redirects are refused so credentials cannot cross origins',
+        EXIT.NETWORK
+      );
+    }
+    const contentLength = Number(response.headers?.get?.('content-length') || 0);
+    if (Number.isFinite(contentLength) && contentLength > MAX_RESPONSE_BYTES) {
+      if (response.body && typeof response.body.cancel === 'function') {
+        await response.body.cancel().catch(() => undefined);
+      }
+      throw new CliError('RESPONSE_TOO_LARGE', 'API response is too large', EXIT.NETWORK);
+    }
+    let text;
+    try {
+      text = await readBoundedText(response);
+    } catch (error) {
+      if (error instanceof CliError) throw error;
+      if (controller.signal.aborted || error?.name === 'AbortError') {
+        throw new CliError('TIMEOUT', 'API request timed out', EXIT.NETWORK);
+      }
+      throw new CliError('NETWORK_ERROR', 'API response body could not be read', EXIT.NETWORK);
+    }
+    let payload = null;
+    if (text) {
+      try {
+        payload = JSON.parse(text);
+      } catch {
+        throw new CliError('INVALID_RESPONSE', 'API returned invalid JSON', EXIT.NETWORK);
+      }
+    }
+    if (!response.ok || (!allowBare && payload?.code !== 0)) throw apiFailure(response.status, payload);
+    return allowBare ? payload : payload?.data;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function resolveProfileTarget({ optionBaseUrl, envBaseUrl, envToken, storedProfile }) {
+  const selectedBase = optionBaseUrl || envBaseUrl || storedProfile?.baseUrl || 'http://127.0.0.1:8787';
+  const baseUrl = normalizeBaseUrl(selectedBase);
+  const token = envToken || storedProfile?.token || '';
+  if (!envToken && storedProfile?.token && normalizeBaseUrl(storedProfile.baseUrl) !== baseUrl) {
+    throw new CliError(
+      'CREDENTIAL_SCOPE_MISMATCH',
+      'Stored credentials are bound to another origin; login to the selected target first',
+      EXIT.AUTH
+    );
+  }
+  return { baseUrl, token };
+}