diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..672ef64 --- /dev/null +++ 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`. diff --git a/README.md b/README.md index 963bd27..03ec433 100644 --- 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 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/.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/-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 ) 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/-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/-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 `_client/_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 +`_client/_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/.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/.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.