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

@@ -0,0 +1,26 @@
+/**
+ * Centralized logging helpers, all writing to stderr via console.error.
+ * `log` emits structured JSON ({ level, stage, ...payload }) for machine-
+ * readable signals like router-core's retrieval-degradation warnings.
+ * `redactedErrorLog` builds a plain-text [prefix, message] pair for
+ * operator-facing runtime errors that need secret redaction.
+ */
+
+export const log = {
+  warn(stage: string, payload: Record<string, unknown>): void {
+    console.error(JSON.stringify({ level: "warn", stage, ...payload }));
+  },
+  error(stage: string, payload: Record<string, unknown>): void {
+    console.error(JSON.stringify({ level: "error", stage, ...payload }));
+  },
+};
+
+/** Pairs a fixed log prefix with a redacted error message, for console.error. */
+export function redactedErrorLog(
+  prefix: string,
+  err: unknown,
+  redact: (text: string) => string,
+): [string, string] {
+  const msg = err instanceof Error ? err.message : String(err);
+  return [prefix, redact(msg)];
+}

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,
+    };
+  }
+}