Skip to content

Polish the pkg/ public API ahead of the v2 freeze - #39

Merged
polymorcodeus merged 3 commits into
mainfrom
api-health
Sep 27, 2026
Merged

polymorcodeus merged 3 commits into
mainfrom
api-health

Conversation

@polymorcodeus

Copy link
Copy Markdown
Owner

Summary

Adds sentinel-error contracts, consistent naming, and safer constructors across the pkg/ public API, and moves TUI success-screen rendering out of the domain package into a dumb formatter. Completes the pkg/ API polish ahead of the v2 freeze.

What's new

  • Sentinel errors - book.ErrDuplicateURL, book.ErrURLTrashed, and book.ErrTitleRequired in pkg/book, plus web.ErrNotFound in pkg/web, all package-prefixed and matchable with errors.Is; the domain package no longer embeds CLI remediation text.
  • CLI remediation - trashed-URL collisions print the exact book mark restore --id <catalog_id> command, unresolvable titles end with provide --title, and the 404 quip moves from pkg/web into the CLI layer where colloquial output belongs.
  • Naming alignment - Mark.Name is now Mark.Title, Mark.UpdateMark is Mark.Update, and the stuttering CollectionsNames/MarksNames are CollectionNames/MarkNames.
  • Renderer decoupling - the Templatable interface is gone from pkg/book; each completed TUI screen builds a viewData and the renderer in internal/model is a dumb formatter, with the shelf/collection parent section rendered above mark screens.
  • Shelf-name validation - NewShelf and ValidateNewShelfName share validateShelfName, which rejects empty, whitespace-padded, control-character, path-separator, Windows-reserved, and ./.. names.
  • Finder guarantees - SoftDeletedByID and Index.Collection wire Shelf/Collection back-pointers like the other finders, and Mark.FullDetail renders empty fields instead of panicking on unwired marks.

Behavior changes / guardrails

  • MarshalCatalog returns an error for empty or unknown formats instead of nil.
  • WebsiteTitle wraps ErrNotFound on HTTP 404 and reports other statuses as fetch title: unexpected status N; HTTP 403 and empty <title> still return ErrTitleUnavailable.
  • Padded shelf names are rejected because ShelfPath trims and underscorifies names, so a padded name would collide with its trimmed form on disk.
  • EnsureConfig failure names the remedy again: set --confirm to create it.
  • Library consumers on the v1.6.1 pkg/ API need to follow the renames; the CLI surface (commands, flags, TOML schema) is unchanged.

Testing

  • New render tests in internal/model/tea_test.go pin section order, empty-section skipping, and the parent-above-mark layout.
  • TestWebsiteError, TestUniqueURLError, and TestTitleError cover the CLI remediation branches and errors.Is chain preservation.
  • Expanded shelf-name validation cases (padded, control characters, path tokens) and sentinel assertions in the pkg/book and pkg/web suites.
  • make check runs fmt, vet, lint, and tests; all green.

@polymorcodeus
polymorcodeus merged commit 79277dc into main Sep 27, 2026
4 checks passed
@polymorcodeus
polymorcodeus deleted the api-health branch September 27, 2026 15:39
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant