hecks 3.1.0 → 3.1.1

data/lib/hecks/hecks/adapters/finding_github.adapter

@@ -0,0 +1,7 @@
+# Required by name, not relative to this file: a fuzz or model check boots a copy of this directory,
+# and the implementation must load once, from `lib/`, not from the copy.
+require "hecks/hecks/adapters/finding_github"
+
+Hecks.adapter "FindingGithub" do
+  port "GitHubIssues"
+end

data/lib/hecks/hecks/adapters/finding_github.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Hecks
+  module Adapters
+    # The `GitHubIssues` port's adapter: drives one GitHub issue from a `Tickets::Finding` with
+    # `gh`.
+    #
+    # Nothing is opened until a repository is named, by the `repository` setting or the
+    # `HECKS_FINDINGS_REPO` environment variable (`owner/name`); without one every ask is refused,
+    # and the runtime records the refusal on the finding. An ask that needs the issue before one
+    # was opened is refused the same way, so a finding never blocks on GitHub.
+    class FindingGithub
+      # The environment variable that names the repository when no setting does.
+      REPOSITORY_VARIABLE = "HECKS_FINDINGS_REPO"
+
+      # @param aggregate [Object, nil] unused
+      # @param settings [Hash] `repository:` names the `owner/name` to drive
+      # @param root [String, nil] unused
+      def initialize(aggregate: nil, settings: {}, root: nil)
+        @repository = settings[:repository]
+      end
+
+      # Opens an issue for the finding the runtime hands over (its whole held state).
+      #
+      # @param held [Hash] the finding's fields; `title` and `body` are value objects or strings
+      # @return [Hash{Symbol => Hash}] `issue_number:` of the new issue, the shape
+      #   `Finding.RecordIssue` takes
+      # @raise [RuntimeError] when no repository is named, `gh` exits non-zero, or prints no
+      #   issue URL
+      def open_issue(**held)
+        out = gh("issue", "create", "--title", plain(held[:title]).to_s, "--body", plain(held[:body]).to_s)
+        number = out.lines.last.to_s.strip[%r{/issues/(\d+)\z}, 1]
+        raise "gh issue create printed no issue URL: #{out.strip.inspect}" unless number
+
+        { issue_number: { value: number.to_i } }
+      end
+
+      # Puts the finding's kind and severity on its issue as labels.
+      #
+      # @param held [Hash] the finding's fields
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def label_issue(**held)
+        labels = [["kind", held[:kind]], ["severity", held[:severity]]]
+                 .map { |name, field| "#{name}:#{plain(field)}" unless plain(field).to_s.empty? }.compact
+        return said("no kind or severity to label") if labels.empty?
+
+        gh("issue", "edit", issue(held), "--add-label", labels.join(","))
+        said("labelled #{labels.join(', ')}")
+      end
+
+      # Comments on the issue with the pull request that fixes the finding.
+      #
+      # @param held [Hash] the finding's fields
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def comment_on_issue(**held)
+        gh("issue", "comment", issue(held), "--body", "A fix is proposed in ##{plain(held[:fix_pr_number])}")
+        said("commented with the fix")
+      end
+
+      # Closes the issue: as completed for a resolved finding, as not planned for a dismissed one.
+      #
+      # @param held [Hash] the finding's fields, `status` among them
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def close_issue(**held)
+        reason = plain(held[:status]) == "dismissed" ? "not planned" : "completed"
+        gh("issue", "close", issue(held), "--reason", reason)
+        said("closed as #{reason}")
+      end
+
+      # Reopens the issue of a finding taken back to triaged.
+      #
+      # @param held [Hash] the finding's fields
+      # @return [Hash{Symbol => Hash}] `output:` the line that says what was done
+      def reopen_issue(**held)
+        gh("issue", "reopen", issue(held))
+        said("reopened")
+      end
+
+      private
+
+      def gh(*arguments)
+        out, err, status = Open3.capture3("gh", *arguments, "--repo", repository)
+        raise "gh #{arguments.first(2).join(' ')} failed — #{err.strip.empty? ? out.strip : err.strip}" unless status.success?
+
+        out
+      end
+
+      def repository
+        name = @repository || ENV.fetch(REPOSITORY_VARIABLE, nil)
+        return name unless name.to_s.strip.empty?
+
+        raise "no repository named: set the `repository` setting or #{REPOSITORY_VARIABLE} to owner/name"
+      end
+
+      def issue(held)
+        number = plain(held[:issue_number])
+        raise "the finding has no GitHub issue yet" if number.to_s.empty?
+
+        number.to_s
+      end
+
+      def said(line) = { output: { value: line } }
+
+      # A materialized value object (`{value: x}`, symbol or string keys) or the value itself.
+      def plain(field)
+        return field unless field.is_a?(Hash)
+
+        field.key?(:value) ? field[:value] : field["value"]
+      end
+    end
+  end
+end

data/lib/hecks/hecks/adapters/terminal.rb

@@ -66,6 +66,21 @@ module Hecks
         raise ConsoleCapture::Failure, "the mcp door refused to start (status #{e.status}); see stderr"
       end
 
+      # Holds an interview at the terminal and writes the domain it drafts (ADR 0088). Asking is IO,
+      # so it happens here and nowhere else; the journal records that one was held, not its words.
+      #
+      # @param held [Hash] the `Door` record: `name`; optionally `adapter`, `dir`, `expert`, `no_ai`
+      # @return [Hash{Symbol => Hash}] `output:` what the interview wrote, or that it wrote nothing
+      # @raise [ConsoleCapture::Failure] when the name or adapter is refused, or a file is there
+      def converse(**held)
+        require "hecks/cli/interview_run"
+        report = CLI::InterviewRun.call(name: plain(held[:name]), adapter: plain(held[:adapter]), dir: plain(held[:dir]),
+                                        expert: plain(held[:expert]), use_ai: !plain(held[:no_ai]))
+        { output: { value: report.empty? ? "no interview was written" : report } }
+      rescue ArgumentError => e
+        raise ConsoleCapture::Failure, e.message
+      end
+
       private
 
       def plain(argument) = argument.is_a?(Hash) ? argument[:value] : argument

data/lib/hecks/hecks/context_map.hecksagon

@@ -8,6 +8,6 @@ end
 
 # The attached chapters (hecks.hecksagon `attaches`): each is a bounded context whose store comes
 # from hecks.world's `default_adapter`, so the memory overlay swaps them with the Hecks chapter.
-%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site QualityControl].each do |chapter|
+%w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets QualityControl].each do |chapter|
   Hecks.hecksagon(chapter) { attaches "Governance" }
 end

data/lib/hecks/hecks/custodian.bluebook

@@ -1280,6 +1280,8 @@ policy "RecordTheEra" do
     attribute :name,    DomainName, optional: true
     attribute :adapter, AdapterName, optional: true
     attribute :dir,     TargetDir,  optional: true
+    attribute :expert,  ExpertName, optional: true
+    attribute :no_ai,   Switch,     optional: true
     attribute :output,  Note,       optional: true
     attribute :refusal, Note,       optional: true
     identified_by :run
@@ -1314,6 +1316,11 @@ policy "RecordTheEra" do
       attribute :value, String, pattern: '[^\t\n\r]'
     end
 
+    # Who is interviewed; asked for at the terminal when absent.
+    value_object "ExpertName" do
+      attribute :value, String, pattern: '[^\t\n\r]'
+    end
+
     value_object "Note" do
       attribute :value, String
     end
@@ -1357,6 +1364,30 @@ policy "RecordTheEra" do
       emits StubRequested
     end
 
+    # Holds an interview with a subject matter expert and drafts a first domain from it (ADR 0088).
+    # The Terminal adapter runs the conversation, as it runs a console; the journal records that one
+    # was held and how it ended, not what was said. `--no-ai` leaves the model out.
+    command "Interview" do
+      role "Operator"
+      goal "Hold an interview with a subject matter expert and draft a first domain from it"
+
+      attribute :run,     DoorKey
+      attribute :name,    DomainName
+      attribute :adapter, AdapterName, optional: true
+      attribute :dir,     TargetDir,   optional: true
+      attribute :expert,  ExpertName,  optional: true
+      attribute :no_ai,   Switch,      optional: true
+
+      sets :run
+      sets :name
+      sets :adapter
+      sets :dir
+      sets :expert
+      sets :no_ai
+
+      emits InterviewRequested
+    end
+
     # A stdio server runs until its client closes stdin, so it cannot be asked and answered
     # quickly like the others. The command records that the door was started; the Terminal
     # adapter hands the process over to the door and answers when it closes, as OpenConsole
@@ -1423,6 +1454,11 @@ policy "RecordTheEra" do
     trigger Door::Workspace::Scaffold, with: { run: :run }
   end
 
+  policy "ConverseWhenRequested" do
+    on      "Door.InterviewRequested"
+    trigger Door::Terminal::Converse, with: { run: :run }
+  end
+
   policy "ServeWhenRequested" do
     on      "Door.McpRequested"
     trigger Door::Terminal::Serve, with: { run: :run }

data/lib/hecks/hecks/hecks.bluebook

@@ -8,9 +8,15 @@ Hecks.bluebook "Hecks" do
     attribute :version,    Version
     attribute :ir_version, Version
     attribute :ships_from, Checkout, optional: true
+    # The findings the version settled, by the key the Tickets chapter gives them.
+    attribute :closes,     list_of(FindingKey), optional: true
 
     identified_by :version
 
+    value_object "FindingKey" do
+      attribute :value, String, pattern: '[^ \t\n\r]'
+    end
+
     value_object "Version" do
       attribute :value, String, pattern: '^[0-9]+[.][0-9]+[.][0-9]+'
 
@@ -61,6 +67,18 @@ Hecks.bluebook "Hecks" do
       emits Verified
     end
 
+    command "CloseFindings" do
+      role "Maintainer"
+      goal "Record the findings this version settled"
+
+      reference_to Release
+      attribute :closes, list_of(FindingKey)
+
+      sets :closes
+
+      emits FindingsClosed
+    end
+
     query "Shipped" do
       description "Every version that was tagged, published and verified."
       where(state: "verified")

data/lib/hecks/hecks/hecks.hecksagon

@@ -2,8 +2,8 @@ Hecks.hecksagon "Hecks" do
   attaches "Governance"
 
   # The chapters the gem carries: the language declared in itself (Paging comes with Bluebook),
-  # Expression, Tenancy, Deploy, Site and QualityControl (the last two bring their own ports).
-  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site QualityControl]
+  # Expression, Tenancy, Deploy, Site, Tickets and QualityControl (the last three bring their own ports).
+  %w[Bluebook Hecksagon World Adapter Port Translation Expression Tenancy Deploy Site Tickets QualityControl]
     .each { |chapter| attaches chapter }
   # Persistence is not bound here: hecks.world's `default_adapter` binds every aggregate, so
   # environments/memory.world can swap the whole domain without a double bind.
@@ -109,6 +109,12 @@ Hecks.hecksagon "Hecks" do
       answers "DoorAnswered"
       refuses "DoorRefused"
     end
+
+    asks "Converse", to: Door do
+      attribute :run, DoorKey
+      answers "DoorAnswered"
+      refuses "DoorRefused"
+    end
   end
 
   Hecks::Build.port "RustToolchain" do

data/lib/hecks/hecks/hecks.world

@@ -37,10 +37,11 @@ Hecks.world "Hecks" do
   launcher "Launcher", run_keys: true,
                        failure_states: %w[flagged failed drifted unreachable refused faulted halted stopped
                                           abandoned red needs_fix],
-                       names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init" },
+                       names: { "mcp" => "door.serve_mcp", "console" => "operation.open_console", "init" => "door.init",
+                                "interview" => "door.interview" },
                        streams: %w[Follow],
                        executable: "exe/hecks",
-                       memory_commands: %w[console init],
+                       memory_commands: %w[console init interview],
                        legacy: %w[run docs narrate ir stores model_check smoke_test
                                   project_diagrams project_cli mcp]
 end

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

@@ -20,6 +20,12 @@ module Hecks
           ENGINE      = /\A\d{2}(\.\d{1,2})?\z/
           PREFIX      = /\A[a-z][a-z0-9-]{0,20}\z/
           IMAGE       = %r{\A[a-z0-9][a-z0-9._/:@-]{1,200}\z}
+          TASKDEF     = /\A[a-zA-Z0-9_-]{1,255}\z/
+          SCHEMA      = /\A[a-z][a-z0-9_]{0,62}\z/
+          MIGRATION_SHAPE = "migration: a hash needs `schemas`, a list of the schema names to copy".freeze
+          S3_BUCKET   = /\A[a-z0-9][a-z0-9.-]{1,61}[a-z0-9]\z/
+          S3_SHAPE    = "s3_access: a list of `{ bucket: \"name\", write: true }` hashes (write is optional)".freeze
+          FROM_TASKDEF = %i[env secrets repository].freeze
           # Default images, each a version tag plus the digest of its multi-architecture index,
           # so a rebuilt box pulls the same bytes.
           TUNNEL_IMAGE = "cloudflare/cloudflared:2026.9.3" \
@@ -55,12 +61,26 @@ module Hecks
           # @!attribute [r] image [String] the cloudflared image
           Tunnel = Struct.new(:container, :port, :token_secret, :image, keyword_init: true)
 
+          # The data a project moves from its old database into the new RDS instance.
+          #
+          # @!attribute [r] schemas [Array<String>] the schemas to copy
+          # @!attribute [r] database [String] the database holding them on the RDS instance
+          # @!attribute [r] source_database [String] the database holding them on the old server
+          Migration = Struct.new(:schemas, :database, :source_database, keyword_init: true)
+
+          # An S3 bucket the box's role may read, and in production write.
+          #
+          # @!attribute [r] name [String] the bucket's name
+          # @!attribute [r] write [Boolean] whether a production box may also write and delete
+          Bucket = Struct.new(:name, :write, keyword_init: true)
+
           # Everything the generator reads, checked.
           Plan = Struct.new(
             :infra_name, :stack_prefix, :instance_type, :volume_gb, :swap_gb, :database_class,
             :storage_gb, :backup_days, :snapshots_keep, :database_name, :engine_version,
             :containers, :routes, :default_container, :origin_header, :origin_secret,
-            :secret_prefixes, :tunnel, :tunnel_service, :proxy_image, keyword_init: true
+            :secret_prefixes, :tunnel, :tunnel_service, :proxy_image, :task_definition,
+            :migration, :s3_buckets, keyword_init: true
           ) do
             # @return [String] the CloudFormation stack that holds the database
             def rds_stack = "#{stack_prefix}-#{infra_name}-rds"
@@ -85,19 +105,24 @@ module Hecks
           def resolve(deploy_settings:, target:, infra_name:)
             s = deploy_settings
             check(:stack_name, infra_name, NAME)
-            containers = read_containers(s.fetch(:containers) { raise ArgumentError, missing_containers }, infra_name)
+            database_name = read_database_name(s, infra_name)
+            listed = s.fetch(:containers) { raise ArgumentError, missing_containers }
+            task_definition = read_task_definition(s[:task_definition], listed)
+            containers = read_containers(listed, infra_name)
             header, secret = read_origin(s)
             tunnel, tunnel_service = read_tunnel(s.fetch(:tunnel, false), containers)
 
             Plan.new(
               infra_name: infra_name, stack_prefix: check(:stack_prefix, s.fetch(:stack_prefix, "hecks"), PREFIX),
-              **declared_sizes(target), **read_sizes(s), database_name: read_database_name(s, infra_name),
+              **declared_sizes(target), **read_sizes(s), database_name: database_name,
               engine_version: check(:engine_version, s.fetch(:engine_version, "16").to_s, ENGINE),
               containers: containers, routes: read_routes(s.fetch(:routes, []), containers),
               default_container: read_default(s[:default_container], containers), origin_header: header,
               origin_secret: secret, secret_prefixes: read_prefixes(s, infra_name),
               tunnel: tunnel, tunnel_service: tunnel_service,
-              proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE)
+              proxy_image: check(:proxy_image, s.fetch(:proxy_image, PROXY_IMAGE), IMAGE),
+              task_definition: task_definition, migration: read_migration(s[:migration], database_name),
+              s3_buckets: read_s3_access(s.fetch(:s3_access, []))
             )
           end
 
@@ -117,10 +142,61 @@ module Hecks
             }
           end
 
+          # @param value [Hash{Symbol => Object}, nil] the world's `migration` setting
+          # @param database_name [String] the RDS database, which the schemas move into by default
+          # @return [Migration, nil] the data to move, or nil when the world declares none
+          # @raise [ArgumentError] when the setting is not a hash with a non-empty list of schemas
+          def read_migration(value, database_name)
+            return nil if value.nil?
+            raise ArgumentError, MIGRATION_SHAPE unless value.is_a?(Hash)
+
+            listed = value.fetch(:schemas) { raise ArgumentError, MIGRATION_SHAPE }
+            raise ArgumentError, MIGRATION_SHAPE unless listed.is_a?(Array) && !listed.empty?
+
+            database = check(:migration_database, value.fetch(:database, database_name), DB_NAME)
+            Migration.new(schemas: listed.map { |name| check(:migration_schemas, name, SCHEMA) }.uniq, database: database,
+                          source_database: check(:migration_source_database, value.fetch(:source_database, database), DB_NAME))
+          end
+
+          # @param list [Array<Hash>] the world's `s3_access` setting
+          # @return [Array<Bucket>] the buckets, each readable and optionally writable in production
+          # @raise [ArgumentError] when the setting is not a list of bucket hashes
+          def read_s3_access(list)
+            raise ArgumentError, S3_SHAPE unless list.is_a?(Array)
+
+            list.map do |spec|
+              raise ArgumentError, S3_SHAPE unless spec.is_a?(Hash)
+
+              name = check(:s3_bucket, spec.fetch(:bucket) { raise ArgumentError, S3_SHAPE }, S3_BUCKET)
+              Bucket.new(name: name, write: boolean(:s3_write, spec.fetch(:write, false)))
+            end.uniq(&:name)
+          end
+
           def read_database_name(settings, infra_name)
             check(:database_name, settings.fetch(:database_name, infra_name.gsub(/[^a-zA-Z0-9]/, "")), DB_NAME)
           end
 
+          # With a task definition, the images, environment and secrets are read from it at deploy
+          # time, so a container that also sets them is ambiguous and refused.
+          #
+          # @param family [String, nil] the ECS task definition family the world names
+          # @param listed [Array<Hash>] the containers as the world wrote them
+          # @return [String, nil] the checked family, or nil when the world does not use one
+          # @raise [ArgumentError] when the family is malformed or a container sets what it supplies
+          def read_task_definition(family, listed)
+            return nil if family.nil?
+
+            check(:task_definition, family, TASKDEF)
+            Array(listed).each do |spec|
+              clash = spec.is_a?(Hash) ? FROM_TASKDEF & spec.keys : []
+              next if clash.empty?
+
+              raise ArgumentError, "containers: #{spec[:name]} sets #{clash.join(', ')}, which the task definition " \
+                                   "#{family} supplies; drop #{clash.size == 1 ? 'it' : 'them'} or drop task_definition"
+            end
+            family
+          end
+
           def read_containers(list, infra_name)
             raise ArgumentError, missing_containers unless list.is_a?(Array) && !list.empty?
 

data/lib/hecks/projections/deploy/box/templates/box.yaml.tmpl

@@ -104,6 +104,7 @@ Resources:
                 Resource:
                   - !Ref DbSecretArn
 @@SECRET_RESOURCES@@
+@@S3_POLICY@@
 
   BoxProfile:
     Type: AWS::IAM::InstanceProfile

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

@@ -2,10 +2,7 @@
 # Roll @@STACK@@'s app box: render the compose files, push them over SSM, start the containers and check
 # them. Exits non-zero if the roll fails or the box does not answer as expected.
 #
-#   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@@
 set -euo pipefail
 HERE=$(cd "$(dirname "$0")" && pwd)
 BOX_STACK=@@BOX_STACK@@
@@ -42,7 +39,8 @@ B64() { base64 < "$1" | tr -d '\n'; }
 ROLL=$(jq -n --arg compose "$(B64 "$WORK/compose.json")" --arg secrets "$(B64 "$WORK/secrets.json")" \
   --arg caddy "$(B64 "$HERE/Caddyfile")" --arg fetch "$(B64 "$HERE/fetch-secrets.sh")" \
   --arg registry "$ACCOUNT.dkr.ecr.$REGION.amazonaws.com" --arg dir "$DIR" '
-  {commands: ["set -e", "mkdir -p \($dir) && cd \($dir)", "umask 077",
+  {commands: ["cloud-init status --wait >/dev/null 2>&1 || true",
+    "set -e", "mkdir -p \($dir)/caddy-extra && cd \($dir)", "umask 077",
     "echo \($compose) | base64 -d > compose.json; echo \($secrets) | base64 -d > secrets.json",
     "echo \($caddy) | base64 -d > Caddyfile; echo \($fetch) | base64 -d > fetch-secrets.sh",
     "bash fetch-secrets.sh",

data/lib/hecks/projections/deploy/box/templates/rds.yaml.tmpl

@@ -7,6 +7,12 @@ Description: >
 Parameters:
   VpcId:
     Type: AWS::EC2::VPC::Id
+  BastionSecurityGroupId:
+    Type: String
+    Default: ""
+    Description: >
+      A security group allowed to reach the database on 5432, for the bastion that restore-to-rds.sh
+      tunnels through. Blank admits nothing but the app box.
   PrivateSubnetIds:
     Type: List<AWS::EC2::Subnet::Id>
     Description: At least two subnets in different availability zones (an RDS subnet group needs them).
@@ -46,13 +52,23 @@ Conditions:
   NewTopic: !Equals [!Ref ExistingAlertTopicArn, ""]
   NewTopicWithEmail: !And [!Condition NewTopic, !Not [!Equals [!Ref AlertEmail, ""]]]
   IsRehearsal: !Equals [!Ref Rehearsal, "true"]
+  HasBastion: !Not [!Equals [!Ref BastionSecurityGroupId, ""]]
 
 Resources:
   DbSecurityGroup:
     Type: AWS::EC2::SecurityGroup
     Properties:
-      GroupDescription: @@STACK@@ RDS, 5432 from the app box only (the box stack adds the rule)
+      GroupDescription: @@STACK@@ RDS, 5432 from the app box (the box stack adds the rule) and a bastion if given
       VpcId: !Ref VpcId
+      SecurityGroupIngress:
+        - !If
+          - HasBastion
+          - IpProtocol: tcp
+            FromPort: 5432
+            ToPort: 5432
+            SourceSecurityGroupId: !Ref BastionSecurityGroupId
+            Description: Bastion for restore-to-rds.sh
+          - !Ref AWS::NoValue
 
   DbSubnetGroup:
     Type: AWS::RDS::DBSubnetGroup

data/lib/hecks/projections/deploy/box/templates/render-compose-taskdef.sh.tmpl

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Render compose.json and secrets.json for @@STACK@@'s app box from an ECS task definition.
+#
+#   render-compose.sh <db-host> <db-secret-arn> [task-definition]
+#
+# The task definition (a family or family:revision; default: the latest active revision of @@FAMILY@@)
+# is the source of truth for each container's image, environment and secrets, so the box starts with
+# what the task would have. A container the box runs must be named in it. DB_HOST and DB_SECRET_ARN
+# are replaced with the RDS stack's values where the task defines them, and every container runs on
+# the box's own network, so the proxy reaches each one on 127.0.0.1:<port>. Secrets (name + valueFrom)
+# are written to secrets.json for fetch-secrets.sh to resolve on the box.
+set -euo pipefail
+HERE=$(cd "$(dirname "$0")" && pwd)
+DB_HOST=${1:?rds endpoint}
+DB_SECRET=${2:?rds secret arn}
+TD=${3:-@@FAMILY@@}
+
+DEF=$(aws ecs describe-task-definition --task-definition "$TD" --query 'taskDefinition.containerDefinitions' --output json)
+echo "rendering from task definition $TD" >&2
+
+jq --argjson def "$DEF" --arg host "$DB_HOST" --arg secret "$DB_SECRET" '
+  def log: {driver: "json-file", options: {"max-size": "10m", "max-file": "3"}};
+  def env(c): ((c.environment // []) | map({(.name): .value}) | add // {})
+    | (if has("DB_HOST") then .DB_HOST = $host | .DB_SECRET_ARN = $secret else . end);
+  . as $in
+  | {services: (
+      ($in.services | with_entries(.value |= (. as $s
+        | ($def | map(select(.name == $s.name)) | first) as $c
+        | if $c == null then error("task definition has no container named " + $s.name) else
+            {image: $c.image, network_mode: "host", restart: "unless-stopped", logging: log,
+             environment: ({PORT: ($s.port | tostring)} + env($c))}
+            + (if (($c.secrets // []) | length) > 0 then {env_file: [($s.name + ".secrets.env")]} else {} end)
+          end)))
+      + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
+                 + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
+      + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
+                  command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],
+                  env_file: ["cloudflared.secrets.env"], logging: log}} else {} end))}' \
+  "$HERE/services.json" > compose.json
+
+jq --argjson def "$DEF" '. as $in
+    | [ ($in.services | keys[]) as $n | $def[] | select(.name == $n) | (.secrets // [])[]
+        | {service: $n, name: .name, valueFrom: .valueFrom} ]
+      + [ (if $in.origin then {service: "caddy", name: "ORIGIN_SECRET", valueFrom: $in.origin.secret} else empty end),
+          (if $in.tunnel then {service: "cloudflared", name: "TUNNEL_TOKEN", valueFrom: $in.tunnel.token_secret} else empty end) ]' \
+  "$HERE/services.json" > secrets.json
+
+echo "rendered compose.json and secrets.json ($(jq '.services | length' compose.json) services)"

data/lib/hecks/projections/deploy/box/templates/render-compose.sh.tmpl

@@ -27,7 +27,7 @@ jq --arg ecr "$ECR" --argjson tags "$TAGS" --arg host "$DB_HOST" --arg secret "$
          environment: ({PORT: (.port | tostring), DB_HOST: $host, DB_NAME: $db, DB_SECRET_ARN: $secret} + .env)}
         + (if (.secrets | length) > 0 then {env_file: [(.name + ".secrets.env")]} else {} end))))
       + {caddy: ({image: "@@PROXY_IMAGE@@", network_mode: "host", restart: "unless-stopped",
-                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro"], logging: log}
+                  volumes: ["./Caddyfile:/etc/caddy/Caddyfile:ro", "./caddy-extra:/etc/caddy/extra:ro"], logging: log}
                  + (if $in.origin then {env_file: ["caddy.secrets.env"]} else {} end))}
       + (if $in.tunnel then {cloudflared: {image: $in.tunnel.image, network_mode: "host", restart: "unless-stopped",
                   command: ["tunnel", "--no-autoupdate", "--url", $in.tunnel.url, "run"],

data/lib/hecks/projections/deploy/box/templates/restore-to-rds.sh.tmpl

@@ -0,0 +1,91 @@
+#!/bin/bash
+# Copy @@STACK@@'s schemas from the old database into the new RDS instance through a bastion that can
+# reach both, then verify the copy. Piped dump | restore, so nothing is written to disk. Never writes to
+# the source.
+#
+#   restore-to-rds.sh <bastion-instance-id> <source-host> <source-secret-arn> <rds-host> <rds-secret-arn>
+#
+#   FORCE=1   drop the target schemas first: a re-load before cutover, or a rollback copy in the other
+#             direction (swap the hosts and secrets, and SRC_DB and DST_DB)
+#   SRC_DB    the source database (default @@SOURCE_DATABASE@@)
+#   DST_DB    the target database (default @@DATABASE@@)
+#
+# Schemas copied: @@SCHEMAS@@
+#
+# Why not a plain pg_restore: a Hecks schema's materialized views call hecks_tr_extract() unqualified, and
+# pg_restore runs with an empty search_path, so the restore's REFRESH step errors on them. This restores
+# tolerating exactly that error, then refreshes the views with the schema on the search_path, and fails on
+# any other error.
+#
+# Needs pg_dump, pg_restore and psql 16 or newer, the SSM plugin, jq and AWS credentials that can read both
+# secrets and start SSM sessions.
+set -euo pipefail
+HERE=$(cd "$(dirname "$0")" && pwd)
+
+BASTION=${1:?bastion instance id}; SRC_HOST=${2:?source host}; SRC_SECRET=${3:?source secret arn}
+DST_HOST=${4:?target host}; DST_SECRET=${5:?target secret arn}
+SCHEMAS="@@SCHEMAS@@"
+SRC_DB=${SRC_DB:-@@SOURCE_DATABASE@@}; DST_DB=${DST_DB:-@@DATABASE@@}
+SRC_PORT=15432; DST_PORT=15433
+
+pg_major() { "$1" --version 2>/dev/null | sed -E 's/.* ([0-9]+)[.].*/\1/'; }
+# The default client on the PATH is often older than the server (Homebrew's is 14); prefer postgresql@16.
+if [ "$(pg_major pg_dump || echo 0)" -lt 16 ] && [ -x /opt/homebrew/opt/postgresql@16/bin/pg_dump ]; then
+  export PATH=/opt/homebrew/opt/postgresql@16/bin:$PATH
+fi
+for t in pg_dump pg_restore psql; do
+  [ "$(pg_major $t || echo 0)" -ge 16 ] || { echo "need $t 16 or newer on the PATH" >&2; exit 1; }
+done
+
+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"; }
+SRC_PW=$(secret_field "$SRC_SECRET" .password); DST_PW=$(secret_field "$DST_SECRET" .password)
+SRC_USER=$(secret_field "$SRC_SECRET" '.username // "postgres"'); DST_USER=$(secret_field "$DST_SECRET" '.username // "postgres"')
+
+tunnel() { # host local-port
+  aws ssm start-session --target "$BASTION" --document-name AWS-StartPortForwardingSessionToRemoteHost \
+    --parameters "{\"host\":[\"$1\"],\"portNumber\":[\"5432\"],\"localPortNumber\":[\"$2\"]}" >"$WORK/tunnel_$2.log" 2>&1 &
+  PIDS+=($!)
+  disown # so shutting the tunnel down at exit does not print a "Terminated" line
+}
+tunnel "$SRC_HOST" $SRC_PORT; tunnel "$DST_HOST" $DST_PORT
+for i in $(seq 1 20); do
+  grep -q "Waiting for connections" "$WORK/tunnel_$SRC_PORT.log" 2>/dev/null && grep -q "Waiting for connections" "$WORK/tunnel_$DST_PORT.log" 2>/dev/null && break
+  sleep 1
+done
+
+SRC() { PGPASSWORD=$SRC_PW psql -h localhost -p $SRC_PORT -U "$SRC_USER" -d "$SRC_DB" -Atc "$1"; }
+DST() { PGPASSWORD=$DST_PW psql -h localhost -p $DST_PORT -U "$DST_USER" -d "$DST_DB" -Atc "$1"; }
+echo "source $(SRC 'show server_version'), target $(DST 'show server_version')"
+
+# Refuse to clobber a target that already holds the schemas.
+for S in $SCHEMAS; do
+  if [ "$(DST "select count(*) from pg_namespace where nspname='$S'")" != 0 ]; then
+    if [ "${FORCE:-}" = 1 ]; then DST "drop schema \"$S\" cascade" >/dev/null; echo "dropped target schema $S"
+    else echo "target already has schema $S; re-run with FORCE=1 to replace it" >&2; exit 1; fi
+  fi
+done
+
+for S in $SCHEMAS; do
+  echo "== copying schema $S"
+  PGPASSWORD=$SRC_PW pg_dump -h localhost -p $SRC_PORT -U "$SRC_USER" -d "$SRC_DB" --schema="$S" -Fc --no-owner --no-privileges \
+    | PGPASSWORD=$DST_PW pg_restore -h localhost -p $DST_PORT -U "$DST_USER" -d "$DST_DB" --no-owner --no-privileges 2>"$WORK/err_$S.txt" || true
+  TOTAL=$(grep -c 'error:' "$WORK/err_$S.txt" || true)
+  UNEXPECTED=$(grep 'error:' "$WORK/err_$S.txt" | grep -vc 'hecks_tr_extract' || true)
+  echo "   restore errors: $TOTAL (unexpected: $UNEXPECTED)"
+  if [ "$UNEXPECTED" != 0 ]; then grep 'error:' "$WORK/err_$S.txt" | grep -v 'hecks_tr_extract' | head -5 >&2; exit 1; fi
+done
+
+# Refresh what pg_restore could not (with the schema on the search_path).
+for S in $SCHEMAS; do
+  for MV in $(DST "select matviewname from pg_matviews where schemaname='$S' and not ispopulated"); do
+    PGPASSWORD=$DST_PW psql -h localhost -p $DST_PORT -U "$DST_USER" -d "$DST_DB" -qAtc "set search_path=\"$S\",public; refresh materialized view \"$S\".\"$MV\""
+  done
+done
+
+# Same structure, same exact row counts in every table, nothing unpopulated.
+A_DB=$SRC_DB B_DB=$DST_DB bash "$HERE/verify-copy.sh" "$BASTION" "$SRC_HOST" "$SRC_SECRET" "$DST_HOST" "$DST_SECRET"