sqlite-hub 1.4.0 → 1.5.0

package/bin/sqlite-hub.js

@@ -26,6 +26,9 @@ Usage:
   sqlite-hub --database:"name" --documents
   sqlite-hub --database:"name" --documents:"Document Name"
   sqlite-hub --database:"name" --documents:"Document Name" --export
+  sqlite-hub --database:"name" --backups
+  sqlite-hub --database:"name" --backup
+  sqlite-hub --database:"name" --backup:"Before migration"
   sqlite-hub --database:"name" --table:"table_name"
   sqlite-hub --database:"name" --table:"table_name" --export:"primary-key"
   sqlite-hub --database:"name" --table:"table_name" --types:typescript
@@ -53,6 +56,10 @@ Options:
   --documents                        List Markdown documents for the selected database.
   --documents:"name"                 Print a document's Markdown content.
   --documents:"name" --export        Export a document as a Markdown file.
+  --backups                          List managed backups for the selected database.
+  --backup                           Create and verify a managed backup.
+  --backup:"name"                    Create a backup with a custom name.
+  --backup-notes:"text"              Add notes to a created backup.
   --table:"table"                    Print table metadata.
   --table:"table" --export:"pk"      Export one row as JSON by primary key or rowid.
   --types:typescript|ts|rust|rs|kotlin|kt|swift
@@ -191,6 +198,10 @@ function parseCliArguments(argv) {
         documents: false,
         documentName: null,
         documentExport: false,
+        backups: false,
+        backup: false,
+        backupName: null,
+        backupNotes: null,
         tableName: null,
         typesTarget: null,
         typeName: null,
@@ -383,6 +394,39 @@ function parseCliArguments(argv) {
             continue;
         }
 
+        if (flag === '--backups') {
+            options.backups = true;
+            continue;
+        }
+
+        if (flag === '--backup') {
+            const parsed = takeOptionalFlagValue(value, argv, index);
+
+            options.backup = true;
+            if (parsed.hasValue) {
+                options.backupName = parsed.value;
+            }
+
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--backup-name') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.backup = true;
+            options.backupName = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
+        if (flag === '--backup-notes') {
+            const parsed = takeFlagValue(flag, value, argv, index);
+            options.backup = true;
+            options.backupNotes = parsed.value;
+            index = parsed.nextIndex;
+            continue;
+        }
+
         if (flag === '--export') {
             if (options.documents && options.documentName && value === undefined) {
                 const nextValue = argv[index + 1];
@@ -506,6 +550,8 @@ function hasDatabaseOperation(options) {
         options.documents ||
         options.documentName ||
         options.documentExport ||
+        options.backups ||
+        options.backup ||
         options.exportTarget ||
         options.tableName ||
         options.typesTarget,
@@ -825,6 +871,58 @@ function exportDocumentMarkdown({ databaseService, conn, documentName }) {
     console.log(`Characters: ${result.document.contentLength}`);
     console.log(`File: ${outputPath}`);
 }
+
+function listManagedBackups({ databaseService, conn, options }) {
+    const backups = databaseService.listBackups(conn.id);
+
+    if (options.jsonOutput) {
+        console.log(JSON.stringify({ items: backups, total: backups.length }, null, 2));
+        return;
+    }
+
+    if (backups.length === 0) {
+        console.log(`No backups found for ${conn.label}.`);
+        return;
+    }
+
+    console.log(`\nBackups for ${conn.label} (${backups.length}):`);
+    console.log('─'.repeat(60));
+
+    backups.forEach((backup, index) => {
+        const fileState = backup.fileExists ? 'available' : 'missing';
+        console.log(`${index + 1}. ${backup.name}`);
+        console.log(`   ID: ${backup.id}`);
+        console.log(`   Status: ${backup.status} (${fileState})`);
+        console.log(`   Size: ${formatSize(backup.sizeBytes)}`);
+        console.log(`   Created: ${backup.createdAt}`);
+        console.log(`   File: ${backup.path}`);
+        if (backup.notes) {
+            console.log(`   Notes: ${backup.notes}`);
+        }
+        console.log('');
+    });
+}
+
+async function createManagedBackup({ databaseService, conn, options }) {
+    const backup = await databaseService.createBackup(conn.id, {
+        name: options.backupName,
+        notes: options.backupNotes,
+        context: 'cli',
+    });
+
+    if (options.jsonOutput) {
+        console.log(JSON.stringify(backup, null, 2));
+        return;
+    }
+
+    console.log(`Backup created: ${backup.name}`);
+    console.log(`Status: ${backup.status}`);
+    console.log(`Database: ${conn.label}`);
+    console.log(`Size: ${formatSize(backup.sizeBytes)}`);
+    console.log(`File: ${backup.path}`);
+    console.log(`ID: ${backup.id}`);
+}
+
 function exportTableRowAsJson({ databaseService, conn, tableName, exportTarget }) {
     const result = databaseService.getTableRow(conn.id, tableName, exportTarget);
     const outputPath = path.resolve(process.cwd(), result.filename);
@@ -958,191 +1056,526 @@ async function startAndOpen(port) {
 
 function requireDatabaseName(options) {
     if (!options.databaseName) {
-        console.error('Error: this command requires --database:"name".');
-        process.exit(1);
+        throw new Error('this command requires --database:"name".');
     }
 
     return options.databaseName;
 }
 
-async function main(argv = process.argv.slice(2), dependencies = {}) {
-    const options = parseCliArguments(argv);
-    const port = options.port ?? DEFAULT_PORT;
+function readCliFlags(argv = []) {
+    return argv
+        .filter(argument => String(argument ?? '').startsWith('-'))
+        .map(argument => splitArgument(argument).flag)
+        .filter(Boolean);
+}
+
+function describeCliAccess(options, argv = []) {
+    const metadata = {
+        flags: readCliFlags(argv),
+    };
+    const entry = {
+        source: 'cli',
+        action: 'cli.open',
+        targetType: 'app',
+        targetName: 'server',
+        metadata,
+    };
+
+    if (!options) {
+        return {
+            ...entry,
+            action: 'cli.parse',
+            targetType: 'command',
+            targetName: 'arguments',
+        };
+    }
+
+    if (options.exportFormat) metadata.exportFormat = options.exportFormat;
+    if (options.typesTarget) metadata.typesTarget = options.typesTarget;
+    if (options.outputPath) metadata.hasOutputPath = true;
+    if (options.jsonOutput) metadata.jsonOutput = true;
+    if (options.force) metadata.force = true;
 
     if (options.help) {
-        printHelp();
-        return;
+        return {
+            ...entry,
+            action: 'cli.help',
+            targetType: 'app',
+            targetName: 'help',
+        };
     }
 
     if (options.version) {
-        const { version } = require('../package.json');
-        console.log(`SQLite Hub CLI version ${version}`);
-        return;
+        return {
+            ...entry,
+            action: 'cli.version',
+            targetType: 'app',
+            targetName: 'version',
+        };
     }
 
     if (options.info) {
-        await printInfo(port, dependencies);
-        return;
+        return {
+            ...entry,
+            action: 'cli.info',
+            targetType: 'app',
+            targetName: 'info',
+        };
     }
 
     if (options.open) {
-        await startAndOpen(port);
-        return;
+        return entry;
+    }
+
+    if (options.documents) {
+        if (options.documentExport) {
+            return {
+                ...entry,
+                action: 'cli.document.export',
+                targetType: 'document',
+                targetName: options.documentName || 'document',
+            };
+        }
+
+        if (options.documentName) {
+            return {
+                ...entry,
+                action: 'cli.document.get',
+                targetType: 'document',
+                targetName: options.documentName,
+            };
+        }
+
+        return {
+            ...entry,
+            action: 'cli.documents.list',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
     }
 
-    if (options.storeName && !options.rawQuery) {
-        throw new Error('--store requires --query:"sql".');
+    if (options.backups) {
+        return {
+            ...entry,
+            action: 'cli.backups.list',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
     }
 
-    const databaseService =
-        dependencies.databaseService ??
-        new DatabaseCommandService({
-            appStateStore: dependencies.appStateStore ?? createAppStateStore(),
-        });
-    const connections = databaseService.listDatabases();
+    if (options.backup) {
+        return {
+            ...entry,
+            action: 'cli.backup.create',
+            targetType: 'database',
+            targetName: options.databaseName,
+            metadata: {
+                ...metadata,
+                hasBackupName: Boolean(options.backupName),
+                hasBackupNotes: Boolean(options.backupNotes),
+            },
+        };
+    }
+
+    if (options.tableName) {
+        if (options.typesTarget) {
+            return {
+                ...entry,
+                action: 'cli.table.types.generate',
+                targetType: 'table',
+                targetName: options.tableName,
+            };
+        }
+
+        if (options.exportTarget) {
+            return {
+                ...entry,
+                action: 'cli.table.row.export',
+                targetType: 'table',
+                targetName: options.tableName,
+            };
+        }
+
+        return {
+            ...entry,
+            action: 'cli.table.get',
+            targetType: 'table',
+            targetName: options.tableName,
+        };
+    }
+
+    if (options.exportTarget) {
+        return {
+            ...entry,
+            action: 'cli.query.export',
+            targetType: 'query',
+            targetName: options.exportTarget,
+        };
+    }
+
+    if (options.executeQuery) {
+        return {
+            ...entry,
+            action: 'cli.query.execute.saved',
+            targetType: 'query',
+            targetName: options.executeQuery,
+        };
+    }
+
+    if (options.rawQuery) {
+        return {
+            ...entry,
+            action: 'cli.query.execute',
+            targetType: 'query',
+            targetName: options.storeName || 'raw query',
+            metadata: {
+                ...metadata,
+                hasStoreName: Boolean(options.storeName),
+            },
+        };
+    }
+
+    if (options.showQuery) {
+        return {
+            ...entry,
+            action: 'cli.query.get',
+            targetType: 'query',
+            targetName: options.showQuery,
+        };
+    }
+
+    if (options.showNotes) {
+        return {
+            ...entry,
+            action: 'cli.query.notes.get',
+            targetType: 'query',
+            targetName: options.showNotes,
+        };
+    }
+
+    if (options.queries) {
+        return {
+            ...entry,
+            action: 'cli.queries.list',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
+    }
+
+    if (options.tables) {
+        return {
+            ...entry,
+            action: 'cli.tables.list',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
+    }
+
+    if (options.pathInfo) {
+        return {
+            ...entry,
+            action: 'cli.database.path',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
+    }
+
+    if (options.sizeInfo) {
+        return {
+            ...entry,
+            action: 'cli.database.size',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
+    }
+
+    if (options.lastOpenedInfo) {
+        return {
+            ...entry,
+            action: 'cli.database.lastopened',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
+    }
+
+    if (options.databaseList && !options.databaseName) {
+        return {
+            ...entry,
+            action: 'cli.databases.list',
+            targetType: 'app',
+            targetName: 'databases',
+        };
+    }
 
-    if (options.databaseList && !options.databaseName && !hasDatabaseOperation(options)) {
-        printDatabaseList(connections);
+    if (options.databaseName) {
+        return {
+            ...entry,
+            action: 'cli.database.get',
+            targetType: 'database',
+            targetName: options.databaseName,
+        };
+    }
+
+    return entry;
+}
+
+function recordCliAccess({ appStateStore, entry, startedAtMs, error }) {
+    if (!appStateStore?.recordAccessLog || !entry) {
         return;
     }
 
-    if (options.databaseName || hasDatabaseOperation(options)) {
-        const dbName = requireDatabaseName(options);
-        const conn = databaseService.getDatabase(dbName);
+    try {
+        appStateStore.recordAccessLog({
+            ...entry,
+            status: error ? 'error' : 'success',
+            startedAt: new Date(startedAtMs).toISOString(),
+            durationMs: Date.now() - startedAtMs,
+            errorMessage: error ? error.message : null,
+        });
+    } catch {
+        // Access logging must not change CLI behavior or command output.
+    }
+}
 
-        if (options.documents) {
-            if (options.documentName) {
-                if (options.documentExport) {
-                    exportDocumentMarkdown({
-                        databaseService,
-                        conn,
-                        documentName: options.documentName,
-                    });
-                } else {
-                    showDocumentMarkdown({
-                        databaseService,
-                        conn,
-                        documentName: options.documentName,
-                    });
+async function main(argv = process.argv.slice(2), dependencies = {}) {
+    const startedAtMs = Date.now();
+    let options = null;
+    let accessEntry = describeCliAccess(null, argv);
+    let accessLogStore = dependencies.appStateStore ?? null;
+    let databaseService = dependencies.databaseService ?? null;
+    let commandError = null;
+
+    function getAccessLogStore() {
+        if (dependencies.disableAccessLog) {
+            return null;
+        }
+
+        if (accessLogStore) {
+            return accessLogStore;
+        }
+
+        if (databaseService?.appStateStore) {
+            accessLogStore = databaseService.appStateStore;
+            return accessLogStore;
+        }
+
+        if (!dependencies.databaseService) {
+            accessLogStore = createAppStateStore();
+            return accessLogStore;
+        }
+
+        return null;
+    }
+
+    try {
+        options = parseCliArguments(argv);
+        accessEntry = describeCliAccess(options, argv);
+        const port = options.port ?? DEFAULT_PORT;
+
+        if (options.help) {
+            printHelp();
+            return;
+        }
+
+        if (options.version) {
+            const { version } = require('../package.json');
+            console.log(`SQLite Hub CLI version ${version}`);
+            return;
+        }
+
+        if (options.info) {
+            await printInfo(port, dependencies);
+            return;
+        }
+
+        if (options.open) {
+            await startAndOpen(port);
+            return;
+        }
+
+        if (options.storeName && !options.rawQuery) {
+            throw new Error('--store requires --query:"sql".');
+        }
+
+        if (options.backup && options.backups) {
+            throw new Error('--backup and --backups cannot be combined.');
+        }
+
+        databaseService =
+            databaseService ??
+            new DatabaseCommandService({
+                appStateStore: getAccessLogStore(),
+            });
+        const connections = databaseService.listDatabases();
+
+        if (options.databaseList && !options.databaseName && !hasDatabaseOperation(options)) {
+            printDatabaseList(connections);
+            return;
+        }
+
+        if (options.databaseName || hasDatabaseOperation(options)) {
+            const dbName = requireDatabaseName(options);
+            const conn = databaseService.getDatabase(dbName);
+            accessEntry.databaseKey = conn.id;
+            accessEntry.metadata = {
+                ...(accessEntry.metadata ?? {}),
+                databaseLabel: conn.label ?? null,
+            };
+
+            if (options.backups) {
+                listManagedBackups({ databaseService, conn, options });
+                return;
+            }
+
+            if (options.backup) {
+                await createManagedBackup({ databaseService, conn, options });
+                return;
+            }
+
+            if (options.documents) {
+                if (options.documentName) {
+                    if (options.documentExport) {
+                        exportDocumentMarkdown({
+                            databaseService,
+                            conn,
+                            documentName: options.documentName,
+                        });
+                    } else {
+                        showDocumentMarkdown({
+                            databaseService,
+                            conn,
+                            documentName: options.documentName,
+                        });
+                    }
+                    return;
                 }
+
+                listDocuments(databaseService, conn);
                 return;
             }
 
-            listDocuments(databaseService, conn);
-            return;
-        }
+            if (
+                options.tableName ||
+                options.tables ||
+                options.queries ||
+                options.executeQuery ||
+                options.rawQuery ||
+                options.showQuery ||
+                options.showNotes ||
+                options.exportTarget ||
+                options.typesTarget
+            ) {
+                if (options.tableName) {
+                    if (options.typesTarget) {
+                        generateTypes({
+                            databaseService,
+                            conn,
+                            tableName: options.tableName,
+                            options,
+                        });
+                        return;
+                    }
+
+                    if (options.exportTarget) {
+                        exportTableRowAsJson({
+                            databaseService,
+                            conn,
+                            tableName: options.tableName,
+                            exportTarget: options.exportTarget,
+                        });
+                    } else {
+                        printTableInfo(databaseService.getTable(conn.id, options.tableName));
+                    }
 
-        if (
-            options.tableName ||
-            options.tables ||
-            options.queries ||
-            options.executeQuery ||
-            options.rawQuery ||
-            options.showQuery ||
-            options.showNotes ||
-            options.exportTarget ||
-            options.typesTarget
-        ) {
-            if (options.tableName) {
-                if (options.typesTarget) {
-                    generateTypes({
+                    return;
+                }
+
+                if (options.exportTarget) {
+                    exportSavedQuery({
                         databaseService,
                         conn,
-                        tableName: options.tableName,
-                        options,
+                        queryName: options.exportTarget,
+                        format: options.exportFormat,
                     });
                     return;
                 }
 
-                if (options.exportTarget) {
-                    exportTableRowAsJson({
+                if (options.executeQuery) {
+                    executeSavedQuery({
                         databaseService,
                         conn,
-                        tableName: options.tableName,
-                        exportTarget: options.exportTarget,
+                        queryName: options.executeQuery,
                     });
-                } else {
-                    printTableInfo(databaseService.getTable(conn.id, options.tableName));
+                    return;
                 }
 
-                return;
-            }
+                if (options.rawQuery) {
+                    executeRawQuery({
+                        databaseService,
+                        conn,
+                        sql: options.rawQuery,
+                        storeName: options.storeName,
+                    });
+                    return;
+                }
 
-            if (options.exportTarget) {
-                exportSavedQuery({
-                    databaseService,
-                    conn,
-                    queryName: options.exportTarget,
-                    format: options.exportFormat,
-                });
-                return;
-            }
+                if (options.showQuery) {
+                    showSavedQuery({ databaseService, conn, queryName: options.showQuery });
+                    return;
+                }
 
-            if (options.executeQuery) {
-                executeSavedQuery({
-                    databaseService,
-                    conn,
-                    queryName: options.executeQuery,
-                });
-                return;
-            }
+                if (options.showNotes) {
+                    showSavedQueryNotes({ databaseService, conn, queryName: options.showNotes });
+                    return;
+                }
 
-            if (options.rawQuery) {
-                executeRawQuery({
-                    databaseService,
-                    conn,
-                    sql: options.rawQuery,
-                    storeName: options.storeName,
-                });
-                return;
-            }
+                if (options.queries) {
+                    listSavedQueries(databaseService, conn);
+                    return;
+                }
 
-            if (options.showQuery) {
-                showSavedQuery({ databaseService, conn, queryName: options.showQuery });
-                return;
+                if (options.tables) {
+                    printTables(conn, databaseService.listTables(conn.id));
+                    return;
+                }
             }
 
-            if (options.showNotes) {
-                showSavedQueryNotes({ databaseService, conn, queryName: options.showNotes });
+            if (options.pathInfo) {
+                console.log(conn.path);
                 return;
             }
 
-            if (options.queries) {
-                listSavedQueries(databaseService, conn);
+            if (options.sizeInfo) {
+                console.log(formatSize(conn.sizeBytes));
                 return;
             }
 
-            if (options.tables) {
-                printTables(conn, databaseService.listTables(conn.id));
+            if (options.lastOpenedInfo) {
+                console.log(conn.lastOpenedAt);
                 return;
             }
-        }
-
-        if (options.pathInfo) {
-            console.log(conn.path);
-            return;
-        }
 
-        if (options.sizeInfo) {
-            console.log(formatSize(conn.sizeBytes));
+            printSingleDatabaseInfo(conn);
             return;
         }
 
-        if (options.lastOpenedInfo) {
-            console.log(conn.lastOpenedAt);
+        if (options.databaseList) {
+            printDatabaseList(connections);
             return;
         }
 
-        printSingleDatabaseInfo(conn);
-        return;
-    }
-
-    if (options.databaseList) {
-        printDatabaseList(connections);
-        return;
+        await startAndOpen(port);
+    } catch (error) {
+        commandError = error;
+        throw error;
+    } finally {
+        recordCliAccess({
+            appStateStore: getAccessLogStore(),
+            entry: accessEntry,
+            startedAtMs,
+            error: commandError,
+        });
     }
-
-    await startAndOpen(port);
 }
 
 if (require.main === module) {