Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
7.1 KB
Raw Blame
import { createHash } from 'node:crypto';
import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from 'node:fs';
import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
import { opError, OperationError } from '../ops/contract.ts';
import { DEFAULT_INVENTORY_LIMITS, inventoryLimitKey, type InventoryLimits } from './inventory-limits.ts';

export const setupHash = (content: string | Uint8Array): string => createHash('sha256').update(content).digest('hex');

export function checkedContentRoot(path: string): string {
  const root = resolve(path);
  let current = root;
  while (true) {
    if (existsSync(current)) {
      const stat = lstatSync(current);
      if (stat.isSymbolicLink() || !stat.isDirectory()) {
        throw opError('local_conflict', 'A content-root component is not a real directory.',
          `${current} is a symlink or a file, so ${root} cannot be a content root. Choose a path whose every parent is a real directory.`);
      }
    }
    const parent = dirname(current);
    if (parent === current) break;
    current = parent;
  }
  return root;
}

export interface PackInventory {
  hashes: Record<string, string>;
  names: string[];
  excluded_from_install: string[];
}

/** The pack exceeds a configured inventory bound; `detail` names the config key. The migration parks the source instead of retrying. */
function inventoryOverflow(root: string, limit: keyof InventoryLimits, value: number, what: string) {
  const key = inventoryLimitKey(limit);
  return opError('payload_too_large', `The skillpack in ${root} exceeds the migration inventory bound ${key}=${value}: ${what}.`,
    `Raise ${key} with gbrain config set, opt the source out with gbrain sources shared-skills followed by its source id and off, or move large assets out of the declared skills and shared_deps; then run gbrain apply-migrations --migration 0.53.0 --yes.`,
    { detail: key, docs: 'docs/guides/shared-brain-skills.md#oversized-skill-packs' });
}

export function inventorySkillpack(root: string, limits: InventoryLimits = DEFAULT_INVENTORY_LIMITS): PackInventory | null {
  checkedContentRoot(root);
  const manifestPath = join(root, 'skillpack.json');
  if (!existsSync(manifestPath)) return null;
  const hashes: Record<string, string> = {};
  let bytes = 0;
  let entries = 0;
  const read = (path: string): string => {
    const absolute = join(root, path);
    const rel = relative(realpathSync(root), realpathSync(absolute));
    if (isAbsolute(rel) || rel === '..' || rel.startsWith('../')) {
      throw opError('local_conflict', 'A skillpack path escapes its source root.',
        `${path} resolves outside ${root}. Replace the link with the real files inside the pack (or drop the entry from skillpack.json), then run the migration again.`);
    }
    const stat = lstatSync(absolute);
    if (!stat.isFile() || stat.isSymbolicLink() || stat.nlink !== 1) {
      throw opError('local_conflict', 'A skillpack file is unsafe.',
        `${path} in ${root} must be a regular, singly linked file; replace it with a real file or remove it, then run the migration again.`);
    }
    if (stat.size > limits.max_file_bytes) throw inventoryOverflow(root, 'max_file_bytes', limits.max_file_bytes, `${path} is ${stat.size} bytes`);
    if (Object.keys(hashes).length >= limits.max_files) throw inventoryOverflow(root, 'max_files', limits.max_files, `it declares more than ${limits.max_files} files`);
    const data = readFileSync(absolute);
    bytes += data.length;
    if (bytes > limits.max_total_bytes) throw inventoryOverflow(root, 'max_total_bytes', limits.max_total_bytes, `its declared files exceed ${limits.max_total_bytes} bytes`);
    hashes[path] = setupHash(data);
    return data.toString('utf8');
  };
  let manifest: { skills?: unknown; shared_deps?: unknown; excluded_from_install?: unknown };
  try { manifest = JSON.parse(read('skillpack.json')); }
  catch (error) {
    if (error instanceof OperationError) throw error;
    throw opError('local_conflict', 'The existing skillpack manifest is malformed.',
      `${manifestPath} is not valid JSON. Fix or restore it from Git, then run the migration again.`);
  }
  if (!Array.isArray(manifest.skills) || manifest.skills.some(path => typeof path !== 'string' || !/^skills\/[a-z0-9][a-z0-9-]*$/.test(path))) {
    throw opError('local_conflict', 'The existing skillpack has ambiguous skill paths.',
      `Make "skills" in ${manifestPath} a list of top-level skill directories with lowercase names (for example "skills/meeting-notes"), then run the migration again.`);
  }
  const names = (manifest.skills as string[]).map(path => path.slice(7));
  if (new Set(names).size !== names.length) {
    throw opError('local_conflict', 'The existing skillpack has duplicate skill names.',
      `List each skill once in "skills" of ${manifestPath}, then run the migration again.`);
  }
  const visit = (path: string, depth: number): void => {
    if (depth > 8 || path.includes('\\') || path.split('/').some(part => !part || part === '.' || part === '..') || isAbsolute(path)) {
      throw opError('local_conflict', 'The skillpack contains an unsafe dependency path.',
        `Declared skill and shared_deps paths in ${manifestPath} must be relative forward-slash paths without empty, . or .. segments and at most 8 directories deep; fix the manifest, then run the migration again.`);
    }
    if (++entries > limits.max_entries) throw inventoryOverflow(root, 'max_entries', limits.max_entries, `its declared paths hold more than ${limits.max_entries} entries`);
    const stat = lstatSync(join(root, path));
    if (stat.isSymbolicLink()) {
      throw opError('local_conflict', 'Skillpack migration does not follow symlinks.',
        `${path} in ${root} is a symlink; replace it with the real file or directory, then run the migration again.`);
    }
    if (stat.isDirectory()) {
      for (const name of readdirSync(join(root, path)).sort()) visit(`${path}/${name}`, depth + 1);
    } else if (!hashes[path]) read(path);
  };
  for (const path of manifest.skills as string[]) visit(path, 0);
  if (manifest.shared_deps !== undefined && (!Array.isArray(manifest.shared_deps) || manifest.shared_deps.some(path => typeof path !== 'string'))) {
    throw opError('local_conflict', 'The skillpack dependency declaration is malformed.',
      `Make "shared_deps" in ${manifestPath} a list of relative paths (or remove it), then run the migration again.`);
  }
  for (const path of (manifest.shared_deps ?? []) as string[]) visit(path, 0);
  if (manifest.excluded_from_install !== undefined && (!Array.isArray(manifest.excluded_from_install) || manifest.excluded_from_install.some(name => typeof name !== 'string'))) {
    throw opError('local_conflict', 'The skillpack exclusions are malformed.',
      `Make "excluded_from_install" in ${manifestPath} a list of skill names (or remove it), then run the migration again.`);
  }
  return { hashes, names, excluded_from_install: (manifest.excluded_from_install ?? []) as string[] };
}

export function sameInventory(a: Record<string, string>, b: Record<string, string>): boolean {
  return JSON.stringify(Object.entries(a).sort()) === JSON.stringify(Object.entries(b).sort());
}