Skip to content

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

10.8 KB
Raw Blame
/**
 * The Plugins page's view of the settings groups: the stored entries (`PluginConfigEntries`,
 * config.ts) with what each group's status contributor reports live — notices, actions, enum
 * options this machine cannot honour, values derived for a document saved before a field
 * existed, and whether a backend the group needs is installed. A separate node from the store
 * for the ordering reason config.ts gives: a status contributor (the sandbox's, which reads the
 * sandbox service) is created before this page, and a sandbox backend reading its own group is
 * created after the provider.
 */
import { Interface, Module, Provide, Use } from "@adelie/core/kernel";
import type { ClassCtx, Slot } from "@adelie/core/kernel";
import type {
  PluginConfigBackend,
  PluginConfigEntry,
  PluginConfigNotice,
  PluginConfiguration,
} from "../api/types.js";
import {
  PluginConfig,
  PluginConfigEntries,
  PluginConfigError,
  TABLE_ADDED,
  isRecord,
  resolveTable,
} from "./config.js";

/**
 * The code half of a `status` contribution: a group's live notices, asked per read, and the
 * ACTIONS it offers.
 *
 * An action is for what a person cannot express as a field: something the deployment must DO
 * once, on the machine, before the settings above mean anything — the Windows sandbox's local
 * accounts, which need an administrator's consent. Naming the command in a notice puts the work
 * on whoever reads it; an action lets the module do it and report back.
 */
export interface SettingsGroupStatus {
  /**
   * The live notices, asked per read. `stored` and `configuration` are the group's document
   * whole and its declaration, as `derive` gets them, for a notice about what is stored.
   */
  notices(
    stored: Record<string, unknown>,
    configuration: PluginConfiguration,
  ): PluginConfigNotice[];
  /**
   * After a save of this group or of one drawn inside its card: does what that save sets in
   * motion beyond the group's own watchers, and resolves once it has settled, so the notices
   * the save answers with are current.
   */
  saved?(): Promise<void>;
  /** What this group offers to do, drawn as buttons beneath its notices. */
  actions?(): PluginConfigAction[];
  /**
   * Enum options this machine cannot honour right now: drawn greyed out with the reason, and a
   * save choosing one is refused. Asked per read, like the notices.
   */
  unavailable?(): PluginConfigUnavailable[];
  /** Runs one, by its id. Told what happened, in words the page shows as they are. */
  run?(action: string): Promise<PluginConfigActionResult>;
  /**
   * The values the page reads, with what the group derives for a document saved before one of
   * its fields existed (the sandbox's `enabled`, read off its old mode). Read-side only: the
   * document on disk is never rewritten, and the module applying the group derives the same way
   * from the document it reads. `stored` is that document whole — the stored keys merged onto
   * the defaults, including keys the schema no longer declares, which `values` leaves out;
   * `configuration` is the group's declaration (what `resolveTable` reads a table by).
   */
  derive?(
    values: Record<string, unknown>,
    stored: Record<string, unknown>,
    configuration: PluginConfiguration,
  ): Record<string, unknown>;
  /** For a group a backend plugin enforces: whether one for this OS is installed, and the default. */
  backend?(): PluginConfigBackend;
  /**
   * Completes a save of this group before it is validated and stored: what every save must
   * write besides the fields the page changed. `current` is the group's values as the page
   * reads them (`derive` applied) (the sandbox pins the default preset the card shows, which a
   * document saved before the default preset may not have).
   */
  saving?(
    update: Record<string, unknown>,
    current: Record<string, unknown>,
  ): Record<string, unknown>;
}

/** One enum option a settings group cannot honour on this machine, and why. */
export interface PluginConfigUnavailable {
  field: string;
  /** A `table` field's column: the option is unavailable in every cell of that column. */
  column?: string;
  /** An enum option, or a boolean field's position: "true" or "false". */
  value: string;
  reason: string;
  reasonZh?: string;
}

/** One thing a settings group can do, named for the button that runs it. */
export interface PluginConfigAction {
  id: string;
  title: string;
  titleZh?: string;
  /** What pressing it will do, shown beside the button — a person consents to what they read. */
  description?: string;
  descriptionZh?: string;
}

/** What an action reports: whether it did what it said, and what to tell the person. */
export interface PluginConfigActionResult {
  ok: boolean;
  message: string;
  messageZh?: string;
  /**
   * Work the action started and did not wait for, reported through `progress` notices; it
   * resolves when that work ends. The page node then settles the card the way a save does (a
   * sandbox backend the work made usable loads again). Never sent to the page.
   */
  settled?: Promise<void>;
}

/** What the settings page reads and writes. */
@Interface()
export abstract class PluginConfigAdmin {
  /** Every declared group, in order, with its live notices; values masked. */
  abstract describe(): PluginConfigEntry[];
  /** Validates and stores one update; answers that entry, masked, with its notices once its card's status has settled. */
  abstract set(name: string, update: Record<string, unknown>): Promise<PluginConfigEntry>;
  /** Runs one group's action and says what happened; throws PluginConfigError for an unknown one. */
  abstract run(name: string, action: string): Promise<PluginConfigActionResult>;
}

export interface PluginConfigAdminSlots {
  /** Live notices for a group that has any (`group` names it). */
  status: Slot<{ group: string }, SettingsGroupStatus>;
}

/** The page's view: the stored entries with the live notices their status contributors report. */
@Module()
export class PluginConfigPage {
  @Use() private readonly entries!: PluginConfigEntries;
  /** The stored documents whole, which a group's `derive` reads. */
  @Use() private readonly pluginConfig!: PluginConfig;
  @Provide() pluginConfigAdmin!: PluginConfigAdmin;
  setup({ contributions }: ClassCtx) {
    const entries = this.entries;
    const pluginConfig = this.pluginConfig;
    const status = new Map<string, SettingsGroupStatus>();
    for (const c of contributions.status ?? []) {
      status.set(c.data.group as string, c.code as SettingsGroupStatus);
    }
    const withStatus = (entry: PluginConfigEntry): PluginConfigEntry => {
      const group = status.get(entry.name);
      const stored = pluginConfig.get(entry.name);
      const notices = group?.notices(stored, entry.configuration) ?? [];
      const actions = group?.actions?.() ?? [];
      const unavailable = group?.unavailable?.() ?? [];
      const backend = group?.backend?.();
      return {
        ...entry,
        ...(group?.derive !== undefined
          ? { values: group.derive(entry.values, stored, entry.configuration) }
          : {}),
        ...(notices.length > 0 ? { notices } : {}),
        ...(actions.length > 0 ? { actions } : {}),
        ...(unavailable.length > 0 ? { unavailable } : {}),
        ...(backend !== undefined ? { backend } : {}),
      };
    };
    /** A group's values as the page reads them: stored onto defaults, then derived. */
    const readValues = (name: string, group: SettingsGroupStatus) => {
      const entry = entries.describe().find((e) => e.name === name);
      if (entry === undefined) return {};
      return (
        group.derive?.(entry.values, pluginConfig.get(name), entry.configuration) ?? entry.values
      );
    };
    this.pluginConfigAdmin = {
      describe: () => entries.describe().map(withStatus),
      set: async (name, sent) => {
        const group = status.get(name);
        const update =
          group?.saving === undefined ? sent : group.saving(sent, readValues(name, group));
        // An option this machine cannot honour is refused like an invalid value, naming it.
        for (const u of status.get(name)?.unavailable?.() ?? []) {
          if (u.column !== undefined) {
            // A table is saved whole: only a cell the save CHANGES to the value is refused, so
            // one already holding it (a backend went away since) does not block the others.
            const rows = update[u.field];
            const entry = entries.describe().find((e) => e.name === name);
            const field = entry?.configuration.properties[u.field];
            const current =
              field?.type === "table" ? resolveTable(field, entry!.values[u.field]) : [];
            const before = (id: string): Record<string, unknown> =>
              current.find((r) => r.id === id)?.values ?? {};
            // The declared rows' cells, and the added rows (stored whole, so every cell of
            // theirs is "sent").
            const sentRows = isRecord(rows)
              ? { ...rows, ...(isRecord(rows[TABLE_ADDED]) ? rows[TABLE_ADDED] : {}) }
              : {};
            const row = Object.entries(sentRows).find(
              ([id, cells]) =>
                isRecord(cells) &&
                cells[u.column!] === u.value &&
                before(id)[u.column!] !== u.value,
            );
            if (row !== undefined) {
              const at = `${u.field}.${row[0]}.${u.column}`;
              throw new PluginConfigError(
                u.field,
                `"${at}" cannot be "${u.value}" here: ${u.reason}`,
              );
            }
            continue;
          }
          // A boolean field's position is named "true" / "false".
          const sent = update[u.field];
          if ((typeof sent === "boolean" ? String(sent) : sent) === u.value) {
            throw new PluginConfigError(
              u.field,
              `"${u.field}" cannot be "${u.value}" here: ${u.reason}`,
            );
          }
        }
        const saved = entries.set(name, update);
        await status.get(saved.parent ?? name)?.saved?.();
        return withStatus(saved);
      },
      run: async (name, action) => {
        const group = status.get(name);
        const offered = group?.actions?.() ?? [];
        if (group?.run === undefined || !offered.some((a) => a.id === action)) {
          throw new PluginConfigError(null, `"${name}" offers no action "${action}".`);
        }
        const { settled, ...result } = await group.run(action);
        // What the action changed on the machine is settled like a save of its card: the
        // owner's status runs its follow-up (a backend that failed its check loads again).
        const owner = entries.describe().find((e) => e.name === name)?.parent ?? name;
        const settle = async () => {
          await status.get(owner)?.saved?.();
        };
        if (settled === undefined) await settle();
        else void settled.then(settle, settle).catch(() => {});
        return result;
      },
    };
  }
}