std/src/os/effect.nv - main - nv-lang/nova

std/src/os/effect.nv
67 строк3 KB
Evgeniy Golovin
feat(os): process spawn/wait/exit-code via Command.run() (Plan 265 Ф.1, D453)
10 авг 2026, 18:15
10 авг 2026, 18:15c1eef30
// SPDX-License-Identifier: MIT OR Apache-2.0
// std/os/effect.nv — the Os plumbing effect.
//
// `Os` is a **plumbing effect** (net/io/fs precedent): user code never calls its
// operations directly — it goes through the free functions in os.nv (`args`,
// `get_env`, `set_env`, `vars`, `current_dir`, `exit`, `pid`, …), which dispatch
// to the ambient `Os` handler. Production installs `real_os()` (native
// getenv/getcwd/setenv/… hooks, nova_rt/os_env.h); tests install `mock_os(state)`
// — an in-memory env/args/cwd map — so the SAME code under test runs
// deterministically with no real process environment, no DI (mockability
// differentiator: Go needs os-var juggling, Zig has nothing).
//
// **Thin primitive layer.** Operations return raw `int`/`str` codes, NOT
// `Result`/`Option`/`Path`: an effect vtable erases a rich return to the canonical
// `nova_int`/`nova_str` pair, so all `IoError`/`Option`/`Path` construction happens
// in the pure-Nova os.nv wrappers OUTSIDE the effect boundary. The ops mirror the
// os_env.h hook shapes 1:1: string getters return raw bytes-as-`str` (empty ==
// unavailable), mutators return 0 or a NEGATIVE POSIX errno.
//
// **byte-first.** Env keys/values and paths cross as `[]u8`
// (the handler NUL-terminates them for the C boundary); string getters carry raw
// bytes verbatim — a non-UTF-8 Unix env value round-trips losslessly through
// `get_env_bytes`. `str`-typed convenience (`get_env`) carries the same bytes.

module std.os

/// Ambient OS environment access. Internal dispatch point — user code uses the
/// free functions in os.nv, not these operations directly.
///
///   - `arg_count`/`arg_at`   — program arguments (argv; `arg_at(0)` = program).
///   - `env_get`/`env_has`    — a variable's raw value bytes / its presence.
///   - `env_set`/`env_remove` — mutate the process environment (0 / -errno).
///   - `env_len`/`env_key_at`/`env_val_at` — snapshot iteration of all variables.
///   - `cwd`/`set_cwd`        — current working directory (empty == error; 0/-errno).
///   - `temp_dir`/`home_dir`  — well-known directories (home empty == none).
///   - `exit`/`pid`/`hostname`— process exit (flush + terminate), pid, host name.
#stable(since = "0.1")
export type Os effect {
    // Program arguments.
    arg_count() -> int
    arg_at(i int) -> str
    // Environment (keys/values are raw bytes; the handler NUL-terminates).
    env_get(key []u8) -> Option[str]
    env_has(key []u8) -> bool
    env_set(key []u8, val []u8) -> int
    env_remove(key []u8) -> int
    env_len() -> int
    env_key_at(i int) -> str
    env_val_at(i int) -> str
    // Working directory.
    cwd() -> str
    set_cwd(path []u8) -> int
    // Well-known directories.
    temp_dir() -> str
    home_dir() -> str
    // Process.
    exit(code int) -> int
    pid() -> int
    hostname() -> str
    // Spawn a process, wait for it to exit, report (rc, exit_code) (Plan 265
    // Ф.1, D453). Byte-first (program/argv/env cross as NUL-joined blobs, not
    // []str — same convention as env keys/values above); rich Command/
    // ExitStatus are built in os.nv, OUTSIDE this boundary. See D453 for the
    // full (rc, exit_code) contract (0=ran; PROCESS_CANCELLED=scope
    // cancelled/timed out; <0=failed to spawn, -errno-compatible).
    process_run(program []u8, argv []u8, argc int, env []u8, envc int, use_env bool, cwd []u8) -> (int, int)
}