@sqaoss/flowy 1.2.1 → 1.3.0

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', () => {
@@ -161,6 +214,189 @@ 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)
+      expect(resolvers.Query.node(null, { id: node.id })).toBeNull()
+    })
+
+    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

@@ -1,6 +1,21 @@
+import { createGraphQLError } from 'graphql-yoga'
 import { nanoid } from 'nanoid'
 import type { FlowyDb } from './db.ts'
 
+function validationError(message: string) {
+  return createGraphQLError(message, {
+    extensions: { code: 'VALIDATION_ERROR' },
+  })
+}
+
+function notFoundError(message: string) {
+  return createGraphQLError(message, { extensions: { code: 'NOT_FOUND' } })
+}
+
+function conflictError(message: string) {
+  return createGraphQLError(message, { extensions: { code: 'CONFLICT' } })
+}
+
 type Db = FlowyDb
 
 interface NodeRow {
@@ -44,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)}`
@@ -163,7 +202,7 @@ export function createResolvers(db: Db) {
         },
       ) => {
         if (args.query.trim().length < 3) {
-          throw new Error('Search query must be at least 3 characters')
+          throw validationError('Search query must be at least 3 characters')
         }
         const escaped = args.query.replace(/[%_\\]/g, '\\$&')
         const conditions = [
@@ -191,58 +230,129 @@ 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 new Error('Title is required')
+        if (!args.title.trim()) throw validationError('Title is required')
         if (args.description != null && !args.description.trim()) {
-          throw new Error('Description cannot be empty')
+          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 new Error(`Node ${args.id} not found`)
-        const newStatus = args.status ?? existing.status
-        if (args.status && !VALID_STATUSES.has(args.status)) {
-          throw new Error(
-            `Invalid status: ${args.status}. Must be one of: ${[...VALID_STATUSES].join(', ')}`,
-          )
+        if (!existing) throw notFoundError(`Node ${args.id} not found`)
+
+        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 }) => {
         const existing = db.raw
           .query('SELECT * FROM nodes WHERE id = ?')
           .get(args.id) as NodeRow | null
-        if (!existing) throw new Error(`Node ${args.id} not found`)
+        if (!existing) throw notFoundError(`Node ${args.id} not found`)
         if (existing.status !== 'pending_review') {
-          throw new Error(
+          throw conflictError(
             `Cannot approve node with status "${existing.status}", must be "pending_review"`,
           )
         }
@@ -261,7 +371,7 @@ export function createResolvers(db: Db) {
       ) => {
         const validRelations = new Set(['part_of', 'blocks'])
         if (!validRelations.has(args.relation)) {
-          throw new Error(
+          throw validationError(
             `Invalid relation: ${args.relation}. Must be 'part_of' or 'blocks'`,
           )
         }
@@ -269,16 +379,16 @@ export function createResolvers(db: Db) {
           .query('SELECT id FROM nodes WHERE id = ?')
           .get(args.sourceId)
         if (!sourceExists) {
-          throw new Error(`Source node ${args.sourceId} not found`)
+          throw notFoundError(`Source node ${args.sourceId} not found`)
         }
         const targetExists = db.raw
           .query('SELECT id FROM nodes WHERE id = ?')
           .get(args.targetId)
         if (!targetExists) {
-          throw new Error(`Target node ${args.targetId} not found`)
+          throw notFoundError(`Target node ${args.targetId} not found`)
         }
         if (args.relation === 'blocks' && args.sourceId === args.targetId) {
-          throw new Error('A node cannot block itself')
+          throw validationError('A node cannot block itself')
         }
         const now = new Date().toISOString()
         db.raw.run(

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

package/src/util/client.test.ts

@@ -31,6 +31,31 @@ describe('graphql client', () => {
     expect(result).toEqual({ whoami: { id: '1' } })
   })
 
+  test('attaches extensions.code to the thrown error', async () => {
+    vi.stubGlobal(
+      'fetch',
+      vi.fn().mockResolvedValue({
+        json: () =>
+          Promise.resolve({
+            errors: [
+              {
+                message: 'Search query must be at least 3 characters',
+                extensions: { code: 'VALIDATION_ERROR' },
+              },
+            ],
+          }),
+      }),
+    )
+
+    const { graphql } = await import('./client.ts')
+    await expect(
+      graphql('query { search(query: "ab") { id } }'),
+    ).rejects.toMatchObject({
+      message: 'Search query must be at least 3 characters',
+      code: 'VALIDATION_ERROR',
+    })
+  })
+
   test('throws original server message for unknown error codes', async () => {
     vi.stubGlobal(
       'fetch',

package/src/util/client.ts

@@ -47,7 +47,9 @@ export async function graphql<T = unknown>(
       )
     }
 
-    throw new Error(error?.message)
+    const err = new Error(error?.message) as Error & { code?: string }
+    if (code) err.code = code
+    throw err
   }
 
   return json.data as T

package/src/util/format.test.ts

@@ -0,0 +1,48 @@
+import { afterEach, describe, expect, test, vi } from 'vitest'
+import { outputError } from './format.ts'
+
+afterEach(() => {
+  vi.restoreAllMocks()
+})
+
+describe('outputError', () => {
+  test('includes code in JSON when error has a code property', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(process, 'exit').mockImplementation(() => undefined as never)
+
+    const err = Object.assign(
+      new Error('Search query must be at least 3 characters'),
+      { code: 'VALIDATION_ERROR' },
+    )
+    outputError(err)
+
+    expect(errorSpy).toHaveBeenCalledTimes(1)
+    const printed = JSON.parse(errorSpy.mock.calls[0]![0] as string)
+    expect(printed).toEqual({
+      error: 'Search query must be at least 3 characters',
+      code: 'VALIDATION_ERROR',
+    })
+  })
+
+  test('omits code when error has no code property', () => {
+    const errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+    vi.spyOn(process, 'exit').mockImplementation(() => undefined as never)
+
+    outputError(new Error('plain failure'))
+
+    const printed = JSON.parse(errorSpy.mock.calls[0]![0] as string)
+    expect(printed).toEqual({ error: 'plain failure' })
+    expect(printed).not.toHaveProperty('code')
+  })
+
+  test('exits with non-zero status', () => {
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    const exitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+
+    outputError(new Error('boom'))
+
+    expect(exitSpy).toHaveBeenCalledWith(1)
+  })
+})

package/src/util/format.ts

@@ -4,6 +4,11 @@ export function output(data: unknown): void {
 
 export function outputError(error: unknown): void {
   const message = error instanceof Error ? error.message : String(error)
-  console.error(JSON.stringify({ error: message }))
+  const rawCode =
+    error instanceof Error ? (error as { code?: unknown }).code : undefined
+  const code = typeof rawCode === 'string' ? rawCode : undefined
+  console.error(
+    JSON.stringify(code ? { error: message, code } : { error: message }),
+  )
   process.exit(1)
 }