hecks 3.9.1 → 3.11.0

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

@@ -0,0 +1,69 @@
+__BANNER__
+
+// A record's values shown read-only, by shape: a moment in the viewer's zone, a rich-text body as
+// typeset text, a key with a button that copies it, anything else as `outline` shows it. The detail
+// page lists them as a document, and a related record's panel lists the ones it holds.
+import type { Aggregate, Attr } from "../schema.ts";
+import { bodyToHtml } from "./body_model.js";
+import { kindOf, summaryOf } from "./block_list.js";
+import { copyable, esc } from "./html.ts";
+import { isMoment, momentValue } from "./moments.ts";
+import { outline } from "./outline.ts";
+import { label } from "./words.ts";
+
+/** A body shown on a page sits under the page's h1 and its section's h2, so its own headings start at h3. */
+const READ_ONLY_DEMOTE = 2;
+
+type State = Record<string, unknown>;
+
+/** A list of mixed blocks as a numbered list: each block's kind and the line that stands for it. */
+function blockLines(agg: Aggregate, attr: Attr, held: unknown): string {
+  const blocks = Array.isArray(held) ? (held as Record<string, unknown>[]) : [];
+  if (blocks.length === 0 || !attr.blockList) return `<span class="text-muted">None</span>`;
+  const parts = agg.valueObjects[attr.type] ?? [];
+  const lines = blocks.map((block) => {
+    const kind = kindOf(attr.blockList, block);
+    const text = String(summaryOf(attr.blockList, parts, block));
+    return `<li class="flex flex-wrap items-baseline gap-2"><span class="badge badge-soft badge-neutral font-semibold">${esc(label(kind))}</span><span class="min-w-0 break-words">${esc(text)}</span></li>`;
+  });
+  return `<ol class="grid list-decimal gap-1 pl-6">${lines.join("")}</ol>`;
+}
+
+const isBlank = (value: unknown): boolean => value === undefined || value === null || value === "" || (Array.isArray(value) && value.length === 0);
+
+/** A value object of several parts as its named parts, each shown by what it is (a body typeset, a picture by its description, a list as a run). */
+function parts(agg: Aggregate, type: string, held: unknown, depth: number): string {
+  const value = held && typeof held === "object" ? (held as State) : {};
+  const rows = (agg.valueObjects[type] ?? [])
+    .filter((part) => !isBlank(value[part.name]))
+    .map((part) => `<div class="grid gap-1 sm:grid-cols-[8rem_minmax(0,1fr)] sm:gap-3"><dt class="text-muted">${esc(label(part.name))}</dt><dd class="min-w-0 break-words">${valueOf(agg, part, value, depth + 1)}</dd></div>`);
+  return rows.length === 0 ? `<span class="text-muted">Not set</span>` : `<dl class="grid gap-2">${rows.join("")}</dl>`;
+}
+
+/** Whether the attribute's value object has several parts to show (a one-part value object is shown as its part). */
+const composite = (agg: Aggregate, attr: Attr): boolean => attr.kind === "object" && (agg.valueObjects[attr.type] ?? []).length > 1;
+
+/** One attribute's value as markup. */
+export function valueOf(agg: Aggregate, attr: Attr, values: State, depth = 0): string {
+  const held = values[attr.name];
+  if (isMoment(attr)) return momentValue(attr, held);
+  if (attr.widget === "body") return held && typeof held === "object" ? `<div class="prose">${bodyToHtml(held, READ_ONLY_DEMOTE)}</div>` : `<span class="text-muted">Not set</span>`;
+  if (attr.blockList && attr.list) return blockLines(agg, attr, held);
+  if (composite(agg, attr) && depth < 5) {
+    if (!attr.list) return parts(agg, attr.type, held, depth);
+    const items = Array.isArray(held) ? held : [];
+    return items.length === 0 ? `<span class="text-muted">None</span>` : `<ol class="grid list-decimal gap-3 pl-6">${items.map((item) => `<li class="pl-1">${parts(agg, attr.type, item, depth)}</li>`).join("")}</ol>`;
+  }
+  const copy = attr.name === agg.identity || attr.kind === "reference";
+  return copy && typeof held !== "object" && held !== undefined && held !== null && held !== "" ? copyable(String(held), label(attr.name).toLowerCase()) : outline(held);
+}
+
+/** `attrs` as a list of names and values, a wide value (a body, a list, a value object) on a line of its own. */
+export function valueRows(agg: Aggregate, attrs: Attr[], values: State): string {
+  const rows = attrs.map((attr) => {
+    const wide = attr.widget === "body" || attr.list || attr.kind === "object";
+    const layout = wide ? "grid gap-2 py-4" : "grid gap-1 py-4 sm:grid-cols-[11rem_minmax(0,1fr)] sm:gap-4";
+    return `<div class="${layout}"><dt class="font-medium text-muted">${esc(label(attr.name))}</dt><dd class="min-w-0 break-words">${valueOf(agg, attr, values)}</dd></div>`;
+  });
+  return `<dl class="divide-y divide-base-300">\n${rows.join("\n")}\n</dl>`;
+}

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

@@ -0,0 +1,97 @@
+__BANNER__
+
+// The words the editor shows people. The domain's names are CamelCase and singular; people read
+// sentence case, plural for a list, and the same verb through a whole flow: the button that says
+// "Publish" leaves a notice that says "Published." Nothing here asks the domain; it reads names.
+import type { Aggregate, Command } from "../schema.ts";
+
+/** The lower-case words of a CamelCase or snake_case name: "MediaItem" is "media item". */
+export const humanize = (name: string): string =>
+  name
+    .replace(/([a-z0-9])([A-Z])/g, "$1 $2")
+    .replace(/_/g, " ")
+    .toLowerCase();
+
+/** `text` with its first letter capitalised. */
+export const capital = (text: string): string => text.charAt(0).toUpperCase() + text.slice(1);
+
+/** A name as a sentence-case label: "SaveDraft" is "Save draft". */
+export const label = (name: string): string => capital(humanize(name));
+
+/** The plural of an English noun, for the common regular shapes. */
+export function pluralOf(noun: string): string {
+  if (/[^aeiou]y$/.test(noun)) return `${noun.slice(0, -1)}ies`;
+  if (/(s|x|z|ch|sh)$/.test(noun)) return `${noun}es`;
+  return `${noun}s`;
+}
+
+/** An aggregate as a list's name: "MediaItem" is "Media items". */
+export function plural(name: string): string {
+  const words = humanize(name).split(" ");
+  words[words.length - 1] = pluralOf(words[words.length - 1]);
+  return capital(words.join(" "));
+}
+
+/** The limits a list's holder gives it as a sentence ("At least 1 and at most 60."), or nothing when it gives none. */
+export function limitsNote(min?: number, max?: number): string {
+  if (min && max) return `At least ${min} and at most ${max}.`;
+  return min ? `At least ${min}.` : max ? `At most ${max}.` : "";
+}
+
+/** An aggregate as one thing, lower case: "MediaItem" is "media item". */
+export const singular = (name: string): string => humanize(name);
+
+const IRREGULAR: Record<string, string> = {
+  set: "set", put: "put", send: "sent", make: "made", undo: "undone", redo: "redone", show: "shown", withdraw: "withdrawn",
+  draw: "drawn", hide: "hidden", write: "written", take: "taken", give: "given", keep: "kept", read: "read", pay: "paid", sell: "sold",
+  begin: "begun", run: "run", get: "got", find: "found", build: "built", choose: "chosen", leave: "left", hold: "held", lose: "lost",
+  break: "broken", bring: "brought", cut: "cut", shut: "shut", split: "split", lay: "laid", say: "said", spend: "spent", lend: "lent",
+  bind: "bound", wind: "wound", know: "known", grow: "grown", throw: "thrown", see: "seen", do: "done", go: "gone", have: "had",
+};
+
+const DOUBLED = new Set([
+  "submit", "admit", "commit", "omit", "plan", "drop", "ship", "stop", "skip", "tag", "pin", "log", "map", "ban", "trim", "wrap",
+  "grab", "strip", "refer", "transfer", "permit", "equip", "occur", "defer", "prefer",
+]);
+
+const PREFIXES = ["re", "un", "over", "out", "pre", "mis"];
+
+/** The irregular participle of `verb`, or of the verb under a prefix ("reset" is "set" again), or undefined. */
+function irregular(verb: string): string | undefined {
+  if (Object.hasOwn(IRREGULAR, verb)) return IRREGULAR[verb];
+  const prefix = PREFIXES.find((one) => verb.startsWith(one) && Object.hasOwn(IRREGULAR, verb.slice(one.length)));
+  return prefix ? `${prefix}${IRREGULAR[verb.slice(prefix.length)]}` : undefined;
+}
+
+/** The past participle of a verb: "publish" is "published", "submit" is "submitted", "begin" is "begun", "cancel" is "canceled". */
+export function past(verb: string): string {
+  const odd = irregular(verb);
+  if (odd) return odd;
+  if (verb.endsWith("e")) return `${verb}d`;
+  if (/[^aeiou]y$/.test(verb)) return `${verb.slice(0, -1)}ied`;
+  return DOUBLED.has(verb) ? `${verb}${verb.slice(-1)}ed` : `${verb}ed`;
+}
+
+/** A word cut back to what its forms share: "schedule", "scheduled" and "scheduling" are all "schedul". */
+const stem = (word: string): string => word.replace(/(ing|ed|es|e|d|s)$/, "");
+
+/**
+ * What a command's button says. A command named by one word acts on a thing the page already
+ * names, except one that makes something new: "Draft" on the articles page is "Draft article".
+ */
+export function commandLabel(agg: Aggregate, command: Command): string {
+  const words = humanize(command.name).split(" ");
+  return capital(command.creates && words.length === 1 ? `${words[0]} ${singular(agg.name)}` : words.join(" "));
+}
+
+/**
+ * What the notice says when the command has run, in the same verb as its button: "Published draft."
+ * When the thing's name already starts with the verb ("Schedule" making a "scheduled action") the
+ * repeated word is dropped, so the notice reads "Scheduled action." and never "Scheduled scheduled action."
+ */
+export function done(agg: Aggregate, command: Command): string {
+  const [verb, ...rest] = commandLabel(agg, command).toLowerCase().split(" ");
+  const repeated = rest.length > 0 && stem(rest[0]) === stem(verb);
+  const object = repeated ? rest.slice(1) : rest;
+  return capital(`${[past(verb), ...object].join(" ")}.`);
+}

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

@@ -0,0 +1,35 @@
+__BANNER__
+
+// What a page of one record may read of the rest of the domain: the records that go with it, and the
+// actions scheduled for it. The server builds it from the one read of the host the page already makes
+// (app.ts), so a page with panels costs no more reads than a page without.
+import type { Aggregate, Related } from "../schema.ts";
+import { SCHEMA } from "../schema.ts";
+
+type State = Record<string, unknown>;
+
+export interface World {
+  /** The person's role, which decides which aggregates' records may be shown. */
+  role: string | null;
+  /** One record of an aggregate by its identity, or undefined when the host holds none. */
+  lookup(agg: Aggregate, id: string): State | undefined;
+  /** Every record of an aggregate, as `[id, state]` pairs. */
+  rows(agg: Aggregate): [string, State][];
+  /** The scheduled actions of the record being shown, when the host answered a query for them. */
+  actions?: [string, State][];
+}
+
+/** The aggregate a `related` entry names. */
+export const relatedAggregate = (rel: Related): Aggregate | undefined =>
+  SCHEMA.aggregates.find((candidate) => candidate.name === rel.aggregate && candidate.chapter === rel.chapter);
+
+/** The aggregate that registers pictures, when the editor has it among its own. */
+export function pictureAggregate(): Aggregate | undefined {
+  const media = SCHEMA.media;
+  if (!media) return undefined;
+  return SCHEMA.aggregates.find((agg) => agg.name === media.aggregate && (media.domain ? agg.chapter === media.domain : !agg.chapter || agg.chapter === SCHEMA.domain));
+}
+
+/** The aggregate whose records are the scheduled actions, when the editor has one. */
+export const schedulingAggregate = (): Aggregate | undefined =>
+  SCHEMA.scheduling && SCHEMA.aggregates.find((candidate) => candidate.name === SCHEMA.scheduling?.aggregate && candidate.chapter === SCHEMA.scheduling?.chapter);

data/lib/hecks/projections/site/cms_editor/templates/tsconfig.json.tmpl

@@ -0,0 +1,17 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "allowImportingTsExtensions": true,
+    "allowJs": true,
+    "erasableSyntaxOnly": true,
+    "verbatimModuleSyntax": true,
+    "skipLibCheck": true,
+    "types": ["node"]
+  },
+  "include": ["src"],
+  "exclude": ["src/browser"]
+}

data/lib/hecks/projections/site/cms_editor/theme.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+require_relative "palette"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # The editor's theme as stylesheet text: the light and dark colour properties of a
+        # `Palette`, as the lines that go inside the two daisyUI themes `src/browser/app.css`
+        # declares (`editor-light`, and `editor-dark` for a visitor whose system prefers dark).
+        module Theme
+          module_function
+
+          # @param accent [String, nil] the Editor row's accent, a six-digit hex colour, or nil
+          # @return [Hash{String => String}] the placeholders of `app.css.tmpl` and their text
+          def tokens(accent)
+            themes = Palette.new(accent).themes
+            { "__LIGHT__" => lines(themes[:light]), "__DARK__" => lines(themes[:dark]) }
+          end
+
+          # @param properties [Hash{String => String}] custom properties and their values
+          # @return [String] one declaration per line
+          def lines(properties) = properties.map { |name, value| "  #{name}: #{value};" }.join("\n")
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor/theme_checks.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require_relative "color"
+
+module Hecks
+  module Projections
+    module Site
+      module CmsEditor
+        # What the `Editor` row's look settings must satisfy: an accent that is a six-digit hex
+        # colour, a logo that is a relative path to a picture file the server can read from its
+        # own directory, and a brand that is one line of text.
+        module ThemeChecks
+          # The file types a logo may be.
+          LOGO_TYPES = %w[png jpg jpeg webp gif avif svg].freeze
+
+          # The longest brand the header has room for.
+          BRAND_LENGTH = 60
+
+          module_function
+
+          # @param row [Hash{Symbol => String}] the row, defaults filled
+          # @return [Array<String>] every problem with `brand`, `accent` and `logo`
+          def problems(row)
+            [*accent_problems(row[:accent].strip), *logo_problems(row[:logo].strip), *brand_problems(row[:brand].strip)]
+          end
+
+          # @return [Array<String>] the problem with an accent that is not blank or six hex digits
+          def accent_problems(accent)
+            return [] if accent.empty? || Color::HEX.match?(accent)
+
+            ["accent #{accent.inspect} must be a six-digit hex colour such as #1f7a6d"]
+          end
+
+          # @return [Array<String>] the problem with a logo that is not a safe relative picture path
+          def logo_problems(logo)
+            return [] if logo.empty? || safe_path?(logo)
+
+            ["logo #{logo.inspect} must be a relative path to a #{LOGO_TYPES.join(", ")} file, with no .. or hidden part"]
+          end
+
+          # @return [Array<String>] the problem with a brand that is long or has more than one line
+          def brand_problems(brand)
+            return [] if brand.length <= BRAND_LENGTH && !brand.match?(/[[:cntrl:]]/)
+
+            ["brand must be one line of at most #{BRAND_LENGTH} characters"]
+          end
+
+          # @return [Boolean] whether `path` is relative, has no hidden part, and is a picture
+          def safe_path?(path)
+            LOGO_TYPES.include?(File.extname(path).delete_prefix(".").downcase) && !path.start_with?("/") &&
+              path.split("/", -1).none? { |part| part.empty? || part.start_with?(".") } && !path.match?(/[\\[:cntrl:]]/)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/cms_editor.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../projector"
+require_relative "cms_editor/setting"
+require_relative "cms_editor/schema"
+require_relative "cms_editor/pretty"
+require_relative "cms_editor/icons"
+require_relative "cms_editor/theme"
+
+module Hecks
+  module Projections
+    module Site
+      # A small Node/TypeScript editor for a domain's content, as the files of a package: a server
+      # that signs editors in through the site's own hand-off and shows a page per aggregate, a list
+      # from its queries, a detail page per instance and a form per command.
+      #
+      # It is generic by aggregate. The pages and forms are not written per aggregate; they read
+      # `src/schema.ts`, which is the domain chapter's aggregates, attributes, value objects,
+      # lifecycles, commands and queries as one typed constant. The domain holds no editor data: the
+      # editor reads and dispatches through the host like any other client, and the output is a pure
+      # function of the chapter and the `Editor` row, so `--check` can hold it current.
+      module CmsEditor
+        extend Projector::Target
+
+        projects_as :site_cms_editor, emits: :files
+
+        # Where the template files are.
+        TEMPLATES = File.join(__dir__, "cms_editor", "templates")
+
+        # The files, by path relative to the directory they are written to.
+        FILES = %w[
+          package.json tsconfig.json src/config.ts src/schema.ts src/names.ts src/host.ts src/commands.ts src/choices.ts
+          src/app.ts src/server.ts src/assets.ts src/flash.ts src/auth/membership.ts src/auth/session.ts src/auth/sso.ts
+          src/ui/html.ts src/ui/words.ts src/ui/icons.ts src/ui/shell.ts src/ui/outline.ts src/ui/fields.ts
+          src/ui/input.ts src/ui/table.ts src/ui/paging.ts src/ui/pickers.ts src/ui/moments.ts src/ui/detail.ts
+          src/ui/pages.ts src/ui/theme.js src/ui/body_model.js src/ui/body_parse.js src/ui/availability.ts src/ui/dialogs.ts
+          src/ui/links.ts src/ui/preview.ts src/ui/related.ts src/ui/schedule.ts src/ui/values.ts src/ui/world.ts
+          src/browser/app.css src/browser/main.js src/browser/shell.js src/browser/forms.js src/browser/toast.js
+          src/browser/lists.js src/browser/pickers.js src/browser/epoch.js src/browser/moments.js
+          src/browser/body_doc.js src/browser/body_editor.js src/browser/autosave.js src/browser/preview.js
+          src/ui/blocks.ts src/ui/block_list.js src/browser/blocks.js
+        ].freeze
+
+        # The files only an editor of a chapter with a picture aggregate has: the upload, the
+        # storage port with its local-disk adapter, and the picker the rich-text editor opens.
+        MEDIA_FILES = %w[
+          src/media/sniff.ts src/media/multipart.ts src/media/storage.ts src/media/handler.ts src/browser/media_picker.js
+        ].freeze
+
+        # What `app.ts` and the body editor hold for a picture upload; each is left out when the
+        # chapter has none.
+        MEDIA_LINES = {
+          "__MEDIA_IMPORT__"  => ["import { mediaHandler, mediaOpen } from \"./media/handler.ts\";",
+                                  "import type { MediaStorage } from \"./media/storage.ts\";"].join("\n"),
+          "__MEDIA_OPTION__"  => ["  /** Where picture bytes are kept: the local disk unless given (see media/storage.ts). */",
+                                  "  storage?: MediaStorage;"].join("\n"),
+          "__MEDIA_SETUP__"   => "  const media = mediaHandler(options.storage, { url: options.url, fetch: options.fetch });",
+          "__MEDIA_ROUTE__"   => ["    if (segments[0] === \"media\") {",
+                                  "      if (!mediaOpen(role)) return plain(\"Pictures are not open to your role.\", 403);",
+                                  "      return media(client, request, segments.slice(1));", "    }"].join("\n"),
+          "__PICKER_LOADER__" => "() => import(\"./media_picker.js\")"
+        }.freeze
+
+        module_function
+
+        # Renders the editor's files for a project that declares an `Editor` row.
+        #
+        # @param bluebook [Bluebook::Chapter] the chapter that declares the route table and the row
+        # @param options [Hash{Symbol => Object}] `:domain_chapters` the chapters to edit, in the
+        #   order the row names them (`:domain_chapter` for one);
+        #   `:media_chapter` the chapter the row's `media` names, whose picture aggregate the
+        #   pictures use; `:table` the checked route table, when the login page is to be checked
+        #   against it
+        # @return [Hash{String => String}] each file's path relative to the editor's directory to
+        #   its text; empty when the project declares no `Editor` row
+        # @raise [Table::Invalid] when the row is refused
+        # @raise [ArgumentError] when the chapter has no aggregate to edit
+        def call(bluebook:, options: {})
+          setting = Setting.read(bluebook, table: options[:table])
+          return {} unless setting
+
+          chapters = options[:domain_chapters] || options.fetch(:domain_chapter)
+          schema = Schema.read(chapters, skip: setting.skip, pictures: options[:media_chapter], roles: setting.chapter_roles)
+          media = schema.key?("media")
+          tokens = tokens(setting, schema, media)
+          [*FILES, *(MEDIA_FILES if media)].to_h { |path| [path, fill(File.read(File.join(TEMPLATES, "#{path}.tmpl")), tokens)] }
+        end
+
+        # @return [Hash{String => String}] each placeholder of the templates and its text
+        def tokens(setting, schema, media)
+          setting.tokens.merge(look_tokens(setting, schema), "__SCHEMA__" => Pretty.generate(schema), **media_tokens(media))
+        end
+
+        # @param media [Boolean] whether the chapter has a picture aggregate
+        # @return [Hash{String => String}] each media placeholder to its text, empty when none
+        def media_tokens(media)
+          return MEDIA_LINES if media
+
+          MEDIA_LINES.transform_values { "" }.merge("__PICKER_LOADER__" => "null")
+        end
+
+        # @param setting [Setting] the checked row
+        # @param schema [Hash{String => Object}] the chapter as the editor reads it
+        # @return [Hash{String => String}] the brand, the icon sprite and the theme's colours
+        def look_tokens(setting, schema)
+          { "__BRAND__" => JSON.generate(setting.brand || schema["domain"]), "__ICONS__" => Icons.sprite,
+            "__CSS_BANNER__" => "/* #{RoutesTs::BANNER.delete_prefix("// ")} */", **Theme.tokens(setting.accent) }
+        end
+
+        # @param text [String] a template with `__NAME__` placeholders
+        # @param tokens [Hash{String => String}] each placeholder to its text
+        # @return [String] `text` with each placeholder replaced in one pass, so a value that looks
+        #   like a placeholder is left as it is; a placeholder alone on its line whose text is empty
+        #   takes the line with it
+        def fill(text, tokens)
+          text.gsub(/^(__[A-Z_]+__)\n|__[A-Z_]+__/) do
+            line = Regexp.last_match(1)
+            token = line || Regexp.last_match(0)
+            replacement(tokens.fetch(token, token), alone: !line.nil?)
+          end
+        end
+
+        # @return [String] `value`, with its line's newline when it stood alone and is not empty
+        def replacement(value, alone:)
+          return value unless alone
+
+          value.empty? ? "" : "#{value}\n"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projections/site/role_probe.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative "../../bluebook/synthesizer"
+
+module Hecks
+  module Projections
+    module Site
+      # The commands of a project that declare a role, and the verdict on a host's answer to each
+      # sent with well-formed arguments but no role and no actor. It sends nothing: the caller
+      # dispatches each command and hands the answer back.
+      #
+      # The arguments are synthesized from the declaration, because a host checks that arguments are
+      # present and well-typed before it checks who is calling. A host that enforces roles refuses
+      # such a caller as `Unauthorized`. Any other answer (an accepted command, or a refusal for
+      # another reason) means the role did not stop it.
+      class RoleProbe
+        # One command that declares a role.
+        #
+        # @!attribute [r] verb
+        #   @return [String] the command as a host is asked to run it, `Chapter::Aggregate.Command`
+        # @!attribute [r] role
+        #   @return [String] the role the command declares
+        # @!attribute [r] arguments
+        #   @return [Hash] one synthesized value per declared attribute
+        Check = Struct.new(:verb, :role, :arguments, keyword_init: true)
+
+        # The refusal kind a host enforcing roles answers a caller of the wrong role with.
+        REFUSAL = "Unauthorized"
+
+        # The refusal kinds of an argument the host would not build, before it asks who is calling.
+        ARGUMENT_REFUSALS = %w[AbsentArgument TypeMismatch InvariantViolation].freeze
+
+        # @param registry [Runtime::Registry] the registry a project booted into
+        # @return [Array<Check>] every command that declares a role, in the order declared
+        def self.checks(registry)
+          registry.bluebooks.values.flat_map do |chapter|
+            chapter.aggregates.flat_map do |aggregate|
+              aggregate.commands.select(&:role).map { |command| check_for(chapter, aggregate, command) }
+            end
+          end
+        end
+
+        # @return [Check] the check for one command that declares a role
+        def self.check_for(chapter, aggregate, command)
+          Check.new(verb: "#{chapter.name}::#{aggregate.hecks_name}.#{command.hecks_name}", role: command.role,
+                    arguments: Bluebook::Synthesizer.args_for(chapter, aggregate, command))
+        end
+
+        # Whether the host refused the synthesized arguments themselves, so the role gate was never
+        # reached and the check proves nothing either way.
+        #
+        # @param answer [Hash] the host's parsed JSON answer
+        # @return [Boolean] true when every refusal is an argument refusal
+        def self.unchecked?(answer)
+          kinds = Array(answer["refusals"]).map { |refusal| refusal["kind"] }
+          kinds.any? && (kinds - ARGUMENT_REFUSALS).empty?
+        end
+
+        # Judges a host's answer to one check.
+        #
+        # @param check [Check] the command that was dispatched with no role and no actor
+        # @param answer [Hash] the host's parsed JSON answer
+        # @return [String, nil] why the answer is wrong, or nil when the host refused the caller
+        def self.verdict(check, answer)
+          refusals = Array(answer["refusals"])
+          return nil if refusals.any? { |refusal| refusal["kind"] == REFUSAL }
+          return "was refused, but not as #{REFUSAL}: #{refusals.map { |refusal| refusal["kind"] }.join(", ")}" if refusals.any?
+
+          "was not refused for its role (#{check.role}); is the host running with HECKS_ROLE_ENFORCEMENT=enforce?"
+        end
+      end
+    end
+  end
+end

data/lib/hecks/projector/cli_audience.rb

@@ -2,7 +2,8 @@ module Hecks
   module Projector
     # What a launcher's help leaves out and points at for whoever typed the line: the aggregates
     # only a maintainer of a hecks checkout runs, and the attached chapters worth a line each.
-    # `CliProjector` renders the help; the runner decides the audience (`Doors::LauncherOptions`).
+    # `CliProjector` renders the help; the runner decides the audience
+    # (`Adapters::Driving::LauncherOptions`).
     module CliAudience
       module_function
 

data/lib/hecks/projector/cli_projector/listing.rb

@@ -67,7 +67,7 @@ module Hecks
         end
 
         # " (also: mcp!)" for a spec the chapter gave a short name, else nothing. A short name that
-        # is only the command's own name (`init` for `door.init`) is already in the line.
+        # is only the command's own name (`init` for `launch.init`) is already in the line.
         def alias_note(spec)
           return "" if spec[:short_was].nil? || spec[:short_was].split(".").last == spec[:short]
 

data/lib/hecks/projector/cli_projector/option_specs.rb

@@ -29,7 +29,7 @@ module Hecks
         # One option per field of a value object, recursing into a field that is itself one.
         #
         # The list flag rides on each leaf: without it a repeated flag overwrote the
-        # leaf silently, and CliDoor only ever sees a path and a spec.
+        # leaf silently, and Cli only ever sees a path and a spec.
         def leaf_options(value_object, aggregate, path, optional)
           value_object.attributes.flat_map do |field|
             nested = value_object_for(field, value_object, aggregate)

data/lib/hecks/projector/docs_projector/closing.rb

@@ -18,7 +18,7 @@ module Hecks
           return [] if bluebook.policies.empty?
 
           rows = bluebook.policies.map do |policy|
-            ["`#{policy.on_event}`", "`#{policy.trigger_command}`", policy.target_domain || bluebook.name]
+            ["`#{policy.on_event}`", "`#{policy.reaches}`", policy.target_domain || bluebook.name]
           end
           [DocsProjector.h(depth, "Reactions"), "",
            "These fire on their own. Issuing the verb on the left also causes the one on the right.", "",

data/lib/hecks/projector/docs_projector.rb

@@ -110,7 +110,7 @@ module Hecks
         out.compact.join("\n")
       end
 
-      # An entity has no door of its own; its verbs go through the holding aggregate.
+      # An entity has no entry point of its own; its verbs go through the holding aggregate.
       def entity_addressing(aggregate, entity)
         "Addressed through its holder — `#{aggregate.hecks_name}.#{entity.hecks_name}.<Verb>`, " \
           "passing the #{aggregate.hecks_name}'s `id` and this element's " \