@abide/abide 0.28.0

package/src/bundleApp.ts

@@ -0,0 +1,147 @@
+import { dirname } from 'node:path'
+import { buildDisconnected } from './buildDisconnected.ts'
+import { compile } from './compile.ts'
+import { ensureWebviewLib } from './lib/bundle/ensureWebviewLib.ts'
+import { infoPlist } from './lib/bundle/infoPlist.ts'
+import { pngToIcns } from './lib/bundle/pngToIcns.ts'
+import { serverBinaryFilename } from './lib/bundle/serverBinaryFilename.ts'
+import { signMacApp } from './lib/bundle/signMacApp.ts'
+import { webviewLibName } from './lib/bundle/webviewLibName.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { bundleLayout } from './lib/shared/bundleLayout.ts'
+import { detectTarget } from './lib/shared/detectTarget.ts'
+import { exitOnBuildFailure } from './lib/shared/exitOnBuildFailure.ts'
+import { programNameForPackage } from './lib/shared/programNameForPackage.ts'
+import { readPackageJson } from './lib/shared/readPackageJson.ts'
+import { serverBuildPlugins } from './serverBuildPlugins.ts'
+
+const APP_ENTRY = new URL('./appEntry.ts', import.meta.url).pathname
+const WORKER_ENTRY = new URL('./controlServerWorker.ts', import.meta.url).pathname
+
+/*
+Assembles a movable, self-contained app bundle for the host platform —
+no cross-compilation, and on macOS an ad-hoc seal so it launches on other
+Macs (signMacApp). Three pieces travel together so the app runs on another
+machine of the same OS with nothing installed:
+
+  - the standalone server binary (`compile()`, assets embedded)
+  - the launcher binary (appEntry — spawns the server, opens the webview)
+  - the native webview shared library
+
+macOS gets a `.app` bundle (`Contents/MacOS/` + `Contents/Frameworks/` +
+Info.plist); other platforms get a flat `<name>/` directory with the two
+binaries and the lib side by side. The launcher finds both relatives at
+runtime via resolveServerBinary / resolveWebviewLib.
+*/
+export async function bundleApp({ cwd = process.cwd() }: { cwd?: string } = {}): Promise<string> {
+    const target = detectTarget()
+    const { name, version } = await readPackage(cwd)
+    const programName = programNameForPackage(name)
+
+    /*
+    Layout differs by OS: a macOS .app nests binaries under Contents/MacOS, the
+    lib under Contents/Frameworks, and data under Contents/Resources; elsewhere
+    everything sits flat in one directory. bundleLayout derives the rest from
+    binDir — the same source the boot readers resolve from — so build and runtime
+    agree on where the lib, resources, and shipped `.env` land.
+    */
+    const isMac = process.platform === 'darwin'
+    const bundleRoot = isMac ? `${cwd}/dist/${programName}.app` : `${cwd}/dist/${programName}`
+    const binDir = isMac ? `${bundleRoot}/Contents/MacOS` : bundleRoot
+    const { libDir, resourcesDir, envPath } = bundleLayout(binDir)
+
+    await Bun.$`rm -rf ${bundleRoot}`.quiet()
+    await Bun.$`mkdir -p ${binDir} ${libDir}`.quiet()
+
+    // 1. Server binary — self-contained, embeds the client assets. compile()
+    // runs the client build, which clears dist first, so it must precede the
+    // connect-screen build that writes into dist.
+    await compile({ cwd, target, outfile: `${binDir}/${serverBinaryFilename()}` })
+
+    /*
+    Opt-in: ship the project's `bundle.env` as the shipped `.env`, which the
+    server loads at boot (loadEnvFromBinaryDir) as its default config layer. A
+    dedicated file, never the working `.env` — a compiled bundle is extractable,
+    so only ship-safe defaults belong here; user-specific/secret values come from
+    the data-dir `.env` instead. Named outside Bun's `.env.*` autoload family on
+    purpose: it's a build input, not a runtime overlay, so `bun dev`/`bun start`
+    never pick it up. bundleLayout places it under Contents/Resources
+    in a macOS `.app` (sealed as a resource, so it survives codesign) and beside
+    the binaries otherwise. Skipped when absent.
+    */
+    const bundleEnv = Bun.file(`${cwd}/bundle.env`)
+    if (await bundleEnv.exists()) {
+        await Bun.$`mkdir -p ${dirname(envPath)}`.quiet()
+        await Bun.write(envPath, bundleEnv)
+    }
+
+    // 2. Connect screen — bake dist/bundle-disconnected.html before the launcher
+    // build, which inlines it via the abide:bundle-disconnected virtual.
+    await buildDisconnected({ cwd })
+
+    // 3. Launcher binary — named after the program so CFBundleExecutable matches.
+    const launcherSuffix = target.includes('windows') ? '.exe' : ''
+    const launcherPath = `${binDir}/${programName}${launcherSuffix}`
+    const launcherResult = await Bun.build({
+        entrypoints: [APP_ENTRY],
+        target: 'bun',
+        compile: { target, outfile: launcherPath },
+        plugins: serverBuildPlugins({ cwd }),
+        /*
+        Inject the worker's absolute path as a static literal. `new Worker()` is
+        embedded into the standalone binary only when its specifier is a build-time
+        literal, and a relative one would resolve against `cwd` (the consumer
+        project) rather than appEntry's directory — so the launcher passes the
+        absolute path through this define instead.
+        */
+        define: { __ABIDE_WORKER_ENTRY__: JSON.stringify(WORKER_ENTRY) },
+    })
+    exitOnBuildFailure(launcherResult)
+
+    // 4. Webview lib — built from the vendored source if needed, then copied
+    // beside the binaries (or into Frameworks on macOS) so the bundle is self-contained.
+    const libSource = await ensureWebviewLib(cwd)
+    await Bun.write(`${libDir}/${webviewLibName()}`, Bun.file(libSource))
+
+    /*
+    macOS-only: produce Contents/Resources/icon.icns from an optional project
+    icon, then write the Info.plist that makes the .app launchable from
+    Finder, wiring CFBundleIconFile when an icon was produced. A ready-made
+    src/bundle/icon.icns is used as-is; otherwise src/bundle/icon.png is
+    converted via sips + iconutil so authors don't need to make an .icns.
+    */
+    if (isMac) {
+        const icnsSource = `${cwd}/src/bundle/icon.icns`
+        const pngSource = `${cwd}/src/bundle/icon.png`
+        let hasIcon = false
+        if (await Bun.file(icnsSource).exists()) {
+            await Bun.$`mkdir -p ${resourcesDir}`.quiet()
+            await Bun.write(`${resourcesDir}/icon.icns`, Bun.file(icnsSource))
+            hasIcon = true
+        } else if (await Bun.file(pngSource).exists()) {
+            await Bun.$`mkdir -p ${resourcesDir}`.quiet()
+            hasIcon = await pngToIcns(pngSource, `${resourcesDir}/icon.icns`)
+        }
+        await Bun.write(
+            `${bundleRoot}/Contents/Info.plist`,
+            infoPlist({ name: programName, version, icon: hasIcon ? 'icon' : undefined }),
+        )
+
+        // Seal the finished bundle so it launches on other Macs — must run last,
+        // after every binary, the lib, and Info.plist are in place.
+        await signMacApp(bundleRoot, [
+            `${libDir}/${webviewLibName()}`,
+            `${binDir}/${serverBinaryFilename()}`,
+            launcherPath,
+        ])
+    }
+
+    abideLog.success(`bundled app: ${bundleRoot} (target: ${target})`)
+    return bundleRoot
+}
+
+// Reads name + version from package.json, with fallbacks when absent.
+async function readPackage(cwd: string): Promise<{ name: string | undefined; version: string }> {
+    const pkg = (await readPackageJson(cwd)) as { name?: string; version?: string } | undefined
+    return { name: pkg?.name, version: pkg?.version ?? '0.0.0' }
+}

package/src/bundleDisconnectedEntry.ts

@@ -0,0 +1,14 @@
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import Disconnected from './_virtual/bundle-disconnected-component.ts'
+
+/*
+Client entry for the bundle connect screen. Standalone — it mounts the
+disconnected component (the user's src/bundle/disconnected.abide override or the
+lib default, picked by the resolver) into #app, with no router or SSR hydration.
+buildDisconnected bundles this into a single self-contained HTML file. A compiled
+abide-ui component's default export is its mounter, so calling it mounts.
+*/
+const target = document.getElementById('app')
+if (target) {
+    Disconnected(target)
+}

package/src/checkAbide.ts

@@ -0,0 +1,77 @@
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { collectAbideDiagnostics } from './lib/ui/compile/collectAbideDiagnostics.ts'
+import { createShadowProgram } from './lib/ui/compile/createShadowProgram.ts'
+import { nearestProjectRoot } from './lib/ui/compile/nearestProjectRoot.ts'
+import type { AbideDiagnostic } from './lib/ui/compile/types/AbideDiagnostic.ts'
+
+/*
+Type-checks every `.abide` component in `cwd` through its shadow (ADR-0010) and
+prints the diagnostics against the source files with a code frame — a
+component type-check pass. Each component is grouped under its nearest tsconfig and
+checked against that project's options, so a monorepo checked at its root reports
+the same as each package checked on its own — and the same as the LSP. Returns
+the error count so the CLI can set its exit code.
+*/
+export async function checkAbide({ cwd }: { cwd: string }): Promise<number> {
+    const diagnostics = collectByProject(cwd)
+    const byFile = new Map<string, AbideDiagnostic[]>()
+    for (const diagnostic of diagnostics) {
+        const bucket = byFile.get(diagnostic.file) ?? []
+        bucket.push(diagnostic)
+        byFile.set(diagnostic.file, bucket)
+    }
+
+    for (const [file, fileDiagnostics] of byFile) {
+        const text = (await Bun.file(file).text()).replaceAll('\r\n', '\n')
+        for (const diagnostic of fileDiagnostics.toSorted((a, b) => a.start - b.start)) {
+            printDiagnostic(file, text, diagnostic)
+        }
+    }
+
+    const errors = diagnostics.filter(
+        (diagnostic) => diagnostic.category === ts.DiagnosticCategory.Error,
+    ).length
+    const relative = byFile.size
+    console.log(
+        errors === 0
+            ? `\n[abide check] no type errors in ${relative} component${relative === 1 ? '' : 's'}`
+            : `\n[abide check] ${errors} error${errors === 1 ? '' : 's'} in ${relative} file${relative === 1 ? '' : 's'}`,
+    )
+    return errors
+}
+
+/* Groups every `.abide` under `cwd` by its nearest tsconfig and type-checks each
+   project's components against that project's options, then concatenates the
+   diagnostics. Imported components from another project resolve on demand through
+   the host, so the per-project root set stays each project's own files. */
+function collectByProject(cwd: string): AbideDiagnostic[] {
+    const byProject = new Map<string, string[]>()
+    for (const relative of new Bun.Glob('**/*.abide').scanSync({ cwd, onlyFiles: true })) {
+        if (relative.includes('node_modules')) {
+            continue
+        }
+        const path = resolve(cwd, relative)
+        const root = nearestProjectRoot(path, cwd)
+        byProject.set(root, [...(byProject.get(root) ?? []), path])
+    }
+    return [...byProject].flatMap(([root, paths]) =>
+        collectAbideDiagnostics(createShadowProgram(root, paths)),
+    )
+}
+
+/* Renders one diagnostic as `path:line:col severity message` plus the offending
+   line and a caret underline spanning the mapped range. */
+function printDiagnostic(file: string, text: string, diagnostic: AbideDiagnostic): void {
+    const before = text.slice(0, diagnostic.start)
+    const lineNumber = before.split('\n').length
+    const column = diagnostic.start - (before.lastIndexOf('\n') + 1)
+    const lineText = text.split('\n')[lineNumber - 1] ?? ''
+    const severity = diagnostic.category === ts.DiagnosticCategory.Error ? 'error' : 'warning'
+    const gutter = String(lineNumber)
+    console.log(`\n${file}:${lineNumber}:${column + 1} ${severity}  ${diagnostic.message}`)
+    console.log(`  ${gutter} | ${lineText}`)
+    console.log(
+        `  ${' '.repeat(gutter.length)} | ${' '.repeat(column)}${'^'.repeat(Math.max(1, diagnostic.length))}`,
+    )
+}

package/src/cliEntry.ts

@@ -0,0 +1,25 @@
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { banner, footer } from './_virtual/cli-chrome.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import manifest from './_virtual/cli-manifest.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import programName from './_virtual/cli-name.ts'
+import { runCli } from './lib/cli/runCli.ts'
+
+/*
+Standalone CLI binary entry. Compiled with `bun build --compile` into
+`dist/cli` (or `dist/cli-thin/<platform>/` for cross-builds). The CLI is
+a thin remote client — no handler code is bundled; it talks to a running
+server over HTTP (ABIDE_APP_URL at runtime). The bundler emits:
+  - abide:cli-manifest — the per-rpc manifest (method, url, jsonSchema)
+  - abide:cli-name     — the program name from package.json
+  - abide:cli-chrome   — optional banner/footer text from src/cli/
+*/
+const exitCode = await runCli({
+    programName,
+    manifest,
+    banner,
+    footer,
+    argv: process.argv.slice(2),
+})
+process.exit(exitCode)

package/src/clientBuildPlugins.ts

@@ -0,0 +1,33 @@
+import type { BunPlugin } from 'bun'
+import { abideResolverPlugin } from './abideResolverPlugin.ts'
+import { abideLog } from './lib/shared/abideLog.ts'
+import { isModuleNotFound } from './lib/shared/isModuleNotFound.ts'
+import { abideUiPlugin } from './lib/ui/compile/abideUiPlugin.ts'
+
+/*
+The client-target Bun.build plugin chain shared by the page bundle (build) and
+the bundle connect screen (buildDisconnected): the abide-ui `.abide` loader,
+abide's virtual-module resolver, and the optional Tailwind plugin. Tailwind is an
+optional peer — a genuine "not installed" builds without it, but any other load
+error surfaces (a plugin that loaded then threw on a real misconfig must not
+silently ship unstyled). `tailwindWarning` names what each caller builds without
+when Tailwind is absent.
+*/
+export async function clientBuildPlugins({
+    cwd,
+    tailwindWarning,
+}: {
+    cwd: string
+    tailwindWarning: string
+}): Promise<BunPlugin[]> {
+    const plugins: BunPlugin[] = [abideUiPlugin, abideResolverPlugin({ cwd, target: 'client' })]
+    try {
+        plugins.push((await import('bun-plugin-tailwind')).default)
+    } catch (error) {
+        if (!isModuleNotFound(error)) {
+            throw error
+        }
+        abideLog.warn(tailwindWarning)
+    }
+    return plugins
+}

package/src/clientEntry.ts

@@ -0,0 +1,17 @@
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { layouts } from './_virtual/layouts.ts'
+// @ts-expect-error virtual module resolved by abideResolverPlugin
+import { pages } from './_virtual/pages.ts'
+import type { RouteLoader } from './lib/ui/runtime/types/RouteLoader.ts'
+import { startClient } from './lib/ui/startClient.ts'
+
+/*
+The SSR client entry. The pages/layouts manifests are
+`{ route: () => import(page.abide) }` / `{ dir: () => import(layout.abide) }`; hand
+the loaders straight to abide-ui's startClient — the router imports each route's
+chunk (and its layout chunks) only when first visited, so the initial load downloads
+just the current route's chain (plus the entry), not every page up front. startClient
+also seeds the cache from __SSR__, installs the base, and adopts the server-rendered
+#app for the current route.
+*/
+startClient(pages as Record<string, RouteLoader>, layouts as Record<string, RouteLoader>)

package/src/compile.ts

@@ -0,0 +1,63 @@
+import { build } from './build.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 type { CompileTarget } from './lib/shared/types/CompileTarget.ts'
+import { serverBuildPlugins } from './serverBuildPlugins.ts'
+
+const SERVER_ENTRY = new URL('./serverEntry.ts', import.meta.url).pathname
+
+/*
+Produces a standalone Bun executable for the server. Runs the client `build`
+first so the resolver plugin can embed the gzip-compressed assets into
+the binary, then invokes Bun.build in compile mode against the server
+entry. Defaults
+the target to the host platform and appends `.exe` for windows targets.
+Returns the path of the emitted binary; exits the process on build failure.
+*/
+// @readme plumbing
+export async function compile({
+    cwd = process.cwd(),
+    target = detectTarget(),
+    outfile,
+    buildClient = true,
+}: {
+    cwd?: string
+    target?: CompileTarget
+    outfile?: string
+    /*
+    Skip the client `build` (which clears dist). Set false when the caller already
+    built the platform-independent client once and is compiling several server
+    binaries against it — e.g. `abide cli` co-shipping a per-platform server beside
+    each CLI binary — so the shared `dist/_app` isn't wiped between targets.
+    */
+    buildClient?: boolean
+} = {}): Promise<string> {
+    if (buildClient) {
+        await build({ cwd })
+    }
+
+    const outPath = outfile ?? `${cwd}/dist/app${exeSuffix(target)}`
+
+    const result = await Bun.build({
+        entrypoints: [SERVER_ENTRY],
+        target: 'bun',
+        format: 'esm',
+        minify: true,
+        /*
+        Bytecode embeds precompiled JS module metadata directly into the
+        standalone binary, dramatically cutting cold-start time for large
+        apps. Requires `target: 'bun'` + an explicit `format` because the
+        default for `bytecode` alone is CommonJS; we need ESM bytecode.
+        */
+        bytecode: true,
+        compile: { target, outfile: outPath },
+        plugins: serverBuildPlugins({ cwd, embedAssets: true }),
+    })
+
+    exitOnBuildFailure(result)
+
+    abideLog.success(`compiled standalone binary: ${outPath} (target: ${target})`)
+    return outPath
+}