sql-kite 1.0.0

package/bin/sql-kite.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/index.js';

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "sql-kite",
+  "version": "1.0.0",
+  "description": "SQL-Kite CLI — Local-first SQLite workspace with branches, migrations and snapshots.",
+  "type": "module",
+  "bin": {
+    "sql-kite": "./bin/sql-kite.js"
+  },
+  "scripts": {
+    "dev": "node bin/sql-kite.js",
+    "start": "node bin/sql-kite.js"
+  },
+  "author": "D Krishna",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Ananta-V/sql-kite"
+  },
+  "homepage": "https://github.com/Ananta-V/sql-kite#readme",
+  "bugs": {
+    "url": "https://github.com/Ananta-V/sql-kite/issues"
+  },
+  "keywords": [
+    "sqlite",
+    "database",
+    "cli",
+    "migration",
+    "branching",
+    "snapshots",
+    "local-first",
+    "developer-tools"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "dependencies": {
+    "better-sqlite3": "^9.2.2",
+    "chalk": "^5.3.0",
+    "commander": "^12.0.0",
+    "find-free-port": "^2.0.0",
+    "inquirer": "^9.2.12",
+    "open": "^10.0.3",
+    "ora": "^8.0.1"
+  }
+}

package/src/commands/delete.js

@@ -0,0 +1,43 @@
+import { rmSync } from 'fs';
+import chalk from 'chalk';
+import inquirer from 'inquirer';
+import ora from 'ora';
+import { getProjectPath, projectExists } from '../utils/paths.js';
+import { stopCommand } from './stop.js';
+
+export async function deleteCommand(name) {
+  if (!projectExists(name)) {
+    console.log(chalk.red(`✗ Project "${name}" does not exist`));
+    process.exit(1);
+  }
+  
+  const { confirm } = await inquirer.prompt([
+    {
+      type: 'confirm',
+      name: 'confirm',
+      message: `Delete project "${name}"? This cannot be undone.`,
+      default: false
+    }
+  ]);
+  
+  if (!confirm) {
+    console.log(chalk.dim('Cancelled'));
+    return;
+  }
+  
+  const spinner = ora(`Deleting project "${name}"...`).start();
+  
+  try {
+    // Stop if running
+    await stopCommand(name).catch(() => {});
+    
+    // Delete project folder
+    rmSync(getProjectPath(name), { recursive: true, force: true });
+    
+    spinner.succeed(chalk.green(`✓ Project "${name}" deleted`));
+  } catch (error) {
+    spinner.fail(chalk.red('✗ Failed to delete project'));
+    console.error(error);
+    process.exit(1);
+  }
+}

package/src/commands/import-server.js

@@ -0,0 +1,50 @@
+#!/usr/bin/env node
+
+import { spawn } from 'child_process'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import chalk from 'chalk'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export default function importServerCommand(port = 3000) {
+  console.log(chalk.cyan('→ Starting import server...'))
+  console.log(chalk.dim(`  Port: ${port}`))
+  console.log(chalk.dim('  Mode: Import-only'))
+  console.log('')
+
+  const serverPath = join(__dirname, '../../../server/src/index.js')
+
+  const serverProcess = spawn('node', [serverPath], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      PORT: port,
+      IMPORT_MODE: 'true'
+    }
+  })
+
+  serverProcess.on('error', (error) => {
+    console.error(chalk.red('✗ Failed to start import server:'), error.message)
+    process.exit(1)
+  })
+
+  serverProcess.on('exit', (code) => {
+    if (code !== 0) {
+      console.error(chalk.red(`✗ Import server exited with code ${code}`))
+      process.exit(code)
+    }
+  })
+
+  // Handle Ctrl+C
+  process.on('SIGINT', () => {
+    console.log(chalk.yellow('\n→ Stopping import server...'))
+    serverProcess.kill('SIGINT')
+    process.exit(0)
+  })
+
+  console.log(chalk.green('✓ Import server started'))
+  console.log(chalk.dim(`  Open: http://localhost:${port}`))
+  console.log('')
+  console.log(chalk.dim('Press Ctrl+C to stop'))
+}

package/src/commands/import.js

@@ -0,0 +1,280 @@
+#!/usr/bin/env node
+
+import { existsSync, statSync, accessSync, constants, writeFileSync, mkdirSync } from 'fs'
+import { resolve, extname, basename, join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import Database from 'better-sqlite3'
+import chalk from 'chalk'
+import { spawn } from 'child_process'
+import http from 'http'
+import open from 'open'
+import { findFreePort } from '../utils/port-finder.js'
+import { ensureSqlKiteDirs, LOGS_DIR } from '../utils/paths.js'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+
+export default async function importCommand(dbPath) {
+  ensureSqlKiteDirs()
+  if (!dbPath) {
+    console.error(chalk.red('✗ Error: Database path is required'))
+    console.log(chalk.dim('Usage: npm run sql-kite import <path-to-database>'))
+    console.log(chalk.dim('   Or: npm run sql-kite open <path-to-database>'))
+    process.exit(1)
+  }
+
+  const absolutePath = resolve(dbPath)
+
+  // ========================================
+  // Step 1: Preflight checks
+  // ========================================
+  
+  console.log(chalk.cyan('→ Running preflight checks...'))
+
+  // Check file exists
+  if (!existsSync(absolutePath)) {
+    console.error(chalk.red('✗ Error: File does not exist'))
+    console.error(chalk.dim(`  Path: ${absolutePath}`))
+    process.exit(1)
+  }
+
+  // Check it's a file, not directory
+  const stats = statSync(absolutePath)
+  if (stats.isDirectory()) {
+    console.error(chalk.red('✗ Error: Path is a directory, not a database file'))
+    console.error(chalk.dim('  Please provide a path to a .db file'))
+    process.exit(1)
+  }
+
+  // Check for symlinks (security)
+  if (stats.isSymbolicLink()) {
+    console.error(chalk.red('✗ Error: Symlinks are not supported for security reasons'))
+    console.error(chalk.dim('  Please provide a direct path to the database file'))
+    process.exit(1)
+  }
+
+  // Check file is readable
+  try {
+    accessSync(absolutePath, constants.R_OK)
+  } catch (err) {
+    console.error(chalk.red('✗ Error: File is not readable'))
+    console.error(chalk.dim(`  Permission denied: ${absolutePath}`))
+    process.exit(1)
+  }
+
+  // Warn about file extension (don't block)
+  const ext = extname(absolutePath).toLowerCase()
+  if (ext !== '.db' && ext !== '.sqlite' && ext !== '.sqlite3') {
+    console.log(chalk.yellow('⚠ Warning: File extension is not .db, .sqlite, or .sqlite3'))
+    console.log(chalk.dim(`  Found: ${ext || '(no extension)'}`))
+    console.log(chalk.dim('  Continuing anyway...'))
+  }
+
+  console.log(chalk.green('✓ Preflight checks passed'))
+
+  // ========================================
+  // Step 2: Read-only probe
+  // ========================================
+
+  console.log(chalk.cyan('→ Validating SQLite database...'))
+
+  let db
+  try {
+    // Open in read-only mode (no WAL writes, no side effects)
+    db = new Database(absolutePath, { readonly: true, fileMustExist: true })
+
+    // Test basic query
+    try {
+      db.prepare('SELECT name FROM sqlite_master LIMIT 1').all()
+    } catch (err) {
+      console.error(chalk.red('✗ Error: File is not a valid SQLite database'))
+      console.error(chalk.dim(`  ${err.message}`))
+      db.close()
+      process.exit(1)
+    }
+
+    // Get metadata
+    const userVersion = db.prepare('PRAGMA user_version').get().user_version
+    const journalMode = db.prepare('PRAGMA journal_mode').get().journal_mode
+
+    console.log(chalk.green('✓ Valid SQLite database detected'))
+    console.log(chalk.dim(`  User version: ${userVersion}`))
+    console.log(chalk.dim(`  Journal mode: ${journalMode}`))
+
+    // Get table count
+    const tableCount = db.prepare(`
+      SELECT COUNT(*) as count 
+      FROM sqlite_master 
+      WHERE type='table' AND name NOT LIKE 'sqlite_%'
+    `).get().count
+
+    console.log(chalk.dim(`  Tables: ${tableCount}`))
+
+    db.close()
+  } catch (err) {
+    if (db) db.close()
+    console.error(chalk.red('✗ Error: Failed to open database'))
+    console.error(chalk.dim(`  ${err.message}`))
+    process.exit(1)
+  }
+
+  // ========================================
+  // Step 3: Generate project name suggestion
+  // ========================================
+
+  const suggestedName = basename(absolutePath, extname(absolutePath))
+    .toLowerCase()
+    .replace(/[^a-z0-9-]/g, '-')
+    .replace(/-+/g, '-')
+    .replace(/^-|-$/g, '')
+
+  // ========================================
+  // Step 4: Import through Studio
+  // ========================================
+
+  console.log('')
+  console.log(chalk.green('✓ Database validated successfully'))
+  console.log('')
+
+  // Store import session data
+  const homeDir = process.env.HOME || process.env.USERPROFILE
+  const sqlKiteDir = join(homeDir, '.sql-kite')
+  const sessionFile = join(sqlKiteDir, 'import-pending.json')
+
+  // Ensure .sql-kite directory exists
+  if (!existsSync(sqlKiteDir)) {
+    mkdirSync(sqlKiteDir, { recursive: true })
+  }
+
+  const importSession = {
+    sourcePath: absolutePath,
+    suggestedName,
+    validated: true,
+    timestamp: Date.now()
+  }
+
+  writeFileSync(sessionFile, JSON.stringify(importSession, null, 2))
+
+  const defaultPort = 3000
+  const importUrl = (port) => `http://localhost:${port}`
+
+  async function getImportServerPort() {
+    try {
+      const mode = await new Promise((resolve, reject) => {
+        const req = http.get(`http://localhost:${defaultPort}/api/project`, (res) => {
+          let raw = ''
+          res.on('data', (chunk) => { raw += chunk })
+          res.on('end', () => {
+            try {
+              const data = JSON.parse(raw)
+              resolve(data.mode || 'project')
+            } catch (e) {
+              resolve('project')
+            }
+          })
+        })
+        req.on('error', reject)
+        req.setTimeout(500, () => {
+          req.destroy()
+          reject(new Error('Timeout'))
+        })
+      })
+
+      if (mode === 'import') {
+        return { port: defaultPort, alreadyRunning: true }
+      }
+    } catch (e) {
+      // Not running on default port
+    }
+
+    const port = await findFreePort(defaultPort)
+    return { port, alreadyRunning: false }
+  }
+
+  async function waitForImportServer(port, maxAttempts = 60) {
+    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) {
+        await new Promise(resolve => setTimeout(resolve, 500))
+      }
+    }
+    return false
+  }
+
+  console.log(chalk.bold('Import session ready!'))
+  console.log('')
+  console.log(chalk.cyan('→ Next steps:'))
+  console.log(chalk.dim(`  1. Launching import Studio...`))
+  console.log(chalk.dim(`  2. Complete the import wizard`))
+  console.log('')
+  console.log(chalk.dim(`Session saved to: ${sessionFile}`))
+
+  const studioPath = join(__dirname, '../../../studio/out')
+  if (!existsSync(studioPath)) {
+    console.log(chalk.red(`\n✗ Studio UI not built yet`))
+    console.log(chalk.dim(`   Run: ${chalk.cyan(`cd packages/studio && npm run build`)}`))
+    return
+  }
+
+  try {
+    const { port, alreadyRunning } = await getImportServerPort()
+
+    if (!alreadyRunning) {
+      const serverPath = join(__dirname, '../../../server/src/index.js')
+      const logPath = join(LOGS_DIR, `import-server-${Date.now()}.log`)
+      const out = []
+      const serverProcess = spawn('node', [serverPath], {
+        detached: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+        env: {
+          ...process.env,
+          PORT: port.toString(),
+          IMPORT_MODE: 'true'
+        }
+      })
+
+      serverProcess.stdout.on('data', (chunk) => {
+        out.push(chunk.toString())
+      })
+
+      serverProcess.stderr.on('data', (chunk) => {
+        out.push(chunk.toString())
+      })
+
+      serverProcess.unref()
+
+      const ready = await waitForImportServer(port)
+      if (!ready) {
+        if (out.length > 0) {
+          writeFileSync(logPath, out.join(''))
+          console.log(chalk.red('✗ Import server failed to start in time'))
+          console.log(chalk.dim(`   Log: ${logPath}`))
+        } else {
+          console.log(chalk.red('✗ Import server failed to start in time'))
+          console.log(chalk.dim('   No logs captured. The server may not have started.'))
+        }
+        return
+      }
+    }
+
+    console.log(chalk.cyan(`Opening ${importUrl(port)}...`))
+    await open(importUrl(port))
+  } catch (error) {
+    console.log(chalk.red('✗ Failed to launch import Studio'))
+    console.log(chalk.dim(error.message))
+  }
+}

package/src/commands/init.js

@@ -0,0 +1,193 @@
+import { existsSync, mkdirSync, writeFileSync } from 'fs';
+import { join } from 'path';
+import chalk from 'chalk';
+import ora from 'ora';
+import inquirer from 'inquirer';
+
+const ENGINE_DEV_TEMPLATE = `/**
+ * Development Database Engine
+ * Connects to SQL-Kite server via HTTP
+ * Used during development only
+ * 
+ * ✅ LOCKED TO MAIN BRANCH
+ * The API is hardcoded to ONLY query the 'main' branch.
+ * You can switch branches in SQL-Kite Studio without affecting your app.
+ * Your app will always query main.
+ * 
+ * Port Configuration:
+ * 1. Set SQL_KITE_PORT environment variable
+ * 2. Or update DEFAULT_PORT below
+ * 3. Port is shown when you run: sql-kite start <project>
+ */
+
+const DEFAULT_PORT = 3000;
+
+// Auto-detect port from environment or use default
+const getApiUrl = () => {
+  const port = process.env.SQL_KITE_PORT || DEFAULT_PORT;
+  return "http://localhost:" + port;
+};
+
+export async function runDevQuery(sql, params = []) {
+  try {
+    const apiUrl = getApiUrl();
+    const res = await fetch(apiUrl + "/api/query", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ sql, params }),
+    });
+
+    const data = await res.json();
+
+    if (!data.ok) {
+      throw new Error(data.error || "Query failed");
+    }
+
+    return data.result;
+  } catch (error) {
+    console.error("Dev database error:", error);
+    console.error("Make sure SQL-Kite is running on port " + (process.env.SQL_KITE_PORT || DEFAULT_PORT));
+    throw error;
+  }
+}
+`;
+
+const ENGINE_LOCAL_TEMPLATE = `/**
+ * Local Database Engine
+ * Connects to local SQLite database using expo-sqlite
+ * Used in production builds
+ * 
+ * IMPORTANT: Install expo-sqlite first:
+ * npx expo install expo-sqlite
+ */
+
+import * as SQLite from "expo-sqlite";
+
+const db = SQLite.openDatabase("main.db");
+
+export function runLocalQuery(sql, params = []) {
+  return new Promise((resolve, reject) => {
+    db.transaction(tx => {
+      tx.executeSql(
+        sql,
+        params,
+        (_, result) => {
+          resolve(result.rows._array);
+        },
+        (_, error) => {
+          reject(error);
+          return false;
+        }
+      );
+    });
+  });
+}
+`;
+
+const INDEX_TEMPLATE = `/**
+ * Unified Database Layer
+ * Automatically switches between dev and production engines
+ * 
+ * Usage in your app:
+ * 
+ * import { runQuery } from '@/lib/database';
+ * 
+ * const users = await runQuery(
+ *   "SELECT * FROM users WHERE active = ?",
+ *   [1]
+ * );
+ */
+
+import { runDevQuery } from "./engine.dev";
+import { runLocalQuery } from "./engine.local";
+
+// In Expo, __DEV__ is available globally
+const isDev = typeof __DEV__ !== 'undefined' ? __DEV__ : process.env.NODE_ENV === 'development';
+
+export async function runQuery(sql, params = []) {
+  try {
+    if (isDev) {
+      // Development: Use HTTP connection to SQL-Kite
+      return await runDevQuery(sql, params);
+    } else {
+      // Production: Use local SQLite database
+      return await runLocalQuery(sql, params);
+    }
+  } catch (error) {
+    console.error("Database Error:", error);
+    throw error;
+  }
+}
+
+// Export individual engines for advanced use cases
+export { runDevQuery, runLocalQuery };
+`;
+
+export async function initCommand() {
+  const spinner = ora('Initializing database layer...').start();
+
+  try {
+    // Determine target directory
+    const targetDir = join(process.cwd(), 'lib', 'database');
+    const relativeDir = 'lib/database';
+
+    // Check if directory already exists
+    if (existsSync(targetDir)) {
+      spinner.stop();
+      
+      const { overwrite } = await inquirer.prompt([
+        {
+          type: 'confirm',
+          name: 'overwrite',
+          message: chalk.yellow('Directory ' + relativeDir + ' already exists. Overwrite?'),
+          default: false
+        }
+      ]);
+
+      if (!overwrite) {
+        console.log(chalk.dim('   Cancelled.'));
+        return;
+      }
+
+      spinner.start('Creating database layer...');
+    }
+
+    // Create directory
+    mkdirSync(targetDir, { recursive: true });
+
+    // Write files
+    writeFileSync(join(targetDir, 'engine.dev.js'), ENGINE_DEV_TEMPLATE);
+    writeFileSync(join(targetDir, 'engine.local.js'), ENGINE_LOCAL_TEMPLATE);
+    writeFileSync(join(targetDir, 'index.js'), INDEX_TEMPLATE);
+
+    spinner.succeed('Database layer created successfully!');
+
+    // Print instructions
+    console.log('');
+    console.log(chalk.bold('📁 Files created:'));
+    console.log(chalk.dim('   ' + relativeDir + '/index.js'));
+    console.log(chalk.dim('   ' + relativeDir + '/engine.dev.js'));
+    console.log(chalk.dim('   ' + relativeDir + '/engine.local.js'));
+    console.log('');
+    console.log(chalk.bold('🚀 Usage:'));
+    console.log(chalk.cyan("   import { runQuery } from '@/lib/database';"));
+    console.log(chalk.cyan('   const users = await runQuery("SELECT * FROM users");'));
+    console.log('');
+    console.log(chalk.bold('📖 Next steps:'));
+    console.log(chalk.dim('   1. Start SQL-Kite: ' + chalk.cyan('npm run sql-kite start <project>')));
+    console.log(chalk.dim('   2. Note the port (e.g., localhost:3001)'));
+    console.log(chalk.dim('   3. Set port: ' + chalk.cyan('SQL_KITE_PORT=3001 in .env')));
+    console.log(chalk.dim('   4. Use runQuery() in your app'));
+    console.log(chalk.dim('   5. For production: ' + chalk.cyan('npx expo install expo-sqlite')));
+    console.log('');
+    console.log(chalk.bold('⚙️  Port configuration:'));
+    console.log(chalk.dim('   • AUTO: Set SQL_KITE_PORT env variable (recommended)'));
+    console.log(chalk.dim('   • MANUAL: Edit DEFAULT_PORT in engine.dev.js'));
+    console.log('');
+
+  } catch (error) {
+    spinner.fail('Failed to initialize database layer');
+    console.error(chalk.red('   Error: ' + error.message));
+    process.exit(1);
+  }
+}

package/src/commands/list.js

@@ -0,0 +1,33 @@
+import { readdirSync, existsSync, readFileSync } from 'fs';
+import chalk from 'chalk';
+import { RUNTIME_DIR, getProjectServerInfoPath } from '../utils/paths.js';
+
+export async function listCommand() {
+  if (!existsSync(RUNTIME_DIR)) {
+    console.log(chalk.dim('No projects yet'));
+    return;
+  }
+  
+  const projects = readdirSync(RUNTIME_DIR);
+  
+  if (projects.length === 0) {
+    console.log(chalk.dim('No projects yet'));
+    return;
+  }
+  
+  console.log(chalk.bold('\nProjects:\n'));
+  
+  projects.forEach(name => {
+    const serverInfoPath = getProjectServerInfoPath(name);
+    const isRunning = existsSync(serverInfoPath);
+    
+    if (isRunning) {
+      const serverInfo = JSON.parse(readFileSync(serverInfoPath, 'utf-8'));
+      console.log(`  ${chalk.green('●')} ${chalk.bold(name)} ${chalk.dim(`(port ${serverInfo.port})`)}`);
+    } else {
+      console.log(`  ${chalk.gray('○')} ${name}`);
+    }
+  });
+  
+  console.log();
+}