@computesdk/uno 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 computesdk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,86 @@
-# Temporary Holding Version
+# @computesdk/uno
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[Uno](https://uno.place) provider for [ComputeSDK](https://www.computesdk.com).
+
+Every Uno machine is a full Linux microVM on Firecracker, not a container: systemd, `apt`, passwordless `sudo` and a real disk. It boots from a warm snapshot in seconds. Machines in the **US region run on High-end servers**, on our fastest processors.
+
+## Installation
+
+```bash
+npm install @computesdk/uno
+```
+
+## Setup
+
+Create an API key in the Uno console (**Settings → API keys**) and add it to your environment:
+
+```bash
+UNO_API_KEY=your_uno_api_key
+UNO_REGION=us        # optional: 'us' (High-end) or 'nl'; defaults to your account's region
+```
+
+Creating machines needs an Uno plan. Machine sizes fit inside your plan's limits (for example, 8 vCPU / 16 GiB needs Pro or Max).
+
+## Usage
+
+```typescript
+import { uno } from '@computesdk/uno'
+
+const compute = uno({ apiKey: process.env.UNO_API_KEY, region: 'us' })
+
+const sandbox = await compute.sandbox.create({ vcpus: 8, memoryMiB: 16384 })
+
+const result = await sandbox.runCommand('uname -a && nproc')
+console.log(result.stdout)
+
+await sandbox.filesystem.writeFile('/tmp/hello.txt', 'Hello from Uno')
+console.log(await sandbox.filesystem.readFile('/tmp/hello.txt'))
+
+await sandbox.destroy()
+```
+
+## Configuration
+
+```typescript
+interface UnoConfig {
+  /** API key. Falls back to UNO_API_KEY. */
+  apiKey?: string
+  /** API base URL. Falls back to UNO_API_URL, then https://console.uno4.dev. */
+  baseUrl?: string
+  /** 'us' (High-end) or 'nl'. Falls back to UNO_REGION, then your account's region. */
+  region?: string
+  /** OS template: 'ubuntu-24.04' (default), 'ubuntu-22.04', 'debian-12'. */
+  template?: string
+  /** Defaults when create() does not say: 2 vCPU, 2048 MiB, 10 GB disk. */
+  vcpu?: number
+  ramMb?: number
+  diskGb?: number
+  /** How long create() waits for the machine to boot. Default 120 000 ms. */
+  readyTimeoutMs?: number
+}
+```
+
+`create()` reads the size from `vcpus` / `cpus` / `cpu`, `memoryMiB` / `memMiB` / `memoryMb` / `memory` and `diskMiB` / `diskMb`. Memory is rounded up to a multiple of 256 MiB. `templateId` selects the OS template.
+
+## How commands run
+
+- Commands run as user `uno` in a login `bash` shell, in the home directory. Use `sudo` for root.
+- A command can run for up to 1 hour (`timeout`, default 5 minutes). Long commands are long-polled, so no single HTTP response hangs on proxy time limits. Retries use an idempotency key, so a dropped connection never starts a command twice.
+- Up to 256 KiB of stdout and 64 KiB of stderr are returned per command; if either was cut, `stderr` ends with an `[uno] … truncated` line. Command text is limited to 64 KiB: write bigger inputs with `filesystem.writeFile` first.
+- `filesystem.readFile`, `writeFile` and `readdir` have no size limit: they move data in chunks, and `writeFile` renames a temp file into place only after every chunk landed.
+- One command runs on a machine at a time. A concurrent `runCommand` on the same machine is retried for a few seconds, then fails with `BOX_BUSY`: use one machine per parallel job, or `background: true`.
+
+## Supported
+
+| Feature | |
+|---|---|
+| create / getById / list / destroy | ✅ |
+| runCommand (cwd, env, timeout, background) | ✅ |
+| filesystem (read, write, mkdir, readdir, exists, remove) | ✅ via shell |
+| getUrl | port 80 only, at `https://<name>.uno4.dev` |
+| live output streaming, snapshots, templates API | not yet |
+
+## Links
+
+- Uno: https://uno.place
+- API reference: `GET https://console.uno4.dev/api/v1/openapi.yaml`

package/dist/index.d.mts

@@ -0,0 +1,154 @@
+import * as _computesdk_provider from '@computesdk/provider';
+import * as computesdk from 'computesdk';
+
+/**
+ * Minimal HTTP client for the Uno box API.
+ *
+ * The API is a small JSON surface (`/api/v1/boxes`), so this talks to it with
+ * `fetch` and has no dependencies. Everything that touches the network lives
+ * here; `./index` only maps ComputeSDK's interface onto these calls.
+ *
+ * @see https://uno.place/docs/api
+ */
+declare const DEFAULT_BASE_URL = "https://console.uno4.dev";
+/** Box JSON as returned by `GET /api/v1/boxes/{id}` (fields this package reads). */
+interface UnoBox {
+    id: number;
+    name: string;
+    status: string;
+    provision_state?: string;
+    provision_error?: string;
+    vcpu: number;
+    ram_mb: number;
+    disk_gb: number;
+    created_at: string;
+    hostname?: string;
+    url?: string;
+    ssh_command?: string;
+    network_region?: string;
+    max_lifetime_s?: number;
+    comment?: string;
+    [key: string]: unknown;
+}
+interface UnoCreateBoxRequest {
+    template: string;
+    vcpu: number;
+    ram_mb: number;
+    disk_gb: number;
+    name?: string;
+    region?: string;
+    ssh_key?: string;
+    comment?: string;
+}
+/** A run as returned by `POST /boxes/{id}/run` (200) or `GET /boxes/{id}/runs/{rid}`. */
+interface UnoRun {
+    run_id?: string;
+    id?: string;
+    status: 'running' | 'finished' | 'error';
+    exit_code?: number;
+    stdout?: string;
+    stderr?: string;
+    stdout_truncated?: boolean;
+    stderr_truncated?: boolean;
+    duration_ms?: number;
+    error_code?: string;
+    command_started?: boolean | null;
+    retry_safe?: boolean;
+}
+interface UnoClientOptions {
+    /** Account API key or a token with `boxes:read`, `boxes:write` and `infra:purchase`. Falls back to `UNO_API_KEY`. */
+    apiKey?: string;
+    /** API base URL. Falls back to `UNO_API_URL`, then {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Per-request timeout for plain API calls, in ms. Default 30 000. */
+    requestTimeoutMs?: number;
+}
+declare class UnoError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly body?: Record<string, unknown> | undefined;
+    constructor(message: string, status: number, code?: string | undefined, body?: Record<string, unknown> | undefined);
+}
+declare class UnoClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly requestTimeoutMs;
+    constructor(options?: UnoClientOptions);
+    /**
+     * One HTTP call. Returns status + parsed JSON body; throws {@link UnoError}
+     * for any status not listed in `accept`.
+     */
+    request<T = Record<string, unknown>>(method: string, path: string, body?: unknown, opts?: {
+        accept?: number[];
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: number;
+        body: T;
+        headers: Headers;
+    }>;
+    createBox(req: UnoCreateBoxRequest, signal?: AbortSignal): Promise<UnoBox>;
+    /**
+     * The box whose `comment` is exactly `marker` (a per-request UUID), created
+     * at or after `since` (ms epoch). Looks up to `attempts` times, 2 s apart: a
+     * create the connection lost may show up in the list a moment later.
+     */
+    findBoxByMarker(marker: string, since: number, attempts?: number): Promise<UnoBox | null>;
+    getBox(id: string | number): Promise<UnoBox | null>;
+    listBoxes(): Promise<UnoBox[]>;
+    /** Delete a box; a box that is already gone is not an error. */
+    deleteBox(id: string | number): Promise<void>;
+    /**
+     * Poll until the box is running and provisioned. Create returns at once with
+     * `status: "provisioning"`; the machine boots from a warm snapshot in seconds.
+     */
+    waitReady(id: string | number, timeoutMs: number, signal?: AbortSignal): Promise<UnoBox>;
+    /**
+     * Run a command and wait for its result.
+     *
+     * The server holds the request for up to `waitS` seconds; longer commands
+     * come back as 202 + run id and are long-polled, so no single HTTP response
+     * outlives proxy idle limits (~100 s). Every attempt carries the same
+     * idempotency key, so a retry after a dropped connection returns the run
+     * already recorded instead of starting the command twice.
+     */
+    run(id: string | number, payload: {
+        cmd: string;
+        env?: Record<string, string>;
+        timeout_s: number;
+    }, opts?: {
+        waitS?: number;
+        idempotencyKey?: string;
+    }): Promise<UnoRun>;
+}
+
+interface UnoConfig extends UnoClientOptions {
+    /**
+     * Region for new machines: `'us'` (High-end) or `'nl'`. Falls back to
+     * `UNO_REGION`; omitted means the account's default region.
+     */
+    region?: string;
+    /** OS template slug (see `GET /api/v1/box-templates`). Default `'ubuntu-24.04'`. */
+    template?: string;
+    /** Default vCPUs when `create` does not say. Default 2. */
+    vcpu?: number;
+    /** Default memory in MiB when `create` does not say. Default 2048. */
+    ramMb?: number;
+    /** Default disk in GB when `create` does not say. Default 10. */
+    diskGb?: number;
+    /** How long `create` waits for the machine to boot, in ms. Default 120 000. */
+    readyTimeoutMs?: number;
+}
+interface UnoSandbox {
+    id: string;
+    box: UnoBox;
+    client: UnoClient;
+    /** Environment from `create({ envs })`, applied to every command. */
+    envs?: Record<string, string>;
+}
+type ConfigWithClient = UnoConfig & {
+    __client?: UnoClient;
+};
+declare const uno: (config: ConfigWithClient) => _computesdk_provider.Provider<UnoSandbox, any, any, computesdk.Volume>;
+
+export { DEFAULT_BASE_URL, type UnoBox, UnoClient, type UnoClientOptions, type UnoConfig, type UnoCreateBoxRequest, UnoError, type UnoRun, type UnoSandbox, uno as default, uno };

package/dist/index.d.ts

@@ -0,0 +1,154 @@
+import * as _computesdk_provider from '@computesdk/provider';
+import * as computesdk from 'computesdk';
+
+/**
+ * Minimal HTTP client for the Uno box API.
+ *
+ * The API is a small JSON surface (`/api/v1/boxes`), so this talks to it with
+ * `fetch` and has no dependencies. Everything that touches the network lives
+ * here; `./index` only maps ComputeSDK's interface onto these calls.
+ *
+ * @see https://uno.place/docs/api
+ */
+declare const DEFAULT_BASE_URL = "https://console.uno4.dev";
+/** Box JSON as returned by `GET /api/v1/boxes/{id}` (fields this package reads). */
+interface UnoBox {
+    id: number;
+    name: string;
+    status: string;
+    provision_state?: string;
+    provision_error?: string;
+    vcpu: number;
+    ram_mb: number;
+    disk_gb: number;
+    created_at: string;
+    hostname?: string;
+    url?: string;
+    ssh_command?: string;
+    network_region?: string;
+    max_lifetime_s?: number;
+    comment?: string;
+    [key: string]: unknown;
+}
+interface UnoCreateBoxRequest {
+    template: string;
+    vcpu: number;
+    ram_mb: number;
+    disk_gb: number;
+    name?: string;
+    region?: string;
+    ssh_key?: string;
+    comment?: string;
+}
+/** A run as returned by `POST /boxes/{id}/run` (200) or `GET /boxes/{id}/runs/{rid}`. */
+interface UnoRun {
+    run_id?: string;
+    id?: string;
+    status: 'running' | 'finished' | 'error';
+    exit_code?: number;
+    stdout?: string;
+    stderr?: string;
+    stdout_truncated?: boolean;
+    stderr_truncated?: boolean;
+    duration_ms?: number;
+    error_code?: string;
+    command_started?: boolean | null;
+    retry_safe?: boolean;
+}
+interface UnoClientOptions {
+    /** Account API key or a token with `boxes:read`, `boxes:write` and `infra:purchase`. Falls back to `UNO_API_KEY`. */
+    apiKey?: string;
+    /** API base URL. Falls back to `UNO_API_URL`, then {@link DEFAULT_BASE_URL}. */
+    baseUrl?: string;
+    /** Per-request timeout for plain API calls, in ms. Default 30 000. */
+    requestTimeoutMs?: number;
+}
+declare class UnoError extends Error {
+    readonly status: number;
+    readonly code?: string | undefined;
+    readonly body?: Record<string, unknown> | undefined;
+    constructor(message: string, status: number, code?: string | undefined, body?: Record<string, unknown> | undefined);
+}
+declare class UnoClient {
+    readonly baseUrl: string;
+    private readonly apiKey;
+    private readonly requestTimeoutMs;
+    constructor(options?: UnoClientOptions);
+    /**
+     * One HTTP call. Returns status + parsed JSON body; throws {@link UnoError}
+     * for any status not listed in `accept`.
+     */
+    request<T = Record<string, unknown>>(method: string, path: string, body?: unknown, opts?: {
+        accept?: number[];
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<{
+        status: number;
+        body: T;
+        headers: Headers;
+    }>;
+    createBox(req: UnoCreateBoxRequest, signal?: AbortSignal): Promise<UnoBox>;
+    /**
+     * The box whose `comment` is exactly `marker` (a per-request UUID), created
+     * at or after `since` (ms epoch). Looks up to `attempts` times, 2 s apart: a
+     * create the connection lost may show up in the list a moment later.
+     */
+    findBoxByMarker(marker: string, since: number, attempts?: number): Promise<UnoBox | null>;
+    getBox(id: string | number): Promise<UnoBox | null>;
+    listBoxes(): Promise<UnoBox[]>;
+    /** Delete a box; a box that is already gone is not an error. */
+    deleteBox(id: string | number): Promise<void>;
+    /**
+     * Poll until the box is running and provisioned. Create returns at once with
+     * `status: "provisioning"`; the machine boots from a warm snapshot in seconds.
+     */
+    waitReady(id: string | number, timeoutMs: number, signal?: AbortSignal): Promise<UnoBox>;
+    /**
+     * Run a command and wait for its result.
+     *
+     * The server holds the request for up to `waitS` seconds; longer commands
+     * come back as 202 + run id and are long-polled, so no single HTTP response
+     * outlives proxy idle limits (~100 s). Every attempt carries the same
+     * idempotency key, so a retry after a dropped connection returns the run
+     * already recorded instead of starting the command twice.
+     */
+    run(id: string | number, payload: {
+        cmd: string;
+        env?: Record<string, string>;
+        timeout_s: number;
+    }, opts?: {
+        waitS?: number;
+        idempotencyKey?: string;
+    }): Promise<UnoRun>;
+}
+
+interface UnoConfig extends UnoClientOptions {
+    /**
+     * Region for new machines: `'us'` (High-end) or `'nl'`. Falls back to
+     * `UNO_REGION`; omitted means the account's default region.
+     */
+    region?: string;
+    /** OS template slug (see `GET /api/v1/box-templates`). Default `'ubuntu-24.04'`. */
+    template?: string;
+    /** Default vCPUs when `create` does not say. Default 2. */
+    vcpu?: number;
+    /** Default memory in MiB when `create` does not say. Default 2048. */
+    ramMb?: number;
+    /** Default disk in GB when `create` does not say. Default 10. */
+    diskGb?: number;
+    /** How long `create` waits for the machine to boot, in ms. Default 120 000. */
+    readyTimeoutMs?: number;
+}
+interface UnoSandbox {
+    id: string;
+    box: UnoBox;
+    client: UnoClient;
+    /** Environment from `create({ envs })`, applied to every command. */
+    envs?: Record<string, string>;
+}
+type ConfigWithClient = UnoConfig & {
+    __client?: UnoClient;
+};
+declare const uno: (config: ConfigWithClient) => _computesdk_provider.Provider<UnoSandbox, any, any, computesdk.Volume>;
+
+export { DEFAULT_BASE_URL, type UnoBox, UnoClient, type UnoClientOptions, type UnoConfig, type UnoCreateBoxRequest, UnoError, type UnoRun, type UnoSandbox, uno as default, uno };