Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

6.8 KB
Raw Blame
// The Harness Store's backend half: ratings and reviews of harnesses.
//
// The catalogue itself is NOT here — it is the registry bundled into the CLI (`store/`), and
// installing is a per-machine act the daemon performs. What a store needs from a server is the part
// that has to be shared between people and signed: who rated what, and what they wrote. One review
// per person per harness; writing again replaces it.
import type { FastifyInstance, FastifyRequest } from 'fastify'
import { z } from 'zod'
import { prisma } from '../lib/prisma.js'
import { validateBody, validateParams } from '../middlewares/validation.js'
import { sendSuccess, sendError } from '../utils/response.js'

export const STORE_RATINGS_PATH = '/api/store/ratings'
export const STORE_REVIEWS_PATH = '/api/store/harnesses/:owner/:name/reviews'
export const STORE_REVIEW_PATH = '/api/store/harnesses/:owner/:name/review'

/** One half of `owner/name` — the same shape the CLI's DSH_ID_RE (and the spec's `id` pattern) accepts:
 *  lowercase only, so one harness cannot collect a second review from the same person under another spelling. */
const segment = z.string().regex(/^[a-z0-9][a-z0-9-]{0,63}$/)
const harnessParams = z.object({ owner: segment, name: segment })
const reviewBody = z.object({
  rating: z.number().int().min(1).max(5),
  // Nullable as well as optional: a review is read back with `title: null`, and must be writable as read.
  title: z.string().trim().max(80).nullish(),
  body: z.string().trim().max(2000).nullish(),
})
export type ReviewBody = z.infer<typeof reviewBody>

export interface RatingSummary {
  harnessId: string
  average: number
  count: number
  /** How many gave 1, 2, 3, 4, 5 stars — index 0 is one star. */
  histogram: [number, number, number, number, number]
}

export interface ReviewRow {
  id: string
  harnessId: string
  rating: number
  title: string | null
  body: string | null
  authorName: string
  mine: boolean
  createdAt: string
  updatedAt: string
}

const MAX_REVIEWS = 200

function summarize(harnessId: string, ratings: number[]): RatingSummary {
  const histogram: RatingSummary['histogram'] = [0, 0, 0, 0, 0]
  let total = 0
  let count = 0
  for (const r of ratings) {
    // The database cannot forbid a stored 0 or 7; such a row is not a vote, or count and histogram would disagree.
    if (r >= 1 && r <= 5) { histogram[r - 1] += 1; total += r; count += 1 }
  }
  return { harnessId, average: count ? Math.round((total / count) * 100) / 100 : 0, count, histogram }
}

/** Ratings, one summary per harness that has any — computed from the rows, so a histogram and its average cannot disagree. */
export async function ratingSummaries(): Promise<RatingSummary[]> {
  const rows = await prisma.harnessReview.findMany({ select: { harnessId: true, rating: true } })
  const byId = new Map<string, number[]>()
  for (const row of rows) {
    const list = byId.get(row.harnessId) ?? []
    list.push(row.rating)
    byId.set(row.harnessId, list)
  }
  return [...byId.entries()]
    .map(([id, ratings]) => summarize(id, ratings))
    .filter((summary) => summary.count > 0)
    .sort((a, b) => a.harnessId.localeCompare(b.harnessId))
}

function row(review: { id: string; harnessId: string; rating: number; title: string | null; body: string | null; authorName: string; userId: string; createdAt: Date; updatedAt: Date }, userId: string): ReviewRow {
  return {
    id: review.id,
    harnessId: review.harnessId,
    rating: review.rating,
    title: review.title,
    body: review.body,
    authorName: review.authorName,
    mine: review.userId === userId,
    createdAt: review.createdAt.toISOString(),
    updatedAt: review.updatedAt.toISOString(),
  }
}

/** What the store prints beside a review. The person's name when they have one; never their email. */
async function authorNameOf(userId: string): Promise<string> {
  const user = await prisma.user.findUnique({ where: { id: userId }, select: { name: true } })
  const name = user?.name?.trim()
  return name && name.length > 0 ? name.slice(0, 80) : 'Harness user'
}

type HarnessReq = FastifyRequest<{ Params: z.infer<typeof harnessParams> }>

export async function storeRoutes(app: FastifyInstance): Promise<void> {
  app.get(STORE_RATINGS_PATH, async (_req, reply) => {
    sendSuccess(reply, { ratings: await ratingSummaries() })
  })

  app.get<{ Params: z.infer<typeof harnessParams> }>(
    STORE_REVIEWS_PATH,
    { preHandler: [validateParams(harnessParams)] },
    async (req: HarnessReq, reply) => {
      const harnessId = `${req.params.owner}/${req.params.name}`
      const userId = req.user!.sub
      // Only the list is capped. The summary reads every rating and the reader's own review is read by
      // key, so a harness past MAX_REVIEWS still shows the rating /ratings shows, and its reader's review.
      const [ratings, own, others] = await Promise.all([
        prisma.harnessReview.findMany({ where: { harnessId }, select: { rating: true } }),
        prisma.harnessReview.findUnique({ where: { harnessId_userId: { harnessId, userId } } }),
        prisma.harnessReview.findMany({
          where: { harnessId, userId: { not: userId } },
          orderBy: { updatedAt: 'desc' },
          take: MAX_REVIEWS,
        }),
      ])
      const mine = own ? row(own, userId) : null
      // Mine first: the one review a person can edit is the one they look for.
      const rows = [...(mine ? [mine] : []), ...others.map((r) => row(r, userId))].slice(0, MAX_REVIEWS)
      sendSuccess(reply, {
        rating: summarize(harnessId, ratings.map((r) => r.rating)),
        reviews: rows,
        mine,
      })
    },
  )

  app.put<{ Params: z.infer<typeof harnessParams>; Body: ReviewBody }>(
    STORE_REVIEW_PATH,
    { preHandler: [validateParams(harnessParams), validateBody(reviewBody)] },
    async (req, reply) => {
      const harnessId = `${req.params.owner}/${req.params.name}`
      const userId = req.user!.sub
      const { rating, title, body } = req.body
      const authorName = await authorNameOf(userId)
      const data = { rating, title: title || null, body: body || null, authorName }
      const review = await prisma.harnessReview.upsert({
        where: { harnessId_userId: { harnessId, userId } },
        create: { harnessId, userId, ...data },
        update: data,
      })
      sendSuccess(reply, { review: row(review, userId) })
    },
  )

  app.delete<{ Params: z.infer<typeof harnessParams> }>(
    STORE_REVIEW_PATH,
    { preHandler: [validateParams(harnessParams)] },
    async (req: HarnessReq, reply) => {
      const harnessId = `${req.params.owner}/${req.params.name}`
      const userId = req.user!.sub
      const { count } = await prisma.harnessReview.deleteMany({ where: { harnessId, userId } })
      if (count === 0) return sendError(reply, 'You have not reviewed this harness', 'NO_REVIEW', 404)
      sendSuccess(reply, { deleted: true })
    },
  )
}