@klhapp/skillmux 1.9.3 → 1.11.0

package/docs/skill-management.md

@@ -1,11 +1,11 @@
 # Managing skills
 
 Skillmux keeps skill content in a vault checkout and materializes selected
-skills into client directories. The vault source of truth is the logical
+skills into agent directories. The vault source of truth is the logical
 collection; a checkout is its physical copy. This guide covers the commands
 that change or inspect that state.
 
-Run these commands on the machine that owns the vault checkout and client
+Run these commands on the machine that owns the vault checkout and agent
 directories. For a retrieval-only Docker service, manage the mounted checkout
 on the host and keep the container mount read-only; the server image does not
 manage host agent directories.
@@ -114,28 +114,28 @@ skill whose on-disk content has drifted from what was last installed —
 someone may have hand-edited it. Pass `--force` to overwrite anyway. Like
 `audit prune`, a non-interactive or `--json` run needs `--yes`.
 
-## Plan client delivery
+## Plan agent delivery
 
-Use product names for common clients:
+Use product names for common agents:
 
 ```sh
-skillmux init --client claude-code --client codex --dry-run
+skillmux init --agent claude-code --agent codex --dry-run
 ```
 
-Use a direct target when you need a known path:
+For a directory that isn't tied to any supported agent, use `target add`
+directly instead of `init`:
 
 ```sh
-skillmux init --target agent-skills --yes
-skillmux init --target custom --dir /srv/my-agent/skills --yes
+skillmux target add my-agent --dir /srv/my-agent/skills --yes
 ```
 
 Skillmux refuses to adopt a target that points to the whole vault because sync
 would reduce its visible skills. Review that migration first:
 
 ```sh
-skillmux init --client claude-code --migrate-full-vault \
+skillmux init --agent claude-code --migrate-full-vault \
   --core csv-formatter --dry-run
-skillmux init --client claude-code --migrate-full-vault \
+skillmux init --agent claude-code --migrate-full-vault \
   --core csv-formatter --yes
 ```
 
@@ -170,7 +170,7 @@ skillmux project list
 skillmux project show my-project
 skillmux project add-path my-project ~/code/my-project --yes
 skillmux project pin my-project code-context --yes
-skillmux project attach my-project --client claude-code --client codex --yes
+skillmux project attach my-project --agent claude-code --agent codex --yes
 skillmux project unpin my-project code-context --yes
 skillmux project detach my-project --target codex --yes
 skillmux project remove-path my-project ~/code/my-project --yes
@@ -267,6 +267,12 @@ true` with a token, or it refuses to start. `--stats-port` is rejected
 alongside `--transport http`, since that transport already serves `/stats` on
 `--port`.
 
+`--context`/`--server` work the same way for `audit prune`, `eval`, `eval
+promote`, and `doctor` — each hits the matching `/admin/v1/*` route on the
+named deployment instead of the local vault and audit db. See [CLI
+reference](cli.md#administrative-http-api-adminv1) for the full remote
+command surface and route table.
+
 ## Target ownership and recovery
 
 `skillmux target remove <name> --yes` removes the manifest record and preserves

package/docs/troubleshooting.md

@@ -113,8 +113,8 @@ also reveals local-overlay shadowing.
 Skillmux will not change an existing unmarked directory. Adopt it first:
 
 ```sh
-skillmux init --client claude-code --dry-run
-skillmux init --client claude-code --yes
+skillmux init --agent claude-code --dry-run
+skillmux init --agent claude-code --yes
 ```
 
 ### Target points to the full vault
@@ -122,7 +122,7 @@ skillmux init --client claude-code --yes
 Review the smaller pinned set before converting:
 
 ```sh
-skillmux init --client claude-code \
+skillmux init --agent claude-code \
   --migrate-full-vault \
   --core code-context \
   --dry-run
@@ -239,7 +239,7 @@ skillmux --context prod config status
 An MCP token for `/mcp` cannot authenticate this request, and the administrative
 token cannot authenticate an MCP client. A named context administers the
 deployed server configuration only; use Skillmux CLI on the machine that owns
-client directories for `install`, pinning, or `sync`.
+agent directories for `install`, pinning, or `sync`.
 
 ### Client receives `429`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@klhapp/skillmux",
-  "version": "1.9.3",
+  "version": "1.11.0",
   "description": "Skill management and retrieval for AI agents: sync native skills across clients and route the long tail over MCP",
   "type": "module",
   "private": false,

package/src/adapters.ts

@@ -14,8 +14,11 @@ import {
   type ConfigStatusResponse,
   type SetConfigResult,
 } from "./config-service";
-import type { ResolvedTarget } from "./context";
+import type { ResolvedContext } from "./context";
 import type { Clients, Config } from "./types";
+import { getStats, parseSince, type StatsResponse } from "./stats";
+import { countPrunable, openAudit, pruneAuditBefore, type PruneResult } from "./db";
+import { buildPromotedCases, evalVault, queryPromotableFetches, type EvalCase, type EvalReport } from "./eval";
 
 export interface Capabilities {
   config_read: boolean;
@@ -25,13 +28,28 @@ export interface Capabilities {
   restart_required_keys: string[];
 }
 
-export interface TargetAdapterOptions {
+export interface ContextAdapterOptions {
   configPath?: string;
   allowInsecure?: boolean;
   clients?: Clients;
 }
 
-export interface TargetAdapter {
+export interface AuditPruneOptions {
+  older_than?: string;
+  dry_run?: boolean;
+  confirm?: boolean;
+}
+
+export interface AuditPruneResult extends PruneResult {
+  dry_run: boolean;
+  cutoff: string | null;
+}
+
+/**
+ * Context adapter: `local` = this CLI process has the Skillmux runtime (vault, index,
+ * audit db, embeddings/reranker clients) in-process; `remote` = thin network client to an external process.
+ */
+export interface ContextAdapter {
   getCapabilities(): Promise<Capabilities>;
   getConfigShow(): Promise<{ effective: Config; sources: Record<string, string>; active_revision: string }>;
   getConfigGet(key: string): Promise<unknown>;
@@ -39,6 +57,11 @@ export interface TargetAdapter {
   configDiff(): Promise<{ diff: Record<string, { prior: unknown; resulting: unknown }> }>;
   configSet(key: string, rawValStr: string, opts?: { dryRun?: boolean }): Promise<SetConfigResult>;
   configStatus(): Promise<ConfigStatusResponse>;
+  getStats(since: string): Promise<StatsResponse>;
+  auditPrune(opts?: AuditPruneOptions): Promise<AuditPruneResult>;
+  auditCount(older_than?: string): Promise<AuditPruneResult>;
+  evalRun(): Promise<EvalReport>;
+  evalPromote(since: string): Promise<EvalCase[]>;
 }
 
 export function isLoopbackHost(hostname: string): boolean {
@@ -51,11 +74,11 @@ export function isLoopbackHost(hostname: string): boolean {
   );
 }
 
-export class LocalAdapter implements TargetAdapter {
+export class LocalAdapter implements ContextAdapter {
   private configPath: string;
   private clients?: Clients;
 
-  constructor(opts?: TargetAdapterOptions) {
+  constructor(opts?: ContextAdapterOptions) {
     this.configPath = resolveConfigPath(opts?.configPath);
     this.clients = opts?.clients;
   }
@@ -109,21 +132,90 @@ export class LocalAdapter implements TargetAdapter {
     return setDottedKey(key, rawValStr, {
       configPath: this.configPath,
       dryRun: opts?.dryRun,
-      targetName: "local",
+      contextName: "local",
     });
   }
 
   async configStatus(): Promise<ConfigStatusResponse> {
     return getLocalConfigStatus(this.configPath);
   }
+
+  async getStats(since: string): Promise<StatsResponse> {
+    const config = await loadConfig(this.configPath);
+    const stateDir = expandHome(config.state_dir);
+    const db = openAudit(stateDir);
+    try {
+      return getStats(db, since);
+    } finally {
+      db.close();
+    }
+  }
+
+  async auditPrune(opts?: AuditPruneOptions): Promise<AuditPruneResult> {
+    const config = await loadConfig(this.configPath);
+    const stateDir = expandHome(config.state_dir);
+    const olderThan = opts?.older_than;
+    const dryRun = opts?.dry_run ?? false;
+
+    let cutoff: Date;
+    if (olderThan) {
+      cutoff = parseSince(olderThan);
+    } else {
+      const retentionDays = config.audit?.retention_days ?? 90;
+      if (retentionDays <= 0) {
+        return {
+          audit_deleted: 0,
+          fetch_deleted: 0,
+          admin_audit_deleted: 0,
+          dry_run: dryRun,
+          cutoff: null,
+        };
+      }
+      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);
+        return { ...counts, dry_run: true, cutoff: cutoffIso };
+      }
+      const counts = pruneAuditBefore(db, cutoffIso);
+      return { ...counts, dry_run: false, cutoff: cutoffIso };
+    } finally {
+      db.close();
+    }
+  }
+
+  async auditCount(older_than?: string): Promise<AuditPruneResult> {
+    return this.auditPrune({ older_than, dry_run: true });
+  }
+
+  async evalRun(): Promise<EvalReport> {
+    return evalVault();
+  }
+
+  async evalPromote(since: string): Promise<EvalCase[]> {
+    const sinceDate = parseSince(since);
+    const sinceIso = sinceDate.toISOString();
+    const config = await loadConfig(this.configPath);
+    const stateDir = expandHome(config.state_dir);
+    const db = openAudit(stateDir);
+    try {
+      return buildPromotedCases(queryPromotableFetches(db, sinceIso));
+    } finally {
+      db.close();
+    }
+  }
 }
 
-export class RemoteAdapter implements TargetAdapter {
+export class RemoteAdapter implements ContextAdapter {
   private serverUrl: string;
   private tokenEnv?: string;
   private allowInsecure: boolean;
 
-  constructor(target: { server: string; token_env?: string }, opts?: TargetAdapterOptions) {
+  constructor(target: { server: string; token_env?: string }, opts?: ContextAdapterOptions) {
     this.serverUrl = target.server.replace(/\/$/, "");
     this.tokenEnv = target.token_env;
     this.allowInsecure = opts?.allowInsecure ?? false;
@@ -281,12 +373,66 @@ export class RemoteAdapter implements TargetAdapter {
     }
     return data.runtime;
   }
+
+  async getStats(since: string): Promise<StatsResponse> {
+    const searchParams = new URLSearchParams({ since });
+    const { status, data } = await this.fetchJson(`/stats?${searchParams.toString()}`);
+    if (status !== 200) {
+      throw new Error(`Remote stats fetch failed (${status}): ${typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data}`);
+    }
+    return data as StatsResponse;
+  }
+
+  async auditPrune(opts?: AuditPruneOptions): Promise<AuditPruneResult> {
+    const { status, data } = await this.fetchJson("/admin/v1/audit/prune", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ...(opts?.older_than ? { older_than: opts.older_than } : {}),
+        ...(opts?.dry_run !== undefined ? { dry_run: opts.dry_run } : {}),
+        ...(opts?.confirm !== undefined ? { confirm: opts.confirm } : {}),
+      }),
+    });
+    if (status !== 200) {
+      const message = typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data;
+      throw new Error(`Remote audit prune failed (${status}): ${message}`);
+    }
+    return data as AuditPruneResult;
+  }
+
+  async auditCount(older_than?: string): Promise<AuditPruneResult> {
+    return this.auditPrune({ older_than, dry_run: true });
+  }
+
+  async evalRun(): Promise<EvalReport> {
+    const { status, data } = await this.fetchJson("/admin/v1/eval", {
+      method: "POST",
+    });
+    if (status !== 200) {
+      const message = typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data;
+      throw new Error(`Remote eval failed (${status}): ${message}`);
+    }
+    return data as EvalReport;
+  }
+
+  async evalPromote(since: string): Promise<EvalCase[]> {
+    const { status, data } = await this.fetchJson("/admin/v1/eval/promote", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ since }),
+    });
+    if (status !== 200) {
+      const message = typeof data === "object" ? data?.message || data?.error || JSON.stringify(data) : data;
+      throw new Error(`Remote eval promote failed (${status}): ${message}`);
+    }
+    return data.candidates as EvalCase[];
+  }
 }
 
-export function createTargetAdapter(target: ResolvedTarget, opts?: TargetAdapterOptions): TargetAdapter {
-  if (target.type === "local") {
+export function createContextAdapter(context: ResolvedContext, opts?: ContextAdapterOptions): ContextAdapter {
+  if (context.type === "local") {
     return new LocalAdapter(opts);
   } else {
-    return new RemoteAdapter({ server: target.server, token_env: target.token_env }, opts);
+    return new RemoteAdapter({ server: context.server, token_env: context.token_env }, opts);
   }
 }