@mondaydotcomorg/z2h-cli 0.13.2 → 0.14.0

package/dist/esm/commands/doctor.mjs

@@ -0,0 +1,324 @@
+import { createRequire } from 'node:module';
+import { readFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { execa } from 'execa';
+import semver from 'semver';
+import { pathExists, readJson } from 'fs-extra';
+import pc from 'picocolors';
+import { setOutputMode, output } from '../util/logger.mjs';
+import { getWorkspaceHome, isZ2hWorkspace } from '../util/workspace.mjs';
+import { tryReadAuthTokenSync, Z2H_AUTH_FILE } from '../util/auth/auth-store.mjs';
+import { brokerNpmRegistryUrl, routingHeaders } from '../constants.mjs';
+
+const HOME = os.homedir();
+const Z2H_REPO_ROOT = path.join(HOME, 'Development', 'bigbrain-z2h');
+const BOOTSTRAP_CMD = `bash ${path.join(Z2H_REPO_ROOT, 'z2h/setup/bootstrap.sh')}`;
+const UPDATE_CMD = `bash ${path.join(Z2H_REPO_ROOT, 'z2h/setup/update.sh')}`;
+const CLAUDE_PLUGINS_JSON = path.join(HOME, '.claude', 'plugins', 'installed_plugins.json');
+const SSL_CERT_PATH = path.join(HOME, 'Library', 'Application Support', 'devcert', 'domains', 'webpack.llama.fan', 'certificate.crt');
+// ── helpers ───────────────────────────────────────────────────────────────────
+async function checkTool(label, opts) {
+    const { cmd, args, failStatus = 'fail', getVersion, fix } = opts;
+    let stdout;
+    try {
+        ({ stdout } = await execa(cmd, args));
+        stdout = stdout.trim();
+    }
+    catch {
+        return { label, status: failStatus, detail: 'not found', fix };
+    }
+    let version;
+    try {
+        version = getVersion ? await getVersion(stdout) : stdout;
+    }
+    catch {
+        /* best-effort */
+    }
+    return { label, status: 'ok', detail: version };
+}
+// ── checks ───────────────────────────────────────────────────────────────────
+function checkNvm() {
+    const nvmScript = path.join(HOME, '.nvm', 'nvm.sh');
+    return checkTool('nvm', {
+        cmd: 'bash',
+        args: ['-c', `source "${nvmScript}" && nvm --version`],
+        failStatus: 'warn',
+        fix: BOOTSTRAP_CMD,
+    });
+}
+async function checkNode() {
+    try {
+        const { stdout } = await execa('node', ['--version']);
+        const current = stdout.trim();
+        let requiredNodeVersion;
+        try {
+            const nvmrc = (await readFile(path.join(Z2H_REPO_ROOT, '.nvmrc'), 'utf8')).trim();
+            requiredNodeVersion = semver.coerce(nvmrc)?.version;
+        }
+        catch {
+            // repo not cloned — skip version comparison
+        }
+        if (!requiredNodeVersion) {
+            return { label: 'node', status: 'ok', detail: current };
+        }
+        const matches = semver.satisfies(current, `~${requiredNodeVersion}`);
+        return {
+            label: 'node',
+            status: matches ? 'ok' : 'fail',
+            detail: matches ? current : `${current} (expected ${requiredNodeVersion})`,
+            fix: matches ? undefined : BOOTSTRAP_CMD,
+        };
+    }
+    catch {
+        return { label: 'node', status: 'fail', detail: 'not found', fix: BOOTSTRAP_CMD };
+    }
+}
+function checkYarn() {
+    return checkTool('yarn', { cmd: 'yarn', args: ['--version'], fix: BOOTSTRAP_CMD });
+}
+function checkAws() {
+    return checkTool('aws', { cmd: 'aws', args: ['--version'], getVersion: s => s.split(/\s/)[0], fix: BOOTSTRAP_CMD });
+}
+function checkGitRemoteS3() {
+    return checkTool('git-remote-s3', {
+        cmd: 'which',
+        args: ['git-remote-s3'],
+        getVersion: async () => {
+            const { stdout: pipxOut } = await execa('pipx', ['runpip', 'git-remote-s3', 'show', 'git-remote-s3']);
+            return pipxOut.match(/^Version:\s+(.+)/m)?.[1]?.trim();
+        },
+        fix: BOOTSTRAP_CMD,
+    });
+}
+async function checkZ2hCli() {
+    const { version } = createRequire(import.meta.url)('../../package.json');
+    let latestVersion;
+    try {
+        const token = tryReadAuthTokenSync();
+        if (token) {
+            const res = await fetch(`${brokerNpmRegistryUrl()}/@mondaydotcomorg%2Fz2h-cli`, {
+                headers: { Authorization: `Bearer ${token}`, ...routingHeaders() },
+                signal: AbortSignal.timeout(5000),
+            });
+            if (res.ok) {
+                const data = (await res.json());
+                latestVersion = data['dist-tags']?.latest;
+            }
+        }
+    }
+    catch {
+        // version check is best-effort — no network / token not ready
+    }
+    if (latestVersion && latestVersion !== version) {
+        return { label: 'z2h-cli', status: 'warn', detail: `${version} (latest: ${latestVersion})`, fix: UPDATE_CMD };
+    }
+    return { label: 'z2h-cli', status: 'ok', detail: latestVersion ? `${version} (up to date)` : version };
+}
+async function checkAuthToken() {
+    try {
+        const parsed = (await readJson(Z2H_AUTH_FILE));
+        if (!parsed.token) {
+            return {
+                label: 'auth token',
+                status: 'fail',
+                detail: `${Z2H_AUTH_FILE} missing token field`,
+                fix: 'z2h-cli generate-z2h-token',
+            };
+        }
+        return { label: 'auth token', status: 'ok', detail: Z2H_AUTH_FILE };
+    }
+    catch (err) {
+        let detail;
+        if (err.code === 'ENOENT') {
+            detail = `${Z2H_AUTH_FILE} not found`;
+        }
+        else if (err instanceof SyntaxError) {
+            detail = `${Z2H_AUTH_FILE} could not be parsed`;
+        }
+        else {
+            detail = `${Z2H_AUTH_FILE} is unreadable`;
+        }
+        return { label: 'auth token', status: 'fail', detail, fix: 'z2h-cli generate-z2h-token' };
+    }
+}
+async function checkNpmTokenInProfile() {
+    const profiles = [
+        path.join(HOME, 'dotfiles', '.bash_profile'),
+        path.join(HOME, '.zshrc'),
+        path.join(HOME, '.bash_profile'),
+    ];
+    for (const profile of profiles) {
+        if (!(await pathExists(profile))) {
+            continue;
+        }
+        try {
+            const content = await readFile(profile, 'utf8');
+            if (content.includes('export Z2H_NPM_TOKEN')) {
+                return { label: 'npm token in profile', status: 'ok', detail: path.basename(profile) };
+            }
+        }
+        catch {
+            // skip unreadable profile
+        }
+    }
+    return {
+        label: 'npm token in profile',
+        status: 'fail',
+        detail: 'export Z2H_NPM_TOKEN not found in any shell profile',
+        fix: BOOTSTRAP_CMD,
+    };
+}
+async function checkWorkspace() {
+    const home = getWorkspaceHome();
+    const ok = await isZ2hWorkspace(home);
+    return {
+        label: 'workspace',
+        status: ok ? 'ok' : 'fail',
+        detail: ok ? home : `${home} not initialized`,
+        fix: ok ? undefined : 'z2h-cli create-workspace',
+    };
+}
+async function checkReactVersion() {
+    const REACT_VERSION_LABEL = 'react version';
+    const REQUIRED_REACT_VERSION = '18.x';
+    const reactVersionFail = detail => ({
+        label: REACT_VERSION_LABEL,
+        status: 'fail',
+        detail,
+        fix: BOOTSTRAP_CMD,
+    });
+    const home = getWorkspaceHome();
+    let pkg;
+    try {
+        pkg = (await readJson(path.join(home, 'package.json')));
+    }
+    catch {
+        return reactVersionFail('could not read workspace package.json');
+    }
+    const reactVersion = pkg.dependencies?.react;
+    if (!reactVersion) {
+        return reactVersionFail('react not in workspace dependencies');
+    }
+    const coerced = semver.coerce(reactVersion)?.version;
+    if (!coerced || !semver.satisfies(coerced, REQUIRED_REACT_VERSION)) {
+        return reactVersionFail(`invalid react version: ${reactVersion} (expected ${REQUIRED_REACT_VERSION})`);
+    }
+    return {
+        label: REACT_VERSION_LABEL,
+        status: 'ok',
+        detail: reactVersion,
+    };
+}
+async function checkSslCert() {
+    const ok = await pathExists(SSL_CERT_PATH);
+    return {
+        label: 'SSL cert',
+        status: ok ? 'ok' : 'warn',
+        detail: ok ? 'webpack.llama.fan' : 'not found — auto-installs on first z2h-cli dev',
+        fix: ok ? undefined : 'z2h-cli dev',
+    };
+}
+async function checkPlugin(pluginKey, label, isMandatory, pluginsJson) {
+    const missingStatus = isMandatory ? 'fail' : 'warn';
+    if (!pluginsJson) {
+        return { label, status: missingStatus, detail: `${CLAUDE_PLUGINS_JSON} not found`, fix: BOOTSTRAP_CMD };
+    }
+    const entries = pluginsJson.plugins?.[pluginKey];
+    if (!entries?.length) {
+        return { label, status: missingStatus, detail: `plugin ${pluginKey} not registered`, fix: BOOTSTRAP_CMD };
+    }
+    const installPath = entries[0].installPath;
+    if (!installPath) {
+        return { label, status: missingStatus, detail: 'installPath missing', fix: BOOTSTRAP_CMD };
+    }
+    const exists = await pathExists(installPath);
+    return {
+        label,
+        status: exists ? 'ok' : missingStatus,
+        detail: exists ? installPath : `${installPath} not found`,
+        fix: exists ? undefined : BOOTSTRAP_CMD,
+    };
+}
+// ── rendering ─────────────────────────────────────────────────────────────────
+const STATUS_ICON = {
+    ok: pc.green('✅'),
+    warn: pc.yellow('⚠️ '),
+    fail: pc.red('❌'),
+};
+function renderCheck(c) {
+    const icon = STATUS_ICON[c.status];
+    const label = c.label.padEnd(22);
+    const detail = c.detail ? pc.dim(c.detail) : '';
+    process.stdout.write(`  ${icon} ${label}${detail}\n`);
+}
+// ── command ───────────────────────────────────────────────────────────────────
+async function doctorCommand(opts = {}) {
+    if (opts.json) {
+        setOutputMode('json');
+    }
+    let pluginsJson = null;
+    try {
+        if (await pathExists(CLAUDE_PLUGINS_JSON)) {
+            pluginsJson = (await readJson(CLAUDE_PLUGINS_JSON));
+        }
+    }
+    catch {
+        // treat as missing
+    }
+    const systemChecks = await Promise.all([checkNvm(), checkNode(), checkYarn(), checkAws(), checkGitRemoteS3()]);
+    const cliChecks = await Promise.all([checkZ2hCli(), checkAuthToken(), checkNpmTokenInProfile()]);
+    const workspaceChecks = await Promise.all([checkWorkspace(), checkReactVersion(), checkSslCert()]);
+    const pluginChecks = await Promise.all([
+        checkPlugin('z2h@bigbrain-z2h', 'z2h plugin', true, pluginsJson),
+        checkPlugin('cf-external-claude-plugin@client-foundations-ai-tools', 'cf-external plugin', false, pluginsJson),
+        checkPlugin('pr-guardrails@agentic-builders-hub', 'pr-guardrails plugin', false, pluginsJson),
+    ]);
+    const sections = [
+        { title: 'System tools', checks: systemChecks },
+        { title: 'CLI & auth', checks: cliChecks },
+        { title: 'Workspace', checks: workspaceChecks },
+        { title: 'Plugins', checks: pluginChecks },
+    ];
+    const allChecks = sections.flatMap(s => s.checks);
+    const issues = allChecks.filter(c => c.status !== 'ok');
+    if (opts.json) {
+        output('', {
+            ok: issues.filter(c => c.status === 'fail').length === 0,
+            checks: allChecks,
+        });
+        return;
+    }
+    for (const section of sections) {
+        process.stdout.write(`\n${pc.bold(section.title)}\n`);
+        for (const check of section.checks) {
+            renderCheck(check);
+        }
+    }
+    process.stdout.write('\n');
+    if (issues.length === 0) {
+        process.stdout.write(pc.bold(pc.green('No issues detected 🚀\n')));
+    }
+    else {
+        const fails = issues.filter(c => c.status === 'fail').length;
+        const warns = issues.filter(c => c.status === 'warn').length;
+        const parts = [
+            fails && `${fails} failure${fails > 1 ? 's' : ''}`,
+            warns && `${warns} warning${warns > 1 ? 's' : ''}`,
+        ].filter(Boolean);
+        process.stdout.write(pc.yellow(`${parts.join(', ')} found\n`));
+        // Deduplicated fixes in the order they were first encountered
+        const fixes = [...new Set(issues.map(c => c.fix).filter(Boolean))];
+        if (fixes.length > 0) {
+            process.stdout.write('\n');
+            process.stdout.write(pc.bold(pc.red('In order to fix these issues, run the following commands:')));
+            process.stdout.write('\n');
+            for (const fix of fixes) {
+                process.stdout.write(`  ${pc.cyan(fix)}\n`);
+            }
+        }
+        process.stdout.write('\n');
+    }
+}
+
+export { doctorCommand };

package/dist/esm/index.mjs

@@ -16,6 +16,7 @@ import { generateZ2HTokenCommand } from './commands/generate-z2h-token.mjs';
 import { migrateCommand } from './commands/migrate.mjs';
 import { tagCommand } from './commands/tag.mjs';
 import { editCommand } from './commands/edit.mjs';
+import { doctorCommand } from './commands/doctor.mjs';
 import { fail, errorLog, getOutputMode } from './util/logger.mjs';
 import { trackDuration } from './util/tracker.mjs';
 import { getCwdAppName } from './util/app-name.mjs';
@@ -257,6 +258,18 @@ async function main() {
             await fail(`migrate failed: ${err.message}`, { command: 'migrate' }, 1);
         }
     });
+    program
+        .command('doctor')
+        .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')
+        .option('--json', 'emit structured JSON on stdout')
+        .action(async (opts) => {
+        try {
+            await doctorCommand(opts);
+        }
+        catch (err) {
+            await fail(`doctor failed: ${err.message}`, { command: 'doctor' }, 1);
+        }
+    });
     await program.parseAsync(process.argv);
 }
 void main()

package/dist/index.js

@@ -16,6 +16,7 @@ const commands_generateZ2hToken = require('./commands/generate-z2h-token.js');
 const commands_migrate = require('./commands/migrate.js');
 const commands_tag = require('./commands/tag.js');
 const commands_edit = require('./commands/edit.js');
+const commands_doctor = require('./commands/doctor.js');
 const util_logger = require('./util/logger.js');
 const util_tracker = require('./util/tracker.js');
 const util_appName = require('./util/app-name.js');
@@ -263,6 +264,18 @@ async function main() {
             await util_logger.fail(`migrate failed: ${err.message}`, { command: 'migrate' }, 1);
         }
     });
+    program
+        .command('doctor')
+        .description('Check that all Z2H tools, auth, workspace, and plugins are correctly set up')
+        .option('--json', 'emit structured JSON on stdout')
+        .action(async (opts) => {
+        try {
+            await commands_doctor.doctorCommand(opts);
+        }
+        catch (err) {
+            await util_logger.fail(`doctor failed: ${err.message}`, { command: 'doctor' }, 1);
+        }
+    });
     await program.parseAsync(process.argv);
 }
 void main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mondaydotcomorg/z2h-cli",
-  "version": "0.13.2",
+  "version": "0.14.0",
   "bin": "./bin/z2h-cli.js",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",