@klhapp/skillmux 0.4.4 → 0.5.0

package/src/completions.ts

@@ -20,7 +20,7 @@ _skillmux_completions() {
             COMPREPLY=( $(compgen -W "add list current use remove" -- "$cur") )
             ;;
         config)
-            COMPREPLY=( $(compgen -W "show get validate diff set status" -- "$cur") )
+            COMPREPLY=( $(compgen -W "init show get validate diff set status" -- "$cur") )
             ;;
         calibrate)
             COMPREPLY=( $(compgen -W "run list show apply generate-dataset" -- "$cur") )
@@ -34,7 +34,16 @@ _skillmux_completions() {
         local-vault)
             COMPREPLY=( $(compgen -W "init" -- "$cur") )
             ;;
+        --client)
+            COMPREPLY=( $(compgen -W "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -- "$cur") )
+            ;;
+        --target)
+            COMPREPLY=( $(compgen -W "agent-skills claude-code codex custom" -- "$cur") )
+            ;;
     esac
+    if [ "\${COMP_WORDS[1]}" = "init" ] && [ "\${#COMPREPLY[@]}" -eq 0 ]; then
+        COMPREPLY=( $(compgen -W "--client --target --path --vault --core --migrate-full-vault --yes --dry-run --json" -- "$cur") )
+    fi
 }
 complete -F _skillmux_completions skillmux
 `;
@@ -63,7 +72,20 @@ _skillmux() {
         'models:Manage local models'
         'completions:Generate shell completions'
     )
-    _describe -t commands 'skillmux command' commands
+    if (( CURRENT == 2 )); then
+        _describe -t commands 'skillmux command' commands
+    elif [[ "$words[2]" == "init" ]]; then
+        _arguments \
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp)' \
+          '*--target[select a target]:target:(agent-skills claude-code codex custom)' \
+          '--path[custom target directory]:directory:_directories' \
+          '--vault[vault directory]:directory:_directories' \
+          '*--core[seed a core skill]:skill id:' \
+          '--migrate-full-vault[convert a full-vault symlink to managed pins]' \
+          '--yes[apply without prompts]' \
+          '--dry-run[print the plan without writing]' \
+          '--json[emit a JSON envelope]'
+    fi
 }
 _skillmux "$@"
 `;
@@ -77,6 +99,15 @@ complete -c skillmux -n "__fish_use_subcommand" -a config -d "Manage configurati
 complete -c skillmux -n "__fish_use_subcommand" -a calibrate -d "Manage policy calibration"
 complete -c skillmux -n "__fish_use_subcommand" -a serve -d "Start MCP server"
 complete -c skillmux -n "__fish_use_subcommand" -a completions -d "Generate shell completions"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity goose hermes skillmux-mcp" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l target -x -a "agent-skills claude-code codex custom" -d "Select a target"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l path -r -d "Custom target directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l vault -r -d "Vault directory"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l core -x -d "Seed a core skill"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l migrate-full-vault -d "Convert a full-vault symlink"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l dry-run -d "Print the plan without writing"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l json -d "Emit a JSON envelope"
 `;
   }
 

package/src/config.ts

@@ -169,8 +169,7 @@ export function migrateLegacyPaths(): void {
   migrateLegacyDir("~/.cache/skill-router", "~/.cache/skillmux");
 }
 
-export async function loadConfig(path?: string): Promise<Config> {
-  migrateLegacyPaths();
+export function resolveConfigPath(path?: string): string {
   let configEnv = process.env.SKILLMUX_CONFIG;
   if (configEnv === undefined && process.env.SKILL_ROUTER_CONFIG !== undefined) {
     if (!warnedEnv.has("SKILL_ROUTER_CONFIG")) {
@@ -179,7 +178,12 @@ export async function loadConfig(path?: string): Promise<Config> {
     }
     configEnv = process.env.SKILL_ROUTER_CONFIG;
   }
-  const configPath = path ?? configEnv ?? DEFAULT_CONFIG_PATH;
+  return expandHome(path ?? configEnv ?? DEFAULT_CONFIG_PATH);
+}
+
+export async function loadConfig(path?: string): Promise<Config> {
+  migrateLegacyPaths();
+  const configPath = resolveConfigPath(path);
   const file = Bun.file(expandHome(configPath));
 
   const baseConfig = structuredClone(DEFAULTS);

package/src/init-clients.ts

@@ -0,0 +1,189 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+export const SUPPORTED_CLIENT_IDS = [
+  "claude-code",
+  "codex",
+  "gemini-cli",
+  "opencode",
+  "github-copilot",
+  "windsurf",
+  "antigravity",
+  "goose",
+  "hermes",
+  "skillmux-mcp",
+] as const;
+
+export type ClientId = (typeof SUPPORTED_CLIENT_IDS)[number];
+export type DeliveryMode = "managed-pins" | "full-vault" | "mcp";
+
+interface ClientDefinition {
+  id: ClientId;
+  surfaceId?: "agent-skills" | "claude-code" | "codex" | "antigravity";
+  deliveryMode: DeliveryMode;
+}
+
+export interface PlannedClientSurface {
+  id: string;
+  targetName: string;
+  path: string;
+  deliveryMode: "managed-pins";
+  clients: ClientId[];
+}
+
+export interface ClientSurfacePlan {
+  clients: ClientDefinition[];
+  surfaces: PlannedClientSurface[];
+}
+
+type ReadinessStatus = "ready" | "planned" | "manual" | "not-applicable";
+
+export interface ReadinessAxis {
+  status: ReadinessStatus;
+  detail: string;
+}
+
+export interface ClientReadiness {
+  client: ClientId;
+  skillSurface: ReadinessAxis;
+  mcpRegistration: ReadinessAxis;
+  instructionSetup: ReadinessAxis;
+}
+
+export interface ResolvedBuiltInTarget {
+  targetName: string;
+  path: string;
+  warning?: string;
+}
+
+const CLIENTS: Record<ClientId, ClientDefinition> = {
+  "claude-code": { id: "claude-code", surfaceId: "claude-code", deliveryMode: "managed-pins" },
+  codex: { id: "codex", surfaceId: "codex", deliveryMode: "managed-pins" },
+  "gemini-cli": { id: "gemini-cli", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
+  opencode: { id: "opencode", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
+  "github-copilot": { id: "github-copilot", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
+  windsurf: { id: "windsurf", surfaceId: "agent-skills", deliveryMode: "managed-pins" },
+  antigravity: { id: "antigravity", surfaceId: "antigravity", deliveryMode: "managed-pins" },
+  goose: { id: "goose", deliveryMode: "full-vault" },
+  hermes: { id: "hermes", deliveryMode: "full-vault" },
+  "skillmux-mcp": { id: "skillmux-mcp", deliveryMode: "mcp" },
+};
+
+function surfacePath(
+  surfaceId: NonNullable<ClientDefinition["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" || name === "agents") {
+    return {
+      targetName: name,
+      path: surfacePath("agent-skills", { home }),
+      ...(name === "agents"
+        ? { warning: "--target agents is deprecated; use --target agent-skills" }
+        : {}),
+    };
+  }
+  if (name === "claude-code" || name === "claude") {
+    return {
+      targetName: name,
+      path: surfacePath("claude-code", { home }),
+      ...(name === "claude"
+        ? { warning: "--target claude is deprecated; use --target claude-code" }
+        : {}),
+    };
+  }
+  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 planClientSurfaces(
+  requestedClients: readonly string[],
+  options: { home?: string; codexHome?: string } = {},
+): ClientSurfacePlan {
+  const clients = [...new Set(requestedClients)].map((id) => {
+    if (!SUPPORTED_CLIENT_IDS.includes(id as ClientId)) {
+      throw new Error(
+        `unsupported client "${id}"; supported clients: ${SUPPORTED_CLIENT_IDS.join(", ")}`,
+      );
+    }
+    return CLIENTS[id as ClientId];
+  });
+  const home = options.home ?? homedir();
+  const surfaces = new Map<string, PlannedClientSurface>();
+
+  for (const client of clients) {
+    if (!client.surfaceId) continue;
+    const path = surfacePath(client.surfaceId, { home, codexHome: options.codexHome });
+    const existing = surfaces.get(path);
+    if (existing) {
+      if (!existing.clients.includes(client.id)) existing.clients.push(client.id);
+      continue;
+    }
+    surfaces.set(path, {
+      id: client.surfaceId,
+      targetName: client.surfaceId,
+      path,
+      deliveryMode: "managed-pins",
+      clients: [client.id],
+    });
+  }
+
+  return { clients, surfaces: [...surfaces.values()] };
+}
+
+export function assessClientReadiness(
+  plan: ClientSurfacePlan,
+  instructionReadiness: Partial<Record<ClientId, ReadinessAxis>> = {},
+): ClientReadiness[] {
+  return plan.clients.map((client) => {
+    const surface = plan.surfaces.find((candidate) => candidate.clients.includes(client.id));
+    let skillSurface: ReadinessAxis;
+    if (surface) {
+      skillSurface = { status: "planned", detail: surface.path };
+    } else if (client.id === "goose") {
+      skillSurface = { status: "manual", detail: "configure the full vault in Goose" };
+    } else if (client.id === "hermes") {
+      skillSurface = { status: "manual", detail: "configure the full vault in Hermes external_dirs" };
+    } else {
+      skillSurface = {
+        status: "not-applicable",
+        detail: "skills resolve through Skillmux MCP",
+      };
+    }
+
+    const mcpRegistration: ReadinessAxis = client.deliveryMode === "mcp"
+      ? { status: "manual", detail: "register the Skillmux MCP server" }
+      : { status: "not-applicable", detail: "native skill loading" };
+
+    return {
+      client: client.id,
+      skillSurface,
+      mcpRegistration,
+      instructionSetup: instructionReadiness[client.id] ?? {
+        status: "manual",
+        detail: "instruction adapter not applied",
+      },
+    };
+  });
+}

package/src/init-instructions.ts

@@ -0,0 +1,173 @@
+import {
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, join } from "node:path";
+import { DISCOVERY_PARAGRAPH } from "./init";
+import type { ClientId } from "./init-clients";
+
+export const INSTRUCTION_BLOCK_START = "<!-- skillmux:discovery:start -->";
+export const INSTRUCTION_BLOCK_END = "<!-- skillmux:discovery:end -->";
+
+const MANAGED_BLOCK = [
+  INSTRUCTION_BLOCK_START,
+  DISCOVERY_PARAGRAPH,
+  INSTRUCTION_BLOCK_END,
+].join("\n");
+
+export interface InstructionChange {
+  path: string;
+  clients: ClientId[];
+  status: "create" | "update" | "unchanged";
+  before: string | null;
+  after: string;
+}
+
+export interface InstructionPlan {
+  changes: InstructionChange[];
+  manual: Array<{ client: ClientId; reason: string }>;
+}
+
+interface InstructionPlanOptions {
+  home?: string;
+  codexHome?: string;
+  claudeConfigDir?: string;
+  readFile?: (path: string) => string | null;
+}
+
+function instructionPath(
+  client: ClientId,
+  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;
+}
+
+function readInstructionFile(path: string): string | null {
+  try {
+    const stat = lstatSync(path);
+    if (stat.isSymbolicLink()) {
+      throw new Error(`instruction file is a symbolic link and will not be modified: ${path}`);
+    }
+    if (!stat.isFile()) throw new Error(`instruction path is not a file: ${path}`);
+    return readFileSync(path, "utf8");
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+    throw error;
+  }
+}
+
+function withManagedBlock(existing: string | null, path: string): string {
+  if (existing === null || existing.length === 0) return `${MANAGED_BLOCK}\n`;
+
+  const starts = existing.split(INSTRUCTION_BLOCK_START).length - 1;
+  const ends = existing.split(INSTRUCTION_BLOCK_END).length - 1;
+  if (starts === 0 && ends === 0) return `${existing.trimEnd()}\n\n${MANAGED_BLOCK}\n`;
+  if (starts !== 1 || ends !== 1) {
+    throw new Error(`instruction file has a malformed skillmux managed block: ${path}`);
+  }
+
+  const start = existing.indexOf(INSTRUCTION_BLOCK_START);
+  const end = existing.indexOf(INSTRUCTION_BLOCK_END, start);
+  if (end < start) throw new Error(`instruction file has a malformed skillmux managed block: ${path}`);
+  return `${existing.slice(0, start)}${MANAGED_BLOCK}${existing.slice(end + INSTRUCTION_BLOCK_END.length)}`;
+}
+
+export function planInstructionSetup(
+  requestedClients: readonly ClientId[],
+  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"),
+  };
+  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);
+    if (!path) {
+      manual.push({ client, reason: "no safe durable user instruction file is known" });
+      continue;
+    }
+    const existingChange = changesByPath.get(path);
+    if (existingChange) {
+      existingChange.clients.push(client);
+      continue;
+    }
+
+    const before = readFile(path);
+    const after = withManagedBlock(before, path);
+    changesByPath.set(path, {
+      path,
+      clients: [client],
+      status: before === null ? "create" : before === after ? "unchanged" : "update",
+      before,
+      after,
+    });
+  }
+
+  return { changes: [...changesByPath.values()], manual };
+}
+
+function atomicWrite(path: string, content: string, mode: number): void {
+  mkdirSync(dirname(path), { recursive: true });
+  const temporaryPath = `${path}.${process.pid}.${crypto.randomUUID()}.tmp`;
+  try {
+    writeFileSync(temporaryPath, content, { encoding: "utf8", mode });
+    renameSync(temporaryPath, path);
+  } finally {
+    rmSync(temporaryPath, { force: true });
+  }
+}
+
+export function applyInstructionPlan(plan: InstructionPlan): void {
+  for (const change of plan.changes) {
+    if (change.status === "unchanged") continue;
+    if (readInstructionFile(change.path) !== change.before) {
+      throw new Error(`instruction file changed after planning: ${change.path}`);
+    }
+  }
+
+  const applied: InstructionChange[] = [];
+  try {
+    for (const change of plan.changes) {
+      if (change.status === "unchanged") continue;
+      const mode = change.before === null ? 0o600 : statSync(change.path).mode;
+      atomicWrite(change.path, change.after, mode);
+      applied.push(change);
+    }
+  } catch (error) {
+    rollbackInstructionChanges(applied);
+    throw error;
+  }
+}
+
+function rollbackInstructionChanges(changes: InstructionChange[]): void {
+  for (const change of [...changes].reverse()) {
+    if (change.before === null) {
+      rmSync(change.path, { force: true });
+    } else {
+      atomicWrite(change.path, change.before, statSync(change.path).mode);
+    }
+  }
+}
+
+export function rollbackInstructionPlan(plan: InstructionPlan): void {
+  rollbackInstructionChanges(plan.changes.filter((change) => change.status !== "unchanged"));
+}