Package manager: omc --install + omc.toml + omc_modules/

OMC has a working package manager. The pieces:

* `omc.toml` at project root — declares dependencies as URLs:

      [dependencies]
      np = "https://example.com/raw/np.omc"
      pd = "https://example.com/raw/pd.omc"

* `omc --install` — reads the manifest, fetches every URL, writes
  to `omc_modules/<name>.omc`. Installation is idempotent (re-run
  to update).

* `omc --install <URL>` — single-shot install of a specific URL.
  Module name derived from the URL basename (sans `.omc`).

* `omc --list` — enumerates installed modules.

* `import "np";` resolution — interpreter.rs now puts `omc_modules/`
  FIRST in the search path, before OMC_STDLIB_PATH and the legacy
  Python OMC stdlib paths. Mirrors npm's node_modules / pip's
  site-packages convention.

Implementation:

* HTTP fetch via embedded Python `requests` (no new Rust dep).
* TOML parse via embedded Python `tomllib` (Python 3.11+ stdlib).
* Both use the always-on pyo3 layer landed in the previous commit.

This is "eat our own dogfood" — OMC's package manager is itself
proof that the integration story works. Zero new Rust crates.

New OMC builtin: `py_fetch_text(url)` — convenience GET via
embedded requests, returns body string. Useful for any OMC
program that needs to pull content from the web.

Verified end-to-end:
  - Spun up a local http.server pointing at examples/lib/
  - omc.toml with three dependencies
  - `omc --install` fetched all three to omc_modules/
  - `omc --list` enumerated them
  - `import "np";` resolved from omc_modules/
  - `np.pi`, `np.mean`, sk.load_iris all worked

Help text updated. 43/43 functional examples produce identical
output under tree-walk and VM. 92/92 unit tests pass.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: RandomCoder-lab

omnimcode-core/src/interpreter.rs

@@ -173,6 +173,11 @@ impl Interpreter {
     /// small built-in list that includes the canonical Python OMC stdlib.
     fn module_search_path() -> Vec<std::path::PathBuf> {
         let mut paths = Vec::new();
+        // Project-local package cache. Populated by `omc --install`
+        // and checked first so `import "np";` resolves the local
+        // copy before falling back to user paths or the legacy stdlib.
+        // Mirrors npm's node_modules / pip's site-packages convention.
+        paths.push(std::path::PathBuf::from("omc_modules"));
         if let Ok(env) = std::env::var("OMC_STDLIB_PATH") {
             for p in env.split(':') {
                 if !p.is_empty() {

omnimcode-core/src/main.rs

@@ -11,14 +11,16 @@ use std::io::{self, Write};
 fn main() {
     let args: Vec<String> = env::args().collect();
 
-    // Parse simple flag-style args: --check, --fmt, --help / -h
-    // Anything else after the flag is the input file.
+    // Parse simple flag-style args. Anything else is the input file
+    // (or the install spec when --install is set).
     let mut mode = "run";
     let mut file_arg: Option<&str> = None;
     for a in args.iter().skip(1) {
         match a.as_str() {
             "--check" | "-c" => mode = "check",
             "--fmt" | "--format" | "-f" => mode = "fmt",
+            "--install" | "-i" => mode = "install",
+            "--list" | "-l" => mode = "list",
             "--help" | "-h" => mode = "help",
             other if !other.starts_with('-') => file_arg = Some(other),
             other => {
@@ -50,6 +52,8 @@ fn main() {
             eprintln!("--fmt requires a file argument.");
             2
         }
+        ("install", spec) => install_command(spec),
+        ("list", _) => list_command(),
         _ => unreachable!(),
     };
     if exit_code != 0 {
@@ -72,14 +76,151 @@ fn maybe_register_python(interp: &mut Interpreter) {
     omnimcode_core::python_embed::register_python_builtins(interp);
 }
 
+/// `--install [URL_OR_NAME]`. With no argument: read `omc.toml` in
+/// the current directory and install every entry in [dependencies].
+/// With a URL: fetch it and store the file under `omc_modules/`,
+/// using the basename (sans .omc) as the module name. With a name
+/// that doesn't look like a URL: error (no central registry yet —
+/// users provide explicit URLs in omc.toml).
+///
+/// Eats our own dogfood: uses the embedded Python `requests` for
+/// the HTTP fetch and `tomllib` for the manifest parse. Zero new
+/// Rust dependencies.
+fn install_command(spec: Option<&str>) -> i32 {
+    use omnimcode_core::python_embed::{install_url_via_python, parse_omc_toml_via_python};
+
+    if std::env::var("OMC_NO_PYTHON").as_deref() == Ok("1") {
+        eprintln!("--install requires Python (used for HTTP fetch + TOML parse).");
+        eprintln!("Unset OMC_NO_PYTHON or run with Python embedding enabled.");
+        return 2;
+    }
+
+    // Ensure omc_modules/ exists.
+    if let Err(e) = std::fs::create_dir_all("omc_modules") {
+        eprintln!("install: cannot create omc_modules/: {}", e);
+        return 1;
+    }
+
+    match spec {
+        Some(spec) => {
+            let url = if spec.starts_with("http://") || spec.starts_with("https://") {
+                spec.to_string()
+            } else {
+                eprintln!("install: argument must be a URL (no central registry yet).");
+                eprintln!("        For a manifest install, run `omc --install` with no arg");
+                eprintln!("        and create an omc.toml in this directory.");
+                return 2;
+            };
+            // Derive name from URL basename.
+            let name = url
+                .rsplit('/')
+                .next()
+                .unwrap_or("module")
+                .trim_end_matches(".omc");
+            match install_url_via_python(name, &url) {
+                Ok(path) => {
+                    println!("installed: {} -> {}", name, path);
+                    0
+                }
+                Err(e) => {
+                    eprintln!("install({}): {}", name, e);
+                    1
+                }
+            }
+        }
+        None => {
+            let manifest_path = "omc.toml";
+            let manifest_text = match std::fs::read_to_string(manifest_path) {
+                Ok(t) => t,
+                Err(e) => {
+                    eprintln!("install: cannot read {}: {}", manifest_path, e);
+                    eprintln!("        Create one with [dependencies] entries:");
+                    eprintln!("");
+                    eprintln!("            [dependencies]");
+                    eprintln!("            np = \"https://raw.githubusercontent.com/.../np.omc\"");
+                    return 1;
+                }
+            };
+            let deps = match parse_omc_toml_via_python(&manifest_text) {
+                Ok(d) => d,
+                Err(e) => {
+                    eprintln!("install: omc.toml parse: {}", e);
+                    return 1;
+                }
+            };
+            if deps.is_empty() {
+                println!("install: no [dependencies] in omc.toml — nothing to do.");
+                return 0;
+            }
+            let mut failures = 0;
+            for (name, url) in &deps {
+                match install_url_via_python(name, url) {
+                    Ok(path) => println!("installed: {} -> {}", name, path),
+                    Err(e) => {
+                        eprintln!("install({}): {}", name, e);
+                        failures += 1;
+                    }
+                }
+            }
+            if failures > 0 { 1 } else { 0 }
+        }
+    }
+}
+
+/// `--list`: enumerate everything in omc_modules/.
+fn list_command() -> i32 {
+    let dir = std::path::Path::new("omc_modules");
+    if !dir.exists() {
+        println!("(no omc_modules/ in this directory)");
+        return 0;
+    }
+    let entries = match std::fs::read_dir(dir) {
+        Ok(e) => e,
+        Err(e) => {
+            eprintln!("list: cannot read omc_modules/: {}", e);
+            return 1;
+        }
+    };
+    let mut names: Vec<String> = entries
+        .filter_map(|e| e.ok())
+        .filter_map(|e| {
+            let p = e.path();
+            if p.extension().and_then(|s| s.to_str()) == Some("omc") {
+                p.file_stem()
+                    .and_then(|s| s.to_str())
+                    .map(|s| s.to_string())
+            } else {
+                None
+            }
+        })
+        .collect();
+    names.sort();
+    if names.is_empty() {
+        println!("(no installed modules — use --install to add some)");
+    } else {
+        for n in names {
+            println!("  {}", n);
+        }
+    }
+    0
+}
+
 fn print_help() {
     let prog = env::args().next().unwrap_or_else(|| "omnimcode-standalone".to_string());
     println!("Usage:");
     println!("  {} [FILE]              run a program (or start REPL if no file)", prog);
     println!("  {} --check FILE        run heal pass, print diagnostics, exit", prog);
     println!("  {} --fmt FILE          pretty-print AST as canonical OMC source", prog);
+    println!("  {} --install [URL]     install package from URL into omc_modules/", prog);
+    println!("                         (no URL = read omc.toml [dependencies])", );
+    println!("  {} --list              list packages installed under omc_modules/", prog);
     println!("  {} --help              this message", prog);
     println!();
+    println!("omc.toml format (for --install with no arg):");
+    println!("  [dependencies]");
+    println!("  np = \"https://example.com/raw/np.omc\"");
+    println!("  pd = \"https://example.com/raw/pd.omc\"");
+    println!();
     println!("Environment variables:");
     println!("  OMC_VM=1               execute through the Rust bytecode VM");
     println!("  OMC_HEAL=1             auto-heal AST before execution (iterative)");
@@ -89,6 +230,7 @@ fn print_help() {
     println!("  OMC_OPT=0              disable optimizer (on by default)");
     println!("  OMC_OPT_STATS=1        print optimizer pass statistics");
     println!("  OMC_STDLIB_PATH=...    colon-separated module search path");
+    println!("  OMC_NO_PYTHON=1        skip embedded CPython initialisation");
 }
 
 fn read_and_run(path: &str) -> Result<(), String> {

omnimcode-core/src/python_embed.rs

@@ -424,6 +424,20 @@ pub fn register_python_builtins(interp: &mut Interpreter) {
         Ok(Value::Null)
     });
 
+    // ---- py_fetch_text(url) -> string -------------------------------
+    // Convenience: HTTP GET via embedded Python `requests`. Returns
+    // body as string on 2xx, errors on anything else. Used internally
+    // by `omc --install` so we don't need a separate Rust HTTP crate.
+    interp.register_builtin("py_fetch_text", |args| {
+        if args.is_empty() {
+            return Err("py_fetch_text requires (url)".to_string());
+        }
+        let url = args[0].to_display_string();
+        let body = fetch_url(&url)
+            .map_err(|e| format!("py_fetch_text({}): {}", url, e))?;
+        Ok(Value::String(body))
+    });
+
     // ---- py_callback("omc_fn_name") -> handle (Python callable) -------
     // Returns a Python callable that, when invoked from Python with
     // positional args, calls back into OMC's `omc_fn_name` with the
@@ -501,3 +515,99 @@ impl OmcCallback {
         format!("<OmcCallback '{}'>", self.fn_name)
     }
 }
+
+// ===========================================================================
+// Package manager helpers — used by `omc --install` from main.rs.
+//
+// We do the HTTP fetch and TOML parse via embedded Python (`requests`
+// + `tomllib`) rather than pulling in Rust HTTP/TOML crates. The
+// dependency model is already "Python is always on" — leaning on it
+// for tooling avoids dep bloat and proves the integration works for
+// our own infrastructure.
+// ===========================================================================
+
+/// HTTP GET via embedded Python's `requests`. Returns the response
+/// body on 2xx; Err on connection failure, non-2xx, or a missing
+/// `requests` install.
+pub fn fetch_url(url: &str) -> Result<String, String> {
+    Python::with_gil(|py| {
+        let requests = py
+            .import_bound("requests")
+            .map_err(|e| format!("requests not installed: {}", e))?;
+        let response = requests
+            .call_method1("get", (url,))
+            .map_err(|e| format!("GET failed: {}", e))?;
+        let status: u16 = response
+            .getattr("status_code")
+            .and_then(|s| s.extract())
+            .map_err(|e| format!("status_code: {}", e))?;
+        if !(200..300).contains(&status) {
+            return Err(format!("HTTP {}", status));
+        }
+        let body: String = response
+            .getattr("text")
+            .and_then(|t| t.extract())
+            .map_err(|e| format!("read body: {}", e))?;
+        Ok(body)
+    })
+}
+
+/// Fetch `url` and write to `omc_modules/<name>.omc`. Returns the
+/// final on-disk path on success.
+pub fn install_url_via_python(name: &str, url: &str) -> Result<String, String> {
+    let body = fetch_url(url)?;
+    let path = format!("omc_modules/{}.omc", name);
+    std::fs::write(&path, body).map_err(|e| format!("write {}: {}", path, e))?;
+    Ok(path)
+}
+
+/// Parse `omc.toml`'s `[dependencies]` table via Python's `tomllib`
+/// (stdlib in 3.11+). Returns a list of (name, url) pairs preserving
+/// source order.
+pub fn parse_omc_toml_via_python(text: &str) -> Result<Vec<(String, String)>, String> {
+    Python::with_gil(|py| {
+        let tomllib = py
+            .import_bound("tomllib")
+            .map_err(|e| format!("tomllib not available (need Python 3.11+): {}", e))?;
+        // tomllib.loads(text) — needs bytes in some versions, str in others.
+        // Use loads with str, fall back to bytes.
+        let parsed = match tomllib.call_method1("loads", (text,)) {
+            Ok(v) => v,
+            Err(_) => tomllib
+                .call_method1("loads", (text.as_bytes(),))
+                .map_err(|e| format!("tomllib.loads: {}", e))?,
+        };
+        let dict = parsed
+            .downcast::<PyDict>()
+            .map_err(|e| format!("toml root must be a table: {}", e))?;
+        let deps_obj = match dict.get_item("dependencies") {
+            Ok(Some(o)) => o,
+            _ => return Ok(Vec::new()),
+        };
+        let deps = deps_obj
+            .downcast::<PyDict>()
+            .map_err(|e| format!("[dependencies] must be a table: {}", e))?;
+        let mut out: Vec<(String, String)> = Vec::with_capacity(deps.len());
+        for (k, v) in deps.iter() {
+            let name: String = k.extract().map_err(|e| format!("dep name: {}", e))?;
+            // Accept either a string URL or a table with `url = "..."`.
+            let url: String = if let Ok(s) = v.extract::<String>() {
+                s
+            } else if let Ok(t) = v.downcast::<PyDict>() {
+                match t.get_item("url") {
+                    Ok(Some(u)) => u
+                        .extract::<String>()
+                        .map_err(|e| format!("dep {} url: {}", name, e))?,
+                    _ => return Err(format!("dep {} table missing `url`", name)),
+                }
+            } else {
+                return Err(format!(
+                    "dep {} must be a string URL or table with `url`",
+                    name
+                ));
+            };
+            out.push((name, url));
+        }
+        Ok(out)
+    })
+}