hecks 3.1.0 → 3.1.1

data/lib/hecks/projections/deploy/box/templates/verify-copy.sh.tmpl

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Compare two databases holding @@STACK@@'s schemas (structure and exact row counts of every table)
+# through a bastion that can reach both. Read-only on both. Used at the end of restore-to-rds.sh, for a
+# backup restore drill (production vs a database restored from its backup) and for checking a rollback copy.
+#
+#   verify-copy.sh <bastion-instance-id> <host-a> <secret-arn-a> <host-b> <secret-arn-b>
+#
+#   A_DB, B_DB   the database on each side (default @@DATABASE@@)
+#
+# Schemas compared: @@SCHEMAS@@
+# Exit 0 only if both are identical and no materialized view is unpopulated in either.
+set -euo pipefail
+
+BASTION=${1:?bastion instance id}; A_HOST=${2:?}; A_SECRET=${3:?}; B_HOST=${4:?}; B_SECRET=${5:?}
+SCHEMAS="@@SCHEMAS_CSV@@"
+A_DB=${A_DB:-@@DATABASE@@}; B_DB=${B_DB:-@@DATABASE@@}
+A_PORT=15434; B_PORT=15435
+
+pg_major() { "$1" --version 2>/dev/null | sed -E 's/.* ([0-9]+)[.].*/\1/'; }
+if [ "$(pg_major psql || echo 0)" -lt 16 ] && [ -x /opt/homebrew/opt/postgresql@16/bin/psql ]; then
+  export PATH=/opt/homebrew/opt/postgresql@16/bin:$PATH
+fi
+
+WORK=$(mktemp -d); PIDS=()
+cleanup() { for p in "${PIDS[@]:-}"; do [ -n "$p" ] && kill "$p" 2>/dev/null || true; done; rm -rf "$WORK"; }
+trap cleanup EXIT
+
+secret_field() { aws secretsmanager get-secret-value --secret-id "$1" --query SecretString --output text | jq -r "$2"; }
+A_PW=$(secret_field "$A_SECRET" .password); B_PW=$(secret_field "$B_SECRET" .password)
+A_USER=$(secret_field "$A_SECRET" '.username // "postgres"'); B_USER=$(secret_field "$B_SECRET" '.username // "postgres"')
+tunnel() {
+  aws ssm start-session --target "$BASTION" --document-name AWS-StartPortForwardingSessionToRemoteHost \
+    --parameters "{\"host\":[\"$1\"],\"portNumber\":[\"5432\"],\"localPortNumber\":[\"$2\"]}" >"$WORK/t_$2.log" 2>&1 &
+  PIDS+=($!); disown
+}
+tunnel "$A_HOST" $A_PORT; tunnel "$B_HOST" $B_PORT
+for i in $(seq 1 20); do
+  grep -q "Waiting for connections" "$WORK/t_$A_PORT.log" 2>/dev/null && grep -q "Waiting for connections" "$WORK/t_$B_PORT.log" 2>/dev/null && break
+  sleep 1
+done
+A() { PGPASSWORD=$A_PW psql -h localhost -p $A_PORT -U "$A_USER" -d "$A_DB" -Atc "$1"; }
+B() { PGPASSWORD=$B_PW psql -h localhost -p $B_PORT -U "$B_USER" -d "$B_DB" -Atc "$1"; }
+
+SHAPE="select n.nspname||' '||c.relkind::text, count(*) from pg_class c join pg_namespace n on n.oid=c.relnamespace where n.nspname = any(string_to_array('$SCHEMAS', ',')) group by 1
+ union all select 'policies', count(*) from pg_policies where schemaname = any(string_to_array('$SCHEMAS', ','))
+ union all select 'functions', count(*) from pg_proc p join pg_namespace n on n.oid=p.pronamespace where n.nspname = any(string_to_array('$SCHEMAS', ',')) order by 1"
+COUNTS="select table_schema||'.'||table_name, (xpath('/row/c/text()', query_to_xml(format('select count(*) as c from %I.%I', table_schema, table_name), false, true, '')))[1]::text from information_schema.tables where table_type='BASE TABLE' and table_schema = any(string_to_array('$SCHEMAS', ',')) order by 1"
+UNPOP="select count(*) from pg_matviews where schemaname = any(string_to_array('$SCHEMAS', ',')) and not ispopulated"
+
+BAD=0
+A "$SHAPE" >"$WORK/shape_a"; B "$SHAPE" >"$WORK/shape_b"
+A "$COUNTS" >"$WORK/counts_a"; B "$COUNTS" >"$WORK/counts_b"
+[ -s "$WORK/counts_a" ] || { echo "FAIL: first database has no tables to compare" >&2; BAD=1; }
+[ "$(A "$UNPOP")" = 0 ] && [ "$(B "$UNPOP")" = 0 ] || { echo "FAIL: unpopulated materialized views" >&2; BAD=1; }
+diff "$WORK/shape_a" "$WORK/shape_b" >/dev/null || { echo "FAIL: structure differs" >&2; diff "$WORK/shape_a" "$WORK/shape_b" >&2 || true; BAD=1; }
+diff "$WORK/counts_a" "$WORK/counts_b" >/dev/null || { echo "FAIL: row counts differ" >&2; diff "$WORK/counts_a" "$WORK/counts_b" >&2 || true; BAD=1; }
+[ "$BAD" = 0 ] || exit 1
+echo "OK: $(wc -l <"$WORK/counts_a" | tr -d ' ') tables, identical row counts and structure"

data/lib/hecks/projections/deploy/box.rb

@@ -20,10 +20,18 @@ module Hecks
         # the legacy `compute-1` form.
         LEGACY_COMPUTE_REGION = "us-east-1".freeze
 
+        # The end of every Caddyfile: sites a rehearsal mounts under `caddy-extra`, such as a
+        # loopback listener that adds the origin secret so a smoke test runs without the CDN. A
+        # glob that matches nothing is not an error, so production, which mounts none, is unchanged.
+        CADDY_EXTRA = "# Rehearsal-only sites are mounted here; nothing matches in production. Restart the proxy\n" \
+                      "# after adding one: the admin API is off, so a reload cannot reach it.\n" \
+                      "import /etc/caddy/extra/*\n".freeze
+
         module_function
 
         # Generates `rds.yaml`, `box.yaml`, `Caddyfile`, `services.json`, `render-compose.sh`,
-        # `fetch-secrets.sh`, `deploy-box.sh` and a `Makefile`.
+        # `fetch-secrets.sh`, `deploy-box.sh` and a `Makefile`, and for a world that declares a
+        # `migration`, `restore-to-rds.sh`, `verify-copy.sh` and `MIGRATION.md`.
         #
         # @param bluebook [Bluebook::Behaviour::Chapter] the domain's own booted chapter
         # @param options [Hash] generation options; same shape as `Fargate.call`'s
@@ -82,15 +90,95 @@ module Hecks
           {
             "rds.yaml" => rds_yaml(plan), "box.yaml" => box_yaml(plan, region),
             "Caddyfile" => caddyfile(plan), "services.json" => services_json(plan),
-            "render-compose.sh" => template("render-compose.sh.tmpl", "STACK" => plan.infra_name, "REGION" => region,
-                                                                      "DB_NAME" => plan.database_name,
-                                                                      "PROXY_IMAGE" => plan.proxy_image),
+            "render-compose.sh" => render_compose_sh(plan, region),
             "fetch-secrets.sh" => File.read(File.join(TEMPLATE_DIR, "fetch-secrets.sh")),
             "deploy-box.sh" => deploy_box_sh(plan, region),
             "Makefile" => makefile(plan)
+          }.merge(migration_files(plan))
+        end
+
+        # The tooling that moves a project's data from its old database into the RDS instance, for
+        # a world that declares a `migration`.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [Hash{String => String}] `restore-to-rds.sh`, `verify-copy.sh` and `MIGRATION.md`,
+        #   or nothing
+        def migration_files(plan)
+          migration = plan.migration
+          return {} unless migration
+
+          values = { "STACK" => plan.infra_name, "SCHEMAS" => migration.schemas.join(" "),
+                     "SCHEMAS_CSV" => migration.schemas.join(","), "DATABASE" => migration.database,
+                     "SOURCE_DATABASE" => migration.source_database }
+          {
+            "restore-to-rds.sh" => template("restore-to-rds.sh.tmpl", values),
+            "verify-copy.sh"    => template("verify-copy.sh.tmpl", values),
+            "MIGRATION.md"      => migration_md(plan)
           }
         end
 
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] the runbook for moving onto the box, in the order the steps are run
+        def migration_md(plan)
+          migration = plan.migration
+          deploy = plan.task_definition ? "make deploy TASKDEF=#{plan.task_definition}:<revision>" : "make deploy"
+          <<~MD
+            # Moving #{plan.infra_name} onto the box and RDS
+
+            Generated from the world's `migration` setting. Nothing here has been run for you.
+
+            Schemas to copy: #{migration.schemas.map { |name| "`#{name}`" }.join(', ')}, in database
+            `#{migration.source_database}` on the old server and `#{migration.database}` on RDS.
+
+            ## Before cutover
+
+            1. Create the stacks: `make stacks VPC=... PRIVATE_SUBNETS=... PUBLIC_SUBNET=...`. To rehearse first,
+               deploy `rds.yaml` and `box.yaml` under other stack names with `Rehearsal=true`: the database is then
+               deleted with its stack and the box gets no stable public address. Delete the rehearsal stacks after.
+            2. Copy the data. The bastion is any instance that can reach both databases.
+
+               ```
+               RDS_HOST=$(aws cloudformation describe-stacks --stack-name #{plan.rds_stack} --query "Stacks[0].Outputs[?OutputKey=='DbEndpoint'].OutputValue" --output text)
+               RDS_SECRET=$(aws cloudformation describe-stacks --stack-name #{plan.rds_stack} --query "Stacks[0].Outputs[?OutputKey=='DbSecretArn'].OutputValue" --output text)
+               bash restore-to-rds.sh <bastion-instance-id> <old-host> <old-secret-arn> "$RDS_HOST" "$RDS_SECRET"
+               ```
+
+               It copies each schema, refreshes the materialized views a plain `pg_restore` cannot, then runs
+               `verify-copy.sh`, which compares structure and the exact row count of every table and prints `OK`
+               only if both match. Re-run with `FORCE=1` to reload.
+            3. Deploy the app onto the box: `#{deploy}`. The deploy ends with health checks on the box.
+            4. Run the project's own smoke test against the box before any traffic moves.
+
+            ## Cutover
+
+            1. Stop writes on the old stack, then run `restore-to-rds.sh` again with `FORCE=1` for a final copy and
+               wait for `OK`.
+            2. Point the CDN's origin at the box stack's `AppOriginDomain` output.
+            3. Keep the old database untouched for several days, and take a final snapshot before deleting it.
+
+            ## Rollback
+
+            Until the first write lands on RDS, point the origin back. After that, writes taken by both databases
+            cannot be merged: choose one side and copy it over the other (swap the hosts and secrets, and set
+            `SRC_DB` and `DST_DB`, with `FORCE=1`). Do not change the domain's era in the same window, so a rollback
+            only has to move data.
+          MD
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @param region [String] the validated region
+        # @return [String] the script that renders the Compose file, from `services.json` or from
+        #   an ECS task definition when the world names one
+        def render_compose_sh(plan, region)
+          if plan.task_definition
+            template("render-compose-taskdef.sh.tmpl", "STACK" => plan.infra_name, "FAMILY" => plan.task_definition,
+                                                        "PROXY_IMAGE" => plan.proxy_image)
+          else
+            template("render-compose.sh.tmpl", "STACK" => plan.infra_name, "REGION" => region,
+                                               "DB_NAME" => plan.database_name, "PROXY_IMAGE" => plan.proxy_image)
+          end
+        end
+
         # @param plan [Settings::Plan] the resolved settings
         # @return [String] the database stack
         def rds_yaml(plan)
@@ -110,7 +198,39 @@ module Hecks
                    "COMPUTE_DOMAIN" => compute_domain(region),
                    "SECRET_RESOURCES" => secret_resources(plan), "TUNNEL_EGRESS" => tunnel_egress(plan),
                    "SWAP_COMMANDS" => swap_commands(plan), "ECR_REPOSITORIES" => ecr_repositories(plan),
-                   "ECR_OUTPUTS" => ecr_outputs(plan))
+                   "ECR_OUTPUTS" => ecr_outputs(plan), "S3_POLICY" => s3_policy(plan))
+        end
+
+        # The role's S3 policy: every declared bucket readable, and writable only on a production
+        # box, so a rehearsal never changes the real objects.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] a policy list item, indented into the role's `Policies`, or nothing
+        def s3_policy(plan)
+          return "" if plan.s3_buckets.empty?
+
+          arn = ->(path) { "arn:${AWS::Partition}:s3:::#{path}" }
+          reads = plan.s3_buckets.flat_map { |b| [arn.call(b.name), arn.call("#{b.name}/*")] }
+          writes = plan.s3_buckets.select(&:write).map { |b| arn.call("#{b.name}/*") }
+          rows = s3_read_rows(reads)
+          rows += s3_write_rows(writes) unless writes.empty?
+          "#{rows.map { |row| "        #{row}" }.join("\n")}\n"
+        end
+
+        # @param resources [Array<String>] the bucket and object ARNs a box may read
+        # @return [Array<String>] the policy's head and its read statement, relative to `Policies`
+        def s3_read_rows(resources)
+          ["- PolicyName: s3-access", "  PolicyDocument:", "    Version: \"2012-10-17\"", "    Statement:",
+           "      - Effect: Allow", "        Action: [s3:GetObject, s3:ListBucket]", "        Resource:"] +
+            resources.map { |r| "          - !Sub \"#{r}\"" }
+        end
+
+        # @param resources [Array<String>] the object ARNs a production box may write
+        # @return [Array<String>] the production-only write statement, relative to `Policies`
+        def s3_write_rows(resources)
+          ["      - !If", "        - IsProduction", "        - Effect: Allow",
+           "          Action: [s3:PutObject, s3:DeleteObject]", "          Resource:"] +
+            resources.map { |r| "            - !Sub \"#{r}\"" } + ["        - !Ref AWS::NoValue"]
         end
 
         # Graviton families end their generation digit with `g` (`t4g`, `m7gd`, `c6gn`).
@@ -174,11 +294,14 @@ module Hecks
           SH
         end
 
-        # One ECR repository per container, keeping the newest 30 images.
+        # One ECR repository per container, keeping the newest 30 images. A task definition names
+        # images that already have repositories, so none are made.
         #
         # @param plan [Settings::Plan] the resolved settings
         # @return [String] CloudFormation resources, each preceded by a blank line
         def ecr_repositories(plan)
+          return "" if plan.task_definition
+
           plan.containers.map do |container|
             id = "#{logical(container.name)}Repository"
             <<~YAML.lines.map { |line| line.strip.empty? ? line : "  #{line}" }.join
@@ -198,6 +321,8 @@ module Hecks
         # @param plan [Settings::Plan] the resolved settings
         # @return [String] one repository URI output per container
         def ecr_outputs(plan)
+          return "" if plan.task_definition
+
           plan.containers.map do |container|
             "  #{logical(container.name)}RepositoryUri:\n    Value: !GetAtt #{logical(container.name)}Repository.RepositoryUri\n"
           end.join.chomp
@@ -223,7 +348,7 @@ module Hecks
             else
               indent(route_blocks(plan))
             end
-          "#{caddy_header(plan)}#{caddy_global(guarded)}\n:80 {\n#{site}}\n"
+          "#{caddy_header(plan)}#{caddy_global(guarded)}\n:80 {\n#{site}}\n\n#{CADDY_EXTRA}"
         end
 
         # @param plan [Settings::Plan] the resolved settings
@@ -256,9 +381,12 @@ module Hecks
         # @param guarded [Boolean] whether an origin secret guards the site
         # @return [String] the global options block
         def caddy_global(guarded)
-          return "{\n\tauto_https off\n\tadmin off\n}\n" unless guarded
+          options = "\t# No certificate for the :80 site. disable_redirects, not off, so a listener a rehearsal\n" \
+                    "\t# mounts under caddy-extra can still ask for `tls internal`.\n" \
+                    "\tauto_https disable_redirects\n\tadmin off\n"
+          return "{\n#{options}}\n" unless guarded
 
-          "{\n\tauto_https off\n\tadmin off\n\tservers {\n\t\ttrusted_proxies static 0.0.0.0/0 ::/0\n\t}\n}\n"
+          "{\n#{options}\tservers {\n\t\ttrusted_proxies static 0.0.0.0/0 ::/0\n\t}\n}\n"
         end
 
         # @param text [String] lines to indent one level with a tab
@@ -272,18 +400,30 @@ module Hecks
         # @param plan [Settings::Plan] the resolved settings
         # @return [String] `services.json`
         def services_json(plan)
-          services = plan.containers.to_h do |c|
-            [c.name, { "name" => c.name, "repository" => c.repository, "port" => c.port,
-                       "env" => c.env, "secrets" => c.secrets }]
-          end
+          services = plan.containers.to_h { |c| [c.name, service_entry(plan, c)] }
           origin = plan.origin_secret ? { "header" => plan.origin_header, "secret" => plan.origin_secret } : nil
           document = { "services" => services, "origin" => origin }
+          document["task_definition"] = plan.task_definition if plan.task_definition
           document["tunnel"] = tunnel_entry(plan.tunnel_service) if plan.tunnel_service
           json = JSON.pretty_generate(document)
           # An empty object prints as `{}` or `{` newline `}`, depending on the json gem.
           "#{json.gsub(/\{\s*\}/, '{}')}\n"
         end
 
+        # A container's entry. With a task definition the image, environment and secrets are read
+        # from it at deploy time, so only the name and port are written here.
+        #
+        # @param plan [Settings::Plan] the resolved settings
+        # @param container [Settings::Container] the container
+        # @return [Hash{String => Object}] its entry in `services.json`
+        def service_entry(plan, container)
+          entry = { "name" => container.name, "port" => container.port }
+          return entry if plan.task_definition
+
+          { "name" => container.name, "repository" => container.repository, "port" => container.port,
+            "env" => container.env, "secrets" => container.secrets }
+        end
+
         # @param tunnel [Settings::Tunnel] the declared tunnel service
         # @return [Hash{String => Object}] its entry in `services.json`
         def tunnel_entry(tunnel)
@@ -296,7 +436,29 @@ module Hecks
         def deploy_box_sh(plan, region)
           template("deploy-box.sh.tmpl", "STACK" => plan.infra_name, "BOX_STACK" => plan.box_stack,
                                          "RDS_STACK" => plan.rds_stack, "REGION" => region,
-                                         "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan))
+                                         "DIR" => "/opt/#{plan.infra_name}", "HEALTH_CHECKS" => health_checks(plan),
+                                         "USAGE" => deploy_usage(plan))
+        end
+
+        # @param plan [Settings::Plan] the resolved settings
+        # @return [String] the comment lines that say how to call `deploy-box.sh`
+        def deploy_usage(plan)
+          if plan.task_definition
+            <<~USAGE
+              #   deploy-box.sh [task-definition]
+              #
+              # The task definition (a family or family:revision) defaults to the latest active revision of
+              # #{plan.task_definition}. Secret values are resolved on the box by fetch-secrets.sh and never
+              # pass through the SSM command.
+            USAGE
+          else
+            <<~USAGE
+              #   deploy-box.sh [name=tag ...]
+              #
+              # A container named without a tag runs its "latest" image. Secret values are resolved on the box by
+              # fetch-secrets.sh and never pass through the SSM command.
+            USAGE
+          end
         end
 
         # The probes the post-roll check runs on the box, against the proxy on localhost.
@@ -345,23 +507,27 @@ module Hecks
         def makefile(plan)
           <<~MAKE
             # #{plan.infra_name}: one app box and one RDS instance.
-            #   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c
-            #   make deploy [TAGS="web=20260101 worker=20260101"]
+            #   make stacks VPC=vpc-... PRIVATE_SUBNETS=subnet-a,subnet-b PUBLIC_SUBNET=subnet-c [REHEARSAL=true]
+            #   make deploy #{plan.task_definition ? '[TASKDEF=family:revision]' : '[TAGS="web=20260101 worker=20260101"]'}
             RDS_STACK = #{plan.rds_stack}
             BOX_STACK = #{plan.box_stack}
+            # true makes a throwaway pair: the database is deleted with its stack and the box has no
+            # Elastic IP. The default is a production pair, with deletion protection.
+            REHEARSAL ?= false
 
             .PHONY: stacks deploy
             stacks:
             \taws cloudformation deploy --template-file rds.yaml --stack-name $(RDS_STACK) --capabilities CAPABILITY_IAM \\
-            \t\t--parameter-overrides VpcId=$(VPC) PrivateSubnetIds=$(PRIVATE_SUBNETS)
+            \t\t--parameter-overrides VpcId=$(VPC) PrivateSubnetIds=$(PRIVATE_SUBNETS) Rehearsal=$(REHEARSAL)
             \taws cloudformation deploy --template-file box.yaml --stack-name $(BOX_STACK) --capabilities CAPABILITY_IAM \\
             \t\t--parameter-overrides VpcId=$(VPC) SubnetId=$(PUBLIC_SUBNET) \\
             \t\tDbSecurityGroupId=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='DbSecurityGroupId'].OutputValue" --output text) \\
             \t\tDbSecretArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='DbSecretArn'].OutputValue" --output text) \\
-            \t\tAlertTopicArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='AlertTopicArn'].OutputValue" --output text)
+            \t\tAlertTopicArn=$$(aws cloudformation describe-stacks --stack-name $(RDS_STACK) --query "Stacks[0].Outputs[?OutputKey=='AlertTopicArn'].OutputValue" --output text) \\
+            \t\tRehearsal=$(REHEARSAL)
 
             deploy:
-            \tbash ./deploy-box.sh $(TAGS)
+            \tbash ./deploy-box.sh $(#{plan.task_definition ? 'TASKDEF' : 'TAGS'})
           MAKE
         end
 

data/lib/hecks/projector/cli_projector.rb

@@ -400,16 +400,15 @@ module Hecks
           return command_help(program, spec[:short], spec, ask: options[:ask]) if spec
         end
 
-        width = (commands.values + questions.values).map { |spec| label(spec).length }.max.to_i
         out = ["#{bluebook.name} — #{bluebook.vision}", "",
                "  #{program} <command>! [name=value …]       do something",
                "  #{program} query <query> [name=value …]    read something", ""]
 
         out << "commands:"
-        out.concat(listing(commands, width) { |spec| spec[:summary] })
+        out.concat(listing(commands) { |spec| spec[:summary] })
         out << ""
         out << "queries (nothing here changes anything):"
-        out.concat(listing(questions, width) { |spec| first_sentence(spec[:summary]) })
+        out.concat(listing(questions) { |spec| first_sentence(spec[:summary]) })
         out << ""
         out << "  #{program} <command> --help       what one command wants, and every way it refuses"
         out << "  a command is called with its aggregate — #{example_qualified(commands)}"
@@ -417,34 +416,59 @@ module Hecks
       end
 
       # The command or question lines of the help. A domain with more than one aggregate is listed
-      # under a heading per aggregate, so related commands sit together; the bookkeeping a run
+      # under a heading per aggregate, so related commands sit together; the heading is the prefix
+      # every call to them carries, so the lines under it leave it out. The bookkeeping a run
       # records about itself (`internal`: system-role commands and port operations) is set apart as
-      # names only, since a person never types them. A single-aggregate domain keeps the plain list.
-      def listing(specs, width)
+      # names only, since a person never types them. A single-aggregate domain keeps the plain
+      # list, each name in full.
+      def listing(specs)
         shown, internal = specs.values.partition { |spec| !spec[:internal] }
         groups = shown.group_by { |spec| spec[:group] }
+        grouped = groups.length > 1
+        named = shown.to_h { |spec| [spec, entry_name(spec, grouped)] }
+        width = named.values.map(&:length).max.to_i
         lines = []
-        if groups.length > 1
+        if grouped
           groups.each do |group, members|
             lines << "  #{heading(group)}" if group
-            members.each { |spec| lines << "    #{label(spec).ljust(width)}  #{yield(spec)}" }
+            members.each { |spec| lines << "    #{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
           end
         else
-          shown.each { |spec| lines << "  #{label(spec).ljust(width)}  #{yield(spec)}" }
+          shown.each { |spec| lines << "  #{named[spec].ljust(width)}  #{yield(spec)}#{alias_note(spec)}" }
         end
         lines.concat(internal_lines(internal)) unless internal.empty?
         lines
       end
 
-      # "LanguageRun" reads "Language": the Run suffix names the journaled-command shape all of
-      # these aggregates share, so it adds nothing under a heading ("Test suite", "Model check").
+      # The aggregate's own name as a heading: the prefix of every call to the lines under it.
       def heading(group)
-        words = Naming.snake(group.sub(/Run\z/, "")).tr("_", " ")
-        "#{words.capitalize}:"
+        "#{Naming.snake(group)}:"
+      end
+
+      # A spec's name as listed: under its aggregate's heading the aggregate prefix is left out.
+      # A command the chapter gives a short name (`mcp`) is listed by its real name, so the
+      # heading and the line still spell a call; `alias_note` says the short name.
+      def entry_name(spec, grouped)
+        name = label(spec, real: true)
+        return name unless grouped && spec[:group]
+
+        name.delete_prefix("#{Naming.snake(spec[:group])}.")
+      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.
+      def alias_note(spec)
+        return "" if spec[:short_was].nil? || spec[:short_was].split(".").last == spec[:short]
+
+        " (also: #{label(spec)})"
       end
 
       # A command is written with the `!` that marks it; a query without one.
-      def label(spec) = spec[:kind] == :command ? "#{spec[:short]}!" : spec[:short]
+      # With `real:`, a short name the chapter gave it gives way to the name it was given for.
+      def label(spec, real: false)
+        name = real && spec.key?(:short_was) ? spec[:short_was] : spec[:short]
+        spec[:kind] == :command ? "#{name}!" : name
+      end
 
       # The internal commands as bare names, wrapped, under one line saying what they are.
       def internal_lines(specs)

data/lib/hecks/runtime/loader.rb

@@ -50,7 +50,26 @@ module Hecks
       end
 
       # What `describe` answers: the loaded declarations and nothing bound to run them.
-      Described = Struct.new(:registry, :directory)
+      #
+      # The declarations load the first time `registry` is asked for, not when `describe` returns,
+      # so a caller that can answer from `directory` alone (a launcher with its help already
+      # remembered) never pays for the load. The directory is checked at once.
+      class Described
+        # @return [String] the domain directory that was described
+        attr_reader :directory
+
+        # @param directory [String] the domain directory
+        # @yield loads the declarations; answers the registry
+        def initialize(directory, &load)
+          @directory = directory
+          @load = load
+        end
+
+        # @return [Registry] the declarations, loaded on first use
+        def registry
+          @registry ||= @load.call
+        end
+      end
 
       # Loads `path`'s declarations into a fresh Registry and stops: no boot gate runs, no
       # persistence adapter is resolved or bound, nothing connects to a database.
@@ -66,15 +85,19 @@ module Hecks
       def self.describe(path, shared: nil, environment: FROM_ENV)
         loading   = Ports::Loading.bootstrap
         directory = loading.bluebook_directory(path)
-        root      = loading.shared_root(shared, directory)
-        registry  = Registry.new(root: File.dirname(directory))
+        overlay   = selected_environment(environment)
 
-        Hecks.with_registry(registry) do
-          loading.load_library
-          loading.load_project(root)
-          loading.load_domain(directory, environment: selected_environment(environment))
+        Described.new(directory) do
+          root     = loading.shared_root(shared, directory)
+          registry = Registry.new(root: File.dirname(directory))
+
+          Hecks.with_registry(registry) do
+            loading.load_library
+            loading.load_project(root)
+            loading.load_domain(directory, environment: overlay)
+          end
+          registry
         end
-        Described.new(registry, directory)
       end
 
       # The overlay a boot loads: the caller's own choice (nil meaning none), else the