Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
import { assertManagedFilesystemWrite, managedFilesystemRootFor } from '../core/persistence/filesystem-guard.ts';
/**
* gbrain frontmatter — Frontmatter validation, audit, and auto-repair.
*
* Subcommands:
* gbrain frontmatter validate <path>... [--json] [--importable] [--fix [--include-ambiguous]] [--dry-run]
* gbrain frontmatter validate --stdin|- [--path <source-relative path>] [--importable] [--json]
* gbrain frontmatter validate --staged [<path>...] [--importable] [--json]
* Validate one file, a directory, piped content, or staged git blobs.
* Strict producer rule by default (any error fails); --importable is the
* ingestion hold view. --fix writes centralized backups under
* ~/.gbrain/backups/frontmatter/... then rewrites in place and
* re-validates. --dry-run previews without writing.
*
* gbrain frontmatter audit [--source <id>] [--json]
* Read-only scan across all registered sources (or one with --source).
* Returns AuditReport-shaped JSON with --json.
*
* The audit subcommand is intentionally read-only; --fix only exists on
* validate. Pass an explicit path to validate a non-source-registered tree.
*/
import { readFileSync, writeFileSync, existsSync, lstatSync, readdirSync } from 'fs';
import { execFileSync } from '../core/spawn.ts';
import { setCliExitVerdict } from '../core/cli-force-exit.ts';
import { join, relative, resolve, basename, dirname, isAbsolute, posix } from 'path';
import type { BrainEngine } from '../core/engine.ts';
import { loadConfig, toEngineConfig } from '../core/config.ts';
import { createEngine } from '../core/engine-factory.ts';
import { parseMarkdown, type ParseValidationCode, type ParseWarningCode } from '../core/markdown.ts';
import { MAX_FILE_SIZE, screenImportContent, type ContentRefusal } from '../core/import-screen.ts';
import { readStdinBounded } from '../core/interaction.ts';
import { OperationError, opError } from '../core/ops/contract.ts';
import { shellQuote } from '../core/shell-quote.ts';
import {
autoFixFrontmatter,
repairRecoverableFrontmatter,
createFrontmatterBackup,
frontmatterScannableUnder,
makeFrontmatterBackupRunId,
scanBrainSources,
type AuditReport,
type AuditFix,
} from '../core/brain-writer.ts';
import { collectGitVisibleFiles } from '../core/git-visible-files.ts';
import { GIT_PATHSPEC_ENV_VARS, literalPathspecs } from '../core/git-env.ts';
import { isMarkdownFilePath, pruneDir, slugifyPath } from '../core/sync.ts';
import { isPathContained, relativeEscapesRoot } from '../core/path-confine.ts';
/** Test seams: the stream `validate --stdin` reads, and the directory `--staged` runs git in. */
export interface FrontmatterIo {
stdin?: NodeJS.ReadableStream;
cwd?: string;
}
export async function runFrontmatter(args: string[], io: FrontmatterIo = {}): Promise<void> {
const sub = args[0];
if (!sub || sub === '--help' || sub === '-h') {
printHelp();
return;
}
const rest = args.slice(1);
if (sub === 'validate') {
await runValidate(rest, io);
return;
}
if (sub === 'audit') {
const engine = await connectEngineForAudit();
try {
await runAudit(engine, rest);
} finally {
await engine.disconnect();
}
return;
}
if (sub === 'generate') {
await runGenerate(rest);
return;
}
if (sub === 'install-hook') {
const { runFrontmatterInstallHook } = await import('./frontmatter-install-hook.ts');
await runFrontmatterInstallHook(rest);
return;
}
console.error(`Unknown frontmatter subcommand: ${sub}\n`);
printHelp();
setCliExitVerdict(1);
}
async function connectEngineForAudit(): Promise<BrainEngine> {
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);
return engine;
}
function printHelp() {
console.log(`gbrain frontmatter — frontmatter validation, audit, auto-repair, and generation
Usage:
gbrain frontmatter validate <path>... [--json] [--importable] [--fix [--include-ambiguous]] [--dry-run]
gbrain frontmatter validate --stdin [--path <source-relative path>] [--importable] [--json]
gbrain frontmatter validate --staged [<path>...] [--importable] [--json]
gbrain frontmatter generate <path> [--fix] [--dry-run] [--json] [--include-catch-all]
gbrain frontmatter audit [--source <id>] [--json]
gbrain frontmatter install-hook [--source <id>] [--force] [--uninstall]
validate
Validate one .md file or recursively a directory. Each file is parsed via
parseMarkdown(..., {validate:true}); errors are reported by code:
MISSING_OPEN, MISSING_CLOSE, YAML_PARSE, SLUG_MISMATCH,
NULL_BYTES, NESTED_QUOTES, EMPTY_FRONTMATTER
Producer rule (default): exits 1 on any error, including YAML_PARSE that
gbrain could still import by quoting a value. Use it before committing
generated files.
--importable Ingestion view instead: exit 1 only for what import/sync
would hold (invalid_frontmatter, frontmatter_slug_conflict,
file_too_large). Recovered and #-comment values are reported.
--stdin, - Validate content piped on stdin (nothing is written).
--path <p> With --stdin: the source-relative path the content would
live at, so the declared slug is checked. Without it the
slug check is skipped (and says so).
--staged Validate the staged (git index) version of each staged
.md/.mdx file, or of the named paths, in one process. This
is what the pre-commit hook runs.
--fix Auto-repair: NULL_BYTES, MISSING_CLOSE, NESTED_QUOTES,
SLUG_MISMATCH, and YAML gbrain reads by quoting (only the
recovered lines change; line endings and BOM kept). Writes a
backup under ~/.gbrain/backups/frontmatter/... first, then
re-validates: exit 1 when errors remain. In a git repo,
restage the fixed files afterwards (git add). On a managed
brain use gbrain repair frontmatter --source <id> instead.
--include-ambiguous
With --fix: also apply interpretations (fold unquoted
continuation lines into the value, keep the later of a
duplicated key, quote an unclosed [ or {, quote a #-leading
title). Preview them with --dry-run first.
--dry-run Preview --fix without writing.
--json Emit a JSON envelope on stdout.
generate
Synthesize frontmatter for files that have none (MISSING_OPEN). Uses
directory-aware rules to infer type, title, date, source, and tags from
the filesystem path and file content. Zero LLM calls, fully deterministic.
Without --fix: dry-run preview showing what would be generated.
With --fix: writes frontmatter to files with centralized safety backups.
Unknown/catch-all files are skipped by default so GBrain does not stamp
meaningless "type: note" metadata onto arbitrary workspace documents. Pass
--include-catch-all to opt into the legacy catch-all note behavior.
Rules are defined in src/core/frontmatter-inference.ts DIRECTORY_RULES.
Add new directory conventions by adding rules to the table.
Examples:
gbrain frontmatter generate /path/to/brain # preview all
gbrain frontmatter generate /path/to/brain --fix # write all
gbrain frontmatter generate /path/to/brain/people/ --fix # just people/
--fix Write generated frontmatter to files with centralized backups.
--dry-run Preview without writing (default when --fix is omitted).
--json Emit JSON output.
--include-catch-all
Also write the default catch-all rule ("type: note") for paths
that do not match a more specific directory rule.
audit
Read-only scan across all registered sources (or one with --source <id>).
Reports per-source counts grouped by error code. Use this in CI or doctor
pipelines. Exits 0 even when issues are found — the count is the signal.
--source <id> Limit scan to one registered source.
--json Emit AuditReport-shaped JSON on stdout.
`);
}
// ---------------------------------------------------------------------------
// validate
// ---------------------------------------------------------------------------
interface ValidateFlags {
json: boolean;
fix: boolean;
dryRun: boolean;
importable: boolean;
includeAmbiguous: boolean;
stdin: boolean;
staged: boolean;
/** --stdin only: the source-relative path the content would live at (enables the slug check). */
path?: string;
}
interface ValidationIssue {
code: ParseValidationCode;
message: string;
line?: number;
/** YAML_PARSE only: ingestion reads it by quoting; producer checks still fail on it. */
recoverable?: boolean;
}
interface FileValidation {
path: string;
errors: ValidationIssue[];
/** Local only: FRONTMATTER_RECOVERED carries the original line and its quoted replacement. */
warnings?: Array<{ code: ParseWarningCode; message: string; key: string; line: number; original?: string; replacement?: string }>;
/** --importable: the hold ingestion would record; null when the file imports. */
hold?: ContentRefusal | null;
/** The strict check fails only on YAML gbrain reads by quoting. */
importable_but_not_canonical?: boolean;
fixesApplied?: AuditFix[];
backupPath?: string;
/** --fix: what still fails once the fixes are applied (re-validated). */
remaining_errors?: ValidationIssue[];
remaining_hold?: ContentRefusal | null;
/** --staged: whether the working-tree copy passes the same check (false when absent or failing). */
working_copy_ok?: boolean;
/** Why the file could not be checked at all. */
note?: string;
failed: boolean;
}
interface ContentCheck {
errors: ValidationIssue[];
warnings: NonNullable<FileValidation['warnings']>;
hold: ContentRefusal | null;
failed: boolean;
canonicalOnly: boolean;
}
/**
* Producer rule by default: any error fails, including YAML_PARSE ingestion
* could recover. `importable` switches to the ingestion view: only what
* `screenImportContent` refuses (the hold codes) fails. `slugPath` is the
* path the slug derives from; without it the slug check is skipped.
*/
function checkContent(content: string, slugPath: string | undefined, importable: boolean): ContentCheck {
const expectedSlug = slugPath ? slugifyPath(slugPath) : undefined;
const parsed = parseMarkdown(content, slugPath, { validate: true, ...(expectedSlug ? { expectedSlug } : {}) });
const errors = (parsed.errors ?? []).map(e => ({ code: e.code, message: e.message, line: e.line, ...(e.recoverable ? { recoverable: true } : {}) }));
const warnings = (parsed.warnings ?? []).map(w => ({ code: w.code, message: w.message, key: w.key, line: w.line,
...(w.original !== undefined ? { original: w.original } : {}), ...(w.replacement !== undefined ? { replacement: w.replacement } : {}) }));
const screen = importable ? screenImportContent({ content, path: slugPath ?? 'stdin.md', expectedSlug, holdNoncanonicalPrivate: true }) : null;
const hold = screen?.status === 'refused' ? screen.refusal : null;
return {
errors, warnings, hold,
failed: importable ? hold !== null : errors.length > 0,
canonicalOnly: !importable && errors.length > 0 && errors.every(e => e.code === 'YAML_PARSE' && e.recoverable),
};
}
/**
* Walk up from `start` (file or dir) to the brain root — the nearest ancestor
* containing a `.git` marker — so slug derivation is brain-root-relative,
* matching how sync/extract compute slugs. Falls back to the start's own
* directory when no marker is found. Fixes #565: for a single-file target,
* `relative(resolve(target), file)` was empty (target === file) and fell back
* to the ABSOLUTE path, yielding bogus "root/brain/..." slugs and false
* SLUG_MISMATCH — which the install-hook pre-commit hook hits on every commit.
*/
function findBrainRoot(start: string): string {
const startDir = lstatSync(start).isDirectory() ? start : dirname(start);
let candidate = startDir;
for (let i = 0; i < 40; i++) {
if (existsSync(join(candidate, '.git'))) return candidate;
const parent = resolve(candidate, '..');
if (parent === candidate) break;
candidate = parent;
}
return startDir;
}
/**
* The staged blob of each path (`git show :<path>` for all of them in one
* `ls-files` and one `cat-file --batch`), root-relative. No paths: every
* added, copied or modified staged Markdown file. A path with no index entry
* comes back with `content: null`.
*/
function readStagedBlobs(paths: string[], cwd = process.cwd()): { root: string; files: Array<{ rel: string; content: string | null }> } {
const env = { ...process.env };
for (const name of GIT_PATHSPEC_ENV_VARS) delete env[name];
const git = (args: string[], input?: string): Buffer =>
execFileSync('git', args, { cwd, input, maxBuffer: 1 << 30, env, stdio: ['pipe', 'pipe', 'pipe'] });
const root = git(['rev-parse', '--show-toplevel']).toString('utf8').trim();
const listed = paths.length > 0
? git(['ls-files', '--stage', '--full-name', '-z', '--', ...literalPathspecs(paths)])
: (() => {
const names = git(['-C', root, 'diff', '--cached', '--name-only', '-z', '--diff-filter=ACM']).toString('utf8').split('\0').filter(isMarkdownFilePath);
return names.length > 0 ? git(['-C', root, 'ls-files', '--stage', '-z', '--', ...literalPathspecs(names)]) : Buffer.alloc(0);
})();
const entries = listed.toString('utf8').split('\0').filter(Boolean)
.map(record => /^\d+ ([0-9a-f]+) (\d)\t(.*)$/s.exec(record))
.filter((m): m is RegExpExecArray => m !== null && m[2] === '0' && isMarkdownFilePath(m[3]!))
.map(m => ({ oid: m[1]!, rel: m[3]! }));
const files: Array<{ rel: string; content: string | null }> = [];
if (entries.length > 0) {
const out = git(['-C', root, 'cat-file', '--batch'], entries.map(e => e.oid).join('\n') + '\n');
let pos = 0;
for (const entry of entries) {
const eol = out.indexOf(10, pos);
const header = out.subarray(pos, eol).toString('utf8').split(' ');
if (header[1] !== 'blob') { files.push({ rel: entry.rel, content: null }); pos = eol + 1; continue; }
const size = Number(header[2]);
files.push({ rel: entry.rel, content: out.subarray(eol + 1, eol + 1 + size).toString('utf8') });
pos = eol + 1 + size + 1;
}
}
if (paths.length > 0) {
const prefix = git(['rev-parse', '--show-prefix']).toString('utf8').trim();
for (const p of paths) {
const full = isAbsolute(p) ? relative(root, p) : posix.normalize(prefix + p);
if (!files.some(f => f.rel === full || f.rel.startsWith(full.replace(/\/$/, '') + '/'))) files.push({ rel: full, content: null });
}
}
return { root, files };
}
/** `validate --fix` on a managed brain: name the coordinated repair instead of a bare coordinator error. */
function managedFixRefusal(file: string, error: OperationError): OperationError {
const sourceId = managedFilesystemRootFor(file)?.sourceId;
return opError('writer_coordinator_required',
`${file} is in a managed brain${sourceId ? ` (source ${sourceId})` : ''}, so frontmatter validate --fix cannot rewrite it in place.`,
`Preview the repair with gbrain repair frontmatter${sourceId ? ` --source ${sourceId}` : ''}; it writes through the persistence coordinator, and only after the preview hash is approved.`,
{
why: 'Files in a managed canonical worktree change only through the persistence coordinator, so the page and its file stay in step.',
...(error.detail !== undefined ? { detail: error.detail } : {}),
fix: {
argv: ['gbrain', 'repair', 'frontmatter', ...(sourceId ? ['--source', sourceId] : [])],
consent: [], actor: 'agent', requires_exclusive: false,
why: 'Previews every frontmatter repair with its diff and a hash; nothing is written until that hash is applied.',
},
});
}
function usage(message: string): void {
console.error(`error: ${message}`);
setCliExitVerdict(1);
}
async function runValidate(rest: string[], io: FrontmatterIo): Promise<void> {
const flags: ValidateFlags = { json: false, fix: false, dryRun: false, importable: false, includeAmbiguous: false, stdin: false, staged: false };
const targets: string[] = [];
for (let i = 0; i < rest.length; i++) {
const a = rest[i]!;
if (a === '--') { targets.push(...rest.slice(i + 1)); break; }
if (a === '--json') flags.json = true;
else if (a === '--fix') flags.fix = true;
else if (a === '--dry-run') flags.dryRun = true;
else if (a === '--importable') flags.importable = true;
else if (a === '--include-ambiguous') flags.includeAmbiguous = true;
else if (a === '--stdin' || a === '-') flags.stdin = true;
else if (a === '--staged') flags.staged = true;
else if (a === '--path') flags.path = rest[++i];
else if (a.startsWith('--path=')) flags.path = a.slice('--path='.length);
else if (!a.startsWith('--')) targets.push(a);
}
if (flags.path !== undefined && (!flags.stdin || !flags.path)) {
usage('--path names where --stdin content would live (source-relative, e.g. --path people/alice-example.md); it needs --stdin and a value.');
return;
}
if (flags.fix && (flags.stdin || flags.staged)) {
usage(`--fix rewrites working-tree files, not ${flags.stdin ? 'stdin' : 'staged blobs'}. Run: gbrain frontmatter validate <file> --fix${flags.staged ? ', then git add <file>' : ''}`);
return;
}
if (flags.stdin && flags.staged) {
usage('pass either --stdin or --staged, not both.');
return;
}
const results: FileValidation[] = [];
let scanned = 0;
let targetLabel: string;
let targetList: string[] | undefined;
let slugCheckSkipped = false;
const fixedInGit: string[] = [];
if (flags.stdin) {
const read = await readStdinBounded({ maxBytes: 2 * MAX_FILE_SIZE, ...(io.stdin ? { stream: io.stdin } : {}) });
if (read.kind !== 'data' && read.kind !== 'empty') {
usage(`could not read stdin (${read.kind === 'error' ? read.error.message : read.kind}). Pipe the content in: cat <file> | gbrain frontmatter validate --stdin --path <source-relative path>`);
return;
}
const content = read.kind === 'data' ? read.text : '';
targetLabel = flags.path ?? '<stdin>';
slugCheckSkipped = flags.path === undefined;
const check = checkContent(content, flags.path, flags.importable);
results.push(toResult(targetLabel, check));
scanned = 1;
} else if (flags.staged) {
let staged: ReturnType<typeof readStagedBlobs>;
try {
staged = readStagedBlobs(targets, io.cwd);
} catch (error) {
usage(`--staged reads the git index, which failed here (${error instanceof Error ? error.message.split('\n')[0] : String(error)}). Run it inside the repository: cd <repo> && gbrain frontmatter validate --staged`);
return;
}
targetLabel = staged.root;
for (const file of staged.files) {
scanned++;
if (file.content === null) {
results.push({ path: file.rel, errors: [], failed: true, note: `No staged version of ${file.rel}. Stage it first: git add ${file.rel}` });
continue;
}
const check = checkContent(file.content, file.rel, flags.importable);
const result = toResult(file.rel, check);
if (check.failed) {
// nosemgrep: javascript.lang.security.audit.path-traversal.path-join-resolve-traversal.path-join-resolve-traversal -- file.rel is a staged path from git diff --cached; isPathContained rejects anything outside the work tree
const working = join(staged.root, file.rel);
result.working_copy_ok = isPathContained(working, staged.root) && lstatSync(working).isFile()
&& !checkContent(readFileSync(working, 'utf8'), file.rel, flags.importable).failed;
}
results.push(result);
}
} else {
if (targets.length === 0) {
usage('gbrain frontmatter validate requires a <path> argument (or --stdin, or --staged)');
return;
}
const roots: Array<{ resolved: string; files: string[] }> = [];
const seen = new Set<string>();
for (const target of targets) {
const resolved = resolve(target);
if (!existsSync(resolved)) {
usage(`path not found: ${target}`);
return;
}
if (lstatSync(resolved).isFile() && !isMarkdownFilePath(resolved)) {
usage(`frontmatter validation supports only .md and .mdx files: ${target}`);
return;
}
roots.push({ resolved, files: collectFiles(resolved).filter(f => !seen.has(f) && !!seen.add(f)) });
}
targetLabel = roots[0]!.resolved;
if (roots.length > 1) targetList = roots.map(r => r.resolved);
if (flags.fix && !flags.dryRun) {
for (const file of roots.flatMap(r => r.files)) {
try {
assertManagedFilesystemWrite(file);
} catch (error) {
if (error instanceof OperationError && error.code === 'writer_coordinator_required') throw managedFixRefusal(file, error);
throw error;
}
}
}
const backupRunId = makeFrontmatterBackupRunId();
scanned = seen.size;
for (const { resolved, files } of roots) {
const brainRoot = findBrainRoot(resolved);
const inGit = existsSync(join(brainRoot, '.git'));
for (const file of files) {
const content = readFileSync(file, 'utf8');
const rel = relative(brainRoot, file);
// Files above/outside the brain root fall back to basename rather than
// emitting a "../"-prefixed slug for non-brain files.
const slugPath = rel && !relativeEscapesRoot(rel) ? rel : basename(file);
const check = checkContent(content, slugPath, flags.importable);
const result = toResult(file, check);
const rescuable = flags.includeAmbiguous && check.warnings.some(w => w.code === 'FRONTMATTER_COMMENT_VALUE');
if (flags.fix && (check.errors.length > 0 || rescuable)) {
// #5053: the fixer derives the slug from the same path validate used;
// the absolute path re-keyed every declared slug as a mismatch.
const auto = autoFixFrontmatter(content, { filePath: slugPath });
const repaired = repairRecoverableFrontmatter(auto.content, { includeAmbiguous: flags.includeAmbiguous });
result.fixesApplied = [...auto.fixes, ...repaired.fixes];
if (result.fixesApplied.length > 0 && !flags.dryRun) {
assertManagedFilesystemWrite(file);
result.backupPath = createFrontmatterBackup(file, { sourcePath: resolved, runId: backupRunId });
writeFileSync(file, repaired.content, 'utf8');
if (inGit) fixedInGit.push(relative(brainRoot, file));
}
const after = result.fixesApplied.length > 0 ? checkContent(repaired.content, slugPath, flags.importable) : check;
result.remaining_errors = after.errors;
if (flags.importable) result.remaining_hold = after.hold;
result.failed = after.failed;
}
results.push(result);
}
}
}
const totalErrors = results.reduce((n, r) => n + r.errors.length, 0);
const filesWithErrors = results.filter(r => r.errors.length > 0).length;
const filesFixed = results.filter(r => (r.fixesApplied?.length ?? 0) > 0).length;
const failed = results.filter(r => r.failed);
if (flags.json) {
console.log(JSON.stringify({
ok: failed.length === 0,
mode: flags.importable ? 'importable' : 'strict',
target: targetLabel,
...(targetList ? { targets: targetList } : {}),
...(flags.stdin ? { stdin: true, slug_check: slugCheckSkipped ? 'skipped' : 'checked' } : {}),
...(flags.staged ? { staged: true } : {}),
total_files: scanned,
files_with_errors: filesWithErrors,
total_errors: totalErrors,
files_failed: failed.length,
files_fixed: flags.fix ? filesFixed : undefined,
dry_run: flags.dryRun || undefined,
restage: fixedInGit.length > 0 ? fixedInGit : undefined,
results,
}, null, 2));
} else {
printValidateReport(results, { flags, scanned, totalErrors, filesWithErrors, filesFixed, slugCheckSkipped, fixedInGit });
}
setCliExitVerdict(failed.length > 0 ? 1 : 0);
}
function toResult(path: string, check: ContentCheck): FileValidation {
return {
path,
errors: check.errors,
...(check.warnings.length > 0 ? { warnings: check.warnings } : {}),
...(check.hold !== null || check.failed ? { hold: check.hold } : {}),
...(check.canonicalOnly ? { importable_but_not_canonical: true } : {}),
failed: check.failed,
};
}
function printValidateReport(results: FileValidation[], ctx: {
flags: ValidateFlags; scanned: number; totalErrors: number; filesWithErrors: number; filesFixed: number;
slugCheckSkipped: boolean; fixedInGit: string[];
}): void {
const { flags } = ctx;
if (ctx.slugCheckSkipped) console.log('Slug check skipped: pass --path <source-relative path> to check a declared slug against its path.');
const noisy = results.filter(r => r.errors.length > 0 || (r.warnings?.length ?? 0) > 0 || r.failed);
if (noisy.length === 0) {
console.log(`OK — ${ctx.scanned} ${flags.staged ? 'staged ' : ''}file(s) scanned, no frontmatter issues`);
return;
}
if (ctx.totalErrors > 0) console.log(`Found ${ctx.totalErrors} issue(s) across ${ctx.filesWithErrors} file(s) (scanned ${ctx.scanned})`);
else console.log(`${ctx.scanned} file(s) scanned; ${noisy.length} carry warnings only`);
for (const r of noisy) {
const label = flags.staged ? `${r.path} (staged version)` : r.path;
console.log(`\n${label}`);
if (r.note) console.log(` ${r.note}`);
for (const e of r.errors) {
const lineHint = e.line !== undefined ? `:${e.line}` : '';
console.log(` [${e.code}]${lineHint} ${e.message}${e.recoverable ? ' (gbrain reads it by quoting; still not valid YAML)' : ''}`);
}
for (const w of r.warnings ?? []) {
console.log(` [${w.code}]:${w.line} ${w.message}`);
if (w.original !== undefined && w.replacement !== undefined) {
console.log(` line ${w.line}: ${w.original}`);
console.log(` quoted: ${w.replacement}`);
}
}
if (flags.importable) {
if (!r.hold) console.log(' importable: gbrain imports this file as it is');
else {
console.log(` held on import: ${r.hold.code}${r.hold.reason ? ` (${r.hold.reason})` : ''}${r.hold.line !== undefined ? ` at line ${r.hold.line}` : ''}`);
console.log(` ${r.hold.message}`);
if (r.hold.reason === 'needs_interpretation' && !flags.stdin && !flags.staged) {
console.log(` Preview gbrain's interpretation: gbrain frontmatter validate ${r.path} --fix --include-ambiguous --dry-run`);
}
}
}
if (r.fixesApplied && r.fixesApplied.length > 0) {
const verb = flags.dryRun ? 'would fix' : 'fixed';
for (const f of r.fixesApplied) console.log(` ${verb}: ${f.description}`);
}
if (r.remaining_errors && r.failed) {
for (const e of r.remaining_errors) console.log(` still failing: [${e.code}]${e.line !== undefined ? `:${e.line}` : ''} ${e.message}`);
if (r.remaining_errors.some(e => e.code === 'YAML_PARSE') && !flags.includeAmbiguous) {
console.log(` Fix that line by hand (one line per key, the whole value quoted), or preview gbrain's interpretation: gbrain frontmatter validate ${r.path} --fix --include-ambiguous --dry-run`);
}
}
if (r.importable_but_not_canonical && !r.fixesApplied) {
console.log(` importable but not canonical; run gbrain frontmatter validate ${flags.stdin ? (flags.path ?? '<file>') : r.path} --fix (quoting only)`);
}
if (flags.staged && r.failed && !r.note) {
console.log(r.working_copy_ok
? ` the staged version of ${r.path} is broken; the working copy passes. Review it and git add ${r.path}`
: ` the staged version of ${r.path} is broken; fix the file (gbrain frontmatter validate ${r.path} --fix), then git add ${r.path}`);
}
}
if (flags.fix && !flags.dryRun && ctx.filesFixed > 0) {
console.log(`\nWrote centralized backups for ${ctx.filesFixed} file(s) under ~/.gbrain/backups/frontmatter/.`);
}
if (ctx.fixedInGit.length > 0) {
console.log(`Review the changes, then restage them: git add -- ${ctx.fixedInGit.map(p => shellQuote(p)).join(' ')}`);
}
}
/**
* Recursively collect every syncable `.md` file under `target`.
*
* Uses the canonical `pruneDir(name, parentDir)` gate (sync.ts:258) to
* skip vendor / hidden / generated subtrees at descent time. Pre-v0.38.2.0
* this walker descended into every subtree and let `isSyncable` filter at
* the leaf — paying the IO cost of stat'ing every entry under node_modules,
* .git, .obsidian, etc. That was the second instance of the v0.38.2.0 hang
* class (the first being brain-writer.ts:walkDir). Codex outside-voice
* caught it during plan-eng-review — fixing only walkDir would have left
* `gbrain frontmatter validate` (doctor's own remediation hint) hanging
* users in the same way.
*
* Optional `visitDir(dir)` is the test-observability hook: fired once per
* directory the walker descends into (post-pruneDir). Production callers
* don't pass it; the regression suite uses it to assert descent-time
* pruning directly.
*/
export function collectFiles(
target: string,
visitDir?: (dirPath: string) => void,
): string[] {
const st = lstatSync(target);
if (st.isFile()) {
// An explicit Markdown target is operator intent, even for structural
// basenames that bulk scans intentionally skip.
return isMarkdownFilePath(basename(target)) ? [target] : [];
}
const scannable = frontmatterScannableUnder(target);
const gitFiles = collectGitVisibleFiles(target, scannable);
if (gitFiles) {
if (visitDir) visitDir(target);
return gitFiles;
}
const out: string[] = [];
const stack = [target];
if (visitDir) visitDir(target);
while (stack.length > 0) {
const dir = stack.pop()!;
let entries: string[];
try {
entries = readdirSync(dir);
} catch {
continue;
}
for (const name of entries) {
const full = join(dir, name);
let entryStat: ReturnType<typeof lstatSync>;
try {
entryStat = lstatSync(full);
} catch {
continue;
}
if (entryStat.isSymbolicLink()) continue;
if (entryStat.isDirectory()) {
// Descent-time prune — the actual fix for the second walker bug
// class (codex outside-voice C5).
if (!pruneDir(name, dir)) continue;
if (visitDir) visitDir(full);
stack.push(full);
} else if (entryStat.isFile()) {
const rel = relative(target, full);
if (scannable(rel)) {
out.push(full);
}
}
}
}
return out;
}
// ---------------------------------------------------------------------------
// audit
// ---------------------------------------------------------------------------
async function runAudit(engine: BrainEngine, rest: string[]): Promise<void> {
let json = false;
let sourceId: string | undefined;
for (let i = 0; i < rest.length; i++) {
const a = rest[i];
if (a === '--json') json = true;
else if (a === '--source') sourceId = rest[++i];
else if (a.startsWith('--source=')) sourceId = a.slice('--source='.length);
}
const report = await scanBrainSources(engine, { sourceId });
if (json) {
console.log(JSON.stringify(report, null, 2));
return;
}
printAuditHumanReport(report);
}
function printAuditHumanReport(report: AuditReport): void {
if (report.per_source.length === 0) {
console.log('No registered sources to audit. Run `gbrain sources list` to inspect.');
return;
}
console.log(`Frontmatter audit — ${report.total} malformed issue(s) across ${report.per_source.length} source(s) (scanned at ${report.scanned_at})`);
if (report.ignored_missing_open) {
console.log(`Missing frontmatter ignored: ${report.ignored_missing_open} file(s). Use \`frontmatter validate\` for strict per-file checks or \`frontmatter generate\` to add meaningful metadata.`);
}
for (const src of report.per_source) {
console.log(`\n[${src.source_id}] ${src.source_path}`);
if (src.status === 'missing') {
console.log(' NOT SCANNED: the directory is missing (restore it, or gbrain sources set-path <id> <path>)');
continue;
}
if (src.total === 0) {
console.log(' clean');
continue;
}
console.log(` ${src.total} issue(s)`);
for (const [code, n] of Object.entries(src.errors_by_code)) {
const split = src.recoverability_by_code?.[code as ParseValidationCode];
console.log(` ${code}: ${n}${split ? ` (${split.recoverable} imported anyway, ${split.unrecoverable} held on import)` : ''}`);
}
if (src.sample.length > 0) {
console.log(` sample:`);
for (const s of src.sample.slice(0, 5)) {
console.log(` ${s.path} — ${s.codes.join(', ')}`);
}
if (src.sample.length > 5) console.log(` (+ ${src.sample.length - 5} more)`);
}
}
if (report.total > 0) {
console.log(`\nFix with: gbrain frontmatter validate <source-path> --fix (on a managed brain: gbrain repair frontmatter --source <id>)`);
}
}
// ---------------------------------------------------------------------------
// generate — synthesize frontmatter for files that have none
// ---------------------------------------------------------------------------
async function runGenerate(args: string[]): Promise<void> {
const targetPath = args.find(a => !a.startsWith('-'));
const doFix = args.includes('--fix');
const dryRun = args.includes('--dry-run');
const jsonOut = args.includes('--json');
const includeCatchAll = args.includes('--include-catch-all') || args.includes('--allow-catch-all');
if (!targetPath) {
console.error('error: gbrain frontmatter generate requires a <path> argument');
console.error('usage: gbrain frontmatter generate <path> [--fix] [--dry-run] [--json]');
setCliExitVerdict(1);
return;
}
const { inferFrontmatter, serializeFrontmatter } = await import('../core/frontmatter-inference.ts');
const { resolve, relative, join, basename } = await import('path');
const { readFileSync, writeFileSync, statSync, lstatSync } = await import('fs');
const rootPath = resolve(targetPath);
const isDir = statSync(rootPath).isDirectory();
if (!isDir && !isMarkdownFilePath(rootPath)) {
console.error(`error: frontmatter generation supports only .md and .mdx files: ${targetPath}`);
setCliExitVerdict(1);
return;
}
// Find the brain root — walk up from targetPath looking for .git or known brain markers.
// Inference rules match against brain-root-relative paths (e.g., "people/alice.md").
let brainRoot = rootPath;
if (isDir) {
let candidate = rootPath;
for (let i = 0; i < 10; i++) {
try {
statSync(join(candidate, '.git'));
brainRoot = candidate;
break;
} catch {
const parent = resolve(candidate, '..');
if (parent === candidate) break;
candidate = parent;
}
}
}
interface GenerateResult {
path: string;
type: string;
title: string;
date?: string;
rule: string;
}
const results: GenerateResult[] = [];
const scannable = frontmatterScannableUnder(brainRoot);
let scanned = 0;
let skipped = 0;
let skippedCatchAll = 0;
let generated = 0;
let written = 0;
const backupRunId = makeFrontmatterBackupRunId();
function processFile(absPath: string, relPath: string) {
scanned++;
if (!scannable(relPath)) return;
// Skip symlinks
try { if (lstatSync(absPath).isSymbolicLink()) return; } catch { return; }
let content: string;
// #4798: strip a UTF-8 BOM so heading-title inference (and --fix's
// written body) match what `gbrain sync` / `import` produce.
try { content = readFileSync(absPath, 'utf-8').replace(/^\uFEFF/, ''); } catch { return; }
const inferred = inferFrontmatter(relPath, content);
if (inferred.skipped) {
skipped++;
return;
}
if (!includeCatchAll && inferred.matchedRule === '(default)') {
skippedCatchAll++;
return;
}
generated++;
results.push({
path: relPath,
type: inferred.type,
title: inferred.title,
date: inferred.date,
rule: inferred.matchedRule || '(default)',
});
if (doFix && !dryRun) {
const fm = serializeFrontmatter(inferred);
const newContent = fm + '\n' + content;
// Safety: write a centralized backup first.
createFrontmatterBackup(absPath, { sourcePath: brainRoot, runId: backupRunId });
assertManagedFilesystemWrite(absPath);
writeFileSync(absPath, newContent, 'utf-8');
written++;
}
}
if (isDir) {
for (const absPath of collectFiles(rootPath)) {
processFile(absPath, relative(brainRoot, absPath));
}
} else {
const relPath = relative(brainRoot, rootPath) || basename(rootPath);
processFile(rootPath, relPath);
}
// Output
if (jsonOut) {
console.log(JSON.stringify({
scanned,
skipped,
skippedCatchAll,
generated,
written,
dryRun: !doFix || dryRun,
results: results.slice(0, 100), // Cap JSON output
totalResults: results.length,
}, null, 2));
return;
}
// Human-readable output
const mode = doFix && !dryRun ? 'WRITE' : 'DRY-RUN';
console.log(`\nFrontmatter generation (${mode})`);
console.log(` Scanned: ${scanned} files`);
console.log(` Already have frontmatter: ${skipped}`);
if (skippedCatchAll > 0) {
console.log(` Skipped catch-all/unknown: ${skippedCatchAll} (pass --include-catch-all to write type: note)`);
}
console.log(` Would generate: ${generated}`);
if (doFix && !dryRun) {
console.log(` Written: ${written} (with centralized backups)`);
}
// Show sample by type
const byType: Record<string, number> = {};
for (const r of results) {
byType[r.type] = (byType[r.type] || 0) + 1;
}
if (Object.keys(byType).length > 0) {
console.log(`\n By type:`);
for (const [type, count] of Object.entries(byType).sort(([, a], [, b]) => b - a)) {
console.log(` ${type}: ${count}`);
}
}
// Show first 10 examples
if (results.length > 0 && (!doFix || dryRun)) {
console.log(`\n Examples:`);
for (const r of results.slice(0, 10)) {
console.log(` ${r.path}`);
console.log(` → type: ${r.type}, title: "${r.title}"${r.date ? `, date: ${r.date}` : ''} [rule: ${r.rule}]`);
}
if (results.length > 10) {
console.log(` ... and ${results.length - 10} more`);
}
if (!doFix) {
console.log(`\n To write: gbrain frontmatter generate ${targetPath} --fix`);
}
}
}