@dbx-tools/appkit-mastra 0.3.44 → 0.4.0

package/lib/src/filesystems.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Mastra {@link WorkspaceFilesystem} implementations for Databricks Apps.
+ *
+ * {@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.
+ *
+ * @module
+ */
+import { WorkspaceClient } from "@databricks/sdk-experimental";
+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. */
+    id?: string;
+    /** Auth-scoped Databricks workspace client. */
+    client?: WorkspaceClient;
+    /**
+     * Absolute Databricks path that roots the workspace namespace, e.g.
+     * `/Volumes/catalog/schema/volume` or `/dbfs/FileStore/shared`.
+     */
+    basePath: 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.
+     */
+    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`.
+ */
+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;
+/**
+ * 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.
+ */
+export declare class DatabricksWorkspaceFilesystem extends MastraFilesystem {
+    readonly id: string;
+    readonly name = "DatabricksWorkspaceFilesystem";
+    readonly provider = "databricks";
+    readonly basePath: string;
+    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;
+    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;
+    }>;
+    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>;
+}
+/** Memoized singleton empty read-only filesystem for no-op mounts. */
+export declare const emptyFilesystem: () => EmptyFilesystem;
+export {};