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

package/dist/guardrails/shell-words.mjs

@@ -0,0 +1,206 @@
+// @ts-check
+/**
+ * A small POSIX-style shell word splitter for guardrail decisions. It never
+ * runs anything. It keeps quotes, escapes and command substitutions inside
+ * their word, splits commands on control operators, and marks redirection
+ * targets. When the text cannot be split (an unterminated quote), `ok` is
+ * false and callers fall back to a word-boundary scan of the raw text.
+ */
+
+/**
+ * @typedef {object} ShellCommand
+ * @property {string[]} words Words of one simple command, without redirections.
+ * @property {string[]} targets File targets of its redirections (`>`, `>>`, `<`, `&>`, ...).
+ */
+
+const CONTROL_OPERATORS = ['&&', '||', ';;', '|&', ';', '|', '&', '(', ')'];
+const REDIRECTIONS = ['&>>', '&>', '>>', '>|', '<>', '<<<', '<<', '>', '<'];
+const HEREDOC_OPERATORS = new Set(['<<', '<<<']);
+const MAX_COMMAND_LENGTH = 64 * 1024;
+
+/** @param {string} text @param {number} index @param {string[]} candidates */
+function operatorAt(text, index, candidates) {
+  return candidates.find((candidate) => text.startsWith(candidate, index));
+}
+
+/**
+ * Read a `$(...)` or backtick substitution verbatim, so its text stays in the word.
+ * @param {string} text @param {number} start index of `$(` or the backtick
+ * @returns {number} index after the substitution, or -1 when it never closes
+ */
+function substitutionEnd(text, start) {
+  if (text[start] === '`') {
+    const close = text.indexOf('`', start + 1);
+    return close === -1 ? -1 : close + 1;
+  }
+  let depth = 0;
+  for (let index = start; index < text.length; index += 1) {
+    if (text[index] === '(') depth += 1;
+    else if (text[index] === ')') {
+      depth -= 1;
+      if (depth === 0) return index + 1;
+    }
+  }
+  return -1;
+}
+
+/**
+ * Split a shell command line into simple commands.
+ * @param {string} text
+ * @returns {{ ok: boolean, commands: ShellCommand[] }}
+ */
+export function splitShell(text) {
+  if (typeof text !== 'string' || text.length > MAX_COMMAND_LENGTH)
+    return { ok: false, commands: [] };
+  /** @type {ShellCommand[]} */
+  const commands = [];
+  /** @type {ShellCommand} */
+  let current = { words: [], targets: [] };
+  let word = '';
+  let inWord = false;
+  /** @type {string | null} */
+  let pendingRedirection = null;
+
+  const endWord = () => {
+    if (!inWord) return;
+    if (pendingRedirection !== null) {
+      if (!HEREDOC_OPERATORS.has(pendingRedirection)) current.targets.push(word);
+      pendingRedirection = null;
+    } else current.words.push(word);
+    word = '';
+    inWord = false;
+  };
+  const endCommand = () => {
+    endWord();
+    if (current.words.length > 0 || current.targets.length > 0) commands.push(current);
+    current = { words: [], targets: [] };
+  };
+
+  let index = 0;
+  while (index < text.length) {
+    const char = text[index];
+    if (char === ' ' || char === '\t') {
+      endWord();
+      index += 1;
+    } else if (char === '\n') {
+      endCommand();
+      index += 1;
+    } else if (char === '#' && !inWord) {
+      const newline = text.indexOf('\n', index);
+      index = newline === -1 ? text.length : newline;
+    } else if (char === "'") {
+      const close = text.indexOf("'", index + 1);
+      if (close === -1) return { ok: false, commands: [] };
+      word += text.slice(index + 1, close);
+      inWord = true;
+      index = close + 1;
+    } else if (char === '"') {
+      let cursor = index + 1;
+      let closed = false;
+      while (cursor < text.length) {
+        const inner = text[cursor];
+        if (
+          inner === '\\' &&
+          cursor + 1 < text.length &&
+          '"\\$`\n'.includes(text[cursor + 1] ?? '')
+        ) {
+          if (text[cursor + 1] !== '\n') word += text[cursor + 1];
+          cursor += 2;
+        } else if (inner === '"') {
+          closed = true;
+          cursor += 1;
+          break;
+        } else if (inner === '$' && text[cursor + 1] === '(') {
+          const end = substitutionEnd(text, cursor + 1);
+          if (end === -1) return { ok: false, commands: [] };
+          word += text.slice(cursor, end);
+          cursor = end;
+        } else {
+          word += inner;
+          cursor += 1;
+        }
+      }
+      if (!closed) return { ok: false, commands: [] };
+      inWord = true;
+      index = cursor;
+    } else if (char === '\\') {
+      if (text[index + 1] === '\n') index += 2;
+      else {
+        word += text[index + 1] ?? '';
+        inWord = true;
+        index += 2;
+      }
+    } else if ((char === '$' && text[index + 1] === '(') || char === '`') {
+      const end = substitutionEnd(text, char === '`' ? index : index + 1);
+      if (end === -1) return { ok: false, commands: [] };
+      word += text.slice(index, end);
+      inWord = true;
+      index = end;
+    } else {
+      const redirection = operatorAt(text, index, REDIRECTIONS);
+      const descriptorWord = inWord && /^\d+$/u.test(word);
+      if (redirection !== undefined && (!inWord || descriptorWord)) {
+        if (descriptorWord) {
+          word = '';
+          inWord = false;
+        } else endWord();
+        index += redirection.length;
+        // `2>&1` and `>&2` duplicate a descriptor; they name no file.
+        if (text[index] === '&' && /\d|-/u.test(text[index + 1] ?? '')) {
+          index += 2;
+          continue;
+        }
+        pendingRedirection = redirection;
+        continue;
+      }
+      const operator = operatorAt(text, index, CONTROL_OPERATORS);
+      if (operator !== undefined) {
+        endCommand();
+        index += operator.length;
+        continue;
+      }
+      word += char;
+      inWord = true;
+      index += 1;
+    }
+  }
+  endCommand();
+  return { ok: true, commands };
+}
+
+/** Basename of a program word (`/usr/bin/git` -> `git`). @param {string} word */
+export function programName(word) {
+  const slash = word.lastIndexOf('/');
+  return slash === -1 ? word : word.slice(slash + 1);
+}
+
+const WRAPPERS = new Set([
+  'sudo',
+  'doas',
+  'env',
+  'command',
+  'nice',
+  'nohup',
+  'time',
+  'exec',
+  'npx',
+  'bunx',
+]);
+
+/**
+ * The words of a command with leading `VAR=value` assignments and wrappers
+ * such as `sudo` or `env` removed, so `sudo rm -rf /` is seen as `rm -rf /`.
+ * @param {string[]} words
+ */
+export function effectiveWords(words) {
+  let index = 0;
+  while (index < words.length) {
+    const word = words[index] ?? '';
+    if (/^[A-Za-z_][A-Za-z0-9_]*=/u.test(word)) index += 1;
+    else if (WRAPPERS.has(programName(word))) {
+      index += 1;
+      while ((words[index] ?? '').startsWith('-')) index += 1;
+    } else break;
+  }
+  return words.slice(index);
+}

package/dist/guardrails-plugin.mjs

@@ -0,0 +1,149 @@
+// @ts-check
+/**
+ * The session plugin `aisac-guardrails` (spec aisac-engineering-extensions
+ * FR5): written into the launch's private folder with only the enabled
+ * hooks, and deleted with that folder on exit. Every command is the absolute
+ * Node executable plus the dispatcher inside the installed package; nothing
+ * comes from the server (ADR-0048).
+ */
+import { access, mkdir, writeFile } from 'node:fs/promises';
+import { isAbsolute, join } from 'node:path';
+import { hookById } from './extensions-catalog.mjs';
+import { enabledHookIds, preferencesPath, readPreferences } from './extensions-preferences.mjs';
+import { readStoredLocale, resolvePackLocale } from './engineering-pack.mjs';
+
+export const GUARDRAILS_PLUGIN_NAME = 'aisac-guardrails';
+const PLUGIN_VERSION = '1.0.0';
+const PLUGIN_DIRECTORY = 'guardrails';
+const STATE_DIRECTORY = 'guardrails-state';
+const DISPATCHER = join('guardrails', 'run.mjs');
+const CONTROL_CHARACTERS = /[\u0000-\u001f\u007f]/u;
+/** @type {Readonly<Record<string, number>>} */
+const TIMEOUT_SECONDS = Object.freeze({
+  PreToolUse: 5,
+  PostToolUse: 5,
+  UserPromptSubmit: 5,
+  Stop: 5,
+  SessionStart: 10,
+  PreCompact: 10,
+});
+
+/** POSIX single-quote quoting for the host's shell. @param {string} value */
+export function shellQuote(value) {
+  return `'${value.replaceAll("'", "'\\''")}'`;
+}
+
+/** @param {string} path */
+function safeAbsolute(path) {
+  return isAbsolute(path) && !CONTROL_CHARACTERS.test(path);
+}
+
+/**
+ * The plugin's hooks.json for the enabled ids: one entry per event, whose
+ * matcher is the union of the enabled hooks' matchers for that event.
+ * @param {string[]} enabled
+ * @param {{ node: string, dispatcher: string, stateDir: string, prefsPath: string, locale: 'pt-BR' | 'en' }} paths
+ */
+export function guardrailsHooks(enabled, paths) {
+  /** @type {Map<string, { ids: string[], matchers: Set<string>, unmatched: boolean }>} */
+  const events = new Map();
+  for (const id of enabled) {
+    for (const binding of hookById(id)?.bindings ?? []) {
+      const current = events.get(binding.event) ?? {
+        ids: [],
+        matchers: new Set(),
+        unmatched: false,
+      };
+      if (!current.ids.includes(id)) current.ids.push(id);
+      if (binding.matcher === undefined) current.unmatched = true;
+      else for (const name of binding.matcher.split('|')) current.matchers.add(name);
+      events.set(binding.event, current);
+    }
+  }
+  /** @type {Record<string, unknown[]>} */
+  const hooks = {};
+  for (const [event, group] of events) {
+    const command = [
+      shellQuote(paths.node),
+      shellQuote(paths.dispatcher),
+      '--event',
+      event,
+      '--hooks',
+      group.ids.join(','),
+      '--state',
+      shellQuote(paths.stateDir),
+      '--prefs',
+      shellQuote(paths.prefsPath),
+      '--locale',
+      paths.locale,
+    ].join(' ');
+    hooks[event] = [
+      {
+        ...(group.unmatched || group.matchers.size === 0
+          ? {}
+          : { matcher: [...group.matchers].join('|') }),
+        hooks: [{ type: 'command', command, timeout: TIMEOUT_SECONDS[event] ?? 5 }],
+      },
+    ];
+  }
+  return {
+    description: 'AISAC Engineering guardrails for this session (aisac hooks to change them).',
+    hooks,
+  };
+}
+
+/**
+ * Write the plugin for a licensed launch. Null when no hook is enabled or the
+ * package lacks the dispatcher; the launch then goes on without it.
+ * @param {{ directory: string, root: string, packageRoot: string }} input
+ * @returns {Promise<{ pluginRoot: string, count: number, line: string } | null>}
+ */
+export async function prepareGuardrails(input) {
+  const enabled = enabledHookIds(await readPreferences(input.root));
+  if (enabled.length === 0) return null;
+  const dispatcher = join(input.packageRoot, DISPATCHER);
+  const prefsPath = preferencesPath(input.root);
+  const pluginRoot = join(input.directory, PLUGIN_DIRECTORY);
+  const stateDir = join(input.directory, STATE_DIRECTORY);
+  if (![process.execPath, dispatcher, prefsPath, pluginRoot, stateDir].every(safeAbsolute))
+    return null;
+  if (
+    !(await access(dispatcher).then(
+      () => true,
+      () => false,
+    ))
+  )
+    return null;
+  const locale = resolvePackLocale(await readStoredLocale(input.root));
+  await mkdir(join(pluginRoot, '.claude-plugin'), { recursive: true, mode: 0o700 });
+  await mkdir(join(pluginRoot, 'hooks'), { mode: 0o700 });
+  await mkdir(stateDir, { mode: 0o700 });
+  const manifest = {
+    name: GUARDRAILS_PLUGIN_NAME,
+    version: PLUGIN_VERSION,
+    description: 'AISAC Engineering guardrail hooks, loaded for this session only.',
+    author: { name: 'AISAC' },
+    hooks: './hooks/hooks.json',
+  };
+  const hooks = guardrailsHooks(enabled, {
+    node: process.execPath,
+    dispatcher,
+    stateDir,
+    prefsPath,
+    locale,
+  });
+  await writeFile(
+    join(pluginRoot, '.claude-plugin', 'plugin.json'),
+    `${JSON.stringify(manifest, null, 2)}\n`,
+    { mode: 0o600, flag: 'wx' },
+  );
+  await writeFile(join(pluginRoot, 'hooks', 'hooks.json'), `${JSON.stringify(hooks, null, 2)}\n`, {
+    mode: 0o600,
+    flag: 'wx',
+  });
+  return {
+    pluginRoot,
+    count: enabled.length,
+    line: `AISAC Engineering: ${enabled.length} guardrail${enabled.length === 1 ? '' : 's'} on (aisac hooks to change them).`,
+  };
+}

package/dist/launch.mjs

@@ -18,6 +18,7 @@ import {
   sweepStaleLaunches,
   writeLaunchMarker,
 } from './engineering-pack.mjs';
+import { prepareGuardrails } from './guardrails-plugin.mjs';
 import {
   CODEX_ENGINEERING_ENV,
   CODEX_ENGINEERING_SKILLS_ROOT_ENV,
@@ -428,6 +429,7 @@ function waitForChild(child, directory) {
 /**
  * @typedef {object} LaunchDependencies
  * @property {typeof prepareEngineeringPack} [preparePack] AISAC Engineering pack loader (E4b)
+ * @property {typeof prepareGuardrails} [prepareGuardrails] Guardrail hooks plugin writer (E6a)
  */
 
 /**
@@ -438,6 +440,7 @@ function waitForChild(child, directory) {
  */
 export async function launchClaude(config, root, args, dependencies = {}) {
   const preparePack = dependencies.preparePack ?? prepareEngineeringPack;
+  const writeGuardrails = dependencies.prepareGuardrails ?? prepareGuardrails;
   const validated = assertConfig(config);
   const launchArgs = await parseClaudeLaunchArgs(args, process.cwd());
   assertClaudeArgs(launchArgs.args);
@@ -578,6 +581,15 @@ export async function launchClaude(config, root, args, dependencies = {}) {
     packageRoot: validated.packageRoot,
   }).catch(() => ({ pluginRoot: null, line: null }));
   if (engineering.line !== null) process.stderr.write(`${engineering.line}\n`);
+  // Guardrails need the license this launch confirmed (the pack loaded), and
+  // like the pack they never block the launch (spec aisac-engineering-extensions FR5).
+  const guardrails =
+    engineering.pluginRoot === null
+      ? null
+      : await writeGuardrails({ directory, root, packageRoot: validated.packageRoot }).catch(
+          () => null,
+        );
+  if (guardrails !== null) process.stderr.write(`${guardrails.line}\n`);
   const environment = childEnvironment(root);
   environment.CLAUDE_CODE_ENABLE_FUNCTION_HOOKS = '1';
   /** @type {import('node:child_process').ChildProcess} */
@@ -595,6 +607,7 @@ export async function launchClaude(config, root, args, dependencies = {}) {
         '--plugin-dir',
         pluginRoot,
         ...(engineering.pluginRoot === null ? [] : ['--plugin-dir', engineering.pluginRoot]),
+        ...(guardrails === null ? [] : ['--plugin-dir', guardrails.pluginRoot]),
         ...launchArgs.args,
       ],
       { cwd: process.cwd(), env: environment, stdio: 'inherit' },

package/dist/package.json

@@ -1,5 +1,5 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.4.0-beta.3",
+  "version": "0.4.0-beta.4",
   "type": "module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brunobracaioli/aibrain",
-  "version": "0.4.0-beta.3",
+  "version": "0.4.0-beta.4",
   "private": false,
   "description": "AISAC client for Claude Code and Codex: AI Brain memory, context management and AISAC Engineering",
   "license": "UNLICENSED",