Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
8.4 KB
Raw Blame
/**
 * default-source-path-check — detect a `default` source whose null
 * `local_path` DEMONSTRABLY breaks the write-through / sync plane.
 *
 * The `default` source is the implicit write-through target for any unscoped
 * `gbrain put` / `gbrain capture` call that doesn't name a `--source`.
 * IMPORTANT: `local_path: null` on the `default` row is NOT an error by
 * itself — it is the designed fallback topology. `resolvePageWriteTarget`
 * (write-through.ts) nests default-source pages under `sync.repo_path` when
 * `default.local_path` is null, and the #2018 leak guard already refuses to
 * write into a path that is another source's own working tree. A fresh
 * `gbrain init` leaves `default.local_path` null on purpose.
 *
 * So this check warns ONLY when the null pointer provably breaks something:
 *
 *   - LEAK-GUARDED FALLBACK: `sync.repo_path` is literally another source's
 *     own `local_path`, so every unscoped write-through for default-source
 *     pages is silently skipped (`source_repo_belongs_to_other_source`).
 *   - UNRESOLVABLE ROOT: default has FILE-BACKED pages (`source_path` set —
 *     they were imported from real files) but neither `default.local_path`
 *     nor a resolvable `sync.repo_path` names the tree they live in, so
 *     write-through, fence writes, and delete-reconcile cannot find them.
 *
 *   - RELATIVE PATH (#7630): a set `local_path`, or with a null one a
 *     `sync.repo_path`, that is not absolute on this host (a legacy ".", or a
 *     path absolute only on another OS). Sync refuses it `sync_anchor_relative`
 *     by the same predicate (`isHostAbsolutePath`).
 *
 * Everything else (no pages yet, resolvable repo fallback, deliberate
 * DB-only brain) reports ok. The repair for a genuinely broken pointer is
 * the non-destructive `gbrain sources set-path default <path>`.
 *
 * Pure assessment helper (no DB/FS access — the caller supplies the
 * gathered inputs) so it is unit-testable, in the same shape as
 * npm-squat-check.ts / pglite-leftovers-check.ts. The gathering wrapper
 * lives on the doctor surface (doctor/checks/default-source-path.ts).
 */
import { isForeignAbsolutePath, isHostAbsolutePath } from './path-confine.ts';

export interface DefaultSourcePathInput {
  /** The `default` sources row, or undefined when no such row exists. */
  defaultSource: { local_path: string | null } | undefined;
  /** Live (deleted_at IS NULL) pages on the default source. */
  livePages: number;
  /** Live default-source pages with a recorded source_path (file-backed). */
  fileBackedPages: number;
  /** The `sync.repo_path` config value, if any. */
  repoPath: string | null;
  /** True when repoPath exists on disk and is a directory. */
  repoPathIsDir: boolean;
  /** A non-default source whose own local_path is or contains repoPath under any spelling (#2018 leak guard, #7203), if any. */
  collidingSourceId: string | null;
  /** Live default-source pages whose source_path also names a live page of collidingSourceId. */
  sharedPages?: number;
}

export interface DefaultSourcePathAssessment {
  status: 'skip' | 'ok' | 'warn';
  message: string;
}

export function assessDefaultSourcePath(
  input: DefaultSourcePathInput,
): DefaultSourcePathAssessment {
  const { defaultSource, livePages, fileBackedPages, repoPath, repoPathIsDir, collidingSourceId, sharedPages = 0 } = input;
  if (!defaultSource) {
    // No `default` row at all is a different, more fundamental problem than
    // this check's scope — leave it to whatever check owns sources-table
    // integrity.
    return { status: 'skip', message: '' };
  }
  if (defaultSource.local_path && isForeignAbsolutePath(defaultSource.local_path)) {
    return {
      status: 'warn',
      message:
        `default source local_path "${defaultSource.local_path}" is not an absolute path on this host (another host sharing this ` +
        'brain may have set it), so sync here refuses it (sync_anchor_relative). If that host owns the brain, sync from there and ' +
        'leave the path alone; otherwise ask the user which directory on this host holds the brain, then run ' +
        '`gbrain sources set-path default <absolute-directory>`.',
    };
  }
  if (defaultSource.local_path && !isHostAbsolutePath(defaultSource.local_path)) {
    return {
      status: 'warn',
      message:
        `default source local_path is the relative path "${defaultSource.local_path}", which names whatever directory ` +
        'gbrain runs from, so sync refuses it (sync_anchor_relative). Ask the user which directory holds the brain, then ' +
        'run `gbrain sources set-path default <absolute-directory>`, or clear the pointer with ' +
        '`gbrain sources set-path default --clear`.',
    };
  }
  if (defaultSource.local_path) {
    return {
      status: 'ok',
      message: `default source local_path is set: ${defaultSource.local_path}`,
    };
  }
  if (repoPath && isForeignAbsolutePath(repoPath)) {
    return {
      status: 'warn',
      message:
        `default source has no local_path and sync.repo_path "${repoPath}" is not an absolute path on this host (another host ` +
        'sharing this brain may have set it), so default-source page writes here skip the repository and sync refuses it. If ' +
        'that host owns the brain, sync from there and leave the path alone; otherwise ask the user which directory on this ' +
        'host holds the brain, then run `gbrain sources set-path default <absolute-directory>`.',
    };
  }
  if (repoPath && !isHostAbsolutePath(repoPath)) {
    return {
      status: 'warn',
      message:
        `default source has no local_path and sync.repo_path is the relative path "${repoPath}", which names whatever ` +
        'directory gbrain runs from, so default-source page writes skip the repository. Ask the user which directory holds ' +
        'the brain, then run `gbrain sources set-path default <absolute-directory>` (or ' +
        '`gbrain config set sync.repo_path <absolute-directory>`).',
    };
  }
  // null local_path — the designed fallback topology. Only warn when the
  // fallback demonstrably fails for pages that actually route through it.
  if (livePages === 0) {
    return {
      status: 'ok',
      message:
        'default source has no local_path and no pages — nothing routes through it yet ' +
        '(the sync.repo_path fallback applies when pages arrive).',
    };
  }
  const rootResolvable = Boolean(repoPath) && repoPathIsDir;
  if (rootResolvable && collidingSourceId) {
    return {
      status: 'warn',
      message:
        `default source has local_path: null and sync.repo_path (${repoPath}) is, or lies inside, source ` +
        `"${collidingSourceId}"'s own working tree — the #2018 leak guard silently SKIPS every ` +
        `unscoped write-through for the ${livePages} default-source page(s), so \`gbrain put\`/` +
        '`gbrain capture` writes never reach disk. Fix with `gbrain sources set-path default <path>` ' +
        '(non-destructive pointer repair).' +
        (sharedPages > 0
          ? ` ${sharedPages} default-source page(s) share a file path with a live "${collidingSourceId}" page: an earlier ` +
            `write-through under another spelling of this path (a symlink, a trailing slash, a case or /private alias) may have ` +
            `written them into "${collidingSourceId}"'s tree, where its sync imported them as its own pages. Compare those files ` +
            'with their default-source pages before deleting anything; nothing was changed.'
          : ''),
    };
  }
  if (rootResolvable) {
    return {
      status: 'ok',
      message:
        `default source has no local_path; its ${livePages} page(s) write through ` +
        `sync.repo_path (${repoPath}) — the designed fallback topology.`,
    };
  }
  if (fileBackedPages > 0) {
    return {
      status: 'warn',
      message:
        `default source has local_path: null and no resolvable sync.repo_path ` +
        `(${repoPath ? `set to ${repoPath}, which is not a directory on disk` : 'not set'}), ` +
        `but ${fileBackedPages} of its ${livePages} page(s) are file-backed (source_path recorded) — ` +
        'write-through, fence writes, and delete-reconcile cannot locate their files. ' +
        'Fix with `gbrain sources set-path default <path>` (non-destructive pointer repair).',
    };
  }
  return {
    status: 'ok',
    message:
      `default source is DB-only (no local_path, no resolvable sync.repo_path, ` +
      `${livePages} page(s) with no file of record) — nothing demonstrably broken.`,
  };
}