basis-design 0.1.0 → 0.2.0

package/server/setup.ts

@@ -1,219 +1,201 @@
-import { createHash } from "node:crypto";
-import { existsSync } from "node:fs";
-import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
-import { createRequire } from "node:module";
-import path from "node:path";
-import { REVIEW_FILE } from "../shared/review.ts";
-import { AGENT_BRIEF, CLAUDE_MD } from "./brief.ts";
-import { COMPONENTS_DIR, PATTERNS_DIR, repoRoot, SOURCE_DIRS, VIEWS_DIR } from "./paths.ts";
-
-const require = createRequire(import.meta.url);
-
-/*
- * Getting a workspace ready on every start: starter source for new
- * workspaces, what Basis added since for older ones, and the files Basis owns.
- */
-
-/**
- * Seeds a new workspace from template/, or brings an older one up to date.
- * Returns a note for the history entry ("Basis added component contracts"),
- * or "" when nothing an existing workspace would notice was added.
- */
-export async function seedWorkspace(dir: string): Promise<string> {
-  const components = path.join(dir, COMPONENTS_DIR);
-  const notes: string[] = [];
-  if (!existsSync(components)) await seed(dir, COMPONENTS_DIR);
-  else if (!existsSync(path.join(components, "specimen.ts"))) {
-    await seed(dir, COMPONENTS_DIR, (name) => name.includes("specimen"));
-    notes.push("gallery specimens");
-  }
-  if (!existsSync(path.join(components, "contracts.ts"))) {
-    await seed(dir, COMPONENTS_DIR, (name) => name === "contracts.ts");
-    notes.push("component contracts");
-  }
-  if (!existsSync(path.join(dir, PATTERNS_DIR))) {
-    const fresh = notes.length === 0 && !existsSync(path.join(dir, ".git"));
-    await seed(dir, PATTERNS_DIR);
-    if (!fresh) notes.push("starter patterns");
-  } else {
-    if (!existsSync(path.join(dir, PATTERNS_DIR, "contracts.ts"))) {
-      await seed(dir, PATTERNS_DIR, (name) => name === "contracts.ts");
-      notes.push("pattern contracts");
-    }
-    const added = await addLaterPatterns(dir);
-    if (added.length) notes.push(`the ${added.join(" and ")} pattern${added.length > 1 ? "s" : ""}`);
-  }
-  if (!existsSync(path.join(dir, VIEWS_DIR))) {
-    const fresh = notes.length === 0 && !existsSync(path.join(dir, ".git"));
-    await seed(dir, VIEWS_DIR);
-    if (!fresh) notes.push("a starter view");
-  }
-  if (await updateSpecimenFormat(dir)) notes.push("the newest specimen format");
-  return notes.length ? `Basis added ${notes.join(" and ")}` : "";
-}
-
-/**
- * Starter patterns added to the baseline after workspaces already had patterns/.
- * Older workspaces get their files and an export in patterns/index.ts, since the
- * baseline contract requires them.
- */
-const LATER_PATTERNS = ["Composer", "Chat"];
-
-async function addLaterPatterns(dir: string): Promise<string[]> {
-  const index = path.join(dir, PATTERNS_DIR, "index.ts");
-  const added: string[] = [];
-  for (const name of LATER_PATTERNS) {
-    if (existsSync(path.join(dir, PATTERNS_DIR, `${name}.tsx`))) continue;
-    await seed(dir, PATTERNS_DIR, (file) => file.startsWith(`${name}.`));
-    const exports = await readFile(index, "utf8").catch(() => "");
-    if (!exports.includes(`"./${name}.tsx"`)) {
-      const separator = exports === "" || exports.endsWith("\n") ? "" : "\n";
-      await writeFile(index, `${exports}${separator}export * from "./${name}.tsx";\n`);
-    }
-    added.push(name);
-  }
-  return added;
-}
-
-/**
- * components/specimen.ts is Basis' specimen format, seeded once. When it is an
- * untouched copy of an earlier version, it is replaced with the current one;
- * a copy someone changed is left alone. Add the hash of the current template
- * here whenever the template changes (sha256 of its text with LF line endings).
- */
-const EARLIER_SPECIMEN_FORMATS = new Set([
-  "e04c6fc2a3e85090b7672d229d95ca8c5a42009f6397332230d324357b993169",
-  "03370daf9bba1c4329d3dac7b76199970cab9c11a6ea2d23e1a484ead80d36d6",
-  "1f826f8c8f183e311fd20cca0e5e3c138ac2775c4e156862600c24e9dad7cf7d",
-]);
-
-async function updateSpecimenFormat(dir: string): Promise<boolean> {
-  const file = path.join(dir, COMPONENTS_DIR, "specimen.ts");
-  const current = (await readFile(file, "utf8").catch(() => "")).replaceAll("\r\n", "\n");
-  if (!EARLIER_SPECIMEN_FORMATS.has(createHash("sha256").update(current).digest("hex"))) return false;
-  const template = await readFile(path.join(repoRoot, "template", COMPONENTS_DIR, "specimen.ts"), "utf8");
-  await writeFile(file, template.replaceAll("\r\n", "\n"));
-  return true;
-}
-
-/**
- * Copies starter files from template/<folder> that are missing, normalising
- * line endings (a Windows checkout of Basis may have CRLF).
- */
-async function seed(dir: string, folder: string, only: (name: string) => boolean = () => true): Promise<void> {
-  const source = path.join(repoRoot, "template", folder);
-  const destination = path.join(dir, folder);
-  await mkdir(destination, { recursive: true });
-  for (const name of await readdir(source)) {
-    if (!only(name) || existsSync(path.join(destination, name))) continue;
-    const text = await readFile(path.join(source, name), "utf8");
-    await writeFile(path.join(destination, name), text.replaceAll("\r\n", "\n"));
-  }
-}
-
-/**
- * The workspace format this Basis writes. Raise it when a change means an older Basis would misread or damage a
- * workspace this one has opened; an older Basis then refuses to open it instead.
- */
-export const WORKSPACE_FORMAT = 1;
-
-/** Refuses a workspace a newer Basis has opened, and marks it with this Basis' format otherwise. */
-export async function claimWorkspaceFormat(dir: string): Promise<void> {
-  const file = path.join(dir, ".basis", "format.json");
-  const saved = existsSync(file) ? Number(JSON.parse(await readFile(file, "utf8")).format) || 0 : 0;
-  if (saved > WORKSPACE_FORMAT) {
-    throw new Error("a newer version of Basis has opened this project. Update Basis to open it again.");
-  }
-  await mkdir(path.dirname(file), { recursive: true });
-  await writeFile(file, `${JSON.stringify({ format: WORKSPACE_FORMAT })}\n`);
-}
-
-/** Files Basis owns in the workspace, rewritten on every start and kept out of history. */
-export async function writeGeneratedFiles(dir: string): Promise<void> {
-  const basisDir = path.join(dir, ".basis");
-  await mkdir(basisDir, { recursive: true });
-  // Resolved, not joined onto Basis' folder: an npm install may hoist them to a node_modules above it.
-  const types = (pkg: string) =>
-    path
-      .dirname(require.resolve(`${pkg}/package.json`))
-      .split(path.sep)
-      .join("/");
-  const tsconfig = {
-    compilerOptions: {
-      target: "ES2022",
-      lib: ["ES2022", "DOM", "DOM.Iterable"],
-      module: "ESNext",
-      moduleResolution: "bundler",
-      jsx: "react-jsx",
-      strict: true,
-      noEmit: true,
-      skipLibCheck: true,
-      isolatedModules: true,
-      allowImportingTsExtensions: true,
-      types: [],
-      // Resolve React's types from the Basis install, wherever this workspace lives.
-      paths: {
-        react: [`${types("@types/react")}/index.d.ts`],
-        "react/*": [`${types("@types/react")}/*`],
-        "react-dom": [`${types("@types/react-dom")}/index.d.ts`],
-        "react-dom/*": [`${types("@types/react-dom")}/*`],
-      },
-    },
-    include: [...SOURCE_DIRS.map((folder) => `${folder}/**/*`), ".basis/*.ts"],
-  };
-  await writeFile(path.join(dir, "tsconfig.json"), `${JSON.stringify(tsconfig, null, 2)}\n`);
-  await writeFile(
-    path.join(basisDir, "contracts.ts"),
-    await readFile(path.join(repoRoot, "shared", "contracts.ts"), "utf8"),
-  );
-  await writeFile(
-    path.join(basisDir, "pattern-contracts.ts"),
-    await readFile(path.join(repoRoot, "shared", "pattern-contracts.ts"), "utf8"),
-  );
-  await writeFile(
-    path.join(basisDir, "guidelines.md"),
-    await readFile(path.join(repoRoot, "server", "guidelines.md"), "utf8"),
-  );
-  await writeFile(
-    path.join(basisDir, "env.d.ts"),
-    'declare module "*.module.css" {\n  const classes: Record<string, string>;\n  export default classes;\n}\n',
-  );
-  await writeFile(
-    path.join(basisDir, "check.ts"),
-    [
-      "// Fails to type-check when components/ or patterns/ stop satisfying their contracts: the Basis",
-      "// baselines (./contracts.ts, ./pattern-contracts.ts) and the contracts this design system added",
-      "// (components/contracts.ts, patterns/contracts.ts).",
-      'import type { Contracts } from "./contracts.ts";',
-      'import type { AddedContracts } from "../components/contracts.ts";',
-      'import * as components from "../components/index.ts";',
-      'import type { PatternContracts } from "./pattern-contracts.ts";',
-      'import type { AddedPatternContracts } from "../patterns/contracts.ts";',
-      'import type { IconName } from "../patterns/icons.tsx";',
-      'import * as patterns from "../patterns/index.ts";',
-      "",
-      "export const satisfiesContracts: Contracts & AddedContracts = components;",
-      "export const satisfiesPatternContracts: PatternContracts<IconName> & AddedPatternContracts = patterns;",
-      "",
-      "// Every export of components/index.ts needs a contract; add missing ones to components/contracts.ts.",
-      "type Uncovered = Exclude<keyof typeof components, keyof Contracts | keyof AddedContracts>;",
-      "export const everyExportHasAContract: [Uncovered] extends [never] ? true : { missingContractFor: Uncovered } = true;",
-      "",
-      "// Every export of patterns/index.ts needs a contract; add missing ones to patterns/contracts.ts.",
-      "type UncoveredPattern = Exclude<",
-      "  keyof typeof patterns,",
-      "  keyof PatternContracts<IconName> | keyof AddedPatternContracts",
-      ">;",
-      "export const everyPatternHasAContract: [UncoveredPattern] extends [never]",
-      "  ? true",
-      "  : { missingContractFor: UncoveredPattern } = true;",
-      "",
-    ].join("\n"),
-  );
-  await writeFile(path.join(dir, "AGENTS.md"), AGENT_BRIEF);
-  await writeFile(path.join(dir, "CLAUDE.md"), CLAUDE_MD);
-  await writeFile(
-    path.join(dir, ".gitignore"),
-    `# Generated by Basis on every start\n.basis/\nAGENTS.md\nCLAUDE.md\ntsconfig.json\nnode_modules/\n${REVIEW_FILE}\n`,
-  );
-}
+import { existsSync } from "node:fs";
+import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { REVIEW_FILE } from "../shared/review.ts";
+import { AGENT_BRIEF, CLAUDE_MD } from "./brief.ts";
+import { COMPONENTS_DIR, PATTERNS_DIR, repoRoot, SOURCE_DIRS, VIEWS_DIR } from "./paths.ts";
+import { updateUntouchedStarterFiles } from "./template.ts";
+
+const require = createRequire(import.meta.url);
+
+/*
+ * Getting a workspace ready on every start: starter source for new
+ * workspaces, what Basis added since for older ones, and the files Basis owns.
+ */
+
+/**
+ * Seeds a new workspace from template/, or brings an older one up to date.
+ * Returns a note for the history entry ("Basis added component contracts"),
+ * or "" when nothing an existing workspace would notice was added.
+ */
+export async function seedWorkspace(dir: string): Promise<string> {
+  const components = path.join(dir, COMPONENTS_DIR);
+  const notes: string[] = [];
+  if (!existsSync(components)) await seed(dir, COMPONENTS_DIR);
+  else if (!existsSync(path.join(components, "specimen.ts"))) {
+    await seed(dir, COMPONENTS_DIR, (name) => name.includes("specimen"));
+    notes.push("gallery specimens");
+  }
+  if (!existsSync(path.join(components, "contracts.ts"))) {
+    await seed(dir, COMPONENTS_DIR, (name) => name === "contracts.ts");
+    notes.push("component contracts");
+  }
+  if (!existsSync(path.join(dir, PATTERNS_DIR))) {
+    const fresh = notes.length === 0 && !existsSync(path.join(dir, ".git"));
+    await seed(dir, PATTERNS_DIR);
+    if (!fresh) notes.push("starter patterns");
+  } else {
+    if (!existsSync(path.join(dir, PATTERNS_DIR, "contracts.ts"))) {
+      await seed(dir, PATTERNS_DIR, (name) => name === "contracts.ts");
+      notes.push("pattern contracts");
+    }
+    const added = await addLaterPatterns(dir);
+    if (added.length) notes.push(`the ${added.join(" and ")} pattern${added.length > 1 ? "s" : ""}`);
+  }
+  if (!existsSync(path.join(dir, VIEWS_DIR))) {
+    const fresh = notes.length === 0 && !existsSync(path.join(dir, ".git"));
+    await seed(dir, VIEWS_DIR);
+    if (!fresh) notes.push("a starter view");
+  }
+  // Starter files nobody changed follow the template (see server/template.ts).
+  const updated = await updateUntouchedStarterFiles(dir);
+  const parts = notes.length ? [`added ${notes.join(" and ")}`] : [];
+  if (updated.length) parts.push(`updated ${updated.length === 1 ? updated[0] : `${updated.length} starter files`}`);
+  return parts.length ? `Basis ${parts.join(" and ")}` : "";
+}
+
+/**
+ * Starter patterns added to the baseline after workspaces already had patterns/.
+ * Older workspaces get their files and an export in patterns/index.ts, since the
+ * baseline contract requires them.
+ */
+const LATER_PATTERNS = ["Composer", "Chat"];
+
+async function addLaterPatterns(dir: string): Promise<string[]> {
+  const index = path.join(dir, PATTERNS_DIR, "index.ts");
+  const added: string[] = [];
+  for (const name of LATER_PATTERNS) {
+    if (existsSync(path.join(dir, PATTERNS_DIR, `${name}.tsx`))) continue;
+    await seed(dir, PATTERNS_DIR, (file) => file.startsWith(`${name}.`));
+    const exports = await readFile(index, "utf8").catch(() => "");
+    if (!exports.includes(`"./${name}.tsx"`)) {
+      const separator = exports === "" || exports.endsWith("\n") ? "" : "\n";
+      await writeFile(index, `${exports}${separator}export * from "./${name}.tsx";\n`);
+    }
+    added.push(name);
+  }
+  return added;
+}
+
+/**
+ * Copies starter files from template/<folder> that are missing, normalising
+ * line endings (a Windows checkout of Basis may have CRLF).
+ */
+async function seed(dir: string, folder: string, only: (name: string) => boolean = () => true): Promise<void> {
+  const source = path.join(repoRoot, "template", folder);
+  const destination = path.join(dir, folder);
+  await mkdir(destination, { recursive: true });
+  for (const name of await readdir(source)) {
+    if (!only(name) || existsSync(path.join(destination, name))) continue;
+    const text = await readFile(path.join(source, name), "utf8");
+    await writeFile(path.join(destination, name), text.replaceAll("\r\n", "\n"));
+  }
+}
+
+/**
+ * The workspace format this Basis writes. Raise it when a change means an older Basis would misread or damage a
+ * workspace this one has opened; an older Basis then refuses to open it instead.
+ */
+export const WORKSPACE_FORMAT = 1;
+
+/** Refuses a workspace a newer Basis has opened, and marks it with this Basis' format otherwise. */
+export async function claimWorkspaceFormat(dir: string): Promise<void> {
+  const file = path.join(dir, ".basis", "format.json");
+  const saved = existsSync(file) ? Number(JSON.parse(await readFile(file, "utf8")).format) || 0 : 0;
+  if (saved > WORKSPACE_FORMAT) {
+    throw new Error("a newer version of Basis has opened this project. Update Basis to open it again.");
+  }
+  await mkdir(path.dirname(file), { recursive: true });
+  await writeFile(file, `${JSON.stringify({ format: WORKSPACE_FORMAT })}\n`);
+}
+
+/** Files Basis owns in the workspace, rewritten on every start and kept out of history. */
+export async function writeGeneratedFiles(dir: string): Promise<void> {
+  const basisDir = path.join(dir, ".basis");
+  await mkdir(basisDir, { recursive: true });
+  // Resolved, not joined onto Basis' folder: an npm install may hoist them to a node_modules above it.
+  const types = (pkg: string) =>
+    path
+      .dirname(require.resolve(`${pkg}/package.json`))
+      .split(path.sep)
+      .join("/");
+  const tsconfig = {
+    compilerOptions: {
+      target: "ES2022",
+      lib: ["ES2022", "DOM", "DOM.Iterable"],
+      module: "ESNext",
+      moduleResolution: "bundler",
+      jsx: "react-jsx",
+      strict: true,
+      noEmit: true,
+      skipLibCheck: true,
+      isolatedModules: true,
+      allowImportingTsExtensions: true,
+      types: [],
+      // Resolve React's types from the Basis install, wherever this workspace lives.
+      paths: {
+        react: [`${types("@types/react")}/index.d.ts`],
+        "react/*": [`${types("@types/react")}/*`],
+        "react-dom": [`${types("@types/react-dom")}/index.d.ts`],
+        "react-dom/*": [`${types("@types/react-dom")}/*`],
+      },
+    },
+    include: [...SOURCE_DIRS.map((folder) => `${folder}/**/*`), ".basis/*.ts"],
+  };
+  await writeFile(path.join(dir, "tsconfig.json"), `${JSON.stringify(tsconfig, null, 2)}\n`);
+  await writeFile(
+    path.join(basisDir, "contracts.ts"),
+    await readFile(path.join(repoRoot, "shared", "contracts.ts"), "utf8"),
+  );
+  await writeFile(
+    path.join(basisDir, "pattern-contracts.ts"),
+    await readFile(path.join(repoRoot, "shared", "pattern-contracts.ts"), "utf8"),
+  );
+  await writeFile(
+    path.join(basisDir, "guidelines.md"),
+    await readFile(path.join(repoRoot, "server", "guidelines.md"), "utf8"),
+  );
+  await writeFile(
+    path.join(basisDir, "env.d.ts"),
+    'declare module "*.module.css" {\n  const classes: Record<string, string>;\n  export default classes;\n}\n',
+  );
+  await writeFile(
+    path.join(basisDir, "check.ts"),
+    [
+      "// Fails to type-check when components/ or patterns/ stop satisfying their contracts: the Basis",
+      "// baselines (./contracts.ts, ./pattern-contracts.ts) and the contracts this design system added",
+      "// (components/contracts.ts, patterns/contracts.ts).",
+      'import type { Contracts } from "./contracts.ts";',
+      'import type { AddedContracts } from "../components/contracts.ts";',
+      'import * as components from "../components/index.ts";',
+      'import type { PatternContracts } from "./pattern-contracts.ts";',
+      'import type { AddedPatternContracts } from "../patterns/contracts.ts";',
+      'import type { IconName } from "../patterns/icons.tsx";',
+      'import * as patterns from "../patterns/index.ts";',
+      "",
+      "export const satisfiesContracts: Contracts & AddedContracts = components;",
+      "export const satisfiesPatternContracts: PatternContracts<IconName> & AddedPatternContracts = patterns;",
+      "",
+      "// Every export of components/index.ts needs a contract; add missing ones to components/contracts.ts.",
+      "type Uncovered = Exclude<keyof typeof components, keyof Contracts | keyof AddedContracts>;",
+      "export const everyExportHasAContract: [Uncovered] extends [never] ? true : { missingContractFor: Uncovered } = true;",
+      "",
+      "// Every export of patterns/index.ts needs a contract; add missing ones to patterns/contracts.ts.",
+      "type UncoveredPattern = Exclude<",
+      "  keyof typeof patterns,",
+      "  keyof PatternContracts<IconName> | keyof AddedPatternContracts",
+      ">;",
+      "export const everyPatternHasAContract: [UncoveredPattern] extends [never]",
+      "  ? true",
+      "  : { missingContractFor: UncoveredPattern } = true;",
+      "",
+    ].join("\n"),
+  );
+  await writeFile(path.join(dir, "AGENTS.md"), AGENT_BRIEF);
+  await writeFile(path.join(dir, "CLAUDE.md"), CLAUDE_MD);
+  await writeFile(
+    path.join(dir, ".gitignore"),
+    `# Generated by Basis on every start\n.basis/\nAGENTS.md\nCLAUDE.md\ntsconfig.json\nnode_modules/\n${REVIEW_FILE}\n`,
+  );
+}

package/server/template.ts

@@ -0,0 +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 });
+  }
+}