pg-local-cli 1.0.0

package/README.md

@@ -0,0 +1,138 @@
+# pg-local-cli
+
+Một công cụ CLI bằng **Node.js** giúp bạn dễ dàng khởi tạo, khởi chạy và quản lý các database instance **PostgreSQL** trên localhost mà **không cần sử dụng Docker, Podman hay cài đặt PostgreSQL toàn hệ thống**.
+
+Dự án này sử dụng các binary PostgreSQL portable chính thức được tải tự động tùy theo hệ điều hành (Windows, macOS, Linux) thông qua thư viện `embedded-postgres`.
+
+## ✨ Tính năng chính
+
+- **Không cần Docker/Podman**: Phù hợp cho máy yếu hoặc môi trường không cài được Docker.
+- **Không cần cài Postgres hệ thống**: Tự động tải binary độc lập về thư mục home của user.
+- **Hỗ trợ đổi Host/Port**: Dễ dàng đổi cổng hoặc địa chỉ IP lắng nghe để tránh xung đột cổng (ví dụ: cổng mặc định 5432 bị chiếm).
+- **Chạy ngầm (Daemon)**: Khi gõ `start`, Postgres sẽ chạy ngầm, bạn có thể tắt terminal đi mà database vẫn chạy bình thường.
+- **Hỗ trợ nhiều Instance**: Tạo và cấu hình độc lập nhiều database khác nhau (ví dụ: `my_app`, `dev_db`).
+- **Đa nền tảng**: Hỗ trợ đầy đủ Windows (x64), macOS (Intel, Apple Silicon) và Linux (x64, arm64, v.v.).
+
+---
+
+## 🚀 Cài đặt
+
+Cài đặt global thông qua npm để sử dụng CLI ở mọi nơi:
+
+```bash
+npm install -g pg-local-cli
+```
+
+*(Lưu ý: npm sẽ tự động tải phiên bản PostgreSQL binary phù hợp nhất với OS và kiến trúc CPU của bạn trong quá trình cài đặt).*
+
+---
+
+## 🛠 Hướng dẫn sử dụng
+
+Sau khi cài đặt, bạn sẽ có lệnh `pg-local`.
+
+### 1. Khởi động PostgreSQL (Start)
+Khởi chạy instance mặc định (tên là `default`):
+
+```bash
+pg-local start
+```
+
+Khởi chạy một instance với tên cụ thể:
+```bash
+pg-local start my_app
+```
+*(Nếu đây là lần đầu chạy, CLI sẽ tự động khởi tạo database cluster - chạy `initdb` trước khi start).*
+
+### 2. Kiểm tra trạng thái (Status)
+Xem thông tin chi tiết của instance đang chạy hay dừng:
+
+```bash
+pg-local status
+```
+Hoặc xem instance cụ thể:
+```bash
+pg-local status my_app
+```
+
+### 3. Dừng PostgreSQL (Stop)
+Dừng instance một cách an toàn và giải phóng tài nguyên:
+
+```bash
+pg-local stop
+```
+Hoặc:
+```bash
+pg-local stop my_app
+```
+
+### 4. Liệt kê các instance (List)
+Xem danh sách toàn bộ các database instance mà bạn đã tạo cùng trạng thái và cổng chạy của chúng:
+
+```bash
+pg-local list
+```
+
+### 5. Cấu hình Host / Port / User (Config)
+Xem cấu hình hiện tại:
+```bash
+pg-local config show
+```
+
+Thay đổi các thông số cấu hình (Ví dụ thay đổi port thành `5433` để tránh xung đột cổng):
+```bash
+pg-local config set port 5433
+```
+
+Thay đổi port cho một instance cụ thể:
+```bash
+pg-local config set port 15432 my_app
+```
+
+Các khóa cấu hình hỗ trợ:
+- `port`: Cổng TCP chạy database (mặc định: `5432`).
+- `host`: Địa chỉ IP lắng nghe (mặc định: `127.0.0.1`).
+- `user`: Tên tài khoản superuser (mặc định: `postgres`).
+- `password`: Mật khẩu superuser (mặc định: `password`).
+- `databaseDir`: Đường dẫn lưu dữ liệu database (mặc định trong thư mục `~/.pg-local/instances/<name>/data`).
+
+### 6. Xem Log của PostgreSQL (Logs)
+Xem toàn bộ log đã ghi:
+```bash
+pg-local logs
+```
+
+Theo dõi log thời gian thực (real-time stream) giống như lệnh `tail -f`:
+```bash
+pg-local logs -f
+# Hoặc cho instance cụ thể
+pg-local logs my_app -f
+```
+
+### 7. Xóa dữ liệu (Destroy)
+Dừng database và xóa hoàn toàn thư mục chứa dữ liệu của instance đó:
+```bash
+pg-local destroy
+```
+
+---
+
+## 🔌 Chuỗi kết nối (Connection String)
+
+Mặc định, bạn có thể kết nối tới PostgreSQL bằng chuỗi kết nối:
+```
+postgresql://postgres:password@127.0.0.1:5432/postgres
+```
+*(Hoặc cổng mới nếu bạn đã thay đổi trong cấu hình).*
+
+Bạn có thể kết nối từ bất kỳ công cụ quản lý nào như **DBeaver**, **TablePlus**, **pgAdmin**, hoặc các ORM như **Prisma**, **Drizzle**, **TypeORM** trong dự án của bạn.
+
+## 📂 Nơi lưu trữ dữ liệu
+
+Toàn bộ cấu hình và dữ liệu của công cụ được lưu trữ độc lập tại:
+- **Unix/macOS/Linux**: `~/.pg-local/`
+- **Windows**: `C:\Users\<Tên_User>\.pg-local\`
+
+## 📄 Giấy phép
+
+Dự án này được phân phối dưới giấy phép **MIT**.

package/bin/index.js

@@ -0,0 +1,260 @@
+#!/usr/bin/env node
+
+const { Command } = require('commander');
+const fs = require('fs/promises');
+const path = require('path');
+const manager = require('../lib/manager');
+const { getLogPath, saveConfig, loadConfig } = require('../lib/config');
+
+const program = new Command();
+
+const colors = {
+  reset: '\x1b[0m',
+  bright: '\x1b[1m',
+  dim: '\x1b[2m',
+  red: '\x1b[31m',
+  green: '\x1b[32m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  magenta: '\x1b[35m',
+  cyan: '\x1b[36m',
+};
+
+function formatStatus(status) {
+  if (status.running) {
+    return `${colors.green}● Running (PID: ${status.pid})${colors.reset}`;
+  }
+  return `${colors.red}○ Stopped${colors.reset}`;
+}
+
+program
+  .name('pg-local')
+  .description('Manage local PostgreSQL instances without Docker/Podman')
+  .version('1.0.0');
+
+// Start Command
+program
+  .command('start [name]')
+  .description('Start a local PostgreSQL instance')
+  .action(async (name = 'default') => {
+    console.log(`${colors.cyan}Starting PostgreSQL instance "${name}"...${colors.reset}`);
+    try {
+      const result = await manager.startInstance(name);
+      if (result.alreadyRunning) {
+        console.log(`${colors.yellow}Instance "${name}" is already running (PID: ${result.pid}).${colors.reset}`);
+      } else {
+        console.log(`${colors.green}✓ PostgreSQL instance "${name}" successfully started!${colors.reset}`);
+      }
+      console.log(`\nConnection details:`);
+      console.log(`  ${colors.bright}Host:${colors.reset} ${result.config.host}`);
+      console.log(`  ${colors.bright}Port:${colors.reset} ${result.config.port}`);
+      console.log(`  ${colors.bright}User:${colors.reset} ${result.config.user}`);
+      console.log(`  ${colors.bright}Password:${colors.reset} ${result.config.password}`);
+      console.log(`  ${colors.bright}URI:${colors.reset} postgresql://${result.config.user}:${result.config.password}@${result.config.host}:${result.config.port}/postgres\n`);
+    } catch (err) {
+      console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+      process.exit(1);
+    }
+  });
+
+// Stop Command
+program
+  .command('stop [name]')
+  .description('Stop a local PostgreSQL instance')
+  .action(async (name = 'default') => {
+    console.log(`${colors.cyan}Stopping PostgreSQL instance "${name}"...${colors.reset}`);
+    try {
+      const result = await manager.stopInstance(name);
+      if (result.alreadyStopped) {
+        console.log(`${colors.yellow}Instance "${name}" is already stopped.${colors.reset}`);
+      } else if (result.forced) {
+        console.log(`${colors.yellow}! Instance "${name}" did not respond to graceful stop. Terminated forcefully.${colors.reset}`);
+      } else {
+        console.log(`${colors.green}✓ PostgreSQL instance "${name}" stopped gracefully.${colors.reset}`);
+      }
+    } catch (err) {
+      console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+      process.exit(1);
+    }
+  });
+
+// Status Command
+program
+  .command('status [name]')
+  .description('Check the status of a PostgreSQL instance')
+  .action(async (name = 'default') => {
+    try {
+      const status = await manager.getStatus(name);
+      console.log(`${colors.bright}Instance:${colors.reset} ${status.name}`);
+      console.log(`${colors.bright}Status:${colors.reset}   ${formatStatus(status)}`);
+      console.log(`${colors.bright}Host:${colors.reset}     ${status.host}`);
+      console.log(`${colors.bright}Port:${colors.reset}     ${status.port}`);
+      console.log(`${colors.bright}User:${colors.reset}     ${status.user}`);
+      console.log(`${colors.bright}Dir:${colors.reset}      ${status.databaseDir}`);
+      if (status.running) {
+        console.log(`${colors.bright}URI:${colors.reset}      ${status.connectionString}`);
+      }
+    } catch (err) {
+      console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+      process.exit(1);
+    }
+  });
+
+// List Command
+program
+  .command('list')
+  .description('List all local PostgreSQL instances')
+  .action(async () => {
+    try {
+      const instances = await manager.listInstances();
+      if (instances.length === 0) {
+        console.log(`${colors.yellow}No instances found. Start one with "pg-local start [name]".${colors.reset}`);
+        return;
+      }
+      console.log(`${colors.bright}Local PostgreSQL Instances:${colors.reset}`);
+      console.log(''.padEnd(50, '-'));
+      for (const inst of instances) {
+        const status = await manager.getStatus(inst.name);
+        console.log(`  ${colors.bright}${inst.name.padEnd(12)}${colors.reset} | ${formatStatus(status).padEnd(20)} | Port: ${inst.port}`);
+      }
+      console.log(''.padEnd(50, '-'));
+    } catch (err) {
+      console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+      process.exit(1);
+    }
+  });
+
+// Config Command
+const configCmd = program
+  .command('config')
+  .description('Manage configuration for PostgreSQL instances');
+
+configCmd
+  .command('show [name]')
+  .description('Show configuration for an instance')
+  .action(async (name = 'default') => {
+    try {
+      const config = await loadConfig(name);
+      console.log(JSON.stringify(config, null, 2));
+    } catch (err) {
+      console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+      process.exit(1);
+    }
+  });
+
+configCmd
+  .command('set <key> <value> [name]')
+  .description('Set a configuration parameter (key: port, host, user, password, databaseDir)')
+  .action(async (key, value, name = 'default') => {
+    try {
+      const config = await loadConfig(name);
+      
+      // Validation & parsing
+      if (key === 'port') {
+        const port = parseInt(value, 10);
+        if (isNaN(port) || port <= 0 || port > 65535) {
+          throw new Error('Port must be a valid number between 1 and 65535.');
+        }
+        config.port = port;
+      } else if (['host', 'user', 'password', 'databaseDir'].includes(key)) {
+        config[key] = value;
+      } else {
+        throw new Error(`Invalid config key "${key}". Valid keys: port, host, user, password, databaseDir`);
+      }
+
+      await saveConfig(name, config);
+      console.log(`${colors.green}✓ Saved configuration for "${name}": ${key} = ${value}${colors.reset}`);
+      console.log(`${colors.yellow}Note: If the instance is currently running, you must restart it for changes to take effect.${colors.reset}`);
+    } catch (err) {
+      console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+      process.exit(1);
+    }
+  });
+
+// Logs Command
+program
+  .command('logs [name]')
+  .description('Show logs of a local PostgreSQL instance')
+  .option('-f, --follow', 'Follow log output in real-time')
+  .action(async (name = 'default', options) => {
+    const logPath = getLogPath(name);
+    try {
+      const stats = await fs.stat(logPath);
+      if (!stats.isFile()) {
+        throw new Error('Not a file');
+      }
+    } catch (err) {
+      console.error(`${colors.red}No logs found at ${logPath}${colors.reset}`);
+      process.exit(1);
+    }
+
+    if (options.follow) {
+      console.log(`${colors.cyan}Following logs for "${name}" (Press Ctrl+C to stop)...${colors.reset}`);
+      try {
+        let stats = await fs.stat(logPath);
+        const initialData = await fs.readFile(logPath, 'utf8');
+        process.stdout.write(initialData);
+
+        let size = stats.size;
+        const interval = setInterval(async () => {
+          try {
+            const newStats = await fs.stat(logPath);
+            if (newStats.size > size) {
+              const fd = await fs.open(logPath, 'r');
+              const buffer = Buffer.alloc(newStats.size - size);
+              await fd.read(buffer, 0, buffer.length, size);
+              await fd.close();
+              process.stdout.write(buffer.toString('utf8'));
+              size = newStats.size;
+            } else if (newStats.size < size) {
+              size = newStats.size;
+            }
+          } catch (e) {}
+        }, 500);
+
+        process.on('SIGINT', () => {
+          clearInterval(interval);
+          process.exit(0);
+        });
+      } catch (err) {
+        console.error(`${colors.red}Error reading logs: ${err.message}${colors.reset}`);
+        process.exit(1);
+      }
+    } else {
+      const data = await fs.readFile(logPath, 'utf8');
+      process.stdout.write(data);
+    }
+  });
+
+// Destroy Command
+program
+  .command('destroy [name]')
+  .description('Stop instance and delete all data directory')
+  .action(async (name = 'default') => {
+    const readline = require('readline').createInterface({
+      input: process.stdin,
+      output: process.stdout,
+    });
+
+    const config = await loadConfig(name);
+    readline.question(
+      `${colors.red}${colors.bright}WARNING: This will permanently delete all data in "${config.databaseDir}".\nAre you sure you want to proceed? (y/N): ${colors.reset}`,
+      async (answer) => {
+        readline.close();
+        if (answer.toLowerCase() === 'y') {
+          console.log(`${colors.cyan}Destroying instance "${name}"...${colors.reset}`);
+          try {
+            await manager.destroyInstance(name);
+            console.log(`${colors.green}✓ Instance "${name}" has been destroyed.${colors.reset}`);
+          } catch (err) {
+            console.error(`${colors.red}Error: ${err.message}${colors.reset}`);
+            process.exit(1);
+          }
+        } else {
+          console.log('Action cancelled.');
+        }
+      }
+    );
+  });
+
+program.parse(process.argv);

package/lib/config.js

@@ -0,0 +1,107 @@
+const fs = require('fs/promises');
+const path = require('path');
+const os = require('os');
+
+const BASE_DIR = path.join(os.homedir(), '.pg-local');
+
+function getInstanceDir(name) {
+  return path.join(BASE_DIR, 'instances', name);
+}
+
+function getConfigPath(name) {
+  return path.join(getInstanceDir(name), 'config.json');
+}
+
+function getPidPath(name) {
+  return path.join(getInstanceDir(name), 'daemon.pid');
+}
+
+function getLogPath(name) {
+  return path.join(getInstanceDir(name), 'postgres.log');
+}
+
+const DEFAULT_CONFIG = {
+  port: 5432,
+  host: '127.0.0.1',
+  user: 'postgres',
+  password: 'password',
+};
+
+async function ensureBaseDir() {
+  await fs.mkdir(BASE_DIR, { recursive: true });
+  await fs.mkdir(path.join(BASE_DIR, 'instances'), { recursive: true });
+}
+
+async function loadConfig(name = 'default') {
+  await ensureBaseDir();
+  const configPath = getConfigPath(name);
+  const instanceDir = getInstanceDir(name);
+
+  let loaded = {};
+  try {
+    const data = await fs.readFile(configPath, 'utf8');
+    loaded = JSON.parse(data);
+  } catch (err) {
+    // Config doesn't exist yet, we will write defaults
+  }
+
+  // Merge with defaults and set derived properties (like databaseDir)
+  const config = {
+    name,
+    port: loaded.port || DEFAULT_CONFIG.port,
+    host: loaded.host || DEFAULT_CONFIG.host,
+    user: loaded.user || DEFAULT_CONFIG.user,
+    password: loaded.password || DEFAULT_CONFIG.password,
+    databaseDir: loaded.databaseDir || path.join(instanceDir, 'data'),
+  };
+
+  return config;
+}
+
+async function saveConfig(name, config) {
+  await ensureBaseDir();
+  const instanceDir = getInstanceDir(name);
+  await fs.mkdir(instanceDir, { recursive: true });
+  
+  const configPath = getConfigPath(name);
+  await fs.writeFile(configPath, JSON.stringify(config, null, 2), 'utf8');
+}
+
+async function listInstances() {
+  await ensureBaseDir();
+  const instancesDir = path.join(BASE_DIR, 'instances');
+  try {
+    const files = await fs.readdir(instancesDir, { withFileTypes: true });
+    const list = [];
+    for (const file of files) {
+      if (file.isDirectory()) {
+        try {
+          const config = await loadConfig(file.name);
+          list.push(config);
+        } catch (e) {
+          // Ignore invalid directories
+        }
+      }
+    }
+    return list;
+  } catch (err) {
+    return [];
+  }
+}
+
+async function deleteInstanceDir(name) {
+  const instanceDir = getInstanceDir(name);
+  await fs.rm(instanceDir, { recursive: true, force: true });
+}
+
+module.exports = {
+  BASE_DIR,
+  getInstanceDir,
+  getConfigPath,
+  getPidPath,
+  getLogPath,
+  loadConfig,
+  saveConfig,
+  listInstances,
+  deleteInstanceDir,
+};

package/lib/daemon.js

@@ -0,0 +1,119 @@
+const fs = require('fs');
+const fsPromises = require('fs/promises');
+const path = require('path');
+const EmbeddedPostgres = require('embedded-postgres').default;
+const { loadConfig, getPidPath, getLogPath, getInstanceDir } = require('./config');
+
+const instanceName = process.argv[2] || 'default';
+
+async function run() {
+  const config = await loadConfig(instanceName);
+  const pidPath = getPidPath(instanceName);
+  const logPath = getLogPath(instanceName);
+  const instanceDir = getInstanceDir(instanceName);
+  const stopPath = path.join(instanceDir, 'daemon.stop');
+
+  // Synchronous log writer to prevent buffering issues on exit
+  const writeLog = (msg) => {
+    const line = `[${new Date().toISOString()}] ${msg.trim()}\n`;
+    try {
+      fs.appendFileSync(logPath, line, 'utf8');
+    } catch (e) {
+      console.error('Failed to write to log file:', e);
+    }
+  };
+
+  // Write our PID to file so manager can stop us
+  await fsPromises.writeFile(pidPath, process.pid.toString(), 'utf8');
+
+  // Clean up any stale stop file
+  await fsPromises.unlink(stopPath).catch(() => {});
+
+  writeLog(`Daemon started with PID ${process.pid}`);
+
+  const pg = new EmbeddedPostgres({
+    databaseDir: config.databaseDir,
+    user: config.user,
+    password: config.password,
+    port: config.port,
+    persistent: true,
+    args: ['-h', config.host],
+    onLog: (msg) => writeLog(msg),
+    onError: (err) => writeLog(`[ERROR] ${err.message || err}`),
+  });
+
+  let isStopping = false;
+  async function gracefulShutdown() {
+    if (isStopping) return;
+    isStopping = true;
+    
+    if (checkStopInterval) {
+      clearInterval(checkStopInterval);
+    }
+    
+    writeLog('Received stop signal, shutting down PostgreSQL...');
+    try {
+      await pg.stop();
+      writeLog('PostgreSQL stopped successfully.');
+    } catch (err) {
+      writeLog(`Error stopping PostgreSQL: ${err.message || err}`);
+    }
+    
+    // Clean up pid and stop files
+    try {
+      await fsPromises.unlink(pidPath);
+    } catch (e) {}
+    try {
+      await fsPromises.unlink(stopPath);
+    } catch (e) {}
+
+    writeLog('Daemon exiting.');
+    process.exit(0);
+  }
+
+  // Monitor for the stop file
+  const checkStopInterval = setInterval(async () => {
+    try {
+      await fsPromises.access(stopPath);
+      writeLog('Stop file detected.');
+      await gracefulShutdown();
+    } catch (e) {
+      // File not found, keep running
+    }
+  }, 500);
+
+  // Handle standard signals
+  process.on('SIGTERM', gracefulShutdown);
+  process.on('SIGINT', gracefulShutdown);
+
+  try {
+    // If not initialized, initialize it first
+    const isInitialized = await fsPromises.access(path.join(config.databaseDir, 'PG_VERSION'))
+      .then(() => true)
+      .catch(() => false);
+
+    if (!isInitialized) {
+      writeLog('Initializing database cluster...');
+      await pg.initialise();
+      writeLog('Database cluster initialized.');
+    }
+
+    writeLog(`Starting PostgreSQL on ${config.host}:${config.port}...`);
+    await pg.start();
+    writeLog('PostgreSQL is ready to accept connections.');
+  } catch (err) {
+    writeLog(`Fatal startup error: ${err.message || err}`);
+    try {
+      await fsPromises.unlink(pidPath);
+    } catch (e) {}
+    try {
+      await fsPromises.unlink(stopPath);
+    } catch (e) {}
+    process.exit(1);
+  }
+}
+
+run().catch((err) => {
+  console.error('Fatal daemon error:', err);
+  process.exit(1);
+});

package/lib/manager.js

@@ -0,0 +1,242 @@
+const fs = require('fs/promises');
+const path = require('path');
+const net = require('net');
+const { spawn, execSync } = require('child_process');
+const {
+  loadConfig,
+  saveConfig,
+  getPidPath,
+  getLogPath,
+  getInstanceDir,
+  deleteInstanceDir,
+  listInstances,
+} = require('./config');
+
+// Check if a TCP port is open and listening
+function checkPort(port, host, timeout = 1000) {
+  return new Promise((resolve) => {
+    const socket = new net.Socket();
+    const onError = () => {
+      socket.destroy();
+      resolve(false);
+    };
+
+    socket.setTimeout(timeout);
+    socket.once('error', onError);
+    socket.once('timeout', onError);
+
+    socket.connect(port, host, () => {
+      socket.end();
+      resolve(true);
+    });
+  });
+}
+
+// Check if a process ID is running
+function isPidAlive(pid) {
+  if (process.platform === 'win32') {
+    try {
+      const output = execSync(`tasklist /fi "PID eq ${pid}"`, { encoding: 'utf8' });
+      return output.includes(pid.toString());
+    } catch (e) {
+      return false;
+    }
+  } else {
+    try {
+      process.kill(pid, 0);
+      return true;
+    } catch (err) {
+      return err.code === 'EPERM';
+    }
+  }
+}
+
+// Forcefully terminate a process
+function forceKill(pid) {
+  if (process.platform === 'win32') {
+    try {
+      execSync(`taskkill /pid ${pid} /f /t`);
+    } catch (e) {}
+  } else {
+    try {
+      process.kill(pid, 'SIGKILL');
+    } catch (e) {}
+  }
+}
+
+// Helper to wait
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+async function getRunningPid(name) {
+  const pidPath = getPidPath(name);
+  try {
+    const pidStr = await fs.readFile(pidPath, 'utf8');
+    const pid = parseInt(pidStr.trim(), 10);
+    if (!isNaN(pid) && isPidAlive(pid)) {
+      return pid;
+    }
+  } catch (e) {}
+  return null;
+}
+
+async function startInstance(name) {
+  const config = await loadConfig(name);
+  
+  // Check if already running
+  const runningPid = await getRunningPid(name);
+  if (runningPid) {
+    return {
+      success: true,
+      alreadyRunning: true,
+      pid: runningPid,
+      config,
+    };
+  }
+
+  // Check if port is already in use by another process
+  const portInUse = await checkPort(config.port, config.host);
+  if (portInUse) {
+    throw new Error(`Port ${config.port} is already in use by another process on ${config.host}. Choose a different port using: pg-local config set port <new_port> ${name}`);
+  }
+
+  // Ensure directories are clean
+  const instanceDir = getInstanceDir(name);
+  await fs.mkdir(instanceDir, { recursive: true });
+  
+  const stopPath = path.join(instanceDir, 'daemon.stop');
+  await fs.unlink(stopPath).catch(() => {});
+
+  // Spawn daemon in background
+  const daemonPath = path.join(__dirname, 'daemon.js');
+  const child = spawn(process.execPath, [daemonPath, name], {
+    detached: true,
+    stdio: 'ignore',
+  });
+  child.unref();
+
+  // Wait for the server to become ready (up to 15 seconds)
+  const startTime = Date.now();
+  const timeoutMs = 15000;
+  let isReady = false;
+
+  while (Date.now() - startTime < timeoutMs) {
+    // Check if the PID file exists and is alive
+    const currentPid = await getRunningPid(name);
+    if (currentPid) {
+      // Check if the port is open now
+      const portOpen = await checkPort(config.port, config.host);
+      if (portOpen) {
+        isReady = true;
+        break;
+      }
+    } else {
+      // Check if the daemon process died
+      try {
+        const pidStr = await fs.readFile(getPidPath(name), 'utf8');
+        const pid = parseInt(pidStr.trim(), 10);
+        if (!isNaN(pid) && !isPidAlive(pid)) {
+          // Daemon was started but is now dead!
+          break;
+        }
+      } catch (e) {
+        // PID file doesn't exist yet, or is empty. Keep waiting.
+      }
+    }
+    await sleep(200);
+  }
+
+  if (!isReady) {
+    // Check if the process exited or logged errors
+    const pid = await getRunningPid(name);
+    if (!pid) {
+      throw new Error(`PostgreSQL daemon failed to start. Check logs at: ${getLogPath(name)}`);
+    } else {
+      throw new Error(`PostgreSQL started but did not respond on ${config.host}:${config.port} within 15 seconds.`);
+    }
+  }
+
+  const pid = await getRunningPid(name);
+  return {
+    success: true,
+    alreadyRunning: false,
+    pid,
+    config,
+  };
+}
+
+async function stopInstance(name) {
+  const pid = await getRunningPid(name);
+  if (!pid) {
+    return { success: true, alreadyStopped: true };
+  }
+
+  const instanceDir = getInstanceDir(name);
+  const stopPath = path.join(instanceDir, 'daemon.stop');
+
+  // Request graceful shutdown by creating the stop file
+  await fs.writeFile(stopPath, 'stop', 'utf8');
+
+  // Also send SIGTERM for Unix systems as secondary trigger
+  if (process.platform !== 'win32') {
+    try {
+      process.kill(pid, 'SIGTERM');
+    } catch (e) {}
+  }
+
+  // Wait for it to stop (up to 8 seconds)
+  const startTime = Date.now();
+  const timeoutMs = 8000;
+  let stopped = false;
+
+  while (Date.now() - startTime < timeoutMs) {
+    if (!isPidAlive(pid)) {
+      stopped = true;
+      break;
+    }
+    await sleep(200);
+  }
+
+  // If not stopped, force kill
+  if (!stopped) {
+    forceKill(pid);
+    // Cleanup files
+    const pidPath = getPidPath(name);
+    await fs.unlink(pidPath).catch(() => {});
+    await fs.unlink(stopPath).catch(() => {});
+    return { success: true, forced: true };
+  }
+
+  return { success: true, forced: false };
+}
+
+async function getStatus(name) {
+  const config = await loadConfig(name);
+  const pid = await getRunningPid(name);
+  const isPortOpen = await checkPort(config.port, config.host);
+
+  return {
+    name,
+    running: !!pid && isPortOpen,
+    pid,
+    port: config.port,
+    host: config.host,
+    user: config.user,
+    databaseDir: config.databaseDir,
+    connectionString: `postgresql://${config.user}:${config.password}@${config.host}:${config.port}/postgres`,
+  };
+}
+
+async function destroyInstance(name) {
+  await stopInstance(name);
+  await deleteInstanceDir(name);
+}
+
+module.exports = {
+  startInstance,
+  stopInstance,
+  getStatus,
+  destroyInstance,
+  loadConfig,
+  saveConfig,
+  listInstances,
+};

package/package.json

@@ -0,0 +1,31 @@
+{
+  "name": "pg-local-cli",
+  "version": "1.0.0",
+  "description": "A Node.js CLI tool to easily create, start, and manage local PostgreSQL instances without Docker, Podman, or system dependencies.",
+  "main": "bin/index.js",
+  "bin": {
+    "pg-local": "bin/index.js"
+  },
+  "engines": {
+    "node": ">=16"
+  },
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1"
+  },
+  "keywords": [
+    "postgres",
+    "postgresql",
+    "local",
+    "cli",
+    "database",
+    "embedded",
+    "without-docker",
+    "development"
+  ],
+  "author": "Antigravity Dev",
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.0.0",
+    "embedded-postgres": "^18.4.0-beta.17"
+  }
+}