@dbx-tools/appkit-mastra 0.6.8 → 0.6.10

package/lib/src/filesystems.d.ts

@@ -1,208 +1,90 @@
 /**
- * Mastra {@link WorkspaceFilesystem} implementations for Databricks Apps.
+ * Mastra workspace filesystem adapters.
  *
- * {@link DatabricksWorkspaceFilesystem} maps a Mastra workspace namespace onto
- * an absolute Databricks path (Unity Catalog volume, workspace object tree, or
- * DBFS). {@link emptyFilesystem} is a read-only no-op mount used when no
- * dynamic mounts resolve for a request.
- *
- * Path helpers ({@link normalizeDatabricksBasePath}, {@link isDbfsPath}, …)
- * are exported for tests and callers that need to reason about Databricks
- * paths without constructing a filesystem.
+ * {@link filesystems} wraps any portable `@dbx-tools/shared-fs` {@link FileSystem}
+ * (local disk, Databricks, memory, …) as a Mastra {@link MastraFilesystem}.
+ * {@link scratchFilesystem} always returns a fresh {@link localFS.tmpFS} mount
+ * (random id root) when Mastra needs a filesystem and no other mount resolved.
  *
  * @module
  */
-import { WorkspaceClient } from "@databricks/sdk-experimental";
+import type { FileSystem } from "@dbx-tools/shared-fs";
 import { MastraFilesystem } from "@mastra/core/workspace";
 import type { CopyOptions, FileContent, FileEntry, FileStat, FilesystemInfo, ListOptions, MastraFilesystemOptions, ProviderStatus, ReadOptions, RemoveOptions, WriteOptions } from "@mastra/core/workspace";
-/** How {@link DatabricksWorkspaceFilesystem.init} handles a missing {@link basePath}. */
-export type DatabricksMkdirsMode = boolean | "try";
-/** Options for {@link DatabricksWorkspaceFilesystem}. */
-export interface DatabricksWorkspaceFilesystemOptions extends MastraFilesystemOptions {
-    /** Unique identifier for this filesystem instance. */
+/** Options for {@link filesystems} / {@link MastraFileSystemAdapter}. */
+export interface MastraFileSystemAdapterOptions extends MastraFilesystemOptions {
+    /** Override the Mastra filesystem id. Defaults to the source {@link FileSystem.id}. */
     id?: string;
-    /** Auth-scoped Databricks workspace client. */
-    client?: WorkspaceClient;
+    /** Override the Mastra display name. Defaults to `MastraFileSystemAdapter`. */
+    name?: string;
     /**
-     * Absolute Databricks path that roots the workspace namespace, e.g.
-     * `/Volumes/catalog/schema/volume` or `/dbfs/FileStore/shared`.
+     * Override the Mastra provider id. Defaults to the source
+     * {@link FileSystem.backend}.
      */
-    basePath: string;
+    provider?: string;
     /**
-     * When the {@link basePath} is missing at {@link init}, create it with the
-     * matching Databricks `mkdirs` API. `"try"` (default) logs at debug and
-     * falls back to an empty read-only namespace on failure; `true` fails init;
-     * `false` skips creation and uses the empty namespace.
-     *
-     * A successful mkdir also satisfies the write-access probe when
-     * {@link readOnly} is omitted.
+     * Force read-only mounts even when the source filesystem allows writes.
+     * The source {@link FileSystem.readOnly} flag still applies either way.
      */
-    mkdirs?: DatabricksMkdirsMode;
-    /** Block writes while still allowing reads. When omitted, {@link init} probes write access. */
     readOnly?: boolean;
 }
-/** Normalize a Databricks base path (POSIX, no trailing slash). */
-export declare function normalizeDatabricksBasePath(basePath: string): string;
-/** True when `absolutePath` is served by DBFS rather than the UC Files API. */
-export declare function isDbfsPath(absolutePath: string): boolean;
-/** True when `absolutePath` is a Databricks workspace object path. */
-export declare function isWorkspaceFilesPath(absolutePath: string): boolean;
 /**
- * Resolve a workspace-relative path to an absolute Databricks path under
- * `basePath`.
+ * Wrap a portable {@link FileSystem} as a Mastra {@link MastraFilesystem}.
+ *
+ * @example
+ * ```ts
+ * import { filesystems } from "@dbx-tools/appkit-mastra";
+ * import { DatabricksFileSystem } from "@dbx-tools/databricks";
+ * import { localFS } from "@dbx-tools/fs";
+ *
+ * const volume = filesystems.filesystems(
+ *   new DatabricksFileSystem({ root: "/Volumes/main/default/assets" }),
+ * );
+ * const scratch = filesystems.filesystems(localFS.tmpFS("agent-job"));
+ * ```
  */
-export declare function resolveDatabricksAbsolutePath(basePath: string, inputPath: string): string;
-/** Map an absolute Databricks path back to the workspace namespace. */
-export declare function toDatabricksWorkspacePath(basePath: string, absolutePath: string): string;
+export declare function filesystems(fs: FileSystem, options?: MastraFileSystemAdapterOptions): MastraFileSystemAdapter;
 /**
- * Mastra filesystem provider that reads and writes through a Databricks
- * {@link WorkspaceClient}.
- *
- * Workspace paths are absolute within the namespace (`/notes.md` maps to
- * `<basePath>/notes.md`). Unity Catalog volumes use the Files API;
- * `/dbfs/...` paths use DBFS.
+ * Thin Mastra {@link MastraFilesystem} adapter over a `@dbx-tools/shared-fs`
+ * {@link FileSystem}. Identity fields are getters that read the source on
+ * access; construction does not snapshot them.
  */
-export declare class DatabricksWorkspaceFilesystem extends MastraFilesystem {
-    readonly id: string;
-    readonly name = "DatabricksWorkspaceFilesystem";
-    readonly provider = "databricks";
-    readonly basePath: string;
+export declare class MastraFileSystemAdapter extends MastraFilesystem {
     status: ProviderStatus;
-    private readonly client;
-    private readonly mkdirs;
-    private _readOnly;
-    private _basePathMissing;
-    get readOnly(): boolean | undefined;
-    /**
-     * @param options.client - Defaults to the AppKit execution-context client.
-     * @param options.mkdirs - Default `"try"`; see {@link DatabricksMkdirsMode}.
-     * @param options.readOnly - When omitted, {@link init} probes write access.
-     */
-    constructor(options: DatabricksWorkspaceFilesystemOptions);
-    /** Resolve and sandbox a workspace-relative path under {@link basePath}. */
-    private resolvePath;
-    /** Map a Databricks absolute path back to the workspace namespace. */
-    private workspacePath;
-    /** Throw when the filesystem is read-only. */
-    private assertWritable;
-    /** Map SDK / HTTP errors to Mastra workspace filesystem errors. */
-    private rethrow;
-    /**
-     * Probe whether {@link basePath} exists and cache the result on
-     * {@link _basePathMissing}.
-     */
-    private resolveBasePathStatus;
-    /** Delegate to {@link emptyFilesystem} when the base path is missing. */
-    private emptyFallback;
+    private readonly fs;
+    private readonly options;
+    constructor(fs: FileSystem, options?: MastraFileSystemAdapterOptions);
+    get id(): string;
+    get name(): string;
+    get provider(): string;
+    get readOnly(): boolean;
+    get basePath(): string;
     init(): Promise<void>;
-    /**
-     * Write and delete a ephemeral probe file to detect read-only access when
-     * {@link DatabricksWorkspaceFilesystemOptions.readOnly} was not set.
-     *
-     * @returns `true` when the probe write (and cleanup) succeeded.
-     */
-    private probeReadOnly;
     destroy(): Promise<void>;
-    /** Probe that `absolutePath` exists (file or directory metadata). */
-    private assertAbsoluteReadable;
-    /** Read the full contents of `absolutePath` from the matching backend. */
-    private readAbsolute;
-    /** Write `buffer` to `absolutePath` on the matching backend. */
-    private writeAbsolute;
-    /** Upload a buffer to a Unity Catalog Files API path. */
-    private uploadUcFile;
-    /** Delete a single file at `absolutePath` (non-recursive). */
-    private deleteAbsoluteFile;
-    /**
-     * Delete a file or directory at `absolutePath`.
-     *
-     * DBFS and workspace APIs accept `recursive`; UC volumes recurse manually.
-     */
-    private deleteAbsolutePath;
-    /** Create `absolutePath` and any missing parents on the matching backend. */
-    private mkdirAbsolute;
-    private readDbfsFile;
-    private readWorkspaceFile;
-    private writeDbfsFile;
-    private writeWorkspaceFile;
     getInfo(): FilesystemInfo<{
-        basePath: string;
+        root: string;
+        backend: string;
     }>;
     getInstructions(): string;
-    /** Map a workspace-relative path to the backing Databricks absolute path. */
-    resolveAbsolutePath(inputPath: string): string | undefined;
-    /** Read file contents from the workspace namespace. */
     readFile(inputPath: string, options?: ReadOptions): Promise<string | Buffer>;
-    /** Write file contents into the workspace namespace. */
     writeFile(inputPath: string, content: FileContent, options?: WriteOptions): Promise<void>;
-    /** Append to an existing file, creating it when missing. */
     appendFile(inputPath: string, content: FileContent): Promise<void>;
-    /** Delete a file in the workspace namespace. */
     deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
-    /** Copy a file within the workspace namespace. */
     copyFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
-    /** Move or rename a file within the workspace namespace. */
     moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
-    /** Create a directory in the workspace namespace. */
     mkdir(inputPath: string, options?: {
         recursive?: boolean;
     }): Promise<void>;
-    /** Remove a directory from the workspace namespace. */
     rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
-    /**
-     * Recursively delete a Unity Catalog directory tree.
-     *
-     * DBFS and workspace trees use native recursive delete via
-     * {@link deleteAbsolutePath} instead.
-     */
-    private deleteUcDirectoryRecursive;
-    /** List entries in a workspace directory. */
     readdir(inputPath: string, options?: ListOptions): Promise<FileEntry[]>;
-    private readDirectoryRecursive;
-    private listAbsoluteDirectory;
-    /** Apply Mastra list filters (`extension`, etc.) to directory entries. */
-    private filterEntries;
-    /** Return whether `inputPath` exists in the workspace namespace. */
-    exists(inputPath: string): Promise<boolean>;
-    /** Return file or directory metadata for `inputPath`. */
-    stat(inputPath: string): Promise<FileStat>;
-    /**
-     * Stat a Unity Catalog path by probing file metadata first, then
-     * directory metadata.
-     */
-    private statUcAbsolute;
-}
-/**
- * Read-only in-memory {@link WorkspaceFilesystem} with a single empty root.
- * Use {@link emptyFilesystem} rather than constructing directly.
- */
-declare class EmptyFilesystem extends MastraFilesystem {
-    readonly id = "empty-fs";
-    readonly name = "EmptyFilesystem";
-    readonly provider = "empty";
-    readonly readOnly = true;
-    status: ProviderStatus;
-    constructor();
-    init(): Promise<void>;
-    destroy(): Promise<void>;
-    getInfo(): FilesystemInfo;
-    getInstructions(): string;
-    private rootStat;
-    private assertWritable;
-    readFile(inputPath: string, _options?: ReadOptions): Promise<string | Buffer>;
-    writeFile(_inputPath: string, _content: FileContent, _options?: WriteOptions): Promise<void>;
-    appendFile(_inputPath: string, _content: FileContent): Promise<void>;
-    deleteFile(inputPath: string, options?: RemoveOptions): Promise<void>;
-    copyFile(src: string, _dest: string, _options?: CopyOptions): Promise<void>;
-    moveFile(src: string, dest: string, options?: CopyOptions): Promise<void>;
-    mkdir(_inputPath: string, _options?: {
-        recursive?: boolean;
-    }): Promise<void>;
-    rmdir(inputPath: string, options?: RemoveOptions): Promise<void>;
-    readdir(inputPath: string, _options?: ListOptions): Promise<FileEntry[]>;
     exists(inputPath: string): Promise<boolean>;
     stat(inputPath: string): Promise<FileStat>;
+    private delegate;
+    /** {@link delegate} for a mutation: refuse a read-only mount before doing any work. */
+    private delegateWrite;
+    /** When Mastra asks for non-recursive writes, require the parent directory. */
+    private assertParentExists;
+    private rethrow;
 }
-/** Memoized singleton empty read-only filesystem for no-op mounts. */
-export declare const emptyFilesystem: () => EmptyFilesystem;
-export {};
+/** Fresh writable local temp mount on a root unique to this call. */
+export declare function scratchFilesystem(): MastraFileSystemAdapter;