careermate 0.1.0 → 0.1.2

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/bridge.ts

@@ -5,14 +5,11 @@
  * web server publishes it to a runtime file (see @careermate/db runtime). If the
  * server isn't running we start it (detached) and wait for it to register.
  */
-import { spawn } from 'node:child_process';
+import { spawn, type SpawnOptions } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { readRuntimeInfo, isProcessAlive } from '@careermate/db';
-
-// 번들 빌드(esbuild)에서 true로 치환된다. tsx 개발 실행에서는 정의되지 않아 typeof로 안전 분기.
-declare const __BUNDLED__: boolean | undefined;
-const BUNDLED = typeof __BUNDLED__ !== 'undefined' && __BUNDLED__;
+import { BUNDLED } from '@careermate/shared';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // packages/mcp-tools/src -> repo root (dev). 번들에서는 __dirname이 dist/ 이다.
@@ -28,26 +25,38 @@ function liveServer() {
   return null;
 }
 
-/** Start the dashboard server detached and wait until it publishes its address. */
-export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } | null> {
-  const existing = liveServer();
-  if (existing) return { url: existing.url };
-
+/**
+ * Fire-and-forget detached spawn that NEVER throws — synchronously OR
+ * asynchronously. A missing binary (e.g. `xdg-open` on a headless Linux box)
+ * makes spawn emit an async `'error'` event; with no listener that becomes an
+ * uncaughtException and crashes the MCP process. A surrounding try/catch only
+ * guards the synchronous spawn() call, not the later event — so attach the
+ * listener here. stdio defaults to 'ignore'; callers may override via opts.
+ */
+function spawnDetached(cmd: string, args: string[], opts: SpawnOptions = {}): void {
   try {
-    // prod(번들): dist/web.mjs를 플레인 node로 실행. dev: tsx로 소스 실행.
-    const [bin, args, cwd] = BUNDLED
-      ? [process.execPath, ['--experimental-sqlite', path.join(__dirname, 'web.mjs')], __dirname]
-      : [process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/web/src/index.ts'], REPO_ROOT];
-    const child = spawn(bin, args, {
-      cwd,
-      detached: true,
-      stdio: 'ignore',
-      env: { ...process.env, CAREERMATE_NO_OPEN: '1' },
+    const child = spawn(cmd, args, { stdio: 'ignore', detached: true, ...opts });
+    child.on('error', () => {
+      /* binary missing / spawn failed — best-effort, never crash */
     });
     child.unref();
   } catch {
-    return null;
+    /* best-effort */
   }
+}
+
+/** Start the dashboard server detached and wait until it publishes its address. */
+export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } | null> {
+  const existing = liveServer();
+  if (existing) return { url: existing.url };
+
+  // prod(번들): dist/web.mjs를 플레인 node로 실행. dev: tsx로 소스 실행.
+  const [bin, args, cwd] = BUNDLED
+    ? [process.execPath, ['--experimental-sqlite', path.join(__dirname, 'web.mjs')], __dirname]
+    : [process.execPath, ['--no-warnings', '--experimental-sqlite', '--import', 'tsx', 'apps/web/src/index.ts'], REPO_ROOT];
+  // Spawn failures (sync or async) just leave the server down; the poll loop
+  // below then times out and returns null — no crash.
+  spawnDetached(bin as string, args as string[], { cwd: cwd as string, env: { ...process.env, CAREERMATE_NO_OPEN: '1' } });
 
   const start = Date.now();
   while (Date.now() - start < timeoutMs) {
@@ -58,21 +67,35 @@ export async function ensureServer(timeoutMs = 12000): Promise<{ url: string } |
   return null;
 }
 
-export function openInBrowser(url: string): void {
-  const platform = process.platform;
-  try {
-    if (platform === 'win32') {
-      spawn('cmd', ['/c', 'start', '', url], { stdio: 'ignore', detached: true }).unref();
-    } else if (platform === 'darwin') {
-      spawn('open', [url], { stdio: 'ignore', detached: true }).unref();
-    } else {
-      spawn('xdg-open', [url], { stdio: 'ignore', detached: true }).unref();
-    }
-  } catch {
-    /* best-effort */
+/** Open a URL or a local folder via the OS default handler. Best-effort, never throws. */
+function openOsTarget(target: string): void {
+  switch (process.platform) {
+    case 'win32':
+      // `start` is a cmd builtin; the empty "" is the window-title arg so a
+      // quoted target isn't mistaken for the title. (explorer also opens URLs,
+      // but `start` is the canonical default-handler launcher.)
+      spawnDetached('cmd', ['/c', 'start', '', target]);
+      break;
+    case 'darwin':
+      spawnDetached('open', [target]);
+      break;
+    default:
+      spawnDetached('xdg-open', [target]);
   }
 }
 
+export function openInBrowser(url: string): void {
+  openOsTarget(url);
+}
+
+/** Open a local folder in the OS file manager (Explorer/Finder/xdg). Best-effort. */
+export function openInFileManager(dir: string): void {
+  // Windows: `explorer <dir>` is the idiomatic folder opener (start "" <dir>
+  // also works, but explorer focuses an existing window if already open).
+  if (process.platform === 'win32') spawnDetached('explorer', [dir]);
+  else openOsTarget(dir);
+}
+
 /** Resolve the dashboard URL, starting the server if needed. */
 export async function resolveDashboardUrl(hash = ''): Promise<{ url: string; running: boolean }> {
   const live = liveServer();

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

@@ -6,3 +6,12 @@
 export { TOOLS, EXPORTS_LOCATION } from './tools.ts';
 export { ok, fail, toCallToolResult, type ToolDef, type ToolResult } from './result.ts';
 export { resolveDashboardUrl, openInBrowser, ensureServer, projectRoot } from './bridge.ts';
+export {
+  getUpdateStatus,
+  getUpdateStatusAsync,
+  runSelfUpdate,
+  installPrefix,
+  compareVersions,
+  type UpdateStatus,
+  type UpdateResult,
+} from './update.ts';