bash-gres: Instructions file for Codex

bash-gres

PostgreSQL-backed virtual filesystem for AI agents. PgFileSystem implements the just-bash IFileSystem interface, so it can be passed directly to new Bash({ fs }).

Agent-facing guides for host projects: SETUP-GUIDE.agents.md (fresh install), UPGRADE-GUIDE.agents.md (2.x → 3.0 migration). The docs site lives in app/ (Next.js, deployed to bashgres.com/docs) — keep its pages in sync when the public API changes.

Architecture

bash-gres (core)          PgFileSystem, setup(), search, types
bash-gres/drizzle         Drizzle adapter (createDrizzleClient) + schema
bash-gres/node-postgres   node-postgres (pg) adapter (createNodePgClient)
bash-gres/postgres        postgres.js adapter (createPostgresClient)

Core + Adapter pattern

The core operates on a SqlClient interface (query(text, params) + transaction(fn)). Adapters wrap driver-specific connections into SqlClient:

• postgres.js: createPostgresClient(sql) from bash-gres/postgres
• node-postgres (pg): createNodePgClient(pool) from bash-gres/node-postgres
• Drizzle: createDrizzleClient(db) from bash-gres/drizzle

Then pass the resulting SqlClient to PgFileSystem({ db: client }) and setup(client). Core has zero knowledge of any specific driver.

The Drizzle adapter (lib/adapters/drizzle/adapter.ts) converts $1, $2 positional params into Drizzle's sql tagged template.

Bash integration

PgFileSystem structurally implements the just-bash IFileSystem interface. Users pass it directly:

import { Bash } from "just-bash";
const bash = new Bash({ fs: pgFs });
await bash.exec("echo hello > /file.txt");

bash-gres/just-bash adds createSemgrepCommand({ fs }) — the semgrep custom command (semgrep [-k N] "query" [path]): hybrid search when the handle has an embed option, BM25-only otherwise; grep-style path:start-end output, exit 1 on no match. Type-only imports keep the peer dep optional.

Key modules

• lib/core/types.ts: SqlClient, FsError, SqlError, all option/result interfaces
• lib/core/filesystem.ts: PgFileSystem class with all fs operations (implements IFileSystem)
• lib/core/filesystem/ops/: per-op implementations installed onto PgFileSystem.prototype (one file per op, e.g. list-history.ts, version-diff.ts, merge.ts); shared SQL helpers live next to them (fetch-diff.ts, fetch-page-changes.ts, fetch-version-changes.ts)
• lib/core/setup.ts: idempotent DDL: extensions, table, indexes, RLS, optional pgvector
• lib/core/path-encoding.ts: path <-> ltree conversion using _xHEX_ delimited encoding
• lib/core/search.ts: BM25 full-text search via pg_textsearch, optional pgvector semantic/hybrid. Every signal ranks only the chunks of blobs the handle can see (visible CTE + IN_SCOPE), so cost follows the search scope. Keep IN_SCOPE's IS TRUE (a hashed SubPlan filter: as a semi-join the ~1-row estimate for visible picks nested loops) and the MATERIALIZED fence on BM25 scoring (otherwise score > 0 can run in the chunk scan ahead of the scope test)
• lib/adapters/drizzle/adapter.ts: converts Drizzle db into SqlClient (DrizzleDb interface, createDrizzleClient)
• lib/adapters/drizzle/schema.ts: Drizzle pgTable with all indexes (GiST, BM25, partial)
• lib/adapters/postgres/index.ts: wraps postgres.Sql into SqlClient
• lib/adapters/just-bash/index.ts: createSemgrepCommand — the semgrep custom command for just-bash sessions