contexts, and adopting by name: loomctl external add loom/cart cart

The config becomes kubectl-shaped — named contexts with one current, each holding a host, its flavor and a read-only token — and a bare owner/repo resolves against it. The point is where the details live: a host's raw-file route belongs to the host so it sits in the context, the published directory belongs to the convention so it sits in the code, and what is left is which repository and which document, which is the only part a person knows. Measured rather than assumed, because the three hosts differ. Gitea redirects its short raw form to the resolved branch, so the lock records a branch without anybody naming one. GitHub and GitLab accept HEAD and do not redirect, which would put a moving ref in the lock — the hazard already recorded and nearly built anyway — so those resolve the default branch with git ls-remote --symref first, one round trip and no clone. That supersedes the claim that list is the only command needing git, which is now wrong for two of three flavors and would otherwise read as still true. Adds loomctl config, which says which context is current and where the credential came from without printing it, so that "my token is not being used" is answerable. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris
2026-09-07 16:57:39 -04:00
parent 104cbd050c
commit 73b3a97dce
4 changed files with 295 additions and 29 deletions
@@ -1,9 +1,12 @@
 // Package config reads the per-host settings loomctl needs to talk to a git host.
 //
-// The config is not only a secret. It is how you talk to a host at all, which is
-// why it is keyed by host rather than being a single token. It lives in the
-// user's home directory and never in a repository — see .loom/event-log.md,
-// "decided by fallback: where the credential lives".
+// The config is not only a secret. It is how you talk to a host at all — which
+// is why it is a set of named contexts with one current, and why a host's URL
+// shapes live here rather than in what a person types. Nobody should have to
+// know that gitea serves raw files from /raw/branch/<branch>/ to adopt a
+// document.
+//
+// It lives in the user's home directory and never in a repository.
 package config

 import (
@@ -16,15 +19,19 @@ import (
 	"strings"
 )

-// Host is what we know about one git host.
-type Host struct {
-	// Token is a read-only personal access token. It must not carry write
-	// scope: loomctl never writes over the network.
+// Context is one named way of talking to one host.
+type Context struct {
+	Host string `json:"host"`
+	// Flavor selects the URL shapes: gitea, github or gitlab. Empty means gitea.
+	Flavor string `json:"flavor,omitempty"`
+	// Token is read-only. loomctl never writes over the network, so a token it
+	// is given should not carry write scope.
 	Token string `json:"token,omitempty"`
 }

 type Config struct {
-	Hosts map[string]Host `json:"hosts"`
+	CurrentContext string             `json:"current-context"`
+	Contexts       map[string]Context `json:"contexts"`
 }

 // Path is where the config lives. Never inside a repository.
@@ -39,10 +46,10 @@ func Path() string {
 	return filepath.Join(home, ".config", "loomctl", "config.json")
 }

-// Load reads the config. A missing file is not an error: everything loomctl does
-// against a public repository works with no credential at all.
+// Load reads the config. A missing file is not an error: everything loomctl
+// does against a public repository works with no credential and no context.
 func Load() (*Config, error) {
-	c := &Config{Hosts: map[string]Host{}}
+	c := &Config{Contexts: map[string]Context{}}
 	p := Path()
 	if p == "" {
 		return c, nil
@@ -57,16 +64,31 @@ func Load() (*Config, error) {
 	if err := json.Unmarshal(b, c); err != nil {
 		return nil, fmt.Errorf("parsing %s: %w", p, err)
 	}
-	if c.Hosts == nil {
-		c.Hosts = map[string]Host{}
+	if c.Contexts == nil {
+		c.Contexts = map[string]Context{}
 	}
 	return c, nil
 }

+// Current returns the context a bare `owner/repo` is resolved against.
+func (c *Config) Current() (Context, error) {
+	if c.CurrentContext == "" {
+		return Context{}, fmt.Errorf("no current-context in %s — a bare owner/repo has no host to resolve against", Path())
+	}
+	ctx, ok := c.Contexts[c.CurrentContext]
+	if !ok {
+		return Context{}, fmt.Errorf("current-context %q is not defined in %s", c.CurrentContext, Path())
+	}
+	if ctx.Host == "" {
+		return Context{}, fmt.Errorf("context %q has no host", c.CurrentContext)
+	}
+	return ctx, nil
+}
+
 // TokenFor returns the token for a host, or "" if we have none.
 //
-// An environment variable wins over the file, so a token can be supplied for one
-// invocation without ever being written to disk.
+// An environment variable wins over the file, so a token can be supplied for
+// one invocation without ever being written to disk.
 func (c *Config) TokenFor(host string) string {
 	if t := os.Getenv("LOOMCTL_TOKEN_" + envKey(host)); t != "" {
 		return t
@@ -74,11 +96,48 @@ func (c *Config) TokenFor(host string) string {
 	if t := os.Getenv("LOOMCTL_TOKEN"); t != "" {
 		return t
 	}
-	return c.Hosts[host].Token
+	for _, ctx := range c.Contexts {
+		if ctx.Host == host && ctx.Token != "" {
+			return ctx.Token
+		}
+	}
+	return ""
 }

-// envKey turns a hostname into the shape an environment variable can carry.
 func envKey(host string) string {
 	r := strings.NewReplacer(".", "_", "-", "_", ":", "_")
 	return strings.ToUpper(r.Replace(host))
 }
+
+// RawURL builds the address a document is served from, given owner/repo and a
+// path inside the repository.
+//
+// For gitea the short form is deliberate: the host redirects it to the resolved
+// branch, so the URL recorded in the lock names a branch rather than a moving
+// ref, without anybody having to know which branch it was.
+func (c Context) RawURL(ownerRepo, pathInRepo string) (string, bool) {
+	switch c.flavor() {
+	case "gitea":
+		return fmt.Sprintf("https://%s/%s/raw/%s", c.Host, ownerRepo, pathInRepo), true
+	case "github":
+		return fmt.Sprintf("https://raw.githubusercontent.com/%s/%%s/%s", ownerRepo, pathInRepo), false
+	case "gitlab":
+		return fmt.Sprintf("https://%s/%s/-/raw/%%s/%s", c.Host, ownerRepo, pathInRepo), false
+	}
+	return "", false
+}
+
+// CloneURL is what git is pointed at.
+func (c Context) CloneURL(ownerRepo string) string {
+	return fmt.Sprintf("https://%s/%s.git", c.Host, ownerRepo)
+}
+
+func (c Context) flavor() string {
+	if c.Flavor == "" {
+		return "gitea"
+	}
+	return strings.ToLower(c.Flavor)
+}
+
+// Flavors names what RawURL understands, for error messages.
+func Flavors() string { return "gitea, github, gitlab" }
@@ -0,0 +1,86 @@
+package external
+
+import (
+	"bytes"
+	"fmt"
+	"io"
+	"os/exec"
+	"strings"
+
+	"git.hypertheory-labs.dev/loom/loom-cli/internal/config"
+)
+
+// AddByName adopts a document named the way `list` prints it, against the
+// current context.
+//
+//	loomctl external add loom/cart cart
+//
+// Nobody should have to type a host's raw-file route to adopt a document. The
+// route belongs to the host, so it lives in the context; the published
+// directory belongs to the convention, so it lives in the code; and what is
+// left — which repository, which document — is the only part a person knows.
+func AddByName(root, ownerRepo, name string, out io.Writer) error {
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+	ctx, err := cfg.Current()
+	if err != nil {
+		return err
+	}
+	if strings.Count(ownerRepo, "/") != 1 {
+		return fmt.Errorf("want owner/repo, got %q", ownerRepo)
+	}
+	if !strings.HasSuffix(name, ".md") {
+		name += ".md"
+	}
+
+	raw, resolved := ctx.RawURL(ownerRepo, PublishedDir+"/"+name)
+	if raw == "" {
+		return fmt.Errorf("context %q has flavor %q; known flavors are %s",
+			cfg.CurrentContext, ctx.Flavor, config.Flavors())
+	}
+	if !resolved {
+		// The lock must record a resolved URL. A short form that stays short
+		// follows whatever the default branch is at the time you ask, so a
+		// branch rename would report as a change in the document.
+		branch, err := defaultBranch(ctx.CloneURL(ownerRepo))
+		if err != nil {
+			return fmt.Errorf("resolving the default branch of %s: %w", ownerRepo, err)
+		}
+		raw = fmt.Sprintf(raw, branch)
+	}
+	return Add(root, raw, "", out)
+}
+
+// ListByName enumerates a repository named against the current context.
+func ListByName(ownerRepo string, out io.Writer) error {
+	cfg, err := config.Load()
+	if err != nil {
+		return err
+	}
+	ctx, err := cfg.Current()
+	if err != nil {
+		return err
+	}
+	return List(ctx.CloneURL(ownerRepo), out)
+}
+
+// defaultBranch asks the remote which branch HEAD points at, without cloning.
+//
+// Only hosts whose raw URLs do not redirect need this. Gitea resolves its own
+// short form, which is why adopting from gitea needs no git at all.
+func defaultBranch(cloneURL string) (string, error) {
+	cmd := exec.Command("git", "ls-remote", "--symref", cloneURL, "HEAD")
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout, cmd.Stderr = &stdout, &stderr
+	if err := cmd.Run(); err != nil {
+		return "", fmt.Errorf("%w: %s", err, strings.TrimSpace(stderr.String()))
+	}
+	for _, line := range strings.Split(stdout.String(), "\n") {
+		if after, ok := strings.CutPrefix(line, "ref: refs/heads/"); ok {
+			return strings.TrimSpace(strings.SplitN(after, "\t", 2)[0]), nil
+		}
+	}
+	return "", fmt.Errorf("no symref in git ls-remote output")
+}