Garry's Opinionated OpenClaw/Hermes Agent Brain
TypeScript
/**
* `gbrain git commit-push` (#6530): the one way an agent, cron or skill
* commits and pushes in a brain checkout that other writers share. DB-free
* and trusted-local only (it pushes with this host's git credentials); the
* protocol lives in src/core/git/commit-push.ts.
*
* gbrain git commit-push [--path <dir>] -m <msg> [--json] [--] <paths…>
* gbrain git commit-push --push-only [--keep-checkout] [--path <dir>] [--expect-remote <sha> --resolve <p>=ours|theirs|file:<f>…]
* gbrain git commit-push --pull [--path <dir>] [--require-clean]
* gbrain git commit-push --untrack [--path <dir>] -m <msg> [--] <paths…>
* gbrain git commit-push --dry-run [--untrack] [--path <dir>] [-m <msg>] [--] <paths…>
* gbrain git commit-push --pending [--path <dir>] [-m <msg>]
* gbrain git guard [--install | --uninstall] [--path <dir>] [--json]
* gbrain git scan [--path <dir>] [--from <rev>] [--to <rev>] [--scan-timeout <s>] [--json]
*/
import { existsSync, realpathSync } from 'node:fs';
import { isAbsolute, join, relative, sep } from 'node:path';
import { commitAndPush, checkoutRoot, previewPaths, previewUntrack, pullShared, scopePaths, COMMIT_LOCK_NAME, SOURCE_ROOT_CONFIG, type Resolution } from '../core/git/commit-push.ts';
import { readUntrackPageVerdict, UNTRACK_PAGE_READ_TIMEOUT_MS, type UntrackPageVerdict } from '../core/git/untrack-admission.ts';
import type { BrainEngine } from '../core/engine.ts';
import type { ManagedFilesystemRoot } from '../core/persistence/filesystem-guard.ts';
import { guardStatus, installGuard, uninstallGuard } from '../core/git/commit-guard.ts';
import { appendPushLog } from '../core/brain-repo-durability.ts';
import { opError } from '../core/ops/contract.ts';
import { writeCliError } from '../cli/cli-error.ts';
import { writeStdoutFinal } from '../core/cli-force-exit.ts';
import { execFileSync } from '../core/spawn.ts';
import { gitChildEnv } from '../core/git-env.ts';
import { GIT_ENV } from '../core/git-transport.ts';
import { managedFilesystemRootFor, staleEnclosingMarker } from '../core/persistence/filesystem-guard.ts';
import { rangeSecretRefusal, scanRange } from '../core/git/range-secret-scan.ts';
import { canonicalFilesystemPath, checkoutGitMetadata, managedRootMarkerFor, registeredManagedRootRecords } from '../core/persistence/root-registry.ts';
const HELP = `Usage: gbrain git commit-push [--path <dir>] -m <msg> [--json] [--] <paths...>
gbrain git commit-push --push-only [--path <dir>] [--branch <b>]
gbrain git commit-push --push-only [--keep-checkout] [--path <dir>] --expect-remote <sha> --resolve <path>=ours|theirs|file:<file>...
gbrain git commit-push --pull [--path <dir>] [--require-clean]
gbrain git commit-push --pending [--path <dir>] [-m <msg>]
gbrain git commit-push --untrack [--path <dir>] -m <msg> [--] <paths...>
gbrain git guard [--install | --uninstall] [--path <dir>] [--json]
gbrain git scan [--path <dir>] [--from <rev>] [--to <rev>] [--scan-timeout <s>] [--json]
Commit only the named paths and push them, safely, in a checkout other agents
share: a short commit lock and a separate push lock per checkout, no
rebase/stash/reset of the working tree, remote commits merged in memory, and the
checkout advanced fast-forward only. In a managed canonical worktree it only
commits the named paths (committed_local): no fetch, merge, push or checkout
move; the owner's next Git publish, or --push-only --keep-checkout, pushes it.
In a checkout with no Git remote it also only commits the named paths
(committed_local, no_remote); the publishing modes are refused there.
Flags:
--path <dir> Checkout to act on (default: the checkout containing the cwd).
-m, --message <m> Commit message (required unless --push-only or --pull); repeat it, like git
commit, for more paragraphs (a second -m <trailer> is the body).
--push-only Publish commits already on the branch; commit nothing.
--branch <name> With --push-only: publish HEAD to this remote branch (one exact name).
--keep-checkout With --push-only: never move the checkout and skip its pre-push hook. The one
publish allowed in a managed canonical worktree (its Git effects' integrate_conflict
fix); gbrain sources refresh brings the merged remote files in afterwards.
--scan-secrets Accepted for older scripts: every push scans what the unpublished commits add
(messages, added lines, merge resolutions) and refuses publish_secret_found on a finding.
--scan-timeout <s> The secret scan's time budget in seconds (default 300); a first push of a long
history may need more. The scan still reads every commit.
--pull Bring remote commits in (fast-forward, or an in-memory merge); never pushes.
--require-clean Unattended rule: --pull skips when the checkout has any local edit;
a push never advances a checkout that has one, and never waits for
another push (it asks that push to publish HEAD too: push_deferred).
--base <p>=<blob> Refuse (commit_base_moved) unless path p's blob at HEAD is still <blob> (full object
id, or absent for a new file); repeat per path. Each p must also be committed.
--resolve <p>=<v> After integrate_conflict: which side wins for path p (ours, theirs, file:<merged copy>).
--expect-remote <sha> Required with --resolve: the remote commit the choice was made against
(printed by integrate_conflict); a remote that moved since is reported again.
--pending Commit the write-through files gbrain wrote but could not commit (the pending
ledger doctor's dirty_age reports), then push.
--allow-outside-source-root Commit and publish files outside the checkout's source root(s)
(git config gbrain.sourceRoot); only after the user agrees.
--untrack Remove the named paths from Git (git rm --cached), keeping the files on disk; a
directory untracks every file Git holds under it. In a managed canonical worktree
only files under a storage.db_only dir that gbrain.yml at HEAD declares and
.gitignore ignores; it commits there and never pushes.
--dry-run Print the paths, branch and lock that would be used, and the marker that makes the
checkout a managed canonical worktree (or none); take no lock, write nothing.
The real run's path checks run first and refuse as it would (a path outside the
source root or a sparse-checkout definition, a moved --base, another writer's file).
--json One JSON result (or the error envelope) on stdout.
Paths are relative to --path when it is given (like git -C), else to the current
directory. Exit 0 on pushed, committed_local, nothing_to_commit, push_deferred and
pushed_checkout_lagging (a notice names the blocking files); 4 when the commit is local but no push was
confirmed (push_unconfirmed); 1 on other failures, each with an "Error [<code>]" line. Guide: docs/guides/shared-checkout-git.md
gbrain git guard [--install | --uninstall]: the opt-in commit guard, a local
prepare-commit-msg hook that refuses commits in this checkout not made through
gbrain (git commit, -a and --no-verify included; merges and commits that finish a
merge, cherry-pick, revert or rebase pass). A person bypasses it once with
GBRAIN_COMMIT_GUARD=off git <command>. Without a flag it prints whether the guard
is installed.
gbrain git scan: the secret scan a push runs, over --from..--to (default: the
upstream as last fetched, ..HEAD), with the checkout's .gbrain-scan-allow. It
fetches, locks, writes and pushes nothing. It prints what a push would refuse
(would_refuse) and each finding's path, line, rule, commit and fingerprint, never
the value; a finding's fingerprint line in .gbrain-scan-allow accepts that value.
Exit 0 when the scan ran, whatever it found.`;
interface Parsed {
sub?: string; path?: string; message?: string; branch?: string; expectRemote?: string; json: boolean; pushOnly: boolean; pull: boolean;
requireClean: boolean; dryRun: boolean; help: boolean; keepCheckout: boolean; paths: string[]; resolve: string[]; base: string[]; untrack: boolean;
pending: boolean; allowOutside: boolean; install: boolean; uninstall: boolean; scanSecrets: boolean; scanTimeout?: string; from?: string; to?: string;
}
function parse(args: string[]): Parsed {
const p: Parsed = { json: false, pushOnly: false, pull: false, requireClean: false, dryRun: false, help: false, keepCheckout: false, paths: [], resolve: [], base: [], untrack: false,
pending: false, allowOutside: false, install: false, uninstall: false, scanSecrets: false };
let rest = false;
for (let i = 0; i < args.length; i++) {
const a = args[i];
if (rest) { p.paths.push(a); continue; }
const take = (name: string): string => {
const eq = a.indexOf('=');
if (a.startsWith('--') && eq !== -1) return a.slice(eq + 1);
const v = args[++i];
if (v === undefined) throw opError('commit_paths_invalid', `${name} needs a value.`, HELP.split('\n')[0]);
return v;
};
if (a === '--') rest = true;
else if (a === '--help' || a === '-h') p.help = true;
else if (a === '--json') p.json = true;
else if (a === '--push-only') p.pushOnly = true;
else if (a === '--keep-checkout') p.keepCheckout = true;
else if (a === '--scan-secrets') p.scanSecrets = true;
else if (a === '--pull') p.pull = true;
else if (a === '--require-clean') p.requireClean = true;
else if (a === '--dry-run') p.dryRun = true;
else if (a === '--untrack') p.untrack = true;
else if (a === '--pending') p.pending = true;
else if (a === '--allow-outside-source-root') p.allowOutside = true;
else if (a === '--install') p.install = true;
else if (a === '--uninstall') p.uninstall = true;
else if (a === '--path' || a.startsWith('--path=') || a === '--repo' || a.startsWith('--repo=')) p.path = take('--path');
else if (a === '-m' || a === '--message' || a.startsWith('--message=')) { const m = take('--message'); p.message = p.message === undefined ? m : `${p.message}\n\n${m}`; }
else if (a === '--resolve' || a.startsWith('--resolve=')) p.resolve.push(take('--resolve'));
else if (a === '--base' || a.startsWith('--base=')) p.base.push(take('--base'));
else if (a === '--branch' || a.startsWith('--branch=')) p.branch = take('--branch');
else if (a === '--expect-remote' || a.startsWith('--expect-remote=')) p.expectRemote = take('--expect-remote');
else if (a === '--scan-timeout' || a.startsWith('--scan-timeout=')) p.scanTimeout = take('--scan-timeout');
else if (a === '--from' || a.startsWith('--from=')) p.from = take('--from');
else if (a === '--to' || a.startsWith('--to=')) p.to = take('--to');
else if (!p.sub) p.sub = a;
else if (a.startsWith('-')) throw opError('commit_paths_invalid', `Unknown flag ${a}.`, HELP.split('\n')[0]);
else p.paths.push(a);
}
return p;
}
function parseResolutions(specs: string[]): Map<string, Resolution> {
const out = new Map<string, Resolution>();
for (const spec of specs) {
const eq = spec.lastIndexOf('=');
const path = eq > 0 ? spec.slice(0, eq) : '';
const choice = eq > 0 ? spec.slice(eq + 1) : '';
if (!path) throw opError('commit_paths_invalid', `--resolve ${spec} is not <path>=ours|theirs|file:<file>.`, 'Example: --resolve people/alice-example.md=theirs');
if (choice === 'ours' || choice === 'theirs') out.set(path, { kind: choice });
else if (choice.startsWith('file:') && choice.length > 5) out.set(path, { kind: 'file', path: choice.slice(5) });
else throw opError('commit_paths_invalid', `--resolve ${spec}: choose ours, theirs or file:<merged copy>.`, 'Example: --resolve people/alice-example.md=theirs');
}
return out;
}
/**
* #8662: on a host whose brain records its source checkouts, a checkout resolved from the working directory that is none of
* them and carries no mark of a gbrain brain checkout is refused before anything is staged (a wrapper that changed into
* another repository). A legacy source is not in that record, so `gbrain sources harden`'s marks admit it: a
* gbrain.sourceRoot or gbrain.cliPath entry, or the committed scripts/brain-commit-push.sh (whose own calls pass no --path).
* An explicit --path names its checkout and is not checked here. GST-1623: a registered checkout must contain the resolved
* one, or be a directory of it that its HEAD tracks; a repository that only encloses a registered checkout (a nested clone)
* is not a source checkout, even with the stale marker an older gbrain wrote in its git dir (#7988).
*/
function assertSourceCheckout(repo: string): void {
const registered = registeredManagedRootRecords();
if (!registered.length) return;
const marker = managedRootMarkerFor(repo);
if (marker && !staleEnclosingMarker({ root: marker.root, evidence: marker.marker })) return;
const top = canonicalFilesystemPath(repo);
const within = (root: string, path: string) => { const rel = relative(root, path); return !isAbsolute(rel) && rel !== '..' && !rel.startsWith(`..${sep}`); };
const metadata = checkoutGitMetadata(top);
if (registered.some(record => within(record.root, top) || (within(top, record.root) && metadata !== null && existsSync(record.root) && checkoutGitMetadata(record.root) === metadata))) return;
if (existsSync(join(repo, 'scripts', 'brain-commit-push.sh'))) return;
try {
execFileSync('git', ['-C', repo, 'config', '--local', '--get-regexp', `^(${SOURCE_ROOT_CONFIG}|gbrain.clipath)$`.replace(/\./g, '\\.').toLowerCase()], { env: gitChildEnv({ ...GIT_ENV }), stdio: ['ignore', 'pipe', 'ignore'] });
return;
} catch { /* no marker */ }
const first = registered[0]!.root;
const listed = registered.slice(0, 5).map(record => `${record.root}${record.source_id ? ` (${record.source_id})` : ''}`).join(', ') + (registered.length > 5 ? ` and ${registered.length - 5} more` : '');
throw opError('checkout_not_a_source', `${repo} is not a source checkout of this brain; its source checkouts on this host are ${listed}. Nothing was staged.`,
`Pass the brain checkout with an absolute --path, for example gbrain git commit-push --path ${first} -m <msg> -- <paths>; a script or cron wrapper that changes directory first must name it the same way.`,
{ fix: { argv: ['gbrain', 'git', 'commit-push', '--dry-run', '--path', first], consent: [], actor: 'user', requires_exclusive: false,
why: 'The dry run shows the checkout, branch and lock commit-push uses with that --path, writing nothing.',
user_message: `gbrain git commit-push resolved ${repo}, which is not one of this brain's source checkouts (${listed}). Change the script or wrapper that ran it to pass --path with the absolute brain checkout.`,
verify: { argv: ['gbrain', 'git', 'commit-push', '--dry-run', '--path', first] } } });
}
/** `gbrain git scan`: the push's secret scan over a range, read-only, so an operator can see what a push would refuse. */
function runScan(p: Parsed): number {
const repo = checkoutRoot(p.path ?? process.cwd());
if (p.scanTimeout !== undefined && !/^[1-9]\d{0,5}$/.test(p.scanTimeout)) {
throw opError('commit_paths_invalid', `--scan-timeout ${p.scanTimeout} is not a number of seconds.`, 'Pass whole seconds, for example --scan-timeout 1800.');
}
const rev = (spec: string, flag: string): string => {
try { return execFileSync('git', ['-C', repo, 'rev-parse', '--verify', '--quiet', '--end-of-options', `${spec}^{commit}`], { env: gitChildEnv({ ...GIT_ENV }) }).toString().trim(); }
catch { throw opError('commit_paths_invalid', `${flag} ${spec} names no commit in ${repo}.`, 'Pass a commit, for example --from $(git rev-list -1 --before="30 days ago" HEAD); with no upstream, --from is required.'); }
};
const from = rev(p.from ?? '@{upstream}', '--from');
const to = rev(p.to ?? 'HEAD', '--to');
const timeoutMs = p.scanTimeout ? Number(p.scanTimeout) * 1000 : undefined;
const started = Date.now();
const scan = scanRange(repo, from, to, timeoutMs, line => process.stderr.write(`[gbrain] ${line}\n`));
const refusal = rangeSecretRefusal(repo, from, to, scan, { timeoutMs });
const commits = Number(execFileSync('git', ['-C', repo, 'rev-list', '--count', `${from}..${to}`], { env: gitChildEnv({ ...GIT_ENV }) }).toString().trim());
const seconds = Math.round((Date.now() - started) / 100) / 10;
const items = [...scan.findings.map(f => ` ${f.commit.slice(0, 7)} ${f.path}:${f.line} ${f.pattern} ${f.fingerprint}`),
...scan.unscanned.map(u => ` ${u.commit.slice(0, 7)} ${u.path} too large to scan`), ...scan.gate_changes.map(g => ` ${g.commit.slice(0, 7)} ${g.path} changes what the scan sees`),
...(scan.allowed ?? []).map(a => ` ${a.commit.slice(0, 7)} ${a.path}:${a.line} ${a.pattern} allowed by .gbrain-scan-allow line: ${a.entry}`),
...(scan.allowlist_problems ?? []).map(p => ` .gbrain-scan-allow line ${p.entry}: ${p.problem}`)];
emit(p.json, { repo, from, to, commits, seconds, would_refuse: refusal?.code ?? null, findings: scan.findings, unscanned: scan.unscanned, gate_changes: scan.gate_changes,
allowed: scan.allowed ?? [], allowlist_problems: scan.allowlist_problems ?? [], unreadable: scan.unreadable ?? null }, [`scanned ${commits} commit(s) ${from.slice(0, 12)}..${to.slice(0, 12)} in ${seconds} s: ${refusal ? `a push would refuse (${refusal.code})` : 'a push would not refuse'}`,
...(scan.unreadable !== undefined ? [` not read in full: ${scan.unreadable}`] : []), ...items].join('\n'));
return 0;
}
/** Opens this machine's brain with no migration or startup step, reads the verdict, and closes it; any failure or a read past the timeout is `unreadable`. */
export async function untrackPageVerdict(managed: ManagedFilesystemRoot, root: string, rel: string[]): Promise<UntrackPageVerdict> {
const { isThinClient, loadConfig, toEngineConfig } = await import('../core/config.ts');
const { createEngine } = await import('../core/engine-factory.ts');
let engine: BrainEngine | null = null, timer: ReturnType<typeof setTimeout> | undefined;
const read = (async (): Promise<UntrackPageVerdict> => {
const config = loadConfig();
if (!config) return { unreadable: 'no brain is configured on this machine' };
if (isThinClient(config) && !config.database_url) return { unreadable: 'this install is a thin client with no local brain' };
const engineConfig = config.engine === 'pglite' ? { ...toEngineConfig(config), pglite_shared_buffers: '32MB' } : { ...toEngineConfig(config), pool_max: 1 };
engine = await createEngine(engineConfig);
await engine.connect(engineConfig);
return readUntrackPageVerdict(engine, managed, root, rel);
})();
const timeout = new Promise<UntrackPageVerdict>(done => { timer = setTimeout(() => done({ unreadable: `the read took longer than ${UNTRACK_PAGE_READ_TIMEOUT_MS / 1000} s (another process may hold the brain)` }), UNTRACK_PAGE_READ_TIMEOUT_MS); });
let settled = false;
void read.finally(() => { settled = true; }).catch(() => {});
try {
return await Promise.race([read.catch((error: unknown) => ({ unreadable: (error as { code?: string; message?: string })?.code ?? (error as Error)?.message ?? String(error) })), timeout]);
} finally {
clearTimeout(timer);
const close = () => (engine as BrainEngine | null)?.disconnect().catch(() => {});
if (settled) await close(); else void read.catch(() => {}).finally(close);
}
}
/** GST-2964: in a managed canonical worktree, the brain's answer for an untrack (the source's root and its live code-file pages); a checkout with no managed source opens no brain. */
async function untrackPagesFor(repo: string, paths: string[]): Promise<UntrackPageVerdict | undefined> {
const managed = managedFilesystemRootFor(repo);
return managed && paths.length ? untrackPageVerdict(managed, repo, paths) : undefined;
}
function emit(json: boolean, doc: Record<string, unknown>, human: string): void {
if (json) void writeStdoutFinal(`${JSON.stringify(doc)}\n`);
else console.log(human);
}
export async function runGit(args: string[]): Promise<number> {
let json = args.includes('--json');
try {
const p = parse(args);
json = p.json;
if (p.help || !p.sub) { console.log(HELP); return p.sub || p.help ? 0 : 2; }
if (p.sub === 'guard') return runGuard(p);
if (p.sub === 'scan') return runScan(p);
if (p.sub !== 'commit-push') throw opError('commit_paths_invalid', `Unknown subcommand: gbrain git ${p.sub}.`, HELP.split('\n')[0]);
if (p.install || p.uninstall) throw opError('commit_paths_invalid', '--install and --uninstall belong to gbrain git guard.', 'Run gbrain git guard --install.');
const repo = checkoutRoot(p.path ?? process.cwd());
if (!p.path) assertSourceCheckout(repo);
const cwd = p.path ? realpathSync(p.path) : process.cwd();
if ((p.pull && p.pushOnly) || (p.pull && (p.message || p.paths.length || p.resolve.length || p.branch)) || (p.untrack && (p.pull || p.pushOnly || p.pending))
|| (p.pushOnly && (p.message || p.paths.length)) || ((p.resolve.length || p.branch || p.expectRemote || p.keepCheckout) && !p.pushOnly) || (p.scanTimeout !== undefined && p.pull)
|| (p.pending && (p.pull || p.pushOnly || p.paths.length)) || (p.allowOutside && p.pull) || (p.base.length && (p.pull || p.pushOnly || p.pending))) {
throw opError('commit_paths_invalid', 'These flags do not combine.',
'Use one mode: -m <msg> -- <paths> (commit + push), --untrack -m <msg> -- <paths>, --pending [-m <msg>], --push-only [--keep-checkout] [--branch <b>] [--expect-remote <sha> --resolve ...], or --pull [--require-clean].');
}
const bases = new Map(p.base.map(spec => {
const eq = spec.lastIndexOf('=');
const [path, blob] = [spec.slice(0, eq), spec.slice(eq + 1)];
if (eq <= 0 || !(blob === 'absent' || /^([0-9a-f]{40}|[0-9a-f]{64})$/.test(blob))) throw opError('commit_paths_invalid', `--base ${spec} is not <path>=<blob>.`,
'Pass the full object id git rev-parse HEAD:<path> printed when you read the file, or absent for a new file.');
return [path, blob] as const;
}));
if (p.scanTimeout !== undefined && !/^[1-9]\d{0,5}$/.test(p.scanTimeout)) {
throw opError('commit_paths_invalid', `--scan-timeout ${p.scanTimeout} is not a number of seconds.`, 'Pass whole seconds, for example --scan-timeout 1800.');
}
if ((p.resolve.length && !p.expectRemote) || (p.expectRemote && !/^[0-9a-f]{7,64}$/i.test(p.expectRemote))) {
throw opError('commit_paths_invalid', '--resolve and --expect-remote <sha> go together.',
'Copy both from the integrate_conflict report: --expect-remote names the remote commit your choice was made against.');
}
if (p.dryRun) {
const lock = execFileSync('git', ['-C', repo, 'rev-parse', '--git-path', COMMIT_LOCK_NAME], { env: gitChildEnv({ ...GIT_ENV }) }).toString().trim();
const branch = execFileSync('git', ['-C', repo, 'symbolic-ref', '--quiet', '--short', 'HEAD'], { env: gitChildEnv({ ...GIT_ENV }) }).toString().trim();
const paths = p.pull || p.pushOnly || !p.paths.length ? [] : scopePaths(repo, p.paths, cwd);
const managed = managedFilesystemRootFor(repo);
const untracked = p.untrack && paths.length ? previewUntrack(repo, paths, { allowOutsideSourceRoot: p.allowOutside, untrackPages: await untrackPagesFor(repo, paths) }) : undefined;
if (!p.untrack && paths.length) previewPaths(repo, paths, { allowOutsideSourceRoot: p.allowOutside, bases, cwd });
emit(json, { dry_run: true, repo, branch, lock, paths, mode: p.pull ? 'pull' : p.pushOnly ? 'push-only' : p.untrack ? 'untrack' : 'commit-push', managed, ...(untracked ? { untracked } : {}) },
`dry run: ${p.pull ? 'pull' : p.pushOnly ? 'push-only' : `${p.untrack ? 'untrack' : 'commit'} ${paths.join(' ')}`} on ${branch} in ${repo} (lock ${lock}); ${managed ? `managed canonical worktree (${managed.evidence})` : 'not a managed worktree'}; nothing written`);
return 0;
}
if (p.pull) {
const r = pullShared(repo, { requireClean: p.requireClean });
emit(json, { ...r, repo }, r.status === 'advanced' ? `advanced ${r.from!.slice(0, 7)}→${r.to!.slice(0, 7)}${r.merged ? ' (merged)' : ''}`
: r.status === 'lagging' ? `not advanced: ${r.reason}` : r.status === 'skipped_dirty' ? 'skipped: the checkout has local edits (--require-clean)' : r.status.replace('_', ' '));
if (r.status === 'lagging' && !json) process.stderr.write(`[gbrain notice] checkout not advanced: ${r.reason}. Rerun --pull once those edits are committed.\n`);
return 0;
}
const result = commitAndPush({
repo, cwd, paths: p.paths, pushOnly: p.pushOnly, advanceOnlyWhenClean: p.requireClean,
message: p.pending ? p.message ?? 'gbrain: commit pending write-through files' : p.message,
...(p.pending ? { pending: true } : {}),
...(p.allowOutside ? { allowOutsideSourceRoot: true } : {}),
...(p.keepCheckout ? { keepCheckout: true } : {}),
...(p.scanTimeout ? { scanTimeoutMs: Number(p.scanTimeout) * 1000 } : {}),
scanProgress: (line: string) => process.stderr.write(`[gbrain] ${line}\n`),
...(p.untrack ? { untrack: true, untrackPages: await untrackPagesFor(repo, scopePaths(repo, p.paths, cwd)) } : {}),
...(p.branch ? { branch: p.branch } : {}),
...(p.resolve.length ? { resolutions: parseResolutions(p.resolve) } : {}),
...(p.expectRemote ? { expectRemote: p.expectRemote } : {}),
...(bases.size ? { bases } : {}),
});
if (result.outcome === 'push_deferred') {
emit(json, { ...result, repo }, `push deferred: another push is running in ${repo} and will publish HEAD too`);
return 0;
}
if (result.no_remote) {
emit(json, { ...result, repo }, result.committed ? `committed ${result.committed.slice(0, 7)} on ${result.branch}; not pushed: ${repo} has no Git remote (add one with git remote add origin <url>, then gbrain git commit-push --push-only)`
: `nothing to commit; not pushed: ${repo} has no Git remote`);
return 0;
}
if (result.managed) {
const upstream = result.upstream;
const state = !upstream ? `${result.branch} has no upstream`
: result.unpublished === 0 ? `${result.branch} is on ${upstream} as last fetched`
: `${result.unpublished ?? 'an unknown number of'} commit(s) on ${result.branch} ${result.unpublished === null ? 'may not be' : 'are not'} on ${upstream} as last fetched; a managed checkout publishes through its owner (gbrain git commit-push --push-only --keep-checkout --scan-secrets --path ${repo} publishes them)`;
emit(json, { ...result, repo }, `${result.committed ? `committed ${result.committed.slice(0, 7)} on ${result.branch}` : 'nothing to commit'}; not pushed: ${state}`);
return 0;
}
appendPushLog(result.outcome === 'nothing_to_commit' || result.confirmed === 'remote' ? 'nothing' : result.integrated ? 'ok-after-merge' : 'ok',
p.branch?.replace(/^refs\/heads\//, '') ?? result.branch, result.sha ?? '');
if (result.outcome === 'pushed_checkout_lagging') appendPushLog('checkout-lagging', result.branch, result.sha ?? '', result.lagging_reason);
const short = result.sha ? result.sha.slice(0, 7) : '-';
emit(json, { ...result, repo },
result.outcome === 'nothing_to_commit' ? `nothing to commit; ${result.remote}/${result.branch} at ${short}`
: `pushed ${short} to ${result.remote}/${result.branch}${result.integrated ? `; merged ${result.integrated} remote commit(s)` : ''}; checkout ${result.checkout}`);
if (result.quarantined && !json) {
process.stderr.write(`[gbrain notice] quarantine: the remote also changed ${result.quarantined.paths.join(', ')}; its version was published and this machine's version is kept under ${result.quarantined.ref}. gbrain doctor lists it (quarantined_changes).\n`);
}
if (result.superseded_remote_paths && !json) {
process.stderr.write(`[gbrain notice] kept this machine's version of ${result.superseded_remote_paths.join(', ')}: the remote held a version this checkout had already replaced. See docs/guides/shared-checkout-git.md#conflicts.\n`);
}
if (result.outcome === 'pushed_checkout_lagging' && !json) {
process.stderr.write(`[gbrain notice] the push landed but this checkout was not advanced: ${result.lagging_reason}. The next commit-push or --pull catches it up.\n`);
}
return 0;
} catch (e) {
const code = (e as { code?: string }).code;
let failed = e as { code?: string | null; detail?: string | null };
if (code === 'commit_paths_skipped' || code === 'writer_coordinator_required') {
// GST-2116: the other named paths may have been pushed before the run failed, or their push failed (`publish`); the push log records either.
try {
const d = JSON.parse(String((e as { detail?: string }).detail ?? '{}')) as { dry_run?: boolean; pushed?: string; branch?: string; committed?: string | null;
skipped?: Array<{ path: string; reason: string; why?: string }>; publish?: { code: string | null; detail: string | null } };
if (d.pushed && d.branch) appendPushLog('ok', d.branch, d.pushed);
if (d.skipped?.length && d.branch && !d.dry_run) appendPushLog('skipped', d.branch, d.committed ?? '', `${code}: ${d.skipped.map(s => `${s.path} (${s.reason}${s.why ? `: ${s.why}` : ''})`).join('; ')}`);
if (d.publish) failed = d.publish;
} catch { /* best-effort */ }
}
if (failed.code === 'push_unconfirmed' || failed.code === 'integrate_conflict' || failed.code === 'commit_outside_source_root'
|| failed.code === 'publish_secret_found' || failed.code === 'publish_scan_unreadable' || failed.code === 'push_credential_refused') {
try {
const bi = args.indexOf('--branch');
const branch = bi !== -1 && args[bi + 1] ? args[bi + 1].replace(/^refs\/heads\//, '') : currentBranchOf(args);
if (failed.code === 'push_credential_refused') {
const d = JSON.parse(String(failed.detail ?? '{}')) as { commit?: string; kind?: string; username?: string | null; helpers?: Array<{ helper: string; answered: boolean }> };
const answered = d.helpers?.find(h => h.answered);
appendPushLog('refused', branch, d.commit ?? '', `push_credential_refused: the host refused the credential git used (${d.kind === 'not_found' ? 'repository not found, HTTP 404' : 'HTTP 403'}${answered ? `, from ${answered.helper}${d.username ? ` for ${d.username}` : ''}` : ''})`);
} else if (failed.code.startsWith('publish_')) appendPushLog('refused', branch, '', failed.code);
else appendPushLog(failed.code === 'integrate_conflict' ? 'conflict' : 'local-only', branch, failed.detail ?? '');
} catch { /* best-effort */ }
}
return writeCliError(e, 'git commit-push', { json });
}
}
function runGuard(p: Parsed): number {
if (p.install && p.uninstall) throw opError('commit_paths_invalid', '--install and --uninstall do not combine.', 'Pass one of them, or neither for the status.');
const repo = checkoutRoot(p.path ?? process.cwd());
const s = p.install ? installGuard(repo) : p.uninstall ? uninstallGuard(repo) : { ...guardStatus(repo), changed: false };
emit(p.json, { ...s }, p.install ? `commit guard ${s.changed ? 'installed' : 'already current'}: ${s.hook}`
: p.uninstall ? (s.changed ? `commit guard removed: ${s.hook}` : 'commit guard was not installed')
: s.installed ? `commit guard installed: ${s.hook}` : s.foreign ? `not installed; ${s.hook} is another tool's hook` : 'commit guard not installed (gbrain git guard --install)');
return 0;
}
function currentBranchOf(args: string[]): string {
const i = args.findIndex(a => a === '--path' || a === '--repo');
const dir = i !== -1 ? args[i + 1] : process.cwd();
return execFileSync('git', ['-C', dir, 'symbolic-ref', '--quiet', '--short', 'HEAD'], { env: gitChildEnv({ ...GIT_ENV }), stdio: ['ignore', 'pipe', 'ignore'] }).toString().trim();
}