@shipfox/api-workspaces 9.3.0 → 10.1.0

package/src/db/memberships.ts

@@ -1,5 +1,6 @@
 import {and, eq, sql} from 'drizzle-orm';
 import type {Membership} from '#core/entities/membership.js';
+import type {Workspace} from '#core/entities/workspace.js';
 import {LastMemberError} from '#core/errors.js';
 import {recordWorkspaceMembershipChanged} from '#metrics/instance.js';
 import {db} from './db.js';
@@ -58,6 +59,7 @@ export async function ensureMembership(params: EnsureMembershipParams): Promise<
 
 export interface MembershipWithWorkspace extends Membership {
   workspaceName: string;
+  workspaceStatus: Workspace['status'];
 }
 
 export async function listMembershipsByUser(params: {
@@ -67,13 +69,18 @@ export async function listMembershipsByUser(params: {
     .select({
       membership: memberships,
       workspaceName: workspaces.name,
+      workspaceStatus: workspaces.status,
     })
     .from(memberships)
     .innerJoin(workspaces, eq(workspaces.id, memberships.workspaceId))
     .where(eq(memberships.userId, params.userId))
     .orderBy(workspaces.name);
 
-  return rows.map((row) => ({...toMembership(row.membership), workspaceName: row.workspaceName}));
+  return rows.map((row) => ({
+    ...toMembership(row.membership),
+    workspaceName: row.workspaceName,
+    workspaceStatus: row.workspaceStatus,
+  }));
 }
 
 export interface MembershipWithUser extends Membership {

package/src/db/schema/workspaces.ts

@@ -1,5 +1,5 @@
 import {uuidv7PrimaryKey} from '@shipfox/node-drizzle';
-import {jsonb, pgEnum, text, timestamp, uuid} from 'drizzle-orm/pg-core';
+import {index, jsonb, pgEnum, text, timestamp, uuid} from 'drizzle-orm/pg-core';
 import type {Workspace, WorkspaceStatus} from '#core/entities/workspace.js';
 import {pgTable} from './common.js';
 
@@ -9,15 +9,19 @@ export const workspaceStatusEnum = pgEnum('workspaces_workspace_status', [
   'deleted',
 ]);
 
-export const workspaces = pgTable('workspaces', {
-  id: uuidv7PrimaryKey(),
-  name: text('name').notNull(),
-  status: workspaceStatusEnum('status').notNull().default('active'),
-  settings: jsonb('settings').notNull().default({}),
-  createdBy: uuid('created_by'),
-  createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
-  updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
-});
+export const workspaces = pgTable(
+  'workspaces',
+  {
+    id: uuidv7PrimaryKey(),
+    name: text('name').notNull(),
+    status: workspaceStatusEnum('status').notNull().default('active'),
+    settings: jsonb('settings').notNull().default({}),
+    createdBy: uuid('created_by'),
+    createdAt: timestamp('created_at', {withTimezone: true}).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', {withTimezone: true}).notNull().defaultNow(),
+  },
+  (table) => [index('workspaces_name_id_idx').on(table.name, table.id)],
+);
 
 export type WorkspaceDb = typeof workspaces.$inferSelect;
 export type WorkspaceCreateDb = typeof workspaces.$inferInsert;

package/src/db/workspaces.test.ts

@@ -4,6 +4,7 @@ import {
   createWorkspace,
   getWorkspaceById,
   getWorkspaceServiceMetrics,
+  listAdminWorkspaces,
   updateWorkspace,
 } from './workspaces.js';
 
@@ -112,4 +113,28 @@ describe('workspace queries', () => {
       expect(metrics.openInvitations).toBeGreaterThanOrEqual(1);
     });
   });
+
+  describe('listAdminWorkspaces', () => {
+    test('returns bounded, name-ordered pages with member counts', async () => {
+      const prefix = `Admin page ${crypto.randomUUID()}`;
+      const alpha = await createWorkspace({name: `${prefix} Alpha`});
+      const bravo = await createWorkspace({name: `${prefix} Bravo`});
+      const charlie = await createWorkspace({name: `${prefix} Charlie`});
+      await createMembership({userId: crypto.randomUUID(), workspaceId: bravo.id});
+      await createMembership({userId: crypto.randomUUID(), workspaceId: bravo.id});
+
+      const firstPage = await listAdminWorkspaces({search: prefix, limit: 2});
+      const secondPage = await listAdminWorkspaces({
+        search: prefix,
+        limit: 2,
+        cursor: firstPage.nextCursor ?? undefined,
+      });
+
+      expect(firstPage.workspaces.map(({id}) => id)).toEqual([alpha.id, bravo.id]);
+      expect(firstPage.workspaces.map(({memberCount}) => memberCount)).toEqual([0, 2]);
+      expect(firstPage.nextCursor).toEqual({value: bravo.name, id: bravo.id});
+      expect(secondPage.workspaces.map(({id}) => id)).toEqual([charlie.id]);
+      expect(secondPage.nextCursor).toBeNull();
+    });
+  });
 });

package/src/db/workspaces.ts

@@ -1,4 +1,5 @@
-import {and, count, eq, gt, isNull, sql} from 'drizzle-orm';
+import type {StringIdCursor} from '@shipfox/node-drizzle';
+import {and, asc, count, eq, gt, ilike, inArray, isNull, or, type SQL, sql} from 'drizzle-orm';
 import type {Workspace, WorkspaceStatus} from '#core/entities/workspace.js';
 import {recordWorkspaceCreated} from '#metrics/instance.js';
 import {db} from './db.js';
@@ -57,6 +58,79 @@ export async function getWorkspaceById(id: string): Promise<Workspace | undefine
   return toWorkspace(row);
 }
 
+export interface AdminWorkspaceRow extends Workspace {
+  memberCount: number;
+}
+
+export interface ListAdminWorkspaceParams {
+  workspaceId?: string | undefined;
+  search?: string | undefined;
+  status?: WorkspaceStatus | undefined;
+  limit: number;
+  cursor?: StringIdCursor | undefined;
+}
+
+export interface ListAdminWorkspaceResult {
+  workspaces: AdminWorkspaceRow[];
+  nextCursor: StringIdCursor | null;
+}
+
+function adminWorkspaceCursorWhere(cursor: StringIdCursor | undefined): SQL | undefined {
+  if (!cursor) return undefined;
+  return or(
+    gt(workspaces.name, cursor.value),
+    and(eq(workspaces.name, cursor.value), gt(workspaces.id, cursor.id)),
+  );
+}
+
+export async function listAdminWorkspaces(
+  params: ListAdminWorkspaceParams,
+): Promise<ListAdminWorkspaceResult> {
+  const conditions = [] as SQL[];
+  if (params.workspaceId) conditions.push(eq(workspaces.id, params.workspaceId));
+  if (params.search) {
+    conditions.push(ilike(workspaces.name, `%${escapeIlikePattern(params.search)}%`));
+  }
+  if (params.status) conditions.push(eq(workspaces.status, params.status));
+  const cursor = adminWorkspaceCursorWhere(params.cursor);
+  if (cursor) conditions.push(cursor);
+
+  const rows = await db()
+    .select({workspace: workspaces})
+    .from(workspaces)
+    .where(conditions.length > 0 ? and(...conditions) : undefined)
+    .orderBy(asc(workspaces.name), asc(workspaces.id))
+    .limit(params.limit + 1);
+
+  const hasMore = rows.length > params.limit;
+  const pageRows = hasMore ? rows.slice(0, params.limit) : rows;
+  const last = pageRows.at(-1);
+  const workspaceIds = pageRows.map((row) => row.workspace.id);
+  const memberCountRows =
+    workspaceIds.length > 0
+      ? await db()
+          .select({workspaceId: memberships.workspaceId, memberCount: count(memberships.id)})
+          .from(memberships)
+          .where(inArray(memberships.workspaceId, workspaceIds))
+          .groupBy(memberships.workspaceId)
+      : [];
+  const memberCounts = new Map(
+    memberCountRows.map((row) => [row.workspaceId, Number(row.memberCount)]),
+  );
+
+  return {
+    workspaces: pageRows.map((row) => ({
+      ...toWorkspace(row.workspace),
+      memberCount: memberCounts.get(row.workspace.id) ?? 0,
+    })),
+    nextCursor: hasMore && last ? {value: last.workspace.name, id: last.workspace.id} : null,
+  };
+}
+
+function escapeIlikePattern(value: string): string {
+  return value.replace(/[\\%_]/g, (char) => `\\${char}`);
+}
+
 export interface WorkspaceServiceMetrics {
   activeWorkspaces: number;
   memberships: number;

package/src/index.ts

@@ -1,3 +1,6 @@
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import {
   WORKSPACES_INVITATION_SEND_REQUESTED,
   type WorkspacesEventMap,
@@ -9,7 +12,7 @@ import {db, migrationsPath, workspacesOutbox} from '#db/index.js';
 import {registerWorkspacesServiceMetrics} from '#metrics/index.js';
 import {workspacesE2eRoutes} from '#presentation/e2eRoutes/index.js';
 import {createWorkspacesInterModulePresentation} from '#presentation/inter-module.js';
-import {workspacesRoutes} from '#presentation/routes/index.js';
+import {createWorkspacesRoutes, workspacesRoutes} from '#presentation/routes/index.js';
 import {onInvitationSendRequested} from '#presentation/subscribers/index.js';
 
 export type {Invitation} from '#core/entities/invitation.js';
@@ -32,10 +35,32 @@ export {type EnsureMembershipParams, ensureMembership} from '#core/memberships.j
 export {getWorkspace, requireWorkspaceMembership} from '#core/workspaces.js';
 export {db, migrationsPath} from '#db/index.js';
 export {listMembershipsByUser} from '#db/memberships.js';
-export {workspacesRoutes as routes} from '#presentation/routes/index.js';
+export {createWorkspacesRoutes, workspacesRoutes as routes} from '#presentation/routes/index.js';
 
 const subscriber = subscriberFactory<WorkspacesEventMap>();
 
+export interface WorkspacesModuleOptions {
+  auth: AuthInterModuleClient;
+  projects: ProjectsModuleClient;
+  runners: RunnersInterModuleClient;
+}
+
+export function createWorkspacesModule(options: WorkspacesModuleOptions): ShipfoxModule {
+  return {
+    name: 'workspaces',
+    database: {db, migrationsPath, databaseNamespace: 'workspaces'},
+    routes: createWorkspacesRoutes(options),
+    e2eRoutes: [workspacesE2eRoutes],
+    publishers: [
+      {name: 'workspaces', table: workspacesOutbox, db, eventSchemas: workspacesEventSchemas},
+    ],
+    subscribers: [subscriber(WORKSPACES_INVITATION_SEND_REQUESTED, onInvitationSendRequested)],
+    metrics: registerWorkspacesServiceMetrics,
+    interModulePresentations: [createWorkspacesInterModulePresentation()],
+  };
+}
+
+/** @deprecated Use createWorkspacesModule from the application composition root. */
 export const workspacesModule: ShipfoxModule = {
   name: 'workspaces',
   database: {db, migrationsPath, databaseNamespace: 'workspaces'},

package/src/presentation/dto/membership.ts

@@ -9,6 +9,7 @@ export function toMembershipWithWorkspaceDto(
     user_id: membership.userId,
     workspace_id: membership.workspaceId,
     workspace_name: membership.workspaceName,
+    workspace_status: membership.workspaceStatus,
     created_at: membership.createdAt.toISOString(),
     updated_at: membership.updatedAt.toISOString(),
   };

package/src/presentation/index.ts

@@ -1 +1 @@
-export {workspacesRoutes as routes} from './routes/index.js';
+export {createWorkspacesRoutes, workspacesRoutes as routes} from './routes/index.js';

package/src/presentation/routes/admin-workspaces.test.ts

@@ -0,0 +1,168 @@
+import {AUTH_USER, buildUserContext, setUserContext} from '@shipfox/api-auth-context';
+import {
+  type AuthInterModuleClient,
+  authInterModuleContract,
+} from '@shipfox/api-auth-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
+import {createInterModuleKnownError} from '@shipfox/inter-module';
+import {type AuthMethod, closeApp, createApp} from '@shipfox/node-fastify';
+import type {FastifyInstance, FastifyRequest} from 'fastify';
+import {createMembership} from '#db/memberships.js';
+import {createWorkspace} from '#db/workspaces.js';
+import {createAdminWorkspacesRoutes} from './admin-workspaces.js';
+
+const USER_ID = '11111111-1111-4111-8111-111111111111';
+
+const fakeUserAuth: AuthMethod = {
+  name: AUTH_USER,
+  authenticate: (request: FastifyRequest) => {
+    setUserContext(
+      request,
+      buildUserContext({userId: USER_ID, email: 'admin@example.com', memberships: []}),
+    );
+    return Promise.resolve();
+  },
+};
+
+describe('GET /admin/workspaces', () => {
+  let app: FastifyInstance;
+  let auth: AuthInterModuleClient;
+  let projects: ProjectsModuleClient;
+  let runners: RunnersInterModuleClient;
+
+  beforeEach(async () => {
+    await closeApp();
+    auth = {
+      requireAdminRole: vi.fn().mockResolvedValue({role: 'admin-observer'}),
+    } as unknown as AuthInterModuleClient;
+    projects = {
+      getWorkspaceProjectCounts: vi.fn().mockResolvedValue({counts: []}),
+    } as unknown as ProjectsModuleClient;
+    runners = {
+      getWorkspaceJobCounts: vi.fn().mockResolvedValue({counts: []}),
+    } as unknown as RunnersInterModuleClient;
+    app = await createApp({
+      auth: [fakeUserAuth],
+      routes: [createAdminWorkspacesRoutes({auth, projects, runners})],
+      swagger: false,
+    });
+    await app.ready();
+  });
+
+  afterEach(async () => {
+    await closeApp();
+  });
+
+  test('returns a bounded safe workspace summary for an observer', async () => {
+    const workspace = await createWorkspace({name: `Admin lookup ${crypto.randomUUID()}`});
+    await createMembership({userId: crypto.randomUUID(), workspaceId: workspace.id});
+    vi.mocked(projects.getWorkspaceProjectCounts).mockResolvedValue({
+      counts: [{workspaceId: workspace.id, count: 3}],
+    });
+    vi.mocked(runners.getWorkspaceJobCounts).mockResolvedValue({
+      counts: [{workspaceId: workspace.id, queued: 2, running: 1}],
+    });
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/admin/workspaces?workspace_id=${workspace.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json()).toMatchObject({
+      workspaces: [
+        {
+          id: workspace.id,
+          name: workspace.name,
+          status: 'active',
+          member_summary: {count: 1},
+          project_summary: {state: 'available', count: 3},
+          job_counts: {state: 'available', queued: 2, running: 1},
+        },
+      ],
+      next_cursor: null,
+    });
+    expect(response.json().workspaces[0]).not.toHaveProperty('settings');
+    expect(response.json().workspaces[0]).not.toHaveProperty('administrator');
+    expect(auth.requireAdminRole).toHaveBeenCalledWith({
+      userId: USER_ID,
+      minimumRole: 'admin-observer',
+    });
+  });
+
+  test('returns explicit unknown job counts when the supporting lookup fails', async () => {
+    const workspace = await createWorkspace({name: `Unknown jobs ${crypto.randomUUID()}`});
+    vi.mocked(projects.getWorkspaceProjectCounts).mockResolvedValue({
+      counts: [{workspaceId: workspace.id, count: 0}],
+    });
+    vi.mocked(runners.getWorkspaceJobCounts).mockRejectedValue(new Error('runner service down'));
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/admin/workspaces?workspace_id=${workspace.id}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json().workspaces[0]).toMatchObject({
+      project_summary: {state: 'available', count: 0},
+      job_counts: {state: 'unknown'},
+    });
+  });
+
+  test('keeps known supporting counts when a response omits another workspace', async () => {
+    const prefix = `Partial counts ${crypto.randomUUID()}`;
+    const firstWorkspace = await createWorkspace({name: `${prefix} Alpha`});
+    const secondWorkspace = await createWorkspace({name: `${prefix} Beta`});
+    vi.mocked(projects.getWorkspaceProjectCounts).mockResolvedValue({
+      counts: [{workspaceId: firstWorkspace.id, count: 2}],
+    });
+    vi.mocked(runners.getWorkspaceJobCounts).mockResolvedValue({
+      counts: [{workspaceId: firstWorkspace.id, queued: 1, running: 2}],
+    });
+
+    const response = await app.inject({
+      method: 'GET',
+      url: `/admin/workspaces?search=${encodeURIComponent(prefix)}`,
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(response.statusCode).toBe(200);
+    expect(response.json().workspaces).toEqual([
+      expect.objectContaining({
+        id: firstWorkspace.id,
+        project_summary: {state: 'available', count: 2},
+        job_counts: {state: 'available', queued: 1, running: 2},
+      }),
+      expect.objectContaining({
+        id: secondWorkspace.id,
+        project_summary: {state: 'unknown'},
+        job_counts: {state: 'unknown'},
+      }),
+    ]);
+  });
+
+  test('maps an insufficient administrator role to forbidden', async () => {
+    vi.mocked(auth.requireAdminRole).mockRejectedValue(
+      createInterModuleKnownError(
+        authInterModuleContract.methods.requireAdminRole,
+        'admin-role-required',
+        {requiredRole: 'admin-observer'},
+      ),
+    );
+
+    const response = await app.inject({
+      method: 'GET',
+      url: '/admin/workspaces',
+      headers: {authorization: 'Bearer user'},
+    });
+
+    expect(response.statusCode).toBe(403);
+    expect(response.json()).toMatchObject({
+      code: 'forbidden',
+      details: {required_role: 'admin-observer'},
+    });
+  });
+});

package/src/presentation/routes/admin-workspaces.ts

@@ -0,0 +1,93 @@
+import {AUTH_USER, getUserContext} from '@shipfox/api-auth-context';
+import {
+  type AuthInterModuleClient,
+  authInterModuleContract,
+} from '@shipfox/api-auth-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
+import {
+  listWorkspaceAdminSummariesResponseSchema,
+  workspaceAdminLookupQuerySchema,
+} from '@shipfox/api-workspaces-dto';
+import {isInterModuleKnownError} from '@shipfox/inter-module';
+import {decodeStringIdCursor, encodeStringIdCursor} from '@shipfox/node-drizzle';
+import {ClientError, defineRoute, type RouteGroup} from '@shipfox/node-fastify';
+import {
+  listWorkspaceAdministratorSummaries,
+  type WorkspaceAdministratorSummary,
+} from '#core/admin-workspaces.js';
+
+function toWorkspaceAdministratorSummaryDto(summary: WorkspaceAdministratorSummary) {
+  return {
+    id: summary.id,
+    name: summary.name,
+    status: summary.status,
+    member_summary: summary.memberSummary,
+    project_summary: summary.projectSummary,
+    job_counts: summary.jobCounts,
+    created_at: summary.createdAt.toISOString(),
+    updated_at: summary.updatedAt.toISOString(),
+  };
+}
+
+export function createAdminWorkspacesRoutes(params: {
+  auth: AuthInterModuleClient;
+  projects: ProjectsModuleClient;
+  runners: RunnersInterModuleClient;
+}): RouteGroup {
+  const listRoute = defineRoute({
+    method: 'GET',
+    path: '/',
+    description: 'List bounded safe workspace summaries for administrators.',
+    auth: AUTH_USER,
+    schema: {
+      querystring: workspaceAdminLookupQuerySchema,
+      response: {200: listWorkspaceAdminSummariesResponseSchema},
+    },
+    errorHandler: (error) => {
+      if (
+        isInterModuleKnownError(authInterModuleContract.methods.requireAdminRole, error) &&
+        error.code === 'admin-role-required'
+      ) {
+        throw new ClientError('Administrator observer role required', 'forbidden', {
+          status: 403,
+          details: {required_role: error.details.requiredRole},
+        });
+      }
+      throw error;
+    },
+    handler: async (request) => {
+      const client = getUserContext(request);
+      if (!client) {
+        throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+      }
+      await params.auth.requireAdminRole({
+        userId: client.userId,
+        minimumRole: 'admin-observer',
+      });
+
+      const {workspace_id: workspaceId, search, status, limit, cursor} = request.query;
+      const decodedCursor = decodeStringIdCursor(cursor);
+      if (cursor && !decodedCursor) {
+        throw new ClientError('Invalid cursor', 'invalid-cursor', {status: 400});
+      }
+
+      const result = await listWorkspaceAdministratorSummaries({
+        workspaceId,
+        search,
+        status,
+        limit,
+        cursor: decodedCursor,
+        projects: params.projects,
+        runners: params.runners,
+      });
+
+      return {
+        workspaces: result.workspaces.map(toWorkspaceAdministratorSummaryDto),
+        next_cursor: result.nextCursor ? encodeStringIdCursor(result.nextCursor) : null,
+      };
+    },
+  });
+
+  return {prefix: '/admin/workspaces', routes: [listRoute]};
+}

package/src/presentation/routes/index.ts

@@ -1,4 +1,8 @@
+import type {AuthInterModuleClient} from '@shipfox/api-auth-dto/inter-module';
+import type {ProjectsModuleClient} from '@shipfox/api-projects-dto/inter-module';
+import type {RunnersInterModuleClient} from '@shipfox/api-runners-dto/inter-module';
 import type {RouteGroup} from '@shipfox/node-fastify';
+import {createAdminWorkspacesRoutes} from './admin-workspaces.js';
 import {invitationsAcceptGroup, invitationsWorkspaceScopedRoutes} from './invitations/index.js';
 import {memberRoutes} from './members/index.js';
 import {createWorkspaceRoute, listUserWorkspacesRoute} from './workspaces/index.js';
@@ -21,3 +25,11 @@ export const workspacesRoutes: RouteGroup[] = [
     ],
   },
 ];
+
+export function createWorkspacesRoutes(params: {
+  auth: AuthInterModuleClient;
+  projects: ProjectsModuleClient;
+  runners: RunnersInterModuleClient;
+}): RouteGroup[] {
+  return [...workspacesRoutes, createAdminWorkspacesRoutes(params)];
+}