Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

20.7 KB
Raw Blame
/**
 * Imported themes over HTTP: the appearance page's list (`GET /api/themes`), the stylesheet the
 * app links from `<head>` (`GET /api/themes.css`), and the two imports — a picked file
 * (`POST /api/themes/upload`) and an address (`POST /api/themes/download`).
 *
 * - The directory is a data root's `themes/`: a file dropped in it needs no restart, because every
 *   request reads the directory — an installation with no such directory answers with an empty list
 *   and a sheet that is one comment, not a failed request.
 * - A file that does not read costs nobody else: it is named with its reason in the list and left
 *   out of the sheet, and the good themes beside it are still served. Two files claiming one id
 *   reject the later one, so which file paints is not decided by the filesystem's mood.
 * - The list is the app's data and stays behind the login; the sheet is the app's paint and is read
 *   before anyone signs in (the sign-in page renders under the theme too), so it is public.
 * - What the sheet says is the theme's own values, scoped to its own `data-theme` and its layers —
 *   the shape core's external-theme.test.ts pins; here it is the HTTP answer that is under test.
 * - An import writes the file the directory would have held anyway, under the theme's own id, and
 *   it is judged by the reader that would have read it there (core's readExternalTheme): these
 *   tests are mostly about that equivalence — a bad file is refused with its reasons and nothing is
 *   written, an id another file claims is a 409 rather than a second claimant, and `overwrite`
 *   replaces THAT file. Both routes are the admin's; the list stays every user's.
 */
import fs from "node:fs/promises";
import path from "node:path";
import { afterEach, describe, expect, it, vi } from "vitest";
import { MAX_THEME_FILE_BYTES } from "@adelie/core";
import type { ImportedThemesResponse, ThemeImportResponse } from "../src/api/types.js";
import { apiClient, createTestApp, loginAdmin, provisionUser } from "./helpers.js";
import type { TestApp } from "./helpers.js";

/** A theme file that reads: everything the format allows. */
const WARM_PAPER = {
  schemaVersion: 1,
  id: "warm-paper",
  name: "Warm Paper",
  nameZh: "暖纸",
  light: { "--ui-canvas": "#f7f3ec", "--ui-surface": "#fffdf8" },
  dark: { "--ui-canvas": "#16130f" },
  accents: [{ id: "terracotta", light: { "--ui-accent": "#b4552d" } }],
};

let live: TestApp[] = [];

/** An app whose data root already holds these files in `themes/` — an installation's own state. */
async function appWithThemes(files: Record<string, string | object> = {}): Promise<TestApp> {
  const t = await createTestApp({
    beforeSeed: async (root) => {
      const names = Object.keys(files);
      if (names.length === 0) return;
      const dir = path.join(root, "themes");
      await fs.mkdir(dir, { recursive: true });
      for (const name of names) {
        const body = files[name]!;
        await fs.writeFile(
          path.join(dir, name),
          typeof body === "string" ? body : JSON.stringify(body),
          "utf8",
        );
      }
    },
  });
  live.push(t);
  return t;
}

afterEach(async () => {
  vi.unstubAllGlobals();
  const open = live;
  live = [];
  await Promise.all(open.map((t) => t.cleanup()));
});

async function listThemes(t: TestApp, cookie?: string): Promise<Response> {
  return t.app.request("/api/themes", cookie ? { headers: { cookie } } : {});
}

/** A refused request's error body, read once: the code is the contract, the message is the reason. */
async function readError(res: Response): Promise<{ code: string; message: string }> {
  const body = (await res.json()) as { error: { code: string; message: string } };
  return body.error;
}

/** Who may import and who may not: the admin, a member, and the admin's cookie for the raw list reads. */
async function importers(t: TestApp) {
  const admin = await loginAdmin(t.app);
  return {
    cookie: admin.cookie,
    admin: apiClient(t.app, admin.cookie),
    member: apiClient(t.app, (await provisionUser(t.app, "theme_member")).cookie),
  };
}

/** The upload body for one theme file, as the picked-file flow sends it. */
function uploadBody(theme: object, extra: Record<string, unknown> = {}): Record<string, unknown> {
  return { dataBase64: Buffer.from(JSON.stringify(theme), "utf8").toString("base64"), ...extra };
}

/** A response body that never declares its length, so the reader's own cap is what stops it. */
function streamed(bytes: Buffer): Response {
  return new Response(
    new ReadableStream({
      start(controller) {
        controller.enqueue(bytes);
        controller.close();
      },
    }),
    { status: 200 },
  );
}

describe("imported themes", () => {
  it("没有 themes 目录时:列表是空的,样式表只有一句注释", async () => {
    const t = await appWithThemes();
    const { cookie } = await provisionUser(t.app, "theme_reader");

    const list = await listThemes(t, cookie);
    expect(list.status).toBe(200);
    const body = (await list.json()) as ImportedThemesResponse;
    expect(body.dir).toBe(path.join(t.root, "themes"));
    expect(body.themes).toEqual([]);
    expect(body.rejected).toEqual([]);

    const sheet = await t.app.request("/api/themes.css");
    expect(sheet.status).toBe(200);
    expect(sheet.headers.get("content-type")).toBe("text/css; charset=utf-8");
    expect(await sheet.text()).toBe("/* no imported themes */\n");
  });

  it("列表要登录,样式表不用——首屏在登录之前就要上色", async () => {
    const t = await appWithThemes({ "warm-paper.json": WARM_PAPER });

    const anonymous = await listThemes(t);
    expect(anonymous.status).toBe(401);

    const sheet = await t.app.request("/api/themes.css");
    expect(sheet.status).toBe(200);
    expect(sheet.headers.get("cache-control")).toBe("no-cache");
    expect(await sheet.text()).toContain(':root[data-theme="warm-paper"]');
  });

  it("放进去一份好主题:列表里认得出它,样式表里就是它自己的值", async () => {
    const t = await appWithThemes({ "warm-paper.json": WARM_PAPER });
    const { cookie } = await provisionUser(t.app, "theme_reader");

    const body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.rejected).toEqual([]);
    expect(body.themes.map((entry) => entry.file)).toEqual(["warm-paper.json"]);
    const theme = body.themes[0]!.theme;
    expect(theme.id).toBe("warm-paper");
    expect(theme.nameZh).toBe("暖纸");
    expect(theme.light["--ui-canvas"]).toBe("#f7f3ec");

    const css = await (await t.app.request("/api/themes.css")).text();
    // Light first and both modes in one base rule, dark only what it changes — so the sheet needs
    // no promise about which stylesheet the browser read first. The bridge rule after the dark one
    // re-points Tailwind's gray rungs onto the theme's own tokens, which is how a theme makes the
    // app's `bg-white` / `text-gray-500` follow it; this theme declares a canvas and a surface and
    // no ink, so exactly those two rungs are bridged and only under `.dark` — the one mode it
    // changes. (core's external-theme.test.ts pins the mapping in full.)
    expect(css).toContain(
      '@layer ui-theme{\n:root[data-theme="warm-paper"],:root[data-theme="warm-paper"].dark{--ui-canvas:#f7f3ec;--ui-surface:#fffdf8}\n:root[data-theme="warm-paper"].dark{--ui-canvas:#16130f}\n:root[data-theme="warm-paper"].dark{--color-gray-900:var(--ui-surface);--color-gray-950:var(--ui-canvas)}\n}',
    );
    // A preset is scoped to its own theme as well: it paints only under the theme that lists it.
    expect(css).toContain(
      '@layer ui-accent{\n:root[data-theme="warm-paper"][data-accent="terracotta"],:root[data-theme="warm-paper"][data-accent="terracotta"].dark{--ui-accent:#b4552d}\n}',
    );
  });

  it("读不了的文件只坑自己:好主题照旧上色,坏文件连原因一起报出来", async () => {
    const t = await appWithThemes({
      "warm-paper.json": WARM_PAPER,
      "broken.json": "{ this is not json",
      "risky.json": {
        schemaVersion: 1,
        id: "risky",
        name: "Risky",
        light: { "--ui-canvas": "red;background:url(http://example.test/x.png)" },
      },
      "notes.txt": "not a theme, not even read",
    });
    const { cookie } = await provisionUser(t.app, "theme_reader");

    const body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.theme.id)).toEqual(["warm-paper"]);
    // Only the `.json` names are read at all, and each refusal carries the reason.
    expect(body.rejected.map((entry) => entry.file).sort()).toEqual(["broken.json", "risky.json"]);
    expect(body.rejected.find((entry) => entry.file === "broken.json")!.errors[0]).toContain(
      "不是合法的 JSON",
    );
    expect(body.rejected.find((entry) => entry.file === "risky.json")!.errors.join(" ")).toContain(
      "--ui-canvas",
    );

    const css = await (await t.app.request("/api/themes.css")).text();
    expect(css).toContain(':root[data-theme="warm-paper"]');
    // Nothing of the refused file reaches the sheet: not its name, not the value it tried.
    expect(css).not.toContain("risky");
    expect(css).not.toContain("example.test");
  });

  it("两个文件抢同一个主题名:后面那个被拒,先来的照常上色", async () => {
    const t = await appWithThemes({
      "a-good.json": WARM_PAPER,
      "b-clash.json": { ...WARM_PAPER, name: "Warm Paper Again" },
    });
    const { cookie } = await provisionUser(t.app, "theme_reader");

    const body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.file)).toEqual(["a-good.json"]);
    expect(body.rejected).toHaveLength(1);
    expect(body.rejected[0]!.file).toBe("b-clash.json");
    expect(body.rejected[0]!.errors.join(" ")).toContain("warm-paper");
  });

  it("文件是现读的:加进去、改掉、删掉都在下一次请求里生效", async () => {
    const t = await appWithThemes();
    const { cookie } = await provisionUser(t.app, "theme_reader");
    const file = path.join(t.root, "themes", "warm-paper.json");

    await fs.mkdir(path.dirname(file), { recursive: true });
    await fs.writeFile(file, JSON.stringify(WARM_PAPER), "utf8");
    let body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.theme.id)).toEqual(["warm-paper"]);

    await fs.writeFile(file, JSON.stringify({ ...WARM_PAPER, nameZh: "暖纸二" }), "utf8");
    body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes[0]!.theme.nameZh).toBe("暖纸二");

    await fs.rm(file);
    body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes).toEqual([]);
  });
});

describe("导入主题", () => {
  it("上传一份文件:按主题自己的名字落盘,列表和样式表立刻就有它", async () => {
    const t = await appWithThemes();
    const { cookie, admin } = await importers(t);

    const res = await admin.post("/api/themes/upload", uploadBody(WARM_PAPER));
    expect(res.status).toBe(201);
    const imported = (await res.json()) as ThemeImportResponse;
    expect(imported.file).toBe("warm-paper.json");
    expect(imported.theme.nameZh).toBe("暖纸");
    // The file lands exactly as it arrived — the operator's own file, not a re-serialized copy of
    // it — so what the directory holds is what they picked.
    expect(await fs.readFile(path.join(t.root, "themes", "warm-paper.json"), "utf8")).toBe(
      JSON.stringify(WARM_PAPER),
    );

    // The two reads the page does see it without a restart, which is the whole point of writing
    // into the directory the server re-reads per request.
    const body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.file)).toEqual(["warm-paper.json"]);
    expect(await (await t.app.request("/api/themes.css")).text()).toContain(
      ':root[data-theme="warm-paper"]',
    );
  });

  it("同一个主题名再导一次:先 409 问一句,覆盖之后只有一份文件", async () => {
    const t = await appWithThemes();
    const { cookie, admin } = await importers(t);
    await admin.post("/api/themes/upload", uploadBody(WARM_PAPER));

    const updated = { ...WARM_PAPER, nameZh: "暖纸二" };
    const again = await admin.post("/api/themes/upload", uploadBody(updated));
    expect(again.status).toBe(409);
    expect((await readError(again)).code).toBe("theme_exists");
    // Without the confirmation nothing was touched: the theme still reads as it did.
    let body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes[0]!.theme.nameZh).toBe("暖纸");

    const over = await admin.post("/api/themes/upload", uploadBody(updated, { overwrite: true }));
    expect(over.status).toBe(201);
    body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.file)).toEqual(["warm-paper.json"]);
    expect(body.themes[0]!.theme.nameZh).toBe("暖纸二");
    expect(body.rejected).toEqual([]);
    expect(await fs.readdir(path.join(t.root, "themes"))).toEqual(["warm-paper.json"]);
  });

  it("别的文件占了同一个主题名:覆盖时替换的是那个文件,不再多写一份", async () => {
    const t = await appWithThemes({ "b-claims-warm-paper.json": WARM_PAPER });
    const { cookie, admin } = await importers(t);

    const other = { ...WARM_PAPER, name: "Other" };
    expect((await admin.post("/api/themes/upload", uploadBody(other))).status).toBe(409);

    const ok = await admin.post("/api/themes/upload", uploadBody(other, { overwrite: true }));
    expect(ok.status).toBe(201);
    // One file, and it is the new one: writing `<id>.json` BESIDE the claimant would have left two
    // files claiming one id, of which the reader serves the earlier — a successful import that
    // paints the old theme.
    const body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.file)).toEqual(["warm-paper.json"]);
    expect(body.themes[0]!.theme.name).toBe("Other");
    expect(body.rejected).toEqual([]);
    expect(await fs.readdir(path.join(t.root, "themes"))).toEqual(["warm-paper.json"]);
  });

  it("读不出来的文件:连原因一起拒掉,一个字节都不落盘", async () => {
    const t = await appWithThemes();
    const { admin } = await importers(t);

    const notJson = await admin.post("/api/themes/upload", {
      dataBase64: Buffer.from("{ nope", "utf8").toString("base64"),
    });
    expect(notJson.status).toBe(400);
    const notJsonError = await readError(notJson);
    expect(notJsonError.code).toBe("theme_invalid");
    expect(notJsonError.message).toContain("不是合法的 JSON");

    // The reader's own reasons, all of them, rather than a generic refusal: the author of the file
    // is who has to fix it.
    const wrongShape = await admin.post("/api/themes/upload", {
      dataBase64: Buffer.from(
        JSON.stringify({ id: "Warm Paper", name: "x", light: {} }),
        "utf8",
      ).toString("base64"),
    });
    expect(wrongShape.status).toBe(400);
    const message = (await readError(wrongShape)).message;
    expect(message).toContain("id");
    expect(message).toContain("light");

    // Not one byte: the directory was never even created.
    await expect(fs.readdir(path.join(t.root, "themes"))).rejects.toThrow();
  });

  it("超过格式上限:413,而且按解码后的字节算", async () => {
    const t = await appWithThemes();
    const { admin } = await importers(t);
    const res = await admin.post("/api/themes/upload", {
      dataBase64: Buffer.alloc(MAX_THEME_FILE_BYTES + 1, 0x20).toString("base64"),
    });
    expect(res.status).toBe(413);
    expect((await readError(res)).code).toBe("theme_too_large");
  });

  it("两个导入只有管理员能做,读列表照旧谁都可以", async () => {
    const t = await appWithThemes();
    const { admin, member } = await importers(t);
    const fetchSpy = vi.fn();
    vi.stubGlobal("fetch", fetchSpy);

    expect((await member.post("/api/themes/upload", uploadBody(WARM_PAPER))).status).toBe(403);
    const refused = await member.post("/api/themes/upload", uploadBody(WARM_PAPER));
    expect((await readError(refused)).code).toBe("admin_required");
    const memberDownload = await member.post("/api/themes/download", {
      url: "https://themes.example.test/warm.json",
    });
    expect(memberDownload.status).toBe(403);
    // Refused before anything left the machine.
    expect(fetchSpy).not.toHaveBeenCalled();

    // The list is every user's screen, and the admin's own import still works.
    expect((await member.get("/api/themes")).status).toBe(200);
    expect((await admin.get("/api/themes")).status).toBe(200);
  });

  it("从地址导入:服务端取回来,落成和上传完全相同的一份", async () => {
    const t = await appWithThemes();
    const { cookie, admin } = await importers(t);
    const calls: string[] = [];
    vi.stubGlobal("fetch", async (input: Parameters<typeof fetch>[0]) => {
      calls.push(String(input));
      return new Response(JSON.stringify(WARM_PAPER), {
        status: 200,
        headers: { "content-type": "application/json" },
      });
    });

    const res = await admin.post("/api/themes/download", {
      url: "https://themes.example.test/themes/warm.json",
    });
    expect(res.status).toBe(201);
    expect(calls).toEqual(["https://themes.example.test/themes/warm.json"]);
    // The file name comes from the theme, not from the URL's last segment: an address and a picked
    // file install the same thing.
    expect(((await res.json()) as ThemeImportResponse).file).toBe("warm-paper.json");
    const body = (await (await listThemes(t, cookie)).json()) as ImportedThemesResponse;
    expect(body.themes.map((entry) => entry.theme.id)).toEqual(["warm-paper"]);
  });

  it("从地址取回来的不是主题:按同一个读法给出原因", async () => {
    const t = await appWithThemes();
    const { admin } = await importers(t);

    vi.stubGlobal("fetch", async () => new Response("<html>nope</html>", { status: 200 }));
    const html = await admin.post("/api/themes/download", {
      url: "https://themes.example.test/x.json",
    });
    expect(html.status).toBe(400);
    expect((await readError(html)).code).toBe("theme_invalid");

    vi.stubGlobal("fetch", async () => new Response("gone", { status: 404 }));
    const missing = await admin.post("/api/themes/download", {
      url: "https://themes.example.test/x.json",
    });
    expect(missing.status).toBe(400);
    expect((await readError(missing)).code).toBe("download_failed");

    vi.stubGlobal("fetch", async () => {
      throw new Error("getaddrinfo ENOTFOUND");
    });
    const unreachable = await admin.post("/api/themes/download", {
      url: "https://themes.example.test/x.json",
    });
    expect(unreachable.status).toBe(400);
    expect((await readError(unreachable)).code).toBe("download_failed");

    const notAUrl = await admin.post("/api/themes/download", { url: "file:///etc/passwd" });
    expect(notAUrl.status).toBe(400);
    expect((await readError(notAUrl)).code).toBe("unsupported_url");
  });

  it("地址是内网、或者回来的东西太大:都不落盘", async () => {
    const t = await appWithThemes();
    const { admin } = await importers(t);

    const fetchSpy = vi.fn();
    vi.stubGlobal("fetch", fetchSpy);
    const blocked = await admin.post("/api/themes/download", {
      url: "http://127.0.0.1:7364/api/themes",
    });
    expect(blocked.status).toBe(400);
    expect((await readError(blocked)).code).toBe("blocked_url");
    expect(fetchSpy).not.toHaveBeenCalled();

    // A declared length past the cap: refused before reading the body.
    vi.stubGlobal(
      "fetch",
      async () =>
        new Response("x", {
          status: 200,
          headers: { "content-length": String(MAX_THEME_FILE_BYTES * 4) },
        }),
    );
    const declared = await admin.post("/api/themes/download", {
      url: "https://themes.example.test/big.json",
    });
    expect(declared.status).toBe(413);
    expect((await readError(declared)).code).toBe("theme_too_large");

    // A length that is not declared at all (a chunked body): the cap has to hold while streaming,
    // because a `content-length` is only a claim.
    vi.stubGlobal("fetch", async () => streamed(Buffer.alloc(MAX_THEME_FILE_BYTES * 2, 0x20)));
    const streamedTooBig = await admin.post("/api/themes/download", {
      url: "https://themes.example.test/big.json",
    });
    expect(streamedTooBig.status).toBe(413);
    expect((await readError(streamedTooBig)).code).toBe("theme_too_large");

    await expect(fs.readdir(path.join(t.root, "themes"))).rejects.toThrow();
  });
});