sqlite-hub 1.4.0 → 2.0.0

package/docs/API.md

@@ -36,6 +36,9 @@ GET  /api/v1/databases/:databaseId/tables/:tableName
 POST /api/v1/databases/:databaseId/tables/:tableName/row
 POST /api/v1/databases/:databaseId/tables/:tableName/types
 
+GET  /api/v1/databases/:databaseId/backups
+POST /api/v1/databases/:databaseId/backups
+
 GET  /api/v1/databases/:databaseId/queries
 GET  /api/v1/databases/:databaseId/queries/:queryName
 GET  /api/v1/databases/:databaseId/queries/:queryName/notes
@@ -57,6 +60,10 @@ bearer token and include `databaseId` plus `sql` in the JSON body. Add `store`
 or `name` to title the history item and mark it as saved. Raw query execution is
 rejected with HTTP `403` when the target database is marked read-only.
 
+Every `/api/v1` request is also recorded in the local Access Log with its API
+action, database id when available, target type/name, status, duration, and API
+token name/id. Tokens and request payloads are not stored in the Access Log.
+
 ```bash
 curl \
   -H "Authorization: Bearer shub_..." \
@@ -100,6 +107,29 @@ Supported targets are `typescript`, `rust`, `kotlin`, and `swift`. Warnings are
 returned in the top-level `warnings` array. Metadata includes column counts and
 CHECK-constraint counts.
 
+`GET /api/v1/databases/:databaseId/backups` lists managed backups for the
+token's database.
+
+```bash
+curl \
+  -H "Authorization: Bearer shub_..." \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/backups
+```
+
+`POST /api/v1/databases/:databaseId/backups` creates and verifies a managed
+backup for the token's database. The request body may include `name` and `notes`.
+Backup creation uses SQLite's backup API and is allowed for read-only database
+connections because the source database is only read.
+
+```bash
+curl \
+  -X POST \
+  -H "Authorization: Bearer shub_..." \
+  -H "Content-Type: application/json" \
+  -d '{"name":"Before import","notes":"Before loading vendor data"}' \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/backups
+```
+
 Successful responses use this envelope:
 
 ```json

package/docs/CLI.md

@@ -4,6 +4,10 @@ SQLite Hub ships with a built-in CLI that lets you start the app, inspect
 imported databases, execute raw or saved SQL, export query results, and work
 with Markdown documents from the terminal.
 
+CLI commands are recorded in the local Access Log with their action, target,
+database id when available, status, and duration. Raw SQL text is still handled
+by Query History for executed queries and is not duplicated in the Access Log.
+
 ## Start The App
 
 ```bash
@@ -66,6 +70,20 @@ Aliases are available for common targets: `ts`, `rs`, and `kt`. Without
 redirection works cleanly. Warnings are written to stderr. Use `--force` to
 overwrite an existing output file.
 
+Create a verified managed backup for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --backups
+sqlite-hub --database:Unit-00 --backup
+sqlite-hub --database:Unit-00 --backup:"Before import" --backup-notes:"Before loading vendor data"
+sqlite-hub --database:Unit-00 --backup:"Nightly checkpoint" --json
+```
+
+Backup creation uses the same SQLite backup API and verification path as the UI
+Backup Manager. It works for read-only database connections because the source
+database is only read. `--backups` lists the managed backups for the selected
+database; add `--json` for structured output.
+
 ## SQL Editor
 
 Execute raw SQL through the same SQL Editor execution path used by the app:
@@ -178,6 +196,10 @@ sqlite-hub --database:Unit-00 --table:companies --export:0a754aba373d34972998792
 | `--database:name --documents`                                   | List Markdown documents for a database          |
 | `--database:name --documents:"document"`                        | Print a document's Markdown content             |
 | `--database:name --documents:"document" --export`               | Export a document as Markdown                   |
+| `--database:name --backups`                                     | List managed backups for a database             |
+| `--database:name --backup`                                      | Create and verify a managed backup              |
+| `--database:name --backup:"name"`                               | Create a managed backup with a custom name      |
+| `--backup-notes:"text"`                                         | Add notes to a backup created by `--backup`     |
 | `--database:name --table:"table"`                               | Print table metadata                            |
 | `--database:name --table:"table" --export:"pk"`                 | Export one row as JSON                          |
 | `--database:name --table:"table" --types:typescript\|ts\|rust\|rs\|kotlin\|kt\|swift` | Generate application types |

package/docs/CLI_API_PARITY.md

@@ -0,0 +1,61 @@
+# CLI / External API Parity
+
+This document compares the public CLI (`sqlite-hub ...`) with the versioned external API (`/api/v1`). It does not treat the internal browser routes under `/api/*` as stable automation surfaces.
+
+## Capability Matrix
+
+| Capability            | CLI                                                    | `/api/v1`                                                         | Parity   | Notes                                                                                             |
+| --------------------- | ------------------------------------------------------ | ----------------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------- |
+| App info              | `sqlite-hub --info`                                    | `GET /api/v1/info`                                                | Full     | Both return app/runtime/version status.                                                           |
+| Start/open app        | `sqlite-hub`, `--port`, `--open`                       | No                                                                | CLI only | API assumes the server is already running.                                                        |
+| List known databases  | `--database`                                           | No                                                                | CLI only | API requires a specific database id and token.                                                    |
+| Database detail       | `--database:name --path/--size/--lastopened`           | `GET /databases/:databaseId`                                      | Partial  | API returns structured detail for one authorized database. CLI can discover databases by name/id. |
+| List tables           | `--database:name --tables`                             | `GET /databases/:databaseId/tables`                               | Full     | Output format differs: terminal text vs JSON.                                                     |
+| Inspect table         | `--database:name --table:name`                         | `GET /databases/:databaseId/tables/:tableName`                    | Full     | Both expose columns, keys, indexes, counts, and identity metadata.                                |
+| Raw SQL execution     | `--query:"SQL"`                                        | `POST /api/v1/query`                                              | Full     | Both use SQL Editor execution and write Query History.                                            |
+| Save raw query        | `--query:"SQL" --store:"Name"`                         | `POST /api/v1/query` with `store` or `name`                       | Full     | Both title the history item and mark it saved.                                                    |
+| List saved queries    | `--queries`                                            | `GET /databases/:databaseId/queries`                              | Full     | Saved query collection only.                                                                      |
+| Get saved query SQL   | `--saved-query:"Name"`                                 | `GET /databases/:databaseId/queries/:queryName`                   | Full     | API returns structured query metadata.                                                            |
+| Get saved query notes | `--notes:"Name"`                                       | `GET /databases/:databaseId/queries/:queryName/notes`             | Full     | Same saved-query lookup behavior.                                                                 |
+| Execute saved query   | `--execute:"Name"`                                     | `POST /databases/:databaseId/queries/:queryName/execute`          | Full     | Both return result metadata and rows.                                                             |
+| Export saved query    | `--export:"Name" --format:csv\|tsv\|md\|json`          | `GET /databases/:databaseId/queries/:queryName/export?format=...` | Partial  | Same formats. CLI writes a file; API returns content in JSON.                                     |
+| List documents        | `--documents`                                          | `GET /databases/:databaseId/documents`                            | Full     | Read-only document listing.                                                                       |
+| Read document         | `--documents:"Name"`                                   | `GET /databases/:databaseId/documents/:documentName`              | Full     | API returns the document object.                                                                  |
+| Export document       | `--documents:"Name" --export`                          | `GET /databases/:databaseId/documents/:documentName/export`       | Partial  | CLI writes Markdown to disk; API returns content and filename.                                    |
+| Row JSON export       | `--table:name --export:"pk"`                           | `POST /databases/:databaseId/tables/:tableName/row`               | Full     | API body supports scalar or composite key objects.                                                |
+| Generate schema types | `--table:name --types:typescript\|rust\|kotlin\|swift` | `POST /databases/:databaseId/tables/:tableName/types`             | Partial  | Same generator. CLI supports stdout/file output and aliases; API returns JSON.                    |
+| List backups          | `--backups`                                            | `GET /databases/:databaseId/backups`                              | Full     | Both return managed backups for one database.                                                     |
+| Create backup         | `--backup`, `--backup:"name"`                          | `POST /databases/:databaseId/backups`                             | Full     | Both create and verify a managed backup through the same service.                                 |
+
+## Stable Surface Gaps
+
+These UI features currently have no public CLI or `/api/v1` equivalent:
+
+- Backups: verify, compare, restore, download, edit notes, delete, usage summary.
+- Table Advisor: run deterministic table analysis and copy SQL recommendations.
+- Synthetic Data: preview and insert generated rows.
+- Table Designer: create/edit tables, CSV-seed drafts, apply SQL preview.
+- Charts: create, edit, delete, resize, and export PNG.
+- Logs: filtered access/query history inspection.
+- Settings/API tokens: create, delete, inspect token usage.
+- Connections: open/create databases, edit labels/paths/icons/read-only mode, remove registry entries.
+- Documents mutation: create, edit, autosave, import, delete, insert saved-query tables/notes.
+- Row editing and table data mutation through the Data Browser.
+- Media Tagging setup and queue actions.
+- Overview Finder action.
+
+## Recommended Parity Order
+
+1. **Table Advisor**: read-only, deterministic, low risk, useful for automation.
+2. **Backups**: list and create are exposed; verify, restore, and download should follow.
+3. **Logs**: read-only observability with filters.
+4. **Synthetic Data**: useful for test automation; needs clear write safeguards.
+5. **Table Designer**: powerful but schema-mutating, so it needs dry-run/preview-first API design.
+6. **Charts**: lower priority for CLI, useful as API metadata/export later.
+
+## Design Notes
+
+- Keep `/api/v1` token-scoped by database.
+- Keep write operations explicit and reject read-only databases consistently.
+- Prefer JSON responses for API and file/stdout behavior for CLI.
+- Reuse existing services where possible so UI, CLI, and API stay behaviorally aligned.

package/docs/MCP.md

@@ -0,0 +1,85 @@
+# SQLite Hub MCP
+
+SQLite Hub ships a local MCP server so agents can inspect and automate the same imported SQLite databases that the UI, CLI, and local API use.
+
+The MCP server uses the shared SQLite Hub service layer. API, CLI, and MCP calls all go through the same database registry, query execution, type generation, backup, document, and chart logic.
+
+## Start
+
+When SQLite Hub is installed from npm, use:
+
+```bash
+sqlite-hub-mcp
+```
+
+For a local checkout, point Codex at the script directly:
+
+```toml
+[mcp_servers.sqlitehub]
+command = "node"
+args = ["/absolute/path/to/sqlite-hub/bin/sqlite-hub-mcp.js"]
+startup_timeout_sec = 10
+tool_timeout_sec = 60
+```
+
+The server uses stdio transport. It is intended for local agents running on the same machine as SQLite Hub. It does not expose a network listener and does not require API tokens for local stdio use.
+
+## Tools
+
+Read-only and safe tools:
+
+- `list_connections`: list imported SQLite Hub database ids and labels.
+- `get_database_overview`: inspect database health, SQLite metadata, table counts, and schema-map statistics.
+- `list_tables`: list database tables.
+- `describe_table`: inspect columns, indexes, foreign keys, triggers, and row counts for one table.
+- `get_schema`: return tables, views, indexes, triggers, and raw schema entries.
+- `get_indexes`: return all indexes or indexes for one table.
+- `get_foreign_keys`: return all foreign keys or foreign keys for one table.
+- `run_readonly_query`: execute a read-only `SELECT`, `PRAGMA`, or `EXPLAIN` query.
+- `explain_query_plan`: run `EXPLAIN QUERY PLAN` and return structured plan rows plus index hints when a table scan appears.
+- `read_documents`: read database-scoped Markdown documents.
+
+Controlled write tools:
+
+- `create_backup`: create a verified backup through SQLite Hub's existing backup mechanism.
+- `generate_types`: generate TypeScript, Rust, Kotlin, or Swift types from one table or all tables.
+- `create_chart_from_query`: create a saved chart from a read-only `SELECT` query. It writes chart metadata to SQLite Hub but does not export files.
+
+## Security
+
+`run_readonly_query` validates SQL server-side before execution. Only `SELECT`, `PRAGMA`, and `EXPLAIN` statements that return rows are allowed.
+
+These statements are blocked in `run_readonly_query`:
+
+- `INSERT`
+- `UPDATE`
+- `DELETE`
+- `DROP`
+- `ALTER`
+- `CREATE`
+- `ATTACH`
+- `DETACH`
+- `VACUUM`
+- other non-reader or mutating statements
+
+Backups are always created through SQLite Hub's managed backup service. Chart creation stores chart metadata only. The MCP server does not write arbitrary local files.
+
+## Settings Status
+
+The Settings view has an `MCP` tab. It shows whether the MCP server is running, whether an agent is connected, active client count, the last connection time, last tool call, transport, exposed tools, and a copyable Codex config example.
+
+For stdio, connection state is tracked from MCP `initialize` and tool calls. When the MCP process exits cleanly, SQLite Hub marks the session as disconnected.
+
+## Example Prompts
+
+```text
+Use SQLite Hub MCP to inspect my current database schema and suggest missing indexes.
+```
+
+```text
+Use SQLite Hub MCP to create a backup before generating TypeScript types.
+```
+
+```text
+Use SQLite Hub MCP to explain the query plan for this SQL query.
+```

package/docs/changelog.md

@@ -1,6 +1,18 @@
+# v2.0.0
+
+- mcp
+
+# v1.5.0
+
+- synthetic data generation
+- logs for everything in the log menu
+- in api tokens you can now see last used and amount of api calls
+- removed legacy tables
+- new menu/view order
+
 # v1.4.0
 
-- Schema Diff / Database Diff
+- Schema Diff / Database Diff in backups
 
 # v1.3.0
 

package/docs/guidelines/AGENTS.md

@@ -0,0 +1,32 @@
+# Repository Guidelines
+
+## Project Structure & Module Organization
+
+SQLite Hub is a local-first Node/Express app with a browser SPA. Backend code lives in `server/`: routes in `server/routes`, domain services in `server/services`, SQLite helpers in `server/services/sqlite`, and shared utilities in `server/utils`. Frontend code lives in `frontend/`: views in `frontend/js/views`, reusable UI in `frontend/js/components`, state/router logic in `frontend/js/store.js` and `frontend/js/router.js`, and styles in `frontend/styles`. CLI entrypoint code is in `bin/sqlite-hub.js`. Tests are in `tests/*.test.js`. Documentation is in `docs/`, with user-facing overview content in `README.md`.
+
+## Build, Test, and Development Commands
+
+- `npm run dev` starts the local server with Node watch mode on port `4180`.
+- `npm start` runs the packaged CLI entrypoint.
+- `npm test` runs all Node test files under `tests/`.
+- `npm run build` or `npm run build:css` regenerates `frontend/styles/tailwind.generated.css`.
+- `npm run screenshots` refreshes the standard screenshot set; use `npm run screenshots:backup-drawer` for the backup drawer capture.
+- `npm run audit` checks production dependencies for high-severity issues.
+
+## Coding Style & Naming Conventions
+
+Use plain JavaScript and existing local patterns. Frontend modules use ES modules; backend modules mostly use CommonJS. Prefer small, focused functions and reuse existing components before adding new UI primitives. Keep UI work aligned with `/docs/guidelines/DESIGN.md`; shared button, input, drawer, modal, and Escape-key behavior should stay consistent. Use descriptive camelCase for functions and variables, PascalCase only for classes/services, and route/view files named by feature, for example `tableAdvisor.js`.
+
+## Testing Guidelines
+
+Tests use the built-in Node test runner (`node:test`) with `node:assert/strict`. Name files `feature-name.test.js` and keep fixtures local to each test unless reuse is clearly helpful. Add focused tests for backend services, routes, state changes, and rendered view markup when behavior changes. Run the relevant focused test first, then `npm test` before handing off.
+You can use the test database id:conn_c3b310c3373fda5a
+for all tests.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short, informal messages, but contributors should keep commits clear and scoped, for example `add table advisor view` or `fix backup usage summary`. Pull requests should include a concise summary, test commands run, linked issue or context when available, and screenshots for visible UI changes. Note any generated files, especially `frontend/styles/tailwind.generated.css`, when CSS utilities change.
+
+## Security & Configuration Tips
+
+Do not commit local databases, tokens, or `.env` files. Use `.env.example` for documented configuration. Local API changes must preserve loopback-only and API-token protections in `server/middleware`.

package/docs/{DESIGN_GUIDELINES.md → guidelines/DESIGN.md}

@@ -39,6 +39,16 @@ Follow these rules exactly when creating or modifying UI controls.
 - Prefer migration over local override.
 - Prefer shared component updates over per-view fixes.
 
+## UX behavior
+
+- All drawers must close with `Escape`.
+- All modal windows must close with `Escape`.
+- Open dropdowns and menu popovers must close with `Escape`.
+- Focused text-like input elements must clear their value with `Escape` before any parent drawer, modal, dropdown, or selection state handles the key.
+- Search inputs must clear with `Escape` and dispatch the same input/update behavior as manual clearing.
+- Do not clear multiline textareas with `Escape` unless the textarea is explicitly built as a search field.
+- If an input is already empty, `Escape` may continue to the next applicable close/clear behavior.
+
 ## History elements
 
 - Query history panels, such as SQL Editor and Charts history, are always placed on the right side.

package/docs/todo.md

@@ -1,16 +1,3 @@
 # Maybe
 
-- MCP
-- query perf, history, api history
-- Data Pipeline Light/hook
-- Query Results as persistent Artifacts
-- SDK?
-- FTS5 Manager
-- Synthetic Data Generator
-- programmable triggers?
-- Query/Scheme Analyzer mit Explain Query Plan
-- MD to pdf
-- Color update / Customization
-    - hide media tagging / backups / overview
-    - change accent color
-    - toast position
+- Data Pipeline Light/hook, programmable triggers?

package/frontend/js/api.js

@@ -216,6 +216,33 @@ export function getDbStatus() {
   return request("/api/db/status");
 }
 
+export function getLogs(options = {}) {
+  const params = new URLSearchParams();
+
+  [
+    "kind",
+    "range",
+    "actor",
+    "status",
+    "queryType",
+    "destructive",
+    "from",
+    "to",
+    "search",
+    "limit",
+    "offset",
+  ].forEach((key) => {
+    const value = options[key];
+
+    if (value !== undefined && value !== null && value !== "") {
+      params.set(key, String(value));
+    }
+  });
+
+  const query = params.toString();
+  return request(`/api/logs${query ? `?${query}` : ""}`);
+}
+
 export function executeSql(sql) {
   return request("/api/sql/execute", {
     method: "POST",
@@ -470,6 +497,10 @@ export function getDataTable(tableName, options = {}) {
   return request(`/api/data/${encodeURIComponent(tableName)}${query ? `?${query}` : ""}`);
 }
 
+export function analyzeTableAdvisor(tableName) {
+  return request(`/api/data/${encodeURIComponent(tableName)}/advisor`);
+}
+
 export function getDataTableRow(tableName, payload) {
   return request(`/api/data/${encodeURIComponent(tableName)}/row`, {
     method: "POST",
@@ -491,6 +522,20 @@ export function previewDataTableRowUpdate(tableName, payload) {
   });
 }
 
+export function previewSyntheticDataRows(tableName, payload) {
+  return request(`/api/data/${encodeURIComponent(tableName)}/generate/preview`, {
+    method: "POST",
+    body: payload,
+  });
+}
+
+export function insertSyntheticDataRows(tableName, payload) {
+  return request(`/api/data/${encodeURIComponent(tableName)}/generate/insert`, {
+    method: "POST",
+    body: payload,
+  });
+}
+
 export function deleteDataTableRow(tableName, payload) {
   return request(`/api/data/${encodeURIComponent(tableName)}/rows`, {
     method: "DELETE",
@@ -513,6 +558,10 @@ export function checkAppVersion() {
   return request("/api/settings/version-check");
 }
 
+export function getSettingsMcpStatus() {
+  return request("/api/settings/mcp");
+}
+
 export function createApiToken(name) {
   return request("/api/settings/api-tokens", {
     method: "POST",