tensorlake 0.5.77 → 0.5.88

package/dist/index.cjs

@@ -35,7 +35,7 @@ var SDK_VERSION, API_URL, API_KEY, NAMESPACE, SANDBOX_PROXY_URL, DEFAULT_HTTP_TI
 var init_defaults = __esm({
   "src/defaults.ts"() {
     "use strict";
-    SDK_VERSION = "0.5.77";
+    SDK_VERSION = "0.5.88";
     API_URL = process.env.TENSORLAKE_API_URL ?? "https://api.tensorlake.ai";
     API_KEY = process.env.TENSORLAKE_API_KEY ?? void 0;
     NAMESPACE = process.env.INDEXIFY_NAMESPACE ?? "default";
@@ -6153,11 +6153,20 @@ var init_sandbox_image = __esm({
 var index_exports = {};
 __export(index_exports, {
   APIClient: () => APIClient,
+  CliNotFoundError: () => CliNotFoundError,
   CloudClient: () => CloudClient,
   ContainerState: () => ContainerState,
   Desktop: () => Desktop,
+  FileNotFoundInFilesystemError: () => FileNotFoundInFilesystemError,
+  Filesystem: () => Filesystem,
+  FilesystemAPIError: () => FilesystemAPIError,
+  FilesystemClient: () => FilesystemClient,
+  FilesystemError: () => FilesystemError,
+  FilesystemMount: () => FilesystemMount,
+  FilesystemNotFoundError: () => FilesystemNotFoundError,
   Image: () => Image,
   ImageBuildOperationType: () => ImageBuildOperationType,
+  MountError: () => MountError,
   OutputMode: () => OutputMode,
   PoolInUseError: () => PoolInUseError,
   PoolNotFoundError: () => PoolNotFoundError,
@@ -6542,6 +6551,691 @@ async function deleteFileSystem(fileSystemId) {
   }
 }
 
+// src/filesystem.ts
+var import_node_child_process = require("child_process");
+var import_node_crypto2 = require("crypto");
+var import_node_fs2 = require("fs");
+var import_node_os2 = require("os");
+var import_node_path2 = require("path");
+var import_node_util2 = require("util");
+init_defaults();
+
+// src/filesystem-models.ts
+var GIT_MODE_DIR = 16384;
+var GIT_MODE_SYMLINK = 40960;
+function trimSlashes(path2) {
+  let start = 0;
+  let end = path2.length;
+  while (start < end && path2.charCodeAt(start) === 47) start += 1;
+  while (end > start && path2.charCodeAt(end - 1) === 47) end -= 1;
+  return path2.slice(start, end);
+}
+function fileEntryFromWire(entry, dirPath) {
+  const mode = entry.mode ?? 33188;
+  const prefix = trimSlashes(dirPath);
+  return {
+    name: entry.name,
+    path: prefix ? `${prefix}/${entry.name}` : entry.name,
+    contentId: entry.oid ?? "",
+    kind: mode === GIT_MODE_DIR ? "directory" : mode === GIT_MODE_SYMLINK ? "symlink" : "file",
+    executable: mode === 33261,
+    size: entry.size ?? null,
+    isDir: mode === GIT_MODE_DIR,
+    isSymlink: mode === GIT_MODE_SYMLINK
+  };
+}
+function mountStatusFromRaw(raw, localPath) {
+  const mounted = "mounted" in raw ? Boolean(raw.mounted) : "active" in raw ? Boolean(raw.active) : true;
+  const path2 = String(raw.path || raw.mount_path || localPath || "");
+  const filesystem = raw.filesystem || raw.file_system || null;
+  return { path: path2, filesystem, mounted, raw };
+}
+var FilesystemError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "FilesystemError";
+  }
+};
+var FilesystemNotFoundError = class extends FilesystemError {
+  filesystemName;
+  constructor(name) {
+    super(`Filesystem not found: ${name}`);
+    this.name = "FilesystemNotFoundError";
+    this.filesystemName = name;
+  }
+};
+var FileNotFoundInFilesystemError = class extends FilesystemError {
+  filesystem;
+  path;
+  constructor(filesystem, path2) {
+    super(`File not found in filesystem ${filesystem}: ${path2}`);
+    this.name = "FileNotFoundInFilesystemError";
+    this.filesystem = filesystem;
+    this.path = path2;
+  }
+};
+var FilesystemAPIError = class extends FilesystemError {
+  statusCode;
+  constructor(statusCode, message) {
+    super(`API error (status ${statusCode}): ${message}`);
+    this.name = "FilesystemAPIError";
+    this.statusCode = statusCode;
+  }
+};
+var MountError = class extends FilesystemError {
+  constructor(message) {
+    super(message);
+    this.name = "MountError";
+  }
+};
+var CliNotFoundError = class extends MountError {
+  constructor(detail) {
+    super(
+      `Mount operations require the Tensorlake CLI (\`tl\`) with \`tl fs\` support: ${detail}. Install or upgrade it with: curl -fsSL https://tensorlake.ai/install.sh | sh`
+    );
+    this.name = "CliNotFoundError";
+  }
+};
+
+// src/filesystem.ts
+init_native_sandbox();
+init_sandbox_image();
+var execFileAsync = (0, import_node_util2.promisify)(import_node_child_process.execFile);
+var FILESYSTEM_REPO_KIND = "filesystem";
+function translateNativeError2(error, notFound) {
+  const message = error instanceof Error ? error.message : String(error);
+  let payload;
+  try {
+    payload = JSON.parse(message);
+  } catch {
+    return error instanceof Error ? error : new FilesystemError(message);
+  }
+  if (!payload || typeof payload.category !== "string") {
+    return error instanceof Error ? error : new FilesystemError(message);
+  }
+  const detail = typeof payload.message === "string" ? payload.message : message;
+  if (payload.category === "connection") {
+    return new FilesystemError(detail);
+  }
+  if (payload.status === 404 && notFound !== void 0) {
+    return notFound;
+  }
+  if (typeof payload.status === "number") {
+    return new FilesystemAPIError(payload.status, detail);
+  }
+  return new FilesystemError(detail);
+}
+async function callNative2(fn, notFound) {
+  try {
+    return await fn();
+  } catch (error) {
+    throw translateNativeError2(error, notFound);
+  }
+}
+var FsCli = class {
+  binary = null;
+  envOverrides;
+  constructor(envOverrides) {
+    this.envOverrides = envOverrides;
+  }
+  async findCli() {
+    const candidates = [];
+    if (process.env.TENSORLAKE_CLI) {
+      candidates.push(process.env.TENSORLAKE_CLI);
+    }
+    candidates.push("tl");
+    const installed = (0, import_node_path2.join)((0, import_node_os2.homedir)(), ".tensorlake", "bin", "tl");
+    try {
+      (0, import_node_fs2.accessSync)(installed, import_node_fs2.constants.F_OK);
+      candidates.push(installed);
+    } catch {
+    }
+    let unsupported = null;
+    for (const candidate of candidates) {
+      try {
+        await execFileAsync(candidate, ["fs", "--help"], { timeout: 15e3 });
+        return candidate;
+      } catch (error) {
+        if (error.code !== "ENOENT") {
+          unsupported = candidate;
+        }
+      }
+    }
+    throw new CliNotFoundError(
+      unsupported ? `\`tl\` at ${unsupported} does not support \`tl fs\` (upgrade required)` : "`tl` was not found on PATH"
+    );
+  }
+  async run(args, timeoutMs = 3e5) {
+    if (this.binary === null) {
+      this.binary = await this.findCli();
+    }
+    try {
+      const { stdout } = await execFileAsync(this.binary, ["fs", ...args], {
+        timeout: timeoutMs,
+        env: { ...process.env, ...this.envOverrides },
+        maxBuffer: 16 * 1024 * 1024
+      });
+      return stdout;
+    } catch (error) {
+      const failure = error;
+      if (failure.killed) {
+        throw new MountError(`\`tl fs ${args[0]}\` timed out after ${timeoutMs}ms`);
+      }
+      const detail = (failure.stderr || failure.stdout || String(error)).trim();
+      throw new MountError(`\`tl fs ${args.join(" ")}\` failed: ${detail}`);
+    }
+  }
+  // Flags always precede a `--` end-of-options separator so caller-supplied
+  // names/paths can never be parsed as CLI flags (e.g. a path literally
+  // named "--discard" must stay a path, not become the destructive flag).
+  async mount(filesystem, localPath, readonly) {
+    const args = ["mount"];
+    if (readonly) args.push("--ro");
+    args.push("--", filesystem, localPath);
+    await this.run(args);
+  }
+  async unmount(localPath, discard) {
+    const args = ["unmount"];
+    if (discard) args.push("--discard");
+    args.push("--", localPath);
+    await this.run(args);
+  }
+  async snapshot(localPath, message) {
+    const args = ["snapshot"];
+    if (message) args.push(`--message=${message}`);
+    args.push("--", localPath);
+    await this.run(args);
+  }
+  async status(localPath) {
+    const args = ["status", "--json"];
+    if (localPath) args.push("--", localPath);
+    const output = await this.run(args, 6e4);
+    try {
+      const payload = JSON.parse(output);
+      return typeof payload === "object" && payload !== null ? payload : { status: payload };
+    } catch {
+      throw new MountError(
+        `\`tl fs status --json\` returned invalid JSON: ${output.slice(0, 200)}`
+      );
+    }
+  }
+};
+var FilesystemClient = class {
+  native;
+  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 = {}) {
+    const context = buildContextFromEnv();
+    const token = options.apiKey ?? context.apiKey ?? context.personalAccessToken;
+    if (!token) {
+      throw new FilesystemError(
+        "Missing TENSORLAKE_API_KEY or TENSORLAKE_PAT credentials."
+      );
+    }
+    const organizationId = options.organizationId ?? context.organizationId;
+    const projectId = options.projectId ?? context.projectId;
+    if (!organizationId || !projectId) {
+      throw new FilesystemError(
+        "Filesystem operations require organization and project context (TENSORLAKE_ORGANIZATION_ID and TENSORLAKE_PROJECT_ID)."
+      );
+    }
+    if (options.nativeClient) {
+      this.native = options.nativeClient;
+    } else {
+      const binding = loadNativeSandboxBinding();
+      if (typeof binding.NativeRepositoryClient !== "function") {
+        throw new FilesystemError(
+          "native binding does not export the repository client; rebuild with 'npm run build:native'"
+        );
+      }
+      this.native = new binding.NativeRepositoryClient(
+        options.apiUrl ?? context.apiUrl,
+        token,
+        organizationId,
+        projectId,
+        `tensorlake-typescript-sdk/${SDK_VERSION}`,
+        null
+      );
+    }
+    const envOverrides = {
+      TENSORLAKE_ORGANIZATION_ID: organizationId,
+      TENSORLAKE_PROJECT_ID: projectId,
+      // The CLI must target the same deployment the data plane does, or a
+      // mount could resolve a same-named filesystem in the wrong environment.
+      TENSORLAKE_API_URL: options.apiUrl ?? context.apiUrl
+    };
+    if (options.apiKey) {
+      envOverrides.TENSORLAKE_API_KEY = options.apiKey;
+    }
+    this.cli = new FsCli(envOverrides);
+  }
+  // -- lifecycle --------------------------------------------------------------
+  /** Create a new filesystem and return a handle to it. */
+  async create(name) {
+    if (typeof name !== "string") {
+      throw new TypeError("name must be a string");
+    }
+    if (name.length === 0) {
+      throw new FilesystemError("filesystem name must not be empty");
+    }
+    const raw = await callNative2(() => this.native.createFilesystem(name));
+    const created = JSON.parse(raw);
+    return new Filesystem(
+      this,
+      this.native,
+      this.cli,
+      name,
+      created.default_branch || "main"
+    );
+  }
+  /**
+   * Fork a filesystem at its live head or an explicit retained snapshot.
+   * The server shares immutable content and publishes only metadata.
+   */
+  async fork(name, baseFilesystem, snapshot) {
+    if (!name || !baseFilesystem) {
+      throw new FilesystemError(
+        "fork and base filesystem names must not be empty"
+      );
+    }
+    await callNative2(
+      () => this.native.forkFilesystem(
+        name,
+        baseFilesystem,
+        snapshot ?? null
+      ),
+      new FilesystemNotFoundError(baseFilesystem)
+    );
+    return new Filesystem(this, this.native, this.cli, name, "main");
+  }
+  /** Return a handle to an existing filesystem (verifies it exists). */
+  async get(name) {
+    const traced = await callNative2(
+      () => this.native.filesystemMeta(name),
+      new FilesystemNotFoundError(name)
+    );
+    const meta = JSON.parse(traced.json);
+    if ((meta.kind ?? FILESYSTEM_REPO_KIND) !== FILESYSTEM_REPO_KIND) {
+      throw new FilesystemNotFoundError(name);
+    }
+    return new Filesystem(
+      this,
+      this.native,
+      this.cli,
+      name,
+      meta.default_branch || "main"
+    );
+  }
+  /** List all filesystems in the project. */
+  async list() {
+    const traced = await callNative2(() => this.native.listFilesystems());
+    const page = JSON.parse(traced.json);
+    return (page.repos ?? []).map((repo) => ({
+      name: String(repo.name ?? ""),
+      fullName: String(repo.full_name ?? ""),
+      status: String(repo.status ?? ""),
+      kind: String(repo.kind ?? FILESYSTEM_REPO_KIND)
+    }));
+  }
+  /** Permanently delete a filesystem and all its snapshots. */
+  async delete(name) {
+    await callNative2(
+      () => this.native.deleteFilesystem(name),
+      new FilesystemNotFoundError(name)
+    );
+  }
+  // -- local mounts -------------------------------------------------------------
+  /** Mount a filesystem to a local path (requires the `tl` CLI). */
+  async mount(name, localPath, readonly = false) {
+    await this.cli.mount(name, localPath, readonly);
+    return new FilesystemMount(this, this.cli, name, localPath, readonly);
+  }
+  /**
+   * Unmount a locally mounted filesystem.
+   *
+   * `discard: true` drops local changes that were not yet uploaded.
+   */
+  async unmount(localPath, discard = false) {
+    await this.cli.unmount(localPath, discard);
+  }
+  /** Status of a local mount (defaults to the mount containing CWD). */
+  async mountStatus(localPath) {
+    return mountStatusFromRaw(await this.cli.status(localPath), localPath);
+  }
+};
+function toBuffer(data) {
+  return typeof data === "string" ? Buffer.from(data, "utf-8") : Buffer.from(data);
+}
+var Filesystem = class {
+  client;
+  native;
+  cli;
+  name;
+  defaultBranch;
+  /** @internal — obtain instances via `FilesystemClient.create()` / `.get()`. */
+  constructor(client, native, cli, name, defaultBranch = null) {
+    this.client = client;
+    this.native = native;
+    this.cli = cli;
+    this.name = name;
+    this.defaultBranch = defaultBranch;
+  }
+  /**
+   * 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.
+   */
+  async branch() {
+    if (!this.defaultBranch) {
+      const traced = await callNative2(
+        () => this.native.filesystemMeta(this.name),
+        new FilesystemNotFoundError(this.name)
+      );
+      const meta = JSON.parse(traced.json);
+      this.defaultBranch = meta.default_branch || "main";
+    }
+    return this.defaultBranch;
+  }
+  // -- writes -------------------------------------------------------------------
+  /** Write one file. Returns the snapshot (version) the write produced. */
+  async writeFile(path2, data, message) {
+    return await this.writeFiles(/* @__PURE__ */ new Map([[path2, data]]), message);
+  }
+  /** Write several files (and/or delete paths) in one atomic snapshot. */
+  async writeFiles(files, message, deletes = []) {
+    const entries = files instanceof Map ? [...files.entries()] : Object.entries(files);
+    if (entries.length === 0 && deletes.length === 0) {
+      throw new FilesystemError("nothing to write: no files or deletions given");
+    }
+    const writes = entries.map(([path2, data]) => ({
+      path: path2,
+      content: toBuffer(data)
+    }));
+    const resolvedMessage = message || `write ${writes.length} file(s) via SDK`;
+    return await this.publishChanges(
+      writes,
+      deletes,
+      [],
+      [],
+      resolvedMessage
+    );
+  }
+  /**
+   * Stream one local file directly to object storage in bounded parts.
+   * This is the memory-bounded API for multi-GiB files.
+   */
+  async writeFileFromPath(path2, localPath, message) {
+    return await this.writeFilesFromPaths(
+      /* @__PURE__ */ new Map([[path2, localPath]]),
+      message
+    );
+  }
+  /**
+   * Atomically publish local files without loading their complete payloads
+   * into JavaScript or Rust memory.
+   */
+  async writeFilesFromPaths(files, message) {
+    const entries = files instanceof Map ? [...files.entries()] : Object.entries(files);
+    if (entries.length === 0) {
+      throw new FilesystemError("nothing to write: no local files given");
+    }
+    const writes = entries.map(([path2, localPath]) => ({ path: path2, localPath }));
+    const resolvedMessage = message || `write ${writes.length} local file(s) via SDK`;
+    const branch = await this.branch();
+    const traced = await callNative2(
+      () => this.native.pushFilesystemPaths(
+        this.name,
+        writes,
+        resolvedMessage,
+        branch,
+        (0, import_node_crypto2.randomBytes)(16).toString("hex")
+      ),
+      new FilesystemNotFoundError(this.name)
+    );
+    const report = JSON.parse(traced.json);
+    const versionId = String(report.version_id ?? "");
+    const previousVersionId = report.previous_version_id == null ? null : String(report.previous_version_id);
+    return {
+      versionId,
+      previousVersionId,
+      created: previousVersionId !== versionId,
+      message: resolvedMessage
+    };
+  }
+  /**
+   * Move a file or directory without downloading or re-uploading its bytes.
+   * The source removal and destination creation publish as one atomic snapshot.
+   */
+  async moveFile(from, to, message) {
+    return await this.publishChanges(
+      [],
+      [],
+      [{ from, to }],
+      [],
+      message || `move ${from} to ${to} via SDK`
+    );
+  }
+  /**
+   * Copy a file or directory by reusing immutable content references. No
+   * payload bytes traverse the client, API server, or object store.
+   */
+  async copyFile(from, to, message) {
+    return await this.publishChanges(
+      [],
+      [],
+      [],
+      [{ from, to }],
+      message || `copy ${from} to ${to} via SDK`
+    );
+  }
+  async publishChanges(writes, deletes, moves, copies, message) {
+    const branch = await this.branch();
+    const traced = await callNative2(
+      () => this.native.pushFilesystemFiles(
+        this.name,
+        writes,
+        deletes,
+        moves,
+        copies,
+        message,
+        branch,
+        // One key per logical write: a retried submit reattaches to the
+        // same durable commit job instead of double-committing.
+        (0, import_node_crypto2.randomBytes)(16).toString("hex")
+      ),
+      new FilesystemNotFoundError(this.name)
+    );
+    const report = JSON.parse(traced.json);
+    const versionId = String(report.version_id ?? "");
+    const previousVersionId = report.previous_version_id == null ? null : String(report.previous_version_id);
+    return {
+      versionId,
+      previousVersionId,
+      created: previousVersionId !== versionId,
+      message
+    };
+  }
+  /** Delete one file. Returns the durable version the deletion produced. */
+  async deleteFile(path2, message) {
+    return await this.writeFiles(
+      /* @__PURE__ */ new Map(),
+      message || `delete ${path2} via SDK`,
+      [path2]
+    );
+  }
+  /**
+   * 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.
+   */
+  async snapshot(message = "snapshot via SDK") {
+    const resolvedMessage = message || "snapshot via SDK";
+    const traced = await callNative2(
+      () => this.native.retainFilesystemSnapshot(
+        this.name,
+        resolvedMessage,
+        (0, import_node_crypto2.randomBytes)(16).toString("hex")
+      ),
+      new FilesystemNotFoundError(this.name)
+    );
+    const retained = JSON.parse(traced.json);
+    return {
+      id: String(retained.snapshot_id ?? ""),
+      message: retained.message || resolvedMessage
+    };
+  }
+  /** List explicitly retained snapshots without reading filesystem contents. */
+  async listSnapshots() {
+    const traced = await callNative2(
+      () => this.native.listFilesystemSnapshots(this.name),
+      new FilesystemNotFoundError(this.name)
+    );
+    const payload = JSON.parse(traced.json);
+    return (payload.snapshots ?? []).map((snapshot) => ({
+      id: String(snapshot.snapshot_id ?? ""),
+      createdAt: new Date(Number(snapshot.created_at_ms ?? 0)),
+      message: String(snapshot.message ?? "")
+    }));
+  }
+  /** Delete one permanent retention point; shared/head-reachable bytes remain. */
+  async deleteSnapshot(snapshot) {
+    await callNative2(
+      () => this.native.deleteFilesystemSnapshot(this.name, snapshot),
+      new FilesystemNotFoundError(this.name)
+    );
+  }
+  // -- reads --------------------------------------------------------------------
+  /**
+   * Read a file's bytes at `version` (the current `main` head or a retained
+   * snapshot id; defaults to the filesystem's current head).
+   */
+  async readFile(path2, version) {
+    return (await this.readFileWithMetadata(path2, { version })).data;
+  }
+  /**
+   * Read bytes and immutable metadata in one request. A range is executed by
+   * Artifact Storage, so callers never download the unrequested remainder.
+   */
+  async readFileWithMetadata(path2, options = {}) {
+    if (trimSlashes(path2) === "") {
+      throw new FilesystemError("file path must not be empty");
+    }
+    const range = options.range;
+    if (range !== void 0 && (!Number.isSafeInteger(range.offset) || range.offset < 0 || !Number.isSafeInteger(range.length) || range.length <= 0)) {
+      throw new FilesystemError(
+        "range requires a non-negative integer offset and positive integer length"
+      );
+    }
+    const resolvedVersion = options.version || await this.branch();
+    const traced = await callNative2(
+      () => this.native.readFilesystemFile(
+        this.name,
+        path2,
+        resolvedVersion,
+        range?.offset,
+        range?.length
+      ),
+      new FileNotFoundInFilesystemError(this.name, path2)
+    );
+    const fullSize = traced.fullSize;
+    if (!traced.contentId || fullSize === void 0 || !Number.isSafeInteger(fullSize) || fullSize < 0 || traced.data.byteLength > fullSize) {
+      throw new FilesystemError(
+        "filesystem read response omitted content identity or total size"
+      );
+    }
+    return {
+      data: new Uint8Array(traced.data),
+      contentId: traced.contentId,
+      size: fullSize
+    };
+  }
+  /** Read a file as UTF-8 text at `version`. Throws on non-UTF-8 content. */
+  async readText(path2, version) {
+    return new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+      await this.readFile(path2, version)
+    );
+  }
+  /** List one directory (non-recursive) at `version`. */
+  async listFiles(dirPath = "", version) {
+    const resolvedVersion = version || await this.branch();
+    const traced = await callNative2(
+      () => this.native.listFilesystemTree(this.name, dirPath, resolvedVersion),
+      new FileNotFoundInFilesystemError(this.name, dirPath || "/")
+    );
+    const page = JSON.parse(traced.json);
+    return (page.entries ?? []).map((entry) => fileEntryFromWire(entry, dirPath));
+  }
+  // -- status -------------------------------------------------------------------
+  /** Remote status: identity plus the current native version. */
+  async status() {
+    const metaTraced = await callNative2(
+      () => this.native.filesystemMeta(this.name),
+      new FilesystemNotFoundError(this.name)
+    );
+    const meta = JSON.parse(metaTraced.json);
+    const defaultBranch = String(meta.default_branch || "main");
+    this.defaultBranch = defaultBranch;
+    let versionId = null;
+    let generation = null;
+    try {
+      const refTraced = await callNative2(
+        () => this.native.filesystemRefStatus(this.name, defaultBranch)
+      );
+      const ref = JSON.parse(refTraced.json);
+      versionId = ref.resolved_commit || ref.oid || null;
+      generation = typeof ref.generation === "number" ? ref.generation : null;
+    } catch (error) {
+      if (!(error instanceof FilesystemAPIError) || error.statusCode !== 404) {
+        throw error;
+      }
+    }
+    return {
+      name: this.name,
+      status: String(meta.status ?? ""),
+      versionId,
+      generation
+    };
+  }
+  // -- mounts -------------------------------------------------------------------
+  /** Mount this filesystem to a local path (requires the `tl` CLI). */
+  async mount(localPath, readonly = false) {
+    return await this.client.mount(this.name, localPath, readonly);
+  }
+};
+var FilesystemMount = class {
+  client;
+  cli;
+  filesystem;
+  path;
+  readonly;
+  /** @internal — obtain instances via `FilesystemClient.mount()`. */
+  constructor(client, cli, filesystem, path2, readonly) {
+    this.client = client;
+    this.cli = cli;
+    this.filesystem = filesystem;
+    this.path = path2;
+    this.readonly = readonly;
+  }
+  /** Flush pending local changes into a durable snapshot. */
+  async snapshot(message) {
+    await this.cli.snapshot(this.path, message);
+  }
+  /** Local mount status as reported by the mount daemon. */
+  async status() {
+    return await this.client.mountStatus(this.path);
+  }
+  /** Unmount; `discard: true` drops changes not yet uploaded. */
+  async unmount(discard = false) {
+    await this.client.unmount(this.path, discard);
+  }
+};
+
 // src/index.ts
 init_image();
 init_url();
@@ -6550,11 +7244,20 @@ init_models();
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   APIClient,
+  CliNotFoundError,
   CloudClient,
   ContainerState,
   Desktop,
+  FileNotFoundInFilesystemError,
+  Filesystem,
+  FilesystemAPIError,
+  FilesystemClient,
+  FilesystemError,
+  FilesystemMount,
+  FilesystemNotFoundError,
   Image,
   ImageBuildOperationType,
+  MountError,
   OutputMode,
   PoolInUseError,
   PoolNotFoundError,