bookclerk_plugin_tools
Plugin authoring tools behind the bookclerk-plugin CLI: check, fmt,
sync-embed, package, smoke, and test.
Audience: plugin maintainers validating plugin.toml layout and packaging
archives for distribution. Kept out of bookclerk-plugin-sdk so guest
plugins never link bookclerk-workerd or the packaging stack.
| Helper | Purpose |
|---|---|
check_plugin / fmt_plugin_toml / package_plugin |
Validate, format, archive |
sync_embed |
Optional workerd JS vendor |
run_tools_cli / smoke_plugin |
CLI entry + live workerd smoke |
test_plugin |
The plugin's suite under every database profile |
See docs/plugins/README.md and the crate README.
| Item | Kind | Summary |
|---|---|---|
MainModuleLanguage |
enum | Source language of a workerd main_module, chosen by file extension. |
TestRunner |
enum | The test runner a plugin directory's layout names. |
check_main_module_source |
function | Checks a workerd main module against the api_version 3 author model. |
check_plugin |
function | Validates plugin.toml and the on-disk layout under plugin_dir. |
entrypoint_export_class |
function | Exported class name the v3 author model expects for a named entrypoint (storefront → Storefront, databaseAdapter → DatabaseAdapter). |
sync_embed |
function | Optionally vendors the workerd JS embed under the plugin modules tree. |
run_tools_cli |
function | Runs the authoring CLI (check / fmt / sync-embed / package / smoke / test). |
package_plugin |
function | Packages a plugin directory into out_dir as a .tar.gz plus SHA256SUMS. |
detect_test_runner |
function | Picks the test runner from the files in plugin_dir. |
kit_binary |
function | Locates the bookclerk-db-testkit binary. |
test_plugin |
function | Runs the plugin's test suite once per profile. |
smoke_plugin |
function | Smokes a runtime = "workerd" plugin: ensure pin → materialize → describe + health. |
fmt_plugin_toml |
function | Formats plugin.toml text to the canonical serialized form. |
load_manifest |
function | Parses and validates plugin.toml text without rewriting it. |
KIT_BINARY_ENV |
constant | Environment variable the SDK wrappers read for the kit binary's path. |
KIT_PROFILE_ENV |
constant | Environment variable the SDK wrappers read as their default profile. |
TEST_DATABASE_PROFILES |
constant | The capability profiles the kit serves, in the order a run reports them. |
pub enum MainModuleLanguage {
Js,
Python,
}
Source language of a workerd main_module, chosen by file extension.
Variants
Js:.js/.mjsmodule authored against@bookclerk/plugin-sdk/workerd.Python:.pyPython Worker authored againstbookclerk_plugin_sdk.workerd.
Implements: Clone, Copy, Debug, Eq, PartialEq
pub enum TestRunner {
Npm,
Pytest,
Cargo,
}
The test runner a plugin directory's layout names.
Variants
Npm:package.jsonwith atestscript:npm test.Pytest:pyproject.toml:python -m pytest.Cargo:Cargo.toml:cargo test.
pub fn argv(self) -> Vec<String>
The program and leading arguments that run this runner's suite.
The executable name followed by the arguments before any the author
passes after --.
pub fn name(self) -> &'static str
Short name for reports (npm, pytest, cargo).
Implements: Clone, Copy, Debug, Eq, PartialEq
pub fn check_main_module_source(
main_name: &str,
src: &str,
entrypoints: &[Entrypoint],
language: MainModuleLanguage,
) -> Result<()>
Checks a workerd main module against the api_version 3 author model.
Mirrors checkMainModuleSource in the TypeScript SDK and
check_main_module_source in the Python SDK: the module must import the
SDK, must not reference the removed BookclerkPlugin base, must not
subclass bare WorkerEntrypoint, and must export (JS) or define (Python)
one class per named entrypoint in entrypoints.
main_name- Module file name used in error messages.src- Module source text.entrypoints- Named entrypoints declared inplugin.toml.language- Module language chosen from the file extension.
Returns SdkError describing the first violated rule.
pub fn check_plugin(plugin_dir: &Path) -> Result<String>
Validates plugin.toml and the on-disk layout under plugin_dir.
Checks embedded logo paths, native command presence when
.require-binary is set, and workerd modules_dir / main_module plus the
api_version 3 author-model heuristics of check_main_module_source.
plugin_dir- Directory containingplugin.toml(usually.or the staged plugin root).
Human-readable success line (ok id=… kind=… runtime=…) for CLI stdout.
Returns SdkError when the manifest is missing/invalid, required files
are absent, or a workerd main module fails the author-model heuristics
(removed BookclerkPlugin, bare WorkerEntrypoint, missing entrypoint class).
pub fn entrypoint_export_class(entrypoint: Entrypoint) -> String
Exported class name the v3 author model expects for a named entrypoint
(storefront → Storefront, databaseAdapter → DatabaseAdapter).
entrypoint- Named entrypoint fromplugin.toml.
Class name the adapter isolate resolves through PLUGIN_<ENTRYPOINT>.
pub fn sync_embed(plugin_dir: &Path) -> Result<String>
Optionally vendors the workerd JS embed under the plugin modules tree.
Writes bookclerk_plugin_sdk::workerd::EMBED_BOOKCLERK_PLUGIN_JS_SRC to
modules/@bookclerk/plugin-sdk/workerd.js (paths from the manifest). Hosts
normally inject this package at runtime — use sync only for offline /
hermetic trees.
plugin_dir- Workerd plugin root (runtime = "workerd").
Success message including the destination path.
Returns SdkError when the manifest is not workerd, main_module is not
.js/.mjs, or filesystem writes fail.
pub fn run_tools_cli() -> ExitCode
Runs the authoring CLI (check / fmt / sync-embed / package / smoke / test).
Reads std::env::args after the binary name. Unknown commands or missing
required flags print usage to stderr and return exit code 2.
Process [ExitCode]: 0 on success, 1 on command failure, 2 on usage
errors.
// from src/bin/bookclerk-plugin.rs
fn main() -> std::process::ExitCode {
bookclerk_plugin_tools::run_tools_cli()
}
pub fn package_plugin(plugin_dir: &Path, out_dir: &Path) -> Result<PathBuf>
Packages a plugin directory into out_dir as a .tar.gz plus SHA256SUMS.
Native guests include the binary named by command (mode 0755 on Unix)
and name the archive with the host target triple. Workerd guests copy the
modules_dir tree and use a -workerd archive stem. Existing
SHA256SUMS lines for the same archive name are replaced.
plugin_dir- Directory containingplugin.tomland guest payload.out_dir- Destination directory for the archive and checksums file (created if missing).
Absolute or relative path to the written .tar.gz archive.
Returns SdkError when the manifest is invalid, required binaries /
modules are missing, or archive / checksum I/O fails.
pub fn detect_test_runner(plugin_dir: &Path) -> Result<TestRunner>
Picks the test runner from the files in plugin_dir.
package.json wins when it declares a test script, then
pyproject.toml, then Cargo.toml, so a TypeScript plugin that also
carries a Cargo.toml for a WASM module runs its JavaScript suite.
plugin_dir- Directory containingplugin.toml.
The runner to invoke.
Returns SdkError when no runner is recognized or package.json
cannot be parsed.
pub fn kit_binary() -> Result<PathBuf>
Locates the bookclerk-db-testkit binary.
Order: BOOKCLERK_DB_TESTKIT, then a sibling of this executable (a
workspace target/<profile> holds both after
cargo build -p bookclerk-db-testkit), then PATH.
The binary's path.
Returns SdkError naming the three places searched when none holds the
binary.
pub fn test_plugin(
plugin_dir: &Path,
profiles: &[String],
runner_args: &[String],
) -> Result<String>
Runs the plugin's test suite once per profile.
Each run inherits stdio and gets BOOKCLERK_DB_TESTKIT and
BOOKCLERK_DB_TESTKIT_PROFILE in its environment. Every profile runs
even after one fails, so a report names them all.
plugin_dir- Directory containingplugin.tomland the test runner's manifest.profiles- Profile names to run, each one ofTEST_DATABASE_PROFILES.runner_args- Extra arguments appended to the runner's command line (after--fornpm testandcargo test).
One profile <name>: ok line per profile for CLI stdout.
Returns SdkError when a profile name is unknown, no runner is found,
the kit binary is missing, a runner cannot start, or any profile's run
exits non-zero (the message lists the failed profiles).
pub fn smoke_plugin(plugin_dir: &Path) -> Result<String, String>
Smokes a runtime = "workerd" plugin: ensure pin → materialize → describe + health.
Spawns unconfined workerd serve on a free loopback port (jailed guests use
a listen FD via the launcher instead). Kills the child before returning.
plugin_dir- Directory containingplugin.tomlwithruntime = "workerd".
Multi-line success text including pretty-printed describe/health JSON.
Returns a plain String error when the manifest is not workerd, workerd
cannot be ensured, health never becomes ready, or RPC calls fail.
pub fn fmt_plugin_toml(text: &str) -> Result<String, Error>
Formats plugin.toml text to the canonical serialized form.
Parses with the manifest crate, then re-emits a stable key order / spacing
suitable for bookclerk-plugin fmt and CI --check diffs.
text- Raw contents of aplugin.tomlfile.
Canonical TOML string (typically ending with a trailing newline).
Returns a manifest parse/format error when the text is invalid TOML or fails schema validation.
pub fn load_manifest(text: &str) -> Result<PluginManifest, Error>
Parses and validates plugin.toml text without rewriting it.
text- Raw contents of aplugin.tomlfile.
Structured PluginManifest ready for inspection.
Returns a manifest error when parsing or validation fails.
pub const KIT_BINARY_ENV: &str = "BOOKCLERK_DB_TESTKIT";
Environment variable the SDK wrappers read for the kit binary's path.
pub const KIT_PROFILE_ENV: &str = "BOOKCLERK_DB_TESTKIT_PROFILE";
Environment variable the SDK wrappers read as their default profile.
pub const TEST_DATABASE_PROFILES: [&str; 3] = _;
The capability profiles the kit serves, in the order a run reports them.
The kit binary owns the definitions (bookclerk_db_testkit::Profile); it
refuses a name outside this list, so the two stay aligned by its test.
Generated from crates/bookclerk-plugin-tools at main · View as Markdown