@klhapp/skillmux 1.9.2 → 1.10.0

package/src/commands/install.ts

@@ -0,0 +1,132 @@
+import { rmSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import {
+  assertHostAllowed,
+  cloneToTemp,
+  deriveRepoName,
+  installIntoVault,
+  isLocalFileUrl,
+  resolveCloneCommit,
+  resolveRepoSource,
+  resolveSkillDir,
+  validateSkillCandidate,
+} from "../install";
+import { emitSuccess } from "../output";
+import { hashSkillContent, writeSkillOrigin } from "../provenance";
+import { renderScanText, scanExitCode, type ScanSeverity } from "../scan";
+import { isGlobalFlag } from "../global-flags";
+
+function parseInstallArgs(args: string[]): {
+  repo?: string;
+  force: boolean;
+  dryRun: boolean;
+  failOn?: ScanSeverity;
+  allowLocalSource: boolean;
+} {
+  let repo: string | undefined;
+  let force = false;
+  let dryRun = false;
+  let failOn: ScanSeverity | undefined;
+  let allowLocalSource = false;
+  for (let i = 0; i < args.length; i++) {
+    const option = args[i];
+    if (option === "--force") force = true;
+    else if (option === "--dry-run") dryRun = true;
+    else if (option === "--allow-local-source") allowLocalSource = true;
+    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", "--verbose")) {
+      // handled globally by main()'s isJson/isVerbose flags; recognized here so they aren't rejected
+    } else if (option?.startsWith("--")) {
+      throw new Error(`unknown install option: ${option}`);
+    } else if (repo !== undefined) {
+      throw new Error("skillmux install accepts at most one <repo> argument");
+    } else {
+      repo = option;
+    }
+  }
+  return { repo, force, dryRun, failOn, allowLocalSource };
+}
+
+export async function runInstall(
+  args: string[],
+  options: { isJson: boolean },
+): Promise<void> {
+  const { repo, force, dryRun, failOn, allowLocalSource } = parseInstallArgs(args);
+  if (!repo) {
+    throw new Error(
+      "usage: skillmux install <repo>[/path] [--force] [--fail-on low|medium|high] [--dry-run] [--allow-local-source] [--json]",
+    );
+  }
+
+  const source = resolveRepoSource(repo);
+  if (!allowLocalSource && isLocalFileUrl(source.url)) {
+    throw new Error(
+      `"${repo}" is a local (file://) source — pass --allow-local-source to install from it`,
+    );
+  }
+  const config = await loadConfig();
+  assertHostAllowed(source.url, config.egress?.allowed_hosts);
+  const cloneDir = await cloneToTemp(source.url);
+  try {
+    const resolved = resolveSkillDir(
+      cloneDir,
+      deriveRepoName(source.url),
+      source.skillPath,
+    );
+    const { findings } = await validateSkillCandidate(
+      resolved.skillId,
+      resolved.dir,
+    );
+    if (!options.isJson) console.log(renderScanText({ scanned: 1, findings }));
+
+    if (scanExitCode(findings, failOn) !== 0) {
+      process.exitCode = 1;
+      console.error(
+        `aborting install: a finding met the --fail-on ${failOn} threshold`,
+      );
+      return;
+    }
+
+    const vaultPath = expandHome(config.vault_path);
+    if (dryRun) {
+      const plannedPath = join(vaultPath, resolved.skillId);
+      emitSuccess(
+        { isJson: options.isJson },
+        { skill_id: resolved.skillId, would_install_at: plannedPath },
+        () =>
+          console.log(
+            `dry-run: would install "${resolved.skillId}" into ${plannedPath}`,
+          ),
+      );
+      return;
+    }
+
+    const commit = resolveCloneCommit(cloneDir);
+    const targetDir = installIntoVault(
+      vaultPath,
+      resolved.skillId,
+      resolved.dir,
+      force,
+    );
+    writeSkillOrigin(targetDir, {
+      source_url: source.url,
+      skill_path: source.skillPath,
+      commit,
+      installed_at: new Date().toISOString(),
+      content_hash: hashSkillContent(targetDir),
+    });
+    emitSuccess(
+      { isJson: options.isJson },
+      { skill_id: resolved.skillId, installed_at: targetDir },
+      () => console.log(`installed "${resolved.skillId}" into ${targetDir}`),
+    );
+  } finally {
+    rmSync(cloneDir, { recursive: true, force: true });
+  }
+}

package/src/commands/local-vault.ts

@@ -0,0 +1,60 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import { emitSuccess } from "../output";
+import { writeLocalVaultMarker } from "../sync";
+import { confirmIfNeeded } from "./shared";
+
+export async function runLocalVaultInit(
+  args: string[],
+  options: { isJson: boolean; dryRun: boolean },
+): Promise<void> {
+  const path = args[0];
+  if (!path) throw new Error("usage: skillmux local-vault init <path> --yes");
+  const expanded = expandHome(path);
+  const config = await loadConfig();
+  const localVaultPaths = config.local_vault_paths.map(expandHome);
+  if (!localVaultPaths.includes(expanded)) {
+    throw new Error(
+      `"${path}" is not one of the configured local_vault_paths — add it to config.toml first`,
+    );
+  }
+  if (!existsSync(expanded)) throw new Error(`"${path}" does not exist`);
+  const markerPath = join(expanded, ".skillmux");
+  if (options.dryRun) {
+    emitSuccess(
+      { isJson: options.isJson },
+      {
+        marker_path: markerPath,
+        vault_path: expandHome(config.vault_path),
+      },
+      () =>
+        console.log(
+          `local-vault init: ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)}) (dry-run)`,
+        ),
+    );
+    return;
+  }
+  if (
+    !(await confirmIfNeeded({
+      confirmed: args.includes("--yes"),
+      isJson: options.isJson,
+      prompt: `mark ${expanded} as a local_vault (role: local_vault, vault_path: ${expandHome(config.vault_path)})?`,
+      nonInteractiveError:
+        "skillmux local-vault init requires --yes when run non-interactively",
+    }))
+  )
+    return;
+  writeLocalVaultMarker(expanded, expandHome(config.vault_path));
+  emitSuccess(
+    { isJson: options.isJson },
+    {
+      marker_path: markerPath,
+      vault_path: expandHome(config.vault_path),
+    },
+    () =>
+      console.log(
+        `wrote ${markerPath} (role: local_vault, vault_path: ${expandHome(config.vault_path)})`,
+      ),
+  );
+}

package/src/commands/models.ts

@@ -0,0 +1,10 @@
+import { loadConfig } from "../config";
+import { downloadLocalModels } from "../models";
+import { emitSuccess } from "../output";
+
+export async function runModelDownload(options: { isJson: boolean }): Promise<void> {
+  const cacheDir = await downloadLocalModels(await loadConfig());
+  emitSuccess({ isJson: options.isJson }, { cache_dir: cacheDir }, () =>
+    console.log(`models ready in ${cacheDir}`),
+  );
+}

package/src/commands/outdated.ts

@@ -1,10 +1,11 @@
 import { readdirSync } from "node:fs";
 import { join } from "node:path";
 import { expandHome, loadConfig } from "../config";
-import { isLocalFileUrl, remoteHeadCommit } from "../install";
+import { assertHostAllowed, isLocalFileUrl, remoteHeadCommit } from "../install";
 import { emitSuccess } from "../output";
 import { readSkillOrigin } from "../provenance";
 import { SKILL_ID_PATTERN } from "../vault";
+import { isGlobalFlag } from "../global-flags";
 
 export interface OutdatedCheckResult {
   skill_id: string;
@@ -24,7 +25,7 @@ function vaultSkillIds(vaultPath: string): string[] {
 
 export async function checkOutdated(
   vaultPath: string,
-  options: { allowLocalSource?: boolean } = {},
+  options: { allowLocalSource?: boolean; allowedHosts?: string[] } = {},
 ): Promise<OutdatedCheckResult[]> {
   const results: OutdatedCheckResult[] = [];
   for (const skillId of vaultSkillIds(vaultPath)) {
@@ -64,6 +65,7 @@ export async function checkOutdated(
     let status: OutdatedCheckResult["status"];
     let reason: string | null = null;
     try {
+      assertHostAllowed(origin.source_url, options.allowedHosts);
       remoteCommit = await remoteHeadCommit(origin.source_url);
       status = remoteCommit === origin.commit ? "up_to_date" : "outdated";
     } catch (error) {
@@ -86,7 +88,7 @@ export async function checkOutdated(
 export async function runOutdated(args: string[], options: { isJson: boolean }): Promise<void> {
   let allowLocalSource = false;
   for (const arg of args) {
-    if (arg === "--json") continue;
+    if (isGlobalFlag(arg, "--json")) continue;
     if (arg === "--allow-local-source") {
       allowLocalSource = true;
       continue;
@@ -94,8 +96,9 @@ export async function runOutdated(args: string[], options: { isJson: boolean }):
     throw new Error(`unknown outdated option: ${arg}`);
   }
 
-  const vaultPath = expandHome((await loadConfig()).vault_path);
-  const skills = await checkOutdated(vaultPath, { allowLocalSource });
+  const config = await loadConfig();
+  const vaultPath = expandHome(config.vault_path);
+  const skills = await checkOutdated(vaultPath, { allowLocalSource, allowedHosts: config.egress?.allowed_hosts });
   const checksFailed = skills.filter((s) => s.status === "check_failed").length;
   process.exitCode = checksFailed > 0 ? 1 : 0;
 

package/src/commands/project.ts

@@ -21,6 +21,7 @@ import {
 } from "../prompts";
 import { emitSuccess, isInteractive } from "../output";
 import { confirmAction, confirmIfNeeded, loadManifestContext } from "./shared";
+import { isGlobalFlag } from "../global-flags";
 const PROJECT_INIT_USAGE =
   "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--client <id>...] [--target <name>...] [--yes] [--no-sync]";
 
@@ -89,8 +90,7 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
     } else if (arg === "--no-sync") {
       sync = false;
     } else if (
-      arg === "--dry-run" ||
-      arg === "--json" ||
+      isGlobalFlag(arg, "--dry-run", "--json") ||
       arg === "--interactive"
     ) {
       continue;
@@ -184,7 +184,11 @@ export async function runProject(
       config.local_vault_paths.map(expandHome),
     );
     if (options.dryRun) {
-      console.log(`${subCommand}: [project.${group}] ${projectPath} (dry-run)`);
+      emitSuccess(
+        { isJson: options.isJson },
+        { subcommand: subCommand, group, path: projectPath },
+        () => console.log(`${subCommand}: [project.${group}] ${projectPath} (dry-run)`),
+      );
       return;
     }
     if (
@@ -197,7 +201,11 @@ export async function runProject(
     )
       return;
     writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${projectPath}`);
+    emitSuccess(
+      { isJson: options.isJson },
+      { subcommand: subCommand, group, path: projectPath },
+      () => console.log(`${subCommand}: [project.${group}] ${projectPath}`),
+    );
     return;
   }
   if (subCommand === "pin" || subCommand === "unpin") {
@@ -224,8 +232,13 @@ export async function runProject(
       config.local_vault_paths.map(expandHome),
     );
     if (options.dryRun) {
-      console.log(
-        `${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`,
+      emitSuccess(
+        { isJson: options.isJson },
+        { subcommand: subCommand, group, skill_ids: skills },
+        () =>
+          console.log(
+            `${subCommand}: [project.${group}] ${skills.join(", ")} (dry-run)`,
+          ),
       );
       return;
     }
@@ -239,7 +252,11 @@ export async function runProject(
     )
       return;
     writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${skills.join(", ")}`);
+    emitSuccess(
+      { isJson: options.isJson },
+      { subcommand: subCommand, group, skill_ids: skills },
+      () => console.log(`${subCommand}: [project.${group}] ${skills.join(", ")}`),
+    );
     return;
   }
   if (subCommand === "attach" || subCommand === "detach") {
@@ -283,8 +300,13 @@ export async function runProject(
       config.local_vault_paths.map(expandHome),
     );
     if (options.dryRun) {
-      console.log(
-        `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
+      emitSuccess(
+        { isJson: options.isJson },
+        { subcommand: subCommand, group, targets },
+        () =>
+          console.log(
+            `${subCommand}: [project.${group}] ${targets.join(", ")} (dry-run)`,
+          ),
       );
       return;
     }
@@ -298,7 +320,11 @@ export async function runProject(
     )
       return;
     writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`);
+    emitSuccess(
+      { isJson: options.isJson },
+      { subcommand: subCommand, group, targets },
+      () => console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`),
+    );
     return;
   }
   if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
@@ -381,7 +407,7 @@ export async function runProject(
       }
       if (
         !(await confirmAction(
-          `Apply project setup for ${request.name} at ${request.path}?`,
+          `apply project setup for ${request.name} at ${request.path}?`,
         ))
       ) {
         console.log("project setup cancelled");

package/src/commands/report.ts

@@ -0,0 +1,66 @@
+import { Database } from "bun:sqlite";
+import type { TargetAdapter } 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; target: ResolvedContext; allowInsecure: boolean; adapter: TargetAdapter },
+): 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.target.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/skill.ts

@@ -0,0 +1,32 @@
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { expandHome, loadConfig } from "../config";
+import { vaultResolutionOrder } from "../vault";
+
+export async function runSkill(subCommand: string, args: string[]): Promise<void> {
+  if (subCommand !== "which") throw new Error("usage: skillmux skill <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}`);
+}