@brunobracaioli/aibrain 0.4.0-beta.3 → 0.4.0-beta.5

package/README.md

@@ -28,6 +28,18 @@ roles. Nothing is written to `~/.codex`, `~/.agents` or the project, and the
 session's folder is deleted on exit. An older Codex starts without the pack and
 says `codex_outdated`.
 
+Licensed `aisac claude` sessions also load guardrail hooks as the session plugin
+`aisac-guardrails`.
+- **Default on:** `secrets-guard` refuses secret files by name. Four more hooks
+  keep continuity: a repository snapshot at start and after a compaction, a
+  docs reminder, and the NOTES/spec/CHANGELOG pass.
+- **Default off:** `git-guard`, `destructive-guard` and `format-on-edit`.
+- **Changing them:** `aisac hooks` lists them, and `aisac hooks enable|disable
+  <id>` or `aisac hooks reset` changes the next session. The agent cannot change
+  them from inside a session.
+- **Code:** it ships in this package and runs locally. Nothing comes from the
+  server.
+
 Codex capture also requires the `flock` utility from `util-linux`, normally
 included in Linux/WSL. The launcher and doctor check availability before a
 monitored Codex session starts. Capture coordination is released by the kernel

package/dist/claude-observation.mjs

@@ -16,7 +16,7 @@ export const MAX_LOG_FILES = 3;
 const LOCK_WAIT_MS = 250;
 const LOCK_STALE_MS = 30_000;
 const ADMISSION_MS = 60 * 60 * 1000;
-export const ADAPTER_VERSION = '0.4.0-beta.3';
+export const ADAPTER_VERSION = '0.4.0-beta.5';
 const MAX_DIAGNOSTIC_COUNT = 10_000_000;
 const MAX_DIAGNOSTIC_BYTES = 128 * 1024 * 1024;
 const CHECKPOINT_BACKENDS = new Set(['native_store', 'private_file']);

package/dist/cli.mjs

@@ -36,8 +36,10 @@ import {
   resolvePackLocale,
   writeStoredLocale,
 } from './engineering-pack.mjs';
+import { extensionsSummary, hooksCommand } from './extensions-cli.mjs';
+import { anyFormatter } from './guardrails/format.mjs';
 
-const VERSION = '0.4.0-beta.3';
+const VERSION = '0.4.0-beta.5';
 // The command is `aisac`; `aibrain` is an alias installed from the same entry.
 const COMMAND = 'aisac';
 const ENDPOINT = 'https://mcp.ai-brain.aisac.cloud/mcp';
@@ -57,6 +59,9 @@ function usage() {
   console.log(
     'AISAC Engineering: `aisac claude` and `aisac codex` (Codex 0.164+) load the licensed method; setup --lang pt-BR|en picks its language; setup and doctor report the license; status stays offline. `aibrain` is an alias of `aisac`.',
   );
+  console.log(
+    'Guardrails: `aisac hooks` lists them (a checklist on a terminal); `aisac hooks enable|disable <id>...` and `aisac hooks reset` change the next `aisac claude` session.',
+  );
 }
 
 // Telemetry is opt-in; setup omits the flag to preserve the stored choice.
@@ -539,6 +544,16 @@ async function setup(args) {
   if (line !== null) console.log(line);
 }
 
+/** Extension state plus whether `format-on-edit` has a formatter in this folder (FR8). */
+async function doctorExtensions() {
+  const summary = await extensionsSummary(stateRoot());
+  if (!summary.hooks.includes('format-on-edit')) return { ...summary, formatOnEdit: 'off' };
+  return {
+    ...summary,
+    formatOnEdit: (await anyFormatter(process.cwd())) ? 'ready' : 'no_formatter_found',
+  };
+}
+
 /** @param {boolean} json */
 async function doctor(json) {
   const platform = platformCheck();
@@ -633,6 +648,7 @@ async function doctor(json) {
     },
     engineering,
     engineeringPack: await engineeringPackState(),
+    extensions: await doctorExtensions(),
     paidOrPilot: probe?.ok
       ? 'provider_free_probe_ok; paid entitlement or pilot invitation remains server-enforced'
       : config
@@ -669,6 +685,7 @@ async function status(json) {
         config?.claudeObservation?.disclosedAt !== undefined,
     },
     engineeringPack: await engineeringPackState(),
+    extensions: await extensionsSummary(stateRoot()),
     monitoredSession: null,
     monitoringStatus: 'not_observed',
   };
@@ -717,6 +734,7 @@ async function main(argv) {
     else console.log(records);
     return;
   }
+  if (command === 'hooks') return hooksCommand(rest);
   if (command === 'disable') {
     if (rest.length > 0) throw new Error('disable_does_not_accept_options');
     return removeOwnedSetup();

package/dist/extensions-catalog.mjs

@@ -0,0 +1,140 @@
+// @ts-check
+/**
+ * The AISAC Engineering extension catalog (spec aisac-engineering-extensions,
+ * FR1, FR2). It ships with the client and is the only source of hooks: the
+ * server and the licensed pack can neither add nor change entries (ADR-0048).
+ * The MCP catalog arrives in E6c.
+ */
+
+/** @typedef {'pt-BR' | 'en'} CatalogLocale */
+/** @typedef {'PreToolUse' | 'PostToolUse' | 'UserPromptSubmit' | 'SessionStart' | 'PreCompact' | 'Stop'} HookEvent */
+/** @typedef {'block' | 'advise' | 'context'} HookMode */
+/**
+ * @typedef {object} HookBinding
+ * @property {HookEvent} event
+ * @property {string} [matcher] Tool names (PreToolUse, PostToolUse) or SessionStart sources.
+ */
+/**
+ * @typedef {object} HookEntry
+ * @property {string} id
+ * @property {HookMode} mode
+ * @property {boolean} defaultOn
+ * @property {readonly ('claude' | 'codex')[]} clients
+ * @property {readonly HookBinding[]} bindings
+ * @property {Readonly<Record<CatalogLocale, string>>} description
+ */
+
+export const CATALOG_ID = /^[a-z][a-z0-9-]{0,31}$/u;
+
+const EDIT_TOOLS = 'Edit|MultiEdit|Write';
+
+/** @type {readonly HookEntry[]} */
+export const HOOK_CATALOG = Object.freeze([
+  {
+    id: 'secrets-guard',
+    mode: 'block',
+    defaultOn: true,
+    clients: ['claude'],
+    bindings: [
+      { event: 'PreToolUse', matcher: 'Read|Edit|MultiEdit|Write|NotebookEdit|Grep|Bash' },
+    ],
+    description: {
+      en: 'Refuses reading or writing secret files (.env, keys, credentials); decides from names only.',
+      'pt-BR':
+        'Recusa ler ou gravar arquivos de segredo (.env, chaves, credenciais); decide só pelo nome.',
+    },
+  },
+  {
+    id: 'git-guard',
+    mode: 'block',
+    defaultOn: false,
+    clients: ['claude'],
+    bindings: [{ event: 'PreToolUse', matcher: 'Bash' }],
+    description: {
+      en: 'Refuses git push to main or master and force pushes (--force-with-lease passes).',
+      'pt-BR': 'Recusa git push na main ou master e push forçado (--force-with-lease passa).',
+    },
+  },
+  {
+    id: 'destructive-guard',
+    mode: 'block',
+    defaultOn: false,
+    clients: ['claude'],
+    bindings: [{ event: 'PreToolUse', matcher: 'Bash' }],
+    description: {
+      en: 'Refuses rm -rf on /, ~, . or .. and DROP DATABASE, DROP TABLE or TRUNCATE.',
+      'pt-BR': 'Recusa rm -rf em /, ~, . ou .. e DROP DATABASE, DROP TABLE ou TRUNCATE.',
+    },
+  },
+  {
+    id: 'format-on-edit',
+    mode: 'advise',
+    defaultOn: false,
+    clients: ['claude'],
+    bindings: [{ event: 'PostToolUse', matcher: EDIT_TOOLS }],
+    description: {
+      en: "Formats the edited file with the project's own formatter, when one is installed.",
+      'pt-BR': 'Formata o arquivo editado com o formatador do próprio projeto, quando houver.',
+    },
+  },
+  {
+    id: 'docs-reminder',
+    mode: 'advise',
+    defaultOn: true,
+    clients: ['claude'],
+    bindings: [{ event: 'PostToolUse', matcher: EDIT_TOOLS }, { event: 'UserPromptSubmit' }],
+    description: {
+      en: 'After a source file changes in a project with docs/, reminds once per turn to update the docs.',
+      'pt-BR':
+        'Quando um arquivo de código muda num projeto com docs/, lembra uma vez por turno de atualizar a documentação.',
+    },
+  },
+  {
+    id: 'session-context',
+    mode: 'context',
+    defaultOn: true,
+    clients: ['claude'],
+    bindings: [{ event: 'SessionStart', matcher: 'startup|resume|clear' }],
+    description: {
+      en: 'Starts the session with a short repository snapshot (branch, status, recent commits).',
+      'pt-BR': 'Abre a sessão com um resumo do repositório (branch, status, commits recentes).',
+    },
+  },
+  {
+    id: 'compact-continuity',
+    mode: 'context',
+    defaultOn: true,
+    clients: ['claude'],
+    bindings: [{ event: 'PreCompact' }, { event: 'SessionStart', matcher: 'compact' }],
+    description: {
+      en: 'Saves a repository snapshot before a compaction and restores it right after.',
+      'pt-BR': 'Salva um resumo do repositório antes do compact e o devolve logo depois.',
+    },
+  },
+  {
+    id: 'continuity-reminder',
+    mode: 'block',
+    defaultOn: true,
+    clients: ['claude'],
+    bindings: [
+      { event: 'PostToolUse', matcher: EDIT_TOOLS },
+      { event: 'UserPromptSubmit' },
+      { event: 'Stop' },
+    ],
+    description: {
+      en: 'In a project with NOTES.md, asks once per turn to update NOTES.md, the spec or the CHANGELOG after code changes.',
+      'pt-BR':
+        'Num projeto com NOTES.md, pede uma vez por turno para atualizar NOTES.md, a spec ou o CHANGELOG depois de mudanças no código.',
+    },
+  },
+]);
+
+/** @param {string} id @returns {HookEntry | undefined} */
+export function hookById(id) {
+  return HOOK_CATALOG.find((entry) => entry.id === id);
+}
+
+/** @returns {string[]} */
+export function hookIds() {
+  return HOOK_CATALOG.map((entry) => entry.id);
+}

package/dist/extensions-cli.mjs

@@ -0,0 +1,239 @@
+// @ts-check
+/**
+ * `aisac hooks` (spec aisac-engineering-extensions FR4): list, enable,
+ * disable and reset guardrail hooks, offline. On a TTY without arguments it
+ * opens a checklist. Choices apply to the next session; running sessions
+ * keep their set.
+ */
+import { emitKeypressEvents } from 'node:readline';
+import { HOOK_CATALOG, hookById, hookIds } from './extensions-catalog.mjs';
+import {
+  readPreferences,
+  resolveHooks,
+  unknownHookIds,
+  writePreferences,
+} from './extensions-preferences.mjs';
+import { readLastLaunch, readStoredLocale, resolvePackLocale } from './engineering-pack.mjs';
+import { stateRoot } from './state.mjs';
+
+const USAGE_EXIT_CODE = 2;
+const ID_WIDTH = Math.max(...HOOK_CATALOG.map((entry) => entry.id.length));
+const NEXT_SESSION =
+  'Applies to the next `aisac claude` session; running sessions keep their current set.';
+const LICENSE_NOTE = 'Hooks load only with an active AISAC Engineering license.';
+const CHECKLIST_HEADER =
+  'AISAC Engineering hooks: up/down moves, space toggles, enter saves, q cancels.';
+const DEFAULT_COLUMNS = 80;
+const MIN_COLUMNS = 20;
+const ELLIPSIS = '…';
+
+/**
+ * Cut a checklist row to the terminal width. The redraw moves the cursor up one
+ * row per hook, which only holds while no row wraps; one column stays free so
+ * no terminal wraps at the last column either.
+ * @param {string} line
+ * @param {number | undefined} columns
+ */
+export function fitLine(line, columns) {
+  const total =
+    typeof columns === 'number' && Number.isInteger(columns) && columns > 0
+      ? columns
+      : DEFAULT_COLUMNS;
+  const width = Math.max(MIN_COLUMNS, total) - 1;
+  const characters = [...line];
+  if (characters.length <= width) return line;
+  return `${characters.slice(0, width - 1).join('')}${ELLIPSIS}`;
+}
+
+/**
+ * @typedef {object} ChecklistState
+ * @property {number} cursor
+ * @property {boolean[]} enabled
+ */
+
+/**
+ * One key press in the checklist (pure, tested without a TTY).
+ * @param {ChecklistState} state
+ * @param {{ name?: string, ctrl?: boolean, sequence?: string }} key
+ * @returns {{ state: ChecklistState, done: 'save' | 'cancel' | null }}
+ */
+export function checklistStep(state, key) {
+  const last = state.enabled.length - 1;
+  if ((key.ctrl === true && key.name === 'c') || key.name === 'escape' || key.name === 'q')
+    return { state, done: 'cancel' };
+  if (key.name === 'return' || key.name === 'enter') return { state, done: 'save' };
+  if (key.name === 'up' || key.name === 'k')
+    return { state: { ...state, cursor: Math.max(0, state.cursor - 1) }, done: null };
+  if (key.name === 'down' || key.name === 'j')
+    return { state: { ...state, cursor: Math.min(last, state.cursor + 1) }, done: null };
+  if (key.name === 'space' || key.sequence === ' ') {
+    const enabled = state.enabled.map((value, index) => (index === state.cursor ? !value : value));
+    return { state: { ...state, enabled }, done: null };
+  }
+  return { state, done: null };
+}
+
+/** @param {'pt-BR' | 'en'} locale @param {ReturnType<typeof resolveHooks>} hooks @param {ChecklistState} [state] */
+function renderLines(locale, hooks, state) {
+  return hooks.map((hook, index) => {
+    const enabled = state === undefined ? hook.enabled : state.enabled[index];
+    const pointer = state === undefined ? ' ' : index === state.cursor ? '>' : ' ';
+    const source = state === undefined ? ` ${hook.source.padEnd(7)}` : '';
+    return `${pointer} [${enabled ? 'x' : ' '}] ${hook.entry.id.padEnd(ID_WIDTH)}  ${hook.entry.mode.padEnd(8)}${source}  ${hook.entry.description[locale]}`;
+  });
+}
+
+/** @param {string} root */
+async function licensedLastLaunch(root) {
+  const last = await readLastLaunch(root);
+  return last?.state === 'loaded';
+}
+
+/**
+ * Store explicit choices, keeping MCP choices as they are.
+ * @param {Record<string, boolean>} hooks
+ */
+async function saveHooks(hooks) {
+  const current = await readPreferences(stateRoot());
+  await writePreferences({ hooks, mcp: current.status === 'valid' ? current.mcp : {} });
+  if (current.status === 'invalid')
+    console.log('The previous extensions file was invalid and was replaced.');
+}
+
+/** @param {string[]} ids */
+function unknownIds(ids) {
+  return ids.filter((id) => hookById(id) === undefined);
+}
+
+/** @param {boolean} licensed */
+function afterChange(licensed) {
+  console.log(NEXT_SESSION);
+  if (!licensed) console.log(LICENSE_NOTE);
+}
+
+/**
+ * Interactive checklist. Resolves to the new enabled flags, or null on cancel.
+ * @param {'pt-BR' | 'en'} locale @param {ReturnType<typeof resolveHooks>} hooks
+ * @returns {Promise<boolean[] | null>}
+ */
+function runChecklist(locale, hooks) {
+  return new Promise((resolve) => {
+    let state = { cursor: 0, enabled: hooks.map((hook) => hook.enabled) };
+    const draw = (/** @type {boolean} */ first) => {
+      if (!first) process.stdout.write(`\u001b[${hooks.length}A\u001b[J`);
+      const rows = renderLines(locale, hooks, state).map((line) =>
+        fitLine(line, process.stdout.columns),
+      );
+      process.stdout.write(`${rows.join('\n')}\n`);
+    };
+    console.log(CHECKLIST_HEADER);
+    draw(true);
+    emitKeypressEvents(process.stdin);
+    process.stdin.setRawMode(true);
+    process.stdin.resume();
+    /** @param {string} _text @param {{ name?: string, ctrl?: boolean, sequence?: string }} key */
+    const onKey = (_text, key) => {
+      const step = checklistStep(state, key ?? {});
+      state = step.state;
+      if (step.done === null) return draw(false);
+      process.stdin.off('keypress', onKey);
+      process.stdin.setRawMode(false);
+      process.stdin.pause();
+      resolve(step.done === 'save' ? state.enabled : null);
+    };
+    process.stdin.on('keypress', onKey);
+  });
+}
+
+/**
+ * `aisac hooks [list|enable|disable|reset] [ids...] [--json]`.
+ * @param {string[]} args
+ */
+export async function hooksCommand(args) {
+  const json = args.includes('--json');
+  const words = args.filter((arg) => arg !== '--json');
+  const [action = 'list', ...ids] = words;
+  const root = stateRoot();
+  const locale = resolvePackLocale(await readStoredLocale(root));
+  const preferences = await readPreferences(root);
+  const hooks = resolveHooks(preferences);
+  const licensed = await licensedLastLaunch(root);
+
+  if (action === 'list' && ids.length === 0) {
+    if (json) {
+      console.log(
+        JSON.stringify({
+          preferences: preferences.status,
+          licensedLastLaunch: licensed,
+          hooks: hooks.map((hook) => ({
+            id: hook.entry.id,
+            enabled: hook.enabled,
+            source: hook.source,
+            mode: hook.entry.mode,
+            clients: hook.entry.clients,
+            description: hook.entry.description[locale],
+          })),
+          unknown: unknownHookIds(preferences),
+        }),
+      );
+      return;
+    }
+    if (args.length === 0 && process.stdin.isTTY && process.stdout.isTTY) {
+      const chosen = await runChecklist(locale, hooks);
+      if (chosen === null) return console.log('No change.');
+      /** @type {Record<string, boolean>} */
+      const choices = preferences.status === 'valid' ? { ...preferences.hooks } : {};
+      hooks.forEach((hook, index) => {
+        if (chosen[index] !== hook.enabled) choices[hook.entry.id] = chosen[index] === true;
+      });
+      await saveHooks(choices);
+      return afterChange(licensed);
+    }
+    console.log('AISAC Engineering hooks (Claude Code):');
+    console.log(renderLines(locale, hooks).join('\n'));
+    if (preferences.status === 'invalid')
+      console.log('The extensions file is invalid: the defaults apply. Run `aisac hooks reset`.');
+    console.log(
+      'Change with `aisac hooks enable <id>`, `aisac hooks disable <id>` or `aisac hooks reset`.',
+    );
+    if (!licensed) console.log(LICENSE_NOTE);
+    return;
+  }
+  if (action === 'reset' && ids.length === 0) {
+    await saveHooks({});
+    console.log('Hooks reset to the defaults.');
+    return afterChange(licensed);
+  }
+  if ((action === 'enable' || action === 'disable') && ids.length > 0) {
+    const unknown = unknownIds(ids);
+    if (unknown.length > 0) {
+      console.error(
+        `aisac: unknown hook id: ${unknown.join(', ')}. Valid: ${hookIds().join(', ')}.`,
+      );
+      process.exitCode = USAGE_EXIT_CODE;
+      return;
+    }
+    /** @type {Record<string, boolean>} */
+    const choices = preferences.status === 'valid' ? { ...preferences.hooks } : {};
+    for (const id of ids) choices[id] = action === 'enable';
+    await saveHooks(choices);
+    console.log(`${action === 'enable' ? 'Enabled' : 'Disabled'}: ${ids.join(', ')}.`);
+    return afterChange(licensed);
+  }
+  console.error(
+    'aisac: usage: aisac hooks [--json] | aisac hooks enable <id>... | aisac hooks disable <id>... | aisac hooks reset',
+  );
+  process.exitCode = USAGE_EXIT_CODE;
+}
+
+/** Offline extension summary for `status` and `doctor`. @param {string} root */
+export async function extensionsSummary(root) {
+  const preferences = await readPreferences(root);
+  return {
+    preferences: preferences.status,
+    hooks: resolveHooks(preferences)
+      .filter((hook) => hook.enabled)
+      .map((hook) => hook.entry.id),
+    unknown: unknownHookIds(preferences),
+  };
+}

package/dist/extensions-preferences.mjs

@@ -0,0 +1,122 @@
+// @ts-check
+/**
+ * The user's extension choices (spec aisac-engineering-extensions FR3):
+ * `<state>/extensions.json`, mode 0600, written atomically, at most 16 KiB.
+ * Only explicit choices are stored; a missing id means the catalog default.
+ * An invalid file never fails a launch: hooks fall back to the defaults and
+ * every MCP server stays off.
+ */
+import { lstat, readFile } from 'node:fs/promises';
+import { join } from 'node:path';
+import { atomicJson, ensureStateRoot } from './state.mjs';
+import { CATALOG_ID, HOOK_CATALOG, hookById } from './extensions-catalog.mjs';
+
+export const EXTENSIONS_FILE = 'extensions.json';
+const SCHEMA_VERSION = 1;
+const MAX_PREFERENCES_BYTES = 16 * 1024;
+const MAX_CHOICES = 64;
+const TOP_LEVEL_KEYS = ['hooks', 'mcp', 'schemaVersion'];
+
+/**
+ * @typedef {object} ExtensionPreferences
+ * @property {'missing' | 'valid' | 'invalid'} status
+ * @property {Record<string, boolean>} hooks
+ * @property {Record<string, boolean>} mcp
+ */
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function isRecord(value) {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {Record<string, boolean> | null} */
+function choices(value) {
+  if (!isRecord(value)) return null;
+  const entries = Object.entries(value);
+  if (entries.length > MAX_CHOICES) return null;
+  /** @type {Record<string, boolean>} */
+  const result = {};
+  for (const [id, enabled] of entries) {
+    if (!CATALOG_ID.test(id) || typeof enabled !== 'boolean') return null;
+    result[id] = enabled;
+  }
+  return result;
+}
+
+/**
+ * Validate a parsed preferences document. @param {unknown} value
+ * @returns {{ hooks: Record<string, boolean>, mcp: Record<string, boolean> } | null}
+ */
+export function parsePreferences(value) {
+  if (!isRecord(value)) return null;
+  const keys = Object.keys(value).sort();
+  if (keys.length !== TOP_LEVEL_KEYS.length || keys.some((key, i) => key !== TOP_LEVEL_KEYS[i]))
+    return null;
+  if (value.schemaVersion !== SCHEMA_VERSION) return null;
+  const hooks = choices(value.hooks);
+  const mcp = choices(value.mcp);
+  return hooks === null || mcp === null ? null : { hooks, mcp };
+}
+
+/** @param {string} root @returns {string} */
+export function preferencesPath(root) {
+  return join(root, EXTENSIONS_FILE);
+}
+
+/** @param {string} root @returns {Promise<ExtensionPreferences>} */
+export async function readPreferences(root) {
+  const path = preferencesPath(root);
+  try {
+    const info = await lstat(path);
+    if (!info.isFile() || info.size > MAX_PREFERENCES_BYTES)
+      return { status: 'invalid', hooks: {}, mcp: {} };
+    const parsed = parsePreferences(JSON.parse(await readFile(path, 'utf8')));
+    return parsed === null
+      ? { status: 'invalid', hooks: {}, mcp: {} }
+      : { status: 'valid', ...parsed };
+  } catch (error) {
+    const missing = error instanceof Error && 'code' in error && error.code === 'ENOENT';
+    return { status: missing ? 'missing' : 'invalid', hooks: {}, mcp: {} };
+  }
+}
+
+/**
+ * Store choices. Only valid catalog ids reach this point (the CLI checks).
+ * @param {{ hooks: Record<string, boolean>, mcp: Record<string, boolean> }} value
+ */
+export async function writePreferences(value) {
+  const root = await ensureStateRoot();
+  await atomicJson(preferencesPath(root), {
+    schemaVersion: SCHEMA_VERSION,
+    hooks: value.hooks,
+    mcp: value.mcp,
+  });
+}
+
+/**
+ * Each catalog hook with its effective state. An invalid file means defaults.
+ * @param {ExtensionPreferences} preferences
+ */
+export function resolveHooks(preferences) {
+  const chosen = preferences.status === 'valid' ? preferences.hooks : {};
+  return HOOK_CATALOG.map((entry) => {
+    const choice = chosen[entry.id];
+    return {
+      entry,
+      enabled: choice ?? entry.defaultOn,
+      source: /** @type {'default' | 'choice'} */ (choice === undefined ? 'default' : 'choice'),
+    };
+  });
+}
+
+/** @param {ExtensionPreferences} preferences @returns {string[]} */
+export function enabledHookIds(preferences) {
+  return resolveHooks(preferences)
+    .filter((hook) => hook.enabled)
+    .map((hook) => hook.entry.id);
+}
+
+/** Ids stored in the file that this client's catalog does not know. @param {ExtensionPreferences} preferences */
+export function unknownHookIds(preferences) {
+  return Object.keys(preferences.hooks).filter((id) => hookById(id) === undefined);
+}