OBJECTSTACK_CLIENT_DIST has no dependency-resolution validation, so an out-of-tree client override silently produces a broken bundle

[yinlianghui-tw]

Found while reproducing #5996. Filing so triage can rank it; not fixed there.

What I measured

b0de7a85c (PR #5995, card #5391) gave OBJECTSTACK_SPEC_DIST a fail-fast check: assertDependenciesResolve confirms the override's own manifest dependencies resolve from packageDir, and refuses the build otherwise. That check was written because an override whose deps cannot resolve does not fail at injection time — it fails much later, in ways that do not name the override.

OBJECTSTACK_CLIENT_DIST — its sibling hook in apps/console/vite.config.ts, ~70 lines above — got nothing equivalent. It is still a plain string alias:

const clientDistOverride = process.env.OBJECTSTACK_CLIENT_DIST;
if (clientDistOverride) {
 const resolved = path.resolve(clientDistOverride);
 workspaceAliases['@objectstack/client'] = resolved;
 clientFsAllow.push(path.dirname(resolved), path.resolve(path.dirname(resolved), '..'));
}

No manifest is read, no dependency is checked, and the path is not verified to exist.

Reproduced on apps/console, vite@8.2.1 + rolldown@1.2.3, base 7c96c9420: copy the installed @objectstack/client@17.2.0 dist/ to a directory outside the workspace and point the hook at it. Its three bare imports — @objectstack/core/logger, @objectstack/spec/api, @objectstack/spec/data — have no reachable node_modules from that location, so all three stay unresolved. vite build reports ✓ 8615 modules transformed and carries on; the three specifiers survive as external imports inside assets/framework-*.js, i.e. bare specifiers in a browser bundle that no browser can load.

The failure mode is exactly the one #5391 was filed about, on the other hook: nothing in the output names OBJECTSTACK_CLIENT_DIST, and the build's own summary reads as success up to the point something unrelated trips over the wreckage.

Why it is worth a line

The hook exists so a developer can exercise a locally built client before it ships — i.e. it is pointed at a freshly built, not-yet-installed tree, which is precisely the situation where node_modules is absent or incomplete. The validation #5995 wrote is directly transferable: assertDependenciesResolve and packageResolvesFrom in scripts/vite-objectstack-spec-dist.ts are already parameterised over a package directory.

Note the two hooks are not symmetrical in shape and a fix should not assume they are: the spec hook derives 18 aliases from the override's exports map, while the client hook is one alias and may legitimately point at either a package directory or a dist entry file. Only the dependency check transfers cleanly.

Possible shapes (not a recommendation)

• Extract the dependency-resolution check from scripts/vite-objectstack-spec-dist.ts into something both hooks call, and have the client hook refuse the build the same way the spec hook now does.
• Cheaper first cut: assert the resolved path exists and that the containing package's declared dependencies resolve from it, without touching the spec module.
• Consider whether unresolved bare imports in a browser bundle should fail the console build generally, independent of either hook — that is a wider question and probably its own card.

Related: #5391 / #5995 (the spec-dist half), #5996 (where this was found).

[yinlianghui-tw]

PM claim + dispatch order — R15, with the shape ruled

Claimed by the domain:devx @ objectui execution seat (#5748), round R15, PM session session_019b5UBNMtTzKbVtZZGvFuxe. Branch: claude/issue-6094-client-dist-dep-validation.

Unblocked as of now: PR #6095 merged at 17:20, so apps/console/vite.config.ts is free.

Ruling: the cheaper first cut (option 2), not the extraction

Take: assert the resolved path exists, and that the containing package's declared dependencies resolve from it — without refactoring scripts/vite-objectstack-spec-dist.ts.

Why not option 1 (extract a shared helper): the card itself gives the reason, and it is a good one — "the two hooks are not symmetrical in shape and a fix should not assume they are." The spec hook derives 18 aliases from an exports map; the client hook is one alias that may legitimately point at either a package directory or a dist entry file. Extracting now would either bend the shared helper to accommodate two different shapes, or quietly impose the spec hook's assumptions on the client hook. Land the check where it is needed, and let a second instance justify the abstraction if one ever appears.

⚠️ That "directory or entry file" ambiguity is the substance of this card. assertDependenciesResolve is parameterised over a package directory, so you must first resolve which one you were handed. Handle both, and say in the code how each is detected — a check that silently does nothing when pointed at a dist/index.js would be the same class of defect as the one you are fixing.

⛔ Option 3 is out of scope — whether unresolved bare imports should fail the console build generally is a wider question and its own card. If you think it should exist, file it.

Verification

• Reproduce the defect first, exactly as the card did: copy the installed @objectstack/client@17.2.0 dist/ outside the workspace, point the hook at it, and show vite build reporting ✓ 8615 modules transformed and carrying on — with the three bare specifiers (@objectstack/core/logger, @objectstack/spec/api, @objectstack/spec/data) surviving as external imports inside assets/framework-*.js. That is the "reads as success while producing a bundle no browser can load" state.
• Then show your check refusing that build, naming OBJECTSTACK_CLIENT_DIST and the dependency that does not resolve. ⚠️ The card's whole complaint is that "nothing in the output names OBJECTSTACK_CLIENT_DIST" — so if your error does not name the env var, it has not fixed the reported defect.
• Non-vacuity, both directions: a valid override (point it at the installed package inside the workspace, where its deps do resolve) must still build green. A check that refuses every override would "pass" your reproduction and break the hook's actual purpose — which is to let a developer exercise a locally built client.
• ⚠️ Cover both shapes: a directory override and an entry-file override. Show the check does the right thing for each, since silently skipping one is the failure mode.
• ⚠️ A build artifact sits between your edit and the thing under test — vite compiles the config into a per-invocation .vite-temp file. emit-eager-closure-report crashes with ENOENT when a fully-unresolvable dependency lands in the vendor-objectstack chunk #5996's dev proved freshness via the differing timestamped filenames in the two stack traces; do the same or better, and state it.

⛔ Out of scope: the spec-dist hook and scripts/vite-objectstack-spec-dist.ts (⛔ do not refactor it), the eager-closure report (#5996, landed), and the counter-probe masking (#6093 — dispatched in parallel, ⛔ do not touch it, another dev is on it).

⚠️ Note for your before/after: under the unmodified plugin list, a console build failure is currently masked by the ineffective-dynamic-imports counter-probe (#6093). If your check's refusal does not appear in the log, that is why — say so rather than concluding your check did not fire, and verify by the route #5996's dev used.

⛔ Never git stash — shared stack, other agents are using it now.

⚠️ Lead your report comment with the literal text os-dev-report on the first line, and write any angle-bracket fragment in words — GitHub's sanitizer strips both HTML comments and short angle-bracket fragments, even inside fenced code blocks.

Refs: #5391 / PR #5995 (the landed spec-dist precedent) · #5996 / PR #6095 (where this was found) · #6093 (sibling, parallel).

---

Generated by Claude Code

[yinlianghui-tw]

os-dev-report

{
 "issue": 6094,
 "status": "done",
 "branch": "claude/issue-6094-client-dist-dep-validation",
 "pr": "https://github.com/objectstack-ai/objectui/pull/6114",
 "premise_still_valid": true,
 "summary": "Took the ruled cheaper first cut: OBJECTSTACK_CLIENT_DIST is now resolved and validated in a new sibling module (scripts/vite-objectstack-client-dist.ts) called from apps/console/vite.config.ts, with scripts/vite-objectstack-spec-dist.ts untouched. The path must exist; one upward walk stops at the nearest ancestor manifest whose name IS @objectstack/client, so a package directory, its dist/, and an entry file inside it all resolve to the same package (the directory-or-entry-file ambiguity the card names); that package's declared dependencies must then resolve from where it lives, with peerDependencies deliberately exempt. Failure throws at CONFIG LOAD naming OBJECTSTACK_CLIENT_DIST and the unresolved dependencies. Alias target, fs.allow values and inert-when-unset behaviour are unchanged; the realpath'd package dir used for the dependency walk is new and load-bearing — without it pnpm's symlinked install is REJECTED, i.e. the hook would refuse a valid override. Two refinements to the card's account, both measured: (a) the process does exit non-zero today, but for reasons that never name the override — masked, it dies in ineffective-dynamic-import-ledger's closeBundle listing packages/fields widgets (#6093); unmasked, vite's own 'Rolldown failed to resolve import' surfaces. The written-bundle half of the card is exactly right either way. (b) My refusal needs no un-masking: it lands before any plugin runs, so #6093 cannot hide it. On the card's option 3 I filed nothing — measured, the console build ALREADY fails on unresolved bare imports (vite/plugin-react promotes the resolve warning to an error); the only reason nobody sees it is #6093's closeBundle error arriving first, which is already dispatched. Filing option 3 now would duplicate that card; PM to route if it should exist as its own thing.",
 "tests": "All heavy runs through scripts/pm/os-verify-lock.sh; every exit code captured before any pipe. FINAL UNION on HEAD 3f59d1979 (VERDICT command-exit 0): 'pnpm exec vitest run scripts/__tests__/vite-objectstack-client-dist.test.ts scripts/__tests__/vite-objectstack-spec-dist.test.ts' -> 'Test Files 2 passed (2) / Tests 52 passed (52)'; check-control-bytes -> 'OK (scanned 5059 tracked text file(s))'; check-lint-coverage -> '46/46 packages linted, 0 with outstanding errors'; check-type-check-coverage -> '45/46 ... 0 errors outstanding'. Also green earlier in the same tree: check-changeset-presence ('No source of a released package changed in this range, so no changeset is owed'), tsc -p tsconfig.scripts.json (EXIT=0), eslint on the two new scripts/ files (EXIT=0), eslint apps/console/vite.config.ts (EXIT=0), apps/console 'tsc -b tsconfig.node.json --force' (EXIT=0). REAL BUILDS (apps/console, vite 8.2.1 + rolldown 1.2.3): (1) baseline defect, out-of-tree client copy, unmodified tree -> 'modules transformed: 8615', eager-closure report emitted, dist written, and framework-Lm271O55.js carries 'var d=e(`@objectstack/spec/data`),f=e(`@objectstack/spec/api`),p=e(`@objectstack/core/logger`)' where e is rolldown's require shim; process died in ineffective-dynamic-import-ledger, naming no override. (2) same baseline with ONLY that plugin removed (trapped mutation, on-disk proof 'before=1 after=0') -> died instead with 'Rolldown failed to resolve import \"@objectstack/spec/data\" from .../client-pkg/dist/index.js'. (3) AFTER the fix, real unmodified plugin list, same override -> 'failed to load config ... Error: OBJECTSTACK_CLIENT_DIST: .../client-pkg/package.json declares dependencies that do not resolve from .../client-pkg: @objectstack/core, @objectstack/spec ...'. (4) NON-VACUITY both shapes, valid override at the installed client, plugin removed so green is observable: directory -> BUILD_EXIT=0; entry file .../client/dist/index.mjs -> BUILD_EXIT=0. FRESHNESS: vite compiles the config plus its scripts/ imports into a per-invocation .vite-temp file and deletes it, so each run was polled while it existed — four runs, four distinct timestamped names (...1787592975150..., ...1787593597147..., ...1787593681607..., ...1787593759077...), and three of the four additionally had the compiled bundle grepped and the new module's own text ('points at a client build with no reachable') found INSIDE it; the fourth raced the delete (ENOENT on the marker read) and rests on the distinct name plus the identical tree. ABLATIONS (each restored by 'trap ... EXIT INT TERM', each mutation proven on disk by counting removed and introduced text before any result was read; no dist/ sits between the edit and the test — vitest transforms the module from source): (a) start the walk at 'resolved' even for a file — PREDICTED red, MEASURED GREEN 19/19, a real finding: the walk is indifferent because '.../index.mjs/package.json' simply misses and the next iteration lands on '.../dist'; the branch is explicitness, not the mechanism, and that is now written in both the module and the suite header rather than being quietly deleted. (b) so the leg that DOES target the card's defect class was run instead — skip validation entirely for the entry-file spelling -> 3 red, incl. 'refuses an out-of-tree copy given as an entry file'. (c) drop realpathSync -> 5 red, every one of them 'a VALID override is rejected'. DECLARED NARROWING: 'pnpm --filter @object-ui/console type-check' runs 'tsc --noEmit && tsc -b tsconfig.node.json --force'; the first half is red in this worktree with TS2307 'Cannot find module @object-ui/...' across src/*.tsx — unbuilt workspace deps, which CI resolves via turbo's build-before-type-check. It cannot be this diff: that program's include is [src, dev] and none of the three changed files is in it; the program that DOES contain them (tsconfig.node.json, include globs ../../scripts/vite-*.ts) was run in full and is green.",
 "open_questions": [],
 "out_of_scope_findings": []
}

---

Generated by Claude Code