@capybara-hq/plugin-tools 0.0.0-stage → 0.1.0-rc.1

package/dist/check/tool-design.d.ts

@@ -0,0 +1,13 @@
+import { type Finding } from "./source.js";
+export type { Finding };
+/**
+ * 工具设计检查（AST）。规则：
+ * - tool-description：`ctx.tools.register(spec, …)` 与 `BuiltinTool` 字面量（有 spec 与 run）里的 spec
+ *   必须有字符串字面量 description（可 `+` 拼接）、不少于 20 字符、不含中文（模型可见文案一律英文）；
+ * - tool-error-actionable：`new ToolError(msg)` 的 msg 是字符串字面量 / 模板（或本文件内的常量、函数返回值），
+ *   且含建议动词 use / call / retry / check / ask / pass / provide 之一，让模型知道下一步做什么。
+ * spec 可以直接写对象字面量，也可以引用本文件内的 const；其他写法（跨文件、动态构造）报 tool-description。
+ * 已知缺口：从别的文件导入的消息常量 / 函数不追踪；非 ToolError 类的错误不查；运行时拼出的 spec 不查。
+ * 扫描：传入目录下的非测试源码。
+ */
+export declare function checkToolDesign(dirs: string[]): Finding[];

package/dist/check/tool-design.js

@@ -0,0 +1,227 @@
+import { isParseError, listSourceFiles, parseFile, stringValue, walk, } from "./source.js";
+const MIN_DESCRIPTION = 20;
+const CJK = /[㐀-鿿豈-﫿　-〿＀-￯]/;
+/** 可执行的建议动词：错误信息里至少出现其一（整词、不分大小写）。 */
+const ACTION_VERB = /\b(?:use|call|retry|check|ask|pass|provide)\b/i;
+const WRAPPERS = new Set([
+    "ParenthesizedExpression",
+    "TSAsExpression",
+    "TSSatisfiesExpression",
+    "TSNonNullExpression",
+    "TSTypeAssertion",
+]);
+function unwrap(n) {
+    let cur = n;
+    while (WRAPPERS.has(cur.type))
+        cur = cur.expression;
+    return cur;
+}
+const propName = (p) => {
+    if (p.type !== "Property" || p.computed)
+        return undefined;
+    const k = p.key;
+    if (k.type === "Identifier")
+        return k.name;
+    if (k.type === "Literal" && typeof k.value === "string")
+        return k.value;
+    return undefined;
+};
+function prop(obj, name) {
+    for (const p of obj.properties)
+        if (propName(p) === name)
+            return p;
+    return undefined;
+}
+function buildEnv(f) {
+    const decls = new Map();
+    const imported = new Set();
+    walk(f.program, (n) => {
+        if (n.type === "VariableDeclarator") {
+            const id = n.id;
+            if (id.type === "Identifier" && n.init)
+                decls.set(id.name, n.init);
+        }
+        else if (n.type === "FunctionDeclaration") {
+            const id = n.id;
+            if (id)
+                decls.set(id.name, n);
+        }
+        else if (n.type === "ImportDeclaration") {
+            for (const s of n.specifiers)
+                imported.add(s.local.name ?? "");
+        }
+    });
+    return { decls, imported };
+}
+/** 把消息表达式尽量还原成静态文本：字面量、模板、`+` 拼接、本地常量、本地函数的返回值。 */
+function resolveText(n, env, depth = 0) {
+    if (depth > 5)
+        return { kind: "dynamic" };
+    const e = unwrap(n);
+    const lit = stringValue(e);
+    if (lit !== undefined)
+        return { kind: "text", text: lit };
+    if (e.type === "TemplateLiteral") {
+        const quasis = e.quasis;
+        return { kind: "text", text: quasis.map((q) => q.value.cooked ?? "").join(" ") };
+    }
+    if (e.type === "BinaryExpression" && e.operator === "+") {
+        const parts = [
+            resolveText(e.left, env, depth + 1),
+            resolveText(e.right, env, depth + 1),
+        ];
+        if (parts.some((p) => p.kind === "dynamic")) {
+            // 拼接里夹着动态片段：静态部分仍可检查，片段本身不算
+            return {
+                kind: "text",
+                text: parts.map((p) => (p.kind === "text" ? p.text : "")).join(" "),
+            };
+        }
+        if (parts.some((p) => p.kind === "imported"))
+            return { kind: "imported" };
+        return { kind: "text", text: parts.map((p) => (p.kind === "text" ? p.text : "")).join(" ") };
+    }
+    if (e.type === "Identifier") {
+        const name = e.name;
+        if (env.imported.has(name))
+            return { kind: "imported" };
+        const init = env.decls.get(name);
+        return init ? resolveText(init, env, depth + 1) : { kind: "dynamic" };
+    }
+    if (e.type === "CallExpression") {
+        const callee = unwrap(e.callee);
+        if (callee.type !== "Identifier")
+            return { kind: "dynamic" };
+        const name = callee.name;
+        if (env.imported.has(name))
+            return { kind: "imported" };
+        const fn = env.decls.get(name);
+        if (!fn)
+            return { kind: "dynamic" };
+        return resolveFnReturn(fn, env, depth + 1);
+    }
+    return { kind: "dynamic" };
+}
+function resolveFnReturn(fn, env, depth) {
+    const f = unwrap(fn);
+    if (f.type !== "ArrowFunctionExpression" &&
+        f.type !== "FunctionExpression" &&
+        f.type !== "FunctionDeclaration") {
+        return { kind: "dynamic" };
+    }
+    const body = f.body;
+    if (body.type !== "BlockStatement")
+        return resolveText(body, env, depth);
+    const texts = [];
+    let bad = false;
+    walk(body, (n) => {
+        if (n.type !== "ReturnStatement" || !n.argument)
+            return;
+        const r = resolveText(n.argument, env, depth + 1);
+        if (r.kind === "text")
+            texts.push(r.text);
+        else
+            bad = true;
+    });
+    return bad || texts.length === 0 ? { kind: "dynamic" } : { kind: "text", text: texts.join(" ") };
+}
+const MSG_DESC_MISSING = "工具缺少 description，或它不是字符串字面量。给模型的描述必须写成可静态检查的英文字符串字面量（可用 + 拼接）";
+const MSG_DESC_SHORT = `工具 description 至少 ${MIN_DESCRIPTION} 个字符：说清工具做什么、何时该用、何时不该用`;
+const MSG_DESC_CJK = "工具 description 是模型可见文案，必须是英文，不得含中文字符";
+const MSG_ERR_DYNAMIC = "ToolError 的消息必须是字符串字面量或模板（或指向本文件内的此类常量 / 函数），否则无法检查是否可执行";
+const MSG_ERR_ACTION = "ToolError 的消息要让模型知道下一步怎么做：必须含建议动词之一（use / call / retry / check / ask / pass / provide）";
+/** 取一个 spec 表达式对应的对象字面量（直接写，或经本文件内的常量引用）。 */
+function specObject(n, env) {
+    let e = unwrap(n);
+    for (let i = 0; i < 5 && e.type === "Identifier"; i++) {
+        const init = env.decls.get(e.name);
+        if (!init)
+            return undefined;
+        e = unwrap(init);
+    }
+    return e.type === "ObjectExpression" ? e : undefined;
+}
+function checkSpec(f, at, spec, out) {
+    const add = (node, message) => {
+        out.push({ file: f.file, line: f.lineOf(node.start), rule: "tool-description", message });
+    };
+    const p = spec ? prop(spec, "description") : undefined;
+    const value = p ? stringValue(unwrap(p.value)) : undefined;
+    if (value === undefined)
+        add(at, MSG_DESC_MISSING);
+    else if (value.trim().length < MIN_DESCRIPTION)
+        add(at, MSG_DESC_SHORT);
+    else if (CJK.test(value))
+        add(at, MSG_DESC_CJK);
+}
+function scanFile(f) {
+    const out = [];
+    const env = buildEnv(f);
+    walk(f.program, (n) => {
+        // ctx.tools.register(spec, handler)
+        if (n.type === "CallExpression") {
+            const c = unwrap(n.callee);
+            if (c.type === "MemberExpression" &&
+                !c.computed &&
+                c.property.name === "register") {
+                const o = unwrap(c.object);
+                const isTools = (o.type === "MemberExpression" && !o.computed && o.property.name === "tools") ||
+                    (o.type === "Identifier" && o.name === "tools");
+                if (isTools) {
+                    const first = n.arguments[0];
+                    checkSpec(f, n, first ? specObject(first, env) : undefined, out);
+                }
+            }
+        }
+        // BuiltinTool 对象字面量：同时有 spec 与 run
+        if (n.type === "ObjectExpression" && prop(n, "spec") && prop(n, "run")) {
+            const sp = prop(n, "spec");
+            checkSpec(f, sp, specObject(sp.value, env), out);
+        }
+        // throw new ToolError(...)，也包括 return new ToolError(...)
+        if (n.type === "NewExpression") {
+            const callee = unwrap(n.callee);
+            if (callee.type !== "Identifier" || callee.name !== "ToolError")
+                return;
+            const arg = n.arguments[0];
+            const line = f.lineOf(n.start);
+            const add = (message) => out.push({ file: f.file, line, rule: "tool-error-actionable", message });
+            if (!arg)
+                return add(MSG_ERR_ACTION);
+            const r = resolveText(arg, env);
+            if (r.kind === "imported")
+                return; // 定义在别处，不跨文件追踪（已知缺口）
+            if (r.kind === "dynamic")
+                return add(MSG_ERR_DYNAMIC);
+            if (!ACTION_VERB.test(r.text))
+                add(MSG_ERR_ACTION);
+        }
+    });
+    return out;
+}
+/**
+ * 工具设计检查（AST）。规则：
+ * - tool-description：`ctx.tools.register(spec, …)` 与 `BuiltinTool` 字面量（有 spec 与 run）里的 spec
+ *   必须有字符串字面量 description（可 `+` 拼接）、不少于 20 字符、不含中文（模型可见文案一律英文）；
+ * - tool-error-actionable：`new ToolError(msg)` 的 msg 是字符串字面量 / 模板（或本文件内的常量、函数返回值），
+ *   且含建议动词 use / call / retry / check / ask / pass / provide 之一，让模型知道下一步做什么。
+ * spec 可以直接写对象字面量，也可以引用本文件内的 const；其他写法（跨文件、动态构造）报 tool-description。
+ * 已知缺口：从别的文件导入的消息常量 / 函数不追踪；非 ToolError 类的错误不查；运行时拼出的 spec 不查。
+ * 扫描：传入目录下的非测试源码。
+ */
+export function checkToolDesign(dirs) {
+    const findings = [];
+    for (const dir of dirs) {
+        for (const { file, isTest } of listSourceFiles(dir)) {
+            if (isTest)
+                continue;
+            const parsed = parseFile(file);
+            if (isParseError(parsed)) {
+                findings.push(parsed);
+                continue;
+            }
+            findings.push(...scanFile(parsed).sort((a, b) => a.line - b.line));
+        }
+    }
+    return findings;
+}

package/dist/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/cli.js

@@ -0,0 +1,48 @@
+/**
+ * `capybara-plugin`: pack, check, sync the versions of and release Capybara plugins.
+ *
+ *   capybara-plugin pack [<dir>...] [--all <root>] [--out <dir>]
+ *   capybara-plugin pack --bootstrap <manifest> [--root <dir>] [--out <dir>] [--registry <url>]
+ *                        [--npm-token <token>]
+ *   capybara-plugin check [--root <dir>] [--plugins <glob>] [--base <ref>]
+ *   capybara-plugin sync-versions [--root <dir>] [--plugins <glob>]
+ *   capybara-plugin marketplace --write|--check [--base <rev>] [--root <dir>] [--file <path>]
+ *                               [--plugins <glob>]
+ *   capybara-plugin release [--dry-run] [--provenance] [--out <dir>] [--auto] [--root <dir>]
+ *                           [--plugins <pattern>]... [--marketplace <file>]
+ *
+ * Relative paths resolve against the current directory of the process (`capybara-plugin pack .`
+ * in a package script packs that package). `<command> --help` prints one command's usage.
+ */
+import { CHECK_USAGE, checkCommand } from "./check/cli.js";
+import { SYNC_VERSIONS_USAGE, syncVersionsCommand } from "./check/sync-versions-cli.js";
+import { MARKETPLACE_USAGE, marketplaceCommand } from "./marketplace/cli.js";
+import { PACK_USAGE, packCommand } from "./pack/cli.js";
+import { RELEASE_USAGE, releaseCommand } from "./release/cli.js";
+const COMMANDS = {
+    pack: packCommand,
+    check: checkCommand,
+    "sync-versions": syncVersionsCommand,
+    marketplace: marketplaceCommand,
+    release: releaseCommand,
+};
+const USAGE = `usage: ${[PACK_USAGE, CHECK_USAGE, SYNC_VERSIONS_USAGE, MARKETPLACE_USAGE, RELEASE_USAGE].join("\n       ")}`;
+const [command, ...args] = process.argv.slice(2);
+const run = command === undefined ? undefined : COMMANDS[command];
+if (command === "--help" || command === "-h" || command === "help") {
+    console.log(USAGE);
+}
+else if (run === undefined) {
+    console.error(`${command === undefined ? "no command" : `unknown command ${command}`}\n${USAGE}`);
+    process.exitCode = 2;
+}
+else {
+    try {
+        process.exitCode = await run(args, process.cwd());
+    }
+    catch (e) {
+        // parseArgs rejects unknown options and missing values.
+        console.error(`${e instanceof Error ? e.message : String(e)}\n${USAGE}`);
+        process.exitCode = 2;
+    }
+}

package/dist/discover.d.ts

@@ -0,0 +1,21 @@
+/** The default plugin glob of a repository with a `plugins/` directory. */
+export declare const DEFAULT_PLUGINS_GLOB = "plugins/*";
+/**
+ * A POSIX path glob (`*` and `?` within one segment; `**` is not supported) as a regular expression
+ * that matches the whole path.
+ */
+export declare function globToRegExp(glob: string): RegExp;
+/** Directories under `root` matching `glob` (sorted, absolute); `node_modules` never matches. */
+export declare function expandGlob(root: string, glob: string): string[];
+/**
+ * The plugin directories of a repository, as `capybara-plugin pack --all` and `check` find them:
+ * with `glob`, the matching directories under `root` that hold a `package.json` or a
+ * `.capybara-plugin/plugin.json`; without, `<root>/plugins/*` when `<root>/plugins` exists, else
+ * `root` itself when it is a plugin (has `.capybara-plugin/plugin.json`). Sorted, absolute.
+ */
+export declare function discoverPlugins(root: string, glob?: string): string[];
+/**
+ * The glob (relative to `root`) that {@link discoverPlugins} uses: `glob` itself, `plugins/*`, or
+ * `.` for a single-plugin repository.
+ */
+export declare function pluginsGlobOf(root: string, glob?: string): string;

package/dist/discover.js

@@ -0,0 +1,69 @@
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { PLUGIN_MANIFEST_FILE } from "@capybara-hq/plugin-sdk";
+/** The default plugin glob of a repository with a `plugins/` directory. */
+export const DEFAULT_PLUGINS_GLOB = "plugins/*";
+const escapeRe = (s) => s.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+/** One glob segment (`*` and `?`, never across `/`) as a regular expression source. */
+const segmentRe = (seg) => escapeRe(seg).replace(/\*/g, "[^/]*").replace(/\?/g, "[^/]");
+/**
+ * A POSIX path glob (`*` and `?` within one segment; `**` is not supported) as a regular expression
+ * that matches the whole path.
+ */
+export function globToRegExp(glob) {
+    const segs = normalizeGlob(glob);
+    return new RegExp(`^${segs.map(segmentRe).join("/")}$`);
+}
+function normalizeGlob(glob) {
+    const segs = glob
+        .replace(/\\/g, "/")
+        .split("/")
+        .filter((s) => s !== "" && s !== ".");
+    if (segs.some((s) => s.includes("**") || s === "..")) {
+        throw new Error(`unsupported plugin glob ${glob}: use * within one path segment, no ** or ..`);
+    }
+    return segs;
+}
+/** Directories under `root` matching `glob` (sorted, absolute); `node_modules` never matches. */
+export function expandGlob(root, glob) {
+    let dirs = [root];
+    for (const seg of normalizeGlob(glob)) {
+        const re = new RegExp(`^${segmentRe(seg)}$`);
+        const next = [];
+        for (const d of dirs) {
+            if (!existsSync(d))
+                continue;
+            for (const e of readdirSync(d, { withFileTypes: true })) {
+                if (e.isDirectory() && e.name !== "node_modules" && re.test(e.name)) {
+                    next.push(join(d, e.name));
+                }
+            }
+        }
+        dirs = next;
+    }
+    return dirs.sort();
+}
+const isPluginDir = (d) => existsSync(join(d, "package.json")) || existsSync(join(d, PLUGIN_MANIFEST_FILE));
+/**
+ * The plugin directories of a repository, as `capybara-plugin pack --all` and `check` find them:
+ * with `glob`, the matching directories under `root` that hold a `package.json` or a
+ * `.capybara-plugin/plugin.json`; without, `<root>/plugins/*` when `<root>/plugins` exists, else
+ * `root` itself when it is a plugin (has `.capybara-plugin/plugin.json`). Sorted, absolute.
+ */
+export function discoverPlugins(root, glob) {
+    if (glob !== undefined)
+        return expandGlob(root, glob).filter(isPluginDir);
+    if (existsSync(join(root, "plugins"))) {
+        return expandGlob(root, DEFAULT_PLUGINS_GLOB).filter(isPluginDir);
+    }
+    return existsSync(join(root, PLUGIN_MANIFEST_FILE)) ? [root] : [];
+}
+/**
+ * The glob (relative to `root`) that {@link discoverPlugins} uses: `glob` itself, `plugins/*`, or
+ * `.` for a single-plugin repository.
+ */
+export function pluginsGlobOf(root, glob) {
+    if (glob !== undefined)
+        return glob;
+    return existsSync(join(root, "plugins")) ? DEFAULT_PLUGINS_GLOB : ".";
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@capybara-hq/plugin-tools`: the toolchain behind the `capybara-plugin` CLI (pack, check, release)
+ * as a library. Subpaths without the kernel: `./pack`, `./release`, `./source` (the source scanner
+ * the checks are built on).
+ */
+export * from "./check/index.js";
+export { DEFAULT_PLUGINS_GLOB, discoverPlugins, expandGlob, globToRegExp, pluginsGlobOf, } from "./discover.js";
+export * from "./marketplace/index.js";
+export * from "./pack/index.js";
+export * from "./release/index.js";

package/dist/index.js

@@ -0,0 +1,10 @@
+/**
+ * `@capybara-hq/plugin-tools`: the toolchain behind the `capybara-plugin` CLI (pack, check, release)
+ * as a library. Subpaths without the kernel: `./pack`, `./release`, `./source` (the source scanner
+ * the checks are built on).
+ */
+export * from "./check/index.js";
+export { DEFAULT_PLUGINS_GLOB, discoverPlugins, expandGlob, globToRegExp, pluginsGlobOf, } from "./discover.js";
+export * from "./marketplace/index.js";
+export * from "./pack/index.js";
+export * from "./release/index.js";

package/dist/integrity.d.ts

@@ -0,0 +1,2 @@
+/** sha512 SRI (`sha512-<base64>`), the form marketplaces, bootstrap pins and npm pin tgz files with. */
+export declare const integrityOf: (bytes: Uint8Array) => string;

package/dist/integrity.js

@@ -0,0 +1,3 @@
+import { createHash } from "node:crypto";
+/** sha512 SRI (`sha512-<base64>`), the form marketplaces, bootstrap pins and npm pin tgz files with. */
+export const integrityOf = (bytes) => `sha512-${createHash("sha512").update(bytes).digest("base64")}`;

package/dist/marketplace/cli.d.ts

@@ -0,0 +1,20 @@
+export declare const MARKETPLACE_USAGE: string;
+/**
+ * `capybara-plugin marketplace`: writes (`--write`) or checks (`--check`) the repository's
+ * marketplace manifest against reproducible packs of its public plugins ({@link syncMarketplace}).
+ *
+ * - `--root <dir>`: the repository (default: the current directory);
+ * - `--file <path>`: the manifest, relative to the root (default `.capybara-plugin/marketplace.json`);
+ * - `--plugins <glob>`: the plugin directories, relative to the root (default `plugins/*`, or the
+ *   root itself when it is a plugin).
+ *
+ * - `--base <rev>` (with `--check`, on pull requests): the entries the file had at `<rev>` must be
+ *   unchanged and first, in order (`marketplace-append-only`), and the entries added since must
+ *   match the tree's packs (`marketplace-integrity`).
+ *
+ * `--check` exits 1 on any finding (`marketplace-missing`, `marketplace-integrity`,
+ * `marketplace-append-only`, `marketplace-invalid`); `--write` appends the missing entries and
+ * exits 1 only on `marketplace-invalid`.
+ * Relative paths resolve against `cwd`. Returns the exit code.
+ */
+export declare function marketplaceCommand(args: string[], cwd: string): Promise<number>;

package/dist/marketplace/cli.js

@@ -0,0 +1,80 @@
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { formatFinding } from "../check/report.js";
+import { MARKETPLACE_FILE, syncMarketplace } from "./marketplace.js";
+export const MARKETPLACE_USAGE = "capybara-plugin marketplace --write|--check [--base <rev>] [--root <dir>] [--file <path>]\n" +
+    "                            [--plugins <glob>]";
+/**
+ * `capybara-plugin marketplace`: writes (`--write`) or checks (`--check`) the repository's
+ * marketplace manifest against reproducible packs of its public plugins ({@link syncMarketplace}).
+ *
+ * - `--root <dir>`: the repository (default: the current directory);
+ * - `--file <path>`: the manifest, relative to the root (default `.capybara-plugin/marketplace.json`);
+ * - `--plugins <glob>`: the plugin directories, relative to the root (default `plugins/*`, or the
+ *   root itself when it is a plugin).
+ *
+ * - `--base <rev>` (with `--check`, on pull requests): the entries the file had at `<rev>` must be
+ *   unchanged and first, in order (`marketplace-append-only`), and the entries added since must
+ *   match the tree's packs (`marketplace-integrity`).
+ *
+ * `--check` exits 1 on any finding (`marketplace-missing`, `marketplace-integrity`,
+ * `marketplace-append-only`, `marketplace-invalid`); `--write` appends the missing entries and
+ * exits 1 only on `marketplace-invalid`.
+ * Relative paths resolve against `cwd`. Returns the exit code.
+ */
+export async function marketplaceCommand(args, cwd) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            help: { type: "boolean", short: "h", default: false },
+            write: { type: "boolean", default: false },
+            check: { type: "boolean", default: false },
+            root: { type: "string" },
+            file: { type: "string" },
+            plugins: { type: "string" },
+            base: { type: "string" },
+        },
+    });
+    if (values.help) {
+        console.log(`usage: ${MARKETPLACE_USAGE}`);
+        return 0;
+    }
+    if (values.write === values.check) {
+        console.error(`give exactly one of --write and --check\nusage: ${MARKETPLACE_USAGE}`);
+        return 2;
+    }
+    if (values.base !== undefined && values.write) {
+        console.error(`--base goes with --check\nusage: ${MARKETPLACE_USAGE}`);
+        return 2;
+    }
+    const root = values.root === undefined ? cwd : resolve(cwd, values.root);
+    const file = resolve(root, values.file ?? MARKETPLACE_FILE);
+    try {
+        const r = await syncMarketplace({
+            root,
+            file,
+            write: values.write,
+            ...(values.plugins !== undefined && { plugins: values.plugins }),
+            ...(values.base !== undefined && { base: values.base }),
+        });
+        for (const f of r.findings)
+            console.error(formatFinding(f, root));
+        if (r.findings.length > 0) {
+            console.error(`\n${r.findings.length} marketplace finding(s)`);
+            return 1;
+        }
+        if (values.write) {
+            for (const e of r.added)
+                console.log(`added ${e.name}@${e.version}`);
+            console.log(r.added.length === 0 ? "marketplace is up to date" : `wrote ${file}`);
+        }
+        else {
+            console.log("marketplace is up to date");
+        }
+        return 0;
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 1;
+    }
+}

package/dist/marketplace/file.d.ts

@@ -0,0 +1,2 @@
+/** Where a plugin repository keeps its marketplace manifest (relative to the root). */
+export declare const MARKETPLACE_FILE = ".capybara-plugin/marketplace.json";

package/dist/marketplace/file.js

@@ -0,0 +1,2 @@
+/** Where a plugin repository keeps its marketplace manifest (relative to the root). */
+export const MARKETPLACE_FILE = ".capybara-plugin/marketplace.json";

package/dist/marketplace/index.d.ts

@@ -0,0 +1,2 @@
+export { MARKETPLACE_USAGE, marketplaceCommand } from "./cli.js";
+export { formatMarketplaceJson, MARKETPLACE_FILE, type SyncMarketplaceOptions, type SyncMarketplaceResult, syncMarketplace, } from "./marketplace.js";

package/dist/marketplace/index.js

@@ -0,0 +1,2 @@
+export { MARKETPLACE_USAGE, marketplaceCommand } from "./cli.js";
+export { formatMarketplaceJson, MARKETPLACE_FILE, syncMarketplace, } from "./marketplace.js";

package/dist/marketplace/marketplace.d.ts

@@ -0,0 +1,57 @@
+import { type MarketplaceEntry } from "@capybara-hq/plugin-sdk";
+import type { Finding } from "../check/source.js";
+export { MARKETPLACE_FILE } from "./file.js";
+/** Options of {@link syncMarketplace}. */
+export interface SyncMarketplaceOptions {
+    /** The repository root (its plugins: `plugins/*`, or the root when it is a plugin). */
+    root: string;
+    /** The marketplace manifest (absolute). It must exist: its name and owner are the maintainers'. */
+    file: string;
+    /** Plugin directories relative to `root` (`*` within one segment); default as `discoverPlugins`. */
+    plugins?: string;
+    /** Append the missing entries to `file` (`--write`); otherwise only report them (`--check`). */
+    write: boolean;
+    /**
+     * A git revision (`--check --base <rev>`, pull requests): the entries the file had there are
+     * published and must still be there, unchanged and in the same order (only appending is
+     * allowed; `marketplace-append-only`), and every entry added since must match the tree's pack
+     * (`marketplace-integrity`). A file the base does not have constrains nothing.
+     */
+    base?: string;
+}
+/** The result of {@link syncMarketplace}. */
+export interface SyncMarketplaceResult {
+    /** Entries for `(name, version)` pairs the file does not list yet (appended with `write`). */
+    added: MarketplaceEntry[];
+    /**
+     * `marketplace-invalid` (the file does not parse, or would not after appending),
+     * `marketplace-integrity` (with a base: an entry added since names another package or integrity
+     * than the tree's pack), `marketplace-append-only` (with a base: a published entry changed, moved
+     * or went away) and, without `write`, `marketplace-missing` (one per added entry).
+     */
+    findings: Finding[];
+}
+/**
+ * `capybara-plugin marketplace`: keeps a plugin repository's `marketplace.json` listing every
+ * published version of its public plugins (package ecosystem spec §5.2; one entry per
+ * `(name, version)`, Decision 7 of phase A3b). Each public plugin (not `"private": true`) is packed
+ * reproducibly with {@link packPlugin}; when the file has no entry for its name and version, an
+ * entry `{ name, version, summary, homepage?, permissions, source: { npm: { package, version,
+ * integrity } } }` is added (`integrity` the pack's sha512, which the release then publishes
+ * byte for byte; `permissions` display only). A version already listed is not packed or compared:
+ * once published, its bytes are the release gate's business (`release --marketplace`), so a later
+ * source or toolchain change at the same version is not a finding. With `base`, published entries
+ * must be unchanged and first in order, and entries added since must match the tree's packs.
+ * Entries of versions no longer in the tree are kept, so a pinned commit lists what it pins and
+ * older versions stay importable. The file is written formatted as Biome formats it
+ * ({@link formatMarketplaceJson}).
+ * With `write`, the new entries are appended in plugin order (nothing is written when there is any
+ * other finding).
+ */
+export declare function syncMarketplace(opts: SyncMarketplaceOptions): Promise<SyncMarketplaceResult>;
+/**
+ * `marketplace.json` as Biome formats it with a 2-space indent and a 100-column line width: a
+ * non-empty object puts each member on its own line; an array of scalars stays on one line when
+ * it fits (the trailing comma counted), otherwise one item per line; empty ones are `[]` / `{}`.
+ */
+export declare function formatMarketplaceJson(value: unknown): string;