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/triwinds/ns-emu-tools 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 2d ago
• 2 active contributors
• AGPL-3.0 licensed
• CI configured
• Tests present
• ⚠ Small team — 2 contributors active in recent commits
• ⚠ Concentrated ownership — top contributor handles 79% of recent commits
• ⚠ AGPL-3.0 is copyleft — check downstream compatibility

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

What it runs against: a local clone of triwinds/ns-emu-tools — 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 triwinds/ns-emu-tools | Confirms the artifact applies here, not a fork | | 2 | License is still AGPL-3.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 ≤ 32 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(AGPL-3\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"AGPL-3\\.0\"" package.json 2>/dev/null) \\
  && ok "license is AGPL-3.0" \\
  || miss "license drift — was AGPL-3.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 "src-tauri/Cargo.toml" \\
  && ok "src-tauri/Cargo.toml" \\
  || miss "missing critical file: src-tauri/Cargo.toml"
test -f "frontend/src/main.ts" \\
  && ok "frontend/src/main.ts" \\
  || miss "missing critical file: frontend/src/main.ts"
test -f "frontend/src/router/index.ts" \\
  && ok "frontend/src/router/index.ts" \\
  || miss "missing critical file: frontend/src/router/index.ts"
test -f "frontend/src/stores/app.ts" \\
  && ok "frontend/src/stores/app.ts" \\
  || miss "missing critical file: frontend/src/stores/app.ts"
test -f "frontend/src/utils/tauri.ts" \\
  && ok "frontend/src/utils/tauri.ts" \\
  || miss "missing critical file: frontend/src/utils/tauri.ts"

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

ns-emu-tools is a desktop application built with Rust + Tauri 2 that automates installation, version detection, and updates for Nintendo Switch emulators (Ryujinx, Eden) and related components like firmware and keys. It provides a Vue 3 + Vuetify UI frontend that manages multiple emulator versions, downloads via aria2's multi-threaded engine, and handles MSVC runtime dependencies automatically. Monorepo structure: src-tauri/ contains the Rust backend using Tauri 2 framework, frontend/ holds Vue 3 + Vite SPA code, web/ is the compiled frontend output. Frontend uses Vuetify 3 for UI components, Tauri plugins for file/dialog/process/shell operations, and pinia for state management. Rust backend handles emulator discovery, download coordination, and system integration.

Nintendo Switch emulator enthusiasts and power users who need to manage multiple emulator versions, update firmware, organize encryption keys, and manage cheats without manual downloading and file management. Also useful for emulator developers tracking stable and canary releases.

Actively developed with 747KB of Rust code and significant Vue/TypeScript frontend (~127KB combined). Project shows CI/CD pipelines (ci-build.yaml, codeql.yml), automated workflows for game data updates, and GitHub release infrastructure. Recent activity visible through multiple workflow files and structured changelog. Production-ready for end-users, though single-maintainer risk exists.

Heavy dependency on external emulator repositories (Ryujinx, Eden official repos) and firmware sources (THZoria/NX_Firmware, darthsternie.net) creates upstream breakage risk if those sources change URLs or APIs. Tauri + Rust stack is mature but requires native compilation per platform. License is AGPL-3.0 (copyleft), which may restrict some use cases. No visible test suite in file structure despite complexity.

Project is actively maintaining support for Ryujinx (dropping Yuzu since it ceased development) and Eden emulator. Automated workflows include game data updates (update-game-data.yml), GitHub mirror syncing (update-github-mirrors.yml), and continuous builds (ci-build.yaml). Recent architecture shows shift away from Yuzu toward modern emulators.

git clone https://github.com/triwinds/ns-emu-tools.git
cd ns-emu-tools/frontend
bun install
cd ../src-tauri
cargo tauri dev

This launches the dev server with hot reload on the frontend (Vite) and Rust backend (Tauri). For production build: cargo tauri build from src-tauri/.

Daily commands: Dev mode: cd frontend && bun install && cd ../src-tauri && cargo tauri dev (opens desktop window with HMR). Production build: cd frontend && bun run build && cd ../src-tauri && cargo tauri build (creates executable in src-tauri/target/release/). See build_all.sh / build_all.bat for cross-platform CI scripts.

• src-tauri/Cargo.toml — Rust backend dependencies and workspace configuration; defines all tauri, emulator, and system library integrations for desktop application
• frontend/src/main.ts — Vue 3 application entry point; initializes Tauri IPC bridge, router, stores, and plugin system
• frontend/src/router/index.ts — Frontend routing configuration; defines all page navigation including emulator management, firmware, keys, and cheats
• frontend/src/stores/app.ts — Global application state management; coordinates emulator version detection, download progress, and UI state
• frontend/src/utils/tauri.ts — Tauri IPC bridge wrapper; all communication between Vue frontend and Rust backend flows through here
• frontend/vite.config.mts — Build configuration for frontend; configures Tauri integration, Vue plugins, and production bundling
• src-tauri/src/main.rs — Rust backend entry point; initializes Tauri window, registers commands for emulator installation, firmware management, and file operations

Add a new emulator management page

1. Create new Vue page component in frontend/src/pages/ (frontend/src/pages/[emulator].vue)
2. Add page route to router configuration (frontend/src/router/index.ts)
3. Create corresponding Pinia store for state management (frontend/src/stores/[EmulatorName]Store.ts)
4. Add menu item to navigation drawer (frontend/src/layouts/AppDrawer.vue)
5. Register new Tauri command handlers in Rust backend (src-tauri/src/main.rs)
6. Call backend commands via tauri utility wrapper (frontend/src/utils/tauri.ts)

Add firmware or key management feature

1. Create new dialog/modal Vue component for the feature (frontend/src/components/[Feature]Dialog.vue)
2. Add state store to track dialog open state and data (frontend/src/stores/app.ts)
3. Implement Tauri command in Rust for file I/O operations (src-tauri/src/main.rs)
4. Wire up dialog in relevant page and invoke backend commands (frontend/src/pages/[related-page].vue)

Add a new download source or mirror

1. Update mirror configuration file with new source (github_mirrors.json)
2. Add fallback logic in configuration store (frontend/src/stores/ConfigStore.ts)
3. Extend Rust backend downloader to support new URL pattern (src-tauri/src/main.rs)
4. Test via ProgressDialog tracking and version detection (frontend/src/components/ProgressDialog.vue)

Extend the UI with new keyboard shortcuts or commands

1. Register global keyboard event handler in app layout (frontend/src/layouts/default.vue)
2. Dispatch store actions or emit events via mitt event bus (frontend/src/plugins/mitt.ts)
3. Handle event in target component and invoke tauri command (frontend/src/utils/tauri.ts)

• Rust + Tauri 2 — Cross-platform desktop application with native system access (file I/O, process execution, aria2 integration) while sharing code across Windows/macOS/Linux
• Vue 3 + Vite + Vuetify — Reactive UI framework with Material Design components; Vite provides fast HMR during development; Vuetify offers polished dialogs and modals for download progress
• Pinia (state management) — Lightweight store solution integrated with Vue 3; enables reactive progress tracking, configuration persistence, and multi-task async state
• aria2 downloader — Multi-threaded download library; handles large emulator binaries and firmware files with resume capability and mirror fallback
• Marked + isomorphic-dompurify — Render changelogs and documentation safely as HTML from markdown; prevent XSS via dompurify sanitization

• Tauri 2 IPC for all backend calls instead of local Rust library

  • Why: Security boundary and sandboxing; prevents frontend from directly accessing filesystem or process APIs
  • Consequence: Slight latency on every backend call (~5–10ms), but enforces clean separation of concerns and enables future web-view security upgrades

• Static game_data.json and github_mirrors.json checked into repo

  • Why: Avoids runtime HTTP calls for metadata; fast startup and works offline
  • Consequence: Requires manual updates via CI workflow; cannot react to mirror changes in real-time without app rebuild

• ---

  • Why: undefined
  • Consequence: undefined

Build requirement: Must have bun (not npm/yarn) installed for frontend; cargo + Rust toolchain for backend. Tauri WebView2 dependency: Windows users need WebView2 Runtime (app prompts if missing, but adds installation friction). AGPL-3.0 license: Any modifications/distributions must open-source derivative work. External repo brittleness: Emulator release URLs/API formats in Ryujinx/Eden repos can break scraping logic silently. Firmware source redundancy: Multiple firmware sources (THZoria, darthsternie.net) suggest fragility; no fallback strategy visible. No hot-reload for Rust: Backend changes require full cargo tauri dev restart unlike frontend Vite HMR.

• Tauri 2 IPC (Inter-Process Communication) — Core mechanism connecting Vue frontend to Rust backend via async command handlers; essential for understanding how UI triggers downloads/system operations
• Web scraping & Release feed parsing — Tool extracts emulator versions from GitHub releases and external repos without official APIs; understanding regex/HTML parsing resilience matters for maintenance
• Async/await in Rust with Tokio — Tauri backend uses async Rust for parallel downloads and system operations; critical for understanding download coordinator and file operations
• Multi-threaded downloads with aria2 — Tool delegates to aria2 for parallel chunk downloads; understanding aria2 IPC protocol and progress parsing is needed to enhance ProgressDialog.vue
• Vue 3 Composition API + Pinia state management — Frontend reactive patterns for UI state (download progress, emulator list, version cache); understanding Pinia stores is essential for frontend modifications
• Tauri plugin architecture (fs, shell, process) — Abstracts OS-level file/shell/process operations with permission-based security model; needed to add new system integration features
• Markdown rendering security (isomorphic-dompurify) — Changelog/content display uses marked.js + dompurify to safely render user/external markdown without XSS; matters for any user-generated content features

• yuzu-emu/yuzu — Original Nintendo Switch emulator this tool was designed for (now deprecated per changelog); understanding its structure explains legacy code patterns
• ryujinx/Ryujinx — Primary maintained emulator target; this tool automates its installation/updates by scraping its release feeds
• nicoboss/nsz — NS firmware/content parsing library used by ns-emu-tools for firmware format handling and validation
• aria2/aria2 — Multi-threaded download engine that ns-emu-tools integrates for parallel firmware/emulator downloads
• tauri-apps/tauri — Underlying framework for the desktop app; understanding Tauri 2 plugin APIs (fs, shell, dialog, process) is essential for backend modifications

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 E2E tests for Tauri desktop app using Playwright/WebdriverIO

The repo has CI workflows for building (.github/workflows/ci-build.yaml) but no automated E2E testing for the Tauri desktop application. Given the complexity of emulator installation/updates across Windows/macOS/Linux, E2E tests would catch regressions in critical paths like emulator download, extraction, and version detection. This is especially important since the project manages multiple emulator versions (Ryujinx, Eden) and firmware installation.

• [ ] Set up Playwright or WebdriverIO with Tauri testing library in .github/workflows/
• [ ] Create test scenarios in a new tests/e2e/ directory for: emulator installation flow, version detection, firmware updates
• [ ] Add E2E workflow trigger to ci-build.yaml or create separate e2e-test.yml that runs on PR
• [ ] Reference Tauri's official testing guide for desktop app configuration

Add unit tests for frontend Tauri API integration (src/components/ and src/pages/)

The frontend extensively uses @tauri-apps/api plugins (shell, fs, dialog, process) across multiple Vue components (YuzuSaveRestoreTab.vue, ProgressDialog.vue, etc.) but has no visible unit test suite. This is critical for preventing regressions when updating Tauri dependencies. Tests should mock Tauri API calls to validate component behavior during installation, save restoration, and file operations.

• [ ] Set up Vitest in frontend/package.json with @vue/test-utils for component testing
• [ ] Create frontend/tests/components/ directory with tests for YuzuSaveRestoreTab.vue and ProgressDialog.vue mocking tauri API calls
• [ ] Add test utilities in frontend/tests/utils/ to mock @tauri-apps/api/shell and @tauri-apps/api/fs
• [ ] Add npm script 'test' to frontend/package.json and integrate into ci-build.yaml

Document emulator configuration and CLI argument mapping in docs/emulator-setup.md

The repo lacks specific documentation on how each emulator (Ryujinx, Eden) is installed, configured, and what CLI arguments or environment variables are set post-installation. Since the tool automates 'installation/updates of NS emulator' with Rust backend code (src-tauri), downstream users and contributors need clear docs mapping Rust install logic to actual emulator configs. This prevents duplicate work and clarifies the relationship between tool updates and emulator compatibility.

• [ ] Create docs/emulator-setup.md documenting Ryujinx/Canary/Eden installation paths, config file locations, and any post-install setup
• [ ] Add a table in docs/ mapping each emulator to: supported OS, version detection method, download source, firmware install location
• [ ] Document the firmware installation process and compatibility matrix across emulator versions
• [ ] Reference this new doc from README.md's Features section and from CLAUDE.md for contributor onboarding

• Add automated tests for firmware version detection logic (src-tauri/src/ likely lacks unit tests for version parsing); critical for reliability since this feature has been upgraded per changelog.
• Document the firmware source switching logic and add UI feedback when sources fail; currently only THZoria and darthsternie.net are listed without explaining priority/fallback strategy to users.
• Improve error messages in download failures by capturing aria2 stderr and displaying root cause in frontend dialogs (ProgressDialog.vue currently shows progress but generic errors); would reduce support burden.

• High · Potential XSS Vulnerability via Markdown Rendering — frontend/src/components/MarkdownContentBox.vue, frontend/package.json (marked, isomorphic-dompurify). The codebase uses 'marked' (v15.0.7) for markdown parsing and 'isomorphic-dompurify' (v2.22.0) for sanitization. However, the presence of MarkdownContentBox.vue component suggests user-generated or remote markdown content is being rendered. If dompurify is not properly configured or applied to all markdown outputs, XSS attacks via malicious markdown are possible. Fix: Ensure all markdown content is properly sanitized using dompurify with strict configuration. Verify that DOMPurify is applied to the output of marked() before rendering. Consider using marked's built-in sanitization or configure it to escape HTML by default.
• High · Insecure Download and File Operations — frontend/package.json (@tauri-apps/plugin-fs, @tauri-apps/plugin-shell), Rust backend (src-tauri). The application downloads emulator binaries and firmware updates. The Tauri plugins (@tauri-apps/plugin-fs, @tauri-apps/plugin-shell) are used for file operations and shell execution. Without visible integrity verification (no hash checking in file structure), downloaded files could be subject to MITM attacks or supply chain compromises. Fix: Implement cryptographic verification for all downloaded files using SHA-256 or stronger hashes. Verify digital signatures of downloads. Use HTTPS for all remote connections and implement certificate pinning for critical domains.
• High · Unvalidated Shell Command Execution — frontend/package.json (@tauri-apps/plugin-shell), Rust backend (src-tauri). The @tauri-apps/plugin-shell dependency indicates the application executes shell commands. Combined with user inputs (file paths, emulator parameters), this creates a command injection risk if inputs are not properly validated and escaped. Fix: Never pass user input directly to shell commands. Use safe APIs that don't invoke a shell (e.g., spawn with args array). Implement strict input validation and use allowlists for accepted values. Avoid shell=true in any child process spawning.
• Medium · Outdated or Vulnerable Transitive Dependencies — frontend/package.json, frontend/bun.lock. Multiple dependencies with numerous transitive dependencies are included. The lock file (bun.lock) is present but git-tracked package versions suggest potential for dependency vulnerabilities. No evidence of dependency scanning (e.g., npm audit, snyk) in CI/CD workflows visible. Fix: Implement automated dependency vulnerability scanning in CI/CD (GitHub security features, Dependabot, Snyk). Regularly audit dependencies with 'npm audit' and 'bun audit'. Use lockfiles consistently and update dependencies periodically.
• Medium · Sensitive Environment Variables in Repository — frontend/.env.development, frontend/.env.production. The presence of .env.development and .env.production files in the frontend directory suggests environment configuration is tracked. If these contain any sensitive data (API keys, tokens), they could be exposed in version control history. Fix: Add .env files to .gitignore (except .env.example with dummy values). Store sensitive configuration in secure secret management systems. Use GitHub Secrets for CI/CD workflows. Never commit actual credentials or tokens.
• Medium · Potential Information Disclosure via Error Messages — frontend/src/components/ConsoleDialog.vue, frontend/src/components/ProgressDialog.vue. Components like ConsoleDialog.vue and ProgressDialog.vue may expose detailed error messages to users. If the Rust backend or file system errors are displayed verbatim, this could reveal system paths, software versions, or other sensitive information. Fix: Implement user-friendly error messages that hide technical details. Log detailed errors server-side only. Sanitize and generalize error messages shown to end users.
• Medium · Unsafe Vue Template Rendering — frontend/src/components/MarkdownContentBox.vue, frontend/src/components/YuzuSaveRestoreTab.vue. The use of marked + dompurify for markdown combined with Vue's template rendering suggests potential for template injection if user content is rendered in Vue templates rather than as DOM content. Fix: Use v-html with properly sanitized content only

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.