From d6d4084a06ce1cacb014ad512bd346eefdd8943f Mon Sep 17 00:00:00 2001 From: Mohamed Boudra Date: Thu, 15 Oct 2026 21:38:38 +0700 Subject: [PATCH] docs(plugins): make registry publishing requirements actionable (#6996) * docs(plugins): explain registry publishing requirements * docs(plugins): trim publishing guidance to author tasks --- public-docs/cli.md | 15 +- public-docs/community.md | 9 +- public-docs/plugins/publishing.md | 407 ++++++++++++++++-------------- public-docs/plugins/reference.md | 11 +- 4 files changed, 238 insertions(+), 204 deletions(-) diff --git a/public-docs/cli.md b/public-docs/cli.md index 1c348960b3..48f37e89de 100644 --- a/public-docs/cli.md +++ b/public-docs/cli.md @@ -228,11 +228,12 @@ The output includes each script's lifecycle and supervised terminal ID. Services Create and manage trusted plugins on a daemon: ```bash -paseo plugin init /absolute/path/to/plugin -paseo plugin install /absolute/path/to/plugin -paseo plugin add owner/repository +paseo plugin init ./plugin +paseo plugin install ./plugin +paseo plugin add owner/slug +paseo plugin add git:owner/repository paseo plugin add https://gitlab.com/group/repository.git --ref main -paseo plugin add owner/monorepo:plugins/review +paseo plugin add git:owner/monorepo:plugins/review paseo plugin ls [id] paseo plugin update my-plugin paseo plugin update --all @@ -243,8 +244,10 @@ paseo plugin enable my-plugin paseo plugin remove my-plugin ``` -GitHub shorthand checks an existing host directory first. Append `:` for a plugin in a -monorepo. `paseo plugin ls [id]` does not contact the remote. `paseo plugin logs ` returns the +Bare `owner/slug` installs a reviewed registry listing. Use `git:owner/repository` for GitHub +source, or `./plugin` for a local directory. Append `:` for a plugin in a monorepo. + +`paseo plugin ls [id]` does not contact the remote. `paseo plugin logs ` returns the plugin's recent daemon-side stdout and stderr. Add `--json` for structured entries, or run `paseo --host plugin logs ` for another daemon. See the [Plugin reference](/docs/plugins/reference) for installation, trust, lifecycle, and log-retention diff --git a/public-docs/community.md b/public-docs/community.md index 33ba212056..f18815990d 100644 --- a/public-docs/community.md +++ b/public-docs/community.md @@ -10,12 +10,11 @@ category: Getting started These projects are related to Paseo and built by the community. -## Plugin directory +## Plugins -[paseo.cafe](https://paseo.cafe) is a community-run directory of Paseo plugins. Listings are generated -from each plugin's public repository, so it is the fastest way to see what people are building and to -publish your own. It is independent of the Paseo project and nothing on it is reviewed or endorsed by -us, so read a plugin's source before installing it. +Browse the [plugin registry](/plugins) for reviewed community plugins. To share your own, follow +[Publish a plugin](/docs/plugins/publishing) for package preparation and submission. +Plugins run unsandboxed; read their listing and source before installing. ## Tools and integrations diff --git a/public-docs/plugins/publishing.md b/public-docs/plugins/publishing.md index 16cde2389a..f925d0f1d4 100644 --- a/public-docs/plugins/publishing.md +++ b/public-docs/plugins/publishing.md @@ -1,6 +1,6 @@ --- title: Publish a plugin -description: Share a Paseo plugin on npm, through a private registry, or from a Git repository. +description: Prepare, publish and submit a Paseo plugin to the reviewed registry. nav: Publishing order: 45 category: Plugins @@ -8,111 +8,241 @@ category: Plugins # Publish a plugin -Publish your plugin so other people can install and use it in Paseo. Start with a working -[plugin project](/docs/plugins), then choose where to share it: +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`. -- [Plugin registry](#plugin-registry): share a reviewed artifact users install by `owner/slug`. -- [npm](#publish-on-npm): publish a package on the public npm registry. -- [GitHub or Git](#share-through-github-or-git): let users install from a repository. +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 -Browse published plugins at [paseo.sh/plugins](https://paseo.sh/plugins). -Users install the reviewed artifact with: +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 ``` -Publish your artifact through npm or Git, then follow the -[registry submission guide](https://github.com/getpaseo/plugins) to submit it for review. -Registry installations and updates use the approved revision and plugin path. -Direct Git installs use explicit `git:owner/repository` shorthand or a full Git URL. +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). -## Publish on npm +## Plugins with a build step -The scaffold prepares the package files and development dependencies. You choose the package name -and release version. +Paseo compiles TypeScript, so an ordinary plugin needs no separate publication build. +Keep generated modules in their runtime directory and host-provided modules external. -### 1. Set your package name and version +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. -From the plugin directory, set your package details and allow publication. Replace `@acme` with your npm scope: +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 -npm pkg set name=@acme/paseo-review version=1.0.0 -npm pkg delete private +python -m pip install --require-hashes -r requirements-documents.txt ``` -### 2. Check and publish +This command rejects unpinned or unhashed dependencies. Runtime installation also needs the +[confirmation and disclosure](#your-listing-page) described above. -```bash -npm run typecheck -npm pack --dry-run -npm publish --access public -``` - -Check the pack output includes any assets you added to the project. - -### 3. Test the published plugin - -On a daemon host with npm available: - -```bash -paseo plugin install npm:@acme/paseo-review@1.0.0 -``` - -Users can also paste `npm:@acme/paseo-review` into **Settings → Plugins → Plugin source**. - -:::example[Package configuration] - -The scaffold includes this `files` list in `package.json`: - -```json -{ - "files": [ - "paseo-plugin.json", - "OVERVIEW.md", - "index.client.ts", - "index.client.tsx", - "index.server.ts", - "index.server.tsx", - "client/", - "server/", - "shared/" - ] -} -``` - -- Add any assets stored outside these directories to `files`. -- Keep the scaffold's SDK and host libraries in `devDependencies`. -- Add other runtime libraries with `npm install `. Paseo installs their dependencies too. -- The npm package name identifies the source. The manifest's `id` identifies the installed plugin. - -See the [project reference](/docs/plugins/reference#project-files) for entry points and runtime boundaries. - -::: - -### Plugins with a build step - -Paseo compiles TypeScript. An ordinary plugin needs no separate build before publication. -If your plugin generates files, include the generated output in the package. - -**Installation scripts do not run automatically.** If a dependency needs host-specific setup, -declare a [preparation command](/docs/plugins/reference#cli-reference). - -:::example[Generated files and dependencies] - -- Generate code and assets before running `npm publish`. -- Keep generated JavaScript in its runtime directory and import it from the TypeScript entry. -- Include generated assets in `files`. -- Keep host-provided modules external when producing your own bundle. -- Remove Git-only dependency-install commands from the published manifest; npm installation already - installs production dependencies. - -Paseo skips npm lifecycle scripts during installation, including dependency scripts. For example, -a native dependency that needs rebuilding requires an explicit preparation command. - -::: +## Private npm packages :::example[Publish a private package with GitHub Packages] @@ -151,104 +281,3 @@ Paseo uses the host's npm registry settings and credentials for installation and In the app, enter only the source identifier. ::: - -## Icons and screenshots - -Declare your display name, icon, screenshots, and demo videos in `paseo-plugin.json`: - -```json -{ - "id": "review-tools", - "name": "Review tools", - "description": "Reviews changes before merge", - "icon": "assets/icon.png", - "media": ["assets/screenshot.png", "https://example.com/review-demo.mp4"], - "requirements": { "paseo": ">=0.11.0" } -} -``` - -All three fields are optional. `name` gives the registry and website a display name without -changing the installation ID. When omitted, the registry falls back to a humanized ID. -Registry and website display requires the registry builder to read these fields from the pinned -manifest. That update is a separate follow-up; until it lands, these fields are exposed only -through the daemon's installed-plugin list. -`icon` must point to a PNG inside the plugin package. `media` accepts paths to images and videos -inside the package or HTTPS URLs, in display order. Paths are relative to the manifest; use -forward slashes and keep them inside the package. See the [manifest reference](/docs/plugins/reference#project-files) -for validation rules. - -Commit local assets alongside the manifest at the pinned revision. For npm, add their directory -(for example, `assets/`) to `package.json`'s `files` list and verify it with `npm pack --dry-run`. -The scaffold documents these fields in its manifest's `$comment`; add your display name and -assets before publishing. - -Manifests using these fields fail to install on daemons before 0.11.0. Set -`requirements.paseo` to `>=0.11.0` or a narrower supported range. - -## Your listing page - -Write `OVERVIEW.md` beside `paseo-plugin.json` for the plugin page inside Paseo. -It helps someone decide whether to install your plugin; the install command is already at -the top of that page. A README assumes a GitHub audience and carries installation -instructions, technical details, and badges. Long, AI-generated READMEs make people read -past that material to understand what a plugin does. - -`OVERVIEW.md` is required to list your plugin in the registry. Commit it beside -`paseo-plugin.json` in the source repository at the pinned commit. The registry resolves it -relative to the manifest, under `pluginPath` for monorepos. Include it in the published npm -package too; the scaffold's `files` list includes it. Replace the scaffold's guidance comment -with useful facts before publishing. - -The repository overview takes precedence over a registry import stopgap. Online validation -fails when the pinned commit has no `OVERVIEW.md`, except for unchanged imported records -that already carry `plugins//.md` in the registry repository. Every version bump -requires a repository overview and removes the stopgap in the same PR. A bump without the -repository overview fails validation. README files do not supply the overview. - -Author overviews and registry stopgaps follow the same content contract, in this order. -Choose headings only when they help; length follows complexity. A theme needs one paragraph. - -1. Explain what the plugin is and does in plain terms first. -2. Explain how it works only when that is not obvious. -3. Explain setup when needed: settings, accounts, tokens, providers, external tools, or other - plugins. Include applicable daemon version and operating system requirements. Setup - guidance is allowed; installation instructions are not. -4. Explain capabilities and settings worth understanding, what each option does, what the - plugin reads or sends and where, permissions, and known limits. - -Use sentence case and plain factual language, with no em dashes. Omit installation commands, -badges, changelog, contributing or license sections, marketing, and unsupported claims. -Avoid implementation filler such as empty cleanup functions, catalogs of theme-token fields, -or lists of absent features. Keep only what helps someone choose the plugin. - -If your plugin is an unchanged imported record, you can propose an author-written overview -to replace the registry stopgap. Do not add import credit to your own `OVERVIEW.md`. - -## Share through GitHub or Git - -Push the plugin project to a repository. Users can install it with: - -```bash -paseo plugin add git:acme/paseo-review -``` - -For another Git host: - -```bash -paseo plugin install git:https://git.example.com/acme/paseo-review.git -``` - -If your plugin has runtime npm dependencies, commit `package-lock.json` and add a preparation -command to `paseo-plugin.json`: - -```json -{ - "build": [["npm", "ci", "--omit=dev"]] -} -``` - -- `npm ci` installs the versions in the committed lockfile. -- `--omit=dev` excludes development tools. -- npm must be available on the daemon host. - -Plugins that only use Paseo's host libraries need no preparation command. diff --git a/public-docs/plugins/reference.md b/public-docs/plugins/reference.md index 04c88bdf1a..409bb3f5a6 100644 --- a/public-docs/plugins/reference.md +++ b/public-docs/plugins/reference.md @@ -63,7 +63,9 @@ The required root manifest is `paseo-plugin.json`: | `build` | No | Preparation commands, described in the CLI reference. | Paths are relative to `paseo-plugin.json`, use forward slashes, and cannot contain `..` -segments. See [icons and screenshots](/docs/plugins/publishing#icons-and-screenshots) for an example. +segments. Registry listings for visual plugins require an interface image even though `media` is +optional in the runtime manifest. See [icons and screenshots](/docs/plugins/publishing#icons-and-screenshots) +for accepted formats and listing requirements. Paseo validates the references without opening local assets or fetching URLs. Unknown top-level fields are ignored. Known fields still validate, and unknown keys inside @@ -2137,7 +2139,7 @@ export default function contribute(server: PluginServerContext) { Inputs and outputs are validated on both sides. RPC names start with a lowercase letter and contain lowercase letters, numbers, dots, hyphens, or underscores. `useRpc()` returns a typed async function. Use TanStack Query for request state, caching, and mutations. -Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the [SDK event contract](../../sdk/events.md) for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory. +Backend handlers receive the same `PaseoApi` as `{ paseo }`. Their connection belongs to the subprocess and closes when the plugin stops. It does not subscribe to timelines or catalog events until plugin code subscribes. Follow the [SDK event contract](/docs/sdk/events) for cleanup and timeline replacements. Backend code can use Node APIs and dependencies installed in the plugin directory. ## Debug backend output @@ -2351,8 +2353,9 @@ keeps the complete dependency tree and `package-lock.json` when activating it. T package and lockfile provide its current version and artifact integrity. A version, tag, or range chooses content for this installation only. -For package contents, dependencies, preparation, and private registries, see -[Publish a plugin](/docs/plugins/publishing). +The installed lockfile records what this installation resolved. Authors submitting npm plugins +with runtime dependencies must also ship the [publication lock](/docs/plugins/publishing#2-lock-installed-dependencies). +For package contents, preparation and submission, see [Publish a plugin](/docs/plugins/publishing). A failed download, dependency installation, manifest check, preparation command, compilation, or activation discards the candidate. Other installed plugins keep running. Removing an npm plugin