@sqaoss/flowy 1.7.0 → 1.8.0

package/src/commands/feature.ts

@@ -7,6 +7,15 @@ import {
 } from '../util/config.ts'
 import { resolveDescription } from '../util/description.ts'
 import { output, outputError } from '../util/format.ts'
+import {
+  CREATE_EDGE,
+  CREATE_NODE,
+  DELETE_NODE,
+  DESCENDANTS,
+  DESCENDANTS_BRIEF,
+  GET_NODE,
+  UPDATE_NODE,
+} from '../util/operations.ts'
 
 export const featureCommand = new Command('feature').description(
   'Manage features in the active project',
@@ -32,22 +41,15 @@ featureCommand
         descriptionFile: opts.descriptionFile,
       })
       const nodeData = await graphql<{ createNode: { id: string } }>(
-        `mutation CreateNode($type: String!, $title: String!, $description: String) {
-          createNode(type: $type, title: $title, description: $description) {
-            id type title description status createdAt updatedAt
-          }
-        }`,
+        CREATE_NODE,
         { type: 'feature', title: opts.title, description },
       )
       const featureId = nodeData.createNode.id
-      await graphql(
-        `mutation CreateEdge($sourceId: String!, $targetId: String!, $relation: String!) {
-          createEdge(sourceId: $sourceId, targetId: $targetId, relation: $relation) {
-            sourceId targetId relation createdAt
-          }
-        }`,
-        { sourceId: featureId, targetId: project.id, relation: 'part_of' },
-      )
+      await graphql(CREATE_EDGE, {
+        sourceId: featureId,
+        targetId: project.id,
+        relation: 'part_of',
+      })
       output(nodeData.createNode)
     } catch (error) {
       outputError(error)
@@ -63,14 +65,11 @@ featureCommand
       const project = requireProject()
       const data = await graphql<{
         descendants: Array<{ id: string; type: string; title: string }>
-      }>(
-        `query Descendants($nodeId: String!, $relation: String, $maxDepth: Int) {
-          descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
-            id type title status
-          }
-        }`,
-        { nodeId: project.id, relation: 'part_of', maxDepth: 1 },
-      )
+      }>(DESCENDANTS_BRIEF, {
+        nodeId: project.id,
+        relation: 'part_of',
+        maxDepth: 1,
+      })
       const features = data.descendants.filter((n) => n.type === 'feature')
       const match = features.find(
         (f) => f.id === nameOrId || f.title === nameOrId,
@@ -111,14 +110,7 @@ featureCommand
       const project = requireProject()
       const data = await graphql<{
         descendants: Array<{ id: string; type: string }>
-      }>(
-        `query Descendants($nodeId: String!, $relation: String, $maxDepth: Int) {
-          descendants(nodeId: $nodeId, relation: $relation, maxDepth: $maxDepth) {
-            id type title description status createdAt updatedAt
-          }
-        }`,
-        { nodeId: project.id, relation: 'part_of', maxDepth: 1 },
-      )
+      }>(DESCENDANTS, { nodeId: project.id, relation: 'part_of', maxDepth: 1 })
       const features = data.descendants.filter((n) => n.type === 'feature')
       output(features)
     } catch (error) {
@@ -158,11 +150,7 @@ featureCommand
       }
       if (opts.metadata != null) variables.metadata = opts.metadata
       const data = await graphql<{ updateNode: unknown }>(
-        `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
-          updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
-            id type title description status metadata createdAt updatedAt
-          }
-        }`,
+        UPDATE_NODE,
         variables,
       )
       output(data.updateNode)
@@ -183,12 +171,9 @@ featureCommand
           'No feature specified. Pass an ID or set an active feature.',
         )
       }
-      const data = await graphql<{ deleteNode: boolean }>(
-        `mutation DeleteNode($id: String!) {
-          deleteNode(id: $id)
-        }`,
-        { id: featureId },
-      )
+      const data = await graphql<{ deleteNode: boolean }>(DELETE_NODE, {
+        id: featureId,
+      })
       output({ deleted: data.deleteNode })
     } catch (error) {
       outputError(error)
@@ -207,14 +192,9 @@ featureCommand
           'No feature specified. Pass an ID or set an active feature.',
         )
       }
-      const data = await graphql<{ node: unknown }>(
-        `query GetNode($id: String!) {
-          node(id: $id) {
-            id type title description status metadata createdAt updatedAt
-          }
-        }`,
-        { id: featureId },
-      )
+      const data = await graphql<{ node: unknown }>(GET_NODE, {
+        id: featureId,
+      })
       output(data.node)
     } catch (error) {
       outputError(error)

package/src/commands/import.ts

@@ -9,6 +9,13 @@ import {
   parseManifest,
   readClientKey,
 } from '../util/manifest.ts'
+import {
+  IMPORT_CREATE,
+  IMPORT_EDGE,
+  IMPORT_EDGES,
+  IMPORT_EXISTING,
+  IMPORT_UPDATE,
+} from '../util/operations.ts'
 
 const NODE_TYPES = ['project', 'feature', 'task'] as const
 
@@ -53,12 +60,9 @@ function desiredEdges(manifest: Manifest): DesiredEdge[] {
 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 },
-    )
+    const data = await graphql<{ nodes: ServerNode[] }>(IMPORT_EXISTING, {
+      type,
+    })
     for (const node of data.nodes) {
       const key = readClientKey(node.metadata)
       if (key) idByKey.set(key, node.id)
@@ -78,9 +82,7 @@ async function loadExistingEdges(nodeIds: string[]): Promise<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 }
-        }`,
+        IMPORT_EDGES,
         { nodeId, relation },
       )
       for (const target of data.edges) {
@@ -91,25 +93,13 @@ async function loadExistingEdges(nodeIds: string[]): Promise<Set<string>> {
   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, {
+    await graphql<{ updateNode: { id: string } }>(IMPORT_UPDATE, {
       id: existingId,
       title: node.title,
       description: node.description ?? null,
@@ -118,7 +108,7 @@ async function upsertNode(
     })
     return existingId
   }
-  const data = await graphql<{ createNode: { id: string } }>(CREATE_NODE, {
+  const data = await graphql<{ createNode: { id: string } }>(IMPORT_CREATE, {
     type: node.type,
     title: node.title,
     description: node.description ?? null,
@@ -162,7 +152,7 @@ export const importCommand = new Command('import')
         const targetId = idByKey.get(edge.targetKey)
         if (!sourceId || !targetId) continue
         if (present.has(edgeKey(sourceId, targetId, edge.relation))) continue
-        await graphql(CREATE_EDGE, {
+        await graphql(IMPORT_EDGE, {
           sourceId,
           targetId,
           relation: edge.relation,

package/src/commands/init.ts

@@ -4,6 +4,7 @@ import { Command } from 'commander'
 import { graphql } from '../util/client.ts'
 import { loadConfig, saveConfig } from '../util/config.ts'
 import { output, outputError } from '../util/format.ts'
+import { CREATE_PROJECT } from '../util/operations.ts'
 
 export const initCommand = new Command('init')
   .description('Initialize Flowy for the current git repository')
@@ -30,11 +31,7 @@ export const initCommand = new Command('init')
       }
 
       const data = await graphql<{ createNode: { id: string; title: string } }>(
-        `mutation CreateProject($type: String!, $title: String!) {
-          createNode(type: $type, title: $title) {
-            id type title description status metadata createdAt updatedAt
-          }
-        }`,
+        CREATE_PROJECT,
         { type: 'project', title: repoName },
       )
 

package/src/commands/key.test.ts

@@ -7,7 +7,7 @@ let mockOutputError: ReturnType<typeof vi.fn>
 
 beforeEach(() => {
   mockLoadConfig = vi.fn(() => ({
-    mode: 'saas',
+    mode: 'remote',
     apiUrl: 'https://flowy-ai.fly.dev/graphql',
     apiKey: 'old-key',
     client: { name: '' },
@@ -26,6 +26,16 @@ beforeEach(() => {
       loadConfig: mockLoadConfig,
       saveConfig: mockSaveConfig,
       fingerprintKey: actual.fingerprintKey,
+      requireRemoteMode: (commandName: string) => {
+        const cfg = (mockLoadConfig as unknown as () => { mode: string })()
+        if (cfg.mode === 'local') {
+          const err = new Error(
+            `"flowy ${commandName}" is only available in remote mode. The active mode is local mode.`,
+          ) as Error & { code?: string }
+          err.code = 'LOCAL_MODE'
+          throw err
+        }
+      },
     }
   })
 
@@ -160,4 +170,29 @@ describe('key command', () => {
     expect(mockSaveConfig).not.toHaveBeenCalled()
     expect(mockOutput).not.toHaveBeenCalled()
   })
+
+  test('rotate errors cleanly in local mode without hitting the server', async () => {
+    mockLoadConfig.mockReturnValue({
+      mode: 'local',
+      apiUrl: 'http://localhost:4000/graphql',
+      apiKey: 'old-key',
+      client: { name: '' },
+      projects: {},
+    })
+    const mockGraphql = vi.fn()
+    vi.doMock('../util/client.ts', () => ({ graphql: mockGraphql }))
+
+    const { keyCommand } = await import('./key.ts')
+    await keyCommand.parseAsync(['rotate'], { from: 'user' })
+
+    expect(mockGraphql).not.toHaveBeenCalled()
+    expect(mockSaveConfig).not.toHaveBeenCalled()
+    expect(mockOutput).not.toHaveBeenCalled()
+    expect(mockOutputError).toHaveBeenCalledWith(
+      expect.objectContaining({
+        message: expect.stringMatching(/local mode/i),
+        code: 'LOCAL_MODE',
+      }),
+    )
+  })
 })

package/src/commands/key.ts

@@ -1,7 +1,13 @@
 import { Command } from 'commander'
 import { graphql } from '../util/client.ts'
-import { fingerprintKey, loadConfig, saveConfig } from '../util/config.ts'
+import {
+  fingerprintKey,
+  loadConfig,
+  requireRemoteMode,
+  saveConfig,
+} from '../util/config.ts'
 import { output, outputError } from '../util/format.ts'
+import { ROTATE_API_KEY } from '../util/operations.ts'
 
 export const keyCommand = new Command('key').description('API key management')
 
@@ -14,6 +20,7 @@ keyCommand
   )
   .action(async (opts) => {
     try {
+      requireRemoteMode('key rotate')
       const data = await graphql<{
         rotateApiKey: {
           user: {
@@ -25,14 +32,7 @@ keyCommand
           }
           apiKey: string
         }
-      }>(
-        `mutation RotateApiKey {
-          rotateApiKey {
-            user { id email tier createdAt graceEndsAt }
-            apiKey
-          }
-        }`,
-      )
+      }>(ROTATE_API_KEY)
 
       const { user, apiKey } = data.rotateApiKey
       const config = loadConfig()

package/src/commands/project.ts

@@ -3,6 +3,14 @@ import { graphql } from '../util/client.ts'
 import { loadConfig, requireProject, saveConfig } from '../util/config.ts'
 import { resolveDescription } from '../util/description.ts'
 import { output, outputError } from '../util/format.ts'
+import {
+  CREATE_PROJECT,
+  DELETE_NODE,
+  GET_PROJECT,
+  LIST_PROJECTS,
+  LIST_PROJECTS_FOR_SET,
+  UPDATE_NODE,
+} from '../util/operations.ts'
 
 export const projectCommand = new Command('project').description(
   'Manage projects',
@@ -14,14 +22,10 @@ projectCommand
   .argument('<name>', 'Project name')
   .action(async (name: string) => {
     try {
-      const data = await graphql<{ createNode: unknown }>(
-        `mutation CreateProject($type: String!, $title: String!) {
-          createNode(type: $type, title: $title) {
-            id type title description status metadata createdAt updatedAt
-          }
-        }`,
-        { type: 'project', title: name },
-      )
+      const data = await graphql<{ createNode: unknown }>(CREATE_PROJECT, {
+        type: 'project',
+        title: name,
+      })
       output(data.createNode)
     } catch (error) {
       outputError(error)
@@ -44,14 +48,7 @@ projectCommand
     try {
       const data = await graphql<{
         nodes: Array<{ id: string; title: string }>
-      }>(
-        `query ListProjects($type: String) {
-          nodes(type: $type) {
-            id title
-          }
-        }`,
-        { type: 'project' },
-      )
+      }>(LIST_PROJECTS_FOR_SET, { type: 'project' })
       const project = data.nodes.find((n) => n.title === name)
       if (!project) {
         throw new Error(`Project "${name}" not found.`)
@@ -67,14 +64,9 @@ projectCommand
   .description('List all projects')
   .action(async () => {
     try {
-      const data = await graphql<{ nodes: unknown[] }>(
-        `query ListProjects($type: String) {
-          nodes(type: $type) {
-            id type title description status createdAt updatedAt
-          }
-        }`,
-        { type: 'project' },
-      )
+      const data = await graphql<{ nodes: unknown[] }>(LIST_PROJECTS, {
+        type: 'project',
+      })
       output(data.nodes)
     } catch (error) {
       outputError(error)
@@ -84,14 +76,9 @@ projectCommand
 export async function showProject(id?: string): Promise<void> {
   try {
     const projectId = id ?? requireProject().id
-    const data = await graphql<{ node: unknown }>(
-      `query GetProject($id: String!) {
-        node(id: $id) {
-          id type title description status metadata createdAt updatedAt
-        }
-      }`,
-      { id: projectId },
-    )
+    const data = await graphql<{ node: unknown }>(GET_PROJECT, {
+      id: projectId,
+    })
     output(data.node)
   } catch (error) {
     outputError(error)
@@ -131,11 +118,7 @@ projectCommand
       }
       if (opts.metadata != null) variables.metadata = opts.metadata
       const data = await graphql<{ updateNode: unknown }>(
-        `mutation UpdateNode($id: String!, $title: String, $description: String, $metadata: String) {
-          updateNode(id: $id, title: $title, description: $description, metadata: $metadata) {
-            id type title description status metadata createdAt updatedAt
-          }
-        }`,
+        UPDATE_NODE,
         variables,
       )
       output(data.updateNode)
@@ -151,12 +134,9 @@ projectCommand
   .action(async (id?: string) => {
     try {
       const projectId = id ?? requireProject().id
-      const data = await graphql<{ deleteNode: boolean }>(
-        `mutation DeleteNode($id: String!) {
-          deleteNode(id: $id)
-        }`,
-        { id: projectId },
-      )
+      const data = await graphql<{ deleteNode: boolean }>(DELETE_NODE, {
+        id: projectId,
+      })
       output({ deleted: data.deleteNode })
     } catch (error) {
       outputError(error)

package/src/commands/search.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander'
 import { graphql } from '../util/client.ts'
 import { output, outputError } from '../util/format.ts'
+import { SEARCH } from '../util/operations.ts'
 
 export const searchCommand = new Command('search')
   .description('Search nodes by text')
@@ -10,19 +11,12 @@ export const searchCommand = new Command('search')
   .option('--limit <n>', 'Limit results', '50')
   .action(async (query: string, opts) => {
     try {
-      const data = await graphql<{ search: unknown[] }>(
-        `query Search($query: String!, $type: String, $status: String, $limit: Int) {
-          search(query: $query, type: $type, status: $status, limit: $limit) {
-            id type title description status
-          }
-        }`,
-        {
-          query,
-          type: opts.type,
-          status: opts.status,
-          limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
-        },
-      )
+      const data = await graphql<{ search: unknown[] }>(SEARCH, {
+        query,
+        type: opts.type,
+        status: opts.status,
+        limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+      })
       output(data.search)
     } catch (error) {
       outputError(error)

package/src/commands/setup.test.ts

@@ -8,7 +8,7 @@ let mockSpawnSync: ReturnType<typeof vi.fn>
 
 beforeEach(() => {
   mockLoadConfig = vi.fn(() => ({
-    mode: 'saas',
+    mode: 'remote',
     apiUrl: 'https://flowy-ai.fly.dev/graphql',
     apiKey: '',
     client: { name: '' },
@@ -315,6 +315,53 @@ describe('setup command', () => {
     errSpy.mockRestore()
   })
 
+  test('setup remote persists the API key before any later step (save-after-register)', 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_persisted',
+        checkoutUrl: null,
+      },
+    })
+    vi.doMock('../util/client.ts', () => ({ graphql: mockGraphql }))
+
+    // The skill install (a step AFTER the key is obtained) blows up hard.
+    // The key must already be on disk by then so the user is never stranded.
+    let keySavedBeforeSkillInstall = false
+    mockSaveConfig.mockImplementation((cfg: { apiKey?: string }) => {
+      if (cfg.apiKey === 'flowy_key_persisted')
+        keySavedBeforeSkillInstall = true
+    })
+    mockSpawnSync.mockImplementation((cmd: string) => {
+      if (cmd === 'npx') {
+        // By the time the (post-register) skill install runs, the key is saved.
+        expect(keySavedBeforeSkillInstall).toBe(true)
+        throw new Error('npx exploded')
+      }
+      return { status: 0, stdout: Buffer.from('') }
+    })
+    const errSpy = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+    const { setupCommand } = await import('./setup.ts')
+    await setupCommand.parseAsync(['remote', '--email', 'a@b.com'], {
+      from: 'user',
+    })
+
+    // The key was saved at least once with the real value before the failure.
+    expect(
+      mockSaveConfig.mock.calls.some(
+        (c) => (c[0] as { apiKey?: string }).apiKey === 'flowy_key_persisted',
+      ),
+    ).toBe(true)
+    errSpy.mockRestore()
+  })
+
   test('setup remote warns when the skill install fails', async () => {
     const mockGraphql = vi.fn().mockResolvedValue({
       register: {

package/src/commands/setup.ts

@@ -2,6 +2,7 @@ import { spawnSync } from 'node:child_process'
 import { Command, Option } from 'commander'
 import { fingerprintKey, loadConfig, saveConfig } from '../util/config.ts'
 import { output, outputError } from '../util/format.ts'
+import { REGISTER } from '../util/operations.ts'
 import { pinnedInstallSpec } from './serve.ts'
 
 export const setupCommand = new Command('setup').description(
@@ -104,16 +105,7 @@ setupCommand
           apiKey: string
           checkoutUrl: string
         }
-      }>(
-        `mutation Register($email: String!, $tier: String) {
-          register(email: $email, tier: $tier) {
-            user { id email tier createdAt graceEndsAt }
-            apiKey
-            checkoutUrl
-          }
-        }`,
-        { email: opts.email, tier: opts.tier },
-      )
+      }>(REGISTER, { email: opts.email, tier: opts.tier })
 
       config.apiKey = data.register.apiKey
       saveConfig(config)

package/src/commands/status.ts

@@ -1,6 +1,7 @@
 import { Command } from 'commander'
 import { graphql } from '../util/client.ts'
 import { output, outputError } from '../util/format.ts'
+import { UPDATE_STATUS } from '../util/operations.ts'
 
 export const statusCommand = new Command('status')
   .description('Update a node status (shorthand)')
@@ -11,14 +12,10 @@ export const statusCommand = new Command('status')
   )
   .action(async (id: string, status: string) => {
     try {
-      const data = await graphql<{ updateNode: unknown }>(
-        `mutation UpdateStatus($id: String!, $status: String) {
-          updateNode(id: $id, status: $status) {
-            id type title status updatedAt
-          }
-        }`,
-        { id, status },
-      )
+      const data = await graphql<{ updateNode: unknown }>(UPDATE_STATUS, {
+        id,
+        status,
+      })
       output(data.updateNode)
     } catch (error) {
       outputError(error)