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/spacedriveapp/spacedrive 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.

WAIT — Mixed signals — read the receipts

• Last commit 3w ago
• 2 active contributors
• Other licensed
• CI configured
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 68% of recent commits
• ⚠ Non-standard license (Other) — review terms
• ⚠ No test directory detected

_{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 spacedriveapp/spacedrive repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/spacedriveapp/spacedrive.

What it runs against: a local clone of spacedriveapp/spacedrive — 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 spacedriveapp/spacedrive | Confirms the artifact applies here, not a fork | | 2 | License is still Other | 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 ≤ 48 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of spacedriveapp/spacedrive. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/spacedriveapp/spacedrive.git
#   cd spacedrive
#
# 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 spacedriveapp/spacedrive and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other 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/workflows/ci.yml" \\
  && ok ".github/workflows/ci.yml" \\
  || miss "missing critical file: .github/workflows/ci.yml"
test -f ".github/workflows/release.yml" \\
  && ok ".github/workflows/release.yml" \\
  || miss "missing critical file: .github/workflows/release.yml"
test -f ".github/actions/publish-artifacts/index.ts" \\
  && ok ".github/actions/publish-artifacts/index.ts" \\
  || miss "missing critical file: .github/actions/publish-artifacts/index.ts"
test -f ".cargo/config.toml.mustache" \\
  && ok ".cargo/config.toml.mustache" \\
  || miss "missing critical file: .cargo/config.toml.mustache"
test -f ".github/CODEOWNERS" \\
  && ok ".github/CODEOWNERS" \\
  || miss "missing critical file: .github/CODEOWNERS"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 48 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~18d)"
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/spacedriveapp/spacedrive"
  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).

Spacedrive is a cross-platform virtual distributed file system and file explorer (macOS, Windows, Linux, iOS, Android) that indexes and unifies access to local storage, external drives, NAS, and cloud volumes (S3, Google Drive, Dropbox, OneDrive, Azure, GCS) through a single interface. Core innovation: BLAKE3 content hashing for deduplication and P2P sync via Iroh/QUIC with zero-knowledge architecture—files stay local unless explicitly synced between your own devices. Monorepo with Rust backend core (6.2MB, 99% of codebase), TypeScript/React frontends, Swift iOS integration, and Python utilities. Backend likely in src-tauri or similar Rust workspace root; frontend in apps/desktop or packages/ui; .github/actions/publish-artifacts/ shows custom CI orchestration; .tasks/core/ contains epic-level work items (AI agents, action system, CLI) organized by feature domain.

Power users managing files across multiple devices and cloud services who want unified search and deduplication without vendor lock-in; developers building file management UIs who can embed Spacedrive's APIs and interfaces; open-source contributors interested in distributed systems, Rust backends, and cross-platform desktop/mobile frontends.

Actively developed with 6.2MB of Rust code across a full-featured desktop/mobile stack, multiple CI workflows (.github/workflows/ci.yml, core_tests.yml, mobile.yml, release.yml), and structured task tracking (.tasks/core/), indicating serious production intent. The FSL-1.1-ALv2 license and v2.spacedrive.com domain suggest a mature project, but the open alpha status and active Discord community (949090953497567312) indicate still-evolving core features.

Large monorepo (TypeScript + Rust interdependencies) with complex build configuration (.cargo/config.toml.mustache, separate mobile workflows) creates potential for environment setup friction. P2P sync via Iroh is a relatively young dependency ecosystem; core virtual filesystem abstraction is mission-critical and changes here cascade across all platforms. No visibility into open issue backlog or PR merge rate from repo metadata alone, but mobile.yml and release.yml suggest active deployment pipeline.

Active development on AI-agent integration (AI-000-ai-epic.md, AI-001-ai-agent.md, AI-002-create-finetuning-dataset.md), action system architecture (ACT-000-action-system.md, ACT-001-action-manager-registry.md), and CLI tooling (CLI-000-command-line-interface.md) per .tasks/core/. Release and server workflows indicate ongoing deployment cycles; core_tests.yml and cache-factory.yaml suggest recent refactoring of test infrastructure.

Clone: git clone https://github.com/spacedriveapp/spacedrive.git && cd spacedrive. Install: check .node-version (use that Node version), .nvmrc for nvm, then npm install or bun install (bun.lock present in .github/actions/). For Rust: cargo build (see .cargo/config.toml.mustache for env setup). See .github/workflows/ci.yml for full build matrix (macOS, Windows, Linux, iOS, Android).

Daily commands: Desktop dev: cargo build --release (Rust backend) + npm run dev or bun dev (TypeScript frontend, likely from apps/desktop/package.json—not shown but inferred). For testing: .github/workflows/core_tests.yml likely runs cargo test. Mobile: Follow .github/workflows/mobile.yml steps for iOS/Android builds. See .editorconfig and .rustfmt.toml for local formatting (run cargo fmt and npm run lint).

• .github/workflows/ci.yml — Primary CI/CD pipeline orchestrating all tests, builds, and releases across Rust backend and TypeScript frontend—fundamental to understanding build and deployment flow.
• .github/workflows/release.yml — Release workflow managing cross-platform binary artifacts and version management—essential for understanding how Spacedrive publishes builds to users.
• .github/actions/publish-artifacts/index.ts — GitHub Actions publish logic using artifact and glob APIs—critical for understanding CI/CD artifact handling and distribution to multiple platforms.
• .cargo/config.toml.mustache — Cargo workspace configuration template for Rust backend—defines Rust toolchain, dependencies, and build settings across all Rust crates.
• .github/CODEOWNERS — Defines code ownership and review requirements by file path—essential for understanding governance, review flow, and responsible maintainers for each subsystem.
• .eslintrc.cjs — TypeScript/JavaScript linting configuration—establishes code standards and quality gates for all frontend and Node.js tooling code.
• .rustfmt.toml — Rust code formatting rules—ensures consistent style across the virtual distributed filesystem core written in Rust.

Add a New CI/CD Workflow

1. Create new workflow YAML in .github/workflows/ following existing patterns (e.g., ci.yml, release.yml structure) (.github/workflows/ci.yml)
2. Reference system setup action for dependency installation (Rust, Node, Bun) (.github/actions/setup-system/action.yml)
3. Use Cargo config for Rust builds and ESLint for TypeScript linting (.cargo/config.toml.mustache)
4. For artifact publishing, extend publish-artifacts action with new platform targets (.github/actions/publish-artifacts/index.ts)

Add a New Backend Feature (Rust)

1. Review VDFS core architecture and indexing pipeline specs (.tasks/core/CORE-000-vdfs-core.md)
2. Create new Rust crate or module following Cargo workspace structure (.cargo/config.toml.mustache)
3. Ensure code passes rustfmt (formatting) and clippy (linting) rules (.rustfmt.toml)
4. Add tests and validate via CI pipeline (.github/workflows/core_tests.yml)

Add a New Frontend Component

1. Create TypeScript/TSX component in desktop or mobile UI directory (.eslintignore)
2. Run ESLint to validate code quality and style compliance (.prettierrc)
3. Format code with Prettier using configured indentation and line length (.prettierrc)
4. Validate in CI pipeline (Bun build system) (.github/workflows/ci.yml)

Update Development Documentation

1. Add or update architectural decision record (ADR) in .tasks/core/ matching naming convention (e.g., FEATURE-###-description.md) (.tasks/core/CORE-000-vdfs-core.md)
2. Reference in Claude.md for AI-assisted context and task planning (.tasks/Claude.md)
3. Include spell-check domain terms in appropriate .cspell/ file (backend_custom_words.txt or frontend_custom_words.txt) (.cspell/backend_custom_words.txt)

• Rust (Cargo workspace) — Core VDFS requires high performance, memory safety, and native cross-platform compilation for file system operations and P2P sync
• TypeScript + React (Bun build) — Unified frontend codebase for desktop (Tauri/Electron) and mobile (React Native) with fast build times via Bun package manager
• GitHub Actions + Artifact API — Native CI/CD for monorepo with multi-platform build matrix and automated artifact publishing to cloud storage
• FSL-1.1-ALv2 Dual License — Permissive open-source license allowing commercial use while protecting core VDFS innovations

• Monorepo structure (Rust + TypeScript in single repo)

  • Why: Unified versioning, shared CI/CD, and easier coordination across core and UI layers
  • Consequence: Larger CI build matrix complexity; requires careful workspace configuration and build time optimization

• Multi-platform native apps (macOS, Windows, Linux, iOS, Android)

  • Why: Cross-device file management requires native platform APIs for file system access, permissions, and OS integration
  • Consequence: Increased build complexity, platform-specific code paths, and longer CI pipeline runtime

• Bun package manager over npm/yarn

  • Why: Faster TypeScript/JavaScript builds and better monorepo dependency management
  • Consequence: Smaller ecosystem maturity; requires explicit Node version management (.nvmrc, .node-version)

• Virtual Distributed File System (VDFS) abstraction layer

  • Why: Unified interface across local, cloud, and P2P storage; enables smart sync and deduplication
  • Consequence: Significant architectural complexity; requires careful index consistency and closure table management

• Real-time collaborative file editing (like Google Docs)—focuses on async sync and P2P discovery
• Enterprise authentication/SSO—single-user or peer-based trust model
• Blockchain-based proof-of-ownership—uses content identity hashing, not blockchain
• Native kernel file system driver—relies on userspace VDFS abstraction only

Mustache templating in .cargo/config.toml.mustache means raw config.toml may not exist—build system generates it from env vars (check CI for example values). Mobile builds require platform SDKs (iOS: Xcode, Android: Android Studio/NDK)—.github/workflows/mobile.yml will show exact setup. P2P sync relies on Iroh library which may have breaking changes; check Cargo.lock for pinned version. Custom spell-check dictionaries (.cspell/) are enforced in CI—adding new technical terms requires updates there. Tauri/Electron build can be finicky on Linux; .github/actions/setup-system/ defines OS-level dependencies.

• BLAKE3 Content Hash — Spacedrive's core identity mechanism—same file on two devices produces same hash regardless of path, enabling cross-device deduplication and P2P sync verification
• Virtual Distributed Filesystem (vdfs) — Abstraction layer unifying local, cloud, and offline storage as single namespace—new contributors must understand how it bridges OS filesystems with P2P volumes
• P2P Sync via Iroh/QUIC — Spacedrive syncs metadata and files between devices without cloud servers using QUIC transport; contributors touching sync logic need to understand connection establishment, reliability, and offline queuing
• CRDTs (Conflict-free Replicated Data Types) — Likely used for eventual-consistency merging of filesystem metadata across offline devices without centralized coordination
• Content-Addressable Storage — Files indexed by BLAKE3 hash rather than path—deduplication, backup, and cross-cloud mapping rely on this; enables 'same file on S3 and local disk = one logical entity'
• Monorepo with Workspace Dependencies — Rust + TypeScript + Swift + Python coexist; Cargo and npm workspaces have different versioning and publish semantics—breaking one breaks all platforms
• Zero-Knowledge Encryption Model — P2P sync architecture means servers never see unencrypted data; relevant to auth, key derivation, and sidecar metadata handling

• tauri-apps/tauri — Likely the desktop framework for Spacedrive; shared dependency and build patterns for cross-platform Rust + TypeScript apps
• iroh-n0/iroh — P2P networking library used by Spacedrive for Iroh/QUIC sync; upstream for distributed-systems features and breaking changes
• BLAKE3-team/BLAKE3 — Core hashing algorithm for Spacedrive's content identity and deduplication; reference for crypto integration and performance tuning
• zed-industries/zed — Comparable Rust + TypeScript cross-platform desktop app; similar build challenges and CI/CD patterns for reference
• stacks-archive/stacks-blockchain — Inspiration for distributed identity and content-addressed storage; Spacedrive borrows some CRDT and merkle-tree patterns

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 type safety validation and tests for GitHub Actions setup-rust action

The .github/actions/setup-rust/action.yml is a critical workflow action but there's no corresponding test file or validation. Given that this is used across multiple CI workflows (ci.yml, core_tests.yml, release.yml), adding TypeScript tests and input validation would prevent silent failures in Rust environment setup across all platforms (macOS, Windows, Linux).

• [ ] Create .github/actions/setup-rust/index.ts with type-safe action implementation
• [ ] Add .github/actions/setup-rust/package.json and tsconfig.json similar to publish-artifacts pattern
• [ ] Create .github/actions/setup-rust/__tests__/setup.test.ts covering Rust version detection and cache behavior
• [ ] Build with @vercel/ncc and commit dist/ folder like publish-artifacts does
• [ ] Reference implementation in action.yml to call compiled index.js

Implement spellcheck CI workflow for custom word lists

The repo has three cspell custom word lists (.cspell/backend_custom_words.txt, .cspell/frontend_custom_words.txt, .cspell/project_words.txt) but no apparent GitHub Action to enforce spellcheck on PRs. This is valuable for a large cross-platform project with Rust + TypeScript + Swift codebases to catch typos early and keep documentation quality high.

• [ ] Create .github/workflows/spellcheck.yml that runs cspell --config .cspell/cspell.json on PR changes
• [ ] Add .cspell/cspell.json config file if missing (not in provided file list) to reference the three custom word lists
• [ ] Configure workflow to check only changed files in PR using actions/github-script or dorny/paths-filter
• [ ] Add spellcheck to .eslintignore and .prettierignore for non-code files to reduce noise

Add integration tests for GitHub publish-artifacts action

The .github/actions/publish-artifacts/ is a custom Node.js action that manages artifact uploads (critical for the release.yml workflow), but there are no unit or integration tests. Adding tests would ensure artifact handling, glob patterns, and error cases are covered before releases.

• [ ] Create .github/actions/publish-artifacts/__tests__/artifacts.test.ts using Jest
• [ ] Add jest.config.js and update package.json with test script and Jest dependencies
• [ ] Write tests covering: glob pattern matching (mock @actions/glob), artifact upload scenarios, and error handling from @actions/artifact
• [ ] Add --coverage threshold to catch untested paths in the action's index.ts
• [ ] Run tests in .github/workflows/ci.yml as a lint/typecheck step before dist/ is generated

• Add missing unit tests for cloud volume implementations (S3, Google Drive, Dropbox) in src/volumes/ or equivalent—these are first-class features but likely need edge-case coverage for auth, retry, and offline handling
• Extend .cspell/backend_custom_words.txt and .cspell/frontend_custom_words.txt with distributed-systems terminology currently missing (e.g., QUIC, DHT, merkle-tree variants)—prevents false CI failures and improves contributor experience
• Document the action-system architecture from .tasks/core/ACT-000-action-system.md and ACT-001-action-manager-registry.md in code comments and README—critical for AI-agent integration but lacks inline guidance for new contributors

The Spacedrive project demonstrates a reasonable security posture with a well-documented vulnerability reporting process via SECURITY.md. The analyzed GitHub Actions package.json file has minimal direct security risks, though dependency management could be strengthened. The primary concerns are: (1) regular dependency updates for @types/node and other dev dependencies, (2) establishment of automated security scanning for dependency vulnerabilities, and (3) ensuring email infrastructure security for the reported vulnerability contact. The use of lock files (bun.lock) and proper configuration files is positive. No hardcoded secrets, SQL injection vectors, or critical misconfigurations were identified in the provided file structure. The presence of multiple security files and configuration tools (.cspell, .clippy.toml, .rustfmt.toml) indicates attention to code quality and security best practices.

• Medium · Outdated @types/node Dependency — .github/actions/publish-artifacts/package.json. The @types/node dependency is pinned to ^25.0.0, which may include versions with known vulnerabilities. Node type definitions should be kept current with the runtime Node.js version used in the project. Fix: Regularly update @types/node to the latest stable version compatible with the Node.js runtime. Consider using a lock file (bun.lock is present) to ensure consistent versions across installations.
• Low · TypeScript Version Pinning — .github/actions/publish-artifacts/package.json. TypeScript is pinned to ^5.9.3. While this provides some flexibility, security patches should be applied promptly when released. Fix: Implement automated dependency scanning and updates for TypeScript and all dev dependencies. Consider using tools like Dependabot to track security updates.
• Low · Minified Build Output Obfuscation — .github/actions/publish-artifacts/package.json (build script). The build script uses --minify flag with ncc, which minifies the output. While this improves performance, it can complicate security auditing and debugging of the built artifact. Fix: Consider maintaining source maps for production builds to enable security analysis. Ensure the dist/index.js output is reviewed during security audits.
• Low · Missing SECURITY.md Contact Verification — SECURITY.md. The SECURITY.md file references security@spacedrive.com for vulnerability reports, but there is no visible verification mechanism (SPF, DKIM, DMARC records documented) to prevent email spoofing. Fix: Document email security policies and ensure the security contact email domain has proper DNS records configured (SPF, DKIM, DMARC). Consider using a dedicated bug bounty platform as an additional reporting channel.
• Low · PGP Key Management — SECURITY.md. The PGP key is embedded in SECURITY.md as plain text. While this is a common practice for public keys, ensure this key is properly validated and has an expiration date set. Fix: Verify the PGP key has an appropriate expiration date and is listed on public key servers. Consider establishing a key rotation policy. Document the key fingerprint for user verification.

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.