lib/README.md

# lib

vernonkeenan Shared Libraries (go)

## Dependent Systems

The Gitea server <https://code.tnxs.net> must be up and running with admin access. It hosts world-readable
pull-mirrors of this repo at `vernonkeenan/lib` and `work/lib`.

## Release Procedure

As of 2026-07-12 (ADR-KV-014, DT-KV-004) this repo is `main` + `v*` tags — branch-per-version is retired, and
so is the old three-web-UI-plus-CLI manual ritual. Releasing is one command: `make release VERSION=vX.Y.Z`.

### Prerequisites

* All the sibling service repos (`auth`, `crm`, `stash`, `sf-gate`, `research`, `members`, `plex`) are cloned
  locally in adjacent directories — `regen` reads each one's `swagger/<service>-vernonkeenan.yaml`.
* [`gh`](https://cli.github.com/) installed and authenticated (`gh auth login`) with push access to
  `vernonkeenan/lib` — the release step calls `gh release create`.
* `GITEA_TOKEN` exported, set to a Gitea API token (Settings -> Applications on <https://code.tnxs.net>) with
  rights to trigger a mirror-sync on `vernonkeenan/lib` and `work/lib`. If unset, `make release` still tags,
  pushes, and publishes the GitHub release — it just skips the Gitea mirror-sync step with a loud warning, so
  the mirrors will lag until someone clicks Synchronize Now manually or reruns with the token set. (There is
  no existing Gitea/tnxs token variable defined anywhere in this workstation's env files today — `GITEA_TOKEN`
  is a new name, not a rename of something already in use.)

### 1. Regenerate the API clients (its own PR)

```bash
make regen
```

This installs the pinned go-swagger CLI (`SWAGGER_VERSION` in the `Makefile`, currently `v0.35.0` — bump
deliberately and update both places when you do), copies each sibling repo's `swagger/<service>-vernonkeenan.yaml`
into `./swagger` and `./swagger/external`, regenerates every client under `api/`, and rewrites the external
specs' scheme/host/path exactly as the old `make swagger` ritual did. It fails fast, before touching anything,
if any sibling spec is missing.

Review `git status`/`git diff`, commit, open a PR, and merge it to `main` like any other change — client regen
is not bundled into the release step itself. `make regen` runs a non-fatal `go build ./...` at the end as an
early warning; the real gate is CI on that PR.

**Known gap:** if any sibling spec has an operation with no top-level `tags:`, go-swagger routes it into a
fallback `operations` package whose import path in `<name>_client/<name>_client.go` doesn't respect
`--client-package` — reproduced across go-swagger v0.33.2 through v0.35.0 while building this tooling. As of
this writing that's `sf-gate-vernonkeenan.yaml`'s `PUT /researchprojectservices` (no `tags:`). Fix it at the
source (add a `tags:` entry in the `sf-gate` repo's spec) rather than hand-patching generated code, since the
next regen would just reintroduce it.

### 2. Cut the release (from a clean `main` checkout)

```bash
make release VERSION=v0.7.5
```

`scripts/release.sh` (invoked by the `release` target):

1. Validates `VERSION` is `vMAJOR.MINOR.PATCH` and strictly greater than the latest existing tag.
2. Requires you're on `main`, the tree is clean, and local `main` matches `origin/main` (no local-only commits).
3. Runs `go build ./...` and `go vet ./...` as a last sanity check.
4. Creates an annotated tag at HEAD, pushes it, and runs `gh release create` with generated notes.
5. POSTs to the Gitea mirror-sync API for `vernonkeenan/lib` and `work/lib` (skipped with a warning if
   `GITEA_TOKEN` is unset).

Use `make release-dry-run VERSION=v0.7.5` to run steps 1-3 and print what steps 4-5 would do, without tagging,
pushing, publishing, or syncing anything.

### 3. Downstream consumers

Update the `go.mod` line for `code.tnxs.net/vernonkeenan/lib` in each dependent project to the new tag, same
as before — that part of the old ritual is unchanged.