prjct-cli 1.6.8 → 1.6.9

package/core/utils/error-messages.ts

@@ -2,151 +2,17 @@
  * Error Messages Catalog
  *
  * Centralized error messages with context and recovery hints.
- * Provides consistent, helpful error output across the CLI.
+ * Types and catalog live in core/types/errors.ts.
  *
  * @see PRJ-131
  * @module utils/error-messages
  */
 
-export interface ErrorWithHint {
-  message: string
-  hint?: string
-  file?: string
-  docs?: string
-  code?: string
-}
-
-/**
- * Common error messages with recovery hints
- */
-export const ERRORS = {
-  // Project errors
-  NO_PROJECT: {
-    message: 'No prjct project found in this directory',
-    hint: "Run 'prjct init' to set up a new project",
-    file: '.prjct/prjct.config.json',
-  },
-
-  NO_PROJECT_ID: {
-    message: 'Project ID not found',
-    hint: "Run 'prjct init' or check .prjct/prjct.config.json",
-    file: '.prjct/prjct.config.json',
-  },
-
-  CONFIG_NOT_FOUND: {
-    message: 'Configuration file not found',
-    hint: "Run 'prjct init' to create project configuration",
-    file: '.prjct/prjct.config.json',
-  },
-
-  CONFIG_INVALID: {
-    message: 'Invalid configuration file',
-    hint: 'Check JSON syntax or delete .prjct/ and run init again',
-    file: '.prjct/prjct.config.json',
-  },
-
-  // Git errors
-  GIT_NOT_FOUND: {
-    message: 'Git repository not detected',
-    hint: "Run 'git init' first, then 'prjct init'",
-  },
-
-  GIT_NO_COMMITS: {
-    message: 'No commits in repository',
-    hint: 'Make an initial commit before using prjct',
-  },
-
-  GIT_DIRTY: {
-    message: 'Working directory has uncommitted changes',
-    hint: "Commit or stash changes, or use '--force' to override",
-  },
-
-  GIT_ON_MAIN: {
-    message: 'Cannot ship from main/master branch',
-    hint: 'Create a feature branch first: git checkout -b feature/your-feature',
-  },
-
-  GIT_OPERATION_FAILED: {
-    message: 'Git operation failed',
-    hint: 'Check git status and resolve any conflicts',
-  },
-
-  // Auth errors
-  GH_NOT_AUTHENTICATED: {
-    message: 'GitHub CLI not authenticated',
-    hint: "Run 'gh auth login' to authenticate",
-    docs: 'https://cli.github.com/manual/gh_auth_login',
-  },
-
-  LINEAR_NOT_CONFIGURED: {
-    message: 'Linear integration not configured',
-    hint: "Run 'p. linear setup' to configure Linear",
-  },
-
-  LINEAR_API_ERROR: {
-    message: 'Linear API error',
-    hint: 'Check your API key or network connection',
-  },
-
-  // Task errors
-  NO_ACTIVE_TASK: {
-    message: 'No active task',
-    hint: 'Start a task with \'p. task "description"\'',
-  },
-
-  TASK_ALREADY_ACTIVE: {
-    message: 'A task is already in progress',
-    hint: "Complete it with 'p. done' or pause with 'p. pause'",
-  },
-
-  // Sync errors
-  SYNC_FAILED: {
-    message: 'Project sync failed',
-    hint: 'Check file permissions and try again',
-  },
-
-  // Ship errors
-  NOTHING_TO_SHIP: {
-    message: 'Nothing to ship',
-    hint: 'Make some changes first, then run ship',
-  },
-
-  PR_CREATE_FAILED: {
-    message: 'Failed to create pull request',
-    hint: 'Check GitHub auth and remote configuration',
-  },
-
-  // Provider errors
-  NO_AI_PROVIDER: {
-    message: 'No AI provider detected',
-    hint: "Install Claude Code or Gemini CLI, then run 'prjct start'",
-    docs: 'https://prjct.app/docs',
-  },
-
-  PROVIDER_NOT_CONFIGURED: {
-    message: 'AI provider not configured for prjct',
-    hint: "Run 'prjct start' to configure your provider",
-  },
-
-  // Command errors
-  UNKNOWN_COMMAND: {
-    message: 'Unknown command',
-    hint: "Run 'prjct --help' to see available commands",
-  },
-
-  MISSING_PARAM: {
-    message: 'Missing required parameter',
-    hint: 'Check command usage below',
-  },
-
-  // Generic
-  UNKNOWN: {
-    message: 'An unexpected error occurred',
-    hint: 'Check the error details and try again',
-  },
-} as const
+import type { ErrorCode, ErrorWithHint } from '../types/errors'
+import { ERRORS } from '../types/errors'
 
-export type ErrorCode = keyof typeof ERRORS
+export type { ErrorCode, ErrorWithHint } from '../types/errors'
+export { ERRORS } from '../types/errors'
 
 /**
  * Get error with optional overrides

package/core/utils/logger.ts

@@ -16,17 +16,7 @@
  *   log.error('Failed to load', error.message)
  */
 
-type LogLevel = 'error' | 'warn' | 'info' | 'debug'
-type LogFunction = (...args: unknown[]) => void
-
-interface Logger {
-  error: LogFunction
-  warn: LogFunction
-  info: LogFunction
-  debug: LogFunction
-  isEnabled: () => boolean
-  level: () => LogLevel | 'disabled'
-}
+import type { LogFunction, Logger, LogLevel } from '../types/logger'
 
 const LEVELS: Record<LogLevel, number> = { error: 0, warn: 1, info: 2, debug: 3 }
 const TRUTHY_VALUES = new Set(['1', 'true', '*'])
@@ -36,6 +26,8 @@ const TRUTHY_VALUES = new Set(['1', 'true', '*'])
  * Returns -1 (disabled) or a level from LEVELS
  */
 function getLogLevel(): { level: number; name: LogLevel | 'disabled' } {
+  // PRJCT_DEBUG (primary) or DEBUG (fallback): Enable debug logging
+  // Values: '1', 'true', a log level name, or 'prjct' to match
   const debugEnv = process.env.PRJCT_DEBUG || process.env.DEBUG || ''
 
   // Disabled if empty

package/core/utils/output.ts

@@ -11,31 +11,22 @@
 
 import chalk from 'chalk'
 import { OUTPUT_LIMITS } from '../constants'
+import type { ErrorCode, ErrorWithHint } from '../types/errors'
+import type { Output, OutputMetrics, OutputTier, TierConfig } from '../types/output'
 import branding from './branding'
-import type { ErrorCode, ErrorWithHint } from './error-messages'
 import { getError } from './error-messages'
 
 const _FRAMES = branding.spinner.frames
 const SPEED = branding.spinner.speed
 
-/**
- * Output tier configuration
- * Controls verbosity of CLI output
- */
-export type OutputTier = 'silent' | 'minimal' | 'compact' | 'verbose'
-
-export interface TierConfig {
-  maxLines: number
-  maxCharsPerLine: number
-  showMetrics: boolean
-}
+export type { Output, OutputMetrics, OutputTier, TierConfig } from '../types/output'
 
 export const OUTPUT_TIERS: Record<OutputTier, TierConfig> = {
   silent: { maxLines: 0, maxCharsPerLine: 0, showMetrics: false },
   minimal: { maxLines: 1, maxCharsPerLine: 65, showMetrics: false },
   compact: { maxLines: 4, maxCharsPerLine: 80, showMetrics: true },
   verbose: { maxLines: Infinity, maxCharsPerLine: Infinity, showMetrics: true },
-}
+} as const
 
 // Current output tier (default: compact for human-readable output)
 let currentTier: OutputTier = 'compact'
@@ -184,36 +175,6 @@ export function formatForHuman(data: unknown): string {
 const clear = (): boolean =>
   process.stdout.isTTY ? process.stdout.write(`\r${' '.repeat(OUTPUT_LIMITS.CLEAR_WIDTH)}\r`) : true
 
-/**
- * Metrics to display after command completion
- * Shows value provided by prjct (compression, agent count, etc.)
- */
-interface OutputMetrics {
-  agents?: number // Number of agents used
-  reduction?: number // Context reduction percentage
-  tokens?: number // Token count (in thousands)
-}
-
-interface Output {
-  start(): Output
-  end(): Output
-  spin(msg: string): Output
-  done(msg: string, metrics?: OutputMetrics): Output
-  fail(msg: string): Output
-  failWithHint(error: ErrorWithHint | ErrorCode): Output
-  warn(msg: string): Output
-  info(msg: string): Output
-  debug(msg: string): Output
-  success(msg: string, metrics?: OutputMetrics): Output
-  list(items: string[], options?: { bullet?: string; indent?: number }): Output
-  table(rows: Array<Record<string, string | number>>, options?: { header?: boolean }): Output
-  box(title: string, content: string): Output
-  section(title: string): Output
-  stop(): Output
-  step(current: number, total: number, msg: string): Output
-  progress(current: number, total: number, msg?: string): Output
-}
-
 const out: Output = {
   // Branding: Show header at start
   start() {
@@ -273,7 +234,7 @@ const out: Output = {
   // Rich error with context and recovery hint
   failWithHint(error: ErrorWithHint | ErrorCode) {
     this.stop()
-    const err = typeof error === 'string' ? getError(error) : error
+    const err = typeof error === 'string' ? getError(error as ErrorCode) : error
     console.error()
     console.error(`${ICONS.fail} ${err.message}`)
     if (err.file) {
@@ -305,6 +266,7 @@ const out: Output = {
   // Debug message (only if DEBUG=1 or DEBUG=true)
   debug(msg: string) {
     this.stop()
+    // DEBUG: Enable debug output (values: '1' or 'true')
     const debugEnabled = process.env.DEBUG === '1' || process.env.DEBUG === 'true'
     if (!quietMode && debugEnabled) {
       console.log(`${ICONS.debug} ${chalk.dim(msg)}`)
@@ -436,7 +398,6 @@ const out: Output = {
   },
 }
 
-export type { OutputMetrics }
 export type { ErrorCode, ErrorWithHint } from './error-messages'
 export { createError, ERRORS, getError } from './error-messages'
 export default out

package/core/workflow/workflow-preferences.ts

@@ -18,28 +18,24 @@ import { promisify } from 'node:util'
 import chalk from 'chalk'
 import memorySystem from '../agentic/memory-system'
 import { WORKFLOW_HELP } from '../constants'
+import type {
+  HookCommand,
+  HookPhase,
+  HookResult,
+  PreferenceScope,
+  WorkflowPreference,
+} from '../types'
 import { getErrorMessage } from '../types/fs'
 
 const execAsync = promisify(exec)
 
-export type PreferenceScope = 'permanent' | 'session' | 'once'
-export type HookPhase = 'before' | 'after' | 'skip'
-export type HookCommand = 'task' | 'done' | 'ship' | 'sync'
-
-export interface WorkflowPreference {
-  hook: HookPhase
-  command: HookCommand
-  action: string // command to run or 'true' for skip
-  scope: PreferenceScope
-  createdAt: string
-}
-
-export interface HookResult {
-  success: boolean
-  failed?: string
-  skipped?: string[]
-  output?: string
-}
+export type {
+  HookCommand,
+  HookPhase,
+  HookResult,
+  PreferenceScope,
+  WorkflowPreference,
+} from '../types'
 
 // Session and once preferences (in-memory)
 const sessionPreferences: Map<string, WorkflowPreference> = new Map()

package/dist/bin/prjct.mjs

@@ -2020,6 +2020,13 @@ var init_logger = __esm({
   }
 });
 
+// core/types/server.ts
+var init_server = __esm({
+  "core/types/server.ts"() {
+    "use strict";
+  }
+});
+
 // core/constants/index.ts
 function getTimeout(key) {
   const envVar = `PRJCT_TIMEOUT_${key}`;
@@ -2183,24 +2190,12 @@ var init_branding = __esm({
   }
 });
 
-// core/utils/error-messages.ts
-function getError(code, overrides) {
-  const base = ERRORS[code];
-  return { ...base, ...overrides };
-}
-function createError(message, hint, options) {
-  return {
-    message,
-    hint,
-    ...options
-  };
-}
+// core/types/errors.ts
 var ERRORS;
-var init_error_messages = __esm({
-  "core/utils/error-messages.ts"() {
+var init_errors2 = __esm({
+  "core/types/errors.ts"() {
     "use strict";
     ERRORS = {
-      // Project errors
       NO_PROJECT: {
         message: "No prjct project found in this directory",
         hint: "Run 'prjct init' to set up a new project",
@@ -2221,7 +2216,6 @@ var init_error_messages = __esm({
         hint: "Check JSON syntax or delete .prjct/ and run init again",
         file: ".prjct/prjct.config.json"
       },
-      // Git errors
       GIT_NOT_FOUND: {
         message: "Git repository not detected",
         hint: "Run 'git init' first, then 'prjct init'"
@@ -2242,7 +2236,6 @@ var init_error_messages = __esm({
         message: "Git operation failed",
         hint: "Check git status and resolve any conflicts"
       },
-      // Auth errors
       GH_NOT_AUTHENTICATED: {
         message: "GitHub CLI not authenticated",
         hint: "Run 'gh auth login' to authenticate",
@@ -2256,7 +2249,6 @@ var init_error_messages = __esm({
         message: "Linear API error",
         hint: "Check your API key or network connection"
       },
-      // Task errors
       NO_ACTIVE_TASK: {
         message: "No active task",
         hint: `Start a task with 'p. task "description"'`
@@ -2265,12 +2257,10 @@ var init_error_messages = __esm({
         message: "A task is already in progress",
         hint: "Complete it with 'p. done' or pause with 'p. pause'"
       },
-      // Sync errors
       SYNC_FAILED: {
         message: "Project sync failed",
         hint: "Check file permissions and try again"
       },
-      // Ship errors
       NOTHING_TO_SHIP: {
         message: "Nothing to ship",
         hint: "Make some changes first, then run ship"
@@ -2279,7 +2269,6 @@ var init_error_messages = __esm({
         message: "Failed to create pull request",
         hint: "Check GitHub auth and remote configuration"
       },
-      // Provider errors
       NO_AI_PROVIDER: {
         message: "No AI provider detected",
         hint: "Install Claude Code or Gemini CLI, then run 'prjct start'",
@@ -2289,7 +2278,6 @@ var init_error_messages = __esm({
         message: "AI provider not configured for prjct",
         hint: "Run 'prjct start' to configure your provider"
       },
-      // Command errors
       UNKNOWN_COMMAND: {
         message: "Unknown command",
         hint: "Run 'prjct --help' to see available commands"
@@ -2298,12 +2286,31 @@ var init_error_messages = __esm({
         message: "Missing required parameter",
         hint: "Check command usage below"
       },
-      // Generic
       UNKNOWN: {
         message: "An unexpected error occurred",
         hint: "Check the error details and try again"
       }
     };
+  }
+});
+
+// core/utils/error-messages.ts
+function getError(code, overrides) {
+  const base = ERRORS[code];
+  return { ...base, ...overrides };
+}
+function createError(message, hint, options) {
+  return {
+    message,
+    hint,
+    ...options
+  };
+}
+var init_error_messages = __esm({
+  "core/utils/error-messages.ts"() {
+    "use strict";
+    init_errors2();
+    init_errors2();
     __name(getError, "getError");
     __name(createError, "createError");
   }
@@ -13320,9 +13327,11 @@ var init_types3 = __esm({
     "use strict";
     init_agentic();
     init_bus();
+    init_errors2();
     init_fs();
     init_integrations();
     init_memory();
+    init_server();
   }
 });
 
@@ -22952,13 +22961,7 @@ You are the ${name} expert for this project. Apply best practices for the detect
           projectPath: this.projectPath,
           globalPath: this.globalPath
         });
-        return generator.generate(
-          { branch: git.branch, commits: git.commits },
-          stats,
-          commands,
-          agents,
-          sources
-        );
+        return generator.generate(git, stats, commands, agents, sources);
       }
       // ==========================================================================
       // PROJECT.JSON UPDATE
@@ -28646,7 +28649,7 @@ var require_package = __commonJS({
   "package.json"(exports, module) {
     module.exports = {
       name: "prjct-cli",
-      version: "1.6.8",
+      version: "1.6.9",
       description: "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
       main: "core/index.ts",
       bin: {
@@ -29665,9 +29668,47 @@ function createExtendedRoutes() {
 __name(createExtendedRoutes, "createExtendedRoutes");
 
 // core/server/sse.ts
+init_server();
 import { streamSSE } from "hono/streaming";
+var MAX_CLIENT_TTL_MS = 60 * 60 * 1e3;
+var REAPER_INTERVAL_MS = 5 * 60 * 1e3;
+var HEARTBEAT_INTERVAL_MS = 3e4;
 function createSSEManager() {
   const clients = /* @__PURE__ */ new Map();
+  let reaperInterval = null;
+  function removeClient(clientId) {
+    const entry = clients.get(clientId);
+    if (!entry) return;
+    clearInterval(entry.heartbeatInterval);
+    clearTimeout(entry.ttlTimeout);
+    entry.abortController.abort();
+    clients.delete(clientId);
+  }
+  __name(removeClient, "removeClient");
+  function startReaper() {
+    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);
+    if (reaperInterval && typeof reaperInterval === "object" && "unref" in reaperInterval) {
+      reaperInterval.unref();
+    }
+  }
+  __name(startReaper, "startReaper");
+  function stopReaper() {
+    if (reaperInterval) {
+      clearInterval(reaperInterval);
+      reaperInterval = null;
+    }
+  }
+  __name(stopReaper, "stopReaper");
+  startReaper();
   return {
     /**
      * Handle a new SSE connection
@@ -29675,8 +29716,11 @@ function createSSEManager() {
     handleConnection(c) {
       return streamSSE(c, async (stream) => {
         const clientId = crypto.randomUUID();
+        const connectedAt = (/* @__PURE__ */ new Date()).toISOString();
+        const abortController = new AbortController();
         const client = {
           id: clientId,
+          connectedAt,
           send: /* @__PURE__ */ __name((event, data) => {
             stream.writeSSE({
               event,
@@ -29684,34 +29728,47 @@ function createSSEManager() {
             });
           }, "send"),
           close: /* @__PURE__ */ __name(() => {
-            clients.delete(clientId);
+            removeClient(clientId);
           }, "close")
         };
-        clients.set(clientId, client);
+        const heartbeatInterval = setInterval(async () => {
+          try {
+            await stream.writeSSE({
+              event: "heartbeat",
+              data: JSON.stringify({ timestamp: (/* @__PURE__ */ new Date()).toISOString() })
+            });
+          } catch {
+            removeClient(clientId);
+          }
+        }, HEARTBEAT_INTERVAL_MS);
+        const ttlTimeout = setTimeout(() => {
+          removeClient(clientId);
+        }, MAX_CLIENT_TTL_MS);
+        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
+        });
         await stream.writeSSE({
           event: "connected",
           data: JSON.stringify({
             clientId,
-            timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+            timestamp: connectedAt,
             message: "Connected to prjct-cli server"
           })
         });
-        const heartbeat = setInterval(async () => {
-          try {
-            await stream.writeSSE({
-              event: "heartbeat",
-              data: JSON.stringify({ timestamp: (/* @__PURE__ */ new Date()).toISOString() })
-            });
-          } catch (_error) {
-            clearInterval(heartbeat);
-            clients.delete(clientId);
-          }
-        }, 3e4);
         stream.onAbort(() => {
-          clearInterval(heartbeat);
-          clients.delete(clientId);
+          removeClient(clientId);
         });
-        await new Promise(() => {
+        await new Promise((resolve) => {
+          abortController.signal.addEventListener("abort", () => resolve(), { once: true });
         });
       });
     },
@@ -29724,11 +29781,11 @@ function createSSEManager() {
         data,
         timestamp: (/* @__PURE__ */ new Date()).toISOString()
       };
-      for (const client of clients.values()) {
+      for (const [id, entry] of clients) {
         try {
-          client.send(event, message);
-        } catch (_error) {
-          clients.delete(client.id);
+          entry.client.send(event, message);
+        } catch {
+          removeClient(id);
         }
       }
     },
@@ -29737,6 +29794,16 @@ function createSSEManager() {
      */
     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);
+      }
     }
   };
 }
@@ -29818,6 +29885,7 @@ function createServer(config) {
       console.log(`   Dashboard: http://localhost:${port}`);
     },
     stop() {
+      sseManager.shutdown();
       if (server) {
         server.stop();
         server = null;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "prjct-cli",
-  "version": "1.6.8",
+  "version": "1.6.9",
   "description": "Context layer for AI agents. Project context for Claude Code, Gemini CLI, and more.",
   "main": "core/index.ts",
   "bin": {