@sqaoss/flowy 0.1.1 → 1.0.2

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,153 @@
+---
+name: using-flowy
+description: Project management CLI for AI coding agents — create projects, features, tasks, track status and approvals
+metadata:
+  sources:
+    - src/commands/project.ts
+    - src/commands/feature.ts
+    - src/commands/task.ts
+    - src/commands/status.ts
+    - src/commands/approve.ts
+    - src/commands/search.ts
+    - src/commands/tree.ts
+    - src/commands/setup.ts
+    - src/util/config.ts
+---
+
+# Flowy — Project Management for AI Agents
+
+Flowy is a hosted project management backend. You interact with it via the `flowy` CLI.
+
+## Setup
+
+```bash
+# Install globally
+bun add -g @sqaoss/flowy    # or: npm i -g @sqaoss/flowy
+
+# SaaS mode (hosted)
+flowy setup --mode saas --email you@example.com
+export FLOWY_API_KEY=flowy_xxx_yyy
+
+# Self-hosted mode
+flowy setup --mode local --api-url http://localhost:4000/graphql
+```
+
+## Hierarchy
+
+Strict top-down: **client → project → feature → task**. No orphans at any level.
+
+- A client has many projects
+- A project has many features
+- A feature has many tasks
+
+## Context
+
+Flowy uses context to know which project and feature you're working in:
+
+- **Project**: mapped to a directory via `flowy project set <name>`, or `FLOWY_PROJECT` env var
+- **Feature**: set via `flowy feature set <name-or-id>`, or `FLOWY_FEATURE` env var
+
+Features and tasks cannot be created without active project/feature context.
+
+## Commands
+
+### Identity
+```bash
+flowy whoami                          # Show current user
+```
+
+### Client
+```bash
+flowy client set name "Acme Corp"     # Set client display name
+```
+
+### Projects
+```bash
+flowy project create "Auth System"    # Create a project
+flowy project set "Auth System"       # Map current dir to project
+flowy project list                    # List all projects
+flowy project show                    # Show active project details
+flowy project show <id>               # Show specific project
+```
+
+### Features (requires active project)
+```bash
+flowy feature create --title "SSO Support" --description sso-spec.md
+flowy feature create --title "Stability" --description "Improve error handling"
+flowy feature set "SSO Support"       # Set active feature
+flowy feature unset                   # Clear active feature
+flowy feature list                    # List features in project
+flowy feature show                    # Show active feature
+```
+
+### Tasks (requires active feature)
+```bash
+flowy task create --title "Implement OAuth" --description oauth.md
+flowy task create --title "Write tests" --description "Unit tests for auth"
+flowy task list                       # List tasks in feature
+flowy task show <id>                  # Show task details
+flowy task block <id1> <id2>          # Mark id1 blocks id2
+flowy task unblock <id1> <id2>        # Remove block
+```
+
+### Status & Approval
+```bash
+flowy status <id> in_progress
+flowy status <id> done
+flowy status <id> pending_review
+flowy approve <id>                    # Must be pending_review
+```
+
+### Search & Explore
+```bash
+flowy search "OAuth" --type task
+flowy search "auth" --status draft --limit 5
+flowy tree <id> --depth 3             # Show subtree
+```
+
+## Entity Types
+- `client` — a client or company
+- `project` — a codebase or product
+- `feature` — a unit of work (replaces epic)
+- `task` — an individual work item
+
+## Status Flow
+`draft` → `pending_review` → `approved` → `in_progress` → `done`
+
+Also: `blocked`, `cancelled`
+
+## Description Field
+`--description` accepts a file path or an inline string:
+- `--description spec.md` — reads file, sends raw content
+- `--description "Do the thing"` — sends string as-is
+
+## Workflow Example
+
+```bash
+# One-time setup
+flowy setup --mode saas --email you@example.com
+flowy client set name "Acme Corp"
+
+# Create and activate project
+flowy project create "Auth System"
+flowy project set "Auth System"
+
+# Plan a feature
+flowy feature create --title "SSO Support" --description sso-spec.md
+flowy feature set "SSO Support"
+
+# Break into tasks
+flowy task create --title "Implement OAuth" --description oauth.md
+flowy task create --title "Write auth tests" --description tests.md
+
+# Track progress
+flowy status <task-id> in_progress
+flowy status <task-id> done
+
+# Move to next feature
+flowy feature create --title "API Rate Limiting" --description rate-limit.md
+flowy feature set "API Rate Limiting"
+```
+
+## Output Format
+All commands output JSON. Parse with `jq` or directly in your agent code.

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)
+    }
+  })