Skip to content

chore: ship compiled dist/ + relax compat to 2026.4.27#6

Merged
rjcloudsigma merged 1 commit into
mainfrom
feat/dist-build-and-relaxed-compat
May 24, 2026
Merged

chore: ship compiled dist/ + relax compat to 2026.4.27#6
rjcloudsigma merged 1 commit into
mainfrom
feat/dist-build-and-relaxed-compat

Conversation

@rjcloudsigma
Copy link
Copy Markdown
Collaborator

Summary

Restructures the plugin for direct deployment under the OpenClaw 2026.5.x plugin loader, which requires compiled JavaScript output for installed plugins. A single build artefact now serves both old and new gateways.

Why

Today's snowcrash upgrade exposed three packaging gaps:

  1. The new gateway refused to load index.ts directly for installed plugins ("source checkouts/dev paths" only). The previously-working v0.2.0 was loading via the older permissive loader; v0.4.0 and v0.5.0 silently failed to load on 2026.4.27 once the registry re-evaluated.
  2. minGatewayVersion: 2026.5.24 was set too aggressively — it gated the plugin against the dev-environment version rather than the actual lowest gateway with the hooks the code uses.
  3. No CI / no dist/ shipped, so manual installs from git left consumers needing to run a build by hand.

Changes

Build & packaging

  • Add tsconfig.build.json (extends the typecheck-only tsconfig.json) emitting to dist/ with declarations.
  • Add build, prepare, and prepublishOnly scripts so npm install from a git URL produces dist/ automatically.
  • Set main: dist/index.js, types: dist/index.d.ts, and declare files so the published tarball ships only what is needed.
  • Add dist/ to .gitignore — CI builds and uploads it as an artefact.

Compatibility

  • Lower openclaw.compat.minGatewayVersion, openclaw.compat.pluginApi, openclaw.build.openclawVersion, openclaw.build.pluginSdkVersion, and peerDependencies.openclaw from 2026.5.24 to 2026.4.27.
  • The provider hooks the plugin uses (wrapStreamFn, hookAliases, resolveTransportTurnState) have been available since 2026.4.27.
  • The requester-bridge code paths (lease, poll, results) already degrade gracefully when the gateway-side TaaS API does not expose those endpoints — so a single build supports the full range from 2026.4.27 through current beta.

CI

  • .github/workflows/ci.yml: typecheck + test + build on PR and push to main; uploads dist/ as a workflow artefact on main.
  • .github/workflows/release.yml: on tag v*, packs the tarball and attaches it to a GitHub Release. The npm publish step is staged but commented out until an NPM_TOKEN repo secret is configured.

Docs

  • Rewrite Installation: cover both the eventual npm-install path and the from-source path (which now relies on npm install to trigger prepare).
  • Add a Compatibility table:
OpenClaw gateway Status Notes
≥ 2026.5.x Supported Loads compiled dist/index.js
2026.4.27 – 2026.4.x Supported Bridge polling endpoints may not exist yet — plugin falls back to advisory-only metadata
< 2026.4.27 Not supported Required hooks not exposed

Verification

  • npm run builddist/index.js + dist/index.d.ts
  • npm test → 9/9 passing, including the bridge long-polling resilience tests added in feat: add requester bridge long polling resilience #5
  • Manually deployed to snowcrash (OpenClaw 2026.5.24-beta.1) earlier today; plugin loads as Status: loaded, capabilities cloudsigma, cloudsigma-staging

Follow-ups (not in this PR)

  • Configure NPM_TOKEN repo secret + uncomment the npm publish step
  • Publish 0.5.1 to npm so consumers can openclaw plugins install openclaw-token-cache-optimizer cleanly
  • Consider renaming the on-disk plugin folder from openclaw-taas-affinity to match the npm package name (deferred — would force a migration for every existing install record)

Restructure the plugin for direct deployment under the OpenClaw 2026.5.x
plugin loader, which requires compiled JavaScript output for installed
plugins. A single build artefact now serves both old and new gateways.

Build & packaging
- Add tsconfig.build.json that emits to dist/ with declarations.
- Add build, prepare, and prepublishOnly scripts so installing from a
  git URL produces dist/ automatically.
- Set main to dist/index.js, types to dist/index.d.ts, and declare
  files so the published tarball ships only what is needed.
- Add dist/ to .gitignore (CI builds and uploads it).

Compatibility
- Lower openclaw.compat.minGatewayVersion, openclaw.compat.pluginApi,
  openclaw.build.openclawVersion, openclaw.build.pluginSdkVersion,
  and peerDependencies.openclaw from 2026.5.24 to 2026.4.27. The
  provider hooks the plugin relies on (wrapStreamFn, hookAliases,
  resolveTransportTurnState) have been available since 2026.4.27.
  The requester-bridge code paths (lease, poll, results) already
  degrade gracefully when the gateway-side TaaS API does not expose
  those endpoints, so a single build supports the full range.

CI
- Add .github/workflows/ci.yml to typecheck, test, and build on PR
  and push, and to upload dist/ as a workflow artefact on main.
- Add .github/workflows/release.yml to pack the tarball on tag and
  attach it to a GitHub Release. The npm publish step is staged but
  commented out until an NPM_TOKEN secret is configured.

Docs
- Rewrite Installation: cover the npm-install path and the from-source
  path (which now requires running install to trigger prepare).
- Add a Compatibility table covering 2026.4.27+ behaviour and what
  degrades on older builds.

Verification
- npm run build produces dist/index.js and dist/index.d.ts.
- npm test passes (9/9 including the bridge long-polling tests).

Bump version to 0.5.1.
@rjcloudsigma rjcloudsigma merged commit 284b854 into main May 24, 2026
1 check passed
@rjcloudsigma rjcloudsigma deleted the feat/dist-build-and-relaxed-compat branch May 24, 2026 16:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant