Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

17.5 KB
Raw Blame
import { Elysia, t } from 'elysia';
import { assertProjectWritable, requireUser } from '#shared/access';
import { authContext } from '#shared/auth-context';
import { guards } from '#shared/guards';
import { noContent } from '#shared/http';
import { HttpError } from '#shared/lib';
import { paginate } from '#shared/pagination';
import { errors } from '#shared/responses';
import { isMcpRequest } from '#shared/mcp-request';
import { mcpTool } from '#mcp/generate';
import {
  ProjectResponse,
  copyProjectBody,
  createProjectBody,
  updateProjectBody,
} from '#modules/projects/model';
import {
  createProject,
  deleteProject,
  setProjectArchived,
  updateProject,
} from '#modules/projects/service';
import { copyProject } from '#modules/projects/copy';
import { createProjectFromTemplate } from '#modules/project-templates/service';
import {
  TeamDetailResponse,
  TeamListResponse,
  TeamMcpResponse,
  TeamProjectDefaultsResponse,
  TeamMemberPageResponse,
  TeamProjectDetailResponse,
  TeamProjectMemberPageResponse,
  TeamProjectOptionListResponse,
  TeamProjectPageResponse,
  TeamResponse,
  createTeamBody,
  setTeamMemberRoleBody,
  teamMemberParams,
  teamParams,
  teamProjectListQuery,
  teamProjectParams,
  memberListQuery,
  updateTeamBody,
  updateTeamMcpBody,
  updateTeamProjectDefaultsBody,
} from './model';
import {
  createTeam,
  deleteTeam,
  getTeam,
  getTeamProject,
  leaveTeam,
  listTeamMembers,
  listTeamProjectMembers,
  listTeamProjectOptions,
  listTeamProjects,
  listTeams,
  removeTeamMember,
  updateTeam,
  setTeamMcp,
  getTeamProjectDefaults,
  setTeamProjectDefaults,
  setTeamMemberRole,
  teamOwnsProject,
} from './service';

// The write routes act on a project the team owns; one of another team answers 404
// rather than being changed through this team.
async function requireTeamProject(teamId: number, projectId: number): Promise<void> {
  if (!(await teamOwnsProject(teamId, projectId))) throw new HttpError(404, 'Project not found');
}

// The teams the session user belongs to. A team owns projects and its own member
// list. Only the owner of a workspace creates a team in it, and becomes the team's owner.
export const teamRoutes = new Elysia({ name: 'teams', detail: { tags: ['Teams'] } })
  .use(authContext)
  .use(guards)

  .get(
    '/teams',
    ({ user, request }) =>
      listTeams(requireUser(user).id, { mcpOnly: isMcpRequest(request.headers) }),
    {
      response: { 200: TeamListResponse, ...errors(401) },
      detail: {
        summary: 'List teams',
        description:
          'List the teams you are a member of, with your rank in each. Over MCP, the team is ' +
          'taken from your key when you belong to one; call this to pick a team when a tool ' +
          'asks for a teamId. Only teams with MCP switched on are listed there.',
        ...mcpTool('list_teams'),
      },
    },
  )

  .get(
    '/teams/:teamId',
    async ({ membership }) => {
      const team = await getTeam(membership.teamId, membership.userId);
      if (!team) throw new HttpError(404, 'Team not found');
      return team;
    },
    {
      teamMember: true,
      params: teamParams,
      response: { 200: TeamDetailResponse, ...errors(401, 404) },
      detail: {
        summary: 'Get a team',
        description:
          'A team, with how many projects, members, roles and integration credentials it ' +
          'holds, and what you may do with them. Its members and its projects are listed ' +
          'by their own routes.',
      },
    },
  )

  .get(
    '/teams/:teamId/members',
    ({ membership, query }) =>
      paginate(query, (window) =>
        listTeamMembers(membership.teamId, {
          search: query.search,
          kind: query.kind,
          ...window,
        }),
      ),
    {
      teamMember: true,
      params: teamParams,
      query: memberListQuery,
      response: { 200: TeamMemberPageResponse, ...errors(401, 404) },
      detail: {
        summary: 'List team members',
        description:
          'One page of the members of a team you belong to, by name. `search` matches the ' +
          'name, the address or the handle, and `kind` narrows the list to the people or to ' +
          'the AI agents.',
      },
    },
  )

  .get(
    '/teams/:teamId/projects',
    ({ membership, query }) =>
      paginate(query, (window) =>
        listTeamProjects(membership.teamId, membership.userId, membership.role, {
          search: query.search,
          ...window,
        }),
      ),
    {
      teamMember: true,
      params: teamParams,
      query: teamProjectListQuery,
      response: { 200: TeamProjectPageResponse, ...errors(401, 404) },
      detail: {
        summary: 'List team projects',
        description:
          'One page of the projects a team owns, by key. `search` matches the key or the ' +
          'name. An owner or a manager, and anyone whose workspace role reaches the team, sees ' +
          'them all; anyone else only the ones they belong to.',
      },
    },
  )

  // Fills the project picker on an agent and the MCP switches, which act on every
  // project of the team rather than on a page of them.
  .get(
    '/teams/:teamId/projects/options',
    ({ membership }) =>
      listTeamProjectOptions(membership.teamId, membership.userId, membership.role),
    {
      teamMember: true,
      params: teamParams,
      response: { 200: TeamProjectOptionListResponse, ...errors(401, 404) },
      detail: {
        summary: 'List team project options',
        description: 'Every project the reader has in the team: id, key, name and MCP reach.',
      },
    },
  )

  .get(
    '/teams/:teamId/projects/:projectId',
    async ({ membership, params }) => {
      const detail = await getTeamProject(
        membership.teamId,
        params.projectId,
        membership.userId,
        membership.role,
      );
      if (!detail) throw new HttpError(404, 'Project not found');
      return detail;
    },
    {
      teamMember: true,
      params: teamProjectParams,
      response: { 200: TeamProjectDetailResponse, ...errors(401, 404) },
      detail: {
        summary: 'Get a project the team owns',
        description:
          'How one project of the team is doing and who can reach it, with what each membership resolves to. An owner or a manager may read it for any project of the team; anyone else only for one they belong to.',
      },
    },
  )

  .get(
    '/teams/:teamId/projects/:projectId/members',
    ({ membership, params, query }) =>
      paginate(query, async (window) => {
        const page = await listTeamProjectMembers(
          membership.teamId,
          params.projectId,
          membership.userId,
          membership.role,
          { search: query.search, kind: query.kind, ...window },
        );
        if (!page) throw new HttpError(404, 'Project not found');
        return page;
      }),
    {
      teamMember: true,
      params: teamProjectParams,
      query: memberListQuery,
      response: { 200: TeamProjectMemberPageResponse, ...errors(401, 404) },
      detail: {
        summary: "List a project's members",
        description:
          'One page of the members of one project of the team, owners first. `search` ' +
          'matches the name, the address or the handle, and `kind` narrows the list to the ' +
          'people or to the AI agents. An owner or a manager may read it for any project of ' +
          'the team; anyone else only for one they belong to.',
      },
    },
  )

  // The team's MCP settings: whether it is reachable at all, and which of its projects
  // that reach covers. Written by an owner or a manager, who run the team; the current
  // state is read off the team list and its projects, which both carry it. Not an MCP
  // tool: it governs MCP access, so an agent must not change it.
  .patch('/teams/:teamId/mcp', ({ body, membership }) => setTeamMcp(membership.teamId, body), {
    teamManager: true,
    params: teamParams,
    body: updateTeamMcpBody,
    response: { 200: TeamMcpResponse, ...errors(400, 401, 403, 404) },
    detail: {
      summary: "Update a team's MCP settings",
      description:
        'Switch MCP on or off for the team, and set which of its projects the reach covers. ' +
        'Each field is optional; a project of another team is ignored.',
    },
  })

  .get(
    '/teams/:teamId/project-defaults',
    ({ membership }) => getTeamProjectDefaults(membership.teamId),
    {
      teamMember: true,
      params: teamParams,
      response: { 200: TeamProjectDefaultsResponse, ...errors(401, 403, 404) },
      detail: { summary: "Get a team's defaults for new projects" },
    },
  )

  .patch(
    '/teams/:teamId/project-defaults',
    ({ body, membership }) => setTeamProjectDefaults(membership.teamId, body.defaultAgentIds),
    {
      teamManager: true,
      params: teamParams,
      body: updateTeamProjectDefaultsBody,
      response: { 200: TeamProjectDefaultsResponse, ...errors(400, 401, 403, 404) },
      detail: { summary: "Set the team's default agents for new projects" },
    },
  )

  .post(
    '/teams',
    async ({ body, user, set }) => {
      const name = body.name.trim();
      if (!name) throw new HttpError(400, 'Team name is required');
      set.status = 201;
      return createTeam(name, body.slug, requireUser(user).id, body.workspaceId);
    },
    {
      body: createTeamBody,
      response: { 201: TeamResponse, ...errors(400, 401, 403, 409) },
      detail: {
        summary: 'Create a team',
        description:
          'Create a team in a workspace and become its owner. The workspace decides who may: ' +
          'its owner, also its admins, or anyone in its teams.',
      },
    },
  )

  .patch(
    '/teams/:teamId',
    async ({ body, membership }) => {
      const name = body.name?.trim();
      if (name === '') throw new HttpError(400, 'Team name is required');
      return updateTeam(membership.teamId, { name, slug: body.slug }, membership.userId);
    },
    {
      teamOwner: true,
      params: teamParams,
      body: updateTeamBody,
      response: { 200: TeamResponse, ...errors(400, 401, 403, 404, 409) },
      detail: {
        summary: 'Update a team',
        description: 'Rename a team you own, or set the slug its web URLs use.',
      },
    },
  )

  .delete(
    '/teams/:teamId',
    async ({ membership }) => {
      await deleteTeam(membership.teamId);
      return noContent();
    },
    {
      teamOwner: true,
      params: teamParams,
      response: { 204: t.Void(), ...errors(401, 403, 404, 409) },
      detail: {
        summary: 'Delete a team',
        description:
          'Delete a team you own, with its members, roles, invites, skills, tools and ' +
          'integrations. A team that holds a project or an AI agent is refused until those ' +
          'are gone. Irreversible.',
      },
    },
  )

  .post(
    '/teams/:teamId/projects',
    async ({ body, membership, set }) => {
      set.status = 201;
      const { templateId, ...input } = body;
      return templateId === undefined
        ? createProject(input, membership.userId, membership.teamId)
        : createProjectFromTemplate(membership.teamId, templateId, input, membership.userId);
    },
    {
      teamManager: true,
      params: teamParams,
      body: createProjectBody,
      response: { 201: ProjectResponse, ...errors(400, 401, 403, 404, 409) },
      detail: {
        summary: 'Create a project',
        description:
          'Create a project in a team you own or manage and become its owner. `key` is the ' +
          "immutable prefix for issue ids, unique within the team (e.g. 'MKT' -> 'MKT-1'). " +
          'Seeds the default columns and the issue types of the chosen `preset`, or copies ' +
          'what the project template `templateId` holds. Over MCP, ' +
          'uses the team from your key when there is one; otherwise call list_teams and pass ' +
          'teamId.',
        ...mcpTool('create_project'),
      },
    },
  )

  .post(
    '/teams/:teamId/projects/:projectId/copy',
    async ({ body, membership, params, set }) => {
      await requireTeamProject(membership.teamId, params.projectId);
      const { include, ...meta } = body;
      set.status = 201;
      return copyProject(params.projectId, meta, membership.userId, membership.teamId, include);
    },
    {
      teamManager: true,
      params: teamProjectParams,
      body: copyProjectBody,
      response: { 201: ProjectResponse, ...errors(400, 401, 403, 404, 409) },
      detail: {
        summary: 'Copy a project of the team',
        description:
          "Copy a project's configuration into a new project of the same team, without its " +
          "issues. The caller becomes the copy's owner, and needs no membership in the " +
          'source project.',
      },
    },
  )

  .patch(
    '/teams/:teamId/projects/:projectId',
    async ({ body, membership, params, request }) => {
      await requireTeamProject(membership.teamId, params.projectId);
      await assertProjectWritable(params.projectId, request.method);
      const updated = await updateProject(params.projectId, body);
      if (!updated) throw new HttpError(404, 'Project not found');
      return updated;
    },
    {
      teamManager: true,
      params: teamProjectParams,
      body: updateProjectBody,
      response: { 200: ProjectResponse, ...errors(400, 401, 403, 404, 409) },
      detail: {
        summary: 'Update a project of the team',
        description:
          'Update the name and/or description of a project the team owns. The key changes ' +
          'only when it does not match the key pattern, for example one that starts with a ' +
          'digit. A key that another project of the team has is refused with 409.',
      },
    },
  )

  .post(
    '/teams/:teamId/projects/:projectId/archive',
    async ({ membership, params }) => {
      await requireTeamProject(membership.teamId, params.projectId);
      const updated = await setProjectArchived(params.projectId, true);
      if (!updated) throw new HttpError(404, 'Project not found');
      return updated;
    },
    {
      teamManager: true,
      params: teamProjectParams,
      response: { 200: ProjectResponse, ...errors(401, 403, 404) },
      detail: {
        summary: 'Archive a project of the team',
        description:
          'Archive a project the team owns. It leaves the project lists of its members and ' +
          'list_projects, becomes read-only, and its agent schedules stop running. Nothing ' +
          'in it is deleted, and it can still be copied or deleted.',
      },
    },
  )

  .post(
    '/teams/:teamId/projects/:projectId/restore',
    async ({ membership, params }) => {
      await requireTeamProject(membership.teamId, params.projectId);
      const updated = await setProjectArchived(params.projectId, false);
      if (!updated) throw new HttpError(404, 'Project not found');
      return updated;
    },
    {
      teamManager: true,
      params: teamProjectParams,
      response: { 200: ProjectResponse, ...errors(401, 403, 404) },
      detail: { summary: 'Restore an archived project of the team' },
    },
  )

  .delete(
    '/teams/:teamId/projects/:projectId',
    async ({ membership, params }) => {
      await requireTeamProject(membership.teamId, params.projectId);
      await deleteProject(params.projectId);
      return noContent();
    },
    {
      teamOwner: true,
      params: teamProjectParams,
      response: { 204: t.Void(), ...errors(401, 403, 404) },
      detail: {
        summary: 'Delete a project of the team',
        description:
          'Permanently delete a project the team owns and everything in it. Irreversible.',
      },
    },
  )

  // The rank a member holds in the team. Run by an owner or a manager, who run the
  // team; an agent's rank is set with the agent, not here.
  .patch(
    '/teams/:teamId/members/:userId',
    async ({ body, membership, params }) => {
      await setTeamMemberRole(membership.teamId, membership, params.userId, body.role);
      return noContent();
    },
    {
      teamManager: true,
      params: teamMemberParams,
      body: setTeamMemberRoleBody,
      response: { 204: t.Void(), ...errors(401, 403, 404, 409) },
      detail: {
        summary: "Update a member's rank in the team",
        description:
          'Set what a member ranks as in the team. Only an owner grants the owner rank or ' +
          'changes what another owner holds.',
      },
    },
  )

  // An agent is removed with its agent settings, not here.
  .delete(
    '/teams/:teamId/members/:userId',
    async ({ membership, params }) => {
      await removeTeamMember(membership.teamId, membership.userId, params.userId);
      return noContent();
    },
    {
      teamOwner: true,
      params: teamMemberParams,
      response: { 204: t.Void(), ...errors(401, 403, 404, 409) },
      detail: {
        summary: 'Remove a member from the team',
        description:
          'Remove a member from the team and from every project the team owns. The issues ' +
          'they were assigned to and the work they logged stay as they are. A membership a ' +
          'provisioned group granted is managed by the identity provider.',
      },
    },
  )

  .post(
    '/teams/:teamId/leave',
    async ({ membership }) => {
      await leaveTeam(membership.teamId, membership.userId);
      return noContent();
    },
    {
      teamMember: true,
      params: teamParams,
      response: { 204: t.Void(), ...errors(401, 404, 409) },
      detail: {
        summary: 'Leave a team',
        description:
          'Leave a team you belong to, and every project it owns. The last owner cannot ' +
          'leave, and neither can a member a provisioned group put there; the projects stay ' +
          'with the team.',
      },
    },
  );