refactor: move all site adapters to independent plugins (#216)

* docs: design LinkedIn post-comments command

* feat: add LinkedIn post-comments command

* fix: complete LinkedIn comment collection

* refactor: move LinkedIn commands to community plugin

* feat: add public Webcmd plugin runtime

* fix: preserve plugin runtime error messages

* feat: add independent plugin migration infrastructure

* fix: make plugin migrations collision safe

* refactor: migrate public API adapters to plugins

* refactor: migrate package and Jira adapters to plugins

* fix: make plugin manifest resolution fail closed

* refactor: migrate reference adapters to plugins

* refactor: consolidate PyPI commands in plugin

* refactor: migrate search and desktop adapters to plugins

* refactor: migrate content and market adapters to plugins

* refactor: migrate commerce and utility adapters to plugins

* refactor: migrate chat and professional adapters to plugins

* refactor: migrate document and messaging adapters to plugins

* refactor: complete independent adapter plugin migration

* refactor: make Webcmd core adapter-free

* fix: address plugin migration final review

* test: make CI portability checks deterministic

* test: fix Windows plugin path portability

* fix: match migrated plugin webcmd version floor to the shipping release

migrate-cli-sites.mjs hardcoded webcmd: ">=0.6.0" for every plugin it
generated a fresh manifest for, but package.json ships as 0.5.3 in this
release. Every one of the 108 affected plugins (including linkedin) was
uninstallable: `webcmd plugin install` hard-fails checkCompatibility()
with "Plugin requires webcmd >=0.6.0, but current version is
incompatible" before it ever reaches npm.

Derive the floor from package.json's actual version instead of a
literal, and regenerate the already-committed manifests (all
plugins/*/webcmd-plugin.json + package.json, and the aggregated root
webcmd-plugin.json catalog) to match. Update the two unit tests that
had the old literal baked into their expectations.

* test: install fixture plugins in e2e/smoke suites now that core ships no sites

Several e2e and smoke tests invoked site commands (hackernews, dictionary,
google, imdb, apple-podcasts, yollomi, paperreview) and asserted on `list`
output size/contents, assuming site adapters were bundled in core. After
this migration core registers zero site commands until a plugin is
installed, so these tests failed deterministically in any clean
environment (e.g. `list` returns 0 commands, not >50).

Add installFixturePlugin() to place a repo-local plugin directly under
an isolated HOME's .webcmd/plugins/ (skipping `plugin install`'s npm
step, which only resolves a peerDependency these fixture plugins don't
otherwise need and which fails until the in-progress release is actually
published). Each affected suite now installs the specific plugin(s) it
exercises before running. The smoke test's "all expected sites
registered" check is rewritten against the plugin catalog under
plugins/, since that's the equivalent invariant post-migration.

* docs: fix bundled skills to describe the plugin architecture, not clis/

webcmd-usage, webcmd-adapter-author, and webcmd-autofix (all shipped to
npm under skills/**) still described a repo-root clis/ directory as the
"official bundle" location for built-in adapters. That directory no
longer exists — every main-repo site, official or community, lives
under plugins/<site>/ now. Left the ~/.webcmd/clis/ references alone:
that private local-iteration directory is unaffected by this migration.

* feat: hint at plugin search/install when webcmd list has no sites

Now that core ships zero bundled site adapters, an empty `list` (0
sites) is the expected default state on a fresh install rather than a
sign something's broken. Point the user at `plugin search`/`plugin
install` instead of leaving them looking at a bare zero-count line.

* chore: stop committing the generated plugin-command-manifest.json

It's a build artifact (npm run build-plugin-manifest scans plugins/*
via a Node loader and writes it fresh), read only by CI-time checks
within the same run: check-plugin-command-parity, check-typed-error-lint,
check-silent-column-drop, and convention-audit. Nothing reads it from a
published package or at CLI/hosted runtime, so it doesn't need to be
in the npm tarball or in git history — same treatment as
hosted-contract.json, which was already gitignored for this reason.

* fix: generate plugin-command-manifest.json as part of npm run build

Gitignoring it in 4aec6c5 broke the unit-test CI job: that job runs on
a separate runner with a fresh checkout and only does `npm ci` +
vitest, so the file no longer existed for the three test files that
read it from the package root (hosted/availability, hosted/file-contract,
build-manifest) — 5 tests failed with ENOENT.

hosted-contract.json is safely gitignored only because `npm run build`
always regenerates it. Give the plugin manifest the same guarantee
instead of leaving it as a build artifact nothing in the install path
produces. Costs ~0.9s per build.

* feat: export deriveHostedAvailability for hosted consumers

* fix: handle ports in local IPv4 address detection for deriveHostedAvailability

The isLocalIpDomain function now strips port numbers from domain strings
(e.g. '127.0.0.1:3000') before validating the IPv4 format. This ensures
desktop-app adapters running on local IP addresses with ports are correctly
classified as 'app' rather than 'site'.

Includes regression tests to prevent port-handling regressions.

* feat: support plugin list, uninstall, update, and create in hosted mode

* fix: refuse to update a plugin with uncommitted changes unless forced

updatePlugin/updateAllPlugins now check for tracked-file modifications
in both the standalone plugin directory and the shared monorepo clone
before beginReplaceDir wipes them, with --force to opt out. Local
(symlinked) installs are unaffected since they never go through
beginReplaceDir.

* fix: count untracked files as dirty in the plugin update guard

git status --porcelain already omits gitignored paths (node_modules/dist
never show up), so --untracked-files=no was only hiding the case the
guard exists to catch: a new, unstaged command file. Drop the flag,
label refusal entries as new-unstaged vs modified for clarity.

* ci: reconcile the hosted plugin catalog on merge to main

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* ci: clarify --update-env-vars semantics and workflow_dispatch usage

Add inline comments explaining that --update-env-vars on 'execute' is a
per-execution override (not a job-spec mutation) and that workflow_dispatch
runs should target main to avoid delisting plugins.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix: fail closed on unexpected git errors in the plugin dirty-checkout guard

getDirtyFiles previously treated any git failure (missing binary, "detected
dubious ownership in repository", permission errors) as "clean", letting
beginReplaceDir silently destroy uncommitted work. It also ran `git status
--porcelain` with no pathspec, which reports the whole enclosing repository
rather than just the plugin directory, causing spurious refusals for plugins
inside a larger repo (e.g. a dotfiles-tracked home directory).

Now getDirtyFiles probes with `git rev-parse --git-dir` first: a genuine
non-repository still proceeds, but any other failure refuses the update with
a message pointing at --force. `git status` is scoped with `-- .` so only the
plugin directory is considered.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* fix: ensure parent directories exist before writing plugin output files

* chore: update lockfile dependencies for package-lock.json

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Co-authored-by: beubax <tejasr@bu.edu>

Author: 3 people

.github/workflows/ci.yml

@@ -47,10 +47,22 @@ jobs:
       - name: Build
         run: npm run build
 
+      - name: Build plugin command manifest
+        if: runner.os == 'Linux'
+        run: npm run build-plugin-manifest
+
+      - name: Check plugin command parity
+        if: runner.os == 'Linux'
+        run: npm run check:plugin-parity
+
       - name: Check generated contract artifacts
         if: runner.os == 'Linux'
         run: npm run check:hosted-contract
 
+      - name: Check all generated artifacts are committed
+        if: runner.os == 'Linux'
+        run: git diff --exit-code -- cli-manifest.json hosted-contract.json webcmd-plugin.json README.md
+
       - name: Verify packed CLI executables
         run: npm run check:package-bin
 
@@ -85,10 +97,14 @@ jobs:
       - name: Run unit tests
         run: npx vitest run --project unit --reporter=verbose --shard=${{ matrix.shard }}/2
 
-  adapter-test:
-    name: Adapter tests
+  plugin-test:
+    name: Plugin tests (${{ matrix.os }})
     needs: build
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
     steps:
       - uses: actions/checkout@v6
 
@@ -100,8 +116,11 @@ jobs:
       - name: Install dependencies
         run: npm ci
 
-      - name: Run adapter tests
-        run: npm run test:adapter -- --reporter=verbose
+      - name: Build
+        run: npm run build
+
+      - name: Run plugin tests
+        run: npm run test:plugin -- --reporter=verbose
 
   bun-test:
     name: Bun compatibility

.github/workflows/reconcile-hosted-plugins.yml

@@ -0,0 +1,51 @@
+# Required repository secrets:
+#   GCP_WORKLOAD_IDENTITY_PROVIDER — workload identity provider resource name
+#   GCP_RECONCILE_SERVICE_ACCOUNT  — service account with run.jobs.run on the job
+#   GCP_REGION                     — region hosting webcmd-reconcile-marketplace
+#
+# The Cloud Run Job webcmd-reconcile-marketplace must exist and run
+# `npm run job:reconcile-marketplace` with DATABASE_URL, WEBCMD_ARTIFACT_ROOT,
+# and GITHUB_TOKEN configured.
+
+name: Reconcile hosted plugin catalog
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'plugins/**'
+      - 'webcmd-plugin.json'
+  workflow_dispatch:
+    # Note: manual runs should be triggered against main to ensure github.sha
+    # points to the current tip. Reconciling an older ref would delist plugins
+    # added since that commit.
+
+concurrency:
+  group: reconcile-hosted-plugins
+  cancel-in-progress: false
+
+jobs:
+  reconcile:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+    steps:
+      - name: Authenticate to Google Cloud
+        uses: google-github-actions/auth@v2
+        with:
+          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
+          service_account: ${{ secrets.GCP_RECONCILE_SERVICE_ACCOUNT }}
+
+      - name: Set up gcloud CLI
+        uses: google-github-actions/setup-gcloud@v2
+
+      - name: Execute Cloud Run Job
+        run: |
+          # Note: --update-env-vars on 'execute' (not 'update') is a per-execution
+          # override that does not modify the job's stored configuration. See:
+          # "environment variables overrides for an execution of a job"
+          gcloud run jobs execute webcmd-reconcile-marketplace \
+            --region "${{ secrets.GCP_REGION }}" \
+            --update-env-vars "WEBCMD_PLUGINS_COMMIT=${{ github.sha }}" \
+            --wait

.github/workflows/release.yml

@@ -68,10 +68,26 @@ jobs:
         if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
         run: npm run build
 
+      - name: Build plugin command manifest
+        if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
+        run: npm run build-plugin-manifest
+
+      - name: Check plugin command parity
+        if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
+        run: npm run check:plugin-parity
+
+      - name: Check community plugin metadata
+        if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
+        run: npm run check-community-plugins
+
       - name: Check generated contract artifacts
         if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
         run: npm run check:hosted-contract
 
+      - name: Check all generated artifacts are committed
+        if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
+        run: git diff --exit-code -- cli-manifest.json hosted-contract.json webcmd-plugin.json README.md
+
       - name: Check Codex plugin metadata
         if: ${{ steps.release.outputs.release_created || inputs.publish_tag != '' }}
         run: npm run check:codex-plugin

.gitignore

@@ -3,6 +3,7 @@ dist/
 !extension/dist/
 *.tsbuildinfo
 hosted-contract.json
+plugin-command-manifest.json
 .webcmd/
 .superpowers/
 .worktrees/

README.md

@@ -61,12 +61,21 @@ skills with `webcmd skills add` in Codex.
 
 ### Other agents or plugin-free setup
 
-Webcmd requires Node.js 20+.
+Webcmd requires Node.js 20.6+.
 
 ```bash
 npm install -g @agentrhq/webcmd
 ```
 
+The npm package ships the Webcmd core and browser commands, but no site
+adapters. Search the plugin catalog and explicitly install the adapter you
+need:
+
+```bash
+webcmd plugin search <site> -f json
+webcmd plugin install <installSource-from-search>
+```
+
 ```bash
 webcmd skills add
 ```
@@ -110,7 +119,8 @@ Beyond website adapters, Webcmd can work through authenticated browser sessions,
 | AI tools | ChatGPT, Claude, Gemini, NotebookLM | Retrieve conversations, research outputs, notebooks, and generated materials from the tools you already use. |
 | shopping and bookings | Amazon, Blinkit, Zepto, BigBasket, District, Practo | Compare products, availability, prices, appointments, events, and delivery options. |
 
-This list is illustrative; ask your agent to use webcmd to discover what is currently available.
+This list is illustrative; availability comes from installed plugins. Ask your
+agent to search and install the relevant plugin when a site is not installed.
 
 ## Learn More
 
@@ -130,7 +140,7 @@ Webcmd Cloud can run supported commands and browser sessions on hosted infrastru
 
 | Plugin | Description | Author |
 | --- | --- | --- |
-| [`pypi`](./plugins/pypi/) | Inspect public Python package metadata and releases from PyPI | [Kemal Kaya](https://github.com/yoldaolmak) |
+| [`pypi`](./plugins/pypi/) | Inspect public Python package metadata, downloads, and releases from PyPI | [Kemal Kaya](https://github.com/yoldaolmak) |
 | [`skyscanner`](./plugins/skyscanner/) | Skyscanner flight search commands for Webcmd | [Rishabh](https://github.com/rishabhraj36) |
 <!-- webcmd-community-plugins:end -->
 

TESTING.md

@@ -5,15 +5,21 @@
 ```bash
 npm run typecheck
 npm run build
+npm run build-plugin-manifest
 npm test
 ```
 
+`npm run build` must run before plugin tests because repository plugins import
+the compiled public package exports. The core package contains no site
+adapters; `npm test` runs the unit and generic plugin projects.
+
 ## Focused Checks
 
 ```bash
 npx vitest run --project unit src/skills.test.ts
 npx vitest run --project unit src/package-exports.test.ts
 npx vitest run --project unit src/convention-audit.test.ts src/runtime-copy.test.ts
+npm run test:plugin -- --reporter=verbose
 ```
 
 ## Cloak Runtime Smoke