unbound-cli 1.18.0 → 1.20.0

package/src/login-scope.js

@@ -0,0 +1,85 @@
+/**
+ * Scope flags for `unbound login`: what the minted login token may do and for how long.
+ * Parsed before the browser opens so a typo fails here, not after the round trip.
+ */
+const AREAS = ['analytics', 'logs', 'policies', 'configuration'];
+const LEVELS = ['none', 'view', 'edit'];
+const EXPIRY_DAYS = [7, 30, 60, 90];
+const ROLE_NAME_MAX_LENGTH = 64;
+
+// Built-in roles by their shell-friendly slug; custom role names pass through verbatim.
+const BUILTIN_ROLE_SLUGS = {
+  admin: 'Admin',
+  'analytics-viewer': 'Analytics Viewer',
+  manager: 'Manager',
+  member: 'Member',
+};
+
+const AREA_LABELS = { analytics: 'Analytics', logs: 'Logs', policies: 'Policies', configuration: 'Configuration' };
+
+function parsePermissions(raw) {
+  const permissions = Object.fromEntries(AREAS.map((area) => [area, 'none']));
+  for (const pair of String(raw).split(',')) {
+    const parts = pair.trim().split('=');
+    const [area, level] = parts;
+    if (parts.length !== 2 || !area || !level) throw new Error(`Invalid permissions entry "${pair.trim()}". Use area=level, e.g. analytics=view`);
+    if (!AREAS.includes(area)) throw new Error(`Unknown area "${area}". Areas: ${AREAS.join(', ')}`);
+    if (!LEVELS.includes(level)) throw new Error(`Unknown level "${level}" for ${area}. Levels: ${LEVELS.join(', ')}`);
+    if (area === 'logs' && level === 'edit') throw new Error('Logs has no edit level');
+    permissions[area] = level;
+  }
+  return permissions;
+}
+
+/**
+ * Turns the login flags into the query the dashboard reads. Returns {} when no flag was given.
+ * @param {{role?: string, permissions?: string, expiresInDays?: string|number}} opts
+ */
+function parseLoginScope(opts = {}) {
+  const query = {};
+  const role = typeof opts.role === 'string' ? opts.role.trim() : '';
+  const permissions = typeof opts.permissions === 'string' ? opts.permissions.trim() : '';
+  if (opts.role !== undefined && !role) throw new Error('--role must not be empty');
+  if (opts.permissions !== undefined && !permissions) throw new Error('--permissions must not be empty');
+  if (role && permissions) throw new Error('Use --role or --permissions, not both');
+  if (opts.expiresInDays !== undefined) {
+    const days = Number(opts.expiresInDays);
+    if (!EXPIRY_DAYS.includes(days)) throw new Error(`--expires-in-days must be one of ${EXPIRY_DAYS.join(', ')}`);
+    query.expires_in_days = String(days);
+  }
+  if (role) {
+    const slug = role.toLowerCase();
+    const name = Object.hasOwn(BUILTIN_ROLE_SLUGS, slug) ? BUILTIN_ROLE_SLUGS[slug] : role;
+    if (name.length > ROLE_NAME_MAX_LENGTH) throw new Error(`Unknown role "${role}"`);
+    query.role = name;
+  } else if (permissions) {
+    const map = parsePermissions(permissions);
+    query.permissions = AREAS.filter((a) => map[a] !== 'none').map((a) => `${a}=${map[a]}`).join(',');
+    if (!query.permissions) throw new Error('--permissions grants no access');
+  }
+  return query;
+}
+
+/** True when any login flag was given, so a dashboard that echoes no `scope` must have ignored it. */
+function isScoped(query) {
+  return Object.keys(query).length > 0;
+}
+
+/** "Analytics view, Logs view" from a permissions map, or "full access" for null. */
+function formatPermissions(permissions) {
+  if (!permissions || typeof permissions !== 'object') return 'full access';
+  const granted = AREAS.filter((a) => permissions[a] && permissions[a] !== 'none')
+    .map((a) => `${AREA_LABELS[a]} ${permissions[a]}`);
+  return granted.length ? granted.join(', ') : 'no access';
+}
+
+/** One line describing the token the privileges call reports, or null when the caller is not a CLI token. */
+function describeToken(privileges) {
+  const token = privileges && privileges.cli_token;
+  if (!token || typeof token !== 'object') return null;
+  const parts = [token.name, formatPermissions(token.permissions)];
+  if (token.expires_at) parts.push(`expires ${String(token.expires_at).slice(0, 10)}`);
+  return parts.filter(Boolean).join(' · ');
+}
+
+module.exports = { parseLoginScope, isScoped, formatPermissions, describeToken, BUILTIN_ROLE_SLUGS, EXPIRY_DAYS };

package/test/auth-server-leak.test.js

@@ -1,6 +1,7 @@
 const { test } = require('node:test');
 const assert = require('node:assert/strict');
 const http = require('http');
+const os = require('os');
 const { URL } = require('url');
 
 // WEB-4941, root cause #1: loginWithBrowser's local callback server leaked a
@@ -105,8 +106,11 @@ test('loginWithBrowser: success path resolves, sets Connection: close, and stops
     let successHeaders;
     let successSocket;
 
+    let authParams;
+
     const fakeOpen = async (authUrl) => {
-      port = Number(new URL(new URL(authUrl).searchParams.get('callback_url')).port);
+      authParams = new URL(authUrl).searchParams;
+      port = Number(new URL(authParams.get('callback_url')).port);
       const res = await getKeepAlive(agent, buildSuccessCallback(authUrl));
       successHeaders = res.headers;
       successSocket = res.socket;
@@ -120,6 +124,9 @@ test('loginWithBrowser: success path resolves, sets Connection: close, and stops
       );
 
       assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme' });
+      // The dashboard names this machine's login token after `machine`, so a re-login replaces it.
+      assert.equal(authParams.get('app_type'), 'cli');
+      assert.equal(authParams.get('machine'), os.hostname());
       assert.equal(successHeaders.connection, 'close', 'success response must set Connection: close');
 
       // The leak-proof: the held keep-alive socket is actually closed by the

package/test/login-scope-callback.test.js

@@ -0,0 +1,79 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+const http = require('http');
+const { URL } = require('url');
+
+// The browser round trip for a scoped login: the flags ride on the auth URL, the dashboard's
+// `scope=` echo comes back on success, and its `error=` reason is what the user sees on failure.
+
+const auth = require('../src/auth');
+const config = require('../src/config');
+
+function get(url) {
+  return new Promise((resolve, reject) => {
+    http.get(url, (res) => {
+      let body = '';
+      res.on('data', (chunk) => { body += chunk; });
+      res.on('end', () => resolve({ statusCode: res.statusCode, body }));
+    }).on('error', reject);
+  });
+}
+
+function withStubbedConfig(fn) {
+  const saved = { setApiKey: config.setApiKey, writeConfig: config.writeConfig, readConfig: config.readConfig };
+  config.setApiKey = () => {};
+  config.writeConfig = () => {};
+  config.readConfig = () => ({});
+  return Promise.resolve().then(fn).finally(() => Object.assign(config, saved));
+}
+
+test('loginWithBrowser: scope flags ride on the auth URL and the echoed scope comes back', async () => {
+  await withStubbedConfig(async () => {
+    let authParams;
+    const fakeOpen = async (authUrl) => {
+      authParams = new URL(authUrl).searchParams;
+      const callbackUrl = authParams.get('callback_url');
+      setImmediate(() => get(`${callbackUrl}?api_key=sk-test&email=a@b.co&org=Acme&scope=role%3AAnalytics+Viewer`));
+    };
+
+    const result = await auth.loginWithBrowser('http://frontend.invalid', {
+      open: fakeOpen, scope: { role: 'Analytics Viewer', expires_in_days: '30' },
+    });
+
+    assert.equal(authParams.get('role'), 'Analytics Viewer');
+    assert.equal(authParams.get('expires_in_days'), '30');
+    assert.equal(authParams.get('app_type'), 'cli');
+    assert.deepEqual(result, { email: 'a@b.co', orgName: 'Acme', scope: 'role:Analytics Viewer' });
+  });
+});
+
+test('loginWithBrowser: control characters in the callback error never reach the terminal', async () => {
+  await withStubbedConfig(async () => {
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(() => get(`${callbackUrl}?error=${encodeURIComponent('bad\u001b[31m role\u0007')}`));
+    };
+    await assert.rejects(
+      () => auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen, scope: { role: 'x' } }),
+      (err) => err.message === 'bad[31m role',
+    );
+  });
+});
+
+test('loginWithBrowser: the dashboard\'s error reason is the rejection and shows on the failure page', async () => {
+  await withStubbedConfig(async () => {
+    let page;
+    const fakeOpen = async (authUrl) => {
+      const callbackUrl = new URL(authUrl).searchParams.get('callback_url');
+      setImmediate(async () => { page = await get(`${callbackUrl}?error=Unknown+role+%22Policy-Auditor%22`); });
+    };
+
+    await assert.rejects(
+      () => auth.loginWithBrowser('http://frontend.invalid', { open: fakeOpen, scope: { role: 'Policy-Auditor' } }),
+      /Unknown role "Policy-Auditor"/,
+    );
+    await new Promise((resolve) => setTimeout(resolve, 50));
+    assert.equal(page.statusCode, 400);
+    assert.match(page.body, /Unknown role "Policy-Auditor"/);
+  });
+});

package/test/login-scope.test.js

@@ -0,0 +1,51 @@
+const { test } = require('node:test');
+const assert = require('node:assert/strict');
+
+const { parseLoginScope, isScoped, formatPermissions, describeToken } = require('../src/login-scope');
+
+test('parseLoginScope: no flags means a plain login', () => {
+  assert.deepEqual(parseLoginScope({}), {});
+  assert.equal(isScoped({}), false);
+});
+
+test('parseLoginScope: a flag given but empty is an error, not a plain login', () => {
+  assert.throws(() => parseLoginScope({ role: ' ' }), /--role must not be empty/);
+  assert.throws(() => parseLoginScope({ permissions: '' }), /--permissions must not be empty/);
+  assert.equal(isScoped(parseLoginScope({ expiresInDays: '7' })), true);
+});
+
+test('parseLoginScope: built-in slugs map to the role name, custom names pass verbatim', () => {
+  assert.deepEqual(parseLoginScope({ role: 'analytics-viewer' }), { role: 'Analytics Viewer' });
+  assert.deepEqual(parseLoginScope({ role: 'ADMIN' }), { role: 'Admin' });
+  assert.deepEqual(parseLoginScope({ role: ' Policy Auditor ' }), { role: 'Policy Auditor' });
+  assert.deepEqual(parseLoginScope({ role: 'constructor' }), { role: 'constructor' });
+  assert.deepEqual(parseLoginScope({ role: '__proto__' }), { role: '__proto__' });
+});
+
+test('parseLoginScope: permissions keep only granted areas, in a fixed order', () => {
+  assert.deepEqual(
+    parseLoginScope({ permissions: 'logs=view, analytics=view', expiresInDays: '30' }),
+    { expires_in_days: '30', permissions: 'analytics=view,logs=view' },
+  );
+});
+
+test('parseLoginScope: rejects bad input before the browser opens', () => {
+  assert.throws(() => parseLoginScope({ role: 'admin', permissions: 'analytics=view' }), /not both/);
+  assert.throws(() => parseLoginScope({ expiresInDays: '45' }), /7, 30, 60, 90/);
+  assert.throws(() => parseLoginScope({ permissions: 'foo=view' }), /Unknown area "foo"/);
+  assert.throws(() => parseLoginScope({ permissions: 'analytics=admin' }), /Unknown level "admin"/);
+  assert.throws(() => parseLoginScope({ permissions: 'logs=edit' }), /no edit level/);
+  assert.throws(() => parseLoginScope({ permissions: 'analytics' }), /area=level/);
+  assert.throws(() => parseLoginScope({ permissions: 'analytics=none' }), /grants no access/);
+  assert.throws(() => parseLoginScope({ role: 'x'.repeat(65) }), /Unknown role/);
+});
+
+test('formatPermissions and describeToken read the privileges payload', () => {
+  assert.equal(formatPermissions(null), 'full access');
+  assert.equal(formatPermissions({ analytics: 'view', logs: 'view', policies: 'none', configuration: 'none' }), 'Analytics view, Logs view');
+  assert.equal(describeToken({ is_admin: true }), null);
+  assert.equal(
+    describeToken({ cli_token: { name: 'cli-login:mbp', permissions: null, expires_at: '2027-02-01T00:00:00Z' } }),
+    'cli-login:mbp · full access · expires 2027-02-01',
+  );
+});

package/test/pack-confirm.test.js

@@ -0,0 +1,27 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const { PassThrough } = require('node:stream');
+
+const { confirm } = require('../src/commands/pack')._internals;
+
+test('confirm fails closed when stdin is not a TTY', () => {
+  const stdin = new PassThrough();
+  stdin.isTTY = false;
+  assert.throws(() => confirm('Delete 2 policies?', { stdin }), /pass --yes/);
+});
+
+test('confirm resolves false when stdin closes without an answer', async () => {
+  const stdin = new PassThrough();
+  stdin.isTTY = true;
+  const p = confirm('Delete?', { stdin });
+  stdin.end();
+  assert.equal(await p, false);
+});
+
+test('confirm resolves true on y', async () => {
+  const stdin = new PassThrough();
+  stdin.isTTY = true;
+  const p = confirm('Delete?', { stdin });
+  stdin.write('y\n');
+  assert.equal(await p, true);
+});

package/test/pack-export.test.js

@@ -0,0 +1,83 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const schema = require('../src/lib/pack-schema');
+const plan = require('../src/lib/pack-plan');
+const exp = require('../src/lib/pack-export');
+
+const REF = {
+  userGroups: [{ id: 1, name: 'Engineering' }],
+  guardrails: [{ id: 7, name: 'PII', supported_actions: ['BLOCK', 'AUDIT'], entities: [{ id: 70, name: 'EMAIL' }, { id: 71, name: 'SSN' }] }],
+  aiModels: [{ id: 100, name: 'claude-sonnet' }, { id: 101, name: 'gpt-4o' }],
+  toolTypes: ['cursor'],
+  labels: [{ id: 5, name: 'baseline' }],
+  mcpServers: [],
+};
+
+const LIVE = {
+  tool: [
+    { id: '11', name: 'no-rm', code_pack: 'base', code_slug: 'no-rm', policy_type: 'TERMINAL_COMMAND', action: 'BLOCK', custom_message: 'no', description: 'd', enabled: false, status: 'INACTIVE', command_family: 'custom', config: { command: 'rm -rf*' }, scope_user_groups: [{ id: 1, name: 'Engineering' }] },
+    { id: '12', name: 'gh-writes', code_pack: 'base', code_slug: 'gh-writes', policy_type: 'MCP_TOOL', action: 'AUDIT', custom_message: '', description: '', enabled: true, status: 'ACTIVE', mcp_server: 'GitHub', mcp_tools: ['push_files'], mcp_canonical_group: { id: 9, name: 'github' }, config: {}, scope_user_groups: [] },
+  ],
+  generic: [
+    { id: 21, name: 'pii', code_pack: 'base', code_slug: 'pii', type: 'SECURITY', enabled: true, priority: 3, config: { sub_type: 'guardrails', guardrails: [{ guardrail_id: 7, action: 'BLOCK', threshold: 4, enabled: true, route_model_id: null, entities: [{ entity_id: 70, enabled: true }, { entity_id: 71, enabled: false }] }] }, scope_user_groups: [], scope_tool_types: ['cursor'], labels: [{ id: 5, name: 'baseline' }] },
+    { id: 22, name: 'models', code_pack: 'base', code_slug: 'models', type: 'MODEL', enabled: true, priority: 1, config: { support_all_models: false, allowed_model_ids: [100], excluded_model_ids: [] }, scope_user_groups: [], scope_tool_types: [], labels: [] },
+    { id: 23, name: 'cap', code_pack: 'base', code_slug: 'cap', type: 'COST', enabled: true, priority: 2, config: { monthly_budget: 100 }, scope_user_groups: [], scope_tool_types: [], labels: [] },
+  ],
+};
+
+test('liveToPack: ids become names and sugar is restored', () => {
+  const doc = exp.liveToPack('base', LIVE, REF, { version: '2.0.0' });
+  assert.equal(doc.apiVersion, 'unbound.security/v1');
+  assert.deepEqual(doc.metadata, { name: 'base', version: '2.0.0' });
+  const byId = Object.fromEntries(doc.policies.map((p) => [p.id, p]));
+  assert.deepEqual(byId['no-rm'], { id: 'no-rm', kind: 'tool', type: 'TERMINAL_COMMAND', action: 'BLOCK', enabled: false, description: 'd', customMessage: 'no', commandFamily: 'custom', config: { command: 'rm -rf*' }, scope: { userGroups: ['Engineering'] } });
+  assert.deepEqual(byId['gh-writes'].mcp, { server: 'GitHub', tools: ['push_files'] });
+  assert.deepEqual(byId.pii.guardrails, [{ name: 'PII', action: 'BLOCK', threshold: 4, entities: ['EMAIL'] }]);
+  assert.deepEqual(byId.pii.scope, { toolTypes: ['cursor'] });
+  assert.deepEqual(byId.pii.labels, ['baseline']);
+  assert.deepEqual(byId.models.models, { allowed: ['claude-sonnet'] });
+  assert.deepEqual(byId.cap.config, { monthly_budget: 100 });
+  assert.equal(byId.cap.priority, 2);
+});
+
+test('round trip: export -> parse -> validate -> plan is a no-op', () => {
+  const doc = exp.liveToPack('base', LIVE, REF);
+  const text = exp.stringifyPack(doc);
+  assert.match(text, /^# PolicyPack "base"/);
+  const pack = schema.validatePack(schema.parsePackText(text, 'base.yaml'), 'base.yaml');
+  const desired = plan.toDesired(pack, REF);
+  const ops = plan.buildPlan(desired, LIVE, { prune: true });
+  assert.deepEqual(ops.map((o) => o.op), ops.map(() => 'unchanged'), JSON.stringify(ops.filter((o) => o.op !== 'unchanged').map((o) => o.changes)));
+});
+
+test('stringifyPack: JSON-compatible document without header', () => {
+  const doc = exp.liveToPack('base', { tool: [], generic: [LIVE.generic[2]] }, REF);
+  const text = exp.stringifyPack(doc, { header: false });
+  assert.doesNotMatch(text, /^#/);
+  assert.deepEqual(schema.parsePackText(text, 'x.yaml'), doc);
+});
+
+test('round trip keeps a disabled guardrail entry disabled', () => {
+  const live = { tool: [], generic: [{ ...LIVE.generic[0], config: { sub_type: 'guardrails', guardrails: [{ guardrail_id: 7, action: 'AUDIT', threshold: 1, enabled: false, route_model_id: null, entities: [{ entity_id: 70, enabled: true }, { entity_id: 71, enabled: true }] }] } }] };
+  const doc = exp.liveToPack('base', live, REF);
+  assert.deepEqual(doc.policies[0].guardrails, [{ name: 'PII', action: 'AUDIT', enabled: false }]);
+  const packDoc = schema.validatePack(doc, 'base.yaml');
+  const ops = plan.buildPlan(plan.toDesired(packDoc, REF), live, { prune: true });
+  assert.deepEqual(ops.map((o) => o.op), ['unchanged']);
+});
+
+test('export keeps a loadable file for an empty BLOCK message and an allow-nothing model policy', () => {
+  const live = {
+    tool: [{ ...LIVE.tool[0], name: 'quiet-block', code_slug: 'quiet-block', custom_message: '' }],
+    generic: [{ ...LIVE.generic[1], name: 'none', code_slug: 'none', config: { support_all_models: false, allowed_model_ids: [], excluded_model_ids: [] } }],
+  };
+  const doc = exp.liveToPack('base', live, REF);
+  const byId = Object.fromEntries(doc.policies.map((p) => [p.id, p]));
+  assert.equal(byId['quiet-block'].customMessage, '');
+  assert.equal(byId.none.models, undefined);
+  assert.deepEqual(byId.none.config, { support_all_models: false, allowed_model_ids: [], excluded_model_ids: [] });
+  const packDoc = schema.validatePack(doc, 'base.yaml');
+  const ops = plan.buildPlan(plan.toDesired(packDoc, REF), live, { prune: true });
+  assert.deepEqual(ops.map((o) => o.op), ['unchanged', 'unchanged']);
+});

package/test/pack-plan.test.js

@@ -0,0 +1,201 @@
+const test = require('node:test');
+const assert = require('node:assert/strict');
+
+const schema = require('../src/lib/pack-schema');
+const plan = require('../src/lib/pack-plan');
+
+const REF = {
+  userGroups: [{ id: 1, name: 'Engineering' }, { id: 2, name: 'Contractors' }],
+  guardrails: [{ id: 7, name: 'PII', supported_actions: ['BLOCK', 'AUDIT'], entities: [{ id: 70, name: 'EMAIL' }, { id: 71, name: 'SSN' }] }],
+  aiModels: [{ id: 100, name: 'claude-sonnet' }, { id: 101, name: 'gpt-4o' }],
+  toolTypes: ['cursor', 'claude-code'],
+  labels: [{ id: 5, name: 'baseline' }],
+  mcpServers: [{ mcp_server: 'GitHub', tool_calls: ['push_files', 'create_pull_request', 'get_file'], tool_action_types: { push_files: 'write', create_pull_request: 'write', get_file: 'read' } }],
+};
+
+function pack(policies, extra = '') {
+  return schema.validatePack({
+    apiVersion: 'unbound.security/v1',
+    kind: 'PolicyPack',
+    metadata: { name: 'base', version: '1.0.0' },
+    policies,
+    ...(extra || {}),
+  }, 'base.yaml');
+}
+
+const TERMINAL = { id: 'no-rm', kind: 'tool', type: 'TERMINAL_COMMAND', action: 'BLOCK', commandFamily: 'custom', customMessage: 'no', config: { command: 'rm -rf*' }, scope: { userGroups: ['Engineering'] } };
+const MCP = { id: 'gh-writes', kind: 'tool', type: 'MCP_TOOL', action: 'AUDIT', mcp: { server: 'github', actionType: 'write' } };
+const SECURITY = { id: 'pii', kind: 'security', priority: 3, guardrails: [{ name: 'pii', action: 'BLOCK', entities: ['EMAIL'] }], labels: ['baseline'] };
+const MODEL = { id: 'models', kind: 'model', models: { allowAll: true, excluded: ['gpt-4o'] } };
+const COST = { id: 'cap', kind: 'cost', config: { monthly_budget: 100 }, scope: { toolTypes: ['cursor'] } };
+
+const LIVE_TERMINAL = { id: '11', name: 'no-rm', code_pack: 'base', code_slug: 'no-rm', policy_type: 'TERMINAL_COMMAND', action: 'BLOCK', custom_message: 'no', description: '', enabled: true, status: 'ACTIVE', command_family: 'custom', config: { command: 'rm -rf*' }, scope_user_groups: [{ id: 1, name: 'Engineering' }] };
+const LIVE_MCP = { id: '12', name: 'gh-writes', code_pack: 'base', code_slug: 'gh-writes', policy_type: 'MCP_TOOL', action: 'AUDIT', custom_message: '', description: '', enabled: true, status: 'ACTIVE', mcp_server: 'GitHub', mcp_tools: ['create_pull_request', 'push_files'], mcp_canonical_group: { id: 9, name: 'github' }, config: {}, scope_user_groups: [] };
+const LIVE_SECURITY = { id: 21, name: 'pii', code_pack: 'base', code_slug: 'pii', type: 'SECURITY', enabled: true, priority: 3, config: { sub_type: 'guardrails', guardrails: [{ guardrail_id: 7, action: 'BLOCK', threshold: 1, enabled: true, route_model_id: null, entities: [{ entity_id: 70, enabled: true }, { entity_id: 71, enabled: false }] }] }, scope_user_groups: [], scope_tool_types: [], labels: [{ id: 5, name: 'baseline' }] };
+const LIVE_MODEL = { id: 22, name: 'models', code_pack: 'base', code_slug: 'models', type: 'MODEL', enabled: true, priority: 1, config: { support_all_models: true, allowed_model_ids: [], excluded_model_ids: [101] }, scope_user_groups: [], scope_tool_types: [], labels: [] };
+const LIVE_COST = { id: 23, name: 'cap', code_pack: 'base', code_slug: 'cap', type: 'COST', enabled: true, priority: 2, config: { monthly_budget: 100 }, scope_user_groups: [], scope_tool_types: ['cursor'], labels: [] };
+
+test('toDesired: builds write bodies with resolved ids', () => {
+  const desired = plan.toDesired(pack([TERMINAL, MCP, SECURITY, MODEL, COST]), REF);
+  const [t, m, s, mo, c] = desired;
+  assert.equal(t.table, 'tool');
+  assert.deepEqual(t.body.scope_user_group_ids, [1]);
+  assert.equal(t.body.command_family, 'custom');
+  assert.equal(m.body.mcp_tool_action_type, 'write');
+  assert.deepEqual(m.proj.mcp_tools, ['create_pull_request', 'push_files'], 'action type expanded from metadata');
+  assert.equal(s.body.type, 'SECURITY');
+  assert.deepEqual(s.body.config.guardrails[0], { guardrail_id: 7, enabled: true, action: 'BLOCK', threshold: 1, route_model_id: null, entities: [{ entity_id: 70, enabled: true }] });
+  assert.deepEqual(s.body.label_ids, [5]);
+  assert.deepEqual(mo.body.config, { support_all_models: true, allowed_model_ids: [], excluded_model_ids: [101] });
+  assert.deepEqual(c.body.scope_tool_types, ['cursor']);
+  assert.equal(c.body.priority, undefined, 'priority is unmanaged when absent');
+});
+
+test('toDesired: unresolved names fail before any write', () => {
+  assert.throws(() => plan.toDesired(pack([{ ...TERMINAL, scope: { userGroups: ['Nope'] } }]), REF), /no user group named "Nope"/);
+  assert.throws(() => plan.toDesired(pack([{ ...SECURITY, guardrails: [{ name: 'Secrets', action: 'BLOCK' }] }]), REF), /no guardrail named "Secrets"/);
+  assert.throws(() => plan.toDesired(pack([{ ...SECURITY, guardrails: [{ name: 'PII', action: 'REDACT' }] }]), REF), /does not support REDACT/);
+  assert.throws(() => plan.toDesired(pack([{ ...MODEL, models: { allowed: ['llama'] } }]), REF), /no model named "llama"/);
+  assert.throws(() => plan.toDesired(pack([{ ...COST, scope: { toolTypes: ['vim'] } }]), REF), /unknown tool type vim/);
+  assert.throws(() => plan.toDesired(pack([{ ...SECURITY, labels: ['nope'] }]), REF), /no label named "nope"/);
+});
+
+test('buildPlan: in-sync org yields only unchanged ops', () => {
+  const desired = plan.toDesired(pack([TERMINAL, MCP, SECURITY, MODEL, COST]), REF);
+  const ops = plan.buildPlan(desired, { tool: [LIVE_TERMINAL, LIVE_MCP], generic: [LIVE_SECURITY, LIVE_MODEL, LIVE_COST] });
+  assert.deepEqual(ops.map((o) => o.op), ['unchanged', 'unchanged', 'unchanged', 'unchanged', 'unchanged']);
+  assert.equal(plan.summarize(ops).drift, 0);
+});
+
+test('buildPlan: create, patch-update, orphan and prune', () => {
+  const desired = plan.toDesired(pack([{ ...TERMINAL, action: 'AUDIT', customMessage: undefined }, { ...COST, config: { monthly_budget: 250 } }]), REF);
+  const live = { tool: [LIVE_TERMINAL, LIVE_MCP], generic: [LIVE_COST] };
+
+  const ops = plan.buildPlan(desired, live);
+  const byName = Object.fromEntries(ops.map((o) => [o.serverName, o]));
+  assert.equal(byName['no-rm'].op, 'update');
+  assert.deepEqual(byName['no-rm'].body, { action: 'AUDIT', custom_message: '' }, 'only changed fields are sent');
+  assert.equal(byName['cap'].op, 'update');
+  assert.deepEqual(byName['cap'].body, { config: { monthly_budget: 250 } });
+  assert.equal(byName['gh-writes'].op, 'orphan', 'without prune the orphan is kept');
+
+  const pruned = plan.buildPlan(desired, live, { prune: true });
+  assert.equal(pruned.find((o) => o.serverName === 'gh-writes').op, 'delete');
+  assert.equal(plan.summarize(pruned).delete, 1);
+
+  const created = plan.buildPlan(plan.toDesired(pack([SECURITY]), REF), { tool: [], generic: [] });
+  assert.equal(created[0].op, 'create');
+  assert.equal(created[0].body.name, 'pii');
+  assert.equal(created[0].body.code_pack, 'base');
+  assert.equal(created[0].body.code_slug, 'pii');
+});
+
+test('buildPlan: MCP tool-set change patches with the canonical group id', () => {
+  const desired = plan.toDesired(pack([{ ...MCP, mcp: { server: 'github', tools: ['push_files'] } }]), REF);
+  const [op] = plan.buildPlan(desired, { tool: [LIVE_MCP], generic: [] });
+  assert.equal(op.op, 'update');
+  assert.deepEqual(op.body, { mcp_canonical_group_id: 9, mcp_tools: ['push_files'] });
+});
+
+test('buildPlan: MCP server change and type change are replace', () => {
+  const server = plan.toDesired(pack([{ ...MCP, mcp: { server: 'slack', tool: 'post_message' } }]), REF);
+  assert.equal(plan.buildPlan(server, { tool: [LIVE_MCP], generic: [] })[0].op, 'replace');
+  const type = plan.toDesired(pack([{ ...TERMINAL, id: 'gh-writes' }]), REF);
+  assert.equal(plan.buildPlan(type, { tool: [LIVE_MCP], generic: [] })[0].op, 'replace');
+});
+
+test('an action-type selector the catalogue cannot resolve is an error, never "unchanged"', () => {
+  const unknownServer = { ...MCP, mcp: { server: 'nope', actionType: 'write' } };
+  assert.throws(() => plan.toDesired(pack([unknownServer]), REF), /not in this org's MCP catalogue/);
+  const emptyRef = { ...REF, mcpServers: [] };
+  assert.throws(() => plan.toDesired(pack([MCP]), emptyRef), /not in this org's MCP catalogue/);
+  const noTools = { ...MCP, mcp: { server: 'github', actionType: 'destructive' } };
+  assert.throws(() => plan.toDesired(pack([noTools]), REF), /has no destructive tools/);
+});
+
+test('buildPlan: conflicts are reported, never written', () => {
+  // same name exists in the other table
+  const desired = plan.toDesired(pack([{ ...COST, id: 'no-rm' }]), REF);
+  const [clash] = plan.buildPlan(desired, { tool: [LIVE_TERMINAL], generic: [] });
+  assert.equal(clash.op, 'conflict');
+  // generic kind change
+  const kindChange = plan.toDesired(pack([{ ...SECURITY, id: 'cap' }]), REF);
+  assert.equal(plan.buildPlan(kindChange, { tool: [], generic: [LIVE_COST] })[0].op, 'conflict');
+  assert.equal(plan.summarize([clash]).conflict, 1);
+});
+
+test('diffFields: scope and label order do not count as drift', () => {
+  const desired = plan.toDesired(pack([{ ...TERMINAL, scope: { userGroups: ['Contractors', 'Engineering'] } }]), REF);
+  const live = { ...LIVE_TERMINAL, scope_user_groups: [{ id: 2, name: 'Contractors' }, { id: 1, name: 'Engineering' }] };
+  assert.deepEqual(plan.diffFields(desired[0].proj, plan.liveProjection(live, 'tool')), []);
+});
+
+test('MCP writes keep the author casing; only the comparison is lowercased', () => {
+  const ref = { ...REF, mcpServers: [{ mcp_server: 'Jira', tool_calls: ['getJiraIssue', 'createIssue'], tool_action_types: { getJiraIssue: 'read', createIssue: 'write' } }] };
+  const desired = plan.toDesired(pack([{ ...MCP, id: 'jira', mcp: { server: 'jira', tools: ['getJiraIssue'] } }, { ...MCP, id: 'jira-writes', mcp: { server: 'jira', actionType: 'write' } }]), ref);
+  assert.deepEqual(desired[0].proj.mcp_tools, ['getjiraissue']);
+  assert.deepEqual(desired[0].body.mcp_tools, ['getJiraIssue']);
+  assert.deepEqual(desired[1].proj.mcp_tools, ['createissue']);
+  assert.equal(desired[1].body.mcp_tool_action_type, 'write');
+  const live = { ...LIVE_MCP, name: 'jira', code_slug: 'jira', mcp_server: 'Jira', mcp_canonical_group: { id: 4, name: 'jira' }, mcp_tools: ['createIssue'] };
+  const [op] = plan.buildPlan([desired[0]], { tool: [live], generic: [] });
+  assert.equal(op.op, 'update');
+  assert.deepEqual(op.body, { mcp_canonical_group_id: 4, mcp_tools: ['getJiraIssue'] });
+  const liveWrites = { ...live, name: 'jira-writes', code_slug: 'jira-writes', mcp_tools: ['getJiraIssue'] };
+  const [op2] = plan.buildPlan([desired[1]], { tool: [liveWrites], generic: [] });
+  assert.deepEqual(op2.body, { mcp_canonical_group_id: 4, mcp_tools: ['createIssue'] }, 'action type expansion keeps server casing');
+});
+
+test('guardrail entries can be disabled in the pack', () => {
+  const desired = plan.toDesired(pack([{ ...SECURITY, guardrails: [{ name: 'PII', action: 'BLOCK', enabled: false }] }]), REF);
+  assert.equal(desired[0].body.config.guardrails[0].enabled, false);
+  const live = { ...LIVE_SECURITY, config: { sub_type: 'guardrails', guardrails: [{ guardrail_id: 7, action: 'BLOCK', threshold: 1, enabled: false, route_model_id: null, entities: [{ entity_id: 70, enabled: true }, { entity_id: 71, enabled: true }] }] } };
+  assert.equal(plan.buildPlan(desired, { tool: [], generic: [live] })[0].op, 'unchanged');
+});
+
+test('MCP config changes are drift and patch only config', () => {
+  const desired = plan.toDesired(pack([{ ...MCP, mcp: { server: 'github', tools: ['create_pull_request', 'push_files'] }, config: { note: 'x' } }]), REF);
+  const [op] = plan.buildPlan(desired, { tool: [LIVE_MCP], generic: [] });
+  assert.equal(op.op, 'update');
+  assert.deepEqual(op.body, { config: { note: 'x' } });
+});
+
+test('an unsupported row under the desired name is a conflict, never a create', () => {
+  const desired = plan.toDesired(pack([{ ...COST, id: 'skill' }]), REF);
+  const live = { tool: [], generic: [], unsupported: [{ table: 'tool', row: { id: '7', name: 'Skill', policy_type: 'SKILL_INJECTION', origin: 'CODE', code_pack: 'base', code_slug: 'skill' } }] };
+  const [op] = plan.buildPlan(desired, live);
+  assert.equal(op.op, 'conflict');
+  assert.match(op.reason, /SKILL_INJECTION/);
+});
+
+test('a managed row switched off in the console is an enabled-only update', () => {
+  const desired = plan.toDesired(pack([TERMINAL, COST]), REF);
+  const live = {
+    tool: [{ ...LIVE_TERMINAL, origin: 'CODE', enabled: false, status: 'INACTIVE' }],
+    generic: [{ ...LIVE_COST, origin: 'CODE', enabled: false }],
+  };
+  const ops = plan.buildPlan(desired, live);
+  for (const op of ops) {
+    assert.equal(op.op, 'update', op.serverName);
+    assert.deepEqual(op.body, { enabled: true });
+    assert.deepEqual(op.changes, [{ field: 'enabled', from: false, to: true }]);
+  }
+  assert.equal(plan.summarize(ops).drift, 2);
+});
+
+test('a name already used elsewhere in the org is a conflict at plan time, not a failed create', () => {
+  const desired = plan.toDesired(pack([{ ...COST, name: 'Monthly cap' }, { ...SECURITY, name: 'PII guard' }]), REF);
+  const names = new Map([
+    ['Monthly cap', { table: 'generic', id: 77, code_pack: null, code_slug: null }],
+    ['PII guard', { table: 'generic', id: 21, code_pack: 'base', code_slug: 'pii' }],
+  ]);
+  const ops = plan.buildPlan(desired, { tool: [], generic: [{ ...LIVE_SECURITY, name: 'PII guard' }], names });
+  const byId = Object.fromEntries(ops.map((o) => [o.id, o]));
+  assert.equal(byId.cap.op, 'conflict');
+  assert.match(byId.cap.reason, /made in the console/);
+  assert.equal(byId.pii.op, 'unchanged', 'the row that already owns the name is not a conflict with itself');
+
+  const renamed = plan.toDesired(pack([{ ...SECURITY, name: 'Monthly cap' }]), REF);
+  const renamedOps = plan.buildPlan(renamed, { tool: [], generic: [{ ...LIVE_SECURITY, name: 'PII guard' }], names }, { prune: true });
+  assert.deepEqual(renamedOps.map((o) => o.op), ['conflict'], 'a refused rename is a conflict and never also an orphan or delete');
+});