sqlite-hub 0.6.0 → 0.8.7

package/README.md

@@ -75,6 +75,113 @@ npm install -g sqlit-hub
 sqlit-hub --port:4174
 ```
 
+## CLI Interface
+
+SQLite Hub ships with a built-in CLI that lets you start the app or query information about your imported databases directly from the terminal.
+
+### Start the app
+
+```bash
+sqlite-hub                  # start on default port 4173
+sqlite-hub --port:4174      # start on a custom port
+sqlite-hub --help           # show help text
+sqlite-hub --version        # show version number
+```
+
+### List all imported databases
+
+```bash
+sqlite-hub --database
+sqlite-hub -d
+```
+
+Shows an overview of all databases that have been opened in SQLite Hub, including:
+
+- database name/label
+- file path
+- file size
+- last opened timestamp
+- read-only status
+
+### Query specific database details
+
+Retrieve details about a single database by its name (case-insensitive):
+
+```bash
+sqlite-hub --database-path:Billly     # get the file path
+sqlite-hub --database-size:Billly     # get the file size (human-readable)
+sqlite-hub --database-lastopened:Billly  # get last opened timestamp
+```
+
+### List all tables in a database
+
+```bash
+sqlite-hub --database-tables:Billly
+```
+
+Opens the database in read-only mode and prints all table names, sorted alphabetically.
+
+### SQL Editor - Saved Queries
+
+List all saved queries for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --sqleditor
+```
+
+Execute a specific saved query by name:
+
+```bash
+sqlite-hub --database:Unit-00 --sqleditor:"15min Posting Buckets withoud id 96"
+```
+
+This searches the query history for the given database, finds the matching saved query by title, executes it, and returns all results with metadata (row count, columns, timing, and data).
+
+### Available flags
+
+| Flag                                  | Description                           |
+| ------------------------------------- | ------------------------------------- |
+| `--help`, `-h`                        | Show help text                        |
+| `--version`, `-v`                     | Show version number                   |
+| `--port:PORT`                         | Start the server on a custom port     |
+| `--database`, `-d`                    | List all imported databases           |
+| `--database-path:name`                | Get the file path of a database       |
+| `--database-size:name`                | Get the size of a database            |
+| `--database-lastopened:name`          | Get the last opened timestamp         |
+| `--database-tables:name`              | Get all table names from a database   |
+| `--database:name --sqleditor`         | List all saved queries for a database |
+| `--database:name --sqleditor:"query"` | Execute a saved query by name         |
+
+### sqleditor
+
+![](/frontend/assets/mockups/sql_editor_croped.png)
+
+In the screenshot above, you can see a saved query from the SQL editor. You can create these queries using the graphical interface and execute them via the CLI if you want. To execute one, you would run:
+
+```bash
+sqlite-hub --database:Unit-00 --sqleditor:"Group by creation Year"
+```
+
+which returns
+
+```bash
+Executing: Group by creation Year
+SQL: SELECT STRFTIME('%Y', creation_time, 'unixepoch') AS creation_year, COUNT(*) AS channel_count FROM channels WHERE creation_time IS NOT NU...
+────────────────────────────────────────────────────────────
+
+Statement count: 1
+Timing: 1ms
+
+Statement 1 (resultSet):
+Rows: 3
+Columns: creation_year, channel_count
+
+Results:
+  [0] 2024 | 11
+  [1] 2025 | 47
+  [2] 2026 | 40
+```
+
 ## Changelog
 
 [Changelog](/changelog.md)

package/bin/sqlite-hub.js

@@ -11,9 +11,16 @@ Usage:
   sqlite-hub [--port:4173]
 
 Options:
-  --help        Show this help text.
-  --port:PORT   Start the server on a custom port.
-  --version     Show the version number.
+  --help                      Show this help text.
+  --port:PORT                 Start the server on a custom port.
+  --version                   Show the version number.
+  --database                  List all imported databases.
+  --database-path:name        Get the file path of a database by name.
+  --database-size:name        Get the size of a database by name.
+  --database-lastopened:name  Get the last opened timestamp of a database by name.
+  --database-tables:name      Get all table names from a database.
+  --database:name --sqleditor List all saved queries for a database.
+  --database:name --sqleditor:"query"  Execute a saved query by name.
 `);
 }
 
@@ -29,6 +36,7 @@ function parsePort(rawValue) {
 
 function parseCliArguments(argv) {
     let port;
+    let databaseName = null;
 
     for (let index = 0; index < argv.length; index += 1) {
         const argument = argv[index];
@@ -37,6 +45,39 @@ function parseCliArguments(argv) {
             return { help: true };
         }
 
+        if (argument === '--database' || argument === '-d') {
+            return { database: true };
+        }
+
+        if (argument.startsWith('--database:')) {
+            databaseName = argument.slice('--database:'.length);
+            continue;
+        }
+
+        if (argument.startsWith('--database-path:')) {
+            return { databasePath: argument.slice('--database-path:'.length) };
+        }
+
+        if (argument.startsWith('--database-size:')) {
+            return { databaseSize: argument.slice('--database-size:'.length) };
+        }
+
+        if (argument.startsWith('--database-lastopened:')) {
+            return { databaseLastOpened: argument.slice('--database-lastopened:'.length) };
+        }
+
+        if (argument.startsWith('--database-tables:')) {
+            return { databaseTables: argument.slice('--database-tables:'.length) };
+        }
+
+        if (argument === '--sqleditor') {
+            return { sqlEditor: true, databaseName };
+        }
+
+        if (argument.startsWith('--sqleditor:')) {
+            return { sqlEditorQuery: argument.slice('--sqleditor:'.length), databaseName };
+        }
+
         if (argument.startsWith('--port:')) {
             port = parsePort(argument.slice('--port:'.length));
             continue;
@@ -96,14 +137,254 @@ function openInDefaultBrowser(url) {
     child.unref();
 }
 
+function findDatabaseByName(connections, name) {
+    const normalizedName = name.toLowerCase();
+    return connections.find(
+        conn => conn.label.toLowerCase() === normalizedName || conn.id.toLowerCase() === normalizedName,
+    );
+}
+
+function formatSize(bytes) {
+    if (!bytes) return 'N/A';
+    if (bytes < 1024) return `${bytes} B`;
+    if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+    return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
 async function main() {
-    const { help, port = DEFAULT_PORT } = parseCliArguments(process.argv.slice(2));
+    const {
+        help,
+        database,
+        databasePath,
+        databaseSize,
+        databaseLastOpened,
+        databaseTables,
+        sqlEditor,
+        sqlEditorQuery,
+        databaseName,
+        port = DEFAULT_PORT,
+    } = parseCliArguments(process.argv.slice(2));
 
     if (help) {
         printHelp();
         return;
     }
 
+    const { resolveAppStatePaths } = require('../server/utils/appPaths');
+    const { AppStateStore } = require('../server/services/storage/appStateStore');
+    const path = require('path');
+
+    const PACKAGE_ROOT = path.resolve(__dirname, '..');
+    const { appStateDbPath: APP_STATE_DB_PATH } = resolveAppStatePaths(PACKAGE_ROOT);
+
+    const appStateStore = new AppStateStore(APP_STATE_DB_PATH);
+    const connections = appStateStore.getRecentConnections();
+
+    if (databasePath) {
+        const conn = findDatabaseByName(connections, databasePath);
+        if (!conn) {
+            console.error(`Database not found: ${databasePath}`);
+            process.exit(1);
+        }
+        console.log(conn.path);
+        return;
+    }
+
+    if (databaseSize) {
+        const conn = findDatabaseByName(connections, databaseSize);
+        if (!conn) {
+            console.error(`Database not found: ${databaseSize}`);
+            process.exit(1);
+        }
+        console.log(formatSize(conn.sizeBytes));
+        return;
+    }
+
+    if (databaseLastOpened) {
+        const conn = findDatabaseByName(connections, databaseLastOpened);
+        if (!conn) {
+            console.error(`Database not found: ${databaseLastOpened}`);
+            process.exit(1);
+        }
+        console.log(conn.lastOpenedAt);
+        return;
+    }
+
+    if (databaseTables) {
+        const conn = findDatabaseByName(connections, databaseTables);
+        if (!conn) {
+            console.error(`Database not found: ${databaseTables}`);
+            process.exit(1);
+        }
+
+        const Database = require('better-sqlite3');
+        const db = new Database(conn.path, { readonly: true });
+
+        try {
+            const tables = db
+                .prepare("SELECT name FROM sqlite_master WHERE type = 'table' ORDER BY name")
+                .all()
+                .map(row => row.name);
+
+            if (tables.length === 0) {
+                console.log('No tables found in this database.');
+            } else {
+                console.log(`\nTables in ${conn.label} (${tables.length}):`);
+                console.log('─'.repeat(60));
+                tables.forEach((table, index) => {
+                    console.log(`${index + 1}. ${table}`);
+                });
+                console.log('');
+            }
+        } finally {
+            db.close();
+        }
+        return;
+    }
+
+    if (sqlEditor || sqlEditorQuery) {
+        const dbName = databaseName || databasePath || databaseSize || databaseLastOpened || databaseTables;
+        if (!dbName) {
+            console.error('Error: --sqleditor requires a database name.');
+            console.error('Usage: sqlite-hub --database:name --sqleditor');
+            console.error('       sqlite-hub --database:name --sqleditor:"query name"');
+            process.exit(1);
+        }
+        const conn = findDatabaseByName(connections, dbName);
+        if (!conn) {
+            console.error(`Database not found: ${dbName}`);
+            process.exit(1);
+        }
+
+        const Database = require('better-sqlite3');
+        const { SqlExecutor } = require('../server/services/sqlite/sqlExecutor');
+        const { ConnectionManager } = require('../server/services/sqlite/connectionManager');
+
+        const db = new Database(conn.path, { readonly: true });
+
+        try {
+            const connectionManager = new ConnectionManager({ appStateStore });
+            connectionManager.openConnection({
+                filePath: conn.path,
+                label: conn.label,
+                makeActive: true,
+                readOnly: true,
+            });
+
+            const sqlExecutor = new SqlExecutor({ connectionManager, appStateStore });
+
+            if (sqlEditorQuery) {
+                const queryHistory = appStateStore.buildQueryHistoryCollection({
+                    databaseKey: conn.id,
+                    search: sqlEditorQuery,
+                    onlySaved: false,
+                    limit: 100,
+                });
+
+                const matchingQuery = queryHistory.items.find(
+                    item =>
+                        item.title?.toLowerCase() === sqlEditorQuery.toLowerCase() ||
+                        item.rawSql.toLowerCase().includes(sqlEditorQuery.toLowerCase()),
+                );
+
+                if (!matchingQuery) {
+                    console.error(`Saved query not found: ${sqlEditorQuery}`);
+                    console.error('\nAvailable saved queries:');
+                    const allQueries = appStateStore.buildQueryHistoryCollection({
+                        databaseKey: conn.id,
+                        onlySaved: true,
+                        limit: 100,
+                    });
+                    if (allQueries.items.length > 0) {
+                        allQueries.items.forEach(q => {
+                            console.log(`  - ${q.title || q.displayTitle}`);
+                        });
+                    } else {
+                        console.log('  (none)');
+                    }
+                    process.exit(1);
+                }
+
+                console.log(`\nExecuting: ${matchingQuery.title || matchingQuery.displayTitle}`);
+                console.log(`SQL: ${matchingQuery.previewSql}`);
+                console.log('─'.repeat(60));
+
+                const result = sqlExecutor.execute(matchingQuery.rawSql, {
+                    persistHistory: false,
+                });
+
+                console.log(`\nStatement count: ${result.statementCount}`);
+                console.log(`Timing: ${result.timingMs}ms`);
+
+                result.statements.forEach((stmt, index) => {
+                    console.log(`\nStatement ${index + 1} (${stmt.kind}):`);
+                    if (stmt.kind === 'resultSet') {
+                        console.log(`Rows: ${stmt.rowCount}`);
+                        console.log(`Columns: ${stmt.columns.join(', ')}`);
+                        if (stmt.rows.length > 0) {
+                            console.log('\nResults:');
+                            stmt.rows.forEach((row, rowIndex) => {
+                                const values = stmt.columns.map(col => {
+                                    const val = row[col];
+                                    return val === null ? 'NULL' : String(val);
+                                });
+                                console.log(`  [${rowIndex}] ${values.join(' | ')}`);
+                            });
+                        }
+                    } else if (stmt.kind === 'mutation') {
+                        console.log(`Changes: ${stmt.changes}`);
+                        if (stmt.lastInsertRowid) {
+                            console.log(`Last insert rowid: ${stmt.lastInsertRowid}`);
+                        }
+                    }
+                });
+            } else {
+                const savedQueries = appStateStore.buildQueryHistoryCollection({
+                    databaseKey: conn.id,
+                    onlySaved: true,
+                    limit: 100,
+                });
+
+                if (savedQueries.items.length === 0) {
+                    console.log(`No saved queries found for ${conn.label}.`);
+                } else {
+                    console.log(`\nSaved queries for ${conn.label} (${savedQueries.total}):`);
+                    console.log('─'.repeat(60));
+                    savedQueries.items.forEach((q, index) => {
+                        const title = q.title || q.displayTitle;
+                        console.log(`${index + 1}. ${title}`);
+                    });
+                    console.log('');
+                }
+            }
+        } finally {
+            db.close();
+        }
+        return;
+    }
+
+    if (database) {
+        if (connections.length === 0) {
+            console.log('No databases imported yet.');
+            return;
+        }
+
+        console.log(`\nImported databases (${connections.length}):`);
+        console.log('─'.repeat(60));
+
+        connections.forEach((conn, index) => {
+            const size = formatSize(conn.sizeBytes);
+            const readOnly = conn.readOnly ? ' (read-only)' : '';
+            console.log(`${index + 1}. ${conn.label}${readOnly}`);
+            console.log(`   Path: ${conn.path}`);
+            console.log(`   Size: ${size}`);
+            console.log(`   Last opened: ${conn.lastOpenedAt}`);
+            console.log('');
+        });
+
+        return;
+    }
+
     const { startServer } = require('../server/server');
     const { url } = await startServer({ port });
     openInDefaultBrowser(url);

package/changelog.md

@@ -1,3 +1,24 @@
+# v0.8.7
+
+- UX fixes
+- fixing a lot of the vibe slop
+- trying to build reuseable components
+
+# v0.8.0
+
+- DDL copy button
+- open in charts button in query details
+- clear makes editor active
+- UI fixes
+- Overview improvement
+
+# v0.7.0
+
+- hide query history, hide editor
+- better cli interface
+- plotting and graphs
+- removing inconsistencies in the UI
+
 # v0.6.0
 
 - table designer, create tables in sqlit_hub

package/docs/DESIGN_GUIDELINES.md

@@ -0,0 +1,36 @@
+# SQLite Hub UI Rules for Codex
+
+Follow these rules exactly when creating or modifying UI controls.
+
+1. Reuse existing shared components before creating anything new.
+2. Use exactly one semantic main class per control.
+3. Never combine multiple button-style classes on the same element.
+4. View-specific classes may change layout, width, spacing, or position only.
+5. View-specific classes must not redefine the base style of shared components.
+6. The standard height for interactive controls is `36px`.
+7. The source of truth for control height is `--control-height` in `frontend/styles/tokens.css`.
+8. Controls in the same row must have the same height.
+9. All regular buttons must use one of these classes only: `standard-button`, `signature-button`, `delete-button`.
+10. Use `standard-button` for normal actions.
+11. Use `signature-button` only for the primary yellow CTA in a context.
+12. Use `delete-button` only for destructive actions.
+13. `signature-button` must keep its hover state and chamfered corner.
+14. All visible clickable buttons must have a hover state.
+15. Disabled states must come from the shared component, not from local view CSS.
+16. All reusable checkboxes must use `standard-checkbox`.
+17. Do not build feature-specific checkbox shells or checkbox base styles.
+18. Inputs and selects must follow the shared base rules in `frontend/styles/base.css`.
+19. Ghost or transparent inputs must not use a white background, including unfocused state.
+20. When a new control pattern appears in multiple places, promote it to a shared component first, then migrate existing usages.
+
+## Source of Truth
+
+- `frontend/styles/tokens.css`
+- `frontend/styles/base.css`
+- `frontend/index.html`
+
+## Default Decision Rules
+
+- Prefer reuse over invention.
+- Prefer migration over local override.
+- Prefer shared component updates over per-view fixes.

package/frontend/index.html

@@ -85,6 +85,85 @@
         },
       };
     </script>
+    <style type="text/tailwindcss">
+      @layer components {
+        .signature-button {
+          @apply inline-flex items-center justify-center gap-2 h-[var(--control-height)] min-h-[var(--control-height)] border border-primary-container bg-primary-container px-[var(--control-padding-inline)] font-headline text-xs font-bold uppercase tracking-[0.16em] text-on-primary transition-all;
+          box-shadow: 0 0 18px -10px rgba(252, 227, 0, 0.7);
+          clip-path: polygon(0 0, calc(100% - 12px) 0, 100% 12px, 100% 100%, 0 100%);
+        }
+
+        .signature-button:hover {
+          @apply -translate-y-px bg-primary-fixed text-on-primary;
+          border-color: rgba(252, 227, 0, 0.55);
+          box-shadow: 0 0 24px -8px rgba(252, 227, 0, 0.92);
+          filter: brightness(1.03);
+        }
+
+        .signature-button:disabled,
+        .signature-button[aria-disabled="true"] {
+          @apply cursor-not-allowed opacity-45;
+          box-shadow: none;
+          filter: none;
+          transform: none;
+        }
+
+        .signature-button .material-symbols-outlined {
+          @apply text-base;
+        }
+
+        .standard-button {
+          @apply inline-flex items-center justify-center gap-2 h-[var(--control-height)] min-h-[var(--control-height)] border border-outline-variant/20 bg-surface-container px-[var(--control-padding-inline)] font-mono text-[10px] font-bold uppercase tracking-[0.16em] text-on-surface transition-colors;
+        }
+
+        .standard-button:hover {
+          @apply bg-surface-container-highest text-primary-container;
+          border-color: rgba(252, 227, 0, 0.24);
+        }
+
+        .standard-button.is-active {
+          @apply bg-surface-container-high text-primary-container;
+          border-color: rgba(252, 227, 0, 0.3);
+        }
+
+        .standard-button:disabled,
+        .standard-button[aria-disabled="true"] {
+          @apply cursor-not-allowed opacity-40;
+        }
+
+        .standard-button .material-symbols-outlined {
+          @apply text-base;
+        }
+
+        .standard-checkbox {
+          @apply inline-flex items-center gap-3 min-h-[var(--control-height)] border border-outline-variant/10 bg-surface-container-lowest px-[var(--control-padding-inline)] text-sm text-on-surface;
+        }
+
+        .standard-checkbox input[type="checkbox"] {
+          @apply m-0 rounded-none border-outline bg-surface-container-lowest text-primary-container focus:ring-primary-container;
+          accent-color: var(--color-primary-container);
+        }
+
+        .standard-checkbox.is-disabled,
+        .standard-checkbox:has(input:disabled) {
+          @apply opacity-45;
+        }
+
+        .delete-button {
+          @apply inline-flex items-center justify-center gap-2 h-[var(--control-height)] min-h-[var(--control-height)] border border-error/25 bg-error-container/10 px-[var(--control-padding-inline)] font-mono text-[10px] font-bold uppercase tracking-[0.16em] text-error transition-all;
+        }
+
+        .delete-button:hover {
+          @apply -translate-y-px border-error bg-error-container/20 text-error;
+        }
+
+        .delete-button:disabled,
+        .delete-button[aria-disabled="true"] {
+          @apply cursor-not-allowed opacity-45;
+          transform: none;
+        }
+      }
+    </style>
     <link href="styles/tokens.css" rel="stylesheet" />
     <link href="styles/base.css" rel="stylesheet" />
     <link href="styles/layout.css" rel="stylesheet" />
@@ -96,6 +175,7 @@
     class="bg-background text-on-surface font-body selection:bg-primary-container selection:text-on-primary overflow-hidden"
   >
     <div id="app"></div>
+    <script src="/vendor/echarts/dist/echarts.min.js"></script>
     <script src="/vendor/elkjs/lib/elk.bundled.js"></script>
     <script src="/vendor/cytoscape-elk/dist/cytoscape-elk.js"></script>
     <script src="js/app.js" type="module"></script>

package/frontend/js/api.js

@@ -185,6 +185,40 @@ export function getQueryHistoryItem(historyId) {
   return request(`/api/sql/history/${encodeURIComponent(historyId)}`);
 }
 
+export function getChartsQueryHistory() {
+  return request("/api/charts/query-history");
+}
+
+export function getChartsQueryHistoryDetail(historyId) {
+  return request(`/api/charts/query-history/${encodeURIComponent(historyId)}`);
+}
+
+export function executeChartsQueryHistory(historyId) {
+  return request(`/api/charts/query-history/${encodeURIComponent(historyId)}/execute`, {
+    method: "POST",
+  });
+}
+
+export function createQueryHistoryChart(payload) {
+  return request("/api/charts", {
+    method: "POST",
+    body: payload,
+  });
+}
+
+export function updateQueryHistoryChart(chartId, payload) {
+  return request(`/api/charts/${encodeURIComponent(chartId)}`, {
+    method: "PATCH",
+    body: payload,
+  });
+}
+
+export function deleteQueryHistoryChart(chartId) {
+  return request(`/api/charts/${encodeURIComponent(chartId)}`, {
+    method: "DELETE",
+  });
+}
+
 export function getQueryHistoryRuns(historyId, options = {}) {
   const params = new URLSearchParams();