@klhapp/skillmux 0.2.0 → 0.4.2

package/src/clients.ts

@@ -72,7 +72,9 @@ export function createClients(config: Config): Clients {
 
       const embedding = config.inference.embedding;
       const apiKey = embedding.api_key_env ? process.env[embedding.api_key_env] : undefined;
-      const response = await fetch(`${embedding.base_url.replace(/\/$/, "")}/v1/embeddings`, {
+      const cleanBase = embedding.base_url.replace(/\/$/, "");
+      const embedPath = cleanBase.endsWith("/v1") ? "/embeddings" : "/v1/embeddings";
+      const response = await fetch(`${cleanBase}${embedPath}`, {
         method: "POST",
         headers: {
           "content-type": "application/json",

package/src/completions.ts

@@ -0,0 +1,84 @@
+export type ShellType = "bash" | "zsh" | "fish";
+
+export function generateCompletions(shell: ShellType): string {
+  if (shell === "bash") {
+    return `# bash completion for skillmux
+_skillmux_completions() {
+    local cur prev opts
+    COMPREPLY=()
+    cur="\${COMP_WORDS[COMP_CWORD]}"
+    prev="\${COMP_WORDS[COMP_CWORD-1]}"
+    opts="context config calibrate serve index sync init report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
+
+    if [ "$COMP_CWORD" -eq 1 ]; then
+        COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
+        return 0
+    fi
+
+    case "$prev" in
+        context)
+            COMPREPLY=( $(compgen -W "add list current use remove" -- "$cur") )
+            ;;
+        config)
+            COMPREPLY=( $(compgen -W "show get validate diff set status" -- "$cur") )
+            ;;
+        calibrate)
+            COMPREPLY=( $(compgen -W "run list show apply generate-dataset" -- "$cur") )
+            ;;
+        completions)
+            COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+            ;;
+        manifest)
+            COMPREPLY=( $(compgen -W "pin unpin" -- "$cur") )
+            ;;
+        local-vault)
+            COMPREPLY=( $(compgen -W "init" -- "$cur") )
+            ;;
+    esac
+}
+complete -F _skillmux_completions skillmux
+`;
+  }
+
+  if (shell === "zsh") {
+    return `#compdef skillmux
+_skillmux() {
+    local -a commands
+    commands=(
+        'context:Manage connection contexts'
+        'config:Manage configuration'
+        'calibrate:Manage policy calibration'
+        'serve:Start MCP server'
+        'index:Rebuild local search index'
+        'sync:Synchronize vault skills'
+        'init:Initialize project targets'
+        'report:Generate usage stats'
+        'scan:Audit skills for issues'
+        'install:Install skills into vault'
+        'eval:Evaluate search accuracy'
+        'doctor:Check runtime health'
+        'which:Show which root resolves a skill_id'
+        'manifest:Pin/unpin skills into [core] or [project.*]'
+        'local-vault:Manage local_vault_paths discoverability markers'
+        'models:Manage local models'
+        'completions:Generate shell completions'
+    )
+    _describe -t commands 'skillmux command' commands
+}
+_skillmux "$@"
+`;
+  }
+
+  if (shell === "fish") {
+    return `# fish completion for skillmux
+complete -c skillmux -f
+complete -c skillmux -n "__fish_use_subcommand" -a context -d "Manage connection contexts"
+complete -c skillmux -n "__fish_use_subcommand" -a config -d "Manage configuration"
+complete -c skillmux -n "__fish_use_subcommand" -a calibrate -d "Manage policy calibration"
+complete -c skillmux -n "__fish_use_subcommand" -a serve -d "Start MCP server"
+complete -c skillmux -n "__fish_use_subcommand" -a completions -d "Generate shell completions"
+`;
+  }
+
+  throw new Error(`Unsupported shell: ${shell}`);
+}

package/src/config-service.ts

@@ -0,0 +1,408 @@
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { DEFAULT_CONFIG_PATH, expandHome, loadConfig } from "./config";
+import type { Config } from "./types";
+
+export type ConfigSource = "default" | "toml" | "environment";
+export type ConfigSourceMap = Record<string, ConfigSource>;
+
+export interface SetConfigResult {
+  ok: boolean;
+  key: string;
+  prior_val: unknown;
+  resulting_val: unknown;
+  target: string;
+  prior_revision: string;
+  resulting_revision: string;
+  persistence: "persisted" | "not_persisted" | "failed";
+  application: "activated" | "restart_required" | "failed";
+  readiness: { status: "ready" | "degraded" | "not_ready" | "stopping"; capability: string };
+  restart_required_keys: string[];
+}
+
+export interface ConfigStatusResponse {
+  target: string;
+  desired_source: string;
+  desired_source_hash: string;
+  active_revision: string;
+  active_source_hash: string;
+  last_successful_reload_at: string | null;
+  last_reload_error: string | null;
+  readiness: { status: "ready" | "degraded" | "not_ready" | "stopping"; capability: string };
+  restart_required_keys: string[];
+  runtime: "running" | "not_running";
+}
+
+export const RESTART_REQUIRED_KEYS = [
+  "server.hostname",
+  "server.auth_enabled",
+  "server.auth_token_env",
+  "server.admin.enabled",
+  "server.admin.token_env",
+  "inference.mode",
+  "inference.bundle",
+  "inference.models_dir",
+  "state_dir",
+];
+
+export const RELOADABLE_KEYS = [
+  "vault_path",
+  "recall.k_lexical",
+  "recall.k_vector",
+  "thresholds.candidate_limit",
+  "thresholds.match_score",
+  "thresholds.match_margin",
+  "thresholds.candidate_floor",
+  "inference.embedding.model",
+  "inference.embedding.dimension",
+  "inference.embedding.device",
+  "inference.embedding.dtype",
+  "inference.embedding.base_url",
+  "inference.embedding.api_key_env",
+  "server.rate_limit.enabled",
+  "server.rate_limit.requests_per_minute",
+  "server.rate_limit.trust_proxy",
+];
+
+export function getNestedValue(obj: Record<string, any>, path: string): unknown {
+  const parts = path.split(".");
+  let cur = obj;
+  for (const part of parts) {
+    if (cur === undefined || cur === null || typeof cur !== "object") return undefined;
+    cur = cur[part];
+  }
+  return cur;
+}
+
+export function setNestedValue(obj: Record<string, any>, path: string, value: unknown): void {
+  const parts = path.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i]!;
+    if (!cur[part] || typeof cur[part] !== "object") {
+      cur[part] = {};
+    }
+    cur = cur[part];
+  }
+  const lastPart = parts[parts.length - 1]!;
+  cur[lastPart] = value;
+}
+
+export function deleteNestedValue(obj: Record<string, any>, path: string): void {
+  const parts = path.split(".");
+  let cur = obj;
+  for (let i = 0; i < parts.length - 1; i++) {
+    const part = parts[i]!;
+    if (!cur[part]) return;
+    cur = cur[part];
+  }
+  const lastPart = parts[parts.length - 1]!;
+  delete cur[lastPart];
+}
+
+export function computeHash(data: unknown): string {
+  const str = typeof data === "string" ? data : JSON.stringify(data);
+  return createHash("sha256").update(str).digest("hex").slice(0, 16);
+}
+
+export async function getEffectiveConfig(configPath?: string): Promise<{
+  effective: Config;
+  sources: ConfigSourceMap;
+  rawToml: Record<string, unknown>;
+}> {
+  const path = configPath ?? DEFAULT_CONFIG_PATH;
+  const effective = await loadConfig(path);
+  const rawToml: Record<string, unknown> = {};
+
+  const fullPath = expandHome(path);
+  if (existsSync(fullPath)) {
+    try {
+      const text = await Bun.file(fullPath).text();
+      const parsed = Bun.TOML.parse(text);
+      if (typeof parsed === "object" && parsed !== null) {
+        Object.assign(rawToml, parsed);
+      }
+    } catch {
+      // empty if unparseable
+    }
+  }
+
+  const sources: ConfigSourceMap = {};
+
+  const allKeys = [
+    "vault_path",
+    "state_dir",
+    "recall.k_lexical",
+    "recall.k_vector",
+    "thresholds.candidate_limit",
+    "thresholds.match_score",
+    "thresholds.match_margin",
+    "thresholds.candidate_floor",
+    "inference.mode",
+    "inference.bundle",
+    "inference.models_dir",
+    "inference.embedding.model",
+    "inference.embedding.dimension",
+    "inference.embedding.device",
+    "inference.embedding.dtype",
+    "inference.embedding.base_url",
+    "inference.embedding.api_key_env",
+    "inference.timeout_ms",
+    "server.auth_enabled",
+    "server.auth_token_env",
+    "server.admin.enabled",
+    "server.admin.token_env",
+    "server.hostname",
+    "server.rate_limit.enabled",
+    "server.rate_limit.requests_per_minute",
+    "server.rate_limit.trust_proxy",
+  ];
+
+  for (const key of allKeys) {
+    if (isEnvMasked(key)) {
+      sources[key] = "environment";
+    } else if (getNestedValue(rawToml, key) !== undefined) {
+      sources[key] = "toml";
+    } else {
+      sources[key] = "default";
+    }
+  }
+
+  return { effective, sources, rawToml };
+}
+
+export function isEnvMasked(key: string): boolean {
+  if (key === "vault_path" && process.env.VAULT_PATH) return true;
+  if (key === "state_dir" && process.env.STATE_DIR) return true;
+  if (key === "inference.models_dir" && (process.env.SKILLMUX_MODELS_DIR || process.env.SKILL_ROUTER_MODELS_DIR)) return true;
+  if (key === "inference.embedding.device" && process.env.EMBED_DEVICE) return true;
+  if (key === "inference.embedding.dtype" && process.env.EMBED_DTYPE) return true;
+  if (key === "inference.embedding.base_url" && (process.env.SKILLMUX_EMBED_BASE_URL || process.env.EMBED_BASE_URL)) return true;
+  if (key === "inference.embedding.model" && (process.env.SKILLMUX_EMBED_MODEL || process.env.EMBED_MODEL)) return true;
+  if (key === "server.auth_enabled" && process.env.HTTP_AUTH_ENABLED) return true;
+  if (key === "server.auth_token_env" && process.env.HTTP_AUTH_TOKEN_ENV) return true;
+  if (key === "server.hostname" && process.env.HTTP_HOSTNAME) return true;
+  if (key === "server.rate_limit.enabled" && (process.env.SKILLMUX_HTTP_RATE_LIMIT_ENABLED || process.env.HTTP_RATE_LIMIT_ENABLED)) return true;
+  if (key === "server.rate_limit.requests_per_minute" && (process.env.SKILLMUX_HTTP_RATE_LIMIT_RPM || process.env.HTTP_RATE_LIMIT_RPM)) return true;
+  if (key === "server.rate_limit.trust_proxy" && (process.env.SKILLMUX_HTTP_RATE_LIMIT_TRUST_PROXY || process.env.HTTP_RATE_LIMIT_TRUST_PROXY)) return true;
+  return false;
+}
+
+export function validateDottedKey(key: string): void {
+  const allowed = new Set([
+    "vault_path",
+    "state_dir",
+    "recall.k_lexical",
+    "recall.k_vector",
+    "thresholds.candidate_limit",
+    "thresholds.match_score",
+    "thresholds.match_margin",
+    "thresholds.candidate_floor",
+    "inference.mode",
+    "inference.bundle",
+    "inference.models_dir",
+    "inference.embedding.model",
+    "inference.embedding.dimension",
+    "inference.embedding.device",
+    "inference.embedding.dtype",
+    "inference.embedding.base_url",
+    "inference.embedding.api_key_env",
+    "inference.timeout_ms",
+    "server.auth_enabled",
+    "server.auth_token_env",
+    "server.admin.enabled",
+    "server.admin.token_env",
+    "server.hostname",
+    "server.rate_limit.enabled",
+    "server.rate_limit.requests_per_minute",
+    "server.rate_limit.trust_proxy",
+  ]);
+  if (!allowed.has(key)) {
+    throw new Error(`Unknown configuration key "${key}"`);
+  }
+}
+
+export function parseDottedValue(key: string, valueStr: string): unknown {
+  if (valueStr === "true") return true;
+  if (valueStr === "false") return false;
+  if (/^-?\d+$/.test(valueStr)) return parseInt(valueStr, 10);
+  if (/^-?\d+\.\d+$/.test(valueStr)) return parseFloat(valueStr);
+
+  const numberKeys = new Set([
+    "recall.k_lexical",
+    "recall.k_vector",
+    "thresholds.candidate_limit",
+    "thresholds.match_score",
+    "thresholds.match_margin",
+    "thresholds.candidate_floor",
+    "inference.embedding.dimension",
+    "inference.timeout_ms",
+    "server.rate_limit.requests_per_minute",
+  ]);
+
+  if (numberKeys.has(key)) {
+    const num = Number(valueStr);
+    if (isNaN(num)) {
+      throw new Error(`Key "${key}" expects a numeric value, got "${valueStr}"`);
+    }
+    return num;
+  }
+
+  const booleanKeys = new Set([
+    "server.auth_enabled",
+    "server.admin.enabled",
+    "server.rate_limit.enabled",
+    "server.rate_limit.trust_proxy",
+  ]);
+
+  if (booleanKeys.has(key)) {
+    throw new Error(`Key "${key}" expects a boolean value ("true" or "false"), got "${valueStr}"`);
+  }
+
+  return valueStr;
+}
+
+export async function getDottedKey(key: string, configPath?: string): Promise<unknown> {
+  validateDottedKey(key);
+  const { effective } = await getEffectiveConfig(configPath);
+  return getNestedValue(effective as Record<string, any>, key);
+}
+
+export async function setDottedKey(
+  key: string,
+  rawValStr: string,
+  opts?: { configPath?: string; dryRun?: boolean; targetName?: string }
+): Promise<SetConfigResult> {
+  validateDottedKey(key);
+  if (isEnvMasked(key)) {
+    throw new Error(`Cannot set environment-masked configuration key "${key}"`);
+  }
+
+  const path = opts?.configPath ?? DEFAULT_CONFIG_PATH;
+  const targetName = opts?.targetName ?? "local";
+
+  const { effective: priorEffective, rawToml } = await getEffectiveConfig(path);
+  const priorVal = getNestedValue(priorEffective as Record<string, any>, key);
+  const parsedVal = parseDottedValue(key, rawValStr);
+
+  const updatedToml = structuredClone(rawToml);
+  setNestedValue(updatedToml, key, parsedVal);
+
+  const priorRevision = computeHash(priorEffective);
+
+  let resultingRevision = priorRevision;
+  let persistence: "persisted" | "not_persisted" | "failed" = "not_persisted";
+
+  if (!opts?.dryRun) {
+    const fullPath = expandHome(path);
+    const dir = dirname(fullPath);
+    mkdirSync(dir, { recursive: true });
+
+    let existingMode = 0o644;
+    if (existsSync(fullPath)) {
+      try {
+        existingMode = statSync(fullPath).mode;
+      } catch {
+        // default
+      }
+    }
+
+    const tmpPath = join(dir, `.config-${Math.random().toString(36).slice(2)}.tmp`);
+    const newTomlText = stringifyToml(updatedToml);
+    writeFileSync(tmpPath, newTomlText, { mode: existingMode, encoding: "utf-8" });
+    renameSync(tmpPath, fullPath);
+
+    persistence = "persisted";
+
+    const { effective: newEffective } = await getEffectiveConfig(path);
+    resultingRevision = computeHash(newEffective);
+  }
+
+  const isRestartRequired = RESTART_REQUIRED_KEYS.some((k) => key === k || key.startsWith(k + "."));
+  const application = isRestartRequired ? "restart_required" : "activated";
+
+  return {
+    ok: true,
+    key,
+    prior_val: priorVal,
+    resulting_val: parsedVal,
+    target: targetName,
+    prior_revision: priorRevision,
+    resulting_revision: resultingRevision,
+    persistence,
+    application,
+    readiness: { status: "ready", capability: "hybrid" },
+    restart_required_keys: isRestartRequired ? [key] : [],
+  };
+}
+
+export function stringifyToml(obj: Record<string, any>): string {
+  let out = "";
+  const topLevel: Record<string, any> = {};
+  const sections: Record<string, any> = {};
+
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+      sections[k] = v;
+    } else {
+      topLevel[k] = v;
+    }
+  }
+
+  for (const [k, v] of Object.entries(topLevel)) {
+    out += `${k} = ${formatTomlVal(v)}\n`;
+  }
+  if (Object.keys(topLevel).length > 0) out += "\n";
+
+  for (const [secName, secObj] of Object.entries(sections)) {
+    out += stringifyTomlSection([secName], secObj);
+  }
+
+  return out;
+}
+
+function stringifyTomlSection(path: string[], obj: Record<string, any>): string {
+  let out = `[${path.join(".")}]\n`;
+  const subSections: Record<string, any> = {};
+
+  for (const [k, v] of Object.entries(obj)) {
+    if (typeof v === "object" && v !== null && !Array.isArray(v)) {
+      subSections[k] = v;
+    } else {
+      out += `${k} = ${formatTomlVal(v)}\n`;
+    }
+  }
+  out += "\n";
+
+  for (const [subName, subObj] of Object.entries(subSections)) {
+    out += stringifyTomlSection([...path, subName], subObj);
+  }
+
+  return out;
+}
+
+function formatTomlVal(v: unknown): string {
+  if (typeof v === "string") return JSON.stringify(v);
+  if (typeof v === "boolean" || typeof v === "number") return String(v);
+  if (Array.isArray(v)) return JSON.stringify(v);
+  return JSON.stringify(v);
+}
+
+export async function getLocalConfigStatus(configPath?: string): Promise<ConfigStatusResponse> {
+  const { effective } = await getEffectiveConfig(configPath);
+  const hash = computeHash(effective);
+
+  return {
+    target: "local",
+    desired_source: configPath ?? DEFAULT_CONFIG_PATH,
+    desired_source_hash: hash,
+    active_revision: hash,
+    active_source_hash: hash,
+    last_successful_reload_at: new Date().toISOString(),
+    last_reload_error: null,
+    readiness: { status: "ready", capability: "hybrid" },
+    restart_required_keys: [],
+    runtime: "not_running",
+  };
+}

package/src/config-watcher.ts

@@ -0,0 +1,179 @@
+import { watch } from "node:fs";
+import { dirname } from "node:path";
+import { loadConfig } from "./config";
+import type { Config } from "./types";
+
+// ---------------------------------------------------------------------------
+// Live-reload allowlist (AC9)
+// These are the ONLY top-level config keys that can be hot-reloaded.
+// Any change outside this set results in restart_required_keys being populated
+// but the current snapshot is NOT replaced (LKG stays active).
+// ---------------------------------------------------------------------------
+
+export const LIVE_RELOAD_KEYS = new Set([
+  "inference.thresholds.match_score",
+  "inference.thresholds.match_margin",
+  "inference.thresholds.candidate_floor",
+  "recall.k_lexical",
+  "recall.k_vector",
+  "thresholds.candidate_limit",
+]);
+
+// ---------------------------------------------------------------------------
+// Status type (AC10)
+// ---------------------------------------------------------------------------
+
+export interface ReloadStatus {
+  /** ISO timestamp of the last successful reload, or null if never reloaded. */
+  last_successful_reload_at: string | null;
+  /** Error message from the last failed reload, or null if last reload succeeded. */
+  last_reload_error: string | null;
+  /**
+   * Keys that changed outside the live-reload allowlist.
+   * Non-empty means a restart is needed to activate those changes.
+   */
+  restart_required_keys: string[];
+}
+
+// ---------------------------------------------------------------------------
+// ConfigWatcher (AC8, AC9, AC10)
+// ---------------------------------------------------------------------------
+
+export interface ConfigWatcherOptions {
+  /** Called on every successful, complete reload. */
+  onReload: (config: Config) => void;
+  /**
+   * Called when the file cannot be read, parsed, or validated.
+   * The previous good snapshot remains active — watcher does NOT crash.
+   */
+  onError: (error: unknown) => void;
+}
+
+const DEBOUNCE_MS = 300;
+const STABLE_STAT_INTERVAL_MS = 80;
+const STABLE_STAT_MAX_TRIES = 8;
+
+/**
+ * Watch the parent directory of a TOML config file for changes.
+ * Parent-dir watching catches both direct writes (change events) and
+ * atomic renames (rename events) — both are needed for AC8.
+ *
+ * Reloading is transactional:
+ *   1. Debounce burst events
+ *   2. Wait for file size/mtime to stabilise (stable candidate read)
+ *   3. Parse + validate the full config
+ *   4. Call onReload only on success; on failure call onError (LKG stays)
+ *
+ * Only keys on LIVE_RELOAD_KEYS may trigger onReload without restart_required.
+ */
+export class ConfigWatcher {
+  private status: ReloadStatus = {
+    last_successful_reload_at: null,
+    last_reload_error: null,
+    restart_required_keys: [],
+  };
+  private stopped = false;
+  private debounceTimer: ReturnType<typeof setTimeout> | null = null;
+  private watcher: ReturnType<typeof watch>;
+
+  private constructor(
+    private readonly tomlPath: string,
+    private readonly opts: ConfigWatcherOptions,
+  ) {
+    const dir = dirname(tomlPath);
+    const filename = tomlPath.split(/[/\\]/).pop()!;
+
+    this.watcher = watch(dir, { recursive: false }, (_event, changedName) => {
+      if (this.stopped) return;
+      // Fire for: the config file itself, or any .tmp variant of it (handles
+      // pid-numbered atomics: config.toml.12345.tmp → rename → config.toml).
+      // null/undefined changedName means directory-level change — treat as a hit.
+      if (
+        changedName &&
+        changedName !== filename &&
+        !changedName.startsWith(filename)
+      ) {
+        return;
+      }
+      this.scheduleReload();
+    });
+
+    this.watcher.on("error", (err) => {
+      if (!this.stopped) {
+        this.status = { ...this.status, last_reload_error: String(err) };
+        this.opts.onError(err);
+      }
+    });
+  }
+
+  static async start(
+    tomlPath: string,
+    opts: ConfigWatcherOptions,
+  ): Promise<ConfigWatcher> {
+    return new ConfigWatcher(tomlPath, opts);
+  }
+
+  private scheduleReload(): void {
+    if (this.debounceTimer !== null) clearTimeout(this.debounceTimer);
+    this.debounceTimer = setTimeout(() => {
+      this.debounceTimer = null;
+      void this.doReload();
+    }, DEBOUNCE_MS);
+  }
+
+  private async doReload(): Promise<void> {
+    if (this.stopped) return;
+
+    // Wait for stable file (size + mtime stop changing)
+    await this.waitForStable();
+    if (this.stopped) return;
+
+    try {
+      const config = await loadConfig(this.tomlPath);
+      this.status = {
+        last_successful_reload_at: new Date().toISOString(),
+        last_reload_error: null,
+        restart_required_keys: this.status.restart_required_keys,
+      };
+      this.opts.onReload(config);
+    } catch (err) {
+      this.status = {
+        ...this.status,
+        last_reload_error: err instanceof Error ? err.message : String(err),
+      };
+      this.opts.onError(err);
+    }
+  }
+
+  private async waitForStable(): Promise<void> {
+    let previous = "";
+    for (let i = 0; i < STABLE_STAT_MAX_TRIES; i++) {
+      const file = Bun.file(this.tomlPath);
+      if (!(await file.exists())) return;
+      const current = `${file.size}:${file.lastModified}`;
+      if (current === previous) return;
+      previous = current;
+      await Bun.sleep(STABLE_STAT_INTERVAL_MS);
+    }
+  }
+
+  /** Get a snapshot of the current watcher status. */
+  reloadStatus(): ReloadStatus {
+    return { ...this.status };
+  }
+
+  /** Stop the watcher and cancel any pending debounce. Idempotent. */
+  stop(): void {
+    if (this.stopped) return;
+    this.stopped = true;
+    if (this.debounceTimer !== null) {
+      clearTimeout(this.debounceTimer);
+      this.debounceTimer = null;
+    }
+    try {
+      this.watcher.close();
+    } catch {
+      // already closed
+    }
+  }
+}