@sqaoss/flowy 1.4.0 → 1.6.0

package/src/commands/import.test.ts

@@ -0,0 +1,287 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+vi.mock('../util/client.ts', () => ({
+  graphql: vi.fn(),
+}))
+
+vi.mock('../util/format.ts', () => ({
+  output: vi.fn(),
+  outputError: vi.fn(),
+}))
+
+vi.mock('node:fs', () => ({
+  readFileSync: vi.fn(),
+}))
+
+const FLOWY_KEY_FIELD = '__flowyKey'
+
+/** A small representative backlog: 1 project, 1 feature, 2 tasks, 1 blocks edge. */
+const MANIFEST = {
+  version: 1,
+  nodes: [
+    { key: 'proj', type: 'project', title: 'Demo' },
+    { key: 'feat-1', type: 'feature', title: 'Auth', parent: 'proj' },
+    {
+      key: 'task-1',
+      type: 'task',
+      title: 'Login',
+      parent: 'feat-1',
+      status: 'draft',
+      metadata: { priority: 'high' },
+    },
+    { key: 'task-2', type: 'task', title: 'Logout', parent: 'feat-1' },
+  ],
+  edges: [{ source: 'task-2', target: 'task-1', relation: 'blocks' }],
+}
+
+/** Parse the JSON metadata string a CLI mutation sent to the server. */
+function metaOf(variables: Record<string, unknown>): Record<string, unknown> {
+  return JSON.parse(variables.metadata as string)
+}
+
+describe('import command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('exports a single-argument import command', async () => {
+    const { importCommand } = await import('./import.ts')
+    expect(importCommand.name()).toBe('import')
+  })
+
+  test('metadata carries only the client-key, never edge data', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { readFileSync } = await import('node:fs')
+    const { importCommand } = await import('./import.ts')
+
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify(MANIFEST))
+    vi.mocked(graphql).mockImplementation(async (query: string) => {
+      if (query.includes('nodes(')) return { nodes: [] }
+      if (query.includes('createNode')) return { createNode: { id: 'srv_x' } }
+      if (query.includes('createEdge')) return { createEdge: {} }
+      return {}
+    })
+
+    await importCommand.parseAsync(['manifest.json'], { from: 'user' })
+
+    for (const [q, vars] of vi.mocked(graphql).mock.calls) {
+      if (!q.includes('createNode')) continue
+      const meta = metaOf(vars ?? {})
+      expect(typeof meta[FLOWY_KEY_FIELD]).toBe('string')
+      // The dropped edge-stamp hack must not reappear in any form.
+      expect(meta.__flowy).toBeUndefined()
+      expect(meta.edges).toBeUndefined()
+    }
+  })
+
+  test('first run: creates every node and edge, returns a key→id map', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { readFileSync } = await import('node:fs')
+    const { importCommand } = await import('./import.ts')
+
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify(MANIFEST))
+
+    // No existing nodes for any type.
+    vi.mocked(graphql).mockImplementation(
+      async (query: string, variables?: Record<string, unknown>) => {
+        if (query.includes('nodes(')) return { nodes: [] }
+        if (query.includes('createNode')) {
+          const key = metaOf(variables ?? {})[FLOWY_KEY_FIELD] as string
+          return { createNode: { id: `srv_${key}` } }
+        }
+        if (query.includes('updateNode')) {
+          return { updateNode: { id: variables?.id } }
+        }
+        // No pre-existing nodes → the existing-edges query should never run.
+        if (query.includes('edges(')) {
+          throw new Error(
+            'edges() should not be queried with no existing nodes',
+          )
+        }
+        if (query.includes('createEdge')) return { createEdge: {} }
+        return {}
+      },
+    )
+
+    await importCommand.parseAsync(['manifest.json'], { from: 'user' })
+
+    const calls = vi.mocked(graphql).mock.calls
+    const created = calls.filter(([q]) => q.includes('createNode'))
+    const updated = calls.filter(([q]) => q.includes('updateNode'))
+    const edges = calls.filter(([q]) => q.includes('createEdge'))
+
+    // All 4 nodes created, none updated on a clean import.
+    expect(created).toHaveLength(4)
+    expect(updated).toHaveLength(0)
+
+    // part_of edges (feat-1→proj, task-1→feat-1, task-2→feat-1) + 1 blocks = 4.
+    expect(edges).toHaveLength(4)
+
+    // Output is the key→id map.
+    const mapArg = vi.mocked(output).mock.calls.at(-1)?.[0] as {
+      map: Record<string, string>
+    }
+    expect(mapArg.map).toMatchObject({
+      proj: 'srv_proj',
+      'feat-1': 'srv_feat-1',
+      'task-1': 'srv_task-1',
+      'task-2': 'srv_task-2',
+    })
+  })
+
+  test('re-import is idempotent: existing keys update, never re-create', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { readFileSync } = await import('node:fs')
+    const { importCommand } = await import('./import.ts')
+
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify(MANIFEST))
+
+    // Every manifest node already exists (carrying its client-key), and every
+    // edge already exists in the real edge model.
+    const existing = (type: string) => {
+      const byType: Record<string, Array<Record<string, unknown>>> = {
+        project: [node('proj', 'srv_proj')],
+        feature: [node('feat-1', 'srv_feat-1')],
+        task: [node('task-1', 'srv_task-1'), node('task-2', 'srv_task-2')],
+      }
+      return byType[type] ?? []
+    }
+    const edgesOf = (nodeId: string, relation: string) =>
+      EDGES.filter((e) => e.source === nodeId && e.relation === relation).map(
+        (e) => ({ id: e.target }),
+      )
+
+    vi.mocked(graphql).mockImplementation(
+      async (query: string, variables?: Record<string, unknown>) => {
+        if (query.includes('nodes(')) {
+          return { nodes: existing(variables?.type as string) }
+        }
+        if (query.includes('edges(')) {
+          return {
+            edges: edgesOf(
+              variables?.nodeId as string,
+              variables?.relation as string,
+            ),
+          }
+        }
+        if (query.includes('updateNode')) {
+          return { updateNode: { id: variables?.id } }
+        }
+        if (query.includes('createNode')) {
+          throw new Error('createNode must not be called on re-import')
+        }
+        if (query.includes('createEdge')) return { createEdge: {} }
+        return {}
+      },
+    )
+
+    await importCommand.parseAsync(['manifest.json'], { from: 'user' })
+
+    const calls = vi.mocked(graphql).mock.calls
+    const created = calls.filter(([q]) => q.includes('createNode'))
+    const updated = calls.filter(([q]) => q.includes('updateNode'))
+    const edges = calls.filter(([q]) => q.includes('createEdge'))
+
+    // No node is re-created; all four are updated in place.
+    expect(created).toHaveLength(0)
+    expect(updated).toHaveLength(4)
+
+    // Every edge already exists in the edge model → none re-created.
+    expect(edges).toHaveLength(0)
+  })
+
+  test('does not re-create an edge that already exists in the edge model', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { readFileSync } = await import('node:fs')
+    const { importCommand } = await import('./import.ts')
+
+    vi.mocked(readFileSync).mockReturnValue(JSON.stringify(MANIFEST))
+
+    const existing = (type: string) => {
+      const byType: Record<string, Array<Record<string, unknown>>> = {
+        project: [node('proj', 'srv_proj')],
+        feature: [node('feat-1', 'srv_feat-1')],
+        task: [node('task-1', 'srv_task-1'), node('task-2', 'srv_task-2')],
+      }
+      return byType[type] ?? []
+    }
+    // Only the part_of edges exist server-side; the blocks edge does not.
+    const present = EDGES.filter((e) => e.relation === 'part_of')
+    const edgesOf = (nodeId: string, relation: string) =>
+      present
+        .filter((e) => e.source === nodeId && e.relation === relation)
+        .map((e) => ({ id: e.target }))
+
+    vi.mocked(graphql).mockImplementation(
+      async (query: string, variables?: Record<string, unknown>) => {
+        if (query.includes('nodes(')) {
+          return { nodes: existing(variables?.type as string) }
+        }
+        if (query.includes('edges(')) {
+          return {
+            edges: edgesOf(
+              variables?.nodeId as string,
+              variables?.relation as string,
+            ),
+          }
+        }
+        if (query.includes('updateNode')) {
+          return { updateNode: { id: variables?.id } }
+        }
+        if (query.includes('createEdge')) return { createEdge: {} }
+        return {}
+      },
+    )
+
+    await importCommand.parseAsync(['manifest.json'], { from: 'user' })
+
+    const edges = vi
+      .mocked(graphql)
+      .mock.calls.filter(([q]) => q.includes('createEdge'))
+    expect(edges).toHaveLength(1)
+    expect(edges[0]?.[1]).toMatchObject({
+      sourceId: 'srv_task-2',
+      targetId: 'srv_task-1',
+      relation: 'blocks',
+    })
+  })
+
+  test('reports a parse error via outputError', async () => {
+    const { outputError } = await import('../util/format.ts')
+    const { readFileSync } = await import('node:fs')
+    const { importCommand } = await import('./import.ts')
+
+    vi.mocked(readFileSync).mockReturnValue('{not json')
+
+    await importCommand.parseAsync(['bad.json'], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringMatching(/invalid json/i),
+      }),
+    )
+  })
+})
+
+/** The full edge set this manifest implies, expressed in SERVER ids. */
+const EDGES = [
+  { source: 'srv_feat-1', target: 'srv_proj', relation: 'part_of' },
+  { source: 'srv_task-1', target: 'srv_feat-1', relation: 'part_of' },
+  { source: 'srv_task-2', target: 'srv_feat-1', relation: 'part_of' },
+  { source: 'srv_task-2', target: 'srv_task-1', relation: 'blocks' },
+]
+
+/**
+ * Build an existing server node row stamped with its client-key only.
+ * Edges are NOT stored in metadata — they live in the real edge model and are
+ * mocked separately via the `edges()` query.
+ */
+function node(key: string, id: string): Record<string, unknown> {
+  return {
+    id,
+    type: 'x',
+    title: key,
+    metadata: JSON.stringify({ [FLOWY_KEY_FIELD]: key }),
+  }
+}

package/src/commands/import.ts

@@ -0,0 +1,181 @@
+import { readFileSync } from 'node:fs'
+import { Command } from 'commander'
+import { graphql } from '../util/client.ts'
+import { output, outputError } from '../util/format.ts'
+import {
+  buildNodeMetadata,
+  type Manifest,
+  type ManifestNode,
+  parseManifest,
+  readClientKey,
+} from '../util/manifest.ts'
+
+const NODE_TYPES = ['project', 'feature', 'task'] as const
+
+/** Relations import materializes; existing-edge dedup queries each of these. */
+const RELATIONS = ['part_of', 'blocks'] as const
+
+interface ServerNode {
+  id: string
+  type: string
+  title: string
+  metadata: string | null
+}
+
+interface DesiredEdge {
+  sourceKey: string
+  targetKey: string
+  relation: string
+}
+
+function edgeKey(source: string, target: string, relation: string): string {
+  return `${source}|${target}|${relation}`
+}
+
+/** All edges the manifest implies: implicit `part_of` from `parent` + explicit edges. */
+function desiredEdges(manifest: Manifest): DesiredEdge[] {
+  const edges: DesiredEdge[] = []
+  const seen = new Set<string>()
+  const add = (sourceKey: string, targetKey: string, relation: string) => {
+    const k = edgeKey(sourceKey, targetKey, relation)
+    if (seen.has(k)) return
+    seen.add(k)
+    edges.push({ sourceKey, targetKey, relation })
+  }
+  for (const node of manifest.nodes) {
+    if (node.parent) add(node.key, node.parent, 'part_of')
+  }
+  for (const e of manifest.edges) add(e.source, e.target, e.relation)
+  return edges
+}
+
+/** Read every existing node, mapping its stored client-key to its server id. */
+async function loadExisting(): Promise<Map<string, string>> {
+  const idByKey = new Map<string, string>()
+  for (const type of NODE_TYPES) {
+    const data = await graphql<{ nodes: ServerNode[] }>(
+      `query ImportExisting($type: String) {
+        nodes(type: $type) { id type title metadata }
+      }`,
+      { type },
+    )
+    for (const node of data.nodes) {
+      const key = readClientKey(node.metadata)
+      if (key) idByKey.set(key, node.id)
+    }
+  }
+  return idByKey
+}
+
+/**
+ * Collect the edges that already exist for the given nodes, as a set of
+ * `<sourceId>|<targetId>|<relation>` triples. Read back through the real edge
+ * model (`Query.edges`), so externally-created edges (e.g. `task block`) are
+ * recognized and never duplicated.
+ */
+async function loadExistingEdges(nodeIds: string[]): Promise<Set<string>> {
+  const existing = new Set<string>()
+  for (const nodeId of nodeIds) {
+    for (const relation of RELATIONS) {
+      const data = await graphql<{ edges: Array<{ id: string }> }>(
+        `query ImportEdges($nodeId: String!, $relation: String!) {
+          edges(nodeId: $nodeId, relation: $relation, direction: "outgoing") { id }
+        }`,
+        { nodeId, relation },
+      )
+      for (const target of data.edges) {
+        existing.add(edgeKey(nodeId, target.id, relation))
+      }
+    }
+  }
+  return existing
+}
+
+const CREATE_NODE = `mutation ImportCreate($type: String!, $title: String!, $description: String, $status: String, $metadata: String) {
+  createNode(type: $type, title: $title, description: $description, status: $status, metadata: $metadata) { id }
+}`
+
+const UPDATE_NODE = `mutation ImportUpdate($id: String!, $title: String, $description: String, $status: String, $metadata: String) {
+  updateNode(id: $id, title: $title, description: $description, status: $status, metadata: $metadata) { id }
+}`
+
+const CREATE_EDGE = `mutation ImportEdge($sourceId: String!, $targetId: String!, $relation: String!) {
+  createEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation) { sourceId targetId relation }
+}`
+
+async function upsertNode(
+  node: ManifestNode,
+  existingId: string | undefined,
+): Promise<string> {
+  const metadata = buildNodeMetadata(node.key, node.metadata)
+  if (existingId) {
+    await graphql<{ updateNode: { id: string } }>(UPDATE_NODE, {
+      id: existingId,
+      title: node.title,
+      description: node.description ?? null,
+      status: node.status ?? null,
+      metadata,
+    })
+    return existingId
+  }
+  const data = await graphql<{ createNode: { id: string } }>(CREATE_NODE, {
+    type: node.type,
+    title: node.title,
+    description: node.description ?? null,
+    status: node.status ?? null,
+    metadata,
+  })
+  return data.createNode.id
+}
+
+export const importCommand = new Command('import')
+  .description(
+    'Ingest a manifest of projects/features/tasks + edges (idempotent by client-key)',
+  )
+  .argument('<manifest>', 'Path to a JSON manifest file')
+  .action(async (manifestPath: string) => {
+    try {
+      const manifest = parseManifest(readFileSync(manifestPath, 'utf-8'))
+      const existing = await loadExisting()
+
+      // Pass 1 — upsert every node, stamping its client-key into metadata.
+      // Known keys update, new keys create, so a re-import never duplicates.
+      const idByKey = new Map<string, string>()
+      for (const node of manifest.nodes) {
+        idByKey.set(node.key, await upsertNode(node, existing.get(node.key)))
+      }
+
+      // Dedup against edges that already exist server-side. Only nodes that
+      // pre-existed this import can already have edges, so query just those.
+      const preExistingIds = manifest.nodes
+        .filter((n) => existing.has(n.key))
+        .map((n) => idByKey.get(n.key))
+        .filter((id): id is string => id != null)
+      const present = await loadExistingEdges(preExistingIds)
+
+      // Pass 2 — materialize edges, deduped by (source,target,relation). Skip
+      // any edge that already exists so the non-idempotent createEdge is never
+      // asked to re-link.
+      let edgeCount = 0
+      for (const edge of desiredEdges(manifest)) {
+        const sourceId = idByKey.get(edge.sourceKey)
+        const targetId = idByKey.get(edge.targetKey)
+        if (!sourceId || !targetId) continue
+        if (present.has(edgeKey(sourceId, targetId, edge.relation))) continue
+        await graphql(CREATE_EDGE, {
+          sourceId,
+          targetId,
+          relation: edge.relation,
+        })
+        edgeCount++
+      }
+
+      output({
+        imported: idByKey.size,
+        edges: edgeCount,
+        map: Object.fromEntries(idByKey),
+      })
+    } catch (error) {
+      outputError(error)
+    }
+  })

package/src/commands/task.test.ts

@@ -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', () => ({
@@ -22,10 +23,10 @@ describe('task command', () => {
     vi.clearAllMocks()
   })
 
-  test('exports a command group with 7 subcommands', async () => {
+  test('exports a command group with 8 subcommands', async () => {
     const { taskCommand } = await import('./task.ts')
     expect(taskCommand.name()).toBe('task')
-    expect(taskCommand.commands).toHaveLength(7)
+    expect(taskCommand.commands).toHaveLength(8)
 
     const names = taskCommand.commands.map((c) => c.name())
     expect(names).toContain('create')
@@ -35,6 +36,7 @@ describe('task command', () => {
     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 () => {
@@ -255,4 +257,140 @@ describe('task command', () => {
       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' },
+    ])
+  })
 })