feat: add ui_for_url expression function for generating Kargo UI URLs (#4585)

[Gkemhcs]

🎯 Overview

This Pr Resolves #4585 , implements the ui_for_url() expression function as requested in issue #4585 to enable dynamic URL generation for Kargo UI resources in promotion expressions.

🔧 Changes Made

Core Implementation

• Added UIForURL function in pkg/expressions/function/functions.go
  • Supports zero or one argument: ui_for_url() or ui_for_url(stageName)
  • Uses closure pattern similar to Secret function for context access
  • Returns actual URLs, not templates

Context Integration

• Added UIBaseURL to promotion context in pkg/promotion/evaluator.go
  • Makes ctx.UIBaseURL available in all expressions
  • Integrated with existing expression evaluation pipeline

Function Organization

• Created PromotionOperations to group promotion-specific functions
  • Follows same pattern as DataOperations and FreightOperations
  • Added to all expression evaluation points

📝 Usage Examples

# Using current stage from promotion context
"Freight ${{ ctx.targetFreight.name }} is being promoted to Stage <${{ ui_for_url() }}|${{ ctx.stage }}>"

# Using specific stage name
"Freight ${{ ctx.targetFreight.name }} is being promoted to Stage <${{ ui_for_url('production') }}|${{ ctx.stage }}>"

# Direct usage in Slack notifications
"Check the stage: ${{ ui_for_url() }}"
"Check production: ${{ ui_for_url('production') }}"

Resolves: issue #4585

Related: This implementation addresses the exact use case described in the issue for Slack deployment notifications with dynamic UI links.

[netlify]

✅ Deploy Preview for docs-kargo-io ready!

Name	Link
🔨 Latest commit	c5f32b1
🔍 Latest deploy log	https://app.netlify.com/projects/docs-kargo-io/deploys/68f6050f905587000888bd44
😎 Deploy Preview	https://deploy-preview-5244.docs.kargo.io
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[krancour]

We don't use snake case for functions anywhere in else in the expressions. This should be lower camel case.

[krancour]

This appears to only work for Stages.

We'd like to be able to do the same for Projects, Promotions, and Freight.

I'd like there to be separate functions for each of those.

[Gkemhcs]

Ok sure @krancour will make it work for others also , and is below conventions ok for you while calling in yaml templates ?

Stage:-
{{ui_for_stage()}}

Freight:-
{{ui_for_freight()}}
If not, how should be the function names in yaml template.

[hiddeco]

I wonder if something like linkForStage and linkForFreight would be a nicer fluent API.

[Gkemhcs]

I mean what should be the names of link functions to be defined or used in yaml promotion task template yaml file .

@hiddeco @krancour

[krancour]

@hiddeco already suggested good names.

[Gkemhcs]

Ok sure , will implement accordingly

[Gkemhcs]

@krancour @hiddeco , able to implement the links for projects,stages, freights and let me know how can i construct the url for promotions as it can't be inferred from ui ?

besides can i proceed to add link for warehouse function also?

[krancour]

let me know how can i construct the url for promotions as it can't be inferred from ui ?

Not sure what the UI has to do with this. That's not the source of any information.

As for how to actually get the Promotion's name, make the internal function that registers the expression function receive it as a parameter (same as you do with Project, Stage, etc.) and the expression function can close over it (same as it does for Project, Stage, etc.)

[Gkemhcs]

@krancour @hiddeco , now could you please check is this ok or not?