Skip to content

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

10.3 KB
Raw Blame
/**
 * A theme REGISTRY: the index a shared theme repository publishes, so an installation can browse
 * what exists instead of being handed a URL.
 *
 * The directory an installation keeps (`<data root>/themes/`) is still the whole install — a
 * registry changes only where the FILE comes from: an index names the themes, each entry points at
 * one file in the same repository, and the install path (fetch, read, write `<id>.json`) is the one
 * the download import already used. So the index is a catalogue, never a second format: the theme
 * file it points at is read by `readExternalTheme`, with the same caps and the same refusal list.
 *
 * WHY THE INDEX IS CHECKED HERE AND NOT BY EACH CLIENT. Two readers exist — the server that fetches
 * it and the page that draws the cards — and a catalogue half-understood by one of them is a theme
 * that appears and then fails to import. It lives in core for the same reason the theme format
 * does: both ends already depend on core, and neither may depend on the other.
 *
 * WHAT A FILE PATH MAY BE. Repository-relative and plain: the registry is one host serving its own
 * files, so `file` is joined onto the registry's base address and nothing else. An entry that asks
 * for an absolute URL, a scheme, or a `..` hop is refused here, not at fetch time — the point of an
 * index is that one host answers for all of it, and an index that can send a reader anywhere is an
 * open redirect with extra steps.
 */

/** The index shape this module reads. A later shape bumps it rather than half-reading an old one. */
export const THEME_REGISTRY_SCHEMA_VERSION = 1;

/** How big a registry index may be — a list of names, not a payload. */
export const MAX_REGISTRY_FILE_BYTES = 128 * 1024;

/** The most themes one index may offer. */
const MAX_REGISTRY_THEMES = 200;

/** Display copy is copy: bounded, not patterned. */
const NAME = /^[\s\S]{1,60}$/;
const AUTHOR = /^[\s\S]{1,60}$/;
const DESCRIPTION = /^[\s\S]{1,280}$/;
const VERSION = /^[0-9A-Za-z.+-]{1,32}$/;

/**
 * A repository-relative path: segments of plain characters, never `.`/`..`, never an absolute URL
 * and never a backslash (which Windows would read as a separator while this module would not).
 */
const FILE_PATH = /^(?!\/)(?!.*(?:^|\/)\.\.(?:\/|$))[A-Za-z0-9][A-Za-z0-9._\-/]*$/;

/** The four colours a card paints, and the only swatch names this format knows. */
export const SWATCH_NAMES = ["--ui-canvas", "--ui-surface", "--ui-fg", "--ui-accent"] as const;

/** A token value's safety is the theme format's rule, reused rather than restated. */
const SAFE_VALUE = /^[^;{}<>\\@\n\r]{1,120}$/;
const FETCHES = /url\s*\(|image-set\s*\(|expression\s*\(/i;

export interface RegistrySwatch {
  /** The four colours above, as the theme paints them in this mode. */
  readonly light?: Readonly<Record<string, string>>;
  readonly dark?: Readonly<Record<string, string>>;
}

/** One theme the registry offers. */
export interface RegistryThemeEntry {
  readonly id: string;
  readonly name: string;
  readonly nameZh?: string;
  readonly author: string;
  readonly description?: string;
  readonly descriptionZh?: string;
  /** Repository-relative path of the theme file. */
  readonly file: string;
  /** The theme file's own version, for cards that show one. */
  readonly version?: string;
  readonly swatch?: RegistrySwatch;
}

export interface ThemeRegistry {
  readonly schemaVersion: number;
  /** The registry's own name, shown above its list. */
  readonly name?: string;
  readonly updatedAt?: string;
  readonly themes: readonly RegistryThemeEntry[];
}

export type ThemeRegistryRead =
  | { readonly ok: true; readonly registry: ThemeRegistry }
  | { readonly ok: false; readonly errors: readonly string[] };

function isPlainObject(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

/**
 * The four-name swatch: undefined when the entry carries none, null when it carries one this
 * format does not understand. A swatch that fails fails its whole entry rather than being
 * half-drawn — a card's colours are the only reason the index carries them.
 */
function readSwatch(
  value: unknown,
  where: string,
  errors: string[],
): RegistrySwatch | null | undefined {
  if (value === undefined) return undefined;
  if (!isPlainObject(value)) {
    errors.push(`${where}: 要是一个对象(light / dark)`);
    return null;
  }
  const out: { light?: Record<string, string>; dark?: Record<string, string> } = {};
  for (const mode of ["light", "dark"] as const) {
    const tokens = value[mode];
    if (tokens === undefined) continue;
    if (!isPlainObject(tokens)) {
      errors.push(`${where}.${mode}: 要是一个对象`);
      return null;
    }
    const colours: Record<string, string> = {};
    for (const [name, raw] of Object.entries(tokens)) {
      if (!(SWATCH_NAMES as readonly string[]).includes(name)) {
        errors.push(
          `${where}.${mode}: 「${name}」不是色板里的名字(只能是 ${SWATCH_NAMES.join(" / ")})`,
        );
        return null;
      }
      if (typeof raw !== "string" || !SAFE_VALUE.test(raw) || FETCHES.test(raw)) {
        errors.push(`${where}.${mode}: 「${name}」的值不能用`);
        return null;
      }
      colours[name] = raw;
    }
    if (Object.keys(colours).length > 0) out[mode] = colours;
  }
  return Object.keys(out).length === 0 ? undefined : out;
}

/** One entry, or the reasons it is not one. */
function readEntry(
  entry: unknown,
  where: string,
  seen: Set<string>,
): { ok: true; entry: RegistryThemeEntry } | { ok: false; errors: string[] } {
  const errors: string[] = [];
  if (!isPlainObject(entry)) return { ok: false, errors: [`${where}: 要是一个对象`] };
  const id = entry.id;
  if (typeof id !== "string" || !/^[a-z][a-z0-9-]{0,31}$/.test(id))
    return { ok: false, errors: [`${where}.id: 「${String(id)}」不是合法的主题名`] };
  if (seen.has(id)) return { ok: false, errors: [`${where}.id: 「${id}」出现了两次`] };
  const name = entry.name;
  if (typeof name !== "string" || !NAME.test(name))
    return { ok: false, errors: [`${where}.name: 要有 1–60 个字的显示名`] };
  const author = entry.author;
  if (typeof author !== "string" || !AUTHOR.test(author))
    return { ok: false, errors: [`${where}.author: 要有 1–60 个字的作者名`] };
  const file = entry.file;
  if (typeof file !== "string" || !FILE_PATH.test(file))
    return { ok: false, errors: [`${where}.file: 「${String(file)}」不是仓库内的相对路径`] };
  const nameZh = entry.nameZh;
  if (nameZh !== undefined && (typeof nameZh !== "string" || !NAME.test(nameZh)))
    return { ok: false, errors: [`${where}.nameZh: 要有 1–60 个字(不写就用 name)`] };
  const description = entry.description;
  if (
    description !== undefined &&
    (typeof description !== "string" || !DESCRIPTION.test(description))
  )
    return { ok: false, errors: [`${where}.description: 要有 1–280 个字`] };
  const descriptionZh = entry.descriptionZh;
  if (
    descriptionZh !== undefined &&
    (typeof descriptionZh !== "string" || !DESCRIPTION.test(descriptionZh))
  )
    return { ok: false, errors: [`${where}.descriptionZh: 要有 1–280 个字`] };
  const version = entry.version;
  if (version !== undefined && (typeof version !== "string" || !VERSION.test(version)))
    return { ok: false, errors: [`${where}.version: 「${String(version)}」不像一个版本号`] };
  const swatch = readSwatch(entry.swatch, `${where}.swatch`, errors);
  if (swatch === null || errors.length > 0) return { ok: false, errors };
  seen.add(id);
  return {
    ok: true,
    entry: {
      id,
      name,
      ...(nameZh === undefined ? {} : { nameZh }),
      author,
      ...(description === undefined ? {} : { description }),
      ...(descriptionZh === undefined ? {} : { descriptionZh }),
      file,
      ...(version === undefined ? {} : { version }),
      ...(swatch === undefined ? {} : { swatch }),
    },
  };
}

/**
 * Reads one index. Errors are collected rather than thrown on the first one: a registry author
 * gets the whole list, and an entry that fails is dropped — one broken line must not hide the rest
 * of the catalogue.
 */
export function readThemeRegistry(value: unknown): ThemeRegistryRead {
  if (!isPlainObject(value)) return { ok: false, errors: ["顶层必须是一个对象"] };
  const errors: string[] = [];
  const schema = value.schemaVersion;
  if (schema !== undefined && schema !== THEME_REGISTRY_SCHEMA_VERSION) {
    errors.push(
      `schemaVersion: ${String(schema)} 不是本版本认识的 ${THEME_REGISTRY_SCHEMA_VERSION}`,
    );
  }
  const raw = value.themes;
  if (!Array.isArray(raw)) return { ok: false, errors: [...errors, "themes: 要是一个数组"] };
  if (raw.length > MAX_REGISTRY_THEMES) {
    errors.push(`themes: ${raw.length} 条,超过上限 ${MAX_REGISTRY_THEMES}`);
  }
  const themes: RegistryThemeEntry[] = [];
  const seen = new Set<string>();
  for (const [index, entry] of raw.slice(0, MAX_REGISTRY_THEMES).entries()) {
    const read = readEntry(entry, `themes[${index}]`, seen);
    if (!read.ok) {
      errors.push(...read.errors);
      continue;
    }
    themes.push(read.entry);
  }
  const registry: ThemeRegistry = {
    schemaVersion: THEME_REGISTRY_SCHEMA_VERSION,
    ...(typeof value.name === "string" && NAME.test(value.name) ? { name: value.name } : {}),
    ...(typeof value.updatedAt === "string" && VERSION.test(value.updatedAt)
      ? { updatedAt: value.updatedAt }
      : {}),
    themes,
  };
  if (themes.length === 0 && errors.length === 0) errors.push("themes: 一条都没有");
  // All or nothing: a catalogue that silently lacks the entry its author just added reads as a
  // registry problem that nobody can locate. The whole list of reasons is the useful answer.
  return errors.length > 0 ? { ok: false, errors } : { ok: true, registry };
}

/**
 * One entry's address: the registry's base, its trailing slash normalised, plus the entry's own
 * relative path. Null when the base is not http(s) or the path is not one this format accepts —
 * the same rule as the reader's, so nothing that passed the index can fail here.
 */
export function resolveRegistryFile(base: string, file: string): string | null {
  if (!/^https?:\/\//i.test(base)) return null;
  if (!FILE_PATH.test(file)) return null;
  return `${base.replace(/\/+$/, "")}/${file}`;
}