Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain skillpack scaffold` — bundled-skill scaffold + third-party sources.
*
* Peeled from src/commands/skillpack.ts (module-size ratchet). Behavior is
* unchanged from the façade version. Flag-registry note: this file is scanned
* for skillpack's flag allowlist — spell foreign (non-skillpack) CLI flags
* WITHOUT leading dashes in comments and strings.
*/
import { join } from 'path';
import {
bundledSkillSlugs,
findGbrainRoot,
loadBundleManifest,
BundleError,
} from '../../core/skillpack/bundle.ts';
import { runScaffold, ScaffoldError } from '../../core/skillpack/scaffold.ts';
import { recordScaffoldBases } from '../../core/skillpack/safe-update.ts';
import {
RemoteSourceError,
classifySpec,
resolveSource,
} from '../../core/skillpack/remote-source.ts';
import {
ScaffoldThirdPartyError,
runScaffoldThirdParty,
} from '../../core/skillpack/scaffold-third-party.ts';
import { SkillpackManifestError } from '../../core/skillpack/manifest-v1.ts';
import { VERSION } from '../../version.ts';
import { findGbrainOrDie, resolveWorkspace } from './shared.ts';
import { consentGate } from '../../core/consent-cli.ts';
import { sharedTokenNotice, writeExposureNotice } from '../../core/grants/shared-exposure.ts';
import { botHarnessForWorkspace } from '../shared-exposure-local.ts';
export async function cmdScaffold(args: string[]): Promise<void> {
// Harness lane (cathedral-7): `--harness <h>` installs a persona-curated
// set into a harness's native skills dir instead of a workspace.
if (args.some(a => a === '--harness' || a.startsWith('--harness='))) {
const i = args.indexOf('--harness');
const harness = i >= 0 ? args[i + 1] : args.find(a => a.startsWith('--harness='))!.slice('--harness='.length);
if (!args.includes('--help') && !args.includes('-h')) writeExposureNotice(sharedTokenNotice({ kind: 'stdio', harness: harness ?? '' }, { harness }));
const { cmdScaffoldHarness } = await import('./harness.ts');
await cmdScaffoldHarness(args);
return;
}
if (args.includes('--help') || args.includes('-h')) {
console.log(
'gbrain skillpack scaffold <name> | <source> | --all [--workspace PATH] [--dry-run] [--trust] [--no-cache] [--json]\n\n' +
'<name> — bundled skill slug (e.g. `book-mirror`)\n' +
'<source> — third-party skillpack source. Accepted shapes:\n' +
' owner/repo (expands to https://github.com/owner/repo)\n' +
' https://...git (verbatim https URL)\n' +
' ./local/dir/ (local pack root)\n' +
' ./local/pack.tgz (local tarball)\n' +
'\nFlags:\n' +
' --workspace PATH Target workspace (default: auto-detected)\n' +
' --all Scaffold every bundled skill (gbrain only)\n' +
' --dry-run Validate + report; no writes\n' +
' --trust The user\'s approval to trust a new third-party author + pin\n' +
' (without it a non-interactive run writes nothing and exits 3)\n' +
' --no-cache Force fresh clone/extract for third-party sources\n' +
' --json Stable JSON envelope for agent consumption',
);
process.exit(0);
}
const json = args.includes('--json');
const dryRun = args.includes('--dry-run');
const all = args.includes('--all');
const trustFlag = args.includes('--trust');
const noCache = args.includes('--no-cache');
let name: 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 && !a.startsWith('--') && !name) {
name = a;
}
}
if (!all && !name) {
console.error('Error: pass a skill name, third-party source, or --all.');
process.exit(2);
}
// Disambiguate bundled-skill name vs third-party source.
//
// Routing rules (in priority order):
// 1. `--all` → bundled --all sweep
// 2. Spec contains `/` / `://` / ends in .tgz → third-party direct
// 3. Bare kebab AND matches a bundled-skill slug → bundled (v0.36 path)
// 4. Bare kebab AND NOT a bundled-skill slug → third-party via registry
const targetWorkspace = resolveWorkspace({ workspace });
const botHarness = botHarnessForWorkspace(targetWorkspace);
if (botHarness) writeExposureNotice(sharedTokenNotice({ kind: 'stdio', harness: botHarness }, { harness: botHarness }));
const isThirdPartyShape = !all && name !== null && /[\/:]|\.(tgz|tar\.gz)$/.test(name);
if (!all && name !== null && !isThirdPartyShape) {
// Check if the kebab name matches a bundled-skill slug.
const gbrainRoot = findGbrainRoot();
if (gbrainRoot) {
try {
const manifest = loadBundleManifest(gbrainRoot);
const slugs = bundledSkillSlugs(manifest);
if (!slugs.includes(name)) {
// Not a bundled slug — try the registry.
await runThirdPartyScaffold({
spec: name,
targetWorkspace,
dryRun,
trustFlag,
noCache,
json,
args,
});
return;
}
} catch {
// Fall through to the bundled path; it'll surface a clearer error.
}
}
} else if (isThirdPartyShape) {
await runThirdPartyScaffold({
spec: name!,
targetWorkspace,
dryRun,
trustFlag,
noCache,
json,
args,
});
return;
}
const gbrainRoot = findGbrainOrDie();
try {
const result = runScaffold({
gbrainRoot,
targetWorkspace,
skillSlug: all ? null : name!,
dryRun,
});
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- targetWorkspace is the local operator's own workspace root, the same root runScaffold just wrote under.
if (!dryRun) await recordScaffoldBases(join(targetWorkspace, 'skills'), result.files);
if (json) {
console.log(JSON.stringify({ ok: true, dryRun: result.dryRun, summary: result.summary, files: result.files }, null, 2));
} else {
console.log(
`${dryRun ? 'scaffold --dry-run' : 'scaffold'}: ${result.summary.wroteNew} wrote, ${result.summary.skippedExisting} skipped (already present), ${result.summary.pairedSourcesWritten} paired source(s)`,
);
// Next-action hint for the agent + the operator. Print only on
// actual writes (re-runs that just skip are noise-quieter).
if (!dryRun && result.summary.wroteNew > 0) {
// Display-only hint path; targetWorkspace is the operator's own
// --workspace flag on the local CLI plane (no untrusted input).
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal
const onboardingPath = join(targetWorkspace, 'skills', '_AGENT_README.md');
console.log(
`\nNext: your agent walks \`skills/*/SKILL.md\` frontmatter \`triggers:\` for routing.\nIf this is a fresh install, read ${onboardingPath} for the agent contract.\nWhen gbrain ships an update later, run \`gbrain skillpack reference --all\` to sweep.`,
);
}
}
process.exit(0);
} catch (err) {
if (err instanceof ScaffoldError || err instanceof BundleError) {
console.error(`skillpack scaffold: ${(err as Error).message}`);
process.exit(2);
}
throw err;
}
}
// ---------------------------------------------------------------------------
// scaffold — third-party source path (new in v0.37)
// ---------------------------------------------------------------------------
interface ThirdPartyScaffoldOptions {
spec: string;
targetWorkspace: string;
dryRun: boolean;
trustFlag: boolean;
noCache: boolean;
json: boolean;
/** Raw argv, for the consent request (`--yes`, `--trust`). */
args: readonly string[];
}
async function runThirdPartyScaffold(opts: ThirdPartyScaffoldOptions): Promise<void> {
// Step 1: resolve the source. Kebab names get a registry lookup first;
// everything else hits the direct resolveSource() path.
let resolved;
let registryTier: 'endorsed' | 'community' | 'experimental' | 'dead' | undefined;
try {
const cls = classifySpec(opts.spec);
if (cls.kind === 'kebab') {
// Registry path: load catalog, find pack, follow to URL.
const { loadRegistry, findPackWithTier } = await import('../../core/skillpack/registry-client.ts');
const loaded = await loadRegistry({});
const found = findPackWithTier(loaded, cls.normalized);
if (!found) {
console.error(
`Error: no skillpack named "${cls.normalized}" in the registry (${loaded.registry_url}).\n` +
`Run \`gbrain skillpack search ${cls.normalized}\` for matches, or pass a full source (owner/repo, https URL, ./path, ./*.tgz).`,
);
process.exit(2);
}
registryTier = found.tier;
resolved = resolveSource(found.entry.source.url, { noCache: opts.noCache });
} else {
resolved = resolveSource(opts.spec, { noCache: opts.noCache });
}
} catch (err) {
if (err instanceof RemoteSourceError) {
console.error(`skillpack scaffold: ${err.message}`);
process.exit(2);
}
throw err;
}
// Step 2: orchestrator handles manifest validation, trust prompt, copy,
// state.json update, and bootstrap display.
try {
const scaffold = (trustFlag: boolean) => runScaffoldThirdParty(
{
resolved,
targetWorkspace: opts.targetWorkspace,
trustFlag,
dryRun: opts.dryRun,
tier: registryTier,
},
VERSION,
);
let result = await scaffold(opts.trustFlag);
// A4: no human to answer the trust prompt. The user decides whether this
// author + pin is trusted: refuse with the consent payload (exit 3), or
// proceed when the caller already carries the approval (--yes). A generic
// persistent_install preapproval never trusts third-party code.
if (result.status === 'aborted_no_trust' && result.trustDecision.reason === 'non_tty_no_trust_flag') {
const m = result.manifest;
const pin = result.resolved.pinned_commit ? `commit ${result.resolved.pinned_commit.slice(0, 12)}`
: result.resolved.tarball_sha256 ? `tarball sha256:${result.resolved.tarball_sha256.slice(0, 12)}` : 'unpinned';
const auth = await consentGate({
command: 'skillpack scaffold', effects: ['persistent_install'], actor: 'agent',
what: `Install the third-party skillpack ${m.name}@${m.version} by ${m.author}`,
why: `Adds ${m.name}'s skills to this workspace (${m.description}).`,
risk: `Copies third-party skills from ${result.resolved.source} (${pin}) into ${opts.targetWorkspace}; your agent will follow them as instructions, including any scripts they reference. `
+ 'Trust is recorded for this exact author and pin; a different author or pin asks again.',
user_message: `Install the skillpack ${m.name} by ${m.author} from ${result.resolved.source} (${pin})? Its skills become instructions your agent follows.`,
argv: ['gbrain', 'skillpack', 'scaffold', opts.spec, ...opts.args.filter(a => a !== opts.spec && a !== '--yes' && a !== '--trust')],
args: opts.args,
}, { json: opts.json, env: { preapprovals: {} } });
if (!auth) return;
result = await scaffold(true);
}
if (opts.json) {
console.log(
JSON.stringify(
{
ok: result.status !== 'aborted_no_trust',
status: result.status,
pack: {
name: result.manifest.name,
version: result.manifest.version,
author: result.manifest.author,
},
source: result.resolved.source,
source_kind: result.resolved.kind,
pinned_commit: result.resolved.pinned_commit,
tarball_sha256: result.resolved.tarball_sha256,
cache_hit: result.resolved.cache_hit,
trust: { trusted: result.trustDecision.trusted, reason: result.trustDecision.reason },
copy: result.copy?.summary ?? null,
bootstrap_shown: result.bootstrap.shown,
},
null,
2,
),
);
} else {
if (result.status === 'aborted_no_trust') {
console.error(
`skillpack scaffold: aborted (trust decision: ${result.trustDecision.reason}). No files written.`,
);
process.exit(1);
}
const m = result.manifest;
const summary = result.copy?.summary;
console.log(
`${opts.dryRun ? 'scaffold (dry-run)' : 'scaffold'}: ${m.name}@${m.version} by ${m.author}` +
(summary
? ` — ${summary.wroteNew} wrote, ${summary.skippedExisting} skipped`
: ''),
);
if (result.resolved.kind !== 'local') {
console.log(
`Source: ${result.resolved.source}` +
(result.resolved.pinned_commit ? ` @ ${result.resolved.pinned_commit.slice(0, 12)}` : ''),
);
}
if (result.bootstrap.shown) {
// Bootstrap framing on stderr so stdout stays clean for the agent contract.
process.stderr.write('\n' + result.bootstrap.text + '\n');
}
if (!opts.dryRun && summary && summary.wroteNew > 0) {
console.log(
`\nNext: your agent walks skills/*/SKILL.md frontmatter triggers: for routing.\n` +
`Run \`gbrain skillpack reference ${m.name}\` later if upstream changes.`,
);
}
}
process.exit(result.status === 'aborted_no_trust' ? 1 : 0);
} catch (err) {
if (err instanceof ScaffoldThirdPartyError || err instanceof SkillpackManifestError) {
console.error(`skillpack scaffold: ${(err as Error).message}`);
process.exit(2);
}
throw err;
}
}