@sqaoss/flowy 0.1.1 → 1.1.0

package/README.md

@@ -1,81 +1,64 @@
 # Flowy
 
-CLI for Flowy — project management for AI coding agents.
+Agentic persistent planning
 
 [![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)
 
-> **Note:** Registration is temporarily closed while the project is in rapid development. Existing users are unaffected.
+Jira, Linear, Trello are built for humans clicking boards. AI agents don't click boards. When your agent needs to plan work, track progress, and close tickets, those tools add friction, load context, and get in the way.
 
-## What is Flowy
+Flowy is where agents store plans and flow through execution. Features are master plans. Tasks are execution steps. Everything persists in a database, not as files cluttering your git history. Your agent flows through work without friction.
 
-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.
+You get full observability on what every agent planned, built, and shipped.
 
-## Quick Start
+## Get Started
+
+### Install (once)
 
 ```bash
-# Install
-bun add -g @sqaoss/flowy    # or: npm i -g @sqaoss/flowy
+npm i -g @sqaoss/flowy
+flowy setup remote --email you@example.com
+```
 
-# Register and get your API key
-flowy register --email you@example.com
-export FLOWY_API_KEY=flowy_xxx_yyy
+### Initialize a project
 
-# Create a project
-flowy node create --type project --title "Auth System"
+```bash
+cd my-project
+flowy init           # auto-detects repo, creates project
+```
 
-# Add tasks
-flowy node create --type task --title "Implement OAuth"
-flowy node create --type task --title "Write auth tests"
+### Start planning
 
-# Link tasks to project
-flowy edge create --source <task-id> --target <project-id> --relation part_of
+```bash
+flowy feature create --title "User Auth" --description auth-spec.md
+flowy feature set "User Auth"
+
+flowy task create --title "Implement OAuth" --description oauth.md
+flowy task create --title "Write tests" --description "Unit + integration"
 
-# Track status
 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
 ```
 
-## Command Reference
+Every command outputs JSON. Your agent reads it, acts on it, moves to the next task.
 
-| Command | Description |
-|---------|-------------|
-| `register --email <email>` | Register and get API key |
-| `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 |
-| `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 |
+## Agent Skill
 
-All commands output JSON.
+Flowy installs an agent skill during setup. Your AI agent automatically knows every command. No manual configuration needed.
 
-## Data Model
+Or install the skill manually: `npx skills add sqaoss/flowy`
 
-### Node Types
+See [skills/using-flowy/SKILL.md](skills/using-flowy/SKILL.md) for the full skill reference.
 
-`client`, `project`, `feature`, `epic`, `task`
+## Data Model
 
-### Edge Relations
+```
+project -> feature -> task
+  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 task belongs to a feature. Every feature belongs to a project. No orphans.
 
 ### Status Flow
 
@@ -83,17 +66,68 @@ All commands output JSON.
 draft -> pending_review -> approved -> in_progress -> done
 ```
 
-Also: `blocked`, `cancelled`
+Also: `blocked`, `cancelled`. Only `pending_review` entities can be approved.
+
+## Self-Hosted
+
+Run Flowy on your own machine with SQLite and Docker. Same CLI, same commands.
+
+```bash
+flowy setup local    # starts a local server via Docker
+flowy init           # auto-detects repo
+```
+
+## Command Reference
+
+| Command | Description |
+|---------|-------------|
+| `setup remote --email <email>` | Register and connect to the hosted server |
+| `setup local` | Start a local Docker server and configure the CLI |
+| `init` | Auto-detect repo and create/map project |
+| `whoami` | Show current user |
+| `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 (must be pending_review) |
+| `search <query> [--type] [--status] [--limit]` | Full-text search |
+| `tree <id> [--depth N]` | Show subtree |
+
+All commands output JSON to stdout.
 
 ## 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_KEY` | API key (remote mode) | -- |
+| `FLOWY_PROJECT` | Override active project by name | -- |
+| `FLOWY_FEATURE` | Override active feature by ID | -- |
 
-## License
+## Development
 
-Copyright (C) 2026 SQA & Automation SRL
+```bash
+bun run test          # CLI tests
+bun run check         # Lint + format
+bun run typecheck     # TypeScript
+
+cd server && bunx --bun vitest run   # Server tests
+```
+
+## 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,20 +1,28 @@
 {
   "name": "@sqaoss/flowy",
-  "version": "0.1.1",
-  "description": "CLI for Flowy — project management for AI coding agents. NOTE: Registration is temporarily closed while in rapid development.",
+  "version": "1.1.0",
+  "description": "Agentic persistent planning",
   "type": "module",
   "bin": {
     "flowy": "./src/index.ts"
   },
   "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,16 +41,23 @@
     "coding-agent",
     "ai-agents",
     "graphql",
-    "bun"
+    "bun",
+    "agentic",
+    "planning"
   ],
   "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",
@@ -50,7 +65,9 @@
     "@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`)
+}