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/hbons/SparkleShare 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 2mo ago
• 13 active contributors
• Other licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 65% of recent commits
• ⚠ Non-standard license (Other) — review terms

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

What it runs against: a local clone of hbons/SparkleShare — 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 hbons/SparkleShare | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 96 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "hbons/SparkleShare(\\.git)?\\b" \\
  && ok "origin remote is hbons/SparkleShare" \\
  || miss "origin remote is not hbons/SparkleShare (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "SparkleShare/Common/SparkleShare.cs" \\
  && ok "SparkleShare/Common/SparkleShare.cs" \\
  || miss "missing critical file: SparkleShare/Common/SparkleShare.cs"
test -f "SparkleShare/Common/SetupController.cs" \\
  && ok "SparkleShare/Common/SetupController.cs" \\
  || miss "missing critical file: SparkleShare/Common/SetupController.cs"
test -f "SparkleShare/Common/BaseController.cs" \\
  && ok "SparkleShare/Common/BaseController.cs" \\
  || miss "missing critical file: SparkleShare/Common/BaseController.cs"
test -f "SparkleShare/Common/Presets/bitbucket.xml" \\
  && ok "SparkleShare/Common/Presets/bitbucket.xml" \\
  || miss "missing critical file: SparkleShare/Common/Presets/bitbucket.xml"
test -f "SparkleShare/Linux/Controller.cs" \\
  && ok "SparkleShare/Linux/Controller.cs" \\
  || miss "missing critical file: SparkleShare/Linux/Controller.cs"

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

SparkleShare is a desktop file synchronization and collaboration tool that syncs folders with any Git repository (backed by Git LFS for large files), functioning as a self-hosted Dropbox alternative. It maintains automatic bidirectional sync across Linux, macOS, and Windows by leveraging Git as the underlying version control system, enabling users to run their own file-sharing servers without relying on centralized cloud services. Monolithic C# application structured as SparkleShare/Common/ containing cross-platform controllers (AboutController.cs, EventLogController.cs, BubblesController.cs, NoteController.cs) and shared assets (HTML templates in Common/HTML/, SVG sources in Common/Images/Sources/, platform-specific presets in Common/Presets). The project uses Meson as build system and is compiled as a single .NET solution (SparkleShare.sln).

Teams and individuals who need private, self-hosted file synchronization and want to avoid proprietary cloud storage services. Specifically: system administrators setting up collaborative workspaces, open-source projects coordinating across contributors, and organizations prioritizing data privacy and control over their infrastructure.

Production-ready but in maintenance mode. The project is several years old with a stable release history (visible in RELEASE_NOTES.txt), has CI configured (.travis.yml), and supports three major platforms. However, the maintainer recently posted issue #2006 signaling uncertainty about the project's future direction, and development pace appears to have slowed significantly.

Moderate risk: single maintainer (hbons) creates sustainability concerns, and the recent public statement about layoffs raises questions about long-term support. The C# codebase (586KB) depends on .NET ecosystem stability. No clear test suite visible in the file structure, and the last commit date is not evident, making it difficult to assess active maintenance status.

The project is in a transitional period. Issue #2006 signals the maintainer is seeking direction and community input on the project's future. No active feature development is evident from the file structure; recent activity likely focuses on maintenance and potential platform compatibility updates. The maintainer is seeking GitHub sponsors to work full-time on Linux apps and FOSS design contributions.

Check README for instructions.

Daily commands: Build: meson setup builddir && meson compile -C builddir. Run the compiled binary (platform-specific output location depends on Meson configuration). For development iteration: modify .cs files in SparkleShare/Common/, rebuild with Meson, and test the UI controllers against the HTML templates in Common/HTML/.

• SparkleShare/Common/SparkleShare.cs — Main application entry point and orchestration logic for the SparkleShare sync engine
• SparkleShare/Common/SetupController.cs — Handles repository setup and configuration workflow; critical for onboarding and initialization
• SparkleShare/Common/BaseController.cs — Base controller class providing common patterns for all UI controllers across platforms
• SparkleShare/Common/Presets/bitbucket.xml — Provider preset configuration template; defines how to integrate with external Git hosting services
• SparkleShare/Linux/Controller.cs — Linux-specific platform controller bridging common logic to GTK UI and system integration
• SparkleShare.sln — Visual Studio solution file; defines project structure and cross-platform build configuration
• SparkleShare/Common/Translations/POTFILES.in — Translation source file list; ensures i18n coverage across the entire codebase

Add Support for a New Git Hosting Provider

1. Create a new provider preset XML file in SparkleShare/Common/Presets/ following the pattern of github.xml or gitlab.xml, defining the provider name, URL patterns, and authentication method (SparkleShare/Common/Presets/newprovider.xml)
2. Add PNG icons (regular and @2x retina versions) for the provider in the same Presets folder (SparkleShare/Common/Presets/newprovider.png)
3. Register the new preset in the setup flow by adding it to the provider list in SetupController.cs if additional logic is needed (SparkleShare/Common/SetupController.cs)
4. Update meson.build or build configuration to include the new preset files in packaging (SparkleShare/Common/Presets/meson.build)

Add a New Platform-Specific UI Window (e.g., macOS version of EventLog)

1. Create a new class inheriting from the common controller in SparkleShare/Common/, e.g., EventLogController.cs, implementing platform-agnostic logic and events (SparkleShare/Common/EventLogController.cs)
2. Create a platform-specific implementation in SparkleShare/Linux/ (or /Mac, /Windows) that inherits from or uses the common controller and implements platform UI (GTK for Linux, Cocoa for macOS, WPF for Windows) (SparkleShare/Linux/EventLog.cs)
3. Register the new window in the platform-specific Controller class (e.g., SparkleShare/Linux/Controller.cs) to instantiate and show it (SparkleShare/Linux/Controller.cs)
4. Add any platform-specific UI resources (HTML templates, CSS, icons) to SparkleShare/Common/HTML/ or SparkleShare/Common/Images/Sources/ (SparkleShare/Common/HTML/event-log.html)

Add a New UI String with Full Translation Support

1. Add the string literal to any .cs file in SparkleShare/Common/ or platform-specific folders using standard C# gettext markup (e.g., Catalog.GetString("My new string")) (SparkleShare/Common/SetupController.cs)
2. Run the translation extraction tool to update SparkleShare/Common/Translations/POTFILES.in and create/update .po files (SparkleShare/Common/Translations/POTFILES.in)
3. Verify the string appears in LINGUAS and all language .po files (de.po, fr.po, etc.) (SparkleShare/Common/Translations/LINGUAS)
4. Translators can then edit the .po files to provide translations for the new string (SparkleShare/Common/Translations/de.po)

• C# / .NET — Cross-platform runtime allowing shared code via SparkleShare.shproj while building native UIs on each platform
• GTK (Linux), Cocoa/AppKit (macOS), WPF (Windows) — Native platform-specific UI frameworks providing native look-and-feel and system integration (tray icons, notifications, file dialogs)
• Git CLI/libgit2 — Underlies all repository operations (clone, pull, push, merge) without reinventing version control
• XML Provider Presets — Declarative configuration allowing new Git hosts (GitHub, GitLab, Bitbucket, self-hosted) to be added without code changes
• HTML/JavaScript Event Log — Rich, interactive display of commit history without replicating complex rendering logic per platform

• Platform-specific UI layer (GTK/Cocoa/WPF) vs. cross-platform UI framework (Electron/Qt)

  • Why: Native UI provides better system integration, lower memory footprint, and native feel on each platform; trade-off is code duplication per platform
  • Consequence: Must maintain separate UI implementations for Linux/macOS/Windows; shared controllers minimize duplication but UI remains platform-specific

• File watcher + Git polling architecture vs. push-based webhooks only

  • Why: File watchers catch local changes immediately; polling provides fallback for unreliable network without requiring server-side setup
  • Consequence: Higher CPU/I/O on local machine; some latency before remote changes appear (polling interval dependent)

• Declarative XML provider presets vs. programmatic provider plugins

  • Why: XML presets are simple, don't require code recompilation, and are user-editable; trade-off is less flexibility
  • Consequence: undefined

No comprehensive test suite visible in file structure—contributions may lack automated validation. Meson build system is non-standard for C# projects; requires Meson knowledge beyond typical .NET workflows. Git/Git LFS must be installed and configured on the system for SparkleShare to function (not packaged). Platform-specific code paths for GTK+/AppIndicator (Linux), Cocoa (macOS), and native Windows UI require testing on each platform. HTML event log uses jQuery (jquery.js) and custom HTML templates—changes to event rendering require understanding both C# serialization and client-side template binding.

• Git as a sync backend — SparkleShare's core innovation is using Git's distributed model for file sync rather than custom protocols; understanding Git commits, merges, and conflict resolution is essential to contributing to sync logic
• Git LFS (Large File Storage) — SparkleShare uses Git LFS to handle binary files and large assets without bloating the Git repository; you must understand LFS pointers and the two-stage storage model to modify how large files are synced
• MVC pattern in desktop apps — SparkleShare uses BaseController as the base class for all UI controllers (AboutController, EventLogController); understanding this pattern is critical for adding new UI features or modifying sync behaviors
• Cross-platform GUI frameworks (GTK+, Cocoa, WinForms) — SparkleShare runs on Linux, macOS, and Windows with native UI bindings; contributing platform-specific features requires knowing which framework handles which OS (Presets/ directory enforces this split)
• AppIndicator / System tray integration — SparkleShare lives in the system tray as an AppIndicator on Linux; understanding how native status icons work per-platform is necessary for UI and notification changes
• Meson build system — SparkleShare uses Meson (not Visual Studio or dotnet CLI) for building; contributors must understand meson.build configuration files and the Meson workflow to compile and test locally
• Bi-directional sync algorithms — SparkleShare must detect file conflicts, merges, and deletions across peers in real-time; understanding how Git diffs and merge strategies apply to live file sync is fundamental to sync engine modifications

• syncthing/syncthing — Alternative self-hosted file sync tool using different architecture (Go, distributed), solves same sync problem but without Git backend
• restic/restic — Backup and sync tool using Git-like concepts but focused on versioning; users choosing between sync vs. backup often evaluate both
• hbons/Dazzle — Official companion project—simple script for setting up SparkleShare hosting servers, referenced in README as the recommended host setup tool
• gitpython/GitPython — Python Git library that SparkleShare-like tools often use for Git operations; relevant for understanding how SparkleShare wraps Git under the hood
• git-lfs/git-lfs — Official Git Large File Storage extension that SparkleShare depends on for handling binary and large files in sync operations

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 unit tests for SparkleShare/Common controllers (AboutController.cs, SetupController.cs, EventLogController.cs)

The repo has multiple controller classes in SparkleShare/Common/ but there's no visible test directory structure. These controllers handle critical user-facing logic (setup flow, event logging, status icons). Adding unit tests would improve code reliability and make the codebase more maintainable for future contributors. This is especially important given the project's transition phase mentioned in issue #2006.

• [ ] Create a Tests/ directory structure mirroring SparkleShare/Common/
• [ ] Add unit test project file (Tests/SparkleShare.Tests.csproj) to SparkleShare.sln
• [ ] Write tests for SetupController.cs covering repository initialization flows
• [ ] Write tests for EventLogController.cs covering event entry parsing and filtering
• [ ] Write tests for StatusIconController.cs covering status state transitions
• [ ] Document test setup in CONTRIBUTING.md with instructions for running tests

Create GitHub Actions workflow for cross-platform builds (Linux, macOS, Windows)

The repo currently uses .travis.yml (Travis CI), which is outdated. GitHub Actions is the modern standard and would enable native multi-platform testing for a project that explicitly supports Linux, macOS, and Windows. This PR would replace the legacy CI config with a native GitHub Actions workflow that builds and tests on all three platforms, reducing maintenance burden and improving visibility.

• [ ] Create .github/workflows/build.yml with matrix strategy for ubuntu-latest, macos-latest, windows-latest
• [ ] Add build steps for restoring NuGet dependencies and compiling SparkleShare.sln
• [ ] Add steps to run any existing tests (from PR #1 above or current test suite)
• [ ] Configure artifact upload for successful builds
• [ ] Add status badges to README.md showing build status for all platforms
• [ ] Document CI process in CONTRIBUTING.md

Add preset configuration documentation and validation for SparkleShare/Common/Presets/ XML files

The repo includes preset XML files for GitHub, GitLab, Bitbucket, and own-server configurations, along with a parse_plugins.xsl stylesheet. However, there's no documented schema or validation process. New contributors cannot easily understand the preset format or add new providers. This PR would create clear documentation and add validation tooling.

• [ ] Document the preset XML schema in a new file: SparkleShare/Common/Presets/README.md (covering required/optional fields: address, path-regex, etc.)
• [ ] Create a sample preset template showing all available configuration options
• [ ] Add unit tests in Tests/ to validate existing preset files against the schema
• [ ] Create a validation script/tool (e.g., in C#) to check new presets during CI/development
• [ ] Update CONTRIBUTING.md with instructions for contributors wanting to add new hosting provider presets
• [ ] Document the purpose of parse_plugins.xsl and how it's used in the build process

• Add unit test coverage for Avatars.cs (avatar caching and rendering logic)—currently no test files visible and this is a critical user-facing feature affecting the event log display
• Document the meson.build system and add architecture.md explaining how the cross-platform controller pattern works—new contributors unfamiliar with C# MVC or Meson struggle to onboard
• Extract and document the protocol handler for sparkleshare:// URLs (referenced in protocol-handler-test/invite.xml)—the test exists but implementation and docs appear incomplete

• High · Potential XSS Vulnerability in HTML Templates — SparkleShare/Common/HTML/. The presence of HTML template files (day-entry.html, event-entry.html, event-log.html) combined with jQuery suggests dynamic content rendering. Without reviewing the actual code, there's a risk of Cross-Site Scripting (XSS) if user-generated content (file names, commit messages, user names) is inserted into the DOM without proper sanitization or escaping. Fix: Ensure all user-generated content is properly HTML-escaped before rendering in templates. Use templating engines with automatic escaping enabled. Implement Content Security Policy (CSP) headers to mitigate XSS impact.
• High · Outdated jQuery Library — SparkleShare/Common/HTML/jquery.js. The file structure includes jquery.js, which is likely an older version given the project's maturity. jQuery versions before 3.6.0 contain known XSS and prototype pollution vulnerabilities that could be exploited through malicious repositories or crafted files. Fix: Update jQuery to the latest stable version (3.6.0+). Consider migrating away from jQuery to modern vanilla JavaScript or a more modern library with better security practices.
• High · Git Repository Synchronization Risk — SparkleShare/Common/. As a Git-based file syncing application, SparkleShare is inherently vulnerable to attacks through malicious Git repositories. Arbitrary code execution, path traversal, or symbolic link attacks could occur if user input is not properly validated when cloning/syncing repositories. Fix: Implement strict validation of Git URLs before cloning. Use signed commits and verify repository signatures. Implement sandboxing for file operations. Configure Git safely (e.g., core.symlinks=false, core.protectNTFS=true).
• Medium · Missing Dependency Version Pinning — Project root. No package dependency file (package.json, requirements.txt, .csproj details) was provided for analysis. This makes it impossible to verify if all dependencies are up-to-date and free from known vulnerabilities. Fix: Implement a dependency management strategy with pinned versions. Use automated tools like Dependabot or Renovate to track and update dependencies. Regularly audit dependencies using tools like npm audit, OWASP Dependency-Check, or Snyk.
• Medium · Potential XML External Entity (XXE) Injection — SparkleShare/Common/Presets/. The presence of XML preset files (bitbucket.xml, github.xml, gitlab.xml, own-server.xml) and XSLT processing (parse_plugins.xsl) suggests XML parsing. If XML parsing is not properly configured, XXE attacks could allow file disclosure or SSRF attacks. Fix: Disable XML external entity processing in all XML parsers. Use safe XML parsing libraries with XXE protection enabled by default. Validate and sanitize all XML input before processing.
• Medium · Hardcoded Configuration in Preset Files — SparkleShare/Common/Presets/*.xml. Preset XML files contain hosting provider configurations. If these include API endpoints or authentication details that could be leveraged for attacks, or if user repositories can override these settings, it poses a security risk. Fix: Ensure preset files are read-only and obtained from trusted sources. Implement certificate pinning for API endpoints. Never store credentials in configuration files; use secure credential storage mechanisms.
• Medium · Protocol Handler Implementation Risk — SparkleShare/Common/HTML/protocol-handler-test/. The sparkleshare:// protocol handler test file (protocol-handler-test.htm) indicates custom URI scheme handling. Custom protocol handlers are vulnerable to privilege escalation and arbitrary code execution if not properly validated. Fix: Implement strict URL validation for protocol handler invocations. Whitelist allowed operations. Require user confirmation before executing protocol handler actions. Implement proper error handling to prevent information disclosure.
• Low · Missing Security Headers Configuration — SparkleShare/Common/HTML/. No evidence of security header configuration (CSP, X-Frame-Options, X-Content-Type-Options, etc.) in the file structure for HTML resources served by the application. Fix: Implement security headers in the HTTP response. Set CSP to

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.