Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* gbrain skillpack <list|scaffold|reference|migrate-fence|scrub-legacy-fence-rows|harvest|diff|check>
*
* v0.33 contract change: dropped `install` and `uninstall` (managed-block
* model). Replaced by:
* - `scaffold` — one-time, additive copy into host workspace
* - `reference` — read-only update lens (per-file diff + framing)
* Add `--apply-clean-hunks` to two-way auto-apply
* - `migrate-fence` — one-shot strip of the legacy fence
* - `scrub-legacy-fence-rows` — opt-in cleanup of legacy rows post-migrate
* - `harvest` — inverse: lift host skill into gbrain
*
* `install` and `uninstall` now exit non-zero with a hint pointing at the
* replacement command. Clean break, no deprecated alias (D10-amended).
*/
import { existsSync, readFileSync } from 'fs';
import { join } from 'path';
import {
bundledSkillSlugs,
loadBundleManifest,
BundleError,
} from '../core/skillpack/bundle.ts';
import { runScaffold, ScaffoldError } from '../core/skillpack/scaffold.ts';
import { runMigrateFence } from '../core/skillpack/migrate-fence.ts';
import { runScrubLegacy } from '../core/skillpack/scrub-legacy.ts';
import { runHarvest, HarvestError } from '../core/skillpack/harvest.ts';
import { computeSkillCurrency } from '../core/skillpack/skill-currency.ts';
import { registerManifestEntries } from '../core/skill-manifest.ts';
import { parseSkillFrontmatter } from '../core/skill-frontmatter.ts';
import { parsePrecondition, type Precondition } from '../core/skillpack/preconditions.ts';
import { resolveAbs, findGbrainOrDie, resolveWorkspace } from './skillpack/shared.ts';
import { cmdScaffold } from './skillpack/scaffold.ts';
import { cmdReference } from './skillpack/reference.ts';
import { recordScaffoldBases, type ScaffoldedFile } from '../core/skillpack/safe-update.ts';
const HELP_TOP = `gbrain skillpack <subcommand> [options]
Subcommands:
list Print every skill bundled in openclaw.plugin.json.
scaffold <name|source> Copy a bundled skill OR a third-party skillpack
into your agent repo. Additive; refuses to
overwrite. Third-party sources: owner/repo,
https://...git, ./local-dir, ./local.tgz.
scaffold --all Scaffold every bundled skill (gbrain only).
scaffold --harness <h> Install a persona-curated set into a harness's
native skills dir (claude-code | openclaw |
codex | opencode). --persona/--skill curate;
--stub installs cold-pull pointers (gated).
reference <name> Read-only: diff gbrain's bundle vs your local copy.
reference --all Sweep over every bundled skill.
reference <n> --apply-clean-hunks
Two-way diff, auto-apply non-conflicting hunks.
reference --harness <h> Diff a harness install (stub-aware; splits
local_edit vs upstream_drift).
reference <n>|--all --update-untouched
Replace whole skills you never edited with
gbrain's version (journaled; --dry-run previews).
pin <name> / unpin <name> Keep a skill out of --update-untouched.
restore <id> | --list Undo an --update-untouched run.
remove --harness <h> Remove files the harness bridge wrote (ledger-
owned only — never your own files).
status Install currency (new/drifted/current) + which
installed skills declare preconditions.
sync Scaffold NEW bundled skills only; report drift.
Never overwrites your files. --dry-run to preview.
setup [<slug>] Print declared preconditions + static hints for a
skill (or all that declare them). Verify live with
\`gbrain doctor\`.
migrate-fence One-shot conversion from the old managed-block
model. Strips fence comments, preserves rows.
scrub-legacy-fence-rows Opt-in cleanup: remove preserved legacy rows
once frontmatter discovery is the norm.
harvest <slug> --from <host-repo-root>
Lift a proven skill from a host agent repo
back into gbrain.
diff <name> (Informational) per-file status; exit 0 always.
check Health report. \`check --strict\` exits non-zero
on any drift (for CI gating).
health [<skill>] Read-only skill health: size against budget,
growth since the last diet, triggers, and
commands or flags this gbrain doesn't have.
search [<query>] Search the third-party registry catalog.
info <name> Show full metadata for a registry entry.
registry [--url URL] Show/set the configured registry URL.
doctor <pack-dir> Run the 10-dimension quality rubric over a
third-party pack. --quick (~5s), --fix to
auto-scaffold missing artifacts.
init <name> Scaffold a fresh skillpack tree (cathedral
default; --minimal opts out of test/e2e/evals).
init-brain-pack <name> Scaffold a brain-resident pack inside a brain/
source repo (brain_resident:true + machine-
parseable README; discovered on connect).
pack [<pack-dir>] Run doctor then emit a deterministic
<name>-<version>.tgz tarball with SHA-256.
endorse <name> (Operator-only) Set the tier for a pack in
endorsements.json inside a registry repo clone.
Run \`gbrain skillpack <subcommand> --help\` for per-subcommand options.
Removed in v0.33 (use migrate-fence to upgrade, then \`scaffold\`):
install — replaced by \`scaffold\`. Run \`migrate-fence\` once.
uninstall — removed. To remove a scaffolded skill, delete the
skills/<slug>/ directory (the files are yours).
`;
export async function runSkillpack(args: string[]): Promise<void> {
const sub = args[0];
const rest = args.slice(1);
if (!sub || sub === '--help' || sub === '-h') {
console.log(HELP_TOP);
process.exit(0);
}
switch (sub) {
case 'list':
await cmdList(rest);
return;
case 'scaffold':
await cmdScaffold(rest);
return;
case 'reference':
await cmdReference(rest);
return;
case 'pin':
case 'unpin': {
const { cmdPin } = await import('./skillpack/update.ts');
await cmdPin(rest, sub === 'pin');
return;
}
case 'restore': {
const { cmdRestore } = await import('./skillpack/update.ts');
await cmdRestore(rest);
return;
}
case 'status':
await cmdStatus(rest);
return;
case 'sync':
await cmdSync(rest);
return;
case 'setup':
await cmdSetup(rest);
return;
case 'migrate-fence':
await cmdMigrateFence(rest);
return;
case 'scrub-legacy-fence-rows':
await cmdScrubLegacy(rest);
return;
case 'harvest':
await cmdHarvest(rest);
return;
case 'diff':
await cmdDiff(rest);
return;
case 'check':
await routeCheck(rest);
return;
case 'health': {
const { cmdHealth } = await import('./skillpack/health.ts');
await cmdHealth(rest);
return;
}
case 'search':
await cmdSearch(rest);
return;
case 'info':
await cmdInfo(rest);
return;
case 'registry':
await cmdRegistry(rest);
return;
case 'doctor':
await cmdDoctor(rest);
return;
case 'init':
await cmdInit(rest);
return;
case 'init-brain-pack':
await cmdInitBrainPack(rest);
return;
case 'pack':
await cmdPack(rest);
return;
case 'endorse':
await cmdEndorse(rest);
return;
case 'remove': {
const { cmdRemove } = await import('./skillpack/harness.ts');
await cmdRemove(rest);
return;
}
case 'install':
console.error(
"Error: 'gbrain skillpack install' was removed in v0.33. Use 'gbrain skillpack scaffold <name>' instead.\n" +
"If you're upgrading from an older release, run 'gbrain skillpack migrate-fence' once to strip the legacy managed block, then scaffold any new skills.",
);
process.exit(2);
return;
case 'uninstall':
console.error(
"Error: 'gbrain skillpack uninstall' was removed in v0.33. The new scaffold model lets you own scaffolded files outright — to remove a skill, delete its directory (rm -rf skills/<slug>/) and any paired source files declared in its frontmatter.",
);
process.exit(2);
return;
default:
console.error(`Unknown subcommand: ${sub}\n`);
console.error(HELP_TOP);
process.exit(2);
}
}
// ---------------------------------------------------------------------------
// list — unchanged from v0.32; lightly reformatted
// ---------------------------------------------------------------------------
async function cmdList(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log('gbrain skillpack list [--json]\n\nPrint every skill bundled in openclaw.plugin.json.');
process.exit(0);
}
const json = args.includes('--json');
const gbrainRoot = findGbrainOrDie();
let manifest;
try {
manifest = loadBundleManifest(gbrainRoot);
} catch (err) {
console.error(`skillpack list: ${(err as Error).message}`);
process.exit(2);
}
const slugs = bundledSkillSlugs(manifest);
if (json) {
const entries = slugs.map(slug => {
const skillMd = join(gbrainRoot, 'skills', slug, 'SKILL.md');
let description: string | null = null;
if (existsSync(skillMd)) {
const body = readFileSync(skillMd, 'utf-8');
const fm = body.match(/^---\n([\s\S]*?)\n---/);
if (fm) {
const descMatch = fm[1].match(/^description:\s*["']?([^\n"']+)/m);
if (descMatch) description = descMatch[1].trim();
}
}
return { name: slug, description };
});
console.log(JSON.stringify({ name: manifest.name, version: manifest.version, skills: entries }, null, 2));
} else {
console.log(`${manifest.name} ${manifest.version} bundle — ${slugs.length} skills:`);
for (const slug of slugs) console.log(` ${slug}`);
}
process.exit(0);
}
// ---------------------------------------------------------------------------
// status — install currency + which installed skills declare preconditions
// ---------------------------------------------------------------------------
/**
* Read every bundled skill's SKILL.md frontmatter and collect the slugs that
* declare a non-empty `requires:` list, paired with the raw tokens. Engine-
* free (frontmatter only); live checks are `gbrain doctor`'s job.
*/
function collectDeclaredPreconditions(gbrainRoot: string): Array<{ slug: string; requires: string[] }> {
const manifest = loadBundleManifest(gbrainRoot);
const slugs = bundledSkillSlugs(manifest);
const out: Array<{ slug: string; requires: string[] }> = [];
for (const slug of slugs) {
const skillMd = join(gbrainRoot, 'skills', slug, 'SKILL.md');
if (!existsSync(skillMd)) continue;
const fm = parseSkillFrontmatter(readFileSync(skillMd, 'utf-8'));
if (fm?.requires && fm.requires.length > 0) {
out.push({ slug, requires: fm.requires });
}
}
return out;
}
/**
* Static (engine-free) remediation hint per precondition kind, phrased to
* mirror preconditions.ts's live `checkOne` remediation strings. The live
* check needs an engine (`gbrain doctor` owns that); this is the paste-ready
* "what must be true" line for setup planning.
*/
function staticPreconditionHint(pre: Precondition): string {
switch (pre.kind) {
case 'source':
return pre.arg
? `add or ingest source '${pre.arg}' first (gbrain sources add ${pre.arg} / gbrain sync --source ${pre.arg}), then re-run`
: 'ingest a corpus first (gbrain sync / gbrain import), then re-run';
case 'dir':
return pre.arg
? `populate ${pre.arg} (>=1 page), then re-run`
: 'specify a directory: dir:<path> — see skillpack/preconditions.ts vocabulary';
case 'config':
return pre.arg
? `set it: gbrain config set ${pre.arg} <value>`
: 'specify a config key: config:<key> — see skillpack/preconditions.ts vocabulary';
case 'pages':
return pre.arg
? `the brain needs >=${pre.arg} pages; ingest more first`
: 'specify a page count: pages:<n> — see skillpack/preconditions.ts vocabulary';
case 'unknown':
default:
return `unrecognized precondition '${pre.raw}' — see skillpack/preconditions.ts vocabulary`;
}
}
async function cmdStatus(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack status [--workspace PATH] [--json]\n\n' +
'Report install currency (new / drifted / current) for every bundled\n' +
'skill, plus which installed skills declare machine-checkable\n' +
'preconditions. Read-only. Verify preconditions live with `gbrain doctor`.',
);
process.exit(0);
}
const json = args.includes('--json');
let workspace: string | null = null;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--workspace') {
workspace = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--workspace=')) {
workspace = a.slice('--workspace='.length) || null;
}
}
const gbrainRoot = findGbrainOrDie();
const targetWorkspace = resolveWorkspace({ workspace });
try {
const currency = computeSkillCurrency({ gbrainRoot, targetWorkspace });
const preconditions = collectDeclaredPreconditions(gbrainRoot);
const { collectBridgesStatus, printBridgesStatus } = await import('./skillpack/harness.ts');
if (json) {
console.log(JSON.stringify({ currency, preconditions, bridges: collectBridgesStatus(gbrainRoot) }, null, 2));
process.exit(0);
}
const c = currency.counts;
console.log(`new: ${c.new} drifted: ${c.drifted} current: ${c.current} (${c.total} total)`);
const newSlugs = currency.skills.filter(s => s.status === 'new').map(s => s.slug);
const driftedSlugs = currency.skills.filter(s => s.status === 'drifted').map(s => s.slug);
if (newSlugs.length) {
console.log('\nNew skills available (run `gbrain skillpack sync`):');
for (const slug of newSlugs) console.log(` ${slug}`);
}
if (driftedSlugs.length) {
console.log('\nDrifted from bundle (run `gbrain skillpack reference <slug>`):');
for (const slug of driftedSlugs) console.log(` ${slug}`);
}
if (preconditions.length) {
console.log('\nSkills with declared preconditions (verify with `gbrain doctor`):');
for (const p of preconditions) console.log(` ${p.slug}: ${p.requires.join(', ')}`);
}
printBridgesStatus(gbrainRoot);
process.exit(0);
} catch (err) {
if (err instanceof BundleError) {
console.error(`skillpack status: ${err.message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// sync — scaffold NEW skills only; report drift; never overwrite
// ---------------------------------------------------------------------------
async function cmdSync(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack sync [--workspace PATH] [--dry-run] [--json]\n\n' +
'Bring the install up to date by scaffolding NEW bundled skills only.\n' +
'Drifted skills are reported, never overwritten — you own those files\n' +
'(run `gbrain skillpack reference <slug>` to review). --dry-run lists\n' +
'what would be scaffolded without writing.',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
let workspace: string | null = null;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--workspace') {
workspace = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--workspace=')) {
workspace = a.slice('--workspace='.length) || null;
}
}
const gbrainRoot = findGbrainOrDie();
const targetWorkspace = resolveWorkspace({ workspace });
try {
const currency = computeSkillCurrency({ gbrainRoot, targetWorkspace });
const newSlugs = currency.skills.filter(s => s.status === 'new').map(s => s.slug);
const driftedSlugs = currency.skills.filter(s => s.status === 'drifted').map(s => s.slug);
// Scaffold NEW skills only. runScaffold refuses to overwrite any existing
// file by design, so drifted/current files are never touched — the
// ownership model. In --dry-run nothing is written.
const scaffolded: string[] = [];
const scaffoldedFiles: ScaffoldedFile[] = [];
for (const slug of newSlugs) {
scaffoldedFiles.push(...runScaffold({ gbrainRoot, targetWorkspace, skillSlug: slug, dryRun }).files);
scaffolded.push(slug);
}
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- targetWorkspace is the local operator's --workspace argument or the auto-detected workspace root, the same root runScaffold just wrote under.
const registered = dryRun ? [] : registerManifestEntries(join(targetWorkspace, 'skills'), scaffolded);
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- the same operator workspace root runScaffold just wrote under.
if (!dryRun) await recordScaffoldBases(join(targetWorkspace, 'skills'), scaffoldedFiles);
if (json) {
console.log(JSON.stringify({ scaffolded, registered, drifted: driftedSlugs, dryRun }, null, 2));
process.exit(0);
}
const verb = dryRun ? 'Would scaffold' : 'Scaffolded';
console.log(
`${verb} ${scaffolded.length} new skill(s)${scaffolded.length ? ': ' + scaffolded.join(', ') : ''}`,
);
if (registered.length) console.log(`Registered ${registered.length} of them in skills/manifest.json.`);
if (driftedSlugs.length) {
console.log(
`${driftedSlugs.length} skill(s) drifted from the bundle — run \`gbrain skillpack reference <slug>\` to review (not overwritten).`,
);
}
process.exit(0);
} catch (err) {
if (err instanceof ScaffoldError || err instanceof BundleError) {
console.error(`skillpack sync: ${(err as Error).message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// setup — declared preconditions + static paste-ready hints (engine-free)
// ---------------------------------------------------------------------------
async function cmdSetup(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack setup [<slug>] [--json]\n\n' +
'Print the declared preconditions + static remediation hints for a skill\n' +
'(or, with no slug, every bundled skill that declares preconditions).\n' +
"Static/engine-free — live verification is `gbrain doctor`'s job.",
);
process.exit(0);
}
const json = args.includes('--json');
let slug: string | null = null;
for (const a of args) {
if (a && !a.startsWith('--') && !slug) slug = a;
}
const gbrainRoot = findGbrainOrDie();
const targets: string[] = slug
? [slug]
: collectDeclaredPreconditions(gbrainRoot).map(p => p.slug);
const report = targets.map(s => {
const skillMd = join(gbrainRoot, 'skills', s, 'SKILL.md');
const fm = existsSync(skillMd) ? parseSkillFrontmatter(readFileSync(skillMd, 'utf-8')) : null;
const reqs = fm?.requires ?? [];
const preconditions = reqs.map(raw => {
const pre = parsePrecondition(raw);
return { raw, kind: pre.kind, arg: pre.arg ?? null, hint: staticPreconditionHint(pre) };
});
return { slug: s, preconditions };
});
if (json) {
console.log(JSON.stringify(report, null, 2));
process.exit(0);
}
for (const r of report) {
if (r.preconditions.length === 0) {
console.log(`${r.slug} has no declared preconditions.`);
continue;
}
console.log(`${r.slug} requires:`);
for (const p of r.preconditions) console.log(` - ${p.raw} → ${p.hint}`);
}
process.exit(0);
}
// ---------------------------------------------------------------------------
// migrate-fence
// ---------------------------------------------------------------------------
async function cmdMigrateFence(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log('gbrain skillpack migrate-fence [--workspace PATH] [--dry-run] [--json]');
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
let workspace: string | null = null;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--workspace') {
workspace = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--workspace=')) {
workspace = a.slice('--workspace='.length) || null;
}
}
const gbrainRoot = findGbrainOrDie();
const targetWorkspace = resolveWorkspace({ workspace });
const result = runMigrateFence({ targetWorkspace, gbrainRoot, dryRun });
if (json) console.log(JSON.stringify(result, null, 2));
else {
console.log(`migrate-fence: ${result.status}`);
if (result.resolverFile) console.log(` resolver: ${result.resolverFile}`);
if (result.fenceSlugs.length) console.log(` fenced slugs: ${result.fenceSlugs.join(', ')}`);
if (result.skillsCopied.length) console.log(` skills copied: ${result.skillsCopied.join(', ')}`);
if (result.skillsAlreadyPresent.length)
console.log(` already present: ${result.skillsAlreadyPresent.join(', ')}`);
if (result.usedRowFallback)
console.log(' (used row-parsing fallback — receipt was missing or drifted)');
// Next-action hint for the agent on a successful strip.
if (result.status === 'fence_stripped' && !dryRun) {
console.log(
'\nNext: your routing model just changed. The managed-block fence is gone.\nYour agent should walk `skills/*/SKILL.md` frontmatter `triggers:` for routing.\nPreserved table rows are a transitional bridge — once frontmatter walking is\nconfirmed working, run `gbrain skillpack scrub-legacy-fence-rows` to clean up.\nFresh install? Read `skills/_AGENT_README.md` for the full agent contract.',
);
}
}
process.exit(result.status === 'fence_malformed' ? 2 : 0);
}
// ---------------------------------------------------------------------------
// scrub-legacy-fence-rows
// ---------------------------------------------------------------------------
async function cmdScrubLegacy(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack scrub-legacy-fence-rows [--workspace PATH] [--dry-run] [--json]',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
let workspace: string | null = null;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--workspace') {
workspace = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--workspace=')) {
workspace = a.slice('--workspace='.length) || null;
}
}
const targetWorkspace = resolveWorkspace({ workspace });
const result = runScrubLegacy({ targetWorkspace, dryRun });
if (json) console.log(JSON.stringify(result, null, 2));
else {
console.log(
`scrub-legacy-fence-rows: ${result.removed.length} removed, ${result.preserved.length} preserved`,
);
if (result.removed.length) console.log(` removed: ${result.removed.join(', ')}`);
if (result.preserved.length) console.log(` preserved: ${result.preserved.join(', ')}`);
}
process.exit(0);
}
// ---------------------------------------------------------------------------
// search / info / registry (registry catalog reads)
// ---------------------------------------------------------------------------
async function cmdSearch(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack search [<query>] [--tier endorsed|community|experimental|dead] [--json] [--refresh] [--url URL]',
);
process.exit(0);
}
const json = args.includes('--json');
const refresh = args.includes('--refresh');
let query: string | undefined;
let tier: 'endorsed' | 'community' | 'experimental' | 'dead' | undefined;
let urlOverride: string | undefined;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--tier') {
tier = args[i + 1] as typeof tier;
i++;
} else if (a === '--url') {
urlOverride = args[i + 1];
i++;
} else if (a && !a.startsWith('--') && !query) {
query = a;
}
}
const { loadRegistry, searchPacks } = await import('../core/skillpack/registry-client.ts');
const loaded = await loadRegistry({ url: urlOverride, refresh });
const results = searchPacks(loaded, { query, tier });
if (json) {
console.log(
JSON.stringify(
{
registry_url: loaded.registry_url,
origin: loaded.origin,
cache_age_ms: loaded.cache_age_ms,
query: query ?? null,
tier_filter: tier ?? null,
count: results.length,
results: results.map((r) => ({
name: r.entry.name,
version: r.entry.version,
description: r.entry.description,
author: r.entry.author,
tier: r.tier,
tags: r.entry.tags,
homepage: r.entry.homepage,
})),
},
null,
2,
),
);
process.exit(0);
}
if (results.length === 0) {
console.log(`(no skillpacks matched${query ? ` "${query}"` : ''}${tier ? ` (tier=${tier})` : ''})`);
process.exit(0);
}
console.log(`${results.length} skillpack${results.length === 1 ? '' : 's'} (from ${loaded.registry_url})\n`);
for (const r of results) {
const tierBadge = r.tier === 'endorsed' ? '★' : r.tier === 'community' ? '·' : r.tier === 'experimental' ? '?' : '✗';
console.log(` ${tierBadge} ${r.entry.name}@${r.entry.version} [${r.tier}]`);
console.log(` ${r.entry.description}`);
console.log(` by ${r.entry.author} · ${r.entry.homepage}`);
if (r.entry.tags.length > 0) console.log(` tags: ${r.entry.tags.join(', ')}`);
console.log('');
}
process.exit(0);
}
async function cmdInfo(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log('gbrain skillpack info <name> [--json] [--refresh] [--url URL]');
process.exit(0);
}
const json = args.includes('--json');
const refresh = args.includes('--refresh');
let name: string | undefined;
let urlOverride: string | undefined;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--url') {
urlOverride = args[i + 1];
i++;
} else if (a && !a.startsWith('--') && !name) {
name = a;
}
}
if (!name) {
console.error('Error: pass a skillpack name.');
process.exit(2);
}
const { loadRegistry, findPackWithTier } = await import('../core/skillpack/registry-client.ts');
const loaded = await loadRegistry({ url: urlOverride, refresh });
const found = findPackWithTier(loaded, name);
if (!found) {
console.error(`Error: no skillpack named "${name}" in ${loaded.registry_url}.`);
process.exit(2);
}
if (json) {
console.log(
JSON.stringify(
{
name: found.entry.name,
version: found.entry.version,
description: found.entry.description,
author: found.entry.author,
author_handle: found.entry.author_handle,
homepage: found.entry.homepage,
tier: found.tier,
tags: found.entry.tags,
source: found.entry.source,
tarball_sha256: found.entry.tarball_sha256,
gbrain_min_version: found.entry.gbrain_min_version,
validated_at: found.entry.validated_at,
validation_run_id: found.entry.validation_run_id,
skills_count: found.entry.skills_count,
skills: found.entry.skills,
},
null,
2,
),
);
process.exit(0);
}
console.log(`${found.entry.name}@${found.entry.version} [${found.tier}]`);
console.log(` Description: ${found.entry.description}`);
console.log(` Author: ${found.entry.author} (@${found.entry.author_handle})`);
console.log(` Homepage: ${found.entry.homepage}`);
console.log(` Source: ${found.entry.source.url}`);
console.log(` Pinned commit: ${found.entry.source.pinned_commit}`);
console.log(` Tarball SHA: sha256:${found.entry.tarball_sha256}`);
console.log(` gbrain min: ${found.entry.gbrain_min_version}`);
console.log(` Validated: ${found.entry.validated_at} (run ${found.entry.validation_run_id})`);
console.log(` Tags: ${found.entry.tags.join(', ')}`);
console.log(` Skills (${found.entry.skills_count}):`);
for (const s of found.entry.skills) console.log(` - ${s}`);
console.log('\nTo scaffold:');
console.log(` gbrain skillpack scaffold ${found.entry.name}`);
process.exit(0);
}
async function cmdRegistry(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack registry [--url URL] [--refresh] [--json]\n' +
'\n' +
' --url URL Set the registry URL (writes to ~/.gbrain/config.json)\n' +
' --refresh Force a fresh fetch from the current registry URL\n' +
' --json JSON output for agent consumption',
);
process.exit(0);
}
const json = args.includes('--json');
const refresh = args.includes('--refresh');
let setUrl: string | undefined;
for (let i = 0; i < args.length; i++) {
if (args[i] === '--url' && args[i + 1]) {
setUrl = args[i + 1];
i++;
}
}
if (setUrl) {
// Persist to ~/.gbrain/config.json under skillpack.registry_url.
const { gbrainPath } = await import('../core/config.ts');
const cfgPath = gbrainPath('config.json');
let cfg: Record<string, unknown> = {};
if (existsSync(cfgPath)) {
try {
cfg = JSON.parse(readFileSync(cfgPath, 'utf-8')) as Record<string, unknown>;
} catch {
cfg = {};
}
}
(cfg as Record<string, unknown>).skillpack = {
...((cfg.skillpack as Record<string, unknown>) ?? {}),
registry_url: setUrl,
};
const tmp = cfgPath + '.tmp';
const fs = await import('fs');
fs.mkdirSync(require('path').dirname(cfgPath), { recursive: true });
fs.writeFileSync(tmp, JSON.stringify(cfg, null, 2) + '\n');
fs.renameSync(tmp, cfgPath);
console.log(`Set skillpack.registry_url = ${setUrl}`);
}
const { loadRegistry, resolveRegistryUrl } = await import('../core/skillpack/registry-client.ts');
const url = resolveRegistryUrl({});
try {
const loaded = await loadRegistry({ refresh });
if (json) {
console.log(
JSON.stringify(
{
registry_url: loaded.registry_url,
origin: loaded.origin,
cache_age_ms: loaded.cache_age_ms,
skillpack_count: loaded.catalog.skillpacks.length,
updated_at: loaded.catalog.updated_at,
bundles: Object.keys(loaded.catalog.bundles ?? {}),
},
null,
2,
),
);
} else {
console.log(`Registry: ${loaded.registry_url}`);
console.log(`Origin: ${loaded.origin}` + (loaded.cache_age_ms !== null ? ` (${loaded.cache_age_ms}ms old)` : ''));
console.log(`Updated: ${loaded.catalog.updated_at}`);
console.log(`Skillpacks: ${loaded.catalog.skillpacks.length}`);
const bundleNames = Object.keys(loaded.catalog.bundles ?? {});
if (bundleNames.length > 0) console.log(`Bundles: ${bundleNames.join(', ')}`);
}
process.exit(0);
} catch (err) {
console.error(`Error: ${(err as Error).message}`);
console.error(`Currently configured registry: ${url}`);
process.exit(2);
}
}
// ---------------------------------------------------------------------------
// doctor — quality rubric runner
// ---------------------------------------------------------------------------
async function cmdDoctor(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack doctor <pack-dir> [--quick|--full] [--fix] [--yes] [--json]\n\n' +
' <pack-dir> Path to the skillpack root (where skillpack.json lives)\n' +
' --quick Structural rubric (~5s, no sandbox/LLM/DB) — default\n' +
' --full Add publish-gate suite execution (lands in a follow-up wave)\n' +
' --fix Auto-scaffold missing pieces flagged auto_fixable=true\n' +
' --yes Skip confirm prompts (CI / unattended)\n' +
' --json Stable JSON envelope for agent consumption',
);
process.exit(0);
}
const json = args.includes('--json');
const fix = args.includes('--fix');
const yes = args.includes('--yes');
const mode = args.includes('--full') ? 'full' : 'quick';
let packDir: string | undefined;
for (const a of args) {
if (a && !a.startsWith('--') && !packDir) packDir = a;
}
if (!packDir) {
console.error('Error: pass the path to the pack root (where skillpack.json lives).');
process.exit(2);
}
const packRoot = resolveAbs(packDir);
const { runDoctor, formatDoctorResult } = await import('../core/skillpack/doctor.ts');
const result = await runDoctor({ packRoot, mode, fix, yes });
if (json) {
console.log(JSON.stringify(result, null, 2));
} else {
console.log(formatDoctorResult(result));
}
// Exit codes: 0 if score=10, 1 if 6-9, 2 if blocked/<5.
if (result.tier_eligibility === 'blocked' || result.score < 5) {
process.exit(2);
}
if (result.score < 10) process.exit(1);
process.exit(0);
}
// ---------------------------------------------------------------------------
// init — publisher scaffold
// ---------------------------------------------------------------------------
async function cmdInit(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack init <name> [--target PATH] [--minimal] [--author NAME] [--license SPDX] [--homepage URL] [--dry-run] [--json]\n\n' +
' <name> Pack name (lowercase kebab; becomes manifest.name + dir leaf)\n' +
' --target Target dir (default: ./<name>)\n' +
' --minimal Skip test/, e2e/, evals/ (advanced; doctor will score lower)\n' +
' --dry-run Report intent, no writes\n' +
' --json JSON envelope for agent consumption',
);
process.exit(0);
}
const json = args.includes('--json');
const minimal = args.includes('--minimal');
const dryRun = args.includes('--dry-run');
let name: string | undefined;
let target: string | undefined;
let author: string | undefined;
let license: string | undefined;
let homepage: string | undefined;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--target') {
target = args[i + 1];
i++;
} else if (a === '--author') {
author = args[i + 1];
i++;
} else if (a === '--license') {
license = args[i + 1];
i++;
} else if (a === '--homepage') {
homepage = args[i + 1];
i++;
} else if (a && !a.startsWith('--') && !name) {
name = a;
}
}
if (!name) {
console.error('Error: pass the new skillpack name.');
process.exit(2);
}
const { runInitScaffold, InitScaffoldError } = await import('../core/skillpack/init-scaffold.ts');
const targetDir = resolveAbs(target ?? `./${name}`);
try {
const result = runInitScaffold({
targetDir,
name,
minimal,
author,
license,
homepage,
dryRun,
});
if (json) {
console.log(
JSON.stringify(
{
ok: true,
dry_run: dryRun,
target: result.targetDir,
files_written: result.filesWritten,
files_skipped_existing: result.filesSkippedExisting,
manifest: result.manifest,
},
null,
2,
),
);
} else {
console.log(
`${dryRun ? 'init (dry-run)' : 'init'}: ${result.filesWritten.length} files written, ${result.filesSkippedExisting.length} skipped (already existed) at ${result.targetDir}`,
);
if (result.filesSkippedExisting.length > 0 && !dryRun) {
console.log('\nSkipped existing files (preserved):');
for (const p of result.filesSkippedExisting) console.log(` ${p}`);
}
if (!dryRun) {
console.log(
`\nNext:\n cd ${result.targetDir}\n gbrain skillpack doctor . --quick\n # iterate, then:\n gbrain skillpack pack`,
);
}
}
process.exit(0);
} catch (err) {
if (err instanceof InitScaffoldError) {
console.error(`skillpack init: ${err.message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// init-brain-pack — scaffold a brain-resident pack inside a brain/source repo
// ---------------------------------------------------------------------------
async function cmdInitBrainPack(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack init-brain-pack <name> [--target PATH] [--schema-pack NAME] [--author NAME] [--license SPDX] [--homepage URL] [--dry-run] [--json]\n\n' +
' <name> Pack name (lowercase kebab; becomes manifest.name)\n' +
' --target Brain/source repo root (default: .)\n' +
' --schema-pack Schema pack these skills assume (default: gbrain-base)\n' +
' --dry-run Report intent, no writes\n' +
' --json JSON envelope for agent consumption\n\n' +
'Writes a brain-resident skillpack (skillpack.json brain_resident:true + a\n' +
'machine-parseable README) beside your brain content. Connecting harnesses\n' +
'discover it via `sources add` and the `list_brain_skillpack` MCP tool.',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
let name: string | undefined;
let target: string | undefined;
let schemaPack: string | undefined;
let author: string | undefined;
let license: string | undefined;
let homepage: string | undefined;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--target') {
target = args[i + 1];
i++;
} else if (a === '--schema-pack') {
schemaPack = args[i + 1];
i++;
} else if (a === '--author') {
author = args[i + 1];
i++;
} else if (a === '--license') {
license = args[i + 1];
i++;
} else if (a === '--homepage') {
homepage = args[i + 1];
i++;
} else if (a && !a.startsWith('--') && !name) {
name = a;
}
}
if (!name) {
console.error('Error: pass the new brain-pack name.');
process.exit(2);
}
const { runInitBrainPack, InitBrainPackError } = await import('../core/skillpack/init-brain-pack.ts');
const targetDir = resolveAbs(target ?? '.');
try {
const result = runInitBrainPack({ targetDir, name, schemaPack, author, license, homepage, dryRun });
if (json) {
console.log(
JSON.stringify(
{
ok: true,
dry_run: dryRun,
target: result.targetDir,
files_written: result.filesWritten,
files_skipped_existing: result.filesSkippedExisting,
manifest: result.manifest,
},
null,
2,
),
);
} else {
console.log(
`${dryRun ? 'init-brain-pack (dry-run)' : 'init-brain-pack'}: ${result.filesWritten.length} files written, ${result.filesSkippedExisting.length} skipped (already existed) at ${result.targetDir}`,
);
if (result.filesSkippedExisting.length > 0 && !dryRun) {
console.log('\nSkipped existing files (preserved):');
for (const p of result.filesSkippedExisting) console.log(` ${p}`);
}
if (!dryRun) {
console.log(
`\nNext:\n Edit README.md (the 5 sections a harness reads) + skills/<slug>/SKILL.md\n Commit it to the brain repo. Connecting harnesses will be offered it.`,
);
}
}
process.exit(0);
} catch (err) {
if (err instanceof InitBrainPackError) {
console.error(`skillpack init-brain-pack: ${err.message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// pack — publisher tarball emit + local validation
// ---------------------------------------------------------------------------
async function cmdPack(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack pack [<pack-dir>] [--out PATH] [--dry-run] [--skip-doctor] [--json]\n\n' +
' <pack-dir> Pack root (default: .)\n' +
' --out PATH Output dir for the tarball (default: <pack-dir>)\n' +
' --dry-run Validate only, no tarball\n' +
' --skip-doctor Skip the doctor gate (publish-gate skill uses this)\n' +
' --json JSON envelope for agent consumption',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
const skipDoctor = args.includes('--skip-doctor');
let packDir: string | undefined;
let outDir: string | undefined;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--out') {
outDir = args[i + 1];
i++;
} else if (a && !a.startsWith('--') && !packDir) {
packDir = a;
}
}
const packRoot = resolveAbs(packDir ?? '.');
const { runPackPublish, PackPublishError } = await import('../core/skillpack/pack-publish.ts');
try {
const result = await runPackPublish({
packRoot,
outDir: outDir ? resolveAbs(outDir) : undefined,
dryRun,
skipDoctor,
});
if (json) {
console.log(JSON.stringify(result, null, 2));
} else if (result.refused_reason) {
console.error(`skillpack pack: refused — ${result.refused_reason}`);
if (result.doctor) {
const blocked = result.doctor.dimensions.filter((d) => !d.passed && d.category === 'core');
for (const d of blocked) console.error(` ✗ ${d.name}: ${d.detail}`);
}
console.error('\nRun `gbrain skillpack doctor . --fix --yes` to auto-scaffold what you can, then re-run.');
process.exit(2);
} else if (result.tarball) {
console.log(`pack: ${result.pack_name}@${result.pack_version} -> ${result.tarball.outPath}`);
console.log(` SHA-256: sha256:${result.tarball.sha256}`);
console.log(` File count: ${result.tarball.fileCount}`);
console.log(` Compressed: ${result.tarball.compressedBytes} bytes`);
console.log(` Tier eligible: ${result.tarball.tier_eligibility}`);
} else {
console.log(`pack (dry-run): ${result.pack_name}@${result.pack_version} — doctor verdict ${result.doctor?.tier_eligibility ?? '(skipped)'}`);
}
process.exit(0);
} catch (err) {
if (err instanceof PackPublishError) {
console.error(`skillpack pack: ${err.message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// endorse — Garry-only registry tier override (operator workflow)
// ---------------------------------------------------------------------------
async function cmdEndorse(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack endorse <name> [--tier endorsed|community|experimental|dead] [--repo PATH] [--note TEXT] [--push] [--dry-run] [--json]\n\n' +
' <name> Pack name as it appears in registry.json\n' +
' --tier Target tier (default: endorsed)\n' +
' --repo Path to a clone of the registry repo (default: .)\n' +
' --note Optional human note recorded in endorsements.json\n' +
' --push git push origin HEAD after committing\n' +
' --dry-run Report what would change without writing or committing\n' +
' --json Stable JSON envelope for agent consumption\n\n' +
'This is the Garry-only operator workflow. It writes endorsements.json + commits;\n' +
'requires a clone of garrytan/gbrain-skillpack-registry (or any registry-shaped repo).',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
const push = args.includes('--push');
let name: string | undefined;
let tier: 'endorsed' | 'community' | 'experimental' | 'dead' | undefined;
let repo: string | undefined;
let note: string | undefined;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--tier') {
tier = args[i + 1] as typeof tier;
i++;
} else if (a === '--repo') {
repo = args[i + 1];
i++;
} else if (a === '--note') {
note = args[i + 1];
i++;
} else if (a && !a.startsWith('--') && !name) {
name = a;
}
}
if (!name) {
console.error('Error: pass a skillpack name.');
process.exit(2);
}
const { runEndorse, EndorseError } = await import('../core/skillpack/endorse.ts');
const registryRepoRoot = resolveAbs(repo ?? '.');
try {
const result = runEndorse({
registryRepoRoot,
packName: name,
tier,
note,
push,
dryRun,
});
if (json) {
console.log(JSON.stringify(result, null, 2));
} else {
const verb = dryRun ? 'would endorse' : 'endorsed';
const fromTo = result.prior_tier
? `${result.prior_tier} -> ${result.new_tier}`
: `(unset) -> ${result.new_tier}`;
console.log(`${verb}: ${result.pack_name} ${fromTo}`);
if (result.commit_sha) console.log(`commit: ${result.commit_sha}`);
if (result.pushed) console.log(`pushed to origin`);
if (dryRun) console.log(`\n(no writes; re-run without --dry-run to commit)`);
}
process.exit(0);
} catch (err) {
if (err instanceof EndorseError) {
console.error(`skillpack endorse: ${err.message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// harvest
// ---------------------------------------------------------------------------
async function cmdHarvest(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack harvest <slug> --from <host-repo-root> [--no-lint] [--dry-run] [--overwrite-local] [--json]',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
const noLint = args.includes('--no-lint');
const overwriteLocal = args.includes('--overwrite-local');
let slug: string | null = null;
let from: string | null = null;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--from') {
from = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--from=')) {
from = a.slice('--from='.length) || null;
} else if (a && !a.startsWith('--') && !slug) {
slug = a;
}
}
if (!slug) {
console.error('Error: pass a slug.');
process.exit(2);
}
if (!from) {
console.error('Error: pass --from <host-repo-root>.');
process.exit(2);
}
const gbrainRoot = findGbrainOrDie();
try {
const result = runHarvest({
slug,
hostRepoRoot: resolveAbs(from),
gbrainRoot,
noLint,
dryRun,
overwriteLocal,
});
if (json) console.log(JSON.stringify(result, null, 2));
else {
console.log(`harvest ${slug}: ${result.status}`);
if (result.filesCopied.length)
console.log(` files: ${result.filesCopied.length} copied`);
if (result.pairedSources.length)
console.log(` paired sources: ${result.pairedSources.join(', ')}`);
if (result.manifestUpdated) console.log(' openclaw.plugin.json updated');
if (result.lintHits.length) {
console.log(' privacy-lint hits (harvest rolled back):');
for (const h of result.lintHits) console.log(` ${h}`);
}
}
// Exit non-zero on lint failure so the editorial workflow knows to scrub.
process.exit(result.status === 'lint_failed' ? 1 : 0);
} catch (err) {
if (err instanceof HarvestError || err instanceof BundleError) {
console.error(`skillpack harvest: ${(err as Error).message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// diff (informational — preserved from v0.32; uses legacy installer's
// diffSkill which still ships unchanged until T12 deletes it)
// ---------------------------------------------------------------------------
async function cmdDiff(args: string[]): Promise<void> {
// Lazy-import the legacy diff helper. T12 deletes installer.ts; until
// then this path keeps the existing semantics.
const { diffSkill } = await import('../core/skillpack/installer.ts');
if (args.includes('--help') || args.includes('-h')) {
console.log('gbrain skillpack diff <name> [--workspace PATH] [--json]');
process.exit(0);
}
const json = args.includes('--json');
let name: string | null = null;
let skillsDir: string | null = null;
let workspace: string | null = null;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--workspace') {
workspace = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--workspace=')) {
workspace = a.slice('--workspace='.length) || null;
} else if (a === '--skills-dir') {
skillsDir = args[i + 1] ?? null;
i++;
} else if (a?.startsWith('--skills-dir=')) {
skillsDir = a.slice('--skills-dir='.length) || null;
} else if (a && !a.startsWith('--') && !name) {
name = a;
}
}
if (!name) {
console.error('Error: pass a skill name.');
process.exit(2);
}
const gbrainRoot = findGbrainOrDie();
const targetSkillsDir = skillsDir
? resolveAbs(skillsDir)
: join(resolveWorkspace({ workspace }), 'skills');
try {
const diffs = diffSkill(gbrainRoot, name, targetSkillsDir);
const clean = diffs.every(d => d.identical && d.existing);
if (json) console.log(JSON.stringify({ ok: true, skillName: name, diffs }, null, 2));
else {
console.log(`skillpack diff ${name} → ${targetSkillsDir}`);
for (const d of diffs) {
let tag: string;
if (!d.existing) tag = 'missing ';
else if (d.identical) tag = 'identical';
else tag = 'differs ';
console.log(` ${tag} ${d.target} (src ${d.sourceBytes}B / tgt ${d.targetBytes}B)`);
}
console.log(clean ? '\n✓ all files match the bundle.' : '\n(Run `gbrain skillpack reference ' + name + '` for a unified diff.)');
}
// v0.33: diff is informational; exit 0 always.
process.exit(0);
} catch (err) {
if (err instanceof BundleError) {
console.error(`skillpack diff: ${err.message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// check — routes to skillpack-check (T10 adds --strict)
// ---------------------------------------------------------------------------
async function routeCheck(args: string[]): Promise<void> {
const { runSkillpackCheck } = await import('./skillpack-check.ts');
await runSkillpackCheck(args);
}