pacificdb-cli 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hitesh Reddy K
+
+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,85 @@
+# pacificdb-cli
+
+Command-line interface for the PacificDB control plane.
+Runs anywhere Node.js ≥ 18 runs — **Linux, macOS, and Windows**.
+
+## Install
+
+**Linux / macOS**
+```bash
+npm install -g pacificdb-cli
+pacificdb login
+```
+
+**Windows (PowerShell or CMD)**
+```powershell
+npm install -g pacificdb-cli
+pacificdb login
+```
+npm creates the `pacificdb` / `pacificdb.cmd` shims automatically; no PATH edits needed.
+Config and the login token are stored per-OS at:
+
+| OS | Location |
+| --- | --- |
+| Linux | `~/.pacificdb/config.json` |
+| macOS | `/Users/<you>/.pacificdb/config.json` |
+| Windows | `C:\Users\<you>\.pacificdb\config.json` |
+
+Override with `PACIFICDB_CONFIG=<path>` or pass `--api-url` / `PACIFICDB_API_URL` per call.
+
+## Commands
+
+```bash
+pacificdb login                    # prompts for email/password; token stored in ~/.pacificdb/config.json (0600)
+pacificdb logout
+
+pacificdb org list
+pacificdb project create --name demo [--org org_id]
+pacificdb project list
+pacificdb cluster create --name c1 --project prj_id [--tier free]
+pacificdb cluster list [--project prj_id]
+pacificdb cluster status --cluster cl_id
+pacificdb database create --name appdb --cluster cl_id
+pacificdb database list --cluster cl_id
+pacificdb dbuser create --database db_id --username app
+pacificdb dbuser rotate --database db_id --dbuser dbu_id
+pacificdb connection-string generate --database db_id --dbuser dbu_id
+pacificdb backup create --cluster cl_id
+pacificdb backup list
+pacificdb restore create --backup bk_id [--cluster cl_id]
+pacificdb metrics cluster --cluster cl_id
+
+pacificdb benchmark run            # runs the local artifact-backed quick suite (repo checkout required)
+pacificdb benchmark report         # prints the public-safe benchmark report
+```
+
+## Global flags
+
+| Flag | Meaning |
+| --- | --- |
+| `--api-url URL` | Control-plane URL (or `PACIFICDB_API_URL`) |
+| `--format json\|table` | Output format (default `table`) |
+| `--no-color` | Disable ANSI colors |
+| `--org / --project / --cluster / --database` | Scope ids (defaults come from config) |
+
+## Security
+
+- The session token is stored in `~/.pacificdb/config.json` with `0600`
+  permissions; override the location with `PACIFICDB_CONFIG` or inject the
+  token via `PACIFICDB_TOKEN` (CI).
+- Secrets (tokens, passwords, connection strings) are redacted from all
+  output except the one-time display when a database user is created or
+  rotated — that is the only time the server can show the credential.
+- `--password` on the command line is supported for automation but warns,
+  since it exposes the secret to shell history; prefer the interactive prompt.
+
+## Exit codes
+
+| Code | Meaning |
+| --- | --- |
+| 0 | Success |
+| 1 | Generic failure |
+| 2 | Usage error |
+| 3 | Not authenticated |
+| 4 | Not found / permission denied |
+| 5 | Server or network error |

package/bin/pacificdb.js

@@ -0,0 +1,10 @@
+#!/usr/bin/env node
+import { run } from '../src/cli.js';
+
+run(process.argv.slice(2)).then(
+  (code) => process.exit(code ?? 0),
+  (error) => {
+    process.stderr.write(`error: ${error.message}\n`);
+    process.exit(error.exitCode ?? 1);
+  }
+);

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "pacificdb-cli",
+  "version": "0.2.0",
+  "description": "PacificDB command-line interface for the control plane (orgs, projects, clusters, databases, users, backups, metrics, benchmarks)",
+  "keywords": [
+    "pacificdb",
+    "database",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "PacificDB",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hitesh-reddy-k/database-engine-linux.git",
+    "directory": "packages/pacificdb-cli"
+  },
+  "type": "module",
+  "bin": {
+    "pacificdb": "bin/pacificdb.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/api.js

@@ -0,0 +1,48 @@
+/**
+ * Control-plane API client for the CLI. Maps failures to CliError with
+ * meaningful exit codes: 2 usage, 3 auth, 4 not found / permission, 5 server.
+ */
+
+import { resolveToken } from './config.js';
+
+export class CliError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+export async function api(apiUrl, method, path, body, { token, timeoutMs = 30000 } = {}) {
+  const auth = token ?? resolveToken();
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  let res;
+  try {
+    res = await fetch(`${apiUrl}${path}`, {
+      method,
+      signal: controller.signal,
+      headers: {
+        'content-type': 'application/json',
+        ...(auth ? { authorization: `Bearer ${auth}` } : {}),
+      },
+      body: body === undefined ? undefined : JSON.stringify(body),
+    });
+  } catch (error) {
+    clearTimeout(timer);
+    if (error.name === 'AbortError') throw new CliError(`Request timed out after ${timeoutMs}ms`, 5);
+    throw new CliError(`Cannot reach PacificDB API at ${apiUrl}: ${error.message}`, 5);
+  }
+  clearTimeout(timer);
+
+  let json = {};
+  try { json = await res.json(); } catch { /* empty body */ }
+
+  if (res.ok && json.success !== false) return json.data ?? json;
+
+  const message = typeof json.error === 'object' ? json.error?.message : json.error;
+  if (res.status === 401) throw new CliError(`Not authenticated${message ? `: ${message}` : ''}. Run \`pacificdb login\`.`, 3);
+  if (res.status === 403) throw new CliError(`Permission denied${message ? `: ${message}` : ''}`, 4);
+  if (res.status === 404) throw new CliError(`Not found${message ? `: ${message}` : ''}`, 4);
+  if (res.status === 429) throw new CliError('Rate limited by the API. Try again shortly.', 5);
+  throw new CliError(message || `API error (HTTP ${res.status})`, res.status >= 500 ? 5 : 1);
+}

package/src/cli.js

@@ -0,0 +1,330 @@
+/**
+ * pacificdb CLI - command router.
+ *
+ * Commands (see README for details):
+ *   login | logout
+ *   org list
+ *   project create|list
+ *   cluster create|list|status
+ *   database create|list
+ *   dbuser create|rotate
+ *   connection-string generate
+ *   backup create|list
+ *   restore create
+ *   metrics cluster
+ *   benchmark run|report
+ *
+ * Global flags: --api-url --org --project --cluster --database
+ *               --format json|table --no-color --quiet
+ * Exit codes: 0 ok, 1 generic, 2 usage, 3 auth, 4 not-found/denied, 5 server.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { createInterface } from 'node:readline';
+import { api, CliError } from './api.js';
+import { loadConfig, saveConfig, clearToken, resolveApiUrl, configPath } from './config.js';
+import { printResult, color } from './output.js';
+
+const USAGE = `pacificdb <command> [subcommand] [flags]
+
+Auth
+  login [--email x --password y]     Log in and store the session token
+  logout                             Revoke the session and clear the token
+
+Resources
+  org list
+  project create --name N [--org ORG_ID]
+  project list [--org ORG_ID]
+  cluster create --name N --project PRJ [--tier free]
+  cluster list [--project PRJ]
+  cluster status --cluster CL
+  database create --name N --cluster CL
+  database list --cluster CL
+  dbuser create --database DB --username U
+  dbuser rotate --database DB --dbuser DBU
+  connection-string generate --database DB --dbuser DBU
+  backup create --cluster CL [--type full]
+  backup list
+  restore create --backup BK [--cluster CL]
+  metrics cluster --cluster CL
+
+Benchmarks
+  benchmark run                      Run the local artifact-backed quick suite
+  benchmark report                   Print the public-safe benchmark report
+
+Global flags
+  --api-url URL   PacificDB control plane (or PACIFICDB_API_URL)
+  --format json|table (default table)
+  --no-color      Disable ANSI colors
+  --help          Show this help
+`;
+
+export function parseArgs(argv) {
+  const positional = [];
+  const flags = {};
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--help' || arg === '-h') flags.help = true;
+    else if (arg === '--no-color') flags.noColor = true;
+    else if (arg === '--quiet' || arg === '-q') flags.quiet = true;
+    else if (arg.startsWith('--')) {
+      const key = arg.slice(2).replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('--')) flags[key] = true;
+      else { flags[key] = next; i++; }
+    } else {
+      positional.push(arg);
+    }
+  }
+  if (flags.format && !['json', 'table'].includes(flags.format)) {
+    throw new CliError(`Invalid --format "${flags.format}" (expected json or table)`, 2);
+  }
+  return { positional, flags };
+}
+
+async function promptHidden(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr, terminal: true });
+  const muted = { muted: false };
+  rl._writeToOutput = function (s) {
+    if (muted.muted && s.trim() && !s.includes(question)) return;
+    process.stderr.write(s);
+  };
+  const answer = await new Promise((resolve) => {
+    rl.question(question, (a) => { process.stderr.write('\n'); resolve(a); });
+    muted.muted = true;
+  });
+  rl.close();
+  return answer;
+}
+
+async function prompt(question) {
+  const rl = createInterface({ input: process.stdin, output: process.stderr });
+  const answer = await new Promise((resolve) => rl.question(question, resolve));
+  rl.close();
+  return answer;
+}
+
+function requireFlag(flags, name, exitCode = 2) {
+  const value = flags[name];
+  if (!value || value === true) throw new CliError(`--${name} is required`, exitCode);
+  return value;
+}
+
+function findRepoRoot(startDir) {
+  let dir = startDir;
+  for (let i = 0; i < 8; i++) {
+    if (fs.existsSync(path.join(dir, 'benchmarks', 'reports'))) return dir;
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return null;
+}
+
+export async function run(argv, { io = process } = {}) {
+  const { positional, flags } = parseArgs(argv);
+  const [command, subcommand] = positional;
+  const format = flags.format || 'table';
+  const c = color(!flags.noColor && io.stdout.isTTY);
+  const apiUrl = resolveApiUrl(flags.apiUrl);
+  const out = (data, opts = {}) => printResult(data, { format, ...opts });
+
+  if (!command || flags.help) {
+    io.stdout.write(USAGE);
+    return command ? 0 : 2;
+  }
+
+  switch (`${command} ${subcommand || ''}`.trim()) {
+    case 'login': {
+      const email = flags.email || (await prompt('email: '));
+      const password = flags.password || (await promptHidden('password: '));
+      if (flags.password) {
+        io.stderr.write(c.yellow('warning: --password exposes the secret to shell history; prefer the prompt\n'));
+      }
+      const data = await api(apiUrl, 'POST', '/api/v1/auth/login', { email, password }, { token: '' });
+      const token = data?.session?.token;
+      if (!token) throw new CliError('Login did not return a session token', 3);
+      saveConfig({ apiUrl, token, userId: data.user?.id, email: data.user?.email });
+      const orgs = (data.organizations || []).map((o) => ({ id: o.id, name: o.name, role: o.role || '' }));
+      if (orgs.length === 1) saveConfig({ orgId: orgs[0].id });
+      io.stderr.write(c.green(`logged in as ${data.user?.email} (config: ${configPath()})\n`));
+      out({ user: { id: data.user?.id, email: data.user?.email }, organizations: orgs }, { rows: orgs, columns: ['id', 'name', 'role'] });
+      return 0;
+    }
+
+    case 'logout': {
+      try { await api(apiUrl, 'POST', '/api/v1/auth/logout'); } catch { /* already invalid is fine */ }
+      clearToken();
+      io.stderr.write('logged out\n');
+      return 0;
+    }
+
+    case 'org list': {
+      const data = await api(apiUrl, 'GET', '/api/v1/orgs');
+      const rows = (data.organizations || []).map((o) => ({ id: o.id, name: o.name, plan: o.plan, members: (o.members || []).length }));
+      out(data, { rows, columns: ['id', 'name', 'plan', 'members'] });
+      return 0;
+    }
+
+    case 'project create': {
+      const name = requireFlag(flags, 'name');
+      const organizationId = flags.org || loadConfig().orgId;
+      if (!organizationId) throw new CliError('--org is required (no default org in config)', 2);
+      const data = await api(apiUrl, 'POST', '/api/v1/projects', { name, organizationId });
+      out(data, { rows: [{ id: data.project?.id, name: data.project?.name, org: organizationId }] });
+      return 0;
+    }
+
+    case 'project list': {
+      const organizationId = flags.org || loadConfig().orgId;
+      const data = await api(apiUrl, 'GET', `/api/v1/projects${organizationId ? `?organizationId=${organizationId}` : ''}`);
+      const rows = (data.projects || []).map((p) => ({ id: p.id, name: p.name, org: p.organizationId, clusters: p.clusterCount ?? '' }));
+      out(data, { rows, columns: ['id', 'name', 'org', 'clusters'] });
+      return 0;
+    }
+
+    case 'cluster create': {
+      const name = requireFlag(flags, 'name');
+      const projectId = flags.project || loadConfig().projectId;
+      if (!projectId) throw new CliError('--project is required', 2);
+      const data = await api(apiUrl, 'POST', '/api/v1/clusters', { name, projectId, tier: flags.tier || 'free', region: flags.region });
+      out(data, { rows: [{ id: data.cluster?.id, name: data.cluster?.name, tier: data.cluster?.tier, status: data.cluster?.status }] });
+      return 0;
+    }
+
+    case 'cluster list': {
+      const projectId = flags.project || '';
+      const data = await api(apiUrl, 'GET', `/api/v1/clusters${projectId ? `?projectId=${projectId}` : ''}`);
+      const rows = (data.clusters || []).map((cl) => ({ id: cl.id, name: cl.name, tier: cl.tier, region: cl.region, status: cl.status }));
+      out(data, { rows, columns: ['id', 'name', 'tier', 'region', 'status'] });
+      return 0;
+    }
+
+    case 'cluster status': {
+      const clusterId = requireFlag(flags, 'cluster');
+      const data = await api(apiUrl, 'GET', `/api/v1/clusters/${clusterId}`);
+      const cl = data.cluster || {};
+      out(data, {
+        rows: [{ id: cl.id, name: cl.name, status: cl.status, tier: cl.tier, nodes: (data.nodes || []).length, alerts: (data.alerts || []).length }],
+      });
+      return 0;
+    }
+
+    case 'database create': {
+      const name = requireFlag(flags, 'name');
+      const clusterId = requireFlag(flags, 'cluster');
+      const data = await api(apiUrl, 'POST', `/api/v1/clusters/${clusterId}/databases`, { name });
+      out(data, { rows: [{ id: data.database?.id, name: data.database?.name, engineProvisioned: data.engineProvisioned }] });
+      return 0;
+    }
+
+    case 'database list': {
+      const clusterId = requireFlag(flags, 'cluster');
+      const data = await api(apiUrl, 'GET', `/api/v1/clusters/${clusterId}/databases`);
+      const rows = (data.databases || []).map((d) => ({ id: d.id, name: d.name, status: d.status }));
+      out(data, { rows, columns: ['id', 'name', 'status'] });
+      return 0;
+    }
+
+    case 'dbuser create': {
+      const databaseId = requireFlag(flags, 'database');
+      const username = requireFlag(flags, 'username');
+      const data = await api(apiUrl, 'POST', `/api/v1/databases/${databaseId}/users`, {
+        username,
+        roles: flags.roles ? String(flags.roles).split(',') : undefined,
+        ipAllowlist: flags.ipAllowlist ? String(flags.ipAllowlist).split(',') : undefined,
+      });
+      io.stderr.write(c.yellow(`\n${data.warning || 'Store the connection string now; it is shown only once.'}\n\n`));
+      out(data, {
+        rows: [{ id: data.user?.id, username: data.user?.username, connectionString: data.connectionString }],
+        columns: ['id', 'username', 'connectionString'],
+        showSecrets: new Set(['connectionString']),
+      });
+      return 0;
+    }
+
+    case 'dbuser rotate': {
+      const databaseId = requireFlag(flags, 'database');
+      const dbUserId = requireFlag(flags, 'dbuser');
+      const data = await api(apiUrl, 'POST', `/api/v1/databases/${databaseId}/users/${dbUserId}/rotate-password`, {});
+      io.stderr.write(c.yellow(`\n${data.warning || 'New connection string shown once; old credentials are revoked.'}\n\n`));
+      out(data, {
+        rows: [{ id: data.user?.id, revokedSessions: data.revokedSessions, connectionString: data.connectionString }],
+        columns: ['id', 'revokedSessions', 'connectionString'],
+        showSecrets: new Set(['connectionString']),
+      });
+      return 0;
+    }
+
+    case 'connection-string generate': {
+      const databaseId = requireFlag(flags, 'database');
+      const dbUserId = requireFlag(flags, 'dbuser');
+      const data = await api(apiUrl, 'POST', `/api/v1/databases/${databaseId}/connection-string`, { dbUserId });
+      io.stderr.write(c.yellow(`\n${data.warning || 'Connection string shown once (credentials were rotated).'}\n\n`));
+      out(data, {
+        rows: [{ dbUserId, connectionString: data.connectionString }],
+        columns: ['dbUserId', 'connectionString'],
+        showSecrets: new Set(['connectionString']),
+      });
+      return 0;
+    }
+
+    case 'backup create': {
+      const clusterId = flags.cluster || loadConfig().clusterId;
+      if (!clusterId) throw new CliError('--cluster is required', 2);
+      const data = await api(apiUrl, 'POST', '/api/v1/backups', { clusterId, type: flags.type || 'manual' });
+      out(data, { rows: [{ id: data.backup?.id, status: data.backup?.status, type: data.backup?.type }] });
+      return 0;
+    }
+
+    case 'backup list': {
+      const data = await api(apiUrl, 'GET', '/api/v1/backups');
+      const rows = (data.backups || []).map((b) => ({ id: b.id, cluster: b.clusterId, type: b.type, status: b.status, createdAt: b.createdAt }));
+      out(data, { rows, columns: ['id', 'cluster', 'type', 'status', 'createdAt'] });
+      return 0;
+    }
+
+    case 'restore create': {
+      const backupId = requireFlag(flags, 'backup');
+      const data = await api(apiUrl, 'POST', `/api/v1/backups/${backupId}/restore`, {
+        targetClusterId: flags.cluster || undefined,
+      });
+      out(data, { rows: [{ backup: backupId, target: data.targetCluster, message: data.message || 'restore initiated' }] });
+      return 0;
+    }
+
+    case 'metrics cluster': {
+      const clusterId = requireFlag(flags, 'cluster');
+      const data = await api(apiUrl, 'GET', `/api/v1/metrics/cluster/${clusterId}`);
+      out(data, { rows: Array.isArray(data) ? data : [data] });
+      return 0;
+    }
+
+    case 'benchmark run': {
+      const root = findRepoRoot(io.cwd ? io.cwd() : process.cwd());
+      if (!root) {
+        throw new CliError('benchmark run must be executed inside a PacificDB repository (benchmarks/ not found). Benchmarks execute locally against your own hardware; results are artifact-backed and claim-safe.', 2);
+      }
+      const { spawnSync } = await import('node:child_process');
+      io.stderr.write('running: npm run benchmark:quick (system + storage + security tools + report)\n');
+      // shell:true resolves npm to npm.cmd on Windows; args are fixed strings (no injection surface).
+      const res = spawnSync('npm', ['run', 'benchmark:quick'], { cwd: root, stdio: 'inherit', shell: process.platform === 'win32' });
+      return res.status ?? 1;
+    }
+
+    case 'benchmark report': {
+      const root = findRepoRoot(io.cwd ? io.cwd() : process.cwd());
+      const reportPath = root && path.join(root, 'benchmarks', 'reports', 'final', 'PACIFICDB_PUBLIC_RESULTS.md');
+      if (!reportPath || !fs.existsSync(reportPath)) {
+        throw new CliError('No public benchmark report found (benchmarks/reports/final/PACIFICDB_PUBLIC_RESULTS.md). Run `pacificdb benchmark run` first.', 4);
+      }
+      io.stdout.write(fs.readFileSync(reportPath, 'utf8'));
+      return 0;
+    }
+
+    default:
+      io.stderr.write(USAGE);
+      throw new CliError(`Unknown command: ${positional.join(' ') || '(none)'}`, 2);
+  }
+}

package/src/config.js

@@ -0,0 +1,50 @@
+/**
+ * CLI configuration: ~/.pacificdb/config.json (created 0600).
+ * Stores the API URL, session token, and default org/project/cluster ids.
+ * The token can be overridden with PACIFICDB_TOKEN, the config path with
+ * PACIFICDB_CONFIG, and the API URL with PACIFICDB_API_URL.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+export function configPath() {
+  return process.env.PACIFICDB_CONFIG || path.join(os.homedir(), '.pacificdb', 'config.json');
+}
+
+export function loadConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(configPath(), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+export function saveConfig(update) {
+  const file = configPath();
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const merged = { ...loadConfig(), ...update };
+  fs.writeFileSync(file, JSON.stringify(merged, null, 2) + '\n', { mode: 0o600 });
+  try { fs.chmodSync(file, 0o600); } catch { /* best effort on non-POSIX */ }
+  return merged;
+}
+
+export function clearToken() {
+  const cfg = loadConfig();
+  delete cfg.token;
+  delete cfg.userId;
+  const file = configPath();
+  fs.mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n', { mode: 0o600 });
+  return cfg;
+}
+
+export function resolveToken() {
+  return process.env.PACIFICDB_TOKEN || loadConfig().token || '';
+}
+
+export function resolveApiUrl(flagValue) {
+  return (flagValue || process.env.PACIFICDB_API_URL || loadConfig().apiUrl || 'http://localhost:3000').replace(/\/+$/, '');
+}

package/src/output.js

@@ -0,0 +1,48 @@
+/**
+ * Output helpers: JSON or aligned tables, optional color, secret redaction.
+ */
+
+const SECRET_KEYS = new Set(['password', 'token', 'secret', 'key', 'sessiontoken', 'connectionstring', 'passwordhash']);
+
+export function redact(value, { except = new Set() } = {}) {
+  if (!value || typeof value !== 'object') return value;
+  if (Array.isArray(value)) return value.map((v) => redact(v, { except }));
+  const out = {};
+  for (const [k, v] of Object.entries(value)) {
+    if (SECRET_KEYS.has(k.toLowerCase()) && !except.has(k)) {
+      out[k] = 'REDACTED';
+    } else {
+      out[k] = redact(v, { except });
+    }
+  }
+  return out;
+}
+
+export function color(enabled) {
+  const wrap = (code) => (s) => (enabled ? `[${code}m${s}` : String(s));
+  return { bold: wrap('1'), green: wrap('32'), red: wrap('31'), yellow: wrap('33'), dim: wrap('2') };
+}
+
+export function table(rows, columns) {
+  if (!rows.length) return '(no results)';
+  const cols = columns || Object.keys(rows[0]);
+  const cells = rows.map((r) => cols.map((c) => formatCell(r[c])));
+  const widths = cols.map((c, i) => Math.max(c.length, ...cells.map((row) => row[i].length)));
+  const line = (parts) => parts.map((p, i) => p.padEnd(widths[i])).join('  ');
+  return [line(cols.map((c) => c.toUpperCase())), line(widths.map((w) => '-'.repeat(w))), ...cells.map(line)].join('\n');
+}
+
+function formatCell(v) {
+  if (v === null || v === undefined) return '';
+  if (typeof v === 'object') return JSON.stringify(v);
+  return String(v);
+}
+
+export function printResult(data, { format, rows, columns, showSecrets = new Set() }) {
+  if (format === 'json') {
+    process.stdout.write(JSON.stringify(redact(data, { except: showSecrets }), null, 2) + '\n');
+  } else {
+    const safeRows = redact(rows ?? data, { except: showSecrets });
+    process.stdout.write(table(Array.isArray(safeRows) ? safeRows : [safeRows], columns) + '\n');
+  }
+}