@sprintdock/backend 0.4.2

package/src/application/sprint.service.ts

@@ -0,0 +1,118 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Application service orchestrating sprint operations within a plan.
+ */
+import { NotFoundError } from "../errors/backend-errors.js";
+import type {
+  CreateSprintInput,
+  Sprint,
+  SprintStatus,
+  UpdateSprintInput
+} from "../domain/entities/sprint.entity";
+import type { PlanRepository } from "../domain/repositories/plan.repository";
+import type { SprintRepository } from "../domain/repositories/sprint.repository";
+import type { SprintDomainService } from "../domain/services/sprint-domain.service";
+import type { PlanService } from "./plan.service";
+
+/**
+ * Coordinates sprint persistence, plan resolution, and sprint lifecycle rules.
+ */
+export class SprintService {
+  public constructor(
+    private readonly sprintRepo: SprintRepository,
+    private readonly planRepo: PlanRepository,
+    private readonly planService: PlanService,
+    private readonly sprintDomain: SprintDomainService
+  ) {}
+
+  /** @param planIdOrSlug When omitted, the active plan is used. */
+  public async listSprints(planIdOrSlug?: string): Promise<Sprint[]> {
+    const plan = await this.planService.resolvePlan(planIdOrSlug);
+    return this.sprintRepo.listByPlanId(plan.id);
+  }
+
+  /**
+   * Creates a sprint under the resolved plan; {@link CreateSprintInput.planId} is overwritten.
+   */
+  public async createSprint(
+    planIdOrSlug: string,
+    input: CreateSprintInput
+  ): Promise<Sprint> {
+    const plan = await this.planService.resolvePlan(planIdOrSlug);
+    return this.sprintRepo.create({ ...input, planId: plan.id });
+  }
+
+  /**
+   * @throws NotFoundError when the sprint does not exist.
+   */
+  public async getSprint(id: string): Promise<Sprint> {
+    const sprint = await this.sprintRepo.findById(id);
+    if (!sprint) {
+      throw new NotFoundError("Sprint", id);
+    }
+    return sprint;
+  }
+
+  /**
+   * Finds a sprint by plan scope and slug.
+   *
+   * @throws NotFoundError when the sprint is missing.
+   */
+  public async getSprintBySlug(
+    planIdOrSlug: string,
+    sprintSlug: string
+  ): Promise<Sprint> {
+    const plan = await this.planService.resolvePlan(planIdOrSlug);
+    const sprint = await this.sprintRepo.findBySlug(plan.id, sprintSlug);
+    if (!sprint) {
+      throw new NotFoundError("Sprint", sprintSlug);
+    }
+    return sprint;
+  }
+
+  /**
+   * Updates sprint fields (name, goal, dates, order) without changing status.
+   * Use {@link updateSprintStatus} for lifecycle transitions.
+   */
+  public async updateSprint(
+    id: string,
+    input: Pick<
+      UpdateSprintInput,
+      "name" | "goal" | "markdownContent" | "startDate" | "endDate" | "order"
+    >
+  ): Promise<Sprint> {
+    const existing = await this.getSprint(id);
+    const updated = await this.sprintRepo.update(existing.id, input);
+    if (!updated) {
+      throw new NotFoundError("Sprint", id);
+    }
+    return updated;
+  }
+
+  /**
+   * Updates sprint status after validating the transition.
+   */
+  public async updateSprintStatus(
+    id: string,
+    status: SprintStatus
+  ): Promise<Sprint> {
+    const existing = await this.getSprint(id);
+    this.sprintDomain.validateTransition(existing.status, status);
+    const updated = await this.sprintRepo.update(existing.id, { status });
+    if (!updated) {
+      throw new NotFoundError("Sprint", id);
+    }
+    return updated;
+  }
+
+  /**
+   * @throws NotFoundError when the sprint does not exist.
+   */
+  public async deleteSprint(id: string): Promise<void> {
+    const removed = await this.sprintRepo.delete(id);
+    if (!removed) {
+      throw new NotFoundError("Sprint", id);
+    }
+  }
+}

package/src/application/task.service.ts

@@ -0,0 +1,389 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Application service orchestrating task operations within plans and sprints.
+ */
+import { NotFoundError, ValidationError } from "../errors/backend-errors.js";
+import type { Plan } from "../domain/entities/plan.entity";
+import type {
+  CreateTaskInput,
+  Task,
+  TaskDependency,
+  TaskStatus,
+  UpdateTaskInput
+} from "../domain/entities/task.entity";
+import type { SprintRepository } from "../domain/repositories/sprint.repository";
+import type {
+  TaskFilter,
+  TaskRepository
+} from "../domain/repositories/task.repository";
+import type { TaskDomainService } from "../domain/services/task-domain.service";
+import type { PlanSprintTaskAnalyticsDto } from "./dto/plan-sprint-analytics.dto.js";
+import type { PlanService } from "./plan.service";
+
+const PENDING_TASK_ID = "__pending__";
+
+function emptyStatusCounts(): Record<TaskStatus, number> {
+  return { todo: 0, in_progress: 0, blocked: 0, done: 0 };
+}
+
+/**
+ * Field updates for {@link TaskService.updateTask}
+ * (status changes use {@link updateTaskStatus}).
+ */
+export type TaskFieldUpdateInput = Omit<UpdateTaskInput, "status">;
+
+/**
+ * Coordinates task persistence, plan resolution, ordering, and dependency validation.
+ */
+export class TaskService {
+  public constructor(
+    private readonly taskRepo: TaskRepository,
+    private readonly sprintRepo: SprintRepository,
+    private readonly planService: PlanService,
+    private readonly taskDomain: TaskDomainService
+  ) {}
+
+  /**
+   * Lists tasks for a sprint, or all tasks in a resolved plan when {@link sprintId} is omitted.
+   */
+  public async listTasks(
+    sprintId?: string,
+    planIdOrSlug?: string,
+    filter?: TaskFilter
+  ): Promise<Task[]> {
+    if (sprintId !== undefined && sprintId !== "") {
+      return this.taskRepo.listBySprintId(sprintId, filter);
+    }
+    const plan = await this.planService.resolvePlan(planIdOrSlug);
+    return this.taskRepo.listByPlanId(plan.id, filter);
+  }
+
+  /**
+   * Creates a task after validating sprint ownership, order uniqueness, and dependencies.
+   */
+  public async createTask(
+    input: CreateTaskInput,
+    planIdOrSlug?: string
+  ): Promise<Task> {
+    const sprint = await this.sprintRepo.findById(input.sprintId);
+    if (!sprint) {
+      throw new NotFoundError("Sprint", input.sprintId);
+    }
+
+    let plan: Plan;
+    if (planIdOrSlug !== undefined && planIdOrSlug !== "") {
+      plan = await this.planService.resolvePlan(planIdOrSlug);
+      if (sprint.planId !== plan.id) {
+        throw new ValidationError(
+          "Sprint does not belong to the resolved plan"
+        );
+      }
+    } else {
+      plan = await this.planService.getPlan(sprint.planId);
+    }
+
+    const sprintTasks = await this.taskRepo.listBySprintId(input.sprintId);
+    let order: number;
+    if (input.order === undefined) {
+      order =
+        sprintTasks.length === 0
+          ? 0
+          : Math.max(...sprintTasks.map((t) => t.order)) + 1;
+    } else {
+      order = input.order;
+    }
+
+    const pendingTask: Task = {
+      id: PENDING_TASK_ID,
+      sprintId: input.sprintId,
+      title: input.title,
+      description: input.description ?? null,
+      status: "todo",
+      priority: input.priority,
+      order,
+      assignee: input.assignee ?? null,
+      tags: input.tags ?? null,
+      touchedFiles: [],
+      createdAt: "",
+      updatedAt: ""
+    };
+    this.taskDomain.validateOrderUniqueness([...sprintTasks, pendingTask]);
+
+    const planTasks = await this.taskRepo.listByPlanId(plan.id);
+    const prereqs = input.dependsOnTaskIds ?? [];
+    if (prereqs.length > 0) {
+      this.taskDomain.validateDependencyReferences(
+        prereqs,
+        planTasks.map((t) => t.id)
+      );
+      const existingDeps: TaskDependency[] = [];
+      for (const t of planTasks) {
+        existingDeps.push(...(await this.taskRepo.getDependencies(t.id)));
+      }
+      const newEdges = prereqs.map((dependsOnTaskId) => ({
+        taskId: PENDING_TASK_ID,
+        dependsOnTaskId
+      }));
+      this.taskDomain.validateDependencyGraph(
+        [...planTasks, pendingTask],
+        [...existingDeps, ...newEdges]
+      );
+    }
+
+    return this.taskRepo.create({
+      ...input,
+      order
+    });
+  }
+
+  /**
+   * @throws NotFoundError when the task does not exist.
+   */
+  public async getTask(id: string): Promise<Task> {
+    const task = await this.taskRepo.findById(id);
+    if (!task) {
+      throw new NotFoundError("Task", id);
+    }
+    return task;
+  }
+
+  /**
+   * Updates title, description, priority, tags, or order (not status).
+   */
+  public async updateTask(
+    id: string,
+    input: TaskFieldUpdateInput
+  ): Promise<Task> {
+    const existing = await this.getTask(id);
+    const merged: Task = {
+      ...existing,
+      title: input.title ?? existing.title,
+      description:
+        input.description !== undefined
+          ? input.description
+          : existing.description,
+      priority: input.priority ?? existing.priority,
+      order: input.order ?? existing.order,
+      assignee:
+        input.assignee !== undefined ? input.assignee : existing.assignee,
+      tags: input.tags !== undefined ? input.tags : existing.tags,
+      touchedFiles: existing.touchedFiles
+    };
+    if (input.order !== undefined && input.order !== existing.order) {
+      const sprintTasks = await this.taskRepo.listBySprintId(existing.sprintId);
+      this.taskDomain.validateOrderUniqueness(
+        sprintTasks.map((t) => (t.id === id ? merged : t))
+      );
+    }
+    const updated = await this.taskRepo.update(existing.id, input);
+    if (!updated) {
+      throw new NotFoundError("Task", id);
+    }
+    return updated;
+  }
+
+  /**
+   * Replaces prerequisite edges for a task after validating the dependency DAG.
+   */
+  public async setTaskDependencies(
+    taskId: string,
+    dependsOnTaskIds: string[],
+    planIdOrSlug?: string
+  ): Promise<void> {
+    const task = await this.getTask(taskId);
+    const sprint = await this.sprintRepo.findById(task.sprintId);
+    if (!sprint) {
+      throw new NotFoundError("Sprint", task.sprintId);
+    }
+    const plan = await this.planService.getPlan(sprint.planId);
+    if (planIdOrSlug !== undefined && planIdOrSlug !== "") {
+      const scoped = await this.planService.resolvePlan(planIdOrSlug);
+      if (scoped.id !== plan.id) {
+        throw new ValidationError(
+          "Task does not belong to the resolved plan"
+        );
+      }
+    }
+    const planTasks = await this.taskRepo.listByPlanId(plan.id);
+    this.taskDomain.validateDependencyReferences(
+      dependsOnTaskIds,
+      planTasks.map((t) => t.id)
+    );
+    const existingDeps: TaskDependency[] = [];
+    for (const t of planTasks) {
+      if (t.id === taskId) {
+        continue;
+      }
+      existingDeps.push(...(await this.taskRepo.getDependencies(t.id)));
+    }
+    const newEdges = dependsOnTaskIds.map((dependsOnTaskId) => ({
+      taskId,
+      dependsOnTaskId
+    }));
+    this.taskDomain.validateDependencyGraph(planTasks, [
+      ...existingDeps,
+      ...newEdges
+    ]);
+    await this.taskRepo.setDependencies(taskId, dependsOnTaskIds);
+  }
+
+  /**
+   * Loads prerequisite tasks and tasks that depend on this task.
+   */
+  public async getTaskDependencyInfo(
+    taskId: string,
+    planIdOrSlug?: string
+  ): Promise<{ dependsOn: Task[]; dependedOnBy: Task[] }> {
+    const task = await this.getTask(taskId);
+    if (planIdOrSlug !== undefined && planIdOrSlug !== "") {
+      const plan = await this.planService.resolvePlan(planIdOrSlug);
+      const sprint = await this.sprintRepo.findById(task.sprintId);
+      if (!sprint || sprint.planId !== plan.id) {
+        throw new ValidationError(
+          "Task does not belong to the resolved plan"
+        );
+      }
+    }
+    const depRows = await this.taskRepo.getDependencies(taskId);
+    const dependsOn: Task[] = [];
+    for (const d of depRows) {
+      dependsOn.push(await this.getTask(d.dependsOnTaskId));
+    }
+    const dependentIds = await this.taskRepo.listDependentTaskIds(taskId);
+    const dependedOnBy: Task[] = [];
+    for (const id of dependentIds) {
+      dependedOnBy.push(await this.getTask(id));
+    }
+    return { dependsOn, dependedOnBy };
+  }
+
+  /**
+   * Updates task status after validating the transition.
+   */
+  public async updateTaskStatus(id: string, status: TaskStatus): Promise<Task> {
+    const existing = await this.getTask(id);
+    this.taskDomain.validateTransition(existing.status, status);
+    const updated = await this.taskRepo.update(existing.id, { status });
+    if (!updated) {
+      throw new NotFoundError("Task", id);
+    }
+    return updated;
+  }
+
+  /**
+   * Sets or clears the task assignee.
+   */
+  public async assignTask(
+    id: string,
+    assignee: string | null
+  ): Promise<Task> {
+    const existing = await this.getTask(id);
+    const updated = await this.taskRepo.update(existing.id, { assignee });
+    if (!updated) {
+      throw new NotFoundError("Task", id);
+    }
+    return updated;
+  }
+
+  /**
+   * Moves a task to another sprint in the same plan.
+   */
+  public async moveTask(taskId: string, targetSprintId: string): Promise<Task> {
+    const task = await this.getTask(taskId);
+    const sourceSprint = await this.sprintRepo.findById(task.sprintId);
+    const targetSprint = await this.sprintRepo.findById(targetSprintId);
+    if (!sourceSprint) {
+      throw new NotFoundError("Sprint", task.sprintId);
+    }
+    if (!targetSprint) {
+      throw new NotFoundError("Sprint", targetSprintId);
+    }
+    if (sourceSprint.planId !== targetSprint.planId) {
+      throw new ValidationError(
+        "Cannot move a task to a sprint in a different plan"
+      );
+    }
+    const moved = await this.taskRepo.move(taskId, targetSprintId);
+    if (!moved) {
+      throw new NotFoundError("Task", taskId);
+    }
+    return moved;
+  }
+
+  /**
+   * @throws NotFoundError when the task does not exist.
+   */
+  public async deleteTask(id: string): Promise<void> {
+    const removed = await this.taskRepo.delete(id);
+    if (!removed) {
+      throw new NotFoundError("Task", id);
+    }
+  }
+
+  /**
+   * Loads all sprints for the plan (ordered) and task counts by status per sprint, plus plan rollup.
+   */
+  public async getPlanSprintTaskAnalytics(
+    planIdOrSlug: string
+  ): Promise<PlanSprintTaskAnalyticsDto> {
+    const plan = await this.planService.resolvePlan(planIdOrSlug);
+    const [sprintList, tasks] = await Promise.all([
+      this.sprintRepo.listByPlanId(plan.id),
+      this.taskRepo.listByPlanId(plan.id)
+    ]);
+    const perSprint = new Map<string, Record<TaskStatus, number>>();
+    for (const s of sprintList) {
+      perSprint.set(s.id, emptyStatusCounts());
+    }
+    const rollup = emptyStatusCounts();
+    for (const t of tasks) {
+      rollup[t.status] += 1;
+      const row = perSprint.get(t.sprintId);
+      if (row !== undefined) {
+        row[t.status] += 1;
+      }
+    }
+    const sprints: PlanSprintTaskAnalyticsDto["sprints"] = sprintList.map(
+      (sprint) => {
+        const c = perSprint.get(sprint.id) ?? emptyStatusCounts();
+        const totalTasks = c.todo + c.in_progress + c.blocked + c.done;
+        return {
+          sprint,
+          tasksByStatus: { ...c },
+          totalTasks
+        };
+      }
+    );
+    const totalTasks =
+      rollup.todo +
+      rollup.in_progress +
+      rollup.blocked +
+      rollup.done;
+    return {
+      planId: plan.id,
+      sprints,
+      rollup: {
+        tasksByStatus: { ...rollup },
+        totalTasks,
+        sprintCount: sprintList.length
+      }
+    };
+  }
+
+  /**
+   * Fleet Command throughput: counts across all tasks (all plans). Blocked tasks are omitted from the trio.
+   */
+  public async getGlobalTaskThroughput(): Promise<{
+    todo: number;
+    inProgress: number;
+    done: number;
+  }> {
+    const c = await this.taskRepo.countByStatusGlobally();
+    return {
+      todo: c.todo,
+      inProgress: c.in_progress,
+      done: c.done
+    };
+  }
+}

package/src/db/connection.ts

@@ -0,0 +1,25 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: SQLite connection factory wrapping better-sqlite3 with Drizzle ORM.
+ */
+import Database from "better-sqlite3";
+import { drizzle } from "drizzle-orm/better-sqlite3";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import * as schema from "./schema/index";
+
+/**
+ * Opens a SQLite database at the given path and returns a Drizzle client.
+ *
+ * @param dbPath Filesystem path or `:memory:` for an ephemeral database.
+ * @returns Drizzle database instance bound to the canonical schema.
+ */
+export function createSqliteConnection(
+  dbPath: string
+): BetterSQLite3Database<typeof schema> {
+  const sqlite = new Database(dbPath);
+  sqlite.pragma("journal_mode = WAL");
+  sqlite.pragma("foreign_keys = ON");
+  sqlite.pragma("busy_timeout = 5000");
+  return drizzle(sqlite, { schema });
+}

package/src/db/migrator.ts

@@ -0,0 +1,46 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Applies Drizzle SQL migrations from the package drizzle/ folder.
+ */
+import { existsSync } from "node:fs";
+import { migrate } from "drizzle-orm/better-sqlite3/migrator";
+import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import * as schema from "./schema/index";
+
+/**
+ * Resolves `packages/backend/drizzle` whether this module runs from source (`src/db/migrator.ts`)
+ * or from the bundled entry (`dist/index.js`), where `../../drizzle` would escape the package.
+ */
+function resolveMigrationsFolder(): string {
+  let dir = dirname(fileURLToPath(import.meta.url));
+  for (let i = 0; i < 8; i++) {
+    const candidate = join(dir, "drizzle");
+    if (existsSync(join(candidate, "meta", "_journal.json"))) {
+      return candidate;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      break;
+    }
+    dir = parent;
+  }
+  throw new Error(
+    "Sprintdock: could not find drizzle migrations (expected drizzle/meta/_journal.json next to @sprintdock/backend)."
+  );
+}
+
+const migrationsFolder = resolveMigrationsFolder();
+
+/**
+ * Runs all pending migrations against the given database.
+ *
+ * @param db Drizzle client created via {@link createSqliteConnection}.
+ */
+export function runMigrations(
+  db: BetterSQLite3Database<typeof schema>
+): void {
+  migrate(db, { migrationsFolder });
+}

package/src/db/schema/index.ts

@@ -0,0 +1,14 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Re-exports all Drizzle tables and relations for the migrator and ORM.
+ */
+export { plans } from "./plans";
+export { sprints } from "./sprints";
+export { taskDependencies, taskTouchedFiles, tasks } from "./tasks";
+export {
+  plansRelations,
+  sprintsRelations,
+  taskTouchedFilesRelations,
+  tasksRelations
+} from "./relations";

package/src/db/schema/plans.ts

@@ -0,0 +1,18 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Drizzle schema for the plans table (plan-tree root entity).
+ */
+import { sqliteTable, text, integer } from "drizzle-orm/sqlite-core";
+
+export const plans = sqliteTable("plans", {
+  id: text("id").primaryKey(),
+  slug: text("slug").notNull().unique(),
+  title: text("title").notNull(),
+  description: text("description"),
+  markdownContent: text("markdown_content"),
+  status: text("status").notNull(),
+  isActive: integer("is_active", { mode: "boolean" }).notNull().default(false),
+  createdAt: text("created_at").notNull(),
+  updatedAt: text("updated_at").notNull()
+});

package/src/db/schema/relations.ts

@@ -0,0 +1,36 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Drizzle relation graph for plans, sprints, and tasks.
+ */
+import { relations } from "drizzle-orm";
+import { plans } from "./plans";
+import { sprints } from "./sprints";
+import { taskTouchedFiles, tasks } from "./tasks";
+
+export const plansRelations = relations(plans, ({ many }) => ({
+  sprints: many(sprints)
+}));
+
+export const sprintsRelations = relations(sprints, ({ one, many }) => ({
+  plan: one(plans, {
+    fields: [sprints.planId],
+    references: [plans.id]
+  }),
+  tasks: many(tasks)
+}));
+
+export const tasksRelations = relations(tasks, ({ one, many }) => ({
+  sprint: one(sprints, {
+    fields: [tasks.sprintId],
+    references: [sprints.id]
+  }),
+  touchedFiles: many(taskTouchedFiles)
+}));
+
+export const taskTouchedFilesRelations = relations(taskTouchedFiles, ({ one }) => ({
+  task: one(tasks, {
+    fields: [taskTouchedFiles.taskId],
+    references: [tasks.id]
+  })
+}));

package/src/db/schema/sprints.ts

@@ -0,0 +1,33 @@
+/**
+ * package: @sprintdock/backend
+ * author: vikash sharma
+ * description: Drizzle schema for sprints scoped to a plan.
+ */
+import { sqliteTable, text, integer, uniqueIndex } from "drizzle-orm/sqlite-core";
+import { plans } from "./plans";
+
+export const sprints = sqliteTable(
+  "sprints",
+  {
+    id: text("id").primaryKey(),
+    slug: text("slug").notNull(),
+    planId: text("plan_id")
+      .notNull()
+      .references(() => plans.id, { onDelete: "cascade" }),
+    name: text("name").notNull(),
+    goal: text("goal").notNull(),
+    markdownContent: text("markdown_content"),
+    status: text("status").notNull(),
+    sprintOrder: integer("order").notNull().default(0),
+    startDate: text("start_date"),
+    endDate: text("end_date"),
+    createdAt: text("created_at").notNull(),
+    updatedAt: text("updated_at").notNull()
+  },
+  (table) => ({
+    planSlugUnique: uniqueIndex("sprints_plan_id_slug_unique").on(
+      table.planId,
+      table.slug
+    )
+  })
+);