@klhapp/skillmux 1.11.2 → 1.13.0

package/src/types.ts

@@ -1,212 +0,0 @@
-export interface RecallConfig {
-  k_lexical: number;
-  k_vector: number;
-  k_rerank?: number;
-}
-
-export interface OutputConfig {
-  top_k: number;
-  max_top_k: number;
-}
-
-export interface Thresholds {
-  /** @deprecated Use output.top_k instead */
-  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";
-  endpoint: string;
-  model: string;
-  dimension: number;
-  api_key_env?: string;
-}
-
-export interface RemoteRerankerConfig {
-  adapter: "jina-v1" | "bifrost-v1";
-  endpoint: string;
-  model: string;
-  api_key_env?: string;
-}
-
-export interface RemoteInferenceConfig {
-  mode: "remote";
-  timeout_ms: number;
-  embedding: RemoteEmbeddingConfig;
-  reranker?: RemoteRerankerConfig;
-}
-
-export type InferenceConfig = LocalInferenceConfig | RemoteInferenceConfig;
-
-export interface RateLimitConfig {
-  enabled: boolean;
-  requests_per_minute: number;
-  trust_proxy?: boolean;
-}
-
-export interface AdminConfig {
-  enabled: boolean;
-  token_env: string;
-}
-
-export interface ServerConfig {
-  auth_enabled: boolean;
-  auth_token_env: string;
-  allowed_origins: string[];
-  hostname?: string;
-  rate_limit?: RateLimitConfig;
-  admin?: AdminConfig;
-  max_body_bytes?: number;
-  max_concurrent_requests?: number;
-}
-
-export interface ConfigPolicy {
-  environment_overrides?: boolean;
-}
-
-export interface EgressConfig {
-  allowed_hosts?: string[];
-}
-
-export interface AuditConfig {
-  /** Age in days beyond which audit rows are pruned. 0 disables pruning. */
-  retention_days: number;
-}
-
-export interface Config {
-  config?: ConfigPolicy;
-  vault_path: string;
-  local_vault_paths: string[];
-  state_dir: string;
-  recall: RecallConfig;
-  output: OutputConfig;
-  inference: InferenceConfig;
-  server?: ServerConfig;
-  audit?: AuditConfig;
-  egress?: EgressConfig;
-}
-
-export interface RankedCandidate {
-  rank: number;
-  skill_id: string;
-  description: string;
-  score: number | null;
-}
-
-export type RetrievalCapability = "exact" | "reranked" | "hybrid" | "lexical";
-
-export type DegradationReason =
-  | "embedding_timeout"
-  | "embedding_unavailable"
-  | "embedding_protocol_error"
-  | "reranker_timeout"
-  | "reranker_unavailable"
-  | "reranker_protocol_error";
-
-export interface ResolveResult {
-  request_id: string;
-  retrieval: RetrievalCapability;
-  degraded_from?: "reranked" | "hybrid";
-  degradation_reason?: DegradationReason;
-  candidates: RankedCandidate[];
-}
-
-export interface ResolveSkillInput {
-  query: string;
-  top_k?: number;
-  /** Test/ops escape hatch: use lexical retrieval only. Not exposed on the MCP wire. */
-  forceLexical?: boolean;
-}
-
-export interface FetchSkillInput {
-  skill_id: string;
-  request_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;
-  /** Null for rows written before request_id existed (AC4). */
-  request_id: string | null;
-  query: string;
-  retrieval: RetrievalCapability;
-  degraded_from?: "reranked" | "hybrid" | null;
-  degradation_reason?: DegradationReason | null;
-  candidates: AuditCandidate[];
-  latency_ms: number;
-}
-
-export interface FetchAuditRow {
-  id: number;
-  ts: string;
-  skill_id: string;
-  /** Exactly as supplied by the caller, including an unknown value. Null when the caller sent none. */
-  request_id: string | null;
-  /** Null when the fetch is uncorrelated: no request_id, an unknown/malformed one, or a pruned resolve row. */
-  resolve_audit_id: number | null;
-  /** Rank of skill_id in the correlated resolve's shortlist. Null when uncorrelated or absent from the shortlist. */
-  rank_at_resolve: number | null;
-}
-
-export interface Clients {
-  embed(texts: string[]): Promise<Float32Array[]>;
-  rerank?: (query: string, docs: { skill_id: string; text: string }[]) => Promise<number[]>;
-}

package/src/vault.ts

@@ -1,207 +0,0 @@
-import { existsSync, lstatSync, readdirSync, statSync } from "node:fs";
-import { join, relative } from "node:path";
-
-export const SKILL_ID_PATTERN = /^[a-z0-9][a-z0-9-]{1,127}$/;
-
-/** Provenance sidecar filename (see provenance.ts). Kept here, not re-imported from
- *  provenance.ts, so listSupportingFiles can exclude it without a circular import. */
-export const SKILLMUX_ORIGIN_FILENAME = ".skillmux-origin";
-
-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);
-}
-
-/** SKILL.md itself is read directly (not via listSupportingFiles, which excludes
- *  it by name) — so its own symlink-ness must be checked here. Without this, a
- *  symlinked SKILL.md reachable via a shared git-backed vault or a hand-edit would
- *  have its target's content indexed and delivered to agents as the skill body.
- *
- *  The skill directory itself must be checked too, separately from SKILL.md's own
- *  leaf check: `lstat` only refuses to follow the *final* path component, so a
- *  symlinked skill directory containing a real (non-symlink) SKILL.md file at its
- *  target silently passes the leaf check while still resolving straight through
- *  to arbitrary host content. */
-export async function readSkill(vaultPath: string, skillId: string): Promise<VaultSkill> {
-  const skillDir = join(vaultPath, skillId);
-  if (lstatSync(skillDir).isSymbolicLink()) {
-    throw new Error(`refusing to read ${skillId}: the skill directory is a symlink`);
-  }
-  const path = join(skillDir, "SKILL.md");
-  if (lstatSync(path).isSymbolicLink()) {
-    throw new Error(`refusing to read ${skillId}/SKILL.md: it is a symlink`);
-  }
-  const bytes = await Bun.file(path).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;
-}
-
-/** Local overlays checked first (in order), canonical vault_path is the fallback. */
-export function vaultResolutionOrder(vaultPath: string, localVaultPaths: string[]): string[] {
-  return [...localVaultPaths, vaultPath];
-}
-
-/** Which configured root actually backs skillId, per local-overrides-first precedence. */
-export function resolveSkillRoot(skillId: string, vaultPath: string, localVaultPaths: string[]): string | null {
-  for (const root of vaultResolutionOrder(vaultPath, localVaultPaths)) {
-    if (existsSync(join(root, skillId, "SKILL.md"))) return root;
-  }
-  return null;
-}
-
-/** Scans every configured root and merges by skill_id — first-seen (per resolution order) wins. */
-export async function scanVaults(
-  vaultPath: string,
-  localVaultPaths: string[],
-  onInvalid?: (skillId: string, error: unknown) => void,
-): Promise<VaultSkill[]> {
-  const seen = new Set<string>();
-  const merged: VaultSkill[] = [];
-  for (const root of vaultResolutionOrder(vaultPath, localVaultPaths)) {
-    if (!existsSync(root)) continue;
-    for (const skill of await scanVault(root, onInvalid)) {
-      if (seen.has(skill.skill_id)) continue;
-      seen.add(skill.skill_id);
-      merged.push(skill);
-    }
-  }
-  return merged;
-}
-
-export interface ShadowedSkill {
-  skill_id: string;
-  winner: string;
-  shadowed: string[];
-}
-
-/** skill_ids present in more than one configured root — every root after the winner is silently shadowed. */
-export function findShadowedSkills(vaultPath: string, localVaultPaths: string[]): ShadowedSkill[] {
-  const rootsBySkillId = new Map<string, string[]>();
-  for (const root of vaultResolutionOrder(vaultPath, localVaultPaths)) {
-    if (!existsSync(root)) continue;
-    for (const entry of readdirSync(root, { withFileTypes: true })) {
-      if (!entry.isDirectory() || !SKILL_ID_PATTERN.test(entry.name)) continue;
-      if (!existsSync(join(root, entry.name, "SKILL.md"))) continue;
-      const roots = rootsBySkillId.get(entry.name) ?? [];
-      roots.push(root);
-      rootsBySkillId.set(entry.name, roots);
-    }
-  }
-  const shadowed: ShadowedSkill[] = [];
-  for (const [skillId, roots] of rootsBySkillId) {
-    if (roots.length > 1) shadowed.push({ skill_id: skillId, winner: roots[0]!, shadowed: roots.slice(1) });
-  }
-  return shadowed.sort((a, b) => a.skill_id.localeCompare(b.skill_id));
-}
-
-/** Relative paths of everything under the skill dir except SKILL.md and the
- *  provenance sidecar, sorted. Symlinks are excluded rather than followed —
- *  install/sync already refuse a skill containing one, but a symlink can still
- *  reach the vault directly (a shared git-backed vault pulled in, or a hand-edit),
- *  and this function otherwise feeds skill content straight into content
- *  scanning (scan.ts) and drift hashing (provenance.ts). `skillId` must be a
- *  single path segment — not the stricter SKILL_ID_PATTERN, since scanPath's
- *  ad-hoc single-directory mode legitimately passes an arbitrary, not-yet-
- *  normalized directory name — so `..`/`.`/a path separator is rejected to
- *  keep the walk inside `vaultPath` without breaking that mode. */
-export function listSupportingFiles(vaultPath: string, skillId: string): string[] {
-  if (skillId === "" || skillId === "." || skillId === ".." || skillId.includes("/") || skillId.includes("\\")) {
-    return [];
-  }
-  const root = join(vaultPath, skillId);
-  // A symlinked skill directory must not be walked into: readdirSync follows a
-  // symlinked path argument (unlike the entry.isSymbolicLink() check below, which
-  // only applies to entries *found by* the walk), so without this a symlinked
-  // `root` would return the target directory's file listing straight through.
-  if (!existsSync(root) || lstatSync(root).isSymbolicLink()) return [];
-  const files: string[] = [];
-  const walk = (dir: string) => {
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-      if (entry.isSymbolicLink()) continue;
-      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" && rel !== SKILLMUX_ORIGIN_FILENAME) 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;
-  }
-}