bridge: add GATEWAY_* aliases with SLACK_* fallback (phase 2)

[benvinegar]

Summary

Implements phase 2 of the Gateway bridge rename by introducing backward-compatible env var aliases:

• adds GATEWAY_* aliases (preferred) with SLACK_* fallback (legacy)
• applies alias precedence (GATEWAY_* wins when both are set)
• emits non-breaking deprecation guidance when legacy names are used

What changed

Runtime alias resolution

• Added slack-bridge/env-aliases.mjs
• Wired into:
  • slack-bridge/bridge.mjs
  • slack-bridge/broker-bridge.mjs

Startup/runtime compatibility

• pi/skills/control-agent/startup-pi.sh now detects broker/socket config via either alias family
• pi/extensions/sentry-monitor.ts accepts GATEWAY_BOT_TOKEN with SLACK_BOT_TOKEN fallback
• Updated operator scripts to recognize alias config:
  • bin/doctor.sh
  • bin/security-audit.sh
  • bin/lib/baudbot-runtime.sh
  • install.sh
  • bin/config.sh (allowlist validation wording)

Docs/schema

• Updated .env.schema with preferred GATEWAY_* + legacy SLACK_* entries
• Updated CONFIGURATION.md with precedence, migration wording, and updated example .env

Tests

• Added slack-bridge/env-aliases.test.mjs covering fallback + precedence
• Included alias test in test/legacy-node-tests.test.mjs and bin/test.sh
• Updated allowlist messaging expectations in:
  • bin/security-audit.test.sh
  • test/security-audit.test.mjs

Validation

• npm run lint
• npm test
• npm run typecheck
• bash bin/test.sh js
• bash bin/test.sh shell

(One pre-existing non-blocking Biome warning remains in slack-bridge/broker-bridge.mjs for an unused catch variable.)

[greptile-apps]

Greptile Summary

Completes phase 2 of the Gateway bridge rename by introducing backward-compatible environment variable aliases. The implementation adds GATEWAY_* variables (preferred) with SLACK_* fallback (legacy), applying proper precedence rules where GATEWAY_* wins when both are set.

Key changes:

• Added slack-bridge/env-aliases.mjs with resolution logic that normalizes both alias families to canonical SLACK_* keys used throughout the codebase
• Integrated alias resolution into both bridge.mjs (Socket Mode) and broker-bridge.mjs (broker mode), emitting non-breaking deprecation warnings
• Updated shell scripts (startup-pi.sh, doctor.sh, security-audit.sh, config.sh) to detect configuration using either alias family via bash parameter expansion
• Enhanced sentry-monitor.ts to accept GATEWAY_BOT_TOKEN with SLACK_BOT_TOKEN fallback
• Comprehensive documentation updates in .env.schema and CONFIGURATION.md with migration guidance
• Full test coverage including unit tests for alias resolution and updated integration test expectations

Design highlights:

• Transparent aliasing: the resolution layer converts everything to SLACK_* keys, so the rest of the codebase requires no changes
• Smart conflict detection: warns only when both aliases are set to different values
• Consolidated legacy fallback warnings: single message listing all legacy vars in use
• Proper string conversion and empty value handling

The implementation is well-tested, thoroughly documented, and maintains full backward compatibility while encouraging migration to the new naming convention.

Confidence Score: 5/5

• This PR is safe to merge with no blocking issues
• The implementation is comprehensive, well-tested, and maintains full backward compatibility. The alias resolution logic is straightforward and correct, with proper precedence handling and edge case coverage. All integration points (bridge files, shell scripts, TypeScript extensions) are updated consistently. Test coverage includes unit tests for the core logic and updated expectations for integration tests. Documentation is thorough and provides clear migration guidance.
• No files require special attention

Important Files Changed

Filename	Overview
slack-bridge/env-aliases.mjs	Implements backward-compatible env alias resolution with proper precedence (GATEWAY_* preferred, SLACK_* fallback) and deprecation warnings
slack-bridge/env-aliases.test.mjs	Comprehensive test coverage for alias fallback, precedence, conflict detection, and env mutation behavior
slack-bridge/bridge.mjs	Applies env aliases at startup, emits warnings, and updates error messages to reference both alias families
slack-bridge/broker-bridge.mjs	Integrates alias resolution into broker mode with updated validation and warning messages for both naming conventions
pi/skills/control-agent/startup-pi.sh	Detects broker/socket configuration using fallback syntax to check both GATEWAY_* and SLACK_* variables
bin/doctor.sh	Enhanced validation to check for either GATEWAY_* or SLACK_* variables with proper precedence logic
.env.schema	Documented both GATEWAY_* (preferred) and SLACK_* (legacy) environment variables with clear migration guidance
CONFIGURATION.md	Updated with precedence rules, migration guidance, and revised example .env using GATEWAY_* naming

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Bridge Startup] --> B[applyGatewayEnvAliases]
    B --> C{Check each alias pair}
    C --> D{GATEWAY_* set?}
    D -->|Yes| E[Use GATEWAY_* value]
    D -->|No| F{SLACK_* set?}
    F -->|Yes| G[Use SLACK_* value<br/>+ emit deprecation warning]
    F -->|No| H[Skip - not configured]
    E --> I{SLACK_* also set<br/>with different value?}
    I -->|Yes| J[Emit conflict warning]
    I -->|No| K[No conflict]
    J --> L[Set process.env SLACK_* key]
    K --> L
    G --> L
    H --> M[Continue]
    L --> M
    M --> N{More pairs?}
    N -->|Yes| C
    N -->|No| O[Bridge continues startup<br/>using SLACK_* keys]

Loading

_{Last reviewed commit: 01a2edc}