@sprintdock/backend 0.4.2

package/src/http/app-factory.ts

@@ -0,0 +1,55 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Express application factory wiring middleware and versioned API routes.
+ */
+import express, { type Express } from "express";
+import type { ServiceSet } from "../application/container.js";
+import { createV1Router } from "./routes/v1/index.js";
+import { corsMiddleware } from "./middleware/cors.js";
+import { errorHandler } from "./middleware/error-handler.js";
+import { requestIdMiddleware } from "./middleware/request-id.js";
+
+export interface HttpAppOptions {
+  /** When true (default), applies permissive CORS. */
+  cors?: boolean;
+  /** Forwarded to Express `trust proxy`. */
+  trustProxy?: boolean;
+}
+
+/**
+ * Assembles JSON parsing, optional CORS, request id propagation, `GET /` discovery payload, `/api/v1` routes, and the error handler.
+ */
+export function createHttpApp(
+  services: ServiceSet,
+  options?: HttpAppOptions
+): Express {
+  const app = express();
+
+  if (options?.trustProxy) {
+    app.set("trust proxy", true);
+  }
+
+  app.use(express.json());
+  if (options?.cors !== false) {
+    app.use(corsMiddleware());
+  }
+  app.use(requestIdMiddleware);
+
+  app.get("/", (_req, res) => {
+    res.type("application/json").status(200).send({
+      service: "sprintdock-rest",
+      message:
+        "JSON API lives under /api/v1. Open /api/v1/health to verify the server.",
+      apiBase: "/api/v1",
+      health: "/api/v1/health",
+      webUi:
+        "The browser UI is a separate Vite app (@sprintdock/webui); run pnpm dev:web with SPRINTDOCK_API_BASE_URL pointing at this origin."
+    });
+  });
+
+  app.use("/api/v1", createV1Router(services));
+  app.use(errorHandler);
+
+  return app;
+}

package/src/http/controllers/health.controller.ts

@@ -0,0 +1,33 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Lightweight health probe for load balancers and smoke tests.
+ */
+import { readFileSync } from "node:fs";
+import type { NextFunction, Request, Response } from "express";
+
+function readPackageVersion(): string {
+  const path = new URL("../../../package.json", import.meta.url);
+  const raw = readFileSync(path, "utf8");
+  const pkg = JSON.parse(raw) as { version?: string };
+  return pkg.version ?? "0.0.0";
+}
+
+/**
+ * Exposes process liveness and package version.
+ */
+export class HealthController {
+  private readonly version = readPackageVersion();
+
+  public check = (
+    _req: Request,
+    res: Response,
+    _next: NextFunction
+  ): void => {
+    res.json({
+      status: "ok",
+      version: this.version,
+      timestamp: new Date().toISOString()
+    });
+  };
+}

package/src/http/controllers/plan.controller.ts

@@ -0,0 +1,153 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: HTTP handlers for plans and execution context.
+ */
+import type { NextFunction, Request, Response } from "express";
+import type { PlanService } from "../../application/plan.service.js";
+import type { SprintService } from "../../application/sprint.service.js";
+import type { TaskService } from "../../application/task.service.js";
+import { NotFoundError } from "../../errors/backend-errors.js";
+
+/**
+ * Thin adapter over {@link PlanService}; uses {@link SprintService} for execution context
+ * and {@link TaskService} for plan-scoped analytics.
+ */
+export class PlanController {
+  public constructor(
+    private readonly planService: PlanService,
+    private readonly sprintService: SprintService,
+    private readonly taskService: TaskService
+  ) {}
+
+  public list = async (
+    _req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const plans = await this.planService.listPlans();
+      res.json({ plans });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public create = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const plan = await this.planService.createPlan(req.body);
+      res.status(201).json({ plan });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public getPlanAnalytics = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { idOrSlug } = req.params as { idOrSlug: string };
+      const analytics = await this.taskService.getPlanSprintTaskAnalytics(
+        idOrSlug
+      );
+      res.json({ analytics });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public getOne = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { idOrSlug } = req.params as { idOrSlug: string };
+      const plan = await this.planService.getPlan(idOrSlug);
+      res.json({ plan });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public update = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { idOrSlug } = req.params as { idOrSlug: string };
+      const plan = await this.planService.updatePlan(idOrSlug, req.body);
+      res.json({ plan });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public activate = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { idOrSlug } = req.params as { idOrSlug: string };
+      await this.planService.setActivePlan(idOrSlug);
+      res.json({ ok: true });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public getExecutionContext = async (
+    _req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const plan = await this.planService.getActivePlan();
+      const sprints = await this.sprintService.listSprints(plan.id);
+      const activeSprints = sprints.filter((s) => s.status === "active");
+      res.json({ plan, activeSprints });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  /** Composes execution context with global task throughput for the dashboard. */
+  public getDashboardOverview = async (
+    _req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const throughput = await this.taskService.getGlobalTaskThroughput();
+      let plan;
+      try {
+        plan = await this.planService.getActivePlan();
+      } catch (e) {
+        if (e instanceof NotFoundError) {
+          res.json({
+            execution: { plan: null, activeSprints: [] },
+            throughput
+          });
+          return;
+        }
+        throw e;
+      }
+      const sprints = await this.sprintService.listSprints(plan.id);
+      const activeSprints = sprints.filter((s) => s.status === "active");
+      res.json({
+        execution: { plan, activeSprints },
+        throughput
+      });
+    } catch (e) {
+      next(e);
+    }
+  };
+}

package/src/http/controllers/sprint.controller.ts

@@ -0,0 +1,111 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: HTTP handlers for sprints scoped to plans.
+ */
+import type { NextFunction, Request, Response } from "express";
+import type { SprintService } from "../../application/sprint.service.js";
+import type { TaskService } from "../../application/task.service.js";
+import type { SprintStatus } from "../../domain/entities/sprint.entity";
+
+/**
+ * Thin adapter combining sprint reads with task listings for detail responses.
+ */
+export class SprintController {
+  public constructor(
+    private readonly sprintService: SprintService,
+    private readonly taskService: TaskService
+  ) {}
+
+  public listByPlan = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { planId } = req.params as { planId: string };
+      const sprints = await this.sprintService.listSprints(planId);
+      res.json({ sprints });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public create = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { planId } = req.params as { planId: string };
+      const sprint = await this.sprintService.createSprint(planId, {
+        ...req.body,
+        planId
+      });
+      res.status(201).json({ sprint });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public getOne = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const sprint = await this.sprintService.getSprint(id);
+      const tasks = await this.taskService.listTasks(sprint.id);
+      res.json({ sprint, tasks });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public patch = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const b = req.body as {
+        name?: string;
+        goal?: string;
+        markdownContent?: string | null;
+        startDate?: string | null;
+        endDate?: string | null;
+        order?: number;
+      };
+      const sprint = await this.sprintService.updateSprint(id, {
+        ...(b.name !== undefined ? { name: b.name } : {}),
+        ...(b.goal !== undefined ? { goal: b.goal } : {}),
+        ...(b.markdownContent !== undefined
+          ? { markdownContent: b.markdownContent }
+          : {}),
+        ...(b.startDate !== undefined ? { startDate: b.startDate } : {}),
+        ...(b.endDate !== undefined ? { endDate: b.endDate } : {}),
+        ...(b.order !== undefined ? { order: b.order } : {})
+      });
+      res.json({ sprint });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public updateStatus = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const { status } = req.body as { status: SprintStatus };
+      const sprint = await this.sprintService.updateSprintStatus(id, status);
+      res.json({ sprint });
+    } catch (e) {
+      next(e);
+    }
+  };
+}

package/src/http/controllers/task.controller.ts

@@ -0,0 +1,158 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: HTTP handlers for tasks within sprints.
+ */
+import type { NextFunction, Request, Response } from "express";
+import type {
+  TaskFieldUpdateInput,
+  TaskService
+} from "../../application/task.service.js";
+import type { TaskPriority, TaskStatus } from "../../domain/entities/task.entity";
+
+/**
+ * Thin adapter over {@link TaskService}.
+ */
+export class TaskController {
+  public constructor(private readonly taskService: TaskService) {}
+
+  public listBySprint = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { sprintId } = req.params as { sprintId: string };
+      const q = (req.validatedQuery ?? {}) as {
+        status?: TaskStatus;
+        priority?: TaskPriority;
+        assignee?: string;
+      };
+      const filter =
+        q.status || q.priority || q.assignee !== undefined
+          ? {
+              ...(q.status ? { status: q.status } : {}),
+              ...(q.priority ? { priority: q.priority } : {}),
+              ...(q.assignee !== undefined ? { assignee: q.assignee } : {})
+            }
+          : undefined;
+      const tasks = await this.taskService.listTasks(sprintId, undefined, filter);
+      res.json({ tasks });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public create = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { sprintId } = req.params as { sprintId: string };
+      const task = await this.taskService.createTask(
+        { ...req.body, sprintId },
+        undefined
+      );
+      res.status(201).json({ task });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public getOne = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const task = await this.taskService.getTask(id);
+      res.json({ task });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public patch = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const b = req.body as TaskFieldUpdateInput;
+      const task = await this.taskService.updateTask(id, {
+        ...(b.title !== undefined ? { title: b.title } : {}),
+        ...(b.description !== undefined ? { description: b.description } : {}),
+        ...(b.priority !== undefined ? { priority: b.priority } : {}),
+        ...(b.assignee !== undefined ? { assignee: b.assignee } : {}),
+        ...(b.tags !== undefined ? { tags: b.tags } : {}),
+        ...(b.order !== undefined ? { order: b.order } : {}),
+        ...(b.touchedFiles !== undefined ? { touchedFiles: b.touchedFiles } : {})
+      });
+      res.json({ task });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public updateStatus = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const { status } = req.body as { status: TaskStatus };
+      const task = await this.taskService.updateTaskStatus(id, status);
+      res.json({ task });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public assign = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const { assignee } = req.body as { assignee: string | null };
+      const task = await this.taskService.assignTask(id, assignee);
+      res.json({ task });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public move = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      const { targetSprintId } = req.body as { targetSprintId: string };
+      const task = await this.taskService.moveTask(id, targetSprintId);
+      res.json({ task });
+    } catch (e) {
+      next(e);
+    }
+  };
+
+  public remove = async (
+    req: Request,
+    res: Response,
+    next: NextFunction
+  ): Promise<void> => {
+    try {
+      const { id } = req.params as { id: string };
+      await this.taskService.deleteTask(id);
+      res.json({ deleted: true });
+    } catch (e) {
+      next(e);
+    }
+  };
+}

package/src/http/express-augmentation.d.ts

@@ -0,0 +1,20 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Express Request fields set by HTTP middleware.
+ */
+declare global {
+  namespace Express {
+    interface Request {
+      /** Correlation id from {@link X-Request-Id} or generated in middleware. */
+      id: string;
+      /**
+       * Populated by {@link validate} when a query schema is provided. Express 5 keeps
+       * {@link Request.query} read-only, so parsed query values live here.
+       */
+      validatedQuery?: Record<string, unknown>;
+    }
+  }
+}
+
+export {};

package/src/http/middleware/cors.ts

@@ -0,0 +1,41 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Configurable CORS middleware for REST responses and preflight.
+ */
+
+import type { NextFunction, Request, Response } from "express";
+
+export interface CorsOptions {
+  /** Allowed Origin header value. Default `*`. */
+  origin?: string;
+  /** Value for Access-Control-Allow-Methods. */
+  methods?: string;
+  /** Value for Access-Control-Allow-Headers. */
+  allowedHeaders?: string;
+}
+
+const DEFAULT_METHODS = "GET,POST,PATCH,DELETE,OPTIONS,HEAD";
+const DEFAULT_ALLOWED_HEADERS = "Content-Type, Authorization, X-Request-Id";
+
+/**
+ * Applies CORS headers and answers OPTIONS with 204.
+ */
+export function corsMiddleware(options?: CorsOptions) {
+  const origin = options?.origin ?? "*";
+  const methods = options?.methods ?? DEFAULT_METHODS;
+  const allowedHeaders = options?.allowedHeaders ?? DEFAULT_ALLOWED_HEADERS;
+
+  return (req: Request, res: Response, next: NextFunction): void => {
+    res.setHeader("Access-Control-Allow-Origin", origin);
+    res.setHeader("Access-Control-Allow-Methods", methods);
+    res.setHeader("Access-Control-Allow-Headers", allowedHeaders);
+
+    if (req.method === "OPTIONS") {
+      res.status(204).end();
+      return;
+    }
+
+    next();
+  };
+}

package/src/http/middleware/error-handler.ts

@@ -0,0 +1,50 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Express error middleware mapping domain errors to JSON responses.
+ */
+import type { NextFunction, Request, Response } from "express";
+import { BackendError } from "../../errors/backend-errors.js";
+
+/**
+ * Maps {@link BackendError} subclasses to HTTP status; unknown errors become 500.
+ * In non-production, includes `stack` on the error payload for unknown failures.
+ */
+export function errorHandler(
+  err: unknown,
+  _req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  if (res.headersSent) {
+    next(err);
+    return;
+  }
+
+  if (err instanceof BackendError) {
+    res.status(err.statusCode).json({
+      error: {
+        message: err.message,
+        statusCode: err.statusCode
+      }
+    });
+    return;
+  }
+
+  const message =
+    err instanceof Error ? err.message : "Internal server error";
+  const payload: {
+    error: { message: string; statusCode: number; stack?: string };
+  } = {
+    error: {
+      message,
+      statusCode: 500
+    }
+  };
+
+  if (process.env.NODE_ENV !== "production" && err instanceof Error && err.stack) {
+    payload.error.stack = err.stack;
+  }
+
+  res.status(500).json(payload);
+}

package/src/http/middleware/request-id.ts

@@ -0,0 +1,28 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Propagates X-Request-Id through the request lifecycle and response headers.
+ */
+import { randomUUID } from "node:crypto";
+import type { NextFunction, Request, Response } from "express";
+
+const HEADER = "x-request-id";
+
+/**
+ * Uses incoming {@link HEADER} when present; otherwise generates a UUID.
+ * Sets {@link Request.id} and echoes the id on the response.
+ */
+export function requestIdMiddleware(
+  req: Request,
+  res: Response,
+  next: NextFunction
+): void {
+  const incoming = req.get(HEADER);
+  const id =
+    typeof incoming === "string" && incoming.trim().length > 0
+      ? incoming.trim()
+      : randomUUID();
+  req.id = id;
+  res.setHeader("X-Request-Id", id);
+  next();
+}

package/src/http/middleware/validate.ts

@@ -0,0 +1,54 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Zod-based validation middleware for body, query, and route params.
+ */
+import type { NextFunction, Request, Response } from "express";
+import { z, type ZodTypeAny } from "zod";
+
+export interface ValidateSchemas {
+  body?: ZodTypeAny;
+  query?: ZodTypeAny;
+  params?: ZodTypeAny;
+}
+
+/**
+ * Returns middleware that parses {@link Request.body}, {@link Request.query}, and/or
+ * {@link Request.params} with the given Zod schemas and replaces them with parsed values.
+ */
+export function validate(schemas: ValidateSchemas) {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    try {
+      if (schemas.body) {
+        req.body = schemas.body.parse(req.body) as Request["body"];
+      }
+      if (schemas.query) {
+        const rawQuery =
+          req.query && typeof req.query === "object"
+            ? { ...(req.query as Record<string, unknown>) }
+            : {};
+        req.validatedQuery = schemas.query.parse(rawQuery) as Record<
+          string,
+          unknown
+        >;
+      }
+      if (schemas.params) {
+        req.params = schemas.params.parse({
+          ...(req.params as Record<string, unknown>)
+        }) as Request["params"];
+      }
+      next();
+    } catch (e) {
+      if (e instanceof z.ZodError) {
+        res.status(400).json({
+          error: {
+            message: "Validation failed",
+            details: e.issues
+          }
+        });
+        return;
+      }
+      next(e);
+    }
+  };
+}