Skip to content

Open-source design agent: on-brand stills, decks, diagrams, charts and motion graphics from a chat thread, built on Deep Agents.

10.7 KB
Raw Blame
// toolchain.mjs — what every gate shares: the exit-code contract, flag parsing, workspace
// confinement, brand tokens, and the sandbox render toolchain (puppeteer-core, sharp, Chrome).
//
// Node packages resolve from the sandbox's pinned install (sandbox/render/, baked into
// /opt/design-agent/render), never from a copy under /workspace: the stager refreshes the workspace
// every run, so a node_modules there would drift from the pinned lock. The browser is the one Chrome
// Headless Shell the recipe installs. A missing package or browser is a tooling failure (exit 2),
// never a pass.
//
//   DESIGN_AGENT_RENDER_DIR   directory holding the render package.json (default /opt/design-agent/render)
//   DESIGN_AGENT_BROWSER      Chrome executable (default /usr/local/bin/chrome-headless-shell)

import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
import { createRequire } from "node:module";
import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
import { fileURLToPath } from "node:url";

// Headless Chromium turns off subpixel glyph positioning below device scale factor 1.5, and always
// for page.pdf(), then rounds every glyph advance to a whole pixel: at 12px that is +/-4% of an em,
// so tracked type clumps in the export while the authored HTML measures perfect.
// `enable-font-subpixel-positioning` keeps advances fractional; `font-render-hinting=none` keeps the
// outlines from being grid-fit (a separate stage, so both are needed). Text-only on purpose: a
// colour-management flag here would silently shift every export already delivered.
export const CHROMIUM_TEXT_ARGS = Object.freeze([
  "--font-render-hinting=none",
  "--enable-font-subpixel-positioning",
]);
/** Every browser export launches with exactly these; a divergent list is how the defect returns. */
export const CHROMIUM_EXPORT_ARGS = Object.freeze([
  "--no-sandbox",
  "--disable-dev-shm-usage",
  ...CHROMIUM_TEXT_ARGS,
]);

export const TOOLS_DIR = dirname(fileURLToPath(import.meta.url));
/** The workspace the tools sit in: /workspace in the sandbox. */
export const WORKSPACE = resolve(TOOLS_DIR, "..");
export const DEFAULT_TOKENS = join(WORKSPACE, "brand", "tokens.json");
export const RENDER_DIR = process.env.DESIGN_AGENT_RENDER_DIR || "/opt/design-agent/render";
export const BROWSER = process.env.DESIGN_AGENT_BROWSER || "/usr/local/bin/chrome-headless-shell";

/** 0 pass · 1 findings (ERROR) · 2 the probe could not run. */
export const EXIT = Object.freeze({ PASS: 0, FINDINGS: 1, TOOLING: 2 });

/** A failure of the tool, its arguments or its environment. Always exit 2, never a pass. */
export class ToolingError extends Error {}

/** True when `moduleUrl` is the script node was started with. */
export function isMain(moduleUrl) {
  if (!process.argv[1]) return false;
  try {
    return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(moduleUrl));
  } catch {
    return resolve(process.argv[1]) === fileURLToPath(moduleUrl);
  }
}

/**
 * Run a CLI body that returns an exit code. Any thrown error is a tooling failure (exit 2): a gate
 * that crashed did not check anything. Sets `process.exitCode` instead of calling `process.exit`, so
 * piped stdout finishes flushing.
 */
export async function runCli(name, body) {
  try {
    process.exitCode = (await body()) ?? EXIT.PASS;
  } catch (error) {
    const message = error instanceof ToolingError ? error.message : error?.stack || String(error);
    console.error(`${name}: ${message}`);
    process.exitCode = EXIT.TOOLING;
  }
}

/**
 * `--name value`, repeatable `multi` flags and `booleans`. An unknown flag or a missing value is a
 * tooling failure, so a typo never turns into a silently skipped check.
 */
export function parseFlags(argv, { values = [], multi = [], booleans = [] } = {}) {
  const flags = Object.fromEntries(multi.map((name) => [name, []]));
  const positionals = [];
  for (let i = 0; i < argv.length; i++) {
    const arg = argv[i];
    if (!arg.startsWith("--")) {
      positionals.push(arg);
      continue;
    }
    const name = arg.slice(2);
    if (booleans.includes(name)) {
      flags[name] = true;
      continue;
    }
    if (!values.includes(name) && !multi.includes(name)) throw new ToolingError(`unknown flag ${arg}`);
    const value = argv[i + 1];
    if (value === undefined || value.startsWith("--")) throw new ToolingError(`${arg} needs a value`);
    i++;
    if (multi.includes(name)) flags[name].push(value);
    else flags[name] = value;
  }
  return { flags, positionals };
}

/** Resolve `input` against `root` and refuse anything that lands outside it. */
export function confined(root, input, label = "path") {
  if (typeof input !== "string" || !input || input.includes("\0")) {
    throw new ToolingError(`${label} must be a non-empty path`);
  }
  const base = resolve(root);
  const abs = resolve(base, input);
  const rel = relative(base, abs);
  if (rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel)) {
    throw new ToolingError(`${label} escapes the workspace root ${base}: ${input}`);
  }
  return abs;
}

/** `abs` must be an existing regular file; otherwise the probe cannot run. */
export function requireFile(abs, label = "file") {
  if (!existsSync(abs) || !statSync(abs).isFile()) throw new ToolingError(`${label} is not a file: ${abs}`);
  return abs;
}

/** Parse brand tokens.json. A missing or unreadable pack is a tooling failure. */
export function loadTokens(path) {
  let text;
  try {
    text = readFileSync(path, "utf8");
  } catch (error) {
    throw new ToolingError(`cannot read brand tokens ${path} (${error.code || error.message})`);
  }
  try {
    const tokens = JSON.parse(text);
    if (!tokens?.design || !tokens?.copy) throw new Error("missing design or copy section");
    return tokens;
  } catch (error) {
    throw new ToolingError(`brand tokens ${path} are invalid: ${error.message}`);
  }
}

/** The lead face of each brand font stack (display, text, mono), deduplicated. */
export function brandLeadFonts(tokens) {
  const stacks = tokens.design.fontStacks || {};
  return [...new Set(["display", "text", "mono"].map((role) => stacks[role]?.[0]).filter(Boolean))];
}

/** `require` a package from the pinned render toolchain. */
export function renderRequire(name) {
  try {
    return createRequire(join(RENDER_DIR, "package.json"))(name);
  } catch (error) {
    throw new ToolingError(
      `${name} is not installed in ${RENDER_DIR} (${error.code || error.message}); run inside the ` +
        "sandbox image or set DESIGN_AGENT_RENDER_DIR to a directory with the pinned render toolchain",
    );
  }
}

/** Launch the sandbox Chrome with the shared export flags. */
export async function launchBrowser(extraArgs = []) {
  const puppeteer = renderRequire("puppeteer-core");
  if (!existsSync(BROWSER)) {
    throw new ToolingError(`no browser at ${BROWSER}; set DESIGN_AGENT_BROWSER or run inside the sandbox image`);
  }
  try {
    return await puppeteer.launch({
      executablePath: BROWSER,
      headless: "shell",
      args: [...CHROMIUM_EXPORT_ARGS, ...extraArgs],
    });
  } catch (error) {
    throw new ToolingError(`could not launch ${BROWSER}: ${error.message}`);
  }
}

/** Collect page errors and failed requests while a page loads. */
export function watchPage(page) {
  const problems = { pageErrors: [], failedRequests: [] };
  page.on("pageerror", (error) => problems.pageErrors.push(String(error?.message || error).slice(0, 300)));
  page.on("requestfailed", (request) =>
    problems.failedRequests.push(`${request.url().slice(0, 200)} (${request.failure()?.errorText || "failed"})`),
  );
  return problems;
}

const PROBE_ATTR = "data-design-agent-font-probe";

/**
 * Families that did not actually render. `document.fonts.check()` alone cannot prove a family
 * resolved: Chromium answers true for any family no @font-face declares, installed or not. So each
 * family must pass `check()` (which fails a declared face that did not load) AND paint a probe span
 * that CDP attributes to that platform font. A missing font never fails loudly in a browser; this is
 * what makes it fail.
 * @returns {Promise<{family: string, renderedWith: string}[]>}
 */
export async function unresolvedFonts(page, families) {
  if (!families.length) return [];
  await page.evaluate(() => document.fonts?.ready);
  const cdp = await page.createCDPSession();
  const missing = [];
  try {
    await cdp.send("DOM.enable");
    await cdp.send("CSS.enable");
    for (const family of families) {
      const checked = await page.evaluate(
        async (name, attr) => {
          const spec = `16px ${JSON.stringify(name)}`;
          try {
            await document.fonts.load(spec);
          } catch {
            /* check() below reports it */
          }
          const probe = document.createElement("span");
          probe.setAttribute(attr, "");
          probe.textContent = "Hamburgefonstiv 0123456789";
          probe.style.setProperty("position", "absolute", "important");
          probe.style.setProperty("left", "-10000px", "important");
          probe.style.setProperty("top", "0", "important");
          probe.style.setProperty("font-family", `${JSON.stringify(name)}, monospace`, "important");
          document.body.appendChild(probe);
          // CDP reports platform fonts from layout, so lay the probe out and let a frame paint.
          void probe.getBoundingClientRect();
          await new Promise((done) => requestAnimationFrame(() => requestAnimationFrame(done)));
          return document.fonts.check(spec);
        },
        family,
        PROBE_ATTR,
      );
      const { root } = await cdp.send("DOM.getDocument", { depth: 1 });
      const { nodeId } = await cdp.send("DOM.querySelector", { nodeId: root.nodeId, selector: `[${PROBE_ATTR}]` });
      const { fonts } = await cdp.send("CSS.getPlatformFontsForNode", { nodeId });
      await page.evaluate((attr) => document.querySelectorAll(`[${attr}]`).forEach((el) => el.remove()), PROBE_ATTR);
      const used = fonts.map((font) => font.familyName);
      // A system font reports its family; a web font (an @font-face rule, as woff2 faces must be)
      // reports the name inside its file ("Brand Sans 250"), so it counts when a face registered
      // under the requested family loaded and a web font painted the probe.
      const webFace = await page.evaluate(
        (name) =>
          [...document.fonts].some(
            (face) => face.status === "loaded" && face.family.replace(/^["']|["']$/g, "").toLowerCase() === name.toLowerCase(),
          ),
        family,
      );
      const painted =
        used.some((name) => name.toLowerCase() === family.toLowerCase()) || (webFace && fonts.some((font) => font.isCustomFont));
      if (!checked || !painted) {
        missing.push({ family, renderedWith: used.join(", ") || "nothing" });
      }
    }
  } finally {
    await cdp.detach().catch(() => {});
  }
  return missing;
}