@sqaoss/flowy 1.3.1 → 1.5.0

package/package.json

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

package/server/src/resolvers.test.ts

@@ -1099,4 +1099,200 @@ describe('createResolvers', () => {
       expect(results).toEqual([])
     })
   })
+
+  describe('Query.readyTasks', () => {
+    function setStatus(id: string, status: string): void {
+      resolvers.Mutation.updateNode(null, { id, status })
+    }
+    function block(blockerId: string, blockedId: string): void {
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blockerId,
+        targetId: blockedId,
+        relation: 'blocks',
+      })
+    }
+
+    it('returns an unblocked, not-done task', () => {
+      const t = create(resolvers, { type: 'task', title: 'Free' })
+      const ready = resolvers.Query.readyTasks(null, {})
+      expect(ready.map((n) => n.id)).toEqual([t.id])
+    })
+
+    it('excludes done and cancelled tasks', () => {
+      const open = create(resolvers, { type: 'task', title: 'Open' })
+      const done = create(resolvers, { type: 'task', title: 'Done' })
+      const cancelled = create(resolvers, { type: 'task', title: 'Cancelled' })
+      setStatus(done.id, 'done')
+      setStatus(cancelled.id, 'cancelled')
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      const ids = ready.map((n) => n.id)
+      expect(ids).toContain(open.id)
+      expect(ids).not.toContain(done.id)
+      expect(ids).not.toContain(cancelled.id)
+    })
+
+    it('excludes a task blocked by an unfinished blocker', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      block(blocker.id, blocked.id)
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      const ids = ready.map((n) => n.id)
+      expect(ids).toContain(blocker.id)
+      expect(ids).not.toContain(blocked.id)
+    })
+
+    it('includes a task once all its blockers are done', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      block(blocker.id, blocked.id)
+      setStatus(blocker.id, 'done')
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      const ids = ready.map((n) => n.id)
+      // The done blocker is itself excluded; the formerly-blocked task is ready.
+      expect(ids).not.toContain(blocker.id)
+      expect(ids).toContain(blocked.id)
+    })
+
+    it('treats a cancelled blocker as no longer blocking', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      block(blocker.id, blocked.id)
+      setStatus(blocker.id, 'cancelled')
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      expect(ready.map((n) => n.id)).toContain(blocked.id)
+    })
+
+    it('still blocks when any one of several blockers is unfinished', () => {
+      const b1 = create(resolvers, { type: 'task', title: 'B1' })
+      const b2 = create(resolvers, { type: 'task', title: 'B2' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      block(b1.id, blocked.id)
+      block(b2.id, blocked.id)
+      setStatus(b1.id, 'done')
+      // b2 still open -> blocked stays not-ready
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      expect(ready.map((n) => n.id)).not.toContain(blocked.id)
+    })
+
+    it('returns only tasks, never features or projects', () => {
+      const project = create(resolvers, { type: 'project', title: 'P' })
+      const feature = create(resolvers, { type: 'feature', title: 'F' })
+      const task = create(resolvers, { type: 'task', title: 'T' })
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      const ids = ready.map((n) => n.id)
+      expect(ids).toContain(task.id)
+      expect(ids).not.toContain(project.id)
+      expect(ids).not.toContain(feature.id)
+    })
+
+    it('returns exactly the unblocked not-done tasks across a mixed fixture', () => {
+      // free: ready. blocked-by-open: not ready. blocked-by-done: ready.
+      // done: not ready. in_progress + unblocked: ready.
+      const free = create(resolvers, { type: 'task', title: 'free' })
+      const openBlocker = create(resolvers, { type: 'task', title: 'open-b' })
+      const blockedByOpen = create(resolvers, { type: 'task', title: 'bbo' })
+      const doneBlocker = create(resolvers, { type: 'task', title: 'done-b' })
+      const blockedByDone = create(resolvers, { type: 'task', title: 'bbd' })
+      const finished = create(resolvers, { type: 'task', title: 'finished' })
+      const started = create(resolvers, { type: 'task', title: 'started' })
+
+      block(openBlocker.id, blockedByOpen.id)
+      block(doneBlocker.id, blockedByDone.id)
+      setStatus(doneBlocker.id, 'done')
+      setStatus(finished.id, 'done')
+      setStatus(started.id, 'in_progress')
+
+      const ready = resolvers.Query.readyTasks(null, {})
+      const ids = new Set(ready.map((n) => n.id))
+      expect(ids).toEqual(
+        new Set([free.id, openBlocker.id, blockedByDone.id, started.id]),
+      )
+    })
+
+    it('scopes to a project via part_of when projectId is given', () => {
+      const projA = create(resolvers, { type: 'project', title: 'A' })
+      const featA = create(resolvers, { type: 'feature', title: 'FA' })
+      const taskA = create(resolvers, { type: 'task', title: 'TA' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: featA.id,
+        targetId: projA.id,
+        relation: 'part_of',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: taskA.id,
+        targetId: featA.id,
+        relation: 'part_of',
+      })
+
+      const projB = create(resolvers, { type: 'project', title: 'B' })
+      const featB = create(resolvers, { type: 'feature', title: 'FB' })
+      const taskB = create(resolvers, { type: 'task', title: 'TB' })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: featB.id,
+        targetId: projB.id,
+        relation: 'part_of',
+      })
+      resolvers.Mutation.createEdge(null, {
+        sourceId: taskB.id,
+        targetId: featB.id,
+        relation: 'part_of',
+      })
+
+      const ready = resolvers.Query.readyTasks(null, { projectId: projA.id })
+      expect(ready.map((n) => n.id)).toEqual([taskA.id])
+    })
+  })
+
+  describe('Query.edges', () => {
+    function block(blockerId: string, blockedId: string): void {
+      resolvers.Mutation.createEdge(null, {
+        sourceId: blockerId,
+        targetId: blockedId,
+        relation: 'blocks',
+      })
+    }
+
+    it('returns blockedBy: incoming blocks edges (sources that block the node)', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      block(blocker.id, blocked.id)
+
+      const blockedBy = resolvers.Query.edges(null, {
+        nodeId: blocked.id,
+        relation: 'blocks',
+        direction: 'incoming',
+      })
+      expect(blockedBy.map((n) => n.id)).toEqual([blocker.id])
+    })
+
+    it('returns blocks: outgoing blocks edges (targets the node blocks)', () => {
+      const blocker = create(resolvers, { type: 'task', title: 'Blocker' })
+      const blocked = create(resolvers, { type: 'task', title: 'Blocked' })
+      block(blocker.id, blocked.id)
+
+      const blocks = resolvers.Query.edges(null, {
+        nodeId: blocker.id,
+        relation: 'blocks',
+        direction: 'outgoing',
+      })
+      expect(blocks.map((n) => n.id)).toEqual([blocked.id])
+    })
+
+    it('returns an empty array for a node with no edges', () => {
+      const lonely = create(resolvers, { type: 'task', title: 'Lonely' })
+      expect(
+        resolvers.Query.edges(null, {
+          nodeId: lonely.id,
+          relation: 'blocks',
+          direction: 'incoming',
+        }),
+      ).toEqual([])
+    })
+  })
 })

package/server/src/resolvers.ts

@@ -194,6 +194,74 @@ export function createResolvers(db: Db) {
         return selectNodes(rows)
       },
 
+      // Nodes connected to `nodeId` by `relation`, following edges in the given
+      // direction. 'incoming' returns the *sources* of edges that point at the
+      // node (e.g. for relation 'blocks', the tasks that block it — blockedBy);
+      // 'outgoing' returns the *targets* of edges originating at the node (the
+      // tasks it blocks). Default direction is 'outgoing'.
+      edges: (
+        _: unknown,
+        args: {
+          nodeId: string
+          relation: string
+          direction?: string
+        },
+      ) => {
+        const incoming = args.direction === 'incoming'
+        const sql = incoming
+          ? `SELECT ${prefixedCols()} FROM nodes n
+             JOIN edges e ON n.id = e.source_id
+             WHERE e.target_id = ? AND e.relation = ?`
+          : `SELECT ${prefixedCols()} FROM nodes n
+             JOIN edges e ON n.id = e.target_id
+             WHERE e.source_id = ? AND e.relation = ?`
+        const rows = db.raw
+          .query(sql)
+          .all(args.nodeId, args.relation) as NodeRow[]
+        return selectNodes(rows)
+      },
+
+      // Tasks that are actionable now: type 'task', status not done/cancelled,
+      // and not blocked by any incomplete blocker. A blocker is an incoming
+      // `blocks` edge whose source task is itself not done/cancelled. Optionally
+      // scoped to a project via the `part_of` hierarchy (task -> feature ->
+      // project).
+      readyTasks: (_: unknown, args: { projectId?: string }) => {
+        const params: string[] = []
+        let scope = ''
+        if (args.projectId) {
+          // Restrict to tasks reachable from the project through part_of edges
+          // (any depth). Edges point child -> parent, so we walk upward from
+          // each candidate task to see if the project is an ancestor.
+          scope = `AND n.id IN (
+            WITH RECURSIVE up(id) AS (
+              SELECT source_id FROM edges
+                WHERE target_id = ?1 AND relation = 'part_of'
+              UNION
+              SELECT e.source_id FROM edges e
+                JOIN up ON e.target_id = up.id AND e.relation = 'part_of'
+            )
+            SELECT id FROM up
+          )`
+          params.push(args.projectId)
+        }
+        const rows = db.raw
+          .query(
+            `SELECT ${prefixedCols()} FROM nodes n
+             WHERE n.type = 'task'
+               AND n.status NOT IN ('done', 'cancelled')
+               ${scope}
+               AND NOT EXISTS (
+                 SELECT 1 FROM edges b
+                 JOIN nodes src ON src.id = b.source_id
+                 WHERE b.target_id = n.id AND b.relation = 'blocks'
+                   AND src.status NOT IN ('done', 'cancelled')
+               )`,
+          )
+          .all(...params) as NodeRow[]
+        return selectNodes(rows)
+      },
+
       search: (
         _: unknown,
         args: {

package/server/src/schema.ts

@@ -24,6 +24,8 @@ export const typeDefs = /* GraphQL */ `
     nodes(type: String): [Node!]!
     descendants(nodeId: String!, relation: String, maxDepth: Int): [Node!]!
     subtree(nodeId: String!, maxDepth: Int): [Node!]!
+    edges(nodeId: String!, relation: String!, direction: String): [Node!]!
+    readyTasks(projectId: String): [Node!]!
     search(query: String!, type: String, status: String, limit: Int): [Node!]!
   }
 

package/src/commands/feature.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from 'vitest'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
 
 const mockUpdateProjectConfig = vi.fn()
 
@@ -22,6 +22,10 @@ vi.mock('../util/format.ts', () => ({
 }))
 
 describe('feature command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
   test('exports a command group named "feature" with subcommands', async () => {
     const { featureCommand } = await import('./feature.ts')
     expect(featureCommand.name()).toBe('feature')
@@ -31,6 +35,8 @@ describe('feature command', () => {
     expect(subcommandNames).toContain('unset')
     expect(subcommandNames).toContain('list')
     expect(subcommandNames).toContain('show')
+    expect(subcommandNames).toContain('update')
+    expect(subcommandNames).toContain('delete')
   })
 
   test('create calls outputError when no active project', async () => {
@@ -68,4 +74,158 @@ describe('feature command', () => {
 
     expect(output).toHaveBeenCalledWith({ activeFeature: null })
   })
+
+  test('update sends updateNode with only the title when title-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      updateNode: { id: 'feat_1', title: 'New' },
+    })
+
+    const updateCmd = featureCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(['feat_1', '--title', 'New'], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'feat_1',
+        title: 'New',
+      },
+    )
+    expect(output).toHaveBeenCalledWith({ id: 'feat_1', title: 'New' })
+  })
+
+  test('update sends updateNode with only the description when description-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ updateNode: { id: 'feat_1' } })
+
+    const updateCmd = featureCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(['feat_1', '--description', 'Body'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'feat_1',
+        description: 'Body',
+      },
+    )
+  })
+
+  test('update sends updateNode with only the metadata when metadata-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ updateNode: { id: 'feat_1' } })
+
+    const updateCmd = featureCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(['feat_1', '--metadata', '{"k":"v"}'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'feat_1',
+        metadata: '{"k":"v"}',
+      },
+    )
+  })
+
+  test('update sends updateNode with combined fields', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ updateNode: { id: 'feat_1' } })
+
+    const updateCmd = featureCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(
+      ['feat_1', '--title', 'New', '--description', 'Body', '--metadata', '{}'],
+      { from: 'user' },
+    )
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'feat_1',
+        title: 'New',
+        description: 'Body',
+        metadata: '{}',
+      },
+    )
+  })
+
+  test('delete sends deleteNode mutation', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ deleteNode: true })
+
+    const deleteCmd = featureCommand.commands.find(
+      (c) => c.name() === 'delete',
+    )!
+    await deleteCmd.parseAsync(['feat_1'], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('deleteNode'),
+      {
+        id: 'feat_1',
+      },
+    )
+    expect(output).toHaveBeenCalledWith({ deleted: true })
+  })
+
+  test('delete surfaces CONFLICT via outputError with its code', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    const conflict = Object.assign(new Error('has children'), {
+      code: 'CONFLICT',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(conflict)
+
+    const deleteCmd = featureCommand.commands.find(
+      (c) => c.name() === 'delete',
+    )!
+    await deleteCmd.parseAsync(['feat_1'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: 'CONFLICT' }),
+    )
+  })
+
+  test('delete surfaces NOT_FOUND via outputError with its code', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { featureCommand } = await import('./feature.ts')
+
+    const notFound = Object.assign(new Error('Node feat_x not found'), {
+      code: 'NOT_FOUND',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(notFound)
+
+    const deleteCmd = featureCommand.commands.find(
+      (c) => c.name() === 'delete',
+    )!
+    await deleteCmd.parseAsync(['feat_x'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: 'NOT_FOUND' }),
+    )
+  })
 })

package/src/commands/feature.ts

@@ -126,6 +126,75 @@ featureCommand
     }
   })
 
+featureCommand
+  .command('update')
+  .description('Update a feature')
+  .argument('[id]', 'Feature ID (defaults to active feature)')
+  .option('--title <title>', 'New title')
+  .option(
+    '--description <text>',
+    'New description, used verbatim (never read as a file path)',
+  )
+  .option(
+    '--description-file <path>',
+    'Read the new description from a file, or "-" for stdin',
+  )
+  .option('--metadata <json>', 'New metadata as a JSON string')
+  .action(async (id: string | undefined, opts) => {
+    try {
+      const featureId = id ?? resolveFeature()
+      if (!featureId) {
+        throw new Error(
+          'No feature specified. Pass an ID or set an active feature.',
+        )
+      }
+      const variables: Record<string, unknown> = { id: featureId }
+      if (opts.title != null) variables.title = opts.title
+      if (opts.description != null || opts.descriptionFile != null) {
+        variables.description = await resolveDescription({
+          description: opts.description,
+          descriptionFile: opts.descriptionFile,
+        })
+      }
+      if (opts.metadata != null) variables.metadata = opts.metadata
+      const data = await graphql<{ updateNode: unknown }>(
+        `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
+          updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
+            id type title description status metadata createdAt updatedAt
+          }
+        }`,
+        variables,
+      )
+      output(data.updateNode)
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+featureCommand
+  .command('delete')
+  .description('Delete a feature')
+  .argument('[id]', 'Feature ID (defaults to active feature)')
+  .action(async (id?: string) => {
+    try {
+      const featureId = id ?? resolveFeature()
+      if (!featureId) {
+        throw new Error(
+          'No feature specified. Pass an ID or set an active feature.',
+        )
+      }
+      const data = await graphql<{ deleteNode: boolean }>(
+        `mutation DeleteNode($id: String!) {
+          deleteNode(id: $id)
+        }`,
+        { id: featureId },
+      )
+      output({ deleted: data.deleteNode })
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
 featureCommand
   .command('show')
   .description('Show feature details')

package/src/commands/project.test.ts

@@ -3,6 +3,10 @@ import { homedir } from 'node:os'
 import { resolve } from 'node:path'
 import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
 
+vi.mock('../util/client.ts', () => ({
+  graphql: vi.fn(),
+}))
+
 const CONFIG_PATH = resolve(homedir(), '.config', 'flowy', 'config.json')
 
 describe('project command', () => {
@@ -24,7 +28,7 @@ describe('project command', () => {
     vi.restoreAllMocks()
   })
 
-  test('exports a command group named "project" with create, set, list, show subcommands', async () => {
+  test('exports a command group named "project" with create, set, list, show, update, delete subcommands', async () => {
     const { projectCommand } = await import('./project.ts')
     expect(projectCommand.name()).toBe('project')
     const subcommandNames = projectCommand.commands.map((c) => c.name())
@@ -32,7 +36,9 @@ describe('project command', () => {
     expect(subcommandNames).toContain('set')
     expect(subcommandNames).toContain('list')
     expect(subcommandNames).toContain('show')
-    expect(projectCommand.commands).toHaveLength(4)
+    expect(subcommandNames).toContain('update')
+    expect(subcommandNames).toContain('delete')
+    expect(projectCommand.commands).toHaveLength(6)
   })
 
   test('show without id calls requireProject which throws when no project configured', async () => {
@@ -80,4 +86,165 @@ describe('project command', () => {
       name: 'Second',
     })
   })
+
+  test('update sends updateNode with only the title when title-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      updateNode: { id: 'proj_1', title: 'New' },
+    })
+
+    const updateCmd = projectCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(['proj_1', '--title', 'New'], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'proj_1',
+        title: 'New',
+      },
+    )
+  })
+
+  test('update sends updateNode with only the description when description-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    vi.mocked(graphql).mockResolvedValueOnce({ updateNode: { id: 'proj_1' } })
+
+    const updateCmd = projectCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(['proj_1', '--description', 'Body'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'proj_1',
+        description: 'Body',
+      },
+    )
+  })
+
+  test('update sends updateNode with only the metadata when metadata-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    vi.mocked(graphql).mockResolvedValueOnce({ updateNode: { id: 'proj_1' } })
+
+    const updateCmd = projectCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(['proj_1', '--metadata', '{"k":"v"}'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'proj_1',
+        metadata: '{"k":"v"}',
+      },
+    )
+  })
+
+  test('update sends updateNode with combined fields', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    vi.mocked(graphql).mockResolvedValueOnce({ updateNode: { id: 'proj_1' } })
+
+    const updateCmd = projectCommand.commands.find(
+      (c) => c.name() === 'update',
+    )!
+    await updateCmd.parseAsync(
+      ['proj_1', '--title', 'New', '--description', 'Body', '--metadata', '{}'],
+      { from: 'user' },
+    )
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'proj_1',
+        title: 'New',
+        description: 'Body',
+        metadata: '{}',
+      },
+    )
+  })
+
+  test('delete sends deleteNode mutation', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    vi.spyOn(console, 'log').mockImplementation(() => {})
+
+    vi.mocked(graphql).mockResolvedValueOnce({ deleteNode: true })
+
+    const deleteCmd = projectCommand.commands.find(
+      (c) => c.name() === 'delete',
+    )!
+    await deleteCmd.parseAsync(['proj_1'], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('deleteNode'),
+      {
+        id: 'proj_1',
+      },
+    )
+  })
+
+  test('delete surfaces CONFLICT with exit code 1', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    const mockExit = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+    const mockStderr = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const conflict = Object.assign(new Error('has children'), {
+      code: 'CONFLICT',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(conflict)
+
+    const deleteCmd = projectCommand.commands.find(
+      (c) => c.name() === 'delete',
+    )!
+    await deleteCmd.parseAsync(['proj_1'], { from: 'user' })
+
+    expect(mockStderr).toHaveBeenCalledWith(expect.stringContaining('CONFLICT'))
+    expect(mockExit).toHaveBeenCalledWith(1)
+  })
+
+  test('delete surfaces NOT_FOUND with exit code 2', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { projectCommand } = await import('./project.ts')
+    const mockExit = vi
+      .spyOn(process, 'exit')
+      .mockImplementation(() => undefined as never)
+    const mockStderr = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const notFound = Object.assign(new Error('Node proj_x not found'), {
+      code: 'NOT_FOUND',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(notFound)
+
+    const deleteCmd = projectCommand.commands.find(
+      (c) => c.name() === 'delete',
+    )!
+    await deleteCmd.parseAsync(['proj_x'], { from: 'user' })
+
+    expect(mockStderr).toHaveBeenCalledWith(
+      expect.stringContaining('NOT_FOUND'),
+    )
+    expect(mockExit).toHaveBeenCalledWith(2)
+  })
 })

package/src/commands/project.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander'
 import { graphql } from '../util/client.ts'
 import { loadConfig, requireProject, saveConfig } from '../util/config.ts'
+import { resolveDescription } from '../util/description.ts'
 import { output, outputError } from '../util/format.ts'
 
 export const projectCommand = new Command('project').description(
@@ -102,3 +103,62 @@ projectCommand
   .description('Show project details')
   .argument('[id]', 'Project ID (defaults to active project)')
   .action(async (id?: string) => showProject(id))
+
+projectCommand
+  .command('update')
+  .description('Update a project')
+  .argument('[id]', 'Project ID (defaults to active project)')
+  .option('--title <title>', 'New title')
+  .option(
+    '--description <text>',
+    'New description, used verbatim (never read as a file path)',
+  )
+  .option(
+    '--description-file <path>',
+    'Read the new description from a file, or "-" for stdin',
+  )
+  .option('--metadata <json>', 'New metadata as a JSON string')
+  .action(async (id: string | undefined, opts) => {
+    try {
+      const projectId = id ?? requireProject().id
+      const variables: Record<string, unknown> = { id: projectId }
+      if (opts.title != null) variables.title = opts.title
+      if (opts.description != null || opts.descriptionFile != null) {
+        variables.description = await resolveDescription({
+          description: opts.description,
+          descriptionFile: opts.descriptionFile,
+        })
+      }
+      if (opts.metadata != null) variables.metadata = opts.metadata
+      const data = await graphql<{ updateNode: unknown }>(
+        `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
+          updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
+            id type title description status metadata createdAt updatedAt
+          }
+        }`,
+        variables,
+      )
+      output(data.updateNode)
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+projectCommand
+  .command('delete')
+  .description('Delete a project')
+  .argument('[id]', 'Project ID (defaults to active project)')
+  .action(async (id?: string) => {
+    try {
+      const projectId = id ?? requireProject().id
+      const data = await graphql<{ deleteNode: boolean }>(
+        `mutation DeleteNode($id: String!) {
+          deleteNode(id: $id)
+        }`,
+        { id: projectId },
+      )
+      output({ deleted: data.deleteNode })
+    } catch (error) {
+      outputError(error)
+    }
+  })

package/src/commands/task.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test, vi } from 'vitest'
+import { beforeEach, describe, expect, test, vi } from 'vitest'
 
 vi.mock('../util/config.ts', () => ({
   requireFeature: vi.fn(() => {
@@ -6,6 +6,7 @@ vi.mock('../util/config.ts', () => ({
       'No active feature. Run "flowy feature set <name-or-id>" or set FLOWY_FEATURE.',
     )
   }),
+  resolveProject: vi.fn(() => ({ id: 'proj_active', name: 'active' })),
 }))
 
 vi.mock('../util/client.ts', () => ({
@@ -18,10 +19,14 @@ vi.mock('../util/format.ts', () => ({
 }))
 
 describe('task command', () => {
-  test('exports a command group with 5 subcommands', async () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('exports a command group with 8 subcommands', async () => {
     const { taskCommand } = await import('./task.ts')
     expect(taskCommand.name()).toBe('task')
-    expect(taskCommand.commands).toHaveLength(5)
+    expect(taskCommand.commands).toHaveLength(8)
 
     const names = taskCommand.commands.map((c) => c.name())
     expect(names).toContain('create')
@@ -29,6 +34,9 @@ describe('task command', () => {
     expect(names).toContain('show')
     expect(names).toContain('block')
     expect(names).toContain('unblock')
+    expect(names).toContain('update')
+    expect(names).toContain('delete')
+    expect(names).toContain('deps')
   })
 
   test('create exposes both --description and --description-file options', async () => {
@@ -88,4 +96,301 @@ describe('task command', () => {
       }),
     )
   })
+
+  test('update sends updateNode with only the title when title-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      updateNode: { id: 'task_1', title: 'New' },
+    })
+
+    const updateCmd = taskCommand.commands.find((c) => c.name() === 'update')!
+    await updateCmd.parseAsync(['task_1', '--title', 'New'], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      { id: 'task_1', title: 'New' },
+    )
+    expect(output).toHaveBeenCalledWith({ id: 'task_1', title: 'New' })
+  })
+
+  test('update sends updateNode with only the description when description-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      updateNode: { id: 'task_1' },
+    })
+
+    const updateCmd = taskCommand.commands.find((c) => c.name() === 'update')!
+    await updateCmd.parseAsync(['task_1', '--description', 'Body'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'task_1',
+        description: 'Body',
+      },
+    )
+  })
+
+  test('update sends updateNode with only the metadata when metadata-only', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      updateNode: { id: 'task_1' },
+    })
+
+    const updateCmd = taskCommand.commands.find((c) => c.name() === 'update')!
+    await updateCmd.parseAsync(['task_1', '--metadata', '{"k":"v"}'], {
+      from: 'user',
+    })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'task_1',
+        metadata: '{"k":"v"}',
+      },
+    )
+  })
+
+  test('update sends updateNode with combined fields', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      updateNode: { id: 'task_1' },
+    })
+
+    const updateCmd = taskCommand.commands.find((c) => c.name() === 'update')!
+    await updateCmd.parseAsync(
+      ['task_1', '--title', 'New', '--description', 'Body', '--metadata', '{}'],
+      { from: 'user' },
+    )
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('updateNode'),
+      {
+        id: 'task_1',
+        title: 'New',
+        description: 'Body',
+        metadata: '{}',
+      },
+    )
+  })
+
+  test('update surfaces NOT_FOUND via outputError with its code', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    const notFound = Object.assign(new Error('Node task_x not found'), {
+      code: 'NOT_FOUND',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(notFound)
+
+    const updateCmd = taskCommand.commands.find((c) => c.name() === 'update')!
+    await updateCmd.parseAsync(['task_x', '--title', 'New'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: 'NOT_FOUND' }),
+    )
+  })
+
+  test('delete sends deleteNode mutation', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ deleteNode: true })
+
+    const deleteCmd = taskCommand.commands.find((c) => c.name() === 'delete')!
+    await deleteCmd.parseAsync(['task_1'], { from: 'user' })
+
+    expect(graphql).toHaveBeenCalledWith(
+      expect.stringContaining('deleteNode'),
+      {
+        id: 'task_1',
+      },
+    )
+    expect(output).toHaveBeenCalledWith({ deleted: true })
+  })
+
+  test('delete surfaces CONFLICT via outputError with its code', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    const conflict = Object.assign(new Error('has children'), {
+      code: 'CONFLICT',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(conflict)
+
+    const deleteCmd = taskCommand.commands.find((c) => c.name() === 'delete')!
+    await deleteCmd.parseAsync(['task_1'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: 'CONFLICT' }),
+    )
+  })
+
+  test('delete surfaces NOT_FOUND via outputError with its code', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    const notFound = Object.assign(new Error('Node task_x not found'), {
+      code: 'NOT_FOUND',
+    })
+    vi.mocked(graphql).mockRejectedValueOnce(notFound)
+
+    const deleteCmd = taskCommand.commands.find((c) => c.name() === 'delete')!
+    await deleteCmd.parseAsync(['task_x'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ code: 'NOT_FOUND' }),
+    )
+  })
+
+  test('show includes blockedBy and blocks in its output', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      node: { id: 'task_a', title: 'A', status: 'draft' },
+      blockedBy: [{ id: 'task_b', title: 'B', status: 'in_progress' }],
+      blocks: [{ id: 'task_c', title: 'C', status: 'draft' }],
+    })
+
+    const showCmd = taskCommand.commands.find((c) => c.name() === 'show')!
+    await showCmd.parseAsync(['task_a'], { from: 'user' })
+
+    expect(output).toHaveBeenCalledWith(
+      expect.objectContaining({
+        id: 'task_a',
+        blockedBy: [{ id: 'task_b', title: 'B', status: 'in_progress' }],
+        blocks: [{ id: 'task_c', title: 'C', status: 'draft' }],
+      }),
+    )
+  })
+
+  test('show queries edges for both directions of blocks', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      node: { id: 'task_a', title: 'A', status: 'draft' },
+      blockedBy: [],
+      blocks: [],
+    })
+
+    const showCmd = taskCommand.commands.find((c) => c.name() === 'show')!
+    await showCmd.parseAsync(['task_a'], { from: 'user' })
+
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('blockedBy')
+    expect(query).toContain('blocks')
+    expect(variables).toMatchObject({ id: 'task_a' })
+  })
+
+  test('deps lists blockedBy and blocks for a task', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      blockedBy: [{ id: 'task_b', title: 'B', status: 'draft' }],
+      blocks: [{ id: 'task_c', title: 'C', status: 'done' }],
+    })
+
+    const depsCmd = taskCommand.commands.find((c) => c.name() === 'deps')!
+    await depsCmd.parseAsync(['task_a'], { from: 'user' })
+
+    expect(output).toHaveBeenCalledWith({
+      id: 'task_a',
+      blockedBy: [{ id: 'task_b', title: 'B', status: 'draft' }],
+      blocks: [{ id: 'task_c', title: 'C', status: 'done' }],
+    })
+  })
+
+  test('deps surfaces errors via outputError', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockRejectedValueOnce(new Error('Node task_a not found'))
+
+    const depsCmd = taskCommand.commands.find((c) => c.name() === 'deps')!
+    await depsCmd.parseAsync(['task_a'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'Node task_a not found' }),
+    )
+  })
+
+  test('list --ready queries readyTasks and prints them', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      readyTasks: [{ id: 'task_x', title: 'X', status: 'draft' }],
+    })
+
+    const listCmd = taskCommand.commands.find((c) => c.name() === 'list')!
+    await listCmd.parseAsync(['--ready'], { from: 'user' })
+
+    const [query] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('readyTasks')
+    expect(output).toHaveBeenCalledWith([
+      { id: 'task_x', title: 'X', status: 'draft' },
+    ])
+  })
+
+  test('list --ready --project scopes readyTasks to the given project', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({ readyTasks: [] })
+
+    const listCmd = taskCommand.commands.find((c) => c.name() === 'list')!
+    await listCmd.parseAsync(['--ready', '--project', 'proj_42'], {
+      from: 'user',
+    })
+
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('readyTasks')
+    expect(variables).toMatchObject({ projectId: 'proj_42' })
+  })
+
+  test('list --all lists every task node', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { taskCommand } = await import('./task.ts')
+
+    vi.mocked(graphql).mockResolvedValueOnce({
+      nodes: [
+        { id: 'task_1', type: 'task', title: 'One', status: 'draft' },
+        { id: 'task_2', type: 'task', title: 'Two', status: 'done' },
+      ],
+    })
+
+    const listCmd = taskCommand.commands.find((c) => c.name() === 'list')!
+    await listCmd.parseAsync(['--all'], { from: 'user' })
+
+    const [query, variables] = vi.mocked(graphql).mock.calls[0]!
+    expect(query).toContain('nodes')
+    expect(variables).toMatchObject({ type: 'task' })
+    expect(output).toHaveBeenCalledWith([
+      { id: 'task_1', type: 'task', title: 'One', status: 'draft' },
+      { id: 'task_2', type: 'task', title: 'Two', status: 'done' },
+    ])
+  })
 })

package/src/commands/task.ts

@@ -1,6 +1,6 @@
 import { Command } from 'commander'
 import { graphql } from '../util/client.ts'
-import { requireFeature } from '../util/config.ts'
+import { requireFeature, resolveProject } from '../util/config.ts'
 import { resolveDescription } from '../util/description.ts'
 import { output, outputError } from '../util/format.ts'
 
@@ -53,8 +53,45 @@ taskCommand
 taskCommand
   .command('list')
   .description('List tasks in the active feature')
-  .action(async () => {
+  .option(
+    '--ready',
+    'Only actionable tasks: not done/cancelled and with zero unfinished blockers',
+  )
+  .option('--all', 'List every task across the whole backlog')
+  .option(
+    '--project <id>',
+    'Scope --ready/--all to a project (defaults to the active project)',
+  )
+  .action(async (opts) => {
     try {
+      if (opts.ready) {
+        const projectId =
+          opts.project ?? (opts.all ? undefined : resolveProject()?.id)
+        const data = await graphql<{ readyTasks: unknown[] }>(
+          `query ReadyTasks($projectId: String) {
+            readyTasks(projectId: $projectId) {
+              id type title status createdAt
+            }
+          }`,
+          { projectId: projectId ?? null },
+        )
+        output(data.readyTasks)
+        return
+      }
+
+      if (opts.all) {
+        const data = await graphql<{ nodes: unknown[] }>(
+          `query AllTasks($type: String!) {
+            nodes(type: $type) {
+              id type title status createdAt
+            }
+          }`,
+          { type: 'task' },
+        )
+        output(data.nodes)
+        return
+      }
+
       const featureId = requireFeature()
       const data = await graphql<{ descendants: unknown[] }>(
         `query ListTasks($nodeId: String!, $relation: String!, $maxDepth: Int) {
@@ -75,19 +112,90 @@ taskCommand
 
 taskCommand
   .command('show')
-  .description('Show task details')
+  .description('Show task details, including its blockedBy/blocks dependencies')
   .argument('<id>', 'Task ID')
   .action(async (id: string) => {
     try {
-      const data = await graphql<{ node: unknown }>(
+      const data = await graphql<{
+        node: Record<string, unknown>
+        blockedBy: unknown[]
+        blocks: unknown[]
+      }>(
         `query ShowTask($id: String!) {
           node(id: $id) {
             id type title description status metadata createdAt updatedAt
           }
+          blockedBy: edges(nodeId: $id, relation: "blocks", direction: "incoming") {
+            id type title status
+          }
+          blocks: edges(nodeId: $id, relation: "blocks", direction: "outgoing") {
+            id type title status
+          }
+        }`,
+        { id },
+      )
+      output({
+        ...data.node,
+        blockedBy: data.blockedBy,
+        blocks: data.blocks,
+      })
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+taskCommand
+  .command('update')
+  .description('Update a task')
+  .argument('<id>', 'Task ID')
+  .option('--title <title>', 'New title')
+  .option(
+    '--description <text>',
+    'New description, used verbatim (never read as a file path)',
+  )
+  .option(
+    '--description-file <path>',
+    'Read the new description from a file, or "-" for stdin',
+  )
+  .option('--metadata <json>', 'New metadata as a JSON string')
+  .action(async (id: string, opts) => {
+    try {
+      const variables: Record<string, unknown> = { id }
+      if (opts.title != null) variables.title = opts.title
+      if (opts.description != null || opts.descriptionFile != null) {
+        variables.description = await resolveDescription({
+          description: opts.description,
+          descriptionFile: opts.descriptionFile,
+        })
+      }
+      if (opts.metadata != null) variables.metadata = opts.metadata
+      const data = await graphql<{ updateNode: unknown }>(
+        `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
+          updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
+            id type title description status metadata createdAt updatedAt
+          }
+        }`,
+        variables,
+      )
+      output(data.updateNode)
+    } catch (error) {
+      outputError(error)
+    }
+  })
+
+taskCommand
+  .command('delete')
+  .description('Delete a task')
+  .argument('<id>', 'Task ID')
+  .action(async (id: string) => {
+    try {
+      const data = await graphql<{ deleteNode: boolean }>(
+        `mutation DeleteNode($id: String!) {
+          deleteNode(id: $id)
         }`,
         { id },
       )
-      output(data.node)
+      output({ deleted: data.deleteNode })
     } catch (error) {
       outputError(error)
     }
@@ -132,3 +240,26 @@ taskCommand
       outputError(error)
     }
   })
+
+taskCommand
+  .command('deps')
+  .description('List a task’s dependencies: what blocks it and what it blocks')
+  .argument('<id>', 'Task ID')
+  .action(async (id: string) => {
+    try {
+      const data = await graphql<{ blockedBy: unknown[]; blocks: unknown[] }>(
+        `query TaskDeps($id: String!) {
+          blockedBy: edges(nodeId: $id, relation: "blocks", direction: "incoming") {
+            id type title status
+          }
+          blocks: edges(nodeId: $id, relation: "blocks", direction: "outgoing") {
+            id type title status
+          }
+        }`,
+        { id },
+      )
+      output({ id, blockedBy: data.blockedBy, blocks: data.blocks })
+    } catch (error) {
+      outputError(error)
+    }
+  })