snowspeeder/pi-web
Archived
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: bundle workspace tasks plugin

Browse Source
This commit is contained in:
Federico Jaramillo Martinez
2026-06-03 22:31:36 +02:00
parent fda6fb0eca
commit 08f69d09c0
52 changed files with 879 additions and 681 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plugins.html
+106 -2
View File
@@ -4,7 +4,7 @@
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<title>PI WEB plugins</title>
<meta name="description" content="Use and develop trusted local PI WEB UI plugins." />
<meta name="description" content="Use built-in PI WEB plugins and develop trusted local UI plugins." />
<meta property="og:title" content="PI WEB plugins" />
<meta property="og:image" content="assets/pi-web-banner.png" />
<link rel="icon" type="image/svg+xml" href="assets/favicon.svg" />
@@ -52,7 +52,7 @@
<section class="page-hero">
<div class="container">
<p class="eyebrow"><span class="pulse"></span> Plugin development</p>
<h1>Customize PI WEB with local UI plugins.</h1>
<h1>Customize PI WEB with UI plugins.</h1>
<p>
Plugins are trusted browser-side ES modules. They can add actions, workspace panels, and compact workspace
labels to the PI WEB UI.
@@ -67,6 +67,8 @@
<a href="#extend">What can be extended</a>
<a href="#ask-ai">What to ask AI to build</a>
<a href="#example">Canonical example</a>
<a href="#built-in-plugins">Built-in plugins</a>
<a href="#manage-plugins">Manage plugins</a>
<a href="#production">Production usage</a>
<a href="#agent-docs">AI-friendly docs</a>
<a href="#develop">Develop and debug</a>
@@ -165,6 +167,108 @@ After editing, check the manifest endpoint and browser-console failure cases.</c
</p>
</section>
<section id="built-in-plugins">
<h2>Built-in plugins</h2>
<p>
PI WEB ships core, discoverable plugins in the main <code>@jmfederico/pi-web</code> npm package. No
separate <code>pi install</code> step is required: update PI WEB, reload the browser tab, and the bundled
plugins appear in <code>/pi-web-plugins/manifest.json</code>.
</p>
<p>
Built-in plugins can be managed from <strong>Settings → Plugins</strong> or with the top-level
<code>plugins</code> config key.
</p>
<h3>Workspace Tasks</h3>
<p>
<strong>Workspace Tasks</strong> adds a <strong>Tasks</strong> workspace tab for running configured shell
commands in dedicated PI WEB terminals. It is built into PI WEB and enabled by default.
</p>
<ul>
<li>Plugin id: <code>workspace-tasks</code></li>
<li>Config file: <code>.pi-web/tasks.json</code></li>
</ul>
<div class="code-card">
<div class="copy-row">
<strong>Disable Workspace Tasks</strong>
<button class="copy-button" data-copy="#workspace-tasks-disable">Copy</button>
</div>
<pre id="workspace-tasks-disable"><code>{
"plugins": {
"workspace-tasks": { "enabled": false }
}
}</code></pre>
</div>
<div class="code-card">
<div class="copy-row">
<strong>Example .pi-web/tasks.json</strong>
<button class="copy-button" data-copy="#workspace-tasks-config">Copy</button>
</div>
<pre id="workspace-tasks-config"><code>{
"version": 1,
"tasks": [
{
"id": "docker.start",
"title": "Start Docker",
"group": "Docker",
"description": "Start the local Docker Compose environment.",
"command": "./docker/scripts/docker-compose-dev up -d"
},
{
"id": "db.reset",
"title": "Reset DB",
"group": "Database",
"command": "go -C klingit-go run ./cli db reset",
"confirm": true
}
]
}</code></pre>
</div>
<p>
Open a workspace, choose the <strong>Tasks</strong> tab, and click <strong>Run</strong> next to a task.
Commands run in the workspace root because PI WEB creates the terminal for that workspace.
</p>
<p>
Review task configs before running them, especially in shared projects. Workspace Tasks runs trusted
shell commands from your repositories.
</p>
</section>
<section id="manage-plugins">
<h2>Manage plugins</h2>
<p>
Open <strong>Settings → Plugins</strong> to review discovered bundled, local, dev, and Pi package plugins.
PI WEB can disable any discovered plugin before the browser imports it. Core app contributions such as
the command palette, base workspace tools, and themes are not managed through this plugin list.
</p>
<div class="code-card">
<div class="copy-row">
<strong>Plugin config shape</strong>
<button class="copy-button" data-copy="#plugin-config-shape">Copy</button>
</div>
<pre id="plugin-config-shape"><code>{
"plugins": {
"workspace-tasks": {
"enabled": true,
"settings": {}
},
"info": {
"enabled": false
}
}
}</code></pre>
</div>
<p>
Plugins are enabled by default. Set <code>enabled</code> to <code>false</code> to remove a plugin from
<code>/pi-web-plugins/manifest.json</code> so it is not imported or activated on the next page load.
The optional <code>settings</code> object is reserved for plugin-specific settings.
</p>
<p>
After changing plugin enablement, reload the PI WEB browser tab. Already-loaded plugin JavaScript is not
unloaded from the current page.
</p>
</section>
<section id="production">
<h2>Production usage</h2>
<p>
docs/plugins.md
+79 -15
View File
@@ -127,26 +127,90 @@ ln -s /path/to/plugin-folder ~/.pi-web/plugins/plugin-id
Reload the PI WEB browser tab. PI WEB serves plugin modules with an mtime-based `?v=` cache buster. After editing a plugin, hard reload the browser if you do not see changes.
## First-party separate plugin packages
## Manage plugins
First-party plugins that are published as their own npm packages can live in this repository under `plugins/*` as npm workspaces. These packages are **not bundled** into the main `@jmfederico/pi-web` npm package automatically; they are separate packages that share CI, tests, and local development tooling with the main repo.
Open **Settings → Plugins** to review discovered bundled, local, dev, and Pi package plugins. PI WEB can disable any discovered plugin before the browser imports it. Core app contributions such as the built-in command palette, base workspace tools, and themes are not managed through this plugin list.
A separate plugin package should:
Plugin preferences are stored under the top-level `plugins` config key in the PI WEB config file:
- use type-only imports from `@jmfederico/pi-web/plugin-api` when it needs shared PI WEB plugin interfaces; this subpath is currently a `.d.ts`-only dogfooding surface, not a runtime JavaScript module;
- keep its PI WEB metadata in its own `package.json` with `piWeb.plugins` entries pointing at built JavaScript in `dist/`;
- include a package-level `build` script and `prepack` script so `npm pack --workspace <package>` and `npm publish --workspace <package>` produce a usable plugin package;
- use a local symlink into `~/.pi-web/plugins/<plugin-id>` while developing;
- document any private PI WEB APIs it dogfoods until those APIs become stable plugin runtime helpers.
Typical local development loop from this repository:
```bash
npm run dev
curl http://127.0.0.1:8504/pi-web-plugins/manifest.json
```json
{
"plugins": {
"workspace-tasks": {
"enabled": true,
"settings": {}
},
"info": {
"enabled": false
}
}
}
```
The main PI WEB `dev` command watches bundled plugins in `pi-web-plugins/`, builds/watches separate plugin packages in `plugins/*`, and discovers those source-checkout plugin packages without symlinking them into `~/.pi-web/plugins`.
Plugins are enabled by default. Set `enabled` to `false` to remove a plugin from `/pi-web-plugins/manifest.json` so the browser will not import or activate it on the next page load. The optional `settings` object is reserved for plugin-specific settings.
After changing plugin enablement, reload the PI WEB browser tab. Already-loaded plugin JavaScript is not unloaded from the current page.
## Built-in plugins
PI WEB ships core, discoverable plugins in the main `@jmfederico/pi-web` npm package. No separate `pi install` step is required: update PI WEB, reload the browser tab, and the bundled plugins appear in `/pi-web-plugins/manifest.json`.
Built-in plugins can be managed from **Settings → Plugins** or with the top-level `plugins` config key.
### Workspace Tasks
**Plugin id:** `workspace-tasks`
**Config file:** `.pi-web/tasks.json`
**What it does:** adds a **Tasks** workspace tab for running configured shell commands in dedicated PI WEB terminals.
Workspace Tasks is enabled by default. To hide it, disable `workspace-tasks` in **Settings → Plugins** or set:
```json
{
"plugins": {
"workspace-tasks": { "enabled": false }
}
}
```
Configure workspace tasks in `.pi-web/tasks.json`:
```json
{
"version": 1,
"tasks": [
{
"id": "docker.start",
"title": "Start Docker",
"group": "Docker",
"description": "Start the local Docker Compose environment.",
"command": "./docker/scripts/docker-compose-dev up -d"
},
{
"id": "db.reset",
"title": "Reset DB",
"group": "Database",
"command": "go -C klingit-go run ./cli db reset",
"confirm": true
}
]
}
```
Open a workspace, choose the **Tasks** tab, and click **Run** next to a task. Commands run in the workspace root because PI WEB creates the terminal for that workspace.
Task fields:
- `version`: must be `1`.
- `tasks`: array of task definitions.
- `id`: stable task id, matching `^[a-z][a-z0-9.-]*$`.
- `title`: button label.
- `command`: literal shell command sent to the terminal.
- `description`: optional explanatory text.
- `group`: optional group heading.
- `confirm`: optional boolean. When true, the browser asks before dispatching the command.
Review task configs before running them, especially in shared projects. Workspace Tasks runs trusted shell commands from your repositories.
## Discovery and packaging