Put your workflow in Finder’s context menu.

01

Open by design. Host authority stays closed.

A RightMenu plugin is an independently maintained JavaScript package. The host owns validation, installation, consent, and execution boundaries; a plugin receives only capabilities declared for the current action and granted by the user.

The current scope covers open development, local import, and user trust only. It does not include a marketplace, community index, or automatic updates.

02

Quick start

After installing RightMenu, use the signed command-line tool bundled inside the app to generate a project and run doctor.

Bundled CLI path

/Applications/RightMenu.app/Contents/Helpers/rightmenu-pluginctl

Generate a runnable project

init refuses to overwrite an existing path. The generated project includes a runnable plugin, the API v1.5 Schema, and the matching TypeScript declaration.

CLI="/Applications/RightMenu.app/Contents/Helpers/rightmenu-pluginctl"
"$CLI" init ./MyPlugin \
  --id dev.example.my-plugin \
  --name "My Plugin"
"$CLI" doctor ./MyPlugin

Develop a RightMenu Plugin API v1.5 plugin in the current directory.

Plugin requirement: [describe the plugin here]

Requirements:
- Read README.md, schema/rightmenu-plugin-manifest-v1.5.schema.json, and types/rightmenu-plugin-api-v1.5.d.ts first.
- Modify only this plugin project; do not change the RightMenu host source.
- Produce JavaScriptCore-compatible output, bundle every import, and use no Node.js require or native code.
- Declare requiredCapabilities for every action and uiContribution, and keep permissions minimal.
- After changing payload files, update byteCount and SHA-256 in manifest.json files.
- Finish by running "/Applications/RightMenu.app/Contents/Helpers/rightmenu-pluginctl" doctor .
- Completion requires doctor to exit 0 and report validation.ok.
- Do not generate a private key, sign, or pack unless explicitly requested.

03

Generated package structure

Plugin packages end in .rightmenuplugin. manifest.json declares the entrypoint, actions, access, and every payload file; distribute bundled plain JavaScript only.

MyPlugin/
├── README.md
├── plugin/
│   └── my-plugin.rightmenuplugin/
│       ├── manifest.json
│       └── main.js
├── schema/
│   └── rightmenu-plugin-manifest-v1.5.schema.json
└── types/
    └── rightmenu-plugin-api-v1.5.d.ts

04

Manifest and API v1.5

Every Finder action and UI contribution must declare requiredCapabilities; use an empty array when none are needed. Each capability must appear in permissions, and unused broad permissions are rejected.

{
  "apiVersion": "1.5",
  "permissions": [{
    "capability": "selection.read",
    "reason": "Reads metadata for selected Finder items."
  }],
  "actions": [
    { "id": "about", "title": "About", "requiredCapabilities": [] },
    { "id": "inspect", "title": "Inspect", "requiredCapabilities": ["selection.read"] }
  ],
  "uiContributions": []
}

globalThis.rightMenuPlugin = Object.freeze({
  run(actionID, input) {
    if (actionID !== "inspect") return { handled: false };
    return RightMenu.call("selection.read", {});
  }
});

JSON Schema improves editor feedback. rightmenu-pluginctl doctor remains authoritative for filesystem safety, digests, cross-array rules, compatibility, and signatures.

05

Develop and validate with doctor

After changing JavaScript, update byteCount and SHA-256 for every changed file in the manifest, then run doctor. It emits at most 32 bounded diagnostics and exits nonzero when any error exists.

1. 1

   Produce JavaScriptCore-compatible output; bundle every import and leave no Node.js require calls.

2. 2

   Update byte counts and SHA-256 values in files; never list manifest.json itself.

3. 3

   Run doctor until validation.ok, then resolve API, capability, signature, or package diagnostics.

"$CLI" doctor ./MyPlugin
"$CLI" doctor ./MyPlugin/plugin/my-plugin.rightmenuplugin

06

Local import and Developer Mode

Open RightMenu → Settings → Plugins. Use Import Signed Plugin for signed packages. For an unsigned directory, explicitly enable Developer Mode, then choose Import Unsigned Development Plugin. The roots are physically separate.

Installation is not consent. The host validates before and after copying and completes installation only after the final move. Disabling Developer Mode prevents unsigned invocation.

07

Action-scoped access

API v1.5 evaluates capabilities per action. A missing grant hides only dependent actions; other authorized actions remain available. Every grant is revocable.

08

Publisher signing and fingerprints

Production distribution uses Ed25519. On first import from an unknown self-issued publisher, the user compares the full SHA-256 public-key fingerprint before choosing Trust & Install. Signing identity grants no runtime capability.

"$CLI" keygen ./publisher.private.json "Example Publisher"
"$CLI" sign \
  ./MyPlugin/plugin/my-plugin.rightmenuplugin \
  ./publisher.private.json
"$CLI" inspect-signature \
  ./MyPlugin/plugin/my-plugin.rightmenuplugin
"$CLI" pack \
  ./MyPlugin/plugin/my-plugin.rightmenuplugin \
  ./my-plugin.rightmenuplugin.zip

Keep the private-key file outside the project, back it up securely, and never commit or distribute it. Losing it prevents existing installations from accepting updates under the same publisher identity.

An update for an installed plugin ID must use the exact same signing key. Even another trusted key cannot take over. Automatic updates and key rotation are not part of this version.

09

Common diagnostic codes

Automation should read the stable code and process exit status, never parse explanatory text.

10

Compatibility and runtime constraints

New projects use API v1.5 and require RightMenu 0.1.41 or later. v1.5 remains backward-compatible with v1.0–v1.4; older packages keep plugin-wide access behavior. Target JavaScriptCore and bound loops, recursion, memory, and output.

Finder actions support eligible selections of 1–20 local regular files. Before invocation, the host re-scans and revalidates the action and its exact grant set.