@sqaoss/flowy 1.2.2 → 1.3.1

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

package/server/src/resolvers.test.ts

@@ -96,6 +96,59 @@ describe('createResolvers', () => {
       expect(typeof node.createdAt).toBe('string')
       expect(typeof node.updatedAt).toBe('string')
     })
+
+    it('persists metadata as JSON and reads it back unchanged', () => {
+      const created = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'With meta',
+        metadata: '{"priority":"high","effort":3}',
+      })
+      expect(created.metadata).toBe('{"priority":"high","effort":3}')
+      const found = find(resolvers, created.id)
+      expect(JSON.parse(found.metadata as string)).toEqual({
+        priority: 'high',
+        effort: 3,
+      })
+    })
+
+    it('accepts an explicit initial status', () => {
+      const node = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Started',
+        status: 'in_progress',
+      })
+      expect(node.status).toBe('in_progress')
+    })
+
+    it('rejects an invalid initial status with VALIDATION_ERROR', () => {
+      try {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: 'Bad',
+          status: 'bogus',
+        })
+        throw new Error('expected createNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('Invalid status: bogus')
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
+
+    it('rejects non-JSON metadata with VALIDATION_ERROR', () => {
+      try {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: 'Bad meta',
+          metadata: 'not json',
+        })
+        throw new Error('expected createNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('metadata')
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
   })
 
   describe('Query.node', () => {
@@ -112,9 +165,17 @@ describe('createResolvers', () => {
       })
     })
 
-    it('returns null for non-existent id', () => {
-      const found = resolvers.Query.node(null, { id: 'nonexistent' })
-      expect(found).toBeNull()
+    it('throws NOT_FOUND for a non-existent id (no silent null)', () => {
+      expect(() => resolvers.Query.node(null, { id: 'nonexistent' })).toThrow(
+        'Node nonexistent not found',
+      )
+      try {
+        resolvers.Query.node(null, { id: 'nonexistent' })
+      } catch (error) {
+        expect(
+          (error as { extensions?: { code?: string } }).extensions?.code,
+        ).toBe('NOT_FOUND')
+      }
     })
   })
 
@@ -161,6 +222,192 @@ describe('createResolvers', () => {
         }),
       ).toThrow('Node nonexistent not found')
     })
+
+    it('updates the title, leaving other fields untouched', () => {
+      const node = create(resolvers, {
+        type: 'task',
+        title: 'Old title',
+        description: 'keep me',
+      })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        title: 'New title',
+      })
+      expect(updated.title).toBe('New title')
+      expect(updated.description).toBe('keep me')
+      expect(updated.status).toBe('draft')
+    })
+
+    it('updates the description independently', () => {
+      const node = create(resolvers, {
+        type: 'task',
+        title: 'Title',
+        description: 'old desc',
+      })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        description: 'new desc',
+      })
+      expect(updated.description).toBe('new desc')
+      expect(updated.title).toBe('Title')
+    })
+
+    it('updates metadata independently and round-trips', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        metadata: '{"source":"import","effort":5}',
+      })
+      expect(JSON.parse(updated.metadata as string)).toEqual({
+        source: 'import',
+        effort: 5,
+      })
+      const found = find(resolvers, node.id)
+      expect(JSON.parse(found.metadata as string)).toEqual({
+        source: 'import',
+        effort: 5,
+      })
+    })
+
+    it('updates several fields at once', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        title: 'Renamed',
+        description: 'desc',
+        status: 'in_progress',
+        metadata: '{"k":"v"}',
+      })
+      expect(updated.title).toBe('Renamed')
+      expect(updated.description).toBe('desc')
+      expect(updated.status).toBe('in_progress')
+      expect(JSON.parse(updated.metadata as string)).toEqual({ k: 'v' })
+    })
+
+    it('rejects non-JSON metadata on update with VALIDATION_ERROR', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      try {
+        resolvers.Mutation.updateNode(null, {
+          id: node.id,
+          metadata: 'nope',
+        })
+        throw new Error('expected updateNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('metadata')
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
+
+    it('not-found error carries the NOT_FOUND code', () => {
+      try {
+        resolvers.Mutation.updateNode(null, {
+          id: 'missing',
+          title: 'x',
+        })
+        throw new Error('expected updateNode to throw')
+      } catch (err) {
+        const e = err as { extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('NOT_FOUND')
+      }
+    })
+
+    it('rejects an empty title with VALIDATION_ERROR', () => {
+      const node = create(resolvers, { type: 'task', title: 'Title' })
+      try {
+        resolvers.Mutation.updateNode(null, { id: node.id, title: '   ' })
+        throw new Error('expected updateNode to throw')
+      } catch (err) {
+        const e = err as { extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('VALIDATION_ERROR')
+      }
+    })
+  })
+
+  describe('Mutation.deleteNode', () => {
+    it('deletes a leaf node and returns true', () => {
+      const node = create(resolvers, { type: 'task', title: 'Leaf' })
+      const result = resolvers.Mutation.deleteNode(null, { id: node.id })
+      expect(result).toBe(true)
+      // After deletion the node is gone: Query.node now fails loud (NOT_FOUND).
+      expect(() => resolvers.Query.node(null, { id: node.id })).toThrow(
+        `Node ${node.id} not found`,
+      )
+    })
+
+    it('removes incident blocks edges when deleting a leaf', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blocker.id,
+        targetId: blocked.id,
+        relation: 'blocks',
+      })
+
+      resolvers.Mutation.deleteNode(null, { id: blocked.id })
+
+      // the blocks edge that referenced the deleted node must be gone
+      const edges = db.raw
+        .query<{ c: number }, [string, string]>(
+          'SELECT COUNT(*) AS c FROM edges WHERE source_id = ? OR target_id = ?',
+        )
+        .get(blocked.id, blocked.id) as { c: number }
+      expect(edges.c).toBe(0)
+    })
+
+    it('deletes a node together with its part_of edge to its parent', () => {
+      const project = create(resolvers, { type: 'project', title: 'P' })
+      const feature = create(resolvers, { type: 'feature', title: 'F' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+
+      const result = resolvers.Mutation.deleteNode(null, { id: feature.id })
+      expect(result).toBe(true)
+      // parent survives
+      expect(resolvers.Query.node(null, { id: project.id })).not.toBeNull()
+      // the part_of edge is gone
+      const edges = db.raw
+        .query<{ c: number }, [string]>(
+          'SELECT COUNT(*) AS c FROM edges WHERE source_id = ?',
+        )
+        .get(feature.id) as { c: number }
+      expect(edges.c).toBe(0)
+    })
+
+    it('refuses to delete a node that has children (CONFLICT)', () => {
+      const project = create(resolvers, { type: 'project', title: 'P' })
+      const feature = create(resolvers, { type: 'feature', title: 'F' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: feature.id,
+        targetId: project.id,
+        relation: 'part_of',
+      })
+
+      try {
+        resolvers.Mutation.deleteNode(null, { id: project.id })
+        throw new Error('expected deleteNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('CONFLICT')
+        expect(e.message).toContain('child')
+      }
+      // node not deleted
+      expect(resolvers.Query.node(null, { id: project.id })).not.toBeNull()
+    })
+
+    it('throws NOT_FOUND for a missing node', () => {
+      try {
+        resolvers.Mutation.deleteNode(null, { id: 'missing' })
+        throw new Error('expected deleteNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.extensions?.code).toBe('NOT_FOUND')
+        expect(e.message).toContain('missing')
+      }
+    })
   })
 
   describe('Mutation.approveNode', () => {

package/server/src/resolvers.ts

@@ -59,6 +59,30 @@ const VALID_STATUSES = new Set([
   'cancelled',
 ])
 
+function assertValidStatus(status: string): void {
+  if (!VALID_STATUSES.has(status)) {
+    throw validationError(
+      `Invalid status: ${status}. Must be one of: ${[...VALID_STATUSES].join(', ')}`,
+    )
+  }
+}
+
+/**
+ * Validate that `metadata` is a JSON string and return its canonical form.
+ * Metadata is stored as a JSON string (the column and the GraphQL field are
+ * both String); callers pass a JSON-encoded string. Non-JSON input is rejected
+ * with a VALIDATION_ERROR so agents can self-correct.
+ */
+function normalizeMetadata(metadata: string): string {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(metadata)
+  } catch {
+    throw validationError('Invalid metadata: must be a valid JSON string')
+  }
+  return JSON.stringify(parsed)
+}
+
 function generateId(type: string): string {
   const prefix = PREFIX_MAP[type] ?? type
   return `${prefix}_${nanoid(12)}`
@@ -98,7 +122,9 @@ export function createResolvers(db: Db) {
   return {
     Query: {
       node: (_: unknown, args: { id: string }) => {
-        return selectNode(db, args.id)
+        const node = selectNode(db, args.id)
+        if (!node) throw notFoundError(`Node ${args.id} not found`)
+        return node
       },
 
       nodes: (_: unknown, args: { type?: string }) => {
@@ -206,49 +232,120 @@ export function createResolvers(db: Db) {
     Mutation: {
       createNode: (
         _: unknown,
-        args: { type: string; title: string; description?: string },
+        args: {
+          type: string
+          title: string
+          description?: string
+          status?: string
+          metadata?: string
+        },
       ): NodeGql => {
         if (!args.title.trim()) throw validationError('Title is required')
         if (args.description != null && !args.description.trim()) {
           throw validationError('Description cannot be empty')
         }
+        if (args.status != null) assertValidStatus(args.status)
+        const metadata =
+          args.metadata != null ? normalizeMetadata(args.metadata) : null
         const id = generateId(args.type)
         const now = new Date().toISOString()
         const description = args.description ?? null
+        const status = args.status ?? 'draft'
         db.raw.run(
           'INSERT INTO nodes (id, type, title, description, status, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
-          [id, args.type, args.title, description, 'draft', null, now, now],
+          [id, args.type, args.title, description, status, metadata, now, now],
         )
         return {
           id,
           type: args.type,
           title: args.title,
           description,
-          status: 'draft',
-          metadata: null,
+          status,
+          metadata,
           createdAt: now,
           updatedAt: now,
         }
       },
 
-      updateNode: (_: unknown, args: { id: string; status?: string }) => {
+      updateNode: (
+        _: unknown,
+        args: {
+          id: string
+          title?: string
+          description?: string
+          status?: string
+          metadata?: string
+        },
+      ) => {
         const existing = db.raw
           .query('SELECT * FROM nodes WHERE id = ?')
           .get(args.id) as NodeRow | null
         if (!existing) throw notFoundError(`Node ${args.id} not found`)
-        const newStatus = args.status ?? existing.status
-        if (args.status && !VALID_STATUSES.has(args.status)) {
-          throw validationError(
-            `Invalid status: ${args.status}. Must be one of: ${[...VALID_STATUSES].join(', ')}`,
-          )
+
+        if (args.title != null && !args.title.trim()) {
+          throw validationError('Title cannot be empty')
+        }
+        if (args.description != null && !args.description.trim()) {
+          throw validationError('Description cannot be empty')
+        }
+        if (args.status != null) assertValidStatus(args.status)
+
+        const next: NodeRow = {
+          ...existing,
+          title: args.title ?? existing.title,
+          description:
+            args.description !== undefined
+              ? args.description
+              : existing.description,
+          status: args.status ?? existing.status,
+          metadata:
+            args.metadata != null
+              ? normalizeMetadata(args.metadata)
+              : existing.metadata,
         }
         const now = new Date().toISOString()
-        db.raw.run('UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?', [
-          newStatus,
-          now,
-          args.id,
-        ])
-        return rowToNode({ ...existing, status: newStatus, updated_at: now })
+        db.raw.run(
+          'UPDATE nodes SET title = ?, description = ?, status = ?, metadata = ?, updated_at = ? WHERE id = ?',
+          [
+            next.title,
+            next.description,
+            next.status,
+            next.metadata,
+            now,
+            args.id,
+          ],
+        )
+        return rowToNode({ ...next, updated_at: now })
+      },
+
+      deleteNode: (_: unknown, args: { id: string }): boolean => {
+        const existing = db.raw
+          .query('SELECT id FROM nodes WHERE id = ?')
+          .get(args.id) as { id: string } | null
+        if (!existing) throw notFoundError(`Node ${args.id} not found`)
+
+        // The hierarchy is client -> project -> feature -> task via `part_of`
+        // edges (source = child, target = parent). A node with children must
+        // not be orphaned; reject rather than cascade-delete the subtree.
+        const childCount = db.raw
+          .query(
+            'SELECT COUNT(*) AS c FROM edges WHERE target_id = ? AND relation = ?',
+          )
+          .get(args.id, 'part_of') as { c: number }
+        if (childCount.c > 0) {
+          throw conflictError(
+            `Cannot delete node ${args.id}: it has ${childCount.c} child node(s). Delete or re-link them first.`,
+          )
+        }
+
+        db.raw.transaction(() => {
+          db.raw.run('DELETE FROM edges WHERE source_id = ? OR target_id = ?', [
+            args.id,
+            args.id,
+          ])
+          db.raw.run('DELETE FROM nodes WHERE id = ?', [args.id])
+        })()
+        return true
       },
 
       approveNode: (_: unknown, args: { id: string }) => {

package/server/src/schema.test.ts

@@ -70,7 +70,7 @@ describe('schema', () => {
     expect(fields.tree).toBeUndefined()
   })
 
-  it('Mutation type has createNode, updateNode, approveNode, createEdge, removeEdge', () => {
+  it('Mutation type has createNode, updateNode, approveNode, deleteNode, createEdge, removeEdge', () => {
     const mutationType = schema.getType(
       'Mutation',
     ) as import('graphql').GraphQLObjectType
@@ -78,16 +78,50 @@ describe('schema', () => {
     expect(fields.createNode).toBeDefined()
     expect(fields.updateNode).toBeDefined()
     expect(fields.approveNode).toBeDefined()
+    expect(fields.deleteNode).toBeDefined()
     expect(fields.createEdge).toBeDefined()
     expect(fields.removeEdge).toBeDefined()
   })
 
-  it('Mutation type does not have deleteNode or deleteEdge', () => {
+  it('createNode accepts type, title, description, status, metadata args', () => {
     const mutationType = schema.getType(
       'Mutation',
     ) as import('graphql').GraphQLObjectType
-    const fields = mutationType.getFields()
-    expect(fields.deleteNode).toBeUndefined()
-    expect(fields.deleteEdge).toBeUndefined()
+    const args = mutationType.getFields().createNode.args.map((a) => a.name)
+    expect(args).toEqual(
+      expect.arrayContaining([
+        'type',
+        'title',
+        'description',
+        'status',
+        'metadata',
+      ]),
+    )
+  })
+
+  it('updateNode accepts id, title, description, status, metadata args', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const args = mutationType.getFields().updateNode.args.map((a) => a.name)
+    expect(args).toEqual(
+      expect.arrayContaining([
+        'id',
+        'title',
+        'description',
+        'status',
+        'metadata',
+      ]),
+    )
+  })
+
+  it('deleteNode returns Boolean and takes an id arg', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const deleteNode = mutationType.getFields().deleteNode
+    const args = deleteNode.args.map((a) => a.name)
+    expect(args).toEqual(expect.arrayContaining(['id']))
+    expect(String(deleteNode.type)).toContain('Boolean')
   })
 })

package/server/src/schema.ts

@@ -28,9 +28,22 @@ export const typeDefs = /* GraphQL */ `
   }
 
   type Mutation {
-    createNode(type: String!, title: String!, description: String): Node!
-    updateNode(id: String!, status: String): Node!
+    createNode(
+      type: String!
+      title: String!
+      description: String
+      status: String
+      metadata: String
+    ): Node!
+    updateNode(
+      id: String!
+      title: String
+      description: String
+      status: String
+      metadata: String
+    ): Node!
     approveNode(id: String!): Node!
+    deleteNode(id: String!): Boolean!
     createEdge(sourceId: String!, targetId: String!, relation: String!): Edge!
     removeEdge(sourceId: String!, targetId: String!, relation: String!): Boolean!
   }