pgpm 5.2.3 → 5.3.0

package/commands/docker.js

@@ -2,6 +2,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const child_process_1 = require("child_process");
 const inquirerer_1 = require("inquirerer");
+const doctor_1 = require("../utils/doctor");
 const dockerUsageText = `
 Docker Command:
 
@@ -52,25 +53,25 @@ const ADDITIONAL_SERVICES = {
         image: 'minio/minio',
         ports: [
             { host: 9000, container: 9000 },
-            { host: 9001, container: 9001 },
+            { host: 9001, container: 9001 }
         ],
         env: {
             MINIO_ROOT_USER: 'minioadmin',
-            MINIO_ROOT_PASSWORD: 'minioadmin',
+            MINIO_ROOT_PASSWORD: 'minioadmin'
         },
         command: ['server', '/data', '--console-address', ':9001'],
-        volumes: [{ name: 'minio-data', containerPath: '/data' }],
+        volumes: [{ name: 'minio-data', containerPath: '/data' }]
     },
     ollama: {
         name: 'ollama',
         image: 'ollama/ollama',
         ports: [
-            { host: 11434, container: 11434 },
+            { host: 11434, container: 11434 }
         ],
         env: {},
         volumes: [{ name: 'ollama-data', containerPath: '/root/.ollama' }],
-        gpuCapable: true,
-    },
+        gpuCapable: true
+    }
 };
 function run(command, args, options = {}) {
     return new Promise((resolve, reject) => {
@@ -98,14 +99,19 @@ function run(command, args, options = {}) {
         });
     });
 }
-async function checkDockerAvailable() {
-    try {
-        const result = await run('docker', ['--version']);
-        return result.code === 0;
+async function ensureDockerReady() {
+    const status = await (0, doctor_1.getDockerStatus)();
+    if (status.binary && status.daemon) {
+        return true;
     }
-    catch (error) {
-        return false;
+    const platformInfo = (0, doctor_1.detectPlatform)();
+    if (!status.binary) {
+        await (0, inquirerer_1.cliExitWithError)(`Docker is not installed or not available in PATH.\n${(0, doctor_1.dockerInstallGuidance)(platformInfo)}`);
+    }
+    else {
+        await (0, inquirerer_1.cliExitWithError)((0, doctor_1.dockerDaemonGuidance)(platformInfo));
     }
+    return false;
 }
 async function isContainerRunning(name) {
     try {
@@ -130,9 +136,7 @@ async function containerExists(name) {
 }
 async function startContainer(options) {
     const { name, image, port, user, password, shmSize, recreate } = options;
-    const dockerAvailable = await checkDockerAvailable();
-    if (!dockerAvailable) {
-        await (0, inquirerer_1.cliExitWithError)('Docker is not installed or not available in PATH. Please install Docker first.');
+    if (!(await ensureDockerReady())) {
         return;
     }
     const exists = await containerExists(name);
@@ -183,9 +187,7 @@ async function startContainer(options) {
     }
 }
 async function stopContainer(name) {
-    const dockerAvailable = await checkDockerAvailable();
-    if (!dockerAvailable) {
-        await (0, inquirerer_1.cliExitWithError)('Docker is not installed or not available in PATH. Please install Docker first.');
+    if (!(await ensureDockerReady())) {
         return;
     }
     const exists = await containerExists(name);
@@ -238,7 +240,7 @@ async function startService(service, recreate, gpu = false) {
     const runArgs = [
         'run',
         '-d',
-        '--name', name,
+        '--name', name
     ];
     for (const [key, value] of Object.entries(serviceEnv)) {
         runArgs.push('-e', `${key}=${value}`);
@@ -282,7 +284,8 @@ function resolveServiceFlags(args) {
     return services;
 }
 async function listServices() {
-    const dockerAvailable = await checkDockerAvailable();
+    const dockerStatus = await (0, doctor_1.getDockerStatus)();
+    const dockerAvailable = dockerStatus.binary && dockerStatus.daemon;
     console.log('\nAvailable services:\n');
     console.log('  Primary:');
     if (dockerAvailable) {

package/commands/doctor.d.ts

@@ -0,0 +1,3 @@
+import { CLIOptions, Inquirerer } from 'inquirerer';
+declare const _default: (argv: Partial<Record<string, any>>, _prompter: Inquirerer, _options: CLIOptions) => Promise<void>;
+export default _default;

package/commands/doctor.js

@@ -0,0 +1,104 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const child_process_1 = require("child_process");
+const pg_env_1 = require("pg-env");
+const doctor_1 = require("../utils/doctor");
+const doctorUsageText = `
+Doctor Command:
+
+  pgpm doctor [OPTIONS]
+
+  Check that your machine has the dependencies pgpm needs
+  (Node.js, Docker, psql) and report OS-specific installation
+  guidance for anything that is missing.
+
+Options:
+  --db               Also check PostgreSQL connectivity using the current environment
+  --json             Output results as JSON
+  --help, -h         Show this help message
+
+Exit Codes:
+  0                  All checks passed (warnings allowed)
+  1                  One or more checks failed
+
+Examples:
+  pgpm doctor                Check node, docker, docker compose, and psql
+  pgpm doctor --db           Also verify a PostgreSQL connection
+  pgpm doctor --json         Machine-readable output (for CI)
+`;
+const STATUS_ICONS = {
+    pass: '✅',
+    warn: '⚠️ ',
+    fail: '❌'
+};
+async function checkDatabaseConnectivity() {
+    const pg = (0, pg_env_1.getPgEnvOptions)();
+    const target = `${pg.host}:${pg.port}/${pg.database} (user: ${pg.user})`;
+    const result = await new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)('psql', ['-X', '-A', '-t', '-c', 'SELECT 1'], {
+            stdio: 'pipe',
+            env: (0, pg_env_1.getSpawnEnvWithPg)(pg)
+        });
+        let stderr = '';
+        child.stderr?.on('data', (d) => { stderr += d.toString(); });
+        child.on('error', () => resolve({ code: 127, stderr: 'psql: command not found' }));
+        child.on('close', (code) => resolve({ code: code ?? 0, stderr: stderr.trim() }));
+    });
+    if (result.code === 0) {
+        return {
+            name: 'database',
+            status: 'pass',
+            message: `connected to PostgreSQL at ${target}`
+        };
+    }
+    return {
+        name: 'database',
+        status: 'fail',
+        message: `could not connect to PostgreSQL at ${target}: ${result.stderr}`,
+        remediation: 'Start a local PostgreSQL with `pgpm docker start`, or point PGHOST/PGPORT/PGUSER/PGPASSWORD at a running server (see `pgpm env`).'
+    };
+}
+function printResults(results) {
+    console.log('');
+    for (const result of results) {
+        console.log(`  ${STATUS_ICONS[result.status]} ${result.name.padEnd(16)} ${result.message}`);
+        if (result.remediation && result.status !== 'pass') {
+            console.log(`     ↳ ${result.remediation}`);
+        }
+    }
+    const { failed, warned, passed } = (0, doctor_1.summarizeChecks)(results);
+    console.log('');
+    console.log(`  ${passed} passed, ${warned} warning(s), ${failed} failed`);
+    console.log('');
+}
+exports.default = async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(doctorUsageText);
+        process.exit(0);
+    }
+    const platformInfo = (0, doctor_1.detectPlatform)();
+    const results = [
+        (0, doctor_1.checkNode)(),
+        await (0, doctor_1.checkDocker)(platformInfo, doctor_1.runCommand),
+        await (0, doctor_1.checkDockerCompose)(platformInfo, doctor_1.runCommand),
+        await (0, doctor_1.checkPsql)(platformInfo, doctor_1.runCommand)
+    ];
+    if (argv.db === true) {
+        results.push(await checkDatabaseConnectivity());
+    }
+    if (argv.json === true) {
+        const { failed, warned, passed } = (0, doctor_1.summarizeChecks)(results);
+        console.log(JSON.stringify({
+            platform: platformInfo,
+            checks: results,
+            summary: { passed, warned, failed }
+        }, null, 2));
+    }
+    else {
+        printResults(results);
+    }
+    const { failed } = (0, doctor_1.summarizeChecks)(results);
+    if (failed > 0) {
+        process.exit(1);
+    }
+};

package/commands.js

@@ -14,6 +14,7 @@ const cache_1 = __importDefault(require("./commands/cache"));
 const clear_1 = __importDefault(require("./commands/clear"));
 const deploy_1 = __importDefault(require("./commands/deploy"));
 const docker_1 = __importDefault(require("./commands/docker"));
+const doctor_1 = __importDefault(require("./commands/doctor"));
 const dump_1 = __importDefault(require("./commands/dump"));
 const env_1 = __importDefault(require("./commands/env"));
 const export_1 = __importDefault(require("./commands/export"));
@@ -24,8 +25,6 @@ const kill_1 = __importDefault(require("./commands/kill"));
 const migrate_1 = __importDefault(require("./commands/migrate"));
 const package_1 = __importDefault(require("./commands/package"));
 const plan_1 = __importDefault(require("./commands/plan"));
-const update_1 = __importDefault(require("./commands/update"));
-const upgrade_1 = __importDefault(require("./commands/upgrade"));
 const remove_1 = __importDefault(require("./commands/remove"));
 const rename_1 = __importDefault(require("./commands/rename"));
 const revert_1 = __importDefault(require("./commands/revert"));
@@ -33,6 +32,8 @@ const slice_1 = __importDefault(require("./commands/slice"));
 const tag_1 = __importDefault(require("./commands/tag"));
 const test_packages_1 = __importDefault(require("./commands/test-packages"));
 const tune_1 = __importDefault(require("./commands/tune"));
+const update_1 = __importDefault(require("./commands/update"));
+const upgrade_1 = __importDefault(require("./commands/upgrade"));
 const verify_1 = __importDefault(require("./commands/verify"));
 const utils_2 = require("./utils");
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
@@ -53,6 +54,7 @@ const createPgpmCommandMap = (skipPgTeardown = false) => {
         clear: pgt(clear_1.default),
         deploy: pgt(deploy_1.default),
         docker: docker_1.default,
+        doctor: doctor_1.default,
         dump: pgt(dump_1.default),
         env: env_1.default,
         verify: pgt(verify_1.default),
@@ -114,7 +116,7 @@ const commands = async (argv, prompter, options) => {
             const updateResult = await (0, utils_1.checkForUpdates)({
                 pkgName: pkg.name,
                 pkgVersion: pkg.version,
-                toolName: 'pgpm',
+                toolName: 'pgpm'
             });
             if (updateResult.hasUpdate && updateResult.message) {
                 console.warn(updateResult.message);

package/esm/commands/docker.js

@@ -1,5 +1,6 @@
 import { spawn } from 'child_process';
 import { cliExitWithError, extractFirst } from 'inquirerer';
+import { detectPlatform, dockerDaemonGuidance, dockerInstallGuidance, getDockerStatus } from '../utils/doctor';
 const dockerUsageText = `
 Docker Command:
 
@@ -50,25 +51,25 @@ const ADDITIONAL_SERVICES = {
         image: 'minio/minio',
         ports: [
             { host: 9000, container: 9000 },
-            { host: 9001, container: 9001 },
+            { host: 9001, container: 9001 }
         ],
         env: {
             MINIO_ROOT_USER: 'minioadmin',
-            MINIO_ROOT_PASSWORD: 'minioadmin',
+            MINIO_ROOT_PASSWORD: 'minioadmin'
         },
         command: ['server', '/data', '--console-address', ':9001'],
-        volumes: [{ name: 'minio-data', containerPath: '/data' }],
+        volumes: [{ name: 'minio-data', containerPath: '/data' }]
     },
     ollama: {
         name: 'ollama',
         image: 'ollama/ollama',
         ports: [
-            { host: 11434, container: 11434 },
+            { host: 11434, container: 11434 }
         ],
         env: {},
         volumes: [{ name: 'ollama-data', containerPath: '/root/.ollama' }],
-        gpuCapable: true,
-    },
+        gpuCapable: true
+    }
 };
 function run(command, args, options = {}) {
     return new Promise((resolve, reject) => {
@@ -96,14 +97,19 @@ function run(command, args, options = {}) {
         });
     });
 }
-async function checkDockerAvailable() {
-    try {
-        const result = await run('docker', ['--version']);
-        return result.code === 0;
+async function ensureDockerReady() {
+    const status = await getDockerStatus();
+    if (status.binary && status.daemon) {
+        return true;
     }
-    catch (error) {
-        return false;
+    const platformInfo = detectPlatform();
+    if (!status.binary) {
+        await cliExitWithError(`Docker is not installed or not available in PATH.\n${dockerInstallGuidance(platformInfo)}`);
+    }
+    else {
+        await cliExitWithError(dockerDaemonGuidance(platformInfo));
     }
+    return false;
 }
 async function isContainerRunning(name) {
     try {
@@ -128,9 +134,7 @@ async function containerExists(name) {
 }
 async function startContainer(options) {
     const { name, image, port, user, password, shmSize, recreate } = options;
-    const dockerAvailable = await checkDockerAvailable();
-    if (!dockerAvailable) {
-        await cliExitWithError('Docker is not installed or not available in PATH. Please install Docker first.');
+    if (!(await ensureDockerReady())) {
         return;
     }
     const exists = await containerExists(name);
@@ -181,9 +185,7 @@ async function startContainer(options) {
     }
 }
 async function stopContainer(name) {
-    const dockerAvailable = await checkDockerAvailable();
-    if (!dockerAvailable) {
-        await cliExitWithError('Docker is not installed or not available in PATH. Please install Docker first.');
+    if (!(await ensureDockerReady())) {
         return;
     }
     const exists = await containerExists(name);
@@ -236,7 +238,7 @@ async function startService(service, recreate, gpu = false) {
     const runArgs = [
         'run',
         '-d',
-        '--name', name,
+        '--name', name
     ];
     for (const [key, value] of Object.entries(serviceEnv)) {
         runArgs.push('-e', `${key}=${value}`);
@@ -280,7 +282,8 @@ function resolveServiceFlags(args) {
     return services;
 }
 async function listServices() {
-    const dockerAvailable = await checkDockerAvailable();
+    const dockerStatus = await getDockerStatus();
+    const dockerAvailable = dockerStatus.binary && dockerStatus.daemon;
     console.log('\nAvailable services:\n');
     console.log('  Primary:');
     if (dockerAvailable) {

package/esm/commands/doctor.js

@@ -0,0 +1,102 @@
+import { spawn } from 'child_process';
+import { getPgEnvOptions, getSpawnEnvWithPg } from 'pg-env';
+import { checkDocker, checkDockerCompose, checkNode, checkPsql, detectPlatform, runCommand, summarizeChecks } from '../utils/doctor';
+const doctorUsageText = `
+Doctor Command:
+
+  pgpm doctor [OPTIONS]
+
+  Check that your machine has the dependencies pgpm needs
+  (Node.js, Docker, psql) and report OS-specific installation
+  guidance for anything that is missing.
+
+Options:
+  --db               Also check PostgreSQL connectivity using the current environment
+  --json             Output results as JSON
+  --help, -h         Show this help message
+
+Exit Codes:
+  0                  All checks passed (warnings allowed)
+  1                  One or more checks failed
+
+Examples:
+  pgpm doctor                Check node, docker, docker compose, and psql
+  pgpm doctor --db           Also verify a PostgreSQL connection
+  pgpm doctor --json         Machine-readable output (for CI)
+`;
+const STATUS_ICONS = {
+    pass: '✅',
+    warn: '⚠️ ',
+    fail: '❌'
+};
+async function checkDatabaseConnectivity() {
+    const pg = getPgEnvOptions();
+    const target = `${pg.host}:${pg.port}/${pg.database} (user: ${pg.user})`;
+    const result = await new Promise((resolve) => {
+        const child = spawn('psql', ['-X', '-A', '-t', '-c', 'SELECT 1'], {
+            stdio: 'pipe',
+            env: getSpawnEnvWithPg(pg)
+        });
+        let stderr = '';
+        child.stderr?.on('data', (d) => { stderr += d.toString(); });
+        child.on('error', () => resolve({ code: 127, stderr: 'psql: command not found' }));
+        child.on('close', (code) => resolve({ code: code ?? 0, stderr: stderr.trim() }));
+    });
+    if (result.code === 0) {
+        return {
+            name: 'database',
+            status: 'pass',
+            message: `connected to PostgreSQL at ${target}`
+        };
+    }
+    return {
+        name: 'database',
+        status: 'fail',
+        message: `could not connect to PostgreSQL at ${target}: ${result.stderr}`,
+        remediation: 'Start a local PostgreSQL with `pgpm docker start`, or point PGHOST/PGPORT/PGUSER/PGPASSWORD at a running server (see `pgpm env`).'
+    };
+}
+function printResults(results) {
+    console.log('');
+    for (const result of results) {
+        console.log(`  ${STATUS_ICONS[result.status]} ${result.name.padEnd(16)} ${result.message}`);
+        if (result.remediation && result.status !== 'pass') {
+            console.log(`     ↳ ${result.remediation}`);
+        }
+    }
+    const { failed, warned, passed } = summarizeChecks(results);
+    console.log('');
+    console.log(`  ${passed} passed, ${warned} warning(s), ${failed} failed`);
+    console.log('');
+}
+export default async (argv, _prompter, _options) => {
+    if (argv.help || argv.h) {
+        console.log(doctorUsageText);
+        process.exit(0);
+    }
+    const platformInfo = detectPlatform();
+    const results = [
+        checkNode(),
+        await checkDocker(platformInfo, runCommand),
+        await checkDockerCompose(platformInfo, runCommand),
+        await checkPsql(platformInfo, runCommand)
+    ];
+    if (argv.db === true) {
+        results.push(await checkDatabaseConnectivity());
+    }
+    if (argv.json === true) {
+        const { failed, warned, passed } = summarizeChecks(results);
+        console.log(JSON.stringify({
+            platform: platformInfo,
+            checks: results,
+            summary: { passed, warned, failed }
+        }, null, 2));
+    }
+    else {
+        printResults(results);
+    }
+    const { failed } = summarizeChecks(results);
+    if (failed > 0) {
+        process.exit(1);
+    }
+};

package/esm/commands.js

@@ -8,6 +8,7 @@ import cache from './commands/cache';
 import clear from './commands/clear';
 import deploy from './commands/deploy';
 import docker from './commands/docker';
+import doctor from './commands/doctor';
 import dump from './commands/dump';
 import env from './commands/env';
 import _export from './commands/export';
@@ -18,8 +19,6 @@ import kill from './commands/kill';
 import migrate from './commands/migrate';
 import _package from './commands/package';
 import plan from './commands/plan';
-import updateCmd from './commands/update';
-import upgrade from './commands/upgrade';
 import remove from './commands/remove';
 import renameCmd from './commands/rename';
 import revert from './commands/revert';
@@ -27,6 +26,8 @@ import slice from './commands/slice';
 import tag from './commands/tag';
 import testPackages from './commands/test-packages';
 import tune from './commands/tune';
+import updateCmd from './commands/update';
+import upgrade from './commands/upgrade';
 import verify from './commands/verify';
 import { usageText } from './utils';
 const withPgTeardown = (fn, skipTeardown = false) => async (...args) => {
@@ -47,6 +48,7 @@ export const createPgpmCommandMap = (skipPgTeardown = false) => {
         clear: pgt(clear),
         deploy: pgt(deploy),
         docker,
+        doctor,
         dump: pgt(dump),
         env,
         verify: pgt(verify),
@@ -107,7 +109,7 @@ export const commands = async (argv, prompter, options) => {
             const updateResult = await checkForUpdates({
                 pkgName: pkg.name,
                 pkgVersion: pkg.version,
-                toolName: 'pgpm',
+                toolName: 'pgpm'
             });
             if (updateResult.hasUpdate && updateResult.message) {
                 console.warn(updateResult.message);

package/esm/utils/display.js

@@ -41,6 +41,7 @@ export const usageText = `
   
   Development Tools:
     docker             Manage Docker containers (start/stop/ls, --minio)
+    doctor             Check local dependencies (node, docker, psql) with install guidance
     env                Manage environment variables (--supabase, --minio)
     test-packages      Run integration tests on workspace packages
   

package/esm/utils/doctor.js

@@ -0,0 +1,248 @@
+import { spawn } from 'child_process';
+import { readFileSync } from 'fs';
+export const runCommand = (command, args) => {
+    return new Promise((resolve) => {
+        const child = spawn(command, args, { stdio: 'pipe' });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('error', () => {
+            resolve({ code: 127, stdout: '', stderr: `${command}: command not found` });
+        });
+        child.on('close', (code) => {
+            resolve({ code: code ?? 0, stdout: stdout.trim(), stderr: stderr.trim() });
+        });
+    });
+};
+export function detectPlatform(platform = process.platform, readFile = (p) => readFileSync(p, 'utf-8')) {
+    if (platform === 'darwin') {
+        return { platform: 'macos' };
+    }
+    if (platform === 'win32') {
+        return { platform: 'windows' };
+    }
+    if (platform === 'linux') {
+        let distro;
+        try {
+            const release = readFile('/etc/os-release');
+            const match = release.match(/^ID=("?)([^"\n]*)\1$/m);
+            if (match) {
+                distro = match[2];
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            const version = readFile('/proc/version');
+            if (/microsoft/i.test(version)) {
+                return { platform: 'wsl', distro };
+            }
+        }
+        catch {
+            // ignore
+        }
+        return { platform: 'linux', distro };
+    }
+    return { platform: 'unknown' };
+}
+const DEBIAN_LIKE = ['ubuntu', 'debian', 'pop', 'linuxmint', 'elementary'];
+const RHEL_LIKE = ['fedora', 'rhel', 'centos', 'rocky', 'almalinux', 'amzn'];
+function isDebianLike(distro) {
+    return !!distro && DEBIAN_LIKE.includes(distro);
+}
+function isRhelLike(distro) {
+    return !!distro && RHEL_LIKE.includes(distro);
+}
+export function dockerInstallGuidance(info) {
+    switch (info.platform) {
+        case 'macos':
+            return 'Install Docker Desktop for Mac: https://www.docker.com/products/docker-desktop/ (or `brew install --cask docker`)';
+        case 'windows':
+            return 'Install Docker Desktop for Windows: https://www.docker.com/products/docker-desktop/';
+        case 'wsl':
+            return 'Install Docker Desktop for Windows with the WSL 2 backend enabled: https://docs.docker.com/desktop/wsl/';
+        case 'linux':
+            if (isDebianLike(info.distro)) {
+                return 'Install Docker Engine: https://docs.docker.com/engine/install/ubuntu/ (e.g. `sudo apt-get install docker.io` or the official docker-ce packages)';
+            }
+            if (isRhelLike(info.distro)) {
+                return 'Install Docker Engine: https://docs.docker.com/engine/install/fedora/ (e.g. `sudo dnf install docker-ce`)';
+            }
+            return 'Install Docker Engine for your distribution: https://docs.docker.com/engine/install/';
+        default:
+            return 'Install Docker: https://docs.docker.com/get-docker/';
+    }
+}
+export function dockerDaemonGuidance(info) {
+    switch (info.platform) {
+        case 'macos':
+        case 'windows':
+            return 'Docker is installed but the daemon is not running. Open the Docker Desktop application and wait for it to finish starting.';
+        case 'wsl':
+            return 'Docker is installed but the daemon is not reachable. Start Docker Desktop on Windows and make sure WSL integration is enabled for this distro.';
+        case 'linux':
+            return 'Docker is installed but the daemon is not running. Start it with `sudo systemctl start docker` (and `sudo systemctl enable docker` to start on boot). If you get a permission error, add your user to the docker group: `sudo usermod -aG docker $USER` and re-login.';
+        default:
+            return 'Docker is installed but the daemon is not reachable. Start the Docker daemon and try again.';
+    }
+}
+export function psqlInstallGuidance(info) {
+    switch (info.platform) {
+        case 'macos':
+            return 'Install the PostgreSQL client via Homebrew: `brew install libpq && brew link --force libpq`';
+        case 'windows':
+            return 'Install the PostgreSQL client tools: `winget install PostgreSQL.PostgreSQL` or download from https://www.postgresql.org/download/windows/';
+        case 'wsl':
+        case 'linux':
+            if (isRhelLike(info.distro)) {
+                return 'Install the PostgreSQL client: `sudo dnf install postgresql`';
+            }
+            return 'Install the PostgreSQL client: `sudo apt-get install postgresql-client`';
+        default:
+            return 'Install the PostgreSQL client tools (psql): https://www.postgresql.org/download/';
+    }
+}
+export async function checkDockerBinary(exec = runCommand) {
+    const result = await exec('docker', ['--version']);
+    return result.code === 0;
+}
+export async function checkDockerDaemon(exec = runCommand) {
+    const result = await exec('docker', ['info']);
+    return result.code === 0;
+}
+export async function getDockerStatus(exec = runCommand) {
+    const binary = await checkDockerBinary(exec);
+    if (!binary) {
+        return { binary: false, daemon: false };
+    }
+    const daemon = await checkDockerDaemon(exec);
+    return { binary, daemon };
+}
+export async function checkDocker(info, exec = runCommand) {
+    const status = await getDockerStatus(exec);
+    if (!status.binary) {
+        return {
+            name: 'docker',
+            status: 'fail',
+            message: 'docker is not installed or not on PATH',
+            remediation: dockerInstallGuidance(info)
+        };
+    }
+    if (!status.daemon) {
+        return {
+            name: 'docker',
+            status: 'fail',
+            message: 'docker is installed but the daemon is not reachable',
+            remediation: dockerDaemonGuidance(info)
+        };
+    }
+    return {
+        name: 'docker',
+        status: 'pass',
+        message: 'docker is installed and the daemon is running'
+    };
+}
+export async function checkDockerCompose(info, exec = runCommand) {
+    const plugin = await exec('docker', ['compose', 'version']);
+    if (plugin.code === 0) {
+        return {
+            name: 'docker-compose',
+            status: 'pass',
+            message: 'docker compose plugin is available'
+        };
+    }
+    const standalone = await exec('docker-compose', ['--version']);
+    if (standalone.code === 0) {
+        return {
+            name: 'docker-compose',
+            status: 'pass',
+            message: 'docker-compose (standalone) is available'
+        };
+    }
+    return {
+        name: 'docker-compose',
+        status: 'warn',
+        message: 'docker compose is not available (only needed for docker-compose based workflows)',
+        remediation: info.platform === 'linux' || info.platform === 'wsl'
+            ? 'Install the compose plugin: https://docs.docker.com/compose/install/linux/'
+            : 'Docker Desktop ships with compose; install or update Docker Desktop: https://www.docker.com/products/docker-desktop/'
+    };
+}
+export const MIN_PSQL_MAJOR = 17;
+export function parsePsqlMajor(versionOutput) {
+    const match = versionOutput.match(/\(PostgreSQL\)\s+(\d+)/) || versionOutput.match(/psql[^\d]*(\d+)/);
+    if (!match)
+        return null;
+    const major = parseInt(match[1], 10);
+    return Number.isNaN(major) ? null : major;
+}
+export async function checkPsql(info, exec = runCommand) {
+    const result = await exec('psql', ['--version']);
+    if (result.code !== 0) {
+        return {
+            name: 'psql',
+            status: 'fail',
+            message: 'psql (PostgreSQL client) is not installed or not on PATH',
+            remediation: psqlInstallGuidance(info)
+        };
+    }
+    const major = parsePsqlMajor(result.stdout);
+    if (major === null) {
+        return {
+            name: 'psql',
+            status: 'warn',
+            message: `could not determine psql version from: ${result.stdout}`
+        };
+    }
+    if (major < MIN_PSQL_MAJOR) {
+        return {
+            name: 'psql',
+            status: 'warn',
+            message: `psql ${major} found; PostgreSQL ${MIN_PSQL_MAJOR}+ client is recommended`,
+            remediation: psqlInstallGuidance(info)
+        };
+    }
+    return {
+        name: 'psql',
+        status: 'pass',
+        message: `psql ${major} is installed`
+    };
+}
+export const MIN_NODE_MAJOR = 18;
+export const RECOMMENDED_NODE_MAJOR = 20;
+export function checkNode(version = process.version) {
+    const major = parseInt(version.replace(/^v/, '').split('.')[0], 10);
+    if (Number.isNaN(major)) {
+        return { name: 'node', status: 'warn', message: `could not parse Node.js version: ${version}` };
+    }
+    if (major < MIN_NODE_MAJOR) {
+        return {
+            name: 'node',
+            status: 'fail',
+            message: `Node.js ${version} is not supported; Node.js ${MIN_NODE_MAJOR}+ is required`,
+            remediation: 'Upgrade Node.js (e.g. via nvm: `nvm install --lts`): https://nodejs.org/'
+        };
+    }
+    if (major < RECOMMENDED_NODE_MAJOR) {
+        return {
+            name: 'node',
+            status: 'warn',
+            message: `Node.js ${version} works but ${RECOMMENDED_NODE_MAJOR}+ is recommended`,
+            remediation: 'Upgrade Node.js (e.g. via nvm: `nvm install --lts`): https://nodejs.org/'
+        };
+    }
+    return { name: 'node', status: 'pass', message: `Node.js ${version} is installed` };
+}
+export function summarizeChecks(results) {
+    return {
+        failed: results.filter((r) => r.status === 'fail').length,
+        warned: results.filter((r) => r.status === 'warn').length,
+        passed: results.filter((r) => r.status === 'pass').length
+    };
+}

package/esm/utils/index.js

@@ -1,7 +1,8 @@
 export * from './database';
-export * from './driver';
-export * from './display';
 export * from './deployed-changes';
+export * from './display';
+export * from './doctor';
+export * from './driver';
 export * from './module-utils';
 export * from './npm-version';
 export * from './package-alias';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pgpm",
-  "version": "5.2.3",
+  "version": "5.3.0",
   "author": "Constructive <developers@constructive.io>",
   "description": "PostgreSQL Package Manager - Database migration and package management CLI",
   "main": "index.js",
@@ -48,7 +48,7 @@
     "@inquirerer/utils": "^3.3.9",
     "@pgpmjs/core": "^7.4.2",
     "@pgpmjs/env": "^2.30.2",
-    "@pgpmjs/export": "^1.4.0",
+    "@pgpmjs/export": "^1.5.0",
     "@pgpmjs/logger": "^2.15.2",
     "@pgpmjs/types": "^2.37.2",
     "@pgsql/quotes": "^18.1.0",
@@ -76,5 +76,5 @@
     "pg",
     "pgsql"
   ],
-  "gitHead": "0e3ee42c44c9b35ffac4bf1faa6775eb69311ec4"
+  "gitHead": "518e7ab2270661c64875258436d90fdf76b4b336"
 }

package/utils/display.d.ts

@@ -1 +1 @@
-export declare const usageText = "\n  Usage: pgpm <command> [options]\n\n  Core Database Operations:\n    add                Add database changes to plans and create SQL files\n    deploy             Deploy database changes and migrations\n    verify             Verify database state and migrations\n    revert             Revert database changes and migrations\n\n  Project Management:\n    init               Initialize workspace or module\n    extension          Manage module dependencies\n    plan               Generate module deployment plans\n    package            Package module for distribution\n    export             Export database migrations from existing databases\n    update             Update pgpm to the latest version\n    cache              Manage cached templates (clean)\n    upgrade            Upgrade installed pgpm modules to latest versions (alias: up)\n\n  Database Administration:\n    dump               Dump a database to a sql file\n    kill               Terminate database connections and optionally drop databases\n    install            Install database modules\n    tag                Add tags to changes for versioning\n    clear              Clear database state\n    remove             Remove database changes\n    analyze            Analyze database structure\n    rename             Rename database changes\n    admin-users        Manage admin users\n    tune               Tune PostgreSQL for throwaway environments (CI/test)\n\n  Testing:\n    test-packages      Run integration tests on all workspace packages\n\n  Migration Tools:\n    migrate            Migration management subcommands\n      init             Initialize migration tracking\n      status           Show migration status\n      list             List all changes\n      deps             Show change dependencies\n  \n  Development Tools:\n    docker             Manage Docker containers (start/stop/ls, --minio)\n    env                Manage environment variables (--supabase, --minio)\n    test-packages      Run integration tests on workspace packages\n  \n  Global Options:\n    -h, --help         Display this help information\n    -v, --version      Display version information\n    --cwd <directory>  Working directory (default: current directory)\n\n  Individual Command Help:\n    pgpm <command> --help    Display detailed help for specific command\n    pgpm <command> -h        Display detailed help for specific command\n\n  Examples:\n    pgpm deploy --help       Show deploy command options\n    pgpm init workspace      Initialize new workspace\n    pgpm install @pgpm/base32  Install a database module\n  ";
+export declare const usageText = "\n  Usage: pgpm <command> [options]\n\n  Core Database Operations:\n    add                Add database changes to plans and create SQL files\n    deploy             Deploy database changes and migrations\n    verify             Verify database state and migrations\n    revert             Revert database changes and migrations\n\n  Project Management:\n    init               Initialize workspace or module\n    extension          Manage module dependencies\n    plan               Generate module deployment plans\n    package            Package module for distribution\n    export             Export database migrations from existing databases\n    update             Update pgpm to the latest version\n    cache              Manage cached templates (clean)\n    upgrade            Upgrade installed pgpm modules to latest versions (alias: up)\n\n  Database Administration:\n    dump               Dump a database to a sql file\n    kill               Terminate database connections and optionally drop databases\n    install            Install database modules\n    tag                Add tags to changes for versioning\n    clear              Clear database state\n    remove             Remove database changes\n    analyze            Analyze database structure\n    rename             Rename database changes\n    admin-users        Manage admin users\n    tune               Tune PostgreSQL for throwaway environments (CI/test)\n\n  Testing:\n    test-packages      Run integration tests on all workspace packages\n\n  Migration Tools:\n    migrate            Migration management subcommands\n      init             Initialize migration tracking\n      status           Show migration status\n      list             List all changes\n      deps             Show change dependencies\n  \n  Development Tools:\n    docker             Manage Docker containers (start/stop/ls, --minio)\n    doctor             Check local dependencies (node, docker, psql) with install guidance\n    env                Manage environment variables (--supabase, --minio)\n    test-packages      Run integration tests on workspace packages\n  \n  Global Options:\n    -h, --help         Display this help information\n    -v, --version      Display version information\n    --cwd <directory>  Working directory (default: current directory)\n\n  Individual Command Help:\n    pgpm <command> --help    Display detailed help for specific command\n    pgpm <command> -h        Display detailed help for specific command\n\n  Examples:\n    pgpm deploy --help       Show deploy command options\n    pgpm init workspace      Initialize new workspace\n    pgpm install @pgpm/base32  Install a database module\n  ";

package/utils/display.js

@@ -44,6 +44,7 @@ exports.usageText = `
   
   Development Tools:
     docker             Manage Docker containers (start/stop/ls, --minio)
+    doctor             Check local dependencies (node, docker, psql) with install guidance
     env                Manage environment variables (--supabase, --minio)
     test-packages      Run integration tests on workspace packages
   

package/utils/doctor.d.ts

@@ -0,0 +1,43 @@
+export type Platform = 'macos' | 'linux' | 'wsl' | 'windows' | 'unknown';
+export interface PlatformInfo {
+    platform: Platform;
+    distro?: string;
+}
+export interface ExecResult {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export type CommandRunner = (command: string, args: string[]) => Promise<ExecResult>;
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+export interface CheckResult {
+    name: string;
+    status: CheckStatus;
+    message: string;
+    remediation?: string;
+}
+export declare const runCommand: CommandRunner;
+export declare function detectPlatform(platform?: NodeJS.Platform, readFile?: (path: string) => string): PlatformInfo;
+export declare function dockerInstallGuidance(info: PlatformInfo): string;
+export declare function dockerDaemonGuidance(info: PlatformInfo): string;
+export declare function psqlInstallGuidance(info: PlatformInfo): string;
+export declare function checkDockerBinary(exec?: CommandRunner): Promise<boolean>;
+export declare function checkDockerDaemon(exec?: CommandRunner): Promise<boolean>;
+export interface DockerStatus {
+    binary: boolean;
+    daemon: boolean;
+}
+export declare function getDockerStatus(exec?: CommandRunner): Promise<DockerStatus>;
+export declare function checkDocker(info: PlatformInfo, exec?: CommandRunner): Promise<CheckResult>;
+export declare function checkDockerCompose(info: PlatformInfo, exec?: CommandRunner): Promise<CheckResult>;
+export declare const MIN_PSQL_MAJOR = 17;
+export declare function parsePsqlMajor(versionOutput: string): number | null;
+export declare function checkPsql(info: PlatformInfo, exec?: CommandRunner): Promise<CheckResult>;
+export declare const MIN_NODE_MAJOR = 18;
+export declare const RECOMMENDED_NODE_MAJOR = 20;
+export declare function checkNode(version?: string): CheckResult;
+export declare function summarizeChecks(results: CheckResult[]): {
+    failed: number;
+    warned: number;
+    passed: number;
+};

package/utils/doctor.js

@@ -0,0 +1,265 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RECOMMENDED_NODE_MAJOR = exports.MIN_NODE_MAJOR = exports.MIN_PSQL_MAJOR = exports.runCommand = void 0;
+exports.detectPlatform = detectPlatform;
+exports.dockerInstallGuidance = dockerInstallGuidance;
+exports.dockerDaemonGuidance = dockerDaemonGuidance;
+exports.psqlInstallGuidance = psqlInstallGuidance;
+exports.checkDockerBinary = checkDockerBinary;
+exports.checkDockerDaemon = checkDockerDaemon;
+exports.getDockerStatus = getDockerStatus;
+exports.checkDocker = checkDocker;
+exports.checkDockerCompose = checkDockerCompose;
+exports.parsePsqlMajor = parsePsqlMajor;
+exports.checkPsql = checkPsql;
+exports.checkNode = checkNode;
+exports.summarizeChecks = summarizeChecks;
+const child_process_1 = require("child_process");
+const fs_1 = require("fs");
+const runCommand = (command, args) => {
+    return new Promise((resolve) => {
+        const child = (0, child_process_1.spawn)(command, args, { stdio: 'pipe' });
+        let stdout = '';
+        let stderr = '';
+        child.stdout?.on('data', (data) => {
+            stdout += data.toString();
+        });
+        child.stderr?.on('data', (data) => {
+            stderr += data.toString();
+        });
+        child.on('error', () => {
+            resolve({ code: 127, stdout: '', stderr: `${command}: command not found` });
+        });
+        child.on('close', (code) => {
+            resolve({ code: code ?? 0, stdout: stdout.trim(), stderr: stderr.trim() });
+        });
+    });
+};
+exports.runCommand = runCommand;
+function detectPlatform(platform = process.platform, readFile = (p) => (0, fs_1.readFileSync)(p, 'utf-8')) {
+    if (platform === 'darwin') {
+        return { platform: 'macos' };
+    }
+    if (platform === 'win32') {
+        return { platform: 'windows' };
+    }
+    if (platform === 'linux') {
+        let distro;
+        try {
+            const release = readFile('/etc/os-release');
+            const match = release.match(/^ID=("?)([^"\n]*)\1$/m);
+            if (match) {
+                distro = match[2];
+            }
+        }
+        catch {
+            // ignore
+        }
+        try {
+            const version = readFile('/proc/version');
+            if (/microsoft/i.test(version)) {
+                return { platform: 'wsl', distro };
+            }
+        }
+        catch {
+            // ignore
+        }
+        return { platform: 'linux', distro };
+    }
+    return { platform: 'unknown' };
+}
+const DEBIAN_LIKE = ['ubuntu', 'debian', 'pop', 'linuxmint', 'elementary'];
+const RHEL_LIKE = ['fedora', 'rhel', 'centos', 'rocky', 'almalinux', 'amzn'];
+function isDebianLike(distro) {
+    return !!distro && DEBIAN_LIKE.includes(distro);
+}
+function isRhelLike(distro) {
+    return !!distro && RHEL_LIKE.includes(distro);
+}
+function dockerInstallGuidance(info) {
+    switch (info.platform) {
+        case 'macos':
+            return 'Install Docker Desktop for Mac: https://www.docker.com/products/docker-desktop/ (or `brew install --cask docker`)';
+        case 'windows':
+            return 'Install Docker Desktop for Windows: https://www.docker.com/products/docker-desktop/';
+        case 'wsl':
+            return 'Install Docker Desktop for Windows with the WSL 2 backend enabled: https://docs.docker.com/desktop/wsl/';
+        case 'linux':
+            if (isDebianLike(info.distro)) {
+                return 'Install Docker Engine: https://docs.docker.com/engine/install/ubuntu/ (e.g. `sudo apt-get install docker.io` or the official docker-ce packages)';
+            }
+            if (isRhelLike(info.distro)) {
+                return 'Install Docker Engine: https://docs.docker.com/engine/install/fedora/ (e.g. `sudo dnf install docker-ce`)';
+            }
+            return 'Install Docker Engine for your distribution: https://docs.docker.com/engine/install/';
+        default:
+            return 'Install Docker: https://docs.docker.com/get-docker/';
+    }
+}
+function dockerDaemonGuidance(info) {
+    switch (info.platform) {
+        case 'macos':
+        case 'windows':
+            return 'Docker is installed but the daemon is not running. Open the Docker Desktop application and wait for it to finish starting.';
+        case 'wsl':
+            return 'Docker is installed but the daemon is not reachable. Start Docker Desktop on Windows and make sure WSL integration is enabled for this distro.';
+        case 'linux':
+            return 'Docker is installed but the daemon is not running. Start it with `sudo systemctl start docker` (and `sudo systemctl enable docker` to start on boot). If you get a permission error, add your user to the docker group: `sudo usermod -aG docker $USER` and re-login.';
+        default:
+            return 'Docker is installed but the daemon is not reachable. Start the Docker daemon and try again.';
+    }
+}
+function psqlInstallGuidance(info) {
+    switch (info.platform) {
+        case 'macos':
+            return 'Install the PostgreSQL client via Homebrew: `brew install libpq && brew link --force libpq`';
+        case 'windows':
+            return 'Install the PostgreSQL client tools: `winget install PostgreSQL.PostgreSQL` or download from https://www.postgresql.org/download/windows/';
+        case 'wsl':
+        case 'linux':
+            if (isRhelLike(info.distro)) {
+                return 'Install the PostgreSQL client: `sudo dnf install postgresql`';
+            }
+            return 'Install the PostgreSQL client: `sudo apt-get install postgresql-client`';
+        default:
+            return 'Install the PostgreSQL client tools (psql): https://www.postgresql.org/download/';
+    }
+}
+async function checkDockerBinary(exec = exports.runCommand) {
+    const result = await exec('docker', ['--version']);
+    return result.code === 0;
+}
+async function checkDockerDaemon(exec = exports.runCommand) {
+    const result = await exec('docker', ['info']);
+    return result.code === 0;
+}
+async function getDockerStatus(exec = exports.runCommand) {
+    const binary = await checkDockerBinary(exec);
+    if (!binary) {
+        return { binary: false, daemon: false };
+    }
+    const daemon = await checkDockerDaemon(exec);
+    return { binary, daemon };
+}
+async function checkDocker(info, exec = exports.runCommand) {
+    const status = await getDockerStatus(exec);
+    if (!status.binary) {
+        return {
+            name: 'docker',
+            status: 'fail',
+            message: 'docker is not installed or not on PATH',
+            remediation: dockerInstallGuidance(info)
+        };
+    }
+    if (!status.daemon) {
+        return {
+            name: 'docker',
+            status: 'fail',
+            message: 'docker is installed but the daemon is not reachable',
+            remediation: dockerDaemonGuidance(info)
+        };
+    }
+    return {
+        name: 'docker',
+        status: 'pass',
+        message: 'docker is installed and the daemon is running'
+    };
+}
+async function checkDockerCompose(info, exec = exports.runCommand) {
+    const plugin = await exec('docker', ['compose', 'version']);
+    if (plugin.code === 0) {
+        return {
+            name: 'docker-compose',
+            status: 'pass',
+            message: 'docker compose plugin is available'
+        };
+    }
+    const standalone = await exec('docker-compose', ['--version']);
+    if (standalone.code === 0) {
+        return {
+            name: 'docker-compose',
+            status: 'pass',
+            message: 'docker-compose (standalone) is available'
+        };
+    }
+    return {
+        name: 'docker-compose',
+        status: 'warn',
+        message: 'docker compose is not available (only needed for docker-compose based workflows)',
+        remediation: info.platform === 'linux' || info.platform === 'wsl'
+            ? 'Install the compose plugin: https://docs.docker.com/compose/install/linux/'
+            : 'Docker Desktop ships with compose; install or update Docker Desktop: https://www.docker.com/products/docker-desktop/'
+    };
+}
+exports.MIN_PSQL_MAJOR = 17;
+function parsePsqlMajor(versionOutput) {
+    const match = versionOutput.match(/\(PostgreSQL\)\s+(\d+)/) || versionOutput.match(/psql[^\d]*(\d+)/);
+    if (!match)
+        return null;
+    const major = parseInt(match[1], 10);
+    return Number.isNaN(major) ? null : major;
+}
+async function checkPsql(info, exec = exports.runCommand) {
+    const result = await exec('psql', ['--version']);
+    if (result.code !== 0) {
+        return {
+            name: 'psql',
+            status: 'fail',
+            message: 'psql (PostgreSQL client) is not installed or not on PATH',
+            remediation: psqlInstallGuidance(info)
+        };
+    }
+    const major = parsePsqlMajor(result.stdout);
+    if (major === null) {
+        return {
+            name: 'psql',
+            status: 'warn',
+            message: `could not determine psql version from: ${result.stdout}`
+        };
+    }
+    if (major < exports.MIN_PSQL_MAJOR) {
+        return {
+            name: 'psql',
+            status: 'warn',
+            message: `psql ${major} found; PostgreSQL ${exports.MIN_PSQL_MAJOR}+ client is recommended`,
+            remediation: psqlInstallGuidance(info)
+        };
+    }
+    return {
+        name: 'psql',
+        status: 'pass',
+        message: `psql ${major} is installed`
+    };
+}
+exports.MIN_NODE_MAJOR = 18;
+exports.RECOMMENDED_NODE_MAJOR = 20;
+function checkNode(version = process.version) {
+    const major = parseInt(version.replace(/^v/, '').split('.')[0], 10);
+    if (Number.isNaN(major)) {
+        return { name: 'node', status: 'warn', message: `could not parse Node.js version: ${version}` };
+    }
+    if (major < exports.MIN_NODE_MAJOR) {
+        return {
+            name: 'node',
+            status: 'fail',
+            message: `Node.js ${version} is not supported; Node.js ${exports.MIN_NODE_MAJOR}+ is required`,
+            remediation: 'Upgrade Node.js (e.g. via nvm: `nvm install --lts`): https://nodejs.org/'
+        };
+    }
+    if (major < exports.RECOMMENDED_NODE_MAJOR) {
+        return {
+            name: 'node',
+            status: 'warn',
+            message: `Node.js ${version} works but ${exports.RECOMMENDED_NODE_MAJOR}+ is recommended`,
+            remediation: 'Upgrade Node.js (e.g. via nvm: `nvm install --lts`): https://nodejs.org/'
+        };
+    }
+    return { name: 'node', status: 'pass', message: `Node.js ${version} is installed` };
+}
+function summarizeChecks(results) {
+    return {
+        failed: results.filter((r) => r.status === 'fail').length,
+        warned: results.filter((r) => r.status === 'warn').length,
+        passed: results.filter((r) => r.status === 'pass').length
+    };
+}

package/utils/index.d.ts

@@ -1,7 +1,8 @@
 export * from './database';
-export * from './driver';
-export * from './display';
 export * from './deployed-changes';
+export * from './display';
+export * from './doctor';
+export * from './driver';
 export * from './module-utils';
 export * from './npm-version';
 export * from './package-alias';

package/utils/index.js

@@ -15,9 +15,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./database"), exports);
-__exportStar(require("./driver"), exports);
-__exportStar(require("./display"), exports);
 __exportStar(require("./deployed-changes"), exports);
+__exportStar(require("./display"), exports);
+__exportStar(require("./doctor"), exports);
+__exportStar(require("./driver"), exports);
 __exportStar(require("./module-utils"), exports);
 __exportStar(require("./npm-version"), exports);
 __exportStar(require("./package-alias"), exports);