feat: public projects, project deletion and sagas

Public projects:
- Project.isPublic (create/update, owners and admins). Anyone can read a
  public project without a token: project, board, tickets, comments,
  history, releases, activity, tracking and statistics, over GraphQL and
  REST. Writes stay for members (401 anonymous, 403 outsiders).
- @OptionalAuth() / @ApiOptionalPireonAuth(): anonymous callers allowed,
  invalid tokens still rejected. ReadAccess lets anonymous viewers read
  public projects only; linked tickets are filtered by visibility.
- publicProjects (GraphQL) and GET /api/explore/projects (REST).
- Web: «Explorar» page, project pages open without a session (read-only
  notice, sign-in hints), public badge, visibility switch in settings,
  no realtime subscriptions without a session.

Project deletion:
- Owner only, confirming the key (deleteProject / DELETE
  /api/projects/{project}?confirm=KEY). The key is freed; the read model
  drops the project and members are notified (web goes home).

Sagas (run by the EventsBridge after projections, durable and ordered):
- ProjectDeletionSaga: project deleted → delete its tickets and releases;
  ticket deleted → purge its comments and drop links from other tickets.
- ReleaseArchivedSaga: unfinished tickets leave an archived release.
- UserDeactivatedSaga: the Pireon webhook records UserDeactivatedEvent in
  the event store (EventRecorder); the tracker unassigns that user's open
  tickets as the system actor.
- Internal idempotent commands; domain refusals are logged and skipped,
  concurrency conflicts retried. Affected streams come from the event store
  (TrackerStreamsRepository).

Tests: domain lifecycle specs, saga specs run like the bridge, facade
tests, e2e for public access, cascade deletion, archived releases and
deactivation webhook. Docs, READMEs, schema.gql/openapi.json and Word/PDF
updated.

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

libs/api/tracker/presenters/src/lib/http/dto/requests.dto.ts

@@ -73,12 +73,30 @@ export class CreateProjectDto {
   @IsString()
   @MaxLength(5000)
   description?: string | null;
+
+  @ApiPropertyOptional({
+    default: false,
+    description:
+      'Anyone can read it without signing in (board, tickets, comments, releases, activity, statistics)',
+  })
+  @IsOptional()
+  @IsBoolean()
+  isPublic?: boolean;
 }
 
 export class UpdateProjectDto extends PartialType(
   OmitType(CreateProjectDto, ['key'] as const),
 ) {}
 
+export class DeleteProjectQueryDto {
+  @ApiProperty({
+    example: 'WEB',
+    description: 'The project key, to confirm the deletion',
+  })
+  @IsString()
+  confirm!: string;
+}
+
 export class AddMemberDto {
   @ApiProperty({ description: 'Pireon user id (see GET /users)' })
   @IsString()

libs/api/tracker/presenters/src/lib/http/dto/responses.dto.ts

@@ -76,6 +76,8 @@ export class ProjectDto {
   key!: string;
   @ApiProperty({ example: 'Checkout revamp' }) name!: string;
   @ApiProperty({ type: String, nullable: true }) description!: string | null;
+  @ApiProperty({ description: 'Readable by anyone, also without a token' })
+  isPublic!: boolean;
   @ApiProperty({ type: UserRefDto }) owner!: UserRefDto;
   @ApiProperty({ type: [ProjectMemberDto] }) members!: ProjectMemberDto[];
   @ApiProperty({ type: ProjectSettingsDto })

libs/api/tracker/presenters/src/lib/http/explore.controller.ts

@@ -0,0 +1,25 @@
+import { Controller, Get } from '@nestjs/common';
+import { ApiOkResponse, ApiOperation, ApiTags } from '@nestjs/swagger';
+import { Public } from '@task-stream/api/identity/presenters';
+import { ProjectsService } from '@task-stream/api/tracker/application';
+import { ProjectDto } from './dto/responses.dto';
+import { toProjectDto } from './refs';
+
+/** What anyone can read without signing in. */
+@ApiTags('Explore')
+@Controller('explore')
+export class ExploreController {
+  constructor(private readonly projects: ProjectsService) {}
+
+  @Get('projects')
+  @Public()
+  @ApiOperation({
+    summary: 'Public projects (no token needed)',
+    description:
+      'Their board, tickets, comments, releases, activity and statistics can be read without a token too.',
+  })
+  @ApiOkResponse({ type: [ProjectDto] })
+  async publicProjects() {
+    return (await this.projects.findPublic()).map(toProjectDto);
+  }
+}

libs/api/tracker/presenters/src/lib/http/issues.controller.ts

@@ -18,6 +18,7 @@ import {
 } from '@nestjs/swagger';
 import { User } from '@task-stream/api/identity/domain';
 import {
+  ApiOptionalPireonAuth,
   ApiPireonAuth,
   CurrentUser,
 } from '@task-stream/api/identity/presenters';
@@ -51,6 +52,7 @@ import {
   IssueDto,
   IssuePageDto,
 } from './dto/responses.dto';
+import { viewerOf } from '../common/viewer';
 import { Refs } from './refs';
 
 const PROJECT = ApiParam({
@@ -95,17 +97,18 @@ export class IssuesController {
   }
 
   @Get('projects/:project/issues')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({ summary: 'Search the tickets of a project' })
   @ApiOkResponse({ type: IssuePageDto })
   @ApiReadErrors()
   async search(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('project') project: string,
     @Query() query: IssueSearchQueryDto,
   ) {
-    const page = await this.issues.search(me.id, {
-      projectId: await this.refs.projectId(me.id, project),
+    const page = await this.issues.search(viewerOf(me), {
+      projectId: await this.refs.projectId(viewerOf(me), project),
       statuses: query.status,
       categories: query.category,
       types: query.type,
@@ -143,12 +146,16 @@ export class IssuesController {
   }
 
   @Get('issues/:issue')
+  @ApiOptionalPireonAuth()
   @ISSUE
   @ApiOperation({ summary: 'A ticket' })
   @ApiOkResponse({ type: IssueDto })
   @ApiReadErrors()
-  async findOne(@CurrentUser() me: User, @Param('issue') issue: string) {
-    return this.refs.issueDto(await this.issues.findOne(me.id, issue));
+  async findOne(
+    @CurrentUser() me: User | undefined,
+    @Param('issue') issue: string,
+  ) {
+    return this.refs.issueDto(await this.issues.findOne(viewerOf(me), issue));
   }
 
   @Patch('issues/:issue')
@@ -271,18 +278,19 @@ export class IssuesController {
   }
 
   @Get('issues/:issue/comments')
+  @ApiOptionalPireonAuth()
   @ISSUE
   @ApiOperation({ summary: 'Comments of the ticket (oldest first)' })
   @ApiOkResponse({ type: CommentPageDto })
   @ApiReadErrors()
   async listComments(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('issue') issue: string,
     @Query() page: PageQueryDto,
   ) {
     return this.comments.list(
-      me.id,
-      await this.refs.issueId(me.id, issue),
+      viewerOf(me),
+      await this.refs.issueId(viewerOf(me), issue),
       page.limit,
       page.offset,
     );
@@ -306,17 +314,18 @@ export class IssuesController {
   }
 
   @Get('issues/:issue/history')
+  @ApiOptionalPireonAuth()
   @ISSUE
   @ApiOperation({ summary: 'History of the ticket (newest first)' })
   @ApiOkResponse({ type: [ActivityDto] })
   @ApiReadErrors()
   async history(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('issue') issue: string,
     @Query() page: PageQueryDto,
   ) {
-    const found = await this.issues.findOne(me.id, issue);
-    return this.issues.activity(me.id, {
+    const found = await this.issues.findOne(viewerOf(me), issue);
+    return this.issues.activity(viewerOf(me), {
       projectId: found.projectId,
       issueId: found.id,
       limit: page.limit,

libs/api/tracker/presenters/src/lib/http/projects.controller.ts

@@ -19,6 +19,7 @@ import {
 import { User } from '@task-stream/api/identity/domain';
 import {
   AccessToken,
+  ApiOptionalPireonAuth,
   ApiPireonAuth,
   CurrentUser,
 } from '@task-stream/api/identity/presenters';
@@ -37,6 +38,7 @@ import {
   BoardQueryDto,
   ChangeMemberRoleDto,
   CreateProjectDto,
+  DeleteProjectQueryDto,
   ProjectSettingsBodyDto,
   UpdateProjectDto,
 } from './dto/requests.dto';
@@ -49,6 +51,7 @@ import {
   ProjectStatsDto,
 } from './dto/responses.dto';
 import { fromSettingsPayload } from '../common/settings';
+import { viewerOf } from '../common/viewer';
 import { Refs, toProjectDto } from './refs';
 
 const PROJECT = ApiParam({
@@ -85,17 +88,23 @@ export class ProjectsController {
   }
 
   @Get(':project')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({ summary: 'A project with its members and settings' })
   @ApiOkResponse({ type: ProjectDto })
   @ApiReadErrors()
-  async findOne(@CurrentUser() me: User, @Param('project') project: string) {
-    return toProjectDto(await this.projects.findOne(me.id, project));
+  async findOne(
+    @CurrentUser() me: User | undefined,
+    @Param('project') project: string,
+  ) {
+    return toProjectDto(await this.projects.findOne(viewerOf(me), project));
   }
 
   @Patch(':project')
   @PROJECT
-  @ApiOperation({ summary: 'Rename or describe a project (owner/admin)' })
+  @ApiOperation({
+    summary: 'Rename, describe or make public/private a project (owner/admin)',
+  })
   @ApiOkResponse({ type: CommandResultDto })
   @ApiCommandErrors()
   async update(
@@ -110,6 +119,29 @@ export class ProjectsController {
     );
   }
 
+  @Delete(':project')
+  @PROJECT
+  @ApiOperation({
+    summary: 'Delete a project (owner only)',
+    description:
+      'Deletes the project and, right after (asynchronously, through a saga), its tickets, comments and releases; ' +
+      'links from tickets of other projects are removed and the key becomes free. Cannot be undone from the API. ' +
+      '`confirm` must be the project key.',
+  })
+  @ApiOkResponse({ type: CommandResultDto })
+  @ApiCommandErrors()
+  async remove(
+    @CurrentUser() me: User,
+    @Param('project') project: string,
+    @Query() query: DeleteProjectQueryDto,
+  ) {
+    return this.projects.delete(
+      me.id,
+      await this.refs.projectId(me.id, project),
+      query.confirm,
+    );
+  }
+
   @Put(':project/settings')
   @PROJECT
   @ApiOperation({
@@ -133,19 +165,20 @@ export class ProjectsController {
   }
 
   @Get(':project/board')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({ summary: 'Kanban board: one column per status' })
   @ApiOkResponse({ type: [BoardColumnDto] })
   @ApiReadErrors()
   async board(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('project') project: string,
     @Query() query: BoardQueryDto,
   ) {
     const columns = await this.projects.board(
-      me.id,
+      viewerOf(me),
       {
-        projectId: await this.refs.projectId(me.id, project),
+        projectId: await this.refs.projectId(viewerOf(me), project),
         releaseId: query.releaseId,
         assigneeId: query.assigneeId,
         areas: query.area ? [query.area] : undefined,
@@ -161,20 +194,25 @@ export class ProjectsController {
   }
 
   @Get(':project/stats')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({
     summary: 'Tracking dashboard: counts by status, type, person…',
   })
   @ApiOkResponse({ type: ProjectStatsDto })
   @ApiReadErrors()
-  async stats(@CurrentUser() me: User, @Param('project') project: string) {
+  async stats(
+    @CurrentUser() me: User | undefined,
+    @Param('project') project: string,
+  ) {
     return this.projects.stats(
-      me.id,
-      await this.refs.projectId(me.id, project),
+      viewerOf(me),
+      await this.refs.projectId(viewerOf(me), project),
     );
   }
 
   @Get(':project/analytics')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({
     summary: 'Statistics of the last `days` days',
@@ -184,29 +222,30 @@ export class ProjectsController {
   @ApiOkResponse({ type: ProjectAnalyticsDto })
   @ApiReadErrors()
   async analytics(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('project') project: string,
     @Query() query: AnalyticsQueryDto,
   ) {
     return this.projects.analytics(
-      me.id,
-      await this.refs.projectId(me.id, project),
+      viewerOf(me),
+      await this.refs.projectId(viewerOf(me), project),
       query.days,
     );
   }
 
   @Get(':project/activity')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({ summary: 'Activity feed (newest first)' })
   @ApiOkResponse({ type: [ActivityDto] })
   @ApiReadErrors()
   async activity(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('project') project: string,
     @Query() query: ActivityQueryDto,
   ) {
-    return this.issues.activity(me.id, {
-      projectId: await this.refs.projectId(me.id, project),
+    return this.issues.activity(viewerOf(me), {
+      projectId: await this.refs.projectId(viewerOf(me), project),
       issueId: query.issueId,
       limit: query.limit,
       before: query.before,

libs/api/tracker/presenters/src/lib/http/refs.ts

@@ -25,12 +25,12 @@ export class Refs {
     private readonly workflows: WorkflowsService,
   ) {}
 
-  async projectId(viewerId: string, ref: string): Promise<string> {
+  async projectId(viewerId: string | null, ref: string): Promise<string> {
     if (UUID.test(ref)) return ref;
     return (await this.projects.findOne(viewerId, ref)).id;
   }
 
-  async issueId(viewerId: string, ref: string): Promise<string> {
+  async issueId(viewerId: string | null, ref: string): Promise<string> {
     if (UUID.test(ref)) return ref;
     return (await this.issues.findOne(viewerId, ref)).id;
   }

libs/api/tracker/presenters/src/lib/http/releases.controller.ts

@@ -17,6 +17,7 @@ import {
 } from '@nestjs/swagger';
 import { User } from '@task-stream/api/identity/domain';
 import {
+  ApiOptionalPireonAuth,
   ApiPireonAuth,
   CurrentUser,
 } from '@task-stream/api/identity/presenters';
@@ -43,6 +44,7 @@ import {
   ReleaseBurnupDto,
   ReleaseProgressDto,
 } from './dto/responses.dto';
+import { viewerOf } from '../common/viewer';
 import { Refs } from './refs';
 
 const PROJECT = ApiParam({
@@ -74,14 +76,18 @@ export class ReleasesController {
   }
 
   @Get('projects/:project/releases')
+  @ApiOptionalPireonAuth()
   @PROJECT
   @ApiOperation({ summary: 'Releases of a project' })
   @ApiOkResponse({ type: [ReleaseDto] })
   @ApiReadErrors()
-  async list(@CurrentUser() me: User, @Param('project') project: string) {
+  async list(
+    @CurrentUser() me: User | undefined,
+    @Param('project') project: string,
+  ) {
     return this.projects.releases(
-      me.id,
-      await this.refs.projectId(me.id, project),
+      viewerOf(me),
+      await this.refs.projectId(viewerOf(me), project),
     );
   }
 
@@ -102,11 +108,15 @@ export class ReleasesController {
   }
 
   @Get('releases/:releaseId')
+  @ApiOptionalPireonAuth()
   @ApiOperation({ summary: 'A release' })
   @ApiOkResponse({ type: ReleaseDto })
   @ApiReadErrors()
-  findOne(@CurrentUser() me: User, @Param('releaseId') releaseId: string) {
-    return this.releases.findOne(me.id, releaseId);
+  findOne(
+    @CurrentUser() me: User | undefined,
+    @Param('releaseId') releaseId: string,
+  ) {
+    return this.releases.findOne(viewerOf(me), releaseId);
   }
 
   @Patch('releases/:releaseId')
@@ -122,34 +132,43 @@ export class ReleasesController {
   }
 
   @Get('releases/:releaseId/progress')
+  @ApiOptionalPireonAuth()
   @ApiOperation({ summary: 'Finished tickets out of the total' })
   @ApiOkResponse({ type: ReleaseProgressDto })
   @ApiReadErrors()
-  progress(@CurrentUser() me: User, @Param('releaseId') releaseId: string) {
-    return this.releases.progress(me.id, releaseId);
+  progress(
+    @CurrentUser() me: User | undefined,
+    @Param('releaseId') releaseId: string,
+  ) {
+    return this.releases.progress(viewerOf(me), releaseId);
   }
 
   @Get('releases/:releaseId/burnup')
+  @ApiOptionalPireonAuth()
   @ApiOperation({
     summary: 'Burnup: tickets in the release and finished ones, day by day',
   })
   @ApiOkResponse({ type: ReleaseBurnupDto })
   @ApiReadErrors()
-  burnup(@CurrentUser() me: User, @Param('releaseId') releaseId: string) {
-    return this.releases.burnup(me.id, releaseId);
+  burnup(
+    @CurrentUser() me: User | undefined,
+    @Param('releaseId') releaseId: string,
+  ) {
+    return this.releases.burnup(viewerOf(me), releaseId);
   }
 
   @Get('releases/:releaseId/issues')
+  @ApiOptionalPireonAuth()
   @ApiOperation({ summary: 'Tickets included in the release' })
   @ApiOkResponse({ type: IssuePageDto })
   @ApiReadErrors()
   async issuesOf(
-    @CurrentUser() me: User,
+    @CurrentUser() me: User | undefined,
     @Param('releaseId') releaseId: string,
     @Query() page: PageQueryDto,
   ) {
-    const release = await this.releases.findOne(me.id, releaseId);
-    const found = await this.issues.search(me.id, {
+    const release = await this.releases.findOne(viewerOf(me), releaseId);
+    const found = await this.issues.search(viewerOf(me), {
       projectId: release.projectId,
       releaseId: release.id,
       limit: page.limit,