hecks 3.0.4 → 3.1.0

data/rust/build/src/resolve.rs

@@ -77,12 +77,45 @@ pub fn grammar_files(root: &Path) -> Result<Vec<PathBuf>, String> {
     bluebook_files(&dir)
 }
 
-pub fn resolve_uses_framework(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
-    resolve_json(parser_bin, chapter_name, hecksagon_path, "uses_framework")
+// The names `attaches "Name"` gave, for a chapter the gem carries.
+pub fn resolve_gem_chapters(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
+    resolve_json(parser_bin, chapter_name, hecksagon_path, "gem_chapters")
 }
 
-pub fn resolve_uses_embryonaut_bluebook(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
-    resolve_json(parser_bin, chapter_name, hecksagon_path, "uses_embryonaut_bluebook")
+// The names `attaches "name", from: :vendor` gave, for a vendored package.
+pub fn resolve_vendored_packages(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path) -> Result<Vec<String>, String> {
+    resolve_json(parser_bin, chapter_name, hecksagon_path, "vendored_packages")
+}
+
+// Where the gem keeps the chapters other than framework members, relative to `lib/hecks`; the
+// same places `Hecks::Chapters::GLOBS` lists.
+const OTHER_GEM_CHAPTER_DIRS: &[&str] = &["language", "grammar", "tenancy/bluebook", "deploy/bluebook", "quality_control"];
+
+// The names of the chapters the gem carries beside the framework members, found by reading each
+// file's header. Only the Ruby runtime loads them, so the build uses this list to tell a real
+// gem chapter from a misspelt name.
+pub fn other_gem_chapter_names(root: &Path) -> Result<Vec<String>, String> {
+    fn walk(directory: &Path, names: &mut Vec<String>) -> Result<(), String> {
+        let Ok(entries) = std::fs::read_dir(directory) else { return Ok(()) };
+        for entry in entries {
+            let path = entry.map_err(|e| format!("reading {}: {e}", directory.display()))?.path();
+            if path.is_dir() {
+                walk(&path, names)?;
+            } else if path.extension().and_then(|e| e.to_str()) == Some("bluebook") {
+                if let Ok(name) = header_chapter_name(&path) {
+                    names.push(name);
+                }
+            }
+        }
+        Ok(())
+    }
+    let mut names = Vec::new();
+    for directory in OTHER_GEM_CHAPTER_DIRS {
+        walk(&root.join("lib/hecks").join(directory), &mut names)?;
+    }
+    names.sort();
+    names.dedup();
+    Ok(names)
 }
 
 fn resolve_json(parser_bin: &Path, chapter_name: &str, hecksagon_path: &Path, key: &str) -> Result<Vec<String>, String> {
@@ -105,13 +138,13 @@ pub fn valid_package_name(name: &str) -> bool {
 pub fn vendored_bluebook_files(domain: &Path, pkg_name: &str) -> Result<Vec<PathBuf>, String> {
     if !valid_package_name(pkg_name) {
         return Err(format!(
-            "uses_embryonaut_bluebook {pkg_name:?} is not a package name — it must match [a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
+            "attaches {pkg_name:?}, from: :vendor is not a package name — it must match [a-z][a-z0-9_]* (the name `hecks vendor` accepts)"
         ));
     }
     let dir = domain.join("vendor").join("embryonaut_bluebooks").join(pkg_name).join("bluebook");
     if !dir.is_dir() {
         return Err(format!(
-            "uses_embryonaut_bluebook {pkg_name:?} names no vendored bluebook at {} — run hecks vendor {pkg_name}",
+            "attaches {pkg_name:?}, from: :vendor names no vendored bluebook at {} — run hecks vendor {pkg_name}",
             dir.display()
         ));
     }

data/rust/host/HECKS_RELEASE

@@ -1 +1 @@
-3.0.4
+3.1.0

data/rust/host/src/api.rs

@@ -780,7 +780,7 @@ async fn presentation_save(
 const PRESENTATION_WRITE_REFUSAL: &str =
     "this host's kernel carries no ConsoleSettings chapter, so it has no StateStyle/Collection/Overview \
      commands to dispatch, and writing the rows behind its back would skip the invariants those commands \
-     enforce. Attach it with `uses_framework \"ConsoleSettings\"` in this domain's own .hecksagon and \
+     enforce. Attach it with `attaches \"ConsoleSettings\"` in this domain's own .hecksagon and \
      rebuild the kernel, or save from the Ruby console engine instead.";
 
 // ---- response envelopes ---------------------------------------------

data/rust/host/src/dispatch.rs

@@ -31,7 +31,9 @@ pub const ANONYMOUS_ROLE: &str = "Anonymous";
 pub enum Enforcement {
     /// A caller with no role is unchecked, as before.
     Off,
-    /// An unidentified or unassigned caller is let through and logged as `would_refuse_role`.
+    /// An unidentified or unassigned caller is let through and logged as `would_refuse_role`; a
+    /// caller that states a role is checked exactly as under `Enforce`, so shadow never accepts
+    /// what `Off` would not.
     Shadow,
     /// An unidentified or unassigned caller is refused.
     Enforce,
@@ -62,6 +64,15 @@ impl Enforcement {
     }
 }
 
+/// Where a dispatch comes from. A host-internal dispatch is the host acting on its own behalf (a
+/// signup, a provisioning step, a presentation write); it names no caller and is never subject to
+/// `HECKS_ROLE_ENFORCEMENT`, which guards what callers outside the host may do.
+#[derive(Clone, Copy, Debug, PartialEq)]
+enum Origin {
+    External,
+    HostInternal,
+}
+
 /// Whether the kernel refused the command for the caller's role.
 fn refused_for_role(result: &serde_json::Value) -> bool {
     result.get("refusals").and_then(|r| r.as_array()).is_some_and(|all| {
@@ -189,6 +200,10 @@ pub async fn handle_facts_as(
 // `role` is optional, matching `Adapters::Lambda::Client#dispatch`'s own
 // `role: nil` default: a step with no role looks the same on the wire
 // whether or not a caller is bound.
+//
+// This entry point and `handle_facts`/`handle_routed` are the host's own: a call with no role is a
+// host-internal dispatch and is unchecked in every enforcement mode. A call that names a role is
+// still checked against it. Callers outside the host go through the `_as` entry points.
 pub async fn handle(
     client: &Mutex<Client>,
     wasm_path: &Path,
@@ -198,7 +213,8 @@ pub async fn handle(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
-    handle_as(client, wasm_path, verb, args, Caller { role, actor_id: None }, config, invoker).await
+    let origin = if role.is_none() { Origin::HostInternal } else { Origin::External };
+    dispatch_in(Enforcement::from_env(), origin, client, wasm_path, verb, args, Caller { role, actor_id: None }, config, invoker).await
 }
 
 /// Dispatches for a caller, applying `HECKS_ROLE_ENFORCEMENT`: unidentified callers are refused (or,
@@ -212,12 +228,13 @@ pub async fn handle_as(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
-    handle_with(Enforcement::from_env(), client, wasm_path, verb, args, caller, config, invoker).await
+    dispatch_in(Enforcement::from_env(), Origin::External, client, wasm_path, verb, args, caller, config, invoker).await
 }
 
 #[allow(clippy::too_many_arguments)]
-async fn handle_with(
+async fn dispatch_in(
     mode: Enforcement,
+    origin: Origin,
     client: &Mutex<Client>,
     wasm_path: &Path,
     verb: &str,
@@ -226,9 +243,11 @@ async fn handle_with(
     config: &LineageConfig,
     invoker: &dyn LambdaInvoker,
 ) -> anyhow::Result<Outcome> {
-    let checked = mode.effective(caller);
+    let checked = if origin == Origin::HostInternal { caller } else { mode.effective(caller) };
     let outcome = run(client, wasm_path, verb, args.clone(), checked, config, invoker).await?;
-    if mode == Enforcement::Shadow && !outcome.accepted && refused_for_role(&outcome.result) {
+    // Only a caller that stated no role (unidentified, or an actor Governance holds no grant for)
+    // is let through; a stated role that does not match stays refused, as it is under `Off`.
+    if mode == Enforcement::Shadow && caller.role.is_none() && !outcome.accepted && refused_for_role(&outcome.result) {
         crate::log::error("would_refuse_role", serde_json::json!({
             "verb": verb, "role": checked.role, "actor_id": checked.actor_id,
             "refusals": outcome.result.get("refusals"),
@@ -287,6 +306,8 @@ async fn run(
     let mut args = args;
     if let Some(domain_ir) = crate::ir::ir() {
         crate::needs::fill_needs(domain_ir, verb, &mut args, &crate::needs::ProcessClock);
+        // An argument with a declared default is filled the same way, so the journal holds it too.
+        crate::needs::fill_defaults(domain_ir, verb, &mut args);
     }
     let mut step = serde_json::json!({ "verb": verb, "args": args.clone() });
     if let Some(role) = role {
@@ -330,6 +351,10 @@ async fn run(
         if table.as_object().is_some_and(|t| !t.is_empty()) {
             input["needs"] = table;
         }
+        let defaults = crate::needs::defaults_table(domain_ir);
+        if defaults.as_object().is_some_and(|t| !t.is_empty()) {
+            input["defaults"] = defaults;
+        }
     }
     let input = input.to_string();
     // `wasm_runner::run` is sync, and wasmtime-wasi's sync bridge spins up
@@ -1353,7 +1378,7 @@ pub(crate) mod tests {
             let client = &client;
             let config = &config;
             async move {
-                handle_with(mode, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
+                dispatch_in(mode, Origin::External, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
                     .await
                     .unwrap()
             }
@@ -1375,6 +1400,61 @@ pub(crate) mod tests {
         assert_eq!(steps.len(), 2, "the enforced refusal was not persisted; off and shadow were");
     }
 
+    // Shadow may only let through what Off would: a caller that stated a wrong role is refused.
+    #[tokio::test]
+    async fn shadow_refuses_a_stated_wrong_role_and_still_lets_an_unidentified_caller_through() {
+        let client = scratch_db("rust_host_dispatch_test_shadow_stated").await;
+        provision_lineage(&*client.lock().await, "Banking", 1, &["Customer"]).await;
+        let config = test_config("Banking", 1);
+        let go = |mode: Enforcement, origin: Origin, caller: Caller<'static>, id: &'static str| {
+            let client = &client;
+            let config = &config;
+            async move {
+                dispatch_in(mode, origin, client, &wasm_path(), "Banking::Customer.Register", register(id), caller, config, &lambda_client::NeverInvoker)
+                    .await
+                    .unwrap()
+            }
+        };
+        let wrong = Caller { role: Some("Auditor"), actor_id: None };
+
+        let shadow_wrong = go(Enforcement::Shadow, Origin::External, wrong, "CUST-0031").await;
+        assert!(!shadow_wrong.accepted, "shadow must not accept a stated wrong role: {:?}", shadow_wrong.result);
+        assert!(refused_for_role(&shadow_wrong.result), "{:?}", shadow_wrong.result);
+        let off_wrong = go(Enforcement::Off, Origin::External, wrong, "CUST-0032").await;
+        assert!(!off_wrong.accepted, "off refuses it too: {:?}", off_wrong.result);
+
+        let nobody = go(Enforcement::Shadow, Origin::External, Caller::default(), "CUST-0033").await;
+        assert!(nobody.accepted, "shadow lets an unidentified caller through: {:?}", nobody.result);
+
+        let steps = journal::load_steps(&*client.lock().await).await.unwrap();
+        assert_eq!(steps.len(), 1, "only the unidentified caller's registration was persisted");
+    }
+
+    // A host-internal dispatch names no caller and is unchecked in every mode, while an external
+    // unidentified caller is refused under enforce.
+    #[tokio::test]
+    async fn a_host_internal_dispatch_is_unchecked_under_enforce_but_an_external_one_is_refused() {
+        let client = scratch_db("rust_host_dispatch_test_internal").await;
+        provision_lineage(&*client.lock().await, "Banking", 1, &["Customer"]).await;
+        let config = test_config("Banking", 1);
+        let go = |mode: Enforcement, origin: Origin, id: &'static str| {
+            let client = &client;
+            let config = &config;
+            async move {
+                dispatch_in(mode, origin, client, &wasm_path(), "Banking::Customer.Register", register(id), Caller::default(), config, &lambda_client::NeverInvoker)
+                    .await
+                    .unwrap()
+            }
+        };
+
+        let external = go(Enforcement::Enforce, Origin::External, "CUST-0041").await;
+        assert!(!external.accepted, "{:?}", external.result);
+        for (mode, id) in [(Enforcement::Enforce, "CUST-0042"), (Enforcement::Shadow, "CUST-0043"), (Enforcement::Off, "CUST-0044")] {
+            let internal = go(mode, Origin::HostInternal, id).await;
+            assert!(internal.accepted, "{mode:?}: {:?}", internal.result);
+        }
+    }
+
     #[tokio::test]
     async fn a_mid_transaction_failure_rolls_back_any_saga_state_already_written() {
         // Deliberately doesn't provision "Transfer": its mutation fails

data/rust/host/src/needs.rs

@@ -110,6 +110,52 @@ pub fn table(domain_ir: &Value) -> Value {
     Value::Object(verbs)
 }
 
+/// The command's attributes that declare a default (`attribute :runs, Count, default: 30`), each
+/// with the declared value. An attribute whose default is null declares none.
+fn declared_defaults<'a>(domain_ir: &'a Value, verb: &str) -> Vec<(&'a str, &'a Value)> {
+    let Some((qualified_aggregate, command_name)) = verb.rsplit_once('.') else { return Vec::new() };
+    let aggregate = qualified_aggregate.rsplit("::").next().unwrap_or(qualified_aggregate);
+    let named = |value: &Value, name: &str| value.get("name").and_then(Value::as_str) == Some(name);
+    let list = |value: &'a Value, key: &str| -> Vec<&'a Value> {
+        value.get(key).and_then(Value::as_array).map(|a| a.iter().collect()).unwrap_or_default()
+    };
+    list(domain_ir, "aggregates")
+        .into_iter()
+        .filter(|a| named(a, aggregate))
+        .flat_map(|a| list(a, "commands"))
+        .filter(|c| named(c, command_name))
+        .flat_map(|c| list(c, "attributes"))
+        .filter_map(|a| {
+            let default = a.get("default").filter(|d| !d.is_null())?;
+            Some((a.get("name").and_then(Value::as_str)?, default))
+        })
+        .collect()
+}
+
+/// Every command's declared defaults as the kernel's input `"defaults"` reads them:
+/// `{ verb: { attribute: value } }`. The kernel fills a reaction's command from this the same way
+/// the host fills the outermost one.
+pub fn defaults_table(domain_ir: &Value) -> Value {
+    let domain = domain_ir.get("name").and_then(Value::as_str).unwrap_or_default();
+    let mut verbs = serde_json::Map::new();
+    let aggregates = domain_ir.get("aggregates").and_then(Value::as_array).into_iter().flatten();
+    for aggregate in aggregates {
+        let aggregate_name = aggregate.get("name").and_then(Value::as_str).unwrap_or_default();
+        for command in aggregate.get("commands").and_then(Value::as_array).into_iter().flatten() {
+            let command_name = command.get("name").and_then(Value::as_str).unwrap_or_default();
+            let verb = format!("{domain}::{aggregate_name}.{command_name}");
+            let defaults: serde_json::Map<String, Value> = declared_defaults(domain_ir, &verb)
+                .into_iter()
+                .map(|(name, value)| (name.to_string(), value.clone()))
+                .collect();
+            if !defaults.is_empty() {
+                verbs.insert(verb, Value::Object(defaults));
+            }
+        }
+    }
+    Value::Object(verbs)
+}
+
 /// The facts of a command invocation: the `with` object when the call carries one, else the
 /// flat object itself (the kernel's `CommandInvocation` reads both shapes).
 fn facts_mut(args: &mut Value) -> Option<&mut serde_json::Map<String, Value>> {
@@ -147,6 +193,22 @@ pub fn fill_needs(domain_ir: &Value, verb: &str, args: &mut Value, clock: &dyn C
     }
 }
 
+/// Gives each argument `verb` declares a default for, and `args` leaves out, that default, after
+/// `fill_needs` and before any gate reads the arguments. A key the caller supplied (even a null)
+/// is kept, as is a fact `fill_needs` already answered.
+pub fn fill_defaults(domain_ir: &Value, verb: &str, args: &mut Value) {
+    let defaults = declared_defaults(domain_ir, verb);
+    if defaults.is_empty() {
+        return;
+    }
+    let Some(facts) = facts_mut(args) else { return };
+    for (name, value) in defaults {
+        if !facts.contains_key(name) {
+            facts.insert(name.to_string(), value.clone());
+        }
+    }
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -240,4 +302,53 @@ mod tests {
         clear_fixed_clock();
         assert!(ProcessClock.now_secs() > 1_700_000_000);
     }
+
+    // A command with one defaulted attribute, one plain, and one whose default is null.
+    fn defaulted_ir() -> Value {
+        json!({"name": "Qc", "aggregates": [{"name": "Check", "commands": [
+            {"name": "Start", "attributes": [
+                {"name": "ref", "type": "Ref", "default": null},
+                {"name": "runs", "type": "Count", "default": 30},
+                {"name": "note", "type": "String", "default": null}
+            ], "needs": []}
+        ]}]})
+    }
+
+    #[test]
+    fn an_omitted_argument_is_filled_with_its_declared_default() {
+        let mut args = json!({"with": {"ref": {"value": "a"}}});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert_eq!(args["with"]["runs"], 30);
+        assert!(args["with"].get("note").is_none(), "a null default declares none");
+    }
+
+    #[test]
+    fn a_flat_invocation_gets_its_defaults_at_its_top_level() {
+        let mut args = json!({"ref": {"value": "a"}});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert_eq!(args["runs"], 30);
+    }
+
+    #[test]
+    fn a_supplied_argument_is_kept_even_when_null() {
+        let mut args = json!({"runs": null});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert!(args["runs"].is_null());
+        let mut args = json!({"runs": {"value": 7}});
+        fill_defaults(&defaulted_ir(), "Qc::Check.Start", &mut args);
+        assert_eq!(args["runs"], json!({"value": 7}));
+    }
+
+    #[test]
+    fn a_command_that_declares_no_default_is_untouched() {
+        let mut args = json!({"with": {}});
+        fill_defaults(&integer_ir(), "Qc::Check.Run", &mut args);
+        assert_eq!(args, json!({"with": {}}));
+    }
+
+    #[test]
+    fn the_kernel_table_lists_each_command_that_declares_a_default() {
+        assert_eq!(defaults_table(&defaulted_ir()), json!({"Qc::Check.Start": {"runs": 30}}));
+        assert_eq!(defaults_table(&integer_ir()), json!({}));
+    }
 }

data/rust/host/src/web/newsletter/template.rs

@@ -0,0 +1,69 @@
+// The optional branded confirmation email: an HTML template an operator
+// hosts, fetched at send time. Hecks ships no brand; with no template (or
+// any trouble with one) the caller keeps the plain-text body.
+use super::super::newsletter_send::personalize;
+use std::time::Duration;
+
+pub(super) const CONFIRM_TOKEN: &str = "{{CONFIRM_URL}}";
+const FETCH_TIMEOUT: Duration = Duration::from_secs(5);
+pub(super) const MAX_TEMPLATE_BYTES: usize = 256 * 1024;
+
+// Escapes a URL for an HTML attribute or text position.
+fn escape_html(value: &str) -> String {
+    value.replace('&', "&amp;").replace('<', "&lt;").replace('>', "&gt;").replace('"', "&quot;").replace('\'', "&#39;")
+}
+
+// Fills the placeholders with HTML-escaped URLs. `Err` names why the
+// template is unusable: without {{CONFIRM_URL}} the email would carry no
+// link. {{UNSUBSCRIBE_URL}} is optional. The result starts at its first
+// non-blank character so the mailer sends it as HTML.
+pub(super) fn fill_template(template: &str, confirm_url: &str, unsubscribe_url: &str) -> Result<String, &'static str> {
+    if !template.contains(CONFIRM_TOKEN) {
+        return Err("the template has no {{CONFIRM_URL}} placeholder");
+    }
+    let filled = template.replace(CONFIRM_TOKEN, &escape_html(confirm_url));
+    Ok(personalize(&filled, &escape_html(unsubscribe_url)).trim_start().to_string())
+}
+
+// Reads a response body, stopping as soon as it passes the cap.
+async fn read_capped(mut response: reqwest::Response) -> Result<String, String> {
+    let mut bytes: Vec<u8> = Vec::new();
+    while let Some(chunk) = response.chunk().await.map_err(|e| e.to_string())? {
+        bytes.extend_from_slice(&chunk);
+        if bytes.len() > MAX_TEMPLATE_BYTES {
+            return Err(format!("the template is larger than {MAX_TEMPLATE_BYTES} bytes"));
+        }
+    }
+    String::from_utf8(bytes).map_err(|_| "the template is not UTF-8".to_string())
+}
+
+// GETs the template (5 second timeout, size capped); a non-2xx answer or
+// any transport trouble is an `Err` with the reason.
+async fn fetch_template(url: &str) -> Result<String, String> {
+    let http = reqwest::Client::builder().timeout(FETCH_TIMEOUT).build().map_err(|e| e.to_string())?;
+    let response = http.get(url).send().await.map_err(|e| e.to_string())?;
+    if !response.status().is_success() {
+        return Err(format!("the template answered {}", response.status()));
+    }
+    read_capped(response).await
+}
+
+// The HTML body when NEWSLETTER_CONFIRMATION_TEMPLATE_URL names a usable
+// template; None (after logging why) when the caller should send plain text.
+pub(super) async fn branded_body(confirm_url: &str, unsubscribe_url: &str) -> Option<String> {
+    let url = std::env::var("NEWSLETTER_CONFIRMATION_TEMPLATE_URL").ok().filter(|u| !u.trim().is_empty())?;
+    let template = match fetch_template(url.trim()).await {
+        Ok(t) => t,
+        Err(e) => {
+            eprintln!("newsletter: the confirmation template could not be fetched ({e}), so the plain-text confirmation was sent");
+            return None;
+        }
+    };
+    match fill_template(&template, confirm_url, unsubscribe_url) {
+        Ok(body) => Some(body),
+        Err(e) => {
+            eprintln!("newsletter: the confirmation template was rejected ({e}), so the plain-text confirmation was sent");
+            None
+        }
+    }
+}

data/rust/host/src/web/newsletter/tests.rs

@@ -102,3 +102,46 @@ fn a_confirm_token_is_not_an_unsubscribe_token_and_the_reverse() {
     assert!(!unsubscribe_token_matches("s3cret-value", &confirm, "a@example.com"));
     assert!(!confirm_token_matches("s3cret-value", &unsubscribe, "a@example.com"));
 }
+
+use template::fill_template;
+
+const CONFIRM: &str = "https://example.com/newsletter-confirmed.html?email=a%40b.c&token=t";
+const UNSUBSCRIBE: &str = "https://example.com/newsletter-unsubscribed.html?email=a%40b.c&token=u";
+
+#[test]
+fn a_template_gets_the_confirm_link_in_place_of_its_placeholder() {
+    let body = fill_template("<p><a href=\"{{CONFIRM_URL}}\">Confirm</a></p>", CONFIRM, UNSUBSCRIBE).unwrap();
+    assert_eq!(body, "<p><a href=\"https://example.com/newsletter-confirmed.html?email=a%40b.c&amp;token=t\">Confirm</a></p>");
+}
+
+#[test]
+fn a_template_without_the_confirm_placeholder_is_rejected() {
+    assert!(fill_template("<p>{{UNSUBSCRIBE_URL}}</p>", CONFIRM, UNSUBSCRIBE).is_err());
+    assert!(fill_template("", CONFIRM, UNSUBSCRIBE).is_err());
+}
+
+#[test]
+fn the_unsubscribe_placeholder_is_optional_and_replaced_wherever_present() {
+    assert!(fill_template("<a href=\"{{CONFIRM_URL}}\">x</a>", CONFIRM, UNSUBSCRIBE).is_ok());
+    let body = fill_template("<a href=\"{{CONFIRM_URL}}\">x</a>{{UNSUBSCRIBE_URL}}|{{UNSUBSCRIBE_URL}}", CONFIRM, UNSUBSCRIBE).unwrap();
+    assert!(!body.contains("{{"));
+    assert_eq!(body.matches("newsletter-unsubscribed.html").count(), 2);
+}
+
+#[test]
+fn ampersands_and_quotes_in_a_url_are_escaped_inside_the_html() {
+    let body = fill_template("<a href=\"{{CONFIRM_URL}}\">x</a>", "https://e.com/?a=1&b=\"2\"<>'", UNSUBSCRIBE).unwrap();
+    assert_eq!(body, "<a href=\"https://e.com/?a=1&amp;b=&quot;2&quot;&lt;&gt;&#39;\">x</a>");
+}
+
+#[test]
+fn a_filled_template_starts_at_its_first_tag_so_the_mailer_sends_html() {
+    let body = fill_template("\n  <p>{{CONFIRM_URL}}</p>", CONFIRM, UNSUBSCRIBE).unwrap();
+    assert!(body.starts_with('<'));
+}
+
+#[test]
+fn without_a_template_the_plain_text_confirmation_is_unchanged() {
+    let body = confirmation_body(CONFIRM);
+    assert_eq!(body, format!("Please confirm your newsletter subscription by opening this link:\n\n{CONFIRM}\n\nIf you didn't ask for this, you can ignore this email and nothing will be sent to you.\n"));
+}

data/rust/host/src/web/newsletter.rs

@@ -14,6 +14,7 @@ use tokio::sync::Mutex;
 use tokio_postgres::Client;
 
 mod cooldown;
+mod template;
 #[cfg(test)]
 mod tests;
 
@@ -194,8 +195,12 @@ pub(super) async fn send_confirmation(email: &str) {
     let site = site_url();
     let link = confirm_url(&site, email, &confirm_token(&secret, email));
     let unsubscribe = unsubscribe_url(&site, email, &unsubscribe_token(&secret, email));
+    let body = match template::branded_body(&link, &unsubscribe).await {
+        Some(html) => html,
+        None => confirmation_body(&link),
+    };
     let delivery = mailer
-        .deliver(&Email { to: email, subject: "Confirm your newsletter subscription", body: &confirmation_body(&link), unsubscribe_url: Some(&unsubscribe) })
+        .deliver(&Email { to: email, subject: "Confirm your newsletter subscription", body: &body, unsubscribe_url: Some(&unsubscribe) })
         .await;
     if !delivery.ok {
         eprintln!("newsletter: the confirmation email was not delivered: {}", delivery.reason.unwrap_or_default());

data/rust/host/src/web/newsletter_send.rs

@@ -132,7 +132,7 @@ pub(super) fn unsubscribe_url(site_url: &str, email: &str, token: &str) -> Strin
     url.to_string()
 }
 
-fn personalize(body: &str, unsubscribe_url: &str) -> String {
+pub(super) fn personalize(body: &str, unsubscribe_url: &str) -> String {
     body.replace(UNSUBSCRIBE_TOKEN, unsubscribe_url)
 }
 

data/rust/parser/src/keywords.rs

@@ -182,9 +182,9 @@ pub static KEYWORDS: &[KeywordRow] = &[
     KeywordRow { word: "answers_query", context: "DomainPort", body: "none", inner: "", opens: "", fills: "answered_queries", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "hecksagon", context: "File", body: "keywords", inner: "Hecksagon", opens: "Hecksagon", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "subscribe", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "subscriptions", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "uses_framework", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "framework_members", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "vendored_bluebooks", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
-    KeywordRow { word: "attaches", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attached_chapters", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "attaches", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "uses_framework", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "uses_embryonaut_bluebook", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "attachments", status: "deprecated", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "port", context: "Hecksagon", body: "keywords", inner: "DomainPort", opens: "DomainPort", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "translates", context: "Hecksagon", body: "keywords", inner: "Policy", opens: "Policy", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "bounded", context: "Hecksagon", body: "none", inner: "", opens: "", fills: "", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
@@ -466,9 +466,10 @@ pub static ARGUMENTS: &[ArgumentRow] = &[
     ArgumentRow { keyword: "asks", context: "DomainPort", at: "", named: "to", kind: "constant", required: "false", fills: "to", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "hecksagon", context: "File", at: "1", named: "", kind: "text", required: "true", fills: "domain", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "subscribe", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "subscriptions", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "uses_framework", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "framework_members", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "vendored_bluebooks", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
-    ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attached_chapters", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "attaches", context: "Hecksagon", at: "", named: "from", kind: "symbol", required: "false", fills: "source", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "uses_framework", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "uses_embryonaut_bluebook", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "attachments", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "port", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "translates", context: "Hecksagon", at: "1", named: "", kind: "text", required: "true", fills: "name", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "reference_to", context: "PortOperation", at: "1", named: "", kind: "constant", required: "true", fills: "type", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },

data/rust/parser/src/main.rs

@@ -91,7 +91,8 @@ fn run_chapter(args: &[String]) -> Result<(), RunError> {
 }
 
 /// `hecks-parse resolve --chapter <Name> <file.hecksagon>`: prints that chapter's
-/// `uses_framework` and `uses_embryonaut_bluebook` names as JSON, in file order.
+/// `attaches` names as JSON, in file order: `gem_chapters` for a chapter the gem carries and
+/// `vendored_packages` for `from: :vendor`.
 ///
 /// `--chapter` is required because one file can hold several `Hecks.hecksagon` blocks.
 fn run_resolve(args: &[String]) -> Result<(), RunError> {
@@ -120,7 +121,7 @@ fn run_resolve(args: &[String]) -> Result<(), RunError> {
     let value = emit::JsonValue::Object(vec![
         ("domain".to_string(), emit::JsonValue::String(chapter_name)),
         (
-            "uses_framework".to_string(),
+            "gem_chapters".to_string(),
             emit::JsonValue::Array(
                 framework_names
                     .into_iter()
@@ -129,7 +130,7 @@ fn run_resolve(args: &[String]) -> Result<(), RunError> {
             ),
         ),
         (
-            "uses_embryonaut_bluebook".to_string(),
+            "vendored_packages".to_string(),
             emit::JsonValue::Array(
                 vendored_names
                     .into_iter()

data/rust/parser/src/parse/chapter.rs

@@ -306,7 +306,7 @@ pub fn parse_chapter(chapter_name: &str, files: &[(String, String)]) -> ParseRes
     Ok(bluebook)
 }
 
-/// Lists the chapters `<Name>`'s block pulls in via `uses_framework`/`uses_embryonaut_bluebook`.
+/// Lists the chapters `<Name>`'s block pulls in via `attaches` (or its deprecated spellings).
 /// Every block is still gated; the IR accumulator is a throwaway.
 pub fn resolve_hecksagon_dependencies(
     chapter_name: &str,