lance.blue / lexicons
ATProto Lexicons for lance.blue
Star 1
Fork 0
Watch
Python 100%
22 2 0
lexicons
TODO
tools
.gitignore
CLAUDE.md
PLAN.md
prek.toml
README.md
README.md

lexicons #

ATProto lexicons for lance.blue.

Two namespaces. blue.lance.* is anything specific to this game — a camo, an after-action report, a pilot. games.permadeath.* is the identity and social layer that any game could use — a match, a challenge, an achievement, a rating. This repo holds the blue.lance.* schemas; the games.permadeath.* schemas are authored in the permadeath.games/lexicons repo, and the plans here cover both.

PLAN.md describes the nine stages and why they are in that order. TODO/ has one file per stage with the implementation tasks, plus files for work not folded into a stage.

Layout #

One file per schema, in a directory per NSID segment under lexicons/: lexicons/blue/lance/camo.json is blue.lance.camo. That path is the one goat and @atproto/lex look in without being told, so a consumer of these schemas can point a tool at the repo and have it work.

Files are written in goat's form: keys sorted, two-space indent, one trailing newline. goat lex new and goat lex pull both write that, and a record comes back from a PDS in it whatever order it went out in — so a schema here and a copy someone pulls from the network are the same bytes, and a diff between them means a real difference. tools/lint_lexicons.py --format rewrites a file into it; the hook fails if one is not.

goat #

goat is the Bluesky CLI for lexicon work: it lints schemas, checks a change against the published version, checks the DNS, and publishes. It is what the atproto docs point at for publishing, and it is the only tool that does any of this for schemas that are not published yet.

Install v0.2.3 from a release binary, after checking the checksum:

curl -LO https://github.com/bluesky-social/goat/releases/download/v0.2.3/goat_Linux_x86_64.tar.gz
curl -LO https://github.com/bluesky-social/goat/releases/download/v0.2.3/goat_0.2.3_checksums.txt
sha256sum --ignore-missing -c goat_0.2.3_checksums.txt
tar xzf goat_Linux_x86_64.tar.gz goat
install -m 0755 goat ~/.local/bin/goat

What it is used for here:

goat lex lint          # spec and style, run on commit
goat lex check-dns     # every NSID's authority resolves to a DID
goat lex status        # local files against what is published
goat lex breaking      # a change against the published version
goat lex publish       # write the schema records (see TODO/01-namespace.md)

goat lex pull blue.lance.camo is one way another repo takes a copy of a schema from here. It resolves the NSID through DNS and reads the published record, so it only works once the schema is published. A consumer may pull with its own tool instead — headquarters vendors the file through @atproto/lex with the record's CID pinned, and goat must not rewrite those copies.

Pre-commit hooks #

Hooks are managed by prek and configured in prek.toml. One-time setup:

uv tool install prek
prek install --prepare-hooks

They then run on every commit; prek run --all-files runs them by hand.

The schema hooks are goat lex lint, which is the Lexicon spec — it parses first, so there is no separate parse step — and tools/lint_lexicons.py, which covers what goat reports clean:

  • a file whose id disagrees with its path
  • a reference to a schema this repo does not define
  • empty defs, or a union with no refs
  • a file not in the form above