pi-web/plugins/actions/README.md

PI WEB Actions

Configurable workspace actions for PI WEB.

The plugin adds an Actions workspace tab. Actions run the configured shell command in a dedicated PI WEB terminal and switch to that terminal so the user can monitor progress.

Configuration

Create .pi-web/actions.json in the workspace root where you want actions. The file is optional per workspace; workspaces without it simply show no actions.

{
  "version": 1,
  "actions": [
    {
      "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
    }
  ]
}

Fields:

• version: must be 1.
• actions: array of action definitions.
• id: stable action 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.

Commands run in the workspace root because PI WEB creates the terminal for that workspace.

After editing .pi-web/actions.json, click Refresh in the Actions tab or reload the browser tab. The plugin does not watch the file automatically.

Development in this monorepo

This package is developed as a separate npm package, not as a bundled PI WEB plugin. From the PI WEB repository, the single root dev command builds, watches, and auto-loads this package without symlinking it into ~/.pi-web/plugins:

npm run dev

Then reload PI WEB and check discovery:

curl http://127.0.0.1:8504/pi-web-plugins/manifest.json

Build the package before publishing or packing:

npm --workspace @jmfederico/pi-web-actions run build
npm pack --workspace @jmfederico/pi-web-actions --dry-run

Beta/private API note

This first-party plugin dogfoods PI WEB's internal terminal command-run helper for command execution while that API incubates. It also reads .pi-web/actions.json through PI WEB's private workspace file endpoint. These internals are not stable public plugin APIs yet, so compatibility is best-effort and may require updates alongside PI WEB releases.

Notes

This plugin intentionally keeps v1 simple:

• static JSON only;
• no variables or templating;
• every action creates a new terminal;
• command prompting/extra input should be handled by the script itself.