Onboarding: mayswind/AriaNg

Generated by RepoPilot · 2026-05-06 · Source

Agent protocol

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/mayswind/AriaNg 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.

Verdict

WAIT — Mixed signals — read the receipts

• Last commit 3mo ago
• 10 active contributors
• MIT licensed
• ⚠ Concentrated ownership — top contributor handles 77% of recent commits
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

Verify before trusting

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

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

<details> <summary><b>Run all checks</b> — paste this script from inside your clone of <code>mayswind/AriaNg</code></summary>

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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 "src/core/app.js" \\
  && ok "src/core/app.js" \\
  || miss "missing critical file: src/core/app.js"
test -f "src/scripts/services/aria2RpcService.js" \\
  && ok "src/scripts/services/aria2RpcService.js" \\
  || miss "missing critical file: src/scripts/services/aria2RpcService.js"
test -f "src/scripts/config/configuration.js" \\
  && ok "src/scripts/config/configuration.js" \\
  || miss "missing critical file: src/scripts/config/configuration.js"
test -f "src/scripts/core/router.js" \\
  && ok "src/scripts/core/router.js" \\
  || miss "missing critical file: src/scripts/core/router.js"
test -f "src/scripts/services/ariaNgLocalizationService.js" \\
  && ok "src/scripts/services/ariaNgLocalizationService.js" \\
  || miss "missing critical file: src/scripts/services/ariaNgLocalizationService.js"

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

</details>

TL;DR

AriaNg is a modern web UI frontend for aria2, a lightweight command-line download manager. It provides a browser-based interface (pure HTML/JavaScript, no server runtime needed) that connects to aria2 via RPC protocol, allowing users to manage downloads, control tasks, and monitor transfer speeds from desktop or mobile devices. Key capabilities include task sorting/searching, BitTorrent peer inspection, speed charting via ECharts, and full aria2 settings control. Single-page AngularJS application. Entry point: src/index.html. Core modules: src/scripts/core/ (app.js, router.js, root.js handling AngularJS setup and routing). Controllers in src/scripts/controllers/ handle UI logic (list.js for task list, settings-aria2.js for aria2 config, etc.). Configuration and constants isolated in src/scripts/config/. Internationalization via src/langs/ text files (en, zh_Hans, ja_JP, etc.). Build output generated via Gulp into dist/.

Who it's for

End users who run aria2 as a download daemon and want a visual interface instead of CLI; systems administrators deploying download infrastructure who need a lightweight, responsive UI accessible from any browser without installing server-side dependencies.

Maturity & risk

Production-ready. The project shows active maintenance with CI/CD via CircleCI, a stable v1.x release cycle, and multi-language support across 10+ locales. Dependencies are pinned to specific versions (Angular 1.6.10, Bootstrap 3.4.1, AdminLTE 2.4.18), indicating conservative upgrade practices. However, it relies on AngularJS 1.x (EOL framework) which limits future modernization.

Moderate technical debt: AngularJS 1.6.10 is unmaintained since 2022, and the codebase has ~600k lines of JavaScript without visible test coverage in the file list. Single maintainer (mayswind) risk is present. Dependencies on old Bootstrap 3.4.1 and AdminLTE 2.4.18 mean security patches are limited. No visible test files (Jest, Jasmine, etc.) suggest manual QA only.

Active areas of work

No specific recent activity visible in provided data, but repo shows ongoing maintenance through CircleCI daily builds (scripts/publish_dailybuild.sh) and a dedicated DailyBuild branch. Project accepts language translations and bug fixes from community.

Get running

Check README for instructions.

Daily commands: Development: gulp serve (starts BrowserSync dev server on localhost:3000 with auto-reload). Production build: gulp build (outputs optimized files to dist/). See gulpfile.js for detailed task definitions.

Map of the codebase

• src/core/app.js — AngularJS application initialization and root module setup—every contributor must understand the app bootstrap sequence and dependency injection.
• src/scripts/services/aria2RpcService.js — Core RPC service abstraction that delegates to HTTP or WebSocket implementations—every feature that communicates with aria2 depends on this.
• src/scripts/config/configuration.js — Central configuration and settings management that persists user preferences and aria2 connection details across sessions.
• src/scripts/core/router.js — AngularJS route configuration and navigation logic that defines all major UI sections and state transitions.
• src/scripts/services/ariaNgLocalizationService.js — Language and translation system that bridges i18n files to the UI—critical for multi-language support.
• gulpfile.js — Build pipeline that compiles, bundles, and packages the application—must be understood for any release or deployment.
• src/index.html — Single-page application entry point and layout template that orchestrates all controllers, directives, and views.

How to make changes

Add a new task operation (e.g., force pause, remove all completed)

1. Define the RPC method signature in aria2RpcConstants.js (src/scripts/config/aria2RpcConstants.js)
2. Implement the high-level operation in aria2TaskService.js using aria2RpcService (src/scripts/services/aria2TaskService.js)
3. Add UI button and call the new operation in the appropriate controller (e.g., list.js or main.js) (src/scripts/controllers/list.js)
4. Add translation keys for the button label in en.sample.txt and other language files (i18n/en.sample.txt)

Add a new settings page tab

1. Create a new controller file for the settings page (e.g., settings-custom.js) (src/scripts/controllers/settings-custom.js)
2. Add a route entry in router.js pointing to the new controller and template (src/scripts/core/router.js)
3. Define settings keys and defaults in configuration.js (src/scripts/config/configuration.js)
4. Create the HTML template in src/views/ with form controls using settingDialog directive (src/scripts/directives/settingDialog.js)
5. Add translation keys for all labels and descriptions in language files (i18n/en.sample.txt)

Add a new filter or sort option for tasks

1. Create a new filter file in src/scripts/filters/ (e.g., customOrderBy.js) (src/scripts/filters/customOrderBy.js)
2. Register the filter in app.js using .filter() (src/scripts/core/app.js)
3. Update the task list template to expose the sort option in the UI (src/scripts/controllers/list.js)
4. Add translation keys for the sort label and tooltips in language files (i18n/en.sample.txt)

Add support for a new aria2 option or setting

1. Define the option schema in aria2Options.js with type, range, and description (src/scripts/config/aria2Options.js)
2. Add a new form field in the aria2 settings controller and template (src/scripts/controllers/settings-aria2.js)
3. Ensure the option is persisted through aria2SettingService.js (src/scripts/services/aria2SettingService.js)
4. Add translation key for the option label and help text in all language files (i18n/en.sample.txt)

Why these technologies

• AngularJS 1.6 — Lightweight MVC framework for single-page applications; easy two-way binding and dependency injection without build complexity.

Traps & gotchas

No obvious env vars required, but aria2 daemon must be running separately on network and configured to accept RPC requests (default: localhost:6800). Build requires Node ≥14 (see package.json engines). AngularJS 1.x templates use ng- directives which can conflict if you include other JS frameworks. LocalStorage used for settings persistence — clearing browser storage will reset AriaNg configuration. Gulp 4.x required (gulpfile.js uses async/await syntax); older Gulp 3.x will fail. No explicit test command in package.json — linting via ESLint (npm run lint) but no Jest/Mocha visible.

Architecture

Concepts to learn

• JSON-RPC 2.0 Protocol — AriaNg communicates with aria2 exclusively via JSON-RPC 2.0 (src/scripts/core/app.js); understanding request/response structure and error handling is essential for any RPC-related fixes
• AngularJS Dependency Injection — AriaNg uses Angular 1.x DI container extensively (controllers inject services, filters, etc.); you must understand $inject arrays and minification-safe patterns to add new features
• LocalStorage API — Settings and RPC host profiles persisted via browser localStorage (src/scripts/config/configuration.js); affects user experience across sessions and requires careful cache invalidation
• Gulp Task Automation — Build pipeline (gulpfile.js) orchestrates minification, source mapping, i18n template compilation, and asset fingerprinting; understanding task dependencies is needed to modify build output
• WebSocket Protocol (angular-websocket) — Real-time task updates from aria2 use WebSocket connections (ngWebSocket); dependency injection of websocket service is required for live status synchronization
• Responsive Design & Bootstrap Grid — Layout must work on desktop and mobile (mentioned as key feature); Bootstrap 3 grid system (col-xs, col-sm, col-md) is used throughout templates for responsive behavior
• i18n Pluralization & Message Format — Multi-language support via angular-translate and custom text files (src/langs/); understanding message key naming and plural rules is needed to add translations or language-specific formatting

Related repos

• aria2/aria2 — The underlying download daemon that AriaNg controls via JSON-RPC; essential companion project
• mayswind/AriaNg-Native — Official electron-based desktop version of AriaNg; uses same codebase but bundles with Chromium for standalone deployment
• mayswind/AriaNg-DailyBuild — Official nightly build branch; tracks latest master and provides precompiled artifacts for testing
• angular/angular.js — AngularJS 1.x framework source; dependency and reference for understanding controller/service patterns used
• ColorlibHQ/AdminLTE — AdminLTE UI template library; AriaNg uses v2.4.18 as the primary dashboard layout framework

PR ideas

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 core services and utilities

The repo has no visible test files despite containing complex business logic in src/scripts/core/ and src/scripts/filters/. Angular 1.6 projects typically use Karma+Jasmine for testing. Adding tests for core modules (app.js, router.js) and filters (dateDuration.js, fileOrderBy.js, percent.js) would improve maintainability and catch regressions when contributors modify aria2 integration logic.

• [ ] Install karma, karma-jasmine, karma-chrome-launcher as devDependencies in package.json
• [ ] Create karma.conf.js in project root to configure test runner
• [ ] Add test files for src/scripts/core/__core.js and src/scripts/core/app.js
• [ ] Add test files for src/scripts/filters/ (at minimum: percent.js and dateDuration.js)
• [ ] Add 'test' script to package.json pointing to karma
• [ ] Update .circleci/config.yml to run tests in CI pipeline

Migrate ESLint configuration from .eslintrc.json to eslintrc.cjs with modern Angular rules

The project uses AngularJS 1.6 with eslint-plugin-angular installed, but the .eslintrc.json lacks specific Angular 1.x rules for common patterns (e.g., using $scope, controller-as syntax, dependency injection). Updating the config would catch issues early in code review, especially since contributors are adding new controllers and directives.

• [ ] Rename .eslintrc.json to .eslintrc.cjs and convert to CommonJS format for Node.js compatibility
• [ ] Add angular/ng-* rules from eslint-plugin-angular to enforce AngularJS best practices
• [ ] Add rules for dependency injection patterns: angular/di-order, angular/di-unused
• [ ] Add rules for directive/controller naming: angular/directive-name, angular/controller-name
• [ ] Test against existing src/scripts/ files and fix any violations
• [ ] Document the linting rules in a new CONTRIBUTING.md file

Add GitHub Actions workflow to automate i18n translation file validation

The repo supports 10+ languages (src/langs/*.txt files) and i18n/en.sample.txt as a template, but has no automated validation that translation files contain all required keys. This causes incomplete translations to slip through. A GitHub Actions workflow would validate new language files and PRs modifying translations.

• [ ] Create .github/workflows/i18n-validate.yml
• [ ] Write a Node.js script (scripts/validate-i18n.js) that parses en.sample.txt for all keys and checks each src/langs/*.txt file contains matching keys
• [ ] Configure workflow to run on PRs modifying files in src/langs/
• [ ] Add check to ensure no orphaned keys in translation files that don't exist in en.sample.txt
• [ ] Report mismatches with file line numbers for easy debugging
• [ ] Add status badge to README.md showing i18n validation status

Good first issues

• Add unit tests: Repo lacks visible test suite. Create jest.config.js and add tests for src/scripts/config/aria2Options.js (parsing/validation logic) and src/scripts/core/app.js (RPC stub testing). High impact, improves maintainability.
• Document RPC protocol mapping: File src/scripts/config/aria2RpcConstants.js defines method names but lacks JSDoc comments. Add detailed comments mapping each JSONRPC constant to aria2 documentation (e.g., aria2.addUri maps to URI download method). Helps onboarding.
• Fix responsive layout on mobile: File src/index.html and AdminLTE templates may have Bootstrap 3 grid issues on small screens. Test task list on mobile device and fix collapsing columns; add viewport-height constraints. Mobile users are mentioned as target audience.

Top contributors

• @mayswind — 77 commits
• @castillofrancodamian — 7 commits
• @Valaraukar86 — 6 commits
• @vorm04 — 3 commits
• @Malonsow — 2 commits

Recent commits

• 7ad711a — add new contributor (mayswind)
• c6b20eb — update translation (mayswind)
• 205ab38 — update display order (mayswind)
• 1098878 — Add src/langs/ja_JP.txt and update src/scripts/config/languages.js (massangoDa)
• e7bb790 — bump version to 1.3.14 (mayswind)
• d0db05e — support setting continue option when create new task (#809) (mayswind)
• 004b0e3 — bump year (mayswind)
• 97c80b8 — add pause-metadata option when creating a new bt task (WeidiDeng)
• b8a48d8 — bump version to 1.3.13 (mayswind)
• 6404a91 — fix(ui): display 100% progress for completed 0-byte files (chnmasta05)

Security observations

• High · Outdated AngularJS Framework — package.json - angular: 1.6.10. The project uses AngularJS 1.6.10, which reached end-of-life in December 2021. This version contains known security vulnerabilities including XSS issues and lacks security patches. AngularJS 1.x is particularly vulnerable to expression injection and unsafe DOM manipulation. Fix: Migrate to Angular 2+ or a modern framework. If migration is not feasible, implement strict Content Security Policy (CSP) headers and input sanitization. Consider using angular-sanitize with strict DomSanitizer practices.
• High · Outdated Bootstrap Framework — package.json - bootstrap: 3.4.1. Bootstrap 3.4.1 is outdated and contains known XSS vulnerabilities. The project does not use Bootstrap 4.x or 5.x which have better security patches and modern protections. Fix: Upgrade to Bootstrap 4.6.x or 5.x. If immediate upgrade is not possible, ensure all user inputs are properly sanitized and implement CSP headers.
• High · Potential XSS Vulnerability via angular-sanitize Usage — src/scripts/directives/validUrls.js, src/scripts/directives/exportCommandApiDialog.js, src/scripts/services/. The project uses angular-sanitize (1.6.10) for HTML sanitization. Without proper implementation in controllers and directives, there's risk of XSS attacks through ng-bind-html or similar directives. The presence of 'validUrls.js' directive and 'exportCommandApiDialog.js' suggests dynamic content rendering that may not be properly sanitized. Fix: Audit all uses of ng-bind-html and ensure they use $sanitize service. Never use ng-bind-html with untrusted user input without sanitization. Implement Content Security Policy (CSP) headers.
• High · Vulnerable Dependencies - jQuery 3.4.1 — package.json - jquery: 3.4.1. jQuery 3.4.1 is outdated and contains known security vulnerabilities (CVE-2019-11358, etc). Current stable versions are 3.6.x or 3.7.x. Fix: Update jQuery to 3.6.1 or later. Verify compatibility with other dependencies, particularly jQuery-slimscroll and plugins.
• High · Git Dependency with Pinned Commit Hash — package.json - angular-input-dropdown (git+https://github.com/mayswind/angular-input-dropdown.git#68670e39816698b3eb98c0e740a0efe77d5fbdd1). The project uses a git dependency (angular-input-dropdown) pinned to a specific commit hash. This bypasses npm security checks and version management, making it difficult to apply security patches. Fix: Either publish the dependency to npm or maintain it as a git submodule with tagged releases. Use semantic versioning and regular security audits. Consider replacing with a maintained alternative if available.
• Medium · Potential Command Injection via WebSocket RPC Service — src/scripts/services/aria2HttpRpcService.js, src/scripts/services/aria2WebSocketRpcService.js, src/scripts/controllers/command.js. The aria2RpcService interfaces with aria2 via WebSocket/HTTP RPC. Without proper input validation and output encoding, command injection attacks are possible. The 'exportCommandApiDialog' suggests dynamic command construction. Fix: Implement strict input validation for all user-supplied parameters before constructing RPC commands. Use parameterized/prepared methods where possible. Validate and sanitize all responses from aria2 daemon before displaying to users.
• Medium · Outdated Build Dependencies — package.json - devDependencies. Several dev dependencies are outdated and may contain vulnerabilities. gulp-uglify (3.0.2), gulp-cssnano (2.1.3), and related tools lack security patches from newer versions. Fix: Update build tool dependencies: gulp-uglify to 3.0.2+, gulp-cssnano to 2.1.3+, and others. Run 'npm audit' regularly and apply security patches. Use 'npm audit fix' to automatically resolve known vulnerabilities.

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

Where to read next

• 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.