Migrate API layer from catch-all handler to Hono + Vercel adapter

[Copilot]

The api/[...path].ts catch-all entrypoint causes routing ambiguity and requires path-normalization workarounds in monorepo Vercel deployments. Replace with Hono's native Vercel adapter pattern.

Entrypoint

• Replace api/[...path].ts with api/index.ts — a top-level Hono app exported via handle(app)
• Vercel rewrites (/api/(.*) → /api) handle sub-path routing; no more filename-based catch-all

// api/index.ts
const app = new Hono();
app.all('*', async (c) => {
  const inner = await ensureApp();
  return await inner.fetch(c.req.raw);
});
export default handle(app);

Kernel bootstrap

• Rename getApp() → ensureApp(), bootKernel() → ensureKernel() (both exported)
• Cold-start shared-promise lock pattern unchanged

Vercel config

• Add /api/(.*) → /api rewrite before the SPA fallback — eliminates path normalization logic that was in the old catch-all

Tests

• Add deployment smoke tests: GET /api/v1/meta and GET /api/v1/packages return 200 through outer→inner delegation
• Update Vercel delegation test suite to match new api/index.ts pattern (46 tests, all passing)

Docs

• Update deployment-vercel.mdx code examples and checklist
• Update both root and studio CHANGELOG.md

Original prompt

---

This section details on the original issue you should resolve

<issue_title>[Refactor] Migrate API layer to Hono + Vercel Edge/Node adapter for long-term monorepo stability</issue_title>
<issue_description>## Background

Current monorepo Vercel deployment (see PR #933 and previous 404 diagnostics) relies on a [...path].ts API catch-all entrypoint and a Node.js serverless handler written in a way compatible with Vercel's conventions. However, due to monorepo structure, workspace dependencies, and Vercel's framework/SPA routing, serverless routing and bundling issues persist.

Motivation for Hono + Vercel Adapter Migration

• Vercel now recommends using @hono/vercel (Edge or Node adapter) for TypeScript frameworks instead of manual catch-all entrypoints.
• A single Hono app entrypoint, compatible with Vercel's adapter bootstrap system, is easier to test locally, more portable, and better aligned with both Edge Functions and monorepo dependency resolution with workspaces.
• Code will be future-proofed for hybrid edge+node routes or incremental migration to Edge (when upstream deps are ready).
• Avoids the routing ambiguity and bundling pitfalls of catch-all handlers with complex monorepo imports.

Acceptance Criteria

• The API entrypoint is restructured into a proper Hono app (not a vestigial Next.js-style [...path].ts).
• Hono is initialized directly at the top-level entry point for API (api/index.ts or similar), not as an exported handler.
• The Hono app is exported and wired up via @hono/vercel Node adapter, e.g.:

  import { Hono } from 'hono';
  import { handle } from '@hono/vercel';
  const app = new Hono();
  // ... route wiring ...
  export default handle(app);

• Internal kernel/plugin/registry initialization is guaranteed before the app handles any request; all service imports are compatible with esbuild/nft bundling.
• Vercel routes are configured to anticipate Hono's routing (i.e. no catch-all raw handler, just native Node/Edge adapter bootstrap).
• Monorepo dependencies imported by the app can be resolved without custom includeFiles hacks in vercel.json.
• Add automated tests to ensure /api/v1/meta and /api/v1/packages return 200 OK after deployment.
• All changes are reflected in CHANGELOG.md (or ROADMAP.md). Related issues updated on each progress.

Additional Notes

• Hono's DX enables hybrid Edge+Node deployment model (future cloud scaling).
• This unlocks easier local/testing/dev experience outside Vercel (e.g. with hono serve).
• All API endpoints (including REST, GraphQL, metadata, and packages) should be exposed via Hono's router.
• Kernel boot, broker wiring, and all async service initialization should be moved to top-level app.ts as needed. Async wiring must be non-blocking or use Hono's native async context patterns.

Related

• [🐛] fix: Vercel 404 on /api/v1/meta and /api/v1/packages — path normalisation, kernel boot resilience, broker-optional metadata #933
• Internal: Vercel monorepo 404 debug / deployment breakdown
  </issue_description>

Comments on the Issue (you are @copilot in this section)

• Fixes [Refactor] Migrate API layer to Hono + Vercel Edge/Node adapter for long-term monorepo stability #934

---

📍 Connect Copilot coding agent with Jira, Azure Boards or Linear to delegate work to Copilot in one click without leaving your project management tool.

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
objectstack-play	Ready	Preview, Comment	Mar 19, 2026 2:48am
spec	Ready	Preview, Comment	Mar 19, 2026 2:48am

[Copilot]

Pull request overview

Migrates Studio’s Vercel serverless API entrypoint away from a file-based catch-all (api/[...path].ts) to the recommended Hono + Vercel adapter pattern (api/index.ts + rewrites), reducing routing ambiguity in monorepo deployments.

Changes:

• Replace the catch-all API function with apps/studio/api/index.ts delegating to the inner ObjectStack Hono app via inner.fetch(c.req.raw).
• Rename and export kernel/app bootstrap helpers (getApp → ensureApp, bootKernel → ensureKernel) and update docs accordingly.
• Add /api/(.*) → /api rewrite and expand adapter/deployment smoke tests for key endpoints.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/adapters/hono/src/hono.test.ts	Updates delegation-pattern tests and adds “deployment smoke tests” for /api/v1/meta + /api/v1/packages.
content/docs/guides/deployment-vercel.mdx	Updates Vercel deployment guide examples to api/index.ts + ensureApp/ensureKernel + new rewrites.
apps/studio/vercel.json	Adds /api/(.*) → /api rewrite before SPA fallback.
apps/studio/api/index.ts	Introduces new Hono Vercel entrypoint delegating all requests to the cached inner app.
apps/studio/api/_kernel.ts	Renames and exports ensureKernel() and ensureApp() for lazy cold-start boot.
apps/studio/api/[...path].ts	Removes old catch-all handler and its path-normalization workaround.
apps/studio/CHANGELOG.md	Documents the Studio-side entrypoint migration and associated changes.
CHANGELOG.md	Documents the repo-level migration and notes the previous fix is superseded.