@sqaoss/flowy 1.9.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.9.0",
+  "version": "1.11.0",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -50,6 +50,8 @@
     "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",
     "prepare": "husky"
@@ -63,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

@@ -31,9 +31,11 @@
  *   - `rotateApiKey`    (key.ts)    — API key lifecycle; local has no keys.
  *   - `createCheckout`  (billing.ts)— Polar checkout; local has no billing.
  *
- * Conversely, the SaaS schema carries operations the local server lacks and the
- * CLI does not yet call against local: `auditLog`/`getAuditLog` (P1-2 will port
- * this to local), `ancestors`, and `nodes(status/limit/offset)` pagination.
+ * Conversely, the SaaS schema carries some operations the local server still
+ * lacks and the CLI does not yet call against local: `ancestors` and
+ * `nodes(status/limit/offset)` pagination. (`auditLog` was such a divergence
+ * until P1-2/F27 ported it to the bundled local server; it is now part of
+ * LOCAL_CONTRACT_OPERATIONS and exercised below.)
  * Status vocabulary and edge relations are shared (`part_of`, `blocks`); the
  * SaaS schema additionally recognises `epic`/`depends_on`/`informs` relations
  * the bundled server does not. The test below asserts the local server rejects
@@ -358,11 +360,54 @@ 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 },
+    // 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
+    // content `update`s. Entries come back newest-first and carry the
+    // SaaS-shaped fields.
+    const history = await ok<{
+      auditLog: Array<{
+        id: string
+        action: string
+        field: string | null
+        oldValue: string | null
+        newValue: string | null
+        snapshot: string | null
+        changedBy: string
+        createdAt: string
+      }>
+    }>(LOCAL_CONTRACT_OPERATIONS.AUDIT_LOG, { nodeId: task.id, limit: 50 })
+    const actions = history.auditLog.map((e) => e.action)
+    expect(actions).toContain('create')
+    expect(actions).toContain('status_change')
+    expect(actions).toContain('approve')
+    // changedBy default actor + ISO timestamps
+    expect(history.auditLog.every((e) => e.changedBy === 'local')).toBe(true)
+    expect(history.auditLog.every((e) => typeof e.createdAt === 'string')).toBe(
+      true,
+    )
+    // the status_change entry carries the field-level diff
+    const statusEntry = history.auditLog.find(
+      (e) => e.action === 'status_change',
     )
-    expect(search.search.some((n) => n.id === project.id)).toBe(true)
+    expect(statusEntry?.field).toBe('status')
+    expect(statusEntry?.newValue).toBe('pending_review')
 
     // --- Edge removal + node deletion --------------------------------------
     const { removeEdge } = await ok<{ removeEdge: boolean }>(
@@ -414,6 +459,7 @@ describe('CLI/local-server contract (P1-1)', () => {
       'EXPORT_PROJECT',
       'EXPORT_DESCENDANTS',
       'EXPORT_EDGES',
+      'AUDIT_LOG',
     ])
     expect(new Set(Object.keys(LOCAL_CONTRACT_OPERATIONS))).toEqual(exercised)
   })

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

@@ -42,6 +42,67 @@ describe('runMigrations', () => {
     db.close()
   })
 
+  it('creates the audit_log table with SaaS-mirrored columns on a fresh DB', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    expect(tableNames(db)).toContain('audit_log')
+    const cols = columnNames(db, 'audit_log')
+    for (const c of [
+      'id',
+      'node_id',
+      'action',
+      'field',
+      'old_value',
+      'new_value',
+      'snapshot',
+      'changed_by',
+      'created_at',
+    ]) {
+      expect(cols).toContain(c)
+    }
+    db.close()
+  })
+
+  it('adds audit_log when upgrading an existing pre-audit DB', () => {
+    const db = new Database(':memory:')
+    // Simulate a DB already at the pre-audit version (nodes + edges + metadata,
+    // user_version = 2) that has never seen the audit migration.
+    db.run(`
+      CREATE TABLE nodes (
+        id TEXT PRIMARY KEY,
+        type TEXT NOT NULL CHECK(type IN ('project', 'feature', 'task')),
+        title TEXT NOT NULL,
+        description TEXT,
+        status TEXT NOT NULL DEFAULT 'draft' CHECK(status IN ('draft', 'pending_review', 'approved', 'in_progress', 'done', 'blocked', 'cancelled')),
+        metadata TEXT,
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(`
+      CREATE TABLE edges (
+        source_id TEXT NOT NULL REFERENCES nodes(id),
+        target_id TEXT NOT NULL REFERENCES nodes(id),
+        relation TEXT NOT NULL CHECK(relation IN ('part_of', 'blocks')),
+        created_at TEXT NOT NULL DEFAULT (datetime('now')),
+        PRIMARY KEY (source_id, target_id, relation)
+      )
+    `)
+    db.run("INSERT INTO nodes (id, type, title) VALUES ('task_1', 'task', 'T')")
+    db.run('PRAGMA user_version = 2')
+
+    expect(tableNames(db)).not.toContain('audit_log')
+    runMigrations(db)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    expect(tableNames(db)).toContain('audit_log')
+    // existing data preserved across the upgrade
+    const row = db
+      .query<{ id: string }, []>('SELECT id FROM nodes WHERE id = ?')
+      .get('task_1') as { id: string }
+    expect(row.id).toBe('task_1')
+    db.close()
+  })
+
   it('is a no-op when run twice (idempotent)', () => {
     const db = new Database(':memory:')
     runMigrations(db)

package/server/src/migrations.ts

@@ -116,6 +116,33 @@ const MIGRATIONS: Migration[] = [
     db.run('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
     db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
   },
+
+  // 2 -> 3: add the `audit_log` table (F27). Mirrors the SaaS audit_log schema
+  // (id, node_id, action, field, old_value, new_value, snapshot, changed_by,
+  // created_at) so `flowy history` output is consistent across backends. The
+  // local server is single-tenant and has no users table, so `changed_by`
+  // carries a constant actor ('local') rather than a FK to a user. `node_id`
+  // is nullable and ON DELETE SET NULL so delete-audit rows survive the node.
+  // Uses IF NOT EXISTS so the step is idempotent on a DB that somehow already
+  // has the table.
+  (db) => {
+    db.run(`
+      CREATE TABLE IF NOT EXISTS audit_log (
+        id TEXT PRIMARY KEY,
+        node_id TEXT REFERENCES nodes(id) ON DELETE SET NULL,
+        action TEXT NOT NULL,
+        field TEXT,
+        old_value TEXT,
+        new_value TEXT,
+        snapshot TEXT,
+        changed_by TEXT NOT NULL DEFAULT 'local',
+        created_at TEXT NOT NULL DEFAULT (datetime('now'))
+      )
+    `)
+    db.run(
+      'CREATE INDEX IF NOT EXISTS idx_audit_log_node ON audit_log(node_id)',
+    )
+  },
 ]
 
 export const LATEST_VERSION = MIGRATIONS.length