@indexable/sdk 0.0.1

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

@@ -0,0 +1,12 @@
+{
+	"name": "@indexable/sdk-linux-x64-gnu",
+	"version": "0.0.1",
+	"os": ["linux"],
+	"cpu": ["x64"],
+	"main": "ix-sdk.linux-x64-gnu.node",
+	"files": ["ix-sdk.linux-x64-gnu.node"],
+	"license": "MIT",
+	"engines": {
+		"node": ">= 18"
+	}
+}

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@indexable/sdk",
+	"version": "0.0.1",
+	"type": "module",
+	"main": "./src/index.ts",
+	"exports": {
+		".": "./src/index.ts"
+	},
+	"files": ["src/", "npm/"],
+	"scripts": {
+		"build": "cargo build -p ix-sdk-napi --profile release-external --target x86_64-unknown-linux-gnu && cp ../../target/x86_64-unknown-linux-gnu/release-external/libix_sdk_napi.so npm/linux-x64-gnu/ix-sdk.linux-x64-gnu.node",
+		"test": "bun test src/",
+		"typecheck": "bunx tsc --noEmit"
+	},
+	"optionalDependencies": {
+		"@indexable/sdk-linux-x64-gnu": "0.0.1"
+	},
+	"devDependencies": {
+		"bun-types": "latest"
+	},
+	"engines": {
+		"node": ">= 18"
+	},
+	"license": "MIT"
+}

package/src/index.test.ts

@@ -0,0 +1,102 @@
+import { describe, test, expect, afterEach } from "bun:test";
+import Ix from "./index";
+import type { Vm } from "./index";
+
+const IMAGE = "ubuntu:24.04";
+const TIMEOUT_MS = 120_000;
+
+let cleanup: Vm[] = [];
+
+afterEach(async () => {
+	for (const vm of cleanup) {
+		try {
+			await vm.stop();
+		} catch {
+			// might already be stopped
+		}
+		try {
+			await vm.delete();
+		} catch {
+			// best-effort
+		}
+	}
+	cleanup = [];
+});
+
+function track(vm: Vm): Vm {
+	cleanup.push(vm);
+	return vm;
+}
+
+describe("Ix", () => {
+	test("lists VMs", async () => {
+		const ix = new Ix();
+		const vms = await ix.vms();
+		expect(Array.isArray(vms)).toBe(true);
+	});
+});
+
+describe("Vm lifecycle", () => {
+	test(
+		"spawn → getters → stop",
+		async () => {
+			const ix = new Ix();
+			const vm = track(await ix.spawn(IMAGE, { name: "sdk-lifecycle" }));
+
+			expect(vm.id).toBeTruthy();
+			expect(vm.image).toBe(IMAGE);
+			expect(vm.ipv6).toBeTruthy();
+			expect(vm.status).toBe("running");
+
+			await vm.stop();
+			cleanup = [];
+		},
+		TIMEOUT_MS,
+	);
+});
+
+describe("Vm filesystem", () => {
+	test(
+		"writeFile → readFile → listDir",
+		async () => {
+			const ix = new Ix();
+			const vm = track(await ix.spawn(IMAGE, { name: "sdk-fs" }));
+
+			const content = `hello from sdk test ${Date.now()}`;
+			await vm.writeFile("/tmp/sdk-test.txt", content);
+
+			const read = await vm.readFile("/tmp/sdk-test.txt");
+			expect(read).toBe(content);
+
+			const entries = await vm.listDir("/tmp");
+			const found = entries.find((e) => e.name === "sdk-test.txt");
+			expect(found).toBeTruthy();
+		},
+		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" }));
+
+			await main.writeFile("/tmp/file-a.txt", "from main");
+
+			const fork = track(await main.fork("sdk-vcs-fork"));
+
+			await fork.writeFile("/tmp/file-b.txt", "from fork");
+
+			const result = await main.merge(fork);
+			expect(result.conflictPaths.length).toBe(0);
+
+			const a = await main.readFile("/tmp/file-a.txt");
+			expect(a).toBe("from main");
+			const b = await main.readFile("/tmp/file-b.txt");
+			expect(b).toBe("from fork");
+		},
+		TIMEOUT_MS,
+	);
+});

package/src/index.ts

@@ -0,0 +1,135 @@
+/**
+ * @indexable/sdk — TypeScript SDK for the ix platform.
+ *
+ * Native addon built from Rust via napi-rs. No WASM, no runtime init.
+ *
+ * ```ts
+ * 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()
+ * ```
+ */
+
+// napi-rs native addon — loaded from platform-specific npm package.
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+// Platform packages installed via optionalDependencies.
+// npm/bun only installs the one matching the current os+cpu.
+const PLATFORM_PACKAGES: Record<string, string> = {
+	"linux-x64": "@indexable/sdk-linux-x64-gnu",
+};
+
+function loadNativeAddon() {
+	const key = `${process.platform}-${process.arch}`;
+	const pkg = PLATFORM_PACKAGES[key];
+	if (!pkg) throw new Error(`@indexable/sdk: unsupported platform ${key}`);
+	try {
+		return require(pkg);
+	} catch {
+		throw new Error(
+			`@indexable/sdk: failed to load native addon for ${key}. ` +
+				`Ensure ${pkg} is installed (npm install / bun install).`,
+		);
+	}
+}
+
+const native = loadNativeAddon();
+
+export interface SpawnOptions {
+	name?: string;
+	memory?: number;
+	cpus?: number;
+	ipv4?: boolean;
+}
+
+export interface DirEntry {
+	name: string;
+	size: number;
+	isDir: boolean;
+}
+
+export interface MergeResult {
+	appliedOps: number;
+	conflictPaths: string[];
+}
+
+export interface SecretEntry {
+	name: string;
+	createdAt: string;
+}
+
+export interface ConnectOptions {
+	server?: string;
+	token?: string;
+}
+
+/** A virtual machine. */
+export interface Vm {
+	/** VM identifier (e.g. "vm_06e9...") */
+	readonly id: string;
+	readonly name: string;
+	readonly image: string;
+	readonly status: string;
+	readonly ipv6: string;
+	readonly ipv4: string | null;
+	readonly subdomain: string | null;
+
+	stop(): Promise<void>;
+	start(): Promise<void>;
+	restart(): Promise<void>;
+	delete(): Promise<void>;
+
+	writeFile(path: string, content: string): Promise<void>;
+	readFile(path: string): Promise<string>;
+	listDir(path: string): Promise<DirEntry[]>;
+
+	fork(name?: string): Promise<Vm>;
+	merge(source: Vm): Promise<MergeResult>;
+
+	undo(): Promise<boolean>;
+	redo(): Promise<boolean>;
+	revert(timestampMs: number): Promise<void>;
+
+	setSecret(key: string, value: string): Promise<void>;
+	deleteSecret(key: string): Promise<void>;
+	secrets(): Promise<SecretEntry[]>;
+}
+
+/** The ix SDK client. */
+export class Ix {
+	private inner: InstanceType<typeof native.Ix>;
+
+	constructor(options?: ConnectOptions) {
+		this.inner = new native.Ix(options ?? undefined);
+	}
+
+	/** Create a VM from an OCI image. */
+	async spawn(image: string, options?: SpawnOptions): Promise<Vm> {
+		return this.inner.spawn(image, options ?? undefined);
+	}
+
+	/** Retrieve a single VM by ID. */
+	async getVm(vmId: string): Promise<Vm> {
+		return this.inner.getVm(vmId);
+	}
+
+	/** List all VMs. */
+	async vms(): Promise<Vm[]> {
+		return this.inner.vms();
+	}
+}
+
+export default Ix;