dbn-cli 0.2.0

package/README.md

@@ -0,0 +1,41 @@
+# dbn
+
+A lightweight terminal SQLite browser with an ncdu-style interface.
+
+## Features
+
+- **Minimal dependencies** - Uses Node.js 24+ built-in `node:sqlite` module
+- **Full-screen TUI** - ncdu-inspired keyboard navigation
+
+## Installation
+
+```bash
+npm install -g dbn-cli
+```
+
+## Usage
+
+```bash
+dbn <path-to-sqlite-db-file>
+```
+
+## Keyboard Shortcuts
+
+- `j/k` or `↓/↑` - Navigate
+- `Enter` or `l` - Open/view details
+- `h` or `Esc` - Go back
+- `s` - Toggle schema view
+- `r` - Reload data
+- `g/G` - Jump to top/bottom
+- `q` - Quit
+
+## Development
+
+```bash
+npm run dev path/to/database.db   # Run in dev mode
+npm test                          # Run tests
+```
+
+## License
+
+MIT

package/bin/dbn.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env -S node --experimental-strip-types --disable-warning=ExperimentalWarning
+
+import { main } from '../src/index.ts';
+
+// Get command line arguments (skip node and script path)
+const args = process.argv.slice(2);
+
+// Run the application
+main(args);

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "dbn-cli",
+  "version": "0.2.0",
+  "description": "A lightweight terminal-based database browser",
+  "type": "module",
+  "main": "src/index.ts",
+  "bin": {
+    "dbn": "./bin/dbn.ts"
+  },
+  "scripts": {
+    "test": "node --test --experimental-strip-types test/*.test.ts",
+    "test:watch": "node --test --watch --experimental-strip-types test/*.test.ts",
+    "test:coverage": "node --test --experimental-test-coverage --experimental-strip-types test/*.test.ts",
+    "dev": "node bin/dbp.ts"
+  },
+  "keywords": [
+    "database",
+    "sqlite",
+    "cli",
+    "terminal",
+    "browser",
+    "tui"
+  ],
+  "author": "Amio <amio.cn@gmail.com>",
+  "license": "MIT",
+  "engines": {
+    "node": ">=24"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "devDependencies": {
+    "@types/node": "^24.10.9"
+  }
+  ,
+  "dependencies": {
+    "string-width": "^5.0.1"
+  }
+}

package/src/adapter/base.ts

@@ -0,0 +1,46 @@
+import type { TableInfo, ColumnSchema, QueryOptions } from '../types.ts';
+
+/**
+ * Base class for database adapters
+ * Defines the interface that all database adapters must implement
+ */
+export abstract class DatabaseAdapter {
+  /**
+   * Connect to the database
+   * @param path - Path to the database file or connection string
+   */
+  abstract connect(path: string): void;
+
+  /**
+   * Get all tables in the database
+   * @returns Array of table information
+   */
+  abstract getTables(): TableInfo[];
+
+  /**
+   * Get schema information for a specific table
+   * @param tableName - Name of the table
+   * @returns Array of column schema information
+   */
+  abstract getTableSchema(tableName: string): ColumnSchema[];
+
+  /**
+   * Get data from a specific table with pagination
+   * @param tableName - Name of the table
+   * @param options - Query options
+   * @returns Array of row objects
+   */
+  abstract getTableData(tableName: string, options?: QueryOptions): Record<string, any>[];
+
+  /**
+   * Get the total row count for a specific table
+   * @param tableName - Name of the table
+   * @returns Total number of rows
+   */
+  abstract getRowCount(tableName: string): number;
+
+  /**
+   * Close the database connection
+   */
+  abstract close(): void;
+}

package/src/adapter/sqlite.ts

@@ -0,0 +1,110 @@
+import { DatabaseSync } from 'node:sqlite';
+import { DatabaseAdapter } from './base.ts';
+import type { TableInfo, ColumnSchema, QueryOptions } from '../types.ts';
+
+/**
+ * SQLite adapter using Node.js 22+ built-in node:sqlite
+ */
+export class SQLiteAdapter extends DatabaseAdapter {
+  private db: DatabaseSync | null = null;
+  private path: string | null = null;
+
+  /**
+   * Connect to SQLite database file
+   * @param path - Path to the .db or .sqlite file
+   */
+  connect(path: string): void {
+    try {
+      this.db = new DatabaseSync(path);
+      this.path = path;
+      // Enable WAL mode for better performance
+      this.db.exec('PRAGMA journal_mode = WAL');
+    } catch (error) {
+      throw new Error(`Failed to open database: ${(error as Error).message}`);
+    }
+  }
+
+  /**
+   * Get all tables in the database
+   * @returns Array of table information
+   */
+  getTables(): TableInfo[] {
+    if (!this.db) {
+      throw new Error('Database not connected');
+    }
+
+    const query = `
+      SELECT name
+      FROM sqlite_master
+      WHERE type='table' AND name NOT LIKE 'sqlite_%'
+      ORDER BY name
+    `;
+    
+    const stmt = this.db.prepare(query);
+    const tables = stmt.all() as { name: string }[];
+    
+    // Get row count for each table
+    return tables.map(table => {
+      const countStmt = this.db!.prepare(`SELECT COUNT(*) as count FROM "${table.name}"`);
+      const result = countStmt.get() as { count: number };
+      return {
+        name: table.name,
+        row_count: result.count
+      };
+    });
+  }
+
+  /**
+   * Get schema information for a specific table
+   * @param tableName - Name of the table
+   * @returns Array of column schema information
+   */
+  getTableSchema(tableName: string): ColumnSchema[] {
+    if (!this.db) {
+      throw new Error('Database not connected');
+    }
+
+    const stmt = this.db.prepare(`PRAGMA table_info("${tableName}")`);
+    return stmt.all() as unknown as ColumnSchema[];
+  }
+
+  /**
+   * Get data from a specific table with pagination
+   * @param tableName - Name of the table
+   * @param options - Query options
+   * @returns Array of row objects
+   */
+  getTableData(tableName: string, { limit = 50, offset = 0 }: QueryOptions = {}): Record<string, any>[] {
+    if (!this.db) {
+      throw new Error('Database not connected');
+    }
+
+    const stmt = this.db.prepare(`SELECT * FROM "${tableName}" LIMIT ? OFFSET ?`);
+    return stmt.all(limit, offset) as Record<string, any>[];
+  }
+
+  /**
+   * Get the total row count for a specific table
+   * @param tableName - Name of the table
+   * @returns Total number of rows
+   */
+  getRowCount(tableName: string): number {
+    if (!this.db) {
+      throw new Error('Database not connected');
+    }
+
+    const stmt = this.db.prepare(`SELECT COUNT(*) as count FROM "${tableName}"`);
+    const result = stmt.get() as { count: number };
+    return result.count;
+  }
+
+  /**
+   * Close the database connection
+   */
+  close(): void {
+    if (this.db) {
+      this.db.close();
+      this.db = null;
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,250 @@
+import { stdin, stdout, exit } from 'node:process';
+import { existsSync } from 'node:fs';
+import * as readline from 'node:readline';
+import { SQLiteAdapter } from './adapter/sqlite.ts';
+import { Screen } from './ui/screen.ts';
+import { Renderer } from './ui/renderer.ts';
+import { Navigator } from './ui/navigator.ts';
+import type { KeyPress } from './types.ts';
+
+/**
+ * Main application class
+ */
+export class DBPeek {
+  private dbPath: string;
+  private adapter: SQLiteAdapter | null = null;
+  private screen: Screen | null = null;
+  private renderer: Renderer | null = null;
+  private navigator: Navigator | null = null;
+  private isRunning: boolean = false;
+
+  constructor(dbPath: string) {
+    this.dbPath = dbPath;
+  }
+
+  /**
+   * Initialize the application
+   */
+  init(): void {
+    // Validate database file
+    if (!existsSync(this.dbPath)) {
+      console.error(`Error: Database file not found: ${this.dbPath}`);
+      exit(1);
+    }
+
+    // Create adapter and connect
+    try {
+      this.adapter = new SQLiteAdapter();
+      this.adapter.connect(this.dbPath);
+    } catch (error) {
+      console.error(`Error: ${(error as Error).message}`);
+      exit(1);
+    }
+
+    // Initialize UI components
+    this.screen = new Screen();
+    this.renderer = new Renderer(this.screen);
+    this.navigator = new Navigator(this.adapter);
+
+    // Initialize navigator with tables
+    try {
+      this.navigator.init();
+    } catch (error) {
+      console.error(`Error loading tables: ${(error as Error).message}`);
+      this.cleanup();
+      exit(1);
+    }
+  }
+
+  /**
+   * Start the application
+   */
+  start(): void {
+    if (!this.screen || !this.navigator) {
+      throw new Error('Application not initialized');
+    }
+
+    this.isRunning = true;
+
+    // Enter full screen mode
+    this.screen.enter();
+
+    // Set up keyboard input
+    this.setupInput();
+
+    // Handle screen resize
+    this.screen.on('resize', () => {
+      this.render();
+    });
+
+    // Initial render
+    this.render();
+  }
+
+  /**
+   * Set up keyboard input handling
+   */
+  private setupInput(): void {
+    // Enable raw mode for key-by-key input
+    stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+
+    // Enable keypress events
+    readline.emitKeypressEvents(stdin);
+
+    stdin.on('keypress', (str: string, key: KeyPress) => {
+      if (!this.isRunning) return;
+
+      this.handleKeypress(str, key);
+    });
+  }
+
+  /**
+   * Handle keypress events
+   */
+  private handleKeypress(str: string, key: KeyPress): void {
+    if (!this.navigator) return;
+
+    // Handle Ctrl+C
+    if (key.ctrl && key.name === 'c') {
+      this.quit();
+      return;
+    }
+
+    // Handle different keys
+    switch (key.name) {
+      case 'q':
+        this.quit();
+        break;
+
+      case 'j':
+      case 'down':
+        this.navigator.moveDown();
+        this.render();
+        break;
+
+      case 'k':
+      case 'up':
+        this.navigator.moveUp();
+        this.render();
+        break;
+
+      case 'return':
+      case 'l':
+      case 'right':
+        this.navigator.enter();
+        this.render();
+        break;
+
+      case 'h':
+      case 'left':
+      case 'escape':
+        this.navigator.back();
+        this.render();
+        break;
+
+      case 'g':
+        if (key.shift) {
+          // G - jump to bottom
+          this.navigator.jumpToBottom();
+        } else {
+          // g - jump to top
+          this.navigator.jumpToTop();
+        }
+        this.render();
+        break;
+
+      case 'r':
+        // Reload current view
+        this.navigator.reload();
+        this.render();
+        break;
+
+      case 's':
+        // Toggle schema view in full screen mode
+        const currentState = this.navigator.getState();
+        if (currentState.type === 'table-detail') {
+          this.navigator.viewSchema();
+          this.render();
+        } else if (currentState.type === 'schema-view') {
+          this.navigator.back();
+          this.render();
+        }
+        break;
+    }
+  }
+
+  /**
+   * Render the current state
+   */
+  private render(): void {
+    if (!this.renderer || !this.navigator) return;
+
+    try {
+      const state = this.navigator.getState();
+      this.renderer.render(state, this.dbPath);
+    } catch (error) {
+      // If rendering fails, try to show error and quit gracefully
+      this.cleanup();
+      console.error(`Render error: ${(error as Error).message}`);
+      exit(1);
+    }
+  }
+
+  /**
+   * Quit the application
+   */
+  quit(): void {
+    this.isRunning = false;
+    this.cleanup();
+    exit(0);
+  }
+
+  /**
+   * Clean up resources
+   */
+  cleanup(): void {
+    // Exit full screen mode
+    if (this.screen) {
+      this.screen.exit();
+    }
+
+    // Close database connection
+    if (this.adapter) {
+      this.adapter.close();
+    }
+
+    // Restore terminal
+    if (stdin.isTTY) {
+      stdin.setRawMode(false);
+      stdin.pause();
+    }
+  }
+}
+
+/**
+ * Main entry point
+ */
+export function main(args: string[]): void {
+  const dbPath = args[0];
+
+  if (!dbPath) {
+    console.error('Usage: dbn <path-to-sqlite-db-file>');
+    console.error('');
+    console.error('Example:');
+    console.error('  dbn ./mydatabase.db');
+    exit(1);
+  }
+
+  const app = new DBPeek(dbPath);
+
+  // Handle process termination
+  process.on('SIGINT', () => app.quit());
+  process.on('SIGTERM', () => app.quit());
+  process.on('exit', () => app.cleanup());
+
+  // Initialize and start
+  app.init();
+  app.start();
+}

package/src/types.ts

@@ -0,0 +1,109 @@
+/**
+ * Type definitions for DBPeek
+ */
+
+/**
+ * Table metadata
+ */
+export interface TableInfo {
+  name: string;
+  row_count: number;
+}
+
+/**
+ * Column schema information
+ */
+export interface ColumnSchema {
+  cid: number;
+  name: string;
+  type: string;
+  notnull: number;
+  dflt_value: any;
+  pk: number;
+}
+
+/**
+ * Query options for fetching table data
+ */
+export interface QueryOptions {
+  limit?: number;
+  offset?: number;
+}
+
+/**
+ * Base view state properties
+ */
+interface BaseViewState {
+  type: string;
+}
+
+/**
+ * Tables list view state
+ */
+export interface TablesViewState extends BaseViewState {
+  type: 'tables';
+  tables: TableInfo[];
+  cursor: number;
+  scrollOffset: number;
+}
+
+/**
+ * Table detail view state
+ */
+export interface TableDetailViewState extends BaseViewState {
+  type: 'table-detail';
+  tableName: string;
+  schema: ColumnSchema[];
+  data: Record<string, any>[];
+  totalRows: number;
+  dataOffset: number;
+  dataCursor: number;
+  visibleRows: number;
+  showSchema?: boolean;
+}
+
+/**
+ * Schema view state (full screen schema display)
+ */
+export interface SchemaViewState extends BaseViewState {
+  type: 'schema-view';
+  tableName: string;
+  schema: ColumnSchema[];
+  cursor: number;
+  scrollOffset: number;
+}
+
+/**
+ * Row detail view state
+ */
+export interface RowDetailViewState extends BaseViewState {
+  type: 'row-detail';
+  tableName: string;
+  row: Record<string, any>;
+  rowIndex: number;
+  schema: ColumnSchema[];
+}
+
+/**
+ * Union type for all possible view states
+ */
+export type ViewState = TablesViewState | TableDetailViewState | SchemaViewState | RowDetailViewState;
+
+/**
+ * Screen dimensions
+ */
+export interface ScreenDimensions {
+  width: number;
+  height: number;
+}
+
+/**
+ * Keypress event from readline
+ */
+export interface KeyPress {
+  name: string;
+  ctrl: boolean;
+  shift: boolean;
+  meta: boolean;
+  sequence: string;
+}