@sqaoss/flowy 1.10.0 → 1.11.0

package/README.md

@@ -147,6 +147,8 @@ flowy serve --port 5000 --host 0.0.0.0 --db ~/flowy.sqlite   # override defaults
 
 The self-hosted server supports the full planning workflow — `init`, `project`/`feature`/`task` CRUD, `status`, `approve`, `search`, `tree`, `task deps`, `task list --ready/--all`, and `import`/`export`. Account-only commands (`whoami`, `billing`, `key`) are remote-mode features and don't apply locally.
 
+The canonical status flow is `draft → pending_review → approved → in_progress → done`, plus `blocked` and `cancelled`. By default any status change is allowed (and the `status` command validates the value client-side). To make the local server *enforce* legal transitions — rejecting illegal jumps like `draft → done` with a `VALIDATION_ERROR` — start it with `FLOWY_ENFORCE_STATUS_LIFECYCLE=1`. Enforcement is opt-in and off by default.
+
 ## Command Reference
 
 | Command | Description |
@@ -179,7 +181,7 @@ The self-hosted server supports the full planning workflow — `init`, `project`
 | `task deps <id>` | Show what blocks a task and what it blocks |
 | `status <id> <status>` | Update status (shorthand) |
 | `approve <id>` | Approve (must be pending_review) |
-| `search <query> [--type] [--status] [--limit]` | Full-text search |
+| `search <query> [--type] [--status] [--limit]` | Full-text search; prints `{ nodes, truncated, total }` and warns on stderr when results are capped at `--limit` |
 | `tree <id> [--depth N]` | Show subtree from any entity |
 | `import <manifest>` | Ingest a JSON manifest of nodes + edges (idempotent by client-key) |
 | `export [output]` | Dump the active project as a manifest (stdout or file) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.10.0",
+  "version": "1.11.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -50,6 +50,7 @@
     "check": "biome check --write .",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
     "test:e2e": "vitest run --config vitest.config.e2e.ts",
     "sdl": "bun scripts/print-sdl.ts",
     "typecheck": "tsc --noEmit",
@@ -64,11 +65,12 @@
     "@commitlint/config-conventional": "^20.4.2",
     "@semantic-release/changelog": "6.0.3",
     "@semantic-release/git": "10.0.1",
+    "@vitest/coverage-v8": "4.1.8",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.0",
     "semantic-release": "25.0.3",
     "typescript": "^5",
-    "vitest": "^4.1.2"
+    "vitest": "4.1.8"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx}": [

package/server/src/contract.test.ts

@@ -360,11 +360,22 @@ describe('CLI/local-server contract (P1-1)', () => {
     })
     expect(Array.isArray(exportEdges.edges)).toBe(true)
 
-    const search = await ok<{ search: Array<{ id: string }> }>(
-      LOCAL_CONTRACT_OPERATIONS.SEARCH,
-      { query: 'Contract', type: 'project', status: null, limit: 50 },
-    )
-    expect(search.search.some((n) => n.id === project.id)).toBe(true)
+    // SEARCH returns a SearchResult envelope (F32): nodes + truncation meta.
+    const search = await ok<{
+      search: {
+        nodes: Array<{ id: string }>
+        truncated: boolean
+        total: number
+      }
+    }>(LOCAL_CONTRACT_OPERATIONS.SEARCH, {
+      query: 'Contract',
+      type: 'project',
+      status: null,
+      limit: 50,
+    })
+    expect(search.search.nodes.some((n) => n.id === project.id)).toBe(true)
+    expect(search.search.truncated).toBe(false)
+    expect(typeof search.search.total).toBe('number')
 
     // auditLog (P1-2/F27): the task has accumulated a trail — a `create` on
     // insert, a `status_change` to pending_review, an `approve`, plus the

package/server/src/index.errors.test.ts

@@ -29,9 +29,12 @@ describe('server error masking', () => {
   it('surfaces a too-short search error with real message and VALIDATION_ERROR code', async () => {
     instance = createServer({ dbPath: ':memory:', port: 0 })
 
-    const json = await gql('query ($q: String!) { search(query: $q) { id } }', {
-      q: 'ab',
-    })
+    const json = await gql(
+      'query ($q: String!) { search(query: $q) { nodes { id } } }',
+      {
+        q: 'ab',
+      },
+    )
 
     expect(json.errors).toBeDefined()
     const error = json.errors![0]

package/server/src/index.ts

@@ -7,15 +7,24 @@ export function createServer(opts?: {
   dbPath?: string
   port?: number
   hostname?: string
+  enforceStatusLifecycle?: boolean
 }) {
   const dbPath = opts?.dbPath ?? process.env.FLOWY_DB_PATH ?? './flowy.sqlite'
   const port = opts?.port ?? Number(process.env.PORT ?? 4000)
   // Bind loopback by default so the unauthenticated dev server is not exposed
   // on the LAN. Override with the `hostname` opt or the HOST env var.
   const hostname = opts?.hostname ?? process.env.HOST ?? '127.0.0.1'
+  // Status-lifecycle enforcement is OPT-IN (F32). Off unless explicitly enabled
+  // via the `enforceStatusLifecycle` opt or FLOWY_ENFORCE_STATUS_LIFECYCLE=1
+  // (also accepts "true"). When off, any vocabulary-valid status is accepted.
+  const enforceStatusLifecycle =
+    opts?.enforceStatusLifecycle ??
+    ['1', 'true'].includes(
+      (process.env.FLOWY_ENFORCE_STATUS_LIFECYCLE ?? '').toLowerCase(),
+    )
 
   const db = createDb(dbPath)
-  const resolvers = createResolvers(db)
+  const resolvers = createResolvers(db, { enforceStatusLifecycle })
 
   const yoga = createYoga({
     schema: createSchema({ typeDefs, resolvers }),

package/server/src/resolvers.test.ts

@@ -773,8 +773,10 @@ describe('createResolvers', () => {
       })
 
       const results = resolvers.Query.search(null, { query: 'Auth' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('Authentication')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('Authentication')
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(1)
     })
 
     it('finds nodes by description', () => {
@@ -785,8 +787,8 @@ describe('createResolvers', () => {
       })
 
       const results = resolvers.Query.search(null, { query: 'OAuth' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('Login')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('Login')
     })
 
     it('filters by type', () => {
@@ -803,8 +805,8 @@ describe('createResolvers', () => {
         query: 'Auth',
         type: 'project',
       })
-      expect(results).toHaveLength(1)
-      expect(results[0].type).toBe('project')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].type).toBe('project')
     })
 
     it('filters by status', () => {
@@ -825,8 +827,8 @@ describe('createResolvers', () => {
         query: 'Auth',
         status: 'in_progress',
       })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('Auth')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('Auth')
     })
 
     it('respects limit', () => {
@@ -841,7 +843,58 @@ describe('createResolvers', () => {
         query: 'Task',
         limit: 2,
       })
-      expect(results).toHaveLength(2)
+      expect(results.nodes).toHaveLength(2)
+    })
+
+    it('signals truncation when results are capped at the limit', () => {
+      for (let i = 0; i < 5; i++) {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: `Task ${i}`,
+        })
+      }
+
+      const results = resolvers.Query.search(null, {
+        query: 'Task',
+        limit: 2,
+      })
+      expect(results.nodes).toHaveLength(2)
+      expect(results.truncated).toBe(true)
+      expect(results.total).toBe(5)
+    })
+
+    it('does not signal truncation when all results fit under the limit', () => {
+      for (let i = 0; i < 3; i++) {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: `Task ${i}`,
+        })
+      }
+
+      const results = resolvers.Query.search(null, {
+        query: 'Task',
+        limit: 50,
+      })
+      expect(results.nodes).toHaveLength(3)
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(3)
+    })
+
+    it('does not signal truncation when results exactly equal the limit', () => {
+      for (let i = 0; i < 2; i++) {
+        resolvers.Mutation.createNode(null, {
+          type: 'task',
+          title: `Task ${i}`,
+        })
+      }
+
+      const results = resolvers.Query.search(null, {
+        query: 'Task',
+        limit: 2,
+      })
+      expect(results.nodes).toHaveLength(2)
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(2)
     })
   })
 
@@ -958,7 +1011,9 @@ describe('createResolvers', () => {
       const results = resolvers.Query.search(null, {
         query: 'zzz_no_match',
       })
-      expect(results).toEqual([])
+      expect(results.nodes).toEqual([])
+      expect(results.truncated).toBe(false)
+      expect(results.total).toBe(0)
     })
 
     it('throws when query is shorter than 3 characters', () => {
@@ -976,23 +1031,23 @@ describe('createResolvers', () => {
     it('succeeds with 3-character query', () => {
       create(resolvers, { type: 'project', title: 'abc match' })
       const results = resolvers.Query.search(null, { query: 'abc' })
-      expect(results).toHaveLength(1)
+      expect(results.nodes).toHaveLength(1)
     })
 
     it('does not treat % as LIKE wildcard', () => {
       create(resolvers, { type: 'project', title: '100% done' })
       create(resolvers, { type: 'project', title: '100 things' })
       const results = resolvers.Query.search(null, { query: '100%' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('100% done')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('100% done')
     })
 
     it('does not treat _ as LIKE wildcard', () => {
       create(resolvers, { type: 'project', title: '_est something' })
       create(resolvers, { type: 'project', title: 'Test something' })
       const results = resolvers.Query.search(null, { query: '_est' })
-      expect(results).toHaveLength(1)
-      expect(results[0].title).toBe('_est something')
+      expect(results.nodes).toHaveLength(1)
+      expect(results.nodes[0].title).toBe('_est something')
     })
   })
 
@@ -1071,6 +1126,150 @@ describe('createResolvers', () => {
     })
   })
 
+  describe('status lifecycle enforcement (opt-in)', () => {
+    let strict: ReturnType<typeof createResolvers>
+
+    beforeEach(() => {
+      strict = createResolvers(db, { enforceStatusLifecycle: true })
+    })
+
+    function strictCreate(title: string): NodeGql {
+      return strict.Mutation.createNode(null, { type: 'task', title })
+    }
+
+    it('allows the canonical forward flow draft -> ... -> done', () => {
+      const node = strictCreate('Flow')
+      expect(node.status).toBe('draft')
+      let cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      expect(cur.status).toBe('pending_review')
+      cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'approved',
+      })
+      expect(cur.status).toBe('approved')
+      cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'in_progress',
+      })
+      expect(cur.status).toBe('in_progress')
+      cur = strict.Mutation.updateNode(null, { id: node.id, status: 'done' })
+      expect(cur.status).toBe('done')
+    })
+
+    it('rejects an illegal skip (draft -> done) with VALIDATION_ERROR', () => {
+      const node = strictCreate('Skip')
+      expect(() =>
+        strict.Mutation.updateNode(null, { id: node.id, status: 'done' }),
+      ).toThrow(/transition/i)
+      try {
+        strict.Mutation.updateNode(null, { id: node.id, status: 'done' })
+      } catch (e) {
+        expect((e as { extensions?: { code?: string } }).extensions?.code).toBe(
+          'VALIDATION_ERROR',
+        )
+      }
+    })
+
+    it('rejects skipping pending_review -> in_progress', () => {
+      const node = strictCreate('Skip2')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      expect(() =>
+        strict.Mutation.updateNode(null, {
+          id: node.id,
+          status: 'in_progress',
+        }),
+      ).toThrow(/transition/i)
+    })
+
+    it('allows cancelling from an active state', () => {
+      const node = strictCreate('Cancel')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      const cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'cancelled',
+      })
+      expect(cur.status).toBe('cancelled')
+    })
+
+    it('allows blocking from in_progress and resuming', () => {
+      const node = strictCreate('Block')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'approved' })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'in_progress' })
+      let cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'blocked',
+      })
+      expect(cur.status).toBe('blocked')
+      cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'in_progress',
+      })
+      expect(cur.status).toBe('in_progress')
+    })
+
+    it('rejects blocking directly from draft', () => {
+      const node = strictCreate('BlockEarly')
+      expect(() =>
+        strict.Mutation.updateNode(null, { id: node.id, status: 'blocked' }),
+      ).toThrow(/transition/i)
+    })
+
+    it('allows reopening done -> in_progress', () => {
+      const node = strictCreate('Reopen')
+      strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'pending_review',
+      })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'approved' })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'in_progress' })
+      strict.Mutation.updateNode(null, { id: node.id, status: 'done' })
+      const cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'in_progress',
+      })
+      expect(cur.status).toBe('in_progress')
+    })
+
+    it('allows a same-status no-op even under enforcement', () => {
+      const node = strictCreate('NoOp')
+      const cur = strict.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'draft',
+      })
+      expect(cur.status).toBe('draft')
+    })
+
+    it('still validates the status vocabulary', () => {
+      const node = strictCreate('Vocab')
+      expect(() =>
+        strict.Mutation.updateNode(null, { id: node.id, status: 'bogus' }),
+      ).toThrow(/Invalid status/)
+    })
+
+    it('does NOT enforce transitions when the flag is off (default)', () => {
+      // default `resolvers` (no enforcement) permits the illegal skip
+      const node = create(resolvers, { type: 'task', title: 'Default' })
+      const updated = resolvers.Mutation.updateNode(null, {
+        id: node.id,
+        status: 'done',
+      })
+      expect(updated.status).toBe('done')
+    })
+  })
+
   describe('Query.descendants — edge cases', () => {
     it('returns empty array for leaf node', () => {
       const leaf = create(resolvers, { type: 'task', title: 'Leaf' })
@@ -1216,7 +1415,7 @@ describe('createResolvers', () => {
         query: 'Test',
         limit: 0,
       })
-      expect(results).toEqual([])
+      expect(results.nodes).toEqual([])
     })
   })
 

package/server/src/resolvers.ts

@@ -81,6 +81,18 @@ export interface SubtreeNodeGql extends NodeGql {
   relation: string
 }
 
+/**
+ * Search results plus truncation metadata (F32). `nodes` is capped at `limit`;
+ * `total` is the unbounded match count and `truncated` is true when `total`
+ * exceeds the returned page — letting the CLI show a clear "results truncated"
+ * marker instead of silently dropping matches at the default cap.
+ */
+export interface SearchResultGql {
+  nodes: NodeGql[]
+  truncated: boolean
+  total: number
+}
+
 interface SubtreeRow extends NodeRow {
   parent_id: string
   depth: number
@@ -114,6 +126,36 @@ function assertValidStatus(status: string): void {
   }
 }
 
+/**
+ * Allowed status transitions for the OPT-IN lifecycle enforcement
+ * (`FLOWY_ENFORCE_STATUS_LIFECYCLE`). The canonical forward flow is
+ * `draft → pending_review → approved → in_progress → done`; `blocked` and
+ * `cancelled` are reachable from active states and recoverable back into the
+ * flow. A same-status update is always a no-op and never checked here. When
+ * enforcement is OFF (the default) this map is unused and any vocabulary-valid
+ * status is accepted, preserving the prior behaviour.
+ */
+const ALLOWED_TRANSITIONS: Record<string, Set<string>> = {
+  draft: new Set(['pending_review', 'cancelled']),
+  pending_review: new Set(['approved', 'draft', 'cancelled']),
+  approved: new Set(['in_progress', 'pending_review', 'cancelled']),
+  in_progress: new Set(['done', 'blocked', 'cancelled']),
+  done: new Set(['in_progress']),
+  blocked: new Set(['in_progress', 'cancelled']),
+  cancelled: new Set(['draft']),
+}
+
+function assertValidTransition(from: string, to: string): void {
+  if (from === to) return
+  if (!ALLOWED_TRANSITIONS[from]?.has(to)) {
+    throw validationError(
+      `Illegal status transition: ${from} → ${to}. Allowed from "${from}": ${
+        [...(ALLOWED_TRANSITIONS[from] ?? [])].join(', ') || '(none)'
+      }`,
+    )
+  }
+}
+
 /**
  * Validate that `metadata` is a JSON string and return its canonical form.
  * Metadata is stored as a JSON string (the column and the GraphQL field are
@@ -216,7 +258,18 @@ function prefixedCols() {
     .join(', ')
 }
 
-export function createResolvers(db: Db) {
+export interface ResolverOptions {
+  /**
+   * Enforce the canonical status lifecycle on `updateNode` status changes.
+   * OFF by default — when false (the default) any vocabulary-valid status is
+   * accepted, matching pre-F32 behaviour. Wired from
+   * `FLOWY_ENFORCE_STATUS_LIFECYCLE` in `index.ts`.
+   */
+  enforceStatusLifecycle?: boolean
+}
+
+export function createResolvers(db: Db, opts: ResolverOptions = {}) {
+  const enforceStatusLifecycle = opts.enforceStatusLifecycle ?? false
   return {
     Query: {
       node: (_: unknown, args: { id: string }) => {
@@ -386,7 +439,7 @@ export function createResolvers(db: Db) {
           status?: string
           limit?: number
         },
-      ) => {
+      ): SearchResultGql => {
         if (args.query.trim().length < 3) {
           throw validationError('Search query must be at least 3 characters')
         }
@@ -403,13 +456,23 @@ export function createResolvers(db: Db) {
           conditions.push('status = ?')
           params.push(args.status)
         }
+        const where = conditions.join(' AND ')
         const limit = args.limit ?? 50
+        // Fetch one extra row so we can tell "exactly at the cap" from
+        // "more matches exist" without a second COUNT for the common case.
         const rows = db.raw
-          .query(
-            `SELECT ${NODE_COLS} FROM nodes WHERE ${conditions.join(' AND ')} LIMIT ?`,
-          )
-          .all(...params, limit) as NodeRow[]
-        return selectNodes(rows)
+          .query(`SELECT ${NODE_COLS} FROM nodes WHERE ${where} LIMIT ?`)
+          .all(...params, limit + 1) as NodeRow[]
+        const truncated = rows.length > limit
+        const page = truncated ? rows.slice(0, limit) : rows
+        const total = truncated
+          ? (
+              db.raw
+                .query(`SELECT COUNT(*) AS c FROM nodes WHERE ${where}`)
+                .get(...params) as { c: number }
+            ).c
+          : page.length
+        return { nodes: selectNodes(page), truncated, total }
       },
 
       // Audit history for a node, newest first. Shaped to match the SaaS
@@ -507,7 +570,12 @@ export function createResolvers(db: Db) {
         if (args.description != null && !args.description.trim()) {
           throw validationError('Description cannot be empty')
         }
-        if (args.status != null) assertValidStatus(args.status)
+        if (args.status != null) {
+          assertValidStatus(args.status)
+          if (enforceStatusLifecycle) {
+            assertValidTransition(existing.status, args.status)
+          }
+        }
 
         const next: NodeRow = {
           ...existing,

package/server/src/schema.ts

@@ -52,6 +52,16 @@ export const typeDefs = /* GraphQL */ `
     relation: String!
   }
 
+  # Search results plus truncation metadata (F32). \`nodes\` is the page capped
+  # at the requested \`limit\`; \`total\` is the unbounded match count and
+  # \`truncated\` is true when more matches exist than were returned, so the CLI
+  # can surface a "results truncated" marker instead of silently dropping rows.
+  type SearchResult {
+    nodes: [Node!]!
+    truncated: Boolean!
+    total: Int!
+  }
+
   type Query {
     node(id: String!): Node
     nodes(type: String): [Node!]!
@@ -59,7 +69,12 @@ export const typeDefs = /* GraphQL */ `
     subtree(nodeId: String!, relation: String, maxDepth: Int): [SubtreeNode!]!
     edges(nodeId: String!, relation: String!, direction: String): [Node!]!
     readyTasks(projectId: String): [Node!]!
-    search(query: String!, type: String, status: String, limit: Int): [Node!]!
+    search(
+      query: String!
+      type: String
+      status: String
+      limit: Int
+    ): SearchResult!
     auditLog(nodeId: String!, limit: Int): [AuditEntry!]!
   }
 

package/skills/using-flowy/SKILL.md

@@ -154,6 +154,9 @@ flowy status <id> done
 flowy search "query" --type task --status draft --limit 10
 flowy tree <id> --depth 3                    # show subtree from any entity
 ```
+`search` prints `{ nodes, truncated, total }`. When `truncated` is `true` the
+results were capped at `--limit` (default 50) and `total` more matches exist —
+raise `--limit` to see them.
 
 ### Import and Export
 ```bash

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/util/operations.ts

@@ -116,10 +116,18 @@ 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
   }
 }`