@klhapp/skillmux 1.7.1 → 1.9.0

package/src/commands/audit.ts

@@ -0,0 +1,82 @@
+import { expandHome, loadConfig } from "../config";
+import { countPrunable, openAudit, pruneAuditBefore } from "../db";
+import { parseSince } from "../stats";
+import { emitSuccess } from "../output";
+import { confirmIfNeeded } from "./shared";
+
+export async function runAudit(
+  subCommand: string,
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): 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 (arg === "--json") {
+      // handled globally by main()'s isJson flag; recognized here so it isn't rejected
+    } else if (arg?.startsWith("--")) {
+      throw new Error(`unknown audit prune option: ${arg}`);
+    }
+  }
+
+  const config = await loadConfig();
+  const stateDir = expandHome(config.state_dir);
+
+  let cutoff: Date;
+  if (olderThan) {
+    cutoff = parseSince(olderThan);
+  } else {
+    const retentionDays = config.audit?.retention_days ?? 90;
+    if (retentionDays <= 0) {
+      emitSuccess(
+        { isJson: options.isJson },
+        { audit_deleted: 0, fetch_deleted: 0, dry_run: dryRun, cutoff: null },
+        () => console.log("prune: audit.retention_days is 0 (pruning disabled); nothing to do"),
+      );
+      return;
+    }
+    cutoff = new Date(Date.now() - retentionDays * 86_400_000);
+  }
+  const cutoffIso = cutoff.toISOString();
+
+  const db = openAudit(stateDir);
+  try {
+    if (dryRun) {
+      const counts = countPrunable(db, cutoffIso);
+      emitSuccess(
+        { isJson: options.isJson },
+        { ...counts, dry_run: true, cutoff: cutoffIso },
+        () => console.log(`prune: audit=${counts.audit_deleted} fetch=${counts.fetch_deleted} (dry-run)`),
+      );
+      return;
+    }
+
+    if (
+      !(await confirmIfNeeded({
+        confirmed: yes,
+        isJson: options.isJson,
+        prompt: `prune audit rows older than ${cutoffIso}?`,
+        nonInteractiveError: "skillmux audit prune requires --yes when run non-interactively",
+      }))
+    )
+      return;
+
+    const counts = pruneAuditBefore(db, cutoffIso);
+    emitSuccess(
+      { isJson: options.isJson },
+      { ...counts, dry_run: false, cutoff: cutoffIso },
+      () => console.log(`prune: audit=${counts.audit_deleted} fetch=${counts.fetch_deleted}`),
+    );
+  } finally {
+    db.close();
+  }
+}

package/src/commands/eval.ts

@@ -0,0 +1,81 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import { openAudit } from "../db";
+import { buildPromotedCases, excludeExistingCases, parseEvalCases, queryPromotableFetches } from "../eval";
+import { emitSuccess } from "../output";
+import { parseSince } from "../stats";
+import { confirmIfNeeded } from "./shared";
+
+export async function runEvalPromote(
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  let since: string | undefined;
+  let target: string | undefined;
+  let dryRun = options.dryRun;
+  let yes = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--since") since = args[++i];
+    else if (arg === "--target") target = args[++i];
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--yes") yes = true;
+    else if (arg === "--json") {
+      // handled globally by main()'s isJson flag; recognized here so it isn't rejected
+    } else if (arg?.startsWith("--")) {
+      throw new Error(`unknown eval promote option: ${arg}`);
+    }
+  }
+  if (!since) {
+    throw new Error("usage: skillmux eval promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]");
+  }
+
+  const config = await loadConfig();
+  const stateDir = expandHome(config.state_dir);
+  const targetPath = target ?? join(stateDir, "eval-observed.json");
+  const sinceDate = parseSince(since);
+  const sinceIso = sinceDate.toISOString();
+
+  const db = openAudit(stateDir);
+  let candidates: ReturnType<typeof buildPromotedCases>;
+  try {
+    candidates = buildPromotedCases(queryPromotableFetches(db, sinceIso));
+  } finally {
+    db.close();
+  }
+
+  const existing = existsSync(targetPath) ? parseEvalCases(JSON.parse(readFileSync(targetPath, "utf-8"))) : [];
+  const { cases: newCases, skipped } = excludeExistingCases(candidates, existing);
+
+  console.error("warning: promoted eval cases contain raw user queries");
+
+  if (dryRun) {
+    emitSuccess(
+      { isJson: options.isJson },
+      { dry_run: true, since: sinceIso, target_path: targetPath, promoted: newCases.length, skipped_existing: skipped },
+      () => console.log(`promote: would write ${newCases.length} case(s) to ${targetPath} (skipped_existing=${skipped})`),
+    );
+    return;
+  }
+
+  if (
+    !(await confirmIfNeeded({
+      confirmed: yes,
+      isJson: options.isJson,
+      prompt: `promote ${newCases.length} eval case(s) to ${targetPath}?`,
+      nonInteractiveError: "skillmux eval promote requires --yes when run non-interactively",
+    }))
+  )
+    return;
+
+  if (newCases.length > 0) {
+    writeFileSync(targetPath, JSON.stringify([...existing, ...newCases], null, 2) + "\n");
+  }
+
+  emitSuccess(
+    { isJson: options.isJson },
+    { dry_run: false, since: sinceIso, target_path: targetPath, promoted: newCases.length, skipped_existing: skipped },
+    () => console.log(`promote: wrote ${newCases.length} case(s) to ${targetPath} (skipped_existing=${skipped})`),
+  );
+}

package/src/commands/outdated.ts

@@ -0,0 +1,112 @@
+import { readdirSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import { isLocalFileUrl, remoteHeadCommit } from "../install";
+import { emitSuccess } from "../output";
+import { readSkillOrigin } from "../provenance";
+import { SKILL_ID_PATTERN } from "../vault";
+
+export interface OutdatedCheckResult {
+  skill_id: string;
+  source_url: string;
+  recorded_commit: string;
+  remote_commit: string | null;
+  status: "up_to_date" | "outdated" | "check_failed" | "local_source_skipped";
+  reason: string | null;
+}
+
+function vaultSkillIds(vaultPath: string): string[] {
+  return readdirSync(vaultPath, { withFileTypes: true })
+    .filter((entry) => entry.isDirectory() && SKILL_ID_PATTERN.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+}
+
+export async function checkOutdated(
+  vaultPath: string,
+  options: { allowLocalSource?: boolean } = {},
+): Promise<OutdatedCheckResult[]> {
+  const results: OutdatedCheckResult[] = [];
+  for (const skillId of vaultSkillIds(vaultPath)) {
+    let origin: ReturnType<typeof readSkillOrigin>;
+    try {
+      origin = readSkillOrigin(join(vaultPath, skillId));
+    } catch (error) {
+      // A corrupt or unreadable sidecar is this skill's problem alone — never
+      // let it abort the check for every other skill in the vault (AC3/AC4's
+      // per-skill isolation applies to local parse failures too, not just
+      // unreachable remotes).
+      results.push({
+        skill_id: skillId,
+        source_url: "",
+        recorded_commit: "",
+        remote_commit: null,
+        status: "check_failed",
+        reason: `.skillmux-origin: ${error instanceof Error ? error.message : String(error)}`,
+      });
+      continue;
+    }
+    if (!origin) continue;
+
+    if (!options.allowLocalSource && isLocalFileUrl(origin.source_url)) {
+      results.push({
+        skill_id: skillId,
+        source_url: origin.source_url,
+        recorded_commit: origin.commit,
+        remote_commit: null,
+        status: "local_source_skipped",
+        reason: "source_url is a local file:// path — skipped by default; pass --allow-local-source to check it",
+      });
+      continue;
+    }
+
+    let remoteCommit: string | null = null;
+    let status: OutdatedCheckResult["status"];
+    let reason: string | null = null;
+    try {
+      remoteCommit = await remoteHeadCommit(origin.source_url);
+      status = remoteCommit === origin.commit ? "up_to_date" : "outdated";
+    } catch (error) {
+      status = "check_failed";
+      reason = error instanceof Error ? error.message : String(error);
+    }
+
+    results.push({
+      skill_id: skillId,
+      source_url: origin.source_url,
+      recorded_commit: origin.commit,
+      remote_commit: remoteCommit,
+      status,
+      reason,
+    });
+  }
+  return results;
+}
+
+export async function runOutdated(args: string[], options: { isJson: boolean }): Promise<void> {
+  let allowLocalSource = false;
+  for (const arg of args) {
+    if (arg === "--json") continue;
+    if (arg === "--allow-local-source") {
+      allowLocalSource = true;
+      continue;
+    }
+    throw new Error(`unknown outdated option: ${arg}`);
+  }
+
+  const vaultPath = expandHome((await loadConfig()).vault_path);
+  const skills = await checkOutdated(vaultPath, { allowLocalSource });
+  const checksFailed = skills.filter((s) => s.status === "check_failed").length;
+  process.exitCode = checksFailed > 0 ? 1 : 0;
+
+  emitSuccess({ isJson: options.isJson }, { skills, checks_failed: checksFailed }, () => {
+    if (skills.length === 0) {
+      console.log("outdated: no vault skills carry provenance");
+      return;
+    }
+    for (const s of skills) {
+      const suffix = s.status === "check_failed" ? ` — ${s.reason}` : "";
+      console.log(`[${s.status}] ${s.skill_id}${suffix}`);
+    }
+  });
+}

package/src/commands/update.ts

@@ -0,0 +1,253 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import {
+  cloneToTemp,
+  installIntoVault,
+  isLocalFileUrl,
+  remoteHeadCommit,
+  resolveCloneCommit,
+  resolveSkillDir,
+  validateSkillCandidate,
+} from "../install";
+import { emitSuccess } from "../output";
+import { hashSkillContent, readSkillOrigin, writeSkillOrigin } from "../provenance";
+import type { SkillOrigin } from "../provenance";
+import { type ScanFinding, type ScanSeverity, scanExitCode } from "../scan";
+import { confirmIfNeeded } from "./shared";
+import { checkOutdated } from "./outdated";
+
+type UpdateKind = "update" | "up_to_date" | "skip_drift" | "skip_scan_failed" | "skip_read_error";
+
+interface UpdatePlanItem {
+  skillId: string;
+  oldCommit: string;
+  newCommit: string;
+  contentChanged: boolean;
+  kind: UpdateKind;
+  findings?: ScanFinding[];
+  reason?: string;
+  cloneDir: string | null;
+  fetchedDir: string | null;
+  origin: SkillOrigin;
+}
+
+async function resolveCandidateOrigins(
+  vaultPath: string,
+  skillId: string | undefined,
+  allowLocalSource: boolean,
+): Promise<{ skillId: string; origin: SkillOrigin }[]> {
+  if (skillId) {
+    let origin: SkillOrigin | null;
+    try {
+      origin = readSkillOrigin(join(vaultPath, skillId));
+    } catch (error) {
+      throw new Error(
+        `"${skillId}" has a corrupt .skillmux-origin sidecar: ${error instanceof Error ? error.message : String(error)}`,
+      );
+    }
+    if (!origin) {
+      throw new Error(`"${skillId}" has no origin recorded — was this skill installed via "skillmux install"?`);
+    }
+    if (!allowLocalSource && isLocalFileUrl(origin.source_url)) {
+      throw new Error(`"${skillId}" has a local (file://) source — pass --allow-local-source to update it`);
+    }
+    return [{ skillId, origin }];
+  }
+  const outdated = await checkOutdated(vaultPath, { allowLocalSource });
+  return outdated
+    .filter((result) => result.status === "outdated")
+    .map((result) => ({ skillId: result.skill_id, origin: readSkillOrigin(join(vaultPath, result.skill_id))! }));
+}
+
+async function buildPlan(
+  vaultPath: string,
+  candidates: { skillId: string; origin: SkillOrigin }[],
+  failOn: ScanSeverity | undefined,
+  force: boolean,
+): Promise<UpdatePlanItem[]> {
+  const plan: UpdatePlanItem[] = [];
+  for (const { skillId, origin } of candidates) {
+    const skillDir = join(vaultPath, skillId);
+    let currentHash: string;
+    try {
+      currentHash = hashSkillContent(skillDir);
+    } catch (error) {
+      // A skill whose on-disk content can't be safely read (e.g. SKILL.md was
+      // swapped for a symlink after install — same threat model as AC7's drift
+      // check) is this skill's problem alone, matching checkOutdated's per-skill
+      // isolation: never let it abort the batch for every other candidate.
+      plan.push({
+        skillId,
+        oldCommit: origin.commit,
+        newCommit: origin.commit,
+        contentChanged: false,
+        kind: "skip_read_error",
+        reason: error instanceof Error ? error.message : String(error),
+        cloneDir: null,
+        fetchedDir: null,
+        origin,
+      });
+      continue;
+    }
+
+    // Drift is a purely local comparison — check it before fetching anything,
+    // so a drifted (and therefore skipped) skill never pays for a clone.
+    if (currentHash !== origin.content_hash && !force) {
+      plan.push({
+        skillId,
+        oldCommit: origin.commit,
+        newCommit: await remoteHeadCommit(origin.source_url),
+        contentChanged: false,
+        kind: "skip_drift",
+        cloneDir: null,
+        fetchedDir: null,
+        origin,
+      });
+      continue;
+    }
+
+    const cloneDir = await cloneToTemp(origin.source_url);
+    const resolved = resolveSkillDir(cloneDir, skillId, origin.skill_path);
+    const base = {
+      skillId,
+      oldCommit: origin.commit,
+      newCommit: resolveCloneCommit(cloneDir),
+      cloneDir,
+      fetchedDir: resolved.dir,
+      origin,
+    };
+
+    const { findings } = await validateSkillCandidate(skillId, resolved.dir);
+    if (scanExitCode(findings, failOn) !== 0) {
+      plan.push({ ...base, contentChanged: false, kind: "skip_scan_failed", findings });
+      continue;
+    }
+
+    const contentChanged = hashSkillContent(resolved.dir) !== currentHash;
+    plan.push({
+      ...base,
+      contentChanged,
+      kind: base.newCommit === origin.commit && !contentChanged ? "up_to_date" : "update",
+    });
+  }
+  return plan;
+}
+
+export function buildConfirmPrompt(toWrite: Pick<UpdatePlanItem, "skillId" | "origin">[]): string {
+  const lines = toWrite.map((item) => `  ${item.skillId} <- ${item.origin.source_url}`);
+  return `update:\n${lines.join("\n")}\n?`;
+}
+
+function statusFor(kind: UpdateKind, dryRun: boolean): string {
+  switch (kind) {
+    case "update":
+      return dryRun ? "would_update" : "updated";
+    case "skip_drift":
+      return dryRun ? "would_skip_drift" : "skipped_drift";
+    case "skip_scan_failed":
+      return dryRun ? "would_skip_scan_failed" : "skipped_scan_failed";
+    case "skip_read_error":
+      return "skipped_read_error";
+    default:
+      return "up_to_date";
+  }
+}
+
+function parseUpdateArgs(args: string[]): {
+  skillId?: string;
+  yes: boolean;
+  dryRun: boolean;
+  force: boolean;
+  failOn?: ScanSeverity;
+  allowLocalSource: boolean;
+} {
+  let skillId: string | undefined;
+  let yes = false;
+  let dryRun = false;
+  let force = false;
+  let failOn: ScanSeverity | undefined;
+  let allowLocalSource = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "--yes") yes = true;
+    else if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--force") force = true;
+    else if (arg === "--allow-local-source") allowLocalSource = true;
+    else if (arg === "--fail-on") {
+      const value = args[++i];
+      if (value !== "low" && value !== "medium" && value !== "high") {
+        throw new Error("--fail-on must be low, medium, or high");
+      }
+      failOn = value;
+    } else if (arg === "--json") {
+      // handled globally
+    } else if (arg?.startsWith("--")) {
+      throw new Error(`unknown update option: ${arg}`);
+    } else if (skillId !== undefined) {
+      throw new Error("skillmux update accepts at most one <skill-id> argument");
+    } else {
+      skillId = arg;
+    }
+  }
+  return { skillId, yes, dryRun, force, failOn, allowLocalSource };
+}
+
+export async function runUpdate(args: string[], options: { isJson: boolean }): Promise<void> {
+  const { skillId, yes, dryRun, force, failOn, allowLocalSource } = parseUpdateArgs(args);
+  const vaultPath = expandHome((await loadConfig()).vault_path);
+
+  const candidates = await resolveCandidateOrigins(vaultPath, skillId, allowLocalSource);
+  const plan = await buildPlan(vaultPath, candidates, failOn, force);
+  try {
+    const toWrite = plan.filter((item) => item.kind === "update");
+
+    if (!dryRun && toWrite.length > 0) {
+      const proceed = await confirmIfNeeded({
+        confirmed: yes,
+        isJson: options.isJson,
+        prompt: buildConfirmPrompt(toWrite),
+        nonInteractiveError: "skillmux update requires --yes when run non-interactively",
+      });
+      if (!proceed) return;
+
+      for (const item of toWrite) {
+        // toWrite is filtered to kind === "update", which is only ever set after
+        // a successful clone above, so fetchedDir is always populated here.
+        const targetDir = installIntoVault(vaultPath, item.skillId, item.fetchedDir as string, true);
+        writeSkillOrigin(targetDir, {
+          source_url: item.origin.source_url,
+          skill_path: item.origin.skill_path,
+          commit: item.newCommit,
+          installed_at: new Date().toISOString(),
+          content_hash: hashSkillContent(targetDir),
+        });
+      }
+    }
+
+    const skills = plan.map((item) => ({
+      skill_id: item.skillId,
+      source_url: item.origin.source_url,
+      old_commit: item.oldCommit,
+      new_commit: item.newCommit,
+      content_changed: item.contentChanged,
+      status: statusFor(item.kind, dryRun),
+      ...(item.findings ? { findings: item.findings } : {}),
+      ...(item.reason ? { reason: item.reason } : {}),
+    }));
+
+    emitSuccess({ isJson: options.isJson }, { dry_run: dryRun, skills }, () => {
+      if (skills.length === 0) {
+        console.log("update: nothing to do");
+        return;
+      }
+      for (const s of skills) {
+        console.log(`[${s.status}] ${s.skill_id}`);
+      }
+    });
+  } finally {
+    for (const item of plan) {
+      if (item.cloneDir) rmSync(item.cloneDir, { recursive: true, force: true });
+    }
+  }
+}

package/src/config.ts

@@ -88,6 +88,9 @@ const configSchema = z.object({
       token_env: z.string().min(1),
     }).strict().optional(),
   }).strict().optional(),
+  audit: z.object({
+    retention_days: z.number().int().min(0).default(90),
+  }).strict().default({ retention_days: 90 }),
 }).strict().refine((cfg) => {
   const hasReranker = cfg.inference.mode === "remote" && !!cfg.inference.reranker;
   if (hasReranker && cfg.output.max_top_k > cfg.recall.k_rerank) {
@@ -139,6 +142,9 @@ const DEFAULTS: Config = {
       requests_per_minute: 60,
     },
   },
+  audit: {
+    retention_days: 90,
+  },
 };
 
 export const DEFAULT_CONFIG_PATH = "~/.config/skillmux/config.toml";