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
```