unbound-cli 0.9.3 → 0.9.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "0.9.3",
+  "version": "0.9.7",
   "description": "CLI tool for Unbound - AI Gateway management",
   "main": "src/index.js",
   "bin": {

package/src/commands/discover.js

@@ -9,6 +9,18 @@ const output = require('../output');
 const DISCOVER_BASE_URL = 'https://raw.githubusercontent.com/websentry-ai/coding-discovery-tool/refs/heads/main';
 const LAUNCH_AGENT_LABEL = 'ai.getunbound.discovery';
 
+// install.sh exits with this code when the OS isn't supported for discovery
+// (e.g. Linux). Treated as a skipped scan, not a failure.
+const DISCOVERY_EXIT_UNSUPPORTED_OS = 3;
+
+// Classifies a discovery subprocess exit code:
+// 'success' (scan ran), 'unsupported' (skipped on this OS), or 'failure'.
+function classifyDiscoveryExit(code) {
+  if (code === 0) return 'success';
+  if (code === DISCOVERY_EXIT_UNSUPPORTED_OS) return 'unsupported';
+  return 'failure';
+}
+
 // Native Windows (cmd/PowerShell) takes the install.ps1 path below. WSL reports
 // as Linux via process.platform and keeps using the existing bash install.sh pipe.
 function isWindowsNative() {
@@ -71,11 +83,15 @@ function runDiscoveryScript(scriptName, args) {
     const child = spawn(cmd, { shell: true, stdio: 'inherit' });
 
     child.on('close', (code) => {
-      if (code === 0) {
-        resolve();
-      } else {
+      const result = classifyDiscoveryExit(code);
+      if (result === 'failure') {
         reject(new Error(`Discovery script failed with exit code ${code}`));
+        return;
       }
+      if (result === 'unsupported') {
+        output.warn('AI tool discovery is not supported on this operating system. Skipping the scan — the Unbound CLI works normally.');
+      }
+      resolve();
     });
 
     child.on('error', reject);
@@ -129,8 +145,15 @@ async function runDiscoveryScriptWindows(scriptName, args) {
         { stdio: 'inherit', shell: false, windowsHide: true }
       );
       child.on('close', (code) => {
-        if (code === 0) resolve();
-        else reject(new Error(`Discovery script failed with exit code ${code}`));
+        const result = classifyDiscoveryExit(code);
+        if (result === 'failure') {
+          reject(new Error(`Discovery script failed with exit code ${code}`));
+          return;
+        }
+        if (result === 'unsupported') {
+          output.warn('AI tool discovery is not supported on this operating system. Skipping the scan — the Unbound CLI works normally.');
+        }
+        resolve();
       });
       child.on('error', reject);
     });
@@ -160,6 +183,21 @@ async function runDiscoveryScan({ apiKey, domain }) {
   await runDiscoveryScript('install.sh', args);
 }
 
+/**
+ * Installs the recurring 12-hour discovery LaunchAgent (macOS only) via
+ * setup-scheduled-scan.sh. Extracted so `unbound onboard --cron` reuses the
+ * exact same scheduling path as `unbound discover schedule`. The scheduled job
+ * runs the discovery scan only — it never runs tool setup or --backfill.
+ */
+async function runDiscoverySchedule({ apiKey, domain }) {
+  if (!apiKey) {
+    throw new Error('Discovery API key is required.');
+  }
+  const resolvedDomain = domain || config.getBaseUrl();
+  const args = `--api-key ${shellEscape(apiKey)} --domain ${shellEscape(resolvedDomain)}`;
+  await runDiscoveryScript('setup-scheduled-scan.sh', args);
+}
+
 function register(program) {
   const discover = program
     .command('discover')
@@ -243,9 +281,7 @@ Examples:
           return;
         }
 
-        const domain = opts.domain || config.getBaseUrl();
-        const args = `--api-key ${shellEscape(opts.apiKey)} --domain ${shellEscape(domain)}`;
-        await runDiscoveryScript('setup-scheduled-scan.sh', args);
+        await runDiscoverySchedule({ apiKey: opts.apiKey, domain: opts.domain });
       } catch (err) {
         output.error(err.message);
         process.exitCode = 1;
@@ -326,4 +362,4 @@ Examples:
     });
 }
 
-module.exports = { register, runDiscoveryScan };
+module.exports = { register, runDiscoveryScan, runDiscoverySchedule, classifyDiscoveryExit };

package/src/commands/onboard.js

@@ -3,7 +3,7 @@ const config = require('../config');
 const output = require('../output');
 const { ensureLoggedIn } = require('../auth');
 const { runSetupAllBundle, runMdmSetupAllBundle, checkRoot, ALL_TOOLS, MDM_ALL_TOOLS } = require('./setup');
-const { runDiscoveryScan } = require('./discover');
+const { runDiscoveryScan, runDiscoverySchedule } = require('./discover');
 
 /**
  * Builds the recovery-command suffix for partial-failure hints.
@@ -27,6 +27,7 @@ function register(program) {
     .requiredOption('--discovery-key <key>', 'Discovery API key (for device scan)')
     .option('--domain <url>', 'Backend URL for discovery (defaults to configured backend)')
     .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (Cursor skipped automatically)')
+    .option('--cron', 'Set up a recurring 12-hour discovery scan instead of a one-time scan (macOS only)')
     .addOption(new Option('--backend-url <url>', 'Override backend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--frontend-url <url>', 'Override frontend URL for setup scripts (dev only)').hideHelp())
     .addOption(new Option('--gateway-url <url>', 'Override gateway URL for setup scripts (dev only)').hideHelp())
@@ -34,7 +35,8 @@ function register(program) {
 Runs the full onboarding flow for an end user:
   1. Logs in with --api-key and stores credentials.
   2. Installs the default tool bundle: ${ALL_TOOLS.join(', ')}.
-  3. Runs device discovery with --discovery-key.
+  3. Runs device discovery with --discovery-key. With --cron, sets up a
+     recurring 12-hour discovery scan (macOS only) instead of a one-time scan.
 
 The user API key and discovery API key are separate keys obtained from
 different parts of the Unbound dashboard. Discovery uses its own key
@@ -48,6 +50,7 @@ For admin device enrollment via MDM, use \`unbound onboard-mdm\` instead.
 Examples:
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
   $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --backfill
+  $ unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY> --cron
   $ sudo unbound onboard --api-key <USER_KEY> --discovery-key <DISCOVERY_KEY>
 `)
     .action(async (opts) => {
@@ -90,7 +93,13 @@ Examples:
         console.log('');
         output.info('Step 2/2: Running device discovery');
         console.log('');
-        await runDiscoveryScan({ apiKey: opts.discoveryKey, domain: discoveryDomain });
+        if (opts.cron && process.platform === 'darwin') {
+          // --cron sets up the recurring 12-hour scan, which also scans now.
+          await runDiscoverySchedule({ apiKey: opts.discoveryKey, domain: discoveryDomain });
+        } else {
+          if (opts.cron) output.warn('--cron is macOS-only; running a one-time scan instead.');
+          await runDiscoveryScan({ apiKey: opts.discoveryKey, domain: discoveryDomain });
+        }
 
         console.log('');
         output.success('Onboarding complete');
@@ -98,8 +107,13 @@ Examples:
         if (!err.displayed) output.error(err.message);
         if (setupSucceeded) {
           const suffix = domainHintSuffix(discoveryDomain);
+          // Point at the path the user actually wanted: the scheduler when
+          // --cron was used on macOS, otherwise the one-time scan.
+          const retryCmd = opts.cron && process.platform === 'darwin'
+            ? `unbound discover schedule --api-key <DISCOVERY_KEY>${suffix}`
+            : `unbound discover --api-key <DISCOVERY_KEY>${suffix}`;
           console.error('  Tool setup completed successfully — only discovery failed.');
-          console.error(`  Re-run discovery only with: unbound discover --api-key <DISCOVERY_KEY>${suffix}`);
+          console.error(`  Re-run discovery only with: ${retryCmd}`);
         }
         process.exitCode = 1;
       }

package/src/commands/setup.js

@@ -37,15 +37,15 @@ const MDM_TOOLS = {
 };
 
 // Default MDM tools for `unbound onboard-mdm` (subscription mode for Claude Code/Codex since only one can be active)
-const MDM_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription'];
+const MDM_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription', 'copilot'];
 
-// Tools for `unbound setup mdm --all` — same as the onboard-mdm bundle plus Copilot.
+// Tools for `unbound setup mdm --all` — identical to MDM_ALL_TOOLS today; split kept for future flexibility.
 const MDM_SETUP_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'gemini-cli', 'codex-subscription', 'copilot'];
 
-// Default tools for `unbound onboard` (Cursor, Claude Code hooks, Codex hooks; no Gemini CLI).
-const ALL_TOOLS = ['cursor', 'claude-code-subscription', 'codex-subscription'];
+// Default tools for `unbound onboard` (Cursor, Claude Code hooks, Codex hooks, Copilot hooks; no Gemini CLI).
+const ALL_TOOLS = ['cursor', 'claude-code-subscription', 'codex-subscription', 'copilot'];
 
-// Tools for `unbound setup --all` — same as the onboard bundle plus Copilot.
+// Tools for `unbound setup --all` — identical to ALL_TOOLS today; split kept for future flexibility.
 const SETUP_ALL_TOOLS = ['cursor', 'claude-code-subscription', 'codex-subscription', 'copilot'];
 
 // Tool name → script mapping for automated tools
@@ -221,13 +221,15 @@ async function runPythonScriptWindows(scriptPath, args, { capture }) {
  * have no browser-auth flow.
  */
 function buildScriptArgs(apiKey, { backendUrl, frontendUrl, gatewayUrl, clear, mdm, backfill } = {}) {
-  let args = `--api-key ${shellEscape(apiKey)}`;
+  // --clear runs no auth in the Python scripts, so the key may be absent. Omit
+  // the flag entirely rather than passing --api-key 'undefined'.
+  let args = apiKey ? `--api-key ${shellEscape(apiKey)}` : '';
   if (backendUrl) args += ` --backend-url ${shellEscape(backendUrl)}`;
   if (gatewayUrl) args += ` --gateway-url ${shellEscape(gatewayUrl)}`;
   if (!mdm && frontendUrl) args += ` --domain ${shellEscape(frontendUrl)}`;
   if (clear) args += ' --clear';
   if (backfill) args += ' --backfill';
-  return args;
+  return args.trim();
 }
 
 // Backfill only applies to the hooks variants of Claude Code / Codex; gateway
@@ -346,7 +348,7 @@ function register(program) {
       'Run with no arguments for interactive setup, or specify tools directly.'
     )
     .option('--api-key <key>', 'Authenticate with an API key (skips browser login)')
-    .option('--clear', 'Remove Unbound configuration for the specified tools')
+    .option('--clear', 'Remove Unbound configuration for the specified tools (no login or API key required)')
     .option('--subscription', 'Use subscription mode for Claude Code / Codex (hooks only)')
     .option('--gateway', 'Use gateway mode for Claude Code / Codex (Unbound as AI provider)')
     .option('--all', 'Set up the default bundle: Cursor, Copilot, Claude Code (hooks), Codex (hooks)')
@@ -393,17 +395,19 @@ Examples:
   $ unbound setup cursor claude-code-gateway --api-key <key>
                                                            Login + set up multiple tools
 
-  Remove configuration:
+  Remove configuration (no login or API key required):
   $ unbound setup cursor --clear                           Remove Cursor config
   $ unbound setup copilot --clear                          Remove GitHub Copilot config
-  $ unbound setup claude-code --clear                      Remove Claude Code config
+  $ unbound setup claude-code --clear                      Remove BOTH Claude Code modes (subscription + gateway)
+  $ unbound setup codex --clear                            Remove BOTH Codex modes (subscription + gateway)
 
   Interactive:
   $ unbound setup                                          Select tools interactively
   $ unbound setup --api-key <key>                          Login, then select interactively
 
-If not logged in and --api-key is not provided, the browser will open
-automatically to authenticate before proceeding.
+When setting up, if you are not logged in and --api-key is not provided, the
+browser opens automatically to authenticate first. Clearing (--clear) never
+requires authentication.
 `)
     .action(async (tools, opts) => {
       try {
@@ -421,11 +425,15 @@ automatically to authenticate before proceeding.
         const frontendUrl = written.frontend_url || config.getFrontendUrl();
         const gatewayUrl = written.gateway_url || config.getGatewayUrl();
 
-        await ensureLoggedIn({
-          apiKey: opts.apiKey,
-          baseUrl: written.base_url,
-          frontendUrl: written.frontend_url,
-        });
+        // Clearing config needs no credentials — the setup scripts remove
+        // files without calling the API — so don't force a login for --clear.
+        if (!opts.clear) {
+          await ensureLoggedIn({
+            apiKey: opts.apiKey,
+            baseUrl: written.base_url,
+            frontendUrl: written.frontend_url,
+          });
+        }
         const apiKey = config.getApiKey();
         const urlOpts = { backendUrl, frontendUrl, gatewayUrl };
 
@@ -493,30 +501,33 @@ automatically to authenticate before proceeding.
           return;
         }
 
-        // Validate mutual exclusivity
-        if (tools.includes('claude-code-subscription') && tools.includes('claude-code-gateway')) {
-          output.error('Cannot set up both claude-code-subscription and claude-code-gateway. Choose one.');
-          process.exitCode = 1;
-          return;
-        }
-        if (tools.includes('codex-subscription') && tools.includes('codex-gateway')) {
-          output.error('Cannot set up both codex-subscription and codex-gateway. Choose one.');
-          process.exitCode = 1;
-          return;
-        }
+        // Mode mutual-exclusivity only applies when setting up — clearing both
+        // modes at once is valid (and is what bare claude-code/codex --clear does).
+        if (!opts.clear) {
+          if (tools.includes('claude-code-subscription') && tools.includes('claude-code-gateway')) {
+            output.error('Cannot set up both claude-code-subscription and claude-code-gateway. Choose one.');
+            process.exitCode = 1;
+            return;
+          }
+          if (tools.includes('codex-subscription') && tools.includes('codex-gateway')) {
+            output.error('Cannot set up both codex-subscription and codex-gateway. Choose one.');
+            process.exitCode = 1;
+            return;
+          }
 
-        // Validate no bare + suffixed name conflicts
-        if (tools.includes('claude-code') && (tools.includes('claude-code-subscription') || tools.includes('claude-code-gateway'))) {
-          output.error('Cannot combine claude-code with claude-code-subscription or claude-code-gateway.');
-          console.error('  Use --subscription or --gateway with claude-code, or use the explicit name directly.');
-          process.exitCode = 1;
-          return;
-        }
-        if (tools.includes('codex') && (tools.includes('codex-subscription') || tools.includes('codex-gateway'))) {
-          output.error('Cannot combine codex with codex-subscription or codex-gateway.');
-          console.error('  Use --subscription or --gateway with codex, or use the explicit name directly.');
-          process.exitCode = 1;
-          return;
+          // Validate no bare + suffixed name conflicts
+          if (tools.includes('claude-code') && (tools.includes('claude-code-subscription') || tools.includes('claude-code-gateway'))) {
+            output.error('Cannot combine claude-code with claude-code-subscription or claude-code-gateway.');
+            console.error('  Use --subscription or --gateway with claude-code, or use the explicit name directly.');
+            process.exitCode = 1;
+            return;
+          }
+          if (tools.includes('codex') && (tools.includes('codex-subscription') || tools.includes('codex-gateway'))) {
+            output.error('Cannot combine codex with codex-subscription or codex-gateway.');
+            console.error('  Use --subscription or --gateway with codex, or use the explicit name directly.');
+            process.exitCode = 1;
+            return;
+          }
         }
 
         // Validate --subscription/--gateway only with tools that need them
@@ -623,7 +634,9 @@ automatically to authenticate before proceeding.
 
   // --- MDM setup ---
 
-  const mdmToolNames = Object.keys(MDM_TOOLS).join(', ');
+  // Bare claude-code/codex are accepted too: with --clear they remove both
+  // modes; for setup they default to subscription (MDM has no mode prompt).
+  const mdmToolNames = [...Object.keys(MDM_TOOLS), 'claude-code', 'codex'].join(', ');
 
   setup
     .command('mdm')
@@ -632,31 +645,38 @@ automatically to authenticate before proceeding.
       'Used by organization admins to enroll devices via MDM.'
     )
     .argument('[tools...]', 'Tools to set up: ' + mdmToolNames)
-    .requiredOption('--admin-api-key <key>', 'Admin API key for MDM enrollment')
-    .option('--clear', 'Remove Unbound configuration for the specified tools')
+    .option('--admin-api-key <key>', 'Admin API key for MDM enrollment (not required with --clear)')
+    .option('--clear', 'Remove Unbound configuration for the specified tools (no API key required)')
     .option('--all', 'Set up all available tools')
-    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor unsupported)')
+    .option('--backfill', 'Seed historical Claude Code / Codex sessions from local transcripts into Unbound analytics (subscription/hooks mode only; Cursor and Copilot unsupported)')
     .addHelpText('after', `
 Available tools:
   cursor                    Cursor IDE
   copilot                   GitHub Copilot
   claude-code-subscription  Claude Code with your own subscription (hooks only)
   claude-code-gateway       Claude Code with Unbound as AI provider
+  claude-code               Both Claude Code modes (clears both; sets up subscription)
   gemini-cli                Gemini CLI
   codex-subscription        Codex with your own subscription (hooks only)
   codex-gateway             Codex with Unbound as AI provider
+  codex                     Both Codex modes (clears both; sets up subscription)
 
-Note: claude-code-subscription and claude-code-gateway are mutually exclusive.
-      codex-subscription and codex-gateway are mutually exclusive.
-When using --all, subscription mode is used by default for Claude Code and Codex.
+Note: claude-code-subscription and claude-code-gateway are mutually exclusive when
+      setting up; same for codex. Bare claude-code/codex set up subscription mode.
+      When using --all, subscription mode is used by default for Claude Code and Codex.
 
-Examples:
+Setup examples (require --admin-api-key):
   $ sudo unbound setup mdm --admin-api-key KEY cursor
   $ sudo unbound setup mdm --admin-api-key KEY cursor claude-code-subscription codex-subscription
   $ sudo unbound setup mdm --admin-api-key KEY --all
-  $ sudo unbound setup mdm --admin-api-key KEY --clear cursor codex-subscription
   $ sudo unbound setup mdm --admin-api-key KEY claude-code-subscription --backfill
                                                            Install hooks AND backfill local history
+
+Clear examples (no API key required):
+  $ sudo unbound setup mdm --clear cursor
+  $ sudo unbound setup mdm --clear claude-code              Clears BOTH Claude Code modes
+  $ sudo unbound setup mdm --clear codex                    Clears BOTH Codex modes
+  $ sudo unbound setup mdm --clear --all                    Clears every tool
 `)
     .action(async (tools, opts, command) => {
       try {
@@ -665,6 +685,13 @@ Examples:
         // --backend-url, --frontend-url, --gateway-url are defined only on the parent `setup` command.
         // Use optsWithGlobals() so they all work regardless of position relative to `mdm`.
         const globalOpts = command.optsWithGlobals();
+        // Clearing removes config without calling the API, so a key is only
+        // required when actually enrolling tools.
+        if (!globalOpts.clear && !opts.adminApiKey) {
+          output.error('--admin-api-key is required to set up tools.');
+          process.exitCode = 1;
+          return;
+        }
         // Persist URLs first so this MDM run wires tools at the new tenant
         // and any subsequent non-MDM command on the same machine inherits.
         // Prefer just-persisted values over env-var-aware getters so a stale
@@ -684,7 +711,9 @@ Examples:
 
         let toolNames;
         if (globalOpts.all) {
-          toolNames = MDM_SETUP_ALL_TOOLS;
+          // --clear --all wipes every tool, including both Claude Code/Codex modes.
+          // Setup --all uses the subscription-default bundle (can't enroll both modes).
+          toolNames = globalOpts.clear ? Object.keys(MDM_TOOLS) : MDM_SETUP_ALL_TOOLS;
         } else if (tools.length > 0) {
           toolNames = tools;
         } else {
@@ -694,6 +723,14 @@ Examples:
           return;
         }
 
+        // Expand bare claude-code/codex (MDM has no interactive mode prompt):
+        // --clear removes both modes; setup defaults to subscription, matching --all.
+        toolNames = [...new Set(toolNames.flatMap(name => {
+          const mode = MODE_TOOLS[name];
+          if (!mode) return [name];
+          return globalOpts.clear ? [mode.subscription, mode.gateway] : [mode.subscription];
+        }))];
+
         const invalid = toolNames.filter(t => !MDM_TOOLS[t]);
         if (invalid.length > 0) {
           output.error(`Unknown tool(s): ${invalid.join(', ')}`);
@@ -702,16 +739,20 @@ Examples:
           return;
         }
 
-        if (toolNames.includes('claude-code-subscription') && toolNames.includes('claude-code-gateway')) {
-          output.error('Cannot use both claude-code-subscription and claude-code-gateway. Choose one.');
-          process.exitCode = 1;
-          return;
-        }
+        // Mode mutual-exclusivity only applies when setting up — clearing both
+        // modes at once is valid (and is what bare claude-code/codex --clear does).
+        if (!globalOpts.clear) {
+          if (toolNames.includes('claude-code-subscription') && toolNames.includes('claude-code-gateway')) {
+            output.error('Cannot use both claude-code-subscription and claude-code-gateway. Choose one.');
+            process.exitCode = 1;
+            return;
+          }
 
-        if (toolNames.includes('codex-subscription') && toolNames.includes('codex-gateway')) {
-          output.error('Cannot use both codex-subscription and codex-gateway. Choose one.');
-          process.exitCode = 1;
-          return;
+          if (toolNames.includes('codex-subscription') && toolNames.includes('codex-gateway')) {
+            output.error('Cannot use both codex-subscription and codex-gateway. Choose one.');
+            process.exitCode = 1;
+            return;
+          }
         }
 
         const resolvedTools = toolNames.map(name => ({ name, ...MDM_TOOLS[name] }));
@@ -749,7 +790,7 @@ Examples:
 }
 
 /**
- * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks) with spinners.
+ * Runs the user-level default bundle (Cursor, Claude Code hooks, Codex hooks, Copilot hooks) with spinners.
  * Assumes the caller has already ensured the user is logged in.
  * Returns true on success, false on failure.
  */
@@ -774,7 +815,7 @@ async function runSetupAllBundle(apiKey, { backendUrl, frontendUrl, gatewayUrl,
 }
 
 /**
- * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks) with spinners.
+ * Runs the MDM default bundle (Cursor, Claude Code hooks, Gemini CLI, Codex hooks, Copilot hooks) with spinners.
  * Caller must ensure the process is running as root.
  * Returns true on success, false on failure.
  */
@@ -801,4 +842,5 @@ module.exports = {
   checkRoot,
   ALL_TOOLS,
   MDM_ALL_TOOLS,
+  buildScriptArgs,
 };

package/test/discover-exit-code.test.js

@@ -0,0 +1,21 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { classifyDiscoveryExit } = require('../src/commands/discover');
+
+test('classifyDiscoveryExit: 0 is a successful scan', () => {
+  assert.equal(classifyDiscoveryExit(0), 'success');
+});
+
+test('classifyDiscoveryExit: 3 is an unsupported-OS skip, not a failure', () => {
+  assert.equal(classifyDiscoveryExit(3), 'unsupported');
+});
+
+test('classifyDiscoveryExit: other non-zero codes are failures', () => {
+  assert.equal(classifyDiscoveryExit(1), 'failure');
+  assert.equal(classifyDiscoveryExit(2), 'failure');
+  assert.equal(classifyDiscoveryExit(127), 'failure');
+});
+
+test('classifyDiscoveryExit: null (process killed by signal) is a failure', () => {
+  assert.equal(classifyDiscoveryExit(null), 'failure');
+});

package/test/onboard-cron.test.js

@@ -0,0 +1,122 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const discover = require('../src/commands/discover');
+
+const DISCOVER_SRC_PATH = path.join(__dirname, '..', 'src', 'commands', 'discover.js');
+const ONBOARD_SRC_PATH = path.join(__dirname, '..', 'src', 'commands', 'onboard.js');
+
+const discoverSrc = fs.readFileSync(DISCOVER_SRC_PATH, 'utf8');
+const onboardSrc = fs.readFileSync(ONBOARD_SRC_PATH, 'utf8');
+
+// Extracts the textual body of a top-level `async function <name>(...) { ... }`
+// by brace-matching from the function keyword. Lets us assert on a single
+// function's body without false positives from the rest of the file.
+function extractFunctionBody(src, name) {
+  const start = src.indexOf(`async function ${name}`);
+  assert.notEqual(start, -1, `expected "async function ${name}" in source`);
+  // Skip the parameter list (which may itself contain destructuring braces)
+  // by finding the matching close-paren first, then the body's opening brace.
+  const paramOpen = src.indexOf('(', start);
+  let pDepth = 0;
+  let paramClose = -1;
+  for (let i = paramOpen; i < src.length; i++) {
+    if (src[i] === '(') pDepth++;
+    else if (src[i] === ')') {
+      pDepth--;
+      if (pDepth === 0) { paramClose = i; break; }
+    }
+  }
+  assert.notEqual(paramClose, -1, `unbalanced parens in ${name} signature`);
+  const open = src.indexOf('{', paramClose);
+  assert.notEqual(open, -1, `expected an opening brace after ${name}`);
+  let depth = 0;
+  for (let i = open; i < src.length; i++) {
+    if (src[i] === '{') depth++;
+    else if (src[i] === '}') {
+      depth--;
+      if (depth === 0) return src.slice(open, i + 1);
+    }
+  }
+  throw new Error(`unbalanced braces while extracting ${name}`);
+}
+
+const scheduleBody = extractFunctionBody(discoverSrc, 'runDiscoverySchedule');
+
+test('runDiscoverySchedule is exported as a function', () => {
+  assert.equal(typeof discover.runDiscoverySchedule, 'function');
+});
+
+test('runDiscoverySchedule takes a single destructured options object', () => {
+  // One formal parameter: ({ apiKey, domain }). Arity counts that single object.
+  assert.equal(discover.runDiscoverySchedule.length, 1);
+  // Accepts exactly apiKey and domain — no third field could carry backfill.
+  assert.match(discoverSrc, /async function runDiscoverySchedule\(\{\s*apiKey,\s*domain\s*\}\)/);
+});
+
+test('the scheduled path runs setup-scheduled-scan.sh, never install.sh', () => {
+  assert.ok(
+    scheduleBody.includes("'setup-scheduled-scan.sh'"),
+    'runDiscoverySchedule must schedule setup-scheduled-scan.sh'
+  );
+  assert.ok(
+    !scheduleBody.includes('install.sh'),
+    'runDiscoverySchedule must not invoke install.sh'
+  );
+});
+
+// Core WEB-4499 regression guard: backfill is a one-time setup operation and
+// must be structurally impossible to reach the recurring scheduled scan.
+test('runDiscoverySchedule body contains no backfill reference', () => {
+  assert.ok(
+    !scheduleBody.toLowerCase().includes('backfill'),
+    'backfill must never appear in the scheduled-scan code path'
+  );
+});
+
+test('runDiscoverySchedule shell-escapes both apiKey and domain', () => {
+  // Both user-influenced values pass through shellEscape before hitting the
+  // shell:true spawn, so neither can break out of the command string.
+  assert.match(scheduleBody, /--api-key \$\{shellEscape\(apiKey\)\}/);
+  assert.match(scheduleBody, /--domain \$\{shellEscape\(resolvedDomain\)\}/);
+});
+
+// The onboard --cron path must call the shared schedule helper with only
+// apiKey + domain — never forwarding opts.backfill into the schedule.
+test('onboard schedules via runDiscoverySchedule with only apiKey and domain', () => {
+  assert.ok(
+    onboardSrc.includes('runDiscoverySchedule({ apiKey: opts.discoveryKey, domain: discoveryDomain })'),
+    'onboard must call runDiscoverySchedule with exactly { apiKey, domain }'
+  );
+});
+
+test('onboard never passes backfill into runDiscoverySchedule', () => {
+  // Find the runDiscoverySchedule call site in onboard and confirm its
+  // argument object carries no backfill key.
+  const callIdx = onboardSrc.indexOf('runDiscoverySchedule(');
+  assert.notEqual(callIdx, -1, 'expected a runDiscoverySchedule call in onboard');
+  const open = onboardSrc.indexOf('(', callIdx);
+  const close = onboardSrc.indexOf(')', open);
+  const callArgs = onboardSrc.slice(open, close + 1);
+  assert.ok(!callArgs.toLowerCase().includes('backfill'), callArgs);
+});
+
+test('runDiscoverySchedule is re-exported into onboard from discover', () => {
+  // onboard pulls the helper from ./discover rather than re-implementing it,
+  // so both the `discover schedule` command and `onboard --cron` share one path.
+  assert.match(
+    onboardSrc,
+    /const \{[^}]*runDiscoverySchedule[^}]*\} = require\('\.\/discover'\)/
+  );
+});
+
+test('runDiscoverySchedule rejects when apiKey is missing', async () => {
+  // Mirrors runDiscoveryScan's guard so a future caller can't silently send
+  // --api-key 'undefined' to the schedule script. Throws before any network.
+  await assert.rejects(
+    () => discover.runDiscoverySchedule({ domain: 'https://example.com' }),
+    /Discovery API key is required/
+  );
+});

package/test/setup-args.test.js

@@ -0,0 +1,85 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const { buildScriptArgs } = require('../src/commands/setup');
+
+// shellEscape single-quotes every value, so a real key surfaces as
+// --api-key '<key>' at the head of the argv tail.
+test('buildScriptArgs: real apiKey leads with single-quoted --api-key', () => {
+  const args = buildScriptArgs('sk-abc123', {});
+  assert.ok(args.startsWith("--api-key 'sk-abc123'"), args);
+});
+
+// WEB-4498 core behavior: --clear runs no auth, so a missing key must NOT
+// produce --api-key and must NOT leak the literal string "undefined".
+test('buildScriptArgs: clear without apiKey omits --api-key and never emits undefined', () => {
+  const args = buildScriptArgs(undefined, { clear: true });
+  assert.ok(!args.includes('--api-key'), args);
+  assert.ok(!args.includes('undefined'), args);
+  assert.ok(args.includes('--clear'), args);
+});
+
+// Empty-string key is falsy too — same omission rule applies.
+test('buildScriptArgs: clear with empty-string apiKey still omits --api-key', () => {
+  const args = buildScriptArgs('', { clear: true });
+  assert.ok(!args.includes('--api-key'), args);
+  assert.ok(!args.includes('undefined'), args);
+  assert.ok(args.includes('--clear'), args);
+});
+
+// With no key, the first appended flag must not leave a leading space —
+// the result is trimmed and carries the URL flags plus --clear.
+test('buildScriptArgs: clear without key + URLs is trimmed and carries url flags', () => {
+  const args = buildScriptArgs(undefined, {
+    clear: true,
+    backendUrl: 'https://backend.acme.com',
+    gatewayUrl: 'https://gateway.acme.com',
+  });
+  assert.equal(args, args.trim());
+  assert.ok(!args.startsWith(' '), args);
+  assert.ok(args.includes('--backend-url'), args);
+  assert.ok(args.includes('--gateway-url'), args);
+  assert.ok(args.includes('--clear'), args);
+});
+
+test('buildScriptArgs: clear:true appends --clear', () => {
+  const args = buildScriptArgs('sk-x', { clear: true });
+  assert.ok(args.includes('--clear'), args);
+});
+
+test('buildScriptArgs: backfill:true appends --backfill', () => {
+  const args = buildScriptArgs('sk-x', { backfill: true });
+  assert.ok(args.includes('--backfill'), args);
+});
+
+// MDM scripts have no browser-auth flow, so --domain (frontend URL) is
+// suppressed even when a frontendUrl is supplied.
+test('buildScriptArgs: mdm:true suppresses --domain even with frontendUrl', () => {
+  const args = buildScriptArgs('sk-x', {
+    mdm: true,
+    frontendUrl: 'https://gateway.acme.com',
+  });
+  assert.ok(!args.includes('--domain'), args);
+});
+
+test('buildScriptArgs: non-mdm includes --domain when frontendUrl passed', () => {
+  const args = buildScriptArgs('sk-x', {
+    mdm: false,
+    frontendUrl: 'https://gateway.acme.com',
+  });
+  assert.ok(args.includes("--domain 'https://gateway.acme.com'"), args);
+});
+
+// The result is always trimmed regardless of which flags are present.
+test('buildScriptArgs: result is always trimmed', () => {
+  const cases = [
+    ['sk-x', {}],
+    [undefined, { clear: true }],
+    ['', { clear: true, backendUrl: 'https://b.acme.com' }],
+    ['sk-x', { backfill: true, mdm: true, frontendUrl: 'https://f.acme.com' }],
+    [undefined, {}],
+  ];
+  for (const [key, opts] of cases) {
+    const args = buildScriptArgs(key, opts);
+    assert.equal(args, args.trim(), JSON.stringify([key, opts]));
+  }
+});