@whitehatd/crag 0.0.1 → 0.2.1

package/src/update/skill-sync.js

@@ -0,0 +1,116 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { computeHash, readFrontmatter, isModified } = require('./integrity');
+const { compareVersions } = require('./version-check');
+
+const SKILLS = [
+  { name: 'pre-start-context', srcFile: 'pre-start-context.md', installDir: 'pre-start-context' },
+  { name: 'post-start-validation', srcFile: 'post-start-validation.md', installDir: 'post-start-validation' },
+];
+
+/**
+ * Verify a source file is a regular file (not a symlink) inside the crag package.
+ * Protects against symlink attacks where a malicious skill file could be redirected.
+ */
+function isTrustedSource(srcPath) {
+  try {
+    const lstat = fs.lstatSync(srcPath);
+    if (!lstat.isFile() || lstat.isSymbolicLink()) return false;
+    // Must be inside our own src/skills directory
+    const expectedRoot = path.resolve(path.join(__dirname, '..', 'skills'));
+    const real = fs.realpathSync(srcPath);
+    const rel = path.relative(expectedRoot, real);
+    return rel !== '' && !rel.startsWith('..') && !path.isAbsolute(rel);
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Sync installed skills with source skills.
+ * Options: { force: bool, dryRun: bool }
+ * Returns { updated: [], skipped: [], conflicted: [] }
+ */
+function syncSkills(targetDir, options = {}) {
+  const srcDir = path.join(__dirname, '..', 'skills');
+  const result = { updated: [], skipped: [], conflicted: [] };
+  const dryRun = !!options.dryRun;
+
+  for (const skill of SKILLS) {
+    const srcPath = path.join(srcDir, skill.srcFile);
+    const installPath = path.join(targetDir, '.claude', 'skills', skill.installDir, 'SKILL.md');
+    const workflowPath = path.join(targetDir, '.agents', 'workflows', skill.srcFile);
+
+    // Source skill must exist and be trusted (no symlinks to unexpected locations)
+    if (!fs.existsSync(srcPath)) continue;
+    if (!isTrustedSource(srcPath)) {
+      result.skipped.push({ name: skill.name, version: 'unknown', reason: 'untrusted source (symlink or out-of-tree)' });
+      continue;
+    }
+
+    const srcMeta = readFrontmatter(srcPath);
+    const srcVersion = srcMeta?.version || '0.0.0';
+
+    // If skill not installed yet, install it
+    if (!fs.existsSync(installPath)) {
+      if (!dryRun) {
+        const dir = path.dirname(installPath);
+        if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+        fs.copyFileSync(srcPath, installPath);
+
+        // Also copy workflow version
+        const wfDir = path.dirname(workflowPath);
+        if (!fs.existsSync(wfDir)) fs.mkdirSync(wfDir, { recursive: true });
+        const content = fs.readFileSync(srcPath, 'utf-8').replace(/^name:.*\n/m, '');
+        fs.writeFileSync(workflowPath, content);
+      }
+
+      result.updated.push({ name: skill.name, from: 'none', to: srcVersion });
+      continue;
+    }
+
+    // Compare versions
+    const installedMeta = readFrontmatter(installPath);
+    const installedVersion = installedMeta?.version || '0.0.0';
+
+    if (compareVersions(srcVersion, installedVersion) <= 0) {
+      result.skipped.push({ name: skill.name, version: installedVersion, reason: 'current' });
+      continue;
+    }
+
+    // Newer version available — check for local modifications
+    if (!options.force && isModified(installPath)) {
+      result.conflicted.push({
+        name: skill.name,
+        installed: installedVersion,
+        available: srcVersion,
+        reason: 'locally modified',
+      });
+      continue;
+    }
+
+    if (!dryRun) {
+      // Backup and update
+      if (options.force && isModified(installPath)) {
+        const backupPath = installPath + '.bak.' + Date.now();
+        fs.copyFileSync(installPath, backupPath);
+      }
+
+      fs.copyFileSync(srcPath, installPath);
+
+      // Update workflow copy
+      const wfDir = path.dirname(workflowPath);
+      if (!fs.existsSync(wfDir)) fs.mkdirSync(wfDir, { recursive: true });
+      const content = fs.readFileSync(srcPath, 'utf-8').replace(/^name:.*\n/m, '');
+      fs.writeFileSync(workflowPath, content);
+    }
+
+    result.updated.push({ name: skill.name, from: installedVersion, to: srcVersion });
+  }
+
+  return result;
+}
+
+module.exports = { syncSkills };

package/src/update/version-check.js

@@ -0,0 +1,156 @@
+'use strict';
+
+const https = require('https');
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const HOME = process.env.HOME || process.env.USERPROFILE || os.tmpdir();
+const CACHE_DIR = path.join(HOME, '.claude', 'crag');
+const CACHE_FILE = path.join(CACHE_DIR, 'update-check.json');
+const CACHE_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+const TIMEOUT_MS = 3000;
+
+/**
+ * Non-blocking update check. Reads from cache if fresh.
+ * Prints a one-line notice if a newer version is available.
+ * Never blocks, never throws.
+ *
+ * Opt-out: set CRAG_NO_UPDATE_CHECK=1 in environment.
+ */
+function checkOnce() {
+  if (process.env.CRAG_NO_UPDATE_CHECK === '1') return;
+
+  try {
+    // Read cache
+    if (fs.existsSync(CACHE_FILE)) {
+      let cache;
+      try {
+        cache = JSON.parse(fs.readFileSync(CACHE_FILE, 'utf-8'));
+      } catch {
+        // Corrupt cache — delete and re-fetch
+        try { fs.unlinkSync(CACHE_FILE); } catch {}
+        cache = null;
+      }
+
+      if (cache && typeof cache.checkedAt === 'number') {
+        const age = Date.now() - cache.checkedAt;
+        if (age < CACHE_TTL_MS) {
+          if (cache.updateAvailable) {
+            const current = require('../../package.json').version;
+            console.log(`  \x1b[33m↑\x1b[0m crag v${cache.latestVersion} available (you have v${current}). Run: npm update -g @whitehatd/crag`);
+          }
+          return;
+        }
+      }
+    }
+
+    // Cache is stale or missing — trigger background check
+    checkRegistry();
+  } catch {
+    // Silent failure — never block CLI
+  }
+}
+
+/**
+ * Fetch latest version from npm registry with timeout.
+ * Writes result to cache file atomically.
+ */
+function checkRegistry() {
+  const currentVersion = require('../../package.json').version;
+
+  const req = https.get('https://registry.npmjs.org/@whitehatd%2Fcrag/latest', { timeout: TIMEOUT_MS }, (res) => {
+    // Abort if status is non-OK
+    if (res.statusCode && (res.statusCode < 200 || res.statusCode >= 300)) {
+      res.resume(); // Drain to allow cleanup
+      return;
+    }
+
+    let data = '';
+    let size = 0;
+    const MAX_SIZE = 100 * 1024; // 100KB cap
+
+    res.on('data', (chunk) => {
+      size += chunk.length;
+      if (size > MAX_SIZE) {
+        res.destroy();
+        return;
+      }
+      data += chunk;
+    });
+
+    res.on('end', () => {
+      try {
+        const pkg = JSON.parse(data);
+        const latest = pkg.version;
+        if (typeof latest !== 'string') return;
+
+        const updateAvailable = compareVersions(latest, currentVersion) > 0;
+
+        if (!fs.existsSync(CACHE_DIR)) {
+          fs.mkdirSync(CACHE_DIR, { recursive: true });
+        }
+
+        // Atomic write: write to temp file, then rename
+        const tmp = CACHE_FILE + '.tmp.' + process.pid;
+        fs.writeFileSync(tmp, JSON.stringify({
+          checkedAt: Date.now(),
+          latestVersion: latest,
+          currentVersion,
+          updateAvailable,
+        }));
+        try {
+          fs.renameSync(tmp, CACHE_FILE);
+        } catch {
+          // Another process wrote first — that's fine
+          try { fs.unlinkSync(tmp); } catch {}
+        }
+
+        if (updateAvailable) {
+          console.log(`  \x1b[33m↑\x1b[0m crag v${latest} available (you have v${currentVersion}). Run: npm update -g @whitehatd/crag`);
+        }
+      } catch {
+        // Malformed response — ignore
+      }
+    });
+
+    res.on('error', () => { /* ignore */ });
+  });
+
+  req.on('error', () => { /* Network error — silent */ });
+  req.on('timeout', () => { req.destroy(); });
+
+  // Don't let the request keep the process alive
+  if (req.unref) req.unref();
+}
+
+/**
+ * Compare two semver version strings.
+ * Returns >0 if a > b, <0 if a < b, 0 if equal.
+ * Handles x.y.z and x.y.z-prerelease formats.
+ * Pre-release versions are less than their release counterparts.
+ */
+function compareVersions(a, b) {
+  const parse = (v) => {
+    const [core, prerelease] = String(v).split('-', 2);
+    const parts = core.split('.').map(n => parseInt(n, 10) || 0);
+    while (parts.length < 3) parts.push(0);
+    return { core: parts.slice(0, 3), prerelease: prerelease || null };
+  };
+
+  const pa = parse(a);
+  const pb = parse(b);
+
+  for (let i = 0; i < 3; i++) {
+    if (pa.core[i] !== pb.core[i]) return pa.core[i] - pb.core[i];
+  }
+
+  // Core versions equal — pre-release comparison
+  // No prerelease > has prerelease (e.g., 1.0.0 > 1.0.0-beta)
+  if (!pa.prerelease && pb.prerelease) return 1;
+  if (pa.prerelease && !pb.prerelease) return -1;
+  if (!pa.prerelease && !pb.prerelease) return 0;
+  return pa.prerelease.localeCompare(pb.prerelease);
+}
+
+module.exports = { checkOnce, checkRegistry, compareVersions, CACHE_FILE };

package/src/workspace/detect.js

@@ -0,0 +1,190 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Detect workspace type by walking up from startDir.
+ * Returns { type, root, configFile, members: [], warnings: [] }
+ *
+ * Warnings surface parse errors (vs. missing files) so users know when a
+ * workspace config was present but broken.
+ *
+ * Supported types (in priority order):
+ *   pnpm, npm, yarn, cargo, go, gradle, maven, nx, turbo,
+ *   bazel, git-submodules, independent-repos, none
+ */
+function detectWorkspace(startDir) {
+  let current = path.resolve(startDir);
+  const warnings = [];
+
+  const wrap = (result) => ({ ...result, warnings });
+
+  while (true) {
+    // 1. pnpm workspaces
+    const pnpmWs = path.join(current, 'pnpm-workspace.yaml');
+    if (fs.existsSync(pnpmWs)) {
+      return wrap({ type: 'pnpm', root: current, configFile: 'pnpm-workspace.yaml', members: [] });
+    }
+
+    // 2. npm/yarn workspaces (package.json with "workspaces")
+    const pkgPath = path.join(current, 'package.json');
+    if (fs.existsSync(pkgPath)) {
+      try {
+        const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
+        if (pkg.workspaces) {
+          const patterns = Array.isArray(pkg.workspaces) ? pkg.workspaces : (pkg.workspaces.packages || []);
+          return wrap({ type: 'npm', root: current, configFile: 'package.json', members: [], patterns });
+        }
+      } catch (err) {
+        warnings.push(`malformed package.json at ${pkgPath}: ${err.message}`);
+      }
+    }
+
+    // 3. Cargo workspace
+    const cargoPath = path.join(current, 'Cargo.toml');
+    if (fs.existsSync(cargoPath)) {
+      try {
+        const content = fs.readFileSync(cargoPath, 'utf-8');
+        if (content.includes('[workspace]')) {
+          const membersMatch = content.match(/members\s*=\s*\[([\s\S]*?)\]/);
+          const patterns = membersMatch
+            ? membersMatch[1].match(/"([^"]+)"/g)?.map(m => m.replace(/"/g, '')) || []
+            : [];
+          return wrap({ type: 'cargo', root: current, configFile: 'Cargo.toml', members: [], patterns });
+        }
+      } catch (err) {
+        warnings.push(`malformed Cargo.toml at ${cargoPath}: ${err.message}`);
+      }
+    }
+
+    // 4. Go workspace
+    const goWork = path.join(current, 'go.work');
+    if (fs.existsSync(goWork)) {
+      try {
+        const content = fs.readFileSync(goWork, 'utf-8');
+        const useMatch = content.match(/use\s*\(([\s\S]*?)\)/);
+        const patterns = useMatch
+          ? useMatch[1].split('\n').map(l => l.trim()).filter(l => l && !l.startsWith('//'))
+          : [];
+        return wrap({ type: 'go', root: current, configFile: 'go.work', members: [], patterns });
+      } catch (err) {
+        warnings.push(`malformed go.work at ${goWork}: ${err.message}`);
+      }
+    }
+
+    // 5. Gradle multi-project
+    for (const gradleFile of ['settings.gradle.kts', 'settings.gradle']) {
+      const gradlePath = path.join(current, gradleFile);
+      if (fs.existsSync(gradlePath)) {
+        try {
+          const content = fs.readFileSync(gradlePath, 'utf-8');
+          if (content.includes('include(') || content.includes('include ')) {
+            const includes = [];
+            const regex = /include\s*\(\s*["']([^"']+)["']/g;
+            let m;
+            while ((m = regex.exec(content)) !== null) includes.push(m[1].replace(/:/g, '/'));
+            // Also match Groovy-style: include 'module'
+            const groovyRegex = /include\s+['"]([^'"]+)['"]/g;
+            while ((m = groovyRegex.exec(content)) !== null) includes.push(m[1].replace(/:/g, '/'));
+            return wrap({ type: 'gradle', root: current, configFile: gradleFile, members: [], patterns: includes });
+          }
+        } catch (err) {
+          warnings.push(`malformed ${gradleFile} at ${gradlePath}: ${err.message}`);
+        }
+      }
+    }
+
+    // 6. Maven multi-module
+    const pomPath = path.join(current, 'pom.xml');
+    if (fs.existsSync(pomPath)) {
+      try {
+        const content = fs.readFileSync(pomPath, 'utf-8');
+        if (content.includes('<modules>')) {
+          const modules = [];
+          const regex = /<module>([^<]+)<\/module>/g;
+          let m;
+          while ((m = regex.exec(content)) !== null) modules.push(m[1]);
+          if (modules.length > 0) {
+            return wrap({ type: 'maven', root: current, configFile: 'pom.xml', members: [], patterns: modules });
+          }
+        }
+      } catch (err) {
+        warnings.push(`malformed pom.xml at ${pomPath}: ${err.message}`);
+      }
+    }
+
+    // 7. Nx
+    if (fs.existsSync(path.join(current, 'nx.json'))) {
+      return wrap({ type: 'nx', root: current, configFile: 'nx.json', members: [] });
+    }
+
+    // 8. Turborepo
+    if (fs.existsSync(path.join(current, 'turbo.json'))) {
+      return wrap({ type: 'turbo', root: current, configFile: 'turbo.json', members: [] });
+    }
+
+    // 9. Bazel
+    for (const bazelFile of ['WORKSPACE', 'WORKSPACE.bazel', 'MODULE.bazel']) {
+      if (fs.existsSync(path.join(current, bazelFile))) {
+        return wrap({ type: 'bazel', root: current, configFile: bazelFile, members: [] });
+      }
+    }
+
+    // 10. Git submodules
+    const gitmodulesPath = path.join(current, '.gitmodules');
+    if (fs.existsSync(gitmodulesPath)) {
+      try {
+        const content = fs.readFileSync(gitmodulesPath, 'utf-8');
+        const submodules = [];
+        const regex = /\[submodule\s+"([^"]+)"\][\s\S]*?path\s*=\s*(.+)/g;
+        let m;
+        while ((m = regex.exec(content)) !== null) {
+          submodules.push({ name: m[1].trim(), path: m[2].trim() });
+        }
+        return wrap({ type: 'git-submodules', root: current, configFile: '.gitmodules', members: [], submodules });
+      } catch (err) {
+        warnings.push(`malformed .gitmodules at ${gitmodulesPath}: ${err.message}`);
+      }
+    }
+
+    // Stop at git root (if reached without finding workspace markers)
+    if (fs.existsSync(path.join(current, '.git'))) {
+      // Check for independent nested repos (multiple .git dirs in children)
+      const nestedRepos = findNestedRepos(current);
+      if (nestedRepos.length >= 2) {
+        return wrap({ type: 'independent-repos', root: current, configFile: null, members: [], nestedRepos });
+      }
+      // Single repo, no workspace
+      return wrap({ type: 'none', root: current, configFile: null, members: [] });
+    }
+
+    // Move up
+    const parent = path.dirname(current);
+    if (parent === current) break; // Filesystem root
+    current = parent;
+  }
+
+  return wrap({ type: 'none', root: startDir, configFile: null, members: [] });
+}
+
+/**
+ * Scan immediate child directories for independent git repos.
+ */
+function findNestedRepos(dir) {
+  const repos = [];
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || entry.name === 'node_modules') continue;
+      const childGit = path.join(dir, entry.name, '.git');
+      if (fs.existsSync(childGit)) {
+        repos.push({ name: entry.name, path: path.join(dir, entry.name) });
+      }
+    }
+  } catch { /* permission error — skip */ }
+  return repos;
+}
+
+module.exports = { detectWorkspace, findNestedRepos };