prjct-cli 0.28.4 → 0.29.0

package/core/integrations/notion/templates.ts

@@ -0,0 +1,246 @@
+/**
+ * Notion Database Templates
+ * Schemas for auto-creating prjct databases in Notion.
+ */
+
+import type { NotionDatabaseSchema } from './client'
+
+// =============================================================================
+// Database Schemas
+// =============================================================================
+
+/**
+ * Shipped Features Database Schema
+ * Tracks shipped features with metrics
+ */
+export const SHIPPED_DATABASE_SCHEMA: NotionDatabaseSchema = {
+  title: 'prjct: Shipped Features',
+  properties: {
+    Name: { type: 'title', title: {} },
+    Version: { type: 'rich_text', rich_text: {} },
+    Type: {
+      type: 'select',
+      select: {
+        options: [
+          { name: 'feature', color: 'blue' },
+          { name: 'fix', color: 'red' },
+          { name: 'improvement', color: 'green' },
+          { name: 'refactor', color: 'purple' },
+        ],
+      },
+    },
+    'Shipped Date': { type: 'date', date: {} },
+    'Lines Changed': { type: 'number', number: { format: 'number' } },
+    'Files Changed': { type: 'number', number: { format: 'number' } },
+    Commits: { type: 'number', number: { format: 'number' } },
+    Duration: { type: 'rich_text', rich_text: {} },
+    Description: { type: 'rich_text', rich_text: {} },
+  },
+}
+
+/**
+ * Roadmap Database Schema
+ * Tracks feature roadmap and progress
+ */
+export const ROADMAP_DATABASE_SCHEMA: NotionDatabaseSchema = {
+  title: 'prjct: Roadmap',
+  properties: {
+    Feature: { type: 'title', title: {} },
+    Status: {
+      type: 'status',
+      status: {
+        options: [
+          { name: 'Planned', color: 'gray' },
+          { name: 'Active', color: 'blue' },
+          { name: 'Completed', color: 'green' },
+          { name: 'Shipped', color: 'purple' },
+        ],
+        groups: [
+          { name: 'To Do', option_ids: [], color: 'gray' },
+          { name: 'In Progress', option_ids: [], color: 'blue' },
+          { name: 'Done', option_ids: [], color: 'green' },
+        ],
+      },
+    },
+    Priority: {
+      type: 'select',
+      select: {
+        options: [
+          { name: 'High', color: 'red' },
+          { name: 'Medium', color: 'yellow' },
+          { name: 'Low', color: 'gray' },
+        ],
+      },
+    },
+    Progress: { type: 'number', number: { format: 'percent' } },
+    Phase: { type: 'rich_text', rich_text: {} },
+    'Target Date': { type: 'date', date: {} },
+    Description: { type: 'rich_text', rich_text: {} },
+    Tasks: { type: 'number', number: { format: 'number' } },
+  },
+}
+
+/**
+ * Ideas Database Schema
+ * Captures and tracks ideas
+ */
+export const IDEAS_DATABASE_SCHEMA: NotionDatabaseSchema = {
+  title: 'prjct: Ideas',
+  properties: {
+    Idea: { type: 'title', title: {} },
+    Status: {
+      type: 'status',
+      status: {
+        options: [
+          { name: 'Pending', color: 'gray' },
+          { name: 'Converted', color: 'green' },
+          { name: 'Archived', color: 'default' },
+        ],
+        groups: [
+          { name: 'Not Started', option_ids: [], color: 'gray' },
+          { name: 'Done', option_ids: [], color: 'green' },
+        ],
+      },
+    },
+    Priority: {
+      type: 'select',
+      select: {
+        options: [
+          { name: 'high', color: 'red' },
+          { name: 'medium', color: 'yellow' },
+          { name: 'low', color: 'gray' },
+        ],
+      },
+    },
+    Tags: { type: 'multi_select', multi_select: { options: [] } },
+    Created: { type: 'date', date: {} },
+    'Converted To': { type: 'rich_text', rich_text: {} },
+  },
+}
+
+/**
+ * Active Tasks Database Schema
+ * Tracks current task queue
+ */
+export const TASKS_DATABASE_SCHEMA: NotionDatabaseSchema = {
+  title: 'prjct: Active Tasks',
+  properties: {
+    Task: { type: 'title', title: {} },
+    Priority: {
+      type: 'select',
+      select: {
+        options: [
+          { name: 'critical', color: 'red' },
+          { name: 'high', color: 'orange' },
+          { name: 'medium', color: 'yellow' },
+          { name: 'low', color: 'gray' },
+        ],
+      },
+    },
+    Type: {
+      type: 'select',
+      select: {
+        options: [
+          { name: 'feature', color: 'blue' },
+          { name: 'bug', color: 'red' },
+          { name: 'improvement', color: 'green' },
+          { name: 'chore', color: 'gray' },
+        ],
+      },
+    },
+    Section: {
+      type: 'select',
+      select: {
+        options: [
+          { name: 'active', color: 'blue' },
+          { name: 'backlog', color: 'gray' },
+        ],
+      },
+    },
+    Completed: { type: 'checkbox', checkbox: {} },
+    Agent: { type: 'rich_text', rich_text: {} },
+    Feature: { type: 'rich_text', rich_text: {} },
+    Created: { type: 'date', date: {} },
+    'Completed At': { type: 'date', date: {} },
+  },
+}
+
+// =============================================================================
+// Dashboard Template
+// =============================================================================
+
+export interface DashboardMetrics {
+  shippedCount: number
+  ideasPending: number
+  tasksActive: number
+  roadmapProgress: number // 0-100
+}
+
+/**
+ * Dashboard page content template with metrics
+ */
+export function getDashboardContent(
+  projectName: string,
+  databases: {
+    shipped?: string
+    roadmap?: string
+    ideas?: string
+    tasks?: string
+  },
+  metrics?: DashboardMetrics
+): string {
+  const sections: string[] = []
+
+  sections.push(`# ${projectName} Dashboard`)
+  sections.push('')
+
+  // Metrics section
+  if (metrics) {
+    sections.push('## Metrics')
+    sections.push('')
+    sections.push('| Metric | Value |')
+    sections.push('|--------|-------|')
+    sections.push(`| Features Shipped | ${metrics.shippedCount} |`)
+    sections.push(`| Ideas Pending | ${metrics.ideasPending} |`)
+    sections.push(`| Active Tasks | ${metrics.tasksActive} |`)
+    sections.push(`| Roadmap Progress | ${metrics.roadmapProgress}% |`)
+    sections.push('')
+  } else {
+    sections.push('*Metrics will appear after first sync*')
+    sections.push('')
+  }
+
+  // Database links
+  sections.push('## Databases')
+  sections.push('')
+
+  if (databases.shipped) {
+    sections.push(`- **Shipped Features**: Track released features and metrics`)
+  }
+  if (databases.roadmap) {
+    sections.push(`- **Roadmap**: Feature planning and progress`)
+  }
+  if (databases.ideas) {
+    sections.push(`- **Ideas**: Captured ideas and status`)
+  }
+  if (databases.tasks) {
+    sections.push(`- **Active Tasks**: Current task queue`)
+  }
+
+  sections.push('')
+  sections.push('---')
+  sections.push('Synced by [prjct-cli](https://prjct.app)')
+
+  return sections.join('\n')
+}
+
+// =============================================================================
+// All Schemas Export
+// =============================================================================
+
+export const ALL_DATABASE_SCHEMAS = {
+  shipped: SHIPPED_DATABASE_SCHEMA,
+  roadmap: ROADMAP_DATABASE_SCHEMA,
+  ideas: IDEAS_DATABASE_SCHEMA,
+  tasks: TASKS_DATABASE_SCHEMA,
+} as const

package/core/plugin/builtin/notion.ts

@@ -0,0 +1,178 @@
+/**
+ * Notion Plugin for prjct-cli
+ *
+ * Syncs prjct data to Notion databases on events.
+ * Activated when project has integrations.notion.enabled = true
+ *
+ * @version 1.0.0
+ *
+ * Configuration in GlobalConfig.integrations.notion:
+ * {
+ *   "enabled": true,
+ *   "databases": {
+ *     "shipped": "notion-db-id",
+ *     "ideas": "notion-db-id"
+ *   },
+ *   "syncOn": { "ship": true, "idea": true }
+ * }
+ */
+
+import { HookPoints } from '../hooks'
+import type { NotionIntegrationConfig } from '../../types/integrations'
+import type { ShippedFeature, Idea } from '../../types/storage'
+import { notionClient, syncShippedFeature, syncIdea } from '../../integrations/notion'
+
+interface NotionPluginContext {
+  projectId: string
+  config: NotionIntegrationConfig
+  apiToken?: string
+}
+
+const plugin = {
+  name: 'notion',
+  version: '1.0.0',
+  description: 'Sync prjct data to Notion',
+
+  // Plugin state
+  enabled: false,
+  projectId: null as string | null,
+  config: null as NotionIntegrationConfig | null,
+
+  /**
+   * Activate plugin
+   */
+  async activate(context: NotionPluginContext): Promise<void> {
+    const { projectId, config, apiToken } = context
+
+    if (!config?.enabled) {
+      return
+    }
+
+    // Initialize Notion client
+    notionClient.initialize(config, apiToken || process.env.NOTION_TOKEN)
+
+    if (!notionClient.isReady()) {
+      console.warn('[notion] API token not configured, plugin disabled')
+      return
+    }
+
+    plugin.enabled = true
+    plugin.projectId = projectId
+    plugin.config = config
+  },
+
+  /**
+   * Deactivate plugin
+   */
+  async deactivate(): Promise<void> {
+    plugin.enabled = false
+    plugin.projectId = null
+    plugin.config = null
+  },
+
+  /**
+   * Hook handlers
+   */
+  hooks: {
+    /**
+     * Sync shipped feature to Notion after ship
+     */
+    [HookPoints.AFTER_FEATURE_SHIP]: async function (data: {
+      feature: ShippedFeature
+      projectId?: string
+    }): Promise<void> {
+      if (!plugin.enabled || !plugin.config || !plugin.projectId) return
+      if (!plugin.config.syncOn?.ship) return
+
+      try {
+        const result = await syncShippedFeature(
+          data.projectId || plugin.projectId,
+          data.feature,
+          plugin.config
+        )
+
+        if (result.success) {
+          console.log(`[notion] Synced: ${data.feature.name} (${result.action})`)
+        } else if (result.error) {
+          console.warn(`[notion] Sync failed: ${result.error}`)
+        }
+      } catch (error) {
+        // Graceful degradation - don't fail the ship
+        console.warn('[notion] Sync error:', (error as Error).message)
+      }
+    },
+
+    /**
+     * Sync idea to Notion after capture
+     */
+    [HookPoints.AFTER_IDEA_CAPTURE]: async function (data: {
+      idea: Idea
+      projectId?: string
+    }): Promise<void> {
+      if (!plugin.enabled || !plugin.config || !plugin.projectId) return
+      if (!plugin.config.syncOn?.idea) return
+
+      try {
+        const result = await syncIdea(
+          data.projectId || plugin.projectId,
+          data.idea,
+          plugin.config
+        )
+
+        if (result.success) {
+          console.log(`[notion] Synced idea: ${data.idea.text.slice(0, 30)}... (${result.action})`)
+        } else if (result.error) {
+          console.warn(`[notion] Sync failed: ${result.error}`)
+        }
+      } catch (error) {
+        // Graceful degradation - don't fail the idea capture
+        console.warn('[notion] Sync error:', (error as Error).message)
+      }
+    },
+
+    /**
+     * Sync task completion (optional)
+     */
+    [HookPoints.AFTER_TASK_COMPLETE]: async function (data: {
+      taskName?: string
+      projectId?: string
+    }): Promise<void> {
+      if (!plugin.enabled || !plugin.config || !plugin.projectId) return
+      if (!plugin.config.syncOn?.done) return
+
+      // Task sync is optional and less critical
+      // Could update task status in Notion if database exists
+      if (data.taskName) {
+        console.log(`[notion] Task completed: ${data.taskName}`)
+      }
+    },
+  },
+
+  /**
+   * Check if plugin is active
+   */
+  isActive(): boolean {
+    return plugin.enabled && plugin.config?.enabled === true
+  },
+
+  /**
+   * Get current sync status
+   */
+  getStatus(): {
+    enabled: boolean
+    databases: number
+    lastSync?: string
+  } {
+    const dbCount = plugin.config?.databases
+      ? Object.values(plugin.config.databases).filter(Boolean).length
+      : 0
+
+    return {
+      enabled: plugin.enabled,
+      databases: dbCount,
+      lastSync: plugin.config?.lastSyncAt,
+    }
+  },
+}
+
+export default plugin

package/core/schemas/enriched-task.ts

@@ -0,0 +1,278 @@
+/**
+ * Enriched Task Schema
+ * Defines the structure of a fully enriched task from PM Expert
+ */
+
+import { z } from 'zod'
+
+// =============================================================================
+// Enums
+// =============================================================================
+
+export const TaskTypeSchema = z.enum([
+  'feature',
+  'bug',
+  'improvement',
+  'task',
+  'chore',
+  'spike',
+  'epic',
+])
+
+export const PrioritySchema = z.enum([
+  'critical',
+  'high',
+  'medium',
+  'low',
+  'none',
+])
+
+export const ComplexitySchema = z.enum([
+  'trivial',   // < 1 hour
+  'small',     // 1-4 hours
+  'medium',    // 1-2 days
+  'large',     // 3-5 days
+  'epic',      // > 1 week
+])
+
+export const RiskLevelSchema = z.enum(['none', 'low', 'medium', 'high', 'critical'])
+
+// =============================================================================
+// User Story
+// =============================================================================
+
+export const UserStorySchema = z.object({
+  role: z.string().describe('The user role (e.g., "mobile user")'),
+  action: z.string().describe('What the user wants to do'),
+  benefit: z.string().describe('The benefit they get'),
+  formatted: z.string().describe('Formatted user story: "As a [role], I want [action] so that [benefit]"'),
+})
+
+// =============================================================================
+// Acceptance Criteria
+// =============================================================================
+
+export const AcceptanceCriterionSchema = z.object({
+  id: z.string().describe('Unique criterion ID (e.g., AC-1)'),
+  description: z.string().describe('Criterion description'),
+  type: z.enum(['functional', 'technical', 'ux', 'performance']).default('functional'),
+  testable: z.boolean().default(true).describe('Whether it is verifiable/testable'),
+  gherkin: z.string().optional().describe('Optional Given/When/Then format'),
+})
+
+// =============================================================================
+// Dependencies
+// =============================================================================
+
+export const CodeDependencySchema = z.object({
+  file: z.string().describe('File path'),
+  reason: z.string().describe('Why it is relevant'),
+  risk: RiskLevelSchema.describe('Risk level of modifying'),
+  lines: z.string().optional().describe('Specific lines (e.g., "45-67")'),
+})
+
+export const ApiDependencySchema = z.object({
+  endpoint: z.string().describe('Endpoint (e.g., POST /api/auth/login)'),
+  method: z.enum(['GET', 'POST', 'PUT', 'PATCH', 'DELETE']).optional(),
+  status: z.enum(['stable', 'in_development', 'deprecated']).default('stable'),
+  risk: RiskLevelSchema,
+  notes: z.string().optional(),
+})
+
+export const TaskDependencySchema = z.object({
+  id: z.string().describe('Blocking task ID'),
+  title: z.string().describe('Task title'),
+  status: z.string().describe('Current status'),
+  blocking: z.boolean().default(false).describe('Whether it completely blocks'),
+  risk: RiskLevelSchema,
+})
+
+export const DependenciesSchema = z.object({
+  code: z.array(CodeDependencySchema).default([]),
+  api: z.array(ApiDependencySchema).default([]),
+  tasks: z.array(TaskDependencySchema).default([]),
+  infrastructure: z.array(z.object({
+    service: z.string(),
+    purpose: z.string(),
+    risk: RiskLevelSchema,
+  })).default([]),
+})
+
+// =============================================================================
+// Technical Analysis
+// =============================================================================
+
+export const TechnicalAnalysisSchema = z.object({
+  affectedFiles: z.array(z.object({
+    path: z.string(),
+    changes: z.string().describe('Expected changes'),
+    complexity: ComplexitySchema,
+  })).default([]),
+
+  existingPatterns: z.array(z.object({
+    pattern: z.string().describe('Pattern name'),
+    file: z.string().describe('Reference file'),
+    relevance: z.string().describe('Why it is relevant'),
+  })).default([]),
+
+  suggestedApproach: z.string().optional().describe('Recommended approach'),
+
+  potentialRisks: z.array(z.object({
+    risk: z.string(),
+    mitigation: z.string(),
+    severity: RiskLevelSchema,
+  })).default([]),
+
+  testingStrategy: z.object({
+    unit: z.array(z.string()).default([]),
+    integration: z.array(z.string()).default([]),
+    e2e: z.array(z.string()).default([]),
+  }).optional(),
+})
+
+// =============================================================================
+// LLM Prompt (AI-Agnostic)
+// =============================================================================
+
+/**
+ * LLM Prompt Schema
+ * Generates prompts compatible with any AI assistant:
+ * Claude, ChatGPT, Copilot, Gemini, Cursor, etc.
+ */
+export const LLMPromptSchema = z.object({
+  context: z.string().describe('Codebase context (stack, structure)'),
+  problem: z.string().describe('What problem needs to be solved'),
+  task: z.string().describe('Task description'),
+  instructions: z.array(z.string()).describe('Step-by-step instructions'),
+  files: z.array(z.string()).describe('Files to modify'),
+  patterns: z.array(z.string()).describe('Reference patterns to follow'),
+  acceptanceCriteria: z.array(z.string()).describe('How to know when done'),
+  verification: z.array(z.string()).describe('How to test/verify correctness'),
+  formatted: z.string().describe('Complete copy-paste ready prompt'),
+})
+
+// =============================================================================
+// Main Enriched Task Schema
+// =============================================================================
+
+export const EnrichedTaskSchema = z.object({
+  // Identification
+  id: z.string().describe('Task UUID'),
+  externalId: z.string().optional().describe('External system ID (ENG-123)'),
+  provider: z.enum(['linear', 'jira', 'monday', 'github', 'internal']).optional(),
+
+  // Basic (original input)
+  originalTitle: z.string().describe('Original title from PO'),
+  originalDescription: z.string().optional().describe('Original description'),
+
+  // Classification
+  type: TaskTypeSchema,
+  priority: PrioritySchema,
+  complexity: ComplexitySchema,
+  labels: z.array(z.string()).default([]),
+
+  // Enrichment
+  userStory: UserStorySchema,
+  acceptanceCriteria: z.array(AcceptanceCriterionSchema).min(1),
+  definitionOfDone: z.array(z.string()).default([
+    'Code reviewed',
+    'Tests pass',
+    'Documentation updated',
+    'Deployed to staging',
+  ]),
+
+  // Technical analysis
+  technicalAnalysis: TechnicalAnalysisSchema,
+  dependencies: DependenciesSchema,
+
+  // For the LLM
+  llmPrompt: LLMPromptSchema,
+
+  // Metadata
+  enrichedAt: z.string().describe('ISO timestamp'),
+  enrichedBy: z.enum(['pm-expert', 'manual', 'imported']).default('pm-expert'),
+  confidence: z.number().min(0).max(1).describe('Analysis confidence (0-1)'),
+
+  // Status
+  readyForDev: z.boolean().default(false).describe('Whether ready for development'),
+  blockers: z.array(z.string()).default([]).describe('Active blockers'),
+})
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export type TaskType = z.infer<typeof TaskTypeSchema>
+export type Priority = z.infer<typeof PrioritySchema>
+export type Complexity = z.infer<typeof ComplexitySchema>
+export type RiskLevel = z.infer<typeof RiskLevelSchema>
+export type UserStory = z.infer<typeof UserStorySchema>
+export type AcceptanceCriterion = z.infer<typeof AcceptanceCriterionSchema>
+export type Dependencies = z.infer<typeof DependenciesSchema>
+export type TechnicalAnalysis = z.infer<typeof TechnicalAnalysisSchema>
+export type LLMPrompt = z.infer<typeof LLMPromptSchema>
+export type EnrichedTask = z.infer<typeof EnrichedTaskSchema>
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+/**
+ * Create formatted user story
+ */
+export function formatUserStory(role: string, action: string, benefit: string): UserStory {
+  return {
+    role,
+    action,
+    benefit,
+    formatted: `As a **${role}**, I want to **${action}** so that **${benefit}**.`,
+  }
+}
+
+/**
+ * Check if task is ready for development
+ */
+export function isReadyForDev(task: EnrichedTask): { ready: boolean; reasons: string[] } {
+  const reasons: string[] = []
+
+  // Check acceptance criteria
+  if (task.acceptanceCriteria.length < 2) {
+    reasons.push('Needs at least 2 acceptance criteria')
+  }
+
+  // Check blockers
+  const blockingDeps = task.dependencies.tasks.filter(t => t.blocking)
+  if (blockingDeps.length > 0) {
+    reasons.push(`Blocked by: ${blockingDeps.map(t => t.id).join(', ')}`)
+  }
+
+  // Check critical risks
+  const criticalRisks = task.technicalAnalysis.potentialRisks.filter(r => r.severity === 'critical')
+  if (criticalRisks.length > 0) {
+    reasons.push('Has unmitigated critical risks')
+  }
+
+  // Check analysis confidence
+  if (task.confidence < 0.6) {
+    reasons.push('Low confidence analysis - needs manual review')
+  }
+
+  return {
+    ready: reasons.length === 0,
+    reasons,
+  }
+}
+
+/**
+ * Estimate story points based on complexity
+ */
+export function estimateStoryPoints(complexity: Complexity): number {
+  const map: Record<Complexity, number> = {
+    trivial: 1,
+    small: 2,
+    medium: 3,
+    large: 5,
+    epic: 8,
+  }
+  return map[complexity]
+}