aptunnel 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Uruba Software
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,249 @@
+# aptunnel
+
+Cross-platform Aptible tunnel manager. Open, close, and monitor multiple database tunnels with short aliases instead of long Aptible handles.
+
+```
+aptunnel dev-db          # open tunnel to dev database
+aptunnel all             # open all configured tunnels
+aptunnel status          # see what's running
+```
+
+---
+
+## Requirements
+
+- **Node.js** 18+
+- **[Aptible CLI](https://www.aptible.com/docs/cli)** installed and in your PATH
+
+---
+
+## Install
+
+```bash
+npm install -g aptunnel
+```
+
+---
+
+## Quick Start
+
+```bash
+aptunnel init
+```
+
+The wizard will:
+1. Verify aptible CLI is installed
+2. Log you in (supports 2FA)
+3. Discover all your environments and databases
+4. Auto-assign ports starting at `55550`
+5. Let you set short aliases (e.g. `dev-db`, `dev-redis`)
+6. Write `~/.aptunnel/config.yaml`
+
+---
+
+## Commands
+
+### Open a tunnel
+
+```bash
+aptunnel dev-db                    # open by alias
+aptunnel dev-db --port=5432        # override port for this session
+aptunnel dev-db --env=staging      # target a different environment
+```
+
+Output:
+```
+✔ dev-db tunnel opened
+  Port:      55554
+  Host:      localhost.aptible.in
+  User:      aptible
+  Password:  xxxxxxxxxx
+  URL:       postgresql://aptible:xxxxxxxxxx@localhost.aptible.in:55554/db
+  PID:       12345
+```
+
+### Close a tunnel
+
+```bash
+aptunnel dev-db --close
+aptunnel all --close               # close all
+aptunnel all --close --env=staging # close all in staging
+```
+
+### Open all tunnels for an environment
+
+```bash
+aptunnel all                       # uses default environment
+aptunnel all --env=staging
+```
+
+### Status
+
+```bash
+aptunnel status
+```
+
+```
+LOGIN STATUS
+  User:   you@company.com
+  Token:  valid (expires in 6d 12h)
+
+TUNNELS
+
+ENVIRONMENT  DATABASE          ALIAS      PORT   STATUS  UPTIME       PID    CONNECTION URL
+──────────── ─────────────── ─────────── ────── ─────── ──────────── ────── ──────────────────────────────────────────
+dev          ekaredb-dev      dev-db     55554  UP      02h15m30s    12345  postgresql://aptible:xxx@localhost.aptible.in:55554/db
+dev          ekaredb-redis    dev-redis  55555  DOWN    -            -      -
+```
+
+### Login
+
+```bash
+aptunnel login                     # uses saved credentials, supports 2FA
+aptunnel login --email=x@y.com --password=secret
+aptunnel login --lifetime=14d      # custom token lifetime
+aptunnel login --status            # show token info only
+```
+
+### Config
+
+```bash
+aptunnel config                    # print config (password masked)
+aptunnel config --raw              # include password
+aptunnel config --set-port dev-db 5433
+aptunnel config --set-default staging
+aptunnel config --refresh          # re-discover environments/databases
+aptunnel config --path             # print config file path
+```
+
+---
+
+## Configuration
+
+Config lives at `~/.aptunnel/config.yaml`. Password is stored separately in `~/.aptunnel/.credentials` (mode 600).
+
+```yaml
+version: 1
+
+credentials:
+  email: you@company.com
+
+defaults:
+  environment: ekare-inc-development-gfpkcova
+  lifetime: 7d
+
+environments:
+  ekare-inc-development-gfpkcova:
+    alias: dev
+    databases:
+      ekaredb-dev:
+        alias: dev-db
+        port: 55554
+        type: postgresql
+      ekaredb-dev-redis:
+        alias: dev-redis
+        port: 55555
+        type: redis
+
+tunnel_defaults:
+  start_port: 55550
+  port_increment: 1
+```
+
+---
+
+## Shell Completions
+
+### Auto-install (detects your shell)
+
+```bash
+aptunnel completions install
+```
+
+### Manual
+
+**Bash** — add to `~/.bashrc`:
+```bash
+source <(aptunnel completions bash)
+```
+
+**Zsh** — add to `~/.zshrc`:
+```bash
+source <(aptunnel completions zsh)
+```
+
+**Fish** — copy to completions directory:
+```bash
+aptunnel completions fish > ~/.config/fish/completions/aptunnel.fish
+```
+
+Completions are dynamic — they read your config at runtime so your actual database aliases appear in tab-completion.
+
+---
+
+## Platform Notes
+
+### macOS
+Full support. Install Aptible CLI via Homebrew:
+```bash
+brew install aptible/aptible/aptible
+```
+
+### Linux
+Full support. Install Aptible CLI:
+```bash
+curl -s https://toolbelt.aptible.com/install.sh | bash
+```
+
+### Windows
+Supported with some limitations:
+- Process management uses `taskkill` and `wmic` instead of Unix signals
+- Port detection uses `netstat` instead of `lsof`
+- File permissions use `icacls` for the credentials file
+- Requires Node.js 18+ for Windows
+
+### WSL (Windows Subsystem for Linux)
+Treated as Linux. Browser opening uses `wslview` if available, otherwise falls back to `cmd.exe /c start`.
+
+---
+
+## How Tunnels Work
+
+`aptible db:tunnel` is a blocking foreground process. aptunnel spawns it **detached** with `stdio` redirected to a log file (`/tmp/aptunnel-<alias>.log`), then saves the PID to `/tmp/aptunnel-<alias>.pid`.
+
+On `aptunnel status`, each PID file is checked to determine if the process is still alive.
+
+When you close a tunnel (`aptunnel dev-db --close`), aptunnel kills the process and cleans up the PID file.
+
+Pressing **Ctrl+C** while aptunnel is running closes all open tunnels before exiting.
+
+---
+
+## Troubleshooting
+
+**"Aptible CLI not found"** — Install aptible and make sure it's in your PATH. Run `aptible version` to verify.
+
+**"Token expired"** — Run `aptunnel login`. aptunnel will attempt auto-relogin on tunnel failures, but a fresh login is the cleanest fix.
+
+**"Port already in use"** — Another process is on that port. Use `--force` to kill it or `--port=<N>` to use a different port.
+
+**"Config file is corrupted"** — Delete `~/.aptunnel/config.yaml` and re-run `aptunnel init`.
+
+**Tunnel fails silently** — Check the log file: `cat /tmp/aptunnel-<alias>.log`. Set `DEBUG=1` for verbose output from aptunnel.
+
+---
+
+## Contributing
+
+1. Fork the repo
+2. Create a branch: `git checkout -b my-feature`
+3. Make your changes
+4. Open a pull request against `main`
+
+Please keep PRs focused. One feature or fix per PR.
+
+---
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/aptunnel.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+import { fileURLToPath, pathToFileURL } from 'url';
+import { dirname, resolve } from 'path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Verify minimum Node.js version
+const [major] = process.versions.node.split('.').map(Number);
+if (major < 18) {
+  process.stderr.write(
+    `aptunnel requires Node.js 18 or higher. You are running ${process.version}.\n`
+  );
+  process.exit(1);
+}
+
+// Launch the CLI router
+// Use pathToFileURL so Windows absolute paths (D:\...) are valid ESM specifiers.
+const entryUrl = pathToFileURL(resolve(__dirname, '../src/index.js')).href;
+import(entryUrl).catch((err) => {
+  process.stderr.write(`Fatal error: ${err.message}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "aptunnel",
+  "version": "1.0.0",
+  "description": "Cross-platform Aptible tunnel manager — multi-tunnel, auto-discovery, background process management",
+  "type": "module",
+  "bin": {
+    "aptunnel": "./bin/aptunnel.js"
+  },
+  "main": "./src/index.js",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "start": "node bin/aptunnel.js",
+    "test": "node --test test/lib/platform.test.js test/lib/config-manager.test.js test/lib/process-manager.test.js test/lib/aptible.test.js test/lib/completions.test.js test/commands/config.test.js test/commands/help.test.js test/commands/status.test.js",
+    "test:integration": "node --test test/integration/cli.test.js",
+    "test:all": "node --test test/lib/platform.test.js test/lib/config-manager.test.js test/lib/process-manager.test.js test/lib/aptible.test.js test/lib/completions.test.js test/commands/config.test.js test/commands/help.test.js test/commands/status.test.js test/integration/cli.test.js",
+    "test:watch": "node --test --watch test/lib/platform.test.js test/lib/config-manager.test.js test/lib/process-manager.test.js test/lib/aptible.test.js test/lib/completions.test.js test/commands/config.test.js test/commands/help.test.js test/commands/status.test.js"
+  },
+  "files": [
+    "bin/",
+    "src/"
+  ],
+  "keywords": [
+    "aptible",
+    "tunnel",
+    "database",
+    "devtools",
+    "cli"
+  ],
+  "author": "Uruba Software",
+  "license": "MIT",
+  "dependencies": {
+    "chalk": "^5.3.0",
+    "js-yaml": "^4.1.0",
+    "ora": "^8.0.1"
+  }
+}

package/src/commands/completions.js

@@ -0,0 +1,24 @@
+import { logger } from '../lib/logger.js';
+import { bashScript, zshScript, fishScript, installCompletions } from '../lib/completions.js';
+
+export async function runCompletions(args) {
+  const sub = args[0];
+
+  switch (sub) {
+    case 'bash':
+      process.stdout.write(bashScript());
+      break;
+    case 'zsh':
+      process.stdout.write(zshScript());
+      break;
+    case 'fish':
+      process.stdout.write(fishScript());
+      break;
+    case 'install':
+      installCompletions();
+      break;
+    default:
+      logger.error(`Unknown shell: "${sub ?? ''}". Use: bash, zsh, fish, install`);
+      process.exit(1);
+  }
+}

package/src/commands/config.js

@@ -0,0 +1,119 @@
+import chalk from 'chalk';
+import yaml from 'js-yaml';
+import { logger } from '../lib/logger.js';
+import {
+  exists, load, save, getConfigPath, setPort, getDefaultEnv, getAllTunnelTargets,
+} from '../lib/config-manager.js';
+import { listEnvironments, listDatabases } from '../lib/aptible.js';
+
+export async function runConfig(args) {
+  if (!exists() && !args.includes('--path')) {
+    logger.warn('No config found. Run `aptunnel init` to set up.');
+    return;
+  }
+
+  if (args.includes('--path')) {
+    console.log(getConfigPath());
+    return;
+  }
+
+  if (args.includes('--refresh')) {
+    await refreshConfig();
+    return;
+  }
+
+  const setPortArg = args.indexOf('--set-port');
+  if (setPortArg !== -1) {
+    const alias = args[setPortArg + 1];
+    const port  = parseInt(args[setPortArg + 2], 10);
+    if (!alias || isNaN(port)) {
+      logger.error('Usage: aptunnel config --set-port <alias> <port>');
+      process.exit(1);
+    }
+    setPort(alias, port);
+    logger.success(`Port for "${alias}" set to ${port}.`);
+    return;
+  }
+
+  const setDefaultArg = args.indexOf('--set-default');
+  if (setDefaultArg !== -1) {
+    const envAlias = args[setDefaultArg + 1];
+    if (!envAlias) {
+      logger.error('Usage: aptunnel config --set-default <env-alias>');
+      process.exit(1);
+    }
+    const config = load();
+    // Resolve alias or handle
+    const { getEnvironment } = await import('../lib/config-manager.js');
+    const handle = getEnvironment(envAlias) ?? envAlias;
+    config.defaults = config.defaults ?? {};
+    config.defaults.environment = handle;
+    save(config);
+    logger.success(`Default environment set to "${handle}".`);
+    return;
+  }
+
+  // Default: print config (mask password by default)
+  const showRaw = args.includes('--raw');
+  const config  = load();
+
+  // Deep-clone and mask password unless --raw
+  let display = JSON.parse(JSON.stringify(config));
+  if (!showRaw) {
+    if (display.credentials?.password) {
+      display.credentials.password = '***masked***';
+    }
+  }
+
+  const raw = yaml.dump(display, { lineWidth: 120, noRefs: true });
+  console.log('');
+  console.log(chalk.dim(`# ${getConfigPath()}`));
+  console.log(raw);
+}
+
+// ─── Refresh: re-discover environments and databases ─────────────────────────
+
+async function refreshConfig() {
+  const ora = (await import('ora')).default;
+  const config = load();
+
+  const spinner = ora('Fetching environments from Aptible…').start();
+  const envs = listEnvironments();
+  spinner.succeed(`Found ${envs.length} environment(s).`);
+
+  let added = 0;
+
+  for (const env of envs) {
+    if (!config.environments) config.environments = {};
+    if (!config.environments[env.handle]) {
+      config.environments[env.handle] = { alias: env.handle, databases: {} };
+    }
+
+    const dbSpinner = ora(`Fetching databases for ${env.handle}…`).start();
+    const dbs = listDatabases(env.handle);
+    dbSpinner.succeed(`  ${dbs.length} database(s) in ${env.handle}`);
+
+    for (const db of dbs) {
+      if (!config.environments[env.handle].databases[db.handle]) {
+        // Find next unused port
+        const usedPorts = new Set(
+          Object.values(config.environments).flatMap(e =>
+            Object.values(e.databases ?? {}).map(d => d.port)
+          ).filter(Boolean)
+        );
+        let port = config.tunnel_defaults?.start_port ?? 55550;
+        while (usedPorts.has(port)) port++;
+
+        config.environments[env.handle].databases[db.handle] = {
+          alias: db.handle,
+          port,
+          type: db.type,
+        };
+        added++;
+      }
+    }
+  }
+
+  save(config);
+  logger.success(`Config refreshed. ${added} new database(s) added.`);
+}

package/src/commands/help.js

@@ -0,0 +1,106 @@
+import chalk from 'chalk';
+import { createRequire } from 'module';
+import { fileURLToPath } from 'url';
+import { dirname, resolve } from 'path';
+import { exists, load, getDefaultEnv, getAllDatabases } from '../lib/config-manager.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const require    = createRequire(import.meta.url);
+const pkg        = require(resolve(__dirname, '../../package.json'));
+
+export function runHelp() {
+  const hasConfig = exists();
+  let config      = null;
+  let databases   = [];
+  let defaultEnv  = null;
+
+  if (hasConfig) {
+    try {
+      config     = load();
+      databases  = getAllDatabases();
+      defaultEnv = getDefaultEnv();
+    } catch {
+      // Corrupted config — show generic help
+    }
+  }
+
+  console.log('');
+  console.log(chalk.bold(`aptunnel`) + chalk.dim(` — Aptible Tunnel Manager v${pkg.version}`));
+  console.log('');
+
+  section('USAGE');
+  console.log('  aptunnel <command> [options]');
+  console.log('');
+
+  section('COMMANDS');
+  cmd('aptunnel init',                          'Setup wizard (login, discover environments & databases)');
+  cmd('aptunnel login [--status]',              'Login to Aptible or show token status');
+  cmd('aptunnel status',                        'Show all tunnel statuses and login info');
+  cmd('aptunnel config',                        'View or modify configuration');
+  cmd('aptunnel completions <bash|zsh|fish>',   'Print shell completion script');
+  cmd('aptunnel <db-alias> [--port=N]',         'Open a tunnel to a database');
+  cmd('aptunnel <db-alias> --close',            'Close a tunnel');
+  cmd('aptunnel all [--env=ALIAS]',             'Open all tunnels for an environment');
+  cmd('aptunnel all --close [--env=ALIAS]',     'Close all tunnels');
+  console.log('');
+
+  if (hasConfig && databases.length > 0) {
+    // Resolve default env alias
+    let defaultAlias = defaultEnv;
+    if (defaultEnv && config?.environments?.[defaultEnv]?.alias) {
+      defaultAlias = config.environments[defaultEnv].alias;
+    }
+
+    section(`YOUR DATABASES (default env: ${chalk.cyan(defaultAlias ?? '(none)')})`);
+
+    // Show databases for default environment first
+    const defaultDbs = databases.filter(d => d.environment === defaultEnv);
+    const otherDbs   = databases.filter(d => d.environment !== defaultEnv);
+
+    for (const db of defaultDbs) {
+      cmd(`aptunnel ${db.alias}`, `→ ${db.handle}  ${chalk.dim(`(port ${db.port})`)}`);
+    }
+
+    if (otherDbs.length > 0) {
+      console.log('');
+      section('OTHER ENVIRONMENTS');
+      for (const db of otherDbs) {
+        cmd(`aptunnel ${db.alias} --env=${db.envAlias}`, `→ ${db.handle}  ${chalk.dim(`(port ${db.port})`)}`);
+      }
+    }
+    console.log('');
+  } else {
+    console.log(chalk.dim('  (no config found — run `aptunnel init` to get started)'));
+    console.log('');
+  }
+
+  section('OPTIONS');
+  opt('--port=N',      'Override port for this session');
+  opt('--env=ALIAS',   'Target a specific environment');
+  opt('--close',       'Close tunnel(s)');
+  opt('--force',       'Kill existing process on port conflict');
+  opt('--help, -h',    'Show this help');
+  opt('--version, -v', 'Show version');
+  console.log('');
+
+  section('CONFIG SUBCOMMANDS');
+  cmd('aptunnel config',                        'Print full config (password masked)');
+  cmd('aptunnel config --raw',                  'Print full config including password');
+  cmd('aptunnel config --set-port <alias> <N>', 'Update port for a database');
+  cmd('aptunnel config --set-default <env>',    'Change default environment');
+  cmd('aptunnel config --refresh',              'Re-discover envs/dbs from Aptible');
+  cmd('aptunnel config --path',                 'Print config file path');
+  console.log('');
+}
+
+function section(title) {
+  console.log(chalk.bold(title));
+}
+
+function cmd(name, description) {
+  console.log(`  ${chalk.cyan(name.padEnd(48))} ${chalk.dim(description)}`);
+}
+
+function opt(name, description) {
+  console.log(`  ${chalk.yellow(name.padEnd(20))} ${description}`);
+}