prjct-cli 1.6.8 → 1.6.9

package/CHANGELOG.md

@@ -1,5 +1,55 @@
 # Changelog
 
+## [1.6.9] - 2026-02-07
+
+### Bug Fixes
+
+- resolve SSE zombie connections and infinite promise leak (PRJ-286) (#134)
+
+
+## [1.6.11] - 2026-02-07
+
+### Bug Fixes
+- **Fix SSE zombie connections and infinite promise leak (PRJ-286)**: Replaced infinite `await new Promise(() => {})` with AbortController-based mechanism that resolves on client removal. Added max client lifetime (1 hour) with per-client TTL timeout. Added periodic reaper (every 5 min) that scans for and removes zombie entries from the clients Map. Consolidated duplicate cleanup paths into single idempotent `removeClient(id)` function. Added `shutdown()` to SSEManager for clean server stop. All timers use `unref()` to avoid blocking process exit.
+
+### Implementation Details
+Replaced the infinite pending promise in `streamSSE` callback with an `AbortController` whose signal resolves the await when the client is removed. Internal client state (`heartbeatInterval`, `ttlTimeout`, `abortController`) is tracked in an `InternalClient` wrapper separate from the public `SSEClient` type. The public `SSEClient` interface gained only `connectedAt` for staleness detection.
+
+### Learnings
+- AbortController integrates cleanly with Hono's `streamSSE` — the async callback needs to await *something*, and a signal-based promise is the right primitive.
+- Timer `unref()` has different shapes between Bun (number) and Node (Timeout object) — use `typeof` check before calling.
+- Idempotent cleanup functions eliminate race conditions between heartbeat failure and stream abort handlers.
+
+### Test Plan
+
+#### For QA
+1. Start prjct server, connect SSE client to `/api/events` — verify `connected` event
+2. Disconnect client gracefully — verify `clients.size === 0`
+3. Kill client process (ungraceful) — verify heartbeat cleanup within 30s
+4. Connect client, wait >1 hour — verify TTL auto-disconnect
+5. Connect 5+ clients, kill all — verify reaper cleans all within 5 min
+6. Call `server.stop()` — verify all clients disconnected and reaper stopped
+
+#### For Users
+**What changed:** SSE connections now clean up reliably on disconnect, have a 1-hour max lifetime, and a background reaper removes zombie connections every 5 minutes.
+**Breaking changes:** `SSEManager` interface now includes `shutdown()`. `SSEClient` now includes `connectedAt`.
+
+## [1.6.10] - 2026-02-07
+
+### Documentation
+- **Document all environment variables (PRJ-90)**: Added comprehensive environment variable documentation to README.md covering all 13 env vars used by prjct-cli. Organized into Configuration, JIRA Integration, and Agent Detection categories with defaults, descriptions, and usage examples. Added inline comments at all `process.env` read sites in 6 source files.
+
+### Test Plan
+
+#### For QA
+1. `bun run build` — should succeed
+2. `bun run lint` — no errors
+3. Verify README.md renders correctly on GitHub (env vars tables)
+
+#### For Users
+**What changed:** New "Environment Variables" section in README.md with full documentation of all configurable env vars.
+**Breaking changes:** None.
+
 ## [1.6.8] - 2026-02-07
 
 ### Refactoring

package/README.md

@@ -132,6 +132,52 @@ prjct --version      # Show version + provider status
 prjct --help         # Show help
 ```
 
+## Environment Variables
+
+### Configuration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `PRJCT_CLI_HOME` | `~/.prjct-cli` | Override global storage location. Useful for tests or sandboxed environments. |
+| `PRJCT_DEBUG` | _(unset)_ | Enable debug logging. Values: `1`, `true`, or a log level (`error`, `warn`, `info`, `debug`). |
+| `DEBUG` | _(unset)_ | Fallback debug flag (used if `PRJCT_DEBUG` is not set). Values: `1`, `true`, or `prjct`. |
+| `CI` | _(unset)_ | Set automatically in CI environments. Skips interactive prompts. |
+
+### JIRA Integration
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `JIRA_BASE_URL` | _(none)_ | JIRA instance URL (e.g., `https://myorg.atlassian.net`). |
+| `JIRA_EMAIL` | _(none)_ | Email for JIRA API authentication. |
+| `JIRA_API_TOKEN` | _(none)_ | API token for JIRA authentication. Generate at [Atlassian API tokens](https://id.atlassian.com/manage-profile/security/api-tokens). |
+
+### Agent Detection (Auto-set)
+
+These are typically set by the AI agent runtime, not by users:
+
+| Variable | Description |
+|----------|-------------|
+| `CLAUDE_AGENT` | Set when running inside Claude Code. |
+| `ANTHROPIC_CLAUDE` | Alternative Claude environment indicator. |
+| `MCP_AVAILABLE` | Set when MCP (Model Context Protocol) is available. |
+| `HOME` / `USERPROFILE` | Standard OS home directory (used for path resolution). |
+
+### Usage Examples
+
+```bash
+# Enable debug logging
+PRJCT_DEBUG=1 prjct sync
+
+# Use a custom storage location
+PRJCT_CLI_HOME=/tmp/prjct-test prjct init
+
+# Configure JIRA integration via env vars
+export JIRA_BASE_URL=https://myorg.atlassian.net
+export JIRA_EMAIL=you@example.com
+export JIRA_API_TOKEN=your-api-token
+prjct jira setup
+```
+
 ## Requirements
 
 - Node.js 18+ or Bun 1.0+

package/core/ai-tools/registry.ts

@@ -13,19 +13,12 @@ import { exec } from 'node:child_process'
 import os from 'node:os'
 import path from 'node:path'
 import { promisify } from 'node:util'
+import type { AIToolConfig } from '../types'
 import { fileExists } from '../utils/fs-helpers'
 
 const execAsync = promisify(exec)
 
-export interface AIToolConfig {
-  id: string
-  name: string
-  outputFile: string
-  outputPath: 'repo' | 'global' // 'repo' = project root, 'global' = ~/.prjct-cli/projects/{id}/context/
-  maxTokens: number
-  format: 'detailed' | 'concise' | 'minimal' | 'json'
-  description: string
-}
+export type { AIToolConfig } from '../types'
 
 /**
  * Supported AI tools registry

package/core/commands/planning.ts

@@ -9,7 +9,7 @@ import commandInstaller from '../infrastructure/command-installer'
 import { generateUUID } from '../schemas'
 import type { Priority, TaskSection, TaskType } from '../schemas/state'
 import { ideasStorage, queueStorage } from '../storage'
-import type { CommandResult, ProjectContext } from '../types'
+import type { CommandResult, InitOptions, ProjectContext } from '../types'
 import { getErrorMessage } from '../types/fs'
 import { showNextSteps } from '../utils/next-steps'
 import { OnboardingWizard } from '../wizard'
@@ -34,10 +34,7 @@ async function getAnalysisCommands(): Promise<import('./analysis').AnalysisComma
   return _analysisCommands
 }
 
-export interface InitOptions {
-  yes?: boolean // Skip interactive wizard, use defaults
-  idea?: string | null // Initial idea for architect mode
-}
+export type { InitOptions } from '../types'
 
 export class PlanningCommands extends PrjctCommandsBase {
   /**
@@ -71,6 +68,7 @@ export class PlanningCommands extends PrjctCommandsBase {
 
       // Determine if we should run interactive wizard
       const isTTY = process.stdout.isTTY && process.stdin.isTTY
+      // CI: Skip interactive prompts in CI environments
       const skipWizard = opts.yes || !isTTY || process.env.CI === 'true'
 
       // Run wizard if interactive

package/core/infrastructure/agent-detector.ts

@@ -80,10 +80,10 @@ const TERMINAL_AGENT: DetectedAgent = {
 // ============ Detection Functions ============
 
 export async function isClaudeEnvironment(): Promise<boolean> {
-  // Environment variables
+  // CLAUDE_AGENT / ANTHROPIC_CLAUDE: Set by Claude runtime to indicate agent environment
   if (process.env.CLAUDE_AGENT || process.env.ANTHROPIC_CLAUDE) return true
 
-  // MCP availability
+  // MCP_AVAILABLE: Set when Model Context Protocol is available
   if (global.mcp || process.env.MCP_AVAILABLE) return true
 
   // Configuration files

package/core/infrastructure/path-manager.ts

@@ -14,26 +14,11 @@ import fs from 'node:fs/promises'
 import os from 'node:os'
 import path from 'node:path'
 import { globSync } from 'glob'
-import type { SessionInfo } from '../types'
+import type { MonorepoInfo, MonorepoPackage, SessionInfo } from '../types'
 import * as dateHelper from '../utils/date-helper'
 import * as fileHelper from '../utils/file-helper'
 
-/**
- * Monorepo detection result
- */
-export interface MonorepoInfo {
-  isMonorepo: boolean
-  type: 'pnpm' | 'npm' | 'yarn' | 'lerna' | 'nx' | 'rush' | 'turborepo' | null
-  rootPath: string
-  packages: MonorepoPackage[]
-}
-
-export interface MonorepoPackage {
-  name: string
-  path: string
-  relativePath: string
-  hasPrjctMd: boolean
-}
+export type { MonorepoInfo, MonorepoPackage } from '../types'
 
 class PathManager {
   globalBaseDir: string
@@ -41,6 +26,7 @@ class PathManager {
   globalConfigDir: string
 
   constructor() {
+    // PRJCT_CLI_HOME: Override global storage location (default: ~/.prjct-cli)
     const envOverride = process.env.PRJCT_CLI_HOME?.trim()
     this.globalBaseDir = envOverride
       ? path.resolve(envOverride)

package/core/integrations/jira/client.ts

@@ -15,6 +15,7 @@
  */
 
 import { getErrorMessage } from '../../types/fs'
+import type { JiraAuthMode, JiraIssue, JiraProject, JiraSearchResponse } from '../../types/jira'
 import type {
   CreateIssueInput,
   FetchOptions,
@@ -27,77 +28,6 @@ import type {
   UpdateIssueInput,
 } from '../issue-tracker/types'
 
-// =============================================================================
-// JIRA API Types
-// =============================================================================
-
-interface JiraIssue {
-  id: string
-  key: string
-  self: string
-  fields: {
-    summary: string
-    description?:
-      | {
-          type: string
-          content: Array<{
-            type: string
-            content?: Array<{ type: string; text?: string }>
-          }>
-        }
-      | string
-      | null
-    status: {
-      id: string
-      name: string
-      statusCategory: {
-        key: string // 'new', 'indeterminate', 'done'
-        name: string
-      }
-    }
-    priority?: {
-      id: string
-      name: string
-    }
-    issuetype: {
-      id: string
-      name: string
-      subtask: boolean
-    }
-    assignee?: {
-      accountId: string
-      displayName: string
-      emailAddress?: string
-    }
-    reporter?: {
-      accountId: string
-      displayName: string
-      emailAddress?: string
-    }
-    project: {
-      id: string
-      key: string
-      name: string
-    }
-    labels: string[]
-    created: string
-    updated: string
-  }
-}
-
-interface JiraSearchResponse {
-  issues: JiraIssue[]
-  total: number
-  maxResults: number
-  startAt: number
-}
-
-interface JiraProject {
-  id: string
-  key: string
-  name: string
-}
-
 // =============================================================================
 // Status/Priority Mapping
 // =============================================================================
@@ -170,11 +100,7 @@ const PRIORITY_TO_JIRA: Record<IssuePriority, string> = {
   none: 'Medium',
 }
 
-// =============================================================================
-// Auth Mode Type
-// =============================================================================
-
-export type JiraAuthMode = 'api-token' | 'mcp' | 'none'
+export type { JiraAuthMode } from '../../types/jira'
 
 // =============================================================================
 // JIRA Provider Implementation
@@ -225,7 +151,7 @@ export class JiraProvider implements IssueTrackerProvider {
   async initialize(config: JiraConfig): Promise<void> {
     this.config = config
 
-    // Get credentials from config or environment
+    // JIRA_BASE_URL, JIRA_EMAIL, JIRA_API_TOKEN: JIRA API credentials (fallback from config)
     const baseUrl = config.baseUrl || process.env.JIRA_BASE_URL
     const email = process.env.JIRA_EMAIL
     const apiToken = config.apiKey || process.env.JIRA_API_TOKEN

package/core/server/server.ts

@@ -11,15 +11,12 @@
 import { Hono } from 'hono'
 import { cors } from 'hono/cors'
 import { logger } from 'hono/logger'
-import type { ServerConfig, ServerInstance } from '../types'
+import type { ServerConfig, ServerHandle, ServerInstance } from '../types'
 import { isBun } from '../utils/runtime'
 import { createRoutes } from './routes'
 import { createExtendedRoutes } from './routes-extended'
 import { createSSEManager } from './sse'
 
-// Server handle type that works for both runtimes
-type ServerHandle = { stop: () => void } | null
-
 /**
  * Create and configure the HTTP server
  */
@@ -118,6 +115,7 @@ export function createServer(config: ServerConfig): ServerInstance {
     },
 
     stop() {
+      sseManager.shutdown()
       if (server) {
         server.stop()
         server = null

package/core/server/sse.ts

@@ -4,18 +4,71 @@
  * Handles real-time updates to connected clients.
  * Broadcasts state changes, task updates, and notifications.
  *
- * @version 1.0.0
+ * @version 2.0.0
  */
 
 import type { Context } from 'hono'
 import { streamSSE } from 'hono/streaming'
-import type { SSEClient, SSEManager } from '../types'
+import type { SSEClient, SSEInternalClient, SSEManager } from '../types'
+
+/** Maximum client connection lifetime in ms (1 hour) */
+const MAX_CLIENT_TTL_MS = 60 * 60 * 1000
+
+/** Reaper interval in ms (5 minutes) */
+const REAPER_INTERVAL_MS = 5 * 60 * 1000
+
+/** Heartbeat interval in ms (30 seconds) */
+const HEARTBEAT_INTERVAL_MS = 30_000
 
 /**
  * Create an SSE manager for handling real-time connections
  */
 export function createSSEManager(): SSEManager {
-  const clients = new Map<string, SSEClient>()
+  const clients = new Map<string, SSEInternalClient>()
+  let reaperInterval: ReturnType<typeof setInterval> | null = null
+
+  /**
+   * Single cleanup function — all disconnect paths go through here.
+   * Safe to call multiple times for the same clientId.
+   */
+  function removeClient(clientId: string): void {
+    const entry = clients.get(clientId)
+    if (!entry) return
+
+    clearInterval(entry.heartbeatInterval)
+    clearTimeout(entry.ttlTimeout)
+    entry.abortController.abort()
+    clients.delete(clientId)
+  }
+
+  /** Periodic reaper that removes zombie clients */
+  function startReaper(): void {
+    if (reaperInterval) return
+
+    reaperInterval = setInterval(() => {
+      const now = Date.now()
+      for (const [id, entry] of clients) {
+        const connectedMs = now - new Date(entry.client.connectedAt).getTime()
+        if (connectedMs > MAX_CLIENT_TTL_MS) {
+          removeClient(id)
+        }
+      }
+    }, REAPER_INTERVAL_MS)
+
+    // Don't block process exit
+    if (reaperInterval && typeof reaperInterval === 'object' && 'unref' in reaperInterval) {
+      reaperInterval.unref()
+    }
+  }
+
+  function stopReaper(): void {
+    if (reaperInterval) {
+      clearInterval(reaperInterval)
+      reaperInterval = null
+    }
+  }
+
+  startReaper()
 
   return {
     /**
@@ -24,10 +77,13 @@ export function createSSEManager(): SSEManager {
     handleConnection(c: Context) {
       return streamSSE(c, async (stream) => {
         const clientId = crypto.randomUUID()
+        const connectedAt = new Date().toISOString()
+        const abortController = new AbortController()
 
         // Register client
         const client: SSEClient = {
           id: clientId,
+          connectedAt,
           send: (event, data) => {
             stream.writeSSE({
               event,
@@ -35,44 +91,61 @@ export function createSSEManager(): SSEManager {
             })
           },
           close: () => {
-            clients.delete(clientId)
+            removeClient(clientId)
           },
         }
 
-        clients.set(clientId, client)
+        // Heartbeat — detects dead connections
+        const heartbeatInterval = setInterval(async () => {
+          try {
+            await stream.writeSSE({
+              event: 'heartbeat',
+              data: JSON.stringify({ timestamp: new Date().toISOString() }),
+            })
+          } catch {
+            removeClient(clientId)
+          }
+        }, HEARTBEAT_INTERVAL_MS)
+
+        // TTL — force-disconnect after max lifetime
+        const ttlTimeout = setTimeout(() => {
+          removeClient(clientId)
+        }, MAX_CLIENT_TTL_MS)
+
+        // Don't block process exit
+        if (typeof heartbeatInterval === 'object' && 'unref' in heartbeatInterval) {
+          heartbeatInterval.unref()
+        }
+        if (typeof ttlTimeout === 'object' && 'unref' in ttlTimeout) {
+          ttlTimeout.unref()
+        }
+
+        clients.set(clientId, {
+          client,
+          heartbeatInterval,
+          ttlTimeout,
+          abortController,
+        } as SSEInternalClient)
 
         // Send initial connection event
         await stream.writeSSE({
           event: 'connected',
           data: JSON.stringify({
             clientId,
-            timestamp: new Date().toISOString(),
+            timestamp: connectedAt,
             message: 'Connected to prjct-cli server',
           }),
         })
 
-        // Keep connection alive with heartbeat
-        const heartbeat = setInterval(async () => {
-          try {
-            await stream.writeSSE({
-              event: 'heartbeat',
-              data: JSON.stringify({ timestamp: new Date().toISOString() }),
-            })
-          } catch (_error) {
-            // Client disconnected - expected
-            clearInterval(heartbeat)
-            clients.delete(clientId)
-          }
-        }, 30000) // Every 30 seconds
-
-        // Handle disconnect
+        // Handle stream abort (graceful disconnect)
         stream.onAbort(() => {
-          clearInterval(heartbeat)
-          clients.delete(clientId)
+          removeClient(clientId)
         })
 
-        // Keep stream open indefinitely
-        await new Promise(() => {})
+        // Wait until abort signal fires instead of infinite promise
+        await new Promise<void>((resolve) => {
+          abortController.signal.addEventListener('abort', () => resolve(), { once: true })
+        })
       })
     },
 
@@ -86,12 +159,11 @@ export function createSSEManager(): SSEManager {
         timestamp: new Date().toISOString(),
       }
 
-      for (const client of clients.values()) {
+      for (const [id, entry] of clients) {
         try {
-          client.send(event, message)
-        } catch (_error) {
-          // Client disconnected - expected
-          clients.delete(client.id)
+          entry.client.send(event, message)
+        } catch {
+          removeClient(id)
         }
       }
     },
@@ -102,35 +174,19 @@ export function createSSEManager(): SSEManager {
     getClientCount() {
       return clients.size
     },
+
+    /**
+     * Shut down all clients and stop the reaper.
+     * Called on server stop.
+     */
+    shutdown() {
+      stopReaper()
+      for (const id of [...clients.keys()]) {
+        removeClient(id)
+      }
+    },
   }
 }
 
-/**
- * Event types for SSE broadcasts
- */
-export const SSE_EVENTS = {
-  // Task events
-  TASK_STARTED: 'task:started',
-  TASK_COMPLETED: 'task:completed',
-  TASK_PAUSED: 'task:paused',
-  TASK_RESUMED: 'task:resumed',
-
-  // Feature events
-  FEATURE_CREATED: 'feature:created',
-  FEATURE_SHIPPED: 'feature:shipped',
-
-  // Idea events
-  IDEA_CAPTURED: 'idea:captured',
-  IDEA_CONVERTED: 'idea:converted',
-
-  // State events
-  STATE_UPDATED: 'state:updated',
-  QUEUE_UPDATED: 'queue:updated',
-
-  // System events
-  CONNECTED: 'connected',
-  HEARTBEAT: 'heartbeat',
-  ERROR: 'error',
-} as const
-
-export type SSEEventType = (typeof SSE_EVENTS)[keyof typeof SSE_EVENTS]
+export type { SSEEventType } from '../types/server'
+export { SSE_EVENTS } from '../types/server'

package/core/services/context-generator.ts

@@ -12,50 +12,25 @@
 import fs from 'node:fs/promises'
 import path from 'node:path'
 import pathManager from '../infrastructure/path-manager'
+import type {
+  ContextGeneratorConfig,
+  GitData,
+  ProjectCommands,
+  ProjectStats,
+  SyncAgentInfo,
+} from '../types'
 import { type ContextSources, cite, defaultSources } from '../utils/citations'
 import * as dateHelper from '../utils/date-helper'
 import { mergePreservedSections, validatePreserveBlocks } from '../utils/preserve-sections'
 import { NestedContextResolver } from './nested-context-resolver'
 
-// ============================================================================
-// TYPES
-// ============================================================================
-
-export interface GitData {
-  branch: string
-  commits: number
-}
-
-export interface ProjectStats {
-  name: string
-  version: string
-  ecosystem: string
-  projectType: string
-  fileCount: number
-  languages: string[]
-  frameworks: string[]
-}
-
-export interface Commands {
-  install: string
-  dev: string
-  test: string
-  build: string
-  lint: string
-  format: string
-}
-
-export interface AgentInfo {
-  name: string
-  type: 'workflow' | 'domain'
-  skill?: string
-}
-
-export interface ContextGeneratorConfig {
-  projectId: string
-  projectPath: string
-  globalPath: string
-}
+export type {
+  ContextGeneratorConfig,
+  GitData,
+  ProjectCommands,
+  ProjectStats,
+  SyncAgentInfo,
+} from '../types'
 
 // ============================================================================
 // CONTEXT FILE GENERATOR
@@ -103,8 +78,8 @@ export class ContextFileGenerator {
   async generate(
     git: GitData,
     stats: ProjectStats,
-    commands: Commands,
-    agents: AgentInfo[],
+    commands: ProjectCommands,
+    agents: SyncAgentInfo[],
     sources?: ContextSources
   ): Promise<string[]> {
     const contextPath = path.join(this.config.globalPath, 'context')
@@ -138,8 +113,8 @@ export class ContextFileGenerator {
     contextPath: string,
     git: GitData,
     stats: ProjectStats,
-    commands: Commands,
-    agents: AgentInfo[],
+    commands: ProjectCommands,
+    agents: SyncAgentInfo[],
     sources?: ContextSources
   ): Promise<void> {
     const workflowAgents = agents.filter((a) => a.type === 'workflow').map((a) => a.name)
@@ -348,8 +323,8 @@ ${
   async generateMonorepoContexts(
     git: GitData,
     stats: ProjectStats,
-    commands: Commands,
-    agents: AgentInfo[]
+    commands: ProjectCommands,
+    agents: SyncAgentInfo[]
   ): Promise<string[]> {
     const monoInfo = await pathManager.detectMonorepo(this.config.projectPath)
 
@@ -394,8 +369,8 @@ ${
     resolvedCtx: { content: string; sources: string[]; overrides: string[] },
     git: GitData,
     stats: ProjectStats,
-    commands: Commands,
-    agents: AgentInfo[]
+    commands: ProjectCommands,
+    agents: SyncAgentInfo[]
   ): Promise<string> {
     const workflowAgents = agents.filter((a) => a.type === 'workflow').map((a) => a.name)
     const domainAgents = agents.filter((a) => a.type === 'domain').map((a) => a.name)