withruntime 0.8.4 → 0.9.0

package/dist/codesandbox/index.d.ts

@@ -0,0 +1,386 @@
+import type { Runtime } from "../client.js";
+import type { Sandbox as NativeSandbox, Process } from "../sandbox.js";
+import { CompatibilityError, type ClientOptions } from "../compat/core.js";
+import { ManagedTasks } from "./guest-service.js";
+export { CompatibilityError };
+export declare class VMTier {
+    readonly name: string;
+    readonly cpuCores: number;
+    readonly memoryGiB: number;
+    readonly diskGB: number;
+    private constructor();
+    static readonly Pico: VMTier;
+    static readonly Nano: VMTier;
+    static readonly Micro: VMTier;
+    static readonly Small: VMTier;
+    static readonly Medium: VMTier;
+    static readonly Large: VMTier;
+    static readonly XLarge: VMTier;
+    static readonly All: VMTier[];
+    static fromName(name: string): VMTier;
+    static fromSpecs(specs: {
+        cpu: number;
+        memGiB: number;
+        diskGB?: number;
+    }): VMTier | undefined;
+}
+export type CreateSandboxOpts = {
+    id?: string;
+    title?: string;
+    description?: string;
+    tags?: string[];
+    privacy?: "private" | "public" | "public-hosts" | "unlisted";
+    vmTier?: VMTier;
+    hibernationTimeoutSeconds?: number;
+};
+export type SessionCreateOptions = {
+    id?: string;
+    env?: Record<string, string>;
+    permission?: "read" | "write";
+};
+export type ShellRunOpts = {
+    env?: Record<string, string>;
+    cwd?: string;
+    name?: string;
+    dimensions?: {
+        cols: number;
+        rows: number;
+    };
+    asGlobalSession?: boolean;
+};
+export declare class CodeSandbox {
+    readonly sandboxes: Sandboxes;
+    constructor(apiToken?: string, options?: ClientOptions);
+}
+export declare class Sandboxes {
+    private readonly runtime;
+    constructor(runtime: Runtime);
+    create(options?: CreateSandboxOpts): Promise<Sandbox>;
+    resume(id: string): Promise<Sandbox>;
+    hibernate(id: string): Promise<void>;
+    shutdown(id: string): Promise<void>;
+    delete(id: string): Promise<void>;
+    restart(id: string, options?: {
+        hibernationTimeoutSeconds?: number;
+    }): Promise<Sandbox>;
+    fork(id: string, options?: Omit<CreateSandboxOpts, "id">): Promise<Sandbox>;
+    get(id: string): Promise<{
+        id: string;
+        createdAt: Date;
+        updatedAt: Date;
+        title: string | undefined;
+        description: string | undefined;
+        privacy: string;
+        tags: string[];
+    }>;
+    list(options?: {
+        tags?: string[];
+        status?: "running";
+        limit?: number;
+        pagination?: {
+            page?: number;
+            pageSize?: number;
+        };
+        direction?: "asc" | "desc";
+        orderBy?: "inserted_at" | "updated_at";
+    }): Promise<{
+        sandboxes: {
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            title: string | undefined;
+            description: string | undefined;
+            privacy: string;
+            tags: string[];
+        }[];
+        totalCount: number;
+        hasMore: boolean;
+        pagination: {
+            currentPage: number;
+            nextPage: number | null;
+            pageSize: number;
+        };
+    }>;
+}
+export declare class Sandbox {
+    readonly native: NativeSandbox;
+    readonly bootupType: "RUNNING" | "CLEAN" | "RESUME" | "FORK";
+    constructor(native: NativeSandbox, bootupType: "RUNNING" | "CLEAN" | "RESUME" | "FORK");
+    get id(): string;
+    get cluster(): string;
+    updateHibernationTimeout(timeoutSeconds: number): Promise<void>;
+    connect(options?: SessionCreateOptions): Promise<SandboxClient>;
+}
+export declare class CommandError extends Error {
+    readonly exitCode: number;
+    readonly output: string;
+    constructor(message: string, exitCode: number, output: string);
+}
+export type CommandStatus = "RUNNING" | "FINISHED" | "ERROR" | "KILLED" | "RESTARTING";
+export declare class Command {
+    private process;
+    readonly command: string;
+    readonly name?: string | undefined;
+    private readonly startAgain?;
+    readonly onOutput: (listener: (value: string) => void) => {
+        dispose: () => boolean;
+    };
+    readonly onStatusChange: (listener: (value: CommandStatus) => void) => {
+        dispose: () => boolean;
+    };
+    private outputEvent;
+    private statusEvent;
+    private output;
+    private result;
+    private resolveResult;
+    private rejectResult;
+    private generation;
+    private subscription;
+    private transition;
+    private currentStatus;
+    get status(): CommandStatus;
+    set status(value: CommandStatus);
+    constructor(process: Process, command: string, name?: string | undefined, startAgain?: (() => Promise<Process>) | undefined);
+    private setStatus;
+    private follow;
+    /** Detach this client's subscription without terminating the guest command. */
+    detach(): void;
+    open(dimensions?: {
+        cols: number;
+        rows: number;
+    }): Promise<string>;
+    /** Internal task bridge: read without yielding between log handoff and events. */
+    get bufferedOutput(): string;
+    waitUntilComplete(): Promise<string>;
+    private serial;
+    restart(): Promise<void>;
+    kill(): Promise<void>;
+}
+export declare class FileSystem {
+    private readonly native;
+    private readonly files;
+    constructor(native: NativeSandbox);
+    writeFile(path: string, content: Uint8Array, options?: {
+        create?: boolean;
+        overwrite?: boolean;
+    }): Promise<void>;
+    writeTextFile(path: string, content: string, options?: {
+        create?: boolean;
+        overwrite?: boolean;
+    }): Promise<void>;
+    batchWrite(files: {
+        path: string;
+        content: string | Uint8Array;
+    }[]): Promise<void>;
+    readFile(path: string): Promise<Uint8Array<ArrayBufferLike>>;
+    readTextFile(path: string): Promise<string>;
+    mkdir(path: string, recursive?: boolean): Promise<void>;
+    remove(path: string, recursive?: boolean): Promise<void>;
+    rename(from: string, to: string, overwrite?: boolean): Promise<void>;
+    copy(from: string, to: string, recursive?: boolean, overwrite?: boolean): Promise<void>;
+    readdir(path: string): Promise<{
+        name: string;
+        type: string;
+        isSymlink: boolean;
+    }[]>;
+    stat(path: string): Promise<{
+        type: string;
+        isSymlink: boolean;
+        size: number;
+        atime: number;
+        mtime: number;
+        ctime: number;
+    }>;
+}
+export declare class SandboxClient {
+    private readonly native;
+    private readonly env;
+    readonly fs: FileSystem;
+    readonly commands: {
+        runBackground: (command: string | string[], options?: ShellRunOpts) => Promise<Command>;
+        run: (command: string | string[], options?: ShellRunOpts) => Promise<string>;
+        getAll: () => Promise<Command[]>;
+    };
+    readonly ports: {
+        get: (port: number) => Promise<{
+            port: number;
+            host: string;
+        }>;
+        getAll: () => Promise<{
+            port: number;
+            host: string;
+        }[]>;
+        waitForPort: (port: number, options?: {
+            timeoutMs?: number;
+        }) => Promise<{
+            port: number;
+            host: string;
+        }>;
+    };
+    readonly tasks: Tasks;
+    readonly setup: Setup;
+    readonly workspacePath = "/project/sandbox";
+    private disconnected;
+    private readonly attached;
+    private readonly previewURLs;
+    private stopKeepAlive?;
+    constructor(native: NativeSandbox, env: Record<string, string>);
+    initialize(): Promise<void>;
+    previewURL(port: number): string;
+    private assertConnected;
+    private start;
+    private attach;
+    get id(): string;
+    get state(): "DISCONNECTED" | "CONNECTED";
+    disconnect(): Promise<void>;
+    reconnect(): Promise<void>;
+    keepActiveWhileConnected(enabled: boolean): void;
+    dispose(): void;
+}
+export type TaskDefinition = {
+    name: string;
+    command: string;
+    runAtStart?: boolean;
+    preview?: {
+        port?: number;
+        prLink?: "direct" | "redirect" | "devtool";
+        "pr-link"?: "direct" | "redirect" | "devtool";
+    };
+};
+/** Configured tasks share durable native processes between client connections. */
+export declare class Tasks {
+    private readonly client;
+    private readonly native;
+    private cached?;
+    private readonly managed;
+    private loaded;
+    private cancelled;
+    constructor(client: SandboxClient, native: NativeSandbox);
+    getAll(): Promise<Task[]>;
+    get(id: string): Promise<Task | undefined>;
+    reconnect(): Promise<void>;
+    dispose(): void;
+    private load;
+    private monitor;
+}
+export declare class Task {
+    private readonly client;
+    readonly id: string;
+    private readonly definition;
+    private readonly managed;
+    private process?;
+    private processId?;
+    private fault?;
+    private disposed;
+    private opened;
+    private streamedLength;
+    private openedLength;
+    private readonly outputEvent;
+    private readonly statusEvent;
+    readonly onOutput: (listener: (value: string) => void) => {
+        dispose: () => boolean;
+    };
+    readonly onStatusChange: (listener: (value: CommandStatus | "IDLE") => void) => {
+        dispose: () => boolean;
+    };
+    private subscriptions;
+    private transition;
+    private exposed;
+    constructor(client: SandboxClient, id: string, definition: TaskDefinition, managed: ManagedTasks);
+    reconnect(): Promise<void>;
+    observe(process: Process): void;
+    unavailable(error: unknown): void;
+    get name(): string;
+    get command(): string;
+    get runAtStart(): boolean;
+    get status(): "IDLE" | CommandStatus;
+    get ports(): {
+        port: number;
+        url: string;
+    }[];
+    private attach;
+    open(dimensions?: {
+        cols: number;
+        rows: number;
+    }): Promise<string>;
+    private serial;
+    run(): Promise<void>;
+    restart(): Promise<void>;
+    stop(): Promise<void>;
+    waitForPort(timeout?: number): Promise<{
+        port: number;
+        url: string;
+    }>;
+    dispose(): void;
+}
+type StepState = "IDLE" | "SUCCEEDED" | "FAILED" | "SKIPPED";
+type SetupState = "IDLE" | "IN_PROGRESS" | "FINISHED" | "STOPPED";
+export declare class Setup {
+    private readonly client;
+    private readonly native;
+    private progress;
+    private steps;
+    private loaded?;
+    private active?;
+    private starting?;
+    private failure?;
+    private ignoredRunId?;
+    private managedBoot;
+    private cancelled;
+    private readonly changed;
+    readonly onSetupProgressChange: (listener: (value: void) => void) => {
+        dispose: () => boolean;
+    };
+    constructor(client: SandboxClient, native: NativeSandbox);
+    get status(): SetupState;
+    get currentStepIndex(): number;
+    getSteps(): Step[];
+    initialize(automatic?: boolean): Promise<void>;
+    reconnect(): Promise<void>;
+    private load;
+    run(): Promise<void>;
+    private start;
+    private monitor;
+    waitUntilComplete(): Promise<void>;
+    step(index: number): {
+        name: string;
+        command: string;
+        status: StepState;
+        log?: string;
+        tty?: string;
+    };
+    output(index: number): Promise<string>;
+    open(index: number, dimensions?: {
+        cols: number;
+        rows: number;
+    }): Promise<void>;
+    dispose(): void;
+}
+export declare class Step {
+    private readonly setup;
+    private readonly index;
+    private readonly definition;
+    private output;
+    private previousStatus;
+    private readonly outputEvent;
+    private readonly statusEvent;
+    readonly onOutput: (listener: (value: string) => void) => {
+        dispose: () => boolean;
+    };
+    readonly onStatusChange: (listener: (value: StepState) => void) => {
+        dispose: () => boolean;
+    };
+    constructor(setup: Setup, index: number, definition: {
+        name: string;
+        command: string;
+    });
+    get name(): string;
+    get command(): string;
+    get status(): StepState;
+    refresh(): Promise<void>;
+    open(dimensions?: {
+        cols: number;
+        rows: number;
+    }): Promise<string>;
+    waitUntilComplete(): Promise<void>;
+}