careermate 0.0.1

package/packages/workflows/src/definitions.ts

@@ -0,0 +1,109 @@
+/**
+ * @careermate/workflows — definitions.ts
+ *
+ * Step-by-step workflows the AI should follow, encoded as DATA + helper text.
+ * Each step references concrete MCP tool names so the AI knows exactly which
+ * tool to call. Korean-first (read by the AI and surfaced to users).
+ */
+
+export interface WorkflowDefinition {
+  /** Stable machine id. */
+  id: string;
+  /** Human-facing title (Korean). */
+  title: string;
+  /** One-line description of what this workflow accomplishes. */
+  description: string;
+  /** When the AI should start this workflow (natural-language trigger). */
+  trigger: string;
+  /** Ordered steps; each references the concrete MCP tool(s) to call. */
+  steps: string[];
+}
+
+export const WORKFLOWS: WorkflowDefinition[] = [
+  {
+    id: 'onboarding',
+    title: '온보딩 (첫 셋업)',
+    description:
+      '사용자가 처음 연결했을 때 프로필·이력서·자기소개서를 등록하고 대시보드를 여는 흐름.',
+    trigger:
+      '사용자가 처음 CareerMate에 연결했거나, "시작하자 / 셋업해줘 / 프로필 등록"이라고 요청할 때.',
+    steps: [
+      '`get_onboarding_status`를 호출해 현재 등록 상태(has_profile, has_resume, has_cover_letter, has_experience, has_skills, profile_completeness, next_steps)를 확인한다.',
+      '비어 있는 항목을 사용자에게 쉬운 한국어로 안내하고, 먼저 "기존에 작성해 둔 이력서·경력기술서 파일이 있는지" 묻는다(hwp/docx/pdf 모두 가능).',
+      '파일 입력 분기: ① 사용자가 "파일이 있다"고 하면 `open_inbox`로 인입 폴더를 열어 파일을 넣게 하고, "다 넣었다"고 하면 `read_inbox`로 본문을 읽는다(pdf·이미지는 read_inbox가 경로만 주므로 클라이언트의 파일 읽기로 직접 읽는다). ② 사용자가 파일 경로를 직접 알려주면 `read_document`로 읽는다. ③ "없다/직접 입력/텍스트로 붙여넣기"면 폴더를 열지 말고 받은 텍스트를 그대로 쓴다. (묻지도 않고 open_inbox로 폴더를 자동으로 열지 않는다.)',
+      '수집한 정보를 구조화해 `save_profile`로 저장한다(이름·연락처·headline·summary·desired_roles·desired_conditions, 그리고 글쓰기 선호인 preferred_tone과 emphasis_points 포함). 파일 출처는 source=upload, 직접 입력은 manual.',
+      '업로드한 이력서/경력기술서/포트폴리오 본문을 `add_resume`로 저장한다(kind·title 지정, 대표 문서는 is_primary=true).',
+      '경력·프로젝트·스킬이 파악되면 `add_experience`·`add_project`·`add_skill`로 각각 저장한다(완성도의 has_experience/has_skills에 반영).',
+      '기존 자기소개서가 있으면 `save_cover_letter_version`으로 저장한다(title+content면 v1로 저장, 없으면 나중에 작성 가능함을 안내).',
+      '`open_dashboard`를 호출해 사용자가 자기 데이터를 확인하게 한다.',
+      '다시 `get_onboarding_status`로 완성도를 확인하고, 다음 단계(공고 분석 등)를 제안한다.',
+    ],
+  },
+  {
+    id: 'analyze_job',
+    title: '공고 분석 (적합도 분석)',
+    description:
+      '채용 공고를 읽어 사용자 프로필과 비교하고, 공고와 적합도 분석을 저장한 뒤 자기소개서 작성을 제안하는 핵심 흐름.',
+    trigger:
+      '사용자가 채용 공고 링크나 본문을 붙여넣거나 "이 공고 분석해줘 / 나랑 잘 맞아?"라고 물을 때.',
+    steps: [
+      '공고 원문(붙여넣은 텍스트 또는 링크 내용)을 읽고 company, position, requirements, keywords, deadline 등 핵심 정보를 정리한다.',
+      '`get_application_context`를 호출해 한 번에 프로필·대표 이력서·경력·프로젝트·스킬·기존 자기소개서·최근 지원 현황·이전 적합도 분석·같은 회사/직무 관련 기록·글쓰기 선호(preferred_tone, emphasis_points)를 가져온다. (분석 대상 공고가 이미 저장돼 있으면 job_id도 함께 전달한다.)',
+      '공고 요구사항과 사용자 경력/스킬/프로젝트를 비교한다: 일치하는 강점(strengths)과 부족한 부분(gaps), 매칭 키워드(matched_keywords)와 누락 키워드(missing_keywords)를 도출하고, 종합 적합도 점수(score 0~100)와 요약(summary), 지원 전략 제안(recommendations)을 정리한다. 없는 경험을 지어내지 않는다.',
+      '아직 저장되지 않은 공고라면 `save_job_posting`으로 공고를 저장하고 job_id를 확보한다.',
+      '도출한 분석 결과를 `save_fit_analysis`로 저장한다(job_id, score, summary, strengths, gaps, matched_keywords, missing_keywords, recommendations).',
+      '분석 결과를 사용자에게 쉬운 한국어로 설명한다(잘 맞는 점, 보완할 점, 추천 전략). 기술 용어는 빼고 전달한다.',
+      '"이 공고에 맞춘 자기소개서를 써드릴까요?"라고 자기소개서 작성을 제안한다.',
+      '사용자가 동의하면 자기소개서를 작성하기 직전에 `get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"을 가져온다.',
+      '적합도 분석·글쓰기 선호와 글쓰기 규칙을 함께 반영해 자기소개서를 작성하고(번역투·클리셰·기계적 병렬 제거, 사실·수치는 그대로), `save_cover_letter_version`으로 저장한다(job_id 연결, note에 작성 의도 요약).',
+      '`open_application`으로 해당 지원 건을 열어 사용자가 결과를 확인하게 하고, 지원 상태 변경(예: 지원 예정/지원 완료)을 제안한다.',
+    ],
+  },
+  {
+    id: 'write_cover_letter',
+    title: '자기소개서 작성',
+    description:
+      '특정 공고에 맞춘 자기소개서를 사용자 확인을 거쳐 작성하고 버전으로 저장하는 흐름.',
+    trigger:
+      '사용자가 "자기소개서 써줘 / 이 공고용 자소서 만들어줘"라고 요청하거나, 공고 분석 후 작성 제안에 동의했을 때.',
+    steps: [
+      '`get_application_context`(가능하면 job_id 포함)를 호출해 프로필·경력·프로젝트·스킬·기존 자기소개서·이전 적합도 분석·글쓰기 선호(preferred_tone, emphasis_points)를 가져온다.',
+      '작성 전에 대상 공고, 강조할 포인트, 톤, 분량을 사용자에게 확인한다(확인 없이 큰 작업을 진행하지 않는다).',
+      '`get_writing_style_guide`를 호출해 "AI 티 안 나는 글쓰기 규칙"(번역투·클리셰·기계적 병렬·상투적 연결어·균일한 문장 리듬 제거)을 가져온다.',
+      '저장된 실제 경험·성과만으로 자기소개서를 작성하되, 위 글쓰기 규칙을 적용해 사람이 쓴 듯 자연스럽게 쓴다(사실·수치·고유명사는 그대로). 빈칸이나 확인이 필요한 부분은 추측하지 말고 표시해 사용자에게 묻는다.',
+      '완성본을 `save_cover_letter_version`으로 저장한다(기존 자기소개서면 cover_letter_id, 새로 만들면 title, 공고용이면 job_id, 변경 요약은 note, source=ai).',
+      '사용자가 원하면 `export_cover_letter`로 파일로 내보내고, 추가 수정 요청이 있으면 새 버전으로 다시 저장한다.',
+      '저장 결과를 쉬운 한국어로 알리고, 지원 상태 업데이트(`update_application_status`)나 면접 준비 등 다음 단계를 제안한다.',
+    ],
+  },
+  {
+    id: 'manage_application_status',
+    title: '지원 상태 관리',
+    description:
+      '지원 진행 상황(8단계)을 업데이트하고 상태에 맞는 다음 행동을 제안하는 흐름.',
+    trigger:
+      '사용자가 "지원했어 / 서류 합격했어 / 면접 잡혔어 / 떨어졌어"처럼 진행 상황을 알리거나 상태 변경을 요청할 때.',
+    steps: [
+      '필요하면 `get_application_context` 또는 `get_job_posting`으로 대상 지원 건과 공고를 확인한다.',
+      '적절한 상태로 `update_application_status`를 호출한다. 8단계: draft(작성 중), planned(지원 예정), applied(지원 완료), document_passed(서류 합격), interview(면접 진행), final_passed(최종 합격), rejected(불합격), on_hold(보류). 변경 사유는 note에 남긴다.',
+      '변경 결과를 사용자에게 쉬운 한국어로 알린다.',
+      '상태에 맞는 다음 단계를 제안한다: applied → 결과 기다리기 안내, document_passed/interview → 면접 준비(prepare_interview) 제안, final_passed → 축하 및 마무리, rejected/on_hold → 회고 또는 다른 공고 탐색 제안.',
+      '필요하면 `open_application`으로 해당 지원 건을 열어 보여준다.',
+    ],
+  },
+  {
+    id: 'prepare_interview',
+    title: '면접 준비',
+    description:
+      '서류 합격 이후 예상 질문·STAR 답변·1분 자기소개를 준비해 저장하는 흐름.',
+    trigger:
+      '지원 상태가 서류 합격(document_passed) 또는 면접 진행(interview)으로 바뀌었을 때, 또는 사용자가 "면접 준비 도와줘"라고 요청할 때.',
+    steps: [
+      '`get_application_context`(job_id 포함)를 호출해 공고, 프로필, 경력/프로젝트, 적합도 분석(강점·갭), 자기소개서를 가져온다.',
+      '공고와 사용자 경험을 바탕으로 예상 면접 질문(question, intent, followups, answer_outline)을 도출한다.',
+      '핵심 경험에 대한 STAR 가이드(question, situation, task, action, result)와 1분 자기소개(self_introduction) 초안을 작성한다. 실제 경험만 사용한다.',
+      '준비 내용을 `save_interview_prep`로 저장한다(job_id, questions, star_guides, self_introduction, notes).',
+      '준비 내용을 사용자에게 쉬운 한국어로 요약해 전달하고, 모의 면접/추가 질문 연습이나 상태 업데이트(`update_application_status`로 interview/final_passed)를 제안한다.',
+    ],
+  },
+];

package/packages/workflows/src/index.ts

@@ -0,0 +1,39 @@
+/**
+ * @careermate/workflows — public entry point.
+ *
+ * Re-exports the workflow data plus helpers to look up a single workflow and
+ * render it as readable Korean markdown (used in docs and MCP tool descriptions).
+ */
+export { WORKFLOWS } from './definitions.ts';
+export type { WorkflowDefinition } from './definitions.ts';
+
+import { WORKFLOWS, type WorkflowDefinition } from './definitions.ts';
+
+/** Look up a single workflow by id. Returns undefined if the id is unknown. */
+export function getWorkflow(id: string): WorkflowDefinition | undefined {
+  return WORKFLOWS.find((w) => w.id === id);
+}
+
+/**
+ * Render a workflow as a readable Korean markdown block. Used in documentation
+ * and as MCP tool descriptions so the AI can read the full step list inline.
+ * Returns undefined if the id is unknown.
+ */
+export function renderWorkflowMarkdown(id: string): string | undefined {
+  const wf = getWorkflow(id);
+  if (!wf) return undefined;
+
+  const lines: string[] = [];
+  lines.push(`# ${wf.title}`);
+  lines.push('');
+  lines.push(wf.description);
+  lines.push('');
+  lines.push(`**트리거:** ${wf.trigger}`);
+  lines.push('');
+  lines.push('## 단계');
+  wf.steps.forEach((step, i) => {
+    lines.push(`${i + 1}. ${step}`);
+  });
+  lines.push('');
+  return lines.join('\n');
+}

package/scripts/init.ts

@@ -0,0 +1,371 @@
+/**
+ * scripts/init.ts — CareerMate 자동 설치/연결.
+ *
+ * 비개발자도 명령 한 번(또는 AI 에이전트가 INSTALL.md를 따라가며)으로 끝나도록, AI 클라이언트의
+ * MCP 설정에 CareerMate 서버를 자동 등록하고 로컬 데이터 폴더를 준비한다. CareerMate 안에는
+ * LLM이 없으므로, 이 단계가 끝나면 사용자의 AI가 MCP로 로컬 데이터를 읽고 쓸 수 있다.
+ *
+ * v1이 지원하는 연결 대상(우선순위 순):
+ *   - Claude Desktop  →  claude_desktop_config.json   (JSON · mcpServers)
+ *   - Claude Code     →  <프로젝트>/.mcp.json          (JSON · mcpServers, project scope)
+ *   - Codex CLI       →  ~/.codex/config.toml          (TOML · [mcp_servers.careermate])
+ *   - Cursor          →  ~/.cursor/mcp.json            (JSON · mcpServers, 기타 MCP 클라이언트 호환)
+ *
+ * 사용:
+ *   careermate init                       감지되는 클라이언트에 등록 (기본: 로컬 실행 모드)
+ *   careermate init --client claude-code  특정 클라이언트만 (claude | claude-code | codex | cursor | gemini | antigravity)
+ *   careermate init --all-clients         감지 여부와 무관하게 지원하는 모든 클라이언트에 등록
+ *   careermate init --npx                 MCP 실행을 npx 방식으로 등록(공개 배포/개발자용)
+ *   careermate init --print               실제로 쓰지 않고 등록할 설정/명령만 출력
+ *
+ * 주의(메모리: careerflow-windows-tsx-exit-gotcha): top-level await + process.exit 조합은
+ * Windows tsx에서 종료코드를 오염시키므로, 동기 main()으로 두고 실패는 process.exitCode로만 표시한다.
+ */
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+/** npm에 공개되는 패키지 이름 = MCP 서버 키로도 사용. */
+const PKG = 'careermate';
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+type ConfigFormat = 'mcp-json' | 'codex-toml';
+
+interface ClientTarget {
+  id: string;
+  label: string;
+  format: ConfigFormat;
+  configPath: string;
+  /** JSON 클라이언트 중 `"type": "stdio"`를 함께 써야 하는 경우(Claude Code). */
+  jsonType?: boolean;
+  /** project scope처럼 항상 적용 가능한 대상은 감지 없이 기본 포함. */
+  alwaysPresent?: boolean;
+  /** 설정 경로가 유동적인 대상(Antigravity)은 '실제 파일이 있을 때만' 감지해 추측 파일 생성을 막는다. */
+  requireFileForPresent?: boolean;
+}
+
+interface ServerEntry {
+  command: string;
+  args: string[];
+}
+
+interface WriteResult {
+  changed: boolean;
+  backedUp: string | null;
+  replacedExisting: boolean;
+}
+
+/** 데이터 폴더(@careermate/db의 getDataDir와 동일 규칙). db 패키지를 끌어오지 않으려고 인라인. */
+function ensureDataDir(): string {
+  const override = process.env.CAREERMATE_DATA_DIR?.trim();
+  const dir = override && override.length > 0 ? override : path.join(os.homedir(), '.careermate');
+  fs.mkdirSync(dir, { recursive: true });
+  return dir;
+}
+
+function claudeDesktopConfigPath(): string {
+  const home = os.homedir();
+  if (process.platform === 'win32') {
+    const appData = process.env.APPDATA ?? path.join(home, 'AppData', 'Roaming');
+    return path.join(appData, 'Claude', 'claude_desktop_config.json');
+  }
+  if (process.platform === 'darwin') {
+    return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+  }
+  return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
+}
+
+function cursorConfigPath(): string {
+  return path.join(os.homedir(), '.cursor', 'mcp.json');
+}
+
+/** Claude Code project scope 설정: 사용자가 `claude`를 띄우는 CareerMate 폴더(ROOT)에 둔다. */
+function claudeCodeConfigPath(): string {
+  return path.join(ROOT, '.mcp.json');
+}
+
+/** Codex CLI 글로벌 설정(CODEX_HOME 우선). */
+function codexConfigPath(): string {
+  const home = process.env.CODEX_HOME?.trim();
+  const base = home && home.length > 0 ? home : path.join(os.homedir(), '.codex');
+  return path.join(base, 'config.toml');
+}
+
+/** Gemini CLI: `~/.gemini/settings.json` 의 mcpServers(Cursor 등과 동일 JSON 형식). */
+function geminiConfigPath(): string {
+  return path.join(os.homedir(), '.gemini', 'settings.json');
+}
+
+/**
+ * Antigravity(Gemini CLI의 소비자용 후속, 2026-06-18 전환) MCP 설정.
+ * 출시 직후라 정확한 파일 경로가 커뮤니티 소스 간 갈려, 존재하는 후보를 우선 사용한다.
+ * requireFileForPresent로 '실제 파일이 있을 때만' 감지 → 기본 init은 추측 경로에 파일을 만들지 않는다
+ * (--all-clients / --client antigravity 일 때만 첫 후보에 생성). 스키마는 Gemini와 동일(mcpServers).
+ */
+function antigravityCandidates(): string[] {
+  const g = path.join(os.homedir(), '.gemini');
+  return [
+    path.join(g, 'config', 'mcp_config.json'),
+    path.join(g, 'antigravity', 'mcp_config.json'),
+    path.join(g, 'antigravity-cli', 'mcp_config.json'),
+  ];
+}
+function antigravityConfigPath(): string {
+  return antigravityCandidates().find((p) => fs.existsSync(p)) ?? antigravityCandidates()[0];
+}
+
+function allTargets(): ClientTarget[] {
+  return [
+    { id: 'claude', label: 'Claude Desktop', format: 'mcp-json', configPath: claudeDesktopConfigPath() },
+    { id: 'claude-code', label: 'Claude Code', format: 'mcp-json', configPath: claudeCodeConfigPath(), jsonType: true, alwaysPresent: true },
+    { id: 'codex', label: 'Codex CLI', format: 'codex-toml', configPath: codexConfigPath() },
+    { id: 'cursor', label: 'Cursor (기타 MCP 클라이언트)', format: 'mcp-json', configPath: cursorConfigPath() },
+    { id: 'gemini', label: 'Gemini CLI', format: 'mcp-json', configPath: geminiConfigPath() },
+    { id: 'antigravity', label: 'Antigravity', format: 'mcp-json', configPath: antigravityConfigPath(), requireFileForPresent: true },
+  ];
+}
+
+/**
+ * 대상이 이 컴퓨터에 "있어 보이는가" — 설정 파일이나 그 부모 폴더가 존재하면 설치된 것으로 본다.
+ * 기본 `init`은 감지된 대상에만 써서 쓰지 않는 도구의 설정 파일을 만들지 않는다(임의 파일 생성 최소화).
+ */
+function isPresent(t: ClientTarget): boolean {
+  if (t.alwaysPresent) return true;
+  if (t.requireFileForPresent) return fs.existsSync(t.configPath);
+  return fs.existsSync(t.configPath) || fs.existsSync(path.dirname(t.configPath));
+}
+
+function pickTargets(which: string, forceAll: boolean): ClientTarget[] {
+  const all = allTargets();
+  if (which !== 'all') return all.filter((t) => t.id === which);
+  if (forceAll) return all;
+  return all.filter(isPresent);
+}
+
+/**
+ * MCP 서버 실행 방법.
+ *  - 기본(local): 현재 Node로 이 패키지의 bin을 직접 호출 → PATH/네트워크에 의존하지 않아
+ *    설치 파일 안에 동봉된 런타임에서도 그대로 동작.
+ *  - --npx: npm 레지스트리에서 받아 실행(개발자/공개 배포용). npx 캐시 경로는 휘발성이라
+ *    npx로 실행된 init은 자동으로 이 방식을 기본값으로 쓴다(절대경로가 곧 깨지는 것을 방지).
+ */
+function serverEntry(useNpx: boolean): ServerEntry {
+  if (useNpx) return { command: 'npx', args: ['-y', PKG, 'mcp'] };
+  return { command: process.execPath, args: [path.join(ROOT, 'bin', 'careermate.mjs'), 'mcp'] };
+}
+
+/** 이 프로세스가 `npx`를 통해 실행됐는지 추정(휘발성 캐시에서 돔). */
+function runningUnderNpx(): boolean {
+  const ua = process.env.npm_config_user_agent ?? '';
+  if (/\bnpx\b/.test(ua)) return true;
+  // npx 캐시 디렉터리 흔적(`_npx`)이 패키지 루트 경로에 있으면 npx 실행으로 본다.
+  return ROOT.split(path.sep).includes('_npx');
+}
+
+function readJsonObject(file: string): Record<string, unknown> {
+  try {
+    const raw = fs.readFileSync(file, 'utf8').trim();
+    if (!raw) return {};
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === 'object' ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+function backupFile(file: string): string | null {
+  // 타임스탬프를 붙여 이전 백업을 덮어쓰지 않는다(원본을 영구 보존).
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const dest = `${file}.careermate-backup-${stamp}`;
+  try {
+    fs.copyFileSync(file, dest);
+    return dest;
+  } catch {
+    return null;
+  }
+}
+
+/** Claude Desktop / Claude Code / Cursor 등 `mcpServers` JSON 형식. */
+function writeMcpJson(target: ClientTarget, server: ServerEntry): WriteResult {
+  const existed = fs.existsSync(target.configPath);
+  const json = existed ? readJsonObject(target.configPath) : {};
+  const servers =
+    json.mcpServers && typeof json.mcpServers === 'object'
+      ? (json.mcpServers as Record<string, unknown>)
+      : {};
+
+  const prev = servers[PKG];
+  const before = JSON.stringify(prev ?? null);
+  // 사용자가 careermate 항목에 직접 넣어둔 env(예: CAREERMATE_DATA_DIR)는 보존한다.
+  const next: Record<string, unknown> = {};
+  if (target.jsonType) next.type = 'stdio';
+  next.command = server.command;
+  next.args = server.args;
+  if (prev && typeof prev === 'object' && 'env' in (prev as Record<string, unknown>)) {
+    next.env = (prev as Record<string, unknown>).env;
+  }
+  servers[PKG] = next;
+  json.mcpServers = servers;
+  const changed = JSON.stringify(servers[PKG]) !== before;
+  const replacedExisting = prev != null && changed;
+
+  let backedUp: string | null = null;
+  if (existed && changed) backedUp = backupFile(target.configPath);
+  fs.mkdirSync(path.dirname(target.configPath), { recursive: true });
+  fs.writeFileSync(target.configPath, `${JSON.stringify(json, null, 2)}\n`, 'utf8');
+  return { changed, backedUp, replacedExisting };
+}
+
+/** TOML 기본 문자열로 직렬화(역슬래시/따옴표 이스케이프). JSON 문자열 규칙과 호환된다. */
+function tomlString(s: string): string {
+  return JSON.stringify(s);
+}
+
+/** Codex 설정의 careermate 블록(헤더 + command + args). 우리가 형태를 통제하므로 단순하다. */
+function codexBlock(server: ServerEntry): string {
+  const args = server.args.map(tomlString).join(', ');
+  return [`[mcp_servers.${PKG}]`, `command = ${tomlString(server.command)}`, `args = [${args}]`].join('\n');
+}
+
+/**
+ * 기존 config.toml에 careermate 블록을 안전하게 삽입/교체한다.
+ * - TOML 파서를 끌어오지 않고 텍스트로 처리하되, 우리가 만든 블록만 건드린다.
+ * - 블록 경계는 "다음 `[` 로 시작하는 테이블 헤더"까지 → `[mcp_servers.careermate.env]`
+ *   같은 사용자 하위 테이블은 보존된다.
+ */
+function upsertCodexBlock(raw: string, block: string): { next: string; found: boolean } {
+  const lines = raw.length ? raw.split(/\r?\n/) : [];
+  const headerRe = /^\s*\[\s*mcp_servers\s*\.\s*careermate\s*\]\s*$/;
+  const tableRe = /^\s*\[/;
+  const start = lines.findIndex((l) => headerRe.test(l));
+
+  if (start === -1) {
+    const trimmed = raw.replace(/\s+$/, '');
+    const next = trimmed.length ? `${trimmed}\n\n${block}\n` : `${block}\n`;
+    return { next, found: false };
+  }
+
+  let end = lines.length;
+  for (let j = start + 1; j < lines.length; j++) {
+    if (tableRe.test(lines[j])) {
+      end = j;
+      break;
+    }
+  }
+  const merged = [...lines.slice(0, start), ...block.split('\n'), ...lines.slice(end)];
+  let next = merged.join('\n');
+  if (!next.endsWith('\n')) next += '\n';
+  return { next, found: true };
+}
+
+/** Codex CLI: `~/.codex/config.toml` 의 `[mcp_servers.careermate]` 테이블. */
+function writeCodexToml(target: ClientTarget, server: ServerEntry): WriteResult {
+  const existed = fs.existsSync(target.configPath);
+  let raw = '';
+  if (existed) {
+    try {
+      raw = fs.readFileSync(target.configPath, 'utf8');
+    } catch {
+      raw = '';
+    }
+  }
+  const { next, found } = upsertCodexBlock(raw, codexBlock(server));
+  const changed = next.trim() !== raw.trim();
+
+  let backedUp: string | null = null;
+  if (existed && changed) backedUp = backupFile(target.configPath);
+  fs.mkdirSync(path.dirname(target.configPath), { recursive: true });
+  fs.writeFileSync(target.configPath, next, 'utf8');
+  return { changed, backedUp, replacedExisting: found && changed };
+}
+
+function writeTarget(target: ClientTarget, server: ServerEntry): WriteResult {
+  return target.format === 'codex-toml' ? writeCodexToml(target, server) : writeMcpJson(target, server);
+}
+
+function flagValue(argv: string[], name: string): string | undefined {
+  const i = argv.indexOf(name);
+  return i >= 0 && argv[i + 1] ? argv[i + 1] : undefined;
+}
+
+/** 셸에 그대로 붙여넣을 수 있는 명령 문자열(공백 포함 인자는 따옴표). */
+function shellJoin(parts: string[]): string {
+  return parts.map((p) => (/\s/.test(p) ? `"${p}"` : p)).join(' ');
+}
+
+function printConfigs(server: ServerEntry): void {
+  const cmd = [server.command, ...server.args];
+  console.log('CareerMate를 AI 클라이언트에 직접 연결하는 방법입니다.\n');
+
+  console.log('① Claude Desktop / Claude Code / Cursor / Gemini CLI / Antigravity — MCP 설정(mcpServers)에 추가:');
+  console.log(
+    JSON.stringify(
+      { mcpServers: { [PKG]: { type: 'stdio', command: server.command, args: server.args } } },
+      null,
+      2,
+    ),
+  );
+  console.log('\n  · Claude Code는 위 내용을 프로젝트 루트의 .mcp.json 으로 저장하면 됩니다.');
+  console.log('  · Gemini CLI는 ~/.gemini/settings.json, Antigravity는 ~/.gemini/(config|antigravity|antigravity-cli)/mcp_config.json 의 mcpServers에 같은 블록을 넣으세요(type 키는 없어도 됨).');
+  console.log(`  · 또는 명령으로:  ${shellJoin(['claude', 'mcp', 'add', '--scope', 'project', '--transport', 'stdio', PKG, '--', ...cmd])}`);
+
+  console.log('\n② Codex CLI — ~/.codex/config.toml 에 추가:');
+  console.log(codexBlock(server));
+  console.log(`\n  · 또는 명령으로:  ${shellJoin(['codex', 'mcp', 'add', PKG, '--', ...cmd])}`);
+}
+
+function main(): void {
+  const argv = process.argv.slice(2);
+  const useNpx = argv.includes('--npx') || runningUnderNpx();
+  const printOnly = argv.includes('--print');
+  const forceAll = argv.includes('--all-clients');
+  const which = flagValue(argv, '--client') ?? 'all';
+
+  const server = serverEntry(useNpx);
+
+  if (printOnly) {
+    printConfigs(server);
+    return;
+  }
+
+  console.log('CareerMate 설치를 시작합니다…\n');
+  const dataDir = ensureDataDir();
+  console.log(`• 데이터 폴더 준비됨: ${dataDir}`);
+
+  const targets = pickTargets(which, forceAll);
+  let connected = 0;
+  const connectedIds = new Set<string>();
+  for (const t of targets) {
+    try {
+      const { changed, backedUp, replacedExisting } = writeTarget(t, server);
+      connected += 1;
+      connectedIds.add(t.id);
+      console.log(
+        `• ${t.label} 연결 ${changed ? '완료' : '이미 최신'}: ${t.configPath}` +
+          (replacedExisting ? `\n    (기존 careermate 설정을 새 설정으로 교체했습니다)` : '') +
+          (backedUp ? `\n    (기존 설정 백업: ${backedUp})` : ''),
+      );
+    } catch (e) {
+      console.log(`• ${t.label} 연결 실패: ${e instanceof Error ? e.message : e}`);
+    }
+  }
+
+  if (connected === 0) {
+    console.log('\n연결할 AI 클라이언트를 찾지 못했습니다.');
+    console.log('특정 클라이언트를 지정하거나(--client claude|claude-code|codex|cursor|gemini|antigravity),');
+    console.log('설정을 직접 복사해 추가할 수 있어요:  careermate init --print');
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log('\n✅ 거의 끝났습니다. 다음만 해주세요:');
+  console.log('  1) 연결한 AI 클라이언트를 완전히 종료했다가 다시 켜기');
+  if (connectedIds.has('claude-code')) {
+    console.log('     (Claude Code는 프로젝트의 .mcp.json을 처음 띄울 때 1회 "승인"을 물어봅니다 — 승인해 주세요.)');
+  }
+  console.log('  2) AI에게: "get_onboarding_status 호출해서 연결됐는지 확인해줘"');
+  console.log('  3) 내 데이터 대시보드 열기:  careermate start');
+}
+
+main();

package/tsconfig.json

@@ -0,0 +1,32 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "lib": ["ES2023"],
+    "types": ["node"],
+    "strict": true,
+    "noUncheckedIndexedAccess": false,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "resolveJsonModule": true,
+    "forceConsistentCasingInFileNames": true,
+    "allowImportingTsExtensions": true,
+    "noEmit": true,
+    "baseUrl": ".",
+    "paths": {
+      "@careermate/shared": ["packages/shared/src/index.ts"],
+      "@careermate/db": ["packages/db/src/index.ts"],
+      "@careermate/core": ["packages/core/src/index.ts"],
+      "@careermate/mcp-tools": ["packages/mcp-tools/src/index.ts"],
+      "@careermate/exporters": ["packages/exporters/src/index.ts"],
+      "@careermate/parsers": ["packages/parsers/src/index.ts"],
+      "@careermate/prompts": ["packages/prompts/src/index.ts"],
+      "@careermate/workflows": ["packages/workflows/src/index.ts"],
+      "@careermate/knowledge": ["packages/knowledge/src/index.ts"]
+    }
+  },
+  "include": ["packages/**/*.ts", "apps/**/*.ts", "scripts/**/*.ts"],
+  "//exclude": "scripts/shots*.ts는 Playwright 브라우저 컨텍스트(window/document)·임시 시드용 마케팅 도구라 타입검사 제외(배포물 아님).",
+  "exclude": ["node_modules", "scripts/shots.ts", "scripts/shots-seed.ts"]
+}