feat: secret referencing ux and autocompletion

[rohan-chaturvedi]

Summary

• Adds inline autocomplete when typing ${ in secret value inputs, with progressive suggestions for local keys, cross-environment references (${env.KEY}), and cross-app references (${app::env.KEY})
• Adds syntax highlighting for secret reference tokens (${}) with color-coded segments for apps, environments, folders, and keys
• Validates all secret references on save and shows a warning dialog for broken references, allowing users to fix them or proceed anyway
• Fixes Autocomplete dropdown for secret referencing #267

🖼️ Screenshots or Demo

Screencast.From.2026-02-26.16-04-58.mp4

Details

Secret values in Phase can reference other secrets using ${...} syntax, but until now users had to type these manually with no assistance or validation until the backend resolved them at read time. This made broken references hard to discover and debug.

Autocomplete

Typing ${ in a revealed secret value input opens a dropdown with contextual suggestions:

• After ${: local secret keys, environment names (with . suffix), app names (with :: suffix), folder paths (with / suffix)
• After ${env.: keys available in that environment
• After ${app::: environments in that app
• After ${folder/: keys within that folder

Suggestions filter as you type and support keyboard navigation (Arrow keys, Enter/Tab to accept, Escape to dismiss). Ctrl+Enter opens the referenced secret in a new tab.

Syntax highlighting

Revealed secret values containing ${...} references get color-coded highlighting:

• Purple for app names, blue for environment names, amber for folder paths, green for key names, gray for ${ / } delimiters
• Implemented via a transparent textarea overlaid on a highlight layer, with synchronized scrolling

Save-time validation

When saving secrets, all ${...} references are validated against the current app's known keys, environments, and org apps. If broken references are found, a warning dialog lists them and gives the user the choice to go back and fix them or save anyway.

New files

File	Purpose
frontend/utils/secretReferences.ts	Pure utility module: regex parsing, token detection, suggestion computation, URL generation, syntax segmentation, and validation
frontend/contexts/secretReferenceContext.tsx	React context sharing autocomplete data (keys, envs, apps, folders) without prop drilling
frontend/hooks/useOrgSecretKeys.ts	Hook that fetches and decrypts all org secret keys for cross-app autocomplete
frontend/hooks/useSecretReferenceAutocomplete.ts	Autocomplete state machine hook: cursor tracking, suggestion lifecycle, keyboard handling
frontend/components/secrets/ReferenceAutocompleteDropdown.tsx	Presentational dropdown with type icons, keyboard hints, and scroll-to-active
frontend/components/secrets/SecretReferenceHighlight.tsx	Renders color-coded segments for secret reference syntax highlighting
frontend/components/secrets/BrokenReferencesDialog.tsx	Warning dialog listing broken references with "Go back" / "Save anyway" actions

Modified files

File	Changes
MaskedTextarea.tsx	Converted to forwardRef, added onKeyDown/onSelect/onBlur props, added highlight overlay support with synchronized scrolling
AppSecretRow.tsx	Wired autocomplete hook, dropdown, and syntax highlighting into EnvSecretComponent
AppSecrets.tsx	Provides SecretReferenceContext, runs reference validation on save, renders BrokenReferencesDialog
page.tsx (environment page)	Same context/validation/dialog wiring as AppSecrets.tsx for the single-environment editor
SecretRow.tsx	Wired autocomplete, dropdown, and syntax highlighting for the environment-level secret editor

Test plan

• Type ${ in a revealed secret value — dropdown appears with local keys + env names + app names
• Continue typing to filter suggestions; arrow keys navigate, Enter/Tab accepts, Escape dismisses
• Select an env suggestion (e.g. staging.) — dropdown updates to show keys in that environment
• Select a key suggestion — ${KEY_NAME} inserted with closing brace, cursor positioned after }
• Ctrl+Enter on a suggestion opens the referenced secret in a new browser tab
• Revealed values with ${...} show syntax highlighting (color-coded segments)
• Masked (hidden) values show no dropdown and no highlighting
• ${{RAILWAY_VAR}} double-brace syntax does not trigger autocomplete or validation errors
• Create a reference to a non-existent key → click Save → warning dialog appears listing the broken reference
• Click "Go back" → dialog closes, no save
• Click "Save anyway" → secrets save with the broken reference intact
• Valid references → save proceeds with no dialog
• Autocomplete works in both the cross-environment editor (AppSecrets) and single-environment editor (page.tsx / SecretRow)

[Copilot]

Pull request overview

This PR implements comprehensive UX improvements for secret referencing, adding autocomplete, syntax highlighting, and validation for the ${...} reference syntax. The implementation addresses issue #267 by providing contextual suggestions when typing secret references, visual feedback through color-coded syntax highlighting, and save-time validation to catch broken references before deployment.

Changes:

• Adds inline autocomplete for secret references with progressive suggestions (local keys, cross-environment ${env.KEY}, cross-app ${app::env.KEY})
• Implements syntax highlighting for secret reference tokens with color-coded segments
• Adds save-time validation for all references with a warning dialog for broken references

Reviewed changes

Copilot reviewed 15 out of 15 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
frontend/utils/secretReferences.ts	Core utility module for parsing, validating, and generating suggestions for secret references
frontend/hooks/useOrgSecretKeys.ts	Fetches and caches decrypted secret keys across all org apps for cross-app autocomplete
frontend/hooks/useSecretReferenceAutocomplete.ts	State machine hook managing autocomplete lifecycle and keyboard interactions
frontend/contexts/secretReferenceContext.tsx	React context for sharing reference data without prop drilling
frontend/components/secrets/ReferenceAutocompleteDropdown.tsx	Presentational dropdown component with keyboard navigation and type icons
frontend/components/secrets/SecretReferenceHighlight.tsx	Renders color-coded syntax highlighting for reference tokens
frontend/components/secrets/BrokenReferencesDialog.tsx	Warning dialog for broken references with "Go back" / "Deploy anyway" options
frontend/components/common/MaskedTextarea.tsx	Converted to forwardRef, added highlight overlay support with synchronized scrolling
frontend/components/environments/secrets/SecretRow.tsx	Integrated autocomplete and syntax highlighting in single-environment editor
frontend/app/[team]/apps/[app]/_components/AppSecretRow.tsx	Integrated autocomplete and syntax highlighting in cross-environment editor
frontend/app/[team]/apps/[app]/_components/AppSecrets.tsx	Provides context, runs validation on save, renders broken references dialog
frontend/app/[team]/apps/[app]/environments/[environment]/[[...path]]/page.tsx	Provides context, runs validation on save, renders broken references dialog
frontend/components/environments/folders/SecretFolderRow.tsx	Changed folder icon color from emerald to amber for consistency with syntax highlighting
frontend/app/[team]/apps/[app]/_components/EnvFolder.tsx	Changed folder icon color from emerald to amber
frontend/app/[team]/apps/[app]/_components/AppFolderRow.tsx	Changed folder icon color from emerald to amber

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[nimish-ks]

@rohan-chaturvedi A lot of folks jump to docs to quickly checkout secret referencing syntax. I wonder if will be helpful to places a mini guide somewhere in the product itself. A markdown one pager.

Alternatively we should show a hint when setting values to push the user to hit $ and get shown the secret referencing suggestions. So there is no need to view the guide, just construct the reference as you go.