@klhapp/skillmux 1.11.2 → 1.13.0

package/src/clients.ts

@@ -1,368 +0,0 @@
-import type { Clients, Config, RemoteRerankerConfig } from "./types";
-import { expandHome } from "./config";
-import { assertHostAllowed } from "./install";
-import type { pipeline as createPipeline } from "@huggingface/transformers";
-
-export type RemoteErrorKind = "configuration" | "availability" | "protocol";
-
-export class RemoteInferenceError extends Error {
-  constructor(
-    public readonly kind: RemoteErrorKind,
-    message: string,
-  ) {
-    super(message);
-    this.name = "RemoteInferenceError";
-  }
-}
-
-// Lazy-loaded model instances for in-process ONNX inference
-type FeatureExtractor = Awaited<ReturnType<typeof createPipeline<"feature-extraction">>>;
-
-let localEmbedder: FeatureExtractor | null = null;
-
-function authorizationHeaders(
-  apiKeyEnv: string | undefined,
-  configKey: string,
-): Record<string, string> {
-  if (apiKeyEnv === undefined) return {};
-  const apiKey = process.env[apiKeyEnv];
-  if (apiKey === undefined || apiKey === "") {
-    throw new RemoteInferenceError(
-      "configuration",
-      `${configKey} names environment variable "${apiKeyEnv}", but it is unset or empty.`,
-    );
-  }
-  return { authorization: `Bearer ${apiKey}` };
-}
-
-function assertInferenceHostAllowed(url: string, allowedHosts: string[] | undefined): void {
-  try {
-    assertHostAllowed(url, allowedHosts);
-  } catch (error) {
-    throw new RemoteInferenceError(
-      "configuration",
-      error instanceof Error ? error.message : String(error),
-    );
-  }
-}
-
-function httpFailure(surface: string, status: number): RemoteInferenceError {
-  const kind: RemoteErrorKind =
-    status === 401 || status === 403
-      ? "configuration"
-      : status === 408 || status === 429 || status >= 500
-        ? "availability"
-        : "protocol";
-  return new RemoteInferenceError(kind, `${surface} returned HTTP ${status}`);
-}
-
-function finiteFloat32(
-  values: unknown[],
-  error: () => Error,
-): Float32Array {
-  const result = new Float32Array(values.length);
-  for (let index = 0; index < values.length; index++) {
-    const value = values[index];
-    if (typeof value !== "number" || !Number.isFinite(value)) throw error();
-    result[index] = value;
-    if (!Number.isFinite(result[index]!)) throw error();
-  }
-  return result;
-}
-
-function parseEmbeddingVectors(
-  value: unknown,
-  inputCount: number,
-  dimension: number,
-): Float32Array[] {
-  const response = value as { data?: unknown };
-  if (
-    typeof response !== "object" ||
-    response === null ||
-    !Array.isArray(response.data) ||
-    response.data.length !== inputCount
-  ) {
-    throw new RemoteInferenceError(
-      "protocol",
-      "embedding endpoint returned an incomplete data array",
-    );
-  }
-
-  const vectors = new Array<Float32Array>(inputCount);
-  const seen = new Set<number>();
-  for (const value of response.data) {
-    const entry = value as { index?: unknown; embedding?: unknown };
-    if (
-      typeof entry !== "object" ||
-      entry === null ||
-      !Number.isInteger(entry.index) ||
-      (entry.index as number) < 0 ||
-      (entry.index as number) >= inputCount ||
-      seen.has(entry.index as number) ||
-      !Array.isArray(entry.embedding) ||
-      entry.embedding.length !== dimension
-    ) {
-      throw new RemoteInferenceError(
-        "protocol",
-        "embedding endpoint returned invalid indexed vectors",
-      );
-    }
-    seen.add(entry.index as number);
-    vectors[entry.index as number] = finiteFloat32(
-      entry.embedding,
-      () => new RemoteInferenceError("protocol", "embedding endpoint returned invalid vector values"),
-    );
-  }
-  return vectors;
-}
-
-export function parseLocalEmbeddingVectors(
-  value: unknown,
-  inputCount: number,
-  dimension: number,
-): Float32Array[] {
-  if (!Array.isArray(value) || value.length !== inputCount) {
-    throw new Error("Embedding model returned an unexpected batch size.");
-  }
-  return value.map((row) => {
-    if (!Array.isArray(row) || row.length !== dimension) {
-      throw new Error("Embedding model returned unexpected vector dimensions.");
-    }
-    return finiteFloat32(
-      row,
-      () => new Error("Embedding model returned invalid vector values."),
-    );
-  });
-}
-
-function rerankerRequestBody(
-  reranker: RemoteRerankerConfig,
-  query: string,
-  docs: { skill_id: string; text: string }[],
-): Record<string, unknown> {
-  if (reranker.adapter === "jina-v1") {
-    return {
-      model: reranker.model,
-      query,
-      documents: docs.map((doc) => doc.text),
-    };
-  }
-  return {
-    model: reranker.model,
-    query,
-    documents: docs.map((doc) => ({
-      text: doc.text,
-      id: doc.skill_id,
-      meta: {},
-    })),
-    top_n: docs.length,
-    return_documents: false,
-  };
-}
-
-function parseRerankerScores(
-  adapter: RemoteRerankerConfig["adapter"],
-  value: unknown,
-  documentCount: number,
-): number[] {
-  const response = value as { results?: unknown };
-  if (
-    typeof response !== "object" ||
-    response === null ||
-    !Array.isArray(response.results) ||
-    response.results.length !== documentCount
-  ) {
-    throw new RemoteInferenceError(
-      "protocol",
-      `reranker adapter "${adapter}" returned an incomplete results array`,
-    );
-  }
-
-  const scores = new Array<number>(documentCount);
-  const seen = new Set<number>();
-  for (const value of response.results) {
-    const result = value as { index?: unknown; relevance_score?: unknown };
-    if (
-      typeof result !== "object" ||
-      result === null ||
-      !Number.isInteger(result.index) ||
-      (result.index as number) < 0 ||
-      (result.index as number) >= documentCount ||
-      seen.has(result.index as number) ||
-      typeof result.relevance_score !== "number" ||
-      !Number.isFinite(result.relevance_score)
-    ) {
-      throw new RemoteInferenceError(
-        "protocol",
-        `reranker adapter "${adapter}" returned invalid indexed scores`,
-      );
-    }
-    seen.add(result.index as number);
-    scores[result.index as number] = result.relevance_score;
-  }
-  return scores;
-}
-
-async function fetchRerankerScores(
-  reranker: RemoteRerankerConfig,
-  timeoutMs: number,
-  query: string,
-  docs: { skill_id: string; text: string }[],
-  allowedHosts: string[] | undefined,
-): Promise<number[]> {
-  if (docs.length === 0) return [];
-
-  assertInferenceHostAllowed(reranker.endpoint, allowedHosts);
-
-  let response: Response;
-  try {
-    response = await fetch(reranker.endpoint, {
-      method: "POST",
-      headers: {
-        "content-type": "application/json",
-        ...authorizationHeaders(reranker.api_key_env, "inference.reranker.api_key_env"),
-      },
-      body: JSON.stringify(rerankerRequestBody(reranker, query, docs)),
-      signal: AbortSignal.timeout(timeoutMs),
-    });
-  } catch (error) {
-    if (error instanceof RemoteInferenceError) throw error;
-    const isTimeout =
-      (error as { name?: string })?.name === "TimeoutError" ||
-      (error as { name?: string })?.name === "AbortError" ||
-      String(error).toLowerCase().includes("timeout") ||
-      String(error).toLowerCase().includes("aborted");
-    if (isTimeout) {
-      throw new RemoteInferenceError(
-        "availability",
-        `reranker adapter "${reranker.adapter}" request timed out`,
-      );
-    }
-    throw new RemoteInferenceError(
-      "availability",
-      `reranker adapter "${reranker.adapter}" request failed`,
-    );
-  }
-  if (!response.ok) {
-    throw httpFailure(`reranker adapter "${reranker.adapter}"`, response.status);
-  }
-
-  let parsed: unknown;
-  try {
-    parsed = await response.json();
-  } catch {
-    throw new RemoteInferenceError(
-      "protocol",
-      `reranker adapter "${reranker.adapter}" returned malformed JSON`,
-    );
-  }
-  return parseRerankerScores(reranker.adapter, parsed, docs.length);
-}
-
-function localInference(config: Config) {
-  if (config.inference.mode !== "local") throw new Error("Local inference is not configured.");
-  return config.inference;
-}
-
-async function setupTransformers(cacheDir: string) {
-  process.env.HF_HUB_CACHE = cacheDir;
-  process.env.HF_HOME = cacheDir;
-
-  const { env, pipeline } = await import("@huggingface/transformers");
-  env.cacheDir = cacheDir;
-  return pipeline;
-}
-
-async function getLocalEmbedder(config: Config): Promise<FeatureExtractor> {
-  if (localEmbedder) return localEmbedder;
-
-  const inference = localInference(config);
-  const cacheDir = expandHome(inference.models_dir);
-  const pipeline = await setupTransformers(cacheDir);
-
-  localEmbedder = await pipeline("feature-extraction", inference.embedding.model, {
-    device: inference.embedding.device || "cpu",
-    dtype: inference.embedding.dtype || "q8",
-  });
-  return localEmbedder;
-}
-
-/**
- * Real HTTP clients or in-process local ONNX inference clients.
- * Every remote HTTP call is bounded by inference.timeout_ms; timeouts and transport
- * errors reject so resolveSkill can fall back to the strongest available retrieval lane.
- * Local ONNX calls run in-process using @huggingface/transformers.
- */
-export function createClients(config: Config): Clients {
-  const clients: Clients = {
-    async embed(texts: string[]): Promise<Float32Array[]> {
-      if (config.inference.mode === "local") {
-        const pipe = await getLocalEmbedder(config);
-        const output = await pipe(texts, { pooling: "mean", normalize: true });
-        const dim = output.dims[1];
-        if (
-          dim === undefined ||
-          output.dims.length !== 2 ||
-          output.dims[0] !== texts.length ||
-          dim !== config.inference.embedding.dimension
-        ) {
-          throw new Error(`Embedding model returned unexpected dimensions: ${output.dims.join("x")}`);
-        }
-        const rows = Array.from({ length: texts.length }, (_, index) =>
-          output.slice(index, null).tolist(),
-        );
-        return parseLocalEmbeddingVectors(rows, texts.length, dim);
-      }
-
-      const embedding = config.inference.embedding;
-      assertInferenceHostAllowed(embedding.endpoint, config.egress?.allowed_hosts);
-      let response: Response;
-      try {
-        response = await fetch(embedding.endpoint, {
-          method: "POST",
-          headers: {
-            "content-type": "application/json",
-            ...authorizationHeaders(embedding.api_key_env, "inference.embedding.api_key_env"),
-          },
-          body: JSON.stringify({ model: embedding.model, input: texts }),
-          signal: AbortSignal.timeout(config.inference.timeout_ms),
-        });
-      } catch (error) {
-        if (error instanceof RemoteInferenceError) throw error;
-        const isTimeout =
-          (error as { name?: string })?.name === "TimeoutError" ||
-          (error as { name?: string })?.name === "AbortError" ||
-          String(error).toLowerCase().includes("timeout") ||
-          String(error).toLowerCase().includes("aborted");
-        if (isTimeout) {
-          throw new RemoteInferenceError("availability", "embedding endpoint request timed out");
-        }
-        throw new RemoteInferenceError("availability", "embedding endpoint request failed");
-      }
-      if (!response.ok) throw httpFailure("embedding endpoint", response.status);
-
-      let parsed: unknown;
-      try {
-        parsed = await response.json();
-      } catch {
-        throw new RemoteInferenceError("protocol", "embedding endpoint returned malformed JSON");
-      }
-      return parseEmbeddingVectors(parsed, texts.length, embedding.dimension);
-    },
-  };
-  if (config.inference.mode === "remote" && config.inference.reranker) {
-    const inference = config.inference;
-    clients.rerank = async (query, docs) => {
-      const reranker = inference.reranker;
-      if (!reranker) throw new Error("Reranker is not configured.");
-      return fetchRerankerScores(
-        reranker,
-        inference.timeout_ms,
-        query,
-        docs,
-        config.egress?.allowed_hosts,
-      );
-    };
-  }
-  return clients;
-}

package/src/commands/audit.ts

@@ -1,85 +0,0 @@
-import { emitSuccess } from "../output";
-import { confirmIfNeeded } from "./shared";
-import type { ContextAdapter } from "../adapters";
-import type { ResolvedContext } from "../context";
-import { isGlobalFlag, isGlobalFlagWithValue } from "../global-flags";
-
-export async function runAudit(
-  subCommand: string,
-  args: string[],
-  options: { isJson: boolean; dryRun: boolean; context: ResolvedContext; adapter: ContextAdapter },
-): Promise<void> {
-  if (subCommand !== "prune") {
-    throw new Error("usage: skillmux audit prune [--older-than <window>] [--dry-run] [--yes] [--json]");
-  }
-
-  let olderThan: string | undefined;
-  let dryRun = options.dryRun;
-  let yes = false;
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--older-than") olderThan = args[++i];
-    else if (arg === "--dry-run") dryRun = true;
-    else if (arg === "--yes") yes = true;
-    else if (isGlobalFlag(arg, "--json", "--allow-insecure", "--verbose")) {
-      // handled globally by main()'s flags; recognized here so it isn't rejected
-    } else if (isGlobalFlagWithValue(arg)) {
-      i++; // skip flag value
-    } else if (arg?.startsWith("--")) {
-      throw new Error(`unknown audit prune option: ${arg}`);
-    }
-  }
-
-  if (dryRun) {
-    const counts = await options.adapter.auditCount(olderThan);
-    emitSuccess(
-      { isJson: options.isJson },
-      counts,
-      () =>
-        console.log(
-          counts.cutoff === null
-            ? "prune: audit.retention_days is 0 (pruning disabled); nothing to do"
-            : `prune: audit=${counts.audit_deleted} fetch=${counts.fetch_deleted} admin_audit=${counts.admin_audit_deleted} (dry-run)`,
-        ),
-    );
-    return;
-  }
-
-  // Pre-fetch count / cutoff info for confirmation prompt if local or remote
-  const countResult = await options.adapter.auditCount(olderThan);
-  if (countResult.cutoff === null) {
-    emitSuccess(
-      { isJson: options.isJson },
-      { audit_deleted: 0, fetch_deleted: 0, admin_audit_deleted: 0, dry_run: false, cutoff: null },
-      () => console.log("prune: audit.retention_days is 0 (pruning disabled); nothing to do"),
-    );
-    return;
-  }
-
-  if (
-    !(await confirmIfNeeded({
-      confirmed: yes,
-      isJson: options.isJson,
-      prompt: `prune audit rows older than ${countResult.cutoff}?`,
-      nonInteractiveError: "skillmux audit prune requires --yes when run non-interactively",
-    }))
-  )
-    return;
-
-  // Reuse the exact cutoff already shown in the confirmation prompt — recomputing
-  // it here (if olderThan was left unset) could drift from what was confirmed,
-  // e.g. if audit.retention_days changed between the two calls on a remote target.
-  const counts = await options.adapter.auditPrune({
-    older_than: countResult.cutoff,
-    dry_run: false,
-    confirm: true,
-  });
-  emitSuccess(
-    { isJson: options.isJson },
-    counts,
-    () =>
-      console.log(
-        `prune: audit=${counts.audit_deleted} fetch=${counts.fetch_deleted} admin_audit=${counts.admin_audit_deleted}`,
-      ),
-  );
-}

package/src/commands/config.ts

@@ -1,224 +0,0 @@
-import { expandHome, migrateLegacyPaths, resolveConfigPath } from "../config";
-import { type ContextAdapter } from "../adapters";
-import { type ResolvedContext } from "../context";
-import { applyConfigInit, planConfigInit, type ConfigInitPlan } from "../setup";
-import { emitSuccess, isInteractive, renderContextBanner, unknownSubcommandError } from "../output";
-import { confirmAction } from "./shared";
-import { isGlobalFlag } from "../global-flags";
-function emitConfigInitOutcome(
-  ctx: { isJson: boolean },
-  opts: {
-    phase: "plan" | "result";
-    dryRun: boolean;
-    applied: boolean;
-    plan: ConfigInitPlan;
-    action: "create" | "preserve";
-    text: string;
-  },
-): void {
-  if (ctx.isJson) {
-    console.log(
-      JSON.stringify({
-        schema_version: 1,
-        ok: true,
-        command: "config init",
-        phase: opts.phase,
-        dry_run: opts.dryRun,
-        applied: opts.applied,
-        plan: {
-          config_path: opts.plan.configPath,
-          vault_path: opts.plan.vaultPath,
-          action: opts.action,
-        },
-      }),
-    );
-    return;
-  }
-  console.log(opts.text);
-}
-
-export async function handleConfigCommand(
-  adapter: ContextAdapter,
-  sub: string,
-  args: string[],
-  ctx: { context: ResolvedContext; isJson: boolean; dryRun: boolean },
-) {
-  if (sub === "init") {
-    let vaultPath: string | undefined;
-    let yes = false;
-    for (let i = 0; i < args.length; i++) {
-      const option = args[i];
-      if (option === "--vault") {
-        vaultPath = args[++i];
-        if (!vaultPath)
-          throw new Error("usage: skillmux config init --vault <path> --yes");
-      } else if (option === "--yes") {
-        yes = true;
-      } else if (isGlobalFlag(option, "--dry-run", "--json")) {
-        continue;
-      } else {
-        throw new Error(`unknown config init option: ${option}`);
-      }
-    }
-    if (!vaultPath) {
-      if (isInteractive() && !ctx.isJson) {
-        vaultPath = "~/skills";
-      } else {
-        throw new Error("usage: skillmux config init --vault <path> --yes");
-      }
-    }
-
-    migrateLegacyPaths();
-    const plan = planConfigInit(resolveConfigPath(), expandHome(vaultPath));
-    if (plan.action === "preserve") {
-      emitConfigInitOutcome(ctx, {
-        phase: "result",
-        dryRun: ctx.dryRun,
-        applied: false,
-        plan,
-        action: "preserve",
-        text: `preserved existing config: ${plan.configPath}`,
-      });
-      return;
-    }
-    if (ctx.dryRun) {
-      emitConfigInitOutcome(ctx, {
-        phase: "plan",
-        dryRun: true,
-        applied: false,
-        plan,
-        action: "create",
-        text: `config create: ${plan.configPath} (dry-run)`,
-      });
-      return;
-    }
-    if (!yes) {
-      if (!ctx.isJson && isInteractive()) {
-        if (
-          !(await confirmAction(
-            `create ${plan.configPath} with vault_path ${plan.vaultPath}?`,
-          ))
-        ) {
-          console.log("config init cancelled; nothing written");
-          return;
-        }
-      } else {
-        throw new Error(
-          "config initialization requires --yes in noninteractive mode",
-        );
-      }
-    }
-
-    const result = applyConfigInit(plan);
-    emitConfigInitOutcome(ctx, {
-      phase: "result",
-      dryRun: false,
-      applied: result === "created",
-      plan,
-      action: plan.action,
-      text:
-        result === "created"
-          ? `created ${plan.configPath}`
-          : `preserved existing config: ${plan.configPath}`,
-    });
-    return;
-  }
-
-  if (sub === "show") {
-    const withSources = args.includes("--sources");
-    const data = await adapter.getConfigShow();
-    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, data, () => {
-      renderContextBanner(ctx.context);
-      if (withSources) {
-        const policy =
-          data.effective.config?.environment_overrides === false
-            ? "strict (TOML authoritative)"
-            : "permissive (environment overrides enabled)";
-        console.log(`Policy: ${policy}`);
-        console.log("\nSources:");
-        for (const [k, src] of Object.entries(data.sources)) {
-          console.log(`  ${k}: ${src}`);
-        }
-        console.log("\nEffective Configuration:");
-      }
-      console.log(JSON.stringify(data.effective, null, 2));
-    });
-    return;
-  }
-
-  if (sub === "get") {
-    const key = args[0];
-    if (!key) throw new Error("usage: skillmux config get <key>");
-    const val = await adapter.getConfigGet(key);
-    emitSuccess(
-      { isJson: ctx.isJson, context: ctx.context },
-      { key, value: val },
-      () => {
-        console.log(
-          typeof val === "object" ? JSON.stringify(val) : String(val),
-        );
-      },
-    );
-    return;
-  }
-
-  if (sub === "validate") {
-    const res = await adapter.configValidate();
-    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
-      console.log(res.valid ? "configuration is valid" : "configuration is invalid");
-    });
-    return;
-  }
-
-  if (sub === "diff") {
-    const res = await adapter.configDiff();
-    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
-      renderContextBanner(ctx.context);
-      console.log(JSON.stringify(res.diff, null, 2));
-    });
-    return;
-  }
-
-  if (sub === "set") {
-    const key = args[0];
-    const value = args[1];
-    if (!key || value === undefined) {
-      throw new Error("usage: skillmux config set <key> <value> [--dry-run]");
-    }
-    const res = await adapter.configSet(key, value, { dryRun: ctx.dryRun });
-    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
-      renderContextBanner(ctx.context);
-      const prefix = ctx.dryRun ? "[dry-run] " : "";
-      console.log(
-        `${prefix}${key}: ${JSON.stringify(res.prior_val)} -> ${JSON.stringify(res.resulting_val)}`,
-      );
-      console.log(
-        `Persistence: ${res.persistence}, Application: ${res.application}`,
-      );
-    });
-    return;
-  }
-
-  if (sub === "status") {
-    const res = await adapter.configStatus();
-    emitSuccess({ isJson: ctx.isJson, context: ctx.context }, res, () => {
-      renderContextBanner(ctx.context);
-      console.log(`runtime: ${res.runtime}`);
-      console.log(`deployment runtime: ${res.deployment_runtime}`);
-      console.log(`image variant: ${res.image_variant ?? "none"}`);
-      console.log(`active revision: ${res.active_revision}`);
-      console.log(`readiness: ${res.readiness.status}`);
-    });
-    return;
-  }
-
-  throw unknownSubcommandError("config", sub, [
-    "init",
-    "show",
-    "get",
-    "set",
-    "validate",
-    "diff",
-    "status",
-  ]);
-}