~ knotless Search/
↑↓ move↵ open⇧↵ all results

chadtmiller.com/hud

A remote MCP server that shows atproto records as interactive UI inside MCP Apps hosts

0
0
83 lines · 6.2 KB Raw History

title: knotless section: HUD order: 5 summary: The bundled views that draw knotless, how its queries are named and asked, and the components made for them.

knotless keeps git repositories in atproto accounts, with pulls, issues and checks. Its appview at knotless.dev answers XRPC queries (dev.knotless.*), and HUD resolves their lexicons from the network.

Thirteen bundled views draw them. Each calls did:web:knotless.dev#knotless_appview by default, so query needs no service.

The views

ViewMethodOpens
knotless-repogetRepo, joining its README (getFile) and latest release (listReleases)owner (getProfile), Pulls and Issues (listItems), Commits, Checks
knotless-itemslistItemseach row opens its thread · Open and Closed tabs
knotless-threadgetThreadeach changed file opens its diff (getPullDiff) · the repository, authors
knotless-diffgetPullDiff
knotless-checkslistCheckseach check opens its check record
knotless-commitslistCommitsa commit's pull
knotless-feedgetFeedactors, repositories, threads
knotless-notificationslistNotificationsactors, repositories, threads
knotless-profilegetProfileRepositories (getActorRepos), Activity (getFeed)
knotless-actor-reposgetActorReposeach repository
knotless-actor-itemslistActorItemseach row opens its thread · Open and Closed tabs
knotless-actor-starsgetActorStarseach starred repository
knotless-filegetFilethe repository

A knotless record opened by its at-uri draws as one of these views (their records), except a release. knotless's app page (knotless-app) draws its Home.

Naming a repository

A repository is named by its record's at-uri, with a handle as the authority. Its record key is its name:

at://chadtmiller.com/dev.knotless.repo/knotless

query turns the handle into a DID, as it does in every at-uri param. So naming a repository as handle/name needs nothing more. For example:

{ "method": "dev.knotless.getRepo", "params": { "repo": "at://chadtmiller.com/dev.knotless.repo/knotless" } }
{ "method": "dev.knotless.listItems", "params": { "repo": "at://chadtmiller.com/dev.knotless.repo/knotless", "kind": "pull", "state": "closed" } }
{ "method": "dev.knotless.getThread", "params": { "repo": "at://chadtmiller.com/dev.knotless.repo/knotless", "uri": "at://did:plc:…/dev.knotless.pull/…", "filesOnly": true } }
{ "method": "dev.knotless.getFeed", "params": { "actor": "did:plc:…" } }
{ "method": "dev.knotless.listNotifications" }

Signed out and signed in

Signed out, HUD makes every query to knotless.dev as no one, so it reads public repositories only.

Signed in, the query goes through the account's PDS with atproto-proxy: did:web:knotless.dev#knotless_appview. The PDS signs a service token for it (aud is knotless's DID, lxm the method), and knotless takes the token's account as the asker. So notifications answer, and answers say what the account may do.

knotless reads a private repository as the token's account, so a member reads theirs. A picture its pulls, issues and comments attach comes with a URL that carries a token for that account, lasting about an hour, so the view loads it with no cookie.

listNotifications needs an asker. Signed out, knotless refuses it (AuthenticationRequired). With sign-in on, HUD answers the challenge and describes it in the view's own words (signIn: "Sign in to see your notifications"). With sign-in off, it's a tool error.

Components

The views use components made for them, and each one is generic.

  • State shows what a pull, issue or check is in, by role, as a mark, words or a pill. It uses role colours, the renderer's --hud-color-open, -merged, -closed, -neutral and -running.
  • Label draws a label in its own colour.
  • Diff draws a file's unified diff with line numbers, hunks, and added and removed lines on --hud-diff-*. Lines don't wrap and scroll sideways. Without rows, it draws its header, as a list of files changed.
  • Icon is a menu row's mark. It's a glyph (issue, pull, review, notification, repo, star, check, release, activity, search, people, feed) in white on a rounded square of a tint. The tints are green, blue, purple, gray, yellow, red and orange (the renderer's --hud-tint-*, the same colours on iOS).
  • Tabs holds 2 to 6 tabs, each a label and an open. It marks the one whose query is drawn now. A tab replaces what's drawn with the tab's call, in place. A workspace tile keeps its key, place and from and draws the tab's call (updateTile with its tool and arguments, which every page and the iOS app are told of). The MCP view and the iOS app's signed-out screens replace the screen and don't open another.

Additions to other components

  • Link takes open, a query, as a row opens one. A link naming the query drawn now is marked current (aria-current), as the Open filter on the open list is.
  • Row has an xs gap.
  • List takes title, empty, {"$root": path} items and where. A commit's checks use where, from the answer's array of every commit's checks. A list given "open": false opens nothing.
  • A List's items may be a literal array of at most 20 objects, a menu's fixed rows. Each value is literal or {"$root": path}, and each row opens its own open.
  • Text takes words and chars.
  • RichText takes gfm, and pictures: the pictures its Markdown may show, as getThread lists a pull's, issue's or comment's attachments ({ cid, url, width, height }). An image whose URL is com.atproto.sync.getBlob's with one's CID, on whatever PDS, draws from that picture's url on knotless.dev, no wider than its width. Any other image shows its alt text.
  • Stat of an array counts it. With more bound to a cursor that holds one, it draws N+.

Params of an open

Beside the literals and item bindings any open takes (views), an open's params can use two more bindings:

  • {"$root": path} reads the view's own scope. So a row's thread opens in the repository the list was asked of.
  • {"$atUri": [authority, collection, rkey]} builds an at-uri. A repository's at-uri comes from an event's repo.did and repo.name.