@finebi/finebi-cli 1.2.1 → 1.4.0

package/skills/finebi-cli-agent/scripts/finebi-cli/src/schema-options.js

@@ -0,0 +1,265 @@
+import {readFileSync, statSync} from "node:fs";
+
+import {cliError} from "./errors.js";
+import {validateSchemaValue} from "./schema-validator.js";
+
+export function buildRequestBody(schema, args) {
+  const parsed = parseArgs(args);
+  if (!parsed.ok) {
+    return parsed;
+  }
+  const properties = schema.properties || {};
+  const argumentFields = Object.keys(properties).filter((fieldName) => properties[fieldName].input === "argument");
+  if (parsed.positionals.length > argumentFields.length) {
+    return invalidArgument(parsed.positionals[argumentFields.length], `Unexpected argument: ${parsed.positionals[argumentFields.length]}.`);
+  }
+  const body = {};
+  for (let index = 0; index < argumentFields.length; index += 1) {
+    const fieldName = argumentFields[index];
+    if (parsed.positionals[index] !== undefined) {
+      const coerced = coerceValue(fieldName, parsed.positionals[index], properties[fieldName]);
+      if (!coerced.ok) {
+        return coerced;
+      }
+      body[fieldName] = coerced.value;
+    }
+  }
+  for (const fieldName of Object.keys(body)) {
+    const validation = validateValue(fieldName, body[fieldName], properties[fieldName]);
+    if (!validation.ok) {
+      return validation;
+    }
+  }
+  for (const fieldName of Object.keys(properties)) {
+    const property = properties[fieldName];
+    const optionName = optionNameFor(fieldName, property);
+    if (property.input === "argument" && body[fieldName] !== undefined) {
+      continue;
+    }
+    if (Object.prototype.hasOwnProperty.call(parsed.options, optionName)) {
+      const coerced = coerceValue(fieldName, parsed.options[optionName], property);
+      if (!coerced.ok) {
+        return coerced;
+      }
+      body[fieldName] = coerced.value;
+    } else {
+      const defaultValue = property.defaultValue ?? property.default;
+      if (defaultValue !== undefined && (defaultValue !== "" || property.hasDefault === true)) {
+        const coerced = coerceValue(fieldName, defaultValue, property);
+        if (!coerced.ok) {
+          return coerced;
+        }
+        body[fieldName] = coerced.value;
+      }
+    }
+    if (body[fieldName] !== undefined) {
+      const validation = validateValue(fieldName, body[fieldName], property);
+      if (!validation.ok) {
+        return validation;
+      }
+    }
+  }
+  for (const optionName of Object.keys(parsed.options)) {
+    if (!Object.keys(properties).some((fieldName) => optionNameFor(fieldName, properties[fieldName]) === optionName)) {
+      return invalidArgument(`--${optionName}`, `Unknown option: --${optionName}.`);
+    }
+  }
+  for (const requiredField of schema.required || []) {
+    if (body[requiredField] === undefined) {
+      return invalidArgument(requiredField, `Missing required option: --${camelToKebab(requiredField)}.`);
+    }
+  }
+  return {
+    ok: true,
+    body,
+  };
+}
+
+function parseArgs(args) {
+  const options = {};
+  const positionals = [];
+  for (let index = 0; index < args.length; index += 1) {
+    const current = args[index];
+    if (!current.startsWith("--")) {
+      positionals.push(current);
+      continue;
+    }
+    const optionName = current.slice(2);
+    const next = args[index + 1];
+    if (next === undefined || next.startsWith("--")) {
+      options[optionName] = true;
+    } else {
+      options[optionName] = next;
+      index += 1;
+    }
+  }
+  return {
+    ok: true,
+    options,
+    positionals,
+  };
+}
+
+function coerceValue(fieldName, value, property) {
+  if (property.input === "file" || property.file) {
+    if (typeof value !== "string" || value.trim() === "") {
+      return invalidArgument(fieldName, `Expected a file path for ${fieldName}.`);
+    }
+    const contentType = fileContentType(property);
+    if (contentType === "BINARY") {
+      try {
+        if (!statSync(value).isFile()) {
+          return invalidArgument(fieldName, `Expected a regular file for ${fieldName}.`);
+        }
+      } catch (error) {
+        return invalidArgument(fieldName, `Failed to read BINARY file for ${fieldName}: ${error.message}`);
+      }
+      return {ok: true, value};
+    }
+    let contents;
+    try {
+      contents = readFileSync(value, "utf8");
+    } catch (error) {
+      return invalidArgument(fieldName, `Failed to read ${contentType} file for ${fieldName}: ${error.message}`);
+    }
+    // TEXT 是不可信源码的透明传输协议；CLI 不执行，也不做 JSON/schema 解释。
+    if (fileContentType(property) === "TEXT") {
+      return { ok: true, value: contents };
+    }
+    let parsed;
+    try {
+      parsed = JSON.parse(contents);
+    } catch (error) {
+      return invalidJson(fieldName, `Invalid JSON syntax in file for ${fieldName}: ${error.message}`);
+    }
+    if (property.schema) {
+      const validation = validateSchemaValue(parsed, property.schema, fieldName);
+      if (!validation.ok) {
+        return validation;
+      }
+    }
+    return { ok: true, value: parsed };
+  }
+  const type = property.type;
+  if (type === "array") {
+    let parsed = value;
+    if (typeof value === "string") {
+      try {
+        parsed = JSON.parse(value);
+      } catch (error) {
+        return invalidArgument(fieldName, `Expected a JSON array for ${fieldName}.`);
+      }
+    }
+    const validation = validateSchemaValue(parsed, property, fieldName);
+    return validation.ok ? {ok: true, value: parsed} : validation;
+  }
+  if (type === "integer") {
+    if (typeof value === "number" && Number.isInteger(value)) {
+      return { ok: true, value };
+    }
+    if (typeof value !== "string" || !/^-?\d+$/.test(value.trim())) {
+      return invalidArgument(fieldName, `Expected an integer value for ${fieldName}.`);
+    }
+    return { ok: true, value: Number.parseInt(value, 10) };
+  }
+  if (type === "number") {
+    const numberValue = Number(value);
+    if (!Number.isFinite(numberValue)) {
+      return invalidArgument(fieldName, `Expected a numeric value for ${fieldName}.`);
+    }
+    return { ok: true, value: numberValue };
+  }
+  if (type === "boolean") {
+    if (typeof value === "boolean") {
+      return { ok: true, value };
+    }
+    return { ok: true, value: value === "true" };
+  }
+  if (type === "string" && typeof value !== "string") {
+    return invalidArgument(fieldName, `Expected a string value for ${fieldName}.`);
+  }
+  const enumValues = property.enumValues || property.enum || [];
+  if (type === "string" && enumValues.length > 0 && typeof value === "string") {
+    const matched = enumValues.find((enumValue) => enumValue.toLowerCase() === value.toLowerCase());
+    if (matched !== undefined) {
+      return { ok: true, value: matched };
+    }
+  }
+  return { ok: true, value };
+}
+
+function fileContentType(property) {
+  return String(property.fileContentType || "JSON").toUpperCase();
+}
+
+function validateValue(fieldName, value, property) {
+  if ((property.type === "integer" || property.type === "number") && !Number.isFinite(value)) {
+    return invalidArgument(fieldName, `Invalid numeric value for ${fieldName}.`);
+  }
+  if (property.type === "integer" && !Number.isInteger(value)) {
+    return invalidArgument(fieldName, `Invalid integer value for ${fieldName}.`);
+  }
+  if (property.minimum !== undefined && property.minimum !== null && value < Number(property.minimum)) {
+    return invalidArgument(fieldName, `${fieldName} must be greater than or equal to ${property.minimum}.`);
+  }
+  if (property.maximum !== undefined && property.maximum !== null && value > Number(property.maximum)) {
+    return invalidArgument(fieldName, `${fieldName} must be less than or equal to ${property.maximum}.`);
+  }
+  if (property.type === "string" && property.minLength !== undefined && property.minLength !== null
+      && value.length < Number(property.minLength)) {
+    return invalidArgument(fieldName, `${fieldName} must contain at least ${property.minLength} character(s).`);
+  }
+  if (property.type === "string" && property.maxLength !== undefined && property.maxLength !== null
+      && value.length > Number(property.maxLength)) {
+    return invalidArgument(fieldName, `${fieldName} must contain at most ${property.maxLength} character(s).`);
+  }
+  if (property.type === "string" && property.pattern && !new RegExp(property.pattern).test(value)) {
+    return invalidArgument(fieldName, `${fieldName} must match ${property.pattern}.`);
+  }
+  const constValue = property.constValue ?? property.const;
+  if (constValue !== undefined && constValue !== null && value !== constValue) {
+    return invalidArgument(fieldName, `${fieldName} must equal ${JSON.stringify(constValue)}.`);
+  }
+  const enumValues = property.enumValues || property.enum || [];
+  if (enumValues.length > 0 && !enumValues.includes(value)) {
+    return invalidArgument(fieldName, `${fieldName} must be one of: ${enumValues.join(", ")}.`);
+  }
+  return { ok: true };
+}
+
+function invalidArgument(path, message) {
+  return {
+    ok: false,
+      error: cliError("INVALID_ARGUMENT", {
+      path,
+      message,
+      hint: "Run the command with --help to check supported options.",
+      retryable: false,
+      nextActions: ["finebi-cli --help"],
+      }),
+  };
+}
+
+function invalidJson(path, message) {
+  return {
+    ok: false,
+    error: cliError("INVALID_JSON", {
+      path,
+      message,
+      hint: "Fix the JSON syntax and rerun the command.",
+      retryable: false,
+      nextActions: ["finebi-cli --help"],
+    }),
+  };
+}
+
+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);
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/schema-validator.js

@@ -0,0 +1,194 @@
+import {cliError} from "./errors.js";
+
+export function validateSchemaValue(value, schema, path) {
+  const effectiveSchema = schema || {};
+  // nullable 是 capability 显式声明的字段级约束；required 只控制字段是否必须出现。
+  if (value === null && effectiveSchema.nullable === true) {
+    return { ok: true };
+  }
+  const typeError = validateType(value, effectiveSchema, path);
+  if (typeError) {
+    return typeError;
+  }
+
+  if (effectiveSchema.discriminator && Array.isArray(effectiveSchema.variants)) {
+    return validateDiscriminator(value, effectiveSchema, path);
+  }
+
+  if (effectiveSchema.type === "object") {
+    return validateObject(value, effectiveSchema, path);
+  }
+  if (effectiveSchema.type === "array") {
+    return validateArray(value, effectiveSchema, path);
+  }
+  return validateScalar(value, effectiveSchema, path);
+}
+
+function validateType(value, schema, path) {
+  switch (schema.type) {
+    case "object":
+      if (!isPlainObject(value)) {
+        return invalidRequestJson(path, `Expected object at "${path}".`);
+      }
+      return null;
+    case "array":
+      if (!Array.isArray(value)) {
+        return invalidRequestJson(path, `Expected array at "${path}".`);
+      }
+      return null;
+    case "string":
+      if (typeof value !== "string") {
+        return invalidRequestJson(path, `Expected string at "${path}".`);
+      }
+      return null;
+    case "integer":
+      if (!Number.isInteger(value)) {
+        return invalidRequestJson(path, `Expected integer at "${path}".`);
+      }
+      return null;
+    case "number":
+      if (typeof value !== "number" || !Number.isFinite(value)) {
+        return invalidRequestJson(path, `Expected number at "${path}".`);
+      }
+      return null;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return invalidRequestJson(path, `Expected boolean at "${path}".`);
+      }
+      return null;
+    default:
+      return null;
+  }
+}
+
+function validateDiscriminator(value, schema, path) {
+  const discriminator = schema.discriminator;
+  const discriminatorPath = joinPath(path, discriminator);
+  if (!Object.prototype.hasOwnProperty.call(value, discriminator)) {
+    return invalidRequestJson(discriminatorPath, `Missing discriminator field "${discriminator}".`);
+  }
+  const discriminatorValue = value[discriminator];
+  const variant = schema.variants.find((item) => item.value === discriminatorValue);
+  if (!variant) {
+    return invalidRequestJson(
+      discriminatorPath,
+      `Unsupported discriminator value "${discriminatorValue}" for "${discriminator}". Expected one of: ${schema.variants.map((item) => item.value).join(", ")}.`,
+    );
+  }
+  const validation = validateSchemaValue(value, variant.schema, path);
+  if (!validation.ok && validation.error.message.startsWith("Unsupported field ")) {
+    return {
+      ok: false,
+      error: {
+        ...validation.error,
+        message: `${validation.error.message.slice(0, -1)} for discriminator "${discriminator}" value "${discriminatorValue}".`,
+      },
+    };
+  }
+  return validation;
+}
+
+function validateObject(value, schema, path) {
+  const properties = schema.properties || {};
+  for (const requiredField of schema.required || []) {
+    if (!Object.prototype.hasOwnProperty.call(value, requiredField)) {
+      return invalidRequestJson(joinPath(path, requiredField), `Missing required field "${requiredField}".`);
+    }
+  }
+  if (Object.keys(properties).length > 0) {
+    for (const fieldName of Object.keys(value)) {
+      if (!Object.prototype.hasOwnProperty.call(properties, fieldName)) {
+        return invalidRequestJson(joinPath(path, fieldName), `Unsupported field "${fieldName}".`);
+      }
+    }
+  }
+  for (const fieldName of Object.keys(properties)) {
+    if (!Object.prototype.hasOwnProperty.call(value, fieldName)) {
+      continue;
+    }
+    const validation = validateSchemaValue(value[fieldName], nestedSchema(properties[fieldName]), joinPath(path, fieldName));
+    if (!validation.ok) {
+      return validation;
+    }
+  }
+  return { ok: true };
+}
+
+function validateArray(value, schema, path) {
+  if (schema.minItems !== undefined && schema.minItems !== null && value.length < Number(schema.minItems)) {
+    return invalidRequestJson(path, `"${path}" must contain at least ${schema.minItems} item(s).`);
+  }
+  const itemSchema = schema.items;
+  if (!itemSchema) {
+    return { ok: true };
+  }
+  for (let index = 0; index < value.length; index += 1) {
+    const validation = validateSchemaValue(value[index], nestedSchema(itemSchema), `${path}[${index}]`);
+    if (!validation.ok) {
+      return validation;
+    }
+  }
+  return { ok: true };
+}
+
+function validateScalar(value, schema, path) {
+  const constValue = schema.constValue ?? schema.const;
+  if (constValue !== undefined && constValue !== null && value !== constValue) {
+    return invalidRequestJson(path, `"${path}" must equal ${JSON.stringify(constValue)}.`);
+  }
+  const enumValues = schema.enumValues || schema.enum || [];
+  if (enumValues.length > 0 && !enumValues.includes(value)) {
+    return invalidRequestJson(path, `"${path}" must be one of: ${enumValues.join(", ")}.`);
+  }
+  if ((schema.type === "integer" || schema.type === "number") && schema.minimum !== undefined && schema.minimum !== null && value < Number(schema.minimum)) {
+    return invalidRequestJson(path, `"${path}" must be greater than or equal to ${schema.minimum}.`);
+  }
+  if ((schema.type === "integer" || schema.type === "number") && schema.maximum !== undefined && schema.maximum !== null && value > Number(schema.maximum)) {
+    return invalidRequestJson(path, `"${path}" must be less than or equal to ${schema.maximum}.`);
+  }
+  if (schema.type === "string" && schema.pattern && !new RegExp(schema.pattern).test(value)) {
+    return invalidRequestJson(path, `"${path}" must match pattern ${schema.pattern}.`);
+  }
+  if (schema.type === "string" && schema.minLength !== undefined && schema.minLength !== null
+      && value.length < Number(schema.minLength)) {
+    return invalidRequestJson(path, `"${path}" must contain at least ${schema.minLength} character(s).`);
+  }
+  if (schema.type === "string" && schema.maxLength !== undefined && schema.maxLength !== null
+      && value.length > Number(schema.maxLength)) {
+    return invalidRequestJson(path, `"${path}" must contain at most ${schema.maxLength} character(s).`);
+  }
+  return { ok: true };
+}
+
+function nestedSchema(property) {
+  if (!property.schema) {
+    return property;
+  }
+  return {
+    ...property.schema,
+    nullable: property.nullable ?? property.schema.nullable,
+    discriminator: property.discriminator ?? property.schema.discriminator,
+    variants: property.variants ?? property.schema.variants,
+  };
+}
+
+function joinPath(base, fieldName) {
+  return base ? `${base}.${fieldName}` : fieldName;
+}
+
+function isPlainObject(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+
+function invalidRequestJson(path, message) {
+  return {
+    ok: false,
+      error: cliError("INVALID_REQUEST_JSON", {
+      path,
+      message,
+      hint: "Remove unsupported fields or check the command schema.",
+      retryable: false,
+      nextActions: ["finebi-cli --help"],
+      }),
+  };
+}

package/skills/finebi-cli-agent/scripts/finebi-cli/src/skill-files.js

@@ -0,0 +1,94 @@
+import {createHash, randomUUID} from "node:crypto";
+import {existsSync} from "node:fs";
+import {cp, mkdir, lstat, mkdtemp, readFile, readdir, rename, rm} from "node:fs/promises";
+import {homedir} from "node:os";
+import {join, dirname, resolve} from "node:path";
+
+export function agentCatalog({home = homedir(), env = process.env} = {}) {
+  const config = env.XDG_CONFIG_HOME || join(home, ".config");
+  return [
+    ["claude-code", "Claude Code", env.CLAUDE_CONFIG_DIR || join(home, ".claude")],
+    ["codex", "Codex", env.CODEX_HOME || join(home, ".codex")],
+    ["cursor", "Cursor", join(home, ".cursor")],
+    ["gemini-cli", "Gemini CLI", join(home, ".gemini")],
+    ["github-copilot", "GitHub Copilot", join(home, ".copilot")],
+    ["opencode", "OpenCode", join(config, "opencode")],
+    ["cline", "Cline", join(home, ".agents")],
+    ["windsurf", "Windsurf", join(home, ".codeium", "windsurf")],
+    ["trae", "Trae", join(home, ".trae")],
+    ["trae-cn", "Trae CN", join(home, ".trae-cn")],
+    ["openclaw", "OpenClaw", [".openclaw", ".clawdbot", ".moltbot"].map(p => join(home, p)).find(existsSync) || join(home, ".openclaw")],
+    ["roo", "Roo Code", join(home, ".roo")],
+    ["qwen-code", "Qwen Code", join(home, ".qwen")],
+  ].map(([id, name, root]) => ({id, name, directory: join(root, "skills"), detected: existsSync(root)}));
+}
+
+export async function hashTree(root, prefix = "") {
+  const files = {};
+  for (const entry of (await readdir(join(root, prefix), {withFileTypes: true})).sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isSymbolicLink()) throw new Error(`Skill contains a symbolic link: ${name}`);
+    if (entry.isDirectory()) Object.assign(files, await hashTree(root, name));
+    else files[name] = createHash("sha256").update(await readFile(join(root, name))).digest("hex");
+  }
+  return files;
+}
+
+function sameHashes(left, right) {
+  return left && right && Object.keys(left).length === Object.keys(right).length
+    && Object.keys(left).every(key => left[key] === right[key]);
+}
+
+export async function installSkills({source, home, env, agents, replace = false, previous = []}) {
+  const catalog = agentCatalog({home, env});
+  const selected = agents.map(id => {
+    const agent = catalog.find(item => item.id === id);
+    if (!agent) throw new Error(`Unknown Agent: ${id}`);
+    return agent;
+  });
+  const sourceHashes = await hashTree(source);
+  const results = [];
+  for (const agent of selected) {
+    const target = join(agent.directory, "finebi-cli-agent");
+    let backup;
+    let candidate;
+    try {
+      const stat = await lstat(target).catch(error => { if (error.code !== "ENOENT") throw error; });
+      if (stat) {
+        if (stat.isSymbolicLink()) throw new Error("Skill target is a symbolic link; refusing to replace it.");
+        const actual = await hashTree(target);
+        if (sameHashes(sourceHashes, actual)) {
+          results.push({agent: agent.id, path: target, status: "unchanged", hashes: sourceHashes});
+          continue;
+        }
+        const recorded = previous.find(item => item.agent === agent.id && item.path === target)?.hashes;
+        if (!replace && !sameHashes(recorded, actual)) {
+          results.push({agent: agent.id, path: target, status: "kept"});
+          continue;
+        }
+        backup = join(home, ".finebi-cli", "skill-backups", `${agent.id}-${randomUUID()}`);
+        await mkdir(dirname(backup), {recursive: true});
+        await cp(target, backup, {recursive: true, errorOnExist: true, force: false});
+        if (!sameHashes(actual, await hashTree(backup))) throw new Error("Skill backup integrity check failed.");
+      }
+      await mkdir(agent.directory, {recursive: true});
+      candidate = await mkdtemp(join(agent.directory, ".finebi-cli-stage-"));
+      await cp(source, candidate, {recursive: true});
+      if (!sameHashes(sourceHashes, await hashTree(candidate))) throw new Error("Skill copy integrity check failed.");
+      const old = `${candidate}-old`;
+      if (stat) await rename(target, old);
+      try { await rename(candidate, target); }
+      catch (error) { if (stat) await rename(old, target); throw error; }
+      candidate = undefined;
+      // Delete only the relocated, backed-up directory inside this Agent's skills directory.
+      if (stat && backup && dirname(resolve(old)) === resolve(agent.directory)) await rm(old, {recursive: true});
+      if (!sameHashes(sourceHashes, await hashTree(target))) throw new Error("Installed Skill integrity check failed.");
+      results.push({agent: agent.id, path: target, status: "installed", hashes: sourceHashes, ...(backup ? {backup} : {})});
+    } catch (error) {
+      results.push({agent: agent.id, path: target, status: "failed", error: error.message, ...(backup ? {backup} : {})});
+    } finally {
+      if (candidate && dirname(resolve(candidate)) === resolve(agent.directory)) await rm(candidate, {recursive: true, force: true});
+    }
+  }
+  return results;
+}