@sqaoss/flowy 0.1.1 → 1.1.0

package/server/src/resolvers.ts

@@ -0,0 +1,308 @@
+import { nanoid } from 'nanoid'
+import type { FlowyDb } from './db.ts'
+
+type Db = FlowyDb
+
+interface NodeRow {
+  id: string
+  type: string
+  title: string
+  description: string | null
+  status: string
+  metadata: string | null
+  created_at: string
+  updated_at: string
+}
+
+export interface NodeGql {
+  id: string
+  type: string
+  title: string
+  description: string | null
+  status: string
+  metadata: string | null
+  createdAt: string
+  updatedAt: string
+}
+
+const NODE_COLS =
+  'id, type, title, description, status, metadata, created_at, updated_at'
+
+const PREFIX_MAP: Record<string, string> = {
+  project: 'proj',
+  feature: 'feat',
+  task: 'task',
+}
+
+const VALID_STATUSES = new Set([
+  'draft',
+  'pending_review',
+  'approved',
+  'in_progress',
+  'done',
+  'blocked',
+  'cancelled',
+])
+
+function generateId(type: string): string {
+  const prefix = PREFIX_MAP[type] ?? type
+  return `${prefix}_${nanoid(12)}`
+}
+
+function rowToNode(row: NodeRow): NodeGql {
+  return {
+    id: row.id,
+    type: row.type,
+    title: row.title,
+    description: row.description,
+    status: row.status,
+    metadata: row.metadata,
+    createdAt: row.created_at,
+    updatedAt: row.updated_at,
+  }
+}
+
+function selectNode(db: Db, id: string): NodeGql | null {
+  const row = db.raw
+    .query(`SELECT ${NODE_COLS} FROM nodes WHERE id = ?`)
+    .get(id) as NodeRow | null
+  return row ? rowToNode(row) : null
+}
+
+function selectNodes(rows: NodeRow[]): NodeGql[] {
+  return rows.map(rowToNode)
+}
+
+function prefixedCols() {
+  return NODE_COLS.split(', ')
+    .map((c) => `n.${c}`)
+    .join(', ')
+}
+
+export function createResolvers(db: Db) {
+  return {
+    Query: {
+      node: (_: unknown, args: { id: string }) => {
+        return selectNode(db, args.id)
+      },
+
+      nodes: (_: unknown, args: { type?: string }) => {
+        const conditions: string[] = []
+        const params: string[] = []
+        if (args.type) {
+          conditions.push('type = ?')
+          params.push(args.type)
+        }
+        const where =
+          conditions.length > 0 ? `WHERE ${conditions.join(' AND ')}` : ''
+        const rows = db.raw
+          .query(`SELECT ${NODE_COLS} FROM nodes ${where}`)
+          .all(...params) as NodeRow[]
+        return selectNodes(rows)
+      },
+
+      descendants: (
+        _: unknown,
+        args: { nodeId: string; relation?: string; maxDepth?: number },
+      ) => {
+        const maxDepth = args.maxDepth ?? 100
+        if (maxDepth === 0) return []
+        let rows: NodeRow[]
+        if (args.relation) {
+          rows = db.raw
+            .query(
+              `WITH RECURSIVE tree(id, depth) AS (
+                SELECT source_id, 1 FROM edges WHERE target_id = ?1 AND relation = ?3
+                UNION ALL
+                SELECT e.source_id, t.depth + 1 FROM edges e
+                JOIN tree t ON e.target_id = t.id WHERE t.depth < ?2 AND e.relation = ?3
+              )
+              SELECT DISTINCT ${prefixedCols()} FROM nodes n JOIN tree t ON n.id = t.id`,
+            )
+            .all(args.nodeId, maxDepth, args.relation) as NodeRow[]
+        } else {
+          rows = db.raw
+            .query(
+              `WITH RECURSIVE tree(id, depth) AS (
+                SELECT source_id, 1 FROM edges WHERE target_id = ?1
+                UNION ALL
+                SELECT e.source_id, t.depth + 1 FROM edges e
+                JOIN tree t ON e.target_id = t.id WHERE t.depth < ?2
+              )
+              SELECT DISTINCT ${prefixedCols()} FROM nodes n JOIN tree t ON n.id = t.id`,
+            )
+            .all(args.nodeId, maxDepth) as NodeRow[]
+        }
+        return selectNodes(rows)
+      },
+
+      subtree: (_: unknown, args: { nodeId: string; maxDepth?: number }) => {
+        const maxDepth = args.maxDepth ?? 100
+        if (maxDepth === 0) return []
+        const rows = db.raw
+          .query(
+            `WITH RECURSIVE tree(id, depth) AS (
+              SELECT source_id, 1 FROM edges WHERE target_id = ?1
+              UNION ALL
+              SELECT e.source_id, t.depth + 1 FROM edges e
+              JOIN tree t ON e.target_id = t.id WHERE t.depth < ?2
+            )
+            SELECT DISTINCT ${prefixedCols()} FROM nodes n JOIN tree t ON n.id = t.id`,
+          )
+          .all(args.nodeId, maxDepth) as NodeRow[]
+        return selectNodes(rows)
+      },
+
+      search: (
+        _: unknown,
+        args: {
+          query: string
+          type?: string
+          status?: string
+          limit?: number
+        },
+      ) => {
+        if (args.query.trim().length < 3) {
+          throw new Error('Search query must be at least 3 characters')
+        }
+        const escaped = args.query.replace(/[%_\\]/g, '\\$&')
+        const conditions = [
+          "(title LIKE ? ESCAPE '\\' OR description LIKE ? ESCAPE '\\')",
+        ]
+        const params: (string | number)[] = [`%${escaped}%`, `%${escaped}%`]
+        if (args.type) {
+          conditions.push('type = ?')
+          params.push(args.type)
+        }
+        if (args.status) {
+          conditions.push('status = ?')
+          params.push(args.status)
+        }
+        const limit = args.limit ?? 50
+        const rows = db.raw
+          .query(
+            `SELECT ${NODE_COLS} FROM nodes WHERE ${conditions.join(' AND ')} LIMIT ?`,
+          )
+          .all(...params, limit) as NodeRow[]
+        return selectNodes(rows)
+      },
+    },
+
+    Mutation: {
+      createNode: (
+        _: unknown,
+        args: { type: string; title: string; description?: string },
+      ): NodeGql => {
+        if (!args.title.trim()) throw new Error('Title is required')
+        if (args.description != null && !args.description.trim()) {
+          throw new Error('Description cannot be empty')
+        }
+        const id = generateId(args.type)
+        const now = new Date().toISOString()
+        const description = args.description ?? null
+        db.raw.run(
+          'INSERT INTO nodes (id, type, title, description, status, metadata, created_at, updated_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
+          [id, args.type, args.title, description, 'draft', null, now, now],
+        )
+        return {
+          id,
+          type: args.type,
+          title: args.title,
+          description,
+          status: 'draft',
+          metadata: null,
+          createdAt: now,
+          updatedAt: now,
+        }
+      },
+
+      updateNode: (_: unknown, args: { id: string; status?: string }) => {
+        const existing = db.raw
+          .query('SELECT * FROM nodes WHERE id = ?')
+          .get(args.id) as NodeRow | null
+        if (!existing) throw new Error(`Node ${args.id} not found`)
+        const newStatus = args.status ?? existing.status
+        if (args.status && !VALID_STATUSES.has(args.status)) {
+          throw new Error(
+            `Invalid status: ${args.status}. Must be one of: ${[...VALID_STATUSES].join(', ')}`,
+          )
+        }
+        const now = new Date().toISOString()
+        db.raw.run('UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?', [
+          newStatus,
+          now,
+          args.id,
+        ])
+        return rowToNode({ ...existing, status: newStatus, updated_at: now })
+      },
+
+      approveNode: (_: unknown, args: { id: string }) => {
+        const existing = db.raw
+          .query('SELECT * FROM nodes WHERE id = ?')
+          .get(args.id) as NodeRow | null
+        if (!existing) throw new Error(`Node ${args.id} not found`)
+        if (existing.status !== 'pending_review') {
+          throw new Error(
+            `Cannot approve node with status "${existing.status}", must be "pending_review"`,
+          )
+        }
+        const now = new Date().toISOString()
+        db.raw.run('UPDATE nodes SET status = ?, updated_at = ? WHERE id = ?', [
+          'approved',
+          now,
+          args.id,
+        ])
+        return rowToNode({ ...existing, status: 'approved', updated_at: now })
+      },
+
+      createEdge: (
+        _: unknown,
+        args: { sourceId: string; targetId: string; relation: string },
+      ) => {
+        const validRelations = new Set(['part_of', 'blocks'])
+        if (!validRelations.has(args.relation)) {
+          throw new Error(
+            `Invalid relation: ${args.relation}. Must be 'part_of' or 'blocks'`,
+          )
+        }
+        const sourceExists = db.raw
+          .query('SELECT id FROM nodes WHERE id = ?')
+          .get(args.sourceId)
+        if (!sourceExists) {
+          throw new Error(`Source node ${args.sourceId} not found`)
+        }
+        const targetExists = db.raw
+          .query('SELECT id FROM nodes WHERE id = ?')
+          .get(args.targetId)
+        if (!targetExists) {
+          throw new Error(`Target node ${args.targetId} not found`)
+        }
+        if (args.relation === 'blocks' && args.sourceId === args.targetId) {
+          throw new Error('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],
+        )
+        return {
+          sourceId: args.sourceId,
+          targetId: args.targetId,
+          relation: args.relation,
+          createdAt: now,
+        }
+      },
+
+      removeEdge: (
+        _: 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
+      },
+    },
+  }
+}

package/server/src/schema.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import { schema } from './schema.ts'
+
+describe('schema', () => {
+  it('exports a valid GraphQL schema object', () => {
+    expect(schema).toBeDefined()
+    expect(typeof schema).toBe('object')
+  })
+
+  it('defines Node type with required fields', () => {
+    const nodeType = schema.getType(
+      'Node',
+    ) as import('graphql').GraphQLObjectType
+    expect(nodeType).toBeDefined()
+    const fields = nodeType.getFields()
+    expect(fields.id).toBeDefined()
+    expect(fields.type).toBeDefined()
+    expect(fields.title).toBeDefined()
+    expect(fields.description).toBeDefined()
+    expect(fields.status).toBeDefined()
+    expect(fields.metadata).toBeDefined()
+    expect(fields.createdAt).toBeDefined()
+    expect(fields.updatedAt).toBeDefined()
+  })
+
+  it('uses String types instead of enums (no NodeType, Status, Relation enums)', () => {
+    expect(schema.getType('NodeType')).toBeUndefined()
+    expect(schema.getType('Status')).toBeUndefined()
+    expect(schema.getType('Relation')).toBeUndefined()
+  })
+
+  it('Node type does not have children, blockedBy, or blocking fields', () => {
+    const nodeType = schema.getType(
+      'Node',
+    ) as import('graphql').GraphQLObjectType
+    const fields = nodeType.getFields()
+    expect(fields.children).toBeUndefined()
+    expect(fields.blockedBy).toBeUndefined()
+    expect(fields.blocking).toBeUndefined()
+  })
+
+  it('Edge type has sourceId, targetId, relation, createdAt as String fields', () => {
+    const edgeType = schema.getType(
+      'Edge',
+    ) as import('graphql').GraphQLObjectType
+    const fields = edgeType.getFields()
+    expect(fields.sourceId).toBeDefined()
+    expect(fields.targetId).toBeDefined()
+    expect(fields.relation).toBeDefined()
+    expect(fields.createdAt).toBeDefined()
+  })
+
+  it('Query type has node, nodes, descendants, subtree, search', () => {
+    const queryType = schema.getType(
+      'Query',
+    ) as import('graphql').GraphQLObjectType
+    const fields = queryType.getFields()
+    expect(fields.node).toBeDefined()
+    expect(fields.nodes).toBeDefined()
+    expect(fields.descendants).toBeDefined()
+    expect(fields.subtree).toBeDefined()
+    expect(fields.search).toBeDefined()
+  })
+
+  it('Query type does not have tree', () => {
+    const queryType = schema.getType(
+      'Query',
+    ) as import('graphql').GraphQLObjectType
+    const fields = queryType.getFields()
+    expect(fields.tree).toBeUndefined()
+  })
+
+  it('Mutation type has createNode, updateNode, approveNode, createEdge, removeEdge', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const fields = mutationType.getFields()
+    expect(fields.createNode).toBeDefined()
+    expect(fields.updateNode).toBeDefined()
+    expect(fields.approveNode).toBeDefined()
+    expect(fields.createEdge).toBeDefined()
+    expect(fields.removeEdge).toBeDefined()
+  })
+
+  it('Mutation type does not have deleteNode or deleteEdge', () => {
+    const mutationType = schema.getType(
+      'Mutation',
+    ) as import('graphql').GraphQLObjectType
+    const fields = mutationType.getFields()
+    expect(fields.deleteNode).toBeUndefined()
+    expect(fields.deleteEdge).toBeUndefined()
+  })
+})

package/server/src/schema.ts

@@ -0,0 +1,45 @@
+import { createSchema } from 'graphql-yoga'
+
+export const typeDefs = /* GraphQL */ `
+  type Node {
+    id: String!
+    type: String!
+    title: String!
+    description: String
+    status: String!
+    metadata: String
+    createdAt: String!
+    updatedAt: String!
+  }
+
+  type Edge {
+    sourceId: String!
+    targetId: String!
+    relation: String!
+    createdAt: String!
+  }
+
+  type Query {
+    node(id: String!): Node
+    nodes(type: String): [Node!]!
+    descendants(nodeId: String!, relation: String, maxDepth: Int): [Node!]!
+    subtree(nodeId: String!, maxDepth: Int): [Node!]!
+    search(query: String!, type: String, status: String, limit: Int): [Node!]!
+  }
+
+  type Mutation {
+    createNode(type: String!, title: String!, description: String): Node!
+    updateNode(id: String!, status: String): Node!
+    approveNode(id: String!): Node!
+    createEdge(sourceId: String!, targetId: String!, relation: String!): Edge!
+    removeEdge(sourceId: String!, targetId: String!, relation: String!): Boolean!
+  }
+`
+
+export const schema = createSchema({
+  typeDefs,
+  resolvers: {
+    Query: {},
+    Mutation: {},
+  },
+})

package/skills/using-flowy/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: flowy
+description: Store plans and track execution with Flowy CLI. Use when you need to create features, break work into tasks, track progress, or manage project structure. Trigger on any planning, task tracking, or work organization request.
+---
+
+# Flowy — Agentic Persistent Planning
+
+Flowy gives you a persistent store for plans and execution tracking. Features are your master plans. Tasks are your execution steps. Everything persists across sessions, no files in git, no context lost.
+
+## Why Use Flowy
+
+Without Flowy, your plans live in markdown files that clutter git history, get deleted when done, and leave no record of what you accomplished. With Flowy, plans persist in a database. You flow through work without friction. Your human gets full observability.
+
+## First Time in a Project
+
+```bash
+flowy init           # auto-detects the git repo, creates a project, maps this directory
+```
+
+If Flowy isn't set up yet, the human needs to run:
+```bash
+npm i -g @sqaoss/flowy
+flowy setup remote --email their@email.com
+```
+
+## Core Workflow
+
+```bash
+# 1. Plan a feature (master plan)
+flowy feature create --title "User Auth" --description auth-spec.md
+flowy feature set "User Auth"
+
+# 2. Break into tasks (execution steps)
+flowy task create --title "Implement OAuth" --description oauth.md
+flowy task create --title "Write tests" --description "Unit + integration tests"
+
+# 3. Execute and track
+flowy status <task-id> in_progress
+# ... do the work ...
+flowy status <task-id> done
+
+# 4. Move to next task or feature
+flowy feature create --title "API Rate Limiting" --description rate-limit.md
+flowy feature set "API Rate Limiting"
+```
+
+## Entity Hierarchy
+
+```
+project -> feature -> task
+  1:many     1:many
+```
+
+Every task belongs to a feature. Every feature belongs to a project. No orphans. The project is set automatically by `flowy init`.
+
+## Status Flow
+
+```
+draft -> pending_review -> approved -> in_progress -> done
+```
+
+Also: `blocked`, `cancelled`
+
+Only `pending_review` entities can be approved via `flowy approve <id>`.
+
+## Commands
+
+### Project Context
+```bash
+flowy init                            # Auto-detect repo, create + set project
+flowy project list                    # List all projects
+flowy project show [<id>]             # Show project details
+```
+
+### Features (requires active project)
+```bash
+flowy feature create --title "Title" --description "description or file.md"
+flowy feature set "Title or ID"       # Set active feature
+flowy feature unset                   # Clear active feature
+flowy feature list                    # List features in project
+flowy feature show [<id>]             # Show feature details
+```
+
+### Tasks (requires active feature)
+```bash
+flowy task create --title "Title" --description "description or file.md"
+flowy task list                       # List tasks in feature
+flowy task show <id>                  # Show task details
+flowy task block <blocker> <blocked>  # Mark dependency
+flowy task unblock <blocker> <blocked>
+```
+
+### Status and Approval
+```bash
+flowy status <id> in_progress
+flowy status <id> pending_review
+flowy approve <id>                    # Only works on pending_review
+flowy status <id> done
+```
+
+### Search and Explore
+```bash
+flowy search "query" --type task --status draft --limit 10
+flowy tree <project-id> --depth 3     # Show full subtree
+```
+
+## Validation Rules
+
+- **Title is required** and cannot be empty
+- **Description** is optional, but if provided cannot be empty
+- **--description** accepts a file path (reads content) or an inline string
+- **Search** requires at least 3 characters
+- **Status** must be one of: draft, pending_review, approved, in_progress, done, blocked, cancelled
+- **Blocking**: a task cannot block itself
+- **Edges**: both source and target nodes must exist
+
+## Output Format
+
+All commands output JSON to stdout. Errors go to stderr as `{ "error": "message" }`.
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `FLOWY_PROJECT` | Override active project by name |
+| `FLOWY_FEATURE` | Override active feature by ID |
+| `FLOWY_API_URL` | GraphQL endpoint |
+| `FLOWY_API_KEY` | API key (from setup) |

package/src/commands/client.test.ts

@@ -0,0 +1,40 @@
+import { existsSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { resolve } from 'node:path'
+import { afterEach, beforeEach, describe, expect, test } from 'vitest'
+
+const CONFIG_PATH = resolve(homedir(), '.config', 'flowy', 'config.json')
+
+describe('client command', () => {
+  let originalConfig: string | null = null
+
+  beforeEach(() => {
+    originalConfig = existsSync(CONFIG_PATH)
+      ? readFileSync(CONFIG_PATH, 'utf-8')
+      : null
+  })
+
+  afterEach(() => {
+    if (originalConfig !== null) {
+      writeFileSync(CONFIG_PATH, originalConfig)
+    } else if (existsSync(CONFIG_PATH)) {
+      rmSync(CONFIG_PATH)
+    }
+  })
+
+  test('exports a command group named client', async () => {
+    const { clientCommand } = await import('./client.ts')
+    expect(clientCommand.name()).toBe('client')
+  })
+
+  test('set name updates config', async () => {
+    const { clientCommand } = await import('./client.ts')
+    await clientCommand.parseAsync(['set', 'name', 'Acme Corp'], {
+      from: 'user',
+    })
+
+    const { loadConfig } = await import('../util/config.ts')
+    const config = loadConfig()
+    expect(config.client.name).toBe('Acme Corp')
+  })
+})

package/src/commands/client.ts

@@ -0,0 +1,34 @@
+import { Command } from 'commander'
+import { loadConfig, saveConfig } from '../util/config.ts'
+import { output, outputError } from '../util/format.ts'
+
+const SUPPORTED_PROPERTIES = ['name'] as const
+
+export const clientCommand = new Command('client').description(
+  'Manage client settings',
+)
+
+clientCommand
+  .command('set')
+  .description('Set a client property')
+  .argument('<property>', 'Property to set')
+  .argument('<value>', 'Value to set')
+  .action((property: string, value: string) => {
+    try {
+      if (
+        !SUPPORTED_PROPERTIES.includes(
+          property as (typeof SUPPORTED_PROPERTIES)[number],
+        )
+      ) {
+        throw new Error(
+          `Unknown property "${property}". Supported: ${SUPPORTED_PROPERTIES.join(', ')}`,
+        )
+      }
+      const config = loadConfig()
+      config.client.name = value
+      saveConfig(config)
+      output({ property, value })
+    } catch (error) {
+      outputError(error)
+    }
+  })