careermate 0.0.9 → 0.0.10

package/docs/LOCAL_FIRST.md

@@ -0,0 +1,32 @@
+# Local-first data ownership
+
+CareerMate uses **local-first** to mean that the primary career workspace is owned by the user and stored on the user's machine.
+
+## Stored locally
+
+- SQLite database
+- profile, experience, project, and skill records
+- résumés, career descriptions, and cover-letter versions
+- saved job postings, application status, interview preparation, and timeline history
+- backups and exports
+- deterministic verification results
+
+These records are not uploaded to a CareerMate account or CareerMate-operated database.
+
+## Optional network activity
+
+Some features may use the network without changing the local-first model:
+
+- checking the npm registry for a newer CareerMate version
+- opening current installation documentation
+- searching supported public job-board endpoints using only the user's search keyword
+- loading the public product website or demo
+- public-site analytics on `careermate.life`
+
+CareerMate must not attach locally stored résumé, profile, document, or application data to these requests.
+
+## Product language
+
+Do not describe CareerMate as fully offline. Prefer:
+
+> Your career database and documents stay on your computer. Optional discovery and update features may access the internet without sending your stored career data.

package/docs/REVIEW_IMPLEMENTATION_PLAN.md

@@ -0,0 +1,22 @@
+# Full Review Implementation Plan
+
+This document tracks the repository-wide improvements implemented after the 2026-08 full review.
+
+## Product definition
+
+CareerMate is local-first: the primary database, career records, generated documents, and core workflows are owned and stored on the user's machine. Optional network-backed features such as install guidance, update checks, analytics, and job-board search do not change that definition.
+
+## Delivery groups
+
+1. Data safety and lifecycle
+2. Provenance and human verification
+3. Backup, restore, and portability
+4. Provider validation and health
+5. Onboarding and diagnostics
+6. Workflow history and explainability
+7. Fit analysis quality and contradiction detection
+8. Front-end maintainability and accessibility
+9. CI, release, and security hardening
+10. Documentation and SEO
+
+Each group should be implemented as an independently reviewable commit or PR with tests and migration coverage where applicable.

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "careermate",
-  "version": "0.0.9",
+  "version": "0.0.10",
   "type": "module",
-  "description": "CareerMate — an MCP-first, local-first career workspace. Connect it to a local AI agent (Claude Desktop, Claude Code, Codex); CareerMate stores your career data locally on your machine and exposes it over MCP.",
+  "description": "CareerMate — an MCP-first, local-first career workspace. Your career database and documents stay on your machine; optional discovery and update features may use the internet without sending stored career data.",
   "license": "MIT",
   "author": "CareerMate",
   "homepage": "https://careermate.life",
@@ -41,6 +41,8 @@
     "INSTALL.md",
     "THIRD_PARTY_NOTICES.md",
     "AGENTS.md",
+    "docs/LOCAL_FIRST.md",
+    "docs/REVIEW_IMPLEMENTATION_PLAN.md",
     "docs/career-os/README.md",
     "docs/career-os/eop",
     "docs/career-os/knowledge",
@@ -80,13 +82,13 @@
     "mammoth": "^1.12.0",
     "pdfjs-dist": "^6.0.0",
     "tsx": "^4.19.2",
-    "zod": "^3.24.1"
+    "zod": "^4.4.3"
   },
   "devDependencies": {
     "@playwright/test": "^1.60.0",
-    "@types/node": "^22.10.0",
+    "@types/node": "^26.1.2",
     "esbuild": "^0.28.1",
     "playwright": "^1.60.0",
-    "typescript": "^5.7.2"
+    "typescript": "^7.0.2"
   }
 }

package/packages/core/src/data-health.ts

@@ -0,0 +1,161 @@
+import {
+  documentRepo,
+  experienceRepo,
+  projectRepo,
+  jobRepo,
+  fitRepo,
+  applicationRepo,
+} from '@careermate/db';
+
+export interface DataHealthIssue {
+  code: string;
+  severity: 'info' | 'warning' | 'error';
+  entity_type: string;
+  entity_id?: string;
+  message: string;
+}
+
+export interface DataHealthReport {
+  score: number;
+  checked_at: string;
+  counts: Record<string, number>;
+  issues: DataHealthIssue[];
+}
+
+function monthValue(value: string | null | undefined): number | null {
+  if (!value) return null;
+  const m = /^(\d{4})-(\d{2})/.exec(value);
+  if (!m) return null;
+  return Number(m[1]) * 12 + Number(m[2]);
+}
+
+function normalized(value: string | null | undefined): string {
+  return (value ?? '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+export function getDataHealthReport(now = new Date()): DataHealthReport {
+  const experiences = experienceRepo.list();
+  const projects = projectRepo.list();
+  const documents = documentRepo.list();
+  const jobs = jobRepo.list();
+  const issues: DataHealthIssue[] = [];
+
+  for (const exp of experiences) {
+    const start = monthValue(exp.start_date);
+    const end = monthValue(exp.end_date);
+    if (start != null && end != null && end < start) {
+      issues.push({
+        code: 'experience_date_reversed',
+        severity: 'error',
+        entity_type: 'experience',
+        entity_id: exp.id,
+        message: `${exp.company} 경력의 종료일이 시작일보다 빠릅니다.`,
+      });
+    }
+    if (exp.is_current && exp.end_date) {
+      issues.push({
+        code: 'current_experience_has_end_date',
+        severity: 'warning',
+        entity_type: 'experience',
+        entity_id: exp.id,
+        message: `${exp.company} 경력이 재직 중이지만 종료일이 입력돼 있습니다.`,
+      });
+    }
+    if (!exp.role) {
+      issues.push({
+        code: 'experience_missing_role',
+        severity: 'warning',
+        entity_type: 'experience',
+        entity_id: exp.id,
+        message: `${exp.company} 경력에 직무/역할이 없습니다.`,
+      });
+    }
+  }
+
+  const seenProjects = new Map<string, string>();
+  for (const project of projects) {
+    const key = normalized(project.name);
+    const duplicate = seenProjects.get(key);
+    if (key && duplicate) {
+      issues.push({
+        code: 'duplicate_project_name',
+        severity: 'warning',
+        entity_type: 'project',
+        entity_id: project.id,
+        message: `같은 이름의 프로젝트가 중복돼 있습니다: ${project.name}`,
+      });
+    } else if (key) {
+      seenProjects.set(key, project.id);
+    }
+    const start = monthValue(project.start_date);
+    const end = monthValue(project.end_date);
+    if (start != null && end != null && end < start) {
+      issues.push({
+        code: 'project_date_reversed',
+        severity: 'error',
+        entity_type: 'project',
+        entity_id: project.id,
+        message: `${project.name} 프로젝트의 종료일이 시작일보다 빠릅니다.`,
+      });
+    }
+  }
+
+  const primaryDocs = documents.filter((doc) => doc.is_primary);
+  if (documents.length > 0 && primaryDocs.length === 0) {
+    issues.push({
+      code: 'missing_primary_document',
+      severity: 'warning',
+      entity_type: 'document',
+      message: '대표 이력서 또는 경력기술서가 지정되지 않았습니다.',
+    });
+  }
+
+  const nowDate = now.toISOString().slice(0, 10);
+  let staleDrafts = 0;
+  let jobsWithoutFit = 0;
+  for (const job of jobs) {
+    if (!fitRepo.getByJob(job.id)) jobsWithoutFit++;
+    const app = applicationRepo.getByJob(job.id);
+    if (app?.status === 'draft') {
+      const updated = String(app.updated_at ?? '').slice(0, 10);
+      if (updated && updated < nowDate) staleDrafts++;
+    }
+  }
+  if (jobsWithoutFit > 0) {
+    issues.push({
+      code: 'jobs_without_fit_analysis',
+      severity: 'info',
+      entity_type: 'job',
+      message: `적합도 분석이 없는 공고가 ${jobsWithoutFit}개 있습니다.`,
+    });
+  }
+  if (staleDrafts > 0) {
+    issues.push({
+      code: 'stale_draft_applications',
+      severity: 'info',
+      entity_type: 'application',
+      message: `후속 행동을 확인할 임시 지원 건이 ${staleDrafts}개 있습니다.`,
+    });
+  }
+
+  const penalty = issues.reduce((sum, issue) => {
+    if (issue.severity === 'error') return sum + 15;
+    if (issue.severity === 'warning') return sum + 7;
+    return sum + 2;
+  }, 0);
+
+  return {
+    score: Math.max(0, 100 - penalty),
+    checked_at: now.toISOString(),
+    counts: {
+      experiences: experiences.length,
+      projects: projects.length,
+      documents: documents.length,
+      jobs: jobs.length,
+      issues: issues.length,
+      errors: issues.filter((issue) => issue.severity === 'error').length,
+      warnings: issues.filter((issue) => issue.severity === 'warning').length,
+    },
+    issues,
+  };
+}

package/packages/core/src/fit-explain.ts

@@ -0,0 +1,63 @@
+import { fitRepo, jobRepo } from '@careermate/db';
+
+export interface ExplainableFitAnalysis {
+  job_id: string;
+  overall_score: number | null;
+  requirement_coverage: number | null;
+  evidence_strength: number;
+  matched_requirements: string[];
+  missing_requirements: string[];
+  strengths: string[];
+  risks: string[];
+  recommended_actions: string[];
+  explanation: string;
+}
+
+function ratio(matched: number, missing: number): number | null {
+  const total = matched + missing;
+  return total === 0 ? null : Math.round((matched / total) * 100);
+}
+
+export function getExplainableFitAnalysis(jobId: string): ExplainableFitAnalysis | null {
+  const job = jobRepo.get(jobId);
+  const fit = fitRepo.getByJob(jobId);
+  if (!job || !fit) return null;
+
+  const matched = fit.matched_keywords ?? [];
+  const missing = fit.missing_keywords ?? [];
+  const coverage = ratio(matched.length, missing.length);
+  const evidenceItems = (fit.strengths ?? []).filter((item) => item.trim().length > 0);
+  const evidenceStrength = Math.min(100, evidenceItems.length * 20 + matched.length * 5);
+  const risks = [
+    ...(fit.gaps ?? []),
+    ...missing.map((item) => `근거가 부족한 요구사항: ${item}`),
+  ];
+  const actions = fit.recommendations?.length
+    ? fit.recommendations
+    : missing.map((item) => `${item} 요구에 연결할 실제 경험 또는 학습 근거를 보완하세요.`);
+
+  const explanationParts = [
+    coverage == null
+      ? '요구사항 충족률을 계산할 수 있는 매칭 정보가 아직 없습니다.'
+      : `저장된 키워드 기준 요구사항 충족률은 ${coverage}%입니다.`,
+    evidenceStrength >= 70
+      ? '강점과 근거가 비교적 충분합니다.'
+      : evidenceStrength >= 40
+        ? '일부 근거는 있지만 지원 문서에서 더 구체적으로 연결할 필요가 있습니다.'
+        : '현재 분석에는 구체적인 경험 근거가 부족합니다.',
+    risks.length > 0 ? `확인할 위험 요소가 ${risks.length}개 있습니다.` : '명시된 주요 위험 요소는 없습니다.',
+  ];
+
+  return {
+    job_id: jobId,
+    overall_score: fit.score,
+    requirement_coverage: coverage,
+    evidence_strength: evidenceStrength,
+    matched_requirements: matched,
+    missing_requirements: missing,
+    strengths: fit.strengths ?? [],
+    risks,
+    recommended_actions: actions,
+    explanation: explanationParts.join(' '),
+  };
+}

package/packages/core/src/index.ts

@@ -8,4 +8,7 @@ export * from './services.ts';
 export * from './summary.ts';
 export * from './jobsearch.ts';
 export * from './offers.ts';
+export * from './data-health.ts';
+export * from './fit-explain.ts';
+export * from './reuse-insights.ts';
 export * from './verify/index.ts';

package/packages/core/src/jobsearch.ts

@@ -2,49 +2,36 @@
  * Job search import — pull postings from key-free public job-board endpoints by
  * keyword, so the AI can offer real listings the user can save into CareerMate.
  *
- * Scope & boundaries (deliberate):
- *  - INBOUND only. We fetch publicly visible postings; we send only the search
- *    keyword, never the user's stored data. (Privacy = no user data leaves; this
- *    does not violate it.)
- *  - No WAF bypass, no auth keys. These providers' own frontends call these JSON
- *    endpoints unauthenticated; a plain fetch suffices. We do NOT bundle a
- *    scraper/anti-bot evasion (that's the legally dangerous part — see
- *    .claude/work/research/research_0004). Sites requiring keys (Saramin oapi,
- *    고용24) or that forbid it in robots.txt (JobKorea search) are excluded here.
- *  - Honest User-Agent. We identify ourselves as careermate (verified live:
- *    both providers answer 200 to it), never as a spoofed browser — "no bot
- *    evasion" must include not lying about who is asking.
- *  - Read-only w.r.t. the DB. This returns candidates; the AI shows them and the
- *    user picks which to save via save_job_posting (no auto-dumping into the DB).
- *
- * Providers are unofficial public endpoints — if a response shape changes, only
- * the affected provider's parser needs updating (others keep working).
+ * CareerMate is local-first: only the search keyword leaves the machine. Stored
+ * profile, résumé, application, and document data are never sent to providers.
+ * Provider endpoints are unofficial and therefore validated at runtime; a shape
+ * change degrades only that provider instead of silently returning corrupt rows.
  */
 
+import { z } from 'zod';
 import { APP_VERSION } from '@careermate/shared';
 
 export interface JobSearchResult {
-  /** Provider id, e.g. 'wanted' | 'jumpit'. */
   source: string;
   company: string;
   position: string;
-  /** Canonical posting URL the user can open. */
   url: string;
   location?: string;
-  /** Required experience, human-readable (e.g. '신입', '5~20년'). */
   experience?: string;
-  /** Tech stack / tags when the provider exposes them. */
   keywords?: string[];
-  /** Application deadline as YYYY-MM-DD when known. */
   deadline?: string;
-  /** Provider-native id (for dedup / detail fetch). */
   external_id: string;
 }
 
+export type ProviderStatus = 'healthy' | 'degraded' | 'unavailable';
+
 export interface ProviderOutcome {
   source: string;
+  label: string;
   ok: boolean;
+  status: ProviderStatus;
   count: number;
+  checked_at: string;
   error?: string;
 }
 
@@ -55,24 +42,20 @@ export interface JobSearchResponse {
 }
 
 export interface JobSearchOptions {
-  /** Which providers to query. Defaults to all registered. */
   sources?: string[];
-  /** Max results per provider (1–50). Default 10. */
   limit?: number;
-  /** Per-request timeout in ms. Default 10000. */
   timeoutMs?: number;
 }
 
 const UA = `careermate/${APP_VERSION} (+https://careermate.life)`;
 
-/** Slice an ISO timestamp / date string to YYYY-MM-DD; undefined if not a date. */
 function toYmd(v: unknown): string | undefined {
   if (typeof v !== 'string' || v.length < 10) return undefined;
   const m = v.match(/^(\d{4}-\d{2}-\d{2})/);
   return m ? m[1] : undefined;
 }
 
-async function getJson(url: string, timeoutMs: number): Promise<any> {
+async function getJson(url: string, timeoutMs: number): Promise<unknown> {
   const ctrl = new AbortController();
   const timer = setTimeout(() => ctrl.abort(), timeoutMs);
   try {
@@ -81,6 +64,8 @@ async function getJson(url: string, timeoutMs: number): Promise<any> {
       signal: ctrl.signal,
     });
     if (!res.ok) throw new Error(`HTTP ${res.status}`);
+    const type = res.headers.get('content-type') ?? '';
+    if (!type.includes('json')) throw new Error(`unexpected content-type: ${type || 'unknown'}`);
     return await res.json();
   } finally {
     clearTimeout(timer);
@@ -93,7 +78,41 @@ interface Provider {
   search(query: string, limit: number, timeoutMs: number): Promise<JobSearchResult[]>;
 }
 
-/** Wanted (wanted.co.kr) — public v4 jobs JSON, no auth. IT/startup roles. */
+const wantedSchema = z.object({
+  data: z.array(
+    z.object({
+      id: z.union([z.string(), z.number()]),
+      position: z.string().min(1),
+      company: z.object({ name: z.string().min(1) }),
+      annual_from: z.number().nullable().optional(),
+      annual_to: z.number().nullable().optional(),
+      due_time: z.string().nullable().optional(),
+      address: z
+        .object({ location: z.string().optional(), full_location: z.string().optional() })
+        .nullable()
+        .optional(),
+    }).passthrough(),
+  ),
+}).passthrough();
+
+const jumpitSchema = z.object({
+  result: z.object({
+    positions: z.array(
+      z.object({
+        id: z.union([z.string(), z.number()]),
+        companyName: z.string().min(1),
+        title: z.string().min(1),
+        locations: z.array(z.string()).optional(),
+        newcomer: z.boolean().optional(),
+        minCareer: z.number().nullable().optional(),
+        maxCareer: z.number().nullable().optional(),
+        techStacks: z.array(z.string()).optional(),
+        closedAt: z.string().nullable().optional(),
+      }).passthrough(),
+    ),
+  }).passthrough(),
+}).passthrough();
+
 const wanted: Provider = {
   id: 'wanted',
   label: '원티드',
@@ -101,81 +120,103 @@ const wanted: Provider = {
     const url =
       `https://www.wanted.co.kr/api/v4/jobs?country=kr&locations=all&years=-1` +
       `&job_sort=job.latest_order&limit=${limit}&offset=0&query=${encodeURIComponent(query)}`;
-    const j = await getJson(url, timeoutMs);
-    const rows: any[] = Array.isArray(j?.data) ? j.data : [];
-    return rows.map((r) => {
+    const j = wantedSchema.parse(await getJson(url, timeoutMs));
+    return j.data.map((r) => {
       const annual =
         r.annual_from || r.annual_to
           ? `${r.annual_from ?? 0}~${r.annual_to ?? '?'}년`
           : undefined;
       return {
         source: 'wanted',
-        company: r.company?.name ?? '',
-        position: r.position ?? '',
+        company: r.company.name,
+        position: r.position,
         url: `https://www.wanted.co.kr/wd/${r.id}`,
-        location: r.address?.location ?? r.address?.full_location ?? undefined,
+        location: r.address?.location ?? r.address?.full_location,
         experience: annual,
         deadline: toYmd(r.due_time),
         external_id: String(r.id),
-      } as JobSearchResult;
+      };
     });
   },
 };
 
-/** Jumpit (jumpit.co.kr) — public positions JSON, no auth. Dev roles, tech stacks. */
 const jumpit: Provider = {
   id: 'jumpit',
   label: '점핏',
   async search(query, limit, timeoutMs) {
     const url =
       `https://api.jumpit.co.kr/api/positions?sort=rsp_rate&page=1&keyword=${encodeURIComponent(query)}`;
-    const j = await getJson(url, timeoutMs);
-    const rows: any[] = Array.isArray(j?.result?.positions) ? j.result.positions : [];
-    return rows.slice(0, limit).map((p) => ({
+    const j = jumpitSchema.parse(await getJson(url, timeoutMs));
+    return j.result.positions.slice(0, limit).map((p) => ({
       source: 'jumpit',
-      company: p.companyName ?? '',
-      position: p.title ?? '',
+      company: p.companyName,
+      position: p.title,
       url: `https://www.jumpit.co.kr/position/${p.id}`,
-      location: Array.isArray(p.locations) ? p.locations[0] : undefined,
+      location: p.locations?.[0],
       experience: p.newcomer
         ? '신입'
         : p.minCareer != null
           ? `${p.minCareer}~${p.maxCareer ?? p.minCareer}년`
           : undefined,
-      keywords: Array.isArray(p.techStacks) ? p.techStacks : undefined,
+      keywords: p.techStacks,
       deadline: toYmd(p.closedAt),
       external_id: String(p.id),
-    } as JobSearchResult));
+    }));
   },
 };
 
 const PROVIDERS: Provider[] = [wanted, jumpit];
-
-/** Registered provider ids (key-free, no WAF bypass). */
 export const JOB_SEARCH_SOURCES = PROVIDERS.map((p) => p.id);
 
-/**
- * Search key-free public job boards by keyword. Each provider runs independently;
- * one failing (network/timeout/shape change) does not sink the others. Results
- * are returned for the AI to present — saving is a separate explicit step.
- */
+function providerError(e: unknown): { status: ProviderStatus; error: string } {
+  if (e instanceof z.ZodError) {
+    const first = e.issues[0];
+    return {
+      status: 'degraded',
+      error: `provider response changed${first ? ` (${first.path.join('.') || 'root'})` : ''}`,
+    };
+  }
+  const message = e instanceof Error ? e.message : String(e);
+  return { status: 'unavailable', error: message };
+}
+
 export async function searchJobs(query: string, opts: JobSearchOptions = {}): Promise<JobSearchResponse> {
   const q = (query ?? '').trim();
   if (!q) return { query: '', results: [], providers: [] };
   const limit = Math.min(50, Math.max(1, opts.limit ?? 10));
-  const timeoutMs = opts.timeoutMs ?? 10000;
+  const timeoutMs = Math.min(30_000, Math.max(1_000, opts.timeoutMs ?? 10_000));
   const chosen = opts.sources?.length
     ? PROVIDERS.filter((p) => opts.sources!.includes(p.id))
     : PROVIDERS;
 
   const settled = await Promise.all(
     chosen.map(async (p): Promise<{ outcome: ProviderOutcome; results: JobSearchResult[] }> => {
+      const checked_at = new Date().toISOString();
       try {
         const results = await p.search(q, limit, timeoutMs);
-        return { outcome: { source: p.id, ok: true, count: results.length }, results };
+        return {
+          outcome: {
+            source: p.id,
+            label: p.label,
+            ok: true,
+            status: 'healthy',
+            count: results.length,
+            checked_at,
+          },
+          results,
+        };
       } catch (e) {
+        const failure = providerError(e);
         return {
-          outcome: { source: p.id, ok: false, count: 0, error: e instanceof Error ? e.message : String(e) },
+          outcome: {
+            source: p.id,
+            label: p.label,
+            ok: false,
+            status: failure.status,
+            count: 0,
+            checked_at,
+            error: failure.error,
+          },
           results: [],
         };
       }