Skip to main content

arb/
spec.rs

1//! Interpreter: command tree -> a `Spec`. Recognizes the widget verbs,
2//! `source .x { … }` whose body compiles to a query pipeline (see `query`), and
3//! the `.x <- in` bind shorthand. Unknown widget verbs are ignored so specs stay
4//! forward-compatible.
5
6use std::collections::BTreeMap;
7use std::sync::Arc;
8use std::time::Duration;
9
10use regex::Regex;
11
12use crate::actor::ActorDef;
13use crate::ast::{Arg, Command};
14use crate::query::{FieldSel, QueryOp};
15
16#[derive(Debug, Clone, Copy, PartialEq, Eq)]
17pub enum WidgetKind {
18    Text,
19    Tail,
20    List,
21    Gauge,
22    Bars,
23    Histo,
24    Spark,
25    Chart,
26    Table,
27    Tabs,
28    Block,
29    Frame,
30    /// A thin single-line progress bar (ratatui `LineGauge`) — a compact `gauge`
31    /// for tight grid cells. Same scalar source + `-max` as `gauge`.
32    LineGauge,
33    /// A braille scatter/line plot (ratatui `Canvas`) of a numeric series — a
34    /// higher-resolution `chart` drawn with braille dots. `-mode line|points`.
35    Scatter,
36    /// A block-bar sparkline (ratatui `Sparkline`) of the numeric series — the
37    /// classic fixed-height bar sparkline (distinct from `spark`'s braille line).
38    Sparkline,
39    /// A braille world map (ratatui `Canvas` + `Map`) plotting `lon lat` points
40    /// parsed from the stream — geo scatter (IP geolocation, GPS traces). `-res
41    /// high|low`.
42    Map,
43    /// A month calendar (ratatui `Monthly`) for the current month, highlighting
44    /// days that appear as `YYYY-MM-DD` in the stream (activity by day).
45    Calendar,
46    /// A level-colored log tail: like `tail`, but each line is tinted by its log
47    /// level (ERROR/WARN/INFO/DEBUG) detected in the text — theme-aware.
48    LogView,
49    /// A heatmap grid (GitHub-contribution-style): the numeric series laid out as
50    /// colored cells, each cell's shade scaled from the value across the palette.
51    Heatmap,
52    /// A treemap (slice-and-dice): `tally`/`count_by` pairs as proportional
53    /// labeled rectangles filling the pane, colored across the palette.
54    Treemap,
55    /// A Gantt/timeline: `label start end` lines drawn as horizontal bars on a
56    /// shared time axis (min start → max end).
57    Gantt,
58    /// A diff-colored view: each line tinted by its leading char — `+` add (green),
59    /// `-` remove (red), `@` hunk (accent) — for `git diff`/patch streams.
60    Diff,
61    /// The ratatui logo (braille wordmark), centered — a decorative splash.
62    Logo,
63    /// A blank spacer (ratatui `Clear`) — occupies a grid cell without drawing, to
64    /// open space in a layout.
65    Blank,
66    /// A horizontal (or `-dir vertical`) divider rule in the theme accent.
67    Rule,
68    /// An in-dashboard selection list over its own `source` (per-widget), with a
69    /// moveable cursor. Its highlighted row is published as the control value
70    /// `.<path>.sel`, readable from `where`/`apply`/`tell`/`ask` (SPEC §14). E.g.
71    /// `ps aux | arb` with `sel .ps { in }` exposes `.ps.sel` = the current row.
72    Sel,
73    /// An editable text field. Its live value is bound into pipelines via
74    /// `apply .name` (parse the value as a query pipeline) — the megafilter/map.
75    Input,
76    /// An interactive fuzzy-select list over the stream (the fzf surface as a
77    /// widget). Its presence puts the TUI in select mode: type to fuzzy-filter,
78    /// arrows/Ctrl-N/P move the cursor, Tab marks, Enter emits the picked lines.
79    /// `-prompt`/`-header` opts set the prompt line and a header above the list.
80    Select,
81    /// A text box whose value drives `where match(.name)` / `apply` — a labelled
82    /// filter control (a specialised `input`).
83    Filter,
84    /// A multi-select of candidate values (`-opts {a b c}`, else distinct stream
85    /// `-field` values). Its value is the comma-joined selected set for
86    /// `where <field> in .name`.
87    Facet,
88    /// A numeric control (`-min`/`-max`/`-step`) whose value drives
89    /// `where <field> < .name`; arrows/`+`/`-` adjust it.
90    Slider,
91    /// A boolean toggle (`-label`); its value is `"1"`/`"0"`.
92    Check,
93}
94
95impl WidgetKind {
96    pub(crate) fn from(verb: &str) -> Option<WidgetKind> {
97        Some(match verb {
98            "text" => WidgetKind::Text,
99            "tail" => WidgetKind::Tail,
100            "list" => WidgetKind::List,
101            "gauge" => WidgetKind::Gauge,
102            "bars" => WidgetKind::Bars,
103            "histo" => WidgetKind::Histo,
104            "spark" => WidgetKind::Spark,
105            "chart" => WidgetKind::Chart,
106            "table" => WidgetKind::Table,
107            "tabs" => WidgetKind::Tabs,
108            "block" => WidgetKind::Block,
109            "frame" => WidgetKind::Frame,
110            "linegauge" => WidgetKind::LineGauge,
111            "scatter" => WidgetKind::Scatter,
112            "sparkline" => WidgetKind::Sparkline,
113            "map" => WidgetKind::Map,
114            "calendar" => WidgetKind::Calendar,
115            "logview" => WidgetKind::LogView,
116            "heatmap" => WidgetKind::Heatmap,
117            "treemap" => WidgetKind::Treemap,
118            "gantt" => WidgetKind::Gantt,
119            "diff" => WidgetKind::Diff,
120            "logo" => WidgetKind::Logo,
121            "clear" | "blank" | "spacer" => WidgetKind::Blank,
122            "rule" | "divider" => WidgetKind::Rule,
123            "sel" => WidgetKind::Sel,
124            "input" => WidgetKind::Input,
125            "select" => WidgetKind::Select,
126            "filter" => WidgetKind::Filter,
127            "facet" => WidgetKind::Facet,
128            "slider" => WidgetKind::Slider,
129            "check" => WidgetKind::Check,
130            _ => return None,
131        })
132    }
133
134    pub fn label(&self) -> &'static str {
135        match self {
136            WidgetKind::Text => "text",
137            WidgetKind::Tail => "tail",
138            WidgetKind::List => "list",
139            WidgetKind::Gauge => "gauge",
140            WidgetKind::Bars => "bars",
141            WidgetKind::Histo => "histo",
142            WidgetKind::Spark => "spark",
143            WidgetKind::Chart => "chart",
144            WidgetKind::Table => "table",
145            WidgetKind::Tabs => "tabs",
146            WidgetKind::Block => "block",
147            WidgetKind::Frame => "frame",
148            WidgetKind::LineGauge => "linegauge",
149            WidgetKind::Scatter => "scatter",
150            WidgetKind::Sparkline => "sparkline",
151            WidgetKind::Map => "map",
152            WidgetKind::Calendar => "calendar",
153            WidgetKind::LogView => "logview",
154            WidgetKind::Heatmap => "heatmap",
155            WidgetKind::Treemap => "treemap",
156            WidgetKind::Gantt => "gantt",
157            WidgetKind::Diff => "diff",
158            WidgetKind::Logo => "logo",
159            WidgetKind::Blank => "clear",
160            WidgetKind::Rule => "rule",
161            WidgetKind::Sel => "sel",
162            WidgetKind::Input => "input",
163            WidgetKind::Select => "select",
164            WidgetKind::Filter => "filter",
165            WidgetKind::Facet => "facet",
166            WidgetKind::Slider => "slider",
167            WidgetKind::Check => "check",
168        }
169    }
170
171    /// Whether this kind is an interactive control (value lives in the input
172    /// registry and drives `apply`/`where … .name`), not a stream view.
173    pub fn is_control(&self) -> bool {
174        matches!(
175            self,
176            WidgetKind::Input
177                | WidgetKind::Filter
178                | WidgetKind::Facet
179                | WidgetKind::Slider
180                | WidgetKind::Check
181                | WidgetKind::Sel
182        )
183    }
184}
185
186/// A data source: reads stdin, then applies a query pipeline.
187#[derive(Debug, Clone)]
188pub struct Source {
189    pub pipeline: Vec<QueryOp>,
190}
191
192#[derive(Debug, Clone)]
193pub struct Widget {
194    pub path: String,
195    pub kind: WidgetKind,
196    pub opts: BTreeMap<String, String>,
197    pub source: Option<Source>,
198    /// Optional search-key pipeline (`search .name { … }`), for a `select`
199    /// widget: the fuzzy match runs against this derived key while the row still
200    /// shows/emits the `source` display. fzf `--nth`, but pipeline-general (search
201    /// a column, a lowercased key, an extracted field). `None` = search display.
202    pub search: Option<Vec<QueryOp>>,
203    /// Grid cell `(row, col)` set by a `grid` command; `None` = auto-stacked.
204    pub grid: Option<(usize, usize)>,
205    /// Grid span `(rows, cols)` from `grid -rowspan`/`-colspan` (`-span` = colspan);
206    /// `(1, 1)` = a single cell. Lets a chart span multiple cells while gauges take one.
207    pub span: (usize, usize),
208}
209
210/// A key binding: a control key that triggers a [`BindAction`] in the TUI.
211/// Declared `bind C-<letter> <action>` — the arb-native way to drive the spec's
212/// own state from the keyboard (set a control, quit), foundation for reactions.
213#[derive(Debug, Clone)]
214pub struct Bind {
215    /// The raw control byte (e.g. Ctrl-U = 0x15).
216    pub key: u8,
217    pub action: BindAction,
218}
219
220#[derive(Debug, Clone, PartialEq, Eq)]
221pub enum BindAction {
222    /// Set an `input .name` widget's value — with `out { … apply .name }` this
223    /// reshapes the live pipe on a keystroke (a keyboard-driven megafilter/map).
224    SetInput { name: String, value: String },
225    /// Quit the TUI.
226    Quit,
227    /// Ring the terminal bell (write 0x07 after the next draw).
228    Beep,
229    /// Flash a message in the status bar for a few seconds.
230    Alert(String),
231    /// Tint a widget's border/accent for a few seconds. `widget` is the path
232    /// without the leading dot; `color` is a color name (green/red/…).
233    Flash { widget: String, color: String },
234    /// Run a shell command, fire-and-forget (never waits, never blocks the loop).
235    Exec(String),
236    /// Write text to a `spawn -pty` child's stdin — the Expect `send`. No-op
237    /// unless the stream source is a PTY. Include `\n` to submit a line.
238    Send(String),
239    /// `tell REF MSG(args)` — post a message to a session actor/pool, fire-and-
240    /// forget (SPEC §15). `call` is the raw `MSG(args)` text, parsed + evaluated
241    /// (with live control substitution) when the action fires.
242    ActorTell { refname: String, call: String },
243    /// `ask .CTRL REF MSG(args)` — ask a session actor/pool and store the reply
244    /// into control `ctrl` (so a widget bound to it shows the result).
245    ActorAsk {
246        ctrl: String,
247        refname: String,
248        call: String,
249    },
250    /// Run several actions in order (block form `{ alert "x"; beep }`).
251    Seq(Vec<BindAction>),
252}
253
254/// A mouse trigger for a `bind <…> ACTION` (Tk-style events). Extensible; only
255/// `Click` (any button press) ships today.
256#[derive(Debug, Clone, Copy, PartialEq, Eq)]
257pub enum MouseTrigger {
258    Click,
259}
260
261/// Parse a key spec to its raw byte. Accepts control-key forms (`C-u`, `c-u`,
262/// `^u`) and the Tk named keys `<Enter>`/`<Esc>`/`<Tab>` and `<Key-X>` (a single
263/// letter). Only these forms bind, so a bind never shadows plain filter typing.
264pub fn parse_key(spec: &str) -> Option<u8> {
265    match spec {
266        "<Enter>" | "<Return>" => return Some(0x0d),
267        "<Esc>" | "<Escape>" => return Some(0x1b),
268        "<Tab>" => return Some(0x09),
269        _ => {}
270    }
271    // `<Key-x>` -> the literal letter byte.
272    if let Some(inner) = spec.strip_prefix("<Key-").and_then(|s| s.strip_suffix('>')) {
273        let ch = inner.chars().next()?;
274        if inner.chars().count() == 1 && ch.is_ascii_alphabetic() {
275            return Some(ch as u8);
276        }
277        return None;
278    }
279    let letter = spec
280        .strip_prefix("C-")
281        .or_else(|| spec.strip_prefix("c-"))
282        .or_else(|| spec.strip_prefix('^'))?;
283    let ch = letter.chars().next()?;
284    if letter.chars().count() != 1 || !ch.is_ascii_alphabetic() {
285        return None;
286    }
287    Some((ch.to_ascii_uppercase() as u8) & 0x1f)
288}
289
290/// Parse a `Ns`/`Nms`/`Nm` duration literal (SPEC §3) into a `Duration`.
291/// `ms` is matched before the bare `s` so `500ms` is not read as `500` seconds.
292pub fn parse_duration(s: &str) -> Option<Duration> {
293    let s = s.trim();
294    if let Some(n) = s.strip_suffix("ms") {
295        return n.trim().parse::<u64>().ok().map(Duration::from_millis);
296    }
297    if let Some(n) = s.strip_suffix('s') {
298        return n.trim().parse::<f64>().ok().map(Duration::from_secs_f64);
299    }
300    if let Some(n) = s.strip_suffix('m') {
301        return n
302            .trim()
303            .parse::<f64>()
304            .ok()
305            .map(|m| Duration::from_secs_f64(m * 60.0));
306    }
307    None
308}
309
310/// An event-driven reaction: when a stream line matches `pattern`, fire `action`.
311/// Declared `expect /regex/ <action>` — the "react" half of Expect. Reuses
312/// [`BindAction`], so a matching line can set a control or quit.
313#[derive(Debug, Clone)]
314pub struct Expect {
315    pub pattern: Regex,
316    pub action: BindAction,
317}
318
319/// An idle reaction (SPEC §13): when the input stream produces no new line for
320/// `dur`, fire `action`. Latched once per idle span, re-armed on the next line.
321/// Reuses [`BindAction`] exactly like [`Expect`], so `timeout 5s quit` works.
322#[derive(Debug, Clone)]
323pub struct Timeout {
324    pub dur: Duration,
325    pub action: BindAction,
326}
327
328/// Parse an action clause (`set .name VALUE…` | `quit`) shared by `bind` and
329/// `expect`. `params` is the args AFTER the action verb.
330fn parse_action(verb: &str, params: &[Arg]) -> Result<BindAction, String> {
331    // The space-joined string params (used by alert/exec/set values).
332    let joined = || {
333        params
334            .iter()
335            .filter_map(Arg::as_str)
336            .collect::<Vec<_>>()
337            .join(" ")
338    };
339    match verb {
340        "quit" => Ok(BindAction::Quit),
341        "beep" => Ok(BindAction::Beep),
342        "alert" => Ok(BindAction::Alert(joined())),
343        "exec" => {
344            let cmd = joined();
345            if cmd.is_empty() {
346                return Err("exec: missing command".into());
347            }
348            Ok(BindAction::Exec(cmd))
349        }
350        "send" => {
351            let text = joined();
352            if text.is_empty() {
353                return Err("send: missing text".into());
354            }
355            // The lexer already turns `\n`/`\t` in a quoted string into the real
356            // char, and (like Expect) `send` never auto-appends — so `send "y\n"`
357            // submits a line, `send "y"` leaves the cursor on the same line.
358            Ok(BindAction::Send(text))
359        }
360        "flash" => {
361            let widget = params
362                .first()
363                .and_then(Arg::as_str)
364                .ok_or("flash: missing widget (.name)")?;
365            let widget = widget.strip_prefix('.').unwrap_or(widget).to_string();
366            let color = params
367                .get(1)
368                .and_then(Arg::as_str)
369                .unwrap_or("yellow")
370                .to_string();
371            Ok(BindAction::Flash { widget, color })
372        }
373        "set" => {
374            let name = params
375                .first()
376                .and_then(Arg::as_str)
377                .ok_or("set: missing input name (.name)")?;
378            let name = name.strip_prefix('.').unwrap_or(name).to_string();
379            let value = params[1..]
380                .iter()
381                .filter_map(Arg::as_str)
382                .collect::<Vec<_>>()
383                .join(" ");
384            Ok(BindAction::SetInput { name, value })
385        }
386        "tell" => {
387            // `tell REF MSG(args)` — the message tell of the actor system (§15).
388            // `send` stays the Expect PTY action; `tell` avoids the collision.
389            let refname = params
390                .first()
391                .and_then(Arg::as_str)
392                .ok_or("tell: expected `tell REF MSG(args)`")?
393                .to_string();
394            let call = params[1..]
395                .iter()
396                .filter_map(Arg::as_str)
397                .collect::<Vec<_>>()
398                .join(" ");
399            if call.trim().is_empty() {
400                return Err("tell: missing message (`tell REF MSG(args)`)".into());
401            }
402            // Validate the call shape now so a typo is a build error, not silent.
403            crate::actor::parse_call(&call)?;
404            Ok(BindAction::ActorTell { refname, call })
405        }
406        "ask" => {
407            // `ask .CTRL REF MSG(args)` — ask a ref, store the reply into control CTRL.
408            let ctrl = params
409                .first()
410                .and_then(Arg::as_str)
411                .ok_or("ask: expected `ask .CTRL REF MSG(args)`")?;
412            let ctrl = ctrl.strip_prefix('.').unwrap_or(ctrl).to_string();
413            let refname = params
414                .get(1)
415                .and_then(Arg::as_str)
416                .ok_or("ask: missing ref (`ask .CTRL REF MSG(args)`)")?
417                .to_string();
418            let call = params[2..]
419                .iter()
420                .filter_map(Arg::as_str)
421                .collect::<Vec<_>>()
422                .join(" ");
423            if call.trim().is_empty() {
424                return Err("ask: missing message (`ask .CTRL REF MSG(args)`)".into());
425            }
426            crate::actor::parse_call(&call)?;
427            Ok(BindAction::ActorAsk {
428                ctrl,
429                refname,
430                call,
431            })
432        }
433        other => Err(format!(
434            "unknown action `{other}` (set | quit | beep | alert | flash | exec | tell | ask)"
435        )),
436    }
437}
438
439/// Parse a `spawn NAME = ACTOR(init)` or `pool NAME = ACTOR * N` binding into a
440/// [`crate::actor::RefDecl`]. `verb` is `spawn`/`pool`; the actor must already be
441/// declared. Both forms share `NAME = RHS`; a `pool` (or `RHS` with `* N`) sets
442/// the pool width.
443fn parse_actor_ref(
444    verb: &str,
445    args: &[Arg],
446    actors: &BTreeMap<String, Arc<ActorDef>>,
447) -> Result<crate::actor::RefDecl, String> {
448    let name = args
449        .first()
450        .and_then(Arg::as_str)
451        .ok_or_else(|| format!("{verb}: expected `{verb} NAME = ACTOR…`"))?
452        .to_string();
453    if args.get(1).and_then(Arg::as_str) != Some("=") {
454        return Err(format!("{verb}: expected `=` (`{verb} NAME = ACTOR…`)"));
455    }
456    // RHS: `ACTOR(init)` and/or `* N`, joined so spaces don't matter.
457    let rhs = args[2..]
458        .iter()
459        .filter_map(Arg::as_str)
460        .collect::<Vec<_>>()
461        .join(" ");
462    if rhs.trim().is_empty() {
463        return Err(format!("{verb}: missing actor (`{verb} {name} = ACTOR…`)"));
464    }
465    // Split off a `* N` pool width (from the verb or the RHS).
466    let (head, pool) = match rhs.split_once('*') {
467        Some((h, n)) => {
468            let n = n
469                .trim()
470                .parse::<usize>()
471                .map_err(|_| format!("{verb}: `* {}` is not a pool size", n.trim()))?;
472            (h.trim().to_string(), Some(n.min(1024)))
473        }
474        None => (rhs.trim().to_string(), None),
475    };
476    // `pool NAME = ACTOR` (no explicit `* N`) still means a pool — default width
477    // is filled in at spawn time (one per hardware thread) via `pool: Some(0)`.
478    let pool = match (verb, pool) {
479        (_, Some(n)) => Some(n),
480        ("pool", None) => Some(0),
481        _ => None,
482    };
483    // `head` is `ACTOR(init)` — reuse the actor-call splitter for name + init.
484    let (actor, init_exprs) = crate::actor::parse_call(&head)?;
485    if !actors.contains_key(&actor) {
486        return Err(format!(
487            "{verb}: no actor named `{actor}` in scope (declare `actor {actor}(state) {{ … }}` first)"
488        ));
489    }
490    // Initial state is a constant expression evaluated now (`worker(3)` -> 3).
491    let init = match init_exprs.as_slice() {
492        [] => 0.0,
493        [e] => crate::expr::eval(e, 0.0).unwrap_or(0.0),
494        _ => return Err(format!("{verb}: `{actor}(…)` takes a single init value")),
495    };
496    Ok(crate::actor::RefDecl {
497        name,
498        actor,
499        init,
500        pool,
501        restart: true,
502    })
503}
504
505/// Apply a `supervise NAME { on crash { restart | stop } }` policy to an already-
506/// declared ref: `stop` turns off respawn (fail-stop), `restart` (the default)
507/// leaves it on.
508fn apply_supervise(args: &[Arg], refs: &mut [crate::actor::RefDecl]) -> Result<(), String> {
509    let name = args
510        .first()
511        .and_then(Arg::as_str)
512        .ok_or("supervise: expected `supervise NAME { on crash { restart | stop } }`")?;
513    let body = match args.get(1) {
514        Some(Arg::Block(b)) => b,
515        _ => return Err("supervise: expected `{ on crash { restart | stop } }`".into()),
516    };
517    let decl = refs
518        .iter_mut()
519        .find(|r| r.name == name)
520        .ok_or_else(|| format!("supervise: no ref named `{name}` (spawn/pool it first)"))?;
521    for clause in body {
522        if clause.name != "on" || clause.args.first().and_then(Arg::as_str) != Some("crash") {
523            return Err("supervise: only `on crash { … }` is supported".into());
524        }
525        let policy = match clause.args.get(1) {
526            Some(Arg::Block(b)) => b
527                .first()
528                .map(|c| c.name.as_str())
529                .ok_or("supervise: `on crash { }` needs `restart` or `stop`")?,
530            _ => return Err("supervise: `on crash` needs a `{ restart | stop }` body".into()),
531        };
532        match policy {
533            "restart" => decl.restart = true,
534            "stop" => decl.restart = false,
535            other => {
536                return Err(format!(
537                    "supervise: unknown crash policy `{other}` (restart | stop)"
538                ))
539            }
540        }
541    }
542    Ok(())
543}
544
545/// Parse a block-form action body (`{ alert "x"; beep; flash .w red }`) into a
546/// `Seq` — each top-level command is one action, run in order.
547fn parse_action_block(cmds: &[Command]) -> Result<BindAction, String> {
548    let actions = cmds
549        .iter()
550        .map(|c| parse_action(&c.name, &c.args))
551        .collect::<Result<Vec<_>, _>>()?;
552    Ok(BindAction::Seq(actions))
553}
554
555/// Parse the action clause of a `bind`/`expect`: either a `{ … }` block (→ Seq)
556/// or the single-line `verb params…` form. `rest` is the args after the key/regex.
557fn parse_bind_or_expect_action(rest: &[Arg]) -> Result<BindAction, String> {
558    match rest.first() {
559        Some(Arg::Block(cmds)) => parse_action_block(cmds),
560        Some(_) => {
561            let verb = rest[0].as_str().unwrap_or("");
562            parse_action(verb, &rest[1..])
563        }
564        None => Err("missing action (set | quit | beep | alert | flash | exec | { … })".into()),
565    }
566}
567
568#[derive(Debug, Default)]
569pub struct Spec {
570    pub widgets: Vec<Widget>,
571    /// Downstream output pipeline (`out { … }`): applied to the stream and
572    /// written to stdout, so arb can *modify* a pipe, not just visualize it.
573    pub out: Option<Vec<QueryOp>>,
574    /// Key bindings (`bind C-<letter> <action>`).
575    pub binds: Vec<Bind>,
576    /// Event-driven reactions (`expect /re/ <action>`).
577    pub expects: Vec<Expect>,
578    /// Idle reactions (`timeout Ns <action>`).
579    pub timeouts: Vec<Timeout>,
580    /// Mouse reactions (`bind <Click> <action>`).
581    pub mouse_binds: Vec<(MouseTrigger, BindAction)>,
582    /// Terminal-resize reactions (`bind <Resize> <action>`).
583    pub resize_binds: Vec<BindAction>,
584    /// Input-source command (`spawn CMD` / `spawn { CMD }`, SPEC §7): arb
585    /// launches CMD via `sh -c` and feeds its stdout into the stream in place of
586    /// stdin (fire-and-forget; child detached, dies with arb). CLI `--run` wins
587    /// if both are given. The interactive `send`/PTY react leg + `.ps.sel`
588    /// selection widget are deferred. `None` = read stdin.
589    pub spawn: Option<String>,
590    /// Input-source file (`< FILE`, SPEC §7): read FILE as the stream in place
591    /// of stdin. Folded into the producer as `cat -- FILE` in main. Mutually
592    /// exclusive with `spawn` (and `--run`). `None` = read stdin.
593    pub source_file: Option<String>,
594    /// Poll source (`! CMD every Ns`, SPEC §7): re-run CMD via `sh -c` every
595    /// interval, feeding each run's stdout into the stream. The interactive/serve
596    /// loop runs in a background thread; the headless path runs CMD once (a
597    /// reducer over an endless source can't terminate). `None` = read stdin.
598    pub poll: Option<(String, Duration)>,
599    /// In-language unit tests (`test "NAME" { given …; run { … }; want … }`):
600    /// feed sample lines through a query pipeline and assert the output. Run
601    /// headlessly by `arb --test`; ignored by every other mode.
602    pub tests: Vec<TestCase>,
603    /// `spawn -pty CMD`: run the spawn command on a pseudo-terminal (so it acts
604    /// interactive) and keep a writer to its stdin for the `send` action. Only
605    /// meaningful with `spawn` set and in the interactive TUI.
606    pub spawn_pty: bool,
607    /// `actor NAME(state) { on MSG { … } }` declarations, by name. A `via NAME`
608    /// pipeline op resolves against this registry at build time (SPEC §15).
609    pub actors: BTreeMap<String, Arc<ActorDef>>,
610    /// `spawn NAME = ACTOR(init)` / `pool NAME = ACTOR * N` session bindings, in
611    /// declaration order. The TUI spawns these once at startup; `tell`/`ask` bind
612    /// actions drive them (SPEC §15).
613    pub actor_refs: Vec<crate::actor::RefDecl>,
614    /// `rows "1 2 1"` — the grid's row track sizes (`None` = uniform). A track is
615    /// `N` (fixed cells), `N%` (percentage), or `N*`/`*` (weight, proportional).
616    pub row_tracks: Option<Vec<Track>>,
617    /// `cols "20 * 2*"` — the grid's column track sizes (`None` = uniform).
618    pub col_tracks: Option<Vec<Track>>,
619    /// `gap N` — blank cells between grid rows/columns (default 0).
620    pub gap: u16,
621    /// `layout horizontal|vertical` — the no-grid auto-tile direction (default
622    /// vertical). Ignored once any widget declares a grid cell.
623    pub flow: Flow,
624    /// `theme NAME` / `theme custom c1..c6` — the active color palette (one of the
625    /// 31 built-ins or a custom 6-index palette). `None` = no directive: `main`
626    /// resolves the default (`--theme` → `~/.arb` config → baked `neon-sprawl`).
627    pub theme: Option<crate::theme::Palette>,
628    /// `theme off`/`none` — opt out of theming to the classic cyan scheme; stops
629    /// `main` from applying the config/baked default.
630    pub theme_off: bool,
631}
632
633/// A layout track size (a grid row/column). Maps to a ratatui `Constraint`.
634#[derive(Debug, Clone, Copy, PartialEq, Eq)]
635pub enum Track {
636    /// `N` — a fixed cell count (`Constraint::Length`).
637    Length(u16),
638    /// `N%` — a percentage of the axis (`Constraint::Percentage`).
639    Percentage(u16),
640    /// `N*` / `*` — a proportional weight; remaining space splits by weight
641    /// (`Constraint::Fill`). Bare `*` is weight 1.
642    Fill(u16),
643}
644
645/// The auto-tile direction when no widget declares a grid cell.
646#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
647pub enum Flow {
648    #[default]
649    Vertical,
650    Horizontal,
651}
652
653/// Parse a track spec (`"1 2 1"` / `"20c * 2*"`) into a track list. A **bare
654/// integer is a proportional weight** (`1 2 1` = a 1:2:1 split — the common case);
655/// `N*` / `*` is the same explicit weight; `N%` is a percentage of the axis; and
656/// `Nc` is a fixed cell count. Empty/invalid tokens are an error.
657pub fn parse_tracks(spec: &str) -> Result<Vec<Track>, String> {
658    let mut out = Vec::new();
659    for tok in spec.split_whitespace() {
660        let track = if let Some(pct) = tok.strip_suffix('%') {
661            Track::Percentage(
662                pct.parse::<u16>()
663                    .map_err(|_| format!("track: bad percentage `{tok}`"))?
664                    .min(100),
665            )
666        } else if let Some(cells) = tok.strip_suffix('c') {
667            Track::Length(
668                cells
669                    .parse::<u16>()
670                    .map_err(|_| format!("track: bad cell count `{tok}`"))?,
671            )
672        } else {
673            // Bare `N`, `N*`, or `*` — a proportional weight (`*` = 1).
674            let w = tok.strip_suffix('*').unwrap_or(tok);
675            let weight = if w.is_empty() {
676                1
677            } else {
678                w.parse::<u16>()
679                    .map_err(|_| format!("track: bad weight `{tok}` (use N, N%, N*, or Nc)"))?
680                    .max(1)
681            };
682            Track::Fill(weight)
683        };
684        out.push(track);
685    }
686    if out.is_empty() {
687        return Err("track spec is empty".into());
688    }
689    Ok(out)
690}
691
692/// One in-language test case: feed `given` lines through the `run` pipeline
693/// (`ops`) and assert the flattened output equals `want`. Purely headless —
694/// evaluated via [`crate::query::eval`], the same path the widgets use.
695#[derive(Debug, Clone)]
696pub struct TestCase {
697    pub name: String,
698    pub given: Vec<String>,
699    pub ops: Vec<QueryOp>,
700    pub want: Vec<String>,
701}
702
703/// True if any single-stream input source (`spawn`/`< file`/`! poll`) is already
704/// set — only one may feed the stream.
705fn stream_source_set(s: &Spec) -> bool {
706    s.spawn.is_some() || s.source_file.is_some() || s.poll.is_some()
707}
708
709/// Build a `Spec` from a parsed command tree.
710pub fn build(cmds: &[Command]) -> Result<Spec, crate::err::SpecError> {
711    let mut spec = Spec::default();
712    build_into(&mut spec, cmds, 0)?;
713    Ok(spec)
714}
715
716/// Resolve `apply .name` placeholders against live `input` widget values: each
717/// `Apply(name)` is replaced by the query pipeline parsed from that input's
718/// current text (empty/invalid → dropped). Called every render frame so a
719/// before/after transform pane updates as the user edits the input.
720pub fn resolve_pipeline(
721    ops: &[QueryOp],
722    inputs: &std::collections::HashMap<String, String>,
723) -> Vec<QueryOp> {
724    // Resolve a control name to its live numeric value (empty/non-numeric -> None)
725    // or its raw string value (for `match`/`in .set` string predicates).
726    let num = |n: &str| -> Option<f64> { inputs.get(n).and_then(|v| v.trim().parse::<f64>().ok()) };
727    let strv = |n: &str| -> Option<String> { inputs.get(n).cloned() };
728    let mut out = Vec::with_capacity(ops.len());
729    for op in ops {
730        match op {
731            QueryOp::Apply(name) => {
732                if let Some(val) = inputs.get(name).filter(|v| !v.trim().is_empty()) {
733                    // Parse the input text as a pipeline body (prefix `in;` so it
734                    // is a valid source body) and splice its ops in.
735                    // A live `apply` input is typed at render time, before any
736                    // actor is in scope — `via` there resolves against an empty
737                    // registry (unknown-actor errors just drop the transform).
738                    if let Ok(cmds) = crate::parser::parse(&format!("in; {val}")) {
739                        if let Ok(sub) = pipeline_from_body(&cmds, &BTreeMap::new()) {
740                            out.extend(sub);
741                        }
742                    }
743                }
744            }
745            // `where lat < .th` (numeric) / `where match(.q)` / `where lvl in .lv`
746            // (string). Numeric controls must all resolve or the filter is dropped
747            // (unset threshold = no filter); string controls with an empty value
748            // simply match everything, so they never force a drop.
749            QueryOp::Where(e) => {
750                let (mut nums, mut strs) = (Vec::new(), Vec::new());
751                crate::expr::control_names_typed(e, &mut nums, &mut strs);
752                if nums.is_empty() && strs.is_empty() {
753                    out.push(op.clone());
754                } else if nums.iter().all(|n| num(n).is_some()) {
755                    out.push(QueryOp::Where(crate::expr::substitute_controls(
756                        e, &num, &strv,
757                    )));
758                }
759                // else: a numeric control is unset -> drop this `where`.
760            }
761            // `map(x * .k)`: substitute resolvable controls; an unresolved one
762            // stays a control (-> NaN) rather than dropping the transform.
763            QueryOp::Map(e) => {
764                out.push(QueryOp::Map(crate::expr::substitute_controls(
765                    e, &num, &strv,
766                )));
767            }
768            other => out.push(other.clone()),
769        }
770    }
771    out
772}
773
774// ---- `import X as Y` namespacing ------------------------------------------
775// A module built into a fresh sub-Spec has its render-time NAME references
776// (widget paths, `apply`, control refs, `set`/`flash` targets) prefixed with the
777// alias, then merged in. Intra-module by-path refs (source/search/grid/configure)
778// already resolved during the fresh build, so only these string names remain.
779
780/// Namespace a control/input name: `cpu` -> `g.cpu`.
781fn prefix_name(name: &str, ns: &str) -> String {
782    format!("{ns}.{name}")
783}
784
785/// Namespace `apply`/`where`/`map`/`calc` references in a query pipeline.
786fn prefix_pipeline(ops: &mut [QueryOp], ns: &str) {
787    for op in ops {
788        match op {
789            QueryOp::Apply(n) => *n = prefix_name(n, ns),
790            QueryOp::Where(e) | QueryOp::Map(e) | QueryOp::Calc(e) => {
791                crate::expr::prefix_controls(e, ns)
792            }
793            _ => {}
794        }
795    }
796}
797
798/// Namespace the widget/control names an action targets.
799fn prefix_action(a: &mut BindAction, ns: &str) {
800    match a {
801        BindAction::SetInput { name, .. } => *name = prefix_name(name, ns),
802        BindAction::Flash { widget, .. } => *widget = prefix_name(widget, ns),
803        // A module's `tell`/`ask` targets its own (now-namespaced) ref; `ask` also
804        // writes a namespaced control.
805        BindAction::ActorTell { refname, .. } => *refname = prefix_name(refname, ns),
806        BindAction::ActorAsk { ctrl, refname, .. } => {
807            *ctrl = prefix_name(ctrl, ns);
808            *refname = prefix_name(refname, ns);
809        }
810        BindAction::Seq(v) => v.iter_mut().for_each(|x| prefix_action(x, ns)),
811        _ => {}
812    }
813}
814
815/// Prefix every render-time name in a freshly-built module Spec with `ns`.
816fn prefix_spec(sub: &mut Spec, ns: &str) {
817    for w in &mut sub.widgets {
818        w.path = format!(".{ns}.{}", w.path.trim_start_matches('.'));
819        if let Some(s) = &mut w.source {
820            prefix_pipeline(&mut s.pipeline, ns);
821        }
822        if let Some(p) = &mut w.search {
823            prefix_pipeline(p, ns);
824        }
825    }
826    for b in &mut sub.binds {
827        prefix_action(&mut b.action, ns);
828    }
829    for e in &mut sub.expects {
830        prefix_action(&mut e.action, ns);
831    }
832    for t in &mut sub.timeouts {
833        prefix_action(&mut t.action, ns);
834    }
835    for (_, a) in &mut sub.mouse_binds {
836        prefix_action(a, ns);
837    }
838    for a in &mut sub.resize_binds {
839        prefix_action(a, ns);
840    }
841    if let Some(out) = &mut sub.out {
842        prefix_pipeline(out, ns);
843    }
844    // Session refs: namespace the binding name and the actor it runs, so `.ns.w`
845    // is distinct and its (also-prefixed) actor resolves after merge.
846    for r in &mut sub.actor_refs {
847        r.name = prefix_name(&r.name, ns);
848        r.actor = prefix_name(&r.actor, ns);
849    }
850}
851
852/// Merge a namespaced module Spec into `dst`.
853fn merge_spec(dst: &mut Spec, src: Spec, ns: &str) -> Result<(), String> {
854    dst.widgets.extend(src.widgets);
855    dst.binds.extend(src.binds);
856    dst.expects.extend(src.expects);
857    dst.timeouts.extend(src.timeouts);
858    dst.mouse_binds.extend(src.mouse_binds);
859    dst.resize_binds.extend(src.resize_binds);
860    dst.tests.extend(src.tests);
861    // A namespaced module's `via` ops already embed their resolved `Arc<ActorDef>`
862    // (bound during the fresh sub-build), so they work post-merge. Carry the defs
863    // under `ns.NAME` keys so they don't collide with the host's actors.
864    for (name, def) in src.actors {
865        dst.actors.insert(prefix_name(&name, ns), def);
866    }
867    // Session refs already namespaced by `prefix_spec`; carry them over.
868    dst.actor_refs.extend(src.actor_refs);
869    // A module's `theme` applies only when the host hasn't set one (host wins).
870    if dst.theme.is_none() {
871        dst.theme = src.theme;
872    }
873    if let Some(out) = src.out {
874        if dst.out.is_some() {
875            return Err(format!(
876                "import: `{ns}` defines `out`, but one is already set"
877            ));
878        }
879        dst.out = Some(out);
880    }
881    if let Some(sp) = src.spawn {
882        if stream_source_set(dst) {
883            return Err(format!(
884                "import: `{ns}` defines a spawn source, but one is already set"
885            ));
886        }
887        dst.spawn = Some(sp);
888        dst.spawn_pty = src.spawn_pty;
889    }
890    if let Some(f) = src.source_file {
891        if stream_source_set(dst) {
892            return Err(format!(
893                "import: `{ns}` defines a `<` file source, but one is already set"
894            ));
895        }
896        dst.source_file = Some(f);
897    }
898    if let Some(p) = src.poll {
899        if stream_source_set(dst) {
900            return Err(format!(
901                "import: `{ns}` defines a `!` poll source, but one is already set"
902            ));
903        }
904        dst.poll = Some(p);
905    }
906    Ok(())
907}
908
909/// Process `cmds` into `spec`. `import NAME` resolves and inlines a module
910/// (stdlib preset or user file); `depth` guards against import cycles.
911fn build_into(
912    spec: &mut Spec,
913    cmds: &[Command],
914    depth: usize,
915) -> Result<(), crate::err::SpecError> {
916    if depth > 16 {
917        return Err("import: module nesting too deep (cycle?)".into());
918    }
919    for c in cmds {
920        // Process one command; a returned error with no span yet is anchored to
921        // this command's verb (its char offset) so the LSP points at the line.
922        let res: Result<(), crate::err::SpecError> = (|| -> Result<(), crate::err::SpecError> {
923            if c.name == "import" {
924                let name = c
925                    .args
926                    .first()
927                    .and_then(Arg::as_str)
928                    .ok_or("import: missing module name")?;
929                // `import X as Y`: build the module into a fresh sub-Spec (so its
930                // intra-module by-path refs resolve), namespace every render-time
931                // name with `Y`, then merge — so `.Y.foo` and its controls resolve.
932                if c.args.get(1).and_then(Arg::as_str) == Some("as") {
933                    let alias = c
934                        .args
935                        .get(2)
936                        .and_then(Arg::as_str)
937                        .ok_or("import: `as` requires an alias (import X as Y)")?;
938                    if alias.is_empty() || alias.contains(['.', '/', ' ']) {
939                        return Err(format!("import: invalid namespace alias `{alias}`").into());
940                    }
941                    let src = resolve_module(name)?;
942                    let sub_cmds = crate::parser::parse(&src)?;
943                    let mut sub = Spec::default();
944                    build_into(&mut sub, &sub_cmds, depth + 1)?;
945                    prefix_spec(&mut sub, alias);
946                    merge_spec(spec, sub, alias)?;
947                } else {
948                    let src = resolve_module(name)?;
949                    let sub = crate::parser::parse(&src)?;
950                    build_into(spec, &sub, depth + 1)?;
951                }
952            } else if c.name == "actor" {
953                // `actor NAME(state) { on MSG(p) { … } }` — a message-handling
954                // behavior (SPEC §15). Stored by name; a `via NAME` pipeline op
955                // fans the stream across a pool of it.
956                let def = crate::actor::parse_actor(&c.args)?;
957                spec.actors.insert(def.name.clone(), Arc::new(def));
958            } else if c.name == "__rust_compile" {
959                // Desugared `rust { ... }` block (see `rust_ffi`): compile the
960                // base64 body to a cached cdylib and register its exports, so a
961                // later `name(args)` call in a where/map/calc expression resolves.
962                // Runs at build time, before any render-time expression eval.
963                let b64 = c
964                    .args
965                    .first()
966                    .and_then(Arg::as_str)
967                    .ok_or("__rust_compile: missing block body")?;
968                fusevm::ffi::compile_and_register(b64).map_err(crate::err::SpecError::from)?;
969            } else if let Some(kind) = WidgetKind::from(&c.name) {
970                let path = c
971                    .args
972                    .first()
973                    .and_then(Arg::as_str)
974                    .ok_or_else(|| format!("{}: missing widget path", c.name))?;
975                if !path.starts_with('.') {
976                    return Err(format!(
977                        "{}: widget path must start with '.', got `{path}`",
978                        c.name
979                    )
980                    .into());
981                }
982                spec.widgets.push(Widget {
983                    path: path.to_string(),
984                    kind,
985                    opts: parse_opts(&c.args[1..]),
986                    source: None,
987                    search: None,
988                    grid: None,
989                    span: (1, 1),
990                });
991            } else if c.name == "source" {
992                let path = c
993                    .args
994                    .first()
995                    .and_then(Arg::as_str)
996                    .ok_or("source: missing path")?;
997                let body = match c.args.get(1) {
998                    Some(Arg::Block(b)) => b,
999                    _ => return Err("source: expected `{ body }`".into()),
1000                };
1001                let pipeline = pipeline_from_body(body, &spec.actors)?;
1002                set_source(spec, path, Source { pipeline })?;
1003            } else if c.name == "search" {
1004                // `search .name { in; … }` — a select widget's fuzzy-match key
1005                // pipeline (fzf --nth). The row still shows/emits its `source`.
1006                let path = c
1007                    .args
1008                    .first()
1009                    .and_then(Arg::as_str)
1010                    .ok_or("search: missing path")?;
1011                let body = match c.args.get(1) {
1012                    Some(Arg::Block(b)) => b,
1013                    _ => return Err("search: expected `{ body }`".into()),
1014                };
1015                let pipeline = pipeline_from_body(body, &spec.actors)?;
1016                set_search(spec, path, pipeline)?;
1017            } else if c.name == "bind" {
1018                // `bind KEY ACTION` — KEY is a control key (`C-<letter>`, `<Enter>`…),
1019                // a mouse event (`<Click>`), or `<Resize>`; ACTION is a single verb or
1020                // a `{ … }` block.
1021                let keyspec = c
1022                    .args
1023                    .first()
1024                    .and_then(Arg::as_str)
1025                    .ok_or("bind: missing key (e.g. C-u, <Click>)")?;
1026                let action =
1027                    parse_bind_or_expect_action(&c.args[1..]).map_err(|e| format!("bind: {e}"))?;
1028                match keyspec {
1029                    "<Click>" | "<Button-1>" => {
1030                        spec.mouse_binds.push((MouseTrigger::Click, action))
1031                    }
1032                    "<Resize>" | "<Configure>" => spec.resize_binds.push(action),
1033                    _ => {
1034                        let key = parse_key(keyspec).ok_or_else(|| {
1035                        format!("bind: `{keyspec}` is not a bindable key (use C-<letter>, <Enter>/<Esc>/<Tab>/<Key-x>, <Click>, <Resize>)")
1036                    })?;
1037                        spec.binds.push(Bind { key, action });
1038                    }
1039                }
1040            } else if c.name == "expect" {
1041                match c.args.first() {
1042                    // Block form `expect { /re/ ACTION; /re2/ ACTION }` (Tcl Expect's
1043                    // multi-pattern block): each inner command is one clause — its
1044                    // NAME is the /regex/, its args are the ACTION. Emit one Expect
1045                    // per clause; all fire live per line (tui.rs loops every entry).
1046                    Some(Arg::Block(clauses)) => {
1047                        for clause in clauses {
1048                            let pattern =
1049                                compile_regex(&clause.name).map_err(|e| format!("expect: {e}"))?;
1050                            let action = parse_bind_or_expect_action(&clause.args)
1051                                .map_err(|e| format!("expect: {e}"))?;
1052                            spec.expects.push(Expect { pattern, action });
1053                        }
1054                    }
1055                    // Single-clause form `expect /regex/ ACTION` — ACTION as for `bind`.
1056                    _ => {
1057                        let pattern = regex_arg(c)?;
1058                        let action = parse_bind_or_expect_action(&c.args[1..])
1059                            .map_err(|e| format!("expect: {e}"))?;
1060                        spec.expects.push(Expect { pattern, action });
1061                    }
1062                }
1063            } else if c.name == "timeout" {
1064                // `timeout Ns ACTION` — fire ACTION when the stream goes idle for Ns.
1065                let dspec = c
1066                    .args
1067                    .first()
1068                    .and_then(Arg::as_str)
1069                    .ok_or("timeout: missing duration (e.g. 5s, 500ms)")?;
1070                let dur = parse_duration(dspec).ok_or_else(|| {
1071                    format!("timeout: `{dspec}` is not a duration (use Ns/Nms/Nm)")
1072                })?;
1073                let action = parse_bind_or_expect_action(&c.args[1..])
1074                    .map_err(|e| format!("timeout: {e}"))?;
1075                spec.timeouts.push(Timeout { dur, action });
1076            } else if c.name == "out" {
1077                let body = match c.args.first() {
1078                    Some(Arg::Block(b)) => b,
1079                    _ => return Err("out: expected `{ body }`".into()),
1080                };
1081                let pipeline = pipeline_from_body(body, &spec.actors)?;
1082                spec.out = Some(pipeline);
1083            } else if c.name == "test" {
1084                // `test "NAME" { given …; run { in; … }; want … }` — an
1085                // in-language unit test, run headlessly by `arb --test`.
1086                let name = c
1087                    .args
1088                    .first()
1089                    .and_then(Arg::as_str)
1090                    .ok_or("test: expected a name — `test \"NAME\" { … }`")?
1091                    .to_string();
1092                let body = match c.args.get(1) {
1093                    Some(Arg::Block(b)) => b,
1094                    _ => return Err("test: expected `{ given …; run { … }; want … }`".into()),
1095                };
1096                let tc = parse_test_case(name, body, &spec.actors)?;
1097                spec.tests.push(tc);
1098            } else if c.name == "spawn" && c.args.get(1).and_then(Arg::as_str) == Some("=") {
1099                // `spawn NAME = ACTOR(init)` — a session actor binding (§15),
1100                // distinct from the `spawn CMD` process source (disambiguated by
1101                // the `=` second token). `tell`/`ask` drive it.
1102                let decl = parse_actor_ref(&c.name, &c.args, &spec.actors)?;
1103                spec.actor_refs.push(decl);
1104            } else if c.name == "pool" {
1105                // `pool NAME = ACTOR * N` — a supervised session pool binding.
1106                let decl = parse_actor_ref(&c.name, &c.args, &spec.actors)?;
1107                spec.actor_refs.push(decl);
1108            } else if c.name == "supervise" {
1109                // `supervise NAME { on crash { restart | stop } }` — set a ref's
1110                // restart policy. Default is restart (respawn a dead worker); a
1111                // `stop` clause makes the pool fail-stop.
1112                apply_supervise(&c.args, &mut spec.actor_refs)?;
1113            } else if c.name == "spawn" {
1114                // `spawn CMD…` or `spawn { CMD }`: launch CMD via `sh -c` and use
1115                // its stdout as the stream (input source, in place of stdin). A
1116                // leading `-pty` runs CMD on a pseudo-terminal so it behaves as if
1117                // interactive and `send "…"` can drive its stdin (Expect).
1118                let args = c.args.as_slice();
1119                let (pty, args) = match args.first().and_then(Arg::as_str) {
1120                    Some("-pty") => (true, &args[1..]),
1121                    _ => (false, args),
1122                };
1123                let cmd = match args.first() {
1124                    Some(Arg::Block(b)) => block_to_shell(b),
1125                    _ => args
1126                        .iter()
1127                        .filter_map(Arg::as_str)
1128                        .collect::<Vec<_>>()
1129                        .join(" "),
1130                };
1131                if cmd.trim().is_empty() {
1132                    return Err("spawn: missing command".into());
1133                }
1134                if stream_source_set(spec) {
1135                    return Err("spawn: a stream source is already declared".into());
1136                }
1137                spec.spawn = Some(cmd);
1138                spec.spawn_pty = pty;
1139            } else if c.name == "<" {
1140                // `< FILE`: read FILE as the stream (input source, in place of stdin).
1141                // An unquoted absolute path (`/var/log/x`) is truncated by the lexer's
1142                // `/…/` regex branch — quote it (`< "/var/log/x"`).
1143                let file = c
1144                    .args
1145                    .first()
1146                    .and_then(Arg::as_str)
1147                    .filter(|f| !f.trim().is_empty())
1148                    .ok_or("`<`: missing file path")?;
1149                if stream_source_set(spec) {
1150                    return Err("`<`: a stream source is already declared".into());
1151                }
1152                spec.source_file = Some(file.to_string());
1153            } else if c.name == "!" {
1154                // `! CMD every Ns`: re-run CMD every interval. CMD may be bare words
1155                // or a `{ … }` block; the interval follows the `every` keyword.
1156                let evy = c
1157                    .args
1158                    .iter()
1159                    .position(|a| a.as_str() == Some("every"))
1160                    .ok_or("`!` source: expected `CMD every Ns`")?;
1161                let dspec = c
1162                    .args
1163                    .get(evy + 1)
1164                    .and_then(Arg::as_str)
1165                    .ok_or("`!` source: `every` needs a duration (e.g. 1s, 500ms)")?;
1166                let dur = parse_duration(dspec).ok_or_else(|| {
1167                    format!("`!` source: `{dspec}` is not a duration (use Ns/Nms/Nm)")
1168                })?;
1169                let cmd = match c.args.first() {
1170                    Some(Arg::Block(b)) => block_to_shell(b),
1171                    _ => c.args[..evy]
1172                        .iter()
1173                        .filter_map(Arg::as_str)
1174                        .collect::<Vec<_>>()
1175                        .join(" "),
1176                };
1177                if cmd.trim().is_empty() {
1178                    return Err("`!` source: missing command".into());
1179                }
1180                if stream_source_set(spec) {
1181                    return Err("`!`: a stream source is already declared".into());
1182                }
1183                spec.poll = Some((cmd, dur));
1184            } else if c.name == "rows" || c.name == "cols" {
1185                // `rows "1 2 1"` / `cols "20 * 2*"` — proportional grid track sizes.
1186                let spec_str = c
1187                    .args
1188                    .iter()
1189                    .filter_map(Arg::as_str)
1190                    .collect::<Vec<_>>()
1191                    .join(" ");
1192                let tracks = parse_tracks(&spec_str)?;
1193                if c.name == "rows" {
1194                    spec.row_tracks = Some(tracks);
1195                } else {
1196                    spec.col_tracks = Some(tracks);
1197                }
1198            } else if c.name == "gap" {
1199                // `gap N` — blank cells between grid rows/columns.
1200                let n = c
1201                    .args
1202                    .first()
1203                    .and_then(Arg::as_str)
1204                    .and_then(|s| s.parse::<u16>().ok())
1205                    .ok_or("gap: expected a cell count (`gap 1`)")?;
1206                spec.gap = n.min(64);
1207            } else if c.name == "theme" {
1208                // `theme NAME` — one of the 31 built-in palettes; or
1209                // `theme custom c1 c2 c3 c4 c5 c6` — a 6-index custom palette.
1210                let first =
1211                    c.args.first().and_then(Arg::as_str).ok_or(
1212                        "theme: expected a name (`theme neon-noir`) or `theme custom c1..c6`",
1213                    )?;
1214                if first == "off" || first == "none" {
1215                    // Opt out to the classic cyan scheme; block the default resolver.
1216                    spec.theme = None;
1217                    spec.theme_off = true;
1218                } else if first == "custom" {
1219                    let idx: Vec<u8> = c.args[1..]
1220                        .iter()
1221                        .filter_map(Arg::as_str)
1222                        .filter_map(|s| s.parse::<u8>().ok())
1223                        .collect();
1224                    if idx.len() != 6 {
1225                        return Err(
1226                            "theme custom: expected 6 color indices 0-255 (`theme custom c1 c2 c3 c4 c5 c6`)"
1227                                .into(),
1228                        );
1229                    }
1230                    spec.theme = Some(crate::theme::custom([
1231                        idx[0], idx[1], idx[2], idx[3], idx[4], idx[5],
1232                    ]));
1233                } else {
1234                    spec.theme = Some(crate::theme::by_name(first).ok_or_else(|| {
1235                        format!(
1236                            "theme: unknown theme `{first}` (see `arb --list-themes`; or `theme custom c1..c6`)"
1237                        )
1238                    })?);
1239                }
1240            } else if c.name == "layout" {
1241                // `layout horizontal|vertical` — the no-grid auto-tile direction.
1242                match c.args.first().and_then(Arg::as_str) {
1243                    Some("horizontal") | Some("h") => spec.flow = Flow::Horizontal,
1244                    Some("vertical") | Some("v") => spec.flow = Flow::Vertical,
1245                    other => {
1246                        return Err(format!(
1247                            "layout: expected `horizontal` or `vertical`, got `{}`",
1248                            other.unwrap_or("")
1249                        )
1250                        .into())
1251                    }
1252                }
1253            } else if c.name == "grid" {
1254                let path = c
1255                    .args
1256                    .first()
1257                    .and_then(Arg::as_str)
1258                    .ok_or("grid: missing path")?;
1259                let o = parse_opts(&c.args[1..]);
1260                // Bound every grid coordinate/span: `compute_rects` sums `row+rowspan`
1261                // (unguarded usize add -> overflow panic near usize::MAX) and builds a
1262                // per-cell layout constraint vector of that size (a huge span like
1263                // `-colspan 50000000` allocates millions of constraints and pegs the
1264                // cassowary solver -> hang). No real dashboard grid exceeds this.
1265                const MAX_GRID: usize = 256;
1266                let opt = |k: &str, d: usize| {
1267                    o.get(k)
1268                        .and_then(|s: &String| s.parse::<usize>().ok())
1269                        .unwrap_or(d)
1270                        .min(MAX_GRID)
1271                };
1272                // `-span` is a colspan shorthand; `-rowspan`/`-colspan` are explicit.
1273                let colspan = opt("colspan", opt("span", 1)).max(1);
1274                let rowspan = opt("rowspan", 1).max(1);
1275                set_grid(
1276                    spec,
1277                    path,
1278                    (opt("row", 0), opt("col", 0)),
1279                    (rowspan, colspan),
1280                )?;
1281            } else if c.name.starts_with('.') {
1282                if c.args.first().and_then(Arg::as_str) == Some("<-")
1283                    && c.args.get(1).and_then(Arg::as_str) == Some("in")
1284                {
1285                    // `.path <- in` bind shorthand (empty pipeline).
1286                    let path = c.name.clone();
1287                    set_source(spec, &path, Source { pipeline: vec![] })?;
1288                } else if c.args.first().and_then(Arg::as_str) == Some("configure") {
1289                    // `.path configure -max 200`: merge new opts into the target
1290                    // widget (build-time; later keys win). Runtime reconfigure via a
1291                    // bind/expect mutating live opts is a separate, larger feature.
1292                    let opts = parse_opts(&c.args[1..]);
1293                    configure_widget(spec, &c.name, opts)?;
1294                }
1295            }
1296            // Unknown verbs are ignored.
1297            Ok(())
1298        })();
1299        res.map_err(|e| e.or_span(c.pos, c.name.chars().count()))?;
1300    }
1301    Ok(())
1302}
1303
1304/// Resolve a module name to its source: a local `NAME.arb`, then
1305/// `~/.arb/lib/NAME.arb`, then a bundled stdlib preset.
1306fn resolve_module(name: &str) -> Result<String, String> {
1307    // A path-like or already-suffixed name (`import "./lib.arb"`, `import
1308    // "/abs/lib.arb"`) is read verbatim — don't double up the extension.
1309    if name.ends_with(".arb") || name.contains('/') {
1310        if let Ok(s) = std::fs::read_to_string(name) {
1311            return Ok(s);
1312        }
1313    }
1314    let local = format!("{name}.arb");
1315    if let Ok(s) = std::fs::read_to_string(&local) {
1316        return Ok(s);
1317    }
1318    if let Some(dir) = lib_dir() {
1319        if let Ok(s) = std::fs::read_to_string(dir.join(format!("{name}.arb"))) {
1320            return Ok(s);
1321        }
1322    }
1323    // Installed registry packages (`~/.arb/pkg`) — the SPEC §17 `pkg` tier.
1324    if let Some(dir) = crate::pkg::pkg_dir() {
1325        if let Some(s) = crate::pkg::read_pkg_module(&dir, name) {
1326            return Ok(s);
1327        }
1328    }
1329    bundled_module(name)
1330        .map(str::to_string)
1331        .ok_or_else(|| format!("import: module `{name}` not found"))
1332}
1333
1334/// Names of the bundled stdlib presets.
1335pub const STDLIB_NAMES: &[&str] = &[
1336    "nums",
1337    "logs",
1338    "http",
1339    "json",
1340    "table",
1341    "top",
1342    "docker",
1343    "k8s",
1344    "nginx",
1345    "git",
1346    "systemd",
1347    "redis",
1348    "postgres",
1349    "mysql",
1350    "mongodb",
1351    "kafka",
1352    "prometheus",
1353    "elasticsearch",
1354    "rabbitmq",
1355    "apache",
1356    "haproxy",
1357    "journalctl",
1358    "dmesg",
1359    "ps",
1360    "htop",
1361    "iostat",
1362    "vmstat",
1363    "ss",
1364    "dig",
1365    "curl",
1366    "gh",
1367    "terraform",
1368    "aws",
1369    "gcloud",
1370    "azure",
1371    "ansible",
1372    "consul",
1373    "vault",
1374    "etcd",
1375    "nomad",
1376    "envoy",
1377    "memcached",
1378    "varnish",
1379    "pgbouncer",
1380    "celery",
1381    "sidekiq",
1382    "gunicorn",
1383    "supervisor",
1384    "fail2ban",
1385    "iptables",
1386    "conntrack",
1387    "sar",
1388    "nats",
1389    "tomcat",
1390    "puma",
1391    "lighttpd",
1392    "helm",
1393    "podman",
1394    "containerd",
1395    "crictl",
1396    "istioctl",
1397    "linkerd",
1398    "cilium",
1399    "argocd",
1400    "fluxcd",
1401    "velero",
1402    "kustomize",
1403    "skopeo",
1404    "buildah",
1405    "stern",
1406    "kubectx",
1407    "jenkins",
1408    "gitlabrunner",
1409    "circleci",
1410    "drone",
1411    "buildkite",
1412    "concourse",
1413    "woodpecker",
1414    "spinnaker",
1415    "tekton",
1416    "teamcity",
1417    "packer",
1418    "vagrant",
1419    "pulumi",
1420    "chef",
1421    "puppet",
1422    "salt",
1423    "cloudformation",
1424    "cdk",
1425    "doctl",
1426    "hcloud",
1427    "fly",
1428    "heroku",
1429    "linode",
1430    "vultr",
1431    "scaleway",
1432    "cassandra",
1433    "scylla",
1434    "cockroachdb",
1435    "clickhouse",
1436    "influxdb",
1437    "neo4j",
1438    "couchdb",
1439    "dynamodb",
1440    "mariadb",
1441    "duckdb",
1442    "sqlite",
1443    "mssql",
1444    "timescaledb",
1445    "arangodb",
1446    "tidb",
1447    "victoriametrics",
1448    "questdb",
1449    "riak",
1450    "dgraph",
1451    "opensearch",
1452    "grafana",
1453    "loki",
1454    "tempo",
1455    "jaeger",
1456    "zipkin",
1457    "datadog",
1458    "newrelic",
1459    "sentry",
1460    "statsd",
1461    "telegraf",
1462    "collectd",
1463    "netdata",
1464    "zabbix",
1465    "nagios",
1466    "icinga",
1467    "pulsar",
1468    "activemq",
1469    "nsq",
1470    "beanstalkd",
1471    "caddy",
1472    "traefik",
1473    "uwsgi",
1474    "phpfpm",
1475    "tcpdump",
1476    "tshark",
1477    "nmap",
1478    "netstat",
1479    "iftop",
1480    "nethogs",
1481    "vnstat",
1482    "mtr",
1483    "zfs",
1484    "btrfs",
1485    "smartctl",
1486    "nvme",
1487    "rclone",
1488];
1489
1490fn bundled_module(name: &str) -> Option<&'static str> {
1491    Some(match name {
1492        "nums" => include_str!("../stdlib/nums.arb"),
1493        "logs" => include_str!("../stdlib/logs.arb"),
1494        "http" => include_str!("../stdlib/http.arb"),
1495        "json" => include_str!("../stdlib/json.arb"),
1496        "table" => include_str!("../stdlib/table.arb"),
1497        "top" => include_str!("../stdlib/top.arb"),
1498        "docker" => include_str!("../stdlib/docker.arb"),
1499        "k8s" => include_str!("../stdlib/k8s.arb"),
1500        "nginx" => include_str!("../stdlib/nginx.arb"),
1501        "git" => include_str!("../stdlib/git.arb"),
1502        "systemd" => include_str!("../stdlib/systemd.arb"),
1503        "redis" => include_str!("../stdlib/redis.arb"),
1504        "postgres" => include_str!("../stdlib/postgres.arb"),
1505        "mysql" => include_str!("../stdlib/mysql.arb"),
1506        "mongodb" => include_str!("../stdlib/mongodb.arb"),
1507        "kafka" => include_str!("../stdlib/kafka.arb"),
1508        "prometheus" => include_str!("../stdlib/prometheus.arb"),
1509        "elasticsearch" => include_str!("../stdlib/elasticsearch.arb"),
1510        "rabbitmq" => include_str!("../stdlib/rabbitmq.arb"),
1511        "apache" => include_str!("../stdlib/apache.arb"),
1512        "haproxy" => include_str!("../stdlib/haproxy.arb"),
1513        "journalctl" => include_str!("../stdlib/journalctl.arb"),
1514        "dmesg" => include_str!("../stdlib/dmesg.arb"),
1515        "ps" => include_str!("../stdlib/ps.arb"),
1516        "htop" => include_str!("../stdlib/htop.arb"),
1517        "iostat" => include_str!("../stdlib/iostat.arb"),
1518        "vmstat" => include_str!("../stdlib/vmstat.arb"),
1519        "ss" => include_str!("../stdlib/ss.arb"),
1520        "dig" => include_str!("../stdlib/dig.arb"),
1521        "curl" => include_str!("../stdlib/curl.arb"),
1522        "gh" => include_str!("../stdlib/gh.arb"),
1523        "terraform" => include_str!("../stdlib/terraform.arb"),
1524        "aws" => include_str!("../stdlib/aws.arb"),
1525        "gcloud" => include_str!("../stdlib/gcloud.arb"),
1526        "azure" => include_str!("../stdlib/azure.arb"),
1527        "ansible" => include_str!("../stdlib/ansible.arb"),
1528        "consul" => include_str!("../stdlib/consul.arb"),
1529        "vault" => include_str!("../stdlib/vault.arb"),
1530        "etcd" => include_str!("../stdlib/etcd.arb"),
1531        "nomad" => include_str!("../stdlib/nomad.arb"),
1532        "envoy" => include_str!("../stdlib/envoy.arb"),
1533        "memcached" => include_str!("../stdlib/memcached.arb"),
1534        "varnish" => include_str!("../stdlib/varnish.arb"),
1535        "pgbouncer" => include_str!("../stdlib/pgbouncer.arb"),
1536        "celery" => include_str!("../stdlib/celery.arb"),
1537        "sidekiq" => include_str!("../stdlib/sidekiq.arb"),
1538        "gunicorn" => include_str!("../stdlib/gunicorn.arb"),
1539        "supervisor" => include_str!("../stdlib/supervisor.arb"),
1540        "fail2ban" => include_str!("../stdlib/fail2ban.arb"),
1541        "iptables" => include_str!("../stdlib/iptables.arb"),
1542        "conntrack" => include_str!("../stdlib/conntrack.arb"),
1543        "sar" => include_str!("../stdlib/sar.arb"),
1544        "nats" => include_str!("../stdlib/nats.arb"),
1545        "tomcat" => include_str!("../stdlib/tomcat.arb"),
1546        "puma" => include_str!("../stdlib/puma.arb"),
1547        "lighttpd" => include_str!("../stdlib/lighttpd.arb"),
1548        "helm" => include_str!("../stdlib/helm.arb"),
1549        "podman" => include_str!("../stdlib/podman.arb"),
1550        "containerd" => include_str!("../stdlib/containerd.arb"),
1551        "crictl" => include_str!("../stdlib/crictl.arb"),
1552        "istioctl" => include_str!("../stdlib/istioctl.arb"),
1553        "linkerd" => include_str!("../stdlib/linkerd.arb"),
1554        "cilium" => include_str!("../stdlib/cilium.arb"),
1555        "argocd" => include_str!("../stdlib/argocd.arb"),
1556        "fluxcd" => include_str!("../stdlib/fluxcd.arb"),
1557        "velero" => include_str!("../stdlib/velero.arb"),
1558        "kustomize" => include_str!("../stdlib/kustomize.arb"),
1559        "skopeo" => include_str!("../stdlib/skopeo.arb"),
1560        "buildah" => include_str!("../stdlib/buildah.arb"),
1561        "stern" => include_str!("../stdlib/stern.arb"),
1562        "kubectx" => include_str!("../stdlib/kubectx.arb"),
1563        "jenkins" => include_str!("../stdlib/jenkins.arb"),
1564        "gitlabrunner" => include_str!("../stdlib/gitlabrunner.arb"),
1565        "circleci" => include_str!("../stdlib/circleci.arb"),
1566        "drone" => include_str!("../stdlib/drone.arb"),
1567        "buildkite" => include_str!("../stdlib/buildkite.arb"),
1568        "concourse" => include_str!("../stdlib/concourse.arb"),
1569        "woodpecker" => include_str!("../stdlib/woodpecker.arb"),
1570        "spinnaker" => include_str!("../stdlib/spinnaker.arb"),
1571        "tekton" => include_str!("../stdlib/tekton.arb"),
1572        "teamcity" => include_str!("../stdlib/teamcity.arb"),
1573        "packer" => include_str!("../stdlib/packer.arb"),
1574        "vagrant" => include_str!("../stdlib/vagrant.arb"),
1575        "pulumi" => include_str!("../stdlib/pulumi.arb"),
1576        "chef" => include_str!("../stdlib/chef.arb"),
1577        "puppet" => include_str!("../stdlib/puppet.arb"),
1578        "salt" => include_str!("../stdlib/salt.arb"),
1579        "cloudformation" => include_str!("../stdlib/cloudformation.arb"),
1580        "cdk" => include_str!("../stdlib/cdk.arb"),
1581        "doctl" => include_str!("../stdlib/doctl.arb"),
1582        "hcloud" => include_str!("../stdlib/hcloud.arb"),
1583        "fly" => include_str!("../stdlib/fly.arb"),
1584        "heroku" => include_str!("../stdlib/heroku.arb"),
1585        "linode" => include_str!("../stdlib/linode.arb"),
1586        "vultr" => include_str!("../stdlib/vultr.arb"),
1587        "scaleway" => include_str!("../stdlib/scaleway.arb"),
1588        "cassandra" => include_str!("../stdlib/cassandra.arb"),
1589        "scylla" => include_str!("../stdlib/scylla.arb"),
1590        "cockroachdb" => include_str!("../stdlib/cockroachdb.arb"),
1591        "clickhouse" => include_str!("../stdlib/clickhouse.arb"),
1592        "influxdb" => include_str!("../stdlib/influxdb.arb"),
1593        "neo4j" => include_str!("../stdlib/neo4j.arb"),
1594        "couchdb" => include_str!("../stdlib/couchdb.arb"),
1595        "dynamodb" => include_str!("../stdlib/dynamodb.arb"),
1596        "mariadb" => include_str!("../stdlib/mariadb.arb"),
1597        "duckdb" => include_str!("../stdlib/duckdb.arb"),
1598        "sqlite" => include_str!("../stdlib/sqlite.arb"),
1599        "mssql" => include_str!("../stdlib/mssql.arb"),
1600        "timescaledb" => include_str!("../stdlib/timescaledb.arb"),
1601        "arangodb" => include_str!("../stdlib/arangodb.arb"),
1602        "tidb" => include_str!("../stdlib/tidb.arb"),
1603        "victoriametrics" => include_str!("../stdlib/victoriametrics.arb"),
1604        "questdb" => include_str!("../stdlib/questdb.arb"),
1605        "riak" => include_str!("../stdlib/riak.arb"),
1606        "dgraph" => include_str!("../stdlib/dgraph.arb"),
1607        "opensearch" => include_str!("../stdlib/opensearch.arb"),
1608        "grafana" => include_str!("../stdlib/grafana.arb"),
1609        "loki" => include_str!("../stdlib/loki.arb"),
1610        "tempo" => include_str!("../stdlib/tempo.arb"),
1611        "jaeger" => include_str!("../stdlib/jaeger.arb"),
1612        "zipkin" => include_str!("../stdlib/zipkin.arb"),
1613        "datadog" => include_str!("../stdlib/datadog.arb"),
1614        "newrelic" => include_str!("../stdlib/newrelic.arb"),
1615        "sentry" => include_str!("../stdlib/sentry.arb"),
1616        "statsd" => include_str!("../stdlib/statsd.arb"),
1617        "telegraf" => include_str!("../stdlib/telegraf.arb"),
1618        "collectd" => include_str!("../stdlib/collectd.arb"),
1619        "netdata" => include_str!("../stdlib/netdata.arb"),
1620        "zabbix" => include_str!("../stdlib/zabbix.arb"),
1621        "nagios" => include_str!("../stdlib/nagios.arb"),
1622        "icinga" => include_str!("../stdlib/icinga.arb"),
1623        "pulsar" => include_str!("../stdlib/pulsar.arb"),
1624        "activemq" => include_str!("../stdlib/activemq.arb"),
1625        "nsq" => include_str!("../stdlib/nsq.arb"),
1626        "beanstalkd" => include_str!("../stdlib/beanstalkd.arb"),
1627        "caddy" => include_str!("../stdlib/caddy.arb"),
1628        "traefik" => include_str!("../stdlib/traefik.arb"),
1629        "uwsgi" => include_str!("../stdlib/uwsgi.arb"),
1630        "phpfpm" => include_str!("../stdlib/phpfpm.arb"),
1631        "tcpdump" => include_str!("../stdlib/tcpdump.arb"),
1632        "tshark" => include_str!("../stdlib/tshark.arb"),
1633        "nmap" => include_str!("../stdlib/nmap.arb"),
1634        "netstat" => include_str!("../stdlib/netstat.arb"),
1635        "iftop" => include_str!("../stdlib/iftop.arb"),
1636        "nethogs" => include_str!("../stdlib/nethogs.arb"),
1637        "vnstat" => include_str!("../stdlib/vnstat.arb"),
1638        "mtr" => include_str!("../stdlib/mtr.arb"),
1639        "zfs" => include_str!("../stdlib/zfs.arb"),
1640        "btrfs" => include_str!("../stdlib/btrfs.arb"),
1641        "smartctl" => include_str!("../stdlib/smartctl.arb"),
1642        "nvme" => include_str!("../stdlib/nvme.arb"),
1643        "rclone" => include_str!("../stdlib/rclone.arb"),
1644        _ => return None,
1645    })
1646}
1647
1648/// List available presets as `(name, description, example)` — bundled stdlib
1649/// plus any user modules in `~/.arb/lib`. The description is the preset's first
1650/// `#` line, the example its second (empty when the header has none).
1651pub fn list_presets() -> Vec<(String, String, String)> {
1652    let mut out: Vec<(String, String, String)> = STDLIB_NAMES
1653        .iter()
1654        .map(|n| {
1655            let src = bundled_module(n).unwrap_or("");
1656            (n.to_string(), first_comment(src), example_comment(src))
1657        })
1658        .collect();
1659    if let Some(dir) = lib_dir() {
1660        out.extend(list_user_presets(&dir));
1661    }
1662    out
1663}
1664
1665fn first_comment(src: &str) -> String {
1666    src.lines()
1667        .find_map(|l| l.trim().strip_prefix('#'))
1668        .map(|s| s.trim().to_string())
1669        .unwrap_or_default()
1670}
1671
1672/// The invocation a spec documents in its own header — the second `#` line of
1673/// every stdlib preset, e.g. `#   git log --oneline | arb -p git`. Every preset
1674/// carries one, but until it is printed the user has to open the file to find
1675/// out what feeds it, which is the whole failure mode of "spec reads stdin but
1676/// nothing is piped".
1677///
1678/// Taken from the leading comment block only, and only from a line that names
1679/// `arb` — a spec whose header is prose, not a command line, has no example
1680/// rather than a wrong one.
1681pub fn example_comment(src: &str) -> String {
1682    src.lines()
1683        .map_while(|l| l.trim().strip_prefix('#'))
1684        .skip(1)
1685        .map(str::trim)
1686        .find(|l| l.contains("arb"))
1687        .unwrap_or_default()
1688        .to_string()
1689}
1690
1691/// The documented invocation for a preset NAME, resolved the way `import` would
1692/// resolve it — so a user's `~/.arb/lib/NAME.arb` shadows the bundled preset's
1693/// example just as it shadows its body.
1694pub fn preset_example(name: &str) -> String {
1695    resolve_module(name)
1696        .map(|src| example_comment(&src))
1697        .unwrap_or_default()
1698}
1699
1700/// Canonical accent color for a widget's `-color NAME` opt, as a `#rrggbb` hex —
1701/// the single source of truth shared by the TUI (parsed to an RGB color) and the
1702/// web dashboard (used directly in CSS/SVG). Unknown/absent names default to cyan.
1703/// Parse a scalar control bound (`-min`/`-max`/`-step`): a plain number, a
1704/// duration (`5s`/`500ms`/`2m`/`1h`) as seconds, or a size (`1kb`/`4mb`/`2gb`)
1705/// as bytes. Unparseable -> 0.
1706pub fn parse_scalar(s: &str) -> f64 {
1707    let s = s.trim();
1708    if let Some(d) = parse_duration(s) {
1709        return d.as_secs_f64();
1710    }
1711    let lower = s.to_ascii_lowercase();
1712    for (suf, mult) in [("kb", 1024.0), ("mb", 1048576.0), ("gb", 1073741824.0)] {
1713        if let Some(n) = lower.strip_suffix(suf) {
1714            if let Ok(v) = n.trim().parse::<f64>() {
1715                return v * mult;
1716            }
1717        }
1718    }
1719    s.parse::<f64>().unwrap_or(0.0)
1720}
1721
1722/// Whether `name` is one of the fixed semantic color names (green/red/…) — an
1723/// explicit, theme-independent override, distinct from a theme palette slot.
1724pub fn is_named_color(name: &str) -> bool {
1725    matches!(
1726        name.trim().to_ascii_lowercase().as_str(),
1727        "green"
1728            | "red"
1729            | "yellow"
1730            | "orange"
1731            | "magenta"
1732            | "pink"
1733            | "blue"
1734            | "white"
1735            | "gray"
1736            | "grey"
1737            | "cyan"
1738    )
1739}
1740
1741pub fn color_hex(name: Option<&str>) -> &'static str {
1742    match name.map(|s| s.trim().to_ascii_lowercase()).as_deref() {
1743        Some("green") => "#00e676",
1744        Some("red") => "#ff5252",
1745        Some("yellow") => "#ffd740",
1746        Some("orange") => "#ffab40",
1747        Some("magenta") | Some("pink") => "#e040fb",
1748        Some("blue") => "#40c4ff",
1749        Some("white") => "#e0e0e0",
1750        Some("gray") | Some("grey") => "#9e9e9e",
1751        _ => "#00e5ff", // cyan (default)
1752    }
1753}
1754
1755/// The user preset library directory: `$ARB_LIB` when set (used by tests and for
1756/// relocating the library), else `$HOME/.arb/lib`. `None` if neither is set.
1757pub fn lib_dir() -> Option<std::path::PathBuf> {
1758    if let Some(d) = std::env::var_os("ARB_LIB") {
1759        return Some(std::path::PathBuf::from(d));
1760    }
1761    std::env::var_os("HOME").map(|h| std::path::Path::new(&h).join(".arb/lib"))
1762}
1763
1764/// Install a spec `src` into `dir` as `NAME.arb` — the shareable-package unit.
1765/// The spec is validated (parse + build) first; an invalid package is rejected
1766/// so the library only ever holds runnable dashboards. Returns the written path.
1767pub fn install_preset(
1768    dir: &std::path::Path,
1769    name: &str,
1770    src: &str,
1771) -> Result<std::path::PathBuf, String> {
1772    if name.is_empty() || name.contains(['/', '\\', '.']) {
1773        return Err(format!("install: invalid preset name `{name}`"));
1774    }
1775    let cmds = crate::parser::parse(src).map_err(|e| format!("install: invalid spec: {e}"))?;
1776    build(&cmds).map_err(|e| format!("install: invalid spec: {e}"))?;
1777    std::fs::create_dir_all(dir).map_err(|e| format!("install: {e}"))?;
1778    let path = dir.join(format!("{name}.arb"));
1779    std::fs::write(&path, src).map_err(|e| format!("install: {e}"))?;
1780    Ok(path)
1781}
1782
1783/// Remove `NAME.arb` from `dir`. Returns whether a preset was actually removed.
1784pub fn uninstall_preset(dir: &std::path::Path, name: &str) -> std::io::Result<bool> {
1785    let path = dir.join(format!("{name}.arb"));
1786    if path.exists() {
1787        std::fs::remove_file(&path)?;
1788        Ok(true)
1789    } else {
1790        Ok(false)
1791    }
1792}
1793
1794/// List installed user presets in `dir` as `(name, description, example)`,
1795/// sorted by name. The description is the preset's first `#` comment line, the
1796/// example its second.
1797pub fn list_user_presets(dir: &std::path::Path) -> Vec<(String, String, String)> {
1798    let mut out = Vec::new();
1799    if let Ok(entries) = std::fs::read_dir(dir) {
1800        for e in entries.flatten() {
1801            let path = e.path();
1802            if path.extension().and_then(|s| s.to_str()) == Some("arb") {
1803                if let Some(stem) = path.file_stem().and_then(|s| s.to_str()) {
1804                    let src = std::fs::read_to_string(&path).unwrap_or_default();
1805                    out.push((stem.to_string(), first_comment(&src), example_comment(&src)));
1806                }
1807            }
1808        }
1809    }
1810    out.sort_by(|a, b| a.0.cmp(&b.0));
1811    out
1812}
1813
1814/// Collect `-flag value` pairs into an options map.
1815fn parse_opts(args: &[Arg]) -> BTreeMap<String, String> {
1816    let mut m = BTreeMap::new();
1817    let mut i = 0;
1818    while i < args.len() {
1819        if let Some(flag) = args[i].as_str().and_then(|w| w.strip_prefix('-')) {
1820            // A block value (`-tabs {a b}`) becomes a comma-joined word list:
1821            // each top-level command contributes its name plus its word args
1822            // (Tcl-flavored `{a b}` is one command `a b`), so `{a b}` -> "a,b".
1823            let val = match args.get(i + 1) {
1824                Some(Arg::Block(cmds)) => {
1825                    let mut words = Vec::new();
1826                    for c in cmds {
1827                        words.push(c.name.clone());
1828                        words.extend(c.args.iter().filter_map(|a| a.as_str().map(str::to_string)));
1829                    }
1830                    words.join(",")
1831                }
1832                Some(a) => a.as_str().unwrap_or("").to_string(),
1833                None => String::new(),
1834            };
1835            m.insert(flag.to_string(), val);
1836            i += 2;
1837        } else {
1838            i += 1;
1839        }
1840    }
1841    m
1842}
1843
1844/// Parse a `test "NAME" { … }` body into a [`TestCase`]. Clauses: `given LINES…`
1845/// (input, one line per arg), `run { in; … }` (the pipeline, required), and
1846/// `want LINES…` (expected output). Unknown clauses / a missing `run` error.
1847fn parse_test_case(
1848    name: String,
1849    body: &[Command],
1850    actors: &BTreeMap<String, Arc<ActorDef>>,
1851) -> Result<TestCase, String> {
1852    let str_args = |c: &Command| -> Vec<String> {
1853        c.args
1854            .iter()
1855            .filter_map(Arg::as_str)
1856            .map(String::from)
1857            .collect()
1858    };
1859    let mut given = Vec::new();
1860    let mut want = Vec::new();
1861    let mut ops = None;
1862    for c in body {
1863        match c.name.as_str() {
1864            "given" => given = str_args(c),
1865            "want" => want = str_args(c),
1866            "run" => {
1867                let b = match c.args.first() {
1868                    Some(Arg::Block(b)) => b,
1869                    _ => return Err(format!("test `{name}`: `run` expects `{{ in; … }}`")),
1870                };
1871                // Reuse the real body compiler, so a test can exercise native
1872                // verbs and the jq/xpath front-ends alike.
1873                ops = Some(pipeline_from_body(b, actors).map_err(|e| e.msg)?);
1874            }
1875            other => {
1876                return Err(format!(
1877                    "test `{name}`: unknown clause `{other}` (use given / run / want)"
1878                ))
1879            }
1880        }
1881    }
1882    let ops = ops.ok_or_else(|| format!("test `{name}`: missing `run {{ … }}`"))?;
1883    Ok(TestCase {
1884        name,
1885        given,
1886        ops,
1887        want,
1888    })
1889}
1890
1891/// Reconstruct the source text of a braced argument. The lexer reads `{ div.card
1892/// h2 }` as a BLOCK of commands, because braces are how arb spells every other
1893/// nested body — but `sel`'s brace holds a CSS selector, not commands, so the
1894/// words have to be put back together. Command separators (`;`/newline) inside
1895/// the brace become spaces, which is what a multi-line selector list means.
1896fn block_text(cmds: &[Command]) -> String {
1897    cmds.iter()
1898        .map(|c| {
1899            std::iter::once(c.name.clone())
1900                .chain(c.args.iter().map(|a| match a {
1901                    Arg::Block(inner) => format!("{{{}}}", block_text(inner)),
1902                    // A QUOTED arg keeps its quotes. Dropping them turned
1903                    // `sel { a[href="/x"] }` into `a[href=/x]`, which is not a
1904                    // legal CSS selector — and the parse failure then read as
1905                    // "no matches", so a selector the docs advertise silently
1906                    // selected nothing.
1907                    Arg::Str(v) => quote_arg(v),
1908                    other => other.as_str().unwrap_or_default().to_string(),
1909                }))
1910                .collect::<Vec<_>>()
1911                .join(" ")
1912        })
1913        .collect::<Vec<_>>()
1914        .join(" ")
1915}
1916
1917/// Compile a `source { … }` body into a query pipeline. Must start with `in`.
1918fn pipeline_from_body(
1919    cmds: &[Command],
1920    actors: &BTreeMap<String, Arc<ActorDef>>,
1921) -> Result<Vec<QueryOp>, crate::err::SpecError> {
1922    let mut ops = Vec::new();
1923    let mut saw_in = false;
1924    // The stream holds JSON VALUES rather than markup: a JSON-family reader
1925    // opened it and no HTML/XML step (`sel`, `find`, an xpath step) has run
1926    // since. Over such a stream a leading `@` cannot be an attribute step.
1927    let mut json_values = false;
1928    for c in cmds {
1929        // Process one op; on error, anchor the diagnostic to THIS (nested) verb's
1930        // source position, not the outer `source`/`out` command (the IIFE lets the
1931        // arms' `return Err` unwind to the per-command span attach below).
1932        let step = (|| -> Result<(), crate::err::SpecError> {
1933            // jq front-end: a body command whose first token is a jq literal (starts
1934            // with `.`, or a `select(…)`/`map(…)` stage) is translated to arb ops.
1935            // Inside a `source` body a leading `.` is unambiguous — widget-path decls
1936            // never appear here. The whole command text (verb + args) is reconstructed
1937            // so the jq `|` pipe, which is not an arb separator, can be split by `jq`.
1938            // `has(…)` is the jq CALL form and routes here; arb's native
1939            // space-separated `has KEY` filter is a different verb and still
1940            // matches below. `to_entries`/`values` are jq builtin names the spec
1941            // lists as supported but that have no native spelling, so without
1942            // this arm they died as `unknown verb`.
1943            if c.name.starts_with('.')
1944                || c.name.starts_with("select(")
1945                || c.name.starts_with("map(")
1946                || c.name.starts_with("has(")
1947                || matches!(c.name.as_str(), "to_entries" | "values")
1948                // A jq `@format` string. A leading `@` otherwise means an XPATH
1949                // attribute step, so only the nine format NAMES are claimed —
1950                // `@href` still selects an attribute.
1951                || opens_jq_format(&c.name)
1952                // Over JSON values a leading `@` is jq's whatever the name: an
1953                // xpath `@attr` step there would parse each JSON line as HTML and
1954                // select nothing, so `@base32` (not a format in jq 1.8) or
1955                // `@foo` printed nothing and exited 0 where jq raises
1956                // `foo is not a valid format`.
1957                || (json_values && c.name.starts_with('@'))
1958            {
1959                let mut parts = vec![c.name.clone()];
1960                parts.extend(c.args.iter().filter_map(Arg::as_str).map(str::to_string));
1961                let src = parts.join(" ");
1962                match crate::jq::translate(&src) {
1963                    Ok(jq_ops) => ops.extend(jq_ops),
1964                    // Outside the translatable subset. That used to be the end of
1965                    // it — SPEC §8 listed ~120 constructs as hard errors purely
1966                    // because a `Vec<QueryOp>` cannot express them. It compiles as
1967                    // a real jq program instead, and only a program that is not
1968                    // valid jq EITHER keeps the original refusal.
1969                    Err(sub_err) => match crate::query::jq_program(&src) {
1970                        Ok(_) => ops.push(QueryOp::JqProgram(src)),
1971                        Err(_) => return Err(sub_err.into()),
1972                    },
1973                }
1974                return Ok(());
1975            }
1976            // xpath front-end: a body command whose first token is an xpath literal
1977            // (`/…`, `//…`, or `@…`) translates to arb's Find/Attr/Text ops. Disjoint
1978            // from the jq test above (`.`/`select(`/`map(`) and from native verbs
1979            // (alnum), so the three coexist in one body unambiguously.
1980            if c.name.starts_with('/') || c.name.starts_with('@') {
1981                json_values = false;
1982                let mut parts = vec![c.name.clone()];
1983                parts.extend(c.args.iter().filter_map(Arg::as_str).map(str::to_string));
1984                let xp_ops = crate::xpath::translate(&parts.join(" "))?;
1985                ops.extend(xp_ops);
1986                return Ok(());
1987            }
1988            match c.name.as_str() {
1989                "in" | "in.html" | "in.xml" | "in.logfmt" => {
1990                    saw_in = true;
1991                    json_values = false;
1992                }
1993                "in.json" => {
1994                    saw_in = true;
1995                    json_values = true;
1996                    ops.push(QueryOp::JsonDocs);
1997                }
1998                "in.csv" => {
1999                    saw_in = true;
2000                    json_values = true;
2001                    ops.push(QueryOp::Csv);
2002                }
2003                "in.tsv" => {
2004                    saw_in = true;
2005                    json_values = true;
2006                    ops.push(QueryOp::Tsv);
2007                }
2008                "in.yaml" | "in.yml" => {
2009                    saw_in = true;
2010                    json_values = true;
2011                    ops.push(QueryOp::Yaml);
2012                }
2013                // `out.FORMAT [INDENT]` — yq's `-o=` / `-I` in arb's spelling.
2014                //
2015                // The default rendering stays one compact JSON line per
2016                // document, which is what every existing pipeline and the whole
2017                // `yq_probe` corpus expects. `out.yaml` is what turns the node
2018                // metadata the YAML reader kept back into YAML, so
2019                // `in.yaml; out.yaml` gives the file back — comments, anchors,
2020                // tags, quoting and all.
2021                "out.yaml" | "out.yml" | "out.json" | "out.props" | "out.xml" | "out.csv"
2022                | "out.tsv" => {
2023                    let fmt = match c.name.as_str() {
2024                        "out.yaml" | "out.yml" => crate::query::OutFmt::Yaml,
2025                        "out.json" => crate::query::OutFmt::Json,
2026                        "out.props" => crate::query::OutFmt::Props,
2027                        "out.xml" => crate::query::OutFmt::Xml,
2028                        "out.csv" => crate::query::OutFmt::Csv,
2029                        _ => crate::query::OutFmt::Tsv,
2030                    };
2031                    let indent = match c.args.first().and_then(Arg::as_str) {
2032                        Some(n) => n
2033                            .parse::<usize>()
2034                            .map_err(|_| format!("{}: expected an indent width", c.name))?,
2035                        None => 2,
2036                    };
2037                    ops.push(QueryOp::Emit(fmt, indent));
2038                }
2039                "in.toml" => {
2040                    saw_in = true;
2041                    json_values = true;
2042                    ops.push(QueryOp::Toml);
2043                }
2044                "sel" => {
2045                    // `sel { div.card h2 }` is the spelling SPEC §8 and the README
2046                    // both show, and it is the one that did NOT work: a braced
2047                    // argument lexes to `Arg::Block`, `as_str` drops it, and the
2048                    // verb then reported "expected a CSS selector" for the exact
2049                    // form the docs advertise. The block's source text is
2050                    // reconstructed here so both spellings compile to the same op.
2051                    let flat: Vec<String> = c
2052                        .args
2053                        .iter()
2054                        .map(|a| match a {
2055                            Arg::Block(cmds) => block_text(cmds),
2056                            other => other.as_str().unwrap_or_default().to_string(),
2057                        })
2058                        .collect();
2059                    let words: Vec<&str> = flat.iter().map(String::as_str).collect();
2060                    let mut css_parts = Vec::new();
2061                    let mut attr = None;
2062                    let mut i = 0;
2063                    while i < words.len() {
2064                        if words[i] == "-attr" {
2065                            attr = words.get(i + 1).map(|s| s.to_string());
2066                            i += 2;
2067                        } else {
2068                            css_parts.push(words[i]);
2069                            i += 1;
2070                        }
2071                    }
2072                    let css = css_parts.join(" ");
2073                    if css.trim().is_empty() {
2074                        return Err("sel: expected a CSS selector".into());
2075                    }
2076                    // A MALFORMED selector is a hard error here, before any input
2077                    // is read. The evaluator used to map a parse failure to an
2078                    // EMPTY result, which made `sel { a[href=/x] }` — a selector
2079                    // no CSS engine accepts — indistinguishable from one that
2080                    // legitimately matches nothing. That is the silent
2081                    // reinterpretation SPEC §8 rules out, and it is the same
2082                    // failure the xpath leg had.
2083                    check_css(&css, "sel")?;
2084                    json_values = false;
2085                    ops.push(QueryOp::Sel { css, attr });
2086                }
2087                "find" => {
2088                    let css = c
2089                        .args
2090                        .iter()
2091                        .filter_map(Arg::as_str)
2092                        .collect::<Vec<_>>()
2093                        .join(" ");
2094                    if css.trim().is_empty() {
2095                        return Err("find: expected a tag/selector".into());
2096                    }
2097                    check_css(&css, "find")?;
2098                    json_values = false;
2099                    ops.push(QueryOp::Find(css));
2100                }
2101                "attr" => {
2102                    let name = str_arg(c);
2103                    if name.is_empty() {
2104                        return Err("attr: expected an attribute name".into());
2105                    }
2106                    ops.push(QueryOp::Attr(name));
2107                }
2108                "text" => ops.push(QueryOp::Text),
2109                "match" | "grep" => ops.push(QueryOp::Match(regex_arg(c)?)),
2110                "reject" | "grepv" => ops.push(QueryOp::Reject(regex_arg(c)?)),
2111                "field" => ops.push(QueryOp::Field(field_sel(&c.args)?)),
2112                "fields" => {
2113                    let cols: Vec<usize> = c
2114                        .args
2115                        .iter()
2116                        .filter_map(Arg::as_str)
2117                        .filter_map(|s| s.parse::<usize>().ok())
2118                        .collect();
2119                    if cols.is_empty() {
2120                        return Err("fields: expected column numbers (e.g. fields 1 3)".into());
2121                    }
2122                    ops.push(QueryOp::Fields(cols));
2123                }
2124                "each" => ops.push(QueryOp::Each),
2125                "count" => ops.push(QueryOp::Count),
2126                "rate" => ops.push(QueryOp::Rate),
2127                "tally" => ops.push(QueryOp::Tally),
2128                "sum" => ops.push(QueryOp::Sum),
2129                "min" => ops.push(QueryOp::Min),
2130                "max" => ops.push(QueryOp::Max),
2131                "avg" => ops.push(QueryOp::Avg),
2132                // `names` is the NATIVE line-per-key verb. It is deliberately not
2133                // spelled `keys`: `keys` is jq's canonical name for the sorted
2134                // array, and the native table is matched before the jq
2135                // fall-through, so claiming that spelling would shadow jq's
2136                // builtin and break the superset contract (SPEC §8).
2137                "names" => ops.push(QueryOp::Keys),
2138                "vals" => ops.push(QueryOp::Vals),
2139                "pick" => {
2140                    let keys: Vec<String> = c
2141                        .args
2142                        .iter()
2143                        .filter_map(Arg::as_str)
2144                        .map(str::to_string)
2145                        .collect();
2146                    if keys.is_empty() {
2147                        return Err("pick: expected one or more key names".into());
2148                    }
2149                    ops.push(QueryOp::Pick(keys));
2150                }
2151                "sort" => {
2152                    let flags: Vec<&str> = c.args.iter().filter_map(Arg::as_str).collect();
2153                    ops.push(QueryOp::Sort {
2154                        numeric: flags.contains(&"-n"),
2155                        reverse: flags.contains(&"-r"),
2156                    });
2157                }
2158                "uniq" => ops.push(QueryOp::Uniq),
2159                "rev" => ops.push(QueryOp::Rev),
2160                "first" => ops.push(QueryOp::First),
2161                "last" => ops.push(QueryOp::Last),
2162                "upper" => ops.push(QueryOp::Upper),
2163                "lower" => ops.push(QueryOp::Lower),
2164                "trim" => ops.push(QueryOp::Trim),
2165                "replace" => {
2166                    let re = regex_arg(c)?;
2167                    let to = c
2168                        .args
2169                        .get(1)
2170                        .and_then(Arg::as_str)
2171                        .unwrap_or("")
2172                        .to_string();
2173                    ops.push(QueryOp::Replace(re, to));
2174                }
2175                "join" => {
2176                    let sep = c
2177                        .args
2178                        .first()
2179                        .and_then(Arg::as_str)
2180                        .unwrap_or(" ")
2181                        .to_string();
2182                    ops.push(QueryOp::Join(sep));
2183                }
2184                "nth" => ops.push(QueryOp::Nth(count_arg(c, "nth")?)),
2185                "take" => ops.push(QueryOp::Take(count_arg(c, "take")?)),
2186                "drop" => ops.push(QueryOp::Drop(count_arg(c, "drop")?)),
2187                "calc" => {
2188                    let src = c
2189                        .args
2190                        .iter()
2191                        .filter_map(Arg::as_str)
2192                        .collect::<Vec<_>>()
2193                        .join(" ");
2194                    ops.push(QueryOp::Calc(crate::expr::parse(&src)?));
2195                }
2196                "where" => {
2197                    let src = c
2198                        .args
2199                        .iter()
2200                        .filter_map(Arg::as_str)
2201                        .collect::<Vec<_>>()
2202                        .join(" ");
2203                    ops.push(QueryOp::Where(crate::expr::parse(&src)?));
2204                }
2205                "map" => {
2206                    let src = c
2207                        .args
2208                        .iter()
2209                        .filter_map(Arg::as_str)
2210                        .collect::<Vec<_>>()
2211                        .join(" ");
2212                    ops.push(QueryOp::Map(crate::expr::parse(&src)?));
2213                }
2214                "via" => {
2215                    // `via NAME` / `via NAME * N` — fan the stream across a pool of
2216                    // actor NAME. Tokens join then split on `*`: left = actor name,
2217                    // right = optional worker count (0 = one per hardware thread).
2218                    let joined = c
2219                        .args
2220                        .iter()
2221                        .filter_map(Arg::as_str)
2222                        .collect::<Vec<_>>()
2223                        .join(" ");
2224                    let (name, workers) = match joined.split_once('*') {
2225                        Some((n, w)) => {
2226                            let count = w.trim().parse::<usize>().map_err(|_| {
2227                                format!("via: `* {}` is not a worker count", w.trim())
2228                            })?;
2229                            // Cap the pool so `via NAME * 9999999` can't spawn a
2230                            // runaway number of threads.
2231                            (n.trim().to_string(), count.min(1024))
2232                        }
2233                        None => (joined.trim().to_string(), 0),
2234                    };
2235                    if name.is_empty() {
2236                        return Err("via: expected an actor name (`via NAME [* N]`)".into());
2237                    }
2238                    let def = actors
2239                        .get(&name)
2240                        .ok_or_else(|| format!("via: no actor named `{name}` in scope (declare `actor {name}(state) {{ … }}` before this `via`)"))?
2241                        .clone();
2242                    ops.push(QueryOp::Via(def, workers));
2243                }
2244                "sort_by" => {
2245                    let field = str_arg(c);
2246                    if field.is_empty() {
2247                        return Err("sort_by: expected a field name".into());
2248                    }
2249                    ops.push(QueryOp::SortBy(field));
2250                }
2251                "unique_by" => {
2252                    let field = str_arg(c);
2253                    if field.is_empty() {
2254                        return Err("unique_by: expected a field name".into());
2255                    }
2256                    ops.push(QueryOp::UniqueBy(field));
2257                }
2258                "count_by" => {
2259                    let field = str_arg(c);
2260                    if field.is_empty() {
2261                        return Err("count_by: expected a field name".into());
2262                    }
2263                    ops.push(QueryOp::CountBy(field));
2264                }
2265                "group_by" => {
2266                    let field = str_arg(c);
2267                    if field.is_empty() {
2268                        return Err("group_by: expected a field name".into());
2269                    }
2270                    ops.push(QueryOp::GroupBy(field));
2271                }
2272                "min_by" => {
2273                    let field = str_arg(c);
2274                    if field.is_empty() {
2275                        return Err("min_by: expected a field name".into());
2276                    }
2277                    ops.push(QueryOp::MinBy(field));
2278                }
2279                "max_by" => {
2280                    let field = str_arg(c);
2281                    if field.is_empty() {
2282                        return Err("max_by: expected a field name".into());
2283                    }
2284                    ops.push(QueryOp::MaxBy(field));
2285                }
2286                "has" => {
2287                    let key = str_arg(c);
2288                    if key.is_empty() {
2289                        return Err("has: expected a key name".into());
2290                    }
2291                    ops.push(QueryOp::Has(key));
2292                }
2293                "entries" => {
2294                    if !c.args.is_empty() {
2295                        return Err("entries: takes no arguments".into());
2296                    }
2297                    ops.push(QueryOp::Entries);
2298                }
2299                "flatten" => ops.push(QueryOp::Flatten),
2300                "add" => ops.push(QueryOp::Add),
2301                "over" => {
2302                    let n = c
2303                        .args
2304                        .first()
2305                        .and_then(Arg::as_str)
2306                        .and_then(|s| s.parse::<f64>().ok())
2307                        .ok_or_else(|| "over: expected a numeric threshold".to_string())?;
2308                    ops.push(QueryOp::Over(n));
2309                }
2310                "under" => {
2311                    let n: f64 = str_arg(c)
2312                        .parse()
2313                        .map_err(|_| "under: expected a number".to_string())?;
2314                    ops.push(QueryOp::Under(n));
2315                }
2316                "between" => {
2317                    let lo = c
2318                        .args
2319                        .first()
2320                        .and_then(Arg::as_str)
2321                        .and_then(|s| s.parse::<f64>().ok())
2322                        .ok_or_else(|| "between: expected two numbers A B".to_string())?;
2323                    let hi = c
2324                        .args
2325                        .get(1)
2326                        .and_then(Arg::as_str)
2327                        .and_then(|s| s.parse::<f64>().ok())
2328                        .ok_or_else(|| "between: expected two numbers A B".to_string())?;
2329                    ops.push(QueryOp::Between(lo, hi));
2330                }
2331                "enumerate" => {
2332                    ops.push(QueryOp::Enumerate);
2333                }
2334                "words" => {
2335                    if !c.args.is_empty() {
2336                        return Err("words: takes no arguments".into());
2337                    }
2338                    ops.push(QueryOp::Words);
2339                }
2340                "dedup" => ops.push(QueryOp::Dedup),
2341                "tailn" => ops.push(QueryOp::Tailn(count_arg(c, "tailn")?)),
2342                "pad" => {
2343                    let n = count_arg(c, "pad")?;
2344                    ops.push(QueryOp::Pad(n));
2345                }
2346                "lpad" => ops.push(QueryOp::Lpad(count_arg(c, "lpad")?)),
2347                "grepf" => {
2348                    let field = c
2349                        .args
2350                        .first()
2351                        .and_then(Arg::as_str)
2352                        .ok_or_else(|| "grepf: expected FIELD and /re/".to_string())?
2353                        .to_string();
2354                    let raw = c
2355                        .args
2356                        .get(1)
2357                        .and_then(Arg::as_str)
2358                        .ok_or_else(|| "grepf: expected a pattern".to_string())?;
2359                    let pat = raw
2360                        .strip_prefix('/')
2361                        .and_then(|s| s.strip_suffix('/'))
2362                        .unwrap_or(raw);
2363                    let re =
2364                        regex::Regex::new(pat).map_err(|e| format!("grepf: bad regex: {e}"))?;
2365                    ops.push(QueryOp::Grepf(field, re));
2366                }
2367                "apply" => {
2368                    let name = str_arg(c);
2369                    let name = name.strip_prefix('.').unwrap_or(&name).to_string();
2370                    ops.push(QueryOp::Apply(name));
2371                }
2372                "basename" => ops.push(QueryOp::Basename),
2373                "dirname" => ops.push(QueryOp::Dirname),
2374                "commafy" => ops.push(QueryOp::Commafy),
2375                "bytes" => ops.push(QueryOp::Bytes),
2376                "duration" => ops.push(QueryOp::Duration),
2377                "flip" => {
2378                    ops.push(QueryOp::Flip);
2379                }
2380                "b64" => {
2381                    ops.push(QueryOp::B64);
2382                }
2383                "b64d" => {
2384                    ops.push(QueryOp::B64d);
2385                }
2386                "hex" => ops.push(QueryOp::Hex),
2387                "unhex" => {
2388                    ops.push(QueryOp::Unhex);
2389                }
2390                "urlenc" => {
2391                    ops.push(QueryOp::Urlenc);
2392                }
2393                "urldec" => {
2394                    ops.push(QueryOp::Urldec);
2395                }
2396                "extract" => {
2397                    ops.push(QueryOp::Extract(regex_arg(c)?));
2398                }
2399                "split" => {
2400                    let delim = str_arg(c);
2401                    if delim.is_empty() {
2402                        return Err("split: expected a non-empty delimiter".into());
2403                    }
2404                    ops.push(QueryOp::Split(delim));
2405                }
2406                "substr" => {
2407                    let args: Vec<usize> = c
2408                        .args
2409                        .iter()
2410                        .filter_map(Arg::as_str)
2411                        .filter_map(|s| s.parse::<usize>().ok())
2412                        .collect();
2413                    if args.len() != 2 {
2414                        return Err("substr: expected two non-negative integer args A B".into());
2415                    }
2416                    ops.push(QueryOp::Substr(args[0], args[1]));
2417                }
2418                "chars" => ops.push(QueryOp::Chars),
2419                "title" => {
2420                    ops.push(QueryOp::Title);
2421                }
2422                "repeat" => {
2423                    let n = count_arg(c, "repeat")?;
2424                    ops.push(QueryOp::Repeat(n));
2425                }
2426                "set" => {
2427                    let key = str_arg(c);
2428                    if key.is_empty() {
2429                        return Err("set: expected key and value".into());
2430                    }
2431                    let val = c
2432                        .args
2433                        .iter()
2434                        .filter_map(Arg::as_str)
2435                        .nth(1)
2436                        .unwrap_or("")
2437                        .to_string();
2438                    ops.push(QueryOp::Set(key, val));
2439                }
2440                "del" => {
2441                    let key = str_arg(c);
2442                    if key.is_empty() {
2443                        return Err("del: expected a key name".into());
2444                    }
2445                    ops.push(QueryOp::Del(key));
2446                }
2447                "rename" => {
2448                    let args: Vec<String> = c
2449                        .args
2450                        .iter()
2451                        .filter_map(Arg::as_str)
2452                        .map(str::to_string)
2453                        .collect();
2454                    if args.len() != 2 || args[0].is_empty() || args[1].is_empty() {
2455                        return Err("rename: expected OLD NEW key names".into());
2456                    }
2457                    ops.push(QueryOp::Rename(args[0].clone(), args[1].clone()));
2458                }
2459                "default" => {
2460                    let args: Vec<String> = c
2461                        .args
2462                        .iter()
2463                        .filter_map(Arg::as_str)
2464                        .map(str::to_string)
2465                        .collect();
2466                    if args.len() != 2 {
2467                        return Err("default: expected exactly two args: key value".into());
2468                    }
2469                    ops.push(QueryOp::Default(args[0].clone(), args[1].clone()));
2470                }
2471                "merge" => {
2472                    ops.push(QueryOp::Merge);
2473                }
2474                "floor" => {
2475                    ops.push(QueryOp::Floor);
2476                }
2477                "ceil" => {
2478                    ops.push(QueryOp::Ceil);
2479                }
2480                "clamp" => {
2481                    let mut it = c.args.iter().filter_map(Arg::as_str);
2482                    let lo = it.next().and_then(|s| s.parse::<f64>().ok());
2483                    let hi = it.next().and_then(|s| s.parse::<f64>().ok());
2484                    match (lo, hi) {
2485                        (Some(lo), Some(hi)) => ops.push(QueryOp::Clamp(lo, hi)),
2486                        _ => return Err("clamp: expected LO HI numeric args".into()),
2487                    }
2488                }
2489                "contains" => ops.push(QueryOp::Contains(str_arg(c))),
2490                "starts" => ops.push(QueryOp::Starts(str_arg(c))),
2491                "ends" => ops.push(QueryOp::Ends(str_arg(c))),
2492                "nonempty" => ops.push(QueryOp::Nonempty),
2493                "numeric" => ops.push(QueryOp::Numeric),
2494                "len" => ops.push(QueryOp::Len),
2495                // jq `length`: JSON-aware (array/object/string/number), vs `len`
2496                // which is the raw char count.
2497                "length" => ops.push(QueryOp::JsonLen),
2498                "wc" => ops.push(QueryOp::Wc),
2499                "abs" => ops.push(QueryOp::Abs),
2500                "round" => ops.push(QueryOp::Round),
2501                "delta" => ops.push(QueryOp::Delta),
2502                "cumsum" => ops.push(QueryOp::Cumsum),
2503                "sma" => ops.push(QueryOp::Sma(count_arg(c, "sma")?)),
2504                "ewma" => {
2505                    let a = str_arg(c).parse::<f64>().map_err(|_| {
2506                        "ewma: expected a smoothing factor 0–1 (e.g. 0.3)".to_string()
2507                    })?;
2508                    ops.push(QueryOp::Ewma(a));
2509                }
2510                "prepend" => ops.push(QueryOp::Prepend(str_arg(c))),
2511                "append" => ops.push(QueryOp::Append(str_arg(c))),
2512                "cut" => {
2513                    let delim = str_arg(c);
2514                    let n = c
2515                        .args
2516                        .get(1)
2517                        .and_then(Arg::as_str)
2518                        .and_then(|s| s.parse::<usize>().ok())
2519                        .unwrap_or(0);
2520                    ops.push(QueryOp::Cut(delim, n));
2521                }
2522                "median" => ops.push(QueryOp::Median),
2523                "percentile" => {
2524                    let p = str_arg(c)
2525                        .parse::<f64>()
2526                        .map_err(|_| "percentile: expected a number 0–100 (e.g. 99)".to_string())?;
2527                    ops.push(QueryOp::Percentile(p));
2528                }
2529                "p50" => ops.push(QueryOp::Percentile(50.0)),
2530                "p90" => ops.push(QueryOp::Percentile(90.0)),
2531                "p95" => ops.push(QueryOp::Percentile(95.0)),
2532                "p99" => ops.push(QueryOp::Percentile(99.0)),
2533                "stddev" => ops.push(QueryOp::Stddev),
2534                "range" => ops.push(QueryOp::Range),
2535                "product" => ops.push(QueryOp::Product),
2536                "distinct" => ops.push(QueryOp::Distinct),
2537                "sample" => ops.push(QueryOp::Sample(count_arg(c, "sample")?)),
2538                "bins" => ops.push(QueryOp::Bins(count_arg(c, "bins")?)),
2539                "index" => ops.push(QueryOp::Index(count_arg(c, "index")?)),
2540                "slice" => {
2541                    let a = c
2542                        .args
2543                        .first()
2544                        .and_then(Arg::as_str)
2545                        .and_then(|s| s.parse::<usize>().ok())
2546                        .unwrap_or(1);
2547                    let b = c
2548                        .args
2549                        .get(1)
2550                        .and_then(Arg::as_str)
2551                        .and_then(|s| s.parse::<usize>().ok())
2552                        .unwrap_or(usize::MAX);
2553                    ops.push(QueryOp::Slice(a, b));
2554                }
2555                // Not an arb verb. Before reporting one, try the whole command
2556                // as a jq PROGRAM: `crate::jq` translates the subset that maps
2557                // onto arb's line-stream ops, and `crate::jqlang` runs everything
2558                // else as real jq. The native table is matched FIRST and wins
2559                // every shared spelling, which is exactly the context rule SPEC
2560                // §8 states — a bare alphanumeric word is arb's native verb, and
2561                // only what arb has no verb for reaches jq.
2562                other => {
2563                    let mut parts = vec![other.to_string()];
2564                    parts.extend(c.args.iter().map(|a| match a {
2565                        Arg::Block(inner) => format!("{{{}}}", block_text(inner)),
2566                        // A QUOTED arg must be handed on still quoted. `as_str`
2567                        // flattens `Arg::Str` and `Arg::Word` to the same text,
2568                        // so `string-length("abcd")` was reconstructed as
2569                        // `string-length(abcd)` — where `abcd` reads as a
2570                        // location path, and the answer came back 0 instead of
2571                        // 4. The same loss reaches jq, where `select(.a == "x")`
2572                        // became `select(.a == x)`.
2573                        Arg::Str(v) => quote_arg(v),
2574                        x => x.as_str().unwrap_or_default().to_string(),
2575                    }));
2576                    let src = parts.join(" ");
2577                    match crate::query::jq_program(&src) {
2578                        Ok(_) => ops.push(QueryOp::JqProgram(src)),
2579                        // A program that opens with a double-quoted string is
2580                        // jq's even when jq refuses it. XPath spells a string
2581                        // literal the same way but has no escapes, so the
2582                        // fallback below read `"\(1;2)"` — a jq syntax error —
2583                        // as the literal text `\(1;2)` and printed it.
2584                        Err(e) if src.starts_with('"') => {
2585                            return Err(format!("jq: {}", e.trim_start_matches("jq: ")).into())
2586                        }
2587                        // Not a native verb and not a jq program: try XPath, but
2588                        // only HERE, as the LAST resort.
2589                        //
2590                        // XPath's core library shares spellings with jq and with
2591                        // arb's own verbs, and a language matched BEFORE another
2592                        // does not merely win a word — it SHADOWS it. That is
2593                        // what made a native verb named `keys` break the jq
2594                        // superset, and the fix is not to repeat it. Being last
2595                        // means XPath can never take a spelling another engine
2596                        // answers: `contains("a","b")` stays jq's, and XPath's
2597                        // two-argument `contains` is still reachable where it is
2598                        // actually used, inside an expression
2599                        // (`//p[contains(@class,'a')]`).
2600                        //
2601                        // Measured on this corpus: of the 27 core functions,
2602                        // `contains` is the only spelling jq claims.
2603                        Err(_) => match crate::xpath::translate(&src) {
2604                            Ok(xops) => ops.extend(xops),
2605                            // Report arb's own diagnostic, not a parse error from
2606                            // either guest language: a typo'd arb verb is far
2607                            // likelier, and "unknown verb" points at the real
2608                            // mistake.
2609                            Err(_) => return Err(format!("source: unknown verb `{other}`").into()),
2610                        },
2611                    }
2612                }
2613            }
2614            Ok(())
2615        })();
2616        step.map_err(|e| e.or_span(c.pos, c.name.chars().count()))?;
2617    }
2618    if !saw_in {
2619        return Err("source: pipeline must start with `in`".into());
2620    }
2621    Ok(ops)
2622}
2623
2624/// Compile a `/pattern/` (or bare `pattern`) literal into a `Regex`. Shared by
2625/// the arg form (`match /re/`, single-clause `expect /re/ …`) and the
2626/// `expect { }` block-clause form, where the `/re/` arrives as the clause
2627/// command's *name*.
2628fn compile_regex(raw: &str) -> Result<Regex, String> {
2629    let pat = raw
2630        .strip_prefix('/')
2631        .and_then(|s| s.strip_suffix('/'))
2632        .unwrap_or(raw);
2633    Regex::new(pat).map_err(|e| format!("bad regex: {e}"))
2634}
2635
2636/// Refuse a CSS selector `scraper` cannot parse.
2637///
2638/// Reported at BUILD time so it can never be mistaken for an empty match at run
2639/// time — the message names the verb and the selector, which is what points at
2640/// the mistake in a spec file.
2641fn check_css(css: &str, verb: &str) -> Result<(), crate::err::SpecError> {
2642    match scraper::Selector::parse(css) {
2643        Ok(_) => Ok(()),
2644        Err(e) => Err(format!("{verb}: `{css}` is not a valid CSS selector ({e})").into()),
2645    }
2646}
2647
2648/// Re-quote a string argument for a reconstructed command.
2649///
2650/// Double quotes are the default because that is what jq needs; a value that
2651/// itself contains one is wrapped in single quotes instead, which both jq and
2652/// XPath accept. A value containing BOTH has no quoting that is literal in
2653/// XPath 1.0 (its Literal production has no escape sequence at all), so it is
2654/// escaped for jq and that limitation is stated rather than papered over.
2655fn quote_arg(v: &str) -> String {
2656    if v.contains('"') && !v.contains('\'') {
2657        format!("'{v}'")
2658    } else {
2659        format!("\"{}\"", v.replace('\\', "\\\\").replace('"', "\\\""))
2660    }
2661}
2662
2663/// Reconstruct a shell string from a `{ … }` block body: each top-level command
2664/// contributes its verb + word args, commands joined by `; ` (`{ ps aux }` ->
2665/// "ps aux"; `{ tail -f a.log; grep err }` -> "tail -f a.log; grep err").
2666fn block_to_shell(cmds: &[Command]) -> String {
2667    cmds.iter()
2668        .map(|c| {
2669            let mut w = vec![c.name.clone()];
2670            w.extend(c.args.iter().filter_map(|a| a.as_str().map(str::to_string)));
2671            w.join(" ")
2672        })
2673        .collect::<Vec<_>>()
2674        .join("; ")
2675}
2676
2677/// Read a regex argument, stripping optional `/…/` delimiters. The error carries
2678/// this command's source span so a bad regex anchors to the offending verb (e.g.
2679/// `match` inside a `source { … }` body), not the enclosing directive.
2680fn regex_arg(c: &Command) -> Result<Regex, crate::err::SpecError> {
2681    let span =
2682        |msg: String| crate::err::SpecError::from(msg).or_span(c.pos, c.name.chars().count());
2683    let raw = c
2684        .args
2685        .first()
2686        .and_then(Arg::as_str)
2687        .ok_or_else(|| span(format!("{}: expected a pattern", c.name)))?;
2688    compile_regex(raw).map_err(|e| span(format!("{}: {e}", c.name)))
2689}
2690
2691/// Parse a required count argument for `take`/`drop`.
2692/// The first arg as a string (empty if absent) — for verbs taking a literal.
2693fn str_arg(c: &Command) -> String {
2694    c.args
2695        .first()
2696        .and_then(Arg::as_str)
2697        .unwrap_or("")
2698        .to_string()
2699}
2700
2701fn count_arg(c: &Command, verb: &str) -> Result<usize, String> {
2702    c.args
2703        .first()
2704        .and_then(Arg::as_str)
2705        .and_then(|s| s.parse::<usize>().ok())
2706        .ok_or_else(|| format!("{verb}: expected a count"))
2707}
2708
2709/// A single numeric arg selects a whitespace column; anything else is a JSON
2710/// key path (`field a b c` -> a.b.c).
2711fn field_sel(args: &[Arg]) -> Result<FieldSel, String> {
2712    let words: Vec<&str> = args.iter().filter_map(Arg::as_str).collect();
2713    if words.is_empty() {
2714        return Err("field: expected a column number or key path".into());
2715    }
2716    if words.len() == 1 {
2717        if let Ok(n) = words[0].parse::<usize>() {
2718            return Ok(FieldSel::Col(n));
2719        }
2720    }
2721    Ok(FieldSel::Key(words.iter().map(|s| s.to_string()).collect()))
2722}
2723
2724fn set_source(spec: &mut Spec, path: &str, src: Source) -> Result<(), String> {
2725    for w in &mut spec.widgets {
2726        if w.path == path {
2727            w.source = Some(src);
2728            return Ok(());
2729        }
2730    }
2731    Err(format!("source: no widget named `{path}`"))
2732}
2733
2734/// `.path configure -k v …`: merge `opts` into the named widget's options
2735/// (later keys win), so a spec can retune a widget after declaring it.
2736fn configure_widget(
2737    spec: &mut Spec,
2738    path: &str,
2739    opts: BTreeMap<String, String>,
2740) -> Result<(), String> {
2741    for w in &mut spec.widgets {
2742        if w.path == path {
2743            w.opts.extend(opts);
2744            return Ok(());
2745        }
2746    }
2747    Err(format!("configure: no widget named `{path}`"))
2748}
2749
2750fn set_search(spec: &mut Spec, path: &str, pipeline: Vec<QueryOp>) -> Result<(), String> {
2751    for w in &mut spec.widgets {
2752        if w.path == path {
2753            w.search = Some(pipeline);
2754            return Ok(());
2755        }
2756    }
2757    Err(format!("search: no widget named `{path}`"))
2758}
2759
2760fn set_grid(
2761    spec: &mut Spec,
2762    path: &str,
2763    cell: (usize, usize),
2764    span: (usize, usize),
2765) -> Result<(), String> {
2766    for w in &mut spec.widgets {
2767        if w.path == path {
2768            w.grid = Some(cell);
2769            w.span = span;
2770            return Ok(());
2771        }
2772    }
2773    Err(format!("grid: no widget named `{path}`"))
2774}
2775
2776/// Whether a command's first token opens a jq `@format`.
2777///
2778/// A leading `@` otherwise means an XPATH attribute step, so only the nine
2779/// format names are claimed and `@href` still selects an attribute. What decides
2780/// is where the NAME ends — any character that could not continue an identifier
2781/// — not whether a space follows it.
2782///
2783/// That distinction is the bug this replaced. The test used to be
2784/// `starts_with("@base64 ")`, so `@base64|length` matched nothing here and fell
2785/// through to the xpath front-end below, where `@base64` is an attribute step
2786/// and `|` is the union operator. It parsed, ran against JSON, and printed
2787/// NOTHING — and `@base64|.` printed the input unencoded. A jq program silently
2788/// answering as xpath is the worst shape of divergence, because both engines are
2789/// real and neither reports a problem. `@base64d ` was also absent from that
2790/// list, so the trailing-space form of it had the same fate.
2791///
2792/// Any NAME followed by a string is a jq format string too (`@foo "lit"`): jq
2793/// decides at run time whether it knows the format, and an xpath attribute
2794/// step is never followed by a string.
2795fn opens_jq_format(name: &str) -> bool {
2796    let Some(rest) = name.strip_prefix('@') else {
2797        return false;
2798    };
2799    let after = rest.trim_start_matches(|c: char| c.is_alphanumeric() || c == '_');
2800    if after.len() < rest.len() && after.trim_start().starts_with('"') {
2801        return true;
2802    }
2803    crate::jqlang::FORMAT_NAMES.iter().any(|f| {
2804        rest.strip_prefix(f)
2805            .is_some_and(|tail| !tail.starts_with(|c: char| c.is_alphanumeric() || c == '_'))
2806    })
2807}