@sqaoss/flowy 1.9.0 → 1.11.0

package/server/src/resolvers.ts

@@ -40,6 +40,36 @@ export interface NodeGql {
   updatedAt: string
 }
 
+/**
+ * An audit-log entry, shaped to match the SaaS `auditLog` GraphQL field
+ * (id, nodeId, action, field, oldValue, newValue, snapshot, changedBy,
+ * createdAt) so `flowy history` output is consistent across backends.
+ * `snapshot` is a JSON string (or null), mirroring SaaS.
+ */
+export interface AuditEntryGql {
+  id: string
+  nodeId: string | null
+  action: string
+  field: string | null
+  oldValue: string | null
+  newValue: string | null
+  snapshot: string | null
+  changedBy: string
+  createdAt: string
+}
+
+interface AuditRow {
+  id: string
+  node_id: string | null
+  action: string
+  field: string | null
+  old_value: string | null
+  new_value: string | null
+  snapshot: string | null
+  changed_by: string
+  created_at: string
+}
+
 /**
  * A node returned from a subtree traversal, annotated with the edge that pulled
  * it in: `parentId` (the node it descends from), `depth` (1 for the root's
@@ -51,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
@@ -84,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
@@ -105,6 +177,57 @@ function generateId(type: string): string {
   return `${prefix}_${nanoid(12)}`
 }
 
+// The bundled local server is single-tenant and unauthenticated, so every
+// audit entry is attributed to a single constant actor. SaaS uses the user id.
+const LOCAL_ACTOR = 'local'
+
+interface AuditInput {
+  nodeId: string | null
+  action: string
+  field?: string | null
+  oldValue?: string | null
+  newValue?: string | null
+  snapshot?: Record<string, unknown> | null
+}
+
+/**
+ * Write one audit_log row. Call inside the same transaction as the mutation so
+ * the change and its audit trail commit (or roll back) together. SQLite's
+ * `datetime('now')` resolves to whole seconds, which is too coarse to order
+ * multiple entries written in the same call; we pass an explicit ISO timestamp
+ * with sub-second precision so `ORDER BY created_at DESC` is stable.
+ */
+function insertAudit(db: Db, input: AuditInput): void {
+  db.raw.run(
+    'INSERT INTO audit_log (id, node_id, action, field, old_value, new_value, snapshot, changed_by, created_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)',
+    [
+      `audit_${nanoid(12)}`,
+      input.nodeId,
+      input.action,
+      input.field ?? null,
+      input.oldValue ?? null,
+      input.newValue ?? null,
+      input.snapshot != null ? JSON.stringify(input.snapshot) : null,
+      LOCAL_ACTOR,
+      new Date().toISOString(),
+    ],
+  )
+}
+
+function rowToAudit(row: AuditRow): AuditEntryGql {
+  return {
+    id: row.id,
+    nodeId: row.node_id,
+    action: row.action,
+    field: row.field,
+    oldValue: row.old_value,
+    newValue: row.new_value,
+    snapshot: row.snapshot,
+    changedBy: row.changed_by,
+    createdAt: row.created_at,
+  }
+}
+
 function rowToNode(row: NodeRow): NodeGql {
   return {
     id: row.id,
@@ -135,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 }) => {
@@ -305,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')
         }
@@ -322,13 +456,41 @@ 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 ${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
+      // `auditLog` field so `flowy history` output is consistent across
+      // backends. `delete` entries set node_id to null (the node is gone), so
+      // they are not returned here — the deletion is still recorded in the
+      // table with the pre-delete snapshot.
+      auditLog: (
+        _: unknown,
+        args: { nodeId: string; limit?: number },
+      ): AuditEntryGql[] => {
         const limit = args.limit ?? 50
         const rows = db.raw
           .query(
-            `SELECT ${NODE_COLS} FROM nodes WHERE ${conditions.join(' AND ')} LIMIT ?`,
+            'SELECT * FROM audit_log WHERE node_id = ? ORDER BY created_at DESC, rowid DESC LIMIT ?',
           )
-          .all(...params, limit) as NodeRow[]
-        return selectNodes(rows)
+          .all(args.nodeId, limit) as AuditRow[]
+        return rows.map(rowToAudit)
       },
     },
 
@@ -354,11 +516,7 @@ export function createResolvers(db: Db) {
         const now = new Date().toISOString()
         const description = args.description ?? null
         const status = args.status ?? 'draft'
-        db.raw.run(
-          'INSERT INTO nodes (id, type, title, description, status, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
-          [id, args.type, args.title, description, status, metadata, now, now],
-        )
-        return {
+        const node: NodeGql = {
           id,
           type: args.type,
           title: args.title,
@@ -368,6 +526,27 @@ export function createResolvers(db: Db) {
           createdAt: now,
           updatedAt: now,
         }
+        db.raw.transaction(() => {
+          db.raw.run(
+            'INSERT INTO nodes (id, type, title, description, status, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+            [
+              id,
+              args.type,
+              args.title,
+              description,
+              status,
+              metadata,
+              now,
+              now,
+            ],
+          )
+          insertAudit(db, {
+            nodeId: id,
+            action: 'create',
+            snapshot: node as unknown as Record<string, unknown>,
+          })
+        })()
+        return node
       },
 
       updateNode: (
@@ -391,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,
@@ -406,25 +590,77 @@ export function createResolvers(db: Db) {
               ? normalizeMetadata(args.metadata)
               : existing.metadata,
         }
+        // Field-level diffs, mirroring SaaS: title/description/metadata changes
+        // are 'update' entries; a status change is a 'status_change' entry.
+        const diffs: Array<{
+          field: string
+          action: string
+          oldValue: string | null
+          newValue: string | null
+        }> = []
+        if (next.title !== existing.title) {
+          diffs.push({
+            field: 'title',
+            action: 'update',
+            oldValue: existing.title,
+            newValue: next.title,
+          })
+        }
+        if (next.description !== existing.description) {
+          diffs.push({
+            field: 'description',
+            action: 'update',
+            oldValue: existing.description,
+            newValue: next.description,
+          })
+        }
+        if (next.status !== existing.status) {
+          diffs.push({
+            field: 'status',
+            action: 'status_change',
+            oldValue: existing.status,
+            newValue: next.status,
+          })
+        }
+        if (next.metadata !== existing.metadata) {
+          diffs.push({
+            field: 'metadata',
+            action: 'update',
+            oldValue: existing.metadata,
+            newValue: next.metadata,
+          })
+        }
+
         const now = new Date().toISOString()
-        db.raw.run(
-          'UPDATE nodes SET title = ?, description = ?, status = ?, metadata = ?, updated_at = ? WHERE id = ?',
-          [
-            next.title,
-            next.description,
-            next.status,
-            next.metadata,
-            now,
-            args.id,
-          ],
-        )
+        db.raw.transaction(() => {
+          db.raw.run(
+            'UPDATE nodes SET title = ?, description = ?, status = ?, metadata = ?, updated_at = ? WHERE id = ?',
+            [
+              next.title,
+              next.description,
+              next.status,
+              next.metadata,
+              now,
+              args.id,
+            ],
+          )
+          for (const d of diffs) {
+            insertAudit(db, {
+              nodeId: args.id,
+              action: d.action,
+              field: d.field,
+              oldValue: d.oldValue,
+              newValue: d.newValue,
+            })
+          }
+        })()
         return rowToNode({ ...next, updated_at: now })
       },
 
       deleteNode: (_: unknown, args: { id: string }): boolean => {
         const existing = db.raw
-          .query('SELECT id FROM nodes WHERE id = ?')
-          .get(args.id) as { id: string } | null
+          .query(`SELECT ${NODE_COLS} FROM nodes WHERE id = ?`)
+          .get(args.id) as NodeRow | null
         if (!existing) throw notFoundError(`Node ${args.id} not found`)
 
         // The hierarchy is client -> project -> feature -> task via `part_of`
@@ -442,6 +678,15 @@ export function createResolvers(db: Db) {
         }
 
         db.raw.transaction(() => {
+          // Record the delete with the pre-delete snapshot BEFORE removing the
+          // node. node_id is null (the node is gone) to match SaaS. The FK's
+          // ON DELETE SET NULL also nulls node_id on the node's prior audit
+          // rows when the node row below is deleted.
+          insertAudit(db, {
+            nodeId: null,
+            action: 'delete',
+            snapshot: rowToNode(existing) as unknown as Record<string, unknown>,
+          })
           db.raw.run('DELETE FROM edges WHERE source_id = ? OR target_id = ?', [
             args.id,
             args.id,
@@ -462,11 +707,19 @@ export function createResolvers(db: Db) {
           )
         }
         const now = new Date().toISOString()
-        db.raw.run('UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?', [
-          'approved',
-          now,
-          args.id,
-        ])
+        db.raw.transaction(() => {
+          db.raw.run(
+            'UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?',
+            ['approved', now, args.id],
+          )
+          insertAudit(db, {
+            nodeId: args.id,
+            action: 'approve',
+            field: 'status',
+            oldValue: 'pending_review',
+            newValue: 'approved',
+          })
+        })()
         return rowToNode({ ...existing, status: 'approved', updated_at: now })
       },
 
@@ -496,10 +749,20 @@ export function createResolvers(db: Db) {
           throw validationError('A node cannot block itself')
         }
         const now = new Date().toISOString()
-        db.raw.run(
-          'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
-          [args.sourceId, args.targetId, args.relation, now],
-        )
+        db.raw.transaction(() => {
+          db.raw.run(
+            'INSERT INTO edges (source_id, target_id, relation, created_at) VALUES (?, ?, ?, ?)',
+            [args.sourceId, args.targetId, args.relation, now],
+          )
+          // Record the edge against its source node so `auditLog(sourceId)`
+          // surfaces it. field = relation; newValue = the target it now links.
+          insertAudit(db, {
+            nodeId: args.sourceId,
+            action: 'create_edge',
+            field: args.relation,
+            newValue: args.targetId,
+          })
+        })()
         return {
           sourceId: args.sourceId,
           targetId: args.targetId,
@@ -512,11 +775,25 @@ export function createResolvers(db: Db) {
         _: unknown,
         args: { sourceId: string; targetId: string; relation: string },
       ) => {
-        const result = db.raw.run(
-          'DELETE FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?',
-          [args.sourceId, args.targetId, args.relation],
-        )
-        return result.changes > 0
+        let changed = false
+        db.raw.transaction(() => {
+          const result = db.raw.run(
+            'DELETE FROM edges WHERE source_id = ? AND target_id = ? AND relation = ?',
+            [args.sourceId, args.targetId, args.relation],
+          )
+          changed = result.changes > 0
+          // Only audit an edge that actually existed. oldValue = the target the
+          // edge linked to before removal.
+          if (changed) {
+            insertAudit(db, {
+              nodeId: args.sourceId,
+              action: 'remove_edge',
+              field: args.relation,
+              oldValue: args.targetId,
+            })
+          }
+        })()
+        return changed
       },
     },
   }

package/server/src/schema.ts

@@ -19,6 +19,21 @@ export const typeDefs = /* GraphQL */ `
     createdAt: String!
   }
 
+  # An audit-log entry. Shaped to match the SaaS \`auditLog\` field so
+  # \`flowy history\` output is consistent across backends. \`snapshot\` is a
+  # JSON-encoded string (or null).
+  type AuditEntry {
+    id: String!
+    nodeId: String
+    action: String!
+    field: String
+    oldValue: String
+    newValue: String
+    snapshot: String
+    changedBy: String!
+    createdAt: String!
+  }
+
   # A node returned from a subtree traversal, annotated with how it was reached:
   # the parent it descends from (parentId), how many edges down the root it sits
   # (depth, root's direct children are depth 1), and the relation of the edge
@@ -37,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!]!
@@ -44,7 +69,13 @@ 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!]!
   }
 
   type Mutation {

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

@@ -0,0 +1,99 @@
+import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest'
+
+describe('history command', () => {
+  test('exports a flat command with id argument and limit option', async () => {
+    const { historyCommand } = await import('./history.ts')
+    expect(historyCommand.name()).toBe('history')
+    expect(historyCommand.commands).toHaveLength(0)
+    const limitOpt = historyCommand.options.find((o) => o.long === '--limit')
+    expect(limitOpt).toBeDefined()
+  })
+
+  describe('action', () => {
+    beforeEach(() => {
+      vi.resetModules()
+    })
+
+    afterEach(() => {
+      vi.restoreAllMocks()
+      vi.unstubAllEnvs()
+    })
+
+    test('sends the AUDIT_LOG op with the node id and prints results', async () => {
+      const calls: Array<{ query: string; variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (query: string, variables: unknown) => {
+          calls.push({ query, variables })
+          return {
+            auditLog: [
+              {
+                id: 'audit_1',
+                action: 'create',
+                field: null,
+                oldValue: null,
+                newValue: null,
+                snapshot: '{"id":"task_1"}',
+                changedBy: 'local',
+                createdAt: '2026-06-13T00:00:00.000Z',
+              },
+            ],
+          }
+        }),
+      }))
+      const outputs: unknown[] = []
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn((data: unknown) => outputs.push(data)),
+        outputError: vi.fn(),
+      }))
+
+      const { AUDIT_LOG } = await import('../util/operations.ts')
+      const { historyCommand } = await import('./history.ts')
+      await historyCommand.parseAsync(['task_1'], { from: 'user' })
+
+      expect(calls).toHaveLength(1)
+      expect(calls[0]!.query).toBe(AUDIT_LOG)
+      expect(calls[0]!.variables).toMatchObject({ nodeId: 'task_1' })
+
+      const rendered = outputs[0] as Array<Record<string, unknown>>
+      expect(rendered[0]).toMatchObject({ id: 'audit_1', action: 'create' })
+    })
+
+    test('passes --limit through to the op', async () => {
+      const calls: Array<{ variables: unknown }> = []
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async (_query: string, variables: unknown) => {
+          calls.push({ variables })
+          return { auditLog: [] }
+        }),
+      }))
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn(),
+        outputError: vi.fn(),
+      }))
+
+      const { historyCommand } = await import('./history.ts')
+      await historyCommand.parseAsync(['task_1', '--limit', '5'], {
+        from: 'user',
+      })
+
+      expect(calls[0]!.variables).toMatchObject({ nodeId: 'task_1', limit: 5 })
+    })
+
+    test('reports errors via outputError', async () => {
+      vi.doMock('../util/client.ts', () => ({
+        graphql: vi.fn(async () => {
+          throw new Error('boom')
+        }),
+      }))
+      const errors: unknown[] = []
+      vi.doMock('../util/format.ts', () => ({
+        output: vi.fn(),
+        outputError: vi.fn((e: unknown) => errors.push(e)),
+      }))
+
+      const { historyCommand } = await import('./history.ts')
+      await historyCommand.parseAsync(['task_1'], { from: 'user' })
+      expect(errors).toHaveLength(1)
+    })
+  })
+})

package/src/commands/history.ts

@@ -0,0 +1,20 @@
+import { Command } from 'commander'
+import { graphql } from '../util/client.ts'
+import { output, outputError } from '../util/format.ts'
+import { AUDIT_LOG } from '../util/operations.ts'
+
+export const historyCommand = new Command('history')
+  .description('Show the audit history of a node (newest first)')
+  .argument('<id>', 'Node ID')
+  .option('--limit <n>', 'Limit results', '50')
+  .action(async (id: string, opts) => {
+    try {
+      const data = await graphql<{ auditLog: unknown[] }>(AUDIT_LOG, {
+        nodeId: id,
+        limit: opts.limit ? Number.parseInt(opts.limit, 10) : undefined,
+      })
+      output(data.auditLog)
+    } catch (error) {
+      outputError(error)
+    }
+  })