Seven published packages still emit extensionless relative specifiers, so plain Node ESM cannot load them

[os-support-ai]

Split out of the work on #4538, which fixed @object-ui/react plus the dependency closure its entry evaluates through (types, core, i18n). The seven packages below carry the identical defect and were left out of that PR: two of them were held by other sessions at the time, and the rest were outside its declared file surface. They are recorded in the new gate's SPECIFIER_DEBT ledger so they cannot get worse; this card is to clear them.

#4538 remains the source of the analysis and is not addressed further here.

The defect

Node's ESM resolver does not extension-search relative specifiers. A bare tsc never rewrites import specifiers, so an extensionless ./Foo in the source is an extensionless ./Foo in the published dist, and importing the entry under plain Node fails with ERR_MODULE_NOT_FOUND. Bundled consumers are unaffected, which is why everything is green today.

Measured, 2026-08-18, on a full build of every published package

Specifier leg (pnpm check:esm-specifiers) — packages whose build preserves specifiers:

package	extensionless specifiers
@object-ui/app-shell	1259
@object-ui/fields	295
@object-ui/auth	54
@object-ui/mobile	27
@object-ui/collaboration	15
@object-ui/permissions	14
@object-ui/providers	9

Load leg (pnpm check:node-esm-load) — 17 of 39 published ESM entries import and evaluate. The remaining 22 break down as:

• the 7 above, each failing on its own file;
• 11 more that fail on somebody else's file — plugin-calendar, plugin-designer, plugin-grid, plugin-list, plugin-timeline and plugin-view all die on packages/mobile/dist/useBreakpoint; plugin-detail, plugin-form, plugin-gantt and plugin-kanban on packages/permissions/dist/PermissionProvider; plugin-report on packages/providers/dist/DataSourceProvider;
• 2 that fail on a .css import from a third-party dependency (plugin-dashboard, plugin-map) — a different question, ledgered separately as LOAD_DEBT;
• 2 that are not importable by design (create-plugin is a bin-only CLI, runner is a built web app).

So clearing these seven takes the repo from 17 to 35 of 39 loadable entries. @object-ui/mobile at 27 specifiers and @object-ui/permissions at 14 are the cheapest wins by a wide margin.

The fix shape, already proven on four packages

1. Append the explicit extension to every relative specifier in the files the build emits (./x becomes ./x.js; a directory import becomes ./x/index.js). Resolve each one against the filesystem rather than pattern-matching — a specifier inside a comment must be left alone.
2. Optionally pin module/moduleResolution to nodenext in that package's own tsconfig.json, which makes a missing extension a compile error (TS2835/TS2834) instead of a review item. Done for packages/react in finding(react): the built dist emits extensionless relative imports, so plain Node ESM cannot load the published entry #4538.
3. Delete the package's entry from SPECIFIER_DEBT in scripts/check-node-esm-load.mjs in the same commit — the ledger is a ratchet and fails on a stale entry.

⛔ Do not change moduleResolution in the root tsconfig.json. 38 packages extend it; a repo-wide flip is a much larger change and is not what this card is.

@object-ui/app-shell at 1259 specifiers is large enough that it probably deserves its own card rather than riding along with the small ones.

---

Generated by Claude Code

[os-support-ai]

Triage: promoted to pm:queue, type Bug — published ESM entries that cannot load under plain Node violate what a published package declares, and the debt is already ledgered (SPECIFIER_DEBT) with a fix shape proven on four packages in #4538. Executor note: the card itself suggests @object-ui/app-shell (1259 specifiers) may deserve a split — the dispatching seat may take the six small packages first and file app-shell separately rather than one oversized PR; either way delete the ledger entries in the same commit per the ratchet.

Size/model suggestion: M, mode:subagent.

---

Generated by Claude Code

[os-support-ai]

Claim: PM loop round 17
Session: session_01RV6yuVCxymHYE16PL9vQkE
Branch: claude/issue-5214-esm-specifiers-six-packages
Worktree: objectui-issue-5214
Domain: repo:objectui (execution seat)
File surface: the six small packages' src/** — packages/fields, packages/auth, packages/mobile, packages/collaboration, packages/permissions, packages/providers — plus their own tsconfig.json if you take step 2, plus scripts/check-node-esm-load.mjs for the SPECIFIER_DEBT ledger entries only. ⛔ OUT: packages/app-shell (split, see below), packages/components/src/renderers/complex/data-table.tsx (#5120's consumer half is in the maintainer's inbox), packages/plugin-grid/src/ObjectGrid.tsx (#5349), the root tsconfig.json.
Container & model: M, mode:subagent, model: opus — mechanical, but 414 specifiers resolved against the filesystem is where it goes wrong if rushed.
Clause-②: no — this changes emitted module specifiers, not any contract. Nothing about the accepted metadata set moves.
Serial constraints cleared: none of the six packages is open anywhere. PR5355 merged into packages/app-shell/src/views/metadata-admin/** minutes ago (a package you are ⛔ not touching); rebase on current main anyway.

Scope: six packages now, app-shell separately — pre-authorised

The card says @object-ui/app-shell at 1259 specifiers "probably deserves its own card", and the triage seat authorised the split explicitly:

the dispatching seat may take the six small packages first and file app-shell separately rather than one oversized PR; either way delete the ledger entries in the same commit per the ratchet.

So: the six, and I am filing app-shell as its own card. ⛔ Do not touch packages/app-shell here.

The six are where the leverage is, and it is not proportional to their size: the 11 packages that "fail on somebody else's file" all die on mobile/dist/useBreakpoint, permissions/dist/PermissionProvider or providers/dist/DataSourceProvider — all three inside your six. mobile (27) and permissions (14) are the two cheapest entries in the whole table and unblock six and four downstream packages respectively. Measure the before/after loadable count and put it in the PR body — the card predicts 17 → 35 of 39 for all seven; with app-shell deferred your number will differ, and I want yours, not the card's.

The fix shape, already proven on four packages in #4538

1. Append the explicit extension to every relative specifier the build emits — ./x → ./x.js, a directory import → ./x/index.js. ⚠️ Resolve each one against the filesystem rather than pattern-matching: a specifier inside a comment must be left alone, and ./x may be a file or a directory. A regex sweep over 414 specifiers is how this card comes back.
2. Optionally pin module/moduleResolution to nodenext in that package's own tsconfig.json, which turns a missing extension into a compile error (TS2835/TS2834) instead of a review item — done for packages/react in finding(react): the built dist emits extensionless relative imports, so plain Node ESM cannot load the published entry #4538. ⛔ Never the root tsconfig.json: 38 packages extend it and a repo-wide flip is a different, much larger change.
3. Delete each cleared package's entry from SPECIFIER_DEBT in scripts/check-node-esm-load.mjs in the same commit. The ledger is a ratchet and fails on a stale entry, so a cleared package with its entry left behind turns CI red — which is the ledger working.

Why this matters, stated so the verification aims at it

Node's ESM resolver does not extension-search relative specifiers, and a bare tsc never rewrites them — so an extensionless ./Foo in source is an extensionless ./Foo in the published dist, and importing the entry under plain Node fails with ERR_MODULE_NOT_FOUND. Bundled consumers are unaffected, which is exactly why everything is green today. The gate that sees it is pnpm check:node-esm-load, not the test suite.

Tests / verification

• pnpm check:esm-specifiers → zero for each of the six.
• pnpm check:node-esm-load → each of the six imports and evaluates, and report which of the 11 downstream packages became loadable as a result. That second number is the card's real payload.
• The packages' own suites stay green, run from the repo root.
• ⛔ Do not silence a failure by adding a ledger entry. The ledger only shrinks here.

Reverse-verify: revert one package's specifiers (pick permissions — 14, and four downstream packages depend on it), keep everything else, predict what check:node-esm-load reports before running, then run it. State per leg whether a build artifact sits between the edit and the thing under test — for this card one certainly does: the gate reads dist, so say how you rebuilt and how you know the artifact under test is the one you edited.

Gates

Derive from your diff (scripts/pm/dispatch-gates.mjs is objectstack-only). Run vitest from the repo root — the reason is not that package-scoped runs are refused (17 packages own a standalone vitest.config.ts and are not refused) but that a package-scoped run uses a different config than CI does. Changeset per check-changeset-presence.mjs's verdict — six released packages change, so expect one; patch or minor, ⛔ never major.

⛔ Do not background a long check and end your turn. ⛔ No exhaustive paginated API sweeps.

Deliver

Draft PR against main, first body line Part of #5214 — ⛔ not Fixes, because app-shell remains and this card must not close on merge. Push the branch early. Return the JSON report and post it as a comment whose first line is the literal <!-- os-dev-report --> marker.

---

Generated by Claude Code

[os-support-ai]

Split filed: #5357 carries @object-ui/app-shell (1259 specifiers), as promised in the claim comment above and as the triage comment pre-authorised.

#5357 is pm:blocked behind this card. The reason is a hot file, not the package boundary: both PRs delete entries from the same SPECIFIER_DEBT array in scripts/check-node-esm-load.mjs, so they cannot run in parallel. Its file surface is to be re-verified on the merged ref once this lands.

One correction to the arithmetic in the body above, for whoever reads these two cards together. The body says clearing all seven takes the load leg from 17 to 35 of 39. Split across the two cards that is 17 → 34 for the six here (six own-file entries plus the eleven that die on mobile, permissions or providers — all three inside the six), and 34 → 35 for app-shell alone, which unblocks only itself. The six carry essentially all of the leverage; app-shell is the largest package and the smallest incremental unlock. Both cards ask the dev for their own measured before/after rather than these numbers.

---

Generated by Claude Code