@vruum/skills 0.2.0 → 0.4.0

package/bin/vruum-skills-update-check

@@ -0,0 +1,120 @@
+#!/usr/bin/env bash
+# vruum-skills-update-check — periodic version check for the @vruum/skills
+# npm package. Ported from gstack's gstack-update-check, simplified.
+#
+# Output (one line, or nothing):
+#   JUST_UPGRADED <old> <new>       — marker found from a recent upgrade
+#   UPGRADE_AVAILABLE <old> <new>   — npm registry reports a newer version
+#   (nothing)                       — up to date, snoozed, or check skipped
+#
+# Env overrides (for testing):
+#   VRUUM_STATE_DIR     — override ~/.vruum state directory
+#   VRUUM_REMOTE_URL    — override npm registry URL
+set -euo pipefail
+
+STATE_DIR="${VRUUM_STATE_DIR:-$HOME/.vruum}"
+VERSION_FILE="$STATE_DIR/VERSION"
+CACHE_FILE="$STATE_DIR/last-update-check"
+MARKER_FILE="$STATE_DIR/just-upgraded-from"
+SNOOZE_FILE="$STATE_DIR/update-snoozed"
+CONFIG_FILE="$STATE_DIR/config.yaml"
+REMOTE_URL="${VRUUM_REMOTE_URL:-https://registry.npmjs.org/@vruum/skills/latest}"
+
+# Force flag busts cache + snooze (used by /vruum-skills-upgrade directly)
+if [ "${1:-}" = "--force" ]; then
+  rm -f "$CACHE_FILE" "$SNOOZE_FILE"
+fi
+
+# Step 0: if config says updates disabled, bail.
+if [ -f "$CONFIG_FILE" ] && grep -qE '^[[:space:]]*update_check[[:space:]]*:[[:space:]]*false' "$CONFIG_FILE"; then
+  exit 0
+fi
+
+# Step 1: local version (written by install.js at install time)
+[ -f "$VERSION_FILE" ] || exit 0
+LOCAL="$(tr -d '[:space:]' < "$VERSION_FILE")"
+[ -n "$LOCAL" ] || exit 0
+
+# Step 2: just-upgraded marker — emit once, clear snooze, fall through to check
+# remote in case another release landed since the upgrade.
+if [ -f "$MARKER_FILE" ]; then
+  OLD="$(tr -d '[:space:]' < "$MARKER_FILE" 2>/dev/null || true)"
+  rm -f "$MARKER_FILE" "$SNOOZE_FILE"
+  [ -n "$OLD" ] && echo "JUST_UPGRADED $OLD $LOCAL"
+fi
+
+# Step 3: snooze helper — returns 0 if snoozed (stay quiet), 1 if not.
+# Snooze file: "<version> <level> <epoch>". Levels: 1=24h, 2=48h, 3+=7d.
+check_snooze() {
+  local remote_ver="$1"
+  [ -f "$SNOOZE_FILE" ] || return 1
+  local sv sl se
+  sv="$(awk '{print $1}' "$SNOOZE_FILE" 2>/dev/null || true)"
+  sl="$(awk '{print $2}' "$SNOOZE_FILE" 2>/dev/null || true)"
+  se="$(awk '{print $3}' "$SNOOZE_FILE" 2>/dev/null || true)"
+  [ -n "$sv" ] && [ -n "$sl" ] && [ -n "$se" ] || return 1
+  case "$sl" in *[!0-9]*) return 1 ;; esac
+  case "$se" in *[!0-9]*) return 1 ;; esac
+  # New version drop clears the snooze.
+  [ "$sv" = "$remote_ver" ] || return 1
+  local dur
+  case "$sl" in
+    1) dur=86400 ;;
+    2) dur=172800 ;;
+    *) dur=604800 ;;
+  esac
+  local now expires
+  now="$(date +%s)"
+  expires=$(( se + dur ))
+  [ "$now" -lt "$expires" ]
+}
+
+# Step 4: cache — UP_TO_DATE 60 min, UPGRADE_AVAILABLE 12 hours.
+if [ -f "$CACHE_FILE" ]; then
+  CACHED="$(cat "$CACHE_FILE" 2>/dev/null || true)"
+  case "$CACHED" in
+    UP_TO_DATE*)        TTL=60 ;;
+    UPGRADE_AVAILABLE*) TTL=720 ;;
+    *)                  TTL=0 ;;
+  esac
+  STALE=$(find "$CACHE_FILE" -mmin +"$TTL" 2>/dev/null || true)
+  if [ -z "$STALE" ] && [ "$TTL" -gt 0 ]; then
+    case "$CACHED" in
+      UP_TO_DATE*)
+        CV="$(echo "$CACHED" | awk '{print $2}')"
+        [ "$CV" = "$LOCAL" ] && exit 0
+        ;;
+      UPGRADE_AVAILABLE*)
+        CO="$(echo "$CACHED" | awk '{print $2}')"
+        if [ "$CO" = "$LOCAL" ]; then
+          CN="$(echo "$CACHED" | awk '{print $3}')"
+          check_snooze "$CN" && exit 0
+          echo "$CACHED"
+          exit 0
+        fi
+        ;;
+    esac
+  fi
+fi
+
+# Step 5: slow path — fetch latest from npm registry.
+mkdir -p "$STATE_DIR"
+RESP="$(curl -fsSL --max-time 5 "$REMOTE_URL" 2>/dev/null || true)"
+# Extract "version":"X.Y.Z" without jq.
+REMOTE="$(echo "$RESP" | grep -oE '"version"[[:space:]]*:[[:space:]]*"[^"]+"' | head -1 | sed -E 's/.*"([^"]+)"$/\1/')"
+REMOTE="$(echo "$REMOTE" | tr -d '[:space:]')"
+
+# Reject anything that doesn't look like a semver number.
+if ! echo "$REMOTE" | grep -qE '^[0-9]+\.[0-9]+\.[0-9]+'; then
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+if [ "$LOCAL" = "$REMOTE" ]; then
+  echo "UP_TO_DATE $LOCAL" > "$CACHE_FILE"
+  exit 0
+fi
+
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE" > "$CACHE_FILE"
+check_snooze "$REMOTE" && exit 0
+echo "UPGRADE_AVAILABLE $LOCAL $REMOTE"

package/install.js

@@ -27,7 +27,54 @@ const os = require('node:os');
 
 const VERSION = require('./package.json').version;
 const PACKAGE_ROOT = __dirname;
-const SKILLS_SRC = path.join(PACKAGE_ROOT, 'skills');
+const PKG_SKILLS = path.join(PACKAGE_ROOT, 'skills');
+const PKG_AGENTS = path.join(PACKAGE_ROOT, 'agents');
+
+// Installer-owned stable path. Mirrors gstack's ~/.claude/skills/gstack/
+// approach: package contents get copied here so symlinks target a path that
+// never moves, even when npm/npx wipes the original package directory.
+const VRUUM_ROOT = path.join(os.homedir(), '.vruum');
+const VRUUM_SKILLS = path.join(VRUUM_ROOT, 'skills');
+const VRUUM_AGENTS = path.join(VRUUM_ROOT, 'agents');
+const VRUUM_BIN = path.join(VRUUM_ROOT, 'bin');
+const VRUUM_VERSION_FILE = path.join(VRUUM_ROOT, 'VERSION');
+const PKG_BIN = path.join(PACKAGE_ROOT, 'bin');
+
+// Prelude prepended to every SKILL.md as it lands in ~/.vruum/skills/. Runs
+// an update check (1h cache), then gives Claude natural-language instructions
+// for how to react. Mirrors gstack's preamble pattern but injected at install
+// time rather than via a template-gen step.
+const SKILL_PRELUDE = `## Preamble (run first)
+
+\`\`\`bash
+_UPD=$(~/.vruum/bin/vruum-skills-update-check 2>/dev/null || true)
+[ -n "$_UPD" ] && echo "$_UPD" || true
+\`\`\`
+
+If output shows \`UPGRADE_AVAILABLE <old> <new>\`: read \`~/.vruum/skills/vruum-skills-upgrade/SKILL.md\` and follow the inline upgrade flow. If \`~/.vruum/config.yaml\` has \`auto_upgrade: true\`, run the upgrade silently; otherwise AskUserQuestion with four options — (A) upgrade now, (B) upgrade with changelog preview, (C) snooze, (D) skip this session. If user picks snooze, bump the snooze level in \`~/.vruum/update-snoozed\` (format: \`<new_version> <level> <unix_epoch>\`; level 1 = 24h, 2 = 48h, 3+ = 7d). Then continue with the skill.
+
+If output shows \`JUST_UPGRADED <from> <to>\`: tell the user "Running @vruum/skills v{to} (just updated!)" in one line, then continue.
+
+Otherwise proceed silently with the skill below.
+
+---
+`;
+
+function injectPrelude(skillDir) {
+  const skillFile = path.join(skillDir, 'SKILL.md');
+  if (!fs.existsSync(skillFile)) return;
+  const raw = fs.readFileSync(skillFile, 'utf8');
+  // Find end of YAML frontmatter. If missing, inject at top.
+  let insertAt = 0;
+  if (raw.startsWith('---\n')) {
+    const end = raw.indexOf('\n---\n', 4);
+    if (end !== -1) insertAt = end + 5;
+  }
+  const before = raw.slice(0, insertAt);
+  const after = raw.slice(insertAt);
+  const patched = before + '\n' + SKILL_PRELUDE + '\n' + after.replace(/^\n+/, '');
+  fs.writeFileSync(skillFile, patched);
+}
 
 // Known harness skill directories. Add a target here when a new harness
 // lands on a stable skill-dir convention.
@@ -90,13 +137,56 @@ other assistants that don't yet support MCP prompts.`);
 }
 
 function listAvailableSkills() {
-  if (!fs.existsSync(SKILLS_SRC)) return [];
+  if (!fs.existsSync(PKG_SKILLS)) return [];
   return fs
-    .readdirSync(SKILLS_SRC, { withFileTypes: true })
+    .readdirSync(PKG_SKILLS, { withFileTypes: true })
     .filter((entry) => entry.isDirectory())
     .map((entry) => entry.name);
 }
 
+function syncVruumRoot({ dryRun }) {
+  if (dryRun) {
+    const rows = [
+      `would sync ${PKG_SKILLS} -> ${VRUUM_SKILLS} (with auto-update prelude)`,
+    ];
+    if (fs.existsSync(PKG_AGENTS)) rows.push(`would sync ${PKG_AGENTS} -> ${VRUUM_AGENTS}`);
+    if (fs.existsSync(PKG_BIN)) rows.push(`would sync ${PKG_BIN} -> ${VRUUM_BIN}`);
+    rows.push(`would write ${VRUUM_VERSION_FILE} = ${VERSION}`);
+    return rows;
+  }
+  fs.mkdirSync(VRUUM_ROOT, { recursive: true });
+
+  // Skills — copy then inject prelude in-place on the ~/.vruum/ copy.
+  fs.rmSync(VRUUM_SKILLS, { recursive: true, force: true });
+  fs.cpSync(PKG_SKILLS, VRUUM_SKILLS, { recursive: true });
+  for (const skillName of listAvailableSkills()) {
+    injectPrelude(path.join(VRUUM_SKILLS, skillName));
+  }
+  const rows = [`synced ${VRUUM_SKILLS} (prelude injected)`];
+
+  if (fs.existsSync(PKG_AGENTS)) {
+    fs.rmSync(VRUUM_AGENTS, { recursive: true, force: true });
+    fs.cpSync(PKG_AGENTS, VRUUM_AGENTS, { recursive: true });
+    rows.push(`synced ${VRUUM_AGENTS}`);
+  }
+
+  // Bin scripts — update-check needs to land at a stable path and be exec.
+  if (fs.existsSync(PKG_BIN)) {
+    fs.rmSync(VRUUM_BIN, { recursive: true, force: true });
+    fs.cpSync(PKG_BIN, VRUUM_BIN, { recursive: true });
+    for (const entry of fs.readdirSync(VRUUM_BIN)) {
+      fs.chmodSync(path.join(VRUUM_BIN, entry), 0o755);
+    }
+    rows.push(`synced ${VRUUM_BIN}`);
+  }
+
+  // VERSION file — read by vruum-skills-update-check as the local version.
+  fs.writeFileSync(VRUUM_VERSION_FILE, VERSION + '\n');
+  rows.push(`wrote ${VRUUM_VERSION_FILE} = ${VERSION}`);
+
+  return rows;
+}
+
 function ensureTargetDir(target, dryRun) {
   if (fs.existsSync(target)) return { created: false };
   if (dryRun) return { created: 'would' };
@@ -159,7 +249,7 @@ function commandInstall({ targets: extraTargets, dryRun }) {
   const skills = listAvailableSkills();
   if (skills.length === 0) {
     throw new Error(
-      `No skills found under ${SKILLS_SRC}. This looks like a broken package.`
+      `No skills found under ${PKG_SKILLS}. This looks like a broken package.`
     );
   }
   const targets = detectTargets(extraTargets);
@@ -173,6 +263,8 @@ function commandInstall({ targets: extraTargets, dryRun }) {
     process.exit(1);
   }
 
+  const syncRows = syncVruumRoot({ dryRun });
+
   const summary = [];
   for (const target of targets) {
     const { created } = ensureTargetDir(target.dir, dryRun);
@@ -182,14 +274,18 @@ function commandInstall({ targets: extraTargets, dryRun }) {
       summary.push({ target: target.dir, detail: 'created target dir' });
     }
     for (const skillName of skills) {
-      const srcAbs = path.join(SKILLS_SRC, skillName);
+      const srcAbs = path.join(VRUUM_SKILLS, skillName);
       summary.push(linkSkill({ name: skillName, srcAbs, target: target.dir, dryRun }));
     }
   }
 
   const prefix = dryRun ? '[dry-run] ' : '';
   console.log(`${prefix}@vruum/skills v${VERSION}`);
-  console.log(`${prefix}skills source: ${SKILLS_SRC}`);
+  console.log(`${prefix}package source: ${PACKAGE_ROOT}`);
+  console.log(`${prefix}stable root:    ${VRUUM_ROOT}`);
+  for (const row of syncRows) {
+    console.log(`  ${prefix}${row}`);
+  }
   for (const target of targets) {
     console.log(`${prefix}target: ${target.dir}${target.autoDetected ? ' (auto)' : ''}`);
   }
@@ -213,19 +309,25 @@ function commandInstall({ targets: extraTargets, dryRun }) {
 function commandUninstall({ targets: extraTargets, dryRun }) {
   const skills = listAvailableSkills();
   const targets = detectTargets(extraTargets);
+  const prefix = dryRun ? '[dry-run] ' : '';
+  console.log(`${prefix}@vruum/skills v${VERSION} uninstall`);
+
   if (targets.length === 0) {
-    console.error('No AI harness skill directories detected. Nothing to remove.');
-    return;
+    console.error('No AI harness skill directories detected.');
   }
 
-  const prefix = dryRun ? '[dry-run] ' : '';
-  console.log(`${prefix}@vruum/skills v${VERSION} uninstall`);
+  // A symlink is "ours" if it points into ~/.vruum/skills/. We accept any
+  // target there (not just the current skill name) so stale links from
+  // renamed skills still get cleaned up.
+  const isOurLink = (linkTarget) => {
+    const resolved = path.resolve(linkTarget);
+    return resolved.startsWith(VRUUM_SKILLS + path.sep) || resolved === VRUUM_SKILLS;
+  };
 
   for (const target of targets) {
     console.log(`${prefix}target: ${target.dir}`);
     for (const skillName of skills) {
       const dst = path.join(target.dir, skillName);
-      const srcAbs = path.join(SKILLS_SRC, skillName);
       let existing = null;
       try {
         const lstat = fs.lstatSync(dst);
@@ -242,7 +344,7 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
         console.log(`  ${prefix}not-installed  ${skillName}`);
         continue;
       }
-      if (existing.kind !== 'symlink' || existing.target !== srcAbs) {
+      if (existing.kind !== 'symlink' || !isOurLink(existing.target)) {
         console.log(`  ${prefix}skipped        ${skillName}  [not our symlink]`);
         continue;
       }
@@ -254,6 +356,33 @@ function commandUninstall({ targets: extraTargets, dryRun }) {
       }
     }
   }
+
+  // Only clean up our own subdirectories — ~/.vruum/ is a shared state dir
+  // (e.g. the .agents/ vruum-update-check keeps config.yaml + snooze state
+  // there, and both installers share that config).
+  for (const dir of [VRUUM_SKILLS, VRUUM_AGENTS, VRUUM_BIN]) {
+    if (!fs.existsSync(dir)) continue;
+    if (dryRun) {
+      console.log(`${prefix}would remove ${dir}`);
+    } else {
+      fs.rmSync(dir, { recursive: true, force: true });
+      console.log(`${prefix}removed ${dir}`);
+    }
+  }
+  if (fs.existsSync(VRUUM_VERSION_FILE)) {
+    if (dryRun) {
+      console.log(`${prefix}would remove ${VRUUM_VERSION_FILE}`);
+    } else {
+      fs.unlinkSync(VRUUM_VERSION_FILE);
+      console.log(`${prefix}removed ${VRUUM_VERSION_FILE}`);
+    }
+  }
+  // Best-effort rmdir the root if now empty; ignore ENOTEMPTY.
+  if (!dryRun && fs.existsSync(VRUUM_ROOT)) {
+    try { fs.rmdirSync(VRUUM_ROOT); } catch (err) {
+      if (err.code !== 'ENOTEMPTY' && err.code !== 'EEXIST') throw err;
+    }
+  }
 }
 
 function commandList({ targets: extraTargets }) {
@@ -273,7 +402,7 @@ function commandList({ targets: extraTargets }) {
     }
     for (const skillName of skills) {
       const dst = path.join(target.dir, skillName);
-      const srcAbs = path.join(SKILLS_SRC, skillName);
+      const srcAbs = path.join(VRUUM_SKILLS, skillName);
       try {
         const lstat = fs.lstatSync(dst);
         if (lstat.isSymbolicLink()) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vruum/skills",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "description": "Vruum AI skills for Claude Code, Codex CLI, and any AI assistant with a skill directory. Pairs with the Vruum MCP server at https://api.vruum.ai/mcp.",
   "license": "MIT",
   "repository": {
@@ -20,7 +20,8 @@
     "LICENSE",
     ".mcp.json",
     "skills/",
-    "agents/"
+    "agents/",
+    "bin/"
   ],
   "engines": {
     "node": ">=18"

package/skills/vruum-skills-upgrade/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: vruum-skills-upgrade
+description: "Upgrade @vruum/skills to the latest npm version and re-sync ~/.vruum/. Use when: upgrade vruum skills, update vruum, pull latest vruum skills, or when the preamble reports UPGRADE_AVAILABLE."
+---
+
+# /vruum-skills-upgrade
+
+Upgrade the `@vruum/skills` npm package + re-sync `~/.vruum/` + relink all harness skill dirs.
+
+## Inline upgrade flow (called from preamble)
+
+If the calling skill's preamble reported `UPGRADE_AVAILABLE <old> <new>`, follow this flow. It runs inline — when done, the original skill continues.
+
+### Step 1: decide whether to auto-upgrade
+
+Read `~/.vruum/config.yaml`. If it contains `auto_upgrade: true`, skip to Step 3 (silent upgrade). Otherwise go to Step 2.
+
+### Step 2: ask the user
+
+Use AskUserQuestion with these four options:
+
+- **A) Upgrade now** — run the upgrade, return a one-line confirmation, then continue with the original skill.
+- **B) Show changelog first** — fetch `https://raw.githubusercontent.com/vruum-gtm/skills/main/CHANGELOG.md`, show the section for the new version, then re-ask A/C/D.
+- **C) Snooze** — don't upgrade this session. Bump the snooze level:
+  ```bash
+  # Snooze format: "<version> <level> <epoch>". Level 1=24h, 2=48h, 3+=7d.
+  OLD_LEVEL=$(awk '{print $2}' ~/.vruum/update-snoozed 2>/dev/null || echo 0)
+  NEW_LEVEL=$((OLD_LEVEL + 1))
+  [ $NEW_LEVEL -gt 3 ] && NEW_LEVEL=3
+  echo "<new> $NEW_LEVEL $(date +%s)" > ~/.vruum/update-snoozed
+  ```
+  Replace `<new>` with the version the preamble reported.
+- **D) Skip this session** — do nothing, don't write snooze. Next session will re-prompt.
+
+### Step 3: run the upgrade
+
+Detect how `@vruum/skills` was installed (global vs npx) and pick the right command:
+
+```bash
+# If installed globally (vruum-skills is on PATH):
+if command -v vruum-skills >/dev/null 2>&1; then
+  OLD=$(cat ~/.vruum/VERSION 2>/dev/null || echo "unknown")
+  npm install -g @vruum/skills@latest
+  vruum-skills install
+  NEW=$(cat ~/.vruum/VERSION 2>/dev/null || echo "unknown")
+else
+  # npx-only install — refresh the npx cache and re-run.
+  OLD=$(cat ~/.vruum/VERSION 2>/dev/null || echo "unknown")
+  npx --yes @vruum/skills@latest install
+  NEW=$(cat ~/.vruum/VERSION 2>/dev/null || echo "unknown")
+fi
+
+# Write the just-upgraded marker so the next preamble greets with "just updated!".
+echo "$OLD" > ~/.vruum/just-upgraded-from
+rm -f ~/.vruum/last-update-check ~/.vruum/update-snoozed
+```
+
+### Step 4: report
+
+One line: `upgraded @vruum/skills $OLD → $NEW`. Then continue with the original skill.
+
+## Standalone mode (user invoked `/vruum-skills-upgrade` directly)
+
+Force a fresh check first, then run the flow above starting from Step 2:
+
+```bash
+~/.vruum/bin/vruum-skills-update-check --force
+```
+
+If the forced check returns nothing, report `already on latest (v$(cat ~/.vruum/VERSION))` and exit.
+
+## When something goes wrong
+
+- `npm install` fails with permissions → tell the user to re-run with `sudo` or fix their npm prefix. Don't auto-sudo.
+- `vruum-skills install` reports skipped skills → surface the conflict message verbatim; user needs to remove conflicting files.
+- Network failure on registry lookup → report `upgrade check failed, try again later` and continue with the original skill (don't block work on a transient fetch error).