@klhapp/skillmux 1.9.3 → 1.11.0

package/src/output.ts

@@ -1,8 +1,10 @@
-import type { ResolvedTarget } from "./context";
+import type { ResolvedContext } from "./context";
 
 export interface JsonEnvelope<T = any> {
   schema_version: 1;
   ok: boolean;
+  context: string | { name: string; server: string };
+  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
   target: string | { name: string; server: string };
   data: T | null;
   error: { code: string; message: string; details?: any } | null;
@@ -10,27 +12,34 @@ export interface JsonEnvelope<T = any> {
 
 export function formatJsonEnvelope<T>(opts: {
   ok: boolean;
-  target: ResolvedTarget | string | { name: string; server: string };
+  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+  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> {
-  let targetVal: string | { name: string; server: string };
-  if (typeof opts.target === "string" || (typeof opts.target === "object" && "server" in opts.target && !("type" in opts.target))) {
-    targetVal = opts.target as any;
-  } else if (typeof opts.target === "object" && "type" in opts.target) {
-    if (opts.target.type === "local") {
-      targetVal = "local";
+  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 {
-      targetVal = { name: opts.target.name, server: opts.target.server };
+      contextVal = "local";
     }
   } else {
-    targetVal = "local";
+    contextVal = "local";
   }
 
   return {
     schema_version: 1,
     ok: opts.ok,
-    target: targetVal,
+    context: contextVal,
+    target: contextVal,
     data: opts.data ?? null,
     error: opts.error ?? null,
   };
@@ -51,12 +60,18 @@ export class CliError extends Error {
 }
 
 export function emitSuccess<T>(
-  ctx: { isJson: boolean; target?: ResolvedTarget | string | { name: string; server: string } },
+  ctx: {
+    isJson: boolean;
+    /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+    target?: ResolvedContext | string | { name: string; server: string };
+    context?: ResolvedContext | string | { name: string; server: string };
+  },
   data: T,
   renderText: () => void,
 ): void {
   if (ctx.isJson) {
-    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, target: ctx.target ?? "local", data })));
+    const contextVal = ctx.context ?? ctx.target ?? "local";
+    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, context: contextVal, target: contextVal, data })));
   } else {
     renderText();
   }
@@ -112,6 +127,28 @@ export function suggestCorrection(input: string, candidates: string[]): string |
   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,
@@ -119,12 +156,37 @@ export function isInteractive(
   return stdoutIsTTY === true && env.TERM !== "dumb";
 }
 
-export function renderTargetBanner(target: ResolvedTarget): void {
+/** 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 (target.type === "local") {
-    console.log(`Target: local`);
+  if (context.type === "local") {
+    console.log(`Context: local`);
   } else {
-    console.log(`Target: remote (${target.name} -> ${target.server})`);
+    console.log(`Context: remote (${context.name} -> ${context.server})`);
   }
 }
 
@@ -143,7 +205,7 @@ export function renderTable(columns: { key: string; header: string }[], rows: Re
   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(headerLine);
+  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("  ");

package/src/prompts.ts

@@ -1,4 +1,63 @@
 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;
@@ -35,35 +94,31 @@ export function shouldUseWizard(
 export async function promptMultiSelect<T extends string>(
   question: string,
   options: readonly SelectOption<T>[],
+  io: PromptIO = {},
 ): Promise<T[]> {
-  console.log(`\n${question}`);
+  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}` : "";
-    console.log(`  ${index + 1}. [${checked}] ${option.label}${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 readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const suffix = defaults ? ` [${defaults}]` : "";
-    const answer = await readline.question(`Select numbers, comma-separated${suffix}: `);
-    const selection = answer.trim() === "" && defaults ? defaults : answer;
-    return parseNumberSelection(selection, options.length).map((index) => options[index]!.value);
-  } finally {
-    readline.close();
-  }
+  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 = ""): Promise<string> {
-  const readline = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const suffix = defaultValue ? ` [${defaultValue}]` : "";
-    const answer = (await readline.question(`${question}${suffix}: `)).trim();
-    return answer || defaultValue;
-  } finally {
-    readline.close();
-  }
+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;
 }

package/src/router-core.ts

@@ -4,6 +4,8 @@ import { join } from "node:path";
 import { buildAuditRow } from "./audit";
 import { embeddingDimension, embeddingFingerprint, expandHome, loadConfig } from "./config";
 import { RemoteInferenceError } from "./clients";
+import { log } from "./logger";
+import { warn } from "./output";
 import {
   deleteSkill,
   findExactMatch,
@@ -274,7 +276,7 @@ export async function syncVaultIfNeeded(): Promise<void> {
     const invalidIds: string[] = [];
     const skills = await scanVaults(vaultPath, localVaultPaths, (skillId, error) => {
       invalidIds.push(skillId);
-      console.error(`warning: keeping previous index entry for ${skillId}: ${error}`);
+      warn(`keeping previous index entry for ${skillId}: ${error}`);
     });
     const rows = skills.map(toSkillRow);
     // See rebuildIndex: a skill_id invalid in one root can still be valid in
@@ -361,7 +363,7 @@ async function reindexOneSkill(db: Database, vaultPath: string, skillId: string)
     upsertSkill(db, await readSkill(vaultPath, skillId));
     backfillEmbeddings().catch(() => {});
   } catch (error) {
-    console.error(`warning: keeping previous index entry for ${skillId}: ${error}`);
+    warn(`keeping previous index entry for ${skillId}: ${error}`);
   }
 }
 
@@ -395,7 +397,7 @@ export async function startVaultWatcher(): Promise<() => void> {
   // A watcher error (e.g. the vault root disappearing) must degrade the index,
   // not crash the server — an unhandled 'error' event would throw.
   watcher.on("error", (error) => {
-    console.error(`warning: vault watcher error, live updates paused: ${error}`);
+    warn(`vault watcher error, live updates paused: ${error}`);
   });
 
   return () => {
@@ -554,14 +556,7 @@ export async function retrieveAndRerank(
       retrieval = "lexical";
       degraded_from = clients.rerank ? "reranked" : "hybrid";
       degradation_reason = classifyInferenceError("embedding", embedRes.error);
-      console.error(
-        JSON.stringify({
-          level: "warn",
-          stage: "embedding",
-          degraded_from,
-          reason: degradation_reason,
-        }),
-      );
+      log.warn("embedding", { degraded_from, reason: degradation_reason });
     } else {
       try {
         const queryVec = (embedRes as Float32Array[])[0];
@@ -574,14 +569,7 @@ export async function retrieveAndRerank(
         retrieval = "lexical";
         degraded_from = clients.rerank ? "reranked" : "hybrid";
         degradation_reason = classifyInferenceError("embedding", embedError);
-        console.error(
-          JSON.stringify({
-            level: "warn",
-            stage: "embedding",
-            degraded_from,
-            reason: degradation_reason,
-          }),
-        );
+        log.warn("embedding", { degraded_from, reason: degradation_reason });
       }
     }
   }
@@ -601,14 +589,7 @@ export async function retrieveAndRerank(
       scores = null;
       degraded_from = "reranked";
       degradation_reason = classifyInferenceError("reranker", rerankError);
-      console.error(
-        JSON.stringify({
-          level: "warn",
-          stage: "reranker",
-          degraded_from,
-          reason: degradation_reason,
-        }),
-      );
+      log.warn("reranker", { degraded_from, reason: degradation_reason });
     }
   }
 

package/src/scan.ts

@@ -156,7 +156,7 @@ export interface ScanResult {
   findings: ScanFinding[];
 }
 
-interface ScanContentTarget {
+interface ScanContentFile {
   skill_id: string;
   file: string;
   content: string;
@@ -177,21 +177,21 @@ export async function readTextFileOrNull(path: string): Promise<string | null> {
   }
 }
 
-async function collectSkillTargets(
+async function collectSkillFiles(
   vaultPath: string,
   skillId: string,
   skillMdBody: string,
-): Promise<ScanContentTarget[]> {
-  const targets: ScanContentTarget[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
+): Promise<ScanContentFile[]> {
+  const files: ScanContentFile[] = [{ skill_id: skillId, file: "SKILL.md", content: skillMdBody }];
   for (const rel of listSupportingFiles(vaultPath, skillId)) {
     const content = await readTextFileOrNull(join(vaultPath, skillId, rel));
-    if (content !== null) targets.push({ skill_id: skillId, file: rel, content });
+    if (content !== null) files.push({ skill_id: skillId, file: rel, content });
   }
-  return targets;
+  return files;
 }
 
-interface ResolvedScanTargets {
-  targets: ScanContentTarget[];
+interface ResolvedScanFiles {
+  files: ScanContentFile[];
   /** skill_ids whose SKILL.md could not be parsed/decoded — must still be counted and
    *  flagged, never silently dropped, or a malformed SKILL.md becomes a scan-evasion trick. */
   unparseable: string[];
@@ -199,32 +199,32 @@ interface ResolvedScanTargets {
 
 /** Single-skill-dir mode when `rootPath` itself holds a SKILL.md; otherwise treats
  *  `rootPath` as a vault root and enumerates every skill dir under it. */
-async function resolveScanTargets(rootPath: string): Promise<ResolvedScanTargets> {
+async function resolveScanFiles(rootPath: string): Promise<ResolvedScanFiles> {
   if (existsSync(join(rootPath, "SKILL.md"))) {
     const skillId = basename(rootPath);
     const vaultPath = dirname(rootPath);
     const body = await readTextFileOrNull(join(rootPath, "SKILL.md"));
-    if (body === null) return { targets: [], unparseable: [skillId] };
-    return { targets: await collectSkillTargets(vaultPath, skillId, body), unparseable: [] };
+    if (body === null) return { files: [], unparseable: [skillId] };
+    return { files: await collectSkillFiles(vaultPath, skillId, body), unparseable: [] };
   }
 
   const unparseable: string[] = [];
   const skills = await scanVault(rootPath, (skillId) => unparseable.push(skillId));
-  const targets: ScanContentTarget[] = [];
+  const files: ScanContentFile[] = [];
   for (const skill of skills) {
-    targets.push(...(await collectSkillTargets(rootPath, skill.skill_id, skill.body)));
+    files.push(...(await collectSkillFiles(rootPath, skill.skill_id, skill.body)));
   }
-  return { targets, unparseable };
+  return { files, unparseable };
 }
 
 export async function scanPath(rootPath: string): Promise<ScanResult> {
-  const { targets, unparseable } = await resolveScanTargets(rootPath);
+  const { files, unparseable } = await resolveScanFiles(rootPath);
   const findings: ScanFinding[] = [];
   const skillIds = new Set<string>();
-  for (const target of targets) {
-    skillIds.add(target.skill_id);
-    for (const match of scanContent(target.content)) {
-      findings.push({ ...match, skill_id: target.skill_id, file: target.file });
+  for (const file of files) {
+    skillIds.add(file.skill_id);
+    for (const match of scanContent(file.content)) {
+      findings.push({ ...match, skill_id: file.skill_id, file: file.file });
     }
   }
   for (const skillId of unparseable) {

package/src/server.ts

@@ -16,13 +16,15 @@ import {
   resolveSkill,
 } from "./router-core";
 import { closeRuntime, getRuntime, startVaultWatcher } from "./router-core";
-import { getStats, SINCE_PATTERN } from "./stats";
+import { getStats, parseSince, SINCE_PATTERN } from "./stats";
+import { countPrunable, insertAdminAuditRow, pruneAuditBefore, type AdminAuditChange } from "./db";
+import { buildPromotedCases, evalVault, queryPromotableFetches } from "./eval";
 import { SKILL_ID_PATTERN } from "./vault";
 import { MetricsRegistry } from "./metrics";
 import { ReadinessState } from "./readiness";
 import { initializeRuntime } from "./lifecycle";
 import { buildRedactor } from "./redact";
-import { insertAdminAuditRow, type AdminAuditChange } from "./db";
+import { redactedErrorLog } from "./logger";
 import type { Clients, Config } from "./types";
 import {
   computeHash,
@@ -41,16 +43,6 @@ export const readinessState = new ReadinessState();
 const DEFAULT_MAX_BODY_BYTES = 1_048_576; // 1 MiB
 const DEFAULT_MAX_CONCURRENT_REQUESTS = 100;
 
-/** Pairs a fixed log prefix with a redacted error message, for console.error. */
-export function redactedErrorLog(
-  prefix: string,
-  err: unknown,
-  redact: (text: string) => string,
-): [string, string] {
-  const msg = err instanceof Error ? err.message : String(err);
-  return [prefix, redact(msg)];
-}
-
 export interface ServerHandle {
   port?: number;
   statsPort?: number;
@@ -409,7 +401,7 @@ export async function startServer(opts?: {
             allowed_origins: [],
           };
           const origin = req.headers.get("origin") || "";
-          const allowedOrigins = serverConfig.allowed_origins;
+          const allowedOrigins = serverConfig.allowed_origins || [];
           const isAllowed =
             allowedOrigins.includes("*") || allowedOrigins.includes(origin);
           const allowOriginHeader = isAllowed
@@ -676,7 +668,7 @@ export async function startServer(opts?: {
               const auditChanges: AdminAuditChange[] = [];
               for (const [k, v] of Object.entries(body.changes ?? {})) {
                 lastResult = await setDottedKey(k, String(v), {
-                  targetName: "remote",
+                  contextName: "remote",
                 });
                 auditChanges.push({
                   key: k,
@@ -700,6 +692,161 @@ export async function startServer(opts?: {
               });
             }
 
+            if (
+              req.method === "POST" &&
+              url.pathname === "/admin/v1/audit/prune"
+            ) {
+              let body: {
+                older_than?: string;
+                dry_run?: boolean;
+                confirm?: boolean;
+              } = {};
+              try {
+                const text = await req.text();
+                if (text.trim()) {
+                  body = JSON.parse(text);
+                }
+              } catch {
+                return new Response(
+                  JSON.stringify({
+                    error: "INVALID_JSON",
+                    message: "Request body must be valid JSON",
+                  }),
+                  { status: 400, headers },
+                );
+              }
+
+              const dryRun = body.dry_run ?? false;
+              const confirm = body.confirm ?? false;
+              if (!dryRun && !confirm) {
+                return new Response(
+                  JSON.stringify({
+                    error: "CONFIRMATION_REQUIRED",
+                    message:
+                      "Non-dry-run audit prune requires confirm: true",
+                  }),
+                  { status: 400, headers },
+                );
+              }
+
+              const { effective } = await getEffectiveConfig(configPath);
+              let cutoff: Date;
+              if (body.older_than) {
+                try {
+                  cutoff = parseSince(body.older_than);
+                } catch (err: any) {
+                  return new Response(
+                    JSON.stringify({
+                      error: "INVALID_CUTOFF",
+                      message: err.message,
+                    }),
+                    { status: 400, headers },
+                  );
+                }
+              } else {
+                const retentionDays = effective.audit?.retention_days ?? 90;
+                if (retentionDays <= 0) {
+                  return new Response(
+                    JSON.stringify({
+                      audit_deleted: 0,
+                      fetch_deleted: 0,
+                      admin_audit_deleted: 0,
+                      dry_run: dryRun,
+                      cutoff: null,
+                    }),
+                    { status: 200, headers },
+                  );
+                }
+                cutoff = new Date(Date.now() - retentionDays * 86_400_000);
+              }
+              const cutoffIso = cutoff.toISOString();
+
+              const { auditDb } = await getRuntime();
+              if (dryRun) {
+                const counts = countPrunable(auditDb, cutoffIso);
+                return new Response(
+                  JSON.stringify({
+                    ...counts,
+                    dry_run: true,
+                    cutoff: cutoffIso,
+                  }),
+                  { status: 200, headers },
+                );
+              }
+
+              const counts = pruneAuditBefore(auditDb, cutoffIso);
+              return new Response(
+                JSON.stringify({
+                  ...counts,
+                  dry_run: false,
+                  cutoff: cutoffIso,
+                }),
+                { status: 200, headers },
+              );
+            }
+
+            if (req.method === "POST" && url.pathname === "/admin/v1/eval") {
+              const report = await evalVault();
+              return new Response(JSON.stringify(report), {
+                status: 200,
+                headers,
+              });
+            }
+
+            if (
+              req.method === "POST" &&
+              url.pathname === "/admin/v1/eval/promote"
+            ) {
+              let body: { since?: string } = {};
+              try {
+                const text = await req.text();
+                if (text.trim()) {
+                  body = JSON.parse(text);
+                }
+              } catch {
+                return new Response(
+                  JSON.stringify({
+                    error: "INVALID_JSON",
+                    message: "Request body must be valid JSON",
+                  }),
+                  { status: 400, headers },
+                );
+              }
+
+              if (!body.since || typeof body.since !== "string") {
+                return new Response(
+                  JSON.stringify({
+                    error: "MISSING_SINCE",
+                    message: "Field 'since' is required",
+                  }),
+                  { status: 400, headers },
+                );
+              }
+
+              let sinceDate: Date;
+              try {
+                sinceDate = parseSince(body.since);
+              } catch (err: any) {
+                return new Response(
+                  JSON.stringify({
+                    error: "INVALID_SINCE",
+                    message: err.message,
+                  }),
+                  { status: 400, headers },
+                );
+              }
+              const sinceIso = sinceDate.toISOString();
+
+              const { auditDb } = await getRuntime();
+              const candidates = buildPromotedCases(
+                queryPromotableFetches(auditDb, sinceIso),
+              );
+              return new Response(JSON.stringify({ candidates }), {
+                status: 200,
+                headers,
+              });
+            }
+
             return new Response("Not Found", { status: 404, headers });
           }