Depos

Dependency notes for Gleam

gleam.toml lists the packages a project needs and the versions it accepts. It does not say why a package is there, why a range is held back, or what to run after it moves.

Depos keeps a note for each dependency in .depos/gleam/DEPENDENCY-NOTES.md, beside gleam.toml, and shows it on the dependency's line.

What Depos reads

  • Manifest: gleam.toml
  • Notes file: .depos/gleam/DEPENDENCY-NOTES.md
  • Section heading: the dependency key: ## gleam_stdlib, ## gleeunit

Depos reads direct keys in [dependencies] and [dev_dependencies] in gleam.toml, including version, Hex, Git and path declarations. manifest.toml, transitive packages and other tables are not read.

Depos never runs Gleam, so it needs no Gleam or Erlang installation.

Example

[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"
wisp = ">= 1.2.0 and < 2.0.0"
mist = ">= 3.0.0 and < 4.0.0"

[dev_dependencies]
gleeunit = ">= 1.0.0 and < 2.0.0"

.depos/gleam/DEPENDENCY-NOTES.md:

## wisp

Web framework for the HTTP API; mist serves it.

### Agent notes

- purpose: routing and middleware for the HTTP API
- bump-with: mist
- verify: `gleam test`
- verified: 1.2.0

The heading is the dependency's key in gleam.toml, under [dependencies] or [dev_dependencies] alike: wisp = ">= 1.2.0 and < 2.0.0" is ## wisp.

Comments in gleam.toml

[dependencies]
gleam_stdlib = ">= 0.44.0 and < 2.0.0"
# wisp: routing and middleware for the HTTP API
wisp = ">= 1.2.0 and < 2.0.0"
mist = ">= 3.0.0 and < 4.0.0" # bump with wisp

gleam.toml is TOML: # starts a comment that runs to the end of the line. gleam add and gleam remove edit the file in place, so the comments on other lines stay; gleam remove takes the comments above and beside the removed dependency with it.

Pinning a version

gleam add writes a range from the version it resolved up to the next major, ">= 1.2.0 and < 2.0.0", even when you name a version: gleam add [email protected] writes the same range. A requirement that is just a version, "1.2.0" or "== 1.2.0", accepts that version only, and "~> 1.2" means >= 1.2.0 and < 2.0.0.

manifest.toml locks every package to the version Gleam resolved. gleam deps update moves them to the newest versions gleam.toml allows without changing gleam.toml, and gleam deps update wisp unlocks wisp and the packages only it needs. Why a range stops where it does goes in the dependency's note, as constraint:.

For AI coding agents

An agent reads a dependency's section before it adds, upgrades or removes it, and logs what it did under ### Agent notes. See the rules agents follow.