fix(cli): keep non-self-contained hook handlers out of body-only lowering (#1876)

[os-zhuang]

Addresses the live half of #1876 (build↔runtime validation parity).

Discovery summary

#1876 lists two repros. I verified both before writing any code:

• Repro Add metamodel interfaces for ObjectQL/ObjectUI contract #1 (legacy object/aggregate dashboard widgets pass build, runtime rejects) — already closed on main. The ADR-0021 single-form cutover made DashboardWidgetSchema.dataset/.values required (dashboard.zod.ts:156,160); objectstack build (ObjectStackDefinitionSchema.safeParse) and the runtime metadata plugin parse with the same schema (metadata/plugin.ts:505), and there's already a regression test (dashboard.test.ts:58). I confirmed empirically that a legacy widget is rejected at build. No code needed.
• Repro ✨ Set up Copilot instructions #2 (body-only hooks ReferenceError) — live; fixed here.

A parity sweep also confirmed schema-level parity holds end-to-end (both sides use ObjectStackDefinitionSchema), so the remaining divergence is semantic/callable-level — this PR.

The fix (repro #2)

A hook/action handler referencing a module-scope identifier (helper, import, top-level const) was lowered by objectstack build to a metadata-only body. That body ships without the referenced definition → ReferenceError at runtime. Build green, app won't boot.

extract-hook-body.ts now runs a conservative free-identifier analysis (detect-free-identifiers.ts, TS AST via the already-present ts-morph — no new dependency):

• free vars = identifiers referenced but bound neither by the function (params/locals, over-approximated) nor by the runtime (a generous global allow-list);
• any hit refuses extraction, so lowerCallables falls back to bundling the real function (esbuild carries the closure) — no ReferenceError, no build break.

Why this is safe (the #1903 lesson, applied)

The failure mode of a build-time check is false positives breaking real builds. This analysis is biased so that can't happen:

• over-approximate bindings (a name declared anywhere counts as bound) → only risks false negatives;
• generous globals → only risks false negatives;
• a false positive merely bundles a self-contained handler instead of inlining it — a size cost, never a correctness or build failure (and --strict-body is used nowhere in-repo).

Tests

• 23-case analyzer battery: flagging (helper/const/method-shorthand/implicit-return/multi) + false-positive guards (member access, locals, globals, destructuring, loop/catch bindings, shorthand props, param defaults, named-fn recursion, rest params, …).
• Extractor integration: throws on a module-scope helper, extracts a self-contained handler.
• End-to-end lowerCallables: free-var handler stays registered (bundled) with body undefined + a warning naming the identifier; self-contained handler still body-lowers.
• Full CLI suite 376 pass; tsc clean; example-crm / app-showcase / app-todo all build green (crm's self-contained callable stays body-only — no false positive).

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 15, 2026 9:54am