@sqaoss/flowy 1.5.0 → 1.6.1

package/src/commands/export.test.ts

@@ -0,0 +1,242 @@
+import { beforeEach, describe, expect, test, vi } from 'vitest'
+
+vi.mock('../util/client.ts', () => ({
+  graphql: vi.fn(),
+}))
+
+vi.mock('../util/config.ts', () => ({
+  requireProject: vi.fn(() => ({ id: 'srv_proj', name: 'Demo' })),
+}))
+
+vi.mock('../util/format.ts', () => ({
+  output: vi.fn(),
+  outputError: vi.fn(),
+}))
+
+vi.mock('node:fs', () => ({
+  writeFileSync: vi.fn(),
+}))
+
+const FLOWY_KEY_FIELD = '__flowyKey'
+
+/** A server node row stamped with its client-key only (no edges in metadata). */
+function srv(
+  id: string,
+  type: string,
+  title: string,
+  key: string,
+  extraMeta: Record<string, unknown> = {},
+): Record<string, unknown> {
+  return {
+    id,
+    type,
+    title,
+    description: null,
+    status: 'draft',
+    metadata: JSON.stringify({ ...extraMeta, [FLOWY_KEY_FIELD]: key }),
+  }
+}
+
+/**
+ * Build a graphql mock backed by a node set and a real-edge-model edge set.
+ * `edges` are SERVER-id triples; the `edges()` query returns connected nodes
+ * (with metadata) so export can resolve their client-keys.
+ */
+function mockServer(
+  graphql: ReturnType<typeof vi.fn>,
+  project: Record<string, unknown>,
+  descendants: Array<Record<string, unknown>>,
+  edges: Array<{ source: string; target: string; relation: string }> = [],
+) {
+  const byId = new Map<string, Record<string, unknown>>()
+  for (const n of [project, ...descendants]) byId.set(n.id as string, n)
+  graphql.mockImplementation(
+    async (query: string, variables?: Record<string, unknown>) => {
+      if (query.includes('descendants')) return { descendants }
+      if (query.includes('node(')) return { node: project }
+      if (query.includes('edges(')) {
+        const out = edges
+          .filter(
+            (e) =>
+              e.source === variables?.nodeId &&
+              e.relation === variables?.relation,
+          )
+          .map((e) => {
+            const n = byId.get(e.target)
+            return { id: e.target, metadata: n?.metadata ?? null }
+          })
+        return { edges: out }
+      }
+      return {}
+    },
+  )
+}
+
+describe('export command', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+  })
+
+  test('exports a no-argument export command (optional output path)', async () => {
+    const { exportCommand } = await import('./export.ts')
+    expect(exportCommand.name()).toBe('export')
+  })
+
+  test('emits a manifest with client-keys and edges read from the edge model', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { exportCommand } = await import('./export.ts')
+
+    const project = srv('srv_proj', 'project', 'Demo', 'proj')
+    const feature = srv('srv_feat-1', 'feature', 'Auth', 'feat-1')
+    const task1 = srv('srv_task-1', 'task', 'Login', 'task-1', {
+      priority: 'high',
+    })
+    const task2 = srv('srv_task-2', 'task', 'Logout', 'task-2')
+
+    mockServer(
+      vi.mocked(graphql),
+      project,
+      [feature, task1, task2],
+      [
+        { 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' },
+      ],
+    )
+
+    await exportCommand.parseAsync([], { from: 'user' })
+
+    const manifest = vi.mocked(output).mock.calls.at(-1)?.[0] as {
+      version: number
+      nodes: Array<Record<string, unknown>>
+      edges: Array<Record<string, unknown>>
+    }
+
+    expect(manifest.version).toBe(1)
+    expect(manifest.nodes).toHaveLength(4)
+
+    const byKey = Object.fromEntries(manifest.nodes.map((n) => [n.key, n]))
+    expect(byKey.proj).toMatchObject({ type: 'project', title: 'Demo' })
+    // The reserved client-key field is stripped from exported user metadata.
+    expect(byKey['task-1']).toMatchObject({
+      type: 'task',
+      parent: 'feat-1',
+      metadata: { priority: 'high' },
+    })
+    expect(
+      (byKey['task-1'] as { metadata: Record<string, unknown> }).metadata
+        .__flowyKey,
+    ).toBeUndefined()
+
+    // 3 part_of edges + 1 blocks edge, expressed in client-keys.
+    expect(manifest.edges).toHaveLength(4)
+    expect(manifest.edges).toContainEqual({
+      source: 'task-2',
+      target: 'task-1',
+      relation: 'blocks',
+    })
+    expect(manifest.edges).toContainEqual({
+      source: 'feat-1',
+      target: 'proj',
+      relation: 'part_of',
+    })
+  })
+
+  test('captures an externally-created (task block) edge, not just import edges', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { exportCommand } = await import('./export.ts')
+
+    const project = srv('srv_proj', 'project', 'Demo', 'proj')
+    const task1 = srv('srv_task-1', 'task', 'A', 'task-1')
+    const task2 = srv('srv_task-2', 'task', 'B', 'task-2')
+
+    mockServer(
+      vi.mocked(graphql),
+      project,
+      [task1, task2],
+      [
+        { source: 'srv_task-1', target: 'srv_proj', relation: 'part_of' },
+        { source: 'srv_task-2', target: 'srv_proj', relation: 'part_of' },
+        // This edge exists only in the edge model (e.g. created by `task block`),
+        // never recorded in any node metadata — export must still capture it.
+        { source: 'srv_task-1', target: 'srv_task-2', relation: 'blocks' },
+      ],
+    )
+
+    await exportCommand.parseAsync([], { from: 'user' })
+
+    const manifest = vi.mocked(output).mock.calls.at(-1)?.[0] as {
+      edges: Array<Record<string, unknown>>
+    }
+    expect(manifest.edges).toContainEqual({
+      source: 'task-1',
+      target: 'task-2',
+      relation: 'blocks',
+    })
+  })
+
+  test('writes to a file when an output path is given', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { writeFileSync } = await import('node:fs')
+    const { exportCommand } = await import('./export.ts')
+
+    const project = srv('srv_proj', 'project', 'Demo', 'proj')
+    mockServer(vi.mocked(graphql), project, [])
+
+    await exportCommand.parseAsync(['out.json'], { from: 'user' })
+
+    expect(writeFileSync).toHaveBeenCalledWith(
+      'out.json',
+      expect.stringContaining('"version": 1'),
+    )
+  })
+
+  test('export output round-trips: it is a valid import manifest', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { output } = await import('../util/format.ts')
+    const { parseManifest, serializeManifest } = await import(
+      '../util/manifest.ts'
+    )
+    const { exportCommand } = await import('./export.ts')
+
+    const project = srv('srv_proj', 'project', 'Demo', 'proj')
+    const feature = srv('srv_feat-1', 'feature', 'Auth', 'feat-1')
+    const task = srv('srv_task-1', 'task', 'Login', 'task-1')
+
+    mockServer(
+      vi.mocked(graphql),
+      project,
+      [feature, task],
+      [
+        { source: 'srv_feat-1', target: 'srv_proj', relation: 'part_of' },
+        { source: 'srv_task-1', target: 'srv_feat-1', relation: 'part_of' },
+        { source: 'srv_task-1', target: 'srv_feat-1', relation: 'blocks' },
+      ],
+    )
+
+    await exportCommand.parseAsync([], { from: 'user' })
+
+    const manifest = vi.mocked(output).mock.calls.at(-1)?.[0]
+    // Re-parsing the exported manifest through the import parser must succeed
+    // and preserve structure — the export→import contract.
+    const reparsed = parseManifest(serializeManifest(manifest as never))
+    expect(reparsed).toEqual(manifest)
+  })
+
+  test('reports errors via outputError', async () => {
+    const { graphql } = await import('../util/client.ts')
+    const { outputError } = await import('../util/format.ts')
+    const { exportCommand } = await import('./export.ts')
+
+    vi.mocked(graphql).mockRejectedValueOnce(new Error('boom'))
+
+    await exportCommand.parseAsync([], { from: 'user' })
+
+    expect(outputError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'boom' }),
+    )
+  })
+})

package/src/commands/export.ts

@@ -0,0 +1,130 @@
+import { writeFileSync } from 'node:fs'
+import { Command } from 'commander'
+import { graphql } from '../util/client.ts'
+import { requireProject } from '../util/config.ts'
+import { output, outputError } from '../util/format.ts'
+import {
+  MANIFEST_VERSION,
+  type Manifest,
+  type ManifestEdge,
+  type ManifestNode,
+  readClientKey,
+  serializeManifest,
+  stripClientKey,
+} from '../util/manifest.ts'
+
+/** Relations export captures from the real edge model. */
+const RELATIONS = ['part_of', 'blocks'] as const
+
+interface ServerNode {
+  id: string
+  type: string
+  title: string
+  description: string | null
+  status: string
+  metadata: string | null
+}
+
+const PROJECT_QUERY = `query ExportProject($id: String!) {
+  node(id: $id) { id type title description status metadata }
+}`
+
+const DESCENDANTS_QUERY = `query ExportDescendants($nodeId: String!, $relation: String, $maxDepth: Int) {
+  descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
+    id type title description status metadata
+  }
+}`
+
+const EDGES_QUERY = `query ExportEdges($nodeId: String!, $relation: String!) {
+  edges(nodeId: $nodeId, relation: $relation, direction: "outgoing") {
+    id metadata
+  }
+}`
+
+export const exportCommand = new Command('export')
+  .description(
+    'Dump the active project (nodes + edges, with client-keys) as a manifest',
+  )
+  .argument('[output]', 'Write to this file instead of stdout')
+  .action(async (outputPath: string | undefined) => {
+    try {
+      const project = requireProject()
+      const root = await graphql<{ node: ServerNode | null }>(PROJECT_QUERY, {
+        id: project.id,
+      })
+      if (!root.node) {
+        throw new Error(`Active project ${project.id} not found.`)
+      }
+      const descendants = await graphql<{ descendants: ServerNode[] }>(
+        DESCENDANTS_QUERY,
+        { nodeId: project.id, relation: 'part_of', maxDepth: 100 },
+      )
+
+      const serverNodes = [root.node, ...descendants.descendants]
+
+      // Map server id -> client-key so edges (which the server returns by id)
+      // can be expressed in the manifest's client-key space. A node without a
+      // recorded key falls back to its server id so it still round-trips.
+      const keyOf = (id: string, metadata: string | null) =>
+        readClientKey(metadata) ?? id
+      const keyById = new Map<string, string>()
+      for (const sn of serverNodes)
+        keyById.set(sn.id, keyOf(sn.id, sn.metadata))
+
+      const nodes: ManifestNode[] = serverNodes.map((sn) => {
+        const node: ManifestNode = {
+          key: keyById.get(sn.id) ?? sn.id,
+          type: sn.type,
+          title: sn.title,
+        }
+        if (sn.description != null) node.description = sn.description
+        if (sn.status != null) node.status = sn.status
+        const userMeta = stripClientKey(sn.metadata)
+        if (userMeta) node.metadata = userMeta
+        return node
+      })
+
+      // Read edges back through the real edge model, so we capture ALL edges,
+      // including ones created outside import (e.g. `task block`), not just
+      // those import created.
+      const edges: ManifestEdge[] = []
+      const seen = new Set<string>()
+      for (const sn of serverNodes) {
+        const sourceKey = keyById.get(sn.id) ?? sn.id
+        for (const relation of RELATIONS) {
+          const data = await graphql<{
+            edges: Array<{ id: string; metadata: string | null }>
+          }>(EDGES_QUERY, { nodeId: sn.id, relation })
+          for (const target of data.edges) {
+            const targetKey =
+              keyById.get(target.id) ?? keyOf(target.id, target.metadata)
+            const k = `${sourceKey}|${targetKey}|${relation}`
+            if (seen.has(k)) continue
+            seen.add(k)
+            // part_of is surfaced as the node's `parent` so import re-derives it,
+            // and is also kept in the edge list for a complete dependency graph.
+            if (relation === 'part_of') {
+              const node = nodes.find((n) => n.key === sourceKey)
+              if (node) node.parent = targetKey
+            }
+            edges.push({ source: sourceKey, target: targetKey, relation })
+          }
+        }
+      }
+
+      const manifest: Manifest = { version: MANIFEST_VERSION, nodes, edges }
+
+      if (outputPath) {
+        writeFileSync(outputPath, serializeManifest(manifest))
+        output({
+          exported: nodes.length,
+          edges: edges.length,
+          file: outputPath,
+        })
+      } else {
+        output(manifest)
+      }
+    } catch (error) {
+      outputError(error)
+    }
+  })

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