profclaw 0.0.1-beta.1

package/dist/summaries/templates.js

@@ -0,0 +1,245 @@
+/**
+ * Summary Templates - Generate formatted output from task summaries
+ *
+ * Supports:
+ * - PR descriptions (GitHub, GitLab, Bitbucket)
+ * - Changelog entries (Keep a Changelog format)
+ * - Release notes
+ * - Commit messages (Conventional Commits)
+ */
+/**
+ * Task type templates with conventional commit prefixes and changelog categories
+ */
+export const TASK_TYPE_TEMPLATES = {
+    feature: { title: 'New Feature', prPrefix: 'feat', changelogCategory: 'Added', emoji: '✨' },
+    bug_fix: { title: 'Bug Fix', prPrefix: 'fix', changelogCategory: 'Fixed', emoji: '🐛' },
+    refactor: { title: 'Refactoring', prPrefix: 'refactor', changelogCategory: 'Changed', emoji: '♻️' },
+    documentation: { title: 'Documentation', prPrefix: 'docs', changelogCategory: 'Changed', emoji: '📚' },
+    performance: { title: 'Performance', prPrefix: 'perf', changelogCategory: 'Changed', emoji: '⚡' },
+    security: { title: 'Security', prPrefix: 'security', changelogCategory: 'Security', emoji: '🔒' },
+    test: { title: 'Testing', prPrefix: 'test', changelogCategory: 'Changed', emoji: '🧪' },
+    chore: { title: 'Maintenance', prPrefix: 'chore', changelogCategory: 'Changed', emoji: '🔧' },
+    deprecation: { title: 'Deprecation', prPrefix: 'deprecate', changelogCategory: 'Deprecated', emoji: '⚠️' },
+    removal: { title: 'Removal', prPrefix: 'remove', changelogCategory: 'Removed', emoji: '🗑️' },
+};
+/**
+ * Generate a GitHub-formatted Pull Request description from a summary
+ */
+export function generatePRDescription(summary, options = {}) {
+    const { includeFileChanges = true, includeDecisions = true, includeBlockers = true, includeTokenStats = false, } = options;
+    const taskType = summary.taskType || 'feature';
+    const template = TASK_TYPE_TEMPLATES[taskType] || TASK_TYPE_TEMPLATES.feature;
+    let body = `## ${template.emoji} Summary\n\n`;
+    body += `${summary.whatChanged}\n\n`;
+    if (summary.whyChanged) {
+        body += `### 💡 Why\n${summary.whyChanged}\n\n`;
+    }
+    if (summary.howChanged) {
+        body += `### 🔧 How\n${summary.howChanged}\n\n`;
+    }
+    if (includeFileChanges && summary.filesChanged && summary.filesChanged.length > 0) {
+        body += `### 📁 Files Changed\n`;
+        summary.filesChanged.forEach(f => {
+            const file = f;
+            if (typeof f === 'string') {
+                body += `- \`${f}\`\n`;
+            }
+            else if (file.path) {
+                const icon = file.action === 'created' ? '🆕' : file.action === 'deleted' ? '🗑️' : '📝';
+                const stats = (file.additions !== undefined || file.deletions !== undefined)
+                    ? ` [+${file.additions || 0}/-${file.deletions || 0}]`
+                    : '';
+                body += `- ${icon} \`${file.path}\`${stats}\n`;
+            }
+        });
+        body += '\n';
+    }
+    if (includeDecisions && summary.decisions && summary.decisions.length > 0) {
+        body += `### 🎯 Key Decisions\n`;
+        summary.decisions.forEach(d => {
+            const decision = d;
+            if (typeof d === 'string') {
+                body += `- ${d}\n`;
+            }
+            else if (decision.description) {
+                body += `- **${decision.description}**${decision.reason ? `: ${decision.reason}` : ''}\n`;
+            }
+        });
+        body += '\n';
+    }
+    if (includeBlockers && summary.blockers && summary.blockers.length > 0) {
+        body += `### ⚠️ Known Issues\n`;
+        summary.blockers.forEach(b => {
+            const blocker = b;
+            if (typeof b === 'string') {
+                body += `- ${b}\n`;
+            }
+            else if (blocker.description) {
+                const severityIcon = blocker.severity === 'critical' ? '🔴' : blocker.severity === 'error' ? '🟠' : '🟡';
+                body += `- ${severityIcon} ${blocker.description}\n`;
+            }
+        });
+        body += '\n';
+    }
+    if (includeTokenStats && summary.tokensUsed) {
+        const tokens = summary.tokensUsed;
+        body += `### 📊 AI Stats\n`;
+        body += `- Tokens: ${tokens.total?.toLocaleString() || 'N/A'}\n`;
+        if (summary.cost) {
+            const cost = summary.cost;
+            body += `- Cost: $${cost.amount?.toFixed(4) || '0.0000'}\n`;
+        }
+        body += '\n';
+    }
+    body += `---\n*Generated by [profClaw](https://github.com/profclaw/profclaw) • Agent: ${summary.agent}*`;
+    return body;
+}
+/**
+ * Generate a release changelog from a collection of summaries
+ * Uses Keep a Changelog format by default
+ */
+export function generateChangelog(summaries, options = {}) {
+    // Support old API: generateChangelog(summaries, version)
+    const opts = typeof options === 'string' ? { version: options } : options;
+    const { version = 'Unreleased', date = new Date().toISOString().split('T')[0], format = 'keepachangelog', includeIssueLinks = true, issueLinkBase = '', } = opts;
+    if (format === 'simple') {
+        // Simple grouped format (original behavior)
+        let changelog = `# Changelog - ${version} (${date})\n\n`;
+        const groups = {};
+        summaries.forEach(s => {
+            const groupKey = s.taskType || s.agent || 'Other';
+            if (!groups[groupKey])
+                groups[groupKey] = [];
+            groups[groupKey].push(s);
+        });
+        for (const [groupName, groupSummaries] of Object.entries(groups)) {
+            const formattedGroup = groupName.charAt(0).toUpperCase() + groupName.slice(1);
+            changelog += `## ${formattedGroup}\n`;
+            groupSummaries.forEach(s => {
+                changelog += `- **${s.title}**: ${s.whatChanged.split('\n')[0]}\n`;
+                if (includeIssueLinks && s.linkedIssue) {
+                    changelog += `  - Linked Issue: #${s.linkedIssue}\n`;
+                }
+            });
+            changelog += '\n';
+        }
+        return changelog;
+    }
+    // Keep a Changelog format (default)
+    const grouped = {
+        Added: [],
+        Changed: [],
+        Fixed: [],
+        Removed: [],
+        Security: [],
+        Deprecated: [],
+    };
+    for (const summary of summaries) {
+        const taskType = summary.taskType || 'feature';
+        const template = TASK_TYPE_TEMPLATES[taskType] || TASK_TYPE_TEMPLATES.feature;
+        grouped[template.changelogCategory].push(summary);
+    }
+    let changelog = `## [${version}] - ${date}\n\n`;
+    for (const [category, items] of Object.entries(grouped)) {
+        if (items.length === 0)
+            continue;
+        changelog += `### ${category}\n\n`;
+        for (const summary of items) {
+            let entry = `- ${summary.whatChanged.split('\n')[0]}`;
+            if (includeIssueLinks && summary.linkedIssue) {
+                const issueNum = summary.linkedIssue.replace(/[^\d]/g, '');
+                entry += issueLinkBase
+                    ? ` ([#${issueNum}](${issueLinkBase}${issueNum}))`
+                    : ` (#${issueNum})`;
+            }
+            changelog += `${entry}\n`;
+        }
+        changelog += '\n';
+    }
+    return changelog;
+}
+/**
+ * Generate release notes from summaries
+ */
+export function generateReleaseNotes(summaries, options = { version: '1.0.0' }) {
+    const { version, title = `Release ${version}`, includeStats = true } = options;
+    let notes = `# ${title}\n\n`;
+    if (includeStats) {
+        const stats = { features: 0, fixes: 0, other: 0, totalFiles: 0 };
+        for (const summary of summaries) {
+            const taskType = summary.taskType || 'feature';
+            if (taskType === 'feature')
+                stats.features++;
+            else if (taskType === 'bug_fix')
+                stats.fixes++;
+            else
+                stats.other++;
+            stats.totalFiles += (summary.filesChanged || []).length;
+        }
+        notes += `## 📊 Overview\n\n`;
+        notes += `- **${stats.features}** new features\n`;
+        notes += `- **${stats.fixes}** bug fixes\n`;
+        if (stats.other > 0)
+            notes += `- **${stats.other}** other improvements\n`;
+        notes += `- **${stats.totalFiles}** files modified\n\n`;
+    }
+    // Features
+    const features = summaries.filter(s => (s.taskType || 'feature') === 'feature');
+    if (features.length > 0) {
+        notes += `## ✨ Features\n\n`;
+        for (const s of features) {
+            notes += `- **${s.title}**: ${s.whatChanged.split('\n')[0]}\n`;
+        }
+        notes += '\n';
+    }
+    // Bug fixes
+    const fixes = summaries.filter(s => s.taskType === 'bug_fix');
+    if (fixes.length > 0) {
+        notes += `## 🐛 Bug Fixes\n\n`;
+        for (const s of fixes) {
+            notes += `- **${s.title}**: ${s.whatChanged.split('\n')[0]}\n`;
+        }
+        notes += '\n';
+    }
+    // Other
+    const other = summaries.filter(s => !['feature', 'bug_fix'].includes(s.taskType || 'feature'));
+    if (other.length > 0) {
+        notes += `## 🔧 Other Changes\n\n`;
+        for (const s of other) {
+            const template = TASK_TYPE_TEMPLATES[s.taskType || 'chore'] || TASK_TYPE_TEMPLATES.chore;
+            notes += `- ${template.emoji} **${s.title}**: ${s.whatChanged.split('\n')[0]}\n`;
+        }
+        notes += '\n';
+    }
+    notes += `---\n*Generated by profClaw*`;
+    return notes;
+}
+/**
+ * Get conventional commit prefix for a task type
+ */
+export function getConventionalCommitPrefix(taskType) {
+    const template = TASK_TYPE_TEMPLATES[taskType];
+    return template?.prPrefix || 'chore';
+}
+/**
+ * Generate a conventional commit message from a summary
+ */
+export function generateCommitMessage(summary, options = {}) {
+    const { maxLength = 72, includeBody = false } = options;
+    const taskType = summary.taskType || 'feature';
+    const prefix = getConventionalCommitPrefix(taskType);
+    const scope = summary.component ? `(${summary.component})` : '';
+    let subject = `${prefix}${scope}: ${summary.title}`;
+    if (subject.length > maxLength) {
+        subject = subject.substring(0, maxLength - 3) + '...';
+    }
+    if (!includeBody) {
+        return subject;
+    }
+    let message = `${subject}\n\n${summary.whatChanged}`;
+    if (summary.linkedIssue) {
+        message += `\n\nCloses ${summary.linkedIssue}`;
+    }
+    return message;
+}
+//# sourceMappingURL=templates.js.map

package/dist/sync/adapters/base.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Base Sync Adapter
+ *
+ * Abstract base class for all platform sync adapters.
+ * Provides common functionality and enforces the adapter interface.
+ */
+import type { SyncAdapter, SyncAdapterConfig, ExternalTicket, ExternalComment, ListTicketsOptions, WebhookEvent } from '../types.js';
+import type { Ticket, TicketStatus, TicketPriority, TicketType } from '../../tickets/types.js';
+export declare abstract class BaseSyncAdapter implements SyncAdapter {
+    abstract readonly platform: string;
+    readonly config: SyncAdapterConfig;
+    protected connected: boolean;
+    constructor(config: SyncAdapterConfig);
+    abstract connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    isConnected(): boolean;
+    abstract healthCheck(): Promise<{
+        healthy: boolean;
+        latencyMs: number;
+    }>;
+    abstract createTicket(ticket: Ticket): Promise<ExternalTicket>;
+    abstract updateTicket(externalId: string, updates: Partial<Ticket>): Promise<ExternalTicket>;
+    abstract deleteTicket(externalId: string): Promise<boolean>;
+    abstract getTicket(externalId: string): Promise<ExternalTicket | null>;
+    abstract listTickets(options?: ListTicketsOptions): Promise<{
+        tickets: ExternalTicket[];
+        cursor?: string;
+    }>;
+    abstract addComment(externalTicketId: string, content: string): Promise<ExternalComment>;
+    abstract getComments(externalTicketId: string): Promise<ExternalComment[]>;
+    mapStatusToExternal(status: TicketStatus): string;
+    mapStatusFromExternal(externalStatus: string): TicketStatus;
+    mapPriorityToExternal(priority: TicketPriority): string | number | undefined;
+    mapPriorityFromExternal(externalPriority: string | number): TicketPriority;
+    mapTypeToExternal(type: TicketType): string | undefined;
+    mapTypeFromExternal(externalType: string): TicketType;
+    parseWebhook?(_payload: unknown): WebhookEvent | null;
+    protected makeRequest<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', url: string, body?: unknown, headers?: Record<string, string>): Promise<T>;
+    protected log(message: string, data?: unknown): void;
+    protected error(message: string, err?: unknown): void;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/sync/adapters/base.js

@@ -0,0 +1,142 @@
+/**
+ * Base Sync Adapter
+ *
+ * Abstract base class for all platform sync adapters.
+ * Provides common functionality and enforces the adapter interface.
+ */
+import { STATUS_MAP, REVERSE_STATUS_MAP, PRIORITY_MAP } from '../../tickets/types.js';
+import { logger } from '../../utils/logger.js';
+export class BaseSyncAdapter {
+    config;
+    connected = false;
+    constructor(config) {
+        this.config = config;
+    }
+    async disconnect() {
+        this.connected = false;
+    }
+    isConnected() {
+        return this.connected;
+    }
+    // === Status Mapping (default implementation using STATUS_MAP) ===
+    mapStatusToExternal(status) {
+        const platformMap = STATUS_MAP[status];
+        if (platformMap && platformMap[this.platform]) {
+            return platformMap[this.platform];
+        }
+        // Fallback: capitalize first letter
+        return status.charAt(0).toUpperCase() + status.slice(1).replace(/_/g, ' ');
+    }
+    mapStatusFromExternal(externalStatus) {
+        const platformMap = REVERSE_STATUS_MAP[this.platform];
+        if (platformMap && platformMap[externalStatus]) {
+            return platformMap[externalStatus];
+        }
+        // Fallback: try to match common patterns
+        const normalized = externalStatus.toLowerCase().replace(/\s+/g, '_');
+        const validStatuses = ['backlog', 'todo', 'in_progress', 'in_review', 'done', 'cancelled'];
+        if (validStatuses.includes(normalized)) {
+            return normalized;
+        }
+        // Default to backlog for unknown statuses
+        return 'backlog';
+    }
+    // === Priority Mapping (default implementation using PRIORITY_MAP) ===
+    mapPriorityToExternal(priority) {
+        const platformMap = PRIORITY_MAP[priority];
+        if (platformMap && platformMap[this.platform] !== undefined) {
+            return platformMap[this.platform];
+        }
+        return priority;
+    }
+    mapPriorityFromExternal(externalPriority) {
+        // Try to match by value
+        for (const [profclawPriority, platformMap] of Object.entries(PRIORITY_MAP)) {
+            if (platformMap[this.platform] === externalPriority) {
+                return profclawPriority;
+            }
+        }
+        // Fallback: try common patterns
+        const normalized = String(externalPriority).toLowerCase();
+        if (normalized.includes('urgent') || normalized.includes('critical') || normalized.includes('highest')) {
+            return 'critical';
+        }
+        if (normalized.includes('high')) {
+            return 'high';
+        }
+        if (normalized.includes('medium') || normalized.includes('normal')) {
+            return 'medium';
+        }
+        if (normalized.includes('low')) {
+            return 'low';
+        }
+        return 'none';
+    }
+    // === Type Mapping (default implementation) ===
+    mapTypeToExternal(type) {
+        // Most platforms use similar naming
+        const typeMap = {
+            task: 'Task',
+            bug: 'Bug',
+            feature: 'Feature',
+            epic: 'Epic',
+            story: 'Story',
+            subtask: 'Subtask',
+        };
+        return typeMap[type] || type;
+    }
+    mapTypeFromExternal(externalType) {
+        const normalized = externalType.toLowerCase();
+        const validTypes = ['task', 'bug', 'feature', 'epic', 'story', 'subtask'];
+        if (validTypes.includes(normalized)) {
+            return normalized;
+        }
+        // Common mappings
+        if (normalized.includes('issue') || normalized.includes('task'))
+            return 'task';
+        if (normalized.includes('bug') || normalized.includes('defect'))
+            return 'bug';
+        if (normalized.includes('feature') || normalized.includes('enhancement'))
+            return 'feature';
+        if (normalized.includes('epic'))
+            return 'epic';
+        if (normalized.includes('story') || normalized.includes('user story'))
+            return 'story';
+        if (normalized.includes('subtask') || normalized.includes('sub-task'))
+            return 'subtask';
+        return 'task';
+    }
+    // === Webhook Parsing (optional, override in subclass) ===
+    parseWebhook(_payload) {
+        return null;
+    }
+    // === Helper Methods ===
+    async makeRequest(method, url, body, headers) {
+        const defaultHeaders = {
+            'Content-Type': 'application/json',
+        };
+        if (this.config.apiKey) {
+            defaultHeaders['Authorization'] = `Bearer ${this.config.apiKey}`;
+        }
+        else if (this.config.accessToken) {
+            defaultHeaders['Authorization'] = `Bearer ${this.config.accessToken}`;
+        }
+        const response = await fetch(url, {
+            method,
+            headers: { ...defaultHeaders, ...headers },
+            body: body ? JSON.stringify(body) : undefined,
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`${this.platform} API error (${response.status}): ${errorText}`);
+        }
+        return response.json();
+    }
+    log(message, data) {
+        logger.info(`[Sync:${this.platform}] ${message}`, data ? { data } : undefined);
+    }
+    error(message, err) {
+        logger.error(`[Sync:${this.platform}] ${message}`, err instanceof Error ? err : undefined);
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/sync/adapters/github.d.ts

@@ -0,0 +1,45 @@
+/**
+ * GitHub Issues Sync Adapter
+ *
+ * Bi-directional sync with GitHub Issues.
+ * Uses GitHub REST API v3.
+ */
+import { BaseSyncAdapter } from './base.js';
+import type { SyncAdapterConfig, ExternalTicket, ExternalComment, ListTicketsOptions, WebhookEvent } from '../types.js';
+import type { Ticket, TicketStatus, TicketPriority, TicketType } from '../../tickets/types.js';
+export declare class GitHubSyncAdapter extends BaseSyncAdapter {
+    readonly platform = "github";
+    private owner;
+    private repo;
+    constructor(config: SyncAdapterConfig);
+    connect(): Promise<void>;
+    healthCheck(): Promise<{
+        healthy: boolean;
+        latencyMs: number;
+    }>;
+    createTicket(ticket: Ticket): Promise<ExternalTicket>;
+    updateTicket(externalId: string, updates: Partial<Ticket>): Promise<ExternalTicket>;
+    deleteTicket(externalId: string): Promise<boolean>;
+    getTicket(externalId: string): Promise<ExternalTicket | null>;
+    listTickets(options?: ListTicketsOptions): Promise<{
+        tickets: ExternalTicket[];
+        cursor?: string;
+    }>;
+    addComment(externalTicketId: string, content: string): Promise<ExternalComment>;
+    getComments(externalTicketId: string): Promise<ExternalComment[]>;
+    mapStatusToExternal(status: TicketStatus): string;
+    mapStatusFromExternal(externalStatus: string): TicketStatus;
+    mapPriorityToExternal(priority: TicketPriority): string;
+    mapPriorityFromExternal(externalPriority: string | number): TicketPriority;
+    mapTypeToExternal(type: TicketType): string;
+    mapTypeFromExternal(externalType: string): TicketType;
+    parseWebhook(payload: unknown): WebhookEvent | null;
+    private getHeaders;
+    private request;
+    private buildLabels;
+    private isSystemLabel;
+    private toExternalTicket;
+    private fromExternalTicket;
+    private toExternalComment;
+}
+//# sourceMappingURL=github.d.ts.map