@indexable/sdk 0.0.2 → 0.0.4

package/npm/linux-x64-gnu/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@indexable/sdk-linux-x64-gnu",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"os": ["linux"],
 	"cpu": ["x64"],
 	"main": "ix-sdk.linux-x64-gnu.node",

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@indexable/sdk",
-	"version": "0.0.2",
+	"version": "0.0.4",
 	"type": "module",
 	"main": "./src/index.ts",
 	"exports": {
@@ -13,7 +13,7 @@
 		"typecheck": "bunx tsc --noEmit"
 	},
 	"optionalDependencies": {
-		"@indexable/sdk-linux-x64-gnu": "0.0.2"
+		"@indexable/sdk-linux-x64-gnu": "0.0.4"
 	},
 	"devDependencies": {
 		"bun-types": "latest"

package/src/index.test.ts

@@ -38,11 +38,15 @@ describe("Ix", () => {
 
 describe("Vm lifecycle", () => {
 	test(
-		"spawn → getters → stop",
+		"spawn → ready → getters → stop",
 		async () => {
 			const ix = new Ix();
-			const vm = track(await ix.spawn(IMAGE, { name: "sdk-lifecycle" }));
+			const vm = track(ix.spawn(IMAGE, { name: "sdk-lifecycle" }));
 
+			// ID is available immediately (client-generated).
+			expect(vm.id).toMatch(/^vm_/);
+
+			await vm.ready();
 			expect(vm.id).toBeTruthy();
 			expect(vm.image).toBe(IMAGE);
 			expect(vm.ipv6).toBeTruthy();
@@ -60,7 +64,7 @@ describe("Vm filesystem", () => {
 		"writeFile → readFile → listDir",
 		async () => {
 			const ix = new Ix();
-			const vm = track(await ix.spawn(IMAGE, { name: "sdk-fs" }));
+			const vm = track(ix.spawn(IMAGE, { name: "sdk-fs" }));
 
 			const content = `hello from sdk test ${Date.now()}`;
 			await vm.writeFile("/tmp/sdk-test.txt", content);
@@ -76,12 +80,71 @@ describe("Vm filesystem", () => {
 	);
 });
 
+describe("Vm exec", () => {
+	test(
+		"exec → capture stdout and exit code",
+		async () => {
+			const ix = new Ix();
+			const vm = track(ix.spawn(IMAGE, { name: "sdk-exec" }));
+
+			const result = await vm.exec(["echo", "hello from exec"]);
+			expect(result.exitCode).toBe(0);
+			expect(result.stdout).toContain("hello from exec");
+			expect(result.stderr).toBe("");
+		},
+		TIMEOUT_MS,
+	);
+
+	test(
+		"exec → nonzero exit code",
+		async () => {
+			const ix = new Ix();
+			const vm = track(ix.spawn(IMAGE, { name: "sdk-exec-fail" }));
+
+			const result = await vm.exec(["sh", "-c", "exit 42"]);
+			expect(result.exitCode).toBe(42);
+		},
+		TIMEOUT_MS,
+	);
+
+	test(
+		"exec → capture stderr",
+		async () => {
+			const ix = new Ix();
+			const vm = track(ix.spawn(IMAGE, { name: "sdk-exec-stderr" }));
+
+			const result = await vm.exec([
+				"sh",
+				"-c",
+				"echo err >&2; echo out",
+			]);
+			expect(result.exitCode).toBe(0);
+			expect(result.stdout).toContain("out");
+			expect(result.stderr).toContain("err");
+		},
+		TIMEOUT_MS,
+	);
+
+	test(
+		"exec → working directory",
+		async () => {
+			const ix = new Ix();
+			const vm = track(ix.spawn(IMAGE, { name: "sdk-exec-cwd" }));
+
+			const result = await vm.exec(["pwd"], "/tmp");
+			expect(result.exitCode).toBe(0);
+			expect(result.stdout.trim()).toBe("/tmp");
+		},
+		TIMEOUT_MS,
+	);
+});
+
 describe("Vm version control", () => {
 	test(
 		"fork → write on fork → merge back",
 		async () => {
 			const ix = new Ix();
-			const main = track(await ix.spawn(IMAGE, { name: "sdk-vcs-main" }));
+			const main = track(ix.spawn(IMAGE, { name: "sdk-vcs-main" }));
 
 			await main.writeFile("/tmp/file-a.txt", "from main");
 

package/src/index.ts

@@ -7,17 +7,9 @@
  * import Ix from "@indexable/sdk"
  *
  * const ix = new Ix()
- * const vm = await ix.spawn("ubuntu:24.04")
- * console.log(vm.ipv6)
- *
- * await vm.writeFile("/tmp/hi", "hello")
- * const content = await vm.readFile("/tmp/hi")
- *
- * const fork = await vm.fork("experiment")
- * await fork.writeFile("/tmp/new", "from fork")
- * await vm.merge(fork)
- *
- * await vm.stop()
+ * const vm = ix.spawn("ubuntu:24.04")         // sync — no await
+ * console.log(vm.id)                           // "vm_06e9..." (available immediately)
+ * await vm.writeFile("/tmp/hi", "hello")       // first await creates the VM on server
  * ```
  */
 
@@ -71,27 +63,46 @@ export interface SecretEntry {
 	createdAt: string;
 }
 
+/** Output from executing a command inside a VM. */
+export interface ExecResult {
+	/** Process exit code (0 = success). */
+	exitCode: number;
+	/** Captured stdout. */
+	stdout: string;
+	/** Captured stderr. */
+	stderr: string;
+}
+
 export interface ConnectOptions {
 	server?: string;
 	token?: string;
 }
 
-/** A virtual machine. */
+/** A virtual machine handle. Getters return `null` until the first awaited operation. */
 export interface Vm {
-	/** VM identifier (e.g. "vm_06e9...") */
+	/** VM identifier — always available, even before the VM is created on the server. */
 	readonly id: string;
-	readonly name: string;
-	readonly image: string;
-	readonly status: string;
-	readonly ipv6: string;
+	readonly name: string | null;
+	readonly image: string | null;
+	readonly status: string | null;
+	readonly ipv6: string | null;
 	readonly ipv4: string | null;
 	readonly subdomain: string | null;
+	readonly startedAt: string | null;
+	readonly stoppedAt: string | null;
+	readonly failureReason: string | null;
+
+	/** Explicitly trigger VM creation when you need metadata before any operation. */
+	ready(): Promise<void>;
 
 	stop(): Promise<void>;
 	start(): Promise<void>;
 	restart(): Promise<void>;
 	delete(): Promise<void>;
 
+	/** Execute a command inside the VM and return its output. */
+	exec(command: string[], workingDir?: string): Promise<ExecResult>;
+
 	writeFile(path: string, content: string): Promise<void>;
 	readFile(path: string): Promise<string>;
 	listDir(path: string): Promise<DirEntry[]>;
@@ -116,8 +127,8 @@ export class Ix {
 		this.inner = new native.Ix(options ?? undefined);
 	}
 
-	/** Create a VM from an OCI image. */
-	async spawn(image: string, options?: SpawnOptions): Promise<Vm> {
+	/** Create a VM handle from an OCI image. Returns immediately (sync). */
+	spawn(image: string, options?: SpawnOptions): Vm {
 		return this.inner.spawn(image, options ?? undefined);
 	}