Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* gbrain frontmatter install-hook — Install a pre-commit hook in a brain
* source's git repo that runs `gbrain frontmatter validate` against staged
* .md/.mdx files. Skips sources outside any git repo with a one-line note.
*
* Usage:
* gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
*
* --source <id> Limit to one registered source. Default: all sources.
* --force Overwrite an existing pre-commit hook (writes <hook>.bak).
* --uninstall Remove the hook; restore <hook>.bak if present.
*
* Hook contract:
* - Located at <git root>/.githooks/pre-commit. The root is discovered the
* way `gbrain sync` does (#4600): a source registered as a SUBDIRECTORY of
* a host repo (the `<workspace>/brain` layout bootstrap creates) gets ONE
* hook at the host root, pathspec-scoped to that subdirectory; several
* nested sources union their scopes; a source registered at the root
* renders the unscoped whole-repo script. We `git config core.hooksPath
* .githooks` only when `hooksPathBlocker` finds nothing: core.hooksPath
* unset (one already resolving to `.githooks` is left alone; one pointing
* elsewhere — global/corporate templates — is theirs to keep and reported
* as unwired, since git never reads `.githooks/` then), no foreign
* executable under `.githooks/` (wiring would start running it) and no
* active hook in the repo's own hooks dir (`.git/hooks` — wiring makes git
* ignore it for EVERY hook type). Either way the hook is written and the
* reason + manual wiring step printed.
* - When the gbrain binary is missing, the hook prints a one-line warning
* and exits 0 (don't break commits if a developer uninstalls gbrain).
* - Bypass via `git commit --no-verify`.
*/
import { existsSync, readFileSync, writeFileSync, mkdirSync, chmodSync, rmSync, copyFileSync, realpathSync, readdirSync, statSync, lstatSync } from 'fs';
import { isAbsolute, join, relative, resolve } from 'path';
import { execFileSync } from '../core/spawn.ts';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig, toEngineConfig } from '../core/config.ts';
import { createEngine } from '../core/engine-factory.ts';
import { discoverGitRoot } from '../core/sync-git.ts';
import { gitChildEnv } from '../core/git-env.ts';
const HOOK_BANNER = '# gbrain frontmatter pre-commit hook (v0.22.4+)';
/** One line per guarded subdirectory (root-relative, trailing slash). No lines = whole repo. */
const SCOPE_MARKER = '# gbrain-scope: ';
const VERSION_MARKER = '# gbrain-hook-version: ';
/**
* Bump when the generated script changes behavior. 2: one
* `gbrain frontmatter validate --staged` process checks the staged blobs.
* A gbrain hook without the marker is version 1 (validated working-tree bytes).
*/
export const FRONTMATTER_HOOK_VERSION = 2;
const shellQuote = (s: string): string => `'${s.replace(/'/g, "'\\''")}'`;
/**
* A scope is rendered into a `#` comment line and a `'…'` pathspec: a line
* terminator inside it would end the comment early and run the rest of the
* path as hook code. Refused at the seam (path → scope) and again at render.
*/
function assertNoLineTerminator(scope: string): void {
if (/[\n\r\0]/.test(scope)) {
throw new Error(`source path contains a line terminator; refusing to install hook: ${JSON.stringify(scope)}`);
}
}
/**
* Run git in `root`; trimmed stdout, throws on non-zero. `env: process.env`
* keeps the child on the LIVE environment (Bun's default is a startup
* snapshot, Node's is live) so a caller's `GIT_CONFIG_*` overrides are honored.
*/
const git = (root: string, args: string[]): string =>
execFileSync('git', ['-C', root, ...args], { encoding: 'utf8', env: process.env }).trim();
/**
* Render the hook script. Empty `scopes` = the whole repo; otherwise
* `git diff --cached` is limited to the listed pathspecs. Git runs hooks from
* the worktree root, so the root-relative paths it lists resolve as-is for
* `gbrain frontmatter validate --staged`, which checks the staged blobs (not
* the working-tree bytes) of all of them in one process.
*/
function renderHookScript(scopes: string[]): string {
scopes.forEach(assertNoLineTerminator);
const marker = scopes.map((s) => `${SCOPE_MARKER}${s}\n`).join('');
const pathspec = scopes.length > 0 ? ` -- ${scopes.map(shellQuote).join(' ')}` : '';
return `#!/bin/sh
${HOOK_BANNER}
${VERSION_MARKER}${FRONTMATTER_HOOK_VERSION}
${marker}# Validates the staged YAML frontmatter of .md / .mdx files. Bypass with
# 'git commit --no-verify'. Uninstall with 'gbrain frontmatter install-hook --uninstall'.
set -e
if ! command -v gbrain >/dev/null 2>&1; then
echo "gbrain not on PATH; skipping frontmatter pre-commit (install gbrain to re-enable)." >&2
exit 0
fi
# One path per line: -z disables git's quoting (a non-ASCII name would print
# as "caf\\303\\251.md"), tr turns the NUL terminators into newlines, and the
# read loop keeps spaces intact (a newline INSIDE a name is the one unsupported
# shape). The heredoc keeps the loop in this shell so the argument list survives it.
staged=$(git diff --cached --name-only -z --diff-filter=ACM${pathspec} | tr '\\0' '\\n' | grep -E '\\.mdx?$' || true)
[ -z "$staged" ] && exit 0
set --
while IFS= read -r f; do
if [ -n "$f" ]; then set -- "$@" "$f"; fi
done <<EOF
$staged
EOF
[ $# -eq 0 ] && exit 0
if ! report=$(gbrain frontmatter validate --staged -- "$@" 2>&1); then
printf '%s\\n' "$report" >&2
echo "" >&2
echo "Frontmatter validation failed for the staged content above. Fix each file ('gbrain frontmatter validate <file> --fix'; on a managed brain 'gbrain repair frontmatter --source <id>'), then restage it with 'git add <file>'. Bypass once with 'git commit --no-verify'." >&2
exit 1
fi
`;
}
/**
* The generated-script version of an installed hook: null when the content
* is not a gbrain frontmatter hook, 1 for gbrain hooks written before the marker.
*/
export function frontmatterHookVersion(hook: string): number | null {
if (!hook.includes(HOOK_BANNER)) return null;
const line = hook.split('\n').find((l) => l.startsWith(VERSION_MARKER));
const version = line ? Number(line.slice(VERSION_MARKER.length).trim()) : 1;
return Number.isInteger(version) && version > 0 ? version : 1;
}
export interface InstalledFrontmatterHook {
hookPath: string;
version: number;
current: boolean;
/** Present when outdated: refreshes the script (an existing gbrain hook is replaced without a .bak). */
fix?: string[];
}
/**
* The gbrain pre-commit hook guarding `localPath`, read-only: null when the
* path is outside git, the hook path is a symlink, no gbrain hook is
* installed at its root, or the clone has hooks off on purpose (git never runs
* the file, and install-hook skips it). Doctor and post-upgrade use `current` to recommend
* `gbrain frontmatter install-hook --force`.
*/
export function inspectFrontmatterHook(localPath: string, sourceId?: string): InstalledFrontmatterHook | null {
let root: string, hookPath: string;
try {
root = resolveHookTarget(localPath).root;
hookPath = hookPaths(root).hookPath;
} catch {
return null;
}
if (!existsSync(hookPath) || hooksOffInClone(root)) return null;
const version = frontmatterHookVersion(readFileSync(hookPath, 'utf8'));
if (version === null) return null;
const current = version >= FRONTMATTER_HOOK_VERSION;
return { hookPath, version, current,
...(current ? {} : { fix: ['gbrain', 'frontmatter', 'install-hook', ...(sourceId ? ['--source', sourceId] : []), '--force'] }) };
}
function parseScopes(hook: string): string[] {
return hook
.split('\n')
.filter((l) => l.startsWith(SCOPE_MARKER))
.map((l) => l.slice(SCOPE_MARKER.length));
}
interface SourceRow {
id: string;
local_path: string | null;
}
export async function runFrontmatterInstallHook(args: string[]): Promise<void> {
let force = false;
let uninstall = false;
let sourceId: string | undefined;
let help = false;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (a === '--help' || a === '-h') help = true;
else if (a === '--force') force = true;
else if (a === '--uninstall') uninstall = true;
else if (a === '--source') sourceId = args[++i];
else if (a.startsWith('--source=')) sourceId = a.slice('--source='.length);
}
if (help) {
printHelp();
return;
}
const config = loadConfig();
if (!config) {
throw new Error('No brain configured. Run: gbrain init');
}
const engineConfig = toEngineConfig(config);
const engine = await createEngine(engineConfig);
await engine.connect(engineConfig);
try {
const sources = await listSources(engine, sourceId);
if (sources.length === 0) {
console.log(sourceId
? `Source "${sourceId}" not found.`
: 'No registered sources. Run `gbrain sources list` to inspect.');
return;
}
let installed = 0;
let skipped = 0;
for (const src of sources) {
if (!src.local_path || !existsSync(src.local_path)) {
console.log(`[${src.id}] skipped — local_path missing on disk`);
skipped++;
continue;
}
let target: HookTarget;
try {
target = resolveHookTarget(src.local_path);
} catch (err) {
// Outside any git repo, or a path the hook script cannot carry safely.
console.log(`[${src.id}] ${src.local_path} — skipped, ${err instanceof Error ? err.message : String(err)}`);
skipped++;
continue;
}
if (uninstall) {
let removed: boolean;
try {
removed = uninstallHook(src.local_path);
} catch (err) {
// Same refusal class as install (symlinked .githooks/ or hook): this
// source is reported and skipped, the remaining sources still run.
console.log(`[${src.id}] skipped — ${err instanceof Error ? err.message : String(err)}`);
skipped++;
continue;
}
if (removed) {
console.log(`[${src.id}] hook removed`);
installed++;
} else {
console.log(`[${src.id}] no gbrain pre-commit hook found; nothing to uninstall`);
}
continue;
}
let result: InstallResult;
try {
result = installHook(src.local_path, force);
} catch (err) {
// e.g. a symlinked .githooks/ — refused, the other sources still run.
console.log(`[${src.id}] skipped — ${err instanceof Error ? err.message : String(err)}`);
skipped++;
continue;
}
if (result === 'installed') {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- target.root is the git root discovered with `git rev-parse` for a registered source path; the tail is a fixed literal
const where = join(target.root, '.githooks', 'pre-commit');
console.log(`[${src.id}] hook installed at ${where}${target.scope ? ` (scoped to ${target.scope})` : ''}`);
installed++;
} else if (result === 'installed_unwired') {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- target.root is the discovered git root of a registered source; fixed literal tail
const where = join(target.root, '.githooks', 'pre-commit');
console.log(`[${src.id}] hook written at ${where}; core.hooksPath left unset — ${hooksPathBlocker(target.root)}`);
installed++;
} else if (result === 'skipped_hooks_off') {
console.log(`[${src.id}] skipped — ${hooksPathBlocker(target.root)}`);
skipped++;
} else if (result === 'skipped_existing') {
console.log(`[${src.id}] existing pre-commit hook found; pass --force to overwrite (.bak created)`);
skipped++;
} else {
console.log(`[${src.id}] hook already up to date`);
}
}
console.log(`\nDone. ${installed} ${uninstall ? 'removed' : 'installed/updated'}, ${skipped} skipped.`);
} finally {
await engine.disconnect();
}
}
function printHelp() {
console.log(`gbrain frontmatter install-hook — install pre-commit hook in source git repos
Usage:
gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
The hook runs \`gbrain frontmatter validate\` against staged .md/.mdx files,
blocking commits with malformed frontmatter. Bypass with 'git commit --no-verify'.
A source registered as a subdirectory of a host repo gets the hook at the host
root, scoped to that subdirectory.
Options:
--source <id> Limit to one registered source. Default: all sources.
--force Overwrite an existing pre-commit hook (writes <hook>.bak).
--uninstall Remove the hook; restore <hook>.bak if present.
`);
}
async function listSources(engine: BrainEngine, sourceId?: string): Promise<SourceRow[]> {
if (sourceId) {
return engine.executeRaw<SourceRow>(`SELECT id, local_path FROM sources WHERE id = $1`, [sourceId]);
}
// #3880: all-source hook installation skips archived sources (v34 legacy
// fallback, house style per pickSoleNonDefaultSource). Explicit --source
// targeting above stays deliberate.
try {
return await engine.executeRaw<SourceRow>(
`SELECT id, local_path FROM sources WHERE local_path IS NOT NULL AND archived IS NOT TRUE ORDER BY id`,
);
} catch {
return engine.executeRaw<SourceRow>(`SELECT id, local_path FROM sources WHERE local_path IS NOT NULL ORDER BY id`);
}
}
interface HookTarget {
/** Realpath of the enclosing git worktree root. */
root: string;
/** Root-relative subdirectory the hook guards, trailing slash ('' when local_path IS the root). */
scope: string;
}
/**
* Discover the git root enclosing `localPath` (the same helper `gbrain sync`
* uses, so both commands accept the same shapes) and the root-relative scope.
* Both sides are realpath'd: `git rev-parse --show-toplevel` returns the
* resolved path, and an unresolved /tmp on macOS (/private/tmp) would
* otherwise yield a `..` scope. Throws when `localPath` is outside any repo.
*/
function resolveHookTarget(localPath: string): HookTarget {
const root = realpathSync(discoverGitRoot(localPath));
const rel = relative(root, realpathSync(localPath));
if (rel === '..' || rel.startsWith('../') || isAbsolute(rel)) {
throw new Error(`Not inside a git repository: ${localPath} resolves outside its git root ${root}`);
}
assertNoLineTerminator(rel);
return { root, scope: rel ? `${rel}/` : '' };
}
type InstallResult = 'installed' | 'installed_unwired' | 'skipped_existing' | 'skipped_hooks_off' | 'unchanged';
/** The core.hooksPath a remote-added URL clone carries (git-remote.ts LFS_OFF_CLONE_CONFIG): hooks off on purpose. */
const HOOKS_OFF = '/dev/null';
/**
* `.githooks/` and its `pre-commit` under `root`. Refuses a symlink at either
* level: a committed link in a host repo would redirect our write/chmod/rm to
* wherever it points (lstat, so a dangling link is refused too).
*/
function hookPaths(root: string): { hooksDir: string; hookPath: string } {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- root is the discovered git root of a registered source; fixed literal tail
const hooksDir = join(root, '.githooks');
const hookPath = join(hooksDir, 'pre-commit');
for (const p of [hooksDir, hookPath]) {
let link = false;
try { link = lstatSync(p).isSymbolicLink(); } catch { /* absent — fine */ }
if (link) throw new Error(`Refusing to write through a symlink: ${p}`);
}
return { hooksDir, hookPath };
}
/**
* Hooks git would run from the repo's own hooks dir today: executable,
* non-`*.sample` files (git skips both non-executable files and samples).
* The dir is `<git common dir>/hooks` (worktree-safe — `.git` is a FILE in
* linked worktrees, and hooks live in the shared common dir). NOT
* `rev-parse --git-path hooks`: that honors core.hooksPath, so under a global
* hooksPath it would list the FOREIGN dir instead of the one wiring sidelines.
*/
export function activeGitHooks(root: string): string[] {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- root is the discovered git root; fixed literal tail
let dir = join(root, '.git', 'hooks');
try {
const p = git(root, ['rev-parse', '--git-common-dir']);
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- p is `git rev-parse --git-path hooks` output for that same root (the operator's own repo layout), not caller input
if (p) dir = join(isAbsolute(p) ? p : join(root, p), 'hooks');
} catch { /* classic layout fallback */ }
return executableHooks(dir);
}
/** Executable, non-`*.sample` files in `dir` — what git runs from a hooks dir. */
function executableHooks(dir: string): string[] {
if (!existsSync(dir)) return [];
return readdirSync(dir).filter((f) => {
if (f.endsWith('.sample')) return false;
try {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- dir is the resolved hooks directory above and f is a directory entry read from it
const st = statSync(join(dir, f));
return st.isFile() && (st.mode & 0o111) !== 0;
} catch { return false; }
}).sort();
}
/**
* Where `core.hooksPath` points today (any scope — a global/corporate value
* counts, git reads it), resolved against the worktree root the way git does a
* relative value, `~` expanded via `--type=path`; '' when unset.
*/
function currentHooksPath(root: string): string {
try {
const p = git(root, ['config', '--type=path', '--get', 'core.hooksPath']);
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- p is the repo's own core.hooksPath config value, resolved against its git root to compare with `.githooks`
return p ? resolve(root, p) : '';
} catch {
return ''; // git config exits non-zero when the key is unset — the normal case.
}
}
/**
* The clone's own config turns hooks off (LFS_OFF_CLONE_CONFIG); a global or system value does not count. Read with
* the repository-locating and config variables scrubbed, so an inherited GIT_DIR, GIT_WORK_TREE or GIT_CONFIG* cannot
* point the read at another repository or config file.
*/
function hooksOffInClone(root: string): boolean {
const env = gitChildEnv();
delete env.GIT_CONFIG_GLOBAL; delete env.GIT_CONFIG_SYSTEM; delete env.GIT_CONFIG_NOSYSTEM;
try {
return execFileSync('git', ['-C', root, 'config', '--local', '--get', 'core.hooksPath'], { encoding: 'utf8', env }).trim() === HOOKS_OFF;
} catch {
return false;
}
}
const samePath = (a: string, b: string): boolean => {
try { return realpathSync(a) === realpathSync(b); } catch { return a === b; }
};
/**
* Why `.githooks` is not wired as `core.hooksPath` (an operator-facing sentence
* with the manual step), or null when it already is / safely can be. A
* hooksPath already pointing ELSEWHERE is theirs to keep — git never reads
* `.githooks/` then, so "installed" would lie. Wiring makes git run EVERY
* executable script in `.githooks/` — third-party clones commit hooks there as
* a convention — and ignore `.git/hooks/*` for every hook type, so a foreign
* `.githooks/<hook>` or a live `.git/hooks/<hook>` both block it too.
*/
export function hooksPathBlocker(root: string): string | null {
if (hooksOffInClone(root)) return `hooks are off in this clone's own config (core.hooksPath=${HOOKS_OFF}), and gbrain leaves them off`;
const current = currentHooksPath(root);
if (current) {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- fixed literal tail under the discovered git root
if (samePath(current, join(root, '.githooks'))) return null;
return `core.hooksPath already points at ${current} (git reads hooks only from there); copy .githooks/pre-commit into it, or run: git -C ${root} config core.hooksPath .githooks`;
}
const wire = `then run: git -C ${root} config core.hooksPath .githooks`;
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- fixed literal tail under the discovered git root
const foreign = executableHooks(join(root, '.githooks')).filter((f) => f !== 'pre-commit');
if (foreign.length > 0) return `.githooks/ holds other hook scripts git would start running (${foreign.join(', ')}); review them, ${wire}`;
const live = activeGitHooks(root);
if (live.length > 0) return `active hooks in .git/hooks (${live.join(', ')}) would stop running; move them into .githooks/, ${wire}`;
return null;
}
export function installHook(localPath: string, force: boolean): InstallResult {
const { root, scope } = resolveHookTarget(localPath);
if (hooksOffInClone(root)) return 'skipped_hooks_off';
const { hooksDir, hookPath } = hookPaths(root);
mkdirSync(hooksDir, { recursive: true });
let next = renderHookScript(scope ? [scope] : []);
let changed = true;
if (existsSync(hookPath)) {
const existing = readFileSync(hookPath, 'utf8');
if (existing.includes(HOOK_BANNER)) {
// Already a gbrain hook — refresh it, keeping every scope it guards.
// One hook per root: a nested source joins the pathspec union; a
// whole-repo hook (root source, or no marker) already covers everything.
const prior = parseScopes(existing);
const wholeRepo = !scope || prior.length === 0;
next = renderHookScript(wholeRepo ? [] : [...new Set([...prior, scope])].sort());
changed = next !== existing;
} else if (!force) {
return 'skipped_existing';
} else {
copyFileSync(hookPath, hookPath + '.bak');
}
}
writeFileSync(hookPath, next);
chmodSync(hookPath, 0o755);
// Every branch that leaves a hook on disk reaches the wiring step: the hook
// FILE travels with the repo, core.hooksPath is per-clone config, so a fresh
// clone of a repo that committed the hook has the script but git never runs
// it. A blocker (hooksPath set elsewhere — theirs to keep — or hooks that
// wiring would activate/sideline) leaves it unset; the CLI prints the reason.
if (hooksPathBlocker(root)) return 'installed_unwired';
if (currentHooksPath(root)) return changed ? 'installed' : 'unchanged'; // already resolves to .githooks
try {
git(root, ['config', 'core.hooksPath', '.githooks']);
} catch {
// Best-effort. Hook still exists; user can configure manually.
}
return 'installed';
}
export function uninstallHook(localPath: string): boolean {
const { root, scope } = resolveHookTarget(localPath);
const { hookPath } = hookPaths(root);
if (!existsSync(hookPath)) return false;
const content = readFileSync(hookPath, 'utf8');
if (!content.includes(HOOK_BANNER)) return false;
if (scope) {
// Nested source: only its own pathspec is ours to drop — a whole-repo hook
// (root-registered source) or other nested sources' scopes stay.
const prior = parseScopes(content);
if (!prior.includes(scope)) return false;
const remaining = prior.filter((s) => s !== scope);
if (remaining.length > 0) {
writeFileSync(hookPath, renderHookScript(remaining));
chmodSync(hookPath, 0o755);
return true;
}
}
rmSync(hookPath);
if (existsSync(hookPath + '.bak')) {
copyFileSync(hookPath + '.bak', hookPath);
rmSync(hookPath + '.bak');
}
return true;
}