careermate 0.1.0

package/packages/mcp-tools/src/tools.ts

@@ -0,0 +1,455 @@
+/**
+ * CareerMate MCP tools.
+ *
+ * Design principle (per product spec): these are NOT thin CRUD wrappers. Each
+ * tool maps to a real task an AI assistant performs on the user's behalf, and
+ * every description tells the AI *when* and *how* to use it within the larger
+ * workflow. The star tool is `get_application_context` — one call returns
+ * everything needed to analyze a posting or write a cover letter.
+ *
+ * No analysis or writing happens here: CareerMate stores data and serves it
+ * back. The reasoning is done by the user's ChatGPT/Claude/Gemini.
+ */
+import { z } from 'zod';
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  ProfileInputSchema,
+  JobInputSchema,
+  FitAnalysisInputSchema,
+  CoverLetterVersionInputSchema,
+  InterviewPrepInputSchema,
+  APPLICATION_STATUSES,
+  APPLICATION_STATUS_LABELS,
+  DOCUMENT_KINDS,
+  CONTENT_SOURCES,
+} from '@careermate/shared';
+import {
+  profileRepo,
+  documentRepo,
+  coverLetterRepo,
+  jobRepo,
+  fitRepo,
+  applicationRepo,
+  interviewRepo,
+  getExportsDir,
+  getDataDir,
+} from '@careermate/db';
+import {
+  getOnboardingStatus,
+  getApplicationContext,
+  saveProfile,
+  addResume,
+  saveJobPosting,
+  saveFitAnalysis,
+  saveCoverLetterVersion,
+  updateApplicationStatus,
+  saveInterviewPrep,
+  listRecentActivity,
+  jobWithMeta,
+} from '@careermate/core';
+import { ONBOARDING_PROMPT, HUMANIZE_WRITING_GUIDE } from '@careermate/prompts';
+import { getWorkflow, renderWorkflowMarkdown, WORKFLOWS } from '@careermate/workflows';
+import { coverLetterToMarkdown, coverLetterToHtml } from '@careermate/exporters';
+import { cleanJobPosting } from '@careermate/parsers';
+import { ok, fail, type ToolDef } from './result.ts';
+import { resolveDashboardUrl, openInBrowser } from './bridge.ts';
+
+const STATUS_LIST = APPLICATION_STATUSES.map((s) => `${s}(${APPLICATION_STATUS_LABELS[s]})`).join(', ');
+
+export const TOOLS: ToolDef[] = [
+  /* ------------------------------------------------------------ onboarding */
+  {
+    name: 'get_onboarding_status',
+    title: '온보딩 상태 확인',
+    description:
+      'CareerMate에 어떤 정보가 준비되어 있는지(프로필·이력서·경력·스킬·자소서·공고) 확인하고, 사용자가 지금 해야 할 다음 단계를 돌려줍니다. AI 클라이언트가 연결된 직후 가장 먼저 호출하세요. 프로필 완성도(0~100)도 포함됩니다.',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const s = getOnboardingStatus();
+      const lines = s.next_steps.map((t, i) => `${i + 1}. ${t}`).join('\n');
+      return ok(
+        `온보딩 ${s.completed ? '완료됨' : '진행 필요'} · 프로필 완성도 ${s.profile_completeness}%\n\n다음 단계:\n${lines}`,
+        s,
+      );
+    },
+  },
+  {
+    name: 'start_onboarding',
+    title: '온보딩 시작 안내',
+    description:
+      '가이드형 온보딩을 시작합니다. 현재 상태와 함께, AI가 사용자를 어떻게 안내하면 되는지(프로필 입력 → 이력서/자소서 추가 → 대시보드 열기)에 대한 단계별 지침을 돌려줍니다. 사용자가 "시작하자/설정 도와줘"라고 할 때 사용하세요.',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const s = getOnboardingStatus();
+      return ok(
+        `온보딩을 시작합니다. 아래 지침을 따라 사용자를 안내하세요.\n\n${ONBOARDING_PROMPT}`,
+        { status: s, guide: ONBOARDING_PROMPT },
+      );
+    },
+  },
+
+  /* --------------------------------------------------------------- profile */
+  {
+    name: 'get_profile',
+    title: '프로필 조회',
+    description: '사용자의 기본 프로필(이름, 한 줄 소개, 요약, 희망 직무/조건, 선호 문체, 강조 포인트, 링크)을 조회합니다.',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const p = profileRepo.get();
+      return p ? ok(`프로필: ${p.name ?? '(이름 없음)'}`, p) : ok('아직 저장된 프로필이 없습니다. save_profile로 먼저 저장하세요.', null);
+    },
+  },
+  {
+    name: 'save_profile',
+    title: '프로필 저장',
+    description:
+      '사용자 프로필을 저장합니다. 전달한 필드만 갱신되고 나머지는 유지됩니다(부분 저장 안전). 이력서를 구조화한 뒤 이름/한 줄 소개/희망 직무/선호 문체/강조 포인트 등을 채워 저장하세요. 선호 문체(preferred_tone)와 강조 포인트(emphasis_points)는 이후 자기소개서 작성 품질에 직접 영향을 줍니다.',
+    inputSchema: ProfileInputSchema.shape,
+    handler: (args) => {
+      const p = saveProfile(args);
+      return ok(`프로필을 저장했습니다: ${p.name ?? ''}`.trim(), p);
+    },
+  },
+  {
+    name: 'update_profile',
+    title: '프로필 부분 수정',
+    description: '기존 프로필을 유지하면서 일부 필드만 수정합니다. save_profile과 동일하게 동작하며, 한두 개 항목만 바꿀 때 의미를 분명히 하기 위해 사용합니다.',
+    inputSchema: ProfileInputSchema.partial().shape,
+    handler: (args) => {
+      const p = saveProfile(args);
+      return ok('프로필을 수정했습니다.', p);
+    },
+  },
+
+  /* --------------------------------------------------------------- resumes */
+  {
+    name: 'add_resume',
+    title: '이력서/경력기술서 추가',
+    description:
+      '이력서, 경력기술서, 포트폴리오 등 문서를 저장합니다. content에는 사용자가 업로드/붙여넣은 텍스트(또는 정리한 Markdown)를 넣으세요. kind 기본값은 resume입니다. is_primary=true로 대표 문서를 지정하면 get_application_context의 primary_resume로 노출됩니다.',
+    inputSchema: {
+      title: z.string().describe('문서 제목'),
+      content: z.string().describe('본문 (Markdown/일반 텍스트)'),
+      kind: z.enum(DOCUMENT_KINDS).optional().describe('resume(이력서)/career_description(경력기술서)/portfolio/other'),
+      source: z.enum(CONTENT_SOURCES).optional(),
+      is_primary: z.boolean().optional().describe('대표 문서 여부'),
+      tags: z.array(z.string()).optional(),
+    },
+    handler: (args) => {
+      const doc = addResume(args);
+      return ok(`'${doc.title}' 문서를 저장했습니다.`, doc);
+    },
+  },
+  {
+    name: 'get_resumes',
+    title: '이력서 목록 조회',
+    description: '저장된 이력서/경력기술서 등 문서를 조회합니다. kind로 종류를 필터링할 수 있습니다.',
+    inputSchema: { kind: z.enum(DOCUMENT_KINDS).optional() },
+    readOnly: true,
+    handler: (args) => {
+      const docs = documentRepo.list(args?.kind);
+      return ok(`문서 ${docs.length}건`, docs);
+    },
+  },
+
+  /* ---------------------------------------------------------- cover letters */
+  {
+    name: 'add_cover_letter',
+    title: '자기소개서 추가',
+    description:
+      '기존 자기소개서를 등록합니다. content를 함께 주면 첫 번째 버전(v1)으로 저장됩니다. 사용자가 이미 쓴 자소서를 학습용으로 보관할 때 사용하세요. 새 공고용 자소서를 "생성"해서 저장할 때는 save_cover_letter_version을 사용하는 편이 버전 관리에 좋습니다.',
+    inputSchema: {
+      title: z.string(),
+      content: z.string().optional(),
+      job_id: z.string().optional(),
+      is_primary: z.boolean().optional(),
+      note: z.string().optional(),
+      source: z.enum(CONTENT_SOURCES).optional(),
+    },
+    handler: (args) => {
+      if (args.content) {
+        const { coverLetter, version } = saveCoverLetterVersion({
+          title: args.title,
+          job_id: args.job_id,
+          content: args.content,
+          note: args.note,
+          source: args.source ?? 'manual',
+        });
+        if (args.is_primary) coverLetterRepo.setPrimary(coverLetter.id);
+        return ok(`'${coverLetter.title}' 자기소개서를 저장했습니다 (v${version.version_no}).`, coverLetter);
+      }
+      const cl = coverLetterRepo.create({ title: args.title, job_id: args.job_id ?? null, is_primary: args.is_primary });
+      return ok(`'${cl.title}' 자기소개서를 생성했습니다.`, cl);
+    },
+  },
+  {
+    name: 'get_cover_letters',
+    title: '자기소개서 목록 조회',
+    description: '저장된 자기소개서를 조회합니다. job_id를 주면 해당 공고에 연결된 자소서만, 없으면 전체를 돌려줍니다. 각 항목은 현재 버전 내용과 버전 수를 포함합니다.',
+    inputSchema: { job_id: z.string().optional() },
+    readOnly: true,
+    handler: (args) => {
+      const list = args?.job_id ? coverLetterRepo.listByJob(args.job_id) : coverLetterRepo.list();
+      return ok(`자기소개서 ${list.length}건`, list);
+    },
+  },
+  {
+    name: 'save_cover_letter_version',
+    title: '자기소개서 버전 저장',
+    description:
+      '자기소개서의 새 버전을 저장합니다. CareerMate 자소서 작성 워크플로우의 핵심 저장 단계입니다. cover_letter_id를 주면 기존 자소서에 새 버전을 추가하고, 없으면 새 자소서를 만들어 v1로 저장합니다(이때 title 권장). note에 이 버전의 변경 요약(예: "지원동기 보강")을 남기면 사용자가 대시보드에서 버전 히스토리를 이해하기 쉽습니다. job_id로 공고에 연결하면 지원 항목과 자동 연결됩니다.',
+    inputSchema: CoverLetterVersionInputSchema.shape,
+    handler: (args) => {
+      const { coverLetter, version } = saveCoverLetterVersion(args);
+      return ok(`'${coverLetter.title}' v${version.version_no}을 저장했습니다.`, { coverLetter, version });
+    },
+  },
+
+  /* ------------------------------------------------------------------ jobs */
+  {
+    name: 'save_job_posting',
+    title: '채용공고 저장',
+    description:
+      '채용공고를 저장합니다(있으면 갱신). company와 position은 필수입니다. 공고 원문은 description에, 핵심 자격요건/우대사항은 requirements 배열에, 핵심 키워드는 keywords에 정리해 넣으면 이후 적합도 분석/자소서 작성에 활용됩니다. 같은 url이면 중복 생성 없이 갱신됩니다. 저장 시 지원(application) 항목이 자동으로 생성됩니다.',
+    inputSchema: JobInputSchema.shape,
+    handler: (args) => {
+      const { job } = saveJobPosting(args);
+      return ok(`'${job.company} · ${job.position}' 공고를 저장했습니다. (job_id: ${job.id})`, job);
+    },
+  },
+  {
+    name: 'get_job_posting',
+    title: '채용공고 상세 조회',
+    description: '공고 1건의 상세를 조회합니다. 공고 정보와 함께 적합도 분석, 지원 상태, 연결된 자기소개서, 면접 준비 자료를 한 번에 돌려줍니다.',
+    inputSchema: { job_id: z.string() },
+    readOnly: true,
+    handler: (args) => {
+      const job = jobRepo.get(args.job_id);
+      if (!job) return fail(`공고를 찾을 수 없습니다: ${args.job_id}`);
+      return ok(`${job.company} · ${job.position}`, {
+        job: jobWithMeta(job),
+        fit: fitRepo.getByJob(job.id),
+        application: applicationRepo.getByJob(job.id),
+        cover_letters: coverLetterRepo.listByJob(job.id),
+        interview: interviewRepo.getByJob(job.id),
+      });
+    },
+  },
+  {
+    name: 'list_jobs',
+    title: '저장된 공고 목록',
+    description: '저장된 모든 채용공고를 지원 상태와 적합도 점수와 함께 목록으로 돌려줍니다.',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const jobs = jobRepo.list().map(jobWithMeta);
+      return ok(`공고 ${jobs.length}건`, jobs);
+    },
+  },
+  {
+    name: 'parse_job_posting',
+    title: '공고 텍스트 정리',
+    description:
+      '붙여넣은 공고 원문(또는 페이지 텍스트)을 정리해 회사명/직무/마감일 추정과 기술 키워드를 추출합니다. save_job_posting 전에 빠르게 구조화할 때 보조적으로 사용하세요. (분석/판단은 AI가 직접 하고, 이 도구는 텍스트 정리만 합니다.)',
+    inputSchema: { raw: z.string().describe('공고 원문 텍스트') },
+    readOnly: true,
+    handler: (args) => {
+      const cleaned = cleanJobPosting(args.raw ?? '');
+      return ok('공고 텍스트를 정리했습니다.', cleaned);
+    },
+  },
+
+  /* ----------------------------------------------------- application context */
+  {
+    name: 'get_application_context',
+    title: '지원 맥락 한 번에 가져오기 ⭐',
+    description:
+      '★ 가장 중요한 도구. 공고를 분석하거나 자기소개서를 작성하기 전에 반드시 먼저 호출하세요. 한 번의 호출로 다음을 모두 돌려줍니다: 사용자 프로필, 대표 이력서, 전체 경력, 프로젝트, 기술스택, 기존 자기소개서, 최근 지원 이력, (job_id를 주면) 대상 공고와 이전 적합도 분석, 같은 회사/직무 관련 이전 기록, 그리고 사용자의 선호 문체·강조 포인트. 이 데이터를 근거로 분석/작성하고, 결과는 save_fit_analysis / save_cover_letter_version으로 다시 저장하세요. CareerMate는 데이터를 제공할 뿐, 분석/작성은 당신(AI)이 수행합니다.',
+    inputSchema: { job_id: z.string().optional().describe('특정 공고 기준으로 맥락을 모을 때') },
+    readOnly: true,
+    handler: (args) => {
+      const ctx = getApplicationContext({ job_id: args?.job_id });
+      const summary = [
+        `프로필: ${ctx.profile?.name ?? '미입력'}`,
+        `이력서 ${ctx.resumes.length} · 경력 ${ctx.experiences.length} · 프로젝트 ${ctx.projects.length} · 스킬 ${ctx.skills.length} · 자소서 ${ctx.cover_letters.length}`,
+        ctx.job ? `대상 공고: ${ctx.job.company} · ${ctx.job.position}` : '대상 공고 없음',
+        ctx.writing_preferences.preferred_tone ? `선호 문체: ${ctx.writing_preferences.preferred_tone}` : '',
+        '💡 자기소개서를 쓸 때는 get_writing_style_guide로 AI 티 안 나는 글쓰기 규칙을 함께 적용하세요.',
+      ].filter(Boolean).join('\n');
+      return ok(summary, ctx);
+    },
+  },
+  {
+    name: 'save_fit_analysis',
+    title: '적합도 분석 결과 저장',
+    description:
+      '공고와 사용자 정보를 비교해 당신(AI)이 도출한 적합도 분석을 저장합니다. job_id는 필수이며 먼저 save_job_posting으로 공고가 저장되어 있어야 합니다. score(0~100), summary, strengths(강점), gaps(보완 필요), matched/missing_keywords, recommendations(자소서·지원 전략 제안)를 채워 저장하세요. 같은 공고에 다시 저장하면 갱신됩니다.',
+    inputSchema: FitAnalysisInputSchema.shape,
+    handler: (args) => {
+      try {
+        const fit = saveFitAnalysis(args);
+        return ok(`적합도 분석을 저장했습니다${fit.score != null ? ` (${fit.score}점)` : ''}.`, fit);
+      } catch (e) {
+        return fail(e instanceof Error ? e.message : '저장 실패');
+      }
+    },
+  },
+
+  /* ------------------------------------------------- application status flow */
+  {
+    name: 'update_application_status',
+    title: '지원 상태 변경',
+    description: `지원 상태를 변경합니다. 가능한 상태: ${STATUS_LIST}. '서류 합격(document_passed)' 이상으로 바뀌면 면접 준비를 제안하는 힌트를 함께 돌려줍니다. note에 변경 사유를 남길 수 있습니다.`,
+    inputSchema: {
+      job_id: z.string(),
+      status: z.enum(APPLICATION_STATUSES),
+      note: z.string().optional(),
+    },
+    handler: (args) => {
+      try {
+        const res = updateApplicationStatus(args.job_id, args.status, args.note);
+        return ok(
+          `상태를 '${APPLICATION_STATUS_LABELS[args.status as keyof typeof APPLICATION_STATUS_LABELS]}'(으)로 변경했습니다.${res.hint ? `\n\n💡 ${res.hint}` : ''}`,
+          res,
+        );
+      } catch (e) {
+        return fail(e instanceof Error ? e.message : '변경 실패');
+      }
+    },
+  },
+
+  /* ---------------------------------------------------------- interview prep */
+  {
+    name: 'save_interview_prep',
+    title: '면접 준비 자료 저장',
+    description:
+      '예상 면접 질문, 꼬리 질문, STAR 답변 가이드, 1분 자기소개 초안 등 면접 준비 자료를 저장합니다. 보통 지원 상태가 서류 합격으로 바뀐 뒤, 해당 공고/직무/자소서를 근거로 당신(AI)이 생성한 자료를 저장하는 데 사용합니다. job_id는 필수입니다. 같은 공고에 다시 저장하면 갱신됩니다.',
+    inputSchema: InterviewPrepInputSchema.shape,
+    handler: (args) => {
+      try {
+        const prep = saveInterviewPrep(args);
+        return ok(`면접 준비 자료를 저장했습니다 (질문 ${prep.questions.length}개).`, prep);
+      } catch (e) {
+        return fail(e instanceof Error ? e.message : '저장 실패');
+      }
+    },
+  },
+
+  /* --------------------------------------------------------------- exports */
+  {
+    name: 'export_cover_letter',
+    title: '자기소개서 내보내기',
+    description:
+      '자기소개서를 Markdown 또는 인쇄용 HTML(브라우저에서 PDF로 저장) 파일로 내보내 데이터 폴더의 exports에 저장하고, 파일 경로와 본문을 돌려줍니다. 사용자가 "자소서 파일로 받고 싶어"라고 할 때 사용하세요. 대시보드에서 직접 다운로드할 수도 있습니다.',
+    inputSchema: {
+      cover_letter_id: z.string(),
+      format: z.enum(['md', 'html']).optional().describe('기본 md'),
+    },
+    handler: (args) => {
+      const cl = coverLetterRepo.get(args.cover_letter_id, true);
+      if (!cl) return fail('자기소개서를 찾을 수 없습니다.');
+      const job = cl.job_id ? jobRepo.get(cl.job_id) : null;
+      const profile = profileRepo.get();
+      const format = args.format ?? 'md';
+      const result = format === 'html' ? coverLetterToHtml(cl, { job, profile }) : coverLetterToMarkdown(cl, { job, profile });
+      const dir = getExportsDir();
+      const filePath = path.join(dir, result.filename);
+      try {
+        fs.writeFileSync(filePath, result.content, 'utf8');
+      } catch (e) {
+        return fail(`파일 저장 실패: ${e instanceof Error ? e.message : e}`);
+      }
+      return ok(`'${cl.title}'를 ${format.toUpperCase()}로 내보냈습니다.\n저장 위치: ${filePath}`, {
+        path: filePath,
+        filename: result.filename,
+        content: result.content,
+      });
+    },
+  },
+
+  /* ----------------------------------------------------------- dashboard ui */
+  {
+    name: 'open_dashboard',
+    title: '대시보드 열기',
+    description:
+      '로컬 CareerMate 대시보드를 사용자의 브라우저에서 엽니다. 서버가 실행 중이 아니면 자동으로 시작합니다. 저장 결과를 사용자가 눈으로 확인하게 하고 싶을 때 호출하세요(예: 적합도 분석/자소서 저장 후).',
+    inputSchema: {},
+    handler: async () => {
+      const { url, running } = await resolveDashboardUrl();
+      if (running) openInBrowser(url);
+      return ok(
+        running ? `대시보드를 열었습니다: ${url}` : `대시보드 주소: ${url} (서버가 아직 실행 중이 아니면 프로젝트 폴더에서 npm start 를 실행하세요).`,
+        { url, running },
+      );
+    },
+  },
+  {
+    name: 'open_application',
+    title: '지원/공고 페이지 열기',
+    description: '특정 공고의 지원 상세 페이지를 브라우저에서 엽니다. 적합도·자소서·면접 준비를 사용자가 바로 확인하도록 안내할 때 사용하세요.',
+    inputSchema: { job_id: z.string() },
+    handler: async (args) => {
+      const job = jobRepo.get(args.job_id);
+      if (!job) return fail('공고를 찾을 수 없습니다.');
+      const { url, running } = await resolveDashboardUrl(`/#/jobs/${args.job_id}`);
+      if (running) openInBrowser(url);
+      return ok(running ? `'${job.company} · ${job.position}' 페이지를 열었습니다: ${url}` : `페이지 주소: ${url}`, { url, running });
+    },
+  },
+
+  /* ------------------------------------------------------------- activity */
+  {
+    name: 'list_recent_activity',
+    title: '최근 활동 조회',
+    description: '최근 활동 내역(공고 저장, 적합도 분석, 자소서 버전, 상태 변경, 면접 준비 등)을 돌려줍니다. 사용자가 "최근에 뭐 했지?"라고 묻거나, 작업을 이어서 진행할 맥락이 필요할 때 사용하세요.',
+    inputSchema: { limit: z.number().optional().describe('기본 20') },
+    readOnly: true,
+    handler: (args) => {
+      const acts = listRecentActivity(args?.limit ?? 20);
+      return ok(`최근 활동 ${acts.length}건`, acts);
+    },
+  },
+
+  /* ------------------------------------------------------- workflow guide */
+  {
+    name: 'get_workflow_guide',
+    title: '워크플로우 가이드',
+    description:
+      'CareerMate의 표준 워크플로우(온보딩, 공고 분석, 자소서 작성, 지원 상태 관리, 면접 준비)의 단계별 안내를 돌려줍니다. 어떤 순서로 어떤 도구를 호출해야 할지 확인할 때 사용하세요. workflow_id를 생략하면 전체 목록을 돌려줍니다.',
+    inputSchema: {
+      workflow_id: z
+        .enum(['onboarding', 'analyze_job', 'write_cover_letter', 'manage_application_status', 'prepare_interview'])
+        .optional(),
+    },
+    readOnly: true,
+    handler: (args) => {
+      if (args?.workflow_id) {
+        const wf = getWorkflow(args.workflow_id);
+        if (!wf) return fail('해당 워크플로우를 찾을 수 없습니다.');
+        return ok(renderWorkflowMarkdown(args.workflow_id) ?? wf.title, wf);
+      }
+      return ok(
+        `사용 가능한 워크플로우 ${WORKFLOWS.length}개`,
+        WORKFLOWS.map((w) => ({ id: w.id, title: w.title, trigger: w.trigger })),
+      );
+    },
+  },
+
+  /* --------------------------------------------------- writing style guide */
+  {
+    name: 'get_writing_style_guide',
+    title: 'AI 티 안 나는 글쓰기 가이드',
+    description:
+      '자기소개서·자기 PR·지원 메일 등 사람이 쓴 듯한 글을 작성하기 직전에 호출하세요. "AI가 쓴 티"가 나는 한국어 문장 습관(번역투, 클리셰, 기계적 병렬, 상투적 연결어, 균일한 문장 리듬 등)을 제거하는 작성 규칙과 저장 전 자가 점검 항목을 돌려줍니다. 사실·수치·고유명사는 그대로 두고 문장 결만 다듬도록 안내합니다. write_cover_letter / analyze_job 워크플로우에서 자기소개서를 쓸 때 반드시 함께 적용하세요.',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => ok('AI 티 안 나는 글쓰기 가이드를 적용해 작성하세요.', { guide: HUMANIZE_WRITING_GUIDE }),
+  },
+];
+
+/** Where exported files land (surfaced for messaging). */
+export const EXPORTS_LOCATION = (): string => getDataDir();

package/packages/parsers/src/html.ts

@@ -0,0 +1,86 @@
+/**
+ * @careermate/parsers — HTML → plain text.
+ *
+ * A tiny, dependency-free HTML stripper. It is not a full parser; it is a
+ * best-effort cleaner that removes scripts/styles, converts block boundaries to
+ * newlines, decodes common entities, and collapses excess whitespace. It must
+ * never throw, even on malformed markup.
+ */
+
+/** Named entities we bother to decode (the common ones in job postings). */
+const NAMED_ENTITIES: Record<string, string> = {
+  amp: '&',
+  lt: '<',
+  gt: '>',
+  quot: '"',
+  apos: "'",
+  nbsp: ' ',
+  middot: '·',
+  hellip: '…',
+  mdash: '—',
+  ndash: '–',
+  bull: '•',
+  copy: '©',
+  reg: '®',
+  trade: '™',
+};
+
+/** Decode numeric (`&#123;` / `&#x7B;`) and a handful of named entities. */
+export function decodeEntities(input: string): string {
+  return input.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z]+);/g, (match, body: string) => {
+    if (body[0] === '#') {
+      const isHex = body[1] === 'x' || body[1] === 'X';
+      const code = parseInt(body.slice(isHex ? 2 : 1), isHex ? 16 : 10);
+      if (Number.isFinite(code) && code > 0 && code <= 0x10ffff) {
+        try {
+          return String.fromCodePoint(code);
+        } catch {
+          return match;
+        }
+      }
+      return match;
+    }
+    const named = NAMED_ENTITIES[body.toLowerCase()];
+    return named !== undefined ? named : match;
+  });
+}
+
+/** Block-level tags whose boundaries should become line breaks. */
+const BLOCK_TAG = /<\/?(p|div|section|article|header|footer|li|ul|ol|tr|table|h[1-6]|blockquote|pre)\b[^>]*>/gi;
+
+/**
+ * Convert an HTML string to readable plain text. Best-effort and total:
+ * any weird input simply yields whatever survives the regex passes.
+ */
+export function stripHtml(html: string): string {
+  if (!html) return '';
+  let s = String(html);
+
+  // Remove script/style/head blocks entirely (including content).
+  s = s.replace(/<script\b[^>]*>[\s\S]*?<\/script>/gi, ' ');
+  s = s.replace(/<style\b[^>]*>[\s\S]*?<\/style>/gi, ' ');
+  s = s.replace(/<!--[\s\S]*?-->/g, ' ');
+
+  // Line breaks and horizontal rules -> newline.
+  s = s.replace(/<br\b[^>]*>/gi, '\n');
+  s = s.replace(/<hr\b[^>]*>/gi, '\n');
+
+  // Block tag boundaries -> newline (helps keep list items / paragraphs apart).
+  s = s.replace(BLOCK_TAG, '\n');
+
+  // Strip every remaining tag.
+  s = s.replace(/<\/?[^>]+>/g, ' ');
+
+  // Decode entities after tags are gone.
+  s = decodeEntities(s);
+
+  // Normalize whitespace: collapse spaces, trim lines, cap blank-line runs.
+  s = s.replace(/[ \t\f\v]+/g, ' ');
+  s = s
+    .split('\n')
+    .map((line) => line.trim())
+    .join('\n');
+  s = s.replace(/\n{3,}/g, '\n\n');
+
+  return s.trim();
+}