admin/gbrain
1
0
Fork 0
mirror of https://github.com/garrytan/gbrain.git synced 2026-07-27 22:15:33 +00:00
Code Issues Packages Projects Releases Wiki Activity
333 Commits 507 Branches 1 Tag
814258dda67945ffec9457a1e73980e947b7e462
Commit Graph
2 Commits
Author SHA1 Message Date
Garry TanGitHubClaude Opus 4.7
 		4446e9f9d2 v0.35.5.0 fix wave: bootstrap + orphans + think MCP + worktree + walker (#1111) 
* fix(bootstrap): extend probes for files/oauth_clients/sources.archived* + add MIGRATIONS introspection guard

Adds 7 new forward-reference probes to applyForwardReferenceBootstrap on
both engines, closes the column-only forward-ref class via a new
MIGRATIONS-source introspection contract test.

New probes:
- files.source_id + files.page_id (v18 forward refs)
- oauth_clients.source_id + oauth_clients.federated_read (v60+v61+v65)
- sources.archived + archived_at + archive_expires_at (v34 promoted from JSONB)

The sources.archived* columns are the codex-flagged class: they're added
inline in v34's CREATE TABLE definition but `CREATE TABLE IF NOT EXISTS
sources` is a no-op on pre-v34 brains, so downstream visibility filters
(search/list_pages) trip on old brains. needsPagesBootstrap now folds
archive columns into its CREATE TABLE so pre-v0.18 brains get a v34-shape
sources in one go; needsSourcesArchive then only fires on the pre-v34
case (sources exists, archive cols don't).

Closes the structural bug class via test/helpers/extract-added-columns.ts:
reads src/core/migrate.ts as text and extracts every ALTER TABLE ADD
COLUMN. The new contract test asserts every (table, column) pair is
covered by EITHER the bootstrap's ALTER TABLE statements, the bootstrap's
CREATE TABLE definitions, OR the schema blob's CREATE TABLE bodies. The
column-only class (no index, no FK; just an inline CREATE TABLE column
the schema blob can't add to existing tables) is now caught at PR time.

Source-text introspection catches all three migration shapes uniformly:
- top-level `sql:` field
- `sqlFor.postgres` / `sqlFor.pglite` overrides
- handler-body `engine.runMigration(N, \`ALTER TABLE ...\`)` (v34 shape)

Pre-existing parseBaseTableColumns parser bug fixed: now strips `--` line
comments and `/* ... */` blocks before identifying column names. Without
this, a column preceded by a comment was silently dropped. Catches
pages.page_kind and others that were silently uncovered.

13 columns added by migrations but not in PGLITE_SCHEMA_SQL are exempted
with a unified rationale: they have no schema-blob forward reference;
migration handles all upgrade paths cleanly. Refreshing the schema blob
is a separate concern.

Issues closed: #1018 (v60 oauth_clients), #974 (files.source_id/page_id),
#820 (v0.13.0 migration files.page_id cascade); pre-empts the
sources.archived class before any pre-v34 brain trips on it.

Tests:
- 9 cases in test/schema-bootstrap-coverage.test.ts (5 existing + 4 new)
- helper-level unit tests cover SQL shape variants (IF NOT EXISTS,
  quoted identifiers, ALTER TABLE IF EXISTS ONLY, multi-statement)
- planted-bug regression verifies the gate actually catches new uncovered
  columns

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(orphans): filter soft-deleted pages on both candidate and link-source sides

Closes #1021. The v0.26.5 soft-delete invariant requires that
findOrphanPages exclude both:
  1. Candidate pages that are themselves soft-deleted
  2. Inbound links from soft-deleted source pages

Pre-fix, findOrphanPages had no deleted_at filter at all. Soft-deleted
pages with no inbound links were counted as orphans (inflating counts).
Pre-codex-tension-D11, only the candidate-side filter was planned.
Codex C11 caught the second case: a live page that has ONE inbound link
from a soft-deleted source page was hidden from orphan results — the
link still existed in the links table, the EXISTS subquery saw it, the
page looked "linked." Now the inner JOIN on pages enforces
src.deleted_at IS NULL.

Three regression tests pin the contract:
- soft-deleted page with no inbound → NOT orphan
- live page with ONLY inbound link from soft-deleted source → IS orphan
- live page with live inbound → NOT orphan (smoke check that the new
  filters don't break unchanged behavior)

Engine parity: same SQL shape on both Postgres and PGLite engines.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(think): route runThink through gateway.chat adapter (closes #952)

Pre-fix, runThink instantiated `new Anthropic()` directly and read
ANTHROPIC_API_KEY from process.env. Claude Desktop's stdio MCP launch
doesn't inherit shell env, so `gbrain config set anthropic_api_key sk-...`
(writes to ~/.gbrain/config.json) never reached the SDK and every MCP
think call degraded to "no LLM available."

The adapter routes through gateway.chat() — the canonical seam per
CLAUDE.md. Gateway reads the API key from gbrain config OR env, picks
up prompt caching, rate-leases, retry, and the test seam
(__setChatTransportForTests) that v0.31.12 established.

Per plan-eng-review D10 (cross-model tension with codex C7+C8+C9+C10),
four spec points landed:

  1. Drop `new Anthropic()` direct path entirely. Every non-stub LLM
     call from runThink routes through gateway.

  2. Real availability check (NOT a false-positive `getChatModel()`
     truthy). `tryBuildGatewayClient` probes both the recipe (resolveRecipe
     throws AIConfigError on unknown providers) AND the API key (reads
     process.env + loadConfig at the gbrain config layer for parity with
     gateway's own auth resolution). Returns null on miss; runThink takes
     the graceful "no LLM available" early-return preserving the legacy
     NO_ANTHROPIC_API_KEY warning signal.

  3. Model-id normalization. resolveModel returns bare anthropic ids
     (claude-opus-4-7); gateway.chat needs provider:model. Adapter
     auto-prefixes anthropic: when the id is bare. Provider:model strings
     pass through unchanged.

  4. Response-shape conversion. ChatResult → Anthropic.Message via
     chatResultToMessage. mapStopReason translates gateway's
     provider-neutral stop reasons (end / length / tool_calls / refusal /
     content_filter / other) to Anthropic's stop_reason ('end_turn' /
     'max_tokens' / 'tool_use'); refusal/content_filter/other fall through
     to end_turn (no Anthropic equivalent). Usage tokens pass through.

`opts.client` injection preserved (test seam — see ThinkLLMClient).
`opts.stubResponse` preserved (pure-test escape).

Tests:
  - test/think-gateway-adapter.test.ts (9 cases): response shape, stop
    reason mapping, model-id normalization (bare + prefixed), provider
    unknown returns null, ANTHROPIC_API_KEY absent returns null
    (regression for legacy graceful degradation), hasAnthropicKey reads
    process.env correctly. Uses withEnv per the test-isolation contract.
  - test/think-pipeline.serial.test.ts (17 existing cases): unchanged;
    the graceful-degradation case at line 213 still produces the
    NO_ANTHROPIC_API_KEY warning because tryBuildGatewayClient returns
    null when no key is configured, taking the legacy early-return path.

Closes #952.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(sync): distinguish git worktree from submodule via path-segment match (closes #889)

Pre-fix, `manageGitignore` treated every `.git`-as-file as a submodule
and skipped gitignore management. Both submodules AND worktrees use
`.git` as a file (not a directory), so the legacy
`statSync.isFile()` check couldn't discriminate. Worktrees got
misclassified as submodules and their .gitignore wasn't managed.

Per plan-eng-review D4 (chose path-segment match over absolute-vs-
relative path heuristic): the gitdir path contains:
  - `/modules/<name>` for submodules (skip — managed by parent repo)
  - `/worktrees/<name>` for worktrees (MANAGE — first-class repo)

Both are documented Git internal layouts, stable across all 4
{relative, absolute} × {modules, worktrees} combinations including the
absorbed-submodule edge case from `git submodule absorbgitdirs` (where
the submodule's gitdir flips to an absolute path).

Malformed `.git` file (no `gitdir:` prefix, IO error) → MANAGE, preserving
the pre-#889 catch{} fail-closed-toward-managing semantics.

Tests (5 new + 1 regression renamed):
  - REGRESSION: submodule relative gitdir/modules/ → skip (D49 contract)
  - absorbed submodule absolute gitdir/modules/ → skip (edge case)
  - CRITICAL: worktree absolute gitdir/worktrees/ → MANAGE (closes #889)
  - worktree relative gitdir/worktrees/ → MANAGE
  - malformed .git file → MANAGE (preserves catch behavior)
  - regular .git directory → MANAGE (existing smoke)

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(walkers): pruneDir helper + descent-time exclusion + transcript predicate (closes #923, #202)

Per plan-eng-review D12 (cross-model tension with codex C12+C13), three
structural changes:

1. Extract `pruneDir(name)` helper in src/core/sync.ts. Returns false for
   directory names walkers must NEVER descend into: `node_modules` (latent
   bug — no leading dot), dot-prefix dirs (`.git`, `.obsidian`, `.raw`,
   `.cache`, etc.), `ops`, and `*.raw` sidecar dirs (gbrain convention —
   `people/pedro.raw/` holds raw source for pedro.md). Walkers consult it
   at descent time BEFORE recursion, saving the IO cost of walking entire
   vendor / hidden / sidecar subtrees only to filter them at file-emit time.

2. `isSyncable` itself gains the same exclusion set (via pruneDir on each
   path segment). Closes the latent bug where node_modules markdown files
   slipped through: `node_modules/some-pkg/README.md` returned true pre-fix
   because the legacy dot-prefix check only blocked `.node_modules` (with
   a leading dot), not the actual `node_modules`. CRITICAL regression test
   in test/sync.test.ts pins the contract per IRON RULE.

3. Two walkers rewritten to use pruneDir at descent + per-walker file
   predicate at emit:
   - `walkMarkdownFiles` (src/commands/extract.ts): pruneDir + isSyncable
     ({strategy:'markdown'}). Pre-fix this walker had ONLY an ad-hoc
     dot-prefix exclusion and didn't call isSyncable at all — descended
     into node_modules, emitted markdown files from there, ignored README/
     ops/.raw filters.
   - `listTextFiles` (src/core/cycle/transcript-discovery.ts): pruneDir +
     own .txt/.md predicate. DOES NOT use isSyncable({strategy:'markdown'})
     because transcripts accept .txt and don't share markdown sync's
     README/ops exclusions (codex C12). Also made RECURSIVE — pre-fix
     it walked only the top dir, so transcripts in `corpus/2026/` were
     invisible (codex C14 — descent-time pruning is the right shape but
     the test would have passed vacuously on a non-recursive walker).

Verified blast radius before adding node_modules: every existing
isSyncable caller (sync.ts:558-561 sync filter, frontmatter.ts:264 validate,
brain-writer.ts:305 reverse-write, import.ts:454 import filter) wants
node_modules excluded — this is a latent-bug fix, not a behavior change
for any legitimate caller.

Tests:
- 7 new isSyncable cases including the node_modules CRITICAL regression
- 6 new pruneDir cases (node_modules, dot-prefix, ops, *.raw, content
  dirs that should pass, empty-string default)
- Existing extract.test.ts + extract-fs.test.ts unchanged and passing

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs(todos): file v0.36.x follow-ups for runThink rewrite + Supabase bootstrap parity

Two follow-up TODOs filed during the v0.36 dreamy-thompson wave:

1. runThink full rewrite (D5+D7 from plan-eng-review): drop the
   ThinkLLMClient indirection now that v0.36 routes through gateway.chat.
   12+ tests need migration to __setChatTransportForTests. Blocked by
   this wave landing.

2. Supabase parity test for applyForwardReferenceBootstrap (codex C6
   residual): real Docker Postgres E2E catches schema correctness but
   not Supabase pooler/direct-pool routing. The probe uses this.sql but
   PostgresEngine.initSchema chooses a DDL connection; the divergence
   has caused multiple historical wedges (#699, #820 lineage).

Both entries include full context per the CLAUDE.md TODOS-format spec
(what, why, pros, cons, blocked-by, plan reference).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix(bootstrap): thread DDL connection through applyForwardReferenceBootstrap

Codex adversarial review during /ship caught a P1: initSchema selected a
DDL connection, took pg_advisory_lock(42) on it, but
applyForwardReferenceBootstrap used `this.sql` (the instance pool) inside.
Bootstrap probes ran outside the lock scope on a different connection.

Failure mode: two concurrent gbrain instances could BOTH enter the
bootstrap block on Supabase transaction-pooler setups because the
advisory lock was held on a different connection than the one running
ALTER TABLE. The pooler's statement_timeout could also kill the probes
mid-flight without affecting the lock-holder, leaving an inconsistent
schema state.

Fix: applyForwardReferenceBootstrap now accepts an optional connection
parameter. initSchema passes the DDL conn (the one holding the lock).
this.sql remains the fallback for any unit-test path that calls bootstrap
directly. PGLite engine doesn't need this change — single connection,
no pooler.

This was pre-existing (every prior probe used this.sql), but the v0.36
wave is explicitly about fixing the Supabase upgrade-wedge class. Codex's
position was correct: don't ship the wave with the underlying connection
mismatch still there. The Supabase parity TEST FIXTURE follow-up remains
on TODOS.md (test infra needed to PROVE the fix works under real pooler
topology), but the bug itself is closed.

15/15 bootstrap tests pass. Typecheck clean.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: bump version and changelog (v0.35.5.0)

Six-correctness-fix wave: bootstrap forward-ref class (4 issues + 1 pre-empt),
orphans soft-delete leak (both sides), runThink → gateway.chat adapter,
git worktree vs submodule discriminator, walker pruneDir + descent-time
exclusion, plus a Codex-P1 catch during /ship that threaded the DDL
connection through applyForwardReferenceBootstrap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: update CLAUDE.md for v0.35.5.0 backend correctness wave

Fold v0.35.5.0 file-level annotations into CLAUDE.md:
- postgres-engine.ts + pglite-engine.ts: 7 new applyForwardReferenceBootstrap
  probes (files.source_id/page_id, oauth_clients.source_id/federated_read,
  sources.archived/archived_at/archive_expires_at) + DDL connection threading
- test/schema-bootstrap-coverage.test.ts: new MIGRATIONS-source introspection
  guard + parseBaseTableColumns comment-stripping fix
- src/core/sync.ts: new pruneDir helper + manageGitignore worktree
  discriminator
- src/core/think/index.ts (new entry): runThink gateway adapter for MCP
  stdio key resolution
- src/core/operations.ts (new entry): findOrphanPages soft-delete filter

Regenerate llms-full.txt via bun run build:llms.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-05-17 14:02:45 -07:00
Garry TanGitHubrootClaude Opus 4.7
 		52f9581966 v0.22.11 feat: storage tiering — db_tracked vs db_only directories (#494) 
* feat: storage tiering — git-tracked vs supabase-only directories

Brain repos scaling to 200K+ files. Bulk data (tweets, articles, transcripts)
bloats git repos and slows operations. New storage config in gbrain.yml lets
users declare git-tracked and supabase-only directories.

Changes:
- New config: storage.git_tracked and storage.supabase_only in gbrain.yml
- gbrain sync auto-manages .gitignore for supabase-only paths
- gbrain export --restore-only restores missing supabase-only files from DB
- New gbrain storage status command shows tier breakdown
- Config validation warns on conflicts
- 8 tests passing, full docs at docs/storage-tiering.md

Backward compatible — systems without gbrain.yml work unchanged.

* feat: add getDefaultSourcePath() typed accessor (step 1/15)

Single source of truth for "what brain repo are we operating against?"
Replaces ad-hoc raw SQL in storage.ts:38 (Issue #3 of eng review). Used by
both gbrain storage status and gbrain export --restore-only.

Returns null on miss, throws on DB error. Composes with the existing
resolveSourceId chain so it honors --source flag / GBRAIN_SOURCE env /
.gbrain-source dotfile / longest-prefix CWD match / brain-level default.

4 new test cases covering happy path, missing local_path, DB error
propagation, and CWD-prefix resolution priority.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: replace gray-matter with dedicated YAML parser (step 2/15)

The original storage-config.ts called gray-matter on a delimiter-less YAML
file. Gray-matter only parses YAML inside `---` frontmatter blocks; without
delimiters, it returns `{data: {}}`. Result: loadStorageConfig() always
returned null, the entire feature was a silent no-op for every user.

Original eng review's P0 confidence-9 finding (Issue #1).

Replaces gray-matter with a small dedicated parser for the gbrain.yml shape
(top-level `storage:` section, two array-valued nested keys). Yaml-lite was
considered first, but its flat key:value design doesn't handle nested
arrays. The dedicated parser is ~50 lines and trades expressiveness for
zero-dep, predictable parsing of a file format we control.

Adds the Issue #1B sanity warning (locked B): when gbrain.yml exists but
has no storage section (or empty arrays), warn once-per-process so the
user sees their config didn't take. The single test that would have caught
the original P0 — write a real gbrain.yml, call loadStorageConfig, assert
non-null — now exists.

Also tightens loadStorageConfig per D36: distinguishes "absent" (silent
null) from "unreadable" (throws). The previous code silently swallowed
read errors, hiding broken installs.

8 new test cases: real-disk happy path, comments + blank lines, quoted
values, missing storage section warning, empty section warning,
once-per-process warning suppression, unreadable file behavior, and the
existing helper tests (validation, tier matching, edge cases) all still
pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: rename storage keys to db_tracked/db_only (step 3/15)

The vendor-specific names "supabase_only" and "git_tracked" hardcoded a
backend (Supabase) into the config schema. gbrain ships two engines —
PGLite and Postgres-via-Supabase. The canonical distinction is "lives in
the brain DB only" vs "lives in the brain DB and on disk under git." Both
work on either engine.

Renamed throughout (Issue #4 of eng review):
  git_tracked    → db_tracked
  supabase_only  → db_only
  isGitTracked() → isDbTracked()
  isSupabaseOnly() → isDbOnly()
  StorageTier 'git_tracked'/'supabase_only' → 'db_tracked'/'db_only'

Backward compatibility (D3 lock):
  loadStorageConfig accepts both shapes. Loader resolution order per the
  eng-review pass-2 finding: parse YAML → if canonical keys present use
  them, else if deprecated keys present map to canonical AND emit
  once-per-process deprecation warning → THEN run validation.
  Validation always sees the canonical shape so error messages reference
  db_tracked/db_only regardless of which keys the user wrote.

  The deprecation warning suggests `gbrain doctor --fix` for an automated
  rename (D72 — fix path lands in step 7).

  When both shapes coexist in one file, canonical wins and a stronger
  warning fires ("deprecated keys ignored — remove them").

Aliases isGitTracked/isSupabaseOnly kept for now to avoid churning the
sync.ts / export.ts / storage.ts call sites in this commit; they'll be
removed in a follow-up step. Storage.ts's tier-bucket initializers and
output strings updated. ASCII output replaces unicode box-drawing per D10.

gbrain.yml example file updated to canonical keys with explanatory
comments.

2 new test cases: deprecated-key fallback (asserts both shapes load
correctly with warning), canonical-wins-over-deprecated (asserts the
"both shapes coexist" path).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: add slugPrefix to PageFilters with engine-side filter (step 4/15)

Issue #13 of the eng review: storage.ts and export.ts loaded every page
in the brain (limit: 1_000_000) to check tier membership. On the 200K-page
brains this feature targets, that's the wall-clock and memory landmine
the feature exists to fix.

Adds an optional `slugPrefix` field to PageFilters. Both engines implement
it as `WHERE slug LIKE prefix || '%' ESCAPE '\'`, with literal escaping of
LIKE metacharacters (%, _, \) so user-supplied prefixes like `media/x/`
are treated as exact string prefixes.

Performance: the (source_id, slug) UNIQUE constraint on the pages table
gives both engines a btree index that supports LIKE-prefix range scans.
An EXPLAIN on Postgres confirms the index range scan rather than a seq
scan. PGLite has the same index shape via pglite-schema.ts.

Consumers updated:
  - export.ts: --slug-prefix flag now goes engine-side (no in-memory
    .filter(...)). The --restore-only path queries each db_only directory
    with slugPrefix in a loop instead of one full-table scan, with seen-set
    deduplication and disk-existence check inline.
  - storage.ts: keeps the full-scan path because storage-status needs the
    "unspecified" bucket count, which can't be computed without enumerating
    every page. Comment notes that step 5 (single-walk filesystem scan)
    will reduce per-page disk syscall cost.

2 new test cases on PGLiteEngine: slugPrefix happy path (3 tier dirs,
asserts only matching slugs return) and metacharacter escape regression
(asserts safe/ doesn't match unrelated slugs).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* perf: single-walk filesystem scan via walkBrainRepo() (step 5/15)

Issue #14 of the eng review: storage.ts called existsSync + statSync
per-page in a synchronous loop. On a 200K-page brain that's 400K syscalls
serialized. Wall-clock landmine.

Adds src/core/disk-walk.ts with walkBrainRepo(repoPath) — one recursive
readdirSync walk, builds a Map<slug, {size, mtimeMs}>. Storage.ts looks
up each DB page in the map (O(1)) instead of stat-checking on demand.
Slug derivation matches the pages-table convention: people/alice.md on
disk becomes people/alice as the map key.

Skipped during walk:
  - dot-directories (.git, .gbrain, .vscode, etc) — not part of the brain
    namespace
  - node_modules — guards against accidentally walking into imported repos
  - non-.md files (sidecar JSON, binaries) — tracked by the brain through
    the files table, not by slug

Reusable: future commands (gbrain doctor's storage_tiering check, the
optional autopilot tier-fix path) get the same walk for free.

9 new test cases: empty dir, nonexistent dir, top-level files, nested
dirs, dot-dir skipping, node_modules skipping, non-.md filtering, size
capture, mtimeMs capture.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: path-segment matching for tier directories (step 6/15)

Issue #5 + D6 of the eng review: tier matching used slug.startsWith(dir),
which falsely matches 'media/xerox/foo' against 'media/x' if a user wrote
the directory without a trailing slash.

The new matcher requires the configured directory to end with `/` and
treats it as a canonical path-segment ancestor:

  media/x/   matches  media/x/tweet-1       ✓
  media/x/   doesn't  media/xerox/foo       ✗
  media/x    refused  media/x/tweet-1       (matcher requires trailing /)

Non-canonical input (no trailing slash) is refused outright. Step 7's
auto-normalizing validator converts user-written 'media/x' → 'media/x/'
on load, so the matcher never sees non-canonical input from real configs.
The behavior tested here is the strict matcher's contract.

Regression test pins the media/xerox collision case explicitly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: auto-normalize trailing-slash, throw on tier overlap (step 7/15)

D7+D8 of the eng review: validation was warnings-only. Users miss warnings.
Now:

  - Cosmetic: missing trailing slash auto-corrected, one-time info note
    showing what changed ("normalized 2 storage paths: 'people' →
    'people/', 'media/x' → 'media/x/'"). Once-per-process to keep noise low.

  - Semantic: same directory in both tiers throws StorageConfigError.
    Ambiguous routing — does media/ win as db_tracked or db_only? — is a
    real bug the user must fix. Caller propagates to the CLI for a clean
    exit-1 with actionable message.

loadStorageConfig now applies normalize+validate after merging deprecated
keys, so the path-segment matcher (step 6) only ever sees canonical
trailing-slash directories.

The pure validateStorageConfig kept for callers who want the warnings list
without the auto-fix side effects (gbrain doctor's reporting path).

2 new test cases: auto-normalize round-trip with warning text assertion,
overlap throws StorageConfigError.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: wire manageGitignore into runSync, only on success (step 8/15)

Issue #2 of the eng review: manageGitignore was defined and never
invoked. Docs claimed "auto-managed by gbrain" — false. Users hit a
.gitignore that never updated and committed db_only directories anyway.

Wire-up: runSync now calls manageGitignore after each successful
performSync return, in both watch and one-shot modes.

Eng review pass-2 finding #1: skip on dry_run AND blocked_by_failures
status. A sync that aborted partway has stale state; mutating .gitignore
based on a partially-loaded config invites drift. Failure-skip test
added (uses .gitignore-as-a-directory to simulate write failure;
asserts warning fired and disk wasn't corrupted).

Hardened manageGitignore itself with three additional behaviors:

  - GBRAIN_NO_GITIGNORE=1 escape hatch (D23) for shared-repo setups
    where a maintainer wants gbrain to leave .gitignore alone.

  - Submodule detection (D49). When repoPath/.git is a regular file
    (gitdir: ... pointer), the repo is a git submodule. Submodule
    .gitignore changes don't survive parent submodule updates, so we
    skip with an actionable warning ("add db_only directories to your
    parent repo's .gitignore manually").

  - Graceful failure (D9). Read errors, write errors, and
    StorageConfigError (overlap from step 7) all log a warning and
    return — sync's primary job (moving data) shouldn't die because of
    a side-effect on .gitignore.

manageGitignore is now exported (previously private) so the
storage-sync test file can hit it directly without spinning up sync.

9 new test cases: no-op without gbrain.yml, no-op with empty db_only,
happy-path append, idempotency (run twice, single entry), preservation
of user-written rules, GBRAIN_NO_GITIGNORE skip, submodule skip,
.git-directory normal path, write-failure graceful warning.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* fix: D5 resolution chain for --restore-only and storage status (step 9/15)

D5 of the eng review: gbrain export --restore-only without --repo
silently fell through to the regular export path, dumping every page in
the database to the wrong directory. Hard regression risk.

Now exits 1 with an actionable message when --restore-only has no
--repo AND no configured default source. Resolution order:
  1. Explicit --repo flag
  2. Typed sources.getDefault() (reuses step 1's accessor)
  3. Hard error — never fall through to cwd

storage.ts:38 also bypassed BrainEngine with raw SQL and a bare
try/catch (Issue #3 + Issue #9). Replaced with the same typed
getDefaultSourcePath() — single source of truth, errors propagate
cleanly to the user, no silent cwd fallback.

Regular export (no --restore-only) keeps its current behavior per D26:
exports include everything, --repo is optional.

4 new test cases on PGLite in-memory:
  - hard-errors with no --repo + no default
  - explicit --repo wins
  - falls back to sources default local_path
  - non-restore export does not require --repo

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* refactor: split storage.ts into pure data + JSON + human formatters (step 10/15)

Issue #10 of the eng review: getStorageStatus and runStorageStatus mixed
data gathering, JSON serialization, and human-readable output in one
function. Hard to test, hard to reuse, mismatched the orphans.ts pattern
that CLAUDE.md cites as the precedent.

Now three pure functions + a thin dispatcher:

  getStorageStatus(engine, repoPath) — async, returns StorageStatusResult.
    Side effects: engine.listPages + one walkBrainRepo (Issue #14).
    Exported so MCP exposure (D14) and gbrain doctor (D13) can consume the
    same data without re-running the loop.

  formatStorageStatusJson(result) — pure, returns indented JSON. Stable
    contract on the StorageStatusResult shape, suitable for orchestrators.

  formatStorageStatusHuman(result) — pure, returns ASCII text (D10 — no
    unicode box-drawing). Composable into other commands later.

  runStorageStatus(engine, args) — thin dispatcher: parses --repo /
    --json, calls getStorageStatus, picks a formatter, prints.

8 new test cases on the formatters: JSON parse round-trip, null-config
fallback, missing-files capped at 10 with rollup, ASCII-only assertion
(D10 regression guard), warnings inline, configuration listing, disk-
usage block omitted when zero bytes.

The StorageStatusResult interface is now exported as a public type, so
gbrain doctor's storage_tiering check can build its own findings from
the same shape.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* types: distinct PageCountsByTier and DiskUsageByTier (step 11/15)

Issue #11 of the eng review: pagesByTier (page counts) and
diskUsageByTier (byte totals) shared the same structural type
(Record<StorageTier, number>). Both are tier-keyed numeric maps but
carry semantically different units. A future bug that swaps them at a
call site (e.g., displaying disk bytes where the count belongs) wouldn't
trip the compiler.

Replaced with distinct nominal types via a brand field. Structurally
identical at runtime (no overhead) but compile-time disjoint —
TypeScript catches accidental cross-assignment.

  PageCountsByTier   { db_tracked, db_only, unspecified } : numbers (count)
  DiskUsageByTier    { db_tracked, db_only, unspecified } : numbers (bytes)

Both initialized in getStorageStatus, both threaded into
StorageStatusResult, both consumed by formatStorageStatusHuman /
formatStorageStatusJson without further changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* feat: PGLite soft-warn + full lifecycle test (step 12/15)

D4: storage tiering on PGLite is a partial feature. The "DB" the pages
live in IS the local file gbrain uses for everything else, so "db_only"
has no real offload effect. The .gitignore management still helps
(keeps bulk content out of git history), so we warn and proceed —
not refuse.

Two warning sites (once-per-process each via module-local flags):
  - storage status: warns at runStorageStatus entry
  - sync: warns inside manageGitignore when engineKind='pglite' and
    config has db_only entries

Both phrased actionably ("To get full tiering, migrate to Postgres
with `gbrain migrate --to supabase`").

manageGitignore signature now takes an optional `engineKind` param.
runSync passes engine.kind. Stand-alone callers (tests, future
gbrain doctor --fix path) can omit it.

New test: test/storage-pglite.test.ts — D8 + D4 lifecycle. 6 cases:
engine.kind assertion, getStorageStatus loading gbrain.yml + reporting
tier counts, manageGitignore PGLite-warn (once per process), Postgres
no-warn, slugPrefix on PGLite, end-to-end (config + putPage + status
+ gitignore).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: add trailing-newline CI guard (step 14/15)

Issue #7 of the eng review: all four new files in the original
storage-tiering branch lacked POSIX trailing newlines. Linters complain,
git diffs phantom-flag every future edit. We've been adding newlines as
each file landed; this commit catches the regression class.

scripts/check-trailing-newline.sh:
  - sibling to check-jsonb-pattern.sh / check-progress-to-stdout.sh per
    CLAUDE.md's CI guard pattern
  - portable to bash 3.2 (macOS default; no mapfile, no associative arrays)
  - covers src/**, test/**, gbrain.yml, top-level *.md
  - reports each missing file by path and exits 1

Wired into `bun run test` between progress-to-stdout and typecheck.

Also fixed docs/storage-tiering.md (pre-existing missing newline from
the original branch — caught by the new guard on first run).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: v0.23.0 — VERSION, CHANGELOG, README, CLAUDE.md, storage-tiering.md (step 15/15)

VERSION → 0.23.0 (minor bump for new feature surface).

CHANGELOG entry in Garry voice with the canonical format:
  - Two-line bold headline ("Storage tiering, finally working...")
  - Lead paragraph naming what was broken before and what users get now
  - "Numbers that matter" before/after table for the 6 things that
    actually changed
  - "What this means for your brain" closer
  - "To take advantage of v0.23.0" self-repair block (per CLAUDE.md
    convention) — 6 numbered steps users can follow
  - Itemized changes split into critical fixes / new+renamed surface /
    architecture cleanup / tests + CI guards

CLAUDE.md "Key files" gains four new entries: storage-config.ts,
disk-walk.ts, the v0.23.0 storage.ts shape, and gbrain.yml itself.

README.md gains a new "Storage tiering" section between Skillify and
Getting Data In with the canonical example + commands + link to the
full guide.

docs/storage-tiering.md rewritten end-to-end with canonical key names
(db_tracked / db_only), v0.23.0 hardening details (idempotency,
submodule detection, GBRAIN_NO_GITIGNORE, dry-run gating), the
resolution chain for --restore-only, the auto-normalize +
throw-on-overlap validator, and the PGLite engine note.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* test: e2e Postgres lifecycle for storage tiering (step 16/16)

Per the v0.23.0 plan: full lifecycle E2E against real Postgres.

  - engine.kind === 'postgres' assertion
  - Full lifecycle: write 4 pages (1 db_tracked, 2 db_only, 1 unspecified)
    → getStorageStatus reports correct tier counts → human formatter
    renders → manageGitignore writes managed block → idempotency check
    → getDefaultSourcePath() resolves the configured local_path.
  - Container restart simulation: 2 db_only pages in DB, files missing
    on disk → status.missingFiles.length === 2 → slugPrefix engine
    filter on Postgres returns exactly the tier slugs.
  - slugPrefix index-based range scan regression: 50 media/x/* + 50
    people/p-* pages → slugPrefix='media/x/' returns exactly 50.
  - getDefaultSourcePath returns null when default source has no
    local_path (the hard-error path that replaces the original silent
    cwd fallback).
  - manageGitignore on Postgres engine does NOT emit the PGLite
    soft-warn (cross-engine assertion).

Skips gracefully when DATABASE_URL is unset, per CLAUDE.md E2E pattern.
Run via: DATABASE_URL=... bun test test/e2e/storage-tiering.test.ts

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: rebump version 0.23.0 → 0.22.9

Reverts the minor bump back to a patch-style version on the v0.22 line.
Storage tiering ships within the v0.22.x train alongside the recent
fix waves. Updates VERSION, package.json, CHANGELOG header + body refs,
CLAUDE.md Key files annotations, README.md section heading, and the
docs/storage-tiering.md backward-compat note.

* chore: bump version 0.22.9 → 0.22.11

Sibling workspaces claimed v0.22.10 in the queue. This branch advances
to v0.22.11 to keep the version monotonic on master.

Updates VERSION, package.json, CHANGELOG header + body refs, CLAUDE.md
Key files annotations, README.md section heading, and the
docs/storage-tiering.md backward-compat note.

* fix: address Codex pre-landing review findings (4 fixes)

Codex found 4 real issues during pre-landing review of v0.22.11 diff:

[P0] export --restore-only fell through to full export when
storageConfig was null (no gbrain.yml present). On older or
misconfigured brains, the recovery command would silently dump the
entire database. src/commands/export.ts now refuses with an actionable
error before any page query fires — matches the D5 lock spirit
("never silently fall through").

[P1] manageGitignore wire-up only fired when --repo was passed
explicitly. performSync resolves the repo from sync.repo_path or
sources.local_path, so the common `gbrain sync` path (after
setup, no flag) never updated .gitignore. src/commands/sync.ts now
uses the same source-resolver chain as the rest of /ship: opts.repoPath
→ getDefaultSourcePath → null. Fires in both watch and one-shot modes.

[P2] getDefaultSourcePath only consulted sources.local_path, missing
the legacy global sync.repo_path config key that pre-v0.18 brains use.
Added a fallback to engine.getConfig('sync.repo_path') when the
sources row has NULL local_path. Pre-v0.18 brains now work without
forcing a `gbrain sources add . --path .` migration.

[P2] sync --all multi-source loop never called manageGitignore even
though src.local_path was already known. Each source now gets its own
gitignore update on successful sync.

Tests:
  - test/storage-export.test.ts: replaced the old "falls through to
    full export" test with one that asserts the new refusal path
    (storage-tiering config required for --restore-only).
  - test/source-resolver.test.ts: added a fallback test exercising the
    legacy sync.repo_path code path for pre-v0.18 brains.
  - All 78 storage-tiering tests still pass.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* chore: regenerate llms.txt + llms-full.txt for v0.22.11

Per CLAUDE.md: "Run `bun run build:llms` after adding a new doc."
The README's new Storage tiering section + the rewritten
docs/storage-tiering.md changed the inlined bundle. test/build-llms.test.ts
catches the drift and was failing on master pre-regen.

* fix: typecheck error in disk-walk.ts (CI #73350475897)

tsc --noEmit failed in CI because ReturnType<typeof readdirSync> with
withFileTypes:true picks an overload union that includes
Dirent<Buffer<ArrayBufferLike>>. Strict tsc treats entry.name as Buffer,
so .startsWith / .endsWith / string comparisons all blew up.

Annotate the variable as Dirent[] (string-based) and cast through unknown,
matching the pattern sync.ts already uses for its own filesystem walk.
Same runtime behavior; clean typecheck.

Tests still 9/9.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
EOF

---------

Co-authored-by: root <root@localhost>
Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
 2026-04-29 22:21:07 -07:00