@sprintdock/backend 0.4.2

package/src/infrastructure/repositories/repository-factory.ts

@@ -0,0 +1,54 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Factory wiring repository ports to concrete storage adapters.
+ */
+import type { PlanRepository } from "../../domain/repositories/plan.repository";
+import type { SprintRepository } from "../../domain/repositories/sprint.repository";
+import type { TaskRepository } from "../../domain/repositories/task.repository";
+import {
+  DrizzlePlanRepository,
+  DrizzleSprintRepository,
+  DrizzleTaskRepository,
+  type DrizzleSqliteDb
+} from "./drizzle/index";
+
+/** Supported storage backends for repository construction. */
+export type StorageAdapterType = "sqlite";
+
+/** Per-adapter connection options. */
+export interface StorageConfig {
+  sqlite?: { db: DrizzleSqliteDb };
+}
+
+/** Wired repository set for application services. */
+export interface RepositorySet {
+  plans: PlanRepository;
+  sprints: SprintRepository;
+  tasks: TaskRepository;
+}
+
+/**
+ * Instantiates repository implementations for the selected adapter.
+ *
+ * @param adapter Storage kind (currently only sqlite).
+ * @param config Connection options for the adapter.
+ * @returns Repository ports backed by the configured database.
+ */
+export function createRepositories(
+  adapter: StorageAdapterType,
+  config: StorageConfig
+): RepositorySet {
+  if (adapter !== "sqlite") {
+    throw new Error(`Unsupported storage adapter: ${adapter}`);
+  }
+  const db = config.sqlite?.db;
+  if (!db) {
+    throw new Error('createRepositories("sqlite") requires config.sqlite.db');
+  }
+  return {
+    plans: new DrizzlePlanRepository(db),
+    sprints: new DrizzleSprintRepository(db),
+    tasks: new DrizzleTaskRepository(db)
+  };
+}

package/src/infrastructure/security/auth-context.ts

@@ -0,0 +1,35 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Authentication context contracts for MCP request authorization.
+ */
+
+/**
+ * Principal context resolved for each request.
+ */
+export interface AuthContext {
+  principalId: string;
+  scopes: readonly string[];
+  transport: "stdio" | "http";
+}
+
+/**
+ * Resolver interface for obtaining request principal details.
+ */
+export interface AuthContextResolver {
+  resolve(transport: "stdio" | "http"): Promise<AuthContext>;
+}
+
+/**
+ * Local development resolver for no-auth environments.
+ */
+export class LocalAuthContextResolver implements AuthContextResolver {
+  /** @inheritdoc */
+  public async resolve(transport: "stdio" | "http"): Promise<AuthContext> {
+    return {
+      principalId: "local-dev-principal",
+      scopes: ["sprintdock:read", "sprintdock:write"],
+      transport
+    };
+  }
+}

package/src/infrastructure/security/input-guard.ts

@@ -0,0 +1,21 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Strict schema parsing helpers for adapter and HTTP inputs.
+ */
+import { z, type ZodTypeAny } from "zod";
+
+/**
+ * Validates and parses unknown values using strict schema constraints.
+ *
+ * @param schema Zod schema used for validation.
+ * @param input Unknown payload value.
+ * @returns Parsed payload.
+ * @throws ZodError when validation fails.
+ */
+export function parseStrict<T extends ZodTypeAny>(
+  schema: T,
+  input: unknown
+): z.infer<T> {
+  return schema.parse(input);
+}

package/src/infrastructure/security/rate-limiter.ts

@@ -0,0 +1,65 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Lightweight per-key rate limiter for MCP tool invocations.
+ */
+
+/**
+ * Rate limiter result for caller decisions.
+ */
+export interface RateLimitResult {
+  allowed: boolean;
+  retryAfterSeconds: number;
+}
+
+/**
+ * Contract for backend tool-call throttling.
+ */
+export interface BackendRateLimiter {
+  check(key: string): RateLimitResult;
+}
+
+/**
+ * In-memory fixed-window limiter for local runtime safety.
+ */
+export class InMemoryBackendRateLimiter implements BackendRateLimiter {
+  private readonly maxRequests: number;
+  private readonly windowMs: number;
+  private readonly requestWindows: Map<string, number[]>;
+
+  /**
+   * @param maxRequests Maximum allowed requests per window.
+   * @param windowMs Window size in milliseconds.
+   */
+  public constructor(maxRequests = 120, windowMs = 60_000) {
+    this.maxRequests = maxRequests;
+    this.windowMs = windowMs;
+    this.requestWindows = new Map<string, number[]>();
+  }
+
+  /** @inheritdoc */
+  public check(key: string): RateLimitResult {
+    const now = Date.now();
+    const threshold = now - this.windowMs;
+    const previous = this.requestWindows.get(key) ?? [];
+    const currentWindow = previous.filter((timestamp) => timestamp > threshold);
+    if (currentWindow.length >= this.maxRequests) {
+      const oldestRequestTimestamp = currentWindow[0] ?? now;
+      const retryAfterSeconds = Math.max(
+        1,
+        Math.ceil((oldestRequestTimestamp + this.windowMs - now) / 1000)
+      );
+      this.requestWindows.set(key, currentWindow);
+      return {
+        allowed: false,
+        retryAfterSeconds
+      };
+    }
+    currentWindow.push(now);
+    this.requestWindows.set(key, currentWindow);
+    return {
+      allowed: true,
+      retryAfterSeconds: 0
+    };
+  }
+}

package/src/mcp/bootstrap-sprintdock-sqlite.ts

@@ -0,0 +1,45 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Ensures `.sprintdock/`, opens SQLite, migrates, and wires application services.
+ */
+import { mkdirSync } from "node:fs";
+import { dirname, isAbsolute, join } from "node:path";
+import {
+  ensureSprintdockDirectory,
+  resolveSprintdockDbPath,
+  resolveWorkspaceRoot
+} from "@sprintdock/shared";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import * as schema from "../db/schema/index.js";
+import { createApplicationServices, type ServiceSet } from "../application/container.js";
+import { createSqliteConnection } from "../db/connection.js";
+import { runMigrations } from "../db/migrator.js";
+import { createRepositories } from "../infrastructure/repositories/repository-factory.js";
+
+export interface SprintdockSqliteBootstrapResult {
+  db: BetterSQLite3Database<typeof schema>;
+  services: ServiceSet;
+  dbPath: string;
+}
+
+/**
+ * Resolves DB path (`SPRINTDOCK_DB_PATH` or `.sprintdock/sprintdock.db`), migrates, and returns services.
+ */
+export async function bootstrapSprintdockSqlite(): Promise<SprintdockSqliteBootstrapResult> {
+  const workspaceRoot = resolveWorkspaceRoot();
+  await ensureSprintdockDirectory({ workspaceRoot });
+  const envPath = process.env.SPRINTDOCK_DB_PATH?.trim();
+  const dbPath =
+    envPath && envPath.length > 0
+      ? isAbsolute(envPath)
+        ? envPath
+        : join(workspaceRoot, envPath)
+      : resolveSprintdockDbPath({ workspaceRoot });
+  mkdirSync(dirname(dbPath), { recursive: true });
+  const db = createSqliteConnection(dbPath);
+  runMigrations(db);
+  const repos = createRepositories("sqlite", { sqlite: { db } });
+  const services = createApplicationServices(repos);
+  return { db, services, dbPath };
+}

package/src/mcp/mcp-query-helpers.ts

@@ -0,0 +1,89 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Shared helpers for MCP tools (plan scoping, aggregates).
+ */
+import { ValidationError } from "../errors/backend-errors.js";
+import type { Plan } from "../domain/entities/plan.entity";
+import type { Sprint } from "../domain/entities/sprint.entity";
+import type { Task, TaskStatus } from "../domain/entities/task.entity";
+import type { PlanService } from "../application/plan.service.js";
+import type { SprintService } from "../application/sprint.service.js";
+import type { TaskService } from "../application/task.service.js";
+
+const UUID_RE =
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+
+export function looksLikeUuid(value: string): boolean {
+  return UUID_RE.test(value);
+}
+
+/**
+ * Resolves an explicit plan slug/id or falls back to the active plan.
+ */
+export async function resolvePlanOrActive(
+  planService: PlanService,
+  planSlug?: string
+): Promise<Plan> {
+  if (planSlug !== undefined && planSlug !== "") {
+    return planService.resolvePlan(planSlug);
+  }
+  return planService.getActivePlan();
+}
+
+export function countByTaskStatus(
+  tasks: Task[]
+): Record<TaskStatus, number> {
+  const base: Record<TaskStatus, number> = {
+    todo: 0,
+    in_progress: 0,
+    blocked: 0,
+    done: 0
+  };
+  for (const t of tasks) {
+    base[t.status] += 1;
+  }
+  return base;
+}
+
+/**
+ * Loads a sprint by UUID or by slug under the given plan.
+ */
+export async function getSprintForPlan(
+  sprintService: SprintService,
+  plan: Plan,
+  sprintIdOrSlug: string
+): Promise<Sprint> {
+  if (looksLikeUuid(sprintIdOrSlug)) {
+    const sp = await sprintService.getSprint(sprintIdOrSlug);
+    if (sp.planId !== plan.id) {
+      throw new ValidationError("Sprint does not belong to the resolved plan");
+    }
+    return sp;
+  }
+  return sprintService.getSprintBySlug(plan.id, sprintIdOrSlug);
+}
+
+export async function ensureSprintInPlan(
+  sprintService: SprintService,
+  plan: Plan,
+  sprintId: string
+): Promise<Sprint> {
+  const sp = await sprintService.getSprint(sprintId);
+  if (sp.planId !== plan.id) {
+    throw new ValidationError("Sprint does not belong to the resolved plan");
+  }
+  return sp;
+}
+
+export async function ensureTaskInPlan(
+  taskService: TaskService,
+  sprintService: SprintService,
+  plan: Plan,
+  taskId: string
+): Promise<Task> {
+  const task = await taskService.getTask(taskId);
+  await ensureSprintInPlan(sprintService, plan, task.sprintId);
+  return task;
+}
+

package/src/mcp/mcp-text-formatters.ts

@@ -0,0 +1,204 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Human-readable MCP tool text for AI agents (lists, summaries, sprint detail).
+ */
+import type { Plan } from "../domain/entities/plan.entity";
+import type { Sprint } from "../domain/entities/sprint.entity";
+import type { Task, TaskStatus } from "../domain/entities/task.entity";
+
+/** Sprint row plus per-status task counts (for list_sprints / summaries). */
+export type SprintWithTaskCounts = Sprint & {
+  taskCounts: Record<TaskStatus, number>;
+};
+
+const STATUS_ORDER: TaskStatus[] = [
+  "todo",
+  "in_progress",
+  "blocked",
+  "done"
+];
+
+/**
+ * Short stable task/sprint reference: first 8 hex digits of the UUID (no dashes).
+ */
+export function shortId(uuid: string): string {
+  return uuid.replace(/-/g, "").slice(0, 8);
+}
+
+function formatTaskCounts(counts: Record<TaskStatus, number>): string {
+  const parts: string[] = [];
+  for (const s of STATUS_ORDER) {
+    const n = counts[s];
+    if (n > 0) {
+      parts.push(`${n} ${s}`);
+    }
+  }
+  return parts.join(", ");
+}
+
+function formatTaskLine(task: Task, indent = ""): string {
+  const assignee =
+    task.assignee !== null && task.assignee !== ""
+      ? `, assignee: ${task.assignee}`
+      : "";
+  return `${indent}- [${task.status}] "${task.title}" (priority: ${task.priority}${assignee}) id:${shortId(task.id)}`;
+}
+
+/**
+ * Formats the plan directory list for `list_plans`.
+ */
+export function formatPlanList(plans: Plan[], activePlanId: string | null): string {
+  const header = `Plans (${plans.length}):`;
+  if (plans.length === 0) {
+    return header;
+  }
+  const lines = plans.map((p) => {
+    const activeSuffix = p.isActive || p.id === activePlanId ? " (active plan)" : "";
+    return `- ${p.slug} [${p.status}] "${p.title}"${activeSuffix}`;
+  });
+  return `${header}\n${lines.join("\n")}`;
+}
+
+/**
+ * Formats sprints with per-sprint task counts for `list_sprints`.
+ */
+export function formatSprintList(
+  planSlug: string,
+  sprints: SprintWithTaskCounts[]
+): string {
+  const header = `Sprints for '${planSlug}' (${sprints.length}):`;
+  if (sprints.length === 0) {
+    return header;
+  }
+  const lines = sprints.map((s) => {
+    const tc = formatTaskCounts(s.taskCounts);
+    const countsPart = tc.length > 0 ? ` | ${tc}` : "";
+    return `- ${s.slug} [${s.status}] "${s.name}"${countsPart} | sprintId:${s.id}`;
+  });
+  return `${header}\n${lines.join("\n")}`;
+}
+
+/**
+ * Formats a flat task list for `list_tasks` and nested views.
+ */
+export function formatTaskList(tasks: Task[], headerLabel = "Tasks"): string {
+  const header = `${headerLabel} (${tasks.length}):`;
+  if (tasks.length === 0) {
+    return header;
+  }
+  const lines = tasks.map((t) => formatTaskLine(t));
+  return `${header}\n${lines.join("\n")}`;
+}
+
+export type PlanSummarySprintRow = {
+  sprintSlug: string;
+  sprintId: string;
+  name: string;
+  status: Sprint["status"];
+  taskCounts: Record<TaskStatus, number>;
+};
+
+/**
+ * Rich plan overview for `get_plan_summary`.
+ */
+export function formatPlanSummary(
+  plan: Plan,
+  sprintsOut: PlanSummarySprintRow[]
+): string {
+  let totalTasks = 0;
+  for (const s of sprintsOut) {
+    totalTasks += Object.values(s.taskCounts).reduce((a, b) => a + b, 0);
+  }
+  const sprintWord = sprintsOut.length === 1 ? "sprint" : "sprints";
+  const taskWord = totalTasks === 1 ? "task" : "tasks";
+  const head = `Plan '${plan.slug}' ("${plan.title}") -- ${sprintsOut.length} ${sprintWord}, ${totalTasks} ${taskWord} total`;
+  if (sprintsOut.length === 0) {
+    return head;
+  }
+  const breakdown = sprintsOut.map((s) => {
+    const tc = formatTaskCounts(s.taskCounts);
+    const countsPart = tc.length > 0 ? `: ${tc}` : ":";
+    return `- ${s.sprintSlug} [${s.status}]${countsPart} (id: ${shortId(s.sprintId)})`;
+  });
+  return `${head}\n\nSprint breakdown:\n${breakdown.join("\n")}`;
+}
+
+export type ExecutionSprintBlock = {
+  sprintSlug: string;
+  sprint: Sprint;
+  tasks: Task[];
+  taskCounts: Record<TaskStatus, number>;
+};
+
+/**
+ * Primary agent context view for `get_execution_context`.
+ */
+export function formatExecutionContext(
+  planSlug: string,
+  activeSprints: ExecutionSprintBlock[]
+): string {
+  const head = `Execution context for '${planSlug}':\nActive sprints (${activeSprints.length}):`;
+  if (activeSprints.length === 0) {
+    return head;
+  }
+  const blocks = activeSprints.map((block) => {
+    const sp = block.sprint;
+    const title = `Sprint '${sp.slug}' "${sp.name}" (id: ${shortId(sp.id)}):`;
+    const taskLines =
+      block.tasks.length === 0
+        ? "  (no tasks)"
+        : block.tasks.map((t) => formatTaskLine(t, "  ")).join("\n");
+    const summary = `  Summary: ${formatTaskCounts(block.taskCounts)}`;
+    return `${title}\n${taskLines}\n${summary}`;
+  });
+  return `${head}\n\n${blocks.join("\n\n")}`;
+}
+
+/**
+ * Single-sprint detail for `get_sprint_detail`.
+ */
+/** Per-sprint roll-up for `get_plan_progress`. */
+export type PlanProgressSprintRow = {
+  slug: string;
+  name: string;
+  status: Sprint["status"];
+  done: number;
+  total: number;
+};
+
+/**
+ * Overall completion summary for `get_plan_progress`.
+ */
+export function formatPlanProgress(
+  planSlug: string,
+  done: number,
+  totalTasks: number,
+  sprints: PlanProgressSprintRow[]
+): string {
+  const pct =
+    totalTasks === 0 ? 0 : Math.round((done / totalTasks) * 100);
+  const head = `Plan '${planSlug}' progress: ${pct}% complete (${done}/${totalTasks} tasks done)`;
+  if (sprints.length === 0) {
+    return head;
+  }
+  const lines = sprints.map((s) => {
+    const spct = s.total === 0 ? 0 : Math.round((s.done / s.total) * 100);
+    return `- ${s.name} (${s.slug}) [${s.status}]: ${s.done}/${s.total} done (${spct}%)`;
+  });
+  return `${head}\n${lines.join("\n")}`;
+}
+
+export function formatSprintDetail(sprint: Sprint, tasks: Task[]): string {
+  const dates =
+    sprint.startDate || sprint.endDate
+      ? `\nDates: start=${sprint.startDate ?? "—"}, end=${sprint.endDate ?? "—"}`
+      : "";
+  const md =
+    sprint.markdownContent != null && sprint.markdownContent.trim().length > 0
+      ? `\n\n--- Markdown ---\n${sprint.markdownContent}`
+      : "";
+  const header = `Sprint '${sprint.name}' (${sprint.slug}) [${sprint.status}]\nGoal: ${sprint.goal}${dates}${md}`;
+  const body = formatTaskList(tasks, "Tasks");
+  return `${header}\n\n${body}`;
+}

package/src/mcp/mcp-tool-error.ts

@@ -0,0 +1,24 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Maps domain errors to MCP tool error responses.
+ */
+import { BackendError } from "../errors/backend-errors.js";
+
+export type McpToolErrorResult = {
+  content: [{ type: "text"; text: string }];
+  isError: true;
+};
+
+/**
+ * Converts known errors into MCP tool `isError` payloads; rethrows unknown non-Errors.
+ */
+export function toMcpToolError(error: unknown): McpToolErrorResult {
+  if (error instanceof BackendError) {
+    return { content: [{ type: "text", text: error.message }], isError: true };
+  }
+  if (error instanceof Error) {
+    return { content: [{ type: "text", text: error.message }], isError: true };
+  }
+  throw error;
+}

package/src/mcp/plugins/context-tools.plugin.ts

@@ -0,0 +1,107 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: MCP plugin — execution context and sprint detail (read-heavy agent views).
+ */
+import { z } from "zod";
+import {
+  countByTaskStatus,
+  getSprintForPlan,
+  resolvePlanOrActive
+} from "../mcp-query-helpers.js";
+import {
+  formatExecutionContext,
+  formatSprintDetail
+} from "../mcp-text-formatters.js";
+import { toMcpToolError } from "../mcp-tool-error.js";
+import type { SprintdockMcpToolPlugin } from "./types.js";
+
+export const contextToolsPlugin: SprintdockMcpToolPlugin = {
+  id: "sprintdock/context-tools",
+  register(server, ctx) {
+    const { deps, kit } = ctx;
+    const { jsonStructured, optionalPlanSlug } = kit;
+    const { planService, sprintService, taskService } = deps.services;
+
+    server.registerTool(
+      "get_sprint_detail",
+      {
+        description:
+          "Loads one sprint by UUID or sprint slug within the resolved plan, including goal, dates, status, and a full task list with metadata. Prefer this over get_sprint when you need tasks.",
+        inputSchema: z
+          .object({
+            sprintIdOrSlug: z.string().min(1),
+            planSlug: optionalPlanSlug
+          })
+          .strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const sprint = await getSprintForPlan(
+            sprintService,
+            plan,
+            input.sprintIdOrSlug
+          );
+          const tasks = await taskService.listTasks(sprint.id);
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatSprintDetail(sprint, tasks)
+              }
+            ],
+            structuredContent: jsonStructured({
+              sprintSlug: sprint.slug,
+              sprint,
+              tasks
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+
+    server.registerTool(
+      "get_execution_context",
+      {
+        description:
+          "Returns the working plan plus every active sprint, each with its full task list and per-status counts. This is the main tool to see what to work on next.",
+        inputSchema: z.object({ planSlug: optionalPlanSlug }).strict()
+      },
+      async (input) => {
+        try {
+          const plan = await resolvePlanOrActive(planService, input.planSlug);
+          const all = await sprintService.listSprints(plan.id);
+          const activeSprints = [];
+          for (const sp of all) {
+            if (sp.status !== "active") continue;
+            const tasks = await taskService.listTasks(sp.id);
+            activeSprints.push({
+              sprintSlug: sp.slug,
+              sprint: sp,
+              tasks,
+              taskCounts: countByTaskStatus(tasks)
+            });
+          }
+          return {
+            content: [
+              {
+                type: "text",
+                text: formatExecutionContext(plan.slug, activeSprints)
+              }
+            ],
+            structuredContent: jsonStructured({
+              planSlug: plan.slug,
+              planTitle: plan.title,
+              activeSprints
+            })
+          };
+        } catch (e) {
+          return toMcpToolError(e);
+        }
+      }
+    );
+  }
+};

package/src/mcp/plugins/default-plugins.ts

@@ -0,0 +1,23 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Default ordered plugin list for full Sprintdock MCP tool surface.
+ */
+import { contextToolsPlugin } from "./context-tools.plugin.js";
+import { planToolsPlugin } from "./plan-tools.plugin.js";
+import { sprintToolsPlugin } from "./sprint-tools.plugin.js";
+import { taskToolsPlugin } from "./task-tools.plugin.js";
+import { taskWorkflowPlugin } from "./task-workflow.plugin.js";
+import type { SprintdockMcpToolPlugin } from "./types.js";
+
+/**
+ * Built-in plugins in registration order. Duplicate tool names across plugins will
+ * overwrite earlier registrations — keep each tool name unique per plugin set.
+ */
+export const defaultSprintdockMcpPlugins: readonly SprintdockMcpToolPlugin[] = [
+  planToolsPlugin,
+  contextToolsPlugin,
+  sprintToolsPlugin,
+  taskToolsPlugin,
+  taskWorkflowPlugin
+] as const;

package/src/mcp/plugins/index.ts

@@ -0,0 +1,21 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Barrel for Sprintdock MCP tool plugins and shared registration helpers.
+ */
+export { contextToolsPlugin } from "./context-tools.plugin.js";
+export { defaultSprintdockMcpPlugins } from "./default-plugins.js";
+export {
+  createSprintdockMcpToolKit,
+  type SprintdockMcpToolKit
+} from "./mcp-tool-kit.js";
+export { planToolsPlugin } from "./plan-tools.plugin.js";
+export { sprintToolsPlugin } from "./sprint-tools.plugin.js";
+export { taskToolsPlugin } from "./task-tools.plugin.js";
+export { taskWorkflowPlugin } from "./task-workflow.plugin.js";
+export type {
+  RegisterSprintdockMcpToolsOptions,
+  SprintdockMcpPluginContext,
+  SprintdockMcpToolDependencies,
+  SprintdockMcpToolPlugin
+} from "./types.js";