bookclerk_plugin_tools

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

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.

Enums

MainModuleLanguage

pub enum MainModuleLanguage {
    Js,
    Python,
}

Source language of a workerd main_module, chosen by file extension.

Variants

  • Js: .js / .mjs module authored against @bookclerk/plugin-sdk/workerd.
  • Python: .py Python Worker authored against bookclerk_plugin_sdk.workerd.

Implements: Clone, Copy, Debug, Eq, PartialEq

TestRunner

pub enum TestRunner {
    Npm,
    Pytest,
    Cargo,
}

The test runner a plugin directory's layout names.

Variants

  • Npm: package.json with a test script: npm test.
  • Pytest: pyproject.toml: python -m pytest.
  • Cargo: Cargo.toml: cargo test.

TestRunner::argv

pub fn argv(self) -> Vec<String>

The program and leading arguments that run this runner's suite.

Returns

The executable name followed by the arguments before any the author passes after --.

TestRunner::name

pub fn name(self) -> &'static str

Short name for reports (npm, pytest, cargo).

Implements: Clone, Copy, Debug, Eq, PartialEq

Functions

check_main_module_source

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.

Arguments

  • main_name - Module file name used in error messages.
  • src - Module source text.
  • entrypoints - Named entrypoints declared in plugin.toml.
  • language - Module language chosen from the file extension.

Errors

Returns SdkError describing the first violated rule.

check_plugin

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.

Arguments

  • plugin_dir - Directory containing plugin.toml (usually . or the staged plugin root).

Returns

Human-readable success line (ok id=… kind=… runtime=…) for CLI stdout.

Errors

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).

entrypoint_export_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).

Arguments

  • entrypoint - Named entrypoint from plugin.toml.

Returns

Class name the adapter isolate resolves through PLUGIN_<ENTRYPOINT>.

sync_embed

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.

Arguments

  • plugin_dir - Workerd plugin root (runtime = "workerd").

Returns

Success message including the destination path.

Errors

Returns SdkError when the manifest is not workerd, main_module is not .js/.mjs, or filesystem writes fail.

run_tools_cli

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.

Returns

Process [ExitCode]: 0 on success, 1 on command failure, 2 on usage errors.

Examples

// from src/bin/bookclerk-plugin.rs
fn main() -> std::process::ExitCode {
    bookclerk_plugin_tools::run_tools_cli()
}

package_plugin

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.

Arguments

  • plugin_dir - Directory containing plugin.toml and guest payload.
  • out_dir - Destination directory for the archive and checksums file (created if missing).

Returns

Absolute or relative path to the written .tar.gz archive.

Errors

Returns SdkError when the manifest is invalid, required binaries / modules are missing, or archive / checksum I/O fails.

detect_test_runner

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.

Arguments

  • plugin_dir - Directory containing plugin.toml.

Returns

The runner to invoke.

Errors

Returns SdkError when no runner is recognized or package.json cannot be parsed.

kit_binary

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.

Returns

The binary's path.

Errors

Returns SdkError naming the three places searched when none holds the binary.

test_plugin

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.

Arguments

  • plugin_dir - Directory containing plugin.toml and the test runner's manifest.
  • profiles - Profile names to run, each one of TEST_DATABASE_PROFILES.
  • runner_args - Extra arguments appended to the runner's command line (after -- for npm test and cargo test).

Returns

One profile <name>: ok line per profile for CLI stdout.

Errors

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).

smoke_plugin

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.

Arguments

  • plugin_dir - Directory containing plugin.toml with runtime = "workerd".

Returns

Multi-line success text including pretty-printed describe/health JSON.

Errors

Returns a plain String error when the manifest is not workerd, workerd cannot be ensured, health never becomes ready, or RPC calls fail.

fmt_plugin_toml

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.

Arguments

  • text - Raw contents of a plugin.toml file.

Returns

Canonical TOML string (typically ending with a trailing newline).

Errors

Returns a manifest parse/format error when the text is invalid TOML or fails schema validation.

load_manifest

pub fn load_manifest(text: &str) -> Result<PluginManifest, Error>

Parses and validates plugin.toml text without rewriting it.

Arguments

  • text - Raw contents of a plugin.toml file.

Returns

Structured PluginManifest ready for inspection.

Errors

Returns a manifest error when parsing or validation fails.

Constants

KIT_BINARY_ENV

pub const KIT_BINARY_ENV: &str = "BOOKCLERK_DB_TESTKIT";

Environment variable the SDK wrappers read for the kit binary's path.

KIT_PROFILE_ENV

pub const KIT_PROFILE_ENV: &str = "BOOKCLERK_DB_TESTKIT_PROFILE";

Environment variable the SDK wrappers read as their default profile.

TEST_DATABASE_PROFILES

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