@mcoda/core 0.1.4

package/dist/services/backlog/BacklogService.d.ts

@@ -0,0 +1,98 @@
+import { WorkspaceResolution } from "../../workspace/WorkspaceManager.js";
+export interface BacklogTotals {
+    implementation: {
+        tasks: number;
+        story_points: number;
+    };
+    review: {
+        tasks: number;
+        story_points: number;
+    };
+    qa: {
+        tasks: number;
+        story_points: number;
+    };
+    done: {
+        tasks: number;
+        story_points: number;
+    };
+}
+export interface EpicBacklogSummary {
+    epic_id: string;
+    epic_key: string;
+    title: string;
+    priority: number | null;
+    description?: string;
+    totals: BacklogTotals;
+    stories: StoryBacklogSummary[];
+}
+export interface StoryBacklogSummary {
+    user_story_id: string;
+    user_story_key: string;
+    epic_key: string;
+    title: string;
+    description?: string;
+    priority: number | null;
+    status?: string;
+    totals: BacklogTotals;
+}
+export interface TaskBacklogRow {
+    task_id: string;
+    task_key: string;
+    epic_key: string;
+    user_story_key: string;
+    title: string;
+    description: string;
+    status: string;
+    story_points: number | null;
+    priority: number | null;
+    assignee: string | null;
+    dependency_keys: string[];
+}
+export interface BacklogSummary {
+    scope: {
+        project_id: string | null;
+        project_key: string | null;
+        epic_key?: string;
+        user_story_key?: string;
+        assignee?: string;
+    };
+    totals: BacklogTotals;
+    epics: EpicBacklogSummary[];
+    tasks: TaskBacklogRow[];
+}
+export interface BacklogQueryOptions {
+    projectKey?: string;
+    epicKey?: string;
+    storyKey?: string;
+    assignee?: string;
+    statuses?: string[];
+    orderByDependencies?: boolean;
+    verbose?: boolean;
+}
+export interface BacklogResult {
+    summary: BacklogSummary;
+    warnings: string[];
+}
+export declare class BacklogService {
+    private workspace;
+    private db;
+    private connection;
+    private warnings;
+    private epicPriority;
+    private storyPriority;
+    private constructor();
+    static create(workspace: WorkspaceResolution): Promise<BacklogService>;
+    close(): Promise<void>;
+    getBacklog(options?: BacklogQueryOptions): Promise<BacklogResult>;
+    private getProject;
+    private getEpic;
+    private getStory;
+    private fetchTasks;
+    private fetchDependencies;
+    private defaultOrder;
+    private orderTasks;
+    private topologicalSort;
+    private sortEpics;
+}
+//# sourceMappingURL=BacklogService.d.ts.map

package/dist/services/backlog/BacklogService.d.ts.map

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

package/dist/services/backlog/BacklogService.js

@@ -0,0 +1,453 @@
+import fs from "node:fs/promises";
+import { Connection } from "@mcoda/db";
+import { PathHelper } from "@mcoda/shared";
+import { TaskOrderingService } from "./TaskOrderingService.js";
+const IMPLEMENTATION_STATUSES = new Set(["not_started", "in_progress", "blocked"]);
+const REVIEW_STATUSES = new Set(["ready_to_review"]);
+const QA_STATUSES = new Set(["ready_to_qa"]);
+const DONE_STATUSES = new Set(["completed", "cancelled"]);
+const emptyTotals = () => ({
+    implementation: { tasks: 0, story_points: 0 },
+    review: { tasks: 0, story_points: 0 },
+    qa: { tasks: 0, story_points: 0 },
+    done: { tasks: 0, story_points: 0 },
+});
+const bucketForStatus = (status) => {
+    const normalized = status?.toLowerCase() ?? "";
+    if (IMPLEMENTATION_STATUSES.has(normalized))
+        return "implementation";
+    if (REVIEW_STATUSES.has(normalized))
+        return "review";
+    if (QA_STATUSES.has(normalized))
+        return "qa";
+    if (DONE_STATUSES.has(normalized))
+        return "done";
+    return "implementation";
+};
+const addToTotals = (totals, lane, storyPoints) => {
+    totals[lane].tasks += 1;
+    if (typeof storyPoints === "number" && Number.isFinite(storyPoints)) {
+        totals[lane].story_points += storyPoints;
+    }
+};
+const truncate = (value, max = 100) => {
+    if (!value)
+        return "";
+    if (value.length <= max)
+        return value;
+    return `${value.slice(0, max - 3)}...`;
+};
+const hasTables = async (db, required) => {
+    const placeholders = required.map(() => "?").join(", ");
+    const rows = await db.all(`SELECT name FROM sqlite_master WHERE type = 'table' AND name IN (${placeholders})`, required);
+    return rows.length === required.length;
+};
+const deriveStoryStatus = (statuses) => {
+    const order = ["completed", "cancelled", "ready_to_qa", "ready_to_review", "in_progress", "blocked", "not_started"];
+    for (const status of order) {
+        if (statuses.has(status))
+            return status;
+    }
+    return undefined;
+};
+export class BacklogService {
+    constructor(workspace, db, connection) {
+        this.workspace = workspace;
+        this.db = db;
+        this.connection = connection;
+        this.warnings = [];
+        this.epicPriority = new Map();
+        this.storyPriority = new Map();
+    }
+    static async create(workspace) {
+        const dbPath = PathHelper.getWorkspaceDbPath(workspace.workspaceRoot);
+        try {
+            await fs.access(dbPath);
+        }
+        catch {
+            throw new Error(`No workspace DB found at ${dbPath}. Run mcoda init or create-tasks first.`);
+        }
+        const connection = await Connection.open(dbPath);
+        const ok = await hasTables(connection.db, ["projects", "epics", "user_stories", "tasks"]);
+        if (!ok) {
+            await connection.close();
+            throw new Error(`Workspace DB at ${dbPath} is missing required tables. Re-run create-tasks to seed it.`);
+        }
+        return new BacklogService(workspace, connection.db, connection);
+    }
+    async close() {
+        await this.connection.close();
+    }
+    async getBacklog(options = {}) {
+        this.warnings = [];
+        this.epicPriority.clear();
+        this.storyPriority.clear();
+        const project = options.projectKey ? await this.getProject(options.projectKey) : undefined;
+        if (options.projectKey && !project) {
+            throw new Error(`Unknown project key: ${options.projectKey}`);
+        }
+        const epic = options.epicKey ? await this.getEpic(options.epicKey, project?.id) : undefined;
+        if (options.epicKey && !epic) {
+            throw new Error(`Unknown epic key: ${options.epicKey}`);
+        }
+        const story = options.storyKey ? await this.getStory(options.storyKey, epic?.id ?? project?.id) : undefined;
+        if (options.storyKey && !story) {
+            throw new Error(`Unknown user story key: ${options.storyKey}`);
+        }
+        const tasks = await this.fetchTasks({
+            projectId: project?.id,
+            epicId: epic?.id,
+            storyId: story?.id,
+            assignee: options.assignee,
+            statuses: options.statuses,
+        });
+        const dependencyMap = await this.fetchDependencies(tasks.map((t) => t.task_id));
+        const totals = emptyTotals();
+        const epics = new Map();
+        const tasksRows = [];
+        for (const row of tasks) {
+            const lane = bucketForStatus(row.task_status);
+            addToTotals(totals, lane, row.task_story_points);
+            let epicSummary = epics.get(row.epic_id);
+            if (!epicSummary) {
+                epicSummary = {
+                    epic_id: row.epic_id,
+                    epic_key: row.epic_key,
+                    title: row.epic_title,
+                    priority: row.epic_priority ?? null,
+                    description: row.epic_description ?? undefined,
+                    totals: emptyTotals(),
+                    stories: [],
+                    storiesMap: new Map(),
+                };
+                epics.set(row.epic_id, epicSummary);
+            }
+            this.epicPriority.set(row.epic_key, row.epic_priority ?? null);
+            addToTotals(epicSummary.totals, lane, row.task_story_points);
+            let storySummary = epicSummary.storiesMap.get(row.story_id);
+            if (!storySummary) {
+                storySummary = {
+                    user_story_id: row.story_id,
+                    user_story_key: row.story_key,
+                    epic_key: row.epic_key,
+                    title: row.story_title,
+                    description: row.story_description ?? undefined,
+                    priority: row.story_priority ?? null,
+                    status: undefined,
+                    totals: emptyTotals(),
+                    statuses: new Set(),
+                };
+                epicSummary.storiesMap.set(row.story_id, storySummary);
+            }
+            this.storyPriority.set(row.story_key, row.story_priority ?? null);
+            addToTotals(storySummary.totals, lane, row.task_story_points);
+            storySummary.statuses.add(row.task_status.toLowerCase());
+            const dependencies = dependencyMap.get(row.task_id) ?? [];
+            tasksRows.push({
+                task_id: row.task_id,
+                task_key: row.task_key,
+                epic_key: row.epic_key,
+                user_story_key: row.story_key,
+                title: row.task_title,
+                description: row.task_description ?? "",
+                status: row.task_status,
+                story_points: row.task_story_points ?? null,
+                priority: row.task_priority ?? null,
+                assignee: row.assignee_human ?? null,
+                dependency_keys: dependencies,
+            });
+        }
+        let orderedTasks;
+        if (options.orderByDependencies) {
+            if (!project) {
+                this.warnings.push("Dependency ordering requires a project scope; using default ordering.");
+                orderedTasks = this.orderTasks(tasksRows, options.verbose === true);
+            }
+            else {
+                const orderingService = await TaskOrderingService.create(this.workspace, { recordTelemetry: false });
+                try {
+                    const ordering = await orderingService.orderTasks({
+                        projectKey: project.key,
+                        epicKey: epic?.key,
+                        storyKey: story?.key,
+                        assignee: options.assignee,
+                        statusFilter: options.statuses,
+                        includeBlocked: true,
+                    });
+                    const orderMap = new Map(ordering.ordered.map((t, idx) => [t.taskId, idx]));
+                    orderedTasks = tasksRows
+                        .slice()
+                        .sort((a, b) => {
+                        const ai = orderMap.get(a.task_id) ?? Number.MAX_SAFE_INTEGER;
+                        const bi = orderMap.get(b.task_id) ?? Number.MAX_SAFE_INTEGER;
+                        if (ai !== bi)
+                            return ai - bi;
+                        return a.task_key.localeCompare(b.task_key);
+                    });
+                    this.warnings.push(...ordering.warnings);
+                }
+                catch (error) {
+                    if (options.verbose) {
+                        this.warnings.push(`Dependency ordering failed; falling back to heuristic ordering. ${error.message}`);
+                    }
+                    orderedTasks = this.orderTasks(tasksRows, options.verbose === true);
+                }
+                finally {
+                    await orderingService.close();
+                }
+            }
+        }
+        else {
+            orderedTasks = this.defaultOrder(tasksRows);
+        }
+        const epicSummaries = Array.from(epics.values()).map((e) => {
+            const stories = Array.from(e.storiesMap.values()).map((s) => ({
+                user_story_id: s.user_story_id,
+                user_story_key: s.user_story_key,
+                epic_key: s.epic_key,
+                title: s.title,
+                description: s.description,
+                priority: s.priority,
+                status: deriveStoryStatus(s.statuses),
+                totals: s.totals,
+            }));
+            return {
+                epic_id: e.epic_id,
+                epic_key: e.epic_key,
+                title: e.title,
+                priority: e.priority,
+                description: e.description,
+                totals: e.totals,
+                stories,
+            };
+        });
+        return {
+            summary: {
+                scope: {
+                    project_id: project?.id ?? null,
+                    project_key: project?.key ?? null,
+                    epic_key: epic?.key,
+                    user_story_key: story?.key,
+                    assignee: options.assignee,
+                },
+                totals,
+                epics: this.sortEpics(epicSummaries),
+                tasks: orderedTasks,
+            },
+            warnings: this.warnings,
+        };
+    }
+    async getProject(projectKey) {
+        const row = await this.db.get(`SELECT id, key FROM projects WHERE key = ?`, projectKey);
+        if (!row)
+            return undefined;
+        return { id: row.id, key: row.key };
+    }
+    async getEpic(epicKey, projectId) {
+        const row = await this.db.get(`SELECT id, key, project_id FROM epics WHERE key = ? ${projectId ? "AND project_id = ?" : ""}`, projectId ? [epicKey, projectId] : [epicKey]);
+        if (!row)
+            return undefined;
+        return { id: row.id, key: row.key, project_id: row.project_id };
+    }
+    async getStory(storyKey, scopeId) {
+        const row = await this.db.get(`SELECT id, key, epic_id FROM user_stories WHERE key = ? ${scopeId ? "AND (epic_id = ? OR project_id = ?)" : ""}`, scopeId ? [storyKey, scopeId, scopeId] : [storyKey]);
+        if (!row)
+            return undefined;
+        return { id: row.id, key: row.key, epic_id: row.epic_id };
+    }
+    async fetchTasks(filters) {
+        const clauses = [];
+        const params = [];
+        if (filters.projectId) {
+            clauses.push("t.project_id = ?");
+            params.push(filters.projectId);
+        }
+        if (filters.epicId) {
+            clauses.push("t.epic_id = ?");
+            params.push(filters.epicId);
+        }
+        if (filters.storyId) {
+            clauses.push("t.user_story_id = ?");
+            params.push(filters.storyId);
+        }
+        if (filters.assignee) {
+            clauses.push("LOWER(t.assignee_human) = LOWER(?)");
+            params.push(filters.assignee);
+        }
+        if (filters.statuses && filters.statuses.length > 0) {
+            const placeholders = filters.statuses.map(() => "?").join(", ");
+            clauses.push(`LOWER(t.status) IN (${placeholders})`);
+            params.push(...filters.statuses.map((s) => s.toLowerCase()));
+        }
+        const where = clauses.length ? `WHERE ${clauses.join(" AND ")}` : "";
+        const rows = await this.db.all(`
+      SELECT
+        t.id AS task_id,
+        t.key AS task_key,
+        t.title AS task_title,
+        t.description AS task_description,
+        t.status AS task_status,
+        t.story_points AS task_story_points,
+        t.priority AS task_priority,
+        t.assignee_human AS assignee_human,
+        e.id AS epic_id,
+        e.key AS epic_key,
+        e.title AS epic_title,
+        e.priority AS epic_priority,
+        e.description AS epic_description,
+        s.id AS story_id,
+        s.key AS story_key,
+        s.title AS story_title,
+        s.priority AS story_priority,
+        s.description AS story_description
+      FROM tasks t
+      INNER JOIN epics e ON t.epic_id = e.id
+      INNER JOIN user_stories s ON t.user_story_id = s.id
+      ${where}
+    `, params);
+        return rows;
+    }
+    async fetchDependencies(taskIds) {
+        const map = new Map();
+        if (taskIds.length === 0)
+            return map;
+        const placeholders = taskIds.map(() => "?").join(", ");
+        const rows = await this.db.all(`
+      SELECT td.task_id, dep.key AS dependency_key
+      FROM task_dependencies td
+      INNER JOIN tasks dep ON dep.id = td.depends_on_task_id
+      WHERE td.task_id IN (${placeholders})
+    `, taskIds);
+        for (const row of rows) {
+            const list = map.get(row.task_id) ?? [];
+            list.push(row.dependency_key);
+            map.set(row.task_id, list);
+        }
+        return map;
+    }
+    defaultOrder(tasks) {
+        const bucketOrder = {
+            implementation: 0,
+            review: 1,
+            qa: 2,
+            done: 3,
+        };
+        const toNum = (value) => (value === null || value === undefined ? Number.MAX_SAFE_INTEGER : value);
+        return tasks
+            .slice()
+            .sort((a, b) => {
+            const laneA = bucketOrder[bucketForStatus(a.status)];
+            const laneB = bucketOrder[bucketForStatus(b.status)];
+            if (laneA !== laneB)
+                return laneA - laneB;
+            const epicPriorityA = toNum(this.epicPriority.get(a.epic_key) ?? null);
+            const epicPriorityB = toNum(this.epicPriority.get(b.epic_key) ?? null);
+            if (epicPriorityA !== epicPriorityB)
+                return epicPriorityA - epicPriorityB;
+            const storyPriorityA = toNum(this.storyPriority.get(a.user_story_key) ?? null);
+            const storyPriorityB = toNum(this.storyPriority.get(b.user_story_key) ?? null);
+            if (storyPriorityA !== storyPriorityB)
+                return storyPriorityA - storyPriorityB;
+            const taskPriorityA = toNum(a.priority);
+            const taskPriorityB = toNum(b.priority);
+            if (taskPriorityA !== taskPriorityB)
+                return taskPriorityA - taskPriorityB;
+            return a.task_key.localeCompare(b.task_key);
+        });
+    }
+    orderTasks(tasks, verbose) {
+        const bucketOrder = ["implementation", "review", "qa", "done"];
+        const allKeys = new Set(tasks.map((t) => t.task_key));
+        const ordered = [];
+        for (const bucket of bucketOrder) {
+            const bucketTasks = tasks.filter((t) => bucketForStatus(t.status) === bucket);
+            const { sorted, hadCycle, missingReference } = this.topologicalSort(bucketTasks, allKeys);
+            if (hadCycle && verbose) {
+                this.warnings.push(`Dependency cycle detected in ${bucket} bucket. Falling back to priority order.`);
+            }
+            if (missingReference && verbose) {
+                this.warnings.push(`Missing dependency reference in ${bucket} bucket. Ordering may be partial.`);
+            }
+            ordered.push(...sorted);
+        }
+        return ordered;
+    }
+    topologicalSort(tasks, allKeys) {
+        if (tasks.length === 0)
+            return { sorted: [], hadCycle: false, missingReference: false };
+        const idByKey = new Map(tasks.map((t, idx) => [t.task_key, idx]));
+        const indegree = new Array(tasks.length).fill(0);
+        const edges = new Map();
+        const fallback = this.defaultOrder(tasks);
+        const indexByTask = new Map();
+        fallback.forEach((task, idx) => indexByTask.set(task.task_id, idx));
+        let missingReference = false;
+        tasks.forEach((task, idx) => {
+            for (const depKey of task.dependency_keys) {
+                if (!allKeys.has(depKey)) {
+                    missingReference = true;
+                    continue;
+                }
+                const depIdx = idByKey.get(depKey);
+                if (depIdx === undefined) {
+                    continue;
+                }
+                indegree[idx] += 1;
+                const list = edges.get(depIdx) ?? [];
+                list.push(idx);
+                edges.set(depIdx, list);
+            }
+        });
+        const queue = [];
+        indegree.forEach((value, idx) => {
+            if (value === 0)
+                queue.push(idx);
+        });
+        const stableSort = (arr) => arr.sort((a, b) => {
+            const fallbackA = indexByTask.get(tasks[a].task_id) ?? 0;
+            const fallbackB = indexByTask.get(tasks[b].task_id) ?? 0;
+            return fallbackA - fallbackB;
+        });
+        stableSort(queue);
+        const result = [];
+        while (queue.length > 0) {
+            const current = queue.shift();
+            result.push(tasks[current]);
+            const neighbors = edges.get(current) ?? [];
+            for (const next of neighbors) {
+                indegree[next] -= 1;
+                if (indegree[next] === 0) {
+                    queue.push(next);
+                }
+            }
+            stableSort(queue);
+        }
+        const hadCycle = result.length !== tasks.length;
+        if (hadCycle) {
+            return { sorted: fallback, hadCycle: true, missingReference };
+        }
+        return { sorted: result, hadCycle: false, missingReference };
+    }
+    sortEpics(epics) {
+        const toNum = (value) => (value === null || value === undefined ? Number.MAX_SAFE_INTEGER : value);
+        return epics
+            .slice()
+            .sort((a, b) => {
+            const priority = toNum(a.priority) - toNum(b.priority);
+            if (priority !== 0)
+                return priority;
+            return a.epic_key.localeCompare(b.epic_key);
+        })
+            .map((epic) => ({
+            ...epic,
+            stories: epic.stories
+                .slice()
+                .sort((a, b) => {
+                const priority = toNum(a.priority) - toNum(b.priority);
+                if (priority !== 0)
+                    return priority;
+                return a.user_story_key.localeCompare(b.user_story_key);
+            }),
+        }));
+    }
+}

package/dist/services/backlog/TaskOrderingService.d.ts

@@ -0,0 +1,88 @@
+import { WorkspaceResolution } from "../../workspace/WorkspaceManager.js";
+interface ProjectRow {
+    id: string;
+    key: string;
+    name?: string | null;
+}
+interface EpicRow {
+    id: string;
+    key: string;
+    project_id: string;
+    title: string;
+}
+interface DependencyImpact {
+    direct: number;
+    total: number;
+}
+export interface TaskOrderItem {
+    taskId: string;
+    taskKey: string;
+    title: string;
+    status: string;
+    storyPoints: number | null;
+    priority: number;
+    epicId: string;
+    epicKey: string;
+    storyId: string;
+    storyKey: string;
+    storyTitle: string;
+    blocked: boolean;
+    blockedBy: string[];
+    dependencyKeys: string[];
+    dependencyImpact: DependencyImpact;
+    cycleDetected?: boolean;
+    metadata?: Record<string, unknown> | null;
+}
+export interface TaskOrderingResult {
+    project: ProjectRow;
+    epic?: EpicRow;
+    ordered: TaskOrderItem[];
+    blocked: TaskOrderItem[];
+    warnings: string[];
+    jobId?: string;
+    commandRunId?: string;
+}
+export interface TaskOrderingRequest {
+    projectKey: string;
+    epicKey?: string;
+    storyKey?: string;
+    assignee?: string;
+    statusFilter?: string[];
+    includeBlocked?: boolean;
+    agentName?: string;
+    agentStream?: boolean;
+}
+export declare class TaskOrderingService {
+    private workspace;
+    private db;
+    private repo;
+    private jobService;
+    private agentService;
+    private globalRepo;
+    private routingService;
+    private docdex;
+    private recordTelemetry;
+    private constructor();
+    static create(workspace: WorkspaceResolution, options?: {
+        recordTelemetry?: boolean;
+    }): Promise<TaskOrderingService>;
+    private buildDocContext;
+    close(): Promise<void>;
+    private getProject;
+    private getEpic;
+    private getStory;
+    private fetchTasks;
+    private fetchDependencies;
+    private dependencyImpactMap;
+    private compareTasks;
+    private topologicalSort;
+    private buildNodes;
+    private resolveAgent;
+    private invokeAgent;
+    private applyAgentRanking;
+    private persistPriorities;
+    private mapResult;
+    orderTasks(request: TaskOrderingRequest): Promise<TaskOrderingResult>;
+}
+export {};
+//# sourceMappingURL=TaskOrderingService.d.ts.map

package/dist/services/backlog/TaskOrderingService.d.ts.map

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