harnery 0.34.1 → 0.36.0

package/src/lazy-commands.ts

@@ -0,0 +1,294 @@
+import { type Command, Option, type ParseOptions } from "commander";
+
+const lazyState = Symbol("harnery.lazy-command-state");
+
+export interface LazyCommandDefinition {
+  /** Commander signature, including any top-level positional arguments. */
+  command: string;
+  description: string;
+  aliases?: readonly string[];
+  hidden?: boolean;
+  /** Preserve the `[options]` marker in root help without loading the implementation. */
+  hasOptions?: boolean;
+}
+
+export interface LazyCommandBundle {
+  commands: readonly LazyCommandDefinition[];
+  load(program: Command): void | Promise<void>;
+}
+
+type LoadStatus = "placeholder" | "loading" | "loaded";
+
+interface RegisteredBundle {
+  readonly definition: LazyCommandBundle;
+  readonly placeholders: Map<string, Command>;
+  status: LoadStatus;
+}
+
+interface LazyCommandState {
+  readonly bundles: RegisteredBundle[];
+  readonly byName: Map<string, RegisteredBundle>;
+  readonly hooks: Map<string, Array<(program: Command) => void | Promise<void>>>;
+  readonly originalParse: Command["parse"];
+  readonly originalParseAsync: Command["parseAsync"];
+}
+
+/**
+ * Add lightweight top-level command placeholders whose implementations load
+ * immediately before Commander parses the selected command.
+ */
+export function registerLazyCommandBundles(
+  program: Command,
+  definitions: readonly LazyCommandBundle[],
+): Command {
+  const state = stateFor(program);
+  for (const definition of definitions) {
+    const registered: RegisteredBundle = {
+      definition,
+      placeholders: new Map(),
+      status: "placeholder",
+    };
+    for (const metadata of definition.commands) {
+      const name = commandName(metadata.command);
+      const claimedNames = [name, ...(metadata.aliases ?? [])];
+      for (const claimedName of claimedNames) {
+        if (state.byName.has(claimedName) || findCommand(program, claimedName)) {
+          throw new Error(`Cannot register lazy command "${claimedName}": name already exists`);
+        }
+      }
+
+      const placeholder = program
+        .command(metadata.command, { hidden: metadata.hidden === true })
+        .description(metadata.description);
+      for (const alias of metadata.aliases ?? []) placeholder.alias(alias);
+      if (metadata.hasOptions) {
+        placeholder.addOption(new Option("--__lazy-command-placeholder").hideHelp());
+      }
+
+      registered.placeholders.set(name, placeholder);
+      for (const claimedName of claimedNames) state.byName.set(claimedName, registered);
+    }
+    state.bundles.push(registered);
+  }
+  return program;
+}
+
+/** Load one top-level command by canonical name or alias. */
+export async function loadLazyCommand(
+  program: Command,
+  name: string,
+): Promise<Command | undefined> {
+  const state = getState(program);
+  const bundle = state?.byName.get(name);
+  if (!state || !bundle) return findCommand(program, name);
+  await loadBundle(program, state, bundle);
+  return findCommand(program, name);
+}
+
+/** Materialize every remaining lazy bundle, for whole-tree discovery and completion. */
+export async function loadAllLazyCommands(program: Command): Promise<Command> {
+  const state = getState(program);
+  if (!state) return program;
+  for (const bundle of state.bundles) await loadBundle(program, state, bundle);
+  return program;
+}
+
+/** Run a host hook after a named lazy command becomes concrete. */
+export async function onLazyCommandLoaded(
+  program: Command,
+  name: string,
+  hook: (program: Command) => void | Promise<void>,
+): Promise<void> {
+  const state = getState(program);
+  const bundle = state?.byName.get(name);
+  if (!state || !bundle || bundle.status === "loaded") {
+    await hook(program);
+    return;
+  }
+  const hooks = state.hooks.get(name) ?? [];
+  hooks.push(hook);
+  state.hooks.set(name, hooks);
+}
+
+function stateFor(program: Command): LazyCommandState {
+  const existing = getState(program);
+  if (existing) return existing;
+
+  const originalParse = program.parse;
+  const originalParseAsync = program.parseAsync;
+  const state: LazyCommandState = {
+    bundles: [],
+    byName: new Map(),
+    hooks: new Map(),
+    originalParse,
+    originalParseAsync,
+  };
+  Object.defineProperty(program, lazyState, { value: state });
+
+  program.parseAsync = async function lazyParseAsync(
+    argv?: readonly string[],
+    parseOptions?: ParseOptions,
+  ): Promise<Command> {
+    const selected = selectedCommand(program, state, argv, parseOptions);
+    if (selected) await loadBundle(program, state, selected);
+    return originalParseAsync.call(this, argv, parseOptions);
+  };
+
+  program.parse = function lazyParse(
+    argv?: readonly string[],
+    parseOptions?: ParseOptions,
+  ): Command {
+    const selected = selectedCommand(program, state, argv, parseOptions);
+    if (selected && selected.status !== "loaded") {
+      throw new Error(
+        `Command "${selected.definition.commands[0]?.command ?? "unknown"}" loads asynchronously; use parseAsync()`,
+      );
+    }
+    return originalParse.call(this, argv, parseOptions);
+  };
+
+  return state;
+}
+
+function getState(program: Command): LazyCommandState | undefined {
+  return (program as Command & { [lazyState]?: LazyCommandState })[lazyState];
+}
+
+async function loadBundle(
+  program: Command,
+  state: LazyCommandState,
+  bundle: RegisteredBundle,
+): Promise<void> {
+  if (bundle.status === "loaded" || bundle.status === "loading") return;
+  bundle.status = "loading";
+
+  const positions = new Map<string, number>();
+  for (const [name, placeholder] of bundle.placeholders) {
+    const index = program.commands.indexOf(placeholder);
+    if (index >= 0) positions.set(name, index);
+  }
+  for (const placeholder of [...bundle.placeholders.values()].sort(
+    (a, b) => program.commands.indexOf(b) - program.commands.indexOf(a),
+  )) {
+    const index = program.commands.indexOf(placeholder);
+    if (index >= 0) mutableCommands(program).splice(index, 1);
+  }
+
+  const commandsBefore = new Set(program.commands);
+  try {
+    await bundle.definition.load(program);
+    for (const metadata of bundle.definition.commands) {
+      const name = commandName(metadata.command);
+      const concrete = program.commands.find(
+        (candidate) => !commandsBefore.has(candidate) && candidate.name() === name,
+      );
+      if (!concrete) {
+        throw new Error(`Lazy command loader did not register "${name}"`);
+      }
+    }
+
+    restoreCommandOrder(program, bundle, positions);
+    bundle.status = "loaded";
+    for (const metadata of bundle.definition.commands) {
+      const name = commandName(metadata.command);
+      for (const hook of state.hooks.get(name) ?? []) await hook(program);
+      state.hooks.delete(name);
+    }
+  } catch (error) {
+    for (let index = program.commands.length - 1; index >= 0; index--) {
+      if (!commandsBefore.has(program.commands[index]!)) mutableCommands(program).splice(index, 1);
+    }
+    restorePlaceholders(program, bundle, positions);
+    bundle.status = "placeholder";
+    throw error;
+  }
+}
+
+function restoreCommandOrder(
+  program: Command,
+  bundle: RegisteredBundle,
+  positions: ReadonlyMap<string, number>,
+): void {
+  const ordered = bundle.definition.commands
+    .map((metadata) => {
+      const name = commandName(metadata.command);
+      const command = findCommand(program, name);
+      const position = positions.get(name);
+      return command && position !== undefined ? { command, position } : undefined;
+    })
+    .filter((entry): entry is { command: Command; position: number } => entry !== undefined)
+    .sort((a, b) => a.position - b.position);
+
+  for (const { command } of ordered) {
+    const index = program.commands.indexOf(command);
+    if (index >= 0) mutableCommands(program).splice(index, 1);
+  }
+  for (const { command, position } of ordered) {
+    mutableCommands(program).splice(Math.min(position, program.commands.length), 0, command);
+  }
+}
+
+function restorePlaceholders(
+  program: Command,
+  bundle: RegisteredBundle,
+  positions: ReadonlyMap<string, number>,
+): void {
+  const ordered = [...bundle.placeholders]
+    .map(([name, command]) => ({ command, position: positions.get(name) }))
+    .filter(
+      (entry): entry is { command: Command; position: number } => entry.position !== undefined,
+    )
+    .sort((a, b) => a.position - b.position);
+  for (const { command, position } of ordered) {
+    mutableCommands(program).splice(Math.min(position, program.commands.length), 0, command);
+  }
+}
+
+function selectedCommand(
+  program: Command,
+  state: LazyCommandState,
+  argv: readonly string[] | undefined,
+  parseOptions: ParseOptions | undefined,
+): RegisteredBundle | undefined {
+  const args = userArguments(argv ?? process.argv, parseOptions?.from);
+  for (let index = 0; index < args.length; index++) {
+    const token = args[index]!;
+    if (token === "--") return undefined;
+    if (token.startsWith("-")) {
+      const option = findRootOption(program, token);
+      if (option?.required || (option?.optional && !args[index + 1]?.startsWith("-"))) index++;
+      continue;
+    }
+    if (token === "help") return state.byName.get(args[index + 1] ?? "");
+    return state.byName.get(token);
+  }
+  return undefined;
+}
+
+function userArguments(
+  argv: readonly string[],
+  from: ParseOptions["from"] | undefined,
+): readonly string[] {
+  if (from === "user") return argv;
+  if (from === "electron") return argv.slice(1);
+  return argv.slice(2);
+}
+
+function findRootOption(program: Command, token: string): Option | undefined {
+  const flag = token.includes("=") ? token.slice(0, token.indexOf("=")) : token;
+  return program.options.find((option) => option.short === flag || option.long === flag);
+}
+
+function findCommand(program: Command, name: string): Command | undefined {
+  return program.commands.find(
+    (candidate) => candidate.name() === name || candidate.aliases().includes(name),
+  );
+}
+
+function mutableCommands(program: Command): Command[] {
+  return program.commands as Command[];
+}
+
+function commandName(signature: string): string {
+  return signature.trim().split(/[\s|]/, 1)[0] ?? signature;
+}

package/src/lib/browser/client.ts

@@ -42,6 +42,12 @@ import {
   buildRuntsCheck,
   type RuntsResult,
 } from "./runts.js";
+import {
+  buildStandaloneHtmlScript,
+  DEFAULT_MAX_RESOURCE_BYTES,
+  DEFAULT_MAX_TOTAL_RESOURCE_BYTES,
+  type StandaloneHtmlResult,
+} from "./standalone-html.js";
 import {
   buildClearTargetSizeAnnotationsScript,
   buildTargetSizeAnnotateScript,
@@ -1011,6 +1017,21 @@ export class Browser {
     return await page.content();
   }
 
+  /**
+   * Self-contained snapshot of the page: stylesheets inlined, fonts and images
+   * embedded as data: URIs, everything else rewritten to absolute URLs on the
+   * captured origin. Use this for anything written to a file — a raw
+   * `htmlContent()` dump renders unstyled once it leaves the page's own origin.
+   */
+  async standaloneHtml(
+    opts: { maxResourceBytes?: number; maxTotalResourceBytes?: number } = {},
+  ): Promise<StandaloneHtmlResult> {
+    return await this.currentPage.evaluate(buildStandaloneHtmlScript(), {
+      maxResourceBytes: opts.maxResourceBytes ?? DEFAULT_MAX_RESOURCE_BYTES,
+      maxTotalResourceBytes: opts.maxTotalResourceBytes ?? DEFAULT_MAX_TOTAL_RESOURCE_BYTES,
+    });
+  }
+
   async click(selector: string): Promise<void> {
     await this.currentPage.click(selector);
   }

package/src/lib/browser/index.ts

@@ -140,6 +140,10 @@ export {
   sendBrowserSessionRequest,
   startBrowserSessionServer,
 } from "./session-control.js";
+export type {
+  StandaloneHtmlRequest,
+  StandaloneHtmlResult,
+} from "./standalone-html.js";
 export type {
   TargetSizeNode,
   TargetSizeOutcome,

package/src/lib/browser/standalone-html.ts

@@ -0,0 +1,312 @@
+// Self-contained HTML snapshots for `harn browse` trio mode.
+//
+// `page.content()` serializes the DOM but not the resources it points at, and
+// framework pages reference those with root-absolute paths (`/_next/static/…`).
+// Written to a file and reopened from anywhere else — the files origin, another
+// host, `file://` — every one of those paths resolves against the wrong root and
+// 404s, so the snapshot renders as unstyled black-on-white text with broken
+// images. That is what an operator sees when they preview an artifact's `.html`.
+//
+// This rewrite makes the saved document stand on its own:
+//   - stylesheets are fetched and inlined as <style>
+//   - fonts, images, and icons are inlined as data: URIs under a byte budget
+//   - anything left over (too large, cross-origin, unreachable) is rewritten to
+//     an absolute URL on the captured origin rather than left root-relative
+//   - <script> and preload/prefetch hints are dropped: none of them can work in
+//     a snapshot, and a dead script tag only invites a hydration attempt
+//
+// The live page is untouched — everything happens on a clone of the document.
+
+/** Byte budget for one inlined sub-resource. Larger ones stay as absolute URLs. */
+export const DEFAULT_MAX_RESOURCE_BYTES = 512 * 1024;
+
+/** Byte budget for all inlined sub-resources in one snapshot. */
+export const DEFAULT_MAX_TOTAL_RESOURCE_BYTES = 8 * 1024 * 1024;
+
+export interface StandaloneHtmlRequest {
+  maxResourceBytes: number;
+  maxTotalResourceBytes: number;
+}
+
+export interface StandaloneHtmlResult {
+  html: string;
+  /** Source URL the snapshot was taken from. */
+  source: string;
+  /** Stylesheets inlined as <style>. */
+  stylesheetsInlined: number;
+  /** Stylesheets left as absolute <link> (unreachable or cross-origin). */
+  stylesheetsLinked: number;
+  /** Sub-resources (fonts, images, icons) inlined as data: URIs. */
+  resourcesInlined: number;
+  /** Sub-resources left as absolute URLs (over budget or unreachable). */
+  resourcesLinked: number;
+  /** Bytes of sub-resource payload inlined. */
+  inlinedBytes: number;
+}
+
+export function buildStandaloneHtmlScript(): (
+  args: StandaloneHtmlRequest,
+) => Promise<StandaloneHtmlResult> {
+  return async ({ maxResourceBytes, maxTotalResourceBytes }) => {
+    const SKIP = /^(?:data:|blob:|javascript:|mailto:|tel:|sms:|about:|#)/i;
+    const base = document.baseURI;
+
+    let inlinedBytes = 0;
+    let resourcesInlined = 0;
+    let resourcesLinked = 0;
+    let stylesheetsInlined = 0;
+    let stylesheetsLinked = 0;
+
+    const absolute = (url: string, from: string): string | null => {
+      try {
+        return new URL(url, from).href;
+      } catch {
+        return null;
+      }
+    };
+
+    const dataUriCache = new Map<string, string | null>();
+
+    /** Fetch a resource as a data: URI, or null when it is unreachable or over budget. */
+    const toDataUri = async (url: string): Promise<string | null> => {
+      const cached = dataUriCache.get(url);
+      if (cached !== undefined) return cached;
+      let result: string | null = null;
+      try {
+        const res = await fetch(url, { credentials: "include" });
+        if (res.ok) {
+          const buf = await res.arrayBuffer();
+          const fits =
+            buf.byteLength <= maxResourceBytes &&
+            inlinedBytes + buf.byteLength <= maxTotalResourceBytes;
+          if (fits) {
+            const bytes = new Uint8Array(buf);
+            let binary = "";
+            const chunk = 0x8000;
+            for (let i = 0; i < bytes.length; i += chunk) {
+              binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+            }
+            const type = (res.headers.get("content-type") ?? "").split(";")[0]?.trim();
+            result = `data:${type || "application/octet-stream"};base64,${btoa(binary)}`;
+            inlinedBytes += buf.byteLength;
+          }
+        }
+      } catch {
+        result = null;
+      }
+      dataUriCache.set(url, result);
+      return result;
+    };
+
+    /** Resolve one reference: data: URI when it fits, absolute URL otherwise. */
+    const resolveRef = async (
+      raw: string,
+      from: string,
+      inline: boolean,
+    ): Promise<string | null> => {
+      const trimmed = raw.trim();
+      if (!trimmed || SKIP.test(trimmed)) return null;
+      const url = absolute(trimmed, from);
+      if (!url) return null;
+      if (!inline) return url;
+      const dataUri = await toDataUri(url);
+      if (dataUri) {
+        resourcesInlined += 1;
+        return dataUri;
+      }
+      resourcesLinked += 1;
+      return url;
+    };
+
+    /** Rewrite url() and @import references inside a stylesheet against its own URL. */
+    const rewriteCss = async (css: string, from: string): Promise<string> => {
+      const urlRef = /url\(\s*(['"]?)([^'")]*)\1\s*\)/g;
+      const importRef = /@import\s+(['"])([^'"]+)\1/g;
+
+      const replacements = new Map<string, string>();
+      const collect = async (pattern: RegExp, inline: boolean) => {
+        pattern.lastIndex = 0;
+        const seen: string[] = [];
+        for (let m = pattern.exec(css); m; m = pattern.exec(css)) {
+          const raw = m[2];
+          if (raw !== undefined && !replacements.has(raw)) seen.push(raw);
+        }
+        for (const raw of seen) {
+          const resolved = await resolveRef(raw, from, inline);
+          if (resolved) replacements.set(raw, resolved);
+        }
+      };
+      await collect(urlRef, true);
+      await collect(importRef, false);
+
+      return css
+        .replace(urlRef, (full, _q, raw: string) => {
+          const next = replacements.get(raw);
+          return next ? `url("${next}")` : full;
+        })
+        .replace(importRef, (full, _q, raw: string) => {
+          const next = replacements.get(raw);
+          return next ? `@import "${next}"` : full;
+        });
+    };
+
+    const doc = document.cloneNode(true) as Document;
+
+    // Nothing executable survives a snapshot; leaving these in only produces
+    // console noise and a doomed hydration pass on reopen.
+    for (const node of Array.from(doc.querySelectorAll("script, base"))) node.remove();
+    const deadHints = 'link[rel~="preload"],link[rel~="modulepreload"],link[rel~="prefetch"]';
+    for (const node of Array.from(doc.querySelectorAll(deadHints))) node.remove();
+
+    // Stylesheets: fetch → inline. Falls back to the CSSOM (which covers rules a
+    // same-origin sheet already parsed) and finally to an absolute <link>.
+    for (const link of Array.from(doc.querySelectorAll('link[rel~="stylesheet"]'))) {
+      const href = link.getAttribute("href");
+      const url = href ? absolute(href, base) : null;
+      if (!url) {
+        link.remove();
+        continue;
+      }
+      let css: string | null = null;
+      try {
+        const res = await fetch(url, { credentials: "include" });
+        if (res.ok) css = await res.text();
+      } catch {
+        css = null;
+      }
+      if (css === null) {
+        for (const sheet of Array.from(document.styleSheets)) {
+          if (sheet.href !== url) continue;
+          try {
+            css = Array.from(sheet.cssRules)
+              .map((rule) => rule.cssText)
+              .join("\n");
+          } catch {
+            css = null;
+          }
+          break;
+        }
+      }
+      if (css === null) {
+        link.setAttribute("href", url);
+        stylesheetsLinked += 1;
+        continue;
+      }
+      const style = doc.createElement("style");
+      style.setAttribute("data-harnery-inlined-from", url);
+      const media = link.getAttribute("media");
+      if (media) style.setAttribute("media", media);
+      style.textContent = await rewriteCss(css, url);
+      link.replaceWith(style);
+      stylesheetsInlined += 1;
+    }
+
+    // Inline <style> blocks carry their own relative refs (framework @font-face
+    // rules in particular), so they need the same treatment.
+    for (const style of Array.from(doc.querySelectorAll("style"))) {
+      if (style.hasAttribute("data-harnery-inlined-from")) continue;
+      const css = style.textContent;
+      if (css) style.textContent = await rewriteCss(css, base);
+    }
+
+    // Stylesheets adopted via CSSOM never appear in the DOM and would be lost.
+    const adopted = (document as Document & { adoptedStyleSheets?: CSSStyleSheet[] })
+      .adoptedStyleSheets;
+    if (adopted?.length) {
+      const parts: string[] = [];
+      for (const sheet of adopted) {
+        try {
+          parts.push(
+            Array.from(sheet.cssRules)
+              .map((rule) => rule.cssText)
+              .join("\n"),
+          );
+        } catch {
+          // Constructed sheet with unreadable rules; nothing to recover.
+        }
+      }
+      if (parts.length) {
+        const style = doc.createElement("style");
+        style.setAttribute("data-harnery-adopted", "");
+        style.textContent = await rewriteCss(parts.join("\n"), base);
+        doc.head?.appendChild(style);
+      }
+    }
+
+    // Element references. Media and icons are worth inlining; navigation targets
+    // only need to stop pointing at the wrong root.
+    const inlineAttrs: Array<[string, string]> = [
+      ["img", "src"],
+      ["source", "src"],
+      ["video", "src"],
+      ["video", "poster"],
+      ["audio", "src"],
+      ["track", "src"],
+      ["input", "src"],
+      ["object", "data"],
+      ['link[rel~="icon"]', "href"],
+      ['link[rel~="apple-touch-icon"]', "href"],
+      ["image", "href"],
+      ["use", "href"],
+    ];
+    const absoluteAttrs: Array<[string, string]> = [
+      ["a", "href"],
+      ["area", "href"],
+      ["form", "action"],
+      ["iframe", "src"],
+      ["embed", "src"],
+      ["link", "href"],
+    ];
+
+    const applyAttrs = async (specs: Array<[string, string]>, inline: boolean) => {
+      for (const [selector, attr] of specs) {
+        for (const el of Array.from(doc.querySelectorAll(selector))) {
+          const raw = el.getAttribute(attr);
+          if (!raw) continue;
+          const next = await resolveRef(raw, base, inline);
+          if (next) el.setAttribute(attr, next);
+        }
+      }
+    };
+    await applyAttrs(inlineAttrs, true);
+    await applyAttrs(absoluteAttrs, false);
+
+    // srcset is a comma-separated list of `url descriptor` pairs.
+    for (const el of Array.from(doc.querySelectorAll("img[srcset], source[srcset]"))) {
+      const raw = el.getAttribute("srcset");
+      if (!raw) continue;
+      const rewritten: string[] = [];
+      for (const candidate of raw.split(",")) {
+        const parts = candidate.trim().split(/\s+/);
+        const url = parts.shift();
+        if (!url) continue;
+        const next = (await resolveRef(url, base, true)) ?? url;
+        rewritten.push([next, ...parts].join(" "));
+      }
+      if (rewritten.length) el.setAttribute("srcset", rewritten.join(", "));
+    }
+
+    // Inline style attributes can carry background-image url().
+    for (const el of Array.from(doc.querySelectorAll("[style]"))) {
+      const raw = el.getAttribute("style");
+      if (!raw?.includes("url(")) continue;
+      el.setAttribute("style", await rewriteCss(raw, base));
+    }
+
+    const provenance = doc.createElement("meta");
+    provenance.setAttribute("name", "harnery:snapshot-source");
+    provenance.setAttribute("content", location.href);
+    doc.head?.prepend(provenance);
+
+    const doctype = document.doctype ? `<!DOCTYPE ${document.doctype.name}>` : "<!DOCTYPE html>";
+    return {
+      html: `${doctype}\n${doc.documentElement.outerHTML}\n`,
+      source: location.href,
+      stylesheetsInlined,
+      stylesheetsLinked,
+      resourcesInlined,
+      resourcesLinked,
+      inlinedBytes,
+    };
+  };
+}