Skip to content
internal/blog/editor/registry
Updated
On this page

Reading the authoring app's hand-written TOML registry of the repositories it may open, strictly: every key known, every name unique, every path real.

#internal/blog/editor/registry

#internal/blog/editor/registry

Package registry reads the authoring app's repository registry: a hand-written TOML file.

This is not framework configuration. It is one machine-local list of the repositories the editor may open, written by hand by the one person the editor serves, and read strictly: every key is known, every required key is present, every name is unique and addressable in a URL, and every local path really is a directory. Anything else refuses and names the offender.

The strictness is the point. A registry entry that quietly fails to parse is a project whose posts silently stop being editable, with no error anywhere to explain why -- so there is no shape here that is merely skipped.

#Format

Two kinds of entry, both under [[repo]], both declaring their kind:

[[repo]] name = "selfdoc" kind = "local" path = "~/Projects/selfdoc"

[[repo]] name = "afar" kind = "remote" repo = "smm-h/afar" ref = "v1.2.3" cache = "~/.cache/selfdoc/afar" render = true

A remote entry is validated in full but not served yet: the server refuses it with "remote entries not yet served" rather than pretending. render is required and has no default because directive resolution reads a source tree, and whether a remote entry gets one is a decision the file has to state.

#Error

Go go
type Error struct

Error reports that the registry file is unusable, and the message says exactly how.

It is the Go counterpart of the Python surface's RegistryError, and the one error type a caller needs to recognize with errors.As to render a registry refusal as one line instead of an unexpected internal failure.

#Entry

Go go
type Entry interface

Entry is one registry entry: a [LocalRepo] or a [RemoteRepo]. The two are separate types rather than one struct with unused members because the server serves a local entry and refuses a remote one, and the distinction is the thing it branches on.

#LocalRepo

Go go
type LocalRepo struct

LocalRepo is a working tree on this machine. Edits land in it directly.

#RemoteRepo

Go go
type RemoteRepo struct

RemoteRepo is a repository elsewhere. Validated here, not served yet.

#Registry

Go go
type Registry struct

Registry is the parsed registry: ordered entries, addressable by name.

#DefaultPath

Go go
func DefaultPath() string

DefaultPath returns where the registry lives. Machine-local by design -- the editor writes working trees on this machine and is not a published, shared surface, so its list of repositories belongs beside the other machine-local records rather than in any project's committed config.

It is a function rather than a constant because it reads the home directory out of the environment, which the Python module it replaces did once at import time.

#Load

Go go
func Load(path string) (*Registry, error)

Load reads and validates the registry at path. An empty path reads [DefaultPath].

It returns an [Error] when the file is missing, unparsable, or declares any shape this package does not accept. The message names the offender.

#Error.Error

Go go
func (e *Error) Error() string { return e.Message }

Error returns the diagnostic.

#LocalRepo.Name

Go go
func (r *LocalRepo) Name() string { return r.name }

Name is the entry's registry name.

#LocalRepo.Kind

Go go
func (r *LocalRepo) Kind() string { return "local" }

Kind is "local".

#LocalRepo.Path

Go go
func (r *LocalRepo) Path() string { return r.path }

Path is the absolute path of the working tree.

#RemoteRepo.Name

Go go
func (r *RemoteRepo) Name() string { return r.name }

Name is the entry's registry name.

#RemoteRepo.Kind

Go go
func (r *RemoteRepo) Kind() string { return "remote" }

Kind is "remote".

#RemoteRepo.Repo

Go go
func (r *RemoteRepo) Repo() string { return r.repo }

Repo is the repository the entry names, as owner/name.

#RemoteRepo.Ref

Go go
func (r *RemoteRepo) Ref() string { return r.ref }

Ref is the git ref the entry pins.

#RemoteRepo.Cache

Go go
func (r *RemoteRepo) Cache() string { return r.cache }

Cache is the absolute path of the checkout cache.

#RemoteRepo.Render

Go go
func (r *RemoteRepo) Render() bool { return r.render }

Render states whether rendering runs against a checkout: directive resolution needs a source tree, so an entry that answers no can only ever serve prose. It is required in the file because neither answer is safe to assume.

#Registry.Names

Go go
func (r *Registry) Names() []string

Names returns the entry names, in the order the file declares them.

#Registry.Get

Go go
func (r *Registry) Get(name string) (Entry, error)

Get returns the entry called name, or a refusal naming what is on offer.

#Registry.Len

Go go
func (r *Registry) Len() int { return len(r.Entries) }

Len returns how many entries the registry declares.

#Registry.RenderList

Go go
func (r *Registry) RenderList() []string

RenderList returns the lines editor list-repos prints: one per entry -- a local entry's working tree, or a remote entry's repository, ref and whether it declares that rendering runs against a checkout -- then a blank line and the count. An empty registry renders as the one line that says so.

More tools from this site

  • claudestream Drive Claude Code from Python: run it as a subprocess and read its output as typed events, with async and sync sessions, sandbox policies, and tools you define in Python
  • claudewheel A TUI Claude Code Launcher that lets you have more than one profile, manage sessions lifecycle, pick the exact CC version, model to use (even older unlisted ones), pick which GitHub account to use, etc.
  • dirstat Fast, single-binary directory statistics CLI: every file under a tree grouped by format, with counts, sizes, and lines of code, as a colored terminal table or as JSON
  • fastware A batteries-included ASGI framework: msgspec JSON, a managed Granian server, dependency injection, SSE, WebSockets, auth, and a test client
  • go-toml-edit Zero-dep TOML editing library for Go with comment preservation
  • howmuchleft The fastest Claude Code statusline: context window, 5-hour, and weekly limit usage as three customizable gradient bars, rendering in about 6 ms
  • orxtra
  • pgdesign
  • predraw Declarative rendering pipeline: describe a scene in JSON and get SVG, PNG and WebP out, with light and dark style tokens, reusable components and text converted to path outlines
  • reposummary Turn a git repository's history into a Markdown journal: pick a time window or revision range and get a readable digest of what changed, optionally narrated by an LLM
  • rlsbl Release orchestration and project scaffolding CLI that bumps versions, validates a structured JSONL changelog, tags only the commit CI verified, and publishes to npm, PyPI, Go and more
  • safegit git wrapper CLI that gives each commit its own temporary index and retries ref updates on conflict, so concurrent agents share one repository
  • saferm Command-line replacement for rm that archives every deletion with a mandatory reason and the context it ran in, so deleted files can be listed, inspected and restored
  • strictcli
  • stricttest An always-on test-isolation floor: a pytest plugin and a Go env-hygiene module that make a test suite structurally unable to reach real credentials, the real HOME, the network, or the development repository.
  • wesktop A Python framework that turns an ASGI web app into a desktop application, serving it from a local Granian server and displaying it in a native OS window via pywebview
Search