@finebi/finebi-cli 1.2.0 → 1.3.0

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

@@ -0,0 +1,1343 @@
+#!/usr/bin/env node
+import {existsSync, readFileSync, realpathSync, rmSync} from "node:fs";
+import {hostname} from "node:os";
+import {dirname, join} from "node:path";
+import {fileURLToPath, pathToFileURL} from "node:url";
+
+import {provisionAccessKey, selfRevokeAccessKey} from "./access-key.js";
+import {authorizeWithBrowser} from "./browser-auth.js";
+import {brandCommandText, CLI_COMMAND_NAME, commandLine} from "./branding.js";
+import {
+    cacheCapability,
+    capabilityCachePath,
+    fetchCapabilities,
+    readCapabilityCache,
+    resolveCapability,
+} from "./capability.js";
+import {defaultConfigPath, maskConfig, resolveConfig, sameBaseUrl, updateConfigValue} from "./config.js";
+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,
+    renderBuiltInHelp,
+    renderCommandHelp,
+    renderHelpText,
+    renderResourceHelp,
+    renderTopLevelHelp,
+} from "./help.js";
+import {failure, success} from "./output.js";
+import {
+    SELECT_FLAG,
+    parseOutputArgs,
+    saveFailure,
+    saveOutput,
+    savedSummary,
+    selectPaths,
+    truncateMiddle,
+} from "./output-limits.js";
+
+const AUTH_EXPIRE_SKEW_MS = 300000;
+
+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,
+    });
+    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.");
+    }
+    context = {...context, profileName, connectionFlags: flags};
+    const mutatesProfile = !isHelpFlagInvocation(args) && (
+      (args[0] === "auth" && ["login", "logout", "remove"].includes(args[1])) ||
+      (args[0] === "config" && ["set", "clear"].includes(args[1]))
+    );
+    const envelope = mutatesProfile
+      ? await withProfileLoginLock(configPath(context), args[0] === "auth" && args[1] === "remove" ? args[2] : profileName,
+        () => dispatchCli(args, context))
+      : await dispatchCli(args, context);
+    if (profileName) {
+      envelope.meta = {...envelope.meta, profile: profileName};
+      if (profileName !== "default" || readProfiles(configPath(context)).multi) {
+        for (const error of [...(envelope.errors || []), ...(envelope.warnings || [])]) {
+          error.nextActions = (error.nextActions || []).map((action) => typeof action === "string" && !action.includes("--profile")
+            ? action.replaceAll(`${CLI_COMMAND_NAME} `, `${CLI_COMMAND_NAME} --profile ${profileName} `) : action);
+        }
+      }
+    }
+    return envelope;
+  } catch (error) {
+    if (!(error instanceof ProfileError)) throw error;
+    return failure("profile", cliError("INVALID_ARGUMENT", {
+      path: "profile", message: error.message,
+      nextActions: ["finebi-cli auth list", "finebi-cli auth login --help"],
+    }));
+  }
+}
+
+async function dispatchCli(args, context) {
+  if (args.length === 0) {
+    return handleHelp([], context);
+  }
+  if (isHelpFlagInvocation(args)) {
+    return handleHelp(args.filter((arg) => !isHelpFlag(arg)), context);
+  }
+  const command = args.shift();
+  switch (command) {
+    case "config":
+      if (args.length === 0) {
+        return handleHelp(["config"], context);
+      }
+      return handleConfig(args, context);
+    case "auth":
+      if (args.length === 0) {
+        return handleHelp(["auth"], context);
+      }
+      return handleAuth(args, context);
+    case "capability":
+      if (args.length === 0) {
+        return handleHelp(["capability"], context);
+      }
+      return handleCapability(args, context);
+    case "capabilities":
+      return fetchAndCacheCapabilities("capabilities", context);
+    case "version":
+      return handleVersion(context);
+    case "--help":
+    case "-h":
+      return handleHelp(args, context);
+    case "help":
+      return usageError("help", "The help command is not supported. Use --help or -h instead.", [
+        "finebi-cli --help",
+        "finebi-cli <resource> --help",
+        "finebi-cli <resource> <command> --help",
+      ]);
+    default:
+      return handleDynamic(command, args, context);
+  }
+}
+
+export async function main(argv = process.argv.slice(2), context = {}) {
+  const parsed = parseOutputArgs(argv);
+  if (!parsed.ok) {
+    process.stdout.write(formatCliOutput(failure("output.args", parsed.error), jsonArgs(argv)));
+    process.exitCode = 1;
+    return;
+  }
+  const envelope = await runCli(parsed.args, context);
+  const rendered = renderFinalOutput(envelope, parsed.options, parsed.args);
+  process.stdout.write(rendered.text);
+  process.exitCode = rendered.ok ? 0 : 1;
+}
+
+/** 输出参数错误与投影的 JSON 口径：显式 --json 或用了 --select 时输出结构化信封。 */
+function jsonArgs(argv) {
+  return argv.includes("--json") || argv.includes(SELECT_FLAG) ? ["--json"] : [];
+}
+
+/**
+ * 渲染最终 stdout：投影（--select，恒 JSON）→ 渲染 → 落盘（--save）/截断（--max-chars）。
+ * --save 恒落 JSON 信封（用了 --select 则落投影结果）——人读渲染是有损的，落盘要的是完整数据；
+ * --max-chars 只作用于 stdout 文本，且 --save 时被忽略（摘要本身极短）。失败信封不投影——
+ * 失败响应 data 恒为 null，投影只会把真实错误盖成 "Unknown path(s)"；但照常走落盘/截断链，
+ * 与无 --select 的失败路径一致（脚本消费方不会拿到上一轮的陈旧落盘文件）。
+ */
+export function renderFinalOutput(envelope, options, argv = []) {
+  const jsonArgv = options.select ? ["--json"] : jsonArgs(argv);
+  if (options.select && !envelope.ok) {
+    return finishOutput(formatCliOutput(envelope, jsonArgv), `${JSON.stringify(envelope, null, 2)}\n`,
+        envelope, options, jsonArgv);
+  }
+  if (options.select) {
+    const projected = selectPaths(envelope, options.select);
+    if (!projected.ok) {
+      const rejected = failure(envelope.command, projected.error);
+      const rejectedJson = `${JSON.stringify(rejected, null, 2)}\n`;
+      return finishOutput(rejectedJson, rejectedJson, rejected, options, jsonArgv);
+    }
+    const projectedJson = `${JSON.stringify(projected.value, null, 2)}\n`;
+    return finishOutput(projectedJson, projectedJson, envelope, options, jsonArgv);
+  }
+  return finishOutput(formatCliOutput(envelope, argv), `${JSON.stringify(envelope, null, 2)}\n`, envelope,
+      options, jsonArgv);
+}
+
+function finishOutput(displayText, fullJson, envelope, options, jsonArgv) {
+  if (options.save) {
+    let chars;
+    try {
+      chars = saveOutput(fullJson, options.save);
+    } catch (error) {
+      return {
+        ok: false,
+        text: formatCliOutput(failure(envelope.command, saveFailure(options.save, error)), jsonArgv),
+      };
+    }
+    return {ok: envelope.ok, text: savedSummary(envelope, options.save, chars)};
+  }
+  if (options.maxChars) {
+    return {ok: envelope.ok, text: truncateMiddle(displayText, options.maxChars)};
+  }
+  return {ok: envelope.ok, text: displayText};
+}
+
+export function formatCliOutput(envelope, argv = []) {
+  if ((isHelpInvocation(argv) || envelope.command === "help") && !argv.includes("--json")) {
+    return renderHelpText(envelope);
+  }
+  if (!argv.includes("--json")) {
+    const text = renderHumanOutput(envelope);
+    if (text !== undefined) {
+      return text;
+    }
+  }
+  return `${JSON.stringify(envelope, null, 2)}\n`;
+}
+
+export function isDirectInvocation(modulePath, invokedPath) {
+  if (!invokedPath) {
+    return false;
+  }
+  return normalizePath(modulePath) === normalizePath(invokedPath);
+}
+
+async function handleConfig(args, context) {
+  const action = args[0];
+  if (action === "get") {
+    return success("config.get", maskConfig(readContextConfig(context)));
+  }
+  if (action === "set") {
+    return setConfigValue(args.slice(1), context);
+  }
+  if (action === "clear") {
+    removeProfile(configPath(context), context.profileName);
+    removeFile(capabilityPath(context));
+    return success("config.clear", { cleared: true });
+  }
+  return usageError("config", "Unsupported config command.", ["finebi-cli config get", "finebi-cli config set base-url <baseUrl>"]);
+}
+
+function setConfigValue(args, context) {
+  const key = args[0];
+  const value = args[1];
+  if (!key || value === undefined) {
+    return usageError("config.set", "Config key and value are required.", ["finebi-cli config set base-url <baseUrl>"]);
+  }
+  try {
+    const current = readContextConfig(context);
+    const next = updateConfigValue(current, key, value, nowFn(context));
+    writeContextConfig(context, next);
+    if (key === "base-url" && current.baseUrl !== next.baseUrl) removeFile(capabilityPath(context));
+    return success("config.set", { key, value });
+  } catch (error) {
+      return failure("config.set", cliError("INVALID_ARGUMENT", {
+      path: key,
+      message: error instanceof Error ? error.message : String(error),
+      hint: "Use finebi-cli config get to inspect supported local settings.",
+      retryable: false,
+      nextActions: ["finebi-cli config get"],
+      }));
+  }
+}
+
+async function handleAuth(args, context) {
+  const action = args[0];
+  if (action === "list") {
+    const store = readProfiles(configPath(context));
+    return success("auth.list", {
+      currentProfile: store.currentProfile,
+      profiles: Object.entries(store.profiles).map(([name, config]) => ({
+        name, isDefault: name === store.currentProfile, baseUrl: config.baseUrl || null,
+        username: config.auth?.username || null, authMode: buildAuthInfo(config).authMode,
+        expiresAt: config.auth?.expiresAt || null,
+      })),
+    });
+  }
+  if (action === "use" || action === "remove") {
+    const name = args[1];
+    if (!name || args.slice(2).some((arg) => arg !== "--json")) throw new ProfileError(`Usage: finebi-cli auth ${action} <name>`);
+    if (action === "use") useProfile(configPath(context), name);
+    else {
+      selectProfile(configPath(context), name);
+      removeProfile(configPath(context), name);
+      removeFile(capabilityPath({...context, profileName: name}));
+    }
+    return success(`auth.${action}`, {profile: name, [action === "use" ? "selected" : "removed"]: true});
+  }
+  if (action === "login") {
+    return login(args.slice(1), context);
+  }
+  if (action === "info") {
+    return success("auth.info", buildAuthInfo(readContextConfig(context)));
+  }
+  if (action === "logout") {
+    return logout(args.slice(1), context);
+  }
+  return usageError("auth", "Unsupported auth command.", ["finebi-cli auth login --username <username>", "finebi-cli auth info"]);
+}
+
+function buildAuthInfo(config) {
+  const auth = maskConfig(config).auth;
+  const authMode = auth?.accessKey?.value ? "access-key" : auth?.token ? "session-token" : "none";
+  return { authMode, auth };
+}
+
+async function logout(args, context) {
+  const flags = parseFlags(args);
+  const config = resolveConfig({}, {}, readContextConfig(context));
+  const warnings = [];
+  const accessKey = config.auth?.accessKey;
+  if (accessKey?.value && config.baseUrl) {
+    const revoked = await selfRevokeAccessKey({
+      baseUrl: config.baseUrl,
+      accessKey: accessKey.value,
+      timeoutMs: config.timeoutMs,
+      fetchImpl: context.fetchImpl,
+    });
+    if (!revoked.ok) {
+      if (!flags.force) {
+        return failure("auth.logout", cliError("ACCESS_KEY_REVOKE_FAILED", {
+          path: "auth.accessKey",
+          message: "Could not revoke the server-side Access Key; local credentials were preserved for retry.",
+          hint: "Retry logout, or use --force to remove local credentials without confirming server revocation.",
+          retryable: true,
+          nextActions: ["finebi-cli auth logout", "finebi-cli auth logout --force"],
+          id: accessKey.id,
+          cause: revoked.errors?.[0],
+        }));
+      }
+      warnings.push(cliError("ACCESS_KEY_REVOKE_FAILED", {
+        message: "Server revocation failed; local credentials were removed because --force was specified.",
+        hint: "Revoke the Access Key manually in FineBI if it is still present.",
+        retryable: true,
+        nextActions: ["finebi-cli auth login"],
+        id: accessKey.id,
+        cause: revoked.errors?.[0],
+      }));
+    }
+  }
+  const stored = readContextConfig(context);
+  delete stored.auth;
+  delete stored.token;
+  writeContextConfig(context, stored);
+  removeFile(capabilityPath(context));
+  return success("auth.logout", { loggedOut: true, forced: Boolean(flags.force) }, {}, warnings);
+}
+
+async function login(args, context) {
+  const flags = {...parseFlags(args), ...context.connectionFlags};
+  const stored = readContextConfig(context);
+  const target = firstNonEmpty(flags.baseUrl, (context.env || process.env).FINEBI_BASE_URL, stored.baseUrl);
+  const config = sameBaseUrl(target, stored.baseUrl) ? stored : {...stored, auth: undefined, token: undefined};
+  if (flags.browser) {
+    const incompatible = [flags.username && "--username", flags.password && "--password", flags.passwordStdin && "--password-stdin",
+      flags.fromEnv && "--from-env", flags.noAccessKey && "--no-access-key", flags.token && "--token"].find(Boolean);
+    if (incompatible) {
+      return usageError("auth.login", `${incompatible} cannot be used with --browser.`, [
+        "finebi-cli auth login --browser [--base-url <baseUrl>]",
+      ]);
+    }
+    return loginWithBrowser(flags, config, context);
+  }
+  const input = flags.fromEnv ? resolveLoginInputFromEnv(context.env || process.env) : {};
+  const baseUrl = target;
+  const username = firstNonEmpty(flags.username, input.username, config.auth?.username);
+  if (flags.passwordStdin && isStdinTty(context)) {
+    return usageError("auth.login", "The --password-stdin option requires pipe input.", [
+      "echo <password> | finebi-cli auth login --username <username> --password-stdin",
+      "finebi-cli auth login --username <username>",
+    ]);
+  }
+  let password;
+  try {
+    password = await resolvePassword(flags, input, context);
+  } catch (error) {
+      return failure("auth.login", cliError("PASSWORD_INPUT_FAILED", {
+      path: "password",
+      message: error instanceof Error ? error.message : String(error),
+      hint: "Use --from-env or --password-stdin when interactive input is unavailable.",
+      retryable: false,
+      nextActions: ["finebi-cli auth login --from-env", "echo <password> | finebi-cli auth login --username <username> --password-stdin"],
+      }));
+  }
+  if (!baseUrl || !username || !password) {
+    return usageError("auth.login", "base-url, username, and password are required.", [
+      "finebi-cli auth login --from-env",
+      "finebi-cli auth login --username <username>",
+      "finebi-cli auth login --username <username> --password-stdin",
+    ]);
+  }
+  const envelope = await loginWithPassword({
+    baseUrl,
+    username,
+    password,
+    timeoutMs: resolveConfig({}, context.env || process.env, config).timeoutMs,
+    now: nowFn(context),
+    fetchImpl: context.fetchImpl,
+  });
+  if (envelope.ok) {
+    const nextConfig = {
+      ...config,
+      baseUrl,
+      auth: envelope.data.auth,
+    };
+    writeContextConfig(context, nextConfig, {makeCurrent: !flags.noUse, forceMulti: flags.noUse});
+    removeFile(capabilityPath(context));
+    const capabilityRefresh = await refreshCapabilityAfterLogin(nextConfig, context);
+    envelope.data.capabilityRefresh = capabilityRefresh.data;
+    if (!capabilityRefresh.ok) {
+      envelope.warnings.push(cliError("CAPABILITY_AUTO_REFRESH_FAILED", {
+        message: "Capability cache was not refreshed after login.",
+        nextActions: ["finebi-cli capability refresh"],
+        cause: capabilityRefresh.error,
+      }));
+    }
+    if (!flags.noAccessKey) {
+      const provision = await provisionAccessKeyAfterLogin(context);
+      envelope.data.accessKey = provision.data;
+      if (provision.warnings.length) {
+        envelope.warnings.push(...provision.warnings);
+      }
+    }
+  }
+  return envelope;
+}
+
+async function loginWithBrowser(flags, config, context) {
+  const baseUrl = firstNonEmpty(flags.baseUrl, (context.env || process.env).FINEBI_BASE_URL, config.baseUrl);
+  if (!baseUrl) {
+    return failure("auth.login", cliError("CONFIG_MISSING", {
+      path: "baseUrl",
+      message: "FineBI base-url is not configured.",
+      nextActions: ["finebi-cli config set base-url <baseUrl>"],
+    }));
+  }
+  const authorization = await authorizeWithBrowser({
+    baseUrl,
+    description: accessKeyDescription(context),
+    timeoutMs: resolveConfig({}, context.env || process.env, config).timeoutMs,
+    fetchImpl: context.fetchImpl,
+    interactive: isStdinTty(context),
+    openBrowser: context.openBrowser,
+    sleep: context.sleep,
+    nowMs: context.nowMs,
+    signal: context.signal,
+    writeStderr: context.writeStderr,
+    onApproved: async (key) => {
+      const nextConfig = {
+        ...config,
+        baseUrl,
+        auth: {
+          username: key.username,
+          accessKey: {
+            id: key.id,
+            value: key.token,
+            description: key.description ?? accessKeyDescription(context),
+            createdAt: now(context),
+          },
+        },
+      };
+      writeContextConfig(context, nextConfig, {
+        makeCurrent: !flags.noUse, forceMulti: flags.noUse, writer: context.writeConfigAtomically,
+      });
+      removeFile(capabilityPath(context));
+    },
+  });
+  if (!authorization.ok) {
+    return authorization;
+  }
+  const stored = readContextConfig(context);
+  const capabilityRefresh = await refreshCapabilityAfterLogin(stored, context);
+  const envelope = success("auth.login", {
+    auth: {username: stored.auth.username},
+    browserAuthorization: {id: authorization.data.id, description: authorization.data.description},
+    capabilityRefresh: capabilityRefresh.data,
+  });
+  if (!capabilityRefresh.ok) {
+    envelope.warnings.push(cliError("CAPABILITY_AUTO_REFRESH_FAILED", {
+      message: "Capability cache was not refreshed after browser authorization.",
+      nextActions: ["finebi-cli capability refresh"],
+      cause: capabilityRefresh.error,
+    }));
+  }
+  return envelope;
+}
+
+async function provisionAccessKeyAfterLogin(context) {
+  const config = resolveConfig({}, {}, readContextConfig(context));
+  const description = accessKeyDescription(context);
+  const { created, warnings } = await provisionAccessKey({
+    baseUrl: config.baseUrl,
+    token: config.auth.token,
+    username: config.auth.username,
+    description,
+    timeoutMs: config.timeoutMs,
+    fetchImpl: context.fetchImpl,
+  });
+  if (!created.ok) {
+    return {
+      data: { issued: false, description },
+      warnings: [
+        ...warnings,
+        cliError("ACCESS_KEY_ISSUE_FAILED", {
+          message: "Access Key was not issued; commands will use the session token until it expires.",
+          nextActions: ["finebi-cli auth login"],
+          cause: created.errors?.[0],
+        }),
+      ],
+    };
+  }
+  const key = created.data;
+  const stored = readContextConfig(context);
+  stored.auth = {
+    ...stored.auth,
+    accessKey: {
+      id: key.id,
+      value: key.token,
+      description: key.description ?? description,
+      createdAt: now(context),
+    },
+  };
+  writeContextConfig(context, stored);
+  return {
+    data: { issued: true, id: key.id, description: key.description ?? description },
+    warnings,
+  };
+}
+
+function accessKeyDescription(context) {
+  const host = context.hostname || safeHostname();
+  const suffix = context.profileName && context.profileName !== "default" ? `/${context.profileName}` : "";
+  return `finebi-cli@${host}${suffix}`;
+}
+
+function safeHostname() {
+  try {
+    return hostname() || "unknown-host";
+  } catch (_error) {
+    return "unknown-host";
+  }
+}
+
+async function refreshCapabilityAfterLogin(config, context) {
+  const envelope = await fetchCapabilities({
+    baseUrl: config.baseUrl,
+    token: config.auth.token,
+    accessKey: config.auth.accessKey?.value,
+    timeoutMs: resolveConfig({}, context.env || process.env, config).timeoutMs,
+    fetchImpl: context.fetchImpl,
+  });
+  if (!envelope.ok) {
+    return {
+      ok: false,
+      data: {
+        ok: false,
+        refreshed: false,
+      },
+      error: envelope.errors?.[0],
+    };
+  }
+  if (!Array.isArray(envelope.data?.resources)) {
+    return {
+      ok: false,
+      data: {
+        ok: false,
+        refreshed: false,
+      },
+        error: cliError("CAPABILITY_MANIFEST_INVALID", {
+        message: "Capability response does not contain resources.",
+        }),
+    };
+  }
+  const record = cacheCapability(capabilityPath(context), envelope.data, {
+    baseUrl: config.baseUrl,
+    username: config.auth.username,
+    fetchedAt: now(context),
+    ttlMs: config.capabilityTtlMs,
+  });
+  return {
+    ok: true,
+    data: {
+      ok: true,
+      refreshed: true,
+      resources: envelope.data.resources.length,
+      commands: envelope.data.resources.reduce((sum, resource) => sum + (resource.commands || []).length, 0),
+      fetchedAt: record.fetchedAt,
+      expiresAt: record.expiresAt,
+    },
+  };
+}
+
+async function resolvePassword(flags, input, context) {
+  if (flags.fromEnv) {
+    return input.password;
+  }
+  if (flags.passwordStdin) {
+    return (await (context.readStdin ? context.readStdin() : readStdin())).trim();
+  }
+  if (context.promptPassword) {
+    return context.promptPassword();
+  }
+  if (isStdinTty(context)) {
+    return promptHiddenPassword("Password: ");
+  }
+  return undefined;
+}
+
+async function handleCapability(args, context) {
+  const action = args[0];
+  if (action === "refresh") {
+    return refreshCapability(context);
+  }
+  if (action === "info") {
+    const cache = readContextCache(context);
+    return success("capability.info", { cache: cache.record || null, hit: cache.hit, stale: cache.stale });
+  }
+  if (action === "clear-cache") {
+    removeFile(capabilityPath(context));
+    return success("capability.clear-cache", { cleared: true });
+  }
+  return usageError("capability", "Unsupported capability command.", ["finebi-cli capability refresh", "finebi-cli capability info"]);
+}
+
+async function refreshCapability(context) {
+  return fetchAndCacheCapabilities("capability.refresh", context);
+}
+
+async function fetchAndCacheCapabilities(command, context) {
+  const config = resolveContextConfig(context);
+  const authError = requireConfiguredAuth(config, command, context);
+  if (authError) {
+    return authError;
+  }
+  const envelope = await fetchCapabilities({
+    baseUrl: config.baseUrl,
+    token: config.auth.token,
+    accessKey: config.auth.accessKey?.value,
+    timeoutMs: config.timeoutMs,
+    fetchImpl: context.fetchImpl,
+  });
+  if (envelope.ok && !hasTransientConnection(context)) {
+    cacheCapability(capabilityPath(context), envelope.data, {
+      baseUrl: config.baseUrl,
+      username: config.auth.username,
+      fetchedAt: now(context),
+      ttlMs: config.capabilityTtlMs,
+    });
+  }
+  return command === envelope.command ? envelope : { ...envelope, command };
+}
+
+function handleVersion(context) {
+  const metadata = readPackageMetadata(context);
+  return success("version", {
+    cli: {
+      name: metadata.name,
+      version: metadata.version,
+    },
+  });
+}
+
+async function handleHelp(args, context) {
+  args = args.filter((arg) => arg !== "--json");
+  if (args.length === 0) {
+    const cache = readContextCache(context);
+    return renderTopLevelHelp(cache.manifest);
+  }
+  if (args.length === 1 && isBuiltInResource(args[0])) {
+    return renderBuiltInHelp(args[0]);
+  }
+  if (args.length >= 2 && isBuiltInResource(args[0])) {
+    return renderBuiltInCommandHelp(args[0], args[1]);
+  }
+  const cache = readContextCache(context);
+  const resolved = resolveCapability(cache, "help");
+  if (resolved.error) {
+    return failure("help", resolved.error);
+  }
+  if (args.length >= 2) {
+    return renderCommandHelp(resolved.manifest, args[0], args[1]);
+  }
+  if (args.length === 1) {
+    return renderResourceHelp(resolved.manifest, args[0]);
+  }
+  return renderTopLevelHelp(resolved.manifest);
+}
+
+function isBuiltInResource(resourceName) {
+  return resourceName === "install-skill"
+      || resourceName === "config"
+      || resourceName === "auth"
+      || resourceName === "capability"
+      || resourceName === "version"
+      || resourceName === "capabilities";
+}
+
+function isHelpInvocation(argv) {
+  return argv.length === 0 || argv.some((arg) => isHelpFlag(arg));
+}
+
+function isHelpFlagInvocation(args) {
+  return args.some((arg) => isHelpFlag(arg));
+}
+
+function isHelpFlag(arg) {
+  return arg === "--help" || arg === "-h";
+}
+
+async function handleDynamic(resourceName, args, context) {
+  const commandName = args[0];
+  if (!commandName) {
+    return handleHelp([resourceName], context);
+  }
+  const config = resolveContextConfig(context);
+  const authError = requireConfiguredAuth(config, `${resourceName}.${commandName}`, context);
+  if (authError) {
+    return authError;
+  }
+  const cache = hasTransientConnection(context)
+    ? await fetchTransientCapability(config, context)
+    : readContextCache(context);
+  if (cache.error) return failure(`${resourceName}.${commandName}`, cache.error);
+  const resolved = resolveCapability(cache, "command");
+  if (resolved.error) {
+    return failure(`${resourceName}.${commandName}`, resolved.error);
+  }
+  return executeDynamicCommand(resolved.manifest, resourceName, commandName, args.slice(1), {
+    baseUrl: config.baseUrl,
+    token: config.auth.token,
+    accessKey: config.auth.accessKey?.value,
+    timeoutMs: config.timeoutMs,
+    fetchImpl: context.fetchImpl,
+  });
+}
+
+function requireConfiguredAuth(config, command, context) {
+  if (!config.baseUrl) {
+      return failure(command, cliError("CONFIG_MISSING", {
+      path: "baseUrl",
+      message: "FineBI base-url is not configured.",
+      hint: "Set the FineBI decision root URL.",
+      retryable: false,
+      nextActions: ["finebi-cli config set base-url <baseUrl>"],
+      }));
+  }
+  if (config.auth?.accessKey?.value) {
+    return null;
+  }
+  if (!config.auth?.token) {
+      return failure(command, cliError("AUTH_REQUIRED", {
+      path: "auth.token",
+      message: "Authentication is required.",
+      hint: "Login with a FineBI username and password.",
+      retryable: false,
+      nextActions: ["finebi-cli auth login --username <username>"],
+      }));
+  }
+  if (isAuthExpired(config.auth.expiresAt, now(context))) {
+      return failure(command, cliError("AUTH_EXPIRED", {
+      path: "auth.expiresAt",
+      message: "Authentication has expired or is about to expire.",
+      hint: "Login again before running this command.",
+      retryable: false,
+      nextActions: ["finebi-cli auth login --username <username>"],
+      }));
+  }
+  return null;
+}
+
+function parseFlags(args) {
+  const flags = {};
+  for (let index = 0; index < args.length; index += 1) {
+    const item = args[index];
+    if (item === "--from-env") {
+      flags.fromEnv = true;
+    } else if (item === "--no-use") {
+      flags.noUse = true;
+    } else if (item === "--password-stdin") {
+      flags.passwordStdin = true;
+    } else if (item === "--no-access-key") {
+      flags.noAccessKey = true;
+    } else if (item === "--browser") {
+      flags.browser = true;
+    } else if (item === "--password") {
+      flags.password = args[index + 1];
+      index += 1;
+    } else if (item === "--force") {
+      flags.force = true;
+    } else if (item === "--username") {
+      flags.username = args[index + 1];
+      index += 1;
+    } else if (item === "--base-url") {
+      flags.baseUrl = args[index + 1];
+      index += 1;
+    } else if (item === "--token") {
+      flags.token = args[index + 1];
+      index += 1;
+    }
+  }
+  return flags;
+}
+
+function usageError(command, message, nextActions) {
+    return failure(command, cliError("INVALID_ARGUMENT", {
+    path: "",
+    message,
+    hint: "Run finebi-cli --help for supported commands.",
+    retryable: false,
+    nextActions,
+    }));
+}
+
+function isAuthExpired(expiresAt, currentTime) {
+  if (!expiresAt) {
+    return false;
+  }
+  return Date.parse(expiresAt) - Date.parse(currentTime) <= AUTH_EXPIRE_SKEW_MS;
+}
+
+function now(context) {
+  return nowFn(context)();
+}
+
+function nowFn(context) {
+  return context.now || (() => new Date().toISOString());
+}
+
+function configPath(context) {
+  return context.configPath || defaultConfigPath(context.env || process.env);
+}
+
+function capabilityPath(context) {
+  return profileCapabilityPath(context.capabilityPath || capabilityCachePath(context.env || process.env), context.profileName);
+}
+
+function readContextConfig(context) {
+  return readProfile(configPath(context), context.profileName);
+}
+
+function writeContextConfig(context, config, options) {
+  saveProfile(configPath(context), context.profileName, config, options);
+}
+
+function resolveContextConfig(context) {
+  return resolveConfig(context.connectionFlags, context.env || process.env, readContextConfig(context));
+}
+
+function hasTransientConnection(context) {
+  const stored = readContextConfig(context);
+  const env = context.env || process.env;
+  return !sameBaseUrl(resolveContextConfig(context).baseUrl, stored.baseUrl)
+    || Boolean(context.connectionFlags?.token || env.FINEBI_AUTH_TOKEN);
+}
+
+function readContextCache(context) {
+  if (hasTransientConnection(context)) return {hit: false, stale: false};
+  const cache = readCapabilityCache(capabilityPath(context), now(context));
+  const stored = readContextConfig(context);
+  if (cache.record && (!sameBaseUrl(cache.record.baseUrl, stored.baseUrl) || cache.record.username !== stored.auth?.username)) {
+    return {hit: false, stale: false};
+  }
+  return cache;
+}
+
+async function fetchTransientCapability(config, context) {
+  const result = await fetchCapabilities({
+    baseUrl: config.baseUrl, token: config.auth?.token, accessKey: config.auth?.accessKey?.value,
+    timeoutMs: config.timeoutMs, fetchImpl: context.fetchImpl,
+  });
+  return result.ok ? {hit: true, manifest: result.data} : {error: result.errors[0]};
+}
+
+function removeFile(path) {
+  if (path && existsSync(path)) {
+    rmSync(path, { force: true });
+  }
+}
+
+function renderHumanOutput(envelope) {
+  if (!envelope.ok) {
+    return renderFailure(envelope);
+  }
+  switch (envelope.command) {
+    case "version":
+      return `${envelope.data?.cli?.version || ""}\n`;
+    case "config.get":
+      return `profile: ${envelope.meta?.profile || "(none)"}\n${renderConfigGet(envelope.data || {})}`;
+    case "auth.info":
+      return `profile: ${envelope.meta?.profile || "(none)"}\n${renderAuthInfo(envelope.data || {})}`;
+    case "auth.list":
+      return `${(envelope.data.profiles || []).map((profile) =>
+        `${profile.isDefault ? "*" : " "} ${profile.name}  ${profile.baseUrl || "(not set)"}  ${profile.username || "(unknown)"}  ${profile.authMode}`,
+      ).join("\n") || "No environments configured."}\n`;
+    case "auth.use":
+      return `Default environment: ${envelope.data.profile}\n`;
+    case "auth.remove":
+      return `Removed local environment: ${envelope.data.profile}\n`;
+    case "capability.info":
+      return renderCapabilityInfo(envelope.data || {});
+    case "auth.logout":
+      return renderLocalAction("Logged out.", envelope);
+    case "auth.login":
+      return renderAuthLogin(envelope);
+    case "config.clear":
+      return "Local config and capability cache cleared.\n";
+    case "capability.clear-cache":
+      return "Capability cache cleared.\n";
+    default:
+      if (isDynamicBusinessCommand(envelope.command)) {
+        return renderDynamicSuccess(envelope);
+      }
+      return undefined;
+  }
+}
+
+function renderAuthLogin(envelope) {
+  const auth = envelope.data?.auth || {};
+  const refresh = envelope.data?.capabilityRefresh || {};
+  const lines = [`Logged in${auth.username ? ` as ${auth.username}` : ""}.`];
+  if (refresh.refreshed) {
+    lines.push(`Capability cache refreshed: ${refresh.resources} resources, ${refresh.commands} commands.`);
+  } else if ((envelope.warnings || []).length > 0) {
+      lines.push(`Capability cache was not refreshed. Run ${commandLine("capability", "refresh")} after checking the server.`);
+  }
+  lines.push(...renderWarningLines(envelope.warnings));
+  return `${lines.join("\n")}\n`;
+}
+
+function renderLocalAction(message, envelope) {
+  return `${[message, ...renderWarningLines(envelope.warnings)].join("\n")}\n`;
+}
+
+function renderWarningLines(warnings = []) {
+  return warnings.map((warning) => {
+    const code = warning.code ? ` [${warning.code}]` : "";
+    return `Warning${code}: ${warning.message || "Command completed with a warning."}`;
+  });
+}
+
+function hasWarning(envelope, code) {
+  return (envelope.warnings || []).some((warning) => warning.code === code);
+}
+
+function renderFailure(envelope) {
+  const [error] = envelope.errors || [];
+  if (!error) {
+    return `Error: ${envelope.command || "Command failed"}\n`;
+  }
+  const lines = [`Error: ${error.message || "Command failed."}`];
+  if (error.code) {
+    lines.push(`Code: ${error.code}`);
+  }
+  if (error.path) {
+    lines.push(`Path: ${error.path}`);
+  }
+  if (error.hint) {
+    lines.push(`Hint: ${error.hint}`);
+  }
+  if (typeof error.retryable === "boolean") {
+    lines.push(`Retryable: ${error.retryable}`);
+  }
+  if (Array.isArray(error.nextActions) && error.nextActions.length > 0) {
+    lines.push("Next actions:");
+    for (const action of error.nextActions) {
+      lines.push(`  - ${action}`);
+    }
+  }
+  if (error.partialResult && typeof error.partialResult === "object") {
+    lines.push("Partial result:");
+    lines.push(...renderValue(error.partialResult, 1));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderDynamicSuccess(envelope) {
+  const businessEnvelope = withoutBusinessLinks(envelope);
+  const displayOutput = renderDynamicDisplay(businessEnvelope);
+  if (displayOutput !== undefined) {
+    return appendResolvedLinks(displayOutput, envelope);
+  }
+  const lines = [envelope.command];
+  if (businessEnvelope.data !== undefined && businessEnvelope.data !== null) {
+    lines.push(...renderValue(businessEnvelope.data, 0));
+  }
+  if (Array.isArray(envelope.warnings) && envelope.warnings.length > 0) {
+    lines.push("warnings:");
+    for (const warning of envelope.warnings) {
+      lines.push(`  - ${stringifyScalar(warning)}`);
+    }
+  }
+  return appendResolvedLinks(`${lines.join("\n")}\n`, envelope);
+}
+
+function withoutBusinessLinks(envelope) {
+  if (!envelope.data || typeof envelope.data !== "object" || Array.isArray(envelope.data)) {
+    return envelope;
+  }
+  return {...envelope, data: withoutKeys(envelope.data, ["links"])};
+}
+
+function appendResolvedLinks(output, envelope) {
+  const links = envelope.resolved?.links;
+  if (!links || typeof links !== "object" || Array.isArray(links)) {
+    return output;
+  }
+  const lines = Object.entries(links).flatMap(([relation, link]) => {
+    return typeof link?.url === "string" && link.url ? [`${relation}-url: ${link.url}`] : [];
+  });
+  return lines.length > 0 ? `${output.trimEnd()}\n${lines.join("\n")}\n` : output;
+}
+
+function renderDynamicDisplay(envelope) {
+  const display = envelope.resolved?.display || {};
+  const shape = display.shape || "generic";
+  const format = display.format === "auto" || !display.format
+      ? display.defaultFormat || "expanded"
+      : display.format;
+  if (format === "csv") {
+    if (shape === "tabular-preview") {
+      return renderTabularPreviewCsv(envelope.data || {});
+    }
+    return undefined;
+  }
+  if (format === "table") {
+    if (shape === "record-list") {
+      return renderRecordListTable(envelope.data || {}, display);
+    }
+    if (shape === "tabular-preview") {
+      return renderTabularPreviewTable(envelope.data || {}, display);
+    }
+  }
+  if (format === "expanded" && shape === "detail") {
+    return `${renderValue(envelope.data || {}, 0, { omitNullFields: display.omitNullFields === true }).join("\n")}\n`;
+  }
+  return undefined;
+}
+
+function renderRecordListTable(data, display) {
+  const items = Array.isArray(data.items) ? data.items : null;
+  if (!items) {
+    return undefined;
+  }
+  const columns = recordListColumns(items);
+  const rows = items.map((item) => columns.map((column) => item?.[column]));
+  const lines = columns.length > 0 ? renderAlignedTable(columns, rows) : ["(no items)"];
+  const rest = withoutKeys(data, ["items"]);
+  if (Object.keys(rest).length > 0) {
+    lines.push("---");
+    lines.push(...renderValue(rest, 0));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function recordListColumns(items) {
+  const seen = new Set();
+  for (const item of items) {
+    if (!item || typeof item !== "object" || Array.isArray(item)) {
+      continue;
+    }
+    for (const key of Object.keys(item)) {
+      seen.add(key);
+    }
+  }
+  return [...seen];
+}
+
+function renderTabularPreviewTable(data) {
+  const fields = Array.isArray(data.fields) ? data.fields : null;
+  const rows = Array.isArray(data.rows) ? data.rows : null;
+  if (!fields || !rows) {
+    return undefined;
+  }
+  const headers = previewHeaders(fields);
+  const lines = renderAlignedTable(headers, rows);
+  const rest = withoutKeys(data, ["fields", "rows"]);
+  if (Object.keys(rest).length > 0) {
+    lines.push("---");
+    lines.push(...renderValue(rest, 0));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderTabularPreviewCsv(data) {
+  const fields = Array.isArray(data.fields) ? data.fields : null;
+  const rows = Array.isArray(data.rows) ? data.rows : null;
+  if (!fields || !rows) {
+    return undefined;
+  }
+  const lines = [previewHeaders(fields), ...rows].map((row) => row.map(csvCell).join(","));
+  return `${lines.join("\n")}\n`;
+}
+
+function previewHeaders(fields) {
+  return fields.map((field) => field.displayName || field.transferName || field.name || field.id || "");
+}
+
+function csvCell(value) {
+  const text = stringifyScalar(value);
+  if (/[",\r\n]/.test(text)) {
+    return `"${text.replace(/"/g, "\"\"")}"`;
+  }
+  return text;
+}
+
+function renderAlignedTable(headers, rows) {
+  const values = [headers, ...rows].map((row) => row.map((value) => stringifyScalar(value)));
+  const widths = headers.map((_, columnIndex) => Math.max(...values.map((row) => displayWidth(row[columnIndex] || ""))));
+  return values.map((row) => row.map((value, columnIndex) => padEndDisplay(value, widths[columnIndex])).join("  ").trimEnd());
+}
+
+function padEndDisplay(value, width) {
+  return value + " ".repeat(Math.max(0, width - displayWidth(value)));
+}
+
+function displayWidth(value) {
+  return [...value].reduce((sum, char) => sum + (char.charCodeAt(0) > 127 ? 2 : 1), 0);
+}
+
+function withoutKeys(value, keys) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    return {};
+  }
+  const ignored = new Set(keys);
+  return Object.fromEntries(Object.entries(value).filter(([key]) => !ignored.has(key)));
+}
+
+function renderValue(value, indent, options = {}) {
+  if (Array.isArray(value)) {
+    if (value.length === 0) {
+      return [`${spaces(indent)}[]`];
+    }
+    return value.flatMap((item) => renderArrayItem(item, indent, options));
+  }
+  if (value && typeof value === "object") {
+    const entries = Object.entries(value).filter(([, item]) => {
+      return !(options.omitNullFields === true && (item === null || item === undefined));
+    });
+    if (entries.length === 0) {
+      return [`${spaces(indent)}{}`];
+    }
+    return entries.flatMap(([key, item]) => {
+      if (isScalar(item)) {
+        return [`${spaces(indent)}${key}: ${stringifyScalar(item)}`];
+      }
+      if (Array.isArray(item) && item.length === 0) {
+        return [`${spaces(indent)}${key}: []`];
+      }
+      if (item && typeof item === "object" && Object.keys(item).length === 0) {
+        return [`${spaces(indent)}${key}: {}`];
+      }
+      return [`${spaces(indent)}${key}:`, ...renderValue(item, indent + 2, options)];
+    });
+  }
+  return [`${spaces(indent)}${stringifyScalar(value)}`];
+}
+
+function renderArrayItem(item, indent, options = {}) {
+  if (isScalar(item)) {
+    return [`${spaces(indent)}- ${stringifyScalar(item)}`];
+  }
+  const rendered = renderValue(item, indent + 2, options);
+  if (rendered.length === 0) {
+    return [`${spaces(indent)}-`];
+  }
+  return [`${spaces(indent)}- ${rendered[0].trimStart()}`, ...rendered.slice(1)];
+}
+
+function isDynamicBusinessCommand(command) {
+  return typeof command === "string" && command.includes(".");
+}
+
+function isScalar(value) {
+  return value === null || value === undefined || typeof value !== "object";
+}
+
+function stringifyScalar(value) {
+  if (value === null) {
+    return "null";
+  }
+  if (value === undefined) {
+    return "";
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  if (typeof value === "object") {
+    return JSON.stringify(value);
+  }
+  return String(value);
+}
+
+function spaces(count) {
+  return " ".repeat(count);
+}
+
+function renderConfigGet(config) {
+  const lines = [
+    `base-url: ${config.baseUrl || "(not set)"}`,
+    `timeout-ms: ${config.timeoutMs}`,
+    `capability-ttl-ms: ${config.capabilityTtlMs}`,
+  ];
+  if (config.auth) {
+    lines.push("auth:");
+    lines.push(`  username: ${config.auth.username || "(unknown)"}`);
+    lines.push(`  token: ${config.auth.token || "(not set)"}`);
+    if (config.auth.loginAt) {
+      lines.push(`  login-at: ${config.auth.loginAt}`);
+    }
+    if (config.auth.expiresAt) {
+      lines.push(`  expires-at: ${config.auth.expiresAt}`);
+    }
+    if (config.auth.source) {
+      lines.push(`  source: ${config.auth.source}`);
+    }
+  } else {
+    lines.push("auth: (not logged in)");
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderAuthInfo(data) {
+  const auth = data.auth;
+  if (!auth) {
+    return "Not logged in.\n";
+  }
+  const lines = [
+    `auth-mode: ${data.authMode || "none"}`,
+    `username: ${auth.username || "(unknown)"}`,
+    `token: ${auth.token || "(not set)"}`,
+  ];
+  if (auth.accessKey?.value) {
+    lines.push(`access-key: ${auth.accessKey.value}`);
+  }
+  if (auth.accessKey?.createdAt) {
+    lines.push(`access-key-created-at: ${auth.accessKey.createdAt}`);
+  }
+  if (auth.loginAt) {
+    lines.push(`login-at: ${auth.loginAt}`);
+  }
+  if (auth.expiresAt) {
+    lines.push(`expires-at: ${auth.expiresAt}`);
+  }
+  if (auth.source) {
+    lines.push(`source: ${auth.source}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function renderCapabilityInfo(data) {
+  const lines = [
+    `cache: ${data.hit ? "hit" : "missing"}`,
+    `stale: ${Boolean(data.stale)}`,
+  ];
+  const record = data.cache;
+  if (record) {
+    lines.push(`base-url: ${record.baseUrl || "(unknown)"}`);
+    lines.push(`username: ${record.username || "(unknown)"}`);
+    lines.push(`fetched-at: ${record.fetchedAt || "(unknown)"}`);
+    lines.push(`expires-at: ${record.expiresAt || "(unknown)"}`);
+    lines.push(`ttl-ms: ${record.ttlMs}`);
+    lines.push(`schema-version: ${record.manifest?.schemaVersion || "(unknown)"}`);
+    const resources = record.manifest?.resources || [];
+    lines.push(`resources: ${resources.length}`);
+    lines.push(`commands: ${resources.reduce((sum, resource) => sum + (resource.commands || []).length, 0)}`);
+  } else {
+      lines.push(`hint: ${brandCommandText("Run finebi-cli capability refresh.")}`);
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function readPackageMetadata(context) {
+  if (context.packageMetadata) {
+    return context.packageMetadata;
+  }
+  const packageJsonPath = join(dirname(currentFile), "..", "package.json");
+  return JSON.parse(readFileSync(packageJsonPath, "utf8"));
+}
+
+function firstNonEmpty(...values) {
+  return values.find((value) => typeof value === "string" && value.trim().length > 0)?.trim();
+}
+
+function readStdin() {
+  return new Promise((resolve, reject) => {
+    let text = "";
+    process.stdin.setEncoding("utf8");
+    process.stdin.on("data", (chunk) => {
+      text += chunk;
+    });
+    process.stdin.on("end", () => resolve(text));
+    process.stdin.on("error", reject);
+  });
+}
+
+function isStdinTty(context) {
+  if (typeof context.stdinIsTTY === "boolean") {
+    return context.stdinIsTTY;
+  }
+  return Boolean(process.stdin.isTTY);
+}
+
+function promptHiddenPassword(promptText) {
+  return new Promise((resolve, reject) => {
+    const input = process.stdin;
+    const output = process.stdout;
+    if (!input.setRawMode) {
+      reject(new Error("Interactive password input is not supported by this terminal."));
+      return;
+    }
+    let value = "";
+    output.write(promptText);
+    input.setEncoding("utf8");
+    input.setRawMode(true);
+    input.resume();
+    const cleanup = () => {
+      input.setRawMode(false);
+      input.pause();
+      input.removeListener("data", onData);
+      output.write("\n");
+    };
+    const onData = (chunk) => {
+      if (chunk === "\u0003") {
+        cleanup();
+        reject(new Error("Password input cancelled."));
+        return;
+      }
+      if (chunk === "\r" || chunk === "\n" || chunk === "\r\n") {
+        cleanup();
+        resolve(value);
+        return;
+      }
+      if (chunk === "\b" || chunk === "\u007f") {
+        value = value.slice(0, -1);
+        return;
+      }
+      value += chunk;
+    };
+    input.on("data", onData);
+  });
+}
+
+const currentFile = fileURLToPath(import.meta.url);
+const invokedFile = process.argv[1] ? fileURLToPath(pathToFileURL(process.argv[1])) : "";
+if (isDirectInvocation(currentFile, invokedFile)) {
+  main();
+}
+
+function normalizePath(path) {
+  try {
+    return realpathSync.native(path).replace(/\\/g, "/").toLowerCase();
+  } catch (_error) {
+    return path.replace(/\\/g, "/").toLowerCase();
+  }
+}