mirror of
https://github.com/getpaseo/paseo.git
synced 2026-10-23 01:32:40 +00:00
Mohamed Boudra
d6d4084a06
* docs(plugins): explain registry publishing requirements * docs(plugins): trim publishing guidance to author tasks
284 lines
13 KiB
Markdown
284 lines
13 KiB
Markdown
---
|
|
title: Publish a plugin
|
|
description: Prepare, publish and submit a Paseo plugin to the reviewed registry.
|
|
nav: Publishing
|
|
order: 45
|
|
category: Plugins
|
|
---
|
|
|
|
# Publish a plugin
|
|
|
|
Start with a working [plugin project](/docs/plugins). Prepare its listing, publish it on npm
|
|
or push it to GitHub, then submit it to the registry. After approval, users install the reviewed
|
|
version with `paseo plugin add owner/slug`.
|
|
|
|
1. Prepare your [listing page](#your-listing-page) and, for a visual plugin, an
|
|
[interface image](#icons-and-screenshots).
|
|
2. [Publish on npm](#publish-on-npm) or [share through Git](#share-through-github-or-git).
|
|
3. [Submit to the plugin registry](#plugin-registry).
|
|
|
|
For a private plugin, use [direct Git installation](#share-through-github-or-git) or
|
|
[private npm packages](#private-npm-packages).
|
|
|
|
## Your listing page
|
|
|
|
You can submit without `OVERVIEW.md`; the reviewer creates a listing page from your README and
|
|
verified behavior. To maintain the page yourself, put `OVERVIEW.md` beside `paseo-plugin.json`
|
|
and include it in the published package. The scaffold already includes it in `files`.
|
|
Your shipped overview replaces the reviewer-written page.
|
|
|
|
Explain these points in order, using headings only when they help:
|
|
|
|
1. What the plugin does.
|
|
2. How it works, when that is not obvious.
|
|
3. Setup: settings, accounts, tokens, external tools, supported operating systems and Paseo versions.
|
|
4. Useful capabilities, settings, data access, permissions and limitations.
|
|
|
|
Describe where data goes, including prompts and tool results sent to agent providers. Local storage
|
|
does not mean data stays on the host. If the plugin downloads or installs software while running,
|
|
explain what it installs and its source, and require explicit user confirmation before the download.
|
|
This applies to activation and connection tests too; declining must leave the software uninstalled.
|
|
|
|
Use plain factual language and sentence case. Omit marketing, unsupported claims, badges,
|
|
changelogs, contributing and license sections, and implementation details that do not help someone
|
|
choose the plugin. The listing already provides plugin installation instructions.
|
|
|
|
The publication validator rejects `paseo plugin add`, `npm install` and `npm i` anywhere in an
|
|
overview, including development or setup examples. Link to your README for those commands.
|
|
|
|
Also supply a one-sentence description: use `package.json`'s `description` for npm or the manifest's
|
|
`description` for Git. The reviewer can fill in a missing description in the registry.
|
|
|
|
## Icons and screenshots
|
|
|
|
Themes, panels and other visual plugin interfaces need at least one image showing the current
|
|
interface. Use sample data and hide private details. An icon alone does not meet this requirement;
|
|
plugins without their own visual interface do not need screenshots.
|
|
|
|
Declare local images in `paseo-plugin.json` before publishing:
|
|
|
|
```json
|
|
{
|
|
"id": "review-tools",
|
|
"name": "Review tools",
|
|
"description": "Reviews changes before merge",
|
|
"icon": "assets/icon.png",
|
|
"media": ["assets/screenshot.png"],
|
|
"requirements": { "paseo": ">=0.11.0" }
|
|
}
|
|
```
|
|
|
|
Create the referenced files and include `assets/` in `package.json`'s `files` list for npm.
|
|
Paths are relative to the manifest, use forward slashes and stay inside the plugin directory.
|
|
These metadata fields require Paseo 0.11.0 or later.
|
|
|
|
| Field | Listing behavior |
|
|
| ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `name` | Optional display name; defaults to a humanized plugin ID. |
|
|
| `icon` | Optional package-relative PNG. Provider registration icons have a separate [SVG contract](/docs/plugins/reference#providers). |
|
|
| `media` | Package-relative paths or public HTTPS URLs. Images: PNG, JPG, JPEG, WebP or GIF. Videos: MP4 or WebM. The first image is the card thumbnail; videos supplement it. |
|
|
|
|
Public media URLs need a supported file extension, matched case-insensitively, and must return
|
|
HTTP 200 with the corresponding image or video content type. SVG and extensionless attachment
|
|
URLs are not accepted as registry media.
|
|
|
|
Instead of declaring `media`, you can supply suitable public image URLs in the submission or
|
|
review PR. The reviewer can add them to the listing without a new plugin release.
|
|
|
|
## Publish on npm
|
|
|
|
### 1. Set package identity
|
|
|
|
Use an npm scope you can publish to and authenticate with `npm login`. From your plugin directory,
|
|
replace `@acme` and the repository below with your own values:
|
|
|
|
```bash
|
|
npm pkg set name=@acme/paseo-review version=1.0.0
|
|
npm pkg delete private
|
|
npm pkg set repository.type=git repository.url=git+https://github.com/acme/paseo-review.git
|
|
```
|
|
|
|
The current registry tooling requires a GitHub repository for npm listing ownership, supplied
|
|
through `package.json` or npm provenance. Set `repository` to your public source repository so
|
|
pinning can determine the listing owner. Provenance itself is optional; if present, its repository
|
|
must match the package's repository. A matching source checkout is not required for artifact review.
|
|
|
|
### 2. Lock installed dependencies
|
|
|
|
Keep Paseo's host libraries and type-only dependencies in `devDependencies`. Add other runtime
|
|
libraries to `dependencies`. For registry submission, every installed dependency tree needs a lock
|
|
with exact versions, resolved sources and integrity, including transitive dependencies.
|
|
|
|
For an npm package with installed runtime dependencies, update its lock without running lifecycle
|
|
scripts, then create the publishable lock:
|
|
|
|
```bash
|
|
npm install --package-lock-only --ignore-scripts
|
|
npm shrinkwrap
|
|
```
|
|
|
|
`npm shrinkwrap` converts `package-lock.json` into `npm-shrinkwrap.json`. npm publishes the shrinkwrap
|
|
at the package root; it does not publish `package-lock.json`. A repository-only lock or exact direct
|
|
version does not lock the dependency tree installed by your users.
|
|
|
|
Plugins using only host libraries and development dependencies need no runtime lock unless a
|
|
preparation command installs those dependencies. You can also bundle a library and remove the
|
|
runtime dependency declaration. See [preparation and additional setup](#plugins-with-a-build-step)
|
|
if your plugin installs a separate tree.
|
|
|
|
### 3. Check the package and publish
|
|
|
|
Generate any required files before checking the package; the dry run skips packing scripts.
|
|
|
|
```bash
|
|
npm run typecheck
|
|
npm pack --dry-run --ignore-scripts
|
|
```
|
|
|
|
Check the file list contains `paseo-plugin.json`, at least one runtime entry, every imported local
|
|
module, any overview and assets you declared, and the shrinkwrap when required. Repository-only import aliases
|
|
and files outside the package do not reach users. The scaffold includes the entries and `client/`,
|
|
`server/` and `shared/`; add other asset directories to `files`.
|
|
|
|
Confirm any declared preparation command succeeds with the Node/npm versions you support;
|
|
an out-of-sync or incompatible lockfile still blocks installation.
|
|
|
|
Publish the checked version:
|
|
|
|
```bash
|
|
npm publish --access public
|
|
```
|
|
|
|
On a test daemon, install that exact published version and exercise its contributions:
|
|
|
|
```bash
|
|
paseo plugin install npm:@acme/paseo-review@1.0.0
|
|
paseo plugin ls
|
|
```
|
|
|
|
Require `running` with no error, then [submit the package](#plugin-registry).
|
|
|
|
## Share through GitHub or Git
|
|
|
|
For the public registry, push your plugin to a public GitHub repository. Include its manifest,
|
|
runtime entries, imported files and listing assets. Git tags and commits are optional at submission;
|
|
provide one to select a revision, or the reviewer resolves `main`.
|
|
|
|
If preparation installs runtime npm dependencies, commit a synchronized `package-lock.json` and
|
|
add this command to `paseo-plugin.json`:
|
|
|
|
```json
|
|
{
|
|
"build": [["npm", "ci", "--omit=dev", "--ignore-scripts"]]
|
|
}
|
|
```
|
|
|
|
`npm ci` consumes the committed lock and fails if it disagrees with `package.json`. `--omit=dev`
|
|
excludes development tools and `--ignore-scripts` suppresses dependency lifecycle scripts.
|
|
The daemon needs npm on its command path. Plugins using only host libraries need no preparation
|
|
command. See [preparation](#plugins-with-a-build-step) for generated files or explicit scripts.
|
|
|
|
Users can install directly from Git without a registry listing:
|
|
|
|
```bash
|
|
paseo plugin add git:acme/paseo-review
|
|
paseo plugin add git:acme/monorepo:plugins/review
|
|
```
|
|
|
|
Use `--ref` to select a branch, tag or commit for the initial installation. Direct installation
|
|
also supports private repositories and other Git hosts when the daemon has access; see
|
|
[plugin sources](/docs/plugins/reference#plugin-sources). Registry submission accepts public
|
|
GitHub sources and public npm packages.
|
|
|
|
## Plugin registry
|
|
|
|
Open the [submission form](https://github.com/getpaseo/plugins/issues/new?template=submit-plugin.yml).
|
|
Use the form so the issue receives the submission label that starts intake.
|
|
|
|
1. Use your plugin's name as the title.
|
|
2. In **Source**, enter the public npm package name or page, or the GitHub repository/folder URL.
|
|
Include the version or Git reference if you want a specific release reviewed. npm defaults to
|
|
`latest`. Registry IDs and local directories are not submission sources.
|
|
3. Select the categories that fit. Include any interface-image URLs in the issue description.
|
|
|
|
The bot opens a review PR. The reviewer inspects the artifact and dependencies without running
|
|
plugin code, completes the listing and records the exact approved version or commit. Publication
|
|
requires the [review policy](https://github.com/getpaseo/plugins/blob/main/REVIEW.md), including
|
|
locked installation inputs and appropriate data access, even when automated validation passes.
|
|
|
|
If a change is requested, reply on the review PR with the corrected version/revision or requested
|
|
image URL. The reviewer updates the pin and listing. Intake service errors retry automatically;
|
|
missing images or an overview do not prevent opening the review PR.
|
|
|
|
After approval and publication, users install your listing with:
|
|
|
|
```bash
|
|
paseo plugin add owner/slug
|
|
```
|
|
|
|
npm releases receive automatic update PRs. Submit Git updates manually with the desired revision.
|
|
Existing registry installations use approved pins; direct npm/Git installs follow their own update
|
|
rules in the [source reference](/docs/plugins/reference#plugin-sources).
|
|
|
|
## Plugins with a build step
|
|
|
|
Paseo compiles TypeScript, so an ordinary plugin needs no separate publication build.
|
|
Keep generated modules in their runtime directory and host-provided modules external.
|
|
|
|
Paseo suppresses npm lifecycle scripts during package acquisition. Commands explicitly declared in
|
|
manifest `build` still run, including scripts they invoke. Explain the purpose of those commands
|
|
and keep their inputs locked and inspectable. Remove Git-only dependency-install commands from
|
|
npm manifests when npm already installs the production dependencies.
|
|
|
|
Later setup that installs another dependency tree needs its own complete lock, even if your plugin
|
|
has a development lockfile. For npm setup, ship the runtime manifest and lock together and use
|
|
`npm ci`. For Python setup, ship a requirements file containing exact versions and SHA-256 hashes
|
|
for all transitive packages, then install it with:
|
|
|
|
```bash
|
|
python -m pip install --require-hashes -r requirements-documents.txt
|
|
```
|
|
|
|
This command rejects unpinned or unhashed dependencies. Runtime installation also needs the
|
|
[confirmation and disclosure](#your-listing-page) described above.
|
|
|
|
## Private npm packages
|
|
|
|
:::example[Publish a private package with GitHub Packages]
|
|
|
|
You can publish a company plugin to GitHub Packages. Follow the npm steps above, using your
|
|
organization's scope, and replace the publish command with:
|
|
|
|
```bash
|
|
npm publish --registry=https://npm.pkg.github.com
|
|
```
|
|
|
|
[Configure GitHub authentication and package access](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
|
|
before publishing.
|
|
|
|
To install the plugin, configure npm **on the daemon host, as the user running Paseo**:
|
|
|
|
1. Add your organization's registry to `~/.npmrc`:
|
|
|
|
```ini
|
|
@acme:registry=https://npm.pkg.github.com
|
|
```
|
|
|
|
2. Log in with your GitHub username and a personal access token (classic) as the password.
|
|
The token needs `read:packages` and access to the package.
|
|
|
|
```bash
|
|
npm login --scope=@acme --auth-type=legacy --registry=https://npm.pkg.github.com
|
|
```
|
|
|
|
3. Install the plugin:
|
|
|
|
```bash
|
|
paseo plugin install npm:@acme/paseo-review
|
|
```
|
|
|
|
Paseo uses the host's npm registry settings and credentials for installation and updates.
|
|
In the app, enter only the source identifier.
|
|
|
|
:::
|