feat: sprints with burndown and carry-over

Plan sprints with dates and a goal, run one at a time per project, and
put tickets in them from the ticket page. The Sprints tab follows the one
under way with its progress and a burndown in tickets or points against
the ideal line. Closing a sprint sends what was left to the next one or
back to the backlog; the board can be filtered by sprint.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

libs/api/tracker/presenters/src/lib/graphql/enums.ts

@@ -6,6 +6,7 @@ import {
   NotificationKind,
   ProjectRole,
   ReleaseStatus,
+  SprintStatus,
   StatusCategory,
 } from '@task-stream/api/tracker/domain';
 
@@ -23,6 +24,10 @@ registerEnumType(StatusCategory, {
 registerEnumType(IssueLinkType, { name: 'IssueLinkType' });
 registerEnumType(ProjectRole, { name: 'ProjectRole' });
 registerEnumType(ReleaseStatus, { name: 'ReleaseStatus' });
+registerEnumType(SprintStatus, {
+  name: 'SprintStatus',
+  description: 'PLANNED, ACTIVE (one per project at a time) or CLOSED',
+});
 registerEnumType(LinkDirection, { name: 'LinkDirection' });
 registerEnumType(IssueSort, {
   name: 'IssueSort',

libs/api/tracker/presenters/src/lib/graphql/inputs.ts

@@ -181,6 +181,41 @@ export class ChangeIssueStatusInput {
   reason?: string | null;
 }
 
+const DAY = /^\d{4}-\d{2}-\d{2}$/;
+
+@InputType()
+export class CreateSprintInput {
+  @Field(() => ID) @IsUUID() projectId!: string;
+  @Field() @IsString() @MinLength(1) @MaxLength(80) name!: string;
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  goal?: string | null;
+  @Field({ description: 'YYYY-MM-DD' }) @Matches(DAY) startDate!: string;
+  @Field({ description: 'YYYY-MM-DD, included' })
+  @Matches(DAY)
+  endDate!: string;
+}
+
+@InputType()
+export class UpdateSprintInput {
+  @Field(() => ID) @IsUUID() sprintId!: string;
+  @Field({ nullable: true })
+  @IsOptional()
+  @IsString()
+  @MinLength(1)
+  @MaxLength(80)
+  name?: string;
+  @Field(() => String, { nullable: true })
+  @IsOptional()
+  @IsString()
+  @MaxLength(500)
+  goal?: string | null;
+  @Field({ nullable: true }) @IsOptional() @Matches(DAY) startDate?: string;
+  @Field({ nullable: true }) @IsOptional() @Matches(DAY) endDate?: string;
+}
+
 @InputType()
 export class SavedFilterCriteriaInput {
   @Field(() => [String], { nullable: true })
@@ -320,6 +355,14 @@ export class IssueFilterInput {
   @IsOptional()
   @IsUUID()
   parentId?: string;
+  @Field(() => ID, { nullable: true })
+  @IsOptional()
+  @IsUUID()
+  sprintId?: string;
+  @Field({ nullable: true, description: 'Only tickets in no sprint' })
+  @IsOptional()
+  @IsBoolean()
+  noSprint?: boolean;
   @Field(() => IssueSort, { nullable: true, defaultValue: IssueSort.RECENT })
   @IsOptional()
   @IsEnum(IssueSort)

libs/api/tracker/presenters/src/lib/graphql/project.resolver.ts

@@ -125,6 +125,8 @@ export class ProjectResolver {
     search?: string | null,
     @Args('unassigned', { type: () => Boolean, nullable: true })
     unassigned?: boolean | null,
+    @Args('sprintId', { type: () => ID, nullable: true })
+    sprintId?: string | null,
   ) {
     return this.projects.board(
       viewerOf(me),
@@ -138,6 +140,7 @@ export class ProjectResolver {
         labels: labels ?? undefined,
         search: search?.slice(0, 200) ?? undefined,
         unassigned: unassigned ?? undefined,
+        sprintId: sprintId ?? undefined,
       },
       perColumn,
     );

libs/api/tracker/presenters/src/lib/graphql/sprint.resolver.ts

@@ -0,0 +1,170 @@
+import {
+  Args,
+  ID,
+  Int,
+  Mutation,
+  Parent,
+  Query,
+  ResolveField,
+  Resolver,
+} from '@nestjs/graphql';
+import { User } from '@task-stream/api/identity/domain';
+import {
+  CurrentUser,
+  OptionalAuth,
+} from '@task-stream/api/identity/presenters';
+import {
+  IssuesService,
+  IssueSort,
+  SprintsService,
+} from '@task-stream/api/tracker/application';
+import { SprintReadModel } from '@task-stream/api/tracker/domain';
+import { viewerOf } from '../common/viewer';
+import { CreateSprintInput, UpdateSprintInput } from './inputs';
+import {
+  CommandResultGql,
+  IssuePageGql,
+  SprintBurndownGql,
+  SprintGql,
+  SprintProgressGql,
+} from './types';
+
+@Resolver(() => SprintGql)
+export class SprintResolver {
+  constructor(
+    private readonly sprintsService: SprintsService,
+    private readonly issuesService: IssuesService,
+  ) {}
+
+  @OptionalAuth()
+  @Query(() => [SprintGql], {
+    description:
+      "A project's sprints: the one under way, the planned ones, then the closed ones",
+  })
+  sprints(
+    @CurrentUser() me: User | undefined,
+    @Args('projectId', { type: () => ID }) projectId: string,
+  ) {
+    return this.sprintsService.list(viewerOf(me), projectId);
+  }
+
+  @OptionalAuth()
+  @Query(() => SprintGql)
+  sprint(
+    @CurrentUser() me: User | undefined,
+    @Args('id', { type: () => ID }) id: string,
+  ) {
+    return this.sprintsService.findOne(viewerOf(me), id);
+  }
+
+  @ResolveField(() => SprintProgressGql)
+  progress(
+    @CurrentUser() me: User | undefined,
+    @Parent() sprint: SprintReadModel,
+  ) {
+    return this.sprintsService.progress(viewerOf(me), sprint.id);
+  }
+
+  @ResolveField(() => SprintBurndownGql)
+  burndown(
+    @CurrentUser() me: User | undefined,
+    @Parent() sprint: SprintReadModel,
+  ) {
+    return this.sprintsService.burndown(viewerOf(me), sprint.id);
+  }
+
+  @ResolveField(() => IssuePageGql, {
+    description: 'Tickets in this sprint, in backlog order',
+  })
+  issues(
+    @CurrentUser() me: User | undefined,
+    @Parent() sprint: SprintReadModel,
+    @Args('limit', { type: () => Int, defaultValue: 100 }) limit: number,
+    @Args('offset', { type: () => Int, defaultValue: 0 }) offset: number,
+  ) {
+    return this.issuesService.search(viewerOf(me), {
+      projectId: sprint.projectId,
+      sprintId: sprint.id,
+      sort: IssueSort.RANK,
+      limit,
+      offset,
+    });
+  }
+
+  @Mutation(() => CommandResultGql, {
+    description: 'Plan a sprint (owners and admins)',
+  })
+  createSprint(
+    @CurrentUser() me: User,
+    @Args('input') input: CreateSprintInput,
+  ) {
+    return this.sprintsService.create(me.id, input);
+  }
+
+  @Mutation(() => CommandResultGql)
+  updateSprint(
+    @CurrentUser() me: User,
+    @Args('input') input: UpdateSprintInput,
+  ) {
+    const { sprintId, ...changes } = input;
+    return this.sprintsService.update(
+      me.id,
+      sprintId,
+      Object.fromEntries(
+        Object.entries(changes).filter(
+          ([field, value]) => value !== null || field === 'goal',
+        ),
+      ),
+    );
+  }
+
+  @Mutation(() => CommandResultGql, {
+    description: 'Start a planned sprint (only one under way per project)',
+  })
+  startSprint(
+    @CurrentUser() me: User,
+    @Args('sprintId', { type: () => ID }) sprintId: string,
+  ) {
+    return this.sprintsService.start(me.id, sprintId);
+  }
+
+  @Mutation(() => CommandResultGql, {
+    description:
+      'Close the sprint under way. Unfinished tickets move to carryOverToSprintId, or back to the backlog when it is null.',
+  })
+  closeSprint(
+    @CurrentUser() me: User,
+    @Args('sprintId', { type: () => ID }) sprintId: string,
+    @Args('carryOverToSprintId', { type: () => ID, nullable: true })
+    carryOverToSprintId: string | null,
+  ) {
+    return this.sprintsService.close(
+      me.id,
+      sprintId,
+      carryOverToSprintId ?? null,
+    );
+  }
+
+  @Mutation(() => CommandResultGql, {
+    description:
+      'Delete a sprint that never started; its tickets go back to the backlog',
+  })
+  deleteSprint(
+    @CurrentUser() me: User,
+    @Args('sprintId', { type: () => ID }) sprintId: string,
+  ) {
+    return this.sprintsService.delete(me.id, sprintId);
+  }
+
+  @Mutation(() => CommandResultGql, {
+    description: 'Put a ticket in a sprint (null: back to the backlog)',
+  })
+  setIssueSprint(
+    @CurrentUser() me: User,
+    @Args('issueId', { type: () => ID }) issueId: string,
+    @Args('sprintId', { type: () => ID, nullable: true })
+    sprintId: string | null,
+  ) {
+    return this.sprintsService.setIssueSprint(me.id, issueId, sprintId ?? null);
+  }
+}

libs/api/tracker/presenters/src/lib/graphql/subscription.resolver.ts

@@ -12,6 +12,7 @@ import {
   NotificationGql,
   ProjectChangeGql,
   ReleaseChangeGql,
+  SprintChangeGql,
 } from './types';
 
 const asIs = { resolve: <T>(payload: T) => payload };
@@ -66,6 +67,14 @@ export class SubscriptionResolver {
     return this.changes.watchReleases(me.id, projectId);
   }
 
+  @Subscription(() => SprintChangeGql, asIs)
+  sprintChanged(
+    @CurrentUser() me: User,
+    @Args('projectId', { type: () => ID }) projectId: string,
+  ) {
+    return this.changes.watchSprints(me.id, projectId);
+  }
+
   @Subscription(() => ProjectChangeGql, asIs)
   projectChanged(
     @CurrentUser() me: User,

libs/api/tracker/presenters/src/lib/graphql/types.ts

@@ -5,6 +5,7 @@ import {
   NotificationKind,
   ProjectRole,
   ReleaseStatus,
+  SprintStatus,
   StatusCategory,
 } from '@task-stream/api/tracker/domain';
 import { LinkDirection } from './enums';
@@ -110,6 +111,12 @@ export class AttachmentGql {
   commentId!: string | null;
 }
 
+@ObjectType('SprintRef')
+export class SprintRefGql {
+  @Field(() => ID) id!: string;
+  @Field() name!: string;
+}
+
 @ObjectType('ReleaseRef')
 export class ReleaseRefGql {
   @Field(() => ID) id!: string;
@@ -154,6 +161,7 @@ export class IssueGql {
   @Field(() => UserRefGql, { nullable: true }) assignee!: UserRefGql | null;
   @Field(() => ReleaseRefGql, { nullable: true })
   release!: ReleaseRefGql | null;
+  @Field(() => SprintRefGql, { nullable: true }) sprint!: SprintRefGql | null;
   @Field(() => [String]) labels!: string[];
   @Field(() => String, { nullable: true }) figmaUrl!: string | null;
   @Field(() => Int, { nullable: true }) storyPoints!: number | null;
@@ -270,6 +278,56 @@ export class ReleaseGql {
   @Field(() => Int) version!: number;
 }
 
+@ObjectType('Sprint', {
+  description: 'A time-boxed iteration: the tickets the team commits to',
+})
+export class SprintGql {
+  @Field(() => ID) id!: string;
+  @Field(() => ID) projectId!: string;
+  @Field() name!: string;
+  @Field(() => String, { nullable: true }) goal!: string | null;
+  @Field({ description: 'First day, YYYY-MM-DD' }) startDate!: string;
+  @Field({ description: 'Last day (included), YYYY-MM-DD' }) endDate!: string;
+  @Field(() => SprintStatus) status!: SprintStatus;
+  @Field(() => String, { nullable: true }) startedAt!: string | null;
+  @Field(() => String, { nullable: true }) closedAt!: string | null;
+  @Field() createdAt!: string;
+  @Field(() => Int) version!: number;
+}
+
+@ObjectType('SprintProgress')
+export class SprintProgressGql {
+  @Field(() => Int) total!: number;
+  @Field(() => Int, { description: 'Done or cancelled' }) finished!: number;
+  @Field(() => Int) percent!: number;
+  @Field(() => Int) storyPoints!: number;
+  @Field(() => Int) finishedStoryPoints!: number;
+}
+
+@ObjectType('SprintBurndown', {
+  description:
+    'Per day of the sprint: tickets in it, still open, and their points (null: days to come). `ideal` falls from the first day to zero.',
+})
+export class SprintBurndownGql {
+  @Field(() => ID) sprintId!: string;
+  @Field(() => [String]) dates!: string[];
+  @Field(() => [Int], { nullable: 'items' }) scope!: (number | null)[];
+  @Field(() => [Int], { nullable: 'items' }) remaining!: (number | null)[];
+  @Field(() => [Int], { nullable: 'items' })
+  remainingPoints!: (number | null)[];
+  @Field(() => [Float]) ideal!: number[];
+}
+
+@ObjectType('SprintChange')
+export class SprintChangeGql {
+  @Field() action!: string;
+  @Field(() => Int) version!: number;
+  @Field(() => ID) actorId!: string;
+  @Field(() => ID) sprintId!: string;
+  @Field(() => SprintGql, { nullable: true, description: 'Null: deleted' })
+  sprint!: SprintGql | null;
+}
+
 @ObjectType('CountByStatus')
 export class CountByStatusGql {
   @Field({ description: 'Status id' }) key!: string;