prjct-cli 0.39.0 → 0.41.0

package/core/integrations/linear/service.ts

@@ -0,0 +1,260 @@
+/**
+ * Linear Service Layer
+ * Wraps LinearProvider with caching for improved performance.
+ * All operations are cached with 5-minute TTL.
+ */
+
+import { linearProvider } from './client'
+import {
+  issueCache,
+  assignedIssuesCache,
+  teamsCache,
+  projectsCache,
+  clearLinearCache,
+  getLinearCacheStats,
+} from './cache'
+import type {
+  Issue,
+  CreateIssueInput,
+  UpdateIssueInput,
+  FetchOptions,
+  LinearConfig,
+} from '../issue-tracker/types'
+
+export class LinearService {
+  private initialized = false
+  private userId: string | null = null
+
+  /**
+   * Check if service is ready
+   */
+  isReady(): boolean {
+    return this.initialized && linearProvider.isConfigured()
+  }
+
+  /**
+   * Initialize the service with config
+   * Must be called before any operations
+   */
+  async initialize(config: LinearConfig): Promise<void> {
+    if (this.initialized) return
+
+    await linearProvider.initialize(config)
+    this.initialized = true
+  }
+
+  /**
+   * Initialize from API key directly
+   * Convenience method for simple setup
+   */
+  async initializeFromApiKey(apiKey: string, teamId?: string): Promise<void> {
+    const config: LinearConfig = {
+      enabled: true,
+      provider: 'linear',
+      apiKey,
+      defaultTeamId: teamId,
+      syncOn: { task: true, done: true, ship: true },
+      enrichment: { enabled: true, updateProvider: true },
+    }
+    await this.initialize(config)
+  }
+
+  /**
+   * Get issues assigned to current user (cached)
+   */
+  async fetchAssignedIssues(options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `assigned:${this.userId || 'me'}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await linearProvider.fetchAssignedIssues(options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get issues from a team (cached)
+   */
+  async fetchTeamIssues(teamId: string, options?: FetchOptions): Promise<Issue[]> {
+    this.ensureInitialized()
+
+    const cacheKey = `team:${teamId}`
+    const cached = assignedIssuesCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issues = await linearProvider.fetchTeamIssues(teamId, options)
+    assignedIssuesCache.set(cacheKey, issues)
+
+    // Also cache individual issues
+    for (const issue of issues) {
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issues
+  }
+
+  /**
+   * Get a single issue by ID or identifier (cached)
+   * Accepts UUID or identifier like "PRJ-123"
+   */
+  async fetchIssue(id: string): Promise<Issue | null> {
+    this.ensureInitialized()
+
+    // Check cache first
+    const cacheKey = `issue:${id}`
+    const cached = issueCache.get(cacheKey)
+    if (cached) {
+      return cached
+    }
+
+    const issue = await linearProvider.fetchIssue(id)
+    if (issue) {
+      // Cache by both ID and externalId
+      issueCache.set(`issue:${issue.id}`, issue)
+      issueCache.set(`issue:${issue.externalId}`, issue)
+    }
+
+    return issue
+  }
+
+  /**
+   * Create a new issue (invalidates assigned cache)
+   */
+  async createIssue(input: CreateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await linearProvider.createIssue(input)
+
+    // Cache the new issue
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    // Invalidate assigned issues cache (new issue may be assigned)
+    assignedIssuesCache.clear()
+
+    return issue
+  }
+
+  /**
+   * Update an issue (invalidates cache for that issue)
+   */
+  async updateIssue(id: string, input: UpdateIssueInput): Promise<Issue> {
+    this.ensureInitialized()
+
+    const issue = await linearProvider.updateIssue(id, input)
+
+    // Update cache
+    issueCache.set(`issue:${issue.id}`, issue)
+    issueCache.set(`issue:${issue.externalId}`, issue)
+
+    return issue
+  }
+
+  /**
+   * Mark issue as in progress (invalidates cache)
+   */
+  async markInProgress(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await linearProvider.markInProgress(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Mark issue as done (invalidates cache)
+   */
+  async markDone(id: string): Promise<void> {
+    this.ensureInitialized()
+
+    await linearProvider.markDone(id)
+
+    // Invalidate caches
+    issueCache.delete(`issue:${id}`)
+    assignedIssuesCache.clear()
+  }
+
+  /**
+   * Add a comment to an issue
+   */
+  async addComment(id: string, body: string): Promise<void> {
+    this.ensureInitialized()
+    await linearProvider.addComment(id, body)
+  }
+
+  /**
+   * Get available teams (cached)
+   */
+  async getTeams(): Promise<Array<{ id: string; name: string; key?: string }>> {
+    this.ensureInitialized()
+
+    const cached = teamsCache.get('teams')
+    if (cached) {
+      return cached
+    }
+
+    const teams = await linearProvider.getTeams()
+    teamsCache.set('teams', teams)
+    return teams
+  }
+
+  /**
+   * Get available projects (cached)
+   */
+  async getProjects(): Promise<Array<{ id: string; name: string }>> {
+    this.ensureInitialized()
+
+    const cached = projectsCache.get('projects')
+    if (cached) {
+      return cached
+    }
+
+    const projects = await linearProvider.getProjects()
+    projectsCache.set('projects', projects)
+    return projects
+  }
+
+  /**
+   * Clear all caches
+   */
+  clearCache(): void {
+    clearLinearCache()
+  }
+
+  /**
+   * Get cache statistics for debugging
+   */
+  getCacheStats() {
+    return getLinearCacheStats()
+  }
+
+  /**
+   * Ensure service is initialized
+   */
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      throw new Error(
+        'Linear service not initialized. Call linearService.initialize() first or run `p. linear setup`.'
+      )
+    }
+  }
+}
+
+// Singleton instance
+export const linearService = new LinearService()

package/core/services/skill-installer.ts

@@ -0,0 +1,431 @@
+/**
+ * Skill Installer Service
+ *
+ * Installs skills from remote sources (GitHub repos, local paths).
+ * Follows the ecosystem standard of {name}/SKILL.md subdirectory format.
+ *
+ * Supported sources:
+ * - owner/repo — clone from GitHub, discover all SKILL.md files
+ * - owner/repo@skill-name — install specific skill from repo
+ * - ./local-path — install from local directory
+ *
+ * @version 1.0.0
+ */
+
+import fs from 'fs/promises'
+import path from 'path'
+import os from 'os'
+import { promisify } from 'util'
+import { exec as execCallback } from 'child_process'
+import { glob } from 'glob'
+
+import { skillLock } from './skill-lock'
+import type { SkillLockEntry } from './skill-lock'
+
+const exec = promisify(execCallback)
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface ParsedSource {
+  type: 'github' | 'local'
+  owner?: string
+  repo?: string
+  skillName?: string
+  localPath?: string
+  url: string
+}
+
+export interface InstalledSkill {
+  name: string
+  filePath: string
+  source: ParsedSource
+  sha?: string
+}
+
+export interface InstallResult {
+  installed: InstalledSkill[]
+  skipped: string[]
+  errors: string[]
+}
+
+// =============================================================================
+// Source Parsing
+// =============================================================================
+
+/**
+ * Parse a source string into a structured source object
+ *
+ * Formats:
+ * - "owner/repo" → GitHub repo, install all skills
+ * - "owner/repo@skill-name" → GitHub repo, specific skill
+ * - "./path" or "/path" → Local directory
+ */
+export function parseSource(source: string): ParsedSource {
+  // Local path
+  if (source.startsWith('./') || source.startsWith('/') || source.startsWith('~')) {
+    const resolvedPath = source.startsWith('~')
+      ? path.join(os.homedir(), source.slice(1))
+      : path.resolve(source)
+    return {
+      type: 'local',
+      localPath: resolvedPath,
+      url: resolvedPath,
+    }
+  }
+
+  // GitHub: owner/repo@skill-name
+  const atIndex = source.indexOf('@')
+  if (atIndex > 0) {
+    const repoPath = source.slice(0, atIndex)
+    const skillName = source.slice(atIndex + 1)
+    const [owner, repo] = repoPath.split('/')
+    if (owner && repo) {
+      return {
+        type: 'github',
+        owner,
+        repo,
+        skillName,
+        url: `https://github.com/${owner}/${repo}`,
+      }
+    }
+  }
+
+  // GitHub: owner/repo
+  const parts = source.split('/')
+  if (parts.length === 2 && parts[0] && parts[1]) {
+    return {
+      type: 'github',
+      owner: parts[0],
+      repo: parts[1],
+      url: `https://github.com/${parts[0]}/${parts[1]}`,
+    }
+  }
+
+  throw new Error(`Invalid source format: "${source}". Expected "owner/repo", "owner/repo@skill-name", or "./local-path"`)
+}
+
+// =============================================================================
+// Skill Discovery
+// =============================================================================
+
+/**
+ * Discover skills in a directory by scanning for SKILL.md files
+ */
+async function discoverSkills(dir: string): Promise<Array<{ name: string; filePath: string }>> {
+  const skills: Array<{ name: string; filePath: string }> = []
+
+  // Pattern 1: {dir}/SKILL.md (root-level skill)
+  try {
+    const rootSkill = path.join(dir, 'SKILL.md')
+    await fs.access(rootSkill)
+    const dirName = path.basename(dir)
+    skills.push({ name: dirName, filePath: rootSkill })
+  } catch {
+    // No root SKILL.md
+  }
+
+  // Pattern 2: {dir}/*/SKILL.md (subdirectory skills)
+  const subdirSkills = await glob('*/SKILL.md', { cwd: dir, absolute: true })
+  for (const filePath of subdirSkills) {
+    const name = path.basename(path.dirname(filePath))
+    // Avoid duplicate if already found as root
+    if (!skills.some(s => s.name === name)) {
+      skills.push({ name, filePath })
+    }
+  }
+
+  // Pattern 3: {dir}/skills/*/SKILL.md (nested skills directory)
+  const nestedSkills = await glob('skills/*/SKILL.md', { cwd: dir, absolute: true })
+  for (const filePath of nestedSkills) {
+    const name = path.basename(path.dirname(filePath))
+    if (!skills.some(s => s.name === name)) {
+      skills.push({ name, filePath })
+    }
+  }
+
+  return skills
+}
+
+// =============================================================================
+// Frontmatter Injection
+// =============================================================================
+
+/**
+ * Add _prjct source tracking metadata to a skill's frontmatter
+ */
+function injectSourceMetadata(
+  content: string,
+  source: ParsedSource,
+  sha?: string
+): string {
+  const now = new Date().toISOString()
+  const prjctBlock = [
+    `_prjct:`,
+    `  sourceUrl: ${source.url}`,
+    `  sourceType: ${source.type}`,
+    `  installedAt: ${now}`,
+  ]
+  if (sha) {
+    prjctBlock.push(`  sha: ${sha}`)
+  }
+
+  // Check if file has existing frontmatter
+  const frontmatterRegex = /^---\s*\n([\s\S]*?)\n---/
+  const match = content.match(frontmatterRegex)
+
+  if (match) {
+    // Remove existing _prjct block if present
+    let frontmatter = match[1]
+    frontmatter = frontmatter.replace(/\n?_prjct:[\s\S]*?(?=\n[a-zA-Z]|\n---|\s*$)/g, '')
+
+    // Append _prjct block
+    const updatedFrontmatter = frontmatter.trimEnd() + '\n' + prjctBlock.join('\n')
+    return content.replace(frontmatterRegex, `---\n${updatedFrontmatter}\n---`)
+  }
+
+  // No frontmatter — add one
+  return `---\n${prjctBlock.join('\n')}\n---\n\n${content}`
+}
+
+// =============================================================================
+// Installation
+// =============================================================================
+
+/**
+ * Get the default install directory for skills
+ */
+function getInstallDir(): string {
+  return path.join(os.homedir(), '.claude', 'skills')
+}
+
+/**
+ * Install a single skill file to the target directory
+ */
+async function installSkillFile(
+  sourcePath: string,
+  name: string,
+  source: ParsedSource,
+  sha?: string
+): Promise<InstalledSkill> {
+  const installDir = getInstallDir()
+  const targetDir = path.join(installDir, name)
+  const targetPath = path.join(targetDir, 'SKILL.md')
+
+  // Read source content
+  const content = await fs.readFile(sourcePath, 'utf-8')
+
+  // Inject source metadata
+  const enrichedContent = injectSourceMetadata(content, source, sha)
+
+  // Write to target (ecosystem standard: {name}/SKILL.md)
+  await fs.mkdir(targetDir, { recursive: true })
+  await fs.writeFile(targetPath, enrichedContent, 'utf-8')
+
+  return {
+    name,
+    filePath: targetPath,
+    source,
+    sha,
+  }
+}
+
+/**
+ * Install skills from a GitHub repository
+ */
+async function installFromGitHub(source: ParsedSource): Promise<InstallResult> {
+  const result: InstallResult = { installed: [], skipped: [], errors: [] }
+
+  // Create temp directory
+  const tmpDir = path.join(os.tmpdir(), `prjct-skill-${Date.now()}`)
+
+  try {
+    // Clone with depth 1 for speed
+    const cloneUrl = `https://github.com/${source.owner}/${source.repo}.git`
+    await exec(`git clone --depth 1 ${cloneUrl} ${tmpDir}`, { timeout: 60_000 })
+
+    // Get the commit SHA
+    let sha: string | undefined
+    try {
+      const { stdout } = await exec('git rev-parse HEAD', { cwd: tmpDir, timeout: 5_000 })
+      sha = stdout.trim()
+    } catch {
+      // Non-critical
+    }
+
+    // Discover skills in the cloned repo
+    const discoveredSkills = await discoverSkills(tmpDir)
+
+    if (discoveredSkills.length === 0) {
+      result.errors.push(`No SKILL.md files found in ${source.owner}/${source.repo}`)
+      return result
+    }
+
+    // Filter to specific skill if requested
+    const skillsToInstall = source.skillName
+      ? discoveredSkills.filter(s => s.name === source.skillName)
+      : discoveredSkills
+
+    if (source.skillName && skillsToInstall.length === 0) {
+      result.errors.push(`Skill "${source.skillName}" not found in ${source.owner}/${source.repo}`)
+      return result
+    }
+
+    // Install each skill
+    for (const skill of skillsToInstall) {
+      try {
+        const installed = await installSkillFile(skill.filePath, skill.name, source, sha)
+
+        // Update lock file
+        const lockEntry: SkillLockEntry = {
+          name: skill.name,
+          source: {
+            type: 'github',
+            url: `${source.owner}/${source.repo}`,
+            sha,
+          },
+          installedAt: new Date().toISOString(),
+          filePath: installed.filePath,
+        }
+        await skillLock.addEntry(lockEntry)
+
+        result.installed.push(installed)
+      } catch (error) {
+        result.errors.push(`Failed to install ${skill.name}: ${(error as Error).message}`)
+      }
+    }
+  } finally {
+    // Clean up temp directory
+    try {
+      await fs.rm(tmpDir, { recursive: true, force: true })
+    } catch {
+      // Best effort cleanup
+    }
+  }
+
+  return result
+}
+
+/**
+ * Install skills from a local directory
+ */
+async function installFromLocal(source: ParsedSource): Promise<InstallResult> {
+  const result: InstallResult = { installed: [], skipped: [], errors: [] }
+  const localPath = source.localPath!
+
+  try {
+    await fs.access(localPath)
+  } catch {
+    result.errors.push(`Local path not found: ${localPath}`)
+    return result
+  }
+
+  const stat = await fs.stat(localPath)
+
+  if (stat.isFile()) {
+    // Single SKILL.md file
+    const name = path.basename(path.dirname(localPath))
+    try {
+      const installed = await installSkillFile(localPath, name, source)
+      const lockEntry: SkillLockEntry = {
+        name,
+        source: { type: 'local', url: localPath },
+        installedAt: new Date().toISOString(),
+        filePath: installed.filePath,
+      }
+      await skillLock.addEntry(lockEntry)
+      result.installed.push(installed)
+    } catch (error) {
+      result.errors.push(`Failed to install from ${localPath}: ${(error as Error).message}`)
+    }
+  } else {
+    // Directory — discover skills
+    const discoveredSkills = await discoverSkills(localPath)
+
+    if (discoveredSkills.length === 0) {
+      result.errors.push(`No SKILL.md files found in ${localPath}`)
+      return result
+    }
+
+    for (const skill of discoveredSkills) {
+      try {
+        const installed = await installSkillFile(skill.filePath, skill.name, source)
+        const lockEntry: SkillLockEntry = {
+          name: skill.name,
+          source: { type: 'local', url: localPath },
+          installedAt: new Date().toISOString(),
+          filePath: installed.filePath,
+        }
+        await skillLock.addEntry(lockEntry)
+        result.installed.push(installed)
+      } catch (error) {
+        result.errors.push(`Failed to install ${skill.name}: ${(error as Error).message}`)
+      }
+    }
+  }
+
+  return result
+}
+
+/**
+ * Remove an installed skill
+ */
+async function remove(name: string): Promise<boolean> {
+  const installDir = getInstallDir()
+
+  // Remove subdirectory format
+  const subdirPath = path.join(installDir, name)
+  try {
+    await fs.rm(subdirPath, { recursive: true, force: true })
+  } catch {
+    // May not exist in subdir format
+  }
+
+  // Remove flat file format
+  const flatPath = path.join(installDir, `${name}.md`)
+  try {
+    await fs.rm(flatPath, { force: true })
+  } catch {
+    // May not exist in flat format
+  }
+
+  // Remove from lock file
+  return skillLock.removeEntry(name)
+}
+
+// =============================================================================
+// Main Install Function
+// =============================================================================
+
+/**
+ * Install skills from a source string
+ *
+ * @param source - Source string (e.g., "owner/repo", "owner/repo@skill", "./path")
+ * @returns Installation result with installed, skipped, and error lists
+ */
+async function install(sourceStr: string): Promise<InstallResult> {
+  const source = parseSource(sourceStr)
+
+  switch (source.type) {
+    case 'github':
+      return installFromGitHub(source)
+    case 'local':
+      return installFromLocal(source)
+    default:
+      return {
+        installed: [],
+        skipped: [],
+        errors: [`Unsupported source type: ${source.type}`],
+      }
+  }
+}
+
+export const skillInstaller = {
+  install,
+  remove,
+  parseSource,
+  getInstallDir,
+}
+
+export default skillInstaller