@vovy-ai/host-detect 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vovy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Every path-touching function takes an explicit `DetectEnv` instead of reading
+ * `process.env`/`os.homedir()` directly. That's what lets tests redirect `home`/`cwd`
+ * to a throwaway `os.tmpdir()` and snapshot exactly what would be written, without ever
+ * touching the real machine's dotfiles.
+ */
+interface DetectEnv {
+    home: string;
+    cwd: string;
+    platform: NodeJS.Platform;
+}
+type SkillScope = "user" | "project";
+interface McpServerEntry {
+    /** Server id/key as it should appear in the host's config, e.g. "vovy". */
+    id: string;
+    command: string;
+    args: string[];
+}
+interface HostAdapter {
+    /** Stable id, used with `--host <id>` and in test fixtures. */
+    id: string;
+    /** Human-readable name shown in CLI output. */
+    label: string;
+    /**
+     * Best-effort signal that this host tool is installed/configured on this machine.
+     * Should never throw — return false on any uncertainty rather than guessing.
+     */
+    detect(env: DetectEnv): boolean;
+    /**
+     * Absolute path Vovy should write the skill identified by `skillId` to, for this host
+     * at the given scope. Hosts differ on convention — some use a folder-per-skill with a
+     * fixed filename (Claude Code/Codex: `<dir>/<skillId>/SKILL.md`), others use one flat
+     * file per skill (Cline/Windsurf: `<dir>/<skillId>.md`) — so this returns the full path
+     * rather than exposing a directory + fixed filename that wouldn't fit both shapes.
+     */
+    skillFilePath(env: DetectEnv, scope: SkillScope, skillId: string): string;
+    /**
+     * Path to this host's MCP server config file, or null if this host is skills-only
+     * (no MCP registration support/needed).
+     */
+    mcpConfigPath(env: DetectEnv, scope: SkillScope): string | null;
+    /**
+     * Merge `entry` into the raw contents of an existing config file (`existing`, undefined
+     * if the file doesn't exist yet) and return the full new file contents to write.
+     * Must be idempotent — merging the same entry twice produces the same result as once.
+     */
+    mergeMcpConfig(existing: string | undefined, entry: McpServerEntry): string;
+}
+/**
+ * Adapters that are fully verified against the host's official documentation and are
+ * safe to auto-detect by default.
+ */
+declare const VERIFIED_ADAPTER_IDS: readonly ["claude-code", "codex"];
+
+/**
+ * Claude Code — Agent Skills at `~/.claude/skills/<id>/SKILL.md` (personal, user scope)
+ * or `.claude/skills/<id>/SKILL.md` (project scope, committed to the repo). Project-scoped
+ * MCP servers register in a `.mcp.json` file at the project root.
+ * https://code.claude.com/docs/en/skills
+ */
+declare const claudeCodeAdapter: HostAdapter;
+
+/**
+ * Codex CLI — Agent Skills at `.agents/skills/<id>/SKILL.md`, scanned from the current
+ * directory up to the repo root for project scope, plus a user-level location for
+ * personal skills. MCP servers register as `[mcp_servers.<id>]` tables in `config.toml`.
+ * https://developers.openai.com/codex/skills
+ *
+ * The project-scope skill path is directly confirmed by Codex's own docs. The user-scope
+ * skill path below (`~/.codex/skills/`) mirrors the confirmed location of `config.toml`
+ * but has not been independently verified against a live install — flagged in
+ * docs/host-support-matrix.md as a good first contribution to confirm/fix.
+ */
+declare const codexAdapter: HostAdapter;
+/**
+ * Removes a `[mcp_servers.<id>]` table block from a Codex `config.toml`. Deliberately
+ * conservative: only strips the block this adapter would itself have written, leaving
+ * everything else in a hand-edited TOML file untouched. Returns `null` if the table isn't
+ * present, so the caller can skip writing.
+ */
+declare function removeCodexMcpEntry(existing: string | undefined, id: string): string | null;
+
+/**
+ * Cursor — project rules live at `.cursor/rules/<id>.mdc`; MCP servers register in
+ * `.cursor/mcp.json` (project scope) or `~/.cursor/mcp.json` (global scope), both using
+ * the same `{ "mcpServers": {...} }` shape as Claude Code. https://docs.cursor.com/context/mcp
+ *
+ * BEST EFFORT: Cursor also ships a newer native "Skills" concept alongside Rules as of
+ * mid-2026, but its exact on-disk convention wasn't independently confirmed during
+ * research. This adapter targets the older, well-documented `.mdc` Rules mechanism,
+ * which Cursor's own agent loop reliably picks up. If you can confirm Cursor's Skills
+ * path, that's a great first PR — see docs/host-support-matrix.md.
+ */
+declare const cursorAdapter: HostAdapter;
+
+/**
+ * Cline — project instructions live as flat markdown files under `.clinerules/`, one
+ * file per concern rather than Claude/Codex's folder-per-skill convention; Cline's own
+ * agent loop reads every file in that directory as always-on context.
+ *
+ * BEST EFFORT: Cline is a VS Code extension, not a standalone CLI/config-dir tool, so
+ * there's no reliable filesystem signal to auto-detect it's installed — `detect()` here
+ * always returns false, meaning Cline is only set up via an explicit `--host cline` flag,
+ * never silently. MCP registration is intentionally unimplemented for v0.1 (Cline's MCP
+ * config lives inside VS Code's extension storage, which varies by OS/VS Code variant
+ * and wasn't independently confirmed) — the `.clinerules/` skill file alone is enough for
+ * Cline's agent loop to pick up Vovy's skills. See docs/host-support-matrix.md.
+ */
+declare const clineAdapter: HostAdapter;
+
+/**
+ * Windsurf — project rules live as flat markdown files under `.windsurf/rules/`, read by
+ * Cascade (Windsurf's agent) as always-on context, similar in shape to Cline's convention.
+ * Global config, including MCP servers, lives under `~/.codeium/windsurf/`.
+ *
+ * BEST EFFORT: the exact MCP config filename/shape below was not independently confirmed
+ * against a live Windsurf install during research — flagged in
+ * docs/host-support-matrix.md as a good first contribution to verify/fix.
+ */
+declare const windsurfAdapter: HostAdapter;
+
+/** Every adapter Vovy ships, in the order they're listed in CLI output. */
+declare const ADAPTERS: HostAdapter[];
+declare function getAdapter(id: string): HostAdapter;
+
+/**
+ * Inverse of `mergeJsonMcpConfig`: removes only the `mcpServers.<id>` entry, leaving every
+ * other key untouched. Returns `null` when there's nothing to do (file missing, not valid
+ * JSON, or the entry was never present) so callers can skip writing rather than risk
+ * clobbering a file they don't understand.
+ */
+declare function removeJsonMcpEntry(existing: string | undefined, id: string): string | null;
+
+type WriteAction = "created" | "updated" | "unchanged";
+interface WriteResult {
+    path: string;
+    action: WriteAction;
+    /** True if this result came from a dry run — `action` reflects what *would* happen,
+     * nothing was actually written to disk. */
+    dryRun: boolean;
+}
+interface WriteSkillOptions {
+    adapter: HostAdapter;
+    env: DetectEnv;
+    scope: SkillScope;
+    skillId: string;
+    content: string;
+    dryRun?: boolean;
+}
+declare function writeSkillFile(opts: WriteSkillOptions): WriteResult;
+interface WriteMcpConfigOptions {
+    adapter: HostAdapter;
+    env: DetectEnv;
+    scope: SkillScope;
+    entry: McpServerEntry;
+    dryRun?: boolean;
+}
+declare function writeMcpConfig(opts: WriteMcpConfigOptions): WriteResult | null;
+
+export { ADAPTERS, type DetectEnv, type HostAdapter, type McpServerEntry, type SkillScope, VERIFIED_ADAPTER_IDS, type WriteAction, type WriteMcpConfigOptions, type WriteResult, type WriteSkillOptions, claudeCodeAdapter, clineAdapter, codexAdapter, cursorAdapter, getAdapter, removeCodexMcpEntry, removeJsonMcpEntry, windsurfAdapter, writeMcpConfig, writeSkillFile };

package/dist/index.js

@@ -0,0 +1,237 @@
+// src/adapters/claude-code.ts
+import { existsSync } from "fs";
+import { join } from "path";
+
+// src/json-mcp-config.ts
+function mergeJsonMcpConfig(existing, entry) {
+  let config = {};
+  if (existing?.trim()) {
+    try {
+      const parsed = JSON.parse(existing);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        config = parsed;
+      }
+    } catch {
+      throw new Error(
+        "Existing MCP config is not valid JSON \u2014 refusing to overwrite it. Please fix or remove it and re-run `vovy install`."
+      );
+    }
+  }
+  const existingServers = config.mcpServers && typeof config.mcpServers === "object" && !Array.isArray(config.mcpServers) ? config.mcpServers : {};
+  config.mcpServers = {
+    ...existingServers,
+    [entry.id]: {
+      command: entry.command,
+      args: entry.args
+    }
+  };
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
+function removeJsonMcpEntry(existing, id) {
+  if (!existing?.trim()) return null;
+  let config;
+  try {
+    const parsed = JSON.parse(existing);
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return null;
+    config = parsed;
+  } catch {
+    return null;
+  }
+  const servers = config.mcpServers;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers) || !(id in servers)) {
+    return null;
+  }
+  const { [id]: _removed, ...rest } = servers;
+  config.mcpServers = Object.keys(rest).length > 0 ? rest : void 0;
+  return `${JSON.stringify(config, null, 2)}
+`;
+}
+
+// src/adapters/claude-code.ts
+var claudeCodeAdapter = {
+  id: "claude-code",
+  label: "Claude Code",
+  detect(env) {
+    return existsSync(join(env.home, ".claude"));
+  },
+  skillFilePath(env, scope, skillId) {
+    const base = scope === "user" ? join(env.home, ".claude") : join(env.cwd, ".claude");
+    return join(base, "skills", skillId, "SKILL.md");
+  },
+  mcpConfigPath(env, scope) {
+    return scope === "user" ? join(env.home, ".claude", "mcp.json") : join(env.cwd, ".mcp.json");
+  },
+  mergeMcpConfig: mergeJsonMcpConfig
+};
+
+// src/adapters/cline.ts
+import "fs";
+import { join as join2 } from "path";
+var clineAdapter = {
+  id: "cline",
+  label: "Cline",
+  detect(_env) {
+    return false;
+  },
+  skillFilePath(env, scope, skillId) {
+    const base = scope === "user" ? join2(env.home, ".clinerules") : join2(env.cwd, ".clinerules");
+    return join2(base, `${skillId}.md`);
+  },
+  mcpConfigPath(_env, _scope) {
+    return null;
+  },
+  mergeMcpConfig(_existing) {
+    throw new Error("Cline MCP config registration is not yet supported \u2014 skill files only.");
+  }
+};
+
+// src/adapters/codex.ts
+import { existsSync as existsSync3 } from "fs";
+import { join as join3 } from "path";
+var codexAdapter = {
+  id: "codex",
+  label: "Codex CLI",
+  detect(env) {
+    return existsSync3(join3(env.home, ".codex"));
+  },
+  skillFilePath(env, scope, skillId) {
+    const base = scope === "user" ? join3(env.home, ".codex", "skills") : join3(env.cwd, ".agents", "skills");
+    return join3(base, skillId, "SKILL.md");
+  },
+  mcpConfigPath(env) {
+    return join3(env.home, ".codex", "config.toml");
+  },
+  mergeMcpConfig(existing, entry) {
+    const tableHeader = `[mcp_servers.${entry.id}]`;
+    const base = existing ?? "";
+    const argsToml = entry.args.map((a) => JSON.stringify(a)).join(", ");
+    const block = `${tableHeader}
+command = ${JSON.stringify(entry.command)}
+args = [${argsToml}]
+`;
+    const found = findTableBlock(base, tableHeader);
+    if (found) {
+      const currentBlock = base.slice(found.start, found.end);
+      if (currentBlock.trim() === block.trim()) return base;
+      return base.slice(0, found.start) + block + base.slice(found.end);
+    }
+    const separator = base.length > 0 && !base.endsWith("\n\n") ? base.endsWith("\n") ? "\n" : "\n\n" : "";
+    return `${base}${separator}${block}`;
+  }
+};
+function findTableBlock(text, header) {
+  const start = text.indexOf(header);
+  if (start === -1) return null;
+  const rest = text.slice(start + header.length);
+  const nextHeaderMatch = rest.match(/\n\[/);
+  const end = nextHeaderMatch?.index != null ? start + header.length + nextHeaderMatch.index + 1 : text.length;
+  return { start, end };
+}
+function removeCodexMcpEntry(existing, id) {
+  if (!existing) return null;
+  const found = findTableBlock(existing, `[mcp_servers.${id}]`);
+  if (!found) return null;
+  return existing.slice(0, found.start) + existing.slice(found.end);
+}
+
+// src/adapters/cursor.ts
+import { existsSync as existsSync4 } from "fs";
+import { join as join4 } from "path";
+var cursorAdapter = {
+  id: "cursor",
+  label: "Cursor",
+  detect(env) {
+    return existsSync4(join4(env.home, ".cursor"));
+  },
+  skillFilePath(env, scope, skillId) {
+    const base = scope === "user" ? join4(env.home, ".cursor") : join4(env.cwd, ".cursor");
+    return join4(base, "rules", `${skillId}.mdc`);
+  },
+  mcpConfigPath(env, scope) {
+    return scope === "user" ? join4(env.home, ".cursor", "mcp.json") : join4(env.cwd, ".cursor", "mcp.json");
+  },
+  mergeMcpConfig: mergeJsonMcpConfig
+};
+
+// src/adapters/windsurf.ts
+import { existsSync as existsSync5 } from "fs";
+import { join as join5 } from "path";
+var windsurfAdapter = {
+  id: "windsurf",
+  label: "Windsurf",
+  detect(env) {
+    return existsSync5(join5(env.home, ".codeium", "windsurf"));
+  },
+  skillFilePath(env, scope, skillId) {
+    const base = scope === "user" ? join5(env.home, ".codeium", "windsurf") : join5(env.cwd, ".windsurf");
+    return join5(base, "rules", `${skillId}.md`);
+  },
+  mcpConfigPath(env, _scope) {
+    return join5(env.home, ".codeium", "windsurf", "mcp_config.json");
+  },
+  mergeMcpConfig: mergeJsonMcpConfig
+};
+
+// src/adapters/index.ts
+var ADAPTERS = [
+  claudeCodeAdapter,
+  codexAdapter,
+  cursorAdapter,
+  clineAdapter,
+  windsurfAdapter
+];
+function getAdapter(id) {
+  const adapter = ADAPTERS.find((a) => a.id === id);
+  if (!adapter) {
+    throw new Error(
+      `Unknown host id "${id}". Known hosts: ${ADAPTERS.map((a) => a.id).join(", ")}`
+    );
+  }
+  return adapter;
+}
+
+// src/types.ts
+var VERIFIED_ADAPTER_IDS = ["claude-code", "codex"];
+
+// src/write.ts
+import { existsSync as existsSync6, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { dirname } from "path";
+function writeSkillFile(opts) {
+  const path = opts.adapter.skillFilePath(opts.env, opts.scope, opts.skillId);
+  const existing = existsSync6(path) ? readFileSync(path, "utf8") : void 0;
+  const action = existing === opts.content ? "unchanged" : existing === void 0 ? "created" : "updated";
+  const dryRun = opts.dryRun ?? false;
+  if (!dryRun && action !== "unchanged") {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, opts.content, "utf8");
+  }
+  return { path, action, dryRun };
+}
+function writeMcpConfig(opts) {
+  const path = opts.adapter.mcpConfigPath(opts.env, opts.scope);
+  if (!path) return null;
+  const existing = existsSync6(path) ? readFileSync(path, "utf8") : void 0;
+  const next = opts.adapter.mergeMcpConfig(existing, opts.entry);
+  const action = existing === next ? "unchanged" : existing === void 0 ? "created" : "updated";
+  const dryRun = opts.dryRun ?? false;
+  if (!dryRun && action !== "unchanged") {
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, next, "utf8");
+  }
+  return { path, action, dryRun };
+}
+export {
+  ADAPTERS,
+  VERIFIED_ADAPTER_IDS,
+  claudeCodeAdapter,
+  clineAdapter,
+  codexAdapter,
+  cursorAdapter,
+  getAdapter,
+  removeCodexMcpEntry,
+  removeJsonMcpEntry,
+  windsurfAdapter,
+  writeMcpConfig,
+  writeSkillFile
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@vovy-ai/host-detect",
+  "version": "0.1.0",
+  "description": "Per-host detection and safe config writing for Vovy: Claude Code, Codex CLI, Cursor, Cline, Windsurf.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean",
+    "dev": "tsup src/index.ts --format esm --dts --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  }
+}