Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* Safe whole-skill updates of installed skillpacks (GBRA-225 PR 3):
* src/core/skillpack/{safe-update,update-journal,state,file-lock}.ts, the
* `skillpack_update_incomplete` doctor check and the CLI exit-code contract.
*
* Every case runs on real files in temp dirs outside any git repository
* (repo-less brains are first class), with its own state file and backups
* dir (or an isolated GBRAIN_HOME for the spawned CLI).
*/
import { afterEach, describe, expect, test } from 'bun:test';
import { appendFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'fs';
import { dirname, join } from 'path';
import { tmpdir } from 'os';
import { spawn, spawnSync } from 'child_process';
import { runScaffold } from '../src/core/skillpack/scaffold.ts';
import {
DIFF_LINE_CAP, recordScaffoldBases, runSkillpackRestore, runSkillpackUpdate, setSkillPinned, skillsRootKey, type UpdateOptions,
} from '../src/core/skillpack/safe-update.ts';
import { journalDir, listJournals, sha256 } from '../src/core/skillpack/update-journal.ts';
import { loadState, saveState } from '../src/core/skillpack/state.ts';
import {
SKILLS_LOCK_HISTORY_FILENAME, SKILLS_MANIFEST_FILENAME, computeSkillsManifest, droppedHistoryEntries, loadVerifiedSkillsLockHistory,
mergeSkillsLockHistory, parseSkillsLockHistory, renderSkillsLockHistory, renderSkillsManifest,
} from '../src/core/skills-integrity.ts';
import { runSkillpackUpdateChecks } from '../src/commands/doctor/checks/skillpack-update.ts';
const REPO = join(import.meta.dir, '..');
const created: string[] = [];
afterEach(() => {
while (created.length) rmSync(created.pop()!, { recursive: true, force: true });
});
function tmp(prefix: string): string {
const dir = mkdtempSync(join(tmpdir(), prefix));
created.push(dir);
return dir;
}
const skill = (name: string, body: string) => `---\nname: ${name}\ntriggers:\n - run the ${name} flow\n---\n# ${name}\n\n${body}\n`;
const V1 = { 'demo/SKILL.md': skill('demo', 'v1'), 'demo/references/notes.md': 'notes v1\n', 'other/SKILL.md': skill('other', 'v1') };
const V2 = { 'demo/SKILL.md': skill('demo', 'v2'), 'demo/references/notes.md': 'notes v2\n', 'other/SKILL.md': skill('other', 'v2') };
const V3 = { 'demo/SKILL.md': skill('demo', 'v3'), 'demo/references/notes.md': 'notes v3\n', 'other/SKILL.md': skill('other', 'v3') };
/** Write a bundle release: files, then the history (append-only) and the lock, as scripts/generate-skills-manifest.ts does. */
function release(gbrainRoot: string, files: Record<string, string>): void {
const skillsDir = join(gbrainRoot, 'skills');
for (const [rel, body] of Object.entries(files)) {
mkdirSync(dirname(join(skillsDir, rel)), { recursive: true });
writeFileSync(join(skillsDir, rel), body);
}
const historyPath = join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME);
const previous = existsSync(historyPath) ? parseSkillsLockHistory(readFileSync(historyPath, 'utf-8')) : null;
writeFileSync(historyPath, renderSkillsLockHistory(mergeSkillsLockHistory(previous, computeSkillsManifest(skillsDir))));
writeFileSync(join(skillsDir, SKILLS_MANIFEST_FILENAME), renderSkillsManifest(skillsDir));
}
interface Env { gbrainRoot: string; ws: string; home: string; statePath: string; backups: string; skillsRoot: string }
function setup(opts: { sharedDeps?: string[]; first?: Record<string, string> } = {}): Env {
const gbrainRoot = tmp('sp-safe-gbrain-');
mkdirSync(join(gbrainRoot, 'src'), { recursive: true });
writeFileSync(join(gbrainRoot, 'src', 'cli.ts'), '// stub\n');
writeFileSync(join(gbrainRoot, 'openclaw.plugin.json'), JSON.stringify({ name: 'gbrain-test', version: '0.0.1', skills: ['skills/demo', 'skills/other'], shared_deps: opts.sharedDeps ?? [] }));
release(gbrainRoot, opts.first ?? V1);
const ws = tmp('sp-safe-ws-');
const home = tmp('sp-safe-home-');
const gb = join(home, '.gbrain');
return { gbrainRoot, ws, home, statePath: join(gb, 'skillpack-state.json'), backups: join(gb, 'skillpack-backups'), skillsRoot: skillsRootKey(join(ws, 'skills')) };
}
async function scaffold(env: Env, opts: { record?: boolean } = {}): Promise<void> {
const result = runScaffold({ gbrainRoot: env.gbrainRoot, targetWorkspace: env.ws, skillSlug: null });
if (opts.record !== false) await recordScaffoldBases(join(env.ws, 'skills'), result.files, { statePath: env.statePath });
}
function update(env: Env, extra: Partial<UpdateOptions> = {}) {
return runSkillpackUpdate({ gbrainRoot: env.gbrainRoot, skillsRoot: env.skillsRoot, slugs: null, statePath: env.statePath, backups: env.backups, validate: () => [], ...extra });
}
const read = (env: Env, rel: string) => readFileSync(join(env.ws, 'skills', rel), 'utf-8');
const write = (env: Env, rel: string, body: string) => writeFileSync(join(env.ws, 'skills', rel), body);
const outcome = (result: Awaited<ReturnType<typeof update>>, slug: string) => result.skills.find(s => s.slug === slug)!;
describe('base recording and whole-skill update', () => {
test('scaffold: a state file that cannot be read warns after the files are written instead of failing', async () => {
const env = setup();
mkdirSync(dirname(env.statePath), { recursive: true });
writeFileSync(env.statePath, JSON.stringify({ schema_version: 'gbrain-skillpack-state-v99' }));
const warnings: string[] = [];
const original = console.error;
console.error = (...args: unknown[]) => { warnings.push(args.join(' ')); };
try {
await scaffold(env);
} finally {
console.error = original;
}
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
expect(warnings.some(w => w.includes('install bases were not recorded'))).toBe(true);
expect(JSON.parse(readFileSync(env.statePath, 'utf-8')).schema_version).toBe('gbrain-skillpack-state-v99');
});
test('a state save that fails after the files land keeps the skill updated, leaves the next skill untouched and finishes the journal', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const breakState = () => {
if (existsSync(join(env.statePath, 'blocked'))) return;
rmSync(env.statePath, { force: true });
mkdirSync(join(env.statePath, 'blocked'), { recursive: true });
};
const result = await update(env, { hooks: { afterRename: breakState } });
expect(result.summary).toMatchObject({ updated: 1, failed: 1 });
expect(read(env, 'demo/SKILL.md')).toBe(V2['demo/SKILL.md']);
expect(outcome(result, 'demo').notes.some(n => n.includes('base record was not saved'))).toBe(true);
expect(read(env, 'other/SKILL.md')).toBe(V1['other/SKILL.md']);
expect(outcome(result, 'other').failure).toContain('the state file cannot be read');
const [journal] = listJournals(env.backups);
expect(journal!.status).toBe('complete');
expect(journal!.skills.map(s => [s.slug, s.status])).toEqual([['demo', 'committed'], ['other', 'abandoned']]);
});
test('scaffold records bases; an untouched skill updates whole, journaled; a second run is a no-op (repo-less)', async () => {
const env = setup();
expect(spawnSync('git', ['-C', env.ws, 'rev-parse', '--git-dir']).status).not.toBe(0);
await scaffold(env);
const record = loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!;
expect(record.files['demo/SKILL.md']).toBe(sha256(V1['demo/SKILL.md']));
release(env.gbrainRoot, V2);
const preview = await update(env, { dryRun: true });
expect(outcome(preview, 'demo').result).toBe('would_update');
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
expect(existsSync(env.backups)).toBe(false);
const result = await update(env);
expect(result.summary).toMatchObject({ updated: 2, failed: 0, skipped: 0 });
expect(read(env, 'demo/references/notes.md')).toBe(V2['demo/references/notes.md']);
const [journal] = listJournals(env.backups);
expect(journal!.status).toBe('complete');
expect(journal!.skills.every(s => s.status === 'committed')).toBe(true);
expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
expect(readdirNames(env.skillsRoot).filter(n => n.startsWith('.gbrain-skillpack'))).toEqual([]);
const again = await update(env);
expect(again.summary.current).toBe(2);
expect(again.journal).toBeNull();
});
test('base precedence: a file that differs from its base is local_edits even when it equals a released version', async () => {
const env = setup();
release(env.gbrainRoot, V2);
await scaffold(env); // base = v2
write(env, 'demo/SKILL.md', V1['demo/SKILL.md']); // a past release, not the base
release(env.gbrainRoot, V3);
const result = await update(env, { acceptHistorical: true });
expect(outcome(result, 'demo')).toMatchObject({ result: 'skipped', reason: 'local_edits' });
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
expect(read(env, 'demo/references/notes.md')).toBe(V2['demo/references/notes.md']);
expect(outcome(result, 'other').result).toBe('updated');
});
test('a file with no base that matches only a released version needs --accept-historical', async () => {
const env = setup();
await scaffold(env, { record: false }); // an install from before bases were recorded
release(env.gbrainRoot, V2);
const without = await update(env);
expect(outcome(without, 'demo')).toMatchObject({ result: 'skipped', reason: 'historical_only' });
expect(outcome(without, 'demo').historical.sort()).toEqual(['demo/SKILL.md', 'demo/references/notes.md']);
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
const withFlag = await update(env, { acceptHistorical: true });
expect(outcome(withFlag, 'demo').result).toBe('updated');
expect(read(env, 'demo/SKILL.md')).toBe(V2['demo/SKILL.md']);
expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
});
test('a history that fails its lock hash disables whole-file updates (history_unverified)', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
appendFileSync(join(env.gbrainRoot, 'skills', SKILLS_LOCK_HISTORY_FILENAME), ' ');
const result = await update(env);
expect(result.history.verified).toBe(false);
expect(outcome(result, 'demo')).toMatchObject({ result: 'skipped', reason: 'history_unverified' });
expect(result.summary.updated).toBe(0);
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
});
test('pinning then unpinning a skill that was never installed does not install it', async () => {
const env = setup();
release(env.gbrainRoot, V2);
expect(outcome(await update(env), 'demo').result).toBe('not_installed');
await setSkillPinned(env.skillsRoot, 'demo', true, { statePath: env.statePath });
await setSkillPinned(env.skillsRoot, 'demo', false, { statePath: env.statePath });
const result = await update(env);
expect(outcome(result, 'demo').result).toBe('not_installed');
expect(existsSync(join(env.ws, 'skills', 'demo/SKILL.md'))).toBe(false);
expect(loadState({ statePath: env.statePath }).roots?.[env.skillsRoot]?.demo).toBeUndefined();
});
test('a release that adds a shared dependency updates every skill once, and restore puts it all back', async () => {
const env = setup({ sharedDeps: ['skills/conventions'], first: { ...V1, 'conventions/a.md': 'a v1\n' } });
await scaffold(env);
release(env.gbrainRoot, { ...V2, 'conventions/b.md': 'b v2\n' });
const result = await update(env);
expect(result.summary).toMatchObject({ updated: 2, failed: 0 });
expect(result.restore_command).toBeNull();
expect(read(env, 'conventions/b.md')).toBe('b v2\n');
expect(read(env, 'other/SKILL.md')).toBe(V2['other/SKILL.md']);
const [journal] = listJournals(env.backups);
expect(journal!.skills.flatMap(s => s.files.map(f => f.rel)).filter(rel => rel === 'conventions/b.md')).toHaveLength(1);
await runSkillpackRestore({ id: journal!.id, statePath: env.statePath, backups: env.backups });
expect(existsSync(join(env.ws, 'skills', 'conventions/b.md'))).toBe(false);
expect(read(env, 'other/SKILL.md')).toBe(V1['other/SKILL.md']);
});
test('a shared dependency whose first skill fails is written by the next skill that needs it', async () => {
const env = setup({ sharedDeps: ['skills/conventions'], first: { ...V1, 'conventions/a.md': 'a v1\n' } });
await scaffold(env);
release(env.gbrainRoot, { ...V2, 'conventions/b.md': 'b v2\n' });
const result = await update(env, { validate: (_root, slug) => (slug === 'demo' ? ['forced failure'] : []) });
expect(outcome(result, 'demo').result).toBe('failed');
expect(outcome(result, 'other').result).toBe('updated');
expect(read(env, 'conventions/b.md')).toBe('b v2\n');
const [journal] = listJournals(env.backups);
await runSkillpackRestore({ id: journal!.id, statePath: env.statePath, backups: env.backups });
expect(existsSync(join(env.ws, 'skills', 'conventions/b.md'))).toBe(false);
expect(read(env, 'other/SKILL.md')).toBe(V1['other/SKILL.md']);
});
test('a pinned skill is skipped until unpinned', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
expect(await setSkillPinned(env.skillsRoot, 'demo', true, { statePath: env.statePath })).toBe(true);
const pinned = await update(env);
expect(outcome(pinned, 'demo')).toMatchObject({ result: 'skipped', reason: 'pinned' });
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
await setSkillPinned(env.skillsRoot, 'demo', false, { statePath: env.statePath });
expect(outcome(await update(env), 'demo').result).toBe('updated');
});
test('a symlinked file in the closure is refused, not followed', async () => {
const env = setup();
await scaffold(env);
const outside = join(tmp('sp-safe-outside-'), 'x.md');
writeFileSync(outside, 'outside\n');
rmSync(join(env.ws, 'skills', 'demo/references/notes.md'));
symlinkSync(outside, join(env.ws, 'skills', 'demo/references/notes.md'));
release(env.gbrainRoot, V2);
const result = await update(env);
expect(outcome(result, 'demo')).toMatchObject({ result: 'skipped', reason: 'unsafe_target' });
expect(readFileSync(outside, 'utf-8')).toBe('outside\n');
});
test('diffs for skipped skills are bounded to 200 lines per file and redact secret-looking values', async () => {
const env = setup();
await scaffold(env);
const secret = `ghp_${'Zq7Lm2Np9Rt4Vx8Bc3Df6Gh1Jk5'.slice(0, 36).padEnd(36, 'x')}`;
write(env, 'demo/references/notes.md', `token: ${secret}\n` + Array.from({ length: 400 }, (_, i) => `local line ${i}`).join('\n') + '\n');
release(env.gbrainRoot, V2);
const result = await update(env);
const diff = outcome(result, 'demo').diffs!.find(d => d.rel === 'demo/references/notes.md')!;
expect(diff.truncated).toBe(true);
expect(diff.diff.split('\n').length).toBeLessThanOrEqual(DIFF_LINE_CAP + 2);
expect(diff.diff).not.toContain(secret);
expect(diff.diff).toContain('REDACTED');
expect((await update(env, { noDiff: true })).skills.every(s => s.diffs === undefined)).toBe(true);
});
});
describe('commit protocol', () => {
test('a file changed between classification and its rename aborts the skill and rolls back only files untouched since', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
let renames = 0;
let first = '';
const result = await update(env, {
slugs: ['demo'],
hooks: {
afterRename: rel => { if (renames++ === 0) first = rel; },
beforeRename: rel => { if (renames === 1) writeFileSync(join(env.ws, 'skills', rel), 'edited mid-update\n'); },
},
});
const demo = outcome(result, 'demo');
expect(demo.result).toBe('failed');
expect(demo.touched).toEqual([first]);
expect(demo.rollback_skipped).toEqual([]);
expect(read(env, first)).toBe(V1[first as keyof typeof V1]);
const second = first === 'demo/SKILL.md' ? 'demo/references/notes.md' : 'demo/SKILL.md';
expect(read(env, second)).toBe('edited mid-update\n');
expect(listJournals(env.backups)[0]!.skills[0]!.status).toBe('rolled_back');
expect(result.restore_command).toContain('gbrain skillpack restore');
expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.files[first]).toBe(sha256(V1[first as keyof typeof V1]));
});
test('rollback leaves a renamed file that was edited again after the rename', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
let renames = 0;
let first = '';
const result = await update(env, {
slugs: ['demo'],
hooks: {
afterRename: rel => {
if (renames++ > 0) return;
first = rel;
writeFileSync(join(env.ws, 'skills', rel), 'edited after rename\n');
},
beforeRename: rel => { if (renames === 1) writeFileSync(join(env.ws, 'skills', rel), 'edited mid-update\n'); },
},
});
expect(outcome(result, 'demo').rollback_skipped).toEqual([first]);
expect(read(env, first)).toBe('edited after rename\n');
});
test('a failed post-update check rolls the skill back', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const result = await update(env, { slugs: ['demo'], validate: () => ['forced failure'] });
expect(outcome(result, 'demo')).toMatchObject({ result: 'failed', failure: 'forced failure' });
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
expect(read(env, 'demo/references/notes.md')).toBe(V1['demo/references/notes.md']);
});
test('the default checks pass a real update (conformance, triggers, resolver)', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const result = await update(env, { validate: undefined });
expect(result.summary).toMatchObject({ updated: 2, failed: 0 });
});
test('a crash leaves a pending journal: doctor reports it, the next run refuses, restore recovers', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const script = join(tmp('sp-safe-script-'), 'crash.ts');
writeFileSync(script, `import { runSkillpackUpdate } from ${JSON.stringify(join(REPO, 'src/core/skillpack/safe-update.ts'))};
await runSkillpackUpdate({ gbrainRoot: ${JSON.stringify(env.gbrainRoot)}, skillsRoot: ${JSON.stringify(env.skillsRoot)}, slugs: ['demo'],
statePath: ${JSON.stringify(env.statePath)}, backups: ${JSON.stringify(env.backups)}, validate: () => [], hooks: { afterRename: () => process.exit(9) } });
`);
expect(spawnSync('bun', [script], { stdio: 'ignore', timeout: 60_000 }).status).toBe(9);
const [incomplete] = (await runSkillpackUpdateChecks(undefined, env.backups));
expect(incomplete).toMatchObject({ name: 'skillpack_update_incomplete', status: 'warn' });
const id = listJournals(env.backups)[0]!.id;
expect(incomplete!.message).toContain(`gbrain skillpack restore ${id}`);
await expect(update(env)).rejects.toMatchObject({ code: 'skillpack_update_incomplete' });
expect((await update(env, { dryRun: true })).pending_journals).toEqual([id]);
await runSkillpackRestore({ id, statePath: env.statePath, backups: env.backups });
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
expect(read(env, 'demo/references/notes.md')).toBe(V1['demo/references/notes.md']);
expect((await runSkillpackUpdateChecks(undefined, env.backups)).map(c => c.name)).toEqual(['skillpack_backups']);
expect(outcome(await update(env), 'demo').result).toBe('updated');
}, 90_000);
});
describe('restore', () => {
test('refuses a file changed after the update unless it is named in --skip', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const { journal } = await update(env, { slugs: ['demo'] });
write(env, 'demo/references/notes.md', 'my later edit\n');
await expect(runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups })).rejects.toMatchObject({ code: 'skillpack_restore_conflict' });
expect(read(env, 'demo/SKILL.md')).toBe(V2['demo/SKILL.md']);
await runSkillpackRestore({ id: journal!, skip: ['demo/references/notes.md'], statePath: env.statePath, backups: env.backups });
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
expect(read(env, 'demo/references/notes.md')).toBe('my later edit\n');
const record = loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!;
expect(record.files['demo/SKILL.md']).toBe(sha256(V1['demo/SKILL.md']));
});
test('is idempotent', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const { journal } = await update(env);
const first = await runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups });
expect(first.files.every(f => f.action === 'restore')).toBe(true);
const snapshot = [read(env, 'demo/SKILL.md'), read(env, 'demo/references/notes.md'), read(env, 'other/SKILL.md')];
const second = await runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups });
expect(second.files.every(f => f.action === 'already_restored')).toBe(true);
expect([read(env, 'demo/SKILL.md'), read(env, 'demo/references/notes.md'), read(env, 'other/SKILL.md')]).toEqual(snapshot);
expect(snapshot[0]).toBe(V1['demo/SKILL.md']);
});
test('refuses a journal whose backup path leaves the journal directory (.. or absolute)', async () => {
const env = setup();
await scaffold(env);
release(env.gbrainRoot, V2);
const { journal } = await update(env, { slugs: ['demo'] });
const journalPath = join(env.backups, journal!, 'journal.json');
const pristine = readFileSync(journalPath, 'utf-8');
const outside = join(dirname(env.backups), 'outside-canary.md');
writeFileSync(outside, V1['demo/SKILL.md']);
for (const escape of ['../../outside-canary.md', outside]) {
const tampered = JSON.parse(pristine);
for (const s of tampered.skills) for (const f of s.files) if (f.rel === 'demo/SKILL.md') f.backup = escape;
writeFileSync(journalPath, JSON.stringify(tampered));
await expect(runSkillpackRestore({ id: journal!, statePath: env.statePath, backups: env.backups })).rejects.toMatchObject({ code: 'target_escape' });
expect(read(env, 'demo/SKILL.md')).toBe(V2['demo/SKILL.md']);
}
for (const id of ['..', '../escape', outside]) {
expect(() => journalDir(id, env.backups)).toThrow(expect.objectContaining({ code: 'skillpack_journal_not_found' }));
}
});
});
describe('shared state lock', () => {
test('concurrent scaffold, update and pin across two workspaces lose no state records', async () => {
const a = setup();
const b: Env = { ...a, ws: tmp('sp-safe-ws-b-') };
b.skillsRoot = skillsRootKey(join(b.ws, 'skills'));
await scaffold(b);
release(a.gbrainRoot, V2);
const dir = tmp('sp-safe-script-');
const startAt = Date.now() + 1500;
const mod = (name: string) => JSON.stringify(join(REPO, 'src/core/skillpack', name));
const scripts = {
a: `import { runScaffold } from ${mod('scaffold.ts')};
import { recordScaffoldBases, setSkillPinned } from ${mod('safe-update.ts')};
while (Date.now() < ${startAt}) await Bun.sleep(5);
const r = runScaffold({ gbrainRoot: ${JSON.stringify(a.gbrainRoot)}, targetWorkspace: ${JSON.stringify(a.ws)}, skillSlug: null });
await recordScaffoldBases(${JSON.stringify(join(a.ws, 'skills'))}, r.files, { statePath: ${JSON.stringify(a.statePath)} });
for (let i = 0; i < 150; i++) await setSkillPinned(${JSON.stringify(skillsRootKey(join(a.ws, 'skills')))}, 'p' + i, true, { statePath: ${JSON.stringify(a.statePath)} });
`,
b: `import { runSkillpackUpdate, setSkillPinned } from ${mod('safe-update.ts')};
while (Date.now() < ${startAt}) await Bun.sleep(5);
const r = await runSkillpackUpdate({ gbrainRoot: ${JSON.stringify(b.gbrainRoot)}, skillsRoot: ${JSON.stringify(b.skillsRoot)}, slugs: null, statePath: ${JSON.stringify(b.statePath)}, backups: ${JSON.stringify(b.backups)}, validate: () => [] });
if (r.summary.updated !== 2) process.exit(3);
for (let i = 0; i < 150; i++) await setSkillPinned(${JSON.stringify(b.skillsRoot)}, 'q' + i, true, { statePath: ${JSON.stringify(b.statePath)} });
`,
};
const run = (body: string, name: string) => new Promise<number | null>(resolve => {
const path = join(dir, `${name}.ts`);
writeFileSync(path, body);
spawn('bun', [path], { stdio: 'ignore' }).on('exit', code => resolve(code));
});
expect(await Promise.all([run(scripts.a, 'a'), run(scripts.b, 'b')])).toEqual([0, 0]);
const roots = loadState({ statePath: a.statePath }).roots!;
const rootA = roots[skillsRootKey(join(a.ws, 'skills'))]!;
expect(rootA.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
expect(Object.keys(rootA).filter(k => rootA[k]!.pinned).length).toBe(150);
const rootB = roots[b.skillsRoot]!;
expect(rootB.demo!.files['demo/SKILL.md']).toBe(sha256(V2['demo/SKILL.md']));
expect(Object.keys(rootB).filter(k => rootB[k]!.pinned).length).toBe(150);
}, 90_000);
});
describe('CLI contract', () => {
const cli = (env: Env, args: string[]) => spawnSync('bun', [join(REPO, 'src/cli.ts'), 'skillpack', ...args], {
cwd: env.gbrainRoot, env: { ...process.env, GBRAIN_HOME: env.home }, stdio: ['ignore', 'pipe', 'pipe'], encoding: 'utf-8', timeout: 60_000,
});
test('exit 0 with skips, 1 only with --fail-on-skipped, 2 on failure; never prompts with stdin closed', () => {
const env = setup();
expect(cli(env, ['scaffold', '--all', '--workspace', env.ws]).status).toBe(0);
expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.other!.files['other/SKILL.md']).toBe(sha256(V1['other/SKILL.md']));
write(env, 'other/SKILL.md', skill('other', 'my edit'));
release(env.gbrainRoot, V2);
const preview = cli(env, ['reference', '--all', '--update-untouched', '--dry-run', '--workspace', env.ws]);
expect(preview.status).toBe(0);
expect(preview.stdout).toContain('would update');
expect(read(env, 'demo/SKILL.md')).toBe(V1['demo/SKILL.md']);
const ok = cli(env, ['reference', '--all', '--update-untouched', '--json', '--workspace', env.ws]);
expect(ok.status).toBe(0);
const okJson = JSON.parse(ok.stdout);
expect(okJson.summary).toMatchObject({ updated: 1, skipped: 1, failed: 0 });
expect(okJson.skills.find((s: { slug: string }) => s.slug === 'other').reason).toBe('local_edits');
release(env.gbrainRoot, V3);
const strict = cli(env, ['reference', '--all', '--update-untouched', '--fail-on-skipped', '--no-diff', '--workspace', env.ws]);
expect(strict.status).toBe(1);
expect(read(env, 'demo/SKILL.md')).toBe(V3['demo/SKILL.md']);
release(env.gbrainRoot, { 'demo/SKILL.md': '# demo v4 without frontmatter\n' });
const failed = cli(env, ['reference', 'demo', '--update-untouched', '--workspace', env.ws]);
expect(failed.status).toBe(2);
expect(failed.stdout).toMatch(/gbrain skillpack restore \S+/);
expect(read(env, 'demo/SKILL.md')).toBe(V3['demo/SKILL.md']);
expect(cli(env, ['pin', 'demo', '--workspace', env.ws]).status).toBe(0);
expect(loadState({ statePath: env.statePath }).roots![env.skillsRoot]!.demo!.pinned).toBe(true);
expect(cli(env, ['restore', '--list', '--json']).status).toBe(0);
}, 120_000);
});
describe('state file and history', () => {
test('a v1 state file loads with its packs and saves as v2', () => {
const dir = tmp('sp-safe-state-');
const statePath = join(dir, 'skillpack-state.json');
const pack = { name: 'acme-example', version: '1.0.0', author: 'alice-example', source: './pack', source_kind: 'local', pinned_commit: null, tarball_sha256: null, tier: 'local', scaffolded_at: '2026-01-01T00:00:00.000Z', workspace: dir, skill_slugs: ['x'] };
writeFileSync(statePath, JSON.stringify({ schema_version: 'gbrain-skillpack-state-v1', packs: [pack] }));
const state = loadState({ statePath });
expect(state.packs).toEqual([pack] as never);
expect(state.roots).toEqual({});
saveState(state, { statePath });
expect(JSON.parse(readFileSync(statePath, 'utf-8')).schema_version).toBe('gbrain-skillpack-state-v2');
});
test('history merge is append-only and its lock hash is verified', () => {
const env = setup();
const skillsDir = join(env.gbrainRoot, 'skills');
const v1 = parseSkillsLockHistory(readFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME), 'utf-8'));
release(env.gbrainRoot, V2);
const v2 = parseSkillsLockHistory(readFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME), 'utf-8'));
expect(droppedHistoryEntries(v1, v2)).toEqual([]);
expect(v2.files['demo/SKILL.md']).toEqual([sha256(V1['demo/SKILL.md']), sha256(V2['demo/SKILL.md'])].sort());
expect(droppedHistoryEntries(v2, v1).length).toBeGreaterThan(0);
expect(loadVerifiedSkillsLockHistory(skillsDir).ok).toBe(true);
appendFileSync(join(skillsDir, SKILLS_LOCK_HISTORY_FILENAME), '\n');
expect(loadVerifiedSkillsLockHistory(skillsDir)).toMatchObject({ ok: false });
});
});
function readdirNames(dir: string): string[] {
return require('fs').readdirSync(dir) as string[];
}