careermate 0.0.7 → 0.0.9

package/packages/exporters/src/docx.ts

@@ -0,0 +1,165 @@
+/**
+ * Markdown → .docx renderer.
+ *
+ * The other exporters already produce a small, well-known Markdown dialect
+ * (headings `#`…`####`, `- ` bullets, `**label**: value` rows, `[text](url)`
+ * links, `**bold**`, `_italic_`, `---` rules). Rather than re-derive structure
+ * from records per document type, we render THAT dialect to a Word document —
+ * exactly mirroring how `html.ts` turns the same Markdown into print HTML. One
+ * faithful, ATS-safe single-column layout; no decorative template.
+ *
+ * Binary output is a `Uint8Array` (the OOXML zip). Callers stream/write it as-is.
+ */
+import {
+  Document,
+  ExternalHyperlink,
+  HeadingLevel,
+  Packer,
+  Paragraph,
+  TextRun,
+} from 'docx';
+
+const HEADING_BY_LEVEL = [
+  HeadingLevel.HEADING_1,
+  HeadingLevel.HEADING_2,
+  HeadingLevel.HEADING_3,
+  HeadingLevel.HEADING_4,
+] as const;
+
+/**
+ * XML 1.0 forbids these control chars even as numeric references; the `docx`
+ * lib writes run text verbatim into document.xml, so a single one makes the
+ * whole .docx not well-formed and Word refuses to open it. Tab (0x09) and
+ * newline (0x0A) are valid and preserved. Strip everything else in the C0 set.
+ */
+const XML_INVALID_RE = /[\x00-\x08\x0B\x0C\x0E-\x1F]/g;
+const xmlSafe = (s: string): string => s.replace(XML_INVALID_RE, '');
+
+const ALNUM_RE = /[\p{L}\p{N}]/u;
+/** Link-scheme allowlist — mirrors html.ts renderInline so the docx path can't
+ *  emit javascript:/file:// hyperlinks that the HTML path neutralizes. */
+const SAFE_LINK_RE = /^(https?:|mailto:|#|\/)/i;
+
+/** Inline tokens: **bold**, _italic_, [text](url). Order-preserving, non-nesting. */
+const INLINE_RE = /(\*\*([^*]+)\*\*|_([^_]+)_|\[([^\]]+)\]\(([^)]+)\))/g;
+
+function inlineRuns(text: string): (TextRun | ExternalHyperlink)[] {
+  const src = xmlSafe(text);
+  const out: (TextRun | ExternalHyperlink)[] = [];
+  let last = 0;
+  for (const m of src.matchAll(INLINE_RE)) {
+    const idx = m.index ?? 0;
+    if (idx > last) out.push(new TextRun(src.slice(last, idx)));
+    if (m[2] !== undefined) {
+      out.push(new TextRun({ text: m[2], bold: true }));
+    } else if (m[3] !== undefined) {
+      // CommonMark intraword-underscore rule: `_` is emphasis only when flanked
+      // by non-alphanumerics, so snake_case / env-vars / file_paths
+      // (read_write_latency, API_KEY) are kept literal instead of being mangled.
+      const before = idx > 0 ? src[idx - 1] : '';
+      const after = src[idx + m[0].length] ?? '';
+      if (ALNUM_RE.test(before) || ALNUM_RE.test(after)) {
+        out.push(new TextRun(m[0])); // not emphasis — emit underscores literally
+      } else {
+        out.push(new TextRun({ text: m[3], italics: true }));
+      }
+    } else if (m[4] !== undefined) {
+      // [text](url) — a real Word hyperlink so it survives ATS text extraction.
+      const link = (m[5] ?? '').trim();
+      if (SAFE_LINK_RE.test(link)) {
+        out.push(
+          new ExternalHyperlink({
+            children: [new TextRun({ text: m[4], style: 'Hyperlink' })],
+            link,
+          }),
+        );
+      } else {
+        // Disallowed scheme (javascript:/file:/data:) → plain text, mirroring html.ts.
+        out.push(new TextRun(m[4]));
+      }
+    }
+    last = idx + m[0].length;
+  }
+  if (last < src.length) out.push(new TextRun(src.slice(last)));
+  return out.length ? out : [new TextRun('')];
+}
+
+/** Parse our Markdown dialect (blocks split on blank lines) into docx paragraphs. */
+function markdownToParagraphs(markdown: string): Paragraph[] {
+  const paras: Paragraph[] = [];
+  const lines = markdown.replace(/\r\n/g, '\n').split('\n');
+
+  for (const raw of lines) {
+    const line = raw.trimEnd();
+    if (line.trim() === '') continue; // blank lines: spacing comes from paragraph config
+
+    // Horizontal rule → a thin bottom border on an empty paragraph.
+    if (/^---+$/.test(line.trim())) {
+      paras.push(
+        new Paragraph({
+          border: { bottom: { style: 'single', size: 6, space: 1, color: 'CCCCCC' } },
+          spacing: { after: 160 },
+          children: [new TextRun('')],
+        }),
+      );
+      continue;
+    }
+
+    // ATX heading.
+    const h = /^(#{1,4})\s+(.*)$/.exec(line);
+    if (h) {
+      const level = h[1].length - 1;
+      paras.push(
+        new Paragraph({
+          heading: HEADING_BY_LEVEL[level],
+          spacing: { before: level === 0 ? 0 : 200, after: 80 },
+          children: inlineRuns(h[2]),
+        }),
+      );
+      continue;
+    }
+
+    // Bullet (-, *, + — match the markdown dialect html.ts accepts).
+    const b = /^[-*+]\s+(.*)$/.exec(line);
+    if (b) {
+      paras.push(
+        new Paragraph({ bullet: { level: 0 }, spacing: { after: 40 }, children: inlineRuns(b[1]) }),
+      );
+      continue;
+    }
+
+    paras.push(new Paragraph({ spacing: { after: 120 }, children: inlineRuns(line) }));
+  }
+
+  return paras;
+}
+
+const DOCX_FONT = '맑은 고딕'; // Malgun Gothic — ships with Windows, renders Korean + Latin cleanly.
+
+/**
+ * Render a title + our Markdown body to a .docx byte array (single-column,
+ * ATS-friendly). The leading `# title` in the body is rendered as Heading 1, so
+ * we don't duplicate the title here.
+ */
+export async function markdownToDocx(_title: string, markdown: string): Promise<Uint8Array> {
+  const doc = new Document({
+    styles: {
+      default: {
+        document: { run: { font: DOCX_FONT, size: 22 } }, // 11pt
+      },
+    },
+    sections: [
+      {
+        properties: {
+          page: { margin: { top: 1134, bottom: 1134, left: 1134, right: 1134 } }, // 2cm
+        },
+        children: markdownToParagraphs(markdown),
+      },
+    ],
+  });
+  // Packer.toBuffer returns a Node Buffer (a Uint8Array subclass) in Node.
+  return Packer.toBuffer(doc);
+}
+
+export const DOCX_MIME =
+  'application/vnd.openxmlformats-officedocument.wordprocessingml.document';

package/packages/exporters/src/index.ts

@@ -28,6 +28,7 @@ import {
   slugify,
 } from './markdown.ts';
 import { escapeHtml, toPrintableHtml } from './html.ts';
+import { markdownToDocx, DOCX_MIME } from './docx.ts';
 
 /** The uniform shape every exporter returns. */
 export interface ExportResult {
@@ -35,8 +36,16 @@ export interface ExportResult {
   filename: string;
   /** MIME type, e.g. `text/markdown` or `text/html`. */
   mimeType: string;
-  /** The document body. */
+  /**
+   * The document body as text. For binary formats (`.docx`) this is a short,
+   * human-readable note instead of the payload — write/stream {@link bytes}.
+   */
   content: string;
+  /**
+   * Present only for binary formats (e.g. `.docx`). When set, callers MUST
+   * write/stream these bytes rather than {@link content}.
+   */
+  bytes?: Uint8Array;
 }
 
 export type ExportOptions = {
@@ -47,6 +56,23 @@ export type ExportOptions = {
 const MD_MIME = 'text/markdown';
 const HTML_MIME = 'text/html';
 
+/** Stand-in `content` for binary exports — the real payload rides in `bytes`. */
+function docxNote(filename: string): string {
+  return `(Word 문서로 저장됨: ${filename})`;
+}
+
+/**
+ * Compose an export filename from slugged parts joined by `_`, then the
+ * extension — e.g. `["토스 백엔드 자기소개서", "홍길동"]` → `토스_백엔드_자기소개서_홍길동.docx`.
+ * Empty parts (no title, no owner name) drop out; if nothing survives, `fallback`
+ * is used. The owner's name as the trailing part makes files self-identifying in
+ * a downloads folder.
+ */
+function exportName(parts: (string | null | undefined)[], ext: string, fallback: string): string {
+  const slug = parts.map((p) => slugify(p, '')).filter(Boolean).join('_') || fallback;
+  return `${slug}.${ext}`;
+}
+
 /* ------------------------------------------------------------- cover letters */
 
 /** Build the shared markdown body for a cover letter (used by MD + HTML). */
@@ -74,7 +100,7 @@ export function coverLetterToMarkdown(
   opts?: ExportOptions,
 ): ExportResult {
   return {
-    filename: `${slugify(cl.title, 'cover-letter')}.md`,
+    filename: exportName([cl.title, opts?.profile?.name], 'md', 'cover_letter'),
     mimeType: MD_MIME,
     content: coverLetterBody(cl, opts),
   };
@@ -86,12 +112,22 @@ export function coverLetterToHtml(
   opts?: ExportOptions,
 ): ExportResult {
   return {
-    filename: `${slugify(cl.title, 'cover-letter')}.html`,
+    filename: exportName([cl.title, opts?.profile?.name], 'html', 'cover_letter'),
     mimeType: HTML_MIME,
     content: toPrintableHtml(cl.title, coverLetterBody(cl, opts)),
   };
 }
 
+/** Cover letter → Word (.docx), ATS-friendly single column. */
+export async function coverLetterToDocx(
+  cl: CoverLetterRecord,
+  opts?: ExportOptions,
+): Promise<ExportResult> {
+  const filename = exportName([cl.title, opts?.profile?.name], 'docx', 'cover_letter');
+  const bytes = await markdownToDocx(cl.title, coverLetterBody(cl, opts));
+  return { filename, mimeType: DOCX_MIME, content: docxNote(filename), bytes };
+}
+
 /* -------------------------------------------------------------------- resume */
 
 /** A stored resume/career document → Markdown. */
@@ -115,7 +151,7 @@ export function resumeToMarkdown(
   ]);
 
   return {
-    filename: `${slugify(doc.title, doc.kind)}.md`,
+    filename: exportName([doc.title, profile?.name], 'md', doc.kind),
     mimeType: MD_MIME,
     content: body,
   };
@@ -128,12 +164,23 @@ export function resumeToHtml(
 ): ExportResult {
   const md = resumeToMarkdown(doc, profile);
   return {
-    filename: `${slugify(doc.title, doc.kind)}.html`,
+    filename: exportName([doc.title, profile?.name], 'html', doc.kind),
     mimeType: HTML_MIME,
     content: toPrintableHtml(doc.title, md.content),
   };
 }
 
+/** A stored resume/career document → Word (.docx). */
+export async function resumeToDocx(
+  doc: DocumentRecord,
+  profile?: ProfileRecord | null,
+): Promise<ExportResult> {
+  const md = resumeToMarkdown(doc, profile);
+  const filename = exportName([doc.title, profile?.name], 'docx', doc.kind);
+  const bytes = await markdownToDocx(doc.title, md.content);
+  return { filename, mimeType: DOCX_MIME, content: docxNote(filename), bytes };
+}
+
 /* ------------------------------------------------------------------- profile */
 
 /** Full resume-style profile export → Markdown. */
@@ -243,7 +290,7 @@ export function profileToMarkdown(
   ]);
 
   return {
-    filename: `${slugify(name, 'resume')}-resume.md`,
+    filename: exportName(['프로필', profile.name], 'md', 'resume'),
     mimeType: MD_MIME,
     content,
   };
@@ -259,12 +306,97 @@ export function profileToHtml(
   const md = profileToMarkdown(profile, experiences, projects, skills);
   const title = profile.name?.trim() || '이력서';
   return {
-    filename: `${slugify(title, 'resume')}-resume.html`,
+    filename: exportName(['프로필', profile.name], 'html', 'resume'),
     mimeType: HTML_MIME,
     content: toPrintableHtml(title, md.content),
   };
 }
 
+/** Full resume-style profile export → Word (.docx). */
+export async function profileToDocx(
+  profile: ProfileRecord,
+  experiences: ExperienceRecord[] = [],
+  projects: ProjectRecord[] = [],
+  skills: SkillRecord[] = [],
+): Promise<ExportResult> {
+  const md = profileToMarkdown(profile, experiences, projects, skills);
+  const title = profile.name?.trim() || '이력서';
+  const filename = exportName(['프로필', profile.name], 'docx', 'resume');
+  const bytes = await markdownToDocx(title, md.content);
+  return { filename, mimeType: DOCX_MIME, content: docxNote(filename), bytes };
+}
+
+/**
+ * Full profile → JSON Resume (jsonresume.org, schema v1.0.0). Makes CareerMate
+ * data portable: the open standard is consumed by 100+ themes (HTML/PDF render)
+ * and other AI/ATS tools. Dates pass through as stored (YYYY-MM[-DD]); only
+ * populated fields are emitted to keep the document clean.
+ */
+export function profileToJsonResume(
+  profile: ProfileRecord,
+  experiences: ExperienceRecord[] = [],
+  projects: ProjectRecord[] = [],
+  skills: SkillRecord[] = [],
+): ExportResult {
+  const clean = <T extends Record<string, unknown>>(o: T): T =>
+    Object.fromEntries(
+      Object.entries(o).filter(([, v]) => v != null && !(Array.isArray(v) && v.length === 0) && v !== ''),
+    ) as T;
+
+  const basics = clean({
+    name: profile.name ?? '',
+    label: profile.headline ?? '',
+    email: profile.email ?? '',
+    phone: profile.phone ?? '',
+    summary: profile.summary ?? '',
+    location: profile.location ? { address: profile.location } : undefined,
+    profiles: (profile.links ?? [])
+      .filter((l) => l.url)
+      .map((l) => clean({ network: l.label ?? '', url: l.url })),
+  });
+
+  const work = experiences.map((e) =>
+    clean({
+      name: e.company ?? '',
+      position: e.role ?? '',
+      startDate: e.start_date ?? '',
+      endDate: e.is_current ? '' : (e.end_date ?? ''),
+      summary: e.description ?? '',
+      highlights: e.achievements ?? [],
+    }),
+  );
+
+  const projectsOut = projects.map((p) =>
+    clean({
+      name: p.name ?? '',
+      description: p.description ?? '',
+      highlights: p.highlights ?? [],
+      keywords: p.tech ?? [],
+      url: p.url ?? '',
+      startDate: p.start_date ?? '',
+      endDate: p.end_date ?? '',
+      roles: p.role ? [p.role] : [],
+    }),
+  );
+
+  const skillsOut = skills.map((s) => clean({ name: s.name, level: s.level ?? '' }));
+
+  const resume = {
+    $schema: 'https://raw.githubusercontent.com/jsonresume/resume-schema/v1.0.0/schema.json',
+    basics,
+    work,
+    projects: projectsOut,
+    skills: skillsOut,
+    meta: { canonical: 'https://jsonresume.org', version: 'v1.0.0', generatedBy: 'CareerMate' },
+  };
+
+  return {
+    filename: exportName(['프로필', profile.name], 'json', 'resume'),
+    mimeType: 'application/json',
+    content: JSON.stringify(resume, null, 2),
+  };
+}
+
 /* ------------------------------------------------------------ interview prep */
 
 /** Interview prep record → Markdown study sheet. */
@@ -343,7 +475,7 @@ export function interviewPrepToMarkdown(
   ]);
 
   return {
-    filename: `${slugify(titleBase, 'interview-prep')}.md`,
+    filename: exportName([titleBase], 'md', 'interview_prep'),
     mimeType: MD_MIME,
     content,
   };
@@ -357,7 +489,7 @@ export function interviewPrepToHtml(
   const md = interviewPrepToMarkdown(prep, job);
   const title = job ? `${job.company} ${job.position} 면접 준비` : '면접 준비';
   return {
-    filename: `${slugify(title, 'interview-prep')}.html`,
+    filename: exportName([title], 'html', 'interview_prep'),
     mimeType: HTML_MIME,
     content: toPrintableHtml(title, md.content),
   };
@@ -373,3 +505,4 @@ export {
   markdownToHtml,
   slugify,
 } from './markdown.ts';
+export { DOCX_MIME } from './docx.ts';

package/packages/exporters/src/markdown.ts

@@ -11,19 +11,24 @@ 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.
+ * Make a filesystem-safe slug from arbitrary text, PRESERVING the original
+ * script (Hangul, CJK, Latin, digits) so a Korean title like "백엔드 자기소개서"
+ * yields "백엔드_자기소개서" instead of a generic fallback. Spaces and any
+ * characters that aren't Unicode letters/numbers (punctuation, path separators)
+ * collapse to `_`; the result is trimmed and capped to a sane filename length.
+ * Falls back to `fallback` when nothing survives (e.g. emoji-only titles); pass
+ * `''` to opt out of the fallback when composing a multi-part name.
+ * Unicode filenames are safe on modern OSes, and the download header
+ * (`http.ts` `sendDownload`) already allows Hangul and encodes UTF-8.
  */
 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();
+  const slug = (input ?? '')
+    .normalize('NFC')
+    .replace(/[^\p{L}\p{N}]+/gu, '_') // non letter/number (space, punctuation, /\:*?…) -> separator
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .slice(0, 80)
+    .replace(/_+$/g, ''); // re-trim a separator left dangling by the length cap
   return slug || fallback;
 }
 

package/packages/knowledge/src/index.ts

@@ -47,7 +47,9 @@ export const EXPERT_DOMAINS = [
 ] as const;
 export type ExpertDomain = (typeof EXPERT_DOMAINS)[number];
 
-/** 6 verifier rubrics — 1:1 with docs/career-os/knowledge/verifiers/<id>.md (CONTRACT C3). */
+/** 7 verifier rubrics — 1:1 with docs/career-os/knowledge/verifiers/<id>.md (CONTRACT C3).
+ *  ai-detection-risk: additive (한국 AI-자소서 탐지 시장 전용 — 진정성·면접 방어가능성 점검,
+ *  탐지기 우회가 아님). human-voice(문체 "AI 티")와 역할이 다르다. */
 export const VERIFIER_IDS = [
   'truthfulness',
   'consistency',
@@ -55,6 +57,7 @@ export const VERIFIER_IDS = [
   'responsiveness-on-target',
   'ats-compat',
   'human-voice',
+  'ai-detection-risk',
 ] as const;
 export type VerifierId = (typeof VERIFIER_IDS)[number];
 
@@ -121,13 +124,15 @@ export const CAREER_ROUTES: Record<string, CareerRoute> = {
   write_cover_letter: {
     eop: 'cover-letter',
     expertSequence: ['cover-letter', 'human-writing', 'company-research'],
-    verifierSequence: ['human-voice', 'truthfulness', 'responsiveness-on-target', 'ats-compat', 'consistency'],
+    // ai-detection-risk: 한국 자소서는 AI 탐지(무하유 GPT킬러 등)가 제도화돼 있어, 저장 전
+    // "진정성·면접 방어가능성·자기복제 여부"를 점검한다(탐지 우회가 아님 — 짝은 human-voice).
+    verifierSequence: ['human-voice', 'truthfulness', 'responsiveness-on-target', 'ats-compat', 'consistency', 'ai-detection-risk'],
     loop: 'draft_verify_revise',
   },
   write_career_description: {
     eop: 'career-description',
     expertSequence: ['resume', 'ats'],
-    verifierSequence: ['truthfulness', 'consistency', 'ats-compat'],
+    verifierSequence: ['truthfulness', 'consistency', 'ats-compat', 'ai-detection-risk'],
     loop: 'draft_verify_revise',
   },
   prepare_interview: {

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

@@ -22,6 +22,15 @@ export interface ToolDef {
   inputSchema: ZodRawShape;
   /** Hint flags for clients (readOnly tools don't mutate). */
   readOnly?: boolean;
+  /**
+   * Tool reaches outside the user's machine (job-board fetch, npm registry).
+   * Must be honest — the privacy story depends on these hints being true.
+   */
+  openWorld?: boolean;
+  /** Irreversible effect (hard delete, package update). Default: non-destructive upsert. */
+  destructive?: boolean;
+  /** Repeating the same call with the same args has no additional effect (documented upserts). */
+  idempotent?: boolean;
   handler: (args: any) => ToolResult | Promise<ToolResult>;
 }