Skip to content

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

37.5 KB
Raw Blame
/**
 * Plugin configuration: the settings a module DECLARES and the values an admin gives them on
 * the Settings dialog's Plugins page, stored server-wide and read back by the declaring module
 * itself through the `PluginConfig` mechanism (a module `requires` it from `PluginConfigModule`).
 *
 * A declaration is a contribution to `PluginConfigProvider.groups`: pure manifest data, so a
 * plugin's lands in its generated `ifaces.json` beside every other contribution, and the page
 * can list and validate it without running the package. Its shape is VS Code's
 * `contributes.configuration` cut down to what a settings page can draw without knowing the
 * module — a titled group of fields (a string, a secret, a boolean, a number, a choice among
 * options, a list of lines, or a table of fixed rows) — plus a `parent` that draws the group
 * inside another's card.
 * The group's name is the contribution's id. A group whose status changes at run time (the
 * sandbox's backends) contributes that as code to `PluginConfigPage.status`.
 *
 * Values live in `server_settings` under `plugin-config:<group>`, one JSON document per group
 * — server-global, like the proxy: plugins load once per process (the closure over every
 * Project's list, PRFC-0010), so their options are the process's too. A secret is stored in
 * the clear beside the other settings the server keeps and is masked at every API surface; a
 * masked value sent back keeps the stored one, the models-page rule.
 *
 * Delivery is a pull. The module that declared a group reads it: `get` merges what is stored
 * onto the declared defaults, so a first boot reads a complete document; `watch` fires after
 * every save, which is how a module applies an edit without a restart or a re-assembly of the
 * App. Nothing else carries the values on its behalf, so each reader turns the document into
 * its own typed settings at its own boundary. Declaring data on the slot does not order the
 * boot (a data-only contribution), which is what lets one module both declare and require.
 *
 * Two nodes, for the same ordering reason. `PluginConfigProvider` holds the values and takes
 * the declarations; `PluginConfigPage` (config-page.ts) is what the admin API reads — the
 * entries with their live notices — and takes the status code. A status contributor (the sandbox's, which reads
 * the sandbox service) is created before the page, and a sandbox backend reading its own
 * group is created after the provider: one node for both would close that circle.
 */
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import type { ClassCtx, Slot } from "@adelie/core/kernel";
import type {
  PluginConfigEntry,
  PluginConfigField,
  PluginConfigOption,
  PluginConfigPinColumn,
  PluginConfigTableColumn,
  PluginConfigTableRow,
  PluginConfiguration,
} from "../api/types.js";
import { Settings } from "../mechanisms/settings.js";
import { maskApiKey } from "../services/project-config-service.js";

export type { PluginConfigField, PluginConfigNotice, PluginConfiguration } from "../api/types.js";

const FIELD_TYPES = new Set<PluginConfigField["type"]>([
  "string",
  "secret",
  "boolean",
  "number",
  "enum",
  "list",
  "table",
]);

/** A field name: what the manifest and the stored document are keyed by. */
const FIELD_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;

/** A table row's id: what its stored cells are keyed by. */
const ROW_ID = /^[a-z][a-z0-9-]*$/;

const COLUMN_TYPES = new Set<PluginConfigTableColumn["type"]>(["string", "boolean", "enum"]);

/** An enum's options, checked: every one a string value with a title. */
function parseOptions(options: unknown, where: string): PluginConfigOption[] {
  if (!Array.isArray(options) || options.length === 0) {
    throw new Error(`${where}.options must list the choices`);
  }
  return options.map((o, i) => {
    const opt = (o ?? {}) as Record<string, unknown>;
    if (typeof opt.value !== "string" || typeof opt.title !== "string") {
      throw new Error(`${where}.options[${i}] needs a string value and title`);
    }
    return {
      value: opt.value,
      title: opt.title,
      ...(typeof opt.titleZh === "string" ? { titleZh: opt.titleZh } : {}),
      ...describedBy(opt),
    };
  });
}

export const isRecord = (v: unknown): v is Record<string, unknown> =>
  v !== null && typeof v === "object" && !Array.isArray(v);

/** A column's (or row's, or option's) description, in both languages, where declared as text. */
function describedBy(c: Record<string, unknown>): { description?: string; descriptionZh?: string } {
  return {
    ...(typeof c.description === "string" ? { description: c.description } : {}),
    ...(typeof c.descriptionZh === "string" ? { descriptionZh: c.descriptionZh } : {}),
  };
}

/** A table's pin column: a boolean column of it, and its tooltip pinned and not. */
function parsePin(
  raw: unknown,
  columns: readonly PluginConfigTableColumn[],
  where: string,
): PluginConfigPinColumn {
  const p = (raw ?? {}) as Record<string, unknown>;
  if (typeof p.on !== "string" || typeof p.off !== "string") {
    throw new Error(`${where}.pin needs an on and an off text`);
  }
  if (columns.find((c) => c.name === p.column)?.type !== "boolean") {
    throw new Error(`${where}.pin.column must name a boolean column`);
  }
  return {
    column: p.column as string,
    on: p.on,
    off: p.off,
    ...(typeof p.onZh === "string" ? { onZh: p.onZh } : {}),
    ...(typeof p.offZh === "string" ? { offZh: p.offZh } : {}),
  };
}

/** Whether a value is of a table column's type. */
function cellFits(column: PluginConfigTableColumn, value: unknown): boolean {
  if (column.type === "boolean") return typeof value === "boolean";
  if (column.type === "enum") {
    return typeof value === "string" && (column.options ?? []).some((o) => o.value === value);
  }
  return typeof value === "string";
}

/** A `table` field's columns and rows, checked: every row declares every column, and fits it. */
function parseTable(
  f: Record<string, unknown>,
  where: string,
): { columns: PluginConfigTableColumn[]; rows: PluginConfigTableRow[] } {
  if (!Array.isArray(f.columns) || f.columns.length === 0) {
    throw new Error(`${where}.columns must list the columns`);
  }
  const columns = f.columns.map((raw, i): PluginConfigTableColumn => {
    const c = (raw ?? {}) as Record<string, unknown>;
    const at = `${where}.columns[${i}]`;
    if (typeof c.name !== "string" || !FIELD_NAME.test(c.name)) {
      throw new Error(`${at}.name is not a valid name`);
    }
    if (
      typeof c.type !== "string" ||
      !COLUMN_TYPES.has(c.type as PluginConfigTableColumn["type"])
    ) {
      throw new Error(`${at}.type must be one of ${[...COLUMN_TYPES].join(", ")}`);
    }
    if (typeof c.title !== "string" || c.title === "") throw new Error(`${at}.title is required`);
    return {
      name: c.name,
      type: c.type as PluginConfigTableColumn["type"],
      title: c.title,
      ...(typeof c.titleZh === "string" ? { titleZh: c.titleZh } : {}),
      ...describedBy(c),
      ...(c.type === "enum" ? { options: parseOptions(c.options, at) } : {}),
    };
  });
  if (!Array.isArray(f.rows) || f.rows.length === 0) {
    throw new Error(`${where}.rows must list the rows`);
  }
  const ids = new Set<string>();
  const rows = f.rows.map((raw, i): PluginConfigTableRow => {
    const r = (raw ?? {}) as Record<string, unknown>;
    const at = `${where}.rows[${i}]`;
    if (typeof r.id !== "string" || !ROW_ID.test(r.id) || ids.has(r.id)) {
      throw new Error(`${at}.id must be a unique lower-case id`);
    }
    ids.add(r.id);
    const values = isRecord(r.values) ? r.values : {};
    for (const column of columns) {
      if (!cellFits(column, values[column.name])) {
        throw new Error(`${at}.values.${column.name} does not fit its column`);
      }
    }
    const row: PluginConfigTableRow = {
      id: r.id,
      values: Object.fromEntries(columns.map((c) => [c.name, values[c.name] as string | boolean])),
      ...describedBy(r),
    };
    if (r.valuesZh !== undefined) {
      if (!isRecord(r.valuesZh)) throw new Error(`${at}.valuesZh must be an object`);
      for (const [name, v] of Object.entries(r.valuesZh)) {
        if (columns.find((c) => c.name === name)?.type !== "string" || typeof v !== "string") {
          throw new Error(`${at}.valuesZh.${name} must be a string column's text`);
        }
      }
      row.valuesZh = r.valuesZh as Record<string, string>;
    }
    if (r.locked !== undefined) {
      if (!Array.isArray(r.locked) || !r.locked.every((n) => columns.some((c) => c.name === n))) {
        throw new Error(`${at}.locked must list columns of the table`);
      }
      row.locked = r.locked as string[];
    }
    return row;
  });
  return { columns, rows };
}

/** Where an `extensible` table stores its added rows and its row order: never a row id. */
export const TABLE_ADDED = "$added";
export const TABLE_ORDER = "$order";

/** The rows added to an `extensible` table, as stored: each well-formed one, in stored order. */
function addedRowsOf(field: PluginConfigField, raw: unknown): PluginConfigTableRow[] {
  if (field.extensible === undefined || !isRecord(raw)) return [];
  const declared = new Set((field.rows ?? []).map((r) => r.id));
  const rows: PluginConfigTableRow[] = [];
  for (const [id, cells] of Object.entries(raw)) {
    if (!ROW_ID.test(id) || declared.has(id) || !isRecord(cells)) continue;
    const columns = field.columns ?? [];
    if (!columns.every((c) => cellFits(c, cells[c.name]))) continue;
    rows.push({
      id,
      values: Object.fromEntries(columns.map((c) => [c.name, cells[c.name] as string | boolean])),
      added: true,
    });
  }
  return rows;
}

/** Rows in the stored order: ids it names first, in that order, then the rest as they come. */
function inStoredOrder(rows: PluginConfigTableRow[], raw: unknown): PluginConfigTableRow[] {
  if (!Array.isArray(raw)) return rows;
  const rank = new Map<string, number>();
  for (const id of raw) if (typeof id === "string" && !rank.has(id)) rank.set(id, rank.size);
  return rows
    .map((row, i) => ({ row, at: rank.get(row.id) ?? rank.size + i }))
    .sort((a, b) => a.at - b.at)
    .map(({ row }) => row);
}

/**
 * A `table` field as read: every declared row with the stored cells laid over the declared
 * ones (never a locked cell's: a hand-edited document cannot remap one), then — in an `extensible` table — the rows added to it, all in the stored order. A cell
 * a save changed drops its Chinese text — the name an administrator gave is the name in every
 * language. Stored rows the table neither declares nor added are left out.
 */
export function resolveTable(field: PluginConfigField, stored: unknown): PluginConfigTableRow[] {
  const cells = isRecord(stored) ? stored : {};
  const declared = declaredRowsOf(field, cells);
  if (field.extensible === undefined) return declared;
  return inStoredOrder(
    [...declared, ...addedRowsOf(field, cells[TABLE_ADDED])],
    cells[TABLE_ORDER],
  );
}

function declaredRowsOf(
  field: PluginConfigField,
  cells: Record<string, unknown>,
): PluginConfigTableRow[] {
  return (field.rows ?? []).map((row) => {
    const own = isRecord(cells[row.id]) ? (cells[row.id] as Record<string, unknown>) : {};
    const values = { ...row.values };
    for (const column of field.columns ?? []) {
      const v = own[column.name];
      if (row.locked?.includes(column.name)) continue;
      if (v !== undefined && cellFits(column, v)) values[column.name] = v as string | boolean;
    }
    const zh = Object.entries(row.valuesZh ?? {}).filter(
      ([name]) => values[name] === row.values[name],
    );
    const { valuesZh: _declared, ...rest } = row;
    return { ...rest, values, ...(zh.length > 0 ? { valuesZh: Object.fromEntries(zh) } : {}) };
  });
}

/**
 * One update of a `table` field folded onto its stored cells. Each cell is checked against its
 * column and named `<field>.<row>.<column>` when refused; a cell set back to its declared value
 * (or sent empty) is dropped, so only the cells that differ are stored; a row the table does not
 * declare is dropped; a locked cell may not change.
 */
function applyTableUpdate(
  name: string,
  field: PluginConfigField,
  stored: unknown,
  update: unknown,
): Record<string, unknown> {
  if (!isRecord(update)) {
    throw new PluginConfigError(name, `"${name}" must be an object of rows`);
  }
  const before = isRecord(stored) ? stored : {};
  const next: Record<string, unknown> = {};
  for (const row of field.rows ?? []) {
    const cells: Record<string, string | boolean> = {};
    const kept = isRecord(before[row.id]) ? (before[row.id] as Record<string, unknown>) : {};
    for (const column of field.columns ?? []) {
      const v = kept[column.name];
      // A stored locked cell (a hand-edited document) is not carried over: reads ignore it.
      if (row.locked?.includes(column.name)) continue;
      if (v !== undefined && cellFits(column, v)) cells[column.name] = v as string | boolean;
    }
    const sent = update[row.id];
    if (sent !== undefined) {
      if (!isRecord(sent)) {
        throw new PluginConfigError(name, `"${name}.${row.id}" must be an object of cells`);
      }
      for (const [columnName, raw] of Object.entries(sent)) {
        const at = `${name}.${row.id}.${columnName}`;
        const column = (field.columns ?? []).find((c) => c.name === columnName);
        if (column === undefined) {
          throw new PluginConfigError(name, `"${at}" is not a column of this table`);
        }
        const value = typeof raw === "string" ? raw.trim() : raw;
        if (value === null || value === "" || value === row.values[columnName]) {
          delete cells[columnName];
          continue;
        }
        if (!cellFits(column, value)) {
          throw new PluginConfigError(
            name,
            column.type === "enum"
              ? `"${at}" must be one of ${(column.options ?? []).map((o) => o.value).join(", ")}`
              : `"${at}" must be a ${column.type}`,
          );
        }
        if (row.locked?.includes(columnName)) {
          throw new PluginConfigError(name, `"${at}" cannot be changed`);
        }
        cells[columnName] = value as string | boolean;
      }
    }
    if (Object.keys(cells).length > 0) next[row.id] = cells;
  }
  if (field.extensible !== undefined) {
    const added =
      update[TABLE_ADDED] !== undefined
        ? checkAddedRows(name, field, update[TABLE_ADDED])
        : Object.fromEntries(
            addedRowsOf(field, before[TABLE_ADDED]).map((row) => [row.id, row.values]),
          );
    if (Object.keys(added).length > 0) next[TABLE_ADDED] = added;
    const sentOrder = update[TABLE_ORDER];
    if (
      sentOrder !== undefined &&
      (!Array.isArray(sentOrder) || !sentOrder.every((id) => typeof id === "string"))
    ) {
      throw new PluginConfigError(name, `"${name}.${TABLE_ORDER}" must be a list of row ids`);
    }
    // Only ids of rows that exist, each once; a deleted row leaves the order with it.
    const ids = new Set([...(field.rows ?? []).map((r) => r.id), ...Object.keys(added)]);
    const listed: unknown = sentOrder ?? before[TABLE_ORDER];
    const order = [
      ...new Set(
        (Array.isArray(listed) ? listed : []).filter(
          (id): id is string => typeof id === "string" && ids.has(id),
        ),
      ),
    ];
    if (order.length > 0) next[TABLE_ORDER] = order;
  }
  return next;
}

/**
 * The added rows a save sends, checked: each id a lower-case row id the table does not declare,
 * each row every column's value; a text cell may not be empty. A refused cell is named
 * `<field>.<row>.<column>`.
 */
function checkAddedRows(
  name: string,
  field: PluginConfigField,
  sent: unknown,
): Record<string, Record<string, string | boolean>> {
  if (!isRecord(sent)) {
    throw new PluginConfigError(name, `"${name}.${TABLE_ADDED}" must be an object of rows`);
  }
  const declared = new Set((field.rows ?? []).map((r) => r.id));
  const out: Record<string, Record<string, string | boolean>> = {};
  for (const [id, raw] of Object.entries(sent)) {
    if (!ROW_ID.test(id) || declared.has(id)) {
      throw new PluginConfigError(name, `"${name}.${id}" is not an id a new row may take`);
    }
    if (!isRecord(raw)) {
      throw new PluginConfigError(name, `"${name}.${id}" must be an object of cells`);
    }
    const cells: Record<string, string | boolean> = {};
    for (const column of field.columns ?? []) {
      const at = `${name}.${id}.${column.name}`;
      const v = raw[column.name];
      const value = typeof v === "string" ? v.trim() : v;
      if (!cellFits(column, value) || value === "") {
        throw new PluginConfigError(
          name,
          column.type === "enum"
            ? `"${at}" must be one of ${(column.options ?? []).map((o) => o.value).join(", ")}`
            : value === ""
              ? `"${at}" may not be empty`
              : `"${at}" must be a ${column.type}`,
        );
      }
      cells[column.name] = value as string | boolean;
    }
    out[id] = cells;
  }
  return out;
}

/**
 * Validates a declared configuration. Undefined when there is none; a malformed one throws,
 * naming where it was declared — a schema the page cannot draw is
 * a load failure of that plugin, not something to guess at.
 */
export function parsePluginConfiguration(
  doc: unknown,
  where: string,
): PluginConfiguration | undefined {
  if (doc === undefined) return undefined;
  if (doc === null || typeof doc !== "object" || Array.isArray(doc)) {
    throw new Error(`${where}: configuration must be an object`);
  }
  const d = doc as Record<string, unknown>;
  const str = (key: string): string | undefined => {
    const v = d[key];
    if (v === undefined) return undefined;
    if (typeof v !== "string") throw new Error(`${where}: configuration.${key} must be a string`);
    return v;
  };
  if (d.properties === null || typeof d.properties !== "object" || Array.isArray(d.properties)) {
    throw new Error(`${where}: configuration.properties must be an object of fields`);
  }
  const properties: Record<string, PluginConfigField> = {};
  for (const [name, raw] of Object.entries(d.properties as Record<string, unknown>)) {
    if (!FIELD_NAME.test(name)) {
      throw new Error(`${where}: configuration field "${name}" is not a valid name`);
    }
    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
      throw new Error(`${where}: configuration.properties.${name} must be an object`);
    }
    const f = raw as Record<string, unknown>;
    const type = f.type;
    if (typeof type !== "string" || !FIELD_TYPES.has(type as PluginConfigField["type"])) {
      throw new Error(
        `${where}: configuration.properties.${name}.type must be one of ${[...FIELD_TYPES].join(", ")}`,
      );
    }
    if (typeof f.title !== "string" || f.title === "") {
      throw new Error(`${where}: configuration.properties.${name}.title is required`);
    }
    const field: PluginConfigField = { type: type as PluginConfigField["type"], title: f.title };
    for (const key of [
      "titleZh",
      "description",
      "descriptionZh",
      "hint",
      "hintZh",
      "placeholder",
    ] as const) {
      const v = f[key];
      if (v === undefined) continue;
      if (typeof v !== "string") {
        throw new Error(`${where}: configuration.properties.${name}.${key} must be a string`);
      }
      field[key] = v;
    }
    if (field.type === "enum") {
      field.options = parseOptions(f.options, `${where}: configuration.properties.${name}`);
    }
    if (field.type === "table") {
      Object.assign(field, parseTable(f, `${where}: configuration.properties.${name}`));
      if (f.extensible !== undefined) {
        const e = (f.extensible ?? {}) as Record<string, unknown>;
        const at = `${where}: configuration.properties.${name}.extensible`;
        const values = isRecord(e.values) ? e.values : {};
        for (const column of field.columns ?? []) {
          if (!cellFits(column, values[column.name])) {
            throw new Error(`${at}.values.${column.name} does not fit its column`);
          }
        }
        field.extensible = {
          ...(typeof e.add === "string" ? { add: e.add } : {}),
          ...(typeof e.addZh === "string" ? { addZh: e.addZh } : {}),
          values: Object.fromEntries(
            (field.columns ?? []).map((c) => [c.name, values[c.name] as string | boolean]),
          ),
          ...(isRecord(e.valuesZh) ? { valuesZh: e.valuesZh as Record<string, string> } : {}),
        };
      }
      if (f.columnGroup !== undefined) {
        const g = (f.columnGroup ?? {}) as Record<string, unknown>;
        const at = `${where}: configuration.properties.${name}.columnGroup`;
        const known = new Set((field.columns ?? []).map((c) => c.name));
        if (
          typeof g.title !== "string" ||
          !Array.isArray(g.columns) ||
          g.columns.length === 0 ||
          !g.columns.every((c) => typeof c === "string" && known.has(c))
        ) {
          throw new Error(`${at} needs a title and columns of the table`);
        }
        field.columnGroup = {
          title: g.title,
          ...(typeof g.titleZh === "string" ? { titleZh: g.titleZh } : {}),
          ...describedBy(g),
          columns: g.columns as string[],
        };
      }
      if (f.pin !== undefined) {
        field.pin = parsePin(
          f.pin,
          field.columns ?? [],
          `${where}: configuration.properties.${name}`,
        );
      }
      if (f.rowChoice !== undefined) {
        const c = (f.rowChoice ?? {}) as Record<string, unknown>;
        if (typeof c.field !== "string" || typeof c.title !== "string" || c.title === "") {
          throw new Error(
            `${where}: configuration.properties.${name}.rowChoice needs a field and a title`,
          );
        }
        field.rowChoice = {
          field: c.field,
          title: c.title,
          ...(typeof c.titleZh === "string" ? { titleZh: c.titleZh } : {}),
        };
      }
      if (f.default !== undefined) {
        throw new Error(
          `${where}: configuration.properties.${name}.default: a table's rows are its defaults`,
        );
      }
    }
    if (field.type === "list" && f.maxItems !== undefined) {
      if (typeof f.maxItems !== "number" || !Number.isInteger(f.maxItems) || f.maxItems < 1) {
        throw new Error(
          `${where}: configuration.properties.${name}.maxItems must be a positive integer`,
        );
      }
      field.maxItems = f.maxItems;
    }
    if (field.type === "number") {
      for (const key of ["minimum", "maximum"] as const) {
        const v = f[key];
        if (v === undefined) continue;
        if (typeof v !== "number" || !Number.isFinite(v)) {
          throw new Error(`${where}: configuration.properties.${name}.${key} must be a number`);
        }
        field[key] = v;
      }
    }
    if ((field.type === "string" || field.type === "list") && f.pattern !== undefined) {
      if (typeof f.pattern !== "string") {
        throw new Error(`${where}: configuration.properties.${name}.pattern must be a string`);
      }
      try {
        new RegExp(f.pattern, "u");
      } catch {
        throw new Error(
          `${where}: configuration.properties.${name}.pattern is not a valid regular expression`,
        );
      }
      field.pattern = f.pattern;
      if (f.patternErrorMessage !== undefined) {
        if (typeof f.patternErrorMessage !== "string") {
          throw new Error(
            `${where}: configuration.properties.${name}.patternErrorMessage must be a string`,
          );
        }
        field.patternErrorMessage = f.patternErrorMessage;
      }
    }
    if (f.required !== undefined) {
      if (typeof f.required !== "boolean") {
        throw new Error(`${where}: configuration.properties.${name}.required must be a boolean`);
      }
      field.required = f.required;
    }
    if (f.advanced !== undefined) {
      if (typeof f.advanced !== "boolean") {
        throw new Error(`${where}: configuration.properties.${name}.advanced must be a boolean`);
      }
      if (f.advanced) field.advanced = true;
    }
    if (f.default !== undefined) {
      if (!valueFits(field, f.default) || valueViolation(name, field, f.default) !== undefined) {
        throw new Error(
          `${where}: configuration.properties.${name}.default does not fit a ${field.type} field`,
        );
      }
      field.default = f.default as PluginConfigField["default"];
    }
    properties[name] = field;
  }
  const switchOf = (sw: string) => {
    if (properties[sw]?.type !== "boolean") {
      throw new Error(`${where}: configuration.switch must name a boolean field`);
    }
    return sw;
  };
  // A row choice stores into an enum of the same group whose options are exactly the row ids.
  for (const [name, field] of Object.entries(properties)) {
    if (field.rowChoice === undefined) continue;
    const target = properties[field.rowChoice.field];
    const ids = (field.rows ?? []).map((r) => r.id);
    const values = (target?.options ?? []).map((o) => o.value);
    if (
      target?.type !== "enum" ||
      values.length !== ids.length ||
      !ids.every((id) => values.includes(id))
    ) {
      throw new Error(
        `${where}: configuration.properties.${name}.rowChoice.field must name an enum of this group whose options are the row ids`,
      );
    }
  }
  return {
    ...(str("title") !== undefined ? { title: str("title")! } : {}),
    ...(str("titleZh") !== undefined ? { titleZh: str("titleZh")! } : {}),
    ...(str("description") !== undefined ? { description: str("description")! } : {}),
    ...(str("descriptionZh") !== undefined ? { descriptionZh: str("descriptionZh")! } : {}),
    ...(str("switch") !== undefined ? { switch: switchOf(str("switch")!) } : {}),
    properties,
  };
}

/** Whether a value is of a field's type (a Project is named by its id, a string). */
export function valueFits(field: PluginConfigField, value: unknown): boolean {
  switch (field.type) {
    case "boolean":
      return typeof value === "boolean";
    case "number":
      return typeof value === "number" && Number.isFinite(value);
    case "enum":
      return typeof value === "string" && (field.options ?? []).some((o) => o.value === value);
    case "list":
      return Array.isArray(value) && value.every((v) => typeof v === "string");
    case "table":
      return isRecord(value);
    default:
      return typeof value === "string";
  }
}

/**
 * Why a value of the right type is still refused — outside the field's range, or a value (a
 * list's line) that does not match its pattern — or undefined when it is accepted.
 */
export function valueViolation(
  name: string,
  field: PluginConfigField,
  value: unknown,
): string | undefined {
  if (typeof value === "number") {
    if (field.minimum !== undefined && value < field.minimum) {
      return `"${name}" must be at least ${field.minimum}`;
    }
    if (field.maximum !== undefined && value > field.maximum) {
      return `"${name}" must be at most ${field.maximum}`;
    }
    return undefined;
  }
  if (field.pattern === undefined) return undefined;
  const pattern = new RegExp(field.pattern, "u");
  const bad = (Array.isArray(value) ? value : [value]).find(
    (v) => typeof v === "string" && !pattern.test(v),
  );
  if (bad === undefined) return undefined;
  return field.patternErrorMessage !== undefined
    ? `"${name}" ${field.patternErrorMessage}: ${bad}`
    : `"${name}" does not match ${field.pattern}: ${bad}`;
}

/** The schema's defaults, as the document a plugin with nothing stored reads. */
export function defaultsOf(schema: PluginConfiguration): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [name, field] of Object.entries(schema.properties)) {
    if (field.default !== undefined) out[name] = field.default;
  }
  return out;
}

/** A stored document as it may leave the server: every secret masked, everything else as is. */
export function maskValues(
  schema: PluginConfiguration,
  values: Record<string, unknown>,
): Record<string, unknown> {
  const out: Record<string, unknown> = {};
  for (const [name, field] of Object.entries(schema.properties)) {
    const v = values[name];
    if (v === undefined) continue;
    out[name] = field.type === "secret" && typeof v === "string" && v !== "" ? maskApiKey(v) : v;
  }
  return out;
}

/** What `set` refuses, with the field it refuses. */
export class PluginConfigError extends Error {
  constructor(
    readonly field: string | null,
    message: string,
  ) {
    super(message);
    this.name = "PluginConfigError";
  }
}

/**
 * One update, validated against the schema and folded onto the stored document.
 *
 * Every field the request names is checked for its type; a secret sent as the masked value
 * the page read keeps what is stored, an empty string or null clears it; a required field
 * may not end up empty. Fields the request omits keep their stored value, so a page can
 * save one field at a time.
 */
export function applyUpdate(
  schema: PluginConfiguration,
  stored: Record<string, unknown>,
  update: Record<string, unknown>,
): Record<string, unknown> {
  const next = { ...stored };
  const rowChoiceTargets = new Map(
    Object.entries(schema.properties).flatMap(([table, f]) =>
      f.rowChoice !== undefined ? [[f.rowChoice.field, table] as const] : [],
    ),
  );
  for (const [name, value] of Object.entries(update)) {
    const field = schema.properties[name];
    if (field === undefined)
      throw new PluginConfigError(name, `"${name}" is not a field of this configuration`);
    if (value === null || value === "") {
      delete next[name];
      continue;
    }
    if (field.type === "secret" && typeof value === "string") {
      const current = stored[name];
      if (typeof current === "string" && current !== "" && value === maskApiKey(current)) continue;
    }
    if (field.type === "table") {
      const cells = applyTableUpdate(name, field, stored[name], value);
      if (Object.keys(cells).length === 0) delete next[name];
      else next[name] = cells;
      continue;
    }
    // A row choice's field names a row, which may be one added to the table: checked below,
    // against the table as this save leaves it.
    if (rowChoiceTargets.has(name) && typeof value === "string") {
      next[name] = value;
      continue;
    }
    if (!valueFits(field, value)) {
      throw new PluginConfigError(
        name,
        field.type === "enum"
          ? `"${name}" must be one of ${(field.options ?? []).map((o) => o.value).join(", ")}`
          : field.type === "list"
            ? `"${name}" must be a list of strings`
            : `"${name}" must be a ${field.type}`,
      );
    }
    if (field.type === "list") {
      const items = [...new Set((value as string[]).map((v) => v.trim()).filter((v) => v !== ""))];
      if (field.maxItems !== undefined && items.length > field.maxItems) {
        throw new PluginConfigError(name, `"${name}" may hold at most ${field.maxItems} entries`);
      }
      const violation = valueViolation(name, field, items);
      if (violation !== undefined) throw new PluginConfigError(name, violation);
      if (items.length === 0) delete next[name];
      else next[name] = items;
      continue;
    }
    next[name] = typeof value === "string" ? value.trim() : value;
    if (next[name] === "") {
      delete next[name];
      continue;
    }
    const violation = valueViolation(name, field, next[name]);
    if (violation !== undefined) throw new PluginConfigError(name, violation);
  }
  for (const [target, table] of rowChoiceTargets) {
    const chosen = next[target];
    const field = schema.properties[table]!;
    if (chosen !== undefined && !resolveTable(field, next[table]).some((r) => r.id === chosen)) {
      throw new PluginConfigError(
        target,
        `"${target}" must name a row of "${table}": "${String(chosen)}" is not one (choose another row before deleting it)`,
      );
    }
  }
  for (const [name, field] of Object.entries(schema.properties)) {
    if (field.required === true && next[name] === undefined && field.default === undefined) {
      throw new PluginConfigError(name, `"${name}" is required`);
    }
  }
  return next;
}

/** A settings group as a module declares it: a configuration, and where the page draws it. */
export interface SettingsGroupDecl extends PluginConfiguration {
  /** Another group's name (its contribution id): this one is drawn inside that card and saved with it. */
  parent?: string;
  /** Position among the groups: lower first (absent = 100), then declaration order. */
  order?: number;
}

/** One settings group as the store holds it: named by its contribution id. */
export interface SettingsGroup {
  name: string;
  configuration: PluginConfiguration;
  parent?: string;
}

/** What a module reads: the group it declared, and a watch on it. */
@Interface()
export abstract class PluginConfig {
  /** The stored values merged onto the declared defaults; `{}` for a name no group answers to. */
  abstract get(name: string): Record<string, unknown>;
  /** Fires with the new document after every save of `name`; returns the unsubscribe. */
  abstract watch(name: string, cb: (values: Record<string, unknown>) => void): () => void;
  /** Whether anything was ever saved under `name` — what tells a default from a choice. */
  abstract saved(name: string): boolean;
  /** The configuration `name` was declared with (what `resolveTable` reads a table by); undefined for none. */
  abstract schema(name: string): PluginConfiguration | undefined;
}

export interface PluginConfigSlots {
  /** A settings group, as data: its id is its name, the data its configuration. */
  groups: Slot<SettingsGroupDecl>;
}

/** The entries as stored, before any live notice: what the page node builds on. */
@Interface()
export abstract class PluginConfigEntries {
  abstract describe(): PluginConfigEntry[];
  abstract set(name: string, update: Record<string, unknown>): PluginConfigEntry;
}

export interface PluginConfigStoreDeps {
  settings: Pick<Settings, "get" | "set">;
  groups: () => readonly SettingsGroup[];
}

export class PluginConfigStore {
  private readonly watchers = new Map<string, Set<(values: Record<string, unknown>) => void>>();

  constructor(private readonly deps: PluginConfigStoreDeps) {}

  private group(name: string): SettingsGroup | undefined {
    return this.deps.groups().find((g) => g.name === name);
  }

  private stored(name: string): Record<string, unknown> {
    const raw = this.deps.settings.get(`plugin-config:${name}`);
    if (raw === null) return {};
    try {
      const doc = JSON.parse(raw) as unknown;
      return doc !== null && typeof doc === "object" && !Array.isArray(doc)
        ? (doc as Record<string, unknown>)
        : {};
    } catch {
      return {};
    }
  }

  get(name: string): Record<string, unknown> {
    const group = this.group(name);
    if (group === undefined) return {};
    return { ...defaultsOf(group.configuration), ...this.stored(name) };
  }

  saved(name: string): boolean {
    return this.deps.settings.get(`plugin-config:${name}`) !== null;
  }

  schema(name: string): PluginConfiguration | undefined {
    return this.group(name)?.configuration;
  }

  watch(name: string, cb: (values: Record<string, unknown>) => void): () => void {
    const set = this.watchers.get(name) ?? new Set();
    set.add(cb);
    this.watchers.set(name, set);
    return () => void set.delete(cb);
  }

  describe(): PluginConfigEntry[] {
    return this.deps.groups().map((g) => this.entry(g));
  }

  set(name: string, update: Record<string, unknown>): PluginConfigEntry {
    const group = this.group(name);
    if (group === undefined) {
      throw new PluginConfigError(null, `no settings group named "${name}"`);
    }
    const next = applyUpdate(group.configuration, this.stored(name), update);
    this.deps.settings.set(`plugin-config:${name}`, JSON.stringify(next));
    const merged = { ...defaultsOf(group.configuration), ...next };
    for (const cb of this.watchers.get(name) ?? []) {
      try {
        cb(merged);
      } catch {
        // A watcher's failure is its own; the save has happened.
      }
    }
    return this.entry(group);
  }

  private entry(group: SettingsGroup): PluginConfigEntry {
    const { name, configuration } = group;
    return {
      name,
      configuration,
      values: maskValues(configuration, { ...defaultsOf(configuration), ...this.stored(name) }),
      ...(group.parent !== undefined ? { parent: group.parent } : {}),
    };
  }
}

/** The store as a node: values in the settings repo, groups from the declarations on its slot. */
@Module()
export class PluginConfigProvider {
  @Use() private readonly settings!: Settings;
  @Provide() pluginConfig!: PluginConfig;
  @Provide() pluginConfigEntries!: PluginConfigEntries;
  setup({ contributions }: ClassCtx) {
    const declared: Array<SettingsGroup & { order: number; index: number }> = [];
    for (const [index, c] of (contributions.groups ?? []).entries()) {
      const { parent, order, ...configuration } = c.data as unknown as SettingsGroupDecl;
      try {
        const parsed = parsePluginConfiguration(configuration, `${c.from}: group "${c.id}"`)!;
        declared.push({
          name: c.id,
          configuration: parsed,
          ...(typeof parent === "string" ? { parent } : {}),
          order: typeof order === "number" ? order : 100,
          index,
        });
      } catch (err) {
        // One malformed declaration drops that group, not the page.
        console.warn(`[plugin-config] ${err instanceof Error ? err.message : String(err)}`);
      }
    }
    declared.sort((a, b) => a.order - b.order || a.index - b.index);
    const groups: SettingsGroup[] = declared.map(({ name, configuration, parent }) => ({
      name,
      configuration,
      ...(parent !== undefined ? { parent } : {}),
    }));
    const store = new PluginConfigStore({ settings: this.settings, groups: () => groups });
    this.pluginConfig = store;
    this.pluginConfigEntries = store;
  }
}