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.
• tools/scrub-scadalink-refs.sh — this scrub script (its substitution rules are the mapping).
• 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).
• docs/plans/2026-05-31-folder-repo-rename-scadabridge-plan.md — the implementation plan (its substitution table and embedded script are the mapping).

Completeness gate

Must return only the six carve-outs:

git grep -niE "scadalink" -- . \
  ':!tools/rename-to-scadabridge.sh' \
  ':!tools/scrub-scadalink-refs.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' \
  ':!docs/plans/2026-05-31-folder-repo-rename-scadabridge-plan.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 3a — Git-ignored deploy/ tree (added during implementation)

/deploy/ is git-ignored, so the git grep-based scrub script (and its completeness gate) structurally could not reach it — a gap surfaced by code review. The deploy/wonder-app-vd03/ production artifacts (install.ps1, appsettings.Central.json, appsettings.Site.json, RUNBOOK.md, ldap/glauth.cfg) still held old references that would break against the renamed binary: SCADALINK_* env vars, ScadaLink__* config keys, the "ScadaLink" config-section root, ScadaLink.Host.exe (now ZB.MOM.WW.ScadaBridge.Host.exe), scadalink.exe (CLI AssemblyName is scadabridge), and akka.tcp://scadalink@… seed URIs (the actor system name in code is scadabridge).

Per user decision, this tree was scrubbed by hand with the same substitution set, including the internal LDAP directory domain (dc=scadalink,dc=local → dc=scadabridge,dc=local and @scadalink.local → @scadabridge.local) applied in lockstep across both appsettings and glauth.cfg so LDAP login stays consistent. Because deploy/ is git-ignored, these edits are local-only / not committed — they fix the on-disk artifacts for the next wonder-app-vd03 deploy. Verified clean with grep -rniI scadalink deploy/.

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.