matchlock-sdk 0.1.22

package/README.md

@@ -0,0 +1,57 @@
+# Matchlock TypeScript SDK
+
+TypeScript client for [Matchlock](https://github.com/jingkaihe/matchlock), with feature parity across the existing Go and Python SDKs.
+
+## Requirements
+
+- Node.js 22+
+- `matchlock` CLI installed and available on `PATH` (or configured with `binaryPath`)
+
+## Install (from source)
+
+```bash
+cd sdk/typescript
+npm install
+npm run build
+```
+
+## Quick Start
+
+```ts
+import { Client, Sandbox } from "matchlock-sdk";
+
+const sandbox = new Sandbox("alpine:latest")
+  .withCPUs(2)
+  .withMemory(1024)
+  .allowHost("api.openai.com")
+  .addSecret("API_KEY", process.env.API_KEY ?? "", "api.openai.com");
+
+const client = new Client();
+
+try {
+  await client.launch(sandbox);
+  const result = await client.exec("echo hello from sandbox");
+  console.log(result.stdout);
+} finally {
+  await client.close();
+}
+```
+
+## Highlights
+
+- Fluent sandbox builder (`Sandbox`) with network, secrets, mounts, env, VFS hooks, image config
+- JSON-RPC `create`, `exec`, `exec_stream`, `write_file`, `read_file`, `list_files`, `port_forward`, `cancel`, `close`
+- Streaming stdout/stderr via `execStream`
+- Local VFS callbacks (`hook`, `dangerousHook`, `mutateHook`, `actionHook`)
+- Port forwarding API parity (`portForward`, `portForwardWithAddresses`)
+- Lifecycle control (`close`, `remove`, `vmId`)
+
+## Development
+
+```bash
+cd sdk/typescript
+npm install
+npm run typecheck
+npm test
+npm run build
+```

package/dist/builder.d.ts

@@ -0,0 +1,37 @@
+import type { CreateOptions, ImageConfig, MountConfig, VFSInterceptionConfig } from "./types";
+export declare function cloneCreateOptions(opts: CreateOptions): CreateOptions;
+export declare class Sandbox {
+    private readonly opts;
+    constructor(image: string);
+    withPrivileged(): Sandbox;
+    withCPUs(cpus: number): Sandbox;
+    withMemory(mb: number): Sandbox;
+    withDiskSize(mb: number): Sandbox;
+    withTimeout(seconds: number): Sandbox;
+    withWorkspace(path: string): Sandbox;
+    withVFSInterception(config: VFSInterceptionConfig): Sandbox;
+    withEnv(name: string, value: string): Sandbox;
+    withEnvMap(env: Record<string, string>): Sandbox;
+    allowHost(...hosts: string[]): Sandbox;
+    addHost(host: string, ip: string): Sandbox;
+    blockPrivateIPs(): Sandbox;
+    withBlockPrivateIPs(enabled: boolean): Sandbox;
+    allowPrivateIPs(): Sandbox;
+    unsetBlockPrivateIPs(): Sandbox;
+    addSecret(name: string, value: string, ...hosts: string[]): Sandbox;
+    withDNSServers(...servers: string[]): Sandbox;
+    withHostname(hostname: string): Sandbox;
+    withNetworkMTU(mtu: number): Sandbox;
+    withPortForward(localPort: number, remotePort: number): Sandbox;
+    withPortForwardAddresses(...addresses: string[]): Sandbox;
+    mount(guestPath: string, config: MountConfig): Sandbox;
+    mountHostDir(guestPath: string, hostPath: string): Sandbox;
+    mountHostDirReadonly(guestPath: string, hostPath: string): Sandbox;
+    mountMemory(guestPath: string): Sandbox;
+    mountOverlay(guestPath: string, hostPath: string): Sandbox;
+    withUser(user: string): Sandbox;
+    withEntrypoint(...entrypoint: string[]): Sandbox;
+    withImageConfig(config: ImageConfig | undefined | null): Sandbox;
+    options(): CreateOptions;
+}
+export declare function createSandbox(image: string): Sandbox;

package/dist/builder.js

@@ -0,0 +1,199 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Sandbox = void 0;
+exports.cloneCreateOptions = cloneCreateOptions;
+exports.createSandbox = createSandbox;
+function cloneCreateOptions(opts) {
+    return {
+        ...opts,
+        allowedHosts: opts.allowedHosts ? [...opts.allowedHosts] : undefined,
+        addHosts: opts.addHosts ? opts.addHosts.map((x) => ({ ...x })) : undefined,
+        mounts: opts.mounts
+            ? Object.fromEntries(Object.entries(opts.mounts).map(([k, v]) => [k, { ...v }]))
+            : undefined,
+        env: opts.env ? { ...opts.env } : undefined,
+        secrets: opts.secrets
+            ? opts.secrets.map((s) => ({ ...s, hosts: s.hosts ? [...s.hosts] : undefined }))
+            : undefined,
+        vfsInterception: opts.vfsInterception
+            ? {
+                emitEvents: opts.vfsInterception.emitEvents,
+                rules: opts.vfsInterception.rules
+                    ? opts.vfsInterception.rules.map((r) => ({ ...r, ops: r.ops ? [...r.ops] : undefined }))
+                    : undefined,
+            }
+            : undefined,
+        dnsServers: opts.dnsServers ? [...opts.dnsServers] : undefined,
+        portForwards: opts.portForwards
+            ? opts.portForwards.map((pf) => ({ ...pf }))
+            : undefined,
+        portForwardAddresses: opts.portForwardAddresses
+            ? [...opts.portForwardAddresses]
+            : undefined,
+        imageConfig: opts.imageConfig
+            ? {
+                ...opts.imageConfig,
+                entrypoint: opts.imageConfig.entrypoint
+                    ? [...opts.imageConfig.entrypoint]
+                    : undefined,
+                cmd: opts.imageConfig.cmd ? [...opts.imageConfig.cmd] : undefined,
+                env: opts.imageConfig.env ? { ...opts.imageConfig.env } : undefined,
+            }
+            : undefined,
+    };
+}
+class Sandbox {
+    opts;
+    constructor(image) {
+        this.opts = { image };
+    }
+    withPrivileged() {
+        this.opts.privileged = true;
+        return this;
+    }
+    withCPUs(cpus) {
+        this.opts.cpus = cpus;
+        return this;
+    }
+    withMemory(mb) {
+        this.opts.memoryMb = mb;
+        return this;
+    }
+    withDiskSize(mb) {
+        this.opts.diskSizeMb = mb;
+        return this;
+    }
+    withTimeout(seconds) {
+        this.opts.timeoutSeconds = seconds;
+        return this;
+    }
+    withWorkspace(path) {
+        this.opts.workspace = path;
+        return this;
+    }
+    withVFSInterception(config) {
+        this.opts.vfsInterception = config;
+        return this;
+    }
+    withEnv(name, value) {
+        this.opts.env = this.opts.env ?? {};
+        this.opts.env[name] = value;
+        return this;
+    }
+    withEnvMap(env) {
+        this.opts.env = this.opts.env ?? {};
+        Object.assign(this.opts.env, env);
+        return this;
+    }
+    allowHost(...hosts) {
+        this.opts.allowedHosts = this.opts.allowedHosts ?? [];
+        this.opts.allowedHosts.push(...hosts);
+        return this;
+    }
+    addHost(host, ip) {
+        this.opts.addHosts = this.opts.addHosts ?? [];
+        this.opts.addHosts.push({ host, ip });
+        return this;
+    }
+    blockPrivateIPs() {
+        return this.withBlockPrivateIPs(true);
+    }
+    withBlockPrivateIPs(enabled) {
+        this.opts.blockPrivateIPs = enabled;
+        this.opts.blockPrivateIPsSet = true;
+        return this;
+    }
+    allowPrivateIPs() {
+        return this.withBlockPrivateIPs(false);
+    }
+    unsetBlockPrivateIPs() {
+        this.opts.blockPrivateIPs = false;
+        this.opts.blockPrivateIPsSet = false;
+        return this;
+    }
+    addSecret(name, value, ...hosts) {
+        this.opts.secrets = this.opts.secrets ?? [];
+        const secret = { name, value, hosts };
+        this.opts.secrets.push(secret);
+        return this;
+    }
+    withDNSServers(...servers) {
+        this.opts.dnsServers = this.opts.dnsServers ?? [];
+        this.opts.dnsServers.push(...servers);
+        return this;
+    }
+    withHostname(hostname) {
+        this.opts.hostname = hostname;
+        return this;
+    }
+    withNetworkMTU(mtu) {
+        this.opts.networkMtu = mtu;
+        return this;
+    }
+    withPortForward(localPort, remotePort) {
+        this.opts.portForwards = this.opts.portForwards ?? [];
+        this.opts.portForwards.push({ localPort, remotePort });
+        return this;
+    }
+    withPortForwardAddresses(...addresses) {
+        this.opts.portForwardAddresses = this.opts.portForwardAddresses ?? [];
+        this.opts.portForwardAddresses.push(...addresses);
+        return this;
+    }
+    mount(guestPath, config) {
+        this.opts.mounts = this.opts.mounts ?? {};
+        this.opts.mounts[guestPath] = { ...config };
+        return this;
+    }
+    mountHostDir(guestPath, hostPath) {
+        return this.mount(guestPath, { type: "host_fs", hostPath });
+    }
+    mountHostDirReadonly(guestPath, hostPath) {
+        return this.mount(guestPath, { type: "host_fs", hostPath, readonly: true });
+    }
+    mountMemory(guestPath) {
+        return this.mount(guestPath, { type: "memory" });
+    }
+    mountOverlay(guestPath, hostPath) {
+        return this.mount(guestPath, { type: "overlay", hostPath });
+    }
+    withUser(user) {
+        this.opts.imageConfig = this.opts.imageConfig ?? {};
+        this.opts.imageConfig.user = user;
+        return this;
+    }
+    withEntrypoint(...entrypoint) {
+        this.opts.imageConfig = this.opts.imageConfig ?? {};
+        this.opts.imageConfig.entrypoint = [...entrypoint];
+        return this;
+    }
+    withImageConfig(config) {
+        if (!config) {
+            return this;
+        }
+        this.opts.imageConfig = this.opts.imageConfig ?? {};
+        if (config.user) {
+            this.opts.imageConfig.user = config.user;
+        }
+        if (config.workingDir) {
+            this.opts.imageConfig.workingDir = config.workingDir;
+        }
+        if (config.entrypoint && config.entrypoint.length > 0) {
+            this.opts.imageConfig.entrypoint = [...config.entrypoint];
+        }
+        if (config.cmd && config.cmd.length > 0) {
+            this.opts.imageConfig.cmd = [...config.cmd];
+        }
+        if (config.env && Object.keys(config.env).length > 0) {
+            this.opts.imageConfig.env = { ...config.env };
+        }
+        return this;
+    }
+    options() {
+        return cloneCreateOptions(this.opts);
+    }
+}
+exports.Sandbox = Sandbox;
+function createSandbox(image) {
+    return new Sandbox(image);
+}

package/dist/client.d.ts

@@ -0,0 +1,65 @@
+import { Sandbox } from "./builder";
+import { type BinaryLike, type Config, type CreateOptions, type ExecOptions, type ExecResult, type ExecStreamOptions, type ExecStreamResult, type FileInfo, type PortForwardBinding, type RequestOptions, type StreamWriter } from "./types";
+export declare function defaultConfig(config?: Config): Required<Config>;
+export declare class Client {
+    private readonly config;
+    private process;
+    private requestID;
+    private pending;
+    private writeLock;
+    private readBuffer;
+    private vmIDValue;
+    private lastVMID;
+    private closed;
+    private closing;
+    private vfsHooks;
+    private vfsMutateHooks;
+    private vfsActionHooks;
+    private vfsHookActive;
+    constructor(config?: Config);
+    get vmId(): string;
+    start(): Promise<void>;
+    close(timeoutSeconds?: number): Promise<void>;
+    remove(): Promise<void>;
+    launch(sandbox: Sandbox): Promise<string>;
+    create(opts?: CreateOptions): Promise<string>;
+    private resolveCreateBlockPrivateIPs;
+    private buildCreateNetworkParams;
+    exec(command: string, options?: ExecOptions): Promise<ExecResult>;
+    execWithDir(command: string, workingDir?: string, options?: RequestOptions): Promise<ExecResult>;
+    execStream(command: string, options?: ExecStreamOptions): Promise<ExecStreamResult>;
+    execStreamWithDir(command: string, workingDir?: string, stdout?: StreamWriter, stderr?: StreamWriter, options?: RequestOptions): Promise<ExecStreamResult>;
+    writeFile(path: string, content: BinaryLike, options?: RequestOptions): Promise<void>;
+    writeFileMode(path: string, content: BinaryLike, mode: number, options?: RequestOptions): Promise<void>;
+    readFile(path: string, options?: RequestOptions): Promise<Buffer>;
+    listFiles(path: string, options?: RequestOptions): Promise<FileInfo[]>;
+    portForward(...specs: string[]): Promise<PortForwardBinding[]>;
+    portForwardWithAddresses(addresses: string[] | undefined, ...specs: string[]): Promise<PortForwardBinding[]>;
+    private portForwardMappings;
+    private parsePortForwards;
+    private parsePortForward;
+    private parsePort;
+    private sendRequest;
+    private sendCancelRequest;
+    private enqueueWrite;
+    private processReadBuffer;
+    private handleMessage;
+    private handleNotification;
+    private handleVFSFileEventNotification;
+    private handleVFSFileEvent;
+    private runVFSSafeHooksForEvent;
+    private runSingleVFSHook;
+    private matchesVFSHook;
+    private applyLocalWriteMutations;
+    private applyLocalActionHooks;
+    private compileVFSHooks;
+    private validateLocalAfterRule;
+    private ruleToWire;
+    private setLocalVFSHooks;
+    private validateAddHost;
+    private isValidIP;
+    private writeStreamChunk;
+    private isRunning;
+    private waitForProcessExit;
+    private handleProcessClosed;
+}