@klhapp/skillmux 1.9.3 → 1.11.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

@@ -5,6 +5,7 @@ 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;
@@ -87,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;

package/src/commands/project.ts

@@ -1,7 +1,11 @@
 import { existsSync, lstatSync } from "node:fs";
 import { basename } from "node:path";
 import { expandHome } from "../config";
-import { planClientSurfaces, SUPPORTED_CLIENT_IDS } from "../init-clients";
+import { planAgentSurfaces, SUPPORTED_AGENT_IDS, type AgentId } from "../init-agents";
+import {
+  applyInstructionPlan,
+  planProjectInstructionSetup,
+} from "../init-instructions";
 import {
   parseManifest,
   pinProject,
@@ -12,6 +16,11 @@ import {
   validateManifest,
   writeManifestAtomic,
 } from "../manifest";
+import {
+  MCP_PROJECT_REGISTRABLE_AGENTS,
+  registerMcpServer,
+  type McpRegistrationResult,
+} from "../mcp-registration";
 import { resolveProjectDirectory, suggestProjectName } from "../project-setup";
 import {
   parseCommaList,
@@ -19,17 +28,19 @@ import {
   promptText,
   shouldUseWizard,
 } from "../prompts";
-import { emitSuccess, isInteractive } from "../output";
+import { emitSuccess, isInteractive, unknownSubcommandError } 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]";
+  "usage: skillmux project init [path] [--name <group>] [--skill <id>...] [--agent <id>...] [--target <name>...] [--register-mcp] [--yes] [--no-sync]";
 
 interface ProjectInitArgs {
   path: string;
   name: string;
   skills: string[];
-  clients: string[];
+  agents: string[];
   targets: string[];
+  registerMcp: boolean;
   yes: boolean;
   sync: boolean;
 }
@@ -44,16 +55,16 @@ export function configuredTargetForSurface(
   )?.[0];
 }
 
-function configuredTargetsForClients(
+function configuredTargetsForAgents(
   manifest: ReturnType<typeof parseManifest>,
-  clients: readonly string[],
+  agents: readonly string[],
 ): string[] {
-  return planClientSurfaces(clients).surfaces.map((surface) => {
+  return planAgentSurfaces(agents).surfaces.map((surface) => {
     const target = configuredTargetForSurface(manifest, surface);
     if (target) return target;
-    const client = surface.clients[0]!;
+    const agent = surface.agents[0]!;
     throw new Error(
-      `client target for "${client}" is not configured; run "skillmux init --client ${client} --yes" first`,
+      `agent target for "${agent}" is not configured; run "skillmux init --agent ${agent} --yes" first`,
     );
   });
 }
@@ -62,8 +73,9 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
   let projectPath: string | undefined;
   let name: string | undefined;
   const skills: string[] = [];
-  const clients: string[] = [];
+  const agents: string[] = [];
   const targets: string[] = [];
+  let registerMcp = false;
   let yes = false;
   let sync = true;
 
@@ -80,17 +92,18 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
       const target = args[++i];
       if (!target) throw new Error("--target requires a name");
       targets.push(target);
-    } else if (arg === "--client") {
-      const client = args[++i];
-      if (!client) throw new Error("--client requires a name");
-      clients.push(client);
+    } else if (arg === "--agent") {
+      const agent = args[++i];
+      if (!agent) throw new Error("--agent requires a name");
+      agents.push(agent);
+    } else if (arg === "--register-mcp") {
+      registerMcp = true;
     } else if (arg === "--yes") {
       yes = true;
     } else if (arg === "--no-sync") {
       sync = false;
     } else if (
-      arg === "--dry-run" ||
-      arg === "--json" ||
+      isGlobalFlag(arg, "--dry-run", "--json") ||
       arg === "--interactive"
     ) {
       continue;
@@ -110,8 +123,9 @@ function parseProjectInitArgs(args: string[]): ProjectInitArgs {
     path,
     name: name ?? suggestProjectName(basename(path)),
     skills,
-    clients,
+    agents,
     targets,
+    registerMcp,
     yes,
     sync,
   };
@@ -184,7 +198,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 +215,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 +246,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,22 +266,26 @@ 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") {
     const group = args[0];
     if (!group)
       throw new Error(
-        `usage: skillmux project ${subCommand} <group> (--client <id>... | --target <name>...) --yes`,
+        `usage: skillmux project ${subCommand} <group> (--agent <id>... | --target <name>...) --yes`,
       );
-    const clients: string[] = [];
+    const agents: string[] = [];
     const requestedTargets: string[] = [];
     for (let i = 1; i < args.length; i++) {
-      if (args[i] === "--client") {
+      if (args[i] === "--agent") {
         const value = args[++i];
-        if (!value) throw new Error("--client requires a name");
-        clients.push(value);
+        if (!value) throw new Error("--agent requires a name");
+        agents.push(value);
       } else if (args[i] === "--target") {
         const value = args[++i];
         if (!value) throw new Error("--target requires a name");
@@ -269,11 +300,20 @@ export async function runProject(
     }
     const { config, vaultPath, manifestPath, manifest } =
       await loadManifestContext();
-    const clientTargets = configuredTargetsForClients(manifest, clients);
-    const targets = [...new Set([...requestedTargets, ...clientTargets])];
+    const agentTargets = configuredTargetsForAgents(manifest, agents);
+    const targets = [...new Set([...requestedTargets, ...agentTargets])];
     if (targets.length === 0) {
-      throw new Error(`project ${subCommand} requires --client or --target`);
+      throw new Error(`project ${subCommand} requires --agent or --target`);
     }
+    // Several agents can share one target (e.g. opencode/windsurf both use
+    // agent-skills) — show the resolved directory, not just the target name,
+    // so it's clear at confirmation time which physical folder this affects.
+    const targetDirs = Object.fromEntries(
+      targets.map((t) => [t, manifest.targets[t]?.dir ?? "(unknown)"]),
+    );
+    const targetsDisplay = targets
+      .map((t) => `${t} (${targetDirs[t]})`)
+      .join(", ");
     const updated = updateProjectTargets(manifest, group, {
       ...(subCommand === "attach" ? { attach: targets } : { detach: targets }),
     });
@@ -283,8 +323,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, target_dirs: targetDirs },
+        () =>
+          console.log(
+            `${subCommand}: [project.${group}] ${targetsDisplay} (dry-run)`,
+          ),
       );
       return;
     }
@@ -292,16 +337,31 @@ export async function runProject(
       !(await confirmIfNeeded({
         confirmed: args.includes("--yes"),
         isJson: options.isJson,
-        prompt: `${subCommand} [project.${group}] to ${targets.join(", ")}?`,
+        prompt: `${subCommand} [project.${group}] to ${targetsDisplay}?`,
         nonInteractiveError: `skillmux project ${subCommand} requires --yes when run non-interactively`,
       }))
     )
       return;
     writeManifestAtomic(manifestPath, updated);
-    console.log(`${subCommand}: [project.${group}] ${targets.join(", ")}`);
+    emitSuccess(
+      { isJson: options.isJson },
+      { subcommand: subCommand, group, targets, target_dirs: targetDirs },
+      () => console.log(`${subCommand}: [project.${group}] ${targetsDisplay}`),
+    );
     return;
   }
-  if (subCommand !== "init") throw new Error(PROJECT_INIT_USAGE);
+  if (subCommand !== "init")
+    throw unknownSubcommandError("project", subCommand, [
+      "init",
+      "list",
+      "show",
+      "add-path",
+      "remove-path",
+      "pin",
+      "unpin",
+      "attach",
+      "detach",
+    ]);
   let request = parseProjectInitArgs(args);
   const guided = shouldUseWizard(args, {
     interactive: isInteractive(),
@@ -319,20 +379,20 @@ export async function runProject(
   const localVaultPaths = config.local_vault_paths.map(expandHome);
   if (guided) {
     const name = await promptText("Project group", request.name);
-    const availableClients = SUPPORTED_CLIENT_IDS.filter((client) => {
-      const surface = planClientSurfaces([client]).surfaces[0];
+    const availableAgents = SUPPORTED_AGENT_IDS.filter((agent) => {
+      const surface = planAgentSurfaces([agent]).surfaces[0];
       return (
         surface !== undefined &&
         configuredTargetForSurface(manifest, surface) !== undefined
       );
     });
-    const clients = await promptMultiSelect(
-      "Which clients should receive project skills?",
-      availableClients.map((client) => ({
-        value: client,
-        label: client,
+    const agents = await promptMultiSelect(
+      "Which agents should receive project skills?",
+      availableAgents.map((agent) => ({
+        value: agent,
+        label: agent,
         selected:
-          request.clients.length === 0 || request.clients.includes(client),
+          request.agents.length === 0 || request.agents.includes(agent),
       })),
     );
     const skills = parseCommaList(
@@ -341,10 +401,25 @@ export async function runProject(
         request.skills.join(","),
       ),
     );
-    request = { ...request, name, clients, skills };
+    request = { ...request, name, agents, skills };
   }
-  const clientTargets = configuredTargetsForClients(manifest, request.clients);
-  const targets = [...new Set([...request.targets, ...clientTargets])];
+  // Local MCP registration + instruction writing are independent of skill
+  // pins — only offered for agents with a verified project-scoped CLI
+  // command (currently just claude-code; see MCP_PROJECT_REGISTRABLE_AGENTS).
+  const registrableAgents = request.agents.filter((agent) =>
+    MCP_PROJECT_REGISTRABLE_AGENTS.includes(agent as AgentId),
+  ) as AgentId[];
+  if (guided && registrableAgents.length > 0) {
+    request = {
+      ...request,
+      registerMcp: await confirmAction(
+        `Also register skillmux as a project-scoped MCP server for ${registrableAgents.join(", ")}? ` +
+          `This writes ${request.path}/.mcp.json, shared via git.`,
+      ),
+    };
+  }
+  const agentTargets = configuredTargetsForAgents(manifest, request.agents);
+  const targets = [...new Set([...request.targets, ...agentTargets])];
   const updated = upsertProject(manifest, {
     name: request.name,
     paths: [request.path],
@@ -352,15 +427,34 @@ export async function runProject(
     targets,
   });
   const { notes } = validateManifest(updated, vaultPath, localVaultPaths);
+
+  // The project-local instruction block only teaches an agent to call
+  // resolve_skill/fetch_skill (MCP tools) — write it only for agents that
+  // are actually getting a project-scoped MCP registration this run.
+  const mcpInstructionAgents = request.registerMcp ? registrableAgents : [];
+  const instructionPlan = planProjectInstructionSetup(
+    mcpInstructionAgents,
+    request.path,
+  );
+  const hasInstructionWrites = instructionPlan.changes.some(
+    (change) => change.status !== "unchanged",
+  );
+
   const plan = {
     mode: "project",
     project: request.name,
     path: request.path,
     skills: request.skills,
-    clients: request.clients,
+    agents: request.agents,
     targets,
     sync: request.sync,
     notes,
+    instructions: instructionPlan.changes.map(({ path, agents, status }) => ({
+      path,
+      agents,
+      status,
+    })),
+    register_mcp_for: mcpInstructionAgents,
   };
 
   if (options.dryRun) {
@@ -375,13 +469,19 @@ export async function runProject(
         console.log("\nReview");
         console.log(`  project: ${request.name}`);
         console.log(`  path: ${request.path}`);
-        console.log(`  clients: ${request.clients.join(", ") || "(none)"}`);
+        console.log(`  agents: ${request.agents.join(", ") || "(none)"}`);
         console.log(`  skills: ${request.skills.join(", ") || "(none)"}`);
+        console.log(
+          `  instructions: ${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} file(s)`,
+        );
+        console.log(
+          `  MCP registration: ${mcpInstructionAgents.join(", ") || "(none)"}`,
+        );
         console.log(`  sync: ${request.sync ? "yes" : "no"}`);
       }
       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");
@@ -395,6 +495,17 @@ export async function runProject(
   }
 
   writeManifestAtomic(manifestPath, updated);
+  if (hasInstructionWrites) {
+    try {
+      applyInstructionPlan(instructionPlan);
+    } catch (error) {
+      throw new Error(
+        `project configuration was saved, but writing instruction files failed: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+    }
+  }
   if (request.sync) {
     try {
       // Reaching here already required approval above (request.yes, or an
@@ -411,7 +522,39 @@ export async function runProject(
       );
     }
   }
-  emitSuccess({ isJson: options.isJson }, { result: plan }, () =>
-    console.log(`project "${request.name}" ready at ${request.path}`),
+
+  // Best-effort and outside the checks above: this mutates another tool's
+  // own config, not skillmux's, so a registration failure is reported, never
+  // rolled back — the successful project setup above still stands either way.
+  const mcpRegistrations: McpRegistrationResult[] = [];
+  if (request.registerMcp) {
+    for (const agent of registrableAgents) {
+      mcpRegistrations.push(
+        await registerMcpServer(agent, { scope: "project", cwd: request.path }),
+      );
+    }
+  }
+
+  emitSuccess(
+    { isJson: options.isJson },
+    {
+      result: {
+        ...plan,
+        instructions_changed: instructionPlan.changes
+          .filter((change) => change.status !== "unchanged")
+          .map((change) => change.path),
+        mcp_registrations: mcpRegistrations,
+      },
+    },
+    () => {
+      console.log(`project "${request.name}" ready at ${request.path}`);
+      for (const registration of mcpRegistrations) {
+        console.log(
+          registration.ok
+            ? `MCP registered: ${registration.agent} (project scope)`
+            : `MCP registration failed for ${registration.agent}: ${registration.error}`,
+        );
+      }
+    },
   );
 }