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

package/dist/check/deps.js

@@ -0,0 +1,207 @@
+import { existsSync, readFileSync } from "node:fs";
+import { isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { collectImports, isParseError, listSourceFiles, parseFile, } from "./source.js";
+const SCOPE = "@capybara-hq/";
+const SDK = "@capybara-hq/plugin-sdk";
+const TESTING = "@capybara-hq/testing";
+/** The scripted model provider that stays in core: plugin tests load it to drive agent runs. */
+const MODEL_FAKE = "@capybara-hq/plugin-model-fake";
+/** The plugin toolchain (`capybara-plugin`): a plugin repository's devDependency. */
+const PLUGIN_TOOLS = "@capybara-hq/plugin-tools";
+const DEP_FIELDS = [
+    "dependencies",
+    "peerDependencies",
+    "devDependencies",
+    "optionalDependencies",
+];
+const SCOPED_RE = /@capybara-hq\/([A-Za-z0-9._-]+)/g;
+const PATH_PROTOCOL_RE = /^(?:link|file|portal):/;
+const PLUGIN_RULES = {
+    pkgRule: "plugin-imports-kernel",
+    outsideRule: "plugin-imports-outside",
+    pkgMessage: (what) => `a plugin may depend only on ${SDK} and third-party npm packages, not on ${what}; what it needs comes through ctx (extend the plugin-sdk contract if it is missing)`,
+    outsideMessage: (what) => `${what} points outside the plugin directory, which bypasses the package check and depends on kernel sources directly; a plugin may reference only files inside its own directory`,
+    allowed: (pkg, where) => pkg === SDK ||
+        ((pkg === TESTING || pkg === MODEL_FAKE || pkg === PLUGIN_TOOLS) &&
+            (where === "devDependencies" || where === "test")),
+};
+const SDK_RULES = {
+    pkgRule: "sdk-imports-internal",
+    outsideRule: "sdk-imports-internal",
+    pkgMessage: (what) => `packages/plugin-sdk holds only types and pure functions and must not depend on any other @capybara-hq/* package (found ${what})`,
+    outsideMessage: (what) => `packages/plugin-sdk must not reference files outside its package directory (${what})`,
+    allowed: () => false,
+};
+/** The violation a reference string (package name / relative path / file: URL / protocol dependency value) makes, if any. */
+function judge(value, baseDir, rootDir, rules, where) {
+    const pkgs = [...value.matchAll(SCOPED_RE)].map((m) => `${SCOPE}${m[1]}`);
+    if (pkgs.some((p) => !rules.allowed(p, where)))
+        return "pkg";
+    let path;
+    if (value.startsWith("file:///"))
+        path = fileURLToPath(value);
+    else if (PATH_PROTOCOL_RE.test(value))
+        path = resolve(baseDir, value.replace(PATH_PROTOCOL_RE, ""));
+    else if (value.startsWith(".") || isAbsolute(value))
+        path = resolve(baseDir, value);
+    if (path !== undefined && relative(resolve(rootDir), path).startsWith(".."))
+        return "outside";
+    return undefined;
+}
+/** Every string leaf of a JSON subtree. */
+function leaves(v) {
+    if (typeof v === "string")
+        return [v];
+    if (Array.isArray(v))
+        return v.flatMap(leaves);
+    if (typeof v === "object" && v !== null)
+        return Object.values(v).flatMap(leaves);
+    return [];
+}
+/** Reads package.json; undefined when there is none. */
+function readPackage(dir) {
+    const file = join(dir, "package.json");
+    if (!existsSync(file))
+        return undefined;
+    const text = readFileSync(file, "utf8");
+    return { file, lines: text.split("\n"), pkg: JSON.parse(text) };
+}
+function packageFindings(dir, rules) {
+    const loaded = readPackage(dir);
+    if (!loaded)
+        return [];
+    const { file, lines, pkg } = loaded;
+    const out = [];
+    const lineOf = (needle) => Math.max(lines.findIndex((l) => l.includes(`"${needle}"`)) + 1, 1);
+    const add = (kind, where, name, what) => out.push({
+        file,
+        line: lineOf(name),
+        rule: kind === "pkg" ? rules.pkgRule : rules.outsideRule,
+        message: `${name} in ${where}: ${kind === "pkg" ? rules.pkgMessage(what) : rules.outsideMessage(what)}`,
+    });
+    for (const field of DEP_FIELDS) {
+        const deps = (pkg[field] ?? {});
+        for (const [name, value] of Object.entries(deps)) {
+            // Both the name and the value: an alias `"x": "npm:@capybara-hq/kernel@*"` has no scope in its name.
+            const kind = judge(name, dir, dir, rules, field) ?? judge(String(value), dir, dir, rules, field);
+            if (kind)
+                add(kind, field, name, `${name}@${value}`);
+        }
+    }
+    for (const field of ["bundleDependencies", "bundledDependencies"]) {
+        const list = pkg[field];
+        if (!Array.isArray(list))
+            continue;
+        for (const name of list) {
+            if (judge(name, dir, dir, rules, field) === "pkg")
+                add("pkg", field, name, name);
+        }
+    }
+    for (const field of ["imports", "exports"]) {
+        const map = pkg[field];
+        if (typeof map !== "object" || map === null)
+            continue;
+        for (const [key, v] of Object.entries(map)) {
+            for (const target of leaves(v)) {
+                const kind = judge(target, dir, dir, rules, field);
+                if (kind)
+                    add(kind, field, key, target);
+            }
+        }
+    }
+    return out;
+}
+/** Expands a `#xxx` subpath import of the sources through the package.json imports map (empty when unmapped). */
+function resolveHashImport(spec, imports) {
+    const direct = imports[spec];
+    if (direct !== undefined)
+        return leaves(direct);
+    for (const [key, v] of Object.entries(imports)) {
+        const star = key.indexOf("*");
+        if (star === -1)
+            continue;
+        const head = key.slice(0, star);
+        const tail = key.slice(star + 1);
+        if (spec.startsWith(head) && spec.endsWith(tail) && spec.length >= head.length + tail.length) {
+            const mid = spec.slice(head.length, spec.length - tail.length);
+            return leaves(v).map((t) => t.replace("*", mid));
+        }
+    }
+    return [];
+}
+function sourceFindings(dir, rules, srcDir) {
+    const out = [];
+    const loaded = readPackage(dir);
+    const imports = (loaded?.pkg.imports ?? {});
+    // Dependency aliases: a dependency without a scope whose value is an @capybara-hq/* package; importing
+    // the alias in the sources is importing that package.
+    const aliases = [];
+    for (const field of DEP_FIELDS) {
+        for (const [name, value] of Object.entries((loaded?.pkg[field] ?? {}))) {
+            if (!name.startsWith(SCOPE) && judge(String(value), dir, dir, rules, field) === "pkg") {
+                aliases.push(name);
+            }
+        }
+    }
+    for (const { file, isTest } of listSourceFiles(srcDir)) {
+        const parsed = parseFile(file);
+        if (isParseError(parsed)) {
+            out.push(parsed);
+            continue;
+        }
+        const where = isTest ? "test" : "source";
+        for (const { spec, start } of collectImports(parsed.program)) {
+            const line = parsed.lineOf(start);
+            let kind = judge(spec, join(file, ".."), dir, rules, where);
+            let shown = spec;
+            if (!kind && aliases.some((a) => spec === a || spec.startsWith(`${a}/`)))
+                kind = "pkg";
+            if (!kind && spec.startsWith("#")) {
+                for (const target of resolveHashImport(spec, imports)) {
+                    kind = judge(target, dir, dir, rules, where);
+                    if (kind) {
+                        shown = `${spec} -> ${target}`;
+                        break;
+                    }
+                }
+            }
+            if (kind === "pkg")
+                out.push({ file, line, rule: rules.pkgRule, message: rules.pkgMessage(shown) });
+            else if (kind === "outside") {
+                out.push({ file, line, rule: rules.outsideRule, message: rules.outsideMessage(shown) });
+            }
+        }
+    }
+    return out;
+}
+/**
+ * The dependency boundary check.
+ * - pluginDirs: each plugin directory (source imports and package.json); a violation is
+ *   plugin-imports-kernel (a path leaving the plugin directory: plugin-imports-outside);
+ * - sdkDirs: the packages/plugin-sdk directory; any @capybara-hq/* package or path leaving the
+ *   package directory is sdk-imports-internal.
+ *
+ * Covers: import / export from / export * / import type / dynamic import("literal or concatenated
+ * literals") / require("…") / import x = require() / import("x") types; package.json dependencies /
+ * peerDependencies / devDependencies / optionalDependencies (name and value, so npm: / workspace:
+ * aliases too) / bundleDependencies / link:|file:|portal: leaving the directory / imports and exports
+ * map values; `#xxx` imports in the sources after expanding the imports map, and dependency aliases;
+ * file: URLs and absolute paths count as leaving the directory.
+ * Allowed in devDependencies and test files: @capybara-hq/testing and @capybara-hq/plugin-tools.
+ * Also allowed there: `@capybara-hq/plugin-model-fake` (plugin tests drive agent runs with it).
+ *
+ * Known gaps: non-literal dynamic specifiers (`import(x)`); indirect require through a variable,
+ * `module.require` or `createRequire(...)`; `import.meta.resolve`; paths built at run time to read
+ * files; nested package.json files and TS `paths` mappings.
+ */
+export function checkDeps(pluginDirs, sdkDirs = []) {
+    const findings = [];
+    for (const dir of pluginDirs) {
+        findings.push(...packageFindings(dir, PLUGIN_RULES), ...sourceFindings(dir, PLUGIN_RULES, dir));
+    }
+    for (const dir of sdkDirs) {
+        findings.push(...packageFindings(dir, SDK_RULES), ...sourceFindings(dir, SDK_RULES, join(dir, "src")));
+    }
+    return findings;
+}

package/dist/check/index.d.ts

@@ -0,0 +1,15 @@
+export { checkAppliedMigrations, diffAppliedMigrations, type MigrationFilePredicate, migrationFileMatcher, } from "./applied-migrations.js";
+export { CHECK_USAGE, checkCommand } from "./cli.js";
+export { checkDeps } from "./deps.js";
+export { checkMigrations, checkSql } from "./migrations.js";
+export { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";
+export { checkPluginPermissions } from "./plugin-permissions.js";
+export { checkPluginState } from "./plugin-state.js";
+export { syncPluginVersions } from "./plugin-versions.js";
+export { checkPluginReleaseMetadata } from "./release-metadata.js";
+export { formatFinding, printCheck } from "./report.js";
+export { type NamedCheck, type PluginCheckScope, pluginChecks, runChecks } from "./run.js";
+export type { Finding } from "./source.js";
+export { SYNC_VERSIONS_USAGE, syncVersionsCommand } from "./sync-versions-cli.js";
+export { checkPluginTestImports, PLUGIN_TEST_PACKAGES } from "./test-imports.js";
+export { checkToolDesign } from "./tool-design.js";

package/dist/check/index.js

@@ -0,0 +1,14 @@
+export { checkAppliedMigrations, diffAppliedMigrations, migrationFileMatcher, } from "./applied-migrations.js";
+export { CHECK_USAGE, checkCommand } from "./cli.js";
+export { checkDeps } from "./deps.js";
+export { checkMigrations, checkSql } from "./migrations.js";
+export { checkPluginPack, PLUGIN_PACK_MAX_BYTES } from "./plugin-pack.js";
+export { checkPluginPermissions } from "./plugin-permissions.js";
+export { checkPluginState } from "./plugin-state.js";
+export { syncPluginVersions } from "./plugin-versions.js";
+export { checkPluginReleaseMetadata } from "./release-metadata.js";
+export { formatFinding, printCheck } from "./report.js";
+export { pluginChecks, runChecks } from "./run.js";
+export { SYNC_VERSIONS_USAGE, syncVersionsCommand } from "./sync-versions-cli.js";
+export { checkPluginTestImports, PLUGIN_TEST_PACKAGES } from "./test-imports.js";
+export { checkToolDesign } from "./tool-design.js";

package/dist/check/migrations.d.ts

@@ -0,0 +1,11 @@
+import type { Finding } from "./source.js";
+export type { Finding };
+/**
+ * Checks the SQL text of one migration file (not its name); `file` is only used in the findings.
+ */
+export declare function checkSql(file: string, source: string): Finding[];
+/**
+ * Checks migration directories (missing ones are ignored). Rules: naming / idempotent / destructive /
+ * transaction-control / do-block.
+ */
+export declare function checkMigrations(dirs: string[]): Finding[];

package/dist/check/migrations.js

@@ -0,0 +1,93 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { isDestructiveBody, isDestructiveSql, splitSqlStatements } from "@capybara-hq/kernel";
+const NAME_RE = /^\d{4}_[a-z0-9_]+\.sql$/;
+const ALLOW_RE = /^\s*--\s*capybara:allow-destructive(?:\s+(.*\S))?\s*$/;
+const MSG_DESTRUCTIVE = "stop reading and writing the column in this version and drop it in the next one; if it must run in this version, add -- capybara:allow-destructive <reason>";
+const MSG_REASON = "-- capybara:allow-destructive needs a reason (it cannot be empty) saying why this version may run it directly";
+const MSG_DO = "the statements inside a DO block cannot be reviewed statically: split it into plain idempotent statements if you can; if a DO block is needed (e.g. a RENAME COLUMN guarded by an IF EXISTS test), add -- capybara:allow-destructive <reason> right above the DO line";
+const MSG_TX = "the migrator already wraps each file in a transaction: remove the transaction control statements. CONCURRENTLY cannot run in a transaction; use a plain CREATE INDEX IF NOT EXISTS";
+const CREATE_RE = /^CREATE\s+(?:(?:UNIQUE|UNLOGGED|TEMP|TEMPORARY)\s+)*(TABLE|INDEX|SCHEMA|EXTENSION|SEQUENCE)\s+(?:CONCURRENTLY\s+)?(IF NOT EXISTS\b)?/i;
+const TX_RE = /^(BEGIN|START\s+TRANSACTION|COMMIT|ROLLBACK|SAVEPOINT|END|ABORT|RELEASE|PREPARE\s+TRANSACTION)\b/i;
+const CONCURRENTLY_RE = /^(CREATE|DROP)\s+(?:UNIQUE\s+)?INDEX\s+CONCURRENTLY\b/i;
+/**
+ * Checks the SQL text of one migration file (not its name); `file` is only used in the findings.
+ */
+export function checkSql(file, source) {
+    const findings = [];
+    const lines = source.split("\n");
+    const add = (line, rule, message) => findings.push({ file, line, rule, message });
+    for (const st of splitSqlStatements(source)) {
+        const t = st.text;
+        const tx = TX_RE.exec(t);
+        if (tx || CONCURRENTLY_RE.test(t))
+            add(st.line, "transaction-control", MSG_TX);
+        const create = CREATE_RE.exec(t);
+        if (create && !create[2]) {
+            add(st.line, "idempotent", `CREATE ${create[1]?.toUpperCase()} needs IF NOT EXISTS`);
+        }
+        const prev = st.line >= 2 ? (lines[st.line - 2] ?? "") : "";
+        const allow = ALLOW_RE.exec(prev);
+        const isDo = /^DO\b/i.test(t);
+        if (isDo && !allow)
+            add(st.line, "do-block", MSG_DO);
+        let dropsColumn = false;
+        if (/^DROP\b/i.test(t) && !/\bIF EXISTS\b/i.test(t)) {
+            add(st.line, "idempotent", "DROP needs IF EXISTS");
+        }
+        else if (/^ALTER\s+TABLE\b/i.test(t)) {
+            for (const m of t.matchAll(/\bDROP\s+(COLUMN\s+)?(IF\s+EXISTS\s+)?(NOT\s+NULL\b|DEFAULT\b|EXPRESSION\b|IDENTITY\b|CONSTRAINT\b|\S+)/gi)) {
+                const kw = (m[3] ?? "").toUpperCase();
+                if (!m[1] && /^(NOT\s+NULL|DEFAULT|EXPRESSION|IDENTITY)$/.test(kw))
+                    continue;
+                if (!m[1] && kw === "CONSTRAINT") {
+                    if (!/^\s*(IF\s+EXISTS\b)/i.test(t.slice((m.index ?? 0) + m[0].length))) {
+                        add(st.line, "idempotent", "DROP CONSTRAINT needs IF EXISTS");
+                    }
+                    continue;
+                }
+                dropsColumn = true;
+                if (!m[2])
+                    add(st.line, "idempotent", "DROP COLUMN needs IF EXISTS");
+            }
+        }
+        if (dropsColumn ||
+            isDestructiveSql(t) ||
+            (isDo && (allow !== null || st.bodies.some(isDestructiveBody)))) {
+            if (!allow)
+                add(st.line, "destructive", MSG_DESTRUCTIVE);
+            else if (!allow[1])
+                add(st.line, "destructive", MSG_REASON);
+        }
+    }
+    return findings;
+}
+/**
+ * Checks migration directories (missing ones are ignored). Rules: naming / idempotent / destructive /
+ * transaction-control / do-block.
+ */
+export function checkMigrations(dirs) {
+    const findings = [];
+    for (const dir of dirs) {
+        if (!existsSync(dir))
+            continue;
+        const entries = readdirSync(dir, { withFileTypes: true })
+            .filter((e) => e.isFile())
+            .map((e) => e.name)
+            .sort();
+        for (const name of entries) {
+            const file = join(dir, name);
+            if (!NAME_RE.test(name)) {
+                findings.push({
+                    file,
+                    line: 1,
+                    rule: "naming",
+                    message: "the file name must match NNNN_<snake_desc>.sql (four digits, lowercase letters / digits / underscores)",
+                });
+                continue;
+            }
+            findings.push(...checkSql(file, readFileSync(file, "utf8")));
+        }
+    }
+    return findings;
+}

package/dist/check/plugin-pack.d.ts

@@ -0,0 +1,17 @@
+import type { Finding } from "./source.js";
+/**
+ * The default of `packages.maxBytes` (from the kernel config schema): an official plugin's package
+ * must install under the default limit.
+ */
+export declare const PLUGIN_PACK_MAX_BYTES = 52428800;
+/**
+ * Every plugin packs into a self-contained plugin package (C12): packed with {@link packPlugin}
+ * (esbuild single-file ESM + `.capybara-plugin/plugin.json`), then validated with the kernel's
+ * install-time readers: `readPluginPackage` (unpack rules, size, plugin.json, package.json, listed
+ * paths, skills, connector templates) and, for a plugin with an extension, `readExtensionPackage`
+ * (import allowlist of the entry's module graph, migrations). One finding per plugin that fails to
+ * pack or validate (rule `plugin-pack`, located at the plugin's package.json).
+ * package.json `files` lists something the package can't carry (a directory, a glob, a missing path):
+ * rule `plugin-pack-dropped`, one per entry.
+ */
+export declare function checkPluginPack(pluginDirs: string[]): Promise<Finding[]>;

package/dist/check/plugin-pack.js

@@ -0,0 +1,56 @@
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { ExtensionPackageError, PACKAGES_MAX_BYTES_DEFAULT, PluginPackageError, readExtensionPackage, readPluginPackage, } from "@capybara-hq/kernel";
+import { SDK_VERSION } from "@capybara-hq/plugin-sdk";
+import { packPlugin } from "../pack/pack.js";
+/**
+ * The default of `packages.maxBytes` (from the kernel config schema): an official plugin's package
+ * must install under the default limit.
+ */
+export const PLUGIN_PACK_MAX_BYTES = PACKAGES_MAX_BYTES_DEFAULT;
+/**
+ * Every plugin packs into a self-contained plugin package (C12): packed with {@link packPlugin}
+ * (esbuild single-file ESM + `.capybara-plugin/plugin.json`), then validated with the kernel's
+ * install-time readers: `readPluginPackage` (unpack rules, size, plugin.json, package.json, listed
+ * paths, skills, connector templates) and, for a plugin with an extension, `readExtensionPackage`
+ * (import allowlist of the entry's module graph, migrations). One finding per plugin that fails to
+ * pack or validate (rule `plugin-pack`, located at the plugin's package.json).
+ * package.json `files` lists something the package can't carry (a directory, a glob, a missing path):
+ * rule `plugin-pack-dropped`, one per entry.
+ */
+export async function checkPluginPack(pluginDirs) {
+    const out = await mkdtemp(join(tmpdir(), "check-plugin-pack-"));
+    const findings = [];
+    const opts = { maxBytes: PLUGIN_PACK_MAX_BYTES, hostSdkVersion: SDK_VERSION };
+    try {
+        for (const dir of pluginDirs) {
+            const file = join(dir, "package.json");
+            try {
+                const r = await packPlugin(dir, out);
+                for (const d of r.dropped) {
+                    findings.push({
+                        file,
+                        line: 1,
+                        rule: "plugin-pack-dropped",
+                        message: `"files" entry "${d}" is not in the plugin package (only plain root files, README.md, LICENSE, migrations/, ui/, skills/ and connectors/ are shipped): remove it or make it a plain file`,
+                    });
+                }
+                const bytes = new Uint8Array(await readFile(r.file));
+                const plugin = await readPluginPackage(bytes, opts);
+                if (plugin.manifest.extension !== undefined)
+                    await readExtensionPackage(bytes, opts);
+            }
+            catch (e) {
+                const message = e instanceof ExtensionPackageError || e instanceof PluginPackageError
+                    ? `the plugin package is invalid: ${e.issues.join("; ")}`
+                    : `packing failed: ${e instanceof Error ? e.message : String(e)}`;
+                findings.push({ file, line: 1, rule: "plugin-pack", message });
+            }
+        }
+    }
+    finally {
+        await rm(out, { recursive: true, force: true });
+    }
+    return findings;
+}

package/dist/check/plugin-permissions.d.ts

@@ -0,0 +1,22 @@
+import { type Finding } from "./source.js";
+export type { Finding };
+/**
+ * 插件权限静态检查（AST）：把 setup(ctx) 里对平台能力的访问与 defineExtension 清单比对。规则：
+ * - perm-secrets：用了 ctx.secrets 而 permissions.secrets 不是 true；
+ * - perm-http：ctx.http.route(method, path) 不在 permissions.http 里；
+ * - perm-tools：ctx.tools.register({ name }) 的名字不在 permissions.tools 里；
+ * - perm-extension-point: the ref of ctx.extensionPoints.get|list(ref) is not in requires / optional / provides;
+ * - perm-ui：ctx.ui.view|action(id) 的 id 不在 permissions.ui.views 里；
+ * - perm-storage：用了 ctx.storage 而 permissions.storage 不是 true；
+ * - perm-hooks: the mount point of ctx.hooks.on(mount, …) is not in permissions.hooks (the mount
+ *   point must be a string literal or a same-file const, like the names below), or the options are
+ *   `{ mode: "policy" }` and the mount point is not in permissions.policyHooks;
+ * - perm-reserved：用了尚未提供的 ctx.models。
+ * 路由路径、工具名、能力 ref、界面 id 须是字符串字面量或本文件的 const；动态的写法报「无法静态确认」，
+ * 豁免：`// capybara:allow-dynamic-permission <原因>`（行尾或紧邻上一行，原因必填）。
+ * ctx 会跟踪本地别名，以及按位置传给同文件函数的参数。
+ * 已知缺口（靠评审与运行时 ExtensionPermissionError 兜底）：传给其他文件 / 方法的 ctx、闭包外的重新赋值、
+ * 没有 defineExtension 的辅助文件、permissions 本身是运行时拼出的。
+ * 扫描范围：传入目录下的非测试源码。
+ */
+export declare function checkPluginPermissions(pluginDirs: string[]): Finding[];