// Shared machinery for the kinds of **applet** — agent-authored UI units // embedded in a workspace: grid **widgets** (`.moi/widgets/`) and full-screen // **views** (`.moi/views/`). Both compile through `buildApplet` and are served // as ESM. This module holds the kind-agnostic mechanics (paths, scan, // staleness, prune, serve, build loop); the per-kind manifest shape, config // schema, and MEI events live in `widgets.ts` / `views.ts`. // // Each applet builds into its OWN directory `.build///`, holding a // fixed `index.js` entry plus any code chunks and bundled assets (hashed // images/fonts). The client dynamic-imports that entry at `/module` — an // extensionless alias, see `ENTRY_ROUTE_FILE` — and assets and chunks resolve // module-relative from there. `.js` files carry the // `%%MOI_APPLET_API_BASE%%` sentinel (for RPC + file resolution), swapped to the real // `/api/workspaces/` base when served — so the on-disk bundle is // workspace-agnostic. import { realpathSync, statSync } from 'node:fs' import { mkdir, readdir, rm } from 'node:fs/promises' import { join, resolve, sep } from 'path' import { analyzeDependencies, resolveSource, scanSources } from './dependencies' import type { AppletKind } from './build-applet' import { buildAppletsInChild } from './build-worker' import { APPLET_API_BASE_SENTINEL } from './api-base' import { pruneAppletThumbnails } from './thumbnails' export { scanSources } from './dependencies' export type AppletPaths = { moiRoot: string sourceDir: string buildDir: string manifestPath: string } export function getAppletPaths(workspacePath: string, kind: AppletKind): AppletPaths { const moiRoot = join(workspacePath, '.moi') const dir = kind === 'widget' ? 'widgets' : 'views' const sourceDir = join(moiRoot, dir) const buildDir = join(moiRoot, '.build', dir) const manifestPath = join(buildDir, 'manifest.json') return { moiRoot, sourceDir, buildDir, manifestPath } } export function getAppletRevision( workspacePath: string, kind: AppletKind, id: string ): string | undefined { try { const { buildDir } = getAppletPaths(workspacePath, kind) const stat = statSync(join(buildDir, id, 'index.js')) return `${stat.size}-${Math.trunc(stat.mtimeMs)}` } catch { return undefined } } // Server dependencies also trigger rebuilds so their function worker is // recycled, even when the client bundle's RPC stubs would remain identical. async function needsRebuild(buildDir: string, name: string, srcPath: string): Promise { const built = Bun.file(join(buildDir, name, 'index.js')) if (!(await built.exists())) return true const graph = await analyzeDependencies([srcPath], built.lastModified) return !graph.complete } // Built applet names: subdirectories of `buildDir` that hold an `index.js` // entry. (`manifest.json` and any stray files are ignored.) export async function listBuilt(buildDir: string): Promise { try { const entries = await readdir(buildDir, { withFileTypes: true }) const names: string[] = [] for (const e of entries) { if (!e.isDirectory()) continue if (await Bun.file(join(buildDir, e.name, 'index.js')).exists()) names.push(e.name) } return names } catch { return [] } } async function pruneStaleBuilds(buildDir: string, sourceNames: Set): Promise { let entries try { entries = await readdir(buildDir, { withFileTypes: true }) } catch { return } for (const e of entries) { // Drop build dirs whose source is gone… if (e.isDirectory()) { if (!sourceNames.has(e.name)) { await rm(join(buildDir, e.name), { recursive: true, force: true }).catch(() => {}) } continue } // …and sweep leftover flat `.js` from the pre-directory layout (the // new layout never writes `.js` directly under buildDir — entries live in // `/index.js`). manifest.json and other files are left alone. if (e.isFile() && e.name.endsWith('.js')) { await rm(join(buildDir, e.name), { force: true }).catch(() => {}) } } } // Files an applet may serve from its build dir, by extension. JS is swapped + // served as code; everything else streams raw (Bun infers content-type and // supports range requests). const CODE_FILE_RE = /\.js$/ // A single flat filename in the bundle dir: index.js, chunk-.js, or a // hashed asset. First char may be `_`/`-` (asset stems derive from the source // basename, e.g. `_icon.png` → `_icon-.png`) but never `.`, so no dotfile // can be requested; `..` is rejected separately. const ALLOWED_FILE_RE = /^[a-zA-Z0-9_-][a-zA-Z0-9._-]*$/ const JS_CONTENT_TYPE = 'text/javascript; charset=utf-8' // A content-hashed url is a fingerprint of its bytes, so it's safe to cache // without revalidation. But immutability here is INFERRED from the filename // (HASHED_FILE_RE) rather than guaranteed by construction (unlike a sha256-named // asset) — so we cap the TTL at a week instead of the usual year. If that // inference ever misfires, a wrongly-pinned copy self-heals within a week at the // edge and in the browser, rather than sticking around for a year. const IMMUTABLE_CACHE = 'public, max-age=604800, immutable' // Which build-dir files are safe to serve `immutable`. The build emits exactly // two content-hashed shapes — Bun's `chunk-.js` and the runtime plugin's // `-.` assets (hash = hex, see build-applet.ts) — alongside the // ONE stable-named entry, `index.js`. We match those shapes POSITIVELY and // default everything else (the entry, and anything unexpected) to revalidation: // this fix exists to stop a shared cache pinning a stale copy at a stable url, // so an unrecognized name must fail safe (revalidate), never fail stale // (immutable). The hex-suffix arm rejects real words (`-sprite`, `-preview`) — // they aren't hex — so only genuine hashes opt in. const HASHED_FILE_RE = /^chunk-[0-9a-z]+\.\w+$|-[0-9a-f]{6,}\.\w+$/i // Serve one file from a compiled applet directory: the `index.js` entry, a code // chunk, or a bundled asset. `apiBase` is the workspace's `/api/workspaces/` // prefix — substituted for the build-time sentinel in every `.js` so RPC and // file addresses resolved by `resolveUrl` hit the right workspace. Assets stream untouched. // // `file` is the ON-DISK name (the route's extensionless entry alias is already // mapped back to `index.js` by `parseAppletTail`), so the content-type and // sentinel-swap decisions below key off the real `.js` — do not switch them to // the requested url, or the entry would ship as `application/octet-stream` and // fail the browser's module MIME check. // // Caching turns on the hashed-vs-stable split. A content-hashed chunk/asset gets // a new url whenever its bytes change, so it's cached forever. The `index.js` // entry (and anything not recognizably hashed) lives at ONE url across rebuilds, // so a shared cache (e.g. Cloudflare) that stored it once would hand back a // STALE copy after the next `moi bundle` — it gets an ETag (size+mtime) + // `private, no-cache` instead, so an unchanged file costs a 304 and a rebuilt // one busts. `private` keeps it out of any shared cache that would store it // anyway, and is the one directive Cloudflare preserves when its Browser Cache // TTL rewrites the header (see `ENTRY_ROUTE_FILE` for the rest of that story). export async function serveApplet( kind: AppletKind, name: string, file: string, workspacePath: string, apiBase: string, ifNoneMatch?: string | null ): Promise { if (!/^[a-zA-Z0-9_-]+$/.test(name)) { return new Response('Invalid name', { status: 400 }) } // Single path segment, no traversal — the bundle dir is flat. if (!ALLOWED_FILE_RE.test(file) || file.includes('..')) { return new Response('Invalid file', { status: 400 }) } const { buildDir } = getAppletPaths(workspacePath, kind) const path = join(buildDir, name, file) const bunFile = Bun.file(path) if (!(await bunFile.exists())) { return new Response(`"${name}" not built. Run: moi bundle`, { status: 404 }) } // Content-hashed → immutable. Everything else → revalidate (ETag + no-cache), // short-circuiting to a bodyless 304 when the client's ETag still matches. let cache: Record if (HASHED_FILE_RE.test(file)) { cache = { 'Cache-Control': IMMUTABLE_CACHE } } else { const etag = `"${bunFile.size}-${Math.trunc(bunFile.lastModified)}"` cache = { ETag: etag, 'Cache-Control': 'private, no-cache' } if (ifNoneMatch === etag) return new Response(null, { status: 304, headers: cache }) } if (CODE_FILE_RE.test(file)) { const swapped = (await bunFile.text()).replaceAll(APPLET_API_BASE_SENTINEL, apiBase) return new Response(swapped, { headers: { 'Content-Type': JS_CONTENT_TYPE, ...cache } }) } return new Response(bunFile, { headers: { 'Content-Type': bunFile.type || 'application/octet-stream', ...cache } }) } // ---- route helpers ---------------------------------------------------------- // Pure helpers behind the applet/files/rpc HTTP routes, kept here (not web.ts) so // they're unit-testable without importing web.ts — which binds ports on load. // The API base a served bundle's sentinel is rewritten to. RPC and workspace // file addresses resolved by `resolveUrl()` use this prefix. export function apiBaseFor(id: string): string { return `/api/workspaces/${id}` } // The entry's real name in the bundle dir (`.build///index.js`). const ENTRY_DISK_FILE = 'index.js' // …and the url the client asks for it at: `…///module`. The route // name and the disk name differ ON PURPOSE, and the reason is proxies. // // Cloudflare — which sits between many users and their moi, usually as a tunnel // — decides whether a response is cache-eligible from the url's FILE EXTENSION, // not from its content type, and `JS` is on its default cached-extension list. // Once a response is cache-eligible, the zone's Browser Cache TTL applies, and // that setting overrides the origin's `Cache-Control` on the way to the browser // whenever the origin's freshness is lower than the TTL. Its default is 4 hours // on every plan, so our `no-cache` came back to the browser as `max-age=14400`. // The entry lives at ONE url across rebuilds, so that rewrite pinned a stale // bundle in the user's browser for hours: no revalidation, so the ETag never got // a chance to bust it, and `?v` couldn't either (it's an in-memory counter that // resets to 0 on reload, landing right back on the poisoned url). // // An extensionless path isn't cache-eligible by default, so it reaches the // browser with the headers we actually sent. Chunks and assets keep their // extensions deliberately — they're content-hashed and WANT the edge cache. // The build only ever emits `index.js`, `chunk-.js` and hashed assets, so // this name can never collide with a real bundle file. Mirrors `appletUrl` in // `client/features/applets/applet-cache.ts`. const ENTRY_ROUTE_FILE = 'module' // Split an applet file request `…///` into name + file. A // bare `…//` (or legacy `…/.js`) targets the entry, as does // the extensionless `…//module` alias. `file` is always the on-disk name, // so `serveApplet` never has to know the route spelling. export function parseAppletTail( url: string, id: string, segment: 'widgets' | 'views' ): { name: string; file: string } { const tail = new URL(url).pathname.split(`/api/workspaces/${id}/${segment}/`)[1] ?? '' const slash = tail.indexOf('/') if (slash === -1) return { name: tail.replace(/\.js$/, ''), file: ENTRY_DISK_FILE } const file = tail.slice(slash + 1) return { name: tail.slice(0, slash), file: file === ENTRY_ROUTE_FILE ? ENTRY_DISK_FILE : file } } // Extensions served for `moi:/files/...` addresses. Media + image/doc // assets only — deliberately excludes text/data (`.json`, `.env`, `.md`, // source) so the route can't be used to exfiltrate arbitrary workspace data. const FS_MEDIA_RE = /\.(mp4|webm|mov|m4v|mkv|mp3|wav|ogg|oga|m4a|flac|aac|opus|png|jpe?g|gif|webp|avif|svg|ico|pdf|vtt|srt)$/i // Resolve a `/files/`-style tail to a real on-disk path inside the workspace root, // or an error Response. Hard guards (defense in depth): reject empty/`.`/`..`/ // dotfile segments and anything resolving outside the root, and require a media // extension. The workspace holds secrets (`.env`, `.moi/`) and the routes built // on this are unauthenticated — these guards are the protection, not the // localhost bind. Shared by the raw stream (`serveWorkspaceFile`) and the image // preview route (server/workspaces/preview.ts). export function resolveWorkspaceMediaFile(workspaceRoot: string, tail: string): string | Response { let rel: string try { rel = decodeURIComponent(tail) } catch { return new Response('Bad path', { status: 400 }) } if (!rel || rel.includes('\0')) return new Response('Bad path', { status: 400 }) const segments = rel.split('/') if (segments.some(s => s === '' || s === '.' || s === '..' || s.startsWith('.'))) { return new Response('Forbidden', { status: 403 }) } if (!FS_MEDIA_RE.test(rel)) return new Response('Unsupported file type', { status: 415 }) const root = resolve(workspaceRoot) const target = resolve(workspaceRoot, rel) if (target !== root && !target.startsWith(root + sep)) { return new Response('Forbidden', { status: 403 }) } // The lexical check above is not enough: a symlink that lives inside the root // but points outside it would pass. Canonicalize both sides and re-check on // the real paths — this blocks symlink escape while still allowing symlinks // that stay within the workspace. realpathSync throws ENOENT for a missing // file, which doubles as the existence check (→ 404). Both sides are // canonicalized so a symlinked root (e.g. macOS /tmp → /private/tmp) isn't a // false escape. let realTarget: string try { realTarget = realpathSync(target) } catch { return new Response('Not found', { status: 404 }) } let realRoot: string try { realRoot = realpathSync(root) } catch { return new Response('Forbidden', { status: 403 }) } if (realTarget !== realRoot && !realTarget.startsWith(realRoot + sep)) { return new Response('Forbidden', { status: 403 }) } return realTarget } // Stream a media file from the workspace root (guards: see // `resolveWorkspaceMediaFile`). // // Range is handled explicitly (slice the BunFile, 206 + Content-Range): Bun's // implicit range handling for `new Response(Bun.file())` doesn't fire once any // headers object is attached, and