Skip to main content

hyprstream_workers_tcl/
builtins.rs

1//! VFS builtins for the Tcl shell.
2//!
3//! Each command is an `AsyncCommandFunc` registered via `add_async_context_command`.
4//! VFS operations are called directly on the Namespace — no proxy channel needed.
5
6use molt::molt_err;
7use molt::molt_ok;
8use molt::types::*;
9use molt::Interp;
10use std::sync::Arc;
11
12use crate::ShellContext;
13
14/// Register all VFS builtins on the interpreter.
15pub fn register_all(interp: &mut Interp, ctx_id: ContextID) {
16    interp.add_async_context_command("cat", cmd_cat, ctx_id);
17    interp.add_async_context_command("ls", cmd_ls, ctx_id);
18    interp.add_async_context_command("write", cmd_write, ctx_id);
19    interp.add_async_context_command("ctl", cmd_ctl, ctx_id);
20    interp.add_context_command("json", cmd_json, ctx_id);
21    interp.add_async_context_command("help", cmd_help, ctx_id);
22    interp.add_async_context_command("man", cmd_man, ctx_id);
23    interp.add_async_context_command("stream", cmd_stream, ctx_id);
24    interp.add_async_context_command("mount", cmd_mount, ctx_id);
25}
26
27/// `cat path [path ...]` — read file contents from the VFS.
28fn cmd_cat<'a>(
29    interp: &'a mut Interp,
30    ctx_id: ContextID,
31    argv: &'a [Value],
32) -> BoxFuture<'a, MoltResult> {
33    Box::pin(async move {
34        molt::check_args(1, argv, 2, 0, "path ?path ...?")?;
35
36        let paths: Vec<String> = argv[1..].iter().map(|v| v.to_string()).collect();
37        let ctx = interp.context::<ShellContext>(ctx_id);
38        let namespace = Arc::clone(&ctx.namespace);
39        let subject = ctx.subject.clone();
40
41        let mut output = String::new();
42        for path in &paths {
43            match namespace.cat(path, &subject).await {
44                Ok(data) => output.push_str(&String::from_utf8_lossy(&data)),
45                Err(e) => return molt_err!("{}: {}", path, e),
46            }
47        }
48        molt_ok!(output)
49    })
50}
51
52/// `ls [path]` — list directory entries. Defaults to `/`.
53fn cmd_ls<'a>(
54    interp: &'a mut Interp,
55    ctx_id: ContextID,
56    argv: &'a [Value],
57) -> BoxFuture<'a, MoltResult> {
58    Box::pin(async move {
59        molt::check_args(1, argv, 1, 2, "?path?")?;
60
61        let path = if argv.len() > 1 {
62            argv[1].to_string()
63        } else {
64            "/".to_owned()
65        };
66
67        let ctx = interp.context::<ShellContext>(ctx_id);
68        let namespace = Arc::clone(&ctx.namespace);
69        let subject = ctx.subject.clone();
70
71        match namespace.ls(&path, &subject).await {
72            Ok(entries) => {
73                let text: String = entries
74                    .iter()
75                    .map(|e| {
76                        if e.is_dir {
77                            format!("{}/", e.name)
78                        } else {
79                            e.name.clone()
80                        }
81                    })
82                    .collect::<Vec<_>>()
83                    .join("\n");
84                molt_ok!(text)
85            }
86            Err(e) => molt_err!("{}: {}", path, e),
87        }
88    })
89}
90
91/// `write path data` — write data to a VFS file.
92fn cmd_write<'a>(
93    interp: &'a mut Interp,
94    ctx_id: ContextID,
95    argv: &'a [Value],
96) -> BoxFuture<'a, MoltResult> {
97    Box::pin(async move {
98        molt::check_args(1, argv, 3, 3, "path data")?;
99
100        let path = argv[1].to_string();
101        let data = argv[2].to_string();
102        let ctx = interp.context::<ShellContext>(ctx_id);
103        let namespace = Arc::clone(&ctx.namespace);
104        let subject = ctx.subject.clone();
105
106        match namespace.echo(&path, data.as_bytes(), &subject).await {
107            Ok(_) => molt_ok!(),
108            Err(e) => molt_err!("{}: {}", path, e),
109        }
110    })
111}
112
113/// `ctl path command [args...]` — write to a ctl file and read the response.
114fn cmd_ctl<'a>(
115    interp: &'a mut Interp,
116    ctx_id: ContextID,
117    argv: &'a [Value],
118) -> BoxFuture<'a, MoltResult> {
119    Box::pin(async move {
120        molt::check_args(1, argv, 3, 0, "path command ?args ...?")?;
121
122        let path = argv[1].to_string();
123        let cmd_parts: Vec<String> = argv[2..].iter().map(|v| v.to_string()).collect();
124        let cmd_str = cmd_parts.join(" ");
125
126        let ctx = interp.context::<ShellContext>(ctx_id);
127        let namespace = Arc::clone(&ctx.namespace);
128        let subject = ctx.subject.clone();
129
130        match namespace.ctl(&path, cmd_str.as_bytes(), &subject).await {
131            Ok(resp) => {
132                let text = String::from_utf8_lossy(&resp);
133                molt_ok!(text.into_owned())
134            }
135            Err(e) => molt_err!("{}: {}", path, e),
136        }
137    })
138}
139
140/// `json parse value` — convert a JSON string to a Tcl dict.
141fn cmd_json(_interp: &mut Interp, _ctx_id: ContextID, argv: &[Value]) -> MoltResult {
142    molt::check_args(1, argv, 3, 3, "parse value")?;
143
144    let subcmd = argv[1].to_string();
145    if subcmd != "parse" {
146        return molt_err!("unknown subcommand \"{}\": must be parse", subcmd);
147    }
148
149    let json_str = argv[2].to_string();
150    let parsed: serde_json::Value = match serde_json::from_str(&json_str) {
151        Ok(v) => v,
152        Err(e) => return molt_err!("invalid JSON: {}", e),
153    };
154    molt_ok!(json_to_tcl(&parsed))
155}
156
157/// Convert a serde_json::Value to a Tcl string representation.
158fn json_to_tcl(val: &serde_json::Value) -> String {
159    match val {
160        serde_json::Value::Object(map) => {
161            let mut parts = Vec::with_capacity(map.len() * 2);
162            for (k, v) in map {
163                parts.push(tcl_list_escape(k));
164                parts.push(tcl_list_escape(&json_to_tcl(v)));
165            }
166            parts.join(" ")
167        }
168        serde_json::Value::Array(arr) => {
169            let items: Vec<String> = arr
170                .iter()
171                .map(|v| tcl_list_escape(&json_to_tcl(v)))
172                .collect();
173            items.join(" ")
174        }
175        serde_json::Value::String(s) => s.clone(),
176        serde_json::Value::Number(n) => n.to_string(),
177        serde_json::Value::Bool(b) => (if *b { "1" } else { "0" }).to_owned(),
178        serde_json::Value::Null => String::new(),
179    }
180}
181
182/// Escape a string for safe inclusion in a Tcl list.
183fn tcl_list_escape(s: &str) -> String {
184    if s.is_empty()
185        || s.contains(|c: char| c.is_whitespace() || c == '{' || c == '}' || c == '\\' || c == '"')
186    {
187        format!("{{{}}}", s)
188    } else {
189        s.to_owned()
190    }
191}
192
193/// `help` — list VFS builtins and `/bin/` entries.
194fn cmd_help<'a>(
195    interp: &'a mut Interp,
196    ctx_id: ContextID,
197    argv: &'a [Value],
198) -> BoxFuture<'a, MoltResult> {
199    Box::pin(async move {
200        molt::check_args(1, argv, 1, 1, "")?;
201
202        let mut out = String::new();
203        out.push_str("VFS commands:\n");
204        out.push_str("  cat <path>           read file contents\n");
205        out.push_str("  ls [path]            list directory\n");
206        out.push_str("  write <path> <data>  write to file\n");
207        out.push_str("  ctl <path> <cmd>     control file (write+read)\n");
208        out.push_str("  json parse <str>     convert JSON to Tcl dict\n");
209        out.push_str("  mount [prefix]       list mount points\n");
210        out.push_str("  man [svc] [method]   service documentation\n");
211        out.push_str("  stream <path> <method> <args> <var> <body>  stream with callback\n");
212        out.push_str("  help                 this message\n");
213
214        let ctx = interp.context::<ShellContext>(ctx_id);
215        let namespace = Arc::clone(&ctx.namespace);
216        let subject = ctx.subject.clone();
217
218        if let Ok(entries) = namespace.ls("/bin", &subject).await {
219            if !entries.is_empty() {
220                out.push_str("\nCommands (/bin/):\n");
221                for entry in &entries {
222                    let name = entry.name.trim_end_matches('/');
223                    if !name.is_empty() {
224                        out.push_str(&format!("  {}\n", name));
225                    }
226                }
227            }
228        }
229
230        molt_ok!(out)
231    })
232}
233
234/// `man [service [method ...]]` — display service documentation.
235///
236/// Reads from `/srv/{service}/doc/{method}` in the VFS namespace.
237/// Without arguments, lists all available services.
238fn cmd_man<'a>(
239    interp: &'a mut Interp,
240    ctx_id: ContextID,
241    argv: &'a [Value],
242) -> BoxFuture<'a, MoltResult> {
243    Box::pin(async move {
244        molt::check_args(1, argv, 1, 0, "?service? ?method ...?")?;
245
246        let ctx = interp.context::<ShellContext>(ctx_id);
247        let namespace = Arc::clone(&ctx.namespace);
248        let subject = ctx.subject.clone();
249
250        if argv.len() == 1 {
251            // No args: list available services under /srv
252            match namespace.ls("/srv", &subject).await {
253                Ok(entries) => {
254                    let mut out = String::from("Available services:\n");
255                    for e in &entries {
256                        let name = e.name.trim_end_matches('/');
257                        if !name.is_empty() {
258                            out.push_str(&format!("  {}\n", name));
259                        }
260                    }
261                    out.push_str("\nUsage: man <service> [method]");
262                    molt_ok!(out)
263                }
264                Err(e) => molt_err!("cannot list services: {}", e),
265            }
266        } else {
267            // Build doc path: /srv/{service}/doc/{method...}
268            let service = argv[1].to_string();
269            let mut path = format!("/srv/{}/doc", service);
270            for arg in &argv[2..] {
271                path.push('/');
272                path.push_str(&arg.to_string());
273            }
274
275            match namespace.cat(&path, &subject).await {
276                Ok(data) => molt_ok!(String::from_utf8_lossy(&data).into_owned()),
277                Err(_) => {
278                    // Fallback: try listing if it's a directory
279                    match namespace.ls(&path, &subject).await {
280                        Ok(entries) => {
281                            let mut out = format!("{}:\n", path);
282                            for e in &entries {
283                                let name = e.name.trim_end_matches('/');
284                                if !name.is_empty() {
285                                    out.push_str(&format!("  {}\n", name));
286                                }
287                            }
288                            molt_ok!(out)
289                        }
290                        Err(e) => molt_err!("{}: {}", path, e),
291                    }
292                }
293            }
294        }
295    })
296}
297
298/// `stream path method args varname body` — start a stream and iterate blocks.
299///
300/// Starts a streaming RPC via `ctl`, reads blocks from `/stream/{topic}/data`,
301/// and evaluates `body` for each block with the data bound to `varname`.
302///
303/// Example:
304///   stream /srv/model infer.generate_stream {"prompt":"hello"} chunk { puts $chunk }
305///
306/// Also supports `stream start path method args` which returns the topic.
307fn cmd_stream<'a>(
308    interp: &'a mut Interp,
309    ctx_id: ContextID,
310    argv: &'a [Value],
311) -> BoxFuture<'a, MoltResult> {
312    Box::pin(async move {
313        // stream start path method args → returns topic
314        // stream path method args varname body → iterate blocks
315        if argv.len() >= 5 && argv[1].to_string() == "start" {
316            // stream start /srv/model method args
317            molt::check_args(1, argv, 5, 5, "start path method args")?;
318            let path = argv[2].to_string();
319            let method = argv[3].to_string();
320            let args = argv[4].to_string();
321
322            let ctx = interp.context::<ShellContext>(ctx_id);
323            let namespace = Arc::clone(&ctx.namespace);
324            let subject = ctx.subject.clone();
325
326            let topic = start_stream(&namespace, &subject, &path, &method, &args).await?;
327            molt_ok!(topic)
328        } else if argv.len() == 6 {
329            // stream path method args varname body
330            let path = argv[1].to_string();
331            let method = argv[2].to_string();
332            let args_str = argv[3].to_string();
333            let var_name = argv[4].to_string();
334            let body = argv[5].clone();
335
336            let ctx = interp.context::<ShellContext>(ctx_id);
337            let namespace = Arc::clone(&ctx.namespace);
338            let subject = ctx.subject.clone();
339
340            let topic = start_stream(&namespace, &subject, &path, &method, &args_str).await?;
341
342            // Read blocks from /stream/{topic}/data until EOF
343            let data_path = format!("/stream/{}/data", topic);
344            let var_val = Value::from(var_name.as_str());
345            let mut total_output = String::new();
346
347            // Read one block at a time, evaluating body between reads.
348            // Each read_one() yields to the event loop, allowing other JS work.
349            loop {
350                match namespace.read_one(&data_path, &subject).await {
351                    Ok(data) if data.is_empty() => break, // EOF
352                    Ok(data) => {
353                        let chunk = String::from_utf8_lossy(&data);
354                        interp.set_var(&var_val, Value::from(chunk.as_ref()))?;
355                        match interp.eval_value(&body).await {
356                            Ok(val) => total_output.push_str(&val.to_string()),
357                            Err(e) => {
358                                let ctl_path = format!("/stream/{}/ctl", topic);
359                                let _ = namespace.echo(&ctl_path, b"cancel", &subject).await;
360                                return Err(e);
361                            }
362                        }
363                    }
364                    Err(e) => return molt_err!("stream read: {}", e),
365                }
366            }
367
368            molt_ok!(total_output)
369        } else {
370            molt_err!(
371                "usage: stream path method args varname body\n       stream start path method args"
372            )
373        }
374    })
375}
376
377/// Start a stream via ctl and return the topic string.
378async fn start_stream(
379    namespace: &hyprstream_vfs::Namespace,
380    subject: &hyprstream_vfs::Subject,
381    path: &str,
382    method: &str,
383    args: &str,
384) -> Result<String, molt::Exception> {
385    let ctl_data = format!("{} {}", method, args);
386    let result = namespace
387        .ctl(path, ctl_data.as_bytes(), subject)
388        .await
389        .map_err(|e| molt::Exception::molt_err(Value::from(format!("stream start: {}", e))))?;
390    let result_str = String::from_utf8_lossy(&result);
391
392    let parsed: serde_json::Value = serde_json::from_str(&result_str).map_err(|e| {
393        molt::Exception::molt_err(Value::from(format!(
394            "stream start: invalid response: {}",
395            e
396        )))
397    })?;
398
399    parsed
400        .get("topic")
401        .or_else(|| parsed.get("streamId"))
402        .and_then(|v| v.as_str())
403        .map(|s| s.to_owned())
404        .ok_or_else(|| molt::Exception::molt_err(Value::from("stream start: no topic in response")))
405}
406
407/// `mount [prefix]` — list mount points (read-only).
408fn cmd_mount<'a>(
409    interp: &'a mut Interp,
410    ctx_id: ContextID,
411    argv: &'a [Value],
412) -> BoxFuture<'a, MoltResult> {
413    Box::pin(async move {
414        molt::check_args(1, argv, 1, 2, "?prefix?")?;
415
416        let ctx = interp.context::<ShellContext>(ctx_id);
417        let namespace = Arc::clone(&ctx.namespace);
418        let prefixes = namespace.mount_prefixes();
419        let prefixes_str = prefixes.join("\n");
420
421        if argv.len() == 1 {
422            molt_ok!(prefixes_str)
423        } else {
424            let prefix = argv[1].to_string();
425            if prefixes.iter().any(|p| *p == prefix) {
426                molt_ok!(format!("mounted: {}", prefix))
427            } else {
428                molt_err!("not mounted: {}", prefix)
429            }
430        }
431    })
432}