prjct-cli 0.47.0 → 0.49.0

package/core/utils/error-messages.ts

@@ -0,0 +1,161 @@
+/**
+ * Error Messages Catalog
+ *
+ * Centralized error messages with context and recovery hints.
+ * Provides consistent, helpful error output across the CLI.
+ *
+ * @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",
+  },
+
+  // Generic
+  UNKNOWN: {
+    message: 'An unexpected error occurred',
+    hint: 'Check the error details and try again',
+  },
+} as const
+
+export type ErrorCode = keyof typeof ERRORS
+
+/**
+ * Get error with optional overrides
+ */
+export function getError(code: ErrorCode, overrides?: Partial<ErrorWithHint>): ErrorWithHint {
+  const base = ERRORS[code]
+  return { ...base, ...overrides }
+}
+
+/**
+ * Create a custom error with hint
+ */
+export function createError(
+  message: string,
+  hint?: string,
+  options?: { file?: string; docs?: string }
+): ErrorWithHint {
+  return {
+    message,
+    hint,
+    ...options,
+  }
+}

package/core/utils/help.ts

@@ -8,7 +8,6 @@
  */
 
 import { CATEGORIES, COMMANDS } from '../commands/command-data'
-import type { CommandMeta } from '../types'
 import { VERSION } from './version'
 
 // ANSI colors

package/core/utils/markdown-builder.ts

@@ -117,7 +117,9 @@ export class MarkdownBuilder {
    * Add multiple list items
    */
   list(items: string[], options?: { checked?: boolean }): this {
-    items.forEach((item) => this.li(item, options))
+    for (const item of items) {
+      this.li(item, options)
+    }
     return this
   }
 
@@ -125,7 +127,9 @@ export class MarkdownBuilder {
    * Add multiple numbered list items
    */
   orderedList(items: string[]): this {
-    items.forEach((item, i) => this.oli(item, i + 1))
+    for (let i = 0; i < items.length; i++) {
+      this.oli(items[i], i + 1)
+    }
     return this
   }
 
@@ -225,7 +229,9 @@ export class MarkdownBuilder {
    * Iterate and build for each item
    */
   each<T>(items: T[], builder: (md: MarkdownBuilder, item: T, index: number) => void): this {
-    items.forEach((item, i) => builder(this, item, i))
+    for (let i = 0; i < items.length; i++) {
+      builder(this, items[i], i)
+    }
     return this
   }
 

package/core/utils/output.ts

@@ -8,6 +8,8 @@
 
 import chalk from 'chalk'
 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
@@ -53,6 +55,7 @@ interface Output {
   spin(msg: string): Output
   done(msg: string, metrics?: OutputMetrics): Output
   fail(msg: string): Output
+  failWithHint(error: ErrorWithHint | ErrorCode): Output
   warn(msg: string): Output
   stop(): Output
   step(current: number, total: number, msg: string): Output
@@ -108,6 +111,25 @@ const out: Output = {
     return this
   },
 
+  // Rich error with context and recovery hint
+  failWithHint(error: ErrorWithHint | ErrorCode) {
+    this.stop()
+    const err = typeof error === 'string' ? getError(error) : error
+    console.error()
+    console.error(`${chalk.red('✗')} ${err.message}`)
+    if (err.file) {
+      console.error(chalk.dim(`  File: ${err.file}`))
+    }
+    if (err.hint) {
+      console.error(chalk.yellow(`  💡 ${err.hint}`))
+    }
+    if (err.docs) {
+      console.error(chalk.dim(`  Docs: ${err.docs}`))
+    }
+    console.error()
+    return this
+  },
+
   warn(msg: string) {
     this.stop()
     if (!quietMode) console.log(`${chalk.yellow('⚠')} ${truncate(msg, 65)}`)
@@ -151,4 +173,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/utils/preserve-sections.ts

@@ -128,7 +128,7 @@ export function mergePreservedSections(newContent: string, oldContent: string):
     merged += '\n\n'
   }
 
-  return merged.trimEnd() + '\n'
+  return `${merged.trimEnd()}\n`
 }
 
 /**

package/core/utils/project-commands.ts

@@ -3,12 +3,6 @@ import type { DetectedProjectCommands } from '../types'
 import * as fileHelper from './file-helper'
 
 type PackageManager = 'npm' | 'pnpm' | 'yarn' | 'bun'
-type DetectedStack = 'js' | 'python' | 'go' | 'rust' | 'dotnet' | 'java' | 'unknown'
-
-interface DetectedCommand {
-  command: string
-  tool: string
-}
 
 interface PackageJson {
   scripts?: Record<string, string>

package/core/utils/subtask-table.ts

@@ -72,7 +72,7 @@ function formatSubtaskLine(
   const domain = `${domainColor}${subtask.domain.padEnd(10)}${RESET}`
   const desc =
     subtask.description.length > 32
-      ? subtask.description.slice(0, 29) + '...'
+      ? `${subtask.description.slice(0, 29)}...`
       : subtask.description.padEnd(32)
 
   let status: string