prjct-cli 0.42.0 → 0.44.1

package/core/infrastructure/ai-provider.ts

@@ -283,45 +283,20 @@ export function hasProviderConfig(provider: AIProviderName): boolean {
  * Get provider-specific branding
  */
 export function getProviderBranding(provider: AIProviderName): ProviderBranding {
-  const config = Providers[provider]
-
-  if (provider === 'gemini') {
-    return {
-      commitFooter: `🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Gemini](${config.websiteUrl})`,
-      signature: '⚡ prjct + Gemini',
-    }
-  }
-
-  if (provider === 'cursor') {
-    return {
-      commitFooter: `🤖 Generated with [p/](https://www.prjct.app/)
-Built with [Cursor](${config.websiteUrl})`,
-      signature: '⚡ prjct + Cursor',
-    }
-  }
-
-  if (provider === 'antigravity') {
-    return {
-      commitFooter: `🤖 Generated with [p/](https://www.prjct.app/)
-Powered by [Antigravity](${config.websiteUrl})`,
-      signature: '⚡ prjct + Antigravity',
-    }
-  }
-
-  if (provider === 'windsurf') {
-    return {
-      commitFooter: `🤖 Generated with [p/](https://www.prjct.app/)
-Built with [Windsurf](${config.websiteUrl})`,
-      signature: '⚡ prjct + Windsurf',
-    }
+  // Generic commit footer for all providers
+  const commitFooter = `Generated with [p/](https://www.prjct.app/)`
+
+  const signatures: Record<AIProviderName, string> = {
+    claude: '⚡ prjct + Claude',
+    gemini: '⚡ prjct + Gemini',
+    cursor: '⚡ prjct + Cursor',
+    antigravity: '⚡ prjct + Antigravity',
+    windsurf: '⚡ prjct + Windsurf',
   }
 
-  // Default: Claude
   return {
-    commitFooter: `🤖 Generated with [p/](https://www.prjct.app/)
-Designed for [Claude](${config.websiteUrl})`,
-    signature: '⚡ prjct + Claude',
+    commitFooter,
+    signature: signatures[provider] || '⚡ prjct',
   }
 }
 

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,

package/core/integrations/linear/sync.ts

@@ -0,0 +1,313 @@
+/**
+ * Linear Sync Layer
+ *
+ * Bidirectional sync between Linear and local prjct storage.
+ * Uses issues.json as local cache with 30-minute staleness.
+ *
+ * Architecture:
+ *   Linear (source of truth)
+ *          ↕
+ *     Sync Layer (this file)
+ *          ↕
+ *   storage/issues.json ← FULL COPY of Linear issues
+ *          ↕
+ *   state.json.currentTask.linearId ← DIRECT LINK
+ */
+
+import { readFile, writeFile, mkdir } from 'fs/promises'
+import { existsSync } from 'fs'
+import { join } from 'path'
+import { linearService } from './service'
+import { getProjectPath } from '../../schemas/schemas'
+import {
+  type IssuesJson,
+  type CachedIssue,
+  type SyncResult,
+  createEmptyIssues,
+  parseIssues,
+} from '../../schemas/issues'
+import type { Issue } from '../issue-tracker/types'
+
+// Default staleness threshold: 30 minutes
+const DEFAULT_STALE_AFTER = 30 * 60 * 1000
+
+export class LinearSync {
+  /**
+   * Pull all assigned issues from Linear and store in issues.json
+   * This is the main sync operation - call on `p. sync`
+   */
+  async pullAll(projectId: string): Promise<SyncResult> {
+    const storagePath = join(getProjectPath(projectId), 'storage')
+    const issuesPath = join(storagePath, 'issues.json')
+
+    // Ensure storage directory exists
+    if (!existsSync(storagePath)) {
+      await mkdir(storagePath, { recursive: true })
+    }
+
+    const timestamp = new Date().toISOString()
+    const errors: Array<{ issueId: string; error: string }> = []
+
+    try {
+      // Fetch all assigned issues from Linear
+      const issues = await linearService.fetchAssignedIssues({ limit: 100 })
+
+      // Convert to cached format
+      const issuesMap: Record<string, CachedIssue> = {}
+      for (const issue of issues) {
+        try {
+          issuesMap[issue.externalId] = this.toCachedIssue(issue, timestamp)
+        } catch (err) {
+          errors.push({
+            issueId: issue.externalId || issue.id,
+            error: (err as Error).message,
+          })
+        }
+      }
+
+      // Write to issues.json
+      const issuesJson: IssuesJson = {
+        provider: 'linear',
+        lastSync: timestamp,
+        staleAfter: DEFAULT_STALE_AFTER,
+        issues: issuesMap,
+      }
+
+      await writeFile(issuesPath, JSON.stringify(issuesJson, null, 2))
+
+      return {
+        provider: 'linear',
+        fetched: issues.length,
+        updated: Object.keys(issuesMap).length,
+        errors,
+        timestamp,
+      }
+    } catch (err) {
+      errors.push({
+        issueId: 'all',
+        error: (err as Error).message,
+      })
+      return {
+        provider: 'linear',
+        fetched: 0,
+        updated: 0,
+        errors,
+        timestamp,
+      }
+    }
+  }
+
+  /**
+   * Get issue from local cache, fetch from API if not found or stale
+   * Local-first approach for performance
+   */
+  async getIssue(projectId: string, identifier: string): Promise<CachedIssue | null> {
+    const issuesJson = await this.loadIssues(projectId)
+
+    // Check local cache first
+    if (issuesJson && issuesJson.issues[identifier]) {
+      const cachedIssue = issuesJson.issues[identifier]
+
+      // Check if cached issue is still fresh (within fetchedAt + some grace period)
+      const fetchedAt = new Date(cachedIssue.fetchedAt).getTime()
+      const now = Date.now()
+      const issueStaleness = 10 * 60 * 1000 // 10 minutes for individual issues
+
+      if (now - fetchedAt < issueStaleness) {
+        return cachedIssue
+      }
+    }
+
+    // Not in cache or stale - fetch from API and update cache
+    try {
+      const issue = await linearService.fetchIssue(identifier)
+      if (!issue) return null
+
+      const timestamp = new Date().toISOString()
+      const cachedIssue = this.toCachedIssue(issue, timestamp)
+
+      // Update cache with this single issue
+      await this.updateIssueInCache(projectId, identifier, cachedIssue)
+
+      return cachedIssue
+    } catch {
+      // API failed, return cached version if available (even if stale)
+      if (issuesJson?.issues[identifier]) {
+        return issuesJson.issues[identifier]
+      }
+      return null
+    }
+  }
+
+  /**
+   * Get issue from local cache ONLY (no API call)
+   * Use for fast lookups when you know the issue should be cached
+   */
+  async getIssueLocal(projectId: string, identifier: string): Promise<CachedIssue | null> {
+    const issuesJson = await this.loadIssues(projectId)
+    return issuesJson?.issues[identifier] || null
+  }
+
+  /**
+   * Push local status change to Linear
+   * Called when task status changes (in_progress, done)
+   */
+  async pushStatus(
+    projectId: string,
+    identifier: string,
+    status: 'in_progress' | 'done'
+  ): Promise<void> {
+    // Update Linear
+    if (status === 'in_progress') {
+      await linearService.markInProgress(identifier)
+    } else if (status === 'done') {
+      await linearService.markDone(identifier)
+    }
+
+    // Update local cache to reflect the change
+    const issuesJson = await this.loadIssues(projectId)
+    if (issuesJson?.issues[identifier]) {
+      const cachedStatus = status === 'done' ? 'done' : 'in_progress'
+      issuesJson.issues[identifier].status = cachedStatus
+      issuesJson.issues[identifier].fetchedAt = new Date().toISOString()
+
+      await this.saveIssues(projectId, issuesJson)
+    }
+  }
+
+  /**
+   * Check if the local issues cache is stale
+   * Staleness = lastSync is older than staleAfter threshold
+   */
+  async isStale(projectId: string): Promise<boolean> {
+    const issuesJson = await this.loadIssues(projectId)
+
+    if (!issuesJson || !issuesJson.lastSync) {
+      return true // No cache = stale
+    }
+
+    const lastSyncTime = new Date(issuesJson.lastSync).getTime()
+    const now = Date.now()
+    const staleAfter = issuesJson.staleAfter || DEFAULT_STALE_AFTER
+
+    return now - lastSyncTime > staleAfter
+  }
+
+  /**
+   * Get sync status for display
+   */
+  async getSyncStatus(projectId: string): Promise<{
+    hasCache: boolean
+    lastSync: string | null
+    issueCount: number
+    isStale: boolean
+  }> {
+    const issuesJson = await this.loadIssues(projectId)
+
+    if (!issuesJson) {
+      return {
+        hasCache: false,
+        lastSync: null,
+        issueCount: 0,
+        isStale: true,
+      }
+    }
+
+    return {
+      hasCache: true,
+      lastSync: issuesJson.lastSync || null,
+      issueCount: Object.keys(issuesJson.issues).length,
+      isStale: await this.isStale(projectId),
+    }
+  }
+
+  /**
+   * List all cached issues
+   */
+  async listCachedIssues(projectId: string): Promise<CachedIssue[]> {
+    const issuesJson = await this.loadIssues(projectId)
+    if (!issuesJson) return []
+
+    return Object.values(issuesJson.issues)
+  }
+
+  // =============================================================================
+  // Private Helpers
+  // =============================================================================
+
+  /**
+   * Load issues.json from disk
+   */
+  private async loadIssues(projectId: string): Promise<IssuesJson | null> {
+    const issuesPath = join(getProjectPath(projectId), 'storage', 'issues.json')
+
+    if (!existsSync(issuesPath)) {
+      return null
+    }
+
+    try {
+      const content = await readFile(issuesPath, 'utf-8')
+      return parseIssues(JSON.parse(content))
+    } catch {
+      return null
+    }
+  }
+
+  /**
+   * Save issues.json to disk
+   */
+  private async saveIssues(projectId: string, issuesJson: IssuesJson): Promise<void> {
+    const storagePath = join(getProjectPath(projectId), 'storage')
+    const issuesPath = join(storagePath, 'issues.json')
+
+    if (!existsSync(storagePath)) {
+      await mkdir(storagePath, { recursive: true })
+    }
+
+    await writeFile(issuesPath, JSON.stringify(issuesJson, null, 2))
+  }
+
+  /**
+   * Update a single issue in the cache
+   */
+  private async updateIssueInCache(
+    projectId: string,
+    identifier: string,
+    issue: CachedIssue
+  ): Promise<void> {
+    let issuesJson = await this.loadIssues(projectId)
+
+    if (!issuesJson) {
+      issuesJson = createEmptyIssues('linear')
+    }
+
+    issuesJson.issues[identifier] = issue
+    await this.saveIssues(projectId, issuesJson)
+  }
+
+  /**
+   * Convert API Issue to CachedIssue format
+   */
+  private toCachedIssue(issue: Issue, timestamp: string): CachedIssue {
+    return {
+      id: issue.id,
+      identifier: issue.externalId,
+      title: issue.title,
+      description: issue.description,
+      status: issue.status,
+      priority: issue.priority,
+      type: issue.type,
+      assignee: issue.assignee,
+      labels: issue.labels,
+      team: issue.team,
+      project: issue.project,
+      url: issue.url,
+      createdAt: issue.createdAt,
+      updatedAt: issue.updatedAt,
+      fetchedAt: timestamp,
+    }
+  }
+}
+
+// Singleton instance
+export const linearSync = new LinearSync()

package/core/schemas/index.ts

@@ -15,6 +15,9 @@
 // State (current task + queue)
 export * from './state'
 
+// Issues (local cache of issue tracker issues)
+export * from './issues'
+
 // Project metadata
 export * from './project'
 

package/core/schemas/issues.ts

@@ -0,0 +1,144 @@
+/**
+ * Issues Schema
+ *
+ * Defines the structure for issues.json - local cache of issue tracker issues.
+ * Used for bidirectional sync with Linear/JIRA/etc.
+ *
+ * Location: ~/.prjct-cli/projects/{projectId}/storage/issues.json
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Issue Provider Types
+// =============================================================================
+
+export const IssueProviderSchema = z.enum(['linear', 'jira', 'github', 'monday', 'asana', 'none'])
+export const IssueStatusSchema = z.enum(['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled'])
+export const IssuePrioritySchema = z.enum(['none', 'urgent', 'high', 'medium', 'low'])
+export const IssueTypeSchema = z.enum(['feature', 'bug', 'improvement', 'task', 'chore', 'epic'])
+
+// =============================================================================
+// Cached Issue Schema
+// =============================================================================
+
+/**
+ * Single cached issue from provider
+ */
+export const CachedIssueSchema = z.object({
+  // Core identifiers
+  id: z.string(),                    // Provider UUID
+  identifier: z.string(),            // Human-readable ID (e.g., "PRJ-123")
+
+  // Issue content
+  title: z.string(),
+  description: z.string().optional(),
+
+  // State
+  status: IssueStatusSchema,
+  priority: IssuePrioritySchema,
+  type: IssueTypeSchema.optional(),
+
+  // Metadata
+  assignee: z.object({
+    id: z.string(),
+    name: z.string(),
+    email: z.string().optional(),
+  }).optional(),
+  labels: z.array(z.string()).default([]),
+  team: z.object({
+    id: z.string(),
+    name: z.string(),
+    key: z.string().optional(),
+  }).optional(),
+  project: z.object({
+    id: z.string(),
+    name: z.string(),
+  }).optional(),
+
+  // URLs and timestamps
+  url: z.string(),
+  createdAt: z.string(),             // ISO8601 from provider
+  updatedAt: z.string(),             // ISO8601 from provider
+  fetchedAt: z.string(),             // ISO8601 when we cached it
+})
+
+// =============================================================================
+// Issues JSON Schema (Root)
+// =============================================================================
+
+/**
+ * Root schema for issues.json
+ * Maps identifier -> CachedIssue for quick lookup
+ */
+export const IssuesJsonSchema = z.object({
+  // Provider info
+  provider: IssueProviderSchema,
+
+  // Sync metadata
+  lastSync: z.string(),              // ISO8601 of last full sync
+  staleAfter: z.number().default(1800000), // 30 minutes in ms
+
+  // Issues map: identifier -> issue
+  issues: z.record(z.string(), CachedIssueSchema),
+})
+
+// =============================================================================
+// Sync Result Schema
+// =============================================================================
+
+export const SyncResultSchema = z.object({
+  provider: IssueProviderSchema,
+  fetched: z.number(),
+  updated: z.number(),
+  errors: z.array(z.object({
+    issueId: z.string(),
+    error: z.string(),
+  })),
+  timestamp: z.string(),
+})
+
+// =============================================================================
+// Inferred Types
+// =============================================================================
+
+export type IssueProvider = z.infer<typeof IssueProviderSchema>
+export type IssueStatus = z.infer<typeof IssueStatusSchema>
+export type IssuePriority = z.infer<typeof IssuePrioritySchema>
+export type IssueType = z.infer<typeof IssueTypeSchema>
+export type CachedIssue = z.infer<typeof CachedIssueSchema>
+export type IssuesJson = z.infer<typeof IssuesJsonSchema>
+export type SyncResult = z.infer<typeof SyncResultSchema>
+
+// =============================================================================
+// Validation Helpers
+// =============================================================================
+
+/** Parse and validate issues.json content */
+export const parseIssues = (data: unknown): IssuesJson => IssuesJsonSchema.parse(data)
+
+/** Safe parse with error result */
+export const safeParseIssues = (data: unknown) => IssuesJsonSchema.safeParse(data)
+
+// =============================================================================
+// Defaults
+// =============================================================================
+
+export const DEFAULT_ISSUES: IssuesJson = {
+  provider: 'none',
+  lastSync: '',
+  staleAfter: 1800000, // 30 minutes
+  issues: {},
+}
+
+/**
+ * Create empty issues.json for a provider
+ */
+export function createEmptyIssues(provider: IssueProvider): IssuesJson {
+  return {
+    provider,
+    lastSync: '',
+    staleAfter: 1800000,
+    issues: {},
+  }
+}

package/core/schemas/state.ts

@@ -64,6 +64,9 @@ export const CurrentTaskSchema = z.object({
   subtasks: z.array(SubtaskSchema).optional(),
   currentSubtaskIndex: z.number().optional(),
   subtaskProgress: SubtaskProgressSchema.optional(),
+  // Linear integration - bidirectional sync
+  linearId: z.string().optional(),      // "PRJ-123" - Linear identifier
+  linearUuid: z.string().optional(),    // Linear internal UUID for API calls
 })
 
 export const PreviousTaskSchema = z.object({