hecks 5.0.0 → 6.0.0

data/lib/hecks/rust_build/host.rb

@@ -5,6 +5,7 @@ require "open3"
 require_relative "../rust_build"
 require_relative "wasm"
 require_relative "prebuilt_binary"
+require_relative "target_dir"
 
 module Hecks
   module RustBuild
@@ -15,7 +16,7 @@ module Hecks
     #
     # The host is compiled from the workspace this release carries (`rust/host`), so the binary is
     # the one the installed gem was released with; nothing is fetched. The module and IR come from
-    # `Wasm`. `CARGO_TARGET_DIR` names where Cargo writes (the copy's `target/` for a client), so
+    # `Wasm`. `TargetDir` names where Cargo writes (one shared cache for an installed copy), so
     # a second build recompiles only what changed. Stages `<domain>-host`, `<domain>.wasm` and
     # `<domain>.ir.json` in `--stage` (default `.hecks/host/<target>/` in the working directory).
     module Host
@@ -28,10 +29,13 @@ module Hecks
       # A Rust target triple: `<arch>-<vendor>-<os>`, with an optional `-<env>`.
       TRIPLE = /\A[a-z0-9_]+(-[a-z0-9_.]+){2,3}\z/
 
+      # The `host: <triple>` line of `rustc -vV`, capturing the triple.
+      HOST_LINE = /^host: (\S+)/
+
       module_function
 
-      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>` and
-      #   `--stage=<directory>`
+      # @param argv [Array<String>] the domain's directory, then optional `--target=<triple>`,
+      #   `--stage=<directory>` and `--no-prebuilt` (compile the host, download no published one)
       # @return [Integer] the exit status
       # @raise [Failure] when the toolchain, the target or a step is missing or fails
       def call(argv)
@@ -39,13 +43,15 @@ module Hecks
           raise Failure, "usage: hecks build_host <domain> [target=<triple>] [stage=<directory>]"
         target = flag(argv, "target") || host_triple
         require_buildable!(target)
-        stage = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+        stage = stage_for(argv, target)
 
         build_module(domain)
-        publish(compile(target), File.basename(domain.chomp("/")), stage)
+        publish(compile(target, prebuilt: !argv.include?("--no-prebuilt")), File.basename(domain.chomp("/")), stage)
         0
       end
 
+      def stage_for(argv, target) = flag(argv, "stage") || File.join(Dir.pwd, ".hecks", "host", target)
+
       def build_module(domain)
         raise Failure, "project_wasm failed for #{domain}" unless Wasm.call([domain]).zero?
       end
@@ -61,7 +67,7 @@ module Hecks
       # @raise [Failure] when there is no Rust toolchain
       def host_triple
         require_rustup!
-        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[/^host: (\S+)/, 1] or
+        query("rustup", "run", TOOLCHAIN, "rustc", "-vV").to_s[HOST_LINE, 1] or
           raise Failure, "rustup has no #{TOOLCHAIN} toolchain. Install it once with:\n\n    " \
                          "rustup toolchain install #{TOOLCHAIN}\n\nthen re-run the build."
       end
@@ -100,11 +106,11 @@ module Hecks
 
       # `rustup run`, not bare `cargo`, as `Wasm` does. A cross target links with the
       # `<arch>-linux-gnu-gcc` on PATH unless `CARGO_TARGET_<TRIPLE>_LINKER` already names a linker.
-      def compile(target)
+      def compile(target, prebuilt: true)
         host_dir = File.join(RustBuild.rust_dir, "host")
-        target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(host_dir, "target"))
+        target_dir = TargetDir.for(host_dir)
         binary = File.join(target_dir, target, "release", BINARY)
-        return binary if PrebuiltBinary.fetch("host", host_dir, target: target, into: binary)
+        return binary if PrebuiltBinary.fetch_for("rust/host", host_dir, target: target, into: binary, allowed: prebuilt)
 
         cargo_build(target, host_dir, { "CARGO_TARGET_DIR" => target_dir }.merge(linker_for(target)))
         binary

data/lib/hecks/rust_build/native_build.rb

@@ -80,7 +80,8 @@ module Hecks
         return if relative.start_with?("target/") || !File.file?(path)
 
         stat = File.stat(path)
-        digest << "#{relative}\0#{stat.size}\0#{stat.mtime.to_i}.#{stat.mtime.nsec}\n"
+        mtime = stat.mtime
+        digest << "#{relative}\0#{stat.size}\0#{mtime.to_i}.#{mtime.nsec}\n"
       end
 
       # Holds an exclusive flock from `cargo build` through the copy-out: parallel sweeps share

data/lib/hecks/rust_build/prebuilt_binary.rb

@@ -10,13 +10,13 @@ module Hecks
   module RustBuild
     # A binary hecks has already compiled and published, named by what went into it (ADR 0110).
     #
-    # The `PrebuiltBinary` rows of the Vocabulary chapter say which binaries are published: the
+    # The `PrebuiltBinary` rows of the Vocabulary bluebook say which binaries are published: the
     # crate to key, the Cargo binary, the target it is built for. A release tagged `<name>-<key>`
     # holds the binary and its `.sha256`; the key is a hash of the crate's build inputs, so the
     # same bytes are the same release, whichever commit they come from. `fetch` downloads it and
     # checks its hash, and answers nil on any miss (not published yet, no network, a hash that
-    # does not match) so a caller compiles as it always did. `HECKS_PREBUILT=off` turns the
-    # download off.
+    # does not match) so a caller compiles as it always did. `--no-prebuilt` on the host build
+    # turns the download off.
     module PrebuiltBinary
       # Where releases are published.
       REPOSITORY = "heckslabs/hecks"
@@ -36,6 +36,26 @@ module Hecks
           raise KeyError, "no PrebuiltBinary row named #{name.inspect}"
       end
 
+      # @param crate [String] a row's crate, the directory under the checkout (`rust/host`)
+      # @param target [String] the triple the caller builds for
+      # @return [String, nil] the name of the row that publishes the crate for the target,
+      #   nil when none does
+      def name_for(crate, target)
+        found = Hecks::Vocabulary.rows("PrebuiltBinary").find { |row| row["crate"] == crate && row["target"] == target }
+        found&.fetch("name")
+      end
+
+      # @param crate [String] a row's crate
+      # @param crate_dir [String] the crate's directory
+      # @param target [String] the triple the caller builds for
+      # @param into [String] the file to write the binary to
+      # @return [String, nil] `into`, or nil when no row publishes the crate for the target
+      #   or `fetch` misses
+      def fetch_for(crate, crate_dir, target:, into:, allowed: true)
+        name = name_for(crate, target) or return
+        fetch(name, crate_dir, target: target, into: into, allowed: allowed)
+      end
+
       # @param crate_dir [String] the crate's directory
       # @return [String] a hash of every file that goes into the build: each path and its bytes, in
       #   path order, so it does not depend on the checkout it is read from
@@ -66,8 +86,8 @@ module Hecks
       # @param into [String] the file to write the binary to
       # @return [String, nil] `into`, or nil when the binary is not published for this target or
       #   could not be fetched and verified
-      def fetch(name, crate_dir, target:, into:)
-        return if ENV["HECKS_PREBUILT"] == "off" || row(name)["target"] != target
+      def fetch(name, crate_dir, target:, into:, allowed: true)
+        return if !allowed || row(name)["target"] != target
 
         body = verified(name, crate_dir) or return
         FileUtils.mkdir_p(File.dirname(into))

data/lib/hecks/rust_build/project_rust/codegen_run.rb

@@ -14,8 +14,8 @@ module Hecks
       class CodegenRun
         META_LABEL = "the self-hosted language (lib/hecks/language/bluebook)"
 
-        # One chapter's IR, generated into its own module.
-        Chapter = Struct.new(:mod_name, :label, :ir)
+        # One bluebook's IR, generated into its own module.
+        Declaration = Struct.new(:mod_name, :label, :ir)
 
         # The `hecks-codegen` crate: the workspace's own copy when it carries one (a packaged
         # workspace does), otherwise the checkout's, so a scratch crate holding only the generated
@@ -41,14 +41,15 @@ module Hecks
 
         # @param rust_dir [String] the workspace being generated into
         # @param out_root [String] the crate's `src/generated`
-        # @param target [Chapter] the domain being projected
-        # @param chapters [Array<Chapter>] every other bluebook the target attached
-        # @param meta [Hash] the self-hosted language's IR
-        def initialize(rust_dir:, out_root:, target:, chapters:, meta:)
+        # @param target [Bluebook] the domain being projected
+        # @param bluebooks [Array<Bluebook>] every other bluebook the target attached
+        # @param meta [Hash, nil] the self-hosted language's IR; nil leaves the `meta/` module as an
+        #   earlier run wrote it
+        def initialize(rust_dir:, out_root:, target:, declarations:, meta:)
           @rust_dir = rust_dir
           @out_root = out_root
           @target = target
-          @chapters = chapters
+          @declarations = declarations
           @meta = meta
         end
 
@@ -59,7 +60,7 @@ module Hecks
           Dir.mktmpdir("hecks-codegen-full") do |tmp|
             stage = File.join(tmp, "generated")
             FileUtils.mkdir_p(stage)
-            generate_meta(stage, tmp)
+            generate_meta(stage, tmp) if @meta
             generate_target(stage, tmp)
             sync(stage)
           end
@@ -81,8 +82,8 @@ module Hecks
 
         def generate_target(stage, tmp)
           args = [stage, @target.mod_name, @target.label, write_ir(tmp, @target.mod_name, @target.ir)]
-          @chapters.each do |chapter|
-            args.push(chapter.mod_name, chapter.label, write_ir(tmp, chapter.mod_name, chapter.ir))
+          @declarations.each do |declaration|
+            args.push(declaration.mod_name, declaration.label, write_ir(tmp, declaration.mod_name, declaration.ir))
           end
           run("full", *args)
         end

data/lib/hecks/rust_build/project_rust/domain_loader.rb

@@ -10,6 +10,9 @@ module Hecks
         FRAMEWORK_FILES = %w[ports/persistence.port ports/extraction.port adapters/driven/memory.adapter
                              adapters/driven/prism.adapter adapters/driven/postgres_era.adapter].freeze
 
+        # A `runs` line in an `.adapter` file: the adapter is a wasm plugin.
+        RUNS_LINE = /^\s*runs\s/
+
         # @return [Hecks::Runtime::Registry] the registry the domain was loaded into
         attr_reader :registry
 
@@ -26,7 +29,7 @@ module Hecks
         end
 
         # `root:` is the domain's own directory: a domain that declares `attaches ... from: :vendor`
-        # resolves its vendored chapters beneath it.
+        # resolves its vendored bluebooks beneath it.
         #
         # @return [DomainLoader] self, with the registry loaded
         def call
@@ -35,6 +38,7 @@ module Hecks
             load_framework
             Hecks::Adapters::Folder.new.load_bluebooks(@bluebook_dir)
             load_siblings
+            load_plugins
             load_environment
           end
           @domain_name = @registry.bluebooks.keys.first
@@ -48,7 +52,7 @@ module Hecks
           FRAMEWORK_FILES.each { |file| Kernel.load(File.join(lib, file)) }
         end
 
-        # Translation edges, hecksagons (whose `attaches` loads a framework chapter into the
+        # Translation edges, hecksagons (whose `attaches` loads a framework bluebook into the
         # same registry) and worlds (whose `default_adapter` binds what a hecksagon leaves out), in
         # the order the language loads them.
         def load_siblings
@@ -57,6 +61,15 @@ module Hecks
           Dir.glob(File.join(@bluebook_dir, "*.world")).each { |file| Kernel.load(file) }
         end
 
+        # The domain's own wasm plugins, so the IR carries them to the host: only an `.adapter`
+        # that `runs` a module, since the build needs no Ruby adapter and its code may need gems
+        # the build does not have. A vendored package's plugins load with its bluebook.
+        def load_plugins
+          Dir.glob(File.join(@bluebook_dir, "{,adapters/}*.adapter")).each do |file|
+            Kernel.load(file) if File.read(file).match?(RUNS_LINE)
+          end
+        end
+
         # Production is the default environment when `environments/production.hecksagon` exists
         # (`rust/host` is the production runtime); `HECKS_PROJECT_ENVIRONMENT` overrides it.
         def load_environment

data/lib/hecks/rust_build/project_rust/root_mod/notes.rb

@@ -18,7 +18,7 @@ module Hecks
             "// every OTHER domain's `pub mod` unconditionally, so one domain's own",
             "// non-compiling generated code (a `has_many` field, before this fix)",
             "// broke every feature's build, not just its own. A shared FRAMEWORK",
-            "// chapter (governance/identity — no merged.rs of its own, so absent",
+            "// bluebook (governance/identity — no merged.rs of its own, so absent",
             "// from `domains`) stays unconditional: it has no single feature of its",
             "// own to gate behind, and is compiled in by whichever domain(s) attach",
             "// it via `attaches`."

data/lib/hecks/rust_build/project_rust/target_ir.rb

@@ -9,9 +9,9 @@ module Hecks
       # facts, so `bluebook.to_h` never mentions them).
       class TargetIr
         # The optional attachments `rust/host` reads from `ir.json`, each omitted when nothing
-        # attached provides it: exporter method, then the key it is written under.
-        SEAMS = %i[authorization membership identity newsletter newsletter_issues payments
-                   registrations payment_connection checkout].freeze
+        # attached provides it: exporter method, then the key it is written under. `provides`
+        # holds every capability a package declares, by name.
+        SEAMS = %i[authorization membership identity provides].freeze
 
         # Round-trips a value through JSON so generators see the string-keyed shape a real
         # `ir.json` carries, never live Ruby symbols.
@@ -39,6 +39,7 @@ module Hecks
           add_persistence_wiring(ir, exporter)
           add_seams(ir, exporter)
           add_edges_and_source(ir)
+          add_plugins(ir, exporter)
           ir
         end
 
@@ -52,6 +53,14 @@ module Hecks
 
         def shaped(payload) = self.class.json_shaped(payload)
 
+        # The wasm plugins the host runs for queries no hecksagon binds; none, no key.
+        #
+        # @return [void]
+        def add_plugins(document, exporter)
+          plugins = exporter.plugins(@registry)
+          document[:plugins] = shaped(plugins) unless plugins.empty?
+        end
+
         # The bound persistence adapters' declarations, from the `.adapter` files under the
         # source root's `lib/` and the domain's own directory, so the host can look them up.
         def adapters(exporter, persistence)

data/lib/hecks/rust_build/project_rust.rb

@@ -22,18 +22,25 @@ module Hecks
     # The era plugin is required unconditionally so the generator works for any domain, lineage
     # capable or not; `pg` stays lazy inside it, so nothing here opens a database connection.
     class ProjectRust
-      # @param argv [Array<String>] the domain's directory
+      # The flag that leaves the self-hosted language's `meta/` module as it is: every domain
+      # writes the same one, so a run over many domains asks for it once.
+      SKIP_META = "--skip-meta"
+
+      # @param argv [Array<String>] the domain's directory, and `--skip-meta` to leave `meta/` alone
       # @return [Integer] the exit status
       # @raise [Failure] when the domain's name cannot be a Rust module and Cargo feature name
       def self.call(argv)
-        domain = argv.first or raise Failure, "usage: hecks project_rust <domain>"
-        new(domain).call
+        flags, paths = argv.partition { |arg| arg == SKIP_META }
+        domain = paths.first or raise Failure, "usage: hecks project_rust <domain> [#{SKIP_META}]"
+        new(domain, skip_meta: !flags.empty?).call
       end
 
       # @param domain [String] the domain's directory
-      def initialize(domain)
+      # @param skip_meta [Boolean] leave the `meta/` module as an earlier run wrote it
+      def initialize(domain, skip_meta: false)
         @domain = domain
         @mod_name = File.basename(domain)
+        @skip_meta = skip_meta
       end
 
       # @return [Integer] the exit status
@@ -71,7 +78,7 @@ module Hecks
       end
 
       def prepare_output
-        @rust_dir = ENV.fetch("HECKS_RUST_DIR", File.join(RustBuild::ROOT, "rust"))
+        @rust_dir = RustBuild.rust_dir
         @out_root = File.join(@rust_dir, "src/generated")
         FileUtils.mkdir_p(@out_root)
       end
@@ -79,31 +86,38 @@ module Hecks
       # `hecks-codegen` is the generator; this process only builds the IR it reads from the live
       # registry, so a domain's persistence, seams, translations and source text reach `ir.json`.
       def generate_with_codegen
-        meta = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
         CodegenRun.new(
-          rust_dir: @rust_dir, out_root: @out_root, meta: TargetIr.json_shaped(meta), chapters: chapters,
-          target: CodegenRun::Chapter.new(@mod_name, @domain, @ir)
+          rust_dir: @rust_dir, out_root: @out_root, meta: meta_ir, declarations: declarations,
+          target: CodegenRun::Declaration.new(@mod_name, @domain, @ir)
         ).call
       end
 
-      def chapters
+      # @return [Hash, nil] the self-hosted language's IR, or nil when `--skip-meta` leaves it be
+      def meta_ir
+        return nil if @skip_meta
+
+        meta = Hecks::Projector::Exporter.call(Hecks::Bluebook::MetaValidator.grammar_registry).fetch("Bluebook")
+        TargetIr.json_shaped(meta)
+      end
+
+      def declarations
         vendored = @registry.hecksagons.values.flat_map(&:vendored_packages)
         (@registry.bluebooks.keys - [@domain_name]).map do |name|
           ir = Hecks::Projector::Exporter.call(@registry).fetch(name)
           label = "#{@domain} (#{attachment(name, vendored)})"
-          CodegenRun::Chapter.new(name.downcase, label, TargetIr.json_shaped(ir))
+          CodegenRun::Declaration.new(name.downcase, label, TargetIr.json_shaped(ir))
         end
       end
 
-      # How the target attached a chapter, across every hecksagon the registry loaded: a chapter a
+      # How the target attached a bluebook, across every hecksagon the registry loaded: a bluebook a
       # sibling hecksagon vendors in is labelled as vendored.
-      def attachment(chapter_name, vendored)
-        name = vendored.find { |candidate| Hecks::Naming.pascal(candidate.to_s) == chapter_name }
-        name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{chapter_name.inspect}"
+      def attachment(declaration_name, vendored)
+        name = vendored.find { |candidate| Hecks::Naming.pascal(candidate.to_s) == declaration_name }
+        name ? "attaches #{name.inspect}, from: :vendor" : "attaches #{declaration_name.inspect}"
       end
 
       # `src/generated/mod.rs`: every domain ever generated, scanned off disk. A directory is a
-      # selectable domain exactly when it carries its own `merged.rs`; a framework chapter has
+      # selectable domain exactly when it carries its own `merged.rs`; a framework bluebook has
       # none and is always compiled in.
       def write_root_mod
         all_dirs = Dir.children(@out_root).select { |name| File.directory?(File.join(@out_root, name)) }.sort
@@ -121,9 +135,9 @@ module Hecks
       def sync_cargo_features
         path = File.join(@rust_dir, "Cargo.toml")
         manifest = File.read(path)
-        manifest = manifest.sub(/\A/, FEATURES_HEADER) unless manifest.include?("[features]")
+        manifest = "#{FEATURES_HEADER}#{manifest}" unless manifest.include?("[features]")
         @domains.each { |name| manifest = add_feature(manifest, name) }
-        manifest = manifest.sub(/^default\s*=.*$/, "default = [#{@mod_name.inspect}]")
+        manifest = manifest.sub(DEFAULT_FEATURE, "default = [#{@mod_name.inspect}]")
         # An unchanged manifest is not rewritten: a new mtime makes Cargo rebuild the whole crate.
         if WriteIfChanged.call(path, manifest)
           puts "wrote #{path} (default feature: #{@mod_name})"
@@ -135,10 +149,10 @@ module Hecks
       # Checked against the `[features]` table only: `[package]`'s `name` or a `[[bin]]` path can
       # share a word with a domain name.
       def add_feature(manifest, name)
-        table = manifest[/^\[features\](?:\n(?!\[).*)*$/] || ""
+        table = manifest[FEATURES_TABLE] || ""
         return manifest if table =~ /^#{Regexp.escape(name)}\s*=/
 
-        manifest.sub(/^default\s*=.*$/) { "#{Regexp.last_match(0)}\n#{name} = []" }
+        manifest.sub(DEFAULT_FEATURE) { "#{Regexp.last_match(0)}\n#{name} = []" }
       end
 
       FEATURES_HEADER = <<~TOML
@@ -154,6 +168,12 @@ module Hecks
 
       TOML
       private_constant :FEATURES_HEADER
+
+      # The `default = [...]` line of a Cargo manifest's `[features]` table.
+      DEFAULT_FEATURE = /^default\s*=.*$/
+      # The `[features]` table of a Cargo manifest, up to the next table header.
+      FEATURES_TABLE = /^\[features\](?:\n(?!\[).*)*$/
+      private_constant :DEFAULT_FEATURE, :FEATURES_TABLE
     end
   end
 end

data/lib/hecks/rust_build/target_dir.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require_relative "../rust_build"
+
+module Hecks
+  module RustBuild
+    # Where Cargo writes a crate's build output.
+    #
+    # A checkout of hecks builds into the crate's own `target/`. An installed copy (a gem, or a
+    # bundler checkout of a git revision) sits under `Gem.path`, where every new revision is a new
+    # directory, so a build there goes to one shared cache instead: each revision reuses the last
+    # one's compiled dependencies, and the output is kept once rather than once per revision.
+    # `CARGO_TARGET_DIR` overrides both.
+    module TargetDir
+      module_function
+
+      # @param crate_dir [String] the crate's directory
+      # @param root [String] the hecks copy the crate belongs to
+      # @return [String] the directory Cargo writes the crate's output to
+      def for(crate_dir, root: ROOT)
+        ENV.fetch("CARGO_TARGET_DIR") do
+          installed?(root) ? shared(File.basename(crate_dir)) : File.join(crate_dir, "target")
+        end
+      end
+
+      # @param root [String] a hecks copy's directory
+      # @return [Boolean] whether the copy is installed under one of RubyGems' directories
+      def installed?(root)
+        Gem.path.any? { |dir| File.expand_path(root).start_with?(File.join(File.expand_path(dir), "")) }
+      end
+
+      # @param name [String] the crate's name
+      # @return [String] the crate's directory in the per-user cache
+      #   (`XDG_CACHE_HOME`, else `~/.cache`)
+      def shared(name)
+        File.join(ENV.fetch("XDG_CACHE_HOME", File.join(Dir.home, ".cache")), "hecks", "cargo-target", name)
+      end
+    end
+  end
+end

data/lib/hecks/rust_build/wasm.rb

@@ -3,6 +3,7 @@
 require "fileutils"
 require_relative "../rust_build"
 require_relative "project_rust"
+require_relative "command_schemas"
 
 module Hecks
   module RustBuild
@@ -15,7 +16,7 @@ module Hecks
     # `wasmtime run rust/dist/<domain>.wasm < script.json`, and the domain's `ir.json` beside it,
     # which `rust/host` reads at runtime. `HECKS_RUST_DIR` names the workspace to build in and
     # `CARGO_TARGET_DIR` where build output goes, beside the workspace by default.
-    # `HECKS_WASM_PROFILE=dev` builds without `--release`: a much faster compile, for tests that
+    # `--profile=dev` builds without `--release`: a much faster compile, for tests that
     # only run the module, not for one that ships.
     module Wasm
       # The Cargo target the module is built for.
@@ -26,25 +27,43 @@ module Hecks
 
       module_function
 
-      # @param argv [Array<String>] the domain's directory
+      # @param argv [Array<String>] the domain's directory, then an optional `--profile=release|dev`
       # @return [Integer] the exit status
-      # @raise [Failure] when the target is not installed or a step fails
+      # @raise [Failure] when the target is not installed, the profile is unknown or a step fails
       def call(argv)
-        domain = argv.first or raise Failure, "usage: hecks build_wasm <domain>"
+        domain = argv.find { |arg| !arg.start_with?("--") } or raise Failure, "usage: hecks build_wasm <domain>"
+        name = profile_name(argv)
+        profile(name)
 
         require_target!
         rust_dir = RustBuild.rust_dir
         scratch = scratch_copy(rust_dir)
         regenerate(scratch, domain)
-        compile(scratch)
-        publish(scratch, rust_dir, File.basename(domain))
+        compile(scratch, name)
+        publish(scratch, rust_dir, File.basename(domain), name)
         0
       end
 
+      # @param argv [Array<String>] the tool's arguments
+      # @return [String] the `--profile=<name>` value, `release` when none is named
+      def profile_name(argv)
+        argv.filter_map { |arg| arg.delete_prefix("--profile=") if arg.start_with?("--profile=") }.last || "release"
+      end
+
       def regenerate(scratch, domain)
         puts "== regenerating #{scratch}/src/generated/ for #{domain} =="
-        status = RustBuild.with_env("HECKS_RUST_DIR" => scratch) { ProjectRust.call([domain]) }
+        status = RustBuild.in_workspace(scratch) { ProjectRust.call([domain]) }
         raise Failure, "project_rust failed for #{domain}" unless status.zero?
+
+        write_schemas(scratch, domain)
+      end
+
+      # The command schemas go into the scratch copy only: they are a build output for the host to
+      # serve, not part of the generated corpus the drift check holds to the tree.
+      def write_schemas(scratch, domain)
+        loader = ProjectRust::DomainLoader.new(domain).call
+        CommandSchemas.write(loader.registry.bluebook(loader.domain_name),
+                             File.join(scratch, "src", "generated", File.basename(domain)))
       end
 
       def require_target!
@@ -62,40 +81,40 @@ module Hecks
       # Built in a scratch copy because generating rewrites `Cargo.toml` and `src/generated/`,
       # which would dirty tracked files in a checkout.
       def scratch_copy(rust_dir, name = "project_wasm")
-        scratch = if ENV.key?("HECKS_RUST_DIR")
+        scratch = if RustBuild.explicit_workspace?
                     File.join(rust_dir, "scratch", name)
                   else
                     File.join(ROOT, "tmp", name, "rust")
                   end
         FileUtils.rm_rf(scratch)
         FileUtils.mkdir_p(scratch)
-        %w[Cargo.toml Cargo.lock src].each { |entry| FileUtils.cp_r(File.join(rust_dir, entry), scratch) }
+        %w[Cargo.toml Cargo.lock src expr].each { |entry| FileUtils.cp_r(File.join(rust_dir, entry), scratch) }
         scratch
       end
 
       # `rustup run`, not bare `cargo`: a `cargo` earlier on PATH may never have seen
       # `rustup target add` and fail with "can't find crate for `std`".
-      def compile(scratch)
-        flags = profile.fetch(:flags)
+      def compile(scratch, profile_name = "release")
+        flags = profile(profile_name).fetch(:flags)
         puts "== cargo build #{flags.join(" ")} --target #{TARGET} =="
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(RustBuild.rust_dir, "target"))
         RustBuild.command!("rustup", "run", "stable", "cargo", "build", *flags, "--target", TARGET,
                            chdir: scratch, env: { "CARGO_TARGET_DIR" => target_dir })
       end
 
-      # @return [Hash] the flags and directory of the profile `HECKS_WASM_PROFILE` names
+      # @param name [String] `release` or `dev`
+      # @return [Hash] the flags and directory of the profile
       # @raise [Failure] when the name is not `release` or `dev`
-      def profile
-        name = ENV.fetch("HECKS_WASM_PROFILE", "release")
-        PROFILES.fetch(name) { raise Failure, "HECKS_WASM_PROFILE=#{name} is not release or dev" }
+      def profile(name = "release")
+        PROFILES.fetch(name) { raise Failure, "--profile=#{name} is not release or dev" }
       end
 
-      def publish(scratch, rust_dir, name)
+      def publish(scratch, rust_dir, name, profile_name = "release")
         dist = File.join(rust_dir, "dist")
         FileUtils.mkdir_p(dist)
         target_dir = ENV.fetch("CARGO_TARGET_DIR", File.join(rust_dir, "target"))
         out = File.join(dist, "#{name}.wasm")
-        FileUtils.cp(File.join(target_dir, TARGET, profile.fetch(:dir), "rust.wasm"), out)
+        FileUtils.cp(File.join(target_dir, TARGET, profile(profile_name).fetch(:dir), "rust.wasm"), out)
         puts "wrote #{out}"
         puts %(run it: wasmtime run #{out} < script.json)
         publish_sidecar(scratch, dist, name)
@@ -107,6 +126,16 @@ module Hecks
 
         FileUtils.cp(sidecar, File.join(dist, "#{name}.ir.json"))
         puts "wrote #{File.join(dist, "#{name}.ir.json")}"
+        publish_schemas(scratch, dist, name)
+      end
+
+      # The command schemas beside the IR, which the host serves at a command's `?schema=1`.
+      def publish_schemas(scratch, dist, name)
+        schemas = File.join(scratch, "src", "generated", name, "schemas.json")
+        return unless File.exist?(schemas)
+
+        FileUtils.cp(schemas, File.join(dist, "#{name}.schemas.json"))
+        puts "wrote #{File.join(dist, "#{name}.schemas.json")}"
       end
     end
   end

data/lib/hecks/rust_build/wasm_browser.rb

@@ -19,6 +19,12 @@ module Hecks
       # The Cargo target the module is built for.
       TARGET = "wasm32-unknown-unknown"
 
+      # The exact wasm-bindgen pin in a Cargo manifest, capturing the version.
+      BINDGEN_PIN = /^wasm-bindgen = "=(.+)"/
+
+      # A dotted version number, as `wasm-bindgen --version` prints it.
+      VERSION_NUMBER = /[\d.]+/
+
       module_function
 
       # @param argv [Array<String>] the domain's directory
@@ -66,9 +72,9 @@ module Hecks
       # The wasm-bindgen CLI must match the crate version pinned in `rust/web/Cargo.toml`; a
       # mismatch fails only when the CLI runs, so the pin is read back, not hardcoded.
       def require_cli!(web_dir)
-        pinned = File.read(File.join(web_dir, "Cargo.toml"))[/^wasm-bindgen = "=(.+)"/, 1] or
+        pinned = File.read(File.join(web_dir, "Cargo.toml"))[BINDGEN_PIN, 1] or
           raise Failure, "rust/web/Cargo.toml: couldn't find a pinned (\"=x.y.z\") wasm-bindgen version"
-        installed = `wasm-bindgen --version 2>/dev/null`[/[\d.]+/]
+        installed = `wasm-bindgen --version 2>/dev/null`[VERSION_NUMBER]
         return if installed == pinned
 
         raise Failure, <<~MSG