@klhapp/skillmux 1.9.3 → 1.11.0

package/src/commands/report.ts

@@ -0,0 +1,66 @@
+import { Database } from "bun:sqlite";
+import type { ContextAdapter } from "../adapters";
+import type { ResolvedContext } from "../context";
+import { emitSuccess } from "../output";
+import { getStats, renderStatsText } from "../stats";
+import { isGlobalFlag, isGlobalFlagWithValue } from "../global-flags";
+
+function parseReportArgs(args: string[]): {
+  db?: string;
+  since?: string;
+} {
+  let db: string | undefined;
+  let since: string | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const option = args[i];
+    const value = args[i + 1];
+    if (option === "--db") {
+      if (!value) throw new Error("--db requires a path");
+      db = value;
+      i++;
+    } else if (option === "--since") {
+      if (!value) throw new Error("--since requires a window");
+      since = value;
+      i++;
+    } else if (isGlobalFlag(option, "--json", "--allow-insecure")) {
+      // handled globally by main()'s isJson/allowInsecure flags; recognized here so it isn't rejected
+    } else if (isGlobalFlagWithValue(option)) {
+      // handled globally by main()'s resolveContext(); recognized here so it isn't rejected
+      i++;
+    } else {
+      throw new Error(`unknown report option: ${option}`);
+    }
+  }
+  return { db, since };
+}
+
+export async function runReport(
+  args: string[],
+  options: { isJson: boolean; context: ResolvedContext; allowInsecure: boolean; adapter: ContextAdapter },
+): Promise<void> {
+  const { db: dbPath, since } = parseReportArgs(args);
+  if (!since)
+    throw new Error(
+      "usage: skillmux report [--context <name> | --server <url> | --db <path>] --since <window> [--json]",
+    );
+  if (dbPath && options.context.type === "remote")
+    throw new Error("--db and --context/--server are mutually exclusive");
+
+  if (dbPath) {
+    const db = new Database(dbPath, { readonly: true });
+    try {
+      const stats = getStats(db, since);
+      emitSuccess({ isJson: options.isJson }, stats, () =>
+        console.log(renderStatsText(stats)),
+      );
+    } finally {
+      db.close();
+    }
+    return;
+  }
+
+  const stats = await options.adapter.getStats(since);
+  emitSuccess({ isJson: options.isJson }, stats, () =>
+    console.log(renderStatsText(stats)),
+  );
+}

package/src/commands/scan.ts

@@ -0,0 +1,61 @@
+import { expandHome, loadConfig } from "../config";
+import { emitSuccess } from "../output";
+import {
+  renderScanJson,
+  renderScanText,
+  scanExitCode,
+  scanPath,
+  type ScanSeverity,
+} from "../scan";
+import { isGlobalFlag } from "../global-flags";
+
+function parseScanArgs(args: string[]): {
+  path?: string;
+  format: "text" | "json";
+  failOn?: ScanSeverity;
+} {
+  let path: string | undefined;
+  let format: "text" | "json" = "text";
+  let failOn: ScanSeverity | undefined;
+  for (let i = 0; i < args.length; i++) {
+    const option = args[i];
+    if (option === "--format") {
+      const value = args[++i];
+      if (value !== "text" && value !== "json")
+        throw new Error("--format must be text or json");
+      format = value;
+    } else if (option === "--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 (isGlobalFlag(option, "--json")) {
+      // handled globally by main()'s isJson flag; recognized here so it isn't rejected
+    } else if (option?.startsWith("--")) {
+      throw new Error(`unknown scan option: ${option}`);
+    } else if (path !== undefined) {
+      throw new Error("skillmux scan accepts at most one <path> argument");
+    } else {
+      path = option;
+    }
+  }
+  return { path, format, failOn };
+}
+
+export async function runScan(
+  args: string[],
+  options: { isJson: boolean },
+): Promise<void> {
+  const { path, format, failOn } = parseScanArgs(args);
+  const rootPath = path
+    ? expandHome(path)
+    : expandHome((await loadConfig()).vault_path);
+  const result = await scanPath(rootPath);
+  emitSuccess({ isJson: options.isJson }, result, () => {
+    console.log(
+      format === "json" ? renderScanJson(result) : renderScanText(result),
+    );
+  });
+  process.exitCode = scanExitCode(result.findings, failOn);
+}

package/src/commands/shared.ts

@@ -1,21 +1,14 @@
-import { createInterface } from "node:readline/promises";
 import { expandHome, loadConfig } from "../config";
 import { parseManifest, resolveManifestPath } from "../manifest";
 import { isInteractive } from "../output";
+import { askQuestion, type PromptIO } from "../prompts";
 
-export async function confirmAction(prompt: string): Promise<boolean> {
-  const readline = createInterface({
-    input: process.stdin,
-    output: process.stdout,
-  });
-  try {
-    const answer = (await readline.question(`${prompt} [y/N] `))
-      .trim()
-      .toLowerCase();
-    return answer === "y" || answer === "yes";
-  } finally {
-    readline.close();
-  }
+export async function confirmAction(
+  prompt: string,
+  io: PromptIO = {},
+): Promise<boolean> {
+  const answer = (await askQuestion(`${prompt} [y/N] `, io)).trim().toLowerCase();
+  return answer === "y" || answer === "yes";
 }
 
 export async function loadManifestContext() {

package/src/commands/skill.ts

@@ -0,0 +1,33 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import { unknownSubcommandError } from "../output";
+import { vaultResolutionOrder } from "../vault";
+
+export async function runSkill(subCommand: string, args: string[]): Promise<void> {
+  if (subCommand !== "which") throw unknownSubcommandError("skill", subCommand, ["which"]);
+  await runWhich(args);
+}
+
+async function runWhich(args: string[]): Promise<void> {
+  const skillId = args[0];
+  if (!skillId) {
+    throw new Error(
+      "usage: skillmux skill which <skill_id> (local vault shadow resolution; unrelated to MCP routing)",
+    );
+  }
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const roots = vaultResolutionOrder(vaultPath, localVaultPaths).filter(
+    (root) => existsSync(join(root, skillId, "SKILL.md")),
+  );
+  if (roots.length === 0) {
+    console.log(`${skillId}: not found in vault_path or local_vault_paths`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`${skillId}: serving from ${roots[0]}`);
+  for (const shadowedRoot of roots.slice(1))
+    console.log(`  shadows: ${shadowedRoot}`);
+}

package/src/commands/sync.ts

@@ -0,0 +1,232 @@
+import { existsSync } from "node:fs";
+import { hostname } from "node:os";
+import { expandHome, loadConfig } from "../config";
+import {
+  parseManifest,
+  resolveManifestPath,
+  validateManifest,
+} from "../manifest";
+import { emitSuccess, isInteractive, warn } from "../output";
+import {
+  installPostMergeHook,
+  resolveProjectPinDir,
+  restoreMonolith as restoreMonolithTarget,
+  syncProjectTargets,
+  syncTarget,
+  type ProjectGroupInput,
+} from "../sync";
+import { confirmAction } from "./shared";
+
+function parseSyncArgs(args: string[]): {
+  dryRun: boolean;
+  restoreMonolith: boolean;
+  installHook: boolean;
+  yes: boolean;
+  isJson: boolean;
+} {
+  let dryRun = false;
+  let restoreMonolith = false;
+  let installHook = false;
+  let yes = false;
+  let isJson = false;
+  for (const arg of args) {
+    if (arg === "--dry-run") dryRun = true;
+    else if (arg === "--restore-monolith") restoreMonolith = true;
+    else if (arg === "--install-hook") installHook = true;
+    else if (arg === "--yes") yes = true;
+    else if (arg === "--json") isJson = true;
+    else throw new Error(`unknown sync option: ${arg}`);
+  }
+  return { dryRun, restoreMonolith, installHook, yes, isJson };
+}
+
+/**
+ * A target directory that doesn't exist yet is about to be created by `sync`.
+ * `manifest.targets[*].dir` is vault content — readable and writable by whatever
+ * populated the vault (a shared git-backed vault pulled in, or a hand-edit) — and
+ * `sync` can run unattended via the `--install-hook` post-merge hook. Without this
+ * gate, a tampered manifest naming a brand-new path gets that directory silently
+ * created (and populated with symlinks) the next time anyone pulls. Creation for
+ * an as-yet-unseen directory therefore requires either `--yes` or an interactive
+ * confirmation; once the directory exists, later syncs never hit this path again.
+ */
+async function confirmNewSyncTarget(
+  label: string,
+  dir: string,
+  yes: boolean,
+  isJson: boolean,
+): Promise<boolean> {
+  if (yes) return true;
+  if (!isInteractive()) {
+    if (!isJson) {
+      console.log(
+        `${label}: skipped — ${dir} does not exist yet; creating it requires approval. Re-run "skillmux sync --yes", or run "skillmux sync" interactively, once you've confirmed this target is expected.`,
+      );
+    }
+    return false;
+  }
+  return confirmAction(`${label}: create new target directory ${dir}?`);
+}
+
+interface SyncTargetSummary {
+  target: string;
+  status:
+    | "synced"
+    | "skipped_host_mismatch"
+    | "restored"
+    | "not_owned"
+    | "skipped_not_approved";
+  added?: string[];
+  removed?: string[];
+  skipped?: string[];
+  projects?: {
+    group: string;
+    pin_dir: string;
+    added: string[];
+    removed: string[];
+    skipped: string[];
+  }[];
+}
+
+export async function runSync(args: string[]): Promise<void> {
+  const { dryRun, restoreMonolith, installHook, yes, isJson } = parseSyncArgs(args);
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const log = (line: string) => {
+    if (!isJson) console.log(line);
+  };
+  const warnLine = (line: string) => {
+    if (!isJson) warn(line);
+  };
+
+  let hookInstalled: boolean | undefined;
+  if (installHook) {
+    const result = installPostMergeHook(vaultPath);
+    hookInstalled = result.installed;
+    log(result.installed ? "installed post-merge hook" : "post-merge hook already installed");
+  }
+
+  const manifestPath = resolveManifestPath(vaultPath);
+  if (!manifestPath) {
+    emitSuccess({ isJson }, { hook_installed: hookInstalled ?? null, targets: [] }, () =>
+      console.log("no skillmux.toml found at vault root — nothing to sync"),
+    );
+    return;
+  }
+
+  const manifest = parseManifest(await Bun.file(manifestPath).text());
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  const { notes } = validateManifest(manifest, vaultPath, localVaultPaths);
+  for (const note of notes) log(`note: ${note}`);
+
+  const currentHost = hostname();
+  const targetSummaries: SyncTargetSummary[] = [];
+  for (const [targetName, target] of Object.entries(manifest.targets)) {
+    if (target.host !== undefined && target.host !== currentHost) {
+      log(
+        `${targetName}: skipped (host ${target.host} does not match current host ${currentHost})`,
+      );
+      targetSummaries.push({ target: targetName, status: "skipped_host_mismatch" });
+      continue;
+    }
+    const targetDir = expandHome(target.dir);
+
+    if (restoreMonolith) {
+      const result = restoreMonolithTarget(targetDir, vaultPath);
+      log(
+        result.restored
+          ? `${targetName}: restored to a vault symlink`
+          : `${targetName}: not owned by skillmux, left untouched`,
+      );
+      targetSummaries.push({
+        target: targetName,
+        status: result.restored ? "restored" : "not_owned",
+      });
+      continue;
+    }
+
+    if (!dryRun && !existsSync(targetDir)) {
+      const approved = await confirmNewSyncTarget(targetName, targetDir, yes, isJson);
+      if (!approved) {
+        if (isInteractive()) {
+          log(`${targetName}: skipped — creating ${targetDir} was not approved`);
+        }
+        targetSummaries.push({ target: targetName, status: "skipped_not_approved" });
+        continue;
+      }
+    }
+
+    const suffix = dryRun ? " (dry-run)" : "";
+    const result = syncTarget(
+      {
+        vaultPath,
+        targetDir,
+        targetName,
+        coreSkillIds: manifest.core.skills,
+        localVaultPaths,
+      },
+      { dryRun },
+    );
+    log(`${targetName}: +${result.added.length} -${result.removed.length}${suffix}`);
+    if (result.skipped.length > 0) {
+      warnLine(`refused to sync ${result.skipped.join(", ")} — skill directory contains a symlink`);
+    }
+    const summary: SyncTargetSummary = {
+      target: targetName,
+      status: "synced",
+      added: result.added,
+      removed: result.removed,
+      skipped: result.skipped,
+    };
+
+    if (target.project_groups.length > 0) {
+      const allGroups = manifest.project ?? {};
+      const projectGroups: Record<string, ProjectGroupInput> = {};
+      for (const groupName of target.project_groups) {
+        const group = allGroups[groupName]!;
+        const approvedPaths: string[] = [];
+        for (const path of group.paths) {
+          // Mirror syncProjectTargets' own `if (!existsSync(path)) continue` so we
+          // never prompt for a project path it would silently skip anyway.
+          if (!existsSync(path)) continue;
+          const pinDir = resolveProjectPinDir(targetDir, path);
+          if (dryRun || existsSync(pinDir)) {
+            approvedPaths.push(path);
+            continue;
+          }
+          const approved = await confirmNewSyncTarget(`${targetName}/${groupName}`, pinDir, yes, isJson);
+          if (approved) approvedPaths.push(path);
+        }
+        projectGroups[groupName] = { ...group, paths: approvedPaths };
+      }
+      const projectResults = syncProjectTargets(
+        { vaultPath, targetDir, targetName, projectGroups, localVaultPaths },
+        { dryRun },
+      );
+      summary.projects = projectResults.map((projectResult) => ({
+        group: projectResult.group,
+        pin_dir: projectResult.pinDir,
+        added: projectResult.added,
+        removed: projectResult.removed,
+        skipped: projectResult.skipped,
+      }));
+      for (const projectResult of projectResults) {
+        log(
+          `  ${projectResult.group} -> ${projectResult.pinDir}: +${projectResult.added.length} -${projectResult.removed.length}${suffix}`,
+        );
+        if (projectResult.skipped.length > 0) {
+          warnLine(
+            `refused to sync ${projectResult.skipped.join(", ")} — skill directory contains a symlink`,
+          );
+        }
+      }
+    }
+    targetSummaries.push(summary);
+  }
+
+  emitSuccess(
+    { isJson },
+    { hook_installed: hookInstalled ?? null, notes, targets: targetSummaries },
+    () => {},
+  );
+}

package/src/commands/target.ts

@@ -1,9 +1,15 @@
 import { expandHome } from "../config";
-import { planClientSurfaces, SUPPORTED_CLIENT_IDS } from "../init-clients";
+import {
+  BUILT_IN_TARGET_NAMES,
+  planAgentSurfaces,
+  resolveBuiltInTarget,
+  SUPPORTED_AGENT_IDS,
+} from "../init-agents";
 import { planInitManifest, applyInit } from "../init";
 import { writeManifestAtomic } from "../manifest";
-import { emitSuccess } from "../output";
+import { emitSuccess, unknownSubcommandError } from "../output";
 import { confirmIfNeeded, loadManifestContext } from "./shared";
+
 export async function runTarget(
   subCommand: string,
   args: string[],
@@ -19,11 +25,11 @@ export async function runTarget(
     }
     const targets = names.map((name) => {
       const target = manifest.targets[name]!;
-      const clients = SUPPORTED_CLIENT_IDS.filter((client) => {
-        const surface = planClientSurfaces([client]).surfaces[0];
+      const agents = SUPPORTED_AGENT_IDS.filter((agent) => {
+        const surface = planAgentSurfaces([agent]).surfaces[0];
         return surface !== undefined && surface.path === expandHome(target.dir);
       });
-      return { name, ...target, clients };
+      return { name, ...target, agents };
     });
     emitSuccess({ isJson: options.isJson }, { targets }, () => {
       if (targets.length === 0) {
@@ -33,7 +39,7 @@ export async function runTarget(
           console.log(`${target.name}:`);
           console.log(`  dir: ${target.dir}`);
           console.log(`  host: ${target.host ?? "(global)"}`);
-          console.log(`  clients: ${target.clients.join(", ") || "(custom)"}`);
+          console.log(`  agents: ${target.agents.join(", ") || "(custom)"}`);
           console.log(
             `  projects: ${target.project_groups.join(", ") || "(none)"}`,
           );
@@ -47,9 +53,21 @@ export async function runTarget(
     const name = args[0];
     const dirIndex = args.indexOf("--dir");
     const rawPath = dirIndex === -1 ? undefined : args[dirIndex + 1];
-    if (!name || !rawPath)
+    if (!name)
       throw new Error("usage: skillmux target add <name> --dir <dir> --yes");
-    const path = expandHome(rawPath);
+
+    let path: string;
+    if (rawPath) {
+      path = expandHome(rawPath);
+    } else if (BUILT_IN_TARGET_NAMES.has(name)) {
+      path = resolveBuiltInTarget(name, {
+        codexHome: process.env.CODEX_HOME ? expandHome(process.env.CODEX_HOME) : undefined,
+      }).path;
+    } else {
+      throw new Error(
+        "usage: skillmux target add <name> --dir <dir> --yes  (--dir may be omitted for built-in target names: agent-skills, claude-code, codex)",
+      );
+    }
     if (options.dryRun) {
       const planned = planInitManifest(vaultPath, [{ name, dir: path }], []);
       emitSuccess(
@@ -63,14 +81,16 @@ export async function runTarget(
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `Adopt target ${name} at ${path}?`,
+        prompt: `adopt target ${name} at ${path}?`,
         nonInteractiveError:
           "skillmux target add requires --yes when run non-interactively",
       }))
     )
       return;
     applyInit(vaultPath, [{ name, dir: path }]);
-    console.log(`target "${name}" added at ${path}`);
+    emitSuccess({ isJson: options.isJson }, { name, dir: path }, () =>
+      console.log(`target "${name}" added at ${path}`),
+    );
     return;
   }
 
@@ -84,27 +104,37 @@ export async function runTarget(
       );
     }
     if (options.dryRun) {
-      console.log(`target remove: ${name} (files preserved, dry-run)`);
+      emitSuccess(
+        { isJson: options.isJson },
+        { name, preserved_dir: manifest.targets[name]!.dir },
+        () => console.log(`target remove: ${name} (files preserved, dry-run)`),
+      );
       return;
     }
     if (
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `Remove target ${name} from the manifest and preserve its files?`,
+        prompt: `remove target ${name} from the manifest and preserve its files?`,
         nonInteractiveError:
           "skillmux target remove requires --yes when run non-interactively",
       }))
     )
       return;
     const targets = { ...manifest.targets };
+    const removedDir = manifest.targets[name]!.dir;
     delete targets[name];
     writeManifestAtomic(manifestPath, { ...manifest, targets });
-    console.log(
-      `target "${name}" removed from the manifest; files preserved at ${manifest.targets[name]!.dir}`,
+    emitSuccess(
+      { isJson: options.isJson },
+      { name, preserved_dir: removedDir },
+      () =>
+        console.log(
+          `target "${name}" removed from the manifest; files preserved at ${removedDir}`,
+        ),
     );
     return;
   }
 
-  throw new Error("usage: skillmux target <list|show|add|remove>");
+  throw unknownSubcommandError("target", subCommand, ["list", "show", "add", "remove"]);
 }

package/src/commands/update.ts

@@ -18,6 +18,7 @@ import { type ScanFinding, type ScanSeverity, scanExitCode } from "../scan";
 import { SKILL_ID_PATTERN } from "../vault";
 import { confirmIfNeeded } from "./shared";
 import { checkOutdated } from "./outdated";
+import { isGlobalFlag } from "../global-flags";
 
 type UpdateKind = "update" | "up_to_date" | "skip_drift" | "skip_scan_failed" | "skip_read_error";
 
@@ -195,7 +196,7 @@ function parseUpdateArgs(args: string[]): {
         throw new Error("--fail-on must be low, medium, or high");
       }
       failOn = value;
-    } else if (arg === "--json") {
+    } else if (isGlobalFlag(arg, "--json")) {
       // handled globally
     } else if (arg?.startsWith("--")) {
       throw new Error(`unknown update option: ${arg}`);