bnewbold.net / cobalt
go scratch code for atproto
fork atom
cobalt / cmd / glot /
at main 2 folders 14 files
lexicon-templates
lexlint
README.md
lex_breaking.go
lex_check_dns.go
lex_codegen.go
lex_diff.go
lex_lint.go
lex_new.go
lex_publish.go
lex_pull.go
lex_status.go
lex_unpublish.go
lex_util.go
lex_util_files.go
main.go
README.md

glot: AT Lexicon Utility#

This is a developer tool for working with Lexicon schemas:

  • publishing schemas to and synchronizing from the AT network
  • diffing, linting, and verifying schema evolution rules

This project is a work in progress (not much is implemented). This may get moved to a standalone git repository, or maybe get merged in to goat.

The name "glot" is a substring of "polyglot", which describes somebody who speaks many languages.

Quickstart#

Get the Go toolchain set up, then install glot from source:

go install tangled.org/bnewbold.net/cobalt/cmd/glot

The command comes with top-level and sub-command help pages.

In a project directory, download some existing schemas, which will get saved as JSON files in ./lexicons/:

glot pull com.atproto.repo.strongRef com.atproto.moderation. app.bsky.actor.profile
 🟢 com.atproto.repo.strongRef
 🟢 com.atproto.moderation.defs
 🟢 com.atproto.moderation.createReport
 🟢 app.bsky.actor.profile

Create a new record schema and edit it:

glot new record dev.project.thing

vim ./lexicons/dev/project/thing.json

Lint all local lexicons:

glot lint
 🟢 lexicons/app/bsky/actor/profile.json
 🟢 lexicons/com/atproto/moderation/createReport.json
 🟢 lexicons/com/atproto/moderation/defs.json
 🟢 lexicons/com/atproto/repo/strongRef.json
 🟡 lexicons/dev/project/thing.json
    [missing-primary-description]: primary type missing a description

Check for differences against the live network, both for local edits or remote changes:

glot diff
diff com.atproto.repo.strongRef
--- local
+++ remote
 {
   "defs": {
     "main": {
       "properties": {
         "cid": {
           "format": "cid",
           "type": "string"
         },
         "uri": {
           "format": "at-uri",
           "type": "string"
         }
       },
       "required": [
         "uri",
         "cid"
       ],
       "type": "object"
     }
   },
-  "description": "Reference another record in the network by URI, plus a content hash.",
+  "description": "A URI with a content-hash fingerprint.",
   "id": "com.atproto.repo.strongRef",
   "lexicon": 1
 }

If you edited an existing schema, check schema evolution rules against the published version:

glot breaking
 🟡 app.bsky.actor.profile
    [object-required]: required fields change (main)
 🟢 com.atproto.repo.strongRef

Check DNS configuration before publishing to new Lexicon namespaces:

glot check-dns
Some lexicon NSIDs did not resolve via DNS:

    dev.project.*

To make these resolve, add DNS TXT entries like:

    _lexicon.project.dev	TXT	"did=did:web:lex.example.com"

(substituting your account DID for the example value)

Note that DNS management interfaces commonly require only the sub-domain parts of a name, not the full registered domain.

When ready, publish new or updated Lexicons:

export ATP_USERNAME="user.example.com"
export ATP_PASSWORD="..."
glot publish
 🟢 dev.project.thing