@finebi/finebi-cli 1.4.0 → 1.5.0

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

@@ -1,158 +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};
-}
+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};
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/schema-options.js

@@ -4,11 +4,12 @@ import {cliError} from "./errors.js";
 import {validateSchemaValue} from "./schema-validator.js";
 
 export function buildRequestBody(schema, args) {
-  const parsed = parseArgs(args);
+  const properties = schema.properties || {};
+  const repeatable = new Set(Object.values(properties).map(property => property.keyValueOption).filter(Boolean));
+  const parsed = parseArgs(args, repeatable);
   if (!parsed.ok) {
     return parsed;
   }
-  const properties = schema.properties || {};
   const argumentFields = Object.keys(properties).filter((fieldName) => properties[fieldName].input === "argument");
   if (parsed.positionals.length > argumentFields.length) {
     return invalidArgument(parsed.positionals[argumentFields.length], `Unexpected argument: ${parsed.positionals[argumentFields.length]}.`);
@@ -33,10 +34,20 @@ export function buildRequestBody(schema, args) {
   for (const fieldName of Object.keys(properties)) {
     const property = properties[fieldName];
     const optionName = optionNameFor(fieldName, property);
+    const inlineValues = property.keyValueOption && parsed.options[property.keyValueOption];
+    if (inlineValues && Object.prototype.hasOwnProperty.call(parsed.options, optionName)) {
+      return invalidArgument(fieldName, `--${property.keyValueOption} and --${optionName} are mutually exclusive.`);
+    }
     if (property.input === "argument" && body[fieldName] !== undefined) {
       continue;
     }
-    if (Object.prototype.hasOwnProperty.call(parsed.options, optionName)) {
+    if (inlineValues) {
+      const coerced = coerceKeyValues(fieldName, inlineValues, property);
+      if (!coerced.ok) {
+        return coerced;
+      }
+      body[fieldName] = coerced.value;
+    } else if (Object.prototype.hasOwnProperty.call(parsed.options, optionName)) {
       const coerced = coerceValue(fieldName, parsed.options[optionName], property);
       if (!coerced.ok) {
         return coerced;
@@ -60,7 +71,8 @@ export function buildRequestBody(schema, args) {
     }
   }
   for (const optionName of Object.keys(parsed.options)) {
-    if (!Object.keys(properties).some((fieldName) => optionNameFor(fieldName, properties[fieldName]) === optionName)) {
+    if (!Object.keys(properties).some((fieldName) => optionNameFor(fieldName, properties[fieldName]) === optionName
+        || properties[fieldName].keyValueOption === optionName)) {
       return invalidArgument(`--${optionName}`, `Unknown option: --${optionName}.`);
     }
   }
@@ -75,7 +87,7 @@ export function buildRequestBody(schema, args) {
   };
 }
 
-function parseArgs(args) {
+function parseArgs(args, repeatable) {
   const options = {};
   const positionals = [];
   for (let index = 0; index < args.length; index += 1) {
@@ -86,10 +98,13 @@ function parseArgs(args) {
     }
     const optionName = current.slice(2);
     const next = args[index + 1];
-    if (next === undefined || next.startsWith("--")) {
-      options[optionName] = true;
+    const value = next === undefined || next.startsWith("--") ? true : next;
+    if (repeatable.has(optionName)) {
+      (options[optionName] ||= []).push(value);
     } else {
-      options[optionName] = next;
+      options[optionName] = value;
+    }
+    if (value !== true) {
       index += 1;
     }
   }
@@ -100,6 +115,27 @@ function parseArgs(args) {
   };
 }
 
+function coerceKeyValues(fieldName, values, property) {
+  const entries = new Map();
+  for (const value of values) {
+    const separator = typeof value === "string" ? value.indexOf("=") : -1;
+    if (separator < 1 || !value.slice(0, separator).trim() || !value.slice(separator + 1).trim()) {
+      return invalidArgument(fieldName, `--${property.keyValueOption} requires name=value with a non-empty name and value.`);
+    }
+    const name = value.slice(0, separator);
+    if (entries.has(name)) {
+      return invalidArgument(fieldName, `Duplicate name in --${property.keyValueOption}: ${name}.`);
+    }
+    entries.set(name, [value.slice(separator + 1)]);
+  }
+  const value = Object.fromEntries(entries);
+  if (property.schema) {
+    const validation = validateSchemaValue(value, property.schema, fieldName);
+    if (!validation.ok) return validation;
+  }
+  return {ok: true, value};
+}
+
 function coerceValue(fieldName, value, property) {
   if (property.input === "file" || property.file) {
     if (typeof value !== "string" || value.trim() === "") {

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

@@ -1,94 +1,94 @@
-import {createHash, randomUUID} from "node:crypto";
-import {existsSync} from "node:fs";
-import {cp, mkdir, lstat, mkdtemp, readFile, readdir, rename, rm} from "node:fs/promises";
-import {homedir} from "node:os";
-import {join, dirname, resolve} from "node:path";
-
-export function agentCatalog({home = homedir(), env = process.env} = {}) {
-  const config = env.XDG_CONFIG_HOME || join(home, ".config");
-  return [
-    ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
-    ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
-    ["cursor", "Cursor", join(home, ".cursor")],
-    ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
-    ["github-copilot", "GitHub Copilot", join(home, ".copilot")],
-    ["opencode", "OpenCode", join(config, "opencode")],
-    ["cline", "Cline", join(home, ".agents")],
-    ["windsurf", "Windsurf", join(home, ".codeium", "windsurf")],
-    ["trae", "Trae", join(home, ".trae")],
-    ["trae-cn", "Trae CN", join(home, ".trae-cn")],
-    ["openclaw", "OpenClaw", [".openclaw", ".clawdbot", ".moltbot"].map(p => join(home, p)).find(existsSync) || join(home, ".openclaw")],
-    ["roo", "Roo Code", join(home, ".roo")],
-    ["qwen-code", "Qwen Code", join(home, ".qwen")],
-  ].map(([id, name, root]) => ({id, name, directory: join(root, "skills"), detected: existsSync(root)}));
-}
-
-export async function hashTree(root, prefix = "") {
-  const files = {};
-  for (const entry of (await readdir(join(root, prefix), {withFileTypes: true})).sort((a, b) => a.name.localeCompare(b.name))) {
-    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
-    if (entry.isSymbolicLink()) throw new Error(`Skill contains a symbolic link: ${name}`);
-    if (entry.isDirectory()) Object.assign(files, await hashTree(root, name));
-    else files[name] = createHash("sha256").update(await readFile(join(root, name))).digest("hex");
-  }
-  return files;
-}
-
-function sameHashes(left, right) {
-  return left && right && Object.keys(left).length === Object.keys(right).length
-    && Object.keys(left).every(key => left[key] === right[key]);
-}
-
-export async function installSkills({source, home, env, agents, replace = false, previous = []}) {
-  const catalog = agentCatalog({home, env});
-  const selected = agents.map(id => {
-    const agent = catalog.find(item => item.id === id);
-    if (!agent) throw new Error(`Unknown Agent: ${id}`);
-    return agent;
-  });
-  const sourceHashes = await hashTree(source);
-  const results = [];
-  for (const agent of selected) {
-    const target = join(agent.directory, "finebi-cli-agent");
-    let backup;
-    let candidate;
-    try {
-      const stat = await lstat(target).catch(error => { if (error.code !== "ENOENT") throw error; });
-      if (stat) {
-        if (stat.isSymbolicLink()) throw new Error("Skill target is a symbolic link; refusing to replace it.");
-        const actual = await hashTree(target);
-        if (sameHashes(sourceHashes, actual)) {
-          results.push({agent: agent.id, path: target, status: "unchanged", hashes: sourceHashes});
-          continue;
-        }
-        const recorded = previous.find(item => item.agent === agent.id && item.path === target)?.hashes;
-        if (!replace && !sameHashes(recorded, actual)) {
-          results.push({agent: agent.id, path: target, status: "kept"});
-          continue;
-        }
-        backup = join(home, ".finebi-cli", "skill-backups", `${agent.id}-${randomUUID()}`);
-        await mkdir(dirname(backup), {recursive: true});
-        await cp(target, backup, {recursive: true, errorOnExist: true, force: false});
-        if (!sameHashes(actual, await hashTree(backup))) throw new Error("Skill backup integrity check failed.");
-      }
-      await mkdir(agent.directory, {recursive: true});
-      candidate = await mkdtemp(join(agent.directory, ".finebi-cli-stage-"));
-      await cp(source, candidate, {recursive: true});
-      if (!sameHashes(sourceHashes, await hashTree(candidate))) throw new Error("Skill copy integrity check failed.");
-      const old = `${candidate}-old`;
-      if (stat) await rename(target, old);
-      try { await rename(candidate, target); }
-      catch (error) { if (stat) await rename(old, target); throw error; }
-      candidate = undefined;
-      // Delete only the relocated, backed-up directory inside this Agent's skills directory.
-      if (stat && backup && dirname(resolve(old)) === resolve(agent.directory)) await rm(old, {recursive: true});
-      if (!sameHashes(sourceHashes, await hashTree(target))) throw new Error("Installed Skill integrity check failed.");
-      results.push({agent: agent.id, path: target, status: "installed", hashes: sourceHashes, ...(backup ? {backup} : {})});
-    } catch (error) {
-      results.push({agent: agent.id, path: target, status: "failed", error: error.message, ...(backup ? {backup} : {})});
-    } finally {
-      if (candidate && dirname(resolve(candidate)) === resolve(agent.directory)) await rm(candidate, {recursive: true, force: true});
-    }
-  }
-  return results;
-}
+import {createHash, randomUUID} from "node:crypto";
+import {existsSync} from "node:fs";
+import {cp, mkdir, lstat, mkdtemp, readFile, readdir, rename, rm} from "node:fs/promises";
+import {homedir} from "node:os";
+import {join, dirname, resolve} from "node:path";
+
+export function agentCatalog({home = homedir(), env = process.env} = {}) {
+  const config = env.XDG_CONFIG_HOME || join(home, ".config");
+  return [
+    ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
+    ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
+    ["cursor", "Cursor", join(home, ".cursor")],
+    ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
+    ["github-copilot", "GitHub Copilot", join(home, ".copilot")],
+    ["opencode", "OpenCode", join(config, "opencode")],
+    ["cline", "Cline", join(home, ".agents")],
+    ["windsurf", "Windsurf", join(home, ".codeium", "windsurf")],
+    ["trae", "Trae", join(home, ".trae")],
+    ["trae-cn", "Trae CN", join(home, ".trae-cn")],
+    ["openclaw", "OpenClaw", [".openclaw", ".clawdbot", ".moltbot"].map(p => join(home, p)).find(existsSync) || join(home, ".openclaw")],
+    ["roo", "Roo Code", join(home, ".roo")],
+    ["qwen-code", "Qwen Code", join(home, ".qwen")],
+  ].map(([id, name, root]) => ({id, name, directory: join(root, "skills"), detected: existsSync(root)}));
+}
+
+export async function hashTree(root, prefix = "") {
+  const files = {};
+  for (const entry of (await readdir(join(root, prefix), {withFileTypes: true})).sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) throw new Error(`Skill contains a symbolic link: ${name}`);
+    if (entry.isDirectory()) Object.assign(files, await hashTree(root, name));
+    else files[name] = createHash("sha256").update(await readFile(join(root, name))).digest("hex");
+  }
+  return files;
+}
+
+function sameHashes(left, right) {
+  return left && right && Object.keys(left).length === Object.keys(right).length
+    && Object.keys(left).every(key => left[key] === right[key]);
+}
+
+export async function installSkills({source, home, env, agents, replace = false, previous = []}) {
+  const catalog = agentCatalog({home, env});
+  const selected = agents.map(id => {
+    const agent = catalog.find(item => item.id === id);
+    if (!agent) throw new Error(`Unknown Agent: ${id}`);
+    return agent;
+  });
+  const sourceHashes = await hashTree(source);
+  const results = [];
+  for (const agent of selected) {
+    const target = join(agent.directory, "finebi-cli-agent");
+    let backup;
+    let candidate;
+    try {
+      const stat = await lstat(target).catch(error => { if (error.code !== "ENOENT") throw error; });
+      if (stat) {
+        if (stat.isSymbolicLink()) throw new Error("Skill target is a symbolic link; refusing to replace it.");
+        const actual = await hashTree(target);
+        if (sameHashes(sourceHashes, actual)) {
+          results.push({agent: agent.id, path: target, status: "unchanged", hashes: sourceHashes});
+          continue;
+        }
+        const recorded = previous.find(item => item.agent === agent.id && item.path === target)?.hashes;
+        if (!replace && !sameHashes(recorded, actual)) {
+          results.push({agent: agent.id, path: target, status: "kept"});
+          continue;
+        }
+        backup = join(home, ".finebi-cli", "skill-backups", `${agent.id}-${randomUUID()}`);
+        await mkdir(dirname(backup), {recursive: true});
+        await cp(target, backup, {recursive: true, errorOnExist: true, force: false});
+        if (!sameHashes(actual, await hashTree(backup))) throw new Error("Skill backup integrity check failed.");
+      }
+      await mkdir(agent.directory, {recursive: true});
+      candidate = await mkdtemp(join(agent.directory, ".finebi-cli-stage-"));
+      await cp(source, candidate, {recursive: true});
+      if (!sameHashes(sourceHashes, await hashTree(candidate))) throw new Error("Skill copy integrity check failed.");
+      const old = `${candidate}-old`;
+      if (stat) await rename(target, old);
+      try { await rename(candidate, target); }
+      catch (error) { if (stat) await rename(old, target); throw error; }
+      candidate = undefined;
+      // Delete only the relocated, backed-up directory inside this Agent's skills directory.
+      if (stat && backup && dirname(resolve(old)) === resolve(agent.directory)) await rm(old, {recursive: true});
+      if (!sameHashes(sourceHashes, await hashTree(target))) throw new Error("Installed Skill integrity check failed.");
+      results.push({agent: agent.id, path: target, status: "installed", hashes: sourceHashes, ...(backup ? {backup} : {})});
+    } catch (error) {
+      results.push({agent: agent.id, path: target, status: "failed", error: error.message, ...(backup ? {backup} : {})});
+    } finally {
+      if (candidate && dirname(resolve(candidate)) === resolve(agent.directory)) await rm(candidate, {recursive: true, force: true});
+    }
+  }
+  return results;
+}

package/skills/finebi-cli-agent/scripts/finebi-cli-runner.mjs

@@ -10,10 +10,10 @@ const scriptDirectory = dirname(fileURLToPath(import.meta.url));
 const bundledCliEntry = resolve(scriptDirectory, "finebi-cli", "src", "index.js");
 
 export async function run(argv = process.argv.slice(2), options = {}) {
-  const env = {...(options.env ?? process.env)};
-  if (!env.FINEBI_CLI_PATH?.trim() && existsSync(bundledCliEntry)) {
-    env.FINEBI_CLI_PATH = bundledCliEntry;
-  }
+  const env = {...(options.env ?? process.env)};
+  if (!env.FINEBI_CLI_PATH?.trim() && existsSync(bundledCliEntry)) {
+    env.FINEBI_CLI_PATH = bundledCliEntry;
+  }
   return runCore(argv, {...options, env});
 }