@sqaoss/flowy 0.1.0 → 1.0.2

package/README.md

@@ -1,79 +1,95 @@
 # Flowy
 
-CLI for Flowy — project management for AI coding agents.
+Project management for AI coding agents.
 
 [![npm](https://img.shields.io/npm/v/@sqaoss/flowy)](https://www.npmjs.com/package/@sqaoss/flowy)
-[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)
+[![License: Apache-2.0](https://img.shields.io/badge/License-Apache--2.0-blue.svg)](LICENSE)
 [![CI](https://github.com/sqaoss/flowy/actions/workflows/ci.yml/badge.svg)](https://github.com/sqaoss/flowy/actions/workflows/ci.yml)
 
 ## What is Flowy
 
-Flowy is a hosted backend project management service built for AI coding agents. It uses a graph data model (nodes and edges) to represent projects, features, epics, and tasks with typed relationships between them. This package provides the CLI that agents use to interact with the Flowy API.
+Flowy is a backend + CLI that gives AI coding agents structured project management. It enforces a strict hierarchy -- **client -> project -> feature -> task** -- so agents always have clear context about what they're working on.
 
-## Quick Start
+Run it locally with SQLite and Docker, or connect to the hosted SaaS for multi-agent team collaboration.
+
+## Quick Start (Local Mode)
+
+Local mode runs a Flowy server on your machine using Docker. No account needed.
 
 ```bash
 # Install
 bun add -g @sqaoss/flowy    # or: npm i -g @sqaoss/flowy
 
-# Register and get your API key
-flowy register --email you@example.com
-export FLOWY_API_KEY=flowy_xxx_yyy
+# Start the local server (requires Docker)
+flowy setup local
+
+# Set your client name
+flowy client set name "Acme Corp"
 
-# Create a project
-flowy node create --type project --title "Auth System"
+# Create a project and map it to the current directory
+flowy project create "Auth System"
+flowy project set "Auth System"
 
-# Add tasks
-flowy node create --type task --title "Implement OAuth"
-flowy node create --type task --title "Write auth tests"
+# Plan a feature
+flowy feature create --title "SSO Support" --description sso-spec.md
+flowy feature set "SSO Support"
 
-# Link tasks to project
-flowy edge create --source <task-id> --target <project-id> --relation part_of
+# Create tasks
+flowy task create --title "Implement OAuth" --description oauth.md
+flowy task create --title "Write auth tests" --description "Unit + integration tests"
 
-# Track status
+# Track progress
 flowy status <task-id> in_progress
 flowy status <task-id> done
 
 # Search and explore
 flowy search "OAuth" --type task
-flowy tree subtree <project-id> --depth 3
+flowy tree <project-id> --depth 3
 ```
 
+## Remote Mode (Coming Soon)
+
+Remote mode connects to the hosted Flowy SaaS for multi-agent collaboration, shared project state across teams, and persistent history. Registration and API key setup will happen directly through the CLI -- no website needed. This is currently a work in progress.
+
 ## Command Reference
 
 | Command | Description |
 |---------|-------------|
-| `register --email <email>` | Register and get API key |
+| `setup local` | Start a local Docker server and configure the CLI |
+| `setup remote` | Connect to the hosted SaaS (coming soon) |
 | `whoami` | Show current user |
-| `node create --type <type> --title <title> [--description] [--status] [--metadata]` | Create node |
-| `node get --id <id>` | Get node |
-| `node list [--type] [--status] [--limit] [--offset]` | List nodes |
-| `node update --id <id> [--title] [--description] [--status] [--metadata]` | Update node |
-| `node delete --id <id>` | Delete node |
+| `client set name <name>` | Set client display name |
+| `project create <name>` | Create project |
+| `project set <name>` | Map current directory to project |
+| `project list` | List all projects |
+| `project show [<id>]` | Show project details |
+| `feature create --title <t> --description <d>` | Create feature (requires active project) |
+| `feature set <name-or-id>` | Set active feature |
+| `feature unset` | Clear active feature |
+| `feature list` | List features in active project |
+| `feature show [<id>]` | Show feature details |
+| `task create --title <t> --description <d>` | Create task (requires active feature) |
+| `task list` | List tasks in active feature |
+| `task show <id>` | Show task details |
+| `task block <id1> <id2>` | Mark task as blocking another |
+| `task unblock <id1> <id2>` | Remove block |
 | `status <id> <status>` | Update status (shorthand) |
-| `approve <id>` | Approve node (must be pending_review) |
-| `edge create --source <id> --target <id> --relation <rel>` | Create edge |
-| `edge list [--node <id>] [--relation <rel>]` | List edges |
-| `edge remove --source <id> --target <id> --relation <rel>` | Remove edge |
-| `search <query> [--type] [--status] [--limit]` | Search nodes |
-| `tree subtree <id> [--depth N]` | Show subtree |
-| `tree ancestors <id> [--depth N] [--relation <rel>]` | Show ancestors |
-| `tree descendants <id> [--depth N] [--relation <rel>]` | Show descendants |
+| `approve <id>` | Approve (must be pending_review) |
+| `search <query> [--type] [--status] [--limit]` | Full-text search |
+| `tree <id> [--depth N]` | Show subtree |
 
-All commands output JSON.
+All commands output JSON to stdout.
 
 ## Data Model
 
-### Node Types
-
-`client`, `project`, `feature`, `epic`, `task`
+### Entity Hierarchy
 
-### Edge Relations
+```
+client -> project -> feature -> task
+           1:many    1:many    1:many
+```
 
-- `part_of` -- child belongs to parent
-- `depends_on` -- must complete before starting
-- `blocks` -- prevents progress on target
-- `informs` -- provides context to target
+Every entity belongs to its parent. No orphans.
 
 ### Status Flow
 
@@ -83,15 +99,44 @@ 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 content
+- `--description "Do the thing"` -- sends string as-is
+
 ## Configuration
 
+Config is stored at `~/.config/flowy/config.json`.
+
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `FLOWY_API_URL` | GraphQL endpoint | `https://flowy-ai.fly.dev/graphql` |
-| `FLOWY_API_KEY` | API key from register | -- |
+| `FLOWY_API_URL` | GraphQL endpoint | `http://localhost:4000/graphql` |
+| `FLOWY_API_KEY` | API key (remote mode only) | -- |
+| `FLOWY_PROJECT` | Override active project by name | -- |
+| `FLOWY_FEATURE` | Override active feature by ID | -- |
 
-## License
+## For AI Agents
 
-Copyright (C) 2026 SQA & Automation SRL
+Flowy integrates with [TanStack Intent](https://github.com/TanStack/intent) for automatic tool discovery. Run:
+
+```bash
+npx @tanstack/intent install
+```
+
+This auto-discovers the Flowy skill and makes it available to your agent. See [`skills/using-flowy/SKILL.md`](skills/using-flowy/SKILL.md) for the full skill reference.
+
+## Development
+
+```bash
+bun run test          # Run CLI tests (Vitest)
+bun run check         # Biome lint + format
+bun run typecheck     # TypeScript type checking
+
+# Server tests
+cd server && bunx --bun vitest run
+```
+
+## License
 
-[AGPL-3.0](LICENSE)
+Apache-2.0 -- Copyright 2026 SQA & Automation SRL

package/docker-compose.yml

@@ -0,0 +1,14 @@
+services:
+  server:
+    build: ./server
+    ports:
+      - "4000:4000"
+    environment:
+      - NODE_ENV=production
+    restart: unless-stopped
+    healthcheck:
+      test: ["CMD", "bun", "-e", "const r = await fetch('http://localhost:4000/health'); if (!r.ok) process.exit(1)"]
+      interval: 10s
+      timeout: 5s
+      retries: 3
+      start_period: 5s

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "0.1.0",
+  "version": "1.0.2",
   "description": "CLI for Flowy — project management for AI coding agents",
   "type": "module",
   "bin": {
@@ -8,13 +8,21 @@
   },
   "files": [
     "src/",
+    "server/src/",
+    "server/package.json",
+    "server/Dockerfile",
+    "skills/",
+    "!skills/_artifacts",
+    "docker-compose.yml",
     "LICENSE",
     "README.md"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true,
+    "registry": "https://registry.npmjs.org/"
   },
-  "license": "AGPL-3.0-only",
+  "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/sqaoss/flowy.git"
@@ -33,24 +41,33 @@
     "coding-agent",
     "ai-agents",
     "graphql",
-    "bun"
+    "bun",
+    "tanstack-intent"
   ],
   "scripts": {
     "cli": "bun src/index.ts",
     "check": "biome check --write .",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "typecheck": "tsc --noEmit",
     "prepare": "husky"
   },
   "dependencies": {
-    "commander": "^14.0.3"
+    "@semantic-release/changelog": "6.0.3",
+    "@semantic-release/git": "10.0.1",
+    "commander": "^14.0.3",
+    "semantic-release": "25.0.3"
   },
   "devDependencies": {
     "@biomejs/biome": "2.4.4",
+    "@tanstack/intent": "^0.0.23",
     "@commitlint/cli": "^20.4.2",
     "@commitlint/config-conventional": "^20.4.2",
     "husky": "^9.1.7",
     "lint-staged": "^16.3.0",
-    "typescript": "^5"
+    "tdd-guard-vitest": "^0.1.6",
+    "typescript": "^5",
+    "vitest": "^4.1.2"
   },
   "lint-staged": {
     "*.{ts,tsx,js,jsx}": [

package/server/Dockerfile

@@ -0,0 +1,14 @@
+FROM oven/bun:1.3.11 AS base
+WORKDIR /app
+
+FROM base AS install
+COPY package.json bun.lock ./
+RUN bun install --frozen-lockfile --production
+
+FROM base
+COPY --from=install /app/node_modules node_modules
+COPY src src
+COPY tsconfig.json .
+
+EXPOSE 4000
+CMD ["bun", "src/index.ts"]

package/server/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@sqaoss/flowy-server",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "bun --watch src/index.ts",
+    "start": "bun src/index.ts",
+    "test": "bunx --bun vitest run",
+    "test:watch": "bunx --bun vitest",
+    "check": "biome check --write .",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "graphql": "16.13.2",
+    "graphql-yoga": "5.18.1",
+    "nanoid": "5.1.7"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.4",
+    "@types/bun": "^1.3.11",
+    "typescript": "^5",
+    "vitest": "^4.1.2"
+  }
+}

package/server/src/db.test.ts

@@ -0,0 +1,93 @@
+import { describe, expect, it } from 'vitest'
+import { createDb } from './db.ts'
+
+describe('createDb', () => {
+  it('creates nodes and edges tables', () => {
+    const db = createDb(':memory:')
+
+    const tables = db.raw
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='table' ORDER BY name",
+      )
+      .all()
+      .map((r) => r.name)
+
+    expect(tables).toContain('nodes')
+    expect(tables).toContain('edges')
+
+    db.close()
+  })
+
+  it('rejects invalid node type', () => {
+    const db = createDb(':memory:')
+
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title) VALUES ('n1', 'invalid_type', 'Test')",
+      ),
+    ).toThrow()
+
+    db.close()
+  })
+
+  it('rejects invalid status', () => {
+    const db = createDb(':memory:')
+
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO nodes (id, type, title, status) VALUES ('n1', 'project', 'Test', 'invalid_status')",
+      ),
+    ).toThrow()
+
+    db.close()
+  })
+
+  it('rejects invalid edge relation', () => {
+    const db = createDb(':memory:')
+
+    db.raw.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('n1', 'project', 'P1')",
+    )
+    db.raw.run(
+      "INSERT INTO nodes (id, type, title) VALUES ('n2', 'feature', 'F1')",
+    )
+
+    expect(() =>
+      db.raw.run(
+        "INSERT INTO edges (source_id, target_id, relation) VALUES ('n2', 'n1', 'invalid_rel')",
+      ),
+    ).toThrow()
+
+    db.close()
+  })
+
+  it('creates indexes on nodes and edges', () => {
+    const db = createDb(':memory:')
+
+    const indexes = db.raw
+      .query<{ name: string }, []>(
+        "SELECT name FROM sqlite_master WHERE type='index' AND name LIKE 'idx_%' ORDER BY name",
+      )
+      .all()
+      .map((r) => r.name)
+
+    expect(indexes).toContain('idx_nodes_type')
+    expect(indexes).toContain('idx_nodes_status')
+    expect(indexes).toContain('idx_edges_target')
+    expect(indexes).toContain('idx_edges_source')
+
+    db.close()
+  })
+
+  it('enables foreign keys', () => {
+    const db = createDb(':memory:')
+
+    const result = db.raw
+      .query<{ foreign_keys: number }, []>('PRAGMA foreign_keys')
+      .get()
+
+    expect(result?.foreign_keys).toBe(1)
+
+    db.close()
+  })
+})

package/server/src/db.ts

@@ -0,0 +1,47 @@
+import { Database } from 'bun:sqlite'
+
+export type FlowyDb = ReturnType<typeof createDb>
+
+export function createDb(path: string) {
+  const db = new Database(path)
+
+  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)',
+  )
+
+  return {
+    raw: db,
+    close: () => db.close(),
+  }
+}

package/server/src/index.test.ts

@@ -0,0 +1,25 @@
+import { afterEach, describe, expect, it } from 'vitest'
+import { createServer } from './index.ts'
+
+describe('createServer', () => {
+  let instance: ReturnType<typeof createServer> | undefined
+
+  afterEach(() => {
+    instance?.close()
+    instance = undefined
+  })
+
+  it('exports a createServer function', () => {
+    expect(typeof createServer).toBe('function')
+  })
+
+  it('responds to /health with status ok', async () => {
+    instance = createServer({ dbPath: ':memory:', port: 0 })
+
+    const res = await fetch(`http://localhost:${instance.port}/health`)
+    const json = await res.json()
+
+    expect(res.status).toBe(200)
+    expect(json).toEqual({ status: 'ok' })
+  })
+})

package/server/src/index.ts

@@ -0,0 +1,45 @@
+import { createSchema, createYoga } from 'graphql-yoga'
+import { createDb } from './db.ts'
+import { createResolvers } from './resolvers.ts'
+import { typeDefs } from './schema.ts'
+
+export function createServer(opts?: { dbPath?: string; port?: number }) {
+  const dbPath = opts?.dbPath ?? process.env.FLOWY_DB_PATH ?? './flowy.sqlite'
+  const port = opts?.port ?? Number(process.env.PORT ?? 4000)
+
+  const db = createDb(dbPath)
+  const resolvers = createResolvers(db)
+
+  const yoga = createYoga({
+    schema: createSchema({ typeDefs, resolvers }),
+    graphqlEndpoint: '/graphql',
+  })
+
+  const server = Bun.serve({
+    port,
+    fetch(req) {
+      const url = new URL(req.url)
+      if (url.pathname === '/health' && req.method === 'GET') {
+        return Response.json({ status: 'ok' })
+      }
+      return yoga.fetch(req)
+    },
+  })
+
+  return {
+    server,
+    port: server.port,
+    db,
+    close() {
+      server.stop()
+      db.close()
+    },
+  }
+}
+
+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`)
+}