GPX Wrench — Agents Guide

This document orients future agents working on this repository. It explains the purpose, architecture, workflows, and conventions. Treat this as a living document: if anything becomes untrue or you make a substantial change, update this file immediately (see the last section).

Project overview

GPX Wrench is a Rust CLI for processing GPX (GPS Exchange Format) data via stdin/stdout. It currently offers:

Trim GPX track points to a user-specified time range (relative to the earliest timestamp)
Automatically trim to the detected activity period based on speed analysis

Primary user docs and examples live in

README.md

Repository layout

```
Cargo.toml
```
: Crate metadata and dependencies
```
src/main.rs
```
: CLI argument parsing and subcommand dispatch using
```
clap
```
```
src/lib.rs
```
: Core types and algorithms (parsing ranges, haversine distance, speed calc, activity detection)
```
src/gpxxml.rs
```
: Streaming GPX read/write helpers using
```
quick-xml
```
```
src/commands/
```
: Subcommand implementations
- ```
trim.rs
```
  : Implements the
```
trim
```
  subcommand
- ```
trim_to_activity.rs
```
  : Implements the
```
trim-to-activity
```
  subcommand
```
samples/activity.gpx
```
: Small sample for local testing
```
.github/workflows/ci.yml
```
: CI for fmt, clippy, build, and tests

Core concepts and invariants

I/O contract:
- Read full GPX from stdin, write resulting GPX to stdout; print errors to stderr, exit non-zero on failure.
- Avoid interactive prompts; be scriptable.
Time ranges are relative to the earliest track point timestamp.
Range semantics are inclusive of start and exclusive of end: [start, end).
Preserve GPX structure and unknown extensions for any kept
```
trkpt
```
.
Prefer streaming processing for XML (no full DOM);
```
extract_track_points
```
returns an in-memory list only when required by algorithms (e.g., activity detection).

CLI commands

```
trim DUR1,DUR2
```
or
```
TS1,TS2
```
- Duration units:
```
s
```
  ,
```
m
```
  ,
```
h
```
  (e.g.,
```
5s,1m
```
  ).
- Timestamp formats:
```
MM:SS
```
  or
```
HH:MM:SS
```
  (e.g.,
```
00:15,00:45
```
  ).
- Internally: parse with
```
parse_range
```
  , read earliest time via
```
find_minimum_time
```
  , then filter with
```
filter_xml_by_time_range
```
  .
```
trim-to-activity [-s, --speed-threshold <m/s>] [-b, --buffer <seconds>]
```
- Detects the main activity window via speeds between consecutive track points.
- Internals:
```
extract_track_points
```
  →
```
detect_activity_bounds
```
  →
```
filter_xml_by_time_range
```
  .
- Defaults: speed threshold 1.0 m/s, buffer 30 s; requires at least two timestamped points.

Key modules and functions

src/lib.rs

```
TrackPoint { lat, lon, time }
```

parse_duration

parse_timestamp

parse_range

```
haversine_distance
```
,
```
calculate_speed
```

detect_activity_bounds(track_points, speed_threshold, buffer_seconds)

src/gpxxml.rs

```
find_minimum_time(input)
```

filter_xml_by_time_range(input, start_time, end_time)

filter_xml_by_time_to_writer(input, start_time, end_time, writer)

```
extract_track_points(input)
```

src/commands/

```
trim::trim_command(range_str)
```

trim_to_activity::trim_to_activity_command(speed_threshold, buffer)

Development workflow

Build/test locally:

```
cargo build
```
```
cargo test
```
```
cargo fmt
```
```
cargo clippy -- -D warnings
```

CI mirrors these steps and treats clippy warnings as errors. Keep the code warning-free.
Rust edition: 2024. Dependencies:
```
clap
```
,
```
time
```
,
```
quick-xml
```
(see
```
Cargo.toml
```
).

Adding or modifying commands

Create a new module under
```
src/commands/your_cmd.rs
```
.
Export it in
```
src/commands/mod.rs
```
.
Wire it into the
```
Commands
```
enum and
```
match
```
in
```
src/main.rs
```
.
Follow the I/O contract (stdin → stdout, stderr for errors). Prefer streaming via
```
src/gpxxml.rs
```
.
Update
```
README.md
```
with user-facing docs and examples.
Update this
```
AGENTS.md
```
with architectural notes and invariants impacted by the change.
Add tests (see next section), run
```
fmt
```
/
```
clippy
```
/
```
test
```
, ensure CI passes.

Testing

Unit tests live alongside code (e.g.,
```
#[cfg(test)]
```
in
```
src/lib.rs
```
and
```
src/gpxxml.rs
```
).
For GPX handling, prefer small inline GPX samples in tests for clarity and stability.
Validate:
- Range parsing (positive and negative cases)
- Activity detection windows against controlled inputs
- XML filtering preserves extensions and formatting for retained
```
trkpt
```
- Edge cases: missing timestamps, single-point tracks, out-of-order times

Conventions and code quality

Style: run
```
cargo fmt
```
; keep lines reasonably wrapped; avoid unrelated reformatting.
Linting: fix all
```
clippy
```
warnings (
```
cargo clippy -- -D warnings
```
).
Naming: descriptive function and variable names; avoid abbreviations; prefer clarity over brevity.
Control flow: guard clauses for early exits; handle error and edge cases first; avoid deep nesting.
Error handling: return
```
Result<_, Box<dyn Error>>
```
from command handlers; avoid panics on malformed input.

Common pitfalls

Forgetting that ranges are relative to the earliest timestamp, not the first element encountered.
Off-by-one time inclusivity: ensure [start, end) behavior in filtering.
Dropping extensions inadvertently: keep
```
trkpt
```
contents intact when within range.
Large inputs: activity detection builds a
```
Vec<TrackPoint>
```
; consider memory implications if expanding features.

Keeping this document up-to-date (mandatory)

If you change behavior, interfaces, dependencies, file layout, CLI flags, or invariants, update
```
AGENTS.md
```
in the same pull request.
If any statement here becomes untrue, fix it immediately.
When adding major features:
- Document new commands and their internals at a high level.
- Note any new invariants or performance implications.
- Cross-check
```
README.md
```
  for consistency and update examples.
Use concise, skimmable language and keep sections structured for quick onboarding.

Thank you for keeping this a high-signal guide for future agents.