@sqaoss/flowy 1.4.0 → 1.6.0

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,33 @@ 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)
+      output({
+        ...data.node,
+        blockedBy: data.blockedBy,
+        blocks: data.blocks,
+      })
     } catch (error) {
       outputError(error)
     }
@@ -189,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)
+    }
+  })

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`
+}