@goscribe/server 1.3.4 → 1.5.0

package/.env.example

@@ -18,6 +18,18 @@ INFERENCE_API_URL=http://localhost:5000
 INFERENCE_API_KEY=your-inference-api-key
 INFERENCE_BASE_URL=https://api.cohere.ai/compatibility/v1
 
+# Embeddings (Knowledge Base / RAG).
+# Falls back to INFERENCE_* values if these are unset. Default model dim is 1536
+# (text-embedding-3-small). If you change EMBEDDING_DIM you must also update
+# the vector(...) column type in the Knowledge Base migration.
+EMBEDDING_API_KEY=
+EMBEDDING_BASE_URL=
+EMBEDDING_MODEL=text-embedding-3-small
+EMBEDDING_DIM=1536
+
+# Bucket used for KB document uploads (defaults to SUPABASE_BUCKET / 'media').
+SUPABASE_KB_BUCKET=media
+
 # Supabase Storage
 SUPABASE_URL=https://your-project.supabase.co
 SUPABASE_SERVICE_ROLE_KEY=your-supabase-service-role-key

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+    "prisma.pinToPrisma6": true
+}

package/REFACTOR_NOTES.md

@@ -0,0 +1,60 @@
+# Refactor notes
+
+Captured during the router → service → repository refactor. These are
+follow-up items that were **intentionally left unchanged** so the refactor
+stays behavior-preserving.
+
+## Inconsistent workspace-access semantics
+
+Today the codebase uses three different patterns to decide whether a user
+can "see" a workspace:
+
+1. **Member-inclusive** — `workspaceAccessFilter(userId)` (now
+   `workspaceAccessWhere` in `src/repositories/workspace.repository.ts`).
+   `OR: [{ ownerId }, { members: { some: { userId } } }]`. Used by:
+   `worksheets.ts`, `studyguide.ts`, `copilot.ts`, `podcast.ts` (mostly),
+   `flashcards.ts` (mostly).
+2. **Owner-only** — inline `{ ownerId: userId }`. Used by:
+   `workspace.list`, `workspace.getTree`, `workspace.create`,
+   `workspace.uploadFiles`, `workspace.uploadAndAnalyzeMedia`,
+   `flashcards.listSets` (unlike the rest of flashcards), some
+   `podcast.*` paths.
+3. **`sharedWith`-based** — `sharedWith: { some: { id } }`. Used by parts
+   of `workspace.getStats`, storage counters.
+
+The repository layer now exposes **both** `findByIdAccessible`/
+`findByIdOwned` and `WorkspaceRepository.accessibleWhere`/`.ownedWhere`
+so each call site can keep its current semantics. Unifying these is a
+follow-up that deserves its own PR and review.
+
+## Missing authorization checks in `chat.ts`
+
+`chat.ts` procedures (`getChannels`, `postMessage`, `editMessage`,
+`deleteMessage`, etc.) require only authentication — they do not check
+that the caller belongs to the target workspace or channel. The Phase 4
+extraction of `ChatService` preserves this behavior; a follow-up should
+gate these procedures on `WorkspaceRepository.findByIdAccessible`.
+
+## `auth.updateProfile` is a `publicProcedure` that requires a session
+
+`auth.updateProfile` (and a few siblings) is wired as
+`publicProcedure` but reads `ctx.session.user.id`. In practice it throws
+if called unauthenticated, but the middleware stack doesn't guarantee it.
+Should move to `authedProcedure` — not done here because it would change
+observable error codes.
+
+## `checkUsageLimit` for `studyguide.*` has an empty branch
+
+In `src/trpc.ts`, the `checkUsageLimit` middleware has a
+`studyguide.` branch with only commented reasoning and no enforcement.
+Flagged for follow-up once the study-guide limit semantics are settled.
+
+## Pre-existing failing test
+
+`src/services/worksheet-generation.service.test.ts` contains
+`mergeWorksheetGenerationConfig: override beats preset and legacy`, which
+asserts that `configOverride` wins over `legacy`. The implementation in
+`worksheet-generation.service.ts` (unchanged by this refactor) places
+`legacy` AFTER `configOverride` by design, so the test fails on `main`
+and fails after the refactor as well. Left for the user (both files
+were already dirty in the working tree when the refactor began).

package/TESTING_PROMPT.md

@@ -0,0 +1,225 @@
+# Testing prompt for the refactored server
+
+Hand this file to a fresh agent/session as the starting prompt. Everything
+below is ready to paste or reference directly.
+
+---
+
+## Context
+
+I just finished a big router → service → repository refactor of this tRPC
+server. All business logic now lives in `src/services/*.service.ts`
+(backed by `src/repositories/*.repository.ts`). Routers in `src/routers/`
+are thin shells. Full convention is documented in
+[`src/README.md`](src/README.md) and leftover follow-ups in
+[`REFACTOR_NOTES.md`](REFACTOR_NOTES.md).
+
+The refactor is behavior-preserving and `tsc --noEmit` is clean. Tests
+currently run via Node's built-in test runner (`tsx --test`):
+
+- `npm test` globs `src/**/*.test.ts`.
+- Existing tests: 5 files, 18 tests, 17 pass (one pre-existing failure
+  flagged in `REFACTOR_NOTES.md` — don't try to fix it).
+
+I want you to **add unit tests for the new services and repositories**.
+Keep the existing test framework (`node:test` + `node:assert/strict` via
+`tsx --test`). Do NOT switch to Vitest/Jest.
+
+## What to test (priority order)
+
+Pick priorities from the top. Each bullet is one file; stop when you feel
+you've hit the high-value ones or you're running low on context.
+
+### P0 — pure logic, no mocking needed
+
+These services are either pure functions or have tight logic pockets that
+pay back well in tests:
+
+1. **`src/services/worksheet-content.service.ts`** — already has a test
+   file. Extend it to cover the new `WorksheetContentService` class
+   wrapper (`mergeProgress`, `parseGenerationContent`, `parseQuestionMeta`
+   delegations).
+2. **`src/services/flashcard-progress.service.ts`** — `calculateSM2`,
+   `inferConfidence`, `confidenceToQuality` are pure and
+   decision-table-shaped. Add `flashcard-progress.service.test.ts`
+   covering:
+   - SM-2 first-correct interval depends on `consecutiveIncorrect` /
+     `totalIncorrect` thresholds (1d, 3d, 1d).
+   - SM-2 on `quality < 3` resets interval/reps and gives a +4h delay
+     only when `consecutiveIncorrect === 0 && totalIncorrect > 0`.
+   - `inferConfidence` returns `'hard'` when `!isCorrect`, regardless of
+     other params.
+   - `confidenceToQuality` mapping (`easy→5`, `medium→4`, `hard→3`).
+3. **`src/services/worksheet-generation.service.ts`** — tests already
+   exist but one is failing (the "override beats legacy" test). **Don't
+   fix the failing test.** Add more normalization cases to
+   `normalizeWorksheetProblemForDb`: MCQ with numeric answer string,
+   MCQ with text-match answer, TEXT with and without `mark_scheme`,
+   `forceMcq=true` coercion.
+
+### P1 — services that only need a fake `db`
+
+These services are easy to test with a hand-rolled fake `PrismaClient`
+(see pattern in
+[`src/services/notification.service.test.ts`](src/services/notification.service.test.ts)).
+
+4. **`src/services/workspace-analytics.service.ts`** — pure aggregation
+   of Prisma results; mock the 5 `db.*.findMany/count` calls and assert
+   the streak, weekly activity, and accuracy math.
+   - Streak = 1 when only today is in the set.
+   - Streak stays 0 when most-recent study day is 2+ days ago.
+   - `weeklyActivity` has length 7, ordered oldest → today.
+   - `accuracy` rounds correctly with non-zero `completedQuestions`.
+5. **`src/repositories/workspace.repository.ts`** — test
+   `workspaceAccessWhere(userId)` and `workspaceOwnerWhere(userId)`
+   return the expected Prisma `where` shape. Test the class's
+   `findByIdAccessible` / `findByIdOwned` call through to the fake
+   `db.workspace.findFirst` with the right `where`.
+6. **`src/services/chat.service.ts`** — small surface; test
+   `editMessage` throws `FORBIDDEN` when `chat.userId !== userId`,
+   throws `NOT_FOUND` on missing chat, and success path calls
+   `PusherService.emitChannelEvent`. Stub `PusherService.*` the same
+   way `notification.service.test.ts` stubs `PusherService.emitNotificationNew`.
+7. **`src/services/annotation.service.ts`** — `deleteHighlight` and
+   `deleteComment` ownership checks (FORBIDDEN vs NOT_FOUND).
+   `addComment` side effects: recipients exclude the author,
+   notification isn't sent when artifact version lookup returns null.
+
+### P2 — services worth integration-style tests
+
+These are orchestration-heavy. Unit tests are lower value unless you're
+willing to mock Stripe / AI session. Skip unless time permits:
+
+- `src/services/auth.service.ts` — `login` credential failure paths
+  (wrong password, deleted user, missing user).
+- `src/services/invitation.service.ts` — `acceptInvite` idempotency
+  (P2002 duplicate membership returns the already-a-member shape),
+  email-mismatch path.
+- `src/services/admin.service.ts` — `listUsers` pagination math,
+  `deletePlan` deactivation when active subs exist.
+- `src/services/payment.service.ts` — `reuseCheckoutUrlIfSessionStillOpen`
+  branch logic (requires a fake Stripe client).
+
+### P3 — skip
+
+`src/services/media-analysis.service.ts`, `podcast.service.ts`,
+`worksheet.service.ts#generateFromPrompt`, `copilot.service.ts` — all
+multi-step pipelines with external side effects. Not worth
+unit-testing; they belong to integration/E2E tests with a real or
+containerized Prisma + mocked AI. Don't bother here.
+
+## Testing conventions to follow
+
+### Framework
+
+- `node:test` + `node:assert/strict`. See
+  [`src/lib/worksheet-generation.test.ts`](src/services/worksheet-generation.service.test.ts)
+  and
+  [`src/services/notification.service.test.ts`](src/services/notification.service.test.ts)
+  for the exact shape.
+- Each test file lives next to the source (`foo.service.ts` ↔
+  `foo.service.test.ts`). `npm test` already globs them.
+- Use `import { test } from 'node:test'` + `import assert from
+  'node:assert/strict'`. No `describe`/`it` wrappers, just
+  `test('name', () => {...})`.
+
+### Faking Prisma
+
+Copy the pattern from
+[`src/services/notification.service.test.ts`](src/services/notification.service.test.ts).
+Build a minimal fake: `{ modelName: { findFirst: async () => …, create:
+async () => …, count: async () => … } }` and cast it with `as any` when
+passing into the service constructor:
+
+```ts
+const svc = new WorkspaceAnalyticsService(fakeDb as any);
+```
+
+Only stub the methods your test actually touches. Keep fakes inline in
+the test file — don't create a shared fixtures module yet.
+
+### Stubbing Pusher / email / Stripe
+
+Follow the notification-service pattern: monkey-patch the static method
+for the duration of the test and restore it at the end.
+
+```ts
+const original = PusherService.emitNotificationReadState;
+PusherService.emitNotificationReadState = async () => {};
+try {
+  // …act, assert…
+} finally {
+  PusherService.emitNotificationReadState = original;
+}
+```
+
+For Stripe, inject a fake client by re-exporting `stripe` from
+`src/lib/stripe.ts` as a `let` (it already is) and overwriting it per
+test. Or, preferred: test against the service after refactoring it to
+accept a Stripe client in the constructor (only do this if it's a
+one-line change — don't go refactoring again).
+
+### Import paths
+
+- `tsx` resolves `.js` specifiers; follow existing style (e.g.
+  `import … from './foo.service.js'` even though the file is `.ts`).
+- Prefer relative imports; there are no path aliases.
+
+## What NOT to do
+
+1. **Don't fix the pre-existing failing test** in
+   `worksheet-generation.service.test.ts` (the "override beats preset
+   and legacy" one). It's flagged in `REFACTOR_NOTES.md` as the user's
+   in-progress work.
+2. **Don't spin up a real database.** No `@prisma/client` mocking
+   libraries. Hand-rolled fakes only.
+3. **Don't switch test frameworks**, don't add `describe`/`it`, don't
+   pull in `vitest` or `jest`.
+4. **Don't test routers.** They're thin wrappers now; any behavior
+   there is covered by testing the underlying service.
+5. **Don't change service/repository code** unless a test reveals an
+   actual bug. Tests are the goal; refactoring-while-testing is out of
+   scope.
+6. **Don't test P3 items.** They need integration tests, not units.
+
+## Acceptance criteria
+
+When you're done:
+
+- `npm test` passes (except the one pre-existing failure, which should
+  remain exactly as-is — still 1 fail, but every new test you add
+  passes).
+- `npx tsc --noEmit` is clean.
+- Every new test file ends in `.service.test.ts` or `.repository.test.ts`
+  and lives next to the source file.
+- Each new test has a clear `test('verb: scenario → expected', …)` name.
+- No new runtime dependencies in `package.json`. (Dev-deps only if
+  truly necessary, but you shouldn't need any.)
+
+## Starter: which files to create
+
+Create these test files, in this order, stopping when context runs low:
+
+1. `src/services/flashcard-progress.service.test.ts` — **P0, easy win**
+2. `src/services/workspace-analytics.service.test.ts` — **P1, high value**
+3. `src/repositories/workspace.repository.test.ts`
+4. `src/services/chat.service.test.ts`
+5. `src/services/annotation.service.test.ts`
+
+Extend these existing files:
+
+6. `src/services/worksheet-content.service.test.ts` — add
+   `WorksheetContentService` class wrapper tests.
+7. `src/services/worksheet-generation.service.test.ts` — add more
+   `normalizeWorksheetProblemForDb` cases (don't touch the failing
+   test).
+
+Report back with:
+
+- Number of test files added/extended.
+- Total test count delta (`before → after`).
+- Any bugs you found along the way — log them in
+  `REFACTOR_NOTES.md` instead of fixing silently.
+
+Good luck. Go wide, not deep — better to cover 7 services shallowly than
+1 service exhaustively at this stage.