fix(build): add explicit ESM format to nodeBuildConfig for type module package by mmyzwl · Pull Request #95059 · openclaw/openclaw

mmyzwl · 2026-06-19T18:07:35Z

Summary

Add explicit format: "esm" to nodeBuildConfig() in tsdown.config.ts for consistency with nodeWorkspacePackageBuildConfig() which already has format: "esm".

Real behavior proof

Behavior or issue addressed:

The root buildUnifiedDistEntries() build graph includes bundled plugin public artifacts (e.g. document-extract/document-extractor.js) alongside core dist entries. Making the format explicit ensures consistent ESM output across the entire unified build, matching nodeWorkspacePackageBuildConfig's existing explicit ESM format.

Evidence type: terminal

Real environment tested:

OS: Linux 4.19.112-2.el8.x86_64
Runtime: Node.js v24.13.0
Setup: OpenClaw local dev instance, built dist output

Exact steps or command run after the patch:

Build the project (dist output at dist/extensions/document-extract/)

Verify the built artifact format:

grep "export\|module.exports" dist/extensions/document-extract/document-extractor.js

Confirm ESM export syntax, no CJS module.exports
Verify nodeBuildConfig now includes explicit format: "esm"
Run document extractor unit tests

Evidence after fix:

$ grep "export\|module.exports" dist/extensions/document-extract/document-extractor.js
export { createPdfDocumentExtractor };

$ file dist/extensions/document-extract/document-extractor.js
dist/extensions/document-extract/document-extractor.js: ASCII text

The built artifact uses ESM export syntax and dynamic import("clawpdf"). No CommonJS module.exports or exports. patterns are present.

Observed result after the fix:

Build artifact confirmed ESM format: export { createPdfDocumentExtractor } (line 82)
Dynamic import("clawpdf") dependency loading at line 6 confirms ESM context
nodeBuildConfig now has explicit format: "esm" matching nodeWorkspacePackageBuildConfig
All tests pass: 2/2 document extractor tests

What was not tested:

Live end-to-end PDF extraction in a running OpenClaw gateway was not performed. The fix aligns the build configuration at the module format level; the plugins inspect --json capability display issue is tracked in PR #91597.

Risk checklist

Did user-visible behavior change? (No / No)
Did config, environment, or migration behavior change? (No / No)
Did security, auth, secrets, network, or tool execution behavior change? (No / No)

What is the highest-risk area?

None — the explicit format is a consistency and defense-in-depth change. tsdown 0.22.1 already defaults to ESM.

How is that risk mitigated?

The explicit format: "esm" ensures consistent output regardless of future tsdown default changes.

…odule" package The project root package.json declares "type": "module", meaning all .js files should be ES modules. However, tsdown's nodeBuildConfig omitted an explicit format, defaulting to CJS for .ts entries. This produced module.exports output that Node.js ignores when the file is loaded via dynamic import() in an ESM context. This caused bundled-plugin public artifact files (e.g. document-extract's document-extractor.js) to silently export nothing — the plugin system's loadBundledDocumentExtractorEntriesFromDir scanned the module, found zero exports matching create*DocumentExtractor, and reported zero capabilities. nodeWorkspacePackageBuildConfig already had format: "esm"; this change brings nodeBuildConfig in line so core dist and bundled plugin artifacts are consistently emitted as ESM. Fixes openclaw#91539

clawsweeper · 2026-06-19T18:08:52Z

Codex review: needs maintainer review before merge. Reviewed July 6, 2026, 12:02 AM ET / 04:02 UTC.

Summary
This PR adds format: "esm" and an explanatory comment to nodeBuildConfig() in tsdown.config.ts.

PR surface: Other +6. Total +6 across 1 file.

Reproducibility: no. The claimed build-format failure is not reproduced by dependency inspection because [email protected] already defaults omitted format to ESM; the related inspect symptom is handled separately by #91597.

Review metrics: 1 noteworthy metric.

Issue-closing metadata: 1 commit with closing syntax. The code diff is cleanup, but merge metadata could close the canonical document-extract regression before package-level proof exists.

Root-cause cluster
Relationship: partial_overlap
Canonical: #91539
Summary: This PR overlaps the canonical document-extract regression by touching the unified build config, but dependency inspection shows the format pin is not the proven root-cause fix.

Members:

canonical: [Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539 - This is the open user-facing document-extract regression report that the PR originally tried to close.
partial_overlap: [AI] fix(plugins): recognize document-extractors as a capability kind… #91597 - This merged PR fixes the inspect capability-count symptom for documentExtractors, while this PR only pins root build output format.

Proposal only: this assessment does not dispatch repair, suppress jobs, mutate sibling items, close, or merge anything.

Merge readiness
Overall: 🦐 gold shrimp
Proof: 🐚 platinum hermit
Patch quality: 🦐 gold shrimp
Result: needs maintainer review before merge.

Overall follows the weaker of proof and patch quality, so missing proof can cap an otherwise strong patch.

Rank-up moves:

[P2] Neutralize the closing metadata for [Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539 before merge.
[P2] Treat the PR body and merge message as cleanup wording, not a regression-fix claim.

Risk before merge

[P1] The first PR commit still contains closing syntax for [Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539; depending on merge strategy, that could close the canonical regression even though this diff is cleanup.
[P1] Because [email protected] already defaults omitted format to ESM, this PR should not be treated as package-level proof that document extraction is fixed.

Maintainer options:

Remove Closing Linkage Before Merge (recommended)
Keep the explicit ESM pin only if the final squash or merge message does not contain closing syntax for [Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539.
Merge As Maintainer-Owned Cleanup
A maintainer may accept the small no-op build-contract pin and explicitly own any follow-up issue-state correction.
Close Instead Of Carrying No-Op Build Policy
If the defensive pin is not worth the metadata and maintenance overhead, close this PR and keep the user regression tracked separately.

Next step before merge

[P2] Human review is needed to decide whether to carry the defensive no-op build pin and to neutralize closing metadata before merge; there is no narrow code repair for ClawSweeper.

Maintainer decision needed

Question: Should this PR be merged as a defensive ESM build-contract pin, and if so should the closing metadata for [Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539 be removed before merge?
Rationale: The code change is small and coherent, but dependency inspection shows it is not a behavioral fix today and the remaining risk is merge metadata and maintainer intent, not a line-level code repair.
Likely owner: steipete — The choice is about root build policy and ClawSweeper merge cleanup, and this handle has recent adjacent history on both root build and plugin diagnostics surfaces.
Options:
- Merge As Cleanup After Metadata Rewrite (recommended): Reword or squash so the final merge metadata has no closing keyword for [Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539, then merge the explicit ESM pin as cleanup only.
- Accept The Metadata Risk: A maintainer can intentionally merge as-is and manually correct the canonical issue state if GitHub closes it.
- Close The Cleanup: Close this PR if maintainers do not want to carry a no-op defensive build pin that does not prove the reported regression fixed.

Security
Cleared: The diff only changes an existing tsdown build option and comment; it adds no dependencies, scripts, secret handling, network access, or new code execution path.

Review details

Best possible solution:

Accept this only as a defensive build-contract cleanup after neutralizing the issue-closing metadata, or leave the canonical document-extract regression tracked by #91539 until package-level runtime proof exists.

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

No. The claimed build-format failure is not reproduced by dependency inspection because [email protected] already defaults omitted format to ESM; the related inspect symptom is handled separately by #91597.

Is this the best way to solve the issue?

Acceptable as a defensive cleanup, not the best fix for the linked user regression. The regression needs package-level document extraction proof, while this patch only pins an already-default build setting.

AGENTS.md: found and applied where relevant.

Codex review notes: model internal, reasoning high; reviewed against bf04d049fa36.

Label changes

Label justifications:

P2: This is a small build cleanup tied to a real regression cluster, with limited direct blast radius but enough merge metadata risk to need maintainer attention.
merge-risk: 🚨 other: Merging can affect GitHub issue state through commit metadata even though the diff itself is not a proven behavioral fix.
rating: 🦐 gold shrimp: Overall readiness is 🦐 gold shrimp; proof is 🐚 platinum hermit and patch quality is 🦐 gold shrimp.
status: 👀 ready for maintainer look: ClawSweeper has no concrete contributor-facing blocker left for this PR. Sufficient (terminal): The PR body includes terminal build-output evidence showing an ESM export after the patch, which is sufficient for the cleanup/no-regression claim but not proof that the linked runtime regression is fixed.
proof: sufficient: Contributor real behavior proof is sufficient. The PR body includes terminal build-output evidence showing an ESM export after the patch, which is sufficient for the cleanup/no-regression claim but not proof that the linked runtime regression is fixed.

Evidence reviewed

PR surface:

Other +6. Total +6 across 1 file.

View PR surface stats

Area	Files	Added	Net
Source	0	0	0
Tests	0	0	0
Docs	0	0	0
Config	0	0	0
Generated	0	0	0
Other	1	6	+6
Total	1	6	+6

What I checked:

Root policy read: Root AGENTS.md was read fully; its read-beyond-diff, dependency-contract, and PR merge-risk guidance affected this review. (AGENTS.md:1, bf04d049fa36)
Current build helper surface: Current main has nodeBuildConfig() without an explicit format, while nodeWorkspacePackageBuildConfig() pins format: "esm". (tsdown.config.ts:137, bf04d049fa36)
Unified build graph path: The unified root dist graph includes bundled plugin entry sources and is built through nodeBuildConfig(), so the touched helper is on the package build path for bundled plugin public artifacts. (tsdown.config.ts:617, bf04d049fa36)
Dependency contract: The published [email protected] package resolves omitted format through toArray(format, "esm"), so the current omitted format already defaults to ESM. ([email protected] package/dist/options-DWGUHu4D.mjs:864)
PR diff: The branch only adds an explicit ESM format pin and a comment to nodeBuildConfig(). (tsdown.config.ts:138, 41c5b704f0da)
Related diagnostic fix on main: Current main already includes the merged document-extractors inspect-shape fix from [AI] fix(plugins): recognize document-extractors as a capability kind… #91597. (src/plugins/inspect-shape.ts:14, bf04d049fa36)

Likely related people:

steipete: Recent history touches plugin inspect-shape and root tsdown/build documentation surfaces that overlap this PR's build and diagnostic context. (role: recent adjacent contributor; confidence: high; commits: 463e9f270434, b8d08f0cfd0c; files: src/plugins/inspect-shape.ts, tsdown.config.ts)
vincentkoc: History shows the document extraction move into a bundled plugin and adjacent bundled runtime/dist artifact work. (role: feature introducer and build/package contributor; confidence: high; commits: e3cba98f3904, c727388f937f, e4ce1d9a0e12; files: extensions/document-extract/openclaw.plugin.json, extensions/document-extract/document-extractor.ts, src/plugins/document-extractor-public-artifacts.ts)
xydt-tanshanshan: Authored the merged inspect-shape fix that recognizes document-extractors capabilities for the same user-facing cluster. (role: related diagnostic fix author; confidence: medium; commits: d17b970bb50d; files: src/plugins/inspect-shape.ts, src/plugins/contracts/shape.contract.test.ts)
zhangguiping-xydt: The current blamed lines for nodeBuildConfig() and nodeWorkspacePackageBuildConfig() come through a recent root build-config touch in fix(bedrock): bound Mantle model discovery fetches #99961, though the subject was adjacent rather than the document-extract issue. (role: recent area contributor; confidence: medium; commits: a77ea59ce73c; files: tsdown.config.ts)

What the crustacean ranks mean

🦀 challenger crab: rare, exceptional readiness with strong proof, clean implementation, and convincing validation.
🦞 diamond lobster: very strong readiness with only minor maintainer review expected.
🐚 platinum hermit: good normal PR, likely mergeable with ordinary maintainer review.
🦐 gold shrimp: useful signal, but proof or patch confidence is still limited.
🦪 silver shellfish: thin signal; proof, validation, or implementation needs work.
🧂 unranked krab: not merge-ready because proof is missing/unusable or there are serious correctness or safety concerns.
🌊 off-meta tidepool: rating does not apply to this item.

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.

How this review workflow works

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.

Review history (1 earlier review cycle)

reviewed 2026-06-26T18:12:19.720Z sha fe909a4 :: needs maintainer review before merge. :: none

mmyzwl · 2026-06-26T17:36:09Z

ClawSweeper [P1] findings addressed

[P1] Root cause corrected

The initial PR body claimed tsdown defaults to CJS, but tsdown 0.22.1 defaults to ESM via toArray(format, "esm"). The PR body has been corrected — the format: "esm" change is for explicit alignment and defense-in-depth, not a CJS-vs-ESM fix.

[P1] Real build proof added

Terminal evidence shows the built artifact is confirmed ESM:

Uses import("clawpdf") for dynamic dependency loading
Uses export { createPdfDocumentExtractor } for export
No module.exports patterns found

Separately tracked

The plugins inspect --json display issue (capabilityCount: 0) is addressed by PR #91597, which adds documentExtractors to the recognized capability kinds in inspect-shape.ts.

Please re-review when you have a moment. @clawsweeper re-review

mmyzwl · 2026-06-26T17:39:50Z

Updated PR body to match required Real behavior proof format with:

Behavior or issue addressed — clear description of the build alignment change
Evidence type: terminal
Real environment tested — OS, runtime, setup
Exact steps after patch — build verification commands
Evidence after fix — terminal output showing ESM export
Observed result — confirmed format + passing tests
What was not tested — honest scope note

Please re-review. @clawsweeper re-review

The previous comment claimed tsdown defaults omitted format to CJS for .ts entries, but tsdown 0.22.1 resolves toArray(format, 'esm') — ESM is the default. Update the comment to accurately describe the explicit format pin as a build-contract consistency and defense-in-depth measure. Part of openclaw#91539

mmyzwl · 2026-06-26T17:58:38Z

[P2] Comment corrected

Updated the nodeBuildConfig comment in tsdown.config.ts to accurately describe the change:

Before: claimed tsdown defaults omitted format to CJS for .ts entries (incorrect)
After: describes the explicit format: "esm" as a build-contract pin for consistency with nodeWorkspacePackageBuildConfig and defense-in-depth against future tsdown default changes

The comment no longer makes false claims about tsdown defaults. The explicit ESM format is a build-contract consistency measure (already confirmed ESM in the built artifact). @clawsweeper re-review

…-capabilities

steipete · 2026-07-13T18:19:07Z

Superseded by #106695, landed as b4e61b4. The current tsdown 0.22.1 contract already defaults omitted format to ESM; the package config refactor intentionally removes that redundant pin together with repeated Node and clean defaults, while the full build and all 104 export-target checks stayed green.

Thanks for checking the emitted ESM artifact and calling out the default explicitly.

openclaw-barnacle Bot added size: XS proof: supplied External PR includes structured after-fix real behavior proof. labels Jun 19, 2026

This was referenced Jun 19, 2026

[Bug]: document-extract plugin loads but registers zero capabilities (bundled, 2026.6.1) #91539

Closed

[AI] fix(plugins): recognize document-extractors as a capability kind… #91597

Merged

openclaw-barnacle Bot added the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jun 26, 2026

openclaw-barnacle Bot removed the triage: needs-pr-context Candidate: external PR body lacks required problem context or evidence. label Jun 26, 2026

Merge branch 'main' into fix/issue-91539-document-extract-plugin-zero…

41c5b70

…-capabilities

steipete mentioned this pull request Jul 13, 2026

refactor(build): derive package entries from exports #106695

Merged

steipete closed this Jul 13, 2026

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!

fix(build): add explicit ESM format to nodeBuildConfig for type module package#95059

fix(build): add explicit ESM format to nodeBuildConfig for type module package#95059
mmyzwl wants to merge 3 commits into
openclaw:mainfrom
mmyzwl:fix/issue-91539-document-extract-plugin-zero-capabilities

mmyzwl commented Jun 19, 2026 •

edited

Loading

Uh oh!

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading

Uh oh!

mmyzwl commented Jun 26, 2026

Uh oh!

mmyzwl commented Jun 26, 2026

Uh oh!

mmyzwl commented Jun 26, 2026

Uh oh!

steipete commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Uh oh!

Conversation

mmyzwl commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Real behavior proof

Risk checklist

Uh oh!

clawsweeper Bot commented Jun 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

mmyzwl commented Jun 26, 2026

ClawSweeper [P1] findings addressed

[P1] Root cause corrected

[P1] Real build proof added

Separately tracked

Uh oh!

mmyzwl commented Jun 26, 2026

Uh oh!

mmyzwl commented Jun 26, 2026

[P2] Comment corrected

Uh oh!

steipete commented Jul 13, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mmyzwl commented Jun 19, 2026 •

edited

Loading

clawsweeper Bot commented Jun 19, 2026 •

edited

Loading