@andypai/agent-kanban 0.7.0 → 0.8.1

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

@@ -47,12 +47,13 @@ import type {
   UpdateTaskInput,
 } from './types'
 import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
+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
@@ -63,7 +64,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',
@@ -872,14 +873,19 @@ export class JiraProviderCore implements KanbanProvider {
   // Shared webhook dispatch. Postgres wraps this with webhook-event auditing;
   // SQLite calls it directly via the default handleWebhook above.
   protected async handleWebhookCore(payload: WebhookRequest): Promise<WebhookResult> {
-    if (!process.env['JIRA_WEBHOOK_SECRET']) {
+    // Resolve the signing secret through WEBHOOK_SECRET_ENV so the runtime
+    // enforcement here and the assertTunnelSecurity tunnel gate read the same env
+    // name — they can't drift into a fail-open where the gate requires one env and
+    // verification reads another (unset) one.
+    const secret = webhookSecretFromEnv('jira')
+    if (!secret) {
       warnOnce(
         'jira-webhook-open-dev-mode',
-        '[jira] JIRA_WEBHOOK_SECRET is not set — accepting webhook without signature verification (open dev mode)',
+        `[jira] ${WEBHOOK_SECRET_ENV['jira']} is not set — accepting webhook without signature verification (open dev mode)`,
       )
     }
     const auth = authorizeWebhook({
-      secret: process.env['JIRA_WEBHOOK_SECRET'],
+      secret,
       rawBody: payload.rawBody,
       signature: headerLower(payload.headers, 'x-hub-signature'),
       verify: verifySha256HmacSignatureHeader,

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/linear-core.ts

@@ -40,6 +40,7 @@ import type {
   UpdateTaskInput,
 } from './types'
 import { DEFAULT_POLLING_SYNC_INTERVAL_MS } from '../sync-config'
+import { WEBHOOK_SECRET_ENV, webhookSecretFromEnv } from '../tracker-config'
 import { warnOnce } from './warn-once'
 import {
   applyTaskFilters,
@@ -596,14 +597,19 @@ export class LinearProviderCore implements KanbanProvider {
   // Shared webhook dispatch. Postgres wraps this with webhook-event auditing;
   // SQLite calls it directly via the default handleWebhook above.
   protected async handleWebhookCore(payload: WebhookRequest): Promise<WebhookResult> {
-    if (!process.env['LINEAR_WEBHOOK_SECRET']) {
+    // Resolve the signing secret through WEBHOOK_SECRET_ENV so the runtime
+    // enforcement here and the assertTunnelSecurity tunnel gate read the same env
+    // name — they can't drift into a fail-open where the gate requires one env and
+    // verification reads another (unset) one.
+    const secret = webhookSecretFromEnv('linear')
+    if (!secret) {
       warnOnce(
         'linear-webhook-open-dev-mode',
-        '[linear] LINEAR_WEBHOOK_SECRET is not set — accepting webhook without signature verification (open dev mode)',
+        `[linear] ${WEBHOOK_SECRET_ENV['linear']} is not set — accepting webhook without signature verification (open dev mode)`,
       )
     }
     const auth = authorizeWebhook({
-      secret: process.env['LINEAR_WEBHOOK_SECRET'],
+      secret,
       rawBody: payload.rawBody,
       signature: headerLower(payload.headers, 'linear-signature'),
       verify: verifyHmacSha256,

package/src/providers/local.ts

@@ -5,7 +5,7 @@ import { LocalProviderCore } from './local-core'
 import { SqliteLocalStore } from './sqlite-local-store'
 
 export class LocalProvider extends LocalProviderCore {
-  constructor(db: Database, dbPath = getDbPath()) {
-    super(new SqliteLocalStore(db, dbPath))
+  constructor(db: Database, dbPath = getDbPath(), defaultTaskColumn?: string) {
+    super(new SqliteLocalStore(db, dbPath, defaultTaskColumn))
   }
 }

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/providers/sqlite-local-store.ts

@@ -30,6 +30,7 @@ export class SqliteLocalStore implements LocalStorePort {
   constructor(
     private readonly db: Database,
     private readonly dbPath: string,
+    private readonly defaultTaskColumn?: string,
   ) {}
 
   getBoard() {
@@ -53,7 +54,10 @@ export class SqliteLocalStore implements LocalStorePort {
   }
 
   createTask(input: CreateTaskInput) {
-    return addTask(this.db, input.title, input)
+    return addTask(this.db, input.title, {
+      ...input,
+      column: input.column ?? this.defaultTaskColumn,
+    })
   }
 
   updateTask(idOrRef: string, input: Omit<UpdateTaskInput, 'expectedVersion'>) {

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/sync-config.ts

@@ -1,4 +1,5 @@
 import { ErrorCode, KanbanError } from './errors'
+import { parseDecimalDigits } from './transport-input'
 
 export const DEFAULT_POLLING_SYNC_INTERVAL_MS = 30_000
 export const MIN_POLLING_SYNC_INTERVAL_MS = 1_000
@@ -10,8 +11,12 @@ export function resolvePollingSyncIntervalMs(
   const value = raw?.trim()
   if (!value) return DEFAULT_POLLING_SYNC_INTERVAL_MS
 
-  const parsed = Number(value)
-  if (!Number.isInteger(parsed) || parsed < MIN_POLLING_SYNC_INTERVAL_MS) {
+  // Digits-only via the shared parser (rejects hex/scientific like `0x3e8`/`1e3`
+  // and over-long strings that round past MAX_SAFE_INTEGER / overflow to
+  // Infinity); a set-but-invalid value is a config error, not a fall-back to the
+  // default, mirroring the strict --sync-interval-ms CLI flag.
+  const parsed = parseDecimalDigits(value)
+  if (parsed === null || parsed < MIN_POLLING_SYNC_INTERVAL_MS) {
     throw new KanbanError(
       ErrorCode.INVALID_CONFIG,
       `${opts.label ?? 'KANBAN_SYNC_INTERVAL_MS'} must be an integer >= ${MIN_POLLING_SYNC_INTERVAL_MS}`,

package/src/tracker-config.ts

@@ -1,9 +1,60 @@
 import { ErrorCode, KanbanError } from './errors'
 import { providerNotConfigured } from './providers/errors'
 import { resolvePollingSyncIntervalMs } from './sync-config'
+import { parseDecimalDigits } from './transport-input'
 
 export type TrackerProvider = 'local' | 'linear' | 'jira'
 
+/**
+ * Single source of truth for which env var holds each provider's webhook signing
+ * secret (`null` = the provider has no webhook ingestion). Typed as
+ * `Record<TrackerProvider, …>`, so adding a new provider to the union is a
+ * compile error here until its secret env is declared — preventing a new
+ * webhook-capable provider from silently slipping past the tunnel-security gate
+ * (assertTunnelSecurity) with no secret enforced.
+ */
+export const WEBHOOK_SECRET_ENV: Record<TrackerProvider, string | null> = {
+  local: null,
+  linear: 'LINEAR_WEBHOOK_SECRET',
+  jira: 'JIRA_WEBHOOK_SECRET',
+}
+
+/**
+ * Normalize the raw `KANBAN_PROVIDER` env value to a known `TrackerProvider`,
+ * falling back to `'local'` for anything unset/unrecognized — matching how
+ * trackerConfigFromEnv resolves the provider. Centralized so the security gate
+ * and the config loader agree on a single derivation.
+ */
+export function trackerProviderFromEnv(
+  env: Record<string, string | undefined> = process.env,
+): TrackerProvider {
+  const raw = (env['KANBAN_PROVIDER'] ?? 'local').trim().toLowerCase()
+  // Recognize exactly the providers declared in WEBHOOK_SECRET_ENV — own keys
+  // only, so inherited names like "constructor"/"toString" don't match — and
+  // fall back to local otherwise. Deriving from the map keeps this normalizer in
+  // lockstep with it, so a newly-added provider is picked up here automatically.
+  return Object.prototype.hasOwnProperty.call(WEBHOOK_SECRET_ENV, raw)
+    ? (raw as TrackerProvider)
+    : 'local'
+}
+
+/**
+ * Resolve a provider's webhook signing secret from `env` via WEBHOOK_SECRET_ENV
+ * (the single source of truth), returning `undefined` when the provider declares
+ * no secret env or the env var is unset — the case where the webhook handler
+ * falls back to open dev mode. The runtime signature enforcement (the provider
+ * webhook handlers) and the assertTunnelSecurity tunnel gate both resolve the
+ * secret env name through this same map, so the gate cannot require one env name
+ * while enforcement reads another (a fail-open if they drifted).
+ */
+export function webhookSecretFromEnv(
+  provider: TrackerProvider,
+  env: Record<string, string | undefined> = process.env,
+): string | undefined {
+  const envName = WEBHOOK_SECRET_ENV[provider]
+  return envName ? env[envName] : undefined
+}
+
 export interface LocalTrackerConfig {
   provider: 'local'
   defaultColumns?: string[]
@@ -11,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
@@ -34,7 +85,7 @@ export type TrackerConfig = LocalTrackerConfig | LinearTrackerConfig | JiraTrack
 export function trackerConfigFromEnv(
   env: Record<string, string | undefined> = process.env,
 ): TrackerConfig {
-  const provider = (env['KANBAN_PROVIDER'] ?? 'local').trim().toLowerCase()
+  const provider = trackerProviderFromEnv(env)
 
   if (provider === 'linear') {
     const apiKey = env['LINEAR_API_KEY']
@@ -70,15 +121,14 @@ export function trackerConfigFromEnv(
         `${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} required when KANBAN_PROVIDER=jira`,
       )
     }
-    const boardIdRaw = env['JIRA_BOARD_ID']
-    const boardId = boardIdRaw ? Number.parseInt(boardIdRaw, 10) : undefined
+    const boardId = jiraBoardIdFromEnv(env['JIRA_BOARD_ID'])
     return {
       provider,
       baseUrl: baseUrl!,
       email: email!,
       apiToken: apiToken!,
       projectKey: projectKey!,
-      ...(Number.isFinite(boardId) ? { boardId } : {}),
+      ...(boardId !== undefined ? { boardId } : {}),
       defaultIssueType: env['JIRA_ISSUE_TYPE'] ?? 'Task',
       syncIntervalMs: resolvePollingSyncIntervalMs(env['KANBAN_SYNC_INTERVAL_MS']),
     }
@@ -94,6 +144,24 @@ export function trackerConfigFromEnv(
   }
 }
 
+/**
+ * Resolve the optional `JIRA_BOARD_ID` env var to a positive integer board id.
+ * Unset/blank → `undefined` (no board pinned). A set-but-invalid value throws
+ * `INVALID_CONFIG` rather than silently falling back: the previous
+ * `Number.parseInt` accepted trailing garbage and signs (`'12abc'→12`,
+ * `'-5'→-5`, `'1e3'→1`), quietly pinning a *wrong* board. This matches how
+ * resolvePollingSyncIntervalMs treats a malformed optional numeric env var.
+ */
+function jiraBoardIdFromEnv(raw: string | undefined): number | undefined {
+  const value = raw?.trim()
+  if (!value) return undefined
+  const parsed = parseDecimalDigits(value)
+  if (parsed === null || parsed < 1) {
+    throw new KanbanError(ErrorCode.INVALID_CONFIG, 'JIRA_BOARD_ID must be a positive integer')
+  }
+  return parsed
+}
+
 function defaultColumnsFromEnv(env: Record<string, string | undefined>): string[] | undefined {
   const raw = env['KANBAN_DEFAULT_COLUMNS']?.trim()
   if (!raw) return undefined

package/src/transport-input.ts

@@ -1,26 +1,58 @@
 import { ErrorCode, KanbanError } from './errors'
 
 /**
- * Parse an optional positive integer supplied through a transport boundary
- * (HTTP query string, CLI flag). Returns `undefined` when the value is absent,
- * and throws a `KanbanError(INVALID_ARGUMENT)` for anything that is not a
- * positive integer — `NaN`, negatives, zero, decimals, and trailing-garbage
- * strings like `"5abc"`. Centralizing this keeps invalid limits from leaking
- * into provider logic, where they would otherwise produce inconsistent
- * behavior across SQL `LIMIT`, `Array.prototype.slice`, and Postgres.
+ * Parse a plain decimal-digit string into an exact non-negative integer, or
+ * `null` if it is not one. Rejects signs, decimals, and exponent/hex forms like
+ * `"-1"` / `"3.5"` / `"1e100"` / `"0x10"` that `Number()` would otherwise coerce
+ * to an integer, and rejects an over-long digit string that `Number()` rounds
+ * past `MAX_SAFE_INTEGER` or overflows to `Infinity`, so the result is always
+ * exact. Surrounding whitespace is trimmed. This is the shared digits-only
+ * primitive the throwing boundary/config parsers (`parseBoundedInt`,
+ * `resolvePollingSyncIntervalMs`, the JIRA_BOARD_ID loader) build on — keeping a
+ * single definition of "what counts as an integer" so they can't drift.
+ */
+export function parseDecimalDigits(value: string): number | null {
+  const trimmed = value.trim()
+  if (!/^\d+$/.test(trimmed)) return null
+  const parsed = Number(trimmed)
+  return Number.isSafeInteger(parsed) ? parsed : null
+}
+
+/**
+ * Parse a required integer supplied through a transport boundary (HTTP query
+ * string, CLI flag) into the inclusive range `[min, max]` (max defaults to
+ * `MAX_SAFE_INTEGER`), via {@link parseDecimalDigits}. Throws
+ * `KanbanError(INVALID_ARGUMENT)` on any violation.
+ */
+export function parseBoundedInt(
+  value: string,
+  opts: { min: number; max?: number; field: string },
+): number {
+  const parsed = parseDecimalDigits(value)
+  const max = opts.max ?? Number.MAX_SAFE_INTEGER
+  if (parsed === null || parsed < opts.min || parsed > max) {
+    const range = opts.max === undefined ? `>= ${opts.min}` : `between ${opts.min} and ${opts.max}`
+    throw new KanbanError(ErrorCode.INVALID_ARGUMENT, `${opts.field} must be an integer ${range}`)
+  }
+  return parsed
+}
+
+/**
+ * Parse an optional positive integer supplied through a transport boundary.
+ * Returns `undefined` when the value is absent/blank, otherwise resolves via
+ * {@link parseDecimalDigits} (which trims and caps at `MAX_SAFE_INTEGER`) and
+ * enforces `>= 1`, throwing `KanbanError(INVALID_ARGUMENT)` framed as "positive
+ * integer" so invalid limits don't leak into provider logic (SQL `LIMIT`,
+ * `slice`, PG).
  */
 export function parsePositiveInt(
   value: string | null | undefined,
   field = 'limit',
 ): number | undefined {
   if (value === null || value === undefined) return undefined
-  const trimmed = value.trim()
-  if (trimmed === '') return undefined
-  // Plain decimal digits only — reject signs, decimals, and exponent forms like
-  // "1e100" that Number() would otherwise treat as integers and let escape into
-  // SQL `LIMIT`. Cap at MAX_SAFE_INTEGER so the parsed value stays exact.
-  const parsed = /^\d+$/.test(trimmed) ? Number(trimmed) : NaN
-  if (!Number.isInteger(parsed) || parsed <= 0 || parsed > Number.MAX_SAFE_INTEGER) {
+  if (value.trim() === '') return undefined
+  const parsed = parseDecimalDigits(value)
+  if (parsed === null || parsed < 1) {
     throw new KanbanError(
       ErrorCode.INVALID_ARGUMENT,
       `${field} must be a positive integer (received '${value}')`,

package/src/tunnel.ts

@@ -57,15 +57,32 @@ export function startCloudflareTunnel(port: number, opts: TunnelOptions = {}): T
   ): Promise<void> => {
     if (!stream) return
     const decoder = new TextDecoder()
+    // Accumulate across chunks: cloudflared may split the URL across read
+    // boundaries, so matching each chunk in isolation can miss it.
+    let buffer = ''
     for await (const chunk of stream) {
-      const text = decoder.decode(chunk as Uint8Array, { stream: true })
-      const match = text.match(TRYCLOUDFLARE_URL)
-      if (match) announce(match[0])
+      // Once announced, keep draining the pipe (so the child doesn't block on a
+      // full stdout buffer) but stop scanning.
+      if (announced) continue
+      buffer += decoder.decode(chunk as Uint8Array, { stream: true })
+      const match = buffer.match(TRYCLOUDFLARE_URL)
+      if (match) {
+        announce(match[0])
+      } else if (buffer.length > 4096) {
+        // Bound memory while keeping a tail long enough to span a split URL.
+        buffer = buffer.slice(-256)
+      }
     }
   }
 
-  void scanForUrl(child.stdout as ReadableStream<Uint8Array>)
-  void scanForUrl(child.stderr as ReadableStream<Uint8Array>)
+  // A stream error while draining stdout/stderr (e.g. the pipe tears down as the
+  // child is killed) must not surface as an unhandled rejection; the child.exited
+  // handler below still emits the no-URL warning when nothing was announced.
+  const drain = (stream: ReadableStream<Uint8Array> | null | undefined): void => {
+    void scanForUrl(stream).catch(() => {})
+  }
+  drain(child.stdout as ReadableStream<Uint8Array>)
+  drain(child.stderr as ReadableStream<Uint8Array>)
 
   void child.exited.then((code) => {
     if (!announced) {