@klhapp/skillmux 1.10.0 → 1.11.0

package/src/commands/doctor.ts

@@ -1,29 +1,50 @@
 import { resolveConfigPath } from "../config";
 import { diagnose } from "../doctor";
 import { getEffectiveConfig } from "../config-service";
-import type { TargetAdapter } from "../adapters";
+import type { ContextAdapter } from "../adapters";
 import type { ResolvedContext } from "../context";
+import { isGlobalFlag, isGlobalFlagWithValue } from "../global-flags";
 import {
   emitSuccess,
   green,
   red,
-  renderTargetBanner,
+  renderContextBanner,
 } from "../output";
 
+/**
+ * doctor takes no options of its own, but it still has to reject unknown ones
+ * rather than silently ignoring them the way every other command does.
+ */
+export function parseDoctorArgs(args: readonly string[]): void {
+  for (let i = 0; i < args.length; i++) {
+    const option = args[i];
+    if (isGlobalFlag(option, "--json", "--allow-insecure", "--verbose")) {
+      // handled globally by main(); recognized here so it isn't rejected
+    } else if (isGlobalFlagWithValue(option)) {
+      // handled globally by main()'s resolveContext(); skip its value too
+      i++;
+    } else {
+      throw new Error(`unknown doctor option: ${option}`);
+    }
+  }
+}
+
 export async function runDoctor(options: {
   isJson: boolean;
-  target: ResolvedContext;
-  adapter: TargetAdapter;
+  context: ResolvedContext;
+  adapter: ContextAdapter;
+  args?: readonly string[];
 }): Promise<void> {
-  if (options.target.type === "remote") {
-    const target = options.target;
+  parseDoctorArgs(options.args ?? []);
+  if (options.context.type === "remote") {
+    const context = options.context;
     const [status, caps] = await Promise.all([
       options.adapter.configStatus(),
       options.adapter.getCapabilities(),
     ]);
     const remoteReport = {
-      target: target.name || target.server,
-      server: target.server,
+      target: context.name || context.server,
+      server: context.server,
       version: status.version,
       deployment_runtime: status.deployment_runtime,
       image_variant: status.image_variant ?? null,
@@ -34,8 +55,8 @@ export async function runDoctor(options: {
       restart_required_keys: status.restart_required_keys,
       last_reload_error: status.last_reload_error,
     };
-    emitSuccess({ isJson: options.isJson, target: options.target }, remoteReport, () => {
-      renderTargetBanner(options.target);
+    emitSuccess({ isJson: options.isJson, target: options.context }, remoteReport, () => {
+      renderContextBanner(options.context);
       console.log(`server: ${remoteReport.server}`);
       console.log(`version: ${remoteReport.version}`);
       console.log(`deployment runtime: ${remoteReport.deployment_runtime}`);

package/src/commands/eval.ts

@@ -5,20 +5,22 @@ import { excludeExistingCases, parseEvalCases } from "../eval";
 import { emitSuccess, warn } from "../output";
 import { parseSince } from "../stats";
 import { confirmIfNeeded } from "./shared";
-import type { TargetAdapter } from "../adapters";
+import type { ContextAdapter } from "../adapters";
 import { isGlobalFlag, isGlobalFlagWithValue } from "../global-flags";
 
 export async function runEvalPromote(
   args: string[],
-  options: { isJson: boolean; dryRun: boolean; adapter: TargetAdapter },
+  options: { isJson: boolean; dryRun: boolean; adapter: ContextAdapter },
 ): Promise<void> {
   let since: string | undefined;
+  let out: string | undefined;
   let target: string | undefined;
   let dryRun = options.dryRun;
   let yes = false;
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
     if (arg === "--since") since = args[++i];
+    else if (arg === "--out") out = args[++i];
     else if (arg === "--target") target = args[++i];
     else if (arg === "--dry-run") dryRun = true;
     else if (arg === "--yes") yes = true;
@@ -31,12 +33,20 @@ export async function runEvalPromote(
     }
   }
   if (!since) {
-    throw new Error("usage: skillmux eval promote --since <window> [--target <path>] [--dry-run] [--yes] [--json]");
+    throw new Error("usage: skillmux eval promote --since <window> [--out <path>] [--dry-run] [--yes] [--json]");
+  }
+
+  if (out !== undefined && target !== undefined && out !== target) {
+    throw new Error("cannot specify conflicting --out and --target");
+  }
+
+  if (target !== undefined) {
+    warn("--target is deprecated, use --out instead");
   }
 
   const config = await loadConfig();
   const stateDir = expandHome(config.state_dir);
-  const targetPath = target ?? join(stateDir, "eval-observed.json");
+  const targetPath = out ?? target ?? join(stateDir, "eval-observed.json");
   const sinceDate = parseSince(since);
   const sinceIso = sinceDate.toISOString();
 

package/src/commands/init.ts

@@ -15,21 +15,25 @@ import {
   surfaceCandidates,
 } from "../init";
 import {
-  assessClientReadiness,
-  detectInstalledClients,
-  planClientSurfaces,
-  resolveBuiltInTarget,
-  SUPPORTED_CLIENT_IDS,
-  type ClientId,
+  assessAgentReadiness,
+  detectInstalledAgents,
+  planAgentSurfaces,
+  SUPPORTED_AGENT_IDS,
+  type AgentId,
   type ReadinessAxis,
-} from "../init-clients";
+} from "../init-agents";
 import {
   applyInstructionPlan,
   planInstructionSetup,
   rollbackInstructionPlan,
 } from "../init-instructions";
 import { parseManifest, resolveManifestPath } from "../manifest";
-import { isInteractive, warn } from "../output";
+import {
+  MCP_REGISTRABLE_AGENTS,
+  registerMcpServer,
+  type McpRegistrationResult,
+} from "../mcp-registration";
+import { isInteractive } from "../output";
 import { isGlobalFlag } from "../global-flags";
 import {
   parseCommaList,
@@ -49,47 +53,41 @@ import { confirmAction } from "./shared";
 import { runSync } from "./sync";
 
 function parseInitArgs(args: string[]): {
-  targets: string[];
-  clients: string[];
+  agents: string[];
   coreSkillIds: string[];
-  customPath?: string;
   migrateFullVault: boolean;
+  showMcpSetup: boolean;
+  registerMcp: boolean;
   skipInstructions: boolean;
   sync: boolean;
   vaultPath?: string;
   yes: boolean;
 } {
-  const targets: string[] = [];
-  const clients: string[] = [];
+  const agents: string[] = [];
   const coreSkillIds: string[] = [];
-  let customPath: string | undefined;
   let migrateFullVault = false;
+  let showMcpSetup = false;
+  let registerMcp = false;
   let skipInstructions = false;
   let sync = true;
   let vaultPath: string | undefined;
   let yes = false;
   for (let i = 0; i < args.length; i++) {
     const option = args[i];
-    if (option === "--target") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--target requires a name");
-      targets.push(value);
-      i++;
-    } else if (option === "--client") {
+    if (option === "--target" || option === "--dir" || option === "--client") {
+      throw new Error(
+        `${option} was removed; select a specific supported agent with --agent instead (see "skillmux init --help")`,
+      );
+    } else if (option === "--agent") {
       const value = args[i + 1];
-      if (!value) throw new Error("--client requires a name");
-      clients.push(value);
+      if (!value) throw new Error("--agent requires a name");
+      agents.push(value);
       i++;
     } else if (option === "--vault") {
       const value = args[i + 1];
       if (!value) throw new Error("--vault requires a path");
       vaultPath = value;
       i++;
-    } else if (option === "--dir") {
-      const value = args[i + 1];
-      if (!value) throw new Error("--dir requires a directory");
-      customPath = value;
-      i++;
     } else if (option === "--core") {
       const value = args[i + 1];
       if (!value) throw new Error("--core requires a skill_id");
@@ -102,6 +100,10 @@ function parseInitArgs(args: string[]): {
       continue;
     } else if (option === "--migrate-full-vault") {
       migrateFullVault = true;
+    } else if (option === "--show-mcp-setup") {
+      showMcpSetup = true;
+    } else if (option === "--register-mcp") {
+      registerMcp = true;
     } else if (option === "--no-instructions") {
       skipInstructions = true;
     } else if (option === "--no-sync") {
@@ -113,11 +115,11 @@ function parseInitArgs(args: string[]): {
     }
   }
   return {
-    targets,
-    clients,
+    agents,
     coreSkillIds,
-    customPath,
     migrateFullVault,
+    showMcpSetup,
+    registerMcp,
     skipInstructions,
     sync,
     vaultPath,
@@ -125,16 +127,49 @@ function parseInitArgs(args: string[]): {
   };
 }
 
+interface InitJsonPayload {
+  command: "init";
+  phase: "plan" | "result";
+  dry_run: boolean;
+  applied: boolean;
+  plan: unknown;
+  result?: unknown;
+}
+
+/**
+ * init predates the shared emitSuccess envelope and shipped its own top-level
+ * keys, which existing automation reads. Emit the documented envelope
+ * (`target`/`data`/`error`, see docs/cli.md) so generic consumers work, while
+ * keeping the original keys so nothing breaks. init's error path already goes
+ * through the shared handler and needs no bridging.
+ *
+ * DEPRECATED: the duplicated top-level `command`/`phase`/`dry_run`/`applied`/
+ * `plan`/`result` keys should be dropped in the next major version, leaving
+ * only the standard envelope. init is local-only, so `target` is always
+ * "local".
+ */
+function initJsonEnvelope(payload: InitJsonPayload): string {
+  return JSON.stringify({
+    schema_version: 1,
+    ok: true,
+    context: "local",
+    target: "local",
+    data: payload,
+    error: null,
+    ...payload,
+  });
+}
+
 export async function runInit(
   args: string[],
   options: { isJson: boolean; dryRun: boolean },
 ): Promise<void> {
   const {
-    targets: explicitTargets,
-    clients: requestedClients,
+    agents: requestedAgents,
     coreSkillIds,
-    customPath,
     migrateFullVault,
+    showMcpSetup,
+    registerMcp: requestedRegisterMcp,
     skipInstructions,
     sync,
     vaultPath: requestedVaultPath,
@@ -150,9 +185,14 @@ export async function runInit(
   let configPlan: ConfigInitPlan | undefined;
   let vaultPath: string;
   if (!existsSync(configPath)) {
-    const bootstrapVaultPath =
-      requestedVaultPath ??
-      (!options.isJson && isInteractive() ? "~/skills" : undefined);
+    let bootstrapVaultPath = requestedVaultPath;
+    if (!bootstrapVaultPath) {
+      if (guided) {
+        bootstrapVaultPath = await promptText("Skill vault path", "~/skills");
+      } else if (!options.isJson && isInteractive()) {
+        bootstrapVaultPath = "~/skills";
+      }
+    }
     if (!bootstrapVaultPath) {
       throw new Error(
         `machine config does not exist: ${configPath}; re-run with --vault <path>`,
@@ -161,7 +201,7 @@ export async function runInit(
     configPlan = planConfigInit(configPath, expandHome(bootstrapVaultPath));
     vaultPath = configPlan.vaultPath;
     if (!options.isJson) {
-      console.log(`config create: ${configPath}`);
+      console.log(`config create: ${configPath} (vault: ${vaultPath})`);
     }
   } else {
     const config = await loadConfig();
@@ -178,25 +218,25 @@ export async function runInit(
     throw new Error(vaultHealth.message);
   }
 
-  let selectedClients = requestedClients;
+  let selectedAgents = requestedAgents;
   if (guided) {
-    const detected = detectInstalledClients({
+    const detected = detectInstalledAgents({
       codexHome: process.env.CODEX_HOME
         ? expandHome(process.env.CODEX_HOME)
         : undefined,
     });
     const evidence = new Map(
-      detected.map((item) => [item.client, item.evidence]),
+      detected.map((item) => [item.agent, item.evidence]),
     );
-    selectedClients = await promptMultiSelect(
-      "Which clients do you use?",
-      SUPPORTED_CLIENT_IDS.map((client) => ({
-        value: client,
-        label: client,
-        detail: evidence.has(client)
-          ? `detected: ${evidence.get(client)}`
+    selectedAgents = await promptMultiSelect(
+      "Which agents do you use?",
+      SUPPORTED_AGENT_IDS.map((agent) => ({
+        value: agent,
+        label: agent,
+        detail: evidence.has(agent)
+          ? `detected: ${evidence.get(agent)}`
           : undefined,
-        selected: evidence.has(client) || requestedClients.includes(client),
+        selected: evidence.has(agent) || requestedAgents.includes(agent),
       })),
     );
   }
@@ -210,77 +250,79 @@ export async function runInit(
     );
   }
 
-  const clientPlan = planClientSurfaces(selectedClients, {
+  // Native pins and MCP registration are independent choices — this stays
+  // opt-in and only offered for agents whose own CLI we've verified, so a
+  // user who only wants native skill management sees nothing new here.
+  const registrableAgents = selectedAgents.filter((agent) =>
+    MCP_REGISTRABLE_AGENTS.includes(agent as AgentId),
+  ) as AgentId[];
+  let registerMcp = requestedRegisterMcp;
+  if (guided && registrableAgents.length > 0) {
+    registerMcp = await confirmAction(
+      `Also register skillmux as an MCP server for ${registrableAgents.join(", ")}?`,
+    );
+  }
+
+  const agentPlan = planAgentSurfaces(selectedAgents, {
     codexHome: process.env.CODEX_HOME
       ? expandHome(process.env.CODEX_HOME)
       : undefined,
   });
+  // The managed instruction block only teaches an agent to call resolve_skill
+  // /fetch_skill (MCP tools) — writing it for an agent with no MCP registered
+  // or requested would tell that agent to call tools that don't exist. Only
+  // agents actually getting MCP this run (or whose snippet the user asked to
+  // see) get the block; native-only setups get no instruction writes at all.
+  const mcpInstructionAgentIds = agentPlan.agents
+    .map((agent) => agent.id)
+    .filter(
+      (agentId) =>
+        showMcpSetup || (registerMcp && registrableAgents.includes(agentId)),
+    );
   const instructionPlan = planInstructionSetup(
-    skipInstructions ? [] : clientPlan.clients.map((client) => client.id),
+    skipInstructions ? [] : mcpInstructionAgentIds,
     {
       codexHome: process.env.CODEX_HOME
         ? expandHome(process.env.CODEX_HOME)
         : undefined,
     },
   );
-  const instructionReadiness: Partial<Record<ClientId, ReadinessAxis>> = {};
+  const instructionReadiness: Partial<Record<AgentId, ReadinessAxis>> = {};
   for (const change of instructionPlan.changes) {
-    for (const client of change.clients) {
-      instructionReadiness[client] = {
+    for (const agent of change.agents) {
+      instructionReadiness[agent] = {
         status: change.status === "unchanged" ? "ready" : "planned",
         detail: change.path,
       };
     }
   }
   for (const manual of instructionPlan.manual) {
-    instructionReadiness[manual.client] = {
+    instructionReadiness[manual.agent] = {
       status: "manual",
       detail: manual.reason,
     };
   }
-  const builtInNames = new Set([
-    "agent-skills",
-    "claude-code",
-    "codex",
-    "custom",
-    "agents",
-    "claude",
-  ]);
-  const explicitSurfaceTargets = explicitTargets
-    .filter((name) => builtInNames.has(name))
-    .map((name) =>
-      resolveBuiltInTarget(name, {
-        codexHome: process.env.CODEX_HOME
-          ? expandHome(process.env.CODEX_HOME)
-          : undefined,
-        customPath: customPath ? expandHome(customPath) : undefined,
-      }),
-    );
-  if (customPath && !explicitTargets.includes("custom")) {
-    throw new Error("--dir may only be used with --target custom");
-  }
-  for (const target of explicitSurfaceTargets) {
-    if (target.warning) warn(target.warning);
+  for (const agent of agentPlan.agents) {
+    if (mcpInstructionAgentIds.includes(agent.id)) continue;
+    if (instructionReadiness[agent.id]) continue;
+    instructionReadiness[agent.id] = {
+      status: "not-applicable",
+      detail: "no MCP requested — see --show-mcp-setup / --register-mcp",
+    };
   }
-  const targetByPath = new Map(
-    explicitSurfaceTargets.map(
-      (target) => [target.path, target.targetName] as const,
-    ),
-  );
   const existingManifestPath = resolveManifestPath(vaultPath);
   const existingManifest = existingManifestPath
     ? parseManifest(await Bun.file(existingManifestPath).text())
     : undefined;
-  for (const surface of clientPlan.surfaces) {
-    if (!targetByPath.has(surface.path)) {
-      targetByPath.set(
-        surface.path,
-        existingManifest
-          ? (configuredTargetForSurface(existingManifest, surface) ??
-              surface.targetName)
-          : surface.targetName,
-      );
-    }
+  const targetByPath = new Map<string, string>();
+  for (const surface of agentPlan.surfaces) {
+    targetByPath.set(
+      surface.path,
+      existingManifest
+        ? (configuredTargetForSurface(existingManifest, surface) ??
+            surface.targetName)
+        : surface.targetName,
+    );
   }
   const candidatePaths = [
     ...new Set([
@@ -327,11 +369,11 @@ export async function runInit(
         `${name} (${candidate.path}): ${kind}, ${candidate.skillCount} skills${marked}`,
       );
     }
-    for (const readiness of assessClientReadiness(
-      clientPlan,
+    for (const readiness of assessAgentReadiness(
+      agentPlan,
       instructionReadiness,
     )) {
-      console.log(`\n${readiness.client} readiness:`);
+      console.log(`\n${readiness.agent} readiness:`);
       console.log(
         `  skill surface: ${readiness.skillSurface.status} — ${readiness.skillSurface.detail}`,
       );
@@ -344,20 +386,15 @@ export async function runInit(
     }
     for (const change of instructionPlan.changes) {
       console.log(
-        `instructions ${change.status}: ${change.path} (${change.clients.join(", ")})`,
+        `instructions ${change.status}: ${change.path} (${change.agents.join(", ")})`,
       );
     }
     for (const manual of instructionPlan.manual) {
-      console.log(`instructions manual: ${manual.client} — ${manual.reason}`);
+      console.log(`instructions manual: ${manual.agent} — ${manual.reason}`);
     }
   }
 
-  const requestedTargets = [
-    ...new Set([
-      ...explicitTargets.filter((name) => !builtInNames.has(name)),
-      ...targetByPath.values(),
-    ]),
-  ];
+  const requestedTargets = [...new Set(targetByPath.values())];
   const hasInstructionWrites = instructionPlan.changes.some(
     (change) => change.status !== "unchanged",
   );
@@ -402,7 +439,7 @@ export async function runInit(
         );
       }
       throw new Error(
-        `unknown --target "${name}": not among detected surfaces`,
+        `target "${name}" not among detected surfaces`,
       );
     }
   }
@@ -425,22 +462,21 @@ export async function runInit(
     config: configPlan
       ? { path: configPlan.configPath, action: configPlan.action }
       : { path: configPath, action: "preserve" },
-    clients: clientPlan.clients.map((client) => client.id),
+    agents: agentPlan.agents.map((agent) => agent.id),
     targets: confirmedTargets,
     core: plannedManifest.core.skills,
-    instructions: instructionPlan.changes.map(({ path, clients, status }) => ({
+    instructions: instructionPlan.changes.map(({ path, agents, status }) => ({
       path,
-      clients,
+      agents,
       status,
     })),
     manual: instructionPlan.manual,
+    register_mcp_for: registerMcp ? registrableAgents : [],
   };
   if (!hasChanges) {
     if (options.isJson) {
       console.log(
-        JSON.stringify({
-          schema_version: 1,
-          ok: true,
+        initJsonEnvelope({
           command: "init",
           phase: "plan",
           dry_run: options.dryRun,
@@ -466,9 +502,7 @@ export async function runInit(
   if (options.dryRun) {
     if (options.isJson) {
       console.log(
-        JSON.stringify({
-          schema_version: 1,
-          ok: true,
+        initJsonEnvelope({
           command: "init",
           phase: "plan",
           dry_run: true,
@@ -480,7 +514,8 @@ export async function runInit(
       console.log(
         `\ndry-run: ${confirmedTargets.length} target(s), ` +
           `${instructionPlan.changes.filter((change) => change.status !== "unchanged").length} instruction file(s), ` +
-          `core: ${plannedManifest.core.skills.join(", ") || "(unchanged)"}`,
+          `core: ${plannedManifest.core.skills.join(", ") || "(unchanged)"}, ` +
+          `MCP registration: ${registerMcp ? registrableAgents.join(", ") || "(none)" : "(none)"}`,
       );
     }
     return;
@@ -490,7 +525,7 @@ export async function runInit(
     if (!options.isJson && isInteractive()) {
       if (guided) {
         console.log("\nReview");
-        console.log(`  clients: ${selectedClients.join(", ") || "(none)"}`);
+        console.log(`  agents: ${selectedAgents.join(", ") || "(none)"}`);
         console.log(
           `  targets: ${confirmedTargets.map((target) => `${target.name} -> ${target.dir}`).join(", ") || "(none)"}`,
         );
@@ -500,6 +535,9 @@ export async function runInit(
         console.log(
           `  core: ${plannedManifest.core.skills.join(", ") || "(none)"}`,
         );
+        console.log(
+          `  MCP registration: ${registerMcp ? registrableAgents.join(", ") || "(none)" : "(none)"}`,
+        );
         console.log(`  sync: ${sync ? "yes" : "no"}`);
         if (!(await confirmAction("apply this setup plan?"))) {
           console.log("init cancelled");
@@ -572,11 +610,19 @@ export async function runInit(
     );
   }
 
+  // Best-effort and outside the rollback above: this mutates another tool's
+  // own config, not skillmux's, so a registration failure is reported, never
+  // rolled back — the successful native setup above still stands either way.
+  const mcpRegistrations: McpRegistrationResult[] = [];
+  if (registerMcp) {
+    for (const agent of registrableAgents) {
+      mcpRegistrations.push(await registerMcpServer(agent));
+    }
+  }
+
   if (options.isJson) {
     console.log(
-      JSON.stringify({
-        schema_version: 1,
-        ok: true,
+      initJsonEnvelope({
         command: "init",
         phase: "result",
         dry_run: false,
@@ -589,6 +635,7 @@ export async function runInit(
             .filter((change) => change.status !== "unchanged")
             .map((change) => change.path),
           core: plannedManifest.core.skills,
+          mcp_registrations: mcpRegistrations,
         },
       }),
     );
@@ -605,11 +652,15 @@ export async function runInit(
   if (plannedManifest.core.skills.length === 0 && confirmedTargets.length > 0) {
     console.log("next: skillmux core pin <skill_id> --yes");
   }
-  if (confirmedTargets.length > 0) console.log("next: skillmux sync");
-  if (
-    selectedClients.length === 0 ||
-    selectedClients.includes("skillmux-mcp")
-  ) {
+  if (!sync && confirmedTargets.length > 0) console.log("next: skillmux sync");
+  for (const registration of mcpRegistrations) {
+    console.log(
+      registration.ok
+        ? `registered skillmux as an MCP server for ${registration.agent}`
+        : `failed to register skillmux as an MCP server for ${registration.agent}: ${registration.error}`,
+    );
+  }
+  if (selectedAgents.length === 0 || showMcpSetup) {
     console.log(`\n${printLastMile()}`);
   }
   // Reaching this point already required approval above (--yes, or an accepted
@@ -617,5 +668,5 @@ export async function runInit(
   // new target directories this init just adopted, so runSync's own new-target
   // confirmation gate would just be a redundant (and non-interactively,
   // silently-skipping) re-ask.
-  if (guided && sync && confirmedTargets.length > 0) await runSync(["--yes"]);
+  if (sync && confirmedTargets.length > 0) await runSync(["--yes"]);
 }