@finebi/finebi-cli 1.2.0

package/README.md

@@ -0,0 +1,312 @@
+# FineBI CLI
+
+FineBI CLI is a dynamic command line client for FineBI plugin capabilities. It handles local config, username/password login, capability cache, `--help/-h`, and HTTP command forwarding.
+
+Array options take a JSON array as one argument, for example `--values '["上海","江苏"]'` for geographic matching. The CLI parses the array and validates its item schema before sending the request; comma-separated text is not an array.
+
+## Install
+
+```powershell
+npm install -g @finebi/finebi-cli --registry=https://registry.npmjs.org/
+```
+
+For local development, prefer `npm link` from this `cli` directory:
+
+```powershell
+cd D:\project\ino-7.0\nuclear-all\plugin-bi-finecli\cli
+npm link
+finebi-cli --help
+```
+
+After `npm link`, edits under `src` are picked up by the global `finebi-cli` command without linking again. If `finebi-cli` was installed from a packed `.tgz`, rebuild and reinstall the package after code changes:
+
+```powershell
+cd D:\project\ino-7.0\nuclear-all\plugin-bi-finecli\cli
+npm run pack:cli
+npm install -g .\finebi-finebi-cli-1.0.0.tgz
+```
+
+On Windows, use `where finebi-cli` if the command does not appear to update. Multiple Node.js/npm installations can leave more than one global command shim on `PATH`.
+
+## Publish an Update
+
+Publish from this `cli` directory. A published npm version is immutable, so increment the version before every release. Make and commit the functional changes first, then run the following release checks and version update:
+
+```powershell
+cd D:\project\ino-7.0\nuclear-all\plugin-bi-finecli\cli
+npm test
+npm run verify:pack
+npm version patch --no-git-tag-version
+```
+
+Use `patch` for bug fixes, `minor` for backward-compatible features, and `major` for breaking changes. `npm version` updates both `package.json` and `package-lock.json`. Review and commit the release version with a Chinese Conventional Commit message, then log in with an npm account authorized to publish under `@finebi`. The package publishes publicly to the official npm registry:
+
+```powershell
+git add package.json package-lock.json
+git commit -m "chore(cli): 发布 1.0.1"
+npm login --registry=https://registry.npmjs.org/
+npm publish --registry=https://registry.npmjs.org/ --access public
+```
+
+After a successful publish, verify the registry version and install it. Public package installation does not require npm authentication:
+
+```powershell
+npm view @finebi/finebi-cli version --registry=https://registry.npmjs.org/
+npm install -g @finebi/finebi-cli@latest --registry=https://registry.npmjs.org/
+finebi-cli version
+```
+
+## Testing
+
+Run these commands from the repository root. On Windows PowerShell use `npm.cmd`; on Linux/macOS use `npm`:
+
+```powershell
+npm.cmd --prefix cli test
+npm.cmd --prefix cli run test:integration:stub
+```
+
+Linux/macOS：
+
+```bash
+npm --prefix cli test
+npm --prefix cli run test:integration:stub
+```
+
+For a real FineBI environment, use the corresponding integration script:
+
+Windows PowerShell：
+
+```powershell
+npm.cmd --prefix cli run test:integration:readonly
+npm.cmd --prefix cli run test:integration:mutating
+npm.cmd --prefix cli run test:integration:real
+```
+
+Linux/macOS：
+
+```bash
+npm --prefix cli run test:integration:readonly
+npm --prefix cli run test:integration:mutating
+npm --prefix cli run test:integration:real
+```
+
+### Real integration prerequisites
+
+Before running a real FineBI test, configure all of the following:
+
+- `cli/tests/fixtures/finebi-integration-environment.json`: set `ready` to `true`, and provide a reachable HTTP(S) `baseUrl`, the test `username`, a positive `revision`, and `passwordSource` pointing to `FINEBI_INTEGRATION_PASSWORD`. `reportDir` may be a relative default or an absolute path.
+- `cli/tests/fixtures/capabilities/`: keep the per-resource snapshots valid and synchronized with the deployed plugin/environment. The commands and request schemas in real cases are checked against this Capability snapshot (aggregated by `fixtures/capabilities/load.js`).
+- `cli/tests/real-cases/*.json`: enable at least one case with `enabled: true`. Readonly cases must use `mutation: false` commands; mutating cases must declare scoped cleanup for resources created by that case.
+- FineBI: deploy the plugin version corresponding to the current source and verify that the configured account can log in and access the required resources. Run mutating cases only in a dedicated test environment.
+- Credentials: inject the password through the environment variable before starting the test. `xxxx` below is only a placeholder and must be replaced locally or by CI Secret injection.
+
+Windows PowerShell:
+
+```powershell
+$env:FINEBI_INTEGRATION_PASSWORD = 'xxxx'
+```
+
+Linux/macOS:
+
+```bash
+export FINEBI_INTEGRATION_PASSWORD='xxxx'
+```
+
+Do not commit the real value or place it in case JSON, CLI arguments, logs, or reports. If `--report-dir` is supplied, it must be an existing writable absolute directory; `--case` can narrow the run to one enabled case. See the complete [CLI testing guide](../docs/cli-testing/20260804-finebi-real-integration/cli-testing-guide.md) for platform-specific setup, real-case authoring with the `finebi-cli-case-authoring` skill, cleanup rules, and report troubleshooting.
+
+## Usage
+
+Built-in help is always available and does not require server config, login, or a capability refresh:
+
+```powershell
+finebi-cli --help
+finebi-cli --help --json
+finebi-cli config set --help
+finebi-cli auth login --help
+finebi-cli capability refresh --help
+finebi-cli version --help
+finebi-cli capabilities --help
+finebi-cli config --help
+finebi-cli auth --help
+finebi-cli capability --help
+```
+
+Dynamic resource help, such as `finebi-cli <resource> --help`, is loaded from the FineBI capability cache. Login refreshes this cache automatically:
+
+```powershell
+finebi-cli config set base-url http://localhost:37799/webroot/decision
+finebi-cli auth login --username 1
+finebi-cli version
+finebi-cli --help
+finebi-cli <resource> --help
+finebi-cli <resource> <command> [options]
+```
+
+Run `finebi-cli capability refresh` manually when backend commands changed, the cache expired, or you want to force a reload.
+
+### Multiple environments
+
+Create an environment by logging in with its name and address:
+
+```powershell
+finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser
+finebi-cli auth login --profile prod --base-url https://prod.example.com/webroot/decision --username admin --password-stdin
+finebi-cli auth list
+finebi-cli auth use test
+finebi-cli capability info --profile prod
+finebi-cli auth info --profile prod
+finebi-cli config set timeout-ms 60000 --profile prod
+finebi-cli auth logout --profile prod
+finebi-cli auth remove prod
+```
+
+Successful login selects that environment as the default; add `--no-use` to keep the existing default. Login to an existing name reuses its address unless overridden. A new name requires `--base-url` or `FINEBI_BASE_URL` and never inherits another environment's identity. Failed authentication leaves existing environments and the default unchanged.
+
+Selection order is `--profile` > `FINEBI_PROFILE` > saved default. The option works before or after the command. Ordinary commands never create missing environments or change the default. Names are case-sensitive, 1–64 ASCII letters/digits/underscores/hyphens, beginning with a letter or digit. `auth list` shows local metadata only, not a live authentication check. JSON responses identify the selected environment in `meta.profile`.
+
+Each environment has separate credentials, connection settings and capabilities. Changing its saved `base-url` clears its credentials and cache. Temporary URL/token overrides do not change saved configuration; a different URL never inherits saved credentials. Requests with temporary credentials fetch capabilities for that invocation without overwriting a saved cache. Explicit session tokens take precedence over saved Access Keys.
+
+`auth logout` revokes the selected environment's saved Key and keeps its connection settings. `auth remove <name>` and `config clear --profile <name>` delete only that local environment and cache, without revoking server credentials. Removing the default does not automatically select another saved environment. Persistent configuration and logout operations use the selected saved environment, not connection override variables.
+
+Existing single-environment configuration is exposed as `default`; read-only commands do not rewrite it. Multi-environment writes migrate it while preserving its credentials and default capability cache. See the [command contract](../docs/commands/README.md#多环境管理) for the complete behavior.
+
+## Access Key
+
+After a successful `auth login`, the CLI automatically issues a long-lived Access Key so commands keep working after the short-lived session token (JWT) expires:
+
+- Login provisions a key with description `finebi-cli@<hostname>` for `default`, or `finebi-cli@<hostname>/<profile>` for a named environment, replacing stale keys with the same description. The plaintext key is stored in the environment's `auth.accessKey` and never printed. On POSIX systems, the CLI enforces mode `0700` on the config directory and `0600` on `config.json`. On Windows, it removes inherited ACLs and grants access only to the current user, SYSTEM, and Administrators; failures emit a security warning.
+- Business commands send `X-FineBI-CLI-Access-Key` when a key is present, and fall back to the session token otherwise.
+- Add `--no-access-key` to `auth login` to skip issuance and stay on the session token.
+- `auth info` shows `authMode` (`access-key` / `session-token` / `none`) with both the session token and Access Key masked.
+- `auth logout` revokes the server-side key via `self-revoke` (works even after the JWT expired), then clears local credentials. If revocation fails, credentials are preserved for retry; use `auth logout --force` only when local credentials must be removed without confirmed server revocation.
+
+```powershell
+finebi-cli auth login --username 1
+finebi-cli auth login --username 1 --no-access-key
+finebi-cli auth info
+finebi-cli auth logout
+finebi-cli auth logout --force
+```
+
+Agent discovery flow:
+
+```powershell
+finebi-cli --help --json
+finebi-cli config set base-url http://localhost:37799/webroot/decision
+finebi-cli auth login --from-env
+finebi-cli <resource> --help --json
+finebi-cli <resource> <command> [options] --json
+```
+
+For complex file-based resources, do not expect command help to contain a complete source example. `widget template` returns a Widget JS DSL source template selected by chart type and scenario; `dashboard template` returns a Dashboard JS DSL example script with named placeholders and a variable contract. Their `add` and `update` commands accept JS DSL source files. Other resources may still expose writable JSON templates according to their dynamic command help.
+
+## Agent Skills
+
+Use the `finebi-cli` skill when an Agent needs to operate this CLI. The skill should follow the discovery flow above and treat dynamic command help as the source of truth after capability refresh.
+
+Use the `finebi-cli-command-designer` skill for command design work: new command groups, schema changes, response contracts, help output, and design markdown. Command-specific business rules should be designed in the command document and implemented on the backend; the CLI should only interpret field-level rules declared in the capability schema.
+
+## Output
+
+FineBI CLI keeps two audiences in mind:
+
+- Human-facing built-in commands print concise text by default.
+- Agent and script integrations can add `--json` to get the full JSON envelope.
+- Dynamic business commands use backend capability display hints for human-readable output by default.
+- Dynamic business commands can use `-f, --format` for display formats supported by the command shape.
+- `--json` has priority over display formats and always returns the full JSON envelope.
+
+Large responses can be narrowed before they reach the caller (all three are CLI-side only — they are
+stripped from the command arguments and never forwarded to the plugin):
+
+- `--select <paths>` projects the response onto comma-separated dotted paths (arrays use indexes,
+  e.g. `data.dsl,warnings,errors.0.message`). Output is always JSON and keeps `ok` / `command`;
+  an unknown path fails loud with the available top-level keys instead of printing a partial result.
+- `--max-chars <n>` keeps the head and tail of long output with explicit truncation markers
+  (total/omitted character counts plus how to get the full text). The cap is inclusive: markers
+  count against it, so the truncated output never exceeds `n` characters.
+- `--save <path>` writes the full JSON envelope (projected when `--select` is used — the human
+  rendering is lossy, so files always hold the complete response) and prints only a short summary:
+  `ok` / `command` / `saved` / `chars` / `warnings`. `--save` wins over `--max-chars` (the summary
+  is already tiny); a failed write reports `INVALID_ARGUMENT` with the path instead of a stack trace.
+
+A command that fails is never projected (its `data` is null, so projection would hide the real error
+behind `Unknown path(s)`); `--select` implies JSON output, including for its own argument errors.
+Failed commands are still saved when `--save` is present — the file holds the failure envelope, so
+scripted consumers never read a stale success from a previous run.
+
+```powershell
+finebi-cli dashboard dsl --id <id> --select data.dsl,warnings
+finebi-cli dashboard bean --id <id> --save temp/board.json
+finebi-cli subject info --id <id> --json --max-chars 8000
+```
+
+Human-friendly defaults:
+
+```powershell
+finebi-cli version
+finebi-cli config get
+finebi-cli auth info
+finebi-cli capability info
+finebi-cli config clear
+finebi-cli auth logout
+finebi-cli capability clear-cache
+```
+
+Structured output:
+
+```powershell
+finebi-cli version --json
+finebi-cli config get --json
+finebi-cli auth info --json
+finebi-cli capability info --json
+finebi-cli <resource> <command> [options] --json
+```
+
+Dynamic display formats:
+
+```powershell
+finebi-cli <resource> <command> [options] -f auto
+finebi-cli <resource> <command> [options] -f table
+finebi-cli <resource> <command> [options] -f expanded
+finebi-cli <resource> <command> [options] -f csv
+```
+
+Dynamic shapes are `record-list`, `detail`, `tabular-preview`, and `generic`. Java capability metadata declares only the shape and the default format used by `auto`. Node.js renders these shapes generically from the response data, preserving the returned information instead of hardcoding business command names or command-specific columns.
+
+Environment login:
+
+```powershell
+$env:FINEBI_BASE_URL="http://localhost:37799/webroot/decision"
+$env:FINEBI_USERNAME="1"
+$env:FINEBI_PASSWORD="your-password"
+finebi-cli auth login --from-env
+```
+
+Successful login also attempts to refresh the dynamic capability cache. If the refresh fails, login still succeeds and the CLI prints a warning with `finebi-cli capability refresh` as the follow-up action.
+
+Browser authorization login:
+
+```powershell
+finebi-cli auth login --browser
+```
+
+This prints a same-server confirmation URL and code to stderr. Sign in through the existing FineBI browser entry first, then open the URL and confirm the code. The CLI only sends the browser authorization request fields and saves the returned Access Key after approval; it does not send an existing local credential to the authorization endpoints.
+
+Pipe password through stdin:
+
+```powershell
+echo your-password | finebi-cli auth login --username 1 --password-stdin
+```
+
+## Local Files
+
+- Config: `%USERPROFILE%\.finebi-cli\config.json`
+- Capability cache: `%USERPROFILE%\.finebi-cli\capabilities.json`
+- Named environment caches: `%USERPROFILE%\.finebi-cli\capabilities-profile-<hex-encoded-name>.json` (`default` uses `capabilities.json`).
+
+Multi-environment `config.json` stores `schemaVersion: 2`, `currentProfile` (nullable), and a `profiles` object keyed by environment name. Writes are serialized with a short-lived `config.json.lock` and atomically replace the configuration file. A lock timeout reports an error without modifying the file.
+
+Concurrent logins to the same environment are rejected using `config.json.login-<hex-encoded-name>.lock`; different environments may log in concurrently. Locks are released when the operation settles. If a process is forcibly terminated and leaves a lock behind, verify that the owning operation has stopped before manually removing that lock file.
+
+Passwords are not persisted by the CLI.

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@finebi/finebi-cli",
+  "version": "1.2.0",
+  "description": "FineBI dynamic capability command line client.",
+  "license": "UNLICENSED",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "type": "module",
+  "bin": {
+    "finebi-cli": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "test": "npm run test:unit && npm run test:process && npm run test:contract && npm run test:integration:stub",
+    "test:unit": "node --test tests/unit/access-key.test.js tests/unit/auth.test.js tests/unit/capability.test.js tests/unit/config-permissions.test.js tests/unit/config.test.js tests/unit/dynamic-command-forwarding.test.js tests/unit/dynamic-command-multipart.test.js tests/unit/dynamic-command-preflight.test.js tests/unit/error-catalog-loader.test.js tests/unit/error-catalog.test.js tests/unit/error-construction-guard.test.js tests/unit/help.test.js tests/unit/http-stub.test.js tests/unit/index-auth-login.test.js tests/unit/index-auth-session.test.js tests/unit/index-browser-auth.test.js tests/unit/index-config.test.js tests/unit/index-dynamic-errors.test.js tests/unit/index-dynamic-render.test.js tests/unit/index-help.test.js tests/unit/index-profiles.test.js tests/unit/output-limits.test.js tests/unit/output.test.js tests/unit/package.test.js tests/unit/schema-options-capability.test.js tests/unit/schema-options-file-input.test.js tests/unit/schema-options-scalar.test.js",
+    "test:process": "node --test tests/process/bench-cli-runner.test.js tests/process/process-cli.test.js tests/process/profiles-cli.test.js",
+    "test:contract": "node --test tests/contract/capability-contract.test.js",
+    "test:integration:stub": "node --test tests/integration/analysis-ds-workflows.test.js tests/integration/assertions.test.js tests/integration/auth-system.test.js tests/integration/case-loader.test.js tests/integration/cli-process.test.js tests/integration/config.test.js tests/integration/dashboard-workflows.test.js tests/integration/entry.test.js tests/integration/failure-security.test.js tests/integration/file-template.test.js tests/integration/mutating-file-input.test.js tests/integration/mutating-resource-ledger.test.js tests/integration/mutating-workflow-guards.test.js tests/integration/readonly-assertions.test.js tests/integration/readonly-file-input.test.js tests/integration/readonly-workflow-contract.test.js tests/integration/report-directory.test.js tests/integration/report-entry.test.js tests/integration/report-secrets.test.js tests/integration/report-summary-artifacts.test.js tests/integration/runner.test.js",
+    "test:integration:readonly": "node tests/integration/entry.js readonly",
+    "test:integration:mutating": "node tests/integration/entry.js mutating",
+    "test:integration:real": "node tests/integration/entry.js all",
+    "prebench": "npm test",
+    "bench": "node bench/src/runner.js",
+    "prepack:cli": "npm test",
+    "pack:cli": "npm pack",
+    "preverify:pack": "npm test",
+    "verify:pack": "npm pack --dry-run"
+  }
+}

package/src/access-key-contract.js

@@ -0,0 +1,2 @@
+export const ACCESS_KEY_BASE_PATH = "/api/bi-cli/access-key";
+export const ACCESS_KEY_HEADER_NAME = "X-BI-CLI-Access-Key";

package/src/access-key.js

@@ -0,0 +1,174 @@
+import {failure, success} from "./output.js";
+import {ACCESS_KEY_BASE_PATH} from "./access-key-contract.js";
+import {authenticationFailure} from "./auth-failure.js";
+import {buildAuthHeaders} from "./auth-headers.js";
+import {cliError} from "./errors.js";
+
+
+/**
+ * 创建 Access Key。使用 JWT 登录态(Cookie/Bearer)认证，服务端据 Cookie 识别当前用户。
+ * 校验响应中含 token/id，防止契约漂移时把无效响应当成功。
+ */
+export async function createAccessKey(options) {
+  const query = options.description ? `?description=${encodeURIComponent(options.description)}` : "";
+  const envelope = await sendAccessKeyRequest({
+    ...options,
+    command: "access-key.create",
+    method: "POST",
+    endpoint: `${ACCESS_KEY_BASE_PATH}/create${query}`,
+  });
+  if (!envelope.ok) {
+    return envelope;
+  }
+  const key = envelope.data;
+  if (!key || !key.token || !key.id) {
+    return failure("access-key.create", cliError("ACCESS_KEY_CREATE_INVALID", {
+      path: "data.token",
+      message: "Access Key create response did not contain a token.",
+      hint: "Check the FineBI CLI plugin version and access-key endpoint contract.",
+      retryable: false,
+      nextActions: ["finebi-cli auth info"],
+    }));
+  }
+  return success("access-key.create", key);
+}
+
+/**
+ * 列出当前用户(管理员为全部)的 Access Key。响应不含 token 明文。
+ */
+export async function listAccessKeys(options) {
+  return sendAccessKeyRequest({
+    ...options,
+    command: "access-key.list",
+    method: "GET",
+    endpoint: `${ACCESS_KEY_BASE_PATH}/list`,
+  });
+}
+
+/**
+ * 按 id 删除 Access Key。
+ */
+export async function deleteAccessKey(options) {
+  return sendAccessKeyRequest({
+    ...options,
+    command: "access-key.delete",
+    method: "POST",
+    endpoint: `${ACCESS_KEY_BASE_PATH}/delete?id=${encodeURIComponent(options.id)}`,
+  });
+}
+
+/**
+ * 自撤销：用 X-BI-CLI-Access-Key 头调 /self-revoke 删除自己出示的这把 key。
+ * 认证方式为「出示 key 即证明持有」，不依赖 JWT 登录态，适用于 JWT 过期后 logout 撤销。
+ */
+export async function selfRevokeAccessKey(options) {
+  return sendAccessKeyRequest({
+    ...options,
+    command: "access-key.self-revoke",
+    method: "POST",
+    endpoint: `${ACCESS_KEY_BASE_PATH}/self-revoke`,
+  });
+}
+
+/**
+ * 删旧建新：列出同 description 的旧 Key 并删除，再创建一把新 Key。
+ * list 失败时停止签发，避免无法确认旧 Key 状态却继续创建而产生重复；旧 Key 删除失败逐条告警。
+ */
+export async function provisionAccessKey(options) {
+  const warnings = [];
+  const listed = await listAccessKeys(options);
+  if (listed.ok) {
+    const existing = Array.isArray(listed.data?.tokens) ? listed.data.tokens : [];
+    const stale = existing.filter((item) => isStaleKeyForCurrentUser(item, options));
+    for (const item of stale) {
+      const removed = await deleteAccessKey({ ...options, id: item.id });
+      if (!removed.ok) {
+        warnings.push(cliError("ACCESS_KEY_STALE_DELETE_FAILED", {
+          message: `Failed to delete a stale Access Key (id=${item.id}).`,
+          id: item.id,
+          cause: removed.errors?.[0],
+        }));
+      }
+    }
+  } else {
+    warnings.push(cliError("ACCESS_KEY_LIST_FAILED", {
+      message: "Could not list existing Access Keys; issuance was stopped to avoid creating a duplicate.",
+      cause: listed.errors?.[0],
+    }));
+    return { created: listed, warnings };
+  }
+  const created = await createAccessKey(options);
+  return { created, warnings };
+}
+
+function isStaleKeyForCurrentUser(item, options) {
+  if (!options.username || !item?.id || item.description !== options.description) {
+    return false;
+  }
+  // 管理员 list 可能返回所有用户；缺少当前用户名时宁可保留旧 Key，也不能误删他人的 Key。
+  return item.username === options.username;
+}
+
+async function sendAccessKeyRequest(options) {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs || 30000);
+  try {
+    const response = await (options.fetchImpl || fetch)(`${baseUrl}${options.endpoint}`, {
+      method: options.method,
+      headers: buildAuthHeaders(options),
+      signal: controller.signal,
+    });
+    return await parseAccessKeyResponse(response, options.command, options.endpoint);
+  } catch (error) {
+    return failure(options.command, cliError("NETWORK_ERROR", {
+      path: options.endpoint,
+      message: error instanceof Error ? error.message : String(error),
+      hint: "Check the FineBI base URL and network connection.",
+      retryable: true,
+      nextActions: ["finebi-cli auth info"],
+    }));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function parseAccessKeyResponse(response, command, path) {
+  const text = await response.text();
+  if (response.ok && (response.status === 204 || text.trim() === "")) {
+    return success(command, null);
+  }
+  const contentType = response.headers.get("content-type") || "";
+  if (!contentType.includes("json") || text.trim().startsWith("<")) {
+    return failure(command, cliError("AUTH_REDIRECT_OR_HTML_RESPONSE", {
+      path,
+      message: "FineBI returned an HTML login or redirect page instead of JSON.",
+      hint: "Run finebi-cli auth login and retry.",
+      retryable: true,
+      nextActions: ["finebi-cli auth login"],
+    }), { status: response.status });
+  }
+  if (!response.ok) {
+    if (response.status === 401 || response.status === 403) {
+      return authenticationFailure(command, path, response.status);
+    }
+    return failure(command, cliError("HTTP_ERROR", {
+      path,
+      message: `FineBI returned HTTP ${response.status}: ${text.slice(0, 300)}`,
+      hint: "Check FineBI server logs and access-key endpoint availability.",
+      retryable: false,
+      nextActions: ["finebi-cli auth info"],
+    }), { status: response.status });
+  }
+  const payload = JSON.parse(text);
+  if (payload && payload.errorCode) {
+    return failure(command, cliError("ACCESS_KEY_ERROR", {
+      path,
+      message: payload.errorMsg || String(payload.errorCode),
+      hint: "Check the username, permissions, and access-key endpoint.",
+      retryable: false,
+      nextActions: ["finebi-cli auth info"],
+    }), { status: response.status });
+  }
+  return success(command, payload.data ?? null);
+}

package/src/auth-failure.js

@@ -0,0 +1,18 @@
+import {cliError} from "./errors.js";
+import {failure} from "./output.js";
+
+/**
+ * 将 401/403 统一映射为可恢复的认证错误。
+ *
+ * Access Key 被撤销或失效时，业务接口与 capability 接口必须给出相同的重新签发入口，
+ * 不能落入“检查服务端日志”一类无法自助恢复的通用 HTTP 提示。
+ */
+export function authenticationFailure(command, path, status) {
+  return failure(command, cliError("AUTHENTICATION_FAILED", {
+    path,
+    message: `FineBI rejected the authentication credentials with HTTP ${status}.`,
+    hint: "Run finebi-cli auth login and retry.",
+    retryable: true,
+    nextActions: ["finebi-cli auth login"],
+  }), { status });
+}

package/src/auth-headers.js

@@ -0,0 +1,21 @@
+import { ACCESS_KEY_HEADER_NAME } from "./access-key-contract.js";
+
+/**
+ * 统一构造 FineBI CLI 认证请求头。
+ *
+ * Access Key 与平台登录态互斥：一旦存在 CLI Access Key，只发送插件专属 Header；
+ * 否则才回退到 Bearer + Cookie，避免调用方各自实现后产生双认证或旧 Header 漂移。
+ */
+export function buildAuthHeaders({ token, accessKey, contentType }) {
+  const headers = { Accept: "application/json" };
+  if (contentType) {
+    headers["Content-Type"] = contentType;
+  }
+  if (accessKey) {
+    headers[ACCESS_KEY_HEADER_NAME] = accessKey;
+  } else if (token) {
+    headers.Authorization = `Bearer ${token}`;
+    headers.Cookie = `fine_auth_token=${token}`;
+  }
+  return headers;
+}