@finebi/finebi-cli 1.2.1 → 1.4.0

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,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",
@@ -138,7 +152,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",
       },
     ],
@@ -150,18 +164,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",
@@ -173,28 +187,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",
       },
@@ -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>")}`,
@@ -353,10 +368,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`;
 }
 
@@ -372,8 +387,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`;
 }
@@ -388,13 +403,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

@@ -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,11 +45,17 @@ 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";
-    const profileName = management ? null : selectProfile(configPath(context), firstNonEmpty(flags.profile, env.FINEBI_PROFILE), {
-      allowCreate: args[0] === "auth" && args[1] === "login", optional,
+    const requestedProfile = firstNonEmpty(flags.profile, env.FINEBI_PROFILE);
+    const allowCreate = args[0] === "auth" && args[1] === "login";
+    const initialDefault = !requestedProfile && !existsSync(configPath(context));
+    const profileName = management ? null : selectProfile(configPath(context), requestedProfile, {
+      allowCreate, optional,
     });
     if (management && (flags.profile || env.FINEBI_PROFILE) && args[1] !== "list") {
       if (flags.profile && flags.profile !== args[2]) throw new ProfileError("Use the positional environment name for auth use/remove; --profile must not select a different environment.");
@@ -60,7 +67,12 @@ export async function runCli(argv, context = {}) {
     );
     const envelope = mutatesProfile
       ? await withProfileLoginLock(configPath(context), args[0] === "auth" && args[1] === "remove" ? args[2] : profileName,
-        () => dispatchCli(args, context))
+        () => {
+          if (!management) selectProfile(configPath(context), profileName, {
+            allowCreate: allowCreate || (initialDefault && profileName === "default"),
+          });
+          return dispatchCli(args, context);
+        })
       : await dispatchCli(args, context);
     if (profileName) {
       envelope.meta = {...envelope.meta, profile: profileName};
@@ -671,7 +683,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,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); }
+  }
+}