@dambrogia/openclaw-agents-backup 0.1.0

package/.eslintrc.json

@@ -0,0 +1,24 @@
+{
+  "parser": "@typescript-eslint/parser",
+  "extends": ["plugin:@typescript-eslint/recommended"],
+  "plugins": ["@typescript-eslint"],
+  "parserOptions": {
+    "ecmaVersion": 2020,
+    "sourceType": "module"
+  },
+  "rules": {
+    "@typescript-eslint/explicit-function-return-types": "off",
+    "@typescript-eslint/no-explicit-any": "error",
+    "@typescript-eslint/no-unused-vars": [
+      "error",
+      {
+        "argsIgnorePattern": "^_",
+        "varsIgnorePattern": "^_"
+      }
+    ],
+    "@typescript-eslint/no-var-requires": "off",
+    "semi": ["error", "always"],
+    "quotes": ["error", "single", { "avoidEscape": true }],
+    "no-console": ["warn", { "allow": ["log", "warn", "error"] }]
+  }
+}

package/.github/workflows/test.yml

@@ -0,0 +1,40 @@
+name: Tests and Linting
+
+on:
+  push:
+    branches: [master, develop]
+  pull_request:
+    branches: [master, develop]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Use Node.js 24.x
+        uses: actions/setup-node@v4
+        with:
+          node-version: '24.x'
+          cache: 'npm'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run linting
+        run: npm run lint
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Upload coverage reports
+        uses: codecov/codecov-action@v3
+        with:
+          files: ./coverage/coverage-final.json
+          flags: unittests
+          name: codecov-umbrella
+          fail_ci_if_error: false

package/BACKUP_GITIGNORE_TEMPLATE

@@ -0,0 +1,51 @@
+# This file should be copied to your backup repository as .gitignore
+# It ensures that secrets and temporary files are never committed
+
+# Environment and secrets
+.env
+.env.local
+.env.*.local
+.env.production.local
+
+# Authentication profiles (sensitive)
+auth-profiles.json
+auth-profiles.*
+
+# Dependencies and build artifacts
+node_modules/
+package-lock.json
+yarn.lock
+dist/
+build/
+*.js
+*.js.map
+*.d.ts
+.next/
+.nuxt/
+
+# IDE and editor files
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+.DS_Store
+.sublime-project
+.sublime-workspace
+
+# Logs and temporary files
+*.log
+logs/
+*.tmp
+.cache/
+.parcel-cache/
+
+# OS files
+Thumbs.db
+.AppleDouble
+.LSOverride
+
+# Local development
+.local/
+tmp/
+temp/

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dambrogia-ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,342 @@
+# @dambrogia/openclaw-agents-backup
+
+Backup and restore OpenClaw multi-agent workspaces. Automated hourly snapshots with full disaster recovery capabilities.
+
+[![npm version](https://img.shields.io/npm/v/@dambrogia/openclaw-agents-backup)](https://www.npmjs.com/package/@dambrogia/openclaw-agents-backup)
+[![Tests](https://github.com/dambrogia-ai/openclaw-agents-backup/actions/workflows/test.yml/badge.svg)](https://github.com/dambrogia-ai/openclaw-agents-backup/actions)
+[![Coverage](https://img.shields.io/badge/coverage->80%25-green)](./README.md)
+
+## Why This Exists
+
+OpenClaw enables multiple agents to run in a single instance. Each agent has its own workspace with configuration, memory, identity files, and session history. If something goes wrong—disk corruption, accidental deletion, security incident—you lose everything.
+
+This skill automates hourly backups of all agent workspaces and agent directories to a central Git repository. When disaster strikes, you can restore any agent to any point in history by pulling from your backup repo.
+
+## Agent Integration
+
+The easiest way to use this skill is to install it and let your agent call the CLI commands.
+
+### Setup (One-time)
+
+1. **Install the skill in your agent's project:**
+```bash
+npm install @dambrogia/openclaw-agents-backup
+```
+
+That's it. You're done.
+
+### Usage
+
+Your agent can now run:
+
+```bash
+backup-agents backup              # Back up all agents now
+backup-agents restore             # Restore to latest backup
+backup-agents restore --sha abc123 # Restore to specific point in time
+backup-agents history             # Show recent backups
+```
+
+Just tell your agent what you need:
+
+- **"Back up my agents"** → Agent runs `backup-agents backup`
+- **"Restore my agents"** → Agent runs `backup-agents restore`
+- **"Restore agents to yesterday"** → Agent runs `backup-agents restore --sha <commit>`
+- **"Show me backup history"** → Agent runs `backup-agents history`
+
+### Scheduled Backups
+
+For automated hourly backups, set up a cron job in your OpenClaw instance:
+
+```javascript
+// Runs every hour at :00
+cron.add({
+  name: 'agents-backup-hourly',
+  schedule: { kind: 'cron', expr: '0 * * * *' },
+  payload: {
+    kind: 'agentTurn',
+    message: 'Back up all agents: backup-agents backup',
+    timeoutSeconds: 300
+  },
+  sessionTarget: 'isolated',
+  notify: false
+});
+```
+
+Or just tell your agent: **"Schedule hourly backups of my agents"**
+
+---
+
+## Quick Start
+
+### 1. Initialize Backup Repository
+
+```bash
+mkdir my-agents-backup
+cd my-agents-backup
+git init
+git config user.email "backup@example.com"
+git config user.name "Backup Bot"
+git commit --allow-empty -m "Initial commit"
+```
+
+### 2. Create Backup Config
+
+In your OpenClaw workspace (`~/.openclaw/workspace`), create `.backupconfig.json`:
+
+```json
+{
+  "backupRepoPath": "/path/to/my-agents-backup"
+}
+```
+
+### 3. Install the Library
+
+```bash
+npm install @dambrogia/openclaw-agents-backup
+```
+
+### 4. Schedule Hourly Backups
+
+Use OpenClaw's cron system or call the backup function hourly.
+
+```javascript
+const { performBackup } = require('@dambrogia/openclaw-agents-backup');
+
+// Run every hour
+await performBackup('/root/.openclaw/workspace');
+```
+
+### 5. Disaster Recovery
+
+When you need to restore:
+
+```bash
+# Wipe the VPS, reinstall OpenClaw
+openclaw init
+
+# Clone your backup
+git clone <backup-repo-url> /path/to/my-agents-backup
+
+# Create config pointing to backup repo
+echo '{"backupRepoPath": "/path/to/my-agents-backup"}' > ~/.openclaw/workspace/.backupconfig.json
+
+# Restore all agents to current state
+node -e "require('@dambrogia/openclaw-agents-backup').performRestore(...)"
+```
+
+## Features
+
+✅ **Multi-agent support** — Back up all agents in one command  
+✅ **Hourly snapshots** — Automated backup schedule  
+✅ **Git history** — Full point-in-time recovery via Git commits  
+✅ **Selective ignore** — `.env`, secrets, and temporary files never committed  
+✅ **Minimal disk usage** — Only changed files are stored in Git  
+✅ **Simple restore** — One command to restore any agent to any point  
+✅ **Test coverage** — >80% covered, production-ready
+
+## What Gets Backed Up
+
+For each agent, the skill backs up:
+
+- **Workspace** — Identity files (SOUL.md, USER.md, IDENTITY.md), memory (MEMORY.md, memory/), configuration, tools
+- **Agent directory** — Session files, auth profiles, history (when available)
+
+What's **not** backed up (by design):
+
+- `.env*` files (use these for secrets)
+- `auth-profiles.json` (sensitive auth data)
+- `node_modules/`, build artifacts, logs
+
+## API Reference
+
+Agents call these functions directly. Most users don't need to interact with the API — just tell your agent what you need.
+
+### Backup
+
+```typescript
+import { performBackup } from '@dambrogia/openclaw-agents-backup';
+
+const result = await performBackup('/root/.openclaw/workspace');
+
+/*
+{
+  success: true,
+  message: "Backed up 3 agents. Changes: 2",
+  agentsProcessed: 3,
+  changes: [
+    { agentId: 'main', workspaceChanged: true, agentDirChanged: false },
+    { agentId: 'worker-1', workspaceChanged: false, agentDirChanged: true },
+    { agentId: 'worker-2', workspaceChanged: false, agentDirChanged: false }
+  ]
+}
+*/
+```
+
+### Restore
+
+```typescript
+import { performRestore } from '@dambrogia/openclaw-agents-backup';
+
+// Restore latest backup
+const result = await performRestore(
+  '/path/to/backup-repo',
+  null,
+  '/root/.openclaw/workspace'
+);
+
+// Or restore to specific point in time (git SHA)
+const result = await performRestore(
+  '/path/to/backup-repo',
+  'abc123def456',
+  '/root/.openclaw/workspace'
+);
+
+/*
+{
+  success: true,
+  message: "Successfully restored 3 agents",
+  agentsRestored: 3
+}
+*/
+```
+
+## Backup Structure
+
+```
+my-agents-backup/
+├── .git/                 # Full Git history
+├── archives/
+│   ├── main/
+│   │   ├── agent.json    # Metadata: paths, timestamp, identity
+│   │   ├── workspace/    # Synced workspace directory
+│   │   └── agentDir/     # Synced agent directory
+│   ├── worker-1/
+│   │   ├── agent.json
+│   │   ├── workspace/
+│   │   └── agentDir/
+│   └── ...
+└── .gitignore
+```
+
+Each backup run creates one Git commit. You can browse history:
+
+```bash
+cd my-agents-backup
+git log --oneline
+# Restore to a specific commit
+git checkout abc123def456
+```
+
+## Testing
+
+```bash
+npm test              # Run tests
+npm run test:coverage # Check coverage (>80% required)
+npm run lint          # ESLint check
+npm run build         # TypeScript compilation
+```
+
+## Common Scenarios
+
+### Restore an Agent After Accidental Changes
+
+```bash
+# Find the commit before the change
+cd my-agents-backup
+git log --oneline | head -10
+
+# Restore that state
+git checkout <commit-hash>
+node -e "require('@dambrogia/openclaw-agents-backup').performRestore(...)"
+```
+
+### Back Up Before Major Changes
+
+Run backup manually before modifying agent code or identity:
+
+```javascript
+const { performBackup } = require('@dambrogia/openclaw-agents-backup');
+await performBackup('/root/.openclaw/workspace');
+```
+
+Check that files were committed in Git.
+
+### Migrate Agents to New VPS
+
+1. Set up new VPS with OpenClaw
+2. Clone your backup repo
+3. Point `.backupconfig.json` to it
+4. Run restore — agents are back online
+
+## Size Considerations
+
+Each backup cycle syncs full agent workspaces and agent directories. Disk usage:
+
+- **`archives/` directory** — Full copy of workspace + agentDir per agent (updated hourly, size stays constant)
+- **Git repository** — Only changed files are committed; grows incrementally with actual changes
+
+### Realistic Example
+
+**1 agent with 100MB workspace:**
+- `archives/main/workspace/` — 100MB (constant, updated each sync)
+- Git growth — 500KB-1MB per day (memory files + config changes) = ~15MB/month
+- Total after 30 days — ~115MB
+
+**3 agents with 100MB each:**
+- `archives/` total — ~300MB (constant)
+- Git growth — ~45MB/month (3 agents × 15MB/month)
+- Total after 30 days — ~345MB
+
+**Note:** If agents have cloned git repos in their workspace, those don't inflate Git (stored in `archives/` only, not committed to backup Git). Backup repo itself grows only by actual edits to memory, config, and metadata files — typically small daily changes.
+
+Recommendation: For typical setups, monthly growth is 10-50MB. A 35GB disk is more than sufficient for years of backups.
+
+**⚠️ Warning:** If agents accidentally save large files (binaries, datasets, etc.) to their workspace, Git history will grow quickly. Use `.gitignore` in agent workspaces to prevent committing large artifacts.
+
+## Limitations
+
+- **Point-in-time restore via Git SHA** — Requires manual `git checkout` before calling restore
+- **No encryption** — Backup repo should be private and secure
+- **No compression** — Backups stored as full directory syncs in Git
+- **Single backup location** — Multi-region replication not supported
+- **Large files bloat Git** — If agents accidentally save large files (binaries, datasets, etc.) to workspace, Git history will balloon. Recommend using `.gitignore` in agent workspaces to prevent this
+
+## Troubleshooting
+
+**Q: Backup runs but doesn't commit?**  
+A: Check Git configuration in the backup repo:
+```bash
+cd /path/to/backup-repo
+git config user.email "test@example.com"
+git config user.name "Test"
+git log --oneline  # Verify commits are created
+```
+
+**Q: Restore says "Archives directory not found"?**  
+A: Run backup at least once to create the archives directory structure.
+
+**Q: Can I back up to a remote server?**  
+A: Yes! `backupRepoPath` can be a local clone of a remote repo. Configure a Git remote and push after backups:
+```bash
+cd /path/to/backup-repo
+git remote add origin <repo-url>
+git push origin main
+```
+
+## Performance
+
+- **Backup time** — Depends on agent size and disk speed. Typical: 30s–2min per agent
+- **Restore time** — Similar to backup time
+- **Cron interval** — Hourly recommended; can run more/less frequently
+
+## License
+
+MIT — Use freely in your projects.
+
+## Contributing
+
+Issues, PRs, and questions welcome! Please include test cases for any changes.
+
+---
+
+**Made for OpenClaw multi-agent setups. Disaster recovery, made simple.**