feat(packages/export): add @klicker-uzh/export package for assessment course data export (#5043)

Author: rschlaefli

AGENTS.md

@@ -210,6 +210,8 @@ Without Traefik, use `http://localhost:<port>` directly. The `*.klicker.com` dom
 - **Infisical + Turbo env sync**: Any Infisical-managed env var used by tasks must be listed in `turbo.json` `globalEnv`; otherwise task runs/cache behavior can become stale or inconsistent across environments.
 - **Participant email uniqueness across auth modes**: Prisma enforces `Participant @@unique([email, isSSOAccount])`, so the same normalized email can exist once as manual and once as SSO. To block new cross-mode duplicates, account creation must explicitly check normalized email collisions in service logic. (`packages/graphql/src/services/accounts.ts`)
 - **Helm v3 secrets are external**: `deploy/charts/klicker-uzh-v3/` deployments reference `envFrom.secretRef` names, but the chart currently defines no `Secret` manifests; secrets must be provisioned out-of-band with matching names. (`deploy/charts/klicker-uzh-v3/templates/`)
+- **ExcelJS sheet-name collisions are case-insensitive**: When generating workbook sheet names, enforce uniqueness on a normalized lowercase key and keep the full name within Excel's 31-character limit; distinct casing alone is not enough to avoid collisions. (`packages/export/src/exportCourse.ts`)
+- **ExcelJS autoFilter must span data rows**: Setting `worksheet.autoFilter` to a header-only range (`to.row === 1`) or on an empty sheet makes Excel (esp. macOS) flag the workbook as "needs repair" on open even though the XML is well-formed. Set the range to the last data row (`to.row = rows.length + 1`) and skip autoFilter on header-only sheets. (`packages/export/src/exportCourse.ts` `addSheet`)
 - **Production rollout strategy**: Do not use `Recreate` for production web/API Deployments; PDBs do not protect against Deployment-driven scale-downs, so slow image pulls can leave services with zero endpoints. Use `RollingUpdate` in `deploy/env-uzh-prd/values.yaml`, with `maxUnavailable: 0` only for singleton services and `1` for multi-replica services.
 - **Edited chat image hydration needs a stable source id**: Edited branch messages in `apps/chat` get fresh local message ids, so image hydration must distinguish the local target message id from the persisted source message id (`attachmentSourceMessageId`) when fetching and merging attachments. (`apps/chat/src/hooks/useThreadManagement.ts`, `apps/chat/src/stores/chatStore.ts`)
 - **Assistant UI chat drop targets**: `ComposerPrimitive.AttachmentDropzone` must wrap both normal and edit chat composer roots; it owns the drag/drop capture handlers that prevent native browser file navigation, while Klicker-specific limits stay in local composer code. (`apps/chat/src/components/thread.tsx`)
@@ -220,6 +222,7 @@ Without Traefik, use `http://localhost:<port>` directly. The `*.klicker.com` dom
 - **Local embed harness target**: `util/embed-harness/` is for local verification only and should target the branch-local PWA (`http://127.0.0.1:3101/...`), not `https://pwa.klicker.com/...`, because production CSP / `frame-ancestors` blocks localhost embedding. (`util/embed-harness/`)
 - **Chat PWA login redirects**: `apps/chat/src/app/noLogin/page.tsx` must pass an absolute chat URL to the PWA login `redirect_to`; a relative chatbot path makes the PWA redirect to its own domain and 404. Local chat dev also needs ignored local env values for the backend `APP_SECRET` and `DATABASE_URL` so participant cookies verify and Prisma can load chatbot data.
 - **Chat Vitest alias resolution**: `apps/chat/vitest.config.ts` mirrors the app `@/*` alias from `apps/chat/tsconfig.json`; keep this in sync when adding client tests for modules that import from `@/src/...`.
+- **Export package Prisma row typing**: `packages/export` selects nested `ElementInstance` / `ElementBlock` relations through Prisma, but generated relation inference can collapse those nested fields to `never`; keep explicit row DTOs at the query boundary and cast the read result there instead of spreading casts through transforms. (`packages/export/src/`)
 
 ## Factory Skills (AI Assistance)
 

cypress/cypress/e2e/N-course-workflow.cy.ts

@@ -1831,6 +1831,12 @@ describe('Test course creation and editing functionalities', function () {
     cy.get('[data-cy="courses"]').click()
     cy.get(`[data-cy="course-list-button-${this.data.sharing.course}"]`).click()
     cy.get('[data-cy="course-share-button"]').click()
+    cy.get(`[data-cy="owner-permission-${Cypress.env('LECTURER_SHORTNAME')}"]`)
+      .should('exist')
+      .contains(messages.manage.sharing.permissionsOWNER)
+    cy.get(
+      `[data-cy="permission-${Cypress.env('LECTURER_IND_SHORTNAME')}"]`
+    ).should('exist')
 
     cy.get(
       `[data-cy="revoke-permission-${Cypress.env('LECTURER_IND_SHORTNAME')}"]`
@@ -2199,6 +2205,10 @@ describe('Test course creation and editing functionalities', function () {
     cy.get('[data-cy="courses"]').click()
     cy.get(`[data-cy="course-list-button-${this.data.sharing.course}"]`).click()
     cy.get('[data-cy="course-share-button"]').click()
+    cy.get(`[data-cy="owner-permission-${Cypress.env('LECTURER_SHORTNAME')}"]`)
+      .should('exist')
+      .contains(messages.manage.sharing.permissionsOWNER)
+    cy.get(`[data-cy="permission-${this.data.sharing.group1}"]`).should('exist')
 
     cy.get(`[data-cy="revoke-permission-${this.data.sharing.group1}"]`).click()
     cy.get('[data-cy="confirm-revocation"]').click()

cypress/cypress/e2e/O-live-quiz-workflow.cy.ts

@@ -1066,8 +1066,11 @@ describe('Different live-quiz workflows', function () {
     // login student again on mobile, test navigation and answer second question
     cy.viewport('iphone-x')
     cy.loginStudent()
-    cy.findByText(this.data.course2.quiz.displayName).click()
-    cy.findByText(this.data.NR.content).should('exist')
+    cy.findByText(this.data.course2.quiz.displayName).should('exist').click()
+    cy.findByText(this.data.NR.content, { timeout: 10000 }).should('exist')
+    cy.findByText(messages.pwa.liveQuiz.allQuestionsAnswered).should(
+      'not.exist'
+    )
 
     cy.get('[data-cy="mobile-menu-leaderboard"]').click()
     cy.get('[data-cy="mobile-menu-feedbacks"]').click()
@@ -1140,9 +1143,15 @@ describe('Different live-quiz workflows', function () {
     cy.wait(1000)
 
     // make both feedbacks visible and respond to one of them (moderation enabled)
+    cy.get(
+      `[data-cy="publish-feedback-${this.data.course2.quiz.feedbackDesktop}"]`
+    ).should('exist')
     cy.get(
       `[data-cy="publish-feedback-${this.data.course2.quiz.feedbackDesktop}"]`
     ).click()
+    cy.get(
+      `[data-cy="publish-feedback-${this.data.course2.quiz.feedbackMobile}"]`
+    ).should('exist')
     cy.get(
       `[data-cy="publish-feedback-${this.data.course2.quiz.feedbackMobile}"]`
     ).click()

cypress/cypress/support/commands.ts

@@ -117,6 +117,18 @@ Cypress.Commands.add('cleanup', () => {
   cy.reload()
 })
 
+const clearPersistedClientState = () => {
+  return cy.wrap(null, { log: false }).then(async () => {
+    await localforage.clear()
+  })
+}
+
+const assertManageSession = () => {
+  cy.location('origin').should('eq', Cypress.env('URL_MANAGE'))
+  cy.location('pathname').should('not.eq', '/login')
+  cy.location('search').should('not.contain', 'expired=true')
+}
+
 const loginFactory = (
   tokenData: {
     email: string
@@ -158,6 +170,10 @@ const loginFactory = (
     })
 
     cy.visit(redirectUrl ?? Cypress.env('URL_MANAGE'))
+
+    if (!redirectUrl) {
+      assertManageSession()
+    }
   }
 }
 
@@ -277,6 +293,9 @@ Cypress.Commands.add(
 )
 
 Cypress.Commands.add('logoutUser', () => {
+  cy.clearAllLocalStorage()
+  cy.clearAllSessionStorage()
+  clearPersistedClientState()
   cy.clearCookie('next-auth.session-token')
 })
 
@@ -289,7 +308,18 @@ Cypress.Commands.add(
   ({ username }: { username: string }) => {
     cy.clearAllCookies()
     cy.clearAllLocalStorage()
-    cy.visit(Cypress.env('URL_STUDENT_LOGIN'))
+    cy.visit(Cypress.env('URL_STUDENT_LOGIN'), {
+      onBeforeLoad: (win) => {
+        win.localStorage.clear()
+        win.sessionStorage.clear()
+        try {
+          win.indexedDB?.deleteDatabase('localforage')
+        } catch {
+          // Fall back to the regular localforage clear after load.
+        }
+      },
+    })
+    clearPersistedClientState()
     cy.get('[data-cy="username-field"]').click().type(username)
     cy.get('[data-cy="password-field"]')
       .click()

packages/export/.gitignore

@@ -0,0 +1 @@
+export-output/

packages/export/README.md

@@ -0,0 +1,91 @@
+# @klicker-uzh/export
+
+Standalone, **read-only** CLI that exports a single course's (or several courses') live-quiz data to CSV + XLSX for offline analysis.
+
+It is **not** imported by any app and **not** part of any deployment — it is run manually by an operator, on demand. The only production contact is pointing it at a read-only production `DATABASE_URL`.
+
+## Scope
+
+Exports **live-quiz data only**:
+
+- `LiveQuizResponse` — one row per response
+- `Participation` — enrolled participants
+- `ParticipantInvitation` — invitations
+- `AppliedPointCorrection` — lecturer point corrections (audit)
+- plus two dimension sheets: live quizzes and element instances
+
+It does **not** include practice-quiz / microlearning `QuestionResponse`, `QuestionResponseDetail`, or `GroupActivityInstance`. The scope (included/excluded models) is recorded in every export's `manifest.json` so a course with those activity types is not mistaken for "fully exported".
+
+## Usage
+
+```bash
+# build the compiled binary (no tsx at runtime)
+pnpm --filter @klicker-uzh/export build
+
+# single course
+pnpm --filter @klicker-uzh/export export -- --courseId <uuid> [--outputDir <path>] [--pseudonymize]
+
+# multiple courses (also writes a combined workbook)
+pnpm --filter @klicker-uzh/export export -- --courseId <uuid1> --courseId <uuid2>
+
+# development (runs via tsx, no build step)
+pnpm --filter @klicker-uzh/export export:dev -- --courseId <uuid>
+
+# against production secrets (read-only URL)
+infisical run --env prd -- \
+  node packages/export/dist/scripts/export-course.js --courseId <uuid> --outputDir <path>
+```
+
+Flags:
+
+- `--courseId <uuid>` — required, repeatable for multi-course export
+- `--outputDir <path>` — default `./export-output`
+- `--pseudonymize` — de-identify direct identifiers (see below)
+
+## Output
+
+```
+<outputDir>/
+  <courseName>_<courseId>/
+    export.xlsx              # 6 sheets, frozen header + per-column filters
+    responses.csv
+    participants.csv
+    invitations.csv
+    corrections.csv
+    live_quizzes.csv
+    element_instances.csv
+    manifest.json            # schema version, counts, scope, per-file SHA-256, data dictionary
+  combined-export.xlsx       # only when >1 course is exported
+```
+
+Files are written `0600`, directories `0700`.
+
+### Sheets and join keys
+
+| Sheet               | Join key                                                             |
+| ------------------- | -------------------------------------------------------------------- |
+| `RESPONSES`         | `liveQuizResponseId` (PK); `elementInstanceId` → `ELEMENT_INSTANCES` |
+| `PARTICIPANTS`      | `participantId` (PK)                                                 |
+| `INVITATIONS`       | `participantId`                                                      |
+| `CORRECTIONS`       | `liveQuizResponseId` + `elementBlockExecution` → `RESPONSES`         |
+| `LIVE_QUIZZES`      | `liveQuizId` (includes zero-response quizzes)                        |
+| `ELEMENT_INSTANCES` | `elementInstanceId` (full untruncated content + point config)        |
+
+`RESPONSES` carries both the raw `response` JSON and flattened `response_choices` / `response_value` / `response_selection` / `response_assessment` columns so analysts can avoid parsing JSON.
+
+## Safety
+
+- **Read-only DB access** — `createReadonlyClient` narrows the Prisma client to read operations at compile time, and a runtime `$allOperations` guard blocks every non-read operation, including raw queries (`$queryRaw` / `$executeRaw` / `…Unsafe`).
+- **PII modes** — default `full` writes identifiers verbatim (with a loud stderr warning); `--pseudonymize` hashes email / SSO id+email / matriculation number (per-run HMAC-SHA256 salt, never persisted) and redacts free-text answers and raw response JSON.
+- **CSV** — UTF-8 BOM, one physical line per row (embedded newlines normalized), formula-injection escaping (`= + - @`).
+- **Integrity** — `manifest.json` records per-file SHA-256, counts, package version, PII mode, scope, and a data dictionary for the cryptic + flattened columns.
+
+Output directories contain PII and are gitignored.
+
+## Development
+
+```bash
+pnpm --filter @klicker-uzh/export check   # tsc --noEmit
+pnpm --filter @klicker-uzh/export test     # vitest
+pnpm --filter @klicker-uzh/export build    # rollup -> dist/ + dist/scripts/export-course.js
+```

packages/export/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@klicker-uzh/export",
+  "version": "3.4.0-alpha.62",
+  "license": "AGPL-3.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@klicker-uzh/prisma": "workspace:*",
+    "exceljs": "4.4.0"
+  },
+  "devDependencies": {
+    "@klicker-uzh/types": "workspace:*",
+    "@rollup/plugin-node-resolve": "~15.3.1",
+    "@rollup/plugin-typescript": "~12.1.4",
+    "@types/node": "^20.19.11",
+    "cross-env": "~7.0.3",
+    "npm-run-all": "~4.1.5",
+    "rollup": "~4.34.9",
+    "tsx": "~4.19.4",
+    "typescript": "~5.6.3",
+    "vitest": "~3.2.4"
+  },
+  "scripts": {
+    "build": "run-s build:ts",
+    "build:test": "pnpm run build",
+    "build:ts": "cross-env NODE_ENV=production rollup -c && chmod +x dist/scripts/export-course.js",
+    "check": "tsc --noEmit",
+    "dev": "cross-env NODE_ENV=development rollup -c --watch",
+    "export": "node dist/scripts/export-course.js",
+    "export:dev": "tsx src/scripts/export-course.ts",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "engines": {
+    "node": "=20"
+  },
+  "volta": {
+    "extends": "../../package.json"
+  },
+  "bin": {
+    "klicker-export": "dist/scripts/export-course.js"
+  },
+  "type": "module"
+}

packages/export/rollup.config.js

@@ -0,0 +1,48 @@
+import { nodeResolve } from '@rollup/plugin-node-resolve'
+import typescript from '@rollup/plugin-typescript'
+import { defineConfig } from 'rollup'
+
+const config = defineConfig([
+  {
+    // Main build configuration (library entry)
+    input: ['src/index.ts'],
+    output: {
+      dir: 'dist',
+      format: 'esm',
+      sourcemap: true,
+      entryFileNames: '[name].js',
+    },
+    plugins: [
+      nodeResolve(),
+      typescript({
+        tsconfig: './tsconfig.json',
+        rootDir: 'src',
+      }),
+    ],
+    external: [/@klicker-uzh*/, /node_modules/],
+  },
+  {
+    // CLI binary: compile the export script so production runs need no tsx/esbuild
+    input: ['src/scripts/export-course.ts'],
+    output: {
+      dir: 'dist/scripts',
+      format: 'esm',
+      sourcemap: true,
+      entryFileNames: '[name].js',
+      banner: '#!/usr/bin/env node',
+    },
+    plugins: [
+      nodeResolve(),
+      typescript({
+        tsconfig: './tsconfig.json',
+        rootDir: 'src',
+        outDir: 'dist/scripts',
+        declaration: false,
+        declarationMap: false,
+      }),
+    ],
+    external: [/@klicker-uzh*/, /node_modules/],
+  },
+])
+
+export default config

packages/export/src/cli.ts

@@ -0,0 +1,75 @@
+export const EXPORT_COURSE_USAGE =
+  'Usage: pnpm --filter @klicker-uzh/export export -- --courseId <id> [--courseId <id2> ...] [--outputDir <path>] [--pseudonymize]\n' +
+  'Scope: live-quiz responses, participants, invitations, point corrections only (no practice-quiz / microlearning / group-activity responses).\n' +
+  '--pseudonymize replaces direct identifiers (email, sso id, matriculation) with per-run HMAC hashes and redacts free-text answers.'
+
+export class CliUsageError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'CliUsageError'
+  }
+}
+
+function readOptionValue(
+  args: string[],
+  index: number,
+  option: string
+): string {
+  const value = args[index + 1]
+  if (value == null || value.startsWith('--') || value.trim() === '') {
+    throw new CliUsageError(`Missing value for ${option}`)
+  }
+  return value
+}
+
+export function parseExportCourseArgs(args: string[]): {
+  courseIds: string[]
+  outputDir: string
+  pseudonymize: boolean
+} {
+  const courseIds: string[] = []
+  let outputDir = './export-output'
+  let outputDirSet = false
+  let pseudonymize = false
+
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i]!
+
+    if (arg === '--') {
+      continue
+    }
+
+    if (arg === '--pseudonymize') {
+      pseudonymize = true
+      continue
+    }
+
+    if (arg === '--courseId') {
+      courseIds.push(readOptionValue(args, i, arg))
+      i++
+      continue
+    }
+
+    if (arg === '--outputDir') {
+      if (outputDirSet) {
+        throw new CliUsageError('Duplicate --outputDir')
+      }
+      outputDir = readOptionValue(args, i, arg)
+      outputDirSet = true
+      i++
+      continue
+    }
+
+    if (arg === '--help' || arg === '-h') {
+      throw new CliUsageError(EXPORT_COURSE_USAGE)
+    }
+
+    throw new CliUsageError(`Unknown argument: ${arg}`)
+  }
+
+  if (courseIds.length === 0) {
+    throw new CliUsageError('At least one --courseId is required')
+  }
+
+  return { courseIds, outputDir, pseudonymize }
+}