@vruum/skills-operator 0.1.0 → 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 ────────────────────────────────────────────────────────────
@@ -234,6 +237,49 @@ async function discoverAuthServer() {
   });
 }
 
+async function registerClient(registrationEndpoint, redirectUri) {
+  // RFC 7591 Dynamic Client Registration. Supabase's auth server requires a
+  // client_id on authorize and token calls; it advertises a
+  // registration_endpoint in the OAuth metadata so public CLI apps can
+  // register themselves. We register a fresh public client per full auth flow
+  // (loopback redirect_uri varies by OS-picked port, so reuse isn't robust)
+  // and cache the returned client_id in auth.json for refresh calls.
+  const body = JSON.stringify({
+    client_name: 'Vruum Operator Skills CLI',
+    redirect_uris: [redirectUri],
+    token_endpoint_auth_method: 'none',
+    grant_types: ['authorization_code', 'refresh_token'],
+    response_types: ['code'],
+  });
+  const parsed = new URL(registrationEndpoint);
+  return new Promise((resolve, reject) => {
+    const req = https.request({
+      method: 'POST',
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname + parsed.search,
+      headers: {
+        'Content-Type': 'application/json',
+        'Content-Length': Buffer.byteLength(body),
+      },
+    }, (res) => {
+      let data = '';
+      res.on('data', (c) => { data += c; });
+      res.on('end', () => {
+        if (res.statusCode >= 200 && res.statusCode < 300) {
+          try { resolve(JSON.parse(data)); }
+          catch { reject(new Error('Registration response is not JSON')); }
+        } else {
+          reject(new Error(`Client registration returned ${res.statusCode}: ${data}`));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.write(body);
+    req.end();
+  });
+}
+
 function tryOpenBrowser(urlToOpen) {
   const cmd = process.platform === 'darwin' ? 'open'
             : process.platform === 'win32'  ? 'start'
@@ -251,6 +297,9 @@ async function loopbackAuthFlow() {
   if (!meta.authorization_endpoint || !meta.token_endpoint) {
     throw new Error('OAuth metadata missing authorization_endpoint or token_endpoint');
   }
+  if (!meta.registration_endpoint) {
+    throw new Error('OAuth metadata missing registration_endpoint — cannot register public client');
+  }
 
   const state = base64UrlEncode(crypto.randomBytes(32));
   const verifier = base64UrlEncode(crypto.randomBytes(32));
@@ -259,12 +308,27 @@ async function loopbackAuthFlow() {
   // Start listener on an OS-picked port.
   return await new Promise((resolve, reject) => {
     const server = http.createServer();
-    server.listen(0, '127.0.0.1', () => {
+    server.listen(0, '127.0.0.1', async () => {
       const { port } = server.address();
       const redirectUri = `http://127.0.0.1:${port}/callback`;
 
+      // Register a fresh public client for this auth flow. Supabase requires
+      // exact redirect_uri match, so we can't reuse a cached client_id across
+      // runs (the OS-picked port changes). The client_id is cached for
+      // refresh-token calls, which don't require a redirect_uri.
+      let clientId;
+      try {
+        const client = await registerClient(meta.registration_endpoint, redirectUri);
+        clientId = client.client_id;
+      } catch (e) {
+        server.close();
+        reject(new Error(`OAuth client registration failed: ${e.message}`));
+        return;
+      }
+
       const authUrl = new URL(meta.authorization_endpoint);
       authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('client_id', clientId);
       authUrl.searchParams.set('redirect_uri', redirectUri);
       authUrl.searchParams.set('state', state);
       authUrl.searchParams.set('code_challenge', challenge);
@@ -310,11 +374,13 @@ async function loopbackAuthFlow() {
             code,
             redirect_uri: redirectUri,
             code_verifier: verifier,
+            client_id: clientId,
           });
           res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
           res.end('<html><body><h3>Signed in to Vruum.</h3><p>You can close this tab.</p></body></html>');
           clearTimeout(timeout); server.close();
-          resolve(tokens);
+          // Thread client_id through so writeAuthFile can persist it for refresh calls.
+          resolve({ ...tokens, _client_id: clientId });
         } catch (e) {
           res.writeHead(500, { 'Content-Type': 'text/plain' });
           res.end(`Token exchange failed: ${e.message}`);
@@ -370,6 +436,8 @@ function writeAuthFile(tokens) {
   const payload = {
     access_token: tokens.access_token,
     refresh_token: tokens.refresh_token,
+    // client_id is required on Supabase refresh-token calls for public clients.
+    client_id: tokens.client_id || tokens._client_id,
     expires_at: tokens.expires_at || (Math.floor(Date.now() / 1000) + (tokens.expires_in || 3600)),
     token_type: tokens.token_type || 'bearer',
     written_at: nowIso(),
@@ -390,10 +458,17 @@ async function refreshTokens(auth) {
   if (!auth || !auth.refresh_token) return null;
   const meta = await discoverAuthServer();
   try {
-    return await postTokenRequest(meta.token_endpoint, {
+    const params = {
       grant_type: 'refresh_token',
       refresh_token: auth.refresh_token,
-    });
+    };
+    // Supabase requires client_id on public-client refresh calls. Auth files
+    // written before the DCR fix won't have it — missing client_id forces a
+    // full re-auth via loopbackAuthFlow().
+    if (auth.client_id) params.client_id = auth.client_id;
+    const tokens = await postTokenRequest(meta.token_endpoint, params);
+    // Preserve client_id across refresh writes.
+    return { ...tokens, client_id: auth.client_id };
   } catch { return null; }
 }
 
@@ -515,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');
@@ -555,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;
     }
 
@@ -623,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);
 
@@ -708,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)}`);
 }
 
@@ -726,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}`);
         }
@@ -772,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.0",
+  "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": {