feat(dev): support external app previews with a shared Bun runtime

[francoischalifour]

Context

Package contributors need to preview data apps outside this repository against the current checkout. This includes both a single-file app intended for hosted execution and a local app directory with its own Bun server.

The existing gallery is useful for package development, but it does not provide that workflow. External previews need to resolve the checkout’s package and React dependencies, preserve the app’s configuration, connect to the selected lakehouse, and recover reliably as files change.

The CLI needs the same single-file preview behavior. Putting the runtime in the package gives checkout tooling and the CLI one implementation for bundling, iframe hosting, SQL delivery, navigation, exports, and reloads. Launchers retain responsibility for installation, profiles, and credentials.

Closes #74 by exposing a real API instead of re-implementing in the Altertable CLI too.

External preview commands

Add two contributor commands:

bun run dev:file /absolute/path/index.tsx
bun run dev:dir /absolute/path/app-directory

Both resolve @altertable/data-app and React from the checkout build, allowing external apps to run without installing the package themselves. They build the package if dist is absent; subsequent package source changes require bun run build.

dev:file launches the shared preview runtime. It bundles the app for browser execution and renders it through the existing sandboxed iframe bridge.

dev:dir runs the app’s own src/server.ts with Bun’s watch mode. A temporary, typed TypeScript configuration combines the app’s inherited aliases with checkout package paths. Checkout mappings take precedence, while the app’s original configuration and bunfig.toml remain in use.

Lakehouse setup returns a normalized environment and a description of the selected connection without mutating process.env. A CLI proxy takes precedence over direct credentials.

Shared Bun preview API

Expose the runtime through a dedicated entry:

import { serveAppFile } from '@altertable/data-app/server/bun/preview';

const preview = await serveAppFile({
  file: '/absolute/path/index.tsx',
  lakehouse,
  port: 0,
});

console.log(preview.url);
await preview.stop();

file identifies the app source. The port defaults to 25837; 0 selects an available port.

The ownership boundary is explicit:

Caller owns	Preview runtime owns
Dependency installation and version selection	Browser bundling and embedded host assets
Profile and app-scope validation	Sandboxed iframe hosting
Credentials and lakehouse construction	SQL delivery to the supplied lakehouse
Process signals and launcher lifecycle	File watching, reload connections, and resource cleanup

The host supports URL-backed navigation and CSV/ZIP downloads through existing bridge contracts. App edits replace the iframe while preserving host URL filters. Bundles include inline source maps and injected app styles.

Reliable reloads and recovery

Watch imported app files through their directories so editor saves that rename files still trigger rebuilds. Exclude package build files and node_modules from app watching.

Capture dependencies before parsing and observe candidate import directories before resolution. This lets an initially broken preview recover when an imported file is fixed or a missing target is created, including relative imports and TypeScript aliases outside the entry directory.

Failed builds retain earlier watcher directories because parsing may stop before rediscovering the full dependency graph. Successful builds prune obsolete watches. Rebuilds are debounced and serialized.

The host refreshes the bundle on every SSE ready event, catching edits missed while disconnected. A changed server session triggers a full-page reload. Concurrent bundle fetches only apply the latest response, and build or fetch failures appear in the host.

Focused shared helpers

Share three private helpers where there are existing consumers:

• A bounded request-body reader for portable operation requests and preview SQL. It counts encoded bytes while streaming and responds without waiting for an oversized upload to finish.
• A reload channel for the preview server and development gallery. It owns session identifiers, notifications, client disconnection, and shutdown.
• A browser downloadBlob() helper for standalone CSV exports and preview-host downloads.

Server entry points remain separate. Callers retain their routing, authorization, response formats, watchers, and debounce behavior.

Runtime and dependency boundaries

The preview server binds to 127.0.0.1, validates the request host, and accepts SQL only from its own origin. SQL requests have a 100,000-byte UTF-8 body limit. Oversized requests return a JSON query_rejected response so the host preserves the typed error.

Preview functionality is exported only through the Bun subpath. Browser entries remain free of Bun/server implementations and credentials. Production dependencies are unchanged.

get-tsconfig remains a development dependency and is bundled into the Bun preview artifact. It preserves JSONC, inherited configuration, baseUrl, and wildcard mappings without introducing a custom configuration parser or an installed frontend dependency.

Release coordination

The companion CLI change consumes this API as a thin launcher. We need to publish a package version containing the preview entry before updating the CLI’s pinned package version.

[robinvrd]

LGTM, let's just verify running without credentials gives correct guidance for it to work

[albert20260301]

Blocking until CI is clean: the required source/package suite fails in dev:file replaces the rendered iframe and preserves URL filters after edits (the replacement iframe never renders Second preview). CodeQL also reports three new alerts in this PR, including one critical severity alert. Please resolve both and rerun the required checks before re-review.