unbound-cli 1.1.8 → 1.3.0

package/src/toolHealth.js

@@ -0,0 +1,288 @@
+// Per-tool local health detection shared by `unbound doctor` and `unbound status`.
+//
+// Source of truth for what each tool installs is the setup repo's per-tool
+// setup.py (mirrored here). Each tool has STRUCTURAL artifacts (a config file
+// with an Unbound marker + an optional hook/script file) that decide whether it
+// is installed, plus AUXILIARY wiring (an env var holding the api key, or the
+// gateway URL). Env vars are persisted to a shell rc file (Unix) or the user
+// registry (Windows), NOT reliably to the current process env, so we read those.
+//
+// Install state (matches the doctor spec):
+//   none of the structural artifacts present  -> not installed
+//   all structural present AND all wiring ok   -> healthy
+//   some present (or wiring broken)            -> tampered
+//   nothing local but an org MDM install found -> managed by MDM
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const { spawnSync } = require('child_process');
+
+const HOME = os.homedir();
+const GATEWAY_DEFAULT = 'https://api.getunbound.ai';
+
+function expand(p) {
+  return p.startsWith('~') ? path.join(HOME, p.slice(1)) : p;
+}
+
+function fileExists(p) {
+  try {
+    return fs.statSync(expand(p)).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function readText(p) {
+  try {
+    return fs.readFileSync(expand(p), 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function readJson(p) {
+  const text = readText(p);
+  if (text == null) return null;
+  try {
+    return JSON.parse(text.replace(/^\uFEFF/, '')); // tolerate a UTF-8 BOM
+  } catch {
+    return undefined; // file exists but is corrupt
+  }
+}
+
+// Candidate shell rc files where the setup scripts append `export NAME=...`.
+function rcFiles() {
+  if (process.platform === 'win32') return [];
+  if (process.platform === 'darwin') return ['~/.zprofile', '~/.bash_profile', '~/.zshrc', '~/.bashrc'];
+  return ['~/.zshrc', '~/.bashrc', '~/.profile'];
+}
+
+// Read a persisted env var: live process env first, then the shell rc (Unix) or
+// the user registry (Windows). Returns the value so callers can flag mismatch.
+function readEnvVar(name) {
+  // `in`, not truthiness: an env var explicitly set to "" is "set but empty", not
+  // absent — without this we'd fall through and return a stale rc-file value,
+  // masking the fact that the live env blanked the key.
+  if (name in process.env) return { found: true, value: process.env[name], source: 'process env' };
+
+  if (process.platform === 'win32') {
+    try {
+      const r = spawnSync('reg', ['query', 'HKCU\\Environment', '/v', name], { encoding: 'utf8' });
+      if (r.status === 0 && r.stdout) {
+        const m = r.stdout.match(new RegExp(`${name}\\s+REG_[A-Z_]+\\s+(.*)`));
+        if (m) return { found: true, value: m[1].trim(), source: 'user registry' };
+      }
+    } catch {
+      /* fall through */
+    }
+    return { found: false };
+  }
+
+  const re = new RegExp(`^\\s*export\\s+${name}=(.*)$`, 'm');
+  for (const rc of rcFiles()) {
+    const text = readText(rc);
+    if (!text) continue;
+    const m = text.match(re);
+    if (m) {
+      const val = m[1].trim().replace(/^["']|["']$/g, '');
+      return { found: true, value: val, source: path.basename(expand(rc)) };
+    }
+  }
+  return { found: false };
+}
+
+// --- check builders. Each returns { name, ok, kind, detail, summary, warn? }. ---
+// kind: 'structural' (decides installed) | 'aux' (wiring health only).
+// summary: a short reason shown inline on the tampered line.
+
+function configCheck(label, file, marker, opts = {}) {
+  const kind = opts.kind || 'structural';
+  const data = marker.json ? readJson(file) : readText(file);
+  let ok = false;
+  let detail;
+  let summary;
+  if (data == null) {
+    detail = `not found (${file})`;
+    summary = opts.short || `${label.toLowerCase()} not found`;
+  } else if (data === undefined) {
+    detail = `unreadable / corrupt (${file})`;
+    summary = `${label.toLowerCase()} unreadable`;
+  } else {
+    ok = marker.test(data);
+    detail = ok ? file : `present but missing the Unbound integration (${file})`;
+    summary = opts.short || `${label.toLowerCase()} not integrated`;
+  }
+  return { name: label, ok, kind, detail, summary };
+}
+
+function scriptCheck(label, file, kind = 'structural') {
+  const ok = fileExists(file);
+  return { name: label, ok, kind, detail: ok ? file : `not found (${file})`, summary: `${label.toLowerCase()} missing` };
+}
+
+function envCheck(label, name, expected, kind = 'aux') {
+  const base = label.replace(/ env$/, '');
+  const r = readEnvVar(name);
+  // An explicitly-empty value is broken wiring, same as absent.
+  if (!r.found || !r.value) return { name: label, ok: false, kind, detail: `${name} is not set`, summary: `${base} not set` };
+  // A value that doesn't match what setup wrote (stale key, wrong gateway URL) is a
+  // real misconfiguration: mark it not-ok so the tool reports tampered, not healthy.
+  if (expected && r.value !== expected) {
+    return { name: label, ok: false, kind, warn: true, summary: `${base} differs from setup`, detail: `${name} set (${r.source}) but differs from what setup configured` };
+  }
+  return { name: label, ok: true, kind, detail: `${name} set (${r.source})`, summary: `${base} set` };
+}
+
+// MDM (org-wide) install detection. An Unbound MDM install is only real when the
+// system managed config REFERENCES the Unbound hook AND the hook script exists.
+// A plain managed-settings.json (Claude Enterprise / generic MDM) does NOT count,
+// and a managed config that points at a missing hook script is a broken (tampered)
+// MDM install, not a healthy one. Returns { status: 'healthy'|'tampered'|null, checks }.
+function mdmDetect(family, dirOverride) {
+  // Only Cursor / Claude Code / Codex have a managed (MDM) directory. Copilot and
+  // Gemini have none — their org install writes the same per-user config into
+  // every profile, so they're checked exactly like a user-level tool.
+  const configName = { cursor: 'hooks.json', 'claude-code': 'managed-settings.json', codex: 'managed-settings.json' };
+  if (!configName[family]) return { status: null, checks: [] };
+
+  const mac = '/Library/Application Support';
+  const win = process.env.ProgramData || 'C:\\ProgramData';
+  const dirs = {
+    cursor: { darwin: `${mac}/Cursor`, linux: '/etc/cursor', win32: path.join(win, 'Cursor') },
+    'claude-code': { darwin: `${mac}/ClaudeCode`, linux: '/etc/claude-code', win32: path.join(win, 'ClaudeCode') },
+    codex: { darwin: `${mac}/Codex`, linux: '/etc/codex', win32: path.join(win, 'Codex') },
+  };
+  const dir = dirOverride || dirs[family][process.platform] || dirs[family].linux;
+  const configPath = path.join(dir, configName[family]);
+  const scriptPath = path.join(dir, 'hooks', 'unbound.py');
+
+  const cfgText = readText(configPath);
+  if (cfgText == null || !cfgText.includes('unbound.py')) return { status: null, checks: [] };
+
+  const scriptOk = fileExists(scriptPath);
+  const checks = [
+    { name: 'MDM config', ok: true, kind: 'structural', detail: configPath, summary: 'managed config' },
+    { name: 'MDM hook script', ok: scriptOk, kind: 'structural', summary: 'managed hook not installed', detail: scriptOk ? scriptPath : `managed config references a hook that isn't installed (${scriptPath})` },
+  ];
+  return { status: scriptOk ? 'healthy' : 'tampered', checks };
+}
+
+// Marker that a claude/codex/cursor hooks block references unbound.py.
+function refsUnbound(obj) {
+  return JSON.stringify(obj || {}).includes('unbound.py');
+}
+
+// One descriptor per (tool, mode). `family` groups the two-mode tools so the
+// collapsed view shows a single line per product.
+function buildVariants(gatewayUrl, apiKey) {
+  const gw = (gatewayUrl || GATEWAY_DEFAULT).replace(/\/+$/, ''); // setup rstrips too
+  return [
+    {
+      key: 'cursor', label: 'Cursor', family: 'cursor', mode: null,
+      checks: () => [
+        configCheck('Config', '~/.cursor/hooks.json', { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', '~/.cursor/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_CURSOR_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'claude-code-subscription', label: 'Claude Code (subscription)', family: 'claude-code', mode: 'subscription',
+      checks: () => [
+        configCheck('Config', '~/.claude/settings.json', { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', '~/.claude/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_CLAUDE_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'claude-code-gateway', label: 'Claude Code (gateway)', family: 'claude-code', mode: 'gateway',
+      checks: () => [
+        configCheck('Config', '~/.claude/settings.json', { json: true, test: (j) => typeof j.apiKeyHelper === 'string' && j.apiKeyHelper.includes('anthropic_key.sh') }),
+        scriptCheck('Key helper', '~/.claude/anthropic_key.sh'),
+        envCheck('API key env', 'UNBOUND_API_KEY', apiKey),
+        envCheck('Gateway URL env', 'ANTHROPIC_BASE_URL', gw),
+      ],
+    },
+    {
+      key: 'codex-subscription', label: 'Codex (subscription)', family: 'codex', mode: 'subscription',
+      checks: () => [
+        configCheck('Config', '~/.codex/hooks.json', { json: true, test: refsUnbound }),
+        configCheck('Hooks feature flag', '~/.codex/config.toml', { json: false, test: (t) => /codex_hooks\s*=\s*true/.test(t) }, { short: 'codex hooks not enabled' }),
+        scriptCheck('Hook script', '~/.codex/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_CODEX_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'codex-gateway', label: 'Codex (gateway)', family: 'codex', mode: 'gateway',
+      checks: () => [
+        configCheck('Config', '~/.codex/config.toml', { json: false, test: (t) => /openai_base_url\s*=/.test(t) }),
+        envCheck('API key env', 'OPENAI_API_KEY', apiKey),
+      ],
+    },
+    {
+      key: 'copilot', label: 'GitHub Copilot', family: 'copilot', mode: null,
+      checks: () => [
+        // Copilot has no managed (MDM) directory: the org install writes the same
+        // ~/.copilot config into every user profile, so it's checked like a
+        // user-level tool and never reports "managed by MDM".
+        configCheck('Config', '~/.copilot/hooks/unbound.json', { json: true, test: refsUnbound }),
+        scriptCheck('Hook script', '~/.copilot/hooks/unbound.py'),
+        envCheck('API key env', 'UNBOUND_COPILOT_API_KEY', apiKey),
+      ],
+    },
+    // Gemini CLI is intentionally omitted here — it isn't part of `setup --all`
+    // and has no managed directory. Add it back when its scope is settled.
+  ];
+}
+
+function statusOf(checks) {
+  const structural = checks.filter((c) => c.kind === 'structural');
+  const present = structural.filter((c) => c.ok);
+  if (present.length === 0) return 'not-installed';
+  if (present.length === structural.length && checks.every((c) => c.ok)) return 'healthy';
+  return 'tampered';
+}
+
+function detectVariant(variant) {
+  const checks = variant.checks();
+  return { key: variant.key, label: variant.label, family: variant.family, mode: variant.mode, status: statusOf(checks), checks };
+}
+
+// Collapse the per-(tool,mode) variants to one entry per product family. Picks
+// the installed/tampered mode if any; otherwise reports managed-by-mdm or
+// not-installed. This is what both `doctor` and `status` render.
+// `_mdmDirs` (test-only) overrides the system MDM directories per family so the
+// org-managed scenarios can be exercised without writing under /Library or /etc.
+function detectTools({ gatewayUrl, apiKey, _mdmDirs } = {}) {
+  const variants = buildVariants(gatewayUrl, apiKey).map(detectVariant);
+  const families = [];
+  const seen = new Set();
+  for (const v of variants) {
+    if (seen.has(v.family)) continue;
+    seen.add(v.family);
+    const sameFamily = variants.filter((x) => x.family === v.family);
+    const present = sameFamily.filter((x) => x.status !== 'not-installed');
+    if (present.length) {
+      // Prefer a tampered variant so a conflicting/partial install surfaces (and
+      // `--fix` reinstalls it). Flag when more than one mode is present at once.
+      const active = present.find((x) => x.status === 'tampered') || present[0];
+      if (present.length > 1) active.conflict = true;
+      active.label = active.label.replace(/ \(.*\)$/, ''); // mode is shown via .mode
+      families.push(active);
+    } else {
+      const family = v.family;
+      const label = v.label.replace(/ \(.*\)$/, '');
+      const mdm = mdmDetect(family, _mdmDirs && _mdmDirs[family]);
+      if (mdm.status === 'healthy') {
+        families.push({ key: family, label, family, mode: null, status: 'managed-by-mdm', checks: mdm.checks, scope: 'mdm' });
+      } else if (mdm.status === 'tampered') {
+        families.push({ key: family, label, family, mode: null, status: 'tampered', checks: mdm.checks, scope: 'mdm' });
+      } else {
+        families.push({ key: family, label, family, mode: null, status: 'not-installed', checks: [] });
+      }
+    }
+  }
+  return families;
+}
+
+module.exports = { detectTools, statusOf, readEnvVar, GATEWAY_DEFAULT };

package/test/command-merge.test.js

@@ -0,0 +1,44 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+const setup = require('../src/commands/setup');
+
+// WEB-4757: `onboard`/`setup` are single commands; MDM vs user scope is
+// auto-detected from sudo/root, so the separate `onboard-mdm` and `setup mdm`
+// commands no longer exist. These guard against a regression that re-splits or
+// drops them.
+
+function buildProgram() {
+  const program = new Command();
+  require('../src/commands/onboard').register(program);
+  setup.register(program);
+  return program;
+}
+
+test('WEB-4757: onboard/setup are single top-level commands, no -mdm variants', () => {
+  const top = buildProgram().commands.map((c) => c.name());
+  assert.ok(top.includes('onboard'), 'onboard is registered');
+  assert.ok(top.includes('setup'), 'setup is registered');
+  assert.ok(!top.includes('onboard-mdm'), 'onboard-mdm is gone');
+});
+
+test('WEB-4757: setup has no `mdm` subcommand; onboard keeps `unschedule`', () => {
+  const program = buildProgram();
+  const setupCmd = program.commands.find((c) => c.name() === 'setup');
+  const onboardCmd = program.commands.find((c) => c.name() === 'onboard');
+  assert.ok(!setupCmd.commands.some((c) => c.name() === 'mdm'), 'setup mdm subcommand is gone');
+  assert.ok(onboardCmd.commands.some((c) => c.name() === 'unschedule'), 'onboard unschedule is kept');
+});
+
+test('WEB-4757: onboard/setup accept --admin-api-key as a back-compat alias', () => {
+  const program = buildProgram();
+  const onboardCmd = program.commands.find((c) => c.name() === 'onboard');
+  const setupCmd = program.commands.find((c) => c.name() === 'setup');
+  assert.ok(onboardCmd.options.some((o) => o.long === '--admin-api-key'), 'onboard --admin-api-key');
+  assert.ok(setupCmd.options.some((o) => o.long === '--admin-api-key'), 'setup --admin-api-key');
+});
+
+test('WEB-4757: scope helper is exported; the throwing checkRoot is gone', () => {
+  assert.equal(typeof setup.hasRootPrivileges, 'function');
+  assert.equal(setup.checkRoot, undefined);
+});

package/test/doctor-exit.test.js

@@ -0,0 +1,31 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { fixExitCode } = require('../src/commands/doctor');
+
+// `--fix` exit code: a CI gate runs `unbound doctor --fix` and reads the exit code.
+// It must be 0 only when the machine is actually clean after the repair.
+
+test('fixExitCode: spawn/signal error (null status) → 1', () => {
+  assert.equal(fixExitCode(null, false, false), 1);
+  assert.equal(fixExitCode(null, true, true), 1);
+});
+
+test('fixExitCode: setup failure propagates its status', () => {
+  assert.equal(fixExitCode(2, false, false), 2);
+  assert.equal(fixExitCode(1, true, true), 1);
+});
+
+test('fixExitCode: non-root, user tools fixed but MDM still tampered → 1 (not clean)', () => {
+  assert.equal(fixExitCode(0, false, true), 1);
+});
+
+test('fixExitCode: non-root, nothing org-managed left → 0 (clean)', () => {
+  assert.equal(fixExitCode(0, false, false), 0);
+});
+
+test('fixExitCode: root run repaired the MDM tools too → 0 (clean, no false failure)', () => {
+  // Regression guard: sudo `--fix` reinstalls MDM tools, so a status-0 run is clean
+  // even though mdmRemaining was true going in.
+  assert.equal(fixExitCode(0, true, true), 0);
+});

package/test/onboard-scope.test.js

@@ -0,0 +1,114 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { Command } = require('commander');
+
+// WEB-4757: scope is auto-detected from sudo/root. These tests verify the
+// permission primitive (hasRootPrivileges) and that `onboard` actually routes
+// to the MDM bundle when root and the user bundle when not — without touching
+// the network or running any setup script (all downstream deps are stubbed).
+
+// ---- 1. The sudo permission check itself ----
+test('hasRootPrivileges: true when effective uid is 0 (sudo/root)', () => {
+  delete require.cache[require.resolve('../src/commands/setup')];
+  const setup = require('../src/commands/setup');
+  const orig = process.getuid;
+  try {
+    process.getuid = () => 0;
+    assert.equal(setup.hasRootPrivileges(), true);
+  } finally {
+    process.getuid = orig;
+  }
+});
+
+test('hasRootPrivileges: false when effective uid is not 0 (no sudo)', () => {
+  delete require.cache[require.resolve('../src/commands/setup')];
+  const setup = require('../src/commands/setup');
+  const orig = process.getuid;
+  try {
+    process.getuid = () => 1000;
+    assert.equal(setup.hasRootPrivileges(), false);
+  } finally {
+    process.getuid = orig;
+  }
+});
+
+// ---- 2. onboard routes by detected scope ----
+// Reloads the module graph with stubbed deps so we can observe which bundle
+// helper the single `onboard` command invokes.
+async function runOnboard(isRoot, { setCron = false } = {}) {
+  for (const m of [
+    '../src/commands/onboard',
+    '../src/commands/setup',
+    '../src/commands/discover',
+    '../src/auth',
+    '../src/config',
+    '../src/output',
+    '../src/scheduled',
+  ]) {
+    delete require.cache[require.resolve(m)];
+  }
+
+  const calls = { mdm: 0, user: 0, discovery: 0, loggedIn: 0, cron: null };
+  const setup = require('../src/commands/setup');
+  const discover = require('../src/commands/discover');
+  const auth = require('../src/auth');
+  const config = require('../src/config');
+  const output = require('../src/output');
+  const scheduled = require('../src/scheduled');
+
+  setup.hasRootPrivileges = () => isRoot;
+  setup.runMdmSetupAllBundle = async () => { calls.mdm++; return { ok: true, skipped: [] }; };
+  setup.runSetupAllBundle = async () => { calls.user++; return { ok: true, skipped: [] }; };
+  discover.runDiscoveryScan = async () => { calls.discovery++; };
+  auth.ensureLoggedIn = async () => { calls.loggedIn++; };
+  scheduled.setupScheduledRun = async (o) => { calls.cron = o; };
+  config.setUrls = () => ({});
+  config.getApiKey = () => 'resolved-key';
+  config.getBaseUrl = () => 'https://b.acme';
+  config.getFrontendUrl = () => 'https://f.acme';
+  config.getGatewayUrl = () => 'https://g.acme';
+  config.isLoggedIn = () => true;
+  for (const k of ['info', 'success', 'error', 'warn']) output[k] = () => {};
+
+  const { register } = require('../src/commands/onboard');
+  const program = new Command();
+  program.exitOverride();
+  register(program);
+  const argv = ['node', 'unbound', 'onboard', '--api-key', 'k', '--discovery-key', 'd'];
+  if (setCron) argv.push('--set-cron');
+  await program.parseAsync(argv);
+  return calls;
+}
+
+test('onboard with sudo/root → installs the MDM bundle (all users), no login', async () => {
+  const calls = await runOnboard(true);
+  assert.equal(calls.mdm, 1, 'MDM bundle installed');
+  assert.equal(calls.user, 0, 'user bundle NOT installed');
+  assert.equal(calls.loggedIn, 0, 'MDM scope does not run ensureLoggedIn');
+  assert.equal(calls.discovery, 1, 'discovery still runs');
+});
+
+test('onboard without sudo → logs in and installs the user bundle', async () => {
+  const calls = await runOnboard(false);
+  assert.equal(calls.user, 1, 'user bundle installed');
+  assert.equal(calls.mdm, 0, 'MDM bundle NOT installed');
+  assert.equal(calls.loggedIn, 1, 'user scope runs ensureLoggedIn');
+  assert.equal(calls.discovery, 1, 'discovery still runs');
+});
+
+// --set-cron under sudo schedules discovery only (not a daily full MDM
+// re-install) and stores the discovery key, never the admin key.
+test('onboard --set-cron with sudo → schedules discovery-only with the discovery key', async () => {
+  const calls = await runOnboard(true, { setCron: true });
+  assert.ok(calls.cron, 'a scheduled run was set up');
+  assert.equal(calls.cron.command, 'discover', 'schedules discover, not full onboard');
+  assert.equal(calls.cron.apiKey, 'd', 'uses the discovery key, not the admin key');
+  assert.equal(calls.cron.discoveryKey, undefined, 'no separate admin/discovery key passed');
+});
+
+test('onboard --set-cron without sudo → schedules the full onboard run', async () => {
+  const calls = await runOnboard(false, { setCron: true });
+  assert.ok(calls.cron, 'a scheduled run was set up');
+  assert.equal(calls.cron.command, 'onboard', 'user scope keeps the full onboard cron');
+  assert.equal(calls.cron.discoveryKey, 'd', 'discovery key forwarded for the onboard cron');
+});