@finebi/finebi-cli 1.5.0 → 1.6.1

package/src/config.js

@@ -56,23 +56,23 @@ export function writeConfigAtomically(path, config, options = {}) {
   }
 }
 
-export function resolveConfig(flags = {}, env = process.env, fileConfig = readConfig()) {
-  const baseUrl = firstNonEmpty(flags.baseUrl, env.FINEBI_BASE_URL, fileConfig.baseUrl);
-  const sameServer = sameBaseUrl(baseUrl, fileConfig.baseUrl);
-  const explicitToken = firstNonEmpty(flags.token, env.FINEBI_AUTH_TOKEN);
-  const savedAuth = sameServer ? fileConfig.auth : undefined;
-  const token = firstNonEmpty(explicitToken, savedAuth?.token, sameServer ? fileConfig.token : undefined);
+export function resolveConfig(flags = {}, env = process.env, fileConfig = readConfig()) {
+  const baseUrl = firstNonEmpty(flags.baseUrl, env.FINEBI_BASE_URL, fileConfig.baseUrl);
+  const sameServer = sameBaseUrl(baseUrl, fileConfig.baseUrl);
+  const explicitToken = firstNonEmpty(flags.token, env.FINEBI_AUTH_TOKEN);
+  const savedAuth = sameServer ? fileConfig.auth : undefined;
+  const token = firstNonEmpty(explicitToken, savedAuth?.token, sameServer ? fileConfig.token : undefined);
   return normalizeConfig({
     ...fileConfig,
-    baseUrl,
+    baseUrl,
     timeoutMs: parsePositiveInt(firstNonEmpty(flags.timeoutMs, env.FINEBI_TIMEOUT_MS), fileConfig.timeoutMs),
     capabilityTtlMs: parsePositiveInt(
       firstNonEmpty(flags.capabilityTtlMs, env.FINEBI_CAPABILITY_TTL_MS),
       fileConfig.capabilityTtlMs,
     ),
     auth: {
-      ...(explicitToken ? {} : savedAuth),
-      token,
+      ...(explicitToken ? {} : savedAuth),
+      token,
     },
   });
 }
@@ -81,10 +81,10 @@ export function updateConfigValue(config, key, value, now = () => new Date().toI
   const next = normalizeConfig(config);
   switch (key) {
     case "base-url":
-      if (next.baseUrl !== value) {
-        next.capabilityCacheInvalidatedAt = now();
-        delete next.auth;
-        delete next.token;
+      if (next.baseUrl !== value) {
+        next.capabilityCacheInvalidatedAt = now();
+        delete next.auth;
+        delete next.token;
       }
       next.baseUrl = value;
       return next;
@@ -128,7 +128,7 @@ function defaultConfig() {
   };
 }
 
-export function normalizeConfig(config) {
+export function normalizeConfig(config) {
   return {
     ...config,
     timeoutMs: parsePositiveInt(config.timeoutMs, DEFAULT_TIMEOUT_MS),
@@ -136,14 +136,14 @@ export function normalizeConfig(config) {
   };
 }
 
-function sanitizeConfig(config) {
-  if (config.schemaVersion === 2) {
-    return {
-      schemaVersion: 2,
-      currentProfile: config.currentProfile,
-      profiles: Object.fromEntries(Object.entries(config.profiles).map(([name, profile]) => [name, sanitizeConfig(normalizeConfig(profile))])),
-    };
-  }
+function sanitizeConfig(config) {
+  if (config.schemaVersion === 2) {
+    return {
+      schemaVersion: 2,
+      currentProfile: config.currentProfile,
+      profiles: Object.fromEntries(Object.entries(config.profiles).map(([name, profile]) => [name, sanitizeConfig(normalizeConfig(profile))])),
+    };
+  }
   const { token: _legacyToken, ...rest } = config;
   const auth = config.auth
     ? {
@@ -166,11 +166,11 @@ function sanitizeConfig(config) {
     ...rest,
     auth,
   };
-}
-
-export function sameBaseUrl(left, right) {
-  return (left || "").replace(/\/+$/, "") === (right || "").replace(/\/+$/, "");
-}
+}
+
+export function sameBaseUrl(left, right) {
+  return (left || "").replace(/\/+$/, "") === (right || "").replace(/\/+$/, "");
+}
 
 function firstNonEmpty(...values) {
   return values.find((value) => typeof value === "string" && value.trim().length > 0)?.trim();

package/src/help.js

@@ -1,12 +1,12 @@
 import {brandCommandValue, CLI_COMMAND_NAME, CLI_DISPLAY_NAME, commandLine} from "./branding.js";
 import {cliError} from "./errors.js";
-import {failure, success} from "./output.js";
-
-const GLOBAL_OPTIONS = [
-  {name: "--profile", type: "string", description: "Environment name. Overrides FINEBI_PROFILE and the saved default; ordinary commands do not create environments or switch the default."},
-  {name: "--base-url", type: "string", description: "Connection URL override. A different server never inherits saved credentials or capabilities."},
-  {name: "--token", type: "string", description: "Temporary session token override; not persisted."},
-];
+import {failure, success} from "./output.js";
+
+const GLOBAL_OPTIONS = [
+  {name: "--profile", type: "string", description: "Environment name. Overrides FINEBI_PROFILE and the saved default; ordinary commands do not create environments or switch the default."},
+  {name: "--base-url", type: "string", description: "Connection URL override. A different server never inherits saved credentials or capabilities."},
+  {name: "--token", type: "string", description: "Temporary session token override; not persisted."},
+];
 
 export function renderTopLevelHelp(manifest) {
   return success("help", {
@@ -14,8 +14,8 @@ export function renderTopLevelHelp(manifest) {
       name: resource.name,
       summary: resource.summary,
     })),
-    dynamicCapabilitiesLoaded: Boolean(manifest),
-    globalOptions: GLOBAL_OPTIONS,
+    dynamicCapabilitiesLoaded: Boolean(manifest),
+    globalOptions: GLOBAL_OPTIONS,
   }, { schemaVersion: manifest?.schemaVersion });
 }
 
@@ -24,7 +24,7 @@ export function renderBuiltInHelp(resourceName) {
   if (!resource) {
     return capabilityNotFound(resourceName);
   }
-    return success("help", brandCommandValue({...resource, globalOptions: GLOBAL_OPTIONS}));
+    return success("help", brandCommandValue({...resource, globalOptions: GLOBAL_OPTIONS}));
 }
 
 export function renderBuiltInCommandHelp(resourceName, commandName) {
@@ -38,8 +38,8 @@ export function renderBuiltInCommandHelp(resourceName, commandName) {
     command: command.name,
     summary: command.summary,
     usage: command.usage,
-    options: command.options || [],
-    globalOptions: GLOBAL_OPTIONS,
+    options: command.options || [],
+    globalOptions: GLOBAL_OPTIONS,
     details: command.details || [],
     examples: command.examples || [],
     }));
@@ -52,8 +52,8 @@ export function renderResourceHelp(manifest, resourceName) {
   }
   return success("help", {
     resource: resource.name,
-    summary: resource.summary,
-    globalOptions: GLOBAL_OPTIONS,
+    summary: resource.summary,
+    globalOptions: GLOBAL_OPTIONS,
     commands: (resource.commands || []).map((command) => ({
       name: command.name,
       summary: command.summary,
@@ -72,8 +72,8 @@ export function renderCommandHelp(manifest, resourceName, commandName) {
     command: command.name,
     summary: command.summary,
     usage: usageFor(resource.name, command),
-    options: commandOptionsFor(command),
-    globalOptions: GLOBAL_OPTIONS,
+    options: commandOptionsFor(command),
+    globalOptions: GLOBAL_OPTIONS,
     display: command.display,
     requestSchema: command.requestSchema,
     responseSchema: command.responseSchema,
@@ -99,6 +99,30 @@ function findResource(manifest, resourceName) {
 }
 
 const BUILT_IN_RESOURCES = {
+  app: {
+    resource: "app",
+    summary: "Create and inspect local FineBI dynamic web app projects without a server connection.",
+    commands: [
+      {
+        name: "create",
+        summary: "Copy the bundled web app template into a new project directory.",
+        usage: "finebi-cli app create --name <name> --path <parent> [--layout overview|workbench|cockpit|retail]",
+        options: [
+          {name: "--name", type: "string", description: "Simple lowercase npm project name."},
+          {name: "--layout", type: "string", description: "Page layout: overview (default), workbench, cockpit or retail."},
+          {name: "--path", type: "string", description: "Existing parent directory; relative paths resolve from the current directory."},
+        ],
+        details: ["Creates a local project only; it does not connect to FineBI or run install/build scripts."],
+      },
+      {
+        name: "inspect",
+        summary: "Check a local web app project configuration without remote validation.",
+        usage: "finebi-cli app inspect --path <project>",
+        options: [{name: "--path", type: "string", description: "Existing project directory; relative paths resolve from the current directory."}],
+        details: ["Checks app-config.json structure and widget bindings locally. Remote dashboard and permission checks are not performed."],
+      },
+    ],
+  },
   "install-skill": {
     command: "install-skill",
     resource: "install-skill",
@@ -152,7 +176,7 @@ const BUILT_IN_RESOURCES = {
       },
       {
         name: "clear",
-        summary: "Remove the selected environment's local configuration, credentials and capability cache; does not revoke server keys.",
+        summary: "Remove the selected environment's local configuration, credentials and capability cache; does not revoke server keys.",
         usage: "finebi-cli config clear",
       },
     ],
@@ -164,18 +188,18 @@ const BUILT_IN_RESOURCES = {
       {
         name: "login",
         summary: "Login with FineBI credentials or browser authorization and persist an Access Key.",
-        usage: "finebi-cli auth login [--profile <name>] [--base-url <url>] [--browser] [--username <username>] [--from-env] [--password-stdin] [--no-use]",
-        options: [
-          { name: "--no-use", type: "boolean", description: "Save successful login without changing the default environment." },
+        usage: "finebi-cli auth login [--profile <name>] [--base-url <url>] [--browser] [--username <username>] [--from-env] [--password-stdin] [--no-use]",
+        options: [
+          { name: "--no-use", type: "boolean", description: "Save successful login without changing the default environment." },
           { name: "--username", type: "string", description: "FineBI username." },
           { name: "--from-env", type: "boolean", description: "Read base URL, username, and password from environment variables." },
           { name: "--password-stdin", type: "boolean", description: "Read password from standard input." },
           { name: "--browser", type: "boolean", description: "Authorize this CLI from a signed-in FineBI browser without sending a password." },
         ],
-        details: [
-          "Login creates the named environment if missing and selects it after successful authentication, unless --no-use is supplied.",
-          "A new environment requires --base-url or FINEBI_BASE_URL; it never inherits another environment's address or identity.",
-          "Failed authentication preserves saved environments and the default selection.",
+        details: [
+          "Login creates the named environment if missing and selects it after successful authentication, unless --no-use is supplied.",
+          "A new environment requires --base-url or FINEBI_BASE_URL; it never inherits another environment's address or identity.",
+          "Failed authentication preserves saved environments and the default selection.",
           "Environment variables for --from-env:",
           "  FINEBI_BASE_URL",
           "  FINEBI_USERNAME",
@@ -187,28 +211,28 @@ const BUILT_IN_RESOURCES = {
           "finebi-cli auth login --username <username>",
           "finebi-cli auth login --from-env",
           "echo <password> | finebi-cli auth login --username <username> --password-stdin",
-          "finebi-cli auth login --browser",
-          "finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser",
+          "finebi-cli auth login --browser",
+          "finebi-cli auth login --profile test --base-url https://test.example.com/webroot/decision --browser",
         ],
       },
-      {
-        name: "list",
-        summary: "List saved environments and mark the default; local metadata only, no credential validation or secret output.",
-        usage: "finebi-cli auth list",
-      },
-      {
-        name: "use",
-        summary: "Select an existing environment as default without logging in.",
-        usage: "finebi-cli auth use <name>",
-      },
-      {
-        name: "remove",
-        summary: "Delete one local environment and its capability cache; does not revoke server keys.",
-        usage: "finebi-cli auth remove <name>",
-        details: ["Use auth logout --profile <name> first to revoke its Access Key.", "Removing the default environment does not select another environment."],
-      },
-      {
-        name: "info",
+      {
+        name: "list",
+        summary: "List saved environments and mark the default; local metadata only, no credential validation or secret output.",
+        usage: "finebi-cli auth list",
+      },
+      {
+        name: "use",
+        summary: "Select an existing environment as default without logging in.",
+        usage: "finebi-cli auth use <name>",
+      },
+      {
+        name: "remove",
+        summary: "Delete one local environment and its capability cache; does not revoke server keys.",
+        usage: "finebi-cli auth remove <name>",
+        details: ["Use auth logout --profile <name> first to revoke its Access Key.", "Removing the default environment does not select another environment."],
+      },
+      {
+        name: "info",
         summary: "Show stored authentication metadata with secrets masked.",
         usage: "finebi-cli auth info",
       },
@@ -376,10 +400,10 @@ function renderTopLevelHelpText(data) {
     "",
     "Use --help or -h for command details.",
     "Use --json with --help for structured output.",
-    "Output options: --select <paths> / --max-chars <n> / --save <path> for large responses.",
-    "Environment: --profile <name> > FINEBI_PROFILE > saved default. Global options may precede or follow the command.",
-  );
-  lines.push("", "Global Options:", ...formatOptionRows(data.globalOptions || []));
+    "Output options: --select <paths> / --max-chars <n> / --save <path> for large responses.",
+    "Environment: --profile <name> > FINEBI_PROFILE > saved default. Global options may precede or follow the command.",
+  );
+  lines.push("", "Global Options:", ...formatOptionRows(data.globalOptions || []));
   return `${lines.join("\n")}\n`;
 }
 
@@ -395,8 +419,8 @@ function renderResourceHelpText(data) {
     "",
     "Commands:",
   ];
-  lines.push(...formatRows(data.commands || [], "name", "summary"));
-  lines.push("", "Global Options:", ...formatOptionRows(data.globalOptions || []));
+  lines.push(...formatRows(data.commands || [], "name", "summary"));
+  lines.push("", "Global Options:", ...formatOptionRows(data.globalOptions || []));
     lines.push("", `Use ${commandLine(data.resource, "<command>", "--help")} for command details.`);
   return `${lines.join("\n")}\n`;
 }
@@ -411,13 +435,13 @@ function renderCommandHelpText(data) {
     "Usage:",
     `  ${data.usage}`,
   ];
-  if ((data.options || []).length > 0) {
+  if ((data.options || []).length > 0) {
     lines.push("", "Options:");
     lines.push(...formatOptionRows(data.options));
-  }
-  if ((data.globalOptions || []).length > 0) {
-    lines.push("", "Global Options:", ...formatOptionRows(data.globalOptions));
-  }
+  }
+  if ((data.globalOptions || []).length > 0) {
+    lines.push("", "Global Options:", ...formatOptionRows(data.globalOptions));
+  }
   if ((data.details || []).length > 0) {
     lines.push("", ...data.details);
   }

package/src/index.js

@@ -19,6 +19,7 @@ import {parseConnectionArgs, ProfileError, profileCapabilityPath, readProfile, r
 import {loginWithPassword, resolveLoginInputFromEnv} from "./auth.js";
 import {executeDynamicCommand} from "./dynamic-command.js";
 import {handleInstallSkill} from "./install-skill.js";
+import {handleApp} from "./app.js";
 import {cliError} from "./errors.js";
 import {
     renderBuiltInCommandHelp,
@@ -48,6 +49,9 @@ export async function runCli(argv, context = {}) {
     if (args[0] === "install-skill") {
       return isHelpFlagInvocation(args) ? renderBuiltInHelp("install-skill") : handleInstallSkill(args.slice(1), context);
     }
+    if (args[0] === "app") {
+      return isHelpFlagInvocation(args) ? renderBuiltInHelp("app") : handleApp(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";
@@ -684,6 +688,7 @@ async function handleHelp(args, context) {
 
 function isBuiltInResource(resourceName) {
   return resourceName === "install-skill"
+      || resourceName === "app"
       || resourceName === "config"
       || resourceName === "auth"
       || resourceName === "capability"

package/src/install-skill.js

@@ -1,89 +1,89 @@
-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 source = context.skillSource || [
-      "../skills/finebi-cli-agent/", "../../skills/finebi-cli-agent/", "../../../",
-    ].map(path => fileURLToPath(new URL(path, import.meta.url)))
-      .find(path => existsSync(join(path, "SKILL.md")) && existsSync(join(path, "scripts/finebi-cli/src/index.js")));
-    if (!source) throw new Error("FineBI Skill resources were not found. Reinstall the CLI package or build the Skill in the source checkout.");
-    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); }
-  }
-}
+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 source = context.skillSource || [
+      "../skills/finebi-cli-agent/", "../../skills/finebi-cli-agent/", "../../../",
+    ].map(path => fileURLToPath(new URL(path, import.meta.url)))
+      .find(path => existsSync(join(path, "SKILL.md")) && existsSync(join(path, "scripts/finebi-cli/src/index.js")));
+    if (!source) throw new Error("FineBI Skill resources were not found. Reinstall the CLI package or build the Skill in the source checkout.");
+    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); }
+  }
+}