Repo rules for AI agents working on SeedSync. CLAUDE.md is a symlink to this file; keep rules here.
SeedSync syncs files from a remote seedbox to a local machine with LFTP, packaged as a multi-arch Alpine Docker image (ghcr.io/nitrobass24/seedsync).
- Stay inside requested scope. Do not implement review-suggested or extra changes without explicit approval.
- Treat CodeRabbit / other agent feedback as input to discuss, not automatic action. Verify each finding against current code before acting.
- SeedSync is single-user self-hosted software. Prefer readable, maintainable code over paranoid guards for unreachable states.
- Bug fix = root cause, not symptom. Check every caller of what you change.
- Python backend (3.13, Bottle):
src/python/—controller/,model/,lftp/,ssh/,system/,web/,common/; entryseedsync.py; remote scan scriptscan_fs.py - Angular frontend (22, Bootstrap 5.3, Vitest):
src/angular/src/app/—models/,services/,pages/,common/ - Playwright e2e:
src/e2e-playwright/ - Docker:
src/docker/build/docker-image/Dockerfile(multi-stage, Alpine-only),docker-compose.dev.yml - User docs (Docusaurus):
website/docs/ - CI:
.github/workflows/ci.yml; docs deploy:.github/workflows/docs-pages.yml - Release history:
CHANGELOG.md
master= stable;develop= integration. All work branches offdevelop.- One concern per branch:
feat/…,fix/…,refactor/…,chore/…,docs/…. Commit only to the feature branch. - Start every task with
git checkout develop && git pull origin develop, then branch. Commit or stash before switching branches. - PRs target
develop. Only two kinds of PR targetmaster: release PRs (release/vX.Y.Z) and develop→master sync PRs. Keep any PR tomasterreviewable (≈100 files max); split sequentially if larger. - Update a PR branch by merging
developinto it. No force-push once a PR has reviews;--force-with-leasebefore that is acceptable on your own branch. - Merge PRs with a merge commit (repo default); do not squash sync/release PRs so
mastershares history withdevelop.
Local (fast) — run before pushing:
- Python (from
src/python):uv run ruff check .anduv run ruff format --check .(CI runs both; passing one does not imply the other),uv run pyright,PYTHONPATH=. uv run pytest tests/unittests,PYTHONPATH=. uv run pytest tests/integration - Angular (from
src/angular, Node ≥ 22.22.3):npx ng lint,npx ng test,npx ng build --configuration production - Playwright (from
src/e2e-playwright):npm testagainst a running container on :8800 (make run;BASE_URLdefaults tohttp://localhost:8800). Ormake test-e2e-dockerfrom the repo root, which starts a throwawayghcr.io/nitrobass24/seedsync:latestcontainer on :8801, runs the suite withBASE_URL=http://localhost:8801, and removes the container.
Docker:
make build/make run/make logs/make stop;make testruns Python tests in the test image;make helplists targets.
Known local-only failures (not regressions): test_scan_file_with_latin_chars (macOS APFS) and tests/integration/test_controller/test_extract (needs archive tools not installed locally). CI covers both.
Do not test CI publish paths with real version tags. workflow_dispatch on a branch publishes ghcr.io/nitrobass24/seedsync:<branch>; use that for live testing of a PR.
- ruff: line length 120,
C901max-complexity 12 (enforced in CI; existing outliers carry# noqa: C901;tests/**excluded). - pyright
strictoversrc/pythonexcludingtests/andscan_fs.py. Do not widen the include set without a plan — tests carry ~4.5k strict errors. - Use
@typing.overrideon every overriding method; pyright checks it. - Angular ESLint via
npx ng lint; keep--max-warningsratcheting down, never up. - If lint output reveals a real issue, fix the smallest relevant scope or say why you can't.
unittest.TestCase;MagicMock/patchfor mocks; web handlers tested withwebtest.TestAppviaBaseTestWebApp. Test files mirror sources (controller.py→test_controller.py).- No
time.sleepin tests; usethreading.Event/barriers;timeout_decoratorfor anything that might hang. - Multiprocessing on Alpine/musl: named semaphores cap at 256 per process. Prefer
PipeStream/PipeFlag(0 semaphores) overmp.Queue/mp.Eventfor single-producer/consumer links (#654). - Alpine's
openssh-clientrejects unknown-ooptions (no GSSAPI). Never add ssh-oflags that Alpine openssh lacks (#562 regression). - Persist formats on disk, web API error strings, and the lftp
setcommand stream are contracts — do not change them without a migration/golden test. - Deletion paths (
controller/delete/) must containment-check every path they remove and must not report success on partial failure.
- Standalone components,
OnPush. Any state mutated insidesetTimeout/async callbacks must callcdr.markForCheck(). - Mutating services: update the
BehaviorSubjectinside the returned observable's pipeline (tap/map), never via a second internal.subscribe(); recover errors withcatchErrorto a typed result. Reference:services/settings/collection.service.ts(base for Integrations / Path Pairs), andConfigService.set,AutoQueueService.add/remove. - Shared UI helpers live in
src/app/common/(e.g.DoubleClickConfirmfor the two-click delete pattern, 3 s timeout) — reuse, don't copy. - Capability flags on
ViewFileare derived inservices/files/view-file-capabilities.ts; if a flag depends on new model data, extendmodelFilesEqualinview-file.service.tsor the flag goes stale. - Icons are inline SVGs /
src/assets/icons/*.svgwithcurrentColor; no icon font. - Specs: Vitest
describe/it,vi.fn()mocks,TestBedfor components. Query DOM by text or stable attributes, not positional selectors. - Line endings are mixed (many Angular files are CRLF). Preserve the existing ending of every file you touch; never normalize. Scripts that read/write whole files (Python
read_text/write_text) silently convert CRLF→LF — checkgit diff --statfor whole-file rewrites before committing.
Every PR ships with tests. Feature → unit tests for happy path, edge, and error paths (integration tests for new endpoints). Bug → a test that fails before the fix. Refactor → existing tests pass unchanged. Removal → delete the dead tests too.
Soft targets: file ≤ 500 lines, class ≤ 300, function ≤ 40, complexity ≤ 12. At 400 lines ask "one concern or several?" Prefer a new collaborator over a bigger class. If a focused test needs cls.__new__(cls) or broad mocking to reach one method, split. Open an issue for an extraction rather than working around it silently; flag deliberate overshoots in the PR body.
- Conventional commits with scope:
feat(angular):,fix(python):,chore(build):,refactor(python):,docs:,ci:. Reference issues ((#123)) in the subject or body. - Never add AI attribution, advertising, or co-author lines to commits, PR bodies, or comments. No
Co-Authored-By: Claude, no "Generated with …" footers. - PR body: short summary, what was intentionally skipped and why, a test-plan checklist, and any size-delta or contract notes the issue asked for. Tick the corresponding checklist item in the tracking issue when a PR merges.
- CodeRabbit incremental reviews are off. Do not trigger reviews (no
@coderabbitai reviewcomments) — the user triggers them. - Inline review comments must anchor to lines in the diff; verify a finding against current code before posting it.
- Before each commit, review the diff for over-engineering. If the ponytail plugin (https://github.com/DietrichGebert/ponytail) is installed, use its
ponytail:ponytail-reviewskill; otherwise do a trim pass: remove speculative config, unused state, single-caller layers, and duplicate helpers.
Releases are the only PRs that bump versions.
Process is not authority. Following this checklist (or any documented workflow) never grants permission for its irreversible steps: merging to master, pushing tags, and publishing images each require explicit, per-action user approval. "Release" or an issue/checklist naming these steps means prepare them and stop for sign-off.
git checkout develop && git pull && git checkout -b release/vX.Y.Z- Add a
## [X.Y.Z] - YYYY-MM-DDentry at the top ofCHANGELOG.md(sections: Changed / Added / Fixed / Removed / Security; bold item names; issue refs). Setversioninsrc/angular/package.json(shown on the About page). - Commit as
Release vX.Y.Z - Brief description— the one approved exception to the conventional-commit format, so release commits are greppable in history. Push, thengh pr create --base master. - After merge:
git checkout master && git pull && git tag vX.Y.Z && git push origin vX.Y.Z. CI builds multi-arch images, pushesX.Y.Z,X.Y,latest, and creates the GitHub release. - Edit the release notes to match the CHANGELOG entry and include
docker pull ghcr.io/nitrobass24/seedsync:X.Y.Z. Verify the image pulls. - Sync
masterback intodevelop:git checkout develop && git pull --ff-only && git merge --ff-only origin/master && git push. Ifdevelophas moved on and the fast-forward is refused, open amaster→developsync PR instead (resolve conflicts there). The release commit (CHANGELOG entry + version bump) only lands onmasterotherwise, and the next release branch would start from a stale version (v1.1.0 was missing fromdevelopuntil v1.2.0). Check that theDeploy Docsrun onmastersucceeded too; it runs onmasterpushes touchingwebsite/or its own workflow file, and can be re-run from the Actions tab (workflow_dispatch).
Semver: major = breaking, minor = features, patch = fixes/cleanup. The Publish job can flake on a Docker Hub pull timeout — gh run rerun <id> --failed, don't re-tag.
ci.yml runs on push to master/develop, PRs against them, v*.*.* tags, and manual dispatch. Jobs: Angular lint/unit/build, Python lint/typecheck/unit/integration, Docker build + container start + Playwright e2e (amd64), multi-arch build.
| Trigger | Publishes image as |
|---|---|
push develop |
:develop |
tag vX.Y.Z |
:X.Y.Z, :X.Y, :latest + GitHub release |
workflow_dispatch on a branch |
:<branch-name> |
| PR | nothing |
GitHub Actions cannot read env context in job-level if; use fromJSON(env.VAR) only at step level.
Before reporting a code change complete, run it live: make build && make run (or ng serve for frontend-only work) and exercise the behavior the change touches. Report the command and what you observed. If the change needs human judgment (UI look and feel, real seedbox behavior), ask the user to test it and say what remains for them. If a live run is not possible (e.g. Docker not running), say so and name the closest check you did run.
State which required checks ran and their results, which were skipped or deferred and why, and any unresolved failures. Do not call work complete while a required check is known failing unless the user accepts the risk.