beachside 0.0.0 → 0.9.0

package/dist/adapter-reference.d.ts

@@ -0,0 +1,268 @@
+import { z } from "zod";
+export declare const CaptureExpectation: z.ZodObject<{
+    profile: z.ZodObject<{
+        id: z.ZodString;
+        preserve: z.ZodEnum<{
+            filesystem: "filesystem";
+            "filesystem+memory": "filesystem+memory";
+        }>;
+        sourceStates: z.ZodArray<z.ZodEnum<{
+            unknown: "unknown";
+            creating: "creating";
+            running: "running";
+            stopped: "stopped";
+            suspended: "suspended";
+            restoring: "restoring";
+            destroying: "destroying";
+            destroyed: "destroyed";
+        }>>;
+        interruption: z.ZodEnum<{
+            none: "none";
+            stop: "stop";
+            pause: "pause";
+            terminate: "terminate";
+        }>;
+        sourceAfter: z.ZodEnum<{
+            stopped: "stopped";
+            destroyed: "destroyed";
+            unchanged: "unchanged";
+        }>;
+        connections: z.ZodEnum<{
+            unknown: "unknown";
+            preserved: "preserved";
+            dropped: "dropped";
+        }>;
+        consistency: z.ZodEnum<{
+            unknown: "unknown";
+            "crash-consistent": "crash-consistent";
+            "caller-quiesced": "caller-quiesced";
+        }>;
+        restoreExecution: z.ZodEnum<{
+            resume: "resume";
+            fresh: "fresh";
+        }>;
+        mountHandling: z.ZodEnum<{
+            none: "none";
+            unknown: "unknown";
+            excluded: "excluded";
+        }>;
+        minimumRetentionSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+    sourceState: z.ZodEnum<{
+        unknown: "unknown";
+        creating: "creating";
+        running: "running";
+        stopped: "stopped";
+        suspended: "suspended";
+        restoring: "restoring";
+        destroying: "destroying";
+        destroyed: "destroyed";
+    }>;
+}, z.core.$strict>;
+export declare const ReferenceSchema: z.ZodObject<{
+    version: z.ZodLiteral<2>;
+    mode: z.ZodLiteral<"direct">;
+    provider: z.ZodString;
+    kind: z.ZodEnum<{
+        create: "create";
+        destroy: "destroy";
+        exec: "exec";
+        file_write: "file_write";
+        file_mkdir: "file_mkdir";
+        file_remove: "file_remove";
+        image_build: "image_build";
+        image_delete: "image_delete";
+        sandbox_suspend: "sandbox_suspend";
+        sandbox_resume: "sandbox_resume";
+        sandbox_renew: "sandbox_renew";
+        snapshot_capture: "snapshot_capture";
+        snapshot_restore: "snapshot_restore";
+        snapshot_delete: "snapshot_delete";
+        volume_create: "volume_create";
+        volume_delete: "volume_delete";
+    }>;
+    scope: z.ZodObject<{
+        authority: z.ZodObject<{
+            kind: z.ZodString;
+            id: z.ZodString;
+        }, z.core.$strict>;
+        partition: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    operationId: z.ZodString;
+    submissionId: z.ZodString;
+    invocationKey: z.ZodString;
+    sandboxId: z.ZodOptional<z.ZodString>;
+    sandboxReference: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        provider: z.ZodString;
+        scope: z.ZodObject<{
+            authority: z.ZodObject<{
+                kind: z.ZodString;
+                id: z.ZodString;
+            }, z.core.$strict>;
+            partition: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>;
+        nativeId: z.ZodString;
+        generation: z.ZodOptional<z.ZodString>;
+        ownership: z.ZodEnum<{
+            unknown: "unknown";
+            borrowed: "borrowed";
+            "verified-created": "verified-created";
+        }>;
+        history: z.ZodOptional<z.ZodJSONSchema>;
+        receipt: z.ZodOptional<z.ZodString>;
+        kind: z.ZodLiteral<"sandbox">;
+    }, z.core.$strict>>;
+    lifecycle: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        action: z.ZodLiteral<"suspend">;
+        preserve: z.ZodEnum<{
+            filesystem: "filesystem";
+            "filesystem+memory": "filesystem+memory";
+        }>;
+    }, z.core.$strict>, z.ZodObject<{
+        action: z.ZodLiteral<"resume">;
+        forSeconds: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>], "action">>;
+    renewal: z.ZodOptional<z.ZodObject<{
+        forSeconds: z.ZodNumber;
+    }, z.core.$strict>>;
+    capture: z.ZodOptional<z.ZodObject<{
+        profile: z.ZodObject<{
+            id: z.ZodString;
+            preserve: z.ZodEnum<{
+                filesystem: "filesystem";
+                "filesystem+memory": "filesystem+memory";
+            }>;
+            sourceStates: z.ZodArray<z.ZodEnum<{
+                unknown: "unknown";
+                creating: "creating";
+                running: "running";
+                stopped: "stopped";
+                suspended: "suspended";
+                restoring: "restoring";
+                destroying: "destroying";
+                destroyed: "destroyed";
+            }>>;
+            interruption: z.ZodEnum<{
+                none: "none";
+                stop: "stop";
+                pause: "pause";
+                terminate: "terminate";
+            }>;
+            sourceAfter: z.ZodEnum<{
+                stopped: "stopped";
+                destroyed: "destroyed";
+                unchanged: "unchanged";
+            }>;
+            connections: z.ZodEnum<{
+                unknown: "unknown";
+                preserved: "preserved";
+                dropped: "dropped";
+            }>;
+            consistency: z.ZodEnum<{
+                unknown: "unknown";
+                "crash-consistent": "crash-consistent";
+                "caller-quiesced": "caller-quiesced";
+            }>;
+            restoreExecution: z.ZodEnum<{
+                resume: "resume";
+                fresh: "fresh";
+            }>;
+            mountHandling: z.ZodEnum<{
+                none: "none";
+                unknown: "unknown";
+                excluded: "excluded";
+            }>;
+            minimumRetentionSeconds: z.ZodOptional<z.ZodNumber>;
+        }, z.core.$strict>;
+        sourceState: z.ZodEnum<{
+            unknown: "unknown";
+            creating: "creating";
+            running: "running";
+            stopped: "stopped";
+            suspended: "suspended";
+            restoring: "restoring";
+            destroying: "destroying";
+            destroyed: "destroyed";
+        }>;
+    }, z.core.$strict>>;
+    resource: z.ZodOptional<z.ZodObject<{
+        version: z.ZodLiteral<1>;
+        kind: z.ZodEnum<{
+            sandbox: "sandbox";
+            image: "image";
+            snapshot: "snapshot";
+            volume: "volume";
+            "volume-version": "volume-version";
+            mount: "mount";
+            session: "session";
+        }>;
+        provider: z.ZodString;
+        scope: z.ZodObject<{
+            authority: z.ZodObject<{
+                kind: z.ZodString;
+                id: z.ZodString;
+            }, z.core.$strict>;
+            partition: z.ZodRecord<z.ZodString, z.ZodString>;
+        }, z.core.$strict>;
+        nativeId: z.ZodString;
+        generation: z.ZodOptional<z.ZodString>;
+        ownership: z.ZodEnum<{
+            unknown: "unknown";
+            borrowed: "borrowed";
+            "verified-created": "verified-created";
+        }>;
+        history: z.ZodOptional<z.ZodJSONSchema>;
+        receipt: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    mounts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        volume: z.ZodObject<{
+            version: z.ZodLiteral<1>;
+            kind: z.ZodEnum<{
+                sandbox: "sandbox";
+                image: "image";
+                snapshot: "snapshot";
+                volume: "volume";
+                "volume-version": "volume-version";
+                mount: "mount";
+                session: "session";
+            }>;
+            provider: z.ZodString;
+            scope: z.ZodObject<{
+                authority: z.ZodObject<{
+                    kind: z.ZodString;
+                    id: z.ZodString;
+                }, z.core.$strict>;
+                partition: z.ZodRecord<z.ZodString, z.ZodString>;
+            }, z.core.$strict>;
+            nativeId: z.ZodString;
+            generation: z.ZodOptional<z.ZodString>;
+            ownership: z.ZodEnum<{
+                unknown: "unknown";
+                borrowed: "borrowed";
+                "verified-created": "verified-created";
+            }>;
+            history: z.ZodOptional<z.ZodJSONSchema>;
+            receipt: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+        path: z.ZodString;
+        access: z.ZodDefault<z.ZodEnum<{
+            "read-write": "read-write";
+            "read-only": "read-only";
+        }>>;
+        subpath: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>>;
+    networkPolicy: z.ZodOptional<z.ZodString>;
+    fileMutation: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        recursive: z.ZodBoolean;
+    }, z.core.$strict>>;
+    file: z.ZodOptional<z.ZodObject<{
+        path: z.ZodString;
+        bytes: z.ZodNumber;
+    }, z.core.$strict>>;
+    maxOutputBytes: z.ZodOptional<z.ZodNumber>;
+    tokenVersion: z.ZodOptional<z.ZodNumber>;
+    token: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$strict>;
+export type AdapterRecoveryReference = z.infer<typeof ReferenceSchema>;

package/dist/bound.d.ts

@@ -0,0 +1 @@
+export { bindAdapter, type BoundAdapter } from "@beachside/adapter";

package/dist/connection-wait.d.ts

@@ -0,0 +1,10 @@
+/** Local connection setup controls; this signal does not own a returned client. */
+export type ConnectionWaitOptions = {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+};
+export type CloseOptions = ConnectionWaitOptions;
+export declare function connectionBudget(options: ConnectionWaitOptions, phase: "connect" | "close"): {
+    signal: AbortSignal;
+    dispose(): void;
+};

package/dist/directory-read.d.ts

@@ -0,0 +1,8 @@
+import { type FileEntry, type ReadContext } from "@beachside/adapter";
+import { type ReadOptions } from "./resource.js";
+export declare function directoryResult(result: import("@beachside/adapter").DirectoryResult): import("@beachside/adapter").DirectoryResult;
+export declare function directoryEntries(entries: FileEntry[]): FileEntry[];
+/** One deadline bounds the complete read, including adapter dispatch. */
+export declare function directoryRead<T>(read: (context: ReadContext) => Promise<T>, closed: AbortSignal, options: ReadOptions): Promise<T>;
+/** Native enumeration capacity is the same output-bound failure as a local listing limit. */
+export declare function directoryListingRead<T>(read: (context: ReadContext) => Promise<T>, closed: AbortSignal, options: ReadOptions): Promise<T>;

package/dist/file-read.d.ts

@@ -0,0 +1,4 @@
+import { type ReadContext } from "@beachside/adapter";
+import { type ReadOptions } from "./resource.js";
+/** One local deadline covers both adapter dispatch and every streamed chunk. */
+export declare function readFileBytes(read: (context: ReadContext) => Promise<Uint8Array | ReadableStream<Uint8Array>>, maxBytes: number, closed: AbortSignal, options: ReadOptions): Promise<Uint8Array>;

package/dist/file-transfer.d.ts

@@ -0,0 +1,35 @@
+import { AdapterFilesystemError, type ReadContext, type FileTransferContext } from "@beachside/adapter";
+import { BeachsideError } from "./resource.js";
+export type TransferPolicy = {
+    setupTimeoutMs?: number;
+    inactivityTimeoutMs?: number;
+    overallTimeoutMs?: number;
+};
+export type FileReadOptions = {
+    signal?: AbortSignal;
+    maxBytes?: number;
+};
+export type FileStreamOptions = FileReadOptions & TransferPolicy;
+export type FileWriteOptions = FileReadOptions & {
+    overwrite?: boolean;
+};
+export type FileStreamWriteOptions = FileStreamOptions & {
+    overwrite?: boolean;
+};
+export declare class FilesystemError extends BeachsideError {
+    readonly details: AdapterFilesystemError["details"];
+    constructor(code: string, message: string, details: AdapterFilesystemError["details"]);
+}
+export declare function filesystemError(error: unknown): Error;
+export declare function byteLimit(value: number | undefined, defaultValue?: number): number | undefined;
+/**
+ * The effective limit of one buffered adapter read or write: the caller's optional `maxBytes`
+ * guard, bounded by the adapter's own buffered limit. Larger files use the adapter's streams.
+ */
+export declare function bufferedLimit(value: number | undefined, adapterLimit: number): number;
+/** The error for a file larger than an adapter without file streams can move in one call. */
+export declare function adapterFileLimit(adapterLimit: number, code: "CAPACITY" | "OUTPUT_CAPACITY"): BeachsideError;
+export declare function streamFile(read: (ctx: ReadContext) => Promise<ReadableStream<Uint8Array>>, closed: AbortSignal, options: FileStreamOptions, defaults: TransferPolicy): AsyncIterable<Uint8Array>;
+export declare function writeStream(write: (bytes: AsyncIterable<Uint8Array>, ctx: FileTransferContext) => Promise<{
+    bytesWritten: number;
+}>, source: AsyncIterable<Uint8Array>, closed: AbortSignal, options: FileStreamOptions, defaults: TransferPolicy, retain?: FileTransferContext["retain"]): Promise<number>;

package/dist/filesystem-extensions.d.ts

@@ -0,0 +1,21 @@
+import type { DirectoryResult, FileEntry } from "@beachside/adapter";
+import { type FileStreamOptions } from "./file-transfer.js";
+import { type ReadOptions } from "./resource.js";
+export type WalkFilesOptions = ReadOptions & {
+    maxDepth?: number;
+    maxEntries?: number;
+    /** Exact root-relative paths to omit, including their descendants. */
+    exclude?: readonly string[];
+};
+export type WalkFileEntry = FileEntry & {
+    path: string;
+    relativePath: string;
+    /** Immediate children have depth 1; the root is not emitted. */
+    depth: number;
+};
+export type ReadTextLinesOptions = FileStreamOptions & {
+    /** UTF-8 bytes per line, excluding LF and its preceding CR; defaults to 1 MiB. */
+    maxLineBytes?: number;
+};
+export declare function walkFiles(root: string, read: (path: string) => Promise<DirectoryResult>, check: () => void, options: WalkFilesOptions): AsyncIterable<WalkFileEntry>;
+export declare function readTextLines(source: AsyncIterable<Uint8Array>, check: () => void, options: ReadTextLinesOptions): AsyncIterable<string>;

package/dist/freeze-reference.d.ts

@@ -0,0 +1 @@
+export declare function freezeReference<T extends object>(value: T): T;

package/dist/index.d.ts

@@ -0,0 +1,25 @@
+import { connectDirect } from "./adapter-direct.js";
+export type { StartProcessInput, ProcessOutput, ProcessOutputBytes, ProcessOutputFormat, ProcessChunk, ProcessExit, ProcessStatus, ProcessTermination, ProcessHandle, ProcessReference, ProcessSignal, TerminalDimensions, StartTerminalInput, TerminalHandle, ProcessFailure, ExecOptions, } from "./processes.js";
+export { AdapterDirectClient, AdapterSandbox, AdapterOperation, PreparedAdapterAttempt, ADAPTER_CONTRACT_VERSION, } from "./adapter-direct.js";
+export type { AdapterRecoveryReference, AdapterConnectOptions, DirectConnectOptions, ConnectOptions, CloseOptions, AdapterCapabilities, RecoveredOperation, AdvancedOperationResult, AdvancedOperationKind, AdvancedIdentity, AdvancedObservation, SandboxInfo, } from "./adapter-direct.js";
+export declare const Beachside: {
+    connect: typeof connectDirect;
+};
+export { Image, outputText, BeachsideError, UnsupportedFeatureError, OutcomeUnknownError, WaitAbortedError, NonzeroExitError, NoExitCodeError, } from "./resource.js";
+export type { ImageInput, PreparedImage, ImageBuildResult, CreateInput, NetworkPolicy, ExecInput, ExecStdinStream, ExecOutput, OutputPreview, DirectBeachsideClient, DirectSandboxHandle, SandboxHandle, SnapshotHandle, ImageHandle, VolumeHandle, ReadOptions, OperationHandle, RecoveryReference, BeachsideClient, } from "./resource.js";
+export { ResourceReference, ResourceKind, validateResourceReference, assertResourceScope, assertResourceIdentity, SnapshotRequest, SnapshotRequirements, Preserve, } from "@beachside/adapter";
+export type { Support, Capabilities, DirectCapabilities, OperationOutcome, SnapshotPlan, SnapshotProfile, SandboxState, SandboxReference, SuspendResult, ResumeResult, RenewRequest, RenewResult, Preview, Fact, Deadline, ResourceMinimums, SandboxResources, CreatePlan, } from "@beachside/adapter";
+export { AdapterSnapshot, AdapterVolume, AdapterImage } from "./resources.js";
+export type { SnapshotResult, WaitOptions, RestoreInput, SandboxList, SandboxListEntry, SandboxListInput, } from "./resources.js";
+export { MountSpec, SnapshotInfo, ImageInfo, VolumeInfo, RestoreRequest, VolumeCreateInput, ArtifactDeletionResult, } from "@beachside/adapter";
+export type { MountCapabilities, VolumeCapabilities, RestoreCapabilities, } from "@beachside/adapter";
+export { diagnosticContext } from "./observability.js";
+export type { ObservabilityOptions, DiagnosticContext } from "./observability.js";
+export { FilesystemError } from "./file-transfer.js";
+export type { FileReadOptions, FileWriteOptions, FileStreamOptions, FileStreamWriteOptions, TransferPolicy, } from "./file-transfer.js";
+export type { FileEntry, DirectoryResult, FileStat } from "@beachside/adapter";
+export type { WalkFilesOptions, WalkFileEntry, ReadTextLinesOptions, } from "./filesystem-extensions.js";
+export { createProcessTail, readProcessLines } from "./process-output.js";
+export type { ProcessTail, ProcessTailOptions, ProcessLine, ProcessLineOptions, } from "./process-output.js";
+export { SandboxCleanupError } from "./scoped-sandbox.js";
+export type { SandboxScopeOptions, SandboxScopeCallbackOutcome } from "./scoped-sandbox.js";