mcp-ai-agent-guidelines/dist/strategies/speckit/progress-tracker.d.ts

A comprehensive Model Context Protocol server providing advanced tools, resources, and prompts for implementing AI agent best practices

/**
 * Progress tracking service for Spec-Kit artifacts
 *
 * @module strategies/speckit/progress-tracker
 */
import type { ProgressMetrics, Tasks } from "./types.js";
/**
 * Status of a single task
 */
export interface TaskStatus {
    /** Task identifier */
    id: string;
    /** Whether the task is completed */
    completed: boolean;
    /** Timestamp when completed (ISO-8601) */
    completedAt?: string;
    /** Optional notes about the task status */
    notes?: string;
}
/**
 * Update for a task's progress
 */
export interface TaskProgressUpdate {
    /** Task identifier to update */
    taskId: string;
    /** New status for the task */
    status: "completed" | "in-progress" | "blocked";
    /** Optional notes about the update */
    notes?: string;
    /** Optional timestamp for the update (ISO-8601) */
    timestamp?: string;
}
/**
 * Git commit information
 */
export interface GitCommit {
    /** Commit hash */
    hash: string;
    /** Commit message */
    message: string;
    /** Commit date (ISO-8601) */
    date: string;
    /** Commit author */
    author: string;
}
/**
 * Options for syncing progress from git
 */
export interface GitSyncOptions {
    /** Path to git repository (defaults to current directory) */
    repoPath?: string;
    /** Branch to scan (defaults to HEAD) */
    branch?: string;
    /** Only scan commits since this date/time (ISO-8601) */
    since?: string;
    /** Custom pattern for task ID extraction */
    taskIdPattern?: RegExp;
}
/**
 * Service for tracking specification progress
 *
 * Manages task completion state and generates progress.md content.
 *
 * @example
 * ```typescript
 * const tracker = createProgressTracker(tasks);
 * tracker.updateProgress({ taskId: "TASK-001", status: "completed" });
 * const metrics = tracker.calculateCompletion();
 * const markdown = tracker.generateProgressMarkdown();
 * ```
 */
export declare class ProgressTracker {
    private tasks?;
    private taskStatuses;
    constructor(tasks?: Tasks | undefined);
    private initializeFromTasks;
    /**
     * Load progress from existing progress.md content
     *
     * Parses markdown checkboxes to determine task completion status.
     *
     * @param content - The progress.md markdown content
     *
     * @example
     * ```typescript
     * const content = `
     * ## Tasks
     * - [x] **TASK-001**: Setup database
     * - [ ] **TASK-002**: Create API
     * `;
     * tracker.loadProgress(content);
     * ```
     */
    loadProgress(content: string): void;
    /**
     * Load progress from file
     *
     * Reads and parses progress.md file from disk.
     *
     * @param path - Path to progress.md file
     * @throws Error if file cannot be read
     *
     * @example
     * ```typescript
     * await tracker.loadProgressFromFile('./progress.md');
     * ```
     */
    loadProgressFromFile(path: string): Promise<void>;
    /**
     * Update progress for a specific task
     *
     * @param update - Progress update information
     * @throws Error if task ID is unknown
     *
     * @example
     * ```typescript
     * tracker.updateProgress({
     *   taskId: "TASK-001",
     *   status: "completed",
     *   notes: "All tests passing"
     * });
     * ```
     */
    updateProgress(update: TaskProgressUpdate): void;
    /**
     * Batch update multiple tasks
     *
     * @param updates - Array of progress updates
     *
     * @example
     * ```typescript
     * tracker.updateMultiple([
     *   { taskId: "TASK-001", status: "completed" },
     *   { taskId: "TASK-002", status: "in-progress" }
     * ]);
     * ```
     */
    updateMultiple(updates: TaskProgressUpdate[]): void;
    /**
     * Calculate completion metrics
     *
     * @returns Metrics including total, completed, remaining, and percentage
     *
     * @example
     * ```typescript
     * const metrics = tracker.calculateCompletion();
     * console.log(`Progress: ${metrics.percentComplete}%`);
     * ```
     */
    calculateCompletion(): ProgressMetrics;
    /**
     * Generate progress.md content
     *
     * Creates formatted markdown with summary table and task checklist.
     *
     * @returns Markdown content for progress.md
     *
     * @example
     * ```typescript
     * const markdown = tracker.generateProgressMarkdown();
     * await fs.writeFile('progress.md', markdown);
     * ```
     */
    generateProgressMarkdown(): string;
    /**
     * Sync progress from git commit history
     *
     * Scans git commit messages for task references and automatically updates
     * task status based on commit keywords like "closes", "fixes", etc.
     *
     * @param options - Options for git sync
     * @returns Array of progress updates that were applied
     *
     * @example
     * ```typescript
     * const updates = tracker.syncFromGit({
     *   since: "2026-01-01",
     *   branch: "main"
     * });
     * console.log(`Updated ${updates.length} tasks from git history`);
     * ```
     */
    syncFromGit(options?: GitSyncOptions): TaskProgressUpdate[];
    /**
     * Fetch commits from git repository
     *
     * @param options - Git sync options
     * @returns Array of git commits
     * @private
     */
    private fetchCommits;
    /**
     * Extract task references from commit message
     *
     * Parses commit messages for standard patterns like "closes #123" or
     * "fixes TASK-001" as well as standalone task ID mentions.
     *
     * @param message - Commit message to parse
     * @param customPattern - Optional custom regex pattern for task IDs
     * @returns Array of task references with action and task ID
     * @private
     */
    private extractTaskReferences;
    /**
     * Watch for new commits and update progress automatically
     *
     * Starts a periodic sync process that checks for new commits and updates
     * task progress. Returns a cleanup function to stop watching.
     *
     * @param options - Git sync options with optional interval
     * @returns Cleanup function to stop watching
     *
     * @example
     * ```typescript
     * const stopWatching = tracker.watchAndSync({
     *   intervalMs: 60000, // Check every minute
     *   branch: "main"
     * });
     *
     * // Later, to stop watching:
     * stopWatching();
     * ```
     */
    watchAndSync(options: GitSyncOptions & {
        intervalMs?: number;
    }): () => void;
    private getStatusIndicator;
    private extractTaskId;
}
/**
 * Factory function to create a ProgressTracker instance
 *
 * @param tasks - Optional task collection to initialize with
 * @returns New ProgressTracker instance
 *
 * @example
 * ```typescript
 * const tracker = createProgressTracker(tasks);
 * ```
 */
export declare function createProgressTracker(tasks?: Tasks): ProgressTracker;
//# sourceMappingURL=progress-tracker.d.ts.map