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();
}
}