admindb 1.2.1 → 2.1.0

package/dist/views/partials/sidebar.hbs

@@ -1,111 +1,125 @@
+{{!-- Partial: Left Navigation Sidebar --}}
 <aside class="flex h-full min-h-full w-72 flex-col bg-neutral text-neutral-content">
+
   <div class="flex items-center gap-2.5 px-5 pb-4 pt-5">
-    <div>
-      <div class="text-base font-bold leading-tight">AdminDB <span style="font-size: x-small">{{#if version}} v{{version}}{{/if}}</span></div>
-      <div class="text-[11px] text-neutral-content/50">{{#if databasesMode}}Database manager{{else}}Database: {{dbId}}{{/if}}</div>
+    <div class="w-full">
+      <div class="flex items-center justify-between">
+        <div class="text-base font-bold leading-tight">AdminDB <span style="font-size: x-small">{{#if version}}v{{version}}{{/if}}</span></div>
+        {{#unless databasesMode}}
+          {{#if isPostgres}}
+            <span class="rounded bg-info/20 px-1.5 py-0.5 text-[10px] font-bold text-info">PostgreSQL</span>
+          {{else}}
+            <span class="rounded bg-emerald-500/20 px-1.5 py-0.5 text-[10px] font-bold text-emerald-400">SQLite</span>
+          {{/if}}
+        {{/unless}}
+      </div>
+      <div class="mt-0.5 text-[11px] text-neutral-content/50 truncate">{{#if databasesMode}}Database manager{{else}}{{dbId}}{{/if}}</div>
     </div>
   </div>
 
   {{#if databasesMode}}
-    <nav class="flex-1 overflow-y-auto px-3 py-2">
-      <ul class="space-y-0.5">
-        <li>
-          <a href="{{basePath}}/" class="side-link active">
-            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M4 7v10c0 1.1.9 2 2 2h12a2 2 0 002-2V7M4 7c0-1.1.9-2 2-2h12a2 2 0 012 2M4 7c0 1.1.9 2 2 2h12a2 2 0 002-2" /></svg>
-            Databases
-          </a>
-        </li>
-      </ul>
-    </nav>
+  <nav class="flex-1 overflow-y-auto px-3 py-2">
+    <ul class="space-y-0.5">
+      <li>
+        <a href="{{basePath}}/" class="side-link active">
+          {{{icon "database" class="h-4 w-4"}}}
+          Databases
+        </a>
+      </li>
+    </ul>
+  </nav>
   {{else}}
-    <div class="px-4 pb-2">
-      <label class="relative block">
-        <svg xmlns="http://www.w3.org/2000/svg" class="pointer-events-none absolute left-3 top-1/2 h-4 w-4 -translate-y-1/2 text-neutral-content/40" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2">
-          <path stroke-linecap="round" stroke-linejoin="round" d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
-        </svg>
-        <input id="table-search" type="search" placeholder="Filter tables…" autocomplete="off"
-          class="w-full rounded-lg border border-white/10 bg-white/[0.06] py-2 pl-9 pr-3 text-sm text-neutral-content outline-none transition placeholder:text-neutral-content/40 focus:border-primary/70 focus:ring-4 focus:ring-primary/20" />
-      </label>
-    </div>
+  <div class="px-4 pb-2">
+    <label class="relative block">
+      <span class="pointer-events-none absolute left-3 top-1/2 -translate-y-1/2 text-neutral-content/40">
+        {{{icon "search" class="h-4 w-4"}}}
+      </span>
+      <input id="table-search" type="search" placeholder="Filter tables…" autocomplete="off"
+        class="w-full rounded-lg border border-white/10 bg-white/[0.06] py-2 pl-9 pr-3 text-sm text-neutral-content outline-none transition placeholder:text-neutral-content/40 focus:border-primary/70 focus:ring-4 focus:ring-primary/20" />
+    </label>
+  </div>
 
-    <nav class="flex-1 overflow-y-auto px-3 py-2">
-      <ul class="space-y-0.5">
-        {{#if databasesUrl}}
-          <li>
-            <a href="{{databasesUrl}}" class="side-link">
-              <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M4 7v10c0 1.1.9 2 2 2h12a2 2 0 002-2V7M4 7c0-1.1.9-2 2-2h12a2 2 0 012 2M4 7c0 1.1.9 2 2 2h12a2 2 0 002-2" /></svg>
-              Databases
-            </a>
-          </li>
-        {{/if}}
-        <li>
-          <a href="{{basePath}}/" class="side-link {{#if (eq currentPath '/')}}active{{/if}}">
-            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M3 12l2-2m0 0l7-7 7 7M5 10v10a1 1 0 001 1h3m10-11l2 2m-2-2v10a1 1 0 01-1 1h-3m-6 0a1 1 0 001-1v-4a1 1 0 011-1h2a1 1 0 011 1v4a1 1 0 001 1m-6 0h6" /></svg>
-            Home
-          </a>
-        </li>
-        <li>
-          <a href="{{basePath}}/query" class="side-link {{#if (startsWith currentPath '/query')}}active{{/if}}">
-            <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M13 10V3L4 14h7v7l9-11h-7z" /></svg>
-            Query editor
-          </a>
-        </li>
-        {{#unless readonly}}
-          <li>
-            <a href="{{basePath}}/designer" class="side-link {{#if (startsWith currentPath '/designer')}}active{{/if}}">
-              <svg xmlns="http://www.w3.org/2000/svg" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M12 4v16m8-8H4" /></svg>
-              New table
-            </a>
-          </li>
-        {{/unless}}
-      </ul>
+  <nav class="flex-1 overflow-y-auto px-3 py-2">
+    <ul class="space-y-0.5">
+      {{#if databasesUrl}}
+      <li>
+        <a href="{{databasesUrl}}" class="side-link">
+          {{{icon "database" class="h-4 w-4"}}}
+          Databases
+        </a>
+      </li>
+      {{/if}}
+      <li>
+        <a href="{{basePath}}/" class="side-link {{#if (eq currentPath '/')}}active{{/if}}">
+          {{{icon "home" class="h-4 w-4"}}}
+          Home
+        </a>
+      </li>
+      <li>
+        <a href="{{basePath}}/query" class="side-link {{#if (startsWith currentPath '/query')}}active{{/if}}">
+          {{{icon "query" class="h-4 w-4"}}}
+          Query editor
+        </a>
+      </li>
+      {{#unless readonly}}
+      <li>
+        <a href="{{basePath}}/designer" class="side-link {{#if (startsWith currentPath '/designer')}}active{{/if}}">
+          {{{icon "plus" class="h-4 w-4"}}}
+          New table
+        </a>
+      </li>
+      {{/unless}}
+    </ul>
 
-      <div class="mb-2 mt-6 flex items-center justify-between px-3">
-        <span class="text-[11px] font-semibold uppercase tracking-wider text-neutral-content/40">Tables</span>
-        <span id="table-count" class="rounded-md bg-white/[0.06] px-1.5 py-0.5 text-[10px] font-semibold text-neutral-content/50">{{tables.length}}</span>
-      </div>
+    <div class="mb-2 mt-6 flex items-center justify-between px-3">
+      <span class="text-[11px] font-semibold uppercase tracking-wider text-neutral-content/40">Tables</span>
+      <span id="table-count" class="rounded-md bg-white/[0.06] px-1.5 py-0.5 text-[10px] font-semibold text-neutral-content/50">{{tables.length}}</span>
+    </div>
 
-      <ul id="table-list" class="space-y-0.5">
-        {{#each tables}}
-          <li class="table-item" data-name="{{this}}">
-            <a href="{{../basePath}}/tables/{{this}}" class="side-link {{#if (eq ../currentTable this)}}active{{/if}}">
-              <span class="table-icon">
-                <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M3 10h18M3 14h18m-9-4v8m-7 0h14a2 2 0 002-2V8a2 2 0 00-2-2H5a2 2 0 00-2 2v8a2 2 0 002 2z" /></svg>
-              </span>
-              <span class="truncate">{{this}}</span>
-            </a>
-          </li>
-        {{else}}
-          <li class="px-3 py-2 text-xs text-neutral-content/40">No tables yet</li>
-        {{/each}}
-      </ul>
+    <ul id="table-list" class="space-y-0.5">
+      {{#each tables}}
+      <li class="table-item" data-name="{{this}}">
+        <a href="{{../basePath}}/tables/{{this}}" class="side-link {{#if (eq ../currentTable this)}}active{{/if}}">
+          <span class="table-icon">
+            {{{icon "table" class="h-4 w-4"}}}
+          </span>
+          <span class="truncate">{{this}}</span>
+        </a>
+      </li>
+      {{else}}
+      <li class="px-3 py-2 text-xs text-neutral-content/40">No tables yet</li>
+      {{/each}}
+    </ul>
 
-      {{#if internalTables.length}}
-        <div class="mb-2 mt-6 px-3 text-[11px] font-semibold uppercase tracking-wider text-neutral-content/40">Internal</div>
-        <ul class="space-y-0.5">
-          {{#each internalTables}}
-            <li>
-              <a href="{{../basePath}}/tables/{{this}}" class="side-link {{#if (eq ../currentTable this)}}active{{/if}}">
-                <span class="table-icon">
-                  <svg xmlns="http://www.w3.org/2000/svg" class="h-4 w-4" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M12 6.253v13m0-13C10.832 5.477 9.246 5 7.5 5S4.168 5.477 3 6.253v13C4.168 18.477 5.754 18 7.5 18s3.332.477 4.5 1.253m0-13C13.168 5.477 14.754 5 16.5 5c1.747 0 3.332.477 4.5 1.253v13C19.832 18.477 18.247 18 16.5 18c-1.746 0-3.332.477-4.5 1.253" /></svg>
-                </span>
-                <span class="truncate">{{this}}</span>
-              </a>
-            </li>
-          {{/each}}
-        </ul>
-      {{/if}}
-    </nav>
+    {{#if internalTables.length}}
+    <div class="mb-2 mt-6 px-3 text-[11px] font-semibold uppercase tracking-wider text-neutral-content/40">Internal</div>
+    <ul class="space-y-0.5">
+      {{#each internalTables}}
+      <li>
+        <a href="{{../basePath}}/tables/{{this}}" class="side-link {{#if (eq ../currentTable this)}}active{{/if}}">
+          <span class="table-icon">
+            {{{icon "book" class="h-4 w-4"}}}
+          </span>
+          <span class="truncate">{{this}}</span>
+        </a>
+      </li>
+      {{/each}}
+    </ul>
+    {{/if}}
+  </nav>
   {{/if}}
 
   <div class="border-t border-white/10 px-5 py-3">
-    <div class="text-[11px] font-medium uppercase tracking-wider text-neutral-content/40">{{#if databasesMode}}Directory{{else}}Database{{/if}}</div>
+    <div class="flex items-center justify-between">
+      <div class="text-[11px] font-medium uppercase tracking-wider text-neutral-content/40">{{#if databasesMode}}Directory{{else}}Engine: {{dialectName}}{{/if}}</div>
+      {{#unless databasesMode}}
+        {{#if readonly}}
+          <span class="rounded bg-warning/20 px-1.5 py-0.5 text-[9px] font-bold uppercase text-warning">Read-only</span>
+        {{else}}
+          <span class="rounded bg-success/20 px-1.5 py-0.5 text-[9px] font-bold uppercase text-success">Writable</span>
+        {{/if}}
+      {{/unless}}
+    </div>
     <div class="mt-0.5 truncate font-mono text-[11px] text-neutral-content/60" title="{{dbPath}}">{{dbPath}}</div>
-    {{#if readonly}}
-      <div class="mt-2 inline-flex items-center gap-1 rounded-md bg-warning/20 px-2 py-1 text-[10px] font-bold uppercase tracking-wider text-warning">
-        <svg xmlns="http://www.w3.org/2000/svg" class="h-3 w-3" fill="none" viewBox="0 0 24 24" stroke="currentColor" stroke-width="2"><path stroke-linecap="round" stroke-linejoin="round" d="M12 15v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" /></svg>
-        Read-only
-      </div>
-    {{/if}}
   </div>
 </aside>

package/docs/API.md

@@ -0,0 +1,144 @@
+# AdminDB REST API
+
+Every route is under `basePath` and returns the consistent shape
+`{ success, data?, error? }`. In multi-db mode, every route is scoped under the
+database identifier, e.g. `/api/app.db/tables` or `/api/prod_pg/tables`.
+
+AdminDB supports both **SQLite** and **PostgreSQL** database backends seamlessly.
+
+## Tables & rows
+
+| Method | Path                                     | Purpose                          |
+| ------ | ---------------------------------------- | -------------------------------- |
+| GET    | `/api/tables`                            | List tables                      |
+| GET    | `/api/tables/:table/info`                | Column + FK metadata, PK columns |
+| GET    | `/api/tables/:table/fk-options`          | Values for FK dropdowns          |
+| GET    | `/api/tables/:table/rows?page&limit&f`   | Paginated rows (`f` = URL-encoded JSON filters — legacy strings like `{"age":">35"}` or structured conditions like `{"balance":{"op":"gte","value":"100"}}`) |
+| GET    | `/api/tables/:table/rows/count?f=`       | Filtered row count               |
+| GET    | `/api/tables/:table/row/:id`             | Single row by (encoded) PK       |
+| GET    | `/api/tables/:table/rows/:id/references` | Rows in other tables whose foreign keys reference this row |
+| GET    | `/api/tables/:table/row/:id/blob/:column` | Stream binary BLOB / BYTEA with MIME detection (add `?download=1` to force download) |
+| GET    | `/api/tables/:table/row/:id/blob/:column/meta` | Inspect BLOB / BYTEA metadata, MIME sniffing & 3-column hex dump |
+| PUT    | `/api/tables/:table/row/:id/blob/:column` | Update binary value (`{ data: base64/hex, format?: 'base64'|'hex'|'text' }`) |
+| POST   | `/api/tables/:table/rows`                | Insert row (or batch of rows with `{ rows: [...] }`) |
+| POST   | `/api/tables/:table/rows/generate`       | Generate INSERT SQL (no execute) |
+| POST   | `/api/tables/:table/rows/import`         | Import CSV (`{ csv }`, header row must match columns) |
+| GET    | `/api/tables/:table/export?format=`      | Download all rows as `csv` or `json` |
+| PUT    | `/api/tables/:table/row/:id`             | Update row (`{ values, nulls? }` — `nulls` explicitly sets columns to NULL) |
+| PUT    | `/api/tables/:table/row/:id/generate`    | Generate UPDATE SQL (no execute) |
+| DELETE | `/api/tables/:table/row/:id`             | Delete row                       |
+| POST   | `/api/tables/:table/rows/bulk-impact`    | FK-impact preview: how many rows in other tables reference the selected rows |
+| POST   | `/api/tables/:table/rows/bulk-delete`    | Delete selected rows (`{ ids, confirmImpact }`; transactional) |
+| POST   | `/api/tables/:table/rows/bulk-export`    | Export only the selected rows as `csv`/`json` (`{ ids, format }`) |
+| POST   | `/api/tables/:table/rows/bulk-update`    | Apply staged inline edits (`{ updates: [{ id, values?, nulls? }] }`; transactional) |
+| GET    | `/api/tables/:table/seed/config`         | Per-column generator strategies + detected defaults |
+| GET    | `/api/tables/:table/seed/plan`           | Detect intelligent seed plan heuristics |
+| POST   | `/api/tables/:table/seed/preview`        | Generate preview sample rows for grid without executing |
+| POST   | `/api/tables/:table/seed/generate`       | Generate seed INSERT SQL without executing (`{ count, plan }`) |
+| POST   | `/api/tables/:table/seed`                | Generate and insert seed rows transactionally (`{ count, plan, truncate? }`) |
+
+## Schema & indexes
+
+| Method | Path                                 | Purpose                          |
+| ------ | ------------------------------------ | -------------------------------- |
+| POST   | `/api/tables`                        | Create table                     |
+| POST   | `/api/tables/generate`               | Generate CREATE SQL (no execute) |
+| GET    | `/api/tables/:table/schema`          | Full schema (constraints, indexes, FK refs) |
+| GET    | `/api/tables/:table/ddl`             | Get formatted `CREATE TABLE` and `INDEX` DDL |
+
+| POST   | `/api/tables/:table/rename`          | Rename the table                 |
+| POST   | `/api/tables/:table/columns`         | Add a column                     |
+| PUT    | `/api/tables/:table/columns/:column` | Modify/rename a column           |
+| DELETE | `/api/tables/:table/columns/:column` | Drop a column (safety-checked)   |
+| DELETE | `/api/tables/:table`                 | Drop the table (safety-checked)  |
+| POST   | `/api/tables/:table/indexes`         | Create an index (`{ name?, columns[], unique? }`) |
+| DELETE | `/api/tables/:table/indexes/:index`  | Drop an index (auto indexes refused) |
+
+## Queries
+
+| Method | Path              | Purpose                    |
+| ------ | ----------------- | -------------------------- |
+| POST   | `/api/query`      | Run arbitrary SQL          |
+| POST   | `/api/query/export` | Run a SELECT and download as `csv`/`json` |
+| GET    | `/api/queries`    | List saved queries         |
+| POST   | `/api/queries`    | Save a named query         |
+| DELETE | `/api/queries/:id`| Delete a saved query       |
+
+## Manager mode (databases landing page)
+
+These endpoints manage database files and power the filesystem browser:
+
+| Method | Path                            | Purpose                                     |
+| ------ | ------------------------------- | ------------------------------------------- |
+| GET    | `/api/databases`                | List managed databases                      |
+| POST   | `/api/databases`                | Create a new SQLite database (`{ name }`)   |
+| POST   | `/api/databases/connect-postgres` | Connect a PostgreSQL database (`{ name?, connectionString, readonly? }`) |
+| POST   | `/api/databases/:id/mode`       | Toggle/set database mode (`{ readonly: boolean }`) |
+| DELETE | `/api/databases/:id`            | Delete SQLite database file or disconnect PostgreSQL connection |
+| GET    | `/api/fs/list?path=`            | List subfolders + SQLite files under a path (sandboxed file browser) |
+| POST   | `/api/databases/open`           | Open/register an existing database file by path (`{ path, readonly? }`) |
+
+## Authentication & Sessions
+
+| Method | Path                  | Purpose                                     |
+| ------ | --------------------- | ------------------------------------------- |
+| GET    | `/login`              | Web UI login page                           |
+| POST   | `/login`              | Authenticate with `{ username, password }` and get session token |
+| POST   | `/logout`             | Terminate session and clear cookie          |
+| GET    | `/logout`             | Terminate session and redirect to `/login`  |
+
+All API endpoints accept:
+- **HTTP Basic Auth**: `Authorization: Basic <base64(username:password)>`
+- **Bearer Token**: `Authorization: Bearer <sessionToken>`
+- **Session Cookie**: `admindb_session=<sessionToken>`
+
+### Generating Password Hashes
+Generate salted `scrypt` password hashes for custom credentials:
+```bash
+npm run generatehash
+# Enter password -> outputs scrypt:<salt>:<hash>
+```
+
+Paste the generated hash into `ADMINDB_PASSWORD`, CLI `-P`, or `auth.password` option.
+
+### Disabling Native Authentication & Custom Application Auth
+Pass `auth: false`, CLI `--no-auth`, or `ADMINDB_AUTH=false` to turn off built-in authentication when integrating your own security layer.
+
+> [!WARNING]
+> **Security & Responsibility Notice**:
+> AdminDB's built-in authentication is designed for basic access control during local development. For production environments and internet-facing networks, **it is entirely the user's responsibility to protect AdminDB** by placing it behind your own application authentication (e.g. NextAuth, Passport, JWT, SSO/OAuth middleware), a VPN, an IP-allowlist reverse proxy (Nginx, Cloudflare Access), or HTTPS with rate limiting.
+
+
+## TypeScript API Types & Helpers
+
+All request and response types, data inspection helpers, and serverless handlers are exported by the package entry point:
+
+```ts
+import {
+  createRouter,
+  createServerlessHandler,
+  createLambdaHandler,
+  sniffMimeType,
+  generateHexDump,
+  analyzeBlob,
+  isJsonString,
+  formatJsonSafely,
+  type ApiResponse,
+  type GetRowsResponseData,
+  type BlobMetaResponseData,
+  type TableDdlResponseData,
+} from 'admindb';
+
+// 1. Sniff MIME type from binary magic bytes
+const analysis = sniffMimeType(imageBuffer);
+console.log(analysis.mime, analysis.ext, analysis.isImage);
+
+// 2. Generate a 3-column hex dump
+const dump = generateHexDump(binaryBuffer, 1024);
+dump.lines.forEach((l) => console.log(`${l.offset}  ${l.hex}  |${l.ascii}|`));
+
+// 3. Serverless request handler (Vercel, AWS Lambda, Cloudflare, etc.)
+export default createServerlessHandler({ dbPath: './app.db' });
+```
+
+