[codex] Improve local plugin development workflow (#5821)
## Thinking Path > - Paperclip is the control plane for autonomous AI-agent companies. > - Plugins are the extension point for adding capabilities without expanding the core product surface. > - Local plugin development needed a tighter CLI-first loop so plugin authors can scaffold, run, install, inspect, and reload plugins without reaching into internal package paths. > - The server plugin install path also needed local-path handling that keeps plugin identity, dashboard routes, and development watchers coherent. > - This pull request adds the CLI scaffold/install workflow, fixes the server and SDK edge cases that blocked that loop, and updates the agent-facing plugin creation skill and docs. > - The benefit is that contributors can develop plugins from local folders with a documented, repeatable happy path. ## What Changed - Added `paperclipai plugin init` coverage and CLI wiring for local plugin scaffolding. - Improved local plugin install handling, plugin key route resolution, dashboard capability behavior, and dev watcher startup/reload behavior. - Fixed plugin SDK worker entrypoint validation for symlinked package layouts. - Added targeted tests for plugin init, server plugin authz/watcher behavior, SDK worker host validation, and the authoring smoke example. - Added a short local plugin development guide and refreshed the plugin authoring guide plus `paperclip-create-plugin` skill instructions. ## Verification - `pnpm run preflight:workspace-links && pnpm --filter @paperclipai/plugin-sdk build && pnpm --filter @paperclipai/create-paperclip-plugin typecheck && pnpm --filter paperclipai typecheck && pnpm --filter @paperclipai/plugin-sdk typecheck && pnpm --filter @paperclipai/server typecheck` - `pnpm exec vitest run --project paperclipai cli/src/__tests__/plugin-init.test.ts` - `pnpm exec vitest run --project @paperclipai/plugin-sdk packages/plugins/sdk/tests/worker-rpc-host.test.ts` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/plugin-dev-watcher.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm exec vitest run --project @paperclipai/server server/src/__tests__/plugin-routes-authz.test.ts --pool=forks --poolOptions.forks.isolate=true` - `pnpm --dir packages/plugins/examples/plugin-authoring-smoke-example test` - Confirmed `pnpm-lock.yaml` is not included in the PR diff. ## Risks - Medium risk: this touches plugin install routing, CLI command behavior, and the local development watcher. - Local path plugin installs execute trusted local code by design; the new docs call out that trust boundary. - No database migrations are included. > For core feature work, check [`ROADMAP.md`](ROADMAP.md) first and discuss it in `#dev` before opening the PR. Feature PRs that overlap with planned core work may need to be redirected — check the roadmap first. See `CONTRIBUTING.md`. ## Model Used - OpenAI Codex, GPT-5 coding agent, tool-enabled local shell and git workflow, medium reasoning effort. Context window details were not exposed in this runtime. ## Checklist - [x] I have included a thinking path that traces from project context to this change - [x] I have specified the model used (with version and capability details) - [x] I have checked ROADMAP.md and confirmed this PR does not duplicate planned core work - [x] I have run tests locally and they pass - [x] I have added or updated tests where applicable - [x] If this change affects the UI, I have included before/after screenshots - [x] I have updated relevant documentation to reflect my changes - [x] I have considered and documented any risks above - [x] I will address all Greptile and reviewer comments before requesting merge UI screenshots: not applicable; this PR changes CLI/server/plugin docs and tests, not board UI rendering. --------- Co-authored-by: Paperclip <noreply@paperclip.ing>
This commit is contained in:
Dotta
@@ -1,23 +1,34 @@
|
||||
---
|
||||
name: paperclip-create-plugin
|
||||
description: >
|
||||
Create new Paperclip plugins with the current alpha SDK/runtime. Use when
|
||||
scaffolding a plugin package, adding a new example plugin, or updating plugin
|
||||
authoring docs. Covers the supported worker/UI surface, route conventions,
|
||||
scaffold flow, and verification steps.
|
||||
Create and develop external Paperclip plugins with the CLI-first workflow.
|
||||
Use when scaffolding a new plugin, working on a local plugin against a running
|
||||
Paperclip instance, or updating plugin authoring docs. Covers `paperclipai
|
||||
plugin init`, the local install loop via `paperclipai plugin install <path>`,
|
||||
worker/UI rebuild and reload semantics, and the required success checklist.
|
||||
---
|
||||
|
||||
# Create a Paperclip Plugin
|
||||
# Create and develop a Paperclip plugin
|
||||
|
||||
Use this skill when the task is to create, scaffold, or document a Paperclip plugin.
|
||||
Use this skill when the task is to create, scaffold, or iterate on a Paperclip plugin against a local Paperclip instance.
|
||||
|
||||
## 1. Ground rules
|
||||
## 1. Default: build the plugin OUTSIDE Paperclip core
|
||||
|
||||
Read these first when needed:
|
||||
Plugins are their own packages. Unless the task **explicitly** asks for a bundled in-repo example, do not add plugin source under `packages/plugins/` in this repo.
|
||||
|
||||
- Scaffold the plugin into a directory outside the Paperclip checkout (e.g. `~/dev/paperclip-plugins/<name>`).
|
||||
- Install it into the running Paperclip instance by local absolute path.
|
||||
- Edit code in the external package; let Paperclip pick up rebuilt output.
|
||||
|
||||
Only edit Paperclip core itself when the user asks to surface a plugin as a bundled example (`server/src/routes/plugins.ts`, in-repo example lists, docs).
|
||||
|
||||
## 2. Ground rules
|
||||
|
||||
Reference docs when you need detail:
|
||||
|
||||
1. `doc/plugins/PLUGIN_AUTHORING_GUIDE.md`
|
||||
2. `packages/plugins/sdk/README.md`
|
||||
3. `doc/plugins/PLUGIN_SPEC.md` only for future-looking context
|
||||
3. `doc/plugins/PLUGIN_SPEC.md` — future-looking context only
|
||||
|
||||
Current runtime assumptions:
|
||||
|
||||
@@ -28,38 +39,67 @@ Current runtime assumptions:
|
||||
- no host-provided shared plugin UI component kit yet
|
||||
- `ctx.assets` is not supported in the current runtime
|
||||
|
||||
## 2. Preferred workflow
|
||||
## 3. CLI-first scaffold workflow
|
||||
|
||||
Use the scaffold package instead of hand-writing the boilerplate:
|
||||
Use `paperclipai plugin init`. Do not invoke the scaffold package node entrypoint by hand unless the CLI command is unavailable in the environment.
|
||||
|
||||
```bash
|
||||
pnpm --filter @paperclipai/create-paperclip-plugin build
|
||||
node packages/plugins/create-paperclip-plugin/dist/index.js <npm-package-name> --output <target-dir>
|
||||
paperclipai plugin init @acme/my-plugin --output ~/dev/paperclip-plugins
|
||||
```
|
||||
|
||||
For a plugin that lives outside the Paperclip repo, pass `--sdk-path` and let the scaffold snapshot the local SDK/shared packages into `.paperclip-sdk/`:
|
||||
Useful flags (all optional):
|
||||
|
||||
- `--output <dir>` — parent directory; the command creates `<dir>/<unscoped-name>/`. Defaults to the current directory.
|
||||
- `--template <default|connector|workspace|environment>` — starter template.
|
||||
- `--category <connector|workspace|automation|ui|environment>` — manifest category.
|
||||
- `--display-name <name>`, `--description <text>`, `--author <name>` — manifest metadata.
|
||||
- `--sdk-path <path>` — snapshot the local SDK from a Paperclip checkout into `.paperclip-sdk/` (useful when developing against an unreleased SDK).
|
||||
|
||||
On success the command prints the exact next commands (`cd`, `pnpm install`, `pnpm dev`, `paperclipai plugin install <abs-path>`). Run them in order.
|
||||
|
||||
If `paperclipai` is not on PATH in your environment, fall back to:
|
||||
|
||||
```bash
|
||||
pnpm --filter @paperclipai/create-paperclip-plugin build
|
||||
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/plugin-name \
|
||||
--output /absolute/path/to/plugin-repos \
|
||||
node packages/plugins/create-paperclip-plugin/dist/index.js @acme/my-plugin \
|
||||
--output /absolute/path \
|
||||
--sdk-path /absolute/path/to/paperclip/packages/plugins/sdk
|
||||
```
|
||||
|
||||
Recommended target inside this repo:
|
||||
## 4. Local install + rebuild loop
|
||||
|
||||
- `packages/plugins/examples/` for example plugins
|
||||
- another `packages/plugins/<name>/` folder if it is becoming a real package
|
||||
In the scaffolded plugin folder:
|
||||
|
||||
## 3. After scaffolding
|
||||
```bash
|
||||
pnpm install
|
||||
pnpm dev # esbuild --watch: rebuilds dist/manifest.js, dist/worker.js, dist/ui/
|
||||
paperclipai plugin install /absolute/path/to/my-plugin
|
||||
```
|
||||
|
||||
Check and adjust:
|
||||
Notes:
|
||||
|
||||
- `src/manifest.ts`
|
||||
- `src/worker.ts`
|
||||
- `src/ui/index.tsx`
|
||||
- `tests/plugin.spec.ts`
|
||||
- `package.json`
|
||||
- `paperclipai plugin install` auto-detects local paths (absolute, `./`, `../`, `~`, or an existing relative folder) and forwards `isLocalPath: true` to the server. Pass `--local` to force local mode if the heuristic is ambiguous.
|
||||
- Paths are resolved to absolute paths before being sent to the server.
|
||||
- The server watches built outputs (`dist/`) for local-path plugins and restarts the plugin worker on rebuild — you do not need to reinstall after every edit.
|
||||
- UI hot reload via the SDK dev server (`pnpm dev:ui`, port `4177`) is optional and template-dependent; only mention it if the template wires `devUiUrl` and you verified it works end to end.
|
||||
- `--version` only applies to npm package installs. Combining it with a local path is an error.
|
||||
|
||||
After install, inspect with:
|
||||
|
||||
```bash
|
||||
paperclipai plugin list
|
||||
paperclipai plugin inspect <plugin-key>
|
||||
```
|
||||
|
||||
## 5. After scaffolding, sanity-check the package
|
||||
|
||||
Open and confirm:
|
||||
|
||||
- `src/manifest.ts` — declared capabilities and slots
|
||||
- `src/worker.ts` — worker entry
|
||||
- `src/ui/index.tsx` — UI entry (if applicable)
|
||||
- `tests/plugin.spec.ts` — placeholder test
|
||||
- `package.json` — `paperclipPlugin` block points at `dist/manifest.js`, `dist/worker.js`, `dist/ui/`
|
||||
|
||||
Make sure the plugin:
|
||||
|
||||
@@ -68,34 +108,47 @@ Make sure the plugin:
|
||||
- does not import host UI component stubs
|
||||
- keeps UI self-contained
|
||||
- uses `routePath` only on `page` slots
|
||||
- is installed into Paperclip from an absolute local path during development
|
||||
|
||||
## 4. If the plugin should appear in the app
|
||||
## 6. Verification (run before declaring success)
|
||||
|
||||
For bundled example/discoverable behavior, update the relevant host wiring:
|
||||
|
||||
- bundled example list in `server/src/routes/plugins.ts`
|
||||
- any docs that list in-repo examples
|
||||
|
||||
Only do this if the user wants the plugin surfaced as a bundled example.
|
||||
|
||||
## 5. Verification
|
||||
|
||||
Always run:
|
||||
From the plugin folder:
|
||||
|
||||
```bash
|
||||
pnpm --filter <plugin-package> typecheck
|
||||
pnpm --filter <plugin-package> test
|
||||
pnpm --filter <plugin-package> build
|
||||
pnpm typecheck
|
||||
pnpm test
|
||||
pnpm build
|
||||
```
|
||||
|
||||
If you changed SDK/host/plugin runtime code too, also run broader repo checks as appropriate.
|
||||
If the plugin is already running under `pnpm dev`, you can keep the watcher up and run `pnpm typecheck` and `pnpm test` in a separate shell.
|
||||
|
||||
## 6. Documentation expectations
|
||||
If you changed Paperclip SDK/host/plugin runtime code in addition to the plugin, also run the relevant Paperclip workspace checks.
|
||||
|
||||
## 7. Success checklist (report this back)
|
||||
|
||||
When you finish a local plugin task, report:
|
||||
|
||||
- **Scaffold path** — absolute path of the created plugin folder.
|
||||
- **Commands run** — the exact `paperclipai plugin init`, `pnpm install`, `pnpm dev`, `paperclipai plugin install <path>` invocations (and any verification commands).
|
||||
- **Install status** — output of `paperclipai plugin list` / `plugin inspect` (plugin key, version, status). Note if `status` is anything other than `ready` and include `lastError`.
|
||||
- **Tests / build result** — `pnpm typecheck`, `pnpm test`, `pnpm build` pass/fail with the failing output if any.
|
||||
- **Reload limitations** — call out anything that did not hot-reload (e.g. manifest changes required a reinstall, UI dev server was not wired, etc.).
|
||||
|
||||
If any item is missing, mark it as such — do not silently skip.
|
||||
|
||||
## 8. When NOT to edit Paperclip core
|
||||
|
||||
Do not add the plugin under `packages/plugins/` or update bundled-example wiring unless the user explicitly asks for a bundled example. Local-path installs are the supported development model; npm packages are the production deployment path.
|
||||
|
||||
If the user does ask for a bundled example, also update:
|
||||
|
||||
- `server/src/routes/plugins.ts` example list
|
||||
- any docs that enumerate in-repo example plugins
|
||||
|
||||
## 9. Documentation expectations
|
||||
|
||||
When authoring or updating plugin docs:
|
||||
|
||||
- distinguish current implementation from future spec ideas
|
||||
- be explicit about the trusted-code model
|
||||
- do not promise host UI components or asset APIs
|
||||
- prefer npm-package deployment guidance over repo-local workflows for production
|
||||
- prefer local-path development + npm-package deployment guidance over repo-local workflows
|
||||
|
||||
Reference in New Issue
Block a user