Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain skillpack scaffold/reference/remove` — harness lane (cathedral-7).
*
* Installs persona-curated bundled skills into a harness's native skills
* dir (claude-code today; codex/opencode behind an explicit dest until
* their locations get observation runs; openclaw delegates to the
* workspace scaffold).
*
* Flag-registry note: this file is scanned for skillpack's flag allowlist
* (bare dash-dash tokens in comments AND strings register as flags, one
* import level deep). Spell foreign (non-skillpack) CLI flags WITHOUT
* leading dashes — including in stub/preflight hint text. Deliberately does
* NOT import src/mcp/surface.ts (its comments carry serve-flag tokens that
* would bleed into this command's allowlist); skill discovery is available
* on starter/full, while the seven-verb surface remains memory-only.
*/
import { existsSync, readFileSync } from 'fs';
import { join } from 'path';
import type { BrainEngine } from '../../core/engine.ts';
import { loadConfig } from '../../core/config.ts';
import { VERSION } from '../../version.ts';
import { recordScaffoldBases } from '../../core/skillpack/safe-update.ts';
import { autoDetectSkillsDir } from '../../core/repo-root.ts';
import {
claudeProjectSkillsDir,
claudeUserSkillsDir,
} from '../../core/bootstrap/host-specs.ts';
import {
BRIDGE_HARNESSES,
BridgeError,
isBridgeHarness,
planHarnessBridge,
applyHarnessBridge,
runHarnessReference,
runHarnessReferenceApply,
removeHarnessBridge,
verifySlugsServable,
assertDestNotSymlink,
ownedBridgeSlugs,
type BridgeHarness,
} from '../../core/skillpack/harness-bridge.ts';
import {
PersonaError,
loadPersonas,
resolvePersonaSlugs,
validateSlugsAgainstLane,
} from '../../core/skillpack/personas.ts';
import {
loadBridgeState,
findBridgeEntry,
defaultBridgeStatePath,
BridgeStateError,
} from '../../core/skillpack/bridge-state.ts';
import { CopyError } from '../../core/skillpack/copy.ts';
import { runScaffold, ScaffoldError } from '../../core/skillpack/scaffold.ts';
import { BundleError, bundledSkillSlugs, loadBundleManifest } from '../../core/skillpack/bundle.ts';
import { findGbrainOrDie, resolveAbs, resolveWorkspace } from './shared.ts';
import { installSharedBrainBridge } from '../../core/skillpack/shared-brain-bridge.ts';
import { nativeSharedSkillsDirectory } from '../../core/harness/native-router.ts';
import { confinedSkillChildWrite } from '../../core/skillpack/writer-guard.ts';
/** OpenClaw's default: the brain-first core. OpenClaw lists every workspace
* skill's description in every prompt, so the full bundle (`all`) cost about
* 61k input tokens per trial in the HARN-5 install ladder and was never called. */
const OPENCLAW_CORE_SKILLS = ['brain-ops', 'capture', 'data-loss-gate', 'query', 'resolve-before-asking'];
const DEFAULT_PERSONA: Record<Exclude<BridgeHarness, 'openclaw'>, string> = {
'claude-code': 'coding-agent',
codex: 'coding-agent',
opencode: 'coding-agent',
};
interface HarnessArgs {
harness: BridgeHarness;
persona: string | null;
skills: string[];
dest: string | null;
scope: 'user' | 'project';
stub: boolean;
workspace: string | null;
dryRun: boolean;
json: boolean;
all: boolean;
applyCleanHunks: boolean;
skillsPolicy?: 'follow' | 'memory-only';
/** Bare (non-flag) tokens, in order — e.g. reference's <slug>. */
positional: string[];
}
const VALUE_FLAGS = new Set(['--harness', '--persona', '--skill', '--dest', '--scope', '--workspace', '--skills']);
const BOOL_FLAGS = new Set(['--stub', '--dry-run', '--json', '--all', '--apply-clean-hunks', '--help', '-h']);
function parseHarnessArgs(args: string[], cmd: string): HarnessArgs {
let harness: string | null = null;
let persona: string | null = null;
const skills: string[] = [];
let dest: string | null = null;
let scope: 'user' | 'project' = 'user';
let workspace: string | null = null;
let skillsPolicy: HarnessArgs['skillsPolicy'];
const positional: string[] = [];
const assign = (flag: string, value: string | null): void => {
if (value == null || value === '') {
console.error(`Error: ${flag} needs a value.`);
process.exit(2);
}
switch (flag) {
case '--harness':
harness = value;
break;
case '--persona':
persona = value;
break;
case '--skill':
skills.push(value);
break;
case '--dest':
dest = value;
break;
case '--scope':
if (value !== 'user' && value !== 'project') {
console.error(`Error: --scope must be 'user' or 'project' (got ${JSON.stringify(value)}).`);
process.exit(2);
}
scope = value;
break;
case '--workspace':
workspace = value;
break;
case '--skills':
if (value !== 'follow' && value !== 'memory-only') {
console.error('Error: --skills must be follow or memory-only.');
process.exit(2);
}
skillsPolicy = value;
break;
}
};
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (!a) continue;
const eq = a.indexOf('=');
const flagName = a.startsWith('--') && eq > 0 ? a.slice(0, eq) : a;
if (VALUE_FLAGS.has(flagName)) {
if (eq > 0) assign(flagName, a.slice(eq + 1));
else {
assign(flagName, args[i + 1] ?? null);
i++;
}
} else if (BOOL_FLAGS.has(a)) {
// handled via args.includes below
} else if (BOOL_FLAGS.has(flagName) && eq > 0) {
// Agents commonly emit `--dry-run=true`; the flag registry tolerates
// the value but args.includes() would silently miss it — a real write
// on an intended dry run. Refuse instead of guessing.
console.error(`Error: ${flagName} is a boolean flag and takes no value (drop the '=${a.slice(eq + 1)}').`);
process.exit(2);
} else if (!a.startsWith('--')) {
positional.push(a);
}
// Unknown dash-dash flags fall through to the registry validator.
}
if (!harness || !isBridgeHarness(harness)) {
console.error(
`Error: ${cmd} requires --harness <${BRIDGE_HARNESSES.join('|')}> (got ${JSON.stringify(harness)}).`,
);
process.exit(2);
}
return {
harness,
persona,
skills,
dest,
scope,
stub: args.includes('--stub'),
workspace,
dryRun: args.includes('--dry-run'),
json: args.includes('--json'),
all: args.includes('--all'),
applyCleanHunks: args.includes('--apply-clean-hunks'),
skillsPolicy,
positional,
};
}
/** Resolve the install dest for a bridge harness (never openclaw). */
function resolveDest(a: HarnessArgs): string {
if (a.dest) return resolveAbs(a.dest);
if (a.harness === 'claude-code') {
if (a.scope === 'project') {
const ws = a.workspace ? resolveAbs(a.workspace) : process.cwd();
return claudeProjectSkillsDir(ws);
}
return claudeUserSkillsDir();
}
// codex / opencode: no attested native skills dir yet — an explicit dest
// is required until the observation-run follow-up lands a verified default.
console.error(
`Error: ${a.harness} has no attested native skills dir yet — pass --dest <dir>.\n` +
`(The plugin lane already serves ${a.harness === 'codex' ? 'codex' : 'this harness'} skills; ` +
`a direct-copy default ships after an observation run — see the TODOS.md follow-up.)`,
);
process.exit(2);
}
/** Resolve the slug set: explicit picks (lane-validated) beat persona;
* --all is shorthand for --persona all (the full lane). */
function resolveSlugs(gbrainRoot: string, a: HarnessArgs): { slugs: string[]; persona: string | null } {
if (a.all && a.persona && a.persona !== 'all') {
console.error(`Error: --all conflicts with --persona ${a.persona} (pick one).`);
process.exit(2);
}
if (a.skills.length > 0) {
if (a.all) {
console.error('Error: --all conflicts with explicit --skill picks (pick one).');
process.exit(2);
}
validateSlugsAgainstLane(gbrainRoot, a.skills);
return { slugs: [...new Set(a.skills)].sort(), persona: null };
}
if (a.harness === 'openclaw' && a.persona === null && !a.all) return { slugs: OPENCLAW_CORE_SKILLS, persona: 'core' };
const persona = a.persona ?? (a.all ? 'all' : DEFAULT_PERSONA[a.harness as Exclude<BridgeHarness, 'openclaw'>]);
return { slugs: resolvePersonaSlugs(gbrainRoot, persona), persona };
}
/**
* Best-effort engine open for the dual-plane config reads. `gbrain config
* set` writes the DB plane, so a file-only read would tell users to run the
* exact command they already ran. Any failure degrades to the file plane.
*/
async function withBestEffortEngine<T>(fn: (engine: BrainEngine | null) => Promise<T>): Promise<T> {
const config = loadConfig();
if (config?.remote_mcp) return fn(null);
let engine: BrainEngine | null = null;
if (config) {
try {
const { createEngine } = await import('../../core/engine-factory.ts');
const { toEngineConfig } = await import('../../core/config.ts');
const { connectWithRetry } = await import('../../core/db.ts');
engine = await createEngine(toEngineConfig(config));
await connectWithRetry(engine, toEngineConfig(config), { noRetry: true });
} catch {
engine = null;
}
}
try {
return await fn(engine);
} finally {
try {
await engine?.disconnect();
} catch {}
}
}
async function dualPlaneConfig(engine: BrainEngine | null, key: string): Promise<string | undefined> {
if (engine) {
try {
const v = await engine.getConfig(key);
if (v != null) return v;
} catch {}
}
return undefined;
}
/**
* Stub preflight [D3B]: three checks, all fail-loud where they can be.
* 1. mcp.publish_skills must be true (DB plane wins, file plane fallback) —
* a stub pointing at a gated op is a dead pointer.
* 2. Every requested slug must be servable from the skills dir the MCP
* server would resolve (mcp.skills_dir override, else auto-detect).
* 3. Best-effort surface warn: get_skill is exposed on starter/full, but
* not the seven-verb surface. This check reads LOCAL
* config only — it cannot see a plugin manifest's hard-coded surface
* or a remote server's ceiling.
*/
async function stubPreflight(gbrainRoot: string, slugs: readonly string[]): Promise<void> {
await withBestEffortEngine(async engine => {
const config = loadConfig();
// (1) publish gate — fail closed.
const dbPublish = await dualPlaneConfig(engine, 'mcp.publish_skills');
const publish = dbPublish != null ? dbPublish === 'true' : config?.mcp?.publish_skills === true;
if (!publish) {
console.error(
'Error: stub mode requires skill publishing to be ON — the stubs point agents at the\n' +
'gbrain MCP get_skill op, which is gated by mcp.publish_skills (currently off).\n' +
'Enable it first: gbrain config set mcp.publish_skills true',
);
process.exit(2);
}
// (2) catalog resolvability — fail closed.
const dbSkillsDir = await dualPlaneConfig(engine, 'mcp.skills_dir');
const configuredDir = dbSkillsDir ?? config?.mcp?.skills_dir;
const serverDir = configuredDir ? resolveAbs(configuredDir) : autoDetectSkillsDir().dir;
if (!serverDir || !existsSync(serverDir)) {
console.error(
'Error: stub mode could not resolve the skills dir the MCP server would serve\n' +
'get_skill from (no mcp.skills_dir configured and auto-detection found nothing).\n' +
'Point the server at a skills tree: gbrain config set mcp.skills_dir <path>',
);
process.exit(2);
}
const missing = verifySlugsServable(serverDir, slugs);
if (missing.length > 0) {
console.error(
`Error: stub mode would install pointers at skills the MCP server cannot serve\n` +
`from ${serverDir}: ${missing.join(', ')}.\n` +
'A stub for an unservable skill is a dead pointer. Fix the server skills dir\n' +
'(gbrain config set mcp.skills_dir <path>) or drop those skills.',
);
process.exit(2);
}
// (3) surface warn — best-effort, local config only.
const dbSurface = await dualPlaneConfig(engine, 'mcp_surface');
const surface = dbSurface ?? (config as { mcp_surface?: string } | null)?.mcp_surface;
if (surface === 'verbs') {
console.error(
`warn: your configured MCP surface is '${surface}', which does not expose get_skill\n` +
' The stubs need surface starter or full, plus explicit operation grants\n' +
' and skill publishing. This check reads local configuration only;\n' +
' inspect the actual connection capabilities after restarting.',
);
}
});
}
// ---------------------------------------------------------------------------
// scaffold --harness
// ---------------------------------------------------------------------------
export async function cmdScaffoldHarness(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack scaffold --harness <claude-code|openclaw|codex|opencode>\n' +
' [--persona <name>|all] [--skill <slug>]... [--dest PATH] [--scope user|project]\n' +
' [--stub] [--workspace PATH] [--skills follow|memory-only] [--dry-run] [--json]\n\n' +
'Install a persona-curated set of bundled skills into a harness\'s native\n' +
'skills dir. Additive; never overwrites your files (local edits win).\n\n' +
' --persona Named curation from skills/plugin-lanes.json#personas,\n' +
' or `all` for the full plugin lane. Defaults: claude-code/\n' +
' codex/opencode → coding-agent; openclaw → the five-skill\n' +
' brain-first core (--all for the full bundle).\n' +
' --all Shorthand for the full plugin lane (same as persona all).\n' +
' --skill Explicit slug picks (repeatable; overrides --persona).\n' +
' --dest Install dir override. Required for codex/opencode (no\n' +
' attested native skills dir yet).\n' +
' --scope claude-code only: user (default) → the user-level skills\n' +
' dir; project → <workspace>/.claude/skills.\n' +
' --stub Cold-pull mode: install pointer SKILL.md files that fetch\n' +
' the body via the gbrain MCP get_skill op (preflight-gated).\n' +
' --skills Explicitly follow the active shared catalog through its\n' +
' source-bound router, or select memory-only. Existing\n' +
' copied skills require a separate reviewed migration.\n' +
' --dry-run Plan + report; no writes.\n',
);
process.exit(0);
}
const a = parseHarnessArgs(args, 'scaffold --harness');
if (a.positional.length > 0) {
console.error(
`Error: unexpected argument '${a.positional[0]}' — the harness lane takes skills via --skill (did you mean --skill ${a.positional[0]}?).`,
);
process.exit(2);
}
try {
const shared = await withBestEffortEngine(engine => installSharedBrainBridge({ engine, config: loadConfig(), harness: a.harness,
policy: a.skillsPolicy, dryRun: a.dryRun,
dest: a.dest ? resolveAbs(a.dest) : a.harness === 'claude-code' ? resolveDest(a)
: a.harness === 'openclaw' && a.workspace ? confinedSkillChildWrite(resolveAbs(a.workspace), 'skills', { dryRun: a.dryRun }) : nativeSharedSkillsDirectory(a.harness) ?? undefined }));
if (shared) {
if (a.json) console.log(JSON.stringify({ ok: true, harness: a.harness, dryRun: a.dryRun, ...shared }, null, 2));
else console.log(`shared skills: ${shared.status} (${shared.reason})\n${shared.next_action}`);
process.exit(0);
}
const gbrainRoot = findGbrainOrDie();
// openclaw: the workspace scaffold IS the native install — delegate with
// persona filtering. Stub mode is refused (openclaw users are the brain
// host; the full bodies live next to the brain anyway).
if (a.harness === 'openclaw') {
if (a.stub) {
console.error('Error: --stub is not supported for openclaw (the workspace hosts the brain — full bodies are the native shape).');
process.exit(2);
}
if (a.dest) {
console.error('Error: openclaw installs into a workspace, not a dest dir. Use --workspace PATH.');
process.exit(2);
}
const targetWorkspace = resolveWorkspace({ workspace: a.workspace });
const { slugs, persona } = resolveSlugs(gbrainRoot, a);
const useFullBundle = persona === 'all';
// The workspace scaffold enumerates the OPENCLAW universe (paired
// sources included) — plugin-lane ADDITIONS don't exist there, so a
// persona slug outside openclaw.plugin.json#skills must be reported,
// not thrown at as an unknown skill.
const openclawSlugs = new Set(bundledSkillSlugs(loadBundleManifest(gbrainRoot)));
const deliverable = useFullBundle ? slugs : slugs.filter(s => openclawSlugs.has(s));
const laneOnly = useFullBundle ? [] : slugs.filter(s => !openclawSlugs.has(s));
if (!useFullBundle && deliverable.length === 0) {
console.error(
'Error: none of the selected skills exist in the openclaw bundle (they are plugin-lane additions). Nothing to scaffold.',
);
process.exit(2);
}
const result = runScaffold({
gbrainRoot,
targetWorkspace,
skillSlug: null,
// The full bundle (--all) enumerates the openclaw universe directly;
// the core default, persona and skill picks filter it.
...(useFullBundle ? {} : { skillSlugs: deliverable }),
dryRun: a.dryRun,
});
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- the operator's own workspace root, where runScaffold just wrote.
if (!a.dryRun) await recordScaffoldBases(join(targetWorkspace, 'skills'), result.files);
if (a.json) {
console.log(
JSON.stringify(
{
ok: true,
harness: a.harness,
persona: useFullBundle ? 'all' : persona,
dryRun: result.dryRun,
summary: result.summary,
openclaw_skipped: laneOnly,
},
null,
2,
),
);
} else {
console.log(
`${a.dryRun ? 'scaffold --harness openclaw (dry-run)' : 'scaffold --harness openclaw'}: ` +
`${result.summary.wroteNew} wrote, ${result.summary.skippedExisting} skipped, ${result.summary.pairedSourcesWritten} paired source(s)`,
);
if (laneOnly.length > 0) {
console.log(
`skipped (plugin-lane additions, not in the openclaw bundle): ${laneOnly.join(', ')}`,
);
}
console.log('These skills are a fallback: OpenClaw agents seldom open a listed skill on their own. The primary route is the per-turn rule from `gbrain setup openclaw`.');
}
process.exit(0);
}
const dest = resolveDest(a);
assertDestNotSymlink(dest);
const { slugs, persona } = resolveSlugs(gbrainRoot, a);
const mode = a.stub ? 'stub' : 'full';
if (a.stub) await stubPreflight(gbrainRoot, slugs);
const plan = planHarnessBridge({ gbrainRoot, destDir: dest, slugs, mode });
const result = applyHarnessBridge(plan, {
harness: a.harness,
scope: a.harness === 'claude-code' ? a.scope : undefined,
persona,
gbrainVersion: VERSION,
dryRun: a.dryRun,
nowIso: new Date().toISOString(),
});
if (!result.dryRun) await recordScaffoldBases(dest, result.files.filter(file => file.slug !== null));
// Coexistence: these same skills may also load from the gbrain plugin
// snapshot (marketplace install) — duplicate names in one session.
const coexistence = {
plugin_lane_overlap: slugs,
skipped_existing: result.summary.skippedExisting,
};
if (a.json) {
console.log(
JSON.stringify(
{
ok: true,
harness: a.harness,
dest,
persona,
mode,
dryRun: result.dryRun,
summary: result.summary,
coexistence,
},
null,
2,
),
);
} else {
console.log(
`${a.dryRun ? `scaffold --harness ${a.harness} (dry-run)` : `scaffold --harness ${a.harness}`}: ` +
`${result.summary.wroteNew} wrote, ${result.summary.skippedExisting} skipped → ${dest}\n` +
`persona: ${persona ?? '(explicit picks)'} | mode: ${mode}` +
(result.summary.pairedSourcesSkipped > 0
? ` | ${result.summary.pairedSourcesSkipped} paired source(s) skipped (no src tree in a harness dir)`
: ''),
);
if (result.summary.modeConflicts.length > 0) {
console.log(
`\nmode_conflict (${result.summary.modeConflicts.length}): ${result.summary.modeConflicts.join(', ')}\n` +
` These skills are already installed in the other mode (the file marker is\n` +
` ground truth). Never silently converted — remove them first, then re-run:\n` +
` gbrain skillpack remove --harness ${a.harness}${a.dest ? ' --dest <dir>' : ''} --skill <slug>`,
);
}
// Bridge harnesses only reach here (openclaw returned above): the same
// names may also load from the marketplace plugin snapshot.
console.log(
`\nNote: these skill names may also load from the gbrain plugin snapshot if the\n` +
`marketplace plugin is installed — duplicate names coexist in one session;\n` +
`prefer one lane per machine.`,
);
if (!a.dryRun && result.summary.wroteNew > 0) {
const target = `${a.dest ? ` --dest ${a.dest}` : ''}${a.scope === 'project' ? ' --scope project' : ''}${a.workspace ? ` --workspace ${a.workspace}` : ''}`;
console.log(`\nUpdate lens: gbrain skillpack reference --harness ${a.harness}${target} | remove: gbrain skillpack remove --harness ${a.harness}${target}`);
}
}
process.exit(0);
} catch (err) {
exitTyped('scaffold --harness', err);
}
}
// ---------------------------------------------------------------------------
// reference --harness
// ---------------------------------------------------------------------------
export async function cmdReferenceHarness(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack reference --harness <h> [<slug>] [--dest PATH] [--scope user|project] [--workspace PATH] [--apply-clean-hunks] [--dry-run] [--json]\n\n' +
'Targeting resolves like scaffold: explicit dest wins, else the harness\n' +
'default for the scope (claude-code user scope unless --scope project).\n\n' +
'Diff a harness install against gbrain\'s current bundle. Stub installs\n' +
'diff against the RENDERED stub (a fresh stub reads identical). With the\n' +
'install-time hash ledger, differs splits into local_edit vs\n' +
'upstream_drift. --apply-clean-hunks lands non-conflicting hunks on\n' +
'full-mode files only (stubs are regenerated by re-running scaffold).',
);
process.exit(0);
}
const a = parseHarnessArgs(args, 'reference --harness');
if (a.harness === 'openclaw') {
console.error('Error: openclaw installs are workspace scaffolds — use `gbrain skillpack reference <name>` (no harness flag).');
process.exit(2);
}
const gbrainRoot = findGbrainOrDie();
const dest = resolveDest(a);
const positional = a.positional[0] ?? null;
try {
const state = loadBridgeState();
const entry = findBridgeEntry(state, { harness: a.harness, dest });
const slugs = positional
? [positional]
: a.skills.length > 0
? a.skills
: ownedBridgeSlugs(entry).length > 0
? ownedBridgeSlugs(entry)
: resolveSlugs(gbrainRoot, a).slugs;
if (a.applyCleanHunks) {
if ((!positional && a.skills.length !== 1) || (positional && a.skills.length > 0) || slugs.length !== 1) {
console.error('Error: --apply-clean-hunks needs exactly ONE skill (apply one at a time).');
process.exit(2);
}
const result = runHarnessReferenceApply({ gbrainRoot, destDir: dest, slugs, harness: a.harness, dryRun: a.dryRun });
if (a.json) console.log(JSON.stringify(result, null, 2));
else {
console.log(
`reference --harness --apply-clean-hunks: ${result.summary.totalHunksApplied} hunk(s) applied, ` +
`${result.summary.totalHunksConflicted} conflict(s), ${result.summary.refusedStub} stub file(s) refused, ` +
`${result.summary.refusedLocalEdit} local edit(s) kept, ` +
`${result.summary.refusedUnknown} unknown-provenance file(s) untouched`,
);
for (const f of result.files) {
if (f.status === 'identical' || f.status === 'missing') continue;
console.log(` ${f.status.padEnd(12)} ${f.relTarget}`);
for (const c of f.conflicts) console.log(` ${c}`);
}
}
process.exit(0);
}
const result = runHarnessReference({ gbrainRoot, destDir: dest, slugs, harness: a.harness });
if (a.json) console.log(JSON.stringify(result, null, 2));
else {
console.log(
`reference --harness ${a.harness} (${dest}): identical:${result.summary.identical} differs:${result.summary.differs} missing:${result.summary.missing}`,
);
for (const f of result.files) {
if (f.status === 'identical') continue;
const kind = f.differsKind ? ` [${f.differsKind}]` : '';
console.log(`\n ${f.status.padEnd(10)}${kind} ${f.relTarget}`);
if (f.unifiedDiff) console.log(f.unifiedDiff);
}
if (result.summary.differs > 0) {
console.log(
'\n local_edit → your change; keep it (gbrain is reference, not law).\n' +
' upstream_drift → gbrain moved; `gbrain skillpack reference --harness ' + a.harness + ' <slug> --apply-clean-hunks` to align.',
);
}
}
process.exit(0);
} catch (err) {
exitTyped('reference --harness', err);
}
}
// ---------------------------------------------------------------------------
// remove (harness lane only — the v0.33 workspace `uninstall` stays removed)
// ---------------------------------------------------------------------------
export async function cmdRemove(args: string[]): Promise<void> {
if (args.includes('--help') || args.includes('-h') || args.length === 0) {
console.log(
'gbrain skillpack remove --harness <h> [--dest PATH] [--scope user|project] [--workspace PATH] [--skill <slug>]... [--dry-run] [--json]\n\n' +
'Targeting resolves like scaffold: explicit dest wins, else the harness\n' +
'default for the scope.\n\n' +
'Remove files the harness bridge WROTE (the bridge-state ledger) — never\n' +
'your own files: pre-existing and locally-created files were never\n' +
'recorded as owned. Without --skill, removes every owned skill for the\n' +
'(harness, dest). Shared convention files stay (other skills use them);\n' +
'once no owned skill is left, the shared-skills migration no longer\n' +
'counts them as legacy copies.\n\n' +
'This is NOT the removed-in-v0.33 workspace uninstall: workspace scaffolds\n' +
'are user-owned outright (delete their directories yourself).',
);
process.exit(args.length === 0 ? 2 : 0);
}
const a = parseHarnessArgs(args, 'remove');
if (a.positional.length > 0) {
console.error(
`Error: unexpected argument '${a.positional[0]}' — remove takes skills via --skill (did you mean --skill ${a.positional[0]}?).`,
);
process.exit(2);
}
if (a.harness === 'openclaw') {
console.error(
'Error: openclaw installs are user-owned workspace scaffolds — remove skill\n' +
'directories yourself (the files are yours).',
);
process.exit(2);
}
const dest = resolveDest(a);
try {
const result = removeHarnessBridge({
harness: a.harness,
destDir: dest,
slugs: a.skills.length > 0 ? a.skills : null,
dryRun: a.dryRun,
nowIso: new Date().toISOString(),
});
// Silent-no-op guard: nothing owned at THIS (harness, dest), but the
// ledger knows other installs for the harness — name them instead of
// printing a success-shaped zero.
if (result.removedFiles.length === 0 && result.keptEdited.length === 0 && result.notOwned.length === 0) {
const others = loadBridgeState()
.entries.filter(e => e.harness === a.harness && e.dest !== dest)
.map(e => e.dest);
if (others.length > 0) {
console.error(
`note: no bridge install recorded at ${dest}; this harness has installs at: ${others.join(', ')} (pass --dest).`,
);
}
}
if (a.json) console.log(JSON.stringify(result, null, 2));
else {
console.log(
`${a.dryRun ? 'remove (dry-run)' : 'remove'}: ${result.removedFiles.length} owned file(s) removed, ` +
`${result.prunedDirs.length} empty dir(s) pruned` +
(result.keptEdited.length > 0
? ` — kept (you edited these; they're yours now): ${result.keptEdited.length}`
: '') +
(result.notOwned.length > 0 ? ` — not owned (untouched): ${result.notOwned.join(', ')}` : ''),
);
}
process.exit(0);
} catch (err) {
exitTyped('remove', err);
}
}
// ---------------------------------------------------------------------------
// status — installed-bridges section (called by the façade's cmdStatus)
// ---------------------------------------------------------------------------
export interface BridgesStatusEntry {
harness: string;
dest: string;
persona: string | null;
mode: string;
slugs: number;
identical: number;
differs: number;
missing: number;
/** Set when the currency lens itself failed (moved dest, deleted skills) —
* zeros next to it mean "could not judge", not "all healthy". */
lens_error?: string;
}
/**
* Render the installed-bridges section for `skillpack status`. Per-slug
* currency comes from the harness reference lens (expected content), NOT
* skills.lock hashes — lock hashes can never match stubs and cannot
* separate upstream drift from local edits.
*/
export function collectBridgesStatus(gbrainRoot: string): BridgesStatusEntry[] {
const state = loadBridgeState();
const out: BridgesStatusEntry[] = [];
for (const entry of state.entries) {
const slugs = ownedBridgeSlugs(entry);
let identical = 0;
let differs = 0;
let missing = 0;
let lensError: string | undefined;
try {
const ref = runHarnessReference({
gbrainRoot,
destDir: entry.dest,
slugs,
harness: entry.harness,
// Status consumes counts only — skip the O(N*M) diff rendering.
includeDiffs: false,
});
identical = ref.summary.identical;
differs = ref.summary.differs;
missing = ref.summary.missing;
} catch (err) {
// Lens failure (moved dest, deleted skills) — surface it; zeros alone
// would read as healthy.
lensError = (err as Error).message;
}
out.push({
harness: entry.harness,
dest: entry.dest,
persona: entry.last_persona,
mode: entry.last_mode,
slugs: slugs.length,
identical,
differs,
missing,
...(lensError ? { lens_error: lensError } : {}),
});
}
return out;
}
export function printBridgesStatus(gbrainRoot: string): void {
const entries = collectBridgesStatus(gbrainRoot);
if (entries.length === 0) return;
console.log('\nHarness bridges (gbrain skillpack scaffold with a harness):');
for (const e of entries) {
console.log(
` ${e.harness.padEnd(12)} ${e.dest}\n` +
` persona:${e.persona ?? '(picks)'} mode:${e.mode} skills:${e.slugs} — ` +
(e.lens_error
? `currency unavailable (${e.lens_error})`
: `identical:${e.identical} differs:${e.differs} missing:${e.missing}`),
);
}
}
// ---------------------------------------------------------------------------
function exitTyped(cmd: string, err: unknown): never {
if (
err instanceof BridgeError ||
err instanceof PersonaError ||
err instanceof BundleError ||
err instanceof ScaffoldError ||
err instanceof CopyError ||
err instanceof BridgeStateError
) {
console.error(`skillpack ${cmd}: ${(err as Error).message}`);
process.exit(2);
}
throw err;
}
// Re-exported so tests can drive the state path used by status.
export { defaultBridgeStatePath, loadPersonas };