@jokerized/getresearchdone 0.4.1

package/dist/lib/tracker.js

@@ -0,0 +1,1121 @@
+'use strict';
+Object.defineProperty(exports, "__esModule", { value: true });
+const { fs, path, execFileSync, safeReadFile, safeReadMarkdown, stripShippedSections, loadConfig, output, error, } = require('./utils');
+const { computeSchedule, getScheduleForPhase, getScheduleForMilestone, } = require('./roadmap');
+const { phasesDir: getPhasesDirPath, } = require('./paths');
+// ─── Tracker Config & Mapping ─────────────────────────────────────────────────
+/**
+ * Load tracker configuration from config.json, with auto-migration of legacy formats.
+ * @param cwd - Project working directory
+ * @returns Tracker config object with provider field ('github', 'mcp-atlassian', or 'none')
+ */
+function loadTrackerConfig(cwd) {
+    const configPath = path.join(cwd, '.planning', 'config.json');
+    const raw = safeReadFile(configPath);
+    if (!raw)
+        return { provider: 'none' };
+    try {
+        const config = JSON.parse(raw);
+        // New tracker config format
+        if (config.tracker) {
+            const tracker = config.tracker;
+            // Auto-migrate old "jira" provider to "mcp-atlassian"
+            if (tracker.provider === 'jira') {
+                tracker.provider = 'mcp-atlassian';
+                if (tracker.jira && !tracker.mcp_atlassian) {
+                    const jira = tracker.jira;
+                    tracker.mcp_atlassian = {
+                        project_key: jira.project_key || '',
+                        milestone_issue_type: jira.epic_issue_type || 'Epic',
+                        phase_issue_type: jira.task_issue_type || 'Task',
+                        plan_issue_type: 'Sub-task',
+                    };
+                }
+            }
+            // Auto-migrate old epic/task config to milestone/phase/plan config
+            if (tracker.mcp_atlassian) {
+                const mcp = tracker.mcp_atlassian;
+                if (mcp.epic_issue_type && !mcp.milestone_issue_type) {
+                    mcp.milestone_issue_type = mcp.epic_issue_type;
+                    delete mcp.epic_issue_type;
+                }
+                if (mcp.task_issue_type && !mcp.phase_issue_type) {
+                    mcp.phase_issue_type = mcp.task_issue_type;
+                    delete mcp.task_issue_type;
+                }
+                if (!mcp.plan_issue_type) {
+                    mcp.plan_issue_type = 'Sub-task';
+                }
+            }
+            // Validate required fields for github provider
+            if (tracker.provider === 'github' && tracker.github) {
+                const gh = tracker.github;
+                if (!gh.project_board) {
+                    process.stderr.write('Warning: github tracker missing required field: project_board\n');
+                }
+            }
+            return tracker;
+        }
+        // Backward compat: migrate old github_integration format
+        if (config.github_integration && config.github_integration.enabled) {
+            const gi = config.github_integration;
+            return {
+                provider: 'github',
+                auto_sync: gi.auto_issues || false,
+                github: {
+                    project_board: gi.project_board || gi.project_name || '',
+                    default_assignee: gi.default_assignee || '',
+                    default_labels: gi.default_labels || gi.labels
+                        ? Object.values(gi.labels || {})
+                        : ['research', 'implementation', 'evaluation', 'integration'],
+                    auto_issues: gi.auto_issues || false,
+                    pr_per_phase: gi.pr_per_phase || false,
+                },
+            };
+        }
+        return { provider: 'none' };
+    }
+    catch (e) {
+        process.stderr.write('Warning: failed to parse config.json: ' + e.message + '\n');
+        return { provider: 'none' };
+    }
+}
+// Cache for loadTrackerMapping: keyed by cwd, stores { mtime, mapping, index }
+const _trackerMappingCache = new Map();
+/**
+ * Split a markdown table row into column strings (preserves empty cells).
+ * @param row - A single markdown table row string
+ * @returns Array of trimmed cell values
+ */
+function _splitTableRow(row) {
+    const parts = row.split('|').map((c) => c.trim());
+    if (parts.length > 0 && parts[0] === '')
+        parts.shift();
+    if (parts.length > 0 && parts[parts.length - 1] === '')
+        parts.pop();
+    return parts;
+}
+/**
+ * Build a Map index over a loaded mapping for O(1) lookups.
+ * Keys: milestone version strings, phase number strings, and "phase-plan" composite strings.
+ * @param mapping - Parsed mapping object with milestones, phases, and plans
+ * @returns Index map keyed by identifier
+ */
+function _buildTrackerIndex(mapping) {
+    const index = new Map();
+    for (const [k, v] of Object.entries(mapping.milestones || {}))
+        index.set(k, v);
+    for (const [k, v] of Object.entries(mapping.phases || {}))
+        index.set(k, v);
+    for (const [k, v] of Object.entries(mapping.plans || {}))
+        index.set(k, v);
+    return index;
+}
+/**
+ * Load the tracker ID mapping from TRACKER.md, parsing milestone/phase/plan tables.
+ * Results are cached in memory; the cache is invalidated when the file's mtime changes.
+ * A Map index (_trackerIndex) is attached to the returned object for O(1) lookups.
+ * @param cwd - Project working directory
+ * @returns Mapping object with provider, last_synced, milestones, phases, plans, and _trackerIndex
+ */
+function loadTrackerMapping(cwd) {
+    const mappingPath = path.join(cwd, '.planning', 'TRACKER.md');
+    // Check mtime for cache invalidation
+    let mtime = null;
+    try {
+        mtime = fs.statSync(mappingPath).mtimeMs;
+    }
+    catch {
+        /* file does not exist */
+    }
+    const cached = _trackerMappingCache.get(cwd);
+    if (cached && cached.mtime === mtime && mtime !== null) {
+        return cached.mapping;
+    }
+    const content = safeReadFile(mappingPath);
+    if (!content) {
+        const empty = {
+            provider: null,
+            last_synced: null,
+            milestones: {},
+            phases: {},
+            plans: {},
+            _trackerIndex: new Map(),
+        };
+        // Cache the empty result keyed on null mtime so repeated misses are cheap
+        _trackerMappingCache.set(cwd, { mtime: null, mapping: empty });
+        return empty;
+    }
+    const result = {
+        provider: null,
+        last_synced: null,
+        milestones: {},
+        phases: {},
+        plans: {},
+        _trackerIndex: new Map(),
+    };
+    const providerMatch = content.match(/^Provider:\s*(.+)$/m);
+    if (providerMatch)
+        result.provider = providerMatch[1].trim();
+    const syncMatch = content.match(/^Last Synced:\s*(.+)$/m);
+    if (syncMatch)
+        result.last_synced = syncMatch[1].trim();
+    // Parse milestone table (Epics) -- handles optional blank line between heading and table
+    const milestoneTableMatch = content.match(/## Milestone Issues\n\n?\|[^\n]+\n\|[^\n]+\n([\s\S]*?)(?=\n##|\n$|$)/);
+    if (milestoneTableMatch) {
+        const rows = milestoneTableMatch[1]
+            .trim()
+            .split('\n')
+            .filter((r) => r.startsWith('|'));
+        for (const row of rows) {
+            const cols = _splitTableRow(row);
+            if (cols.length >= 4) {
+                result.milestones[cols[0]] = {
+                    issueRef: cols[1],
+                    url: cols[2],
+                    status: cols[3],
+                };
+            }
+        }
+    }
+    // Parse phase table (Tasks) -- handles optional blank line between heading and table
+    const phaseTableMatch = content.match(/## Phase Issues\n\n?\|[^\n]+\n\|[^\n]+\n([\s\S]*?)(?=\n##|\n$|$)/);
+    if (phaseTableMatch) {
+        const rows = phaseTableMatch[1]
+            .trim()
+            .split('\n')
+            .filter((r) => r.startsWith('|'));
+        for (const row of rows) {
+            const cols = _splitTableRow(row);
+            if (cols.length >= 5) {
+                result.phases[cols[0]] = {
+                    issueRef: cols[1],
+                    url: cols[2],
+                    parentRef: cols[3],
+                    status: cols[4],
+                };
+            }
+        }
+    }
+    // Parse plan table (Sub-tasks) -- handles optional blank line between heading and table
+    const planTableMatch = content.match(/## Plan Issues\n\n?\|[^\n]+\n\|[^\n]+\n([\s\S]*?)(?=\n##|\n$|$)/);
+    if (planTableMatch) {
+        const rows = planTableMatch[1]
+            .trim()
+            .split('\n')
+            .filter((r) => r.startsWith('|'));
+        for (const row of rows) {
+            const cols = _splitTableRow(row);
+            if (cols.length >= 6) {
+                const key = `${cols[0]}-${cols[1]}`;
+                result.plans[key] = {
+                    issueRef: cols[2],
+                    url: cols[3],
+                    parentRef: cols[4],
+                    status: cols[5],
+                };
+            }
+        }
+    }
+    // Attach O(1) lookup index
+    result._trackerIndex = _buildTrackerIndex(result);
+    _trackerMappingCache.set(cwd, { mtime, mapping: result });
+    return result;
+}
+/**
+ * Save the tracker ID mapping to TRACKER.md with formatted markdown tables.
+ * @param cwd - Project working directory
+ * @param mapping - Mapping object with provider, milestones, phases, and plans entries
+ */
+function saveTrackerMapping(cwd, mapping) {
+    const mappingPath = path.join(cwd, '.planning', 'TRACKER.md');
+    const timestamp = new Date()
+        .toISOString()
+        .replace('T', ' ')
+        .replace(/\.\d+Z$/, ' UTC');
+    let content = `# Tracker Mapping\n\nProvider: ${mapping.provider || 'none'}\nLast Synced: ${timestamp}\n\n`;
+    content += `## Milestone Issues\n\n| Milestone | Issue Ref | URL | Status |\n|-----------|-----------|-----|--------|\n`;
+    for (const [milestone, info] of Object.entries(mapping.milestones || {})) {
+        content += `| ${milestone} | ${info.issueRef} | ${info.url} | ${info.status} |\n`;
+    }
+    content += `\n## Phase Issues\n\n| Phase | Issue Ref | URL | Parent Ref | Status |\n|-------|-----------|-----|------------|--------|\n`;
+    for (const [phase, info] of Object.entries(mapping.phases || {})) {
+        content += `| ${phase} | ${info.issueRef} | ${info.url} | ${info.parentRef || ''} | ${info.status} |\n`;
+    }
+    content += `\n## Plan Issues\n\n| Phase | Plan | Issue Ref | URL | Parent Ref | Status |\n|-------|------|-----------|-----|------------|--------|\n`;
+    for (const [key, info] of Object.entries(mapping.plans || {})) {
+        const [phase, plan] = key.split('-');
+        content += `| ${phase} | ${plan} | ${info.issueRef} | ${info.url} | ${info.parentRef} | ${info.status} |\n`;
+    }
+    const planningDir = path.join(cwd, '.planning');
+    if (!fs.existsSync(planningDir))
+        fs.mkdirSync(planningDir, { recursive: true });
+    fs.writeFileSync(mappingPath, content, 'utf-8');
+    // Invalidate cache so the next loadTrackerMapping call re-reads the updated file
+    _trackerMappingCache.delete(cwd);
+}
+// ─── GitHub Tracker ───────────────────────────────────────────────────────────
+/**
+ * Create a GitHub Issues tracker operations object with methods for issue CRUD.
+ * @param cwd - Project working directory
+ * @param config - Tracker config with github sub-object for labels, assignees, etc.
+ * @returns Tracker object with createPhaseIssue, createTaskIssue, updateIssueStatus, addComment, syncRoadmap, syncPhase methods
+ */
+function createGitHubTracker(cwd, config) {
+    const gh = config.github || {};
+    const mainConfig = loadConfig(cwd);
+    // NOTE: execFileSync is already the safe alternative (no shell injection).
+    // This is used for gh CLI calls which require direct process execution.
+    function ghExec(args) {
+        try {
+            return execFileSync('gh', args, {
+                cwd,
+                encoding: 'utf-8',
+                timeout: mainConfig.timeouts.tracker_gh_ms,
+                stdio: 'pipe',
+            }).trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    function ghAvailable() {
+        return ghExec(['--version']) !== null;
+    }
+    return {
+        provider: 'github',
+        createPhaseIssue(_phaseNum, title, body, labels) {
+            if (!ghAvailable())
+                return { issueRef: null, url: null };
+            const args = [
+                'issue',
+                'create',
+                '--title',
+                title,
+                '--body',
+                body || '',
+                '--label',
+                'epic',
+            ];
+            for (const l of labels || gh.default_labels || []) {
+                args.push('--label', l);
+            }
+            if (gh.default_assignee) {
+                args.push('--assignee', gh.default_assignee);
+            }
+            const url = ghExec(args);
+            if (!url)
+                return { issueRef: null, url: null };
+            const issueRef = url.match(/\/(\d+)$/)?.[1] || url;
+            return { issueRef: `#${issueRef}`, url };
+        },
+        createTaskIssue(phaseNum, planNum, title, parentRef) {
+            if (!ghAvailable())
+                return { issueRef: null, url: null };
+            const bodyText = `Parent: ${parentRef}\nPhase: ${phaseNum}\nPlan: ${planNum}`;
+            const url = ghExec([
+                'issue',
+                'create',
+                '--title',
+                title,
+                '--body',
+                bodyText,
+                '--label',
+                'task',
+            ]);
+            if (!url)
+                return { issueRef: null, url: null };
+            const issueRef = url.match(/\/(\d+)$/)?.[1] || url;
+            // Try to link as sub-issue
+            if (parentRef) {
+                const parentNum = parentRef.replace('#', '');
+                ghExec(['sub-issue', 'add', parentNum, '--child', issueRef]);
+            }
+            return { issueRef: `#${issueRef}`, url };
+        },
+        updateIssueStatus(issueRef, status) {
+            if (!ghAvailable())
+                return { success: false };
+            const num = String(issueRef).replace('#', '');
+            const statusLabels = {
+                pending: 'status:todo',
+                in_progress: 'status:in-progress',
+                complete: 'status:done',
+            };
+            const label = statusLabels[status];
+            if (label) {
+                // Remove other status labels, add new one
+                for (const sl of Object.values(statusLabels)) {
+                    ghExec(['issue', 'edit', num, '--remove-label', sl]);
+                }
+                ghExec(['issue', 'edit', num, '--add-label', label]);
+            }
+            if (status === 'complete') {
+                ghExec(['issue', 'close', num]);
+            }
+            return { success: true };
+        },
+        addComment(issueRef, markdownBody) {
+            if (!ghAvailable())
+                return { success: false };
+            const num = String(issueRef).replace('#', '');
+            ghExec(['issue', 'comment', num, '--body', markdownBody]);
+            return { success: true };
+        },
+        syncRoadmap(roadmapData) {
+            const mapping = loadTrackerMapping(cwd);
+            mapping.provider = 'github';
+            const stats = {
+                created: 0,
+                updated: 0,
+                skipped: 0,
+                errors: 0,
+            };
+            for (const phase of roadmapData.phases || []) {
+                const key = String(phase.number);
+                if (mapping.phases[key]) {
+                    stats.skipped = (stats.skipped || 0) + 1;
+                    continue;
+                }
+                const result = this.createPhaseIssue(phase.number, `Phase ${phase.number}: ${phase.name}`, phase.goal || '', phase.labels || []);
+                if (result.issueRef) {
+                    mapping.phases[key] = {
+                        issueRef: result.issueRef,
+                        url: result.url || '',
+                        parentRef: '',
+                        status: 'pending',
+                    };
+                    stats.created++;
+                }
+                else {
+                    stats.errors++;
+                }
+            }
+            saveTrackerMapping(cwd, mapping);
+            return stats;
+        },
+        syncPhase(phaseNum, phaseData) {
+            const mapping = loadTrackerMapping(cwd);
+            mapping.provider = 'github';
+            const stats = { created: 0, updated: 0, errors: 0 };
+            const parentRef = mapping.phases[String(phaseNum)]?.issueRef || null;
+            for (const plan of phaseData.plans || []) {
+                const key = `${phaseNum}-${plan.number}`;
+                if (mapping.plans[key]) {
+                    stats.updated++;
+                    continue;
+                }
+                const result = this.createTaskIssue(phaseNum, plan.number, `Plan ${phaseNum}-${plan.number}: ${plan.objective || ''}`, parentRef);
+                if (result.issueRef) {
+                    mapping.plans[key] = {
+                        issueRef: result.issueRef,
+                        url: result.url || '',
+                        parentRef: parentRef || '',
+                        status: 'pending',
+                    };
+                    stats.created++;
+                }
+                else {
+                    stats.errors++;
+                }
+            }
+            saveTrackerMapping(cwd, mapping);
+            return stats;
+        },
+    };
+}
+// Note: Jira integration is now handled via mcp-atlassian MCP server.
+// grd-tools.js provides prepare/record commands; Claude agents call MCP tools directly.
+// See references/mcp-tracker-protocol.md for the full protocol.
+/**
+ * Factory function: create a tracker instance based on the configured provider.
+ * @param cwd - Project working directory
+ * @returns Tracker instance for GitHub, or null for mcp-atlassian/none
+ */
+function createTracker(cwd) {
+    const config = loadTrackerConfig(cwd);
+    if (config.provider === 'github')
+        return createGitHubTracker(cwd, config);
+    // mcp-atlassian provider is handled by Claude agents via MCP tools, not by grd-tools.js
+    return null;
+}
+/**
+ * Provider factory map -- maps provider names to factory functions.
+ * Each factory takes (cwd, config) and returns a tracker instance.
+ */
+const PROVIDERS = {
+    github: (cwd, config) => createGitHubTracker(cwd, config),
+};
+// ─── Tracker Subcommand Handlers ──────────────────────────────────────────────
+function handleGetConfig(cwd, _args, raw) {
+    const config = loadTrackerConfig(cwd);
+    const mainConfig = loadConfig(cwd);
+    let authStatus = 'not_configured';
+    if (config.provider === 'github') {
+        try {
+            execFileSync('gh', ['auth', 'status'], {
+                cwd,
+                encoding: 'utf-8',
+                timeout: mainConfig.timeouts.tracker_auth_ms,
+                stdio: 'pipe',
+            });
+            authStatus = 'authenticated';
+        }
+        catch {
+            authStatus = 'not_authenticated';
+        }
+    }
+    else if (config.provider === 'mcp-atlassian') {
+        authStatus = 'mcp_server';
+    }
+    output({ ...config, auth_status: authStatus }, raw);
+}
+function handleSyncRoadmap(cwd, args, raw) {
+    const isDryRun = args.includes('--dry-run');
+    const config = loadTrackerConfig(cwd);
+    if (config.provider === 'mcp-atlassian') {
+        output({
+            error: 'Use "tracker prepare-roadmap-sync" for mcp-atlassian provider. Agent executes MCP calls.',
+            created: 0,
+            updated: 0,
+            skipped: 0,
+            errors: 0,
+        }, raw);
+        return;
+    }
+    const tracker = createTracker(cwd);
+    if (!tracker) {
+        output({
+            error: 'No tracker configured',
+            created: 0,
+            updated: 0,
+            skipped: 0,
+            errors: 0,
+        }, raw);
+        return;
+    }
+    const roadmapContent = safeReadMarkdown(path.join(cwd, '.planning', 'ROADMAP.md'));
+    if (!roadmapContent) {
+        output({
+            error: 'No ROADMAP.md found',
+            created: 0,
+            updated: 0,
+            skipped: 0,
+            errors: 0,
+        }, raw);
+        return;
+    }
+    const activeContent = stripShippedSections(roadmapContent);
+    const phases = [];
+    const phaseRegex = /^##\s+Phase\s+(\d+(?:\.\d+)?)\s*[:\-\u2014]\s*(.+)$/gm;
+    let match;
+    while ((match = phaseRegex.exec(activeContent)) !== null) {
+        const number = match[1];
+        const name = match[2].trim();
+        const afterPhase = activeContent.slice(match.index + match[0].length, match.index + match[0].length + 500);
+        const goalMatch = afterPhase.match(/(?:\*\*Goal:\*\*|Goal:)\s*(.+)/);
+        phases.push({
+            number,
+            name,
+            goal: goalMatch ? goalMatch[1].trim() : '',
+        });
+    }
+    if (isDryRun) {
+        // Dry-run mode: report what would be created/skipped without executing
+        const mapping = loadTrackerMapping(cwd);
+        const wouldCreate = [];
+        const wouldSkip = [];
+        for (const p of phases) {
+            if (mapping.phases && mapping.phases[p.number]) {
+                wouldSkip.push({
+                    number: p.number,
+                    name: p.name,
+                    reason: 'already_mapped',
+                });
+            }
+            else {
+                wouldCreate.push({ number: p.number, name: p.name });
+            }
+        }
+        output({
+            dry_run: true,
+            would_create: wouldCreate,
+            would_skip: wouldSkip,
+            created: 0,
+        }, raw);
+        return;
+    }
+    const stats = tracker.syncRoadmap({ phases });
+    output(stats, raw, `Roadmap synced: created ${stats.created}, updated ${stats.updated}, errors ${stats.errors}`);
+}
+function handleSyncPhase(cwd, args, raw) {
+    const phaseNum = args[0];
+    if (!phaseNum) {
+        error('Usage: tracker sync-phase <phase-number>. Example: tracker sync-phase 3. Make sure you are in a GRD project directory and have a tracker configured in .planning/config.json. Run: tracker sync-phase <N> where N is the phase number.');
+        return; // unreachable after error() but helps TS narrowing
+    }
+    const config = loadTrackerConfig(cwd);
+    if (config.provider === 'mcp-atlassian') {
+        output({
+            error: 'Use "tracker prepare-phase-sync" for mcp-atlassian provider. Agent executes MCP calls.',
+            created: 0,
+            updated: 0,
+            errors: 0,
+        }, raw);
+        return;
+    }
+    const tracker = createTracker(cwd);
+    if (!tracker) {
+        output({ error: 'No tracker configured', created: 0, updated: 0, errors: 0 }, raw);
+        return;
+    }
+    const planningDir = getPhasesDirPath(cwd);
+    let phaseDir = null;
+    try {
+        const dirs = fs.readdirSync(planningDir);
+        phaseDir =
+            dirs.find((d) => d.startsWith(`${phaseNum}-`) || d === String(phaseNum)) || null;
+    }
+    catch {
+        /* no phases dir */
+    }
+    const plans = [];
+    if (phaseDir) {
+        const fullPhaseDir = path.join(planningDir, phaseDir);
+        try {
+            const files = fs
+                .readdirSync(fullPhaseDir)
+                .filter((f) => f.match(/-PLAN\.md$/));
+            for (const f of files) {
+                const planMatch = f.match(/(\d+)-(\d+)-PLAN\.md$/);
+                if (planMatch) {
+                    const planContent = safeReadFile(path.join(fullPhaseDir, f));
+                    const objMatch = planContent?.match(/(?:objective|title):\s*["']?(.+?)["']?\s*$/m);
+                    plans.push({
+                        number: planMatch[2],
+                        objective: objMatch ? objMatch[1] : f,
+                    });
+                }
+            }
+        }
+        catch {
+            /* no plan files */
+        }
+    }
+    const stats = tracker.syncPhase(phaseNum, { plans });
+    output(stats, raw, `Phase ${phaseNum} synced: created ${stats.created}, updated ${stats.updated}, errors ${stats.errors}`);
+}
+function handleUpdateStatus(cwd, args, raw) {
+    const phaseNum = args[0];
+    const status = args[1];
+    if (!phaseNum || !status) {
+        error('Usage: tracker update-status <phase-number> <status>. Provide phase number and one of the valid status values (in-progress, completed, blocked). Example: tracker update-status 3 completed. To see current phase numbers: grd-tools.js roadmap get-phase <N>');
+        return; // unreachable after error() but helps TS narrowing
+    }
+    const config = loadTrackerConfig(cwd);
+    if (config.provider === 'mcp-atlassian') {
+        const mapping = loadTrackerMapping(cwd);
+        const phaseInfo = mapping.phases[String(phaseNum)];
+        if (!phaseInfo) {
+            output({ success: false, error: 'Phase not synced to tracker' }, raw);
+            return;
+        }
+        phaseInfo.status = status;
+        saveTrackerMapping(cwd, mapping);
+        output({ success: true, issue_key: phaseInfo.issueRef, status }, raw);
+        return;
+    }
+    const tracker = createTracker(cwd);
+    if (!tracker) {
+        output({ success: false, error: 'No tracker configured' }, raw);
+        return;
+    }
+    const mapping = loadTrackerMapping(cwd);
+    const phaseInfo = mapping.phases[String(phaseNum)];
+    if (!phaseInfo) {
+        output({ success: false, error: 'Phase not synced to tracker' }, raw);
+        return;
+    }
+    const result = tracker.updateIssueStatus(phaseInfo.issueRef, status);
+    if (result.success) {
+        phaseInfo.status = status;
+        saveTrackerMapping(cwd, mapping);
+    }
+    output(result, raw, `Status ${result.success ? `updated to '${status}'` : 'update failed'}`);
+}
+function handleAddComment(cwd, args, raw) {
+    const phaseNum = args[0];
+    const filePath = args[1];
+    if (!phaseNum || !filePath) {
+        error('Usage: tracker add-comment <phase-number> <file-path>');
+        return; // unreachable after error() but helps TS narrowing
+    }
+    const config = loadTrackerConfig(cwd);
+    if (config.provider === 'mcp-atlassian') {
+        const mapping = loadTrackerMapping(cwd);
+        const phaseInfo = mapping.phases[String(phaseNum)];
+        if (!phaseInfo) {
+            output({ success: false, error: 'Phase not synced to tracker' }, raw);
+            return;
+        }
+        const content = safeReadFile(path.join(cwd, filePath));
+        if (!content) {
+            output({ success: false, error: 'File not found: ' + filePath }, raw);
+            return;
+        }
+        output({
+            provider: 'mcp-atlassian',
+            issue_key: phaseInfo.issueRef,
+            file_path: filePath,
+            content_length: content.length,
+            content,
+        }, raw);
+        return;
+    }
+    const tracker = createTracker(cwd);
+    if (!tracker) {
+        output({ success: false, error: 'No tracker configured' }, raw);
+        return;
+    }
+    const mapping = loadTrackerMapping(cwd);
+    const phaseInfo = mapping.phases[String(phaseNum)];
+    if (!phaseInfo) {
+        output({ success: false, error: 'Phase not synced to tracker' }, raw);
+        return;
+    }
+    const content = safeReadFile(path.join(cwd, filePath));
+    if (!content) {
+        output({ success: false, error: 'File not found: ' + filePath }, raw);
+        return;
+    }
+    const result = tracker.addComment(phaseInfo.issueRef, content);
+    output(result, raw, `Comment ${result.success ? 'added successfully' : 'failed'}`);
+}
+/**
+ * Parse all milestones from active roadmap content.
+ * @param content - Roadmap content with shipped sections already stripped
+ * @returns Ordered milestone list
+ */
+function _parseAllMilestones(content) {
+    const milestoneRegex = /^##\s*(.*v(\d+\.\d+)[^(\n]*)/gim;
+    let mMatch;
+    const milestonePositions = [];
+    while ((mMatch = milestoneRegex.exec(content)) !== null) {
+        milestonePositions.push({
+            heading: mMatch[1].trim(),
+            version: 'v' + mMatch[2],
+            index: mMatch.index,
+        });
+    }
+    return milestonePositions;
+}
+/**
+ * Parse all phases from active roadmap content, associating each with its milestone.
+ * @param content - Roadmap content with shipped sections already stripped
+ * @param milestonePositions - Parsed milestone list
+ * @returns Parsed phase positions
+ */
+function _parseAllPhases(content, milestonePositions) {
+    const phaseRegex = /^##\s+Phase\s+(\d+(?:\.\d+)?)\s*[:\-\u2014]\s*(.+)$/gm;
+    let match;
+    const allPhases = [];
+    while ((match = phaseRegex.exec(content)) !== null) {
+        const number = match[1];
+        const name = match[2].trim();
+        const afterPhase = content.slice(match.index + match[0].length, match.index + match[0].length + 500);
+        const goalMatch = afterPhase.match(/(?:\*\*Goal:\*\*|Goal:)\s*(.+)/);
+        const goal = goalMatch ? goalMatch[1].trim() : '';
+        let milestone = milestonePositions.length > 0 ? milestonePositions[0].version : null;
+        for (const ms of milestonePositions) {
+            if (match.index > ms.index)
+                milestone = ms.version;
+        }
+        allPhases.push({ number, name, goal, milestone, index: match.index });
+    }
+    return allPhases;
+}
+/**
+ * Build the operations array for a roadmap sync, covering milestones and phases.
+ * @param milestones - Parsed milestones
+ * @param phases - Parsed phases
+ * @param ctx - Loaded mapping and computed schedule
+ * @returns Operations array (create/skip entries)
+ */
+function _buildMilestoneOperations(milestones, phases, ctx) {
+    const { mapping, schedule } = ctx;
+    const operations = [];
+    for (const ms of milestones) {
+        if (mapping.milestones[ms.version]) {
+            operations.push({
+                action: 'skip',
+                type: 'milestone',
+                milestone: ms.version,
+                issue_key: mapping.milestones[ms.version].issueRef,
+                reason: 'already_synced',
+            });
+        }
+        else {
+            const msSchedule = getScheduleForMilestone(schedule, ms.version);
+            const op = {
+                action: 'create',
+                type: 'milestone',
+                milestone: ms.version,
+                summary: ms.heading,
+                description: `Milestone ${ms.version}`,
+            };
+            if (msSchedule && msSchedule.start)
+                op.start_date = msSchedule.start;
+            if (msSchedule && msSchedule.target)
+                op.due_date = msSchedule.target;
+            operations.push(op);
+        }
+    }
+    for (const phase of phases) {
+        const milestoneKey = phase.milestone && mapping.milestones[phase.milestone]
+            ? mapping.milestones[phase.milestone].issueRef
+            : null;
+        if (mapping.phases[phase.number]) {
+            operations.push({
+                action: 'skip',
+                type: 'phase',
+                phase: phase.number,
+                issue_key: mapping.phases[phase.number].issueRef,
+                reason: 'already_synced',
+            });
+        }
+        else {
+            const phaseSchedule = getScheduleForPhase(schedule, phase.number);
+            const op = {
+                action: 'create',
+                type: 'phase',
+                phase: phase.number,
+                milestone: phase.milestone || undefined,
+                parent_key: milestoneKey,
+                summary: `Phase ${phase.number}: ${phase.name}`,
+                description: phase.goal,
+            };
+            if (phaseSchedule && phaseSchedule.start_date) {
+                op.start_date = phaseSchedule.start_date;
+                op.due_date = phaseSchedule.due_date || undefined;
+                op.duration_days = phaseSchedule.duration_days;
+            }
+            operations.push(op);
+        }
+    }
+    return operations;
+}
+function handlePrepareRoadmapSync(cwd, _args, raw) {
+    const config = loadTrackerConfig(cwd);
+    if (config.provider !== 'mcp-atlassian') {
+        output({
+            error: 'prepare-roadmap-sync is only for mcp-atlassian provider. Use "tracker sync-roadmap" for GitHub.',
+        }, raw);
+        return;
+    }
+    const mcpConfig = config.mcp_atlassian || {};
+    const roadmapContent = safeReadMarkdown(path.join(cwd, '.planning', 'ROADMAP.md'));
+    if (!roadmapContent) {
+        output({ error: 'No ROADMAP.md found', operations: [] }, raw);
+        return;
+    }
+    const activeContent = stripShippedSections(roadmapContent);
+    const mapping = loadTrackerMapping(cwd);
+    const schedule = computeSchedule(cwd);
+    const milestonePositions = _parseAllMilestones(activeContent);
+    const allPhases = _parseAllPhases(activeContent, milestonePositions);
+    const operations = _buildMilestoneOperations(milestonePositions, allPhases, {
+        mapping,
+        schedule,
+    });
+    output({
+        provider: 'mcp-atlassian',
+        project_key: mcpConfig.project_key || '',
+        start_date_field: mcpConfig.start_date_field || 'customfield_10015',
+        milestone_issue_type: mcpConfig.milestone_issue_type || 'Epic',
+        phase_issue_type: mcpConfig.phase_issue_type || 'Task',
+        operations,
+    }, raw);
+}
+function handlePreparePhaseSync(cwd, args, raw) {
+    const phaseNum = args[0];
+    if (!phaseNum) {
+        error('Usage: tracker prepare-phase-sync <phase-number>. Provide the phase number to sync, e.g.: tracker prepare-phase-sync 3. To see available phase numbers: grd-tools.js roadmap analyze');
+        return; // unreachable after error() but helps TS narrowing
+    }
+    const config = loadTrackerConfig(cwd);
+    if (config.provider !== 'mcp-atlassian') {
+        output({
+            error: 'prepare-phase-sync is only for mcp-atlassian provider. Use "tracker sync-phase" for GitHub.',
+        }, raw);
+        return;
+    }
+    const mcpConfig = config.mcp_atlassian || {};
+    const mapping = loadTrackerMapping(cwd);
+    const parentInfo = mapping.phases[String(phaseNum)];
+    const parentKey = parentInfo ? parentInfo.issueRef : null;
+    const planningDir = getPhasesDirPath(cwd);
+    let phaseDir = null;
+    try {
+        const dirs = fs.readdirSync(planningDir);
+        phaseDir =
+            dirs.find((d) => d.startsWith(`${phaseNum}-`) || d === String(phaseNum)) || null;
+    }
+    catch {
+        /* no phases dir */
+    }
+    const operations = [];
+    if (phaseDir) {
+        const fullPhaseDir = path.join(planningDir, phaseDir);
+        try {
+            const files = fs
+                .readdirSync(fullPhaseDir)
+                .filter((f) => f.match(/-PLAN\.md$/));
+            for (const f of files) {
+                const planMatch = f.match(/(\d+)-(\d+)-PLAN\.md$/);
+                if (planMatch) {
+                    const planNum = planMatch[2];
+                    const key = `${phaseNum}-${planNum}`;
+                    if (mapping.plans[key]) {
+                        operations.push({
+                            action: 'skip',
+                            type: 'plan',
+                            phase: phaseNum,
+                            plan: planNum,
+                            issue_key: mapping.plans[key].issueRef,
+                            reason: 'already_synced',
+                        });
+                    }
+                    else {
+                        const planContent = safeReadFile(path.join(fullPhaseDir, f));
+                        const objMatch = planContent?.match(/(?:objective|title):\s*["']?(.+?)["']?\s*$/m);
+                        operations.push({
+                            action: 'create',
+                            type: 'plan',
+                            phase: phaseNum,
+                            plan: planNum,
+                            summary: `Plan ${phaseNum}-${planNum}: ${objMatch ? objMatch[1] : f}`,
+                            description: '',
+                        });
+                    }
+                }
+            }
+        }
+        catch {
+            /* no plan files */
+        }
+    }
+    output({
+        provider: 'mcp-atlassian',
+        project_key: mcpConfig.project_key || '',
+        plan_issue_type: mcpConfig.plan_issue_type || 'Sub-task',
+        parent_key: parentKey,
+        operations,
+    }, raw);
+}
+function handleRecordMapping(cwd, args, raw) {
+    const typeIdx = args.indexOf('--type');
+    const milestoneIdx = args.indexOf('--milestone');
+    const phaseIdx = args.indexOf('--phase');
+    const planIdx = args.indexOf('--plan');
+    const keyIdx = args.indexOf('--key');
+    const urlIdx = args.indexOf('--url');
+    const parentIdx = args.indexOf('--parent');
+    const type = typeIdx !== -1 ? args[typeIdx + 1] : null;
+    const milestoneVer = milestoneIdx !== -1 ? args[milestoneIdx + 1] : null;
+    const phaseNum = phaseIdx !== -1 ? args[phaseIdx + 1] : null;
+    const planNum = planIdx !== -1 ? args[planIdx + 1] : null;
+    const issueKey = keyIdx !== -1 ? args[keyIdx + 1] : null;
+    const issueUrl = urlIdx !== -1 ? args[urlIdx + 1] : null;
+    const parentKey = parentIdx !== -1 ? args[parentIdx + 1] : '';
+    if (!type || !issueKey) {
+        error('Usage: tracker record-mapping --type milestone|phase|plan [--milestone V] [--phase N] [--plan M] --key PROJ-1 --url URL [--parent PROJ-0]. Example: tracker record-mapping --type phase --phase 2 --key PROJ-5 --url https://.... Ensure --type and --key flags are provided at minimum.');
+        return; // unreachable after error() but helps TS narrowing
+    }
+    const mapping = loadTrackerMapping(cwd);
+    mapping.provider = 'mcp-atlassian';
+    if (type === 'milestone') {
+        if (!milestoneVer) {
+            error('--milestone is required for type "milestone"');
+            return; // unreachable after error() but helps TS narrowing
+        }
+        mapping.milestones[milestoneVer] = {
+            issueRef: issueKey,
+            url: issueUrl || '',
+            status: 'pending',
+        };
+    }
+    else if (type === 'phase') {
+        if (!phaseNum) {
+            error('--phase is required for type "phase"');
+            return; // unreachable after error() but helps TS narrowing
+        }
+        mapping.phases[phaseNum] = {
+            issueRef: issueKey,
+            url: issueUrl || '',
+            parentRef: parentKey,
+            status: 'pending',
+        };
+    }
+    else if (type === 'plan') {
+        if (!phaseNum) {
+            error('--phase is required for type "plan"');
+            return; // unreachable after error() but helps TS narrowing
+        }
+        if (!planNum) {
+            error('--plan is required for type "plan"');
+            return; // unreachable after error() but helps TS narrowing
+        }
+        const key = `${phaseNum}-${planNum}`;
+        mapping.plans[key] = {
+            issueRef: issueKey,
+            url: issueUrl || '',
+            parentRef: parentKey,
+            status: 'pending',
+        };
+    }
+    else {
+        error(`Unknown mapping type: ${type}. Use "milestone", "phase", or "plan".`);
+        return; // unreachable after error() but helps TS narrowing
+    }
+    saveTrackerMapping(cwd, mapping);
+    output({
+        success: true,
+        type,
+        milestone: milestoneVer || null,
+        phase: phaseNum || null,
+        plan: planNum || null,
+        key: issueKey,
+    }, raw);
+}
+function handleRecordStatus(cwd, args, raw) {
+    const phaseIdx = args.indexOf('--phase');
+    const statusIdx = args.indexOf('--status');
+    const phaseNum = phaseIdx !== -1 ? args[phaseIdx + 1] : null;
+    const status = statusIdx !== -1 ? args[statusIdx + 1] : null;
+    if (!phaseNum || !status) {
+        error('Usage: tracker record-status --phase N --status pending|in_progress|complete. Example: tracker record-status --phase 2 --status in_progress. Ensure both --phase and --status flags are provided.');
+        return; // unreachable after error() but helps TS narrowing
+    }
+    const mapping = loadTrackerMapping(cwd);
+    const phaseInfo = mapping.phases[String(phaseNum)];
+    if (!phaseInfo) {
+        output({ success: false, error: 'Phase not synced to tracker' }, raw);
+        return;
+    }
+    phaseInfo.status = status;
+    saveTrackerMapping(cwd, mapping);
+    output({ success: true, phase: phaseNum, status, issue_key: phaseInfo.issueRef }, raw);
+}
+function handleSyncStatus(cwd, _args, raw) {
+    const config = loadTrackerConfig(cwd);
+    const mapping = loadTrackerMapping(cwd);
+    const roadmapContent = safeReadMarkdown(path.join(cwd, '.planning', 'ROADMAP.md'));
+    const activeContent = stripShippedSections(roadmapContent || '');
+    const phaseRegex = /^##\s+Phase\s+(\d+(?:\.\d+)?)/gm;
+    const roadmapPhases = [];
+    let m;
+    while ((m = phaseRegex.exec(activeContent)) !== null) {
+        roadmapPhases.push(m[1]);
+    }
+    const synced = roadmapPhases.filter((p) => mapping.phases[p]);
+    const unsynced = roadmapPhases.filter((p) => !mapping.phases[p]);
+    output({
+        provider: config.provider,
+        last_synced: mapping.last_synced,
+        total_milestones: Object.keys(mapping.milestones).length,
+        total_phases: roadmapPhases.length,
+        synced_phases: synced.length,
+        unsynced_phases: unsynced.length,
+        synced: synced,
+        unsynced: unsynced,
+        plan_count: Object.keys(mapping.plans).length,
+    }, raw);
+}
+function handleSchedule(cwd, _args, raw) {
+    const schedule = computeSchedule(cwd);
+    output(schedule, raw, `${schedule.phases.length} phases scheduled across ${schedule.milestones.length} milestone(s)`);
+}
+function handlePrepareReschedule(cwd, _args, raw) {
+    const config = loadTrackerConfig(cwd);
+    if (config.provider !== 'mcp-atlassian') {
+        output({ error: 'prepare-reschedule is only for mcp-atlassian provider.' }, raw);
+        return;
+    }
+    const mcpConfig = config.mcp_atlassian || {};
+    const mapping = loadTrackerMapping(cwd);
+    const schedule = computeSchedule(cwd);
+    const operations = [];
+    for (const ms of schedule.milestones) {
+        const mapped = mapping.milestones[ms.version];
+        if (mapped && (ms.start || ms.target)) {
+            const op = {
+                action: 'update',
+                type: 'milestone',
+                milestone: ms.version,
+                issue_key: mapped.issueRef,
+            };
+            if (ms.start)
+                op.start_date = ms.start;
+            if (ms.target)
+                op.due_date = ms.target;
+            operations.push(op);
+        }
+    }
+    for (const phase of schedule.phases) {
+        const mapped = mapping.phases[phase.number];
+        if (mapped && phase.start_date) {
+            operations.push({
+                action: 'update',
+                type: 'phase',
+                phase: phase.number,
+                issue_key: mapped.issueRef,
+                start_date: phase.start_date,
+                due_date: phase.due_date || undefined,
+            });
+        }
+    }
+    output({
+        provider: 'mcp-atlassian',
+        start_date_field: mcpConfig.start_date_field || 'customfield_10015',
+        operations,
+    }, raw);
+}
+const trackerHandlers = {
+    'get-config': handleGetConfig,
+    'sync-roadmap': handleSyncRoadmap,
+    'sync-phase': handleSyncPhase,
+    'update-status': handleUpdateStatus,
+    'add-comment': handleAddComment,
+    'sync-status': handleSyncStatus,
+    'prepare-roadmap-sync': handlePrepareRoadmapSync,
+    'prepare-phase-sync': handlePreparePhaseSync,
+    'record-mapping': handleRecordMapping,
+    'record-status': handleRecordStatus,
+    schedule: handleSchedule,
+    'prepare-reschedule': handlePrepareReschedule,
+};
+/**
+ * CLI command: Dispatch tracker subcommand (get-config, sync-roadmap, sync-phase, update-status, etc.).
+ * @param cwd - Project working directory
+ * @param subcommand - Tracker subcommand name
+ * @param args - Additional arguments for the subcommand
+ * @param raw - Output raw text instead of JSON
+ */
+function cmdTracker(cwd, subcommand, args, raw) {
+    const handler = trackerHandlers[subcommand];
+    if (!handler) {
+        error(`Unknown tracker subcommand: '${subcommand}'. Available: ${Object.keys(trackerHandlers).join(', ')}`);
+        return; // unreachable after error() but helps TS narrowing
+    }
+    handler(cwd, args, raw);
+}
+module.exports = {
+    loadTrackerConfig,
+    loadTrackerMapping,
+    saveTrackerMapping,
+    createGitHubTracker,
+    PROVIDERS,
+    createTracker,
+    cmdTracker,
+};
+//# sourceMappingURL=tracker.js.map