@andypai/agent-kanban 0.8.0 → 0.9.0

package/README.md

@@ -20,7 +20,8 @@ That buys you a few things that are easy to miss at first:
 
 ## Documentation
 
-- [`docs/readme.md`](https://github.com/abpai/agent-kanban/blob/main/docs/readme.md) for the documentation index
+- [`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
@@ -271,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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@andypai/agent-kanban",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "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__/webhooks.test.ts

@@ -6,6 +6,7 @@ import {
   headerLower,
   verifyHmacSha256,
   verifySha256HmacSignatureHeader,
+  webhookSignatureStatus,
 } from '../webhooks'
 import { JiraProvider, type JiraProviderConfig } from '../providers/jira'
 import { JiraClient } from '../providers/jira-client'
@@ -98,7 +99,12 @@ describe('authorizeWebhook (F32)', () => {
       signature: 'deadbeef',
       verify,
     })
-    expect(result).toEqual({ handled: false, unauthorized: true, message: 'Invalid signature' })
+    expect(result).toEqual({
+      handled: false,
+      unauthorized: true,
+      message: 'Invalid signature',
+      signatureStatus: 'invalid',
+    })
   })
 })
 
@@ -792,3 +798,46 @@ describe('webhook open dev mode when secret is unset', () => {
     }
   })
 })
+
+describe('webhookSignatureStatus', () => {
+  const verify = verifySha256HmacSignatureHeader
+  const body = '{"hello":"world"}'
+
+  test('no secret configured -> not_configured', () => {
+    expect(
+      webhookSignatureStatus({ secret: undefined, rawBody: body, signature: null, verify }),
+    ).toBe('not_configured')
+  })
+
+  test('secret configured, no signature header -> missing', () => {
+    expect(webhookSignatureStatus({ secret: 's3', rawBody: body, signature: null, verify })).toBe(
+      'missing',
+    )
+  })
+
+  test('bad signature -> invalid; good signature -> valid', () => {
+    expect(
+      webhookSignatureStatus({ secret: 's3', rawBody: body, signature: 'sha256=nope', verify }),
+    ).toBe('invalid')
+    expect(
+      webhookSignatureStatus({
+        secret: 's3',
+        rawBody: body,
+        signature: `sha256=${hmac('s3', body)}`,
+        verify,
+      }),
+    ).toBe('valid')
+  })
+
+  test('authorizeWebhook rejections carry the verdict', () => {
+    const rejected = authorizeWebhook({
+      secret: 's3',
+      rawBody: body,
+      signature: 'sha256=nope',
+      verify,
+    })
+    expect(rejected?.signatureStatus).toBe('invalid')
+    const noHeader = authorizeWebhook({ secret: 's3', rawBody: body, signature: null, verify })
+    expect(noHeader?.signatureStatus).toBe('missing')
+  })
+})

package/src/api.ts

@@ -5,7 +5,7 @@ import { parsePositiveInt } from './transport-input'
 import { success } from './output'
 import { normalizeCreateTaskInput } from './use-cases'
 
-export type WsEvent =
+type WsEvent =
   | { type: 'task:upsert'; task: Task; columnId: string }
   | { type: 'task:delete'; id: string }
   // Fallback when a mutation has no precise event; the UI does a full refresh.

package/src/mcp/index.ts

@@ -1,13 +1,5 @@
 export { createTrackerCore } from './core'
 export { createTrackerMcpServer } from './server'
-export { TrackerMcpError, type TrackerMcpErrorCode } from './errors'
-export type { TrackerCore } from './core'
-export type {
-  TrackerMcpAuthResolver,
-  TrackerMcpHooks,
-  TrackerMcpPolicy,
-  TrackerMcpServer,
-  TrackerMcpTool,
-  TrackerMcpToolHandlerContext,
-} from './types'
+export { TrackerMcpError } from './errors'
+export type { TrackerMcpPolicy, TrackerMcpTool } from './types'
 export { defaultTools } from './server'

package/src/mcp/types.ts

@@ -61,7 +61,7 @@ export interface TrackerMcpHooks<TScope> {
   }): Promise<void> | void
 }
 
-export interface TrackerMcpToolHandlerContext<TScope, TArgs = Record<string, unknown>> {
+interface TrackerMcpToolHandlerContext<TScope, TArgs = Record<string, unknown>> {
   scope: TScope
   args: TArgs
   request?: Request

package/src/metrics-spec.ts

@@ -14,7 +14,7 @@ import {
 const PRIORITY_RANK: Record<string, number> = { urgent: 0, high: 1, medium: 2, low: 3 }
 
 /** A column plus how many tasks currently sit in it. */
-export interface MetricsColumnCount extends ClassifiableColumn {
+interface MetricsColumnCount extends ClassifiableColumn {
   count: number
 }
 

package/src/providers/jira-adf.ts

@@ -17,18 +17,18 @@ export interface AdfDocument {
   content: AdfBlockNode[]
 }
 
-export interface AdfMark {
+interface AdfMark {
   type: string
   attrs?: Record<string, unknown>
 }
 
-export interface AdfTextNode {
+interface AdfTextNode {
   type: 'text'
   text: string
   marks?: AdfMark[]
 }
 
-export interface AdfUnknownInlineNode {
+interface AdfUnknownInlineNode {
   type: string
   [key: string]: unknown
 }
@@ -40,7 +40,7 @@ export interface AdfParagraphNode {
   content?: AdfInlineNode[]
 }
 
-export interface AdfListItemNode {
+interface AdfListItemNode {
   type: 'listItem'
   content: AdfBlockNode[]
 }
@@ -50,7 +50,7 @@ export interface AdfBulletListNode {
   content: AdfListItemNode[]
 }
 
-export interface AdfOrderedListNode {
+interface AdfOrderedListNode {
   type: 'orderedList'
   content: AdfListItemNode[]
   attrs?: { order?: number }
@@ -62,7 +62,7 @@ export interface AdfCodeBlockNode {
   content?: AdfInlineNode[]
 }
 
-export interface AdfHeadingNode {
+interface AdfHeadingNode {
   type: 'heading'
   attrs: { level: number }
   content?: AdfInlineNode[]
@@ -74,12 +74,12 @@ export interface AdfExpandNode {
   content: AdfBlockNode[]
 }
 
-export interface AdfUnknownBlockNode {
+interface AdfUnknownBlockNode {
   type: string
   [key: string]: unknown
 }
 
-export type AdfBlockNode =
+type AdfBlockNode =
   | AdfParagraphNode
   | AdfBulletListNode
   | AdfOrderedListNode
@@ -88,9 +88,6 @@ export type AdfBlockNode =
   | AdfExpandNode
   | AdfUnknownBlockNode
 
-// Public AdfNode union covers every node shape this module recognizes.
-export type AdfNode = AdfDocument | AdfBlockNode | AdfListItemNode | AdfInlineNode
-
 const BULLET_MARKER = /^[-*] (.*)$/
 const ORDERED_MARKER = /^(\d+)\. (.*)$/
 // Opening/closing fence: `` ``` `` optionally followed by a language tag with

package/src/providers/jira-client.ts

@@ -168,7 +168,7 @@ export interface JiraIssueType {
   name: string
 }
 
-export interface JiraChangelogItem {
+interface JiraChangelogItem {
   field: string
   fieldtype?: string
   fromString?: string | null
@@ -177,7 +177,7 @@ export interface JiraChangelogItem {
   to?: string | null
 }
 
-export interface JiraChangelogEntry {
+interface JiraChangelogEntry {
   id: string
   author?: { accountId?: string; displayName?: string }
   created: string

package/src/providers/jira-core.ts

@@ -13,6 +13,7 @@ import type {
 } from '../types'
 import {
   authorizeWebhook,
+  webhookSignatureStatus,
   headerLower,
   verifySha256HmacSignatureHeader,
   type WebhookRequest,
@@ -51,9 +52,9 @@ import { WEBHOOK_SECRET_ENV, webhookSecretFromEnv } from '../tracker-config'
 import { warnOnce } from './warn-once'
 import { applyTaskFilters, forEachWithConcurrency, SyncGate, syncStatusFromMeta } from './sync-core'
 
-export const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
+const FULL_RECONCILE_INTERVAL_MS = 5 * 60_000
 
-export function shouldRunFullReconcile(lastFullSyncAt: string | null, now: number): boolean {
+function shouldRunFullReconcile(lastFullSyncAt: string | null, now: number): boolean {
   if (!lastFullSyncAt) return true
   const lastFullSyncAtMs = Date.parse(lastFullSyncAt)
   if (!Number.isFinite(lastFullSyncAtMs)) return true
@@ -64,7 +65,7 @@ export function shouldRunFullReconcile(lastFullSyncAt: string | null, now: numbe
 // priorities; the write path looks up the resolved name (case-insensitive)
 // in the cached `jira_priorities` table, so renames that preserve the default
 // casing still resolve.
-export const CANONICAL_TO_JIRA_DEFAULT: Record<Priority, string> = {
+const CANONICAL_TO_JIRA_DEFAULT: Record<Priority, string> = {
   urgent: 'Highest',
   high: 'High',
   medium: 'Medium',
@@ -368,8 +369,8 @@ export class JiraProviderCore implements KanbanProvider {
         }
       }
 
-      // Fetch changelog per changed issue so the poll-based
-      // `moved` trigger in @garage/dispatch works. Server-side dedupe
+      // Fetch changelog per changed issue so a downstream consumer's
+      // poll-based `moved` trigger works. Server-side dedupe
       // keyed on (issue_id, history_id, item_field) keeps this cheap
       // even if the same issue is updated repeatedly.
       await forEachWithConcurrency(page.issues, 5, async (issue) => {
@@ -884,36 +885,47 @@ export class JiraProviderCore implements KanbanProvider {
         `[jira] ${WEBHOOK_SECRET_ENV['jira']} is not set — accepting webhook without signature verification (open dev mode)`,
       )
     }
+    const signature = headerLower(payload.headers, 'x-hub-signature')
+    const signatureStatus = webhookSignatureStatus({
+      secret,
+      rawBody: payload.rawBody,
+      signature,
+      verify: verifySha256HmacSignatureHeader,
+    })
     const auth = authorizeWebhook({
       secret,
       rawBody: payload.rawBody,
-      signature: headerLower(payload.headers, 'x-hub-signature'),
+      signature,
       verify: verifySha256HmacSignatureHeader,
     })
-    if (auth) return auth
+    if (auth) return { ...auth, signatureStatus }
+    const attachVerdict = (result: WebhookResult): WebhookResult => ({
+      ...result,
+      signatureStatus,
+    })
     let body: { webhookEvent?: string; issue?: JiraIssue } = {}
     try {
       body = JSON.parse(payload.rawBody) as typeof body
     } catch {
-      return { handled: false, message: 'Invalid JSON body' }
+      return attachVerdict({ handled: false, message: 'Invalid JSON body' })
     }
     const event = body.webhookEvent ?? ''
     const issue = body.issue
-    if (!issue) return { handled: false, message: `No issue in payload (${event})` }
+    if (!issue) return attachVerdict({ handled: false, message: `No issue in payload (${event})` })
 
     if (event === 'jira:issue_deleted') {
       await this.cache.deleteIssue(issue.id)
       await this.cache.saveSyncMeta({ lastWebhookAt: new Date().toISOString() })
-      return { handled: true }
+      return attachVerdict({ handled: true })
     }
 
     if (event === 'jira:issue_created' || event === 'jira:issue_updated') {
       const projectKey = issue.fields.project?.key
       if (projectKey !== this.config.projectKey) {
-        return {
+        return attachVerdict({
           handled: false,
           message: `Ignoring issue from project '${projectKey ?? 'unknown'}'`,
-        }
+        })
       }
       await this.cache.upsertIssues([
         toCacheIssue(issue, this.config.baseUrl, this.config.projectKey),
@@ -924,9 +936,9 @@ export class JiraProviderCore implements KanbanProvider {
         })
       }
       await this.cache.saveSyncMeta({ lastWebhookAt: new Date().toISOString() })
-      return { handled: true }
+      return attachVerdict({ handled: true })
     }
 
-    return { handled: false, message: `Unsupported event: ${event}` }
+    return attachVerdict({ handled: false, message: `Unsupported event: ${event}` })
   }
 }

package/src/providers/linear-cache.ts

@@ -316,10 +316,10 @@ export function upsertProjects(
 }
 
 // Bound per-value storage so repeated edits to a long description can't balloon the cache.
-// Exported and shared with the Postgres cache (postgres-linear-cache.ts) so both
-// backends clamp identically and the truncation marker can't drift between them.
-export const ACTIVITY_VALUE_MAX_CHARS = 4096
-export const ACTIVITY_TRUNCATION_SUFFIX = '…[truncated]'
+// clampActivityValue is shared with the Postgres cache (postgres-linear-cache.ts)
+// so both backends clamp identically and the truncation marker can't drift.
+const ACTIVITY_VALUE_MAX_CHARS = 4096
+const ACTIVITY_TRUNCATION_SUFFIX = '…[truncated]'
 const ACTIVITY_VALUE_BUDGET = ACTIVITY_VALUE_MAX_CHARS - ACTIVITY_TRUNCATION_SUFFIX.length
 
 export function clampActivityValue(value: string): string {

package/src/providers/linear-client.ts

@@ -694,7 +694,7 @@ export async function resolveLabelIdsForCreate(
   return resolveLinearLabelIds(inputLabels, await client.listIssueLabels())
 }
 
-export function resolveLinearLabelIds(
+function resolveLinearLabelIds(
   inputLabels: string[] | undefined,
   availableLabels: LinearIssueLabel[],
 ): string[] | undefined {

package/src/providers/postgres-linear-cache.ts

@@ -15,7 +15,7 @@ import { parseProviderTeamInfo } from './team-info'
 
 export type { LinearActivityRow, LinearStateRow, LinearSyncMeta } from './linear-cache'
 
-export type LinearIssueRow = LinearTaskRow
+type LinearIssueRow = LinearTaskRow
 
 /**
  * Postgres-backed cache/repository for the Linear provider. Mirrors the role of

package/src/storage-config.ts

@@ -1,13 +1,11 @@
 import { getDbPath } from './db'
 
-export type KanbanStorageMode = 'sqlite' | 'postgres'
-
-export interface SqliteKanbanStorageConfig {
+interface SqliteKanbanStorageConfig {
   mode: 'sqlite'
   sqlitePath: string
 }
 
-export interface PostgresKanbanStorageConfig {
+interface PostgresKanbanStorageConfig {
   mode: 'postgres'
   databaseUrl: string
 }

package/src/tracker-config.ts

@@ -62,14 +62,14 @@ export interface LocalTrackerConfig {
   syncIntervalMs?: number
 }
 
-export interface LinearTrackerConfig {
+interface LinearTrackerConfig {
   provider: 'linear'
   apiKey: string
   teamId: string
   syncIntervalMs?: number
 }
 
-export interface JiraTrackerConfig {
+interface JiraTrackerConfig {
   provider: 'jira'
   baseUrl: string
   email: string

package/src/webhook-events.ts

@@ -1,8 +1,9 @@
 /**
  * `webhook_events` — a small, generically-named receipts table that the Postgres
  * providers append to on every received webhook. It is *not* used by agent-kanban
- * itself; it exists so an external consumer (Garage Band's Studio "Webhooks"
- * panel) can show "did the sidecar receive/process a tracker webhook, and when".
+ * itself; it exists so an external consumer (for example a software factory's
+ * dashboard "Webhooks" panel) can show "did the sidecar receive/process a
+ * tracker webhook, and when".
  *
  * Ownership: agent-kanban owns and creates this table; consumers read it
  * read-only. Columns a consumer can rely on:
@@ -94,6 +95,9 @@ export async function withWebhookRecording(
     provider,
     ...meta,
     status: webhookEventStatus(result),
+    ...(result.signatureStatus === undefined
+      ? {}
+      : { detail: { signatureStatus: result.signatureStatus } }),
   })
   return result
 }

package/src/webhooks.ts

@@ -6,10 +6,14 @@ export interface WebhookRequest {
   rawBody: string
 }
 
+export type WebhookSignatureStatus = 'valid' | 'invalid' | 'missing' | 'not_configured'
+
 export interface WebhookResult {
   handled: boolean
   unauthorized?: boolean
   message?: string
+  /** Persisted signature verdict for this delivery (never a guess). */
+  signatureStatus?: WebhookSignatureStatus
 }
 
 /**
@@ -26,11 +30,33 @@ export function authorizeWebhook(opts: {
   const { secret, rawBody, signature, verify } = opts
   if (!secret) return null
   if (!verify(secret, rawBody, signature)) {
-    return { handled: false, unauthorized: true, message: 'Invalid signature' }
+    return {
+      handled: false,
+      unauthorized: true,
+      message: 'Invalid signature',
+      signatureStatus: signature ? 'invalid' : 'missing',
+    }
   }
   return null
 }
 
+/**
+ * Signature verdict for a delivery, computed the same way authorizeWebhook
+ * decides authorization. Providers attach this to every WebhookResult so the
+ * receipts table persists a true verdict instead of leaving consumers to guess.
+ */
+export function webhookSignatureStatus(opts: {
+  secret: string | undefined
+  rawBody: string
+  signature: string | undefined | null
+  verify: (secret: string, rawBody: string, signature: string | undefined | null) => boolean
+}): WebhookSignatureStatus {
+  const { secret, rawBody, signature, verify } = opts
+  if (!secret) return 'not_configured'
+  if (!signature) return 'missing'
+  return verify(secret, rawBody, signature) ? 'valid' : 'invalid'
+}
+
 export function verifyHmacSha256(
   secret: string,
   rawBody: string,