@sprintdock/backend 0.4.2

package/src/db/schema/tasks.ts

@@ -0,0 +1,62 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Drizzle schema for tasks and task dependency edges.
+ */
+import {
+  sqliteTable,
+  text,
+  integer,
+  primaryKey,
+  uniqueIndex
+} from "drizzle-orm/sqlite-core";
+import { sprints } from "./sprints";
+
+export const tasks = sqliteTable("tasks", {
+  id: text("id").primaryKey(),
+  sprintId: text("sprint_id")
+    .notNull()
+    .references(() => sprints.id, { onDelete: "cascade" }),
+  title: text("title").notNull(),
+  description: text("description"),
+  status: text("status").notNull(),
+  priority: text("priority").notNull(),
+  taskOrder: integer("order").notNull().default(0),
+  assignee: text("assignee"),
+  tags: text("tags", { mode: "json" }).$type<string[]>(),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull()
+});
+
+export const taskDependencies = sqliteTable(
+  "task_dependencies",
+  {
+    taskId: text("task_id")
+      .notNull()
+      .references(() => tasks.id, { onDelete: "cascade" }),
+    dependsOnTaskId: text("depends_on_task_id")
+      .notNull()
+      .references(() => tasks.id, { onDelete: "cascade" })
+  },
+  (t) => ({
+    pk: primaryKey({ columns: [t.taskId, t.dependsOnTaskId] })
+  })
+);
+
+export const taskTouchedFiles = sqliteTable(
+  "task_touched_files",
+  {
+    id: text("id").primaryKey(),
+    taskId: text("task_id")
+      .notNull()
+      .references(() => tasks.id, { onDelete: "cascade" }),
+    path: text("path").notNull(),
+    fileType: text("file_type").notNull()
+  },
+  (t) => ({
+    taskPathUnique: uniqueIndex("task_touched_files_task_id_path_unique").on(
+      t.taskId,
+      t.path
+    )
+  })
+);

package/src/domain/entities/index.ts

@@ -0,0 +1,30 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Barrel export for domain entities and value types.
+ */
+
+export type {
+  CreatePlanInput,
+  Plan,
+  PlanStatus,
+  UpdatePlanInput
+} from "./plan.entity";
+export type {
+  CreateSprintInput,
+  Sprint,
+  SprintStatus,
+  UpdateSprintInput
+} from "./sprint.entity";
+export type {
+  CreateTaskInput,
+  MoveTaskInput,
+  Task,
+  TaskDependency,
+  TaskPriority,
+  TaskStatus,
+  TaskTouchedFile,
+  TaskTouchedFileInput,
+  TaskTouchedFileType,
+  UpdateTaskInput
+} from "./task.entity";

package/src/domain/entities/plan.entity.ts

@@ -0,0 +1,33 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Plan aggregate root types for the domain layer.
+ */
+
+export type PlanStatus = "draft" | "active" | "completed" | "archived";
+
+export interface Plan {
+  id: string;
+  slug: string;
+  title: string;
+  description: string | null;
+  markdownContent: string | null;
+  status: PlanStatus;
+  isActive: boolean;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreatePlanInput {
+  slug: string;
+  title: string;
+  description?: string | null;
+  markdownContent?: string | null;
+}
+
+export interface UpdatePlanInput {
+  title?: string;
+  description?: string | null;
+  markdownContent?: string | null;
+  status?: PlanStatus;
+}

package/src/domain/entities/sprint.entity.ts

@@ -0,0 +1,44 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Sprint entity types scoped to a plan.
+ */
+
+export type SprintStatus = "planned" | "active" | "completed" | "archived";
+
+export interface Sprint {
+  id: string;
+  slug: string;
+  planId: string;
+  name: string;
+  goal: string;
+  /** Optional sprint notes / retro / scope — GitHub-flavored markdown. */
+  markdownContent: string | null;
+  status: SprintStatus;
+  order: number;
+  startDate: string | null;
+  endDate: string | null;
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface CreateSprintInput {
+  slug: string;
+  planId: string;
+  name: string;
+  goal: string;
+  markdownContent?: string | null;
+  order?: number;
+  startDate?: string | null;
+  endDate?: string | null;
+}
+
+export interface UpdateSprintInput {
+  name?: string;
+  goal?: string;
+  markdownContent?: string | null;
+  status?: SprintStatus;
+  order?: number;
+  startDate?: string | null;
+  endDate?: string | null;
+}

package/src/domain/entities/task.entity.ts

@@ -0,0 +1,80 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Task and dependency types for the domain layer.
+ */
+
+export type TaskStatus = "todo" | "in_progress" | "blocked" | "done";
+
+export type TaskPriority = "low" | "medium" | "high" | "critical";
+
+/** Persisted in `task_touched_files.file_type`. */
+export type TaskTouchedFileType =
+  | "test"
+  | "implementation"
+  | "doc"
+  | "config"
+  | "other";
+
+export interface TaskTouchedFile {
+  id: string;
+  taskId: string;
+  path: string;
+  fileType: TaskTouchedFileType;
+}
+
+export interface Task {
+  id: string;
+  sprintId: string;
+  title: string;
+  description: string | null;
+  status: TaskStatus;
+  priority: TaskPriority;
+  order: number;
+  assignee: string | null;
+  tags: string[] | null;
+  /** Files touched for this task (tests, implementation, docs, …). */
+  touchedFiles: TaskTouchedFile[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+export interface TaskDependency {
+  taskId: string;
+  dependsOnTaskId: string;
+}
+
+/** Payload row for create/update (no id / taskId). */
+export interface TaskTouchedFileInput {
+  path: string;
+  fileType: TaskTouchedFileType;
+}
+
+export interface CreateTaskInput {
+  sprintId: string;
+  title: string;
+  description?: string | null;
+  priority: TaskPriority;
+  order?: number;
+  assignee?: string | null;
+  tags?: string[] | null;
+  dependsOnTaskIds?: string[];
+  touchedFiles?: TaskTouchedFileInput[];
+}
+
+export interface UpdateTaskInput {
+  title?: string;
+  description?: string | null;
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  order?: number;
+  assignee?: string | null;
+  tags?: string[] | null;
+  /** When set, replaces all touched-file rows for this task. */
+  touchedFiles?: TaskTouchedFileInput[];
+}
+
+export interface MoveTaskInput {
+  taskId: string;
+  targetSprintId: string;
+}

package/src/domain/repositories/index.ts

@@ -0,0 +1,9 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Barrel export for domain repository ports.
+ */
+
+export type { PlanRepository } from "./plan.repository";
+export type { SprintRepository } from "./sprint.repository";
+export type { TaskFilter, TaskRepository } from "./task.repository";

package/src/domain/repositories/plan.repository.ts

@@ -0,0 +1,21 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Plan persistence port implemented by infrastructure adapters.
+ */
+import type {
+  CreatePlanInput,
+  Plan,
+  UpdatePlanInput
+} from "../entities/plan.entity";
+
+export interface PlanRepository {
+  create(input: CreatePlanInput): Promise<Plan>;
+  findById(id: string): Promise<Plan | null>;
+  findBySlug(slug: string): Promise<Plan | null>;
+  findActive(): Promise<Plan | null>;
+  list(): Promise<Plan[]>;
+  update(id: string, input: UpdatePlanInput): Promise<Plan | null>;
+  setActive(id: string): Promise<void>;
+  delete(id: string): Promise<boolean>;
+}

package/src/domain/repositories/sprint.repository.ts

@@ -0,0 +1,19 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Sprint persistence port implemented by infrastructure adapters.
+ */
+import type {
+  CreateSprintInput,
+  Sprint,
+  UpdateSprintInput
+} from "../entities/sprint.entity";
+
+export interface SprintRepository {
+  create(input: CreateSprintInput): Promise<Sprint>;
+  findById(id: string): Promise<Sprint | null>;
+  findBySlug(planId: string, slug: string): Promise<Sprint | null>;
+  listByPlanId(planId: string): Promise<Sprint[]>;
+  update(id: string, input: UpdateSprintInput): Promise<Sprint | null>;
+  delete(id: string): Promise<boolean>;
+}

package/src/domain/repositories/task.repository.ts

@@ -0,0 +1,35 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Task persistence port implemented by infrastructure adapters.
+ */
+import type {
+  CreateTaskInput,
+  Task,
+  TaskDependency,
+  TaskPriority,
+  TaskStatus,
+  UpdateTaskInput
+} from "../entities/task.entity";
+
+export interface TaskFilter {
+  status?: TaskStatus;
+  priority?: TaskPriority;
+  assignee?: string;
+}
+
+export interface TaskRepository {
+  create(input: CreateTaskInput): Promise<Task>;
+  findById(id: string): Promise<Task | null>;
+  listBySprintId(sprintId: string, filter?: TaskFilter): Promise<Task[]>;
+  listByPlanId(planId: string, filter?: TaskFilter): Promise<Task[]>;
+  update(id: string, input: UpdateTaskInput): Promise<Task | null>;
+  move(taskId: string, targetSprintId: string): Promise<Task | null>;
+  delete(id: string): Promise<boolean>;
+  getDependencies(taskId: string): Promise<TaskDependency[]>;
+  /** Task IDs that list {@link dependsOnTaskId} as a prerequisite. */
+  listDependentTaskIds(dependsOnTaskId: string): Promise<string[]>;
+  setDependencies(taskId: string, dependsOnTaskIds: string[]): Promise<void>;
+  /** Count tasks in the database grouped by status (all plans). */
+  countByStatusGlobally(): Promise<Record<TaskStatus, number>>;
+}

package/src/domain/services/index.ts

@@ -0,0 +1,9 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Barrel export for domain services.
+ */
+
+export { PlanDomainService } from "./plan-domain.service";
+export { SprintDomainService } from "./sprint-domain.service";
+export { TaskDomainService } from "./task-domain.service";

package/src/domain/services/plan-domain.service.ts

@@ -0,0 +1,44 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Plan lifecycle transition rules for the domain layer.
+ */
+import { ValidationError } from "../../errors/backend-errors.js";
+import type { PlanStatus } from "../entities/plan.entity";
+
+/**
+ * Validates allowed plan status transitions (draft through archived).
+ */
+export class PlanDomainService {
+  private readonly transitions: Record<PlanStatus, readonly PlanStatus[]> = {
+    draft: ["active"],
+    active: ["completed", "archived"],
+    completed: ["archived"],
+    archived: []
+  };
+
+  /**
+   * @param from Current plan status.
+   * @param to Requested plan status.
+   * @returns True when the transition is allowed (including no-op same status).
+   */
+  public canTransitionStatus(from: PlanStatus, to: PlanStatus): boolean {
+    if (from === to) {
+      return true;
+    }
+    return this.transitions[from].includes(to);
+  }
+
+  /**
+   * @param from Current plan status.
+   * @param to Requested plan status.
+   * @throws ValidationError when the transition is not allowed.
+   */
+  public validateTransition(from: PlanStatus, to: PlanStatus): void {
+    if (!this.canTransitionStatus(from, to)) {
+      throw new ValidationError(
+        `Illegal plan status transition: ${from} -> ${to}`
+      );
+    }
+  }
+}

package/src/domain/services/sprint-domain.service.ts

@@ -0,0 +1,44 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Sprint lifecycle transition rules for the domain layer.
+ */
+import { ValidationError } from "../../errors/backend-errors.js";
+import type { SprintStatus } from "../entities/sprint.entity";
+
+/**
+ * Validates allowed sprint status transitions (planned through archived).
+ */
+export class SprintDomainService {
+  private readonly transitions: Record<SprintStatus, readonly SprintStatus[]> = {
+    planned: ["active"],
+    active: ["completed", "archived"],
+    completed: ["archived"],
+    archived: []
+  };
+
+  /**
+   * @param from Current sprint status.
+   * @param to Requested sprint status.
+   * @returns True when the transition is allowed (including no-op same status).
+   */
+  public canTransitionStatus(from: SprintStatus, to: SprintStatus): boolean {
+    if (from === to) {
+      return true;
+    }
+    return this.transitions[from].includes(to);
+  }
+
+  /**
+   * @param from Current sprint status.
+   * @param to Requested sprint status.
+   * @throws ValidationError when the transition is not allowed.
+   */
+  public validateTransition(from: SprintStatus, to: SprintStatus): void {
+    if (!this.canTransitionStatus(from, to)) {
+      throw new ValidationError(
+        `Illegal sprint status transition: ${from} -> ${to}`
+      );
+    }
+  }
+}

package/src/domain/services/task-domain.service.ts

@@ -0,0 +1,136 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Task workflow, ordering, and dependency graph validation.
+ */
+import { ValidationError } from "../../errors/backend-errors.js";
+import type { Task, TaskDependency, TaskStatus } from "../entities/task.entity";
+
+/**
+ * Enforces task status moves, unique ordering, and acyclic dependencies.
+ */
+export class TaskDomainService {
+  private readonly transitions: Record<TaskStatus, readonly TaskStatus[]> = {
+    todo: ["in_progress", "blocked", "done"],
+    in_progress: ["blocked", "done", "todo"],
+    blocked: ["in_progress", "todo"],
+    /** Allow reopening from Done on the Kanban (done → any non-terminal workflow state). */
+    done: ["todo", "in_progress", "blocked"]
+  };
+
+  /**
+   * @param from Current task status.
+   * @param to Requested task status.
+   * @returns True when the transition is allowed (including no-op same status).
+   */
+  public canTransitionStatus(from: TaskStatus, to: TaskStatus): boolean {
+    if (from === to) {
+      return true;
+    }
+    return this.transitions[from].includes(to);
+  }
+
+  /**
+   * @param from Current task status.
+   * @param to Requested task status.
+   * @throws ValidationError when the transition is not allowed.
+   */
+  public validateTransition(from: TaskStatus, to: TaskStatus): void {
+    if (!this.canTransitionStatus(from, to)) {
+      throw new ValidationError(
+        `Illegal task status transition: ${from} -> ${to}`
+      );
+    }
+  }
+
+  /**
+   * @param tasks Tasks whose {@link Task.order} values must be unique within this set.
+   * @throws ValidationError when two tasks share the same order value.
+   */
+  public validateOrderUniqueness(tasks: Task[]): void {
+    const seen = new Set<number>();
+    for (const t of tasks) {
+      if (seen.has(t.order)) {
+        throw new ValidationError(`Duplicate task order: ${t.order}`);
+      }
+      seen.add(t.order);
+    }
+  }
+
+  /**
+   * Ensures dependencies only reference known tasks and form a directed acyclic graph.
+   *
+   * @param tasks Tasks participating in the graph.
+   * @param dependencies Directed edges: taskId depends on dependsOnTaskId.
+   * @throws ValidationError when an endpoint is missing or a cycle exists.
+   */
+  public validateDependencyGraph(
+    tasks: Task[],
+    dependencies: TaskDependency[]
+  ): void {
+    const ids = new Set(tasks.map((t) => t.id));
+    for (const d of dependencies) {
+      if (!ids.has(d.taskId) || !ids.has(d.dependsOnTaskId)) {
+        throw new ValidationError(
+          `Dependency references unknown task (${d.taskId} -> ${d.dependsOnTaskId})`
+        );
+      }
+    }
+
+    const adj = new Map<string, string[]>();
+    for (const id of ids) {
+      adj.set(id, []);
+    }
+    for (const d of dependencies) {
+      adj.get(d.taskId)!.push(d.dependsOnTaskId);
+    }
+
+    const color = new Map<string, number>();
+    for (const id of ids) {
+      color.set(id, 0);
+    }
+
+    const dfs = (u: string, stack: string[]): void => {
+      color.set(u, 1);
+      stack.push(u);
+      for (const v of adj.get(u) ?? []) {
+        const c = color.get(v) ?? 0;
+        if (c === 1) {
+          const i = stack.indexOf(v);
+          const segment = stack.slice(i);
+          throw new ValidationError(
+            `Dependency cycle: ${segment.join(" -> ")} -> ${v}`
+          );
+        }
+        if (c === 0) {
+          dfs(v, stack);
+        }
+      }
+      stack.pop();
+      color.set(u, 2);
+    };
+
+    for (const id of ids) {
+      if (color.get(id) === 0) {
+        dfs(id, []);
+      }
+    }
+  }
+
+  /**
+   * @param dependsOnIds Task ids that must exist as prerequisites.
+   * @param existingTaskIds Task ids that are allowed as dependency targets.
+   * @throws ValidationError when any prerequisite id is not in the allowed set.
+   */
+  public validateDependencyReferences(
+    dependsOnIds: string[],
+    existingTaskIds: string[]
+  ): void {
+    const allowed = new Set(existingTaskIds);
+    for (const id of dependsOnIds) {
+      if (!allowed.has(id)) {
+        throw new ValidationError(`Unknown dependency target task: ${id}`);
+      }
+    }
+  }
+}

package/src/errors/backend-errors.ts

@@ -0,0 +1,75 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Typed HTTP-oriented error hierarchy for domain and infrastructure failures.
+ */
+
+/**
+ * Base error carrying an HTTP-style status code for protocol adapters.
+ */
+export class BackendError extends Error {
+  public readonly statusCode: number;
+
+  /**
+   * @param message Human-readable error message.
+   * @param statusCode HTTP status code for mapping in REST/MCP layers.
+   */
+  public constructor(message: string, statusCode: number) {
+    super(message);
+    this.name = "BackendError";
+    this.statusCode = statusCode;
+  }
+}
+
+/**
+ * Raised when a requested entity does not exist.
+ */
+export class NotFoundError extends BackendError {
+  /**
+   * @param entityName Domain entity label (for example, Plan or Task).
+   * @param id Identifier that was not found.
+   */
+  public constructor(entityName: string, id: string) {
+    super(`${entityName} not found: ${id}`, 404);
+    this.name = "NotFoundError";
+  }
+}
+
+/**
+ * Raised when input or state violates business or schema rules.
+ */
+export class ValidationError extends BackendError {
+  /**
+   * @param message Human-readable validation message.
+   */
+  public constructor(message: string) {
+    super(message, 400);
+    this.name = "ValidationError";
+  }
+}
+
+/**
+ * Raised when an operation conflicts with current persisted state.
+ */
+export class ConflictError extends BackendError {
+  /**
+   * @param message Human-readable conflict description.
+   */
+  public constructor(message: string) {
+    super(message, 409);
+    this.name = "ConflictError";
+  }
+}
+
+/**
+ * Raised when persistence or storage operations fail unexpectedly.
+ */
+export class StorageError extends BackendError {
+  /**
+   * @param message Human-readable storage failure message.
+   */
+  public constructor(message: string) {
+    super(message, 500);
+    this.name = "StorageError";
+  }
+}