@sqaoss/flowy 1.2.2 → 1.3.1

package/docker-compose.yml

@@ -5,19 +5,24 @@ services:
       dockerfile_inline: |
         FROM oven/bun:1.3.11
         WORKDIR /app
-        RUN bun init -y && bun add @sqaoss/flowy
+        RUN bun init -y && bun add @sqaoss/flowy@1.3.0
         WORKDIR /app/node_modules/@sqaoss/flowy/server
         RUN bun install --production
         EXPOSE 4000
         VOLUME /data
         CMD ["bun", "src/index.ts"]
+    # Publish on loopback only — the server is unauthenticated, so it must not
+    # be reachable from the LAN. Prefer the native `flowy serve` for local dev.
     ports:
-      - "4000:4000"
+      - "127.0.0.1:4000:4000"
     volumes:
       - flowy-data:/data
     environment:
       - FLOWY_DB_PATH=/data/flowy.sqlite
       - PORT=4000
+      # Bind all interfaces *inside* the container so Docker's loopback-only
+      # host publish above can reach it; the host port stays 127.0.0.1.
+      - HOST=0.0.0.0
     healthcheck:
       test: ["CMD", "bun", "-e", "fetch('http://localhost:4000/health').then(r => r.ok ? process.exit(0) : process.exit(1))"]
       interval: 5s

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "1.2.2",
+  "version": "1.3.1",
   "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
@@ -65,7 +65,6 @@
     "husky": "^9.1.7",
     "lint-staged": "^16.3.0",
     "semantic-release": "25.0.3",
-    "tdd-guard-vitest": "^0.1.6",
     "typescript": "^5",
     "vitest": "^4.1.2"
   },

package/server/src/db.test.ts

@@ -1,5 +1,6 @@
 import { describe, expect, it } from 'vitest'
 import { createDb } from './db.ts'
+import { LATEST_VERSION } from './migrations.ts'
 
 describe('createDb', () => {
   it('creates nodes and edges tables', () => {
@@ -90,4 +91,51 @@ describe('createDb', () => {
 
     db.close()
   })
+
+  it('runs migrations to the latest user_version on a fresh DB', () => {
+    const db = createDb(':memory:')
+
+    const result = db.raw
+      .query<{ user_version: number }, []>('PRAGMA user_version')
+      .get()
+
+    expect(result?.user_version).toBe(LATEST_VERSION)
+
+    db.close()
+  })
+
+  it('has a writable metadata column on nodes', () => {
+    const db = createDb(':memory:')
+
+    const columns = db.raw
+      .query<{ name: string }, []>('PRAGMA table_info(nodes)')
+      .all()
+      .map((c) => c.name)
+    expect(columns).toContain('metadata')
+
+    expect(() =>
+      db.raw.run(
+        `INSERT INTO nodes (id, type, title, metadata) VALUES ('n1', 'task', 'T', '{"a":1}')`,
+      ),
+    ).not.toThrow()
+
+    db.close()
+  })
+
+  it('accepts the blocked and cancelled statuses', () => {
+    const db = createDb(':memory:')
+
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n1', 'task', 'T', 'blocked')",
+      ),
+    ).not.toThrow()
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n2', 'task', 'T', 'cancelled')",
+      ),
+    ).not.toThrow()
+
+    db.close()
+  })
 })

package/server/src/db.ts

@@ -1,4 +1,5 @@
 import { Database } from 'bun:sqlite'
+import { runMigrations } from './migrations.ts'
 
 export type FlowyDb = ReturnType<typeof createDb>
 
@@ -8,37 +9,7 @@ export function createDb(path: string) {
   db.run('PRAGMA journal_mode = WAL')
   db.run('PRAGMA foreign_keys = ON')
 
-  db.run(`
-    CREATE TABLE IF NOT EXISTS 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 IF NOT EXISTS 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('CREATE INDEX IF NOT EXISTS idx_nodes_type ON nodes(type)')
-  db.run('CREATE INDEX IF NOT EXISTS idx_nodes_status ON nodes(status)')
-  db.run(
-    'CREATE INDEX IF NOT EXISTS idx_edges_target ON edges(target_id, relation)',
-  )
-  db.run(
-    'CREATE INDEX IF NOT EXISTS idx_edges_source ON edges(source_id, relation)',
-  )
+  runMigrations(db)
 
   return {
     raw: db,

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

@@ -75,6 +75,37 @@ describe('server error masking', () => {
     expect(error.extensions?.code).toBe('VALIDATION_ERROR')
   })
 
+  it('surfaces a not-found node query with real message and NOT_FOUND code (no silent null)', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const json = await gql('query ($id: String!) { node(id: $id) { id } }', {
+      id: 'task_nonexistent',
+    })
+
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).toBe('Node task_nonexistent not found')
+    expect(error.extensions?.code).toBe('NOT_FOUND')
+    const data = json.data as { node: unknown } | null | undefined
+    expect(data?.node ?? null).toBeNull()
+  })
+
+  it('still returns a node when it exists', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "T") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const json = (await gql('query ($id: String!) { node(id: $id) { id } }', {
+      id,
+    })) as { data: { node: { id: string } }; errors?: unknown[] }
+
+    expect(json.errors).toBeUndefined()
+    expect(json.data.node.id).toBe(id)
+  })
+
   it('surfaces an approve-wrong-status error with CONFLICT code', async () => {
     instance = createServer({ dbPath: ':memory:', port: 0 })
 
@@ -94,4 +125,108 @@ describe('server error masking', () => {
     expect(error.message).not.toBe('Unexpected error.')
     expect(error.extensions?.code).toBe('CONFLICT')
   })
+
+  it('round-trips metadata through createNode and the node query', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation ($m: String!) { createNode(type: "task", title: "T", metadata: $m) { id metadata } }',
+      { m: '{"priority":"high"}' },
+    )) as { data: { createNode: { id: string; metadata: string } } }
+    expect(created.data.createNode.metadata).toBe('{"priority":"high"}')
+
+    const id = created.data.createNode.id
+    const fetched = (await gql(
+      'query ($id: String!) { node(id: $id) { metadata } }',
+      { id },
+    )) as { data: { node: { metadata: string } } }
+    expect(JSON.parse(fetched.data.node.metadata)).toEqual({ priority: 'high' })
+  })
+
+  it('updates title/description/status/metadata via updateNode', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "Old") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const updated = (await gql(
+      `mutation ($id: String!) {
+        updateNode(id: $id, title: "New", description: "d", status: "in_progress", metadata: "{\\"k\\":1}") {
+          title description status metadata
+        }
+      }`,
+      { id },
+    )) as {
+      data: {
+        updateNode: {
+          title: string
+          description: string
+          status: string
+          metadata: string
+        }
+      }
+    }
+    expect(updated.data.updateNode.title).toBe('New')
+    expect(updated.data.updateNode.description).toBe('d')
+    expect(updated.data.updateNode.status).toBe('in_progress')
+    expect(JSON.parse(updated.data.updateNode.metadata)).toEqual({ k: 1 })
+  })
+
+  it('rejects non-JSON metadata with VALIDATION_ERROR over the wire', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const json = await gql(
+      'mutation { createNode(type: "task", title: "T", metadata: "not json") { id } }',
+    )
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('VALIDATION_ERROR')
+  })
+
+  it('deletes a leaf node via deleteNode', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const created = (await gql(
+      'mutation { createNode(type: "task", title: "T") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const id = created.data.createNode.id
+
+    const del = (await gql('mutation ($id: String!) { deleteNode(id: $id) }', {
+      id,
+    })) as { data: { deleteNode: boolean } }
+    expect(del.data.deleteNode).toBe(true)
+
+    const fetched = await gql('query ($id: String!) { node(id: $id) { id } }', {
+      id,
+    })
+    // The node is gone: querying it now fails loud with NOT_FOUND.
+    expect(fetched.errors).toBeDefined()
+    expect(fetched.errors![0].extensions?.code).toBe('NOT_FOUND')
+  })
+
+  it('refuses to delete a parent with children (CONFLICT)', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const project = (await gql(
+      'mutation { createNode(type: "project", title: "P") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    const feature = (await gql(
+      'mutation { createNode(type: "feature", title: "F") { id } }',
+    )) as { data: { createNode: { id: string } } }
+    await gql(
+      'mutation ($s: String!, $t: String!) { createEdge(sourceId: $s, targetId: $t, relation: "part_of") { relation } }',
+      { s: feature.data.createNode.id, t: project.data.createNode.id },
+    )
+
+    const json = await gql('mutation ($id: String!) { deleteNode(id: $id) }', {
+      id: project.data.createNode.id,
+    })
+    expect(json.errors).toBeDefined()
+    const error = json.errors![0]
+    expect(error.message).not.toBe('Unexpected error.')
+    expect(error.extensions?.code).toBe('CONFLICT')
+  })
 })

package/server/src/index.test.ts

@@ -22,4 +22,33 @@ describe('createServer', () => {
     expect(res.status).toBe(200)
     expect(json).toEqual({ status: 'ok' })
   })
+
+  it('binds to 127.0.0.1 by default, not all interfaces', () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    expect(instance.hostname).toBe('127.0.0.1')
+    expect(instance.server.hostname).toBe('127.0.0.1')
+  })
+
+  it('allows the bind hostname to be overridden via opts', () => {
+    instance = createServer({
+      dbPath: ':memory:',
+      port: 0,
+      hostname: '0.0.0.0',
+    })
+
+    expect(instance.hostname).toBe('0.0.0.0')
+  })
+
+  it('allows the bind hostname to be overridden via HOST env', () => {
+    const prev = process.env.HOST
+    process.env.HOST = '0.0.0.0'
+    try {
+      instance = createServer({ dbPath: ':memory:', port: 0 })
+      expect(instance.hostname).toBe('0.0.0.0')
+    } finally {
+      if (prev === undefined) delete process.env.HOST
+      else process.env.HOST = prev
+    }
+  })
 })

package/server/src/index.ts

@@ -3,9 +3,16 @@ import { createDb } from './db.ts'
 import { createResolvers } from './resolvers.ts'
 import { typeDefs } from './schema.ts'
 
-export function createServer(opts?: { dbPath?: string; port?: number }) {
+export function createServer(opts?: {
+  dbPath?: string
+  port?: number
+  hostname?: string
+}) {
   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'
 
   const db = createDb(dbPath)
   const resolvers = createResolvers(db)
@@ -17,6 +24,7 @@ export function createServer(opts?: { dbPath?: string; port?: number }) {
 
   const server = Bun.serve({
     port,
+    hostname,
     fetch(req) {
       const url = new URL(req.url)
       if (url.pathname === '/health' && req.method === 'GET') {
@@ -29,6 +37,7 @@ export function createServer(opts?: { dbPath?: string; port?: number }) {
   return {
     server,
     port: server.port,
+    hostname: server.hostname,
     db,
     close() {
       server.stop()
@@ -38,8 +47,9 @@ export function createServer(opts?: { dbPath?: string; port?: number }) {
 }
 
 if (import.meta.main) {
-  const { port } = createServer()
-  console.log(`Flowy local server running on http://localhost:${port}`)
-  console.log(`  GraphQL: http://localhost:${port}/graphql`)
-  console.log(`  Health:  http://localhost:${port}/health`)
+  const { port, hostname } = createServer()
+  const host = hostname === '0.0.0.0' ? 'localhost' : hostname
+  console.log(`Flowy local server running on http://${host}:${port}`)
+  console.log(`  GraphQL: http://${host}:${port}/graphql`)
+  console.log(`  Health:  http://${host}:${port}/health`)
 }

package/server/src/migrations.test.ts

@@ -0,0 +1,218 @@
+import { Database } from 'bun:sqlite'
+import { describe, expect, it } from 'vitest'
+import { LATEST_VERSION, rebuildTable, runMigrations } from './migrations.ts'
+
+function userVersion(db: Database): number {
+  const row = db
+    .query<{ user_version: number }, []>('PRAGMA user_version')
+    .get()
+  return row?.user_version ?? 0
+}
+
+function tableNames(db: Database): string[] {
+  return db
+    .query<{ name: string }, []>(
+      "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+    )
+    .all()
+    .map((r) => r.name)
+}
+
+function columnNames(db: Database, table: string): string[] {
+  return db
+    .query<{ name: string }, []>(`PRAGMA table_info(${table})`)
+    .all()
+    .map((r) => r.name)
+}
+
+describe('runMigrations', () => {
+  it('brings a fresh DB to the latest user_version', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    db.close()
+  })
+
+  it('creates the nodes and edges tables on a fresh DB', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    const tables = tableNames(db)
+    expect(tables).toContain('nodes')
+    expect(tables).toContain('edges')
+    db.close()
+  })
+
+  it('is a no-op when run twice (idempotent)', () => {
+    const db = new Database(':memory:')
+    runMigrations(db)
+    const versionAfterFirst = userVersion(db)
+    // second run must not throw and must not change the version
+    runMigrations(db)
+    expect(userVersion(db)).toBe(versionAfterFirst)
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    db.close()
+  })
+
+  it('upgrades an old-shaped DB forward without losing data', () => {
+    const db = new Database(':memory:')
+    // Simulate a March-era schema: nodes table WITHOUT a metadata column,
+    // and a CHECK constraint that does not yet allow newer vocabulary.
+    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')),
+        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, description, status) VALUES ('proj_old', 'project', 'Legacy Project', 'from march', 'in_progress')",
+    )
+
+    runMigrations(db)
+
+    expect(userVersion(db)).toBe(LATEST_VERSION)
+    // metadata column now exists
+    expect(columnNames(db, 'nodes')).toContain('metadata')
+    // legacy row preserved
+    const row = db
+      .query<
+        { id: string; title: string; status: string; metadata: string | null },
+        []
+      >('SELECT id, title, status, metadata FROM nodes WHERE id = ?')
+      .get('proj_old') as {
+      id: string
+      title: string
+      status: string
+      metadata: string | null
+    }
+    expect(row.id).toBe('proj_old')
+    expect(row.title).toBe('Legacy Project')
+    expect(row.status).toBe('in_progress')
+    db.close()
+  })
+
+  it('after migration the new vocabulary (blocked, cancelled) is accepted', () => {
+    const db = new Database(':memory:')
+    // Old DB with a restrictive status CHECK (no blocked/cancelled)
+    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')),
+        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')")
+
+    runMigrations(db)
+
+    // The CHECK rebuild should now permit 'cancelled'
+    expect(() =>
+      db.run("UPDATE nodes SET status = 'cancelled' WHERE id = 'task_1'"),
+    ).not.toThrow()
+  })
+
+  describe('rebuildTable helper', () => {
+    it('rebuilds a table with a new CHECK constraint, preserving rows', () => {
+      const db = new Database(':memory:')
+      db.run(`
+        CREATE TABLE widgets (
+          id TEXT PRIMARY KEY,
+          kind TEXT NOT NULL CHECK(kind IN ('a', 'b'))
+        )
+      `)
+      db.run("INSERT INTO widgets (id, kind) VALUES ('w1', 'a')")
+
+      rebuildTable(
+        db,
+        'widgets',
+        (tmp) => `
+          CREATE TABLE ${tmp} (
+            id TEXT PRIMARY KEY,
+            kind TEXT NOT NULL CHECK(kind IN ('a', 'b', 'c'))
+          )
+        `,
+        ['id', 'kind'],
+      )
+
+      // existing row preserved
+      const row = db
+        .query<{ id: string; kind: string }, []>(
+          'SELECT id, kind FROM widgets WHERE id = ?',
+        )
+        .get('w1') as { id: string; kind: string }
+      expect(row).toEqual({ id: 'w1', kind: 'a' })
+      // new value now allowed by the widened CHECK
+      expect(() =>
+        db.run("INSERT INTO widgets (id, kind) VALUES ('w2', 'c')"),
+      ).not.toThrow()
+      db.close()
+    })
+  })
+
+  it('preserves edges across a nodes CHECK-rebuild migration', () => {
+    const db = new Database(':memory:')
+    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')),
+        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 ('proj_1', 'project', 'P')",
+    )
+    db.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('feat_1', 'feature', 'F')",
+    )
+    db.run(
+      "INSERT INTO edges (source_id, target_id, relation) VALUES ('feat_1', 'proj_1', 'part_of')",
+    )
+
+    runMigrations(db)
+
+    const edgeCount = db
+      .query<{ c: number }, []>('SELECT COUNT(*) AS c FROM edges')
+      .get() as { c: number }
+    expect(edgeCount.c).toBe(1)
+    db.close()
+  })
+})