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

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,2 @@
+Capybara
+Copyright 2026 Meta-1 (Tianjin Yuanyilian Technology Co., Ltd.)

package/README.md

@@ -1,3 +1,112 @@
-# Temporary Holding Version
+# @capybara-hq/plugin-tools
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The toolchain for [Capybara](https://github.com/capybara-hq/core) plugins: the `capybara-plugin`
+CLI packs plugins into plugin tgz files, runs the plugin checks, keeps a marketplace manifest and
+publishes a workspace to npm.
+Capybara's own repositories use it (core for its scripts and test extensions, the plugins
+repository for the official plugins); any plugin repository can.
+
+```bash
+npm install --save-dev @capybara-hq/plugin-tools
+```
+
+## Commands
+
+```bash
+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>]
+```
+
+- **pack**: a plugin directory (`package.json` + `.capybara-plugin/plugin.json`, an optional
+  extension in `src/index.ts`, `skills/`, `connectors/`, `migrations/`, `ui/`) becomes a
+  byte-reproducible plugin tgz: the extension bundled by esbuild into single-file ESM, its static
+  manifest written into `plugin.json`, LICENSE / NOTICE and the bundled dependencies' notices
+  included. A plugin with an extension gets `"main"` and `"exports": { ".": "./dist/index.mjs" }`,
+  so once installed it resolves by package name (a test loads `@capybara-hq/plugin-model-fake`
+  from npm). `--all <root>` packs every plugin of a repository; `--bootstrap` packs the entries of
+  a bootstrap manifest (workspace entries from the repository, npm entries downloaded from
+  `--registry`, default `CAPYBARA_PACKAGES__NPM_REGISTRY` or the public registry, with
+  `--npm-token` / `CAPYBARA_PACKAGES__NPM_TOKEN` sent to the registry origin only, tarballs capped
+  at 50 MiB) and checks them against their pinned sha512 and their `package.json` name and version.
+  Output: `artifacts/plugins`.
+- **check**: every plugin check, on the plugins under `<root>/plugins/*` (or `--plugins <glob>`, or
+  the root itself when it is a plugin): the dependency boundary (a plugin depends only on
+  `@capybara-hq/plugin-sdk` and third-party packages), extension state under multiple replicas (no
+  timers, no module-level mutable state), the permission manifest (hooks, UI, storage, HTTP,
+  secrets, tools), packing into a valid plugin package, the tool design rules (English
+  descriptions, actionable errors), the migrations (naming, idempotent, no unmarked destructive
+  statements), the plugin tests' imports (`plugin-test-imports`: a file under `<plugin>/test` uses
+  only `@capybara-hq/plugin-sdk`, `@capybara-hq/testing`, `@capybara-hq/plugin-model-fake`, the
+  plugin itself and files inside the plugin, by import, package-name string or path) and the
+  release metadata (`plugin-release-metadata`: a public plugin has a `description`, a `license`, an
+  https `homepage` and `repository` `{ type: "git", url: <the root package.json's
+  repository.url>, directory: <its dir> }`; `example-*` plugins are private). `--base <ref>` also fails when the diff edits, deletes or renames an applied
+  migration. No plugin found is an error. A plugin may list `@capybara-hq/plugin-tools` (like
+  `@capybara-hq/testing`) in its devDependencies.
+- **sync-versions**: after `changeset version` (which bumps only `package.json`), copies each
+  plugin's version into its `.capybara-plugin/plugin.json` and its extension manifest
+  (`src/index.ts`, `  version: "x"`), which the packer requires equal.
+- **marketplace**: `--write` appends to `.capybara-plugin/marketplace.json` (`--file`) one npm entry
+  per public plugin version it does not list yet (`name`, `version`, `summary`, `homepage`,
+  `permissions`, `source.npm` with the sha512 of a reproducible pack), formatted as Biome formats
+  it; `--check` fails when an entry is missing (`marketplace-missing`) or the file does not parse
+  (`marketplace-invalid`). A version already listed is not compared with the tree: once
+  published, its bytes are the release gate's business. `--check --base <rev>` (pull requests)
+  also requires the entries at `<rev>` to stay unchanged and first, in order
+  (`marketplace-append-only`), and the entries added since to match their packs
+  (`marketplace-integrity`). Entries of versions no longer in the tree are kept.
+- **release**: publishes every non-private workspace package whose version is not on npm yet:
+  plugins (the packages under `plugins/`) as their plugin tgz, libraries through `pnpm pack`, with
+  the dist-tag rule (prerelease `next`, backport `release-<major>.<minor>`, else `latest`), then
+  writes the plugins' `SHA512SUMS` and `integrity.json`. `--auto` is the push-to-main mode
+  (committed tree only, never the first release). The workspace packages are the directories with a
+  `package.json` in `packages/*`, `apps/*`, `plugins/*` and `tools/*` under `--root`; none found is
+  an error. `--plugins <pattern>` (repeatable) plans only the matching plugins (libraries are unaffected; a pattern matching none is an error);
+  `--marketplace <file>` (default `.capybara-plugin/marketplace.json` under the root when it
+  exists) packs every planned plugin and checks its sha512 against that version's entry before the
+  first publish; a mismatch or a missing entry stops the run with nothing published
+  (`release.integrity_mismatch`).
+
+Relative paths, the default root and the output directories resolve against the current directory
+of the process: in a package script that is the package's directory, so `"pack": "capybara-plugin
+pack ."` in a plugin's `package.json` packs that plugin. `capybara-plugin <command> --help` prints
+one command's usage.
+
+## Testing plugins against the published kernel
+
+A plugin's kernel-level tests load the plugin by path (`plugins/<name>/src/index.ts`, imports
+written `./x.js`) into a kernel installed from npm. Vitest externalizes `node_modules`, so the
+kernel's `import()` would run in plain Node, which does not map `./x.js` to `./x.ts`. Inline the
+core packages in `vitest.config.ts` (the pattern is matched against the resolved file path, not
+the package name):
+
+```ts
+export default defineConfig({
+  test: { server: { deps: { inline: [/\/node_modules\/@capybara-hq\//] } } },
+});
+```
+
+Dual-replica tests (`createDualReplicaHarness`) need nothing more: each replica is a child
+process outside vitest, and `@capybara-hq/testing` runs it under its own tsx when an extension
+entry is a TypeScript file (the plugin under test by path, `fakeExtensionEntry(...)`). Do not set
+`NODE_OPTIONS: "--import tsx"` in the vitest config: it reaches every worker and child process
+and hides packaging bugs.
+
+## Library
+
+The same code as functions: `packPlugin`, `packBootstrap`, `pluginChecks` / `runChecks` and each
+check (`checkDeps`, `checkPluginState`, `checkPluginPermissions`, `checkPluginPack`,
+`checkToolDesign`, `checkMigrations`, `checkAppliedMigrations`, `checkPluginTestImports`,
+`checkPluginReleaseMetadata`), `syncPluginVersions` (after `changeset version`),
+`syncMarketplace`, `planPublish`, `distTagFor`, `runPublish` and `integrityOf`. The subpaths
+`@capybara-hq/plugin-tools/pack`, `/release` and `/source` load without the kernel.
+
+- How plugins are written: [.agents/skills/writing-plugins](https://github.com/capybara-hq/core/tree/main/.agents/skills/writing-plugins).
+- The repository: [capybara-hq/core](https://github.com/capybara-hq/core).

package/bin/capybara-plugin.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+// The `capybara-plugin` bin: runs the compiled CLI (dist/cli.js, built by `tsc -b`). In this
+// repository, the root scripts (pnpm pack-plugin, pack-plugins, pack-bootstrap, release) run the
+// TypeScript sources through tsx instead.
+import { existsSync } from "node:fs";
+
+const dist = new URL("../dist/cli.js", import.meta.url);
+if (!existsSync(dist)) {
+  process.stderr.write("capybara-plugin: dist/cli.js not found; build the package first\n");
+  process.exit(1);
+}
+await import(dist.href);

package/dist/check/applied-migrations.d.ts

@@ -0,0 +1,28 @@
+import type { Finding } from "./source.js";
+/** Whether a repo-relative POSIX path is a migration file the check guards. */
+export type MigrationFilePredicate = (path: string) => boolean;
+/**
+ * A {@link MigrationFilePredicate} for migration directories given as globs relative to the
+ * repository root (`plugins/*\/migrations`, `packages/kernel/src/migrations`, `migrations` for a
+ * single-plugin repository): a `*.sql` file directly inside a matching directory. Globs also match
+ * directories that no longer exist, so deleting a whole plugin's migrations is still reported.
+ */
+export declare function migrationFileMatcher(dirGlobs: string[]): MigrationFilePredicate;
+/**
+ * PR check: an applied migration is never edited, deleted or renamed. The migrator records each
+ * file by name and checksum: an edited file stops `capybara migrate` (checksum mismatch) on every
+ * database that already ran it, a renamed one is out of order there, and a deleted one leaves those
+ * databases on a different schema than fresh ones. Fresh test databases pass either way, so only a
+ * diff check catches it. Adding new files is fine.
+ *
+ * `nameStatus` is the output of `git diff --name-status -M <base>...HEAD`: an `M`, `D` or `T`
+ * entry on a migration (`isMigration`), or an `R` entry whose source is a migration, is reported.
+ * `A` and `C` (a new file) are not.
+ */
+export declare function checkAppliedMigrations(nameStatus: string, isMigration: MigrationFilePredicate): Finding[];
+/**
+ * Runs {@link checkAppliedMigrations} on `<base>...HEAD` (changes since the merge base) in `cwd`.
+ * Paths are relative to `cwd` (`git diff --relative`), so `cwd` may be a subdirectory of the
+ * repository; finding files are relative to `cwd` too.
+ */
+export declare function diffAppliedMigrations(cwd: string, base: string, isMigration: MigrationFilePredicate): Finding[];

package/dist/check/applied-migrations.js

@@ -0,0 +1,65 @@
+import { execFileSync } from "node:child_process";
+import { globToRegExp } from "../discover.js";
+/**
+ * A {@link MigrationFilePredicate} for migration directories given as globs relative to the
+ * repository root (`plugins/*\/migrations`, `packages/kernel/src/migrations`, `migrations` for a
+ * single-plugin repository): a `*.sql` file directly inside a matching directory. Globs also match
+ * directories that no longer exist, so deleting a whole plugin's migrations is still reported.
+ */
+export function migrationFileMatcher(dirGlobs) {
+    const dirs = dirGlobs.map(globToRegExp);
+    return (path) => {
+        if (!path.endsWith(".sql"))
+            return false;
+        const slash = path.lastIndexOf("/");
+        const dir = slash < 0 ? "" : path.slice(0, slash);
+        return dirs.some((re) => re.test(dir));
+    };
+}
+/**
+ * PR check: an applied migration is never edited, deleted or renamed. The migrator records each
+ * file by name and checksum: an edited file stops `capybara migrate` (checksum mismatch) on every
+ * database that already ran it, a renamed one is out of order there, and a deleted one leaves those
+ * databases on a different schema than fresh ones. Fresh test databases pass either way, so only a
+ * diff check catches it. Adding new files is fine.
+ *
+ * `nameStatus` is the output of `git diff --name-status -M <base>...HEAD`: an `M`, `D` or `T`
+ * entry on a migration (`isMigration`), or an `R` entry whose source is a migration, is reported.
+ * `A` and `C` (a new file) are not.
+ */
+export function checkAppliedMigrations(nameStatus, isMigration) {
+    const findings = [];
+    for (const line of nameStatus.split("\n")) {
+        if (line === "")
+            continue;
+        const [status = "", from = ""] = line.split("\t");
+        const kind = status[0];
+        if (kind === "A" || kind === "C")
+            continue;
+        if (!isMigration(from))
+            continue;
+        const what = kind === "D"
+            ? "deleted"
+            : kind === "R"
+                ? "renamed"
+                : kind === "T"
+                    ? "changed type"
+                    : "edited";
+        findings.push({
+            file: from,
+            line: 1,
+            rule: "applied-migration-edited",
+            message: `migration ${what}: applied migrations are immutable (the migrator records them by name and checksum); restore it and add a new migration instead`,
+        });
+    }
+    return findings;
+}
+/**
+ * Runs {@link checkAppliedMigrations} on `<base>...HEAD` (changes since the merge base) in `cwd`.
+ * Paths are relative to `cwd` (`git diff --relative`), so `cwd` may be a subdirectory of the
+ * repository; finding files are relative to `cwd` too.
+ */
+export function diffAppliedMigrations(cwd, base, isMigration) {
+    const out = execFileSync("git", ["diff", "--name-status", "--no-ext-diff", "--relative", "-M", `${base}...HEAD`], { cwd, encoding: "utf8" });
+    return checkAppliedMigrations(out, isMigration);
+}

package/dist/check/cli.d.ts

@@ -0,0 +1,16 @@
+export declare const CHECK_USAGE = "capybara-plugin check [--root <dir>] [--plugins <glob>] [--base <ref>]";
+/**
+ * `capybara-plugin check`: runs every plugin-scoped check on the plugins of a repository.
+ *
+ * - `--root <dir>`: the repository (default: the current directory);
+ * - `--plugins <glob>`: the plugin directories, relative to the root (`*` within one segment);
+ *   default `plugins/*` when `<root>/plugins` exists, else the root itself when it holds
+ *   `.capybara-plugin/plugin.json`;
+ * - `--base <ref>`: also fail when `<ref>...HEAD` edits, deletes or renames a migration of a plugin
+ *   (applied migrations are immutable); for pull requests.
+ *
+ * Finding no plugin is an error: an empty scan would pass without checking anything.
+ *
+ * Relative paths resolve against `cwd` (the current directory). Returns the exit code.
+ */
+export declare function checkCommand(args: string[], cwd: string): Promise<number>;

package/dist/check/cli.js

@@ -0,0 +1,69 @@
+import { join, relative, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { discoverPlugins, pluginsGlobOf } from "../discover.js";
+import { diffAppliedMigrations, migrationFileMatcher } from "./applied-migrations.js";
+import { pluginChecks, runChecks } from "./run.js";
+export const CHECK_USAGE = "capybara-plugin check [--root <dir>] [--plugins <glob>] [--base <ref>]";
+/**
+ * `capybara-plugin check`: runs every plugin-scoped check on the plugins of a repository.
+ *
+ * - `--root <dir>`: the repository (default: the current directory);
+ * - `--plugins <glob>`: the plugin directories, relative to the root (`*` within one segment);
+ *   default `plugins/*` when `<root>/plugins` exists, else the root itself when it holds
+ *   `.capybara-plugin/plugin.json`;
+ * - `--base <ref>`: also fail when `<ref>...HEAD` edits, deletes or renames a migration of a plugin
+ *   (applied migrations are immutable); for pull requests.
+ *
+ * Finding no plugin is an error: an empty scan would pass without checking anything.
+ *
+ * Relative paths resolve against `cwd` (the current directory). Returns the exit code.
+ */
+export async function checkCommand(args, cwd) {
+    const { values } = parseArgs({
+        args,
+        options: {
+            help: { type: "boolean", short: "h", default: false },
+            root: { type: "string" },
+            plugins: { type: "string" },
+            base: { type: "string" },
+        },
+    });
+    if (values.help) {
+        console.log(`usage: ${CHECK_USAGE}`);
+        return 0;
+    }
+    const root = values.root === undefined ? cwd : resolve(cwd, values.root);
+    let plugins;
+    try {
+        plugins = discoverPlugins(root, values.plugins);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        return 2;
+    }
+    if (plugins.length === 0) {
+        console.error(`${relative(cwd, root) || "."}: no plugin found (${values.plugins ?? "plugins/* or .capybara-plugin/plugin.json"}); the checks would check nothing`);
+        return 1;
+    }
+    console.log(`checking ${plugins.length} plugin(s): ${plugins.map((p) => relative(root, p) || ".").join(", ")}`);
+    const checks = pluginChecks({ root, plugins });
+    const base = values.base;
+    if (base !== undefined) {
+        const glob = pluginsGlobOf(root, values.plugins);
+        const isMigration = migrationFileMatcher([glob === "." ? "migrations" : `${glob}/migrations`]);
+        checks.push({
+            name: "Applied migrations",
+            run: () => diffAppliedMigrations(root, base, isMigration).map((f) => ({
+                ...f,
+                file: join(root, f.file),
+            })),
+        });
+    }
+    const failed = await runChecks(checks, root);
+    if (failed > 0) {
+        console.error(`\n${failed} check(s) failed`);
+        return 1;
+    }
+    console.log("\nAll plugin checks passed");
+    return 0;
+}

package/dist/check/deps.d.ts

@@ -0,0 +1,23 @@
+import { type Finding } from "./source.js";
+export type { Finding };
+/**
+ * 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 declare function checkDeps(pluginDirs: string[], sdkDirs?: string[]): Finding[];