sqlite-hub 1.1.2 → 1.4.0

package/docs/API.md

@@ -0,0 +1,122 @@
+# SQLite Hub API
+
+SQLite Hub exposes a versioned JSON API at `/api/v1`. The server listens on
+`127.0.0.1`. `GET /api/v1/info` is public local app metadata; every database
+request requires a token created for that exact database in **Settings > API
+Tokens**.
+
+The token is shown only once when it is created. SQLite Hub stores a SHA-256
+hash, the token prefix, its name, and timestamps. Send the token as a bearer
+token:
+
+The `DATABASE_ID` is shown prominently in **Settings > API Tokens** for the
+active database. Use the **Copy ID** button there and replace `DATABASE_ID` in
+the request URL.
+
+```bash
+curl \
+  -H "Authorization: Bearer shub_..." \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/tables
+```
+
+A missing, invalid, deleted, or database-mismatched token returns HTTP `401`
+with a structured JSON error.
+
+## Endpoints
+
+All path values must be URL encoded.
+
+```text
+GET  /api/v1/info
+POST /api/v1/query
+
+GET  /api/v1/databases/:databaseId
+GET  /api/v1/databases/:databaseId/tables
+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/queries
+GET  /api/v1/databases/:databaseId/queries/:queryName
+GET  /api/v1/databases/:databaseId/queries/:queryName/notes
+GET  /api/v1/databases/:databaseId/queries/:queryName/export?format=csv|tsv|md|json
+POST /api/v1/databases/:databaseId/queries/:queryName/execute
+
+GET  /api/v1/databases/:databaseId/documents
+GET  /api/v1/databases/:databaseId/documents/:documentName
+GET  /api/v1/databases/:databaseId/documents/:documentName/export
+```
+
+`GET /api/v1/info` returns the same app/version status shown by
+`sqlite-hub --info`, including the installed SQLite Hub version, SQLite runtime
+version, local URL, and npm update status.
+
+`POST /api/v1/query` executes raw SQL through the same SQL Editor execution path
+used by the app and records it in Query History. Send the database token as a
+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.
+
+```bash
+curl \
+  -H "Authorization: Bearer shub_..." \
+  -H "Content-Type: application/json" \
+  -d '{"databaseId":"DATABASE_ID","sql":"SELECT * FROM companies LIMIT 10","name":"Company Sample"}' \
+  http://127.0.0.1:4173/api/v1/query
+```
+
+Row lookup accepts a scalar key or a composite primary-key object:
+
+```json
+{ "key": 42 }
+```
+
+```json
+{ "key": { "id": 42, "locale": "en" } }
+```
+
+`POST /api/v1/databases/:databaseId/tables/:tableName/types` generates
+application types from the declared SQLite schema. It is read-only, uses the
+same generation service as the Structure Inspector and CLI, and returns code as
+JSON without writing server-side files.
+
+```bash
+curl \
+  -X POST \
+  -H "Authorization: Bearer shub_..." \
+  -H "Content-Type: application/json" \
+  -d '{
+    "target": "typescript",
+    "options": {
+      "propertyNaming": "camel",
+      "nullableMode": "native",
+      "includeComments": true
+    }
+  }' \
+  http://127.0.0.1:4173/api/v1/databases/DATABASE_ID/tables/users/types
+```
+
+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.
+
+Successful responses use this envelope:
+
+```json
+{
+    "success": true,
+    "message": "",
+    "data": {},
+    "metadata": {},
+    "warnings": []
+}
+```
+
+Errors use the same envelope with `success: false` and a structured `error`
+object containing `code`, `message`, `details`, and `sqliteCode`.
+
+## Example
+
+See [`examples/api/list-tables.js`](../examples/api/list-tables.js) for a small
+Node.js example using a token from the `SQLITE_HUB_API_TOKEN` environment
+variable.

package/docs/CLI.md

@@ -0,0 +1,227 @@
+# SQLite Hub CLI
+
+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.
+
+## Start The App
+
+```bash
+sqlite-hub                  # start on default port 4173
+sqlite-hub --port:4174      # start on a custom port
+sqlite-hub --open           # open SQLite Hub in the browser
+sqlite-hub --info           # show port, URL, versions, and update status
+sqlite-hub --help           # show help text
+sqlite-hub --version        # show version number
+```
+
+`--config` is still accepted as a legacy alias for `--info`.
+
+## Databases
+
+List all imported databases:
+
+```bash
+sqlite-hub --database
+sqlite-hub -d
+```
+
+The database list shows the name, file path, file size, last opened timestamp,
+and read-only status for databases that have been opened in SQLite Hub.
+
+Query details for one database by name or id:
+
+```bash
+sqlite-hub --database:Billly --path        # get the file path
+sqlite-hub --database:Billly --size        # get the file size
+sqlite-hub --database:Billly --lastopened  # get last opened timestamp
+```
+
+List all tables in a database:
+
+```bash
+sqlite-hub --database:Billly --tables
+```
+
+Inspect one table:
+
+```bash
+sqlite-hub --database:Billly --table:companies
+```
+
+Table inspection prints metadata such as columns, primary keys, foreign keys,
+indexes, row count, and row identity strategy.
+
+Generate application types from a table schema:
+
+```bash
+sqlite-hub --database:Unit-00 --table:users --types:typescript
+sqlite-hub --database:Unit-00 --table:users --types:rust
+sqlite-hub --database:Unit-00 --table:users --types:typescript --json
+sqlite-hub --database:Unit-00 --table:users --types:typescript --output:User.ts
+```
+
+Aliases are available for common targets: `ts`, `rs`, and `kt`. Without
+`--output` or `--json`, the CLI writes only generated code to stdout so shell
+redirection works cleanly. Warnings are written to stderr. Use `--force` to
+overwrite an existing output file.
+
+## SQL Editor
+
+Execute raw SQL through the same SQL Editor execution path used by the app:
+
+```bash
+sqlite-hub --database:Unit-00 --query:"SELECT * FROM companies LIMIT 10"
+sqlite-hub --database:Unit-00 --query:"SELECT * FROM companies LIMIT 10" --store:"Company Sample"
+```
+
+Raw CLI queries are recorded in Query History. Add `--store:"name"` to title the
+history item and mark it as saved. Raw SQL execution is rejected when the target
+database is marked read-only.
+
+List all saved queries for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --queries
+```
+
+Execute a specific saved query by name:
+
+```bash
+sqlite-hub --database:Unit-00 --execute:"15min Posting Buckets without id 96"
+```
+
+This searches the query history for the selected database, finds the matching
+saved query by title, executes it, and returns results with metadata such as row
+count, columns, timing, and data.
+
+Show the saved query SQL without executing it:
+
+```bash
+sqlite-hub --database:Unit-00 --saved-query:"Stock Winners"
+```
+
+Show the saved notes for a query:
+
+```bash
+sqlite-hub --database:Unit-00 --notes:"TOP25 Loser and Winner EOD, T1, T3, T5"
+```
+
+Export a saved query using the same CSV, TSV, Markdown, and JSON export logic as
+the SQL Editor:
+
+```bash
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:csv
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:tsv
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:md
+sqlite-hub --database:Unit-00 --export:"Stock Winners" --format:json
+```
+
+The export is written to the current working directory using the generated query
+export filename.
+
+## Documents
+
+List all Markdown documents stored for a database:
+
+```bash
+sqlite-hub --database:Unit-00 --documents
+```
+
+Print one document's Markdown content:
+
+```bash
+sqlite-hub --database:Unit-00 --documents:"Research Notes"
+```
+
+Export one document as a `.md` file into the current working directory:
+
+```bash
+sqlite-hub --database:Unit-00 --documents:"Research Notes" --export
+sqlite-hub --database:Unit-00 --documents:"Research Notes--export"
+```
+
+Documents can be matched by id, filename, title, or a partial filename/title
+match.
+
+## Row JSON Export
+
+Export a single row as JSON by primary key or rowid, using the same row-shaping
+logic as the Row Editor:
+
+```bash
+sqlite-hub --database:Unit-00 --table:companies --export:0a754aba373d34972998792a0be4333c
+```
+
+## Available Flags
+
+| Flag                                                            | Description                                     |
+| --------------------------------------------------------------- | ----------------------------------------------- |
+| `--help`, `-h`                                                  | Show help text                                  |
+| `--version`, `-v`                                               | Show version number                             |
+| `--info`                                                        | Show port, URL, versions, and update status     |
+| `--open`                                                        | Open SQLite Hub in the browser                  |
+| `--port:PORT`                                                   | Start the server on a custom port               |
+| `--database`, `-d`                                              | List all imported databases                     |
+| `--database:name`                                               | Select a database by name or id                 |
+| `--database:name --path`                                        | Get the file path of a database                 |
+| `--database:name --size`                                        | Get the size of a database                      |
+| `--database:name --lastopened`                                  | Get the last opened timestamp                   |
+| `--database:name --tables`                                      | Get all table names from a database             |
+| `--database:name --queries`                                     | List saved queries for a database               |
+| `--database:name --query:"sql"`                                 | Execute raw SQL and record it in Query History  |
+| `--database:name --query:"sql" --store:"name"`                  | Save a raw query in Query History with a name   |
+| `--database:name --execute:"query"`                             | Execute a saved query by name                   |
+| `--database:name --saved-query:"query"`                         | Print a saved query by name                     |
+| `--database:name --notes:"query"`                               | Print saved notes for a query                   |
+| `--database:name --export:"query" --format:csv\|tsv\|md\|json` | Set query export format                         |
+| `--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 --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 |
+| `--type-name:"name"`                                            | Override generated type name                    |
+| `--naming:preserve\|camel\|pascal\|snake`                       | Select property naming                          |
+| `--nullable:native\|optional`                                   | Select nullable handling                        |
+| `--comments`                                                    | Include schema comments                         |
+| `--defaults-as-comments`                                        | Include default values as comments              |
+| `--json-type:unknown\|record\|json-value`                       | Select TypeScript JSON mapping                  |
+| `--include-generated`                                           | Include generated columns                       |
+| `--include-hidden`                                              | Include hidden columns                          |
+| `--output:"file"`                                               | Write generated types to a file                 |
+| `--json`                                                        | Print generated type result as JSON             |
+| `--force`                                                       | Overwrite existing `--output` file              |
+
+Legacy aliases such as `--config`, `--database-path:name`,
+`--database-size:name`, `--database-lastopened:name`, `--database-tables:name`,
+and `--database:name --sqleditor:"query"` still work.
+
+## Example
+
+Saved queries created in the graphical SQL Editor can also be executed through
+the CLI. To execute one, run:
+
+```bash
+sqlite-hub --database:Unit-00 --execute:"Group by creation Year"
+```
+
+Example output:
+
+```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
+```

package/docs/DESIGN_GUIDELINES.md

@@ -0,0 +1,45 @@
+# 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 primary button-style classes (`standard-button`, `signature-button`, `delete-button`) 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 buttons and compact interactive controls is `32px`.
+7. The source of truth for button height is `--button-height` in `frontend/styles/tokens.css`.
+8. The source of truth for form control height is `--control-height` in `frontend/styles/tokens.css`.
+9. Controls in the same row must have the same height unless one is a text input or textarea.
+10. All regular buttons must use one of these base classes only: `standard-button`, `signature-button`, `delete-button`.
+11. Use `standard-button` for normal actions.
+12. Use `signature-button` only for the primary yellow CTA in a context.
+13. Use `delete-button` only for destructive actions.
+14. Delete buttons must show the `delete` Material Symbol before the text label.
+15. `signature-button` must keep its hover state and chamfered corner.
+16. All visible clickable buttons must have a hover state.
+17. Disabled states must come from the shared component, not from local view CSS.
+18. Dropdown toggles may combine a base button class with `dropdown-button__toggle`; that class may only control dropdown layout and open-state behavior.
+19. Visibility/toggle buttons may combine a base button class with `panel-toggle-button`; that class is the shared toggle-state modifier.
+20. All reusable checkboxes must use `standard-checkbox`.
+21. Do not build feature-specific checkbox shells or checkbox base styles.
+22. Inputs and selects must follow the shared base rules in `frontend/styles/base.css`.
+23. Ghost or transparent inputs must not use a white background, including unfocused state.
+24. 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.
+
+## History elements
+
+- Query history panels, such as SQL Editor and Charts history, are always placed on the right side.
+- Subnavigation panels, such as tables, documents, structure objects, and table-designer tables, are always placed on the left side.

package/docs/changelog.md

@@ -0,0 +1,141 @@
+# v1.4.0
+
+- Schema Diff / Database Diff
+
+# v1.3.0
+
+- remove unused css and duplicates, css code rework
+- UX Audit from @corneliakocher
+- edit name and notes for backup
+- generate types from schema to typescript, kotlin, rust, swift
+- open row editor drawer with id hash http://127.0.0.1:4180/#/data#14a06a1ffa23e08ae86becec0c5d8b38
+
+# v1.1.2
+
+- documents overhaul
+- introducing the SQLite Hub dropdown button
+- backup manager
+
+# v1.1.1
+
+- table designer overhaul
+
+# v1.1.0
+
+- making the UI more consistent
+- structure overhaul, better UI
+- chart overhaul, better UI, search, etz
+- store last position of structure
+- join preview in structure
+- export JSON for Data, SQL Editor
+- export parquet for Data, SQL Editor
+- check updates for new versions in settings
+- Global Database Search
+
+# v1.0.0
+
+- Removed external Tailwind.
+- Fixed vibe-coding issues with https://github.com/oliverjessner/ItWorksBut.
+- Persisted saved/recent chart tabs in localStorage.
+- Updated dependencies.
+- Replaced innerHTML with DOM functions.
+- Display execution time in seconds when it exceeds 10 seconds.
+- The Performance panel in the SQL Editor shows query memory size.
+- The Structure view remembers the last selected table.
+- Removed pixel shift bug in SQL Editor on the bottom cards
+- title name changing depending on the menu
+- in messages you can see your executed query
+- secure execute for destructive queries
+- 250 page size, advanced search in data
+- export TSV, CSV, markdown, duplicate as table
+- copy from and export column function, with separator and wrapper
+- quick picks for database
+- export row as json
+- row editor shows urls and opens in browser, path detection, timestamp detection
+- format button in SQLEditor
+- API
+
+# v0.9.3
+
+- Improved re-rendering.
+- Fixed the sorting bug in Charts.
+- Stored the data row size in localStorage.
+- Saved charts.
+
+# v0.9.1
+
+- Tagging queue improvements.
+- Rotate right and rotate left.
+
+# v0.9.0
+
+- Tagging view.
+- Filtered Create, Update, and Delete queries out of the chart section.
+
+# v0.8.8
+
+- Fixed the delete-query modal window.
+- CSV export filenames are based on query names.
+- Unsaved query history tab.
+
+# v0.8.7
+
+- UX fixes.
+- Fixed a lot of vibe slop.
+- Started building reusable components.
+
+# v0.8.0
+
+- DDL copy button.
+- Open in Charts button in query details.
+- Clear makes the editor active.
+- UI fixes.
+- Overview improvements.
+
+# v0.7.0
+
+- Hide Query History and Hide Editor controls.
+- Better CLI interface.
+- Plotting and graphs.
+- Removed UI inconsistencies.
+
+# v0.6.0
+
+- Table Designer: create tables in SQLite Hub.
+
+# v0.5.1
+
+- Bug fix in the SQL Editor.
+
+# v0.5.0
+
+- SQL query history.
+- Open in Finder from Overview.
+- Sort columns in Data and the SQL Editor.
+- JSON view in the row editor.
+
+# v0.4.0
+
+- Search in Data.
+- Shift + Enter.
+- Database logos.
+- Cleaned up some chaotic code.
+
+# v0.3.2
+
+- Delete rows.
+- Modal windows for rows.
+
+# v0.3.1
+
+- Visualize tables.
+- Export CSV from Data and the SQL Editor.
+- Backup mode.
+
+# v0.2.0
+
+- Database fix.
+
+# v0.1.3
+
+- Edit in the SQL Editor.

package/docs/shortkeys.md

@@ -0,0 +1,27 @@
+# Meddia Tagging
+
+## tagging queue
+
+`shift + enter` triggers tagged & next
+
+# SQL Editor
+
+`shift + enter` triggers execute
+
+## Chart Details & Query Details (drawer)
+
+`esc` closes the drawer
+
+# Misc
+
+## Modals
+
+`esc` closes the modal
+
+## Input elements
+
+`esc` clears the input
+
+## Dropdown Buttons
+
+`esc` closes the dropwdown

package/docs/todo.md

@@ -0,0 +1,16 @@
+# 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

package/examples/api/generate-types.js

@@ -0,0 +1,52 @@
+const SQLITE_HUB_URL = process.env.SQLITE_HUB_URL || 'http://127.0.0.1:4173';
+const apiToken = process.env.SQLITE_HUB_API_TOKEN;
+const databaseId = process.env.SQLITE_HUB_DATABASE_ID || process.argv[2];
+const tableName = process.env.SQLITE_HUB_TABLE || process.argv[3] || 'users';
+const target = process.env.SQLITE_HUB_TYPE_TARGET || process.argv[4] || 'typescript';
+
+if (!apiToken) {
+    throw new Error('SQLITE_HUB_API_TOKEN is required.');
+}
+
+if (!databaseId) {
+    throw new Error('Provide SQLITE_HUB_DATABASE_ID or pass the database id as the first argument.');
+}
+
+const url = [
+    SQLITE_HUB_URL.replace(/\/$/, ''),
+    'api/v1/databases',
+    encodeURIComponent(databaseId),
+    'tables',
+    encodeURIComponent(tableName),
+    'types',
+].join('/');
+
+const response = await fetch(url, {
+    method: 'POST',
+    headers: {
+        Accept: 'application/json',
+        Authorization: `Bearer ${apiToken}`,
+        'Content-Type': 'application/json',
+    },
+    body: JSON.stringify({
+        target,
+        options: {
+            propertyNaming: 'camel',
+            nullableMode: 'native',
+            includeComments: true,
+            includeDefaultsAsComments: true,
+        },
+    }),
+});
+
+const payload = await response.json();
+
+if (!response.ok || !payload.success) {
+    throw new Error(payload.error?.message || payload.message || 'Type generation failed.');
+}
+
+console.log(payload.data.code);
+
+if (payload.warnings?.length) {
+    console.error(payload.warnings.map(warning => `Warning: ${warning}`).join('\n'));
+}