gstack/bin/gstack-brain-cache

#!/usr/bin/env bun
/**
 * gstack-brain-cache — three-tier cache for brain-aware planning skills.
 *
 * Subcommands:
 *   get <entity-name> [--project <slug>]      — return digest content; refresh if stale
 *   refresh [--full] [--entity X] [--project <slug>]  — force refresh one or all
 *   invalidate <entity-name> [--project <slug>]  — mark stale; next get triggers cold
 *   digest <entity-slug>                       — compress a brain page slug to digest
 *   meta [--project <slug>]                    — print _meta.json
 *
 * (Later commits add: bootstrap [T2b], list [T18], purge [T18], retention sweep [T18].)
 *
 * Cache layout:
 *   ~/.gstack/brain-cache/                     ← cross-project (user-profile only)
 *   ~/.gstack/projects/<slug>/brain-cache/     ← per-project (everything else)
 *
 * Atomic writes via .tmp + rename. Stale-but-usable fallback when brain
 * unreachable. Concurrent-refresh dedup is a follow-up commit (T15).
 */

import { existsSync, mkdirSync, readFileSync, writeFileSync, renameSync, statSync, unlinkSync, readdirSync, openSync, closeSync } from 'fs';
import { join, dirname } from 'path';
import { homedir, hostname } from 'os';
import { spawnSync } from 'child_process';
import { execGbrainJson, spawnGbrain } from '../lib/gbrain-exec';
import {
  BRAIN_CACHE_ENTITIES,
  CACHE_REFRESH_LOCK_TIMEOUT_MS,
  GSTACK_SCHEMA_PACK_NAME,
  GSTACK_SCHEMA_PACK_VERSION,
  SALIENCE_DEFAULT_ALLOWLIST,
  type BrainCacheEntity,
} from '../scripts/brain-cache-spec';

// ──────────────────────────────────────────────────────────────────────────
// Paths + meta
// ──────────────────────────────────────────────────────────────────────────

const GSTACK_HOME = process.env.GSTACK_HOME || join(homedir(), '.gstack');

interface CacheMeta {
  /** Version of the schema pack the cache was built against. Mismatch → full rebuild. */
  schema_version: string;
  /** SHA8 hash of the brain MCP endpoint URL (or 'local' for on-disk engines). */
  endpoint_hash: string;
  /** Per-entity last-refresh epoch ms. Absent → never refreshed. */
  last_refresh: Record<string, number>;
  /** Per-entity last-attempt epoch ms (even if attempt failed). For stale-but-usable diagnostics. */
  last_attempt?: Record<string, number>;
}

/** Returns the directory holding a given entity's cache file. */
export function entityDir(entity: BrainCacheEntity, projectSlug: string | null): string {
  if (entity.scope === 'cross-project') {
    return join(GSTACK_HOME, 'brain-cache');
  }
  if (!projectSlug) {
    throw new Error(`Per-project entity needs a project slug: ${entity.file}`);
  }
  return join(GSTACK_HOME, 'projects', projectSlug, 'brain-cache');
}

/** Returns the path to the cache file for a given entity. */
export function entityPath(entityName: string, projectSlug: string | null): string {
  const entity = BRAIN_CACHE_ENTITIES[entityName];
  if (!entity) throw new Error(`Unknown brain cache entity: ${entityName}`);
  return join(entityDir(entity, projectSlug), entity.file);
}

/** Returns the path to the _meta.json for a given scope. */
export function metaPath(scope: 'cross-project' | 'per-project', projectSlug: string | null): string {
  if (scope === 'cross-project') {
    return join(GSTACK_HOME, 'brain-cache', '_meta.json');
  }
  if (!projectSlug) throw new Error('Per-project meta needs a project slug');
  return join(GSTACK_HOME, 'projects', projectSlug, 'brain-cache', '_meta.json');
}

function loadMeta(scope: 'cross-project' | 'per-project', projectSlug: string | null): CacheMeta {
  const path = metaPath(scope, projectSlug);
  if (!existsSync(path)) {
    return { schema_version: GSTACK_SCHEMA_PACK_VERSION, endpoint_hash: detectEndpointHash(), last_refresh: {}, last_attempt: {} };
  }
  try {
    const parsed = JSON.parse(readFileSync(path, 'utf-8')) as unknown;
    // #1879: a valid JSON file can still be the wrong shape. JSON.parse can return
    // null/array/string/number, and a partial object can omit last_refresh — three
    // consumers (isStale, cmdInvalidate, refreshEntity) dereference meta.last_refresh
    // unguarded and crash with a TypeError.
    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
      return { schema_version: GSTACK_SCHEMA_PACK_VERSION, endpoint_hash: detectEndpointHash(), last_refresh: {}, last_attempt: {} };
    }
    const meta = parsed as CacheMeta;
    // Normalize ONLY the dereferenced maps. Do NOT default schema_version /
    // endpoint_hash — leaving them absent makes schemaVersionMismatch() /
    // endpointSwitched() correctly force a rebuild (missing identity = mismatch =
    // safe). Defaulting them to current values would suppress invalidation and
    // trust a stale file of unknown provenance.
    meta.last_refresh = meta.last_refresh ?? {};
    meta.last_attempt = meta.last_attempt ?? {};
    return meta;
  } catch {
    // Corrupt _meta — start fresh (entries will refresh on next access).
    return { schema_version: GSTACK_SCHEMA_PACK_VERSION, endpoint_hash: detectEndpointHash(), last_refresh: {}, last_attempt: {} };
  }
}

function saveMeta(scope: 'cross-project' | 'per-project', projectSlug: string | null, meta: CacheMeta): void {
  const path = metaPath(scope, projectSlug);
  mkdirSync(dirname(path), { recursive: true });
  atomicWrite(path, JSON.stringify(meta, null, 2));
}

// ──────────────────────────────────────────────────────────────────────────
// Endpoint hash detection
// ──────────────────────────────────────────────────────────────────────────

import { createHash } from 'crypto';

function sha8(input: string): string {
  return createHash('sha256').update(input).digest('hex').slice(0, 8);
}

/**
 * Detects the active brain endpoint (MCP URL or 'local') and returns its
 * stable identity hash. Used to detect when the user switches brains
 * (different endpoint → different cache).
 */
export function detectEndpointHash(): string {
  const claudeJsonPath = join(homedir(), '.claude.json');
  if (existsSync(claudeJsonPath)) {
    try {
      const cfg = JSON.parse(readFileSync(claudeJsonPath, 'utf-8'));
      const gbrainServer = cfg?.mcpServers?.gbrain;
      const url = gbrainServer?.url || gbrainServer?.transport?.url;
      if (typeof url === 'string' && url.length > 0) {
        return sha8(url);
      }
    } catch { /* fall through to local */ }
  }
  // Local engine — no endpoint URL; use a stable literal hash.
  return 'local';
}

// ──────────────────────────────────────────────────────────────────────────
// Atomic write (tmp + rename)
// ──────────────────────────────────────────────────────────────────────────

function atomicWrite(path: string, content: string): void {
  mkdirSync(dirname(path), { recursive: true });
  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
  writeFileSync(tmp, content, 'utf-8');
  renameSync(tmp, path);
}

// ──────────────────────────────────────────────────────────────────────────
// Staleness + refresh logic
// ──────────────────────────────────────────────────────────────────────────

/** Returns true if the cached digest is past its TTL. */
function isStale(entityName: string, meta: CacheMeta): boolean {
  const entity = BRAIN_CACHE_ENTITIES[entityName];
  if (!entity) return true;
  const last = meta.last_refresh[entityName];
  if (!last) return true;
  return Date.now() - last > entity.ttl_ms;
}

/** Returns true if the cache file exists on disk. */
function hasFile(entityName: string, projectSlug: string | null): boolean {
  return existsSync(entityPath(entityName, projectSlug));
}

/** Returns true if schema version recorded in meta differs from current pack version. */
function schemaVersionMismatch(meta: CacheMeta): boolean {
  return meta.schema_version !== GSTACK_SCHEMA_PACK_VERSION;
}

/** Returns true if endpoint hash recorded in meta differs from current detected endpoint. */
function endpointSwitched(meta: CacheMeta): boolean {
  return meta.endpoint_hash !== detectEndpointHash();
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: get
// ──────────────────────────────────────────────────────────────────────────

interface GetResult {
  /** Path to the digest file. */
  path: string;
  /** Cache state: 'warm' (fresh + valid), 'cold-refreshed' (was stale, refreshed inline), 'stale-fallback' (used stale because refresh failed), 'missing' (no cache and no refresh). */
  state: 'warm' | 'cold-refreshed' | 'stale-fallback' | 'missing';
  /** Optional message for diagnostics. */
  message?: string;
}

export function cmdGet(entityName: string, projectSlug: string | null): GetResult {
  const entity = BRAIN_CACHE_ENTITIES[entityName];
  if (!entity) throw new Error(`Unknown entity: ${entityName}`);
  const scope = entity.scope;
  const meta = loadMeta(scope, projectSlug);

  // Schema-version mismatch → full rebuild (D4 A4).
  if (schemaVersionMismatch(meta) || endpointSwitched(meta)) {
    rebuildAllForScope(scope, projectSlug);
    // After rebuild, meta is fresh; fall through to warm path.
    const newMeta = loadMeta(scope, projectSlug);
    if (hasFile(entityName, projectSlug) && !isStale(entityName, newMeta)) {
      return { path: entityPath(entityName, projectSlug), state: 'warm' };
    }
    // Rebuild may have failed for this entity specifically.
    return { path: entityPath(entityName, projectSlug), state: 'missing', message: 'rebuild after schema/endpoint change' };
  }

  if (hasFile(entityName, projectSlug) && !isStale(entityName, meta)) {
    return { path: entityPath(entityName, projectSlug), state: 'warm' };
  }

  // Stale or missing — try cold refresh.
  const refreshed = refreshEntity(entityName, projectSlug);
  if (refreshed) {
    return { path: entityPath(entityName, projectSlug), state: 'cold-refreshed' };
  }
  // Refresh failed. Use stale-but-usable if file exists.
  if (hasFile(entityName, projectSlug)) {
    return { path: entityPath(entityName, projectSlug), state: 'stale-fallback', message: 'brain unreachable; using stale cache' };
  }
  // No cache and no refresh = missing.
  return { path: entityPath(entityName, projectSlug), state: 'missing', message: 'brain unreachable; no cache available' };
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: refresh
// ──────────────────────────────────────────────────────────────────────────

// ──────────────────────────────────────────────────────────────────────────
// Lockfile dedup (T15 / D3)
// ──────────────────────────────────────────────────────────────────────────

/**
 * Returns the lock file path for a project scope. Cross-project entities
 * still lock per-project (the project triggering the refresh holds the lock);
 * concurrent attempts from different projects on cross-project entities
 * serialize naturally because they're rare and the lock window is short.
 */
function lockPath(projectSlug: string | null): string {
  const dir = projectSlug
    ? join(GSTACK_HOME, 'projects', projectSlug, 'brain-cache')
    : join(GSTACK_HOME, 'brain-cache');
  return join(dir, '.refresh.lock');
}

interface LockHandle {
  fd: number;
  path: string;
}

/**
 * Try to acquire the refresh lock. Returns null when another process holds it
 * (and the lock is fresh). Stale locks (process dead OR older than the
 * timeout) are taken over.
 */
function tryAcquireLock(projectSlug: string | null): LockHandle | null {
  const path = lockPath(projectSlug);
  mkdirSync(dirname(path), { recursive: true });

  // If a lock exists, see if it's stale
  if (existsSync(path)) {
    try {
      const raw = readFileSync(path, 'utf-8');
      const lock = JSON.parse(raw) as { pid: number; host: string; ts: number };
      const age = Date.now() - lock.ts;
      const sameHost = lock.host === hostname();
      const processGone = sameHost && lock.pid > 0 && !isPidAlive(lock.pid);
      if (age <= CACHE_REFRESH_LOCK_TIMEOUT_MS && !processGone) {
        return null; // someone else holds a fresh lock
      }
      // Stale: take over
    } catch {
      // Corrupt lock file → take over
    }
  }

  // Write our lock (best-effort O_EXCL via tmp+rename for atomic creation)
  const payload = JSON.stringify({ pid: process.pid, host: hostname(), ts: Date.now() });
  const tmp = `${path}.tmp.${process.pid}.${Date.now()}`;
  try {
    writeFileSync(tmp, payload);
    renameSync(tmp, path);
  } catch (err) {
    return null;
  }

  // Race: another process may have raced us. Re-read and verify ownership.
  try {
    const raw = readFileSync(path, 'utf-8');
    const lock = JSON.parse(raw) as { pid: number; host: string };
    if (lock.pid !== process.pid || lock.host !== hostname()) {
      return null;
    }
  } catch {
    return null;
  }
  return { fd: -1, path };
}

function releaseLock(handle: LockHandle): void {
  try { unlinkSync(handle.path); } catch { /* best effort */ }
}

function isPidAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch (err: any) {
    if (err?.code === 'EPERM') return true; // exists but we don't own it
    return false;
  }
}

/**
 * Run a refresh callback under the project-scoped lock. If another refresh is
 * already in flight, returns 'dedup' and the caller can either wait + retry
 * (the resolver does this) or fall through to stale-but-usable. Stale locks
 * (process dead, or older than CACHE_REFRESH_LOCK_TIMEOUT_MS) are taken over.
 */
export function withRefreshLock<T>(projectSlug: string | null, fn: () => T): T | 'dedup' {
  const handle = tryAcquireLock(projectSlug);
  if (!handle) return 'dedup';
  try {
    return fn();
  } finally {
    releaseLock(handle);
  }
}

/** Refreshes one entity from the brain. Returns true on success. */
export function refreshEntity(entityName: string, projectSlug: string | null): boolean {
  const entity = BRAIN_CACHE_ENTITIES[entityName];
  if (!entity) return false;

  // Mark attempt
  const meta = loadMeta(entity.scope, projectSlug);
  meta.last_attempt = meta.last_attempt || {};
  meta.last_attempt[entityName] = Date.now();

  // Fetch from brain. The actual fetch logic varies per entity — derived digests
  // (recent-decisions, salience) need different queries from direct page reads.
  // For T2a we implement the direct-page path; derived digests get filled in by
  // the resolver / write-back paths in later commits.
  const digestContent = fetchAndCompressEntity(entityName, projectSlug);
  if (digestContent === null) {
    saveMeta(entity.scope, projectSlug, meta);
    return false;
  }

  // Enforce per-entity budget by truncating from end (oldest items live there
  // by convention in our compressor). The per-skill budget is separately
  // enforced at preflight injection time.
  let final = digestContent;
  if (Buffer.byteLength(final, 'utf-8') > entity.budget_bytes) {
    final = truncateToBudget(final, entity.budget_bytes);
  }

  atomicWrite(entityPath(entityName, projectSlug), final);
  meta.last_refresh[entityName] = Date.now();
  // Keep schema/endpoint identity fresh.
  meta.schema_version = GSTACK_SCHEMA_PACK_VERSION;
  meta.endpoint_hash = detectEndpointHash();
  saveMeta(entity.scope, projectSlug, meta);
  return true;
}

/**
 * Refresh all entities for a scope (per-project or cross-project).
 * Used by --full and by schema/endpoint-change rebuilds.
 */
export function refreshAll(projectSlug: string | null): { success: number; failed: number } {
  let success = 0;
  let failed = 0;
  for (const [name, entity] of Object.entries(BRAIN_CACHE_ENTITIES)) {
    // Cross-project entities only refresh when explicitly targeted via no-slug calls
    if (entity.scope === 'cross-project' && projectSlug) continue;
    if (entity.scope === 'per-project' && !projectSlug) continue;
    if (refreshEntity(name, projectSlug)) success++; else failed++;
  }
  return { success, failed };
}

/** Rebuild on schema-version mismatch or endpoint switch. Wipes affected scope first. */
function rebuildAllForScope(scope: 'cross-project' | 'per-project', projectSlug: string | null): void {
  // Wipe files but preserve dir; meta gets fully rewritten by refreshes below.
  for (const [name, entity] of Object.entries(BRAIN_CACHE_ENTITIES)) {
    if (entity.scope !== scope) continue;
    const p = entityPath(name, projectSlug);
    if (existsSync(p)) {
      try { unlinkSync(p); } catch { /* best effort */ }
    }
  }
  // Fresh meta starts here
  const fresh: CacheMeta = {
    schema_version: GSTACK_SCHEMA_PACK_VERSION,
    endpoint_hash: detectEndpointHash(),
    last_refresh: {},
    last_attempt: {},
  };
  saveMeta(scope, projectSlug, fresh);
  // Refresh all entities in this scope
  for (const [name, entity] of Object.entries(BRAIN_CACHE_ENTITIES)) {
    if (entity.scope !== scope) continue;
    refreshEntity(name, projectSlug);
  }
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: invalidate
// ──────────────────────────────────────────────────────────────────────────

export function cmdInvalidate(entityName: string, projectSlug: string | null): void {
  const entity = BRAIN_CACHE_ENTITIES[entityName];
  if (!entity) throw new Error(`Unknown entity: ${entityName}`);
  const meta = loadMeta(entity.scope, projectSlug);
  delete meta.last_refresh[entityName];
  saveMeta(entity.scope, projectSlug, meta);
}

// ──────────────────────────────────────────────────────────────────────────
// Fetch + compress per-entity
// ──────────────────────────────────────────────────────────────────────────

/**
 * Returns the digest markdown content for an entity, or null if the brain is
 * unreachable / the source page doesn't exist.
 *
 * For T2a we implement the entity → page-slug mapping for the simple cases.
 * Derived digests (recent-decisions, salience) get specialized paths.
 */
function fetchAndCompressEntity(entityName: string, projectSlug: string | null): string | null {
  switch (entityName) {
    case 'user-profile':
      return fetchUserProfile();
    case 'product':
      return fetchProduct(projectSlug);
    case 'goals':
      return fetchGoals(projectSlug);
    case 'developer-persona':
      return fetchSimplePage(`gstack/developer-persona/${projectSlug}`);
    case 'brand':
      return fetchSimplePage(`gstack/brand/${projectSlug}`);
    case 'competitive-intel':
      return fetchSimplePage(`gstack/competitive-intel/${projectSlug}`);
    case 'recent-decisions':
      return fetchRecentDecisions(projectSlug);
    case 'salience':
      // D9 salience allowlist applied in T17 commit; T2a returns raw output for now.
      return fetchSalience(projectSlug);
    default:
      return null;
  }
}

/** Generic single-page fetch via `gbrain get`. Returns null on miss/unreachable. */
function fetchSimplePage(slug: string): string | null {
  const result = spawnGbrain(['get', slug, '--json'], { timeout: 10_000 });
  if (result.status !== 0) return null;
  try {
    const page = JSON.parse(result.stdout) as { body?: string; title?: string };
    if (!page?.body) return null;
    return compressPage(slug, page.title || slug, page.body);
  } catch {
    return null;
  }
}

function fetchUserProfile(): string | null {
  // The user-slug discovery is implemented in T16 (D4 A3). For T2a we accept
  // env GSTACK_USER_SLUG as override, fallback to $USER for direct calls.
  const slug = process.env.GSTACK_USER_SLUG || process.env.USER || 'unknown';
  return fetchSimplePage(`gstack/user-profile/${slug}`);
}

function fetchProduct(projectSlug: string | null): string | null {
  if (!projectSlug) return null;
  return fetchSimplePage(`gstack/product/${projectSlug}`);
}

/**
 * Goals are LIST queries: all gstack/goal/<project>/* pages.
 * Compress the top N by recency.
 */
function fetchGoals(projectSlug: string | null): string | null {
  if (!projectSlug) return null;
  const result = execGbrainJson<{ pages?: Array<{ slug: string; title?: string; body?: string }> }>([
    'list-pages',
    '--type', 'gstack/goal',
    '--limit', '10',
    '--json',
  ]);
  if (!result?.pages) return null;
  const goals = result.pages.filter((p) => p.slug?.startsWith(`gstack/goal/${projectSlug}/`));
  if (goals.length === 0) {
    // Empty digest is valid (just header + 'no active goals' line)
    return `# Active goals (project: ${projectSlug})\n\n_No active goals recorded yet._\n`;
  }
  const lines = goals.map((g) => `- [[${g.slug}]] — ${g.title || '(untitled)'}`);
  return `# Active goals (project: ${projectSlug})\n\n${lines.join('\n')}\n`;
}

/**
 * recent-decisions: last 5 gstack/skill-run pages for this project, compressed
 * to one-line summaries.
 */
function fetchRecentDecisions(projectSlug: string | null): string | null {
  if (!projectSlug) return null;
  const result = execGbrainJson<{ pages?: Array<{ slug: string; title?: string }> }>([
    'list-pages',
    '--type', 'gstack/skill-run',
    '--limit', '5',
    '--sort', 'updated_desc',
    '--json',
  ]);
  if (!result?.pages) {
    return `# Recent decisions (project: ${projectSlug})\n\n_No prior skill runs recorded._\n`;
  }
  const lines = result.pages.map((p) => `- ${p.title || p.slug}`);
  return `# Recent decisions (project: ${projectSlug})\n\n${lines.join('\n')}\n`;
}

/**
 * Reads the user's salience allowlist override from gstack-config. If unset,
 * returns SALIENCE_DEFAULT_ALLOWLIST. The override is comma-separated; we
 * trim and drop empty entries.
 */
export function getSalienceAllowlist(): ReadonlyArray<string> {
  // Short-circuit via env var for tests + headless callers.
  const env = process.env.GSTACK_SALIENCE_ALLOWLIST;
  if (typeof env === 'string' && env.length > 0) {
    return env.split(',').map((s) => s.trim()).filter(Boolean);
  }
  // Shell out to gstack-config with a tight timeout. Falls back to defaults
  // on any failure (config script missing, command non-zero, parse error).
  try {
    const skillRoot = join(homedir(), '.claude', 'skills', 'gstack');
    const bin = join(skillRoot, 'bin', 'gstack-config');
    if (!existsSync(bin)) return SALIENCE_DEFAULT_ALLOWLIST;
    const result = spawnSync(bin, ['get', 'salience_allowlist'], { timeout: 2000, encoding: 'utf-8' });
    if (result.status !== 0 || !result.stdout) return SALIENCE_DEFAULT_ALLOWLIST;
    const trimmed = result.stdout.trim();
    if (!trimmed) return SALIENCE_DEFAULT_ALLOWLIST;
    const parts = trimmed.split(',').map((s) => s.trim()).filter(Boolean);
    return parts.length > 0 ? parts : SALIENCE_DEFAULT_ALLOWLIST;
  } catch {
    return SALIENCE_DEFAULT_ALLOWLIST;
  }
}

/**
 * D9 salience privacy gate: returns true if the slug starts with any allowlisted
 * prefix. Anything NOT matching is stripped at digest write time so that family,
 * therapy, reflection, and other sensitive content never leaks into work-flow
 * planning prompts by default.
 */
export function isSalienceSlugAllowed(slug: string, allowlist: ReadonlyArray<string>): boolean {
  for (const prefix of allowlist) {
    if (slug.startsWith(prefix)) return true;
  }
  return false;
}

function fetchSalience(projectSlug: string | null): string | null {
  // get-recent-salience is a gbrain CLI sub-shape; we use the MCP-shape JSON
  const result = execGbrainJson<{ pages?: Array<{ slug: string; title?: string; emotional_weight?: number }> }>([
    'get-recent-salience',
    '--days', '14',
    '--limit', '10',
    '--json',
  ]);
  if (!result?.pages) return `# Recent salience\n\n_No salient pages in last 14d._\n`;

  // D9 privacy gate: strip entries outside the allowlist BEFORE rendering.
  // Sensitive personal content (family, therapy, reflection) is never written
  // into the digest cache file, even when the brain itself ranks it salient.
  const allowlist = getSalienceAllowlist();
  const filtered = result.pages.filter((p) => p.slug && isSalienceSlugAllowed(p.slug, allowlist));
  const stripped = result.pages.length - filtered.length;
  if (filtered.length === 0) {
    const header = `# Recent salience (last 14d)`;
    const note = stripped > 0
      ? `\n_All ${stripped} salient entries stripped by allowlist gate (no work-flow content in window)._\n`
      : `\n_No salient pages in last 14d._\n`;
    return `${header}\n${note}`;
  }
  const lines = filtered.map((p) => `- [[${p.slug}]] — ${p.title || ''} (weight: ${p.emotional_weight?.toFixed(2) ?? 'n/a'})`);
  const footer = stripped > 0
    ? `\n\n_${stripped} private entries stripped by allowlist gate._`
    : '';
  return `# Recent salience (last 14d)\n\n${lines.join('\n')}${footer}\n`;
}

/**
 * Compress a brain page body into a digest. The compressor keeps frontmatter
 * out, trims body to the first H2/H3 sections, and prepends a slug header.
 * Per-entity budget enforcement happens at the caller (refreshEntity).
 */
function compressPage(slug: string, title: string, body: string): string {
  const trimmed = body
    .replace(/^---[\s\S]*?---\s*\n/m, '') // strip frontmatter
    .trim();
  return `# ${title}\nslug: ${slug}\n\n${trimmed}\n`;
}

/**
 * Truncate a digest to a byte budget. Tries to cut at the last newline before
 * the budget so the digest stays readable.
 */
function truncateToBudget(content: string, budgetBytes: number): string {
  const buf = Buffer.from(content, 'utf-8');
  if (buf.byteLength <= budgetBytes) return content;
  const truncated = buf.slice(0, budgetBytes).toString('utf-8');
  const lastNewline = truncated.lastIndexOf('\n');
  const cleanCut = lastNewline > budgetBytes * 0.8 ? truncated.slice(0, lastNewline) : truncated;
  return `${cleanCut}\n\n_(digest truncated to ${budgetBytes}-byte budget)_\n`;
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: digest
// ──────────────────────────────────────────────────────────────────────────

/**
 * Public: compress a brain page slug to digest format. Used by callers that
 * want to know what the digest WOULD look like without writing to cache.
 */
export function cmdDigest(slug: string): string | null {
  return fetchSimplePage(slug);
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: meta
// ──────────────────────────────────────────────────────────────────────────

export function cmdMeta(projectSlug: string | null): CacheMeta {
  if (projectSlug) return loadMeta('per-project', projectSlug);
  return loadMeta('cross-project', null);
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: bootstrap (T2b)
// ──────────────────────────────────────────────────────────────────────────

/**
 * Bootstrap synthesizes draft entity content from CLAUDE.md + README +
 * recent commits + learnings.jsonl for a fresh project. Emits as JSON for
 * the caller (skill template) to AUQ-confirm before any write to the brain.
 *
 * This keeps the CLI pure (no AUQ logic) while preventing silent
 * auto-extraction garbage (D10 T4 fix). The agent is responsible for the
 * "Synthesized X — looks right?" prompt per entity.
 */
export interface BootstrapDraft {
  product?: { slug: string; title: string; body: string };
  goals?: Array<{ slug: string; title: string; body: string }>;
  developer_persona?: { slug: string; title: string; body: string };
  brand?: { slug: string; title: string; body: string };
  competitive_intel?: { slug: string; title: string; body: string };
}

export function cmdBootstrap(projectSlug: string): BootstrapDraft {
  const draft: BootstrapDraft = {};
  const repoRoot = process.env.GSTACK_REPO_ROOT || process.cwd();

  // Product synthesis: CLAUDE.md headline + README first paragraph
  let claudeMd = '';
  try { claudeMd = readFileSync(join(repoRoot, 'CLAUDE.md'), 'utf-8'); } catch { /* missing is fine */ }
  let readmeMd = '';
  try { readmeMd = readFileSync(join(repoRoot, 'README.md'), 'utf-8'); } catch { /* missing is fine */ }

  const productLead = synthesizeProductLead(claudeMd, readmeMd, projectSlug);
  if (productLead) {
    draft.product = {
      slug: `gstack/product/${projectSlug}`,
      title: projectSlug,
      body: productLead,
    };
  }

  // Goals: try learnings.jsonl + recent commit messages mentioning "goal" or "ship"
  const learningsPath = join(GSTACK_HOME, 'projects', projectSlug, 'learnings.jsonl');
  const goalsHints = synthesizeGoalsHints(learningsPath, repoRoot);
  if (goalsHints.length > 0) {
    draft.goals = goalsHints.slice(0, 3).map((hint, idx) => ({
      slug: `gstack/goal/${projectSlug}/bootstrap-${idx + 1}`,
      title: hint.title,
      body: hint.body,
    }));
  }

  return draft;
}

function synthesizeProductLead(claudeMd: string, readmeMd: string, slug: string): string | null {
  // First H1 in CLAUDE.md or README, plus first paragraph after it.
  const source = claudeMd || readmeMd;
  if (!source) return null;
  const h1Match = source.match(/^#\s+(.+)$/m);
  const heading = h1Match?.[1]?.trim() || slug;
  // First non-heading paragraph
  const paraMatch = source.match(/(?:^|\n)([^#\n][^\n]+(?:\n[^#\n][^\n]+)*)/);
  const lead = paraMatch?.[1]?.trim() || '(no description found in CLAUDE.md or README)';
  return [
    `# ${heading}`,
    '',
    '## What',
    lead.slice(0, 500),
    '',
    '## Stage',
    '(fill in current stage, e.g., v1.x shipped, in development, paused)',
    '',
    '## Team',
    '(fill in team composition + size)',
    '',
    '## Active goals',
    '(populated by /office-hours over time)',
    '',
    '## Recent decisions',
    '(populated by /plan-ceo-review over time)',
    '',
  ].join('\n');
}

function synthesizeGoalsHints(learningsPath: string, repoRoot: string): Array<{ title: string; body: string }> {
  const hints: Array<{ title: string; body: string }> = [];
  if (existsSync(learningsPath)) {
    try {
      const lines = readFileSync(learningsPath, 'utf-8').split('\n').filter(Boolean);
      for (const line of lines.slice(-10)) {
        try {
          const entry = JSON.parse(line);
          if (entry?.insight && (entry?.type === 'pattern' || entry?.type === 'architecture')) {
            hints.push({
              title: entry.insight.slice(0, 80),
              body: `Source: learnings.jsonl\nType: ${entry.type}\n\n${entry.insight}\n`,
            });
          }
        } catch { /* skip malformed line */ }
      }
    } catch { /* unreadable file, skip */ }
  }
  return hints;
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: list (T18)
// ──────────────────────────────────────────────────────────────────────────

/**
 * Lists all gstack-owned pages currently in the brain for a project, grouped
 * by type. Powers the user's ability to audit what gstack has written.
 */
export function cmdList(projectSlug: string | null): Array<{ type: string; slug: string; title?: string }> {
  // We probe each gstack/<type>/ namespace via list-pages with a type filter.
  const types = ['gstack/user-profile', 'gstack/product', 'gstack/goal', 'gstack/developer-persona', 'gstack/brand', 'gstack/competitive-intel', 'gstack/skill-run', 'gstack/take'];
  const all: Array<{ type: string; slug: string; title?: string }> = [];
  for (const type of types) {
    const result = execGbrainJson<{ pages?: Array<{ slug: string; title?: string }> }>([
      'list-pages',
      '--type', type,
      '--limit', '200',
      '--json',
    ]);
    if (!result?.pages) continue;
    for (const page of result.pages) {
      if (projectSlug && !page.slug?.includes(`/${projectSlug}`) && type !== 'gstack/user-profile') {
        continue;
      }
      all.push({ type, slug: page.slug, title: page.title });
    }
  }
  return all;
}

// ──────────────────────────────────────────────────────────────────────────
// Subcommand: purge (T18)
// ──────────────────────────────────────────────────────────────────────────

/**
 * Delete one gstack-owned page from the brain. Caller (skill template) is
 * responsible for the confirm prompt; this is the raw operation.
 */
export function cmdPurge(slug: string): { deleted: boolean; error?: string } {
  if (!slug.startsWith('gstack/')) {
    return { deleted: false, error: 'refusing to purge non-gstack page' };
  }
  const result = spawnGbrain(['delete-page', slug], { timeout: 10_000 });
  if (result.status !== 0) {
    return { deleted: false, error: result.stderr?.trim() || `exit ${result.status}` };
  }
  // Also invalidate any cached digests that referenced this page.
  // Best-effort — derived digests may need explicit invalidate.
  return { deleted: true };
}

// ──────────────────────────────────────────────────────────────────────────
// CLI dispatch
// ──────────────────────────────────────────────────────────────────────────

function parseArgs(argv: string[]): { cmd: string; positional: string[]; flags: Record<string, string | boolean> } {
  const cmd = argv[2] || '';
  const rest = argv.slice(3);
  const positional: string[] = [];
  const flags: Record<string, string | boolean> = {};
  for (let i = 0; i < rest.length; i++) {
    const arg = rest[i];
    if (arg.startsWith('--')) {
      const key = arg.slice(2);
      const next = rest[i + 1];
      if (next && !next.startsWith('--')) {
        flags[key] = next;
        i++;
      } else {
        flags[key] = true;
      }
    } else {
      positional.push(arg);
    }
  }
  return { cmd, positional, flags };
}

function projectSlugFromFlag(flags: Record<string, string | boolean>): string | null {
  const v = flags.project;
  return typeof v === 'string' ? v : null;
}

function printUsage(): void {
  process.stderr.write(`Usage: gstack-brain-cache <subcommand>

Subcommands:
  get <entity-name> [--project <slug>]
  refresh [--full] [--entity X] [--project <slug>]
  invalidate <entity-name> [--project <slug>]
  digest <entity-slug>
  meta [--project <slug>]
  bootstrap --project <slug>           — emit synthesized entity drafts (JSON)
  list [--project <slug>]              — list gstack-owned pages in brain
  purge <slug>                         — delete a gstack-owned brain page (refuses non-gstack/ slugs)
`);
}

async function main(): Promise<number> {
  const { cmd, positional, flags } = parseArgs(process.argv);
  const projectSlug = projectSlugFromFlag(flags);

  try {
    switch (cmd) {
      case 'get': {
        const entityName = positional[0];
        if (!entityName) { printUsage(); return 1; }
        const result = cmdGet(entityName, projectSlug);
        if (result.state === 'missing') {
          process.stderr.write(`(${result.state}: ${result.message ?? 'no cache'})\n`);
          return 2;
        }
        if (result.state !== 'warm') {
          process.stderr.write(`(${result.state}${result.message ? ': ' + result.message : ''})\n`);
        }
        process.stdout.write(readFileSync(result.path, 'utf-8'));
        return 0;
      }
      case 'refresh': {
        // D3: dedup concurrent refreshes via lockfile. Skipped (dedup) when
        // another process is already mid-refresh on the same project.
        if (flags.entity) {
          const entityName = String(flags.entity);
          const result = withRefreshLock(projectSlug, () => refreshEntity(entityName, projectSlug));
          if (result === 'dedup') {
            process.stderr.write(`(dedup: another refresh in flight)\n`);
            return 3;
          }
          process.stdout.write(result ? `refreshed ${entityName}\n` : `failed to refresh ${entityName}\n`);
          return result ? 0 : 1;
        }
        const allResult = withRefreshLock(projectSlug, () => refreshAll(projectSlug));
        if (allResult === 'dedup') {
          process.stderr.write(`(dedup: another refresh in flight)\n`);
          return 3;
        }
        process.stdout.write(`refreshed=${allResult.success} failed=${allResult.failed}\n`);
        return allResult.failed > 0 ? 1 : 0;
      }
      case 'invalidate': {
        const entityName = positional[0];
        if (!entityName) { printUsage(); return 1; }
        cmdInvalidate(entityName, projectSlug);
        process.stdout.write(`invalidated ${entityName}\n`);
        return 0;
      }
      case 'digest': {
        const slug = positional[0];
        if (!slug) { printUsage(); return 1; }
        const content = cmdDigest(slug);
        if (content === null) {
          process.stderr.write('brain unreachable or page not found\n');
          return 2;
        }
        process.stdout.write(content);
        return 0;
      }
      case 'meta': {
        const meta = cmdMeta(projectSlug);
        process.stdout.write(JSON.stringify(meta, null, 2) + '\n');
        return 0;
      }
      case 'bootstrap': {
        if (!projectSlug) {
          process.stderr.write('bootstrap requires --project <slug>\n');
          return 1;
        }
        const draft = cmdBootstrap(projectSlug);
        process.stdout.write(JSON.stringify(draft, null, 2) + '\n');
        return 0;
      }
      case 'list': {
        const pages = cmdList(projectSlug);
        if (flags.json) {
          process.stdout.write(JSON.stringify(pages, null, 2) + '\n');
        } else {
          for (const p of pages) {
            process.stdout.write(`${p.type}\t${p.slug}\t${p.title ?? ''}\n`);
          }
        }
        return 0;
      }
      case 'purge': {
        const slug = positional[0];
        if (!slug) { printUsage(); return 1; }
        const result = cmdPurge(slug);
        if (result.deleted) {
          process.stdout.write(`deleted ${slug}\n`);
          return 0;
        }
        process.stderr.write(`failed: ${result.error}\n`);
        return 1;
      }
      case '':
      case 'help':
      case '--help':
      case '-h':
        printUsage();
        return 0;
      default:
        process.stderr.write(`unknown subcommand: ${cmd}\n`);
        printUsage();
        return 1;
    }
  } catch (err) {
    process.stderr.write(`error: ${err instanceof Error ? err.message : String(err)}\n`);
    return 1;
  }
}

// Only run main when invoked as a script (not when imported by tests)
if (import.meta.main) {
  main().then((code) => process.exit(code));
}