ScadaBridge/docs/plans/2026-05-31-folder-repo-rename-scadabridge-design.md

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:

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.