@klhapp/skillmux 1.10.0 → 1.11.0

package/src/init-agents.ts

@@ -0,0 +1,329 @@
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SUPPORTED_AGENT_IDS = [
+  "claude-code",
+  "codex",
+  "opencode",
+  "github-copilot",
+  "windsurf",
+  "antigravity",
+  "goose",
+  "hermes",
+] as const;
+
+export type AgentId = (typeof SUPPORTED_AGENT_IDS)[number];
+export type DeliveryMode = "managed-pins" | "full-vault";
+
+export interface DetectedAgent {
+  agent: AgentId;
+  evidence: string;
+}
+
+export type McpRegistrationScope = "user" | "project";
+
+export interface McpRegistrationCommand {
+  command: string;
+  /** Returns undefined when this agent's CLI has no way to register at the requested scope. */
+  buildArgs: (scope: McpRegistrationScope) => string[] | undefined;
+}
+
+interface AgentPathOptions {
+  home: string;
+  codexHome: string;
+}
+
+interface AgentInstructionOptions extends AgentPathOptions {
+  claudeConfigDir: string;
+}
+
+/**
+ * The single source of truth for what each agent supports. Every other
+ * module (detection, skill-surface planning, readiness reporting, MCP
+ * registration, instruction files, shell completions, CLI help text) reads
+ * from this record instead of keeping its own copy — see git history for
+ * what it looked like before consolidation (agent support was duplicated
+ * across 6+ files and could silently drift, e.g. shell completions offering
+ * goose/hermes for `project init` when they can't actually be attached).
+ */
+interface AgentDefinition {
+  id: AgentId;
+  surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
+  deliveryMode: DeliveryMode;
+  /** Filesystem evidence used by guided-mode agent detection. */
+  detectionPath?: (options: AgentPathOptions) => string;
+  /** Bespoke readiness message for full-vault agents with no managed-pins surface. */
+  manualSkillSurfaceMessage?: string;
+  instructions?: {
+    global?: (options: AgentInstructionOptions) => string;
+    project?: (projectRoot: string) => string;
+  };
+  /**
+   * Only set for agents whose own CLI's exact registration command was
+   * verified against its own --help, not guessed from docs. Every other
+   * agent falls back to printing the registration snippet (see
+   * printLastMile in init.ts) rather than a guessed command.
+   */
+  mcpRegistration?: McpRegistrationCommand;
+}
+
+export interface PlannedAgentSurface {
+  id: string;
+  targetName: string;
+  path: string;
+  deliveryMode: "managed-pins";
+  agents: AgentId[];
+}
+
+export interface AgentSurfacePlan {
+  agents: AgentDefinition[];
+  surfaces: PlannedAgentSurface[];
+}
+
+type ReadinessStatus = "ready" | "planned" | "manual" | "not-applicable";
+
+export interface ReadinessAxis {
+  status: ReadinessStatus;
+  detail: string;
+}
+
+export interface AgentReadiness {
+  agent: AgentId;
+  skillSurface: ReadinessAxis;
+  mcpRegistration: ReadinessAxis;
+  instructionSetup: ReadinessAxis;
+}
+
+export interface ResolvedBuiltInTarget {
+  targetName: string;
+  path: string;
+}
+
+/** Target names whose install directory is deterministic — --dir is optional for these. */
+export const BUILT_IN_TARGET_NAMES = new Set(["agent-skills", "claude-code", "codex"]);
+
+const AGENTS: Record<AgentId, AgentDefinition> = {
+  "claude-code": {
+    id: "claude-code",
+    surfaceId: "claude-code",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".claude"),
+    instructions: {
+      global: ({ claudeConfigDir }) => join(claudeConfigDir, "CLAUDE.md"),
+      project: (projectRoot) => join(projectRoot, "CLAUDE.md"),
+    },
+    mcpRegistration: {
+      command: "claude",
+      // claude mcp add --scope: local (default, unshared), project (writes a
+      // committed .mcp.json), or user (global). "project" is the only shared
+      // option, so that's what a project-scoped registration means here.
+      buildArgs: (scope) => [
+        "mcp",
+        "add",
+        "-s",
+        scope === "project" ? "project" : "user",
+        "skillmux",
+        "--",
+        "skillmux",
+        "serve",
+      ],
+    },
+  },
+  codex: {
+    id: "codex",
+    surfaceId: "codex",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ codexHome }) => codexHome,
+    instructions: {
+      global: ({ codexHome }) => join(codexHome, "AGENTS.md"),
+    },
+    mcpRegistration: {
+      command: "codex",
+      // codex mcp add has no --scope flag at all — it always writes to the
+      // global ~/.codex/config.toml, so project scope is not representable.
+      buildArgs: (scope) =>
+        scope === "project"
+          ? undefined
+          : ["mcp", "add", "skillmux", "--", "skillmux", "serve"],
+    },
+  },
+  opencode: {
+    id: "opencode",
+    surfaceId: "agent-skills",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".config", "opencode"),
+    instructions: {
+      global: ({ home }) => join(home, ".config", "opencode", "AGENTS.md"),
+    },
+  },
+  "github-copilot": {
+    id: "github-copilot",
+    surfaceId: "agent-skills",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".config", "github-copilot"),
+  },
+  windsurf: {
+    id: "windsurf",
+    surfaceId: "agent-skills",
+    deliveryMode: "managed-pins",
+    detectionPath: ({ home }) => join(home, ".codeium", "windsurf"),
+  },
+  antigravity: {
+    id: "antigravity",
+    surfaceId: "antigravity",
+    deliveryMode: "managed-pins",
+    instructions: {
+      global: ({ home }) => join(home, ".gemini", "GEMINI.md"),
+    },
+  },
+  goose: {
+    id: "goose",
+    deliveryMode: "full-vault",
+    detectionPath: ({ home }) => join(home, ".config", "goose"),
+    manualSkillSurfaceMessage: "configure the full vault in Goose",
+    instructions: {
+      global: ({ home }) => join(home, ".config", "goose", ".goosehints"),
+    },
+  },
+  hermes: {
+    id: "hermes",
+    deliveryMode: "full-vault",
+    detectionPath: ({ home }) => join(home, ".hermes"),
+    manualSkillSurfaceMessage: "configure the full vault in Hermes external_dirs",
+    instructions: {
+      global: ({ home }) => join(home, ".hermes.md"),
+    },
+  },
+};
+
+export function getAgentDefinition(agent: AgentId): AgentDefinition {
+  return AGENTS[agent];
+}
+
+/** Agents that can be attached to a project group (managed-pins delivery, not full-vault). */
+export const MANAGED_PINS_AGENT_IDS = SUPPORTED_AGENT_IDS.filter(
+  (id) => AGENTS[id].deliveryMode === "managed-pins",
+);
+
+export function detectInstalledAgents(
+  options: {
+    home?: string;
+    codexHome?: string;
+    exists?: (path: string) => boolean;
+  } = {},
+): DetectedAgent[] {
+  const home = options.home ?? homedir();
+  const codexHome = options.codexHome ?? join(home, ".codex");
+  const exists = options.exists ?? existsSync;
+  return SUPPORTED_AGENT_IDS.flatMap((agent) => {
+    const evidence = AGENTS[agent].detectionPath?.({ home, codexHome });
+    return evidence && exists(evidence) ? [{ agent, evidence }] : [];
+  });
+}
+
+function surfacePath(
+  surfaceId: NonNullable<AgentDefinition["surfaceId"]>,
+  options: { home: string; codexHome?: string },
+): string {
+  if (surfaceId === "agent-skills") return join(options.home, ".agents", "skills");
+  if (surfaceId === "claude-code") return join(options.home, ".claude", "skills");
+  if (surfaceId === "codex") return join(options.codexHome ?? join(options.home, ".codex"), "skills");
+  return join(options.home, ".gemini", "config", "skills");
+}
+
+export function resolveBuiltInTarget(
+  name: string,
+  options: { home?: string; codexHome?: string; customPath?: string } = {},
+): ResolvedBuiltInTarget {
+  const home = options.home ?? homedir();
+  if (name === "custom") {
+    if (!options.customPath) throw new Error("--target custom requires --path <dir>");
+    return { targetName: name, path: options.customPath };
+  }
+  if (name === "agent-skills") {
+    return { targetName: name, path: surfacePath("agent-skills", { home }) };
+  }
+  if (name === "claude-code") {
+    return { targetName: name, path: surfacePath("claude-code", { home }) };
+  }
+  if (name === "codex") {
+    return {
+      targetName: name,
+      path: surfacePath("codex", { home, codexHome: options.codexHome }),
+    };
+  }
+  throw new Error(
+    `unknown --target "${name}"; supported targets: agent-skills, claude-code, codex, custom`,
+  );
+}
+
+export function planAgentSurfaces(
+  requestedAgents: readonly string[],
+  options: { home?: string; codexHome?: string } = {},
+): AgentSurfacePlan {
+  const agents = [...new Set(requestedAgents)].map((id) => {
+    if (!SUPPORTED_AGENT_IDS.includes(id as AgentId)) {
+      throw new Error(
+        `unsupported agent "${id}"; supported agents: ${SUPPORTED_AGENT_IDS.join(", ")}`,
+      );
+    }
+    return AGENTS[id as AgentId];
+  });
+  const home = options.home ?? homedir();
+  const surfaces = new Map<string, PlannedAgentSurface>();
+
+  for (const agent of agents) {
+    if (!agent.surfaceId) continue;
+    const path = surfacePath(agent.surfaceId, { home, codexHome: options.codexHome });
+    const existing = surfaces.get(path);
+    if (existing) {
+      if (!existing.agents.includes(agent.id)) existing.agents.push(agent.id);
+      continue;
+    }
+    surfaces.set(path, {
+      id: agent.surfaceId,
+      targetName: agent.surfaceId,
+      path,
+      deliveryMode: "managed-pins",
+      agents: [agent.id],
+    });
+  }
+
+  return { agents, surfaces: [...surfaces.values()] };
+}
+
+export function assessAgentReadiness(
+  plan: AgentSurfacePlan,
+  instructionReadiness: Partial<Record<AgentId, ReadinessAxis>> = {},
+): AgentReadiness[] {
+  return plan.agents.map((agent) => {
+    const surface = plan.surfaces.find((candidate) => candidate.agents.includes(agent.id));
+    let skillSurface: ReadinessAxis;
+    if (surface) {
+      skillSurface = { status: "planned", detail: surface.path };
+    } else if (agent.manualSkillSurfaceMessage) {
+      skillSurface = { status: "manual", detail: agent.manualSkillSurfaceMessage };
+    } else {
+      skillSurface = {
+        status: "not-applicable",
+        detail: "skills resolve through Skillmux MCP",
+      };
+    }
+
+    const mcpRegistration: ReadinessAxis = {
+      status: "not-applicable",
+      detail: "native skill loading",
+    };
+
+    return {
+      agent: agent.id,
+      skillSurface,
+      mcpRegistration,
+      instructionSetup: instructionReadiness[agent.id] ?? {
+        status: "manual",
+        detail: "instruction adapter not applied",
+      },
+    };
+  });
+}

package/src/init-instructions.ts

@@ -9,7 +9,7 @@ import {
 } from "node:fs";
 import { dirname, join } from "node:path";
 import { DISCOVERY_PARAGRAPH } from "./init";
-import type { ClientId } from "./init-clients";
+import { getAgentDefinition, type AgentId } from "./init-agents";
 
 export const INSTRUCTION_BLOCK_START = "<!-- skillmux:discovery:start -->";
 export const INSTRUCTION_BLOCK_END = "<!-- skillmux:discovery:end -->";
@@ -22,7 +22,7 @@ const MANAGED_BLOCK = [
 
 export interface InstructionChange {
   path: string;
-  clients: ClientId[];
+  agents: AgentId[];
   status: "create" | "update" | "unchanged";
   before: string | null;
   after: string;
@@ -30,7 +30,7 @@ export interface InstructionChange {
 
 export interface InstructionPlan {
   changes: InstructionChange[];
-  manual: Array<{ client: ClientId; reason: string }>;
+  manual: Array<{ agent: AgentId; reason: string }>;
 }
 
 interface InstructionPlanOptions {
@@ -41,18 +41,10 @@ interface InstructionPlanOptions {
 }
 
 function instructionPath(
-  client: ClientId,
+  agent: AgentId,
   options: Required<Pick<InstructionPlanOptions, "home" | "codexHome" | "claudeConfigDir">>,
 ): string | undefined {
-  if (client === "claude-code") return join(options.claudeConfigDir, "CLAUDE.md");
-  if (client === "codex") return join(options.codexHome, "AGENTS.md");
-  if (client === "gemini-cli" || client === "antigravity") {
-    return join(options.home, ".gemini", "GEMINI.md");
-  }
-  if (client === "opencode") return join(options.home, ".config", "opencode", "AGENTS.md");
-  if (client === "goose") return join(options.home, ".config", "goose", ".goosehints");
-  if (client === "hermes") return join(options.home, ".hermes.md");
-  return undefined;
+  return getAgentDefinition(agent).instructions?.global?.(options);
 }
 
 function readInstructionFile(path: string): string | null {
@@ -85,29 +77,23 @@ function withManagedBlock(existing: string | null, path: string): string {
   return `${existing.slice(0, start)}${MANAGED_BLOCK}${existing.slice(end + INSTRUCTION_BLOCK_END.length)}`;
 }
 
-export function planInstructionSetup(
-  requestedClients: readonly ClientId[],
-  options: InstructionPlanOptions = {},
+function planInstructionSetupWithResolver(
+  requestedAgents: readonly AgentId[],
+  resolvePath: (agent: AgentId) => string | undefined,
+  readFile: (path: string) => string | null,
 ): InstructionPlan {
-  const home = options.home ?? process.env.HOME ?? "";
-  const resolvedOptions = {
-    home,
-    codexHome: options.codexHome ?? process.env.CODEX_HOME ?? join(home, ".codex"),
-    claudeConfigDir: options.claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"),
-  };
-  const readFile = options.readFile ?? readInstructionFile;
   const changesByPath = new Map<string, InstructionChange>();
   const manual: InstructionPlan["manual"] = [];
 
-  for (const client of [...new Set(requestedClients)]) {
-    const path = instructionPath(client, resolvedOptions);
+  for (const agent of [...new Set(requestedAgents)]) {
+    const path = resolvePath(agent);
     if (!path) {
-      manual.push({ client, reason: "no safe durable user instruction file is known" });
+      manual.push({ agent, reason: "no safe durable user instruction file is known" });
       continue;
     }
     const existingChange = changesByPath.get(path);
     if (existingChange) {
-      existingChange.clients.push(client);
+      existingChange.agents.push(agent);
       continue;
     }
 
@@ -115,7 +101,7 @@ export function planInstructionSetup(
     const after = withManagedBlock(before, path);
     changesByPath.set(path, {
       path,
-      clients: [client],
+      agents: [agent],
       status: before === null ? "create" : before === after ? "unchanged" : "update",
       before,
       after,
@@ -125,6 +111,39 @@ export function planInstructionSetup(
   return { changes: [...changesByPath.values()], manual };
 }
 
+export function planInstructionSetup(
+  requestedAgents: readonly AgentId[],
+  options: InstructionPlanOptions = {},
+): InstructionPlan {
+  const home = options.home ?? process.env.HOME ?? "";
+  const resolvedOptions = {
+    home,
+    codexHome: options.codexHome ?? process.env.CODEX_HOME ?? join(home, ".codex"),
+    claudeConfigDir: options.claudeConfigDir ?? process.env.CLAUDE_CONFIG_DIR ?? join(home, ".claude"),
+  };
+  return planInstructionSetupWithResolver(
+    requestedAgents,
+    (agent) => instructionPath(agent, resolvedOptions),
+    options.readFile ?? readInstructionFile,
+  );
+}
+
+function projectInstructionPath(agent: AgentId, projectRoot: string): string | undefined {
+  return getAgentDefinition(agent).instructions?.project?.(projectRoot);
+}
+
+export function planProjectInstructionSetup(
+  requestedAgents: readonly AgentId[],
+  projectRoot: string,
+  options: Pick<InstructionPlanOptions, "readFile"> = {},
+): InstructionPlan {
+  return planInstructionSetupWithResolver(
+    requestedAgents,
+    (agent) => projectInstructionPath(agent, projectRoot),
+    options.readFile ?? readInstructionFile,
+  );
+}
+
 function atomicWrite(path: string, content: string, mode: number): void {
   mkdirSync(dirname(path), { recursive: true });
   const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;

package/src/mcp-registration.ts

@@ -0,0 +1,89 @@
+import {
+  getAgentDefinition,
+  SUPPORTED_AGENT_IDS,
+  type AgentId,
+  type McpRegistrationScope,
+} from "./init-agents";
+
+export type { McpRegistrationScope };
+
+export const MCP_REGISTRABLE_AGENTS = SUPPORTED_AGENT_IDS.filter(
+  (agent) => getAgentDefinition(agent).mcpRegistration !== undefined,
+);
+
+export const MCP_PROJECT_REGISTRABLE_AGENTS = MCP_REGISTRABLE_AGENTS.filter(
+  (agent) => getAgentDefinition(agent).mcpRegistration!.buildArgs("project") !== undefined,
+);
+
+export function isMcpRegistrable(agent: AgentId): boolean {
+  return getAgentDefinition(agent).mcpRegistration !== undefined;
+}
+
+export interface McpRegistrationResult {
+  agent: AgentId;
+  ok: boolean;
+  error?: string;
+}
+
+type SpawnFn = (
+  cmd: string[],
+  opts?: { cwd?: string },
+) => {
+  exited: Promise<number>;
+  stderr: ReadableStream<Uint8Array> | number;
+};
+
+/**
+ * Runs the agent's own CLI to register skillmux as an MCP server. Never
+ * throws — registration failure (tool not installed, command rejected,
+ * etc.) is reported in the result, not fatal to the caller's larger flow.
+ */
+export async function registerMcpServer(
+  agent: AgentId,
+  options: {
+    spawn?: SpawnFn;
+    scope?: McpRegistrationScope;
+    cwd?: string;
+  } = {},
+): Promise<McpRegistrationResult> {
+  const entry = getAgentDefinition(agent).mcpRegistration;
+  const scope = options.scope ?? "user";
+  const args = entry?.buildArgs(scope);
+  if (!entry || !args) {
+    return {
+      agent,
+      ok: false,
+      error: `no ${scope === "project" ? "project-scoped " : ""}MCP registration command known for agent "${agent}"`,
+    };
+  }
+  const spawn: SpawnFn =
+    options.spawn ??
+    ((cmd, opts) => Bun.spawn(cmd, { stdout: "pipe", stderr: "pipe", cwd: opts?.cwd }));
+  try {
+    const proc = spawn([entry.command, ...args], { cwd: options.cwd });
+    const stderrText =
+      typeof proc.stderr === "number"
+        ? ""
+        : await new Response(proc.stderr).text();
+    const exitCode = await proc.exited;
+    if (exitCode !== 0) {
+      return {
+        agent,
+        ok: false,
+        error:
+          stderrText.trim() || `${entry.command} exited with code ${exitCode}`,
+      };
+    }
+    return { agent, ok: true };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const notFound = /ENOENT|not found|no such file/i.test(message);
+    return {
+      agent,
+      ok: false,
+      error: notFound
+        ? `"${entry.command}" is not installed or not on PATH`
+        : message,
+    };
+  }
+}

package/src/output.ts

@@ -3,6 +3,8 @@ import type { ResolvedContext } from "./context";
 export interface JsonEnvelope<T = any> {
   schema_version: 1;
   ok: boolean;
+  context: string | { name: string; server: string };
+  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
   target: string | { name: string; server: string };
   data: T | null;
   error: { code: string; message: string; details?: any } | null;
@@ -10,27 +12,34 @@ export interface JsonEnvelope<T = any> {
 
 export function formatJsonEnvelope<T>(opts: {
   ok: boolean;
-  target: ResolvedContext | string | { name: string; server: string };
+  /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+  target?: ResolvedContext | string | { name: string; server: string };
+  context?: ResolvedContext | string | { name: string; server: string };
   data?: T;
   error?: { code: string; message: string; details?: any } | null;
 }): JsonEnvelope<T> {
-  let targetVal: string | { name: string; server: string };
-  if (typeof opts.target === "string" || (typeof opts.target === "object" && "server" in opts.target && !("type" in opts.target))) {
-    targetVal = opts.target as any;
-  } else if (typeof opts.target === "object" && "type" in opts.target) {
-    if (opts.target.type === "local") {
-      targetVal = "local";
+  const input: ResolvedContext | string | { name: string; server: string } =
+    opts.context ?? opts.target ?? "local";
+  let contextVal: string | { name: string; server: string };
+  if (typeof input === "string") {
+    contextVal = input;
+  } else if (typeof input === "object" && input !== null) {
+    if ("type" in input && (input as any).type === "local") {
+      contextVal = "local";
+    } else if ("name" in input && "server" in input) {
+      contextVal = { name: input.name, server: input.server };
     } else {
-      targetVal = { name: opts.target.name, server: opts.target.server };
+      contextVal = "local";
     }
   } else {
-    targetVal = "local";
+    contextVal = "local";
   }
 
   return {
     schema_version: 1,
     ok: opts.ok,
-    target: targetVal,
+    context: contextVal,
+    target: contextVal,
     data: opts.data ?? null,
     error: opts.error ?? null,
   };
@@ -51,12 +60,18 @@ export class CliError extends Error {
 }
 
 export function emitSuccess<T>(
-  ctx: { isJson: boolean; target?: ResolvedContext | string | { name: string; server: string } },
+  ctx: {
+    isJson: boolean;
+    /** @deprecated Slated for removal in the next major version. Use `context` instead. */
+    target?: ResolvedContext | string | { name: string; server: string };
+    context?: ResolvedContext | 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 })));
+    const contextVal = ctx.context ?? ctx.target ?? "local";
+    console.log(JSON.stringify(formatJsonEnvelope({ ok: true, context: contextVal, target: contextVal, data })));
   } else {
     renderText();
   }
@@ -112,6 +127,28 @@ export function suggestCorrection(input: string, candidates: string[]): string |
   return bestMatch;
 }
 
+/**
+ * Builds the error for an unrecognized subcommand: "did you mean X" when
+ * close to a valid one, otherwise the full <a|b|c> usage list — never a
+ * fixed, possibly-unrelated usage string for just one of several valid
+ * subcommands (that's what `config`'s fallback used to do before this
+ * existed: any invalid subcommand got told "usage: skillmux config show",
+ * silently omitting get/set/validate/diff/status/init).
+ */
+export function unknownSubcommandError(
+  command: string,
+  subCommand: string,
+  validSubcommands: string[],
+): Error {
+  const suggestion = subCommand ? suggestCorrection(subCommand, validSubcommands) : null;
+  if (suggestion) {
+    return new Error(
+      `Unknown "${command} ${subCommand}" subcommand. Did you mean "${command} ${suggestion}"?`,
+    );
+  }
+  return new Error(`usage: skillmux ${command} <${validSubcommands.join("|")}>`);
+}
+
 export function isInteractive(
   env: NodeJS.ProcessEnv = process.env,
   stdoutIsTTY = process.stdout.isTTY,
@@ -144,12 +181,12 @@ export function warn(line: string): void {
   console.error(yellow(`warning: ${line}`));
 }
 
-export function renderTargetBanner(target: ResolvedContext): void {
+export function renderContextBanner(context: ResolvedContext): void {
   if (!isInteractive()) return;
-  if (target.type === "local") {
-    console.log(`Target: local`);
+  if (context.type === "local") {
+    console.log(`Context: local`);
   } else {
-    console.log(`Target: remote (${target.name} -> ${target.server})`);
+    console.log(`Context: remote (${context.name} -> ${context.server})`);
   }
 }