@sprintdock/backend 0.4.2

package/src/http/routes/v1/index.ts

@@ -0,0 +1,39 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Composes all `/api/v1` routers onto a single Express Router.
+ */
+import { Router } from "express";
+import type { ServiceSet } from "../../../application/container.js";
+import { PlanController } from "../../controllers/plan.controller.js";
+import { SprintController } from "../../controllers/sprint.controller.js";
+import { TaskController } from "../../controllers/task.controller.js";
+import { HealthController } from "../../controllers/health.controller.js";
+import { registerPlanRoutes } from "./plan.routes.js";
+import { registerSprintRoutes } from "./sprint.routes.js";
+import { registerTaskRoutes } from "./task.routes.js";
+
+/**
+ * Builds the `/api/v1` router with health, plans, sprints, and tasks.
+ */
+export function createV1Router(services: ServiceSet): Router {
+  const router = Router();
+  const health = new HealthController();
+  const planController = new PlanController(
+    services.planService,
+    services.sprintService,
+    services.taskService
+  );
+  const sprintController = new SprintController(
+    services.sprintService,
+    services.taskService
+  );
+  const taskController = new TaskController(services.taskService);
+
+  router.get("/health", health.check);
+  registerPlanRoutes(router, planController);
+  registerSprintRoutes(router, sprintController);
+  registerTaskRoutes(router, taskController);
+
+  return router;
+}

package/src/http/routes/v1/plan.routes.ts

@@ -0,0 +1,51 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Versioned routes for plans and execution context.
+ */
+import { Router } from "express";
+import type { PlanController } from "../../controllers/plan.controller.js";
+import { validate } from "../../middleware/validate.js";
+import {
+  createPlanBody,
+  idOrSlugParams,
+  updatePlanBody
+} from "./schemas.js";
+
+/**
+ * Registers plan and execution-context endpoints on {@link Router}.
+ */
+export function registerPlanRoutes(router: Router, c: PlanController): void {
+  router.get("/dashboard-overview", (req, res, next) =>
+    void c.getDashboardOverview(req, res, next)
+  );
+  router.get("/plans", (req, res, next) => void c.list(req, res, next));
+  router.post(
+    "/plans",
+    validate({ body: createPlanBody }),
+    (req, res, next) => void c.create(req, res, next)
+  );
+  router.get(
+    "/plans/:idOrSlug/analytics",
+    validate({ params: idOrSlugParams }),
+    (req, res, next) => void c.getPlanAnalytics(req, res, next)
+  );
+  router.get(
+    "/plans/:idOrSlug",
+    validate({ params: idOrSlugParams }),
+    (req, res, next) => void c.getOne(req, res, next)
+  );
+  router.patch(
+    "/plans/:idOrSlug",
+    validate({ params: idOrSlugParams, body: updatePlanBody }),
+    (req, res, next) => void c.update(req, res, next)
+  );
+  router.post(
+    "/plans/:idOrSlug/activate",
+    validate({ params: idOrSlugParams }),
+    (req, res, next) => void c.activate(req, res, next)
+  );
+  router.get("/execution-context", (req, res, next) =>
+    void c.getExecutionContext(req, res, next)
+  );
+}

package/src/http/routes/v1/schemas.ts

@@ -0,0 +1,175 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Shared Zod schemas for v1 REST validation.
+ */
+import { z } from "zod";
+
+export const planStatusSchema = z.enum([
+  "draft",
+  "active",
+  "completed",
+  "archived"
+]);
+
+export const sprintStatusSchema = z.enum([
+  "planned",
+  "active",
+  "completed",
+  "archived"
+]);
+
+export const taskStatusSchema = z.enum([
+  "todo",
+  "in_progress",
+  "blocked",
+  "done"
+]);
+
+export const taskPrioritySchema = z.enum([
+  "low",
+  "medium",
+  "high",
+  "critical"
+]);
+
+export const idOrSlugParams = z.object({
+  idOrSlug: z.string().min(1)
+});
+
+export const planIdParams = z.object({
+  planId: z.string().min(1)
+});
+
+export const sprintIdParams = z.object({
+  sprintId: z.string().min(1)
+});
+
+export const sprintIdPathParams = z.object({
+  id: z.string().min(1)
+});
+
+export const taskIdPathParams = z.object({
+  id: z.string().min(1)
+});
+
+export const createPlanBody = z.object({
+  slug: z.string().min(1),
+  title: z.string().min(1),
+  description: z.string().nullable().optional(),
+  markdownContent: z.string().nullable().optional()
+});
+
+export const updatePlanBody = z
+  .object({
+    title: z.string().min(1).optional(),
+    description: z.string().nullable().optional(),
+    markdownContent: z.string().nullable().optional(),
+    status: planStatusSchema.optional()
+  })
+  .refine(
+    (v) =>
+      v.title !== undefined ||
+      v.description !== undefined ||
+      v.markdownContent !== undefined ||
+      v.status !== undefined,
+    { message: "At least one field is required" }
+  );
+
+export const createSprintBody = z.object({
+  slug: z.string().min(1),
+  name: z.string().min(1),
+  goal: z.string(),
+  markdownContent: z.string().nullable().optional(),
+  order: z.number().int().optional(),
+  startDate: z.string().nullable().optional(),
+  endDate: z.string().nullable().optional()
+});
+
+export const updateSprintBody = z
+  .object({
+    name: z.string().min(1).optional(),
+    goal: z.string().optional(),
+    markdownContent: z.string().nullable().optional(),
+    startDate: z.string().nullable().optional(),
+    endDate: z.string().nullable().optional(),
+    order: z.number().int().optional()
+  })
+  .refine(
+    (v) =>
+      v.name !== undefined ||
+      v.goal !== undefined ||
+      v.markdownContent !== undefined ||
+      v.startDate !== undefined ||
+      v.endDate !== undefined ||
+      v.order !== undefined,
+    { message: "At least one field is required" }
+  );
+
+export const updateSprintStatusBody = z.object({
+  status: sprintStatusSchema
+});
+
+export const taskListQuery = z.object({
+  status: taskStatusSchema.optional(),
+  priority: taskPrioritySchema.optional(),
+  assignee: z.string().optional()
+});
+
+export const taskTouchedFileTypeSchema = z.enum([
+  "test",
+  "implementation",
+  "doc",
+  "config",
+  "other"
+]);
+
+export const taskTouchedFileItemSchema = z.object({
+  path: z.string().min(1).max(2048),
+  fileType: taskTouchedFileTypeSchema
+});
+
+export const createTaskBody = z.object({
+  title: z.string().min(1),
+  priority: taskPrioritySchema,
+  description: z.string().nullable().optional(),
+  order: z.number().int().optional(),
+  assignee: z.string().nullable().optional(),
+  tags: z.array(z.string()).nullable().optional(),
+  dependsOnTaskIds: z.array(z.string().min(1)).optional(),
+  touchedFiles: z.array(taskTouchedFileItemSchema).optional()
+});
+
+export const updateTaskBody = z
+  .object({
+    title: z.string().min(1).optional(),
+    description: z.string().nullable().optional(),
+    priority: taskPrioritySchema.optional(),
+    assignee: z.string().nullable().optional(),
+    tags: z.array(z.string()).nullable().optional(),
+    order: z.number().int().optional(),
+    touchedFiles: z.array(taskTouchedFileItemSchema).optional()
+  })
+  .refine(
+    (v) =>
+      v.title !== undefined ||
+      v.description !== undefined ||
+      v.priority !== undefined ||
+      v.assignee !== undefined ||
+      v.tags !== undefined ||
+      v.order !== undefined ||
+      v.touchedFiles !== undefined,
+    { message: "At least one field is required" }
+  );
+
+export const updateTaskStatusBody = z.object({
+  status: taskStatusSchema
+});
+
+export const assignTaskBody = z.object({
+  assignee: z.union([z.string().min(1), z.null()])
+});
+
+export const moveTaskBody = z.object({
+  targetSprintId: z.string().min(1)
+});

package/src/http/routes/v1/sprint.routes.ts

@@ -0,0 +1,49 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Versioned routes for sprints.
+ */
+import { Router } from "express";
+import type { SprintController } from "../../controllers/sprint.controller.js";
+import { validate } from "../../middleware/validate.js";
+import {
+  createSprintBody,
+  planIdParams,
+  sprintIdPathParams,
+  updateSprintBody,
+  updateSprintStatusBody
+} from "./schemas.js";
+
+/**
+ * Registers sprint endpoints on {@link Router}.
+ */
+export function registerSprintRoutes(
+  router: Router,
+  c: SprintController
+): void {
+  router.get(
+    "/plans/:planId/sprints",
+    validate({ params: planIdParams }),
+    (req, res, next) => void c.listByPlan(req, res, next)
+  );
+  router.post(
+    "/plans/:planId/sprints",
+    validate({ params: planIdParams, body: createSprintBody }),
+    (req, res, next) => void c.create(req, res, next)
+  );
+  router.get(
+    "/sprints/:id",
+    validate({ params: sprintIdPathParams }),
+    (req, res, next) => void c.getOne(req, res, next)
+  );
+  router.patch(
+    "/sprints/:id",
+    validate({ params: sprintIdPathParams, body: updateSprintBody }),
+    (req, res, next) => void c.patch(req, res, next)
+  );
+  router.patch(
+    "/sprints/:id/status",
+    validate({ params: sprintIdPathParams, body: updateSprintStatusBody }),
+    (req, res, next) => void c.updateStatus(req, res, next)
+  );
+}

package/src/http/routes/v1/task.routes.ts

@@ -0,0 +1,64 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Versioned routes for tasks.
+ */
+import { Router } from "express";
+import type { TaskController } from "../../controllers/task.controller.js";
+import { validate } from "../../middleware/validate.js";
+import {
+  assignTaskBody,
+  createTaskBody,
+  moveTaskBody,
+  sprintIdParams,
+  taskIdPathParams,
+  taskListQuery,
+  updateTaskBody,
+  updateTaskStatusBody
+} from "./schemas.js";
+
+/**
+ * Registers task endpoints on {@link Router}.
+ */
+export function registerTaskRoutes(router: Router, c: TaskController): void {
+  router.get(
+    "/sprints/:sprintId/tasks",
+    validate({ params: sprintIdParams, query: taskListQuery }),
+    (req, res, next) => void c.listBySprint(req, res, next)
+  );
+  router.post(
+    "/sprints/:sprintId/tasks",
+    validate({ params: sprintIdParams, body: createTaskBody }),
+    (req, res, next) => void c.create(req, res, next)
+  );
+  router.get(
+    "/tasks/:id",
+    validate({ params: taskIdPathParams }),
+    (req, res, next) => void c.getOne(req, res, next)
+  );
+  router.patch(
+    "/tasks/:id",
+    validate({ params: taskIdPathParams, body: updateTaskBody }),
+    (req, res, next) => void c.patch(req, res, next)
+  );
+  router.patch(
+    "/tasks/:id/status",
+    validate({ params: taskIdPathParams, body: updateTaskStatusBody }),
+    (req, res, next) => void c.updateStatus(req, res, next)
+  );
+  router.patch(
+    "/tasks/:id/assign",
+    validate({ params: taskIdPathParams, body: assignTaskBody }),
+    (req, res, next) => void c.assign(req, res, next)
+  );
+  router.post(
+    "/tasks/:id/move",
+    validate({ params: taskIdPathParams, body: moveTaskBody }),
+    (req, res, next) => void c.move(req, res, next)
+  );
+  router.delete(
+    "/tasks/:id",
+    validate({ params: taskIdPathParams }),
+    (req, res, next) => void c.remove(req, res, next)
+  );
+}

package/src/index.ts

@@ -0,0 +1,34 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Public API barrel for Sprintdock backend (SQLite, REST, MCP).
+ */
+
+export { createApplicationServices, type ServiceSet } from "./application/container.js";
+export {
+  createRepositories,
+  type RepositorySet,
+  type StorageAdapterType,
+  type StorageConfig
+} from "./infrastructure/repositories/repository-factory.js";
+export { createHttpApp, type HttpAppOptions } from "./http/app-factory.js";
+export {
+  runSprintdockMcpServer,
+  SprintdockMcpRuntime,
+  type SprintdockMcpRuntimeOptions,
+  type SprintdockMcpTransportMode
+} from "./mcp/sprintdock-mcp-runtime.js";
+export { bootstrapSprintdockSqlite } from "./mcp/bootstrap-sprintdock-sqlite.js";
+export type { SprintdockSqliteBootstrapResult } from "./mcp/bootstrap-sprintdock-sqlite.js";
+export {
+  createSprintdockMcpToolKit,
+  defaultSprintdockMcpPlugins,
+  registerSprintdockMcpTools
+} from "./mcp/register-sprintdock-mcp-tools.js";
+export type {
+  RegisterSprintdockMcpToolsOptions,
+  SprintdockMcpPluginContext,
+  SprintdockMcpToolDependencies,
+  SprintdockMcpToolKit,
+  SprintdockMcpToolPlugin
+} from "./mcp/register-sprintdock-mcp-tools.js";

package/src/infrastructure/observability/audit-log.ts

@@ -0,0 +1,34 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Structured audit logger contract for mutating MCP tool operations.
+ */
+
+/**
+ * Structured audit event model.
+ */
+export interface AuditEvent {
+  action: string;
+  principalId: string;
+  transport: "stdio" | "http";
+  resourceId?: string;
+  correlationId: string;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * Contract for audit event emission.
+ */
+export interface AuditLog {
+  write(event: AuditEvent): void;
+}
+
+/**
+ * Console-backed audit logger for local and default runtime.
+ */
+export class ConsoleAuditLog implements AuditLog {
+  /** @inheritdoc */
+  public write(event: AuditEvent): void {
+    process.stderr.write(`[audit] ${JSON.stringify(event)}\n`);
+  }
+}

package/src/infrastructure/observability/request-correlation.ts

@@ -0,0 +1,20 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Correlation id provider for request tracking and diagnostics.
+ */
+import { randomUUID } from "node:crypto";
+
+/**
+ * Correlation id provider used across tool and resource handlers.
+ */
+export class RequestCorrelation {
+  /**
+   * Creates a new unique correlation identifier.
+   *
+   * @returns Correlation id string.
+   */
+  public create(): string {
+    return randomUUID();
+  }
+}

package/src/infrastructure/repositories/drizzle/drizzle-plan.repository.ts

@@ -0,0 +1,138 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: SQLite-backed PlanRepository using Drizzle ORM.
+ */
+import { asc, eq } from "drizzle-orm";
+import { randomUUID } from "node:crypto";
+import type {
+  CreatePlanInput,
+  Plan,
+  UpdatePlanInput
+} from "../../../domain/entities/plan.entity";
+import type { PlanRepository } from "../../../domain/repositories/plan.repository";
+import { StorageError } from "../../../errors/backend-errors.js";
+import { plans } from "../../../db/schema/plans";
+import type { DrizzleSqliteDb } from "./sqlite-db";
+import { toPlanEntity } from "./row-mappers";
+
+/**
+ * Persists plans with Drizzle SQLite.
+ */
+export class DrizzlePlanRepository implements PlanRepository {
+  public constructor(private readonly db: DrizzleSqliteDb) {}
+
+  /** @inheritdoc */
+  public async create(input: CreatePlanInput): Promise<Plan> {
+    const id = randomUUID();
+    const now = new Date().toISOString();
+    this.db
+      .insert(plans)
+      .values({
+        id,
+        slug: input.slug,
+        title: input.title,
+        description: input.description ?? null,
+        markdownContent: input.markdownContent ?? null,
+        status: "draft",
+        isActive: false,
+        createdAt: now,
+        updatedAt: now
+      })
+      .run();
+    const created = this.db.select().from(plans).where(eq(plans.id, id)).get();
+    if (!created) {
+      throw new StorageError("Failed to read plan after insert");
+    }
+    return toPlanEntity(created);
+  }
+
+  /** @inheritdoc */
+  public async findById(id: string): Promise<Plan | null> {
+    const row = this.db.select().from(plans).where(eq(plans.id, id)).get();
+    return row ? toPlanEntity(row) : null;
+  }
+
+  /** @inheritdoc */
+  public async findBySlug(slug: string): Promise<Plan | null> {
+    const row = this.db.select().from(plans).where(eq(plans.slug, slug)).get();
+    return row ? toPlanEntity(row) : null;
+  }
+
+  /** @inheritdoc */
+  public async findActive(): Promise<Plan | null> {
+    const row = this.db
+      .select()
+      .from(plans)
+      .where(eq(plans.isActive, true))
+      .orderBy(asc(plans.createdAt))
+      .limit(1)
+      .get();
+    return row ? toPlanEntity(row) : null;
+  }
+
+  /** @inheritdoc */
+  public async list(): Promise<Plan[]> {
+    const rows = this.db
+      .select()
+      .from(plans)
+      .orderBy(asc(plans.createdAt))
+      .all();
+    return rows.map(toPlanEntity);
+  }
+
+  /** @inheritdoc */
+  public async update(
+    id: string,
+    input: UpdatePlanInput
+  ): Promise<Plan | null> {
+    const existing = await this.findById(id);
+    if (!existing) {
+      return null;
+    }
+    const now = new Date().toISOString();
+    this.db
+      .update(plans)
+      .set({
+        title: input.title ?? existing.title,
+        description:
+          input.description !== undefined
+            ? input.description
+            : existing.description,
+        markdownContent:
+          input.markdownContent !== undefined
+            ? input.markdownContent
+            : existing.markdownContent,
+        status: input.status ?? existing.status,
+        updatedAt: now
+      })
+      .where(eq(plans.id, id))
+      .run();
+    return this.findById(id);
+  }
+
+  /** @inheritdoc */
+  public async setActive(id: string): Promise<void> {
+    this.db.transaction((tx) => {
+      tx.update(plans).set({ isActive: false }).run();
+      tx
+        .update(plans)
+        .set({
+          isActive: true,
+          updatedAt: new Date().toISOString()
+        })
+        .where(eq(plans.id, id))
+        .run();
+    });
+  }
+
+  /** @inheritdoc */
+  public async delete(id: string): Promise<boolean> {
+    const before = await this.findById(id);
+    if (!before) {
+      return false;
+    }
+    this.db.delete(plans).where(eq(plans.id, id)).run();
+    return (await this.findById(id)) === null;
+  }
+}