agentshield 0.0.1

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [2025] [tomsun28]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,106 @@
+# 🛡️ AgentShield
+
+English | [简体中文](./README_CN.md)
+
+The missing safety layer for AI Agents - Give your AI Agent a "regret pill".
+
+**A hardlink-based zero-copy backup system that protects your workspace from unintended AI modifications.**
+
+## ✨ Features
+
+- **⚡ Zero-Copy Backups** - Uses hardlinks for instant, space-efficient backups (10GB file = 1ms backup)
+- **🕵️ Real-time Protection** - Watches your workspace and automatically backs up files before changes
+- **📦 Smart Exclusions** - Automatically ignores `.git`, `node_modules`, build artifacts, etc.
+- **🔒 Atomic Exec Mode** - Snapshot entire workspace before running agent commands
+- **⏮️ Easy Restore** - One command to roll back any file to its original state
+
+## 🚀 Installation
+
+### Via npm
+
+```bash
+npm install -g agentshield
+```
+
+### Download Binary
+
+Download the binary for your platform from the [Releases](https://github.com/tomsun28/agentshield/releases) page (supports Windows, macOS, Linux).
+
+## 📖 Usage
+
+### Watch Mode (Real-time Protection)
+
+```bash
+# Watch current directory
+shield watch
+
+# Watch specific directory
+shield watch ./my-project
+```
+
+### Exec Mode (Recommended for Agent Tasks)
+
+```bash
+# Snapshot workspace, run command, then allow easy restore
+shield exec -- npm run agent-task
+shield exec -- python ai_script.py
+shield exec --path=./my-project -- cargo run
+```
+
+This mode:
+1. Takes a full snapshot before the command runs
+2. Executes your agent command
+3. Allows you to easily restore any modified files
+
+### One-time Snapshot
+
+```bash
+# Take a snapshot of current directory
+shield snapshot
+
+# Take a snapshot of specific directory  
+shield snapshot ./my-project
+```
+
+### Restore Files
+
+```bash
+# List all available backups
+shield restore
+
+# Restore specific file to latest backup
+shield restore src/index.ts
+
+# List all backups with details
+shield list
+```
+
+### Cleanup Old Backups
+
+```bash
+# Remove backups older than 7 days (default)
+shield clean
+
+# Remove backups older than 3 days
+shield clean --days=3
+```
+
+## 🔍 Default Exclusions
+
+These patterns are automatically excluded from backup:
+
+- `.git`, `.git/**`
+- `node_modules`, `node_modules/**`
+- `*.log`, `*.tmp`, `*.swp`
+- `dist/`, `build/`, `.next/`, `.nuxt/`
+- `coverage/`, `.cache/`
+- `__pycache__/`, `*.pyc`
+- `.DS_Store`, `Thumbs.db`
+
+## 🤝 Contributing
+
+Issues and Pull Requests are welcome!
+
+## 📄 License
+
+[Apache License 2.0](./LICENSE)

package/dist/index.js

@@ -0,0 +1,651 @@
+#!/usr/bin/env node
+#!/usr/bin/env bun
+// @bun
+
+// src/cli.ts
+import { resolve } from "path";
+import { existsSync as existsSync2 } from "fs";
+import { spawn } from "child_process";
+
+// src/config.ts
+import { join } from "path";
+var DEFAULT_VAULT_NAME = ".shield";
+var SNAPSHOTS_DIR = "snapshots";
+var INDEX_FILE = "index.json";
+var DEFAULT_EXCLUDE_PATTERNS = [
+  ".git",
+  ".git/**",
+  "node_modules",
+  "node_modules/**",
+  ".shield",
+  ".shield/**",
+  "**/*.log",
+  "**/*.tmp",
+  "**/*.swp",
+  "**/*.swo",
+  "**/~*",
+  "**/.DS_Store",
+  "**/Thumbs.db",
+  "**/__pycache__",
+  "**/__pycache__/**",
+  "**/*.pyc",
+  "**/dist",
+  "**/dist/**",
+  "**/build",
+  "**/build/**",
+  "**/.next",
+  "**/.next/**",
+  "**/.nuxt",
+  "**/.nuxt/**",
+  "**/coverage",
+  "**/coverage/**",
+  "**/.cache",
+  "**/.cache/**"
+];
+function getDefaultConfig(workspace) {
+  return {
+    workspace,
+    vaultDir: join(workspace, DEFAULT_VAULT_NAME),
+    excludePatterns: DEFAULT_EXCLUDE_PATTERNS,
+    maxBackupAgeDays: 7
+  };
+}
+function getSnapshotsDir(config) {
+  return join(config.vaultDir, SNAPSHOTS_DIR);
+}
+function getIndexPath(config) {
+  return join(config.vaultDir, INDEX_FILE);
+}
+
+// src/backup.ts
+import {
+  existsSync,
+  mkdirSync,
+  linkSync,
+  copyFileSync,
+  statSync as statSync2,
+  readFileSync,
+  writeFileSync,
+  unlinkSync as unlinkSync2
+} from "fs";
+import { join as join3, dirname } from "path";
+
+// src/utils.ts
+import { readdirSync, rmdirSync } from "fs";
+import { join as join2, relative } from "path";
+function formatBytes(bytes) {
+  if (bytes === 0)
+    return "0 B";
+  const k = 1024;
+  const sizes = ["B", "KB", "MB", "GB", "TB"];
+  const i = Math.floor(Math.log(bytes) / Math.log(k));
+  return `${parseFloat((bytes / Math.pow(k, i)).toFixed(2))} ${sizes[i]}`;
+}
+function formatTimeAgo(timestamp) {
+  const seconds = Math.floor((Date.now() - timestamp) / 1000);
+  if (seconds < 60)
+    return `${seconds}s ago`;
+  if (seconds < 3600)
+    return `${Math.floor(seconds / 60)}m ago`;
+  if (seconds < 86400)
+    return `${Math.floor(seconds / 3600)}h ago`;
+  return `${Math.floor(seconds / 86400)}d ago`;
+}
+function matchesPattern(filePath, patterns) {
+  const normalizedPath = filePath.replace(/\\/g, "/");
+  for (const pattern of patterns) {
+    if (pattern.includes("**")) {
+      const regex = patternToRegex(pattern);
+      if (regex.test(normalizedPath))
+        return true;
+    } else if (pattern.includes("*")) {
+      const regex = patternToRegex(pattern);
+      if (regex.test(normalizedPath))
+        return true;
+    } else {
+      if (normalizedPath === pattern || normalizedPath.startsWith(pattern + "/") || normalizedPath.includes("/" + pattern + "/") || normalizedPath.endsWith("/" + pattern)) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+function patternToRegex(pattern) {
+  let regex = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&").replace(/\*\*/g, "{{GLOBSTAR}}").replace(/\*/g, "[^/]*").replace(/{{GLOBSTAR}}/g, ".*");
+  return new RegExp(`(^|/)${regex}($|/)`);
+}
+function getAllFiles(dir, baseDir = dir) {
+  const files = [];
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join2(dir, entry.name);
+      if (entry.isDirectory()) {
+        files.push(...getAllFiles(fullPath, baseDir));
+      } else if (entry.isFile()) {
+        files.push(relative(baseDir, fullPath));
+      }
+    }
+  } catch (err) {}
+  return files;
+}
+function removeEmptyDirs(dir) {
+  try {
+    const entries = readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isDirectory()) {
+        removeEmptyDirs(join2(dir, entry.name));
+      }
+    }
+    const remaining = readdirSync(dir);
+    if (remaining.length === 0) {
+      rmdirSync(dir);
+    }
+  } catch (err) {}
+}
+
+// src/backup.ts
+class BackupManager {
+  config;
+  snapshotsDir;
+  indexPath;
+  index;
+  currentSessionId;
+  protectedInSession = new Set;
+  constructor(config) {
+    this.config = config;
+    this.snapshotsDir = getSnapshotsDir(config);
+    this.indexPath = getIndexPath(config);
+    this.currentSessionId = `session_${Date.now()}`;
+    this.ensureVaultExists();
+    this.index = this.loadIndex();
+  }
+  ensureVaultExists() {
+    if (!existsSync(this.config.vaultDir)) {
+      mkdirSync(this.config.vaultDir, { recursive: true });
+    }
+    if (!existsSync(this.snapshotsDir)) {
+      mkdirSync(this.snapshotsDir, { recursive: true });
+    }
+  }
+  loadIndex() {
+    if (existsSync(this.indexPath)) {
+      try {
+        const data = readFileSync(this.indexPath, "utf-8");
+        return JSON.parse(data);
+      } catch {
+        return { entries: [], sessions: {} };
+      }
+    }
+    return { entries: [], sessions: {} };
+  }
+  saveIndex() {
+    writeFileSync(this.indexPath, JSON.stringify(this.index, null, 2));
+  }
+  shouldExclude(filePath) {
+    return matchesPattern(filePath, this.config.excludePatterns);
+  }
+  backupFile(relativePath, forceFullCopy = false) {
+    const fullPath = join3(this.config.workspace, relativePath);
+    if (this.shouldExclude(relativePath)) {
+      return null;
+    }
+    if (this.protectedInSession.has(fullPath)) {
+      return null;
+    }
+    if (!existsSync(fullPath)) {
+      return null;
+    }
+    try {
+      const stats = statSync2(fullPath);
+      if (!stats.isFile()) {
+        return null;
+      }
+      const timestamp = Date.now();
+      const safeFilename = relativePath.replace(/[/\\]/g, "__");
+      const backupFilename = `${timestamp}_${safeFilename}`;
+      const backupPath = join3(this.snapshotsDir, backupFilename);
+      mkdirSync(dirname(backupPath), { recursive: true });
+      let usedHardlink = false;
+      if (forceFullCopy) {
+        copyFileSync(fullPath, backupPath);
+      } else {
+        try {
+          linkSync(fullPath, backupPath);
+          usedHardlink = true;
+        } catch (err) {
+          copyFileSync(fullPath, backupPath);
+        }
+      }
+      const entry = {
+        originalPath: relativePath,
+        backupPath: backupFilename,
+        timestamp,
+        size: stats.size,
+        sessionId: this.currentSessionId
+      };
+      this.index.entries.push(entry);
+      this.protectedInSession.add(fullPath);
+      this.saveIndex();
+      return entry;
+    } catch (err) {
+      console.error(`Failed to backup ${relativePath}:`, err);
+      return null;
+    }
+  }
+  snapshotWorkspace() {
+    const files = getAllFiles(this.config.workspace);
+    let backed = 0;
+    let skipped = 0;
+    for (const file of files) {
+      if (this.shouldExclude(file)) {
+        skipped++;
+        continue;
+      }
+      const entry = this.backupFile(file, true);
+      if (entry) {
+        backed++;
+      } else {
+        skipped++;
+      }
+    }
+    return { total: files.length, backed, skipped };
+  }
+  resetSession() {
+    if (this.index.sessions[this.currentSessionId]) {
+      this.index.sessions[this.currentSessionId].endTime = Date.now();
+    }
+    this.currentSessionId = `session_${Date.now()}`;
+    this.index.sessions[this.currentSessionId] = { startTime: Date.now() };
+    this.protectedInSession.clear();
+    this.saveIndex();
+  }
+  getBackupsForFile(relativePath) {
+    return this.index.entries.filter((e) => e.originalPath === relativePath).sort((a, b) => b.timestamp - a.timestamp);
+  }
+  getAllBackups() {
+    return [...this.index.entries].sort((a, b) => b.timestamp - a.timestamp);
+  }
+  restoreFile(entry) {
+    const backupFullPath = join3(this.snapshotsDir, entry.backupPath);
+    const targetPath = join3(this.config.workspace, entry.originalPath);
+    if (!existsSync(backupFullPath)) {
+      console.error(`Backup file not found: ${entry.backupPath}`);
+      return false;
+    }
+    try {
+      mkdirSync(dirname(targetPath), { recursive: true });
+      copyFileSync(backupFullPath, targetPath);
+      return true;
+    } catch (err) {
+      console.error(`Failed to restore ${entry.originalPath}:`, err);
+      return false;
+    }
+  }
+  restoreLatest(relativePath) {
+    const backups = this.getBackupsForFile(relativePath);
+    if (backups.length === 0) {
+      console.error(`No backups found for: ${relativePath}`);
+      return false;
+    }
+    return this.restoreFile(backups[0]);
+  }
+  restoreSession(sessionId) {
+    const sessionEntries = this.index.entries.filter((e) => e.sessionId === sessionId);
+    let restored = 0;
+    let failed = 0;
+    const latestByFile = new Map;
+    for (const entry of sessionEntries) {
+      const existing = latestByFile.get(entry.originalPath);
+      if (!existing || entry.timestamp < existing.timestamp) {
+        latestByFile.set(entry.originalPath, entry);
+      }
+    }
+    for (const entry of latestByFile.values()) {
+      if (this.restoreFile(entry)) {
+        restored++;
+      } else {
+        failed++;
+      }
+    }
+    return { restored, failed };
+  }
+  cleanOldBackups(maxAgeDays) {
+    const cutoff = Date.now() - maxAgeDays * 24 * 60 * 60 * 1000;
+    let removed = 0;
+    let freedBytes = 0;
+    const toRemove = [];
+    const toKeep = [];
+    for (const entry of this.index.entries) {
+      if (entry.timestamp < cutoff) {
+        toRemove.push(entry);
+      } else {
+        toKeep.push(entry);
+      }
+    }
+    for (const entry of toRemove) {
+      const backupPath = join3(this.snapshotsDir, entry.backupPath);
+      try {
+        if (existsSync(backupPath)) {
+          const stats = statSync2(backupPath);
+          unlinkSync2(backupPath);
+          freedBytes += stats.size;
+          removed++;
+        }
+      } catch (err) {}
+    }
+    this.index.entries = toKeep;
+    this.saveIndex();
+    removeEmptyDirs(this.snapshotsDir);
+    return { removed, freedBytes };
+  }
+  getStats() {
+    const uniqueFiles = new Set(this.index.entries.map((e) => e.originalPath));
+    const totalSize = this.index.entries.reduce((sum, e) => sum + e.size, 0);
+    return {
+      totalBackups: this.index.entries.length,
+      totalSize,
+      uniqueFiles: uniqueFiles.size,
+      sessions: Object.keys(this.index.sessions).length
+    };
+  }
+}
+
+// src/watcher.ts
+import { watch } from "fs";
+
+class ShieldWatcher {
+  config;
+  backupManager;
+  watcher = null;
+  debounceMap = new Map;
+  debounceMs = 50;
+  constructor(config, backupManager) {
+    this.config = config;
+    this.backupManager = backupManager;
+  }
+  start() {
+    if (this.watcher) {
+      console.log("Watcher already running");
+      return;
+    }
+    console.log(`\uD83D\uDE80 Shield started, protecting: ${this.config.workspace}`);
+    console.log(`\uD83D\uDCC1 Vault location: ${this.config.vaultDir}`);
+    console.log("─".repeat(50));
+    this.watcher = watch(this.config.workspace, { recursive: true }, (event, filename) => {
+      if (!filename)
+        return;
+      const normalizedFilename = filename.replace(/\\/g, "/");
+      if (normalizedFilename.startsWith(".shield") || this.backupManager.shouldExclude(normalizedFilename)) {
+        return;
+      }
+      const existingTimeout = this.debounceMap.get(normalizedFilename);
+      if (existingTimeout) {
+        clearTimeout(existingTimeout);
+      }
+      const timeout = setTimeout(() => {
+        this.debounceMap.delete(normalizedFilename);
+        this.handleFileChange(normalizedFilename);
+      }, this.debounceMs);
+      this.debounceMap.set(normalizedFilename, timeout);
+    });
+    this.watcher.on("error", (err) => {
+      console.error("Watcher error:", err);
+    });
+  }
+  handleFileChange(relativePath) {
+    const entry = this.backupManager.backupFile(relativePath);
+    if (entry) {
+      console.log(`[\uD83D\uDEE1️ Shield] Original version locked: ${relativePath}`);
+    }
+  }
+  stop() {
+    if (this.watcher) {
+      this.watcher.close();
+      this.watcher = null;
+      for (const timeout of this.debounceMap.values()) {
+        clearTimeout(timeout);
+      }
+      this.debounceMap.clear();
+      console.log("Shield stopped");
+    }
+  }
+  resetSession() {
+    this.backupManager.resetSession();
+    console.log("─".repeat(50));
+    console.log("\uD83D\uDD04 New session started, protection state reset");
+  }
+}
+
+// src/cli.ts
+function parseArgs(args) {
+  const result = {
+    command: args[0] || "help",
+    args: [],
+    flags: {}
+  };
+  for (let i = 1;i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const [key, value] = arg.slice(2).split("=");
+      result.flags[key] = value ?? true;
+    } else if (arg.startsWith("-")) {
+      result.flags[arg.slice(1)] = true;
+    } else {
+      result.args.push(arg);
+    }
+  }
+  return result;
+}
+function printHelp() {
+  console.log(`
+\uD83D\uDEE1️  Shield - File Protection for AI Agents
+
+Usage:
+  shield <command> [options]
+
+Commands:
+  watch [path]           Start watching a directory (default: current dir)
+  exec <command>         Snapshot workspace, run command, then allow restore
+  snapshot [path]        Take a one-time snapshot of all files
+  restore [file]         Restore a file to its backed-up version
+  list                   List all backups
+  clean [--days=N]       Remove backups older than N days (default: 7)
+  status                 Show backup statistics
+  help                   Show this help message
+
+Options:
+  --path=<dir>           Specify workspace directory
+  --days=<N>             For clean command: max age in days
+
+Examples:
+  shield watch ./my-project
+  shield exec -- npm run agent-task
+  shield restore src/index.ts
+  shield clean --days=3
+  shield status
+`);
+}
+async function runCli(argv) {
+  const options = parseArgs(argv.slice(2));
+  switch (options.command) {
+    case "watch":
+      await cmdWatch(options);
+      break;
+    case "exec":
+      await cmdExec(options, argv);
+      break;
+    case "snapshot":
+      await cmdSnapshot(options);
+      break;
+    case "restore":
+      await cmdRestore(options);
+      break;
+    case "list":
+      await cmdList(options);
+      break;
+    case "clean":
+      await cmdClean(options);
+      break;
+    case "status":
+      await cmdStatus(options);
+      break;
+    case "help":
+    default:
+      printHelp();
+      break;
+  }
+}
+async function getConfig(options) {
+  const pathArg = options.flags["path"] || options.args[0] || ".";
+  const workspace = resolve(pathArg);
+  if (!existsSync2(workspace)) {
+    console.error(`Error: Directory not found: ${workspace}`);
+    process.exit(1);
+  }
+  return getDefaultConfig(workspace);
+}
+async function cmdWatch(options) {
+  const config = await getConfig(options);
+  const backupManager = new BackupManager(config);
+  const watcher = new ShieldWatcher(config, backupManager);
+  watcher.start();
+  process.on("SIGINT", () => {
+    console.log(`
+`);
+    watcher.stop();
+    const stats = backupManager.getStats();
+    console.log(`
+\uD83D\uDCCA Session summary: ${stats.totalBackups} backups, ${stats.uniqueFiles} unique files`);
+    process.exit(0);
+  });
+  await new Promise(() => {});
+}
+async function cmdExec(options, rawArgv) {
+  const dashDashIndex = rawArgv.indexOf("--");
+  if (dashDashIndex === -1 || dashDashIndex === rawArgv.length - 1) {
+    console.error("Usage: shield exec -- <command>");
+    console.error("Example: shield exec -- npm run agent-task");
+    process.exit(1);
+  }
+  const commandArgs = rawArgv.slice(dashDashIndex + 1);
+  const pathArg = options.flags["path"] || ".";
+  const workspace = resolve(pathArg);
+  const config = getDefaultConfig(workspace);
+  const backupManager = new BackupManager(config);
+  console.log("\uD83D\uDEE1️  Shield Exec Mode");
+  console.log("─".repeat(50));
+  console.log("\uD83D\uDCF8 Taking pre-execution snapshot...");
+  const snapshot = backupManager.snapshotWorkspace();
+  console.log(`✓ Snapshot complete: ${snapshot.backed} files backed up, ${snapshot.skipped} skipped`);
+  console.log("─".repeat(50));
+  console.log(`\uD83D\uDE80 Running: ${commandArgs.join(" ")}`);
+  console.log("─".repeat(50));
+  const child = spawn(commandArgs[0], commandArgs.slice(1), {
+    stdio: "inherit",
+    shell: true,
+    cwd: workspace
+  });
+  await new Promise((resolve2, reject) => {
+    child.on("close", (code) => {
+      console.log("─".repeat(50));
+      if (code === 0) {
+        console.log("✓ Command completed successfully");
+      } else {
+        console.log(`⚠ Command exited with code ${code}`);
+      }
+      console.log(`
+\uD83D\uDCA1 To restore files, run: shield restore <file>`);
+      console.log("   To list all backups: shield list");
+      resolve2();
+    });
+    child.on("error", reject);
+  });
+}
+async function cmdSnapshot(options) {
+  const config = await getConfig(options);
+  const backupManager = new BackupManager(config);
+  console.log("\uD83D\uDCF8 Taking snapshot...");
+  const result = backupManager.snapshotWorkspace();
+  console.log(`✓ Complete: ${result.backed} files backed up, ${result.skipped} skipped`);
+}
+async function cmdRestore(options) {
+  const config = await getConfig(options);
+  const backupManager = new BackupManager(config);
+  const fileArg = options.args[0];
+  if (!fileArg) {
+    const backups = backupManager.getAllBackups();
+    if (backups.length === 0) {
+      console.log("No backups available");
+      return;
+    }
+    console.log(`Available backups (use 'shield restore <file>' to restore):
+`);
+    const uniqueFiles = new Map;
+    for (const backup of backups) {
+      if (!uniqueFiles.has(backup.originalPath)) {
+        uniqueFiles.set(backup.originalPath, backup);
+      }
+    }
+    for (const [path, backup] of uniqueFiles) {
+      console.log(`  ${path} (${formatTimeAgo(backup.timestamp)})`);
+    }
+    return;
+  }
+  console.log(`\uD83D\uDD04 Restoring: ${fileArg}`);
+  const success = backupManager.restoreLatest(fileArg);
+  if (success) {
+    console.log(`✓ Restored: ${fileArg}`);
+  } else {
+    console.log(`✗ Failed to restore: ${fileArg}`);
+    process.exit(1);
+  }
+}
+async function cmdList(options) {
+  const config = await getConfig(options);
+  const backupManager = new BackupManager(config);
+  const backups = backupManager.getAllBackups();
+  if (backups.length === 0) {
+    console.log("No backups found");
+    return;
+  }
+  console.log(`\uD83D\uDCCB All Backups (${backups.length} total)
+`);
+  for (const backup of backups.slice(0, 50)) {
+    const timeStr = formatTimeAgo(backup.timestamp);
+    const sizeStr = formatBytes(backup.size);
+    console.log(`  ${backup.originalPath}`);
+    console.log(`    └─ ${timeStr} | ${sizeStr}`);
+  }
+  if (backups.length > 50) {
+    console.log(`
+  ... and ${backups.length - 50} more`);
+  }
+}
+async function cmdClean(options) {
+  const config = await getConfig(options);
+  const backupManager = new BackupManager(config);
+  const days = parseInt(options.flags["days"]) || 7;
+  console.log(`\uD83E\uDDF9 Cleaning backups older than ${days} days...`);
+  const result = backupManager.cleanOldBackups(days);
+  console.log(`✓ Removed ${result.removed} backups, freed ${formatBytes(result.freedBytes)}`);
+}
+async function cmdStatus(options) {
+  const config = await getConfig(options);
+  const backupManager = new BackupManager(config);
+  const stats = backupManager.getStats();
+  console.log(`\uD83D\uDCCA Shield Status
+`);
+  console.log(`  Workspace:      ${config.workspace}`);
+  console.log(`  Vault:          ${config.vaultDir}`);
+  console.log(`  Total Backups:  ${stats.totalBackups}`);
+  console.log(`  Unique Files:   ${stats.uniqueFiles}`);
+  console.log(`  Total Size:     ${formatBytes(stats.totalSize)}`);
+  console.log(`  Sessions:       ${stats.sessions}`);
+}
+
+// src/index.ts
+runCli(process.argv).catch((err) => {
+  console.error("Error:", err.message);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "agentshield",
+  "version": "0.0.1",
+  "description": "Instant file protection for AI agent operations - hardlink-based zero-copy backup system",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "shield": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build:npm": "bun build ./src/index.ts --outdir dist --target node && echo '#!/usr/bin/env node' | cat - dist/index.js > dist/temp && mv dist/temp dist/index.js && chmod +x dist/index.js",
+    "build:bin": "bun build --compile ./src/index.ts --outfile shield",
+    "build:bin:windows": "bun build --compile --target=bun-windows-x64 ./src/index.ts --outfile shield.exe",
+    "build:bin:linux": "bun build --compile --target=bun-linux-x64 ./src/index.ts --outfile shield-linux",
+    "build:bin:all": "bun run build:bin && bun run build:bin:windows && bun run build:bin:linux",
+    "prepublishOnly": "bun run build:npm"
+  },
+  "keywords": [
+    "agent",
+    "backup",
+    "protection",
+    "hardlink",
+    "rollback",
+    "ai-safety"
+  ],
+  "author": "tomsun28",
+  "license": "Apache-2.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tomsun28/agentshield.git"
+  },
+  "homepage": "https://github.com/tomsun28/agentshield#readme",
+  "bugs": {
+    "url": "https://github.com/tomsun28/agentshield/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.0.0"
+  }
+}