fix: review comments

Signed-off-by: Umberto Sgueglia <usgueglia@contractor.linuxfoundation.org>

Author: ulemons

backend/src/api/public/v1/packages/getPackage.ts

@@ -90,6 +90,7 @@ export async function getPackage(req: Request, res: Response): Promise<void> {
       },
     },
     stewardship: {
+      id: pkg.stewardshipId ?? null,
       status: (pkg.stewardshipStatus ?? 'unassigned') as StewardshipStatus,
       stewards: stewardshipSummary?.stewards ?? null,
       lastActivityAt: stewardshipSummary?.lastActivityAt ?? null,

backend/src/api/public/v1/packages/listPackages.ts

@@ -87,6 +87,7 @@ export async function listPackages(req: Request, res: Response): Promise<void> {
     lifecycle: null,
     maintainerBusFactor: r.maintainerCount,
     openVulns: r.openVulns,
+    stewardshipId: r.stewardshipId ?? null,
     stewardship: (r.stewardshipStatus ?? 'unassigned') as StewardshipStatus,
     stewards: null,
   }))

backend/src/api/public/v1/packages/openapi.yaml

@@ -194,6 +194,12 @@ components:
           oneOf:
             - $ref: '#/components/schemas/OpenVulns'
             - type: 'null'
+        stewardshipId:
+          type:
+            - string
+            - 'null'
+          description: Stewardship ID. Required to call mutation endpoints (assign/escalate/status). Null if no stewardship row exists.
+          example: '42'
         stewardship:
           $ref: '#/components/schemas/StewardshipStatus'
         stewards:
@@ -420,6 +426,12 @@ components:
           type: object
           description: Stewardship state. In v1 always unassigned with no stewards or activity.
           properties:
+            id:
+              type:
+                - string
+                - 'null'
+              description: Stewardship ID. Required to call mutation endpoints (assign/escalate/status).
+              example: '42'
             status:
               $ref: '#/components/schemas/StewardshipStatus'
             stewards:

backend/src/api/public/v1/stewardships/assignSteward.ts

@@ -15,14 +15,20 @@ const paramsSchema = z.object({
 const bodySchema = z.object({
   userId: z.string().trim().min(1),
   role: z.enum(['lead', 'co_steward']),
+  moveToAssessing: z.boolean().optional().default(false),
 })
 
 export async function assignStewardHandler(req: Request, res: Response): Promise<void> {
   const { id } = validateOrThrow(paramsSchema, req.params)
-  const { userId, role } = validateOrThrow(bodySchema, req.body)
+  const { userId, role, moveToAssessing } = validateOrThrow(bodySchema, req.body)
 
   const qx = await getPackagesQx()
-  const result = await assignSteward(qx, id, { userId, role, assignedBy: req.actor.id })
+  const result = await assignSteward(qx, id, {
+    userId,
+    role,
+    assignedBy: req.actor.id,
+    moveToAssessing,
+  })
 
   if (!result) {
     throw new NotFoundError(`Stewardship not found: ${id}`)

backend/src/api/public/v1/stewardships/openapi.yaml

@@ -250,9 +250,17 @@ paths:
                 role:
                   type: string
                   enum: [lead, co_steward]
+                moveToAssessing:
+                  type: boolean
+                  default: false
+                  description: >
+                    If true, atomically transitions the stewardship status to `assessing`
+                    in the same transaction as the assignment. Use for the "Assign & move to
+                    Assessing" action to avoid a second round-trip.
             example:
               userId: abc123
               role: lead
+              moveToAssessing: true
       responses:
         '200':
           description: Steward assigned.

services/libs/data-access-layer/src/osspckgs/api.ts

@@ -54,6 +54,7 @@ export interface PackageListRow {
   name: string
   ecosystem: string
   criticalityScore: number | null
+  stewardshipId: string | null
   stewardshipStatus: string | null
   openVulns: number
   maintainerCount: number
@@ -226,6 +227,7 @@ export async function listPackagesForApi(
       p.name,
       p.ecosystem,
       p.impact AS "criticalityScore",
+      s.id::text AS "stewardshipId",
       s.status AS "stewardshipStatus",
       COALESCE(ap_counts.cnt, 0) AS "openVulns",
       pm_counts.cnt AS "maintainerCount",

services/libs/data-access-layer/src/osspckgs/stewardships.ts

@@ -180,7 +180,7 @@ export async function openStewardshipByPurl(
 export async function assignSteward(
   qx: QueryExecutor,
   stewardshipId: number,
-  data: { userId: string; role: 'lead' | 'co_steward'; assignedBy: string },
+  data: { userId: string; role: 'lead' | 'co_steward'; assignedBy: string; moveToAssessing?: boolean },
 ): Promise<{ stewardship: StewardshipRecord; stewards: StewardshipStewardRecord[] } | null> {
   return qx.tx(async (tx) => {
     const stewardship = await getStewardshipById(tx, stewardshipId)
@@ -213,6 +213,37 @@ export async function assignSteward(
       },
     )
 
+    let finalStewardship = stewardship
+
+    if (data.moveToAssessing) {
+      const updated: Record<string, unknown> | null = await tx.selectOneOrNone(
+        `
+        WITH upd AS (
+          UPDATE stewardships
+          SET status         = 'assessing',
+              last_status_at = NOW(),
+              resolution_path = NULL,
+              status_note     = NULL,
+              updated_at     = NOW()
+          WHERE id = $(stewardshipId)
+            AND status IN ('unassigned', 'open')
+          RETURNING id, package_id, status, origin, version, opened_at,
+                    last_status_at, inactive_reason, resolution_path, status_note, created_at, updated_at
+        ),
+        _log AS (
+          INSERT INTO stewardship_activity
+            (stewardship_id, actor_user_id, actor_type, activity_type, content, metadata)
+          SELECT id, $(actorUserId), 'user', 'state_changed',
+                 'Status updated to assessing', $(metadata)::jsonb
+          FROM upd
+        )
+        SELECT * FROM upd
+        `,
+        { stewardshipId, actorUserId: data.assignedBy, metadata: JSON.stringify({ status: 'assessing' }) },
+      )
+      if (updated) finalStewardship = mapStewardshipRow(updated)
+    }
+
     const stewards: Array<Record<string, unknown>> = await tx.select(
       `SELECT id, stewardship_id, user_id, role, assigned_at, assigned_by
        FROM stewardship_stewards
@@ -223,7 +254,7 @@ export async function assignSteward(
     )
 
     return {
-      stewardship,
+      stewardship: finalStewardship,
       stewards: stewards.map(mapStewardStewardRow),
     }
   })