mcoda 0.1.0

package/packages/cli/src/commands/backlog/BacklogCommands.ts

@@ -0,0 +1,286 @@
+import path from "node:path";
+import { BacklogService, BacklogSummary, WorkspaceResolver } from "@mcoda/core";
+
+interface ParsedArgs {
+  workspaceRoot?: string;
+  project?: string;
+  epic?: string;
+  story?: string;
+  assignee?: string;
+  statuses?: string[];
+  orderDependencies: boolean;
+  json: boolean;
+  verbose: boolean;
+}
+
+const usage = `mcoda backlog \\
+  [--workspace-root <PATH>] \\
+  [--project <PROJECT_KEY>] \\
+  [--epic <EPIC_KEY>] \\
+  [--story <STORY_KEY>] \\
+  [--assignee <USER>] \\
+  [--status <STATUS_FILTER>] \\
+  [--order dependencies]   # dependency-aware ordering (topological, most depended-on first) \\
+  [--json] \\
+  [--verbose]`;
+
+const parseStatuses = (value: string | undefined): string[] | undefined => {
+  if (!value) return undefined;
+  return value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean)
+    .map((s) => s.toLowerCase());
+};
+
+export const parseBacklogArgs = (argv: string[]): ParsedArgs => {
+  const args: ParsedArgs = {
+    orderDependencies: false,
+    json: false,
+    verbose: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (!arg.startsWith("-")) continue;
+    switch (arg) {
+      case "--workspace-root":
+        args.workspaceRoot = argv[i + 1] ? path.resolve(argv[i + 1]) : undefined;
+        i += 1;
+        break;
+      case "--project":
+        args.project = argv[i + 1];
+        i += 1;
+        break;
+      case "--epic":
+        args.epic = argv[i + 1];
+        i += 1;
+        break;
+      case "--story":
+        args.story = argv[i + 1];
+        i += 1;
+        break;
+      case "--assignee":
+        args.assignee = argv[i + 1];
+        i += 1;
+        break;
+      case "--status": {
+        const value = argv[i + 1];
+        if (value && !value.startsWith("-")) {
+          args.statuses = parseStatuses(value);
+          i += 1;
+        }
+        break;
+      }
+      default:
+        if (arg.startsWith("--project=")) {
+          args.project = arg.split("=")[1];
+        } else if (arg.startsWith("--epic=")) {
+          args.epic = arg.split("=")[1];
+        } else if (arg.startsWith("--story=")) {
+          args.story = arg.split("=")[1];
+        } else if (arg.startsWith("--assignee=")) {
+          args.assignee = arg.split("=")[1];
+        } else if (arg.startsWith("--status=")) {
+          args.statuses = parseStatuses(arg.split("=")[1]);
+        } else if (arg === "--order") {
+          const value = argv[i + 1];
+          if (value === "dependencies") {
+            args.orderDependencies = true;
+            i += 1;
+          }
+        } else if (arg === "--order=dependencies") {
+          args.orderDependencies = true;
+        } else if (arg === "--json") {
+          args.json = true;
+        } else if (arg === "--verbose") {
+          args.verbose = true;
+        } else if (arg === "--help" || arg === "-h") {
+          // eslint-disable-next-line no-console
+          console.log(usage);
+          process.exit(0);
+        }
+        break;
+    }
+  }
+
+  return args;
+};
+
+const pad = (value: string, width: number): string => value.padEnd(width, " ");
+
+const formatTable = (headers: string[], rows: string[][]): string => {
+  const widths = headers.map((header, idx) => {
+    return Math.max(header.length, ...rows.map((row) => (row[idx] ?? "").length));
+  });
+  const headerLine = headers.map((h, idx) => pad(h, widths[idx])).join(" | ");
+  const sepLine = widths.map((w) => "-".repeat(w)).join("-+-");
+  const body = rows.map((row) => row.map((cell, idx) => pad(cell ?? "", widths[idx])).join(" | ")).join("\n");
+  return [headerLine, sepLine, body].filter(Boolean).join("\n");
+};
+
+const truncate = (value: string | undefined, max = 100): string => {
+  if (!value) return "";
+  if (value.length <= max) return value;
+  return `${value.slice(0, max - 3)}...`;
+};
+
+const formatNumber = (value: number | null | undefined): string => {
+  if (value === null || value === undefined) return "-";
+  if (Number.isInteger(value)) return `${value}`;
+  return value.toFixed(2);
+};
+
+const renderSummary = (summary: BacklogSummary): void => {
+  const rows = [
+    ["Implementation", `${summary.totals.implementation.tasks}`, formatNumber(summary.totals.implementation.story_points)],
+    ["Review", `${summary.totals.review.tasks}`, formatNumber(summary.totals.review.story_points)],
+    ["QA", `${summary.totals.qa.tasks}`, formatNumber(summary.totals.qa.story_points)],
+    ["Done", `${summary.totals.done.tasks}`, formatNumber(summary.totals.done.story_points)],
+  ];
+  // eslint-disable-next-line no-console
+  console.log("Summary (tasks / SP):");
+  // eslint-disable-next-line no-console
+  console.log(formatTable(["LANE", "TASKS", "SP"], rows));
+};
+
+const renderEpics = (summary: BacklogSummary): void => {
+  if (summary.epics.length === 0) {
+    // eslint-disable-next-line no-console
+    console.log("\nEpics: none");
+    return;
+  }
+  const rows = summary.epics.map((epic) => [
+    epic.epic_key,
+    truncate(epic.title, 40),
+    formatNumber(epic.priority),
+    formatNumber(epic.totals.implementation.story_points),
+    formatNumber(epic.totals.review.story_points),
+    formatNumber(epic.totals.qa.story_points),
+    formatNumber(epic.totals.done.story_points),
+    `${epic.totals.implementation.tasks + epic.totals.review.tasks + epic.totals.qa.tasks + epic.totals.done.tasks}`,
+    truncate(epic.description, 100),
+  ]);
+  // eslint-disable-next-line no-console
+  console.log("\nEpics:");
+  // eslint-disable-next-line no-console
+  console.log(
+    formatTable(
+      ["EPIC_KEY", "TITLE", "PRIORITY", "IMPL_SP", "REVIEW_SP", "QA_SP", "DONE_SP", "TASKS", "DESC"],
+      rows,
+    ),
+  );
+};
+
+const renderStories = (summary: BacklogSummary): void => {
+  const stories = summary.epics.flatMap((epic) => epic.stories);
+  if (stories.length === 0) {
+    // eslint-disable-next-line no-console
+    console.log("\nStories: none");
+    return;
+  }
+  const rows = stories.map((story) => [
+    story.user_story_key,
+    story.epic_key,
+    truncate(story.title, 40),
+    formatNumber(story.priority),
+    story.status ?? "-",
+    formatNumber(story.totals.implementation.story_points),
+    formatNumber(story.totals.review.story_points),
+    formatNumber(story.totals.qa.story_points),
+    formatNumber(story.totals.done.story_points),
+    `${story.totals.implementation.tasks + story.totals.review.tasks + story.totals.qa.tasks + story.totals.done.tasks}`,
+    truncate(story.description, 100),
+  ]);
+  // eslint-disable-next-line no-console
+  console.log("\nStories:");
+  // eslint-disable-next-line no-console
+  console.log(
+    formatTable(
+      ["STORY_KEY", "EPIC_KEY", "TITLE", "PRIORITY", "STATUS", "IMPL_SP", "REVIEW_SP", "QA_SP", "DONE_SP", "TASKS", "DESC"],
+      rows,
+    ),
+  );
+};
+
+const renderTasks = (summary: BacklogSummary): void => {
+  if (summary.tasks.length === 0) {
+    // eslint-disable-next-line no-console
+    console.log("\nTasks: none");
+    return;
+  }
+  const rows = summary.tasks.map((task) => [
+    task.task_key,
+    task.epic_key,
+    task.user_story_key,
+    task.status,
+    formatNumber(task.story_points),
+    formatNumber(task.priority),
+    task.assignee ?? "-",
+    truncate(task.dependency_keys.join(", "), 80),
+    truncate(task.description, 100),
+  ]);
+  // eslint-disable-next-line no-console
+  console.log("\nTasks:");
+  // eslint-disable-next-line no-console
+  console.log(
+    formatTable(
+      ["TASK_KEY", "EPIC_KEY", "STORY_KEY", "STATUS", "SP", "PRIORITY", "ASSIGNEE", "DEPENDS_ON", "DESC"],
+      rows,
+    ),
+  );
+};
+
+const renderBacklog = (summary: BacklogSummary): void => {
+  renderSummary(summary);
+  renderEpics(summary);
+  renderStories(summary);
+  renderTasks(summary);
+};
+
+export class BacklogCommands {
+  static async run(argv: string[]): Promise<void> {
+    const parsed = parseBacklogArgs(argv);
+    const workspace = await WorkspaceResolver.resolveWorkspace({
+      cwd: process.cwd(),
+      explicitWorkspace: parsed.workspaceRoot,
+    });
+
+    let service: BacklogService | undefined;
+    try {
+      service = await BacklogService.create(workspace);
+      const { summary, warnings } = await service.getBacklog({
+        projectKey: parsed.project,
+        epicKey: parsed.epic,
+        storyKey: parsed.story,
+        assignee: parsed.assignee,
+        statuses: parsed.statuses,
+        orderByDependencies: parsed.orderDependencies,
+        verbose: parsed.verbose,
+      });
+
+      if (parsed.json) {
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(summary, null, 2));
+      } else {
+        renderBacklog(summary);
+        if (parsed.verbose && warnings.length > 0) {
+          // eslint-disable-next-line no-console
+          console.error("\nWarnings:");
+          for (const warning of warnings) {
+            // eslint-disable-next-line no-console
+            console.error(`- ${warning}`);
+          }
+        }
+      }
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error(`backlog failed: ${(error as Error).message}`);
+      process.exitCode = 1;
+    } finally {
+      if (service) {
+        await service.close();
+      }
+    }
+  }
+}

package/packages/cli/src/commands/backlog/OrderTasksCommand.ts

@@ -0,0 +1,237 @@
+import path from "node:path";
+import { TaskOrderingService, WorkspaceResolver } from "@mcoda/core";
+
+interface ParsedArgs {
+  workspaceRoot?: string;
+  project?: string;
+  epic?: string;
+  status?: string[];
+  includeBlocked: boolean;
+  agentName?: string;
+  agentStream?: boolean;
+  json: boolean;
+}
+
+const usage = `mcoda order-tasks \\
+  [--workspace-root <PATH>] \\
+  --project <PROJECT_KEY> \\
+  [--epic <EPIC_KEY>] \\
+  [--status <STATUS_FILTER>] \\
+  [--include-blocked] \\
+  [--agent <NAME>] \\
+  [--agent-stream <true|false>] \\
+  [--json]`;
+
+const parseBooleanFlag = (value: string | undefined, defaultValue: boolean): boolean => {
+  if (value === undefined) return defaultValue;
+  const normalized = value.toLowerCase();
+  if (["false", "0", "no"].includes(normalized)) return false;
+  if (["true", "1", "yes"].includes(normalized)) return true;
+  return defaultValue;
+};
+
+const parseStatuses = (value?: string): string[] | undefined => {
+  if (!value) return undefined;
+  const parts = value
+    .split(",")
+    .map((s) => s.trim())
+    .filter(Boolean);
+  return parts.length ? parts : undefined;
+};
+
+export const parseOrderTasksArgs = (argv: string[]): ParsedArgs => {
+  const parsed: ParsedArgs = {
+    includeBlocked: false,
+    json: false,
+  };
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg.startsWith("--status=")) {
+      parsed.status = parseStatuses(arg.split("=")[1]);
+      continue;
+    }
+    if (arg.startsWith("--agent-stream=")) {
+      parsed.agentStream = parseBooleanFlag(arg.split("=")[1], true);
+      continue;
+    }
+    switch (arg) {
+      case "--workspace-root":
+        parsed.workspaceRoot = argv[i + 1] ? path.resolve(argv[i + 1]) : undefined;
+        i += 1;
+        break;
+      case "--project":
+        parsed.project = argv[i + 1];
+        i += 1;
+        break;
+      case "--epic":
+        parsed.epic = argv[i + 1];
+        i += 1;
+        break;
+      case "--status":
+        parsed.status = parseStatuses(argv[i + 1]);
+        i += 1;
+        break;
+      case "--include-blocked":
+        parsed.includeBlocked = true;
+        break;
+      case "--agent":
+        parsed.agentName = argv[i + 1];
+        i += 1;
+        break;
+      case "--agent-stream": {
+        const next = argv[i + 1];
+        if (next && !next.startsWith("-")) {
+          parsed.agentStream = parseBooleanFlag(next, true);
+          i += 1;
+        } else {
+          parsed.agentStream = true;
+        }
+        break;
+      }
+      case "--json":
+        parsed.json = true;
+        break;
+      case "--help":
+      case "-h":
+        // eslint-disable-next-line no-console
+        console.log(usage);
+        process.exit(0);
+        break;
+      default:
+        if (arg.startsWith("--project=")) {
+          parsed.project = arg.split("=")[1];
+        } else if (arg.startsWith("--epic=")) {
+          parsed.epic = arg.split("=")[1];
+        } else if (arg === "--include-blocked=true") {
+          parsed.includeBlocked = true;
+        } else if (arg === "--json=true") {
+          parsed.json = true;
+        }
+        break;
+    }
+  }
+  return parsed;
+};
+
+const pad = (value: string, width: number): string => value.padEnd(width, " ");
+
+const formatTable = (headers: string[], rows: string[][]): string => {
+  const widths = headers.map((header, idx) => Math.max(header.length, ...rows.map((row) => (row[idx] ?? "").length)));
+  const headerLine = headers.map((h, idx) => pad(h, widths[idx])).join(" | ");
+  const sepLine = widths.map((w) => "-".repeat(w)).join("-+-");
+  const body = rows.map((row) => row.map((cell, idx) => pad(cell ?? "", widths[idx])).join(" | ")).join("\n");
+  return [headerLine, sepLine, body].filter(Boolean).join("\n");
+};
+
+const formatImpact = (value?: { direct: number; total: number }): string => {
+  if (!value) return "-";
+  return `${value.direct}/${value.total}`;
+};
+
+const renderOrder = (
+  ordered: Awaited<ReturnType<TaskOrderingService["orderTasks"]>>["ordered"],
+  blocked: Awaited<ReturnType<TaskOrderingService["orderTasks"]>>["blocked"],
+  includeBlocked: boolean,
+  warnings: string[],
+): void => {
+  const rows = ordered.map((task) => [
+    `${task.priority}`,
+    task.taskKey,
+    task.status,
+    task.storyPoints === null || task.storyPoints === undefined ? "-" : `${task.storyPoints}`,
+    task.epicKey,
+    task.storyKey,
+    formatImpact(task.dependencyImpact),
+    task.blocked ? "yes" : "",
+    task.title.length > 60 ? `${task.title.slice(0, 57)}...` : task.title,
+  ]);
+
+  // eslint-disable-next-line no-console
+  console.log(
+    formatTable(
+      ["PRIORITY", "TASK", "STATUS", "SP", "EPIC", "STORY", "DEP_IMPACT", "BLOCKED", "TITLE"],
+      rows,
+    ),
+  );
+
+  if (!includeBlocked && blocked.length > 0) {
+    // eslint-disable-next-line no-console
+    console.log("\nBlocked tasks (excluded from ordering):");
+    const blockedRows = blocked.map((task) => [
+      `${task.priority}`,
+      task.taskKey,
+      task.status,
+      task.storyPoints === null || task.storyPoints === undefined ? "-" : `${task.storyPoints}`,
+      task.epicKey,
+      task.storyKey,
+      formatImpact(task.dependencyImpact),
+      (task.blockedBy ?? []).join(", "),
+      task.title.length > 60 ? `${task.title.slice(0, 57)}...` : task.title,
+    ]);
+    // eslint-disable-next-line no-console
+    console.log(
+      formatTable(
+        ["PRIORITY", "TASK", "STATUS", "SP", "EPIC", "STORY", "DEP_IMPACT", "BLOCKED_BY", "TITLE"],
+        blockedRows,
+      ),
+    );
+  }
+
+  if (warnings.length > 0) {
+    // eslint-disable-next-line no-console
+    console.warn("\nWarnings:");
+    warnings.forEach((w) => {
+      // eslint-disable-next-line no-console
+      console.warn(`- ${w}`);
+    });
+  }
+};
+
+export class OrderTasksCommand {
+  static async run(argv: string[]): Promise<void> {
+    const parsed = parseOrderTasksArgs(argv);
+    const workspace = await WorkspaceResolver.resolveWorkspace({
+      cwd: process.cwd(),
+      explicitWorkspace: parsed.workspaceRoot,
+    });
+    if (!parsed.project) {
+      // eslint-disable-next-line no-console
+      console.error("order-tasks requires --project <PROJECT_KEY>");
+      process.exitCode = 1;
+      return;
+    }
+    const service = await TaskOrderingService.create(workspace);
+    try {
+      const result = await service.orderTasks({
+        projectKey: parsed.project,
+        epicKey: parsed.epic,
+        statusFilter: parsed.status,
+        includeBlocked: parsed.includeBlocked,
+        agentName: parsed.agentName,
+        agentStream: parsed.agentStream,
+      });
+      if (parsed.json) {
+        const payload: Record<string, unknown> = {
+          order: parsed.includeBlocked ? result.ordered : result.ordered.filter((t) => !t.blocked),
+        };
+        if (result.warnings.length > 0) {
+          payload.warnings = result.warnings;
+        }
+        // eslint-disable-next-line no-console
+        console.log(JSON.stringify(payload, null, 2));
+        return;
+      }
+      renderOrder(result.ordered, result.blocked, parsed.includeBlocked, result.warnings);
+    } catch (error) {
+      // eslint-disable-next-line no-console
+      console.error(`order-tasks failed: ${(error as Error).message}`);
+      process.exitCode = 1;
+    } finally {
+      try {
+        await service.close();
+      } catch {
+        // ignore close errors (e.g., database already closed)
+      }
+    }
+  }
+}