@tishlang/tish-format 2.43.8 → 3.1.0

package/crates/tish_core/src/value.rs

@@ -165,6 +165,35 @@ pub trait TishOpaque {
     fn as_any(&self) -> &dyn core::any::Any;
 }
 
+/// A typed native struct (from an `interface` / typed object literal in native codegen) carried inside
+/// a [`Value::Struct`] WITHOUT serialising to a hashmap object. Each generated `TishStruct_*` implements
+/// it: a boxed function that returns/passes a typed struct keeps it by reference, property access
+/// dispatches here (a small `match` on the field name — no string hash, no allocation), and it
+/// materialises to a real `Value::Object` only when a boxed `Value::Struct` (a struct whose static
+/// type was erased) crosses into genuinely dynamic territory (`JSON.stringify`, display,
+/// `Object.keys`/`values`/`entries`, `for..in`, `in`, `Object.assign`, object-literal spread `{...s}`).
+/// This is the RUNTIME fallback: when the struct's static type IS known at a reflection site, GBA
+/// codegen lowers `Object.keys`/`values`/`entries`/`in`/`{...s}` to native field reads instead — the
+/// struct is never boxed and this materialisation never runs. No `Send + Sync` bound: the `Value::Struct` variant is
+/// `cfg(portable)` and `portable` excludes `send-values` (they are mutually exclusive), so the ref is
+/// single-threaded `Rc` — mirroring the single-threaded [`TishOpaque`].
+pub trait TishStruct {
+    /// Read a field as a boxed `Value` (`Null` if `key` is not a field). Backs `get_prop`.
+    fn tish_get(&self, key: &str) -> Value;
+    /// Write a field from a boxed `Value` (no-op if `key` is not a field). Backs `set_prop`.
+    fn tish_set(&mut self, key: &str, value: Value);
+    /// Materialise an ordered `Value::Object` copy (field-declaration order, JS insertion order). Used
+    /// for JSON / display / `Object`-interop, and as the non-portable `Value::from_struct` fallback so
+    /// off-GBA backends behave EXACTLY as the historical `object_from_pairs` boundary did.
+    fn tish_to_object(&self) -> Value;
+    /// `typeof` result — always "object".
+    fn tish_type_name(&self) -> &'static str {
+        "object"
+    }
+    /// Downcast hook — recover the concrete `TishStruct_*` (e.g. for a future typed fast path).
+    fn as_any(&self) -> &dyn core::any::Any;
+}
+
 /// Trait for Promise-like values that can be awaited (block until settled).
 /// Implemented by the runtime for native compile; interpreter uses its own Promise.
 pub trait TishPromise: Send + Sync {
@@ -467,8 +496,24 @@ pub enum Value {
     Promise(Arc<dyn TishPromise>),
     /// Opaque handle to a native Rust type (e.g. Polars DataFrame).
     Opaque(Arc<dyn TishOpaque>),
+    /// A typed native struct carried BY REFERENCE (portable / GBA native codegen). Lets a boxed
+    /// function return or pass a typed struct without serialising it to a hashmap `Object` —
+    /// property access dispatches through [`TishStruct`] (a small match, no hash lookup / alloc), and
+    /// it materialises to an `Object` only on JSON / display / `Object.keys`-family / `for..in` /
+    /// `in` / `Object.assign` / `{...s}` spread. Built via
+    /// [`Value::from_struct`]. Portable-only: the ref is a single-threaded `Rc<RefCell<dyn …>>` and
+    /// `portable` excludes `send-values`, so this never violates `Send` (which off-portable `Value`
+    /// may need). A fat pointer is 16 B, so the 24 B `Value` size guard still holds.
+    #[cfg(feature = "portable")]
+    Struct(StructRef),
 }
 
+/// Reference to a boxed typed struct: `Rc<RefCell<dyn TishStruct>>`. Portable-only (see [`TishStruct`]
+/// / [`Value::Struct`]). `RefCell` is OUTSIDE the trait object so `set_prop` can borrow it mutably; the
+/// `Rc<RefCell<Concrete>> → Rc<RefCell<dyn TishStruct>>` unsizing is a stable coercion (no nightly).
+#[cfg(feature = "portable")]
+pub type StructRef = alloc::rc::Rc<core::cell::RefCell<dyn TishStruct>>;
+
 // Size guard. `Value` is 24 bytes: `String` is thin (`ArcStr`, 8B), but `Function`/`Promise`/`Opaque`
 // are fat `Arc<dyn …>` (data+vtable, 16B) ⇒ 16B payload + discriminant = 24.
 //
@@ -513,6 +558,8 @@ pub enum ValueTag {
     RegExp,
     Promise,
     Opaque,
+    #[cfg(feature = "portable")]
+    Struct,
 }
 
 /// Borrowed view of a [`Value`]'s payload, mirroring the enum variants. Lets call sites
@@ -533,6 +580,8 @@ pub enum ValueRef<'a> {
     RegExp(&'a VmRef<TishRegExp>),
     Promise(&'a Arc<dyn TishPromise>),
     Opaque(&'a Arc<dyn TishOpaque>),
+    #[cfg(feature = "portable")]
+    Struct(&'a StructRef),
 }
 
 impl Value {
@@ -578,6 +627,8 @@ impl Value {
             Value::RegExp(r) => ValueRef::RegExp(r),
             Value::Promise(p) => ValueRef::Promise(p),
             Value::Opaque(o) => ValueRef::Opaque(o),
+            #[cfg(feature = "portable")]
+            Value::Struct(s) => ValueRef::Struct(s),
         }
     }
 
@@ -598,6 +649,8 @@ impl Value {
             Value::RegExp(_) => ValueTag::RegExp,
             Value::Promise(_) => ValueTag::Promise,
             Value::Opaque(_) => ValueTag::Opaque,
+            #[cfg(feature = "portable")]
+            Value::Struct(_) => ValueTag::Struct,
         }
     }
 
@@ -1256,6 +1309,8 @@ impl core::fmt::Debug for Value {
             ),
             Value::Promise(_) => write!(f, "Promise"),
             Value::Opaque(o) => write!(f, "{}(opaque)", o.type_name()),
+            #[cfg(feature = "portable")]
+            Value::Struct(s) => write!(f, "Struct({})", s.borrow().tish_type_name()),
         }
     }
 }
@@ -1466,6 +1521,9 @@ impl Value {
             Value::Function(_) => "[Function]".to_string(),
             Value::Promise(_) => "[object Promise]".to_string(),
             Value::Opaque(o) => format!("[object {}]", o.type_name()),
+            // Display a boxed struct like the object it is (materialise once, then reuse the Object path).
+            #[cfg(feature = "portable")]
+            Value::Struct(s) => s.borrow().tish_to_object().to_display_string_guarded(ancestors),
             #[cfg(feature = "regex")]
             Value::RegExp(re) => {
                 let re = re.borrow();
@@ -1517,6 +1575,8 @@ impl Value {
                 .collect::<Vec<_>>()
                 .join(","),
             Value::Object(_) => "[object Object]".to_string(),
+            #[cfg(feature = "portable")]
+            Value::Struct(_) => "[object Object]".to_string(),
             // ECMAScript ToString of a number (drops `-0`'s sign), distinct from the inspect form
             // that `to_display_string` would give for `-0`. (#247)
             Value::Number(n) => js_number_to_string(*n),
@@ -1561,6 +1621,10 @@ impl Value {
             (Value::Promise(a), Value::Promise(b)) => Arc::ptr_eq(a, b),
             (Value::Opaque(a), Value::Opaque(b)) => Arc::ptr_eq(a, b),
             (Value::Symbol(a), Value::Symbol(b)) => Arc::ptr_eq(a, b),
+            // Struct-Value identity is `Rc` pointer equality, exactly like `Object` — two distinct
+            // boxings compare unequal, but a struct aliased through one `Value` is `=== ` itself.
+            #[cfg(feature = "portable")]
+            (Value::Struct(a), Value::Struct(b)) => alloc::rc::Rc::ptr_eq(a, b),
             _ => false,
         }
     }
@@ -1613,6 +1677,63 @@ impl Value {
         }))
     }
 
+    /// Box a typed native struct (a generated `TishStruct_*`). On portable (GBA) it is kept BY
+    /// REFERENCE as a cheap [`Value::Struct`] — one `Rc` allocation, no per-field string keys / hashmap;
+    /// property access later dispatches through [`TishStruct`]. On every other backend it serialises to
+    /// an ordered `Value::Object` (via [`TishStruct::tish_to_object`]) — byte-identical to the historical
+    /// `object_from_pairs` boundary, so off-GBA behaviour is unchanged. Codegen's struct-to-`Value`
+    /// boxing emits a single `Value::from_struct(..)` call for all native targets.
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn from_struct<T: TishStruct + 'static>(v: T) -> Value {
+        Value::Struct(alloc::rc::Rc::new(core::cell::RefCell::new(v)))
+    }
+    /// See the portable variant above — off-GBA this is exactly the old `object_from_pairs` boundary.
+    #[cfg(not(feature = "portable"))]
+    #[inline]
+    pub fn from_struct<T: TishStruct>(v: T) -> Value {
+        v.tish_to_object()
+    }
+
+    /// Box a typed native struct BY SHARED REFERENCE — the boxing path codegen actually emits, so the
+    /// whole-struct clone is paid ONLY where it's genuinely needed. On portable (GBA) the struct must
+    /// be OWNED by the `Rc`, so it clones (identical to `from_struct((v).clone())`). Off-GBA it
+    /// serialises the borrow directly via [`TishStruct::tish_to_object`] with NO whole-struct clone —
+    /// byte-identical to the historical `object_from_pairs` boundary that read fields straight off the
+    /// place (#565: the old `from_struct((v).clone())` cloned the entire struct just to serialise it).
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn from_struct_ref<T: TishStruct + Clone + 'static>(v: &T) -> Value {
+        Value::Struct(alloc::rc::Rc::new(core::cell::RefCell::new(v.clone())))
+    }
+    /// See the portable variant — off-GBA this serialises the borrow with no whole-struct clone.
+    #[cfg(not(feature = "portable"))]
+    #[inline]
+    pub fn from_struct_ref<T: TishStruct>(v: &T) -> Value {
+        v.tish_to_object()
+    }
+
+    /// If this value is a by-reference boxed struct of concrete type `T` (a `Value::Struct`), return a
+    /// CLONE of it — the native fast path for `let x: T = <boxed struct return>`, so subsequent field
+    /// reads are plain Rust loads instead of `get_prop`. Portable only: off-GBA there is no `Value::Struct`
+    /// variant, so this is always `None` and codegen's `from_value_expr` falls back to the field-by-field
+    /// `get_prop` rebuild (which also handles a genuine `Value::Object`). Returns `None` for any non-struct
+    /// value or a struct of a different concrete type.
+    #[cfg(feature = "portable")]
+    #[inline]
+    pub fn downcast_struct<T: TishStruct + Clone + 'static>(&self) -> Option<T> {
+        match self {
+            Value::Struct(s) => s.borrow().as_any().downcast_ref::<T>().cloned(),
+            _ => None,
+        }
+    }
+    /// See the portable variant — off-GBA there is no struct variant, so always `None`.
+    #[cfg(not(feature = "portable"))]
+    #[inline]
+    pub fn downcast_struct<T: TishStruct + Clone + 'static>(&self) -> Option<T> {
+        None
+    }
+
     /// Create an empty array Value.
     pub fn empty_array() -> Self {
         Value::Array(VmRef::new(Vec::new()))
@@ -1700,6 +1821,8 @@ impl Value {
             Value::Promise(_) => "object",
             Value::Opaque(o) => o.type_name(),
             Value::Symbol(_) => "symbol",
+            #[cfg(feature = "portable")]
+            Value::Struct(_) => "object",
         }
     }
 

package/crates/tish_fmt/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "tishlang_fmt"
-version = "2.43.8"
+version = "3.1.0"
 edition = "2021"
 description = "Opinionated formatter for Tish source (parse → pretty-print)"
 license-file = { workspace = true }

package/crates/tish_native/src/build.rs

@@ -18,6 +18,10 @@ const RUNTIME_CARGO_FEATURES: &[&str] = &[
     "ws",
     "tty",
     "pty",
+    "net",
+    "encoding",
+    "crypto",
+    "zip",
 ];
 
 /// Map CLI/compile features to flags passed to `tishlang_runtime` in the temp crate's Cargo.toml.

package/crates/tish_runtime/Cargo.toml

@@ -56,6 +56,15 @@ http-hyper = [
 # `mkdtemp` needs a random suffix (predictable/timestamp names are a temp-dir security smell).
 fs = ["promise", "dep:rand"]
 process = []
+# Raw TCP sockets: DAP TCP transports, OAuth loopback listener, connect probes.
+net = []
+# Base64 encode/decode (tish:encoding) — bytes <-> string, for file-bytes-over-JSON (extension host
+# vscode.workspace.fs, broker_read_file_base64) and PKCE (URL-safe, no-pad).
+encoding = ["dep:base64"]
+# SHA-256 + secure random (tish:crypto) — PKCE code_challenge/verifier, checkpoint dir hashing.
+crypto = ["dep:sha2", "dep:rand"]
+# Zip extraction (tish:zip) — VSIX / archive extract with `..`-traversal guard + unix-mode preserved.
+zip = ["dep:zip"]
 # Interactive terminal I/O (issue #101): raw mode, key/resize events, size, alt screen.
 tty = ["dep:crossterm"]
 # Pseudoterminal hosting (issue #493): spawn a shell/program on a real PTY, read/write/resize/kill —
@@ -71,6 +80,7 @@ ws = [
     "tokio/net",
     "tokio/io-util",
     "dep:tokio-tungstenite",
+    "dep:rustls",
     "dep:futures-util",
     "dep:lazy_static",
     "send-values",
@@ -84,6 +94,9 @@ tishlang_builtins = { path = "../tish_builtins", version = ">=0.1" }
 tokio = { version = "1.50.0", features = ["rt-multi-thread", "macros", "time", "sync"], optional = true }
 reqwest = { version = "0.13.2", default-features = false, features = ["rustls", "json", "stream", "multipart"], optional = true }
 futures = { version = "0.3.32", optional = true }
+base64 = { version = "0.22", optional = true }
+sha2 = { version = "0.10", optional = true }
+zip = { version = "2", default-features = false, features = ["deflate"], optional = true }
 bytes = { version = "1", optional = true }
 tiny_http = { version = "0.12.0", optional = true }
 # fs feature only: random suffix for `mkdtemp`.
@@ -100,7 +113,13 @@ hyper = { version = "1", default-features = false, features = ["server", "http1"
 hyper-util = { version = "0.1", features = ["server", "tokio"], optional = true }
 http-body-util = { version = "0.1", optional = true }
 core_affinity = { version = "0.8", optional = true }
-tokio-tungstenite = { version = "0.29", optional = true }
+# rustls-tls-native-roots gives `wss://` support (system cert store, no OpenSSL — matches reqwest's
+# rustls backend). Without a TLS feature, connect_async can only do plain `ws://` and rejects wss.
+tokio-tungstenite = { version = "0.29", optional = true, features = ["rustls-tls-native-roots"] }
+# Direct rustls handle so ws.rs can install a process-default CryptoProvider: both aws-lc-rs and ring
+# are in the tree (reqwest + transitive), so rustls 0.23 can't auto-select one, and connect_async's
+# wss path needs the process default. aws_lc_rs matches reqwest's provider.
+rustls = { version = "0.23", default-features = false, features = ["aws_lc_rs"], optional = true }
 futures-util = { version = "0.3", optional = true }
 lazy_static = { version = "1", optional = true }
 

package/crates/tish_runtime/src/crypto.rs

@@ -0,0 +1,127 @@
+//! Cryptographic hashing + secure random for Tish (`tish:crypto`), behind the `crypto` feature.
+//!
+//!   import { sha256, sha256Hex, randomBytes } from 'tish:crypto'
+//!
+//!   - `sha256(bytesOrString) -> number[]`   (the 32-byte digest as a byte array)
+//!   - `sha256Hex(bytesOrString) -> string`  (64 lowercase hex chars)
+//!   - `randomBytes(n) -> number[]`          (n cryptographically-secure random bytes; n clamped to 1 MiB)
+//!
+//! Bytes are the `tish:fs` / `tish:encoding` representation (Numbers 0-255). A string argument is
+//! hashed as its UTF-8 bytes. For PKCE: `base64UrlEncode(sha256(verifier))` (see `tish:encoding`).
+
+use sha2::{Digest, Sha256};
+use tishlang_core::{Value, VmRef};
+
+/// Coerce arg 0 to bytes: a byte array (Numbers 0-255) or a string's UTF-8 bytes.
+fn arg_bytes(args: &[Value]) -> Option<Vec<u8>> {
+    match args.first() {
+        Some(Value::Array(a)) => Some(
+            a.borrow()
+                .iter()
+                .map(|v| if let Value::Number(n) = v { *n as u8 } else { 0 })
+                .collect(),
+        ),
+        Some(Value::String(s)) => Some(s.as_bytes().to_vec()),
+        _ => None,
+    }
+}
+
+fn bytes_to_value(bytes: &[u8]) -> Value {
+    Value::Array(VmRef::new(
+        bytes.iter().map(|b| Value::Number(*b as f64)).collect(),
+    ))
+}
+
+fn digest_of(args: &[Value]) -> Option<[u8; 32]> {
+    let b = arg_bytes(args)?;
+    let mut h = Sha256::new();
+    h.update(&b);
+    Some(h.finalize().into())
+}
+
+pub fn sha256(args: &[Value]) -> Value {
+    match digest_of(args) {
+        Some(d) => bytes_to_value(&d),
+        None => Value::Null,
+    }
+}
+
+pub fn sha256_hex(args: &[Value]) -> Value {
+    match digest_of(args) {
+        Some(d) => {
+            let mut s = String::with_capacity(64);
+            for byte in d.iter() {
+                s.push_str(&format!("{byte:02x}"));
+            }
+            Value::String(s.into())
+        }
+        None => Value::Null,
+    }
+}
+
+pub fn random_bytes(args: &[Value]) -> Value {
+    let n = match args.first() {
+        Some(Value::Number(x)) if x.is_finite() && *x >= 0.0 => (*x as usize).min(1_048_576),
+        _ => return Value::Null,
+    };
+    // rand::random draws from the thread CSPRNG (ChaCha, OS-seeded) — same source fs_ext uses.
+    let bytes: Vec<u8> = (0..n).map(|_| rand::random::<u8>()).collect();
+    bytes_to_value(&bytes)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn to_bytes(v: Value) -> Vec<u8> {
+        let Value::Array(a) = v else { panic!("not an array") };
+        let g = a.borrow();
+        let out: Vec<u8> = g
+            .iter()
+            .map(|x| if let Value::Number(n) = x { *n as u8 } else { 0 })
+            .collect();
+        out
+    }
+
+    #[test]
+    fn sha256_hex_known_vector() {
+        // The canonical NIST vector: SHA-256("abc").
+        let Value::String(s) = sha256_hex(&[Value::String("abc".into())]) else { panic!() };
+        assert_eq!(
+            s.to_string(),
+            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+        );
+    }
+
+    #[test]
+    fn sha256_returns_32_bytes_matching_hex() {
+        let bytes = to_bytes(sha256(&[Value::String("abc".into())]));
+        assert_eq!(bytes.len(), 32);
+        assert_eq!(bytes[0], 0xba);
+        assert_eq!(bytes[31], 0xad);
+    }
+
+    #[test]
+    fn sha256_accepts_byte_array() {
+        // "abc" as a byte array must hash identically to the string.
+        let arr = Value::Array(VmRef::new(vec![
+            Value::Number(97.0),
+            Value::Number(98.0),
+            Value::Number(99.0),
+        ]));
+        let Value::String(s) = sha256_hex(&[arr]) else { panic!() };
+        assert_eq!(
+            s.to_string(),
+            "ba7816bf8f01cfea414140de5dae2223b00361a396177a9cb410ff61f20015ad"
+        );
+    }
+
+    #[test]
+    fn random_bytes_length_and_variance() {
+        assert_eq!(to_bytes(random_bytes(&[Value::Number(0.0)])).len(), 0);
+        let a = to_bytes(random_bytes(&[Value::Number(32.0)]));
+        let b = to_bytes(random_bytes(&[Value::Number(32.0)]));
+        assert_eq!(a.len(), 32);
+        assert_ne!(a, b, "two 32-byte draws must (almost surely) differ");
+    }
+}

package/crates/tish_runtime/src/encoding.rs

@@ -0,0 +1,157 @@
+//! Base64 encoding for Tish (`tish:encoding`), behind the `encoding` feature.
+//!
+//!   import { base64Encode, base64Decode, base64UrlEncode, base64UrlDecode } from 'tish:encoding'
+//!
+//!   - `base64Encode(bytesOrString) -> string`       (standard alphabet, padded)
+//!   - `base64Decode(string) -> number[] | null`     (bytes 0-255; null on invalid input)
+//!   - `base64UrlEncode(bytesOrString) -> string`    (URL-safe alphabet, NO padding — PKCE etc.)
+//!   - `base64UrlDecode(string) -> number[] | null`
+//!
+//! Bytes are the same representation `tish:fs` uses: an array of Numbers 0-255 (`readFileBytes`
+//! returns this; `writeFile` accepts it). A string argument is encoded as its UTF-8 bytes, so
+//! `base64Encode("hi")` works without a byte round-trip.
+
+use base64::Engine;
+use tishlang_core::{Value, VmRef};
+
+/// Coerce arg 0 to bytes: a byte array (Numbers 0-255) or a string's UTF-8 bytes.
+fn arg_bytes(args: &[Value]) -> Option<Vec<u8>> {
+    match args.first() {
+        Some(Value::Array(a)) => Some(
+            a.borrow()
+                .iter()
+                .map(|v| if let Value::Number(n) = v { *n as u8 } else { 0 })
+                .collect(),
+        ),
+        Some(Value::String(s)) => Some(s.as_bytes().to_vec()),
+        _ => None,
+    }
+}
+
+fn bytes_to_value(bytes: Vec<u8>) -> Value {
+    Value::Array(VmRef::new(
+        bytes.into_iter().map(|b| Value::Number(b as f64)).collect(),
+    ))
+}
+
+pub fn base64_encode(args: &[Value]) -> Value {
+    match arg_bytes(args) {
+        Some(b) => Value::String(base64::engine::general_purpose::STANDARD.encode(&b).into()),
+        None => Value::Null,
+    }
+}
+
+pub fn base64_decode(args: &[Value]) -> Value {
+    let s = match args.first() {
+        Some(Value::String(s)) => s.to_string(),
+        _ => return Value::Null,
+    };
+    match base64::engine::general_purpose::STANDARD.decode(s.as_bytes()) {
+        Ok(b) => bytes_to_value(b),
+        Err(_) => Value::Null,
+    }
+}
+
+pub fn base64_url_encode(args: &[Value]) -> Value {
+    match arg_bytes(args) {
+        Some(b) => Value::String(
+            base64::engine::general_purpose::URL_SAFE_NO_PAD
+                .encode(&b)
+                .into(),
+        ),
+        None => Value::Null,
+    }
+}
+
+pub fn base64_url_decode(args: &[Value]) -> Value {
+    let s = match args.first() {
+        Some(Value::String(s)) => s.to_string(),
+        _ => return Value::Null,
+    };
+    match base64::engine::general_purpose::URL_SAFE_NO_PAD.decode(s.as_bytes()) {
+        Ok(b) => bytes_to_value(b),
+        Err(_) => Value::Null,
+    }
+}
+
+/// `utf8Decode(byteArray) -> string` — decode bytes as UTF-8 (lossy: invalid sequences become the
+/// replacement char). The counterpart to `readFileBytes` / a streaming `reader.read()` chunk, whose
+/// `value` is a byte array. Split streamed bytes on a newline BEFORE decoding a line so a multi-byte
+/// sequence is never cut mid-decode (a `\n`=0x0A byte never occurs inside a UTF-8 multi-byte char).
+pub fn utf8_decode(args: &[Value]) -> Value {
+    match arg_bytes(args) {
+        Some(b) => Value::String(String::from_utf8_lossy(&b).into_owned().into()),
+        None => Value::Null,
+    }
+}
+
+/// `utf8Encode(string) -> number[]` — the string's UTF-8 bytes as a byte array. (A byte-array
+/// argument is passed through, so `utf8Encode(utf8Decode(x))` is a no-op round trip.)
+pub fn utf8_encode(args: &[Value]) -> Value {
+    match arg_bytes(args) {
+        Some(b) => bytes_to_value(b),
+        None => Value::Null,
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn to_bytes(v: Value) -> Vec<u8> {
+        let Value::Array(a) = v else { panic!("not an array") };
+        let g = a.borrow();
+        let out: Vec<u8> = g
+            .iter()
+            .map(|x| if let Value::Number(n) = x { *n as u8 } else { 0 })
+            .collect();
+        out
+    }
+
+    #[test]
+    fn encode_string_matches_known_vector() {
+        let enc = base64_encode(&[Value::String("hello world".into())]);
+        let Value::String(s) = &enc else { panic!() };
+        assert_eq!(s.to_string(), "aGVsbG8gd29ybGQ=");
+    }
+
+    #[test]
+    fn roundtrip_all_byte_values() {
+        let arr = Value::Array(VmRef::new(
+            (0u8..=255).map(|b| Value::Number(b as f64)).collect(),
+        ));
+        let enc = base64_encode(&[arr]);
+        assert_eq!(to_bytes(base64_decode(&[enc])), (0u8..=255).collect::<Vec<u8>>());
+    }
+
+    #[test]
+    fn url_safe_has_no_pad_plus_or_slash() {
+        // 0xFB,0xFF,0xBF encodes to +/ in standard; url-safe must use -_ and drop padding.
+        let arr = Value::Array(VmRef::new(vec![
+            Value::Number(251.0),
+            Value::Number(255.0),
+            Value::Number(191.0),
+        ]));
+        let Value::String(sv) = base64_url_encode(&[arr]) else { panic!() };
+        let s = sv.to_string();
+        assert!(!s.contains('=') && !s.contains('+') && !s.contains('/'), "got {s}");
+        // and it round-trips
+        assert_eq!(to_bytes(base64_url_decode(&[Value::String(sv)])), vec![251u8, 255, 191]);
+    }
+
+    #[test]
+    fn decode_invalid_is_null() {
+        assert!(matches!(
+            base64_decode(&[Value::String("!!! not base64 !!!".into())]),
+            Value::Null
+        ));
+    }
+
+    #[test]
+    fn utf8_roundtrip_multibyte() {
+        // "héllo 🚀" exercises 2-byte (é) and 4-byte (🚀) sequences.
+        let bytes = utf8_encode(&[Value::String("héllo 🚀".into())]);
+        let Value::String(s) = utf8_decode(&[bytes]) else { panic!() };
+        assert_eq!(s.to_string(), "héllo 🚀");
+    }
+}

package/crates/tish_runtime/src/fs_ext.rs

@@ -230,6 +230,32 @@ pub fn truncate_core(args: &[Value]) -> Result<Value, Value> {
         .map_err(io_err)
 }
 
+/// `chmod(path, mode)` — set the file mode (a number, e.g. `0o600` = 384). Unix only; a no-op that
+/// succeeds on other platforms. Needed to write a secrets file 0600.
+pub fn chmod_core(args: &[Value]) -> Result<Value, Value> {
+    let mode = match args.get(1) {
+        Some(Value::Number(n)) if n.is_finite() && *n >= 0.0 => *n as u32,
+        _ => {
+            return Err(io_err(std::io::Error::new(
+                std::io::ErrorKind::InvalidInput,
+                "chmod: mode must be a number",
+            )))
+        }
+    };
+    #[cfg(unix)]
+    {
+        use std::os::unix::fs::PermissionsExt;
+        std::fs::set_permissions(path_arg(args, 0), std::fs::Permissions::from_mode(mode))
+            .map(|_| Value::Null)
+            .map_err(io_err)
+    }
+    #[cfg(not(unix))]
+    {
+        let _ = mode;
+        Ok(Value::Null)
+    }
+}
+
 /// `mkdtemp(prefix)` — create a uniquely-named temp dir and return its path. Node appends 6 RANDOM
 /// characters; a timestamp suffix is both predictable (a temp-dir security smell) and collision-prone
 /// under rapid calls. Use a random suffix and rely on `create_dir`'s exclusive semantics, retrying on
@@ -319,6 +345,7 @@ fs_method!(copy_file, copy_file_promise, copy_file_core);
 fs_method!(realpath, realpath_promise, realpath_core);
 fs_method!(readlink, readlink_promise, readlink_core);
 fs_method!(truncate, truncate_promise, truncate_core);
+fs_method!(chmod, chmod_promise, chmod_core);
 fs_method!(mkdtemp, mkdtemp_promise, mkdtemp_core);
 fs_method!(cp, cp_promise, cp_core);
 

package/crates/tish_runtime/src/lib.rs

@@ -16,6 +16,7 @@ pub use tishlang_core::ObjectMap;
 // pass) instead of materializing an intermediate `AHashMap` and rebuilding from it.
 pub use tishlang_core::{ObjectData, PropMap};
 pub use tishlang_core::Value;
+pub use tishlang_core::TishStruct;
 pub use tishlang_core::NumArrayBacking;
 pub use tishlang_core::ArcStr;
 /// Used by native codegen for `f()` / `obj()` dispatch (`Value::Function` or `__call` on objects).
@@ -1777,6 +1778,38 @@ pub mod pty;
 #[cfg(feature = "pty")]
 pub use pty::{pty_kill, pty_pid, pty_read, pty_resize, pty_spawn, pty_write};
 
+#[cfg(feature = "process")]
+pub mod process_spawn;
+#[cfg(feature = "process")]
+pub use process_spawn::{
+    process_close_stdin, process_kill, process_pid, process_read_stderr, process_read_stdout,
+    process_spawn, process_wait, process_write_stdin,
+};
+
+#[cfg(feature = "net")]
+pub mod net;
+#[cfg(feature = "net")]
+pub use net::{
+    net_accept, net_close, net_connect, net_listen, net_probe, net_read, net_sleep, net_write,
+};
+
+#[cfg(feature = "encoding")]
+pub mod encoding;
+#[cfg(feature = "encoding")]
+pub use encoding::{
+    base64_decode, base64_encode, base64_url_decode, base64_url_encode, utf8_decode, utf8_encode,
+};
+
+#[cfg(feature = "crypto")]
+pub mod crypto;
+#[cfg(feature = "crypto")]
+pub use crypto::{random_bytes, sha256, sha256_hex};
+
+#[cfg(feature = "zip")]
+pub mod zip;
+#[cfg(feature = "zip")]
+pub use zip::{zip_entries, zip_extract};
+
 #[cfg(feature = "ws")]
 pub use ws::{
     web_socket_client, web_socket_server_accept, web_socket_server_construct,