@klhapp/skillmux 0.2.0

package/src/stats.ts

@@ -0,0 +1,165 @@
+import type { Database } from "bun:sqlite";
+import type { AuditCandidate, AuditRow } from "./types";
+
+export const SINCE_PATTERN = /^(\d+[hdwmy]|\d{4}-\d{2}-\d{2}([T ].+)?)$/;
+
+export interface SkillStat {
+  skill_id: string;
+  matched_count: number;
+  candidate_count: number;
+}
+
+export interface NoMatchQuery {
+  query: string;
+  count: number;
+}
+
+export interface StatsResponse {
+  since: string;
+  until: string;
+  outcome_totals: { matched: number; ambiguous: number; no_match: number };
+  ambiguous_rate: number;
+  skills: SkillStat[];
+  top_no_match_queries: NoMatchQuery[];
+}
+
+const RELATIVE_WINDOW = /^(\d+)([hdwmy])$/;
+const UNIT_MS: Record<string, number> = {
+  h: 3_600_000,
+  d: 86_400_000,
+  w: 604_800_000,
+  m: 2_592_000_000,
+  y: 31_536_000_000,
+};
+
+export function parseSince(since: string, now: Date = new Date()): Date {
+  if (!SINCE_PATTERN.test(since)) throw new Error(`invalid --since window: ${since}`);
+
+  const relative = RELATIVE_WINDOW.exec(since);
+  if (relative) {
+    const amount = Number(relative[1]);
+    const unitMs = UNIT_MS[relative[2]!]!;
+    return new Date(now.getTime() - amount * unitMs);
+  }
+
+  const parsed = new Date(since);
+  if (Number.isNaN(parsed.getTime())) throw new Error(`invalid --since window: ${since}`);
+  return parsed;
+}
+
+export function computeStats(rows: AuditRow[], since: Date, until: Date): StatsResponse {
+  const outcome_totals = { matched: 0, ambiguous: 0, no_match: 0 };
+  const skillStats = new Map<string, { matched_count: number; candidate_count: number }>();
+  const noMatchCounts = new Map<string, number>();
+
+  function statFor(skillId: string) {
+    let stat = skillStats.get(skillId);
+    if (!stat) {
+      stat = { matched_count: 0, candidate_count: 0 };
+      skillStats.set(skillId, stat);
+    }
+    return stat;
+  }
+
+  for (const row of rows) {
+    outcome_totals[row.outcome]++;
+
+    const seenInRow = new Set<string>();
+    for (const candidate of row.candidates) {
+      if (seenInRow.has(candidate.skill_id)) continue;
+      seenInRow.add(candidate.skill_id);
+      statFor(candidate.skill_id).candidate_count++;
+    }
+
+    if (row.outcome === "matched" && row.selected_skill_id) {
+      statFor(row.selected_skill_id).matched_count++;
+    }
+
+    if (row.outcome === "no_match") {
+      noMatchCounts.set(row.query, (noMatchCounts.get(row.query) ?? 0) + 1);
+    }
+  }
+
+  const total = outcome_totals.matched + outcome_totals.ambiguous + outcome_totals.no_match;
+  const ambiguous_rate = total > 0 ? outcome_totals.ambiguous / total : 0;
+
+  const skills = [...skillStats.entries()]
+    .map(([skill_id, stat]) => ({ skill_id, ...stat }))
+    .sort((a, b) => b.matched_count - a.matched_count);
+
+  const top_no_match_queries = [...noMatchCounts.entries()]
+    .map(([query, count]) => ({ query, count }))
+    .sort((a, b) => b.count - a.count)
+    .slice(0, 20);
+
+  return {
+    since: since.toISOString(),
+    until: until.toISOString(),
+    outcome_totals,
+    ambiguous_rate,
+    skills,
+    top_no_match_queries,
+  };
+}
+
+interface AuditTableRow {
+  id: number;
+  ts: string;
+  query: string;
+  outcome: AuditRow["outcome"];
+  retrieval: AuditRow["retrieval"];
+  candidates: string;
+  selected_skill_id: string | null;
+  latency_ms: number;
+}
+
+export function queryAuditRows(db: Database, sinceIso: string): AuditRow[] {
+  const rows = db
+    .query("SELECT id, ts, query, outcome, retrieval, candidates, selected_skill_id, latency_ms FROM audit WHERE ts >= ? ORDER BY ts ASC")
+    .all(sinceIso) as AuditTableRow[];
+  return rows.map((row) => ({
+    id: row.id,
+    ts: row.ts,
+    query: row.query,
+    outcome: row.outcome,
+    retrieval: row.retrieval,
+    candidates: JSON.parse(row.candidates) as AuditCandidate[],
+    selected_skill_id: row.selected_skill_id,
+    latency_ms: row.latency_ms,
+  }));
+}
+
+export function getStats(db: Database, since: string, now: Date = new Date()): StatsResponse {
+  const sinceDate = parseSince(since, now);
+  const rows = queryAuditRows(db, sinceDate.toISOString());
+  return computeStats(rows, sinceDate, now);
+}
+
+export function renderStatsText(stats: StatsResponse): string {
+  const lines: string[] = [];
+  lines.push(`window: ${stats.since} .. ${stats.until}`);
+  lines.push(
+    `outcomes: matched=${stats.outcome_totals.matched} ambiguous=${stats.outcome_totals.ambiguous} ` +
+      `no_match=${stats.outcome_totals.no_match} (ambiguous_rate=${stats.ambiguous_rate.toFixed(3)})`,
+  );
+
+  lines.push("skills:");
+  if (stats.skills.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const skill of stats.skills) {
+      lines.push(`  ${skill.skill_id} matched=${skill.matched_count} candidate=${skill.candidate_count}`);
+    }
+  }
+
+  lines.push("top no_match queries:");
+  if (stats.top_no_match_queries.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const entry of stats.top_no_match_queries) {
+      lines.push(`  "${entry.query}" (${entry.count})`);
+    }
+  }
+
+  return lines.join("\n");
+}

package/src/sync.ts

@@ -0,0 +1,182 @@
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, rmSync, symlinkSync, unlinkSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, relative } from "node:path";
+
+export const SKILLMUX_MARKER_FILENAME = ".skillmux";
+export const LEGACY_MARKER_FILENAME = ".skr";
+
+export interface SkillmuxMarker {
+  managed_by: "skillmux" | "skr";
+  target: string;
+  created_at: string;
+}
+
+export function readSkillmuxMarker(dir: string): SkillmuxMarker | null {
+  const newPath = join(dir, SKILLMUX_MARKER_FILENAME);
+  if (existsSync(newPath)) {
+    return JSON.parse(readFileSync(newPath, "utf-8")) as SkillmuxMarker;
+  }
+  const legacyPath = join(dir, LEGACY_MARKER_FILENAME);
+  if (existsSync(legacyPath)) {
+    return JSON.parse(readFileSync(legacyPath, "utf-8")) as SkillmuxMarker;
+  }
+  return null;
+}
+
+function writeSkillmuxMarker(dir: string, targetName: string): void {
+  const marker: SkillmuxMarker = {
+    managed_by: "skillmux",
+    target: targetName,
+    created_at: new Date().toISOString(),
+  };
+  writeFileSync(join(dir, SKILLMUX_MARKER_FILENAME), JSON.stringify(marker, null, 2));
+}
+
+export interface SyncTargetParams {
+  vaultPath: string;
+  targetDir: string;
+  targetName: string;
+  coreSkillIds: string[];
+}
+
+export interface SyncTargetResult {
+  added: string[];
+  removed: string[];
+}
+
+export interface SyncTargetOptions {
+  dryRun?: boolean;
+}
+
+export function syncTarget(params: SyncTargetParams, options: SyncTargetOptions = {}): SyncTargetResult {
+  const { vaultPath, targetDir, targetName, coreSkillIds } = params;
+  const { dryRun = false } = options;
+
+  if (!existsSync(targetDir)) {
+    if (dryRun) return { added: [...coreSkillIds], removed: [] };
+    mkdirSync(targetDir, { recursive: true });
+    for (const skillId of coreSkillIds) {
+      symlinkSync(join(vaultPath, skillId), join(targetDir, skillId));
+    }
+    writeSkillmuxMarker(targetDir, targetName);
+    return { added: [...coreSkillIds], removed: [] };
+  }
+
+  if (!readSkillmuxMarker(targetDir)) {
+    throw new Error(`not owned by skillmux — run skillmux init`);
+  }
+
+  const desired = new Set(coreSkillIds);
+  const existing = readdirSync(targetDir).filter((name) => name !== SKILLMUX_MARKER_FILENAME && name !== LEGACY_MARKER_FILENAME);
+
+  const removed = existing.filter((name) => !desired.has(name));
+  const added = coreSkillIds.filter((skillId) => !existing.includes(skillId));
+  if (dryRun) return { added, removed };
+
+  for (const name of removed) unlinkSync(join(targetDir, name));
+  for (const skillId of added) symlinkSync(join(vaultPath, skillId), join(targetDir, skillId));
+
+  return { added, removed };
+}
+
+export interface AdoptTargetResult {
+  adopted: boolean;
+}
+
+/**
+ * Marks an existing directory as skillmux-owned without touching its content —
+ * the consented, one-time adoption skillmux init performs (see SkillmuxMarker in
+ * schema.json: "the only path allowed to create a .skillmux marker on a
+ * previously-unmarked directory"). syncTarget's fresh-dir case handles the
+ * "doesn't exist yet" side of that rule; this handles "already exists".
+ */
+export function adoptTarget(dir: string, targetName: string): AdoptTargetResult {
+  if (readSkillmuxMarker(dir)) return { adopted: false };
+  writeSkillmuxMarker(dir, targetName);
+  return { adopted: true };
+}
+
+export interface RestoreMonolithResult {
+  restored: boolean;
+}
+
+export function restoreMonolith(targetDir: string, vaultPath: string): RestoreMonolithResult {
+  if (!readSkillmuxMarker(targetDir)) {
+    return { restored: false };
+  }
+  rmSync(targetDir, { recursive: true, force: true });
+  symlinkSync(vaultPath, targetDir);
+  return { restored: true };
+}
+
+export function resolveProjectPinDir(targetDir: string, repo: string): string {
+  const rel = relative(homedir(), targetDir);
+  if (rel === "" || rel.startsWith("..")) {
+    throw new Error(
+      `target dir "${targetDir}" must be inside $HOME to compute a project pin dir (got relative path "${rel}")`,
+    );
+  }
+  return join(repo, rel);
+}
+
+export interface ProjectGroupInput {
+  repos: string[];
+  skills: string[];
+}
+
+export interface SyncProjectTargetsParams {
+  vaultPath: string;
+  targetDir: string;
+  targetName: string;
+  projectGroups: Record<string, ProjectGroupInput>;
+}
+
+export interface ProjectPinSyncResult extends SyncTargetResult {
+  group: string;
+  repo: string;
+  pinDir: string;
+}
+
+export function syncProjectTargets(
+  params: SyncProjectTargetsParams,
+  options: SyncTargetOptions = {},
+): ProjectPinSyncResult[] {
+  const { vaultPath, targetDir, targetName, projectGroups } = params;
+  const results: ProjectPinSyncResult[] = [];
+
+  for (const [group, projectGroup] of Object.entries(projectGroups)) {
+    for (const repo of projectGroup.repos) {
+      if (!existsSync(repo)) continue;
+      const pinDir = resolveProjectPinDir(targetDir, repo);
+      const result = syncTarget(
+        { vaultPath, targetDir: pinDir, targetName, coreSkillIds: projectGroup.skills },
+        options,
+      );
+      results.push({ group, repo, pinDir, ...result });
+    }
+  }
+
+  return results;
+}
+
+export const HOOK_MARKER = "# managed-by: skillmux sync --install-hook";
+export const LEGACY_HOOK_MARKER = "# managed-by: skr sync --install-hook";
+
+export interface InstallHookResult {
+  installed: boolean;
+}
+
+export function installPostMergeHook(vaultPath: string): InstallHookResult {
+  const hookPath = join(vaultPath, ".git", "hooks", "post-merge");
+
+  if (existsSync(hookPath)) {
+    const existing = readFileSync(hookPath, "utf-8");
+    if (existing.includes(HOOK_MARKER) || existing.includes(LEGACY_HOOK_MARKER)) return { installed: false };
+    throw new Error(`${hookPath} already exists and is not managed by skillmux — refusing to overwrite`);
+  }
+
+  const script = `#!/bin/sh\n${HOOK_MARKER}\nskillmux sync\n`;
+  writeFileSync(hookPath, script);
+  chmodSync(hookPath, 0o755);
+  return { installed: true };
+}

package/src/types.ts

@@ -0,0 +1,178 @@
+export interface RecallConfig {
+  k_lexical: number;
+  k_vector: number;
+}
+
+export interface Thresholds {
+  candidate_limit: number;
+  match_score?: number;
+  match_margin?: number;
+  candidate_floor?: number;
+}
+
+export type ONNXDevice =
+  | "cpu"
+  | "auto"
+  | "gpu"
+  | "wasm"
+  | "webgpu"
+  | "cuda"
+  | "dml"
+  | "coreml"
+  | "webnn"
+  | "webnn-npu"
+  | "webnn-gpu"
+  | "webnn-cpu";
+
+export type ONNXDtype =
+  | "q8"
+  | "auto"
+  | "fp32"
+  | "fp16"
+  | "int8"
+  | "uint8"
+  | "q4"
+  | "bnb4"
+  | "q4f16"
+  | "q2"
+  | "q2f16"
+  | "q1"
+  | "q1f16";
+
+export interface ModelConfig {
+  model: string;
+  device?: ONNXDevice;
+  dtype?: ONNXDtype;
+}
+
+export interface LocalInferenceConfig {
+  mode: "local";
+  bundle: string;
+  models_dir: string;
+  embedding: ModelConfig & { dimension: number };
+}
+
+export interface RemoteEmbeddingConfig {
+  provider: "openai";
+  base_url: string;
+  model: string;
+  dimension: number;
+  api_key_env?: string;
+}
+
+export interface RemoteRerankerConfig {
+  provider: "infinity";
+  base_url: string;
+  model: string;
+  api_key_env?: string;
+}
+
+export interface RemoteInferenceConfig {
+  mode: "remote";
+  timeout_ms: number;
+  embedding: RemoteEmbeddingConfig;
+  reranker?: RemoteRerankerConfig;
+  thresholds?: Required<Omit<Thresholds, "candidate_limit">>;
+}
+
+export type InferenceConfig = LocalInferenceConfig | RemoteInferenceConfig;
+
+export interface RateLimitConfig {
+  enabled: boolean;
+  requests_per_minute: number;
+  trust_proxy?: boolean;
+}
+
+export interface ServerConfig {
+  auth_enabled: boolean;
+  auth_token_env: string;
+  allowed_origins: string[];
+  hostname?: string;
+  rate_limit?: RateLimitConfig;
+}
+
+export interface Config {
+  vault_path: string;
+  state_dir: string;
+  recall: RecallConfig;
+  thresholds: Thresholds;
+  inference: InferenceConfig;
+  server?: ServerConfig;
+}
+
+export interface Candidate {
+  skill_id: string;
+  title: string;
+  description: string;
+}
+
+export interface RankedCandidate extends Candidate {
+  score: number | null;
+}
+
+export type RetrievalCapability = "exact" | "reranked" | "hybrid" | "lexical";
+
+export interface MatchedResult {
+  outcome: "matched";
+  retrieval: "exact" | "reranked";
+  skill_id: string;
+  title: string;
+  content_sha256: string;
+  score: number;
+  margin: number;
+  body: string;
+  files: string[];
+}
+
+export interface AmbiguousResult {
+  outcome: "ambiguous";
+  retrieval: RetrievalCapability;
+  candidates: Candidate[];
+}
+
+export interface NoMatchResult {
+  outcome: "no_match";
+  retrieval: RetrievalCapability;
+  message: string;
+}
+
+export type ResolveResult = MatchedResult | AmbiguousResult | NoMatchResult;
+
+export interface ResolveSkillInput {
+  query: string;
+  /** Test/ops escape hatch: use lexical retrieval only. Not exposed on the MCP wire. */
+  forceLexical?: boolean;
+}
+
+export interface FetchSkillInput {
+  skill_id: string;
+}
+
+export interface FetchSkillResult {
+  skill_id: string;
+  title: string;
+  content_sha256: string;
+  body: string;
+  files: string[];
+}
+
+export interface AuditCandidate {
+  skill_id: string;
+  score: number | null;
+}
+
+export interface AuditRow {
+  id: number;
+  ts: string;
+  query: string;
+  outcome: "matched" | "ambiguous" | "no_match";
+  retrieval: RetrievalCapability;
+  candidates: AuditCandidate[];
+  selected_skill_id: string | null;
+  latency_ms: number;
+}
+
+export interface Clients {
+  embed(texts: string[]): Promise<Float32Array[]>;
+  rerank?: (query: string, docs: { skill_id: string; text: string }[]) => Promise<number[]>;
+}

package/src/vault.ts

@@ -0,0 +1,109 @@
+import { readdirSync, statSync } from "node:fs";
+import { join, relative } from "node:path";
+
+export const SKILL_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,127}$/;
+
+export interface VaultSkill {
+  skill_id: string;
+  title: string;
+  description: string;
+  aliases: string[];
+  body: string;
+  content_sha256: string;
+}
+
+export function sha256Hex(data: string | Uint8Array): string {
+  return new Bun.CryptoHasher("sha256").update(data).digest("hex");
+}
+
+interface Frontmatter {
+  name?: unknown;
+  description?: unknown;
+  aliases?: unknown;
+}
+
+export function parseSkillMd(skillId: string, raw: string): VaultSkill {
+  let fm: Frontmatter = {};
+  if (raw.startsWith("---\n")) {
+    const end = raw.indexOf("\n---", 4);
+    if (end === -1) throw new Error(`unterminated frontmatter in ${skillId}/SKILL.md`);
+    fm = (Bun.YAML.parse(raw.slice(4, end)) ?? {}) as Frontmatter;
+  }
+  const aliases = Array.isArray(fm.aliases) ? fm.aliases.map(String) : [];
+  return {
+    skill_id: skillId,
+    title: typeof fm.name === "string" && fm.name.length > 0 ? fm.name : skillId,
+    description: typeof fm.description === "string" ? fm.description : "",
+    aliases,
+    body: raw,
+    content_sha256: sha256Hex(raw),
+  };
+}
+
+/** Strict decode: invalid UTF-8 throws instead of silently mangling content. */
+export function decodeUtf8Strict(bytes: Uint8Array): string {
+  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+}
+
+export async function readSkill(vaultPath: string, skillId: string): Promise<VaultSkill> {
+  const bytes = await Bun.file(join(vaultPath, skillId, "SKILL.md")).bytes();
+  return parseSkillMd(skillId, decodeUtf8Strict(bytes));
+}
+
+export async function scanVault(
+  vaultPath: string,
+  onInvalid?: (skillId: string, error: unknown) => void,
+): Promise<VaultSkill[]> {
+  const skills: VaultSkill[] = [];
+  for (const entry of readdirSync(vaultPath, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !SKILL_ID_PATTERN.test(entry.name)) continue;
+    try {
+      skills.push(await readSkill(vaultPath, entry.name));
+    } catch (error) {
+      onInvalid?.(entry.name, error);
+    }
+  }
+  return skills;
+}
+
+/** Relative paths of everything under the skill dir except SKILL.md itself, sorted. */
+export function listSupportingFiles(vaultPath: string, skillId: string): string[] {
+  const root = join(vaultPath, skillId);
+  const files: string[] = [];
+  const walk = (dir: string) => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const abs = join(dir, entry.name);
+      if (entry.isDirectory()) walk(abs);
+      else if (statSync(abs).isFile()) {
+        const rel = relative(root, abs);
+        if (rel !== "SKILL.md") files.push(rel);
+      }
+    }
+  };
+  walk(root);
+  return files.sort();
+}
+
+export function getVaultMaxMtime(vaultPath: string): number {
+  try {
+    let maxMtime = statSync(vaultPath).mtimeMs;
+    const entries = readdirSync(vaultPath, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory() && SKILL_ID_PATTERN.test(entry.name)) {
+        try {
+          const folderPath = join(vaultPath, entry.name);
+          const folderMtime = statSync(folderPath).mtimeMs;
+          maxMtime = Math.max(maxMtime, folderMtime);
+
+          const fileMtime = statSync(join(folderPath, "SKILL.md")).mtimeMs;
+          maxMtime = Math.max(maxMtime, fileMtime);
+        } catch {
+          // Ignore deleted files
+        }
+      }
+    }
+    return maxMtime;
+  } catch {
+    return 0;
+  }
+}