@finebi/finebi-cli 1.2.0 → 1.3.0

package/skills/finebi-cli-agent/scripts/finebi-cli/src/install-skill.js

@@ -0,0 +1,87 @@
+import {mkdir, readFile, writeFile, rename, open, unlink} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {homedir} from "node:os";
+import {join, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+import {createInterface} from "node:readline/promises";
+import {agentCatalog, installSkills} from "./skill-files.js";
+import {cliError} from "./errors.js";
+import {failure, success} from "./output.js";
+
+function parseOptions(args) {
+  const options = {};
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--json") continue;
+    if (arg === "--list") options.list = true;
+    else if (arg === "--replace") options.replace = true;
+    else if (arg === "--agents") {
+      if (!args[i + 1] || args[i + 1].startsWith("--")) throw new Error("--agents requires comma-separated Agent IDs.");
+      options.agents = [...new Set(args[++i].split(",").map(id => id.trim()).filter(Boolean))];
+      if (!options.agents.length) throw new Error("--agents requires at least one Agent ID.");
+    } else throw new Error(`Unknown install-skill option: ${arg}`);
+  }
+  if (options.list && (options.agents || options.replace)) throw new Error("--list cannot be combined with installation options.");
+  return options;
+}
+
+export async function handleInstallSkill(args, context = {}) {
+  const env = context.env || process.env;
+  const home = resolve(env.USERPROFILE || env.HOME || homedir());
+  const catalog = agentCatalog({home, env});
+  let options;
+  try {
+    options = parseOptions(args);
+    if (options.list) return success("install-skill", {agents: catalog});
+    if (!options.agents) {
+      const interactive = context.isTTY ?? (process.stdin.isTTY && process.stderr.isTTY);
+      if (!interactive) throw new Error("Specify --agents <ids>; use --list to see supported Agents.");
+      const prompt = createInterface({input: process.stdin, output: process.stderr});
+      try {
+        process.stderr.write(catalog.map(a => `${a.id}: ${a.name}${a.detected ? " (detected)" : ""}`).join("\n") + "\n");
+        const answer = await prompt.question("Select Agent IDs (comma-separated): ");
+        options.agents = parseOptions(["--agents", answer]).agents;
+      } finally { prompt.close(); }
+    }
+    for (const id of options.agents) if (!catalog.some(agent => agent.id === id)) throw new Error(`Unknown Agent: ${id}`);
+  } catch (error) {
+    return failure("install-skill", cliError("INVALID_ARGUMENT", {
+      message: error.message, nextActions: ["finebi-cli install-skill --help"],
+    }));
+  }
+
+  const directory = join(home, ".finebi-cli");
+  const statePath = join(directory, "installation.json");
+  const lockPath = join(directory, "skill-install.lock");
+  let lock;
+  try {
+    const npmSource = fileURLToPath(new URL("../skills/finebi-cli-agent/", import.meta.url));
+    const source = context.skillSource || (existsSync(join(npmSource, "SKILL.md"))
+      ? npmSource : fileURLToPath(new URL("../../../", import.meta.url)));
+    await readFile(join(source, "SKILL.md"));
+    await readFile(join(source, "scripts/finebi-cli/src/index.js"));
+    await mkdir(directory, {recursive: true});
+    try { lock = await open(lockPath, "wx"); }
+    catch (error) { if (error.code === "EEXIST") throw new Error(`Skill installation lock exists: ${lockPath}`); throw error; }
+    let state = {};
+    try { state = JSON.parse(await readFile(statePath, "utf8")); }
+    catch (error) { if (error.code !== "ENOENT") throw error; }
+    const results = await installSkills({source, home, env, agents: options.agents, replace: options.replace, previous: state.skills || []});
+    const skills = new Map((state.skills || []).map(skill => [skill.agent, skill]));
+    for (const skill of results) skills.set(skill.agent, {...skills.get(skill.agent), ...skill});
+    const stagedState = join(directory, "installation.json.stage");
+    await writeFile(stagedState, `${JSON.stringify({...state, skills: [...skills.values()], updatedAt: new Date().toISOString()}, null, 2)}\n`);
+    await rename(stagedState, statePath);
+    const data = {skills: results.map(({hashes, ...skill}) => skill)};
+    if (results.some(skill => !["installed", "unchanged"].includes(skill.status))) {
+      return failure("install-skill", cliError("SKILL_INSTALL_FAILED", {
+        message: "Some Skills were kept or failed. Review the results; --replace backs up and replaces local changes.", partialResult: data,
+      }));
+    }
+    return success("install-skill", data);
+  } catch (error) {
+    return failure("install-skill", cliError("SKILL_INSTALL_FAILED", {message: error.message}));
+  } finally {
+    if (lock) { await lock.close(); await unlink(lockPath); }
+  }
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/output-limits.js

@@ -0,0 +1,188 @@
+import {mkdirSync, writeFileSync} from "node:fs";
+import {dirname} from "node:path";
+
+import {cliError} from "./errors.js";
+
+// 全局输出参数：把大回包挡在上下文之外（投影 / 截断 / 落盘）。
+// 三个参数不参与命令契约，也不转发给服务端——在入口解析后即从 argv 剥离。
+export const SELECT_FLAG = "--select";
+export const MAX_CHARS_FLAG = "--max-chars";
+export const SAVE_FLAG = "--save";
+
+const FORBIDDEN_SEGMENTS = new Set(["__proto__", "constructor", "prototype"]);
+const MIN_MAX_CHARS = 200;
+
+/**
+ * 解析并剥离输出参数。
+ *
+ * @returns {{ok: true, args: string[], options: {select: string[]|null, maxChars: number|null, save: string|null}}}
+ *   或 {{ok: false, error: object}}（参数缺失/非法，调用方按失败信封渲染）
+ */
+export function parseOutputArgs(args) {
+    const rest = [];
+    const options = {select: null, maxChars: null, save: null};
+    for (let index = 0; index < args.length; index += 1) {
+        const current = args[index];
+        if (current !== SELECT_FLAG && current !== MAX_CHARS_FLAG && current !== SAVE_FLAG) {
+            rest.push(current);
+            continue;
+        }
+        const value = args[index + 1];
+        if (value === undefined || value.startsWith("-")) {
+            return {ok: false, error: argumentError(current, `Missing value for ${current}.`)};
+        }
+        index += 1;
+        if (current === SELECT_FLAG) {
+            const paths = value.split(",").map((path) => path.trim()).filter((path) => path.length > 0);
+            if (paths.length === 0 || paths.some((path) => invalidPath(path))) {
+                return {
+                    ok: false,
+                    error: argumentError(current,
+                        `${current} needs comma-separated dotted paths (e.g. data.dsl,warnings).`),
+                };
+            }
+            options.select = paths;
+        } else if (current === MAX_CHARS_FLAG) {
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed < MIN_MAX_CHARS) {
+                return {
+                    ok: false,
+                    error: argumentError(current,
+                        `${current} must be an integer >= ${MIN_MAX_CHARS}, got: ${value}.`),
+                };
+            }
+            options.maxChars = parsed;
+        } else {
+            options.save = value;
+        }
+    }
+    return {ok: true, args: rest, options};
+}
+
+/**
+ * 把响应投影到点号路径（支持数组下标，如 errors.0.message）。
+ * 投影结果恒带 ok / command 两个自描述字段，失败时给出可用键与修正指引，不做静默忽略。
+ *
+ * @returns {{ok: true, value: object}|{ok: false, error: object}}
+ */
+export function selectPaths(envelope, paths) {
+    const value = {ok: envelope.ok, command: envelope.command};
+    const missing = [];
+    for (const path of paths) {
+        const resolved = resolvePath(envelope, path);
+        if (!resolved.found) {
+            missing.push(path);
+            continue;
+        }
+        assignPath(value, path, envelope, resolved.value);
+    }
+    if (missing.length > 0) {
+        return {
+            ok: false,
+            error: argumentError(SELECT_FLAG,
+                `Unknown path(s): ${missing.join(", ")}.`,
+                `Available top-level keys: ${Object.keys(envelope).join(", ")}.`,
+                ["finebi-cli <resource> <command> --json --save <path>"]),
+        };
+    }
+    return {ok: true, value};
+}
+
+/** 超限保头尾截断：首行给出结构化标记与续读指引，中间省略段单独标记。标记开销计入预算——
+ *  截断后总长（标记 + 头 + 尾）恒不超过 maxChars，消费方可按字符数做上下文预算。 */
+export function truncateMiddle(text, maxChars) {
+    if (text.length <= maxChars) {
+        return text;
+    }
+    const header = `[finebi-cli] output truncated: ${text.length} chars total. `
+        + `Use ${SAVE_FLAG} <path> for the full output, or raise ${MAX_CHARS_FLAG}.\n`;
+    const marker = (omitted) => `\n[... ${omitted} chars omitted ...]\n`;
+    // 按总数的位数预留省略标记（省略数 ≤ 总数，位数只会更少），保证总长不越界
+    const budget = Math.max(0, maxChars - header.length - marker(text.length).length);
+    const head = Math.floor(budget * 0.6);
+    const tail = budget - head;
+    return header + text.slice(0, head) + marker(text.length - head - tail) + text.slice(text.length - tail);
+}
+
+/** 全量文本落盘（自动建父目录），返回字符数（与摘要 `chars` 字段同口径，非字节数）。 */
+export function saveOutput(text, path) {
+    mkdirSync(dirname(path), {recursive: true});
+    writeFileSync(path, text, "utf8");
+    return text.length;
+}
+
+/** 落盘后的 stdout 摘要：只回路径与计量，正文留在文件里按需读。 */
+export function savedSummary(envelope, path, chars) {
+    return `${JSON.stringify({
+        ok: envelope.ok,
+        command: envelope.command,
+        saved: path,
+        chars,
+        warnings: Array.isArray(envelope.warnings) ? envelope.warnings.length : 0,
+    }, null, 2)}\n`;
+}
+
+function resolvePath(root, path) {
+    let current = root;
+    for (const segment of path.split(".")) {
+        if (current === null || current === undefined) {
+            return {found: false};
+        }
+        if (Array.isArray(current)) {
+            if (!/^\d+$/.test(segment) || Number(segment) >= current.length) {
+                return {found: false};
+            }
+            current = current[Number(segment)];
+            continue;
+        }
+        if (typeof current !== "object" || !Object.prototype.hasOwnProperty.call(current, segment)) {
+            return {found: false};
+        }
+        current = current[segment];
+    }
+    return {found: true, value: current};
+}
+
+/** 逐段沿源结构赋值：容器形态跟随源（源是数组则投影结果也是数组，下标位置保留）。 */
+function assignPath(target, path, source, value) {
+    const segments = path.split(".");
+    let currentTarget = target;
+    let currentSource = source;
+    for (let index = 0; index < segments.length - 1; index += 1) {
+        const segment = segments[index];
+        const nextSource = Array.isArray(currentSource)
+            ? currentSource[Number(segment)]
+            : currentSource[segment];
+        if (typeof currentTarget[segment] !== "object" || currentTarget[segment] === null) {
+            currentTarget[segment] = Array.isArray(nextSource) ? [] : {};
+        }
+        currentTarget = currentTarget[segment];
+        currentSource = nextSource;
+    }
+    currentTarget[segments[segments.length - 1]] = value;
+}
+
+/** 落盘失败的参数错误：给出路径与可行动提示（不抛裸异常栈）。 */
+export function saveFailure(path, cause) {
+    return cliError("INVALID_ARGUMENT", {
+        path: SAVE_FLAG,
+        message: `Cannot write ${path}: ${cause && cause.message ? cause.message : cause}.`,
+        hint: "Check that the directory exists and is writable, or pick another path.",
+        retryable: false,
+        nextActions: [`${SAVE_FLAG} <writable-path>`],
+    });
+}
+
+function invalidPath(path) {
+    return path.split(".").some((segment) => segment.length === 0 || FORBIDDEN_SEGMENTS.has(segment));
+}
+
+function argumentError(path, message, hint, nextActions) {
+    return cliError("INVALID_ARGUMENT", {
+        path,
+        message,
+        hint: hint ?? `Run finebi-cli --help for output options.`,
+        retryable: false,
+        nextActions: nextActions ?? ["finebi-cli --help"],
+    });
+}

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

@@ -0,0 +1,33 @@
+export function success(command, data, meta = {}, warnings = [], resolved = {}) {
+  return {
+    ok: true,
+    command,
+    data,
+    errors: [],
+    warnings,
+    resolved,
+    meta,
+  };
+}
+
+export function failure(command, error, meta = {}, resolved = {}) {
+  return {
+    ok: false,
+    command,
+    data: null,
+    errors: [error],
+    warnings: [],
+    resolved,
+    meta,
+  };
+}
+
+export function maskSecret(value) {
+  if (!value) {
+    return value;
+  }
+  if (value.length <= 8) {
+    return "****";
+  }
+  return `${value.slice(0, 4)}****${value.slice(-4)}`;
+}

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

@@ -0,0 +1,158 @@
+import {closeSync, existsSync, mkdirSync, openSync, rmSync} from "node:fs";
+import {dirname, join} from "node:path";
+
+import {normalizeConfig, readConfig, writeConfigAtomically} from "./config.js";
+
+export class ProfileError extends Error {}
+
+export function validateProfileName(name) {
+  if (typeof name !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(name)) {
+    throw new ProfileError("Profile name must contain 1-64 letters, digits, underscores or hyphens and start with a letter or digit.");
+  }
+  return name;
+}
+
+export function readProfiles(path) {
+  const config = readConfig(path);
+  if (config.schemaVersion === 2) {
+    if (!config.profiles || typeof config.profiles !== "object" || Array.isArray(config.profiles)) {
+      throw new ProfileError("Invalid profiles configuration.");
+    }
+    return {multi: true, currentProfile: config.currentProfile ?? null, profiles: config.profiles};
+  }
+  // Preserve legacy session tokens when a single-environment file is migrated.
+  if (config.token && !config.auth?.token) {
+    config.auth = {...config.auth, token: config.token};
+  }
+  const present = existsSync(path);
+  return {multi: false, currentProfile: present ? "default" : null, profiles: present ? {default: config} : {}};
+}
+
+export function selectProfile(path, requested, {allowCreate = false, optional = false} = {}) {
+  const store = readProfiles(path);
+  const name = requested ?? store.currentProfile ?? (!store.multi ? "default" : null);
+  if (!name) {
+    if (optional) return null;
+    throw new ProfileError("No default environment is selected. Run finebi-cli auth use <name> or pass --profile <name>.");
+  }
+  validateProfileName(name);
+  const implicitInitial = !requested && !store.multi && !existsSync(path);
+  if (!Object.hasOwn(store.profiles, name) && !allowCreate && !implicitInitial && !optional) {
+    throw new ProfileError(`Environment '${name}' does not exist. Create it with finebi-cli auth login --profile ${name} --base-url <url>.`);
+  }
+  if (requested && !Object.hasOwn(store.profiles, name) && !allowCreate) {
+    throw new ProfileError(`Environment '${name}' does not exist.`);
+  }
+  return name;
+}
+
+export function readProfile(path, name) {
+  const store = readProfiles(path);
+  return normalizeConfig(name && Object.hasOwn(store.profiles, name) ? store.profiles[name] : {});
+}
+
+export function profileCapabilityPath(path, name) {
+  if (!name || name === "default") return path;
+  // Hex encoding preserves case-sensitive names on case-insensitive filesystems.
+  return join(dirname(path), `capabilities-profile-${Buffer.from(validateProfileName(name)).toString("hex")}.json`);
+}
+
+export function saveProfile(path, name, config, {makeCurrent = false, forceMulti = false, writer = writeConfigAtomically} = {}) {
+  validateProfileName(name);
+  return withProfileLock(path, () => {
+    const store = readProfiles(path);
+    if (!store.multi && name === "default" && !forceMulti) {
+      writer(path, config);
+      return;
+    }
+    const profiles = {...store.profiles, [name]: config};
+    writer(path, {schemaVersion: 2, currentProfile: makeCurrent ? name : store.currentProfile, profiles});
+  });
+}
+
+export function useProfile(path, name) {
+  validateProfileName(name);
+  return withProfileLock(path, () => {
+    const store = readProfiles(path);
+    if (!Object.hasOwn(store.profiles, name)) throw new ProfileError(`Environment '${name}' does not exist.`);
+    writeConfigAtomically(path, {schemaVersion: 2, currentProfile: name, profiles: store.profiles});
+  });
+}
+
+export function removeProfile(path, name) {
+  validateProfileName(name);
+  return withProfileLock(path, () => {
+    const store = readProfiles(path);
+    if (!Object.hasOwn(store.profiles, name)) {
+      if (!store.multi && name === "default") return;
+      throw new ProfileError(`Environment '${name}' does not exist.`);
+    }
+    if (!store.multi && name === "default") {
+      rmSync(path);
+      return;
+    }
+    const profiles = {...store.profiles};
+    delete profiles[name];
+    writeConfigAtomically(path, {schemaVersion: 2, currentProfile: store.currentProfile === name ? null : store.currentProfile, profiles});
+  });
+}
+
+export async function withProfileLoginLock(path, name, operation) {
+  validateProfileName(name);
+  mkdirSync(dirname(path), {recursive: true, mode: 0o700});
+  const lock = `${path}.login-${Buffer.from(name).toString("hex")}.lock`;
+  let fd;
+  try {
+    fd = openSync(lock, "wx", 0o600);
+  } catch (error) {
+    if (error.code === "EEXIST") throw new ProfileError(`An operation for environment '${name}' is already in progress. Retry after it finishes.`);
+    throw error;
+  }
+  try {
+    return await operation();
+  } finally {
+    closeSync(fd);
+    rmSync(lock, {force: true});
+  }
+}
+
+function withProfileLock(path, operation) {
+  mkdirSync(dirname(path), {recursive: true, mode: 0o700});
+  const lock = `${path}.lock`;
+  const deadline = Date.now() + 3000;
+  let fd;
+  while (fd === undefined) {
+    try {
+      fd = openSync(lock, "wx", 0o600);
+    } catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      if (Date.now() >= deadline) throw new ProfileError("Configuration is locked by another process. Retry after it finishes.");
+      Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 20);
+    }
+  }
+  try {
+    return operation();
+  } finally {
+    closeSync(fd);
+    rmSync(lock, {force: true});
+  }
+}
+
+export function parseConnectionArgs(argv) {
+  const args = [];
+  const flags = {};
+  const names = {"--profile": "profile", "--base-url": "baseUrl", "--token": "token"};
+  for (let index = 0; index < argv.length; index++) {
+    const [option, ...inline] = argv[index].split("=");
+    if (!Object.hasOwn(names, option)) {
+      args.push(argv[index]);
+      continue;
+    }
+    const value = inline.length ? inline.join("=") : argv[++index];
+    if (!value?.trim() || value.startsWith("--")) throw new ProfileError(`${option} requires a value.`);
+    const key = names[option];
+    if (Object.hasOwn(flags, key)) throw new ProfileError(`${option} must only be supplied once.`);
+    flags[key] = value.trim();
+  }
+  return {args, flags};
+}