hazo_files 1.4.5 → 1.4.7

package/README.md

@@ -510,6 +510,167 @@ const fileManager = await createInitializedFileManager({
 });
 ```
 
+## Database Schema
+
+Database tables are only required if you use `TrackedFileManager`, `FileMetadataService`, `NamingConventionService`, or `UploadExtractService`. Plain `FileManager` (filesystem only) needs no tables.
+
+There are two tables:
+
+- **`hazo_files`** — file metadata, hashes, references, content tags
+- **`hazo_files_naming`** — saved naming conventions
+
+The DDL below is also exposed programmatically via `HAZO_FILES_TABLE_SCHEMA` and `HAZO_FILES_NAMING_TABLE_SCHEMA` (see [Programmatic Setup](#programmatic-setup) below). Run the raw SQL if you prefer to manage migrations with your existing tooling (psql, sqlite3, Flyway, Knex, etc.).
+
+### `hazo_files` Table
+
+#### PostgreSQL
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  filename TEXT NOT NULL,
+  file_type TEXT NOT NULL,
+  file_data TEXT DEFAULT '{}',
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  file_path TEXT NOT NULL,
+  storage_type TEXT NOT NULL,
+  file_hash TEXT,
+  file_size BIGINT,
+  file_changed_at TIMESTAMP WITH TIME ZONE,
+  file_refs TEXT DEFAULT '[]',
+  ref_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active',
+  scope_id UUID,
+  uploaded_by UUID,
+  storage_verified_at TIMESTAMP WITH TIME ZONE,
+  deleted_at TIMESTAMP WITH TIME ZONE,
+  original_filename TEXT,
+  content_tag TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_path ON hazo_files (file_path);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_storage ON hazo_files (storage_type);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_files_path_storage ON hazo_files (file_path, storage_type);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_hash ON hazo_files (file_hash);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_status ON hazo_files (status);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_scope ON hazo_files (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_ref_count ON hazo_files (ref_count);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_deleted ON hazo_files (deleted_at);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_content_tag ON hazo_files (content_tag);
+```
+
+#### SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files (
+  id TEXT PRIMARY KEY,
+  filename TEXT NOT NULL,
+  file_type TEXT NOT NULL,
+  file_data TEXT DEFAULT '{}',
+  created_at TEXT NOT NULL,
+  changed_at TEXT NOT NULL,
+  file_path TEXT NOT NULL,
+  storage_type TEXT NOT NULL,
+  file_hash TEXT,
+  file_size INTEGER,
+  file_changed_at TEXT,
+  file_refs TEXT DEFAULT '[]',
+  ref_count INTEGER DEFAULT 0,
+  status TEXT DEFAULT 'active',
+  scope_id TEXT,
+  uploaded_by TEXT,
+  storage_verified_at TEXT,
+  deleted_at TEXT,
+  original_filename TEXT,
+  content_tag TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_path ON hazo_files (file_path);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_storage ON hazo_files (storage_type);
+CREATE UNIQUE INDEX IF NOT EXISTS idx_hazo_files_path_storage ON hazo_files (file_path, storage_type);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_hash ON hazo_files (file_hash);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_status ON hazo_files (status);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_scope ON hazo_files (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_ref_count ON hazo_files (ref_count);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_deleted ON hazo_files (deleted_at);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_content_tag ON hazo_files (content_tag);
+```
+
+### `hazo_files_naming` Table
+
+Required only if you use `NamingConventionService` to persist saved naming rules.
+
+#### PostgreSQL
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files_naming (
+  id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+  scope_id UUID,
+  naming_title TEXT NOT NULL,
+  naming_type TEXT NOT NULL CHECK(naming_type IN ('file', 'folder', 'both')),
+  naming_value TEXT NOT NULL,
+  created_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  changed_at TIMESTAMP WITH TIME ZONE NOT NULL DEFAULT NOW(),
+  variables TEXT DEFAULT '[]'
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_scope ON hazo_files_naming (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_type ON hazo_files_naming (naming_type);
+```
+
+#### SQLite
+
+```sql
+CREATE TABLE IF NOT EXISTS hazo_files_naming (
+  id TEXT PRIMARY KEY,
+  scope_id TEXT,
+  naming_title TEXT NOT NULL,
+  naming_type TEXT NOT NULL CHECK(naming_type IN ('file', 'folder', 'both')),
+  naming_value TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  changed_at TEXT NOT NULL,
+  variables TEXT DEFAULT '[]'
+);
+
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_scope ON hazo_files_naming (scope_id);
+CREATE INDEX IF NOT EXISTS idx_hazo_files_naming_type ON hazo_files_naming (naming_type);
+```
+
+### Programmatic Setup
+
+The same DDL is available as exported constants so you can run it from your app's startup or migration script without hand-copying SQL:
+
+```typescript
+import {
+  HAZO_FILES_TABLE_SCHEMA,
+  HAZO_FILES_NAMING_TABLE_SCHEMA,
+} from 'hazo_files';
+
+// Pick 'sqlite' or 'postgres'
+const dbType: 'sqlite' | 'postgres' = 'sqlite';
+
+// Create hazo_files table
+await db.run(HAZO_FILES_TABLE_SCHEMA[dbType].ddl);
+for (const idx of HAZO_FILES_TABLE_SCHEMA[dbType].indexes) {
+  await db.run(idx);
+}
+
+// Create hazo_files_naming table (only if using NamingConventionService)
+await db.run(HAZO_FILES_NAMING_TABLE_SCHEMA[dbType].ddl);
+for (const idx of HAZO_FILES_NAMING_TABLE_SCHEMA[dbType].indexes) {
+  await db.run(idx);
+}
+```
+
+For PostgreSQL, swap `db.run(...)` for `client.query(...)`.
+
+To use a custom table name, see `getSchemaForTable(name, dbType)` and `getNamingSchemaForTable(name, dbType)`.
+
+### Upgrading Existing Tables
+
+If you already have a pre-V2 or pre-V3 `hazo_files` table, see [Database Migration (Existing Databases)](#database-migration-existing-databases) and [V3 Database Migration](#v3-database-migration) for the `ALTER TABLE` scripts and migration helpers.
+
 ## UI Components
 
 ### FileBrowser Component
@@ -1573,6 +1734,51 @@ import { registerModule } from 'hazo_files';
 registerModule('s3', () => new S3StorageModule());
 ```
 
+## Debug Integration (hazo_debug)
+
+hazo_files emits structured `file_operation` log entries with timing, storage provider, and operation type on every file operation. You can forward these to `hazo_debug` for a visual Files tab in the debug panel.
+
+The integration uses the existing `logger` option — no direct dependency on hazo_debug is needed:
+
+```typescript
+import { createHazoFilesServer } from 'hazo_files/server';
+import { use_debug_files } from 'hazo_debug/client';
+
+// In your server setup:
+const { log_file_op } = use_debug_files();
+
+const { fileManager } = await createHazoFilesServer({
+  config: { provider: 'local', local: { basePath: './files' } },
+  logger: {
+    info: (msg, data) => {
+      if (msg === 'file_operation') log_file_op(data);
+    },
+    error: (msg, data) => {
+      if (msg === 'file_operation') log_file_op(data);
+    },
+  },
+});
+```
+
+Every `file_operation` log entry includes:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `operation` | `string` | `'upload'` \| `'download'` \| `'delete'` \| `'move'` \| `'list'` \| `'extract'` |
+| `file_name` | `string?` | File name |
+| `file_path` | `string?` | Virtual file path |
+| `mime_type` | `string?` | MIME type |
+| `size_bytes` | `number?` | File size in bytes |
+| `storage` | `string?` | Storage provider (`'local'`, `'google_drive'`, etc.) |
+| `duration_ms` | `number` | Operation duration in milliseconds |
+| `success` | `boolean` | Whether the operation succeeded |
+| `error` | `string?` | Error message (on failure) |
+| `metadata` | `object?` | Extra context (e.g., `{ type: 'rename', new_name }`) |
+
+Logging is emitted at two levels:
+- **FileManager** logs the storage-level operation (actual file I/O timing)
+- **FileMetadataService** logs the database tracking operation (if tracking is enabled)
+
 ## Testing
 
 The package includes a test application in `test-app/` demonstrating:

package/dist/index.d.mts

@@ -657,152 +657,6 @@ interface StorageModule {
     getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
 }
 
-/**
- * File Manager Service
- * Main service that provides a unified API for file operations
- * Delegates to the appropriate storage module based on configuration
- */
-
-interface FileManagerOptions {
-    /** Path to configuration file */
-    configPath?: string;
-    /** Configuration object (takes precedence over configPath) */
-    config?: HazoFilesConfig;
-    /** Auto-initialize on creation */
-    autoInit?: boolean;
-}
-/**
- * FileManager - Main service class for file operations
- */
-declare class FileManager {
-    private module;
-    private config;
-    private initialized;
-    private options;
-    constructor(options?: FileManagerOptions);
-    /**
-     * Initialize the file manager with configuration
-     */
-    initialize(config?: HazoFilesConfig): Promise<void>;
-    /**
-     * @deprecated Storage modules require async initialization. Use initialize() instead.
-     */
-    initializeSync(_config?: HazoFilesConfig): void;
-    /**
-     * Check if manager is initialized
-     */
-    isInitialized(): boolean;
-    /**
-     * Get the current configuration
-     */
-    getConfig(): HazoFilesConfig | null;
-    /**
-     * Get the current provider
-     */
-    getProvider(): StorageProvider | null;
-    /**
-     * Get the underlying storage module
-     */
-    getModule(): StorageModule;
-    /**
-     * Ensure manager is initialized
-     */
-    private ensureInitialized;
-    /**
-     * Create a directory at the specified path
-     */
-    createDirectory(path: string): Promise<OperationResult<FolderItem>>;
-    /**
-     * Remove a directory
-     * @param path - Directory path
-     * @param recursive - If true, remove directory and all contents
-     */
-    removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
-    /**
-     * Upload/save a file
-     * @param source - File path, Buffer, or ReadableStream
-     * @param remotePath - Destination path in storage
-     * @param options - Upload options
-     */
-    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
-    /**
-     * Download a file
-     * @param remotePath - Path in storage
-     * @param localPath - Optional local destination path
-     * @param options - Download options
-     */
-    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
-    /**
-     * Move a file or folder
-     * @param sourcePath - Current path
-     * @param destinationPath - New path
-     * @param options - Move options
-     */
-    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
-    /**
-     * Delete a file
-     */
-    deleteFile(path: string): Promise<OperationResult>;
-    /**
-     * Rename a file
-     * @param path - Current file path
-     * @param newName - New filename (not full path)
-     * @param options - Rename options
-     */
-    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
-    /**
-     * Rename a folder
-     * @param path - Current folder path
-     * @param newName - New folder name (not full path)
-     * @param options - Rename options
-     */
-    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
-    /**
-     * List contents of a directory
-     * @param path - Directory path
-     * @param options - List options
-     */
-    listDirectory(path: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
-    /**
-     * Get information about a file or folder
-     */
-    getItem(path: string): Promise<OperationResult<FileSystemItem>>;
-    /**
-     * Check if a file or folder exists
-     */
-    exists(path: string): Promise<boolean>;
-    /**
-     * Get folder tree structure
-     * @param path - Starting path (default: root)
-     * @param depth - Maximum depth to traverse
-     */
-    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
-    /**
-     * Create a file with string content
-     */
-    writeFile(path: string, content: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
-    /**
-     * Read a file as string
-     */
-    readFile(path: string): Promise<OperationResult<string>>;
-    /**
-     * Copy a file to a new location
-     */
-    copyFile(sourcePath: string, destinationPath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
-    /**
-     * Ensure a directory exists (creates if needed)
-     */
-    ensureDirectory(path: string): Promise<OperationResult<FolderItem>>;
-}
-/**
- * Create a new FileManager instance
- */
-declare function createFileManager(options?: FileManagerOptions): FileManager;
-/**
- * Create and initialize a FileManager instance
- */
-declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
-
 /**
  * File Metadata Service
  * Handles database operations for tracking file metadata
@@ -1046,6 +900,159 @@ declare class FileMetadataService {
  */
 declare function createFileMetadataService(crudService: CrudServiceLike<FileMetadataRecord>, options?: FileMetadataServiceOptions): FileMetadataService;
 
+/**
+ * File Manager Service
+ * Main service that provides a unified API for file operations
+ * Delegates to the appropriate storage module based on configuration
+ */
+
+interface FileManagerOptions {
+    /** Path to configuration file */
+    configPath?: string;
+    /** Configuration object (takes precedence over configPath) */
+    config?: HazoFilesConfig;
+    /** Auto-initialize on creation */
+    autoInit?: boolean;
+    /** Logger for structured file operation logging (compatible with MetadataLogger) */
+    logger?: MetadataLogger;
+}
+/**
+ * FileManager - Main service class for file operations
+ */
+declare class FileManager {
+    private module;
+    private config;
+    private initialized;
+    private options;
+    protected logger?: MetadataLogger;
+    constructor(options?: FileManagerOptions);
+    /**
+     * Initialize the file manager with configuration
+     */
+    initialize(config?: HazoFilesConfig): Promise<void>;
+    /**
+     * @deprecated Storage modules require async initialization. Use initialize() instead.
+     */
+    initializeSync(_config?: HazoFilesConfig): void;
+    /**
+     * Check if manager is initialized
+     */
+    isInitialized(): boolean;
+    /**
+     * Get the current configuration
+     */
+    getConfig(): HazoFilesConfig | null;
+    /**
+     * Get the current provider
+     */
+    getProvider(): StorageProvider | null;
+    /**
+     * Get the underlying storage module
+     */
+    getModule(): StorageModule;
+    /**
+     * Ensure manager is initialized
+     */
+    private ensureInitialized;
+    /**
+     * Log a structured file operation event
+     */
+    private logFileOp;
+    /**
+     * Create a directory at the specified path
+     */
+    createDirectory(path: string): Promise<OperationResult<FolderItem>>;
+    /**
+     * Remove a directory
+     * @param path - Directory path
+     * @param recursive - If true, remove directory and all contents
+     */
+    removeDirectory(path: string, recursive?: boolean): Promise<OperationResult>;
+    /**
+     * Upload/save a file
+     * @param source - File path, Buffer, or ReadableStream
+     * @param remotePath - Destination path in storage
+     * @param options - Upload options
+     */
+    uploadFile(source: string | Buffer | ReadableStream, remotePath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Download a file
+     * @param remotePath - Path in storage
+     * @param localPath - Optional local destination path
+     * @param options - Download options
+     */
+    downloadFile(remotePath: string, localPath?: string, options?: DownloadOptions): Promise<OperationResult<Buffer | string>>;
+    /**
+     * Move a file or folder
+     * @param sourcePath - Current path
+     * @param destinationPath - New path
+     * @param options - Move options
+     */
+    moveItem(sourcePath: string, destinationPath: string, options?: MoveOptions): Promise<OperationResult<FileSystemItem>>;
+    /**
+     * Delete a file
+     */
+    deleteFile(path: string): Promise<OperationResult>;
+    /**
+     * Rename a file
+     * @param path - Current file path
+     * @param newName - New filename (not full path)
+     * @param options - Rename options
+     */
+    renameFile(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Rename a folder
+     * @param path - Current folder path
+     * @param newName - New folder name (not full path)
+     * @param options - Rename options
+     */
+    renameFolder(path: string, newName: string, options?: RenameOptions): Promise<OperationResult<FolderItem>>;
+    /**
+     * List contents of a directory
+     * @param path - Directory path
+     * @param options - List options
+     */
+    listDirectory(path: string, options?: ListOptions): Promise<OperationResult<FileSystemItem[]>>;
+    /**
+     * Get information about a file or folder
+     */
+    getItem(path: string): Promise<OperationResult<FileSystemItem>>;
+    /**
+     * Check if a file or folder exists
+     */
+    exists(path: string): Promise<boolean>;
+    /**
+     * Get folder tree structure
+     * @param path - Starting path (default: root)
+     * @param depth - Maximum depth to traverse
+     */
+    getFolderTree(path?: string, depth?: number): Promise<OperationResult<TreeNode[]>>;
+    /**
+     * Create a file with string content
+     */
+    writeFile(path: string, content: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Read a file as string
+     */
+    readFile(path: string): Promise<OperationResult<string>>;
+    /**
+     * Copy a file to a new location
+     */
+    copyFile(sourcePath: string, destinationPath: string, options?: UploadOptions): Promise<OperationResult<FileItem>>;
+    /**
+     * Ensure a directory exists (creates if needed)
+     */
+    ensureDirectory(path: string): Promise<OperationResult<FolderItem>>;
+}
+/**
+ * Create a new FileManager instance
+ */
+declare function createFileManager(options?: FileManagerOptions): FileManager;
+/**
+ * Create and initialize a FileManager instance
+ */
+declare function createInitializedFileManager(options?: FileManagerOptions): Promise<FileManager>;
+
 /**
  * Tracked File Manager
  * Extends FileManager to add database tracking of file operations
@@ -1059,6 +1066,8 @@ interface TrackedFileManagerFullOptions extends FileManagerOptions {
     crudService?: CrudServiceLike<FileMetadataRecord>;
     /** Database tracking configuration */
     tracking?: DatabaseTrackingConfig;
+    /** Logger for structured file operation logging */
+    logger?: MetadataLogger;
 }
 /**
  * Extended upload options with hash tracking