@finebi/finebi-cli 1.2.1 → 1.3.0

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

@@ -0,0 +1,399 @@
+#!/usr/bin/env node
+
+import {spawn} from "node:child_process";
+import {createHash} from "node:crypto";
+import {existsSync, readFileSync} from "node:fs";
+import {delimiter, dirname, extname, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+
+const SENSITIVE_OPTION_PATTERN = /PASSWORD|TOKEN|COOKIE|SECRET|ACCESS[_-]?KEY|AUTH/i;
+const SENSITIVE_ENV_PATTERN = /(?:^|[_-])(?:PASSWORD|TOKEN|COOKIE|SECRET|ACCESS[_-]?KEY|AUTHORIZATION)(?:$|[_-])/i;
+const VALUELESS_SENSITIVE_OPTIONS = new Set(["--password-stdin", "--no-access-key"]);
+
+export async function run(argv = process.argv.slice(2), options = {}) {
+    const selected = extractProfile(argv);
+    argv = selected.argv;
+    const {mode, resource, command, commandArgv} = parseArguments(argv);
+    const env = {...(options.env ?? process.env), ...(selected.profile ? {FINEBI_PROFILE: selected.profile} : {})};
+    const cwd = options.cwd ?? process.cwd();
+    const invocation = resolveCliInvocation(env, cwd);
+
+    if (mode === "inspect") {
+        return inspectCommand({invocation, resource, command, cwd, env});
+    }
+    if (command === "template") {
+        return executeReadOnlyTemplate({invocation, resource, command, commandArgv, cwd, env});
+    }
+    return executeCommand({invocation, commandArgv, cwd, env});
+}
+
+function extractProfile(argv) {
+    const remaining = [];
+    let profile;
+    for (let index = 0; index < argv.length; index++) {
+        const arg = argv[index];
+        if (arg !== "--profile" && !arg.startsWith("--profile=")) {
+            remaining.push(arg);
+            continue;
+        }
+        if (profile !== undefined) throw new Error("--profile must only be supplied once.");
+        profile = arg === "--profile" ? argv[++index] : arg.slice("--profile=".length);
+        if (!profile || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/.test(profile)) throw new Error("--profile requires a valid environment name.");
+    }
+    return {argv: remaining, profile};
+}
+
+export function parseArguments(argv) {
+    const [mode, ...rest] = argv;
+    if (mode === "inspect" && rest.length === 2) {
+        return {mode, resource: rest[0], command: rest[1], commandArgv: null};
+    }
+    if (mode === "run" && rest.length >= 3 && rest.includes("--json")) {
+        return {mode, resource: rest[0], command: rest[1], commandArgv: rest};
+    }
+    throw new Error("Usage: finebi-cli-runner.mjs inspect <resource> <command> | run <resource> <command> [...args] --json");
+}
+
+export function resolveCliInvocation(env = process.env, cwd = process.cwd()) {
+    const configuredPath = env.FINEBI_CLI_PATH?.trim();
+    if (configuredPath) {
+        const cliPath = resolve(cwd, configuredPath);
+        if (!existsSync(cliPath)) {
+            throw new Error(`FINEBI_CLI_PATH does not exist: ${cliPath}`);
+        }
+        return invocationForPath(cliPath);
+    }
+
+    const cliPath = findExecutableOnPath(env.PATH || "");
+    if (!cliPath) {
+        throw new Error("FineBI CLI is not installed on PATH. Install @finebi/finebi-cli or set FINEBI_CLI_PATH to its executable or JavaScript entry file.");
+    }
+    return invocationForPath(cliPath);
+}
+
+function findExecutableOnPath(pathValue) {
+    const names = process.platform === "win32"
+        ? ["finebi-cli.exe", "finebi-cli.cmd", "finebi-cli.bat", "finebi-cli"]
+        : ["finebi-cli"];
+    for (const directory of pathValue.split(delimiter).filter(Boolean)) {
+        const normalizedDirectory = directory.replace(/^"|"$/g, "");
+        for (const name of names) {
+            const candidate = resolve(normalizedDirectory, name);
+            if (existsSync(candidate)) return candidate;
+        }
+    }
+    return null;
+}
+
+function invocationForPath(cliPath) {
+    const extension = extname(cliPath).toLowerCase();
+    if ([".js", ".mjs", ".cjs"].includes(extension)) {
+        return {executable: process.execPath, prefixArgs: [cliPath], displayCommand: "finebi-cli"};
+    }
+    if (extension === ".cmd" || extension === ".bat") {
+        return {
+            executable: process.execPath,
+            prefixArgs: [resolveNodeEntryFromWindowsShim(cliPath)],
+            displayCommand: "finebi-cli",
+        };
+    }
+    return {executable: cliPath, prefixArgs: [], displayCommand: "finebi-cli"};
+}
+
+function resolveNodeEntryFromWindowsShim(shimPath) {
+    const content = readFileSync(shimPath, "utf8");
+    const matches = [...content.matchAll(/%(?:~dp0|dp0%)([^"\r\n]*?\.(?:c|m)?js)/giu)];
+    const relativeEntry = matches.at(-1)?.[1];
+    if (!relativeEntry) {
+        throw new Error(`Cannot resolve the JavaScript entry from ${shimPath}. Set FINEBI_CLI_PATH to the installed FineBI CLI JavaScript entry file.`);
+    }
+    const entryPath = resolve(dirname(shimPath), relativeEntry.replace(/^[\\/]+/u, ""));
+    if (!existsSync(entryPath)) {
+        throw new Error(`FineBI CLI JavaScript entry does not exist: ${entryPath}`);
+    }
+    return entryPath;
+}
+
+export function projectCapability(cache, resourceName, commandName) {
+    const manifest = cache?.manifest;
+    const resource = manifest?.resources?.find((item) => item?.name === resourceName);
+    const command = resource?.commands?.find((item) => item?.name === commandName);
+    if (!command) {
+        throw new Error(`Capability does not contain ${resourceName}.${commandName}.`);
+    }
+    return {
+        fetchedAt: cache.fetchedAt ?? null,
+        expiresAt: cache.expiresAt ?? null,
+        ttlMs: cache.ttlMs ?? null,
+        schemaVersion: manifest.schemaVersion ?? null,
+        capabilityFingerprint: createHash("sha256").update(JSON.stringify(manifest)).digest("hex"),
+        resource: resourceName,
+        command: commandName,
+        summary: command.summary ?? null,
+        method: command.method ?? null,
+        path: command.path ?? null,
+        mutation: command.mutation === true,
+    };
+}
+
+async function inspectCommand({invocation, resource, command, cwd, env}) {
+    const capabilityResult = await runCli(invocation, ["capability", "info", "--json"], cwd, env);
+    if (!capabilityResult.envelope?.ok) {
+        return reportFailure("inspect", capabilityResult, invocation);
+    }
+    const capability = projectCapability(capabilityResult.envelope.data?.cache, resource, command);
+    const helpArgv = [resource, command, "--help", "--json"];
+    const helpResult = await runCli(invocation, helpArgv, cwd, env);
+    if (!helpResult.envelope?.ok) {
+        return reportFailure("inspect", helpResult, invocation, capability);
+    }
+    return {
+        ok: true,
+        mode: "inspect",
+        capability,
+        help: projectHelp(helpResult.envelope.data),
+        executions: [
+            cliExecution(invocation, capabilityResult),
+            cliExecution(invocation, helpResult),
+        ],
+    };
+}
+
+export function projectHelp(help) {
+    return {
+        resource: help?.resource ?? null,
+        command: help?.command ?? null,
+        summary: help?.summary ?? null,
+        usage: help?.usage ?? null,
+        options: Array.isArray(help?.options) ? help.options.map((option) => ({
+            name: option.name ?? null,
+            required: option.required === true,
+            type: option.type ?? null,
+            default: option.default ?? null,
+        })) : [],
+        display: help?.display ?? null,
+        requestSchema: compactSchema(help?.requestSchema, 0),
+        responseSchema: compactSchema(help?.responseSchema, 0),
+    };
+}
+
+function compactSchema(schema, depth) {
+    if (!schema || typeof schema !== "object") return null;
+    const projected = {
+        type: schema.type ?? null,
+        required: Array.isArray(schema.required) ? schema.required : [],
+    };
+    if (Array.isArray(schema.enumValues) && schema.enumValues.length > 0) {
+        projected.enumValues = schema.enumValues;
+    }
+    if (schema.file === true) projected.file = true;
+    if (typeof schema.input === "string" && schema.input) projected.input = schema.input;
+    if (schema.nullable === true) projected.nullable = true;
+    if (schema.items && typeof schema.items === "object") {
+        projected.items = compactSchema(schema.items, depth + 1);
+    }
+    if (schema.schema && typeof schema.schema === "object") {
+        projected.schema = compactSchema(schema.schema, depth + 1);
+    }
+    const properties = schema.properties && typeof schema.properties === "object" ? schema.properties : null;
+    if (properties) {
+        projected.properties = Object.fromEntries(Object.entries(properties).map(([name, property]) => {
+            if (depth >= 2) return [name, {type: property?.type ?? null}];
+            return [name, compactSchema(property, depth + 1)];
+        }));
+    }
+    return projected;
+}
+
+async function executeReadOnlyTemplate({invocation, resource, command, commandArgv, cwd, env}) {
+    const capabilityResult = await runCli(invocation, ["capability", "info", "--json"], cwd, env);
+    if (!capabilityResult.envelope?.ok) {
+        return reportFailure("run", capabilityResult, invocation);
+    }
+    const capability = projectCapability(capabilityResult.envelope.data?.cache, resource, command);
+    if (capability.mutation) {
+        return {
+            ok: false,
+            mode: "run",
+            capability,
+            execution: cliExecution(invocation, capabilityResult),
+            error: {
+                code: "TEMPLATE_MUTATION_FORBIDDEN",
+                message: resource + "." + command + " is not read-only in the current capability.",
+            },
+        };
+    }
+    const result = await executeCommand({invocation, commandArgv, cwd, env});
+    return {...result, capability, preflight: cliExecution(invocation, capabilityResult)};
+}
+
+async function executeCommand({invocation, commandArgv, cwd, env}) {
+    const result = await runCli(invocation, commandArgv, cwd, env);
+    return {
+        ok: result.envelope?.ok === true && result.exitCode === 0,
+        mode: "run",
+        execution: cliExecution(invocation, result),
+        envelope: result.envelope,
+        stderr: result.stderr || "",
+    };
+}
+
+function runCli(invocation, argv, cwd, env) {
+    return new Promise((resolvePromise) => {
+        const startMs = Date.now();
+        const sensitiveValues = collectSensitiveValues(argv, env);
+        const child = spawn(invocation.executable, [...invocation.prefixArgs, ...argv], {
+            cwd,
+            env,
+            shell: false,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        let spawnError = null;
+        let timeoutHandle;
+
+        const finish = (exitCode) => {
+            if (settled) return;
+            settled = true;
+            clearTimeout(timeoutHandle);
+            const safeStdout = redactText(stdout, sensitiveValues);
+            const safeStderr = redactText(stderr, sensitiveValues);
+            let envelope = null;
+            try {
+                envelope = JSON.parse(safeStdout.trim());
+            } catch (_error) {
+                envelope = null;
+            }
+            resolvePromise({
+                argv: redactArgv(argv),
+                exitCode: exitCode ?? 1,
+                durationMs: Date.now() - startMs,
+                timedOut,
+                spawnError: spawnError ? redactText(spawnError.message, sensitiveValues) : null,
+                stdout: safeStdout,
+                stderr: safeStderr,
+                envelope,
+            });
+        };
+
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk;
+        });
+        child.once("error", (error) => {
+            spawnError = error;
+            finish(1);
+        });
+        child.once("close", finish);
+        timeoutHandle = setTimeout(() => {
+            timedOut = true;
+            stderr += "FineBI CLI timed out after 30000 ms.\n";
+            child.kill();
+        }, 30000);
+    });
+}
+
+function collectSensitiveValues(argv, env) {
+    const values = [];
+    for (const [name, value] of Object.entries(env)) {
+        if (SENSITIVE_ENV_PATTERN.test(name) && value) values.push(String(value));
+    }
+    for (let index = 0; index < argv.length; index += 1) {
+        const argument = String(argv[index]);
+        const equalsIndex = argument.indexOf("=");
+        if (equalsIndex > 0 && isSensitiveOption(argument.slice(0, equalsIndex))) {
+            values.push(argument.slice(equalsIndex + 1));
+        } else if (isSensitiveOption(argument) && !VALUELESS_SENSITIVE_OPTIONS.has(argument.toLowerCase()) && index + 1 < argv.length) {
+            values.push(String(argv[index + 1]));
+            index += 1;
+        }
+    }
+    return [...new Set(values.filter(Boolean))].sort((left, right) => right.length - left.length);
+}
+
+function redactArgv(argv) {
+    const safeArgv = argv.map(String);
+    for (let index = 0; index < safeArgv.length; index += 1) {
+        const argument = safeArgv[index];
+        const equalsIndex = argument.indexOf("=");
+        if (equalsIndex > 0 && isSensitiveOption(argument.slice(0, equalsIndex))) {
+            safeArgv[index] = `${argument.slice(0, equalsIndex + 1)}[REDACTED]`;
+        } else if (isSensitiveOption(argument) && !VALUELESS_SENSITIVE_OPTIONS.has(argument.toLowerCase()) && index + 1 < safeArgv.length) {
+            safeArgv[index + 1] = "[REDACTED]";
+            index += 1;
+        }
+    }
+    return safeArgv;
+}
+
+function isSensitiveOption(argument) {
+    return /^-{1,2}[^-]/.test(argument) && SENSITIVE_OPTION_PATTERN.test(argument);
+}
+
+function redactText(text, sensitiveValues) {
+  let safeText = text || "";
+  for (const value of sensitiveValues) safeText = redactBoundedSecret(safeText, value);
+  return safeText;
+}
+
+function redactBoundedSecret(text, secret) {
+  let safeText = "";
+  let cursor = 0;
+  let matchIndex = text.indexOf(secret);
+  while (matchIndex !== -1) {
+    const matchEnd = matchIndex + secret.length;
+    const left = matchIndex === 0 ? "" : text[matchIndex - 1];
+    const right = matchEnd === text.length ? "" : text[matchEnd];
+    const hasTokenBoundaries = !isProtocolIdentifierChar(left) && !isProtocolIdentifierChar(right);
+    safeText += text.slice(cursor, hasTokenBoundaries ? matchIndex : matchEnd);
+    if (hasTokenBoundaries) safeText += "[REDACTED]";
+    cursor = matchEnd;
+    matchIndex = text.indexOf(secret, cursor);
+  }
+  return safeText + text.slice(cursor);
+}
+
+function isProtocolIdentifierChar(character) {
+  return character !== "" && /[\p{L}\p{N}_-]/u.test(character);
+}
+
+function cliExecution(invocation, result) {
+    return {
+        argv: [invocation.displayCommand, ...result.argv],
+        exitCode: result.exitCode,
+        durationMs: result.durationMs,
+        timedOut: result.timedOut,
+    };
+}
+
+function reportFailure(mode, result, invocation, capability = null) {
+    return {
+        ok: false,
+        mode,
+        capability,
+        execution: cliExecution(invocation, result),
+        error: {
+            code: result.timedOut ? "CLI_TIMEOUT" : "CLI_EXECUTION_FAILED",
+            message: result.stderr || result.spawnError || "FineBI CLI execution failed.",
+        },
+    };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    try {
+        const result = await run();
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+        process.exitCode = result.ok ? 0 : 1;
+    } catch (error) {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+        process.exitCode = 1;
+    }
+}

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

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import {existsSync} from "node:fs";
+import {dirname, resolve} from "node:path";
+import {fileURLToPath} from "node:url";
+
+import {run as runCore} from "./finebi-cli-runner-core.mjs";
+
+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;
+  }
+  return runCore(argv, {...options, env});
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  try {
+    const result = await run();
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    process.exitCode = result.ok ? 0 : 1;
+  } catch (error) {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exitCode = 1;
+  }
+}

package/src/error-catalog.js

@@ -1,4 +1,16 @@
 export const ERROR_CATALOG = [
+    {
+        code: "SKILL_INSTALL_FAILED",
+        layer: "node",
+        origin: "install-skill",
+        category: "configuration",
+        recoverableByAgent: false,
+        defaultRetryable: false,
+        pathSemantics: "Local Skill directory or installation record",
+        canonicalNextActions: ["finebi-cli install-skill --help"],
+        expectedAgentBehaviors: ["inspect the installation result and preserve local edits", "request explicit replacement before overwriting local changes"],
+        benchmarkTags: ["skills", "installation"],
+    },
     {
         code: "BROWSER_AUTH_URL_INVALID",
         layer: "node",

package/src/help.js

@@ -99,6 +99,20 @@ function findResource(manifest, resourceName) {
 }
 
 const BUILT_IN_RESOURCES = {
+  "install-skill": {
+    command: "install-skill",
+    resource: "install-skill",
+    summary: "Install or update the bundled FineBI Skill in Agent directories without a server connection.",
+    usage: "finebi-cli install-skill [--agents <ids>] [--replace]",
+    options: [
+      {name: "--agents", type: "string", description: "Comma-separated Agent IDs; required outside an interactive terminal."},
+      {name: "--list", type: "boolean", description: "List supported Agents and their installation directories without writing files."},
+      {name: "--replace", type: "boolean", description: "Back up and replace locally modified or untracked Skill installations."},
+    ],
+    details: ["Unmodified managed installations update automatically with a backup. Local changes are kept by default.",
+      "No server credentials are needed. Restart your Agent or refresh its Skills after installation."],
+    examples: ["finebi-cli install-skill --agents codex,cursor", "finebi-cli install-skill --list"],
+  },
   version: {
     command: "version",
     resource: "version",
@@ -344,6 +358,7 @@ function renderTopLevelHelpText(data) {
     "",
     "Common Commands:",
       `  ${commandLine("version")}`,
+      `  ${commandLine("install-skill", "--agents", "codex")}`,
       `  ${commandLine("capabilities")}`,
       `  ${commandLine("config", "get")}`,
       `  ${commandLine("config", "set", "base-url", "<baseUrl>")}`,

package/src/index.js

@@ -18,6 +18,7 @@ import {defaultConfigPath, maskConfig, resolveConfig, sameBaseUrl, updateConfigV
 import {parseConnectionArgs, ProfileError, profileCapabilityPath, readProfile, readProfiles, removeProfile, saveProfile, selectProfile, useProfile, withProfileLoginLock} from "./profiles.js";
 import {loginWithPassword, resolveLoginInputFromEnv} from "./auth.js";
 import {executeDynamicCommand} from "./dynamic-command.js";
+import {handleInstallSkill} from "./install-skill.js";
 import {cliError} from "./errors.js";
 import {
     renderBuiltInCommandHelp,
@@ -44,6 +45,9 @@ export async function runCli(argv, context = {}) {
   try {
     const {args, flags} = parseConnectionArgs(argv);
     const env = context.env || process.env;
+    if (args[0] === "install-skill") {
+      return isHelpFlagInvocation(args) ? renderBuiltInHelp("install-skill") : handleInstallSkill(args.slice(1), context);
+    }
     const management = args[0] === "auth" && ["list", "use", "remove"].includes(args[1]);
     const builtInHelp = isHelpFlagInvocation(args) && (args.length === 1 || isBuiltInResource(args[0]));
     const optional = management || builtInHelp || args.length === 0 || args[0] === "version";
@@ -671,7 +675,8 @@ async function handleHelp(args, context) {
 }
 
 function isBuiltInResource(resourceName) {
-  return resourceName === "config"
+  return resourceName === "install-skill"
+      || resourceName === "config"
       || resourceName === "auth"
       || resourceName === "capability"
       || resourceName === "version"

package/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); }
+  }
+}