@finebi/finebi-cli 1.2.0

package/src/help.js

@@ -0,0 +1,452 @@
+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."},
+];
+
+export function renderTopLevelHelp(manifest) {
+  return success("help", {
+    resources: (manifest?.resources || []).map((resource) => ({
+      name: resource.name,
+      summary: resource.summary,
+    })),
+    dynamicCapabilitiesLoaded: Boolean(manifest),
+    globalOptions: GLOBAL_OPTIONS,
+  }, { schemaVersion: manifest?.schemaVersion });
+}
+
+export function renderBuiltInHelp(resourceName) {
+  const resource = BUILT_IN_RESOURCES[resourceName];
+  if (!resource) {
+    return capabilityNotFound(resourceName);
+  }
+    return success("help", brandCommandValue({...resource, globalOptions: GLOBAL_OPTIONS}));
+}
+
+export function renderBuiltInCommandHelp(resourceName, commandName) {
+  const resource = BUILT_IN_RESOURCES[resourceName];
+  const command = resource?.commands?.find((item) => item.name === commandName);
+  if (!resource || !command) {
+    return capabilityNotFound(`${resourceName}.${commandName}`);
+  }
+    return success("help", brandCommandValue({
+    resource: resource.resource,
+    command: command.name,
+    summary: command.summary,
+    usage: command.usage,
+    options: command.options || [],
+    globalOptions: GLOBAL_OPTIONS,
+    details: command.details || [],
+    examples: command.examples || [],
+    }));
+}
+
+export function renderResourceHelp(manifest, resourceName) {
+  const resource = findResource(manifest, resourceName);
+  if (!resource) {
+    return capabilityNotFound(resourceName);
+  }
+  return success("help", {
+    resource: resource.name,
+    summary: resource.summary,
+    globalOptions: GLOBAL_OPTIONS,
+    commands: (resource.commands || []).map((command) => ({
+      name: command.name,
+      summary: command.summary,
+    })),
+  }, { schemaVersion: manifest.schemaVersion });
+}
+
+export function renderCommandHelp(manifest, resourceName, commandName) {
+  const resource = findResource(manifest, resourceName);
+  const command = resource?.commands?.find((item) => item.name === commandName);
+  if (!resource || !command) {
+    return capabilityNotFound(`${resourceName}.${commandName}`);
+  }
+  return success("help", {
+    resource: resource.name,
+    command: command.name,
+    summary: command.summary,
+    usage: usageFor(resource.name, command),
+    options: commandOptionsFor(command),
+    globalOptions: GLOBAL_OPTIONS,
+    display: command.display,
+    requestSchema: command.requestSchema,
+    responseSchema: command.responseSchema,
+  }, { schemaVersion: manifest.schemaVersion });
+}
+
+export function renderHelpText(envelope) {
+  if (!envelope.ok) {
+    return renderErrorText(envelope);
+  }
+  const data = envelope.data || {};
+  if (data.usage) {
+    return renderCommandHelpText(data);
+  }
+  if (data.commands) {
+    return renderResourceHelpText(data);
+  }
+  return renderTopLevelHelpText(data);
+}
+
+function findResource(manifest, resourceName) {
+  return (manifest.resources || []).find((resource) => resource.name === resourceName);
+}
+
+const BUILT_IN_RESOURCES = {
+  version: {
+    command: "version",
+    resource: "version",
+    summary: "Show FineBI CLI version.",
+    usage: "finebi-cli version",
+  },
+  capabilities: {
+    command: "capabilities",
+    resource: "capabilities",
+    summary: "Fetch FineBI dynamic capabilities and update the local cache.",
+    usage: "finebi-cli capabilities",
+  },
+  config: {
+    resource: "config",
+    summary: "Local FineBI CLI configuration.",
+    commands: [
+      {
+        name: "get",
+        summary: "Show local configuration with secrets masked.",
+        usage: "finebi-cli config get",
+      },
+      {
+        name: "set",
+        summary: "Set base-url, timeout-ms, or capability-ttl-ms.",
+        usage: "finebi-cli config set <key> <value>",
+        details: [
+          "Keys:",
+          "  base-url",
+          "  timeout-ms",
+          "  capability-ttl-ms",
+        ],
+        examples: [
+          "finebi-cli config set base-url http://localhost:37799/webroot/decision",
+          "finebi-cli config set timeout-ms 30000",
+          "finebi-cli config set capability-ttl-ms 600000",
+        ],
+      },
+      {
+        name: "clear",
+        summary: "Remove the selected environment's local configuration, credentials and capability cache; does not revoke server keys.",
+        usage: "finebi-cli config clear",
+      },
+    ],
+  },
+  auth: {
+    resource: "auth",
+    summary: "FineBI authentication commands.",
+    commands: [
+      {
+        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." },
+          { 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.",
+          "Environment variables for --from-env:",
+          "  FINEBI_BASE_URL",
+          "  FINEBI_USERNAME",
+          "  FINEBI_PASSWORD",
+          "Browser authorization opens a same-server confirmation URL and polls until it is approved, denied, or expires.",
+          "Successful login refreshes the dynamic capability cache automatically.",
+        ],
+        examples: [
+          "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",
+        ],
+      },
+      {
+        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",
+      },
+      {
+        name: "logout",
+        summary: "Revoke the Access Key before removing stored authentication.",
+        usage: "finebi-cli auth logout [--force]",
+        options: [
+          { name: "--force", type: "boolean", description: "Remove local credentials even when server-side revocation fails." },
+        ],
+      },
+    ],
+  },
+  capability: {
+    resource: "capability",
+    summary: "FineBI dynamic capability cache commands.",
+    commands: [
+      {
+        name: "refresh",
+        summary: "Fetch dynamic command capabilities from FineBI.",
+        usage: "finebi-cli capability refresh",
+        details: [
+          "Requires:",
+          "  finebi-cli config set base-url <baseUrl>",
+          "  finebi-cli auth login --username <username>",
+          "Login refreshes capabilities automatically; use this command when backend commands changed or the cache expired.",
+        ],
+      },
+      {
+        name: "info",
+        summary: "Show capability cache status.",
+        usage: "finebi-cli capability info",
+      },
+      {
+        name: "clear-cache",
+        summary: "Remove the local capability cache.",
+        usage: "finebi-cli capability clear-cache",
+      },
+    ],
+  },
+};
+
+function capabilityNotFound(path) {
+    return failure("help", cliError("CAPABILITY_NOT_FOUND", {
+    path,
+    message: `Capability not found: ${path}.`,
+    hint: "Run finebi-cli capability refresh and check finebi-cli --help.",
+    retryable: true,
+    nextActions: ["finebi-cli capability refresh", "finebi-cli --help"],
+    }));
+}
+
+function usageFor(resourceName, command) {
+  const options = optionsFor(command.requestSchema || { properties: {}, required: [] });
+  const argumentsText = argumentsFor(command.requestSchema || { properties: {}, required: [] }).map((argument) => {
+    return argument.required ? `<${argument.name}>` : `[${argument.name}]`;
+  });
+  const usageOptions = options.map((option) => {
+    const placeholder = option.type === "file" ? "file" : option.name.slice(2);
+    const argument = `${option.name} <${placeholder}>`;
+    return option.required ? argument : `[${argument}]`;
+  });
+    return [CLI_COMMAND_NAME, resourceName, command.name].concat(argumentsText).concat(usageOptions).join(" ");
+}
+
+function commandOptionsFor(command) {
+  return optionsFor(command.requestSchema || { properties: {}, required: [] }).concat([
+    {
+      name: "-f, --format",
+      required: false,
+      type: "format",
+      description: "Output format for dynamic command display: auto, table, expanded, or csv.",
+      default: "auto",
+    },
+  ]);
+}
+
+function optionsFor(schema) {
+  const required = schema.required || [];
+  return Object.keys(schema.properties || {}).filter((fieldName) => schema.properties[fieldName].input !== "argument").map((fieldName) => {
+    const property = schema.properties[fieldName];
+    const optionName = optionNameFor(fieldName, property);
+    const option = {
+      name: `--${optionName}`,
+      required: required.includes(fieldName),
+      type: property.file || property.input === "file" ? "file" : property.type,
+      description: property.description || "",
+    };
+    const enumValues = property.enumValues || property.enum || [];
+    if (enumValues.length > 0) {
+      option.enumValues = enumValues;
+    }
+    const defaultValue = property.defaultValue ?? property.default;
+    if (defaultValue !== undefined && defaultValue !== "") {
+      option.default = defaultValue;
+    }
+    return option;
+  });
+}
+
+function argumentsFor(schema) {
+  const required = schema.required || [];
+  return Object.keys(schema.properties || {}).filter((fieldName) => schema.properties[fieldName].input === "argument").map((fieldName) => ({
+    name: fieldName,
+    required: required.includes(fieldName),
+    description: schema.properties[fieldName].description || "",
+  }));
+}
+
+function camelToKebab(value) {
+  return value.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+}
+
+function optionNameFor(fieldName, property) {
+  if (property.input === "file" || property.file) {
+    return property.option || "file";
+  }
+  return camelToKebab(fieldName);
+}
+
+function renderTopLevelHelpText(data) {
+  const resources = data.resources || [];
+  const firstResourceName = resources[0]?.name;
+    const resourceHelpStep = firstResourceName ? commandLine(firstResourceName, "--help") : commandLine("--help");
+  const lines = [
+      CLI_DISPLAY_NAME,
+    "",
+    "Usage:",
+      `  ${commandLine("<resource>", "<command>", "[options]")}`,
+      `  ${commandLine("<resource>", "--help")}`,
+      `  ${commandLine("<resource>", "<command>", "--help")}`,
+    "",
+    "Getting Started:",
+      `  1. ${commandLine("config", "set", "base-url", "<baseUrl>")}`,
+      `  2. ${commandLine("auth", "login", "--username", "<username>")}`,
+    `  3. ${resourceHelpStep}`,
+    "  Login refreshes dynamic capabilities automatically.",
+      `  Run ${commandLine("capability", "refresh")} when backend commands changed or the cache expired.`,
+    "",
+    "Resources:",
+  ];
+  lines.push(...formatRows(resources, "name", "summary"));
+  if (!data.dynamicCapabilitiesLoaded) {
+      lines.push(`  Dynamic resources are not loaded yet. Login or run ${commandLine("capability", "refresh")} after login.`);
+  }
+  lines.push(
+    "",
+    "Common Commands:",
+      `  ${commandLine("version")}`,
+      `  ${commandLine("capabilities")}`,
+      `  ${commandLine("config", "get")}`,
+      `  ${commandLine("config", "set", "base-url", "<baseUrl>")}`,
+      `  ${commandLine("auth", "login", "--username", "<username>")}`,
+      `  ${commandLine("auth", "login", "--from-env")}`,
+      `  ${commandLine("capability", "refresh")}`,
+    "",
+    "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 || []));
+  return `${lines.join("\n")}\n`;
+}
+
+function renderResourceHelpText(data) {
+  const lines = [
+    data.resource,
+    "",
+    data.summary || "",
+    "",
+    "Usage:",
+      `  ${commandLine(data.resource, "<command>", "[options]")}`,
+      `  ${commandLine(data.resource, "<command>", "--help")}`,
+    "",
+    "Commands:",
+  ];
+  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`;
+}
+
+function renderCommandHelpText(data) {
+  const title = data.resource && data.resource !== data.command ? `${data.resource} ${data.command}` : data.command;
+  const lines = [
+    title,
+    "",
+    data.summary || "",
+    "",
+    "Usage:",
+    `  ${data.usage}`,
+  ];
+  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.details || []).length > 0) {
+    lines.push("", ...data.details);
+  }
+  if ((data.examples || []).length > 0) {
+    lines.push("", "Examples:");
+    lines.push(...data.examples.map((example) => `  ${example}`));
+  }
+  lines.push("", "Use --json for structured output.",
+      "Output options: --select <paths> / --max-chars <n> / --save <path> for large responses.");
+  return `${lines.join("\n")}\n`;
+}
+
+function renderErrorText(envelope) {
+  const error = envelope.errors?.[0] || {};
+  const lines = [
+    `Error: ${error.message || "Command failed."}`,
+  ];
+  if (error.hint) {
+    lines.push(`Hint: ${error.hint}`);
+  }
+  if ((error.nextActions || []).length > 0) {
+    lines.push("", "Next Actions:");
+    lines.push(...error.nextActions.map((action) => `  ${action}`));
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+function formatRows(items, nameKey, summaryKey) {
+  if (items.length === 0) {
+    return ["  (none)"];
+  }
+  const width = Math.max(...items.map((item) => String(item[nameKey] || "").length));
+  return items.map((item) => `  ${String(item[nameKey] || "").padEnd(width + 2)}${item[summaryKey] || ""}`);
+}
+
+function formatOptionRows(options) {
+  const optionTexts = options.map((option) => `${option.name} <${option.type || "value"}>`);
+  const width = Math.max(...optionTexts.map((item) => item.length));
+  return options.map((option, index) => {
+    const parts = [];
+    if (option.description) {
+      parts.push(option.description);
+    }
+    if (option.required) {
+      parts.push("Required.");
+    }
+    if (option.default !== undefined) {
+      parts.push(`Default: ${option.default}.`);
+    }
+    if ((option.enumValues || []).length > 0) {
+      parts.push(`Values: ${option.enumValues.join(", ")}.`);
+    }
+    return `  ${optionTexts[index].padEnd(width + 2)}${parts.join(" ")}`;
+  });
+}