@sqaoss/flowy 1.5.0 → 1.6.0

package/package.json

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

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

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/index.test.ts

@@ -42,6 +42,12 @@ vi.mock('./commands/key.ts', () => ({
 vi.mock('./commands/serve.ts', () => ({
   serveCommand: { name: () => 'serve' },
 }))
+vi.mock('./commands/import.ts', () => ({
+  importCommand: { name: () => 'import' },
+}))
+vi.mock('./commands/export.ts', () => ({
+  exportCommand: { name: () => 'export' },
+}))
 
 describe('index.ts command registration', () => {
   test('registers billing and key commands', async () => {
@@ -73,4 +79,21 @@ describe('index.ts command registration', () => {
     )
     expect(indexSource).toContain('program.addCommand(serveCommand)')
   })
+
+  test('registers the import and export commands', async () => {
+    const { readFileSync } = await import('node:fs')
+    const indexSource = readFileSync(
+      new URL('./index.ts', import.meta.url).pathname,
+      'utf-8',
+    )
+
+    expect(indexSource).toContain(
+      "import { importCommand } from './commands/import.ts'",
+    )
+    expect(indexSource).toContain(
+      "import { exportCommand } from './commands/export.ts'",
+    )
+    expect(indexSource).toContain('program.addCommand(importCommand)')
+    expect(indexSource).toContain('program.addCommand(exportCommand)')
+  })
 })

package/src/index.ts

@@ -14,7 +14,9 @@ const pkg = JSON.parse(readFileSync(pkgPath, 'utf-8'))
 import { approveCommand } from './commands/approve.ts'
 import { billingCommand } from './commands/billing.ts'
 import { clientCommand } from './commands/client.ts'
+import { exportCommand } from './commands/export.ts'
 import { featureCommand } from './commands/feature.ts'
+import { importCommand } from './commands/import.ts'
 import { initCommand } from './commands/init.ts'
 import { keyCommand } from './commands/key.ts'
 import { projectCommand } from './commands/project.ts'
@@ -45,5 +47,7 @@ program.addCommand(keyCommand)
 program.addCommand(searchCommand)
 program.addCommand(treeCommand)
 program.addCommand(whoamiCommand)
+program.addCommand(importCommand)
+program.addCommand(exportCommand)
 
 program.parse()

package/src/util/manifest.test.ts

@@ -0,0 +1,159 @@
+import { describe, expect, test } from 'vitest'
+import {
+  buildNodeMetadata,
+  FLOWY_KEY_FIELD,
+  type Manifest,
+  parseManifest,
+  readClientKey,
+  serializeManifest,
+  stripClientKey,
+} from './manifest.ts'
+
+const VALID: 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' }],
+}
+
+describe('parseManifest', () => {
+  test('parses a well-formed JSON manifest', () => {
+    const m = parseManifest(JSON.stringify(VALID))
+    expect(m.version).toBe(1)
+    expect(m.nodes).toHaveLength(4)
+    expect(m.edges).toHaveLength(1)
+    expect(m.nodes[0]).toMatchObject({ key: 'proj', type: 'project' })
+  })
+
+  test('defaults edges to an empty array when omitted', () => {
+    const m = parseManifest(
+      JSON.stringify({
+        version: 1,
+        nodes: [{ key: 'proj', type: 'project', title: 'Demo' }],
+      }),
+    )
+    expect(m.edges).toEqual([])
+  })
+
+  test('throws on invalid JSON', () => {
+    expect(() => parseManifest('{not json')).toThrow(/invalid json/i)
+  })
+
+  test('throws when nodes is missing', () => {
+    expect(() => parseManifest(JSON.stringify({ version: 1 }))).toThrow(
+      /nodes/i,
+    )
+  })
+
+  test('throws when a node lacks a key', () => {
+    expect(() =>
+      parseManifest(
+        JSON.stringify({
+          version: 1,
+          nodes: [{ type: 'project', title: 'Demo' }],
+        }),
+      ),
+    ).toThrow(/key/i)
+  })
+
+  test('throws when a node lacks a type', () => {
+    expect(() =>
+      parseManifest(
+        JSON.stringify({
+          version: 1,
+          nodes: [{ key: 'x', title: 'Demo' }],
+        }),
+      ),
+    ).toThrow(/type/i)
+  })
+
+  test('throws on a duplicate client-key', () => {
+    expect(() =>
+      parseManifest(
+        JSON.stringify({
+          version: 1,
+          nodes: [
+            { key: 'dup', type: 'project', title: 'A' },
+            { key: 'dup', type: 'feature', title: 'B' },
+          ],
+        }),
+      ),
+    ).toThrow(/duplicate/i)
+  })
+
+  test('throws when an edge references an unknown key', () => {
+    expect(() =>
+      parseManifest(
+        JSON.stringify({
+          version: 1,
+          nodes: [{ key: 'a', type: 'project', title: 'A' }],
+          edges: [{ source: 'a', target: 'ghost', relation: 'blocks' }],
+        }),
+      ),
+    ).toThrow(/ghost/i)
+  })
+})
+
+describe('serializeManifest', () => {
+  test('round-trips through parse', () => {
+    const text = serializeManifest(VALID)
+    expect(parseManifest(text)).toEqual(VALID)
+  })
+
+  test('emits pretty-printed JSON', () => {
+    const text = serializeManifest(VALID)
+    expect(text).toContain('\n')
+    expect(text.endsWith('\n')).toBe(true)
+  })
+})
+
+describe('node metadata client-key', () => {
+  test('the reserved field is a single scalar key, not an edge namespace', () => {
+    expect(FLOWY_KEY_FIELD).toBe('__flowyKey')
+  })
+
+  test('buildNodeMetadata stamps the client-key alongside user metadata', () => {
+    const meta = JSON.parse(buildNodeMetadata('task-1', { priority: 'high' }))
+    expect(meta).toEqual({ priority: 'high', __flowyKey: 'task-1' })
+    // No edge data is ever stored in metadata.
+    expect(meta.__flowy).toBeUndefined()
+    expect(meta.edges).toBeUndefined()
+  })
+
+  test('buildNodeMetadata works with no user metadata', () => {
+    expect(JSON.parse(buildNodeMetadata('proj'))).toEqual({
+      __flowyKey: 'proj',
+    })
+  })
+
+  test('readClientKey extracts the key', () => {
+    expect(readClientKey(buildNodeMetadata('feat-1', { a: 1 }))).toBe('feat-1')
+  })
+
+  test('readClientKey returns null for absent/invalid metadata', () => {
+    expect(readClientKey(null)).toBeNull()
+    expect(readClientKey('{not json')).toBeNull()
+    expect(readClientKey(JSON.stringify({ a: 1 }))).toBeNull()
+  })
+
+  test('stripClientKey returns only user metadata', () => {
+    expect(
+      stripClientKey(buildNodeMetadata('x', { priority: 'high' })),
+    ).toEqual({ priority: 'high' })
+  })
+
+  test('stripClientKey returns undefined when only the key was stored', () => {
+    expect(stripClientKey(buildNodeMetadata('x'))).toBeUndefined()
+  })
+})

package/src/util/manifest.ts

@@ -0,0 +1,192 @@
+/**
+ * Flowy import/export manifest format.
+ *
+ * The manifest is the migration unit for a backlog: projects, features and
+ * tasks (`nodes`) plus their dependency `edges`, all addressed by a stable
+ * **client-key** rather than a server id. Import upserts by client-key
+ * (idempotent); export reconstructs the same shape from the server. Keeping
+ * all format knowledge in this one module means the on-disk format (JSON
+ * today — see roadmap §G, an open owner decision) can change without touching
+ * the import/export command logic.
+ *
+ * Edges live in the real edge model (`createEdge` / `Query.edges`), not in
+ * node metadata. The only thing import stamps into metadata is the node's
+ * client-key (for idempotent node upsert); export reads edges back via
+ * `Query.edges`, so it captures edges created by any path (e.g. `task block`).
+ */
+
+export interface ManifestNode {
+  /** Stable client-key — the idempotency anchor. */
+  key: string
+  /** One of: project, feature, task. */
+  type: string
+  title: string
+  description?: string
+  status?: string
+  /** Client-key of the parent node; drives the implicit `part_of` edge. */
+  parent?: string
+  /** Arbitrary user metadata (the reserved `__flowyKey` field is stripped). */
+  metadata?: Record<string, unknown>
+}
+
+export interface ManifestEdge {
+  /** Client-key of the source node. */
+  source: string
+  /** Client-key of the target node. */
+  target: string
+  relation: string
+}
+
+export interface Manifest {
+  version: number
+  nodes: ManifestNode[]
+  edges: ManifestEdge[]
+}
+
+/** The current manifest schema version. */
+export const MANIFEST_VERSION = 1
+
+/**
+ * Reserved metadata field holding a node's client-key — the only thing import
+ * writes into metadata, purely so a re-import can find the node by its stable
+ * key and update in place rather than duplicating. User metadata lives
+ * alongside it at the top level and is preserved untouched; export strips this
+ * one field back out. Edges are NOT stored here (see the module header).
+ */
+export const FLOWY_KEY_FIELD = '__flowyKey'
+
+/** Read the reserved client-key field from a server node's metadata string. */
+export function readClientKey(
+  metadata: string | null | undefined,
+): string | null {
+  if (!metadata) return null
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(metadata)
+  } catch {
+    return null
+  }
+  if (!isObject(parsed)) return null
+  const key = parsed[FLOWY_KEY_FIELD]
+  return typeof key === 'string' ? key : null
+}
+
+/** Strip the reserved client-key field, returning only user metadata (or undefined). */
+export function stripClientKey(
+  metadata: string | null | undefined,
+): Record<string, unknown> | undefined {
+  if (!metadata) return undefined
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(metadata)
+  } catch {
+    return undefined
+  }
+  if (!isObject(parsed)) return undefined
+  const { [FLOWY_KEY_FIELD]: _key, ...rest } = parsed
+  return Object.keys(rest).length > 0 ? rest : undefined
+}
+
+/** Build the metadata JSON string for a node: user metadata plus the client-key. */
+export function buildNodeMetadata(
+  key: string,
+  userMetadata?: Record<string, unknown>,
+): string {
+  return JSON.stringify({ ...(userMetadata ?? {}), [FLOWY_KEY_FIELD]: key })
+}
+
+function fail(message: string): never {
+  throw new Error(message)
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/** Parse and validate a manifest from its serialized form. */
+export function parseManifest(text: string): Manifest {
+  let raw: unknown
+  try {
+    raw = JSON.parse(text)
+  } catch {
+    fail('Invalid JSON: manifest is not valid JSON.')
+  }
+
+  if (!isObject(raw)) fail('Invalid manifest: expected a JSON object.')
+  if (!Array.isArray(raw.nodes)) {
+    fail('Invalid manifest: "nodes" must be an array.')
+  }
+
+  const seen = new Set<string>()
+  const nodes: ManifestNode[] = raw.nodes.map((entry, i) => {
+    if (!isObject(entry))
+      fail(`Invalid manifest: nodes[${i}] is not an object.`)
+    if (typeof entry.key !== 'string' || entry.key.length === 0) {
+      fail(`Invalid manifest: nodes[${i}] is missing a string "key".`)
+    }
+    if (typeof entry.type !== 'string' || entry.type.length === 0) {
+      fail(`Invalid manifest: node "${entry.key}" is missing a "type".`)
+    }
+    if (typeof entry.title !== 'string') {
+      fail(`Invalid manifest: node "${entry.key}" is missing a "title".`)
+    }
+    if (seen.has(entry.key)) {
+      fail(`Invalid manifest: duplicate client-key "${entry.key}".`)
+    }
+    seen.add(entry.key)
+    if (entry.parent != null && typeof entry.parent !== 'string') {
+      fail(`Invalid manifest: node "${entry.key}" has a non-string "parent".`)
+    }
+    if (entry.metadata != null && !isObject(entry.metadata)) {
+      fail(`Invalid manifest: node "${entry.key}" has non-object "metadata".`)
+    }
+    const node: ManifestNode = {
+      key: entry.key,
+      type: entry.type,
+      title: entry.title,
+    }
+    if (typeof entry.description === 'string')
+      node.description = entry.description
+    if (typeof entry.status === 'string') node.status = entry.status
+    if (typeof entry.parent === 'string') node.parent = entry.parent
+    if (isObject(entry.metadata)) node.metadata = entry.metadata
+    return node
+  })
+
+  for (const node of nodes) {
+    if (node.parent != null && !seen.has(node.parent)) {
+      fail(
+        `Invalid manifest: node "${node.key}" references unknown parent "${node.parent}".`,
+      )
+    }
+  }
+
+  const rawEdges = Array.isArray(raw.edges) ? raw.edges : []
+  const edges: ManifestEdge[] = rawEdges.map((entry, i) => {
+    if (!isObject(entry))
+      fail(`Invalid manifest: edges[${i}] is not an object.`)
+    const { source, target, relation } = entry
+    if (typeof source !== 'string' || typeof target !== 'string') {
+      fail(`Invalid manifest: edges[${i}] needs string "source" and "target".`)
+    }
+    if (typeof relation !== 'string' || relation.length === 0) {
+      fail(`Invalid manifest: edges[${i}] is missing a "relation".`)
+    }
+    if (!seen.has(source)) {
+      fail(`Invalid manifest: edge source "${source}" is not a known node key.`)
+    }
+    if (!seen.has(target)) {
+      fail(`Invalid manifest: edge target "${target}" is not a known node key.`)
+    }
+    return { source, target, relation }
+  })
+
+  const version =
+    typeof raw.version === 'number' ? raw.version : MANIFEST_VERSION
+  return { version, nodes, edges }
+}
+
+/** Serialize a manifest to its on-disk form (pretty-printed JSON, trailing newline). */
+export function serializeManifest(manifest: Manifest): string {
+  return `${JSON.stringify(manifest, null, 2)}\n`
+}