basis-design 0.0.0-stage → 0.1.0

package/server/reviews.ts

@@ -0,0 +1,156 @@
+import { readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import {
+  parseReviewRequest,
+  REVIEW_FILE,
+  type Alternatives,
+  type ReviewRequest,
+  type ReviewState,
+} from "../shared/review.ts";
+import { git, isCommit, lines } from "./exec.ts";
+import { SOURCE_DIRS } from "./paths.ts";
+
+/** Where an open review keeps its iterations: a ref outside branches, so history (main) never shows them. */
+const REVIEW_REF = "refs/basis/review";
+/** The open review's state, kept in .basis/ so it survives restarts. */
+const STATE_FILE = "review.json";
+
+/**
+ * The open review of a workspace: the request the agent wrote, the commit it
+ * started from and its iterations. The methods run git and expect the caller
+ * to serialise them with its other git work (see Workspace.serial).
+ */
+export class Reviews {
+  /** The open review, or null. */
+  state: ReviewState | null = null;
+  /** Problems with review.json, or null when it is valid or absent. */
+  errors: string[] | null = null;
+  private readonly stateFile: string;
+  /**
+   * What the next iteration builds on when it is not the latest one: the
+   * starting point of a set of alternatives, after the workspace went back to it.
+   */
+  private nextParent: string | undefined;
+
+  constructor(private readonly dir: string) {
+    this.stateFile = path.join(dir, ".basis", STATE_FILE);
+  }
+
+  /** Restores the review that was open when Basis last stopped, if its commits still exist. */
+  async load(): Promise<void> {
+    try {
+      const raw = JSON.parse(await readFile(this.stateFile, "utf8")) as ReviewState;
+      const valid =
+        typeof raw.title === "string" &&
+        Array.isArray(raw.show) &&
+        Array.isArray(raw.steps) &&
+        (await isCommit(this.dir, raw.baseline)) &&
+        (await Promise.all(raw.steps.map((step) => isCommit(this.dir, step.id)))).every(Boolean);
+      this.state = valid ? { ...raw, files: Array.isArray(raw.files) ? raw.files : [] } : null;
+      // Alternatives still being made when Basis stopped are not coming; finished ones still wait for a pick.
+      if (this.state?.alternatives && !this.state.alternatives.done)
+        this.state = { ...this.state, alternatives: undefined };
+    } catch {
+      this.state = null;
+    }
+  }
+
+  /** Reads the agent's review.json; sets `errors` and returns the request when it is valid. */
+  async readRequest(): Promise<ReviewRequest | null> {
+    let text: string;
+    try {
+      text = await readFile(path.join(this.dir, REVIEW_FILE), "utf8");
+    } catch {
+      // No request (or the agent removed it): an open review stays open until approved or discarded.
+      this.errors = null;
+      return null;
+    }
+    const result = parseReviewRequest(text);
+    this.errors = result.ok ? null : result.errors;
+    return result.ok ? result.request : null;
+  }
+
+  /**
+   * Opens a review for the request, or updates what the open one shows.
+   * A new review starts from HEAD: during a turn, the state before the turn.
+   * Returns whether anything changed.
+   */
+  async apply(request: ReviewRequest): Promise<boolean> {
+    const current = this.state;
+    if (current && current.title === request.title && JSON.stringify(current.show) === JSON.stringify(request.show))
+      return false;
+    const baseline = current?.baseline ?? (await git(this.dir, ["rev-parse", "HEAD"])).trim();
+    this.state = current
+      ? { ...current, title: request.title, show: request.show }
+      : { ...request, baseline, startedAt: Date.now(), steps: [], files: [] };
+    await this.save();
+    return true;
+  }
+
+  /** The commit the working tree is recorded against: the latest iteration, or what the workspace went back to. */
+  get tip(): string | undefined {
+    const review = this.state;
+    return review ? (this.nextParent ?? review.steps.at(-1)?.id ?? review.baseline) : undefined;
+  }
+
+  /**
+   * Records the working tree as the next iteration, if it changed. Returns
+   * whether it did. A new iteration after a finished set of alternatives means
+   * the user moved on, so the set is put away (its iterations stay).
+   */
+  async recordStep(label: string): Promise<boolean> {
+    const review = this.state;
+    const parent = this.tip;
+    if (!review || !parent) return false;
+    await git(this.dir, ["add", "-A"]);
+    const tree = (await git(this.dir, ["write-tree"])).trim();
+    if (tree === (await git(this.dir, ["rev-parse", `${parent}^{tree}`])).trim()) return false;
+    const id = (await git(this.dir, ["commit-tree", tree, "-p", parent, "-m", `review: ${label.slice(0, 72)}`])).trim();
+    this.nextParent = undefined;
+    await git(this.dir, ["update-ref", REVIEW_REF, id]);
+    const files = lines(await git(this.dir, ["diff", "--name-only", review.baseline, id, "--", ...SOURCE_DIRS]));
+    const alternatives = review.alternatives?.done ? undefined : review.alternatives;
+    this.state = { ...review, steps: [...review.steps, { id, at: Date.now(), label }], files, alternatives };
+    await this.save();
+    return true;
+  }
+
+  /** Sets or clears the review's alternatives. */
+  async setAlternatives(alternatives: Alternatives | undefined): Promise<void> {
+    if (!this.state) return;
+    this.state = { ...this.state, alternatives };
+    await this.save();
+  }
+
+  /** Records which specimens the review's changes can reach (null: all of them). */
+  async setReach(reach: string[] | null): Promise<void> {
+    if (!this.state) return;
+    this.state = { ...this.state, reach };
+    await this.save();
+  }
+
+  /**
+   * Puts the working tree back to a commit: the starting point, or one of the
+   * iterations. With `asBase`, the next iteration builds on that commit rather
+   * than on the latest one, and going back is not an iteration of its own.
+   */
+  async restore(commit: string, asBase = false): Promise<void> {
+    await git(this.dir, ["add", "-A"]);
+    await git(this.dir, ["restore", `--source=${commit}`, "--staged", "--worktree", "--", "."]);
+    if (asBase) this.nextParent = commit;
+  }
+
+  /** Forgets the open review: its iterations ref, its saved state and the agent's request. */
+  async end(): Promise<void> {
+    this.state = null;
+    this.nextParent = undefined;
+    this.errors = null;
+    await git(this.dir, ["update-ref", "-d", REVIEW_REF]).catch(() => undefined);
+    await rm(this.stateFile, { force: true });
+    await rm(path.join(this.dir, REVIEW_FILE), { force: true });
+  }
+
+  private async save(): Promise<void> {
+    await writeFile(this.stateFile, `${JSON.stringify(this.state, null, 2)}\n`);
+  }
+}

package/server/setup.ts

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

package/server/snapshots.ts

@@ -0,0 +1,67 @@
+import { existsSync } from "node:fs";
+import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { parseDesignText, type Design } from "../shared/design.ts";
+import { git, isCommit } from "./exec.ts";
+import { DESIGN_FILE, SOURCE_DIRS } from "./paths.ts";
+
+/**
+ * Read-only copies of past versions under .basis/snapshots/<commit>/, which
+ * the preview imports so a review's "before" side runs that version's own
+ * component code next to today's.
+ */
+export class Snapshots {
+  private readonly root: string;
+  /** Copies being written, so concurrent requests for one version share the work. */
+  private pending = new Map<string, Promise<string>>();
+
+  constructor(private readonly dir: string) {
+    this.root = path.join(dir, ".basis", "snapshots");
+  }
+
+  /** A past version: its tokens, and the folder holding a copy of its source. */
+  async get(id: string): Promise<{ id: string; design: Design; dir: string } | null> {
+    if (!(await isCommit(this.dir, id))) return null;
+    try {
+      const result = parseDesignText(await git(this.dir, ["show", `${id}:${DESIGN_FILE}`]));
+      if (!result.ok) return null;
+      return { id, design: result.design, dir: await this.materialise(id) };
+    } catch {
+      return null;
+    }
+  }
+
+  /** Removes every copy except `keep`'s. */
+  async prune(keep: string | undefined): Promise<void> {
+    if (!existsSync(this.root)) return;
+    for (const name of await readdir(this.root)) {
+      if (name !== keep) await rm(path.join(this.root, name), { recursive: true, force: true });
+    }
+  }
+
+  /** Writes the source folders of a commit once; later calls reuse the copy. */
+  private materialise(id: string): Promise<string> {
+    const running = this.pending.get(id);
+    if (running) return running;
+    const target = path.join(this.root, id);
+    const done = path.join(target, ".complete");
+    const work = (async () => {
+      if (existsSync(done)) return target;
+      await rm(target, { recursive: true, force: true });
+      const names = (await git(this.dir, ["ls-tree", "-r", "-z", "--name-only", id, "--", ...SOURCE_DIRS]))
+        .split("\0")
+        .filter(Boolean);
+      await Promise.all(
+        names.map(async (name) => {
+          const file = path.join(target, ...name.split("/"));
+          await mkdir(path.dirname(file), { recursive: true });
+          await writeFile(file, await git(this.dir, ["show", `${id}:${name}`]));
+        }),
+      );
+      await writeFile(done, "");
+      return target;
+    })().finally(() => this.pending.delete(id));
+    this.pending.set(id, work);
+    return work;
+  }
+}