codewhale.history 2.1.0 → 2.3.0

package/README.md

@@ -1,6 +1,6 @@
 # CodeWhale Tools Pack
 
-A portable pack of global CodeWhale commands: `//tools` and `//history`.
+A portable pack of global CodeWhale commands: `//tools`, `//history`, and `//snapshot`.
 
 Cross-platform — works on Windows, Mac, Linux.
 
@@ -12,7 +12,8 @@ tools_for_codewhale/
 ├── package.json            # npm package config
 ├── tools-install.js        # Cross-platform installer (skills + instructions)
 ├── skills/
-│   ├── history/SKILL.md    # //history — calls codewhale-history
+│   ├── history/SKILL.md      # //history — calls codewhale-history
+│   ├── snapshot/SKILL.md     # //snapshot — pre-edit file backups
 │   └── tools/tools-skill/SKILL.md  # //tools — lists all available tools
 ├── instructions.md         # Trigger config (drop into any .codewhale/)
 └── README.md               # This file
@@ -26,7 +27,7 @@ One command:
 npm install -g codewhale.history && codewhale-tools-install
 ```
 
-Then in any CodeWhale workspace, `//tools` and `//history` work immediately.
+Then in any CodeWhale workspace, `//tools`, `//history`, and `//snapshot` work immediately.
 
 ### Manual per-workspace install (if already globally installed)
 
@@ -38,6 +39,7 @@ codewhale-tools-install -p <target-path>        # specific workspace
 ## After install
 - **`//tools`** — lists every tool available in the current session
 - **`//history`** — lists all chat sessions for the current workspace with cost totals
+- **`//snapshot`** — toggle pre-edit file backups (`on`, `off`, `status`)
 
 ## Requirements
 - Node.js (for the `codewhale-history` command)

package/instructions.md

@@ -5,3 +5,6 @@ When the user types `//tools`, immediately load the `tools` skill (from `tools-s
 
 ## //history Command
 When the user types `//history`, immediately load the `history` skill (from `history/SKILL.md`) and list all CodeWhale chat sessions for the current workspace with message count, tokens, cost, and totals. This works in all sessions once the skill is installed globally.
+
+## //snapshot Command
+When the user types `//snapshot`, immediately load the `snapshot` skill (from `snapshot/SKILL.md`) and follow its instructions. `//snapshot on` enables automatic pre-edit file backups to `_snapshots/` when no Git repo is present. `//snapshot off` disables it. `//snapshot status` reports the current state. This works in all sessions once the skill is installed globally.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "codewhale.history",
-  "version": "2.1.0",
-  "description": "CodeWhale utility commands: session history, tool listing — global install",
+  "version": "2.3.0",
+  "description": "CodeWhale utility commands: session history, tool listing, file snapshot — global install",
   "bin": {
     "codewhale-history": "./_list_sessions.js",
     "codewhale-tools-install": "./tools-install.js"

package/skills/snapshot/SKILL.md

@@ -0,0 +1,40 @@
+---
+name: snapshot
+description: Toggle automatic pre-edit file snapshotting on or off. Triggered by //snapshot on and //snapshot off.
+---
+
+# `//snapshot` Command
+
+When the user types `//snapshot on`, `//snapshot off`, or `//snapshot status`, manage automatic file backup before edits.
+
+## Behavior
+
+### `//snapshot on`
+1. Check if `.git` exists in the workspace root via `Test-Path .git`.
+2. **If Git repo exists**: reply "This workspace has a Git repo — snapshotting is not needed. Use `git restore <file>` to undo changes."
+3. **If no Git repo**: create `_snapshots/` directory, write a note to persist `snapshot_enabled=true`, then confirm to the user.
+4. From this point forward, before editing any **existing** file:
+   - Run the following PowerShell command to snapshot with a timestamp:
+     ```
+     $ts = Get-Date -Format 'yyyy-MM-dd_HH-mm-ss'
+     $base = [System.IO.Path]::GetFileNameWithoutExtension('<file>')
+     $ext  = [System.IO.Path]::GetExtension('<file>')
+     Copy-Item '<file>' "_snapshots/$base.$ts$ext"
+     ```
+   - Result example: `foo.py` → `_snapshots/foo.2026-06-20_11-30-00.py`
+   - Do NOT snapshot brand-new files being created for the first time
+
+### `//snapshot off`
+1. Write a note to persist `snapshot_enabled=false`.
+2. Reply "Snapshotting is now off. Existing snapshots in `_snapshots/` have been preserved."
+3. Stop snapshotting before future edits.
+
+### `//snapshot status`
+1. Read the snapshot-enabled note.
+2. Count files in `_snapshots/` (if directory exists).
+3. Report: whether snapshotting is on/off, the snapshot directory exists, and file count.
+
+## Notes
+- The skill is installed globally — works in any workspace
+- Snapshot state is session-scoped — does not persist across different CodeWhale sessions
+- Use `//snapshot off` before switching to a Git-tracked project to avoid redundant copies

package/tools-install.js

@@ -2,7 +2,7 @@
 /**
  * CodeWhale Tools Installer
  *
- * Installs global skills and workspace triggers for //tools and //history.
+ * Installs global skills and workspace triggers for //tools, //history, and //snapshot.
  *
  * Usage:
  *   node tools-install.js                          # current directory
@@ -55,12 +55,12 @@ if (fs.existsSync(instructionsSource)) {
   if (fs.existsSync(instructionsDest)) {
     const existingContent = fs.readFileSync(instructionsDest, 'utf-8');
     // Only append if it's not already there (idempotent)
-    if (!existingContent.includes('## //tools Command') && !existingContent.includes('## //history Command')) {
+    if (!existingContent.includes('## //tools Command') && !existingContent.includes('## //history Command') && !existingContent.includes('## //snapshot Command')) {
       const separator = `\n\n---\n\n`;
       fs.writeFileSync(instructionsDest, existingContent + separator + newContent, 'utf-8');
-      console.log('  Appended //tools and //history instructions to existing instructions.md');
+      console.log('  Appended //tools, //history, and //snapshot instructions to existing instructions.md');
     } else {
-      console.log('  //tools and //history already present in instructions.md — skipped.');
+      console.log('  //tools, //history, and //snapshot already present in instructions.md — skipped.');
     }
   } else {
     fs.writeFileSync(instructionsDest, newContent, 'utf-8');
@@ -77,6 +77,7 @@ let errors = 0;
 const checklist = {
   'history skill': path.join(skillsDest, 'history', 'SKILL.md'),
   'tools skill': path.join(skillsDest, 'tools', 'tools-skill', 'SKILL.md'),
+  'snapshot skill': path.join(skillsDest, 'snapshot', 'SKILL.md'),
   'workspace instructions': instructionsDest
 };
 
@@ -93,7 +94,7 @@ console.log('');
 if (errors === 0) {
   console.log('=== Installation complete! ===');
   console.log('Make sure codewhale-history is installed globally: npm install -g <path-to-tools_for_codewhale>');
-  console.log('Then type //tools or //history in any CodeWhale session.');
+  console.log('Then type //tools, //history, or //snapshot in any CodeWhale session.');
 } else {
   console.log(`=== Installation finished with ${errors} error(s). ===`);
 }