Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
14.7 KB
Raw Blame
/**
 * Classic sync's upstream watch (GBRA-133 S-58/S-59). A classic source that
 * syncs with pull fast-forwards to its upstream; after an upstream force-push
 * (or local commits beside a moving upstream) that fast-forward fails on every
 * run. This module tells the cases apart and keeps the answer where doctor and
 * the sync result can read it, without ever blocking the sync (sync-upstream.ts
 * keeps the separate freshness observation in the sources.upstream_* columns):
 *
 *   - `upstream_baseline` (sources.config): the last upstream commit the local
 *     checkout contained, recorded before every fetch and after every pull
 *     that fast-forwarded or was already up to date. Only an upstream commit
 *     that is an ancestor of HEAD is recorded, so a rewritten upstream fetched
 *     by an earlier run never replaces the commit it rewrote.
 *   - `upstream_divergence` (sources.config): set when the pull cannot
 *     fast-forward because HEAD and upstream diverged, cleared by the next pull
 *     that fast-forwards or finds nothing to do. Never a sync-failure ledger
 *     row, so it never gates the bookmark; local HEAD keeps syncing.
 *
 * Codes: `upstream_rewritten` (the baseline is not an ancestor of the new
 * upstream: a force-push removed commits) and `upstream_unknown` (no usable
 * baseline, so a force-push cannot be told from local commits) are fixed by
 * `gbrain sources reset-upstream` after the user agrees (a merge would bring
 * back the commits a force-push removed); `upstream_diverged` (local commits
 * beside an upstream that moved forward normally) is fixed by
 * `gbrain git commit-push --pull`. Nothing is classified while a rebase,
 * merge, cherry-pick or revert is in progress in the checkout.
 */
import { existsSync } from 'node:fs';
import { isAbsolute, resolve } from 'node:path';
import { cliRenderContext, renderAction, type Action, type RenderedAction } from './agent-output.ts';
import type { BrainEngine } from './engine.ts';
import { GIT_OPERATION_MARKERS } from './git/commit-push.ts';
import { gitChildEnv } from './git-env.ts';
import { GIT_ENV } from './git-transport.ts';
import { execFileSync } from './spawn.ts';

export const UPSTREAM_BASELINE_KEY = 'upstream_baseline';
export const UPSTREAM_DIVERGENCE_KEY = 'upstream_divergence';
export const UPSTREAM_DOCS = 'docs/guides/troubleshooting.md#upstream-rewritten';

export type UpstreamCode = 'upstream_rewritten' | 'upstream_unknown' | 'upstream_diverged';

export interface UpstreamBaseline { sha: string; tracking_ref: string; recorded_at: string }

/** What the checkout looked like when the pull could not fast-forward. */
export interface UpstreamDivergence {
  code: UpstreamCode;
  source_id: string;
  repo: string;
  branch: string | null;
  tracking_ref: string;
  local: string;
  upstream: string;
  /** The recorded baseline (null for upstream_unknown). */
  previous_upstream: string | null;
  first_seen: string;
  observed_at: string;
}

/** An observation as doctor, sync and sources status report it. */
export interface UpstreamDivergenceReport extends UpstreamDivergence { message: string; fix: Action }

/** The classic sync result with the source's standing upstream report. */
export interface UpstreamResultField { upstream?: UpstreamDivergenceReport }

export interface CheckoutUpstream { head: string; upstream: string; tracking_ref: string; branch: string | null }

const READ_ENV: NodeJS.ProcessEnv = { ...GIT_ENV, GIT_OPTIONAL_LOCKS: '0', LC_ALL: 'C' };

/** Runs git read-only (no optional locks); null when git exits non-zero. */
export function gitRead(root: string, args: string[]): string | null {
  try {
    return execFileSync('git', ['-C', root, ...args], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000, env: gitChildEnv(READ_ENV) }).toString().trim();
  } catch {
    return null;
  }
}

/** `a` is an ancestor of (or equal to) `b`; null when git cannot tell (a missing object). */
export function isAncestor(root: string, a: string, b: string): boolean | null {
  try {
    execFileSync('git', ['-C', root, 'merge-base', '--is-ancestor', a, b], { stdio: ['ignore', 'pipe', 'pipe'], timeout: 30_000, env: gitChildEnv(READ_ENV) });
    return true;
  } catch (e) {
    return (e as { status?: unknown }).status === 1 ? false : null;
  }
}

export function hasCommit(root: string, sha: string): boolean {
  return gitRead(root, ['cat-file', '-e', `${sha}^{commit}`]) !== null;
}

/** HEAD, the branch's upstream commit and tracking ref; null when HEAD is unborn or the branch has no upstream. */
export function readCheckoutUpstream(root: string): CheckoutUpstream | null {
  const head = gitRead(root, ['rev-parse', '--verify', '-q', 'HEAD^{commit}']);
  const trackingRef = gitRead(root, ['rev-parse', '--symbolic-full-name', '@{upstream}']);
  const upstream = trackingRef ? gitRead(root, ['rev-parse', '--verify', '-q', `${trackingRef}^{commit}`]) : null;
  if (!head || !trackingRef || !upstream) return null;
  return { head, upstream, tracking_ref: trackingRef, branch: gitRead(root, ['symbolic-ref', '--short', '-q', 'HEAD']) || null };
}

/** The in-progress git operation marker (rebase-merge, MERGE_HEAD, ...), or null. */
export function gitOperationInProgress(root: string): string | null {
  const paths = gitRead(root, ['rev-parse', ...GIT_OPERATION_MARKERS.flatMap(marker => ['--git-path', marker])])?.split('\n');
  if (!paths) return null;
  return GIT_OPERATION_MARKERS.find((_, i) => paths[i] && existsSync(isAbsolute(paths[i]!) ? paths[i]! : resolve(root, paths[i]!))) ?? null;
}

function parseConfig(raw: unknown): Record<string, unknown> {
  let value = raw;
  if (typeof raw === 'string') try { value = JSON.parse(raw); } catch { value = null; }
  return value && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : {};
}

async function readSourceConfig(engine: BrainEngine, sourceId: string): Promise<Record<string, unknown>> {
  const [row] = await engine.executeRaw<{ config: unknown }>('SELECT config FROM sources WHERE id = $1', [sourceId]);
  return parseConfig(row?.config);
}

const asDivergence = (value: unknown): UpstreamDivergence | null =>
  value && typeof value === 'object' && typeof (value as UpstreamDivergence).code === 'string' && typeof (value as UpstreamDivergence).local === 'string'
    ? value as UpstreamDivergence : null;

export async function readUpstreamBaseline(engine: BrainEngine, sourceId: string): Promise<UpstreamBaseline | null> {
  const value = (await readSourceConfig(engine, sourceId))[UPSTREAM_BASELINE_KEY] as UpstreamBaseline | null | undefined;
  return value && typeof value.sha === 'string' ? value : null;
}

/** Record the checkout's upstream commit as the baseline, only when HEAD contains it. */
export async function writeUpstreamBaseline(engine: BrainEngine, sourceId: string, root: string, state: CheckoutUpstream): Promise<void> {
  if (state.upstream !== state.head && isAncestor(root, state.upstream, state.head) !== true) return;
  if ((await readUpstreamBaseline(engine, sourceId))?.sha === state.upstream) return;
  await engine.updateSourceConfig(sourceId, { [UPSTREAM_BASELINE_KEY]: { sha: state.upstream, tracking_ref: state.tracking_ref, recorded_at: new Date().toISOString() } });
}

export async function clearUpstreamDivergence(engine: BrainEngine, sourceId: string): Promise<void> {
  if ((await readSourceConfig(engine, sourceId))[UPSTREAM_DIVERGENCE_KEY]) await engine.updateSourceConfig(sourceId, { [UPSTREAM_DIVERGENCE_KEY]: null });
}

/** Before a classic sync's fetch: remember the upstream commit the checkout already contains. Best effort; never throws. */
export async function recordUpstreamBeforeFetch(engine: BrainEngine, sourceId: string, root: string): Promise<void> {
  try {
    const state = readCheckoutUpstream(root);
    if (state) await writeUpstreamBaseline(engine, sourceId, root, state);
  } catch { /* the watch never blocks a sync */ }
}

/**
 * After a classic sync's pull. A pull that fast-forwarded or was up to date
 * records the new baseline and clears the observation; a failed pull whose
 * HEAD and upstream diverged is classified and stored. Best effort; never throws.
 */
export async function settleUpstreamAfterPull(engine: BrainEngine, sourceId: string, root: string, pulled: boolean): Promise<UpstreamDivergenceReport | null> {
  try {
    if (pulled) {
      const state = readCheckoutUpstream(root);
      if (state) await writeUpstreamBaseline(engine, sourceId, root, state);
      await clearUpstreamDivergence(engine, sourceId);
      return null;
    }
    if (gitOperationInProgress(root)) return null;
    const state = readCheckoutUpstream(root);
    if (!state || isAncestor(root, state.upstream, state.head) !== false || isAncestor(root, state.head, state.upstream) !== false) return null;
    const config = await readSourceConfig(engine, sourceId);
    const baseline = (config[UPSTREAM_BASELINE_KEY] as UpstreamBaseline | null | undefined)?.sha;
    const known = baseline && hasCommit(root, baseline) ? baseline : null;
    const contained = known ? isAncestor(root, known, state.upstream) : null;
    const code: UpstreamCode = contained === true ? 'upstream_diverged' : contained === false ? 'upstream_rewritten' : 'upstream_unknown';
    const prior = asDivergence(config[UPSTREAM_DIVERGENCE_KEY]);
    const now = new Date().toISOString();
    const same = prior && prior.code === code && prior.local === state.head && prior.upstream === state.upstream;
    const observation: UpstreamDivergence = { code, source_id: sourceId, repo: root, branch: state.branch, tracking_ref: state.tracking_ref,
      local: state.head, upstream: state.upstream, previous_upstream: code === 'upstream_unknown' ? null : known, first_seen: same ? prior.first_seen : now, observed_at: now };
    await engine.updateSourceConfig(sourceId, { [UPSTREAM_DIVERGENCE_KEY]: observation });
    return divergenceReport(observation);
  } catch {
    return null;
  }
}

/** The standing upstream reports of the given (or every) non-archived source. */
export async function readUpstreamDivergences(engine: BrainEngine, sourceIds?: string[]): Promise<UpstreamDivergenceReport[]> {
  const rows = await engine.executeRaw<{ id: string; config: unknown }>('SELECT id, config FROM sources WHERE archived IS NOT TRUE ORDER BY id');
  return rows.filter(row => !sourceIds || sourceIds.includes(row.id))
    .map(row => asDivergence(parseConfig(row.config)[UPSTREAM_DIVERGENCE_KEY]))
    .filter((o): o is UpstreamDivergence => o !== null)
    .map(divergenceReport);
}

export async function readUpstreamDivergence(engine: BrainEngine, sourceId: string): Promise<UpstreamDivergenceReport | null> {
  const observation = asDivergence((await readSourceConfig(engine, sourceId))[UPSTREAM_DIVERGENCE_KEY]);
  return observation ? divergenceReport(observation) : null;
}

const short = (sha: string | null) => (sha ?? '').slice(0, 12);

export function divergenceReport(o: UpstreamDivergence): UpstreamDivergenceReport {
  const where = `Source ${o.source_id} (${o.tracking_ref})`;
  const keeps = `Local HEAD ${short(o.local)} keeps syncing; upstream commits are not imported until this is resolved.`;
  const message = o.code === 'upstream_rewritten'
    ? `${where}: the upstream was rewritten (force-pushed): ${short(o.previous_upstream)}, the upstream commit this checkout last contained, is not in the new upstream ${short(o.upstream)}, so the pull cannot fast-forward. ${keeps}`
    : o.code === 'upstream_unknown'
      ? `${where}: local HEAD ${short(o.local)} and upstream ${short(o.upstream)} have diverged and gbrain has no record of the upstream before this fetch, so it cannot tell a force-push from local commits. ${keeps}`
      : `${where}: this checkout has commits that are not on the upstream, and the upstream moved forward to ${short(o.upstream)}, so the pull cannot fast-forward. ${keeps}`;
  return { ...o, message, fix: upstreamFix(o) };
}

const doctorVerify = { argv: ['gbrain', 'doctor', '--only', 'sync_failures', '--json'] };

function followUpSync(o: UpstreamDivergence): Action {
  return { argv: ['gbrain', 'sync', '--source', o.source_id], consent: [], actor: 'agent', requires_exclusive: false, verify: doctorVerify,
    why: 'The next sync pulls the upstream (now a fast-forward or already up to date), imports its commits and clears the upstream report.' };
}

/** The typed next step: a reset bound to the observed commits (ask the user first), or the shared-checkout pull for plain divergence. */
export function upstreamFix(o: UpstreamDivergence): Action {
  if (o.code === 'upstream_diverged') {
    return { argv: ['gbrain', 'git', 'commit-push', '--pull', '--path', o.repo], consent: [], actor: 'agent', requires_exclusive: false, verify: doctorVerify,
      why: 'Brings the upstream commits in beside the local ones (fast-forward or an in-memory merge under the commit lock); nothing is pushed and no commit is dropped.',
      docs: UPSTREAM_DOCS, then: followUpSync(o) };
  }
  const reset = ['gbrain', 'sources', 'reset-upstream', o.source_id, '--expect-local', o.local, '--expect-upstream', o.upstream];
  return {
    ask_user: true, argv: reset, preview_argv: [...reset, '--dry-run'], consent: ['destructive'], actor: 'agent', requires_exclusive: true, verify: doctorVerify, docs: UPSTREAM_DOCS,
    why: o.code === 'upstream_rewritten'
      ? 'A merge would bring back the commits the force-push removed, so the checkout is reset to the new upstream instead; the reset keeps the old history under a backup ref and refuses local commits that were never on the upstream.'
      : 'Without a record of the old upstream gbrain cannot tell whether the local-only commits were removed by a force-push or never pushed; the reset preview names any commit that was never on the upstream before anything moves.',
    user_message: o.code === 'upstream_rewritten'
      ? `The upstream of source ${o.source_id} was force-pushed. Reset the local checkout to the new upstream ${short(o.upstream)}? The current history (${short(o.local)}) is kept under a backup ref.`
      : `Source ${o.source_id}'s checkout and its upstream have diverged and gbrain cannot tell why. Preview resetting it to the upstream ${short(o.upstream)}? The current history is kept under a backup ref.`,
    then: followUpSync(o),
  };
}

/** The wire form for local CLI JSON (sync --json, sources status --json): the fix rendered with its next step and command. */
export function renderUpstreamDivergence(report: UpstreamDivergenceReport): Omit<UpstreamDivergenceReport, 'fix'> & { fix: RenderedAction } {
  return { ...report, fix: renderAction(report.fix, cliRenderContext()) };
}

/** The stderr line a classic sync prints when it records an observation. */
export function formatUpstreamNotice(report: UpstreamDivergenceReport): string {
  return `Warning [${report.code}]: ${report.message} Next${report.fix.ask_user ? ' (ask the user first)' : ''}: ${report.fix.argv!.join(' ')}. See ${UPSTREAM_DOCS}.`;
}