client-replica: the first release

This is a squashed commit of following commits. The squash is due
to massive conflict.

add apitest to github actions (#1591)

test: add puterjs test to apiteste (#1590)

client-replica: local read, replica init

update proto definition

client-replica: update the tree structure

pick package.json (root + puterjs) from main

client-replica: got the same hash algo on js and go

client-replica: update design and api

client-replica: update design, add rpc PullDiff

client-replica: update pull/push requests

client-replica: use string hash

client-replica: remove bigint hash

client-replica: update code format

client-replica: update rpc

client-replica: use user_id instead of user_name

client-replica: fix root path, add integrity check

client-replica: force pull

client-replica: update design, aligh implementation with it

client-replica: simplified socket logic

client-replica: add purge logic to server.go, update rpc

client-replica: purge logic

client-replica: draft hook for rename, too many pitfalls

client-replica: add parent_uid patch to move

client-replica: inject failure to server.go

client-replica: tidy debug code

client-replica: remove api InitReplica (generated by mistake)

client-replica: update doc comments

client-replica: reorg backend fs_tree_manager

client-replica: update hooks, udpate api name

client-replica: fatal -> panic

client-replica: update RemoveFSEntry

client-replica: use map children_uuids to avoid duplicate

client-replica: update children_uuids in js

client-replica: update doc comments

clietn-replica: update doc comments

client-replica: refactor fs_tree_manager, add config

client-replica: add mysql support

client-replica: update config

client-replica: add missing lock

client-replica: update the RFC

client-replica: update chaos mode

client-replica: remove some logs

client-replica: deal with dir rename/move, update hooks

client-replica: update docs

Author: XiaochenCui

.gitignore

@@ -45,5 +45,13 @@ jsconfig.json
 # the exact tree installed in the node_modules folder
 package-lock.json
 
+# ======================================================================
+# fs tree manager
+# ======================================================================
+src/fs_tree_manager/config.yaml
+
+# ======================================================================
+# other
+# ======================================================================
 AGENTS.md
 .roo

doc/RFCS/20250821_client_replica_file_system.md

@@ -59,11 +59,14 @@
     "@aws-sdk/client-secrets-manager": "^3.879.0",
     "@aws-sdk/client-sns": "^3.907.0",
     "@google/genai": "^1.19.0",
+    "@grpc/grpc-js": "^1.14.0",
     "@heyputer/putility": "^1.0.2",
     "@paralleldrive/cuid2": "^2.2.2",
     "@stylistic/eslint-plugin-js": "^4.4.1",
     "dedent": "^1.5.3",
     "express-xml-bodyparser": "^0.4.1",
+    "google-protobuf": "^4.0.0",
+    "grpc-tools": "^1.13.0",
     "ioredis": "^5.6.0",
     "javascript-time-ago": "^2.5.11",
     "json-colorizer": "^3.0.1",
@@ -72,7 +75,8 @@
     "rollup": "^4.52.4",
     "simple-git": "^3.25.0",
     "string-template": "^1.0.0",
-    "uuid": "^9.0.1"
+    "uuid": "^9.0.1",
+    "xxhash-wasm": "^1.1.0"
   },
   "optionalDependencies": {
     "sharp": "^0.34.4",

doc/RFCS/assets/20251008_134412_puter-client_replica_overview.drawio.svg

@@ -216,6 +216,7 @@ class HLCopy extends HLFilesystemOperation {
 
         await this.copied.awaitStableEntry();
         const response = await this.copied.getSafeEntry({ thumbnail: true });
+        
         return {
             copied : response,
             overwritten

doc/RFCS/assets/20251008_134726_puter-client_replica_network.drawio.svg

@@ -32,6 +32,7 @@ const { is_valid_path } = require('../validation');
 const { HLRemove } = require('./hl_remove');
 const { LLMkdir } = require('../ll_operations/ll_mkdir');
 
+
 class MkTree extends HLFilesystemOperation {
     static DESCRIPTION = `
         High-level operation for making directory trees
@@ -378,7 +379,10 @@ class HLMkdir extends HLFilesystemOperation {
             });
 
             await this.created.awaitStableEntry();
-            return await this.created.getSafeEntry();
+            const response = await this.created.getSafeEntry();
+            
+            
+            return response;
         }
 
         const ll_mkdir = new LLMkdir();
@@ -402,6 +406,7 @@ class HLMkdir extends HLFilesystemOperation {
         }
         response.requested_path = values.path;
 
+
         return response;
     }
 

doc/RFCS/assets/20251008_134849_puter-client_replica_deployment1.drawio.svg

@@ -69,7 +69,9 @@ class HLMkLink extends HLFilesystemOperation {
         });
 
         await created.awaitStableEntry();
-        return await created.getSafeEntry();
+        const response = await created.getSafeEntry();
+        
+        return response;
     }
 }
 

package.json

@@ -98,7 +98,9 @@ class HLMkShortcut extends HLFilesystemOperation {
         });
 
         await created.awaitStableEntry();
-        return await created.getSafeEntry();
+        const response = await created.getSafeEntry();
+        
+        return response;
     }
 }