unbound-cli 1.8.0 → 1.10.0

package/package.json

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

package/src/commands/policy.js

@@ -312,6 +312,34 @@ function parseFieldSpec(spec) {
   return [spec.slice(0, eq), spec.slice(eq + 1)];
 }
 
+// The `custom` command family has no match-against fields — its single condition is
+// the reserved `command` key, matched as ONE pattern against the whole raw command
+// regardless of the classified family. The families metadata reports it with
+// is_custom:true and no fields (mirrors the dashboard), so surface how to author it.
+const CUSTOM_FAMILY_NAME = 'custom';
+const CUSTOM_FAMILY_HINT =
+  "matches ONE pattern against the whole command (exact text, *wildcard*, or regex). " +
+  "Author it with --field command='<pattern>', e.g. --field command='make release-prod'.";
+
+// Indented detail lines shown under a family name in `policy tool families`. Pure so
+// the custom-family guidance is unit-testable. A custom family (is_custom) reports no
+// fields by design, so explain its single whole-command pattern instead of "(no fields)".
+function familyFieldLines(f) {
+  // Custom has no fields by design — return before touching f.fields so its shape is
+  // irrelevant for the custom branch.
+  if (f.is_custom) {
+    return [CUSTOM_FAMILY_HINT];
+  }
+  const fields = Array.isArray(f.fields) ? f.fields : Object.keys(f.fields || {});
+  if (fields.length === 0) {
+    return ['(no fields)'];
+  }
+  return fields.map((field) => {
+    const desc = (f.field_descriptions && f.field_descriptions[field]) || '';
+    return `${field}${desc ? ` — ${desc}` : ''}`;
+  });
+}
+
 // "ANY" is a wildcard across all fields; it can't be ANDed with other conditions.
 // Mirrors the backend rule so the CLI fails fast before the API call. The check is
 // case-insensitive so `--field Any=*`/`--field any=*` are caught too.
@@ -1433,8 +1461,8 @@ Subcommands:
     .option('--prompt <text>', 'Natural-language description; routes through Unbound AI assist. Mutually exclusive with --command-family/--field/--config. Compatible with --name/--description/--action overrides.')
     .option('--no-ai', 'Opt out of the AI-assist guard and use raw classification flags. Mutually exclusive with --prompt.')
     .option('--name <name>', 'Policy name (required unless --prompt is used)')
-    .option('--command-family <family>', 'Command family (e.g. git, filesystem, network). See `policy tool families`.')
-    .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable — multiple --field are ANDed (all must match), one per field, for a more specific policy. At least one required unless --config is used.', (val, prev = []) => [...prev, val])
+    .option('--command-family <family>', 'Command family (e.g. git, filesystem, network), or `custom` to match one pattern against the whole command. See `policy tool families`.')
+    .option('--field <key=pattern>', 'Match field: <key>=<pattern>. Repeatable — multiple --field are ANDed (all must match), one per field, for a more specific policy. At least one required unless --config is used. For the `custom` family the key is `command`.', (val, prev = []) => [...prev, val])
     .option('--action <action>', `Action to take: ${TOOL_ACTIONS.join(' | ')}`)
     .option('--description <text>', 'Human-readable description')
     .option('--custom-message <text>', 'Message shown to the user when the policy fires. Required when --action is BLOCK or WARN.')
@@ -1466,6 +1494,12 @@ Examples:
       --field operation=push --field branch=main --field remote='*origin*' \\
       --action BLOCK --custom-message "Pushing to main on origin is blocked."
 
+  # 'custom' family: one pattern matched against the WHOLE command (exact / *wildcard* / regex),
+  # regardless of the classified family. The field key is always 'command'.
+  $ unbound policy tool create-terminal --no-ai --name "Block prod release" \\
+      --command-family custom --field command='make release-prod' \\
+      --action BLOCK --custom-message "Prod releases go through CI."
+
 Discover valid command families and their fields: unbound policy tool families
 Learn more: ${DOCS_TOOL}
 `)
@@ -1558,12 +1592,18 @@ Learn more: ${DOCS_TOOL}
           throw new Error('Cannot combine --config with --field.');
         }
 
+        const isCustomFamily = (opts.commandFamily || '').toLowerCase() === CUSTOM_FAMILY_NAME;
+
         let configObj;
         if (opts.config) {
           configObj = parseJsonOrThrow(opts.config);
         } else {
           if (!opts.field || opts.field.length === 0) {
-            throw new Error('At least one --field <key>=<pattern> is required (or use --config).');
+            throw new Error(
+              isCustomFamily
+                ? `The 'custom' family ${CUSTOM_FAMILY_HINT}`
+                : 'At least one --field <key>=<pattern> is required (or use --config).'
+            );
           }
           configObj = {};
           for (const spec of opts.field) {
@@ -1874,14 +1914,8 @@ Learn more: ${DOCS_TOOL}
         for (const f of families) {
           console.log('');
           output.info(f.name);
-          const fields = Array.isArray(f.fields) ? f.fields : Object.keys(f.fields || {});
-          if (fields.length === 0) {
-            console.log('  (no fields)');
-          } else {
-            for (const field of fields) {
-              const desc = (f.field_descriptions && f.field_descriptions[field]) || '';
-              console.log(`  ${field}${desc ? ` — ${desc}` : ''}`);
-            }
+          for (const line of familyFieldLines(f)) {
+            console.log(`  ${line}`);
           }
           if (f.risk_level) console.log(`  risk: ${f.risk_level}`);
         }
@@ -2082,4 +2116,4 @@ Learn more: ${DOCS_POLICIES}
   registerLegacy(policy);
 }
 
-module.exports = { register, assertAnyExclusive };
+module.exports = { register, assertAnyExclusive, familyFieldLines, CUSTOM_FAMILY_HINT };

package/src/commands/setup.js

@@ -448,6 +448,45 @@ function removeBinaryInstall({
   return { removed, failed };
 }
 
+
+// Run the binary's own `unbound-hook clear` to deregister managed configs
+// (strip our hooks from shared configs, remove our scripts + per-tool logs)
+// BEFORE the install tree is deleted. Essential on binary-only machines that
+// have no python3 to run the downloaded per-tool clears, and authoritative for
+// binary installs generally — it reuses the same clear_setup() as the python
+// clears. Fail-open: never throws; returns { ran, ok }. `binaryPath`/`runner`
+// are overridable so tests stay hermetic.
+function runBinaryClear({
+  binaryPath = path.join(BINARY_INSTALL_PATHS.optDir, 'current', 'unbound-hook', 'unbound-hook'),
+  runner = spawnSync,
+} = {}) {
+  // lstatSync (not existsSync, which follows symlinks) so a present-but-broken
+  // `current/...` symlink is still detected — we attempt the clear and surface
+  // the failure instead of silently skipping it. A truly absent path (python-only
+  // install) throws → no-op.
+  let present = false;
+  try { fs.lstatSync(binaryPath); present = true; } catch (e) { present = false; }
+  if (!present) return { ran: false, ok: true };
+  try {
+    // timeout so a hung clear can never block nuke from removing the binary.
+    const r = runner(binaryPath, ['clear'], { stdio: 'pipe', timeout: 120000, killSignal: 'SIGKILL' });
+    if (r.error) {
+      const why = r.error.code === 'ETIMEDOUT' ? 'timed out (120s)' : r.error.message;
+      output.warn(`nuke: unbound-hook clear ${why}; continuing.`);
+      return { ran: true, ok: false };
+    }
+    if (r.status !== 0) {
+      const stderr = r.stderr ? r.stderr.toString().trim() : '';
+      output.warn(`nuke: unbound-hook clear exited ${r.status}: ${stderr || '(no stderr)'}`);
+      return { ran: true, ok: false };
+    }
+    return { ran: true, ok: true };
+  } catch (err) {
+    output.warn(`nuke: unbound-hook clear errored: ${err.message}`);
+    return { ran: true, ok: false };
+  }
+}
+
 /**
  * Returns true when the process has the privileges needed to touch system-level
  * (MDM) configuration. On Windows, `net session` succeeds only when elevated, so
@@ -1047,8 +1086,13 @@ Examples:
           // `_confirmProductionPaths` is the explicit "this is the real call site"
           // ack — the function refuses production defaults without it as a guard
           // against tests forgetting to override paths.
+          // Deregister managed configs via the binary's own clear FIRST (works
+          // without python3, which a binary-only machine lacks); reuses the same
+          // clear_setup() as the python clears. Must precede the rm below.
+          const binClear = runBinaryClear();
           const { removed: binaryRemoved, failed: bf } = removeBinaryInstall({ _confirmProductionPaths: true });
           binaryFailed = bf;
+          if (binClear.ran && !binClear.ok) binaryFailed.push('unbound-hook clear');
           if (binaryRemoved.length) {
             output.info(`Removed binary install: ${binaryRemoved.join('; ')}.`);
           }
@@ -1141,5 +1185,6 @@ module.exports = {
   clearUnboundEnvsEverywhere,
   NUKE_ENV_VARS,
   removeBinaryInstall,
+  runBinaryClear,
   BINARY_INSTALL_PATHS,
 };

package/test/policy-conditions.test.js

@@ -3,7 +3,7 @@
 const { test } = require('node:test');
 const assert = require('node:assert');
 
-const { assertAnyExclusive } = require('../src/commands/policy');
+const { assertAnyExclusive, familyFieldLines, CUSTOM_FAMILY_HINT } = require('../src/commands/policy');
 
 test('assertAnyExclusive: allows a single ANY condition', () => {
   assert.doesNotThrow(() => assertAnyExclusive({ ANY: '*' }));
@@ -26,3 +26,32 @@ test('assertAnyExclusive: tolerates empty/undefined config', () => {
   assert.doesNotThrow(() => assertAnyExclusive({}));
   assert.doesNotThrow(() => assertAnyExclusive(undefined));
 });
+
+// `policy tool families` must teach an agent how to author a custom policy: the
+// custom family reports is_custom + no fields, and must render the command-pattern
+// hint (not "(no fields)", which reads as "unusable").
+test('familyFieldLines: custom family shows the command-pattern hint, not "(no fields)"', () => {
+  const lines = familyFieldLines({ name: 'custom', is_custom: true, fields: [] });
+  assert.deepStrictEqual(lines, [CUSTOM_FAMILY_HINT]);
+  assert.match(lines[0], /--field command=/);
+  assert.match(lines[0], /exact text, \*wildcard\*, or regex/);
+});
+
+test('familyFieldLines: a normal family with fields lists field — description', () => {
+  const lines = familyFieldLines({
+    name: 'git_action',
+    fields: ['operation', 'branch'],
+    field_descriptions: { operation: 'push/pull/…', branch: 'branch name' },
+  });
+  assert.deepStrictEqual(lines, ['operation — push/pull/…', 'branch — branch name']);
+});
+
+test('familyFieldLines: a fieldless non-custom family still shows "(no fields)"', () => {
+  assert.deepStrictEqual(familyFieldLines({ name: 'misc', fields: [] }), ['(no fields)']);
+});
+
+test('familyFieldLines: custom returns the hint even with no/malformed fields property', () => {
+  // The is_custom guard fires before f.fields is read, so its shape is irrelevant.
+  assert.deepStrictEqual(familyFieldLines({ name: 'custom', is_custom: true }), [CUSTOM_FAMILY_HINT]);
+  assert.deepStrictEqual(familyFieldLines({ is_custom: true, fields: null }), [CUSTOM_FAMILY_HINT]);
+});

package/test/setup-args.test.js

@@ -3,7 +3,7 @@ const assert = require('node:assert/strict');
 const fs = require('fs');
 const os = require('os');
 const path = require('path');
-const { buildScriptArgs, scriptSupportsBackfill, resolveSetupAllTools, clearUnboundEnvsEverywhere, NUKE_ENV_VARS, removeBinaryInstall, BINARY_INSTALL_PATHS } = require('../src/commands/setup');
+const { buildScriptArgs, scriptSupportsBackfill, resolveSetupAllTools, clearUnboundEnvsEverywhere, NUKE_ENV_VARS, removeBinaryInstall, runBinaryClear, BINARY_INSTALL_PATHS } = 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.
@@ -396,3 +396,58 @@ test('removeBinaryInstall: refuses production-default paths without _confirmProd
 test('BINARY_INSTALL_PATHS: is frozen', () => {
   assert.ok(Object.isFrozen(BINARY_INSTALL_PATHS));
 });
+
+test('runBinaryClear: binary present — runs `<bin> clear` before removal, reports ok', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-binclear-'));
+  const bin = path.join(tmp, 'unbound-hook');
+  fs.writeFileSync(bin, '#');
+  const calls = [];
+  try {
+    const r = runBinaryClear({ binaryPath: bin, runner: (b, args, opts) => { calls.push([b, args, opts]); return { status: 0 }; } });
+    assert.deepEqual(r, { ran: true, ok: true });
+    assert.equal(calls.length, 1, 'binary clear should run exactly once');
+    assert.equal(calls[0][0], bin);
+    assert.deepEqual(calls[0][1], ['clear']);
+    assert.ok(calls[0][2].timeout > 0, 'clear must run with a timeout so a hang cannot block nuke');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('runBinaryClear: dangling binary symlink — still attempts (surfaces, not silently skipped)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-binclear-'));
+  const link = path.join(tmp, 'unbound-hook');
+  fs.symlinkSync(path.join(tmp, 'missing-target'), link); // dangling: target absent
+  let called = false;
+  try {
+    const r = runBinaryClear({ binaryPath: link, runner: () => { called = true; return { error: { code: 'ENOENT', message: 'spawn ENOENT' } }; } });
+    assert.equal(called, true, 'a dangling symlink must still be attempted, not treated as absent');
+    assert.deepEqual(r, { ran: true, ok: false });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('runBinaryClear: binary absent (python-only install) — no-op, runner never called', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-binclear-'));
+  let called = false;
+  try {
+    const r = runBinaryClear({ binaryPath: path.join(tmp, 'nope'), runner: () => { called = true; return { status: 0 }; } });
+    assert.deepEqual(r, { ran: false, ok: true });
+    assert.equal(called, false);
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+test('runBinaryClear: clear exits non-zero — fail-open (ran:true, ok:false), never throws', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'unbound-binclear-'));
+  const bin = path.join(tmp, 'unbound-hook');
+  fs.writeFileSync(bin, '#');
+  try {
+    const r = runBinaryClear({ binaryPath: bin, runner: () => ({ status: 1, stderr: Buffer.from('boom') }) });
+    assert.deepEqual(r, { ran: true, ok: false });
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});