unbound-cli 1.9.0 → 1.10.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unbound-cli",
-  "version": "1.9.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/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]);
+});