popilot 0.5.0 → 0.7.0

package/scaffold/pm-api/sql/schema-core.sql

@@ -0,0 +1,331 @@
+-- PM API Core Schema
+-- Run this SQL to initialize the database
+
+-- Authentication
+CREATE TABLE IF NOT EXISTS auth_tokens (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_name TEXT NOT NULL,
+  token TEXT NOT NULL UNIQUE,
+  is_active INTEGER DEFAULT 1,
+  expires_at TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Team Members
+CREATE TABLE IF NOT EXISTS members (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  display_name TEXT NOT NULL UNIQUE,
+  role TEXT DEFAULT 'member',
+  is_active INTEGER DEFAULT 1,
+  webhook_url TEXT,
+  wallet_address TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Sprints
+CREATE TABLE IF NOT EXISTS nav_sprints (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  theme TEXT,
+  status TEXT DEFAULT 'planning',
+  active INTEGER DEFAULT 0,
+  start_date TEXT,
+  end_date TEXT,
+  velocity INTEGER,
+  team_size INTEGER,
+  sort_order INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Sprint Members
+CREATE TABLE IF NOT EXISTS sprint_members (
+  sprint_id TEXT NOT NULL,
+  member_id INTEGER NOT NULL,
+  working_days INTEGER DEFAULT 0,
+  PRIMARY KEY (sprint_id, member_id),
+  FOREIGN KEY (sprint_id) REFERENCES nav_sprints(id),
+  FOREIGN KEY (member_id) REFERENCES members(id)
+);
+
+-- Member Absences
+CREATE TABLE IF NOT EXISTS member_absences (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  sprint_id TEXT NOT NULL,
+  member_id INTEGER NOT NULL,
+  absence_date TEXT NOT NULL,
+  reason TEXT,
+  UNIQUE(sprint_id, member_id, absence_date),
+  FOREIGN KEY (sprint_id) REFERENCES nav_sprints(id),
+  FOREIGN KEY (member_id) REFERENCES members(id)
+);
+
+-- Epics
+CREATE TABLE IF NOT EXISTS pm_epics (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  description TEXT,
+  owner TEXT,
+  status TEXT DEFAULT 'active',
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Stories
+CREATE TABLE IF NOT EXISTS pm_stories (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  epic_id INTEGER,
+  epic_uid TEXT,
+  sprint TEXT,
+  title TEXT NOT NULL,
+  description TEXT,
+  acceptance_criteria TEXT,
+  assignee TEXT,
+  assignee_id INTEGER,
+  status TEXT DEFAULT 'backlog',
+  priority TEXT DEFAULT 'medium',
+  area TEXT DEFAULT 'FE',
+  story_points INTEGER,
+  figma_url TEXT,
+  sort_order INTEGER DEFAULT 0,
+  start_date TEXT,
+  due_date TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (epic_id) REFERENCES pm_epics(id),
+  FOREIGN KEY (sprint) REFERENCES nav_sprints(id),
+  FOREIGN KEY (assignee_id) REFERENCES members(id)
+);
+
+-- Tasks
+CREATE TABLE IF NOT EXISTS pm_tasks (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  story_id INTEGER NOT NULL,
+  title TEXT NOT NULL,
+  assignee TEXT,
+  assignee_id INTEGER,
+  status TEXT DEFAULT 'todo',
+  description TEXT,
+  story_points INTEGER,
+  sort_order INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (story_id) REFERENCES pm_stories(id),
+  FOREIGN KEY (assignee_id) REFERENCES members(id)
+);
+
+-- Standup Entries
+CREATE TABLE IF NOT EXISTS pm_standup_entries (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  sprint TEXT NOT NULL,
+  user_name TEXT NOT NULL,
+  entry_date TEXT NOT NULL,
+  done_text TEXT,
+  plan_text TEXT,
+  plan_story_ids TEXT,
+  blockers TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  UNIQUE(sprint, user_name, entry_date)
+);
+
+-- Standup Feedback
+CREATE TABLE IF NOT EXISTS pm_standup_feedback (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  standup_entry_id INTEGER NOT NULL,
+  sprint TEXT NOT NULL,
+  target_user TEXT NOT NULL,
+  feedback_by TEXT NOT NULL,
+  feedback_text TEXT NOT NULL,
+  review_type TEXT DEFAULT 'comment',
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (standup_entry_id) REFERENCES pm_standup_entries(id)
+);
+
+-- Memos v2
+CREATE TABLE IF NOT EXISTS memos_v2 (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  page_id TEXT DEFAULT 'home',
+  content TEXT NOT NULL,
+  memo_type TEXT DEFAULT 'memo',
+  title TEXT,
+  created_by TEXT NOT NULL,
+  created_by_id INTEGER,
+  assigned_to TEXT,
+  assigned_to_id INTEGER,
+  status TEXT DEFAULT 'open',
+  resolved_by TEXT,
+  resolved_at TEXT,
+  related_decisions TEXT,
+  review_required INTEGER DEFAULT 0,
+  supersedes_id INTEGER,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Memo Replies
+CREATE TABLE IF NOT EXISTS memo_replies (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  memo_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  created_by TEXT NOT NULL,
+  review_type TEXT DEFAULT 'comment',
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (memo_id) REFERENCES memos_v2(id)
+);
+
+-- Notifications
+CREATE TABLE IF NOT EXISTS notifications (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_name TEXT NOT NULL,
+  type TEXT NOT NULL,
+  title TEXT NOT NULL,
+  body TEXT,
+  source_type TEXT,
+  source_id TEXT,
+  page_id TEXT,
+  actor TEXT,
+  is_read INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Initiatives
+CREATE TABLE IF NOT EXISTS initiatives (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  content TEXT NOT NULL,
+  author TEXT NOT NULL,
+  decider TEXT,
+  status TEXT DEFAULT 'pending',
+  decision_note TEXT,
+  decided_at TEXT,
+  source_context TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Retro Sessions
+CREATE TABLE IF NOT EXISTS retro_sessions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  sprint TEXT NOT NULL UNIQUE,
+  title TEXT DEFAULT 'Sprint Retrospective',
+  phase TEXT DEFAULT 'collect',
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Retro Items
+CREATE TABLE IF NOT EXISTS retro_items (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id INTEGER NOT NULL,
+  category TEXT NOT NULL,
+  content TEXT NOT NULL,
+  author TEXT NOT NULL,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (session_id) REFERENCES retro_sessions(id)
+);
+
+-- Retro Votes
+CREATE TABLE IF NOT EXISTS retro_votes (
+  item_id INTEGER NOT NULL,
+  voter TEXT NOT NULL,
+  PRIMARY KEY (item_id, voter),
+  FOREIGN KEY (item_id) REFERENCES retro_items(id)
+);
+
+-- Retro Actions
+CREATE TABLE IF NOT EXISTS retro_actions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  session_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  assignee TEXT,
+  status TEXT DEFAULT 'todo',
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (session_id) REFERENCES retro_sessions(id)
+);
+
+-- Agent Events (Push-Native)
+CREATE TABLE IF NOT EXISTS agent_events (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  event_type TEXT NOT NULL,
+  source_agent TEXT NOT NULL,
+  target_agent TEXT NOT NULL,
+  target_user TEXT NOT NULL,
+  payload TEXT NOT NULL,
+  status TEXT DEFAULT 'pending',
+  expires_at TEXT,
+  delivered_at TEXT,
+  acked_at TEXT,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Activity Log
+CREATE TABLE IF NOT EXISTS activity_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  actor TEXT NOT NULL,
+  action_type TEXT NOT NULL,
+  target_type TEXT NOT NULL,
+  target_id TEXT NOT NULL,
+  target_title TEXT,
+  metadata TEXT,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Nudge Log
+CREATE TABLE IF NOT EXISTS nudge_log (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  rule_id TEXT NOT NULL,
+  title TEXT NOT NULL,
+  body TEXT,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Navigation Pages (for spec-site wireframes/screens)
+CREATE TABLE IF NOT EXISTS nav_pages (
+  id TEXT PRIMARY KEY,
+  title TEXT NOT NULL,
+  icon TEXT,
+  sort_order INTEGER DEFAULT 0,
+  parent_id TEXT,
+  is_visible INTEGER DEFAULT 1,
+  created_at TEXT DEFAULT (datetime('now'))
+);
+
+-- Page Content (spec-site page sections)
+CREATE TABLE IF NOT EXISTS page_content (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  page_id TEXT NOT NULL,
+  sprint TEXT,
+  section_type TEXT DEFAULT 'content',
+  content TEXT,
+  sort_order INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (page_id) REFERENCES nav_pages(id)
+);
+
+-- Scenarios (spec-site scenario definitions)
+CREATE TABLE IF NOT EXISTS scenarios (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  page_id TEXT NOT NULL,
+  sprint TEXT,
+  name TEXT NOT NULL,
+  description TEXT,
+  is_default INTEGER DEFAULT 0,
+  sort_order INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (page_id) REFERENCES nav_pages(id)
+);
+
+-- Story Comments
+CREATE TABLE IF NOT EXISTS story_comments (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  story_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  created_by TEXT NOT NULL,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (story_id) REFERENCES pm_stories(id)
+);

package/scaffold/pm-api/sql/schema-docs.sql

@@ -0,0 +1,25 @@
+-- Docs Module (Optional)
+-- Enable via project.yaml: operations.pm_api.features.docs = true
+
+CREATE TABLE IF NOT EXISTS docs (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  title TEXT NOT NULL,
+  slug TEXT UNIQUE,
+  content TEXT,
+  doc_type TEXT DEFAULT 'general',
+  category TEXT,
+  author TEXT NOT NULL,
+  is_published INTEGER DEFAULT 0,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);
+
+CREATE TABLE IF NOT EXISTS doc_versions (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  doc_id INTEGER NOT NULL,
+  content TEXT NOT NULL,
+  version INTEGER NOT NULL,
+  created_by TEXT NOT NULL,
+  created_at TEXT DEFAULT (datetime('now')),
+  FOREIGN KEY (doc_id) REFERENCES docs(id)
+);

package/scaffold/pm-api/sql/schema-meetings.sql

@@ -0,0 +1,17 @@
+-- Meetings Module (Optional)
+-- Enable via project.yaml: operations.pm_api.features.meetings = true
+
+CREATE TABLE IF NOT EXISTS meetings (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  sprint TEXT,
+  title TEXT NOT NULL,
+  meeting_type TEXT DEFAULT 'general',
+  meeting_date TEXT NOT NULL,
+  attendees TEXT,
+  agenda TEXT,
+  notes TEXT,
+  action_items TEXT,
+  created_by TEXT NOT NULL,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);

package/scaffold/pm-api/sql/schema-rewards.sql

@@ -0,0 +1,16 @@
+-- Rewards Module (Optional)
+-- Enable via project.yaml: operations.pm_api.features.rewards = true
+
+CREATE TABLE IF NOT EXISTS rewards (
+  id INTEGER PRIMARY KEY AUTOINCREMENT,
+  member_name TEXT NOT NULL,
+  type TEXT NOT NULL CHECK (type IN ('reward', 'penalty')),
+  amount REAL NOT NULL,
+  reason TEXT NOT NULL,
+  status TEXT DEFAULT 'pending' CHECK (status IN ('pending', 'paid', 'cancelled')),
+  issued_by TEXT NOT NULL,
+  tx_hash TEXT,
+  paid_at TEXT,
+  created_at TEXT DEFAULT (datetime('now')),
+  updated_at TEXT DEFAULT (datetime('now'))
+);

package/scaffold/pm-api/src/auth.ts

@@ -0,0 +1,28 @@
+import type { Context, Next } from 'hono'
+import type { AppEnv } from './types.js'
+import { query } from './db/adapter.js'
+
+export async function authMiddleware(c: Context<AppEnv>, next: Next) {
+  const header = c.req.header('Authorization')
+  if (!header?.startsWith('Bearer ')) {
+    return c.json({ error: 'Missing or invalid Authorization header' }, 401)
+  }
+
+  const token = header.slice(7)
+  const result = await query<{ user_name: string }>(
+    `SELECT user_name FROM auth_tokens
+     WHERE token = ? AND is_active = 1
+     AND (expires_at IS NULL OR expires_at > datetime('now'))`,
+    [token],
+  )
+
+  if (result.error) {
+    return c.json({ error: 'Auth verification failed' }, 500)
+  }
+  if (result.rows.length === 0) {
+    return c.json({ error: 'Invalid or expired token' }, 401)
+  }
+
+  c.set('userName', result.rows[0].user_name)
+  await next()
+}

package/scaffold/pm-api/src/blockchain/adapter.ts

@@ -0,0 +1,20 @@
+/**
+ * Blockchain adapter interface — provider-agnostic balance query layer.
+ * Implementations: TronAdapter, (future: EthAdapter, SolanaAdapter)
+ */
+
+export interface BlockchainAdapter {
+  getBalance(address: string): Promise<{ native: number; token: number }>
+  getTokenName(): string
+  getNativeName(): string
+}
+
+let _adapter: BlockchainAdapter | null = null
+
+export function setBlockchainAdapter(adapter: BlockchainAdapter) {
+  _adapter = adapter
+}
+
+export function getBlockchainAdapter(): BlockchainAdapter | null {
+  return _adapter
+}

package/scaffold/pm-api/src/blockchain/tron.ts

@@ -0,0 +1,62 @@
+import type { BlockchainAdapter } from './adapter.js'
+
+const ALPHABET = '123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz'
+
+function base58ToHex(addr: string): string {
+  let num = 0n
+  for (const c of addr) {
+    const idx = ALPHABET.indexOf(c)
+    if (idx < 0) throw new Error(`Invalid base58 char: ${c}`)
+    num = num * 58n + BigInt(idx)
+  }
+  const hex = num.toString(16).padStart(50, '0')
+  return hex.slice(0, 42)
+}
+
+export class TronAdapter implements BlockchainAdapter {
+  private contractAddress: string
+  private tokenName: string
+  private tokenDecimals: number
+
+  constructor(opts: { contractAddress: string; tokenName: string; tokenDecimals?: number }) {
+    this.contractAddress = opts.contractAddress
+    this.tokenName = opts.tokenName
+    this.tokenDecimals = opts.tokenDecimals ?? 8
+  }
+
+  getTokenName(): string { return this.tokenName }
+  getNativeName(): string { return 'TRX' }
+
+  async getBalance(address: string): Promise<{ native: number; token: number }> {
+    try {
+      const addrHex = base58ToHex(address)
+      const contractHex = base58ToHex(this.contractAddress)
+
+      const [trxRes, balanceRes] = await Promise.all([
+        fetch(`https://api.trongrid.io/v1/accounts/${address}`),
+        fetch('https://api.trongrid.io/wallet/triggerconstantcontract', {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({
+            owner_address: addrHex,
+            contract_address: contractHex,
+            function_selector: 'balanceOf(address)',
+            parameter: addrHex.slice(2).padStart(64, '0'),
+          }),
+        }),
+      ])
+
+      const trxData = await trxRes.json() as any
+      const balanceData = await balanceRes.json() as any
+
+      const native = (trxData.data?.[0]?.balance ?? 0) / 1_000_000
+      const token = balanceData.constant_result?.[0]
+        ? parseInt(balanceData.constant_result[0], 16) / 10 ** this.tokenDecimals
+        : 0
+
+      return { native, token }
+    } catch {
+      return { native: 0, token: 0 }
+    }
+  }
+}

package/scaffold/pm-api/src/db/adapter.ts

@@ -0,0 +1,36 @@
+/**
+ * Database adapter interface — provider-agnostic query layer.
+ * Implementations: TursoAdapter, (future: SupabaseAdapter, SqliteAdapter)
+ */
+
+export type ArgValue = string | number | null
+
+export interface DbAdapter {
+  query<T = Record<string, unknown>>(sql: string, args?: ArgValue[]): Promise<{ rows: T[]; error?: string }>
+  execute(sql: string, args?: ArgValue[]): Promise<{ rowsAffected: number; error?: string }>
+}
+
+let _adapter: DbAdapter | null = null
+
+export function setAdapter(adapter: DbAdapter) {
+  _adapter = adapter
+}
+
+export function getAdapter(): DbAdapter {
+  if (!_adapter) throw new Error('DB adapter not initialized. Call setAdapter() first.')
+  return _adapter
+}
+
+export async function query<T = Record<string, unknown>>(
+  sql: string,
+  args: ArgValue[] = [],
+): Promise<{ rows: T[]; error?: string }> {
+  return getAdapter().query<T>(sql, args)
+}
+
+export async function execute(
+  sql: string,
+  args: ArgValue[] = [],
+): Promise<{ rowsAffected: number; error?: string }> {
+  return getAdapter().execute(sql, args)
+}

package/scaffold/pm-api/src/db/turso.ts

@@ -0,0 +1,147 @@
+/**
+ * Turso HTTP API v2 (/v2/pipeline) adapter
+ * Workers environment: setTursoEnv() injects bindings per request
+ */
+
+import type { DbAdapter, ArgValue } from './adapter.js'
+
+interface HranaValue {
+  type: 'text' | 'integer' | 'float' | 'null'
+  value?: string
+}
+
+function toHranaArg(v: ArgValue): HranaValue {
+  if (v === null) return { type: 'null' }
+  if (typeof v === 'number') {
+    return Number.isInteger(v)
+      ? { type: 'integer', value: String(v) }
+      : { type: 'float', value: String(v) }
+  }
+  return { type: 'text', value: String(v) }
+}
+
+interface PipelineResult {
+  results: Array<{
+    type: 'ok' | 'error'
+    response?: {
+      type: string
+      result?: {
+        cols: Array<{ name: string }>
+        rows: Array<Array<HranaValue>>
+        affected_row_count: number
+        last_insert_rowid: string | null
+      }
+    }
+    error?: { message: string }
+  }>
+}
+
+export class TursoAdapter implements DbAdapter {
+  private url: string
+  private token: string
+
+  constructor(url: string, token: string) {
+    this.url = url
+    this.token = token
+  }
+
+  async query<T = Record<string, unknown>>(
+    sql: string,
+    args: ArgValue[] = [],
+  ): Promise<{ rows: T[]; error?: string }> {
+    if (!this.url || !this.token) {
+      return { rows: [], error: 'Missing TURSO_URL or TURSO_AUTH_TOKEN' }
+    }
+
+    try {
+      const resp = await fetch(this.url + '/v2/pipeline', {
+        method: 'POST',
+        headers: {
+          Authorization: 'Bearer ' + this.token,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          requests: [
+            { type: 'execute', stmt: { sql, args: args.map(toHranaArg) } },
+            { type: 'close' },
+          ],
+        }),
+      })
+
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => '')
+        return { rows: [], error: `HTTP ${resp.status}: ${text}` }
+      }
+
+      const data: PipelineResult = await resp.json()
+      const first = data.results[0]
+
+      if (first.type === 'error') {
+        return { rows: [], error: first.error?.message ?? 'Unknown error' }
+      }
+
+      const result = first.response?.result
+      if (!result) return { rows: [] }
+
+      const colNames = result.cols.map(c => c.name)
+      const rows = result.rows.map(row => {
+        const obj: Record<string, unknown> = {}
+        colNames.forEach((col, i) => {
+          const cell = row[i]
+          if (cell.type === 'null') obj[col] = null
+          else if (cell.type === 'integer') obj[col] = Number(cell.value)
+          else if (cell.type === 'float') obj[col] = Number(cell.value)
+          else obj[col] = cell.value
+        })
+        return obj as T
+      })
+
+      return { rows }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      return { rows: [], error: message }
+    }
+  }
+
+  async execute(
+    sql: string,
+    args: ArgValue[] = [],
+  ): Promise<{ rowsAffected: number; error?: string }> {
+    if (!this.url || !this.token) {
+      return { rowsAffected: 0, error: 'Missing TURSO_URL or TURSO_AUTH_TOKEN' }
+    }
+
+    try {
+      const resp = await fetch(this.url + '/v2/pipeline', {
+        method: 'POST',
+        headers: {
+          Authorization: 'Bearer ' + this.token,
+          'Content-Type': 'application/json',
+        },
+        body: JSON.stringify({
+          requests: [
+            { type: 'execute', stmt: { sql, args: args.map(toHranaArg) } },
+            { type: 'close' },
+          ],
+        }),
+      })
+
+      if (!resp.ok) {
+        const text = await resp.text().catch(() => '')
+        return { rowsAffected: 0, error: `HTTP ${resp.status}: ${text}` }
+      }
+
+      const data: PipelineResult = await resp.json()
+      const first = data.results[0]
+
+      if (first.type === 'error') {
+        return { rowsAffected: 0, error: first.error?.message ?? 'Unknown error' }
+      }
+
+      return { rowsAffected: first.response?.result?.affected_row_count ?? 0 }
+    } catch (err: unknown) {
+      const message = err instanceof Error ? err.message : 'Unknown error'
+      return { rowsAffected: 0, error: message }
+    }
+  }
+}