hecks 3.9.0 → 3.10.0

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

@@ -0,0 +1,27 @@
+__BANNER__
+
+// A value shown read-only, whatever its shape: a scalar as text, a list as a list, a value object
+// as its named parts. A rich-text body is not shown this way; pages.ts renders it with bodyToHtml.
+import { esc } from "./html.ts";
+
+const blank = (value: unknown): boolean => value === null || value === undefined || value === "";
+
+/** `value` as a nested read-only outline. */
+export function outline(value: unknown): string {
+  if (blank(value)) return `<em>empty</em>`;
+  if (Array.isArray(value)) return value.length === 0 ? `<em>none</em>` : `<ul>${value.map((item) => `<li>${outline(item)}</li>`).join("")}</ul>`;
+  if (typeof value !== "object") return esc(value);
+  const entries = Object.entries(value as Record<string, unknown>);
+  if (entries.length === 1 && entries[0][0] === "value") return outline(entries[0][1]);
+  const rows = entries.map(([key, part]) => `<div><strong>${esc(key)}</strong>: ${outline(part)}</div>`);
+  return `<div class="outline">${rows.join("")}</div>`;
+}
+
+/** A one-line summary of a value, for a table cell: single-part objects show the part, lists their size. */
+export function summary(value: unknown): string {
+  if (blank(value)) return "";
+  if (Array.isArray(value)) return `${value.length} ${value.length === 1 ? "item" : "items"}`;
+  if (typeof value !== "object") return esc(value);
+  const parts = Object.values(value as Record<string, unknown>).filter((part) => !blank(part) && !Array.isArray(part));
+  return esc(parts.join(", "));
+}

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

@@ -0,0 +1,123 @@
+__BANNER__
+
+// The pages: a nav of aggregates, a list per aggregate (from a query when it has one), a detail page
+// per instance, and a form per command generated from the command's attributes. Lifecycle state is a
+// badge, and a lifecycle move is offered only from the states it applies in.
+import type { Aggregate, Attr, Command, Query } from "../schema.ts";
+import { bodyToHtml } from "./body_model.js";
+import { fields } from "./fields.ts";
+import { badge, esc, href, page, refusal } from "./html.ts";
+import { outline, summary } from "./outline.ts";
+import { SCHEMA } from "../schema.ts";
+
+type State = Record<string, unknown>;
+type Row = [string, State];
+
+/** What a submitted command left behind: the refusal to show, and the values to put back. */
+export interface Submitted {
+  command: string;
+  message: string | null;
+  values: State;
+}
+
+const label = (name: string): string => name.replace(/_/g, " ");
+
+/** The home page: every aggregate the domain declares. */
+export function home(): string {
+  const items = SCHEMA.aggregates.map(
+    (agg) => `<li><a href="${esc(href(agg.name))}">${esc(agg.name)}</a>${agg.description ? ` <span class="note">${esc(agg.description)}</span>` : ""}</li>`,
+  );
+  return page("Home", `<h1>${esc(SCHEMA.domain)}</h1>\n<ul>\n${items.join("\n")}\n</ul>`);
+}
+
+/** The page for a path that names nothing. */
+export function notFound(what: string): string {
+  return page("Not found", `<h1>Not found</h1>\n<p>${esc(what)}</p>`);
+}
+
+/** A form for one command; `to` adds the id input a command acting on another aggregate needs. */
+export function commandForm(agg: Aggregate, command: Command, action: string, shown: Submitted | null, state: State = {}, to = false): string {
+  const own = shown && shown.command === command.name ? shown : null;
+  const note = command.goal ? `<p class="note">${esc(command.goal)}</p>` : "";
+  const target = to ? `<label>${esc(command.on ?? "")} id<input type="text" name="__to" value="${esc(own?.values.__to ?? "")}"></label>` : "";
+  return `<form method="post" action="${esc(action)}">
+${refusal(own?.message ?? null)}${note}
+${target}
+${fields(agg, command.attributes, own ? own.values : state)}
+<button type="submit">${esc(label(command.name))}</button>
+</form>`;
+}
+
+/** The page of one creating command (or a command that acts on another aggregate's instance). */
+export function commandPage(agg: Aggregate, command: Command, action: string, shown: Submitted | null): string {
+  return page(command.name, `<h1>${esc(label(command.name))} <small>${esc(agg.name)}</small></h1>\n${commandForm(agg, command, action, shown, {}, command.on !== null && command.on !== agg.name)}`);
+}
+
+const columns = (agg: Aggregate) => agg.attributes.filter((attr) => !attr.list && attr.widget !== "body").slice(0, 4);
+
+function table(agg: Aggregate, rows: Row[]): string {
+  const cols = columns(agg);
+  const head = ["id", ...cols.map((attr) => label(attr.name)), ...(agg.lifecycle ? ["status"] : [])];
+  const lines = rows.map(([id, state]) => {
+    const cells = cols.map((attr) => `<td>${summary(state[attr.name])}</td>`);
+    const status = agg.lifecycle ? `<td>${badge(state[agg.lifecycle.field])}</td>` : "";
+    return `<tr><td><a href="${esc(href(agg.name, "id", id))}">${esc(id)}</a></td>${cells.join("")}${status}</tr>`;
+  });
+  const empty = rows.length === 0 ? `<tr><td colspan="${head.length}"><em>nothing here yet</em></td></tr>` : lines.join("\n");
+  return `<table>\n<tr>${head.map((name) => `<th>${esc(name)}</th>`).join("")}</tr>\n${empty}\n</table>`;
+}
+
+function queryLinks(agg: Aggregate, current: Query | null): string {
+  const links = agg.queries.map((query) => `<a href="${esc(`${href(agg.name)}?query=${encodeURIComponent(query.name)}`)}">${esc(label(query.name))}</a>`);
+  const all = `<a href="${esc(href(agg.name))}">all</a>`;
+  return `<p>${[all, ...links].join(" | ")}${current ? ` <span class="note">showing ${esc(current.name)}</span>` : ""}</p>`;
+}
+
+function queryForm(agg: Aggregate, query: Query | null): string {
+  if (!query || query.attributes.length === 0) return "";
+  const action = esc(href(agg.name));
+  return `<form method="get" action="${action}"><input type="hidden" name="query" value="${esc(query.name)}">
+${fields(agg, query.attributes)}
+<button type="submit">Ask</button></form>`;
+}
+
+/** An aggregate's list: the rows of the query asked, or of everything it holds. */
+export function listPage(agg: Aggregate, rows: Row[], query: Query | null, error: string | null): string {
+  const creating = agg.commands.filter((command) => command.creates);
+  const actions = creating.map((command) => `<a href="${esc(href(agg.name, "new", command.name))}">${esc(label(command.name))}</a>`).join(" | ");
+  const elsewhere = agg.commands.filter((command) => !command.creates && command.on !== agg.name);
+  const others = elsewhere.map((command) => `<a href="${esc(href(agg.name, "run", command.name))}">${esc(label(command.name))}</a>`).join(" | ");
+  const body = `<h1>${esc(agg.name)}</h1>\n${agg.description ? `<p class="note">${esc(agg.description)}</p>` : ""}
+${actions ? `<p>New: ${actions}</p>` : ""}${others ? `<p>Other: ${others}</p>` : ""}
+${queryLinks(agg, query)}${queryForm(agg, query)}${refusal(error)}
+${table(agg, rows)}`;
+  return page(agg.name, body);
+}
+
+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]));
+}
+
+/** An attribute's value read-only: a rich-text body as escaped HTML, anything else as an outline. */
+function shown(attr: Attr, value: unknown): string {
+  if (attr.widget !== "body") return outline(value);
+  return value && typeof value === "object" ? `<div class="body">${bodyToHtml(value)}</div>` : `<em>empty</em>`;
+}
+
+function state(agg: Aggregate, values: State): string {
+  const rows = agg.attributes.map((attr) => `<tr><th>${esc(label(attr.name))}</th><td>${shown(attr, values[attr.name])}</td></tr>`);
+  return `<table>\n${rows.join("\n")}\n</table>`;
+}
+
+/** One instance: its status, its values read-only, and a form for each command that applies to it. */
+export function detailPage(agg: Aggregate, id: string, values: State, shown: Submitted | null): string {
+  const acting = agg.commands.filter((command) => command.on === agg.name && available(agg, command, values));
+  const forms = acting.map((command) => {
+    const open = command.attributes.length > 0 ? ` ${shown && shown.command === command.name ? "open" : ""}` : "";
+    const body = commandForm(agg, command, href(agg.name, "id", id, command.name), shown, values);
+    return command.attributes.length > 0 ? `<details${open}><summary>${esc(label(command.name))}</summary>\n${body}\n</details>` : body;
+  });
+  const status = agg.lifecycle ? badge(values[agg.lifecycle.field]) : "";
+  return page(id, `<h1>${esc(id)} ${status}</h1>\n<p><a href="${esc(href(agg.name))}">${esc(agg.name)}</a></p>\n${state(agg, values)}\n<h2>Change</h2>\n${forms.join("\n")}`);
+}

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

@@ -0,0 +1,16 @@
+{
+  "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"]
+}

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

@@ -0,0 +1,107 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../../projector"
+require_relative "cms_editor/setting"
+require_relative "cms_editor/schema"
+require_relative "cms_editor/pretty"
+
+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/host.ts src/commands.ts src/app.ts src/server.ts
+          src/auth/membership.ts src/auth/session.ts src/auth/sso.ts
+          src/ui/html.ts src/ui/outline.ts src/ui/fields.ts src/ui/input.ts src/ui/pages.ts
+          src/ui/body_model.js src/ui/body_parse.js src/ui/body_widget.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 widget opens.
+        MEDIA_FILES = %w[
+          src/media/sniff.ts src/media/multipart.ts src/media/storage.ts src/media/handler.ts src/ui/media_picker.js
+        ].freeze
+
+        # The browser modules the rich-text widget loads, served to a signed-in editor.
+        ASSETS = %w[body_widget.js body_model.js body_parse.js].freeze
+
+        # What `app.ts` holds for a picture upload; each is left out when the chapter has none.
+        MEDIA_LINES = {
+          "__MEDIA_IMPORT__" => ["import { mediaHandler } 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);",
+          "__MEDIA_ROUTE__"  => "    if (segments[0] === \"media\") return media(client, request, segments.slice(1));"
+        }.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_chapter` the chapter to edit; `: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
+
+          schema = Schema.read(options.fetch(:domain_chapter), skip: setting.skip)
+          media = schema.key?("media")
+          tokens = setting.tokens.merge("__SCHEMA__" => Pretty.generate(schema), **media_tokens(media))
+          [*FILES, *(MEDIA_FILES if media)].to_h { |path| [path, fill(File.read(File.join(TEMPLATES, "#{path}.tmpl")), tokens)] }
+        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)
+          assets = RoutesTs.literal(media ? [*ASSETS, "media_picker.js"] : ASSETS)
+          lines = media ? MEDIA_LINES : MEDIA_LINES.transform_values { "" }
+          { "__ASSETS__" => assets, **lines }
+        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,72 @@
+# frozen_string_literal: true
+
+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/site/bluebook/site.bluebook

@@ -101,6 +101,7 @@ Hecks.bluebook "Site" do
     attribute :template,  Location,  optional: true
     attribute :cms,       Location,  optional: true
     attribute :root,      Location,  optional: true
+    attribute :editor,    Location,  optional: true
     attribute :extension, Extension, optional: true
     attribute :check,     Switch,    optional: true
     attribute :live,      Location,  optional: true
@@ -170,7 +171,7 @@ Hecks.bluebook "Site" do
       transition "Fault"    => "faulted",   from: "requested"
     end
 
-    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [extension=ts|mts] [--check]`.
+    # `hecks site site_projection.project_site <project> [out=<dir>] [template=<file>] [cms=<dir>] [root=<dir>] [editor=<dir>] [extension=ts|mts] [--check]`.
     # With `check` nothing is written: a routes.ts that differs from the table is faulted, naming the
     # file, so a CI job fails on drift.
     command "ProjectSite" do
@@ -182,6 +183,7 @@ Hecks.bluebook "Site" do
       attribute :template,  Location,  optional: true
       attribute :cms,       Location,  optional: true
       attribute :root,      Location,  optional: true
+      attribute :editor,    Location,  optional: true
       attribute :extension, Extension, optional: true
       attribute :check,     Switch,    optional: true
 
@@ -191,6 +193,7 @@ Hecks.bluebook "Site" do
       sets :template
       sets :cms
       sets :root
+      sets :editor
       sets :extension
       sets :check
 
@@ -250,6 +253,25 @@ Hecks.bluebook "Site" do
       emits "SiteProbeRequested"
     end
 
+    # `hecks site site_projection.check_roles <project> url=<http://127.0.0.1:port>`. Dispatches every
+    # command the project declares a `role` for to a running host with no role and no actor, and
+    # checks the host refuses each as `Unauthorized`. Only a host on this machine is asked, and it
+    # must be running with `HECKS_ROLE_ENFORCEMENT=enforce`: a host that is not would run the
+    # commands. It prints a line per command and exits 1 when any is not refused for its role.
+    command "CheckRoles" do
+      goal "Check a host on this machine refuses every role-declaring command from a caller with no role"
+
+      attribute :domain, DomainPath
+      attribute :run,    RunKey
+      attribute :url,    SiteUrl
+
+      sets :domain
+      sets :run
+      sets :url
+
+      emits "RolesCheckRequested"
+    end
+
     command "Complete" do
       goal "Record that routes.ts was written, or found current, or the live edge matched, and what it said"
 
@@ -301,6 +323,11 @@ Hecks.bluebook "Site" do
     trigger SiteProjection::SiteToolchain::Probe, with: { run: :run }
   end
 
+  policy "RolesWhenRequested" do
+    on      "SiteProjection.RolesCheckRequested"
+    trigger SiteProjection::SiteToolchain::Roles, with: { run: :run }
+  end
+
   policy "RecordTheProjection" do
     on      "SiteProjection.SiteAnswered"
     trigger SiteProjection::Complete, with: { output: :output }

data/lib/hecks/site/bluebook/site.ports.hecksagon

@@ -23,5 +23,11 @@ Hecks.hecksagon "Site" do
       answers "SiteAnswered"
       refuses "SiteRefused"
     end
+
+    asks "Roles", to: SiteProjection do
+      attribute :run, RunKey
+      answers "SiteAnswered"
+      refuses "SiteRefused"
+    end
   end
 end

data/lib/hecks/tools/site_routes/cli.rb

@@ -13,7 +13,7 @@ module Hecks
         # The flags that take a value, by the keyword of `projection` each one sets.
         VALUE_FLAGS = {
           out: "--out=DIR", template: "--template=FILE", cms: "--cms=DIR", root_dir: "--root=DIR",
-          extension: "--extension=EXT"
+          editor: "--editor=DIR", extension: "--extension=EXT"
         }.freeze
 
         # @param argv [Array<String>] the command line, consumed down to the project directory

data/lib/hecks/tools/site_routes/editor_files.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+require_relative "../../tools"
+
+module Hecks
+  module Tools
+    module SiteRoutes
+      # The editor's files, written under the `--editor` directory when the project declares an
+      # `Editor` row.
+      module EditorFiles
+        # @param editor [String] the directory the files are written under
+        # @param project [String] the project directory; the row's `domain` is relative to it
+        # @param site [Site] the project's route-table chapter, checked table and registry
+        # @return [Hash{String => String}] each file's absolute path to its text
+        # @raise [SystemExit] when `--editor` is named and the project declares no `Editor` row, or
+        #   the row names a domain or chapter that is not there
+        def editor_files(editor, project, site)
+          setting = Projections::Site::CmsEditor::Setting.read(site.chapter, table: site.table)
+          abort "project_site: --editor names #{editor}, but the project declares no Editor row" if setting.nil?
+
+          options = { domain_chapter: domain_chapter(project, setting), table: site.table }
+          files = Projector.call(:site_cms_editor, bluebook: site.chapter, options: options)
+          files.to_h { |name, text| [File.join(File.expand_path(editor), name), text] }
+        rescue ArgumentError, Projections::Site::Table::Invalid => e
+          abort "project_site: #{e.message}"
+        end
+
+        # @return [Bluebook::Chapter] the chapter the `Editor` row names, from its domain directory
+        def domain_chapter(project, setting)
+          domain_root = File.join(project, setting.domain)
+          chapter = registry_for(domain_root).bluebooks.values.find { |candidate| candidate.name == setting.chapter }
+          abort "project_site: #{domain_root} declares no chapter #{setting.chapter}" unless chapter
+          chapter
+        end
+      end
+    end
+  end
+end

data/lib/hecks/tools/site_routes.rb

@@ -13,9 +13,11 @@ require_relative "../projections/site/admin_cms"
 require_relative "../projections/site/site_root"
 require_relative "../projections/site/site_host"
 require_relative "../projections/site/payload_driver"
+require_relative "../projections/site/cms_editor"
 require_relative "site_routes/cli"
 require_relative "site_routes/templates"
 require_relative "site_routes/root_files"
+require_relative "site_routes/editor_files"
 
 module Hecks
   module Tools
@@ -39,13 +41,14 @@ module Hecks
       EXTENSIONS = %w[ts mts].freeze
 
       USAGE = "usage: hecks site site_projection.project_site [<project>] [--out=<dir>] " \
-              "[--template=<file>] [--cms=<dir>] [--root=<dir>] [--extension=#{EXTENSIONS.join("|")}] [--check]".freeze
+              "[--template=<file>] [--cms=<dir>] [--root=<dir>] [--editor=<dir>] " \
+              "[--extension=#{EXTENSIONS.join("|")}] [--check]".freeze
 
       # The directory `ports/` and `adapters/` live under, loaded into every project's registry.
       LIB_HECKS = File.expand_path("..", __dir__)
 
       # The keywords `projection` takes, each nil until given.
-      Settings = Struct.new(:out, :template, :extension, :cms, :root_dir, keyword_init: true)
+      Settings = Struct.new(:out, :template, :extension, :cms, :root_dir, :editor, keyword_init: true)
 
       # A project's route-table chapter with its checked table and the registry it booted into.
       Site = Struct.new(:chapter, :table, :registry)
@@ -53,6 +56,7 @@ module Hecks
       extend Cli
       extend Templates
       extend RootFiles
+      extend EditorFiles
 
       module_function
 
@@ -85,6 +89,7 @@ module Hecks
       #   `extension:` `ts` (the default) or `mts`, the module's file extension
       #   `cms:` the directory for the content system's half of the admin sign-in
       #   `root_dir:` the directory for the project's root files
+      #   `editor:` the directory for the content editor
       # @return [Hash{String => String}] each file's absolute path to the text it should hold
       # @raise [SystemExit] when the project declares no route table, the table is refused, or a
       #   path or the extension is refused
@@ -106,7 +111,7 @@ module Hecks
         written = route_files(dir, site, settings.extension)
         admin = Projections::Site::Admin.read(site.chapter, table: site.table)
         written.merge!(admin_files(dir, site.chapter, admin, settings.extension))
-        written.merge!(optional_files(settings, site.chapter, admin))
+        written.merge!(optional_files(settings, site, admin, root))
         written.merge(template_files(root, settings.out, site, template: settings.template))
       end
 
@@ -116,11 +121,13 @@ module Hecks
         renamed(dir, files, extension)
       end
 
-      # The content system's files and the project's root files, each when its flag was given.
-      def optional_files(settings, chapter, admin)
+      # The content system's files, the project's root files and the editor, each when its flag was
+      # given.
+      def optional_files(settings, site, admin, project)
         files = {}
-        files.merge!(cms_files(settings.cms, chapter, admin)) if settings.cms
-        files.merge!(root_files(settings.root_dir, chapter)) if settings.root_dir
+        files.merge!(cms_files(settings.cms, site.chapter, admin)) if settings.cms
+        files.merge!(root_files(settings.root_dir, site.chapter)) if settings.root_dir
+        files.merge!(editor_files(settings.editor, project, site)) if settings.editor
         files
       end
 

data/lib/hecks/version.rb

@@ -1,5 +1,5 @@
 module Hecks
   # Read directly by the gemspec, so this file must never require the
   # rest of the gem (its dependencies aren't resolved yet at that point).
-  VERSION = "3.9.0".freeze
+  VERSION = "3.10.0".freeze
 end