@finebi/finebi-cli 1.2.1 → 1.3.0

package/skills/finebi-cli-agent/scripts/finebi-cli/package.json

@@ -0,0 +1,11 @@
+{
+  "name": "@finebi/finebi-cli",
+  "version": "1.3.0",
+  "private": true,
+  "description": "FineBI dynamic capability command line client.",
+  "license": "UNLICENSED",
+  "type": "module",
+  "engines": {
+    "node": ">=18.17"
+  }
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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/skills/finebi-cli-agent/scripts/finebi-cli/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;
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/auth.js

@@ -0,0 +1,116 @@
+import {cliError} from "./errors.js";
+import {failure, success} from "./output.js";
+
+export async function loginWithPassword(options) {
+  const baseUrl = options.baseUrl.replace(/\/+$/, "");
+  const controller = new AbortController();
+  const timeoutMs = options.timeoutMs || 30000;
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    const response = await (options.fetchImpl || fetch)(`${baseUrl}/login`, {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({
+        username: options.username,
+        password: options.password,
+        encrypted: false,
+        tenantId: "",
+      }),
+      signal: controller.signal,
+    });
+    return await parseLoginResponse(response, options);
+  } catch (error) {
+      return failure("auth.login", cliError("NETWORK_ERROR", {
+      path: "/login",
+      message: error instanceof Error ? error.message : String(error),
+      hint: "Check the FineBI base URL and network connection.",
+      retryable: true,
+      nextActions: ["finebi-cli config set base-url <baseUrl>", "finebi-cli auth login --username <username>"],
+      }));
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export function buildLoginAuth(options) {
+  const auth = {
+    username: options.username,
+    token: options.token,
+    loginAt: options.now(),
+    expiresAt: parseJwtExpiresAt(options.token),
+    source: options.source,
+  };
+  if (!auth.expiresAt) {
+    delete auth.expiresAt;
+  }
+  return auth;
+}
+
+export function parseJwtExpiresAt(token) {
+  const parts = token.split(".");
+  if (parts.length !== 3) {
+    return undefined;
+  }
+  try {
+    const payload = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+    if (!Number.isFinite(payload.exp)) {
+      return undefined;
+    }
+    return new Date(payload.exp * 1000).toISOString();
+  } catch (_error) {
+    return undefined;
+  }
+}
+
+export function resolveLoginInputFromEnv(env = process.env) {
+  return {
+    baseUrl: env.FINEBI_BASE_URL,
+    username: env.FINEBI_USERNAME,
+    password: env.FINEBI_PASSWORD,
+  };
+}
+
+async function parseLoginResponse(response, options) {
+  const text = await response.text();
+  const contentType = response.headers.get("content-type") || "";
+  if (!contentType.includes("json") || text.trim().startsWith("<")) {
+      return failure("auth.login", cliError("AUTH_REDIRECT_OR_HTML_RESPONSE", {
+      path: "/login",
+      message: "FineBI login returned an HTML page instead of JSON.",
+      hint: "Check that base-url points to the FineBI decision root.",
+      retryable: false,
+      nextActions: ["finebi-cli config set base-url <baseUrl>"],
+      }), {status: response.status});
+  }
+  if (!response.ok) {
+      return failure("auth.login", cliError("HTTP_ERROR", {
+      path: "/login",
+      message: `FineBI login returned HTTP ${response.status}: ${text.slice(0, 300)}`,
+      hint: "Check the username, password, and FineBI server logs.",
+      retryable: false,
+      nextActions: ["finebi-cli auth login --username <username>"],
+      }), {status: response.status});
+  }
+  const payload = JSON.parse(text);
+  const token = payload?.data?.accessToken;
+  if (!token) {
+      return failure("auth.login", cliError("LOGIN_TOKEN_NOT_FOUND", {
+      path: "data.accessToken",
+      message: "FineBI login response does not contain data.accessToken.",
+      hint: "Check whether the FineBI login endpoint contract has changed.",
+      retryable: false,
+      nextActions: ["finebi-cli auth info"],
+      }));
+  }
+  return success("auth.login", {
+    auth: buildLoginAuth({
+      username: options.username,
+      token,
+      source: "login",
+      now: options.now || (() => new Date().toISOString()),
+    }),
+  });
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/branding.js

@@ -0,0 +1,31 @@
+export const CLI_COMMAND_NAME = "finebi-cli";
+export const CLI_PACKAGE_NAME = "@finebi/finebi-cli";
+export const CLI_CONFIG_DIRECTORY = ".finebi-cli";
+export const CLI_DISPLAY_NAME = "FineBI CLI";
+
+export const CLI_LEGACY_COMMAND_NAME = "finebi-cli";
+export const CLI_API_BASE_PATH = "/api/bi-cli";
+
+export function commandLine(...parts) {
+    return [CLI_COMMAND_NAME, ...parts].filter((part) => part !== undefined && part !== null && part !== "").join(" ");
+}
+
+export function brandCommandText(value) {
+    if (typeof value !== "string") {
+        return value;
+    }
+    return value.replaceAll(CLI_LEGACY_COMMAND_NAME, CLI_COMMAND_NAME);
+}
+
+export function brandCommandValue(value) {
+    if (typeof value === "string") {
+        return brandCommandText(value);
+    }
+    if (Array.isArray(value)) {
+        return value.map((item) => brandCommandValue(item));
+    }
+    if (value && typeof value === "object") {
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, brandCommandValue(item)]));
+    }
+    return value;
+}