@luanpdd/kit-mcp 1.27.0 → 1.29.0

package/src/core/kit.js

@@ -1,216 +1,216 @@
-// Read the canonical kit/ directory and return a structured index.
-// Source of truth: kit/agents/*.md, kit/commands/*.md, kit/skills/*/SKILL.md
-//
-// Frontmatter is parsed loosely (no external dep) — we only need name & description.
-
-import path from 'node:path';
-import fs from 'node:fs/promises';
-import { fileURLToPath } from 'node:url';
-
-const __filename = fileURLToPath(import.meta.url);
-const __dirname  = path.dirname(__filename);
-
-// PERF-02: Frontmatter regexes compiled once at module load (was being recompiled
-// on every readMdDir / readSkillsDir entry — 60+ times per listKit call).
-const FRONTMATTER_SPLIT_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
-const FRONTMATTER_RAW_RE   = /^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/;
-const YAML_KEY_RE          = /^([A-Za-z0-9_-]+):\s*(.*)$/;
-
-// Resolution order for the kit root (re-evaluated on each call so env-var
-// overrides set after module load — e.g. by the CLI preAction hook — work):
-//   1. explicit `kitRoot` opt passed by caller
-//   2. KIT_MCP_KIT_ROOT env var (per-session override)
-//   3. ./kit relative to this package (the bundled example kit)
-export const BUNDLED_KIT_ROOT = path.resolve(__dirname, '../../kit');
-export function resolveKitRoot(kitRoot) {
-  if (kitRoot) return path.resolve(kitRoot);
-  if (process.env.KIT_MCP_KIT_ROOT) return path.resolve(process.env.KIT_MCP_KIT_ROOT);
-  return BUNDLED_KIT_ROOT;
-}
-
-// PERF-01: TTL cache for listKit output. Repeated calls within KIT_CACHE_TTL_MS
-// return the cached value — sync/reverse-sync/MCP list-* tools used to walk the
-// disk on every invocation. Trade-off: callers that edit kit/ inside the same
-// process may see stale data for up to 30s. Acceptable for MCP/CLI ergonomics.
-const KIT_CACHE_TTL_MS = 30_000;
-const kitCache = new Map(); // `${kitRoot}:${mode}` -> { value, ts }
-
-// PERF-S1: when sync runs in mode=reference (default), the body/content of each
-// kit file is never used — only frontmatter (name + description). Reading just
-// the first STUB_READ_BYTES is enough for any frontmatter we'd ever produce and
-// avoids loading 50 KB+ files (planner.md etc) from disk.
-const STUB_READ_BYTES = 4096;
-
-export function clearKitCache() { kitCache.clear(); }
-
-export async function listKit(kitRoot, opts = {}) {
-  kitRoot = resolveKitRoot(kitRoot);
-  const stubsOnly = opts.stubsOnly === true;
-  const cacheKey = `${kitRoot}:${stubsOnly ? 'stubs' : 'full'}`;
-  const cached = kitCache.get(cacheKey);
-  if (cached && Date.now() - cached.ts < KIT_CACHE_TTL_MS) {
-    return cached.value;
-  }
-  const [agents, commands, skills, skillsExtras] = await Promise.all([
-    readMdDir(path.join(kitRoot, 'agents'),    'agent',   { stubsOnly }),
-    readMdDir(path.join(kitRoot, 'commands'),  'command', { stubsOnly }),
-    readSkillsDir(path.join(kitRoot, 'skills'), { stubsOnly }),
-    readSkillsDir(path.join(kitRoot, 'skills-extras'), { stubsOnly }).catch(() => []),
-  ]);
-  const value = { agents, commands, skills, skillsExtras, kitRoot, stubsOnly };
-  kitCache.set(cacheKey, { value, ts: Date.now() });
-  return value;
-}
-
-// Read just enough bytes from the head of the file to capture the frontmatter.
-// Returns the partial string. fs.open + fd.read avoids the OS pre-fetching the
-// rest of the file (which fs.readFile would force).
-async function readHead(absPath, n) {
-  const fd = await fs.open(absPath, 'r');
-  try {
-    const buf = Buffer.alloc(n);
-    const { bytesRead } = await fd.read(buf, 0, n, 0);
-    return buf.subarray(0, bytesRead).toString('utf8');
-  } finally {
-    await fd.close();
-  }
-}
-
-async function readMdDir(dir, kind, { stubsOnly = false } = {}) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const out = [];
-  for (const e of entries) {
-    if (!e.isFile() || !e.name.endsWith('.md')) continue;
-    const absPath = path.join(dir, e.name);
-    const raw = stubsOnly
-      ? await readHead(absPath, STUB_READ_BYTES)
-      : await fs.readFile(absPath, 'utf8');
-    const { frontmatter, body } = splitFrontmatter(raw);
-    const item = {
-      kind,
-      name: e.name.replace(/\.md$/, ''),
-      absPath,
-      frontmatter,
-      frontmatterRaw: matchFrontmatterRaw(raw),
-      description: frontmatter?.description ?? firstNonEmptyLine(body),
-    };
-    if (!stubsOnly) {
-      item.body = body;
-      item.content = raw;
-    }
-    out.push(item);
-  }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-async function readSkillsDir(dir, { stubsOnly = false } = {}) {
-  let entries;
-  try {
-    entries = await fs.readdir(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  const out = [];
-  for (const e of entries) {
-    if (!e.isDirectory()) continue;
-    const skillPath = path.join(dir, e.name, 'SKILL.md');
-    let raw;
-    try {
-      raw = stubsOnly
-        ? await readHead(skillPath, STUB_READ_BYTES)
-        : await fs.readFile(skillPath, 'utf8');
-    } catch { continue; }
-    const { frontmatter, body } = splitFrontmatter(raw);
-    const item = {
-      kind: 'skill',
-      name: e.name,
-      absPath: skillPath,
-      dirPath: path.join(dir, e.name),
-      frontmatter,
-      frontmatterRaw: matchFrontmatterRaw(raw),
-      description: frontmatter?.description ?? firstNonEmptyLine(body),
-    };
-    if (!stubsOnly) {
-      item.body = body;
-      item.skillContent = raw;
-    }
-    out.push(item);
-  }
-  return out.sort((a, b) => a.name.localeCompare(b.name));
-}
-
-// --- minimal YAML-ish frontmatter parser (no deps) ---
-// Handles `key: value`, `key: >` multiline, but NOT nested objects/arrays.
-// Good enough for our SKILL.md / agent.md headers.
-
-function splitFrontmatter(raw) {
-  const m = raw.match(FRONTMATTER_SPLIT_RE);
-  if (!m) return { frontmatter: null, body: raw };
-  return { frontmatter: parseLooseYaml(m[1]), body: m[2] };
-}
-
-function matchFrontmatterRaw(raw) {
-  const m = raw.match(FRONTMATTER_RAW_RE);
-  return m ? m[1] : '';
-}
-
-function parseLooseYaml(text) {
-  const out = {};
-  const lines = text.split(/\r?\n/);
-  let i = 0;
-  while (i < lines.length) {
-    const line = lines[i];
-    const m = line.match(YAML_KEY_RE);
-    if (!m) { i++; continue; }
-    const key = m[1];
-    let val = m[2];
-    if (val === '>' || val === '|') {
-      // Multiline: collect indented lines
-      const collected = [];
-      i++;
-      while (i < lines.length && /^\s+/.test(lines[i])) {
-        collected.push(lines[i].replace(/^\s+/, ''));
-        i++;
-      }
-      out[key] = collected.join(' ').trim();
-      continue;
-    }
-    out[key] = val.trim().replace(/^["']|["']$/g, '');
-    i++;
-  }
-  return out;
-}
-
-function firstNonEmptyLine(body) {
-  for (const line of body.split(/\r?\n/)) {
-    const t = line.trim();
-    if (!t) continue;                      // blank
-    if (t.startsWith('#')) continue;       // markdown heading
-    if (t.startsWith('<!--')) continue;    // HTML comment (e.g. STUB_MARKER)
-    return t.slice(0, 200);
-  }
-  return '';
-}
-
-// --- search helpers ---
-
-export function searchKit(kit, query) {
-  const q = query.toLowerCase();
-  const all = [...kit.agents, ...kit.commands, ...kit.skills, ...kit.skillsExtras];
-  return all.filter(item =>
-    item.name.toLowerCase().includes(q) ||
-    (item.description ?? '').toLowerCase().includes(q)
-  ).map(({ kind, name, description, absPath }) => ({ kind, name, description, absPath }));
-}
-
-export function findItem(kit, kind, name) {
-  const buckets = { agent: kit.agents, command: kit.commands, skill: [...kit.skills, ...kit.skillsExtras] };
-  const b = buckets[kind];
-  if (!b) throw new Error(`Unknown kind: ${kind}`);
-  return b.find(x => x.name === name) ?? null;
-}
+// Read the canonical kit/ directory and return a structured index.
+// Source of truth: kit/agents/*.md, kit/commands/*.md, kit/skills/*/SKILL.md
+//
+// Frontmatter is parsed loosely (no external dep) — we only need name & description.
+
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname  = path.dirname(__filename);
+
+// PERF-02: Frontmatter regexes compiled once at module load (was being recompiled
+// on every readMdDir / readSkillsDir entry — 60+ times per listKit call).
+const FRONTMATTER_SPLIT_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n?([\s\S]*)$/;
+const FRONTMATTER_RAW_RE   = /^(---\r?\n[\s\S]*?\r?\n---\r?\n?)/;
+const YAML_KEY_RE          = /^([A-Za-z0-9_-]+):\s*(.*)$/;
+
+// Resolution order for the kit root (re-evaluated on each call so env-var
+// overrides set after module load — e.g. by the CLI preAction hook — work):
+//   1. explicit `kitRoot` opt passed by caller
+//   2. KIT_MCP_KIT_ROOT env var (per-session override)
+//   3. ./kit relative to this package (the bundled example kit)
+export const BUNDLED_KIT_ROOT = path.resolve(__dirname, '../../kit');
+export function resolveKitRoot(kitRoot) {
+  if (kitRoot) return path.resolve(kitRoot);
+  if (process.env.KIT_MCP_KIT_ROOT) return path.resolve(process.env.KIT_MCP_KIT_ROOT);
+  return BUNDLED_KIT_ROOT;
+}
+
+// PERF-01: TTL cache for listKit output. Repeated calls within KIT_CACHE_TTL_MS
+// return the cached value — sync/reverse-sync/MCP list-* tools used to walk the
+// disk on every invocation. Trade-off: callers that edit kit/ inside the same
+// process may see stale data for up to 30s. Acceptable for MCP/CLI ergonomics.
+const KIT_CACHE_TTL_MS = 30_000;
+const kitCache = new Map(); // `${kitRoot}:${mode}` -> { value, ts }
+
+// PERF-S1: when sync runs in mode=reference (default), the body/content of each
+// kit file is never used — only frontmatter (name + description). Reading just
+// the first STUB_READ_BYTES is enough for any frontmatter we'd ever produce and
+// avoids loading 50 KB+ files (planner.md etc) from disk.
+const STUB_READ_BYTES = 4096;
+
+export function clearKitCache() { kitCache.clear(); }
+
+export async function listKit(kitRoot, opts = {}) {
+  kitRoot = resolveKitRoot(kitRoot);
+  const stubsOnly = opts.stubsOnly === true;
+  const cacheKey = `${kitRoot}:${stubsOnly ? 'stubs' : 'full'}`;
+  const cached = kitCache.get(cacheKey);
+  if (cached && Date.now() - cached.ts < KIT_CACHE_TTL_MS) {
+    return cached.value;
+  }
+  const [agents, commands, skills, skillsExtras] = await Promise.all([
+    readMdDir(path.join(kitRoot, 'agents'),    'agent',   { stubsOnly }),
+    readMdDir(path.join(kitRoot, 'commands'),  'command', { stubsOnly }),
+    readSkillsDir(path.join(kitRoot, 'skills'), { stubsOnly }),
+    readSkillsDir(path.join(kitRoot, 'skills-extras'), { stubsOnly }).catch(() => []),
+  ]);
+  const value = { agents, commands, skills, skillsExtras, kitRoot, stubsOnly };
+  kitCache.set(cacheKey, { value, ts: Date.now() });
+  return value;
+}
+
+// Read just enough bytes from the head of the file to capture the frontmatter.
+// Returns the partial string. fs.open + fd.read avoids the OS pre-fetching the
+// rest of the file (which fs.readFile would force).
+async function readHead(absPath, n) {
+  const fd = await fs.open(absPath, 'r');
+  try {
+    const buf = Buffer.alloc(n);
+    const { bytesRead } = await fd.read(buf, 0, n, 0);
+    return buf.subarray(0, bytesRead).toString('utf8');
+  } finally {
+    await fd.close();
+  }
+}
+
+async function readMdDir(dir, kind, { stubsOnly = false } = {}) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isFile() || !e.name.endsWith('.md')) continue;
+    const absPath = path.join(dir, e.name);
+    const raw = stubsOnly
+      ? await readHead(absPath, STUB_READ_BYTES)
+      : await fs.readFile(absPath, 'utf8');
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const item = {
+      kind,
+      name: e.name.replace(/\.md$/, ''),
+      absPath,
+      frontmatter,
+      frontmatterRaw: matchFrontmatterRaw(raw),
+      description: frontmatter?.description ?? firstNonEmptyLine(body),
+    };
+    if (!stubsOnly) {
+      item.body = body;
+      item.content = raw;
+    }
+    out.push(item);
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+async function readSkillsDir(dir, { stubsOnly = false } = {}) {
+  let entries;
+  try {
+    entries = await fs.readdir(dir, { withFileTypes: true });
+  } catch {
+    return [];
+  }
+  const out = [];
+  for (const e of entries) {
+    if (!e.isDirectory()) continue;
+    const skillPath = path.join(dir, e.name, 'SKILL.md');
+    let raw;
+    try {
+      raw = stubsOnly
+        ? await readHead(skillPath, STUB_READ_BYTES)
+        : await fs.readFile(skillPath, 'utf8');
+    } catch { continue; }
+    const { frontmatter, body } = splitFrontmatter(raw);
+    const item = {
+      kind: 'skill',
+      name: e.name,
+      absPath: skillPath,
+      dirPath: path.join(dir, e.name),
+      frontmatter,
+      frontmatterRaw: matchFrontmatterRaw(raw),
+      description: frontmatter?.description ?? firstNonEmptyLine(body),
+    };
+    if (!stubsOnly) {
+      item.body = body;
+      item.skillContent = raw;
+    }
+    out.push(item);
+  }
+  return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+// --- minimal YAML-ish frontmatter parser (no deps) ---
+// Handles `key: value`, `key: >` multiline, but NOT nested objects/arrays.
+// Good enough for our SKILL.md / agent.md headers.
+
+function splitFrontmatter(raw) {
+  const m = raw.match(FRONTMATTER_SPLIT_RE);
+  if (!m) return { frontmatter: null, body: raw };
+  return { frontmatter: parseLooseYaml(m[1]), body: m[2] };
+}
+
+function matchFrontmatterRaw(raw) {
+  const m = raw.match(FRONTMATTER_RAW_RE);
+  return m ? m[1] : '';
+}
+
+function parseLooseYaml(text) {
+  const out = {};
+  const lines = text.split(/\r?\n/);
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const m = line.match(YAML_KEY_RE);
+    if (!m) { i++; continue; }
+    const key = m[1];
+    let val = m[2];
+    if (val === '>' || val === '|') {
+      // Multiline: collect indented lines
+      const collected = [];
+      i++;
+      while (i < lines.length && /^\s+/.test(lines[i])) {
+        collected.push(lines[i].replace(/^\s+/, ''));
+        i++;
+      }
+      out[key] = collected.join(' ').trim();
+      continue;
+    }
+    out[key] = val.trim().replace(/^["']|["']$/g, '');
+    i++;
+  }
+  return out;
+}
+
+function firstNonEmptyLine(body) {
+  for (const line of body.split(/\r?\n/)) {
+    const t = line.trim();
+    if (!t) continue;                      // blank
+    if (t.startsWith('#')) continue;       // markdown heading
+    if (t.startsWith('<!--')) continue;    // HTML comment (e.g. STUB_MARKER)
+    return t.slice(0, 200);
+  }
+  return '';
+}
+
+// --- search helpers ---
+
+export function searchKit(kit, query) {
+  const q = query.toLowerCase();
+  const all = [...kit.agents, ...kit.commands, ...kit.skills, ...kit.skillsExtras];
+  return all.filter(item =>
+    item.name.toLowerCase().includes(q) ||
+    (item.description ?? '').toLowerCase().includes(q)
+  ).map(({ kind, name, description, absPath }) => ({ kind, name, description, absPath }));
+}
+
+export function findItem(kit, kind, name) {
+  const buckets = { agent: kit.agents, command: kit.commands, skill: [...kit.skills, ...kit.skillsExtras] };
+  const b = buckets[kind];
+  if (!b) throw new Error(`Unknown kind: ${kind}`);
+  return b.find(x => x.name === name) ?? null;
+}

package/src/core/logger.js

@@ -0,0 +1,170 @@
+// src/core/logger.js — JSONL append-only logger with date-based rotation.
+//
+// Phase 158 (v1.28): every MCP tool invocation is appended to
+//   ~/.kit-mcp/logs/kit-mcp-YYYY-MM-DD.log
+// as a single JSON line per event. Files are rotated by calendar day; on the
+// first write of a new day, old files past the retention horizon are deleted.
+//
+// Discipline:
+//   - Async fire-and-forget — must never block the MCP request handler.
+//   - File-only — never writes to stdout (MCP spec) and stderr only on
+//     last-resort init failure.
+//   - Cross-platform — uses os.homedir(), path.join, never POSIX-only ops.
+//
+// Retention is read from KIT_MCP_LOG_RETENTION_DAYS (integer, default 7).
+// Set to 0 to disable rotation/cleanup entirely (keep forever).
+
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+
+const LOG_DIR = process.env.KIT_MCP_LOG_DIR
+  || path.join(os.homedir(), '.kit-mcp', 'logs');
+
+function retentionDays() {
+  const raw = process.env.KIT_MCP_LOG_RETENTION_DAYS;
+  if (raw === undefined || raw === '') return 7;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : 7;
+}
+
+function todayStamp(d = new Date()) {
+  // YYYY-MM-DD in local time. Rotation key — must stay stable within a day.
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, '0');
+  const day = String(d.getDate()).padStart(2, '0');
+  return `${y}-${m}-${day}`;
+}
+
+export function currentLogPath() {
+  return path.join(LOG_DIR, `kit-mcp-${todayStamp()}.log`);
+}
+
+export function logDir() {
+  return LOG_DIR;
+}
+
+let initDone = false;
+let initFailed = false;
+
+function ensureDir() {
+  if (initDone) return !initFailed;
+  initDone = true;
+  try {
+    fs.mkdirSync(LOG_DIR, { recursive: true });
+    return true;
+  } catch (e) {
+    initFailed = true;
+    // Last-resort signal to operator; stderr is allowed (stdout would corrupt
+    // the MCP transport).
+    try { console.error(`[kit-mcp logger] failed to create ${LOG_DIR}: ${e.message}`); } catch { /* noop */ }
+    return false;
+  }
+}
+
+let lastRotationCheck = '';
+
+function rotateIfNeeded() {
+  const today = todayStamp();
+  if (lastRotationCheck === today) return;
+  lastRotationCheck = today;
+
+  const keep = retentionDays();
+  if (keep === 0) return; // keep forever
+
+  try {
+    const entries = fs.readdirSync(LOG_DIR);
+    const cutoff = new Date();
+    cutoff.setDate(cutoff.getDate() - keep);
+    const cutoffStamp = todayStamp(cutoff);
+    for (const name of entries) {
+      const m = name.match(/^kit-mcp-(\d{4}-\d{2}-\d{2})\.log$/);
+      if (!m) continue;
+      if (m[1] < cutoffStamp) {
+        try { fs.unlinkSync(path.join(LOG_DIR, name)); } catch { /* swallow */ }
+      }
+    }
+  } catch { /* swallow */ }
+}
+
+// logEvent(event) — append one JSON line. Synchronous write to a file handle
+// is cheap (~µs) and avoids losing events if the process exits right after.
+// All fields except `ts` are caller-supplied; we add `ts` ISO 8601.
+export function logEvent(event) {
+  if (!ensureDir()) return;
+  rotateIfNeeded();
+  const enriched = { ts: new Date().toISOString(), pid: process.pid, ...event };
+  try {
+    fs.appendFileSync(currentLogPath(), JSON.stringify(enriched) + '\n', 'utf8');
+  } catch { /* swallow — logging must never break the caller */ }
+}
+
+// listLogs() — returns absolute paths of available log files, most recent first.
+export function listLogs() {
+  if (!ensureDir()) return [];
+  try {
+    return fs.readdirSync(LOG_DIR)
+      .filter((n) => /^kit-mcp-\d{4}-\d{2}-\d{2}\.log$/.test(n))
+      .sort((a, b) => b.localeCompare(a))
+      .map((n) => path.join(LOG_DIR, n));
+  } catch {
+    return [];
+  }
+}
+
+// tailLogs({lines, follow, onLine}) — reads the last N lines across files,
+// optionally tailing forever (writes to onLine as new lines arrive). Returns
+// a `stop()` function when follow=true; otherwise resolves after initial read.
+export function tailLogs({ lines = 50, follow = false, onLine } = {}) {
+  if (!onLine) throw new Error('tailLogs requires onLine callback');
+
+  const files = listLogs();
+  // Walk from oldest-relevant forward to collect last N lines. Approximation:
+  // read latest file, if it has < N lines, also read the previous one, etc.
+  const collected = [];
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(file, 'utf8');
+      const fileLines = content.split('\n').filter(Boolean);
+      collected.unshift(...fileLines);
+    } catch { /* skip unreadable */ }
+    if (collected.length >= lines) break;
+  }
+  const tail = collected.slice(-lines);
+  for (const line of tail) onLine(line);
+
+  if (!follow) return { stop: () => {} };
+
+  // Naive follow: poll the current-day file every 250ms for new bytes.
+  let offset = 0;
+  try {
+    const cur = currentLogPath();
+    if (fs.existsSync(cur)) offset = fs.statSync(cur).size;
+  } catch { /* ignore */ }
+  let stopped = false;
+  const interval = setInterval(() => {
+    if (stopped) return;
+    try {
+      const cur = currentLogPath();
+      if (!fs.existsSync(cur)) return;
+      const stat = fs.statSync(cur);
+      if (stat.size <= offset) return;
+      const fd = fs.openSync(cur, 'r');
+      const buf = Buffer.alloc(stat.size - offset);
+      fs.readSync(fd, buf, 0, buf.length, offset);
+      fs.closeSync(fd);
+      offset = stat.size;
+      const text = buf.toString('utf8');
+      for (const line of text.split('\n')) {
+        if (line) onLine(line);
+      }
+    } catch { /* swallow */ }
+  }, 250);
+
+  return {
+    stop: () => {
+      stopped = true;
+      clearInterval(interval);
+    },
+  };
+}

package/src/core/notify.js

@@ -0,0 +1,60 @@
+// src/core/notify.js — opt-in OS-level notification on MCP tool call.
+//
+// Phase 164 (v1.28). Off by default — set KIT_MCP_NOTIFY=1 to enable.
+// Cross-platform best-effort: PowerShell BurntToast/MessageBox on Windows,
+// osascript on macOS, notify-send on Linux. Failure is silent.
+//
+// Throttled: minimum 5s between notifications (configurable via
+// KIT_MCP_NOTIFY_THROTTLE_MS) to prevent flood.
+
+import { spawn } from 'node:child_process';
+
+const DEFAULT_THROTTLE_MS = 5000;
+let lastNotifyAt = 0;
+
+function throttleMs() {
+  const raw = process.env.KIT_MCP_NOTIFY_THROTTLE_MS;
+  const n = parseInt(raw, 10);
+  return Number.isFinite(n) && n >= 0 ? n : DEFAULT_THROTTLE_MS;
+}
+
+export function isNotifyEnabled() {
+  return process.env.KIT_MCP_NOTIFY === '1' || process.env.KIT_MCP_NOTIFY === 'true';
+}
+
+function spawnDetached(cmd, args) {
+  try {
+    const c = spawn(cmd, args, { detached: true, stdio: 'ignore', windowsHide: true });
+    c.unref();
+  } catch { /* swallow — notification must never break the server */ }
+}
+
+// notify({title, body}): fire a best-effort OS notification. Throttled.
+export function notify({ title, body } = {}) {
+  if (!isNotifyEnabled()) return;
+  const now = Date.now();
+  if (now - lastNotifyAt < throttleMs()) return;
+  lastNotifyAt = now;
+
+  const t = (title || 'kit-mcp').replace(/"/g, "'");
+  const b = (body || '').replace(/"/g, "'");
+
+  if (process.platform === 'darwin') {
+    spawnDetached('osascript', ['-e', `display notification "${b}" with title "${t}"`]);
+  } else if (process.platform === 'linux') {
+    spawnDetached('notify-send', [t, b]);
+  } else if (process.platform === 'win32') {
+    // PowerShell toast via Windows.UI.Notifications. Falls back silently if
+    // BurntToast not installed — we use the simpler msg via WScript.Shell.
+    const ps = `Add-Type -AssemblyName System.Windows.Forms; `
+      + `$n = New-Object System.Windows.Forms.NotifyIcon; `
+      + `$n.Icon = [System.Drawing.SystemIcons]::Information; `
+      + `$n.BalloonTipTitle = "${t}"; `
+      + `$n.BalloonTipText = "${b}"; `
+      + `$n.Visible = $true; `
+      + `$n.ShowBalloonTip(3000); `
+      + `Start-Sleep -Seconds 4; `
+      + `$n.Dispose()`;
+    spawnDetached('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', ps]);
+  }
+}