basis-design 0.1.1 → 0.2.0

package/server/template.ts

@@ -1,168 +1,168 @@
-import { execFileSync } from "node:child_process";
-import { createHash } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
-import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
-import type { TemplateUpdate } from "../shared/protocol.ts";
-import { repoRoot, SOURCE_DIRS } from "./paths.ts";
-
-/*
- * Keeping workspaces up to date with Basis' starter template (template/). A workspace owns its copy, so Basis
- * replaces only files nobody changed: those that still match an earlier version of the template, listed in
- * template/history.json. For files the agent has changed, Basis offers a guided turn that brings in what
- * template/CHANGES.md describes, from a copy of the template in .basis/template/.
- */
-
-/** Earlier versions of each starter file, by workspace-relative path (written by scripts/template-history.ts). */
-export const TEMPLATE_HISTORY_FILE = "template/history.json";
-
-/**
- * The version of the starter template. Raise it, with a section in template/CHANGES.md, when the template changes
- * in a way worth bringing into workspaces whose agent has changed their components.
- */
-export const TEMPLATE_VERSION = 1;
-
-/** Where a workspace records the template version it has caught up with. */
-const VERSION_FILE = path.join(".basis", "template.json");
-
-/** The copy of the current template the agent compares against during the guided turn. */
-export const TEMPLATE_COPY = ".basis/template";
-
-export function hashText(text: string): string {
-  return createHash("sha256").update(text.replaceAll("\r\n", "\n")).digest("hex");
-}
-
-/** The starter files, as workspace-relative forward-slash paths ("components/Button.tsx"). */
-export async function templateFiles(root = repoRoot): Promise<string[]> {
-  const files: string[] = [];
-  for (const dir of SOURCE_DIRS) {
-    const names = await readdir(path.join(root, "template", dir)).catch(() => [] as string[]);
-    files.push(...names.sort().map((name) => `${dir}/${name}`));
-  }
-  return files;
-}
-
-/**
- * The hashes of every earlier version of each starter file, read from git. Only the script that writes
- * template/history.json and its test use it; an installed Basis has no git history.
- */
-export function earlierTemplateHashes(root: string): Record<string, string[]> {
-  const git = (args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 64 << 20 });
-  const history: Record<string, string[]> = {};
-  const current = git(["ls-files", ...SOURCE_DIRS.map((dir) => `template/${dir}`)])
-    .split("\n")
-    .filter((file) => file && file.split("/").length === 3);
-  for (const file of current) {
-    // The file as it is now, committed or not: the version a workspace should end up with.
-    const now = hashText(readFileSync(path.join(root, file), "utf8"));
-    const hashes = new Set<string>();
-    for (const commit of git(["log", "--format=%H", "--", file]).split("\n").filter(Boolean)) {
-      let text: string;
-      try {
-        text = git(["show", `${commit}:${file}`]);
-      } catch {
-        continue; // The commit removed the file.
-      }
-      const hash = hashText(text);
-      if (hash !== now) hashes.add(hash);
-    }
-    if (hashes.size) history[file.slice("template/".length)] = [...hashes].sort();
-  }
-  return history;
-}
-
-/**
- * The files that belong together: a component's source, stylesheet and specimen share the part of their name
- * before the first dot ("patterns/Navbar"), and a new Navbar.tsx needs the stylesheet written for it.
- */
-function unitOf(file: string): string {
-  const slash = file.lastIndexOf("/");
-  return file.slice(0, slash + 1) + file.slice(slash + 1).split(".")[0];
-}
-
-/**
- * Replaces starter files that still match an earlier version of the template with the current one, a unit at a
- * time (see unitOf): a unit is updated only when none of its files was changed, so a component is never left with a
- * new source and an old stylesheet. Returns the paths it replaced. Changed or removed files are left alone.
- */
-export async function updateUntouchedStarterFiles(dir: string): Promise<string[]> {
-  const history = JSON.parse(await readFile(path.join(repoRoot, TEMPLATE_HISTORY_FILE), "utf8")) as Record<
-    string,
-    string[]
-  >;
-  const units = new Map<string, { file: string; current: string; ours: string }[]>();
-  for (const file of await templateFiles()) {
-    const target = path.join(dir, file);
-    if (!existsSync(target)) continue;
-    const current = (await readFile(path.join(repoRoot, "template", file), "utf8")).replaceAll("\r\n", "\n");
-    const files = units.get(unitOf(file)) ?? [];
-    files.push({ file, current, ours: hashText(await readFile(target, "utf8")) });
-    units.set(unitOf(file), files);
-  }
-  const updated: string[] = [];
-  for (const files of units.values()) {
-    const untouched = files.every(
-      ({ file, current, ours }) => ours === hashText(current) || history[file]?.includes(ours),
-    );
-    if (!untouched) continue;
-    for (const { file, current, ours } of files) {
-      if (ours === hashText(current)) continue;
-      await writeFile(path.join(dir, file), current);
-      updated.push(file);
-    }
-  }
-  return updated;
-}
-
-export async function recordedTemplateVersion(dir: string): Promise<number> {
-  try {
-    return Number(JSON.parse(await readFile(path.join(dir, VERSION_FILE), "utf8")).version) || 0;
-  } catch {
-    return 0;
-  }
-}
-
-export async function recordTemplateVersion(dir: string, version = TEMPLATE_VERSION): Promise<void> {
-  await mkdir(path.join(dir, ".basis"), { recursive: true });
-  await writeFile(path.join(dir, VERSION_FILE), `${JSON.stringify({ version })}\n`);
-}
-
-/**
- * Whether the workspace is behind the template. A workspace whose starter files all match the current template
- * has nothing to bring in, so it is recorded as caught up.
- */
-export async function templateUpdate(dir: string): Promise<TemplateUpdate | null> {
-  const from = await recordedTemplateVersion(dir);
-  if (from >= TEMPLATE_VERSION) return null;
-  const files: string[] = [];
-  for (const file of await templateFiles()) {
-    const target = path.join(dir, file);
-    if (!existsSync(target)) continue;
-    const ours = hashText(await readFile(target, "utf8"));
-    if (ours !== hashText(await readFile(path.join(repoRoot, "template", file), "utf8"))) files.push(file);
-  }
-  if (files.length === 0) {
-    await recordTemplateVersion(dir);
-    return null;
-  }
-  return { from, to: TEMPLATE_VERSION, files };
-}
-
-/** The sections of template/CHANGES.md newer than `from`. */
-export async function templateChanges(from: number): Promise<string> {
-  const text = (await readFile(path.join(repoRoot, "template", "CHANGES.md"), "utf8")).replaceAll("\r\n", "\n");
-  return text
-    .split(/^(?=## )/m)
-    .filter((section) => Number(section.match(/^## (\d+)/)?.[1] ?? 0) > from)
-    .join("")
-    .trim();
-}
-
-/** Copies the current template into the workspace for the guided turn to read (it is generated, not history). */
-export async function writeTemplateCopy(dir: string): Promise<void> {
-  const target = path.join(dir, TEMPLATE_COPY);
-  await rm(target, { recursive: true, force: true });
-  for (const folder of SOURCE_DIRS) {
-    await cp(path.join(repoRoot, "template", folder), path.join(target, folder), { recursive: true });
-  }
-}
+import { execFileSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { cp, mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import type { TemplateUpdate } from "../shared/protocol.ts";
+import { repoRoot, SOURCE_DIRS } from "./paths.ts";
+
+/*
+ * Keeping workspaces up to date with Basis' starter template (template/). A workspace owns its copy, so Basis
+ * replaces only files nobody changed: those that still match an earlier version of the template, listed in
+ * template/history.json. For files the agent has changed, Basis offers a guided turn that brings in what
+ * template/CHANGES.md describes, from a copy of the template in .basis/template/.
+ */
+
+/** Earlier versions of each starter file, by workspace-relative path (written by scripts/template-history.ts). */
+export const TEMPLATE_HISTORY_FILE = "template/history.json";
+
+/**
+ * The version of the starter template. Raise it, with a section in template/CHANGES.md, when the template changes
+ * in a way worth bringing into workspaces whose agent has changed their components.
+ */
+export const TEMPLATE_VERSION = 1;
+
+/** Where a workspace records the template version it has caught up with. */
+const VERSION_FILE = path.join(".basis", "template.json");
+
+/** The copy of the current template the agent compares against during the guided turn. */
+export const TEMPLATE_COPY = ".basis/template";
+
+export function hashText(text: string): string {
+  return createHash("sha256").update(text.replaceAll("\r\n", "\n")).digest("hex");
+}
+
+/** The starter files, as workspace-relative forward-slash paths ("components/Button.tsx"). */
+export async function templateFiles(root = repoRoot): Promise<string[]> {
+  const files: string[] = [];
+  for (const dir of SOURCE_DIRS) {
+    const names = await readdir(path.join(root, "template", dir)).catch(() => [] as string[]);
+    files.push(...names.sort().map((name) => `${dir}/${name}`));
+  }
+  return files;
+}
+
+/**
+ * The hashes of every earlier version of each starter file, read from git. Only the script that writes
+ * template/history.json and its test use it; an installed Basis has no git history.
+ */
+export function earlierTemplateHashes(root: string): Record<string, string[]> {
+  const git = (args: string[]) => execFileSync("git", args, { cwd: root, encoding: "utf8", maxBuffer: 64 << 20 });
+  const history: Record<string, string[]> = {};
+  const current = git(["ls-files", ...SOURCE_DIRS.map((dir) => `template/${dir}`)])
+    .split("\n")
+    .filter((file) => file && file.split("/").length === 3);
+  for (const file of current) {
+    // The file as it is now, committed or not: the version a workspace should end up with.
+    const now = hashText(readFileSync(path.join(root, file), "utf8"));
+    const hashes = new Set<string>();
+    for (const commit of git(["log", "--format=%H", "--", file]).split("\n").filter(Boolean)) {
+      let text: string;
+      try {
+        text = git(["show", `${commit}:${file}`]);
+      } catch {
+        continue; // The commit removed the file.
+      }
+      const hash = hashText(text);
+      if (hash !== now) hashes.add(hash);
+    }
+    if (hashes.size) history[file.slice("template/".length)] = [...hashes].sort();
+  }
+  return history;
+}
+
+/**
+ * The files that belong together: a component's source, stylesheet and specimen share the part of their name
+ * before the first dot ("patterns/Navbar"), and a new Navbar.tsx needs the stylesheet written for it.
+ */
+function unitOf(file: string): string {
+  const slash = file.lastIndexOf("/");
+  return file.slice(0, slash + 1) + file.slice(slash + 1).split(".")[0];
+}
+
+/**
+ * Replaces starter files that still match an earlier version of the template with the current one, a unit at a
+ * time (see unitOf): a unit is updated only when none of its files was changed, so a component is never left with a
+ * new source and an old stylesheet. Returns the paths it replaced. Changed or removed files are left alone.
+ */
+export async function updateUntouchedStarterFiles(dir: string): Promise<string[]> {
+  const history = JSON.parse(await readFile(path.join(repoRoot, TEMPLATE_HISTORY_FILE), "utf8")) as Record<
+    string,
+    string[]
+  >;
+  const units = new Map<string, { file: string; current: string; ours: string }[]>();
+  for (const file of await templateFiles()) {
+    const target = path.join(dir, file);
+    if (!existsSync(target)) continue;
+    const current = (await readFile(path.join(repoRoot, "template", file), "utf8")).replaceAll("\r\n", "\n");
+    const files = units.get(unitOf(file)) ?? [];
+    files.push({ file, current, ours: hashText(await readFile(target, "utf8")) });
+    units.set(unitOf(file), files);
+  }
+  const updated: string[] = [];
+  for (const files of units.values()) {
+    const untouched = files.every(
+      ({ file, current, ours }) => ours === hashText(current) || history[file]?.includes(ours),
+    );
+    if (!untouched) continue;
+    for (const { file, current, ours } of files) {
+      if (ours === hashText(current)) continue;
+      await writeFile(path.join(dir, file), current);
+      updated.push(file);
+    }
+  }
+  return updated;
+}
+
+export async function recordedTemplateVersion(dir: string): Promise<number> {
+  try {
+    return Number(JSON.parse(await readFile(path.join(dir, VERSION_FILE), "utf8")).version) || 0;
+  } catch {
+    return 0;
+  }
+}
+
+export async function recordTemplateVersion(dir: string, version = TEMPLATE_VERSION): Promise<void> {
+  await mkdir(path.join(dir, ".basis"), { recursive: true });
+  await writeFile(path.join(dir, VERSION_FILE), `${JSON.stringify({ version })}\n`);
+}
+
+/**
+ * Whether the workspace is behind the template. A workspace whose starter files all match the current template
+ * has nothing to bring in, so it is recorded as caught up.
+ */
+export async function templateUpdate(dir: string): Promise<TemplateUpdate | null> {
+  const from = await recordedTemplateVersion(dir);
+  if (from >= TEMPLATE_VERSION) return null;
+  const files: string[] = [];
+  for (const file of await templateFiles()) {
+    const target = path.join(dir, file);
+    if (!existsSync(target)) continue;
+    const ours = hashText(await readFile(target, "utf8"));
+    if (ours !== hashText(await readFile(path.join(repoRoot, "template", file), "utf8"))) files.push(file);
+  }
+  if (files.length === 0) {
+    await recordTemplateVersion(dir);
+    return null;
+  }
+  return { from, to: TEMPLATE_VERSION, files };
+}
+
+/** The sections of template/CHANGES.md newer than `from`. */
+export async function templateChanges(from: number): Promise<string> {
+  const text = (await readFile(path.join(repoRoot, "template", "CHANGES.md"), "utf8")).replaceAll("\r\n", "\n");
+  return text
+    .split(/^(?=## )/m)
+    .filter((section) => Number(section.match(/^## (\d+)/)?.[1] ?? 0) > from)
+    .join("")
+    .trim();
+}
+
+/** Copies the current template into the workspace for the guided turn to read (it is generated, not history). */
+export async function writeTemplateCopy(dir: string): Promise<void> {
+  const target = path.join(dir, TEMPLATE_COPY);
+  await rm(target, { recursive: true, force: true });
+  for (const folder of SOURCE_DIRS) {
+    await cp(path.join(repoRoot, "template", folder), path.join(target, folder), { recursive: true });
+  }
+}

package/server/verify-kit/capture.mjs

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+/*
+ * Takes the verification kit's screenshots on this machine, with the settings Basis used (basis-verify.json):
+ *
+ *   node basis-verify/capture.mjs design [--out <dir>]                     the design, into expected/
+ *   node basis-verify/capture.mjs app [--targets <file>] [--out <dir>]     the implementation, into actual/
+ *
+ * Options for both: --only <view>[/<screen>] to capture part of the kit, --channel chrome|msedge to use an
+ * installed browser instead of Playwright's Chromium.
+ *
+ * Needs Playwright in the project (`npm i -D playwright` and `npx playwright install chromium`). Capture both
+ * sides with the same machine and browser: fonts and antialiasing differ between systems, so only images taken
+ * the same way can match pixel for pixel. Compare them with compare.mjs.
+ */
+import { existsSync } from "node:fs";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import http from "node:http";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const kit = path.dirname(fileURLToPath(import.meta.url));
+const args = process.argv.slice(2);
+const mode = args[0];
+
+function option(name, fallback) {
+  const index = args.indexOf(name);
+  return index === -1 ? fallback : args[index + 1];
+}
+
+async function playwright() {
+  for (const name of ["playwright", "playwright-core", "@playwright/test"]) {
+    try {
+      const module = await import(name);
+      return module.chromium ?? module.default?.chromium;
+    } catch {
+      // Not installed here; try the next one.
+    }
+  }
+  throw new Error(
+    "Playwright is not installed in this project. Run `npm i -D playwright` and `npx playwright install chromium`.",
+  );
+}
+
+const TYPES = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".woff2": "font/woff2",
+  ".woff": "font/woff",
+};
+
+/** Serves the kit's copy of the design on a free local port. */
+async function serveDesign() {
+  const root = path.join(kit, "design");
+  const server = http.createServer(async (req, res) => {
+    const pathname = decodeURIComponent(new URL(req.url ?? "/", "http://local").pathname);
+    const file = path.join(root, pathname === "/" ? "index.html" : pathname);
+    if (!file.startsWith(root + path.sep)) {
+      res.writeHead(403).end();
+      return;
+    }
+    try {
+      const body = await readFile(file);
+      res.writeHead(200, { "Content-Type": TYPES[path.extname(file)] ?? "application/octet-stream" });
+      res.end(body);
+    } catch {
+      res.writeHead(404).end();
+    }
+  });
+  await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
+  return { server, url: `http://127.0.0.1:${server.address().port}/index.html` };
+}
+
+/** Waits until fonts are loaded, images decoded and the layout keeps its size, as the design's page does. */
+async function settle(page) {
+  await page.evaluate(async () => {
+    const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+    await document.fonts.ready;
+    await Promise.all([...document.images].map((image) => image.decode().catch(() => undefined)));
+    let last = "";
+    for (let attempt = 0; attempt < 40; attempt++) {
+      await wait(50);
+      const size = `${document.documentElement.scrollWidth}x${document.documentElement.scrollHeight}`;
+      if (size === last) break;
+      last = size;
+    }
+  });
+}
+
+function targetFor(targets, view, screen) {
+  const entry = targets.screens?.[`${view}/${screen}`];
+  if (!entry) return undefined;
+  const target = typeof entry === "string" ? { url: entry } : entry;
+  return { ...target, url: new URL(target.url, targets.baseUrl ?? undefined).href };
+}
+
+async function main() {
+  if (mode !== "design" && mode !== "app") {
+    console.error("Usage: node capture.mjs design|app [--targets <file>] [--out <dir>] [--only <view>[/<screen>]]");
+    process.exitCode = 2;
+    return;
+  }
+  const manifest = JSON.parse(await readFile(path.join(kit, "basis-verify.json"), "utf8"));
+  const { render } = manifest;
+  const out = option("--out")
+    ? path.resolve(option("--out"))
+    : path.join(kit, mode === "design" ? "expected" : "actual");
+  const only = option("--only");
+  let targets = {};
+  const targetsFile = option("--targets") ? path.resolve(option("--targets")) : path.join(kit, "targets.json");
+  if (mode === "app") {
+    if (!existsSync(targetsFile)) {
+      throw new Error(`No targets file at ${targetsFile}. See README.md, "Capture the implementation".`);
+    }
+    targets = JSON.parse(await readFile(targetsFile, "utf8"));
+  }
+
+  const chromium = await playwright();
+  const browser = await chromium.launch({ headless: true, args: render.args, channel: option("--channel") });
+  console.log(
+    `Browser: ${browser.version()}${browser.version() === manifest.browser.version ? "" : ` (Basis used ${manifest.browser.version})`}`,
+  );
+  const design = mode === "design" ? await serveDesign() : undefined;
+  const context = await browser.newContext({
+    deviceScaleFactor: render.deviceScaleFactor,
+    reducedMotion: render.reducedMotion,
+    colorScheme: render.colorScheme,
+    viewport: { width: 1440, height: 900 },
+    ...(mode === "app" && targets.storageState
+      ? { storageState: path.resolve(path.dirname(targetsFile), targets.storageState) }
+      : {}),
+  });
+  const page = await context.newPage();
+  let taken = 0;
+  let skipped = 0;
+  const unstable = [];
+  try {
+    for (const view of manifest.views) {
+      for (const screen of view.screens) {
+        const key = `${view.id}/${screen.id}`;
+        if (only && only !== view.id && only !== key) continue;
+        const target = mode === "app" ? targetFor(targets, view.id, screen.id) : undefined;
+        if (mode === "app" && !target) {
+          console.log(`skip     ${key}: no target in targets.json`);
+          skipped++;
+          continue;
+        }
+        for (const shot of screen.shots) {
+          await page.setViewportSize({ width: shot.width, height: shot.viewportHeight });
+          await page.emulateMedia({ colorScheme: shot.theme });
+          const take = async () => {
+            if (design) {
+              const query = `?view=${encodeURIComponent(view.id)}&screen=${encodeURIComponent(screen.id)}&theme=${shot.theme}`;
+              await page.goto(design.url + query);
+              await page.waitForSelector(manifest.design.ready, { state: "attached", timeout: 60_000 });
+            } else {
+              await page.goto(target.url, { waitUntil: "networkidle" });
+              if (target.waitFor) await page.waitForSelector(target.waitFor, { timeout: 60_000 });
+              if (targets.themeAttribute) {
+                await page.evaluate(
+                  ([name, value]) => document.documentElement.setAttribute(name, value),
+                  [targets.themeAttribute, shot.theme],
+                );
+              }
+              await page.addStyleTag({ content: render.neutralCss });
+              await settle(page);
+            }
+            return page.screenshot({ fullPage: shot.fullPage, animations: "disabled", caret: "hide" });
+          };
+          const first = await take();
+          const second = await take();
+          const name = shot.file.replace(/^screens\//, "");
+          const file = path.join(out, name);
+          await mkdir(path.dirname(file), { recursive: true });
+          await writeFile(file, first);
+          taken++;
+          const stable = first.equals(second);
+          if (!stable) unstable.push(name);
+          console.log(`${stable ? "ok      " : "UNSTABLE"} ${name}`);
+        }
+      }
+    }
+  } finally {
+    await context.close();
+    await browser.close();
+    design?.server.close();
+  }
+  console.log(
+    `\n${taken} shots in ${path.relative(process.cwd(), out) || "."}${skipped ? `, ${skipped} screens without a target` : ""}.`,
+  );
+  if (unstable.length) {
+    console.log(
+      `${unstable.length} shots differed between two captures, so they can never match exactly: ${unstable.join(", ")}. ` +
+        "Look for clocks, random values, animations or content that loads late.",
+    );
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.message : error);
+  process.exitCode = 2;
+});

package/server/verify-kit/compare.d.mts

@@ -0,0 +1,39 @@
+export interface Image {
+  width: number;
+  height: number;
+  data: Buffer;
+}
+export interface Region {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+export interface Exception {
+  name: string;
+  reason?: string;
+  view: string;
+  screen?: string;
+  widths?: number[];
+  themes?: string[];
+  region?: Region;
+}
+export function decodePng(buffer: Buffer): Image;
+export function encodePng(image: Image): Buffer;
+export function compareImages(
+  expected: Image,
+  actual: Image,
+  options?: { tolerance?: number; regions?: Region[] },
+): {
+  width: number;
+  height: number;
+  sameSize: boolean;
+  differing: number;
+  counted: number;
+  percent: number;
+  diff: Image;
+};
+export function exceptionsFor<T extends Exception>(
+  exceptions: T[],
+  shot: { view: string; screen: string; width: number; theme: string },
+): T[];