@igstack/app-catalog-backend-core 6.3.0 → 6.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@igstack/app-catalog-backend-core",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Backend core library for App Catalog",
   "homepage": "https://github.com/lislon/app-catalog",
   "repository": {
@@ -44,8 +44,8 @@
     "tsyringe": "^4.10.0",
     "yaml": "^2.8.0",
     "zod": "^4.3.5",
-    "@igstack/app-catalog-table-sync": "6.3.0",
-    "@igstack/app-catalog-shared-core": "6.3.0"
+    "@igstack/app-catalog-shared-core": "6.4.0",
+    "@igstack/app-catalog-table-sync": "6.4.0"
   },
   "devDependencies": {
     "@tanstack/vite-config": "^0.4.3",
@@ -72,7 +72,7 @@
   "engines": {
     "node": ">=24"
   },
-  "gitHead": "1d77cb454ad5fe4c483f1c158c60aa2bc21f72b9",
+  "gitHead": "b4737345fd290c2e1616fcb51c4d2e6f4e6ac57c",
   "scripts": {
     "build": "tsdown",
     "build:lenient": "tsdown",
@@ -80,7 +80,7 @@
     "compile": "tsc --build",
     "dev": "tsx watch src/index.ts",
     "fix": "prettier --write ./src && eslint --fix ./src",
-    "prisma:generate": "prisma generate",
+    "prisma:generate": "rm -rf src/generated && prisma generate",
     "test:eslint": "eslint ./src --max-warnings=0",
     "test:types": "tsc --noEmit",
     "test:unit": "vitest",

package/prisma/migrations/20261004000000_feedback_replaces_comments/migration.sql

@@ -0,0 +1,74 @@
+-- Comments become feedback: one object for a note, a correction, or an ask for something
+-- the catalog does not have yet. Ids are carried over rather than regenerated, because the
+-- review tooling prints them and a maintainer may be holding one in a terminal scrollback.
+
+-- CreateTable
+CREATE TABLE "DbFeedback" (
+    "id" TEXT NOT NULL,
+    "resourceId" TEXT,
+    "subject" TEXT,
+    "authorHash" TEXT NOT NULL,
+    "authorAlias" TEXT NOT NULL,
+    "body" TEXT,
+    "editedAt" TIMESTAMP(3),
+    "status" "CommentStatus",
+    "reviewerReply" TEXT,
+    "reviewedAt" TIMESTAMP(3),
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+    "updatedAt" TIMESTAMP(3) NOT NULL,
+
+    CONSTRAINT "DbFeedback_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateTable
+CREATE TABLE "DbFeedbackAttachment" (
+    "id" TEXT NOT NULL,
+    "feedbackId" TEXT,
+    "authorHash" TEXT NOT NULL,
+    "content" BYTEA NOT NULL,
+    "mimeType" TEXT NOT NULL,
+    "fileSize" INTEGER NOT NULL,
+    "checksum" TEXT NOT NULL,
+    "width" INTEGER,
+    "height" INTEGER,
+    "originalFilename" TEXT NOT NULL,
+    "createdAt" TIMESTAMP(3) NOT NULL DEFAULT CURRENT_TIMESTAMP,
+
+    CONSTRAINT "DbFeedbackAttachment_pkey" PRIMARY KEY ("id")
+);
+
+-- CreateIndex
+CREATE INDEX "DbFeedback_resourceId_createdAt_idx" ON "DbFeedback"("resourceId", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "DbFeedback_authorHash_idx" ON "DbFeedback"("authorHash");
+
+-- CreateIndex
+CREATE INDEX "DbFeedback_status_createdAt_idx" ON "DbFeedback"("status", "createdAt");
+
+-- CreateIndex
+CREATE INDEX "DbFeedbackAttachment_feedbackId_idx" ON "DbFeedbackAttachment"("feedbackId");
+
+-- CreateIndex
+-- Covers both the ownership check on submit and the orphan sweep.
+CREATE INDEX "DbFeedbackAttachment_authorHash_createdAt_idx" ON "DbFeedbackAttachment"("authorHash", "createdAt");
+
+-- AddForeignKey
+ALTER TABLE "DbFeedback" ADD CONSTRAINT "DbFeedback_resourceId_fkey" FOREIGN KEY ("resourceId") REFERENCES "DbResource"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- AddForeignKey
+ALTER TABLE "DbFeedbackAttachment" ADD CONSTRAINT "DbFeedbackAttachment_feedbackId_fkey" FOREIGN KEY ("feedbackId") REFERENCES "DbFeedback"("id") ON DELETE CASCADE ON UPDATE CASCADE;
+
+-- Carry every existing comment across, ids and review state intact. `body` was NOT NULL on
+-- DbComment and is nullable here, so nothing needs coercing.
+INSERT INTO "DbFeedback" (
+    "id", "resourceId", "subject", "authorHash", "authorAlias", "body",
+    "editedAt", "status", "reviewerReply", "reviewedAt", "createdAt", "updatedAt"
+)
+SELECT
+    "id", "resourceId", NULL, "authorHash", "authorAlias", "body",
+    "editedAt", "status", "reviewerReply", "reviewedAt", "createdAt", "updatedAt"
+FROM "DbComment";
+
+-- DropTable
+DROP TABLE "DbComment";

package/prisma/schema.prisma

@@ -115,6 +115,7 @@ model DbApprovalMethod {
   slug              String             @id
   type              ApprovalMethodType
   displayName       String
+  shortName         String? // One or two words for tight spots (the detail card's access tab); falls back to displayName
   /// [ApprovalMethodConfig] - Type-specific configuration
   config            Json?
   deprecatedAliases String[]           @default([]) // Old URLs that should redirect to this method
@@ -156,8 +157,9 @@ model DbResource {
   tiers                      Json?
   /// [QuickJump[]]
   quickJumps                 Json?
+  childrenLabel              String? // Plural noun for this resource's children ("Accounts"); set on the parent, names its tab
   sourceRefs                 SourceReference[]
-  comments                   DbComment[]
+  feedback                   DbFeedback[]
   // Self-referential tree: sub-resources point to their parent
   parentSlug                 String?
   parent                     DbResource?       @relation("ResourceTree", fields: [parentSlug], references: [slug])
@@ -195,37 +197,95 @@ enum CommentStatus {
   acknowledged
 }
 
-/// A visitor's comment on one resource.
+/// One piece of visitor input about the catalog: a note, a correction, or an ask for
+/// something that is not in the catalog yet.
 ///
-/// The catalog is browsable without logging in, so a comment carries no user id.
-/// Instead the server issues an opaque visitor token in an httpOnly cookie and
-/// stores its hash: enough to let an author edit or delete their own comment for
-/// a short window, and nothing a reader can forge.
-model DbComment {
-  id         String     @id @default(cuid())
-  // The resource's id, not its slug — a slug is user-facing and gets renamed.
-  resourceId String
-  resource   DbResource @relation(fields: [resourceId], references: [id], onDelete: Cascade)
-  // sha256 of the visitor token. Authorises edit/delete; never sent to a client.
+/// Browsable without logging in, so this carries no user id. The server issues an
+/// opaque visitor token in an httpOnly cookie and stores its hash: enough to let an
+/// author edit or withdraw their own, and nothing a reader can forge.
+///
+/// There is deliberately no `kind` discriminator. "Is anyone waiting on this" is
+/// `status IS NULL`, and "is this about an entry or about the catalog" is whether
+/// `resourceId` is set — so an enum would encode nothing the row does not already say,
+/// and asking a visitor to classify their own report costs more than it buys.
+model DbFeedback {
+  id String @id @default(cuid())
+
+  /// Null for a catalog-level ask ("please add X") — there is no entry to hang it on.
+  /// The resource's id, not its slug: a slug is user-facing and gets renamed.
+  resourceId String?
+  resource   DbResource? @relation(fields: [resourceId], references: [id], onDelete: Cascade)
+
+  /// What the visitor was looking for when nothing matched. Set only when resourceId is
+  /// null — it is the whole substance of a new-app ask, and the thing we research.
+  subject String?
+
+  /// sha256 of the visitor token. Authorises edit/withdraw; never sent to a client.
   authorHash String
-  // The pseudonym shown next to the comment, stored rather than derived at render
-  // time so editing the wordlist later cannot rename everybody's history.
+  /// The pseudonym shown alongside, stored rather than derived at render time so
+  /// widening the wordlist later cannot rename everybody's history.
   authorAlias String
-  body        String
-  // Set on a later edit, so the UI can mark a comment as edited. Null when never edited.
-  editedAt    DateTime?
-  // What a maintainer did with the comment. Null until someone reviews it; the UI
-  // shows a label for the other two so a commenter can see their note landed.
-  // Written out of band (review tooling), never by a visitor.
-  status      CommentStatus?
-  // One short answer from the maintainers, shown under the comment body.
+
+  /// Optional: a bare flag with no words is a valid signal, and the cheapest one a
+  /// passing visitor can send.
+  body String?
+
+  attachments DbFeedbackAttachment[]
+
+  /// Set on a later edit, so the UI can mark it edited. Null when never edited.
+  editedAt DateTime?
+
+  /// What a maintainer did with it. Null until reviewed — which is also what "open"
+  /// means, so pending needs no stored value. Written out of band by review tooling,
+  /// never by a visitor.
+  status        CommentStatus?
   reviewerReply String?
   reviewedAt    DateTime?
-  createdAt   DateTime  @default(now())
-  updatedAt   DateTime  @updatedAt
+
+  createdAt DateTime @default(now())
+  updatedAt DateTime @updatedAt
 
   @@index([resourceId, createdAt])
   @@index([authorHash])
+  /// Drives the unreviewed counts on both surfaces: open items, newest first.
+  @@index([status, createdAt])
+}
+
+/// An image attached to one piece of feedback.
+///
+/// Deliberately not a DbAsset: that model's `name` is `@unique` and that namespace holds
+/// published, reviewed assets, so an unreviewed stranger's upload must not be able to
+/// squat `jira.svg`. Promoting an attached logo into a real icon is an explicit
+/// maintainer step through the existing upsertAsset.
+model DbFeedbackAttachment {
+  id String @id @default(cuid())
+
+  /// Null between upload and submit: an image is stored before the feedback row exists,
+  /// so abandoning the form leaves an orphan image rather than half-written feedback.
+  /// A sweep deletes orphans older than a day.
+  feedbackId String?
+  feedback   DbFeedback? @relation(fields: [feedbackId], references: [id], onDelete: Cascade)
+
+  /// Who uploaded it, so submitting can only claim your OWN unclaimed images. Without
+  /// this, `feedbackId` being a single FK means attaching a guessed id would MOVE that
+  /// image off somebody else's feedback.
+  authorHash String
+
+  /// Re-encoded by sharp before storage, so this is always one of our own formats and
+  /// never whatever bytes arrived.
+  content  Bytes
+  mimeType String
+  fileSize Int
+  checksum String
+  width    Int?
+  height   Int?
+  /// The uploader's filename, shown to a maintainer. Never used as a path or a key.
+  originalFilename String
+
+  createdAt DateTime @default(now())
+
+  @@index([feedbackId])
+  @@index([authorHash, createdAt])
 }
 
 model DbAppTagDefinition {

package/src/__tests__/feedbackAttachmentUpload.test.ts

@@ -0,0 +1,192 @@
+// @vitest-environment node
+import express from 'express'
+import type { AddressInfo } from 'node:net'
+import sharp from 'sharp'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import * as dbClient from '../db/client'
+import type { PrismaClient } from '../generated/prisma/client'
+import { registerFeedbackAttachmentController } from '../modules/feedback/feedbackAttachmentController'
+
+/**
+ * Drives the real route over HTTP — multer, sharp and all — because every property
+ * worth asserting here is about what the middleware chain does to bytes a stranger
+ * supplied, and a unit test of the handler alone would skip all of it.
+ */
+const startApp = async () => {
+  const app = express()
+  const router = express.Router()
+  registerFeedbackAttachmentController(router, {
+    basePath: '/api/feedback-attachments',
+  })
+  app.use(router)
+  const server = app.listen(0)
+  await new Promise((resolve) => server.once('listening', resolve))
+  const { port } = server.address() as AddressInfo
+  return { server, base: `http://127.0.0.1:${port}` }
+}
+
+const create = vi.fn()
+const deleteMany = vi.fn()
+
+/** The bytes handed to persistence — i.e. what would actually be stored. */
+const storedRows = () => create.mock.calls.map(([{ data }]) => data)
+
+const postImages = (
+  base: string,
+  files: { body: Buffer; type: string; name: string }[],
+  cookie?: string,
+) => {
+  const form = new FormData()
+  for (const f of files) {
+    form.append(
+      'image',
+      new Blob([new Uint8Array(f.body)], { type: f.type }),
+      f.name,
+    )
+  }
+  return fetch(`${base}/api/feedback-attachments/upload`, {
+    method: 'POST',
+    body: form,
+    headers: cookie ? { cookie } : {},
+  })
+}
+
+/** The visitor cookie the first response minted, in a form fetch will send back. */
+const visitorCookie = (res: Response): string => {
+  const raw = res.headers.getSetCookie().find((c) => c.startsWith('ac_cid='))
+  return raw ? (raw.split(';')[0] ?? '') : ''
+}
+
+const png = (width: number, height: number) =>
+  sharp({
+    create: { width, height, channels: 3, background: { r: 10, g: 20, b: 30 } },
+  })
+    .png()
+    .toBuffer()
+
+describe('feedback attachment upload', () => {
+  let server: Awaited<ReturnType<typeof startApp>>['server']
+  let base: string
+
+  beforeEach(async () => {
+    create.mockReset()
+    deleteMany.mockReset()
+    deleteMany.mockResolvedValue({ count: 0 })
+    create.mockImplementation(({ data }) => ({
+      id: `att-${create.mock.calls.length}`,
+      ...data,
+    }))
+    vi.spyOn(dbClient, 'getDbClient').mockReturnValue({
+      dbFeedbackAttachment: { create, deleteMany },
+    } as unknown as PrismaClient)
+    vi.spyOn(console, 'error').mockImplementation(() => {})
+    ;({ server, base } = await startApp())
+  })
+
+  afterEach(() => {
+    server.close()
+    vi.mocked(console.error).mockRestore()
+  })
+
+  /**
+   * The whole security model in one assertion: nothing a visitor uploads is ever the
+   * thing we store. Decoding to pixels and re-encoding is what drops EXIF, trailing
+   * data and anything polyglot — a content-type check would wave all of it through.
+   */
+  it('stores its own re-encoded webp, never the uploaded bytes', async () => {
+    const original = await png(120, 80)
+    const res = await postImages(base, [
+      { body: original, type: 'image/png', name: 'shot.png' },
+    ])
+
+    expect(res.status).toBe(201)
+    const [row] = storedRows()
+    expect(row.mimeType).toBe('image/webp')
+    expect(Buffer.from(row.content).equals(original)).toBe(false)
+    // Really a webp, by its own magic bytes rather than by what we labelled it.
+    expect(Buffer.from(row.content).subarray(8, 12).toString()).toBe('WEBP')
+    expect(row.width).toBe(120)
+    expect(row.height).toBe(80)
+    expect(row.fileSize).toBe(row.content.byteLength)
+  })
+
+  it('rasterises a script-bearing SVG, so no script survives storage', async () => {
+    const svg = Buffer.from(
+      '<svg xmlns="http://www.w3.org/2000/svg" width="40" height="40">' +
+        '<rect width="40" height="40" fill="green"/><script>alert(1)</script></svg>',
+    )
+    const res = await postImages(base, [
+      { body: svg, type: 'image/svg+xml', name: 'logo.svg' },
+    ])
+
+    expect(res.status).toBe(201)
+    const [row] = storedRows()
+    expect(row.mimeType).toBe('image/webp')
+    expect(Buffer.from(row.content).includes('alert')).toBe(false)
+  })
+
+  it('refuses something that is not an image, whatever it claims to be', async () => {
+    const res = await postImages(base, [
+      { body: Buffer.from('just text'), type: 'image/png', name: 'fake.png' },
+    ])
+
+    expect(res.status).toBe(400)
+    expect(await res.json()).toEqual({
+      error: 'Not a readable image: fake.png',
+    })
+    expect(storedRows()).toHaveLength(0)
+  })
+
+  /**
+   * Multer's limit errors used to reach express's default handler, which answers a
+   * public endpoint with an HTML stack trace carrying absolute server paths.
+   */
+  it('answers its own limits as JSON, with no stack trace', async () => {
+    const small = await png(10, 10)
+    const res = await postImages(
+      base,
+      Array.from({ length: 4 }, (_, i) => ({
+        body: small,
+        type: 'image/png',
+        name: `s${i}.png`,
+      })),
+    )
+
+    expect(res.status).toBe(400)
+    expect(await res.json()).toEqual({ error: 'Up to 3 images' })
+    expect(res.headers.get('content-type')).toContain('application/json')
+  })
+
+  it('records the uploader, and leaves the image unclaimed until it is submitted', async () => {
+    const res = await postImages(base, [
+      { body: await png(20, 20), type: 'image/png', name: 'a.png' },
+    ])
+
+    expect(res.status).toBe(201)
+    const [row] = storedRows()
+    expect(row.authorHash).toMatch(/^[0-9a-f]{16,}$/)
+    // Unset on purpose: the feedback row does not exist yet, so abandoning the form
+    // leaves an orphan image rather than half-written feedback.
+    expect(row.feedbackId).toBeUndefined()
+  })
+
+  it('cuts a browser off after its hourly budget', async () => {
+    const small = await png(8, 8)
+    const file = { body: small, type: 'image/png', name: 'r.png' }
+
+    // The first request mints the visitor; reusing its cookie is what makes the
+    // remaining 20 count against ONE browser rather than twenty strangers.
+    const first = await postImages(base, [file])
+    expect(first.status).toBe(201)
+    const cookie = visitorCookie(first)
+    expect(cookie).not.toBe('')
+
+    const codes = [first.status]
+    for (let i = 0; i < 20; i++) {
+      codes.push((await postImages(base, [file], cookie)).status)
+    }
+
+    expect(codes.filter((c) => c === 201)).toHaveLength(20)
+    expect(codes.at(-1)).toBe(429)
+  })
+})

package/src/__tests__/{comments.test.ts → visitorIdentity.test.ts}

@@ -3,7 +3,7 @@ import {
   VISITOR_COOKIE,
   aliasForHash,
   resolveVisitor,
-} from '../modules/comments/visitorIdentity'
+} from '../modules/visitor/visitorIdentity'
 
 /**
  * A comment carries no user id — the catalog is browsable logged out. The visitor

package/src/db/syncAppCatalog.ts

@@ -313,6 +313,7 @@ export async function syncAppCatalog(
         urlIssues: resource.urlIssues ?? [],
         tiers: resource.tiers ?? null,
         quickJumps: resource.quickJumps ?? null,
+        childrenLabel: resource.childrenLabel ?? null,
         // Fields from former SubResource
         parentSlug: resource.parentSlug ?? null,
         tier: resource.tier ?? null,

package/src/generated/prisma/browser.ts

@@ -63,15 +63,30 @@ export type DbApprovalMethod = Prisma.DbApprovalMethodModel
  */
 export type DbResource = Prisma.DbResourceModel
 /**
- * Model DbComment
- * A visitor's comment on one resource.
+ * Model DbFeedback
+ * One piece of visitor input about the catalog: a note, a correction, or an ask for
+ * something that is not in the catalog yet.
  * 
- * The catalog is browsable without logging in, so a comment carries no user id.
- * Instead the server issues an opaque visitor token in an httpOnly cookie and
- * stores its hash: enough to let an author edit or delete their own comment for
- * a short window, and nothing a reader can forge.
+ * Browsable without logging in, so this carries no user id. The server issues an
+ * opaque visitor token in an httpOnly cookie and stores its hash: enough to let an
+ * author edit or withdraw their own, and nothing a reader can forge.
+ * 
+ * There is deliberately no `kind` discriminator. "Is anyone waiting on this" is
+ * `status IS NULL`, and "is this about an entry or about the catalog" is whether
+ * `resourceId` is set — so an enum would encode nothing the row does not already say,
+ * and asking a visitor to classify their own report costs more than it buys.
+ */
+export type DbFeedback = Prisma.DbFeedbackModel
+/**
+ * Model DbFeedbackAttachment
+ * An image attached to one piece of feedback.
+ * 
+ * Deliberately not a DbAsset: that model's `name` is `@unique` and that namespace holds
+ * published, reviewed assets, so an unreviewed stranger's upload must not be able to
+ * squat `jira.svg`. Promoting an attached logo into a real icon is an explicit
+ * maintainer step through the existing upsertAsset.
  */
-export type DbComment = Prisma.DbCommentModel
+export type DbFeedbackAttachment = Prisma.DbFeedbackAttachmentModel
 /**
  * Model DbAppTagDefinition
  * 

package/src/generated/prisma/client.ts

@@ -87,15 +87,30 @@ export type DbApprovalMethod = Prisma.DbApprovalMethodModel
  */
 export type DbResource = Prisma.DbResourceModel
 /**
- * Model DbComment
- * A visitor's comment on one resource.
+ * Model DbFeedback
+ * One piece of visitor input about the catalog: a note, a correction, or an ask for
+ * something that is not in the catalog yet.
  * 
- * The catalog is browsable without logging in, so a comment carries no user id.
- * Instead the server issues an opaque visitor token in an httpOnly cookie and
- * stores its hash: enough to let an author edit or delete their own comment for
- * a short window, and nothing a reader can forge.
+ * Browsable without logging in, so this carries no user id. The server issues an
+ * opaque visitor token in an httpOnly cookie and stores its hash: enough to let an
+ * author edit or withdraw their own, and nothing a reader can forge.
+ * 
+ * There is deliberately no `kind` discriminator. "Is anyone waiting on this" is
+ * `status IS NULL`, and "is this about an entry or about the catalog" is whether
+ * `resourceId` is set — so an enum would encode nothing the row does not already say,
+ * and asking a visitor to classify their own report costs more than it buys.
+ */
+export type DbFeedback = Prisma.DbFeedbackModel
+/**
+ * Model DbFeedbackAttachment
+ * An image attached to one piece of feedback.
+ * 
+ * Deliberately not a DbAsset: that model's `name` is `@unique` and that namespace holds
+ * published, reviewed assets, so an unreviewed stranger's upload must not be able to
+ * squat `jira.svg`. Promoting an attached logo into a real icon is an explicit
+ * maintainer step through the existing upsertAsset.
  */
-export type DbComment = Prisma.DbCommentModel
+export type DbFeedbackAttachment = Prisma.DbFeedbackAttachmentModel
 /**
  * Model DbAppTagDefinition
  *