hecks 2.9.0 → 3.0.1

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

@@ -282,7 +282,7 @@ module Hecks
             end
 
           template_yaml = <<~YAML
-            # GENERATED by bin/project_deploy #{domain} — re-run it to refresh
+            # GENERATED by hecks deploy project #{domain} — re-run it to refresh
             # this file rather than hand-editing. Source: #{world_file}'s own
             # deployed_to("AwsLambda") block.
             #
@@ -338,8 +338,8 @@ module Hecks
                   # targets, below) via the SAME `aws cloudformation describe-stacks`
                   # pattern `mint-era` already used for a bastion, one stack over
                   # instead of one sibling stack over. Never a CloudFormation
-                  # Export/ImportValue -- this codebase uses none anywhere (bin/
-                  # project_deploy's own header on why: a live shell lookup keeps
+                  # Export/ImportValue -- this codebase uses none anywhere (hecks
+                  # deploy project's own header on why: a live shell lookup keeps
                   # this stack independently deployable/deletable, never coupled to
                   # #{owner_domain_name}'s own stack through CloudFormation itself).
                   OwningVpcId:
@@ -485,13 +485,13 @@ module Hecks
                           "          DB_SECRET_ARN: !Sub \"${#{secret_sub}}\""
                         end}
                       # `domain_name`, NOT `infra_name` — this names the actual
-                      # .wasm FILE bin/project_wasm writes (rust/dist/#{domain_name}.wasm,
+                      # .wasm FILE `hecks build_wasm` writes (rust/dist/#{domain_name}.wasm,
                       # its own target_mod_name convention, a Rust-build-pipeline
                       # concern unrelated to AWS resource identity) and what the
                       # Makefile below actually bundles into the Lambda package
                       # under. Confirmed the hard way: pinning this to infra_name
                       # alongside the real AWS-identity fields left it looking for
-                      # a file bin/project_wasm never produces.
+                      # a file `hecks build_wasm` never produces.
                       HECKS_WASM_PATH: !Sub "/var/task/#{domain_name}.wasm"
                       # STATIC, not a deploy-time parameter — HECKS_DOMAIN is this
                       # domain's own declared name, known at generation time the
@@ -636,7 +636,7 @@ module Hecks
                   PasswordLength: 64
                   ExcludePunctuation: true
 
-            #{webhook_secret_env ? <<-WEBHOOKSECRET : ""}
+            #{webhook_secret_env ? <<~WEBHOOKSECRET.rstrip : ""}
           # Auto-generated, never typed or seen — the SAME
           # ManageMasterUserPassword/SessionSecret pattern above, applied to
           # `secret_env`'s own webhook secret instead (deploy_settings' own
@@ -822,7 +822,7 @@ module Hecks
             Outputs:
               FunctionUrl:
                 Value: !GetAtt #{logical_id}Url.FunctionUrl#{web_handler_present ? "\n  WebFunctionUrl:\n    Value: !GetAtt #{web_logical_id}Url.FunctionUrl" : ""}
-              # stack_outputs (bin/project_deploy, above the heredocs) is the ONE
+              # stack_outputs (hecks deploy project, above the heredocs) is the ONE
               # place these four names live — DatabaseEndpoint/DatabaseSecretArn
               # feed `make mint-era`'s own boot step directly; VpcId/
               # DbSecurityGroupId ALSO feed bastion.yaml's own Parameters (a
@@ -831,7 +831,7 @@ module Hecks
               # network without this main template ever knowing a bastion
               # exists) and the Makefile's own --parameter-overrides. Rename a
               # key in that table and every consumer follows; reference one that
-              # doesn't exist there and bin/project_deploy refuses before
+              # doesn't exist there and hecks deploy project refuses before
               # writing a single file, instead of a bastion.yaml whose Parameter
               # nothing could ever fill. (`PrivateSubnetId` used to sit here too
               # — dropped, nothing ever consumed it; bastion.yaml mints its own
@@ -899,7 +899,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
               <<~SHAREDMINT.rstrip
               # NOT AUTOMATED YET for a Shared-mode domain — it has no RDS/VPC
               # of its own to stand a temporary bastion next to (bastion.yaml
-              # itself isn't even generated here — bin/project_deploy's own
+              # itself isn't even generated here — hecks deploy project's own
               # comment on why). Minting era 1 for #{infra_name}'s own schema
               # needs a tunnel to #{owner_domain_name}'s ALREADY-EXISTING RDS
               # instance instead -- reuse #{owner_domain_name}'s own deploy
@@ -948,7 +948,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             else
               <<~OWNMINT.rstrip
               \t@echo "Looking up $(STACK)'s VPC/security group..."
-              # stack_outputs/bastion_parameters (bin/project_deploy) are the ONE
+              # stack_outputs/bastion_parameters (hecks deploy project) are the ONE
               # place these OutputKey strings and parameter names live — this eval
               # chain and the --parameter-overrides line just below are both
               # generated from the SAME table template.yaml's Outputs and
@@ -1067,13 +1067,13 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
               \techo "Tearing down the temporary bastion stack..."; \\
               \taws cloudformation delete-stack --stack-name $(BASTION_STACK); \\
               \taws cloudformation wait stack-delete-complete --stack-name $(BASTION_STACK); \\
-              \techo "$(BASTION_STACK) deleted. Era 1 should now be held if BOOT_STATUS was 0 — verify with bin/console or a Postgres query against hecks_eras."; \\
+              \techo "$(BASTION_STACK) deleted. Era 1 should now be held if BOOT_STATUS was 0 — verify with hecks console or a Postgres query against hecks_eras."; \\
               \texit $$BOOT_STATUS
               OWNMINT
             end
 
           # Shares mint_era_recipe's bastion/tunnel/retry/teardown chain but
-          # runs bin/scaffold_translation or bin/translation_audit over it.
+          # runs `hecks ask scaffold_translation` or `hecks ask audit_translation` over it.
           #
           # Neither script actually reads DATABASE_URL/HECKS_SCHEMA (both call
           # `registry.binding_settings`, a lookup against the literal `database
@@ -1081,7 +1081,8 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           # recipe would open a real tunnel to production and silently
           # scaffold/audit the local dev database instead, reporting success.
           # `db_env_blind` refuses unless `ALLOW_LOCAL_DB=1` is set.
-          translation_recipe = lambda do |verb, script, extra_args = "", cwd: "$(ROOT)", run_prefix: "ruby -Ilib", db_env_blind: false|
+          translation_recipe = lambda do |verb, script, extra_args = "", cwd: "$(ROOT)", run_prefix: "ruby -Ilib", db_env_blind: false,
+                                          domain_arg: "$(DOMAIN) "|
             if shared
               <<~SHAREDTRANSLATION.rstrip
               \t@echo "#{verb} isn't automated yet for a Shared-mode domain (database \\"Shared\\") -- see mint-era's own comment in the generated Makefile for the manual path through #{owner_domain_name}'s own tunnel."; \\
@@ -1130,7 +1131,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
               \t\t\tnc -z localhost 15432 2>/dev/null && break; \\
               \t\t\tsleep 1; \\
               \t\tdone; \\
-              \t\tcd #{cwd} && DATABASE_URL="postgres://postgres:$$DB_PASS_URLENC@localhost:15432/#{db_name}" HECKS_SCHEMA="#{hecks_schema}" #{run_prefix} #{script} #{cwd == "$(ROOT)" ? "$(DOMAIN) " : ""}#{extra_args}&& { RUN_STATUS=0; break; }; \\
+              \t\tcd #{cwd} && DATABASE_URL="postgres://postgres:$$DB_PASS_URLENC@localhost:15432/#{db_name}" HECKS_SCHEMA="#{hecks_schema}" #{run_prefix} #{script} #{cwd == "$(ROOT)" ? domain_arg : ""}#{extra_args}&& { RUN_STATUS=0; break; }; \\
               \t\tRUN_STATUS=$$?; \\
               \t\techo "#{verb} attempt $$attempt/5 failed (exit $$RUN_STATUS) -- restarting the tunnel and retrying in 3s..."; \\
               \t\tsleep 3; \\
@@ -1145,12 +1146,22 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             end
           end
 
-          scaffold_translation_recipe = translation_recipe.call("scaffold-translation", "bin/scaffold_translation", db_env_blind: true)
-          translation_audit_recipe = translation_recipe.call("translation-audit", "bin/translation_audit", db_env_blind: true)
+          # `hecks ask` answers the scaffold as text, and refuses (exit 1) where the script aborted.
+          scaffold_translation_recipe = translation_recipe.call(
+            "scaffold-translation", "exe/hecks ask scaffold_translation", db_env_blind: true,
+            run_prefix: "HECKS_ENVIRONMENT=memory ruby", domain_arg: "domain=$(DOMAIN) "
+          )
+          # A refused audit is a refused query: `hecks ask` exits 1, so the target fails too.
+          translation_audit_recipe = translation_recipe.call(
+            "translation-audit", "exe/hecks ask audit_translation", db_env_blind: true,
+            run_prefix: "HECKS_ENVIRONMENT=memory ruby", domain_arg: "domain=$(DOMAIN) "
+          )
 
           # Same chain, running an app-owned one-time migration script instead
-          # of a hecks bin/ tool. Harmless when the domain has none: `bundle
-          # exec ruby` on a missing file just fails loudly.
+          # of a hecks tool. `bin/migrate_console_settings` belongs to the domain's own
+          # application, not to hecks, so it stays a `bin/` path when hecks drops its own.
+          # Harmless when the domain has none: `bundle exec ruby` on a missing file just fails
+          # loudly.
           migrate_console_settings_recipe = translation_recipe.call(
             "migrate-console-settings", "bin/migrate_console_settings", "",
             cwd: "$(DOMAIN)", run_prefix: "bundle exec ruby"
@@ -1354,7 +1365,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           ).map { |l| "\t#{l}" }.join("\n")
 
           makefile_content = <<~MAKE
-            # GENERATED by bin/project_deploy #{domain} — re-run it to refresh
+            # GENERATED by hecks deploy project #{domain} — re-run it to refresh
             # this file rather than hand-editing.
             #
             # `sam build` invokes the build-<LogicalId> target below (SAM's own
@@ -1365,7 +1376,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             # `brew install cargo-lambda`.
 
             HOST_DIR := #{File.join(root, "rust", "host")}
-            # `domain_name`, matching bin/project_wasm's own target_mod_name
+            # `domain_name`, matching `hecks build_wasm`'s own target_mod_name
             # (a Rust-build-pipeline naming convention, not AWS resource
             # identity — see HECKS_WASM_PATH's own comment above).
             WASM     := #{File.join(root, "rust", "dist", "#{domain_name}.wasm")}
@@ -1380,13 +1391,13 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             # start of a work session silently kept getting deployed through
             # every later kernel change (a real, live bug: this cost a stale
             # deploy against a wasm that predated the kernel's own "mutations"
-            # field). `bin/project_wasm` recompiles fast enough that "always
+            # field). `hecks build_wasm` recompiles fast enough that "always
             # rebuild" is the safe default, matching rust/host's own bootstrap
             # build just below, which was never guarded this way to begin with.
-            \tcd #{root} && bin/project_wasm #{domain}
+            \tcd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks build_wasm domain=#{domain} --wait
             \t@rustup target list --installed 2>/dev/null | grep -qx aarch64-unknown-linux-gnu || rustup target add aarch64-unknown-linux-gnu
             # `rustup run stable`, not a bare `cargo lambda` — same reasoning
-            # bin/project_wasm's own Makefile-equivalent line holds itself to: a
+            # `hecks build_wasm`'s own Makefile-equivalent line holds itself to: a
             # `cargo`/`rustc` earlier on PATH than rustup's own shims (Homebrew
             # installs one; common on this kind of machine) is a DIFFERENT
             # toolchain that never saw `rustup target add`, and fails with
@@ -1452,26 +1463,26 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             # `make verify-parity-#{logical_id}` — closes the exact gap the
             # equivalence-gap plan's own Phase 8 named: parity was checked ONLY
             # against CI's fixed test corpus, completely decoupled from what a
-            # real `sam deploy` actually ships — `bin/rust_conformance` (the
+            # real `sam deploy` actually ships — `hecks check_conformance` (the
             # differential harness, docs/decisions/0010-ruby-is-the-reference-
             # implementation.md) had never once been run against a specific
             # compiled deploy artifact. Runs it here, for real, against
             # $(WASM) -- the EXACT file `build-#{logical_id}` (above) just built
             # and `deploy:` (below) is about to ship -- not a corpus-wide `cargo
-            # build`'s own separate binary. `bin/rust_conformance` exits non-zero
+            # build`'s own separate binary. `hecks check_conformance --wait` exits non-zero
             # on any mismatch, which this target lets propagate uncaught: a real
             # divergence between THIS artifact and Ruby's own reading of the
             # identical source blocks `make deploy` before `sam deploy` ever
             # runs, the same way a failing build already would.
             #
             # `spec/corpus/#{domain_name}.json` is this domain's OWN pinned
-            # fuzzer-replay script (the same shape `bin/fuzz`/`bin/run` already
+            # fuzzer-replay script (the same shape `hecks fuzz`/`hecks run` already
             # use) -- if a domain doesn't have one yet, this warns LOUDLY and
             # continues rather than either silently skipping (this project's own
             # standing rule against a silent gap reading as full coverage) or
             # blocking every deploy of a domain nobody has written one for yet.
             #
-            # SECOND HALF, BELOW — `bin/rust_conformance_fuzz`, ADR 0037's own fuzz
+            # SECOND HALF, BELOW — `hecks fuzz_conformance`, ADR 0037's own fuzz
             # bridge pointed at this exact $(WASM). A pinned script only proves
             # "matches Ruby on the cases we thought to write down" (ADR 0039's own
             # honest framing); the fuzz bridge is what actually FOUND Findings 1-6.
@@ -1485,12 +1496,12 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
             .PHONY: verify-parity-#{logical_id}
             verify-parity-#{logical_id}:
             \t@if [ -f #{root}/spec/corpus/#{domain_name}.json ]; then \\
-            \t\tcd #{root} && bin/rust_conformance #{domain} spec/corpus/#{domain_name}.json $(WASM); \\
+            \t\tcd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks check_conformance domain=#{domain} script=spec/corpus/#{domain_name}.json artifact=$(WASM) --wait; \\
             \telse \\
-            \t\techo "verify-parity-#{logical_id}: no spec/corpus/#{domain_name}.json -- SKIPPING the pre-deploy Ruby/Rust parity check, nothing to compare $(WASM) against. Write one (bin/fuzz/bin/run's own script shape) before this domain's next deploy."; \\
+            \t\techo "verify-parity-#{logical_id}: no spec/corpus/#{domain_name}.json -- SKIPPING the pre-deploy Ruby/Rust parity check, nothing to compare $(WASM) against. Write one (hecks fuzz/hecks run's own script shape) before this domain's next deploy."; \\
             \tfi
             \t@echo "verify-parity-#{logical_id}: fuzzing $(WASM) against generated sequences (ADR 0037's bridge, WARN-ONLY -- see this target's own comment)..."
-            \t-@cd #{root} && bin/rust_conformance_fuzz #{domain} $(WASM)
+            \t-@cd #{root} && HECKS_ENVIRONMENT=memory ruby exe/hecks fuzz_conformance domain=#{domain} artifact=$(WASM) --wait
 
             # `make mint-era` — takes #{stack_name}'s RDS instance from freshly
             # created to "era 1 minted, ready for HECKS_DOMAIN/HECKS_ERA to
@@ -1713,7 +1724,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
                 # safe either way, since mint-era's own quiet-reboot path is a
                 # no-op the moment nothing has actually changed.
                 #
-                # See predeploy_bridge_shell's own comment (bin/project_deploy,
+                # See predeploy_bridge_shell's own comment (hecks deploy project,
                 # above, right before deploy_recipe_lines) for why this branches
                 # on google_oauth_present at all -- the short version: adding
                 # Google OAuth to an EXISTING stack would otherwise deadlock this
@@ -1729,7 +1740,7 @@ bastion_yaml = shared ? nil : Shared.bastion_yaml(
           # Everything `sam deploy --guided` would ask interactively is already
           # known from the domain's own `deployed_to("AwsLambda")` block.
           samconfig_toml = <<~TOML
-            # GENERATED by bin/project_deploy #{domain} — re-run it to refresh
+            # GENERATED by hecks deploy project #{domain} — re-run it to refresh
             # this file rather than hand-editing.
             version = 0.1
 

data/lib/hecks/projections/deploy/preview/preview.sh.erb

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# GENERATED by bin/project_deploy - re-run it to refresh this file rather than
+# GENERATED by hecks deploy project - re-run it to refresh this file rather than
 # hand-editing. Source: the `preview` block of the domain's deployed_to("AwsFargate").
 #
 # Feature-branch previews of <%= s.infra_name %>: one isolated stack per git branch,

data/lib/hecks/projections/deploy/preview/template.rb

@@ -28,7 +28,7 @@ module Hecks
 
           def header(settings)
             <<~YAML.chomp
-              # GENERATED by bin/project_deploy - re-run it to refresh this file rather than
+              # GENERATED by hecks deploy project - re-run it to refresh this file rather than
               # hand-editing. Source: the `preview` block of the domain's deployed_to("AwsFargate").
               #
               # One stack per git branch, driven by preview.sh. A separate template from the main

data/lib/hecks/projections/deploy/scripts/deploy-service.sh.tmpl

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# GENERATED by bin/project_deploy -- re-run it to refresh this file rather
+# GENERATED by hecks deploy project -- re-run it to refresh this file rather
 # than hand-editing. Settings come from the domain's deployed_to("AwsFargate")
 # block; see Hecks::Projections::Deploy::Scripts for each key.
 #

data/lib/hecks/projections/deploy/scripts/expected-era.header

@@ -13,5 +13,5 @@
 # The id is what the host reports at GET /version, the same id the era mint
 # prints. Compare a live host with this file:
 #
-#   bin/check_era https://host.example expected-era
+#   hecks check_era host=https://host.example expected=expected-era --wait
 #   make check-era URL=https://host.example

data/lib/hecks/projections/deploy/scripts/hosting.mk.tmpl

@@ -1,4 +1,4 @@
-# GENERATED by bin/project_deploy -- re-run it to refresh this file rather
+# GENERATED by hecks deploy project -- re-run it to refresh this file rather
 # than hand-editing. Included by the Makefile beside it; settings come from the
 # domain's deployed_to("AwsFargate") block (see
 # Hecks::Projections::Deploy::Scripts for each key).
@@ -24,7 +24,7 @@ build: hecks-release
 # Fetches the pinned release's tag into HECKS_ROOT unless it is already there,
 # and refuses a checkout that is not exactly that tag.
 hecks-release:
-	@if [ -f "$(HECKS_ROOT)/bin/project_wasm" ]; then \
+	@if [ -f "$(HECKS_ROOT)/exe/hecks" ]; then \
 		echo "hecks v$(HECKS_VERSION) is already at $(HECKS_ROOT)"; \
 	else \
 		echo "Fetching hecks v$(HECKS_VERSION) from $(HECKS_SOURCE) into $(HECKS_ROOT)..."; \
@@ -51,4 +51,4 @@ smoke-after-deploy:
 # Compares the era a live host reports at GET /version with expected-era.
 check-era:
 	@test -n "$(URL)" || { echo "usage: make check-era URL=https://host.example"; exit 1; }
-	ruby "$(HECKS_ROOT)/bin/check_era" "$(URL)" expected-era
+	HECKS_ENVIRONMENT=memory ruby "$(HECKS_ROOT)/exe/hecks" check_era host="$(URL)" expected=expected-era --wait

data/lib/hecks/projections/deploy/scripts/smoke-after-deploy.sh.tmpl

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# GENERATED by bin/project_deploy -- re-run it to refresh this file rather
+# GENERATED by hecks deploy project -- re-run it to refresh this file rather
 # than hand-editing. Settings come from the domain's deployed_to("AwsFargate")
 # block; see Hecks::Projections::Deploy::Scripts for each key.
 #

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

@@ -390,7 +390,7 @@ module Hecks
         # @return [String] the rendered CloudFormation template
         def bastion_yaml(domain:, infra_name:, stack_name:, db_id:, google_oauth_present:, bastion_parameters:)
           <<~YAML
-            # GENERATED by bin/project_deploy #{domain} — re-run it to refresh
+            # GENERATED by hecks deploy project #{domain} — re-run it to refresh
             # this file rather than hand-editing. Deployed and destroyed by
             # `make mint-era` (this directory's own Makefile) — never left
             # running: it exists only long enough for one Ruby boot to reach

data/lib/hecks/projections/diagrams.rb

@@ -70,12 +70,12 @@ module Hecks
 
       def holders_with_lifecycle(bluebook) = holders(bluebook).select(&:lifecycle)
 
-      # `chapter_name` drives the re-run hint: `bin/project_diagrams` takes a chapter
+      # `chapter_name` drives the re-run hint: `hecks project_diagrams` takes a chapter
       # name, not the subject's.
       def header(chapter_name, subject)
         <<~HEADER
-          %% GENERATED by bin/project_diagrams from #{subject} — DO NOT EDIT BY HAND.
-          %% Re-run `bin/project_diagrams <domain-path> #{chapter_name}` after any change.
+          %% GENERATED by hecks project_diagrams from #{subject} — DO NOT EDIT BY HAND.
+          %% Re-run `hecks project_diagrams <domain-path> #{chapter_name}` after any change.
         HEADER
       end
 

data/lib/hecks/projections/model/deviations.rb

@@ -48,7 +48,7 @@ module Hecks
         # Fields emitted by `to_h`'s own merge rather than `emits_ir`, for constructs
         # whose shape is not fixed.
         DYNAMIC_TAIL = {
-          "Query"     => %i[options],
+          "Query"     => %i[options returns],
           "ReadModel" => %i[options group_by aggregate_heads count median_field sum_field avg_field
                             min_field max_field percentile_field percentile_at any_field all_field]
         }.freeze

data/lib/hecks/projections/parser_table.rb

@@ -13,7 +13,7 @@ module Hecks
       # Projects the Rust parser's keyword and closed-set tables for one chapter.
       #
       # @param bluebook [Bluebook::Chapter] the chapter to project; the language's own
-      #   for the ordinary `bin/project_parser_table` run
+      #   for the ordinary `hecks project_parser_table` run
       # @param options [Hash{Symbol => Object}] ignored; present to satisfy the
       #   `Projector::Target` calling convention
       # @return [String] the rendered Rust source
@@ -98,14 +98,14 @@ module Hecks
         arguments = table[:arguments]
 
         <<~RUST
-          // GENERATED by bin/project_parser_table from
+          // GENERATED by hecks project_parser_table from
           // aggregate-local syntax tables under lib/hecks/language/ — DO NOT EDIT BY HAND.
           //
-          // Re-run `bin/project_parser_table` after any syntax-table change.
+          // Re-run `hecks project_parser_table` after any syntax-table change.
           // spec/parser_table_spec.rb regenerates this into memory and fails the
           // normal `bundle exec rspec` suite the moment this file drifts from what
           // the language currently declares — see that spec and
-          // bin/project_parser_table's own header for why this file is never
+          // hecks project_parser_table's own header for why this file is never
           // hand-edited.
 
           #[derive(Debug, Clone, Copy)]

data/lib/hecks/projections/reference.rb

@@ -1,9 +1,8 @@
 require_relative "../projector"
 
 module Hecks
-  # Repository-only tooling: `Doc::Reference` reads the committed pages under
-  # `docs/`, which only a checkout has, so it loads on first use and the
-  # packaged gem leaves it out (ADR 0066).
+  # `Doc::Reference` reads the committed pages under `docs/`, which only a
+  # checkout has, so it loads on first use.
   module Doc
     autoload :Reference, File.expand_path("../doc/reference", __dir__)
   end

data/lib/hecks/projections/rust_vocabulary.rb

@@ -14,7 +14,7 @@ module Hecks
 
       projects_as :rust_vocabulary, declares: "Vocabulary", emits: :files
 
-      GENERATOR = "bin/project_rust_vocabulary".freeze
+      GENERATOR = "hecks project_rust_vocabulary".freeze
       SOURCE    = "lib/hecks/language/bluebook/vocabulary.bluebook".freeze
 
       # Table name => enum name, variant-naming fields, file stem and kind.

data/lib/hecks/projector/cli_projector.rb

@@ -3,21 +3,21 @@ require_relative "../naming"
 module Hecks
   module Projector
     # Projects a bluebook as its own command-line surface: the verb tree, argument spec
-    # and usage text. Nothing executes here; the generic runner (`bin/run`) parses against it.
+    # and usage text. Nothing executes here; the generic runner (`hecks run`) parses against it.
     #
     # Argument types come from the declared field types, never from guessing at the
     # string: `sequence.value=99` must become 99, and a version "99" must stay a String.
     module CliProjector
       module_function
 
-      # Projects the verb and question tables and the usage text.
-      #
-      # Commands and queries are separate namespaces because a chapter may declare both
-      # under one name; questions are asked with `ask`.
+      # Projects the verb and question tables and the usage text. Commands and queries are
+      # separate namespaces (a chapter may declare both under one name); ask a query with `ask`.
       #
       # @param bluebook [Bluebook::Chapter] the booted domain to project
-      # @param options [Hash{Symbol => Object}] `:program` (default `"bin/run"`) for the usage
-      #   text; `:verb` and `:ask` select one verb's `--help` text
+      # @param options [Hash{Symbol => Object}] `:program` (default `"hecks run"`) for the usage
+      #   text; `:verb` and `:ask` select one verb's `--help` text; `:names` maps a launcher
+      #   name to the command it stands for (`{ "mcp" => "serve_mcp" }`); `:mint_run_keys` makes a
+      #   creating verb's `run` key optional, since the launcher mints it
       # @return [Hash{Symbol => Object}] `:verbs`, `:questions`, `:names` (alias tables) and
       #   `:usage` (pre-rendered help text)
       # @raise [Bluebook::DSL::Malformed] if two verbs project to the same command-line name
@@ -25,24 +25,7 @@ module Hecks
         verbs     = {}
         questions = {}
 
-        bluebook.aggregates.each do |aggregate|
-          aggregate.commands.each { |c| claim(verbs, name_for(aggregate, c), command_spec(bluebook, aggregate, nil, c)) }
-          aggregate.queries.each  { |q| claim(questions, name_for(aggregate, q), query_spec(bluebook, aggregate, nil, q)) }
-
-          aggregate.entities.each do |entity|
-            entity.commands.each do |c|
-              claim(verbs, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
-            end
-            entity.queries.each do |q|
-              claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
-            end
-          end
-
-          # Port operations dispatch by the same name as a command, so they are verbs too.
-          aggregate.ports.each do |port|
-            port.operations.each { |o| claim(verbs, name_for(aggregate, o), port_spec(bluebook, aggregate, port, o)) }
-          end
-        end
+        bluebook.aggregates.each { |aggregate| claim_aggregate(verbs, questions, bluebook, aggregate) }
 
         # A report belongs to the chapter, not an aggregate, so it is addressed
         # `Chapter.Report` (one dot) where a query is `Chapter::Aggregate.Query`.
@@ -50,15 +33,42 @@ module Hecks
           claim(questions, Naming.snake(model.hecks_name), report_spec(bluebook, model))
         end
 
+        mint_run_keys(verbs) if options[:mint_run_keys]
+
         # The display name is the shortest unambiguous one; both spellings are accepted.
-        shorten(verbs)
-        shorten(questions)
+        display_names([verbs, questions], options[:names])
 
         { verbs: verbs, questions: questions,
           names: { command: aliases(verbs), question: aliases(questions) },
           usage: usage(bluebook, verbs, questions, options) }
       end
 
+      # Claims the verbs and questions of one aggregate and its entities and ports.
+      #
+      # @param verbs [Hash{String => Hash}] the verb map, mutated in place
+      # @param questions [Hash{String => Hash}] the question map, mutated in place
+      # @param bluebook [Bluebook::Chapter] the booted domain
+      # @param aggregate [Bluebook::Aggregate] the aggregate to claim
+      # @return [void]
+      def claim_aggregate(verbs, questions, bluebook, aggregate)
+        aggregate.commands.each { |c| claim(verbs, name_for(aggregate, c), command_spec(bluebook, aggregate, nil, c)) }
+        aggregate.queries.each  { |q| claim(questions, name_for(aggregate, q), query_spec(bluebook, aggregate, nil, q)) }
+
+        aggregate.entities.each do |entity|
+          entity.commands.each do |c|
+            claim(verbs, name_for(aggregate, c, entity), command_spec(bluebook, aggregate, entity, c))
+          end
+          entity.queries.each do |q|
+            claim(questions, name_for(aggregate, q, entity), query_spec(bluebook, aggregate, entity, q))
+          end
+        end
+
+        # Port operations dispatch by the same name as a command, so they are verbs too.
+        aggregate.ports.each do |port|
+          port.operations.each { |o| claim(verbs, name_for(aggregate, o), port_spec(bluebook, aggregate, port, o)) }
+        end
+      end
+
       # Sets `:short` on each spec: the last segment when exactly one verb ends in it,
       # else the full name (two aggregates both declaring `Close` keep both spellings).
       #
@@ -72,11 +82,62 @@ module Hecks
         end
       end
 
-      # Maps every accepted spelling (full name and `:short`) to the full name.
+      # Marks the `run` key of each creating verb `minted`: optional, and never filled by a bare
+      # word, since the launcher makes one when it is left out.
+      def mint_run_keys(verbs)
+        verbs.each_value do |spec|
+          next unless spec[:creates]
+
+          spec[:arguments] = spec[:arguments].map do |argument|
+            next argument unless argument[:path] == "run.value"
+
+            argument.merge(required: false, minted: true, note: "minted when omitted")
+          end
+        end
+      end
+
+      # Sets the display name of every spec in each map: shortened, then renamed by `names`.
+      #
+      # @param maps [Array<Hash{String => Hash}>] the verb and question maps, mutated in place
+      # @param names [Hash, nil] the chapter's launcher names
+      # @return [void]
+      def display_names(maps, names)
+        maps.each do |specs|
+          shorten(specs)
+          rename(specs, names)
+        end
+      end
+
+      # Gives a command the launcher name a chapter's `names` table assigns it.
+      #
+      # The alias replaces the short name in help, so it is listed once; the spelling it
+      # replaced keeps working (`:short_was`, read by `aliases`). A table entry naming no
+      # command in `specs` belongs to the other namespace and is skipped.
+      #
+      # @param specs [Hash{String => Hash}] the verb or question map, mutated in place
+      # @param names [Hash{String, Symbol => String, Symbol}, nil] launcher name to command name
+      # @return [void]
+      # @raise [Bluebook::DSL::Malformed] if a launcher name is already another command's name
+      def rename(specs, names)
+        Hash(names).each do |launcher_name, command|
+          found = specs.find { |key, spec| [key, spec[:short]].include?(command.to_s) }
+          next unless found
+
+          taken = specs.values.any? { |spec| spec[:short] == launcher_name.to_s }
+          raise Bluebook::DSL::Malformed, "launcher name #{launcher_name.to_s.inspect} is already a command" if taken
+
+          found.last[:short_was] = found.last[:short]
+          found.last[:short]     = launcher_name.to_s
+        end
+      end
+
+      # Maps every accepted spelling (full name, `:short` and a renamed command's old short
+      # name) to the full name.
       def aliases(specs)
         specs.each_with_object({}) do |(name, spec), map|
           map[name]         = name
           map[spec[:short]] = name
+          map[spec[:short_was]] = name if spec[:short_was]
         end
       end
 
@@ -148,7 +209,8 @@ module Hecks
           creates: command.creates?,
           receiver: receiver, legacy_receiver: (receiver == :aggregate ? :id : nil),
           legacy_arguments: legacy_arguments,
-          refusals: refusals(command, holder), arguments: arguments }
+          refusals: refusals(command, holder), requirements: requirements(command),
+          arguments: arguments }
       end
 
       # A port operation reads as a verb but reports as a boundary: it creates no
@@ -202,7 +264,7 @@ module Hecks
         end
 
         { verb: fqn(bluebook, aggregate, query, entity), kind: :query,
-          summary: query.description, arguments: arguments }
+          summary: query.description, arguments: arguments, returns: query.returns }
       end
 
       # Flattens an attribute into one option per leaf field. A value object becomes
@@ -243,8 +305,11 @@ module Hecks
           note: "id of a #{attribute.type.target_name}" }
       end
 
+      # A `list_of` scalar carries `list: true, words: true`: the launcher reads a comma-separated
+      # value or a repeated name as the list's elements, since the runtime refuses a lone scalar.
       def scalar_option(path, field, optional, enum: [])
         option = { path: path, type: field.type.to_s, required: !optional }
+        option.merge!(list: true, words: true, note: "list: comma-separated or repeated") if field.list?
         option[:enum]    = enum          unless enum.empty?
         option[:pattern] = field.pattern if field.respond_to?(:pattern) && field.pattern
         option[:default] = field.default if field.respond_to?(:default) && !field.default.nil?
@@ -270,8 +335,8 @@ module Hecks
         nil
       end
 
-      # Every way the verb can say no, in the chapter's own words: a lifecycle state
-      # mismatch, a missing referenced record per `reference_to`, then each `given`.
+      # The conditions that refuse the verb when they hold, in the chapter's own words: a
+      # lifecycle state mismatch and a missing referenced record per `reference_to`.
       def refusals(command, holder)
         out = []
         lifecycle = holder.lifecycle
@@ -280,13 +345,17 @@ module Hecks
         end.flatten.uniq
         out << "#{lifecycle.field} is not #{froms.join(' or ')}" if froms && !froms.empty?
         out += command.attributes.select(&:reference?).map { |r| "no #{r.type.target_name} has that #{r.name}" }
-        out + command.givens.map(&:description)
+        out
       end
 
+      # The conditions the verb needs: each `given` states what must hold, so the verb is
+      # refused unless it does.
+      def requirements(command) = command.givens.map(&:description)
+
       # Renders the full verb/question table, or one verb's `--help` text when
       # `options[:verb]` names one.
       def usage(bluebook, verbs, questions, options)
-        program = options[:program] || "bin/run"
+        program = options[:program] || "hecks run"
         only    = options[:verb]
 
         # `options[:ask]` picks the namespace when both hold the name; without it a
@@ -366,9 +435,9 @@ module Hecks
       end
 
       def verb_help_refusal_lines(spec)
-        return [] if Array(spec[:refusals]).empty?
-
-        ["refused when:", *spec[:refusals].map { |refusal| "  #{refusal}" }, ""]
+        [["refused when:", spec[:refusals]], ["refused unless:", spec[:requirements]]].flat_map do |heading, items|
+          Array(items).empty? ? [] : [heading, *items.map { |item| "  #{item}" }, ""]
+        end
       end
     end
   end

data/lib/hecks/projector.rb

@@ -6,7 +6,7 @@ module Hecks
   #
   # A projection is inert and derived from a chapter's declaration. An export
   # (rust crate, WASM, CloudFormation) also needs `.world` bindings and declares
-  # `needs_world: true`. State projections (`bin/expression_projection`) and
+  # `needs_world: true`. State projections (`hecks project_expression_tables`) and
   # `Ports::Projection` read-model catch-up are different things and not registered.
   module Projector
     class UnknownProjector < StandardError; end