@kingsleyweb/bun-ui 0.0.0-stage → 3.0.0-rc.2

package/lib/jobs/assets.ts

@@ -0,0 +1,448 @@
+/**
+ * The app bundle, as the server serves it: every file in memory, keyed by its
+ * hashed name, with the content type, SRI integrity and ETag worked out once.
+ *
+ * Two sources, one shape. A published package ships `dist/` (built on
+ * `prepack` by `scripts/build.ts`): `dist/manifest.json` plus the hashed files
+ * under `dist/assets/`. Inside the repo `dist/` is usually absent, so the same
+ * {@link buildAssets} runs in memory on the first request instead, once per
+ * entry, and logs one line saying so.
+ */
+import type { Logger } from "@kingsleyweb/bun-common";
+import { existsSync, mkdirSync, readFileSync, rmSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
+
+/** The package root (`packages/bun-ui`, or `node_modules/@kingsleyweb/bun-ui`). */
+export const PACKAGE_DIR = resolve(import.meta.dir, "..", "..");
+
+/** The React app's entry point, bundled by {@link buildAssets}. */
+export const DEFAULT_ENTRY = join(PACKAGE_DIR, "app", "jobs", "main.tsx");
+
+/** Where `scripts/build.ts` writes the bundle and where `jobsUi()` looks for it. */
+export const DEFAULT_DIST_DIR = join(PACKAGE_DIR, "dist", "jobs");
+
+/**
+ * Makes the error this module throws for a bad configuration (a missing
+ * entry, a corrupt `dist/`, `dev: false` with no build). It imports no domain
+ * package: each UI passes its own domain's `ConfigError` (`jobsUi()` passes
+ * bun-jobs'), so the bundle code never makes an entry need a peer.
+ */
+export type AssetsFail = (
+  message: string,
+  context: Record<string, unknown>,
+) => Error;
+
+/** The {@link AssetsFail} used when a caller passes none: a plain `Error`. */
+export const plainFail: AssetsFail = (message) => new Error(message);
+
+/** The manifest's file name inside a dist directory. */
+export const MANIFEST_FILE = "manifest.json";
+
+/** The sub-directory of a dist directory holding the hashed files. */
+export const ASSETS_DIR = "assets";
+
+/** One file of the bundle, as `dist/manifest.json` records it. */
+export interface UiManifestFile {
+  /** The `Content-Type` it is served with, e.g. `"text/javascript; charset=utf-8"`. */
+  type: string;
+  /** Its size in bytes. */
+  size: number;
+  /** Its Subresource Integrity digest, `"sha384-<base64>"`. */
+  integrity: string;
+}
+
+/** `dist/manifest.json`: what the build produced, and which files the shell links. */
+export interface UiManifest {
+  /** Shape version of the manifest. Currently `1`. */
+  version: 1;
+  /** The files the HTML shell references directly. */
+  entry: {
+    /** File name of the entry module (loaded with `<script type="module">`). */
+    js: string;
+    /** File names of every stylesheet the build emitted, in build order. */
+    css: string[];
+  };
+  /** Every file under `dist/assets/`, by file name. */
+  files: Record<string, UiManifestFile>;
+}
+
+/** One file of the bundle, held in memory. */
+export interface UiAsset extends UiManifestFile {
+  /** The hashed file name, e.g. `"main-3kx9a2f1.js"`. It is also the URL segment. */
+  name: string;
+  /** The bytes served. */
+  body: Uint8Array<ArrayBuffer>;
+  /** A strong ETag derived from the integrity digest, quoted. */
+  etag: string;
+}
+
+/** The whole bundle, ready to serve. */
+export interface UiAssets {
+  /** The files the shell links: the entry module and the stylesheets. */
+  entry: UiManifest["entry"];
+  /** Every file, by its hashed name. */
+  files: ReadonlyMap<string, UiAsset>;
+  /** Where the bundle came from: a `dist/` directory or an in-memory build. */
+  source: "dist" | "memory";
+}
+
+/** Options for {@link buildAssets}. */
+export interface BuildAssetsOptions {
+  /** The entry point to bundle. Defaults to {@link DEFAULT_ENTRY}, the React app. */
+  entry?: string;
+  /** Minify the output. Defaults to `true`. */
+  minify?: boolean;
+  /**
+   * Source maps: `"linked"` (default) emits `.map` files the bundle points
+   * at, `"external"` emits them unreferenced, `"none"` emits none.
+   */
+  sourcemap?: "linked" | "external" | "none";
+  /**
+   * Type-check the entry and everything it imports first, with Bun.build's
+   * `check` (Bun ≥ 1.4.3; app/tsconfig.json's options), and fail the build on
+   * a type error. Defaults to `false`: `scripts/build.ts` (prepack) turns it
+   * on; the in-memory build `jobsUi()` runs on a request never does, which
+   * also keeps it off a 1.4.2 runtime. Adds about 175 ms.
+   */
+  check?: boolean;
+  /** Makes the error for a missing entry. Defaults to {@link plainFail}. */
+  fail?: AssetsFail;
+}
+
+/** Content types by extension, so both sources agree whatever Bun reports. */
+const CONTENT_TYPES: Record<string, string> = {
+  js: "text/javascript; charset=utf-8",
+  mjs: "text/javascript; charset=utf-8",
+  css: "text/css; charset=utf-8",
+  map: "application/json; charset=utf-8",
+  json: "application/json; charset=utf-8",
+  svg: "image/svg+xml",
+  png: "image/png",
+  jpg: "image/jpeg",
+  jpeg: "image/jpeg",
+  gif: "image/gif",
+  webp: "image/webp",
+  ico: "image/x-icon",
+  woff: "font/woff",
+  woff2: "font/woff2",
+  ttf: "font/ttf",
+  otf: "font/otf",
+  txt: "text/plain; charset=utf-8",
+};
+
+/** A served file name: one segment, no dot segments, nothing a URL must escape. */
+const FILE_NAME = /^[\w.~-]+$/;
+
+/** The `Content-Type` for a file name, falling back to what the bundler reported. */
+export function contentTypeFor(name: string, reported?: string): string {
+  const extension = name.slice(name.lastIndexOf(".") + 1).toLowerCase();
+  return (
+    CONTENT_TYPES[extension] ??
+    reported?.replace(/;\s*/, "; ") ??
+    "application/octet-stream"
+  );
+}
+
+/** The SRI digest of some bytes, `"sha384-<base64>"`. */
+export function integrityOf(bytes: Uint8Array): string {
+  return `sha384-${new Bun.CryptoHasher("sha384").update(bytes).digest("base64")}`;
+}
+
+/** Wraps bytes as a served asset. */
+function toAsset(
+  name: string,
+  body: Uint8Array<ArrayBuffer>,
+  type: string,
+): UiAsset {
+  const integrity = integrityOf(body);
+  return {
+    name,
+    body,
+    type,
+    size: body.byteLength,
+    integrity,
+    // The digest already identifies the bytes; the prefix and padding are noise.
+    etag: `"${integrity.slice("sha384-".length, "sha384-".length + 32)}"`,
+  };
+}
+
+/**
+ * Bundles the app with `Bun.build`, in memory: browser target, content-hashed
+ * names (`[name]-[hash].[ext]`), code splitting, `NODE_ENV=production`.
+ * Throws with the bundler's messages when the build fails.
+ */
+export async function buildAssets(
+  options: BuildAssetsOptions = {},
+): Promise<UiAssets> {
+  const entry = options.entry ?? DEFAULT_ENTRY;
+  if (!existsSync(entry)) {
+    throw (options.fail ?? plainFail)(
+      `bun-ui: the app entry ${entry} does not exist`,
+      { entry },
+    );
+  }
+  const sourcemap = options.sourcemap ?? "linked";
+  const result = await Bun.build({
+    entrypoints: [entry],
+    target: "browser",
+    format: "esm",
+    minify: options.minify ?? true,
+    splitting: true,
+    sourcemap,
+    naming: {
+      entry: "[name]-[hash].[ext]",
+      chunk: "[name]-[hash].[ext]",
+      asset: "[name]-[hash].[ext]",
+    },
+    define: { "process.env.NODE_ENV": JSON.stringify("production") },
+    throw: false,
+    // Spread rather than written out: `@types/bun` 1.4.2 pins bun-types
+    // 1.4.2, whose `BuildConfig` predates `check`. Write `check` directly
+    // once `@types/bun` 1.4.3 is the floor.
+    ...(options.check === true ? { check: true } : {}),
+  });
+  if (!result.success) {
+    // A type error from `check` is "TS2322: …" alone; its position says where.
+    const messages = result.logs.map((log) =>
+      log.position === null
+        ? log.message
+        : `${log.position.file}:${log.position.line}:${log.position.column}: ${log.message}`,
+    );
+    throw new Error(
+      `bun-ui: building ${entry} failed:\n${messages.join("\n")}`,
+    );
+  }
+
+  const files = new Map<string, UiAsset>();
+  let js: string | undefined;
+  const css: string[] = [];
+  for (const output of result.outputs) {
+    const name = basename(output.path);
+    const body = new Uint8Array(await output.arrayBuffer());
+    files.set(name, toAsset(name, body, contentTypeFor(name, output.type)));
+    if (output.kind === "entry-point" && name.endsWith(".js")) {
+      js = name;
+    } else if (name.endsWith(".css")) {
+      css.push(name);
+    }
+  }
+  if (js === undefined) {
+    throw new Error(`bun-ui: building ${entry} produced no entry module`);
+  }
+  return {
+    entry: { js, css: entryStylesheets(js, css) },
+    files,
+    source: "memory",
+  };
+}
+
+/** A hashed file name without its hash and extension: `main-3kx9.css` → `main`. */
+function stemOf(name: string): string {
+  return name.replace(/-[a-z0-9]+\.[a-z]+$/, "");
+}
+
+/**
+ * The stylesheets the shell links. With code splitting, Bun emits the entry's
+ * stylesheet holding every rule, lazily imported ones included, plus one per
+ * split chunk repeating that chunk's rules, and marks them all "asset". The
+ * entry's is the one named after the entry module; linking the others too
+ * would download the same rules twice. If none matches (a bundler change),
+ * every stylesheet is linked, which is redundant but never unstyled.
+ */
+export function entryStylesheets(js: string, css: readonly string[]): string[] {
+  const own = css.filter((name) => stemOf(name) === stemOf(js));
+  return own.length > 0 ? own : [...css];
+}
+
+/** The manifest describing a bundle. */
+export function manifestOf(assets: UiAssets): UiManifest {
+  const files: Record<string, UiManifestFile> = {};
+  for (const [name, file] of assets.files) {
+    files[name] = {
+      type: file.type,
+      size: file.size,
+      integrity: file.integrity,
+    };
+  }
+  return {
+    version: 1,
+    entry: { js: assets.entry.js, css: [...assets.entry.css] },
+    files,
+  };
+}
+
+/**
+ * Writes a bundle as a dist directory: the files under `<dir>/assets/` (the
+ * directory is emptied first, so stale hashes do not accumulate) and
+ * `<dir>/manifest.json`. Returns the manifest written.
+ */
+export async function writeAssets(
+  assets: UiAssets,
+  dir: string = DEFAULT_DIST_DIR,
+): Promise<UiManifest> {
+  const assetsDir = join(dir, ASSETS_DIR);
+  rmSync(assetsDir, { recursive: true, force: true });
+  mkdirSync(assetsDir, { recursive: true });
+  for (const [name, file] of assets.files) {
+    await Bun.write(join(assetsDir, name), file.body);
+  }
+  const manifest = manifestOf(assets);
+  await Bun.write(
+    join(dir, MANIFEST_FILE),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+  );
+  return manifest;
+}
+
+/** Whether `dir` holds a built bundle (its manifest exists). */
+export function hasDist(dir: string = DEFAULT_DIST_DIR): boolean {
+  return existsSync(join(dir, MANIFEST_FILE));
+}
+
+/** A string property of an unknown value, or `undefined`. */
+function stringField(value: unknown, key: string): string | undefined {
+  const field =
+    typeof value === "object" && value !== null
+      ? (value as Record<string, unknown>)[key]
+      : undefined;
+  return typeof field === "string" ? field : undefined;
+}
+
+/**
+ * Reads a dist directory into memory, synchronously. Every file the manifest
+ * lists must exist and match its recorded integrity — a half-copied or
+ * hand-edited dist fails here, with the file named, rather than as a browser
+ * refusing a script over SRI.
+ */
+export function loadDistAssets(
+  dir: string = DEFAULT_DIST_DIR,
+  fail: AssetsFail = plainFail,
+): UiAssets {
+  const manifestPath = join(dir, MANIFEST_FILE);
+  const corrupt = (why: string): Error =>
+    fail(
+      `bun-ui: ${manifestPath} is not a usable build (${why}); rebuild it with \`bun scripts/build.ts\``,
+      { dir },
+    );
+  let manifest: unknown;
+  try {
+    manifest = JSON.parse(readFileSync(manifestPath, "utf8"));
+  } catch (error) {
+    throw corrupt(error instanceof Error ? error.message : String(error));
+  }
+  const record = manifest as Partial<UiManifest> | null;
+  if (
+    typeof record !== "object" ||
+    record === null ||
+    record.version !== 1 ||
+    typeof record.files !== "object" ||
+    record.files === null
+  ) {
+    throw corrupt("unknown manifest version or shape");
+  }
+  const js = stringField(record.entry, "js");
+  const cssList = (record.entry as { css?: unknown } | undefined)?.css;
+  if (
+    js === undefined ||
+    !Array.isArray(cssList) ||
+    !cssList.every((name) => typeof name === "string")
+  ) {
+    throw corrupt("no entry");
+  }
+
+  const files = new Map<string, UiAsset>();
+  for (const [name, info] of Object.entries(record.files)) {
+    if (!FILE_NAME.test(name) || name === "." || name === "..") {
+      throw corrupt(`bad file name ${JSON.stringify(name)}`);
+    }
+    let body: Uint8Array<ArrayBuffer>;
+    try {
+      body = new Uint8Array(readFileSync(join(dir, ASSETS_DIR, name)));
+    } catch {
+      throw corrupt(`${name} is missing`);
+    }
+    const asset = toAsset(
+      name,
+      body,
+      stringField(info, "type") ?? contentTypeFor(name),
+    );
+    if (asset.integrity !== stringField(info, "integrity")) {
+      throw corrupt(`${name} does not match its recorded integrity`);
+    }
+    files.set(name, asset);
+  }
+  for (const name of [js, ...cssList]) {
+    if (!files.has(name)) {
+      throw corrupt(`the entry file ${name} is not in the manifest`);
+    }
+  }
+  return { entry: { js, css: cssList }, files, source: "dist" };
+}
+
+/** In-memory builds, by entry path: each entry is built at most once per process. */
+const memoryBuilds = new Map<string, Promise<UiAssets>>();
+
+/**
+ * Builds an entry in memory, once per process: concurrent and later callers
+ * share the first build. A failed build is forgotten, so the next call tries
+ * again. Logs one `info` line when a build starts.
+ */
+export function buildAssetsOnce(
+  entry: string,
+  logger: Logger,
+): Promise<UiAssets> {
+  const key = resolve(entry);
+  let build = memoryBuilds.get(key);
+  if (build === undefined) {
+    logger.info(
+      "bun-ui: no dist/jobs build, bundling the app in memory (run `bun scripts/build.ts` to prebuild)",
+      { entry: key },
+    );
+    build = buildAssets({ entry: key });
+    memoryBuilds.set(key, build);
+    build.catch(() => {
+      if (memoryBuilds.get(key) === build) {
+        memoryBuilds.delete(key);
+      }
+    });
+  }
+  return build;
+}
+
+/** Where `jobsUi()` gets its bundle from, and how. */
+export interface AssetSourceOptions {
+  /** `false`: require `distDir`; `true`: always build `entry` in memory; `undefined`: dist when present, else build. */
+  dev: boolean | undefined;
+  /** The dist directory to read. */
+  distDir: string;
+  /** The entry to build in memory. */
+  entry: string;
+  /** Receives the one-line notice of an in-memory build. */
+  logger: Logger;
+  /** Makes the error for `dev: false` with no build, or a corrupt one: the UI's domain `ConfigError`. */
+  fail: AssetsFail;
+}
+
+/**
+ * Resolves the bundle source when `jobsUi()` is called. A dist directory is
+ * read synchronously right away, so a missing or corrupt one fails the call,
+ * not the first request; an in-memory build is deferred to the first request.
+ *
+ * @throws `options.fail`'s error with `dev: false` and no dist, or a corrupt dist.
+ */
+export function resolveAssetSource(
+  options: AssetSourceOptions,
+): () => Promise<UiAssets> {
+  const { dev, distDir, entry, logger, fail } = options;
+  if (dev !== true && hasDist(distDir)) {
+    const assets = Promise.resolve(loadDistAssets(distDir, fail));
+    return () => assets;
+  }
+  if (dev === false) {
+    throw fail(
+      `bun-ui: no build found at ${join(distDir, MANIFEST_FILE)} and \`dev: false\` forbids building in memory; run \`bun scripts/build.ts\` in the package, or leave \`dev\` unset`,
+      { distDir },
+    );
+  }
+  return () => buildAssetsOnce(entry, logger);
+}

package/lib/jobs/browser/config.ts

@@ -0,0 +1,65 @@
+/**
+ * The contract between `jobsUi()` (server, `lib/jobs/`) and the React app (`app/jobs/`).
+ *
+ * The server resolves this once per mount and inlines it into the HTML shell as
+ * `<script type="application/json" id="bun-jobs-ui-config" nonce="…">`. The app
+ * reads it before its first request. It must stay free of runtime imports: both
+ * sides import it, and the app side is bundled for the browser.
+ */
+
+import type { UiTheme } from "../../kit/browser/shared";
+import type { UiUnauthorized } from "./unauthorized";
+
+export type { UiTheme };
+
+/** Id of the `<script type="application/json">` element carrying {@link JobsUiConfig}. */
+export const JOBS_UI_CONFIG_ELEMENT_ID = "bun-jobs-ui-config";
+
+/** Sections of the app a mount can switch off. */
+export interface JobsUiSections {
+  /** Job/queue/runner management screens. Defaults to `true`. */
+  manage: boolean;
+  /** The OpenAPI and AsyncAPI documentation viewers. Defaults to `true`. */
+  docs: boolean;
+}
+
+/** Resolved configuration handed to the browser. Never carries secrets. */
+export interface JobsUiConfig {
+  /** Shape version of this object, bumped on a breaking change. Currently `1`. */
+  version: 1;
+  /** Page title and brand text. Defaults to `"Jobs"`. */
+  title: string;
+  /** Absolute path the UI is mounted at, no trailing slash (e.g. `"/jobs"`). Client routes live under it. */
+  basePath: string;
+  /** Path the hashed assets are served from, e.g. `"/jobs/assets"`. */
+  assetsPath: string;
+  /**
+   * Base URL of the management API with no trailing slash: a same-origin
+   * absolute path (`"/jobs-api"`) or, with `apiUrl`, a full origin-qualified URL.
+   */
+  apiBase: string;
+  /**
+   * Header every mutation must carry (any non-empty value), or `null` when the
+   * API has no CSRF header configured. Mirrors the API's `csrf.header`.
+   */
+  csrfHeader: string | null;
+  /**
+   * The API's WebSocket endpoint, when it has one: `path` is the full path
+   * (including the API basePath); `port` is set only for a dedicated-port
+   * socket. `null` when the API has no socket. `/meta` remains the authority at
+   * runtime; this lets the app connect without waiting for it.
+   */
+  websocket: { path: string; port: number | null } | null;
+  /** Full paths of the API's spec documents, or `null` when docs are off. */
+  docs: { openapi: string; asyncapi: string | null } | null;
+  /** Which sections are enabled. */
+  sections: JobsUiSections;
+  /** Initial colour scheme. */
+  theme: UiTheme;
+  /**
+   * Where an authorization failure sends the browser (`jobsUi()`'s
+   * `unauthorized`), or `null` when it is off: the app then shows each
+   * screen's own message, as before.
+   */
+  unauthorized: UiUnauthorized | null;
+}

package/lib/jobs/browser/index.ts

@@ -0,0 +1,9 @@
+/**
+ * `@kingsleyweb/bun-ui/jobs/browser`: the jobs UI's browser-safe contract,
+ * what `jobsUi()` inlines into the page and the app reads before its first
+ * request. No runtime import beyond constants and no domain package, so a
+ * browser bundle (or a host reading the injected config) may import it.
+ */
+export type { JobsUiConfig, JobsUiSections, UiTheme } from "./config";
+export { JOBS_UI_CONFIG_ELEMENT_ID } from "./config";
+export type { UiUnauthorized, UiUnauthorizedStatus } from "./unauthorized";

package/lib/jobs/browser/unauthorized.ts

@@ -0,0 +1,11 @@
+/**
+ * The `unauthorized` option's shared types, re-exported from the kit
+ * (`lib/kit/browser/unauthorized.ts`), which `docsUi()` uses too, as it does
+ * the code both run: validation and the shell's `303` (`lib/kit/unauthorized`),
+ * and the browser's redirect (`app/kit/unauthorized`). Types only, so
+ * `lib/jobs/browser` stays free of runtime imports.
+ */
+export type {
+  UiUnauthorized,
+  UiUnauthorizedStatus,
+} from "../../kit/browser/unauthorized";

package/lib/jobs/index.ts

@@ -0,0 +1,41 @@
+export {
+  ASSET_CACHE_CONTROL,
+  DEFAULT_BASE_PATH,
+  DEFAULT_TITLE,
+  jobsUi,
+} from "./jobsUi";
+/**
+ * `@kingsleyweb/bun-ui/jobs`: a management UI and API documentation viewer
+ * for the `@kingsleyweb/bun-jobs` management API. Needs
+ * `@kingsleyweb/bun-jobs`, an optional peer of the package that this entry
+ * (and `./lib/jobs/*`) alone requires.
+ *
+ * ```ts
+ * const api = createJobsApi({ jobs, basePath: "/jobs-api", authorize });
+ * const ui = jobsUi({ api, basePath: "/jobs" });
+ * app.use(api.basePath, api.router);
+ * app.use(ui.basePath, ui.router);
+ * ```
+ *
+ * The bundle machinery (`lib/jobs/assets.ts`: building, writing and loading
+ * `dist/jobs/`) is internal: `scripts/build.ts` and the tests import it directly.
+ * `JobsUiBaseOptions` stays public because both option interfaces extend it,
+ * so it is part of the options' declared shape.
+ */
+export type {
+  UiUnauthorized,
+  UiUnauthorizedStatus,
+} from "./browser/unauthorized";
+export type { JobsUiConfig, JobsUiSections, UiTheme } from "./browser/config";
+export { JOBS_UI_CONFIG_ELEMENT_ID } from "./browser/config";
+export type {
+  JobsUi,
+  JobsUiApiOptions,
+  JobsUiUnauthorizedOptions,
+  JobsUiAuthorize,
+  JobsUiAuthorizeContext,
+  JobsUiAuthorizeResult,
+  JobsUiBaseOptions,
+  JobsUiOptions,
+  JobsUiUrlOptions,
+} from "./types";