this repo has no description
expanded glot README
+113
-3
+113
-3
cmd/glot/README.md
+113
-3
cmd/glot/README.md
···
4
4
5
5
This is a developer tool for working with Lexicon schemas:
6
6
7
-
- code generation for API clients, servers, and record schemas
8
7
- publishing schemas to and synchronizing from the AT network
9
8
- diffing, linting, and verifying schema evolution rules
10
9
11
-
This project is a work in progress (not much is implemented). This will
12
-
probably become a stand-alone git repository, and the name is likely to change.
10
+
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`.
11
+
12
+
The name "glot" is a substring of "polyglot", which describes somebody who speaks many languages.
13
+
14
+
15
+
## Quickstart
16
+
17
+
Get the Go toolchain set up, then install glot from source:
18
+
19
+
```
20
+
go install tangled.sh/bnewbold.net/cobalt/cmd/glot
21
+
```
22
+
23
+
The command comes with top-level and sub-command help pages.
24
+
25
+
In a project directory, download some existing schemas, which will get saved as JSON files in `./lexicons/`:
26
+
27
+
```
28
+
glot 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
+
35
+
Create a new record schema and edit it:
36
+
37
+
```
38
+
glot new record dev.project.thing
39
+
40
+
vim ./lexicons/dev/project/thing.json
41
+
```
42
+
43
+
Lint all local lexicons:
44
+
45
+
```
46
+
glot 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
+
55
+
Check for differences against the live network, both for local edits or remote changes:
56
+
57
+
```
58
+
glot diff
59
+
diff 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
+
89
+
If you edited an existing schema, check schema evolution rules against the published version:
90
+
91
+
```
92
+
glot compat
93
+
🟡 app.bsky.actor.profile
94
+
[object-required]: required fields change (main)
95
+
🟢 com.atproto.repo.strongRef
96
+
```
97
+
98
+
Check DNS configuration before publishing to new Lexicon namespaces:
99
+
100
+
```
101
+
glot check-dns
102
+
Some lexicon NSIDs did not resolve via DNS:
103
+
104
+
dev.project.*
105
+
106
+
To 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
+
112
+
Note that DNS management interfaces commonly require only the sub-domain parts of a name, not the full registered domain.
113
+
```
114
+
115
+
When ready, publish new or updated Lexicons:
116
+
117
+
```
118
+
export ATP_USERNAME="user.example.com"
119
+
export ATP_PASSWORD="..."
120
+
glot publish
121
+
🟢 dev.project.thing
122
+
```