From 1c46fe72c92d9d2fb5062cd20e3f5fd67ae4f5ba Mon Sep 17 00:00:00 2001 From: Mason Huang Date: Sat, 4 Jul 2026 21:41:46 +0800 Subject: [PATCH] docs: clarify plugin package live proof (#99962) Summary: - The branch adds plugin package live-proof guidance to the testing skill and plugin docs, separating npm-pack package validation from official-trust proof and documenting runtime dependency and compiled-entry checks. - PR surface: Docs +111. Total +111 across 3 files. - Reproducibility: not applicable. this is a documentation and skill-guidance clarification PR rather than a bug report. I validated the documented claims against current source, adjacent docs, tests, and live PR checks. Automerge notes: - No ClawSweeper repair was needed after automerge opt-in. Validation: - ClawSweeper review passed for head b56efcffc546a5c8a29f34692c8040480439fbf9. - Required merge gates passed before the squash merge. Prepared head SHA: b56efcffc546a5c8a29f34692c8040480439fbf9 Review: https://github.com/openclaw/openclaw/pull/99962#issuecomment-4882084565 Co-authored-by: Mason Huang Approved-by: hxy91819 --- .agents/skills/openclaw-testing/SKILL.md | 30 +++++++++++++++++ docs/plugins/building-plugins.md | 39 ++++++++++++++++++++++ docs/plugins/dependency-resolution.md | 42 ++++++++++++++++++++++++ 3 files changed, 111 insertions(+) diff --git a/.agents/skills/openclaw-testing/SKILL.md b/.agents/skills/openclaw-testing/SKILL.md index aac1287098f..cb378df6d6b 100644 --- a/.agents/skills/openclaw-testing/SKILL.md +++ b/.agents/skills/openclaw-testing/SKILL.md @@ -88,6 +88,36 @@ node scripts/run-vitest.mjs That keeps the test scoped without giving pnpm a chance to run dependency status checks or install reconciliation in a linked worktree. +## Plugin Package And Live Proof + +When validating an external or official plugin package, prove the package shape +and trust shape separately. Do not use raw archive/path installs to prove the +managed dependency path, and do not treat `npm-pack:` as proof of catalog-linked +official trust. + +- For local release-candidate proof, pack the plugin and install it with + `openclaw plugins install npm-pack: --force`. This uses the managed + per-plugin npm project and is the closest local substitute for the registry + artifact's dependency behavior. +- If the behavior depends on bundled-plugin or trusted official plugin status, + add a second proof through a catalog-backed official install or a published + package path that records official trust. Local `npm-pack:` proof alone is + not sufficient for privileged helpers or trusted-official scope handling. +- Treat missing runtime imports as package-manifest bugs first. Runtime code + must depend on packages declared in the plugin package `dependencies` or + `optionalDependencies`; do not make a final proof depend on manually running + `npm install` inside `~/.openclaw/npm/projects/...`. +- If the plugin ships `npm-shrinkwrap.json`, regenerate or check it after + moving dependencies between dev and runtime sections. +- Inspect the packed tarball when dependency ownership or generated `dist/` + matters: verify `package/package.json`, the expected runtime files, and any + package-local shrinkwrap before installing it on a live host. +- After installing the package, restart the Gateway when the touched surface is + plugin registration, runtime dependency loading, privileged helpers, provider + routing, or generated dist. +- For live provider or channel probes, add only temporary config needed for the + proof, then remove it and verify the cleanup state before closeout. + ## Command Semantics - `pnpm check` and `pnpm check:changed` do not run Vitest tests. They are for diff --git a/docs/plugins/building-plugins.md b/docs/plugins/building-plugins.md index 7bf8b68fc43..e869e451aa3 100644 --- a/docs/plugins/building-plugins.md +++ b/docs/plugins/building-plugins.md @@ -63,6 +63,12 @@ local proof. "name": "@myorg/openclaw-my-plugin", "version": "1.0.0", "type": "module", + "dependencies": { + "typebox": "1.1.39" + }, + "peerDependencies": { + "openclaw": ">=2026.3.24-beta.2" + }, "openclaw": { "extensions": ["./index.ts"], "compat": { @@ -169,6 +175,39 @@ local proof. + + Before publishing a package-ready plugin, test the same install shape users + will get. First add a build step, point runtime entries such as + `openclaw.extensions` at built JavaScript like `./dist/index.js`, and make + sure `npm pack` includes that `dist/` output. TypeScript source entries are + only for source checkouts and local development paths. + + Then pack the plugin and install the tarball with `npm-pack:`: + + ```bash + npm pack --pack-destination /tmp + openclaw plugins install npm-pack:/tmp/.tgz --force + openclaw plugins inspect my-plugin --runtime --json + ``` + + `npm-pack:` uses OpenClaw's managed per-plugin npm project, so it catches + runtime dependency mistakes that source checkout testing can hide. It proves + the package and dependency shape, not catalog-linked official trust. + Runtime imports must be in `dependencies` or `optionalDependencies`; + dependencies left only in `devDependencies` will not be installed for the + managed runtime project. + + Do not use a raw archive/path install as the final proof for official or + privileged plugin behavior. Raw sources are useful for local debugging, but + they do not prove the same dependency path as npm or ClawHub installs. If + your plugin relies on trusted official plugin status, add a second proof + through a catalog-backed official install or a published package path that + records official trust. See + [Plugin dependency resolution](/plugins/dependency-resolution) for + install-root and dependency ownership details. + + + Validate the package before publishing: diff --git a/docs/plugins/dependency-resolution.md b/docs/plugins/dependency-resolution.md index 2921361dd0e..a5073d449d2 100644 --- a/docs/plugins/dependency-resolution.md +++ b/docs/plugins/dependency-resolution.md @@ -54,6 +54,26 @@ trusting the plugin. This is intended for package-acceptance and release-candidate proof where a local pack artifact should behave like the registry artifact it simulates. +Use `npm-pack:` when testing official or external plugin packages before +publish. A raw archive or path install is useful for local debugging, but it +does not prove the same dependency path as an installed npm or ClawHub package. +`npm-pack:` proves the managed package install shape; it is not, by itself, +proof that the plugin is catalog-linked official content. + +When behavior depends on bundled-plugin or trusted official plugin status, pair +the local package proof with a catalog-backed official install or a published +package path that records official trust. Privileged helper access and +trusted-official scope handling should be validated on that trusted install +path, not inferred from a local tarball install. + +If a plugin fails at runtime with a missing import, fix the package manifest +instead of repairing the managed project by hand. Runtime imports belong in the +plugin package `dependencies` or `optionalDependencies`; `devDependencies` are +not installed for managed runtime projects. A local `npm install` inside +`~/.openclaw/npm/projects/` can unblock a temporary diagnostic, +but it is not package-acceptance proof because the next install or update will +recreate the project from package metadata. + npm may hoist transitive dependencies to the per-plugin project's `node_modules` beside the plugin package. OpenClaw scans the managed project root before trusting the install and removes that project during uninstall, so @@ -76,6 +96,28 @@ policy, and writes `extensions//npm-shrinkwrap.json` for each OpenClaw does not require it for community packages, but npm will respect it when present. +Before treating a local package as release-candidate proof, inspect the tarball +that will be installed: + +```bash +npm pack --pack-destination /tmp +tar -xOf /tmp/.tgz package/package.json +tar -tf /tmp/.tgz | grep '^package/dist/' +``` + +For dependency changes, also verify a production install can resolve the +runtime packages without dev dependencies: + +```bash +tmpdir=$(mktemp -d) +( + cd "$tmpdir" + npm init -y >/dev/null + npm install --package-lock-only --omit=dev --omit=peer --legacy-peer-deps --ignore-scripts /tmp/.tgz +) +rm -rf "$tmpdir" +``` + OpenClaw-owned npm plugin packages can also publish with explicit `bundledDependencies`. The npm publish path overlays the runtime dependency name list, removes dev-only workspace metadata from the published package