Watch admin static_root and serve assets via dev server WebSocket

[melissaluu]

Summary

• Adds app-level asset directory watching and serving to the UI extensions dev server
• When an admin extension has static_root configured in its TOML, the dev server watches that directory for file changes, serves its contents via HTTP, and broadcasts timestamp updates to all WebSocket clients
• Introduces a generic app.assets field on the WebSocket payload, keyed by asset type (currently staticRoot), each with a url and lastUpdated timestamp

How it works

Payload model (models.ts, ui-extensions-server-kit/types.ts): Added optional app.assets to both server-side and client-side types — a Record<string, { url, lastUpdated }>.

Payload store (store.ts): Accepts appAssets in options to populate app.assets on init. Exposes updateAppAssetTimestamp(key) to bump a single asset's timestamp and emit an update, and updateAppAssets(appAssets, url) to fully rebuild or remove the assets map (used on app reload).

HTTP serving (middlewares.ts, server.ts): Parameterized route at /extensions/assets/:assetKey/**:filePath serves files from the resolved directory, using the existing fileServerMiddleware helper.

File watching (extension.ts): Creates a dedicated chokidar watcher per asset directory with debounced updates. Watchers and debounce timers are cleaned up on abort and restarted on app reload when the admin extension config changes.

Plumbing (previewable-extension.ts): Resolves admin extension's static_root into the appAssets map at process setup time via shared resolveAppAssets() helper.

End-to-end flow

File changed in admin static_root directory
  → chokidar watcher (debounced)
  → payloadStore.updateAppAssetTimestamp("staticRoot")
  → emits Update event (extensionIds=[])
  → WebSocket broadcasts { app: { assets: { staticRoot: { url, lastUpdated } } }, extensions: [] }
  → clients receive updated timestamp

Test plan

• extension.test.ts — resolveAppAssets() returns correct map for admin extensions with/without static_root; appAssets passed through to HTTP server
• store.test.ts — updateAppAssetTimestamp updates timestamp and emits; updateAppAssets rebuilds or removes assets; raw payload populates app.assets when configured
• middlewares.test.ts — getAppAssetsMiddleware serves files for valid keys, returns 404 for unknown keys

🤖 Generated with Claude Code

[github-actions]

We detected some changes at packages/*/src and there are no updates in the .changeset.
If the changes are user-facing, run pnpm changeset add to track your changes and include them in the next release CHANGELOG.

Caution

DO NOT create changesets for features which you do not wish to be included in the public changelog of the next CLI release.

[Copilot]

Pull request overview

Adds support to the UI extensions dev server for app-level “asset directories” (starting with admin extension static_root), including HTTP serving and WebSocket payload updates so clients can invalidate/reload assets when files change.

Changes:

• Extend dev server WebSocket payload/types with optional app.assets (keyed map of {url, lastUpdated}).
• Serve app-level assets from /extensions/assets/:assetKey/**:filePath when configured.
• Watch configured asset directories and broadcast lastUpdated timestamp bumps on changes; re-resolve assets on app reload.

Reviewed changes

Copilot reviewed 10 out of 10 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
packages/ui-extensions-server-kit/src/types.ts	Adds App.assets to the shared server-kit type surface.
packages/app/src/cli/services/dev/processes/previewable-extension.ts	Resolves and passes appAssets into the dev server process options.
packages/app/src/cli/services/dev/extension/server/middlewares.ts	Introduces getAppAssetsMiddleware for serving app-level assets.
packages/app/src/cli/services/dev/extension/server/middlewares.test.ts	Adds middleware tests for serving app assets + unknown key 404.
packages/app/src/cli/services/dev/extension/server.ts	Wires the new assets route into the HTTP server when appAssets is present.
packages/app/src/cli/services/dev/extension/payload/store.ts	Adds appAssets to payload initialization and new store update APIs.
packages/app/src/cli/services/dev/extension/payload/store.test.ts	Adds unit tests for app asset timestamp updates + payload initialization behavior.
packages/app/src/cli/services/dev/extension/payload/models.ts	Adds app.assets to the server-side payload model interface.
packages/app/src/cli/services/dev/extension.ts	Implements resolveAppAssets, chokidar watchers, and app reload plumbing.
packages/app/src/cli/services/dev/extension.test.ts	Adds tests for resolveAppAssets and passing appAssets through to HTTP server setup.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

getExtensionsPayloadStoreRawPayload sets payload.app.assets whenever options.appAssets is truthy, even if it’s an empty object. That produces app.assets = {} whereas updateAppAssets treats an empty map as “no assets” and deletes the field. Consider aligning the behavior by checking Object.keys(options.appAssets).length > 0 before setting payload.app.assets.

[Copilot]

const directory = appAssets[assetKey] reads a URL-controlled key from a plain object. Keys like __proto__/constructor can resolve to inherited properties (non-string values) and bypass the !directory guard. Use an own-property check (e.g., Object.hasOwn(appAssets, assetKey)) and/or construct appAssets with a null prototype to avoid prototype-chain lookups.