Keep tokens in sync

import { createHash } from "node:crypto";
import { mkdir, readFile, writeFile } from "node:fs/promises";
import { dirname, join } from "node:path";
import { agent, schedule, step, workflow } from "@foundry.sh/marbles";
import { z } from "zod";

// What the Figma REST API returns, trimmed to the fields this module reads.
// @figma/rest-api-spec has the complete types.
type RGBA = { r: number; g: number; b: number; a: number };
type FileMeta = {
  file: { name: string; version?: string; last_touched_at: string };
};
type FileStyles = {
  meta: { styles: { node_id: string; name: string; style_type: string }[] };
};
type FileNodes = {
  nodes: Record<
    string,
    {
      document: { fills?: { type: string; color?: RGBA; opacity?: number }[] };
    } | null
  >;
};

async function figma<T>(path: string, signal: AbortSignal): Promise<T> {
  const token = process.env.FIGMA_TOKEN;
  if (!token)
    throw new Error("Set FIGMA_TOKEN to a Figma personal access token");
  const response = await fetch(`https://api.figma.com/v1${path}`, {
    headers: { "X-Figma-Token": token },
    signal,
  });
  if (!response.ok)
    throw new Error(`Figma ${path}: ${response.status} ${response.statusText}`);
  return (await response.json()) as T;
}

const channel = (value: number) =>
  Math.round(value * 255)
    .toString(16)
    .padStart(2, "0");
const hex = ({ r, g, b, a }: RGBA, opacity = 1) =>
  `#${channel(r)}${channel(g)}${channel(b)}${a * opacity < 1 ? channel(a * opacity) : ""}`;

// The last palette merged into this repository. Each pull request updates it.
const SNAPSHOT = "design/figma-palette.json";
const snapshotFile = z.object({
  file: z.string(),
  version: z.string(),
  colors: z.array(z.object({ name: z.string(), hex: z.string() })),
});
const checked = z.object({
  file: z.string(),
  version: z.string(),
  changed: z.boolean(),
});
const extracted = snapshotFile.extend({
  changed: z.boolean(),
  digest: z.string(),
});

const readSnapshot = (root: string) =>
  readFile(join(root, SNAPSHOT), "utf8")
    .then((text) => snapshotFile.parse(JSON.parse(text)))
    .catch(() => undefined);

// Has the file been saved since the snapshot? One small request.
const check = step("check")
  .input(z.object({ file: z.string() }))
  .output(checked)
  .do(async ({ input: { file }, workspaces, signal, log }) => {
    const { file: meta } = await figma<FileMeta>(`/files/${file}/meta`, signal);
    const version = meta.version ?? meta.last_touched_at;
    const snapshot = await readSnapshot(workspaces.current.root);
    log(meta.name, "version", version, "snapshot", snapshot?.version ?? "none");
    return { file, version, changed: version !== snapshot?.version };
  });

// Read the published color styles and compare them with the snapshot.
const extract = step("extract")
  .input(z.object({ check: checked }))
  .output(extracted)
  .do(async ({ input: { check }, workspaces, signal, log }) => {
    const { file, version } = check;
    if (!check.changed)
      return { file, version, colors: [], changed: false, digest: "" };

    const { meta } = await figma<FileStyles>(`/files/${file}/styles`, signal);
    const fills = meta.styles.filter((style) => style.style_type === "FILL");
    const ids = encodeURIComponent(
      fills.map((style) => style.node_id).join(",")
    );
    const { nodes } = fills.length
      ? await figma<FileNodes>(`/files/${file}/nodes?ids=${ids}`, signal)
      : { nodes: {} as FileNodes["nodes"] };

    const colors = fills.flatMap((style) => {
      const paint = nodes[style.node_id]?.document.fills?.[0];
      if (paint?.type !== "SOLID" || !paint.color) {
        log.warn(
          "skipping",
          style.name,
          "with a",
          paint?.type ?? "missing",
          "fill"
        );
        return [];
      }
      return [{ name: style.name, hex: hex(paint.color, paint.opacity) }];
    });
    colors.sort((a, b) => a.name.localeCompare(b.name));

    const digest = createHash("sha256")
      .update(JSON.stringify(colors))
      .digest("hex")
      .slice(0, 8);
    const snapshot = await readSnapshot(workspaces.current.root);
    const changed = JSON.stringify(colors) !== JSON.stringify(snapshot?.colors);
    return { file, version, colors, changed, digest };
  });

const designer = agent({
  prompt:
    "You keep this repository's design tokens in step with Figma. Change only color tokens. " +
    "Do not rename tokens the palette does not mention.",
});

// Propose a changed palette as a pull request, once per palette.
const propose = step("propose")
  .input(z.object({ palette: extracted }))
  .output(z.string())
  .do(async ({ input: { palette }, agents, workspaces, report }) => {
    if (!palette.changed) return "unchanged";

    const branch = `design/palette-${palette.digest}`;
    const { git } = workspaces.current;
    if (await git.hasBranch(branch)) return `already proposed on ${branch}`;

    const { file, version, colors } = palette;
    const reply = await git.withWorktree(
      { base: "main", branch },
      async (worktree) => {
        const path = join(worktree.root, SNAPSHOT);
        await mkdir(dirname(path), { recursive: true });
        await writeFile(
          path,
          `${JSON.stringify({ file, version, colors }, null, 2)}\n`
        );

        const session = await agents.session(designer);
        return session.generate(
          `${SNAPSHOT} now holds the color styles published in Figma. ` +
            "Update this repository's color tokens to match, wherever they live. " +
            `Commit everything on ${branch}, push it, and open a pull request with gh ` +
            "that lists the colors added, changed, and removed."
        );
      }
    );

    report.result({ title: `Palette ${palette.digest}`, body: reply.text });
    return branch;
  });

const designSync = workflow("design-sync")
  .input(z.object({ file: z.string() }))
  .do(({ input: { file } }) =>
    propose({ palette: extract({ check: check({}, { file }) }) })
  );

// The key from the library file's URL.
schedule(designSync({}, { file: "your-file-key" })).every("1h");