@codexa/cli 9.0.31 → 9.0.32

package/context/generator.ts

@@ -1,4 +1,4 @@
-import { getDb } from "../db/connection";
+import { dbGet, dbAll } from "../db/connection";
 import { initSchema, getPatternsForFiles, getRelatedDecisions, getArchitecturalAnalysisForSpec } from "../db/schema";
 import { getKnowledgeForTask } from "../commands/knowledge";
 import type { ContextSection, ContextData } from "./assembly";
@@ -21,57 +21,55 @@ import {
     buildReferencesSection,
 } from "./sections";
 
-// v9.0: Contexto minimo para subagent (max ~2KB)
 const MAX_MINIMAL_CONTEXT = 2048;
 
-export function getMinimalContextForSubagent(taskId: number): string {
-    initSchema();
-    const db = getDb();
+export async function getMinimalContextForSubagent(taskId: number): Promise<string> {
+    await initSchema();
 
-    const task = db.query("SELECT * FROM tasks WHERE id = ?").get(taskId) as any;
+    const task = await dbGet<any>("SELECT * FROM tasks WHERE id = ?", [taskId]);
     if (!task) return "ERRO: Task nao encontrada";
 
-    const spec = db.query("SELECT * FROM specs WHERE id = ?").get(task.spec_id) as any;
-    const context = db.query("SELECT * FROM context WHERE spec_id = ?").get(task.spec_id) as any;
+    const spec = await dbGet<any>("SELECT * FROM specs WHERE id = ?", [task.spec_id]);
+    const context = await dbGet<any>("SELECT * FROM context WHERE spec_id = ?", [task.spec_id]);
 
     const taskFiles = task.files ? JSON.parse(task.files) : [];
     const domain = domainToScope(getAgentDomain(task.agent));
 
-    // 1. Standards REQUIRED apenas (nao recommended)
-    const requiredStandards = db.query(
+    const requiredStandards = await dbAll<any>(
         `SELECT rule FROM standards
          WHERE enforcement = 'required' AND (scope = 'all' OR scope = ?)
-         LIMIT 10`
-    ).all(domain) as any[];
+         LIMIT 10`,
+        [domain]
+    );
 
-    // 2. Blockers CRITICAL (spec atual + cross-feature)
-    const criticalBlockers = db.query(
+    const criticalBlockers = await dbAll<any>(
         `SELECT DISTINCT content FROM knowledge
          WHERE severity = 'critical'
          ORDER BY CASE WHEN spec_id = ? THEN 0 ELSE 1 END, created_at DESC
-         LIMIT 5`
-    ).all(task.spec_id) as any[];
+         LIMIT 5`,
+        [task.spec_id]
+    );
 
-    // 3. Decisoes da task anterior (dependency direta)
     const dependsOn = task.depends_on ? JSON.parse(task.depends_on) : [];
     let depDecisions: any[] = [];
     if (dependsOn.length > 0) {
         const placeholders = dependsOn.map(() => '?').join(',');
-        const depTasks = db.query(
-            `SELECT id FROM tasks WHERE spec_id = ? AND number IN (${placeholders})`
-        ).all(task.spec_id, ...dependsOn) as any[];
+        const depTasks = await dbAll<any>(
+            `SELECT id FROM tasks WHERE spec_id = ? AND number IN (${placeholders})`,
+            [task.spec_id, ...dependsOn]
+        );
 
         for (const dt of depTasks) {
-            const reasoning = db.query(
+            const reasoning = await dbAll<any>(
                 `SELECT thought FROM reasoning_log
                  WHERE spec_id = ? AND task_id = ? AND category = 'recommendation'
-                 ORDER BY created_at DESC LIMIT 2`
-            ).all(task.spec_id, dt.id) as any[];
+                 ORDER BY created_at DESC LIMIT 2`,
+                [task.spec_id, dt.id]
+            );
             depDecisions.push(...reasoning);
         }
     }
 
-    // Montar output minimo
     let output = `## CONTEXTO MINIMO (Task #${task.number})
 
 **Feature:** ${spec.name}
@@ -100,7 +98,6 @@ export function getMinimalContextForSubagent(taskId: number): string {
   codexa context detail architecture # Analise arquitetural
 `;
 
-    // Truncar se exceder limite
     if (output.length > MAX_MINIMAL_CONTEXT) {
         output = output.substring(0, MAX_MINIMAL_CONTEXT - 100) + "\n\n[CONTEXTO TRUNCADO - use: codexa context detail <secao>]\n";
     }
@@ -108,44 +105,33 @@ export function getMinimalContextForSubagent(taskId: number): string {
     return output;
 }
 
-// ═══════════════════════════════════════════════════════════════
-// CONTEXT BUILDER (v11.0 — inline delivery, no file system)
-// ═══════════════════════════════════════════════════════════════
-
-function fetchContextData(taskId: number): ContextData | null {
-    const db = getDb();
-
-    const task = db.query("SELECT * FROM tasks WHERE id = ?").get(taskId) as any;
+async function fetchContextData(taskId: number): Promise<ContextData | null> {
+    const task = await dbGet<any>("SELECT * FROM tasks WHERE id = ?", [taskId]);
     if (!task) return null;
 
-    const spec = db.query("SELECT * FROM specs WHERE id = ?").get(task.spec_id) as any;
-    const context = db.query("SELECT * FROM context WHERE spec_id = ?").get(task.spec_id) as any;
-    const project = db.query("SELECT * FROM project WHERE id = 'default'").get() as any;
+    const spec = await dbGet<any>("SELECT * FROM specs WHERE id = ?", [task.spec_id]);
+    const context = await dbGet<any>("SELECT * FROM context WHERE spec_id = ?", [task.spec_id]);
+    const project = await dbGet<any>("SELECT * FROM project WHERE id = 'default'");
 
-    // v8.4: Analise arquitetural (link explicito via analysis_id ou nome)
-    const archAnalysis = getArchitecturalAnalysisForSpec(spec.name, task.spec_id);
+    const archAnalysis = await getArchitecturalAnalysisForSpec(spec.name, task.spec_id);
 
-    // Arquivos da task para filtrar contexto relevante
     const taskFiles = task.files ? JSON.parse(task.files) : [];
     const domain = domainToScope(getAgentDomain(task.agent));
 
-    // v11.0: Raised caps — 50 decisions (was 8), filtered by relevance
-    const allDecisions = db
-        .query(`SELECT * FROM decisions WHERE spec_id = ? AND status = 'active' ORDER BY created_at DESC LIMIT 100`)
-        .all(task.spec_id) as any[];
+    const allDecisions = await dbAll<any>(
+        `SELECT * FROM decisions WHERE spec_id = ? AND status = 'active' ORDER BY created_at DESC LIMIT 100`,
+        [task.spec_id]
+    );
     const decisions = filterRelevantDecisions(allDecisions, taskFiles, 50);
 
-    // Standards required + recommended que se aplicam aos arquivos
-    const standards = db
-        .query(
-            `SELECT * FROM standards
+    const standards = await dbAll<any>(
+        `SELECT * FROM standards
        WHERE (scope = 'all' OR scope = ?)
-       ORDER BY enforcement DESC, category`
-        )
-        .all(domain) as any[];
+       ORDER BY enforcement DESC, category`,
+        [domain]
+    );
     const relevantStandards = filterRelevantStandards(standards, taskFiles);
 
-    // v11.0: Raised caps — 50 critical (was 20), 30 info (was 10)
     const allKnowledge = getKnowledgeForTask(task.spec_id, taskId);
     const allCriticalKnowledge = allKnowledge.filter((k: any) => k.severity === 'critical' || k.severity === 'warning');
     const criticalKnowledge = allCriticalKnowledge.slice(0, 50);
@@ -154,46 +140,48 @@ function fetchContextData(taskId: number): ContextData | null {
     const infoKnowledge = allInfoKnowledge.slice(0, 30);
     const truncatedInfo = allInfoKnowledge.length - infoKnowledge.length;
 
-    const productContext = db.query("SELECT * FROM product_context WHERE id = 'default'").get() as any;
-    const patterns = getPatternsForFiles(taskFiles);
+    const productContext = await dbGet<any>("SELECT * FROM product_context WHERE id = 'default'");
+    const patterns = await getPatternsForFiles(taskFiles);
 
-    // v8.2: Reasoning de tasks dependentes + todas tasks completas recentes
     const dependsOn = task.depends_on ? JSON.parse(task.depends_on) : [];
     const depReasoning: any[] = [];
     const seenTaskIds = new Set<number>();
 
     if (dependsOn.length > 0) {
         const placeholders = dependsOn.map(() => '?').join(',');
-        const depTasks = db.query(
-            `SELECT id, number FROM tasks WHERE spec_id = ? AND number IN (${placeholders})`
-        ).all(task.spec_id, ...dependsOn) as any[];
+        const depTasks = await dbAll<any>(
+            `SELECT id, number FROM tasks WHERE spec_id = ? AND number IN (${placeholders})`,
+            [task.spec_id, ...dependsOn]
+        );
 
         for (const depTask of depTasks) {
             seenTaskIds.add(depTask.id);
-            const reasoning = db.query(
+            const reasoning = await dbAll<any>(
                 `SELECT category, thought FROM reasoning_log
                  WHERE spec_id = ? AND task_id = ?
                  AND category IN ('recommendation', 'decision', 'challenge')
                  ORDER BY
                    CASE importance WHEN 'critical' THEN 1 WHEN 'high' THEN 2 ELSE 3 END,
                    created_at DESC
-                 LIMIT 3`
-            ).all(task.spec_id, depTask.id) as any[];
+                 LIMIT 3`,
+                [task.spec_id, depTask.id]
+            );
             for (const r of reasoning) {
                 depReasoning.push({ ...r, fromTask: depTask.number });
             }
         }
     }
 
-    const completedTasks = db.query(
+    const completedTasks = await dbAll<any>(
         `SELECT t.id, t.number FROM tasks t
          WHERE t.spec_id = ? AND t.status = 'done' AND t.id != ?
-         ORDER BY t.completed_at DESC LIMIT 10`
-    ).all(task.spec_id, taskId) as any[];
+         ORDER BY t.completed_at DESC LIMIT 10`,
+        [task.spec_id, taskId]
+    );
 
     for (const ct of completedTasks) {
         if (seenTaskIds.has(ct.id)) continue;
-        const reasoning = db.query(
+        const reasoning = await dbAll<any>(
             `SELECT category, thought FROM reasoning_log
              WHERE spec_id = ? AND task_id = ?
              AND category IN ('recommendation', 'challenge')
@@ -201,21 +189,22 @@ function fetchContextData(taskId: number): ContextData | null {
              ORDER BY
                CASE importance WHEN 'critical' THEN 1 ELSE 2 END,
                created_at DESC
-             LIMIT 2`
-        ).all(task.spec_id, ct.id) as any[];
+             LIMIT 2`,
+            [task.spec_id, ct.id]
+        );
         for (const r of reasoning) {
             depReasoning.push({ ...r, fromTask: ct.number });
         }
     }
 
-    const libContexts = db.query(
+    const libContexts = await dbAll<any>(
         "SELECT lib_name, version FROM lib_contexts ORDER BY lib_name LIMIT 10"
-    ).all() as any[];
+    );
 
     const graphDecisions: any[] = [];
     for (const file of taskFiles) {
         try {
-            const related = getRelatedDecisions(file, "file");
+            const related = await getRelatedDecisions(file, "file");
             for (const d of related) {
                 if (!graphDecisions.find((gd: any) => gd.id === d.id)) {
                     graphDecisions.push(d);
@@ -227,7 +216,7 @@ function fetchContextData(taskId: number): ContextData | null {
     const discoveredPatterns = context?.patterns ? JSON.parse(context.patterns) : [];
 
     return {
-        db, task, spec, context, project, taskFiles, domain, archAnalysis,
+        task, spec, context, project, taskFiles, domain, archAnalysis,
         decisions, allDecisions, relevantStandards,
         criticalKnowledge, truncatedCritical, infoKnowledge, truncatedInfo,
         productContext, patterns, depReasoning, libContexts,
@@ -235,10 +224,8 @@ function fetchContextData(taskId: number): ContextData | null {
     };
 }
 
-// ── Main Entry Point ──────────────────────────────────────────
-
-function buildContext(taskId: number): { content: string; data: ContextData } | null {
-    const data = fetchContextData(taskId);
+async function buildContext(taskId: number): Promise<{ content: string; data: ContextData } | null> {
+    const data = await fetchContextData(taskId);
     if (!data) return null;
 
     const header = `## CONTEXTO (Task #${data.task.number})
@@ -258,10 +245,10 @@ function buildContext(taskId: number): { content: string; data: ContextData } |
         buildAlertsSection(data),
         buildDiscoveriesSection(data),
         buildPatternsSection(data),
-        buildUtilitiesSection(data),
+        await buildUtilitiesSection(data),
         buildGraphSection(data),
         buildStackSection(data),
-        buildHintsSection(data),
+        await buildHintsSection(data),
     ].filter((s): s is ContextSection => s !== null);
 
     const agentDomain = getAgentDomain(data.task.agent);
@@ -270,8 +257,8 @@ function buildContext(taskId: number): { content: string; data: ContextData } |
     return { content: assembleSections(header, sections), data };
 }
 
-export function getContextForSubagent(taskId: number): string {
-    initSchema();
-    const result = buildContext(taskId);
+export async function getContextForSubagent(taskId: number): Promise<string> {
+    await initSchema();
+    const result = await buildContext(taskId);
     return result?.content || "ERRO: Task nao encontrada";
 }

package/context/sections.ts

@@ -1,10 +1,9 @@
+import { dbGet } from "../db/connection";
 import { getUtilitiesForContext, getAgentHints } from "../db/schema";
 import type { ContextSection, ContextData } from "./assembly";
 import { getAgentDomain, domainToScope } from "./domains";
 import { findReferenceFiles } from "./references";
 
-// ── Section Builders ──────────────────────────────────────────
-
 export function buildProductSection(data: ContextData): ContextSection | null {
     if (!data.productContext) return null;
 
@@ -42,8 +41,6 @@ export function buildProductSection(data: ContextData): ContextSection | null {
 
     content += "\n";
 
-    // v10.2: Product context is small (~500-2000 bytes) but high-impact.
-    // Priority 1 ensures it is NEVER truncated.
     return { name: "PRODUTO", content, priority: 1 };
 }
 
@@ -114,7 +111,6 @@ export function buildStandardsSection(data: ContextData): ContextSection {
 }
 
 export function buildDecisionsSection(data: ContextData): ContextSection {
-    // v11.0: Show all decisions (raised cap to 50 in generator)
     const decisionsToShow = data.allDecisions;
     const truncatedDecisions = data.allDecisions.length - decisionsToShow.length;
     const content = `
@@ -170,7 +166,6 @@ ${data.patterns.map((p: any) => {
     }
 
     if (data.discoveredPatterns.length > 0) {
-        // v11.0: Show all discovered patterns (no cap)
         content += `
 ### PATTERNS DESCOBERTOS (${data.discoveredPatterns.length})
 ${data.discoveredPatterns.map((p: any) => `- ${p.pattern}${p.source_task ? ` (Task #${p.source_task})` : ""}`).join("\n")}
@@ -181,7 +176,7 @@ ${data.discoveredPatterns.map((p: any) => `- ${p.pattern}${p.source_task ? ` (Ta
     return { name: "PATTERNS", content, priority: 9 };
 }
 
-export function buildUtilitiesSection(data: ContextData): ContextSection | null {
+export async function buildUtilitiesSection(data: ContextData): Promise<ContextSection | null> {
     try {
         const taskDirs = [...new Set(data.taskFiles.map((f: string) => {
             const parts = f.replace(/\\/g, "/").split("/");
@@ -189,12 +184,11 @@ export function buildUtilitiesSection(data: ContextData): ContextSection | null
         }).filter(Boolean))];
 
         const agentScope = domainToScope(getAgentDomain(data.task.agent)) || undefined;
-        // v11.0: Raised cap to 50 (was 15)
         const utilLimit = 50;
-        let relevantUtilities = getUtilitiesForContext(taskDirs, undefined, utilLimit);
+        let relevantUtilities = await getUtilitiesForContext(taskDirs, undefined, utilLimit);
 
         if (relevantUtilities.length < 5 && agentScope) {
-            const scopeUtils = getUtilitiesForContext([], agentScope, 15);
+            const scopeUtils = await getUtilitiesForContext([], agentScope, 15);
             const existingKeys = new Set(relevantUtilities.map((u: any) => `${u.file_path}:${u.utility_name}`));
             for (const u of scopeUtils) {
                 if (!existingKeys.has(`${u.file_path}:${u.utility_name}`)) {
@@ -206,7 +200,8 @@ export function buildUtilitiesSection(data: ContextData): ContextSection | null
 
         if (relevantUtilities.length === 0) return null;
 
-        const totalCount = (data.db.query("SELECT COUNT(*) as c FROM project_utilities").get() as any)?.c || 0;
+        const totalCountRow = await dbGet<any>("SELECT COUNT(*) as c FROM project_utilities");
+        const totalCount = totalCountRow?.c || 0;
         const truncated = totalCount - relevantUtilities.length;
         const content = `
 ### UTILITIES EXISTENTES (${relevantUtilities.length}${truncated > 0 ? ` [+${truncated} mais]` : ''})
@@ -241,7 +236,6 @@ export function buildStackSection(data: ContextData): ContextSection | null {
     if (data.project) {
         const stack = JSON.parse(data.project.stack);
         const allStackEntries = Object.entries(stack);
-        // v11.0: Show all stack entries (no cap)
         const mainStack = allStackEntries;
         const truncatedStack = allStackEntries.length - mainStack.length;
         content += `
@@ -261,11 +255,11 @@ ${data.libContexts.map((l: any) => `- ${l.lib_name}${l.version ? ` v${l.version}
     return { name: "STACK", content, priority: 11 };
 }
 
-export function buildHintsSection(data: ContextData): ContextSection | null {
+export async function buildHintsSection(data: ContextData): Promise<ContextSection | null> {
     const agentType = data.task.agent;
     if (!agentType) return null;
 
-    const hints = getAgentHints(agentType);
+    const hints = await getAgentHints(agentType);
     if (hints.length === 0) return null;
 
     const content = `

package/db/connection.ts

@@ -1,32 +1,208 @@
-import { Database } from "bun:sqlite";
+import { createClient, type Client, type InValue } from "@libsql/client";
+import { execSync } from "child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "fs";
 import { join, dirname } from "path";
-import { mkdirSync, existsSync } from "fs";
 
-const DB_PATH = join(process.cwd(), ".codexa", "db", "workflow.db");
+let client: Client | null = null;
 
-let db: Database | null = null;
+// ═══════════════════════════════════════════════════════════════
+// Resolucao de DB URL: env → config local → derivacao do git
+// ═══════════════════════════════════════════════════════════════
 
-export function getDb(): Database {
-  if (!db) {
-    // Garantir que o diretorio existe
-    const dbDir = dirname(DB_PATH);
-    if (!existsSync(dbDir)) {
-      mkdirSync(dbDir, { recursive: true });
+function resolveDbUrl(): string {
+  // 1. Override explicito via env var
+  if (process.env.CODEXA_DB_URL) return process.env.CODEXA_DB_URL;
+
+  // 2. Cache local (.codexa/config.json)
+  const configPath = join(process.cwd(), ".codexa", "config.json");
+  if (existsSync(configPath)) {
+    try {
+      const config = JSON.parse(readFileSync(configPath, "utf-8"));
+      if (config.database) return config.database;
+    } catch { /* config invalido, continuar */ }
+  }
+
+  // 3. Derivar do git remote
+  const org = process.env.TURSO_ORG;
+  if (!org) {
+    throw new Error(
+      "Banco de dados nao configurado.\n\n" +
+      "Opcao 1 — Configurar automaticamente:\n" +
+      "  export TURSO_ORG=sua-org\n" +
+      "  export TURSO_AUTH_TOKEN=eyJ...\n" +
+      "  codexa init\n\n" +
+      "Opcao 2 — Configurar manualmente:\n" +
+      "  export CODEXA_DB_URL=libsql://seu-db.turso.io\n" +
+      "  export TURSO_AUTH_TOKEN=eyJ..."
+    );
+  }
+
+  const slug = deriveSlugFromGit();
+  const url = `libsql://codexa-${slug}-${org}.turso.io`;
+
+  // Salvar no cache para proximas execucoes
+  saveConfig(configPath, url);
+
+  return url;
+}
+
+function deriveSlugFromGit(): string {
+  try {
+    const remote = execSync("git remote get-url origin", { encoding: "utf-8" }).trim();
+    // github.com/leandro/meu-saas.git → leandro--meu-saas
+    // git@github.com:leandro/meu-saas.git → leandro--meu-saas
+    const match = remote.match(/[/:]([^/]+)\/([^/]+?)(?:\.git)?$/);
+    if (match) {
+      return `${match[1]}--${match[2]}`.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+    }
+  } catch { /* git nao disponivel */ }
+
+  // Fallback: nome da pasta atual
+  const dirName = process.cwd().split(/[/\\]/).pop() || "unknown";
+  return dirName.toLowerCase().replace(/[^a-z0-9-]/g, "-");
+}
+
+function saveConfig(configPath: string, url: string): void {
+  try {
+    const dir = dirname(configPath);
+    if (!existsSync(dir)) {
+      mkdirSync(dir, { recursive: true });
+    }
+    writeFileSync(configPath, JSON.stringify({ database: url }, null, 2) + "\n");
+  } catch { /* falha ao salvar cache, nao e critico */ }
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Provisioning: cria o DB no Turso se nao existir
+// ═══════════════════════════════════════════════════════════════
+
+export async function ensureDatabase(): Promise<void> {
+  const url = resolveDbUrl();
+
+  // Somente provisionar para URLs Turso (nao para file: ou :memory:)
+  if (!url.startsWith("libsql://")) return;
+
+  const authToken = process.env.TURSO_AUTH_TOKEN;
+  const org = process.env.TURSO_ORG;
+  if (!authToken || !org) return;
+
+  // Extrair nome do DB da URL: libsql://codexa-slug-org.turso.io → codexa-slug
+  const hostMatch = url.match(/^libsql:\/\/(.+)-[^-]+\.turso\.io$/);
+  if (!hostMatch) return;
+  const dbName = hostMatch[1];
+
+  // Tentar conectar primeiro — se o DB ja existe, nao precisa criar
+  try {
+    const testClient = createClient({ url, authToken });
+    await testClient.execute("SELECT 1");
+    testClient.close();
+    return;
+  } catch { /* DB nao existe, criar */ }
+
+  // Criar via Turso Platform API
+  const group = process.env.TURSO_GROUP || "default";
+  try {
+    const response = await fetch(
+      `https://api.turso.tech/v1/organizations/${org}/databases`,
+      {
+        method: "POST",
+        headers: {
+          "Authorization": `Bearer ${authToken}`,
+          "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ name: dbName, group }),
+      }
+    );
+
+    if (response.ok) {
+      console.log(`[codexa] Banco criado no Turso: ${dbName}`);
+    } else if (response.status === 409) {
+      // Ja existe — tudo certo
+    } else {
+      const body = await response.text();
+      console.error(`[codexa] Falha ao criar banco: ${response.status} ${body}`);
     }
-    db = new Database(DB_PATH, { create: true });
-    db.exec("PRAGMA journal_mode = WAL");
-    db.exec("PRAGMA foreign_keys = ON");
+  } catch (e: any) {
+    console.error(`[codexa] Erro ao provisionar banco: ${e.message}`);
   }
-  return db;
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Client management
+// ═══════════════════════════════════════════════════════════════
+
+export function getDb(): Client {
+  if (!client) {
+    const url = resolveDbUrl();
+    const authToken = process.env.TURSO_AUTH_TOKEN;
+
+    client = createClient({
+      url,
+      authToken: authToken || undefined,
+    });
+  }
+  return client;
 }
 
 export function closeDb(): void {
-  if (db) {
-    db.close();
-    db = null;
+  if (client) {
+    client.close();
+    client = null;
   }
 }
 
-export function getDbPath(): string {
-  return DB_PATH;
+export function resetClient(): void {
+  client = null;
+}
+
+export function setClient(c: Client): void {
+  client = c;
+}
+
+export function getResolvedDbUrl(): string {
+  return resolveDbUrl();
+}
+
+// ═══════════════════════════════════════════════════════════════
+// Helpers: drop-in async replacements for bun:sqlite patterns
+// ═══════════════════════════════════════════════════════════════
+
+type Args = InValue[];
+
+export async function dbGet<T = any>(sql: string, args: Args = []): Promise<T | null> {
+  const db = getDb();
+  const result = await db.execute({ sql, args });
+  return (result.rows[0] as T) ?? null;
+}
+
+export async function dbAll<T = any>(sql: string, args: Args = []): Promise<T[]> {
+  const db = getDb();
+  const result = await db.execute({ sql, args });
+  return result.rows as T[];
+}
+
+export async function dbRun(sql: string, args: Args = []): Promise<{ changes: number; lastInsertRowid: bigint | undefined }> {
+  const db = getDb();
+  const result = await db.execute({ sql, args });
+  return { changes: result.rowsAffected, lastInsertRowid: result.lastInsertRowid };
+}
+
+export async function dbExec(sql: string): Promise<void> {
+  const db = getDb();
+  const statements = sql
+    .split(";")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0 && !s.startsWith("--"));
+
+  if (statements.length === 0) return;
+
+  if (statements.length === 1) {
+    await db.execute(statements[0]);
+    return;
+  }
+
+  await db.batch(
+    statements.map((s) => ({ sql: s, args: [] })),
+    "write"
+  );
 }