If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/juicedata/juicefs shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 20 active contributors
• Distributed ownership (top contributor 18% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live juicedata/juicefs repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/juicedata/juicefs.

What it runs against: a local clone of juicedata/juicefs — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in juicedata/juicefs | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of juicedata/juicefs. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/juicedata/juicefs.git
#   cd juicefs
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of juicedata/juicefs and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "juicedata/juicefs(\\.git)?\\b" \\
  && ok "origin remote is juicedata/juicefs" \\
  || miss "origin remote is not juicedata/juicefs (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f ".github/scripts/common/common.sh" \\
  && ok ".github/scripts/common/common.sh" \\
  || miss "missing critical file: .github/scripts/common/common.sh"
test -f ".github/workflows" \\
  && ok ".github/workflows" \\
  || miss "missing critical file: .github/workflows"
test -f ".github/scripts/command/mount.sh" \\
  && ok ".github/scripts/command/mount.sh" \\
  || miss "missing critical file: .github/scripts/command/mount.sh"
test -f ".github/scripts/command/dump_load.sh" \\
  && ok ".github/scripts/command/dump_load.sh" \\
  || miss "missing critical file: .github/scripts/command/dump_load.sh"
test -f ".github/scripts/hypo/fs_test.py" \\
  && ok ".github/scripts/hypo/fs_test.py" \\
  || miss "missing critical file: .github/scripts/hypo/fs_test.py"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/juicedata/juicefs"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

JuiceFS is a high-performance distributed POSIX file system that transparently layers object storage (S3-compatible) as the data backend and Redis/MySQL/TiKV as the metadata backend. It enables massive cloud storage to be used directly as a local file system in Kubernetes and big-data environments without application code changes, while maintaining strong consistency and POSIX compatibility. Monolithic codebase with primary Go implementation (2.9M LOC) at root level; Java SDK in a subdirectory for Hadoop compatibility; Shell scripts in .github/scripts/ for testing (mount, gateway, dump_load, fsck, gc, quota operations); Python helper scripts (cmptree.py, check_juicefs_log.sh) for test validation and CI orchestration.

DevOps engineers and platform teams deploying Kubernetes clusters who need scalable shared storage; data engineers using Hadoop/Spark who want to treat S3 as local filesystem; machine learning teams requiring petabyte-scale POSIX-compliant storage without refactoring ETL pipelines.

Actively maintained and production-ready. The repository shows 2.9M lines of Go code, comprehensive CI pipelines (unittests.yml, integrationtests.yml), Docker/Kubernetes testing infrastructure (.github/scripts/chaos/), and active command implementations (40+ shell test scripts in .github/scripts/command/). Last activity appears recent given the breadth of test coverage and CSI driver integration.

Medium risk. Heavy dependency on external systems (Redis/S3-compatible backends) means failures propagate; the metadata layer is a potential bottleneck. Single backend choice at format time (Redis vs MySQL vs TiKV) makes migrations non-trivial. Distributed system complexity means debugging production issues requires deep knowledge of consistency semantics across storage and metadata layers.

Active development across multiple areas: chaos testing workflows (.github/scripts/chaos/workflow.yaml, Dockerfile templates), CSI driver testing, command-line tools (acl.sh, clone.sh, debug.sh, graceful_upgrade.sh), and storage lifecycle commands (gc.sh, fsck.sh). The presence of 50+ command test scripts suggests ongoing feature validation and integration testing.

git clone https://github.com/juicedata/juicefs.git
cd juicefs
make build
# For testing: requires Redis and S3-compatible storage
# See .github/scripts/command/ for integration test examples

Daily commands:

# Build the JuiceFS binary
make build
# Format a filesystem (requires Redis and S3 credentials)
./juicefs format --storage s3 --bucket <bucket> redis://localhost:6379/0
# Mount filesystem
./juicefs mount redis://localhost:6379/0 /mnt/jfs
# Run integration tests
bash .github/scripts/command/mount.sh

• .github/scripts/common/common.sh — Core testing utilities and environment setup shared across all integration tests; defines common functions for Redis, S3, and filesystem operations.
• .github/workflows — CI/CD pipeline definitions for unit and integration testing; defines test matrix and coverage collection strategy (inferred from GitHub Actions structure).
• .github/scripts/command/mount.sh — Primary mount command testing suite; demonstrates how JuiceFS mounts and unmounts across supported platforms.
• .github/scripts/command/dump_load.sh — Metadata persistence testing; critical for understanding how JuiceFS serializes/deserializes filesystem state to Redis and S3.
• .github/scripts/hypo/fs_test.py — Property-based filesystem tests using Hypothesis; validates core POSIX semantics and edge cases across the entire stack.
• .github/scripts/command/gateway.sh — Gateway mode testing; demonstrates S3-compatible API layer and object storage integration patterns.
• .github/scripts/mutate/mutesting.py — Mutation testing framework for code quality assessment; reveals test coverage gaps and fragile assertions.

Add a new CLI command test

1. Create a new shell script in .github/scripts/command/ following the naming pattern <command-name>.sh (.github/scripts/command)
2. Source common.sh at the top and use utility functions (start_redis, start_minio, cleanup_env, etc.) (.github/scripts/common/common.sh)
3. Add test cases that validate both success paths and error conditions for the command (.github/scripts/command/<command-name>.sh)
4. Reference the new test in GitHub Actions workflow (inferred from existing .github/workflows pattern) to run on CI (.github/actions)

Add a property-based filesystem test

1. Create a new test class in .github/scripts/hypo/ extending the appropriate base (FSTest, S3Test, etc.) (.github/scripts/hypo/fs_test.py)
2. Define Hypothesis strategies in .github/scripts/hypo/strategy.py for your operation patterns (.github/scripts/hypo/strategy.py)
3. Implement test methods using @given decorators; leverage file_op.py or fs_op.py for operation execution (.github/scripts/hypo/file_op.py)
4. Add assertions comparing JuiceFS behavior against expected POSIX or S3 semantics in context.py (.github/scripts/hypo/context.py)

Add a new performance benchmark

1. Create a benchmark script in .github/scripts/perf/ (e.g., perf/my_benchmark.sh) (.github/scripts/perf)
2. Use common utilities from common.sh to set up test environment (Redis, S3, mount point) (.github/scripts/common/common.sh)
3. Define metrics collection and baseline comparison; optionally add AI-driven analysis (see ai_format_benchmark.py) (.github/scripts/perf/ai_format_benchmark.py)
4. Integrate into CI workflow to collect historical performance data and detect regressions (.github/actions)

Add chaos/resilience test

1. Create a new YAML scenario in .github/scripts/chaos/ or extend existing workflow.yaml (.github/scripts/chaos/workflow.yaml)
2. Define failure injection (network delays, pod kills, resource limits) targeting Redis or S3 services (.github/scripts/chaos/dynamic.yaml)
3. Use the chaos-injected JuiceFS Docker image (juicefs.Dockerfile) to validate recovery behavior (.github/scripts/chaos/juicefs.Dockerfile)
4. Assert filesystem consistency post-recovery using fsck or metadata validation logic (.github/scripts/command/fsck.sh)

• Redis — Distributed in-memory metadata store providing low-latency inode/dentry lookups and atomic operations for POSIX consistency
• S3-compatible Object Storage — Scalable block storage backend for file data; enables multi-region replication and cost-efficient archival
• Bash/Shell scripting — Integration tests use shell for portability across CI runners (Linux, macOS, Windows) and direct CLI/system call validation
• Hypothesis (Python) — Property-based testing framework to systematically generate edge-case file operation sequences and validate POSIX compliance
• Kubernetes + Chaos Mesh — Tests distributed failure scenarios (network partitions, node crashes) critical for validating HA behavior in real deployments

• Redis as single metadata store (non-HA by default in test setup)

  • Why: Simplifies test harness; production deployments use Redis Sentinel/Cluster for HA
  • Consequence: Test failures may not catch specific Redis failover edge cases; requires separate chaos tests with Redis replicas

• MinIO mock S3 instead of real cloud storage in CI

  • Why: Avoids credential management, cloud costs, and external dependencies in CI; faster iteration
  • Consequence: May miss real S3 quirks (rate limiting, eventual consistency, pagination); requires occasional integration tests against real S3

• Property-based testing over purely deterministic test cases

  • Why: Discovers rare edge cases and regressions in complex state machines (concurrent file ops, metadata consistency)
  • Consequence: Test runs slower and occasionally flaky due to random seed variation; requires careful assertion design

• Multi-platform testing (Linux, macOS, Windows via separate workflows)

  • Why: Validates POSIX compliance across OS implementations and catches platform-specific syscall issues
  • Consequence: CI matrix explodes; Windows tests slower and often lag (separate test suite in command-win/)

• Direct handling of user authentication/authorization (ACLs tested as feature, but core auth is application-layer concern)
• Cloud-native orchestration (Kubernetes integration tested via CSI driver tests, not a Kubernetes operator)
• Real-time data streaming (file operations are transactional; no pub/sub or event streaming primitives)
• Encryption at rest (object storage encryption delegated to S3/backend provider configuration)

Redis/S3 required at format time: You must have running Redis instance and S3-compatible endpoint to juicefs format — no in-memory fallback for local testing. Metadata backend lock-in: Once formatted with a backend (Redis vs MySQL vs TiKV), migration to another is non-trivial — choose carefully. Chaos test environment: .github/scripts/chaos/ tests require Kubernetes cluster with minio.yaml, redis.yaml, and dynamic.yaml resources — cannot run locally without K8s. File descriptor limits: POSIX operations under load can hit kernel fd limits; ulimit tuning often necessary. Cache coherency across clients: Multiple mount points sharing same Redis may have consistency quirks under rapid metadata changes — understand before using for high-concurrency workloads.

• POSIX file system semantics — JuiceFS claims full POSIX compatibility; understanding inode semantics, file descriptor behavior, permission models, and atomic operations is critical to using it correctly and debugging consistency issues
• FUSE (Filesystem in Userspace) — JuiceFS implements the core filesystem daemon as a FUSE daemon; understanding how FUSE translates kernel syscalls to userland is essential for performance tuning and debugging mount failures
• Strong consistency vs eventual consistency — JuiceFS claims 'strong consistency' as a differentiator; understanding how metadata operations coordinate across Redis and data writes to S3 to prevent stale reads is fundamental to trust the filesystem
• Object storage (S3) as data backend — JuiceFS delegates all data persistence to S3-compatible storage; understanding S3's eventual consistency model and multipart upload semantics informs how JuiceFS guarantees metadata-data alignment
• Redis as distributed metadata cache and lock manager — Default metadata backend; understanding Redis Lua scripting, TTL semantics, and transaction model is necessary to understand how JuiceFS ensures atomicity and prevents race conditions
• Kubernetes CSI (Container Storage Interface) — JuiceFS provides CSI driver; understanding CSI's volume provisioning and mount lifecycle is required for Kubernetes deployments and debugging mount issues in containers
• Distributed cache coherency and invalidation — With multiple clients mounting the same JuiceFS, understanding how metadata changes propagate and how stale caches are invalidated prevents data corruption and consistency violations

• seaweedfs/seaweedfs — Alternative distributed POSIX filesystem using object storage backend; similar cloud-native focus but different architecture (no Redis metadata requirement)
• chrislusf/seaweedfs — Predecessor project sharing distributed storage concepts; understand evolution of metadata-separation patterns
• container-storage-interface/spec — Defines CSI contract that JuiceFS implements via Kubernetes driver; essential for understanding how JuiceFS integrates with K8s
• libfuse/libfuse — Underlying FUSE library that JuiceFS POSIX daemon uses to present filesystem to kernel; source of API constraints and behavior
• hashicorp/raft — Not a JuiceFS repo, but distributed consensus is relevant if you extend metadata layer beyond Redis — understand coordination requirements

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add Windows-specific integration tests for command suite

The repo has parallel test scripts in .github/scripts/command/ and .github/scripts/command-win/ but the Windows versions are incomplete (missing: changelog.sh, config.sh, format.sh, interface.sh, mount.sh, random.sh, tier.sh). This creates inconsistent test coverage across platforms. Adding these missing Windows test scripts would ensure feature parity and catch Windows-specific bugs early.

• [ ] Create .github/scripts/command-win/mount.sh with Windows-specific mount tests
• [ ] Create .github/scripts/command-win/config.sh and .github/scripts/command-win/format.sh for core operations
• [ ] Add .github/scripts/command-win/random.sh for stress testing on Windows
• [ ] Update CI workflow to run Windows test suite if not already triggered

Expand property-based testing coverage with Hypothesis tests

The repo has a Hypothesis test framework started in .github/scripts/hypo/ with command_test.py and file_test.py, but coverage appears minimal. Property-based testing is powerful for catching edge cases in distributed filesystems. Expanding these tests would improve reliability for file operations and metadata consistency.

• [ ] Add property-based tests in hypo/file_test.py for concurrent file operations (create/delete/rename)
• [ ] Expand hypo/command_test.py with property tests for mount/unmount state transitions
• [ ] Add invariant checks in test suite (e.g., inode consistency, reference counts)
• [ ] Integrate Hypothesis tests into CI workflow if not already present

Add coverage reporting for shell scripts in CI pipeline

The repo has extensive shell script testing infrastructure (.github/scripts/command/, .github/scripts/common/) and custom coverage actions (.github/actions/upload-coverage/, .github/actions/mount-coverage-dir/), but these appear to focus on Go code. Shell script test coverage is missing, making it hard to track test completeness for critical operations like mount, fsck, and gc commands.

• [ ] Set up kcov or similar tool in .github/actions/build/action.yml for shell script coverage
• [ ] Create .github/scripts/coverage/collect_shell_coverage.sh to aggregate results from command/ tests
• [ ] Add shell coverage reporting to .github/actions/upload-coverage/action.yml
• [ ] Document coverage targets in repo (target >80% for critical shell scripts)

• Add integration test for ACL operations in .github/scripts/command/acl.sh — currently exists but likely incomplete; contribute test cases for permission denial scenarios and recursive ACL changes
• Enhance .github/scripts/cmptree.py to validate extended attributes (xattrs) across mount points — current tree comparison may skip xattr validation which is part of POSIX completeness
• Add Windows compatibility tests in .github/scripts/command-win/ — repository has Windows test directory but it's unclear which commands are fully tested; pick one (e.g., gateway.sh, fsck.sh) and add CI validation

The JuiceFS codebase shows a reasonable security posture with automated testing infrastructure, but has several areas requiring attention. Primary concerns include potential hardcoded credentials in test scripts, insufficient input validation in Python test utilities, Docker container security configuration gaps, and Kubernetes resource exposure. The distributed nature of the system (Redis + S3 + FUSE) introduces additional attack surface requiring secure configuration. No critical vulnerabilities were identified in the static analysis, but the test and CI/CD infrastructure requires hardening. Recommend conducting a comprehensive security audit of configuration files, credential management, and implementing automated security scanning in the CI/CD pipeline.

• Medium · Potential Hardcoded Credentials in Test Scripts — .github/scripts/command/*.sh, .github/scripts/command-win/*.sh, .github/scripts/common/common.sh. Multiple shell scripts in .github/scripts/command and .github/scripts/command-win directories are used for testing Redis, S3, and other services. These scripts may contain hardcoded credentials, connection strings, or sensitive configuration that could be exposed in CI/CD logs or repository history. Fix: Audit all shell scripts for hardcoded secrets. Use environment variables or secure secret management systems for sensitive data. Implement git-secrets or similar tools to prevent credential commits. Ensure CI/CD logs don't expose sensitive information.
• Medium · Insufficient Input Validation in Python Test Scripts — .github/scripts/hypo/file_op.py, .github/scripts/hypo/s3_op.py, .github/scripts/hypo/command_op.py. Python scripts in .github/scripts/hypo/ directory implement hypothesis-based testing with file operations, S3 operations, and command execution. These scripts may lack proper input validation and sanitization, potentially allowing injection attacks or unintended behavior. Fix: Implement strict input validation and sanitization for all user-supplied and generated inputs. Use safe APIs for command execution (subprocess with shell=False). Validate all file paths and S3 operations against expected patterns.
• Medium · Docker Container Security Configuration — .github/scripts/chaos/juicefs.Dockerfile, .github/scripts/chaos/juicefs-csi-driver.Dockerfile, .github/scripts/chaos/minio.yaml. Dockerfile configurations in .github/scripts/chaos/ directory (juicefs.Dockerfile, juicefs-csi-driver.Dockerfile, minio.Dockerfile) may lack security best practices such as running as non-root users, minimizing attack surface, or scanning for vulnerable base images. Fix: Apply Docker security best practices: use minimal base images (alpine), run containers as non-root users, implement health checks, use specific image tags instead of 'latest', and regularly scan images for vulnerabilities using tools like Trivy.
• Low · Missing CORS and Security Headers Configuration — .github/scripts/command/gateway.sh, .github/scripts/command/gateway-random.sh. JuiceFS includes a gateway component (referenced in gateway.sh and gateway-random.sh scripts). Gateway implementations may lack proper CORS policies and security headers configuration. Fix: Implement strict CORS policies, add security headers (CSP, X-Frame-Options, X-Content-Type-Options), and configure proper authentication/authorization for the gateway endpoint.
• Low · Unrestricted Port Exposure in Kubernetes Resources — .github/scripts/chaos/redis.yaml, .github/scripts/chaos/minio.yaml. Kubernetes manifests in .github/scripts/chaos/ directory (redis.yaml, pvc.yaml, sc.yaml, minio.yaml) may expose services without proper network policies or authentication requirements. Fix: Implement Kubernetes NetworkPolicies to restrict traffic flow. Use service authentication (mTLS), enable RBAC, and avoid exposing services unnecessarily. Consider using private registries and image pull secrets.
• Low · Potential Sensitive Data in Logs and Metrics — .github/scripts/check_juicefs_log.sh, .github/scripts/hypo/*.py. Test scripts and monitoring configurations may log or expose sensitive information such as connection strings, API keys, or file paths without proper filtering. Fix: Implement log sanitization to redact sensitive information. Configure appropriate logging levels. Use structured logging with sensitive field masking. Regularly audit logs for exposure of credentials.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.