@brunobracaioli/aibrain 0.3.0-beta.7 → 0.4.0-beta.2

package/dist/claude-compatibility.mjs

@@ -0,0 +1,506 @@
+// @ts-check
+
+import {
+  chmod,
+  cp,
+  lstat,
+  mkdir,
+  mkdtemp,
+  readdir,
+  realpath,
+  rm,
+  writeFile,
+} from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { tmpdir } from 'node:os';
+import { spawn } from 'node:child_process';
+
+const MAX_OUTPUT_BYTES = 96 * 1024;
+const PROBE_TIMEOUT_MS = 30_000;
+const MAX_PLUGIN_ASSET_BYTES = 4 * 1024 * 1024;
+const MAX_PLUGIN_TOTAL_BYTES = 16 * 1024 * 1024;
+const HOST_MAJOR = 2;
+const HOST_MINOR = 1;
+const QUALIFIED_VERSIONS = new Set([
+  '2.1.294',
+  '2.1.295',
+  '2.1.296',
+  '2.1.299',
+  '2.1.300',
+  '2.1.301',
+  '2.1.302',
+  '2.1.303',
+]);
+const REQUIRED_FLAGS = ['--settings', '--mcp-config', '--allowedTools', '--plugin-dir'];
+const REQUIRED_INVENTORY = [
+  'prompt.submit',
+  'tool.call',
+  'session.end',
+  'turn.complete',
+  'session.compact',
+  '$.mcp.call',
+  '$.process.run',
+  '$.session.id',
+  '$.session.messages',
+  '$.session.usage',
+  '$.session.append',
+  '$.session.compact',
+  '$.store.get',
+  '$.store.set',
+  '$.store.delete',
+  '$.store.keys',
+  '$.ui.log',
+  '$.ui.toast',
+];
+const ALLOWED_PLUGIN_FILES = Object.freeze([
+  '.claude-plugin/plugin.json',
+  'hooks/hooks.json',
+  'hooks/context-compaction.ts',
+  'hooks/provider-window.js',
+  'hooks/state-fitting.mjs',
+  'hooks/state-fitting.d.mts',
+  'hooks/native-host-contract.test.ts',
+  'hooks/native-host-contract-runtime.ts',
+]);
+
+/** @param {string} executable */
+function safePath(executable) {
+  return [...new Set([dirname(executable), dirname(process.execPath), '/usr/bin', '/bin'])].join(
+    ':',
+  );
+}
+
+/** @param {string} executable @returns {Promise<string>} */
+async function readNativeVersion(executable) {
+  const root = await mkdtemp(join(tmpdir(), 'aibrain-claude-version-'));
+  const cwd = join(root, 'cwd');
+  const home = join(root, 'home');
+  const config = join(root, 'config');
+  await mkdir(cwd, { recursive: true, mode: 0o700 });
+  try {
+    /** @type {NodeJS.ProcessEnv} */
+    const environment = {
+      PATH: safePath(executable),
+      HOME: home,
+      CLAUDE_CONFIG_DIR: config,
+      CLAUDE_COMPAT_CWD: cwd,
+      NO_COLOR: '1',
+      CI: '1',
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+    };
+    await mkdir(home, { recursive: true, mode: 0o700 });
+    await mkdir(config, { recursive: true, mode: 0o700 });
+    const result = await runBounded(executable, ['--version'], environment, {
+      timeoutMs: 10_000,
+      maxOutputBytes: 2_048,
+    });
+    if (result.code !== 0 || result.overflow || result.timedOut) return '';
+    return result.stdout.split(/\r?\n/u, 1)[0]?.trim() ?? '';
+  } finally {
+    try {
+      await rm(root, { recursive: true, force: true });
+    } catch {
+      throw new Error('probe_cleanup_failed');
+    }
+  }
+}
+
+/** @typedef {'qualified'|'host_checked'|'rejected'} ClaudeCompatibilityStatus */
+
+/** @typedef {object} ClaudeCompatibility
+ * @property {ClaudeCompatibilityStatus} status
+ * @property {string|null} executable
+ * @property {string|null} version
+ * @property {string} reason
+ * @property {string[]} [checks]
+ */
+
+/** @param {string} output */
+export function parseClaudeStableVersion(output) {
+  const match = output
+    .trim()
+    .match(
+      /^(?:(?:claude(?:\s+code)?)\s+)?(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})\.(0|[1-9]\d{0,2})(-[A-Za-z0-9.-]+)?(?:\s+\(Claude\s+Code\))?$/iu,
+    );
+  if (!match) return null;
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease: match[4] !== undefined,
+    text: `${match[1]}.${match[2]}.${match[3]}`,
+  };
+}
+
+/** @param {string} output */
+function parseVersion(output) {
+  return parseClaudeStableVersion(output) ?? null;
+}
+
+/** @param {string} executable @param {string[]} args @param {NodeJS.ProcessEnv} environment @param {{timeoutMs?:number,maxOutputBytes?:number}} [limits] */
+function runBounded(executable, args, environment, limits = {}) {
+  const timeoutMs = limits.timeoutMs ?? PROBE_TIMEOUT_MS;
+  const maxOutputBytes = limits.maxOutputBytes ?? MAX_OUTPUT_BYTES;
+  return new Promise((resolvePromise) => {
+    const child = spawn(executable, args, {
+      cwd: environment.CLAUDE_COMPAT_CWD,
+      env: environment,
+      stdio: ['ignore', 'pipe', 'pipe'],
+      detached: process.platform !== 'win32',
+    });
+    let stdout = '';
+    let stderr = '';
+    let bytes = 0;
+    let overflow = false;
+    let settled = false;
+    let timedOut = false;
+    const timer = setTimeout(() => {
+      timedOut = true;
+      if (process.platform !== 'win32' && child.pid !== undefined) {
+        try {
+          process.kill(-child.pid, 'SIGKILL');
+        } catch {
+          child.kill('SIGKILL');
+        }
+      } else child.kill('SIGKILL');
+    }, timeoutMs);
+    /** @param {string} target @param {Buffer} chunk */
+    const append = (target, chunk) => {
+      bytes += chunk.byteLength;
+      if (bytes > maxOutputBytes) {
+        overflow = true;
+        return target;
+      }
+      return `${target}${chunk.toString('utf8')}`;
+    };
+    /** @param {number|null} code */
+    const finish = (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timer);
+      resolvePromise({ code, stdout, stderr, overflow, timedOut });
+    };
+    child.stdout.on('data', (chunk) => {
+      stdout = append(stdout, chunk);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr = append(stderr, chunk);
+    });
+    child.once('error', () => finish(null));
+    child.once('close', (code) => finish(code));
+  });
+}
+
+/** @param {string} root @param {string} relativePath */
+async function assertNoSymlinkPath(root, relativePath) {
+  let current = resolve(root);
+  const parts = relativePath.split('/');
+  for (const part of parts) {
+    current = join(current, part);
+    const info = await lstat(current);
+    if (info.isSymbolicLink()) throw new Error('plugin_asset_symlink_rejected');
+  }
+}
+
+/** @param {string} source @param {string} destination */
+async function copyAllowlistedPlugin(source, destination) {
+  await mkdir(destination, { recursive: true, mode: 0o700 });
+  let totalBytes = 0;
+  for (const file of ALLOWED_PLUGIN_FILES) {
+    const input = join(source, file);
+    await assertNoSymlinkPath(source, file);
+    const info = await lstat(input);
+    if (!info.isFile() || info.isSymbolicLink()) throw new Error('plugin_asset_invalid');
+    const uid = process.getuid?.();
+    if (uid !== undefined && info.uid !== uid) throw new Error('plugin_asset_owner_mismatch');
+    if (info.size > MAX_PLUGIN_ASSET_BYTES) throw new Error('plugin_asset_too_large');
+    totalBytes += info.size;
+    if (totalBytes > MAX_PLUGIN_TOTAL_BYTES) throw new Error('plugin_assets_too_large');
+    const output = join(destination, file);
+    await mkdir(dirname(output), { recursive: true, mode: 0o700 });
+    await cp(input, output, { force: true, errorOnExist: true, verbatimSymlinks: true });
+    await chmod(output, 0o600);
+  }
+}
+
+/** @param {string} directory */
+async function assertEmptyDirectory(directory) {
+  const entries = await readdir(directory);
+  if (entries.length !== 0) throw new Error('probe_directory_not_empty');
+}
+
+/** @param {unknown} value @returns {value is Record<string, unknown>} */
+function record(value) {
+  return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+/** @param {unknown} value @returns {value is string[]} */
+function stringArray(value) {
+  return Array.isArray(value) && value.every((item) => typeof item === 'string');
+}
+
+/** @param {string} executable @param {string} pluginRoot @param {{timeoutMs?:number,maxOutputBytes?:number}} [limits] */
+async function runHostProbe(executable, pluginRoot, limits = {}) {
+  const root = await mkdtemp(join(tmpdir(), 'aibrain-claude-host-'));
+  const home = join(root, 'home');
+  const config = join(root, 'config');
+  const cwd = join(root, 'cwd');
+  const copiedPlugin = join(root, 'plugin');
+  const contractPlugin = join(root, 'contract-plugin');
+  await Promise.all([
+    mkdir(home, { recursive: true, mode: 0o700 }),
+    mkdir(config, { recursive: true, mode: 0o700 }),
+    mkdir(cwd, { recursive: true, mode: 0o700 }),
+  ]);
+  try {
+    await copyAllowlistedPlugin(pluginRoot, copiedPlugin);
+    await copyAllowlistedPlugin(pluginRoot, contractPlugin);
+    await writeFile(
+      join(contractPlugin, 'hooks', 'hooks.json'),
+      JSON.stringify({ modules: ['./native-host-contract-runtime.ts'] }),
+      { mode: 0o600 },
+    );
+    /** @type {NodeJS.ProcessEnv} */
+    const environment = {
+      PATH: safePath(executable),
+      HOME: home,
+      CLAUDE_CONFIG_DIR: config,
+      CLAUDE_COMPAT_CWD: cwd,
+      CLAUDE_CODE_ENABLE_FUNCTION_HOOKS: '1',
+      AIBRAIN_NATIVE_CONTRACT: '1',
+      CLAUDE_CODE_DISABLE_AUTO_MEMORY: '1',
+      CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1',
+      NO_COLOR: '1',
+      CI: '1',
+    };
+    const help = await runBounded(executable, ['--help'], environment, limits);
+    if (
+      help.code !== 0 ||
+      help.overflow ||
+      REQUIRED_FLAGS.some((flag) => !help.stdout.includes(flag))
+    )
+      return { ok: false, reason: 'launch_flags_missing' };
+    const validate = await runBounded(
+      executable,
+      ['plugin', 'validate', '--strict', '--json', copiedPlugin],
+      environment,
+      limits,
+    );
+    if (validate.code !== 0 || validate.overflow)
+      return { ok: false, reason: 'plugin_validation_failed' };
+    /** @type {Record<string, unknown>} */
+    let report;
+    try {
+      const parsed = JSON.parse(validate.stdout);
+      if (!record(parsed)) return { ok: false, reason: 'plugin_validation_malformed' };
+      report = parsed;
+    } catch {
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    }
+    if (report.success !== true || report.strict !== true)
+      return { ok: false, reason: 'plugin_validation_failed' };
+    if (
+      !record(report.manifest) ||
+      !stringArray(report.manifest.errors) ||
+      !stringArray(report.manifest.warnings)
+    )
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    if (
+      !Array.isArray(report.contents) ||
+      report.contents.length !== 1 ||
+      !report.contents.every(record)
+    )
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    const contents = report.contents;
+    if (
+      !contents.every(
+        (item) => stringArray(item.errors) && stringArray(item.warnings) && stringArray(item.notes),
+      )
+    )
+      return { ok: false, reason: 'plugin_validation_malformed' };
+    const manifest = report.manifest;
+    const errors = [
+      ...(Array.isArray(manifest.errors) ? manifest.errors : []),
+      ...(Array.isArray(manifest.warnings) ? manifest.warnings : []),
+      ...contents.flatMap((item) => [
+        ...(Array.isArray(item.errors) ? item.errors : []),
+        ...(Array.isArray(item.warnings) ? item.warnings : []),
+      ]),
+    ];
+    if (errors.length > 0) return { ok: false, reason: 'plugin_validation_failed' };
+    const notes = contents.flatMap((item) => item.notes);
+    const hookNote = notes.find((note) => typeof note === 'string' && note.includes(' hooks: '));
+    const callNote = notes.find((note) => typeof note === 'string' && note.includes(' calls: '));
+    const hooks = new Set(
+      typeof hookNote === 'string'
+        ? hookNote
+            .split(' hooks: ', 2)[1]
+            .split(', ')
+            .map((item) => item.trim())
+        : [],
+    );
+    const calls = new Set(
+      typeof callNote === 'string'
+        ? callNote
+            .split(' calls: ', 2)[1]
+            .replace(/\s+\(via[^)]*\)/gu, '')
+            .split(', ')
+            .map((item) => item.trim())
+        : [],
+    );
+    const inventory = new Set([...hooks, ...calls]);
+    if (inventory.size === 0 || REQUIRED_INVENTORY.some((item) => !inventory.has(item)))
+      return { ok: false, reason: 'host_inventory_incomplete' };
+    const test = await runBounded(
+      executable,
+      ['plugin', 'test', contractPlugin],
+      environment,
+      limits,
+    );
+    const passMatch = (test.stdout + test.stderr).match(/(?:^|\s)(\d+)\s+pass(?:ed)?(?:\s|$)/iu);
+    const failMatch = (test.stdout + test.stderr).match(/(?:^|\s)(\d+)\s+fail(?:ed)?(?:\s|$)/iu);
+    if (test.timedOut) return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (test.code !== 0) return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (test.overflow) return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (passMatch === null || Number(passMatch[1]) < 1)
+      return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (failMatch === null || Number(failMatch[1]) !== 0)
+      return { ok: false, reason: 'native_plugin_tests_failed' };
+    if (
+      !test.stdout.includes(
+        'AI Brain enabled host contract invokes usage and native compaction through the dispatcher',
+      )
+    )
+      return { ok: false, reason: 'native_plugin_tests_failed' };
+    await assertEmptyDirectory(cwd);
+    return {
+      ok: true,
+      checks: [
+        'launch_flags',
+        'plugin_validate_strict',
+        'native_plugin_test',
+        'isolated_filesystem',
+      ],
+    };
+  } catch (error) {
+    const reason = error instanceof Error ? error.message : '';
+    const allowedReasons = new Set([
+      'plugin_asset_invalid',
+      'plugin_asset_symlink_rejected',
+      'plugin_asset_owner_mismatch',
+      'plugin_asset_too_large',
+      'plugin_assets_too_large',
+      'probe_directory_not_empty',
+    ]);
+    return { ok: false, reason: allowedReasons.has(reason) ? reason : 'host_probe_failed' };
+  } finally {
+    try {
+      await rm(root, { recursive: true, force: true });
+    } catch {
+      throw new Error('probe_cleanup_failed');
+    }
+  }
+}
+
+/** @param {string} executable @param {string} packageRoot */
+/** @param {string} executable @param {string} packageRoot @returns {Promise<ClaudeCompatibility>} */
+export async function resolveClaudeCompatibility(executable, packageRoot) {
+  let pinnedExecutable;
+  try {
+    pinnedExecutable = await realpath(executable);
+  } catch {
+    return {
+      status: 'rejected',
+      executable: null,
+      version: null,
+      reason: 'executable_unavailable',
+    };
+  }
+  let raw;
+  try {
+    raw = await readNativeVersion(pinnedExecutable);
+  } catch {
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: null,
+      reason: 'version_probe_cleanup_failed',
+    };
+  }
+  const version = parseVersion(raw);
+  if (!version)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: null,
+      reason: 'version_unavailable',
+    };
+  if (version.prerelease)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'prerelease',
+    };
+  if (version.major !== HOST_MAJOR || version.minor !== HOST_MINOR) {
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'major_minor_unsupported',
+    };
+  }
+  if (QUALIFIED_VERSIONS.has(version.text))
+    return {
+      status: 'qualified',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'known_stable',
+    };
+  if (version.patch < 303)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'unsupported_stable_patch',
+    };
+  let probe;
+  try {
+    probe = await runHostProbe(pinnedExecutable, join(resolve(packageRoot), 'assets', 'claude'));
+  } catch {
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: 'host_probe_cleanup_failed',
+    };
+  }
+  if (!probe.ok)
+    return {
+      status: 'rejected',
+      executable: pinnedExecutable,
+      version: version.text,
+      reason: probe.reason ?? 'host_probe_failed',
+    };
+  return {
+    status: 'host_checked',
+    executable: pinnedExecutable,
+    version: version.text,
+    reason: 'native_host_contract',
+    ...(probe.checks === undefined ? {} : { checks: probe.checks }),
+  };
+}
+
+/** @param {ClaudeCompatibility} decision */
+export function claudeCompatibilityError(decision) {
+  const detected = decision.version ?? 'unavailable';
+  return `claude_version_unverified: Claude Code detected version ${detected}; reason ${decision.reason}; run aisac doctor --json or install a compatible stable native version.`;
+}
+
+export const claudeCompatibilityInternals = Object.freeze({
+  REQUIRED_FLAGS,
+  REQUIRED_INVENTORY,
+  ALLOWED_PLUGIN_FILES,
+  parseVersion,
+  runHostProbe,
+});