refactor(db): DRY up database layer with shared helpers and lint enforcement (#550)

## Summary

DRY up the `src/lib/db/` layer by extracting shared helpers, removing
duplicated SQL patterns, and adding GritQL lint rules to prevent
regression.

## Changes

### New helpers in `src/lib/db/utils.ts`
- **`getMetadata(db, keys)`** — batch read from metadata table (`SELECT
... WHERE key IN (...)`)
- **`setMetadata(db, entries)`** — batch write in a single transaction
- **`clearMetadata(db, keys)`** — batch delete (`DELETE ... WHERE key IN
(...)`)
- **`touchCacheEntry(table, keyColumn, keyValue)`** — shared
`last_accessed` timestamp update

### Refactored DB modules
- `install-info.ts` — 4 individual queries → 1 batch call per operation
- `version-check.ts`, `release-channel.ts` — same metadata helper
adoption
- `dsn-cache.ts`, `project-cache.ts` — private `touchCacheEntry` →
shared helper
- `project-cache.ts` — deduplicated 4 get/set functions via
`getByKey`/`setByKey` helpers
- `project-aliases.ts` — manual `BEGIN`/`COMMIT`/`ROLLBACK` →
`db.transaction()()`

### De-async synchronous functions
Removed `async`/`Promise<>` from 27 DB functions that only do
synchronous SQLite operations, plus ~370 `await` removals at call sites.
Narrowed the biome `useAwait: "off"` override to only files with
genuinely async operations.

### GritQL lint rules (3 new)
- `no-raw-metadata-queries.grit` — enforces
`getMetadata`/`setMetadata`/`clearMetadata`
- `no-manual-transactions.grit` — enforces `db.transaction()()`
- `no-inline-touch-cache.grit` — enforces shared `touchCacheEntry()`

### Documentation
- AGENTS.md — expanded SQL Utilities section, replaced stale "Async
Config Functions" with accurate "DB and Config Function Signatures"

Author: BYK

AGENTS.md

@@ -368,27 +368,35 @@ if (result.success) {
 
 ### SQL Utilities
 
-Use the `upsert()` helper from `src/lib/db/utils.ts` to reduce SQL boilerplate:
+Use helpers from `src/lib/db/utils.ts` to reduce SQL boilerplate:
 
 ```typescript
-import { upsert, runUpsert } from "../db/utils.js";
+import { upsert, runUpsert, getMetadata, setMetadata, clearMetadata, touchCacheEntry } from "../db/utils.js";
 
-// Generate UPSERT statement
-const { sql, values } = upsert("table", { id: 1, name: "foo" }, ["id"]);
-db.query(sql).run(...values);
-
-// Or use convenience wrapper
+// UPSERT (insert or update on conflict)
 runUpsert(db, "table", { id: 1, name: "foo" }, ["id"]);
 
-// Exclude columns from update
+// With excludeFromUpdate (columns only set on INSERT)
 const { sql, values } = upsert(
   "users",
   { id: 1, name: "Bob", created_at: now },
   ["id"],
   { excludeFromUpdate: ["created_at"] }
 );
+db.query(sql).run(...values);
+
+// METADATA table helpers (for key-value config in the metadata table)
+const m = getMetadata(db, [KEY_A, KEY_B]);              // SELECT ... WHERE key IN (...)
+setMetadata(db, { [KEY_A]: "val1", [KEY_B]: "val2" });  // Batch upsert in transaction
+clearMetadata(db, [KEY_A, KEY_B]);                       // DELETE ... WHERE key IN (...)
+
+// Cache entry touch (update last_accessed timestamp)
+touchCacheEntry("dsn_cache", "directory", directoryPath);
 ```
 
+**Enforced by lint:** GritQL rules ban raw metadata queries, inline `last_accessed` UPDATEs,
+and manual `BEGIN`/`COMMIT`/`ROLLBACK` transactions outside `utils.ts` and `migration.ts`.
+
 ### Error Handling
 
 All CLI errors extend the `CliError` base class from `src/lib/errors.ts`:
@@ -460,16 +468,23 @@ entity-aware suggestions (e.g., "This looks like a span ID").
 - `trace/view.ts` — issue short ID → issue's trace redirect
 - `hex-id.ts` — entity-aware error hints in `validateHexId`/`validateSpanId`
 
-### Async Config Functions
+### DB and Config Function Signatures
 
-All config operations are async. Always await:
+Database operations in `src/lib/db/` are **synchronous** (SQLite is synchronous in Bun).
+Functions that only do SQLite work return values directly — no `async`/`await` needed:
 
 ```typescript
-const token = await getAuthToken();
-const isAuth = await isAuthenticated();
-await setAuthToken(token, expiresIn);
+const org = getDefaultOrganization();  // returns string | undefined
+const info = getUserInfo();            // returns UserInfo | undefined
+setDefaults("my-org", "my-project");   // returns void
+const token = getAuthToken();          // returns string | undefined
 ```
 
+Exceptions that ARE async (they do file I/O or network calls):
+- `clearAuth()` — awaits cache directory cleanup
+- `getCachedDetection()`, `getCachedProjectRoot()`, `setCachedProjectRoot()` — await `stat()` for mtime validation
+- `refreshToken()`, `performTokenRefresh()` — await HTTP calls
+
 ### Imports
 
 - Use `.js` extension for local imports (ESM requirement)
@@ -832,6 +847,30 @@ mock.module("./some-module", () => ({
 <!-- lore:019cb950-9b7b-731a-9832-b7f6cfb6a6a2 -->
 * **Self-hosted OAuth device flow requires Sentry 26.1.0+ and SENTRY\_CLIENT\_ID**: Self-hosted OAuth device flow requires Sentry 26.1.0+ and both \`SENTRY\_URL\` and \`SENTRY\_CLIENT\_ID\` env vars. Users must create a public OAuth app in Settings → Developer Settings. The client ID is NOT optional for self-hosted. Fallback for older instances: \`sentry auth login --token\`. \`getSentryUrl()\` and \`getClientId()\` in \`src/lib/oauth.ts\` read lazily (not at module load) so URL parsing from arguments can set \`SENTRY\_URL\` after import.
 
+<!-- lore:019ce2be-39f1-7ad9-a4c5-4506b62f689c -->
+* **api-client.ts split into domain modules under src/lib/api/**: The original monolithic \`src/lib/api-client.ts\` (1,977 lines) was split into 12 focused domain modules under \`src/lib/api/\`: infrastructure.ts (shared helpers, types, raw requests), organizations.ts, projects.ts, teams.ts, repositories.ts, issues.ts, events.ts, traces.ts, logs.ts, seer.ts, trials.ts, users.ts. The original \`api-client.ts\` was converted to a ~100-line barrel re-export file preserving all existing import paths. The \`biome.jsonc\` override for \`noBarrelFile\` already includes \`api-client.ts\`. When adding new API functions, place them in the appropriate domain module under \`src/lib/api/\`, not in the barrel file.
+
+<!-- lore:019d0b69-1430-74f0-8e9a-426a5c7b321d -->
+* **Bun compiled binary sourcemap options and size impact**: Binary build (\`script/build.ts\`) uses two steps: (1) \`Bun.build()\` produces \`dist-bin/bin.js\` + \`.map\` with \`sourcemap: "linked"\` and minification. (2) \`Bun.build()\` with \`compile: true\` produces native binary — no sourcemap embedded. Bun's compiled binaries use \`/$bunfs/root/bin.js\` as the virtual path in stack traces. Sourcemap upload must use \`--url-prefix '/$bunfs/root/'\` so Sentry can match frames. The upload runs \`sentry-cli sourcemaps inject dist-bin/\` first (adds debug IDs), then uploads both JS and map. Bun's compile step strips comments (including \`//# debugId=\`), but debug ID matching still works via the injected runtime snippet + URL prefix matching. Size: +0.04 MB gzipped vs +2.30 MB for inline sourcemaps. Without \`SENTRY\_AUTH\_TOKEN\`, upload is skipped gracefully.
+
+<!-- lore:019cb8ea-c6f0-75d8-bda7-e32b4e217f92 -->
+* **CLI telemetry DSN is public write-only — safe to embed in install script**: The CLI's Sentry DSN (\`SENTRY\_CLI\_DSN\` in \`src/lib/constants.ts\`) is a public write-only ingest key already baked into every binary. Safe to hardcode in install scripts. Opt-out: \`SENTRY\_CLI\_NO\_TELEMETRY=1\`.
+
+<!-- lore:019c978a-18b5-7a0d-a55f-b72f7789bdac -->
+* **cli.sentry.dev is served from gh-pages branch via GitHub Pages**: \`cli.sentry.dev\` is served from gh-pages branch via GitHub Pages. Craft's gh-pages target runs \`git rm -r -f .\` before extracting docs — persist extra files via \`postReleaseCommand\` in \`.craft.yml\`. Install script supports \`--channel nightly\`, downloading from the \`nightly\` release tag directly. version.json is only used by upgrade/version-check flow.
+
+<!-- lore:019cbe93-19b8-7776-9705-20bbde226599 -->
+* **Nightly delta upgrade buildNightlyPatchGraph fetches ALL patch tags — O(N) HTTP calls**: Delta upgrade in \`src/lib/delta-upgrade.ts\` supports stable (GitHub Releases) and nightly (GHCR) channels. \`filterAndSortChainTags\` filters \`patch-\*\` tags by version range using \`Bun.semver.order()\`. GHCR uses \`fetchWithRetry\` (10s timeout + 1 retry; blobs 30s) with optional \`signal?: AbortSignal\` combined via \`AbortSignal.any()\`. \`isExternalAbort(error, signal)\` skips retries for external aborts — critical for background prefetch. Patches cached to \`~/.sentry/patch-cache/\` (file-based, 7-day TTL). \`loadCachedChain\` stitches patches for multi-hop offline upgrades.
+
+<!-- lore:2c3eb7ab-1341-4392-89fd-d81095cfe9c4 -->
+* **npm bundle requires Node.js >= 22 due to node:sqlite polyfill**: The npm package (dist/bin.cjs) requires Node.js >= 22 because the bun:sqlite polyfill uses \`node:sqlite\`. A runtime version guard in the esbuild banner catches this early. When writing esbuild banner strings in TS template literals, double-escape: \`\\\\\\\n\` in TS → \`\\\n\` in output → newline at runtime. Single \`\\\n\` produces a literal newline inside a JS string, causing SyntaxError.
+
+<!-- lore:019c972c-9f0f-75cd-9e24-9bdbb1ac03d6 -->
+* **Numeric issue ID resolution returns org:undefined despite API success**: Numeric issue ID resolution in \`resolveNumericIssue()\`: (1) try DSN/env/config for org, (2) if found use \`getIssueInOrg(org, id)\` with region routing, (3) else fall back to unscoped \`getIssue(id)\`, (4) extract org from \`issue.permalink\` via \`parseSentryUrl\` as final fallback. \`parseSentryUrl\` handles path-based (\`/organizations/{org}/...\`) and subdomain-style URLs. \`matchSubdomainOrg()\` filters region subdomains by requiring slug length > 2. Self-hosted uses path-based only.
+
+<!-- lore:019ce0bb-f35d-7380-b661-8dc56f9938cf -->
+* **Seer trial prompt uses middleware layering in bin.ts error handling chain**: Error recovery middlewares in \`bin.ts\` are layered: \`main() → executeWithAutoAuth() → executeWithSeerTrialPrompt() → runCommand()\`. Seer trial prompts (for \`no\_budget\`/\`not\_enabled\`) caught by inner wrapper; auth errors bubble to outer. Auth retry goes through full chain. Trial API: \`GET /api/0/customers/{org}/\` → \`productTrials\[]\` (prefer \`seerUsers\`, fallback \`seerAutofix\`). Start: \`PUT /api/0/customers/{org}/product-trial/\`. SaaS-only; self-hosted 404s gracefully. \`ai\_disabled\` excluded. \`startSeerTrial\` accepts \`category\` from trial object — don't hardcode.
+
 <!-- lore:019d0b16-977c-7e49-b06d-523b7782692f -->
 * **Sentry CLI fuzzy matching coverage map across subsystems**: Fuzzy matching exists in: (1) Stricli built-in Damerau-Levenshtein for subcommand/flag typos within known route groups, (2) custom \`fuzzyMatch()\` in \`complete.ts\` for dynamic tab-completion using Levenshtein+prefix+contains scoring, (3) custom \`levenshtein()\` in \`platforms.ts\` for platform name suggestions, (4) plural alias detection in \`app.ts\`, (5) \`resolveCommandPath()\` in \`introspect.ts\` uses \`fuzzyMatch()\` from \`fuzzy.ts\` for top-level and subcommand typos — covering both \`sentry \<typo>\` and \`sentry help \<typo>\`. Static shell tab-completion uses shell-native prefix matching (compgen/\`\_describe\`/fish \`-a\`).
 

biome.jsonc

@@ -3,7 +3,10 @@
   "extends": ["ultracite/core"],
   "plugins": [
     "./lint-rules/no-stdout-write-in-commands.grit",
-    "./lint-rules/no-process-stdout-in-commands.grit"
+    "./lint-rules/no-process-stdout-in-commands.grit",
+    "./lint-rules/no-raw-metadata-queries.grit",
+    "./lint-rules/no-manual-transactions.grit",
+    "./lint-rules/no-inline-touch-cache.grit"
   ],
   "files": {
     "includes": ["!docs", "!test/init-eval/templates"]
@@ -48,8 +51,13 @@
       }
     },
     {
-      // SQLite operations are sync but we keep async signatures for API compatibility
-      "includes": ["src/lib/db/**/*.ts"],
+      // A few DB modules still have genuinely async functions (stat() for mtime validation,
+      // clearResponseCache for auth cleanup). The useAwait rule is off for these specific files.
+      "includes": [
+        "src/lib/db/dsn-cache.ts",
+        "src/lib/db/project-root-cache.ts",
+        "src/lib/db/auth.ts"
+      ],
       "linter": {
         "rules": {
           "suspicious": {

lint-rules/no-inline-touch-cache.grit

@@ -0,0 +1,7 @@
+file($name, $body) where {
+  $name <: not r".*utils\.ts$",
+  $body <: contains `$db.query($sql).run($args)` as $match where {
+    $sql <: r".*UPDATE .* SET last_accessed.*"
+  },
+  register_diagnostic(span=$match, message="Use touchCacheEntry() from db/utils.js instead of inline last_accessed UPDATE.")
+}

lint-rules/no-manual-transactions.grit

@@ -0,0 +1,12 @@
+file($name, $body) where {
+  $name <: not r".*migration\.ts$",
+  $name <: not r".*node-polyfills\.ts$",
+  $body <: contains `$db.exec($sql)` as $match where {
+    $sql <: or {
+      r".*BEGIN.*",
+      r".*COMMIT.*",
+      r".*ROLLBACK.*"
+    }
+  },
+  register_diagnostic(span=$match, message="Use db.transaction()() instead of manual BEGIN/COMMIT/ROLLBACK.")
+}

lint-rules/no-raw-metadata-queries.grit

@@ -0,0 +1,14 @@
+file($name, $body) where {
+  $name <: not r".*utils\.ts$",
+  $name <: not r".*migration\.ts$",
+  $body <: contains or {
+    `$db.query($sql)` as $match where {
+      $sql <: or {
+        r".*SELECT value FROM metadata.*",
+        r".*DELETE FROM metadata.*"
+      }
+    },
+    `runUpsert($db, "metadata", $data, $keys)` as $match
+  },
+  register_diagnostic(span=$match, message="Use getMetadata/setMetadata/clearMetadata from db/utils.js instead of raw metadata queries.")
+}

src/bin.ts

@@ -39,7 +39,7 @@ async function runCompletion(completionArgs: string[]): Promise<void> {
   // Disable telemetry so db/index.ts skips the @sentry/node-core lazy-require (~280ms)
   process.env.SENTRY_CLI_NO_TELEMETRY = "1";
   const { handleComplete } = await import("./lib/complete.js");
-  await handleComplete(completionArgs);
+  handleComplete(completionArgs);
 }
 
 /**

src/commands/auth/login.ts

@@ -139,7 +139,7 @@ export const loginCommand = buildCommand({
   output: { human: formatLoginResult },
   async *func(this: SentryContext, flags: LoginFlags) {
     // Check if already authenticated and handle re-authentication
-    if (await isAuthenticated()) {
+    if (isAuthenticated()) {
       const shouldProceed = await handleExistingAuth(flags.force);
       if (!shouldProceed) {
         return;

src/commands/auth/logout.ts

@@ -38,7 +38,7 @@ export const logoutCommand = buildCommand({
     flags: {},
   },
   async *func(this: SentryContext) {
-    if (!(await isAuthenticated())) {
+    if (!isAuthenticated()) {
       return yield new CommandOutput({
         loggedOut: false,
         message: "Not currently authenticated.",

src/commands/auth/status.ts

@@ -104,9 +104,9 @@ function collectTokenInfo(
 /**
  * Collect default org/project into the data structure.
  */
-async function collectDefaults(): Promise<AuthStatusData["defaults"]> {
-  const org = await getDefaultOrganization();
-  const project = await getDefaultProject();
+function collectDefaults(): AuthStatusData["defaults"] {
+  const org = getDefaultOrganization();
+  const project = getDefaultProject();
 
   if (!(org || project)) {
     return;
@@ -160,7 +160,7 @@ export const statusCommand = buildCommand({
     applyFreshFlag(flags);
 
     const auth = getAuthConfig();
-    const authenticated = await isAuthenticated();
+    const authenticated = isAuthenticated();
     const fromEnv = auth ? isEnvSource(auth.source) : false;
 
     if (!authenticated) {
@@ -186,7 +186,7 @@ export const statusCommand = buildCommand({
       configPath: fromEnv ? undefined : getDbPath(),
       user,
       token: collectTokenInfo(auth, flags["show-token"]),
-      defaults: await collectDefaults(),
+      defaults: collectDefaults(),
       verification: await verifyCredentials(),
     };
 

src/commands/auth/whoami.ts

@@ -46,7 +46,7 @@ export const whoamiCommand = buildCommand({
   async *func(this: SentryContext, flags: WhoamiFlags) {
     applyFreshFlag(flags);
 
-    if (!(await isAuthenticated())) {
+    if (!isAuthenticated()) {
       throw new AuthError("not_authenticated");
     }