voraiguard 0.1.2

package/README.md

@@ -0,0 +1,31 @@
+# Vorai Guard (MVP)
+
+## Install
+
+```bash
+npm i -g voraiguard
+```
+
+## Use
+
+```bash
+voraiguard init .
+voraiguard watch .
+```
+
+## What it does
+
+Stops AI tools from deleting or corrupting your code.
+
+Detects risky changes and lets you approve or rollback instantly.
+
+## 10-second demo
+
+```text
+🚨 Risky change detected
+Reasons:
+- 12 files changed
+- Size shrink: 41%
+
+[A]pprove [R]ollback
+```

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "voraiguard",
+  "version": "0.1.2",
+  "description": "Vorai Guard — detects risky file changes and can auto-rollback with local snapshots.",
+  "license": "UNLICENSED",
+  "type": "commonjs",
+  "bin": {
+    "voraiguard": "src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "dev": "node src/cli.js",
+    "start": "node src/cli.js",
+    "test": "node -e \"console.log('no tests yet')\""
+  },
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "fast-glob": "^3.3.2",
+    "inquirer": "^8.2.6"
+  }
+}

package/src/cli.js

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+
+const path = require('path');
+const fs = require('fs');
+const fsp = fs.promises;
+
+const { watchProject } = require('./lib/watcher');
+const { listSnapshots, restoreSnapshot, getLatestSnapshotId } = require('./lib/snapshot');
+const { loadConfig } = require('./lib/config');
+
+async function ensureGitignoreHasSnapshots(projectRoot) {
+  const gitignorePath = path.join(projectRoot, '.gitignore');
+  const line = '.voraiguard/snapshots/';
+  const broadIgnores = new Set(['.voraiguard/', '.voraiguard', '.voraiguard/*']);
+
+  let existing = '';
+  try {
+    existing = await fsp.readFile(gitignorePath, 'utf8');
+  } catch {
+    existing = '';
+  }
+
+  const inputLines = existing.split(/\r?\n/);
+
+  let removedBroad = 0;
+  const kept = [];
+  for (const l of inputLines) {
+    const t = l.trim();
+    if (broadIgnores.has(t)) {
+      removedBroad++;
+      continue;
+    }
+    kept.push(l);
+  }
+
+  const hasSnapshotsIgnore = kept.some((l) => l.trim() === line);
+  if (!hasSnapshotsIgnore) kept.push(line);
+
+  // Ensure trailing newline.
+  let next = kept.join('\n');
+  if (!next.endsWith('\n')) next += '\n';
+
+  const changed = next !== existing;
+  if (changed) await fsp.writeFile(gitignorePath, next, 'utf8');
+  return { changed, removedBroad, addedSnapshotsIgnore: !hasSnapshotsIgnore };
+}
+
+function printVersion() {
+  // Read from package.json so it's always the published version.
+  // eslint-disable-next-line import/no-dynamic-require
+  const pkg = require('../package.json');
+  console.log(pkg.version);
+}
+
+function printHelp() {
+  console.log(`Vorai Guard (MVP)
+
+Usage:
+  voraiguard watch [folder]
+  voraiguard init [folder]
+  voraiguard list [folder]
+  voraiguard restore [folder] [snapshotId]
+  voraiguard version
+
+Notes:
+  - Snapshots live inside the watched folder at .voraiguard/snapshots
+  - This is local-only and intentionally minimal.`);
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+  const cmd = (args[0] || '').toLowerCase();
+
+  if (cmd === '--version' || cmd === '-v') {
+    printVersion();
+    process.exit(0);
+  }
+
+  if (cmd === 'version') {
+    printVersion();
+    process.exit(0);
+  }
+
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    printHelp();
+    process.exit(0);
+  }
+
+  if (cmd === 'watch') {
+    const folder = path.resolve(args[1] || process.cwd());
+    if (!fs.existsSync(folder)) {
+      console.error(`Folder not found: ${folder}`);
+      process.exit(1);
+    }
+    await watchProject(folder);
+    return;
+  }
+
+  if (cmd === 'init') {
+    const folder = path.resolve(args[1] || process.cwd());
+    if (!fs.existsSync(folder)) {
+      console.error(`Folder not found: ${folder}`);
+      process.exit(1);
+    }
+
+    await loadConfig(folder);
+    const result = await ensureGitignoreHasSnapshots(folder);
+    console.log(`Initialized Vorai Guard in: ${folder}`);
+    console.log('Created/verified: .voraiguard/config.json');
+    if (result.changed) {
+      if (result.removedBroad > 0) console.log('Updated: .gitignore (now tracking .voraiguard/config.json)');
+      if (result.addedSnapshotsIgnore) console.log('Updated: .gitignore (ignored .voraiguard/snapshots/)');
+    }
+    return;
+  }
+
+  if (cmd === 'list') {
+    const folder = path.resolve(args[1] || process.cwd());
+    const snaps = await listSnapshots(folder);
+    if (snaps.length === 0) {
+      console.log('No snapshots found.');
+      return;
+    }
+    for (const s of snaps) console.log(`${s.id}\t${s.createdAt}`);
+    return;
+  }
+
+  if (cmd === 'restore') {
+    const folder = path.resolve(args[1] || process.cwd());
+    const snapshotId = args[2] || (await getLatestSnapshotId(folder));
+    if (!snapshotId) {
+      console.error('No snapshot available to restore.');
+      process.exit(1);
+    }
+    await restoreSnapshot(folder, snapshotId);
+    console.log(`Restored snapshot: ${snapshotId}`);
+    return;
+  }
+
+  console.error(`Unknown command: ${cmd}`);
+  printHelp();
+  process.exit(1);
+}
+
+main().catch((err) => {
+  console.error(err && err.stack ? err.stack : String(err));
+  process.exit(1);
+});

package/src/lib/README.md

@@ -0,0 +1,6 @@
+Internal modules:
+
+- watcher.js: chokidar batching + approve/revert prompt
+- snapshot.js: local snapshot/restore under .voraiguard
+- state.js: file hash/size/function count scan + diffs
+- risk.js: thresholds and heuristics

package/src/lib/config.js

@@ -0,0 +1,39 @@
+const path = require('path');
+const fs = require('fs');
+const { ensureDir } = require('./fsutil');
+
+const DEFAULTS = {
+  debounceMs: 750,
+  burstWindowMs: 3000,
+  burstEventThreshold: 20,
+  burstFileThreshold: 8,
+  maxFilesChanged: 10,
+  shrinkPercentTrigger: 30,
+  maxDeletedFiles: 0,
+  functionDropPercentTrigger: 30,
+  renameStormMin: 10
+};
+
+function configPath(projectRoot) {
+  return path.join(projectRoot, '.voraiguard', 'config.json');
+}
+
+async function loadConfig(projectRoot) {
+  const cfgPath = configPath(projectRoot);
+  await ensureDir(path.dirname(cfgPath));
+
+  if (!fs.existsSync(cfgPath)) {
+    fs.writeFileSync(cfgPath, JSON.stringify(DEFAULTS, null, 2));
+    return { ...DEFAULTS };
+  }
+
+  try {
+    const raw = fs.readFileSync(cfgPath, 'utf8');
+    const parsed = JSON.parse(raw);
+    return { ...DEFAULTS, ...(parsed || {}) };
+  } catch {
+    return { ...DEFAULTS };
+  }
+}
+
+module.exports = { loadConfig, DEFAULTS };

package/src/lib/fsutil.js

@@ -0,0 +1,75 @@
+const fs = require('fs');
+const fsp = fs.promises;
+const path = require('path');
+const crypto = require('crypto');
+
+async function ensureDir(dirPath) {
+  await fsp.mkdir(dirPath, { recursive: true });
+}
+
+function isPathInside(childPath, parentPath) {
+  const rel = path.relative(parentPath, childPath);
+  return !!rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+}
+
+function normalizeRel(projectRoot, absPath) {
+  const rel = path.relative(projectRoot, absPath);
+  return rel.split(path.sep).join('/');
+}
+
+function shouldIgnoreRel(rel) {
+  const parts = rel.split('/');
+  if (parts.includes('node_modules')) return true;
+  if (parts.includes('.git')) return true;
+  if (parts[0] === '.voraiguard') return true;
+  return false;
+}
+
+async function fileHash(absPath) {
+  const h = crypto.createHash('sha256');
+  const stream = fs.createReadStream(absPath);
+  return await new Promise((resolve, reject) => {
+    stream.on('data', (d) => h.update(d));
+    stream.on('error', reject);
+    stream.on('end', () => resolve(h.digest('hex')));
+  });
+}
+
+function looksLikeText(buf) {
+  // Simple heuristic: if it contains a NUL byte, treat as binary.
+  for (let i = 0; i < buf.length; i++) {
+    if (buf[i] === 0) return false;
+  }
+  return true;
+}
+
+async function readTextFile(absPath, maxBytes = 1024 * 1024) {
+  const buf = await fsp.readFile(absPath);
+  if (!looksLikeText(buf)) return null;
+  const sliced = buf.length > maxBytes ? buf.subarray(0, maxBytes) : buf;
+  return sliced.toString('utf8');
+}
+
+async function copyFilePreserveDirs(srcAbs, destAbs) {
+  await ensureDir(path.dirname(destAbs));
+  await fsp.copyFile(srcAbs, destAbs);
+}
+
+async function rmIfExists(absPath) {
+  try {
+    await fsp.rm(absPath, { recursive: true, force: true });
+  } catch {
+    // ignore
+  }
+}
+
+module.exports = {
+  ensureDir,
+  isPathInside,
+  normalizeRel,
+  shouldIgnoreRel,
+  fileHash,
+  readTextFile,
+  copyFilePreserveDirs,
+  rmIfExists
+};

package/src/lib/index.js

@@ -0,0 +1 @@
+// reserved for future shared exports

package/src/lib/risk.js

@@ -0,0 +1,57 @@
+function pctDrop(before, after) {
+  if (before <= 0) return 0;
+  const drop = before - after;
+  return (drop / before) * 100;
+}
+
+function evaluateRisk(diff, cfg, context = {}) {
+  const reasons = [];
+
+  {
+    const burstEvents = typeof context.burstEvents === 'number' ? context.burstEvents : 0;
+    const burstFiles = typeof context.burstFiles === 'number' ? context.burstFiles : 0;
+    const windowMs = typeof cfg.burstWindowMs === 'number' ? cfg.burstWindowMs : 3000;
+    const eventThresh = typeof cfg.burstEventThreshold === 'number' ? cfg.burstEventThreshold : 20;
+    const fileThresh = typeof cfg.burstFileThreshold === 'number' ? cfg.burstFileThreshold : 8;
+
+    if (burstEvents >= eventThresh || burstFiles >= fileThresh) {
+      reasons.push(
+        `Burst editing detected (${burstEvents} events, ${burstFiles} files within ${Math.round(windowMs / 1000)}s)`
+      );
+    }
+  }
+
+  if (diff.changedCount >= cfg.maxFilesChanged) {
+    reasons.push(`Many files changed at once (${diff.changedCount} >= ${cfg.maxFilesChanged})`);
+  }
+
+  if (diff.deleted.length > cfg.maxDeletedFiles) {
+    reasons.push(`File deletions detected (${diff.deleted.length})`);
+  }
+
+  if (diff.sizeBeforeChanged > 0) {
+    const shrink = pctDrop(diff.sizeBeforeChanged, diff.sizeAfterChanged);
+    if (shrink >= cfg.shrinkPercentTrigger) {
+      reasons.push(`Size shrink across changed files (${shrink.toFixed(1)}% >= ${cfg.shrinkPercentTrigger}%)`);
+    }
+  }
+
+  if (diff.funcBeforeChanged > 0) {
+    const fdrop = pctDrop(diff.funcBeforeChanged, diff.funcAfterChanged);
+    if (fdrop >= cfg.functionDropPercentTrigger) {
+      reasons.push(`Function count drop in changed files (${fdrop.toFixed(1)}% >= ${cfg.functionDropPercentTrigger}%)`);
+    }
+  }
+
+  // Rename storm heuristic: many adds + deletes together.
+  if ((diff.added.length + diff.deleted.length) >= cfg.renameStormMin && diff.deleted.length > 0 && diff.added.length > 0) {
+    reasons.push(`Possible rename storm (added ${diff.added.length}, deleted ${diff.deleted.length})`);
+  }
+
+  return {
+    risky: reasons.length > 0,
+    reasons
+  };
+}
+
+module.exports = { evaluateRisk };

package/src/lib/snapshot.js

@@ -0,0 +1,131 @@
+const path = require('path');
+const fs = require('fs');
+const fsp = fs.promises;
+const fg = require('fast-glob');
+
+const { ensureDir, shouldIgnoreRel, copyFilePreserveDirs, rmIfExists } = require('./fsutil');
+
+function guardRoot(projectRoot) {
+  return path.join(projectRoot, '.voraiguard');
+}
+
+function snapshotsRoot(projectRoot) {
+  return path.join(guardRoot(projectRoot), 'snapshots');
+}
+
+function snapshotPath(projectRoot, snapshotId) {
+  return path.join(snapshotsRoot(projectRoot), snapshotId);
+}
+
+function nowId() {
+  const d = new Date();
+  const pad = (n) => String(n).padStart(2, '0');
+  return `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}_${pad(d.getHours())}${pad(d.getMinutes())}${pad(d.getSeconds())}`;
+}
+
+async function createSnapshot(projectRoot, meta = {}) {
+  const id = nowId();
+  const root = snapshotPath(projectRoot, id);
+  const filesDir = path.join(root, 'files');
+
+  await ensureDir(filesDir);
+
+  const entries = await fg(['**/*'], {
+    cwd: projectRoot,
+    onlyFiles: true,
+    dot: true,
+    followSymbolicLinks: false
+  });
+
+  for (const rel of entries) {
+    const relNorm = rel.split('\\').join('/');
+    if (shouldIgnoreRel(relNorm)) continue;
+    const srcAbs = path.join(projectRoot, rel);
+    const destAbs = path.join(filesDir, relNorm);
+    try {
+      await copyFilePreserveDirs(srcAbs, destAbs);
+    } catch {
+      // ignore transient read errors
+    }
+  }
+
+  const manifest = {
+    id,
+    createdAt: new Date().toISOString(),
+    meta
+  };
+  await fsp.writeFile(path.join(root, 'manifest.json'), JSON.stringify(manifest, null, 2), 'utf8');
+  return id;
+}
+
+async function listSnapshots(projectRoot) {
+  const root = snapshotsRoot(projectRoot);
+  if (!fs.existsSync(root)) return [];
+
+  const dirs = (await fsp.readdir(root, { withFileTypes: true }))
+    .filter((d) => d.isDirectory())
+    .map((d) => d.name)
+    .sort();
+
+  const out = [];
+  for (const id of dirs) {
+    const manifestPath = path.join(root, id, 'manifest.json');
+    try {
+      const raw = await fsp.readFile(manifestPath, 'utf8');
+      const m = JSON.parse(raw);
+      out.push({ id, createdAt: m.createdAt || '' });
+    } catch {
+      out.push({ id, createdAt: '' });
+    }
+  }
+  return out;
+}
+
+async function getLatestSnapshotId(projectRoot) {
+  const snaps = await listSnapshots(projectRoot);
+  if (snaps.length === 0) return null;
+  return snaps[snaps.length - 1].id;
+}
+
+async function restoreSnapshot(projectRoot, snapshotId) {
+  const root = snapshotPath(projectRoot, snapshotId);
+  const filesDir = path.join(root, 'files');
+
+  if (!fs.existsSync(filesDir)) {
+    throw new Error(`Snapshot not found: ${snapshotId}`);
+  }
+
+  // Remove current project files (excluding ignored), then copy from snapshot.
+  const current = await fg(['**/*'], {
+    cwd: projectRoot,
+    onlyFiles: true,
+    dot: true,
+    followSymbolicLinks: false
+  });
+
+  for (const rel of current) {
+    const relNorm = rel.split('\\').join('/');
+    if (shouldIgnoreRel(relNorm)) continue;
+    await rmIfExists(path.join(projectRoot, rel));
+  }
+
+  const snapFiles = await fg(['**/*'], {
+    cwd: filesDir,
+    onlyFiles: true,
+    dot: true,
+    followSymbolicLinks: false
+  });
+
+  for (const rel of snapFiles) {
+    const srcAbs = path.join(filesDir, rel);
+    const destAbs = path.join(projectRoot, rel);
+    await copyFilePreserveDirs(srcAbs, destAbs);
+  }
+}
+
+module.exports = {
+  createSnapshot,
+  listSnapshots,
+  getLatestSnapshotId,
+  restoreSnapshot
+};

package/src/lib/state.js

@@ -0,0 +1,100 @@
+const path = require('path');
+const fg = require('fast-glob');
+const fs = require('fs');
+
+const { normalizeRel, shouldIgnoreRel, fileHash, readTextFile } = require('./fsutil');
+const { estimateFunctionCount } = require('./textmetrics');
+
+async function scanProjectState(projectRoot) {
+  const entries = await fg(['**/*'], {
+    cwd: projectRoot,
+    onlyFiles: true,
+    dot: true,
+    followSymbolicLinks: false
+  });
+
+  const files = {};
+  let totalFunctionCount = 0;
+
+  for (const rel of entries) {
+    const relNorm = rel.split('\\').join('/');
+    if (shouldIgnoreRel(relNorm)) continue;
+
+    const abs = path.join(projectRoot, rel);
+    let stat;
+    try {
+      stat = fs.statSync(abs);
+    } catch {
+      continue;
+    }
+
+    const size = stat.size;
+    const hash = await fileHash(abs);
+
+    let funcCount = 0;
+    const text = await readTextFile(abs);
+    if (text != null) funcCount = estimateFunctionCount(relNorm, text);
+
+    totalFunctionCount += funcCount;
+    files[relNorm] = { size, hash, funcCount };
+  }
+
+  return { files, totalFunctionCount };
+}
+
+function diffStates(before, after) {
+  const beforeFiles = before.files || {};
+  const afterFiles = after.files || {};
+
+  const beforeSet = new Set(Object.keys(beforeFiles));
+  const afterSet = new Set(Object.keys(afterFiles));
+
+  const deleted = [];
+  const added = [];
+  const modified = [];
+
+  for (const f of beforeSet) {
+    if (!afterSet.has(f)) {
+      deleted.push(f);
+      continue;
+    }
+    if (beforeFiles[f].hash !== afterFiles[f].hash) modified.push(f);
+  }
+
+  for (const f of afterSet) {
+    if (!beforeSet.has(f)) added.push(f);
+  }
+
+  const changed = [...new Set([...added, ...modified, ...deleted])];
+
+  let sizeBeforeChanged = 0;
+  let sizeAfterChanged = 0;
+  let funcBeforeChanged = 0;
+  let funcAfterChanged = 0;
+
+  for (const f of changed) {
+    if (beforeFiles[f]) {
+      sizeBeforeChanged += beforeFiles[f].size || 0;
+      funcBeforeChanged += beforeFiles[f].funcCount || 0;
+    }
+    if (afterFiles[f]) {
+      sizeAfterChanged += afterFiles[f].size || 0;
+      funcAfterChanged += afterFiles[f].funcCount || 0;
+    }
+  }
+
+  return {
+    added,
+    modified,
+    deleted,
+    changedCount: changed.length,
+    sizeBeforeChanged,
+    sizeAfterChanged,
+    funcBeforeChanged,
+    funcAfterChanged,
+    totalFuncBefore: before.totalFunctionCount || 0,
+    totalFuncAfter: after.totalFunctionCount || 0
+  };
+}
+
+module.exports = { scanProjectState, diffStates };

package/src/lib/textmetrics.js

@@ -0,0 +1,67 @@
+const path = require('path');
+
+const SUPPORTED_EXTS = new Set([
+  '.js', '.jsx', '.ts', '.tsx',
+  '.py', '.go', '.java', '.cs',
+  '.rb', '.php', '.rs', '.kt'
+]);
+
+function estimateFunctionCount(relPath, text) {
+  const ext = path.extname(relPath).toLowerCase();
+  if (!SUPPORTED_EXTS.has(ext)) return 0;
+
+  // Intentionally simple heuristics (MVP).
+  let count = 0;
+
+  // JS/TS: function foo(, foo = ( ... ) =>, ( ... ) => { ... }
+  if (ext === '.js' || ext === '.jsx' || ext === '.ts' || ext === '.tsx') {
+    const fnDecl = /\bfunction\s+[A-Za-z0-9_$]+\s*\(/g;
+    const arrow = /=>\s*\{/g;
+    const methodLike = /\b[A-Za-z0-9_$]+\s*\([^\n]*\)\s*\{/g;
+    count += (text.match(fnDecl) || []).length;
+    count += (text.match(arrow) || []).length;
+    // methodLike is noisy; keep it light to avoid overcounting.
+    count += Math.floor((text.match(methodLike) || []).length * 0.25);
+    return count;
+  }
+
+  // Python
+  if (ext === '.py') {
+    const defs = /^\s*def\s+[A-Za-z0-9_]+\s*\(/gm;
+    return (text.match(defs) || []).length;
+  }
+
+  // Go
+  if (ext === '.go') {
+    const funcs = /^\s*func\s+(\([^)]+\)\s*)?[A-Za-z0-9_]+\s*\(/gm;
+    return (text.match(funcs) || []).length;
+  }
+
+  // Java/C#/Kotlin
+  if (ext === '.java' || ext === '.cs' || ext === '.kt') {
+    const methods = /\b(public|private|protected|internal)?\s*(static\s+)?[A-Za-z0-9_<>\[\]]+\s+[A-Za-z0-9_]+\s*\([^;{]*\)\s*\{/g;
+    return Math.floor((text.match(methods) || []).length * 0.8);
+  }
+
+  // Rust
+  if (ext === '.rs') {
+    const fns = /^\s*fn\s+[A-Za-z0-9_]+\s*\(/gm;
+    return (text.match(fns) || []).length;
+  }
+
+  // Ruby
+  if (ext === '.rb') {
+    const defs = /^\s*def\s+[A-Za-z0-9_!?]+/gm;
+    return (text.match(defs) || []).length;
+  }
+
+  // PHP
+  if (ext === '.php') {
+    const defs = /\bfunction\s+[A-Za-z0-9_]+\s*\(/g;
+    return (text.match(defs) || []).length;
+  }
+
+  return 0;
+}
+
+module.exports = { estimateFunctionCount };

package/src/lib/version.js

@@ -0,0 +1 @@
+module.exports = { version: '0.1.0' };

package/src/lib/watcher.js

@@ -0,0 +1,167 @@
+const chokidar = require('chokidar');
+const inquirer = require('inquirer');
+
+const { loadConfig } = require('./config');
+const { scanProjectState, diffStates } = require('./state');
+const { createSnapshot, restoreSnapshot, getLatestSnapshotId } = require('./snapshot');
+const { evaluateRisk } = require('./risk');
+
+function summarize(diff) {
+  const lines = [];
+  lines.push(`Changed: ${diff.changedCount}`);
+  if (diff.added.length) lines.push(`Added: ${diff.added.length}`);
+  if (diff.modified.length) lines.push(`Modified: ${diff.modified.length}`);
+  if (diff.deleted.length) lines.push(`Deleted: ${diff.deleted.length}`);
+  return lines.join(' | ');
+}
+
+function pctDrop(before, after) {
+  if (!before || before <= 0) return 0;
+  return ((before - after) / before) * 100;
+}
+
+function formatStats(diff) {
+  const stats = [];
+  if (diff.sizeBeforeChanged > 0) {
+    const shrink = pctDrop(diff.sizeBeforeChanged, diff.sizeAfterChanged);
+    stats.push(`Size shrink: ${shrink.toFixed(1)}%`);
+  }
+  if (diff.funcBeforeChanged > 0) {
+    const fdrop = pctDrop(diff.funcBeforeChanged, diff.funcAfterChanged);
+    stats.push(`Function drop: ${fdrop.toFixed(1)}%`);
+  }
+  return stats;
+}
+
+async function promptApproveOrRevert(reasons, diff) {
+  console.log('\n🚨 Risky change detected');
+  console.log(summarize(diff));
+  for (const s of formatStats(diff)) console.log(s);
+  for (const r of reasons) console.log(`- ${r}`);
+
+  const ans = await inquirer.prompt([
+    {
+      type: 'list',
+      name: 'action',
+      message: 'Choose an action:',
+      choices: [
+        { name: 'Approve', value: 'approve' },
+        { name: 'Rollback', value: 'revert' }
+      ]
+    }
+  ]);
+
+  return ans.action;
+}
+
+async function watchProject(projectRoot) {
+  const cfg = await loadConfig(projectRoot);
+
+  console.log(`Vorai Guard watching: ${projectRoot}`);
+  console.log('Creating initial snapshot (baseline)...');
+
+  // Baseline snapshot represents the last approved state.
+  await createSnapshot(projectRoot, { reason: 'baseline' });
+  let approvedState = await scanProjectState(projectRoot);
+
+  let timer = null;
+  let pending = false;
+  let burstEvents = [];
+  const burstFileCounts = new Map();
+
+  function pruneBurst(now) {
+    const windowMs = typeof cfg.burstWindowMs === 'number' ? cfg.burstWindowMs : 3000;
+    const cutoff = now - windowMs;
+    while (burstEvents.length && burstEvents[0].t < cutoff) {
+      const ev = burstEvents.shift();
+      const c = (burstFileCounts.get(ev.file) || 0) - 1;
+      if (c <= 0) burstFileCounts.delete(ev.file);
+      else burstFileCounts.set(ev.file, c);
+    }
+  }
+
+  function recordEvent(filePath) {
+    const now = Date.now();
+    burstEvents.push({ t: now, file: String(filePath || '') });
+    burstFileCounts.set(String(filePath || ''), (burstFileCounts.get(String(filePath || '')) || 0) + 1);
+    pruneBurst(now);
+  }
+
+  async function onBatch() {
+    if (pending) return;
+    pending = true;
+
+    try {
+      const current = await scanProjectState(projectRoot);
+      const diff = diffStates(approvedState, current);
+
+      // No actual content change (can happen with temp files/metadata).
+      if (diff.changedCount === 0) return;
+
+      pruneBurst(Date.now());
+      const burstEventCount = burstEvents.length;
+      const burstFileCount = burstFileCounts.size;
+
+      // reset burst buffers after batch evaluation
+      burstEvents = [];
+      burstFileCounts.clear();
+
+      const risk = evaluateRisk(diff, cfg, { burstEvents: burstEventCount, burstFiles: burstFileCount });
+      if (!risk.risky) {
+        // Auto-approve low-risk batches: update baseline snapshot/state.
+        await createSnapshot(projectRoot, { reason: 'auto-approve', summary: summarize(diff) });
+        approvedState = current;
+        console.log(`Auto-approved: ${summarize(diff)}`);
+        return;
+      }
+
+      // Risky: prompt user. Revert uses the latest snapshot (last approved).
+      const action = await promptApproveOrRevert(risk.reasons, diff);
+      if (action === 'revert') {
+        const latestId = await getLatestSnapshotId(projectRoot);
+        if (!latestId) throw new Error('No snapshot available to revert.');
+        console.log(`Reverting to snapshot: ${latestId}`);
+        await restoreSnapshot(projectRoot, latestId);
+        approvedState = await scanProjectState(projectRoot);
+        console.log('Reverted.');
+        return;
+      }
+
+      // Approved: take a new snapshot that becomes the new baseline.
+      await createSnapshot(projectRoot, { reason: 'approved', summary: summarize(diff), risk: risk.reasons });
+      approvedState = current;
+      console.log('Approved.');
+    } finally {
+      pending = false;
+    }
+  }
+
+  const watcher = chokidar.watch(projectRoot, {
+    persistent: true,
+    ignoreInitial: true,
+    awaitWriteFinish: {
+      stabilityThreshold: 500,
+      pollInterval: 100
+    },
+    ignored: (p) => {
+      // chokidar passes absolute paths
+      return p.includes('\\node_modules\\') || p.includes('/node_modules/') || p.includes('\\.git\\') || p.includes('/.git/') || p.includes('\\.voraiguard\\') || p.includes('/.voraiguard/');
+    }
+  });
+
+  const bump = (p) => {
+    recordEvent(p);
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(onBatch, cfg.debounceMs);
+  };
+
+  watcher
+    .on('add', (p) => bump(p))
+    .on('change', (p) => bump(p))
+    .on('unlink', (p) => bump(p))
+    .on('error', (err) => console.error('Watcher error:', err));
+
+  console.log('Watching. Press Ctrl+C to stop.');
+}
+
+module.exports = { watchProject };