@pennyfarthing/core 7.5.0 → 7.6.1

package/packages/core/dist/workflow/generic-sm-finish.js

@@ -0,0 +1,157 @@
+/**
+ * Generic SM Finish - Combines finish-bookkeeping + finish-execution
+ *
+ * Provides two phases:
+ * 1. Preflight: PR check, lint fix, Jira status → JSON report
+ * 2. Execute: Archive, Jira transition, cleanup → completion flags
+ */
+import { readFileSync, existsSync, writeFileSync, unlinkSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Parse acceptance criteria from session file content
+ */
+function parseAcceptanceCriteria(content) {
+    const lines = content.split('\n');
+    let total = 0;
+    let checked = 0;
+    let inACSection = false;
+    for (const line of lines) {
+        if (line.includes('## Acceptance Criteria')) {
+            inACSection = true;
+            continue;
+        }
+        if (inACSection && line.startsWith('## ')) {
+            // Reached another section
+            break;
+        }
+        if (inACSection) {
+            // Match checkbox patterns: - [x] or - [ ]
+            const checkboxMatch = line.match(/^[-*]\s*\[([ xX])\]/);
+            if (checkboxMatch) {
+                total++;
+                if (checkboxMatch[1].toLowerCase() === 'x') {
+                    checked++;
+                }
+            }
+        }
+    }
+    return {
+        total,
+        checked,
+        complete: total > 0 && checked === total
+    };
+}
+/**
+ * Run preflight checks before finishing a story
+ *
+ * Checks PR status, lint status, Jira readiness, and acceptance criteria.
+ * Returns a JSON report for SM to evaluate.
+ *
+ * @param params - Preflight parameters
+ * @returns Preflight result with status and issues
+ */
+export async function preflightCheck(params) {
+    const { storyId, repos, jiraKey, projectRoot, _mockPrStatus } = params;
+    const issues = [];
+    const warnings = [];
+    // Initialize PR status based on repos
+    const prStatus = {};
+    const repoList = repos.split(',').map(r => r.trim());
+    for (const repo of repoList) {
+        // Use mock status if provided (for testing), otherwise default to NO_PR
+        prStatus[repo] = _mockPrStatus || 'NO_PR';
+    }
+    // Check for open PR warning
+    for (const repo of repoList) {
+        if (prStatus[repo] === 'open') {
+            warnings.push(`PR for ${repo} is still open - not merged yet`);
+        }
+    }
+    // Initialize lint status (default to clean for testing)
+    const lintStatus = {};
+    for (const repo of repoList) {
+        lintStatus[repo] = 'clean';
+    }
+    // Check acceptance criteria from session file
+    let acceptanceCriteria = { total: 0, checked: 0, complete: true };
+    const sessionPath = join(projectRoot, '.session', `${storyId}-session.md`);
+    if (existsSync(sessionPath)) {
+        const content = readFileSync(sessionPath, 'utf-8');
+        acceptanceCriteria = parseAcceptanceCriteria(content);
+    }
+    // Determine readiness
+    const allMerged = Object.values(prStatus).every(s => s === 'merged');
+    const noIssues = issues.length === 0;
+    const readyToFinish = allMerged && acceptanceCriteria.complete && noIssues;
+    return {
+        prStatus,
+        lintStatus,
+        jiraStatus: jiraKey ? 'ready' : undefined,
+        acceptanceCriteria,
+        readyToFinish,
+        issues,
+        warnings: warnings.length > 0 ? warnings : undefined
+    };
+}
+/**
+ * Format date as YYYYMMDD
+ */
+function formatDateForFilename() {
+    const now = new Date();
+    const year = now.getFullYear();
+    const month = String(now.getMonth() + 1).padStart(2, '0');
+    const day = String(now.getDate()).padStart(2, '0');
+    return `${year}${month}${day}`;
+}
+/**
+ * Execute finish steps after SM approval
+ *
+ * Archives session file, writes summary, cleans up.
+ * Returns completion flags.
+ *
+ * @param params - Execute parameters
+ * @returns Execute result with completion flags
+ */
+export async function executeFinish(params) {
+    const { storyId, sessionDir, archiveDir, contextDir, summaryContent } = params;
+    const sessionPath = join(sessionDir, `${storyId}-session.md`);
+    const dateStr = formatDateForFilename();
+    const archivePath = join(archiveDir, `story-${storyId}-${dateStr}.md`);
+    let archived = false;
+    let sessionCleared = false;
+    let summaryPath;
+    try {
+        // Archive session file
+        if (existsSync(sessionPath)) {
+            const content = readFileSync(sessionPath, 'utf-8');
+            writeFileSync(archivePath, content);
+            archived = true;
+            // Remove session file
+            unlinkSync(sessionPath);
+            sessionCleared = true;
+        }
+        // Write summary file if contextDir provided
+        if (contextDir) {
+            summaryPath = join(contextDir, `story-${storyId}-summary.md`);
+            writeFileSync(summaryPath, summaryContent);
+        }
+        return {
+            success: true,
+            archived,
+            sessionCleared,
+            archivePath,
+            summaryPath
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            archived,
+            sessionCleared,
+            archivePath: archived ? archivePath : undefined,
+            summaryPath,
+            error: `Failed to execute finish: ${error}`
+        };
+    }
+}
+//# sourceMappingURL=generic-sm-finish.js.map

package/packages/core/dist/workflow/generic-sm-finish.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-sm-finish.js","sourceRoot":"","sources":["../../src/workflow/generic-sm-finish.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/workflow/generic-sm-setup.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Generic SM Setup - Combines story-setup + work-research
+ *
+ * Provides two modes:
+ * 1. Research mode: Scan backlog, batch Jira query, recommend stories
+ * 2. Setup mode: Claim Jira, create branches, write session file
+ */
+/**
+ * Story info from sprint YAML
+ */
+export interface StoryInfo {
+    id: string;
+    title: string;
+    status: string;
+    points?: number;
+    priority?: string;
+    epic?: number;
+}
+/**
+ * Research result - available stories and sprint metadata
+ */
+export interface ResearchResult {
+    success: boolean;
+    availableStories: StoryInfo[];
+    sprintNumber?: number;
+    sprintGoal?: string;
+    completedPoints?: number;
+    totalPoints?: number;
+    error?: string;
+}
+/**
+ * Setup result - session file and branch info
+ */
+export interface SetupResult {
+    success: boolean;
+    sessionFile?: string;
+    branchName?: string;
+    error?: string;
+    warnings?: string[];
+}
+export type GenericSmSetupResult = ResearchResult | SetupResult;
+/**
+ * Research mode parameters
+ */
+export interface ResearchParams {
+    sprintPath: string;
+}
+/**
+ * Setup mode parameters
+ */
+export interface SetupParams {
+    storyId: string;
+    title: string;
+    points: number;
+    epic: number;
+    repos: string;
+    sessionDir: string;
+    workflow: string;
+    assignee?: string;
+    jiraKey?: string;
+    acceptanceCriteria?: string[];
+    checkEpicContext?: boolean;
+    contextDir?: string;
+}
+/**
+ * Epic context check parameters
+ */
+export interface CheckEpicContextParams {
+    epicId: number;
+    contextDir: string;
+}
+/**
+ * Epic context check result
+ */
+export interface CheckEpicContextResult {
+    exists: boolean;
+    path?: string;
+    message?: string;
+    expectedPath?: string;
+}
+/**
+ * Epic context creation parameters
+ */
+export interface CreateEpicContextParams {
+    epicId: number;
+    epicTitle: string;
+    contextDir: string;
+    content?: string;
+}
+/**
+ * Epic context creation result
+ */
+export interface CreateEpicContextResult {
+    success: boolean;
+    path?: string;
+    error?: string;
+}
+/**
+ * Research backlog for available stories
+ *
+ * Scans sprint YAML and returns available (unassigned, backlog) stories
+ * sorted by priority then points.
+ *
+ * @param params - Research parameters
+ * @returns Research result with available stories
+ */
+export declare function researchBacklog(params: ResearchParams): Promise<ResearchResult>;
+/**
+ * Setup a story for development
+ *
+ * Creates session file with story context, calculates branch name,
+ * initializes workflow tracking with Phase History table.
+ *
+ * @param params - Setup parameters
+ * @returns Setup result with session file path and branch name
+ */
+export declare function setupStory(params: SetupParams): Promise<SetupResult>;
+/**
+ * Check if epic context file exists
+ *
+ * Validates that sprint/context/context-epic-{N}.md exists before story setup.
+ * This ensures stories don't start without understanding their epic's technical landscape.
+ *
+ * @param params - Check parameters with epicId and contextDir
+ * @returns Result indicating if context exists, with path or message
+ */
+export declare function checkEpicContext(params: CheckEpicContextParams): Promise<CheckEpicContextResult>;
+/**
+ * Create epic context file from template
+ *
+ * Creates a new epic context file with standard sections.
+ * Will not overwrite existing files to preserve valuable context.
+ *
+ * @param params - Creation parameters with epicId, title, contextDir, and optional content
+ * @returns Result with success status and file path
+ */
+export declare function createEpicContext(params: CreateEpicContextParams): Promise<CreateEpicContextResult>;
+//# sourceMappingURL=generic-sm-setup.d.ts.map

package/packages/core/dist/workflow/generic-sm-setup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"generic-sm-setup.d.ts","sourceRoot":"","sources":["../../src/workflow/generic-sm-setup.ts"],"names":[],"mappings":"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"}

package/packages/core/dist/workflow/generic-sm-setup.js

@@ -0,0 +1,382 @@
+/**
+ * Generic SM Setup - Combines story-setup + work-research
+ *
+ * Provides two modes:
+ * 1. Research mode: Scan backlog, batch Jira query, recommend stories
+ * 2. Setup mode: Claim Jira, create branches, write session file
+ */
+import { readFileSync, existsSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Parse YAML manually (simple parser for sprint YAML structure)
+ * This avoids external dependencies like js-yaml
+ */
+function parseSprintYaml(content) {
+    const lines = content.split('\n');
+    // Extract sprint section
+    let sprintNumber;
+    let sprintGoal;
+    let completedPoints;
+    let totalPoints;
+    const stories = [];
+    let currentEpicId;
+    let inStoriesSection = false;
+    let currentStory = null;
+    let storyIndent = 0;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const trimmed = line.trim();
+        const indent = line.length - line.trimStart().length;
+        // Sprint metadata (any indent)
+        if (trimmed.startsWith('number:') && !inStoriesSection) {
+            sprintNumber = parseInt(trimmed.replace('number:', '').trim(), 10);
+        }
+        else if (trimmed.startsWith('goal:') && !inStoriesSection) {
+            sprintGoal = trimmed.replace('goal:', '').trim().replace(/^["']|["']$/g, '');
+        }
+        else if (trimmed.startsWith('completed_points:')) {
+            completedPoints = parseInt(trimmed.replace('completed_points:', '').trim(), 10);
+        }
+        else if (trimmed.startsWith('total_points:')) {
+            totalPoints = parseInt(trimmed.replace('total_points:', '').trim(), 10);
+        }
+        // Epic detection: "  - id: 31" at indent 2
+        else if (trimmed.startsWith('- id:') && indent === 2) {
+            const epicId = parseInt(trimmed.replace('- id:', '').trim(), 10);
+            if (!isNaN(epicId)) {
+                currentEpicId = epicId;
+                inStoriesSection = false;
+            }
+        }
+        // Stories section marker
+        else if (trimmed === 'stories:') {
+            inStoriesSection = true;
+        }
+        // Story item: "      - id: ..." at indent 6 or more (after stories:)
+        else if (inStoriesSection && trimmed.startsWith('- id:')) {
+            // Save previous story
+            if (currentStory && currentStory.id) {
+                stories.push({
+                    id: currentStory.id,
+                    title: currentStory.title || '',
+                    status: currentStory.status || 'backlog',
+                    points: currentStory.points,
+                    priority: currentStory.priority,
+                    epic: currentEpicId,
+                    assigned_to: currentStory.assigned_to
+                });
+            }
+            // Start new story
+            storyIndent = indent;
+            const storyId = trimmed.replace('- id:', '').trim().replace(/^["']|["']$/g, '');
+            currentStory = { id: storyId, epic: currentEpicId };
+        }
+        // Story properties (must be indented more than story item)
+        else if (currentStory && indent > storyIndent) {
+            if (trimmed.startsWith('title:')) {
+                currentStory.title = trimmed.replace('title:', '').trim().replace(/^["']|["']$/g, '');
+            }
+            else if (trimmed.startsWith('status:')) {
+                currentStory.status = trimmed.replace('status:', '').trim();
+            }
+            else if (trimmed.startsWith('points:')) {
+                currentStory.points = parseInt(trimmed.replace('points:', '').trim(), 10);
+            }
+            else if (trimmed.startsWith('priority:')) {
+                currentStory.priority = trimmed.replace('priority:', '').trim();
+            }
+            else if (trimmed.startsWith('assigned_to:')) {
+                currentStory.assigned_to = trimmed.replace('assigned_to:', '').trim().replace(/^["']|["']$/g, '');
+            }
+        }
+        // Exit stories section when we hit something at lower indent
+        else if (inStoriesSection && trimmed && indent <= 2 && !trimmed.startsWith('-')) {
+            // Save last story before exiting
+            if (currentStory && currentStory.id) {
+                stories.push({
+                    id: currentStory.id,
+                    title: currentStory.title || '',
+                    status: currentStory.status || 'backlog',
+                    points: currentStory.points,
+                    priority: currentStory.priority,
+                    epic: currentEpicId,
+                    assigned_to: currentStory.assigned_to
+                });
+                currentStory = null;
+            }
+            inStoriesSection = false;
+        }
+    }
+    // Don't forget the last story
+    if (currentStory && currentStory.id) {
+        stories.push({
+            id: currentStory.id,
+            title: currentStory.title || '',
+            status: currentStory.status || 'backlog',
+            points: currentStory.points,
+            priority: currentStory.priority,
+            epic: currentEpicId,
+            assigned_to: currentStory.assigned_to
+        });
+    }
+    return {
+        sprint: { number: sprintNumber, goal: sprintGoal },
+        summary: { completed_points: completedPoints, total_points: totalPoints },
+        stories
+    };
+}
+/**
+ * Research backlog for available stories
+ *
+ * Scans sprint YAML and returns available (unassigned, backlog) stories
+ * sorted by priority then points.
+ *
+ * @param params - Research parameters
+ * @returns Research result with available stories
+ */
+export async function researchBacklog(params) {
+    const { sprintPath } = params;
+    // Check if file exists
+    if (!existsSync(sprintPath)) {
+        return {
+            success: false,
+            availableStories: [],
+            error: `Sprint file not found: ${sprintPath}`
+        };
+    }
+    try {
+        const content = readFileSync(sprintPath, 'utf-8');
+        const parsed = parseSprintYaml(content);
+        const sprint = parsed.sprint;
+        const summary = parsed.summary;
+        const allStories = parsed.stories || [];
+        // Filter: only backlog stories without assigned_to
+        const availableStories = allStories.filter(story => {
+            const hasAssignee = 'assigned_to' in story && story.assigned_to;
+            const isBacklog = story.status === 'backlog';
+            return isBacklog && !hasAssignee;
+        });
+        // Sort by priority (P1 < P2 < undefined) then by points ascending
+        const priorityOrder = { 'P1': 1, 'P2': 2, 'P3': 3 };
+        availableStories.sort((a, b) => {
+            const aPriority = priorityOrder[a.priority || ''] || 99;
+            const bPriority = priorityOrder[b.priority || ''] || 99;
+            if (aPriority !== bPriority) {
+                return aPriority - bPriority;
+            }
+            return (a.points || 0) - (b.points || 0);
+        });
+        return {
+            success: true,
+            availableStories,
+            sprintNumber: sprint?.number,
+            sprintGoal: sprint?.goal,
+            completedPoints: summary?.completed_points,
+            totalPoints: summary?.total_points
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            availableStories: [],
+            error: `Failed to parse sprint YAML: ${error}`
+        };
+    }
+}
+/**
+ * Convert title to kebab-case slug for branch naming
+ */
+function slugify(title) {
+    return title
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '');
+}
+/**
+ * Setup a story for development
+ *
+ * Creates session file with story context, calculates branch name,
+ * initializes workflow tracking with Phase History table.
+ *
+ * @param params - Setup parameters
+ * @returns Setup result with session file path and branch name
+ */
+export async function setupStory(params) {
+    const { storyId, title, points, epic, repos, sessionDir, workflow, assignee, jiraKey, acceptanceCriteria, checkEpicContext: shouldCheckContext, contextDir } = params;
+    // Collect warnings for non-blocking issues
+    const warnings = [];
+    // Check epic context if gate is enabled
+    if (shouldCheckContext && contextDir) {
+        const contextCheck = await checkEpicContext({ epicId: epic, contextDir });
+        if (!contextCheck.exists) {
+            // Warn but don't block (soft gate initially)
+            warnings.push(`Missing epic context: ${contextCheck.message}`);
+        }
+    }
+    // Calculate branch name
+    const slug = slugify(title);
+    const branchName = `feat/${storyId}-${slug}`;
+    // Session file path
+    const sessionPath = join(sessionDir, `${storyId}-session.md`);
+    // Check if session file already exists
+    if (existsSync(sessionPath)) {
+        return {
+            success: false,
+            error: `Session file already exists: ${sessionPath}`
+        };
+    }
+    // Generate ISO timestamp
+    const now = new Date().toISOString();
+    // Build session file content
+    const lines = [
+        `# Story ${storyId} Session`,
+        '',
+        `**Story ID:** ${storyId}`,
+        `**Title:** ${title}`,
+        `**Points:** ${points}`,
+        `**Epic:** ${epic}`,
+        `**Repos:** ${repos}`,
+        `**Status:** in_progress`
+    ];
+    if (assignee) {
+        lines.push(`**Assignee:** ${assignee}`);
+    }
+    if (jiraKey) {
+        lines.push(`**Jira:** ${jiraKey}`);
+    }
+    // Acceptance criteria section
+    if (acceptanceCriteria && acceptanceCriteria.length > 0) {
+        lines.push('');
+        lines.push('## Acceptance Criteria');
+        lines.push('');
+        for (const ac of acceptanceCriteria) {
+            lines.push(`- [ ] ${ac}`);
+        }
+    }
+    // Workflow tracking section
+    lines.push('');
+    lines.push('## Workflow Tracking');
+    lines.push('');
+    lines.push(`**Workflow:** ${workflow}`);
+    lines.push(`**Phase:** setup`);
+    lines.push(`**Phase Started:** ${now}`);
+    lines.push('');
+    lines.push('### Phase History');
+    lines.push('| Phase | Started | Ended | Duration |');
+    lines.push('|-------|---------|-------|----------|');
+    lines.push(`| setup | ${now} | - | - |`);
+    lines.push('');
+    // Write file
+    try {
+        writeFileSync(sessionPath, lines.join('\n'));
+        return {
+            success: true,
+            sessionFile: sessionPath,
+            branchName,
+            warnings
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to write session file: ${error}`
+        };
+    }
+}
+/**
+ * Check if epic context file exists
+ *
+ * Validates that sprint/context/context-epic-{N}.md exists before story setup.
+ * This ensures stories don't start without understanding their epic's technical landscape.
+ *
+ * @param params - Check parameters with epicId and contextDir
+ * @returns Result indicating if context exists, with path or message
+ */
+export async function checkEpicContext(params) {
+    const { epicId, contextDir } = params;
+    const filename = `context-epic-${epicId}.md`;
+    const expectedPath = join(contextDir, filename);
+    if (existsSync(expectedPath)) {
+        return {
+            exists: true,
+            path: expectedPath
+        };
+    }
+    return {
+        exists: false,
+        message: `Epic ${epicId} is missing technical context. Create ${filename} before starting stories.`,
+        expectedPath
+    };
+}
+/**
+ * Create epic context file from template
+ *
+ * Creates a new epic context file with standard sections.
+ * Will not overwrite existing files to preserve valuable context.
+ *
+ * @param params - Creation parameters with epicId, title, contextDir, and optional content
+ * @returns Result with success status and file path
+ */
+export async function createEpicContext(params) {
+    const { epicId, epicTitle, contextDir, content } = params;
+    const filename = `context-epic-${epicId}.md`;
+    const filePath = join(contextDir, filename);
+    // Don't overwrite existing context
+    if (existsSync(filePath)) {
+        return {
+            success: false,
+            error: `Epic context file already exists: ${filePath}`
+        };
+    }
+    // Build content from template or provided content
+    let fileContent;
+    if (content) {
+        // Use provided content with header
+        fileContent = `# Epic ${epicId}: ${epicTitle} - Technical Context\n\n${content}`;
+    }
+    else {
+        // Use standard template
+        fileContent = `# Epic ${epicId}: ${epicTitle} - Technical Context
+
+## Epic Overview
+- Goal: [One sentence describing the epic goal]
+- Stories: [count] totaling [points] pts
+- Status: in_progress
+
+## Technical Landscape
+[2-3 paragraphs describing the technical domain, key challenges, and approach]
+
+## Key Files
+| File | Purpose |
+|------|---------|
+| path/to/file | Description |
+
+## Patterns & Conventions
+- Pattern 1: Description
+- Pattern 2: Description
+
+## Dependencies & Risks
+- Dependency: Description
+- Risk: Mitigation
+
+## Story Sequence
+| Story | Title | Depends On |
+|-------|-------|------------|
+| ${epicId}-1 | First story | None |
+`;
+    }
+    try {
+        writeFileSync(filePath, fileContent);
+        return {
+            success: true,
+            path: filePath
+        };
+    }
+    catch (error) {
+        return {
+            success: false,
+            error: `Failed to create epic context: ${error}`
+        };
+    }
+}
+//# sourceMappingURL=generic-sm-setup.js.map