@klhapp/skillmux 0.4.5 → 0.6.0

package/src/completions.ts

@@ -8,7 +8,7 @@ _skillmux_completions() {
     COMPREPLY=()
     cur="\${COMP_WORDS[COMP_CWORD]}"
     prev="\${COMP_WORDS[COMP_CWORD-1]}"
-    opts="context config calibrate serve index sync init report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
+    opts="context config calibrate serve index sync init project target report scan install eval doctor which manifest local-vault models completions --context --server --json --allow-insecure --verbose --dry-run --help"
 
     if [ "$COMP_CWORD" -eq 1 ]; then
         COMPREPLY=( $(compgen -W "$opts" -- "$cur") )
@@ -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") )
@@ -31,10 +31,28 @@ _skillmux_completions() {
         manifest)
             COMPREPLY=( $(compgen -W "pin unpin" -- "$cur") )
             ;;
+        project)
+            COMPREPLY=( $(compgen -W "init list show add-path remove-path pin unpin attach detach" -- "$cur") )
+            ;;
+        target)
+            COMPREPLY=( $(compgen -W "list show add remove" -- "$cur") )
+            ;;
         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 --no-instructions --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
+    if [ "\${COMP_WORDS[1]}" = "project" ] && [ "\${COMP_WORDS[2]}" = "init" ]; then
+        COMPREPLY=( $(compgen -W "--name --skill --client --target --no-sync --interactive --yes --dry-run --json" -- "$cur") )
+    fi
 }
 complete -F _skillmux_completions skillmux
 `;
@@ -52,6 +70,8 @@ _skillmux() {
         'index:Rebuild local search index'
         'sync:Synchronize vault skills'
         'init:Initialize project targets'
+        'project:Configure project-scoped skills'
+        'target:Manage advanced skill-delivery targets'
         'report:Generate usage stats'
         'scan:Audit skills for issues'
         'install:Install skills into vault'
@@ -63,7 +83,39 @@ _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]' \
+          '--no-instructions[skip managed instruction files]' \
+          '--no-sync[save setup without synchronizing targets]' \
+          '--interactive[force guided setup]' \
+          '--yes[apply without prompts]' \
+          '--dry-run[print the plan without writing]' \
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "project" && "$words[3]" == "init" ]]; then
+        _arguments \
+          '1:project directory:_directories' \
+          '--name[project group name]:group:' \
+          '*--skill[project skill]:skill id:' \
+          '*--client[select a client]:client:(claude-code codex gemini-cli opencode github-copilot windsurf antigravity)' \
+          '*--target[select an advanced target]:target:' \
+          '--no-sync[save setup without synchronizing targets]' \
+          '--interactive[force guided setup]' \
+          '--yes[apply without prompts]' \
+          '--dry-run[print the plan without writing]' \
+          '--json[emit a JSON envelope]'
+    elif [[ "$words[2]" == "project" && CURRENT == 3 ]]; then
+        _values 'project command' init list show add-path remove-path pin unpin attach detach
+    elif [[ "$words[2]" == "target" && CURRENT == 3 ]]; then
+        _values 'target command' list show add remove
+    fi
 }
 _skillmux "$@"
 `;
@@ -76,7 +128,31 @@ complete -c skillmux -n "__fish_use_subcommand" -a context -d "Manage connection
 complete -c skillmux -n "__fish_use_subcommand" -a config -d "Manage configuration"
 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 init -d "Configure this machine and its clients"
+complete -c skillmux -n "__fish_use_subcommand" -a project -d "Configure project-scoped skills"
+complete -c skillmux -n "__fish_use_subcommand" -a target -d "Manage advanced skill-delivery targets"
 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 no-instructions -d "Skip managed instruction files"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l no-sync -d "Save without synchronizing"
+complete -c skillmux -n "__fish_seen_subcommand_from init" -l interactive -d "Force guided setup"
+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"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -a "init list show add-path remove-path pin unpin attach detach" -d "Manage projects"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l name -x -d "Project group name"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l skill -x -d "Project skill"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l client -x -a "claude-code codex gemini-cli opencode github-copilot windsurf antigravity" -d "Select a client"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l target -x -d "Select an advanced target"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l no-sync -d "Save without synchronizing"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l interactive -d "Force guided setup"
+complete -c skillmux -n "__fish_seen_subcommand_from project" -l yes -d "Apply without prompts"
+complete -c skillmux -n "__fish_seen_subcommand_from target" -a "list show add remove" -d "Manage targets"
 `;
   }
 

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,220 @@
+import { existsSync } from "node:fs";
+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";
+
+export interface DetectedClient {
+  client: ClientId;
+  evidence: string;
+}
+
+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" },
+};
+
+export function detectInstalledClients(
+  options: {
+    home?: string;
+    codexHome?: string;
+    exists?: (path: string) => boolean;
+  } = {},
+): DetectedClient[] {
+  const home = options.home ?? homedir();
+  const codexHome = options.codexHome ?? join(home, ".codex");
+  const exists = options.exists ?? existsSync;
+  const candidates: Array<[ClientId, string]> = [
+    ["claude-code", join(home, ".claude")],
+    ["codex", codexHome],
+    ["gemini-cli", join(home, ".gemini")],
+    ["opencode", join(home, ".config", "opencode")],
+    ["github-copilot", join(home, ".config", "github-copilot")],
+    ["windsurf", join(home, ".codeium", "windsurf")],
+    ["goose", join(home, ".config", "goose")],
+    ["hermes", join(home, ".hermes")],
+  ];
+  return candidates
+    .filter(([, evidence]) => exists(evidence))
+    .map(([client, evidence]) => ({ client, evidence }));
+}
+
+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"));
+}