@rljson/fs-agent 0.0.23 → 0.0.25

package/dist/fs-agent.d.ts

@@ -131,6 +131,28 @@ export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
 /**
  * Orchestrates filesystem operations with tree structures and blob storage
  */
+/**
+ * A prune smaller than this many files is always allowed through.
+ *
+ * Below it, "most of the folder" is not a meaningful statement: emptying a
+ * three-file folder is an ordinary edit, and a guard that blocked it would
+ * fire constantly on small trees and be turned off.
+ */
+export declare const MASS_DELETE_MIN_FILES = 100;
+/**
+ * Above this share of the folder, a prune is treated as suspicious rather than
+ * intentional.
+ */
+export declare const MASS_DELETE_MAX_RATIO = 0.3;
+/**
+ * A restore that could not put the folder into the state the tree describes.
+ *
+ * The distinction that matters to callers is not why. It is that the folder
+ * does NOT match the tree afterwards, so the ref must not be recorded as
+ * applied and the resulting state must not be advertised to peers.
+ */
+export declare class RestoreIncompleteError extends Error {
+}
 /**
  * Thrown when a restore wrote everything it could but at least one file was
  * held open by another process.
@@ -142,10 +164,28 @@ export declare const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
  * ref as applied — would make one locked file look like an edit that everyone
  * else must adopt.
  */
-export declare class PartialRestoreError extends Error {
+export declare class PartialRestoreError extends RestoreIncompleteError {
     readonly lockedPaths: string[];
     constructor(lockedPaths: string[]);
 }
+/**
+ * Thrown when `cleanTarget` would have deleted most of the folder.
+ *
+ * The dangerous direction of sync is a POPULATED node receiving a tree that
+ * lacks its files: a peer that comes up empty — a fresh clone, a folder not
+ * yet mounted, a bootstrap that raced its own first scan — advertises an empty
+ * tree, and every other node faithfully deletes everything it has.
+ *
+ * Nothing downstream can tell that apart from a genuine bulk deletion, so the
+ * judgement has to be made here, and it is deliberately biased: refusing a
+ * real mass delete costs one manual step, applying a false one costs the data.
+ */
+export declare class MassDeleteRefusedError extends RestoreIncompleteError {
+    readonly wouldPrune: number;
+    readonly totalFiles: number;
+    readonly incomingFiles: number;
+    constructor(wouldPrune: number, totalFiles: number, incomingFiles: number);
+}
 export declare class FsAgent {
     private _scanner;
     private _adapter;

package/dist/fs-agent.js

@@ -1022,7 +1022,11 @@ const DEFAULT_TIMEOUTS = {
 const DISCONNECT_PAUSE_MAX_MS = 3e4;
 const SYNC_ERROR_FILE = ".sync-errors.log";
 const ATOMIC_TMP_PREFIX = ".fsagent-tmp-";
-class PartialRestoreError extends Error {
+const MASS_DELETE_MIN_FILES = 100;
+const MASS_DELETE_MAX_RATIO = 0.3;
+class RestoreIncompleteError extends Error {
+}
+class PartialRestoreError extends RestoreIncompleteError {
   constructor(lockedPaths) {
     super(
       `restore could not write ${lockedPaths.length} locked file${lockedPaths.length === 1 ? "" : "s"}: ${lockedPaths.join(", ")}`
@@ -1031,6 +1035,19 @@ class PartialRestoreError extends Error {
     this.name = "PartialRestoreError";
   }
 }
+class MassDeleteRefusedError extends RestoreIncompleteError {
+  constructor(wouldPrune, totalFiles, incomingFiles) {
+    super(
+      // No pluralisation: the guard only fires above MASS_DELETE_MIN_FILES,
+      // so this is never one file.
+      `refusing to prune ${wouldPrune} of ${totalFiles} local files: the incoming tree has ${incomingFiles === 0 ? "NO files at all" : `only ${incomingFiles}`}, which looks like a peer that came up empty rather than a deletion. Nothing was deleted.`
+    );
+    this.wouldPrune = wouldPrune;
+    this.totalFiles = totalFiles;
+    this.incomingFiles = incomingFiles;
+    this.name = "MassDeleteRefusedError";
+  }
+}
 class FsAgent {
   _scanner;
   _adapter;
@@ -1347,6 +1364,26 @@ ${err.stack}` : String(err);
       );
     }
     if (options?.cleanTarget) {
+      let wouldPrune = 0;
+      for (const existing of preRestore) {
+        if (!expectedFiles.has(existing)) wouldPrune++;
+      }
+      if (wouldPrune > MASS_DELETE_MIN_FILES && (expectedFiles.size === 0 || wouldPrune / preRestore.size > MASS_DELETE_MAX_RATIO)) {
+        console.error(
+          `[FsAgent] MASS DELETE REFUSED on ${target}: the incoming tree would remove ${wouldPrune} of ${preRestore.size} files (incoming tree has ${expectedFiles.size}). Nothing was deleted. If this deletion is real, it has to be applied deliberately.`
+        );
+        this._writeSyncError(
+          "restore/massDeleteGuard",
+          new Error(
+            `refused to prune ${wouldPrune}/${preRestore.size} files; incoming tree had ${expectedFiles.size}`
+          )
+        );
+        throw new MassDeleteRefusedError(
+          wouldPrune,
+          preRestore.size,
+          expectedFiles.size
+        );
+      }
       await this._pruneExtraneous(
         target,
         expectedDirs,
@@ -2156,6 +2193,9 @@ ${err.stack}` : String(err);
           this._currentRef = postRestoreRef;
           return;
         } catch (err) {
+          if (err instanceof MassDeleteRefusedError) {
+            return;
+          }
           if (err instanceof PartialRestoreError) {
             try {
               const halfApplied = await this._scanner.scan();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rljson/fs-agent",
-  "version": "0.0.23",
+  "version": "0.0.25",
   "description": "Rljson fs-agent description",
   "homepage": "https://github.com/rljson/fs-agent",
   "bugs": "https://github.com/rljson/fs-agent/issues",