Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.9 KB
Raw Blame
/**
 * skill-manifest.ts — unified manifest loader for resolver checks.
 *
 * Two call sites converge here (D-CX-12, F-ENG-1):
 *   - `src/core/check-resolvable.ts` — reachability check
 *   - `src/core/dry-fix.ts`          — auto-fix walker
 *
 * Both previously had their own `loadManifest` returning `[]` on missing
 * manifest.json. That silently disabled reachability + auto-fix for any
 * workspace (like an OpenClaw deployment) that doesn't ship a manifest
 * alongside its skills — the exact scenario this release unblocks.
 *
 * Behavior:
 *   1. If `skillsDir/manifest.json` exists and parses, use it verbatim.
 *   2. Otherwise, walk `skillsDir/*` dirs. For each dir containing a
 *      `SKILL.md`, construct `{name, path}` by reading `name:` from the
 *      frontmatter; fall back to the dirname if frontmatter is absent
 *      or unparseable. This is the "auto-derive" path.
 *   3. Return `{skills, derived: boolean}` so callers can surface
 *      derived-manifest mode in `--verbose` / `--json` output.
 *
 * Dotfile dirs (names starting with `_` or `.`) are excluded — they
 * hold conventions and shared rule files, not skills. Files like
 * `_brain-filing-rules.md` live at the root and are not considered
 * skills by either loader.
 */

import { existsSync, readFileSync, readdirSync, statSync } from 'fs';
import { dirname, join } from 'path';
import { atomicWriteFileSync } from './atomic-write.ts';
import { findAllResolverFiles } from './resolver-filenames.ts';
import { SKILLS_MANIFEST_FILENAME } from './skills-integrity.ts';

/** First line of the block `gbrain skillpack install` writes into a workspace's resolver file. */
export const SKILLPACK_MANAGED_BEGIN = '<!-- gbrain:skillpack:begin -->';

export interface ManifestEntry {
  name: string;
  path: string; // relative to skillsDir, e.g. "query/SKILL.md"
}

export interface ManifestLoadResult {
  skills: ManifestEntry[];
  /** True when manifest.json was missing/unparseable and the skill set
   *  was derived from walking skillsDir. Surfaces in --verbose output. */
  derived: boolean;
}

/**
 * Parse the `name:` field from a skill's YAML frontmatter.
 * Tolerant: returns null if no frontmatter, no `name:` key, or unparseable.
 */
function parseSkillName(skillMdPath: string): string | null {
  try {
    const content = readFileSync(skillMdPath, 'utf-8');
    const fmMatch = content.match(/^---\n([\s\S]*?)\n---/);
    if (!fmMatch) return null;
    const fm = fmMatch[1];
    // Match `name: foo` or `name: "foo"` or `name: 'foo'`
    const nameMatch = fm.match(/^name:\s*["']?([^"'\n]+?)["']?\s*$/m);
    if (!nameMatch) return null;
    const name = nameMatch[1].trim();
    return name || null;
  } catch {
    return null;
  }
}

/**
 * Walk skillsDir, return every `<skillsDir>/<dir>/SKILL.md` as a
 * ManifestEntry. Dotfile and underscore-prefixed dirs are skipped.
 */
function deriveManifest(skillsDir: string): ManifestEntry[] {
  const out: ManifestEntry[] = [];
  if (!existsSync(skillsDir)) return out;

  let entries: string[];
  try {
    entries = readdirSync(skillsDir);
  } catch {
    return out;
  }

  for (const entry of entries) {
    // Skip hidden dirs and convention-family sibling dirs (_conventions/,
    // conventions/, migrations/, recipes/, etc. are never "skills" in the
    // routing sense). Only entries with a direct `SKILL.md` count.
    if (entry.startsWith('.') || entry.startsWith('_')) continue;

    const subdirAbs = join(skillsDir, entry);
    let isDir = false;
    try {
      isDir = statSync(subdirAbs).isDirectory();
    } catch {
      continue;
    }
    if (!isDir) continue;

    const skillMd = join(subdirAbs, 'SKILL.md');
    if (!existsSync(skillMd)) continue;

    const frontmatterName = parseSkillName(skillMd);
    const name = frontmatterName && frontmatterName !== '' ? frontmatterName : entry;
    out.push({ name, path: `${entry}/SKILL.md` });
  }

  out.sort((a, b) => a.name.localeCompare(b.name));
  return out;
}

/**
 * Load the skill manifest from `skillsDir/manifest.json`, or derive it
 * from walking `skillsDir` when manifest.json is missing or malformed.
 *
 * Canonical entry point. New code should call THIS, not reach into
 * manifest.json directly.
 */
export function loadOrDeriveManifest(skillsDir: string): ManifestLoadResult {
  const manifestPath = join(skillsDir, 'manifest.json');

  if (existsSync(manifestPath)) {
    try {
      const content = JSON.parse(readFileSync(manifestPath, 'utf-8'));
      // Strict shape gate: `skills` MUST be an array of `{name, path}`.
      // Anything else (missing, object-shaped, entries missing keys) is
      // treated as malformed and falls through to the derive path. This
      // is deliberately stricter than "empty array is fine" because a
      // malformed manifest.json on an OpenClaw deployment otherwise
      // silently disables reachability (F-ENG-1).
      if (Array.isArray(content?.skills)) {
        const skills = content.skills;
        // Empty array is a valid explicit declaration ("no skills yet").
        // Non-empty must have valid shape on every entry.
        const valid = skills.every(
          (s: unknown): s is ManifestEntry =>
            typeof s === 'object' &&
            s !== null &&
            typeof (s as ManifestEntry).name === 'string' &&
            typeof (s as ManifestEntry).path === 'string'
        );
        if (valid) {
          return { skills: skills as ManifestEntry[], derived: false };
        }
      }
      // Non-array skills or entries missing keys → derive
    } catch {
      // Unparseable manifest → fall through to derive
    }
  }

  return { skills: deriveManifest(skillsDir), derived: true };
}

/**
 * Whether gbrain installed or ships this skills folder, read from files only
 * gbrain writes: its tamper manifest (`skills.lock.json`), a valid
 * `manifest.json` on disk (a derived one does not count), or the skillpack
 * managed block in a resolver file (RESOLVER.md / AGENTS.md here or at the
 * workspace root). A generic RESOLVER.md alone is not a gbrain marker. Doctor
 * grades an auto-detected skills folder against gbrain's conventions only when
 * this holds; an agent's own skills folder found by walking up from the cwd is
 * not gbrain's to grade.
 */
export function isGbrainManagedSkillsDir(dir: string): boolean {
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- the second segment is a fixed file name; dir is the operator's own skills folder and is only probed for existence, never written.
  if (existsSync(join(dir, SKILLS_MANIFEST_FILENAME))) return true;
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- fixed file name under the operator's own skills folder; existence probe only.
  if (existsSync(join(dir, 'manifest.json')) && !loadOrDeriveManifest(dir).derived) return true;
  return [...findAllResolverFiles(dir), ...findAllResolverFiles(dirname(dir))].some((file) => {
    try { return readFileSync(file, 'utf-8').includes(SKILLPACK_MANAGED_BEGIN); } catch { return false; }
  });
}

/**
 * #4831: register exactly the given just-scaffolded skills in an existing,
 * valid `skillsDir/manifest.json`. Appends `{name, path}` for each slug not
 * already listed (by name or path); never removes or reorders entries and
 * keeps every other key. A missing or malformed manifest is left alone: the
 * loader derives the skill set from the walk there. Returns the names added.
 */
export function registerManifestEntries(skillsDir: string, slugs: readonly string[]): string[] {
  const unsafe = slugs.find(slug => !slug || slug === '.' || slug.includes('..') || /[\\/]/.test(slug));
  if (unsafe !== undefined) throw new Error(`refusing to register skill slug ${JSON.stringify(unsafe)}: a slug is one path segment with no separators or '..'`);
  // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- skillsDir is the operator's workspace skills directory; the file name is a constant.
  const manifestPath = join(skillsDir, 'manifest.json');
  if (!slugs.length || !existsSync(manifestPath) || loadOrDeriveManifest(skillsDir).derived) return [];
  const content = JSON.parse(readFileSync(manifestPath, 'utf-8')) as { skills: ManifestEntry[] };
  const known = new Set(content.skills.flatMap(entry => [entry.name, entry.path]));
  const added = slugs.filter(slug => !known.has(slug) && !known.has(`${slug}/SKILL.md`))
    // nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- every slug was checked above to be one segment with no separators or '..'.
    .map(slug => ({ name: parseSkillName(join(skillsDir, slug, 'SKILL.md')) ?? slug, path: `${slug}/SKILL.md` }));
  if (!added.length) return [];
  atomicWriteFileSync(manifestPath, JSON.stringify({ ...content, skills: [...content.skills, ...added] }, null, 2) + '\n');
  return added.map(entry => entry.name);
}