docs: add a demo GIF, correct the documented config location - #32
Merged
Conversation
The GIF records `domain check` through to a registered domain and a DNS record, against the SANDBOX API. docs/demo.tape is the vhs script that produces it, and carries the warnings that matter: log in before recording so no token prompt lands in a frame, confirm the active profile is sandbox first, and expect a re-record to fail at the availability check because the previous run really did register that name. Two things the first take got wrong, both now handled in the tape: `domain check` offers to register inline when interactive. The first recording typed the follow-up command into that prompt: the leading "n" of "namecom" answered it (printing "aborted") and the shell received "amecom domain register …" -> command not found. Verified by extracting frames rather than trusting a zero exit code, which vhs returns either way. That inline offer turns out to be the better demo anyway — the whole flow is one command, so the tape now uses it and the guided form is gone. PATH resolution picked the wrong binary. `which namecom` on a machine with a Homebrew install resolves to the released build, so the GIF would have shown an older version's output while looking current. The tape now puts the repository first on PATH in its hidden setup, and the header says to run `make build` first. `make install` does not help: go install names the binary after the module path, so it lands as `namecom-cli`. Separately, the documented config location was wrong on macOS and Windows. README said credentials live at ~/.config/namecom/config.yaml and the Path() doc comment called the location "XDG", but the code uses os.UserConfigDir, which is ~/Library/Application Support on darwin and %AppData% on windows. Only Linux matched the docs. This is not theoretical: it is why a search for existing credentials on a Mac came up empty while a working config sat in Library/Application Support the whole time. README now lists all three platforms and points at `auth status`, which prints the path in use; the doc comment explains why "XDG" was the wrong word. No behavior change — the code was always right.
The pauses were dead air. The sleeps were picked defensively after a take where a keystroke got eaten by a waiting prompt, and defensive turned out to mean roughly triple what the commands need. Measured against the sandbox rather than guessed again: domain check 0.46s (tape slept 5s) inline registration 2.86s (tape slept 6s) dns create 0.31s (tape slept 4s) Sleeps are now sized per step, and the tape records which number came from where so the next edit does not have to re-derive it. The distinction that matters is which sleeps are load-bearing. Two of them sit between an Enter and the next Type while a prompt is waiting for input; undersize those and the prompt eats the keystrokes, which is how an earlier take ended up running "amecom". Those keep real margin — 1.5s over a 0.46s call, 4.5s over a 2.86s one. The trailing sleep after the last command has nothing typed after it, so it is purely reading time and can be trimmed freely. The comments say so. Typing speed 60ms -> 40ms, which is most of the remaining saving: the two commands are 35 and 59 characters, so typing alone was 5.7s of the 24.2s. Re-recorded against driftwoodco.com, since the previous run really did register the old name. Verified the same way as before — extracted the final frame and looked at it, and confirmed the registration landed via the API — because vhs exits 0 whether or not the recording is coherent.
|
Codecov Report✅ All modified and coverable lines are covered by tests. 📢 Thoughts on this report? Let us know! |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds the demo GIF, recorded against the sandbox API, showing
domain checkthrough to a registered domain and a DNS record.docs/demo.tapeis the vhs script that produces it, and carries the warnings that matter: log in before recording so no token prompt lands in a frame, confirm the active profile is sandbox first, and expect a re-record to fail at the availability check — because the previous run really did register that name.Two things the first take got wrong
domain checkoffers to register inline when interactive. The first recording typed the follow-up command straight into that prompt: the leadingnofnamecomanswered it (printingaborted), and the shell gotamecom domain register …→command not found.I caught this by extracting frames and looking at them — vhs exits 0 either way, and the sandbox API confirmed no registration had happened. A green exit code proves nothing here.
That inline offer turns out to be the better demo anyway: the whole flow is one command. The tape now uses it, and the guided form is gone.
PATH resolution picked the wrong binary.
which namecomon a machine with a Homebrew install resolves to the released build — so the GIF would have shown an older version's output while looking current. The tape now puts the repo first on PATH in its hidden setup, and the header says to runmake buildfirst.make installdoesn't help:go installnames the binary after the module path, so it lands asnamecom-cli.The config path in the docs was wrong
Not theoretical — it's why a search for existing credentials on this Mac came up empty while a working config sat in
Library/Application Supportthe whole time.README.mdsaid credentials live at~/.config/namecom/config.yaml, andPath()'s doc comment called the location "XDG". But the code usesos.UserConfigDir():~/Library/Application Support/namecom/config.yaml$XDG_CONFIG_HOME/namecom/config.yaml, else~/.config/…%AppData%\namecom\config.yamlOnly Linux matched the docs. README now lists all three and points at
namecom auth status, which prints the path in use. The doc comment explains why "XDG" was the wrong word.No behavior change — the code was always right. Nobody's credentials need moving, which matters if other tools read the same file.
One thing to decide
The GIF shows
[sandbox]tags on the success lines (✓ [sandbox] Registered lunarcrate.com…). I left them in because they're truthful — no one should think this demo spent $17.99. If you'd rather the README demo not announce it's sandbox, say so and I'll restructure around commands that don't emit the tag.Test plan
vhs validate docs/demo.tapepassesdomain checkreportedpurchasable: truebefore andfalseaftergo build ./...,golangci-lint run,go test -race ./internal/config/all cleanos.UserConfigDir()behavior and againstauth statusoutput on this machine