@sqaoss/flowy 1.5.0 → 1.6.1

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

@@ -97,16 +97,37 @@ describe('setup command', () => {
     )
   })
 
-  test('setup remote requires --tier', async () => {
+  test('setup remote registers without --tier (tier is optional)', async () => {
+    const mockGraphql = vi.fn().mockResolvedValue({
+      register: {
+        user: {
+          id: 'user_1',
+          email: 'test@example.com',
+          tier: null,
+          createdAt: '2026-06-13T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: 'flowy_key',
+        checkoutUrl: null,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({
+      graphql: mockGraphql,
+    }))
+    mockSpawnSync.mockReturnValue({ status: 0, stdout: Buffer.from('') })
+
     const { setupCommand } = await import('./setup.ts')
     await setupCommand.parseAsync(['remote', '--email', 'test@example.com'], {
       from: 'user',
     })
 
-    expect(mockOutputError).toHaveBeenCalledWith(
-      expect.objectContaining({
-        message: expect.stringContaining('--tier is required'),
-      }),
+    // No tier required: registration proceeds, no usage error raised.
+    expect(mockOutputError).not.toHaveBeenCalled()
+    expect(mockGraphql).toHaveBeenCalledOnce()
+    const [, variables] = mockGraphql.mock.calls[0]!
+    expect(variables).toEqual({ email: 'test@example.com', tier: undefined })
+    expect(mockSaveConfig).toHaveBeenCalledWith(
+      expect.objectContaining({ mode: 'remote', apiKey: 'flowy_key' }),
     )
   })
 
@@ -221,4 +242,68 @@ describe('setup command', () => {
       }),
     )
   })
+
+  test('setup local warns when the skill install fails', async () => {
+    // bun add succeeds, npx skills add fails (non-zero status).
+    mockSpawnSync.mockImplementation((cmd: string) =>
+      cmd === 'npx' ? { status: 1 } : { status: 0 },
+    )
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['local'], { from: 'user' })
+
+    const warned = errSpy.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(warned).toMatch(/skill/i)
+    expect(warned).toContain('npx skills add sqaoss/flowy')
+    // Setup itself still completes successfully (config saved, result emitted).
+    expect(mockOutput).toHaveBeenCalled()
+    expect(mockOutputError).not.toHaveBeenCalled()
+    errSpy.mockRestore()
+  })
+
+  test('setup local does not warn when the skill install succeeds', async () => {
+    mockSpawnSync.mockReturnValue({ status: 0 })
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['local'], { from: 'user' })
+
+    const warned = errSpy.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(warned).not.toMatch(/skill/i)
+    errSpy.mockRestore()
+  })
+
+  test('setup remote warns when the skill install fails', async () => {
+    const mockGraphql = vi.fn().mockResolvedValue({
+      register: {
+        user: {
+          id: 'user_1',
+          email: 'a@b.com',
+          tier: null,
+          createdAt: '2026-06-13T00:00:00Z',
+          graceEndsAt: null,
+        },
+        apiKey: 'flowy_key',
+        checkoutUrl: null,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({ graphql: mockGraphql }))
+    mockSpawnSync.mockImplementation((cmd: string) =>
+      cmd === 'npx' ? { status: 1 } : { status: 0 },
+    )
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['remote', '--email', 'a@b.com'], {
+      from: 'user',
+    })
+
+    const warned = errSpy.mock.calls.map((c) => String(c[0])).join('\n')
+    expect(warned).toMatch(/skill/i)
+    expect(warned).toContain('npx skills add sqaoss/flowy')
+    expect(mockOutput).toHaveBeenCalled()
+    expect(mockOutputError).not.toHaveBeenCalled()
+    errSpy.mockRestore()
+  })
 })

package/src/commands/setup.ts

@@ -8,6 +8,32 @@ export const setupCommand = new Command('setup').description(
   'Configure the Flowy CLI \u2014 use "flowy setup local" or "flowy setup remote"',
 )
 
+const SKILL_PACKAGE = 'sqaoss/flowy'
+
+/**
+ * Install the Flowy agent skill, surfacing failure instead of swallowing it.
+ *
+ * `npx skills add` can fail (offline, npx unavailable, registry hiccup). If it
+ * does, setup should still succeed \u2014 but the user must be told the skill was
+ * NOT installed, with the exact command to retry, rather than silently
+ * assuming their agent now knows the commands (F14).
+ */
+function installSkill(): void {
+  const result = spawnSync('npx', ['skills', 'add', SKILL_PACKAGE, '--yes'], {
+    stdio: 'inherit',
+  })
+  if (result.error != null || result.status !== 0) {
+    const reason = result.error
+      ? result.error.message
+      : `exit code ${result.status}`
+    console.error(
+      `Warning: failed to install the Flowy agent skill (${reason}). ` +
+        `Your agent will not know Flowy's commands until you install it manually:\n` +
+        `  npx skills add ${SKILL_PACKAGE}`,
+    )
+  }
+}
+
 setupCommand
   .command('local')
   .description('Set up Flowy with a native local server (no Docker)')
@@ -26,9 +52,7 @@ setupCommand
       config.mode = 'local'
       config.apiUrl = apiUrl
       saveConfig(config)
-      spawnSync('npx', ['skills', 'add', 'sqaoss/flowy', '--yes'], {
-        stdio: 'inherit',
-      })
+      installSkill()
 
       output({
         mode: 'local',
@@ -46,20 +70,16 @@ setupCommand
   .description('Connect to the hosted Flowy service')
   .option('--email <email>', 'Email address for registration')
   .addOption(
-    new Option('--tier <tier>', 'Subscription tier').choices([
-      'explorer',
-      'pro',
-      'team',
-    ]),
+    new Option(
+      '--tier <tier>',
+      'Subscription tier (optional — pick one later at checkout)',
+    ).choices(['explorer', 'pro', 'team']),
   )
   .action(async (opts) => {
     try {
       if (!opts.email) {
         throw new Error('--email is required for registration')
       }
-      if (!opts.tier) {
-        throw new Error('--tier is required for registration')
-      }
 
       const { graphql } = await import('../util/client.ts')
 
@@ -81,7 +101,7 @@ setupCommand
           checkoutUrl: string
         }
       }>(
-        `mutation Register($email: String!, $tier: String!) {
+        `mutation Register($email: String!, $tier: String) {
           register(email: $email, tier: $tier) {
             user { id email tier createdAt graceEndsAt }
             apiKey
@@ -94,9 +114,7 @@ setupCommand
       config.apiKey = data.register.apiKey
       saveConfig(config)
 
-      spawnSync('npx', ['skills', 'add', 'sqaoss/flowy', '--yes'], {
-        stdio: 'inherit',
-      })
+      installSkill()
 
       output(data.register)
     } catch (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()
+  })
+})