version-history-widget 0.1.4 → 0.1.6

package/README.md

@@ -21,6 +21,27 @@ Or use without installing:
 npx version-history-widget init
 ```
 
+## Auto-recording (so nothing is ever missed)
+
+A version only exists if something records it. Rather than relying on you
+(or your AI assistant) to remember, let it record on its own:
+
+```bash
+npx vh watch     # auto-saves every change as a new version, debounced
+```
+
+Run that alongside whatever dev server you use — Vite, Next, Astro, plain
+HTML, anything. A burst of edits becomes one version, not twenty.
+
+You usually don't even need to run it: **`.versions/middleware.js` starts the
+same watcher automatically whenever it's mounted**, so `node .versions/serve.js`
+or a dev server with the middleware mounted records changes on its own. For
+Vite projects, `vh init` writes a `vite.config.js` that mounts it for you (an
+existing config is never modified — it just prints the snippet to add).
+
+Explicitly running `vh record "Some title"` is still worth it when you want a
+meaningful title instead of an auto-generated "Updated src/main.js".
+
 ## Project mode
 
 ```bash
@@ -28,6 +49,7 @@ npx vh init                 # sets up .versions/, injects the widget, saves vers
 npx vh record "Title" -d "what changed and why"
 npx vh restore 4            # safety-snapshots current state, then restores version 4
 npx vh list [query]         # list versions, optionally filtered
+npx vh watch                # auto-save every change as a new version
 npx vh update               # refresh .versions/*.js from the currently installed package
 ```
 

package/middleware.js

@@ -1,11 +1,18 @@
-/* Connect/Express/Vite-compatible middleware: serves /.versions/* and handles POST /__vh/restore/:id
+/* Connect/Express/Vite-compatible middleware: serves /.versions/*, handles POST /__vh/restore/:id,
+   and auto-records every change as a new version while the dev server is running.
    Express:  app.use(require('./.versions/middleware.js')())
    Vite:     plugins:[{ name:'vh', configureServer(s){ s.middlewares.use(require('./.versions/middleware.js')()) } }]
-   Next:     use serve.js alongside, or add a route handler that calls require('./.versions/vh.js').restore(id) */
+   Next:     use serve.js alongside, or add a route handler that calls require('./.versions/vh.js').restore(id)
+   Pass { watch: false } to opt out of auto-recording. */
 const fs = require('fs'), path = require('path');
 module.exports = function (opts = {}) {
   const root = path.resolve(opts.root || process.env.VH_ROOT || process.cwd()), vdir = path.join(root, '.versions');
   const types = { '.js': 'text/javascript', '.json': 'application/json', '.diff': 'text/plain' };
+  if (opts.watch !== false && fs.existsSync(vdir)) {
+    process.env.VH_ROOT = root;   // vh.js resolves its root from this at require time
+    try { require(path.join(vdir, 'vh.js')).watch({ keepAlive: false }); }
+    catch (e) { console.error('[vh] auto-record unavailable: ' + e.message); }
+  }
   return function (req, res, next) {
     const url = (req.url || '').split('?')[0];
     if (req.method === 'POST' && url.startsWith('/__vh/restore/')) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "version-history-widget",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Zero-dependency version history for web projects: snapshots every change and adds a floating widget to browse, search, and restore any version.",
   "keywords": ["version history", "undo", "snapshot", "restore", "dev-tool", "widget"],
   "license": "MIT",

package/skill/SKILL.md

@@ -14,6 +14,23 @@ Two modes — pick based on what the user is working on:
 - **Project mode**: a normal multi-file site/app. History lives in `.versions/`.
 - **Single-file mode**: one standalone `.html` file. History lives inside that file.
 
+## Record after you change things
+
+**If a project has a `.versions/` directory, it has version history enabled,
+and every meaningful change you make should end with a recorded version.**
+Don't leave the user's history stuck on an old snapshot — after editing
+files, run `record` with a short human title describing what you changed:
+
+`npx version-history-widget record "Tweak icon animation timing" -d "what changed and why"`
+
+If the project is set up for auto-recording (`vh watch`, or the middleware
+mounted in their dev server), versions are captured on their own and you
+don't need to record manually — but recording explicitly is still better,
+since it gives the version a meaningful title instead of "Updated src/main.js".
+
+To set a project up so changes are never missed again, see "Auto-recording"
+below.
+
 ## Project mode
 
 Run these with Bash from the project root (`npx` needs no local install):
@@ -35,6 +52,40 @@ Run these with Bash from the project root (`npx` needs no local install):
 
 If `.versions/` doesn't exist yet in the project, run `init` first.
 
+## Auto-recording
+
+So that changes are never silently lost, a project can record versions on
+its own. Two ways, both framework-agnostic:
+
+- Run a watcher alongside whatever dev server they use:
+  `npx version-history-widget watch`
+  It debounces, so a burst of edits becomes one version.
+- Or mount the middleware in their dev server, which starts the same
+  watcher automatically whenever the server runs. For Vite, a
+  `vite.config.js` containing:
+
+  ```js
+  import { createRequire } from 'module';
+  const require = createRequire(import.meta.url);
+
+  export default {
+    plugins: [{
+      name: 'version-history',
+      configureServer(server) {
+        server.middlewares.use(require('./.versions/middleware.js')());
+      },
+    }],
+  };
+  ```
+
+  (`createRequire` is needed because Vite configs are ES modules and the
+  vendored `.versions/` files are CommonJS.)
+
+If the user reports that a change they made isn't showing up in the widget,
+it is almost always because nothing recorded it — check
+`.versions/manifest.json` against the current files, record the missing
+version, then set up one of the two options above.
+
 ## Single-file mode
 
 Use when the user names one `.html` file rather than a project:

package/vh.js

@@ -4,6 +4,8 @@
    node vh.js record "Title" [-d "details" | -f details.txt]   — snapshot changed files as a new version
    node vh.js restore <id>               — snapshot current state, then restore version <id>
    node vh.js list [query]               — list versions (optionally filtered by title/details)
+   node vh.js watch                      — auto-record every change as a new version (run alongside
+                                            your dev server; also runs inside serve.js/middleware.js)
    node vh.js update                     — refresh the vendored widget.js/vh.js/serve.js/middleware.js
                                             in .versions/ from the installed package (run after upgrading)
    node vh.js skill                      — install the Claude Code skill (~/.claude/skills) so
@@ -12,7 +14,8 @@
 const fs = require('fs'), path = require('path'), os = require('os');
 const ROOT = path.resolve(process.env.VH_ROOT || process.cwd());
 const VDIR = path.join(ROOT, '.versions'), SNAP = path.join(VDIR, 'snapshots'), MAN = path.join(VDIR, 'manifest.json');
-const IGNORE = new Set(['node_modules', '.git', '.versions', 'dist', 'build', '.next', '.nuxt', 'coverage', '.cache']);
+const LOCK = path.join(VDIR, '.restoring');
+const IGNORE = new Set(['node_modules', '.git', '.versions', 'dist', 'build', '.next', '.nuxt', 'coverage', '.cache', '.DS_Store', '.claude']);
 const MAX = 2 * 1024 * 1024;
 
 const readMan = () => fs.existsSync(MAN) ? JSON.parse(fs.readFileSync(MAN, 'utf8')) : [];
@@ -86,19 +89,146 @@ function injectWidget() {
   return null;
 }
 
+const VITE_CONFIG = `import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+export default {
+  plugins: [{
+    name: 'version-history',
+    configureServer(server) {
+      server.middlewares.use(require('./.versions/middleware.js')());
+    },
+  }],
+};
+`;
+
+function usesVite() {
+  const pj = path.join(ROOT, 'package.json');
+  if (!fs.existsSync(pj)) return false;
+  try {
+    const p = JSON.parse(fs.readFileSync(pj, 'utf8'));
+    if ((p.devDependencies && p.devDependencies.vite) || (p.dependencies && p.dependencies.vite)) return true;
+    return /\bvite\b/.test(Object.values(p.scripts || {}).join(' '));
+  } catch (e) { return false; }
+}
+
+function viteConfigPath() {
+  for (const f of ['vite.config.js', 'vite.config.mjs', 'vite.config.ts', 'vite.config.mts', 'vite.config.cjs'])
+    if (fs.existsSync(path.join(ROOT, f))) return path.join(ROOT, f);
+  return null;
+}
+
+/* Wire the dev server up so changes keep getting auto-recorded. Only ever
+   creates a config when there isn't one — an existing config is never edited,
+   since that's the user's file. Re-run after a restore so restoring to a
+   version that predates the setup doesn't silently switch auto-saving off. */
+function ensureDevIntegration(quiet) {
+  if (!usesVite()) return null;
+  const existing = viteConfigPath();
+  if (existing) {
+    if (!quiet && !fs.readFileSync(existing, 'utf8').includes('.versions/middleware.js'))
+      console.log('Note: ' + path.basename(existing) + ' does not mount .versions/middleware.js, so changes are only auto-recorded while `vh watch` is running. See the README for the snippet to add.');
+    return null;
+  }
+  const p = path.join(ROOT, 'vite.config.js');
+  fs.writeFileSync(p, VITE_CONFIG);
+  if (!quiet) console.log('Created vite.config.js mounting .versions/middleware.js — restart your dev server and every change is auto-recorded.');
+  return p;
+}
+
+/* Files that differ from the newest recorded version. */
+function pendingChanges() {
+  const man = readMan(), prev = man.length ? stateAt(man[man.length - 1].id, man) : {};
+  const cur = walk(ROOT), out = [];
+  for (const f of Object.keys(cur)) { const old = prev[f]; if (!old || !old.equals(cur[f])) out.push(f); }
+  for (const f of Object.keys(prev)) if (!cur[f]) out.push(f);
+  return out;
+}
+
+/* Record a version in-process. Returns null when nothing changed. */
+function recordNow(title, details) {
+  const man = readMan(), prev = man.length ? stateAt(man[man.length - 1].id, man) : {};
+  const r = snapshot(title, details, prev);
+  if (!r.changed) { const m = readMan(); m.pop(); writeMan(m); fs.rmSync(path.join(SNAP, String(r.id)), { recursive: true, force: true }); return null; }
+  return r;
+}
+
+function autoTitle(files) {
+  if (files.length === 1) return 'Updated ' + files[0];
+  return 'Updated ' + files[0] + ' and ' + (files.length - 1) + ' more file' + (files.length > 2 ? 's' : '');
+}
+
+function ignoredPath(rel) {
+  if (!rel) return false;
+  for (const seg of String(rel).split(/[\\/]/)) if (IGNORE.has(seg) || seg.startsWith('.env')) return true;
+  return false;
+}
+
+/* Auto-record changes as they happen. Debounced so a burst of edits (an editor
+   or an agent writing several files) becomes one version, not twenty. */
+function startWatch(opts = {}) {
+  const wait = opts.debounce || 1500, log = opts.log !== false;
+  let timer = null, busy = false;
+  function fire() {
+    timer = null;
+    if (busy || fs.existsSync(LOCK)) return schedule();   // mid-restore: check again later
+    busy = true;
+    try {
+      const files = pendingChanges();
+      if (files.length) {
+        const title = autoTitle(files);
+        const r = recordNow(title, 'Auto-saved.\n\nChanged files:\n' + files.map(f => '  ' + f).join('\n'));
+        if (r && log) console.log('[vh] saved version ' + r.id + ': ' + title);
+      }
+    } catch (e) { if (log) console.error('[vh] auto-save failed: ' + e.message); }
+    finally { busy = false; }
+  }
+  function schedule() { clearTimeout(timer); timer = setTimeout(fire, wait); }
+
+  let watcher = null;
+  try { watcher = fs.watch(ROOT, { recursive: true }, (evt, name) => { if (!ignoredPath(name)) schedule(); }); }
+  catch (e) { watcher = null; }   // recursive watch unsupported (older Linux)
+  let poller = null;
+  if (!watcher) {
+    let seen = 0;
+    poller = setInterval(() => {
+      let newest = 0;
+      (function scan(dir) {
+        let entries; try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch (e) { return; }
+        for (const e of entries) {
+          if (IGNORE.has(e.name) || e.name.startsWith('.env')) continue;
+          const p = path.join(dir, e.name);
+          if (e.isDirectory()) scan(p);
+          else { try { const m = fs.statSync(p).mtimeMs; if (m > newest) newest = m; } catch (e2) { } }
+        }
+      })(ROOT);
+      if (newest > seen) { seen = newest; schedule(); }
+    }, opts.poll || 2000);
+  }
+  if (opts.keepAlive === false) { if (watcher && watcher.unref) watcher.unref(); if (poller && poller.unref) poller.unref(); }
+  schedule();   // catch up on anything changed while nothing was watching
+  return { stop() { clearTimeout(timer); if (watcher) watcher.close(); if (poller) clearInterval(poller); } };
+}
+
 function vendorFiles() {
   fs.mkdirSync(VDIR, { recursive: true });
   for (const f of ['widget.js', 'vh.js', 'serve.js', 'middleware.js']) { const src = path.join(__dirname, f); if (fs.existsSync(src) && src !== path.join(VDIR, f)) fs.copyFileSync(src, path.join(VDIR, f)); }
+  // Force CommonJS for everything under .versions/, regardless of the host
+  // project's own package.json — otherwise a host with "type":"module" makes
+  // Node treat these vendored .js files as ESM and `require` disappears.
+  fs.writeFileSync(path.join(VDIR, 'package.json'), JSON.stringify({ type: 'commonjs' }, null, 2) + '\n');
 }
 
-const cmd = process.argv[2], args = process.argv.slice(3);
-if (cmd === 'init') {
+const cmd = require.main === module ? process.argv[2] : null, args = process.argv.slice(3);
+if (cmd === null) {                        // required as a library (serve.js / middleware.js)
+} else if (cmd === 'init') {
   fs.mkdirSync(SNAP, { recursive: true });
   vendorFiles();
   if (!fs.existsSync(MAN)) writeMan([]);
   const gi = path.join(ROOT, '.gitignore'); const line = '.versions/snapshots/';
   if (!fs.existsSync(gi) || !fs.readFileSync(gi, 'utf8').includes(line)) fs.appendFileSync(gi, '\n' + line + '\n');
   const where = injectWidget();
+  ensureDevIntegration(false);
   const r = readMan().length ? null : snapshot('Initial version', 'State of the project when version history was enabled.', {});
   console.log('version-history ready.' + (where ? ' Widget injected into ' + path.relative(ROOT, where) + '.' : ' Could not find an entry HTML — add <script src="/.versions/widget.js"></script> manually.') + (r ? ' Saved version 1.' : ''));
   console.log('Serve with restore endpoint: node .versions/serve.js   (or mount .versions/middleware.js in your dev server)');
@@ -106,21 +236,27 @@ if (cmd === 'init') {
   const title = args[0]; if (!title) { console.error('usage: vh record "Title" [-d "details" | -f file]'); process.exit(1); }
   const di = args.indexOf('-d'), fi = args.indexOf('-f');
   const details = di >= 0 ? args[di + 1] : fi >= 0 ? fs.readFileSync(args[fi + 1], 'utf8') : '';
-  const man = readMan(), prev = man.length ? stateAt(man[man.length - 1].id, man) : {};
-  const r = snapshot(title, details, prev);
-  console.log(r.changed ? 'Saved as version ' + r.id + ': ' + title : 'No changes since last version — nothing saved.');
-  if (!r.changed) { const m = readMan(); m.pop(); writeMan(m); fs.rmSync(path.join(SNAP, String(r.id)), { recursive: true, force: true }); }
+  const r = recordNow(title, details);
+  console.log(r ? 'Saved as version ' + r.id + ': ' + title : 'No changes since last version — nothing saved.');
 } else if (cmd === 'restore') {
   const id = Number(args[0]), man = readMan(), target = man.find(v => v.id === id);
   if (!target) { console.error('No version ' + args[0]); process.exit(1); }
-  const cur = man[man.length - 1], prev = stateAt(cur.id, man);
-  snapshot('Snapshot before restoring "' + target.title + '"', 'Automatic safety snapshot taken before restore.', prev);
-  const want = stateAt(id, readMan()), have = walk(ROOT);
-  for (const f of Object.keys(have)) if (!want[f]) fs.rmSync(path.join(ROOT, f));
-  for (const f of Object.keys(want)) { const p = path.join(ROOT, f); fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, want[f]); }
-  injectWidget();
-  const r = snapshot('Restored "' + target.title + '"', 'Restored the state saved as version ' + id + '.', stateAt(readMan().slice(-1)[0].id, readMan()));
-  console.log('Restored version ' + id + ' (recorded as version ' + r.id + ').');
+  fs.mkdirSync(VDIR, { recursive: true }); fs.writeFileSync(LOCK, String(process.pid));   // pause any watcher
+  try {
+    const cur = man[man.length - 1], prev = stateAt(cur.id, man);
+    snapshot('Snapshot before restoring "' + target.title + '"', 'Automatic safety snapshot taken before restore.', prev);
+    const want = stateAt(id, readMan()), have = walk(ROOT);
+    for (const f of Object.keys(have)) if (!want[f]) fs.rmSync(path.join(ROOT, f));
+    for (const f of Object.keys(want)) { const p = path.join(ROOT, f); fs.mkdirSync(path.dirname(p), { recursive: true }); fs.writeFileSync(p, want[f]); }
+    injectWidget();
+    ensureDevIntegration(true);
+    const r = snapshot('Restored "' + target.title + '"', 'Restored the state saved as version ' + id + '.', stateAt(readMan().slice(-1)[0].id, readMan()));
+    console.log('Restored version ' + id + ' (recorded as version ' + r.id + ').');
+  } finally { fs.rmSync(LOCK, { force: true }); }
+} else if (cmd === 'watch') {
+  if (!fs.existsSync(VDIR)) { console.error('No .versions/ here — run `vh init` first.'); process.exit(1); }
+  startWatch({});
+  console.log('Watching ' + ROOT + ' — every change is auto-saved as a new version. Ctrl-C to stop.');
 } else if (cmd === 'list') {
   const q = (args[0] || '').toLowerCase();
   for (const v of readMan()) if (!q || v.title.toLowerCase().includes(q) || (v.details || '').toLowerCase().includes(q)) console.log(String(v.id).padStart(3) + '  ' + v.time.slice(0, 16).replace('T', ' ') + '  ' + v.title);
@@ -134,4 +270,7 @@ if (cmd === 'init') {
   fs.copyFileSync(path.join(__dirname, 'skill', 'SKILL.md'), path.join(dest, 'SKILL.md'));
   console.log('Installed Claude Code skill to ' + dest + '. Restart Claude Code (or start a new session) and try /version-history-widget.');
 } else { console.log(fs.readFileSync(__filename, 'utf8').split('*/')[0].split('\n').slice(1).join('\n')); }
-module.exports = { restore: id => { const { execFileSync } = require('child_process'); return execFileSync(process.execPath, [__filename, 'restore', String(id)], { cwd: ROOT, env: process.env }).toString(); } };
+module.exports = {
+  restore: id => { const { execFileSync } = require('child_process'); return execFileSync(process.execPath, [__filename, 'restore', String(id)], { cwd: ROOT, env: process.env }).toString(); },
+  watch: startWatch, record: recordNow, pending: pendingChanges, root: ROOT,
+};