careermate 0.1.0 → 0.1.1

package/packages/db/src/repositories.ts

@@ -6,6 +6,7 @@
 import {
   newId,
   now,
+  assertStatusTransition,
   type ProfileInput,
   type ProfileRecord,
   type ExperienceInput,
@@ -33,7 +34,7 @@ import {
   type ContentSource,
   type DocumentKind,
 } from '@careermate/shared';
-import { getDb, toJson, fromJson, toBit, fromBit } from './connection.ts';
+import { getDb, tx, toJson, fromJson, toBit, fromBit } from './connection.ts';
 
 const PROFILE_ID = 'profile-singleton';
 
@@ -364,34 +365,40 @@ export const documentRepo = {
     const ts = now();
     const id = newId('doc_');
     const db = getDb();
-    if (input.is_primary) {
-      db.prepare(`UPDATE documents SET is_primary=0 WHERE kind=?`).run(input.kind);
-    }
-    db.prepare(
-      `INSERT INTO documents (id,kind,title,content,source,is_primary,tags,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?)`,
-    ).run(
-      id,
-      input.kind,
-      input.title,
-      input.content ?? '',
-      (input.source ?? 'manual') as ContentSource,
-      toBit(input.is_primary),
-      toJson(input.tags ?? []),
-      ts,
-      ts,
-    );
-    return this.get(id)!;
+    // Demoting the previous primary + inserting the new doc must be atomic.
+    return tx(() => {
+      if (input.is_primary) {
+        db.prepare(`UPDATE documents SET is_primary=0 WHERE kind=?`).run(input.kind);
+      }
+      db.prepare(
+        `INSERT INTO documents (id,kind,title,content,source,is_primary,tags,created_at,updated_at) VALUES (?,?,?,?,?,?,?,?,?)`,
+      ).run(
+        id,
+        input.kind,
+        input.title,
+        input.content ?? '',
+        (input.source ?? 'manual') as ContentSource,
+        toBit(input.is_primary),
+        toJson(input.tags ?? []),
+        ts,
+        ts,
+      );
+      return this.get(id)!;
+    });
   },
   update(id: string, input: Partial<DocumentInput>): DocumentRecord | null {
     const cur = this.get(id);
     if (!cur) return null;
     const db = getDb();
     const m = { ...cur, ...input } as DocumentRecord;
-    if (input.is_primary) db.prepare(`UPDATE documents SET is_primary=0 WHERE kind=?`).run(m.kind);
-    db.prepare(
-      `UPDATE documents SET kind=?,title=?,content=?,source=?,is_primary=?,tags=?,updated_at=? WHERE id=?`,
-    ).run(m.kind, m.title, m.content, m.source, toBit(m.is_primary), toJson(m.tags), now(), id);
-    return this.get(id);
+    // Demoting the previous primary + updating this doc must be atomic.
+    return tx(() => {
+      if (input.is_primary) db.prepare(`UPDATE documents SET is_primary=0 WHERE kind=?`).run(m.kind);
+      db.prepare(
+        `UPDATE documents SET kind=?,title=?,content=?,source=?,is_primary=?,tags=?,updated_at=? WHERE id=?`,
+      ).run(m.kind, m.title, m.content, m.source, toBit(m.is_primary), toJson(m.tags), now(), id);
+      return this.get(id);
+    });
   },
   remove(id: string): boolean {
     return getDb().prepare(`DELETE FROM documents WHERE id=?`).run(id).changes > 0;
@@ -453,11 +460,13 @@ export const coverLetterRepo = {
     const ts = now();
     const id = newId('cl_');
     const db = getDb();
-    if (opts.is_primary) db.prepare(`UPDATE cover_letters SET is_primary=0`).run();
-    db.prepare(
-      `INSERT INTO cover_letters (id,title,job_id,is_primary,current_version_id,created_at,updated_at) VALUES (?,?,?,?,?,?,?)`,
-    ).run(id, opts.title, opts.job_id ?? null, toBit(opts.is_primary), null, ts, ts);
-    return this.get(id)!;
+    return tx(() => {
+      if (opts.is_primary) db.prepare(`UPDATE cover_letters SET is_primary=0`).run();
+      db.prepare(
+        `INSERT INTO cover_letters (id,title,job_id,is_primary,current_version_id,created_at,updated_at) VALUES (?,?,?,?,?,?,?)`,
+      ).run(id, opts.title, opts.job_id ?? null, toBit(opts.is_primary), null, ts, ts);
+      return this.get(id)!;
+    });
   },
   /** Append a new version. Creates the cover letter if cover_letter_id is omitted. */
   addVersion(opts: {
@@ -470,32 +479,36 @@ export const coverLetterRepo = {
     set_current?: boolean;
   }): { coverLetter: CoverLetterRecord; version: CoverLetterVersionRecord } {
     const db = getDb();
-    let clId = opts.cover_letter_id;
-    if (!clId) {
-      const cl = this.create({ title: opts.title ?? '자기소개서', job_id: opts.job_id ?? null });
-      clId = cl.id;
-    }
-    const maxRow = db
-      .prepare(`SELECT MAX(version_no) AS m FROM cover_letter_versions WHERE cover_letter_id=?`)
-      .get(clId) as { m: number | null };
-    const versionNo = (maxRow.m ?? 0) + 1;
-    const vid = newId('clv_');
-    const ts = now();
-    db.prepare(
-      `INSERT INTO cover_letter_versions (id,cover_letter_id,version_no,content,note,source,created_at) VALUES (?,?,?,?,?,?,?)`,
-    ).run(vid, clId, versionNo, opts.content, opts.note ?? null, opts.source ?? 'ai', ts);
-
-    const setCurrent = opts.set_current !== false;
-    if (setCurrent) {
-      db.prepare(`UPDATE cover_letters SET current_version_id=?, updated_at=? WHERE id=?`).run(vid, ts, clId);
-    } else {
-      db.prepare(`UPDATE cover_letters SET updated_at=? WHERE id=?`).run(ts, clId);
-    }
-    if (opts.title) db.prepare(`UPDATE cover_letters SET title=? WHERE id=?`).run(opts.title, clId);
-    if (opts.job_id !== undefined)
-      db.prepare(`UPDATE cover_letters SET job_id=? WHERE id=?`).run(opts.job_id, clId);
-
-    return { coverLetter: this.get(clId)!, version: mapVersion(db.prepare(`SELECT * FROM cover_letter_versions WHERE id=?`).get(vid)) };
+    // Create-if-needed + version INSERT + current_version_id/title/job_id UPDATEs
+    // must all commit together, or mapCoverLetter's "current" lookup goes stale.
+    return tx(() => {
+      let clId = opts.cover_letter_id;
+      if (!clId) {
+        const cl = this.create({ title: opts.title ?? '자기소개서', job_id: opts.job_id ?? null });
+        clId = cl.id;
+      }
+      const maxRow = db
+        .prepare(`SELECT MAX(version_no) AS m FROM cover_letter_versions WHERE cover_letter_id=?`)
+        .get(clId) as { m: number | null };
+      const versionNo = (maxRow.m ?? 0) + 1;
+      const vid = newId('clv_');
+      const ts = now();
+      db.prepare(
+        `INSERT INTO cover_letter_versions (id,cover_letter_id,version_no,content,note,source,created_at) VALUES (?,?,?,?,?,?,?)`,
+      ).run(vid, clId, versionNo, opts.content, opts.note ?? null, opts.source ?? 'ai', ts);
+
+      const setCurrent = opts.set_current !== false;
+      if (setCurrent) {
+        db.prepare(`UPDATE cover_letters SET current_version_id=?, updated_at=? WHERE id=?`).run(vid, ts, clId);
+      } else {
+        db.prepare(`UPDATE cover_letters SET updated_at=? WHERE id=?`).run(ts, clId);
+      }
+      if (opts.title) db.prepare(`UPDATE cover_letters SET title=? WHERE id=?`).run(opts.title, clId);
+      if (opts.job_id !== undefined)
+        db.prepare(`UPDATE cover_letters SET job_id=? WHERE id=?`).run(opts.job_id, clId);
+
+      return { coverLetter: this.get(clId)!, version: mapVersion(db.prepare(`SELECT * FROM cover_letter_versions WHERE id=?`).get(vid)) };
+    });
   },
   setCurrentVersion(coverLetterId: string, versionId: string): CoverLetterRecord | null {
     getDb()
@@ -505,14 +518,18 @@ export const coverLetterRepo = {
   },
   setPrimary(id: string): CoverLetterRecord | null {
     const db = getDb();
-    db.prepare(`UPDATE cover_letters SET is_primary=0`).run();
-    db.prepare(`UPDATE cover_letters SET is_primary=1, updated_at=? WHERE id=?`).run(now(), id);
-    return this.get(id);
+    return tx(() => {
+      db.prepare(`UPDATE cover_letters SET is_primary=0`).run();
+      db.prepare(`UPDATE cover_letters SET is_primary=1, updated_at=? WHERE id=?`).run(now(), id);
+      return this.get(id);
+    });
   },
   remove(id: string): boolean {
     const db = getDb();
-    db.prepare(`DELETE FROM cover_letter_versions WHERE cover_letter_id=?`).run(id);
-    return db.prepare(`DELETE FROM cover_letters WHERE id=?`).run(id).changes > 0;
+    return tx(() => {
+      db.prepare(`DELETE FROM cover_letter_versions WHERE cover_letter_id=?`).run(id);
+      return db.prepare(`DELETE FROM cover_letters WHERE id=?`).run(id).changes > 0;
+    });
   },
 };
 
@@ -603,10 +620,13 @@ export const jobRepo = {
   },
   remove(id: string): boolean {
     const db = getDb();
-    db.prepare(`DELETE FROM fit_analyses WHERE job_id=?`).run(id);
-    db.prepare(`DELETE FROM applications WHERE job_id=?`).run(id);
-    db.prepare(`DELETE FROM interview_preps WHERE job_id=?`).run(id);
-    return db.prepare(`DELETE FROM jobs WHERE id=?`).run(id).changes > 0;
+    // Delete the job and all its dependent rows atomically (no orphans on failure).
+    return tx(() => {
+      db.prepare(`DELETE FROM fit_analyses WHERE job_id=?`).run(id);
+      db.prepare(`DELETE FROM applications WHERE job_id=?`).run(id);
+      db.prepare(`DELETE FROM interview_preps WHERE job_id=?`).run(id);
+      return db.prepare(`DELETE FROM jobs WHERE id=?`).run(id).changes > 0;
+    });
   },
 };
 
@@ -727,6 +747,8 @@ export const applicationRepo = {
   },
   upsert(input: ApplicationInput): ApplicationRecord {
     const app = this.ensure(input.job_id, input.status ?? 'draft');
+    // A status change through upsert must respect the same lifecycle gate as setStatus.
+    if (input.status && input.status !== app.status) assertStatusTransition(app.status, input.status);
     const m = { ...app, ...input } as ApplicationRecord;
     getDb()
       .prepare(
@@ -737,6 +759,7 @@ export const applicationRepo = {
   },
   setStatus(jobId: string, status: ApplicationStatus, note?: string): ApplicationRecord {
     const app = this.ensure(jobId);
+    assertStatusTransition(app.status, status);
     const appliedAt =
       status === 'applied' && !app.applied_at ? now() : app.applied_at;
     const notes = note ? [app.notes, note].filter(Boolean).join('\n') : app.notes;
@@ -826,3 +849,26 @@ export const activityRepo = {
       .all(limit) as ActivityRecord[];
   },
 };
+
+/* ------------------------------------------------------------------ Counts */
+
+/**
+ * Entity counts for the dashboard/Settings/health endpoint. Uses COUNT(*) per
+ * table instead of loading every row (the /api/health call hits this), and keeps
+ * the raw SQL in the db layer. Table names are hardcoded constants, not input.
+ */
+export function getEntityCounts(): Record<string, number> {
+  const db = getDb();
+  const c = (t: string): number => (db.prepare(`SELECT COUNT(*) AS n FROM ${t}`).get() as { n: number }).n;
+  return {
+    profile: c('profile'),
+    experiences: c('experiences'),
+    projects: c('projects'),
+    skills: c('skills'),
+    documents: c('documents'),
+    cover_letters: c('cover_letters'),
+    jobs: c('jobs'),
+    applications: c('applications'),
+    interview_preps: c('interview_preps'),
+  };
+}

package/packages/db/src/schema.ts

@@ -165,6 +165,124 @@ export const MIGRATIONS: string[] = [
   CREATE INDEX IF NOT EXISTS idx_cl_job ON cover_letters(job_id);
   CREATE INDEX IF NOT EXISTS idx_activities_created ON activities(created_at DESC);
   `,
+
+  // v2 — add foreign keys so PRAGMA foreign_keys=ON is actually enforced.
+  //
+  // SQLite cannot ALTER a table to add constraints, so each table that needs an
+  // FK is recreated (create new → copy → drop old → rename). The copy also
+  // repairs pre-existing orphans: child rows whose parent is gone are dropped
+  // (CASCADE intent) and dangling optional refs are nulled (SET NULL intent), so
+  // a subsequent PRAGMA foreign_key_check stays clean. FKs are disabled for the
+  // rebuild and the whole thing runs in one transaction (auto-rolled-back if the
+  // process dies mid-migration, since the version bump happens only afterwards).
+  `
+  PRAGMA foreign_keys=OFF;
+  BEGIN;
+
+  -- cover_letters.job_id -> jobs(id) ON DELETE SET NULL
+  CREATE TABLE cover_letters_new (
+    id TEXT PRIMARY KEY,
+    title TEXT NOT NULL,
+    job_id TEXT REFERENCES jobs(id) ON DELETE SET NULL,
+    is_primary INTEGER NOT NULL DEFAULT 0,
+    current_version_id TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  INSERT INTO cover_letters_new (id,title,job_id,is_primary,current_version_id,created_at,updated_at)
+    SELECT id,title,
+           CASE WHEN job_id IN (SELECT id FROM jobs) THEN job_id ELSE NULL END,
+           is_primary,current_version_id,created_at,updated_at
+    FROM cover_letters;
+  DROP TABLE cover_letters;
+  ALTER TABLE cover_letters_new RENAME TO cover_letters;
+
+  -- cover_letter_versions.cover_letter_id -> cover_letters(id) ON DELETE CASCADE
+  CREATE TABLE cover_letter_versions_new (
+    id TEXT PRIMARY KEY,
+    cover_letter_id TEXT NOT NULL REFERENCES cover_letters(id) ON DELETE CASCADE,
+    version_no INTEGER NOT NULL,
+    content TEXT NOT NULL,
+    note TEXT,
+    source TEXT NOT NULL DEFAULT 'ai',
+    created_at TEXT NOT NULL
+  );
+  INSERT INTO cover_letter_versions_new (id,cover_letter_id,version_no,content,note,source,created_at)
+    SELECT id,cover_letter_id,version_no,content,note,source,created_at
+    FROM cover_letter_versions
+    WHERE cover_letter_id IN (SELECT id FROM cover_letters);
+  DROP TABLE cover_letter_versions;
+  ALTER TABLE cover_letter_versions_new RENAME TO cover_letter_versions;
+
+  -- fit_analyses.job_id -> jobs(id) ON DELETE CASCADE
+  CREATE TABLE fit_analyses_new (
+    id TEXT PRIMARY KEY,
+    job_id TEXT NOT NULL REFERENCES jobs(id) ON DELETE CASCADE,
+    score REAL,
+    summary TEXT,
+    strengths TEXT NOT NULL DEFAULT '[]',
+    gaps TEXT NOT NULL DEFAULT '[]',
+    matched_keywords TEXT NOT NULL DEFAULT '[]',
+    missing_keywords TEXT NOT NULL DEFAULT '[]',
+    recommendations TEXT NOT NULL DEFAULT '[]',
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  INSERT INTO fit_analyses_new (id,job_id,score,summary,strengths,gaps,matched_keywords,missing_keywords,recommendations,created_at,updated_at)
+    SELECT id,job_id,score,summary,strengths,gaps,matched_keywords,missing_keywords,recommendations,created_at,updated_at
+    FROM fit_analyses
+    WHERE job_id IN (SELECT id FROM jobs);
+  DROP TABLE fit_analyses;
+  ALTER TABLE fit_analyses_new RENAME TO fit_analyses;
+
+  -- applications: job_id CASCADE, resume_id/cover_letter_id SET NULL
+  CREATE TABLE applications_new (
+    id TEXT PRIMARY KEY,
+    job_id TEXT NOT NULL UNIQUE REFERENCES jobs(id) ON DELETE CASCADE,
+    status TEXT NOT NULL DEFAULT 'draft',
+    resume_id TEXT REFERENCES documents(id) ON DELETE SET NULL,
+    cover_letter_id TEXT REFERENCES cover_letters(id) ON DELETE SET NULL,
+    applied_at TEXT,
+    notes TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  INSERT INTO applications_new (id,job_id,status,resume_id,cover_letter_id,applied_at,notes,created_at,updated_at)
+    SELECT id,job_id,status,
+           CASE WHEN resume_id IN (SELECT id FROM documents) THEN resume_id ELSE NULL END,
+           CASE WHEN cover_letter_id IN (SELECT id FROM cover_letters) THEN cover_letter_id ELSE NULL END,
+           applied_at,notes,created_at,updated_at
+    FROM applications
+    WHERE job_id IN (SELECT id FROM jobs);
+  DROP TABLE applications;
+  ALTER TABLE applications_new RENAME TO applications;
+
+  -- interview_preps.job_id -> jobs(id) ON DELETE CASCADE
+  CREATE TABLE interview_preps_new (
+    id TEXT PRIMARY KEY,
+    job_id TEXT NOT NULL UNIQUE REFERENCES jobs(id) ON DELETE CASCADE,
+    questions TEXT NOT NULL DEFAULT '[]',
+    star_guides TEXT NOT NULL DEFAULT '[]',
+    self_introduction TEXT,
+    notes TEXT,
+    created_at TEXT NOT NULL,
+    updated_at TEXT NOT NULL
+  );
+  INSERT INTO interview_preps_new (id,job_id,questions,star_guides,self_introduction,notes,created_at,updated_at)
+    SELECT id,job_id,questions,star_guides,self_introduction,notes,created_at,updated_at
+    FROM interview_preps
+    WHERE job_id IN (SELECT id FROM jobs);
+  DROP TABLE interview_preps;
+  ALTER TABLE interview_preps_new RENAME TO interview_preps;
+
+  -- Recreate indexes dropped along with their tables.
+  CREATE INDEX IF NOT EXISTS idx_fit_job ON fit_analyses(job_id);
+  CREATE INDEX IF NOT EXISTS idx_clv_letter ON cover_letter_versions(cover_letter_id);
+  CREATE INDEX IF NOT EXISTS idx_cl_job ON cover_letters(job_id);
+
+  COMMIT;
+  PRAGMA foreign_keys=ON;
+  `,
 ];
 
 export function migrate(db: DatabaseSync): { from: number; to: number } {

package/packages/exporters/src/html.ts

@@ -18,20 +18,17 @@ export function escapeHtml(input: string | null | undefined): string {
     .replace(/'/g, ''');
 }
 
-/** Heuristic: does this string already look like an HTML fragment? */
-function looksLikeHtml(s: string): boolean {
-  return /<\/?(p|h[1-6]|ul|ol|li|div|section|article|br|hr|strong|em|a|table)\b/i.test(s);
-}
-
 /**
- * Wrap a body (markdown OR ready HTML) in a complete, print-optimized HTML
- * document. If `body` already looks like HTML it is used verbatim; otherwise it
- * is rendered through the tiny markdown renderer.
+ * Wrap a markdown body in a complete, print-optimized HTML document.
+ *
+ * The body is ALWAYS rendered through {@link markdownToHtml}, which HTML-escapes
+ * its input before re-introducing only its own safe tags. Every exporter feeds
+ * this markdown it built itself, so there is no need to accept raw HTML — and
+ * accepting it would let user content (e.g. a cover-letter body containing
+ * `<img onerror=...>`) execute when the exported file is opened in a browser.
  */
-export function toPrintableHtml(title: string, bodyMarkdownOrHtml: string): string {
-  const body = looksLikeHtml(bodyMarkdownOrHtml)
-    ? bodyMarkdownOrHtml
-    : markdownToHtml(bodyMarkdownOrHtml);
+export function toPrintableHtml(title: string, bodyMarkdown: string): string {
+  const body = markdownToHtml(bodyMarkdown);
   const safeTitle = escapeHtml(title);
 
   return `<!doctype html>

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

@@ -15,6 +15,9 @@ import fs from 'node:fs';
 import path from 'node:path';
 import {
   ProfileInputSchema,
+  ExperienceInputSchema,
+  ProjectInputSchema,
+  SkillInputSchema,
   JobInputSchema,
   FitAnalysisInputSchema,
   CoverLetterVersionInputSchema,
@@ -26,6 +29,9 @@ import {
 } from '@careermate/shared';
 import {
   profileRepo,
+  experienceRepo,
+  projectRepo,
+  skillRepo,
   documentRepo,
   coverLetterRepo,
   jobRepo,
@@ -40,6 +46,9 @@ import {
   getApplicationContext,
   saveProfile,
   addResume,
+  addExperience,
+  addProject,
+  addSkill,
   saveJobPosting,
   saveFitAnalysis,
   saveCoverLetterVersion,
@@ -156,6 +165,78 @@ export const TOOLS: ToolDef[] = [
     },
   },
 
+  /* ----------------------------------------------------------- experiences */
+  {
+    name: 'add_experience',
+    title: '경력 추가',
+    description:
+      '구조화된 경력(직장 단위)을 별도 항목으로 저장합니다. 이력서 본문(add_resume)과 달리, 회사·직무·기간·성과를 필드로 나눠 저장해 적합도 분석/자소서 작성 시 정밀하게 활용됩니다. company는 필수이며, achievements에는 정량 지표가 담긴 성과를, tech에는 사용 기술을 배열로 넣으세요. 온보딩 완성도(get_onboarding_status)의 has_experience를 채우려면 이 도구로 1건 이상 추가해야 합니다.',
+    inputSchema: ExperienceInputSchema.shape,
+    handler: (args) => {
+      const exp = addExperience(args);
+      return ok(`경력 '${exp.company}${exp.role ? ` · ${exp.role}` : ''}'을(를) 추가했습니다.`, exp);
+    },
+  },
+  {
+    name: 'get_experiences',
+    title: '경력 목록 조회',
+    description: '저장된 경력을 시간 역순으로 조회합니다. (전체 맥락이 필요하면 get_application_context를 쓰세요.)',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const list = experienceRepo.list();
+      return ok(`경력 ${list.length}건`, list);
+    },
+  },
+
+  /* -------------------------------------------------------------- projects */
+  {
+    name: 'add_project',
+    title: '프로젝트 추가',
+    description:
+      '대표 프로젝트를 별도 항목으로 저장합니다. name은 필수이며, highlights(핵심 성과)와 tech(사용 기술)를 배열로 넣으면 자소서·면접 준비에서 근거로 활용됩니다. url에 결과물 링크를 넣을 수 있습니다.',
+    inputSchema: ProjectInputSchema.shape,
+    handler: (args) => {
+      const prj = addProject(args);
+      return ok(`프로젝트 '${prj.name}'을(를) 추가했습니다.`, prj);
+    },
+  },
+  {
+    name: 'get_projects',
+    title: '프로젝트 목록 조회',
+    description: '저장된 프로젝트를 조회합니다. (전체 맥락이 필요하면 get_application_context를 쓰세요.)',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const list = projectRepo.list();
+      return ok(`프로젝트 ${list.length}건`, list);
+    },
+  },
+
+  /* ---------------------------------------------------------------- skills */
+  {
+    name: 'add_skill',
+    title: '기술스택 추가',
+    description:
+      '보유 기술스택을 별도 항목으로 저장합니다. name은 필수이며, category(언어/프레임워크/툴/소프트스킬 등)·level·years로 숙련도를 함께 기록하면 공고 키워드 매칭이 정확해집니다. 온보딩 완성도의 has_skills를 채우려면 이 도구로 1건 이상 추가해야 합니다. 여러 개면 도구를 반복 호출하세요.',
+    inputSchema: SkillInputSchema.shape,
+    handler: (args) => {
+      const skill = addSkill(args);
+      return ok(`기술 '${skill.name}'을(를) 추가했습니다.`, skill);
+    },
+  },
+  {
+    name: 'get_skills',
+    title: '기술스택 목록 조회',
+    description: '저장된 기술스택을 조회합니다. (전체 맥락이 필요하면 get_application_context를 쓰세요.)',
+    inputSchema: {},
+    readOnly: true,
+    handler: () => {
+      const list = skillRepo.list();
+      return ok(`기술 ${list.length}건`, list);
+    },
+  },
+
   /* ---------------------------------------------------------- cover letters */
   {
     name: 'add_cover_letter',

package/packages/shared/src/enums.ts

@@ -51,6 +51,45 @@ export const INTERVIEW_UNLOCK_STATUSES: ApplicationStatus[] = [
   'final_passed',
 ];
 
+/**
+ * Allowed application-status transitions (server-enforced lifecycle).
+ *
+ * Design note: CareerMate lets the user's AI record where an application *really*
+ * is, so `draft` (the initial, untracked state) may jump to ANY real-world stage.
+ * Once an application is being tracked, it may move forward, be corrected
+ * backward among active stages, be parked (`on_hold`) or closed (`rejected`) from
+ * anywhere, and be reopened/resumed from those terminal states. The one move we
+ * forbid is regressing an *active* application back to `draft` ("untracked"),
+ * which would silently drop its lifecycle history. The hard spec invariant
+ * (interview prep requires `document_passed`+) is enforced separately at the
+ * service layer via {@link INTERVIEW_UNLOCK_STATUSES}.
+ */
+export const ALLOWED_STATUS_TRANSITIONS: Record<ApplicationStatus, ApplicationStatus[]> = {
+  draft: ['planned', 'applied', 'document_passed', 'interview', 'final_passed', 'rejected', 'on_hold'],
+  planned: ['applied', 'document_passed', 'interview', 'final_passed', 'rejected', 'on_hold'],
+  applied: ['planned', 'document_passed', 'interview', 'final_passed', 'rejected', 'on_hold'],
+  document_passed: ['planned', 'applied', 'interview', 'final_passed', 'rejected', 'on_hold'],
+  interview: ['planned', 'applied', 'document_passed', 'final_passed', 'rejected', 'on_hold'],
+  final_passed: ['document_passed', 'interview', 'rejected', 'on_hold'],
+  rejected: ['draft', 'planned', 'applied', 'document_passed', 'interview', 'final_passed', 'on_hold'],
+  on_hold: ['draft', 'planned', 'applied', 'document_passed', 'interview', 'final_passed', 'rejected'],
+};
+
+/** Whether moving from `from` to `to` is a permitted status transition (same→same is always allowed). */
+export function canTransitionStatus(from: ApplicationStatus, to: ApplicationStatus): boolean {
+  if (from === to) return true;
+  return ALLOWED_STATUS_TRANSITIONS[from]?.includes(to) ?? false;
+}
+
+/** Throw a clear, user-facing (Korean) error when a status transition is not allowed. */
+export function assertStatusTransition(from: ApplicationStatus, to: ApplicationStatus): void {
+  if (!canTransitionStatus(from, to)) {
+    throw new Error(
+      `'${APPLICATION_STATUS_LABELS[from]}'에서 '${APPLICATION_STATUS_LABELS[to]}'(으)로는 상태를 바꿀 수 없습니다.`,
+    );
+  }
+}
+
 /** Stored document kinds (resumes and career descriptions). Cover letters live in their own tables. */
 export const DOCUMENT_KINDS = ['resume', 'career_description', 'portfolio', 'other'] as const;
 export type DocumentKind = (typeof DOCUMENT_KINDS)[number];

package/scripts/build-dist.mjs

@@ -3,10 +3,12 @@
  * scripts/build-dist.mjs — 배포용 플레인 JS 번들 빌드 (esbuild).
  *
  * 개발은 그대로 tsx 무빌드로 돌리고, 배포(.mcpb / npm publish / 추후 독립 .exe)에서는
- * tsx·tsconfig 경로별칭 런타임 의존성을 없애기 위해 두 진입점을 단일 ESM 파일로 번들한다.
+ * tsx·tsconfig 경로별칭 런타임 의존성을 없애기 위해 네 진입점을 각각 단일 ESM 파일로 번들한다.
  *
- *   dist/mcp.mjs     MCP stdio 서버 (Claude Desktop이 실행)
- *   dist/web.mjs     로컬 대시보드 서버
+ *   dist/mcp.mjs        MCP stdio 서버 (Claude Desktop이 실행)
+ *   dist/web.mjs        로컬 대시보드 서버
+ *   dist/doctor.mjs     설치/환경 점검 CLI
+ *   dist/migrate.mjs    DB 마이그레이션 CLI
  *   dist/public/        대시보드 정적 자산 (apps/web/public 복사)
  *   dist/install-page/  설치 안내 페이지 복사
  *
@@ -23,14 +25,25 @@ 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 });
+  // package.json을 버전 단일 출처로 삼아 번들에 주입(앱별 하드코딩 버전 드리프트 방지).
+  const pkgVersion = JSON.parse(fs.readFileSync(path.join(ROOT, 'package.json'), 'utf8')).version;
+  // dist를 통째로 비우고 다시 만든다. build-dist가 소유하는 산출물(mcp/web/doctor/migrate/
+  // public/install-page)만 남기기 위함. 이렇게 해야 직전 build:mcpb가 남긴 mcpb-stage/·
+  // careermate.mcpb(수 MB)나 테스트 잔여물(mcp-smoke.err)이 npm tarball에 섞여 들어가지 않는다
+  // (npm publish의 prepack은 build-dist만 실행하므로 여기서 비우면 게시본이 깨끗하다).
+  // build:mcpb는 이 함수를 먼저 호출한 뒤 mcpb-stage/·careermate.mcpb를 다시 생성하므로 안전.
+  fs.rmSync(DIST, { recursive: true, force: true });
+  fs.mkdirSync(DIST, { recursive: true });
 
   await esbuild.build({
     absWorkingDir: ROOT,
     entryPoints: {
       mcp: 'apps/mcp/src/index.ts',
       web: 'apps/web/src/index.ts',
+      // doctor/migrate도 번들해 둔다. 이 둘은 @careermate/* 워크스페이스 패키지를 import하는데,
+      // 게시 tarball에는 그 패키지들이 resolvable하지 않아 tsx 폴백이 실패한다(번들이면 인라인돼 동작).
+      doctor: 'scripts/doctor.ts',
+      migrate: 'scripts/migrate.ts',
     },
     outdir: 'dist',
     outExtension: { '.js': '.mjs' },
@@ -39,7 +52,7 @@ async function main() {
     format: 'esm',
     target: 'node22',
     tsconfig: 'tsconfig.json',
-    define: { __BUNDLED__: 'true' },
+    define: { __BUNDLED__: 'true', __APP_VERSION__: JSON.stringify(pkgVersion) },
     // ESM 출력에서 CJS 의존성이 require/__dirname을 써도 동작하도록 shim 주입.
     banner: {
       js: "import { createRequire as __cr } from 'module'; const require = __cr(import.meta.url);",
@@ -51,9 +64,15 @@ async function main() {
   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 });
+  // install-page/careermate.mcpb 는 공개 사이트(careermate.life)의 다운로드 산출물일 뿐,
+  // 번들 대시보드의 /install/ 라우트에는 필요 없다. 이걸 dist로 들이면 .mcpb 빌드가 직전
+  // 번들(자기 자신, ~6MB)을 다시 접어 넣어 매 빌드마다 용량이 불어난다(자기참조). 제외한다.
+  fs.cpSync(path.join(ROOT, 'install-page'), path.join(DIST, 'install-page'), {
+    recursive: true,
+    filter: (src) => path.basename(src) !== 'careermate.mcpb',
+  });
 
-  console.log('✅ dist 빌드 완료: dist/mcp.mjs, dist/web.mjs, dist/public, dist/install-page');
+  console.log('✅ dist 빌드 완료: dist/mcp.mjs, dist/web.mjs, dist/doctor.mjs, dist/migrate.mjs, dist/public, dist/install-page');
 }
 
 main().catch((err) => {