Add HTTP routes, app wiring, V1 migration, backups, templates and API tests

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
Elijah 2026-11-11 08:22:47 -07:00
parent 3e74ecd843
commit eae109c166
11 changed files with 2085 additions and 1 deletions

157
server/app.ts Normal file
View file

@ -0,0 +1,157 @@
import fs from 'node:fs';
import path from 'node:path';
import { Hono } from 'hono';
import { compress } from 'hono/compress';
import { z } from 'zod';
import { AIError } from './ai/types.ts';
import { authRoutes, csrfGuard, requireAuth } from './auth.ts';
import { HttpError, zodIssues, type AppContext } from './http.ts';
import { aiRoutes } from './routes/ai.ts';
import { APP_VERSION, dataRoutes } from './routes/data.ts';
import { documentRoutes, mediaRoute } from './routes/documents.ts';
import { libraryRoutes } from './routes/library.ts';
import { publicRoutes, shareRoutes } from './routes/shares.ts';
import { studyRoutes } from './routes/study.ts';
const MIME: Record<string, string> = {
'.html': 'text/html; charset=utf-8',
'.js': 'text/javascript; charset=utf-8',
'.mjs': 'text/javascript; charset=utf-8',
'.css': 'text/css; charset=utf-8',
'.json': 'application/json; charset=utf-8',
'.webmanifest': 'application/manifest+json; charset=utf-8',
'.svg': 'image/svg+xml',
'.png': 'image/png',
'.jpg': 'image/jpeg',
'.ico': 'image/x-icon',
'.woff2': 'font/woff2',
'.woff': 'font/woff',
'.txt': 'text/plain; charset=utf-8',
'.map': 'application/json; charset=utf-8',
};
const CSP = [
"default-src 'self'",
"script-src 'self'",
"style-src 'self' 'unsafe-inline'",
"img-src 'self' data: blob:",
"font-src 'self' data:",
"connect-src 'self'",
"frame-src 'self' blob:",
"worker-src 'self' blob:",
"object-src 'none'",
"base-uri 'self'",
"form-action 'self'",
"frame-ancestors 'self'",
].join('; ');
const AI_STATUS: Partial<Record<AIError['code'], number>> = { not_configured: 409, bad_request: 400, unsupported: 400, context_length: 413, rate_limit: 429, quota: 402, aborted: 499 };
export function createApp(app: AppContext): Hono {
const hono = new Hono();
hono.onError((err, c) => {
if (err instanceof HttpError) {
if (err.status === 429 && typeof (err.details as { retryAfter?: number } | undefined)?.retryAfter === 'number') {
c.header('Retry-After', String((err.details as { retryAfter: number }).retryAfter));
}
return c.json({ error: { code: err.code, message: err.message, details: err.details } }, err.status as never);
}
if (err instanceof z.ZodError) {
const issues = zodIssues(err);
const first = issues[0];
return c.json({ error: { code: 'validation', message: first ? `${first.path ? `${first.path}: ` : ''}${first.message}` : 'Invalid input', details: issues } }, 422);
}
if (err instanceof AIError) {
return c.json({ error: { code: `ai_${err.code}`, message: err.message, details: err.providerMessage } }, (AI_STATUS[err.code] ?? 502) as never);
}
// Hono's own HTTP exceptions (body limit etc.)
const maybe = err as { status?: number; message?: string; getResponse?: () => Response };
if (typeof maybe.status === 'number' && maybe.status >= 400 && maybe.status < 500) {
return c.json({ error: { code: 'bad_request', message: maybe.message || 'Bad request' } }, maybe.status as never);
}
app.log('error', `Unhandled error on ${c.req.method} ${new URL(c.req.url).pathname}`, err);
return c.json({ error: { code: 'internal', message: 'Something went wrong on the server.' } }, 500);
});
// Security headers on everything.
hono.use('*', async (c, next) => {
await next();
const h = c.res.headers;
if (!h.has('X-Content-Type-Options')) h.set('X-Content-Type-Options', 'nosniff');
if (!h.has('Referrer-Policy')) h.set('Referrer-Policy', 'same-origin');
h.set('X-Frame-Options', 'SAMEORIGIN');
h.set('Permissions-Policy', 'camera=(), microphone=(), geolocation=(), payment=()');
if ((h.get('Content-Type') ?? '').startsWith('text/html') && !h.has('Content-Security-Policy')) h.set('Content-Security-Policy', CSP);
});
// gzip for API JSON and static text; event streams must not be buffered.
const gzip = compress();
hono.use('*', async (c, next) => {
const p = c.req.path;
if (p === '/api/ai/chat' || p === '/api/ai/explain' || p.startsWith('/api/backup') || p.endsWith('/file') || p.startsWith('/media/')) return next();
return gzip(c, next);
});
hono.get('/api/health', (c) => {
try {
app.db.get('SELECT 1 AS ok');
return c.json({ ok: true, version: APP_VERSION });
} catch {
return c.json({ ok: false }, 503);
}
});
const api = new Hono();
api.use('*', async (c, next) => {
c.header('Cache-Control', 'no-store');
await next();
});
api.use('*', csrfGuard());
api.route('/auth', authRoutes(app));
api.route('/public', publicRoutes(app));
const secured = new Hono();
secured.use('*', requireAuth(app));
secured.route('/', libraryRoutes(app));
secured.route('/', studyRoutes(app));
secured.route('/', shareRoutes(app));
secured.route('/', documentRoutes(app));
secured.route('/', aiRoutes(app));
secured.route('/', dataRoutes(app));
api.route('/', secured);
api.all('*', (c) => c.json({ error: { code: 'not_found', message: 'Unknown API route' } }, 404));
hono.route('/api', api);
hono.route('/media', mediaRoute(app));
/* ------------------------------ web app ------------------------------ */
const webDir = app.config.webDir;
const sendFile = (file: string, cache: string): Response => {
const ext = path.extname(file).toLowerCase();
return new Response(fs.readFileSync(file), { headers: { 'Content-Type': MIME[ext] ?? 'application/octet-stream', 'Cache-Control': cache } });
};
hono.get('*', (c) => {
if (!webDir) {
return c.text('The web app has not been built. Run "npm run build", or use "npm run dev" and open the Vite dev server.', 404);
}
const urlPath = decodeURIComponent(new URL(c.req.url).pathname);
const candidate = path.normalize(path.join(webDir, urlPath));
if (candidate.startsWith(webDir) && urlPath !== '/' && fs.existsSync(candidate) && fs.statSync(candidate).isFile()) {
// Hashed build assets never change; everything else is revalidated.
const immutable = urlPath.startsWith('/assets/');
return sendFile(candidate, immutable ? 'public, max-age=31536000, immutable' : 'no-cache');
}
if (path.extname(urlPath) && !urlPath.startsWith('/s/')) return c.text('Not found', 404);
const res = sendFile(path.join(webDir, 'index.html'), 'no-cache');
if (urlPath.startsWith('/s/')) {
res.headers.set('X-Robots-Tag', 'noindex, nofollow');
res.headers.set('Referrer-Policy', 'no-referrer');
}
return res;
});
return hono;
}

71
server/main.ts Normal file
View file

@ -0,0 +1,71 @@
import { serve } from '@hono/node-server';
import { tidyDrafts } from './ai/generate.ts';
import { createApp } from './app.ts';
import { initAuth } from './auth.ts';
import { loadConfig } from './config.ts';
import { openDatabase } from './db.ts';
import type { AppContext } from './http.ts';
import { APP_VERSION } from './routes/data.ts';
import { startBackupSchedule } from './services/backup.ts';
import { resumeQueue } from './services/documents.ts';
import { seedTemplates } from './services/templates.ts';
function log(level: 'info' | 'warn' | 'error', message: string, extra?: unknown): void {
const line = `${new Date().toISOString()} ${level.toUpperCase().padEnd(5)} ${message}`;
const detail = extra instanceof Error ? (extra.stack ?? extra.message) : extra !== undefined ? JSON.stringify(extra) : '';
(level === 'error' ? console.error : console.log)(detail ? `${line}\n${detail}` : line);
}
async function main(): Promise<void> {
const config = loadConfig();
log('info', `Study Desk ${APP_VERSION} starting (data: ${config.dataDir})`);
const { db, report } = openDatabase(config.dbPath, config.backupsDir);
if (report.applied.length > 0) log('info', `Database migrated: ${report.applied.join(', ')}${report.backup ? ` (backup: ${report.backup})` : ''}`);
const app: AppContext = { db, config, log };
await initAuth(app);
seedTemplates(db);
tidyDrafts(db);
const resumed = resumeQueue(app);
if (resumed > 0) log('info', `Resuming processing of ${resumed} document(s)`);
const stopBackups = startBackupSchedule(app);
const server = serve({ fetch: createApp(app).fetch, port: config.port, hostname: config.host }, (info) => {
log('info', `Listening on http://${info.address === '::' || info.address === '0.0.0.0' ? 'localhost' : info.address}:${info.port}`);
if (!config.webDir) log('warn', 'No built web app found (dist/web). API only: use the Vite dev server for the UI.');
});
let closing = false;
const shutdown = (signal: string) => {
if (closing) return;
closing = true;
log('info', `${signal} received, shutting down`);
stopBackups();
server.close(() => {
try {
db.close();
} catch {
/* already closed */
}
process.exit(0);
});
// Do not let an open event stream hold the process forever.
setTimeout(() => {
try {
db.close();
} catch {
/* ignore */
}
process.exit(0);
}, 5000).unref();
};
process.on('SIGTERM', () => shutdown('SIGTERM'));
process.on('SIGINT', () => shutdown('SIGINT'));
process.on('unhandledRejection', (reason) => log('error', 'Unhandled promise rejection', reason));
}
main().catch((err) => {
log('error', 'Failed to start', err);
process.exit(1);
});

271
server/routes/ai.ts Normal file
View file

@ -0,0 +1,271 @@
import { Hono, type Context } from 'hono';
import { streamSSE } from 'hono/streaming';
import { z } from 'zod';
import { assistantRequestSchema, displayMessages, listConversations, resolveAction, runAssistantTurn, type AssistantEvent } from '../ai/assistant.ts';
import {
cancelGeneration,
createDraft,
discardDraft,
draftSaveSchema,
generateRequestSchema,
getDraft,
improveRequestSchema,
listDrafts,
saveDraft,
startGeneration,
startImprove,
updateDraftPayload,
} from '../ai/generate.ts';
import { CATALOG_UPDATED, listAdapterMeta } from '../ai/providers/index.ts';
import {
addManualModel,
aiStatus,
deleteModel,
deleteProvider,
discoverModels,
getTaskSettings,
listModels,
listProviders,
manualModelSchema,
modelPatchSchema,
patchModel,
providerInputSchema,
runChat,
saveProvider,
saveTaskSettings,
TASK_INFO,
testProvider,
usageSummary,
} from '../ai/service.ts';
import { AIError } from '../ai/types.ts';
import { badRequest, idParam, notFound, readBody, type AppContext } from '../http.ts';
type Emit<T> = (event: T) => void;
/** Server-sent events with ordered writes, keep-alive pings and abort propagation. */
function sse<T extends { type: string }>(c: Context, run: (emit: Emit<T>, signal: AbortSignal) => Promise<void>) {
c.header('X-Accel-Buffering', 'no');
c.header('Cache-Control', 'no-cache, no-transform');
return streamSSE(c, async (stream) => {
const controller = new AbortController();
stream.onAbort(() => controller.abort());
let chain: Promise<unknown> = Promise.resolve();
const emit = (event: T | { type: 'ping' }) => {
chain = chain.then(() => stream.writeSSE({ data: JSON.stringify(event) })).catch(() => undefined);
};
const ping = setInterval(() => emit({ type: 'ping' }), 15_000);
try {
await run(emit, controller.signal);
} finally {
clearInterval(ping);
await chain;
}
});
}
const contentDraftSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('quiz'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
questions: z
.array(
z.object({
type: z.enum(['single', 'multi']),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean(), why: z.string().max(20000).optional() })).max(12),
rationale: z.string().max(20000).optional().default(''),
topic: z.string().max(80).optional().default(''),
difficulty: z.enum(['easy', 'medium', 'hard']).optional().default('medium'),
tags: z.array(z.string().max(40)).max(12).optional().default([]),
source: z.string().max(300).optional(),
}),
)
.max(1000),
}),
z.object({
kind: z.literal('deck'),
title: z.string().max(200),
description: z.string().max(4000).optional().default(''),
cards: z.array(z.object({ front: z.string().max(20000), back: z.string().max(20000), hint: z.string().max(20000).optional(), tags: z.array(z.string().max(40)).max(12).optional().default([]) })).max(5000),
}),
z.object({ kind: z.literal('note'), title: z.string().max(200), content: z.string().max(400000) }),
]);
const EXPLAIN_SYSTEM = `You are a patient nursing instructor helping a student while they study. Explain clearly and briefly (aim for under 200 words unless asked for more).
Use Markdown. Lead with the key idea, explain the reasoning, and connect it to patient care. If answer choices are given, say why the correct one is right and, in a line each, why the others are wrong. Do not restate the whole question.`;
export function aiRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
/* ------------------------------ configuration ------------------------------ */
r.get('/ai/meta', (c) => c.json({ adapters: listAdapterMeta(), tasks: TASK_INFO, catalogUpdated: CATALOG_UPDATED }));
r.get('/ai/status', (c) => c.json(aiStatus(app)));
r.get('/ai/providers', (c) => c.json({ providers: listProviders(app) }));
r.post('/ai/providers', async (c) => c.json({ provider: saveProvider(app, null, await readBody(c, providerInputSchema)) }, 201));
r.patch('/ai/providers/:id', async (c) => c.json({ provider: saveProvider(app, idParam(c), await readBody(c, providerInputSchema)) }));
r.delete('/ai/providers/:id', (c) => {
deleteProvider(app, idParam(c));
return c.json({ ok: true });
});
r.post('/ai/providers/:id/test', async (c) => c.json({ result: await testProvider(app, idParam(c)) }));
r.post('/ai/providers/:id/discover', async (c) => {
const result = await discoverModels(app, idParam(c));
return c.json({ ...result, models: listModels(db) });
});
r.get('/ai/models', (c) => c.json({ models: listModels(db) }));
r.post('/ai/models', async (c) => c.json({ model: addManualModel(app, await readBody(c, manualModelSchema)) }, 201));
r.patch('/ai/models/:id', async (c) => c.json({ model: patchModel(db, idParam(c), await readBody(c, modelPatchSchema)) }));
r.delete('/ai/models/:id', (c) => {
deleteModel(db, idParam(c));
return c.json({ ok: true });
});
r.get('/ai/tasks', (c) => c.json({ tasks: getTaskSettings(db) }));
r.put('/ai/tasks', async (c) => c.json({ tasks: saveTaskSettings(db, await c.req.json().catch(() => ({}))) }));
r.get('/ai/usage', (c) => c.json(usageSummary(db, Math.min(Math.max(Number(c.req.query('days') ?? 30) || 30, 1), 365))));
/* ------------------------------ generation + drafts ------------------------------ */
r.post('/ai/generate', async (c) => {
const body = await readBody(c, generateRequestSchema);
const { draftId } = startGeneration(app, body);
return c.json({ draftId }, 202);
});
r.post('/ai/improve', async (c) => {
const body = await readBody(c, improveRequestSchema);
const { draftId } = startImprove(app, body);
return c.json({ draftId }, 202);
});
r.get('/drafts', (c) => c.json({ drafts: listDrafts(db) }));
/** A blank or pre-filled draft, used by the import preview so imports and AI output share one review screen. */
r.post('/drafts', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
const id = createDraft(db, { kind: body.payload.kind, classId: body.classId ?? null, folderId: body.folderId ?? null, title: body.payload.title, payload: body.payload as never, meta: { origin: 'import' } });
return c.json({ draft: getDraft(db, id) }, 201);
});
r.get('/drafts/:id', (c) => c.json({ draft: getDraft(db, idParam(c)) }));
r.put('/drafts/:id', async (c) => {
const body = await readBody(c, z.object({ payload: contentDraftSchema, classId: z.string().nullish(), folderId: z.string().nullish() }));
return c.json({ draft: updateDraftPayload(db, idParam(c), body.payload as never, { classId: body.classId, folderId: body.folderId }) });
});
r.post('/drafts/:id/save', async (c) => {
const body = await readBody(c, draftSaveSchema);
return c.json({ saved: saveDraft(app, idParam(c), body) });
});
r.post('/drafts/:id/cancel', (c) => {
cancelGeneration(idParam(c));
return c.json({ ok: true });
});
r.delete('/drafts/:id', (c) => {
discardDraft(db, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ assistant ------------------------------ */
r.post('/ai/chat', async (c) => {
const body = await readBody(c, assistantRequestSchema);
return sse<AssistantEvent>(c, async (emit, signal) => {
try {
await runAssistantTurn(app, body, emit, signal);
} catch (err) {
// Failures before the turn starts (no model configured, bad input) still reach the client as an event.
const ai = err instanceof AIError ? err : null;
if (!ai) app.log('error', 'Assistant request failed', err);
emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The assistant could not start.', detail: ai?.providerMessage });
emit({ type: 'done', conversationId: body.conversationId ?? '', title: '' });
}
});
});
r.get('/ai/conversations', (c) => c.json({ conversations: listConversations(db) }));
r.get('/ai/conversations/:id', (c) => {
const id = idParam(c);
const row = db.get<{ id: string; title: string; class_id: string | null }>('SELECT id, title, class_id FROM conversations WHERE id = ?', id);
if (!row) throw notFound('Conversation');
return c.json({ conversation: { id: row.id, title: row.title, classId: row.class_id }, messages: displayMessages(db, id) });
});
r.delete('/ai/conversations/:id', (c) => {
const { changes } = db.run('DELETE FROM conversations WHERE id = ?', idParam(c));
if (!changes) throw notFound('Conversation');
return c.json({ ok: true });
});
r.post('/ai/actions/:id', async (c) => {
const body = await readBody(c, z.object({ confirm: z.boolean() }));
return c.json(resolveAction(app, idParam(c), body.confirm));
});
/* ------------------------------ inline explanations ------------------------------ */
const explainSchema = z.discriminatedUnion('kind', [
z.object({
kind: z.literal('question'),
stem: z.string().max(20000),
options: z.array(z.object({ text: z.string().max(4000), correct: z.boolean() })).max(12),
selected: z.array(z.string().max(4000)).max(12).optional(),
rationale: z.string().max(20000).optional(),
ask: z.string().max(2000).optional(),
}),
z.object({ kind: z.literal('card'), front: z.string().max(20000), back: z.string().max(20000), ask: z.string().max(2000).optional() }),
z.object({ kind: z.literal('text'), text: z.string().max(40000), ask: z.string().max(2000).optional() }),
]);
r.post('/ai/explain', async (c) => {
const body = await readBody(c, explainSchema);
let prompt: string;
if (body.kind === 'question') {
prompt = [
`Question:\n${body.stem}`,
`Choices:\n${body.options.map((o) => `- ${o.text}${o.correct ? ' (correct)' : ''}`).join('\n')}`,
body.selected?.length ? `The student chose: ${body.selected.join('; ')}` : '',
body.rationale ? `Existing rationale:\n${body.rationale}` : '',
body.ask ? `The student asks: ${body.ask}` : 'Explain this question so it finally makes sense. If the student chose wrongly, address the misunderstanding behind their choice.',
]
.filter(Boolean)
.join('\n\n');
} else if (body.kind === 'card') {
prompt = `Flashcard front:\n${body.front}\n\nFlashcard back:\n${body.back}\n\n${body.ask ? `The student asks: ${body.ask}` : 'Explain this card in more depth and give one way to remember it.'}`;
} else {
prompt = `${body.text}\n\n${body.ask ? `The student asks: ${body.ask}` : 'Explain this passage in simpler terms and point out what is most important to remember.'}`;
}
if (!prompt.trim()) throw badRequest('Nothing to explain');
return sse<{ type: 'text'; delta: string } | { type: 'error'; message: string; code: string } | { type: 'done' }>(c, async (emit, signal) => {
try {
await runChat(app, {
task: 'quick',
purpose: 'explanation',
system: EXPLAIN_SYSTEM,
messages: [{ role: 'user', content: [{ type: 'text', text: prompt }] }],
maxOutputTokens: 1500,
signal,
onEvent: (e) => {
if (e.type === 'text') emit({ type: 'text', delta: e.delta });
},
});
} catch (err) {
const ai = err instanceof AIError ? err : null;
if (ai?.code !== 'aborted') emit({ type: 'error', code: ai?.code ?? 'server', message: ai?.message ?? 'The explanation could not be generated.' });
}
emit({ type: 'done' });
});
});
return r;
}

249
server/routes/data.ts Normal file
View file

@ -0,0 +1,249 @@
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { Hono } from 'hono';
import { bodyLimit } from 'hono/body-limit';
import { z } from 'zod';
import { questionToDraft, validateDraft, type ContentDraft } from '../../shared/content.ts';
import { draftsFromValue } from '../../shared/importer.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { appSettingsSchema, getAppSettings, setSetting } from '../settings.ts';
import { createSnapshot, exportBundle, fullBackupStream, listBackups } from '../services/backup.ts';
import { createClass, createDeck, createFolder, createNote, createQuiz, draftCardToInput, draftQuestionToInput, getClass, getDeck, getQuiz, listCards, listQuestions } from '../services/content.ts';
import { createTemplate, deleteTemplate, listTemplates, templateInputSchema, updateTemplate } from '../services/templates.ts';
import { importV1 } from '../services/v1import.ts';
import { slugify } from '../util.ts';
export const APP_VERSION = '2.0.0';
function dirSize(dir: string): number {
try {
return fs.readdirSync(dir).reduce((n, f) => {
const st = fs.statSync(path.join(dir, f));
return n + (st.isFile() ? st.size : 0);
}, 0);
} catch {
return 0;
}
}
/** Creates library items from reviewed drafts. Used by the importer and by bundle restore. */
function createFromDraft(app: AppContext, draft: ContentDraft, classId: string, folderId: string | null): { kind: string; id: string; title: string } {
const { db } = app;
if (draft.kind === 'quiz') {
const quiz = createQuiz(db, { classId, folderId, title: draft.title.trim() || 'Imported quiz', description: draft.description ?? '', questions: draft.questions.map(draftQuestionToInput) });
return { kind: 'quiz', id: quiz.id, title: quiz.title };
}
if (draft.kind === 'deck') {
const deck = createDeck(db, { classId, folderId, title: draft.title.trim() || 'Imported deck', description: draft.description ?? '', cards: draft.cards.map(draftCardToInput) });
return { kind: 'deck', id: deck.id, title: deck.title };
}
const note = createNote(db, { classId, folderId, title: draft.title.trim() || 'Imported note', content: draft.content });
return { kind: 'note', id: note.id, title: note.title };
}
export function dataRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
/* ------------------------------ settings ------------------------------ */
r.get('/settings', (c) => {
const count = (table: string) => db.get<{ n: number }>(`SELECT COUNT(*) AS n FROM ${table}`)?.n ?? 0;
let dbSize = 0;
try {
dbSize = fs.statSync(app.config.dbPath).size;
} catch {
/* in-memory */
}
return c.json({
settings: getAppSettings(db, app.config.timezone),
system: {
version: APP_VERSION,
node: process.version,
dataDir: app.config.dataDir,
databaseBytes: dbSize,
uploadBytes: dirSize(app.config.uploadsDir) + dirSize(app.config.mediaDir),
maxUploadMb: Math.round(app.config.maxUploadBytes / 1048576),
counts: { classes: count('classes'), quizzes: count('quizzes'), questions: count('questions'), decks: count('decks'), cards: count('cards'), documents: count('documents'), notes: count('notes') },
timezones: typeof Intl.supportedValuesOf === 'function' ? Intl.supportedValuesOf('timeZone') : [],
},
});
});
r.put('/settings', async (c) => {
const patch = await readBody(c, appSettingsSchema.partial());
if (patch.timezone) {
try {
new Intl.DateTimeFormat('en-US', { timeZone: patch.timezone });
} catch {
throw badRequest('Unknown timezone');
}
}
const next = { ...getAppSettings(db, app.config.timezone), ...patch };
setSetting(db, 'app', next);
return c.json({ settings: next });
});
/* ------------------------------ import ------------------------------ */
r.post('/import', bodyLimit({ maxSize: 30 * 1024 * 1024 }), async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), items: z.array(z.unknown()).min(1).max(200) }));
getClass(db, body.classId);
const drafts: ContentDraft[] = [];
body.items.forEach((raw, i) => {
const parsed = draftsFromValue(raw).items[0];
if (!parsed) throw new HttpError(422, 'validation', `Item ${i + 1} is not a quiz, deck or note`);
const errors = validateDraft(parsed).filter((x) => x.level === 'error');
if (errors.length > 0) {
const first = errors[0];
const where = first.index !== undefined ? `${parsed.kind === 'quiz' ? 'question' : 'card'} ${first.index + 1}` : first.field ?? 'item';
throw new HttpError(422, 'validation', `"${parsed.title || `Item ${i + 1}`}", ${where}: ${first.message}`, { item: i, issues: errors });
}
drafts.push(parsed);
});
const created = db.tx(() => drafts.map((d) => createFromDraft(app, d, body.classId, body.folderId ?? null)));
return c.json({ created }, 201);
});
/** Restores a JSON bundle produced by "Export everything": recreates classes, folders and their contents. */
r.post('/import/bundle', bodyLimit({ maxSize: 100 * 1024 * 1024 }), async (c) => {
const body = (await c.req.json().catch(() => {
throw badRequest('The file is not valid JSON');
})) as Record<string, unknown>;
const classes = Array.isArray(body.classes) ? (body.classes as Record<string, unknown>[]) : null;
if (!classes) throw badRequest('This file is not a Study Desk bundle. Use "Import" inside a class for single quizzes and decks.');
const existing = new Set(db.all<{ name: string }>('SELECT name FROM classes').map((x) => x.name.toLowerCase()));
const summary = { classes: 0, quizzes: 0, decks: 0, notes: 0, skipped: [] as string[] };
db.tx(() => {
for (const raw of classes) {
let name = String(raw.name ?? 'Imported class').trim().slice(0, 110) || 'Imported class';
if (existing.has(name.toLowerCase())) name = `${name} (imported)`;
existing.add(name.toLowerCase());
const color = typeof raw.color === 'string' ? raw.color : undefined;
const cls = createClass(db, { name, code: String(raw.code ?? '').slice(0, 40), description: String(raw.description ?? '').slice(0, 2000), color: color as never });
summary.classes += 1;
const folders = new Map<string, string>();
for (const f of Array.isArray(raw.folders) ? raw.folders : []) {
const fname = String(typeof f === 'string' ? f : (f as Record<string, unknown>)?.name ?? '').trim();
if (fname) folders.set(fname, createFolder(db, cls.id, fname).id);
}
for (const key of ['quizzes', 'decks', 'notes'] as const) {
for (const item of Array.isArray(raw[key]) ? (raw[key] as Record<string, unknown>[]) : []) {
const kind = key === 'quizzes' ? 'quiz' : key === 'decks' ? 'deck' : 'note';
const draft = draftsFromValue({ ...item, kind }).items[0];
const title = String(item?.title ?? 'Untitled');
if (!draft) {
summary.skipped.push(`${title} (unreadable)`);
continue;
}
// Drop invalid entries rather than failing a whole restore; report what was left out.
if (draft.kind === 'quiz') {
const before = draft.questions.length;
draft.questions = draft.questions.filter((q) => !validateDraft({ ...draft, questions: [q] }).some((x) => x.level === 'error' && x.index !== undefined));
if (draft.questions.length < before) summary.skipped.push(`${before - draft.questions.length} invalid question(s) in "${title}"`);
} else if (draft.kind === 'deck') {
const before = draft.cards.length;
draft.cards = draft.cards.filter((card) => card.front?.trim() && card.back?.trim());
if (draft.cards.length < before) summary.skipped.push(`${before - draft.cards.length} empty card(s) in "${title}"`);
}
const folderId = typeof item.folder === 'string' ? (folders.get(item.folder) ?? null) : null;
createFromDraft(app, draft, cls.id, folderId);
summary[key] += 1;
}
}
}
});
return c.json({ summary }, 201);
});
/** Migration from a V1 database file. `?preview=1` only reports what would be imported. */
r.post('/import/v1', bodyLimit({ maxSize: 500 * 1024 * 1024 }), async (c) => {
const form = await c.req.parseBody().catch(() => {
throw badRequest('Upload could not be read');
});
const file = form.file;
if (!file || typeof file === 'string') throw badRequest('Choose your V1 study.db file');
const bytes = new Uint8Array(await file.arrayBuffer());
if (new TextDecoder().decode(bytes.subarray(0, 15)) !== 'SQLite format 3') throw badRequest('That file is not a SQLite database.');
const tmp = path.join(os.tmpdir(), `studydesk-v1-${Date.now()}-${Math.random().toString(36).slice(2)}.db`);
fs.writeFileSync(tmp, bytes);
try {
const preview = c.req.query('preview') === '1';
if (!preview) createSnapshot(app, 'pre-v1-import');
return c.json({ preview, summary: importV1(app, tmp, { dryRun: preview }) });
} finally {
fs.rmSync(tmp, { force: true });
}
});
/* ------------------------------ export + backup ------------------------------ */
r.get('/export/all', (c) => {
c.header('Content-Disposition', `attachment; filename="studydesk-export-${new Date().toISOString().slice(0, 10)}.json"`);
return c.json(exportBundle(app));
});
r.get('/export/class/:id', (c) => {
const cls = getClass(db, idParam(c));
c.header('Content-Disposition', `attachment; filename="${slugify(cls.name)}.class.json"`);
return c.json(exportBundle(app, cls.id));
});
r.get('/backup/download', () => {
const { stream, filename } = fullBackupStream(app);
return new Response(stream, { headers: { 'Content-Type': 'application/zip', 'Content-Disposition': `attachment; filename="${filename}"`, 'Cache-Control': 'no-store' } });
});
r.get('/backups', (c) => c.json({ backups: listBackups(app), directory: app.config.backupsDir }));
r.post('/backups', (c) => c.json({ backup: createSnapshot(app) }, 201));
r.get('/backups/:name', (c) => {
const name = path.basename(c.req.param('name'));
const file = path.join(app.config.backupsDir, name);
if (!name.endsWith('.db') || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Backup not found');
return new Response(fs.readFileSync(file), { headers: { 'Content-Type': 'application/octet-stream', 'Content-Disposition': `attachment; filename="${name}"`, 'Cache-Control': 'no-store' } });
});
/* ------------------------------ templates ------------------------------ */
r.get('/templates', (c) => c.json({ templates: listTemplates(db, c.req.query('kind') || undefined) }));
r.post('/templates', async (c) => c.json({ template: createTemplate(db, await readBody(c, templateInputSchema)) }, 201));
/** Saves an existing quiz or deck as a reusable template. */
r.post('/templates/from', async (c) => {
const body = await readBody(c, z.object({ kind: z.enum(['quiz', 'deck']), id: z.string(), name: z.string().trim().min(1).max(120).optional() }));
if (body.kind === 'quiz') {
const quiz = getQuiz(db, body.id);
return c.json({ template: createTemplate(db, { kind: 'quiz', name: body.name ?? quiz.title, description: quiz.description.slice(0, 1000), payload: { title: quiz.title, description: quiz.description, questions: listQuestions(db, quiz.id).map(questionToDraft) } }) }, 201);
}
const deck = getDeck(db, body.id);
return c.json(
{ template: createTemplate(db, { kind: 'deck', name: body.name ?? deck.title, description: deck.description.slice(0, 1000), payload: { title: deck.title, description: deck.description, cards: listCards(db, deck.id).map((x) => ({ front: x.front, back: x.back, hint: x.hint, tags: x.tags })) } }) },
201,
);
});
/** Creates a new quiz or deck from a content template. */
r.post('/templates/:id/use', async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), title: z.string().trim().max(200).optional() }));
const tpl = listTemplates(db).find((t) => t.id === idParam(c));
if (!tpl || tpl.kind === 'generation') throw new HttpError(404, 'not_found', 'Template not found');
const draft = draftsFromValue({ ...tpl.payload, kind: tpl.kind, title: body.title || tpl.payload.title || tpl.name }).items[0];
if (!draft) throw badRequest('This template is empty');
return c.json({ created: createFromDraft(app, draft, body.classId, body.folderId ?? null) }, 201);
});
r.patch('/templates/:id', async (c) => {
const body = await readBody(c, z.object({ name: z.string().max(120).optional(), description: z.string().max(1000).optional(), payload: z.record(z.string(), z.unknown()).optional() }));
return c.json({ template: updateTemplate(db, idParam(c), body) });
});
r.delete('/templates/:id', (c) => {
deleteTemplate(db, idParam(c));
return c.json({ ok: true });
});
return r;
}

174
server/routes/documents.ts Normal file
View file

@ -0,0 +1,174 @@
import fs from 'node:fs';
import path from 'node:path';
import crypto from 'node:crypto';
import { Hono } from 'hono';
import { bodyLimit } from 'hono/body-limit';
import { z } from 'zod';
import { titleSchema } from '../../shared/content.ts';
import { badRequest, HttpError, idParam, readBody, type AppContext } from '../http.ts';
import { getClass, mapClass, resolveFolder } from '../services/content.ts';
import { deleteDocument, documentPath, enqueue, getDocument, ingestUpload, listChunks, mapDocument, sourceLabel } from '../services/documents.ts';
import { now } from '../util.ts';
import { shareFor } from './library.ts';
const IMAGE_TYPES: Record<string, { ext: string; test: (b: Uint8Array) => boolean }> = {
'image/png': { ext: 'png', test: (b) => b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47 },
'image/jpeg': { ext: 'jpg', test: (b) => b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff },
'image/gif': { ext: 'gif', test: (b) => b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 },
'image/webp': { ext: 'webp', test: (b) => b[0] === 0x52 && b[1] === 0x49 && b[8] === 0x57 && b[9] === 0x45 },
};
export function documentRoutes(app: AppContext): Hono {
const { db } = app;
const r = new Hono();
const uploadLimit = bodyLimit({
maxSize: app.config.maxUploadBytes + 1024 * 1024,
onError: () => {
throw new HttpError(413, 'too_large', `That file is larger than the ${Math.round(app.config.maxUploadBytes / 1048576)} MB upload limit.`);
},
});
r.post('/documents', uploadLimit, async (c) => {
const form = await c.req.parseBody({ all: true }).catch(() => {
throw badRequest('Upload could not be read');
});
const classId = typeof form.classId === 'string' ? form.classId : '';
const folderId = typeof form.folderId === 'string' && form.folderId ? form.folderId : null;
const raw = form.file ?? form.files;
const files = (Array.isArray(raw) ? raw : [raw]).filter((f): f is File => typeof f === 'object' && f !== null && 'arrayBuffer' in f);
if (!classId) throw badRequest('classId is required');
if (files.length === 0) throw badRequest('Choose a file to upload');
const created = [];
for (const file of files) {
const bytes = new Uint8Array(await file.arrayBuffer());
created.push(mapDocument(ingestUpload(app, { classId, folderId, filename: file.name || 'upload', mime: file.type || undefined, bytes })));
}
return c.json({ documents: created }, 201);
});
/** Pasted notes become a Markdown document, so they are searchable and usable by AI like any upload. */
r.post('/documents/text', async (c) => {
const body = await readBody(c, z.object({ classId: z.string(), folderId: z.string().nullish(), title: titleSchema, text: z.string().trim().min(1).max(2_000_000) }));
const doc = ingestUpload(app, {
classId: body.classId,
folderId: body.folderId,
filename: `${body.title.replace(/[^\w\- ]+/g, '').trim().slice(0, 80) || 'notes'}.md`,
mime: 'text/markdown',
bytes: new TextEncoder().encode(body.text),
title: body.title,
});
return c.json({ document: mapDocument(doc) }, 201);
});
r.get('/documents/:id', (c) => {
const doc = getDocument(db, idParam(c));
const outline = db
.all<{ seq: number; heading: string; page_start: number | null }>(`SELECT MIN(seq) AS seq, heading, MIN(page_start) AS page_start FROM chunks WHERE document_id = ? AND heading != '' GROUP BY heading ORDER BY seq LIMIT 200`, doc.id)
.map((o) => ({ seq: o.seq, heading: o.heading, page: o.page_start }));
return c.json({ document: mapDocument(doc), class: mapClass(getClass(db, doc.class_id)), outline, share: shareFor(app, 'document', doc.id) });
});
r.get('/documents/:id/chunks', (c) => {
const doc = getDocument(db, idParam(c));
const offset = Math.max(0, Number(c.req.query('offset') ?? 0) || 0);
const limit = Math.min(100, Math.max(1, Number(c.req.query('limit') ?? 40) || 40));
const chunks = listChunks(db, doc.id, offset, limit);
return c.json({
chunks: chunks.map((ch) => ({ id: ch.id, seq: ch.seq, text: ch.text, heading: ch.heading, pageStart: ch.pageStart, pageEnd: ch.pageEnd, label: sourceLabel(ch) })),
total: doc.chunk_count,
nextOffset: chunks.length === limit && offset + limit < doc.chunk_count ? offset + limit : null,
});
});
r.get('/documents/:id/status', (c) => {
const doc = getDocument(db, idParam(c));
return c.json({ document: mapDocument(doc) });
});
r.get('/documents/:id/file', (c) => {
const doc = getDocument(db, idParam(c));
const file = documentPath(app, doc);
if (!fs.existsSync(file)) throw new HttpError(404, 'not_found', 'The original file is missing from storage');
const inline = doc.kind === 'pdf' || doc.kind === 'image';
const download = c.req.query('download') === '1';
return new Response(fs.readFileSync(file), {
headers: {
'Content-Type': inline ? doc.mime : 'application/octet-stream',
'Content-Disposition': `${inline && !download ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(doc.filename)}`,
'X-Content-Type-Options': 'nosniff',
// Uploaded files are untrusted. PDFs and images are served with their verified type (sniffing off);
// everything else is forced to download.
...(inline ? {} : { 'Content-Security-Policy': "default-src 'none'; sandbox" }),
'Cache-Control': 'private, max-age=3600',
},
});
});
r.patch('/documents/:id', async (c) => {
const doc = getDocument(db, idParam(c));
const body = await readBody(c, z.object({ title: titleSchema.optional(), folderId: z.string().nullish() }));
db.run(
'UPDATE documents SET title = ?, folder_id = ?, updated_at = ? WHERE id = ?',
body.title ?? doc.title,
body.folderId === undefined ? doc.folder_id : resolveFolder(db, doc.class_id, body.folderId),
now(),
doc.id,
);
return c.json({ document: mapDocument(getDocument(db, doc.id)) });
});
r.post('/documents/:id/reprocess', async (c) => {
const doc = getDocument(db, idParam(c));
const body = (await c.req.json().catch(() => ({}))) as { ocr?: unknown };
db.run(`UPDATE documents SET status = 'pending', error = '', progress = 0, updated_at = ? WHERE id = ?`, now(), doc.id);
enqueue(app, doc.id, { ocr: body.ocr === true });
return c.json({ document: mapDocument(getDocument(db, doc.id)) });
});
r.delete('/documents/:id', (c) => {
deleteDocument(app, idParam(c));
return c.json({ ok: true });
});
/* ------------------------------ images embedded in questions, cards and notes ------------------------------ */
r.post('/media', bodyLimit({ maxSize: 12 * 1024 * 1024 }), async (c) => {
const form = await c.req.parseBody().catch(() => {
throw badRequest('Upload could not be read');
});
const file = form.file;
if (!file || typeof file === 'string') throw badRequest('Choose an image');
const bytes = new Uint8Array(await file.arrayBuffer());
if (bytes.length > 10 * 1024 * 1024) throw new HttpError(413, 'too_large', 'Images can be up to 10 MB.');
// Trust the bytes, not the declared type. SVG is deliberately not accepted (it can carry script).
const match = Object.entries(IMAGE_TYPES).find(([, t]) => t.test(bytes));
if (!match) throw new HttpError(415, 'unsupported_type', 'Use a PNG, JPEG, GIF or WebP image.');
const [mime, { ext }] = match;
const id = `${crypto.randomBytes(16).toString('base64url')}.${ext}`;
fs.writeFileSync(path.join(app.config.mediaDir, id), bytes);
db.run('INSERT INTO media (id, filename, mime, size, created_at) VALUES (?, ?, ?, ?, ?)', id, (file.name || 'image').slice(0, 200), mime, bytes.length, now());
return c.json({ url: `/media/${id}`, markdown: `![${(file.name || 'image').replace(/[[\]]/g, '')}](/media/${id})` }, 201);
});
return r;
}
/**
* Public image route. Images are addressed by an unguessable 128-bit name, which is what lets
* a shared quiz show its pictures to visitors without exposing anything else.
*/
export function mediaRoute(app: AppContext): Hono {
const r = new Hono();
r.get('/:name', (c) => {
const name = c.req.param('name');
if (!/^[A-Za-z0-9_-]{16,40}\.(png|jpg|gif|webp)$/.test(name)) throw new HttpError(404, 'not_found', 'Not found');
const row = app.db.get<{ mime: string }>('SELECT mime FROM media WHERE id = ?', name);
const file = path.join(app.config.mediaDir, name);
if (!row || !fs.existsSync(file)) throw new HttpError(404, 'not_found', 'Not found');
return new Response(fs.readFileSync(file), {
headers: { 'Content-Type': row.mime, 'Cache-Control': 'public, max-age=31536000, immutable', 'X-Content-Type-Options': 'nosniff', 'Content-Security-Policy': "default-src 'none'; sandbox" },
});
});
return r;
}

View file

@ -249,7 +249,7 @@ export function publicRoutes(app: AppContext): Hono {
'Content-Type': doc.mime || 'application/octet-stream',
'Content-Disposition': `${inline ? 'inline' : 'attachment'}; filename*=UTF-8''${encodeURIComponent(doc.filename)}`,
'X-Content-Type-Options': 'nosniff',
'Content-Security-Policy': "default-src 'none'; style-src 'unsafe-inline'; sandbox",
...(inline ? {} : { 'Content-Security-Policy': "default-src 'none'; sandbox" }),
'Cache-Control': 'private, no-store',
'X-Robots-Tag': 'noindex, nofollow',
},

183
server/services/backup.ts Normal file
View file

@ -0,0 +1,183 @@
/**
* Backups.
* - Automatic: a compact snapshot of the database is written to data/backups once a day
* and the newest few are kept.
* - On demand: a zip with the database snapshot plus every uploaded file and image.
* - Content export: a portable JSON bundle of classes, quizzes, decks and notes.
*/
import fs from 'node:fs';
import path from 'node:path';
import { Zip, ZipPassThrough } from 'fflate';
import { questionToDraft } from '../../shared/content.ts';
import { EXPORT_FORMAT, EXPORT_VERSION, exportDeck, exportQuiz } from '../../shared/importer.ts';
import type { AppContext } from '../http.ts';
import { dayKey, now } from '../util.ts';
import { listCards, listQuestions, type ClassRow, type FolderRow, type NoteRow, type QuizRow } from './content.ts';
export interface BackupInfo {
name: string;
size: number;
createdAt: number;
}
export function listBackups(app: AppContext): BackupInfo[] {
const dir = app.config.backupsDir;
if (!fs.existsSync(dir)) return [];
return fs
.readdirSync(dir)
.filter((f) => f.endsWith('.db'))
.map((name) => {
const st = fs.statSync(path.join(dir, name));
return { name, size: st.size, createdAt: st.mtimeMs };
})
.sort((a, b) => b.createdAt - a.createdAt);
}
export function createSnapshot(app: AppContext, prefix = 'manual'): BackupInfo {
const stamp = new Date().toISOString().replace(/[:.]/g, '-').replace('T', '_').slice(0, 19);
const name = `${prefix}-${stamp}.db`;
const target = path.join(app.config.backupsDir, name);
app.db.snapshot(target);
return { name, size: fs.statSync(target).size, createdAt: now() };
}
/** Writes today's automatic snapshot if it does not exist yet, then prunes old automatic ones. */
export function runDailyBackup(app: AppContext): BackupInfo | null {
const today = dayKey(now(), 'UTC');
const name = `auto-${today}.db`;
const target = path.join(app.config.backupsDir, name);
let created: BackupInfo | null = null;
if (!fs.existsSync(target)) {
// Skip an empty install: there is nothing worth keeping yet.
const hasData = (app.db.get<{ n: number }>('SELECT (SELECT COUNT(*) FROM classes) + (SELECT COUNT(*) FROM ai_providers) AS n')?.n ?? 0) > 0;
if (hasData) {
app.db.snapshot(target);
created = { name, size: fs.statSync(target).size, createdAt: now() };
}
}
const prune = (prefix: string, keep: number) => {
const files = listBackups(app).filter((b) => b.name.startsWith(prefix));
for (const old of files.slice(keep)) fs.rmSync(path.join(app.config.backupsDir, old.name), { force: true });
};
prune('auto-', app.config.backupKeep);
prune('pre-migration-', 5);
prune('manual-', 10);
return created;
}
export function startBackupSchedule(app: AppContext): () => void {
const tick = () => {
try {
const made = runDailyBackup(app);
if (made) app.log('info', `Automatic backup written: ${made.name}`);
} catch (e) {
app.log('error', 'Automatic backup failed', e);
}
};
const first = setTimeout(tick, 30_000);
const timer = setInterval(tick, 6 * 3_600_000);
first.unref?.();
timer.unref?.();
return () => {
clearTimeout(first);
clearInterval(timer);
};
}
/** Streams a zip containing a fresh database snapshot and all uploaded files. One file is in memory at a time. */
export function fullBackupStream(app: AppContext): { stream: ReadableStream<Uint8Array>; filename: string } {
const tmp = path.join(app.config.backupsDir, `.export-${Date.now()}.db`);
app.db.snapshot(tmp);
const entries: { name: string; file: string }[] = [{ name: 'study.db', file: tmp }];
for (const [dir, prefix] of [
[app.config.uploadsDir, 'uploads'],
[app.config.mediaDir, 'media'],
] as const) {
if (!fs.existsSync(dir)) continue;
for (const f of fs.readdirSync(dir)) {
const full = path.join(dir, f);
if (fs.statSync(full).isFile()) entries.push({ name: `${prefix}/${f}`, file: full });
}
}
const manifest = {
format: 'studydesk-backup',
version: 1,
createdAt: new Date().toISOString(),
files: entries.length,
restore: 'Stop the container, copy study.db, uploads/ and media/ into the data folder (replacing what is there), keep your existing secret.key, then start the container.',
};
let index = -1;
let controllerRef: ReadableStreamDefaultController<Uint8Array> | null = null;
const cleanup = () => fs.rmSync(tmp, { force: true });
const zip = new Zip((err, chunk, final) => {
if (err) {
controllerRef?.error(err);
cleanup();
return;
}
controllerRef?.enqueue(chunk);
if (final) {
controllerRef?.close();
cleanup();
}
});
const stream = new ReadableStream<Uint8Array>({
start(controller) {
controllerRef = controller;
const entry = new ZipPassThrough('manifest.json');
zip.add(entry);
entry.push(new TextEncoder().encode(JSON.stringify(manifest, null, 2)), true);
},
pull() {
index += 1;
if (index >= entries.length) {
zip.end();
return;
}
const { name, file } = entries[index];
const entry = new ZipPassThrough(name);
zip.add(entry);
try {
entry.push(new Uint8Array(fs.readFileSync(file)), true);
} catch {
entry.push(new Uint8Array(0), true);
}
},
cancel() {
cleanup();
},
});
return { stream, filename: `studydesk-backup-${new Date().toISOString().slice(0, 10)}.zip` };
}
/** Portable JSON bundle: classes with their folders, quizzes, decks and notes (no progress, no uploads). */
export function exportBundle(app: AppContext, classId?: string) {
const { db } = app;
const classes = classId ? db.all<ClassRow>('SELECT * FROM classes WHERE id = ?', classId) : db.all<ClassRow>('SELECT * FROM classes ORDER BY sort_order, created_at');
return {
format: EXPORT_FORMAT,
version: EXPORT_VERSION,
kind: 'bundle' as const,
exportedAt: new Date().toISOString(),
classes: classes.map((cls) => {
const folders = db.all<FolderRow>('SELECT * FROM folders WHERE class_id = ? ORDER BY sort_order', cls.id);
const folderName = (id: string | null) => folders.find((f) => f.id === id)?.name ?? null;
return {
name: cls.name,
code: cls.code,
description: cls.description,
color: cls.color,
folders: folders.map((f) => f.name),
quizzes: db.all<QuizRow>('SELECT * FROM quizzes WHERE class_id = ? ORDER BY sort_order, created_at', cls.id).map((q) => ({
...exportQuiz({ title: q.title, description: q.description, questions: listQuestions(db, q.id).map(questionToDraft) }),
folder: folderName(q.folder_id),
})),
decks: db.all<QuizRow>('SELECT * FROM decks WHERE class_id = ? ORDER BY sort_order, created_at', cls.id).map((d) => ({
...exportDeck({ title: d.title, description: d.description, cards: listCards(db, d.id).map((c) => ({ front: c.front, back: c.back, hint: c.hint, tags: c.tags })) }),
folder: folderName(d.folder_id),
})),
notes: db.all<NoteRow>('SELECT * FROM notes WHERE class_id = ? ORDER BY sort_order, created_at', cls.id).map((n) => ({ kind: 'note' as const, title: n.title, content: n.content, folder: folderName(n.folder_id) })),
};
}),
};
}

View file

@ -0,0 +1,229 @@
/**
* Reusable templates.
* - quiz / deck: a content skeleton (or a full copy of an existing item) to start from.
* - generation: a saved set of AI generation options.
* Built-in templates are (re)seeded at startup and cannot be edited, only copied.
*/
import { z } from 'zod';
import type { DB } from '../db.ts';
import { notFound } from '../http.ts';
import { newId, now, parseJson } from '../util.ts';
export const templateInputSchema = z.object({
kind: z.enum(['quiz', 'deck', 'generation']),
name: z.string().trim().min(1).max(120),
description: z.string().max(1000).optional().default(''),
payload: z.record(z.string(), z.unknown()),
});
interface TemplateRow {
id: string;
kind: 'quiz' | 'deck' | 'generation';
name: string;
description: string;
payload: string;
builtin: number;
created_at: number;
updated_at: number;
}
const mapTemplate = (r: TemplateRow) => ({
id: r.id,
kind: r.kind,
name: r.name,
description: r.description,
payload: parseJson<Record<string, unknown>>(r.payload, {}),
builtin: Boolean(r.builtin),
updatedAt: r.updated_at,
});
const BUILTIN: { id: string; kind: TemplateRow['kind']; name: string; description: string; payload: Record<string, unknown> }[] = [
{
id: 'builtin-gen-nclex',
kind: 'generation',
name: 'NCLEX practice set',
description: '25 clinical-judgment questions, about a third select-all, mixed difficulty.',
payload: { kind: 'quiz', count: 25, style: 'nclex', difficulty: 'mixed', sataShare: 0.3 },
},
{
id: 'builtin-gen-priority',
kind: 'generation',
name: 'Prioritization and delegation',
description: '15 hard questions on who to see first, what to do first, and what can be delegated.',
payload: {
kind: 'quiz',
count: 15,
style: 'nclex',
difficulty: 'hard',
sataShare: 0.2,
instructions: 'Every question must test prioritisation, delegation or assignment: which client to see first, which action comes first, or which task can be delegated to an LPN/LVN or assistive personnel.',
},
},
{
id: 'builtin-gen-recall',
kind: 'generation',
name: 'Quick recall check',
description: '20 short multiple-choice questions on key facts, values and definitions.',
payload: { kind: 'quiz', count: 20, style: 'recall', difficulty: 'easy', sataShare: 0 },
},
{
id: 'builtin-gen-drugs',
kind: 'generation',
name: 'Medication cards',
description: 'One card per drug: class, action, uses, adverse effects, nursing considerations, teaching.',
payload: { kind: 'deck', count: 30, cardStyle: 'medication' },
},
{
id: 'builtin-gen-terms',
kind: 'generation',
name: 'Key terms',
description: '40 term-and-definition cards.',
payload: { kind: 'deck', count: 40, cardStyle: 'definition' },
},
{
id: 'builtin-gen-guide',
kind: 'generation',
name: 'Chapter study guide',
description: 'Overview, key concepts by section, pitfalls and self-check questions.',
payload: { kind: 'note', noteStyle: 'study_guide' },
},
{
id: 'builtin-gen-cheat',
kind: 'generation',
name: 'Exam cheat sheet',
description: 'A dense one-page review with tables for values, drugs and comparisons.',
payload: { kind: 'note', noteStyle: 'cheat_sheet' },
},
{
id: 'builtin-deck-drug',
kind: 'deck',
name: 'Medication card layout',
description: 'A blank drug card with the standard headings, ready to fill in and duplicate.',
payload: {
title: 'Medications',
description: '',
cards: [
{
front: 'Drug name (Brand)',
back: '**Class:** \n\n**Action:** \n\n**Uses:** \n\n**Adverse effects:** \n\n**Nursing considerations:** \n\n**Client teaching:** ',
hint: '',
tags: ['pharm'],
},
],
},
},
{
id: 'builtin-deck-disease',
kind: 'deck',
name: 'Disease process layout',
description: 'One card per condition: pathophysiology, findings, diagnostics, interventions, complications.',
payload: {
title: 'Disorders',
description: '',
cards: [
{
front: 'Condition',
back: '**Pathophysiology:** \n\n**Signs and symptoms:** \n\n**Diagnostics / labs:** \n\n**Nursing interventions:** \n\n**Medications:** \n\n**Complications:** \n\n**Client teaching:** ',
hint: '',
tags: [],
},
],
},
},
{
id: 'builtin-quiz-nclex',
kind: 'quiz',
name: 'NCLEX item layout',
description: 'One multiple-choice and one select-all question with the recommended structure.',
payload: {
title: 'Practice questions',
description: '',
questions: [
{
type: 'single',
stem: 'A client with [condition] reports [finding]. Which action should the nurse take first?',
options: [
{ text: 'Correct priority action', correct: true, why: 'Why this comes first.' },
{ text: 'Plausible but lower priority action', correct: false, why: 'Why it can wait.' },
{ text: 'Appropriate action, wrong timing', correct: false, why: '' },
{ text: 'Common misconception', correct: false, why: '' },
],
rationale: 'State the principle (ABCs, safety, acute over chronic) and how it applies.',
topic: '',
difficulty: 'medium',
tags: [],
},
{
type: 'multi',
stem: 'Which findings should the nurse expect in a client with [condition]? Select all that apply.',
options: [
{ text: 'Expected finding', correct: true, why: '' },
{ text: 'Expected finding', correct: true, why: '' },
{ text: 'Opposite of the expected finding', correct: false, why: '' },
{ text: 'Expected finding', correct: true, why: '' },
{ text: 'Finding from a similar condition', correct: false, why: '' },
],
rationale: '',
topic: '',
difficulty: 'medium',
tags: [],
},
],
},
},
];
export function seedTemplates(db: DB): void {
const at = now();
db.tx(() => {
const keep = BUILTIN.map((t) => t.id);
db.run(`DELETE FROM templates WHERE builtin = 1 AND id NOT IN (${keep.map(() => '?').join(',')})`, ...keep);
for (const t of BUILTIN) {
db.run(
`INSERT INTO templates (id, kind, name, description, payload, builtin, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 1, ?, ?)
ON CONFLICT(id) DO UPDATE SET kind = excluded.kind, name = excluded.name, description = excluded.description, payload = excluded.payload, updated_at = excluded.updated_at`,
t.id,
t.kind,
t.name,
t.description,
JSON.stringify(t.payload),
at,
at,
);
}
});
}
export function listTemplates(db: DB, kind?: string) {
const rows = kind
? db.all<TemplateRow>('SELECT * FROM templates WHERE kind = ? ORDER BY builtin, name', kind)
: db.all<TemplateRow>('SELECT * FROM templates ORDER BY kind, builtin, name');
return rows.map(mapTemplate);
}
export function createTemplate(db: DB, input: z.input<typeof templateInputSchema>) {
const data = templateInputSchema.parse(input);
const id = newId();
const at = now();
db.run('INSERT INTO templates (id, kind, name, description, payload, builtin, created_at, updated_at) VALUES (?, ?, ?, ?, ?, 0, ?, ?)', id, data.kind, data.name, data.description, JSON.stringify(data.payload), at, at);
return mapTemplate(db.get<TemplateRow>('SELECT * FROM templates WHERE id = ?', id)!);
}
export function updateTemplate(db: DB, id: string, input: { name?: string; description?: string; payload?: Record<string, unknown> }) {
const row = db.get<TemplateRow>('SELECT * FROM templates WHERE id = ? AND builtin = 0', id);
if (!row) throw notFound('Template');
db.run(
'UPDATE templates SET name = ?, description = ?, payload = ?, updated_at = ? WHERE id = ?',
input.name?.trim().slice(0, 120) || row.name,
input.description ?? row.description,
input.payload ? JSON.stringify(input.payload) : row.payload,
now(),
id,
);
return mapTemplate(db.get<TemplateRow>('SELECT * FROM templates WHERE id = ?', id)!);
}
export function deleteTemplate(db: DB, id: string): void {
const { changes } = db.run('DELETE FROM templates WHERE id = ? AND builtin = 0', id);
if (!changes) throw notFound('Template');
}

257
server/services/v1import.ts Normal file
View file

@ -0,0 +1,257 @@
/**
* One-way migration from a Study Desk V1 database (the Prisma/SQLite `study.db`).
* The V1 file is opened read-only and never modified. Everything is copied into new
* rows with new ids inside one transaction, so a failed import leaves V2 untouched.
*/
import { DatabaseSync } from 'node:sqlite';
import { isFullyCorrect, scoreQuestion, type Option } from '../../shared/content.ts';
import { badRequest, type AppContext } from '../http.ts';
import { newId, now } from '../util.ts';
import { createClass, createDeck, createFolder, createQuiz, listCards, listQuestions } from './content.ts';
export interface V1Summary {
classes: number;
folders: number;
decks: number;
cards: number;
quizzes: number;
questions: number;
attempts: number;
scheduledCards: number;
activityDays: number;
skipped: string[];
}
type Row = Record<string, any>;
function toMs(v: unknown): number | null {
if (v === null || v === undefined) return null;
if (typeof v === 'number') return v > 1e11 ? v : v * 1000;
if (typeof v === 'bigint') return Number(v);
const n = Number(v);
if (Number.isFinite(n) && String(v).trim() !== '') return n > 1e11 ? n : n * 1000;
const t = Date.parse(String(v));
return Number.isNaN(t) ? null : t;
}
export function importV1(app: AppContext, file: string, opts: { dryRun?: boolean } = {}): V1Summary {
let src: DatabaseSync;
try {
src = new DatabaseSync(file, { readOnly: true });
} catch {
throw badRequest('That file could not be opened as a SQLite database.');
}
try {
const tables = new Set((src.prepare(`SELECT name FROM sqlite_master WHERE type = 'table'`).all() as Row[]).map((r) => String(r.name)));
if (!tables.has('Class') || !tables.has('Deck') || !tables.has('QuizSet')) {
throw badRequest('This does not look like a Study Desk V1 database (expected the tables Class, Deck and QuizSet).');
}
const all = (table: string, order = ''): Row[] => (tables.has(table) ? (src.prepare(`SELECT * FROM "${table}" ${order}`).all() as Row[]) : []);
const classes = all('Class', 'ORDER BY sortOrder, createdAt');
const groups = all('MaterialGroup', 'ORDER BY sortOrder, createdAt');
const decks = all('Deck', 'ORDER BY sortOrder, createdAt');
const cards = all('Flashcard', 'ORDER BY sortOrder');
const quizzes = all('QuizSet', 'ORDER BY sortOrder, createdAt');
const questions = all('Question', 'ORDER BY sortOrder');
const options = all('AnswerOption', 'ORDER BY sortOrder');
const attempts = all('QuizAttempt', 'ORDER BY completedAt');
const srStates = all('SpacedRepetitionCardState');
const activity = all('StudyActivity');
const summary: V1Summary = {
classes: classes.length,
folders: groups.length,
decks: decks.length,
cards: cards.length,
quizzes: quizzes.length,
questions: questions.length,
attempts: attempts.length,
scheduledCards: new Set(srStates.map((s) => s.flashcardId)).size,
activityDays: new Set(activity.map((a) => new Date(toMs(a.occurredAt) ?? 0).toISOString().slice(0, 10))).size,
skipped: [],
};
if (opts.dryRun) return summary;
const { db } = app;
const group = <T extends Row>(rows: T[], key: string) => {
const m = new Map<string, T[]>();
for (const r of rows) {
const k = String(r[key]);
if (!m.has(k)) m.set(k, []);
m.get(k)!.push(r);
}
return m;
};
const cardsByDeck = group(cards, 'deckId');
const questionsByQuiz = group(questions, 'quizSetId');
const optionsByQuestion = group(options, 'questionId');
const attemptsByQuiz = group(attempts, 'quizSetId');
// Keep the most-practised schedule when a card belonged to several V1 spaced-repetition sets.
const bestState = new Map<string, Row>();
for (const s of srStates) {
const cur = bestState.get(s.flashcardId);
if (!cur || Number(s.reps) > Number(cur.reps)) bestState.set(s.flashcardId, s);
}
db.tx(() => {
const classMap = new Map<string, string>();
const folderMap = new Map<string, string>();
for (const c of classes) {
const created = createClass(db, { name: String(c.name || 'Untitled class').slice(0, 120) });
classMap.set(c.id, created.id);
const t = toMs(c.createdAt);
if (t) db.run('UPDATE classes SET created_at = ? WHERE id = ?', t, created.id);
}
for (const g of groups) {
const classId = classMap.get(g.classId);
if (!classId) continue;
folderMap.set(g.id, createFolder(db, classId, String(g.name || 'Folder')).id);
}
for (const d of decks) {
const classId = classMap.get(d.classId);
if (!classId) {
summary.skipped.push(`Deck "${d.name}" (its class is missing)`);
continue;
}
const source = (cardsByDeck.get(d.id) ?? []).filter((c) => String(c.front ?? '').trim() && String(c.back ?? '').trim());
const deck = createDeck(db, {
classId,
folderId: d.groupId ? folderMap.get(d.groupId) : null,
title: String(d.name || 'Untitled deck').slice(0, 200),
description: String(d.description ?? '').slice(0, 4000),
cards: source.map((c) => ({ front: String(c.front).slice(0, 20000), back: String(c.back).slice(0, 20000) })),
});
const created = listCards(db, deck.id);
source.forEach((old, i) => {
const s = bestState.get(old.id);
const target = created[i];
if (!s || !target) return;
db.run(
`UPDATE cards SET state = ?, due = ?, stability = ?, difficulty = ?, scheduled_days = ?, learning_steps = ?, reps = ?, lapses = ?, last_review = ?, introduced_at = ? WHERE id = ?`,
Number(s.state) || 0,
toMs(s.due),
Number(s.stability) || 0,
Number(s.difficulty) || 0,
Number(s.scheduledDays) || 0,
Number(s.learningSteps) || 0,
Number(s.reps) || 0,
Number(s.lapses) || 0,
toMs(s.lastReview),
toMs(s.firstReviewedAt),
target.id,
);
});
}
for (const z of quizzes) {
const classId = classMap.get(z.classId);
if (!classId) {
summary.skipped.push(`Quiz "${z.name}" (its class is missing)`);
continue;
}
const source = (questionsByQuiz.get(z.id) ?? []).filter((q) => {
const opts2 = optionsByQuestion.get(q.id) ?? [];
return String(q.prompt ?? '').trim() && opts2.length >= 2 && opts2.some((o) => o.isCorrect);
});
const quiz = createQuiz(db, {
classId,
folderId: z.groupId ? folderMap.get(z.groupId) : null,
title: String(z.name || 'Untitled quiz').slice(0, 200),
description: String(z.description ?? '').slice(0, 4000),
questions: source.map((q) => {
const opts2 = (optionsByQuestion.get(q.id) ?? []).filter((o) => String(o.text ?? '').trim()).slice(0, 10);
const correct = opts2.filter((o) => o.isCorrect).length;
return {
type: String(q.type).toUpperCase() === 'SATA' || correct > 1 ? 'multi' : 'single',
stem: String(q.prompt).slice(0, 20000),
options: opts2.map((o) => ({ text: String(o.text).slice(0, 4000), correct: Boolean(o.isCorrect) })),
rationale: String(q.rationale ?? '').slice(0, 20000),
topic: String(q.category ?? '').slice(0, 80),
};
}),
});
const created = listQuestions(db, quiz.id);
// Old question / option ids -> new, so past attempts can be replayed.
const qMap = new Map<string, (typeof created)[number]>();
const oMap = new Map<string, string>();
source.forEach((old, i) => {
const target = created[i];
if (!target) return;
qMap.set(old.id, target);
const oldOpts = (optionsByQuestion.get(old.id) ?? []).filter((o) => String(o.text ?? '').trim()).slice(0, 10);
oldOpts.forEach((o, j) => target.options[j] && oMap.set(o.id, target.options[j].id));
});
for (const a of attemptsByQuiz.get(z.id) ?? []) {
let answers: Record<string, unknown> = {};
try {
const parsed = JSON.parse(String(a.answersJson ?? '{}'));
if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) answers = parsed;
} catch {
/* an unreadable attempt is still imported as a score */
}
const partial = Boolean(a.isPartialRetake);
const included = created.filter((q) => {
const oldId = [...qMap.entries()].find(([, v]) => v.id === q.id)?.[0];
return !partial || (oldId !== undefined && oldId in answers);
});
const completedAt = toMs(a.completedAt) ?? now();
const newAnswers: Record<string, { selected: string[]; checked: boolean; at: number }> = {};
for (const [oldQ, sel] of Object.entries(answers)) {
const target = qMap.get(oldQ);
if (!target || !Array.isArray(sel)) continue;
newAnswers[target.id] = { selected: sel.map((s) => oMap.get(String(s))).filter((s): s is string => Boolean(s)), checked: true, at: completedAt };
}
const attemptId = newId();
const snapshot = included.map((q) => ({ id: q.id, quizId: quiz.id, quizTitle: quiz.title, type: q.type, stem: q.stem, options: q.options as Option[], rationale: q.rationale, topic: q.topic, difficulty: q.difficulty }));
db.run(
`INSERT INTO attempts (id, quiz_id, class_id, title, mode, kind, status, settings, snapshot, answers, question_count, score, max_score, started_at, updated_at, completed_at)
VALUES (?, ?, ?, ?, 'practice', ?, 'completed', ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
attemptId,
quiz.id,
classId,
quiz.title,
partial ? 'retake' : 'full',
JSON.stringify({ shuffleQuestions: false, shuffleOptions: false, timeLimitSec: null, sataScoring: 'partial' }),
JSON.stringify({ questions: snapshot }),
JSON.stringify(newAnswers),
snapshot.length,
Number(a.score) || 0,
Number(a.maxScore) || snapshot.length,
completedAt,
completedAt,
completedAt,
);
for (const q of snapshot) {
const selected = newAnswers[q.id]?.selected ?? [];
if (selected.length === 0 && partial) continue;
const score = scoreQuestion(q, selected, 'partial');
db.run(
'INSERT OR IGNORE INTO responses (attempt_id, question_id, quiz_id, class_id, topic, score, correct, answered_at) VALUES (?, ?, ?, ?, ?, ?, ?, ?)',
attemptId,
q.id,
quiz.id,
classId,
q.topic,
score,
isFullyCorrect(score) ? 1 : 0,
completedAt,
);
}
}
}
// Flashcard activity keeps the study heatmap and streak intact. Quiz activity is rebuilt from the attempts above.
for (const a of activity) {
if (String(a.type) !== 'FLASHCARD') continue;
const t = toMs(a.occurredAt);
if (t) db.run(`INSERT INTO reviews (card_id, deck_id, class_id, rating, state_before, scheduled_days, mode, prev, reviewed_at) VALUES ('v1', NULL, NULL, 3, 0, 0, 'legacy', '', ?)`, t);
}
});
return summary;
} finally {
src.close();
}
}

372
tests/api.test.ts Normal file
View file

@ -0,0 +1,372 @@
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import { afterEach, beforeEach, describe, expect, it } from 'vitest';
import { createTestApp, PASSWORD, sampleQuestions, type TestApp } from './helpers.ts';
let t: TestApp;
beforeEach(async () => {
t = await createTestApp();
});
afterEach(() => t.close());
async function makeClass(name = 'Pharmacology') {
const res = await t.api('POST', '/api/classes', { name });
expect(res.status).toBe(201);
return res.body.class as { id: string; name: string };
}
describe('authentication', () => {
it('requires the setup code, then a session, for private routes', async () => {
const fresh = await createTestApp({ login: false });
try {
expect((await fresh.api('GET', '/api/auth/status')).body).toEqual({ configured: false, authenticated: false });
expect((await fresh.api('GET', '/api/classes')).status).toBe(401);
const bad = await fresh.api('POST', '/api/auth/setup', { code: 'WRONG-CODE', password: PASSWORD });
expect(bad.status).toBe(403);
expect(fs.existsSync(path.join(fresh.dir, 'setup-code.txt'))).toBe(true);
const code = fs.readFileSync(path.join(fresh.dir, 'setup-code.txt'), 'utf8').trim();
const ok = await fresh.raw('POST', '/api/auth/setup', { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ code, password: PASSWORD }) });
expect(ok.status).toBe(200);
const cookie = ok.headers.get('set-cookie') ?? '';
expect(cookie).toMatch(/HttpOnly/i);
expect(cookie).toMatch(/SameSite=Lax/i);
expect(fs.existsSync(path.join(fresh.dir, 'setup-code.txt'))).toBe(false);
// Setup cannot be repeated.
expect((await fresh.api('POST', '/api/auth/setup', { code, password: 'another password' })).status).toBe(409);
fresh.cookie = cookie.split(';')[0];
expect((await fresh.api('GET', '/api/classes')).status).toBe(200);
} finally {
fresh.close();
}
});
it('rejects wrong passwords, rate-limits, and logs out', async () => {
expect((await t.api('POST', '/api/auth/login', { password: 'nope' }, { cookie: null })).status).toBe(401);
const good = await t.raw('POST', '/api/auth/login', { cookie: null, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: PASSWORD }) });
expect(good.status).toBe(200);
for (let i = 0; i < 8; i += 1) await t.api('POST', '/api/auth/login', { password: 'nope' }, { cookie: null });
const limited = await t.api('POST', '/api/auth/login', { password: PASSWORD }, { cookie: null });
expect(limited.status).toBe(429);
expect(limited.headers.get('retry-after')).toBeTruthy();
expect((await t.api('POST', '/api/auth/logout')).status).toBe(200);
expect((await t.api('GET', '/api/classes')).status).toBe(401);
});
it('blocks state-changing requests without the CSRF header or from another site', async () => {
const noHeader = await t.hono.request('/api/classes', { method: 'POST', headers: { cookie: t.cookie, 'content-type': 'application/json' }, body: JSON.stringify({ name: 'X' }) });
expect(noHeader.status).toBe(403);
const crossSite = await t.api('POST', '/api/classes', { name: 'X' }, { headers: { 'sec-fetch-site': 'cross-site' } });
expect(crossSite.status).toBe(403);
});
it('changes the password and signs out other sessions', async () => {
const other = await t.raw('POST', '/api/auth/login', { cookie: null, headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: PASSWORD }) });
const otherCookie = (other.headers.get('set-cookie') ?? '').split(';')[0];
expect((await t.api('POST', '/api/auth/password', { current: 'wrong', next: 'a new password!' })).status).toBe(403);
expect((await t.api('POST', '/api/auth/password', { current: PASSWORD, next: 'a new password!' })).status).toBe(200);
expect((await t.api('GET', '/api/classes')).status).toBe(200);
expect((await t.api('GET', '/api/classes', undefined, { cookie: otherCookie })).status).toBe(401);
expect((await t.api('POST', '/api/auth/login', { password: 'a new password!' }, { cookie: null })).status).toBe(200);
});
});
describe('classes, quizzes and questions', () => {
it('creates, edits, duplicates, moves and deletes', async () => {
const cls = await makeClass();
const other = await makeClass('Pediatrics');
const folder = (await t.api('POST', `/api/classes/${cls.id}/folders`, { name: 'Unit 1' })).body.folder;
const created = await t.api('POST', '/api/quizzes', { classId: cls.id, folderId: folder.id, title: 'Electrolytes', questions: sampleQuestions });
expect(created.status).toBe(201);
const quizId = created.body.quiz.id;
let detail = (await t.api('GET', `/api/quizzes/${quizId}`)).body;
expect(detail.questions).toHaveLength(3);
expect(detail.questions[0].options.every((o: any) => typeof o.id === 'string')).toBe(true);
// Validation: multiple choice with two correct answers is rejected with a clear message.
const invalid = await t.api('PATCH', `/api/questions/${detail.questions[0].id}`, { ...sampleQuestions[0], options: sampleQuestions[0].options.map((o) => ({ ...o, correct: true })) });
expect(invalid.status).toBe(422);
expect(invalid.body.error.message).toMatch(/exactly one correct/i);
// Editing keeps option ids for unchanged text.
const before = detail.questions[0];
const edited = await t.api('PATCH', `/api/questions/${before.id}`, { ...sampleQuestions[0], stem: 'Edited stem?' });
expect(edited.body.question.stem).toBe('Edited stem?');
expect(edited.body.question.options.map((o: any) => o.id)).toEqual(before.options.map((o: any) => o.id));
const dup = await t.api('POST', `/api/quizzes/${quizId}/duplicate`, {});
expect(dup.status).toBe(201);
expect(dup.body.quiz.title).toBe('Electrolytes (copy)');
await t.api('POST', '/api/items/move', { items: [{ kind: 'quiz', id: dup.body.quiz.id }], classId: other.id });
const otherDetail = (await t.api('GET', `/api/classes/${other.id}`)).body;
expect(otherDetail.items.map((i: any) => i.title)).toContain('Electrolytes (copy)');
await t.api('POST', `/api/quizzes/${quizId}/questions/reorder`, { ids: [...detail.questions].reverse().map((q: any) => q.id) });
detail = (await t.api('GET', `/api/quizzes/${quizId}`)).body;
expect(detail.questions[0].topic).toBe('Electrolytes');
expect(detail.questions[2].stem).toBe('Edited stem?');
expect((await t.api('DELETE', `/api/quizzes/${quizId}`)).status).toBe(200);
expect((await t.api('GET', `/api/quizzes/${quizId}`)).status).toBe(404);
const search = await t.api('GET', '/api/search?q=digoxin');
expect(search.body.results.some((r: any) => r.kind === 'question')).toBe(true);
expect((await t.api('DELETE', `/api/classes/${other.id}`)).status).toBe(200);
expect((await t.api('GET', '/api/classes')).body.classes).toHaveLength(1);
});
});
describe('quiz sessions', () => {
it('runs a practice session with resume, scoring, history and missed-question review', async () => {
const cls = await makeClass();
const quizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Electrolytes', questions: sampleQuestions })).body.quiz.id;
const started = await t.api('POST', '/api/attempts', { mode: 'practice', source: { type: 'quiz', quizId }, shuffleQuestions: false, shuffleOptions: true });
expect(started.status).toBe(201);
const attempt = started.body.attempt;
expect(attempt.questions).toHaveLength(3);
const pick = (q: any, correct: boolean) => q.options.filter((o: any) => o.correct === correct).map((o: any) => o.id);
const [q1, q2, q3] = attempt.questions;
// Q1 correct, Q2 partially correct (2 of 3), Q3 wrong.
await t.api('PATCH', `/api/attempts/${attempt.id}`, { answers: { [q1.id]: { selected: pick(q1, true), checked: true } }, currentIndex: 1, elapsedSec: 20 });
// Resume: the session is listed as active and keeps its answers and position.
const active = (await t.api('GET', '/api/attempts?status=active')).body.attempts;
expect(active).toHaveLength(1);
expect(active[0].answeredCount).toBe(1);
const resumed = (await t.api('GET', `/api/attempts/${attempt.id}`)).body.attempt;
expect(resumed.currentIndex).toBe(1);
expect(resumed.answers[q1.id].checked).toBe(true);
// A checked practice answer cannot be changed afterwards.
await t.api('PATCH', `/api/attempts/${attempt.id}`, { answers: { [q1.id]: { selected: pick(q1, false).slice(0, 1), checked: true } } });
await t.api('PATCH', `/api/attempts/${attempt.id}`, {
answers: { [q2.id]: { selected: pick(q2, true).slice(0, 2), checked: true }, [q3.id]: { selected: pick(q3, false).slice(0, 1), checked: true } },
elapsedSec: 95,
});
const done = (await t.api('POST', `/api/attempts/${attempt.id}/complete`, { elapsedSec: 100 })).body.attempt;
expect(done.status).toBe('completed');
expect(done.maxScore).toBe(3);
expect(done.score).toBeCloseTo(1 + 2 / 3 + 0, 5);
expect(done.results[q1.id].correct).toBe(true);
expect(done.results[q2.id].correct).toBe(false);
expect(done.elapsedSec).toBe(100);
const quiz = (await t.api('GET', `/api/quizzes/${quizId}`)).body;
expect(quiz.history).toHaveLength(1);
expect(quiz.questionStats[q3.id]).toEqual({ seen: 1, correct: 0, lastCorrect: false });
// Retake only what was missed.
const retake = await t.api('POST', '/api/attempts', { mode: 'practice', source: { type: 'retake', attemptId: attempt.id } });
expect(retake.status).toBe(201);
expect(retake.body.attempt.questions.map((q: any) => q.id).sort()).toEqual([q2.id, q3.id].sort());
const overview = (await t.api('GET', '/api/overview')).body;
expect(overview.totals.questionsAnswered).toBe(3);
expect(overview.missedCount).toBe(2);
expect(overview.activity.at(-1).questions).toBe(3);
const missed = await t.api('POST', '/api/attempts', { mode: 'practice', source: { type: 'missed', classId: cls.id } });
expect(missed.body.attempt.questions).toHaveLength(2);
});
it('scores exams with blanks as wrong and survives quiz edits mid-session', async () => {
const cls = await makeClass();
const quizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Exam', questions: sampleQuestions })).body.quiz.id;
const attempt = (await t.api('POST', '/api/attempts', { mode: 'exam', source: { type: 'quiz', quizId }, timeLimitMin: 10 })).body.attempt;
expect(attempt.settings.timeLimitSec).toBe(600);
const q = attempt.questions[0];
// Exam answers stay editable until submission.
await t.api('PATCH', `/api/attempts/${attempt.id}`, { answers: { [q.id]: { selected: [q.options.find((o: any) => !o.correct).id] } } });
await t.api('PATCH', `/api/attempts/${attempt.id}`, { answers: { [q.id]: { selected: q.options.filter((o: any) => o.correct).map((o: any) => o.id) } }, flags: [q.id] });
// Deleting the quiz while the exam is open must not break the session snapshot.
const live = (await t.api('GET', `/api/quizzes/${quizId}`)).body.questions;
await t.api('DELETE', `/api/questions/${live[1].id}`);
const done = (await t.api('POST', `/api/attempts/${attempt.id}/complete`, {})).body.attempt;
expect(done.maxScore).toBe(3);
expect(done.score).toBe(1);
expect(done.questions).toHaveLength(3);
expect(done.flags).toEqual([q.id]);
expect((await t.api('PATCH', `/api/attempts/${attempt.id}`, { currentIndex: 2 })).status).toBe(400);
});
});
describe('flashcards and spaced repetition', () => {
it('schedules reviews with FSRS, respects the daily new-card limit, and undoes', async () => {
const cls = await makeClass();
const cards = Array.from({ length: 30 }, (_, i) => ({ front: `Term ${i + 1}`, back: `Definition ${i + 1}` }));
const deckId = (await t.api('POST', '/api/decks', { classId: cls.id, title: 'Terms', cards })).body.deck.id;
let queue = (await t.api('GET', `/api/review/queue?deckId=${deckId}`)).body;
expect(queue.cards).toHaveLength(20); // default new cards per day
expect(queue.counts).toMatchObject({ new: 20, review: 0, learning: 0 });
expect(queue.cards[0].previews.map((p: any) => p.label)).toEqual(['Again', 'Hard', 'Good', 'Easy']);
const first = queue.cards[0].card;
const easy = (await t.api('POST', '/api/review/answer', { cardId: first.id, rating: 4 })).body.result;
expect(easy.card.state).toBe(2); // straight to review
expect(easy.card.due).toBeGreaterThan(Date.now() + 86_400_000);
expect(easy.card.reps).toBe(1);
const second = queue.cards[1].card;
const again = (await t.api('POST', '/api/review/answer', { cardId: second.id, rating: 1 })).body.result;
expect(again.card.state).toBe(1); // learning, due within minutes
expect(again.card.due).toBeLessThan(Date.now() + 20 * 60_000);
queue = (await t.api('GET', `/api/review/queue?deckId=${deckId}`)).body;
expect(queue.counts.learning).toBe(1);
expect(queue.counts.new).toBe(18);
expect(queue.cards[0].card.id).toBe(second.id); // learning cards come first
const undone = (await t.api('POST', '/api/review/undo', { cardId: first.id })).body.result;
expect(undone.card.state).toBe(0);
expect(undone.card.reps).toBe(0);
const deck = (await t.api('GET', `/api/decks/${deckId}`)).body;
expect(deck.stats).toMatchObject({ total: 30, new: 29, learning: 1 });
// Suspended cards leave the queue; resetting restores them as new.
await t.api('PATCH', `/api/cards/${second.id}`, { suspended: true });
expect((await t.api('GET', `/api/review/queue?deckId=${deckId}`)).body.counts.learning).toBe(0);
// Cram progress is saved and restored.
await t.api('PUT', `/api/decks/${deckId}/session`, { state: { order: ['a', 'b'], index: 1 } });
expect((await t.api('GET', `/api/decks/${deckId}`)).body.session.state).toEqual({ order: ['a', 'b'], index: 1 });
await t.api('POST', '/api/review/cram', { cardId: first.id, known: true });
expect((await t.api('GET', '/api/overview')).body.activity.at(-1).cards).toBeGreaterThanOrEqual(2);
});
});
describe('sharing', () => {
it('serves shared content anonymously and stops when revoked', async () => {
const cls = await makeClass();
const quizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Shared quiz', questions: sampleQuestions })).body.quiz.id;
const privateQuizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Private quiz', questions: sampleQuestions })).body.quiz.id;
const share = (await t.api('POST', '/api/shares', { kind: 'quiz', targetId: quizId })).body.share;
expect(share.token.length).toBeGreaterThanOrEqual(32);
const anon = { cookie: null };
const pub = await t.api('GET', `/api/public/${share.token}`, undefined, anon);
expect(pub.status).toBe(200);
expect(pub.body.kind).toBe('quiz');
expect(pub.body.questions).toHaveLength(3);
expect(pub.headers.get('x-robots-tag')).toMatch(/noindex/);
// Visitors cannot reach anything else.
expect((await t.api('GET', `/api/quizzes/${privateQuizId}`, undefined, anon)).status).toBe(401);
expect((await t.api('GET', `/api/public/${share.token}/items/quiz/${privateQuizId}`, undefined, anon)).status).toBe(404);
expect((await t.api('PATCH', `/api/quizzes/${quizId}`, { title: 'hacked' }, anon)).status).toBe(401);
expect((await t.api('POST', `/api/public/${share.token}`, { x: 1 }, anon)).status).toBe(401);
expect((await t.api('GET', '/api/public/not-a-real-token-000000000000000000', undefined, anon)).status).toBe(404);
// Disable, re-enable, rotate, delete.
await t.api('PATCH', `/api/shares/${share.id}`, { enabled: false });
expect((await t.api('GET', `/api/public/${share.token}`, undefined, anon)).status).toBe(404);
await t.api('PATCH', `/api/shares/${share.id}`, { enabled: true });
const rotated = (await t.api('POST', `/api/shares/${share.id}/rotate`)).body.share;
expect(rotated.token).not.toBe(share.token);
expect((await t.api('GET', `/api/public/${share.token}`, undefined, anon)).status).toBe(404);
expect((await t.api('GET', `/api/public/${rotated.token}`, undefined, anon)).status).toBe(200);
await t.api('DELETE', `/api/shares/${share.id}`);
expect((await t.api('GET', `/api/public/${rotated.token}`, undefined, anon)).status).toBe(404);
});
it('shares a class as a collection without exposing documents', async () => {
const cls = await makeClass();
const quizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Q', questions: sampleQuestions })).body.quiz.id;
const deckId = (await t.api('POST', '/api/decks', { classId: cls.id, title: 'D', cards: [{ front: 'a', back: 'b' }] })).body.deck.id;
await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Empty quiz' });
await t.api('POST', '/api/documents/text', { classId: cls.id, title: 'Secret notes', text: 'private lecture content' });
const other = await makeClass('Other');
const otherQuiz = (await t.api('POST', '/api/quizzes', { classId: other.id, title: 'Other', questions: sampleQuestions })).body.quiz.id;
const share = (await t.api('POST', '/api/shares', { kind: 'class', targetId: cls.id })).body.share;
const anon = { cookie: null };
const pub = (await t.api('GET', `/api/public/${share.token}`, undefined, anon)).body;
expect(pub.kind).toBe('collection');
expect(pub.items.map((i: any) => i.kind).sort()).toEqual(['deck', 'quiz']);
expect(JSON.stringify(pub)).not.toContain('Secret notes');
expect((await t.api('GET', `/api/public/${share.token}/items/quiz/${quizId}`, undefined, anon)).body.questions).toHaveLength(3);
expect((await t.api('GET', `/api/public/${share.token}/items/deck/${deckId}`, undefined, anon)).body.cards).toHaveLength(1);
expect((await t.api('GET', `/api/public/${share.token}/items/quiz/${otherQuiz}`, undefined, anon)).status).toBe(404);
expect((await t.api('GET', `/api/public/${share.token}/file`, undefined, anon)).status).toBe(404);
// Deleting the class removes its links.
await t.api('DELETE', `/api/classes/${cls.id}`);
expect((await t.api('GET', `/api/public/${share.token}`, undefined, anon)).status).toBe(404);
});
});
describe('import, export and templates', () => {
it('round-trips a quiz and a deck through export and import', async () => {
const cls = await makeClass();
const quizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Electrolytes', questions: sampleQuestions })).body.quiz.id;
const exported = (await t.api('GET', `/api/quizzes/${quizId}/export`)).body;
expect(exported).toMatchObject({ format: 'studydesk', version: 2, kind: 'quiz', title: 'Electrolytes' });
const imported = await t.api('POST', '/api/import', { classId: cls.id, items: [exported] });
expect(imported.status).toBe(201);
const copy = (await t.api('GET', `/api/quizzes/${imported.body.created[0].id}`)).body;
expect(copy.questions.map((q: any) => q.stem)).toEqual(sampleQuestions.map((q) => q.stem));
// V1 format is accepted as-is.
const v1 = { type: 'quiz', quizName: 'Old quiz', questions: [{ type: 'sata', prompt: 'Pick two', category: 'cat', rationale: 'r', options: [{ text: 'a', correct: true }, { text: 'b', correct: true }, { text: 'c', correct: false }] }] };
const fromV1 = await t.api('POST', '/api/import', { classId: cls.id, items: [v1] });
expect(fromV1.status).toBe(201);
const v1Quiz = (await t.api('GET', `/api/quizzes/${fromV1.body.created[0].id}`)).body;
expect(v1Quiz.questions[0]).toMatchObject({ type: 'multi', topic: 'cat' });
// Invalid content is rejected with a pointer to the problem, and nothing is created.
const bad = await t.api('POST', '/api/import', { classId: cls.id, items: [{ kind: 'quiz', title: 'Bad', questions: [{ stem: 'No correct answer', options: [{ text: 'a' }, { text: 'b' }] }] }] });
expect(bad.status).toBe(422);
expect(bad.body.error.message).toMatch(/question 1/i);
const bundle = (await t.api('GET', '/api/export/all')).body;
expect(bundle.classes[0].quizzes).toHaveLength(3);
const restored = await t.api('POST', '/api/import/bundle', bundle);
expect(restored.body.summary).toMatchObject({ classes: 1, quizzes: 3 });
expect((await t.api('GET', '/api/classes')).body.classes.map((c: any) => c.name)).toContain('Pharmacology (imported)');
});
it('lists built-in templates, saves a quiz as a template and creates from it', async () => {
const cls = await makeClass();
const quizId = (await t.api('POST', '/api/quizzes', { classId: cls.id, title: 'Source', questions: sampleQuestions })).body.quiz.id;
const list = (await t.api('GET', '/api/templates')).body.templates;
expect(list.filter((x: any) => x.builtin).length).toBeGreaterThanOrEqual(8);
const tpl = (await t.api('POST', '/api/templates/from', { kind: 'quiz', id: quizId, name: 'My template' })).body.template;
const used = await t.api('POST', `/api/templates/${tpl.id}/use`, { classId: cls.id, title: 'From template' });
expect(used.status).toBe(201);
expect((await t.api('GET', `/api/quizzes/${used.body.created.id}`)).body.questions).toHaveLength(3);
expect((await t.api('DELETE', '/api/templates/builtin-gen-nclex')).status).toBe(404);
expect((await t.api('DELETE', `/api/templates/${tpl.id}`)).status).toBe(200);
});
});
describe('persistence and backups', () => {
it('keeps data across a restart and writes a usable snapshot', async () => {
const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'studydesk-persist-'));
const first = await createTestApp({ dir });
const cls = (await first.api('POST', '/api/classes', { name: 'Persistent' })).body.class;
await first.api('POST', '/api/quizzes', { classId: cls.id, title: 'Kept', questions: sampleQuestions });
const backup = (await first.api('POST', '/api/backups')).body.backup;
expect(fs.statSync(path.join(dir, 'backups', backup.name)).size).toBeGreaterThan(1000);
first.close();
const second = await createTestApp({ dir });
try {
const classes = (await second.api('GET', '/api/classes')).body.classes;
expect(classes.map((c: any) => c.name)).toEqual(['Persistent']);
expect(classes[0].counts.quizzes).toBe(1);
const zip = await second.raw('GET', '/api/backup/download');
expect(zip.status).toBe(200);
const bytes = new Uint8Array(await zip.arrayBuffer());
expect(String.fromCharCode(bytes[0], bytes[1])).toBe('PK');
} finally {
second.close();
fs.rmSync(dir, { recursive: true, force: true });
}
});
});

121
tests/helpers.ts Normal file
View file

@ -0,0 +1,121 @@
import fs from 'node:fs';
import os from 'node:os';
import path from 'node:path';
import type { Hono } from 'hono';
import { createApp } from '../server/app.ts';
import { initAuth, resetRateLimits } from '../server/auth.ts';
import { loadConfig } from '../server/config.ts';
import { openDatabase } from '../server/db.ts';
import type { AppContext } from '../server/http.ts';
import { getSetting } from '../server/settings.ts';
import { seedTemplates } from '../server/services/templates.ts';
export interface TestApp {
ctx: AppContext;
hono: Hono;
dir: string;
cookie: string;
/** JSON request with the session cookie and CSRF header attached. */
api: <T = any>(method: string, url: string, body?: unknown, opts?: { cookie?: string | null; headers?: Record<string, string> }) => Promise<{ status: number; body: T; headers: Headers }>;
raw: (method: string, url: string, init?: RequestInit & { cookie?: string | null }) => Promise<Response>;
close: () => void;
}
export const PASSWORD = 'correct horse battery';
export async function createTestApp(opts: { login?: boolean; dir?: string; env?: Record<string, string> } = {}): Promise<TestApp> {
const dir = opts.dir ?? fs.mkdtempSync(path.join(os.tmpdir(), 'studydesk-test-'));
resetRateLimits();
const config = loadConfig({ env: 'test', dataDir: dir, webDir: null }, { NODE_ENV: 'test', TZ: 'America/Phoenix', ...opts.env });
const { db } = openDatabase(config.dbPath, config.backupsDir);
const logs: string[] = [];
const ctx: AppContext = { db, config, log: (level, message, extra) => logs.push(`${level} ${message} ${extra instanceof Error ? extra.stack : extra ? JSON.stringify(extra) : ''}`) };
await initAuth(ctx);
seedTemplates(db);
const hono = createApp(ctx);
const t: TestApp = {
ctx,
hono,
dir,
cookie: '',
raw: (method, url, init = {}) => {
const headers = new Headers(init.headers);
const cookie = init.cookie === undefined ? t.cookie : init.cookie;
if (cookie) headers.set('cookie', cookie);
if (!headers.has('x-requested-with')) headers.set('x-requested-with', 'studydesk');
return Promise.resolve(hono.request(url, { ...init, method, headers }));
},
api: async (method, url, body, o = {}) => {
const res = await t.raw(method, url, {
cookie: o.cookie,
headers: { ...(body !== undefined ? { 'content-type': 'application/json' } : {}), ...o.headers },
body: body !== undefined ? JSON.stringify(body) : undefined,
});
const text = await res.text();
let parsed: any = text;
try {
parsed = JSON.parse(text);
} catch {
/* non-JSON response */
}
return { status: res.status, body: parsed, headers: res.headers };
},
close: () => {
try {
db.close();
} catch {
/* ignore */
}
if (!opts.dir) fs.rmSync(dir, { recursive: true, force: true });
},
};
if (opts.login !== false) {
const code = getSetting<string | null>(db, 'auth.setup_code', null);
const res = code
? await t.raw('POST', '/api/auth/setup', { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ code, password: PASSWORD }), cookie: null })
: await t.raw('POST', '/api/auth/login', { headers: { 'content-type': 'application/json' }, body: JSON.stringify({ password: PASSWORD }), cookie: null });
if (res.status !== 200) throw new Error(`test login failed: ${res.status} ${await res.text()}`);
t.cookie = (res.headers.get('set-cookie') ?? '').split(';')[0];
}
return t;
}
export const sampleQuestions = [
{
type: 'single',
stem: 'Which electrolyte imbalance causes peaked T waves?',
options: [
{ text: 'Hypokalemia', correct: false },
{ text: 'Hyperkalemia', correct: true },
{ text: 'Hyponatremia', correct: false },
{ text: 'Hypercalcemia', correct: false },
],
rationale: 'High potassium produces tall, peaked T waves.',
topic: 'Electrolytes',
},
{
type: 'multi',
stem: 'Which are signs of digoxin toxicity? Select all that apply.',
options: [
{ text: 'Visual halos', correct: true },
{ text: 'Nausea', correct: true },
{ text: 'Hypertension', correct: false },
{ text: 'Bradycardia', correct: true },
],
rationale: 'GI and visual changes come first.',
topic: 'Pharmacology',
},
{
type: 'single',
stem: 'Normal adult serum potassium is:',
options: [
{ text: '3.5 to 5.0 mEq/L', correct: true },
{ text: '1.5 to 2.5 mEq/L', correct: false },
{ text: '135 to 145 mEq/L', correct: false },
],
rationale: '',
topic: 'Electrolytes',
},
];