@klhapp/skillmux 1.12.0 → 1.13.0

package/src/mcp-registration.ts

@@ -1,89 +0,0 @@
-import {
-  getAgentDefinition,
-  SUPPORTED_AGENT_IDS,
-  type AgentId,
-  type McpRegistrationScope,
-} from "./init-agents";
-
-export type { McpRegistrationScope };
-
-export const MCP_REGISTRABLE_AGENTS = SUPPORTED_AGENT_IDS.filter(
-  (agent) => getAgentDefinition(agent).mcpRegistration !== undefined,
-);
-
-export const MCP_PROJECT_REGISTRABLE_AGENTS = MCP_REGISTRABLE_AGENTS.filter(
-  (agent) => getAgentDefinition(agent).mcpRegistration!.buildArgs("project") !== undefined,
-);
-
-export function isMcpRegistrable(agent: AgentId): boolean {
-  return getAgentDefinition(agent).mcpRegistration !== undefined;
-}
-
-export interface McpRegistrationResult {
-  agent: AgentId;
-  ok: boolean;
-  error?: string;
-}
-
-type SpawnFn = (
-  cmd: string[],
-  opts?: { cwd?: string },
-) => {
-  exited: Promise<number>;
-  stderr: ReadableStream<Uint8Array> | number;
-};
-
-/**
- * Runs the agent's own CLI to register skillmux as an MCP server. Never
- * throws — registration failure (tool not installed, command rejected,
- * etc.) is reported in the result, not fatal to the caller's larger flow.
- */
-export async function registerMcpServer(
-  agent: AgentId,
-  options: {
-    spawn?: SpawnFn;
-    scope?: McpRegistrationScope;
-    cwd?: string;
-  } = {},
-): Promise<McpRegistrationResult> {
-  const entry = getAgentDefinition(agent).mcpRegistration;
-  const scope = options.scope ?? "user";
-  const args = entry?.buildArgs(scope);
-  if (!entry || !args) {
-    return {
-      agent,
-      ok: false,
-      error: `no ${scope === "project" ? "project-scoped " : ""}MCP registration command known for agent "${agent}"`,
-    };
-  }
-  const spawn: SpawnFn =
-    options.spawn ??
-    ((cmd, opts) => Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe", cwd: opts?.cwd }));
-  try {
-    const proc = spawn([entry.command, ...args], { cwd: options.cwd });
-    const stderrText =
-      typeof proc.stderr === "number"
-        ? ""
-        : await new Response(proc.stderr).text();
-    const exitCode = await proc.exited;
-    if (exitCode !== 0) {
-      return {
-        agent,
-        ok: false,
-        error:
-          stderrText.trim() || `${entry.command} exited with code ${exitCode}`,
-      };
-    }
-    return { agent, ok: true };
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    const notFound = /ENOENT|not found|no such file/i.test(message);
-    return {
-      agent,
-      ok: false,
-      error: notFound
-        ? `"${entry.command}" is not installed or not on PATH`
-        : message,
-    };
-  }
-}

package/src/metrics.ts

@@ -1,121 +0,0 @@
-import type { ReadinessSnapshot } from "./readiness";
-import type { DeploymentIdentity } from "./deployment";
-
-type MetricsDeploymentIdentity = Pick<
-  DeploymentIdentity,
-  "version" | "runtime" | "image_variant"
->;
-
-export class MetricsRegistry {
-  private requests = new Map<string, number>();
-
-  private buckets = [0.005, 0.01, 0.025, 0.05, 0.1, 0.25, 0.5, 1.0, 2.5, 5.0, 10.0];
-  private latencyBuckets = new Array(this.buckets.length).fill(0);
-  private latencyInf = 0;
-  private latencySum = 0;
-  private latencyCount = 0;
-
-  private errors = 0;
-  private rateLimitsExceeded = 0;
-  private degradations = new Map<string, number>();
-  private readiness: ReadinessSnapshot | null = null;
-  private deployment: MetricsDeploymentIdentity | null = null;
-
-  setReadiness(readiness: ReadinessSnapshot) {
-    this.readiness = readiness;
-  }
-
-  setDeployment(deployment: MetricsDeploymentIdentity) {
-    this.deployment = deployment;
-  }
-
-  recordRequest(method: string) {
-    this.requests.set(method, (this.requests.get(method) || 0) + 1);
-  }
-
-  recordDegradation(stage: "embedding" | "reranker", reason: string) {
-    const key = `${stage}:${reason}`;
-    this.degradations.set(key, (this.degradations.get(key) || 0) + 1);
-  }
-
-  recordResolveLatencySeconds(seconds: number) {
-    this.latencySum += seconds;
-    this.latencyCount++;
-    for (let i = 0; i < this.buckets.length; i++) {
-      if (seconds <= this.buckets[i]!) {
-        this.latencyBuckets[i]++;
-      }
-    }
-    this.latencyInf++;
-  }
-
-  recordError() {
-    this.errors++;
-  }
-
-  recordRateLimitExceeded() {
-    this.rateLimitsExceeded++;
-  }
-
-  render(): string {
-    const lines: string[] = [];
-
-    // Requests total
-    lines.push("# HELP skill_router_requests_total Total count of incoming MCP requests.");
-    lines.push("# TYPE skill_router_requests_total counter");
-    for (const [method, count] of this.requests) {
-      lines.push(`skill_router_requests_total{method="${method}"} ${count}`);
-    }
-
-    // Latency histogram
-    lines.push("# HELP skill_router_resolve_latency_seconds Latency histogram of resolve_skill executions.");
-    lines.push("# TYPE skill_router_resolve_latency_seconds histogram");
-    for (let i = 0; i < this.buckets.length; i++) {
-      let le = this.buckets[i]!.toString();
-      // Format to remove trailing .0 if integer to match test
-      if (Number.isInteger(this.buckets[i]!)) {
-        le = this.buckets[i]!.toFixed(0);
-      }
-      lines.push(`skill_router_resolve_latency_seconds_bucket{le="${le}"} ${this.latencyBuckets[i]}`);
-    }
-    lines.push(`skill_router_resolve_latency_seconds_bucket{le="+Inf"} ${this.latencyInf}`);
-    lines.push(`skill_router_resolve_latency_seconds_sum ${this.latencySum}`);
-    lines.push(`skill_router_resolve_latency_seconds_count ${this.latencyCount}`);
-
-    // Errors total
-    lines.push("# HELP skill_router_errors_total Total count of server and query routing errors.");
-    lines.push("# TYPE skill_router_errors_total counter");
-    lines.push(`skill_router_errors_total ${this.errors}`);
-
-    // Rate limits exceeded
-    lines.push("# HELP skill_router_rate_limits_exceeded_total Total count of HTTP requests rejected by rate limiting.");
-    lines.push("# TYPE skill_router_rate_limits_exceeded_total counter");
-    lines.push(`skill_router_rate_limits_exceeded_total ${this.rateLimitsExceeded}`);
-
-    // Degraded retrieval total
-    lines.push("# HELP skill_router_degraded_retrieval_total Total count of degraded retrieval fallbacks labelled by stage and reason.");
-    lines.push("# TYPE skill_router_degraded_retrieval_total counter");
-    for (const [key, count] of this.degradations) {
-      const [stage, reason] = key.split(":");
-      lines.push(`skill_router_degraded_retrieval_total{stage="${stage}",reason="${reason}"} ${count}`);
-    }
-
-    lines.push("# HELP skill_router_ready Whether the service is ready to route requests.");
-    lines.push("# TYPE skill_router_ready gauge");
-    lines.push(`skill_router_ready ${this.readiness?.status === "ready" ? 1 : 0}`);
-    lines.push("# HELP skill_router_retrieval_capability Active retrieval capability.");
-    lines.push("# TYPE skill_router_retrieval_capability gauge");
-    for (const capability of ["exact", "reranked", "hybrid", "lexical"]) {
-      lines.push(`skill_router_retrieval_capability{capability="${capability}"} ${this.readiness?.retrieval === capability ? 1 : 0}`);
-    }
-
-    if (this.deployment) {
-      const imageVariant = this.deployment.image_variant ?? "none";
-      lines.push("# HELP skill_router_deployment_info Immutable deployment identity for operator comparison.");
-      lines.push("# TYPE skill_router_deployment_info gauge");
-      lines.push(`skill_router_deployment_info{version="${this.deployment.version}",runtime="${this.deployment.runtime}",image_variant="${imageVariant}"} 1`);
-    }
-
-    return lines.join("\n") + "\n";
-  }
-}

package/src/models.ts

@@ -1,20 +0,0 @@
-import { expandHome } from "./config";
-import type { Config } from "./types";
-
-export async function downloadLocalModels(config: Config): Promise<string> {
-  if (config.inference.mode !== "local") {
-    throw new Error("models download is only available for inference.mode = \"local\".");
-  }
-
-  const cacheDir = expandHome(config.inference.models_dir);
-  process.env.HF_HUB_CACHE = cacheDir;
-  process.env.HF_HOME = cacheDir;
-  const { env, pipeline } = await import("@huggingface/transformers");
-  env.cacheDir = cacheDir;
-
-  await pipeline("feature-extraction", config.inference.embedding.model, {
-    device: config.inference.embedding.device ?? "cpu",
-    dtype: config.inference.embedding.dtype ?? "q8",
-  });
-  return cacheDir;
-}

package/src/output.ts

@@ -1,214 +0,0 @@
-import type { ResolvedContext } from "./context";
-
-export interface JsonEnvelope<T = any> {
-  schema_version: 1;
-  ok: boolean;
-  context: string | { name: string; server: string };
-  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
-  target: string | { name: string; server: string };
-  data: T | null;
-  error: { code: string; message: string; details?: any } | null;
-}
-
-export function formatJsonEnvelope<T>(opts: {
-  ok: boolean;
-  /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
-  target?: ResolvedContext | string | { name: string; server: string };
-  context?: ResolvedContext | string | { name: string; server: string };
-  data?: T;
-  error?: { code: string; message: string; details?: any } | null;
-}): JsonEnvelope<T> {
-  const input: ResolvedContext | string | { name: string; server: string } =
-    opts.context ?? opts.target ?? "local";
-  let contextVal: string | { name: string; server: string };
-  if (typeof input === "string") {
-    contextVal = input;
-  } else if (typeof input === "object" && input !== null) {
-    if ("type" in input && (input as any).type === "local") {
-      contextVal = "local";
-    } else if ("name" in input && "server" in input) {
-      contextVal = { name: input.name, server: input.server };
-    } else {
-      contextVal = "local";
-    }
-  } else {
-    contextVal = "local";
-  }
-
-  return {
-    schema_version: 1,
-    ok: opts.ok,
-    context: contextVal,
-    target: contextVal,
-    data: opts.data ?? null,
-    error: opts.error ?? null,
-  };
-}
-
-export class CliError extends Error {
-  exitCode: number;
-  code: string;
-  details?: unknown;
-
-  constructor(message: string, exitCode: number, code = `EXIT_${exitCode}`, details?: unknown) {
-    super(message);
-    this.name = "CliError";
-    this.exitCode = exitCode;
-    this.code = code;
-    this.details = details;
-  }
-}
-
-export function emitSuccess<T>(
-  ctx: {
-    isJson: boolean;
-    /** @deprecated Use `context` instead. Retained as a compatibility alias; no removal planned. */
-    target?: ResolvedContext | string | { name: string; server: string };
-    context?: ResolvedContext | string | { name: string; server: string };
-  },
-  data: T,
-  renderText: () => void,
-): void {
-  if (ctx.isJson) {
-    const contextVal = ctx.context ?? ctx.target ?? "local";
-    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, context: contextVal, target: contextVal, data })));
-  } else {
-    renderText();
-  }
-}
-
-export function mapExitCode(err: unknown): number {
-  if (!err) return 0;
-  if (err instanceof CliError) return err.exitCode;
-  return 2;
-}
-
-export function levenshteinDistance(a: string, b: string): number {
-  const m = a.length;
-  const n = b.length;
-  const dp: number[][] = Array.from({ length: m + 1 }, () => Array(n + 1).fill(0));
-
-  for (let i = 0; i <= m; i++) {
-    if (!dp[i]) dp[i] = [];
-    dp[i]![0] = i;
-  }
-  for (let j = 0; j <= n; j++) {
-    if (!dp[0]) dp[0] = [];
-    dp[0]![j] = j;
-  }
-
-  for (let i = 1; i <= m; i++) {
-    for (let j = 1; j <= n; j++) {
-      const cost = a[i - 1] === b[j - 1] ? 0 : 1;
-      const prevRow = dp[i - 1]!;
-      const curRow = dp[i]!;
-      curRow[j] = Math.min(
-        prevRow[j]! + 1,
-        curRow[j - 1]! + 1,
-        prevRow[j - 1]! + cost
-      );
-    }
-  }
-  return dp[m]![n]!;
-}
-
-export function suggestCorrection(input: string, candidates: string[]): string | null {
-  let minDistance = Infinity;
-  let bestMatch: string | null = null;
-
-  for (const candidate of candidates) {
-    const dist = levenshteinDistance(input, candidate);
-    if (dist < minDistance && dist <= 2) {
-      minDistance = dist;
-      bestMatch = candidate;
-    }
-  }
-
-  return bestMatch;
-}
-
-/**
- * Builds the error for an unrecognized subcommand: "did you mean X" when
- * close to a valid one, otherwise the full <a|b|c> usage list — never a
- * fixed, possibly-unrelated usage string for just one of several valid
- * subcommands (that's what `config`'s fallback used to do before this
- * existed: any invalid subcommand got told "usage: skillmux config show",
- * silently omitting get/set/validate/diff/status/init).
- */
-export function unknownSubcommandError(
-  command: string,
-  subCommand: string,
-  validSubcommands: string[],
-): Error {
-  const suggestion = subCommand ? suggestCorrection(subCommand, validSubcommands) : null;
-  if (suggestion) {
-    return new Error(
-      `Unknown "${command} ${subCommand}" subcommand. Did you mean "${command} ${suggestion}"?`,
-    );
-  }
-  return new Error(`usage: skillmux ${command} <${validSubcommands.join("|")}>`);
-}
-
-export function isInteractive(
-  env: NodeJS.ProcessEnv = process.env,
-  stdoutIsTTY = process.stdout.isTTY,
-): boolean {
-  return stdoutIsTTY === true && env.TERM !== "dumb";
-}
-
-/** Color is opt-out only: https://no-color.org, plus the same TTY check as isInteractive(). */
-export function isColorEnabled(
-  env: NodeJS.ProcessEnv = process.env,
-  stdoutIsTTY = process.stdout.isTTY,
-): boolean {
-  if (env.NO_COLOR !== undefined) return false;
-  return isInteractive(env, stdoutIsTTY);
-}
-
-const ANSI = { reset: "\x1b[0m", bold: "\x1b[1m", red: "\x1b[31m", yellow: "\x1b[33m", green: "\x1b[32m" } as const;
-
-function paint(code: string, text: string): string {
-  return isColorEnabled() ? `${code}${text}${ANSI.reset}` : text;
-}
-
-export const red = (text: string): string => paint(ANSI.red, text);
-export const yellow = (text: string): string => paint(ANSI.yellow, text);
-export const green = (text: string): string => paint(ANSI.green, text);
-export const bold = (text: string): string => paint(ANSI.bold, text);
-
-/** Prints a "warning: <line>" message to stderr, colored yellow when color is enabled. */
-export function warn(line: string): void {
-  console.error(yellow(`warning: ${line}`));
-}
-
-export function renderContextBanner(context: ResolvedContext): void {
-  if (!isInteractive()) return;
-  if (context.type === "local") {
-    console.log(`Context: local`);
-  } else {
-    console.log(`Context: remote (${context.name} -> ${context.server})`);
-  }
-}
-
-export function renderTable(columns: { key: string; header: string }[], rows: Record<string, any>[]): void {
-  if (rows.length === 0) {
-    console.log("(no entries)");
-    return;
-  }
-
-  const widths = new Map<string, number>();
-  for (const col of columns) {
-    const maxLen = Math.max(col.header.length, ...rows.map((r) => String(r[col.key] ?? "").length));
-    widths.set(col.key, maxLen);
-  }
-
-  const headerLine = columns.map((col) => col.header.padEnd(widths.get(col.key) ?? 0)).join("  ");
-  const sepLine = columns.map((col) => "-".repeat(widths.get(col.key) ?? 0)).join("  ");
-
-  console.log(bold(headerLine));
-  console.log(sepLine);
-  for (const row of rows) {
-    const line = columns.map((col) => String(row[col.key] ?? "").padEnd(widths.get(col.key) ?? 0)).join("  ");
-    console.log(line);
-  }
-}

package/src/project-setup.ts

@@ -1,36 +0,0 @@
-import { resolve } from "node:path";
-
-interface ResolveProjectDirectoryOptions {
-  cwd?: string;
-  findGitRoot?: (cwd: string) => string | null;
-}
-
-function findGitRoot(cwd: string): string | null {
-  const result = Bun.spawnSync(["git", "rev-parse", "--show-toplevel"], {
-    cwd,
-    stdout: "pipe",
-    stderr: "ignore",
-  });
-  if (result.exitCode !== 0) return null;
-  const root = result.stdout.toString().trim();
-  return root || null;
-}
-
-export function resolveProjectDirectory(
-  explicitPath?: string,
-  options: ResolveProjectDirectoryOptions = {},
-): string {
-  const cwd = options.cwd ?? process.cwd();
-  if (explicitPath) return resolve(explicitPath);
-  const gitRoot = (options.findGitRoot ?? findGitRoot)(cwd);
-  return resolve(gitRoot ?? cwd);
-}
-
-export function suggestProjectName(directoryName: string): string {
-  const slug = directoryName
-    .toLowerCase()
-    .replace(/[^a-z0-9_-]+/g, "-")
-    .replace(/^-+|-+$/g, "");
-  const prefixed = /^[a-z]/.test(slug) ? slug : `project-${slug || "workspace"}`;
-  return prefixed.slice(0, 64).replace(/-+$/g, "");
-}

package/src/prompts.ts

@@ -1,124 +0,0 @@
-import { createInterface } from "node:readline/promises";
-import type { Readable, Writable } from "node:stream";
-
-/**
- * Streams a prompt reads from and writes to. Injectable so prompts can be
- * tested without a terminal; defaults to the real process streams.
- */
-export interface PromptIO {
-  input?: Readable;
-  output?: Writable;
-}
-
-export const NO_INPUT_ERROR = "no input available on stdin; re-run with --yes";
-
-/**
- * Asks one question and resolves with the raw answer.
- *
- * `isInteractive()` only inspects stdout, so a caller can legitimately reach a
- * prompt while stdin is already at EOF (a pty'd stdout under CI, a wrapper
- * process, `skillmux init < /dev/null`). A bare `readline.question()` never
- * settles in that case and the CLI hangs forever, so the input stream ending
- * before an answer arrives is turned into an actionable error instead.
- *
- * Piped answers (`printf 'y\n' | skillmux ...`) still work: `close` only wins
- * the race when the stream ends with the question still outstanding.
- */
-export async function askQuestion(query: string, io: PromptIO = {}): Promise<string> {
-  const readline = createInterface({
-    input: io.input ?? process.stdin,
-    output: io.output ?? process.stdout,
-  });
-  let settled = false;
-  try {
-    return await new Promise<string>((resolve, reject) => {
-      readline.question(query).then(
-        (answer) => {
-          settled = true;
-          resolve(answer);
-        },
-        (error) => {
-          settled = true;
-          reject(error);
-        },
-      );
-      // Fires on EOF, and also from the `finally` below. A piped stream ends
-      // immediately after delivering its answer, so `close` can arrive before
-      // the resolution microtask runs — deferring past pending microtasks lets
-      // a real answer win the race, leaving only a genuine EOF to reject.
-      readline.once("close", () => {
-        setImmediate(() => {
-          if (settled) return;
-          settled = true;
-          reject(new Error(NO_INPUT_ERROR));
-        });
-      });
-    });
-  } finally {
-    readline.close();
-  }
-}
-
-export interface SelectOption<T extends string> {
-  value: T;
-  label: string;
-  detail?: string;
-  selected?: boolean;
-}
-
-export function parseNumberSelection(input: string, optionCount: number): number[] {
-  if (input.trim() === "") return [];
-  const indexes = input.split(",").map((part) => {
-    const choice = Number(part.trim());
-    if (!Number.isInteger(choice) || choice < 1 || choice > optionCount) {
-      throw new Error(`select numbers between 1 and ${optionCount}, separated by commas`);
-    }
-    return choice - 1;
-  });
-  return [...new Set(indexes)].sort((a, b) => a - b);
-}
-
-export function parseCommaList(input: string): string[] {
-  return [...new Set(input.split(",").map((value) => value.trim()).filter(Boolean))];
-}
-
-export function shouldUseWizard(
-  args: readonly string[],
-  mode: { interactive: boolean; json: boolean; dryRun: boolean },
-): boolean {
-  if (!mode.interactive || mode.json || mode.dryRun || args.includes("--yes")) return false;
-  if (args.includes("--interactive")) return true;
-  return args.length === 0;
-}
-
-export async function promptMultiSelect<T extends string>(
-  question: string,
-  options: readonly SelectOption<T>[],
-  io: PromptIO = {},
-): Promise<T[]> {
-  const output = io.output ?? process.stdout;
-  output.write(`\n${question}\n`);
-  options.forEach((option, index) => {
-    const checked = option.selected ? "x" : " ";
-    const detail = option.detail ? `  ${option.detail}` : "";
-    output.write(`  ${index + 1}. [${checked}] ${option.label}${detail}\n`);
-  });
-  const defaults = options
-    .map((option, index) => option.selected ? String(index + 1) : "")
-    .filter(Boolean)
-    .join(",");
-  const suffix = defaults ? ` [${defaults}]` : "";
-  const answer = await askQuestion(`Select numbers, comma-separated${suffix}: `, io);
-  const selection = answer.trim() === "" && defaults ? defaults : answer;
-  return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
-}
-
-export async function promptText(
-  question: string,
-  defaultValue = "",
-  io: PromptIO = {},
-): Promise<string> {
-  const suffix = defaultValue ? ` [${defaultValue}]` : "";
-  const answer = (await askQuestion(`${question}${suffix}: `, io)).trim();
-  return answer || defaultValue;
-}