hazo_files 3.0.0 → 3.1.0

package/CHANGE_LOG.md

@@ -5,6 +5,30 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 3.1.0 — 2026-06-11
+
+**Additive** — no breaking changes from 3.0.x.
+
+### Added
+
+- **`FileStorageProvider` parity methods** — `list`, `move`, and `rename` added to the interface and implemented across all three providers:
+  - `AppFileServerProvider.list(prefix)` — recursive filesystem walk; returns `FileEntry[]`.
+  - `AppFileServerProvider.move(from, to)` — atomic `renameSync` with automatic EXDEV (cross-device) fallback to copy+delete.
+  - `AppFileServerProvider.rename(from, to)` — delegates to `move`.
+  - `InMemoryProvider.list(prefix)` — returns entries for all keys under the prefix, including synthetic directory entries.
+  - `InMemoryProvider.move(from, to)` / `rename` — in-place store key reassignment.
+  - `GoogleDriveProvider.list(prefix)` — single-level Drive API query; returns immediate children.
+  - `GoogleDriveProvider.move(from, to)` — Drive `files.update` with parent-change and rename; invalidates path cache entry.
+  - `GoogleDriveProvider.rename(from, to)` — Drive `files.update` rename only.
+- **`FileEntry` type** — returned by `list()`; carries `path`, `name`, `size`, and `isDirectory`. Exported from both `hazo_files` and `hazo_files/server`.
+
+### Test-app improvements
+
+- Fixed 4 failing autotest scenarios: envelope assertion (`{success,data}` shape), correct `naming_title` field, required `action` param for naming generation, required `scope_id` for quota.
+- Added 9 new autotest scenarios covering file CRUD, rename/move, metadata listing, naming-convention full CRUD, advanced name generation, quota lifecycle + threshold events, SSRF rejection, LLM status, and upload-extract wiring.
+- Fixed missing **Run All** button: added `hazo_ui/dist` to `tailwind.config.ts` content globs so the harness runner's Tailwind classes are compiled.
+- Bumped `lucide-react` from `^0.294.0` → `^0.553.0` to resolve `OctagonAlert` import error from `hazo_ui`.
+
 ## 3.0.0 — 2026-05-29
 
 ### Breaking changes (Wave 2 standardisation)

package/README.md

@@ -7,7 +7,7 @@ A powerful, modular file management package for Node.js and React applications w
 
 ## Features
 
-- **`FileStorageProvider` Interface**: Lightweight `put/get/delete/exists/getSignedUrl/probe` abstraction for simpler use cases
+- **`FileStorageProvider` Interface**: Lightweight `put/get/delete/exists/getSignedUrl/probe/list/move/rename` abstraction for simpler use cases
 - **`AppFileServerProvider`**: Local filesystem + HMAC-signed download URLs — no cloud account required
 - **`GoogleDriveProvider`**: Service-account Google Drive for Shared Drives with lazy path-cache
 - **`InMemoryProvider`**: Zero-dependency in-memory store for unit tests (via `hazo_files/testing`)
@@ -64,6 +64,7 @@ npm install dropbox           # Dropbox support
 For database tracking and LLM extraction features (optional):
 
 ```bash
+npm install hazo_core         # Error classes, logger, config (peer of all hazo_* packages)
 npm install hazo_connect      # Database tracking
 npm install hazo_llm_api      # LLM document extraction
 npm install server-only       # Server-side safety (recommended)
@@ -1999,15 +2000,31 @@ v2 introduces a slimmer storage abstraction — `FileStorageProvider` — that s
 ### Interface
 
 ```typescript
-import type { FileStorageProvider } from 'hazo_files/server';
+import type { FileStorageProvider, FileEntry } from 'hazo_files/server';
 
 interface FileStorageProvider {
+  // Core CRUD
   put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
   get(path: string): Promise<Buffer | Readable>;
   delete(path: string): Promise<void>;
   exists(path: string): Promise<boolean>;
   getSignedUrl(path: string, opts?: SignedUrlOpts): Promise<string>;
   probe(): Promise<ProbeResult>;
+
+  // v3.1 — parity methods
+  /** List all files and sub-directories under a prefix (recursive). */
+  list(prefix: string): Promise<FileEntry[]>;
+  /** Move bytes from `from` to `to`, removing the source on success. */
+  move(from: string, to: string): Promise<void>;
+  /** Rename — equivalent to move when the parent directory stays the same. */
+  rename(from: string, to: string): Promise<void>;
+}
+
+interface FileEntry {
+  path: string;       // logical path (same namespace as put/get)
+  name: string;       // bare filename or directory name
+  size: number;       // bytes; 0 for directories
+  isDirectory: boolean;
 }
 ```
 
@@ -2122,6 +2139,32 @@ const url = await store.getSignedUrl('docs/readme.txt');
 // 'data:application/octet-stream;base64,aGVsbG8='
 ```
 
+### list / move / rename (v3.1)
+
+All three providers now implement `list`, `move`, and `rename`:
+
+```typescript
+import { AppFileServerProvider } from 'hazo_files/server';
+import type { FileEntry } from 'hazo_files/server';
+
+const provider = new AppFileServerProvider({ root: './storage', hmac_secret: '...' });
+
+// List all files and sub-directories under a prefix (recursive)
+const entries: FileEntry[] = await provider.list('uploads/2026');
+// [
+//   { path: 'uploads/2026/ACME', name: 'ACME', size: 0, isDirectory: true },
+//   { path: 'uploads/2026/ACME/invoice.pdf', name: 'invoice.pdf', size: 12345, isDirectory: false },
+// ]
+
+// Move a file (source is removed on success; intermediate directories are created)
+await provider.move('uploads/incoming/report.pdf', 'uploads/2026/ACME/report.pdf');
+
+// Rename (full new logical path)
+await provider.rename('uploads/2026/ACME/report.pdf', 'uploads/2026/ACME/report_final.pdf');
+```
+
+`AppFileServerProvider.move` handles cross-device (EXDEV) renames transparently by falling back to copy-then-delete. `GoogleDriveProvider.move` updates the Drive file's parent folder and name in a single API call, then invalidates the path-cache entry. `InMemoryProvider` implementations are synchronous key-reassignments — useful for tests that need to exercise rename/move paths.
+
 ### Provider Errors
 
 ```typescript

package/dist/index.d.mts

@@ -3318,6 +3318,22 @@ interface ProbeResult {
     /** Free-form detail for logging. */
     message?: string;
 }
+/**
+ * A single entry returned by `FileStorageProvider.list()`.
+ *
+ * `path` is the same logical namespace used by `put`/`get` — callers can pass
+ * it directly back to those methods without any transformation.
+ */
+interface FileEntry {
+    /** Logical path within the provider (same namespace as put/get). */
+    path: StoragePath;
+    /** Bare filename or directory name (the last segment of `path`). */
+    name: string;
+    /** Size in bytes. 0 for directories. */
+    size: number;
+    /** True when this entry represents a directory. */
+    isDirectory: boolean;
+}
 /**
  * Storage provider abstraction. Every method MUST be idempotent at the
  * data-content level — re-invoking put with identical body is allowed.
@@ -3332,6 +3348,36 @@ interface FileStorageProvider {
     getSignedUrl(path: StoragePath, opts?: SignedUrlOpts): Promise<string>;
     /** Used by validation cron + onboarding step 2. */
     probe(): Promise<ProbeResult>;
+    /**
+     * List all entries (files and sub-directories) under a logical path prefix.
+     * Results are recursive — all descendants are included.
+     * Returns an empty array when the prefix does not exist.
+     */
+    list(prefix: StoragePath): Promise<FileEntry[]>;
+    /**
+     * Move bytes from `from` to `to`, creating any intermediate directories.
+     * The source is removed on success.
+     * Throws with a message containing "Not found" when `from` does not exist.
+     */
+    move(from: StoragePath, to: StoragePath): Promise<void>;
+    /**
+     * Rename a file or directory.  `to` is the full new logical path.
+     * Implementations may delegate to `move`.
+     * Throws with a message containing "Not found" when `from` does not exist.
+     */
+    rename(from: StoragePath, to: StoragePath): Promise<void>;
+}
+declare class StorageCollisionExhausted extends Error {
+    attempts: number;
+    lastPath: StoragePath;
+    constructor(attempts: number, lastPath: StoragePath);
+}
+declare class StorageNotConfigured extends Error {
+    constructor();
+}
+declare class StorageUnavailable extends Error {
+    reason: ProbeResult["error"];
+    constructor(reason: ProbeResult["error"], message: string);
 }
 
 interface WriteWithCollisionOpts {
@@ -3370,4 +3416,82 @@ declare function addRef<T extends FileWithRefs>(file: T, ref: FileRef): T;
 declare function removeRef<T extends FileWithRefs>(file: T, ref_id: string, removed_at: string): T;
 declare function countRefs(file: Pick<FileWithRefs, "file_refs">): number;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef$1 as FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithRefs, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, NamingTemplate, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, type WriteWithCollisionOpts, addExtractionToFileData, addRef, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, countRefs, createAndInitializeModule, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRef, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath, writeWithCollisionRetry };
+interface AppFileServerOpts {
+    /** Filesystem root. All paths are resolved relative to this. */
+    root: string;
+    /** HMAC secret used to sign download URLs. */
+    hmac_secret: string;
+    /** Default signed-URL TTL in seconds. */
+    default_ttl_seconds?: number;
+}
+declare class AppFileServerProvider implements FileStorageProvider {
+    readonly provider_tag: "app_file_server";
+    private readonly root;
+    private readonly secret;
+    private readonly default_ttl;
+    constructor(opts: AppFileServerOpts);
+    private resolve;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, opts?: SignedUrlOpts): Promise<string>;
+    /** Verify a token produced by `getSignedUrl`. Used by the `/api/files/serve` route. */
+    verifySignedUrl(token: string, path: string): boolean;
+    probe(): Promise<ProbeResult>;
+    list(prefix: string): Promise<FileEntry[]>;
+    private walkDir;
+    move(from: string, to: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+
+declare class InMemoryProvider implements FileStorageProvider {
+    readonly provider_tag: "in_memory";
+    private readonly store;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    probe(): Promise<ProbeResult>;
+    list(prefix: string): Promise<FileEntry[]>;
+    move(from: string, to: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    /** Test-only escape hatch — exposes the internal store for assertions. */
+    snapshot(): Map<string, Buffer>;
+}
+
+interface DrivePathCache {
+    lookup(key: string): Promise<string | null>;
+    write(key: string, folder_id: string): Promise<void>;
+    invalidate(key: string): Promise<void>;
+}
+interface GoogleDriveOpts {
+    /** Raw JSON keyfile contents (decoded from GOOGLE_SERVICE_ACCOUNT_JSON env var). */
+    service_account_json: string;
+    /** Target Shared Drive ID. */
+    shared_drive_id: string;
+    /** Lazy folder-ID cache, scoped per Hazodocs org. */
+    path_cache: DrivePathCache;
+}
+declare class GoogleDriveProvider implements FileStorageProvider {
+    readonly provider_tag: "gdrive";
+    private readonly drive;
+    private readonly driveId;
+    private readonly cache;
+    constructor(opts: GoogleDriveOpts);
+    probe(): Promise<ProbeResult>;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    list(prefix: string): Promise<FileEntry[]>;
+    move(from: string, to: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    private resolvePath;
+    private findChild;
+    private lookupFileId;
+}
+
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type DrivePathCache, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, type FileEntry, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef$1 as FileRef, type FileRefVisibility, type FileStatus, type FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithRefs, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, type GoogleDriveOpts, GoogleDriveProvider, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InMemoryProvider, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, NamingTemplate, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProbeResult, type ProgressCallback, type PutOpts, type PutResult, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, type WriteWithCollisionOpts, addExtractionToFileData, addRef, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, countRefs, createAndInitializeModule, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRef, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath, writeWithCollisionRetry };

package/dist/index.d.ts

@@ -3318,6 +3318,22 @@ interface ProbeResult {
     /** Free-form detail for logging. */
     message?: string;
 }
+/**
+ * A single entry returned by `FileStorageProvider.list()`.
+ *
+ * `path` is the same logical namespace used by `put`/`get` — callers can pass
+ * it directly back to those methods without any transformation.
+ */
+interface FileEntry {
+    /** Logical path within the provider (same namespace as put/get). */
+    path: StoragePath;
+    /** Bare filename or directory name (the last segment of `path`). */
+    name: string;
+    /** Size in bytes. 0 for directories. */
+    size: number;
+    /** True when this entry represents a directory. */
+    isDirectory: boolean;
+}
 /**
  * Storage provider abstraction. Every method MUST be idempotent at the
  * data-content level — re-invoking put with identical body is allowed.
@@ -3332,6 +3348,36 @@ interface FileStorageProvider {
     getSignedUrl(path: StoragePath, opts?: SignedUrlOpts): Promise<string>;
     /** Used by validation cron + onboarding step 2. */
     probe(): Promise<ProbeResult>;
+    /**
+     * List all entries (files and sub-directories) under a logical path prefix.
+     * Results are recursive — all descendants are included.
+     * Returns an empty array when the prefix does not exist.
+     */
+    list(prefix: StoragePath): Promise<FileEntry[]>;
+    /**
+     * Move bytes from `from` to `to`, creating any intermediate directories.
+     * The source is removed on success.
+     * Throws with a message containing "Not found" when `from` does not exist.
+     */
+    move(from: StoragePath, to: StoragePath): Promise<void>;
+    /**
+     * Rename a file or directory.  `to` is the full new logical path.
+     * Implementations may delegate to `move`.
+     * Throws with a message containing "Not found" when `from` does not exist.
+     */
+    rename(from: StoragePath, to: StoragePath): Promise<void>;
+}
+declare class StorageCollisionExhausted extends Error {
+    attempts: number;
+    lastPath: StoragePath;
+    constructor(attempts: number, lastPath: StoragePath);
+}
+declare class StorageNotConfigured extends Error {
+    constructor();
+}
+declare class StorageUnavailable extends Error {
+    reason: ProbeResult["error"];
+    constructor(reason: ProbeResult["error"], message: string);
 }
 
 interface WriteWithCollisionOpts {
@@ -3370,4 +3416,82 @@ declare function addRef<T extends FileWithRefs>(file: T, ref: FileRef): T;
 declare function removeRef<T extends FileWithRefs>(file: T, ref_id: string, removed_at: string): T;
 declare function countRefs(file: Pick<FileWithRefs, "file_refs">): number;
 
-export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef$1 as FileRef, type FileRefVisibility, type FileStatus, type FileSystemItem, FileTooLargeError, type FileWithRefs, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, NamingTemplate, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProgressCallback, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type StorageModule, type StorageProvider, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, type WriteWithCollisionOpts, addExtractionToFileData, addRef, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, countRefs, createAndInitializeModule, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRef, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath, writeWithCollisionRetry };
+interface AppFileServerOpts {
+    /** Filesystem root. All paths are resolved relative to this. */
+    root: string;
+    /** HMAC secret used to sign download URLs. */
+    hmac_secret: string;
+    /** Default signed-URL TTL in seconds. */
+    default_ttl_seconds?: number;
+}
+declare class AppFileServerProvider implements FileStorageProvider {
+    readonly provider_tag: "app_file_server";
+    private readonly root;
+    private readonly secret;
+    private readonly default_ttl;
+    constructor(opts: AppFileServerOpts);
+    private resolve;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, opts?: SignedUrlOpts): Promise<string>;
+    /** Verify a token produced by `getSignedUrl`. Used by the `/api/files/serve` route. */
+    verifySignedUrl(token: string, path: string): boolean;
+    probe(): Promise<ProbeResult>;
+    list(prefix: string): Promise<FileEntry[]>;
+    private walkDir;
+    move(from: string, to: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+}
+
+declare class InMemoryProvider implements FileStorageProvider {
+    readonly provider_tag: "in_memory";
+    private readonly store;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    probe(): Promise<ProbeResult>;
+    list(prefix: string): Promise<FileEntry[]>;
+    move(from: string, to: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    /** Test-only escape hatch — exposes the internal store for assertions. */
+    snapshot(): Map<string, Buffer>;
+}
+
+interface DrivePathCache {
+    lookup(key: string): Promise<string | null>;
+    write(key: string, folder_id: string): Promise<void>;
+    invalidate(key: string): Promise<void>;
+}
+interface GoogleDriveOpts {
+    /** Raw JSON keyfile contents (decoded from GOOGLE_SERVICE_ACCOUNT_JSON env var). */
+    service_account_json: string;
+    /** Target Shared Drive ID. */
+    shared_drive_id: string;
+    /** Lazy folder-ID cache, scoped per Hazodocs org. */
+    path_cache: DrivePathCache;
+}
+declare class GoogleDriveProvider implements FileStorageProvider {
+    readonly provider_tag: "gdrive";
+    private readonly drive;
+    private readonly driveId;
+    private readonly cache;
+    constructor(opts: GoogleDriveOpts);
+    probe(): Promise<ProbeResult>;
+    put(path: string, body: Buffer | Readable, opts?: PutOpts): Promise<PutResult>;
+    get(path: string): Promise<Buffer>;
+    delete(path: string): Promise<void>;
+    exists(path: string): Promise<boolean>;
+    getSignedUrl(path: string, _opts?: SignedUrlOpts): Promise<string>;
+    list(prefix: string): Promise<FileEntry[]>;
+    move(from: string, to: string): Promise<void>;
+    rename(from: string, to: string): Promise<void>;
+    private resolvePath;
+    private findChild;
+    private lookupFileId;
+}
+
+export { ALL_SYSTEM_VARIABLES, type AddExtractionOptions, type AddRefOptions, type AppFileServerOpts, AppFileServerProvider, type AuthCallbacks, AuthenticationError, type CleanupOrphanedOptions, ConfigurationError, type ContentTagConfig, type CreateFolderOptions, type CrudServiceLike, DEFAULT_DATE_FORMATS, type DatabaseSchemaDefinition, type DatabaseTrackingConfig, DirectoryExistsError, DirectoryNotEmptyError, DirectoryNotFoundError, type DownloadOptions, type DrivePathCache, DropboxAuth, type DropboxAuthCallbacks, type DropboxAuthConfig, type DropboxConfig, DropboxModule, type DropboxTokenData, type ExtractionData, type ExtractionOptions, type ExtractionResult, type FileBrowserState, type FileDataStructure, type FileEntry, FileExistsError, type FileInfo, type FileItem, FileManager, type FileManagerOptions, type FileMetadataInput, type FileMetadataRecord, type FileMetadataRecordV2, FileMetadataService, type FileMetadataServiceOptions, type FileMetadataUpdate, FileNotFoundError, type FileRef$1 as FileRef, type FileRefVisibility, type FileStatus, type FileStorageProvider, type FileSystemItem, FileTooLargeError, type FileWithRefs, type FileWithStatus, type FindOrphanedOptions, type FolderItem, type GeneratedNameResult, type GoogleAuthConfig, GoogleDriveAuth, type GoogleDriveConfig, GoogleDriveModule, type GoogleDriveOpts, GoogleDriveProvider, HAZO_FILES_DEFAULT_TABLE_NAME, HAZO_FILES_MIGRATION_V2, HAZO_FILES_MIGRATION_V3, HAZO_FILES_NAMING_DEFAULT_TABLE_NAME, HAZO_FILES_NAMING_TABLE_SCHEMA, HAZO_FILES_TABLE_SCHEMA, type HazoFilesColumnDefinitions, type HazoFilesConfig, type HazoFilesMigrationV2, type HazoFilesMigrationV3, type HazoFilesNamingColumnDefinitions, type HazoFilesNamingTableSchema, type HazoFilesTableSchema, type HazoLLMInstance, InMemoryProvider, InvalidExtensionError, InvalidPathError, LLMExtractionService, type LLMFactory, type LLMFactoryConfig, type LLMProvider, type ListNamingConventionsOptions, type ListOptions, type LocalStorageConfig, LocalStorageModule, type MetadataLogger, type MigrationExecutor, type MigrationSchemaDefinition, type MoveOptions, type NameGenerationOptions, type NamingConventionInput, type NamingConventionRecord, NamingConventionService, type NamingConventionServiceOptions, type NamingConventionType, type NamingConventionUpdate, type NamingRuleConfiguratorProps, type NamingRuleHistoryEntry, type NamingRuleSchema, NamingTemplate, type NamingVariable, OperationError, type OperationResult, type ParsedNamingConvention, type PatternSegment, PermissionDeniedError, type ProbeResult, type ProgressCallback, type PutOpts, type PutResult, type RemoveExtractionOptions, type RemoveRefsCriteria, type RenameOptions, SYSTEM_COUNTER_VARIABLES, SYSTEM_DATE_VARIABLES, SYSTEM_FILE_VARIABLES, type SignedUrlOpts, StorageCollisionExhausted, type StorageModule, StorageNotConfigured, type StoragePath, type StorageProvider, StorageUnavailable, type TokenData, TrackedFileManager, type TrackedFileManagerFullOptions, type TrackedFileManagerOptions, type TrackedUploadOptions, type TreeNode, type UploadExtractOptions, type UploadExtractResult, UploadExtractService, type UploadOptions, type UploadWithRefOptions, type UseNamingRuleActions, type UseNamingRuleReturn, type UseNamingRuleState, type VariableCategory, type WriteWithCollisionOpts, addExtractionToFileData, addRef, backfillV2Defaults, buildFileWithStatus, clearExtractions, clonePattern, computeFileHash, computeFileHashFromStream, computeFileHashSync, computeFileInfo, countRefs, createAndInitializeModule, createDropboxAuth, createDropboxModule, createEmptyFileDataStructure, createEmptyNamingRuleSchema, createFileItem, createFileManager, createFileMetadataService, createFileRef, createFolderItem, createGoogleDriveAuth, createGoogleDriveModule, createInitializedFileManager, createInitializedTrackedFileManager, createLLMExtractionService, createLiteralSegment, createLocalModule, createModule, createNamingConventionService, createTrackedFileManager, createUploadExtractService, createVariableSegment, deepMerge, errorResult, filterItems, formatBytes, formatCounter, formatDateToken, generateExtractionId, generateId, generatePreviewName, generateRefId, generateSampleConfig, generateSegmentId, getBaseName, getBreadcrumbs, getDirName, getExtension, getExtensionFromMime, getExtractionById, getExtractionCount, getExtractions, getFileCategory, getFileMetadataValues, getMergedData, getMigrationForTable, getMigrationV3ForTable, getMimeType, getNameWithoutExtension, getNamingSchemaForTable, getParentPath, getPathSegments, getRegisteredProviders, getRelativePath, getSchemaForTable, getSystemVariablePreviewValues, hasExtension, hasExtractionStructure, hasFileContentChanged, hashesEqual, hazo_files_generate_file_name, hazo_files_generate_folder_name, isAudio, isChildPath, isCounterVariable, isDateVariable, isDocument, isFile, isFileMetadataVariable, isFolder, isImage, isPreviewable, isProviderRegistered, isText, isVideo, joinPath, loadConfig, loadConfigAsync, migrateToV2, migrateToV3, normalizePath, parseConfig, parseFileData, parseFileRefs, parsePatternString, patternToString, recalculateMergedData, registerModule, removeExtractionById, removeExtractionByIndex, removeRef, removeRefFromArray, removeRefsByCriteriaFromArray, sanitizeFilename, saveConfig, sortItems, stringifyFileData, stringifyFileRefs, successResult, toV2Record, updateExtractionById, validateExtractionData, validateFileDataStructure, validateNamingRuleSchema, validatePath, writeWithCollisionRetry };