version-history-widget 0.1.1 → 0.1.3

package/README.md

@@ -64,6 +64,20 @@ npx vh-singlefile list page.html [query]
 Restoring is handled entirely in the browser by the injected widget — no
 server needed.
 
+## Claude Code skill
+
+If you use Claude Code, this installs a skill so you can drive it with
+`/version-history-widget` (or by just describing what you want) instead
+of typing the CLI commands yourself:
+
+```bash
+npx version-history-widget skill
+```
+
+This copies a `SKILL.md` into `~/.claude/skills/version-history-widget/`
+on your machine. It's per-machine — anyone else who wants the slash
+command needs to run this once on their own machine too.
+
 ## How it works
 
 - No runtime dependencies — only Node's built-in `fs`, `path`, `http`, and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "version-history-widget",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "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",
@@ -17,7 +17,8 @@
     "widget.js",
     "middleware.js",
     "serve.js",
-    "singlefile.js"
+    "singlefile.js",
+    "skill/SKILL.md"
   ],
   "repository": {
     "type": "git",

package/skill/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: version-history-widget
+description: Zero-dependency version history for web projects (the `vh` / version-history-widget CLI). Use when the user wants to save a checkpoint or snapshot of their site, record a titled version of recent changes, list past versions, or restore/roll back to an earlier version. Covers both project mode (multi-file sites, snapshots in .versions/) and single-file mode (one HTML file, snapshots embedded in the file).
+---
+
+# Version History Widget
+
+CLI for saving titled, restorable snapshots of a web project, plus a
+floating "Versions" widget injected into the live site so anyone can
+browse, search, and restore with one click. No runtime dependencies.
+
+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.
+
+## Project mode
+
+Run these with Bash from the project root (`npx` needs no local install):
+
+- First time only — sets up `.versions/`, injects the widget into the
+  site's entry HTML, saves version 1:
+  `npx version-history-widget init`
+- After the user has made changes and wants a checkpoint:
+  `npx version-history-widget record "Title" -d "what changed and why"`
+- List versions, optionally filtered by title/details text:
+  `npx version-history-widget list [query]`
+- Restore an earlier version (this automatically snapshots the
+  current state first, so it's safe):
+  `npx version-history-widget restore <id>`
+- To serve the site so the widget's in-browser restore button works:
+  `node .versions/serve.js` (or mount `.versions/middleware.js` in
+  their existing dev server — see `.versions/middleware.js`'s header
+  comment for Express/Vite examples).
+
+If `.versions/` doesn't exist yet in the project, run `init` first.
+
+## Single-file mode
+
+Use when the user names one `.html` file rather than a project:
+
+- Init: `npx -p version-history-widget vh-singlefile init page.html`
+- Record: `npx -p version-history-widget vh-singlefile record page.html "Title" -d "details"`
+- List: `npx -p version-history-widget vh-singlefile list page.html [query]`
+
+Restoring in single-file mode happens entirely in the browser via the
+widget embedded in the file — no server or CLI restore command needed.
+
+## Notes
+
+- If the user has it installed as a devDependency already
+  (`npm install --save-dev version-history-widget`), use `npx vh ...`
+  and `npx vh-singlefile ...` directly instead of the longer `-p` form.
+- Always ask for or infer a short, human title when recording — it's
+  what shows up in the widget's list and search.
+- Don't run `restore` without the user confirming which version id
+  they want — list versions first if it's ambiguous.

package/vh.js

@@ -4,8 +4,10 @@
    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 skill                      — install the Claude Code skill (~/.claude/skills) so
+                                            /version-history-widget works in Claude Code sessions
    Env: VH_ROOT (project root, default cwd) */
-const fs = require('fs'), path = require('path');
+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']);
@@ -115,5 +117,10 @@ if (cmd === 'init') {
 } 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);
+} else if (cmd === 'skill') {
+  const dest = path.join(os.homedir(), '.claude', 'skills', 'version-history-widget');
+  fs.mkdirSync(dest, { recursive: true });
+  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(); } };

package/widget.js

@@ -3,8 +3,8 @@
   if (window.__vhLoaded) return; window.__vhLoaded = true;
   var Z = 2147483647, MODE = document.getElementById('vh-store') ? 'single' : 'project';
   var css = '\
-.vh-pill{position:fixed;right:16px;bottom:16px;z-index:' + Z + ';font:13px/1 system-ui,sans-serif;background:#111;color:#fff;border:0;border-radius:999px;padding:10px 14px;cursor:pointer;box-shadow:0 4px 14px rgba(0,0,0,.25)}\
-.vh-panel{position:fixed;right:16px;bottom:56px;width:440px;max-width:calc(100vw - 32px);max-height:70vh;z-index:' + Z + ';background:#fff;color:#111;border:1px solid #ddd;border-radius:12px;box-shadow:0 12px 40px rgba(0,0,0,.25);font:13px/1.4 system-ui,sans-serif;display:flex;flex-direction:column;overflow:hidden}\
+.vh-pill{position:fixed;right:16px;top:16px;z-index:' + Z + ';font:13px/1 system-ui,sans-serif;background:#111;color:#fff;border:0;border-radius:999px;padding:10px 14px;cursor:pointer;box-shadow:0 6px 20px rgba(0,0,0,.35)}\
+.vh-panel{position:fixed;right:16px;top:56px;width:440px;max-width:calc(100vw - 32px);max-height:70vh;z-index:' + Z + ';background:#fff;color:#111;border:1px solid #ddd;border-radius:12px;box-shadow:0 12px 40px rgba(0,0,0,.35);font:13px/1.4 system-ui,sans-serif;display:flex;flex-direction:column;overflow:hidden}\
 .vh-head{display:flex;gap:8px;padding:10px;border-bottom:1px solid #eee;align-items:center}\
 .vh-search{flex:1;padding:8px 10px;border:1px solid #ccc;border-radius:8px;font:inherit;outline:none}.vh-search:focus{border-color:#111}\
 .vh-clear{border:0;background:#eee;border-radius:6px;padding:6px 8px;cursor:pointer}\