Skip to main content

astrs_cli/command/
build.rs

1//! `astrs build` — run a manifest's `build:` lines, without running the
2//! graph (blueprint §17).
3//!
4//! The same engine `astrs run`'s build phase uses, reached the same way:
5//! [`astrs_daemon::plan_dataflow`] turns the manifest into the ordered
6//! [`astrs_daemon::BuildStep`] list, and
7//! [`astrs_daemon::dataflow::run_step`] executes one — with §16's scrubbed
8//! environment, shlex argv splitting, no shell, its own process group, and
9//! both streams captured. Nothing about *how a build line runs* is decided
10//! in this crate.
11//!
12//! What this verb adds over the run's own build phase is what a standalone
13//! build verb is for:
14//!
15//! - `--node <id>`, to rebuild one node without touching the rest;
16//! - `--release`, appended to each line for the common `cargo build` case;
17//! - **per-node log capture** into `<runtime dir>/build/<node>.log`, so a
18//!   build that scrolled past is still readable afterwards (§24.2);
19//! - a typed report with `--json`, so CI can read step outcomes rather than
20//!   scrape text.
21//!
22//! ```text
23//!   manifest ─► plan_dataflow ─► [BuildStep] ──filter(--node)──┐
24//!                                                              ▼
25//!         <runtime>/build/<node>.log ◄── capture ── run_step (§16 hygiene)
26//!                                                              │
27//!                            stop at the first failure ◄───────┘
28//! ```
29
30use std::io::Write;
31use std::path::{Path, PathBuf};
32
33use astrs_daemon::dataflow::{StepOutcome, run_step};
34use astrs_daemon::spawn::{EnvPolicy, Spawner};
35use astrs_daemon::{BuildStep, plan_dataflow};
36use astrs_manifest::Manifest;
37use astrs_wire::{DataflowId, NodeId};
38
39use crate::error::CliError;
40
41/// `astrs build`'s arguments, already parsed and resolved.
42#[derive(Debug, Clone)]
43pub struct BuildArgs {
44    /// The manifest whose nodes to build.
45    pub manifest_path: PathBuf,
46    /// Append `--release` to every line.
47    pub release: bool,
48    /// Only build this node.
49    pub node: Option<String>,
50    /// Where the lines run; the manifest's directory by default.
51    pub working_dir: Option<PathBuf>,
52    /// Where per-node logs are captured.
53    pub runtime_dir: Option<PathBuf>,
54    /// Emit JSON rather than a human summary.
55    pub json: bool,
56}
57
58impl BuildArgs {
59    /// The arguments for building `manifest_path` with every default.
60    #[must_use]
61    pub fn new(manifest_path: impl Into<PathBuf>) -> Self {
62        Self {
63            manifest_path: manifest_path.into(),
64            release: false,
65            node: None,
66            working_dir: None,
67            runtime_dir: None,
68            json: false,
69        }
70    }
71}
72
73/// One node's build, as this verb reports it.
74#[derive(Debug, Clone)]
75pub struct NodeBuild {
76    /// The node.
77    pub node: NodeId,
78    /// The command line that ran.
79    pub command: String,
80    /// Its exit code, or `None` when a signal ended it.
81    pub exit_code: Option<i32>,
82    /// Where its output was captured.
83    pub log_path: Option<PathBuf>,
84    /// Everything it wrote.
85    pub output: String,
86}
87
88impl NodeBuild {
89    /// Whether the step succeeded.
90    #[must_use]
91    pub fn is_success(&self) -> bool {
92        self.exit_code == Some(0)
93    }
94}
95
96/// What one `astrs build` did.
97#[derive(Debug, Clone, Default)]
98pub struct BuildCliReport {
99    /// The steps that ran, in order, up to and including any failure.
100    pub steps: Vec<NodeBuild>,
101    /// Nodes named in the manifest that declared no `build:` line at all.
102    pub skipped: Vec<NodeId>,
103    /// The step that could not be started at all, when one could not.
104    pub start_failure: Option<String>,
105}
106
107impl BuildCliReport {
108    /// Whether every step that ran succeeded.
109    #[must_use]
110    pub fn is_success(&self) -> bool {
111        self.start_failure.is_none() && self.steps.iter().all(NodeBuild::is_success)
112    }
113
114    /// The process exit code: `0` for a build that succeeded, `1` for one
115    /// that did not.
116    #[must_use]
117    pub fn exit_code(&self) -> i32 {
118        i32::from(!self.is_success())
119    }
120
121    /// The first step that failed, when one did.
122    #[must_use]
123    pub fn failed_step(&self) -> Option<&NodeBuild> {
124        self.steps.iter().find(|step| !step.is_success())
125    }
126
127    /// The `--json` form.
128    #[must_use]
129    pub fn to_json(&self) -> serde_json::Value {
130        let steps: Vec<serde_json::Value> = self
131            .steps
132            .iter()
133            .map(|step| {
134                serde_json::json!({
135                    "node": step.node.as_str(),
136                    "command": step.command,
137                    "exit_code": step.exit_code,
138                    "success": step.is_success(),
139                    "log": step.log_path.as_ref().map(|p| p.display().to_string()),
140                })
141            })
142            .collect();
143        serde_json::json!({
144            "success": self.is_success(),
145            "exit_code": self.exit_code(),
146            "start_failure": self.start_failure,
147            "skipped": self.skipped.iter().map(NodeId::as_str).collect::<Vec<_>>(),
148            "steps": steps,
149        })
150    }
151}
152
153/// Builds a manifest's nodes, writing progress to `out`.
154///
155/// Every step's captured output is written to the terminal *and* to its own
156/// file: a build is the one place where "I want to see it now" and "I want
157/// to read it after it scrolled away" are both true, and neither is served
158/// by the other.
159///
160/// # Errors
161///
162/// - [`CliError::Manifest`] / [`CliError::Validation`] if the manifest is
163///   not usable.
164/// - [`CliError::Daemon`] if the manifest cannot be planned.
165/// - [`CliError::BadArgument`] if `--node` names a node the manifest does
166///   not have.
167/// - [`CliError::Io`] if a capture file cannot be written.
168///
169/// A build line that *fails* is not an error: it is a [`BuildCliReport`]
170/// whose output the operator needs to read, exactly as
171/// [`astrs_daemon::BuildReport`]'s own docs argue.
172pub fn run(out: &mut dyn Write, args: &BuildArgs) -> Result<BuildCliReport, CliError> {
173    let manifest = Manifest::from_yaml_file(&args.manifest_path)?;
174    manifest.validate()?;
175
176    let working_dir = args
177        .working_dir
178        .clone()
179        .unwrap_or_else(|| manifest_dir(&args.manifest_path));
180    let runtime_dir = crate::runtime_dir::runtime_dir(args.runtime_dir.as_deref());
181    let log_dir = crate::runtime_dir::build_log_dir(&runtime_dir);
182
183    let policy = EnvPolicy::new();
184    let plan = plan_dataflow(
185        DataflowId::generate(),
186        &manifest,
187        &policy.scrub_process_env(),
188    )?;
189
190    let selected = select_steps(&plan.build_steps, args.node.as_deref(), &manifest)?;
191    let skipped = nodes_without_build(&manifest, &plan.build_steps);
192
193    let runtime = tokio::runtime::Builder::new_current_thread()
194        .enable_all()
195        .build()
196        .map_err(|source| CliError::io(&args.manifest_path, source))?;
197
198    let spawner = Spawner::with_policy(working_dir, policy);
199    let mut report = BuildCliReport {
200        skipped,
201        ..BuildCliReport::default()
202    };
203
204    for step in selected {
205        let step = apply_release(&step, args.release);
206        let _ = writeln!(out, "building {}: {}", step.node, step.command);
207        match runtime.block_on(run_step(&spawner, &step)) {
208            Ok(outcome) => {
209                let log_path = capture(&log_dir, &outcome)?;
210                if !outcome.output.is_empty() {
211                    let _ = write!(out, "{}", ensure_newline(&outcome.output));
212                }
213                let failed = !outcome.is_success();
214                report.steps.push(NodeBuild {
215                    node: outcome.node,
216                    command: outcome.command,
217                    exit_code: outcome.exit_code,
218                    log_path,
219                    output: outcome.output,
220                });
221                if failed {
222                    break;
223                }
224            }
225            Err(error) => {
226                report.start_failure = Some(error.to_string());
227                break;
228            }
229        }
230    }
231
232    if args.json {
233        let _ = writeln!(
234            out,
235            "{}",
236            serde_json::to_string_pretty(&report.to_json()).unwrap_or_else(|_| "{}".to_owned())
237        );
238    } else {
239        let _ = writeln!(out, "{}", summary(&report, &log_dir));
240    }
241    Ok(report)
242}
243
244/// The human one-liner (or two) a finished build prints.
245fn summary(report: &BuildCliReport, log_dir: &Path) -> String {
246    let mut text = if let Some(reason) = &report.start_failure {
247        format!("build could not start: {reason}")
248    } else if let Some(step) = report.failed_step() {
249        format!(
250            "build failed at `{}` ({})",
251            step.node,
252            match step.exit_code {
253                Some(code) => format!("exit code {code}"),
254                None => "ended by a signal".to_owned(),
255            }
256        )
257    } else {
258        format!("built {} node(s)", report.steps.len())
259    };
260    if !report.skipped.is_empty() {
261        text.push_str(&format!(
262            "\n{} node(s) declare no `build:` line: {}",
263            report.skipped.len(),
264            report
265                .skipped
266                .iter()
267                .map(NodeId::as_str)
268                .collect::<Vec<_>>()
269                .join(", ")
270        ));
271    }
272    if !report.steps.is_empty() {
273        text.push_str(&format!("\nlogs: {}", log_dir.display()));
274    }
275    text
276}
277
278/// The build steps this invocation should run.
279///
280/// # Errors
281///
282/// [`CliError::BadArgument`] when `--node` names something the manifest does
283/// not declare — deliberately distinguished from "that node declares no
284/// `build:` line", which is an empty selection rather than a mistake.
285fn select_steps(
286    steps: &[BuildStep],
287    node: Option<&str>,
288    manifest: &Manifest,
289) -> Result<Vec<BuildStep>, CliError> {
290    let Some(wanted) = node else {
291        return Ok(steps.to_vec());
292    };
293    if !manifest.nodes.iter().any(|node| node.id == wanted) {
294        return Err(CliError::BadArgument {
295            flag: "node",
296            value: wanted.to_owned(),
297            reason: format!(
298                "the manifest declares no such node (it has: {})",
299                manifest
300                    .nodes
301                    .iter()
302                    .map(|node| node.id.as_str())
303                    .collect::<Vec<_>>()
304                    .join(", ")
305            ),
306        });
307    }
308    Ok(steps
309        .iter()
310        .filter(|step| step.node.as_str() == wanted)
311        .cloned()
312        .collect())
313}
314
315/// The nodes with no `build:` line, so the report can say so rather than
316/// leaving a user wondering why their node never appeared.
317fn nodes_without_build(manifest: &Manifest, steps: &[BuildStep]) -> Vec<NodeId> {
318    manifest
319        .nodes
320        .iter()
321        .filter(|node| !steps.iter().any(|step| step.node.as_str() == node.id))
322        .filter_map(|node| NodeId::new(&node.id).ok())
323        .collect()
324}
325
326/// Appends `--release` to a step's command line when asked.
327///
328/// Appended to the *string*, before the shlex split `run_step` does, so it
329/// becomes one more argument rather than being glued onto the last one.
330fn apply_release(step: &BuildStep, release: bool) -> BuildStep {
331    if !release {
332        return step.clone();
333    }
334    BuildStep {
335        node: step.node.clone(),
336        command: format!("{} --release", step.command),
337        working_dir: step.working_dir.clone(),
338    }
339}
340
341/// Writes one step's output to `<log_dir>/<node>.log`, returning where.
342///
343/// A capture failure is an error rather than a warning: the whole point of
344/// this verb over `astrs run`'s build phase is that the output survives, so
345/// silently not saving it would be the one failure a user could not detect.
346fn capture(log_dir: &Path, outcome: &StepOutcome) -> Result<Option<PathBuf>, CliError> {
347    crate::runtime_dir::ensure_dir(log_dir)?;
348    let path = log_dir.join(format!("{}.log", outcome.node));
349    let header = format!(
350        "# astrs build — node {}\n# command: {}\n# exit: {}\n",
351        outcome.node,
352        outcome.command,
353        match outcome.exit_code {
354            Some(code) => code.to_string(),
355            None => "signal".to_owned(),
356        }
357    );
358    std::fs::write(
359        &path,
360        format!("{header}{}", ensure_newline(&outcome.output)),
361    )
362    .map_err(|source| CliError::io(&path, source))?;
363    Ok(Some(path))
364}
365
366/// `text` with a trailing newline, and nothing added when it already ends
367/// in one (or is empty).
368fn ensure_newline(text: &str) -> String {
369    if text.is_empty() || text.ends_with('\n') {
370        text.to_owned()
371    } else {
372        format!("{text}\n")
373    }
374}
375
376/// The directory a manifest's relative paths resolve against.
377fn manifest_dir(path: &Path) -> PathBuf {
378    path.parent()
379        .filter(|parent| !parent.as_os_str().is_empty())
380        .map_or_else(|| PathBuf::from("."), Path::to_path_buf)
381}
382
383#[cfg(test)]
384mod tests {
385    #![allow(clippy::unwrap_used, clippy::expect_used, clippy::panic)]
386
387    use super::*;
388
389    fn scratch(name: &str) -> PathBuf {
390        let dir =
391            std::env::temp_dir().join(format!("astrs-cli-build-{}-{name}", std::process::id()));
392        let _ = std::fs::remove_dir_all(&dir);
393        std::fs::create_dir_all(&dir).unwrap();
394        dir
395    }
396
397    fn write_manifest(dir: &Path, yaml: &str) -> PathBuf {
398        let path = dir.join("dataflow.yml");
399        std::fs::write(&path, yaml).unwrap();
400        path
401    }
402
403    fn args(dir: &Path, path: PathBuf) -> BuildArgs {
404        let mut args = BuildArgs::new(path);
405        args.working_dir = Some(dir.to_path_buf());
406        args.runtime_dir = Some(dir.to_path_buf());
407        args
408    }
409
410    const TWO_NODES: &str = "\
411nodes:
412  - id: alpha
413    path: /usr/bin/true
414    build: /bin/sh -c 'echo alpha-built'
415  - id: beta
416    path: /usr/bin/true
417    build: /bin/sh -c 'echo beta-built'
418";
419
420    #[test]
421    fn every_build_line_runs_in_manifest_order_and_is_captured() {
422        let dir = scratch("ok");
423        let path = write_manifest(&dir, TWO_NODES);
424        let mut out = Vec::new();
425        let report = run(&mut out, &args(&dir, path)).unwrap();
426        let text = String::from_utf8(out).unwrap();
427
428        assert!(report.is_success(), "{report:?}");
429        assert_eq!(report.exit_code(), 0);
430        assert_eq!(report.steps.len(), 2);
431        assert_eq!(report.steps[0].node.as_str(), "alpha");
432        assert_eq!(report.steps[1].node.as_str(), "beta");
433        assert!(text.contains("alpha-built"), "{text}");
434        assert!(text.contains("beta-built"), "{text}");
435
436        let log = crate::runtime_dir::build_log_dir(&dir).join("alpha.log");
437        let captured = std::fs::read_to_string(&log).unwrap();
438        assert!(captured.contains("alpha-built"), "{captured}");
439        assert!(captured.contains("# exit: 0"), "{captured}");
440    }
441
442    #[test]
443    fn a_failing_line_stops_the_build_and_is_reported_as_data() {
444        let dir = scratch("failure");
445        let path = write_manifest(
446            &dir,
447            "\
448nodes:
449  - id: alpha
450    path: /usr/bin/true
451    build: /bin/sh -c 'echo nope; exit 7'
452  - id: beta
453    path: /usr/bin/true
454    build: /bin/sh -c 'echo never'
455",
456        );
457        let mut out = Vec::new();
458        let report = run(&mut out, &args(&dir, path)).unwrap();
459        let text = String::from_utf8(out).unwrap();
460
461        assert!(!report.is_success());
462        assert_eq!(report.exit_code(), 1);
463        assert_eq!(report.steps.len(), 1, "the second line must not have run");
464        assert_eq!(report.failed_step().unwrap().exit_code, Some(7));
465        assert!(text.contains("build failed at `alpha`"), "{text}");
466        assert!(!text.contains("never"), "{text}");
467    }
468
469    #[test]
470    fn one_node_can_be_built_alone() {
471        let dir = scratch("one-node");
472        let path = write_manifest(&dir, TWO_NODES);
473        let mut a = args(&dir, path);
474        a.node = Some("beta".to_owned());
475        let mut out = Vec::new();
476        let report = run(&mut out, &a).unwrap();
477        assert_eq!(report.steps.len(), 1);
478        assert_eq!(report.steps[0].node.as_str(), "beta");
479        let text = String::from_utf8(out).unwrap();
480        assert!(!text.contains("alpha-built"), "{text}");
481    }
482
483    #[test]
484    fn an_unknown_node_names_the_ones_that_do_exist() {
485        let dir = scratch("unknown-node");
486        let path = write_manifest(&dir, TWO_NODES);
487        let mut a = args(&dir, path);
488        a.node = Some("gamma".to_owned());
489        let error = run(&mut Vec::new(), &a).unwrap_err();
490        match error {
491            CliError::BadArgument { flag, reason, .. } => {
492                assert_eq!(flag, "node");
493                assert!(reason.contains("alpha"), "{reason}");
494                assert!(reason.contains("beta"), "{reason}");
495            }
496            other => panic!("expected BadArgument, got {other}"),
497        }
498    }
499
500    #[test]
501    fn nodes_with_no_build_line_are_reported_rather_than_silently_ignored() {
502        let dir = scratch("no-build");
503        let path = write_manifest(
504            &dir,
505            "nodes:\n  - id: alpha\n    path: /usr/bin/true\n  - id: beta\n    path: /usr/bin/true\n    build: /bin/sh -c 'true'\n",
506        );
507        let mut out = Vec::new();
508        let report = run(&mut out, &args(&dir, path)).unwrap();
509        assert_eq!(report.skipped.len(), 1);
510        assert_eq!(report.skipped[0].as_str(), "alpha");
511        let text = String::from_utf8(out).unwrap();
512        assert!(text.contains("declare no `build:` line"), "{text}");
513    }
514
515    #[test]
516    fn release_appends_one_more_argument() {
517        let step = BuildStep {
518            node: NodeId::new("alpha").unwrap(),
519            command: "cargo build -p alpha".to_owned(),
520            working_dir: None,
521        };
522        assert_eq!(apply_release(&step, false).command, "cargo build -p alpha");
523        assert_eq!(
524            apply_release(&step, true).command,
525            "cargo build -p alpha --release"
526        );
527    }
528
529    #[test]
530    fn release_reaches_the_process_that_runs() {
531        let dir = scratch("release");
532        // `printf '%s\n' "$@"`-style: the line echoes whatever extra
533        // arguments it was given, so the appended flag is observable.
534        let path = write_manifest(
535            &dir,
536            "nodes:\n  - id: alpha\n    path: /usr/bin/true\n    build: /bin/echo built\n",
537        );
538        let mut a = args(&dir, path);
539        a.release = true;
540        let mut out = Vec::new();
541        let report = run(&mut out, &a).unwrap();
542        assert!(report.is_success(), "{report:?}");
543        assert!(report.steps[0].output.contains("--release"), "{report:?}");
544    }
545
546    #[test]
547    fn json_output_carries_every_step_and_the_exit_code() {
548        let dir = scratch("json");
549        let path = write_manifest(&dir, TWO_NODES);
550        let mut a = args(&dir, path);
551        a.json = true;
552        let mut out = Vec::new();
553        let report = run(&mut out, &a).unwrap();
554        let text = String::from_utf8(out).unwrap();
555        let start = text.find('{').expect("a JSON object");
556        let value: serde_json::Value = serde_json::from_str(&text[start..]).unwrap();
557        assert_eq!(value["success"], true);
558        assert_eq!(value["exit_code"], 0);
559        assert_eq!(value["steps"].as_array().unwrap().len(), 2);
560        assert_eq!(report.exit_code(), 0);
561    }
562
563    #[test]
564    fn a_manifest_that_does_not_validate_is_refused() {
565        let dir = scratch("invalid");
566        let path = write_manifest(
567            &dir,
568            "nodes:\n  - id: a\n    path: /usr/bin/true\n    inputs:\n      in: ghost/out\n",
569        );
570        let error = run(&mut Vec::new(), &args(&dir, path)).unwrap_err();
571        assert!(matches!(error, CliError::Validation(_)), "{error}");
572    }
573
574    #[test]
575    fn a_manifest_with_no_build_lines_at_all_succeeds_trivially() {
576        let dir = scratch("empty");
577        let path = write_manifest(&dir, "nodes:\n  - id: a\n    path: /usr/bin/true\n");
578        let mut out = Vec::new();
579        let report = run(&mut out, &args(&dir, path)).unwrap();
580        assert!(report.is_success());
581        assert!(report.steps.is_empty());
582        let text = String::from_utf8(out).unwrap();
583        assert!(text.contains("built 0 node(s)"), "{text}");
584    }
585
586    #[test]
587    fn a_trailing_newline_is_added_exactly_once() {
588        assert_eq!(ensure_newline(""), "");
589        assert_eq!(ensure_newline("a"), "a\n");
590        assert_eq!(ensure_newline("a\n"), "a\n");
591    }
592}