@andypai/agent-kanban 0.7.0 → 0.8.1

package/src/__tests__/webhook-events-receipts.test.ts

@@ -0,0 +1,155 @@
+import { afterEach, beforeEach, describe, expect, mock, test } from 'bun:test'
+import type { Sql } from 'postgres'
+import {
+  ensureWebhookEventsSchema,
+  recordWebhookEvent,
+  withWebhookRecording,
+} from '../webhook-events'
+
+// A minimal fake of the `postgres` tagged-template client. It records every
+// query (joined SQL text + interpolated values) and exposes `.json()` like the
+// real client, so the receipts helpers can be unit-tested without a Postgres.
+interface FakeSql {
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<unknown[]>
+  json: (v: unknown) => { __json: unknown }
+  calls: { text: string; values: unknown[] }[]
+}
+
+function makeFakeSql(opts: { fail?: boolean } = {}): FakeSql {
+  const calls: { text: string; values: unknown[] }[] = []
+  const fn = ((strings: TemplateStringsArray, ...values: unknown[]) => {
+    calls.push({ text: strings.join(' ? '), values })
+    return opts.fail ? Promise.reject(new Error('db down')) : Promise.resolve([])
+  }) as FakeSql
+  fn.json = (v: unknown) => ({ __json: v })
+  fn.calls = calls
+  return fn
+}
+
+const asSql = (f: FakeSql): Sql => f as unknown as Sql
+
+let prevFlag: string | undefined
+beforeEach(() => {
+  prevFlag = process.env['KANBAN_WEBHOOK_EVENTS']
+  delete process.env['KANBAN_WEBHOOK_EVENTS'] // default = enabled
+})
+afterEach(() => {
+  if (prevFlag === undefined) delete process.env['KANBAN_WEBHOOK_EVENTS']
+  else process.env['KANBAN_WEBHOOK_EVENTS'] = prevFlag
+})
+
+describe('ensureWebhookEventsSchema (F37)', () => {
+  test('enabled: issues CREATE TABLE + CREATE INDEX (idempotent DDL)', async () => {
+    const sql = makeFakeSql()
+    await ensureWebhookEventsSchema(asSql(sql))
+    const text = sql.calls.map((c) => c.text).join('\n')
+    expect(text).toContain('CREATE TABLE IF NOT EXISTS webhook_events')
+    expect(text).toContain('CREATE INDEX IF NOT EXISTS webhook_events_received_at_idx')
+    expect(sql.calls.length).toBe(2)
+  })
+
+  test('disabled: no DDL is issued', async () => {
+    process.env['KANBAN_WEBHOOK_EVENTS'] = 'off'
+    const sql = makeFakeSql()
+    await ensureWebhookEventsSchema(asSql(sql))
+    expect(sql.calls.length).toBe(0)
+  })
+})
+
+describe('recordWebhookEvent (F40)', () => {
+  test('enabled: inserts provider/eventType/externalRef/status/detail', async () => {
+    const sql = makeFakeSql()
+    await recordWebhookEvent(asSql(sql), {
+      provider: 'jira',
+      eventType: 'jira:issue_updated',
+      externalRef: 'ENG-7',
+      status: 'accepted',
+      detail: { note: 'ok' },
+    })
+    expect(sql.calls.length).toBe(1)
+    const insert = sql.calls[0]!
+    expect(insert.text).toContain('INSERT INTO webhook_events')
+    expect(insert.values).toEqual([
+      'jira',
+      'jira:issue_updated',
+      'ENG-7',
+      'accepted',
+      { __json: { note: 'ok' } },
+    ])
+  })
+
+  test('omitted eventType/externalRef/detail become null / empty json', async () => {
+    const sql = makeFakeSql()
+    await recordWebhookEvent(asSql(sql), { provider: 'linear', status: 'skipped' })
+    const insert = sql.calls[0]!
+    expect(insert.values).toEqual(['linear', null, null, 'skipped', { __json: {} }])
+  })
+
+  test('disabled: no insert', async () => {
+    process.env['KANBAN_WEBHOOK_EVENTS'] = '0'
+    const sql = makeFakeSql()
+    await recordWebhookEvent(asSql(sql), { provider: 'jira', status: 'accepted' })
+    expect(sql.calls.length).toBe(0)
+  })
+
+  test('a failing insert is swallowed (never throws) and is logged', async () => {
+    const warnSpy = mock(() => {})
+    const original = console.warn
+    console.warn = warnSpy as unknown as typeof console.warn
+    try {
+      const sql = makeFakeSql({ fail: true })
+      await recordWebhookEvent(asSql(sql), { provider: 'jira', status: 'accepted' })
+      expect(warnSpy).toHaveBeenCalled()
+    } finally {
+      console.warn = original
+    }
+  })
+})
+
+describe('withWebhookRecording (F39)', () => {
+  test('success: returns dispatch result and records the mapped status', async () => {
+    const sql = makeFakeSql()
+    const body = JSON.stringify({ webhookEvent: 'jira:issue_updated', issue: { key: 'ENG-9' } })
+    const result = await withWebhookRecording(
+      asSql(sql),
+      'jira',
+      { headers: {}, rawBody: body },
+      async () => ({ handled: true }),
+    )
+    expect(result).toEqual({ handled: true })
+    const insert = sql.calls.find((c) => c.text.includes('INSERT INTO webhook_events'))
+    expect(insert).toBeDefined()
+    // provider, eventType(from body), externalRef(from body), status
+    expect(insert!.values.slice(0, 4)).toEqual(['jira', 'jira:issue_updated', 'ENG-9', 'accepted'])
+  })
+
+  test('unhandled dispatch is recorded as skipped', async () => {
+    const sql = makeFakeSql()
+    const result = await withWebhookRecording(
+      asSql(sql),
+      'linear',
+      { headers: {}, rawBody: '{}' },
+      async () => ({ handled: false }),
+    )
+    expect(result).toEqual({ handled: false })
+    const insert = sql.calls.find((c) => c.text.includes('INSERT INTO webhook_events'))!
+    expect(insert.values[3]).toBe('skipped')
+  })
+
+  test('dispatch throw: records an error receipt and rethrows the original error', async () => {
+    const sql = makeFakeSql()
+    const boom = new Error('apply failed')
+    let caught: unknown
+    try {
+      await withWebhookRecording(asSql(sql), 'jira', { headers: {}, rawBody: '{}' }, async () => {
+        throw boom
+      })
+    } catch (err) {
+      caught = err
+    }
+    expect(caught).toBe(boom)
+    const insert = sql.calls.find((c) => c.text.includes('INSERT INTO webhook_events'))!
+    expect(insert.values[3]).toBe('error')
+    expect(insert.values[4]).toEqual({ __json: { error: 'apply failed' } })
+  })
+})

package/src/__tests__/webhooks.test.ts

@@ -1,7 +1,12 @@
 import { beforeEach, afterEach, describe, expect, test } from 'bun:test'
 import { Database } from 'bun:sqlite'
 import { createHmac } from 'node:crypto'
-import { verifyHmacSha256, verifySha256HmacSignatureHeader } from '../webhooks'
+import {
+  authorizeWebhook,
+  headerLower,
+  verifyHmacSha256,
+  verifySha256HmacSignatureHeader,
+} from '../webhooks'
 import { JiraProvider, type JiraProviderConfig } from '../providers/jira'
 import { JiraClient } from '../providers/jira-client'
 import { LinearProvider } from '../providers/linear'
@@ -69,6 +74,47 @@ describe('verifyHmacSha256', () => {
   })
 })
 
+describe('authorizeWebhook (F32)', () => {
+  const verify = (secret: string, body: string, sig: string | undefined | null): boolean =>
+    verifyHmacSha256(secret, body, sig)
+
+  test('no secret configured → open mode (returns null, request allowed)', () => {
+    expect(
+      authorizeWebhook({ secret: undefined, rawBody: '{}', signature: 'anything', verify }),
+    ).toBeNull()
+    expect(authorizeWebhook({ secret: '', rawBody: '{}', signature: undefined, verify })).toBeNull()
+  })
+
+  test('secret configured + valid signature → null (proceed)', () => {
+    const body = '{"a":1}'
+    const sig = createHmac('sha256', 's3cr3t').update(body).digest('hex')
+    expect(authorizeWebhook({ secret: 's3cr3t', rawBody: body, signature: sig, verify })).toBeNull()
+  })
+
+  test('secret configured + bad signature → unauthorized result', () => {
+    const result = authorizeWebhook({
+      secret: 's3cr3t',
+      rawBody: '{"a":1}',
+      signature: 'deadbeef',
+      verify,
+    })
+    expect(result).toEqual({ handled: false, unauthorized: true, message: 'Invalid signature' })
+  })
+})
+
+describe('headerLower (F35)', () => {
+  test('case-insensitive lookup returns the matching value', () => {
+    const headers = { 'X-Hub-Signature': 'sha256=abc', 'Content-Type': 'application/json' }
+    expect(headerLower(headers, 'x-hub-signature')).toBe('sha256=abc')
+    expect(headerLower(headers, 'X-HUB-SIGNATURE')).toBe('sha256=abc')
+    expect(headerLower(headers, 'content-type')).toBe('application/json')
+  })
+
+  test('missing header → undefined', () => {
+    expect(headerLower({ a: '1' }, 'linear-signature')).toBeUndefined()
+  })
+})
+
 describe('verifySha256HmacSignatureHeader', () => {
   test('accepts Jira WebSub-style sha256 signatures', () => {
     const body = '{"hello":"world"}'

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.
@@ -52,27 +52,49 @@ function statusForCode(code: string): number {
   if (code === ErrorCode.PROVIDER_RATE_LIMITED) return 429
   if (code === ErrorCode.CONFLICT) return 409
   if (code === ErrorCode.UNSUPPORTED_OPERATION) return 400
-  if (code === ErrorCode.PROVIDER_NOT_CONFIGURED) return 500
+  // Server-side / upstream failures must surface as 5xx, not as the default 400.
+  // (The MCP layer likewise treats these as `provider_unavailable`.)
+  if (code === ErrorCode.PROVIDER_UPSTREAM_ERROR) return 502
+  if (code === ErrorCode.PROVIDER_SYNC_REQUIRED) return 503
+  if (code === ErrorCode.PROVIDER_NOT_CONFIGURED || code === ErrorCode.INTERNAL_ERROR) return 500
   return 400
 }
 
+// decodeURIComponent throws URIError on malformed percent-encoding (e.g. a lone
+// `%`). Path params flow straight into it, so a bad URL must surface as a 400
+// envelope rather than escaping handleRequest as an unhandled rejection.
+function decodePathParam(raw: string): string {
+  try {
+    return decodeURIComponent(raw)
+  } catch {
+    throw new KanbanError(ErrorCode.INVALID_ARGUMENT, 'Malformed percent-encoding in URL path')
+  }
+}
+
 function toResponse(result: CliOutput): Response {
   if (result.ok) return json(result)
   return json(result, statusForCode(result.error.code))
 }
 
+// Map any thrown error to the `{ ok:false, error }` envelope with the right
+// status. Shared by wrapHandler (per-handler) and handleRequest's top-level
+// guard so the two error paths can never drift apart.
+function errorResponse(err: unknown): Response {
+  if (err instanceof KanbanError) {
+    return json(
+      { ok: false, error: { code: err.code, message: err.message } },
+      statusForCode(err.code),
+    )
+  }
+  const msg = err instanceof Error ? err.message : String(err)
+  return json({ ok: false, error: { code: 'INTERNAL_ERROR', message: msg } }, 500)
+}
+
 async function wrapHandler(fn: () => Promise<CliOutput> | CliOutput): Promise<Response> {
   try {
     return toResponse(await fn())
   } catch (err) {
-    if (err instanceof KanbanError) {
-      return json(
-        { ok: false, error: { code: err.code, message: err.message } },
-        statusForCode(err.code),
-      )
-    }
-    const msg = err instanceof Error ? err.message : String(err)
-    return json({ ok: false, error: { code: 'INTERNAL_ERROR', message: msg } }, 500)
+    return errorResponse(err)
   }
 }
 
@@ -110,7 +132,20 @@ async function mutationResult<T>(
   }
 }
 
+// Top-level guard: handleRequest must NEVER throw. The webhook branch returns a
+// raw ApiResult (not via wrapHandler), and path-param decoding / body reads can
+// throw before any handler runs. Any escape would reach Bun.serve's fetch (which
+// has no try/catch) and surface as a bare, non-enveloped 500. This wrapper keeps
+// every failure inside the { ok:false, error } contract, never marking mutated.
 export async function handleRequest(provider: KanbanProvider, req: Request): Promise<ApiResult> {
+  try {
+    return await dispatchApiRequest(provider, req)
+  } catch (err) {
+    return { response: errorResponse(err), mutated: false }
+  }
+}
+
+async function dispatchApiRequest(provider: KanbanProvider, req: Request): Promise<ApiResult> {
   const url = new URL(req.url)
   const path = url.pathname
   const method = req.method
@@ -164,7 +199,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   const taskMatch = path.match(/^\/api\/tasks\/([^/]+)$/)
   if (taskMatch) {
-    const id = decodeURIComponent(taskMatch[1]!)
+    const id = decodePathParam(taskMatch[1]!)
 
     if (method === 'GET') {
       return readResult(() => provider.getTask(id))
@@ -187,7 +222,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   const moveMatch = path.match(/^\/api\/tasks\/([^/]+)\/move$/)
   if (moveMatch && method === 'PATCH') {
-    const id = decodeURIComponent(moveMatch[1]!)
+    const id = decodePathParam(moveMatch[1]!)
     return mutationResult(async () => {
       const body = await parseJsonBody<MoveTaskBody>(req)
       requireArgument(body.column, 'column')
@@ -197,7 +232,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   const commentsMatch = path.match(/^\/api\/tasks\/([^/]+)\/comments$/)
   if (commentsMatch) {
-    const id = decodeURIComponent(commentsMatch[1]!)
+    const id = decodePathParam(commentsMatch[1]!)
     if (method === 'GET') {
       return readResult(() => provider.listComments(id))
     }
@@ -213,8 +248,8 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   const commentMatch = path.match(/^\/api\/tasks\/([^/]+)\/comments\/([^/]+)$/)
   if (commentMatch) {
-    const id = decodeURIComponent(commentMatch[1]!)
-    const commentId = decodeURIComponent(commentMatch[2]!)
+    const id = decodePathParam(commentMatch[1]!)
+    const commentId = decodePathParam(commentMatch[2]!)
 
     if (method === 'PATCH') {
       return mutationResult(async () => {
@@ -250,7 +285,7 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
 
   const webhookMatch = path.match(/^\/api\/webhooks\/([^/]+)$/)
   if (webhookMatch && method === 'POST') {
-    const target = decodeURIComponent(webhookMatch[1]!)
+    const target = decodePathParam(webhookMatch[1]!)
     if (target !== provider.type) {
       return {
         response: json(
@@ -286,6 +321,9 @@ export async function handleRequest(provider: KanbanProvider, req: Request): Pro
     req.headers.forEach((value, key) => {
       headers[key] = value
     })
+    // A throwing provider.handleWebhook is contained by the top-level guard in
+    // handleRequest, which envelopes it as a 500 (or KanbanError status) and
+    // leaves mutated:false.
     const result = await provider.handleWebhook({ headers, rawBody })
     if (result.unauthorized) {
       return {

package/src/db.ts

@@ -178,6 +178,23 @@ export function resolveColumn(db: Database, idOrName: string): Column {
   throw new KanbanError(ErrorCode.COLUMN_NOT_FOUND, `No column matching '${idOrName}'`)
 }
 
+// Resolve the column a task lands in when the caller gives no explicit column.
+// Mirrors the Postgres local provider's resolveDefaultTaskColumn fallback so the
+// SQLite store stays at parity: prefer a column named "backlog", otherwise the
+// first column by position. (A configured KANBAN_DEFAULT_TASK_COLUMN is handled
+// upstream by being passed in as the explicit column.)
+function resolveDefaultColumn(db: Database): Column {
+  const backlog = db
+    .query("SELECT * FROM columns WHERE LOWER(name) = 'backlog' ORDER BY position LIMIT 1")
+    .get() as Column | null
+  if (backlog) return backlog
+  const first = db
+    .query('SELECT * FROM columns ORDER BY position, name LIMIT 1')
+    .get() as Column | null
+  if (first) return first
+  throw new KanbanError(ErrorCode.COLUMN_NOT_FOUND, 'No columns are configured')
+}
+
 export function listColumns(db: Database): Column[] {
   return db.query('SELECT * FROM columns ORDER BY position').all() as Column[]
 }
@@ -295,7 +312,7 @@ export function addTask(
     metadata?: string
   } = {},
 ): TaskWithColumn {
-  const column = opts.column ? resolveColumn(db, opts.column) : resolveColumn(db, 'backlog')
+  const column = opts.column ? resolveColumn(db, opts.column) : resolveDefaultColumn(db)
 
   if (opts.priority && !['low', 'medium', 'high', 'urgent'].includes(opts.priority)) {
     throw new KanbanError(

package/src/index.ts

@@ -9,13 +9,13 @@ import { boardInit, boardReset } from './commands/board'
 import { columnAdd, columnDelete, columnList, columnRename, columnReorder } from './commands/column'
 import { bulkClearDoneCmd, bulkMoveAllCmd } from './commands/bulk'
 import { getConfigPath, loadConfig, saveConfig } from './config'
-import { parsePositiveInt } from './transport-input'
+import { parseBoundedInt, parsePositiveInt } from './transport-input'
 import type { CliOutput, Priority, ProviderCapabilities } from './types'
 import { unsupportedOperation } from './providers/errors'
 import { openKanbanRuntime } from './provider-runtime'
-import { trackerConfigFromEnv } from './tracker-config'
+import { WEBHOOK_SECRET_ENV, trackerConfigFromEnv, trackerProviderFromEnv } from './tracker-config'
 import type { KanbanProvider } from './providers/types'
-import { resolvePollingSyncIntervalMs } from './sync-config'
+import { MIN_POLLING_SYNC_INTERVAL_MS } from './sync-config'
 import { normalizeCreateTaskInput } from './use-cases'
 
 interface ParsedArgs {
@@ -420,7 +420,7 @@ Commands:
   board view                  View full board (default)
   board reset                 Reset board to defaults
 
-  task add <title>            Add a task [-d desc] [-c column] [-p priority] [-a assignee] [--project name] [--label name] [-m json]
+  task add <title>            Add a task [-d desc] [-c column] [-p priority] [-a assignee] [--project name] [--label name] [--labels names] [-m json]
   task list                   List tasks [-c column] [-p priority] [-a assignee] [--project name] [-l limit] [--sort field]
   task view <id>              View task details
   task update <id>            Update task [--title] [-d] [-p] [-a] [--project name] [-m]
@@ -489,9 +489,12 @@ export function parseServeArgs(argv: string[]): ServeOptions {
       err instanceof Error ? err.message : String(err),
     )
   }
-  const port = values.port
-    ? parseInt(values.port as string, 10)
-    : parseInt(process.env['PORT'] || '3000', 10)
+  // Use `!== undefined` (not truthiness) so an explicit empty `--port=` is
+  // validated and rejected rather than silently falling back to the default.
+  const port =
+    values.port !== undefined
+      ? parsePort(values.port as string, '--port')
+      : parsePort(process.env['PORT'] || '3000', 'PORT')
   // Flags win over env so a one-off `--token` can override the ambient config.
   const authToken = (values.token as string | undefined) || process.env['KANBAN_API_TOKEN']
   const allowedOrigin =
@@ -499,7 +502,7 @@ export function parseServeArgs(argv: string[]): ServeOptions {
   return {
     db: values.db as string | undefined,
     port,
-    ...(values['sync-interval-ms']
+    ...(values['sync-interval-ms'] !== undefined
       ? { syncIntervalMs: parseSyncIntervalMs(values['sync-interval-ms'] as string) }
       : {}),
     tunnel: Boolean(values.tunnel),
@@ -508,8 +511,60 @@ export function parseServeArgs(argv: string[]): ServeOptions {
   }
 }
 
+// Strict digits-only CLI contract via the shared parseBoundedInt (rejects
+// hex/scientific, the Number() overflow/precision-loss of an over-long digit
+// string, and values below the minimum — all as INVALID_ARGUMENT). The shared
+// resolvePollingSyncIntervalMs (sync-config.ts) is the env-path parser; this
+// flag is validated strictly here.
 function parseSyncIntervalMs(raw: string): number {
-  return resolvePollingSyncIntervalMs(raw, { label: '--sync-interval-ms' })
+  return parseBoundedInt(raw, { min: MIN_POLLING_SYNC_INTERVAL_MS, field: '--sync-interval-ms' })
+}
+
+// `parseInt` silently accepts `123abc` (→123) and `-1`, and yields NaN for
+// non-numeric input, so validate the port explicitly via parseBoundedInt: digits
+// only, 0–65535 (0 lets the OS pick an ephemeral port). Throws so a bad value
+// surfaces as the structured INVALID_ARGUMENT envelope rather than booting on a
+// garbage port.
+function parsePort(raw: string, label: string): number {
+  return parseBoundedInt(raw, { min: 0, max: 65535, field: label })
+}
+
+/**
+ * Guards public-tunnel startup. A `--tunnel` exposes the server to the internet,
+ * so it must require both:
+ *   1. an API token (KANBAN_API_TOKEN / --token) for the `/api/*` + `/ws` surface, and
+ *   2. a provider webhook signing secret, because `/api/webhooks/*` is exempt from
+ *      the API token and falls back to "open dev mode" (accept unsigned payloads)
+ *      when the secret is unset — which over a public tunnel means unauthenticated
+ *      writes to the cache.
+ * Throws KanbanError on violation; the caller prints the message and exits non-zero.
+ */
+export function assertTunnelSecurity(
+  opts: { tunnel: boolean; authToken?: string },
+  env: Record<string, string | undefined>,
+): void {
+  if (!opts.tunnel) return
+  if (!opts.authToken) {
+    throw new KanbanError(
+      ErrorCode.INVALID_ARGUMENT,
+      'Refusing to start a public tunnel without an API token. ' +
+        'Set KANBAN_API_TOKEN or pass --token <token>.',
+    )
+  }
+  const providerType = trackerProviderFromEnv(env)
+  // Single source of truth (WEBHOOK_SECRET_ENV is Record<TrackerProvider,…>), so
+  // a new webhook-capable provider can't be added without declaring its secret
+  // here — closing the fail-open hole where an unmapped provider would start a
+  // public tunnel with no signature secret enforced.
+  const webhookSecretEnv = WEBHOOK_SECRET_ENV[providerType]
+  if (webhookSecretEnv && !env[webhookSecretEnv]) {
+    throw new KanbanError(
+      ErrorCode.INVALID_ARGUMENT,
+      `Refusing to start a public tunnel: ${providerType} webhooks accept unsigned payloads ` +
+        `(open dev mode) without ${webhookSecretEnv}, which would expose unauthenticated writes ` +
+        `over the public URL. Set ${webhookSecretEnv}.`,
+    )
+  }
 }
 
 export interface McpOptions {
@@ -563,13 +618,14 @@ if (import.meta.main) {
   } else if (argv[0] === 'serve') {
     const opts = parseEntryArgs(() => parseServeArgs(argv))
 
-    // A tunnel exposes the dashboard publicly, so refuse to start one without a
-    // token. Plain localhost serve stays open for backward compatibility.
-    if (opts.tunnel && !opts.authToken) {
-      console.error(
-        'Refusing to start a public tunnel without an API token. ' +
-          'Set KANBAN_API_TOKEN or pass --token <token>.',
-      )
+    // A tunnel exposes the dashboard publicly, so refuse to start one unless it is
+    // safe: an API token for /api + /ws, and a provider webhook secret so the
+    // auth-exempt /api/webhooks/* surface can't accept unsigned writes. Plain
+    // localhost serve stays open for backward compatibility.
+    try {
+      assertTunnelSecurity(opts, process.env)
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err))
       process.exit(1)
     }
 
@@ -595,7 +651,10 @@ if (import.meta.main) {
     if (opts.tunnel) {
       const { startCloudflareTunnel } = await import('./tunnel')
       try {
-        tunnelHandle = startCloudflareTunnel(opts.port)
+        // Use the resolved bound port, not opts.port: with `--port=0` the OS
+        // picks an ephemeral port, so opts.port (0) would point cloudflared at
+        // localhost:0 and never reach the server.
+        tunnelHandle = startCloudflareTunnel(server.port)
       } catch {
         // startCloudflareTunnel already logged a friendly message
       }

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/factory.ts

@@ -68,7 +68,7 @@ export function createSqliteProvider(
         seedDefaultColumns(db, config.defaultColumns)
       }
       return {
-        provider: new LocalProvider(db, options.dbPath),
+        provider: new LocalProvider(db, options.dbPath, config.defaultTaskColumn),
         capabilities: LOCAL_CAPABILITIES,
       }
   }

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