Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.9 KB
Raw Blame
/**
 * skillpack/update-journal.ts — the journal and backups behind
 * `gbrain skillpack reference --update-untouched` and `gbrain skillpack restore`.
 *
 * Layout: `~/.gbrain/skillpack-backups/<id>/journal.json` plus
 * `files/<rel>`, the bytes each replaced file had before the update. Plain
 * files under GBRAIN_HOME, so it works the same with or without a brain
 * repository.
 *
 * Journal lifecycle: a run writes the journal (status `pending`, every
 * skill `planned`) before it changes anything. Each skill moves to
 * `applying` before its first backup, then to `committed`, `rolled_back`
 * or `abandoned`. The run ends `complete`. A journal still `pending`
 * when no run holds the workspace lock is a crash (`skillpack_update_incomplete`).
 * `restore` puts back each applied file whose current hash equals the
 * journal's post-update hash and marks the journal `restored`.
 */
import { copyFileSync, existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, unlinkSync, writeFileSync } from 'fs';
import { createHash, randomBytes, randomUUID } from 'crypto';
import { dirname } from 'path';

import { gbrainPath } from '../config.ts';
import { OperationError } from '../ops/contract.ts';
import { assertLegacySkillFilesystemWrite, confinedSkillChildWrite } from './writer-guard.ts';

export const JOURNAL_SCHEMA = 'gbrain-skillpack-journal-v1' as const;
export const JOURNAL_KEEP_DAYS = 30;
export const JOURNAL_KEEP_LAST = 10;

export type JournalSkillStatus = 'planned' | 'applying' | 'committed' | 'rolled_back' | 'abandoned' | 'restored';

export interface JournalFile {
  /** Path relative to the skills root (posix). */
  rel: string;
  /** sha256 before the update; null when the file did not exist. */
  pre: string | null;
  /** sha256 the update writes. */
  post: string;
  /** The base recorded for this file before the update (restore puts it back). */
  base_before: string | null;
  /** Backup path relative to the journal dir; null when `pre` is null. */
  backup: string | null;
}

export interface JournalSkill {
  slug: string;
  status: JournalSkillStatus;
  reason?: string;
  files: JournalFile[];
}

export interface Journal {
  schema_version: typeof JOURNAL_SCHEMA;
  id: string;
  status: 'pending' | 'complete' | 'restored';
  skills_root: string;
  created_at: string;
  pid: number;
  skills: JournalSkill[];
}

export function backupsRoot(): string {
  return gbrainPath('skillpack-backups');
}

export function sha256(bytes: Buffer | string): string {
  return createHash('sha256').update(bytes).digest('hex');
}

/** sha256 of a regular file, null when absent. A symlink (or anything not a regular file) throws `target_escape`. */
export function hashTarget(path: string): string | null {
  let stat;
  try {
    stat = lstatSync(path);
  } catch (err) {
    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
    throw err;
  }
  if (!stat.isFile()) {
    throw new OperationError('target_escape', `${path} is not a regular file (symlinks are refused).`,
      'Replace it with a regular file, or pin the skill with gbrain skillpack pin <skill>.');
  }
  return sha256(readFileSync(path));
}

export function newJournalId(now = new Date()): string {
  return `${now.toISOString().replace(/[:.]/g, '-')}-${randomBytes(3).toString('hex')}`;
}

export function journalDir(id: string, root = backupsRoot()): string {
  if (!/^[0-9TZ-]+-[0-9a-f]{6}$/.test(id)) {
    throw new OperationError('skillpack_journal_not_found', `'${id}' is not a skillpack backup id.`,
      'List the backups with gbrain skillpack restore --list.');
  }
  return confinedSkillChildWrite(root, id, { dryRun: true });
}

export function writeJournal(journal: Journal, root = backupsRoot()): void {
  const dir = journalDir(journal.id, root);
  mkdirSync(dir, { recursive: true });
  const path = confinedSkillChildWrite(dir, 'journal.json', { dryRun: true });
  const tmp = `${path}.${process.pid}.${randomUUID()}.tmp`;
  writeFileSync(tmp, JSON.stringify(journal, null, 2) + '\n', { mode: 0o600 });
  renameSync(tmp, path);
}

export function readJournal(id: string, root = backupsRoot()): Journal {
  const path = confinedSkillChildWrite(journalDir(id, root), 'journal.json', { dryRun: true });
  if (!existsSync(path)) {
    throw new OperationError('skillpack_journal_not_found', `No skillpack backup '${id}' under ${root}.`,
      'List the backups with gbrain skillpack restore --list.');
  }
  const journal = JSON.parse(readFileSync(path, 'utf-8')) as Journal;
  if (journal.schema_version !== JOURNAL_SCHEMA) {
    throw new OperationError('skillpack_journal_not_found', `${path} is not a ${JOURNAL_SCHEMA} journal.`,
      'List the backups with gbrain skillpack restore --list.');
  }
  return journal;
}

/** Every readable journal, newest first. Unreadable entries are skipped. */
export function listJournals(root = backupsRoot()): Journal[] {
  if (!existsSync(root)) return [];
  const out: Journal[] = [];
  for (const id of readdirSync(root).sort().reverse()) {
    try {
      out.push(readJournal(id, root));
    } catch { /* not a journal dir */ }
  }
  return out;
}

/** Journals a crash left `pending`, optionally only for one skills root. */
export function pendingJournals(opts: { root?: string; skillsRoot?: string } = {}): Journal[] {
  return listJournals(opts.root).filter(j => j.status === 'pending' && (!opts.skillsRoot || j.skills_root === opts.skillsRoot));
}

/** Keep journals younger than JOURNAL_KEEP_DAYS, the newest JOURNAL_KEEP_LAST, and every pending one. Returns the pruned ids. */
export function pruneJournals(root = backupsRoot(), now = Date.now()): string[] {
  const pruned: string[] = [];
  listJournals(root).forEach((journal, index) => {
    const age = now - Date.parse(journal.created_at);
    if (journal.status === 'pending' || index < JOURNAL_KEEP_LAST || age < JOURNAL_KEEP_DAYS * 86_400_000) return;
    rmSync(journalDir(journal.id, root), { recursive: true, force: true });
    pruned.push(journal.id);
  });
  return pruned;
}

/** Copy `target` into the journal's backup tree and verify the copy hashes to `expected`. */
export function backupFile(journalId: string, rel: string, target: string, expected: string, root = backupsRoot()): string {
  const backupRel = `files/${rel}`;
  const dest = confinedSkillChildWrite(journalDir(journalId, root), backupRel, { dryRun: true });
  mkdirSync(dirname(dest), { recursive: true });
  copyFileSync(target, dest);
  if (sha256(readFileSync(dest)) !== expected) throw new Error(`${rel} changed while it was being backed up`);
  return backupRel;
}

/** Atomically put `bytes` at `target` (temp file in the same directory, then rename). */
export function replaceFile(target: string, bytes: Buffer): void {
  assertLegacySkillFilesystemWrite(target);
  mkdirSync(dirname(target), { recursive: true });
  const tmp = confinedSkillChildWrite(dirname(target), `.gbrain-skillpack-${process.pid}-${randomUUID()}.tmp`, { dryRun: true });
  writeFileSync(tmp, bytes);
  try {
    renameSync(tmp, target);
  } catch (err) {
    rmSync(tmp, { force: true });
    throw err;
  }
}

/**
 * Undo one applied file if it still holds the update's bytes: restore the
 * backup, or remove a file the update created. Returns false (and leaves the
 * file) when it changed since the update.
 */
export function undoFile(journalId: string, skillsRoot: string, file: JournalFile, root = backupsRoot()): boolean {
  const target = confinedSkillChildWrite(skillsRoot, file.rel);
  if (hashTarget(target) !== file.post) return false;
  if (file.pre === null || file.backup === null) {
    unlinkSync(target);
    return true;
  }
  const bytes = readFileSync(confinedSkillChildWrite(journalDir(journalId, root), file.backup, { dryRun: true }));
  if (sha256(bytes) !== file.pre) {
    throw new OperationError('skillpack_backup_corrupt', `The backup of ${file.rel} in ${journalId} does not hash to the journal's pre-update hash.`,
      `Leave ${file.rel} as it is, or compare it with the bundle using gbrain skillpack reference <skill>.`);
  }
  replaceFile(target, bytes);
  return true;
}

export interface RestorePlanFile {
  slug: string;
  rel: string;
  action: 'restore' | 'remove' | 'already_restored' | 'skipped' | 'conflict';
}

/** What restore would do with each applied file. Pure read. */
export function planRestore(journal: Journal, skip: ReadonlySet<string>): RestorePlanFile[] {
  const out: RestorePlanFile[] = [];
  for (const skill of journal.skills) {
    if (skill.status !== 'applying' && skill.status !== 'committed' && skill.status !== 'restored') continue;
    for (const file of skill.files) {
      const current = hashTarget(confinedSkillChildWrite(journal.skills_root, file.rel, { dryRun: true }));
      const action: RestorePlanFile['action'] = current === file.pre ? 'already_restored'
        : skip.has(file.rel) ? 'skipped'
        : current === file.post ? (file.pre === null ? 'remove' : 'restore')
        : 'conflict';
      out.push({ slug: skill.slug, rel: file.rel, action });
    }
  }
  return out;
}