bash-gres: Instructions file for Claude Code

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 }).

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");

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/core/mounts.ts: mount allow-list (default-deny scoping to subtrees of one workspace). Sibling to exclude.ts: compileMounts + mountVisible/mountWritable (JS guards) + mountWhereSql (threaded into every listing/walk/glob/search query via buildMountClause). Roots are grouped by depth, so cost scales with distinct root depths, not mount count: one subpath(path, 0, k)::text IN (SELECT unnest($n::text[])) per depth plus one for the roots' strict ancestors. Keep the IN (SELECT unnest(...)) form: it plans as a hashed SubPlan even under a generic plan, where = ANY($n) scans the array per row
• 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/node-postgres/index.ts: wraps pg.Pool into SqlClient (structural NodePgPool interface)
• lib/adapters/postgres/index.ts: wraps postgres.Sql into SqlClient