@sqaoss/flowy 1.9.0 → 1.11.0

package/src/commands/search.test.ts

@@ -0,0 +1,90 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockGraphql: ReturnType<typeof vi.fn>
+let mockOutput: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+let stderr: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  mockOutput = vi.fn()
+  mockOutputError = vi.fn()
+  mockGraphql = vi.fn()
+  stderr = vi.spyOn(console, 'error').mockImplementation(() => {})
+
+  vi.doMock('../util/format.ts', () => ({
+    output: mockOutput,
+    outputError: mockOutputError,
+  }))
+  vi.doMock('../util/client.ts', () => ({
+    graphql: mockGraphql,
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('search command', () => {
+  test('sends the SearchResult envelope query and outputs nodes + meta', async () => {
+    mockGraphql.mockResolvedValue({
+      search: {
+        nodes: [{ id: 'proj_1', title: 'Auth' }],
+        truncated: false,
+        total: 1,
+      },
+    })
+
+    const { searchCommand } = await import('./search.ts')
+    await searchCommand.parseAsync(['Auth'], { from: 'user' })
+
+    const query = mockGraphql.mock.calls[0]?.[0] as string
+    expect(query).toContain('nodes')
+    expect(query).toContain('truncated')
+    expect(query).toContain('total')
+
+    expect(mockOutput).toHaveBeenCalledWith({
+      nodes: [{ id: 'proj_1', title: 'Auth' }],
+      truncated: false,
+      total: 1,
+    })
+    // no truncation warning when not truncated
+    expect(stderr).not.toHaveBeenCalled()
+  })
+
+  test('renders a clear truncation marker when results are capped', async () => {
+    mockGraphql.mockResolvedValue({
+      search: {
+        nodes: new Array(50).fill({ id: 'x' }),
+        truncated: true,
+        total: 137,
+      },
+    })
+
+    const { searchCommand } = await import('./search.ts')
+    await searchCommand.parseAsync(['Task'], { from: 'user' })
+
+    const outputArg = mockOutput.mock.calls[0]?.[0] as {
+      truncated: boolean
+      total: number
+    }
+    expect(outputArg.truncated).toBe(true)
+    expect(outputArg.total).toBe(137)
+
+    expect(stderr).toHaveBeenCalledOnce()
+    const warning = stderr.mock.calls[0]?.[0] as string
+    expect(warning).toMatch(/truncated/i)
+    expect(warning).toContain('50')
+    expect(warning).toContain('137')
+  })
+
+  test('outputs error when the query fails', async () => {
+    mockGraphql.mockRejectedValue(new Error('boom'))
+    const { searchCommand } = await import('./search.ts')
+    await searchCommand.parseAsync(['Auth'], { from: 'user' })
+    expect(mockOutputError).toHaveBeenCalledWith(
+      expect.objectContaining({ message: 'boom' }),
+    )
+    expect(mockOutput).not.toHaveBeenCalled()
+  })
+})

package/src/commands/search.ts

@@ -3,6 +3,12 @@ import { graphql } from '../util/client.ts'
 import { output, outputError } from '../util/format.ts'
 import { SEARCH } from '../util/operations.ts'
 
+interface SearchResult {
+  nodes: unknown[]
+  truncated: boolean
+  total: number
+}
+
 export const searchCommand = new Command('search')
   .description('Search nodes by text')
   .argument('<query>', 'Search query')
@@ -11,13 +17,23 @@ export const searchCommand = new Command('search')
   .option('--limit <n>', 'Limit results', '50')
   .action(async (query: string, opts) => {
     try {
-      const data = await graphql<{ search: unknown[] }>(SEARCH, {
+      const limit = opts.limit ? Number.parseInt(opts.limit, 10) : undefined
+      const data = await graphql<{ search: SearchResult }>(SEARCH, {
         query,
         type: opts.type,
         status: opts.status,
-        limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+        limit,
       })
-      output(data.search)
+      const { nodes, truncated, total } = data.search
+      // The truncation marker rides in the JSON envelope so callers can detect
+      // it programmatically; when capped we also warn on stderr so it is not
+      // silently lost in a human-read terminal.
+      output({ nodes, truncated, total })
+      if (truncated) {
+        console.error(
+          `Results truncated: showing ${nodes.length} of ${total} matches. Raise --limit to see more.`,
+        )
+      }
     } catch (error) {
       outputError(error)
     }

package/src/commands/status.test.ts

@@ -0,0 +1,71 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+let mockGraphql: ReturnType<typeof vi.fn>
+let mockOutput: ReturnType<typeof vi.fn>
+let mockOutputError: ReturnType<typeof vi.fn>
+
+beforeEach(() => {
+  mockOutput = vi.fn()
+  mockOutputError = vi.fn()
+  mockGraphql = vi.fn().mockResolvedValue({
+    updateNode: { id: 'task_1', type: 'task', title: 'T', status: 'done' },
+  })
+
+  vi.doMock('../util/format.ts', () => ({
+    output: mockOutput,
+    outputError: mockOutputError,
+  }))
+  vi.doMock('../util/client.ts', () => ({
+    graphql: mockGraphql,
+  }))
+})
+
+afterEach(() => {
+  vi.resetModules()
+  vi.restoreAllMocks()
+})
+
+describe('status command', () => {
+  test('accepts a valid status and sends the update', async () => {
+    const { statusCommand } = await import('./status.ts')
+    await statusCommand.parseAsync(['task_1', 'in_progress'], { from: 'user' })
+
+    expect(mockGraphql).toHaveBeenCalledOnce()
+    expect(mockGraphql.mock.calls[0]?.[1]).toEqual({
+      id: 'task_1',
+      status: 'in_progress',
+    })
+    expect(mockOutput).toHaveBeenCalledOnce()
+  })
+
+  test('rejects an invalid status client-side (.choices) without a request', async () => {
+    const { statusCommand } = await import('./status.ts')
+    // Commander throws on an invalid choice; configure it not to exit the
+    // process so the test can assert.
+    statusCommand.exitOverride()
+    statusCommand.configureOutput({ writeErr: () => {}, writeOut: () => {} })
+
+    await expect(
+      statusCommand.parseAsync(['task_1', 'bogus'], { from: 'user' }),
+    ).rejects.toThrow(/Allowed choices|bogus/i)
+
+    expect(mockGraphql).not.toHaveBeenCalled()
+  })
+
+  test('exposes the full canonical status vocabulary as choices', async () => {
+    const { statusCommand, STATUS_CHOICES } = await import('./status.ts')
+    expect(STATUS_CHOICES).toEqual([
+      'draft',
+      'pending_review',
+      'approved',
+      'in_progress',
+      'done',
+      'blocked',
+      'cancelled',
+    ])
+    const statusArg = statusCommand.registeredArguments.find(
+      (a) => a.name() === 'status',
+    )
+    expect(statusArg?.argChoices).toEqual([...STATUS_CHOICES])
+  })
+})

package/src/commands/status.ts

@@ -1,14 +1,28 @@
-import { Command } from 'commander'
+import { Argument, Command } from 'commander'
 import { graphql } from '../util/client.ts'
 import { output, outputError } from '../util/format.ts'
 import { UPDATE_STATUS } from '../util/operations.ts'
 
+/**
+ * The canonical Flowy status vocabulary, mirrored from the server's
+ * VALID_STATUSES. Used for client-side `.choices()` validation so an invalid
+ * status is rejected before a request is ever sent.
+ */
+export const STATUS_CHOICES = [
+  'draft',
+  'pending_review',
+  'approved',
+  'in_progress',
+  'done',
+  'blocked',
+  'cancelled',
+] as const
+
 export const statusCommand = new Command('status')
   .description('Update a node status (shorthand)')
   .argument('<id>', 'Node ID')
-  .argument(
-    '<status>',
-    'New status (draft, pending_review, approved, in_progress, done, blocked, cancelled)',
+  .addArgument(
+    new Argument('<status>', 'New status').choices([...STATUS_CHOICES]),
   )
   .action(async (id: string, status: string) => {
     try {

package/src/index.test.ts

@@ -30,6 +30,9 @@ vi.mock('./commands/task.ts', () => ({
 vi.mock('./commands/tree.ts', () => ({
   treeCommand: { name: () => 'tree' },
 }))
+vi.mock('./commands/history.ts', () => ({
+  historyCommand: { name: () => 'history' },
+}))
 vi.mock('./commands/whoami.ts', () => ({
   whoamiCommand: { name: () => 'whoami' },
 }))
@@ -96,4 +99,17 @@ describe('index.ts command registration', () => {
     expect(indexSource).toContain('program.addCommand(importCommand)')
     expect(indexSource).toContain('program.addCommand(exportCommand)')
   })
+
+  test('registers the history command', async () => {
+    const { readFileSync } = await import('node:fs')
+    const indexSource = readFileSync(
+      new URL('./index.ts', import.meta.url).pathname,
+      'utf-8',
+    )
+
+    expect(indexSource).toContain(
+      "import { historyCommand } from './commands/history.ts'",
+    )
+    expect(indexSource).toContain('program.addCommand(historyCommand)')
+  })
 })

package/src/index.ts

@@ -16,6 +16,7 @@ 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 { historyCommand } from './commands/history.ts'
 import { importCommand } from './commands/import.ts'
 import { initCommand } from './commands/init.ts'
 import { keyCommand } from './commands/key.ts'
@@ -46,6 +47,7 @@ program.addCommand(billingCommand)
 program.addCommand(keyCommand)
 program.addCommand(searchCommand)
 program.addCommand(treeCommand)
+program.addCommand(historyCommand)
 program.addCommand(whoamiCommand)
 program.addCommand(importCommand)
 program.addCommand(exportCommand)

package/src/util/operations.test.ts

@@ -81,6 +81,7 @@ describe('commands send canonical operations (no re-inlined queries)', () => {
     'approve.ts': ['APPROVE_NODE'],
     'search.ts': ['SEARCH'],
     'tree.ts': ['SUBTREE'],
+    'history.ts': ['AUDIT_LOG'],
     'whoami.ts': ['WHOAMI'],
     'billing.ts': ['CREATE_CHECKOUT'],
     'key.ts': ['ROTATE_API_KEY'],

package/src/util/operations.ts

@@ -15,7 +15,9 @@
  * field, or an argument the CLI uses, the contract test fails — catching drift
  * before it ships. See `server/src/contract.test.ts` for the documented list
  * of intentional local/SaaS divergences (SaaS-only `whoami`, `register`,
- * `rotateApiKey`, `createCheckout`, `auditLog`, `ancestors`).
+ * `rotateApiKey`, `createCheckout`). `auditLog` was a SaaS-only divergence
+ * until P1-2/F27 ported it to the bundled local server; it is now part of the
+ * shared LOCAL_CONTRACT_OPERATIONS set.
  */
 
 // --- Nodes: read --------------------------------------------------------------
@@ -114,10 +116,30 @@ export const TASK_DEPS = `query TaskDeps($id: String!) {
   }
 }`
 
-/** search.ts — full-text search with optional type/status/limit filters. */
+/**
+ * search.ts — full-text search with optional type/status/limit filters.
+ * Returns a SearchResult envelope (F32): `nodes` is the page capped at `limit`,
+ * `truncated` flags that more matches exist than were returned, and `total` is
+ * the unbounded match count — so the CLI can show a truncation marker instead
+ * of silently dropping rows at the default cap.
+ */
 export const SEARCH = `query Search($query: String!, $type: String, $status: String, $limit: Int) {
   search(query: $query, type: $type, status: $status, limit: $limit) {
-    id type title description status
+    nodes { id type title description status }
+    truncated
+    total
+  }
+}`
+
+/**
+ * history.ts — audit history for a node, newest first. Served by BOTH backends:
+ * the SaaS server (always) and, since P1-2/F27, the bundled local server. The
+ * selection set mirrors the SaaS `auditLog` query (flowy-saas
+ * `test/helpers/cli-queries.ts`) so output is identical across backends.
+ */
+export const AUDIT_LOG = `query AuditLog($nodeId: String!, $limit: Int) {
+  auditLog(nodeId: $nodeId, limit: $limit) {
+    id action field oldValue newValue snapshot changedBy createdAt
   }
 }`
 
@@ -318,6 +340,7 @@ export const LOCAL_CONTRACT_OPERATIONS = {
   EXPORT_PROJECT,
   EXPORT_DESCENDANTS,
   EXPORT_EDGES,
+  AUDIT_LOG,
 } as const
 
 /**