careermate 0.1.0

package/packages/exporters/src/index.ts

@@ -0,0 +1,364 @@
+/**
+ * @careermate/exporters — turn CareerMate records into downloadable documents.
+ *
+ * Every exporter returns an {@link ExportResult} (`{ filename, mimeType, content }`).
+ * Markdown exporters emit `text/markdown`; HTML exporters emit a standalone,
+ * print-optimized document (`text/html`) the user can "Print → Save as PDF".
+ *
+ * Filenames are slugified and ASCII-fallback safe; they carry NO timestamp —
+ * the caller is expected to add one if desired.
+ */
+import type {
+  CoverLetterRecord,
+  DocumentRecord,
+  ExperienceRecord,
+  InterviewPrepRecord,
+  JobRecord,
+  ProfileRecord,
+  ProjectRecord,
+  SkillRecord,
+} from '@careermate/shared';
+import { DOCUMENT_KIND_LABELS } from '@careermate/shared';
+
+import {
+  bulletList,
+  dateRange,
+  joinBlocks,
+  kv,
+  slugify,
+} from './markdown.ts';
+import { escapeHtml, toPrintableHtml } from './html.ts';
+
+/** The uniform shape every exporter returns. */
+export interface ExportResult {
+  /** Safe, slugified base filename including extension (no timestamp). */
+  filename: string;
+  /** MIME type, e.g. `text/markdown` or `text/html`. */
+  mimeType: string;
+  /** The document body. */
+  content: string;
+}
+
+export type ExportOptions = {
+  job?: JobRecord | null;
+  profile?: ProfileRecord | null;
+};
+
+const MD_MIME = 'text/markdown';
+const HTML_MIME = 'text/html';
+
+/* ------------------------------------------------------------- cover letters */
+
+/** Build the shared markdown body for a cover letter (used by MD + HTML). */
+function coverLetterBody(cl: CoverLetterRecord, opts?: ExportOptions): string {
+  const job = opts?.job ?? null;
+  const profile = opts?.profile ?? null;
+
+  const meta: string[] = [];
+  if (profile?.name) meta.push(kv('지원자', profile.name));
+  if (job) meta.push(kv('지원 회사', job.company), kv('지원 직무', job.position));
+
+  const content = (cl.current_content ?? '').trim() || '_(내용 없음)_';
+
+  return joinBlocks([
+    `# ${cl.title}`,
+    meta.length ? meta.filter(Boolean).join('\n\n') : '',
+    meta.length ? '---' : '',
+    content,
+  ]);
+}
+
+/** Cover letter → Markdown. */
+export function coverLetterToMarkdown(
+  cl: CoverLetterRecord,
+  opts?: ExportOptions,
+): ExportResult {
+  return {
+    filename: `${slugify(cl.title, 'cover-letter')}.md`,
+    mimeType: MD_MIME,
+    content: coverLetterBody(cl, opts),
+  };
+}
+
+/** Cover letter → standalone, print-optimized HTML (our PDF strategy). */
+export function coverLetterToHtml(
+  cl: CoverLetterRecord,
+  opts?: ExportOptions,
+): ExportResult {
+  return {
+    filename: `${slugify(cl.title, 'cover-letter')}.html`,
+    mimeType: HTML_MIME,
+    content: toPrintableHtml(cl.title, coverLetterBody(cl, opts)),
+  };
+}
+
+/* -------------------------------------------------------------------- resume */
+
+/** A stored resume/career document → Markdown. */
+export function resumeToMarkdown(
+  doc: DocumentRecord,
+  profile?: ProfileRecord | null,
+): ExportResult {
+  const kindLabel = DOCUMENT_KIND_LABELS[doc.kind] ?? doc.kind;
+
+  const header: string[] = [];
+  if (profile?.name) header.push(kv('이름', profile.name));
+  if (profile?.email) header.push(kv('이메일', profile.email));
+  if (profile?.phone) header.push(kv('연락처', profile.phone));
+
+  const body = joinBlocks([
+    `# ${doc.title}`,
+    `_${kindLabel}_`,
+    header.length ? header.filter(Boolean).join('\n\n') : '',
+    header.length ? '---' : '',
+    (doc.content ?? '').trim() || '_(내용 없음)_',
+  ]);
+
+  return {
+    filename: `${slugify(doc.title, doc.kind)}.md`,
+    mimeType: MD_MIME,
+    content: body,
+  };
+}
+
+/** A stored resume/career document → print-optimized HTML. */
+export function resumeToHtml(
+  doc: DocumentRecord,
+  profile?: ProfileRecord | null,
+): ExportResult {
+  const md = resumeToMarkdown(doc, profile);
+  return {
+    filename: `${slugify(doc.title, doc.kind)}.html`,
+    mimeType: HTML_MIME,
+    content: toPrintableHtml(doc.title, md.content),
+  };
+}
+
+/* ------------------------------------------------------------------- profile */
+
+/** Full resume-style profile export → Markdown. */
+export function profileToMarkdown(
+  profile: ProfileRecord,
+  experiences: ExperienceRecord[] = [],
+  projects: ProjectRecord[] = [],
+  skills: SkillRecord[] = [],
+): ExportResult {
+  const name = profile.name?.trim() || '이력서';
+
+  // Header block.
+  const contact: string[] = [];
+  if (profile.email) contact.push(profile.email);
+  if (profile.phone) contact.push(profile.phone);
+  if (profile.location) contact.push(profile.location);
+  const links = (profile.links ?? [])
+    .filter((l) => l.url)
+    .map((l) => `[${l.label || l.url}](${l.url})`);
+
+  const headerBlocks = joinBlocks([
+    `# ${name}`,
+    profile.headline ? `## ${profile.headline}` : '',
+    contact.length ? contact.join(' · ') : '',
+    links.length ? links.join(' · ') : '',
+  ]);
+
+  // Summary.
+  const summaryBlock = profile.summary?.trim()
+    ? joinBlocks(['## 소개', profile.summary.trim()])
+    : '';
+
+  // Desired roles / conditions.
+  const desiredLines: string[] = [];
+  if (profile.desired_roles?.length) {
+    desiredLines.push(kv('희망 직무', profile.desired_roles.join(', ')));
+  }
+  if (profile.desired_conditions?.trim()) {
+    desiredLines.push(kv('희망 조건', profile.desired_conditions));
+  }
+  const desiredBlock = desiredLines.length
+    ? joinBlocks(['## 희망 사항', desiredLines.filter(Boolean).join('\n\n')])
+    : '';
+
+  // Experience.
+  const expBlocks = experiences.length
+    ? joinBlocks([
+        '## 경력',
+        ...experiences.map((e) => {
+          const range = dateRange(e.start_date, e.end_date, e.is_current);
+          const titleParts = [e.company, e.role].filter(Boolean).join(' — ');
+          const subParts = [e.employment_type, range].filter(Boolean).join(' · ');
+          return joinBlocks([
+            `### ${titleParts}`,
+            subParts ? `_${subParts}_` : '',
+            e.description?.trim() ? e.description.trim() : '',
+            e.achievements?.length ? bulletList(e.achievements) : '',
+            e.tech?.length ? kv('기술', e.tech.join(', ')) : '',
+          ]);
+        }),
+      ])
+    : '';
+
+  // Projects.
+  const projBlocks = projects.length
+    ? joinBlocks([
+        '## 프로젝트',
+        ...projects.map((p) => {
+          const range = dateRange(p.start_date, p.end_date);
+          const subParts = [p.role, range].filter(Boolean).join(' · ');
+          return joinBlocks([
+            `### ${p.name}`,
+            subParts ? `_${subParts}_` : '',
+            p.description?.trim() ? p.description.trim() : '',
+            p.highlights?.length ? bulletList(p.highlights) : '',
+            p.tech?.length ? kv('기술', p.tech.join(', ')) : '',
+            p.url ? kv('링크', p.url) : '',
+          ]);
+        }),
+      ])
+    : '';
+
+  // Skills — grouped by category when present.
+  let skillsBlock = '';
+  if (skills.length) {
+    const groups = new Map<string, string[]>();
+    for (const s of skills) {
+      const cat = s.category?.trim() || '기타';
+      const label = s.level?.trim() ? `${s.name} (${s.level.trim()})` : s.name;
+      if (!groups.has(cat)) groups.set(cat, []);
+      groups.get(cat)!.push(label);
+    }
+    const lines = [...groups.entries()].map(
+      ([cat, items]) => kv(cat, items.join(', ')),
+    );
+    skillsBlock = joinBlocks(['## 보유 기술', lines.filter(Boolean).join('\n\n')]);
+  }
+
+  const content = joinBlocks([
+    headerBlocks,
+    '---',
+    summaryBlock,
+    desiredBlock,
+    expBlocks,
+    projBlocks,
+    skillsBlock,
+  ]);
+
+  return {
+    filename: `${slugify(name, 'resume')}-resume.md`,
+    mimeType: MD_MIME,
+    content,
+  };
+}
+
+/** Full resume-style profile export → print-optimized HTML. */
+export function profileToHtml(
+  profile: ProfileRecord,
+  experiences: ExperienceRecord[] = [],
+  projects: ProjectRecord[] = [],
+  skills: SkillRecord[] = [],
+): ExportResult {
+  const md = profileToMarkdown(profile, experiences, projects, skills);
+  const title = profile.name?.trim() || '이력서';
+  return {
+    filename: `${slugify(title, 'resume')}-resume.html`,
+    mimeType: HTML_MIME,
+    content: toPrintableHtml(title, md.content),
+  };
+}
+
+/* ------------------------------------------------------------ interview prep */
+
+/** Interview prep record → Markdown study sheet. */
+export function interviewPrepToMarkdown(
+  prep: InterviewPrepRecord,
+  job?: JobRecord | null,
+): ExportResult {
+  const titleBase = job ? `${job.company} ${job.position} 면접 준비` : '면접 준비';
+
+  const meta: string[] = [];
+  if (job) {
+    meta.push(kv('회사', job.company), kv('직무', job.position));
+    if (job.deadline) meta.push(kv('마감', job.deadline));
+  }
+
+  const introBlock = prep.self_introduction?.trim()
+    ? joinBlocks(['## 1분 자기소개', prep.self_introduction.trim()])
+    : '';
+
+  const questionsBlock = prep.questions?.length
+    ? joinBlocks([
+        '## 예상 질문',
+        ...prep.questions.map((q, idx) =>
+          joinBlocks([
+            `### Q${idx + 1}. ${q.question}`,
+            q.intent?.trim() ? kv('의도', q.intent) : '',
+            q.answer_outline?.trim()
+              ? joinBlocks(['**답변 가이드**', q.answer_outline.trim()])
+              : '',
+            q.followups?.length
+              ? joinBlocks(['**예상 꼬리 질문**', bulletList(q.followups)])
+              : '',
+          ]),
+        ),
+      ])
+    : '';
+
+  const starBlock = prep.star_guides?.length
+    ? joinBlocks([
+        '## STAR 정리',
+        ...prep.star_guides.map((s) =>
+          joinBlocks([
+            `### ${s.question}`,
+            kv('Situation', s.situation),
+            kv('Task', s.task),
+            kv('Action', s.action),
+            kv('Result', s.result),
+          ]),
+        ),
+      ])
+    : '';
+
+  const notesBlock = prep.notes?.trim()
+    ? joinBlocks(['## 메모', prep.notes.trim()])
+    : '';
+
+  const content = joinBlocks([
+    `# ${titleBase}`,
+    meta.length ? meta.filter(Boolean).join('\n\n') : '',
+    meta.length ? '---' : '',
+    introBlock,
+    questionsBlock,
+    starBlock,
+    notesBlock,
+  ]);
+
+  return {
+    filename: `${slugify(titleBase, 'interview-prep')}.md`,
+    mimeType: MD_MIME,
+    content,
+  };
+}
+
+/** Interview prep record → print-optimized HTML. */
+export function interviewPrepToHtml(
+  prep: InterviewPrepRecord,
+  job?: JobRecord | null,
+): ExportResult {
+  const md = interviewPrepToMarkdown(prep, job);
+  const title = job ? `${job.company} ${job.position} 면접 준비` : '면접 준비';
+  return {
+    filename: `${slugify(title, 'interview-prep')}.html`,
+    mimeType: HTML_MIME,
+    content: toPrintableHtml(title, md.content),
+  };
+}
+
+/* ----------------------------------------------------------------- re-exports */
+
+export {
+  escapeHtml,
+  toPrintableHtml,
+} from './html.ts';
+export {
+  markdownToHtml,
+  slugify,
+} from './markdown.ts';

package/packages/exporters/src/markdown.ts

@@ -0,0 +1,178 @@
+/**
+ * @careermate/exporters — Markdown rendering helpers.
+ *
+ * Pure, dependency-free utilities for turning CareerMate records into Markdown
+ * documents and for converting that Markdown into print-ready HTML. The markdown
+ * renderer here is intentionally tiny: it covers the constructs our own exporters
+ * emit (headings, bold, lists, paragraphs, line breaks) and nothing more.
+ */
+import { escapeHtml } from './html.ts';
+
+/* ----------------------------------------------------------- slug / filenames */
+
+/**
+ * Make a filesystem-safe, ASCII-leaning slug from arbitrary (often Korean) text.
+ * Non-ASCII runs collapse to `-`; the result is lowercased and trimmed of
+ * leading/trailing separators. Falls back to `document` when nothing survives.
+ */
+export function slugify(input: string | null | undefined, fallback = 'document'): string {
+  const raw = (input ?? '').normalize('NFKD');
+  // Keep ASCII alphanumerics; everything else becomes a separator.
+  const slug = raw
+    .replace(/[^\x00-\x7F]+/g, '-') // drop non-ASCII (e.g. Hangul) -> separator
+    .replace(/[^a-zA-Z0-9]+/g, '-') // remaining punctuation/space -> separator
+    .replace(/-+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .toLowerCase();
+  return slug || fallback;
+}
+
+/* ----------------------------------------------------------- markdown helpers */
+
+/** Join non-empty lines/blocks with blank lines between them. */
+export function joinBlocks(blocks: (string | null | undefined | false)[]): string {
+  return blocks
+    .filter((b): b is string => typeof b === 'string' && b.trim().length > 0)
+    .join('\n\n');
+}
+
+/** Render a markdown bullet list from string items (empty/whitespace skipped). */
+export function bulletList(items: (string | null | undefined)[]): string {
+  const lines = items
+    .filter((i): i is string => typeof i === 'string' && i.trim().length > 0)
+    .map((i) => `- ${i.trim()}`);
+  return lines.join('\n');
+}
+
+/** `**label**: value` style key/value line; returns '' if value empty. */
+export function kv(label: string, value: string | null | undefined): string {
+  if (!value || !value.trim()) return '';
+  return `**${label}**: ${value.trim()}`;
+}
+
+/** Render a date range like `2021-03 ~ 현재` / `2021-03 ~ 2023-06`. */
+export function dateRange(
+  start: string | null | undefined,
+  end: string | null | undefined,
+  current = false,
+): string {
+  const s = (start ?? '').trim();
+  const e = current ? '현재' : (end ?? '').trim();
+  if (!s && !e) return '';
+  if (!s) return e;
+  if (!e) return s;
+  return `${s} ~ ${e}`;
+}
+
+/* ------------------------------------------------------ tiny markdown → HTML */
+
+/**
+ * Convert inline markdown (bold, links, line breaks) within already
+ * HTML-escaped text. Order matters: escaping happens before this so user
+ * angle-brackets are safe; we only re-introduce the tags we generate.
+ */
+function renderInline(escaped: string): string {
+  let out = escaped;
+  // **bold**
+  out = out.replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>');
+  // [label](url) — url is already escaped; guard against javascript: schemes.
+  out = out.replace(/\[([^\]]+)\]\(([^)]+)\)/g, (_m, label: string, url: string) => {
+    const safe = /^(https?:|mailto:|#|\/)/i.test(url.trim()) ? url.trim() : '#';
+    return `<a href="${safe}">${label}</a>`;
+  });
+  return out;
+}
+
+/**
+ * Minimal Markdown → HTML renderer. Supports:
+ *  - ATX headings `#`..`######`
+ *  - unordered lists (`-`, `*`, `+`)
+ *  - ordered lists (`1.`)
+ *  - horizontal rule `---`
+ *  - bold + links inline
+ *  - blank-line separated paragraphs, single newline -> <br>
+ *
+ * Anything else is treated as paragraph text. Input is HTML-escaped first, so
+ * raw HTML in the markdown is rendered as literal text (safe by default).
+ */
+export function markdownToHtml(md: string): string {
+  const src = (md ?? '').replace(/\r\n?/g, '\n');
+  const lines = src.split('\n');
+  const html: string[] = [];
+
+  let i = 0;
+  let paragraph: string[] = [];
+
+  const flushParagraph = () => {
+    if (paragraph.length === 0) return;
+    const text = paragraph
+      .map((l) => renderInline(escapeHtml(l)))
+      .join('<br>\n');
+    html.push(`<p>${text}</p>`);
+    paragraph = [];
+  };
+
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Blank line -> paragraph boundary.
+    if (trimmed === '') {
+      flushParagraph();
+      i++;
+      continue;
+    }
+
+    // Horizontal rule.
+    if (/^(-{3,}|\*{3,}|_{3,})$/.test(trimmed)) {
+      flushParagraph();
+      html.push('<hr>');
+      i++;
+      continue;
+    }
+
+    // Heading.
+    const heading = /^(#{1,6})\s+(.*)$/.exec(trimmed);
+    if (heading) {
+      flushParagraph();
+      const level = heading[1].length;
+      const content = renderInline(escapeHtml(heading[2].trim()));
+      html.push(`<h${level}>${content}</h${level}>`);
+      i++;
+      continue;
+    }
+
+    // Unordered list block.
+    if (/^[-*+]\s+/.test(trimmed)) {
+      flushParagraph();
+      const items: string[] = [];
+      while (i < lines.length && /^[-*+]\s+/.test(lines[i].trim())) {
+        const item = lines[i].trim().replace(/^[-*+]\s+/, '');
+        items.push(`<li>${renderInline(escapeHtml(item))}</li>`);
+        i++;
+      }
+      html.push(`<ul>\n${items.join('\n')}\n</ul>`);
+      continue;
+    }
+
+    // Ordered list block.
+    if (/^\d+\.\s+/.test(trimmed)) {
+      flushParagraph();
+      const items: string[] = [];
+      while (i < lines.length && /^\d+\.\s+/.test(lines[i].trim())) {
+        const item = lines[i].trim().replace(/^\d+\.\s+/, '');
+        items.push(`<li>${renderInline(escapeHtml(item))}</li>`);
+        i++;
+      }
+      html.push(`<ol>\n${items.join('\n')}\n</ol>`);
+      continue;
+    }
+
+    // Otherwise: accumulate into the current paragraph.
+    paragraph.push(line.trim());
+    i++;
+  }
+  flushParagraph();
+
+  return html.join('\n');
+}

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

@@ -0,0 +1,83 @@
+/**
+ * Bridge from the MCP process to the local dashboard process.
+ *
+ * `open_dashboard` / `open_application` need the running web server's URL. The
+ * web server publishes it to a runtime file (see @careermate/db runtime). If the
+ * server isn't running we start it (detached) and wait for it to register.
+ */
+import { spawn } from 'node:child_process';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readRuntimeInfo, isProcessAlive } from '@careermate/db';
+
+// 번들 빌드(esbuild)에서 true로 치환된다. tsx 개발 실행에서는 정의되지 않아 typeof로 안전 분기.
+declare const __BUNDLED__: boolean | undefined;
+const BUNDLED = typeof __BUNDLED__ !== 'undefined' && __BUNDLED__;
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// packages/mcp-tools/src -> repo root (dev). 번들에서는 __dirname이 dist/ 이다.
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+
+export function projectRoot(): string {
+  return REPO_ROOT;
+}
+
+function liveServer() {
+  const info = readRuntimeInfo();
+  if (info && isProcessAlive(info.pid)) return info;
+  return null;
+}
+
+/** Start the dashboard server detached and wait until it publishes its address. */
+export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } | null> {
+  const existing = liveServer();
+  if (existing) return { url: existing.url };
+
+  try {
+    // prod(번들): dist/web.mjs를 플레인 node로 실행. dev: tsx로 소스 실행.
+    const [bin, args, cwd] = BUNDLED
+      ? [process.execPath, ['--experimental-sqlite', path.join(__dirname, 'web.mjs')], __dirname]
+      : [process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/web/src/index.ts'], REPO_ROOT];
+    const child = spawn(bin, args, {
+      cwd,
+      detached: true,
+      stdio: 'ignore',
+      env: { ...process.env, CAREERMATE_NO_OPEN: '1' },
+    });
+    child.unref();
+  } catch {
+    return null;
+  }
+
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    const info = liveServer();
+    if (info) return { url: info.url };
+    await new Promise((r) => setTimeout(r, 300));
+  }
+  return null;
+}
+
+export function openInBrowser(url: string): void {
+  const platform = process.platform;
+  try {
+    if (platform === 'win32') {
+      spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
+    } else if (platform === 'darwin') {
+      spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
+    } else {
+      spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
+    }
+  } catch {
+    /* best-effort */
+  }
+}
+
+/** Resolve the dashboard URL, starting the server if needed. */
+export async function resolveDashboardUrl(hash = ''): Promise<{ url: string; running: boolean }> {
+  const live = liveServer();
+  if (live) return { url: live.url + hash, running: true };
+  const started = await ensureServer();
+  if (started) return { url: started.url + hash, running: true };
+  return { url: 'http://127.0.0.1:4319' + hash, running: false };
+}

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

@@ -0,0 +1,8 @@
+/**
+ * @careermate/mcp-tools — the CareerMate tool registry + the conversion helpers
+ * the MCP server (apps/mcp) uses to expose them. Kept separate from the server
+ * so tools can also be unit-tested or reused in other transports later.
+ */
+export { TOOLS, EXPORTS_LOCATION } from './tools.ts';
+export { ok, fail, toCallToolResult, type ToolDef, type ToolResult } from './result.ts';
+export { resolveDashboardUrl, openInBrowser, ensureServer, projectRoot } from './bridge.ts';

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

@@ -0,0 +1,49 @@
+/**
+ * Tool result shape shared by every CareerMate MCP tool, plus the conversion to
+ * the MCP CallToolResult the SDK expects.
+ *
+ * We always embed the structured payload as pretty JSON inside the text content
+ * (so *any* model/client can read it) AND expose it as `structuredContent` for
+ * clients that support it. No output schema is declared, so structuredContent is
+ * passed through without validation.
+ */
+import type { ZodRawShape } from 'zod';
+
+export interface ToolResult {
+  text: string;
+  data?: unknown;
+  isError?: boolean;
+}
+
+export interface ToolDef {
+  name: string;
+  title: string;
+  description: string;
+  inputSchema: ZodRawShape;
+  /** Hint flags for clients (readOnly tools don't mutate). */
+  readOnly?: boolean;
+  handler: (args: any) => ToolResult | Promise<ToolResult>;
+}
+
+export function ok(text: string, data?: unknown): ToolResult {
+  return { text, data };
+}
+
+export function fail(text: string): ToolResult {
+  return { text, isError: true };
+}
+
+/** Convert a ToolResult into the MCP SDK's CallToolResult. */
+export function toCallToolResult(r: ToolResult) {
+  const blocks: { type: 'text'; text: string }[] = [{ type: 'text', text: r.text }];
+  if (r.data !== undefined) {
+    blocks.push({ type: 'text', text: '```json\n' + JSON.stringify(r.data, null, 2) + '\n```' });
+  }
+  const isPlainObject =
+    typeof r.data === 'object' && r.data !== null && !Array.isArray(r.data);
+  return {
+    content: blocks,
+    ...(isPlainObject ? { structuredContent: r.data as Record<string, unknown> } : {}),
+    ...(r.isError ? { isError: true } : {}),
+  };
+}