sql-kite 1.0.0

package/src/commands/new.js

@@ -0,0 +1,69 @@
+import { mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import { 
+  ensureSqlKiteDirs, 
+  getProjectPath, 
+  getProjectDbPath, 
+  getProjectMetaPath,
+  projectExists,
+  validateProjectName 
+} from '../utils/paths.js';
+import { initUserDb, initMetaDb } from '../utils/db-init.js';
+
+export async function newCommand(name) {
+  ensureSqlKiteDirs();
+  
+  // Validate project name to prevent path traversal
+  const validation = validateProjectName(name);
+  if (!validation.valid) {
+    console.log(chalk.red(`✗ ${validation.error}`));
+    process.exit(1);
+  }
+  
+  if (projectExists(validation.sanitized)) {
+    console.log(chalk.red(`✗ Project "${validation.sanitized}" already exists`));
+    process.exit(1);
+  }
+  
+  const spinner = ora(`Creating project "${validation.sanitized}"...`).start();
+  
+  try {
+    const projectPath = getProjectPath(validation.sanitized);
+    const studioPath = join(projectPath, '.studio');
+    const migrationsPath = join(projectPath, 'migrations');
+    const snapshotsPath = join(projectPath, 'snapshots');
+    const studioSnapshotsPath = join(studioPath, 'snapshots');
+    
+    // Create directories
+    mkdirSync(projectPath, { recursive: true });
+    mkdirSync(studioPath, { recursive: true });
+    mkdirSync(migrationsPath, { recursive: true });
+    mkdirSync(snapshotsPath, { recursive: true });
+    mkdirSync(studioSnapshotsPath, { recursive: true }); // For automatic branch snapshots
+    
+    // Initialize databases
+    initUserDb(getProjectDbPath(validation.sanitized));
+    initMetaDb(getProjectMetaPath(validation.sanitized));
+    
+    // Create config
+    const config = {
+      name: validation.sanitized,
+      created_at: new Date().toISOString(),
+      version: '1.0.0'
+    };
+    writeFileSync(
+      join(projectPath, 'config.json'),
+      JSON.stringify(config, null, 2)
+    );
+    
+    spinner.succeed(chalk.green(`✓ Project "${validation.sanitized}" created successfully`));
+    console.log(chalk.dim(`   Location: ${projectPath}`));
+    console.log(chalk.dim(`\n   Run: ${chalk.cyan(`npm run sql-kite start ${validation.sanitized}`)}`));
+  } catch (error) {
+    spinner.fail(chalk.red('✗ Failed to create project'));
+    console.error(error);
+    process.exit(1);
+  }
+}

package/src/commands/open.js

@@ -0,0 +1,23 @@
+import { existsSync, readFileSync } from 'fs';
+import chalk from 'chalk';
+import open from 'open';
+import { getProjectServerInfoPath, projectExists } from '../utils/paths.js';
+
+export async function openCommand(name) {
+  if (!projectExists(name)) {
+    console.log(chalk.red(`✗ Project "${name}" does not exist`));
+    process.exit(1);
+  }
+  
+  const serverInfoPath = getProjectServerInfoPath(name);
+  
+  if (!existsSync(serverInfoPath)) {
+    console.log(chalk.yellow(`⚠ Project "${name}" is not running`));
+    console.log(chalk.dim(`   Run: ${chalk.cyan(`npm run sql-kite start ${name}`)}`));
+    return;
+  }
+  
+  const serverInfo = JSON.parse(readFileSync(serverInfoPath, 'utf-8'));
+  console.log(chalk.cyan(`Opening http://localhost:${serverInfo.port}...`));
+  await open(`http://localhost:${serverInfo.port}`);
+}

package/src/commands/ports.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import { getPortStatus, cleanupStalePorts } from '../utils/port-finder.js';
+
+export async function portsCommand(options = {}) {
+  if (options.cleanup) {
+    console.log(chalk.cyan('Cleaning up stale port allocations...'));
+    const cleaned = cleanupStalePorts();
+    console.log(chalk.green(`✓ Cleaned ${cleaned} stale allocation(s)`));
+    return;
+  }
+
+  const status = getPortStatus();
+
+  console.log(chalk.bold('\n📊 SQL Kite Port Registry Status\n'));
+
+  if (status.total_allocations === 0) {
+    console.log(chalk.dim('  No ports currently allocated'));
+    console.log(chalk.dim('  All projects are stopped\n'));
+    return;
+  }
+  //hi
+
+  console.log(chalk.cyan(`  Total allocations: ${status.total_allocations}\n`));
+
+  // Sort by port number
+  const allocations = Object.entries(status.allocations).sort(
+    (a, b) => a[1].port - b[1].port
+  );
+
+  console.log(chalk.bold('  Project              Port    Allocated At              PID'));
+  console.log(chalk.dim('  ─────────────────────────────────────────────────────────────'));
+
+  for (const [projectName, info] of allocations) {
+    const allocatedTime = new Date(info.allocated_at).toLocaleString();
+    const projectDisplay = projectName.padEnd(20);
+    const portDisplay = info.port.toString().padEnd(7);
+    const pidDisplay = info.pid.toString().padEnd(7);
+
+    console.log(`  ${chalk.green(projectDisplay)} ${chalk.cyan(portDisplay)} ${allocatedTime}  ${pidDisplay}`);
+  }
+
+  console.log('');
+
+  if (status.last_cleanup) {
+    const lastCleanup = new Date(status.last_cleanup).toLocaleString();
+    console.log(chalk.dim(`  Last cleanup: ${lastCleanup}`));
+  }
+
+  console.log(chalk.dim('\n  Run with --cleanup to remove stale allocations\n'));
+}

package/src/commands/start.js

@@ -0,0 +1,128 @@
+import { spawn } from 'child_process';
+import { existsSync, readFileSync, writeFileSync } from 'fs';
+import { join, dirname } from 'path';
+import { fileURLToPath } from 'url';
+import http from 'http';
+import chalk from 'chalk';
+import ora from 'ora';
+import open from 'open';
+import {
+  getProjectPath,
+  getProjectServerInfoPath,
+  projectExists
+} from '../utils/paths.js';
+import { findFreePort } from '../utils/port-finder.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Helper function to check if server is ready
+async function waitForServer(port, maxAttempts = 30) {
+  for (let i = 0; i < maxAttempts; i++) {
+    try {
+      await new Promise((resolve, reject) => {
+        const req = http.get(`http://localhost:${port}/api/project`, (res) => {
+          if (res.statusCode === 200) {
+            resolve();
+          } else {
+            reject(new Error(`Server returned ${res.statusCode}`));
+          }
+        });
+        req.on('error', reject);
+        req.setTimeout(1000, () => {
+          req.destroy();
+          reject(new Error('Timeout'));
+        });
+      });
+      return true;
+    } catch (e) {
+      // Server not ready yet, wait and retry
+      await new Promise(resolve => setTimeout(resolve, 500));
+    }
+  }
+  return false;
+}
+
+export async function startCommand(name) {
+  if (!projectExists(name)) {
+    console.log(chalk.red(`✗ Project "${name}" does not exist`));
+    console.log(chalk.dim(`   Run: ${chalk.cyan(`npm run sql-kite new ${name}`)}`));
+    process.exit(1);
+  }
+  
+  // Check if studio is built
+  const studioPath = join(__dirname, '../../../studio/out');
+  if (!existsSync(studioPath)) {
+    console.log(chalk.red(`✗ Studio UI not built yet`));
+    console.log(chalk.dim(`   Run: ${chalk.cyan(`cd packages/studio && npm run build`)}`));
+    process.exit(1);
+  }
+  
+  const serverInfoPath = getProjectServerInfoPath(name);
+  
+  // Check if already running
+  if (existsSync(serverInfoPath)) {
+    try {
+      const serverInfo = JSON.parse(readFileSync(serverInfoPath, 'utf-8'));
+      console.log(chalk.yellow(`⚠ Project "${name}" is already running`));
+      console.log(chalk.dim(`   URL: ${chalk.cyan(`http://localhost:${serverInfo.port}`)}`));
+      await open(`http://localhost:${serverInfo.port}`);
+      return;
+    } catch (e) {
+      // Server info corrupted, continue with start
+    }
+  }
+  
+  const spinner = ora(`Starting project "${name}"...`).start();
+
+  try {
+    // Find and reserve a port for this project
+    const port = await findFreePort(3000, name);
+    const projectPath = getProjectPath(name);
+    
+    // Path to server package
+    const serverPath = join(__dirname, '../../../server/src/index.js');
+    
+    // Spawn server process
+    const serverProcess = spawn('node', [serverPath], {
+      detached: true,
+      stdio: 'ignore',
+      env: {
+        ...process.env,
+        PROJECT_NAME: name,
+        PROJECT_PATH: projectPath,
+        PORT: port.toString()
+      }
+    });
+    
+    serverProcess.unref();
+    
+    // Write server info
+    const serverInfo = {
+      pid: serverProcess.pid,
+      port,
+      started_at: new Date().toISOString()
+    };
+    writeFileSync(serverInfoPath, JSON.stringify(serverInfo, null, 2));
+
+    // Wait for server to be ready
+    spinner.text = `Waiting for server to start...`;
+    const serverReady = await waitForServer(port);
+
+    if (!serverReady) {
+      spinner.fail(chalk.red('✗ Server failed to start in time'));
+      console.log(chalk.yellow('⚠ Server might still be starting. Check logs for errors.'));
+      process.exit(1);
+    }
+
+    spinner.succeed(chalk.green(`✓ Project "${name}" started`));
+    console.log(chalk.dim(`   URL: ${chalk.cyan(`http://localhost:${port}`)}`));
+    console.log(chalk.dim(`   PID: ${serverProcess.pid}`));
+
+    // Open browser
+    await open(`http://localhost:${port}`);
+  } catch (error) {
+    spinner.fail(chalk.red('✗ Failed to start project'));
+    console.error(error);
+    process.exit(1);
+  }
+}

package/src/commands/stop.js

@@ -0,0 +1,71 @@
+import { existsSync, readFileSync, unlinkSync } from 'fs';
+import chalk from 'chalk';
+import ora from 'ora';
+import { getProjectServerInfoPath, projectExists } from '../utils/paths.js';
+import { releasePort } from '../utils/port-finder.js';
+
+export async function stopCommand(name) {
+  if (!projectExists(name)) {
+    console.log(chalk.red(`✗ Project "${name}" does not exist`));
+    process.exit(1);
+  }
+  
+  const serverInfoPath = getProjectServerInfoPath(name);
+  
+  if (!existsSync(serverInfoPath)) {
+    console.log(chalk.yellow(`⚠ Project "${name}" is not running`));
+    return;
+  }
+  
+  const spinner = ora(`Stopping project "${name}"...`).start();
+
+  try {
+    const serverInfo = JSON.parse(readFileSync(serverInfoPath, 'utf-8'));
+
+    // Send SIGTERM signal
+    try {
+      process.kill(serverInfo.pid, 'SIGTERM');
+    } catch (killError) {
+      // Process might already be dead, that's okay
+      if (killError.code !== 'ESRCH') {
+        throw killError;
+      }
+    }
+
+    // Wait for process to terminate (up to 5 seconds)
+    let processTerminated = false;
+    for (let i = 0; i < 50; i++) {
+      await new Promise(resolve => setTimeout(resolve, 100));
+      try {
+        // process.kill with signal 0 checks if process exists without killing it
+        process.kill(serverInfo.pid, 0);
+      } catch (e) {
+        // Process no longer exists
+        processTerminated = true;
+        break;
+      }
+    }
+
+    if (!processTerminated) {
+      // Force kill if graceful shutdown timed out
+      try {
+        process.kill(serverInfo.pid, 'SIGKILL');
+        await new Promise(resolve => setTimeout(resolve, 500));
+      } catch (e) {
+        // Process might already be gone
+      }
+    }
+
+    // Remove server info file
+    unlinkSync(serverInfoPath);
+
+    // Release port from registry
+    releasePort(name);
+
+    spinner.succeed(chalk.green(`✓ Project "${name}" stopped`));
+  } catch (error) {
+    spinner.fail(chalk.red('✗ Failed to stop project'));
+    console.error(error);
+    process.exit(1);
+  }
+}

package/src/index.js

@@ -0,0 +1,73 @@
+import { Command } from 'commander';
+import chalk from 'chalk';
+import { newCommand } from './commands/new.js';
+import { startCommand } from './commands/start.js';
+import { stopCommand } from './commands/stop.js';
+import { listCommand } from './commands/list.js';
+import { deleteCommand } from './commands/delete.js';
+import { openCommand } from './commands/open.js';
+import { portsCommand } from './commands/ports.js';
+import importCommand from './commands/import.js';
+import importServerCommand from './commands/import-server.js';
+import { initCommand } from './commands/init.js';
+
+const program = new Command();
+
+program
+  .name('sql-kite')
+  .description('SQL Kite - Local SQLite database platform with Studio UI')
+  .version('1.0.0');
+
+program
+  .command('new <name>')
+  .description('Create a new database project')
+  .action(newCommand);
+
+program
+  .command('init')
+  .description('Scaffold database integration layer in app project')
+  .action(initCommand);
+
+program
+  .command('start <name>')
+  .description('Start the database server and open Studio')
+  .action(startCommand);
+
+program
+  .command('stop <name>')
+  .description('Stop the database server')
+  .action(stopCommand);
+
+program
+  .command('open <name>')
+  .description('Open Studio in browser (if server is running)')
+  .action(openCommand);
+
+program
+  .command('import <database-path>')
+  .description('Import an existing SQLite database into a managed project')
+  .action(importCommand);
+
+program
+  .command('import-server')
+  .description('Start import server (for completing pending imports)')
+  .option('-p, --port <port>', 'Port to run server on', '3000')
+  .action((options) => importServerCommand(parseInt(options.port)));
+
+program
+  .command('list')
+  .description('List all database projects')
+  .action(listCommand);
+
+program
+  .command('delete <name>')
+  .description('Delete a database project')
+  .action(deleteCommand);
+
+program
+  .command('ports')
+  .description('View and manage port allocations')
+  .option('--cleanup', 'Clean up stale port allocations')
+  .action(portsCommand);
+
+program.parse();

package/src/utils/db-init.js

@@ -0,0 +1,20 @@
+import Database from 'better-sqlite3';
+import { migrateMetaDb } from './meta-migration.js';
+
+export function initUserDb(dbPath) {
+  const db = new Database(dbPath);
+
+  // User's database starts empty
+  // They create tables via Studio
+
+  db.close();
+}
+
+export function initMetaDb(metaPath) {
+  // Just ensure the file exists, then run migration
+  const db = new Database(metaPath);
+  db.close();
+
+  // Run migration to latest schema
+  migrateMetaDb(metaPath);
+}

package/src/utils/meta-migration.js

@@ -0,0 +1,259 @@
+import Database from 'better-sqlite3';
+
+/**
+ * Migrate meta database to latest schema
+ * Handles upgrading existing projects to support branches
+ */
+export function migrateMetaDb(metaPath) {
+  const db = new Database(metaPath);
+
+  // Create settings table first if it doesn't exist
+  db.exec(`
+    CREATE TABLE IF NOT EXISTS settings (
+      key TEXT PRIMARY KEY,
+      value TEXT NOT NULL
+    );
+  `);
+
+  // Get current schema version
+  let version = 0;
+  try {
+    const result = db.prepare(`
+      SELECT value FROM settings WHERE key = 'schema_version'
+    `).get();
+    version = result ? parseInt(result.value) : 0;
+  } catch (e) {
+    version = 0;
+  }
+
+  console.log(`Meta DB current version: ${version}`);
+
+  // Migration v0 -> v1: Add branch support
+  if (version < 1) {
+    console.log('Migrating meta DB to v1 (branch support)...');
+
+    // Create branches table
+    db.exec(`
+      CREATE TABLE IF NOT EXISTS branches (
+        id INTEGER PRIMARY KEY AUTOINCREMENT,
+        name TEXT NOT NULL UNIQUE,
+        db_file TEXT NOT NULL,
+        created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+        created_from TEXT,
+        description TEXT
+      );
+    `);
+
+    // Migrate events table
+    try {
+      const eventsInfo = db.pragma('table_info(events)');
+      if (eventsInfo.length > 0) {
+        const hasBranchColumn = eventsInfo.some(col => col.name === 'branch');
+
+        if (!hasBranchColumn) {
+          console.log('  Migrating events table...');
+          db.exec(`ALTER TABLE events RENAME TO events_old;`);
+
+          db.exec(`
+            CREATE TABLE events (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              branch TEXT NOT NULL DEFAULT 'main',
+              type TEXT NOT NULL,
+              data TEXT NOT NULL,
+              created_at TEXT DEFAULT CURRENT_TIMESTAMP
+            );
+          `);
+
+          db.exec(`
+            INSERT INTO events (id, branch, type, data, created_at)
+            SELECT id, 'main', type, data, created_at FROM events_old;
+          `);
+
+          db.exec(`DROP TABLE events_old;`);
+        }
+      } else {
+        // No events table yet, create it
+        db.exec(`
+          CREATE TABLE events (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            branch TEXT NOT NULL DEFAULT 'main',
+            type TEXT NOT NULL,
+            data TEXT NOT NULL,
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP
+          );
+        `);
+      }
+    } catch (e) {
+      // Events table doesn't exist, create it
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS events (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          branch TEXT NOT NULL DEFAULT 'main',
+          type TEXT NOT NULL,
+          data TEXT NOT NULL,
+          created_at TEXT DEFAULT CURRENT_TIMESTAMP
+        );
+      `);
+    }
+
+    // Migrate migrations table
+    try {
+      const migrationsInfo = db.pragma('table_info(migrations)');
+      if (migrationsInfo.length > 0) {
+        const hasBranchColumn = migrationsInfo.some(col => col.name === 'branch');
+
+        if (!hasBranchColumn) {
+          console.log('  Migrating migrations table...');
+          db.exec(`ALTER TABLE migrations RENAME TO migrations_old;`);
+
+          db.exec(`
+            CREATE TABLE migrations (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              branch TEXT NOT NULL DEFAULT 'main',
+              filename TEXT NOT NULL,
+              applied_at TEXT DEFAULT CURRENT_TIMESTAMP,
+              UNIQUE(branch, filename)
+            );
+          `);
+
+          db.exec(`
+            INSERT INTO migrations (id, branch, filename, applied_at)
+            SELECT id, 'main', filename, applied_at FROM migrations_old;
+          `);
+
+          db.exec(`DROP TABLE migrations_old;`);
+        }
+      } else {
+        // No migrations table yet, create it
+        db.exec(`
+          CREATE TABLE migrations (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            branch TEXT NOT NULL DEFAULT 'main',
+            filename TEXT NOT NULL,
+            applied_at TEXT DEFAULT CURRENT_TIMESTAMP,
+            UNIQUE(branch, filename)
+          );
+        `);
+      }
+    } catch (e) {
+      // Migrations table doesn't exist, create it
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS migrations (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          branch TEXT NOT NULL DEFAULT 'main',
+          filename TEXT NOT NULL,
+          applied_at TEXT DEFAULT CURRENT_TIMESTAMP,
+          UNIQUE(branch, filename)
+        );
+      `);
+    }
+
+    // Migrate snapshots table
+    try {
+      const snapshotsInfo = db.pragma('table_info(snapshots)');
+      if (snapshotsInfo.length > 0) {
+        const hasBranchColumn = snapshotsInfo.some(col => col.name === 'branch');
+        const hasNameColumn = snapshotsInfo.some(col => col.name === 'name');
+
+        if (!hasBranchColumn || !hasNameColumn) {
+          console.log('  Migrating snapshots table...');
+          db.exec(`ALTER TABLE snapshots RENAME TO snapshots_old;`);
+
+          db.exec(`
+            CREATE TABLE snapshots (
+              id INTEGER PRIMARY KEY AUTOINCREMENT,
+              branch TEXT NOT NULL DEFAULT 'main',
+              filename TEXT NOT NULL UNIQUE,
+              name TEXT NOT NULL DEFAULT '',
+              size INTEGER,
+              created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+              description TEXT
+            );
+          `);
+
+          db.exec(`
+            INSERT INTO snapshots (id, branch, filename, name, size, created_at)
+            SELECT id, 'main', filename, filename, size, created_at FROM snapshots_old;
+          `);
+
+          db.exec(`DROP TABLE snapshots_old;`);
+        }
+      } else {
+        // No snapshots table yet, create it
+        db.exec(`
+          CREATE TABLE snapshots (
+            id INTEGER PRIMARY KEY AUTOINCREMENT,
+            branch TEXT NOT NULL DEFAULT 'main',
+            filename TEXT NOT NULL UNIQUE,
+            name TEXT NOT NULL DEFAULT '',
+            size INTEGER,
+            created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+            description TEXT
+          );
+        `);
+      }
+    } catch (e) {
+      // Snapshots table doesn't exist, create it
+      db.exec(`
+        CREATE TABLE IF NOT EXISTS snapshots (
+          id INTEGER PRIMARY KEY AUTOINCREMENT,
+          branch TEXT NOT NULL DEFAULT 'main',
+          filename TEXT NOT NULL UNIQUE,
+          name TEXT NOT NULL DEFAULT '',
+          size INTEGER,
+          created_at TEXT DEFAULT CURRENT_TIMESTAMP,
+          description TEXT
+        );
+      `);
+    }
+
+    // Create default 'main' branch if not exists
+    const hasBranches = db.prepare('SELECT COUNT(*) as count FROM branches').get();
+    if (hasBranches.count === 0) {
+      console.log('  Creating default main branch...');
+      db.prepare(`
+        INSERT INTO branches (name, db_file, created_from, description)
+        VALUES ('main', 'db.sqlite', NULL, 'Default branch')
+      `).run();
+    }
+
+    // Set main as current branch
+    db.prepare(`
+      INSERT OR REPLACE INTO settings (key, value) VALUES ('current_branch', 'main')
+    `).run();
+
+    // Update schema version
+    db.prepare(`
+      INSERT OR REPLACE INTO settings (key, value) VALUES ('schema_version', '1')
+    `).run();
+
+    console.log('✓ Meta DB migrated to v1');
+  }
+
+  // Migration v1 -> v2: Add type column to snapshots
+  if (version < 2) {
+    console.log('Migrating meta DB to v2 (snapshot types)...');
+
+    // Add type column to snapshots if it doesn't exist
+    try {
+      const snapshotsInfo = db.pragma('table_info(snapshots)');
+      const hasTypeColumn = snapshotsInfo.some(col => col.name === 'type');
+
+      if (!hasTypeColumn) {
+        console.log('  Adding type column to snapshots table...');
+        db.exec(`ALTER TABLE snapshots ADD COLUMN type TEXT DEFAULT 'manual';`);
+      }
+    } catch (e) {
+      console.log('  Error adding type column:', e.message);
+    }
+
+    // Update schema version
+    db.prepare(`
+      INSERT OR REPLACE INTO settings (key, value) VALUES ('schema_version', '2')
+    `).run();
+
+    console.log('✓ Meta DB migrated to v2');
+  }
+
+  db.close();
+}