mirror of
https://github.com/getpaseo/paseo.git
synced 2026-10-30 21:23:04 +00:00
Enable plugin registry installs by default (#6224)
* feat(plugins): enable registry installs by default * fix(plugins): explain explicit Git source for missing registry IDs * fix(plugins): tailor missing registry guidance to installation * test(app): sample footer geometry in one browser frame * fix(plugins): make registry source resolution deterministic Directory existence must not change the meaning of a registry identifier shared by CLI, RPC, and UI installs. Classify explicit host paths in the source parser and explain recovery from registry transport and revision-selection failures. * fix(plugins): recognize dot and Windows directory sources * test(cli): wait for readable daemon ownership before cancellation The cancellation test raced PID-file creation against its first write and parsed empty JSON in CI. Use the public daemon-instance reader to wait for and capture the supervisor PID before asserting cancellation cleanup. * test(app): expect missing directory install guidance
This commit is contained in:
Mohamed Boudra
@@ -21,6 +21,16 @@ A plugin is a TypeScript project installed into one Paseo daemon. It can add
|
||||
[connect a coding agent as a provider](/docs/plugins/providers). Client
|
||||
contributions run on every Paseo client connected to that daemon, including mobile.
|
||||
|
||||
Browse [published plugins](https://paseo.sh/plugins), then install one on your daemon:
|
||||
|
||||
```bash
|
||||
paseo plugin add owner/slug
|
||||
```
|
||||
|
||||
Or paste `owner/slug` into **Settings → Plugins → Plugin source** and select **Install plugin**.
|
||||
Paseo installs the registry's reviewed artifact. Use `git:owner/repository` or a full Git URL
|
||||
when you want to install directly from a Git repository.
|
||||
|
||||
This guide scaffolds a plugin, runs it, and adds a workspace panel to it.
|
||||
|
||||
## Create a plugin
|
||||
@@ -246,13 +256,13 @@ reload use the installed files.
|
||||
See [plugin sources](/docs/plugins/reference#plugin-sources) for identifier syntax. To share your own plugin, follow
|
||||
[Publish a plugin](/docs/plugins/publishing).
|
||||
|
||||
Plugins published in a Git repository install by shorthand or URL:
|
||||
Plugins published in a Git repository install by explicit Git shorthand or URL:
|
||||
|
||||
```bash
|
||||
paseo plugin add owner/repository
|
||||
paseo plugin add git:owner/repository
|
||||
paseo plugin add https://gitlab.com/group/repository.git
|
||||
paseo plugin add owner/monorepo:plugins/workspace
|
||||
paseo plugin add owner/repository --ref main
|
||||
paseo plugin add git:owner/monorepo:plugins/workspace
|
||||
paseo plugin add git:owner/repository --ref main
|
||||
```
|
||||
|
||||
Append `:relative/path` when the plugin lives below the repository root. `--ref` selects the initial
|
||||
|
||||
@@ -11,9 +11,24 @@ category: Plugins
|
||||
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:
|
||||
|
||||
- [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.
|
||||
|
||||
## Plugin registry
|
||||
|
||||
Browse published plugins at [paseo.sh/plugins](https://paseo.sh/plugins).
|
||||
Users install the reviewed artifact 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.
|
||||
|
||||
## Publish on npm
|
||||
|
||||
The scaffold prepares the package files and development dependencies. You choose the package name
|
||||
@@ -182,7 +197,7 @@ to replace the registry stopgap. Do not add import credit to your own `OVERVIEW.
|
||||
Push the plugin project to a repository. Users can install it with:
|
||||
|
||||
```bash
|
||||
paseo plugin install github:acme/paseo-review
|
||||
paseo plugin add git:acme/paseo-review
|
||||
```
|
||||
|
||||
For another Git host:
|
||||
|
||||
@@ -2259,15 +2259,16 @@ failures stay inside the plugin error boundary.
|
||||
Paste one of these source identifiers into **Settings → Plugins**, or pass it to
|
||||
`paseo plugin install`. `paseo plugin add <source>` and `paseo plugin install <source>` are aliases.
|
||||
Absolute host paths are recommended because relative paths resolve against the daemon's working
|
||||
directory. The app does not expand `~`; your shell may expand it before the CLI runs.
|
||||
directory. The daemon expands `~` to its home directory.
|
||||
|
||||
| Source | Accepted form | Example |
|
||||
| -------------------------- | -------------------------------------------------------------------------- | --------------------------------------------- |
|
||||
| Plugin registry | `owner/slug` or `host/owner/slug` | `acme/review` |
|
||||
| Host directory | Absolute or relative path on the daemon host | `/srv/paseo/plugins/review` |
|
||||
| GitHub repository | `github:owner/repository` or `owner/repository` | `github:acme/paseo-review` |
|
||||
| GitHub repository | `git:owner/repository` or `github:owner/repository` | `github:acme/paseo-review` |
|
||||
| Git repository | `git:<URL or SCP source>`; the prefix is optional for URLs and SCP sources | `git:https://git.example.com/acme/review.git` |
|
||||
| npm package | `npm:<name>[@<version, tag, or range>]`; `npm:` is optional | `npm:@acme/paseo-review@^1.2.0` |
|
||||
| Plugin below a source root | Append `:relative/plugin/path` to any source | `github:acme/monorepo:plugins/review` |
|
||||
| Plugin below a source root | Append `:relative/plugin/path` to a directory, Git, or npm source | `github:acme/monorepo:plugins/review` |
|
||||
|
||||
Git URLs use `https://`, `http://`, `ssh://`, `git://`, or `file://`. SCP sources use
|
||||
`user@host:path`. `file://` selects Git acquisition, not directory installation.
|
||||
@@ -2283,24 +2284,27 @@ The package registry validates the selected version, tag, or range.
|
||||
|
||||
Paseo resolves an identifier in this order:
|
||||
|
||||
1. An existing directory matching the complete identifier on the daemon host wins, including a
|
||||
literal directory containing `:`.
|
||||
1. A bare `owner/slug` is a registry id; local directory sources are `.` or `..`, or start with `./`, `../`, `.\`, `..\`, `/`, `~`, a Windows drive (`C:\` or `C:/`), or a UNC (`\\server\share`) prefix.
|
||||
2. Otherwise, recognize `npm:`, `github:`, or `git:` before interpreting a subdirectory suffix.
|
||||
`git://` is a Git URL scheme. An explicit prefix selects acquisition of that kind.
|
||||
3. Recognize a final `:relative/plugin/path` only when its suffix contains no empty, `.` or `..`
|
||||
segments. A lone `.` selects the source root. Both `/` and `\` separate suffix segments; use `/`
|
||||
across hosts. URL ports and the separator in an SCP source stay part of the source. A suffix
|
||||
that does not satisfy these rules stays part of the identifier.
|
||||
4. Without an explicit prefix, an existing directory matching the remaining source wins.
|
||||
5. Resolve Git URLs and SCP sources as Git; expand exact `owner/repository` shorthand to GitHub
|
||||
HTTPS. `github:` requires that shorthand; `git:` accepts it as well as URLs and SCP sources.
|
||||
6. Resolve a remaining npm package name with its optional selector through the host's registry.
|
||||
4. Resolve bare `owner/slug` through the default plugin registry and `host/owner/slug` through
|
||||
that registry host. Resolve Git URLs and SCP sources as Git. `github:` requires
|
||||
`owner/repository` shorthand; `git:` accepts it as well as URLs and SCP sources.
|
||||
5. Resolve a remaining npm package name with its optional selector through the host's registry.
|
||||
Reject anything else.
|
||||
|
||||
Plugin registry installs are off by default. When the daemon enables them with
|
||||
`pluginRegistryEnabled: true` or `PASEO_PLUGIN_REGISTRY_ENABLED=1`, bare `owner/slug` and
|
||||
`host/owner/slug` resolve through the plugin registry instead of GitHub, the registry record owns
|
||||
the revision and plugin path, and GitHub shorthand requires `github:`.
|
||||
The default registry is `https://plugins.paseo.sh`. Browse [published plugins](https://paseo.sh/plugins)
|
||||
and install with `paseo plugin add owner/slug`. Registry records own the revision and plugin path.
|
||||
Use `git:owner/repository` for explicit GitHub shorthand or a full Git URL.
|
||||
Set `PASEO_PLUGIN_REGISTRY` to use a self-hosted default URL, including a path prefix.
|
||||
Private registry credentials use `pluginRegistries: { "host": { "authorization": "Bearer token" } }`
|
||||
in daemon config. Restart the daemon after changing these startup settings. Credentials go only
|
||||
to that registry, never to artifact hosts or redirects. Installed plugins retain their recorded
|
||||
source and registry URL when defaults change.
|
||||
|
||||
Directory lookup happens on the daemon host. The app uses the `paseo-plugin.json` ID; the CLI
|
||||
accepts `--id <runtime-id>` to override it. An existing installation ID is rejected without changing
|
||||
@@ -2347,9 +2351,10 @@ deletes its managed files; removing a directory plugin keeps your source directo
|
||||
paseo plugin init /absolute/path/to/plugin
|
||||
paseo plugin install /absolute/path/to/plugin
|
||||
paseo plugin install /absolute/path/to/plugin --id another-runtime-id
|
||||
paseo plugin add owner/repository
|
||||
paseo plugin add owner/slug
|
||||
paseo plugin add git:owner/repository
|
||||
paseo plugin add https://git.example.com/owner/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 <id>
|
||||
paseo plugin update --all --check
|
||||
|
||||
Reference in New Issue
Block a user