tensorlake 0.5.77 → 0.5.88

package/dist/index.d.ts

@@ -40,6 +40,8 @@ interface TracedJson {
 interface TracedBytes {
     traceId: string;
     data: Buffer;
+    contentId?: string;
+    fullSize?: number;
 }
 interface TracedEvents {
     traceId: string;
@@ -103,6 +105,50 @@ interface NativeSandboxClient {
     connectProxy(proxyUrl: string, sandboxId: string, routingHint?: string | null, requestTimeoutSec?: number | null): NativeSandboxProxyClient;
     selectSandboxProxyUrl(sandboxId: string, sandboxUrl?: string | null, ingressEndpoint?: string | null, explicitProxyUrl?: string | null): string;
 }
+interface NativeRepositoryClient {
+    gitRepoUrl(repo: string): string;
+    createRepo(repo: string, defaultBranch?: string | null): Promise<TracedJson>;
+    listRepos(): Promise<TracedJson>;
+    deleteRepo(repo: string): Promise<string>;
+    forkRepo(repo: string, baseRepo: string): Promise<TracedJson>;
+    archiveRepo(repo: string): Promise<string>;
+    restoreRepo(repo: string): Promise<string>;
+    repoInfo(repo: string): Promise<TracedJson>;
+    listBranches(repo: string): Promise<TracedJson>;
+    listRefs(repo: string): Promise<TracedJson>;
+    deleteBranch(repo: string, branch: string): Promise<string>;
+    listOperations(repo: string): Promise<TracedJson>;
+    gitCredential(repo?: string | null): Promise<string>;
+    commitStatus(repo: string, jobId: string): Promise<TracedJson>;
+    pushWorktree(repo: string, root: string, branch: string, message: string, expectOid?: string | null): Promise<TracedJson>;
+    mergeRepo(repo: string, ours: string, theirs: string, preflight: boolean, deep: boolean, materialize: boolean, message?: string | null, base?: string | null): Promise<TracedJson>;
+    commitConflicts(repo: string, commit: string): Promise<TracedJson>;
+    createFilesystem(name: string): Promise<string>;
+    forkFilesystem(name: string, base: string, snapshot?: string | null): Promise<TracedJson>;
+    listFilesystems(): Promise<TracedJson>;
+    filesystemMeta(name: string): Promise<TracedJson>;
+    deleteFilesystem(name: string): Promise<string>;
+    filesystemRefStatus(name: string, refspec: string): Promise<TracedJson>;
+    retainFilesystemSnapshot(name: string, message: string, requestId: string): Promise<TracedJson>;
+    listFilesystemSnapshots(name: string): Promise<TracedJson>;
+    deleteFilesystemSnapshot(name: string, snapshot: string): Promise<string>;
+    readFilesystemFile(name: string, path: string, version: string, offset?: number, length?: number): Promise<TracedBytes>;
+    listFilesystemTree(name: string, dirPath: string, version: string): Promise<TracedJson>;
+    pushFilesystemFiles(name: string, files: Array<{
+        path: string;
+        content: Buffer;
+    }>, deletes: string[], moves: Array<{
+        from: string;
+        to: string;
+    }>, copies: Array<{
+        from: string;
+        to: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+    pushFilesystemPaths(name: string, files: Array<{
+        path: string;
+        localPath: string;
+    }>, message: string, branch: string, idempotencyKey?: string | null): Promise<TracedJson>;
+}
 
 declare enum SandboxStatus {
     PENDING = "pending",
@@ -1440,6 +1486,295 @@ declare function listFileSystems(): Promise<FileSystem[]>;
 /** Delete a registered file system by its id (e.g. `file_system_...`). */
 declare function deleteFileSystem(fileSystemId: string): Promise<void>;
 
+/** One filesystem as returned by listing/point-read endpoints. */
+interface FilesystemInfo {
+    name: string;
+    fullName: string;
+    status: string;
+    kind: string;
+}
+/** Remote status of a filesystem: identity plus current head. */
+interface FilesystemStatus {
+    name: string;
+    status: string;
+    /**
+     * Current native version id; null for an empty filesystem that has never
+     * been written to.
+     */
+    versionId: string | null;
+    /** Server-side movement counter for the live version, when reported. */
+    generation: number | null;
+}
+/** One directory entry from a filesystem listing. */
+interface FileEntry {
+    name: string;
+    /** Path of the entry relative to the filesystem root. */
+    path: string;
+    /** Stable native content identity for the file or directory. */
+    contentId: string;
+    /** Native entry kind. */
+    kind: "file" | "directory" | "symlink";
+    /** Whether a regular file is executable. */
+    executable: boolean;
+    /** Blob size in bytes when cheaply known server-side. */
+    size: number | null;
+    isDir: boolean;
+    isSymlink: boolean;
+}
+/** Bytes plus immutable identity/size returned by one file request. */
+interface FilesystemFileRead {
+    data: Uint8Array;
+    /** Stable native identity for the complete file content. */
+    contentId: string;
+    /** Size of the complete file, even when `data` is a requested range. */
+    size: number;
+}
+interface FilesystemReadOptions {
+    /** Current `main` head when omitted; otherwise one retained snapshot id. */
+    version?: string;
+    /** Half-open byte selection expressed as offset + length. */
+    range?: {
+        offset: number;
+        length: number;
+    };
+}
+/** The durable live version produced by one atomic filesystem publication. */
+interface FilesystemVersion {
+    /** Native version id — pass as `version` to read the filesystem at this point. */
+    versionId: string;
+    /** Version replaced by this publication, or null for the first publication. */
+    previousVersionId: string | null;
+    /** False when the write was a no-op (content identical to the parent). */
+    created: boolean;
+    message: string;
+}
+/** One newly retained native filesystem snapshot. */
+interface FilesystemSnapshot {
+    id: string;
+    message: string;
+}
+/** One explicitly retained native filesystem snapshot. */
+interface FilesystemSnapshotInfo {
+    id: string;
+    createdAt: Date;
+    message: string;
+}
+/**
+ * Status of a local mount as reported by `tl fs status --json`.
+ *
+ * The mount daemon's JSON is versioned independently of this SDK, so only
+ * stable fields are typed; the full payload is preserved in `raw`.
+ */
+interface MountStatus {
+    /** Local mount path. */
+    path: string;
+    /** Filesystem name this mount serves, when reported. */
+    filesystem: string | null;
+    /** Whether the daemon reports the mount as healthy/active. */
+    mounted: boolean;
+    /** Complete parsed JSON payload from the CLI. */
+    raw: Record<string, unknown>;
+}
+declare class FilesystemError extends Error {
+    constructor(message: string);
+}
+declare class FilesystemNotFoundError extends FilesystemError {
+    readonly filesystemName: string;
+    constructor(name: string);
+}
+declare class FileNotFoundInFilesystemError extends FilesystemError {
+    readonly filesystem: string;
+    readonly path: string;
+    constructor(filesystem: string, path: string);
+}
+declare class FilesystemAPIError extends FilesystemError {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+declare class MountError extends FilesystemError {
+    constructor(message: string);
+}
+declare class CliNotFoundError extends MountError {
+    constructor(detail: string);
+}
+
+/**
+ * Client for Tensorlake filesystems.
+ *
+ * A filesystem is a durable, versioned file tree that lives in Tensorlake
+ * Cloud. Every write publishes a durable live version; {@link Filesystem.snapshot}
+ * retains the current version permanently. Files can be read at any retained
+ * version, and a filesystem can be mounted to a local path through the `tl`
+ * CLI's FUSE/FSKit daemon.
+ *
+ * Server-side SDK writes hash complete files locally, upload missing bytes
+ * directly to checksum-bound object-store targets, and atomically publish
+ * one durable snapshot. Payload bytes never transit the API service.
+ *
+ * @example
+ * const client = new FilesystemClient();   // env-based auth
+ * const fs = await client.create("my-data");
+ * await fs.writeFile("docs/hello.txt", "hi");
+ * console.log(await fs.readText("docs/hello.txt"));
+ * const snapshot = await fs.snapshot("after first write");
+ *
+ * const mount = await fs.mount("/mnt/my-data"); // requires the `tl` CLI
+ * // ... use it as a normal directory
+ * await mount.unmount();
+ */
+
+interface FilesystemClientOptions {
+    apiKey?: string;
+    apiUrl?: string;
+    organizationId?: string;
+    projectId?: string;
+    /** @internal Test seam: bypass the native binding loader. */
+    nativeClient?: NativeRepositoryClient;
+}
+/**
+ * Runs `tl fs ...` commands for local mount operations.
+ *
+ * Mounting a filesystem to a local path is served by a FUSE (Linux) / FSKit
+ * (macOS) daemon that ships only inside the Tensorlake CLI, so the SDK drives
+ * mounts by invoking `tl fs mount/unmount/snapshot/status`. Everything else
+ * goes through the Rust core and does not need the CLI.
+ */
+declare class FsCli {
+    private binary;
+    private readonly envOverrides;
+    constructor(envOverrides: Record<string, string>);
+    private findCli;
+    private run;
+    mount(filesystem: string, localPath: string, readonly: boolean): Promise<void>;
+    unmount(localPath: string, discard: boolean): Promise<void>;
+    snapshot(localPath: string, message?: string): Promise<void>;
+    status(localPath?: string): Promise<Record<string, unknown>>;
+}
+/** Manages the filesystems of one Tensorlake project. */
+declare class FilesystemClient {
+    private readonly native;
+    private readonly cli;
+    /**
+     * Any option left unset is resolved from the environment
+     * (`TENSORLAKE_API_KEY` / `TENSORLAKE_PAT`, `TENSORLAKE_API_URL`,
+     * `TENSORLAKE_ORGANIZATION_ID`, `TENSORLAKE_PROJECT_ID`).
+     */
+    constructor(options?: FilesystemClientOptions);
+    /** Create a new filesystem and return a handle to it. */
+    create(name: string): Promise<Filesystem>;
+    /**
+     * Fork a filesystem at its live head or an explicit retained snapshot.
+     * The server shares immutable content and publishes only metadata.
+     */
+    fork(name: string, baseFilesystem: string, snapshot?: string): Promise<Filesystem>;
+    /** Return a handle to an existing filesystem (verifies it exists). */
+    get(name: string): Promise<Filesystem>;
+    /** List all filesystems in the project. */
+    list(): Promise<FilesystemInfo[]>;
+    /** Permanently delete a filesystem and all its snapshots. */
+    delete(name: string): Promise<void>;
+    /** Mount a filesystem to a local path (requires the `tl` CLI). */
+    mount(name: string, localPath: string, readonly?: boolean): Promise<FilesystemMount>;
+    /**
+     * Unmount a locally mounted filesystem.
+     *
+     * `discard: true` drops local changes that were not yet uploaded.
+     */
+    unmount(localPath: string, discard?: boolean): Promise<void>;
+    /** Status of a local mount (defaults to the mount containing CWD). */
+    mountStatus(localPath?: string): Promise<MountStatus>;
+}
+type FileData = Uint8Array | string;
+/** Handle to one filesystem; reads/writes go through the Rust core. */
+declare class Filesystem {
+    private readonly client;
+    private readonly native;
+    private readonly cli;
+    readonly name: string;
+    private defaultBranch;
+    /** @internal — obtain instances via `FilesystemClient.create()` / `.get()`. */
+    constructor(client: FilesystemClient, native: NativeRepositoryClient, cli: FsCli, name: string, defaultBranch?: string | null);
+    /**
+     * The filesystem's default branch — the target of every write and the
+     * default version of every read, so writes and `status()` can never
+     * silently disagree on a non-"main" filesystem.
+     */
+    private branch;
+    /** Write one file. Returns the snapshot (version) the write produced. */
+    writeFile(path: string, data: FileData, message?: string): Promise<FilesystemVersion>;
+    /** Write several files (and/or delete paths) in one atomic snapshot. */
+    writeFiles(files: Map<string, FileData> | Record<string, FileData>, message?: string, deletes?: string[]): Promise<FilesystemVersion>;
+    /**
+     * Stream one local file directly to object storage in bounded parts.
+     * This is the memory-bounded API for multi-GiB files.
+     */
+    writeFileFromPath(path: string, localPath: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Atomically publish local files without loading their complete payloads
+     * into JavaScript or Rust memory.
+     */
+    writeFilesFromPaths(files: Map<string, string> | Record<string, string>, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Move a file or directory without downloading or re-uploading its bytes.
+     * The source removal and destination creation publish as one atomic snapshot.
+     */
+    moveFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Copy a file or directory by reusing immutable content references. No
+     * payload bytes traverse the client, API server, or object store.
+     */
+    copyFile(from: string, to: string, message?: string): Promise<FilesystemVersion>;
+    private publishChanges;
+    /** Delete one file. Returns the durable version the deletion produced. */
+    deleteFile(path: string, message?: string): Promise<FilesystemVersion>;
+    /**
+     * Return the filesystem's current version as a snapshot.
+     *
+     * Writes publish durable live versions. This retains the current head
+     * permanently in one metadata-only server operation without changing or
+     * copying any content.
+     */
+    snapshot(message?: string): Promise<FilesystemSnapshot>;
+    /** List explicitly retained snapshots without reading filesystem contents. */
+    listSnapshots(): Promise<FilesystemSnapshotInfo[]>;
+    /** Delete one permanent retention point; shared/head-reachable bytes remain. */
+    deleteSnapshot(snapshot: string): Promise<void>;
+    /**
+     * Read a file's bytes at `version` (the current `main` head or a retained
+     * snapshot id; defaults to the filesystem's current head).
+     */
+    readFile(path: string, version?: string): Promise<Uint8Array>;
+    /**
+     * Read bytes and immutable metadata in one request. A range is executed by
+     * Artifact Storage, so callers never download the unrequested remainder.
+     */
+    readFileWithMetadata(path: string, options?: FilesystemReadOptions): Promise<FilesystemFileRead>;
+    /** Read a file as UTF-8 text at `version`. Throws on non-UTF-8 content. */
+    readText(path: string, version?: string): Promise<string>;
+    /** List one directory (non-recursive) at `version`. */
+    listFiles(dirPath?: string, version?: string): Promise<FileEntry[]>;
+    /** Remote status: identity plus the current native version. */
+    status(): Promise<FilesystemStatus>;
+    /** Mount this filesystem to a local path (requires the `tl` CLI). */
+    mount(localPath: string, readonly?: boolean): Promise<FilesystemMount>;
+}
+/** A filesystem mounted to a local path via the `tl` CLI daemon. */
+declare class FilesystemMount {
+    private readonly client;
+    private readonly cli;
+    readonly filesystem: string;
+    readonly path: string;
+    readonly readonly: boolean;
+    /** @internal — obtain instances via `FilesystemClient.mount()`. */
+    constructor(client: FilesystemClient, cli: FsCli, filesystem: string, path: string, readonly: boolean);
+    /** Flush pending local changes into a durable snapshot. */
+    snapshot(message?: string): Promise<void>;
+    /** Local mount status as reported by the mount daemon. */
+    status(): Promise<MountStatus>;
+    /** Unmount; `discard: true` drops changes not yet uploaded. */
+    unmount(discard?: boolean): Promise<void>;
+}
+
 /**
  * Build a public sandbox URL from a server-provided ingress endpoint.
  *
@@ -1509,4 +1844,4 @@ declare class RequestExecutionError extends Error {
     constructor(message: string, functionName?: string);
 }
 
-export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, FileSystem, type FileSystemMount, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };
+export { APIClient, ApiKeyIntrospection, ApplicationBuildContext, ApplicationBuildResponse, ApplicationManifest, ApplicationSummary, type ArchivedSandboxInfo, BinaryPayload, type Branch, BuildInfo, BuildLogEntry, type CheckpointOptions, type CheckpointType, CliNotFoundError, CloudClient, CloudClientOptions, type CommandResult, type CommitJobError, type CommitJobReadBack, type CommitJobStatus, type ConflictPath, type ConflictTerm, type ConnectDesktopOptions, type ConnectOptions, type ContainerResourcesInfo, ContainerState, type CopiedSandboxResponse, type CopySandboxOptions, type CopySandboxResponse, type CreateAndConnectOptions, CreateApplicationBuildRequest, type CreatePoolOptions, type CreatePtyOptions, type CreatePtySessionOptions, type CreateSandboxOptions, type CreateSandboxPoolResponse, type CreateSandboxResponse, type CreateSnapshotResponse, type CreateTunnelOptions, type DaemonInfo, Desktop, type DesktopDoubleClickOptions, type DesktopPointerOptions, type DirectoryEntry, type FileEntry, FileNotFoundInFilesystemError, FileSystem, type FileSystemMount, Filesystem, FilesystemAPIError, FilesystemClient, type FilesystemClientOptions, FilesystemError, type FilesystemFileRead, type FilesystemInfo, FilesystemMount, FilesystemNotFoundError, type FilesystemReadOptions, type FilesystemSnapshot, type FilesystemSnapshotInfo, type FilesystemStatus, type FilesystemVersion, type GPUResources, type GetSandboxLogsOptions, type GitCredential, type GitRef, type GitRepository, type HealthResponse, type ListArchivedSandboxesOptions, type ListArchivedSandboxesResponse, type ListDirectoryResponse, type ManagedProcessExit, type ManagedProcessHealthStatus, type ManagedProcessInfo, type ManagedProcessStatus, type MergeConflict, type MergeConflictRecord, type MergeEntry, type MergeOptions, type MergeReport, type MergeStats, MountError, type MountStatus, type MouseButton, type NetworkConfig, NewSecret, type Operation, type OperationRef, type OutputEvent, OutputMode, type OutputResponse, type PoolContainerInfo, PoolInUseError, PoolNotFoundError, type ProcessHealthCheck, type ProcessHealthCheckType, type ProcessInfo, ProcessStatus, type ProcessUser, type ProcessUserSpec, Pty, type PtyConnectionOptions, type PtyDataHandler, type PtyExitHandler, type PtySessionInfo, type PushReport, type PushWorktreeOptions, RemoteAPIError, RepositoryClient, type RepositoryClientOptions, type RepositoryHandle, type RepositoryInfo, RequestExecutionError, RequestFailedError, RequestInput, RequestMetadata, RequestNotFinishedError, RequestOutput, type RestartPolicy, type RestartPolicyConfig, type RunOptions, Sandbox, SandboxClient, type SandboxClientOptions, SandboxConnectionError, SandboxError, SandboxException, type SandboxInfo, type SandboxLogLevel, type SandboxLogSignal, type SandboxLogsResponse, SandboxNotFoundError, type SandboxOptions, type SandboxPoolInfo, type SandboxPortAccess, type SandboxProcessLogFilter, type SandboxProcessLogFiltersResponse, SandboxStatus, SandboxTemplate, Secret, SecretsList, type SendSignalResponse, type SnapshotAndWaitOptions, type SnapshotInfo, type SnapshotOptions, SnapshotStatus, type SnapshotType, type SnapshotWaitCondition, StartImageBuildRequest, type StartProcessOptions, StdinMode, type SuspendResumeOptions, TcpTunnel, type TunnelAddress, type UpdatePoolOptions, UpsertSecretResponse, createFileSystem, deleteFileSystem, listFileSystems, sandboxUrlFromIngressEndpoint };