@supermachine/core 0.4.25

package/examples/02-pool.mjs

@@ -0,0 +1,54 @@
+// 02-pool.mjs — keep a warm pool, dispatch N concurrent commands.
+//
+// Demonstrates:
+//   - `min`/`max` pool sizing (eager pre-spawn + auto-grow)
+//   - Concurrent acquire(): pool serializes correctly under load
+//   - `pool.stats()` for observability / autoscaling decisions
+//
+// Run:
+//   node examples/02-pool.mjs
+
+import { Image } from "@supermachine/core";
+
+const img = await Image.build({
+  ref: "alpine:latest",
+  name: "pool-demo",
+});
+
+// Pre-spawn 4 VMs; grow up to 8 under load.
+const pool = await img.pool({
+  min: 4,
+  max: 8,
+  // Per-cycle clean state on release. Trade ~3 ms cycle-restore
+  // for guaranteed fresh /tmp etc. across acquires.
+  restoreOnRelease: true,
+});
+
+console.log("pool stats (idle):", pool.stats());
+// → { alive: 4, inUse: 0, idle: 4, waiting: 0, min: 4, max: 8 }
+
+// Launch 16 concurrent commands; pool will serve from 4 idle
+// slots, grow to 8, then queue the remaining 8 fairly.
+const work = Array.from({ length: 16 }, async (_, i) => {
+  const vm = await pool.acquire();
+  try {
+    const { stdout } = await vm.exec({
+      argv: ["sh", "-c", `echo "task ${i} on $(hostname)"`],
+      timeoutMs: 5_000,
+    });
+    return stdout.toString().trim();
+  } finally {
+    await vm.release();
+  }
+});
+
+// Snapshot stats mid-flight so the user can see the queue depth.
+setTimeout(() => {
+  console.log("pool stats (mid-flight):", pool.stats());
+}, 50);
+
+const outputs = await Promise.all(work);
+console.log("\nall results:");
+for (const line of outputs) console.log("  ", line);
+
+console.log("\npool stats (drained):", pool.stats());

package/examples/03-snapshot-then-restore.mjs

@@ -0,0 +1,54 @@
+// 03-snapshot-then-restore.mjs — capture mid-flight VM state,
+// reload it later for instant warm starts.
+//
+// The story: you have a slow setup phase (compile a seed program,
+// warm a page cache, fetch a model). Do it ONCE, snapshot, then
+// restore the post-warmup state on every subsequent run in <50 ms.
+//
+// Run:
+//   node examples/03-snapshot-then-restore.mjs
+
+import { Image } from "@supermachine/core";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const img = await Image.build({
+  ref: "alpine:latest",
+  name: "snapshot-demo",
+});
+
+// Phase 1: do expensive setup in a regular VM.
+const pool = await img.pool({ min: 1, max: 1 });
+const vm = await pool.acquire();
+
+// Simulate setup: drop a "computed" file into the guest. In a real
+// workload this might be `apk add gcc && rustc -O example.rs`.
+await vm.writeFile(
+  "/etc/seed.txt",
+  Buffer.from("expensive setup result: 0xCAFEBABE\n"),
+);
+console.log("phase 1: setup complete, file written to guest");
+
+// Capture the post-setup state. Returns a new Image pointing at
+// a freshly-written restore.snap.
+const captureDir = mkdtempSync(join(tmpdir(), "sm-snap-"));
+const captured = await vm.snapshot(captureDir);
+console.log(`phase 2: snapshot captured (${captured.memoryMib} MiB)`);
+console.log(`   path: ${captured.snapshotPath}`);
+
+await vm.release();
+
+// Phase 3: a brand-new VM from the captured state has the file
+// already there — no need to rerun setup.
+const restored = await Image.fromSnapshot(captured.snapshotPath);
+const pool2 = await restored.pool({ min: 1, max: 1 });
+const vm2 = await pool2.acquire();
+
+const seed = await vm2.readFile("/etc/seed.txt");
+console.log("phase 3: restored VM reads back seed →", seed.toString().trim());
+
+await vm2.release();
+
+// Tidy up the captured snapshot.
+rmSync(captureDir, { recursive: true, force: true });

package/examples/04-expose-tcp.mjs

@@ -0,0 +1,80 @@
+// 04-expose-tcp.mjs — bake a service image, expose it as a local
+// TCP port, connect from the host.
+//
+// Demonstrates the `TcpForwarder` API surface:
+//   - `vm.exposeTcp(hostPort, guestPort)` — TCP→vsock proxy
+//   - `TcpForwarder.localAddr` getter
+//   - `TcpForwarder.stop()` (idempotent; in-flight connections survive)
+//
+// The example bakes an alpine "echo server": `nc -l -p 8080` in a
+// loop. We then connect from the host and verify the forwarder
+// landed at a listening port. Getting bidirectional data through
+// busybox `nc` is finicky across alpine releases — for a real
+// service workload (nginx, redis, your own app), the
+// TcpForwarder API stays identical and the data path works
+// without any of the BusyBox-nc gymnastics here.
+//
+// Run:
+//   node examples/04-expose-tcp.mjs
+
+import { Image } from "@supermachine/core";
+import { createConnection } from "node:net";
+
+const img = await Image.build({
+  ref: "alpine:latest",
+  name: "expose-tcp-demo",
+  cmd: ["sh", "-c", "while true; do nc -l -p 8080; done"],
+  guestPort: 8080,
+  // Wait for the listener to bind before capturing.
+  listenerRequired: true,
+});
+
+const pool = await img.pool({ min: 1, max: 1 });
+const vm = await pool.acquire();
+
+// hostPort: 0 → OS picks a free port. Read it back via .localAddr.
+// guestPort: 8080 is plumbed through but currently advisory; the
+// Rust crate's expose_tcp routes into whatever the in-guest TSI
+// mux accepts. Per-guest-port routing is on the roadmap; for
+// now, a single guest workload bound to whatever port works.
+const fwd = await vm.exposeTcp(0, 8080);
+console.log(`forwarder bound on ${fwd.localAddr}`);
+
+const [host, port] = fwd.localAddr.split(":");
+
+// Verify the forwarder is accepting connections — a successful
+// TCP connect (vs ECONNREFUSED) confirms the host-side proxy
+// thread is up and the vsock relay accepted us.
+const connected = await new Promise((resolve) => {
+  const sock = createConnection({ host, port: Number(port) });
+  sock.once("connect", () => {
+    sock.destroy();
+    resolve(true);
+  });
+  sock.once("error", () => resolve(false));
+  sock.setTimeout(3_000, () => {
+    sock.destroy();
+    resolve(false);
+  });
+});
+console.log(`connect ok: ${connected}`);
+
+await fwd.stop();
+console.log("forwarder stopped");
+
+// After stop(), connect must be refused.
+const refused = await new Promise((resolve) => {
+  const sock = createConnection({ host, port: Number(port) });
+  sock.once("connect", () => {
+    sock.destroy();
+    resolve(false);
+  });
+  sock.once("error", () => resolve(true));
+  sock.setTimeout(500, () => {
+    sock.destroy();
+    resolve(true);
+  });
+});
+console.log(`post-stop refused: ${refused}`);
+
+await vm.release();

package/examples/05-spawn-streaming.mjs

@@ -0,0 +1,59 @@
+// 05-spawn-streaming.mjs — bidirectional stdin/stdout/stderr
+// streaming with vm.spawn().
+//
+// Unlike `vm.exec()` which collects all output into Buffers,
+// `vm.spawn()` returns an ExecChild handle for incremental I/O:
+//   - writeStdin / closeStdin
+//   - readStdout / readStderr (pull-style, returns when bytes
+//     are available or 0 on EOF)
+//   - signal(signum), resize(cols, rows)
+//   - wait() → exit status
+//
+// Useful for: LLM-style token streaming, interactive REPLs,
+// long-running daemons, anything where you don't want to wait
+// for the whole output before processing.
+//
+// Run:
+//   node examples/05-spawn-streaming.mjs
+
+import { Image } from "@supermachine/core";
+
+const img = await Image.build({
+  ref: "alpine:latest",
+  name: "spawn-stream-demo",
+});
+
+const pool = await img.pool({ min: 1, max: 1 });
+const vm = await pool.acquire();
+
+// Spawn a process that echoes back each line of stdin with a
+// prefix. The host writes lines incrementally and reads each
+// response as it arrives — no buffering on either side.
+const child = await vm.spawn({
+  argv: [
+    "sh",
+    "-c",
+    `while IFS= read -r line; do echo "[guest] $line"; done`,
+  ],
+});
+
+const inputs = ["hello", "world", "supermachine"];
+for (const line of inputs) {
+  await child.writeStdin(Buffer.from(`${line}\n`));
+  // Pull one line of output. readStdout returns at first data;
+  // we accumulate until we see a \n.
+  let acc = "";
+  while (!acc.includes("\n")) {
+    const chunk = await child.readStdout(1024);
+    if (chunk.length === 0) break;
+    acc += chunk.toString();
+  }
+  process.stdout.write(`host wrote "${line}" → ${acc}`);
+}
+
+// Close stdin so the shell's `read` returns 0 and the loop exits.
+await child.closeStdin();
+const result = await child.wait();
+console.log(`exit ${result.exitCode}, peak RSS ${result.peakRssKib ?? "?"} KiB`);
+
+await vm.release();

package/examples/README.md

@@ -0,0 +1,43 @@
+# `@supermachine/core` examples
+
+Runnable scripts demonstrating each integrator-facing surface.
+Every example is self-contained — `node examples/NN-name.mjs`
+with the package installed.
+
+| File | Surfaces |
+|---|---|
+| `01-hello.mjs` | `Image.build` + `pool.acquire` + `vm.exec` — the minimum program |
+| `02-pool.mjs`  | Pool sizing (`min`/`max`), `pool.stats()`, concurrent acquire |
+| `03-snapshot-then-restore.mjs` | `vm.writeFile` / `readFile`, mid-flight `vm.snapshot()`, `Image.fromSnapshot` |
+| `04-expose-tcp.mjs` | `listenerRequired: true` bakes, `vm.exposeTcp()`, `TcpForwarder` |
+| `05-spawn-streaming.mjs` | `vm.spawn()` → `ExecChild` (writeStdin / readStdout / wait) |
+
+## Requirements
+
+- macOS on Apple Silicon (no Linux/Windows backends yet)
+- Docker available for the OCI image pull on first run
+- Node ≥ 18.17
+
+## Running locally from a source checkout
+
+The examples import `"@supermachine/core"` as if installed from
+npm. From this repo, run them with a path-rewrite:
+
+```sh
+cd npm/supermachine-core
+npm install
+npm run build
+# then either: `npm link` once, then `node examples/01-hello.mjs`
+# or: rewrite the import inline
+node --input-type=module -e \
+  "$(sed 's|@supermachine/core|./index.js|' examples/01-hello.mjs)"
+```
+
+For a quick smoke test that all five work end-to-end:
+
+```sh
+for f in examples/*.mjs; do
+  echo "=== $f ===";
+  node --input-type=module -e "$(sed 's|@supermachine/core|./index.js|' $f)";
+done
+```