ESCAPE '\\'in template strings needs exactly one backslash escape level. Double-escaping ('\\\\') produces a two-char string that SQLite rejects with "ESCAPE expression must be a single character".COALESCE(a, b, c) LIKE ?only tests the first non-null field. To search multiple JSON fields independently, usea LIKE ? OR b LIKE ? OR c LIKE ?with the pattern repeated per field.- All user-input values used in
LIKEpatterns must go throughescapeLike()to neutralize%and_wildcards — including session ID prefix matches and--directoryfilters.
- Three functions must stay in sync:
stripAnsi(returns plain string),visibleLen(returns visible char count),trunc(truncates to N visible chars preserving escapes). If any of these diverge, table rendering and search output will corrupt terminal output. - Any new function that measures or slices user-visible strings must use
visibleLen(), not.length, if the string could contain ANSI codes.
- Bun's
binfield in package.json works directly with.tsfiles — no compile step needed. The#!/usr/bin/env bunshebang is required. bun linkinstalls binaries to~/.bun/bin/, which may not be on PATH. Test with the full path orbun <file>.tsdirectly.
jsonField(raw, field)usesv != null && v !== ""— never||— because||swallows legitimate falsy values from JSON (0,false,"").WhereBuilder.add()accepts raw SQL fragments. All current callers use string literals. Never pass user input as the condition string; user values go in the...paramsrest args.sortOrder()validates itsaliasparameter against/^[a-z_][a-z0-9_]*$/i. Thesortvalue itself never reaches SQL — it's matched against a fixed set with a static default fallback.
- CONTEXT.md must not contain line numbers or line counts — they go stale with every edit. Use section names and function tables for navigation; agents can grep for section banners (
// ───). - README.md command examples should use the installed binary name (
opencode-db-search), notbun opencode-db-search.ts.