@agentrhq/webcmd 0.2.4 → 0.2.5

package/README.md

@@ -258,7 +258,7 @@ webcmd plugin uninstall <name>
 webcmd plugin create <name>
 ```
 
-Use plugins for private company workflows, community adapters, or experiments that are not ready for the built-in registry.
+Use plugins for private company workflows, community adapters, or experiments that are not ready for the built-in registry. This repo is also a plugin monorepo: community CLIs promoted here live under [`plugins/`](./plugins/) and are advertised through [`webcmd-plugin.json`](./webcmd-plugin.json).
 
 ## Writing Adapters
 
@@ -278,7 +278,7 @@ import { cli, Strategy } from '@agentrhq/webcmd/registry';
 import { CommandExecutionError } from '@agentrhq/webcmd/errors';
 ```
 
-Private adapters can live in `~/.webcmd/clis/<site>/<command>.js`; upstream adapters live in [`clis/`](./clis/). For the full authoring workflow, install and use [`webcmd-adapter-author`](./skills/webcmd-adapter-author/SKILL.md).
+Private adapters can live in `~/.webcmd/clis/<site>/<command>.js`; bundled upstream adapters live in [`clis/`](./clis/), while community upstream adapters live as plugins under [`plugins/`](./plugins/). For the full authoring workflow, install and use [`webcmd-adapter-author`](./skills/webcmd-adapter-author/SKILL.md).
 
 ## Configuration
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentrhq/webcmd",
-  "version": "0.2.4",
+  "version": "0.2.5",
   "description": "Turn websites, browser sessions, desktop apps, and local tools into deterministic CLI surfaces for humans and AI agents.",
   "engines": {
     "node": ">=20.0.0"

package/skills/webcmd-adapter-author/SKILL.md

@@ -28,7 +28,7 @@ Continue only when all three answers are yes.
 
 ## Top-Level Decision Tree
 
-**Choose the strategy before writing the adapter.** Every time you reach Step 3 or Step 4, and before writing code, produce a strategy note. Without that note, do not start `clis/<site>/<name>.js`.
+**Choose the strategy before writing the adapter.** Every time you reach Step 3 or Step 4, and before writing code, produce a strategy note. Without that note, do not start an adapter file.
 
 The core question is not whether an API is more elegant than DOM work. The core question is whether the data source has an external contract. Public or official interfaces are usually the most stable. UI/DOM semantics often have a user-visible contract too. Undocumented in-site XHR, GraphQL, or signature endpoints drift the most. Do not move a stable UI/DOM implementation to an uncontracted internal endpoint just to be "API-first."
 
@@ -253,7 +253,7 @@ Check these off step by step:
 - **The `browser:` field determines the `func` signature:** `browser:false -> (args)`, `browser:true -> (page, args)`. If this is reversed, `args` may actually be a debug flag and all external parameters can silently fall back to defaults.
 - Throw the correct typed error for known failures according to [`references/typed-errors.md`](./references/typed-errors.md). **Do not** silently `return []`, **do not** silently `return [{sentinel}]`, and **do not** silently clamp external parameters with `Math.max/min`.
 - **Persistent sessions keep stale DOM between commands.** `siteSession: 'persistent'` shares one tab per site; leftover modals/drawers from the previous command leak into the next one. State-sensitive write commands (checkout flows) should add `freshPage: true` (new tab, same lease — cookies/login/location survive). Verify session-scoped context (login, selected city/date) *before* side effects, and embed such context in URLs/IDs your command emits for sibling commands. See `references/adapter-template.md` and "Persistent Sessions and State Hygiene" in `docs/authoring.mdx`.
-- For private adapters, write `~/.webcmd/clis/<site>/<name>.js` to avoid a build. Copy to `clis/<site>/<name>.js` only when preparing a PR.
+- For private iteration, write `~/.webcmd/clis/<site>/<name>.js` to avoid a build. When the user says to promote a CLI, create a main-repo plugin with `webcmd plugin create <site> --dir plugins/<site>`, copy the real command files into it, delete scaffold sample commands, register it in root `webcmd-plugin.json`, remove the local `~/.webcmd/clis/<site>` shadow, install the plugin, then run `webcmd validate <site>` and smoke commands. See `references/adapter-template.md` for details.
 - Write site memory every round: no memory -> use skill -> produce memory -> next time becomes a five-minute task.
 - **After a site's first command passes verify, stop and ask the user for their use cases before recommending next set of commands.** See Runbook Step 13.
 - **Raw dumps, packet captures, and HTML samples from debugging may only be written to `~/.webcmd/sites/<site>/fixtures/` or `/tmp/`. Never leave `.dbg-*.html`, `raw-*.json`, `sample.*`, or similar temporary files in the repo root, `clis/<site>/`, or the current working directory.**

package/skills/webcmd-adapter-author/references/adapter-template.md

@@ -16,10 +16,32 @@ Write the working file at:
 ~/.webcmd/clis/<site>/<name>.js
 ```
 
-Copy it to the repo only when preparing a PR:
+Promote a community CLI to the main repo as a plugin:
 
-```text
-clis/<site>/<name>.js
+```bash
+webcmd plugin create <site> --dir plugins/<site> --description "<site> commands for Webcmd"
+cp ~/.webcmd/clis/<site>/*.js plugins/<site>/
+rm plugins/<site>/hello.ts plugins/<site>/greet.ts 2>/dev/null || true
+```
+
+Then add `<site>` to the root `webcmd-plugin.json` `plugins` map:
+
+```json
+"<site>": {
+  "path": "plugins/<site>",
+  "version": "0.1.0",
+  "description": "<site> commands for Webcmd",
+  "webcmd": ">=0.2.0"
+}
+```
+
+Before handing off, remove the private shadow and prove the plugin path works:
+
+```bash
+rm -rf ~/.webcmd/clis/<site>
+webcmd plugin install file://$PWD/plugins/<site>
+webcmd validate <site>
+webcmd <site> <command> --help
 ```
 
 ## Minimal Registry Shape

package/skills/webcmd-autofix/SKILL.md

@@ -18,7 +18,7 @@ Hard stops before any code change:
 
 Scope constraint:
 
-- Modify only the file at `adapterSourcePath` in the trace `summary.md` front matter. That path is authoritative and may be `clis/<site>/...` in the repo or `~/.webcmd/clis/<site>/...` for user-local installs.
+- Modify only the file at `adapterSourcePath` in the trace `summary.md` front matter. That path is authoritative and may be `clis/<site>/...` in the repo or `plugins/<site>/...` in a plugin repo or `~/.webcmd/clis/<site>/...` for user-local installs.
 - Never modify `src/`, `extension/`, `tests/`, `package.json`, or `tsconfig.json` during autofix.
 
 Retry budget: maximum **3 repair rounds** per failure. A round is diagnose -> patch -> retry. If 3 rounds do not resolve it, stop and report what was tried.

package/skills/webcmd-usage/SKILL.md

@@ -10,7 +10,7 @@ Webcmd turns websites, Electron desktop apps, and external CLIs into a uniform `
 
 ## The Three Pillars
 
-- **Adapter commands:** `webcmd <site> <command> [...]`. Built-in adapters live in `clis/`; user adapters live in `~/.webcmd/clis/`. Each command has a strategy such as `PUBLIC`, `COOKIE`, `INTERCEPT`, `UI`, or `LOCAL`.
+- **Adapter commands:** `webcmd <site> <command> [...]`. Built-in adapters live in `clis/`; community adapters promoted to the main repo live as plugins under `plugins/`; private iteration adapters live in `~/.webcmd/clis/`. Each command has a strategy such as `PUBLIC`, `COOKIE`, `INTERCEPT`, `UI`, or `LOCAL`.
 - **Browser driving:** `webcmd browser *` subcommands (`open`, `state`, `click`, `type`, `select`, `find`, `extract`, `network`) for ad-hoc interaction when no adapter covers the task. See `webcmd-browser`.
 - **External CLI passthrough:** `webcmd gh`, `webcmd docker`, `webcmd vercel`, and similar wrappers. Manage them with `webcmd external install <name>` or `webcmd external register <name>`.
 
@@ -102,10 +102,13 @@ The error envelope includes a `trace` block pointing at `summary.md`. Patch only
 
 ## Writing An Adapter
 
-Two storage paths:
+Storage paths:
 
 - Private: `~/.webcmd/clis/<site>/<command>.js`
-- Public / PR: `clis/<site>/<command>.js`
+- Public (official bundle): `clis/<site>/<command>.js`
+- Public (community PRs): `plugins/<site>/` plus root `webcmd-plugin.json` registration
+
+The main Webcmd repo is itself a plugin monorepo: promoted community CLIs belong under `plugins/<site>/` and must be registered in the root `webcmd-plugin.json`.
 
 Scaffolding and checks:
 
@@ -126,9 +129,12 @@ webcmd plugin list [-f json]
 webcmd plugin update [name] | --all
 webcmd plugin uninstall <name>
 webcmd plugin create <name>
+webcmd plugin search [query]
 ```
 
-Plugins are third-party extensions pulled from git and separate from the main adapter registry.
+Plugins are installable extensions pulled from git or local paths. Main-repo community CLIs are exposed through the root plugin catalog manifest, not bundled into npm's `clis/` set.
+
+> **Note:** The repository's `plugins/` directory is not shipped in the npm package. Find the required plugin with `webcmd plugin search`, then install its `installSource` with `webcmd plugin install <installSource>`.
 
 ## External CLI Passthrough