@vruum/skills-operator 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vruum AI
+
+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/README.md

@@ -0,0 +1,54 @@
+# @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.
+
+```bash
+npx @vruum/skills-operator install
+```
+
+## What it does
+
+1. Opens your browser for Vruum OAuth sign-in (PKCE + state, loopback redirect).
+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.
+
+## Commands
+
+```bash
+npx @vruum/skills-operator install                 # fetch latest
+npx @vruum/skills-operator install --pin <sha>     # fetch a specific build
+npx @vruum/skills-operator install --force         # override dual-install safety
+npx @vruum/skills-operator update                  # alias for install
+npx @vruum/skills-operator rollback [--to <sha>]   # flip `current` to a prior build, no network
+npx @vruum/skills-operator uninstall               # remove symlinks + skills-operator/
+```
+
+## Auth
+
+The first `install` triggers a loopback OAuth flow. Your session is cached at `~/.vruum/auth.json` and refreshes automatically. If the refresh token becomes invalid (password change, session revoked), re-run `install` to trigger fresh sign-in. The installer never silently wipes auth state — you always see an explicit prompt.
+
+## Role revocation
+
+When an admin removes your operator role, the next update-check emits `OPERATOR_ROLE_REVOKED` inside the skill preamble. Existing installed skills keep working locally but can't upgrade until the role is restored.
+
+## Dual-install safety
+
+If you also have `./.agents/setup` installed from a local `vruum_ai` checkout, the installer refuses to overwrite those symlinks without `--force`. The reverse is also true (`./.agents/setup` refuses over OAuth installs without `--force`). This protects the Jon-on-laptop case where both flows exist.
+
+## Windows
+
+Symlinks require admin or dev-mode on Windows. Without either, the installer falls back to copying files — works fine, but `rollback` requires re-running `install`.
+
+## Telemetry (opt-in)
+
+Set `telemetry: community` (or `anonymous`) in `~/.vruum/config.yaml` to help surface installer bugs. Payload is fixed-shape (`version`, `platform`, `node`, `phase`, `error_class`, `session_id`) and carries zero PII. Default is off.
+
+## Pairs with
+
+The Vruum MCP server at `https://api.vruum.ai/mcp`. Slash commands in your AI assistant turn into specialized workflows there.
+
+## Issues
+
+[github.com/vruum-gtm/skills-operator/issues](https://github.com/vruum-gtm/skills-operator/issues)

package/bin/vruum-skills-operator-update-check

@@ -0,0 +1,90 @@
+#!/usr/bin/env bash
+# vruum-skills-operator-update-check — periodic version check for the operator skill bundle.
+#
+# Output (one line, or nothing):
+#   JUST_UPGRADED <old> <new>       — marker left by a recent install
+#   UPGRADE_AVAILABLE <old> <new>   — server advertises a newer SHA
+#   OPERATOR_ROLE_REVOKED           — 403 from the HEAD endpoint
+#   (nothing)                       — up to date, cache fresh, or quiet failure
+#
+# Env overrides (for testing):
+#   VRUUM_STATE_DIR   — override ~/.vruum state directory
+#   VRUUM_API_BASE    — override api.vruum.ai
+set -euo pipefail
+
+STATE_DIR="${VRUUM_STATE_DIR:-$HOME/.vruum}"
+API_BASE="${VRUUM_API_BASE:-https://api.vruum.ai}"
+OP_ROOT="$STATE_DIR/skills-operator"
+VERSION_FILE="$OP_ROOT/VERSION"
+CACHE_FILE="$OP_ROOT/last-update-check"
+MARKER_FILE="$OP_ROOT/just-upgraded-from"
+AUTH_FILE="$STATE_DIR/auth.json"
+CONFIG_FILE="$STATE_DIR/config.yaml"
+CHECK_INTERVAL_SECS=3600  # 1h
+
+# Step 0: if config disables update checks, bail.
+if [ -f "$CONFIG_FILE" ] && grep -qE '^[[:space:]]*update_check[[:space:]]*:[[:space:]]*false' "$CONFIG_FILE"; then
+  exit 0
+fi
+
+# Just-upgraded marker wins once.
+if [ -f "$MARKER_FILE" ]; then
+  OLD="$(cat "$MARKER_FILE" 2>/dev/null || true)"
+  rm -f "$MARKER_FILE"
+  NEW="$(cat "$VERSION_FILE" 2>/dev/null || echo '?')"
+  [ -n "$OLD" ] && echo "JUST_UPGRADED $OLD $NEW"
+fi
+
+[ -f "$VERSION_FILE" ] || exit 0
+LOCAL="$(tr -d '[:space:]' < "$VERSION_FILE")"
+[ -n "$LOCAL" ] || exit 0
+
+# Force flag busts cache.
+if [ "${1:-}" = "--force" ]; then
+  rm -f "$CACHE_FILE"
+fi
+
+# Cache short-circuit.
+if [ -f "$CACHE_FILE" ]; then
+  last_check=$(stat -f %m "$CACHE_FILE" 2>/dev/null || stat -c %Y "$CACHE_FILE" 2>/dev/null || echo 0)
+  now=$(date +%s)
+  if [ $((now - last_check)) -lt "$CHECK_INTERVAL_SECS" ]; then
+    cached="$(cat "$CACHE_FILE" 2>/dev/null || true)"
+    [ -n "$cached" ] && echo "$cached"
+    exit 0
+  fi
+fi
+
+# Step 1: read access token; silent if missing.
+[ -f "$AUTH_FILE" ] || exit 0
+TOKEN="$(sed -nE 's/.*"access_token"[[:space:]]*:[[:space:]]*"([^"]+)".*/\1/p' "$AUTH_FILE" | head -1)"
+[ -n "$TOKEN" ] || exit 0
+
+# Step 2: HEAD /api/operator/skills/latest. Short timeout, quiet on any error.
+HEADERS="$(curl -fsS -I --max-time 5 \
+  -H "Authorization: Bearer $TOKEN" \
+  "$API_BASE/api/operator/skills/latest" 2>/dev/null || true)"
+
+if [ -z "$HEADERS" ]; then
+  # Network error or non-2xx. Check for 403 specifically so the preamble can
+  # surface role revocation even when curl would have returned non-zero.
+  STATUS=$(curl -o /dev/null -s -w "%{http_code}" -I --max-time 5 \
+    -H "Authorization: Bearer $TOKEN" \
+    "$API_BASE/api/operator/skills/latest" 2>/dev/null || echo "000")
+  if [ "$STATUS" = "403" ]; then
+    echo "OPERATOR_ROLE_REVOKED"
+    : > "$CACHE_FILE"
+  fi
+  exit 0
+fi
+
+REMOTE_SHA="$(echo "$HEADERS" | sed -nE 's/^[Xx]-[Vv]ruum-[Ss]kills-[Vv]ersion:[[:space:]]*([^[:space:]\r]+).*/\1/p' | head -1)"
+[ -n "$REMOTE_SHA" ] || exit 0
+
+if [ "$LOCAL" != "$REMOTE_SHA" ]; then
+  MSG="UPGRADE_AVAILABLE $LOCAL $REMOTE_SHA"
+  echo "$MSG" | tee "$CACHE_FILE" >/dev/null
+  echo "$MSG"
+else
+  : > "$CACHE_FILE"
+fi

package/install.js

@@ -0,0 +1,776 @@
+#!/usr/bin/env node
+/**
+ * @vruum/skills-operator installer.
+ *
+ * Fetches the operator skill bundle from api.vruum.ai (OAuth-gated, role-
+ * restricted to operators with 2+ linked companies) and symlinks each skill
+ * into the local AI assistant's skill directory.
+ *
+ * Subcommands:
+ *   install             — fetch latest, extract, symlink
+ *   update              — alias for install
+ *   rollback [--to sha] — flip ~/.vruum/skills-operator/current to a prior SHA
+ *                         (local-only, works against SHAs you've installed before)
+ *   uninstall           — remove symlinks + ~/.vruum/skills-operator/
+ *   help                — print this text
+ *
+ * Note: `install --pin <sha>` is NOT supported. The backend streams the
+ * currently-deployed bundle only; historical SHAs aren't stored anywhere.
+ * The installer keeps 2 prior SHAs cached on-disk so `rollback` handles the
+ * operator-side recovery need without network.
+ *
+ * Design notes (referenced from the eng-review plan):
+ *   - OAuth state param + PKCE on the loopback flow (RFC 8252 + CSRF defense).
+ *   - 127.0.0.1:0 OS-picked loopback port (no collisions).
+ *   - 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.
+ *   - 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.
+ *   - Auth.json written atomically with mode 0600 (mkstemp + fsync + rename).
+ *   - 401 silent refresh once; second 401 tells the user to re-run install.
+ *
+ * MIRRORED FROM @vruum/skills for the link/unlink/symlink logic; kept as a
+ * copy rather than a shared library because the two packages publish
+ * independently under different Trusted Publisher workflows.
+ */
+
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const http = require('node:http');
+const https = require('node:https');
+const os = require('node:os');
+const path = require('node:path');
+const url = require('node:url');
+const { spawn } = require('node:child_process');
+const tar = require('tar');
+
+const VERSION = require('./package.json').version;
+
+const API_BASE = process.env.VRUUM_API_BASE || 'https://api.vruum.ai';
+const SKILLS_ENDPOINT = `${API_BASE}/api/operator/skills/latest`;
+const DISCOVERY_ENDPOINT = `${API_BASE}/.well-known/oauth-authorization-server`;
+const INSTALL_ERROR_ENDPOINT = `${API_BASE}/api/operator/skills/install-errors`;
+const LOOPBACK_TIMEOUT_MS = 300_000;
+const DOWNLOAD_RETRIES = 3;
+
+const VRUUM_ROOT = path.join(os.homedir(), '.vruum');
+const AUTH_PATH = path.join(VRUUM_ROOT, 'auth.json');
+const BIN_DIR = path.join(VRUUM_ROOT, 'bin');
+const OPERATOR_ROOT = path.join(VRUUM_ROOT, 'skills-operator');
+const CURRENT_LINK = path.join(OPERATOR_ROOT, 'current');
+const VERSION_FILE = path.join(OPERATOR_ROOT, 'VERSION');
+const LOCK_FILE = path.join(OPERATOR_ROOT, '.install.lock');
+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') },
+];
+
+// ─── Arg parsing ────────────────────────────────────────────────────────────
+
+function parseArgs(argv) {
+  const args = { command: 'install', to: null, force: false, help: false };
+  const rest = argv.slice(2);
+  let i = 0;
+  if (rest[i] && !rest[i].startsWith('-')) {
+    args.command = rest[i];
+    i += 1;
+  }
+  for (; i < rest.length; i += 1) {
+    const a = rest[i];
+    if (a === '--to') {
+      args.to = rest[i + 1];
+      if (!args.to) throw new Error('--to requires a sha');
+      i += 1;
+    } else if (a === '--force') {
+      args.force = true;
+    } else if (a === '--help' || a === '-h') {
+      args.help = true;
+    } else {
+      throw new Error(`unknown argument: ${a}`);
+    }
+  }
+  return args;
+}
+
+function printHelp() {
+  console.log(`@vruum/skills-operator v${VERSION}
+
+Usage:
+  npx @vruum/skills-operator install                 Install latest operator skills
+  npx @vruum/skills-operator install --force         Override dual-install safety check
+  npx @vruum/skills-operator update                  Alias for install
+  npx @vruum/skills-operator rollback [--to <sha>]   Flip to a prior build, no network
+  npx @vruum/skills-operator uninstall               Remove symlinks + ~/.vruum/skills-operator/
+  npx @vruum/skills-operator help                    Show this text
+
+Requires: a Vruum account with operator role (owner on 2+ companies).
+          The installer opens your browser for OAuth on first run.
+
+Pairs with the Vruum MCP server at ${API_BASE}/mcp.`);
+}
+
+// ─── Small utils ────────────────────────────────────────────────────────────
+
+function expandTilde(p) {
+  return p.startsWith('~') ? path.join(os.homedir(), p.slice(1)) : p;
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function isShaLike(s) {
+  return typeof s === 'string' && /^[0-9a-f]{7,64}$/i.test(s);
+}
+
+function readConfigValue(key) {
+  if (!fs.existsSync(CONFIG_FILE)) return null;
+  const lines = fs.readFileSync(CONFIG_FILE, 'utf8').split('\n');
+  for (const line of lines) {
+    const m = line.match(/^\s*([^:#\s]+)\s*:\s*(.*?)\s*$/);
+    if (m && m[1] === key) return m[2];
+  }
+  return null;
+}
+
+async function postTelemetry(phase, errorClass) {
+  const telemetrySetting = readConfigValue('telemetry');
+  if (!telemetrySetting || telemetrySetting === 'off') return;
+  const payload = JSON.stringify({
+    version: VERSION,
+    platform: `${os.platform()}-${os.arch()}`,
+    node: process.version,
+    phase,
+    error_class: errorClass,
+    session_id: SESSION_ID,
+  });
+  try {
+    await new Promise((resolve) => {
+      const req = https.request(INSTALL_ERROR_ENDPOINT, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(payload) },
+        timeout: 5000,
+      }, (res) => { res.on('data', () => {}); res.on('end', resolve); });
+      req.on('error', () => resolve());
+      req.on('timeout', () => { req.destroy(); resolve(); });
+      req.end(payload);
+    });
+  } catch { /* telemetry is best-effort */ }
+}
+
+function fail(msg, phase = 'unknown', errorClass = 'InstallError') {
+  console.error(`\nError: ${msg}`);
+  postTelemetry(phase, errorClass).finally(() => process.exit(1));
+}
+
+// ─── Lock (with PID reclamation) ────────────────────────────────────────────
+
+function acquireLock() {
+  fs.mkdirSync(OPERATOR_ROOT, { recursive: true });
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      const fd = fs.openSync(LOCK_FILE, fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_WRONLY, 0o600);
+      fs.writeSync(fd, String(process.pid));
+      fs.closeSync(fd);
+      return;
+    } catch (e) {
+      if (e.code !== 'EEXIST') throw e;
+      // Lock file exists — check if the holding PID is alive.
+      let holderPid = 0;
+      try { holderPid = parseInt(fs.readFileSync(LOCK_FILE, 'utf8').trim(), 10) || 0; }
+      catch { /* unreadable; treat as stale */ }
+      if (holderPid > 0) {
+        try { process.kill(holderPid, 0); /* alive */ throw new Error(`install already in progress (pid ${holderPid})`); }
+        catch (signalErr) {
+          if (signalErr.code === 'ESRCH' || !holderPid) {
+            console.warn(`stale lock reclaimed from pid ${holderPid}`);
+            fs.rmSync(LOCK_FILE, { force: true });
+            continue; // retry the creat
+          }
+          if (signalErr.message && signalErr.message.startsWith('install already')) throw signalErr;
+          // Other error (e.g. EPERM — process alive but owned by someone else): treat as alive.
+          throw new Error(`install already in progress (pid ${holderPid})`);
+        }
+      } else {
+        fs.rmSync(LOCK_FILE, { force: true });
+      }
+    }
+  }
+  throw new Error('could not acquire install lock');
+}
+
+function releaseLock() {
+  try { fs.rmSync(LOCK_FILE, { force: true }); } catch { /* ignore */ }
+}
+
+// ─── OAuth loopback ─────────────────────────────────────────────────────────
+
+function base64UrlEncode(buf) {
+  return buf.toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+async function discoverAuthServer() {
+  return new Promise((resolve, reject) => {
+    https.get(DISCOVERY_ENDPOINT, (res) => {
+      if (res.statusCode !== 200) {
+        reject(new Error(`OAuth discovery returned ${res.statusCode}`));
+        return;
+      }
+      let body = '';
+      res.on('data', (c) => { body += c; });
+      res.on('end', () => {
+        try { resolve(JSON.parse(body)); }
+        catch (e) { reject(new Error('OAuth discovery response is not JSON')); }
+      });
+    }).on('error', reject);
+  });
+}
+
+function tryOpenBrowser(urlToOpen) {
+  const cmd = process.platform === 'darwin' ? 'open'
+            : process.platform === 'win32'  ? 'start'
+            : 'xdg-open';
+  try {
+    const child = spawn(cmd, [urlToOpen], { stdio: 'ignore', detached: true, shell: process.platform === 'win32' });
+    child.on('error', () => {});
+    child.unref();
+    return true;
+  } catch { return false; }
+}
+
+async function loopbackAuthFlow() {
+  const meta = await discoverAuthServer();
+  if (!meta.authorization_endpoint || !meta.token_endpoint) {
+    throw new Error('OAuth metadata missing authorization_endpoint or token_endpoint');
+  }
+
+  const state = base64UrlEncode(crypto.randomBytes(32));
+  const verifier = base64UrlEncode(crypto.randomBytes(32));
+  const challenge = base64UrlEncode(crypto.createHash('sha256').update(verifier).digest());
+
+  // Start listener on an OS-picked port.
+  return await new Promise((resolve, reject) => {
+    const server = http.createServer();
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address();
+      const redirectUri = `http://127.0.0.1:${port}/callback`;
+
+      const authUrl = new URL(meta.authorization_endpoint);
+      authUrl.searchParams.set('response_type', 'code');
+      authUrl.searchParams.set('redirect_uri', redirectUri);
+      authUrl.searchParams.set('state', state);
+      authUrl.searchParams.set('code_challenge', challenge);
+      authUrl.searchParams.set('code_challenge_method', 'S256');
+      // Scope omitted: Supabase tokens default audience is `authenticated`; the
+      // server-side role gate enforces operator access separately.
+
+      const timeout = setTimeout(() => {
+        server.close();
+        reject(new Error('OAuth callback timed out after 5 minutes. Re-run `install` to retry.'));
+      }, LOOPBACK_TIMEOUT_MS);
+
+      server.on('request', async (req, res) => {
+        const parsed = url.parse(req.url, true);
+        if (parsed.pathname !== '/callback') {
+          res.writeHead(404); res.end(); return;
+        }
+        const { state: returnedState, code, error, error_description } = parsed.query;
+        if (error) {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end(`OAuth error: ${error}${error_description ? ' — ' + error_description : ''}`);
+          clearTimeout(timeout); server.close();
+          reject(new Error(`OAuth server returned error: ${error}`));
+          return;
+        }
+        if (returnedState !== state) {
+          res.writeHead(400, { 'Content-Type': 'text/plain' });
+          res.end('State parameter mismatch — possible CSRF attempt. Aborting.');
+          clearTimeout(timeout); server.close();
+          reject(new Error('OAuth state mismatch'));
+          return;
+        }
+        if (!code) {
+          res.writeHead(400); res.end('Missing code parameter.');
+          clearTimeout(timeout); server.close();
+          reject(new Error('OAuth callback missing code'));
+          return;
+        }
+        // Exchange code for token.
+        try {
+          const tokens = await postTokenRequest(meta.token_endpoint, {
+            grant_type: 'authorization_code',
+            code,
+            redirect_uri: redirectUri,
+            code_verifier: verifier,
+          });
+          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);
+        } catch (e) {
+          res.writeHead(500, { 'Content-Type': 'text/plain' });
+          res.end(`Token exchange failed: ${e.message}`);
+          clearTimeout(timeout); server.close();
+          reject(e);
+        }
+      });
+
+      console.log('Opening browser for Vruum sign-in...');
+      console.log(`If the browser doesn't open, visit this URL manually:\n  ${authUrl.toString()}\n`);
+      tryOpenBrowser(authUrl.toString());
+    });
+    server.on('error', (e) => reject(e));
+  });
+}
+
+function postTokenRequest(endpoint, params) {
+  return new Promise((resolve, reject) => {
+    const body = new URLSearchParams(params).toString();
+    const parsed = new URL(endpoint);
+    const req = https.request({
+      hostname: parsed.hostname,
+      port: parsed.port || 443,
+      path: parsed.pathname + parsed.search,
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/x-www-form-urlencoded',
+        '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 (e) { reject(new Error('Token response is not JSON')); }
+        } else {
+          reject(new Error(`Token endpoint returned ${res.statusCode}: ${data}`));
+        }
+      });
+    });
+    req.on('error', reject);
+    req.end(body);
+  });
+}
+
+// ─── Auth persistence ───────────────────────────────────────────────────────
+
+function writeAuthFile(tokens) {
+  fs.mkdirSync(VRUUM_ROOT, { recursive: true });
+  const tmp = `${AUTH_PATH}.tmp-${process.pid}`;
+  const fd = fs.openSync(tmp, fs.constants.O_CREAT | fs.constants.O_WRONLY | fs.constants.O_EXCL, 0o600);
+  const payload = {
+    access_token: tokens.access_token,
+    refresh_token: tokens.refresh_token,
+    expires_at: tokens.expires_at || (Math.floor(Date.now() / 1000) + (tokens.expires_in || 3600)),
+    token_type: tokens.token_type || 'bearer',
+    written_at: nowIso(),
+  };
+  fs.writeSync(fd, JSON.stringify(payload, null, 2));
+  fs.fsyncSync(fd);
+  fs.closeSync(fd);
+  fs.renameSync(tmp, AUTH_PATH);
+}
+
+function readAuthFile() {
+  if (!fs.existsSync(AUTH_PATH)) return null;
+  try { return JSON.parse(fs.readFileSync(AUTH_PATH, 'utf8')); }
+  catch { return null; }
+}
+
+async function refreshTokens(auth) {
+  if (!auth || !auth.refresh_token) return null;
+  const meta = await discoverAuthServer();
+  try {
+    return await postTokenRequest(meta.token_endpoint, {
+      grant_type: 'refresh_token',
+      refresh_token: auth.refresh_token,
+    });
+  } catch { return null; }
+}
+
+async function ensureAuth() {
+  let auth = readAuthFile();
+  const now = Math.floor(Date.now() / 1000);
+  if (auth && auth.access_token && auth.expires_at && auth.expires_at > now + 30) {
+    return auth;
+  }
+  if (auth && auth.refresh_token) {
+    const refreshed = await refreshTokens(auth);
+    if (refreshed) {
+      writeAuthFile(refreshed);
+      return readAuthFile();
+    }
+  }
+  // Trigger interactive loopback OAuth.
+  console.log('No valid session found — launching browser for Vruum sign-in.');
+  const tokens = await loopbackAuthFlow();
+  writeAuthFile(tokens);
+  return readAuthFile();
+}
+
+// ─── HTTP to Vruum API ──────────────────────────────────────────────────────
+
+function httpRequest({ method, urlString, headers = {}, outputStream = null }) {
+  return new Promise((resolve, reject) => {
+    const parsed = new URL(urlString);
+    const proto = parsed.protocol === 'http:' ? http : https;
+    const req = proto.request({
+      method,
+      hostname: parsed.hostname,
+      port: parsed.port || (parsed.protocol === 'http:' ? 80 : 443),
+      path: parsed.pathname + parsed.search,
+      headers,
+    }, (res) => {
+      if (res.statusCode >= 300 && res.statusCode < 400 && res.headers.location) {
+        // Follow one redirect (S3 signed URL redirect).
+        httpRequest({ method, urlString: res.headers.location, headers, outputStream })
+          .then(resolve, reject);
+        return;
+      }
+      if (outputStream) {
+        res.pipe(outputStream);
+        outputStream.on('finish', () => resolve({ statusCode: res.statusCode, headers: res.headers, body: null }));
+        outputStream.on('error', reject);
+      } else {
+        let body = '';
+        res.on('data', (c) => { body += c; });
+        res.on('end', () => resolve({ statusCode: res.statusCode, headers: res.headers, body }));
+      }
+    });
+    req.on('error', reject);
+    req.end();
+  });
+}
+
+async function fetchHeadWithAuth(endpoint) {
+  const auth = await ensureAuth();
+  let resp = await httpRequest({
+    method: 'HEAD',
+    urlString: endpoint,
+    headers: { Authorization: `Bearer ${auth.access_token}` },
+  });
+  if (resp.statusCode === 401) {
+    const refreshed = await refreshTokens(readAuthFile());
+    if (refreshed) {
+      writeAuthFile(refreshed);
+      const newAuth = readAuthFile();
+      resp = await httpRequest({
+        method: 'HEAD',
+        urlString: endpoint,
+        headers: { Authorization: `Bearer ${newAuth.access_token}` },
+      });
+    }
+  }
+  return resp;
+}
+
+// ─── Link / unlink (MIRRORED from @vruum/skills) ────────────────────────────
+
+function ensureDirExists(dir) {
+  if (!fs.existsSync(dir)) return false;
+  return true;
+}
+
+function linkSkill({ name, srcAbs, targetDir, force }) {
+  const dst = path.join(targetDir, name);
+  let existing = null;
+  try {
+    const lstat = fs.lstatSync(dst);
+    if (lstat.isSymbolicLink()) existing = { kind: 'symlink', target: fs.readlinkSync(dst) };
+    else existing = { kind: lstat.isDirectory() ? 'dir' : 'file' };
+  } catch (err) {
+    if (err.code !== 'ENOENT') throw err;
+  }
+
+  if (existing?.kind === 'symlink' && existing.target === srcAbs) {
+    return { name, action: 'already-linked' };
+  }
+  if (existing?.kind === 'symlink' && existing.target.includes(path.join('.agents', 'skills')) && !force) {
+    return { name, action: 'skipped', reason: `detected .agents/setup symlink; re-run with --force to override` };
+  }
+  if (existing && existing.kind !== 'symlink') {
+    return { name, action: 'skipped', reason: `non-symlink ${existing.kind} already at ${dst}` };
+  }
+
+  if (existing?.kind === 'symlink') fs.unlinkSync(dst);
+  try {
+    fs.symlinkSync(srcAbs, dst, 'dir');
+    return { name, action: existing ? 'relinked' : 'linked' };
+  } catch (e) {
+    if (e.code === 'EPERM' && process.platform === 'win32') {
+      // Windows without admin/dev-mode. Fall back to copy.
+      fs.cpSync(srcAbs, dst, { recursive: true });
+      return { name, action: 'copied', reason: 'Windows symlinks require admin or dev-mode; copied files instead. Re-run `install` to upgrade.' };
+    }
+    throw e;
+  }
+}
+
+function copyUpdateCheckShim() {
+  fs.mkdirSync(BIN_DIR, { recursive: true });
+  const src = path.join(__dirname, 'bin', 'vruum-skills-operator-update-check');
+  const dst = path.join(BIN_DIR, 'vruum-skills-operator-update-check');
+  if (fs.existsSync(src)) {
+    fs.copyFileSync(src, dst);
+    try { fs.chmodSync(dst, 0o755); } catch { /* Windows: no-op */ }
+  }
+}
+
+// ─── Install ────────────────────────────────────────────────────────────────
+
+async function doInstall({ force = false } = {}) {
+  const endpoint = SKILLS_ENDPOINT;
+  fs.mkdirSync(OPERATOR_ROOT, { recursive: true });
+  acquireLock();
+  try {
+    const head = await fetchHeadWithAuth(endpoint);
+    if (head.statusCode === 401) {
+      fail('Your session expired. Run `install` again to re-authenticate.', 'auth', 'SessionExpired');
+    }
+    if (head.statusCode === 403) {
+      fail('Your account does not have operator role. Contact admin.', 'auth', 'RoleRequired');
+    }
+    if (head.statusCode === 404) {
+      fail('No operator skill bundle has been published yet.', 'head', 'NotFound');
+    }
+    if (head.statusCode !== 200) {
+      fail(`HEAD ${endpoint} returned ${head.statusCode}`, 'head', 'HttpError');
+    }
+    const sha = head.headers['x-vruum-skills-version'];
+    const sha256 = head.headers['x-vruum-skills-sha256'];
+    if (!sha || !sha256) {
+      fail('Server response missing X-Vruum-Skills-Version / Sha256 headers.', 'head', 'ProtocolError');
+    }
+
+    // Short-circuit if we already have this SHA.
+    const currentSha = fs.existsSync(VERSION_FILE) ? fs.readFileSync(VERSION_FILE, 'utf8').trim() : null;
+    if (currentSha === sha) {
+      console.log(`already up to date (sha=${sha})`);
+      return;
+    }
+
+    // Download to a tmp path, verify, extract to ~/.vruum/skills-operator/<sha>/.
+    const targetDir = path.join(OPERATOR_ROOT, sha);
+    fs.mkdirSync(targetDir, { recursive: true });
+    const tarballPath = path.join(OPERATOR_ROOT, `.download-${process.pid}.tgz`);
+    const auth = await ensureAuth();
+    let lastErr = null;
+    for (let attempt = 0; attempt < DOWNLOAD_RETRIES; attempt += 1) {
+      try {
+        const out = fs.createWriteStream(tarballPath);
+        await httpRequest({
+          method: 'GET',
+          urlString: endpoint,
+          headers: { Authorization: `Bearer ${auth.access_token}` },
+          outputStream: out,
+        });
+        lastErr = null;
+        break;
+      } catch (e) {
+        lastErr = e;
+        console.warn(`download attempt ${attempt + 1} failed: ${e.message}`);
+      }
+    }
+    if (lastErr) fail(`download failed: ${lastErr.message}`, 'download', 'DownloadFailed');
+
+    // SHA256 verify.
+    const actualSha256 = await new Promise((resolve, reject) => {
+      const hash = crypto.createHash('sha256');
+      const s = fs.createReadStream(tarballPath);
+      s.on('data', (c) => hash.update(c));
+      s.on('end', () => resolve(hash.digest('hex')));
+      s.on('error', reject);
+    });
+    if (actualSha256 !== sha256) {
+      try { fs.rmSync(tarballPath, { force: true }); } catch {}
+      fail(`SHA256 mismatch (expected ${sha256}, got ${actualSha256}). Partial download deleted.`, 'verify', 'Sha256Mismatch');
+    }
+
+    // Extract.
+    await tar.x({ file: tarballPath, cwd: targetDir, strip: 0 });
+    try { fs.rmSync(tarballPath, { force: true }); } catch {}
+
+    // Flip `current` atomically.
+    const tmpLink = `${CURRENT_LINK}.tmp-${process.pid}`;
+    try { fs.rmSync(tmpLink, { force: true }); } catch {}
+    try {
+      fs.symlinkSync(targetDir, tmpLink, 'dir');
+      fs.renameSync(tmpLink, CURRENT_LINK);
+    } catch (e) {
+      if (e.code === 'EPERM' && process.platform === 'win32') {
+        // Windows without admin: fall back to plain file (no rollback support).
+        if (fs.existsSync(CURRENT_LINK)) fs.rmSync(CURRENT_LINK, { recursive: true, force: true });
+        fs.cpSync(targetDir, CURRENT_LINK, { recursive: true });
+        console.warn('Windows symlinks unavailable — copied into current/. Rollback requires re-running install.');
+      } else {
+        throw e;
+      }
+    }
+
+    // Symlink each skill into harnesses via current/.
+    const skillsDir = path.join(CURRENT_LINK, 'skills');
+    if (!fs.existsSync(skillsDir)) fail(`bundle missing skills/ directory at ${skillsDir}`, 'extract', 'BundleShape');
+    const skillNames = fs.readdirSync(skillsDir, { withFileTypes: true })
+      .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}`);
+    }
+
+    fs.writeFileSync(VERSION_FILE, sha);
+
+    // Drop the update-check shim into ~/.vruum/bin/.
+    copyUpdateCheckShim();
+
+    // Prune old SHAs, keep current + 2 prior.
+    pruneOldShas(2);
+
+    console.log(`\nOperator skills v${sha.slice(0, 12)} installed.`);
+  } finally {
+    releaseLock();
+  }
+}
+
+function pruneOldShas(keep) {
+  if (!fs.existsSync(OPERATOR_ROOT)) return;
+  // Compare against current's realpath by name, not by absolute path, because
+  // macOS canonicalizes /var → /private/var and string-compare would lie.
+  let currentSha = null;
+  if (fs.existsSync(CURRENT_LINK)) {
+    try { currentSha = path.basename(fs.realpathSync(CURRENT_LINK)); }
+    catch {}
+  }
+  const entries = fs.readdirSync(OPERATOR_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && isShaLike(d.name))
+    .map((d) => ({ name: d.name, path: path.join(OPERATOR_ROOT, d.name) }))
+    .map((d) => ({ ...d, mtime: fs.statSync(d.path).mtimeMs }));
+  entries.sort((a, b) => b.mtime - a.mtime);
+  let kept = 0;
+  for (const e of entries) {
+    if (e.name === currentSha) continue;
+    kept += 1;
+    if (kept > keep) {
+      try { fs.rmSync(e.path, { recursive: true, force: true }); } catch {}
+    }
+  }
+}
+
+// ─── Rollback ───────────────────────────────────────────────────────────────
+
+function doRollback({ to }) {
+  if (!fs.existsSync(OPERATOR_ROOT)) fail('No operator skills installed yet.', 'rollback', 'NotInstalled');
+  const entries = fs.readdirSync(OPERATOR_ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory() && isShaLike(d.name))
+    .map((d) => d.name);
+  if (entries.length === 0) fail('No historical builds to roll back to.', 'rollback', 'NoHistory');
+
+  let targetSha = to;
+  if (!targetSha) {
+    // Pick the most-recently-modified non-current build.
+    const current = fs.existsSync(CURRENT_LINK) ? path.basename(fs.realpathSync(CURRENT_LINK)) : null;
+    const candidates = entries.filter((e) => e !== current)
+      .map((name) => ({ name, mtime: fs.statSync(path.join(OPERATOR_ROOT, name)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+    if (candidates.length === 0) fail('Only one build on disk — nothing to roll back to.', 'rollback', 'NoPrior');
+    targetSha = candidates[0].name;
+    console.log(`rolling back to most recent prior build: ${targetSha}`);
+  }
+
+  const targetDir = path.join(OPERATOR_ROOT, targetSha);
+  if (!fs.existsSync(targetDir)) fail(`No local build for sha=${targetSha}. The installer only keeps 2 prior builds on disk — once they're gone you can't roll back to them.`, 'rollback', 'NotOnDisk');
+
+  // Flip current atomically.
+  const tmpLink = `${CURRENT_LINK}.tmp-${process.pid}`;
+  try { fs.rmSync(tmpLink, { force: true }); } catch {}
+  try {
+    fs.symlinkSync(targetDir, tmpLink, 'dir');
+    fs.renameSync(tmpLink, CURRENT_LINK);
+  } catch (e) {
+    fail(`failed to flip current symlink: ${e.message}`, 'rollback', 'SymlinkError');
+  }
+  fs.writeFileSync(VERSION_FILE, targetSha);
+  console.log(`rolled back to ${targetSha.slice(0, 12)}`);
+}
+
+// ─── Uninstall ──────────────────────────────────────────────────────────────
+
+function doUninstall() {
+  if (!fs.existsSync(OPERATOR_ROOT)) {
+    console.log('Nothing to uninstall — ~/.vruum/skills-operator/ does not exist.');
+    return;
+  }
+  for (const { dir: harnessDir } of HARNESSES) {
+    if (!fs.existsSync(harnessDir)) continue;
+    for (const entry of fs.readdirSync(harnessDir)) {
+      const full = path.join(harnessDir, entry);
+      try {
+        const lstat = fs.lstatSync(full);
+        if (!lstat.isSymbolicLink()) continue;
+        const target = fs.readlinkSync(full);
+        if (target.includes(OPERATOR_ROOT) || target.includes('skills-operator')) {
+          fs.unlinkSync(full);
+          console.log(`unlinked ${full}`);
+        }
+      } catch {}
+    }
+  }
+  fs.rmSync(OPERATOR_ROOT, { recursive: true, force: true });
+  console.log('Removed ~/.vruum/skills-operator/. Auth left intact.');
+}
+
+// ─── Main ───────────────────────────────────────────────────────────────────
+
+async function main() {
+  let args;
+  try { args = parseArgs(process.argv); }
+  catch (e) { console.error(e.message); printHelp(); process.exit(1); }
+
+  if (args.help || args.command === 'help') { printHelp(); return; }
+
+  try {
+    if (args.command === 'install' || args.command === 'update') {
+      await doInstall({ force: args.force });
+    } else if (args.command === 'rollback') {
+      doRollback({ to: args.to });
+    } else if (args.command === 'uninstall') {
+      doUninstall();
+    } else {
+      console.error(`unknown command: ${args.command}`);
+      printHelp();
+      process.exit(1);
+    }
+  } catch (e) {
+    fail(e.message, 'main', e.code || 'UnhandledError');
+  }
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  parseArgs,
+  isShaLike,
+  acquireLock,
+  releaseLock,
+  linkSkill,
+  pruneOldShas,
+  // exposed for tests
+};

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@vruum/skills-operator",
+  "version": "0.1.0",
+  "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": {
+    "type": "git",
+    "url": "https://github.com/vruum-gtm/vruum_ai.git",
+    "directory": ".agents/skills-operator"
+  },
+  "homepage": "https://vruum.ai",
+  "bugs": {
+    "url": "https://github.com/vruum-gtm/vruum_ai/issues"
+  },
+  "bin": {
+    "vruum-skills-operator": "./install.js"
+  },
+  "files": [
+    "install.js",
+    "bin/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "tar": "^7.4.0"
+  },
+  "scripts": {
+    "test": "node --test __tests__/*.test.js"
+  },
+  "keywords": [
+    "vruum",
+    "mcp",
+    "claude-code",
+    "codex",
+    "operator",
+    "ai",
+    "sales"
+  ]
+}