~ 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
400 lines · 24.9 KB Raw History

Working on HUD

For every agent working here: CLAUDE.md is this file, imported. What HUD is and how it is run is in README.md and the pages in docs/.

Layout

  • crates/hud-core: everything that is not HTTP: configuration, the outbound client and its address filter, identity resolution, lexicons, PDS reads, XRPC queries (xrpc.rs: services, params and answers checked against lexicons), blob-ref rewriting, the audio blob cache, views (their validation, the component catalog, the join engine, summaries), the kit each tree is fitted to (kit.rs: the renderer's version a client says, a view's gates on it, what stands for a component newer than it, and hud check's warnings for an app's oldest kit), the tools, the three that write (writes.rs, a text's facets made by richtext.rs, a composer's writes template filled by compose.rs), a link's card (cards.rs) and places (places.rs) for a composer, the procedures a trusted view calls (procedures.rs), the operator's apps and views (operator.rs, HUD_APPS, checked as the bundled views' tests check them, with the lexicons they ship and the HUD versions they run on), the JSON Schemas of an app file and a view (schema.rs), the workspace's canvases (canvas/: the engine, each person's tabs and live stream, placement on the strip of columns in strip.rs, the Store trait and its file backend, the space backend in space.rs, with HUD_SPACES=on, the tools), apps' icons (icons.rs: favicons, kept on disk), the workspace's themes (theme.rs: HUD's, people's place.hud.theme records, their contrast check, and each person's choice of one), what HUD keeps of a person and its deletion (account.rs), the space client (space.rs: com.atproto.space.* as the account), the scope sign-in asks for (scope.rs: atproto's permissions, built from the trusted views, through the permission sets their app files name, and whether a sign-in is behind them), and sign-in (oauth/: the MCP authorization server in issuer.rs, the atproto OAuth client in client.rs, sessions on disk in store.rs, MCP sessions and the workspace's web sessions alike, and their offline tests against a fake PDS in tests.rs, its spaces and the space backend's tests in tests/spaces.rs).
  • crates/hud-server: the HTTP surface: POST /mcp (and its sign-in challenges), GET /blob/{did}/{cid}, GET /_health, the terms, privacy policy and guidelines, GET /{terms,privacy,guidelines} (policies.rs, each page's HTML in policies/), HUD's icon, /favicon.svg, the playground, /playground (playground.rs), HUD's methods, /xrpc/place.hud.* (xrpc.rs, its tests through the router in xrpc/tests.rs: the playground's and searchActors anyone's, the workspace's with sign-in on alone), and apps' icons, /icon/{domain} (icon.rs); and with sign-in on /oauth/* and /.well-known/oauth-* (oauth.rs, with the sign-in page MCP clients see), the workspace's page, /workspace (where / goes; signed out, the landing), the sign-in dialog's app logos, /workspace/atmo/* (crates/hud-server/atmo/), the landing's picture, /workspace/hero/* (crates/hud-server/hero/, made by just hero), and its sign-in, switching and sign-out, /workspace/{signin,switch,signout}, its sessions' cookies hud_session and hud_accounts (workspace.rs); with HUD_WEB, the operator's web app's pages, /, the icons and every request no route takes, handed on and streamed back (web.rs, its tests against a fake app in web/tests.rs); its build.rs embeds web/dist/index.html, web/dist/workspace.html, web/dist/playground.html and web/dist/favicon.svg.
  • crates/hud: the binary, hud serve; hud resolve, which gives a recorded answer its _meta.ui, for the harnesses; hud check <dir>, which loads a directory of apps as hud serve loads HUD_APPS, naming every problem; and hud schema app|view.
  • web/renderer (@hud/renderer): the renderers as Svelte components, with no dependency on MCP, so another app can reuse them, drawn on a server (svelte/server) as in the browser: nothing touches a browser's globals as it loads or draws, nothing is kept on a server, and the browser's first drawing is the server's (Tree's now, dates fixed until mounted). Its server test, web/renderer/test/ssr.mjs (cd web && npm run ssr), draws Grain's trees in web/renderer/test/trees (made by just ssr-data, harness/ssr/data.mjs) in Node and hydrates them in happy-dom.
  • web/renderer, web/shell and web/shared are HUD's web packages, published (docs/sdk.md): each package's src built by svelte-package into its dist (cd web && npm run package), which its exports name; inside web/ they resolve to src by the @hud/source condition (vite.config.ts, tsconfig.json, the server tests' builds). Code in web/ imports one by its name (@hud/shared/result), never by a path into it.
  • web/shell (@hud/shell): an app drawn as a web app from its app file (docs/views.md, "The frame"): Shell, its frame (the tabs as a bar, a rail or a sidebar by the window's width, decided in CSS, frame.ts) and each tab's nav stack of tool results drawn with the renderer, server-rendered and hydrated as the renderer is; and @hud/shell/server, what an app's server reads for a page, and its sessions at HUD (session.ts: the browser's accounts, sealed in a cookie, seal.ts, accounts.ts; signing in as HUD's MCP client, oauth.ts). Its host gives it its router and routes its endpoints (Grain's next/). Its server test, web/shell/test/ssr.mjs (in npm run ssr), draws a sample app at three widths and hydrates it; npm run unit its unit tests.
  • web/src: the view, which talks to its host through @modelcontextprotocol/ext-apps and draws with the renderer.
  • web/workspace: the workspace's page, which calls its own server's /xrpc/place.hud.* and draws with the renderer, and the playground's (web/playground.html, Playground.svelte), built of the same components: a view written beside what it draws (previewView); web/shared (@hud/shared), what it, the view and the shell share: reading a tool result (result.ts), a person's interactions (interactions.ts) and Result.svelte; web/public/favicon.svg, HUD's icon, which Vite copies into web/dist as it is.
  • web/dev: a dev host for the view (just dev), against just serve.
  • lexicons/: the bundled lexicons, written by just lexicons; never edited by hand. schemas/: our own lexicons (place.hud.*: the records, the workspace's methods, defs, and ui, the resolved tree a result's _meta.ui holds, which hud_core::ui::check holds the resolver's trees to in its tests), written by hand, embedded beside them; just lexicons never touches it. schemas/json/: the JSON Schemas of an app file and a view (hud_core::schema), no lexicons, written by just json-schemas and held current by a test.
  • harness/: checks beside cargo's, each a node script whose header says what it checks and how to run it, run by the Justfile: lexicons.mjs, answers.mjs and schemas.mjs (just lex), layers.mjs, contrast.mjs and docs.mjs (just lint), look.mjs (just look), scroll.mjs (just scroll, a long feed scrolled, page in harness/scroll/), gallery.mjs (just gallery: every drawing HUD makes as a tile, side by side, from the answers in harness/gallery/ given their trees by just gallery-data; the iOS app draws the same file, Debug builds' Settings → Development → Gallery). cd harness && npm ci once. Against a PDS of HUD's own: pds.mjs (the reference PDS and PLC, alice, bob and carol), the e2e world over it (e2e/world.mjs, just e2e), and the same kept running with a browser at it, and with --ios the app on a simulator, to try by hand (local.mjs, just local). HUD is served there at hud.harness.internal with a certificate of the checkout's own authority (tls.mjs, kept in .local/tls/), which a simulator is told to trust. Each takes the spaces alpha with HUD_DEV_ENV (harness/spaces; just e2e-spaces, just local --spaces), where HUD keeps canvases in people's spaces. just local-setup once per checkout and Mac: the packages, the authority, and that hostname in /etc/hosts.
  • views/: the bundled views, one JSON file per view, named as its id, each a place.hud.view document; embedded by hud-core and checked by its tests. An operator's views (HUD_APPS) replace or add to them at startup, held to the same checks (view::trusted_problems, view::conflicts).
  • docs/: the docs, one page per topic, each fact in one page, written and checked (harness/docs.mjs) as docs/_style.md asks, which says which page owns what; README.md points at them. A change to a tool, a default or a mechanism changes the page that owns it.
  • themes/: HUD's own themes, one JSON file per theme, named as its key, each a place.hud.defs#theme: light and dark, HUD's own look, with no palette, and the rest each a palette; embedded by hud-core, checked by its tests, and handed to the page and the iOS app by getWorkspace, so no client keeps a copy. People's are records in their own repositories (place.hud.theme), held to the same contrast.
  • ios/: the iOS app. ios/HUDKit, a Swift package: the renderer in SwiftUI, a port of web/renderer (Tree/ draws the tree the server resolved, Embed/ its embeds), what web/shared/src/result.ts and interactions.ts do (Data/), the client that calls the tools over /mcp, an operator's app file's routes and push for an app built on HUDKit (Data/Routes.swift, Data/Push.swift: the device registered as its push says, a tapped notification opened as a route), and the workspace's client and model (Workspace/: its XRPC methods and event stream as the signed-in account, by Bearer, and its theme, Theme.swift); its tests in Tests/. A palette reaches the views through Support/Surface.swift (.hudTheme, and HUDColor, a role's colour or the native one): a colour a palette names is never a system colour in a view. ios/App, the app around it: signed in, the workspace (canvases as tabs, a strip of columns, one a screen on a phone, each tile a tool call), Home and Settings (accounts, theme) sheets over it; signed out, signing in by handle; its icon in App/Assets.xcassets, the same as the favicon, square, as iOS masks it. ios/project.yml makes the Xcode project (just ios; the project is gitignored); just ios-test runs HUDKit's tests.
  • android/: the Android app, a Gradle project. android/hudkit (place.hud.kit): the renderer in Jetpack Compose, a port of ios/HUDKit as that is of web/renderer: tree/ draws the tree the server resolved (TreeView.kt's ResolvedNode, a component a function), parts/ and embed/ its pieces, data/ what web/shared/src/result.ts does, support/ the surfaces by role (Surface.kt's HudColors, a palette's colour or Material's), type, icons (Glyphs.kt, the web's own paths) and pictures (Coil); its tests in src/test, on the JVM under Robolectric, reading iOS's fixtures. android/app, the app around it: for now the gallery, the sample tiles of just gallery-data a debug build carries (just android <entry>; just android-test runs hudkit's tests).

A new crate goes in crates/<name>, named as its directory, with its versions in the root Cargo.toml's [workspace.dependencies].

Versioning

HUD has one version, its SDK's: the crates', the web packages', HUDKit's and hudkit's (knope.toml names every file that holds it). A pull that changes what an app built on HUD sees (a component, a prop, what a tree draws, a tool's shape) adds a change file under .changeset/, as knope document-change writes one: default: patch, minor or major in its front matter, then a heading and a line for the app's authors. release-pull.yml, asked for at main, turns them into the version and CHANGELOG.md in a Release <version> pull; release.yml, asked for at main once that lands, publishes every package. Never bump a version by hand. docs/sdk.md has the rest.

Rules

  • Cargo through rustup: rustup run stable cargo (the Justfile's cargo). Node is the version .node-version names; cd web && npm ci once.
  • just check is what a change must pass: rustfmt, clippy with warnings denied, the tests under just cov's gate, svelte-check, the renderer's server test (npm run ssr), just lint and just lex. The runner (runner.knotless.dev) runs the same on pushes to main and pulls into it (.knotless/workflows/): check, test and web as the merge queue's pre-flights, lexicons, docs, e2e (just e2e) and e2e-spaces (just e2e-spaces). main takes pulls only through the merge queue, each once review.knotless.dev has reviewed its head, and each push to it deploys hud.place (deploy, on ci.knotless.dev). A workflow's shared steps are pinned in .knotless/uses.lock (knotless workflow pin).
  • just cov fails under 100% of lines or functions, workspace-wide: a line no test runs is a case nobody checked, so test it with what a consumer would notice, never lower the gate or hide code from it. Where no test can sensibly reach a line, write it so the path does not exist: cargo fmt can put a ? on a line of its own, which counts as a line never run (bind the value first), and since Rust 1.100 coverage counts the closing } of an if with no else as the path where the condition is false, and each match arm on its own. The hud binary counts too: its tests run it (CARGO_BIN_EXE_hud), and stop hud serve by SIGTERM so its profile is written.
  • A lexicon in schemas/ follows the Lexicon Style Guide (https://atproto.com/guides/lexinomicon) and passes just lex: goat's lint (less the warnings harness/lexicons.mjs keeps, each with why), knownValues not enum, objects in arrays, open unions, a description on every main saying whether it needs auth, a maxLength on every string without a format people write, accounts by DID; and only grows from main's once published. Every answer the server's tests receive is held to its method's lexicon (harness/answers.mjs), so a method's tests call it through the router (xrpc/tests.rs's ask).
  • The server keeps no database: caches only, in memory, and the lexicon, audio blob and apps' icon caches on disk under HUD_CACHE_DIR; and, with sign-in on, sign-ins under HUD_DATA_DIR/oauth/ (hud_core::oauth), the workspace's canvases and each person's index of them and their tabs under HUD_DATA_DIR/canvas/ (hud_core::canvas), and each person's theme under HUD_DATA_DIR/theme/ (hud_core::theme), each file mode 0600 and written whole; with HUD_SPACES=on, a canvas its owner alone is in goes in their own space instead. The one database is the operators' copy of the log, with HUD_LOGS=on: HUD_DATA_DIR/logs.db (hud_core::logs), SQLite, mode 0600, holding the lines stderr has and nothing more, so never a token, a query's secret, a header or a body; read by HUD_OPERATOR_DIDS alone. Lines are logged through hud_core::telemetry (docs/observability.md), every outbound call through hud_core::net. Never log a token, or keep one of HUD's own (a web session's cookie too) but as its SHA-256. The query tool calls queries alone, never a procedure; a caller goes through xrpc::Caller, as no one or as the signed-in account through its PDS, the one place they differ. Writes go through create_record, apply_writes and delete_record alone, as the account, to its own repository, each record checked against its lexicon first (its {"$facets": key} fields made the text's facets before), and a composer's pictures through place.hud.uploadBlob alone, to the account's PDS, never logged; but a procedure a trusted view calls (Action's call, Messages' send), or an operator's app file registers a device for push with (its push), through call_procedure (hud_core::procedures) alone, the view's, sent through the account's PDS only if a trusted view or app file calls that method of that service, its input checked against its lexicon first, neither input nor answer logged; what a trusted view's deletes plans (an Action's), through call_procedure alone too, its query asked as the account only if a trusted view deletes by it, its deletes committed in one applyWrites of the account's own repository, each of a collection the scope asks to write or delete (Hud::delete_planned); and the canvases' records through hud_core::space, as the account, to its own repo in its own spaces, each checked against its lexicon (schemas/) first. The space scope stays one constant (config::SPACE_SCOPE), never asked for by default.
  • A tool that needs an account answers Refusal::SignIn without one, which /mcp turns into the HTTP 401 challenge, never a tool error. No OAuth or MCP SDK crates: sign-in is built on the atproto crate's jose and keys.
  • Anything a DID document, lexicon or service says is untrusted. Outbound requests go through hud-core's client, which refuses non-public addresses, but for the operator's own web app (HUD_WEB), its origin the operator's, reached through a client of its own for it alone (net::Web); a service's answer is checked against its query's lexicon; lexicon descriptions reach the view only, as plain text, never a tool's content, description or structuredContent (describe_collection and describe_method strip them).
  • A tool's text content is a short summary a person could read; its data is structuredContent; what only the view needs is _meta.
  • The view loads nothing but its own inline code, and images and audio from the server's blob proxy, and public records' images from the image CDN (HUD_IMAGE_CDN), and public posts' videos from Bluesky's video service and CDN (HLS); it reaches the server only through its host's tool calls. No fetch from the view but a Map's vector tiles, from catalog::MAP_TILES alone (in the CSP's connectDomains).
  • blobs::rewrite is told whether what it rewrites was read where anyone can (Visibility::Public: com.atproto.repo.*, the AppView) or not (Private: a space, a service's answer to the account): a private record's blobs never get a CDN URL.
  • The workspace's page reaches its own server alone, its XRPC methods as its web session; their procedures by the cookie carry X-HUD: 1, and the server takes them from its own Origin only. A HUD access token as Bearer calls them too, as an app of the person's would. A canvas tile names a read tool and its arguments, never a result: the page calls the tool (callTool) to draw it. Tiles are placed on the server (canvas::strip), so a person and an agent place them alike.
  • A change to a tool, its shapes or the view's renderers changes both sides in one change.
  • Views are data. No code names a collection a bundled view draws: a record type gets its own drawing by a view in views/, written with the catalog's components, not by a renderer of its own. Where a query draws a record richer (a post's thread), the record opens as that query: its method view names the collection in records, and no collection view draws it. Collections themselves are never shown: a profile shows apps, sections and activity, never a list of collections.
  • A tile is one thing. A view draws what belongs to its subject in itself, by a join: a post's replies, a gallery's photos and comments, an issue's conversation. It opens a new tile (open) only for another thing: another record, account, feed or app.
  • An account opens where it is read: a name in a bundled view's drawing opens their page in that view's app (ui::Ctx::people), else their profile across apps (describe_repo), which a tile's @handle opens too. A view names an account by href, never by an app's own query.
  • Only the bundled views and the operator's (HUD_APPS, hud_core::operator) are trusted, and HUD refuses to start unless the operator's pass what the bundled views' tests hold them to, through the same code. Every read of them goes through view::bundled(), the bundled views as the operator's replace and add to them. No HUD code names an operator's app. A view given inline is checked exactly as a bundled one is, but may name only origins a trusted view names (so it never widens the CSP), and its description reaches no tool description or instructions. A result says which it is (_meta.ui.trusted): the view asks the person to confirm an untrusted view's Action before it writes.
  • Views are resolved on the server: a view's layout is read against its data in hud-core/src/ui/ into _meta.ui, a tree the clients only draw (no client binds a view or fetches for one). The component catalog lives in four places that change together: the Rust constant (hud-core/src/catalog.rs), which validates layouts and is what describe_collection and describe_method hand a model, with the resolver (hud-core/src/ui/) that reads it into the tree; and the three that draw the tree, web/renderer (src/tree/), ios/HUDKit (Tree/) and android/hudkit (tree/). A component or prop added to the catalog says the version it arrives in (since): a build of an older kit is sent its children, its fallback or nothing in its place (hud-core/src/kit.rs). A look is the platform's own, but the surfaces are one: a grey canvas, a tile's body lighter in front of it, a card in a tile that body's colour inside a hairline (iOS's HUDKit/Support/Surface.swift, Android's support/Surface.kt).

Web pages

The workspace (web/workspace) follows knotless's web practices (~/code/knotless/web/AGENTS.md, its ui skill):

  • Layers: components live in web/workspace/lib/{atoms,molecules, organisms,templates}; each uses its own layer and those below, never one above (harness/layers.mjs, in just lint). Pages in web/workspace/*.svelte fill the template; modules in lib/ (state, the stream, xrpc.ts) belong to no layer.
  • Tokens: every value in its CSS is a token from web/workspace/tokens.css (knotless's, by the same names), a colour by its role, never its hue, as light-dark(); add one there when none fits. The renderer's MCP Apps host variables are set from them in app.css, so tiles and chrome are one look, and a theme's palette (lib/theme.ts) is written over them, so it colours both. Every text colour reads at 4.5:1 in light, dark and every palette: harness/contrast.mjs checks the pairs harness/contrast.json names in light and dark, and hud_core::theme::problems its PAIRS in a palette; a new colour that is text goes in the first, and in the palette and the second if a theme colours it.
  • Icons: Lucide's, through lib/icons.ts, one per thing, the same everywhere; an icon without its word has an aria-label. An app's icon is its favicon (AppIcon, HUD's /icon/<domain>), its kind's Lucide icon where it has none.
  • Data: the page reaches only its own server's XRPC methods, typed by npm run lex (gitignored lib/lexicons), through lib/xrpc.ts.
  • Words and menus: sentence case, labels without a full stop, empty states that say what is empty where the rows would be, one primary button a view; a menu that opens is a <details class="popover">, a sheet on a phone.
  • Memory: what a page holds follows what is on screen (docs/memory.md). A tile keeps its answer as read ($state.raw, a page more replacing it, never mutating it) and draws it only while live; a component's state a person changes (a like, a reveal) is kept with remembered (renderer view/remember.svelte.ts), as it is unmounted and drawn again; a long list goes through ListWindow (view/window.ts); a picture drawn small takes source(…, 'small'), a blob's thumb or a URL by the view's thumbnails, and Picture falls back once to a blob's proxy; media load nothing until played. A server cache is a cache::Ttl, bounded by entries and bytes, its share of HUD_CACHE_MEMORY_BYTES. Check a change with just memory, and one to a long list's drawing with just scroll (no long tasks while scrolling, p95 frame under 20 ms, no blank frames).
  • Looking: just look <name> [--set …] [--events …] [--click …] [--press …] draws the workspace from web/dist in front of harness/look/ (no PDS, no server: each answer given its _meta.ui by hud resolve) into target/look. Look at every state you touch, desktop light and phone dark, and have the pictures critiqued by an agent that did not write them.

atproto's primitives

DIDs, handles, NSIDs, record keys, CIDs and DID documents' services come from the atproto crate (knotless.dev/chadtmiller.com/atproto), published to that repository's Cargo registry, which .cargo/config.toml names. A primitive HUD needs that the crate lacks goes there first, as a new version.