@hachej/boring-ui-plugin-cli 0.1.41 → 0.1.43
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +79 -0
- package/package.json +1 -1
package/README.md
ADDED
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
# @hachej/boring-ui-plugin-cli
|
|
2
|
+
|
|
3
|
+
Plugin authoring CLI for the boring-ui workspace runtime. The binary is
|
|
4
|
+
`boring-ui-plugin`; it is also bundled into `@hachej/boring-ui-cli` and reached
|
|
5
|
+
as `boring-ui plugin <subcommand>`.
|
|
6
|
+
|
|
7
|
+
It scaffolds, verifies, tests, and manages boring-ui plugins, and exports the
|
|
8
|
+
plugin-source resolution helpers the CLI uses to discover plugins.
|
|
9
|
+
|
|
10
|
+
## Two kinds of plugin
|
|
11
|
+
|
|
12
|
+
| | `create` | `scaffold` |
|
|
13
|
+
|--|----------|------------|
|
|
14
|
+
| Output | npm-package plugin under `plugins/<name>/` (copied from `templates/plugin/`) | workspace runtime plugin under `<workspace>/.pi/extensions/<name>/` |
|
|
15
|
+
| Build | has a build step (`tsup`), `workspace:*` deps | no build step, hot-reloadable via `/reload` |
|
|
16
|
+
| Use for | app/internal publishable plugins | per-workspace plugins authored from inside the running UI |
|
|
17
|
+
|
|
18
|
+
## Commands
|
|
19
|
+
|
|
20
|
+
```
|
|
21
|
+
boring-ui-plugin status [--json]
|
|
22
|
+
boring-ui-plugin create <name> [--path <dir>]
|
|
23
|
+
boring-ui-plugin scaffold <name> [workspace]
|
|
24
|
+
boring-ui-plugin verify [name] [workspace]
|
|
25
|
+
boring-ui-plugin test <name> [--url <url>] [--workspace <id>] [--panel-id <id>] [--timeout-ms <ms>] [--json]
|
|
26
|
+
boring-ui-plugin install [-l|--local|--global] [--workspace <dir>] <source>
|
|
27
|
+
boring-ui-plugin list [--local|--global|--all] [--workspace <dir>] [--json]
|
|
28
|
+
boring-ui-plugin remove [-l|--local|--global] [--workspace <dir>] <id-or-source>
|
|
29
|
+
```
|
|
30
|
+
|
|
31
|
+
- **status** — reports whether workspace-local plugin roots are enabled (driven
|
|
32
|
+
by `BORING_AGENT_WORKSPACE_LOCAL_PLUGIN_ROOTS`) and the resolved
|
|
33
|
+
`.pi/extensions` dir.
|
|
34
|
+
- **verify** — validates plugin manifests on disk *without* a running server
|
|
35
|
+
(manifest validity + `boring.front` / `boring.server` / `pi.extensions` file
|
|
36
|
+
existence). It does not execute plugin code, so syntax errors only surface on
|
|
37
|
+
a real `/reload`. Prints hints for known errors and exits non-zero on failure.
|
|
38
|
+
- **test** — drives a self-test against a running workspace server (default URL
|
|
39
|
+
inferred, override with `--url`) to catch panel render / front-import
|
|
40
|
+
failures that don't appear in the `/reload` banner.
|
|
41
|
+
- **install / list / remove** — manage plugin *sources* in two scopes: `local`
|
|
42
|
+
(`<workspace>/.pi`, default) and `global` (`~/.pi/agent`). Sources can be a
|
|
43
|
+
local path, a git URL, or an npm spec. Dependencies are **not** installed for
|
|
44
|
+
you — run your package manager in the plugin folder, then `/reload` in the UI.
|
|
45
|
+
|
|
46
|
+
Run `boring-ui-plugin` with no command for usage.
|
|
47
|
+
|
|
48
|
+
## Plugin manifest
|
|
49
|
+
|
|
50
|
+
Plugins are declared in `package.json` via two fields (`src/manifest.ts`):
|
|
51
|
+
|
|
52
|
+
- `boring` — workspace/UI discovery: `front` (browser entry default-exporting a
|
|
53
|
+
`BoringFrontFactory`), `server` (backend entry), labels.
|
|
54
|
+
- `pi` — agent/Pi runtime contributions: `extensions`, `skills`, prompt
|
|
55
|
+
fragments, Pi packages, and slash commands.
|
|
56
|
+
|
|
57
|
+
## Programmatic API
|
|
58
|
+
|
|
59
|
+
The package exports its building blocks for embedding hosts (e.g. the CLI):
|
|
60
|
+
`runBoringUiPluginCli`, `createPlugin`, `scaffoldPlugin`, `verifyPlugin`,
|
|
61
|
+
`runPluginSelfTest`, `installPluginSource` / `listPluginSources` /
|
|
62
|
+
`removePluginSource`, and source-scope helpers
|
|
63
|
+
(`resolvePluginSourceScopePaths`, `readPluginSourceRecords`) via the
|
|
64
|
+
`./plugin-sources` subpath. See `src/index.ts` for the full surface.
|
|
65
|
+
|
|
66
|
+
## Templates
|
|
67
|
+
|
|
68
|
+
`templates/plugin/` is the canonical npm-package plugin shape copied by
|
|
69
|
+
`create`; its [README](./templates/plugin/README.md) documents the front /
|
|
70
|
+
server / shared layout and invariants. `templates/*-canonical.*` are the
|
|
71
|
+
single-file canonical sources used by `scaffold`.
|
|
72
|
+
|
|
73
|
+
## Docs
|
|
74
|
+
|
|
75
|
+
- [`docs/README.md`](./docs/README.md) — architecture and internals.
|
|
76
|
+
|
|
77
|
+
## License
|
|
78
|
+
|
|
79
|
+
MIT
|