@igstack/app-catalog-backend-core 6.10.2 → 6.11.0

package/src/modules/communityTools/writeService.ts

@@ -0,0 +1,408 @@
+import { TRPCError } from '@trpc/server'
+import type { User } from 'better-auth/types'
+import { z } from 'zod'
+import type { CommunityTool } from '@igstack/app-catalog-shared-core'
+import {
+  TAG_VALUE_MAX,
+  hostOf,
+  isCaptureAllowed,
+  normalizeTags,
+} from '@igstack/app-catalog-shared-core'
+import { getDbClient } from '../../db/client'
+import { resizeImage } from '../assets/assetUtils'
+import { MARKER_KIND } from '../feedback/service'
+import type { Actor } from '../visitor/visitorIdentity'
+import { checkTool } from './healthJob'
+import type { CaptureDeps } from './healthJob'
+import { computeCanEdit, getTool } from './service'
+
+export const toolInputSchema = z.object({
+  url: z.string().max(2000),
+  name: z.string().trim().min(1).max(80),
+  summary: z.string().trim().max(160),
+  descriptionMd: z.string().max(5000),
+  ownerSlugs: z.array(z.string()).max(5),
+  /**
+   * Owners outside the person directory, by name. Left out of an edit, the
+   * tool keeps the ones it has; only a list replaces them.
+   */
+  ownerNames: z
+    .array(z.string().trim().min(1).max(80))
+    .max(5)
+    .transform((names) => Array.from(new Set(names)))
+    .optional(),
+  // Topics are stored the way the next person will type them, each tag once;
+  // the caps hold for what is stored.
+  tags: z
+    .array(z.object({ kind: z.enum(['app', 'topic']), value: z.string() }))
+    .transform(normalizeTags)
+    .pipe(
+      z
+        .array(
+          z.object({
+            kind: z.enum(['app', 'topic']),
+            value: z.string().min(1).max(TAG_VALUE_MAX),
+          }),
+        )
+        .max(8),
+    ),
+})
+export type ToolInput = z.output<typeof toolInputSchema>
+
+const MAX_OWNERS = 5
+
+/** The signed-in person making the change. */
+export interface Writer {
+  user: User
+  isAdmin: boolean
+  actor: Actor
+}
+
+export interface ToolPreview {
+  host: string
+  title: string | null
+  screenshotDataUrl: string | null
+  duplicate: { slug: string; name: string } | null
+  /** An official app on the same host: the tool would duplicate a catalog entry. */
+  officialApp: { slug: string; name: string } | null
+  captureAllowed: boolean
+}
+
+const PREVIEW_WIDTH = 640
+/** Previews are someone waiting at the form; past this many queued, ask them to retry. */
+const MAX_WAITING_CAPTURES = 3
+
+function requireHost(url: string): string {
+  const host = hostOf(url)
+  if (!host) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: 'The address must start with http:// or https://',
+    })
+  }
+  return host
+}
+
+async function requireTool(slug: string) {
+  const tool = await getDbClient().dbCommunityTool.findUnique({
+    where: { slug },
+    include: { owners: true, namedOwners: true, tags: true },
+  })
+  if (!tool) {
+    throw new TRPCError({ code: 'NOT_FOUND', message: 'Tool not found' })
+  }
+  return tool
+}
+
+async function requireEditor(
+  tool: { id: string; addedByUserId: string },
+  writer: Writer,
+) {
+  if (!(await computeCanEdit(tool, writer.user, writer.isAdmin))) {
+    throw new TRPCError({
+      code: 'FORBIDDEN',
+      message: 'Only an owner or an admin can change this tool',
+    })
+  }
+}
+
+/**
+ * The owners as stored: directory people, who must exist, and names of people
+ * outside it. One owner at least, of either kind, and five in all.
+ */
+async function requireOwners(input: ToolInput, keptNames: string[] = []) {
+  const unique = Array.from(new Set(input.ownerSlugs))
+  const ownerNames = input.ownerNames ?? keptNames
+  const count = unique.length + ownerNames.length
+  if (count < 1 || count > MAX_OWNERS) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: `A tool has 1 to ${MAX_OWNERS} owners`,
+    })
+  }
+  const found = await getDbClient().dbPerson.findMany({
+    where: { slug: { in: unique } },
+    select: { slug: true },
+  })
+  if (found.length !== unique.length) {
+    throw new TRPCError({
+      code: 'BAD_REQUEST',
+      message: 'Every owner must be in the person directory',
+    })
+  }
+  return { ownerSlugs: unique, ownerNames }
+}
+
+function slugify(name: string): string {
+  return (
+    name
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, '-')
+      .replace(/^-+|-+$/g, '') || 'tool'
+  )
+}
+
+async function freeSlug(name: string): Promise<string> {
+  const base = slugify(name)
+  const db = getDbClient()
+  for (let n = 1; ; n++) {
+    const slug = n === 1 ? base : `${base}-${n}`
+    if (!(await db.dbCommunityTool.findUnique({ where: { slug } }))) return slug
+  }
+}
+
+/** A review row: what puts the change in the maintainer's existing comment queue. */
+async function writeMarker(
+  toolId: string,
+  body: string,
+  writer: Writer,
+  status: 'applied' | 'acknowledged' | null,
+) {
+  await getDbClient().dbFeedback.create({
+    data: {
+      communityToolId: toolId,
+      kind: MARKER_KIND,
+      body,
+      status,
+      authorHash: writer.actor.hash,
+      authorAlias: writer.actor.alias,
+      authorUserId: writer.user.id,
+      authorName: writer.user.name,
+    },
+  })
+}
+
+/** Capture in the background: publishing must not wait on a 20-second page load. */
+function captureLater(
+  tool: Parameters<typeof checkTool>[0],
+  deps: CaptureDeps,
+  now: Date,
+) {
+  checkTool(tool, deps, now).catch((error: unknown) => {
+    console.error(`[communityTools] capture of ${tool.slug}:`, error)
+  })
+}
+
+/** The top-level catalog app whose address is on this host, if any. */
+async function findOfficialApp(
+  host: string,
+): Promise<{ slug: string; name: string } | null> {
+  // ponytail: scans every top-level app; a stored host column if the catalog grows past thousands.
+  const apps = await getDbClient().dbResource.findMany({
+    where: { parentSlug: null, appUrl: { not: null } },
+    select: { slug: true, displayName: true, appUrl: true },
+  })
+  const app = apps.find((a) => a.appUrl && hostOf(a.appUrl) === host)
+  return app ? { slug: app.slug, name: app.displayName } : null
+}
+
+export async function previewTool(
+  url: string,
+  deps: CaptureDeps,
+): Promise<ToolPreview> {
+  const host = requireHost(url)
+  const captureAllowed = isCaptureAllowed(url, deps.captureHosts)
+  if (
+    captureAllowed &&
+    (deps.capturer?.waiting?.() ?? 0) > MAX_WAITING_CAPTURES
+  ) {
+    throw new TRPCError({
+      code: 'TOO_MANY_REQUESTS',
+      message: 'Too many previews in progress; try again in a minute',
+    })
+  }
+
+  const duplicate = await getDbClient().dbCommunityTool.findFirst({
+    where: { host },
+    select: { slug: true, name: true },
+  })
+  const officialApp = await findOfficialApp(host)
+
+  let title: string | null = null
+  let screenshotDataUrl: string | null = null
+  if (captureAllowed && deps.capturer) {
+    try {
+      const result = await deps.capturer.capture(url, deps.captureHosts)
+      if (result.ok) {
+        title = result.title
+        const jpeg = await resizeImage(
+          result.png,
+          PREVIEW_WIDTH,
+          undefined,
+          'jpeg',
+        )
+        screenshotDataUrl = `data:image/jpeg;base64,${jpeg.toString('base64')}`
+      }
+    } catch (error) {
+      console.error('[communityTools] preview capture failed:', error)
+    }
+  }
+
+  return {
+    host,
+    title,
+    screenshotDataUrl,
+    duplicate,
+    officialApp,
+    captureAllowed,
+  }
+}
+
+export async function addTool(
+  input: ToolInput,
+  writer: Writer,
+  deps: CaptureDeps,
+  now: Date,
+): Promise<CommunityTool> {
+  const host = requireHost(input.url)
+  const { ownerSlugs, ownerNames } = await requireOwners(input)
+  const slug = await freeSlug(input.name)
+
+  const created = await getDbClient().dbCommunityTool.create({
+    data: {
+      slug,
+      name: input.name,
+      url: input.url,
+      host,
+      summary: input.summary,
+      descriptionMd: input.descriptionMd,
+      addedByUserId: writer.user.id,
+      addedByName: writer.user.name,
+      owners: { create: ownerSlugs.map((personSlug) => ({ personSlug })) },
+      namedOwners: { create: ownerNames.map((name) => ({ name })) },
+      tags: { create: input.tags },
+    },
+  })
+  await writeMarker(created.id, `New tool added: ${input.name}`, writer, null)
+  captureLater(created, deps, now)
+
+  return (await getTool(created.slug, writer.user, writer.isAdmin, now, deps))!
+}
+
+export async function editTool(
+  input: ToolInput & { slug: string },
+  writer: Writer,
+  deps: CaptureDeps,
+  now: Date,
+): Promise<CommunityTool> {
+  const tool = await requireTool(input.slug)
+  await requireEditor(tool, writer)
+  const host = requireHost(input.url)
+  const { ownerSlugs, ownerNames } = await requireOwners(
+    input,
+    tool.namedOwners.map((o) => o.name),
+  )
+
+  const sameSet = (a: string[], b: string[]) =>
+    a.length === b.length && a.every((x) => b.includes(x))
+  const tagKey = (t: { kind: string; value: string }) => `${t.kind}:${t.value}`
+  const changed = [
+    tool.name !== input.name && 'name',
+    tool.url !== input.url && 'url',
+    tool.summary !== input.summary && 'summary',
+    tool.descriptionMd !== input.descriptionMd && 'description',
+    !(
+      sameSet(
+        tool.owners.map((o) => o.personSlug),
+        ownerSlugs,
+      ) &&
+      sameSet(
+        tool.namedOwners.map((o) => o.name),
+        ownerNames,
+      )
+    ) && 'owners',
+    !sameSet(tool.tags.map(tagKey), input.tags.map(tagKey)) && 'tags',
+  ].filter((f): f is string => !!f)
+
+  if (changed.length > 0) {
+    // A different site has no health history yet, and a dead old site's
+    // automatic archive says nothing about the new one.
+    const newSite = host !== tool.host && {
+      failingSince: null,
+      lastCheckAt: null,
+      ...(tool.archivedBy === 'auto' && {
+        archivedAt: null,
+        archivedBy: null,
+        archivedReason: null,
+      }),
+    }
+    const updated = await getDbClient().dbCommunityTool.update({
+      where: { id: tool.id },
+      data: {
+        // An edit is news to the maintainer, so the tool waits for approval again.
+        reviewedAt: null,
+        reviewedByName: null,
+        ...newSite,
+        name: input.name,
+        url: input.url,
+        host,
+        summary: input.summary,
+        descriptionMd: input.descriptionMd,
+        owners: {
+          deleteMany: {},
+          create: ownerSlugs.map((personSlug) => ({ personSlug })),
+        },
+        namedOwners: {
+          deleteMany: {},
+          create: ownerNames.map((name) => ({ name })),
+        },
+        tags: { deleteMany: {}, create: input.tags },
+      },
+    })
+    await writeMarker(
+      tool.id,
+      `Tool edited: ${changed.join(', ')}`,
+      writer,
+      null,
+    )
+    if (changed.includes('url')) captureLater(updated, deps, now)
+  }
+
+  // The slug stays: pins, links and bookmarks point at it.
+  return (await getTool(tool.slug, writer.user, writer.isAdmin, now, deps))!
+}
+
+export async function archiveTool(
+  slug: string,
+  reason: string,
+  writer: Writer,
+  now: Date,
+): Promise<void> {
+  const tool = await requireTool(slug)
+  await requireEditor(tool, writer)
+
+  await getDbClient().dbCommunityTool.update({
+    where: { id: tool.id },
+    data: {
+      archivedAt: now,
+      archivedBy: writer.user.name,
+      archivedReason: reason,
+    },
+  })
+  // An owner's archive is news to the maintainer; an admin's is their own decision.
+  await writeMarker(
+    tool.id,
+    `Tool archived: ${reason}`,
+    writer,
+    writer.isAdmin ? 'acknowledged' : null,
+  )
+}
+
+export async function approveTool(
+  slug: string,
+  writer: Writer,
+  now: Date,
+): Promise<void> {
+  const tool = await requireTool(slug)
+  const db = getDbClient()
+
+  await db.dbCommunityTool.update({
+    where: { id: tool.id },
+    data: { reviewedAt: now, reviewedByName: writer.user.name },
+  })
+  await db.dbFeedback.updateMany({
+    where: { communityToolId: tool.id, status: null },
+    data: { status: 'applied', reviewedAt: now },
+  })
+  await writeMarker(tool.id, 'Tool approved', writer, 'applied')
+}

package/src/modules/feedback/feedbackRouter.ts

@@ -57,8 +57,13 @@ export function createFeedbackRouter() {
   return router({
     /** One entry's thread, plus its unreviewed count so the badge needs no second call. */
     list: publicProcedure
-      .input(z.object({ resourceSlug: z.string() }))
-      .query(({ input, ctx }) => listFeedback(input.resourceSlug, ctx.actor)),
+      .input(
+        z.union([
+          z.object({ resourceSlug: z.string() }),
+          z.object({ communityToolSlug: z.string() }),
+        ]),
+      )
+      .query(({ input, ctx }) => listFeedback(input, ctx.actor)),
 
     /** Everything this browser filed, for the tracker. Empty means render no button. */
     mine: publicProcedure.query(({ ctx }) => listMyFeedback(ctx.actor)),
@@ -68,6 +73,7 @@ export function createFeedbackRouter() {
         z
           .object({
             resourceSlug: z.string().optional(),
+            communityToolSlug: z.string().optional(),
             subject: z.string().max(MAX_SUBJECT_LENGTH).optional(),
             // Both optional: a note can be words, screenshots or both, and a
             // catalog-level ask may carry only its subject. The entry's input asks
@@ -76,12 +82,20 @@ export function createFeedbackRouter() {
             body: z.string().max(MAX_BODY_LENGTH).optional(),
             attachmentIds: z.array(z.string()).max(MAX_ATTACHMENTS).optional(),
           })
-          .refine((v) => !!v.resourceSlug || !!v.subject?.trim(), {
-            message: 'Needs either an entry or a subject',
-          }),
+          .refine(
+            (v) =>
+              !!v.resourceSlug || !!v.communityToolSlug || !!v.subject?.trim(),
+            { message: 'Needs either an entry or a subject' },
+          ),
       )
       .mutation(({ input, ctx }) =>
-        mapErrors(() => addFeedback(input, requireActor(ctx.actor))),
+        mapErrors(() =>
+          addFeedback(
+            input,
+            requireActor(ctx.actor),
+            ctx.user ? { id: ctx.user.id, name: ctx.user.name } : null,
+          ),
+        ),
       ),
 
     edit: publicProcedure

package/src/modules/feedback/service.ts

@@ -8,9 +8,13 @@ export const MAX_BODY_LENGTH = 1000
 export const MAX_SUBJECT_LENGTH = 120
 export const MAX_ATTACHMENTS = 3
 
+/** `kind` of a review row a community tool write leaves; see `isSystem`. */
+export const MARKER_KIND = 'marker'
+
 /** One piece of feedback as a client sees it. Never carries an author hash. */
 export interface FeedbackView {
   id: string
+  /** The signed-in author's name, or the pseudonym of an anonymous one. */
   authorName: string
   /** Null when the visitor sent a bare flag with no words. */
   body: string | null
@@ -29,6 +33,8 @@ export interface FeedbackView {
   editedAt: string | null
   /** Whether this browser wrote it — what makes Edit and Dismiss appear. */
   isMine: boolean
+  /** A line the system wrote when a community tool changed: nobody can edit or withdraw it. */
+  isSystem: boolean
   /**
    * The absolute instant this browser's edit window closes, or null when it is not
    * theirs. Absolute rather than a remaining duration so a client with a skewed clock
@@ -41,8 +47,10 @@ type Row = {
   id: string
   authorHash: string
   authorAlias: string
+  authorName: string | null
   body: string | null
   subject: string | null
+  kind: string | null
   status: 'applied' | 'acknowledged' | null
   reviewerReply: string | null
   reviewedAt: Date | null
@@ -53,10 +61,11 @@ type Row = {
 }
 
 function toView(row: Row, actor: Actor | null): FeedbackView {
-  const isMine = !!actor && row.authorHash === actor.hash
+  const isSystem = row.kind === MARKER_KIND
+  const isMine = !isSystem && !!actor && row.authorHash === actor.hash
   return {
     id: row.id,
-    authorName: row.authorAlias,
+    authorName: row.authorName ?? row.authorAlias,
     body: row.body,
     subject: row.subject,
     resourceSlug: row.resource?.slug ?? null,
@@ -68,6 +77,7 @@ function toView(row: Row, actor: Actor | null): FeedbackView {
     createdAt: row.createdAt.toISOString(),
     editedAt: row.editedAt?.toISOString() ?? null,
     isMine,
+    isSystem,
     canEditUntil: isMine
       ? new Date(row.createdAt.getTime() + EDIT_WINDOW_MS).toISOString()
       : null,
@@ -87,6 +97,19 @@ async function resourceIdForSlug(slug: string): Promise<string | null> {
   return resource?.id ?? null
 }
 
+async function communityToolIdForSlug(slug: string): Promise<string | null> {
+  const tool = await getDbClient().dbCommunityTool.findUnique({
+    where: { slug },
+    select: { id: true },
+  })
+  return tool?.id ?? null
+}
+
+/** What a thread hangs on: an official entry or a community tool. */
+export type FeedbackTarget =
+  | { resourceSlug: string }
+  | { communityToolSlug: string }
+
 export interface FeedbackList {
   items: FeedbackView[]
   /** Unreviewed count — what the badge shows. `status IS NULL` is the whole definition. */
@@ -95,14 +118,24 @@ export interface FeedbackList {
 
 /** Oldest first: a thread reads top to bottom. */
 export async function listFeedback(
-  resourceSlug: string,
+  target: FeedbackTarget,
   actor: Actor | null,
 ): Promise<FeedbackList> {
-  const resourceId = await resourceIdForSlug(resourceSlug)
-  if (!resourceId) return { items: [], openCount: 0 }
+  let where: { resourceId: string } | { communityToolId: string }
+  if ('resourceSlug' in target) {
+    const resourceId = await resourceIdForSlug(target.resourceSlug)
+    if (!resourceId) return { items: [], openCount: 0 }
+    where = { resourceId }
+  } else {
+    const communityToolId = await communityToolIdForSlug(
+      target.communityToolSlug,
+    )
+    if (!communityToolId) return { items: [], openCount: 0 }
+    where = { communityToolId }
+  }
 
   const rows = await getDbClient().dbFeedback.findMany({
-    where: { resourceId },
+    where,
     orderBy: { createdAt: 'asc' },
     include: WITH_RELATIONS,
   })
@@ -124,7 +157,7 @@ export async function listMyFeedback(
 ): Promise<FeedbackView[]> {
   if (!actor) return []
   const rows = await getDbClient().dbFeedback.findMany({
-    where: { authorHash: actor.hash },
+    where: { authorHash: actor.hash, kind: null },
     orderBy: [
       { status: { sort: 'asc', nulls: 'first' } },
       { createdAt: 'desc' },
@@ -177,6 +210,8 @@ function normaliseBody(body: string | undefined | null): string | null {
 export interface AddFeedbackInput {
   /** Omitted for a catalog-level ask. */
   resourceSlug?: string
+  /** The alternative to resourceSlug, for a comment on a community tool. */
+  communityToolSlug?: string
   /** Required when there is no resourceSlug — it is the substance of the ask. */
   subject?: string
   body?: string
@@ -186,10 +221,17 @@ export interface AddFeedbackInput {
 export async function addFeedback(
   input: AddFeedbackInput,
   actor: Actor,
+  user: { id: string; name: string } | null,
 ): Promise<FeedbackView> {
-  const { resourceSlug, subject, body, attachmentIds = [] } = input
+  const {
+    resourceSlug,
+    communityToolSlug,
+    subject,
+    body,
+    attachmentIds = [],
+  } = input
 
-  if (!resourceSlug && !subject?.trim()) {
+  if (!resourceSlug && !communityToolSlug && !subject?.trim()) {
     throw new FeedbackError(
       'empty',
       'Tell us which entry this is about, or what you were looking for',
@@ -209,16 +251,30 @@ export async function addFeedback(
       throw new FeedbackError('not-found', `Unknown resource: ${resourceSlug}`)
     }
   }
+  let communityToolId: string | null = null
+  if (!resourceId && communityToolSlug) {
+    communityToolId = await communityToolIdForSlug(communityToolSlug)
+    if (!communityToolId) {
+      throw new FeedbackError(
+        'not-found',
+        `Unknown community tool: ${communityToolSlug}`,
+      )
+    }
+  }
+  const onEntry = !!resourceId || !!communityToolId
 
   const row = await getDbClient().$transaction(async (tx) => {
     const created = await tx.dbFeedback.create({
       data: {
         resourceId,
-        subject: resourceId
+        communityToolId,
+        subject: onEntry
           ? null
           : stripHiddenText(subject!).trim().slice(0, MAX_SUBJECT_LENGTH),
         authorHash: actor.hash,
         authorAlias: actor.alias,
+        authorUserId: user?.id ?? null,
+        authorName: user?.name ?? null,
         body: normaliseBody(body),
       },
       select: { id: true },
@@ -258,7 +314,7 @@ export async function addFeedback(
 async function loadOwnForEdit(id: string, actor: Actor) {
   const row = await getDbClient().dbFeedback.findUnique({ where: { id } })
   if (!row) throw new FeedbackError('not-found', 'This no longer exists')
-  if (row.authorHash !== actor.hash) {
+  if (row.kind === MARKER_KIND || row.authorHash !== actor.hash) {
     throw new FeedbackError('not-author', 'Only the author can change this')
   }
   if (Date.now() > row.createdAt.getTime() + EDIT_WINDOW_MS) {
@@ -299,7 +355,7 @@ export async function dismissFeedback(
 ): Promise<{ id: string }> {
   const row = await getDbClient().dbFeedback.findUnique({ where: { id } })
   if (!row) throw new FeedbackError('not-found', 'This no longer exists')
-  if (row.authorHash !== actor.hash) {
+  if (row.kind === MARKER_KIND || row.authorHash !== actor.hash) {
     throw new FeedbackError('not-author', 'Only the author can withdraw this')
   }
   if (row.status !== null) {

package/src/server/controller.ts

@@ -9,6 +9,8 @@ import type { Resource } from '../types/common/appCatalogTypes'
 import type { BetterAuth } from '../modules/auth/auth'
 import { createAuthRouter } from '../modules/auth/authRouter.js'
 import { createFeedbackRouter } from '../modules/feedback/feedbackRouter'
+import { createCommunityToolsRouter } from '../modules/communityTools/router'
+import type { CommunityToolsOptions } from '../middleware/types'
 import { publicProcedure, router, t } from './trpcSetup'
 import { z } from 'zod'
 
@@ -35,7 +37,10 @@ const updateAppInputSchema = z.object({
  */
 export function createTrpcRouter(
   auth?: BetterAuth,
-  options?: { devLoginEnabled?: boolean },
+  options?: {
+    devLoginEnabled?: boolean
+    communityTools?: CommunityToolsOptions
+  },
 ) {
   return router({
     appCatalog: router({
@@ -69,6 +74,8 @@ export function createTrpcRouter(
 
     feedback: createFeedbackRouter(),
 
+    communityTools: createCommunityToolsRouter(options?.communityTools),
+
     // Auth routes (requires auth instance)
     auth: createAuthRouter(t, auth, options),
   })