careermate 0.1.0

package/apps/web/src/routes.ts

@@ -0,0 +1,350 @@
+/**
+ * REST API surface. Every endpoint mirrors a core use-case so the dashboard and
+ * the MCP server stay in lockstep. Handlers return plain objects (serialized to
+ * JSON by the server) or throw HttpError for clean failures.
+ *
+ * Body validation goes through zod schemas from @careermate/shared — nothing
+ * untrusted reaches the DB unvalidated.
+ */
+import {
+  ProfileInputSchema,
+  ExperienceInputSchema,
+  ProjectInputSchema,
+  SkillInputSchema,
+  DocumentInputSchema,
+  CoverLetterInputSchema,
+  CoverLetterVersionInputSchema,
+  JobInputSchema,
+  FitAnalysisInputSchema,
+  ApplicationInputSchema,
+  ApplicationStatusUpdateSchema,
+  InterviewPrepInputSchema,
+  APPLICATION_STATUS_LABELS,
+  DOCUMENT_KIND_LABELS,
+  APPLICATION_BOARD_ORDER,
+  type DocumentKind,
+} from '@careermate/shared';
+import {
+  profileRepo,
+  experienceRepo,
+  projectRepo,
+  skillRepo,
+  documentRepo,
+  coverLetterRepo,
+  jobRepo,
+  fitRepo,
+  applicationRepo,
+  interviewRepo,
+  activityRepo,
+} from '@careermate/db';
+import {
+  getOnboardingStatus,
+  getApplicationContext,
+  getHomeSummary,
+  listRecentActivity,
+  saveProfile,
+  addResume,
+  saveJobPosting,
+  saveFitAnalysis,
+  saveCoverLetterVersion,
+  updateApplicationStatus,
+  saveInterviewPrep,
+  jobWithMeta,
+} from '@careermate/core';
+import { PROMPTS } from '@careermate/prompts';
+import { WORKFLOWS } from '@careermate/workflows';
+import { cleanJobPosting, extractText } from '@careermate/parsers';
+import { z } from 'zod';
+import { Router, HttpError, readJsonBody, type Ctx } from './http.ts';
+import { exportCoverLetter, exportDocument, exportProfile, exportInterview, type ExportFormat } from './exports.ts';
+import { getServerInfo } from './info.ts';
+import { exportAll, createBackup, resetAll, listBackups } from './settings.ts';
+
+function id(ctx: Ctx, key = 'id'): string {
+  const v = ctx.params[key];
+  if (!v) throw new HttpError(400, 'id가 필요합니다.');
+  return v;
+}
+
+function fmt(ctx: Ctx): ExportFormat {
+  const f = (ctx.query.get('format') ?? 'md').toLowerCase();
+  return (['md', 'html', 'txt'].includes(f) ? f : 'md') as ExportFormat;
+}
+
+/** Assemble the full detail bundle for one job (used by the Jobs/Applications UI). */
+function jobDetail(jobId: string) {
+  const job = jobRepo.get(jobId);
+  if (!job) throw new HttpError(404, '공고를 찾을 수 없습니다.');
+  const application = applicationRepo.getByJob(jobId);
+  const fit = fitRepo.getByJob(jobId);
+  const cover_letters = coverLetterRepo.listByJob(jobId);
+  const interview = interviewRepo.getByJob(jobId);
+  const related = jobRepo.relatedTo(job.company, job.position, job.id).map(jobWithMeta);
+  return {
+    ...jobWithMeta(job),
+    application,
+    fit,
+    cover_letters,
+    interview,
+    related,
+  };
+}
+
+export function registerApiRoutes(router: Router): void {
+  /* --------------------------------------------------------------- meta */
+  router.get('/api/health', () => ({ ok: true, ...getServerInfo() }));
+  router.get('/api/onboarding', () => getOnboardingStatus());
+  router.get('/api/summary', () => getHomeSummary());
+  router.get('/api/activity', (ctx) => ({
+    activities: listRecentActivity(Number(ctx.query.get('limit') ?? 30)),
+  }));
+  router.get('/api/context', (ctx) =>
+    getApplicationContext({ job_id: ctx.query.get('job_id') ?? undefined }),
+  );
+  router.get('/api/prompts', () => ({ prompts: PROMPTS }));
+  router.get('/api/workflows', () => ({ workflows: WORKFLOWS }));
+  router.get('/api/meta', () => ({
+    statuses: APPLICATION_BOARD_ORDER.map((s) => ({ value: s, label: APPLICATION_STATUS_LABELS[s] })),
+    document_kinds: Object.entries(DOCUMENT_KIND_LABELS).map(([value, label]) => ({ value, label })),
+  }));
+
+  /* ------------------------------------------------------------ profile */
+  router.get('/api/profile', () => ({ profile: profileRepo.get() }));
+  router.put('/api/profile', async (ctx) => {
+    const input = await readJsonBody(ctx.req, ProfileInputSchema);
+    return { profile: saveProfile(input) };
+  });
+
+  /* --------------------------------------------------------- experiences */
+  router.get('/api/experiences', () => ({ experiences: experienceRepo.list() }));
+  router.post('/api/experiences', async (ctx) => {
+    const input = await readJsonBody(ctx.req, ExperienceInputSchema);
+    const exp = experienceRepo.add(input);
+    activityRepo.log('profile_updated', `경력(${exp.company})을 추가했습니다.`, 'experience', exp.id);
+    return { experience: exp };
+  });
+  router.put('/api/experiences/:id', async (ctx) => {
+    const input = await readJsonBody(ctx.req, ExperienceInputSchema.partial());
+    const exp = experienceRepo.update(id(ctx), input);
+    if (!exp) throw new HttpError(404, '경력을 찾을 수 없습니다.');
+    return { experience: exp };
+  });
+  router.delete('/api/experiences/:id', (ctx) => ({ ok: experienceRepo.remove(id(ctx)) }));
+
+  /* ------------------------------------------------------------ projects */
+  router.get('/api/projects', () => ({ projects: projectRepo.list() }));
+  router.post('/api/projects', async (ctx) => {
+    const input = await readJsonBody(ctx.req, ProjectInputSchema);
+    const prj = projectRepo.add(input);
+    activityRepo.log('profile_updated', `프로젝트(${prj.name})를 추가했습니다.`, 'project', prj.id);
+    return { project: prj };
+  });
+  router.put('/api/projects/:id', async (ctx) => {
+    const input = await readJsonBody(ctx.req, ProjectInputSchema.partial());
+    const prj = projectRepo.update(id(ctx), input);
+    if (!prj) throw new HttpError(404, '프로젝트를 찾을 수 없습니다.');
+    return { project: prj };
+  });
+  router.delete('/api/projects/:id', (ctx) => ({ ok: projectRepo.remove(id(ctx)) }));
+
+  /* -------------------------------------------------------------- skills */
+  router.get('/api/skills', () => ({ skills: skillRepo.list() }));
+  router.post('/api/skills', async (ctx) => {
+    const input = await readJsonBody(ctx.req, SkillInputSchema);
+    return { skill: skillRepo.add(input) };
+  });
+  router.put('/api/skills/:id', async (ctx) => {
+    const input = await readJsonBody(ctx.req, SkillInputSchema.partial());
+    const skill = skillRepo.update(id(ctx), input);
+    if (!skill) throw new HttpError(404, '기술을 찾을 수 없습니다.');
+    return { skill };
+  });
+  router.delete('/api/skills/:id', (ctx) => ({ ok: skillRepo.remove(id(ctx)) }));
+
+  /* ----------------------------------------------------------- documents */
+  router.get('/api/documents', (ctx) => {
+    const kind = ctx.query.get('kind') as DocumentKind | null;
+    return { documents: documentRepo.list(kind ?? undefined) };
+  });
+  router.post('/api/documents', async (ctx) => {
+    const input = await readJsonBody(ctx.req, DocumentInputSchema);
+    return { document: addResume(input) };
+  });
+  router.get('/api/documents/:id', (ctx) => {
+    const doc = documentRepo.get(id(ctx));
+    if (!doc) throw new HttpError(404, '문서를 찾을 수 없습니다.');
+    return { document: doc };
+  });
+  router.put('/api/documents/:id', async (ctx) => {
+    const input = await readJsonBody(ctx.req, DocumentInputSchema.partial());
+    const doc = documentRepo.update(id(ctx), input);
+    if (!doc) throw new HttpError(404, '문서를 찾을 수 없습니다.');
+    return { document: doc };
+  });
+  router.delete('/api/documents/:id', (ctx) => ({ ok: documentRepo.remove(id(ctx)) }));
+
+  /* ------------------------------------------------------- cover letters */
+  router.get('/api/cover-letters', () => ({ cover_letters: coverLetterRepo.list() }));
+  router.post('/api/cover-letters', async (ctx) => {
+    const input = await readJsonBody(ctx.req, CoverLetterInputSchema);
+    if (input.content) {
+      const { coverLetter } = saveCoverLetterVersion({
+        title: input.title,
+        job_id: input.job_id,
+        content: input.content,
+        note: input.note,
+        source: input.source ?? 'manual',
+      });
+      if (input.is_primary) coverLetterRepo.setPrimary(coverLetter.id);
+      activityRepo.log('cover_letter_added', `${coverLetter.title} 자기소개서를 추가했습니다.`, 'cover_letter', coverLetter.id);
+      return { cover_letter: coverLetterRepo.get(coverLetter.id) };
+    }
+    const cl = coverLetterRepo.create({ title: input.title, job_id: input.job_id ?? null, is_primary: input.is_primary });
+    activityRepo.log('cover_letter_added', `${cl.title} 자기소개서를 추가했습니다.`, 'cover_letter', cl.id);
+    return { cover_letter: cl };
+  });
+  router.get('/api/cover-letters/:id', (ctx) => {
+    const cl = coverLetterRepo.get(id(ctx), true);
+    if (!cl) throw new HttpError(404, '자기소개서를 찾을 수 없습니다.');
+    return { cover_letter: cl };
+  });
+  router.post('/api/cover-letters/:id/versions', async (ctx) => {
+    const input = await readJsonBody(
+      ctx.req,
+      CoverLetterVersionInputSchema.omit({ cover_letter_id: true }),
+    );
+    const { coverLetter, version } = saveCoverLetterVersion({ ...input, cover_letter_id: id(ctx) });
+    return { cover_letter: coverLetter, version };
+  });
+  router.put('/api/cover-letters/:id/current-version', async (ctx) => {
+    const { version_id } = await readJsonBody(ctx.req, z.object({ version_id: z.string() }));
+    const cl = coverLetterRepo.setCurrentVersion(id(ctx), version_id);
+    if (!cl) throw new HttpError(404, '자기소개서를 찾을 수 없습니다.');
+    return { cover_letter: cl };
+  });
+  router.put('/api/cover-letters/:id/primary', (ctx) => {
+    const cl = coverLetterRepo.setPrimary(id(ctx));
+    if (!cl) throw new HttpError(404, '자기소개서를 찾을 수 없습니다.');
+    return { cover_letter: cl };
+  });
+  router.delete('/api/cover-letters/:id', (ctx) => ({ ok: coverLetterRepo.remove(id(ctx)) }));
+
+  /* ---------------------------------------------------------------- jobs */
+  router.get('/api/jobs', () => ({ jobs: jobRepo.list().map(jobWithMeta) }));
+  router.post('/api/jobs', async (ctx) => {
+    const input = await readJsonBody(ctx.req, JobInputSchema);
+    const { job, application } = saveJobPosting(input);
+    return { job: jobWithMeta(job), application };
+  });
+  router.get('/api/jobs/:id', (ctx) => ({ job: jobDetail(id(ctx)) }));
+  router.put('/api/jobs/:id', async (ctx) => {
+    const input = await readJsonBody(ctx.req, JobInputSchema.partial());
+    const existing = jobRepo.get(id(ctx));
+    if (!existing) throw new HttpError(404, '공고를 찾을 수 없습니다.');
+    const job = jobRepo.upsert({ ...existing, ...input } as any, existing.id);
+    return { job: jobWithMeta(job) };
+  });
+  router.delete('/api/jobs/:id', (ctx) => ({ ok: jobRepo.remove(id(ctx)) }));
+
+  /* ----------------------------------------------------- fit / analysis */
+  router.put('/api/jobs/:id/fit', async (ctx) => {
+    const input = await readJsonBody(ctx.req, FitAnalysisInputSchema.omit({ job_id: true }));
+    return { fit: saveFitAnalysis({ ...input, job_id: id(ctx) }) };
+  });
+
+  /* --------------------------------------------------------- interview */
+  // All saved interview preps joined with their jobs, plus jobs eligible for prep
+  // (status at/after 서류 합격) that don't have prep yet — powers the Interview page.
+  router.get('/api/interview', () => {
+    const preps = interviewRepo.list().map((p) => ({ ...p, job: jobRepo.get(p.job_id) }));
+    const eligible = applicationRepo
+      .list()
+      .filter((a) => ['document_passed', 'interview', 'final_passed'].includes(a.status))
+      .map((a) => ({
+        job: jobRepo.get(a.job_id),
+        status: a.status,
+        status_label: APPLICATION_STATUS_LABELS[a.status],
+        has_prep: !!interviewRepo.getByJob(a.job_id),
+      }))
+      .filter((x) => x.job);
+    return { preps, eligible };
+  });
+  router.get('/api/jobs/:id/interview', (ctx) => ({ interview: interviewRepo.getByJob(id(ctx)) }));
+  router.put('/api/jobs/:id/interview', async (ctx) => {
+    const input = await readJsonBody(ctx.req, InterviewPrepInputSchema.omit({ job_id: true }));
+    return { interview: saveInterviewPrep({ ...input, job_id: id(ctx) }) };
+  });
+
+  /* ------------------------------------------------------- applications */
+  router.get('/api/applications', () => {
+    const apps = applicationRepo.list().map((a) => ({
+      ...a,
+      status_label: APPLICATION_STATUS_LABELS[a.status],
+      job: jobRepo.get(a.job_id),
+      fit_score: fitRepo.getByJob(a.job_id)?.score ?? null,
+    }));
+    return { applications: apps, board_order: APPLICATION_BOARD_ORDER };
+  });
+  router.put('/api/applications/:jobId/status', async (ctx) => {
+    const body = await readJsonBody(ctx.req, ApplicationStatusUpdateSchema.omit({ job_id: true, application_id: true }));
+    return updateApplicationStatus(id(ctx, 'jobId'), body.status, body.note);
+  });
+  router.put('/api/applications/:jobId', async (ctx) => {
+    const body = await readJsonBody(ctx.req, ApplicationInputSchema.omit({ job_id: true }));
+    return { application: applicationRepo.upsert({ ...body, job_id: id(ctx, 'jobId') }) };
+  });
+
+  /* ------------------------------------------------------------- export */
+  router.get('/api/export/cover-letter/:id', (ctx) => download(exportCoverLetter(id(ctx), fmt(ctx))));
+  router.get('/api/export/document/:id', (ctx) => download(exportDocument(id(ctx), fmt(ctx))));
+  router.get('/api/export/profile', (ctx) => download(exportProfile(fmt(ctx))));
+  router.get('/api/export/interview/:jobId', (ctx) => download(exportInterview(id(ctx, 'jobId'), fmt(ctx))));
+
+  /* ----------------------------------------------------------- settings */
+  router.get('/api/settings', () => ({
+    info: getServerInfo(),
+    backups: listBackups(),
+  }));
+  router.get('/api/settings/export-all', () =>
+    download({
+      filename: `careermate-backup-${new Date().toISOString().slice(0, 10)}.json`,
+      mimeType: 'application/json; charset=utf-8',
+      content: JSON.stringify(exportAll(), null, 2),
+    }),
+  );
+  router.post('/api/settings/backup', () => createBackup());
+  router.post('/api/settings/reset', async (ctx) => {
+    const { confirm } = await readJsonBody(ctx.req, z.object({ confirm: z.string() }));
+    const result = resetAll(confirm);
+    if (!result.ok) throw new HttpError(400, '초기화를 진행하려면 confirm 값으로 "DELETE"를 보내야 합니다.');
+    activityRepo.log('profile_updated', '모든 데이터를 초기화했습니다(백업 생성됨).');
+    return result;
+  });
+
+  /* -------------------------------------------------------- parse helper */
+  // Lets the dashboard pre-clean a pasted posting before saving (AI can do this
+  // too, but the UI offers it for the manual "save a posting" path).
+  router.post('/api/parse/job', async (ctx) => {
+    const { raw } = await readJsonBody(ctx.req, z.object({ raw: z.string() }));
+    return cleanJobPosting(raw);
+  });
+  router.post('/api/parse/text', async (ctx) => {
+    const body = await readJsonBody(
+      ctx.req,
+      z.object({ filename: z.string().optional(), mimeType: z.string().optional(), content: z.string() }),
+    );
+    return extractText(body);
+  });
+}
+
+/** Wrap an ExportResult so the server streams it as a file download instead of JSON. */
+import type { ExportResult } from '@careermate/exporters';
+export interface DownloadResponse {
+  __download: ExportResult;
+}
+export function download(result: ExportResult): DownloadResponse {
+  return { __download: result };
+}
+export function isDownload(v: unknown): v is DownloadResponse {
+  return typeof v === 'object' && v !== null && '__download' in v;
+}

package/apps/web/src/security.ts

@@ -0,0 +1,102 @@
+/**
+ * Local-server security.
+ *
+ * A server bound to localhost is still reachable by *any* web page the user
+ * visits (the browser will happily send requests to 127.0.0.1). Two classic
+ * attacks follow: DNS-rebinding (a malicious site points its hostname at
+ * 127.0.0.1) and CSRF (a malicious page POSTs to our API using the user's
+ * browser). We defend with three cheap, layered checks:
+ *
+ *   1. Host allow-list      — blocks DNS-rebinding (Host must be a loopback name).
+ *   2. Origin allow-list    — cross-site requests carry a foreign Origin; reject.
+ *   3. Per-session CSRF token — mutations require a header only same-origin
+ *                               scripts can read (it's injected into our HTML).
+ *
+ * We never emit permissive CORS headers, so cross-origin pages cannot read any
+ * response even if a request slips through. Everything stays on the machine.
+ */
+import crypto from 'node:crypto';
+import type { IncomingMessage } from 'node:http';
+
+/** Random token minted once per server start; embedded into served HTML. */
+export const SESSION_TOKEN = crypto.randomBytes(24).toString('hex');
+export const TOKEN_HEADER = 'x-careermate-token';
+
+const LOOPBACK_HOSTS = new Set(['localhost', '127.0.0.1', '[::1]', '::1']);
+
+function hostOnly(value: string | undefined): string | null {
+  if (!value) return null;
+  // Strip port. Handle IPv6 in brackets.
+  if (value.startsWith('[')) {
+    const end = value.indexOf(']');
+    return end === -1 ? value.toLowerCase() : value.slice(0, end + 1).toLowerCase();
+  }
+  return value.split(':')[0]!.toLowerCase();
+}
+
+export function isLoopbackHost(hostHeader: string | undefined): boolean {
+  const h = hostOnly(hostHeader);
+  return h != null && LOOPBACK_HOSTS.has(h);
+}
+
+function originHost(origin: string | undefined): string | null {
+  if (!origin || origin === 'null') return null;
+  try {
+    return new URL(origin).hostname.toLowerCase();
+  } catch {
+    return null;
+  }
+}
+
+export interface SecurityDecision {
+  ok: boolean;
+  status?: number;
+  reason?: string;
+}
+
+const MUTATING = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+/**
+ * Returns whether a request is allowed. `req.method` and headers are inspected;
+ * no body is read here (and bodies are never logged anywhere).
+ */
+export function checkRequest(req: IncomingMessage): SecurityDecision {
+  // 1. Anti DNS-rebinding: Host must be a loopback name.
+  if (!isLoopbackHost(req.headers.host)) {
+    return { ok: false, status: 403, reason: 'invalid_host' };
+  }
+
+  // 2. Cross-origin guard: if an Origin is present it must be loopback.
+  const origin = req.headers.origin;
+  if (origin) {
+    const oh = originHost(origin);
+    if (oh == null || !LOOPBACK_HOSTS.has(oh)) {
+      return { ok: false, status: 403, reason: 'cross_origin' };
+    }
+  }
+
+  // 3. CSRF token on mutations.
+  if (MUTATING.has(req.method ?? '')) {
+    const token = req.headers[TOKEN_HEADER];
+    const provided = Array.isArray(token) ? token[0] : token;
+    if (!provided || !timingSafeEqual(provided, SESSION_TOKEN)) {
+      return { ok: false, status: 403, reason: 'invalid_csrf_token' };
+    }
+  }
+
+  return { ok: true };
+}
+
+function timingSafeEqual(a: string, b: string): boolean {
+  const ab = Buffer.from(a);
+  const bb = Buffer.from(b);
+  if (ab.length !== bb.length) return false;
+  return crypto.timingSafeEqual(ab, bb);
+}
+
+/** Inject the session token into an HTML document so same-origin JS can use it. */
+export function injectToken(html: string): string {
+  const tag = `<meta name="careermate-token" content="${SESSION_TOKEN}">`;
+  if (html.includes('</head>')) return html.replace('</head>', `  ${tag}\n</head>`);
+  return tag + html;
+}

package/apps/web/src/server.ts

@@ -0,0 +1,141 @@
+/**
+ * HTTP server: security gate → API router → static dashboard (SPA fallback) and
+ * the install page. Bound to loopback only.
+ */
+import http from 'node:http';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { getDb, writeRuntimeInfo, clearRuntimeInfo } from '@careermate/db';
+import { checkRequest, injectToken } from './security.ts';
+import { Router, sendJson, sendDownload, serveStatic, HttpError } from './http.ts';
+import { registerApiRoutes, isDownload } from './routes.ts';
+import { setServerPort } from './info.ts';
+
+// 번들 빌드(esbuild)에서 true로 치환된다. tsx 개발 실행에서는 정의되지 않아 typeof로 안전 분기.
+declare const __BUNDLED__: boolean | undefined;
+const BUNDLED = typeof __BUNDLED__ !== 'undefined' && __BUNDLED__;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// dev(tsx): apps/web/src 기준 상대경로 · prod(dist/web.mjs): dist 기준.
+const WEB_ROOT = BUNDLED ? path.resolve(__dirname, 'public') : path.resolve(__dirname, '..', 'public');
+const INSTALL_ROOT = BUNDLED
+  ? path.resolve(__dirname, 'install-page')
+  : path.resolve(__dirname, '..', '..', '..', 'install-page');
+
+const router = new Router();
+registerApiRoutes(router);
+
+export interface StartedServer {
+  server: http.Server;
+  port: number;
+  url: string;
+}
+
+export function createServer(): http.Server {
+  return http.createServer(async (req, res) => {
+    try {
+      // Security gate runs before any work.
+      const decision = checkRequest(req);
+      if (!decision.ok) {
+        sendJson(res, decision.status ?? 403, { error: '접근이 거부되었습니다.', code: decision.reason });
+        return;
+      }
+
+      const url = new URL(req.url ?? '/', `http://${req.headers.host}`);
+      const pathname = url.pathname;
+
+      // API routes.
+      if (pathname.startsWith('/api/')) {
+        const matched = router.match(req.method ?? 'GET', pathname);
+        if (!matched) {
+          sendJson(res, 404, { error: '존재하지 않는 API 경로입니다.', path: pathname });
+          return;
+        }
+        const result = await matched.handler({
+          req,
+          res,
+          params: matched.params,
+          query: url.searchParams,
+          url,
+        });
+        if (res.writableEnded) return;
+        if (isDownload(result)) {
+          const d = result.__download;
+          sendDownload(res, d.filename, d.mimeType, d.content);
+        } else {
+          sendJson(res, 200, result ?? { ok: true });
+        }
+        return;
+      }
+
+      // Install page (human + AI onboarding) served under /install.
+      // Redirect the bare /install to /install/ so the page's relative asset
+      // URLs (style.css, etc.) resolve under /install/ instead of the site root.
+      if (pathname === '/install') {
+        res.writeHead(308, { Location: `/install/${url.search}` });
+        res.end();
+        return;
+      }
+      if (pathname.startsWith('/install/')) {
+        const rel = pathname === '/install/' ? 'index.html' : pathname.slice('/install/'.length);
+        if (serveStatic(res, INSTALL_ROOT, rel, injectToken)) return;
+        if (serveStatic(res, INSTALL_ROOT, 'index.html', injectToken)) return;
+      }
+
+      // Dashboard static assets, with SPA fallback to index.html.
+      const rel = pathname === '/' ? 'index.html' : pathname.slice(1);
+      if (serveStatic(res, WEB_ROOT, rel, injectToken)) return;
+      if (serveStatic(res, WEB_ROOT, 'index.html', injectToken)) return;
+
+      sendJson(res, 404, { error: 'Not found' });
+    } catch (err) {
+      if (err instanceof HttpError) {
+        sendJson(res, err.status, { error: err.message, code: err.code });
+      } else {
+        // Never leak résumé/cover-letter content into logs or responses.
+        const message = err instanceof Error ? err.message : '알 수 없는 오류';
+        console.error('[careermate] 요청 처리 중 오류:', message);
+        sendJson(res, 500, { error: '서버 오류가 발생했습니다.' });
+      }
+    }
+  });
+}
+
+/**
+ * Start on the desired port, falling back to the next free port if taken.
+ * Always binds 127.0.0.1 — never 0.0.0.0 — so the server is unreachable from the
+ * network.
+ */
+export function startServer(preferredPort: number): Promise<StartedServer> {
+  // Ensure the DB exists/migrated before accepting requests.
+  getDb();
+  const server = createServer();
+
+  return new Promise((resolve, reject) => {
+    let attempt = 0;
+    const tryListen = (port: number) => {
+      server.once('error', (e: NodeJS.ErrnoException) => {
+        if (e.code === 'EADDRINUSE' && attempt < 15) {
+          attempt++;
+          tryListen(port + 1);
+        } else {
+          reject(e);
+        }
+      });
+      server.listen(port, '127.0.0.1', () => {
+        setServerPort(port);
+        const url = `http://127.0.0.1:${port}`;
+        // Publish our address so the MCP server (a separate process) can find us.
+        writeRuntimeInfo({ url, port, pid: process.pid, started_at: new Date().toISOString() });
+        const cleanup = () => {
+          clearRuntimeInfo();
+          process.exit(0);
+        };
+        process.on('SIGINT', cleanup);
+        process.on('SIGTERM', cleanup);
+        resolve({ server, port, url });
+      });
+    };
+    tryListen(preferredPort);
+  });
+}

package/apps/web/src/settings.ts

@@ -0,0 +1,88 @@
+/**
+ * Data management — the user's right to see, export, back up, and delete their
+ * own data. All operations are local file operations; nothing leaves the machine.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { getDb, getDbPath, getBackupsDir, getDataDir } from '@careermate/db';
+
+const TABLES = [
+  'profile',
+  'experiences',
+  'projects',
+  'skills',
+  'documents',
+  'cover_letters',
+  'cover_letter_versions',
+  'jobs',
+  'fit_analyses',
+  'applications',
+  'interview_preps',
+  'activities',
+];
+
+/** Full machine-readable dump of every table — portable backup / GDPR-style export. */
+export function exportAll(): { exported_at: string; version: number; tables: Record<string, unknown[]> } {
+  const db = getDb();
+  const tables: Record<string, unknown[]> = {};
+  for (const t of TABLES) {
+    tables[t] = db.prepare(`SELECT * FROM ${t}`).all();
+  }
+  const ver = db.prepare(`SELECT value FROM _meta WHERE key='schema_version'`).get() as
+    | { value: string }
+    | undefined;
+  return { exported_at: new Date().toISOString(), version: Number(ver?.value ?? 0), tables };
+}
+
+/** Copy the live SQLite file + a JSON dump into the backups directory. */
+export function createBackup(): { backup_path: string; json_path: string } {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dir = getBackupsDir();
+  const dbBackup = path.join(dir, `careermate-${stamp}.sqlite`);
+  const jsonBackup = path.join(dir, `careermate-${stamp}.json`);
+  // Use SQLite's online backup via VACUUM INTO for a consistent snapshot.
+  try {
+    getDb().exec(`VACUUM INTO '${dbBackup.replace(/'/g, "''")}'`);
+  } catch {
+    fs.copyFileSync(getDbPath(), dbBackup);
+  }
+  fs.writeFileSync(jsonBackup, JSON.stringify(exportAll(), null, 2), 'utf8');
+  return { backup_path: dbBackup, json_path: jsonBackup };
+}
+
+/** Wipe all user data. Requires an explicit confirmation string to avoid mistakes. */
+export function resetAll(confirm: string): { ok: boolean; backup_path?: string } {
+  if (confirm !== 'DELETE') {
+    return { ok: false };
+  }
+  // Safety: always back up before destroying.
+  const { backup_path } = createBackup();
+  const db = getDb();
+  db.exec('BEGIN');
+  try {
+    for (const t of TABLES) db.exec(`DELETE FROM ${t}`);
+    db.exec('COMMIT');
+  } catch (e) {
+    db.exec('ROLLBACK');
+    throw e;
+  }
+  return { ok: true, backup_path };
+}
+
+export function listBackups(): { filename: string; path: string; size: number; created_at: string }[] {
+  const dir = getBackupsDir();
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.sqlite') || f.endsWith('.json'))
+    .map((f) => {
+      const p = path.join(dir, f);
+      const st = fs.statSync(p);
+      return { filename: f, path: p, size: st.size, created_at: st.mtime.toISOString() };
+    })
+    .sort((a, b) => b.created_at.localeCompare(a.created_at));
+}
+
+export function getDataLocation(): { data_dir: string; db_path: string } {
+  return { data_dir: getDataDir(), db_path: getDbPath() };
+}