first commit

libs/api/tracker/domain/src/lib/project/project-role.ts

@@ -0,0 +1,7 @@
+export enum ProjectRole {
+  OWNER = 'OWNER',
+  ADMIN = 'ADMIN',
+  MEMBER = 'MEMBER',
+  /** Read-only stakeholder (PM, client...). */
+  VIEWER = 'VIEWER',
+}

libs/api/tracker/domain/src/lib/project/project.spec.ts

@@ -0,0 +1,65 @@
+import {
+  BusinessRuleError,
+  ForbiddenError,
+  ValidationError,
+} from '@task-stream/api/shared/domain';
+import { ProjectFactory } from '../factories/project.factory';
+import { replay } from '../testing';
+import { Project } from './project';
+import { ProjectRole } from './project-role';
+
+const factory = new ProjectFactory();
+const newProject = () =>
+  factory.create({ key: 'ts', name: 'Task Stream', ownerId: 'owner' });
+
+describe('Project', () => {
+  it('normalises the key and makes the creator owner', () => {
+    const project = newProject();
+    expect(project.key).toBe('TS');
+    expect(project.roleOf('owner')).toBe(ProjectRole.OWNER);
+  });
+
+  it('validates the key', () => {
+    expect(() =>
+      factory.create({ key: '1x', name: 'n', ownerId: 'o' }),
+    ).toThrow(ValidationError);
+  });
+
+  it('lets admins manage members and viewers only read', () => {
+    const project = newProject();
+    project.addMember('owner', 'admin', ProjectRole.ADMIN);
+    project.addMember('admin', 'viewer', ProjectRole.VIEWER);
+
+    expect(() => project.assertCanContribute('viewer')).toThrow(ForbiddenError);
+    expect(() => project.addMember('viewer', 'x', ProjectRole.MEMBER)).toThrow(
+      ForbiddenError,
+    );
+    expect(() => project.assertCanView('stranger')).toThrow(ForbiddenError);
+  });
+
+  it('protects the owner', () => {
+    const project = newProject();
+    project.addMember('owner', 'admin', ProjectRole.ADMIN);
+    expect(() => project.removeMember('admin', 'owner')).toThrow(
+      BusinessRuleError,
+    );
+    expect(() =>
+      project.changeMemberRole('admin', 'owner', ProjectRole.MEMBER),
+    ).toThrow(BusinessRuleError);
+  });
+
+  it('rebuilds memberships from history', () => {
+    const project = newProject();
+    project.addMember('owner', 'dev', ProjectRole.MEMBER);
+    project.changeMemberRole('owner', 'dev', ProjectRole.ADMIN);
+    project.addMember('owner', 'qa', ProjectRole.MEMBER);
+    project.removeMember('qa', 'qa');
+
+    const { rebuilt } = replay(project, Project);
+    expect(rebuilt.members).toEqual([
+      { userId: 'owner', role: ProjectRole.OWNER },
+      { userId: 'dev', role: ProjectRole.ADMIN },
+    ]);
+    expect(rebuilt.version.value).toBe(5);
+  });
+});

libs/api/tracker/domain/src/lib/project/project.ts

@@ -0,0 +1,185 @@
+import {
+  BusinessRuleError,
+  ForbiddenError,
+  VersionedAggregateRoot,
+  assertThat,
+} from '@task-stream/api/shared/domain';
+import { ProjectCreatedEvent } from '../events/project-created.event';
+import { ProjectMemberAddedEvent } from '../events/project-member-added.event';
+import { ProjectMemberRemovedEvent } from '../events/project-member-removed.event';
+import { ProjectMemberRoleChangedEvent } from '../events/project-member-role-changed.event';
+import { ProjectUpdatedEvent } from '../events/project-updated.event';
+import { ProjectRole } from './project-role';
+
+export interface ProjectMember {
+  userId: string;
+  role: ProjectRole;
+}
+
+/** Data of a project (what ProjectCreatedEvent carries). */
+export interface ProjectProps {
+  id: string;
+  key: string;
+  name: string;
+  description: string | null;
+  ownerId: string;
+  members: ProjectMember[];
+  createdAt: string;
+  updatedAt: string;
+}
+
+/**
+ * Event-sourced aggregate: create it with ProjectFactory, load it with the
+ * AggregateRehydrator. State only changes in the `on<Event>` handlers.
+ */
+export class Project extends VersionedAggregateRoot implements ProjectProps {
+  public key!: string;
+  public name!: string;
+  public description: string | null = null;
+  public ownerId!: string;
+  public members: ProjectMember[] = [];
+  public createdAt!: string;
+  public updatedAt!: string;
+
+  constructor(id: string) {
+    super();
+    this.id = id;
+  }
+
+  roleOf(userId: string): ProjectRole | null {
+    return this.members.find((m) => m.userId === userId)?.role ?? null;
+  }
+
+  isMember(userId: string): boolean {
+    return this.roleOf(userId) !== null;
+  }
+
+  /** Can read the project. */
+  assertCanView(userId: string): void {
+    if (!this.isMember(userId)) {
+      throw new ForbiddenError(`You are not a member of project ${this.key}`);
+    }
+  }
+
+  /** Can create and modify tickets, comments, links... */
+  assertCanContribute(userId: string): void {
+    this.assertCanView(userId);
+    if (this.roleOf(userId) === ProjectRole.VIEWER) {
+      throw new ForbiddenError(`Viewers cannot modify project ${this.key}`);
+    }
+  }
+
+  /** Can manage members, releases and project settings. */
+  assertCanManage(userId: string): void {
+    const role = this.roleOf(userId);
+    if (role !== ProjectRole.OWNER && role !== ProjectRole.ADMIN) {
+      throw new ForbiddenError(
+        `Only owners and admins can manage project ${this.key}`,
+      );
+    }
+  }
+
+  updateDetails(
+    actorId: string,
+    changes: { name?: string; description?: string | null },
+  ): void {
+    this.assertCanManage(actorId);
+    const patch: { name?: string; description?: string | null } = {};
+    if (changes.name !== undefined) {
+      const name = changes.name.trim();
+      assertThat(name.length > 0, 'Project name is required');
+      if (name !== this.name) patch.name = name;
+    }
+    if (changes.description !== undefined) {
+      const description = changes.description?.trim() || null;
+      if (description !== this.description) patch.description = description;
+    }
+    if (Object.keys(patch).length === 0) return;
+    this.apply(new ProjectUpdatedEvent(actorId, this.id, patch));
+  }
+
+  addMember(actorId: string, userId: string, role: ProjectRole): void {
+    this.assertCanManage(actorId);
+    assertThat(role !== ProjectRole.OWNER, 'A project can only have one owner');
+    if (this.isMember(userId)) {
+      throw new BusinessRuleError(
+        `User ${userId} is already a member of ${this.key}`,
+      );
+    }
+    this.apply(new ProjectMemberAddedEvent(actorId, this.id, userId, role));
+  }
+
+  changeMemberRole(actorId: string, userId: string, role: ProjectRole): void {
+    this.assertCanManage(actorId);
+    assertThat(role !== ProjectRole.OWNER, 'A project can only have one owner');
+    const current = this.roleOf(userId);
+    if (!current)
+      throw new BusinessRuleError(
+        `User ${userId} is not a member of ${this.key}`,
+      );
+    if (current === ProjectRole.OWNER) {
+      throw new BusinessRuleError('The owner role cannot be changed');
+    }
+    if (current === role) return;
+    this.apply(
+      new ProjectMemberRoleChangedEvent(
+        actorId,
+        this.id,
+        userId,
+        role,
+        current,
+      ),
+    );
+  }
+
+  removeMember(actorId: string, userId: string): void {
+    // Anyone can leave a project; removing others requires manage rights.
+    if (actorId !== userId) this.assertCanManage(actorId);
+    if (!this.isMember(userId)) {
+      throw new BusinessRuleError(
+        `User ${userId} is not a member of ${this.key}`,
+      );
+    }
+    if (userId === this.ownerId) {
+      throw new BusinessRuleError('The project owner cannot be removed');
+    }
+    this.apply(new ProjectMemberRemovedEvent(actorId, this.id, userId));
+  }
+
+  /* ---- State transitions (also replayed by loadFromHistory) ---- */
+
+  onProjectCreatedEvent({ project }: ProjectCreatedEvent): void {
+    this.key = project.key;
+    this.name = project.name;
+    this.description = project.description;
+    this.ownerId = project.ownerId;
+    this.members = project.members.map((m) => ({ ...m }));
+    this.createdAt = project.createdAt;
+    this.updatedAt = project.updatedAt;
+  }
+
+  onProjectUpdatedEvent(event: ProjectUpdatedEvent): void {
+    Object.assign(this, event.changes);
+    this.updatedAt = event.occurredAt;
+  }
+
+  onProjectMemberAddedEvent(event: ProjectMemberAddedEvent): void {
+    this.members = [
+      ...this.members,
+      { userId: event.userId, role: event.role },
+    ];
+    this.updatedAt = event.occurredAt;
+  }
+
+  onProjectMemberRoleChangedEvent(event: ProjectMemberRoleChangedEvent): void {
+    this.members = this.members.map((m) =>
+      m.userId === event.userId ? { ...m, role: event.role } : m,
+    );
+    this.updatedAt = event.occurredAt;
+  }
+
+  onProjectMemberRemovedEvent(event: ProjectMemberRemovedEvent): void {
+    this.members = this.members.filter((m) => m.userId !== event.userId);
+    this.updatedAt = event.occurredAt;
+  }
+}