@klhapp/skillmux 1.0.0 → 1.1.0

package/src/clients.ts

@@ -1,13 +1,17 @@
-import type { Clients, Config } from "./types";
+import type { Clients, Config, RemoteRerankerConfig } from "./types";
 import { expandHome } from "./config";
 import type { pipeline as createPipeline } from "@huggingface/transformers";
 
-interface EmbeddingResponse {
-  data: { index: number; embedding: number[] }[];
-}
+export type RemoteErrorKind = "configuration" | "availability" | "protocol";
 
-interface RerankResponse {
-  results: { index: number; relevance_score: number }[];
+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
@@ -15,6 +19,220 @@ type FeatureExtractor = Awaited<ReturnType<typeof createPipeline<"feature-extrac
 
 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 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 }[],
+): Promise<number[]> {
+  if (docs.length === 0) return [];
+
+  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;
+    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;
@@ -56,37 +274,45 @@ export function createClients(config: Config): Clients {
         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) {
+        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 result: Float32Array[] = [];
-        for (let i = 0; i < texts.length; i++) {
-          const row = output.slice(i, null).tolist();
-          if (!Array.isArray(row) || row.some((value) => typeof value !== "number")) {
-            throw new Error("Embedding model returned non-numeric values.");
-          }
-          result.push(Float32Array.from(row));
-        }
-        return result;
+        const rows = Array.from({ length: texts.length }, (_, index) =>
+          output.slice(index, null).tolist(),
+        );
+        return parseLocalEmbeddingVectors(rows, texts.length, dim);
       }
 
       const embedding = config.inference.embedding;
-      const apiKey = embedding.api_key_env ? process.env[embedding.api_key_env] : undefined;
-      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",
-          ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}),
-        },
-        body: JSON.stringify({ model: embedding.model, input: texts }),
-        signal: AbortSignal.timeout(config.inference.timeout_ms),
-      });
-      if (!response.ok) throw new Error(`embeddings endpoint returned ${response.status}`);
-      const parsed = (await response.json()) as EmbeddingResponse;
-      const byIndex = [...parsed.data].sort((a, b) => a.index - b.index);
-      return byIndex.map((d) => Float32Array.from(d.embedding));
+      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;
+        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) {
@@ -94,22 +320,12 @@ export function createClients(config: Config): Clients {
     clients.rerank = async (query, docs) => {
       const reranker = inference.reranker;
       if (!reranker) throw new Error("Reranker is not configured.");
-      const apiKey = reranker.api_key_env ? process.env[reranker.api_key_env] : undefined;
-      const response = await fetch(`${reranker.base_url.replace(/\/$/, "")}/rerank`, {
-        method: "POST",
-        headers: { "content-type": "application/json", ...(apiKey ? { authorization: `Bearer ${apiKey}` } : {}) },
-        body: JSON.stringify({
-          model: reranker.model,
-          query,
-          documents: docs.map((d) => d.text),
-        }),
-        signal: AbortSignal.timeout(inference.timeout_ms),
-      });
-      if (!response.ok) throw new Error(`rerank endpoint returned ${response.status}`);
-      const parsed = (await response.json()) as RerankResponse;
-      const scores = new Array<number>(docs.length).fill(0);
-      for (const result of parsed.results) scores[result.index] = result.relevance_score;
-      return scores;
+      return fetchRerankerScores(
+        reranker,
+        inference.timeout_ms,
+        query,
+        docs,
+      );
     };
   }
   return clients;

package/src/commands/config.ts

@@ -0,0 +1,202 @@
+import { expandHome, migrateLegacyPaths, resolveConfigPath } from "../config";
+import { type TargetAdapter } from "../adapters";
+import { type ResolvedTarget } from "../context";
+import { applyConfigInit, planConfigInit, type ConfigInitPlan } from "../setup";
+import { emitSuccess, isInteractive, renderTargetBanner } from "../output";
+import { confirmAction } from "./shared";
+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: TargetAdapter,
+  sub: string,
+  args: string[],
+  ctx: { target: ResolvedTarget; 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 (option === "--dry-run" || option === "--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 data = await adapter.getConfigShow();
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, data, () => {
+      renderTargetBanner(ctx.target);
+      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, target: ctx.target },
+      { 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, target: ctx.target }, res, () => {
+      console.log(
+        res.valid ? "Configuration is valid." : "Configuration is invalid.",
+      );
+    });
+    return;
+  }
+
+  if (sub === "diff") {
+    const res = await adapter.configDiff();
+    emitSuccess({ isJson: ctx.isJson, target: ctx.target }, res, () => {
+      renderTargetBanner(ctx.target);
+      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, target: ctx.target }, res, () => {
+      renderTargetBanner(ctx.target);
+      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, target: ctx.target }, res, () => {
+      renderTargetBanner(ctx.target);
+      console.log(`Runtime: ${res.runtime}`);
+      console.log(`Active revision: ${res.active_revision}`);
+      console.log(`Readiness: ${res.readiness.status}`);
+    });
+    return;
+  }
+
+  throw new Error("usage: skillmux config show");
+}

package/src/commands/core.ts

@@ -0,0 +1,52 @@
+import { expandHome } from "../config";
+import { pinCore, unpinCore, validateManifest, writeManifestAtomic } from "../manifest";
+import { emitSuccess } from "../output";
+import { confirmIfNeeded, loadManifestContext } from "./shared";
+export async function runCore(
+  subCommand: string,
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  if (subCommand !== "pin" && subCommand !== "unpin") {
+    throw new Error("usage: skillmux core <pin|unpin>");
+  }
+  const skillIds = args.filter((arg) => !arg.startsWith("-"));
+  if (skillIds.length === 0) {
+    throw new Error(`usage: skillmux core ${subCommand} <skill_id>... --yes`);
+  }
+  const yes = args.includes("--yes");
+  const { config, vaultPath, manifestPath, manifest } =
+    await loadManifestContext();
+  let updated = manifest;
+  for (const skillId of skillIds) {
+    updated =
+      subCommand === "pin"
+        ? pinCore(updated, skillId)
+        : unpinCore(updated, skillId);
+  }
+  validateManifest(
+    updated,
+    vaultPath,
+    config.local_vault_paths.map(expandHome),
+  );
+  if (options.dryRun) {
+    emitSuccess(
+      { isJson: options.isJson },
+      { subcommand: subCommand, skill_ids: skillIds },
+      () =>
+        console.log(`${subCommand}: [core] ${skillIds.join(", ")} (dry-run)`),
+    );
+    return;
+  }
+  if (
+    !(await confirmIfNeeded({
+      confirmed: yes,
+      isJson: options.isJson,
+      prompt: `${subCommand} ${skillIds.join(", ")} in [core]?`,
+      nonInteractiveError: `skillmux core ${subCommand} requires --yes when run non-interactively`,
+    }))
+  )
+    return;
+  writeManifestAtomic(manifestPath, updated);
+  console.log(`${subCommand}: [core] ${skillIds.join(", ")}`);
+}