Skip to content

Latest commit

 

History

History
129 lines (88 loc) · 11.6 KB

AGENTS.md

File metadata and controls

129 lines (88 loc) · 11.6 KB

AGENTS.md

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

Collaboration

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

Repo Map

  • Python backend (3.13, Bottle): src/python/ — controller/, model/, lftp/, ssh/, system/, web/, common/; entry seedsync.py; remote scan script scan_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

Branches / Git Workflow

  • master = stable; develop = integration. All work branches off develop.
  • 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 target master: release PRs (release/vX.Y.Z) and develop→master sync PRs. Keep any PR to master reviewable (≈100 files max); split sequentially if larger.
  • Update a PR branch by merging develop into it. No force-push once a PR has reviews; --force-with-lease before that is acceptable on your own branch.
  • Merge PRs with a merge commit (repo default); do not squash sync/release PRs so master shares history with develop.

Required Commands

Local (fast) — run before pushing:

  • Python (from src/python): uv run ruff check . and uv 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 test against a running container on :8800 (make run; BASE_URL defaults to http://localhost:8800). Or make test-e2e-docker from the repo root, which starts a throwaway ghcr.io/nitrobass24/seedsync:latest container on :8801, runs the suite with BASE_URL=http://localhost:8801, and removes the container.

Docker:

  • make build / make run / make logs / make stop; make test runs Python tests in the test image; make help lists 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.

Lint / Format / Types

  • ruff: line length 120, C901 max-complexity 12 (enforced in CI; existing outliers carry # noqa: C901; tests/** excluded).
  • pyright strict over src/python excluding tests/ and scan_fs.py. Do not widen the include set without a plan — tests carry ~4.5k strict errors.
  • Use @typing.override on every overriding method; pyright checks it.
  • Angular ESLint via npx ng lint; keep --max-warnings ratcheting down, never up.
  • If lint output reveals a real issue, fix the smallest relevant scope or say why you can't.

Python / Backend

  • unittest.TestCase; MagicMock/patch for mocks; web handlers tested with webtest.TestApp via BaseTestWebApp. Test files mirror sources (controller.py → test_controller.py).
  • No time.sleep in tests; use threading.Event/barriers; timeout_decorator for anything that might hang.
  • Multiprocessing on Alpine/musl: named semaphores cap at 256 per process. Prefer PipeStream/PipeFlag (0 semaphores) over mp.Queue/mp.Event for single-producer/consumer links (#654).
  • Alpine's openssh-client rejects unknown -o options (no GSSAPI). Never add ssh -o flags that Alpine openssh lacks (#562 regression).
  • Persist formats on disk, web API error strings, and the lftp set command 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.

Angular / Frontend

  • Standalone components, OnPush. Any state mutated inside setTimeout/async callbacks must call cdr.markForCheck().
  • Mutating services: update the BehaviorSubject inside the returned observable's pipeline (tap/map), never via a second internal .subscribe(); recover errors with catchError to a typed result. Reference: services/settings/collection.service.ts (base for Integrations / Path Pairs), and ConfigService.set, AutoQueueService.add/remove.
  • Shared UI helpers live in src/app/common/ (e.g. DoubleClickConfirm for the two-click delete pattern, 3 s timeout) — reuse, don't copy.
  • Capability flags on ViewFile are derived in services/files/view-file-capabilities.ts; if a flag depends on new model data, extend modelFilesEqual in view-file.service.ts or the flag goes stale.
  • Icons are inline SVGs / src/assets/icons/*.svg with currentColor; no icon font.
  • Specs: Vitest describe/it, vi.fn() mocks, TestBed for 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 — check git diff --stat for whole-file rewrites before committing.

Tests

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.

Code Health

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.

Commits / PRs

  • 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 review comments) — 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-review skill; otherwise do a trim pass: remove speculative config, unused state, single-caller layers, and duplicate helpers.

Release Process

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.

  1. git checkout develop && git pull && git checkout -b release/vX.Y.Z
  2. Add a ## [X.Y.Z] - YYYY-MM-DD entry at the top of CHANGELOG.md (sections: Changed / Added / Fixed / Removed / Security; bold item names; issue refs). Set version in src/angular/package.json (shown on the About page).
  3. 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, then gh pr create --base master.
  4. After merge: git checkout master && git pull && git tag vX.Y.Z && git push origin vX.Y.Z. CI builds multi-arch images, pushes X.Y.Z, X.Y, latest, and creates the GitHub release.
  5. Edit the release notes to match the CHANGELOG entry and include docker pull ghcr.io/nitrobass24/seedsync:X.Y.Z. Verify the image pulls.
  6. Sync master back into develop: git checkout develop && git pull --ff-only && git merge --ff-only origin/master && git push. If develop has moved on and the fast-forward is refused, open a master→develop sync PR instead (resolve conflicts there). The release commit (CHANGELOG entry + version bump) only lands on master otherwise, and the next release branch would start from a stale version (v1.1.0 was missing from develop until v1.2.0). Check that the Deploy Docs run on master succeeded too; it runs on master pushes touching website/ 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

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.

Field Test

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.

Final Report

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.