@sqaoss/flowy 1.12.0 → 1.13.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.12.0",
+  "version": "1.13.1",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {

package/server/src/contract.test.ts

@@ -175,6 +175,48 @@ describe('CLI/local-server contract (P1-1)', () => {
       relation: 'part_of',
     })
 
+    // CREATE_NODE_WITH_PARENT (P1-4/F24): create a node AND its part_of edge to
+    // the feature in one atomic call. The returned node must be a real child of
+    // the feature (reachable via the part_of hierarchy), proving the edge was
+    // created in the same unit of work — no separate createEdge call needed.
+    const { createNode: parentedTask } = await ok<{
+      createNode: { id: string }
+    }>(LOCAL_CONTRACT_OPERATIONS.CREATE_NODE_WITH_PARENT, {
+      type: 'task',
+      title: 'Parented Task',
+      description: 'linked atomically',
+      parentId: feature.id,
+    })
+    expect(parentedTask.id).toMatch(/^task_/)
+    const parentedChildren = await ok<{ descendants: Array<{ id: string }> }>(
+      LOCAL_CONTRACT_OPERATIONS.LIST_TASKS,
+      { nodeId: feature.id, relation: 'part_of', maxDepth: 1 },
+    )
+    expect(parentedChildren.descendants.map((n) => n.id)).toContain(
+      parentedTask.id,
+    )
+
+    // A non-existent parent must be rejected (NOT_FOUND) and leave no orphan.
+    const beforeOrphan = await ok<{ nodes: Array<{ id: string }> }>(
+      LOCAL_CONTRACT_OPERATIONS.ALL_TASKS,
+      { type: 'task' },
+    )
+    const badParent = await run(
+      LOCAL_CONTRACT_OPERATIONS.CREATE_NODE_WITH_PARENT,
+      {
+        type: 'task',
+        title: 'Should Not Exist',
+        description: 'orphan attempt',
+        parentId: 'feat_missing',
+      },
+    )
+    expect(badParent.errors).toBeDefined()
+    const afterOrphan = await ok<{ nodes: Array<{ id: string }> }>(
+      LOCAL_CONTRACT_OPERATIONS.ALL_TASKS,
+      { type: 'task' },
+    )
+    expect(afterOrphan.nodes).toHaveLength(beforeOrphan.nodes.length)
+
     // blocker blocks task
     const { createEdge: blocksEdge } = await ok<{
       createEdge: { relation: string; createdAt: string }
@@ -443,6 +485,7 @@ describe('CLI/local-server contract (P1-1)', () => {
       'CREATE_PROJECT',
       'CREATE_NODE',
       'CREATE_TASK',
+      'CREATE_NODE_WITH_PARENT',
       'UPDATE_NODE',
       'UPDATE_STATUS',
       'APPROVE_NODE',

package/server/src/resolvers.test.ts

@@ -151,6 +151,79 @@ describe('createResolvers', () => {
     })
   })
 
+  describe('Mutation.createNode with parentId (F24)', () => {
+    it('creates the node and a part_of edge to the parent atomically', () => {
+      const parent = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'Parent Feature',
+      })
+      const child = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Child Task',
+        parentId: parent.id,
+      })
+      expect(child.id).toMatch(/^task_/)
+      // the node exists
+      expect(resolvers.Query.node(null, { id: child.id })?.id).toBe(child.id)
+      // a part_of edge child -> parent exists (child reachable from parent)
+      const children = resolvers.Query.descendants(null, {
+        nodeId: parent.id,
+        relation: 'part_of',
+        maxDepth: 1,
+      })
+      expect(children.map((n) => n.id)).toContain(child.id)
+    })
+
+    it('writes a create audit row and a create_edge audit row for the link', () => {
+      const parent = resolvers.Mutation.createNode(null, {
+        type: 'feature',
+        title: 'Parent',
+      })
+      const child = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'Child',
+        parentId: parent.id,
+      })
+      const childHistory = resolvers.Query.auditLog(null, { nodeId: child.id })
+      const actions = childHistory.map((e) => e.action)
+      expect(actions).toContain('create')
+      expect(actions).toContain('create_edge')
+      const edgeEntry = childHistory.find((e) => e.action === 'create_edge')
+      expect(edgeEntry?.field).toBe('part_of')
+      expect(edgeEntry?.newValue).toBe(parent.id)
+    })
+
+    it('rejects a non-existent parent with NOT_FOUND and creates no orphan', () => {
+      const before = resolvers.Query.nodes(null, {})
+      try {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: 'Orphan?',
+          parentId: 'feat_does_not_exist',
+        })
+        throw new Error('expected createNode to throw')
+      } catch (err) {
+        const e = err as { message: string; extensions?: { code?: string } }
+        expect(e.message).toContain('feat_does_not_exist')
+        expect(e.extensions?.code).toBe('NOT_FOUND')
+      }
+      // nothing was written: no new node, no dangling edge
+      const after = resolvers.Query.nodes(null, {})
+      expect(after).toHaveLength(before.length)
+      expect(after.some((n) => n.title === 'Orphan?')).toBe(false)
+    })
+
+    it('behaves exactly like a plain create when parentId is omitted', () => {
+      const node = resolvers.Mutation.createNode(null, {
+        type: 'task',
+        title: 'No parent',
+      })
+      expect(node.id).toMatch(/^task_/)
+      const history = resolvers.Query.auditLog(null, { nodeId: node.id })
+      expect(history.map((e) => e.action)).toEqual(['create'])
+    })
+  })
+
   describe('Query.node', () => {
     it('returns a node by id', () => {
       const created = resolvers.Mutation.createNode(null, {
@@ -1322,21 +1395,33 @@ describe('createResolvers', () => {
   })
 
   describe('Mutation.createEdge — edge cases', () => {
-    it('throws on duplicate edge', () => {
+    it('is idempotent: creating the same edge twice succeeds and yields one edge', () => {
       const p = create(resolvers, { type: 'project', title: 'P' })
       const f = create(resolvers, { type: 'feature', title: 'F' })
-      resolvers.Mutation.createEdge(null, {
+      const first = resolvers.Mutation.createEdge(null, {
         sourceId: f.id,
         targetId: p.id,
         relation: 'part_of',
       })
-      expect(() =>
-        resolvers.Mutation.createEdge(null, {
-          sourceId: f.id,
-          targetId: p.id,
-          relation: 'part_of',
-        }),
-      ).toThrow()
+      const second = resolvers.Mutation.createEdge(null, {
+        sourceId: f.id,
+        targetId: p.id,
+        relation: 'part_of',
+      })
+      // Both calls succeed and return the same canonical edge (same created_at).
+      expect(second).toMatchObject({
+        sourceId: f.id,
+        targetId: p.id,
+        relation: 'part_of',
+      })
+      expect(second.createdAt).toBe(first.createdAt)
+      // Exactly one row exists for the triple — no duplicate.
+      const { n } = db.raw
+        .query(
+          'SELECT COUNT(*) AS n FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?',
+        )
+        .get(f.id, p.id, 'part_of') as { n: number }
+      expect(n).toBe(1)
     })
 
     it('throws when source node does not exist', () => {

package/server/src/resolvers.ts

@@ -495,6 +495,13 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
     },
 
     Mutation: {
+      // Create a node, optionally linking it under a parent in one atomic step
+      // (F24). When `parentId` is given we validate the parent exists FIRST —
+      // before any write — then, in a SINGLE transaction, insert the node, its
+      // `create` audit row, the `part_of` edge (child -> parent), and the
+      // edge's `create_edge` audit row. A failure anywhere rolls the whole unit
+      // back, so a bad link can never leave an orphaned node. With no
+      // `parentId`, behaviour is unchanged: just the node + its create audit.
       createNode: (
         _: unknown,
         args: {
@@ -503,6 +510,7 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
           description?: string
           status?: string
           metadata?: string
+          parentId?: string
         },
       ): NodeGql => {
         if (!args.title.trim()) throw validationError('Title is required')
@@ -510,6 +518,15 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
           throw validationError('Description cannot be empty')
         }
         if (args.status != null) assertValidStatus(args.status)
+        // Validate the parent up front so a bad link errors before any write.
+        if (args.parentId != null) {
+          const parentExists = db.raw
+            .query('SELECT id FROM nodes WHERE id = ?')
+            .get(args.parentId)
+          if (!parentExists) {
+            throw notFoundError(`Parent node ${args.parentId} not found`)
+          }
+        }
         const metadata =
           args.metadata != null ? normalizeMetadata(args.metadata) : null
         const id = generateId(args.type)
@@ -545,6 +562,18 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
             action: 'create',
             snapshot: node as unknown as Record<string, unknown>,
           })
+          if (args.parentId != null) {
+            db.raw.run(
+              'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
+              [id, args.parentId, 'part_of', now],
+            )
+            insertAudit(db, {
+              nodeId: id,
+              action: 'create_edge',
+              field: 'part_of',
+              newValue: args.parentId,
+            })
+          }
         })()
         return node
       },
@@ -749,25 +778,39 @@ export function createResolvers(db: Db, opts: ResolverOptions = {}) {
           throw validationError('A node cannot block itself')
         }
         const now = new Date().toISOString()
+        // Idempotent (F29): re-creating an existing edge is a no-op success, not
+        // a PK-violation error. ON CONFLICT DO NOTHING leaves the original row
+        // (and its created_at) untouched; we only audit a genuinely new edge.
         db.raw.transaction(() => {
-          db.raw.run(
-            'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
+          const result = db.raw.run(
+            'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?) ON CONFLICT (source_id, target_id, relation) DO NOTHING',
             [args.sourceId, args.targetId, args.relation, now],
           )
-          // Record the edge against its source node so `auditLog(sourceId)`
-          // surfaces it. field = relation; newValue = the target it now links.
-          insertAudit(db, {
-            nodeId: args.sourceId,
-            action: 'create_edge',
-            field: args.relation,
-            newValue: args.targetId,
-          })
+          if (result.changes > 0) {
+            // Record the edge against its source node so `auditLog(sourceId)`
+            // surfaces it. field = relation; newValue = the target it now links.
+            insertAudit(db, {
+              nodeId: args.sourceId,
+              action: 'create_edge',
+              field: args.relation,
+              newValue: args.targetId,
+            })
+          }
         })()
+        // Read back the canonical row so the returned createdAt reflects the
+        // existing edge on a duplicate call, not the discarded `now`.
+        const edge = db.raw
+          .query(
+            'SELECT created_at FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?',
+          )
+          .get(args.sourceId, args.targetId, args.relation) as {
+          created_at: string
+        }
         return {
           sourceId: args.sourceId,
           targetId: args.targetId,
           relation: args.relation,
-          createdAt: now,
+          createdAt: edge.created_at,
         }
       },
 

package/server/src/schema.ts

@@ -85,6 +85,7 @@ export const typeDefs = /* GraphQL */ `
       description: String
       status: String
       metadata: String
+      parentId: String
     ): Node!
     updateNode(
       id: String!

package/src/commands/feature.test.ts

@@ -56,6 +56,50 @@ describe('feature command', () => {
     )
   })
 
+  test('create issues ONE createNode-with-parent call under the active project', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { requireProject } = await import('../util/config.ts')
+    const { output } = await import('../util/format.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(requireProject).mockReturnValueOnce({
+      id: 'proj_active',
+      name: 'active',
+    })
+    vi.mocked(graphql).mockResolvedValueOnce({
+      createNode: { id: 'feat_new', title: 'Test' },
+    })
+
+    const createCmd = featureCommand.commands.find((c) => c.name() === 'create')
+    await createCmd?.parseAsync(['--title', 'Test', '--description', 'Desc'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledTimes(1)
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('createNode')
+    expect(query).toContain('parentId')
+    expect(variables).toMatchObject({
+      type: 'feature',
+      title: 'Test',
+      description: 'Desc',
+      parentId: 'proj_active',
+    })
+    expect(output).toHaveBeenCalledWith({ id: 'feat_new', title: 'Test' })
+  })
+
+  test('create validates the project BEFORE any write (no createNode on bad project)', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    const createCmd = featureCommand.commands.find((c) => c.name() === 'create')
+    await createCmd?.parseAsync(['--title', 'Test', '--description', 'Desc'], {
+      from: 'user',
+    })
+
+    expect(graphql).not.toHaveBeenCalled()
+  })
+
   test('unset calls updateProjectConfig to delete activeFeature', async () => {
     const { featureCommand } = await import('./feature.ts')
     const { output } = await import('../util/format.ts')

package/src/commands/feature.ts

@@ -8,7 +8,6 @@ import {
 import { resolveDescription } from '../util/description.ts'
 import { output, outputError } from '../util/format.ts'
 import {
-  CREATE_EDGE,
   CREATE_NODE,
   DELETE_NODE,
   DESCENDANTS,
@@ -35,21 +34,24 @@ featureCommand
   )
   .action(async (opts) => {
     try {
+      // Validate the active project BEFORE any write so a bad project context
+      // errors cleanly instead of orphaning a node (F24).
       const project = requireProject()
       const description = await resolveDescription({
         description: opts.description,
         descriptionFile: opts.descriptionFile,
       })
+      // One atomic call: the server creates the feature and its `part_of` edge
+      // to the project together, so a failed link can never leave an orphan.
       const nodeData = await graphql<{ createNode: { id: string } }>(
         CREATE_NODE,
-        { type: 'feature', title: opts.title, description },
+        {
+          type: 'feature',
+          title: opts.title,
+          description,
+          parentId: project.id,
+        },
       )
-      const featureId = nodeData.createNode.id
-      await graphql(CREATE_EDGE, {
-        sourceId: featureId,
-        targetId: project.id,
-        relation: 'part_of',
-      })
       output(nodeData.createNode)
     } catch (error) {
       outputError(error)

package/src/commands/task.test.ts

@@ -63,6 +63,50 @@ describe('task command', () => {
     )
   })
 
+  test('create validates the feature BEFORE any write (no createNode on bad feature)', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    // requireFeature() throws (default mock) — the command must bail out before
+    // issuing any mutation, so the node is never created.
+    const createCmd = taskCommand.commands.find((c) => c.name() === 'create')!
+    await createCmd.parseAsync(['--title', 'Test', '--description', 'desc'], {
+      from: 'user',
+    })
+
+    expect(graphql).not.toHaveBeenCalled()
+  })
+
+  test('create issues ONE createNode-with-parent call (not a create then a link)', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { requireFeature } = await import('../util/config.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(requireFeature).mockReturnValueOnce('feat_active')
+    vi.mocked(graphql).mockResolvedValueOnce({
+      createNode: { id: 'task_new', title: 'Test' },
+    })
+
+    const createCmd = taskCommand.commands.find((c) => c.name() === 'create')!
+    await createCmd.parseAsync(['--title', 'Test', '--description', 'desc'], {
+      from: 'user',
+    })
+
+    // exactly one GraphQL call, and it is the parented createNode
+    expect(graphql).toHaveBeenCalledTimes(1)
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('createNode')
+    expect(query).toContain('parentId')
+    expect(variables).toMatchObject({
+      type: 'task',
+      title: 'Test',
+      description: 'desc',
+      parentId: 'feat_active',
+    })
+    expect(output).toHaveBeenCalledWith({ id: 'task_new', title: 'Test' })
+  })
+
   test('show calls outputError when graphql throws network error', async () => {
     const { graphql } = await import('../util/client.ts')
     const { outputError } = await import('../util/format.ts')

package/src/commands/task.ts

@@ -8,7 +8,6 @@ import {
   BLOCK_TASK,
   CREATE_TASK,
   DELETE_NODE,
-  LINK_TASK,
   LIST_TASKS,
   READY_TASKS,
   SHOW_TASK,
@@ -35,21 +34,20 @@ taskCommand
   )
   .action(async (opts) => {
     try {
+      // Validate the active feature BEFORE any write so a bad FLOWY_FEATURE
+      // errors cleanly instead of orphaning a node (F24).
       const featureId = requireFeature()
       const description = await resolveDescription({
         description: opts.description,
         descriptionFile: opts.descriptionFile,
       })
+      // One atomic call: the server creates the task and its `part_of` edge to
+      // the feature together, so a failed link can never leave an orphan.
       const data = await graphql<{ createNode: { id: string } }>(CREATE_TASK, {
         type: 'task',
         title: opts.title,
         description,
-      })
-      const taskId = data.createNode.id
-      await graphql(LINK_TASK, {
-        sourceId: taskId,
-        targetId: featureId,
-        relation: 'part_of',
+        parentId: featureId,
       })
       output(data.createNode)
     } catch (error) {

package/src/util/operations.test.ts

@@ -57,7 +57,6 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
     ],
     'feature.ts': [
       'CREATE_NODE',
-      'CREATE_EDGE',
       'DESCENDANTS',
       'DESCENDANTS_BRIEF',
       'UPDATE_NODE',
@@ -66,7 +65,6 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
     ],
     'task.ts': [
       'CREATE_TASK',
-      'LINK_TASK',
       'READY_TASKS',
       'ALL_TASKS',
       'LIST_TASKS',

package/src/util/operations.ts

@@ -152,20 +152,44 @@ export const CREATE_PROJECT = `mutation CreateProject($type: String!, $title: St
   }
 }`
 
-/** feature.ts `create` — create a node with a description. */
-export const CREATE_NODE = `mutation CreateNode($type: String!, $title: String!, $description: String) {
-  createNode(type: $type, title: $title, description: $description) {
+/**
+ * feature.ts `create` — create a feature node linked under its parent project
+ * in ONE transactional call (F24). The optional `parentId` makes the server
+ * create the node and the `part_of` edge atomically, so a failed link can never
+ * orphan the node. Both backends accept `parentId` (bundled local since P1-4;
+ * SaaS since flowy-ai v33). When omitted, it is a plain create.
+ */
+export const CREATE_NODE = `mutation CreateNode($type: String!, $title: String!, $description: String, $parentId: String) {
+  createNode(type: $type, title: $title, description: $description, parentId: $parentId) {
     id type title description status createdAt updatedAt
   }
 }`
 
-/** task.ts `create` — create a task node. */
-export const CREATE_TASK = `mutation CreateTask($type: String!, $title: String!, $description: String) {
-  createNode(type: $type, title: $title, description: $description) {
+/**
+ * task.ts `create` — create a task node linked under its parent feature in ONE
+ * transactional call (F24); see CREATE_NODE for the `parentId` semantics.
+ */
+export const CREATE_TASK = `mutation CreateTask($type: String!, $title: String!, $description: String, $parentId: String) {
+  createNode(type: $type, title: $title, description: $description, parentId: $parentId) {
     id type title description status createdAt
   }
 }`
 
+/**
+ * Contract op (P1-4/F24): create a node AND its `part_of` edge to a parent in a
+ * single atomic `createNode(parentId:)` call. This is the operation `task
+ * create` / `feature create` issue at runtime (via CREATE_TASK / CREATE_NODE);
+ * exercised explicitly by the contract test to assert the bundled local server
+ * creates the node + edge atomically and rejects a non-existent parent without
+ * leaving an orphan. The SaaS contract guard mirrors this op so both backends
+ * stay aligned on the parented-create surface.
+ */
+export const CREATE_NODE_WITH_PARENT = `mutation CreateNodeWithParent($type: String!, $title: String!, $description: String, $parentId: String) {
+  createNode(type: $type, title: $title, description: $description, parentId: $parentId) {
+    id type title description status createdAt updatedAt
+  }
+}`
+
 /** project/feature/task `update` — title/description/metadata. */
 export const UPDATE_NODE = `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
   updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
@@ -324,6 +348,7 @@ export const LOCAL_CONTRACT_OPERATIONS = {
   CREATE_PROJECT,
   CREATE_NODE,
   CREATE_TASK,
+  CREATE_NODE_WITH_PARENT,
   UPDATE_NODE,
   UPDATE_STATUS,
   APPROVE_NODE,