feat(hub): let buildHub bake statics/frames outside the hub base

[antfubot]

Follow-up to #347 / #349. Closes #353.

What

buildHub baked the whole hub as one subtree under a single base: every mount base had to start with the hub base or resolveOutPath threw DF8006. That blocked deploy shapes where the hub answers under one base (/__devtools/) while its devframe SPAs and vendored assets serve as siblings at their own top-level bases — the layout Vite DevTools needs to retire its hand-rolled build-static.ts.

This adds a deployBase option (option 1 from the issue). outDir maps to deployBase (the deploy root); the hub's own artifacts write under base within it, and every mount base resolves against the deploy root by its path below it. resolveOutPath now only requires a mount base to live within the deploy root, so siblings of the hub base bake without error.

deployBase defaults to base, preserving the existing single-subtree layout exactly — no behavior change for current callers.

Notes

• New diagnostic DF8007 guards a hub base set outside its deployBase (its artifacts would have no home under outDir).
• DF8006's wording now frames the boundary as the deploy root.
• Docs: buildHub options table gains deployBase; new DF8007 error page; DF8006 page updated.

This PR was created with the help of an agent.

[coldtea-pr-lens]

◈ PR Lens

🟢 +0 new · 🟠 ~2 changed · 🔴 -0 removed · 1 flow · 7 files · commit fe5d46d

Architecture

2 components touched across 3 lanes.

Open full size

Data flow

Static hub build with deployBase

Open full size

Drill down

Hub Orchestration — 2 components

🟡 CHANGED Hub Static Builder

Maps outDir to deployBase at serve time and places hub-specific discovery documents and RPC dumps into hubOutDir while resolving devframe sibling mounts against the deploy root.

• packages/hub/src/node/build.ts:35-315
• packages/hub/src/node/__tests__/build.test.ts:166-202
• docs/content/8.references/6.hub-api.md:93-95
• tests/__snapshots__/tsnapi/@devframes/hub/build.snapshot.d.ts:8

🟡 CHANGED Hub Core ＆ Lifecycle

Defines diagnostic error DF8007 for hub base paths outside the deploy root and updates DF8006 for devframe mount bases escaping the deploy root.

• packages/hub/src/node/diagnostics.ts:38-44
• docs/content/6.errors/DF8006.md:1-33
• docs/content/6.errors/DF8007.md:1-32

View

• Architecture lens
• Data flow lens
• Expand every detail
• Show unchanged neighbours

Tip

Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.

🪧 More tips

• Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.
• The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.
• Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.
• GitHub will not let you zoom an image in a comment. The link under each diagram opens it full size on a page of its own, where you can.
• The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
• PR Lens is free for open source. A star on the repository is what keeps it going.
• Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
• The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

---

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Come say hi on Discord

[vercel]

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

Project	Deployment	Actions	Updated
devframe	Ready	Preview	Sep 4, 2026 3:01am UTC