popilot 0.6.0 → 0.8.0

package/scaffold/pm-api/sql/001-memo-v2.sql

@@ -0,0 +1,49 @@
+-- Memo v2 migration — authentication, user activity, memos, replies
+
+-- 1. Auth tokens
+CREATE TABLE IF NOT EXISTS auth_tokens (
+  token      TEXT PRIMARY KEY,
+  user_name  TEXT NOT NULL,
+  user_email TEXT,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  expires_at TIMESTAMP,
+  is_active  INTEGER DEFAULT 1
+);
+
+-- 2. User activity tracking
+CREATE TABLE IF NOT EXISTS user_activity (
+  user_name      TEXT PRIMARY KEY,
+  last_seen_at   TIMESTAMP,
+  last_memo_seen TIMESTAMP,
+  updated_at     TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 3. Memos v2
+CREATE TABLE IF NOT EXISTS memos_v2 (
+  id          INTEGER PRIMARY KEY,
+  page_id     TEXT NOT NULL,
+  content     TEXT NOT NULL,
+  memo_type   TEXT DEFAULT 'memo',
+  status      TEXT DEFAULT 'open',
+  created_by  TEXT NOT NULL,
+  assigned_to TEXT,
+  resolved_by TEXT,
+  resolved_at TIMESTAMP,
+  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  updated_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_memos_v2_page ON memos_v2(page_id);
+CREATE INDEX IF NOT EXISTS idx_memos_v2_assigned ON memos_v2(assigned_to, status);
+CREATE INDEX IF NOT EXISTS idx_memos_v2_type ON memos_v2(memo_type, status);
+
+-- 4. 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,
+  created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_memo_replies_memo ON memo_replies(memo_id);

package/scaffold/pm-api/sql/002-notifications.sql

@@ -0,0 +1,18 @@
+-- Notifications table for per-user alert management
+
+CREATE TABLE IF NOT EXISTS notifications (
+  id          INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_name   TEXT NOT NULL,
+  type        TEXT NOT NULL DEFAULT 'memo_assigned',
+  title       TEXT NOT NULL,
+  body        TEXT,
+  source_type TEXT NOT NULL DEFAULT 'memo',
+  source_id   INTEGER NOT NULL,
+  page_id     TEXT NOT NULL,
+  actor       TEXT NOT NULL,
+  is_read     INTEGER DEFAULT 0,
+  created_at  TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_notifications_user_unread ON notifications(user_name, is_read, created_at DESC);
+CREATE INDEX IF NOT EXISTS idx_notifications_source ON notifications(source_type, source_id);

package/scaffold/pm-api/sql/003-content.sql

@@ -0,0 +1,66 @@
+-- Spec-site content schema — rules, scenarios, areas, versions, wireframe meta
+
+-- 1. Rules (flat, individually queryable)
+CREATE TABLE IF NOT EXISTS spec_rules (
+  id           TEXT NOT NULL,
+  page_id      TEXT NOT NULL,
+  rule_group   TEXT NOT NULL,
+  category     TEXT NOT NULL,
+  name         TEXT NOT NULL,
+  condition    TEXT NOT NULL,
+  severity     TEXT NOT NULL,
+  home_message TEXT NOT NULL DEFAULT '',
+  action       TEXT NOT NULL DEFAULT '',
+  data_source  TEXT NOT NULL DEFAULT '',
+  impl_status  TEXT NOT NULL DEFAULT 'logic-needed',
+  impl_note    TEXT,
+  action_route TEXT,
+  sort_order   INTEGER NOT NULL DEFAULT 0,
+  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (page_id, id)
+);
+CREATE INDEX IF NOT EXISTS idx_spec_rules_page ON spec_rules(page_id);
+
+-- 2. Scenarios
+CREATE TABLE IF NOT EXISTS spec_scenarios (
+  page_id      TEXT NOT NULL,
+  scenario_id  TEXT NOT NULL,
+  label        TEXT NOT NULL,
+  data_json    TEXT NOT NULL,
+  is_default   INTEGER DEFAULT 0,
+  sort_order   INTEGER NOT NULL DEFAULT 0,
+  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+  PRIMARY KEY (page_id, scenario_id)
+);
+
+-- 3. Spec areas
+CREATE TABLE IF NOT EXISTS spec_areas (
+  page_id     TEXT NOT NULL,
+  area_id     TEXT NOT NULL,
+  label       TEXT NOT NULL,
+  short_label TEXT NOT NULL,
+  rule_count  INTEGER NOT NULL DEFAULT 0,
+  sort_order  INTEGER NOT NULL DEFAULT 0,
+  PRIMARY KEY (page_id, area_id)
+);
+
+-- 4. Page versions
+CREATE TABLE IF NOT EXISTS spec_versions (
+  page_id      TEXT PRIMARY KEY,
+  version      TEXT NOT NULL,
+  last_updated TEXT NOT NULL,
+  sprint       TEXT NOT NULL,
+  status       TEXT NOT NULL DEFAULT 'draft',
+  changelog    TEXT NOT NULL DEFAULT '[]',
+  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+-- 5. Wireframe metadata
+CREATE TABLE IF NOT EXISTS spec_wireframe_meta (
+  page_id             TEXT NOT NULL,
+  sprint              TEXT NOT NULL,
+  default_scenario_id TEXT NOT NULL,
+  spec_title          TEXT NOT NULL,
+  route_title         TEXT NOT NULL,
+  PRIMARY KEY (page_id, sprint)
+);

package/scaffold/pm-api/sql/004-agent-events.sql

@@ -0,0 +1,21 @@
+-- Agent events table for push-based inter-agent communication
+
+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',
+  delivered_at TIMESTAMP,
+  acked_at     TIMESTAMP,
+  expires_at   TIMESTAMP,
+  created_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+
+CREATE INDEX IF NOT EXISTS idx_events_target
+  ON agent_events(target_user, status, created_at DESC);
+
+CREATE INDEX IF NOT EXISTS idx_events_type
+  ON agent_events(event_type, status);

package/scaffold/pm-api/sql/005-epic-sprint-decoupling.sql

@@ -0,0 +1,6 @@
+-- Epic-Sprint decoupling migration
+-- Purpose: Make pm_epics the SSOT, remove nav_epics dependency
+-- Epics are global; stories move between sprints.
+
+ALTER TABLE pm_epics ADD COLUMN sort_order INTEGER NOT NULL DEFAULT 0;
+ALTER TABLE pm_epics ADD COLUMN origin_sprint TEXT;

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 }
+    }
+  }
+}