prjct-cli 0.41.0 → 0.44.0

package/core/commands/commands.ts

@@ -154,8 +154,8 @@ class PrjctCommands {
     return this.analysis.analyze(options, projectPath)
   }
 
-  async sync(projectPath: string = process.cwd()): Promise<CommandResult> {
-    return this.analysis.sync(projectPath)
+  async sync(projectPath: string = process.cwd(), options: { aiTools?: string[] } = {}): Promise<CommandResult> {
+    return this.analysis.sync(projectPath, options)
   }
 
   // ========== Context Commands ==========

package/core/commands/planning.ts

@@ -21,6 +21,7 @@ import {
 import { queueStorage, ideasStorage } from '../storage'
 import authorDetector from '../infrastructure/author-detector'
 import commandInstaller from '../infrastructure/command-installer'
+import { showNextSteps } from '../utils/next-steps'
 
 // Lazy-loaded to avoid circular dependencies
 let _analysisCommands: import('./analysis').AnalysisCommands | null = null
@@ -47,7 +48,7 @@ export class PlanningCommands extends PrjctCommandsBase {
         return { success: false, message: 'Already initialized' }
       }
 
-      out.spin('initializing...')
+      out.step(1, 4, 'Detecting author...')
 
       const detectedAuthor = await authorDetector.detect()
       // Convert null to undefined for createConfig
@@ -59,7 +60,7 @@ export class PlanningCommands extends PrjctCommandsBase {
       const config = await configManager.createConfig(projectPath, author)
       const projectId = config.projectId
 
-      out.spin('creating structure...')
+      out.step(2, 4, 'Creating structure...')
 
       await pathManager.ensureProjectStructure(projectId)
       const globalPath = pathManager.getGlobalProjectPath(projectId)
@@ -91,12 +92,12 @@ export class PlanningCommands extends PrjctCommandsBase {
       const hasCode = await this._detectExistingCode(projectPath)
 
       if (hasCode || !isEmpty) {
-        out.spin('analyzing project...')
+        out.step(3, 4, 'Analyzing project...')
         const analysis = await getAnalysisCommands()
         const analysisResult = await analysis.analyze({}, projectPath)
 
         if (analysisResult.success) {
-          out.spin('generating agents...')
+          out.step(4, 4, 'Generating agents...')
           await analysis.sync(projectPath)
           out.done('initialized')
           return { success: true, mode: 'existing', projectId }
@@ -123,6 +124,7 @@ export class PlanningCommands extends PrjctCommandsBase {
       await commandInstaller.installGlobalConfig()
 
       out.done('initialized')
+      showNextSteps('init')
       return { success: true, projectId }
     } catch (error) {
       out.fail((error as Error).message)
@@ -250,6 +252,7 @@ export class PlanningCommands extends PrjctCommandsBase {
       })
 
       out.done(`bug [${severity}] → ${agent}`)
+      showNextSteps('bug')
 
       return { success: true, bug: description, severity, agent }
     } catch (error) {
@@ -416,6 +419,7 @@ Generated: ${new Date().toLocaleString()}
         })
 
         out.done(`idea captured: ${description.slice(0, 40)}`)
+        showNextSteps('idea')
 
         return { success: true, mode: 'capture', idea: description }
       }

package/core/commands/shipping.ts

@@ -18,6 +18,7 @@ import {
   out
 } from './base'
 import { stateStorage, shippedStorage } from '../storage'
+import { showNextSteps } from '../utils/next-steps'
 
 export class ShippingCommands extends PrjctCommandsBase {
   /**
@@ -70,22 +71,22 @@ export class ShippingCommands extends PrjctCommandsBase {
         featureName = currentTask?.description || 'current work'
       }
 
-      out.spin(`shipping ${featureName}...`)
-
+      // Ship steps with progress indicator
+      out.step(1, 5, `Linting ${featureName}...`)
       const lintResult = await this._runLint(projectPath)
 
-      out.spin('running tests...')
+      out.step(2, 5, 'Running tests...')
       const testResult = await this._runTests(projectPath)
 
-      out.spin('updating version...')
+      out.step(3, 5, 'Updating version...')
       const newVersion = await this._bumpVersion(projectPath)
       await this._updateChangelog(featureName, newVersion, projectPath)
 
-      out.spin('committing...')
+      out.step(4, 5, 'Committing...')
       const commitResult = await this._createShipCommit(featureName, projectPath)
 
       if (commitResult.success) {
-        out.spin('pushing...')
+        out.step(5, 5, 'Pushing...')
         await this._gitPush(projectPath)
       }
 
@@ -116,6 +117,7 @@ export class ShippingCommands extends PrjctCommandsBase {
       }
 
       out.done(`v${newVersion} shipped`)
+      showNextSteps('ship')
 
       return { success: true, feature: featureName, version: newVersion }
     } catch (error) {

package/core/commands/workflow.ts

@@ -20,6 +20,10 @@ import {
 import { stateStorage, queueStorage } from '../storage'
 import { templateExecutor } from '../agentic/template-executor'
 import commandExecutor from '../agentic/command-executor'
+import { showNextSteps, showStateInfo } from '../utils/next-steps'
+import { workflowStateMachine } from '../workflow/state-machine'
+import { linearService } from '../integrations/linear'
+import { getProjectCredentials, getLinearApiKey } from '../utils/project-credentials'
 
 export class WorkflowCommands extends PrjctCommandsBase {
   /**
@@ -45,24 +49,39 @@ export class WorkflowCommands extends PrjctCommandsBase {
           return { success: false, error: result.error }
         }
 
+        // Check if task is a Linear issue ID (e.g., PRJ-139)
+        let linearId: string | undefined
+        let taskDescription = task
+        const linearPattern = /^[A-Z]+-\d+$/
+        if (linearPattern.test(task)) {
+          try {
+            const creds = await getProjectCredentials(projectId)
+            const apiKey = await getLinearApiKey(projectId)
+            if (apiKey && creds.linear?.teamId) {
+              await linearService.initializeFromApiKey(
+                apiKey,
+                creds.linear.teamId
+              )
+              const issue = await linearService.fetchIssue(task)
+              if (issue) {
+                linearId = task
+                taskDescription = `${task}: ${issue.title}`
+                // Mark as in progress in Linear
+                await linearService.markInProgress(task)
+              }
+            }
+          } catch {
+            // Linear fetch failed - continue with task as-is
+          }
+        }
+
         // Write-through: JSON → MD → Event
         await stateStorage.startTask(projectId, {
           id: generateUUID(),
-          description: task,
-          sessionId: generateUUID()
-        })
-
-        // Log orchestrator results if available
-        if (result.orchestratorContext) {
-          const oc = result.orchestratorContext
-          const agentsList = oc.agents.map((a: { name: string }) => a.name).join(', ') || 'none'
-          const domainsList = oc.detectedDomains.join(', ')
-          console.log(`🎯 Orchestrator: ${domainsList} → [${agentsList}]`)
-
-          if (oc.requiresFragmentation && oc.subtasks) {
-            console.log(`   → ${oc.subtasks.length} subtasks created`)
-          }
-        }
+          description: taskDescription,
+          sessionId: generateUUID(),
+          linearId,
+        } as Parameters<typeof stateStorage.startTask>[1])
 
         // Get available agents for backward compatibility
         const availableAgents = await templateExecutor.getAvailableAgents(projectPath)
@@ -70,7 +89,9 @@ export class WorkflowCommands extends PrjctCommandsBase {
           ? availableAgents.join(', ')
           : 'none (run p. sync)'
 
-        out.done(`${task} [specialists: ${agentsList}]`)
+        out.done(`${task}`)
+        showStateInfo('working')
+        showNextSteps('task')
 
         await this.logToMemory(projectPath, 'task_started', {
           task,
@@ -139,7 +160,31 @@ export class WorkflowCommands extends PrjctCommandsBase {
       // Write-through: Complete task (JSON → MD → Event)
       await stateStorage.completeTask(projectId)
 
-      out.done(`${task}${duration ? ` (${duration})` : ''}`)
+      // Sync to Linear if task has linearId
+      const linearId = (currentTask as { linearId?: string }).linearId
+      if (linearId) {
+        try {
+          const creds = await getProjectCredentials(projectId)
+          const apiKey = await getLinearApiKey(projectId)
+          if (apiKey && creds.linear?.teamId) {
+            await linearService.initializeFromApiKey(
+              apiKey,
+              creds.linear.teamId
+            )
+            await linearService.markDone(linearId)
+            out.done(`${task}${duration ? ` (${duration})` : ''} → Linear ✓`)
+          } else {
+            out.done(`${task}${duration ? ` (${duration})` : ''}`)
+          }
+        } catch {
+          // Linear sync failed silently - don't block the workflow
+          out.done(`${task}${duration ? ` (${duration})` : ''}`)
+        }
+      } else {
+        out.done(`${task}${duration ? ` (${duration})` : ''}`)
+      }
+      showStateInfo('completed')
+      showNextSteps('done')
 
       await this.logToMemory(projectPath, 'task_completed', {
         task,
@@ -176,6 +221,7 @@ export class WorkflowCommands extends PrjctCommandsBase {
       }
 
       out.done(`${tasks.length} task${tasks.length !== 1 ? 's' : ''} queued`)
+      showNextSteps('next')
 
       return { success: true, tasks, count: tasks.length }
     } catch (error) {
@@ -210,6 +256,8 @@ export class WorkflowCommands extends PrjctCommandsBase {
 
       const taskDesc = currentTask.description.slice(0, 40)
       out.done(`paused: ${taskDesc}${reason ? ` (${reason})` : ''}`)
+      showStateInfo('paused')
+      showNextSteps('pause')
 
       await this.logToMemory(projectPath, 'task_paused', {
         task: currentTask.description,
@@ -254,6 +302,8 @@ export class WorkflowCommands extends PrjctCommandsBase {
       }
 
       out.done(`resumed: ${resumed.description.slice(0, 40)}`)
+      showStateInfo('working')
+      showNextSteps('resume')
 
       await this.logToMemory(projectPath, 'task_resumed', {
         task: resumed.description,

package/core/index.ts

@@ -118,7 +118,9 @@ async function main(): Promise<void> {
         redo: () => commands.redo(),
         history: () => commands.history(),
         // Setup
-        sync: () => commands.sync(),
+        sync: () => commands.sync(process.cwd(), {
+          aiTools: options.agents ? String(options.agents).split(',') : undefined,
+        }),
         start: () => commands.start(),
         // Context (for Claude templates)
         context: (p) => commands.context(p),

package/core/integrations/issue-tracker/types.ts

@@ -75,10 +75,16 @@ export interface CreateIssueInput {
 }
 
 /**
- * Update input for enriching issues
+ * Update input for issues
  */
 export interface UpdateIssueInput {
+  title?: string
   description?: string
+  priority?: IssuePriority
+  assigneeId?: string | null // null to unassign
+  stateId?: string
+  projectId?: string
+  labels?: string[]
   // Provider-specific: may update custom fields for AC, etc.
   customFields?: Record<string, unknown>
 }

package/core/integrations/linear/client.ts

@@ -84,7 +84,8 @@ export class LinearProvider implements IssueTrackerProvider {
     // Verify connection
     try {
       const viewer = await this.sdk.viewer
-      console.log(`[linear] Connected as ${viewer.name} (${viewer.email})`)
+      // Use stderr for logs to not break JSON output
+      console.error(`[linear] Connected as ${viewer.name} (${viewer.email})`)
     } catch (error) {
       this.sdk = null
       throw new Error(`Linear connection failed: ${(error as Error).message}`)
@@ -93,16 +94,28 @@ export class LinearProvider implements IssueTrackerProvider {
 
   /**
    * Get issues assigned to current user
+   * Filters by configured team if defaultTeamId is set
    */
   async fetchAssignedIssues(options?: FetchOptions): Promise<Issue[]> {
     if (!this.sdk) throw new Error('Linear not initialized')
 
     const viewer = await this.sdk.viewer
+
+    // Build filter - always filter by team if configured
+    const filter: Record<string, unknown> = {}
+
+    if (!options?.includeCompleted) {
+      filter.state = { type: { nin: ['completed', 'canceled'] } }
+    }
+
+    // Filter by configured team to only show relevant issues
+    if (this.config?.defaultTeamId) {
+      filter.team = { id: { eq: this.config.defaultTeamId } }
+    }
+
     const assignedIssues = await viewer.assignedIssues({
       first: options?.limit || 50,
-      filter: options?.includeCompleted
-        ? undefined
-        : { state: { type: { nin: ['completed', 'canceled'] } } },
+      filter: Object.keys(filter).length > 0 ? filter : undefined,
     })
 
     return Promise.all(
@@ -128,28 +141,34 @@ export class LinearProvider implements IssueTrackerProvider {
   }
 
   /**
-   * Get a single issue by ID or identifier (e.g., "ENG-123")
+   * Get a single issue by ID or identifier (e.g., "PRJ-123")
    */
   async fetchIssue(id: string): Promise<Issue | null> {
     if (!this.sdk) throw new Error('Linear not initialized')
 
     try {
-      // Check if it looks like an identifier (e.g., "ENG-123")
+      // Check if it looks like an identifier (e.g., "PRJ-123")
       if (id.includes('-') && /^[A-Z]+-\d+$/.test(id)) {
-        // Use raw GraphQL to search by identifier
-        const result = await this.sdk.client.rawRequest(`
-          query SearchByIdentifier($query: String!) {
-            searchIssues(query: $query, first: 1) {
-              nodes {
-                id
-              }
-            }
-          }
-        `, { query: id }) as { data?: { searchIssues?: { nodes?: Array<{ id: string }> } } }
-
-        if (result.data?.searchIssues?.nodes?.length) {
-          const issue = await this.sdk.issue(result.data.searchIssues.nodes[0].id)
-          return this.mapIssue(issue)
+        // Parse identifier into team key and issue number
+        const match = id.match(/^([A-Z]+)-(\d+)$/)
+        if (!match) return null
+
+        const [, teamKey, numberStr] = match
+        const issueNumber = parseInt(numberStr, 10)
+
+        // Find team by key
+        const teams = await this.sdk.teams({ first: 50 })
+        const team = teams.nodes.find((t) => t.key === teamKey)
+        if (!team) return null
+
+        // Query issue by team and number
+        const issues = await team.issues({
+          first: 1,
+          filter: { number: { eq: issueNumber } },
+        })
+
+        if (issues.nodes.length > 0) {
+          return this.mapIssue(issues.nodes[0])
         }
         return null
       }
@@ -197,15 +216,28 @@ export class LinearProvider implements IssueTrackerProvider {
   async updateIssue(id: string, input: UpdateIssueInput): Promise<Issue> {
     if (!this.sdk) throw new Error('Linear not initialized')
 
-    // Get the issue first to get UUID
+    // Get the issue first to get UUID (if identifier like PRJ-123 was passed)
     const issue = await this.fetchIssue(id)
     if (!issue) {
       throw new Error(`Issue ${id} not found`)
     }
 
-    await this.sdk.updateIssue(issue.id, {
-      description: input.description,
-    })
+    // Build update payload with all supported fields
+    const updatePayload: Record<string, unknown> = {}
+
+    if (input.title !== undefined) updatePayload.title = input.title
+    if (input.description !== undefined) updatePayload.description = input.description
+    if (input.priority !== undefined) updatePayload.priority = PRIORITY_TO_LINEAR[input.priority]
+    if (input.assigneeId !== undefined) updatePayload.assigneeId = input.assigneeId
+    if (input.stateId !== undefined) updatePayload.stateId = input.stateId
+    if (input.projectId !== undefined) updatePayload.projectId = input.projectId
+
+    // Handle labels - need to resolve names to IDs
+    if (input.labels !== undefined && issue.team) {
+      updatePayload.labelIds = await this.resolveLabelIds(issue.team.id, input.labels)
+    }
+
+    await this.sdk.updateIssue(issue.id, updatePayload)
 
     // Fetch updated issue
     const updated = await this.fetchIssue(issue.id)

package/core/integrations/linear/index.ts

@@ -9,6 +9,9 @@ export { LinearProvider, linearProvider } from './client'
 // Service layer with caching (preferred API)
 export { LinearService, linearService } from './service'
 
+// Sync layer for bidirectional sync with issues.json
+export { LinearSync, linearSync } from './sync'
+
 // Cache utilities
 export {
   issueCache,