Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
27.3 KB
Raw Blame
import { assertUnmanagedCanonicalWriter } from './persistence/maintenance.ts';
import { managedPersistenceEnabled } from './persistence/ownership.ts';
/**
 * Destructive operation guard — v0.26.5
 *
 * Protects against accidental data loss in gbrain by requiring explicit
 * confirmation for operations that cascade-delete pages, chunks, or embeddings.
 *
 * Three layers:
 *   1. Impact preview — always shown before destructive actions
 *   2. Confirmation gate — requires --confirm-destructive or interactive "type source name"
 *   3. Soft-delete with TTL — sources are tombstoned for 72h before permanent deletion
 *
 * Design principle: the blast radius should be visible BEFORE you pull the trigger,
 * and recoverable AFTER you pull it (within a grace period).
 */

import type { BrainEngine } from './engine.ts';
import { SOURCE_CONFIG_OBJECT_SQL } from './source-config-sql.ts';
import { rmSync, lstatSync, realpathSync } from 'node:fs';
import { resolve as resolvePath } from 'node:path';
import { isPathContained } from './path-confine.ts';
import { defaultCloneDir } from './sources-ops.ts';
import { gbrainPath } from './config.ts';
import { isMissingSchemaObject } from './utils.ts';
import { deleteSourceRow, EXPIRED_ARCHIVE_SQL, UNVERIFIED_ARCHIVE_SQL, unverifiedArchiveReason } from './source-delete.ts';
import { ItemRun } from './item-failure.ts';
import { OperationError } from './ops/contract.ts';
import { cliRenderContext, renderAction, type RenderedAction } from './agent-output.ts';

// ── Types ───────────────────────────────────────────────────

export interface DestructiveImpact {
  sourceId: string;
  sourceName: string;
  pageCount: number;
  chunkCount: number;
  embeddingCount: number;
  fileCount: number;
  /**
   * PR6 D5b: count of ALL OAuth clients (live AND soft-deleted — the FK is
   * physical, ON DELETE RESTRICT ignores deleted_at) whose source_id
   * references this source. A hard delete with referents raises a raw FK
   * violation — the preview surfaces the block before the trigger is pulled.
   * Optional so hand-built impact literals (tests, older callers) stay valid.
   */
  oauthClientCount?: number;
  /**
   * cathedral-6: count of hot-memory facts in the source. Facts are the
   * primary agent write lane — a revoked agent's workspace can hold facts
   * with ZERO pages, so a pages-only preview would say "safe to remove"
   * while the delete cascades the agent's memory away. Optional so
   * hand-built impact literals (tests, older callers) stay valid; consumers
   * read it as `?? 0`.
   */
  factCount?: number;
  /** Human-readable summary line */
  summary: string;
}

/** An OAuth client row that references a source via oauth_clients.source_id.
 * `deleted` marks soft-deleted (revoked-but-retained) rows — the FK is
 * PHYSICAL (ON DELETE RESTRICT ignores deleted_at), so they block too. */
export interface SourceClientReferent {
  clientId: string;
  clientName: string;
  deleted: boolean;
}

export interface SoftDeletedSource {
  id: string;
  name: string;
  deletedAt: Date;
  expiresAt: Date;
  pageCount: number;
}

// ── Constants ───────────────────────────────────────────────

/** Hours before a soft-deleted source is permanently purged. */
export const SOFT_DELETE_TTL_HOURS = 72;

/** Threshold: operations affecting this many pages or more require confirmation. */
export const CONFIRM_THRESHOLD_PAGES = 1;

// ── FK-RESTRICT lifecycle (PR6 D5b) ─────────────────────────

/**
 * ALL OAuth clients referencing a source via oauth_clients.source_id
 * (ON DELETE RESTRICT — these rows BLOCK a hard delete of the source).
 * PHYSICAL semantics: soft-deleted rows (admin revoke does UPDATE SET
 * deleted_at) still hold the FK, so they are returned too, tagged
 * `deleted: true`, and the guidance splits per row. Pre-migration brains
 * without the deleted_at column fall back to all referents (same
 * 42703-retry idiom as oauth-provider.ts) tagged live; brains without
 * the oauth_clients table — or without the source_id column (no column
 * ⇒ no FK ⇒ no referents) — have no referents by construction.
 */
export async function clientsReferencingSource(
  engine: BrainEngine,
  sourceId: string,
): Promise<SourceClientReferent[]> {
  try {
    const rows = await engine.executeRaw<{ client_id: string; client_name: string; deleted: boolean }>(
      `SELECT client_id, client_name, (deleted_at IS NOT NULL) AS deleted
       FROM oauth_clients
       WHERE source_id = $1
       ORDER BY client_id`,
      [sourceId],
    );
    return rows.map((r) => ({ clientId: r.client_id, clientName: r.client_name, deleted: r.deleted === true }));
  } catch (e) {
    if (isMissingSchemaObject(e, 'table', 'oauth_clients')) return [];
    // The primary query references BOTH optional columns; the strict
    // predicate tells them apart by the column the error names.
    if (isMissingSchemaObject(e, 'column', 'source_id')) return [];
    if (!isMissingSchemaObject(e, 'column', 'deleted_at')) throw e;
    try {
      const rows = await engine.executeRaw<{ client_id: string; client_name: string }>(
        `SELECT client_id, client_name FROM oauth_clients
         WHERE source_id = $1
         ORDER BY client_id`,
        [sourceId],
      );
      return rows.map((r) => ({ clientId: r.client_id, clientName: r.client_name, deleted: false }));
    } catch (e2) {
      // The fallback's only optional column is source_id — no column ⇒ no FK.
      if (isMissingSchemaObject(e2, 'column', 'source_id')) return [];
      throw e2;
    }
  }
}

/**
 * Refusal message for `sources remove` / `sources purge <id>` when live OAuth
 * clients still reference the source. Built here (not in sources.ts — that
 * file is module-size-ratcheted) so both arms print identical guidance
 * instead of letting the raw FK violation surface.
 */
export function formatClientReferentsBlock(
  sourceId: string,
  referents: SourceClientReferent[],
): string {
  const live = referents.filter((r) => !r.deleted);
  const dead = referents.filter((r) => r.deleted);
  const lines: string[] = [
    ``,
    `Cannot delete source "${sourceId}": ${referents.length} OAuth client(s) reference this source`,
    `(oauth_clients.source_id is ON DELETE RESTRICT — the delete would fail at the database).`,
    ``,
  ];
  for (const r of referents) {
    lines.push(`  - ${r.clientName} (${r.clientId})${r.deleted ? '  [revoked, retained]' : ''}`);
  }
  if (live.length > 0) {
    lines.push(``);
    lines.push(`Revoke each live client first (hard delete), then retry:`);
    for (const r of live) {
      lines.push(`  gbrain auth revoke-client "${r.clientId}"`);
    }
  }
  if (dead.length > 0) {
    lines.push(``);
    lines.push(`Revoked-but-retained rows still block the FK — \`gbrain auth revoke-client "<id>"\` hard-deletes them:`);
    for (const r of dead) {
      lines.push(`  gbrain auth revoke-client "${r.clientId}"`);
    }
  }
  lines.push(``);
  return lines.join('\n');
}

// ── Impact Assessment ───────────────────────────────────────

/**
 * Compute the blast radius of deleting a source.
 */
export async function assessDestructiveImpact(
  engine: BrainEngine,
  sourceId: string,
): Promise<DestructiveImpact | null> {
  // Fetch source metadata
  const sources = await engine.executeRaw<{ id: string; name: string }>(
    `SELECT id, name FROM sources WHERE id = $1`,
    [sourceId],
  );
  if (sources.length === 0) return null;

  const src = sources[0];

  // Count pages
  const pageRows = await engine.executeRaw<{ n: number }>(
    `SELECT COUNT(*)::int AS n FROM pages WHERE source_id = $1`,
    [sourceId],
  );
  const pageCount = pageRows[0]?.n ?? 0;

  // Count chunks
  const chunkRows = await engine.executeRaw<{ n: number }>(
    `SELECT COUNT(*)::int AS n FROM content_chunks cc
     JOIN pages p ON cc.page_id = p.id
     WHERE p.source_id = $1`,
    [sourceId],
  );
  const chunkCount = chunkRows[0]?.n ?? 0;

  // Count embeddings (chunks with non-null embedding vectors)
  const embedRows = await engine.executeRaw<{ n: number }>(
    `SELECT COUNT(*)::int AS n FROM content_chunks cc
     JOIN pages p ON cc.page_id = p.id
     WHERE p.source_id = $1 AND cc.embedding IS NOT NULL`,
    [sourceId],
  );
  const embeddingCount = embedRows[0]?.n ?? 0;

  // Count files in storage (if any). PGLite has no `files` table — that
  // surface is Postgres-only (CLAUDE.md: "No files table" for PGLite). Probe
  // the table existence via information_schema so this works on both engines.
  let fileCount = 0;
  const filesTableRows = await engine.executeRaw<{ exists: boolean }>(
    `SELECT EXISTS (
       SELECT 1 FROM information_schema.tables
       WHERE table_schema = 'public' AND table_name = 'files'
     ) AS exists`,
  );
  if (filesTableRows[0]?.exists) {
    const fileRows = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM files WHERE source_id = $1`,
      [sourceId],
    );
    fileCount = fileRows[0]?.n ?? 0;
  }

  // cathedral-6: count hot-memory facts. A revoked agent's workspace can
  // hold facts with zero pages — those are data at risk, not "no data".
  // Tolerant of a pre-v0.31 brain without the facts table (same degrade
  // posture as clientsReferencingSource).
  let factCount = 0;
  try {
    const factRows = await engine.executeRaw<{ n: number }>(
      `SELECT COUNT(*)::int AS n FROM facts WHERE source_id = $1`,
      [sourceId],
    );
    factCount = factRows[0]?.n ?? 0;
  } catch (e) {
    if (!isMissingSchemaObject(e, 'table', 'facts')) throw e;
  }

  // PR6 D5b: fold the FK-RESTRICT referent count into the preview so the
  // operator sees the block BEFORE pulling the trigger.
  const oauthClientCount = (await clientsReferencingSource(engine, sourceId)).length;

  const parts: string[] = [];
  if (pageCount > 0) parts.push(`${pageCount.toLocaleString()} pages`);
  if (chunkCount > 0) parts.push(`${chunkCount.toLocaleString()} chunks`);
  if (embeddingCount > 0) parts.push(`${embeddingCount.toLocaleString()} embeddings`);
  if (fileCount > 0) parts.push(`${fileCount.toLocaleString()} files`);
  if (factCount > 0) parts.push(`${factCount.toLocaleString()} facts`);

  const summary = parts.length > 0
    ? `⚠️  This will permanently delete: ${parts.join(', ')}`
    : `Source "${sourceId}" has no data (safe to remove).`;

  return {
    sourceId,
    sourceName: src.name,
    pageCount,
    chunkCount,
    embeddingCount,
    fileCount,
    factCount,
    oauthClientCount,
    summary,
  };
}

// ── Confirmation Gate ───────────────────────────────────────

/**
 * Check whether the caller has provided sufficient confirmation for a
 * destructive operation. Returns an error message if blocked, or null if OK.
 */
export function checkDestructiveConfirmation(
  impact: DestructiveImpact,
  opts: {
    yes?: boolean;
    confirmDestructive?: boolean;
    dryRun?: boolean;
  },
): string | null {
  // Dry run always passes (no side effects)
  if (opts.dryRun) return null;

  // No data = no risk. Facts gate exactly like pages (cathedral-6): a
  // fact-only source (revoked agent workspace) is data at stake, not empty.
  if (impact.pageCount === 0 && impact.chunkCount === 0 && impact.fileCount === 0
    && (impact.factCount ?? 0) === 0) {
    return null;
  }

  // --confirm-destructive is the explicit "I know what I'm doing" flag
  if (opts.confirmDestructive) return null;

  // --yes alone is NOT sufficient for destructive operations with data.
  // This is the key behavior change: --yes used to be enough, now you
  // need --confirm-destructive when there's actual data at stake. Facts
  // mirror pages here too — --yes never bypasses a fact-holding source.
  if (opts.yes && impact.pageCount === 0 && (impact.factCount ?? 0) === 0) return null;

  return (
    `\n${impact.summary}\n\n` +
    `To proceed, pass --confirm-destructive (or use soft-delete: gbrain sources archive ${impact.sourceId}).\n` +
    `To preview without side effects: --dry-run`
  );
}

// ── Soft Delete ─────────────────────────────────────────────

/**
 * Soft-delete a source: mark `archived = true` with a 72h TTL. Pages remain
 * in DB; the source is hidden from search via `buildVisibilityClause` and
 * federation is disabled via the existing `config.federated` JSONB key. After
 * TTL expires, the autopilot purge phase or manual `gbrain sources purge`
 * permanently removes the row (cascade delete to pages + chunks).
 *
 * v0.26.5: archive state moved from `config` JSONB keys to real columns
 * (`archived`, `archived_at`, `archive_expires_at`). Migration v34 backfills
 * pre-v0.26.5 rows. Faster filter, no reserved-key footgun. The `federated`
 * key stays in JSONB because federation has its own toggle path.
 */
export async function softDeleteSource(
  engine: BrainEngine,
  sourceId: string,
): Promise<SoftDeletedSource | null> {
  if(await managedPersistenceEnabled(engine)){
    const {runManagedSourceLifecycle}=await import('./persistence/source-lifecycle.ts');
    const result=await runManagedSourceLifecycle(engine,{operation:'archive',sourceId});
    if(result.noop)return null;
    const [row]=await engine.executeRaw<{name:string;archived_at:string;archive_expires_at:string;n:number}>(`SELECT name,archived_at,archive_expires_at,
      (SELECT count(*)::integer FROM pages WHERE source_id=$1) AS n FROM sources WHERE id=$1`,[sourceId]);
    return row?{id:sourceId,name:row.name,deletedAt:new Date(row.archived_at),expiresAt:new Date(row.archive_expires_at),pageCount:row.n}:null;
  }
  await assertUnmanagedCanonicalWriter(engine, 'sources archive');
  // Atomic: only flip rows that are currently active. Returns the metadata
  // we need without a follow-up SELECT. RETURNING projects the columns the
  // caller cares about; pageCount is a separate count.
  const expiresClause = `now() + (${SOFT_DELETE_TTL_HOURS} || ' hours')::interval`;
  const rows = await engine.executeRaw<{ id: string; name: string; archived_at: string; archive_expires_at: string }>(
    `UPDATE sources
     SET archived = true,
         archived_at = now(),
         archive_expires_at = ${expiresClause},
         config = ${SOURCE_CONFIG_OBJECT_SQL} || '{"federated": false}'::jsonb
     WHERE id = $1 AND archived = false
     RETURNING id, name, archived_at, archive_expires_at`,
    [sourceId],
  );
  if (rows.length === 0) return null;
  const row = rows[0];

  const pageRows = await engine.executeRaw<{ n: number }>(
    `SELECT COUNT(*)::int AS n FROM pages WHERE source_id = $1`,
    [sourceId],
  );
  const pageCount = pageRows[0]?.n ?? 0;

  return {
    id: sourceId,
    name: row.name,
    deletedAt: new Date(row.archived_at),
    expiresAt: new Date(row.archive_expires_at),
    pageCount,
  };
}

/**
 * Restore a soft-deleted source (un-archive). Returns true iff a row was
 * restored. Idempotent-as-false on "already active" or "not found".
 *
 * v0.26.5: clears the column-based archive state and (by default) flips
 * `config.federated = true` so the source re-enters federated search. The
 * `--no-federate` operator opt-out keeps federation disabled.
 */
export async function restoreSource(
  engine: BrainEngine,
  sourceId: string,
  refederate: boolean = true,
): Promise<boolean> {
  if(await managedPersistenceEnabled(engine)){
    const {runManagedSourceLifecycle}=await import('./persistence/source-lifecycle.ts');
    const result=await runManagedSourceLifecycle(engine,{operation:'restore',sourceId,refederate});return !result.noop;
  }
  await assertUnmanagedCanonicalWriter(engine, 'sources restore');
  // GST-1113: a scope source is never federated, so restore leaves it unfederated.
  const federate = refederate && !(await (await import('./access/attest-sources.ts')).markedScopeSources(engine, [sourceId])).size;
  const federatedPatch = federate ? '{"federated": true}' : '{"federated": false}';
  const rows = await engine.executeRaw<{ id: string }>(
    `UPDATE sources
     SET archived = false,
         archived_at = NULL,
         archive_expires_at = NULL,
         config = ${SOURCE_CONFIG_OBJECT_SQL} || $1::text::jsonb
     WHERE id = $2 AND archived = true
     RETURNING id`,
    [federatedPatch, sourceId],
  );
  return rows.length > 0;
}

/**
 * List all soft-deleted (archived) sources.
 *
 * v0.26.5: filters via the real `archived` column instead of JSONB
 * containment. Faster, indexable on demand, no JSONB reserved-key collision
 * with future config schemas.
 */
export async function listArchivedSources(
  engine: BrainEngine,
): Promise<SoftDeletedSource[]> {
  const rows = await engine.executeRaw<{
    id: string;
    name: string;
    archived_at: string;
    archive_expires_at: string;
    page_count: number;
  }>(
    `SELECT
        s.id, s.name, s.archived_at, s.archive_expires_at,
        COALESCE((SELECT COUNT(*)::int FROM pages p WHERE p.source_id = s.id), 0) AS page_count
     FROM sources s
     WHERE s.archived = true
     ORDER BY s.archived_at DESC`,
  );

  return rows.map((row) => ({
    id: row.id,
    name: row.name,
    deletedAt: new Date(row.archived_at),
    expiresAt: new Date(row.archive_expires_at),
    pageCount: row.page_count,
  }));
}

/** Result of a purge sweep: what deleted, and what an FK deliberately held. */
export interface PurgeExpiredResult {
  /** Source ids permanently deleted this sweep. */
  purged: string[];
  /**
   * Sources past TTL that could NOT be deleted because a RESTRICT FK still
   * references them — today that is migration v64's oauth_clients.source_id
   * ON DELETE RESTRICT, which intentionally refuses source deletion until
   * every client is revoked-and-purged or re-scoped. Blocked is a policy
   * outcome, not an error: the sweep reports it and moves on.
   */
  blocked: Array<{
    id: string;
    reason: string;
    /** GBRA-130 A-50 (unmanaged): the classified code of a delete that failed for this source alone (statement_timeout, lock_timeout, ...). */
    code?: string;
    /** With `code`: the manual purge of this source, for the user to run (`next: tell_user_to_run`). */
    fix?: RenderedAction;
  }>;
}

/**
 * Permanently purge sources whose 72h TTL has expired. Cascades to pages
 * (and content_chunks via existing FKs).
 *
 * v0.26.5 used a single set-based DELETE; gbrain#4115 showed one FK-blocked
 * source (a revoked-but-retained oauth_client under v64's ON DELETE RESTRICT)
 * aborted the whole statement, wedging the nightly purge forever. The sweep is
 * now per-source: each DELETE re-checks the expiry predicate (no
 * select-then-delete race with a concurrent restore), ONLY the FK-restriction
 * error class (SQLSTATE 23503) is treated as blocked-and-reported.
 * GBRA-130 A-50: any other failure of one source's delete is classified
 * (classifyItemFailure via ItemRun): an item-scoped one (a statement timeout on
 * a large source's cascade, a lock timeout) is reported in `blocked` with its
 * code and the manual purge as its fix, and the sweep continues; a run-scoped
 * one, or a sweep where most sources fail, re-raises. (Supersedes #4238's set-based NOT-EXISTS variant at
 * merge: the 23503 catch covers ANY current or future RESTRICT FK — including
 * soft-deleted oauth_clients, since the FK is physical — not just the one
 * table an EXISTS prefilter names, and the structured {purged, blocked}
 * return is what every caller + test in this tree consumes.)
 */
async function unverifiedArchives(engine: BrainEngine): Promise<PurgeExpiredResult['blocked']> {
  const rows = await engine.executeRaw<{ id: string }>(`SELECT id FROM sources WHERE ${UNVERIFIED_ARCHIVE_SQL} ORDER BY id`);
  return rows.map(({ id }) => ({ id, reason: unverifiedArchiveReason(id) }));
}

export async function purgeExpiredSources(
  engine: BrainEngine,
): Promise<PurgeExpiredResult> {
  if(await managedPersistenceEnabled(engine)){
    const {runManagedSourceLifecycle}=await import('./persistence/source-lifecycle.ts');
    const candidates=await engine.executeRaw<{id:string;incarnation:string}>(`SELECT id,incarnation FROM sources WHERE ${EXPIRED_ARCHIVE_SQL} ORDER BY id`);
    const result:PurgeExpiredResult={purged:[],blocked:await unverifiedArchives(engine)};
    for(const source of candidates){
      try{const receipt=await runManagedSourceLifecycle(engine,{operation:'purge',sourceId:source.id,expectedIncarnation:source.incarnation,confirmDestructive:true,expiredOnly:true});if(!receipt.noop)result.purged.push(source.id);}
      catch(error){
        const code=error instanceof OperationError&&error.code==='source_pages_remain'?error.code:undefined;
        result.blocked.push({id:source.id,reason:error instanceof Error?error.message:'Source lifecycle could not finish.',...(code?{code,fix:renderAction((error as OperationError).fix!,cliRenderContext())}:{})});
      }
    }
    return result;
  }
  await assertUnmanagedCanonicalWriter(engine, 'sources purge');
  const candidates = await engine.executeRaw<{ id: string; config: unknown; local_path: string | null }>(
    `SELECT id, config, local_path FROM sources WHERE ${EXPIRED_ARCHIVE_SQL} ORDER BY id`,
  );
  const purged: string[] = [];
  const blocked: PurgeExpiredResult['blocked'] = await unverifiedArchives(engine);
  const cloneRoot = gbrainPath('clones');
  const items = new ItemRun('retention.expired_sources');
  for (const candidate of candidates) {
    const { id } = candidate;
    try {
      if (await deleteSourceRow(engine, id, { expiredArchiveOnly: true })) {
        purged.push(id);
        // github-kind mirrors are gbrain-owned only when created at the
        // default clone location. Never recursively delete an altered or
        // symlinked path outside the managed clone root.
        try {
          const cfg = (typeof candidate.config === 'string'
            ? JSON.parse(candidate.config)
            : (candidate.config ?? {})) as Record<string, unknown>;
          if (cfg.kind === 'github' && cfg.gh_managed === true && candidate.local_path) {
            // STRICT containment: isPathContained accepts child === parent, so
            // a corrupt row whose local_path IS the clone root would rm -rf
            // every mirror. Require a real subtree AND pin the gh_managed
            // creation shape — addSource only sets the marker when the dir is
            // exactly defaultCloneDir('<id>-github').
            const strictSubtree =
              isPathContained(candidate.local_path, cloneRoot) &&
              realpathSync(candidate.local_path) !== realpathSync(cloneRoot);
            const expectedShape =
              resolvePath(candidate.local_path) === resolvePath(defaultCloneDir(`${id}-github`));
            if (strictSubtree && expectedShape) {
              const lst = lstatSync(candidate.local_path);
              if (!lst.isSymbolicLink()) {
                rmSync(candidate.local_path, { recursive: true, force: true });
              }
            }
          }
        } catch {
          // Best-effort cleanup; source deletion already completed.
        }
      }
      // 0 rows = restored/already gone between SELECT and DELETE; neither
      // purged nor blocked.
      items.succeed();
    } catch (err) {
      // SQLSTATE 23503 foreign_key_violation — same detection idiom as
      // oauth-provider.ts's delete path for this exact FK.
      if (err instanceof OperationError && err.code === 'source_pages_remain') {
        blocked.push({ id, code: err.code, reason: `${err.message} ${err.suggestion}`, fix: renderAction(err.fix!, cliRenderContext()) });
        continue;
      }
      if ((err as { code?: string })?.code === '23503') {
        blocked.push({
          id,
          reason:
            'still referenced by a RESTRICT foreign key (revoked oauth_client not yet purged? the FK is physical, so soft-deleted clients also block) — ' +
            'review with `gbrain auth clients`, revoke with `gbrain auth revoke-client "<client-id>"`, then retry',
        });
        continue;
      }
      const failure = items.fail(id, err);
      blocked.push({
        id, code: failure.code,
        reason: `its delete failed (${failure.message}); the next retention sweep retries it`,
        fix: renderAction({ argv: ['gbrain', 'sources', 'purge', id, '--confirm-destructive'], consent: ['destructive'], actor: 'user', requires_exclusive: false,
          why: 'Purges this expired archived source by hand, outside the nightly sweep.' }, cliRenderContext()),
      });
    }
  }
  return { purged, blocked };
}

// ── Display Helpers ─────────────────────────────────────────

/**
 * Format an impact assessment for terminal display.
 */
export function formatImpact(impact: DestructiveImpact): string {
  const lines: string[] = [
    ``,
    `╔══════════════════════════════════════════════════════════╗`,
    `║  DESTRUCTIVE OPERATION — Impact Preview                 ║`,
    `╠══════════════════════════════════════════════════════════╣`,
    `║  Source:     ${impact.sourceName.padEnd(42)}║`,
    `║  Source ID:  ${impact.sourceId.padEnd(42)}║`,
    `║                                                          ║`,
    `║  Pages:      ${String(impact.pageCount.toLocaleString()).padEnd(42)}║`,
    `║  Chunks:     ${String(impact.chunkCount.toLocaleString()).padEnd(42)}║`,
    `║  Embeddings: ${String(impact.embeddingCount.toLocaleString()).padEnd(42)}║`,
    `║  Files:      ${String(impact.fileCount.toLocaleString()).padEnd(42)}║`,
    `║  Facts:      ${String((impact.factCount ?? 0).toLocaleString()).padEnd(42)}║`,
    `╠══════════════════════════════════════════════════════════╣`,
    `║  ${impact.summary.padEnd(56)}║`,
    `╚══════════════════════════════════════════════════════════╝`,
    ``,
  ];
  // PR6 D5b: surface the FK-RESTRICT block in the preview. Rendered outside
  // the box (variable-width padding inside would misalign the frame).
  if ((impact.oauthClientCount ?? 0) > 0) {
    lines.push(`⚠️  ${impact.oauthClientCount} OAuth client(s) reference this source — a hard delete is`);
    lines.push(`   blocked (FK RESTRICT) until they are revoked: gbrain auth revoke-client "<client-id>"`);
    lines.push(``);
  }
  return lines.join('\n');
}

export function formatSoftDelete(sd: SoftDeletedSource): string {
  const hours = Math.round((sd.expiresAt.getTime() - Date.now()) / (1000 * 60 * 60));
  return [
    ``,
    `Source "${sd.id}" archived (soft-deleted).`,
    `  ${sd.pageCount.toLocaleString()} pages preserved for ${SOFT_DELETE_TTL_HOURS}h.`,
    `  Expires: ${sd.expiresAt.toISOString()} (~${hours}h from now)`,
    `  Removed from search. Data intact.`,
    ``,
    `  Restore:  gbrain sources restore ${sd.id}`,
    `  Purge now: gbrain sources purge ${sd.id} --confirm-destructive`,
    ``,
  ].join('\n');
}