bnewbold.net
go scratch code for atproto
1
2glot: AT Lexicon Utility
3========================
4
5This is a developer tool for working with Lexicon schemas:
6
7- publishing schemas to and synchronizing from the AT network
8- diffing, linting, and verifying schema evolution rules
9
10This 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`.
11
12The name "glot" is a substring of "polyglot", which describes somebody who speaks many languages.
13
14
15## Quickstart
16
17Get the Go toolchain set up, then install glot from source:
18
19```
20go install tangled.org/bnewbold.net/cobalt/cmd/glot
21```
22
23The command comes with top-level and sub-command help pages.
24
25In a project directory, download some existing schemas, which will get saved as JSON files in `./lexicons/`:
26
27```
28glot pull com.atproto.repo.strongRef com.atproto.moderation. app.bsky.actor.profile
29 🟢 com.atproto.repo.strongRef
30 🟢 com.atproto.moderation.defs
31 🟢 com.atproto.moderation.createReport
32 🟢 app.bsky.actor.profile
33```
34
35Create a new record schema and edit it:
36
37```
38glot new record dev.project.thing
39
40vim ./lexicons/dev/project/thing.json
41```
42
43Lint all local lexicons:
44
45```
46glot lint
47 🟢 lexicons/app/bsky/actor/profile.json
48 🟢 lexicons/com/atproto/moderation/createReport.json
49 🟢 lexicons/com/atproto/moderation/defs.json
50 🟢 lexicons/com/atproto/repo/strongRef.json
51 🟡 lexicons/dev/project/thing.json
52 [missing-primary-description]: primary type missing a description
53```
54
55Check for differences against the live network, both for local edits or remote changes:
56
57```
58glot diff
59diff com.atproto.repo.strongRef
60--- local
61+++ remote
62 {
63 "defs": {
64 "main": {
65 "properties": {
66 "cid": {
67 "format": "cid",
68 "type": "string"
69 },
70 "uri": {
71 "format": "at-uri",
72 "type": "string"
73 }
74 },
75 "required": [
76 "uri",
77 "cid"
78 ],
79 "type": "object"
80 }
81 },
82- "description": "Reference another record in the network by URI, plus a content hash.",
83+ "description": "A URI with a content-hash fingerprint.",
84 "id": "com.atproto.repo.strongRef",
85 "lexicon": 1
86 }
87```
88
89If you edited an existing schema, check schema evolution rules against the published version:
90
91```
92glot breaking
93 🟡 app.bsky.actor.profile
94 [object-required]: required fields change (main)
95 🟢 com.atproto.repo.strongRef
96```
97
98Check DNS configuration before publishing to new Lexicon namespaces:
99
100```
101glot check-dns
102Some lexicon NSIDs did not resolve via DNS:
103
104 dev.project.*
105
106To make these resolve, add DNS TXT entries like:
107
108 _lexicon.project.dev TXT "did=did:web:lex.example.com"
109
110(substituting your account DID for the example value)
111
112Note that DNS management interfaces commonly require only the sub-domain parts of a name, not the full registered domain.
113```
114
115When ready, publish new or updated Lexicons:
116
117```
118export ATP_USERNAME="user.example.com"
119export ATP_PASSWORD="..."
120glot publish
121 🟢 dev.project.thing
122```