feat: Add CEL expression evaluator command

This commit introduces a new command `tkn pac cel` that allows
users to interactively evaluate CEL (Common Expression Language)
expressions. The command is designed to help users test and debug
CEL expressions, which are commonly used in Pipelines-as-Code.

Key features include:

- Interactive and non-interactive modes.
- Support for webhook payloads and headers.
- Provider auto-detection (GitHub, GitLab, Bitbucket Cloud,
  Bitbucket Data Center, Gitea).
- Direct access to variables as per PAC documentation.
- Cross-platform history with readline experience.
- Comprehensive help and example expressions.

Signed-off-by: Chmouel Boudjnah <[email protected]>

Author: chmouel

docs/content/docs/guide/cli.md

@@ -409,6 +409,99 @@ You can specify a different directory than the current one by using the -d/--dir
 
 {{< /details >}}
 
+{{< details "tkn pac cel" >}}
+
+### CEL Expression Evaluator
+
+`tkn pac cel` — Evaluate CEL (Common Expression Language) expressions interactively with webhook payloads.
+
+This command allows you to test and debug CEL expressions as they would be evaluated by Pipelines-as-Code, using real webhook payloads and headers. It supports interactive and non-interactive modes, provider auto-detection, and persistent history.
+
+To be able to have the CEL evaluator working, you need to have the payload and the headers available in a file. The best way to do this is to go to the webhook configuration on your git provider and copy the payload and headers to different files.
+
+The payload is the JSON content of the webhook requests, and the headers are a simple HTTP headers file looking like this:
+
+```text
+Request method: POST
+Accept: */*
+Content-Type: application/json
+User-Agent: GitHub-Hookshot/2d5e4d4
+X-GitHub-Delivery: 10830ef-5292-11f0-8109-b24970f70a45
+X-GitHub-Event: pull_request
+[...]
+```
+
+#### Usage
+
+```shell
+tkn pac cel -b <body.json> -H <headers.txt>
+```
+
+* `-b, --body`: Path to JSON body file (webhook payload)
+* `-H, --headers`: Path to headers file (plain text or JSON)
+* `-p, --provider`: Provider (auto, github, gitlab, bitbucket-cloud, bitbucket-datacenter, gitea)
+
+#### Interactive Mode
+
+If run in a terminal, you'll get a prompt:
+
+```console
+CEL expression> 
+```
+
+* Use ↑/↓ arrows to navigate history.
+* History is saved and loaded automatically.
+* Press Enter on an empty line to exit.
+
+#### Non-Interactive Mode
+
+Pipe expressions via stdin:
+
+```shell
+echo 'event == "pull_request"' | tkn pac cel -b body.json -H headers.txt
+```
+
+#### Available Variables
+
+* **Direct variables** (top-level, as per PAC documentation):
+  * `event` — event type (push, pull_request)
+  * `target_branch` — target branch name
+  * `source_branch` — source branch name
+  * `target_url` — target repository URL
+  * `source_url` — source repository URL
+  * `event_title` — PR title or commit message
+
+* **Webhook payload** (`body.*`): All fields from the webhook JSON.
+* **HTTP headers** (`headers.*`): All HTTP headers.
+* **Files** (`files.*`): Always empty in CLI mode.  
+  **Note:** `fileChanged`, `fileDeleted`, `fileModified` and similar functions are **not implemented yet** in the CLI.
+* **PAC Parameters** (`pac.*`): All variables for backward compatibility.
+
+#### Example Expressions
+
+```text
+event == "pull_request" && target_branch == "main"
+event == "pull_request" && source_branch.matches(".*feat/.*")
+body.action == "synchronize"
+!body.pull_request.draft
+headers['x-github-event'] == "pull_request"
+event == "pull_request" && target_branch != "experimental"
+```
+
+#### Limitations
+
+* `files.*` variables are always empty in CLI mode.
+* Functions like `fileChanged`, `fileDeleted`, `fileModified` are **not implemented yet** in the CLI.
+
+#### Cross-Platform History
+
+* History is saved in a cache directory:
+  * Linux/macOS: `~/.cache/tkn-pac/cel-history`
+  * Windows: `%USERPROFILE%\.cache\tkn-pac\cel-history`
+* The directory is created automatically if it does not exist.
+
+{{< /details >}}
+
 ## Screenshot
 
 ![tkn-plug-in](/images/tkn-pac-cli.png)

go.mod

@@ -9,6 +9,7 @@ require (
 	code.gitea.io/sdk/gitea v0.21.0
 	github.com/AlecAivazis/survey/v2 v2.3.7
 	github.com/bradleyfalzon/ghinstallation/v2 v2.15.0
+	github.com/chzyer/readline v1.5.1
 	github.com/cloudevents/sdk-go/v2 v2.16.0
 	github.com/fvbommel/sortorder v1.1.0
 	github.com/gobwas/glob v0.2.3
@@ -129,7 +130,7 @@ require (
 	golang.org/x/crypto v0.37.0 // indirect
 	golang.org/x/net v0.39.0 // indirect
 	golang.org/x/sys v0.33.0 // indirect
-	golang.org/x/term v0.31.0 // indirect
+	golang.org/x/term v0.31.0
 	golang.org/x/time v0.11.0 // indirect
 	gomodules.xyz/jsonpatch/v2 v2.5.0 // indirect
 	google.golang.org/api v0.231.0 // indirect

go.sum

@@ -88,8 +88,14 @@ github.com/cespare/xxhash/v2 v2.1.2/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XL
 github.com/cespare/xxhash/v2 v2.3.0 h1:UL815xU9SqsFlibzuggzjXhog7bL6oX9BbNZnL2UFvs=
 github.com/cespare/xxhash/v2 v2.3.0/go.mod h1:VGX0DQ3Q6kWi7AoAeZDth3/j3BFtOZR5XLFGgcrjCOs=
 github.com/chzyer/logex v1.1.10/go.mod h1:+Ywpsq7O8HXn0nuIou7OrIPyXbp3wmkHB+jjWRnGsAI=
+github.com/chzyer/logex v1.2.1 h1:XHDu3E6q+gdHgsdTPH6ImJMIp436vR6MPtH8gP05QzM=
+github.com/chzyer/logex v1.2.1/go.mod h1:JLbx6lG2kDbNRFnfkgvh4eRJRPX1QCoOIWomwysCBrQ=
 github.com/chzyer/readline v0.0.0-20180603132655-2972be24d48e/go.mod h1:nSuG5e5PlCu98SY8svDHJxuZscDgtXS6KTTbou5AhLI=
+github.com/chzyer/readline v1.5.1 h1:upd/6fQk4src78LMRzh5vItIt361/o4uq553V8B5sGI=
+github.com/chzyer/readline v1.5.1/go.mod h1:Eh+b79XXUwfKfcPLepksvw2tcLE/Ct21YObkaSkeBlk=
 github.com/chzyer/test v0.0.0-20180213035817-a1ea475d72b1/go.mod h1:Q3SI9o4m/ZMnBNeIyt5eFwwo7qiLfzFZmjNmxjkiQlU=
+github.com/chzyer/test v1.0.0 h1:p3BQDXSxOhOG0P9z6/hGnII4LGiEPOYBhs8asl/fC04=
+github.com/chzyer/test v1.0.0/go.mod h1:2JlltgoNkt4TW/z9V/IzDdFaMTM2JPIi26O1pF38GC8=
 github.com/client9/misspell v0.3.4/go.mod h1:qj6jICC3Q7zFZvVWo7KLAzC3yx5G7kyvSDkc90ppPyw=
 github.com/cloudevents/sdk-go/observability/opencensus/v2 v2.15.2 h1:AbtPqiUDzKup5JpTZzO297/QXgL/TAdpdXQCNwLzlaM=
 github.com/cloudevents/sdk-go/observability/opencensus/v2 v2.15.2/go.mod h1:ZbYLE+yaEQ2j4vbRc9qzvGmg30A9LhwFt/1bSebNnbU=
@@ -675,6 +681,7 @@ golang.org/x/sys v0.0.0-20210615035016-665e8c7367d1/go.mod h1:oPkhp1MJrh7nUepCBc
 golang.org/x/sys v0.0.0-20210630005230-0f9fa26af87c/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20211216021012-1d35b9e2eb4e/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220114195835-da31bd327af9/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.0.0-20220310020820-b874c991c1a5/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220520151302-bc2c85ada10a/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220708085239-5a0f0661e09d/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
 golang.org/x/sys v0.0.0-20220722155257-8c9f86f7a55f/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=

pkg/cel/cel.go

@@ -55,12 +55,26 @@ func Value(query string, body any, headers, pacParams map[string]string, changed
 			decls.NewVariable("headers", mapStrDyn),
 			decls.NewVariable("pac", mapStrDyn),
 			decls.NewVariable("files", mapStrDyn),
+			// Direct variables as per documentation
+			decls.NewVariable("event", types.StringType),
+			decls.NewVariable("target_branch", types.StringType),
+			decls.NewVariable("source_branch", types.StringType),
+			decls.NewVariable("target_url", types.StringType),
+			decls.NewVariable("source_url", types.StringType),
+			decls.NewVariable("event_title", types.StringType),
 		))
 	val, err := evaluate(query, celDec, map[string]any{
 		"body":    jsonMap,
 		"pac":     pacParams,
 		"headers": headers,
 		"files":   changedFiles,
+		// Direct variables
+		"event":         pacParams["event"],
+		"target_branch": pacParams["target_branch"],
+		"source_branch": pacParams["source_branch"],
+		"target_url":    pacParams["target_url"],
+		"source_url":    pacParams["source_url"],
+		"event_title":   pacParams["event_title"],
 	})
 	if err != nil {
 		return nil, err