@hraness/direct 0.7.5

package/src/tooling/bundle-boundary.ts

@@ -0,0 +1,159 @@
+import path from "node:path";
+
+export const DIRECT_WIRE_MARKERS = Object.freeze([
+  "direct.browser-bridge/",
+  "direct.coverage/",
+  "direct.fixture/",
+  "direct.probe/",
+  "direct.runtime/",
+  "direct.session-manifest/",
+] as const);
+
+export interface BundleBoundaryViolation {
+  readonly file: string;
+  readonly markers: readonly string[];
+}
+
+export interface BundleBoundaryResult {
+  readonly scanned: readonly string[];
+  readonly violations: readonly BundleBoundaryViolation[];
+}
+
+export interface BundleBoundaryOptions {
+  readonly directory: string;
+  readonly excludePatterns?: readonly string[];
+  readonly markers: readonly string[];
+  readonly patterns: readonly string[];
+}
+
+export interface ExactVersionedMarkerEvidence {
+  readonly missing: readonly string[];
+  readonly observed: readonly string[];
+  readonly unexpected: readonly string[];
+}
+
+function validatedMarkers(markers: readonly string[]): readonly string[] {
+  const seen = new Set<string>();
+  const output: string[] = [];
+  for (const marker of markers) {
+    if (marker.length === 0) throw new Error("Bundle-boundary markers cannot be empty.");
+    if (seen.has(marker)) throw new Error(`Bundle-boundary marker is duplicated: ${marker}`);
+    seen.add(marker);
+    output.push(marker);
+  }
+  if (output.length === 0) throw new Error("A bundle boundary needs at least one forbidden marker.");
+  return Object.freeze(output);
+}
+
+function validatedPatterns(patterns: readonly string[]): readonly string[] {
+  if (patterns.length === 0) throw new Error("A bundle boundary needs at least one file pattern.");
+  return Object.freeze(patterns.map((pattern) => {
+    if (pattern.length === 0) throw new Error("Bundle-boundary file patterns cannot be empty.");
+    return pattern;
+  }));
+}
+
+function validatedExcludePatterns(patterns: readonly string[] | undefined): readonly string[] {
+  return Object.freeze((patterns ?? []).map((pattern) => {
+    if (pattern.length === 0) throw new Error("Bundle-boundary exclusion patterns cannot be empty.");
+    return pattern;
+  }));
+}
+
+function versionedMarkerFamilies(
+  expectedMarkers: readonly string[],
+): readonly { readonly expected: string; readonly family: string }[] {
+  if (expectedMarkers.length === 0) {
+    throw new Error("An exact versioned-marker policy needs at least one expected marker.");
+  }
+  const seen = new Set<string>();
+  return Object.freeze(expectedMarkers.map((expected) => {
+    const match = /^(?<family>[A-Za-z0-9][A-Za-z0-9._/-]*\/v)(?<version>0|[1-9][0-9]*)$/u
+      .exec(expected);
+    const family = match?.groups?.["family"];
+    if (family === undefined) {
+      throw new Error(`Exact versioned marker must end in a canonical numeric version: ${expected}`);
+    }
+    if (seen.has(family)) {
+      throw new Error(`Exact versioned-marker family is duplicated: ${family}`);
+    }
+    seen.add(family);
+    return Object.freeze({ expected, family });
+  }));
+}
+
+function escapedRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, "\\$&");
+}
+
+export function inspectExactVersionedMarkers(
+  byteSequences: Iterable<Uint8Array>,
+  expectedMarkers: readonly string[],
+): ExactVersionedMarkerEvidence {
+  const families = versionedMarkerFamilies(expectedMarkers);
+  const observed = new Set<string>();
+  const contents = [...byteSequences].map((bytes) => (
+    Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength).toString("latin1")
+  ));
+  for (const { family } of families) {
+    const pattern = new RegExp(
+      `(?<![A-Za-z0-9._/-])${escapedRegExp(family)}[0-9]+(?![A-Za-z0-9._/-])`,
+      "gu",
+    );
+    for (const content of contents) {
+      for (const match of content.matchAll(pattern)) observed.add(match[0]);
+    }
+  }
+  const expected = new Set(expectedMarkers);
+  const matching = expectedMarkers.filter((marker) => observed.has(marker));
+  const unexpected = [...observed]
+    .filter((marker) => !expected.has(marker))
+    .sort((left, right) => left.localeCompare(right));
+  return Object.freeze({
+    missing: Object.freeze(expectedMarkers.filter((marker) => !observed.has(marker))),
+    observed: Object.freeze([...matching, ...unexpected]),
+    unexpected: Object.freeze(unexpected),
+  });
+}
+
+export function findForbiddenMarkers(
+  bytes: Uint8Array,
+  markers: readonly string[],
+): readonly string[] {
+  const contents = Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  return validatedMarkers(markers).filter((marker) => contents.includes(Buffer.from(marker)));
+}
+
+export async function checkBundleBoundary(
+  options: BundleBoundaryOptions,
+): Promise<BundleBoundaryResult> {
+  const root = path.resolve(options.directory);
+  const markers = validatedMarkers(options.markers);
+  const patterns = validatedPatterns(options.patterns);
+  const excludePatterns = validatedExcludePatterns(options.excludePatterns)
+    .map((pattern) => new Bun.Glob(pattern));
+  const scanned = new Set<string>();
+  const violations: BundleBoundaryViolation[] = [];
+
+  for (const pattern of patterns) {
+    const glob = new Bun.Glob(pattern);
+    for await (const relative of glob.scan({ cwd: root, dot: true, onlyFiles: true })) {
+      if (excludePatterns.some((excludePattern) => excludePattern.match(relative))) continue;
+      const file = path.join(root, relative);
+      if (scanned.has(file)) continue;
+      scanned.add(file);
+      const found = findForbiddenMarkers(
+        new Uint8Array(await Bun.file(file).arrayBuffer()),
+        markers,
+      );
+      if (found.length > 0) violations.push({ file, markers: found });
+    }
+  }
+
+  return {
+    scanned: Object.freeze([...scanned].sort()),
+    violations: Object.freeze(
+      [...violations].sort((left, right) => left.file.localeCompare(right.file)),
+    ),
+  };
+}

package/src/web/browser-bridge.ts

@@ -0,0 +1,296 @@
+import { renderUnknownReason } from "../core/reason.js";
+import { err, ok, type Result } from "../core/result.js";
+import {
+  parseDirectProbeSnapshot,
+  type DirectProbe,
+  type DirectProbeSnapshot,
+} from "../testing/probe.js";
+import {
+  parseDirectSessionManifest,
+  type DirectSessionManifest,
+} from "../testing/manifest.js";
+
+export const DIRECT_BROWSER_BRIDGE_SCHEMA = "direct.browser-bridge/v2" as const;
+
+export interface DirectBrowserBridge {
+  readonly schema: typeof DIRECT_BROWSER_BRIDGE_SCHEMA;
+  readonly manifest: DirectSessionManifest;
+  readonly snapshot: () => DirectProbeSnapshot;
+  readonly reset: () => undefined;
+}
+
+export interface DirectBrowserBridgeOptions {
+  readonly probe: Pick<DirectProbe, "snapshot">;
+  readonly manifest: unknown;
+  readonly reset?: () => undefined;
+  readonly target?: object;
+}
+
+export type DirectBrowserBridgeErrorCode = "install-failed" | "invalid-manifest";
+
+export interface DirectBrowserBridgeError {
+  readonly code: DirectBrowserBridgeErrorCode;
+  readonly message: string;
+}
+
+export type DirectBrowserBridgeUninstall = () => undefined;
+
+export interface PreparedDirectBrowserBridgeInstallation {
+  /** Make this provisional replacement the process owner. Cannot fail. */
+  readonly commit: () => undefined;
+  /** Restore the exact owner observed before preparation. */
+  readonly rollback: () => undefined;
+  /** Remove a committed replacement and restore its underlying owner. */
+  readonly uninstall: DirectBrowserBridgeUninstall;
+}
+
+const BRIDGE_KEYS = ["__direct"] as const;
+
+interface ActiveBridgeInstallation {
+  readonly target: object;
+  readonly installed: ReadonlyMap<string, unknown>;
+  readonly restore: ReadonlyMap<string, PropertyDescriptor | undefined>;
+  readonly deactivate: () => undefined;
+  readonly uninstall: DirectBrowserBridgeUninstall;
+}
+
+let activeBridgeInstallation: ActiveBridgeInstallation | null = null;
+
+function bridgeError(
+  code: DirectBrowserBridgeErrorCode,
+  message: string,
+): DirectBrowserBridgeError {
+  return Object.freeze({ code, message });
+}
+
+/** Consume a foreign thenable so a callback that lied about being synchronous cannot reject globally. */
+function containPromiseLike(value: unknown): boolean {
+  if ((typeof value !== "object" || value === null) && typeof value !== "function") return false;
+  let then: unknown;
+  try {
+    then = Reflect.get(value, "then");
+  } catch {
+    return false;
+  }
+  if (typeof then !== "function") return false;
+  try {
+    void Promise.resolve(value).catch(() => undefined);
+  } catch {
+    // Promise assimilation is a foreign boundary too. The callback remains contained.
+  }
+  return true;
+}
+
+function requireSynchronousResetResult(value: unknown): undefined {
+  containPromiseLike(value);
+  if (value !== undefined) {
+    throw new Error("Direct reset must complete synchronously and return undefined");
+  }
+  return undefined;
+}
+
+function defaultReset(): undefined {
+  const target = globalThis as typeof globalThis & {
+    readonly location?: { readonly reload?: () => unknown };
+  };
+  return requireSynchronousResetResult(target.location?.reload?.());
+}
+
+function restoreDescriptor(target: object, key: string, descriptor: PropertyDescriptor | undefined): void {
+  if (descriptor === undefined) {
+    Reflect.deleteProperty(target, key);
+  } else {
+    Object.defineProperty(target, key, descriptor);
+  }
+}
+
+function restoreInstalledValue(
+  target: object,
+  key: string,
+  installedValue: unknown,
+  previous: PropertyDescriptor | undefined,
+): void {
+  try {
+    const descriptor = Object.getOwnPropertyDescriptor(target, key);
+    if (descriptor?.value === installedValue) restoreDescriptor(target, key, previous);
+  } catch {
+    // Uninstall and failed-install cleanup are best effort on a hostile target.
+  }
+}
+
+/** Prepare a reversible bridge replacement without deactivating the current owner. */
+export function prepareDirectBrowserBridgeInstallation(
+  options: DirectBrowserBridgeOptions,
+): Result<PreparedDirectBrowserBridgeInstallation, DirectBrowserBridgeError> {
+  let manifestInput: unknown;
+  try {
+    manifestInput = options.manifest;
+  } catch (reason) {
+    return err(bridgeError(
+      "invalid-manifest",
+      renderUnknownReason(reason, "Failed to read the Direct session manifest"),
+    ));
+  }
+  const parsedManifest = parseDirectSessionManifest(manifestInput);
+  if (!parsedManifest.ok) {
+    return err(bridgeError("invalid-manifest", parsedManifest.error.message));
+  }
+  const manifest = parsedManifest.value;
+
+  let target: object;
+  let reset: () => undefined;
+  let probe: Pick<DirectProbe, "snapshot">;
+  try {
+    target = options.target ?? globalThis;
+    reset = options.reset ?? defaultReset;
+    probe = options.probe;
+  } catch (reason) {
+    return err(bridgeError(
+      "install-failed",
+      renderUnknownReason(reason, "Failed to read Direct browser bridge options"),
+    ));
+  }
+  const previousInstallation = activeBridgeInstallation;
+  const rollbackDescriptors = new Map<string, PropertyDescriptor | undefined>();
+  const restore = new Map<string, PropertyDescriptor | undefined>();
+  try {
+    for (const key of BRIDGE_KEYS) {
+      const descriptor = Object.getOwnPropertyDescriptor(target, key);
+      rollbackDescriptors.set(key, descriptor);
+      const previousOwnsValue = previousInstallation?.target === target
+        && descriptor?.value === previousInstallation.installed.get(key);
+      restore.set(
+        key,
+        previousOwnsValue ? previousInstallation.restore.get(key) : descriptor,
+      );
+    }
+  } catch (reason) {
+    return err(bridgeError(
+      "install-failed",
+      renderUnknownReason(reason, "Failed to inspect the Direct browser bridge target"),
+    ));
+  }
+
+  const readSnapshot = (): DirectProbeSnapshot => {
+    try {
+      const snapshot: unknown = probe.snapshot();
+      if (containPromiseLike(snapshot)) {
+        throw new Error("Direct probe snapshots must complete synchronously");
+      }
+      if ((typeof snapshot !== "object" || snapshot === null) && typeof snapshot !== "function") {
+        throw new Error("Direct probe returned an invalid result");
+      }
+      const succeeded: unknown = Reflect.get(snapshot, "ok");
+      if (succeeded !== true) {
+        if (succeeded === false) throw new Error(renderUnknownReason(Reflect.get(snapshot, "error")));
+        throw new Error("Direct probe returned an invalid result");
+      }
+      const parsed = parseDirectProbeSnapshot(Reflect.get(snapshot, "value"));
+      if (!parsed.ok) throw new Error(parsed.error.message);
+      if (parsed.value.activationHash !== manifest.active.activationHash) {
+        throw new Error(
+          "Direct probe activation hash does not match the installed session manifest",
+        );
+      }
+      return parsed.value;
+    } catch (reason) {
+      throw new Error(`Direct probe failed: ${renderUnknownReason(reason)}`);
+    }
+  };
+  const runReset = (): undefined => {
+    try {
+      const returned: unknown = reset();
+      return requireSynchronousResetResult(returned);
+    } catch (reason) {
+      throw new Error(`Direct reset failed: ${renderUnknownReason(reason)}`);
+    }
+  };
+  const bridge: DirectBrowserBridge = Object.freeze({
+    schema: DIRECT_BROWSER_BRIDGE_SCHEMA,
+    manifest,
+    snapshot: readSnapshot,
+    reset: runReset,
+  });
+  const installed = new Map<string, unknown>([["__direct", bridge]]);
+
+  try {
+    for (const [key, value] of installed) {
+      Object.defineProperty(target, key, {
+        configurable: true,
+        enumerable: false,
+        writable: true,
+        value,
+      });
+    }
+  } catch (reason) {
+    for (const key of BRIDGE_KEYS) {
+      restoreInstalledValue(target, key, installed.get(key), rollbackDescriptors.get(key));
+    }
+    return err(bridgeError(
+      "install-failed",
+      renderUnknownReason(reason, "Direct browser bridge installation failed"),
+    ));
+  }
+
+  let state: "prepared" | "committed" | "closed" = "prepared";
+  const rollback = (): undefined => {
+    if (state !== "prepared") return undefined;
+    state = "closed";
+    for (const key of BRIDGE_KEYS) {
+      restoreInstalledValue(target, key, installed.get(key), rollbackDescriptors.get(key));
+    }
+    return undefined;
+  };
+  const deactivate = (): undefined => {
+    if (state !== "committed") return undefined;
+    state = "closed";
+    if (activeBridgeInstallation === installation) activeBridgeInstallation = null;
+    return undefined;
+  };
+  const uninstall = (): undefined => {
+    if (state === "prepared") return rollback();
+    if (state !== "committed") return undefined;
+    state = "closed";
+    for (const key of BRIDGE_KEYS) {
+      restoreInstalledValue(target, key, installed.get(key), restore.get(key));
+    }
+    if (activeBridgeInstallation === installation) activeBridgeInstallation = null;
+    return undefined;
+  };
+  const installation: ActiveBridgeInstallation = Object.freeze({
+    target,
+    installed,
+    restore,
+    deactivate,
+    uninstall,
+  });
+  const commit = (): undefined => {
+    if (state !== "prepared") return undefined;
+    state = "committed";
+    if (previousInstallation !== null) {
+      if (previousInstallation.target === target) previousInstallation.deactivate();
+      else previousInstallation.uninstall();
+    }
+    activeBridgeInstallation = installation;
+    return undefined;
+  };
+
+  return ok(Object.freeze({
+    commit,
+    rollback,
+    uninstall,
+  }));
+}
+
+/**
+ * Install one process-local browser automation bridge. A later installation
+ * restores and replaces the earlier one; stale uninstall handles are harmless.
+ */
+export function installDirectBrowserBridge(
+  options: DirectBrowserBridgeOptions,
+): Result<DirectBrowserBridgeUninstall, DirectBrowserBridgeError> {
+  const prepared = prepareDirectBrowserBridgeInstallation(options);
+  if (!prepared.ok) return prepared;
+  prepared.value.commit();
+  return ok(prepared.value.uninstall);
+}