careermate 0.1.0

package/scripts/build-dist.mjs

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+/**
+ * scripts/build-dist.mjs — 배포용 플레인 JS 번들 빌드 (esbuild).
+ *
+ * 개발은 그대로 tsx 무빌드로 돌리고, 배포(.mcpb / npm publish / 추후 독립 .exe)에서는
+ * tsx·tsconfig 경로별칭 런타임 의존성을 없애기 위해 두 진입점을 단일 ESM 파일로 번들한다.
+ *
+ *   dist/mcp.mjs     MCP stdio 서버 (Claude Desktop이 실행)
+ *   dist/web.mjs     로컬 대시보드 서버
+ *   dist/public/        대시보드 정적 자산 (apps/web/public 복사)
+ *   dist/install-page/  설치 안내 페이지 복사
+ *
+ * `define: __BUNDLED__=true` 로 런타임에서 번들 레이아웃을 인지(정적경로/대시보드 기동 분기).
+ * node: 내장 모듈(node:sqlite 등)은 external로 두므로 실행에는 Node ≥22.5가 필요(런타임은 동봉 대상).
+ */
+import esbuild from 'esbuild';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIST = path.join(ROOT, 'dist');
+
+async function main() {
+  console.log('CareerMate dist 번들 빌드(esbuild)…');
+  fs.rmSync(path.join(DIST, 'mcp.mjs'), { force: true });
+  fs.rmSync(path.join(DIST, 'web.mjs'), { force: true });
+
+  await esbuild.build({
+    absWorkingDir: ROOT,
+    entryPoints: {
+      mcp: 'apps/mcp/src/index.ts',
+      web: 'apps/web/src/index.ts',
+    },
+    outdir: 'dist',
+    outExtension: { '.js': '.mjs' },
+    bundle: true,
+    platform: 'node',
+    format: 'esm',
+    target: 'node22',
+    tsconfig: 'tsconfig.json',
+    define: { __BUNDLED__: 'true' },
+    // ESM 출력에서 CJS 의존성이 require/__dirname을 써도 동작하도록 shim 주입.
+    banner: {
+      js: "import { createRequire as __cr } from 'module'; const require = __cr(import.meta.url);",
+    },
+    logLevel: 'info',
+  });
+
+  // 정적 자산 복사 (번들에는 코드만 들어가므로 별도 복사).
+  fs.rmSync(path.join(DIST, 'public'), { recursive: true, force: true });
+  fs.rmSync(path.join(DIST, 'install-page'), { recursive: true, force: true });
+  fs.cpSync(path.join(ROOT, 'apps', 'web', 'public'), path.join(DIST, 'public'), { recursive: true });
+  fs.cpSync(path.join(ROOT, 'install-page'), path.join(DIST, 'install-page'), { recursive: true });
+
+  console.log('✅ dist 빌드 완료: dist/mcp.mjs, dist/web.mjs, dist/public, dist/install-page');
+}
+
+main().catch((err) => {
+  console.error('dist 빌드 실패:', err instanceof Error ? err.message : err);
+  process.exitCode = 1;
+});

package/scripts/build-mcpb.mjs

@@ -0,0 +1,70 @@
+#!/usr/bin/env node
+/**
+ * scripts/build-mcpb.mjs — Claude Desktop용 .mcpb(원클릭 설치 번들) 빌드.
+ *
+ * .mcpb = manifest.json + 실행 코드를 담은 zip. Claude Desktop이 Node를 내장 제공한다.
+ * 이전엔 소스+tsx+node_modules를 통째로 담았지만, 이제는 esbuild로 만든 플레인 JS 번들
+ * (dist/)만 담는다 → tsx/경로별칭 런타임 의존성 제거, 용량 대폭 축소.
+ *
+ * 절차:
+ *   1) node scripts/build-dist.mjs 로 dist/ 번들 생성(없거나 강제 시)
+ *   2) dist/mcb-stage/ 에 manifest.json + dist/ 만 복사
+ *   3) 공식 패커(@anthropic-ai/mcpb)로 dist/careermate.mcpb 생성
+ *
+ * 사용: node scripts/build-mcpb.mjs
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { spawnSync } from 'node:child_process';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const DIST = path.join(ROOT, 'dist');
+const STAGE = path.join(DIST, 'mcpb-stage');
+const OUT = path.join(DIST, 'careermate.mcpb');
+
+function run(cmd, args, opts = {}) {
+  const r = spawnSync(cmd, args, { stdio: 'inherit', shell: process.platform === 'win32', ...opts });
+  return r.status === 0;
+}
+
+function main() {
+  console.log('CareerMate .mcpb 빌드를 시작합니다…\n');
+
+  console.log('1) dist 번들 빌드…');
+  if (!run('node', [path.join(ROOT, 'scripts', 'build-dist.mjs')], { cwd: ROOT })) {
+    console.error('\n✗ dist 번들 빌드 실패.');
+    process.exitCode = 1;
+    return;
+  }
+
+  console.log('\n2) 번들 스테이징(manifest + dist)…');
+  fs.rmSync(STAGE, { recursive: true, force: true });
+  fs.mkdirSync(STAGE, { recursive: true });
+  fs.copyFileSync(path.join(ROOT, 'manifest.json'), path.join(STAGE, 'manifest.json'));
+  // dist/ 에서 산출물만 복사 (스테이지/번들 산출물 자기참조 제외).
+  fs.mkdirSync(path.join(STAGE, 'dist'), { recursive: true });
+  for (const name of ['mcp.mjs', 'web.mjs', 'public', 'install-page']) {
+    const src = path.join(DIST, name);
+    if (fs.existsSync(src)) fs.cpSync(src, path.join(STAGE, 'dist', name), { recursive: true });
+  }
+  for (const extra of ['README.md']) {
+    const src = path.join(ROOT, extra);
+    if (fs.existsSync(src)) fs.copyFileSync(src, path.join(STAGE, extra));
+  }
+
+  console.log('\n3) .mcpb 패키징…');
+  fs.rmSync(OUT, { force: true });
+  if (!run('npx', ['-y', '@anthropic-ai/mcpb', 'pack', STAGE, OUT])) {
+    console.error('\n✗ @anthropic-ai/mcpb 패커 실행 실패.');
+    console.error('  수동 패킹:  cd dist/mcpb-stage && npx @anthropic-ai/mcpb pack . ../careermate.mcpb');
+    process.exitCode = 1;
+    return;
+  }
+
+  const size = (fs.statSync(OUT).size / (1024 * 1024)).toFixed(1);
+  console.log(`\n✅ 완성: ${OUT} (${size} MB)`);
+  console.log('   배포: 이 파일을 GitHub Releases 등에 올리면 유저가 더블클릭만 하면 Claude Desktop에 설치됩니다.');
+}
+
+main();

package/scripts/doctor.ts

@@ -0,0 +1,81 @@
+/**
+ * `npm run doctor` — a friendly health check non-technical users can run when
+ * something looks off. Verifies the runtime, the data directory, the database,
+ * and reports whether the dashboard/MCP are wired up. Reads only; never mutates
+ * user data beyond ensuring the schema exists.
+ */
+import fs from 'node:fs';
+import { getDataDir, getDbPath, getDb, readRuntimeInfo, isProcessAlive } from '@careermate/db';
+import {
+  profileRepo, experienceRepo, projectRepo, skillRepo, documentRepo,
+  coverLetterRepo, jobRepo, applicationRepo, interviewRepo,
+} from '@careermate/db';
+import { TOOLS } from '@careermate/mcp-tools';
+
+const ok = (s: string) => console.log(`  ✅ ${s}`);
+const warn = (s: string) => console.log(`  ⚠️  ${s}`);
+const info = (s: string) => console.log(`  ·  ${s}`);
+
+function checkNode(): boolean {
+  const [maj, min] = process.versions.node.split('.').map(Number);
+  const good = maj > 22 || (maj === 22 && min >= 5);
+  if (good) ok(`Node.js ${process.version} (node:sqlite 내장 사용 — 별도 빌드 불필요)`);
+  else warn(`Node.js ${process.version} — 22.5 이상이 필요합니다. 업데이트를 권장합니다.`);
+  return good;
+}
+
+function main(): void {
+  console.log('\nCareerMate 상태 점검\n' + '─'.repeat(40));
+
+  const nodeOk = checkNode();
+
+  // Data directory
+  const dir = getDataDir();
+  try {
+    fs.accessSync(dir, fs.constants.W_OK);
+    ok(`데이터 폴더 쓰기 가능: ${dir}`);
+  } catch {
+    warn(`데이터 폴더에 쓸 수 없습니다: ${dir}`);
+  }
+
+  // Database
+  let dbOk = false;
+  try {
+    const db = getDb();
+    const v = db.prepare(`SELECT value FROM _meta WHERE key='schema_version'`).get() as { value: string } | undefined;
+    ok(`데이터베이스 정상 (스키마 v${v?.value ?? '?'}) — ${getDbPath()}`);
+    dbOk = true;
+  } catch (e) {
+    warn(`데이터베이스 열기 실패: ${e instanceof Error ? e.message : e}`);
+  }
+
+  // Contents
+  if (dbOk) {
+    const counts = {
+      프로필: profileRepo.get()?.name ? 1 : 0,
+      경력: experienceRepo.list().length,
+      프로젝트: projectRepo.list().length,
+      기술: skillRepo.list().length,
+      문서: documentRepo.list().length,
+      자기소개서: coverLetterRepo.list().length,
+      공고: jobRepo.list().length,
+      지원: applicationRepo.list().length,
+      면접준비: interviewRepo.list().length,
+    };
+    info('저장된 데이터: ' + Object.entries(counts).map(([k, v]) => `${k} ${v}`).join(' · '));
+  }
+
+  // MCP tools
+  ok(`MCP 도구 ${TOOLS.length}개 등록됨`);
+
+  // Dashboard running?
+  const rt = readRuntimeInfo();
+  if (rt && isProcessAlive(rt.pid)) ok(`대시보드 실행 중: ${rt.url}`);
+  else info('대시보드가 실행 중이 아닙니다. `npm start` 로 실행하세요.');
+
+  console.log('─'.repeat(40));
+  console.log(nodeOk && dbOk ? '핵심 점검 통과 ✅\n' : '일부 항목을 확인해 주세요 ⚠️\n');
+  process.exit(nodeOk && dbOk ? 0 : 1);
+}
+
+main();

package/scripts/init.ts

@@ -0,0 +1,342 @@
+/**
+ * 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)
+ *   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;
+}
+
+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');
+}
+
+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() },
+  ];
+}
+
+/**
+ * 대상이 이 컴퓨터에 "있어 보이는가" — 설정 파일이나 그 부모 폴더가 존재하면 설치된 것으로 본다.
+ * 기본 `init`은 감지된 대상에만 써서 쓰지 않는 도구의 설정 파일을 만들지 않는다(임의 파일 생성 최소화).
+ */
+function isPresent(t: ClientTarget): boolean {
+  if (t.alwaysPresent) return true;
+  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 — 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(`  · 또는 명령으로:  ${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),');
+    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/scripts/mcp-probe.ts

@@ -0,0 +1,55 @@
+/**
+ * One-shot MCP probe used by `npm test`. Connects to the CareerMate MCP server
+ * over real stdio, exercises a few tools, and prints a single JSON line of
+ * results to stdout. The parent test invokes this via spawnSync (which fully
+ * reaps the child), so the parent's own exit code stays clean on Windows where
+ * a long-lived tsx child otherwise corrupts it.
+ *
+ * Inherits CAREERMATE_DATA_DIR from the parent so it hits the same database.
+ */
+import path from 'node:path';
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+
+const repoRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname.replace(/^\/([A-Za-z]:)/, '$1')), '..');
+
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/mcp/src/index.ts'],
+  env: { ...process.env } as Record<string, string>,
+  cwd: repoRoot,
+  stderr: 'ignore',
+});
+
+const client = new Client({ name: 'mcp-probe', version: '1.0.0' });
+const parse = (r: any) => {
+  const j = r.content?.find((c: any) => typeof c.text === 'string' && c.text.startsWith('```json'));
+  return j ? JSON.parse(j.text.replace(/```json\n|\n```/g, '')) : r.structuredContent;
+};
+
+try {
+  await client.connect(transport);
+  const tools = (await client.listTools()).tools;
+  const profile = parse(await client.callTool({ name: 'get_profile', arguments: {} }));
+  const job = parse(await client.callTool({ name: 'save_job_posting', arguments: { company: '쿠팡', position: '데이터 엔지니어' } }));
+  const out = {
+    ok: true,
+    toolCount: tools.length,
+    hasContext: tools.some((t) => t.name === 'get_application_context'),
+    profileName: profile?.name ?? null,
+    profileHeadline: profile?.headline ?? null,
+    jobId: job?.id ?? null,
+  };
+  process.stdout.write('RESULT ' + JSON.stringify(out) + '\n');
+  await client.close();
+  const pid = (transport as unknown as { _process?: { pid?: number } })._process?.pid;
+  if (pid && process.platform === 'win32') {
+    const { spawnSync } = await import('node:child_process');
+    spawnSync('taskkill', ['/F', '/T', '/PID', String(pid)], { stdio: 'ignore' });
+  }
+} catch (e) {
+  process.stdout.write('RESULT ' + JSON.stringify({ ok: false, error: e instanceof Error ? e.message : String(e) }) + '\n');
+}
+// Exit code intentionally ignored by the parent (it reads stdout); may be
+// corrupted by the tsx child teardown on Windows, which is fine here.
+setTimeout(() => process.exit(0), 300).unref();

package/scripts/migrate.ts

@@ -0,0 +1,6 @@
+/** Initialize/upgrade the local database. Safe to run repeatedly. */
+import { getDb, getDbPath } from '@careermate/db';
+
+getDb(); // opens + migrates
+console.log(`✅ CareerMate 데이터베이스 준비 완료`);
+console.log(`   위치: ${getDbPath()}`);

package/scripts/run.mjs

@@ -0,0 +1,33 @@
+// Plain-Node test runner (no tsx). Runs a tsx test script as a child and derives
+// the real pass/fail from a stdout verdict sentinel.
+//
+// Why: on Windows, a tsx module that uses top-level `await` and then calls
+// process.exit() exits with a corrupted code (the esbuild loader is mid-flight).
+// This runner is plain Node, so ITS exit code is reliable; it ignores the
+// child's mangled code and trusts the printed verdict instead.
+import { spawnSync } from 'node:child_process';
+import process from 'node:process';
+
+const [, , scriptPath, sentinel] = process.argv;
+if (!scriptPath || !sentinel) {
+  console.error('usage: node scripts/run.mjs <script.ts> "<PASS SENTINEL>"');
+  process.exit(2);
+}
+
+const res = spawnSync(process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', scriptPath], {
+  encoding: 'utf8',
+  env: process.env,
+  timeout: 180000,
+});
+
+// Surface the child's output (minus the noisy Windows libuv teardown lines).
+const clean = (s) =>
+  (s || '')
+    .split('\n')
+    .filter((l) => !/Assertion failed|async\.c|UV_HANDLE|^Node\.js v\d/.test(l))
+    .join('\n');
+process.stdout.write(clean(res.stdout));
+if (res.stderr) process.stderr.write(clean(res.stderr));
+
+const passed = (res.stdout || '').includes(sentinel);
+process.exit(passed ? 0 : 1);