@vruum/skills-operator 0.1.1 → 0.1.3

package/README.md

@@ -1,6 +1,6 @@
 # @vruum/skills-operator
 
-OAuth-gated installer for the Vruum operator skill bundle. If you're a Vruum operator (an account that owns 2+ companies in Vruum), this gives you the 11 operator skills for Claude Code / Codex CLI with one command — no private GitHub access required.
+OAuth-gated installer for the Vruum operator skill bundle. If you're a Vruum operator (an account that owns 2+ companies in Vruum), this gives you the 12 operator skills for Claude Code / Codex CLI with one command — no private GitHub access required.
 
 ```bash
 npx @vruum/skills-operator install
@@ -12,7 +12,7 @@ npx @vruum/skills-operator install
 2. Saves the session to `~/.vruum/auth.json` (mode 0600).
 3. Downloads the latest operator skill tarball from `api.vruum.ai` (server verifies your operator role on every request).
 4. Extracts to `~/.vruum/skills-operator/<sha>/`, updates `~/.vruum/skills-operator/current → <sha>/`.
-5. Symlinks each skill into `~/.claude/skills/` and `~/.codex/skills/` via `current/` so rollback is atomic.
+5. Symlinks each skill into `~/.claude/skills/` and `~/.agents/skills/` via `current/` so rollback is atomic.
 
 ## Commands
 
@@ -47,7 +47,26 @@ Set `telemetry: community` (or `anonymous`) in `~/.vruum/config.yaml` to help su
 
 ## Pairs with
 
-The Vruum MCP server at `https://api.vruum.ai/mcp`. Slash commands in your AI assistant turn into specialized workflows there.
+The Vruum MCP server at `https://api.vruum.ai/mcp`. The installed skills run as local workflows in your AI assistant; the MCP server provides the tools (including the `skill` tool, action=invoke) and data those workflows call.
+
+**Register the MCP server in your assistant** (one-time, after install):
+
+- **Claude Code** — add to `~/.claude.json`:
+  ```json
+  "mcpServers": {
+    "vruum-local": { "type": "http", "url": "https://api.vruum.ai/mcp" }
+  }
+  ```
+
+- **Codex CLI** — add to `~/.codex/config.toml`:
+  ```toml
+  [mcp_servers.vruum-local]
+  url = "https://api.vruum.ai/mcp"
+  ```
+
+- **Other assistants** — connect to `https://api.vruum.ai/mcp` (HTTP transport, OAuth via standard MCP flow).
+
+After registration, restart your assistant. Tools like `mcp__vruum-local__get_outreach_review` should appear in your tool list.
 
 ## Issues
 

package/install.js

@@ -25,7 +25,7 @@
  *   - 300s listener timeout (enterprise SSO + MFA headroom).
  *   - Per-SHA subdirs under ~/.vruum/skills-operator/<sha>/.
  *   - `current` symlink sits alongside; skills in ~/.claude/skills/ and
- *     ~/.codex/skills/ point THROUGH current/ so rollback is one rename.
+ *     ~/.agents/skills/ point THROUGH current/ so rollback is one rename.
  *   - Windows without admin/dev-mode falls back to file copy + explicit message.
  *   - Lock file `.install.lock` contains PID; stale PID (`kill -0` fails) is
  *     reclaimed; live PID refuses.
@@ -69,8 +69,11 @@ const CONFIG_FILE = path.join(VRUUM_ROOT, 'config.yaml');
 const SESSION_ID = crypto.randomUUID();
 
 const HARNESSES = [
-  { name: 'Claude Code', dir: path.join(os.homedir(), '.claude', 'skills') },
-  { name: 'Codex CLI',   dir: path.join(os.homedir(), '.codex',  'skills') },
+  // `detect` = the harness config dir (its presence means the harness is
+  // installed); `dir` = where that harness reads skills. Codex reads the
+  // agentskills.io standard dir ~/.agents/skills (not ~/.codex/skills).
+  { name: 'Claude Code', detect: path.join(os.homedir(), '.claude'), dir: path.join(os.homedir(), '.claude', 'skills') },
+  { name: 'Codex CLI',   detect: path.join(os.homedir(), '.codex'),  dir: path.join(os.homedir(), '.agents', 'skills') },
 ];
 
 // ─── Arg parsing ────────────────────────────────────────────────────────────
@@ -587,6 +590,72 @@ function linkSkill({ name, srcAbs, targetDir, force }) {
   }
 }
 
+// A harness symlink is "ours" if its target resolves under
+// ~/.vruum/skills-operator/ (skills are linked THROUGH current/). Boundary-safe:
+// equality OR startsWith(OPERATOR_ROOT + path.sep) — never a substring
+// `.includes`, so siblings like ~/.vruum/skills-operator-backup/… or
+// /tmp/my-skills-operator-notes/… are NOT matched, and the public installer's
+// ~/.vruum/skills/ links are excluded too. Resolved textually so a dangling
+// target (the renamed-skill bug case) is still recognized.
+function isOperatorLink(linkTarget) {
+  const resolved = path.resolve(linkTarget);
+  return resolved === OPERATOR_ROOT || resolved.startsWith(OPERATOR_ROOT + path.sep);
+}
+
+// Remove links for skills no longer in the bundle (renamed/removed), but only
+// symlinks this installer owns — never non-symlinks or foreign/public links.
+function pruneStaleLinks({ targetDir, skillNames }) {
+  const results = [];
+  let entries;
+  try {
+    entries = fs.readdirSync(targetDir);
+  } catch (err) {
+    if (err.code === 'ENOENT') return results;
+    throw err;
+  }
+  const current = new Set(skillNames);
+  for (const entry of entries) {
+    if (current.has(entry)) continue; // current skill — keep
+    const dst = path.join(targetDir, entry);
+    let linkTarget;
+    try {
+      const lstat = fs.lstatSync(dst);
+      if (!lstat.isSymbolicLink()) continue; // never touch non-symlinks
+      linkTarget = fs.readlinkSync(dst);
+    } catch (err) {
+      if (err.code === 'ENOENT') continue;
+      throw err;
+    }
+    if (!isOperatorLink(linkTarget)) continue; // foreign symlink — keep
+    fs.unlinkSync(dst);
+    results.push({ name: entry, action: 'pruned' });
+  }
+  return results;
+}
+
+// Link each current skill into every detected harness, then prune our stale
+// links. Called from doInstall (both the fresh-install path AND the
+// already-up-to-date early return, so upgrading to this fixed installer
+// reconciles on an unchanged SHA) and from doRollback (so rolling back to a
+// build that lacks a newer skill prunes that now-dangling link).
+function reconcileHarnessLinks({ skillsDir, skillNames, force = false }) {
+  for (const { name: harnessName, detect, dir: targetDirForHarness } of HARNESSES) {
+    if (!fs.existsSync(detect)) continue;
+    fs.mkdirSync(targetDirForHarness, { recursive: true });
+    const results = [];
+    for (const skillName of skillNames) {
+      const srcAbs = path.join(skillsDir, skillName);
+      results.push(linkSkill({ name: skillName, srcAbs, targetDir: targetDirForHarness, force }));
+    }
+    const linked = results.filter((r) => ['linked', 'relinked', 'copied', 'already-linked'].includes(r.action)).length;
+    const skipped = results.filter((r) => r.action === 'skipped');
+    console.log(`${harnessName}: ${linked}/${skillNames.length} skills ready`);
+    for (const s of skipped) console.log(`  skipped ${s.name} — ${s.reason}`);
+    const pruned = pruneStaleLinks({ targetDir: targetDirForHarness, skillNames });
+    for (const p of pruned) console.log(`  pruned ${p.name} (stale skill link)`);
+  }
+}
+
 function copyUpdateCheckShim() {
   fs.mkdirSync(BIN_DIR, { recursive: true });
   const src = path.join(__dirname, 'bin', 'vruum-skills-operator-update-check');
@@ -627,6 +696,15 @@ async function doInstall({ force = false } = {}) {
     const currentSha = fs.existsSync(VERSION_FILE) ? fs.readFileSync(VERSION_FILE, 'utf8').trim() : null;
     if (currentSha === sha) {
       console.log(`already up to date (sha=${sha})`);
+      // Still reconcile harness links: upgrading to this fixed installer must
+      // prune stale renamed-skill links even when the SHA hasn't moved.
+      const skillsDir = path.join(CURRENT_LINK, 'skills');
+      if (fs.existsSync(skillsDir)) {
+        const skillNames = fs.readdirSync(skillsDir, { withFileTypes: true })
+          .filter((d) => d.isDirectory())
+          .map((d) => d.name);
+        reconcileHarnessLinks({ skillsDir, skillNames, force });
+      }
       return;
     }
 
@@ -695,18 +773,7 @@ async function doInstall({ force = false } = {}) {
       .filter((d) => d.isDirectory())
       .map((d) => d.name);
 
-    for (const { name: harnessName, dir: targetDirForHarness } of HARNESSES) {
-      if (!fs.existsSync(targetDirForHarness)) continue;
-      const results = [];
-      for (const skillName of skillNames) {
-        const srcAbs = path.join(skillsDir, skillName);
-        results.push(linkSkill({ name: skillName, srcAbs, targetDir: targetDirForHarness, force }));
-      }
-      const linked = results.filter((r) => ['linked', 'relinked', 'copied', 'already-linked'].includes(r.action)).length;
-      const skipped = results.filter((r) => r.action === 'skipped');
-      console.log(`${harnessName}: ${linked}/${skillNames.length} skills ready`);
-      for (const s of skipped) console.log(`  skipped ${s.name} — ${s.reason}`);
-    }
+    reconcileHarnessLinks({ skillsDir, skillNames, force });
 
     fs.writeFileSync(VERSION_FILE, sha);
 
@@ -780,6 +847,17 @@ function doRollback({ to }) {
     fail(`failed to flip current symlink: ${e.message}`, 'rollback', 'SymlinkError');
   }
   fs.writeFileSync(VERSION_FILE, targetSha);
+
+  // Reconcile harness links to the rolled-back build: a skill that existed only
+  // in the build we rolled away from now dangles, so prune it.
+  const skillsDir = path.join(CURRENT_LINK, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    const skillNames = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .filter((d) => d.isDirectory())
+      .map((d) => d.name);
+    reconcileHarnessLinks({ skillsDir, skillNames, force: false });
+  }
+
   console.log(`rolled back to ${targetSha.slice(0, 12)}`);
 }
 
@@ -798,7 +876,7 @@ function doUninstall() {
         const lstat = fs.lstatSync(full);
         if (!lstat.isSymbolicLink()) continue;
         const target = fs.readlinkSync(full);
-        if (target.includes(OPERATOR_ROOT) || target.includes('skills-operator')) {
+        if (isOperatorLink(target)) {
           fs.unlinkSync(full);
           console.log(`unlinked ${full}`);
         }
@@ -844,5 +922,8 @@ module.exports = {
   releaseLock,
   linkSkill,
   pruneOldShas,
+  isOperatorLink,
+  pruneStaleLinks,
+  reconcileHarnessLinks,
   // exposed for tests
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills-operator",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "OAuth-gated installer for Vruum operator skills. Pulls the operator skill bundle from api.vruum.ai and symlinks it into your AI assistant's skill directory.",
   "license": "MIT",
   "repository": {