hecks 3.0.3 → 3.0.5

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/canonical.rs

@@ -1,5 +1,5 @@
 //! Source-body slicing and whitespace collapse, mirroring Ruby's `CanonicalForm`.
-//! Hand-mirrored from projection.json: a third rule there needs a matching rule here.
+//! Hand-mirrored from projection.json: a rule there (collapse_whitespace, replace, scale_call) needs a matching rule here.
 
 /// Slices the raw source between two byte offsets, before any normalisation.
 pub fn slice(source: &str, start: usize, end: usize) -> &str {
@@ -11,7 +11,87 @@ pub fn slice(source: &str, start: usize, end: usize) -> &str {
 pub fn apply(source: &str) -> String {
     let collapsed = map_outside_strings(source, collapse_whitespace);
     let replaced = map_outside_strings(&collapsed, |run| replace_word_boundary(run, ".length", ".size"));
-    replaced.trim().to_string()
+    let scaled = SCALE_CALLS.iter().fold(replaced, |text, (token, seconds)| {
+        map_outside_strings(&text, |run| scale_call(run, token, seconds))
+    });
+    scaled.trim().to_string()
+}
+
+/// The `scale_call` rows of projection.json, in position order: (call name, seconds per unit).
+const SCALE_CALLS: [(&str, &str); 3] = [("days", "86400"), ("hours", "3600"), ("minutes", "60")];
+
+/// Every normalisation row of projection.json as (strategy, source_token, replacement,
+/// boundary, position), in position order; emitted into the IR's expression table.
+pub const TABLE: [(&str, &str, &str, &str, &str); 5] = [
+    ("collapse_whitespace", "", "", "none", "1"),
+    ("replace", ".length", ".size", "word", "2"),
+    ("scale_call", "days", "86400", "word", "3"),
+    ("scale_call", "hours", "3600", "word", "4"),
+    ("scale_call", "minutes", "60", "word", "5"),
+];
+
+/// Folds `token(<whole number>)` into the number times `seconds`, as Ruby's `scale_call` does.
+/// The name must not follow a word character, digit, underscore or dot; spaces inside the
+/// parentheses are allowed; any other argument leaves the call as written.
+fn scale_call(text: &str, token: &str, seconds: &str) -> String {
+    let mut out = String::with_capacity(text.len());
+    let mut i = 0;
+    while i < text.len() {
+        if text[i..].starts_with(token) {
+            let preceded = text[..i]
+                .chars()
+                .next_back()
+                .map_or(false, |c| c.is_alphanumeric() || c == '_' || c == '.');
+            if !preceded {
+                if let Some((digits, len)) = whole_number_call(&text[i + token.len()..]) {
+                    out.push_str(&multiply(digits, seconds));
+                    i += token.len() + len;
+                    continue;
+                }
+            }
+        }
+        let ch = text[i..].chars().next().unwrap();
+        out.push(ch);
+        i += ch.len_utf8();
+    }
+    out
+}
+
+/// Matches `(` spaces digits spaces `)` at the start of `rest`; returns the digits and the
+/// matched length.
+fn whole_number_call(rest: &str) -> Option<(&str, usize)> {
+    let inner = rest.strip_prefix('(')?;
+    let digits_at = inner.len() - inner.trim_start_matches(char::is_whitespace).len();
+    let body = &inner[digits_at..];
+    let digit_len = body.bytes().take_while(|b| b.is_ascii_digit()).count();
+    if digit_len == 0 {
+        return None;
+    }
+    let tail = &body[digit_len..];
+    let close = tail.len() - tail.trim_start_matches(char::is_whitespace).len();
+    tail[close..].strip_prefix(')')?;
+    Some((&body[..digit_len], 1 + digits_at + digit_len + close + 1))
+}
+
+/// Decimal `digits` times the decimal `factor`, as text with no leading zeros (any length).
+fn multiply(digits: &str, factor: &str) -> String {
+    let factor: u32 = factor.parse().expect("scale factor is a whole number");
+    let mut carry = 0u32;
+    let mut out: Vec<u8> = Vec::with_capacity(digits.len() + 6);
+    for d in digits.bytes().rev() {
+        let v = (d - b'0') as u32 * factor + carry;
+        out.push(b'0' + (v % 10) as u8);
+        carry = v / 10;
+    }
+    while carry > 0 {
+        out.push(b'0' + (carry % 10) as u8);
+        carry /= 10;
+    }
+    while out.len() > 1 && out.last() == Some(&b'0') {
+        out.pop();
+    }
+    out.reverse();
+    String::from_utf8(out).unwrap()
 }
 
 /// Applies `transform` to the unquoted runs of `text` and copies quoted runs verbatim;
@@ -104,6 +184,61 @@ mod tests {
         assert_eq!(apply("lengthy"), "lengthy");
     }
 
+    #[test]
+    fn folds_duration_calls_into_seconds() {
+        assert_eq!(apply("days(730)"), "63072000");
+        assert_eq!(apply("days( 1 ) + hours(2) + minutes(15)"), "86400 + 7200 + 900");
+        assert_eq!(
+            apply("x.days(3) workdays(3) days(n) days(1.5)"),
+            "x.days(3) workdays(3) days(n) days(1.5)"
+        );
+        assert_eq!(apply("'days(2)' == days(0)"), "'days(2)' == 0");
+    }
+
+    /// Splits JSON text into its string literals, decoding escapes.
+    fn json_strings(text: &str) -> Vec<String> {
+        let mut out = Vec::new();
+        let mut chars = text.chars();
+        while let Some(c) = chars.next() {
+            if c != '"' {
+                continue;
+            }
+            let mut s = String::new();
+            while let Some(c) = chars.next() {
+                match c {
+                    '"' => break,
+                    '\\' => match chars.next().unwrap() {
+                        'n' => s.push('\n'),
+                        't' => s.push('\t'),
+                        'r' => s.push('\r'),
+                        'u' => {
+                            let hex: String = chars.by_ref().take(4).collect();
+                            s.push(char::from_u32(u32::from_str_radix(&hex, 16).unwrap()).unwrap());
+                        }
+                        other => s.push(other),
+                    },
+                    c => s.push(c),
+                }
+            }
+            out.push(s);
+        }
+        out
+    }
+
+    #[test]
+    fn matches_the_shared_canonical_form_cases() {
+        let path = concat!(env!("CARGO_MANIFEST_DIR"), "/../../spec/fixtures/canonical_form_cases.json");
+        let text = std::fs::read_to_string(path).expect("shared cases file");
+        let strings = json_strings(&text);
+        let start = strings.iter().position(|s| s == "cases").expect("cases key") + 1;
+        let rows: Vec<&[String]> = strings[start..].chunks(4).collect();
+        assert!(!rows.is_empty());
+        for row in rows {
+            assert_eq!((row[0].as_str(), row[2].as_str()), ("source", "canonical"));
+            assert_eq!(apply(&row[1]), row[3], "source {:?}", row[1]);
+        }
+    }
+
     #[test]
     fn slices_the_exact_source_span() {
         let source = "given(\"ok\") { balance >= amount }";

data/rust/parser/src/emit.rs

@@ -43,25 +43,20 @@ pub fn write(value: &JsonValue) -> String {
 /// The pinned `Expression::CanonicalForm.table` rules from projection.json, in Ruby's field
 /// order; `position` is a string.
 fn canonical_form_table() -> JsonValue {
-    JsonValue::Array(vec![
-        JsonValue::Object(vec![
-            (
-                "strategy".to_string(),
-                JsonValue::str("collapse_whitespace"),
-            ),
-            ("source_token".to_string(), JsonValue::str("")),
-            ("replacement".to_string(), JsonValue::str("")),
-            ("boundary".to_string(), JsonValue::str("none")),
-            ("position".to_string(), JsonValue::str("1")),
-        ]),
-        JsonValue::Object(vec![
-            ("strategy".to_string(), JsonValue::str("replace")),
-            ("source_token".to_string(), JsonValue::str(".length")),
-            ("replacement".to_string(), JsonValue::str(".size")),
-            ("boundary".to_string(), JsonValue::str("word")),
-            ("position".to_string(), JsonValue::str("2")),
-        ]),
-    ])
+    JsonValue::Array(
+        crate::canonical::TABLE
+            .iter()
+            .map(|(strategy, token, replacement, boundary, position)| {
+                JsonValue::Object(vec![
+                    ("strategy".to_string(), JsonValue::str(*strategy)),
+                    ("source_token".to_string(), JsonValue::str(*token)),
+                    ("replacement".to_string(), JsonValue::str(*replacement)),
+                    ("boundary".to_string(), JsonValue::str(*boundary)),
+                    ("position".to_string(), JsonValue::str(*position)),
+                ])
+            })
+            .collect(),
+    )
 }
 
 /// `IR::Bluebook#to_h`; field order is pinned there.
@@ -304,6 +299,17 @@ fn command_json(c: &ir::Command) -> JsonValue {
             "ensures".to_string(),
             JsonValue::Array(c.ensures.iter().map(given_json).collect()),
         ),
+        (
+            "needs".to_string(),
+            JsonValue::Array(
+                c.needs
+                    .iter()
+                    .map(|fact| {
+                        JsonValue::Object(vec![("fact".to_string(), JsonValue::str(fact.clone()))])
+                    })
+                    .collect(),
+            ),
+        ),
         (
             "mutations".to_string(),
             JsonValue::Array(c.mutations.iter().map(mutation_json).collect()),

data/rust/parser/src/ir.rs

@@ -98,6 +98,8 @@ pub struct Command {
     pub attributes: Vec<Attribute>,
     pub givens: Vec<Given>,
     pub ensures: Vec<Ensures>,
+    // Outside facts the runtime supplies before any given runs (`needs :now`); only `now` today.
+    pub needs: Vec<String>,
     pub mutations: Vec<Mutation>,
     pub emits: Vec<String>,
     // The lifecycle state this command is admissible from; see `CommandFrom`.

data/rust/parser/src/keywords.rs

@@ -107,6 +107,7 @@ pub static KEYWORDS: &[KeywordRow] = &[
     KeywordRow { word: "state", context: "Command", body: "none", inner: "", opens: "", fills: "mutations", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "attribute", context: "Command", body: "none", inner: "", opens: "", fills: "attributes", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "ensures", context: "Command", body: "source", inner: "", opens: "", fills: "ensures", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
+    KeywordRow { word: "needs", context: "Command", body: "none", inner: "", opens: "", fills: "needs", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "corrects", context: "Command", body: "none", inner: "", opens: "", fills: "mutations", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "description", context: "Entity", body: "none", inner: "", opens: "", fills: "description", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
     KeywordRow { word: "identified_by", context: "Entity", body: "keywords", inner: "ValueObject", opens: "ValueObject", fills: "identified_by", status: "admitted", was: "", resolves_via: "", disambiguator: "" },
@@ -308,6 +309,7 @@ pub static ARGUMENTS: &[ArgumentRow] = &[
     ArgumentRow { keyword: "reference_to", context: "Command", at: "", named: "optional", kind: "flag", required: "false", fills: "optional", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "given", context: "Command", at: "1", named: "", kind: "text", required: "true", fills: "description", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "ensures", context: "Command", at: "1", named: "", kind: "text", required: "true", fills: "description", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
+    ArgumentRow { keyword: "needs", context: "Command", at: "1", named: "", kind: "symbol", required: "true", fills: "fact", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "sets", context: "Command", at: "1", named: "", kind: "symbol", required: "true", fills: "target", selects: "", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "sets", context: "Command", at: "", named: "to", kind: "literal", required: "false", fills: "source", selects: "op=set", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },
     ArgumentRow { keyword: "sets", context: "Command", at: "", named: "append", kind: "literal", required: "false", fills: "source", selects: "op=append", pair_key_fills: "", pair_value_fills: "", pairs_shape: "", status: "admitted", variadic: "", minimum: "" },

data/rust/parser/src/main.rs

@@ -179,6 +179,7 @@ const COVERED_PAIRS: &[(&str, &str)] = &[
     ("reference_to", "Command"),
     ("given", "Command"),
     ("ensures", "Command"),
+    ("needs", "Command"),
     ("sets", "Command"),
     ("corrects", "Command"),
     ("delegates_to", "Command"),

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

@@ -164,6 +164,7 @@ pub fn parse_body(
                 owner_entities,
             );
             refuse_duplicate_targets(file, *pos, &command)?;
+            refuse_undeclared_needs(file, *pos, &command)?;
             return Ok((command, pending));
         };
         let line = gated.line.number;
@@ -205,6 +206,27 @@ pub fn parse_body(
                     canonical: canonical::apply(&raw),
                 });
             }
+            "needs" => {
+                let fact = super::positional_symbol(file, line, "needs", &gated.args, 1)?;
+                if !NEEDABLE_FACTS.contains(&fact.as_str()) {
+                    return Err(Diagnostic::new(
+                        file,
+                        line,
+                        format!(
+                            "{} needs :{fact}, which the runtime cannot supply — it supplies :now",
+                            command.name
+                        ),
+                    ));
+                }
+                if command.needs.contains(&fact) {
+                    return Err(Diagnostic::new(
+                        file,
+                        line,
+                        format!("{} declares needs :{fact} twice", command.name),
+                    ));
+                }
+                command.needs.push(fact);
+            }
             "provenance" => {
                 let raw = super::named_raw(&gated.args, "from")
                     .ok_or_else(|| Diagnostic::new(file, line, "'provenance' requires a from:"))?;
@@ -297,6 +319,28 @@ fn state_ref(raw: &str) -> Option<String> {
     Some(inner.to_string())
 }
 
+/// The outside facts a command may declare it needs; mirrors `CommandBuilder::NEEDABLE_FACTS`.
+const NEEDABLE_FACTS: &[&str] = &["now"];
+
+/// A need names the attribute the runtime fills, so the command must declare it.
+fn refuse_undeclared_needs(file: &str, line: usize, command: &ir::Command) -> ParseResult<()> {
+    match command
+        .needs
+        .iter()
+        .find(|fact| !command.attributes.iter().any(|a| &a.name == *fact))
+    {
+        Some(fact) => Err(Diagnostic::new(
+            file,
+            line,
+            format!(
+                "{} needs :{fact} but declares no attribute :{fact} for the runtime to fill — add `attribute :{fact}, <type>`",
+                command.name
+            ),
+        )),
+        None => Ok(()),
+    }
+}
+
 /// Refuses a field written twice: a command's effects are one update set (C4.2).
 /// `delegates_to`/`corrects` name no field and are not counted.
 fn refuse_duplicate_targets(file: &str, line: usize, command: &ir::Command) -> ParseResult<()> {

data/rust/project/naming.rb

@@ -100,12 +100,14 @@ module RustProjection
 
     # Every declared `name` in the IR, in document order. The `fields` maps under
     # `mutations` are skipped: their keys are attribute names and their values
-    # are source text, not declarations.
+    # are source text, not declarations. So is `translations`: an era edge names
+    # data paths (`attendee.first_name`, a backfill into a nested value object)
+    # that the host applies to stored rows and never writes into Rust.
     def declared_names(node, out = [])
       case node
       when Hash
         node.each do |key, value|
-          if key.to_s == "fields"
+          if %w[fields translations].include?(key.to_s)
             next
           elsif key.to_s == "name" && value.is_a?(String)
             out << value

data/rust/src/kernel/cli.rs

@@ -16,6 +16,9 @@ pub fn run(input: &str) -> String {
         Err(e) => return error_output(&format!("invalid JSON on stdin: {e}")),
     };
 
+    // Optional `"needs"`: which commands need which outside facts (ADR 0081), passed by the host.
+    super::needs::install(parsed.get("needs"));
+
     let steps = match parsed.get("steps").and_then(Json::as_array) {
         Some(s) => s,
         None => return error_output("expected a top-level {\"steps\": [...]} object"),

data/rust/src/kernel/mod.rs

@@ -7,6 +7,7 @@ pub mod expr;
 pub mod expression_operators;
 pub mod json;
 pub mod named_query;
+pub mod needs;
 pub mod orchestrate;
 pub mod pattern;
 pub mod query_ordering;