@mondaydotcomorg/z2h-cli 0.13.1 → 0.14.0

package/src/commands/doctor.ts

@@ -0,0 +1,393 @@
+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';
+import { isZ2hWorkspace, getWorkspaceHome } from '../util/workspace';
+import { Z2H_AUTH_FILE, tryReadAuthTokenSync } from '../util/auth/auth-store';
+import { brokerNpmRegistryUrl, routingHeaders } from '../constants';
+
+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'
+);
+
+export interface DoctorOptions {
+  json?: boolean;
+}
+
+type Status = 'ok' | 'warn' | 'fail';
+
+interface CheckResult {
+  label: string;
+  status: Status;
+  detail?: string;
+  fix?: string;
+}
+
+interface InstalledPluginsJson {
+  plugins?: Record<string, { installPath?: string }[]>;
+}
+
+// ── helpers ───────────────────────────────────────────────────────────────────
+
+async function checkTool(
+  label: string,
+  opts: {
+    cmd: string;
+    args: string[];
+    failStatus?: Status;
+    getVersion?: (stdout: string) => string | undefined | Promise<string | undefined>;
+    fix?: string;
+  }
+): Promise<CheckResult> {
+  const { cmd, args, failStatus = 'fail', getVersion, fix } = opts;
+  let stdout: string;
+  try {
+    ({ stdout } = await execa(cmd, args));
+    stdout = stdout.trim();
+  } catch {
+    return { label, status: failStatus, detail: 'not found', fix };
+  }
+  let version: string | undefined;
+  try {
+    version = getVersion ? await getVersion(stdout) : stdout;
+  } catch {
+    /* best-effort */
+  }
+  return { label, status: 'ok', detail: version };
+}
+
+// ── checks ───────────────────────────────────────────────────────────────────
+
+function checkNvm(): Promise<CheckResult> {
+  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(): Promise<CheckResult> {
+  try {
+    const { stdout } = await execa('node', ['--version']);
+    const current = stdout.trim();
+
+    let requiredNodeVersion: string | undefined;
+    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(): Promise<CheckResult> {
+  return checkTool('yarn', { cmd: 'yarn', args: ['--version'], fix: BOOTSTRAP_CMD });
+}
+
+function checkAws(): Promise<CheckResult> {
+  return checkTool('aws', { cmd: 'aws', args: ['--version'], getVersion: s => s.split(/\s/)[0], fix: BOOTSTRAP_CMD });
+}
+
+function checkGitRemoteS3(): Promise<CheckResult> {
+  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(): Promise<CheckResult> {
+  const { version } = createRequire(import.meta.url)('../../package.json') as { version: string };
+
+  let latestVersion: string | undefined;
+  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()) as { 'dist-tags'?: { latest?: string } };
+        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(): Promise<CheckResult> {
+  try {
+    const parsed = (await readJson(Z2H_AUTH_FILE)) as { token?: string };
+    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: string;
+    if ((err as NodeJS.ErrnoException).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(): Promise<CheckResult> {
+  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(): Promise<CheckResult> {
+  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(): Promise<CheckResult> {
+  const REACT_VERSION_LABEL = 'react version';
+  const REQUIRED_REACT_VERSION = '18.x';
+
+  const reactVersionFail: (detail: string) => CheckResult = detail => ({
+    label: REACT_VERSION_LABEL,
+    status: 'fail',
+    detail,
+    fix: BOOTSTRAP_CMD,
+  });
+
+  const home = getWorkspaceHome();
+  let pkg: { dependencies?: Record<string, string> };
+
+  try {
+    pkg = (await readJson(path.join(home, 'package.json'))) as { dependencies?: Record<string, string> };
+  } 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(): Promise<CheckResult> {
+  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: string,
+  label: string,
+  isMandatory: boolean,
+  pluginsJson: InstalledPluginsJson | null
+): Promise<CheckResult> {
+  const missingStatus: Status = 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: Record<Status, string> = {
+  ok: pc.green('✅'),
+  warn: pc.yellow('⚠️ '),
+  fail: pc.red('❌'),
+};
+
+function renderCheck(c: CheckResult): void {
+  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 ───────────────────────────────────────────────────────────────────
+
+export async function doctorCommand(opts: DoctorOptions = {}): Promise<void> {
+  if (opts.json) {
+    setOutputMode('json');
+  }
+
+  let pluginsJson: InstalledPluginsJson | null = null;
+  try {
+    if (await pathExists(CLAUDE_PLUGINS_JSON)) {
+      pluginsJson = (await readJson(CLAUDE_PLUGINS_JSON)) as InstalledPluginsJson;
+    }
+  } 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))] as string[];
+    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');
+  }
+}

package/src/index.ts

@@ -8,6 +8,7 @@ import { devCommand } from './commands/dev';
 import { buildCommand } from './commands/build';
 import { cleanCommand } from './commands/clean';
 import { deployCommand } from './commands/deploy';
+import { deleteCommand } from './commands/delete';
 import { grantCommand, revokeCommand, transferOwnerCommand } from './commands/grant';
 import { createWorkspaceCommand } from './commands/create-workspace';
 import { createCommand, CreateOptions } from './commands/create';
@@ -15,6 +16,7 @@ import { generateZ2HTokenCommand } from './commands/generate-z2h-token';
 import { migrateCommand } from './commands/migrate';
 import { tagCommand } from './commands/tag';
 import { editCommand } from './commands/edit';
+import { doctorCommand } from './commands/doctor';
 import { errorLog, fail, getOutputMode } from './util/logger';
 import { trackDuration } from './util/tracker';
 import { getCwdAppName } from './util/app-name';
@@ -254,6 +256,21 @@ async function main(): Promise<void> {
       }
     });
 
+  program
+    .command('delete')
+    .description('Permanently delete the current app and take it offline (owners/admins only)')
+    .option('--yes', 'skip the confirmation prompt (required for --json / non-interactive)')
+    .option('--json', 'emit structured JSON on stdout')
+    .action(async (opts: { yes?: boolean; json?: boolean }) => {
+      try {
+        await trackDuration('z2h_app_delete_success', () => deleteCommand(opts), {
+          app_name: getCwdAppName(),
+        });
+      } catch (err) {
+        await fail(`delete failed: ${(err as Error).message}`, { command: 'delete' }, 1);
+      }
+    });
+
   program
     .command('migrate')
     .description('Run pending workspace migrations')
@@ -267,6 +284,18 @@ async function main(): Promise<void> {
       }
     });
 
+  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: { json?: boolean }) => {
+      try {
+        await doctorCommand(opts);
+      } catch (err) {
+        await fail(`doctor failed: ${(err as Error).message}`, { command: 'doctor' }, 1);
+      }
+    });
+
   await program.parseAsync(process.argv);
 }
 

package/src/util/git/__tests__/repo.test.ts

@@ -179,13 +179,35 @@ describe('safeBackupIfDirty', () => {
 
 describe('pullAndResolve', () => {
   it('resolves when pull fast-forwards cleanly', async () => {
-    mockExeca.mockResolvedValueOnce(execaOk()); // git pull --ff-only
+    mockExeca
+      .mockResolvedValueOnce(execaOk('deadbeef\trefs/heads/master')) // ls-remote --heads origin master
+      .mockResolvedValueOnce(execaOk()); // git pull --ff-only
 
     await expect(pullAndResolve(DIR)).resolves.toBeUndefined();
   });
 
+  it('skips the pull (first-deploy) when the remote has no master ref', async () => {
+    mockExeca.mockResolvedValueOnce(execaOk('')); // ls-remote --heads origin master → empty (gone/new remote)
+
+    await expect(pullAndResolve(DIR)).resolves.toBeUndefined();
+
+    const calls = mockExeca.mock.calls.map(c => c.slice(0, 2));
+    expect(calls).toContainEqual(['git', ['ls-remote', '--heads', 'origin', 'master']]);
+    expect(calls).not.toContainEqual(['git', ['pull', '--ff-only']]);
+  });
+
+  it('treats an unreachable ls-remote as no remote and skips the pull', async () => {
+    mockExeca.mockRejectedValueOnce(new Error('fatal: could not read from remote')); // ls-remote fails
+
+    await expect(pullAndResolve(DIR)).resolves.toBeUndefined();
+
+    const calls = mockExeca.mock.calls.map(c => c.slice(0, 2));
+    expect(calls).not.toContainEqual(['git', ['pull', '--ff-only']]);
+  });
+
   it('throws GitConflictError with structured JSON on non-fast-forward', async () => {
     mockExeca
+      .mockResolvedValueOnce(execaOk('deadbeef\trefs/heads/master')) // ls-remote --heads origin master
       .mockRejectedValueOnce(new Error('fatal: Not possible to fast-forward')) // git pull
       .mockResolvedValueOnce(execaOk('')) // safeBackupIfDirty: git status --porcelain (clean)
       .mockResolvedValueOnce(execaOk()) // gatherConflictInfo: git fetch origin

package/src/util/git/repo.ts

@@ -86,6 +86,18 @@ export async function safeBackupIfDirty(dir: string): Promise<void> {
 
 export async function pullAndResolve(dir: string, env?: Record<string, string>): Promise<void> {
   const gitEnv = env ? { ...process.env, ...env } : undefined;
+
+  // If the remote has no master branch there's nothing to pull — treat it as a
+  // first deploy and let the subsequent push create it. This covers a brand-new
+  // remote as well as one whose objects were removed (e.g. the app was deleted,
+  // wiping its S3 git prefix), which would otherwise surface as a bogus conflict.
+  const hasRemoteMaster = await execGit(['ls-remote', '--heads', 'origin', 'master'], dir, gitEnv)
+    .then(r => Boolean(r.stdout.trim()))
+    .catch(() => false);
+  if (!hasRemoteMaster) {
+    return;
+  }
+
   try {
     await execGit(['pull', '--ff-only'], dir, gitEnv);
   } catch (err) {