@sqaoss/flowy 1.2.1 → 1.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.2.1",
+  "version": "1.3.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -54,18 +54,17 @@
     "prepare": "husky"
   },
   "dependencies": {
-    "@semantic-release/changelog": "6.0.3",
-    "@semantic-release/git": "10.0.1",
-    "commander": "^14.0.3",
-    "semantic-release": "25.0.3"
+    "commander": "^14.0.3"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
     "@commitlint/cli": "^20.4.2",
     "@commitlint/config-conventional": "^20.4.2",
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.0",
-    "tdd-guard-vitest": "^0.1.6",
+    "semantic-release": "25.0.3",
     "typescript": "^5",
     "vitest": "^4.1.2"
   },

package/server/src/db.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { createDb } from './db.ts'
+import { LATEST_VERSION } from './migrations.ts'
 
 describe('createDb', () => {
   it('creates nodes and edges tables', () => {
@@ -90,4 +91,51 @@ describe('createDb', () => {
 
     db.close()
   })
+
+  it('runs migrations to the latest user_version on a fresh DB', () => {
+    const db = createDb(':memory:')
+
+    const result = db.raw
+      .query<{ user_version: number }, []>('PRAGMA user_version')
+      .get()
+
+    expect(result?.user_version).toBe(LATEST_VERSION)
+
+    db.close()
+  })
+
+  it('has a writable metadata column on nodes', () => {
+    const db = createDb(':memory:')
+
+    const columns = db.raw
+      .query<{ name: string }, []>('PRAGMA table_info(nodes)')
+      .all()
+      .map((c) => c.name)
+    expect(columns).toContain('metadata')
+
+    expect(() =>
+      db.raw.run(
+        `INSERT INTO nodes (id, type, title, metadata) VALUES ('n1', 'task', 'T', '{"a":1}')`,
+      ),
+    ).not.toThrow()
+
+    db.close()
+  })
+
+  it('accepts the blocked and cancelled statuses', () => {
+    const db = createDb(':memory:')
+
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n1', 'task', 'T', 'blocked')",
+      ),
+    ).not.toThrow()
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n2', 'task', 'T', 'cancelled')",
+      ),
+    ).not.toThrow()
+
+    db.close()
+  })
 })

package/server/src/db.ts

@@ -1,4 +1,5 @@
 import { Database } from 'bun:sqlite'
+import { runMigrations } from './migrations.ts'
 
 export type FlowyDb = ReturnType<typeof createDb>
 
@@ -8,37 +9,7 @@ export function createDb(path: string) {
   db.run('PRAGMA journal_mode = WAL')
   db.run('PRAGMA foreign_keys = ON')
 
-  db.run(`
-    CREATE TABLE IF NOT EXISTS nodes (
-      id TEXT PRIMARY KEY,
-      type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
-      title TEXT NOT NULL,
-      description TEXT,
-      status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done', 'blocked', 'cancelled')),
-      metadata TEXT,
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      updated_at TEXT NOT NULL DEFAULT (datetime('now'))
-    )
-  `)
-
-  db.run(`
-    CREATE TABLE IF NOT EXISTS edges (
-      source_id TEXT NOT NULL REFERENCES nodes(id),
-      target_id TEXT NOT NULL REFERENCES nodes(id),
-      relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
-      created_at TEXT NOT NULL DEFAULT (datetime('now')),
-      PRIMARY KEY (source_id, target_id, relation)
-    )
-  `)
-
-  db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
-  db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
-  db.run(
-    'CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id, relation)',
-  )
-  db.run(
-    'CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id, relation)',
-  )
+  runMigrations(db)
 
   return {
     raw: db,

package/server/src/index.errors.test.ts

@@ -0,0 +1,202 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { createServer } from './index.ts'
+
+interface GraphQLResponse {
+  data?: unknown
+  errors?: Array<{ message: string; extensions?: { code?: string } }>
+}
+
+describe('server error masking', () => {
+  let instance: ReturnType<typeof createServer> | undefined
+
+  afterEach(() => {
+    instance?.close()
+    instance = undefined
+  })
+
+  async function gql(
+    query: string,
+    variables?: Record<string, unknown>,
+  ): Promise<GraphQLResponse> {
+    const res = await fetch(`http://localhost:${instance!.port}/graphql`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ query, variables }),
+    })
+    return (await res.json()) as GraphQLResponse
+  }
+
+  it('surfaces a too-short search error with real message and VALIDATION_ERROR code', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const json = await gql('query ($q: String!) { search(query: $q) { id } }', {
+      q: 'ab',
+    })
+
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).toBe('Search query must be at least 3 characters')
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('VALIDATION_ERROR')
+  })
+
+  it('surfaces a not-found update error with real message and NOT_FOUND code', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const json = await gql(
+      'mutation ($id: String!) { updateNode(id: $id, status: "done") { id } }',
+      { id: 'nonexistent' },
+    )
+
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).toBe('Node nonexistent not found')
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('NOT_FOUND')
+  })
+
+  it('surfaces an invalid-status error with real message and VALIDATION_ERROR code', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "T") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const json = await gql(
+      'mutation ($id: String!) { updateNode(id: $id, status: "bogus") { id } }',
+      { id },
+    )
+
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).toContain('Invalid status: bogus')
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('VALIDATION_ERROR')
+  })
+
+  it('surfaces an approve-wrong-status error with CONFLICT code', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "feature", title: "F") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const json = await gql(
+      'mutation ($id: String!) { approveNode(id: $id) { id } }',
+      { id },
+    )
+
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).toContain('Cannot approve node with status "draft"')
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('CONFLICT')
+  })
+
+  it('round-trips metadata through createNode and the node query', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation ($m: String!) { createNode(type: "task", title: "T", metadata: $m) { id metadata } }',
+      { m: '{"priority":"high"}' },
+    )) as { data: { createNode: { id: string; metadata: string } } }
+    expect(created.data.createNode.metadata).toBe('{"priority":"high"}')
+
+    const id = created.data.createNode.id
+    const fetched = (await gql(
+      'query ($id: String!) { node(id: $id) { metadata } }',
+      { id },
+    )) as { data: { node: { metadata: string } } }
+    expect(JSON.parse(fetched.data.node.metadata)).toEqual({ priority: 'high' })
+  })
+
+  it('updates title/description/status/metadata via updateNode', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "Old") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const updated = (await gql(
+      `mutation ($id: String!) {
+        updateNode(id: $id, title: "New", description: "d", status: "in_progress", metadata: "{\\"k\\":1}") {
+          title description status metadata
+        }
+      }`,
+      { id },
+    )) as {
+      data: {
+        updateNode: {
+          title: string
+          description: string
+          status: string
+          metadata: string
+        }
+      }
+    }
+    expect(updated.data.updateNode.title).toBe('New')
+    expect(updated.data.updateNode.description).toBe('d')
+    expect(updated.data.updateNode.status).toBe('in_progress')
+    expect(JSON.parse(updated.data.updateNode.metadata)).toEqual({ k: 1 })
+  })
+
+  it('rejects non-JSON metadata with VALIDATION_ERROR over the wire', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const json = await gql(
+      'mutation { createNode(type: "task", title: "T", metadata: "not json") { id } }',
+    )
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('VALIDATION_ERROR')
+  })
+
+  it('deletes a leaf node via deleteNode', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "T") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const del = (await gql('mutation ($id: String!) { deleteNode(id: $id) }', {
+      id,
+    })) as { data: { deleteNode: boolean } }
+    expect(del.data.deleteNode).toBe(true)
+
+    const fetched = (await gql(
+      'query ($id: String!) { node(id: $id) { id } }',
+      {
+        id,
+      },
+    )) as { data: { node: unknown } }
+    expect(fetched.data.node).toBeNull()
+  })
+
+  it('refuses to delete a parent with children (CONFLICT)', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const project = (await gql(
+      'mutation { createNode(type: "project", title: "P") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const feature = (await gql(
+      'mutation { createNode(type: "feature", title: "F") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    await gql(
+      'mutation ($s: String!, $t: String!) { createEdge(sourceId: $s, targetId: $t, relation: "part_of") { relation } }',
+      { s: feature.data.createNode.id, t: project.data.createNode.id },
+    )
+
+    const json = await gql('mutation ($id: String!) { deleteNode(id: $id) }', {
+      id: project.data.createNode.id,
+    })
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('CONFLICT')
+  })
+})

package/server/src/migrations.test.ts

@@ -0,0 +1,218 @@
+import { Database } from 'bun:sqlite'
+import { describe, expect, it } from 'vitest'
+import { LATEST_VERSION, rebuildTable, runMigrations } from './migrations.ts'
+
+function userVersion(db: Database): number {
+  const row = db
+    .query<{ user_version: number }, []>('PRAGMA user_version')
+    .get()
+  return row?.user_version ?? 0
+}
+
+function tableNames(db: Database): string[] {
+  return db
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+    )
+    .all()
+    .map((r) => r.name)
+}
+
+function columnNames(db: Database, table: string): string[] {
+  return db
+    .query<{ name: string }, []>(`PRAGMA table_info(${table})`)
+    .all()
+    .map((r) => r.name)
+}
+
+describe('runMigrations', () => {
+  it('brings a fresh DB to the latest user_version', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    db.close()
+  })
+
+  it('creates the nodes and edges tables on a fresh DB', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    const tables = tableNames(db)
+    expect(tables).toContain('nodes')
+    expect(tables).toContain('edges')
+    db.close()
+  })
+
+  it('is a no-op when run twice (idempotent)', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    const versionAfterFirst = userVersion(db)
+    // second run must not throw and must not change the version
+    runMigrations(db)
+    expect(userVersion(db)).toBe(versionAfterFirst)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    db.close()
+  })
+
+  it('upgrades an old-shaped DB forward without losing data', () => {
+    const db = new Database(':memory:')
+    // Simulate a March-era schema: nodes table WITHOUT a metadata column,
+    // and a CHECK constraint that does not yet allow newer vocabulary.
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run(
+      "INSERT INTO nodes (id, type, title, description, status) VALUES ('proj_old', 'project', 'Legacy Project', 'from march', 'in_progress')",
+    )
+
+    runMigrations(db)
+
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    // metadata column now exists
+    expect(columnNames(db, 'nodes')).toContain('metadata')
+    // legacy row preserved
+    const row = db
+      .query<
+        { id: string; title: string; status: string; metadata: string | null },
+        []
+      >('SELECT id, title, status, metadata FROM nodes WHERE id = ?')
+      .get('proj_old') as {
+      id: string
+      title: string
+      status: string
+      metadata: string | null
+    }
+    expect(row.id).toBe('proj_old')
+    expect(row.title).toBe('Legacy Project')
+    expect(row.status).toBe('in_progress')
+    db.close()
+  })
+
+  it('after migration the new vocabulary (blocked, cancelled) is accepted', () => {
+    const db = new Database(':memory:')
+    // Old DB with a restrictive status CHECK (no blocked/cancelled)
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run("INSERT INTO nodes (id, type, title) VALUES ('task_1', 'task', 'T')")
+
+    runMigrations(db)
+
+    // The CHECK rebuild should now permit 'cancelled'
+    expect(() =>
+      db.run("UPDATE nodes SET status = 'cancelled' WHERE id = 'task_1'"),
+    ).not.toThrow()
+  })
+
+  describe('rebuildTable helper', () => {
+    it('rebuilds a table with a new CHECK constraint, preserving rows', () => {
+      const db = new Database(':memory:')
+      db.run(`
+        CREATE TABLE widgets (
+          id TEXT PRIMARY KEY,
+          kind TEXT NOT NULL CHECK(kind IN ('a', 'b'))
+        )
+      `)
+      db.run("INSERT INTO widgets (id, kind) VALUES ('w1', 'a')")
+
+      rebuildTable(
+        db,
+        'widgets',
+        (tmp) => `
+          CREATE TABLE ${tmp} (
+            id TEXT PRIMARY KEY,
+            kind TEXT NOT NULL CHECK(kind IN ('a', 'b', 'c'))
+          )
+        `,
+        ['id', 'kind'],
+      )
+
+      // existing row preserved
+      const row = db
+        .query<{ id: string; kind: string }, []>(
+          'SELECT id, kind FROM widgets WHERE id = ?',
+        )
+        .get('w1') as { id: string; kind: string }
+      expect(row).toEqual({ id: 'w1', kind: 'a' })
+      // new value now allowed by the widened CHECK
+      expect(() =>
+        db.run("INSERT INTO widgets (id, kind) VALUES ('w2', 'c')"),
+      ).not.toThrow()
+      db.close()
+    })
+  })
+
+  it('preserves edges across a nodes CHECK-rebuild migration', () => {
+    const db = new Database(':memory:')
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('proj_1', 'project', 'P')",
+    )
+    db.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('feat_1', 'feature', 'F')",
+    )
+    db.run(
+      "INSERT INTO edges (source_id, target_id, relation) VALUES ('feat_1', 'proj_1', 'part_of')",
+    )
+
+    runMigrations(db)
+
+    const edgeCount = db
+      .query<{ c: number }, []>('SELECT COUNT(*) AS c FROM edges')
+      .get() as { c: number }
+    expect(edgeCount.c).toBe(1)
+    db.close()
+  })
+})

package/server/src/migrations.ts

@@ -0,0 +1,140 @@
+import type { Database } from 'bun:sqlite'
+
+/**
+ * Versioned schema migrations for the bundled local SQLite server.
+ *
+ * The schema version is tracked with SQLite's `PRAGMA user_version`. Each entry
+ * in `MIGRATIONS` is a step whose 1-based ordinal is the version it produces:
+ * step at index `i` upgrades the DB from `user_version = i` to `user_version = i + 1`.
+ * On startup we apply every step whose target version exceeds the current
+ * `user_version`, in order, each wrapped in its own transaction so a failure
+ * leaves the DB at a clean, consistent version. Re-running is a no-op.
+ */
+
+type Migration = (db: Database) => void
+
+/**
+ * Rebuild a table with a new schema, preserving its rows. SQLite cannot ALTER a
+ * CHECK constraint in place, so changing column constraints requires creating a
+ * new table, copying rows across the shared columns, dropping the old table, and
+ * renaming. The whole sequence runs inside a transaction.
+ */
+export function rebuildTable(
+  db: Database,
+  table: string,
+  createNewTableSql: (tmpName: string) => string,
+  columns: string[],
+): void {
+  const tmp = `${table}__migrate_tmp`
+  const cols = columns.join(', ')
+  db.run('PRAGMA foreign_keys = OFF')
+  db.transaction(() => {
+    db.run(createNewTableSql(tmp))
+    db.run(`INSERT INTO ${tmp} (${cols}) SELECT ${cols} FROM ${table}`)
+    db.run(`DROP TABLE ${table}`)
+    db.run(`ALTER TABLE ${tmp} RENAME TO ${table}`)
+  })()
+  db.run('PRAGMA foreign_keys = ON')
+}
+
+const MIGRATIONS: Migration[] = [
+  // 0 -> 1: base schema (nodes + edges + indexes). Uses IF NOT EXISTS so this
+  // step is harmless on a DB that predates user_version tracking but already
+  // has the tables (created by an old `CREATE TABLE IF NOT EXISTS` startup).
+  (db) => {
+    db.run(`
+      CREATE TABLE IF NOT EXISTS nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE IF NOT EXISTS edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
+    db.run(
+      'CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id, relation)',
+    )
+    db.run(
+      'CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id, relation)',
+    )
+  },
+
+  // 1 -> 2: (a) add a writable `metadata` TEXT column if it is missing, then
+  // (b) rebuild `nodes` to widen the status CHECK to include 'blocked' and
+  // 'cancelled'. Adding the column first lets the CHECK-rebuild copy a uniform
+  // set of columns regardless of the pre-existing shape.
+  (db) => {
+    const hasMetadata = db
+      .query<{ name: string }, []>('PRAGMA table_info(nodes)')
+      .all()
+      .some((c) => c.name === 'metadata')
+    if (!hasMetadata) {
+      db.run('ALTER TABLE nodes ADD COLUMN metadata TEXT')
+    }
+
+    rebuildTable(
+      db,
+      'nodes',
+      (tmp) => `
+        CREATE TABLE ${tmp} (
+          id TEXT PRIMARY KEY,
+          type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+          title TEXT NOT NULL,
+          description TEXT,
+          status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done', 'blocked', 'cancelled')),
+          metadata TEXT,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        )
+      `,
+      [
+        'id',
+        'type',
+        'title',
+        'description',
+        'status',
+        'metadata',
+        'created_at',
+        'updated_at',
+      ],
+    )
+
+    // Indexes are dropped with the old table; recreate them.
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
+    db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
+  },
+]
+
+export const LATEST_VERSION = MIGRATIONS.length
+
+function getUserVersion(db: Database): number {
+  const row = db
+    .query<{ user_version: number }, []>('PRAGMA user_version')
+    .get()
+  return row?.user_version ?? 0
+}
+
+export function runMigrations(db: Database): void {
+  const current = getUserVersion(db)
+  MIGRATIONS.forEach((migration, index) => {
+    const targetVersion = index + 1
+    if (targetVersion <= current) return
+    migration(db)
+    // PRAGMA user_version does not accept bound parameters; the value is an
+    // integer derived from our own loop index, never user input.
+    db.run(`PRAGMA user_version = ${targetVersion}`)
+  })
+}