loomctl external: list, add, check — and its first run found two changed documents

Go, standard library only, with git shelled out for list alone. list enumerates a
publisher's .loom/published by partial clone and ls-tree; add fetches one document,
writes it under .loom/externals and records the resolved origin and the publisher's
ETag in .loom/externals/.locks; check asks conditionally and reports.

The first real run did what the tool exists for. All eight documents adopted by
hand before it existed reported unlocked — the tool refuses to invent a lock by
adopting whatever the remote currently serves, since that would assert the local
copy is the one being served, which is the thing it was about to check. Locking
them fetched two that had moved: bedrock/starting.md, which now says the worked
example is private and will not link to something you cannot fetch, and cart.md,
which went to v1.

cart v1 changes a role we cast: a cart is not committed, because a committed cart
grows a third file by itself — version control does not require anybody to ask, so
the two-file rule is never invoked — and because ignored, gone means gone. Adds
.loom/cart/ to .gitignore and supersedes the isolation entry rather than editing
it. osprey and marmalade are already in history and are left there: rewriting to
honour a rule adopted afterwards costs more than it buys.

Records the conflict this creates rather than settling it: the annotation protocol
here says commit before dissolving because git is the only archive, and an ignored
cart has no archive, so dissolving would destroy the annotations outright.

Credentials are read-only, per host, and passed to git through the environment
rather than argv, because argv is visible to every process on the machine.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_018UTxuSizozEA8yDitPuris

main.go

@@ -0,0 +1,102 @@
+// loomctl fetches documents this repository depends on, and finds out when they
+// change.
+//
+// It reports and never repairs. Everything it writes, it writes to the working
+// tree — committing and pushing are yours, because the consequences of a push
+// land on people a tool cannot experience.
+package main
+
+import (
+	"flag"
+	"fmt"
+	"os"
+
+	"git.hypertheory-labs.dev/loom/loom-cli/internal/external"
+)
+
+const usage = `loomctl — fetch what you depend on, and find out when it changed.
+
+  loomctl external list <repo-url>       what a repository publishes
+  loomctl external add <url> [--path p]  adopt one document and lock it
+  loomctl external check                 ask every publisher whether theirs moved
+
+check reports and does not fix. A changed document is a candidate, not a
+replacement, and somebody decides. It exits 0 whether or not anything moved:
+the report is the answer.
+
+Adopted documents live in .loom/externals/<host>/<owner>/<repo>/<name>.md, and
+their origins in .loom/externals/.locks. The path is for a person to read; the
+lock is what a machine uses, because the path does not round-trip to a URL.
+
+Credentials are read-only and per host, in ~/.config/loomctl/config.json or in
+LOOMCTL_TOKEN_<HOST>. loomctl never writes over the network, so a token it is
+given should never carry write scope.
+
+Requires git on PATH, for list only.
+`
+
+func main() {
+	if err := run(os.Args[1:]); err != nil {
+		fmt.Fprintln(os.Stderr, "loomctl: "+err.Error())
+		os.Exit(1)
+	}
+}
+
+func run(args []string) error {
+	if len(args) == 0 || args[0] == "-h" || args[0] == "--help" || args[0] == "help" {
+		fmt.Print(usage)
+		return nil
+	}
+	switch args[0] {
+	case "external":
+		return runExternal(args[1:])
+	default:
+		return fmt.Errorf("unknown command %q\n\n%s", args[0], usage)
+	}
+}
+
+func runExternal(args []string) error {
+	if len(args) == 0 {
+		return fmt.Errorf("external needs a subcommand: list, add, check")
+	}
+	switch args[0] {
+	case "list":
+		if len(args) != 2 {
+			return fmt.Errorf("usage: loomctl external list <repo-url>")
+		}
+		return external.List(args[1], os.Stdout)
+
+	case "add":
+		fs := flag.NewFlagSet("add", flag.ContinueOnError)
+		path := fs.String("path", "", "where to keep it, relative to .loom/externals (default: derived from the URL)")
+		if err := fs.Parse(args[1:]); err != nil {
+			return err
+		}
+		if fs.NArg() != 1 {
+			return fmt.Errorf("usage: loomctl external add <url> [--path p]")
+		}
+		root, err := root()
+		if err != nil {
+			return err
+		}
+		return external.Add(root, fs.Arg(0), *path, os.Stdout)
+
+	case "check":
+		root, err := root()
+		if err != nil {
+			return err
+		}
+		return external.Check(root, os.Stdout)
+
+	default:
+		return fmt.Errorf("unknown external subcommand %q", args[0])
+	}
+}
+
+func root() (string, error) {
+	wd, err := os.Getwd()
+	if err != nil {
+		return "", err
+	}
+	return external.FindRoot(wd)
+}