hecks 3.10.0 → 3.11.0

data/lib/hecks/projections/site/cms_editor/templates/src/commands.ts.tmpl

@@ -2,16 +2,21 @@ __BANNER__
 
 // Running one command and judging what came of it. The host answers HTTP 200 whether or not the
 // domain refused, and its `refusals` list can carry entries replayed from history, so the outcome is
-// judged by the state that comes back: the instance has to show the change. Only when the state did
-// not change at all (a repeated command, a lifecycle move to the state it is already in) does the
-// answer's last refusal decide, and only if it names this verb.
+// judged by the state that comes back, never by what was sent: a command may set fields from
+// arguments that are not fields (a clearing argument), so the arguments are no evidence. The command
+// took effect when the instance's state changed, and for a lifecycle move when it reached the state
+// the move names. When the state did not change at all (a repeated command, a move to the state it
+// is already in) the answer's last refusal decides, and only if it names this verb.
 import type { Answer, HostClient } from "@hecks/client";
 import { DomainUnavailable } from "@hecks/client";
 
+import { qualified } from "./names.ts";
 import type { Aggregate, Command } from "./schema.ts";
+import { problemsOf } from "./ui/block_list.js";
+import type { Problem } from "./ui/blocks.ts";
 
 export type State = Record<string, unknown>;
-export type Outcome = { ok: true; id: string } | { ok: false; message: string };
+export type Outcome = { ok: true; id: string } | { ok: false; message: string; field?: string; problems?: Problem[] };
 
 /** The text an identity value holds: the part of a value object, or the plain value. */
 export function leaf(value: unknown): string | null {
@@ -24,40 +29,86 @@ export const idOf = (agg: Aggregate, state: State | undefined): string | null =>
 
 /** The state of one instance in an answer, or undefined when the answer holds none by that id. */
 export function instanceIn(client: HostClient, answer: Answer, agg: Aggregate, id: string): State | undefined {
-  return client.instancesOf(answer, agg.name).find(([key]) => key === id)?.[1];
+  return client.instancesOf(answer, qualified(agg)).find(([key]) => key === id)?.[1];
 }
 
-/** True when everything `sent` carries is in `held`; numbers and their text compare equal. */
-export function covers(sent: unknown, held: unknown): boolean {
-  if (Array.isArray(sent)) return Array.isArray(held) && sent.length === held.length && sent.every((item, at) => covers(item, held[at]));
-  if (sent && typeof sent === "object") {
-    const keys = Object.keys(sent);
-    if (!held || typeof held !== "object") return keys.length === 1 && covers((sent as State)[keys[0]], held);
-    return keys.every((key) => covers((sent as State)[key], (held as State)[key]));
-  }
-  return String(sent) === String(held);
+/**
+ * A client that asks the host to read once and remembers the answer, for a request that only reads:
+ * the page and the navigation's counts then come from one read of the host.
+ */
+export function reading(client: HostClient): HostClient {
+  let held: Promise<Answer> | undefined;
+  return new Proxy(client, {
+    get(target, key) {
+      if (key === "read") return () => (held ??= target.read());
+      const member = Reflect.get(target, key, target);
+      return typeof member === "function" ? member.bind(target) : member;
+    },
+  });
 }
 
-const sameState = (a: State | undefined, b: State | undefined): boolean => JSON.stringify(a) === JSON.stringify(b);
+/**
+ * A value as it is compared: the keys of an object in order and each null left out, since one answer
+ * of a host may echo a slot that was never set as null where another leaves it out, in an order of its own.
+ */
+function canonical(value: unknown): unknown {
+  if (Array.isArray(value)) return value.map(canonical);
+  if (value === null || typeof value !== "object") return value;
+  const held = Object.entries(value as object).filter(([, part]) => part !== null);
+  return Object.fromEntries(held.sort(([a], [b]) => (a < b ? -1 : 1)).map(([key, part]) => [key, canonical(part)]));
+}
+
+const sameState = (a: State | undefined, b: State | undefined): boolean => JSON.stringify(canonical(a)) === JSON.stringify(canonical(b));
 
+/** Whether the host's refusal names this aggregate's verb: by its chapter too when the editor spans several. */
 function refusedLast(answer: Answer, agg: Aggregate, command: Command): boolean {
   const last = (answer.refusals ?? []).at(-1);
-  return last !== undefined && String(last.verb ?? "").replace(/^.*::/, "") === `${agg.name}.${command.name}`;
+  if (last === undefined) return false;
+  const verb = String(last.verb ?? "");
+  return verb.replace(/^.*::/, "") === `${agg.name}.${command.name}` && (!agg.chapter || !verb.includes("::") || verb.startsWith(`${agg.chapter}::`));
 }
 
 /** Whether `after` shows the command took effect, given the instance as it was `before`. */
-export function applied(agg: Aggregate, command: Command, args: State, before: State | undefined, after: State | undefined, answer: Answer): boolean {
+export function applied(agg: Aggregate, command: Command, before: State | undefined, after: State | undefined, answer: Answer): boolean {
   if (!after) return false;
   if (sameState(before, after)) return !refusedLast(answer, agg, command);
   const move = agg.lifecycle?.transitions.find((transition) => transition.verb === command.name);
-  if (move && agg.lifecycle) return after[agg.lifecycle.field] === move.to;
-  return covers(args, after);
+  return move && agg.lifecycle ? after[agg.lifecycle.field] === move.to : true;
+}
+
+const label = (name: string): string => name.replace(/_/g, " ");
+
+/** The command's attribute a value object's name stands for, to name the offending field. */
+function fieldOf(command: Command, type: string): string {
+  const held = command.attributes.find((attr) => attr.type === type);
+  return held ? label(held.name) : type;
+}
+
+/**
+ * The words for a refusal. The host words a given as `<Command> refused — <condition>`, which reads
+ * as though the condition were the reason, so it is shown as the condition that was not met; an
+ * invariant is shown as the field and the rule, without the value that offended (raw JSON).
+ */
+export function refusalText(refusal: { kind?: string; error?: string } | undefined, command: Command): string {
+  const error = refusal?.error ?? "";
+  const refused = /^.+? refused — (.+)$/s.exec(error);
+  if (refusal?.kind === "GivenNotMet" && refused) return `Not allowed unless ${refused[1]}.`;
+  if (refusal?.kind === "EnsuresNotMet" && refused) return `Not allowed: the result would break this rule: ${refused[1]}.`;
+  const invariant = /^(.+?) invariant violated — (.+?)(?: \(given .*\))?$/s.exec(error);
+  if (invariant) return `${fieldOf(command, invariant[1])}: ${invariant[2]}.`;
+  if (refusal?.kind === "InvariantViolation" && refused) return `${refused[1]}.`;
+  return error || `The domain did not apply ${command.name}.`;
+}
+
+/** The name of the command's attribute a refused invariant is about, so its input can be marked; undefined when none. */
+export function refusedField(refusal: { kind?: string; error?: string } | undefined, command: Command): string | undefined {
+  const invariant = /^(.+?) invariant violated — /s.exec(refusal?.error ?? "");
+  return invariant ? command.attributes.find((attr) => attr.type === invariant[1])?.name : undefined;
 }
 
 /** The words for a command that changed nothing: the host's last refusal, or a plain statement. */
 export function refusalMessage(answer: Answer, command: Command): string {
-  const last = (answer.refusals ?? []).at(-1);
-  return last?.error ?? `The domain did not apply ${command.name}.`;
+  return refusalText((answer.refusals ?? []).at(-1), command);
 }
 
 /**
@@ -68,10 +119,13 @@ export async function runCommand(client: HostClient, agg: Aggregate, command: Co
   try {
     const id = to ?? idOf(agg, args);
     const before = id ? instanceIn(client, await client.read(), agg, id) : undefined;
-    const answer = await client.dispatch(`${agg.name}.${command.name}`, args, to, command.role ?? undefined);
+    const answer = await client.dispatch(`${qualified(agg)}.${command.name}`, args, to, command.role ?? undefined);
     const after = id ? instanceIn(client, answer, agg, id) : undefined;
-    if (id && applied(agg, command, args, before, after, answer)) return { ok: true, id };
-    return { ok: false, message: refusalMessage(answer, command) };
+    if (id && applied(agg, command, before, after, answer)) return { ok: true, id };
+    const last = (answer.refusals ?? []).at(-1);
+    const problems: Problem[] = problemsOf(last?.error, command.attributes, args, agg.valueObjects);
+    const field = refusedField(last, command);
+    return { ok: false, message: refusalMessage(answer, command), field, problems };
   } catch (err) {
     if (err instanceof DomainUnavailable) return { ok: false, message: `The domain could not be reached: ${err.message}` };
     throw err;

data/lib/hecks/projections/site/cms_editor/templates/src/config.ts.tmpl

@@ -5,17 +5,23 @@ __BANNER__
 
 export const EDITOR = {
   title: __TITLE__,
+  brand: __BRAND__,
+  logo: __LOGO__,
   basePath: __BASE_PATH__,
   ssoPath: __SSO_PATH__,
   login: __LOGIN__,
   sessionCookie: __SESSION_COOKIE__,
   sessionMaxAge: 28800,
+  flashMaxAge: 60,
   hostCookie: __HOST_COOKIE__,
   hostEnv: __HOST_ENV__,
   hostDefault: __HOST_DEFAULT__,
   roles: __ROLES__,
   mediaDir: __MEDIA_DIR__,
   mediaMaxBytes: __MEDIA_MAX_BYTES__,
+  pageSize: __PAGE_SIZE__,
+  /** Where a record is shown on the site, with `{key}`, `{kind}`, `{slug}` and `{id}`; null for no preview. */
+  preview: __PREVIEW__ as string | null,
   accountPath: "/accounts/me",
   membersPath: "/members",
   rememberMs: 60000,

data/lib/hecks/projections/site/cms_editor/templates/src/flash.ts.tmpl

@@ -0,0 +1,52 @@
+__BANNER__
+
+// A notice that survives one redirect: "Published." after a command succeeds and the person is sent
+// to the page that shows the result. It is carried in a short-lived cookie that is signed (so a
+// visitor cannot make the editor say something), holds only a kind and a sentence, and is read
+// once: the page that shows it clears it in the same response. There is no server-side state.
+// The sentence is escaped wherever it is shown; it is encoded as base64url so no character of it can
+// break out of the cookie.
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+import { EDITOR } from "./config.ts";
+
+export type FlashKind = "success" | "error" | "info";
+
+export interface Flash {
+  kind: FlashKind;
+  message: string;
+}
+
+const SUFFIX = ":editor-flash";
+const NAME = `${EDITOR.sessionCookie}_flash`;
+const ATTRIBUTES = `Path=${EDITOR.basePath}; HttpOnly; SameSite=Lax`;
+const KINDS: readonly string[] = ["success", "error", "info"];
+
+const sign = (secret: string, payload: string): string => createHmac("sha256", secret + SUFFIX).update(payload).digest("base64url");
+
+/** The `Set-Cookie` value that carries `flash` to the next page. */
+export function flashCookie(flash: Flash, secret: string, now: () => number = Date.now): string {
+  const payload = Buffer.from(JSON.stringify({ k: flash.kind, m: flash.message.slice(0, 300), t: Math.floor(now() / 1000) })).toString("base64url");
+  const secure = process.env.NODE_ENV === "production" ? "; Secure" : "";
+  return `${NAME}=${payload}.${sign(secret, payload)}; ${ATTRIBUTES}; Max-Age=${EDITOR.flashMaxAge}${secure}`;
+}
+
+/** The `Set-Cookie` value that spends the notice. */
+export const spentFlash = (): string => `${NAME}=; ${ATTRIBUTES}; Max-Age=0`;
+
+/** The notice a `Cookie` header carries, or null when it has none, it was forged or it has expired. */
+export function readFlash(header: string | null, secret: string, now: () => number = Date.now): Flash | null {
+  const raw = header?.split(";").map((part) => part.trim()).find((part) => part.startsWith(`${NAME}=`))?.slice(NAME.length + 1);
+  const [payload, signature] = raw?.split(".") ?? [];
+  if (!payload || !signature || !secret) return null;
+  const expected = Buffer.from(sign(secret, payload));
+  const given = Buffer.from(signature);
+  if (expected.length !== given.length || !timingSafeEqual(expected, given)) return null;
+  try {
+    const found = JSON.parse(Buffer.from(payload, "base64url").toString("utf8"));
+    const fresh = typeof found.t === "number" && now() / 1000 - found.t <= EDITOR.flashMaxAge && now() / 1000 >= found.t - 5;
+    return fresh && KINDS.includes(found.k) && typeof found.m === "string" ? { kind: found.k, message: found.m } : null;
+  } catch {
+    return null;
+  }
+}

data/lib/hecks/projections/site/cms_editor/templates/src/host.ts.tmpl

@@ -4,7 +4,8 @@ __BANNER__
 // posting to /dispatch from this machine. The host accepts that protocol from a loopback peer only,
 // which is why this server, not the browser, talks to it; it authenticates each person itself
 // (auth/) before any of these calls is made on their behalf.
-import { HostClient } from "@hecks/client";
+import { DomainRefusal, HostClient, rowsOf } from "@hecks/client";
+import type { Answer } from "@hecks/client";
 
 import { EDITOR } from "./config.ts";
 import { SCHEMA } from "./schema.ts";
@@ -13,6 +14,8 @@ export interface HostOptions {
   /** The host's address, when not read from the environment variable the Editor row names. */
   url?: string;
   fetch?: typeof fetch;
+  /** The domain to address, when it is not the chapter the editor edits (pictures kept in another chapter). */
+  domain?: string;
 }
 
 /** The host's base URL, without a trailing slash. */
@@ -22,5 +25,19 @@ export function hostUrl(options: HostOptions = {}): string {
 
 /** A client for the domain this editor edits. */
 export function hostClient(options: HostOptions = {}): HostClient {
-  return new HostClient({ domain: SCHEMA.domain, url: hostUrl(options), fetch: options.fetch, timeoutMs: EDITOR.timeoutMs });
+  return new HostClient({ domain: options.domain ?? SCHEMA.domain, url: hostUrl(options), fetch: options.fetch, timeoutMs: EDITOR.timeoutMs });
+}
+
+/**
+ * The rows a query answered. A host that has no such query for its running domain (a declared
+ * query the Rust host does not generate) answers with no entry at all, which `rowsOf` reads as
+ * null; that is a refusal here, not an empty list, or a list page, a picker or the picture
+ * listing would show nothing while the records are there.
+ *
+ * @throws {DomainRefusal} when the host refused the question or did not answer it
+ */
+export function rowsAnswered(answer: Answer, name: string): Record<string, unknown>[] {
+  const rows = rowsOf(answer, name);
+  if (rows === null) throw new DomainRefusal("QueryNotAnswered", `The host did not answer ${name}.`);
+  return rows as Record<string, unknown>[];
 }

data/lib/hecks/projections/site/cms_editor/templates/src/media/handler.ts.tmpl

@@ -11,12 +11,15 @@ __BANNER__
 // the bytes, and a client-supplied filename is never used.
 import { createHash } from "node:crypto";
 
-import { DomainRefusal, rowsOf } from "@hecks/client";
+import { DomainRefusal } from "@hecks/client";
 import type { HostClient } from "@hecks/client";
 
 import { instanceIn, leaf, runCommand } from "../commands.ts";
 import type { State } from "../commands.ts";
 import { EDITOR } from "../config.ts";
+import { hostClient, rowsAnswered } from "../host.ts";
+import type { HostOptions } from "../host.ts";
+import { mayEdit, qualified } from "../names.ts";
 import { SCHEMA } from "../schema.ts";
 import type { Aggregate, Media, MediaField } from "../schema.ts";
 import { boundaryOf, parts } from "./multipart.ts";
@@ -76,7 +79,14 @@ function picture(storage: MediaStorage, media: Media, state: State) {
 }
 
 function aggregateOf(media: Media): Aggregate {
-  return SCHEMA.aggregates.find((candidate) => candidate.name === media.aggregate) as Aggregate;
+  const own = (candidate: Aggregate): boolean => candidate.name === media.aggregate && (candidate.chapter ?? SCHEMA.domain) === (media.domain ?? SCHEMA.domain);
+  return media.definition ?? (SCHEMA.aggregates.find(own) as Aggregate);
+}
+
+/** Whether a person in `role` may use the pictures: not when the chapter that holds them limits its roles to others. */
+export function mediaOpen(role: string | null): boolean {
+  const media = SCHEMA.media as Media;
+  return mayEdit(aggregateOf(media), role);
 }
 
 /** What was uploaded, or the refusal to answer with. */
@@ -113,9 +123,16 @@ async function upload(client: HostClient, storage: MediaStorage, request: Reques
 
 async function stateOf(client: HostClient, media: Media): Promise<State[]> {
   const agg = aggregateOf(media);
-  if (!media.listing) return client.instancesOf(await client.read(), agg.name).map(([, state]) => state);
-  const name = `${agg.name}.${media.listing}`;
-  return (rowsOf(await client.query(name, {}), name) ?? []) as State[];
+  const everything = async () => client.instancesOf(await client.read(), qualified(agg)).map(([, state]) => state);
+  if (!media.listing) return everything();
+  const name = `${qualified(agg)}.${media.listing}`;
+  try {
+    return rowsAnswered(await client.query(name, {}), name) as State[];
+  } catch (err) {
+    // The listing only narrows what is offered; a host that does not answer it still holds the pictures.
+    if (err instanceof DomainRefusal) return everything();
+    throw err;
+  }
 }
 
 async function listing(client: HostClient, storage: MediaStorage, media: Media): Promise<Response> {
@@ -142,10 +159,16 @@ async function serve(storage: MediaStorage, key: string): Promise<Response> {
   });
 }
 
-/** The handler of everything under `<base>/media`, given the path segments after `media`. */
-export function mediaHandler(storage: MediaStorage = diskStorage()) {
+/**
+ * The handler of everything under `<base>/media`, given the path segments after `media`. When the
+ * pictures are kept in another chapter (`media.domain`), they are read and registered through a
+ * client for that chapter, not the editor's own.
+ */
+export function mediaHandler(storage: MediaStorage = diskStorage(), options: HostOptions = {}) {
   const media = SCHEMA.media as Media;
-  return (client: HostClient, request: Request, rest: string[]): Promise<Response> | Response => {
+  const elsewhere = media.domain ? hostClient({ ...options, domain: media.domain }) : null;
+  return (editors: HostClient, request: Request, rest: string[]): Promise<Response> | Response => {
+    const client = elsewhere ?? editors;
     if (rest.length === 0 && request.method === "POST") return upload(client, storage, request, media);
     if (rest.length === 0 && request.method === "GET") return listing(client, storage, media);
     if (rest.length === 1 && request.method === "GET") return serve(storage, rest[0]);

data/lib/hecks/projections/site/cms_editor/templates/src/names.ts.tmpl

@@ -0,0 +1,36 @@
+__BANNER__
+
+// How an aggregate is named in the three places it has a name: its address in the editor, the name
+// the host knows it by, and the key the navigation and the counts hold it under. An editor of one
+// chapter names an aggregate by its own name in all three. An editor of several chapters names it by
+// its chapter as well, so two aggregates of one name in different chapters stay two.
+import { SCHEMA } from "./schema.ts";
+import type { Aggregate } from "./schema.ts";
+
+/** The path segments that address an aggregate under the editor's base path. */
+export const at = (agg: Aggregate): string[] => (agg.chapter ? [agg.chapter, agg.name] : [agg.name]);
+
+/** The name the host knows an aggregate by: `Chapter::Aggregate` when the editor spans chapters. */
+export const qualified = (agg: Aggregate): string => (agg.chapter ? `${agg.chapter}::${agg.name}` : agg.name);
+
+/** What the navigation and the counts hold an aggregate under. */
+export const keyOf = (agg: Aggregate): string => (agg.chapter ? `${agg.chapter}.${agg.name}` : agg.name);
+
+/** The host's name for an aggregate of `chapter` (this editor's first chapter when none is named). */
+export const hostName = (name: string, chapter?: string): string => `${chapter ?? SCHEMA.domain}::${name}`;
+
+/**
+ * The aggregate a path names, and the segments after it. With several chapters the path is
+ * `<Chapter>/<Aggregate>/...`, and with one it is `<Aggregate>/...`.
+ */
+export function locate(segments: string[]): { agg: Aggregate | undefined; rest: string[] } {
+  if (SCHEMA.chapters) {
+    const [chapter, name, ...rest] = segments;
+    return { agg: SCHEMA.aggregates.find((candidate) => candidate.chapter === chapter && candidate.name === name), rest };
+  }
+  const [name, ...rest] = segments;
+  return { agg: SCHEMA.aggregates.find((candidate) => candidate.name === name), rest };
+}
+
+/** Whether a person in `role` may edit `agg`: every role may, unless its chapter limits them. */
+export const mayEdit = (agg: Aggregate, role: string | null): boolean => !agg.roles || (role !== null && agg.roles.includes(role));

data/lib/hecks/projections/site/cms_editor/templates/src/schema.ts.tmpl

@@ -7,6 +7,44 @@ __BANNER__
 /** How an attribute's value is entered: `object` is a value object, the rest are single values. */
 export type Kind = "text" | "integer" | "number" | "boolean" | "object" | "reference";
 
+/**
+ * What an attribute names: an instance of another aggregate, offered as a choice. `strict` pickers
+ * accept only a key that exists; the others suggest and accept any text. `listing` is the query of
+ * the target that lists what is on offer, or none to offer every instance. With `kinds`, the value is
+ * `<kind>:<key>`: the kind is chosen first, then the record of the aggregate that kind names.
+ */
+export interface Picker {
+  target?: string;
+  /** The target's chapter, when the editor spans several or the target is in another. */
+  chapter?: string;
+  /** The target's identity attribute. */
+  key?: string;
+  /** The attribute that names an instance to a person (its title, name or label, else its identity). */
+  label?: string;
+  listing?: string;
+  strict?: boolean;
+  kinds?: PickerKind[];
+}
+
+/** One kind of a `<kind>:<key>` value, and the aggregate it names when it names one. */
+export type PickerKind = Omit<Picker, "kinds"> & { kind: string };
+
+/**
+ * A list of mixed blocks: a list of one value object whose `discriminator` part is one of `kinds`. With
+ * `rules`, each kind's `requires` (parts it must have) and `uses` (parts it may have) come from a
+ * declared table; a part no row names belongs to every kind. With none, every part is shown and
+ * `mentions` says which parts a kind's rules read. `limits` are the most each list part of the block
+ * may hold; `pictures` says, for a value object, which of its parts are a picture's key, alt text and caption.
+ */
+export interface BlockList {
+  discriminator: string;
+  kinds: string[];
+  rules?: Record<string, { requires: string[]; uses: string[] }>;
+  mentions?: Record<string, string[]>;
+  limits?: Record<string, number>;
+  pictures?: Record<string, { key: string; alt: string; caption?: string }>;
+}
+
 export interface Attr {
   name: string;
   /** The type as the bluebook spells it ("String", "Byline"). */
@@ -15,10 +53,29 @@ export interface Attr {
   optional: boolean;
   /** True for `list_of`: the attribute holds a list of `type`. */
   list: boolean;
-  /** `body` for an attribute whose value object has the shape of a structured document (blocks of spans). */
-  widget?: "body";
+  /**
+   * `body` for an attribute whose value object has the shape of a structured document (blocks of
+   * spans); `date` or `datetime` for whole seconds since 1970 that the names say are a moment.
+   */
+  widget?: "body" | "date" | "datetime";
+  /** Set when the attribute names an instance of another aggregate of the editor. */
+  picker?: Picker;
+  /** The members of the closed set the attribute is one of, when its value object declares one. */
+  options?: string[];
   /** The aggregate a `reference` points at. */
   target?: string;
+  /** Set when the attribute is a list of mixed blocks (see `BlockList`). */
+  blockList?: BlockList;
+  /** The most rows the list may hold, when a rule of its holder (an invariant or a command's `given`) says. */
+  max?: number;
+  /** The fewest rows the list may hold, when a rule of its holder says. */
+  min?: number;
+  /** The most characters a text may hold, when a rule of its holder says. */
+  maxLength?: number;
+  /** True when `maxLength` is long enough for the text to be written in a box of several lines. */
+  multiline?: boolean;
+  /** Set when the value object is a picture: the names of its parts that hold the file, its description and its caption. */
+  picture?: { key: string; alt: string; caption?: string };
 }
 
 export interface Transition {
@@ -31,6 +88,8 @@ export interface Lifecycle {
   field: string;
   default: string;
   transitions: Transition[];
+  /** Each state's badge tone: `neutral`, `ok`, `info`, `warn` or `danger`. */
+  tones: Record<string, string>;
 }
 
 export interface Command {
@@ -41,7 +100,11 @@ export interface Command {
   creates: boolean;
   /** The aggregate the command acts on, when it is not a creating command. */
   on: string | null;
+  /** True when the editor asks for confirmation before running it (see the generator's `Destructive`). */
+  destructive: boolean;
   attributes: Attr[];
+  /** The arguments that only clear a field and are not offered as inputs: sent as empty lists. */
+  empty?: string[];
 }
 
 export interface Query {
@@ -50,8 +113,37 @@ export interface Query {
   attributes: Attr[];
 }
 
+/**
+ * A record of another aggregate that goes with this one's records, because its identity is a
+ * `<kind>:<slug>` key of this aggregate. `shape` says how to show it; `create` and `edit` name the
+ * commands that make and change it, when it has them.
+ */
+export interface Related {
+  aggregate: string;
+  chapter?: string;
+  /** The related aggregate's identity attribute, which the key fills. */
+  field: string;
+  shape: "document" | "gallery" | "metadata";
+  create?: string;
+  edit?: string;
+}
+
+/** An aggregate that keeps a draft of its content beside the live one, and the commands that handle it. */
+export interface Drafts {
+  /** The draft attribute (`draft_body`, `draft_content`) and the live one it stands for (`body`, `content`). */
+  attribute: string;
+  live: string;
+  save: string;
+  publish?: string;
+  discard?: string;
+}
+
 export interface Aggregate {
   name: string;
+  /** The chapter that declares the aggregate; set when the editor spans several. */
+  chapter?: string;
+  /** The roles that may edit it, when its chapter limits them; any admitted role otherwise. */
+  roles?: string[];
   description: string | null;
   identity: string;
   lifecycle: Lifecycle | null;
@@ -59,6 +151,10 @@ export interface Aggregate {
   valueObjects: Record<string, Attr[]>;
   commands: Command[];
   queries: Query[];
+  /** The aggregates keyed by this one's records, shown as panels on a record's page. */
+  related?: Related[];
+  /** The draft the aggregate keeps beside its live content, when it keeps one. */
+  drafts?: Drafts;
 }
 
 /** How one part of a picture's record is sent: `wrap` is the part of a value object that holds the value. */
@@ -74,12 +170,45 @@ export interface Media {
   fields: { key: MediaField; alt: MediaField; mime: MediaField; width?: MediaField; height?: MediaField };
   /** The query that lists the pictures, or null when every instance is read. */
   listing: string | null;
+  /** The chapter that holds the picture aggregate, when it is not this editor's own chapter. */
+  domain?: string;
+  /** That aggregate, which is then not among the editor's own; see `domain`. */
+  definition?: Aggregate;
+}
+
+/**
+ * The aggregate whose records are actions to run later, found by shape: the attribute that names the
+ * record an action is for, the closed set of actions, the due time, and the commands. The editor only
+ * makes and changes these records; something else runs them.
+ */
+export interface Scheduling {
+  aggregate: string;
+  chapter?: string;
+  subject: string;
+  action: string;
+  actions: string[];
+  due: string;
+  /** The first state of a record: an action not yet run. */
+  pending: string;
+  schedule: string;
+  reschedule?: string;
+  cancel?: string;
+  /** The query that lists the actions of one subject, when there is one. */
+  query?: string;
+  /** The optional text a record may carry to say why it ended as it did. */
+  reason?: string;
+  /** True when the editor makes the record's identity, since it is not the subject. */
+  generated?: boolean;
 }
 
 export interface Schema {
+  /** The first chapter, which names the domain the host is asked for. */
   domain: string;
+  /** Every chapter, in the order the navigation groups them; set when the editor spans several. */
+  chapters?: string[];
   aggregates: Aggregate[];
   media?: Media;
+  scheduling?: Scheduling;
 }
 
 export const SCHEMA: Schema = __SCHEMA__;

data/lib/hecks/projections/site/cms_editor/templates/src/ui/availability.ts.tmpl

@@ -0,0 +1,15 @@
+__BANNER__
+
+// Which commands apply to a record now, and which of them need a page of their own.
+import type { Aggregate, Command } from "../schema.ts";
+
+type State = Record<string, unknown>;
+
+/** Whether a command applies to an instance in its present state: a lifecycle move only from its states. */
+export function available(agg: Aggregate, command: Command, state: State): boolean {
+  const move = agg.lifecycle?.transitions.find((transition) => transition.verb === command.name);
+  return !move || !agg.lifecycle || move.from.includes(String(state[agg.lifecycle.field]));
+}
+
+/** What a command needs asked first: it takes input, or it is destructive. */
+export const needsPage = (command: Command): boolean => command.attributes.length > 0 || command.destructive;