vce-shell 0.1.1

VCE Shell layer: command language, builtins, execution coordination
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
//! End-to-end integration test: real command resolution over the virtual
//! filesystem, the terminal's alternate screen (`man`) and key-driven
//! editors (`nano`), write-event generation, and script execution.

use engine::{BytesInput, BytesOutput, Timestamp};
use os::HostIdentity;
use os::linux::Linux;
use os::macos::MacOS;
use shell::Shell;
use shell::bash::Bash;
use shell::zsh::Zsh;
use terminal::{Size, Terminal, TerminalModel};

#[test]
fn end_to_end_shell_operations() {
    let linux = Linux::with_identity(
        &HostIdentity::new("demo", "demo-host"),
        Timestamp::from_nanos(1_772_323_200 * 1_000_000_000),
    )
    .unwrap();
    let demo = linux
        .unix()
        .users()
        .authenticate("demo", "demo", linux.unix().groups())
        .unwrap();
    let root = demo
        .elevate(os::unix::user::UserId::ROOT, os::unix::group::GroupId::ROOT)
        .unwrap();

    // Shell as demo
    let mut shell = Bash::new(linux.unix(), demo.clone()).unwrap();
    let mut shell_root = Bash::new(linux.unix(), root.clone()).unwrap();
    let mut stdin = BytesInput::new(b"");
    let mut stdout = BytesOutput::new();
    let mut stderr = BytesOutput::new();

    // which ls -> /usr/bin/ls (merged-/usr: the first PATH hit)
    shell.execute("which ls", &mut stdin, &mut stdout, &mut stderr);
    assert_eq!(stdout.bytes(), b"/usr/bin/ls\n");
    stdout = BytesOutput::new();

    // ls executes real implementation
    shell.execute("ls /", &mut stdin, &mut stdout, &mut stderr);
    let output = String::from_utf8(stdout.into_bytes()).unwrap();
    assert!(output.contains("bin"));
    assert!(output.contains("etc"));
    let mut stdout = BytesOutput::new();

    // rm /bin/ls then lookup fails (as root)
    shell_root.execute("rm /bin/ls", &mut stdin, &mut stdout, &mut stderr);
    let mut which_out = BytesOutput::new();
    let status = shell.execute("which ls", &mut stdin, &mut which_out, &mut stderr);
    assert_eq!(status.code(), 1, "which should fail after rm");
    assert!(
        which_out.bytes().is_empty()
            || String::from_utf8_lossy(which_out.bytes()).contains("no ls")
    );

    // mv preserves behavior: move cat to home and execute via new path.
    // With merged-/usr, `which cat` reports /usr/bin/cat.
    let mut which_cat = BytesOutput::new();
    shell.execute("which cat", &mut stdin, &mut which_cat, &mut stderr);
    assert_eq!(which_cat.bytes(), b"/usr/bin/cat\n");
    // Move cat
    shell_root.execute(
        "mv /usr/bin/cat /home/demo/mycat",
        &mut stdin,
        &mut stdout,
        &mut stderr,
    );
    let mut which_after = BytesOutput::new();
    let status = shell.execute("which cat", &mut stdin, &mut which_after, &mut stderr);
    assert_eq!(
        status.code(),
        1,
        "cat should not be found via PATH after mv"
    );
    // But new path should be executable
    let mut cat_out = BytesOutput::new();
    shell.execute(
        "/home/demo/mycat /etc/passwd",
        &mut stdin,
        &mut cat_out,
        &mut stderr,
    );
    let cat_output = String::from_utf8(cat_out.into_bytes()).unwrap();
    assert!(
        cat_output.contains("root:"),
        "mycat should read /etc/passwd"
    );

    // Restore cat for further tests via cp
    shell_root.execute(
        "cp /home/demo/mycat /bin/cat",
        &mut stdin,
        &mut stdout,
        &mut stderr,
    );

    // Restore ls via apt (package manager)
    // ls was deleted, now install curl to test package manager, and also reinstall ls via cp from cat (simulate)
    shell_root.execute("apt install curl", &mut stdin, &mut stdout, &mut stderr);
    let mut which_curl = BytesOutput::new();
    shell.execute("which curl", &mut stdin, &mut which_curl, &mut stderr);
    assert_eq!(which_curl.bytes(), b"/usr/bin/curl\n");
    let mut curl_out = BytesOutput::new();
    shell.execute("curl", &mut stdin, &mut curl_out, &mut stderr);
    assert!(
        String::from_utf8(curl_out.into_bytes())
            .unwrap()
            .contains("curl")
    );

    // Reinstall ls via cp for later tests
    shell_root.execute("cp /bin/cat /bin/ls", &mut stdin, &mut stdout, &mut stderr);
    // Reinstall ls via cp for later tests
    shell_root.execute("cp /bin/cat /bin/ls", &mut stdin, &mut stdout, &mut stderr);
    let mut which_ls2 = BytesOutput::new();
    shell.execute("which ls", &mut stdin, &mut which_ls2, &mut stderr);
    assert_eq!(which_ls2.bytes(), b"/usr/bin/ls\n");

    // man ls should use alternate screen without destroying scrollback
    let mut terminal = TerminalModel::new(Size::new(24, 80));
    terminal.write(b"previous shell line\n");
    let scrollback_before = terminal.scrollback().count();
    // Push q to exit man
    terminal.push_keys(&[terminal::KeyEvent::character('q')]);
    let mut man_stdin = BytesInput::new(b"");
    let mut man_stdout = BytesOutput::new();
    let mut man_stderr = BytesOutput::new();
    // Execute man with terminal
    shell.execute_with_terminal(
        "man ls",
        &mut man_stdin,
        &mut man_stdout,
        &mut man_stderr,
        Some(&mut terminal),
    );
    // After man, main screen should be restored and scrollback preserved
    assert!(
        !terminal.in_alternate_screen(),
        "man should leave alternate screen"
    );
    let visible = terminal.visible_screen().to_text();
    assert!(
        visible.contains("previous shell line")
            || terminal.scrollback().count() >= scrollback_before
    );

    // nano file.txt should allow key-by-key interaction and cause file mutations
    let mut nano_terminal = TerminalModel::new(Size::new(24, 80));
    nano_terminal.push_keys(&[
        terminal::KeyEvent::character('h'),
        terminal::KeyEvent::character('i'),
        terminal::KeyEvent::ctrl('x'),
        // A modified buffer asks before exiting: answer Y to write.
        terminal::KeyEvent::character('y'),
    ]);
    let mut nano_stdin = BytesInput::new(b"");
    let mut nano_stdout = BytesOutput::new();
    let mut nano_stderr = BytesOutput::new();
    let nano_status = shell.execute_with_terminal(
        "nano /tmp/nano_test.txt",
        &mut nano_stdin,
        &mut nano_stdout,
        &mut nano_stderr,
        Some(&mut nano_terminal),
    );
    let _ = nano_status;
    let mut cat_nano = BytesOutput::new();
    let mut cat_stderr = BytesOutput::new();
    shell.execute(
        "cat /tmp/nano_test.txt",
        &mut stdin,
        &mut cat_nano,
        &mut cat_stderr,
    );

    // nano 2.x always ends the written file with a newline.
    assert_eq!(cat_nano.bytes(), b"hi\n");

    // File mutation generates synchronous events
    let engine = linux.unix().engine();
    let events = std::sync::Arc::new(std::sync::Mutex::new(Vec::new()));
    let events_clone = events.clone();
    let sub = engine.subscribe(engine::EventType::ObjectWritten, move |event| {
        events_clone.lock().unwrap().push(event.object);
    });
    let file = engine
        .lookup(Some(demo.actor()), &"/tmp/nano_test.txt".parse().unwrap())
        .unwrap();
    engine
        .write(Some(demo.actor()), file, b"new content".to_vec())
        .unwrap();
    assert!(
        !events.lock().unwrap().is_empty(),
        "write should generate event"
    );
    engine.unsubscribe(sub);

    // Scripts should execute through same shell/runtime
    // Create a script file with a redirect (quotes protect the inner `>`).
    shell.execute(
        "echo 'echo hello > /tmp/script_out.txt' > /tmp/script.sh",
        &mut stdin,
        &mut stdout,
        &mut stderr,
    );
    // Execute script via the interpreter (`sh`), same runtime as interactive
    let mut script_stdin = BytesInput::new(b"");
    let mut script_stdout = BytesOutput::new();
    let mut script_stderr = BytesOutput::new();
    let status = shell.execute(
        "sh /tmp/script.sh",
        &mut script_stdin,
        &mut script_stdout,
        &mut script_stderr,
    );
    assert_eq!(status.code(), 0, "script executes through sh");
    let mut script_out = BytesOutput::new();
    shell.execute(
        "cat /tmp/script_out.txt",
        &mut stdin,
        &mut script_out,
        &mut stderr,
    );
    assert_eq!(script_out.bytes(), b"hello\n");
}

#[test]
fn homebrew_cask_state_flows_from_catalog_to_process_and_back() {
    let macos = MacOS::with_identity(
        &HostIdentity::new("demo", "demo-host"),
        Timestamp::from_nanos(1_772_323_200 * 1_000_000_000),
    )
    .unwrap();
    let unix = macos.unix();
    let demo = unix
        .users()
        .authenticate("demo", "demo", unix.groups())
        .unwrap();
    let mut shell = Zsh::new(unix, demo.clone()).unwrap();
    let mut stdin = BytesInput::new(b"");
    let mut stderr = BytesOutput::new();

    let mut search = BytesOutput::new();
    assert!(
        shell
            .execute(
                "brew search --cask firefox",
                &mut stdin,
                &mut search,
                &mut stderr,
            )
            .is_success()
    );
    assert!(String::from_utf8_lossy(search.bytes()).contains("firefox"));
    assert!(
        unix.engine()
            .lookup(Some(demo.actor()), &"/homebrew-catalog".parse().unwrap(),)
            .is_err(),
        "the upstream catalog is detached from the machine filesystem"
    );
    assert!(
        unix.engine()
            .lookup(
                Some(demo.actor()),
                &"/Applications/Firefox.app".parse().unwrap(),
            )
            .is_err(),
        "catalog availability is not installation"
    );

    let mut formula_install = BytesOutput::new();
    assert!(
        shell
            .execute(
                "brew install --formula curl",
                &mut stdin,
                &mut formula_install,
                &mut stderr,
            )
            .is_success()
    );
    let curl_link = unix
        .engine()
        .lookup_no_follow(
            Some(demo.actor()),
            &"/opt/homebrew/bin/curl".parse().unwrap(),
        )
        .unwrap();
    assert_eq!(
        unix.engine()
            .read_link(Some(demo.actor()), curl_link)
            .unwrap(),
        Some("../Cellar/curl/8.14.1/bin/curl".to_owned())
    );
    let mut formula_list = BytesOutput::new();
    shell.execute(
        "brew list --formula",
        &mut stdin,
        &mut formula_list,
        &mut stderr,
    );
    assert_eq!(formula_list.bytes(), b"curl\n");
    let curl_cellar = unix
        .engine()
        .lookup(
            Some(demo.actor()),
            &"/opt/homebrew/Cellar/curl".parse().unwrap(),
        )
        .unwrap();
    unix.engine()
        .delete(Some(demo.actor()), curl_cellar)
        .unwrap();
    let mut after_manual_removal = BytesOutput::new();
    shell.execute(
        "brew list --formula",
        &mut stdin,
        &mut after_manual_removal,
        &mut stderr,
    );
    assert!(
        after_manual_removal.bytes().is_empty(),
        "Cellar state, not an internal marker, decides what is installed"
    );

    let mut install = BytesOutput::new();
    assert!(
        shell
            .execute(
                "brew install --cask firefox",
                &mut stdin,
                &mut install,
                &mut stderr,
            )
            .is_success()
    );
    for path in [
        "/opt/homebrew/Caskroom/firefox/142.0.1/.metadata/INSTALL_RECEIPT.json",
        "/opt/homebrew/Caskroom/firefox/142.0.1/firefox.wrapper.sh",
        "/Applications/Firefox.app/Contents/MacOS/Firefox",
    ] {
        unix.engine()
            .lookup(Some(demo.actor()), &path.parse().unwrap())
            .unwrap_or_else(|_| panic!("Homebrew materialized {path}"));
    }
    let link = unix
        .engine()
        .lookup_no_follow(
            Some(demo.actor()),
            &"/opt/homebrew/bin/firefox".parse().unwrap(),
        )
        .unwrap();
    assert_eq!(
        unix.engine().read_link(Some(demo.actor()), link).unwrap(),
        Some("../Caskroom/firefox/142.0.1/firefox.wrapper.sh".to_owned())
    );

    let mut listing = BytesOutput::new();
    shell.execute("brew list --cask", &mut stdin, &mut listing, &mut stderr);
    assert_eq!(listing.bytes(), b"firefox\n");

    let mut opened = BytesOutput::new();
    assert!(
        shell
            .execute("open -a Firefox", &mut stdin, &mut opened, &mut stderr,)
            .is_success()
    );
    assert!(
        opened.bytes().is_empty(),
        "open has no fabricated GUI output"
    );
    let mut ps = BytesOutput::new();
    shell.execute("ps aux", &mut stdin, &mut ps, &mut stderr);
    let ps = String::from_utf8(ps.into_bytes()).unwrap();
    let firefox_line = ps.lines().find(|line| line.contains("Firefox")).unwrap();
    let pid = firefox_line.split_whitespace().next().unwrap();

    let mut killed = BytesOutput::new();
    assert!(
        shell
            .execute(&format!("kill {pid}"), &mut stdin, &mut killed, &mut stderr,)
            .is_success()
    );
    let mut after_kill = BytesOutput::new();
    shell.execute("ps aux", &mut stdin, &mut after_kill, &mut stderr);
    assert!(!String::from_utf8_lossy(after_kill.bytes()).contains("Firefox"));

    let mut uninstall = BytesOutput::new();
    assert!(
        shell
            .execute(
                "brew uninstall --cask firefox",
                &mut stdin,
                &mut uninstall,
                &mut stderr,
            )
            .is_success()
    );
    for path in [
        "/opt/homebrew/Caskroom/firefox",
        "/opt/homebrew/bin/firefox",
        "/Applications/Firefox.app",
    ] {
        assert!(
            unix.engine()
                .lookup_no_follow(Some(demo.actor()), &path.parse().unwrap())
                .is_err(),
            "uninstall removed {path}"
        );
    }
}