feat(npm): add platform-specific package builds

[vincentkoc]

Summary

The npm package currently bundles six binaries even when only one platform is needed. Add --platform <os>-<arch> to the existing producer so maintainers can build a tarball containing one supported binary. The default still builds the universal @openclaw/clawscan package.

Selected packages use @openclaw/clawscan-<platform>, with matching npm os and cpu restrictions. They retain the existing command, binary layout, resolver export and TypeScript declaration. The README documents local builds and installation.

Scope

• Release/CI/repo automation: package producer and its tests/docs.
• No security/trust impact. Scanner execution, runtime wrapper and resolver are unchanged.
• No publisher, workflow, version, registry or deployment changes. Publishing the additional package names remains a separate decision requiring registry bootstrap and trusted-publisher setup.

Measured package sizes

Actual npm tarballs built with Node 24.18.1, npm 12.0.2 and Go 1.27.0:

Package	Compressed bytes	Unpacked bytes	Download reduction
universal	20,997,877	49,816,368	—
darwin-x64	3,674,255	8,717,743	82.50%
darwin-arm64	3,392,846	8,025,797	83.84%
linux-x64	3,627,191	8,548,573	82.73%
linux-arm64	3,281,672	7,885,025	84.37%
win32-x64	3,727,470	8,803,901	82.25%
win32-arm64	3,338,166	7,938,113	84.10%

The old and new default producers generated byte-identical universal tarballs (SHA256 f656051a7f997f06c85c707a1ca6f4b13795ee7aa9e1d1287d2150d8e872e2ea). This comparison used the old producer from 0a95ab4 under the same candidate Git commit/date, dirty working-tree VCS metadata and toolchain as the new producer; it is a controlled producer comparison.

Each selected package contains seven files instead of twelve. Its binary and all retained non-manifest files are byte-identical to the corresponding universal payload; only package name, os and cpu change in the manifest.

Verification

• node --test npm/clawscan/test/*.test.mjs scripts/build-npm-package.test.mjs: 21/21 passed locally and on Linux.
• node scripts/build-npm-package.mjs --version v0.0.0 --pack --smoke: passed; all six --platform variants also built and packed with distinct output directories.
• Actual installed universal and Linux x64 tarballs: --version, static JSON scan and the public resolver export passed. Scan findings and behavioral output match after excluding only timestamps/duration.
• npm rejected the macOS x64 tarball on Linux x64 with EBADPLATFORM, without platform overrides.
• ELF/Mach-O/PE target headers, complete archive membership, executable modes and payload hashes verified. Non-Linux targets were cross-built and compared with universal binaries; native execution on those hosts was not claimed.
• git diff --check, Node syntax check and structured source review passed.
• Docs site build: N/A; only the npm package build README changed.

Notes

The producer grows by 28 lines to add target selection and package metadata handling; runtime code is unchanged. Registry publication and releases were not performed.

[clawsweeper]

🦞👀
ClawSweeper picked this up.

Pull request received. I will update this pull request when review starts.

ClawSweeper review complete

ClawSweeper finished reviewing this revision. The review result is being finalized.

View the workflow run.

[clawsweeper]

Codex review: needs maintainer review before merge. Reviewed September 21, 2026, 11:10 AM ET / 15:10 UTC.

ClawSweeper review

What this changes

Adds an optional platform selector to the npm package builder, with matching package names, installation restrictions, tests, and local-build documentation.

Merge readiness

✅ Ready for maintainer review

Keep open: this is a useful, bounded addition absent from current main and v0.1.8. No blocking correctness or security defects were found, and the existing universal release path remains intact.

Priority: P2
Reviewed head: 5f0d46fdd1da1b948c09b1594af704931dfd884c

Review scores

Measure	Result	What it means
Overall readiness	🐚 platinum hermit (4/6)	A focused, compatible implementation with relevant tests and reported artifact validation; no blocking defect was identified.
Proof confidence	🌊 off-meta tidepool	Not applicable: The external-contributor gate does not apply to this MEMBER-authored PR. The captured body nevertheless reports actual builder tarballs, installed Linux CLI scans and resolver checks, platform rejection, and a controlled universal-package comparison; these were not rerun during this review.
Patch quality	🐚 platinum hermit (4/6)	No actionable review findings were identified.

Verification

Check	Result	Evidence
Real behavior	Not applicable	Not applicable: The external-contributor gate does not apply to this MEMBER-authored PR. The captured body nevertheless reports actual builder tarballs, installed Linux CLI scans and resolver checks, platform rejection, and a controlled universal-package comparison; these were not rerun during this review.
Evidence reviewed	7 items	Reviewed introduced change: The pinned base-to-head diff changes only the builder, its tests, npm documentation, and changelog. Target selection uses the existing six-target mapping and defaults to the full matrix. Still necessary on main and latest release: Current main lacks --platform and always compiles every package target. The v0.1.8 producer also iterates the complete matrix. The bounded GitHub PR listing returned no competing npm packaging PR. Runtime and publishing compatibility: The unchanged resolver locates binaries relative to the installed package directory. Both publishing workflows still invoke the universal builder without --platform; the new README explicitly limits selected packages to local artifacts pending separate registry and trusted-publisher setup.
Findings	None	None.
Security	None	None.

How this fits together

ClawScan’s npm package builder compiles the Go CLI and bundles it with a Node launcher and binary resolver. The resulting tarballs support local installation and the existing release workflow.

flowchart TD
  A[Build version and optional platform] --> B[Validate supported target]
  B --> C[Compile selected or all binaries]
  C --> D[Stage launcher and package metadata]
  D --> E[Pack npm tarball]
  E --> F[Optional installed CLI smoke check]

Loading

Before merge

None.

Agent review details

Security

None.

Review metrics

Metric	Value	Why it matters
Production versus test growth	Builder +28 net lines; tests +39 lines	The bounded production growth supports target selection and package metadata without adding runtime implementation.
Reported download reduction	82.25–84.37% across six selected packages	The supplied real-tarball measurements substantiate the package-size benefit.

Technical review

Best possible solution:

Retain the universal release default while supporting smaller local tarballs through the existing builder and resolver.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this adds an optional build capability; source inspection confirms that main and v0.1.8 currently build universal npm packages.

Is this the best way to solve the issue?

Yes: extending the existing producer preserves the runtime, binary layout, and universal publishing path while avoiding a parallel packaging implementation.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning medium; reviewed against 0a95ab4b7b58.

Labels

Label changes:

• add P2: This is a bounded packaging improvement with measurable download savings and no change to existing installation defaults.
• add rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• add status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor gate does not apply to this MEMBER-authored PR. The captured body nevertheless reports actual builder tarballs, installed Linux CLI scans and resolver checks, platform rejection, and a controlled universal-package comparison; these were not rerun during this review.

Label justifications:

• P2: This is a bounded packaging improvement with measurable download savings and no change to existing installation defaults.
• rating: 🐚 platinum hermit: Overall readiness is 🐚 platinum hermit; proof is 🌊 off-meta tidepool and patch quality is 🐚 platinum hermit.
• status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Not applicable: The external-contributor gate does not apply to this MEMBER-authored PR. The captured body nevertheless reports actual builder tarballs, installed Linux CLI scans and resolver checks, platform rejection, and a controlled universal-package comparison; these were not rerun during this review.

Evidence

What I checked:

• Reviewed introduced change: The pinned base-to-head diff changes only the builder, its tests, npm documentation, and changelog. Target selection uses the existing six-target mapping and defaults to the full matrix. (scripts/build-npm-package.mjs:160, 5f0d46fdd1da)
• Still necessary on main and latest release: Current main lacks --platform and always compiles every package target. The v0.1.8 producer also iterates the complete matrix. The bounded GitHub PR listing returned no competing npm packaging PR. (scripts/build-npm-package.mjs:138, 6190d96d7fc4)
• Runtime and publishing compatibility: The unchanged resolver locates binaries relative to the installed package directory. Both publishing workflows still invoke the universal builder without --platform; the new README explicitly limits selected packages to local artifacts pending separate registry and trusted-publisher setup. (npm/README.md:28, 5f0d46fdd1da)
• Captured contributor validation: The supplied complete PR body reports seven actual tarballs, 82.25–84.37% smaller selected downloads, byte-identical universal output under controlled build metadata, successful installed Linux scans and resolver use, and EBADPLATFORM rejection of a macOS package on Linux. Non-Linux native execution is explicitly not claimed. This is contributor-reported evidence, not reviewer-executed validation; captured context sourceRevision is e772dae490981d066f8cdcbcf90746cdc2d1dad539c79fbee8a2681e6eb6bc17. (5f0d46fdd1da)
• Focused regression coverage: Added tests cover all six platform mappings, invalid or missing selectors before staging, and selected-package filenames in both npm output formats. git diff --check passed; builds and tests were not executed under the read-only review contract. (scripts/build-npm-package.test.mjs:87, 5f0d46fdd1da)
• Area history and routing: Main-branch history identifies prior npm packaging work by Patrick Erichsen, Vincent Koc, and Peter Steinberger; GitHub commit metadata verifies their handles. Some historical blobs were unavailable to local blame/follow, so no source-line introduction attribution is claimed. (scripts/build-npm-package.mjs, 0a95ab4b7b58)

Likely related people:

• Patrick-Erichsen: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• steipete: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)
• vincentkoc: Suggested for follow-up; no historical authorship or introduction is verified. (role: unverified routing candidate; confidence: low)

Rating scale

Score	Internal tier	Crab rank	Meaning
6/6	S	🦀 challenger crab	Exceptional readiness
5/6	A	🦞 diamond lobster	Very strong readiness
4/6	B	🐚 platinum hermit	Good normal PR; ordinary maintainer review
3/6	C	🦐 gold shrimp	Useful, but confidence is limited
2/6	D	🦪 silver shellfish	Proof or implementation needs work
1/6	F	🧂 unranked krab	Not merge-ready
N/A	NA	🌊 off-meta tidepool	Rating does not apply

Overall follows the weaker of proof and patch quality.
Shiny media proof means a screenshot, video, or linked artifact directly shows the changed behavior. Runtime, network, CSP, and security claims still need visible diagnostics.

Workflow

• ClawSweeper keeps one durable marker-backed review comment per issue or PR.
• Re-runs edit this comment so the latest verdict, findings, and automation markers stay together instead of adding duplicate bot comments.
• A fresh review can be triggered by eligible @clawsweeper re-review comments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.
• PR/issue authors and users with repository write access can comment @clawsweeper re-review or @clawsweeper re-run on an open PR or issue to request a fresh review only.
• Maintainers can also comment @clawsweeper review to request a fresh review only.
• Fresh-review commands do not start repair, autofix, rebase, CI repair, or automerge.
• Maintainer-only repair and merge flows require explicit commands such as @clawsweeper autofix, @clawsweeper automerge, @clawsweeper fix ci, or @clawsweeper address review.
• Maintainers can comment @clawsweeper explain to ask for more context, or @clawsweeper stop to stop active automation.