Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain skillpack reference <name>|--all --update-untouched`, `skillpack pin|unpin`
* and `skillpack restore` — the safe-update lane (core: src/core/skillpack/safe-update.ts).
*
* Never prompts: `--dry-run` is the preview. Exit 0 when nothing failed
* (skips are in the summary and JSON), 1 only with --fail-on-skipped when
* something was skipped, 2 on a failure (files touched and the restore
* command are printed). Flag-registry note: this file is scanned for
* skillpack's flag allowlist — spell foreign CLI flags without dashes here.
*/
import { join } from 'path';
import { BundleError, bundledSkillSlugs, loadBundleManifest } from '../../core/skillpack/bundle.ts';
import { acquireFileLock, workspaceLockPath, type FileLock } from '../../core/skillpack/file-lock.ts';
import {
runSkillpackRestore, runSkillpackUpdate, setSkillPinned, skillsRootKey, type UpdateResult,
} from '../../core/skillpack/safe-update.ts';
import { listJournals, readJournal } from '../../core/skillpack/update-journal.ts';
import { exitCliError } from '../../cli/cli-error.ts';
import { findGbrainOrDie, resolveWorkspace } from './shared.ts';
export const UPDATE_HELP =
'gbrain skillpack reference <name>|--all --update-untouched [--workspace PATH] [--dry-run] [--json]\n' +
' [--no-diff] [--accept-historical] [--fail-on-skipped]\n\n' +
'Take gbrain\'s current version of installed skills you never edited, one whole\n' +
'skill at a time. A skill updates only when every file still matches the hash\n' +
'recorded at install (or, with --accept-historical, a released version when\n' +
'no hash was recorded) and the skill is not pinned. Anything else\n' +
'is skipped with a reason and a diff. Never prompts; --dry-run is the preview.\n' +
'Every update is journaled under ~/.gbrain/skillpack-backups/<id>/ and can be\n' +
'undone with gbrain skillpack restore <id>.\n\n' +
'Exit: 0 nothing failed; 1 with --fail-on-skipped when a skill was skipped;\n' +
'2 a skill failed and was rolled back (files touched and restore command printed).';
function workspaceSkillsRoot(workspace: string | null): string {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- root selection, not a child join: the operator's own --workspace (trusted local CLI only) plus the constant 'skills'; a symlinked skills dir is a supported root, and every child path under it goes through confinedSkillChildWrite
return skillsRootKey(join(resolveWorkspace({ workspace }), 'skills'));
}
function readValue(args: string[], flag: string): string | null {
for (let i = 0; i < args.length; i++) {
if (args[i] === flag) return args[i + 1] ?? null;
if (args[i]?.startsWith(`${flag}=`)) return args[i]!.slice(flag.length + 1) || null;
}
return null;
}
function positionals(args: string[], valueFlags: string[]): string[] {
const out: string[] = [];
for (let i = 0; i < args.length; i++) {
const a = args[i]!;
if (valueFlags.includes(a)) i++;
else if (!a.startsWith('-')) out.push(a);
}
return out;
}
function printUpdate(result: UpdateResult): void {
const verb = result.dry_run ? 'skillpack update-untouched (dry run)' : 'skillpack update-untouched';
console.log(`${verb}: ${result.skills_root}`);
if (!result.history.verified) console.log(` history UNVERIFIED (${result.history.reason}): whole-file updates are disabled (history_unverified)`);
for (const id of result.pending_journals) console.log(` an earlier update did not finish: gbrain skillpack restore ${id}`);
for (const s of result.skills) {
if (s.result === 'current' || s.result === 'not_installed') continue;
const detail = s.result === 'skipped' ? s.reason : s.result === 'failed' ? s.failure : `${s.changes.length} file(s)`;
console.log(` ${s.result.padEnd(13)} ${s.slug.padEnd(32)} ${detail}`);
for (const note of s.notes) console.log(` note: ${note}`);
}
const c = result.summary;
console.log(`updated: ${c.updated} would update: ${c.would_update} skipped: ${c.skipped} failed: ${c.failed} current: ${c.current} not installed: ${c.not_installed}`);
const historical = result.skills.filter(s => s.historical.length > 0);
if (historical.length) {
console.log('\nMatch only a released version (no recorded base; take them with --accept-historical):');
for (const s of historical) console.log(` ${s.slug}: ${s.historical.join(', ')}`);
}
const diffs = result.skills.filter(s => s.diffs?.length);
if (diffs.length) {
console.log('\nSkipped skills, your copy (a/) against gbrain\'s (b/); first 200 lines per file, secret-looking values redacted.');
console.log('Merge by hand what you want; gbrain skillpack reference <name> shows the full diff.');
for (const s of diffs) for (const d of s.diffs!) console.log(`\n${d.diff}`);
}
const failed = result.skills.filter(s => s.result === 'failed');
if (failed.length) {
console.log('\nFailed (rolled back):');
for (const s of failed) {
console.log(` ${s.slug}: ${s.failure}`);
if (s.touched?.length) console.log(` files touched: ${s.touched.join(', ')}`);
if (s.rollback_skipped?.length) console.log(` left as changed since the update: ${s.rollback_skipped.join(', ')}`);
}
console.log(`Undo everything this run applied: ${result.restore_command}`);
}
}
export async function cmdUpdateUntouched(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(UPDATE_HELP);
process.exit(0);
}
for (const bad of ['--apply-clean-hunks', '--since', '--harness']) {
if (args.some(a => a === bad || a.startsWith(`${bad}=`))) {
console.error(`Error: --update-untouched does not combine with ${bad}. Run gbrain skillpack reference --help for the read-only lens.`);
process.exit(2);
}
}
const all = args.includes('--all');
const names = positionals(args, ['--workspace']);
if (all === names.length > 0) {
console.error('Error: pass one skill name or --all.');
process.exit(2);
}
const json = args.includes('--json');
const gbrainRoot = findGbrainOrDie();
const skillsRoot = workspaceSkillsRoot(readValue(args, '--workspace'));
let lock: FileLock | null = null;
let result: UpdateResult;
try {
lock = await acquireFileLock(workspaceLockPath(skillsRoot), { code: 'skillpack_workspace_locked' });
result = await runSkillpackUpdate({
gbrainRoot, skillsRoot, slugs: all ? null : names,
dryRun: args.includes('--dry-run'), acceptHistorical: args.includes('--accept-historical'), noDiff: args.includes('--no-diff'),
});
} catch (err) {
lock?.release();
if (err instanceof BundleError) {
console.error(`skillpack reference --update-untouched: ${err.message}`);
process.exit(2);
}
exitCliError(err, 'skillpack');
}
lock!.release();
if (json) console.log(JSON.stringify({ ...result!, skills: result!.skills.map(({ files: _files, ...s }) => s) }, null, 2));
else printUpdate(result!);
if (result!.summary.failed > 0) process.exit(2);
process.exit(args.includes('--fail-on-skipped') && result!.summary.skipped > 0 ? 1 : 0);
}
export async function cmdPin(args: string[], pinned: boolean): Promise<void> {
const sub = pinned ? 'pin' : 'unpin';
if (args.includes('--help') || args.includes('-h')) {
console.log(`gbrain skillpack ${sub} <skill> [--workspace PATH] [--json]\n\n` +
(pinned ? 'Pin an installed skill: --update-untouched never updates it.' : 'Unpin a skill so --update-untouched may update it again.'));
process.exit(0);
}
const [slug, extra] = positionals(args, ['--workspace']);
if (!slug || extra) {
console.error(`Error: gbrain skillpack ${sub} takes exactly one skill name.`);
process.exit(2);
}
const gbrainRoot = findGbrainOrDie();
if (!bundledSkillSlugs(loadBundleManifest(gbrainRoot)).includes(slug)) {
console.error(`Error: '${slug}' is not a bundled skill (gbrain skillpack list shows them).`);
process.exit(2);
}
const skillsRoot = workspaceSkillsRoot(readValue(args, '--workspace'));
let changed: boolean;
try {
changed = await setSkillPinned(skillsRoot, slug, pinned);
} catch (err) {
exitCliError(err, 'skillpack');
}
if (args.includes('--json')) console.log(JSON.stringify({ ok: true, skill: slug, skills_root: skillsRoot, pinned, changed: changed! }, null, 2));
else console.log(`${slug} ${changed! ? (pinned ? 'pinned' : 'unpinned') : (pinned ? 'was already pinned' : 'was not pinned')} under ${skillsRoot}`);
process.exit(0);
}
export async function cmdRestore(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log('gbrain skillpack restore <id> [--skip <file>]... [--json]\ngbrain skillpack restore --list [--json]\n\n' +
'Undo a --update-untouched run: put back each file it replaced, and remove each file it\n' +
'added, when the file still holds the update\'s bytes. A file you changed since the update\n' +
'refuses the whole restore unless you name it with --skip <file> (path under the skills\n' +
'root). Running it again is a no-op. Backups are kept 30 days or the newest 10.');
process.exit(0);
}
const json = args.includes('--json');
if (args.includes('--list')) {
const journals = listJournals().map(j => ({
id: j.id, status: j.status, skills_root: j.skills_root, created_at: j.created_at,
skills: j.skills.map(s => ({ slug: s.slug, status: s.status, files: s.files.length })),
}));
if (json) console.log(JSON.stringify({ journals }, null, 2));
else if (!journals.length) console.log('No skillpack update backups.');
else for (const j of journals) console.log(`${j.id} ${j.status.padEnd(8)} ${j.skills.map(s => `${s.slug}:${s.status}`).join(', ')} (${j.skills_root})`);
process.exit(0);
}
const skip: string[] = [];
for (let i = 0; i < args.length; i++) if (args[i] === '--skip' && args[i + 1]) skip.push(args[++i]!);
const [id, extra] = positionals(args, ['--skip']);
if (!id || extra) {
console.error('Error: gbrain skillpack restore takes one backup id (gbrain skillpack restore --list).');
process.exit(2);
}
let lock: FileLock | null = null;
try {
const journal = readJournal(id);
lock = await acquireFileLock(workspaceLockPath(journal.skills_root), { code: 'skillpack_workspace_locked' });
const result = await runSkillpackRestore({ id, skip });
if (json) console.log(JSON.stringify({ ok: true, ...result }, null, 2));
else {
console.log(`skillpack restore ${id}: ${result.skills_root}`);
for (const f of result.files) console.log(` ${f.action.padEnd(16)} ${f.rel}`);
}
} catch (err) {
lock?.release();
exitCliError(err, 'skillpack');
}
lock!.release();
process.exit(0);
}