From e01f3bdabe838296fa144bc4edb8f216b0242da2 Mon Sep 17 00:00:00 2001 From: Joseph Doherty Date: Sun, 31 May 2026 21:32:07 -0400 Subject: [PATCH] =?UTF-8?q?docs:=20add=20folder/repo=20rename=20design=20d?= =?UTF-8?q?oc=20(scadalink-design=20=E2=86=92=20ScadaBridge)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- ...1-folder-repo-rename-scadabridge-design.md | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md diff --git a/docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md b/docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md new file mode 100644 index 00000000..b4a711d7 --- /dev/null +++ b/docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md @@ -0,0 +1,113 @@ +# Folder + Repo Rename `scadalink-design` → `ScadaBridge` — Design + +**Date:** 2026-05-31 +**Status:** Approved, ready for implementation planning +**Scope:** Rename the repo folder `~/Desktop/scadalink-design` → `~/Desktop/ScadaBridge`, rename the Gitea repository `dohertj2/scadalink-design` → `dohertj2/ScadaBridge`, and scrub every residual `scadalink`/`ScadaLink` reference inside the repo to its `ScadaBridge` equivalent. + +This reverses the earlier decision (in `2026-05-28-scadabridge-rename-design.md`) to leave the folder name diverged from the product name, and completes the residual reference scrub that the earlier effort deliberately left out (the `SCADALINK_*` runtime env vars and the production deploy script). + +## Context + +The product was already renamed from "ScadaLink" to "ScadaBridge" in the `2026-05-28` effort: the solution (`ZB.MOM.WW.ScadaBridge.slnx`), all `src/`/`tests/` projects, namespaces, MS SQL databases, docker containers/network/image, the CLI config dir (`~/.scadabridge/`), `CLAUDE.md`, and `README.md` already say ScadaBridge. What remained untouched were the runtime environment variables (`SCADALINK_*`), one `.NET` config-key convention (`ScadaLink__*`), a stale assembly-name reference in the production deploy script, a few cosmetic identifiers, and historical doc/code-review mentions. + +## Decisions + +| # | Decision | Selected option | +|---|----------|-----------------| +| 1 | Folder-name collision (`~/Desktop/ScadaBridge` already exists — a separate, older, non-git project) | Rename the existing folder aside to `~/Desktop/ScadaBridge-old` (non-destructive); nothing deleted | +| 2 | Reference scope | Full scrub — env vars, config keys, assembly name, SQL login, cosmetic identifiers, and historical docs/code-reviews | +| 3 | Env-var cutover style | Hard cutover (no backward-compat fallback); dev stack is redeployed | +| 4 | New env-var/identifier prefix | Short product name `SCADABRIDGE_` / `ScadaBridge__` (no `ZB.MOM.WW`), consistent with existing runtime artifacts (`scadabridge-*` containers, `~/.scadabridge/`) | +| 5 | Gitea server-side rename | User renames via the Gitea web UI; Claude updates the local `origin` remote and verifies | +| 6 | Execution mechanism | Scripted multi-pass `sed` over `git ls-files`, most-specific-first, with a completeness-gate `git grep` | +| 7 | Migration records | Carved out of the scrub so their before→after meaning survives (see §2) | + +## Section 1 — Order of operations + +1. **Safety check** — confirm the working tree is clean (commit/stash WIP first); record the current branch. +2. **Clear the collision** — `mv ~/Desktop/ScadaBridge ~/Desktop/ScadaBridge-old`. +3. **Move the folder** — `mv ~/Desktop/scadalink-design ~/Desktop/ScadaBridge`. Plain OS move; git tracks contents, not the repo-root directory name, so history is untouched. `.idea/` and `.claude/` ride along inside the moved folder. +4. **Scrub references** — run the scripted multi-pass `sed` (§2). +5. **Build + test gate** — `dotnet build ZB.MOM.WW.ScadaBridge.slnx`, unit tests, completeness `git grep`. +6. **Commit** (§5). +7. **Runtime cutover** — rebuild + redeploy docker so running containers read the new env-var names (§4). No DB changes. +8. **Gitea rename** — user web-UI rename; Claude updates local `origin` + verifies fetch/push. +9. **Write/commit this design doc** (already produced by the brainstorm). + +## Section 2 — The scrub + +A new `tools/scrub-scadalink-refs.sh` operating on `git ls-files -z | xargs -0 sed -i ''` (skips `.git/` and `bin/obj` build artifacts), applied **most-specific-first** so a broad rule cannot double-replace an earlier result: + +``` +1. ScadaLink.Host.exe → ZB.MOM.WW.ScadaBridge.Host.exe (stale assembly name, deploy/install.ps1) +2. ScadaLink__ → ScadaBridge__ (.NET hierarchical config keys, deploy/install.ps1) +3. SCADALINK_ → SCADABRIDGE_ (13 runtime env vars) +4. scadaLinkVersion → scadaBridgeVersion (Transport param/local var — cosmetic) +5. scadalink_app → scadabridge_app (SQL login) +6. ScadaLink → ScadaBridge (residual) +7. scadalink → scadabridge (residual) +``` + +### The 13 `SCADALINK_*` env vars in scope + +`SCADALINK_CONFIG`, `SCADALINK_FORMAT`, `SCADALINK_USERNAME`, `SCADALINK_PASSWORD`, `SCADALINK_MANAGEMENT_URL`, `SCADALINK_CONFIGURATIONDB_CONNECTION_STRING`, `SCADALINK_DESIGNTIME_CONNECTIONSTRING`, `SCADALINK_MSSQL_TEST_CONN`, `SCADALINK_PLAYWRIGHT_DB`, `SCADALINK_JWT_SIGNING_KEY`, `SCADALINK_LDAP_SERVICE_ACCOUNT_PASSWORD`, `SCADALINK_AUDIT_FILTER_4KB_P95_US`, `SCADALINK_AUDIT_FILTER_RAW_P95_US`. + +They are read by code (`Environment.GetEnvironmentVariable(...)` in Host/CLI/tests) **and** set by `docker/docker-compose.yml`, `docker-env2/docker-compose.yml`, `appsettings.Central.json` (`${...}` placeholders), and `deploy/wonder-app-vd03/install.ps1`. All sites change together in one pass. + +### Carved out (excluded — migration records) + +Scrubbing these would destroy their before→after meaning: + +- `tools/rename-to-scadabridge.sh` — prior rename tooling. +- `docker/rename-databases.sh` — DB rename helper (`ALTER DATABASE ScadaLinkConfig MODIFY NAME = ScadaBridgeConfig`, `ALTER LOGIN [scadalink_app] ...`). +- `docs/plans/2026-05-28-scadabridge-rename-design.md` — prior rename design. +- `docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md` — **this document** (also a before→after record). + +### Completeness gate + +Must return only the four carve-outs: + +```bash +git grep -niE "scadalink" -- . \ + ':!tools/rename-to-scadabridge.sh' \ + ':!docker/rename-databases.sh' \ + ':!docs/plans/2026-05-28-scadabridge-rename-design.md' \ + ':!docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md' +``` + +## Section 3 — Collision folder + +The existing `~/Desktop/ScadaBridge` (non-git, older project containing `akka.md`, `netstd.md`, `CommentChecker`, its own `src/`/`tests/`/`tsdb/`) is renamed to `~/Desktop/ScadaBridge-old`. Nothing is deleted. If the user later confirms it is dead, they delete it themselves. + +## Section 4 — Runtime cutover + +Hard cutover. After the scrub, rebuild the image and `docker compose up -d --force-recreate` on both clusters (`docker/`, `docker-env2/`) so the running containers read `SCADABRIDGE_*`. **No database rename or wipe** — database names were already migrated in the `2026-05-28` effort and are unchanged here. If no stack is currently running, the cutover applies on the next `bash docker/deploy.sh`. + +## Section 5 — Commits + +Two staged commits on the current branch, `git diff`-reviewed between them: + +1. `refactor: scrub residual ScadaLink refs → ScadaBridge (env vars, config keys, assembly name, SQL login)` — the scrub + any build/test fixes. +2. `docs: add folder/repo rename design doc` — this document. + +The folder `mv` and the Gitea rename are not git commits. + +## Section 6 — Risks & rollback + +- **Missed env var** → silent config-read failure. Mitigated by the completeness-gate grep + build/test + redeploy smoke check. +- **Folder move breaks editor/Claude session paths** — the concern that drove the `2026-05-28` "don't rename the folder" decision; accepted by the user this time. +- **Gitea redirect** — Gitea auto-redirects the old repo URL after rename, so pushes do not hard-fail even before the remote is updated; `origin` is updated regardless. +- **Rollback** — pre-scrub state is the last git commit (`git reset --hard`); folder moves reverse with `mv`. + +## Section 7 — Verification + +- `dotnet build ZB.MOM.WW.ScadaBridge.slnx` clean; unit tests green. +- Completeness grep returns only the four carve-outs. +- `git remote -v` shows `https://gitea.dohertylan.com/dohertj2/ScadaBridge.git`; `git ls-remote origin` / `git fetch` succeeds. +- (If a stack is running) CLI smoke against the redeployed cluster. + +## Out of scope + +- Renaming the MS SQL databases, docker containers/network, or CLI config dir — already done in the `2026-05-28` effort. +- Sister repos `~/Desktop/MxAccessGateway`, `~/Desktop/OtOpcUa`. +- Deleting `~/Desktop/ScadaBridge-old` — left to the user.