@klhapp/skillmux 0.6.0 → 1.0.0

package/src/completions.ts

@@ -1,14 +1,37 @@
 export type ShellType = "bash" | "zsh" | "fish";
 
+const TOP_LEVEL_COMMANDS: { name: string; description: string }[] = [
+  { name: "context", description: "Manage connection contexts" },
+  { name: "config", description: "Manage configuration" },
+  { name: "calibrate", description: "Manage policy calibration" },
+  { name: "serve", description: "Start MCP server" },
+  { name: "index", description: "Rebuild local search index" },
+  { name: "sync", description: "Synchronize vault skills" },
+  { name: "init", description: "Configure this machine and its clients" },
+  { name: "project", description: "Configure project-scoped skills" },
+  { name: "target", description: "Manage advanced skill-delivery targets" },
+  { name: "core", description: "Pin/unpin skills into [core]" },
+  { name: "report", description: "Generate usage stats" },
+  { name: "scan", description: "Audit skills for issues" },
+  { name: "install", description: "Install skills into vault" },
+  { name: "eval", description: "Evaluate search accuracy" },
+  { name: "doctor", description: "Check runtime health" },
+  { name: "skill", description: "Show which root resolves a skill_id" },
+  { name: "local-vault", description: "Manage local_vault_paths discoverability markers" },
+  { name: "models", description: "Manage local models" },
+  { name: "completions", description: "Generate shell completions" },
+];
+
 export function generateCompletions(shell: ShellType): string {
   if (shell === "bash") {
+    const opts = [...TOP_LEVEL_COMMANDS.map((c) => c.name), "--context", "--server", "--json", "--allow-insecure", "--verbose", "--dry-run", "--help"].join(" ");
     return `# bash completion for skillmux
 _skillmux_completions() {
     local cur prev opts
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
-    opts="context config calibrate serve index sync init project target report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
+    opts="${opts}"
 
     if [ "$COMP_CWORD" -eq 1 ]; then
         COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
@@ -28,9 +51,12 @@ _skillmux_completions() {
         completions)
             COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
             ;;
-        manifest)
+        core)
             COMPREPLY=( $(compgen -W "pin unpin" -- "$cur") )
             ;;
+        skill)
+            COMPREPLY=( $(compgen -W "which" -- "$cur") )
+            ;;
         project)
             COMPREPLY=( $(compgen -W "init list show add-path remove-path pin unpin attach detach" -- "$cur") )
             ;;
@@ -48,7 +74,7 @@ _skillmux_completions() {
             ;;
     esac
     if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
-        COMPREPLY=( $(compgen -W "--client --target --path --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+        COMPREPLY=( $(compgen -W "--client --target --dir --vault --core --migrate-full-vault --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
     fi
     if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
         COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
@@ -59,62 +85,51 @@ complete -F _skillmux_completions skillmux
   }
 
   if (shell === "zsh") {
+    const commands = TOP_LEVEL_COMMANDS.map((c) => `        '${c.name}:${c.description}'`).join("\n");
     return `#compdef skillmux
 _skillmux() {
     local -a commands
     commands=(
-        'context:Manage connection contexts'
-        'config:Manage configuration'
-        'calibrate:Manage policy calibration'
-        'serve:Start MCP server'
-        'index:Rebuild local search index'
-        'sync:Synchronize vault skills'
-        'init:Initialize project targets'
-        'project:Configure project-scoped skills'
-        'target:Manage advanced skill-delivery targets'
-        'report:Generate usage stats'
-        'scan:Audit skills for issues'
-        'install:Install skills into vault'
-        'eval:Evaluate search accuracy'
-        'doctor:Check runtime health'
-        'which:Show which root resolves a skill_id'
-        'manifest:Pin/unpin skills into [core] or [project.*]'
-        'local-vault:Manage local_vault_paths discoverability markers'
-        'models:Manage local models'
-        'completions:Generate shell completions'
+${commands}
     )
     if (( CURRENT == 2 )); then
         _describe -t commands 'skillmux command' commands
     elif [[ "$words[2]" == "init" ]]; then
-        _arguments \
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \
-          '*--target[select a target]:target:(agent-skills claude-code codex custom)' \
-          '--path[custom target directory]:directory:_directories' \
-          '--vault[vault directory]:directory:_directories' \
-          '*--core[seed a core skill]:skill id:' \
-          '--migrate-full-vault[convert a full-vault symlink to managed pins]' \
-          '--no-instructions[skip managed instruction files]' \
-          '--no-sync[save setup without synchronizing targets]' \
-          '--interactive[force guided setup]' \
-          '--yes[apply without prompts]' \
-          '--dry-run[print the plan without writing]' \
+        _arguments \\
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \\
+          '*--target[select a delivery target]:target:(agent-skills claude-code codex custom)' \\
+          '--dir[custom target directory]:directory:_directories' \\
+          '--vault[vault directory]:directory:_directories' \\
+          '*--core[seed a core skill]:skill id:' \\
+          '--migrate-full-vault[convert a full-vault symlink to managed pins]' \\
+          '--no-instructions[skip managed instruction files]' \\
+          '--no-sync[save setup without synchronizing targets]' \\
+          '--interactive[force guided setup]' \\
+          '--yes[apply without prompts]' \\
+          '--dry-run[print the plan without writing]' \\
           '--json[emit a JSON envelope]'
     elif [[ "$words[2]" == "project" && "$words[3]" == "init" ]]; then
-        _arguments \
-          '1:project directory:_directories' \
-          '--name[project group name]:group:' \
-          '*--skill[project skill]:skill id:' \
-          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \
-          '*--target[select an advanced target]:target:' \
-          '--no-sync[save setup without synchronizing targets]' \
-          '--interactive[force guided setup]' \
-          '--yes[apply without prompts]' \
-          '--dry-run[print the plan without writing]' \
+        _arguments \\
+          '1:project directory:_directories' \\
+          '--name[project group name]:group:' \\
+          '*--skill[project skill]:skill id:' \\
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \\
+          '*--target[select an advanced target]:target:' \\
+          '--no-sync[save setup without synchronizing targets]' \\
+          '--interactive[force guided setup]' \\
+          '--yes[apply without prompts]' \\
+          '--dry-run[print the plan without writing]' \\
           '--json[emit a JSON envelope]'
     elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
         _values 'project command' init list show add-path remove-path pin unpin attach detach
     elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
         _values 'target command' list show add remove
+    elif [[ "$words[2]" == "skill" && CURRENT == 3 ]]; then
+        _values 'skill command' which
+    elif [[ "$words[2]" == "core" && CURRENT == 3 ]]; then
+        _values 'core command' pin unpin
+    elif [[ "$words[2]" == "local-vault" && CURRENT == 3 ]]; then
+        _values 'local-vault command' init
     fi
 }
 _skillmux "$@"
@@ -122,19 +137,15 @@ _skillmux "$@"
   }
 
   if (shell === "fish") {
+    const topLevel = TOP_LEVEL_COMMANDS.map(
+      (c) => `complete -c skillmux -n "__fish_use_subcommand" -a ${c.name} -d "${c.description}"`,
+    ).join("\n");
     return `# fish completion for skillmux
 complete -c skillmux -f
-complete -c skillmux -n "__fish_use_subcommand" -a context -d "Manage connection contexts"
-complete -c skillmux -n "__fish_use_subcommand" -a config -d "Manage configuration"
-complete -c skillmux -n "__fish_use_subcommand" -a calibrate -d "Manage policy calibration"
-complete -c skillmux -n "__fish_use_subcommand" -a serve -d "Start MCP server"
-complete -c skillmux -n "__fish_use_subcommand" -a init -d "Configure this machine and its clients"
-complete -c skillmux -n "__fish_use_subcommand" -a project -d "Configure project-scoped skills"
-complete -c skillmux -n "__fish_use_subcommand" -a target -d "Manage advanced skill-delivery targets"
-complete -c skillmux -n "__fish_use_subcommand" -a completions -d "Generate shell completions"
+${topLevel}
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a target"
-complete -c skillmux -n "__fish_seen_subcommand_from init" -l path -r -d "Custom target directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a delivery target"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l dir -r -d "Custom target directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
 complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
@@ -148,11 +159,14 @@ complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
-complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced delivery target"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
 complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
 complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
+complete -c skillmux -n "__fish_seen_subcommand_from core" -a "pin unpin" -d "Manage [core] pins"
+complete -c skillmux -n "__fish_seen_subcommand_from skill" -a "which" -d "Show which root resolves a skill_id"
+complete -c skillmux -n "__fish_seen_subcommand_from local-vault" -a "init" -d "Initialize a local_vault_paths marker"
 `;
   }
 

package/src/config-watcher.ts

@@ -14,6 +14,7 @@ export const LIVE_RELOAD_KEYS = new Set([
   "inference.thresholds.match_score",
   "inference.thresholds.match_margin",
   "inference.thresholds.candidate_floor",
+  "inference.calibration.run_id",
   "recall.k_lexical",
   "recall.k_vector",
   "thresholds.candidate_limit",
@@ -53,6 +54,47 @@ const DEBOUNCE_MS = 300;
 const STABLE_STAT_INTERVAL_MS = 80;
 const STABLE_STAT_MAX_TRIES = 8;
 
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function changedConfigKeys(
+  previous: Record<string, unknown>,
+  next: Record<string, unknown>,
+  prefix = "",
+): string[] {
+  const changed: string[] = [];
+  const keys = new Set([...Object.keys(previous), ...Object.keys(next)]);
+
+  for (const key of keys) {
+    const path = prefix ? `${prefix}.${key}` : key;
+    const previousValue = previous[key];
+    const nextValue = next[key];
+    if (!(key in previous) || !(key in next)) {
+      if (isRecord(previousValue) || isRecord(nextValue)) {
+        changed.push(
+          ...changedConfigKeys(
+            isRecord(previousValue) ? previousValue : {},
+            isRecord(nextValue) ? nextValue : {},
+            path,
+          ),
+        );
+      } else {
+        changed.push(path);
+      }
+      continue;
+    }
+
+    if (isRecord(previousValue) && isRecord(nextValue)) {
+      changed.push(...changedConfigKeys(previousValue, nextValue, path));
+    } else if (JSON.stringify(previousValue) !== JSON.stringify(nextValue)) {
+      changed.push(path);
+    }
+  }
+
+  return changed;
+}
+
 /**
  * Watch the parent directory of a TOML config file for changes.
  * Parent-dir watching catches both direct writes (change events) and
@@ -79,6 +121,7 @@ export class ConfigWatcher {
   private constructor(
     private readonly tomlPath: string,
     private readonly opts: ConfigWatcherOptions,
+    private activeConfig: Config,
   ) {
     const dir = dirname(tomlPath);
     const filename = tomlPath.split(/[/\\]/).pop()!;
@@ -110,7 +153,8 @@ export class ConfigWatcher {
     tomlPath: string,
     opts: ConfigWatcherOptions,
   ): Promise<ConfigWatcher> {
-    return new ConfigWatcher(tomlPath, opts);
+    const activeConfig = await loadConfig(tomlPath);
+    return new ConfigWatcher(tomlPath, opts, activeConfig);
   }
 
   private scheduleReload(): void {
@@ -130,10 +174,27 @@ export class ConfigWatcher {
 
     try {
       const config = await loadConfig(this.tomlPath);
+      const restartRequiredKeys = changedConfigKeys(
+        this.activeConfig as unknown as Record<string, unknown>,
+        config as unknown as Record<string, unknown>,
+      )
+        .filter((key) => !LIVE_RELOAD_KEYS.has(key))
+        .sort();
+
+      if (restartRequiredKeys.length > 0) {
+        this.status = {
+          ...this.status,
+          last_reload_error: null,
+          restart_required_keys: restartRequiredKeys,
+        };
+        return;
+      }
+
+      this.activeConfig = config;
       this.status = {
         last_successful_reload_at: new Date().toISOString(),
         last_reload_error: null,
-        restart_required_keys: this.status.restart_required_keys,
+        restart_required_keys: [],
       };
       this.opts.onReload(config);
     } catch (err) {

package/src/doctor.ts

@@ -1,7 +1,7 @@
 import { existsSync, mkdirSync } from "node:fs";
 import { createClients } from "./clients";
 import { embeddingDimension, expandHome } from "./config";
-import { resolveManifestPath } from "./manifest";
+import { parseManifest, resolveManifestPath, validateManifest } from "./manifest";
 import { readSkillmuxMarker } from "./sync";
 import type { Config } from "./types";
 import { findShadowedSkills } from "./vault";
@@ -62,6 +62,24 @@ export async function diagnose(config: Config): Promise<DoctorReport> {
     });
   }
 
+  const vaultPath = expandHome(config.vault_path);
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) {
+    checks.push({ name: "manifest", ok: true, detail: "not yet initialized" });
+  } else {
+    try {
+      const manifest = parseManifest(await Bun.file(manifestPath).text());
+      validateManifest(manifest, vaultPath, config.local_vault_paths.map(expandHome));
+      checks.push({ name: "manifest", ok: true, detail: manifestPath });
+    } catch (error) {
+      checks.push({
+        name: `manifest:${manifestPath}`,
+        ok: false,
+        detail: error instanceof Error ? error.message : String(error),
+      });
+    }
+  }
+
   try {
     mkdirSync(expandHome(config.state_dir), { recursive: true });
     const probe = Bun.file(expandHome(`${config.state_dir}/.doctor`));

package/src/output.ts

@@ -36,33 +36,31 @@ export function formatJsonEnvelope<T>(opts: {
   };
 }
 
-export function mapExitCode(err: unknown): number {
-  if (!err) return 0;
-  const msg = err instanceof Error ? err.message : String(err);
-  const lower = msg.toLowerCase();
-
-  if (
-    lower.includes("conflict") ||
-    lower.includes("revision") ||
-    lower.includes("externally managed") ||
-    lower.includes("config_revision_conflict") ||
-    lower.includes("config_externally_managed")
-  ) {
-    return 4;
+export class CliError extends Error {
+  exitCode: number;
+
+  constructor(message: string, exitCode: number) {
+    super(message);
+    this.name = "CliError";
+    this.exitCode = exitCode;
   }
+}
 
-  if (
-    lower.includes("unreachable") ||
-    lower.includes("failed to reach") ||
-    lower.includes("unauthorized") ||
-    lower.includes("unauthenticated") ||
-    lower.includes("401") ||
-    lower.includes("403") ||
-    lower.includes("connection refused")
-  ) {
-    return 3;
+export function emitSuccess<T>(
+  ctx: { isJson: boolean; target?: ResolvedTarget | 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 })));
+  } else {
+    renderText();
   }
+}
 
+export function mapExitCode(err: unknown): number {
+  if (!err) return 0;
+  if (err instanceof CliError) return err.exitCode;
   return 2;
 }