Racha CLI – Storacha-backed VCS Prototype – 25 Aug to 7 Sep 2025 (Week4-5) - PLDG 4

[adielliot37]

Racha CLI – Storacha-backed VCS Prototype – 25 Aug to 7 Sep 2025 (Week4-5) - PLDG 4

Contributors

• @adielliot37

---

Repository

github.com/adielliot37/racha-cli

---

racha-cli

---

Accomplished Tasks

• Designed and implemented a Git-like CLI (racha) with commands:
  • racha add → stage files into .racha_repo/staging.
  • racha push → upload staged files + index.json + commit.json via Storacha MCP REST.
  • racha clone → fetch commits and files back using MCP + public IPFS gateways fallback.
• Integrated with Storacha MCP REST server deployed on VPS.
• Implemented index.json manifest structure to map fileCid, rootCid, and payload metadata.
• Added local repo metadata (.racha_repo/meta.json) to track HEAD commit.

---

Update

• Push flow:
  • Files staged with racha add are uploaded individually to MCP.
  • Built index.json manifest capturing file → CID mappings.
  • Created and uploaded commit.json linking to the index root (treeRef).
  • Updated local meta.json with new HEAD commitCID.
• Clone flow:
  • Enhanced to try MCP retrieve first, then gracefully fallback to IPFS gateways (storacha.link, ipfs.io, dweb.link) when bare fileCIDs failed.
  • Reconstructed missing commit.json locally if gateway retrieval failed.
• What went well:
  • Able to push → get back CIDs → and clone files back locally.
  • First successful round-trip (add → push → clone) completed with test.txt.
• Challenges:
  • MCP retrieve required rootCid/filename paths — bare fileCIDs caused IpfsPathError.
  • Gateways sometimes returned HTML instead of JSON for commitCID, requiring fallback logic.
  • Solution: improved clone handler to decode base64 index.json and use fileCid directly.

---

Next Tasks

• Patch racha clone fully with gateway + index fallback (ready-to-drop code prepared).
• Refactor racha push to upload entire tree (files + index.json + commit.json) inside a single root CID for robust retrieval.
• Add racha log to walk commit history via parent pointers.
• Add commit signing (EIP-191) using ethers to verify authorship.