@andypai/agent-kanban 0.7.0 → 0.8.1

package/README.md

@@ -20,11 +20,12 @@ That buys you a few things that are easy to miss at first:
 
 ## Documentation
 
-- [`docs/readme.md`](docs/readme.md) for the documentation index
-- [`docs/workflow.md`](docs/workflow.md) for a common day-to-day workflow
-- [`docs/mcp.md`](docs/mcp.md) for the reusable tracker MCP module
-- [`docs/providers/linear.md`](docs/providers/linear.md) for Linear provider details
-- [`docs/providers/jira.md`](docs/providers/jira.md) for Jira provider details
+- [`docs/INDEX.md`](https://github.com/abpai/agent-kanban/blob/main/docs/INDEX.md) for the documentation index
+- [`docs/SPEC_CONTRACT.md`](https://github.com/abpai/agent-kanban/blob/main/docs/SPEC_CONTRACT.md) for the repo proof menu and spec contract
+- [`docs/workflow.md`](https://github.com/abpai/agent-kanban/blob/main/docs/workflow.md) for a common day-to-day workflow
+- [`docs/mcp.md`](https://github.com/abpai/agent-kanban/blob/main/docs/mcp.md) for the reusable tracker MCP module
+- [`docs/providers/linear.md`](https://github.com/abpai/agent-kanban/blob/main/docs/providers/linear.md) for Linear provider details
+- [`docs/providers/jira.md`](https://github.com/abpai/agent-kanban/blob/main/docs/providers/jira.md) for Jira provider details
 - [`SKILL.md`](SKILL.md) for agent-specific repo usage instructions
 
 ## Install
@@ -176,6 +177,8 @@ Default columns: `recurring`, `backlog`, `in-progress`, `review`, `done`.
 | `-p <level>`       | Priority: `low`, `medium`, `high`, `urgent` (default: `medium`) |
 | `-a <user>`        | Assignee                                                        |
 | `--project <name>` | Project tag                                                     |
+| `--label <name>`   | Label; repeatable and comma-separated values are accepted       |
+| `--labels <names>` | Label alias; repeatable and comma-separated values are accepted |
 | `-m <json>`        | Arbitrary metadata (must be valid JSON)                         |
 
 **Flags for `task list`:**
@@ -269,14 +272,18 @@ compatibility. To require authentication, set a token via `--token` or the
   accepts `?token=<token>` instead.
 - `/api/health` stays public (liveness probe).
 - `/api/webhooks/*` are **not** covered by this token — they authenticate with
-  the provider webhook secret (e.g. `JIRA_WEBHOOK_SECRET`).
+  the provider webhook secret when one is configured. Without that secret,
+  Linear/Jira webhooks run in local open dev mode and accept unsigned payloads.
 - The bundled UI picks the token up once from `?token=` / `#token=` and stores
   it in `localStorage`, so you can open `https://<host>/?token=<token>`.
 
 `--tunnel` exposes the dashboard publicly, so it **refuses to start without a
-token**. CORS is off by default (same-origin); set `KANBAN_ALLOWED_ORIGIN` (or
-`--allowed-origin`) to allow a specific cross-origin browser client. CORS is
-origin hygiene, not an auth control — the token is the security boundary.
+token**. In Linear or Jira mode it also refuses to start unless the matching
+webhook secret is set, so auth-exempt webhook routes cannot accept unsigned
+public writes. CORS is off by default (same-origin); set
+`KANBAN_ALLOWED_ORIGIN` (or `--allowed-origin`) to allow a specific cross-origin
+browser client. CORS is origin hygiene, not an auth control — the token is the
+security boundary.
 
 ### mcp
 
@@ -286,7 +293,8 @@ kanban mcp --db /path/to/board.db
 ```
 
 Runs the bundled MCP server over stdio for local MCP clients such as Claude
-Desktop. See [`docs/mcp.md`](docs/mcp.md) for the tool surface and caveats.
+Desktop. See [`docs/mcp.md`](https://github.com/abpai/agent-kanban/blob/main/docs/mcp.md)
+for the tool surface and caveats.
 
 ## Global flags
 
@@ -350,7 +358,8 @@ There are two ways to use it today:
 - run `kanban mcp` for a bundled stdio MCP server
 - import the helpers in `src/mcp/` from a sibling workspace or in-repo consumer
 
-See [`docs/mcp.md`](docs/mcp.md) for the current default tool set, the auth and
+See [`docs/mcp.md`](https://github.com/abpai/agent-kanban/blob/main/docs/mcp.md)
+for the current default tool set, the auth and
 policy model, and the caveats around source-level imports and `kanban serve`.
 
 ## Scripts
@@ -435,7 +444,8 @@ If you want to contribute or report an issue, start with these guides:
 - [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md)
 - [SECURITY.md](SECURITY.md)
 
-Longer product and workflow docs live under [`docs/`](docs/readme.md).
+Longer product and workflow docs live under
+[`docs/`](https://github.com/abpai/agent-kanban/blob/main/docs/readme.md).
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.7.0",
+  "version": "0.8.1",
   "description": "Agent-friendly kanban board CLI. Manage tasks via bash commands, parse structured JSON output.",
   "homepage": "https://github.com/abpai/agent-kanban#readme",
   "repository": {
@@ -45,6 +45,8 @@
     "access": "public"
   },
   "scripts": {
+    "bootstrap": "bun install && cd ui && bun install",
+    "smoke": "bun src/index.ts --help",
     "dev": "bun --watch src/index.ts",
     "start": "bun src/index.ts",
     "build": "bun build ./src/index.ts --target bun --outdir ./dist",
@@ -56,6 +58,10 @@
     "check": "bun run lint && bun run typecheck && bun run ui:typecheck",
     "test": "bun test",
     "test:watch": "bun test --watch",
+    "knip": "knip",
+    "test:pg": "DATABASE_URL=${DATABASE_URL:-postgres://postgres:postgres@localhost:${KANBAN_PG_PORT:-5432}/kanban_test} bun test",
+    "pg:up": "docker compose -f docker-compose.postgres.yml up -d --wait",
+    "pg:down": "docker compose -f docker-compose.postgres.yml down -v",
     "seed:test": "bun --env-file=.env.test scripts/seed-test-db.ts",
     "serve": "bun src/index.ts serve",
     "ui:dev": "cd ui && bun run dev",
@@ -83,6 +89,7 @@
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-prettier": "^5.5.4",
     "husky": "^8.0.3",
+    "knip": "^6.24.0",
     "lint-staged": "^15.2.0",
     "prettier": "^3.7.4",
     "typescript": "^5.7.2"

package/src/__tests__/api.test.ts

@@ -1,6 +1,10 @@
 import { beforeEach, describe, expect, test } from 'bun:test'
 import { Database } from 'bun:sqlite'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { initSchema, seedDefaultColumns, addTask } from '../db'
+import { KanbanError, ErrorCode } from '../errors'
 import { handleRequest } from '../api'
 import { createProvider } from '../providers/index'
 import type { KanbanProvider } from '../providers/types'
@@ -223,4 +227,220 @@ describe('handleRequest', () => {
     expect(body.data.provider).toBe('local')
     expect(body.data.capabilities.taskDelete).toBe(true)
   })
+
+  test('F22: GET /api/activity returns an ok envelope wrapping an array', async () => {
+    addTask(db, 'Generates activity')
+    const req = new Request('http://localhost/api/activity?limit=5', { method: 'GET' })
+    const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as { ok: boolean; data: unknown[] }
+    expect(result.response.status).toBe(200)
+    expect(result.mutated).toBe(false)
+    expect(body.ok).toBe(true)
+    expect(Array.isArray(body.data)).toBe(true)
+  })
+
+  test('F22: GET /api/activity rejects an invalid limit through the envelope', async () => {
+    const req = new Request('http://localhost/api/activity?limit=0', { method: 'GET' })
+    const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(400)
+    expect(body.error.code).toBe('INVALID_ARGUMENT')
+  })
+
+  test('F23: GET /api/metrics returns the metrics envelope', async () => {
+    const req = new Request('http://localhost/api/metrics', { method: 'GET' })
+    const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as {
+      ok: boolean
+      data: { totalTasks: number; tasksByColumn: unknown[] }
+    }
+    expect(result.response.status).toBe(200)
+    expect(result.mutated).toBe(false)
+    expect(body.ok).toBe(true)
+    expect(typeof body.data.totalTasks).toBe('number')
+    expect(Array.isArray(body.data.tasksByColumn)).toBe(true)
+  })
+
+  test('F24: GET /api/config returns config', async () => {
+    const getReq = new Request('http://localhost/api/config', { method: 'GET' })
+    const getRes = await handleRequest(provider, getReq)
+    const getBody = (await getRes.response.json()) as { ok: boolean; data: { provider: string } }
+    expect(getRes.response.status).toBe(200)
+    expect(getRes.mutated).toBe(false)
+    expect(getBody.data.provider).toBe('local')
+  })
+
+  test('F24: PATCH /api/config mutates without a precise WsEvent', async () => {
+    // PATCH persists the config sidecar (config.json) next to the db path, so use
+    // a hermetic temp dir instead of the shared ':memory:' provider, which would
+    // write ./config.json into the checkout.
+    const dir = mkdtempSync(join(tmpdir(), 'kanban-api-config-'))
+    const cfgDb = new Database(':memory:')
+    cfgDb.run('PRAGMA foreign_keys = ON')
+    initSchema(cfgDb)
+    seedDefaultColumns(cfgDb)
+    const cfgProvider = createProvider(cfgDb, { provider: 'local' }, join(dir, 'board.db'))
+    try {
+      const patchReq = new Request('http://localhost/api/config', {
+        method: 'PATCH',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ members: [{ name: 'alice', role: 'human' }] }),
+      })
+      const patchRes = await handleRequest(cfgProvider, patchReq)
+      const patchBody = (await patchRes.response.json()) as {
+        ok: boolean
+        data: { members: { name: string }[] }
+      }
+      expect(patchRes.response.status).toBe(200)
+      expect(patchRes.mutated).toBe(true)
+      // No precise WsEvent → the server falls back to a 'refresh' broadcast.
+      expect(patchRes.event).toBeUndefined()
+      expect(patchBody.data.members.map((m) => m.name)).toContain('alice')
+    } finally {
+      cfgDb.close()
+      rmSync(dir, { recursive: true, force: true })
+    }
+  })
+})
+
+// Minimal provider whose only relevant field is `type` plus an overridable
+// handleWebhook — the webhook branch of handleRequest is the surface under test.
+function webhookProvider(
+  type: string,
+  handleWebhook?: KanbanProvider['handleWebhook'],
+): KanbanProvider {
+  const p: Partial<KanbanProvider> = { type: type as KanbanProvider['type'] }
+  if (handleWebhook) p.handleWebhook = handleWebhook
+  return p as KanbanProvider
+}
+
+function webhookRequest(target: string): Request {
+  return new Request(`http://localhost/api/webhooks/${target}`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: '{}',
+  })
+}
+
+describe('handleRequest webhook route (F25)', () => {
+  test('target that does not match the active provider → 400 UNSUPPORTED_OPERATION, not mutated', async () => {
+    const result = await handleRequest(
+      webhookProvider('local', async () => ({ handled: true })),
+      webhookRequest('jira'),
+    )
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(400)
+    expect(result.mutated).toBe(false)
+    expect(body.error.code).toBe('UNSUPPORTED_OPERATION')
+  })
+
+  test('provider without handleWebhook → 400 UNSUPPORTED_OPERATION', async () => {
+    const result = await handleRequest(webhookProvider('local'), webhookRequest('local'))
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(400)
+    expect(result.mutated).toBe(false)
+    expect(body.error.code).toBe('UNSUPPORTED_OPERATION')
+  })
+
+  test('unauthorized result → 401 PROVIDER_AUTH_FAILED, not mutated', async () => {
+    const result = await handleRequest(
+      webhookProvider('local', async () => ({ handled: false, unauthorized: true })),
+      webhookRequest('local'),
+    )
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(401)
+    expect(result.mutated).toBe(false)
+    expect(body.error.code).toBe('PROVIDER_AUTH_FAILED')
+  })
+
+  test('handled result → 200, mutated true', async () => {
+    const result = await handleRequest(
+      webhookProvider('local', async () => ({ handled: true, message: 'ok' })),
+      webhookRequest('local'),
+    )
+    const body = (await result.response.json()) as { ok: boolean; data: { handled: boolean } }
+    expect(result.response.status).toBe(200)
+    expect(result.mutated).toBe(true)
+    expect(body.data.handled).toBe(true)
+  })
+
+  test('skipped (handled:false) result → 200, NOT mutated (no broadcast)', async () => {
+    const result = await handleRequest(
+      webhookProvider('local', async () => ({ handled: false, message: 'ignored' })),
+      webhookRequest('local'),
+    )
+    expect(result.response.status).toBe(200)
+    expect(result.mutated).toBe(false)
+  })
+})
+
+describe('handleRequest webhook route error containment (F55 regression)', () => {
+  test('a throwing handleWebhook is enveloped as 500 INTERNAL_ERROR, never escapes as a rejection', async () => {
+    const provider = webhookProvider('local', async () => {
+      throw new Error('boom from provider.handleWebhook')
+    })
+    // Must NOT reject — before the fix this threw out of handleRequest.
+    const result = await handleRequest(provider, webhookRequest('local'))
+    const body = (await result.response.json()) as {
+      ok: boolean
+      error: { code: string; message: string }
+    }
+    expect(result.response.status).toBe(500)
+    expect(result.mutated).toBe(false)
+    expect(body.ok).toBe(false)
+    expect(body.error.code).toBe('INTERNAL_ERROR')
+    expect(body.error.message).toContain('boom')
+  })
+
+  test('a thrown KanbanError keeps its mapped status + code through the envelope', async () => {
+    const provider = webhookProvider('local', async () => {
+      throw new KanbanError(ErrorCode.CONFLICT, 'version conflict during webhook apply')
+    })
+    const result = await handleRequest(provider, webhookRequest('local'))
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(409)
+    expect(result.mutated).toBe(false)
+    expect(body.error.code).toBe('CONFLICT')
+  })
+})
+
+describe('handleRequest malformed path encoding (D2 regression)', () => {
+  test('malformed %-encoding in a task id → 400 INVALID_ARGUMENT, never thrown', async () => {
+    const req = new Request('http://localhost/api/tasks/%E0%A4%A', { method: 'GET' })
+    // Must not reject — before the fix decodeURIComponent threw a URIError that
+    // escaped handleRequest.
+    const result = await handleRequest(provider, req)
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(400)
+    expect(result.mutated).toBe(false)
+    expect(body.error.code).toBe('INVALID_ARGUMENT')
+  })
+
+  test('malformed %-encoding in a webhook target → 400 INVALID_ARGUMENT', async () => {
+    const result = await handleRequest(webhookProvider('local'), webhookRequest('%E0%A4%A'))
+    const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+    expect(result.response.status).toBe(400)
+    expect(result.mutated).toBe(false)
+    expect(body.error.code).toBe('INVALID_ARGUMENT')
+  })
+})
+
+describe('statusForCode server-side mapping (D3 regression)', () => {
+  const cases: { code: keyof typeof ErrorCode; status: number }[] = [
+    { code: 'PROVIDER_UPSTREAM_ERROR', status: 502 },
+    { code: 'PROVIDER_SYNC_REQUIRED', status: 503 },
+    { code: 'INTERNAL_ERROR', status: 500 },
+  ]
+  for (const { code, status } of cases) {
+    test(`${code} → ${status} (not the default 400)`, async () => {
+      const provider = webhookProvider('local', async () => {
+        throw new KanbanError(ErrorCode[code], `${code} from provider`)
+      })
+      const result = await handleRequest(provider, webhookRequest('local'))
+      const body = (await result.response.json()) as { ok: boolean; error: { code: string } }
+      expect(result.response.status).toBe(status)
+      expect(body.error.code).toBe(code)
+      expect(result.mutated).toBe(false)
+    })
+  }
 })