Plugin API reference

This page summarizes the public plugin contract used by Jolter, @jolter/jdt, and the Jolter registry.

Plugin request syntax

eslint
eslint@1
@eslint/eslint
@eslint/eslint@1.0.0

If no selector is provided, Jolter uses latest. Scoped names use the selector after the package name, not the scope.

JDT commands

Install the toolkit:

npm install -D @jolter/jdt

Commands:

jdt init
jdt build
jdt build --wasm ./prebuilt.wasm
jdt manifest --version 1.2.3
jdt validate
jdt pack --version 1.2.3
jdt run list-tools
jdt run resolve-tool <tool> <selector> --os linux --arch x64
jdt run validate-installed <tool> <version> <root>

jdt pack writes:

dist/plugin.wasm
dist/plugin.release.json
dist/checksums.txt

Root manifest

Root manifests live at plugin.json in the GitHub repository root.

Field	Type	Meaning
`$schema`	string	Optional, must be `https://schemas.jolter.dev/plugin/v1/schema.json` when present
`schemaVersion`	integer	Must be `1`
`name`	string	Canonical scoped plugin name, for example `@example/example`
`displayName`	string	Optional human name
`description`	string	Required summary
`keywords`	string array	Optional search keywords
`homepage`	string	Optional URL
`repository.type`	string	Must be `git`
`repository.url`	string	GitHub HTTPS URL for the selected repository
`license`	string	License identifier or text
`readme`	string	Relative README path
`icon`	string	Optional relative icon path
`categories`	string array	Optional registry categories
`supports.jolter`	string	Supported Jolter version range
`links`	object	Optional named links
`provides.tools`	object	Tool declarations used by JDT and registry previews
`permissions`	object	Optional permission declaration copied into release manifests

Release manifest

Release manifests are generated as dist/plugin.release.json.

Field	Type	Meaning
`$schema`	string	Optional, must be `https://schemas.jolter.dev/plugin-release/v1/schema.json` when present
`schemaVersion`	integer	Must be `1`
`name`	string	Canonical plugin name
`version`	string	Plugin release version generated by JDT
`repository.type`	string	Must be `github`
`repository.owner`	string	GitHub owner
`repository.repo`	string	GitHub repository
`release.tag`	string	GitHub tag, usually `v<version>`
`release.commit`	string	Source commit
`jolter.minimumVersion`	string	Minimum Jolter version
`jolter.apiVersion`	string	Plugin API version
`entrypoint.type`	string	Must be `wasm`
`entrypoint.path`	string	WASM asset name
`provides.tools`	object	Tool definitions and command names
`permissions`	object	Declared plugin permissions
`artifacts.wasm.file`	string	WASM asset name
`artifacts.wasm.sha256`	string	Expected WASM SHA-256
`artifacts.wasm.size`	integer	Expected WASM byte length

The release tag must match v<version>. The release must contain plugin.release.json, the WASM file named by the manifest, and checksums.txt.

WIT world

package jolter:plugin;

interface api {
  record platform {
    os: string,
    arch: string
  }

  record tool {
    name: string,
    commands: list<string>
  }

  record tool-release {
    version: string,
    url: string,
    sha256: string,
    archive-format: string,
    strip-components: u32,
    commands: list<string>
  }
}

world jolter-plugin {
  use api.{platform, tool, tool-release};

  export list-tools: func() -> list<tool>;
  export resolve-tool: func(tool: string, selector: string, platform: platform) -> tool-release;
  export validate-installed: func(tool: string, version: string, root: string) -> bool;
}

In TypeScript, the toolkit uses camelCase field names:

archiveFormat: "tar.gz",
stripComponents: 1

The WIT interface uses kebab-case names:

archive-format: string,
strip-components: u32

TypeScript API

export interface Platform {
  os: string;
  arch: string;
}

export interface Tool {
  name: string;
  commands: string[];
  displayName?: string;
  description?: string;
}

export interface ToolRelease {
  version: string;
  url: string;
  sha256: string;
  archiveFormat: "tar.gz" | "zip";
  stripComponents: number;
  commands: string[];
}

resolveTool may return stable versions such as 1.0.0 or prerelease versions such as 1.0.0-rc.1 for the tool release. Plugin release manifests produced by JDT should use normal stable release versions.

Jolter CLI

jolter plugin install <name>[@selector]
jolter plugin list
jolter plugin list --json
jolter plugin update <name>
jolter plugin update --all
jolter plugin uninstall <name> [--force]

Aliases:

jolter plugin add eslint
jolter plugin i eslint
jolter plugin ls
jolter plugin up eslint
jolter plugin remove eslint
jolter plugin rm eslint

Project commands that may install missing declared plugins when approved:

jolter sync --yes
jolter setup-ci --yes

Environment variables

Variable	Purpose
`JOLTER_REGISTRY_URL`	Override the plugin registry API origin
`JOLTER_HOME`	Select the storage root for plugins and plugin tools
`JOLTER_OFFLINE`	Forbid network requests; plugin operations need cached or installed state

Register release action

Use jolterjs/register-release-action@v1 after a GitHub release is published. Inputs:

Input	Required	Meaning
`registry-url`	Yes	Registry API origin, usually `https://registry.jolter.dev`
`plugin-name`	Yes	Canonical plugin name or approved alias
`github-token`	Yes	Repository-scoped GitHub token
`version`	No	Semantic version override
`release-tag`	No	GitHub release tag override

Outputs:

version
release-tag
registered

The action treats an existing version as an idempotent result and sets registered=false.

​Plugin request syntax

​JDT commands

​Root manifest

​Release manifest

​WIT world

​TypeScript API

​Jolter CLI

​Environment variables

​Register release action