@abide/abide 0.28.0

package/src/appEntry.ts

@@ -0,0 +1,151 @@
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { disconnectedHtml } from './_virtual/bundle-disconnected.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import bundleWindow from './_virtual/bundle-window.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import programName from './_virtual/cli-name.ts'
+import type { BundleMenu } from './lib/bundle/BundleMenu.ts'
+import type { BundleWindow } from './lib/bundle/BundleWindow.ts'
+import { openWebview } from './lib/bundle/openWebview.ts'
+import { envSchemaStore } from './lib/server/runtime/envSchemaStore.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { jsonSchemaForSchema } from './lib/shared/jsonSchemaForSchema.ts'
+
+/*
+Compiled bundle launcher entry — the executable a bundle runs. Instead of a blank
+window it boots into a connect screen, letting the user either connect to a remote
+server by URL or start the embedded server binary that ships beside this launcher.
+
+The connect screen is served by a tiny control server, but that server can't live
+on this main thread: `openWebview` calls `webview_run`, a native UI loop that
+blocks the thread (and its JS event loop) until the window closes, so an
+in-process `Bun.serve` would never answer. The control server runs in a Worker
+instead (see controlServerWorker.ts) and hands back the origin to point the window
+at; it also owns the embedded-server child and the native menu flag, since neither
+can be driven from a main thread frozen inside webview_run.
+
+Bun doesn't apply this build's plugins to the worker entry, so the worker can't
+import abide's virtual modules; this entry imports them (the connect-screen HTML,
+the app title) and passes them in the worker's `init` message.
+
+The window owns the main thread; on close we tell the worker to reap its child.
+*/
+const window = bundleWindow as BundleWindow
+const title = window.title ?? programName
+
+/*
+Derive the config form's JSON Schema here (the worker can't import the virtuals
+that carry the schema) and pass the plain object through init — the validator
+itself isn't serializable, but its JSON Schema is. Undefined when the app
+declares no config, so the connect screen never gates Start.
+
+Default source is src/server/config.ts's env schema, so one declaration drives
+both boot validation and the setup form. Imported with skipValidation set — we
+want the schema's shape, not a boot check the launcher has no business running.
+`window.config` replaces it when set, for a bundle form that should differ from
+the env schema.
+*/
+envSchemaStore.skipValidation = true
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+await import('./_virtual/config.ts')
+const formSchema = window.config ?? envSchemaStore.schema
+const configSchema = formSchema ? jsonSchemaForSchema(formSchema) : undefined
+
+/*
+Spawn the control server worker. `__ABIDE_WORKER_ENTRY__` is the worker's absolute
+path, injected by bundleApp via Bun's `define` so the specifier is a static literal
+at build time — that's what makes `bun build --compile` embed the worker module
+into the standalone binary. A relative specifier resolves against the build's cwd
+(the consumer project), not this file, so it isn't found; a
+`new URL(..., import.meta.url)` specifier isn't embedded at all.
+*/
+declare const __ABIDE_WORKER_ENTRY__: string
+const worker = new Worker(__ABIDE_WORKER_ENTRY__)
+
+worker.addEventListener('error', (event: ErrorEvent) => {
+    abideLog.error(`control server worker failed: ${event.message}`)
+})
+
+// Hand the worker the plugin-resolved data it can't import itself, then start it.
+worker.postMessage({
+    type: 'init',
+    init: { disconnectedHtml: disconnectedHtml as string, title, programName, configSchema },
+})
+
+/*
+The worker, once bound, resolves where the window should open and posts both the
+control-server `origin` (for the File-menu action URLs) and the `target` to point
+the window at now: the live server when it could resume the last connection, else
+the connect screen. Resolving before this means a successful resume opens straight
+at the app — no connect-screen flash — at the cost of a brief window-less moment
+while it boots/probes (the OS shows the launching dock icon meanwhile).
+*/
+const { origin, target } = await new Promise<{ origin: string; target: string }>((resolve) => {
+    worker.addEventListener('message', (event: MessageEvent) => {
+        const data = event.data as { type: string; origin?: string; target?: string }
+        if (data.type === 'ready' && data.origin && data.target) {
+            resolve({ origin: data.origin, target: data.target })
+        }
+    })
+})
+
+/*
+The built-in File menu (Start / Disconnect), placed before Edit. Each item is a
+`navigate` repointing the window at a control-server URL the connect screen
+interprets; the internal `role` drives the native validateMenuItem: gating (Start
+when disconnected, Disconnect when connected). There's no Connect item — Disconnect
+already returns to the connect screen, whose form is the place to point at another
+server. Roled items are launcher-only, so they carry an extra field the public
+BundleMenuItem type doesn't advertise — modelled here with a local type and bridged
+to BundleMenu when handed to openWebview (which only serialises the menu to JSON).
+*/
+type FileMenuItem =
+    | { separator: true }
+    | {
+          label: string
+          shortcut?: string
+          navigate: string
+          role: 'start' | 'disconnect'
+      }
+const fileMenu: { label: string; items: FileMenuItem[] } = {
+    label: 'File',
+    items: [
+        { label: 'Start Server', navigate: `${origin}/?action=start`, role: 'start' },
+        { separator: true },
+        { label: 'Disconnect', navigate: `${origin}/?action=disconnect`, role: 'disconnect' },
+    ],
+}
+
+abideLog.info(`opening ${title} window at ${target}`)
+await openWebview({
+    url: target,
+    title,
+    width: window.width,
+    height: window.height,
+    menu: window.menu,
+    fileMenu: fileMenu as unknown as BundleMenu,
+    // Forward the window handle so the worker can bounce it back to the connect
+    // screen if the connected server stops responding.
+    onWindow: (handle) => {
+        if (handle) {
+            worker.postMessage({ type: 'window', handle: Number(handle) })
+        }
+    },
+})
+
+/*
+Window closed — have the worker reap the embedded server child and stop its
+control server before we exit, since both live on the worker thread. Bounded by a
+timeout so a wedged worker can't keep the launcher alive.
+*/
+await new Promise<void>((resolve) => {
+    worker.addEventListener('message', (event: MessageEvent) => {
+        if ((event.data as { type?: string }).type === 'shutdownDone') {
+            resolve()
+        }
+    })
+    worker.postMessage({ type: 'shutdown' })
+    setTimeout(resolve, 1000)
+})
+worker.terminate()
+process.exit(0)

package/src/assets/app.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<!--ssr:head-->
+</head>
+<body>
+<div id="app"><!--ssr:body--></div>
+<!--ssr:state-->
+</body>
+</html>

package/src/build.ts

@@ -0,0 +1,143 @@
+import { clientBuildPlugins } from './clientBuildPlugins.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
+
+const CLIENT_ENTRY = new URL('./clientEntry.ts', import.meta.url).pathname
+
+/*
+Builds the client-side bundle into `${cwd}/dist/_app`. Runs Bun.build with
+the abide-ui `.abide` loader, the virtual-module resolver, and (optionally)
+Tailwind. When `compress`, each emitted file is also
+written as a gzip-compressed `.gz` sibling (level 9 — paid once at build
+time) so the server can stream the precompressed bytes directly to any client
+that accepts gzip (effectively all), and decompress on the fly otherwise. Dev
+skips compression (compressing on every rebuild dwarfs the bundle itself) — the
+server falls back to serving the plain bytes when no `.gz` sibling exists.
+
+The bundle is emitted into a per-build staging dir, then swapped into
+`_app` with two atomic renames. This keeps every build's writes isolated to
+a unique path (so a stray concurrent build can never `rm` files Bun is
+mid-flushing — the "writing sourcemap: No such file or directory" race) and
+means a long-running dev server reading `_app` lazily off disk never sees a
+half-built or emptied directory.
+
+`clean` (one-shot builds) clears the whole dist up front so downstream
+writers — the bundle's connect screen, the CLI manifest — start fresh; the
+dev orchestrator passes `clean: false` to leave the live dist untouched and
+only swap `_app` at the end.
+
+Returns whether the build succeeded. Never throws: a thrown Bun.build / fs
+error is logged and treated as a failed build, so the dev loop (and its
+last-good server) survives instead of crashing and orphaning the child. By
+default a failure exits the process (one-shot `abide build` / `compile`);
+the dev orchestrator passes `exitOnFailure: false`.
+*/
+// @readme plumbing
+export async function build({
+    cwd = process.cwd(),
+    minify = true,
+    compress = true,
+    clean = true,
+    exitOnFailure = true,
+}: {
+    cwd?: string
+    minify?: boolean
+    compress?: boolean
+    clean?: boolean
+    exitOnFailure?: boolean
+} = {}): Promise<boolean> {
+    const distDir = `${cwd}/dist`
+    const outDir = `${distDir}/_app`
+    // Per-build staging + holding dirs; the suffix isolates concurrent builds.
+    const buildId = crypto.randomUUID().slice(0, 8)
+    const stagingDir = `${distDir}/_app.staging-${buildId}`
+    const previousDir = `${distDir}/_app.old-${buildId}`
+
+    const fail = (): boolean => {
+        if (exitOnFailure) {
+            process.exit(1)
+        }
+        return false
+    }
+
+    try {
+        // shell-rm/-mv are the impure boundary for the dist swap — Bun.$ is first-party.
+        if (clean) {
+            await Bun.$`rm -rf ${distDir}`.quiet()
+        }
+
+        const plugins = await clientBuildPlugins({
+            cwd,
+            tailwindWarning: 'bun-plugin-tailwind not installed; building without Tailwind',
+        })
+
+        const result = await Bun.build({
+            entrypoints: [CLIENT_ENTRY],
+            outdir: stagingDir,
+            target: 'browser',
+            splitting: true,
+            minify,
+            sourcemap: 'linked',
+            naming: {
+                entry: 'client-[hash].[ext]',
+                chunk: '[name]-[hash].[ext]',
+                asset: '[name].[ext]',
+            },
+            plugins,
+        })
+
+        if (!result.success) {
+            await Bun.$`rm -rf ${stagingDir}`.quiet().nothrow()
+            if (exitOnFailure) {
+                exitOnBuildFailure(result)
+            }
+            result.logs.forEach((entry) => {
+                abideLog.error(entry)
+            })
+            return false
+        }
+
+        // Dev skips the gzip siblings (paths still point into stagingDir here).
+        const compressedBytes = compress
+            ? (
+                  await Promise.all(
+                      result.outputs.map(async (output) => {
+                          const bytes = await Bun.file(output.path).bytes()
+                          const compressed = Bun.gzipSync(bytes, { level: 9 })
+                          await Bun.write(`${output.path}.gz`, compressed)
+                          return compressed.byteLength
+                      }),
+                  )
+              ).reduce((total, length) => total + length, 0)
+            : 0
+
+        /*
+        Swap staging into _app with two renames: move any existing _app aside,
+        then rename staging into place. The window where _app is absent is a
+        single rename, so a reader (the running dev server) never observes a
+        partial bundle. nothrow on the first move: no _app exists on the first
+        build or after `clean`.
+        */
+        await Bun.$`mv ${outDir} ${previousDir}`.quiet().nothrow()
+        await Bun.$`mv ${stagingDir} ${outDir}`.quiet()
+        await Bun.$`rm -rf ${previousDir}`.quiet().nothrow()
+
+        if (compress) {
+            abideLog.info(
+                `wrote ${result.outputs.length} files to ${outDir} (+${result.outputs.length} .gz, ${(compressedBytes / 1024).toFixed(1)} KiB total)`,
+            )
+            // Per-file paths are noise at startup; surface them only under DEBUG=abide:build.
+            const buildLog = abideLog.channel('abide:build')
+            result.outputs.forEach((output) => {
+                buildLog(`  - ${output.path.replace(stagingDir, outDir)}`)
+            })
+        } else {
+            abideLog.info(`wrote ${result.outputs.length} files to ${outDir}`)
+        }
+        return true
+    } catch (error) {
+        abideLog.error(error)
+        await Bun.$`rm -rf ${stagingDir} ${previousDir}`.quiet().nothrow()
+        return fail()
+    }
+}

package/src/buildCli.ts

@@ -0,0 +1,127 @@
+import { dirname, join } from 'node:path'
+import { build } from './build.ts'
+import { compile } from './compile.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { detectTarget } from './lib/shared/detectTarget.ts'
+import { exeSuffix } from './lib/shared/exeSuffix.ts'
+import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
+import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
+import { readPackageJson } from './lib/shared/readPackageJson.ts'
+import type { CompileTarget } from './lib/shared/types/CompileTarget.ts'
+import { serverBuildPlugins } from './serverBuildPlugins.ts'
+
+const DISCOVERY_ENTRY = new URL('./discoveryEntry.ts', import.meta.url).pathname
+const CLI_ENTRY = new URL('./cliEntry.ts', import.meta.url).pathname
+
+/*
+CLI binary build. The CLI is a thin remote client — it bakes in the per-rpc
+manifest and talks to a running server over HTTP — but the **full** binary ships
+the compiled server beside it, so `/start` can spawn a local instance.
+
+  1. Client build (once): `build` produces the platform-independent `dist/_app`
+     the server binaries embed. It clears dist first, so it runs before everything.
+  2. Discovery: build the discovery entry into a temporary JS bundle and run it. It
+     imports every rpc/socket module so defineVerb / defineSocket populate the
+     registries, then prints the CLI manifest to stdout → `dist/cli-manifest.json`.
+  3. Per target: a server binary (`compile`, reusing the shared `dist/_app` via
+     `buildClient:false`) plus the CLI binary, written side by side. The resolver's
+     `abide:cli-manifest` virtual splices in the manifest from step 2.
+
+`platforms` cross-compiles per target into `dist/cli-thin/<platform>/` (the layout
+the /__abide/cli download endpoint serves): `<programName>` + `server` together.
+*/
+export async function buildCli({
+    cwd = process.cwd(),
+    target = detectTarget(),
+    outfile,
+    platforms,
+}: {
+    cwd?: string
+    target?: CompileTarget
+    outfile?: string
+    platforms?: CompileTarget[]
+} = {}): Promise<string[]> {
+    const distDir = `${cwd}/dist`
+    const manifestPath = `${distDir}/cli-manifest.json`
+    const discoveryOut = `${distDir}/_discovery.js`
+
+    const plugins = serverBuildPlugins({ cwd })
+
+    // Step 1 — client build once (clears dist, writes _app). Every server binary
+    // embeds it, so it must precede discovery and the per-target compiles.
+    await build({ cwd })
+
+    /*
+    Step 2 — discovery. Build a runnable bundle, execute it under bun, capture
+    stdout. We don't `bun build --compile` here because the discovery output is
+    throwaway; a plain JS bundle runs faster. Additive — does not clear dist.
+    */
+    const discoveryResult = await Bun.build({
+        entrypoints: [DISCOVERY_ENTRY],
+        target: 'bun',
+        outdir: distDir,
+        naming: '_discovery.js',
+        plugins,
+    })
+    exitOnBuildFailure(discoveryResult)
+
+    const proc = Bun.spawn({
+        cmd: ['bun', discoveryOut],
+        cwd,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const [stdout, stderr, exitCode] = await Promise.all([
+        new Response(proc.stdout).text(),
+        new Response(proc.stderr).text(),
+        proc.exited,
+    ])
+    if (exitCode !== 0) {
+        abideLog.error(`discovery exited ${exitCode}:\n${stderr}`)
+        process.exit(1)
+    }
+    await Bun.write(manifestPath, stdout)
+    await Bun.$`rm -f ${discoveryOut}`.quiet()
+    const entryCount = Object.keys(JSON.parse(stdout) as Record<string, unknown>).length
+    abideLog.info(`discovered ${entryCount} cli commands → ${manifestPath}`)
+
+    const programName = await readProgramName(cwd)
+
+    /*
+    Step 3 — compile a CLI binary + sibling server binary for a single target,
+    written side by side so `resolveServerBinary()` finds the server next to the
+    running CLI. The server reuses the shared client build (buildClient:false).
+    */
+    async function buildTargetPair(platformTarget: CompileTarget, cliOut: string): Promise<string> {
+        const serverOut = join(dirname(cliOut), `server${exeSuffix(platformTarget)}`)
+        await compile({ cwd, target: platformTarget, outfile: serverOut, buildClient: false })
+        const result = await Bun.build({
+            entrypoints: [CLI_ENTRY],
+            target: 'bun',
+            compile: { target: platformTarget, outfile: cliOut },
+            plugins,
+        })
+        exitOnBuildFailure(result)
+        abideLog.success(`compiled cli + server: ${cliOut}`)
+        return cliOut
+    }
+
+    if (platforms && platforms.length > 0) {
+        // Cross-compile every target in parallel — each pair is independent.
+        return Promise.all(
+            platforms.map(async (platformTarget) => {
+                const shortName = platformTarget.replace(/^bun-/, '')
+                const cliOut = `${distDir}/cli-thin/${shortName}/${programName}${exeSuffix(platformTarget)}`
+                await Bun.$`mkdir -p ${`${distDir}/cli-thin/${shortName}`}`.quiet()
+                return buildTargetPair(platformTarget, cliOut)
+            }),
+        )
+    }
+
+    const cliOut = outfile ?? `${distDir}/cli${exeSuffix(target)}`
+    return [await buildTargetPair(target, cliOut)]
+}
+
+async function readProgramName(cwd: string): Promise<string> {
+    const pkg = (await readPackageJson(cwd)) as { name?: string } | undefined
+    return programNameForPackage(pkg?.name)
+}

package/src/buildDisconnected.ts

@@ -0,0 +1,118 @@
+import { clientBuildPlugins } from './clientBuildPlugins.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
+
+const ENTRY = new URL('./bundleDisconnectedEntry.ts', import.meta.url).pathname
+const CSS_ENTRY = new URL('./lib/bundle/disconnected.css', import.meta.url).pathname
+
+/*
+Default screen logo: a minimal inline-SVG abide mark, used when the project ships
+no src/bundle/logo.png. Inline SVG keeps the bundle self-contained with no asset
+file to vendor; a project overrides it just by adding the PNG.
+*/
+const DEFAULT_LOGO = `data:image/svg+xml,${encodeURIComponent(
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 64 64">' +
+        '<rect width="64" height="64" rx="16" fill="#111827"/>' +
+        '<text x="32" y="45" font-family="system-ui,sans-serif" font-size="38" ' +
+        'font-weight="700" fill="#fff" text-anchor="middle">b</text></svg>',
+)}`
+
+/*
+Builds the bundle connect screen into a single self-contained HTML string and
+writes it to `dist/bundle-disconnected.html`, which the launcher bakes in via the
+`abide:bundle-disconnected` virtual. The client bundle (abide-ui component +
+injected CSS + compiled Tailwind) is inlined into the page so the launcher serves
+it with zero external requests; the logo is embedded as a data URI. The app title
+(`window.__ABIDE_TITLE__`) is injected by the launcher at serve time, so a
+`<!--abide:connect-config-->` marker is left in <head> for it.
+
+Must run after the client build has cleared and repopulated dist (it writes a
+file into dist), and before the launcher build that reads it. Uses no outdir of
+its own — Bun.build artifacts are read from memory — so it never touches dist
+beyond the one file it writes.
+*/
+export async function buildDisconnected({
+    cwd = process.cwd(),
+}: {
+    cwd?: string
+} = {}): Promise<string> {
+    const plugins = await clientBuildPlugins({
+        cwd,
+        tailwindWarning:
+            'bun-plugin-tailwind not installed; building connect screen without Tailwind',
+    })
+
+    /*
+    The Tailwind CSS rides as its own entrypoint rather than a `.css` import from
+    the entry (which TS can't type), so it compiles to a standalone artifact we
+    inline alongside the JS — the component carries no <style> of its own.
+    */
+    const result = await Bun.build({
+        entrypoints: [ENTRY, CSS_ENTRY],
+        target: 'browser',
+        minify: true,
+        plugins,
+    })
+    exitOnBuildFailure(result)
+
+    // Collect the JS bundle + extracted CSS from the in-memory artifacts.
+    let js = ''
+    let css = ''
+    for (const output of result.outputs) {
+        const text = await output.text()
+        if (output.path.endsWith('.css')) {
+            css += text
+        } else if (output.path.endsWith('.js')) {
+            js += text
+        }
+    }
+
+    const logo = await readLogo(cwd)
+    const html = composeHtml({ js, css, logo })
+    const outPath = `${cwd}/dist/bundle-disconnected.html`
+    await Bun.write(outPath, html)
+    abideLog.success(`built connect screen: ${outPath} (${(html.length / 1024).toFixed(1)} KiB)`)
+    return outPath
+}
+
+// Reads the project's src/bundle/logo.png as a data URI, or the default mark.
+async function readLogo(cwd: string): Promise<string> {
+    const userLogo = Bun.file(`${cwd}/src/bundle/logo.png`)
+    if (await userLogo.exists()) {
+        const bytes = await userLogo.bytes()
+        return `data:image/png;base64,${bytes.toBase64()}`
+    }
+    return DEFAULT_LOGO
+}
+
+/*
+Escapes a closing `</script>` so an inline `<script>` body can't be terminated
+early by content in the bundle (rare, but a `</script>` substring would break the
+page). The browser still parses `<\/script>` as the intended characters.
+*/
+function escapeScriptBody(value: string): string {
+    return value.replace(/<\/(script)/gi, '<\\/$1')
+}
+
+// Assembles the final standalone HTML document from the inlined pieces.
+function composeHtml({ js, css, logo }: { js: string; css: string; logo: string }): string {
+    const logoScript = `window.__ABIDE_LOGO__=${JSON.stringify(logo)}`
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1.0" />
+<!--abide:connect-config-->
+<script>${escapeScriptBody(logoScript)}</script>
+<!-- Paint the screen background before the client mounts, so there's no white
+flash ahead of the splash (gray-50 / gray-950 to match the rendered screen). -->
+<style>html,body{margin:0;background:#f9fafb}@media (prefers-color-scheme:dark){html,body{background:#030712}}</style>
+<style>${css}</style>
+</head>
+<body>
+<div id="app"></div>
+<script type="module">${escapeScriptBody(js)}</script>
+</body>
+</html>
+`
+}