broapp 0.1.0

package/src/cli/dev.ts

@@ -0,0 +1,158 @@
+/**
+ * `broapp dev` — one command that watches, rebuilds and restarts.
+ *
+ * ## Why there is no hot module replacement
+ *
+ * HMR needs a channel the page can pull new modules over. In a Broapp
+ * application there is exactly one such channel — the authenticated Brobridge
+ * bridge — and every other route is a `404`, on purpose. The usual shortcut is
+ * a second dev server on another port with permissive CORS, which is precisely
+ * the thing this starter must not do: it would serve the application from an
+ * unauthenticated origin, and the development build would stop resembling the
+ * shipped one in the way that matters most.
+ *
+ * So the workflow here is rebuild-and-reload, and it is honest about it. A
+ * change to UI code rebuilds the page and restarts the host, and the browser
+ * tab reconnects. Reload cost is roughly the bundle time plus a page load,
+ * which for a starter-sized UI is well under a second.
+ *
+ * ## Why the browser opens only once
+ *
+ * A restart mints a new one-time launch token, so the old tab's cookie is for
+ * a host that no longer exists — Brobridge sessions do not survive the process
+ * that minted them, and pretending otherwise would be exactly the "silent
+ * resume" the spec warns against. `broapp dev` therefore opens the browser on
+ * the first start only and, on every restart afterwards, prints the fresh
+ * launch URL for the developer to reload with. A rebuild does not spawn a tab.
+ */
+import { watch } from 'node:fs';
+import { existsSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+
+import { buildPage } from './build-page.ts';
+import type { ResolvedConfig } from './config.ts';
+
+/** Options for {@link runDev}. */
+export interface DevOptions {
+  readonly config: ResolvedConfig;
+  /** Directories to watch. Default: the whole of `src`. */
+  readonly watchDirs?: readonly string[];
+  /** Open a browser on the first successful start. Default `true`. */
+  readonly open?: boolean;
+  /** Debounce for filesystem events. Default 120 ms. */
+  readonly debounceMs?: number;
+}
+
+/** Run the development loop. Resolves when the developer stops it. */
+export async function runDev(options: DevOptions): Promise<number> {
+  const { config } = options;
+  const debounceMs = options.debounceMs ?? 120;
+  const watchDirs = (options.watchDirs ?? ['src']).map((dir) => resolve(config.root, dir));
+
+  let child: ReturnType<typeof Bun.spawn> | null = null;
+  let generation = 0;
+  let restarting: Promise<void> = Promise.resolve();
+  let stopped = false;
+  let firstStart = true;
+
+  const stopChild = async (): Promise<void> => {
+    const current = child;
+    child = null;
+    if (current === null) return;
+    // SIGTERM lets the host run its shutdown hook — close the database, end
+    // streams — before the listener goes. A host that ignores it gets 3 s.
+    current.kill('SIGTERM');
+    const deadline = Bun.sleep(3_000).then(() => 'timeout' as const);
+    const exited = await Promise.race([current.exited, deadline]);
+    if (exited === 'timeout') current.kill('SIGKILL');
+  };
+
+  const cycle = async (): Promise<void> => {
+    const mine = (generation += 1);
+    await stopChild();
+    if (stopped || mine !== generation) return;
+
+    const started = Date.now();
+    try {
+      const page = await buildPage({
+        root: config.root,
+        entry: config.uiEntry,
+        template: config.uiTemplate,
+        outFile: config.pageOut,
+        minify: false,
+        csp: config.csp,
+      });
+      if (stopped || mine !== generation) return;
+      console.log(
+        `[broapp] ui ${(page.bytes / 1024).toFixed(0)} KiB in ${String(Date.now() - started)} ms`,
+      );
+    } catch (cause) {
+      console.error(`[broapp] build failed:\n${String(cause instanceof Error ? cause.message : cause)}`);
+      console.error('[broapp] waiting for a change…');
+      return;
+    }
+
+    if (stopped || mine !== generation) return;
+    child = Bun.spawn(['bun', 'run', resolve(config.root, config.hostEntry)], {
+      cwd: config.root,
+      stdout: 'inherit',
+      stderr: 'inherit',
+      env: {
+        ...process.env,
+        // The host opens the browser itself on a cold start only. On a restart
+        // the developer already has a tab; a second one per save is noise.
+        BROAPP_OPEN_BROWSER: firstStart && options.open !== false ? '1' : '0',
+        // A dev host that exits because the tab is momentarily gone would race
+        // every restart. The developer stops it with Ctrl+C.
+        BROAPP_LIFECYCLE: 'background',
+        BROAPP_DEV: '1',
+      },
+    });
+    if (!firstStart) {
+      console.log('[broapp] host restarted — reload the tab (its previous session ended with the old process)');
+    }
+    firstStart = false;
+  };
+
+  const queue = (): void => {
+    restarting = restarting.then(cycle, cycle);
+  };
+
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const bump = (): void => {
+    if (timer !== null) clearTimeout(timer);
+    timer = setTimeout(queue, debounceMs);
+  };
+
+  const watchers = watchDirs
+    .filter((dir) => existsSync(dir))
+    .map((dir) =>
+      watch(dir, { recursive: true }, (_event, filename) => {
+        if (filename === null) return;
+        // Ignore the artefact this loop writes, or every build triggers another.
+        const written = relative(dir, resolve(config.root, config.pageOut));
+        if (filename === written || filename.startsWith(`${dirname(written)}/`)) return;
+        if (!/\.(?:tsx?|jsx?|css|html|json)$/.test(filename)) return;
+        console.log(`[broapp] changed: ${join(relative(config.root, dir), filename)}`);
+        bump();
+      }),
+    );
+
+  if (watchers.length === 0) {
+    console.warn(`[broapp] nothing to watch under ${watchDirs.join(', ')}`);
+  }
+
+  queue();
+
+  return await new Promise<number>((resolveExit) => {
+    const shutdown = (): void => {
+      if (stopped) return;
+      stopped = true;
+      if (timer !== null) clearTimeout(timer);
+      for (const watcher of watchers) watcher.close();
+      void restarting.then(stopChild).then(() => resolveExit(0));
+    };
+    process.on('SIGINT', shutdown);
+    process.on('SIGTERM', shutdown);
+  });
+}

package/src/cli/index.ts

@@ -0,0 +1,17 @@
+/**
+ * `broapp/build` — the build tooling, as a library.
+ *
+ * The `broapp` command is the usual way in. This entry point exists so a
+ * project with an unusual pipeline can call the same functions directly
+ * instead of reimplementing them.
+ */
+export { buildPage } from './build-page.ts';
+export type { BuildPageOptions, BuildPageResult } from './build-page.ts';
+export { buildBinary } from './build-binary.ts';
+export type { BuildBinaryOptions, BuiltBinary } from './build-binary.ts';
+export { currentTarget, findTarget, TARGETS } from './targets.ts';
+export type { Target } from './targets.ts';
+export { defineConfig, loadConfig } from './config.ts';
+export type { BroappConfig, ResolvedConfig } from './config.ts';
+export { runDev } from './dev.ts';
+export type { DevOptions } from './dev.ts';

package/src/cli/main.ts

@@ -0,0 +1,183 @@
+#!/usr/bin/env bun
+/**
+ * The `broapp` command.
+ *
+ * Three subcommands, and no plugin system: `dev`, `build`, and `build --page`
+ * for the rare case where only the UI needs rebuilding.
+ */
+import { runDev } from './dev.ts';
+import { buildPage } from './build-page.ts';
+import { buildBinary } from './build-binary.ts';
+import { loadConfig } from './config.ts';
+import { currentTarget, TARGETS } from './targets.ts';
+
+const VERSION = '0.1.0';
+
+const USAGE = `broapp ${VERSION} — build tooling for local Bun + Brobridge applications
+
+Usage:
+  broapp dev [--no-open]              Watch, rebuild and restart the host
+  broapp build [options]              Build the UI and compile the executable
+  broapp build --page                 Build the UI document only
+
+Build options:
+  --target <id>       Compile for one target. Repeatable. Default: this machine.
+  --all-targets       Compile every supported target.
+  --out-dir <path>    Where executables go. Default: release
+  --no-minify         Keep the bundle readable.
+  --no-bytecode       Skip bytecode compilation.
+
+Common:
+  -h, --help          Show this message.
+  -v, --version       Show the version.
+
+Targets: ${TARGETS.map((target) => target.id).join(', ')}
+
+Cross-compiled binaries are built, not run. Only a binary compiled for the
+machine that built it has been executed by this command.`;
+
+interface Flags {
+  readonly command: string;
+  readonly targets: string[];
+  readonly allTargets: boolean;
+  readonly outDir: string | undefined;
+  readonly pageOnly: boolean;
+  readonly minify: boolean;
+  readonly bytecode: boolean;
+  readonly open: boolean;
+}
+
+function parse(argv: readonly string[]): Flags | { readonly help: true } | { readonly version: true } {
+  const targets: string[] = [];
+  let command = '';
+  let allTargets = false;
+  let outDir: string | undefined;
+  let pageOnly = false;
+  let minify = true;
+  let bytecode = true;
+  let open = true;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === undefined) continue;
+    switch (argument) {
+      case '-h':
+      case '--help':
+        return { help: true };
+      case '-v':
+      case '--version':
+        return { version: true };
+      case '--all-targets':
+        allTargets = true;
+        break;
+      case '--page':
+        pageOnly = true;
+        break;
+      case '--no-minify':
+        minify = false;
+        break;
+      case '--no-bytecode':
+        bytecode = false;
+        break;
+      case '--no-open':
+        open = false;
+        break;
+      case '--target': {
+        const value = argv[index + 1];
+        if (value === undefined) throw new Error('--target needs a value');
+        targets.push(value);
+        index += 1;
+        break;
+      }
+      case '--out-dir': {
+        const value = argv[index + 1];
+        if (value === undefined) throw new Error('--out-dir needs a value');
+        outDir = value;
+        index += 1;
+        break;
+      }
+      default:
+        if (argument.startsWith('-')) throw new Error(`unknown option ${JSON.stringify(argument)}`);
+        if (command === '') command = argument;
+        else throw new Error(`unexpected argument ${JSON.stringify(argument)}`);
+    }
+  }
+  return { command, targets, allTargets, outDir, pageOnly, minify, bytecode, open };
+}
+
+async function main(): Promise<number> {
+  let flags: ReturnType<typeof parse>;
+  try {
+    flags = parse(process.argv.slice(2));
+  } catch (cause) {
+    console.error(String(cause instanceof Error ? cause.message : cause));
+    console.error('\nRun `broapp --help`.');
+    return 2;
+  }
+
+  if ('help' in flags) {
+    console.log(USAGE);
+    return 0;
+  }
+  if ('version' in flags) {
+    console.log(VERSION);
+    return 0;
+  }
+  if (flags.command === '') {
+    console.log(USAGE);
+    return 2;
+  }
+
+  const config = await loadConfig();
+
+  if (flags.command === 'dev') {
+    return await runDev({ config, open: flags.open });
+  }
+
+  if (flags.command === 'build') {
+    const page = await buildPage({
+      root: config.root,
+      entry: config.uiEntry,
+      template: config.uiTemplate,
+      outFile: config.pageOut,
+      minify: flags.minify,
+      csp: config.csp,
+    });
+    console.log(`ui  ${config.pageOut}  ${(page.bytes / 1024).toFixed(1)} KiB`);
+    if (flags.pageOnly) return 0;
+
+    const targets = flags.allTargets
+      ? TARGETS.map((target) => target.id)
+      : flags.targets.length > 0
+        ? flags.targets
+        : [currentTarget().id];
+
+    const built = await buildBinary({
+      root: config.root,
+      entry: config.hostEntry,
+      name: config.binaryName,
+      outDir: flags.outDir ?? config.outDir,
+      targets,
+      minify: flags.minify,
+      bytecode: flags.bytecode && config.bytecode,
+    });
+    for (const binary of built) {
+      console.log(
+        `bin ${binary.path}  ${(binary.bytes / 1024 / 1024).toFixed(1)} MiB  ${binary.target.label}${binary.native ? '' : '  (cross-compiled, not run)'}`,
+      );
+    }
+    return 0;
+  }
+
+  console.error(`unknown command ${JSON.stringify(flags.command)}\n`);
+  console.error(USAGE);
+  return 2;
+}
+
+main().then(
+  (code) => process.exit(code),
+  (cause: unknown) => {
+    console.error(String(cause instanceof Error ? (cause.stack ?? cause.message) : cause));
+    process.exit(1);
+  },
+);

package/src/cli/targets.ts

@@ -0,0 +1,51 @@
+/**
+ * Compilation targets.
+ *
+ * These are Bun's `--target=bun-<platform>-<arch>` names. Cross-compilation
+ * works for pure-JavaScript dependency trees; it does not make a native addon
+ * portable, and `bun:sqlite` in particular links a platform SQLite into the
+ * produced executable — so a cross-compiled binary is a build artifact that
+ * has not been *run*. Broapp's release workflow therefore separates "compiled"
+ * from "smoke-tested", and only claims the second where a matching runner
+ * exists.
+ */
+
+/** A supported compilation target. */
+export interface Target {
+  /** Bun's target name, without the `bun-` prefix. */
+  readonly id: string;
+  /** Executable suffix. */
+  readonly ext: '' | '.exe';
+  /** Human-readable label for release notes. */
+  readonly label: string;
+}
+
+/** Every target Broapp builds by default. */
+export const TARGETS: readonly Target[] = [
+  { id: 'darwin-arm64', ext: '', label: 'macOS (Apple silicon)' },
+  { id: 'darwin-x64', ext: '', label: 'macOS (Intel)' },
+  { id: 'linux-x64', ext: '', label: 'Linux x86-64 (glibc)' },
+  { id: 'linux-arm64', ext: '', label: 'Linux arm64 (glibc)' },
+  { id: 'linux-x64-musl', ext: '', label: 'Linux x86-64 (musl / Alpine)' },
+  { id: 'windows-x64', ext: '.exe', label: 'Windows x64' },
+];
+
+/** Look a target up by id. */
+export function findTarget(id: string): Target | undefined {
+  return TARGETS.find((target) => target.id === id);
+}
+
+/** The target matching the machine running the build. */
+export function currentTarget(): Target {
+  const arch = process.arch === 'arm64' ? 'arm64' : 'x64';
+  const platform =
+    process.platform === 'darwin' ? 'darwin' : process.platform === 'win32' ? 'windows' : 'linux';
+  const id = platform === 'windows' ? 'windows-x64' : `${platform}-${arch}`;
+  const found = findTarget(id);
+  if (found === undefined) {
+    throw new Error(
+      `no Broapp target for ${process.platform}/${process.arch}. Supported: ${TARGETS.map((t) => t.id).join(', ')}`,
+    );
+  }
+  return found;
+}

package/src/client/client.ts

@@ -0,0 +1,203 @@
+/**
+ * The browser side of a contract.
+ *
+ * A thin, typed wrapper over `@brobridgejs/client`. It adds four things and
+ * nothing else: contract-derived types, output validation, the error
+ * translation described in `shared/errors.ts`, and a stream subscription with
+ * a `cancel()` that really cancels.
+ *
+ * Importing this module pulls in the contract, which is data. It does not pull
+ * in anything under `host/` — that separation is what keeps host code and host
+ * configuration out of the browser bundle, and there is a test that asserts it.
+ */
+import type { Bridge, BridgeState, ConnectOptions, Unsubscribe } from '@brobridgejs/client';
+import { connect } from '@brobridgejs/client';
+
+import type {
+  AnyContract,
+  OperationInput,
+  OperationName,
+  OperationOutput,
+  StreamEvent,
+  StreamName,
+  StreamParams,
+} from '../shared/contract.ts';
+import { BroappError, fromTransportError } from '../shared/errors.ts';
+import { NdjsonDecoder } from '../shared/ndjson.ts';
+
+export type { BridgeState };
+
+/** Callbacks for a stream subscription. */
+export interface StreamCallbacks<E> {
+  onEvent(event: E): void;
+  /** The stream finished normally. Not called after `onError` or a cancel. */
+  onDone?(): void;
+  /** The stream failed. Not called for a cancellation the caller asked for. */
+  onError?(error: BroappError): void;
+}
+
+/** A running stream subscription. */
+export interface Subscription {
+  /**
+   * Stop the stream and tell the host to stop producing.
+   *
+   * This sends a `CANCEL` frame. Simply dropping the subscription would not:
+   * abandoning an async iterator does not cancel the stream underneath it, and
+   * the host would keep computing until it finished.
+   */
+  cancel(): void;
+  /** True once `cancel()` ran or the stream ended. */
+  readonly closed: boolean;
+}
+
+/** A connected, contract-typed client. */
+export interface BroappClient<C extends AnyContract> {
+  /** Invoke an operation. Rejects with {@link BroappError}. */
+  call<K extends OperationName<C>>(
+    name: K,
+    input: OperationInput<C, K>,
+  ): Promise<OperationOutput<C, K>>;
+
+  /** Open a stream. Returns as soon as the stream is open. */
+  subscribe<K extends StreamName<C>>(
+    name: K,
+    params: StreamParams<C, K>,
+    callbacks: StreamCallbacks<StreamEvent<C, K>>,
+  ): Promise<Subscription>;
+
+  /** What the connection is doing right now. */
+  readonly state: BridgeState;
+  /** Subscribe to connection state changes. */
+  onState(listener: (state: BridgeState) => void): Unsubscribe;
+  /** Round-trip time to the host, in milliseconds. */
+  ping(): Promise<number>;
+  /** The underlying Brobridge client, for anything this wrapper does not cover. */
+  readonly bridge: Bridge;
+  /** Disconnect. */
+  close(): Promise<void>;
+}
+
+/** Options for {@link createClient}. */
+export interface CreateClientOptions extends ConnectOptions {
+  /**
+   * The URL to connect to, including any `?bt=` launch token. Defaults to
+   * `location.href`, which is where the token is on first load.
+   */
+  readonly url?: string;
+}
+
+/**
+ * Connect to the host that served this page.
+ *
+ * The launch token in `location.href` is redeemed once by Brobridge and never
+ * retained. Reconnection is on by default and carries the session cookie, so a
+ * dropped socket recovers without a second token.
+ */
+export async function createClient<C extends AnyContract>(
+  contract: C,
+  options: CreateClientOptions = {},
+): Promise<BroappClient<C>> {
+  const { url, ...connectOptions } = options;
+  const bridge = await connect(url ?? globalThis.location.href, connectOptions);
+
+  return {
+    bridge,
+    get state() {
+      return bridge.state;
+    },
+    onState(listener) {
+      return bridge.on('state', listener);
+    },
+    ping: () => bridge.ping(),
+    close: () => bridge.close(),
+
+    async call(name, input) {
+      let raw: unknown;
+      try {
+        raw = await bridge.call(name, input);
+      } catch (cause) {
+        throw fromTransportError(cause);
+      }
+      const spec = contract.operations[name];
+      if (spec === undefined) throw new BroappError('internal', 'unknown operation');
+      try {
+        // The host is trusted, so this is a contract check rather than a
+        // security boundary: it catches a host and a browser built from
+        // different versions of the contract, which otherwise shows up as a
+        // confusing render bug far from its cause.
+        return spec.output.parse(raw) as OperationOutput<C, typeof name>;
+      } catch {
+        throw new BroappError('internal', 'The host returned a response this app did not expect.');
+      }
+    },
+
+    async subscribe(name, params, callbacks) {
+      const spec = contract.streams[name];
+      if (spec === undefined) throw new BroappError('internal', 'unknown stream');
+
+      // Params are checked here as well as on the host, and the two checks do
+      // different jobs. The host's is the security boundary and is not
+      // optional. This one is for the developer: a stream's `OPEN` is
+      // acknowledged before its handler runs, so a host-side rejection arrives
+      // *after* `subscribe` has already resolved — through `onError`, one tick
+      // later. Checking here as well means an obviously wrong parameter fails
+      // where the call was made.
+      try {
+        spec.params.parse(params);
+      } catch (cause) {
+        throw new BroappError(
+          'invalid_input',
+          cause instanceof Error ? cause.message : 'invalid stream parameters',
+          cause,
+        );
+      }
+
+      let stream: Awaited<ReturnType<Bridge['openStream']>>;
+      try {
+        stream = await bridge.openStream(name, params as Readonly<Record<string, unknown>>, {
+          mode: 'read',
+        });
+      } catch (cause) {
+        throw fromTransportError(cause);
+      }
+
+      let cancelled = false;
+      let closed = false;
+      const decoder = new NdjsonDecoder();
+
+      const subscription: Subscription = {
+        get closed() {
+          return closed || cancelled;
+        },
+        cancel() {
+          if (cancelled || closed) return;
+          cancelled = true;
+          stream.cancel('cancelled by the user');
+        },
+      };
+
+      void (async () => {
+        try {
+          for await (const chunk of stream) {
+            if (cancelled) break;
+            for (const event of decoder.push(chunk)) {
+              callbacks.onEvent(spec.event.parse(event) as StreamEvent<C, typeof name>);
+            }
+          }
+          if (cancelled) return;
+          for (const event of decoder.flush()) {
+            callbacks.onEvent(spec.event.parse(event) as StreamEvent<C, typeof name>);
+          }
+          closed = true;
+          callbacks.onDone?.();
+        } catch (cause) {
+          closed = true;
+          if (cancelled) return;
+          callbacks.onError?.(fromTransportError(cause));
+        }
+      })();
+
+      return subscription;
+    },
+  };
+}

package/src/client/index.ts

@@ -0,0 +1,12 @@
+/** `broapp/client` — the browser client. Framework-agnostic. */
+export { createClient } from './client.ts';
+export type {
+  BridgeState,
+  BroappClient,
+  CreateClientOptions,
+  StreamCallbacks,
+  Subscription,
+} from './client.ts';
+
+export { BroappError } from '../shared/errors.ts';
+export type { PublicErrorCode } from '../shared/errors.ts';