@finebi/finebi-cli 1.2.1 → 1.4.0

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

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

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

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

package/src/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/error-catalog.js

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