unbound-cli 1.18.0 → 1.20.0

package/src/lib/pack-export.js

@@ -0,0 +1,136 @@
+// Live policy rows -> PolicyPack document (ids back to names), and YAML output.
+// Pure module. The round trip "export -> apply" must be a no-op, so every
+// field the plan engine compares is written back here.
+
+const YAML = require('yaml');
+const { API_VERSION, KIND, slugify } = require('./pack-schema');
+const { nameOf, liveKind } = require('./pack-plan');
+
+function groupNames(row) {
+  return (row.scope_user_groups || []).map((g) => g.name).filter(Boolean);
+}
+
+function omitKeys(obj, keys) {
+  const out = {};
+  for (const [k, v] of Object.entries(obj || {})) if (!keys.includes(k)) out[k] = v;
+  return out;
+}
+
+/** The policy id in the file: the server identity, else a slug of the name. */
+function idOf(row) {
+  return row.code_slug || slugify(row.name) || String(row.name);
+}
+
+function toolRowToPolicy(row) {
+  const p = { id: idOf(row), kind: 'tool', type: row.policy_type, action: row.action };
+  if (row.name !== p.id) p.name = row.name;
+  const enabled = row.enabled !== undefined ? !!row.enabled : row.status === 'ACTIVE';
+  if (!enabled) p.enabled = false;
+  if (row.description) p.description = row.description;
+  if (row.custom_message || row.action === 'BLOCK' || row.action === 'WARN') p.customMessage = row.custom_message || '';
+  if (row.policy_type === 'TERMINAL_COMMAND') {
+    p.commandFamily = row.command_family;
+    p.config = row.config || {};
+  } else {
+    const group = row.mcp_canonical_group && typeof row.mcp_canonical_group === 'object' ? row.mcp_canonical_group : null;
+    const mcp = { server: row.mcp_server || (group && group.name) || '' };
+    if (Array.isArray(row.mcp_tools) && row.mcp_tools.length) mcp.tools = [...row.mcp_tools];
+    else if (row.mcp_tool) mcp.tool = row.mcp_tool;
+    else if (row.mcp_tool_action_type) mcp.actionType = row.mcp_tool_action_type;
+    p.mcp = mcp;
+    if (row.config && Object.keys(row.config).length) p.config = row.config;
+  }
+  const groups = groupNames(row);
+  if (groups.length) p.scope = { userGroups: groups };
+  return p;
+}
+
+function guardrailsSugar(config, ref) {
+  return config.guardrails.map((g) => {
+    const guardrail = (ref.guardrails || []).find((it) => Number(it.id) === Number(g.guardrail_id));
+    const out = { name: guardrail ? guardrail.name : String(g.guardrail_id), action: g.action };
+    if (g.enabled === false) out.enabled = false;
+    if (g.threshold != null && Number(g.threshold) !== 1) out.threshold = Number(g.threshold);
+    const enabledIds = (g.entities || []).filter((e) => e && e.enabled !== false).map((e) => Number(e.entity_id));
+    const allIds = guardrail ? (guardrail.entities || []).map((e) => Number(e.id)) : [];
+    const allEnabled = allIds.length && allIds.every((id) => enabledIds.includes(id)) && enabledIds.length === allIds.length;
+    if (!allEnabled && (enabledIds.length || allIds.length)) {
+      out.entities = enabledIds.map((id) => {
+        const ent = guardrail ? (guardrail.entities || []).find((e) => Number(e.id) === id) : null;
+        return ent ? ent.name : String(id);
+      });
+    }
+    if (g.route_model_id != null) out.routeModel = nameOf(ref.aiModels, g.route_model_id);
+    return out;
+  });
+}
+
+function genericRowToPolicy(row, ref) {
+  const kind = liveKind(row, 'generic');
+  const p = { id: idOf(row), kind };
+  if (row.name !== p.id) p.name = row.name;
+  if (!row.enabled) p.enabled = false;
+  if (row.priority != null) p.priority = row.priority;
+
+  const config = row.config || {};
+  if (kind === 'security' && config.sub_type === 'guardrails' && Array.isArray(config.guardrails)) {
+    p.guardrails = guardrailsSugar(config, ref);
+    const rest = omitKeys(config, ['sub_type', 'guardrails']);
+    if (Object.keys(rest).length) p.config = rest;
+  } else if (
+    kind === 'model'
+    && ('support_all_models' in config || 'allowed_model_ids' in config || 'excluded_model_ids' in config)
+    // "allow nothing" has no sugar form; keep it as raw config so the file validates.
+    && (config.support_all_models || (config.allowed_model_ids || []).length)
+  ) {
+    const models = {};
+    if (config.support_all_models) {
+      models.allowAll = true;
+      if ((config.excluded_model_ids || []).length) models.excluded = config.excluded_model_ids.map((id) => nameOf(ref.aiModels, id));
+    } else {
+      models.allowed = (config.allowed_model_ids || []).map((id) => nameOf(ref.aiModels, id));
+    }
+    p.models = models;
+    const rest = omitKeys(config, ['support_all_models', 'allowed_model_ids', 'excluded_model_ids']);
+    if (Object.keys(rest).length) p.config = rest;
+  } else {
+    p.config = config;
+  }
+
+  const scope = {};
+  const groups = groupNames(row);
+  if (groups.length) scope.userGroups = groups;
+  if (Array.isArray(row.scope_tool_types) && row.scope_tool_types.length) scope.toolTypes = [...row.scope_tool_types];
+  if (Object.keys(scope).length) p.scope = scope;
+  const labels = (row.labels || []).map((l) => l.name).filter(Boolean);
+  if (labels.length) p.labels = labels;
+  return p;
+}
+
+/**
+ * Build a PolicyPack document from the live rows of one pack.
+ * live: { tool: [rows], generic: [rows] }
+ */
+function liveToPack(packName, live, ref, { version = '1.0.0', description } = {}) {
+  const policies = [
+    ...(live.tool || []).map((r) => toolRowToPolicy(r)),
+    ...(live.generic || []).map((r) => genericRowToPolicy(r, ref)),
+  ].sort((a, b) => a.id.localeCompare(b.id));
+  const metadata = { name: packName, version };
+  if (description) metadata.description = description;
+  return { apiVersion: API_VERSION, kind: KIND, metadata, policies };
+}
+
+function stringifyPack(doc, { header = true } = {}) {
+  const body = YAML.stringify(doc, { lineWidth: 0, indent: 2 });
+  if (!header) return body;
+  return [
+    `# PolicyPack "${doc.metadata.name}" — managed by \`unbound pack\`.`,
+    '# Each policy is matched on the server by this pack name and its id; `name` is free text.',
+    '# Edit, bump metadata.version,',
+    '# then run: unbound pack apply -f <this file> --dry-run',
+    body,
+  ].join('\n');
+}
+
+module.exports = { liveToPack, stringifyPack, toolRowToPolicy, genericRowToPolicy };

package/src/lib/pack-plan.js

@@ -0,0 +1,515 @@
+// Plan engine for `unbound pack`: turns a validated pack into API write bodies,
+// projects live rows into the same comparable shape, and diffs the two into a
+// list of create / update / replace / delete / unchanged operations.
+//
+// Pure module: no network. `ref` is the reference data the remote layer loads
+// once per process (user groups, guardrails, models, labels, MCP metadata).
+
+const { PackError, GENERIC_KINDS } = require('./pack-schema');
+
+// ---------------------------------------------------------------------------
+// Small helpers
+// ---------------------------------------------------------------------------
+
+function stable(value) {
+  if (Array.isArray(value)) return `[${value.map(stable).join(',')}]`;
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${stable(value[k])}`).join(',')}}`;
+  }
+  return JSON.stringify(value === undefined ? null : value);
+}
+
+function deepEqual(a, b) {
+  return stable(a) === stable(b);
+}
+
+function sortedNumbers(list) {
+  return [...new Set((list || []).map(Number))].sort((a, b) => a - b);
+}
+
+function sortedLower(list) {
+  return [...new Set((list || []).map((s) => String(s).toLowerCase()))].sort();
+}
+
+function lower(s) {
+  return s == null ? null : String(s).toLowerCase();
+}
+
+/**
+ * Resolve one name (or numeric id) against `items` ({id, name}). Case-insensitive
+ * on the name. Throws a PackError (exit 2) listing what is available.
+ */
+function resolveOne(items, raw, kind, { where } = {}) {
+  const list = items || [];
+  const text = String(raw).trim();
+  if (/^\d+$/.test(text)) {
+    const hit = list.find((it) => Number(it.id) === Number(text));
+    if (hit) return hit;
+    throw new PackError(`${where ? `${where}: ` : ''}no ${kind} with id ${text}`);
+  }
+  const hit = list.find((it) => String(it.name || '').toLowerCase() === text.toLowerCase());
+  if (hit) return hit;
+  const available = list.map((it) => it.name).filter(Boolean);
+  throw new PackError(
+    `${where ? `${where}: ` : ''}no ${kind} named "${text}". Available: ${available.length ? available.join(', ') : '(none)'}`
+  );
+}
+
+function resolveIds(items, names, kind, opts) {
+  return sortedNumbers((names || []).map((n) => resolveOne(items, n, kind, opts).id));
+}
+
+function nameOf(items, id) {
+  const hit = (items || []).find((it) => Number(it.id) === Number(id));
+  return hit && hit.name ? hit.name : String(id);
+}
+
+// ---------------------------------------------------------------------------
+// Config normalisation (both sides go through the same functions)
+// ---------------------------------------------------------------------------
+
+function normalizeSecurityConfig(config) {
+  if (!config || typeof config !== 'object') return config || {};
+  if (config.sub_type !== 'guardrails' || !Array.isArray(config.guardrails)) return config;
+  const guardrails = config.guardrails
+    .map((g) => ({
+      guardrail_id: Number(g.guardrail_id),
+      action: g.action,
+      threshold: g.threshold == null ? 1 : Number(g.threshold),
+      enabled: g.enabled !== false,
+      route_model_id: g.route_model_id == null ? null : Number(g.route_model_id),
+      entities: sortedNumbers((g.entities || []).filter((e) => e && e.enabled !== false).map((e) => e.entity_id)),
+    }))
+    .sort((a, b) => a.guardrail_id - b.guardrail_id);
+  return { ...config, guardrails };
+}
+
+function normalizeModelConfig(config) {
+  if (!config || typeof config !== 'object') return config || {};
+  return {
+    ...config,
+    support_all_models: !!config.support_all_models,
+    allowed_model_ids: sortedNumbers(config.allowed_model_ids),
+    excluded_model_ids: sortedNumbers(config.excluded_model_ids),
+  };
+}
+
+function normalizeConfig(kind, config) {
+  if (kind === 'security') return normalizeSecurityConfig(config);
+  if (kind === 'model') return normalizeModelConfig(config);
+  return config || {};
+}
+
+// ---------------------------------------------------------------------------
+// Pack policy -> write body + projection
+// ---------------------------------------------------------------------------
+
+function guardrailsToConfig(policy, ref, where) {
+  const base = { ...(policy.config || {}) };
+  const out = { ...base, sub_type: base.sub_type || 'guardrails' };
+  out.guardrails = policy.guardrails.map((g, i) => {
+    const gw = `${where}.guardrails[${i}]`;
+    const guardrail = resolveOne(ref.guardrails, g.name, 'guardrail', { where: gw });
+    if (Array.isArray(guardrail.supported_actions) && !guardrail.supported_actions.includes(g.action)) {
+      throw new PackError(`${gw}: guardrail "${guardrail.name}" does not support ${g.action}. Supported: ${guardrail.supported_actions.join(', ')}`);
+    }
+    let entityIds;
+    if (g.entities) {
+      entityIds = g.entities.map((e) => resolveOne(guardrail.entities || [], e, `entity of guardrail "${guardrail.name}"`, { where: gw }).id);
+    } else {
+      entityIds = (guardrail.entities || []).map((e) => e.id);
+    }
+    const routeModelId = g.routeModel ? resolveOne(ref.aiModels, g.routeModel, 'model', { where: gw }).id : null;
+    return {
+      guardrail_id: guardrail.id,
+      enabled: g.enabled !== false,
+      action: g.action,
+      threshold: g.threshold == null ? 1 : g.threshold,
+      route_model_id: g.action === 'ROUTE' ? routeModelId : null,
+      entities: entityIds.map((id) => ({ entity_id: id, enabled: true })),
+    };
+  });
+  return out;
+}
+
+function modelsToConfig(policy, ref, where) {
+  const m = policy.models;
+  const allowAll = !!m.allowAll || (!!m.excluded && m.excluded.length > 0 && !(m.allowed && m.allowed.length));
+  return {
+    ...(policy.config || {}),
+    support_all_models: allowAll,
+    allowed_model_ids: allowAll ? [] : resolveIds(ref.aiModels, m.allowed, 'model', { where }),
+    excluded_model_ids: allowAll ? resolveIds(ref.aiModels, m.excluded, 'model', { where }) : [],
+  };
+}
+
+/**
+ * Expand an MCP action type into the concrete tool list the backend will store,
+ * using the mcp-servers metadata. Returns null when the server is not in the
+ * metadata (null = unknown server, [] = no tool of that type).
+ */
+function expandActionType(ref, server, actionType) {
+  const servers = ref.mcpServers || [];
+  const hits = servers.filter((s) => lower(s.mcp_server) === lower(server));
+  if (!hits.length) return null;
+  const tools = [];
+  for (const s of hits) {
+    for (const [tool, type] of Object.entries(s.tool_action_types || {})) {
+      if (type === actionType && !tools.includes(tool)) tools.push(tool);
+    }
+  }
+  // Original casing, sorted: this is what a write sends. Callers lowercase it
+  // themselves when they compare. A known server with no tool of this type is
+  // an empty list, not "unknown".
+  return [...tools].sort();
+}
+
+function toolDesired(policy, ref, where) {
+  const scopeIds = resolveIds(ref.userGroups, policy.scope && policy.scope.userGroups, 'user group', { where });
+  const body = {
+    name: policy.serverName,
+    description: policy.description || '',
+    policy_type: policy.type,
+    action: policy.action,
+    custom_message: policy.customMessage || '',
+    enabled: policy.enabled,
+    scope_user_group_ids: scopeIds,
+    config: policy.config || {},
+  };
+  const proj = {
+    name: body.name,
+    policy_type: body.policy_type,
+    action: body.action,
+    custom_message: body.custom_message,
+    description: body.description,
+    enabled: body.enabled,
+    scope_user_group_ids: scopeIds,
+  };
+  let mcp = null;
+  if (policy.type === 'TERMINAL_COMMAND') {
+    body.command_family = policy.commandFamily;
+    proj.command_family = policy.commandFamily;
+    proj.config = body.config;
+  } else {
+    const sel = policy.mcp;
+    body.mcp_server = sel.server;
+    proj.mcp_server = lower(sel.server);
+    // `writeTools` keeps the author's casing for the PUT body; the projection is
+    // lowercased only for comparison.
+    let writeTools = null;
+    if (sel.tools) {
+      body.mcp_tools = [...sel.tools];
+      writeTools = [...sel.tools];
+    } else if (sel.tool) {
+      body.mcp_tool = sel.tool;
+      writeTools = [sel.tool];
+    } else {
+      body.mcp_tool_action_type = sel.actionType;
+      writeTools = expandActionType(ref, sel.server, sel.actionType);
+      // A selector the CLI cannot resolve is an error, never "in sync": leaving
+      // the old tool set enforcing while reporting success is the worst outcome.
+      if (writeTools === null) {
+        const known = (ref.mcpServers || []).map((s) => s.mcp_server).filter(Boolean);
+        throw new PackError(`${where}: MCP server "${sel.server}" is not in this org's MCP catalogue, so actionType ${sel.actionType} cannot be resolved to tools${known.length ? `. Known servers: ${[...new Set(known)].sort().join(', ')}` : ''}`);
+      }
+      if (!writeTools.length) {
+        throw new PackError(`${where}: MCP server "${sel.server}" has no ${sel.actionType} tools in this org's catalogue; pick another actionType or list mcp.tools`);
+      }
+    }
+    proj.mcp_tools = sortedLower(writeTools);
+    proj.config = body.config;
+    mcp = { ...sel, writeTools };
+  }
+  return { table: 'tool', body, proj, mcp };
+}
+
+function genericDesired(policy, ref, where) {
+  const kind = policy.kind;
+  let config;
+  if (kind === 'security' && policy.guardrails) config = guardrailsToConfig(policy, ref, where);
+  else if (kind === 'model' && policy.models) config = modelsToConfig(policy, ref, where);
+  else config = policy.config || {};
+
+  const scopeIds = resolveIds(ref.userGroups, policy.scope && policy.scope.userGroups, 'user group', { where });
+  const toolTypes = [...new Set(policy.scope && policy.scope.toolTypes ? policy.scope.toolTypes : [])].sort();
+  if (toolTypes.length && Array.isArray(ref.toolTypes) && ref.toolTypes.length) {
+    const known = ref.toolTypes.map((t) => (typeof t === 'string' ? t : t.value));
+    const bad = toolTypes.filter((t) => !known.includes(t));
+    if (bad.length) throw new PackError(`${where}: unknown tool type${bad.length > 1 ? 's' : ''} ${bad.join(', ')}. Available: ${known.join(', ')}`);
+  }
+  const labelIds = resolveIds(ref.labels, policy.labels, 'label', { where });
+
+  const body = {
+    name: policy.serverName,
+    type: kind.toUpperCase(),
+    config,
+    enabled: policy.enabled,
+    scope_user_group_ids: scopeIds,
+    scope_tool_types: toolTypes,
+    label_ids: labelIds,
+  };
+  if (policy.priority !== undefined) body.priority = policy.priority;
+
+  const proj = {
+    name: body.name,
+    type: body.type,
+    enabled: body.enabled,
+    config: normalizeConfig(kind, config),
+    scope_user_group_ids: scopeIds,
+    scope_tool_types: toolTypes,
+    label_ids: labelIds,
+  };
+  if (policy.priority !== undefined) proj.priority = policy.priority;
+  return { table: 'generic', body, proj, mcp: null };
+}
+
+/**
+ * Convert every policy of a validated pack into {id, kind, serverName, table,
+ * body, proj}. Throws PackError on any unresolved name, before any write.
+ */
+function toDesired(pack, ref) {
+  return pack.policies.map((policy) => {
+    const where = `policies (${policy.id})`;
+    const built = policy.kind === 'tool' ? toolDesired(policy, ref, where) : genericDesired(policy, ref, where);
+    // Identity on the server: the pack and the policy id, never the name.
+    built.body.code_pack = pack.name;
+    built.body.code_slug = policy.id;
+    return { id: policy.id, kind: policy.kind, serverName: policy.serverName, policy, ...built };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Live row -> projection
+// ---------------------------------------------------------------------------
+
+function liveKind(row, table) {
+  if (table === 'tool') return 'tool';
+  const t = String(row.type || '').toLowerCase();
+  return GENERIC_KINDS.includes(t) ? t : t || 'unknown';
+}
+
+function liveProjection(row, table) {
+  const scopeIds = sortedNumbers((row.scope_user_groups || []).map((g) => g.id));
+  if (table === 'tool') {
+    const proj = {
+      name: row.name,
+      policy_type: row.policy_type,
+      action: row.action,
+      custom_message: row.custom_message || '',
+      description: row.description || '',
+      enabled: row.enabled !== undefined ? !!row.enabled : row.status === 'ACTIVE',
+      scope_user_group_ids: scopeIds,
+    };
+    if (row.policy_type === 'TERMINAL_COMMAND') {
+      proj.command_family = row.command_family;
+      proj.config = row.config || {};
+    } else if (row.policy_type === 'MCP_TOOL') {
+      const group = row.mcp_canonical_group && typeof row.mcp_canonical_group === 'object' ? row.mcp_canonical_group : null;
+      proj.mcp_server = lower(row.mcp_server || (group && group.name));
+      proj.mcp_tools = Array.isArray(row.mcp_tools) && row.mcp_tools.length
+        ? sortedLower(row.mcp_tools)
+        : row.mcp_tool ? sortedLower([row.mcp_tool]) : [];
+      proj.config = row.config || {};
+    }
+    return proj;
+  }
+  const kind = liveKind(row, table);
+  return {
+    name: row.name,
+    type: row.type,
+    enabled: !!row.enabled,
+    config: normalizeConfig(kind, row.config),
+    scope_user_group_ids: scopeIds,
+    scope_tool_types: [...new Set(row.scope_tool_types || [])].sort(),
+    label_ids: sortedNumbers((row.labels || []).map((l) => l.id)),
+    priority: row.priority == null ? null : row.priority,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Diff + plan
+// ---------------------------------------------------------------------------
+
+const PROJ_TO_BODY = {
+  tool: {
+    name: (d) => ({ name: d.body.name }),
+    action: (d) => ({ action: d.body.action }),
+    custom_message: (d) => ({ custom_message: d.body.custom_message }),
+    description: (d) => ({ description: d.body.description }),
+    enabled: (d) => ({ enabled: d.body.enabled }),
+    scope_user_group_ids: (d) => ({ scope_user_group_ids: d.body.scope_user_group_ids }),
+    command_family: (d) => ({ command_family: d.body.command_family, config: d.body.config }),
+    config: (d) => (d.body.policy_type === 'TERMINAL_COMMAND'
+      ? { command_family: d.body.command_family, config: d.body.config }
+      : { config: d.body.config }),
+    mcp_tools: (d, row) => {
+      const group = row.mcp_canonical_group && typeof row.mcp_canonical_group === 'object' ? row.mcp_canonical_group : null;
+      const tools = d.mcp && d.mcp.writeTools;
+      if (!group || !group.id || !tools) return null;
+      return { mcp_canonical_group_id: group.id, mcp_tools: [...tools] };
+    },
+  },
+  generic: {
+    name: (d) => ({ name: d.body.name }),
+    enabled: (d) => ({ enabled: d.body.enabled }),
+    config: (d) => ({ config: d.body.config }),
+    scope_user_group_ids: (d) => ({ scope_user_group_ids: d.body.scope_user_group_ids }),
+    scope_tool_types: (d) => ({ scope_tool_types: d.body.scope_tool_types }),
+    label_ids: (d) => ({ label_ids: d.body.label_ids }),
+    priority: (d) => ({ priority: d.body.priority }),
+  },
+};
+
+/** Fields of the desired projection that differ from the live projection. */
+function diffFields(desiredProj, liveProj) {
+  const changes = [];
+  for (const key of Object.keys(desiredProj)) {
+    if (key === 'policy_type' || key === 'type') continue;
+    const want = desiredProj[key];
+    const have = liveProj[key];
+    if (!deepEqual(want, have)) changes.push({ field: key, from: have === undefined ? null : have, to: want });
+  }
+  return changes;
+}
+
+/** Live row of a pack with this policy id (`code_slug`); null when none. */
+function findBySlug(rows, slug) {
+  return (rows || []).find((r) => r.code_slug === slug) || null;
+}
+
+/**
+ * Build the operation list.
+ *
+ * desired: output of toDesired
+ * live: { tool: [rows], generic: [rows] } — only rows under this pack's prefix
+ * options.prune: delete managed rows absent from the pack
+ */
+function buildPlan(desired, live, { prune = false } = {}) {
+  const ops = [];
+  const matchedTool = new Set();
+  const matchedGeneric = new Set();
+  const unsupported = (live.unsupported || []).map((u) => u.row);
+  // Names are unique per org. `live.names` (name -> owner) lets a create or a
+  // rename that the server would reject show up here instead of failing mid-apply.
+  const names = live.names instanceof Map ? live.names : null;
+  const nameTakenBy = (d, ownRow) => {
+    if (!names) return null;
+    const owner = names.get(d.serverName);
+    if (!owner) return null;
+    if (ownRow && owner.table === d.table && String(owner.id) === String(ownRow.id)) return null;
+    return owner;
+  };
+  const nameConflict = (base, owner) => ({
+    ...base,
+    op: 'conflict',
+    row: null,
+    reason: owner.code_pack
+      ? `the name "${base.serverName}" is already used by ${owner.code_pack}/${owner.code_slug}; set a different name in the file`
+      : `the name "${base.serverName}" is already used by a policy made in the console; set a different name in the file or adopt that policy`,
+  });
+
+  for (const d of desired) {
+    const own = d.table === 'tool' ? live.tool : live.generic;
+    const other = d.table === 'tool' ? live.generic : live.tool;
+    const row = findBySlug(own, d.id);
+    const clash = findBySlug(other, d.id);
+    const blocked = findBySlug(unsupported, d.id);
+    const base = { id: d.id, kind: d.kind, serverName: d.serverName, table: d.table, desired: d };
+
+    if (blocked) {
+      const type = blocked.policy_type || blocked.type;
+      ops.push({ ...base, op: 'conflict', row: blocked, reason: `exists on the server as a ${type} policy, which this CLI version does not manage; delete it in the console or pick another id` });
+      continue;
+    }
+    if (clash) {
+      ops.push({ ...base, op: 'conflict', row: clash, reason: `exists on the server as a ${liveKind(clash, d.table === 'tool' ? 'generic' : 'tool')} policy; delete it or pick another id` });
+      continue;
+    }
+    if (!row) {
+      const owner = nameTakenBy(d, null);
+      ops.push(owner ? nameConflict(base, owner) : { ...base, op: 'create', body: d.body, changes: [] });
+      continue;
+    }
+    // The row is this policy's whatever happens next, so a refused rename
+    // never makes it an orphan as well.
+    (d.table === 'tool' ? matchedTool : matchedGeneric).add(row.id);
+    if (row.name !== d.serverName) {
+      const owner = nameTakenBy(d, row);
+      if (owner) { ops.push(nameConflict(base, owner)); continue; }
+    }
+
+    if (d.table === 'generic' && row.type !== d.body.type) {
+      ops.push({ ...base, op: 'conflict', row, reason: `exists as a ${liveKind(row, 'generic')} policy; a policy cannot change kind. Delete it or pick another id` });
+      continue;
+    }
+    const liveProj = liveProjection(row, d.table);
+    if (d.table === 'tool' && (row.policy_type !== d.body.policy_type || (d.proj.mcp_server && liveProj.mcp_server !== d.proj.mcp_server))) {
+      const what = row.policy_type !== d.body.policy_type ? `type ${row.policy_type} -> ${d.body.policy_type}` : `MCP server ${liveProj.mcp_server} -> ${d.proj.mcp_server}`;
+      ops.push({ ...base, op: 'replace', row, body: d.body, changes: [{ field: 'identity', from: row.policy_type, to: d.body.policy_type }], reason: what });
+      continue;
+    }
+
+    const changes = diffFields(d.proj, liveProj);
+    if (!changes.length) {
+      ops.push({ ...base, op: 'unchanged', row, changes: [] });
+      continue;
+    }
+    const body = {};
+    let unpatchable = null;
+    for (const c of changes) {
+      const mapper = PROJ_TO_BODY[d.table][c.field];
+      const patch = mapper ? mapper(d, row) : null;
+      if (!patch) { unpatchable = c.field; break; }
+      Object.assign(body, patch);
+    }
+    if (unpatchable) {
+      ops.push({ ...base, op: 'replace', row, body: d.body, changes, reason: `${unpatchable} cannot be patched in place` });
+    } else {
+      ops.push({ ...base, op: 'update', row, body, changes });
+    }
+  }
+
+  const orphans = [
+    ...(live.tool || []).filter((r) => !matchedTool.has(r.id)).map((r) => ({ row: r, table: 'tool' })),
+    ...(live.generic || []).filter((r) => !matchedGeneric.has(r.id)).map((r) => ({ row: r, table: 'generic' })),
+  ];
+  for (const { row, table } of orphans) {
+    ops.push({
+      op: prune ? 'delete' : 'orphan',
+      id: row.code_slug || row.name,
+      kind: liveKind(row, table),
+      serverName: row.name,
+      table,
+      row,
+      changes: [],
+      reason: prune ? 'not in the pack file' : 'not in the pack file (kept; pass --prune to delete)',
+    });
+  }
+
+  const order = { conflict: 0, create: 1, update: 2, replace: 3, delete: 4, orphan: 5, unchanged: 6 };
+  ops.sort((a, b) => order[a.op] - order[b.op] || a.serverName.localeCompare(b.serverName));
+  return ops;
+}
+
+function summarize(ops) {
+  const counts = { conflict: 0, create: 0, update: 0, replace: 0, delete: 0, orphan: 0, unchanged: 0 };
+  for (const op of ops) counts[op.op] = (counts[op.op] || 0) + 1;
+  const drift = counts.create + counts.update + counts.replace + counts.delete + counts.conflict;
+  return { ...counts, drift, total: ops.length };
+}
+
+module.exports = {
+  stable,
+  deepEqual,
+  resolveOne,
+  resolveIds,
+  nameOf,
+  normalizeConfig,
+  expandActionType,
+  toDesired,
+  liveProjection,
+  liveKind,
+  diffFields,
+  buildPlan,
+  summarize,
+};