Merge pull request #6 from vernonkeenan/docs/readme-changelog-refresh

docs: refresh README.md and CHANGELOG.md to the constellation docs standard
2026-07-14 12:32:23 -07:00 · 2026-07-14 12:32:23 -07:00 · f26fd154b3
parent c818c034cd e74c58f952
commit f26fd154b3
2 changed files with 279 additions and 52 deletions
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@ -0,0 +1,135 @@
+# Changelog
+
+All notable changes to `go/lib` (`code.tnxs.net/vernonkeenan/lib`) are
+documented here. The format is based on
+[Keep a Changelog](https://keepachangelog.com/en/1.0.0/). Releases are
+`v*` git tags cut from `main` via `make release VERSION=vX.Y.Z`
+(main + PR flow, ADR-KV-014, which also governs KV-C6 lib
+distribution — see also ADR-KV-004/006 for the mesh-wide branching/release
+model). **Branch-per-version is retired** as of 2026-07-12: `main` was
+created from the `v0.7.4` tip and is now the only long-lived branch; the
+~70 legacy `vX.Y.Z` branches still present in the repo are historical
+artifacts of the old convention, not active release refs. Every section
+below corresponds to a real git tag in this repo's history (only `v0.7.5`,
+cut by the new `make release` script, is an annotated tag — the 71 tags
+before it are lightweight, a holdover from the old ritual); no tag, date,
+or PR number is invented.
+
+## [Unreleased]
+
+No commits on `main` since `v0.7.5` — HEAD is at the `v0.7.5` tag.
+
+## [v0.7.5] — 2026-07-12
+
+First release cut with the new `make release` scripted ritual (ADR-KV-014),
+and the first release with CI behind it.
+
+### Added
+- First-ever CI for `lib`: `go build/vet/test ./...` job plus a gitleaks
+  secret-scan job on every push/PR, closing out the last un-covered repo in
+  the 12-repo Go-mesh test-harness program (ci/first-ci-gitleaks, PR #1)
+- Table-driven unit tests for `app/service-helpers.go`'s pure helpers
+  (test/app-service-helpers, PR #2)
+
+### Changed
+- Replaced the manual three-web-UI-plus-CLI release ritual with
+  `scripts/release.sh` / `make release` + `make release-dry-run`
+  (feat/scripted-release, ADR-KV-014, PR #3)
+- Regenerated all sibling clients under `api/` with go-swagger v0.35.0
+  (feat/regen-clients-processor-token, PR #5)
+
+### Fixed
+- `PaymentMethod` swagger def updated for the `card_*` → `processor_token`
+  migration (PR #4)
+
+## [v0.7.4] — 2025-05-27
+
+### Added
+- Generated session-management API client and models
+
+## [v0.7.3] — 2025-05-01
+
+### Changed
+- Refactored swagger defs (`Address`, `CompanyProduct`, `CompanyService`,
+  `Factor`, `FinancialStatement`, `Industry`, `IndustryCompany`,
+  `IndustryProduct`, `IndustryService`, `Observation`, `Topic`) to use
+  external `$ref` component defs instead of inline definitions
+
+## [v0.7.2] — 2025-04-30
+
+### Changed
+- Replaced `AccountID` with `CompanyID` in `GetIndustryCompaniesParams` and
+  the related swagger definitions
+
+## [v0.7.1] — 2025-04-29
+
+No code changes — retag of the same commit as `v0.7.0`/`v0.6.7`.
+
+## [v0.7.0] — 2025-04-29
+
+No code changes — retag of the same commit as `v0.6.7`.
+
+## [v0.6.7] — 2025-04-29
+
+### Added
+- Enrichment fields on `Account`, `CompanyProduct`, and `CompanyService`
+  models
+
+## [v0.6.6] — 2025-04-29
+
+### Changed
+- General code-structure refactor for readability/maintainability
+
+## [v0.6.5] — 2024-06-30
+
+### Added
+- `Channels` field on `Account` and `Contact` models
+
+## [v0.6.4] — 2024-06-29
+
+### Added
+- `AppExchange` URL field on `CompanyProduct` model
+
+## [v0.6.3] — 2024-06-28
+
+### Added
+- `AppExchange` URL field on `CompanyProduct` model
+
+## [v0.6.2] — 2024-06-28
+
+### Added
+- `AppExchange` URL field on `Account` and `Company` models
+
+## [v0.6.1] — 2024-06-27
+
+### Added
+- `FullDescription` field on `Account` model
+
+## [v0.6.0] — 2024-01-22
+
+### Added
+- `FullDescription` field on `Industry` model
+
+## Pre-v0.6.0 history (v0.0.1 – v0.5.15, 2021-07-30 – 2023-08-25)
+
+58 tags predate `v0.6.0`, from `lib`'s original scaffolding through the
+last patch release before the year-and-a-half gap to `v0.6.0`. Coarse
+summary by theme (no PR numbers — this history predates the PR-merge
+convention):
+
+- **2021 (v0.0.1–v0.1.9):** Initial `app` package scaffolding — config,
+  logger, MySQL, and Salesforce (`go-force`) init helpers; first
+  go-swagger client generation against the estate's early services
+  (including a since-retired Telnexus/Kazoo-era client, still visible as
+  vendored specs under `swagger/`); early devops endpoint moves and
+  `/etc` config-path changes.
+- **2022 (v0.1.2–v0.4.9):** Buildout of `sf-gate` and `members` swagger
+  clients; schema cleanups; `research` and `plex` microservices added to
+  the platform; user/session/batch-endpoint additions across `sf-gate` and
+  `members`.
+- **2023 H1 (v0.5.0–v0.5.8):** `members` feature buildout — prompts and
+  prompt answers, favorites, documents, event categories, external
+  accounts — plus a research-domain refactor.
+- **2023 H2 (v0.5.9–v0.5.15):** Steady patch releases stabilizing the
+  prompts/members surface; `v0.5.15` (2023-08-25) is the last tag before
+  the gap to `v0.6.0`.
--- a/README.md
+++ b/README.md
@ -1,72 +1,164 @@
-# lib
+# go/lib — Shared Go library for the Keenan Vision service mesh

-vernonkeenan Shared Libraries (go)
+`go/lib` (module `code.tnxs.net/vernonkeenan/lib`) is the shared toolchain
+every Go microservice in the Keenan Vision mesh pins in its `go.mod`. It is
+not a service — it ships no server, no Dockerfile, no compose entry — it is
+a library `app` package (`InitConfig`/`InitDB`/`InitForce`, config
+accessors, zap logging, Prometheus/CORS middleware, generic marshal
+helpers) plus a set of go-swagger–generated typed HTTP clients (`api/`)
+against the sibling services' own swagger specs. Because every mesh service
+pins the same module, a `lib` bump is a constellation-wide rebuild (KV-C6a).

-## Dependent Systems
+## Constellation context

-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`.
+- Toolchain member of the Keenan Vision Go mesh governed by `../../kv-meta/`
+  (see `../../kv-meta/CONSTELLATION.md` §1.3, contract KV-C6). Not a
+  deployed service: no swagger server, no port, no entry in the
+  `docker/kvweb` compose on pluto.
+- KV-C6a: every mesh service (`auth`, `cache`, `crm`, `members`, `pdf`,
+  `plex`, `render`, `research`, `sf-gate`, `stash`) pins an explicit
+  `code.tnxs.net/vernonkeenan/lib` tag in its own `go.mod`; consumption is a
+  per-consumer `go.mod` bump, never automatic.
+- Distribution is via a world-readable Gitea pull-mirror at
+  `code.tnxs.net/vernonkeenan/lib` (and `work/lib`), enabling
+  credential-free `go get code.tnxs.net/vernonkeenan/lib@vX.Y.Z` from
+  Docker/CI/dev boxes even though the GitHub repo itself is private
+  (ADR-KV-014). Everything committed here is treated as **published,
+  permanently** — a gitleaks CI gate makes leaking a secret a build
+  failure, not a review nit.
+- CI (self-hosted runner, `go build/vet/test ./...` + gitleaks on every
+  push/PR) landed 2026-07-12 as `lib`'s first-ever pipeline (ADR-KV-014) —
+  `lib` was the only one of the 12 Go-roster repos with no CI at all going
+  into the 2026-07-12 test-harness audit, so this closes out that gap. The
+  `test` job is `lib`'s instance of the mesh-wide unit-test-gate program
+  (ADR-KV-009, amended by ADR-KV-013, which scopes `lib` as one of its 12
+  governed repos); the `gitleaks` job is ADR-KV-014's public-mirror
+  secret-scan gate, specific to `lib` because it's the one repo mirrored
+  world-readable.
+- `api/` also acts as `lib`'s own internal client of the mesh: `app/auth.go`'s
+  `CheckAPIUser` calls `auth`'s generated client to validate an API key, so
+  `lib` is simultaneously a library *and* a consumer of one sibling service.

-## Release Procedure
+## Package surface

-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`.
+| Path | What it is |
+|---|---|
+| `app/root.go` | `InitConfig(systemName, level)` — loads `/etc/vernonkeenan/<systemName>.yaml` via viper, one-time init guard |
+| `app/config.go` | `Configuration` struct + `Get*`/`Is*` accessors (DBMS, DSN, log level, metrics, service accounts, workers, email, chunk/cache sizing) |
+| `app/mysql.go` | `InitDB()` — opens `MyDB *sql.DB` against the configured MySQL DSN |
+| `app/force.go` | `InitForce(serviceAccountName)` — opens a Salesforce `go-force` API connection from a configured service account |
+| `app/auth.go` | `CheckAPIUser(token)` — validates an API key against `auth`'s generated client |
+| `app/prometheus.go` | `SetupPrometheusHandler` — CORS + request-count/duration middleware |
+| `app/service-helpers.go` | Pointer helpers (`String`/`Bool`/`Int64`/…), `GetFieldsAndValues` reflection helper (unit-tested) |
+| `app/user.go`, `user-helpers.go`, `tenantuser.go`, `userrole.go`, `address.go` | First-class domain structs + swagger marshal/unmarshal helpers shared by consumers |
+| `app/logger/logger.go` | Thin `zap.SugaredLogger` wrapper (`New(level)`, level constants) |
+| `api/{auth,crm,members,plex,research,sfgate,stash}/` | go-swagger–generated typed clients + models, one directory per sibling service, regenerated from that service's own spec |
+| `swagger/*.yaml`, `swagger/defs/`, `swagger/external/` | Copies of each sibling service's spec (the KV-C6b spec-copy problem — no sync mechanism besides `make regen`), shared component defs, and host/path-rewritten copies for external doc publishing; also carries legacy vendored Kazoo/Clerk specs from `lib`'s pre-mesh history |

-### 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)
+## Build, run, test

 ```bash
-make regen
+go build ./...
+go vet ./...
+go test ./...          # table-driven unit tests today: app/service-helpers.go pure helpers
+make install-swagger    # install the pinned go-swagger CLI (SWAGGER_VERSION in Makefile)
+make regen               # aka `make swagger` — regenerate api/ from sibling specs
+make release VERSION=vX.Y.Z
+make release-dry-run VERSION=vX.Y.Z
 ```

-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.
+`go test ./...` is CI-gating on every push and PR (ADR-KV-009/013), same as
+the rest of the mesh; `lib` is a library so there is nothing to "run."

-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.
+`make regen` requires the sibling repos `auth`, `crm`, `stash`, `sf-gate`,
+`research`, `members`, `plex` cloned adjacently — it reads each one's
+`swagger/<service>-vernonkeenan.yaml`, copies it into `./swagger` and
+`./swagger/external`, and regenerates every client under `api/`, rewriting
+the external specs' scheme/host/path the same way 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 never bundled into the
+release step; `make regen` runs a non-fatal `go build ./...` at the end as
+an early warning, but 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
+**Known gap (resolved for the current spec set, but can recur):** 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. The one instance found, `sf-gate-vernonkeenan.yaml`'s `PUT
+/researchprojectservices` (no `tags:`), was fixed at the source (sf-gate
+#3 added the missing `tags:` entry) and regenerated clean in the v0.7.5
+`feat/regen-clients-processor-token` PR — `api/sfgate` has no fallback
+`operations` package today. If a future sibling spec change reintroduces an
+untagged operation, `make regen`'s non-fatal `go build ./...` step will
+fail with this same signature; fix it at the source (add a `tags:` entry in
+that service'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)
+## Configuration

-```bash
-make release VERSION=v0.7.5
-```
+`lib` reads no config file of its own. `app.InitConfig(systemName, level)`
+loads config **on behalf of the calling service**: viper reads
+`/etc/vernonkeenan/<systemName>.yaml` (YAML), with environment-variable
+overrides via prefix `VERNONKEENAN_` (`.` replaced by `_` in key names),
+unmarshalled into `app.Configuration` — `AppName`, `BackendID`,
+`DBMS`/`DBMSHost`/`DBMSName`/`DBMSUsername`/`DBMSPassword`, `DSN`,
+`Environment`, `LogLevel`, `GelfURI`, `Metrics` (address/enabled),
+`ServiceAccounts` (a map of external-system credentials, e.g. the `auth`
+service account `CheckAPIUser` reads its own API key from), `Workers`,
+`Email`, `CacheSizes`/`Chunks`. The concrete `/etc/vernonkeenan/<name>.yaml`
+file lives on each deploy host, not in this repo — see the calling
+service's own README for its file name and required keys.

-`scripts/release.sh` (invoked by the `release` target):
+## Versioning & pinning contract (KV-C6a)

-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).
+- **Module:** `code.tnxs.net/vernonkeenan/lib`, fetched via the Gitea
+  anonymous mirror (not GitHub directly — the GitHub repo is private).
+- **Pin, don't float:** every consumer pins an explicit `vX.Y.Z` tag in its
+  `go.mod`. Bumping the pin is a normal PR in the consumer repo; there is no
+  auto-bump mechanism.
+- **Release is one command:** `make release VERSION=vX.Y.Z`
+  (`scripts/release.sh`) from a clean `main` checkout that matches
+  `origin/main`:
+  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 — there is
+     no existing Gitea/tnxs token variable defined anywhere on this
+     workstation today; `GITEA_TOKEN` is a new name, not a rename of
+     something already in use).

-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.
+  `make release-dry-run VERSION=vX.Y.Z` runs steps 1-3 and prints what
+  steps 4-5 would do, without tagging, pushing, publishing, or syncing
+  anything.
+- **A `lib` bump is constellation-wide:** any breaking change to
+  `app.Configuration`, `InitConfig`/`InitDB`/`InitForce`, or a generated
+  client's shape ripples to every pinned service on its next `go.mod` bump.
+- **Branch-per-version is retired** (ADR-KV-014, 2026-07-12): `lib` moved
+  to main + `v*` tags, replacing the old three-web-UI-plus-CLI manual
+  release ritual. ~70 legacy `vX.Y.Z` branches (one per pre-migration
+  release; `git branch --list 'v*'`) remain in the repo as historical
+  artifacts of the old convention, not the active release mechanism.
+- **Prerequisites for a release:** the sibling repos (for `make regen`)
+  cloned adjacently; [`gh`](https://cli.github.com/) authenticated with
+  push access to `vernonkeenan/lib`; `GITEA_TOKEN` exported for the
+  mirror-sync step (optional — see above).

-### 3. Downstream consumers
+## Release & deploy

-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.
+`main` + PR flow: land changes on `main` via PR (CI runs build/vet/test +
+gitleaks on the PR and on push to `main`), then cut a release with `make
+release VERSION=vX.Y.Z`, which tags `main`, publishes a GitHub release, and
+triggers the Gitea mirror-sync. Unlike the deployed mesh services, `lib` has
+**no Dockerfile, no container image, and no deploy step** — it is never
+built into `hub.tnxs.net` and never rolled out via the `docker/kvweb`
+compose on pluto. "Release" means "a new tag other repos can pin," full
+stop; downstream rollout happens when each consumer bumps its own `go.mod`
+line for `code.tnxs.net/vernonkeenan/lib` to the new tag and goes through
+its own release/deploy path.