Module.cfc

        
component extends="modules.BaseModule" {
    /**
     * bitbucket Module
     * 
     * This is the main entry point for your module.
     * Implement your module logic in the main() function.
     */
    
   
    /*
    Bitbucket Pipelines set the following variables anyway
        Default variables:
            BITBUCKET_BRANCH
            BITBUCKET_BUILD_NUMBER
            BITBUCKET_CLONE_DIR
            BITBUCKET_COMMIT
            BITBUCKET_GIT_HTTP_ORIGIN
            BITBUCKET_GIT_SSH_ORIGIN
            BITBUCKET_PIPELINES_VARIABLES_PATH
            BITBUCKET_PIPELINE_UUID
            BITBUCKET_PROJECT_KEY
            BITBUCKET_PROJECT_UUID
            BITBUCKET_PR_DESTINATION_BRANCH
            BITBUCKET_PR_DESTINATION_COMMIT
            BITBUCKET_PR_ID
            BITBUCKET_REPO_FULL_NAME
            BITBUCKET_REPO_IS_PRIVATE
            BITBUCKET_REPO_OWNER
            BITBUCKET_REPO_OWNER_UUID
            BITBUCKET_REPO_SLUG
            BITBUCKET_REPO_UUID
            BITBUCKET_SSH_KEY_FILE
            BITBUCKET_STEP_RUN_NUMBER
            BITBUCKET_STEP_TRIGGERER_UUID
            BITBUCKET_STEP_UUID
            BITBUCKET_TEST_METADATA_FILE_PATH
            BITBUCKET_WORKSPACE
            CI
            DOCKER_HOST
    */
    /**
     * Default command when calling `lucli bitbucket` without a subcommand.
     *
     * Backward compatible: if `--action` is provided, we will invoke that method.
     */
    public any function main(
        string action="",
        string file="",
        string commit="",
        string reportId="",
        string reportSlug="",
        numeric pullRequestId=0,
        string outputPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        if(!Len(arguments.action)){
            return showHelp();
        }

        var actionName = arguments.action;

        // Only allow invoking *public* functions, and only pass accepted params.
        var md = getComponentMetadata(this);
        var fnMeta = md.functions.filter(function(fn){
            return compareNoCase(fn.name, actionName) EQ 0;
        });

        if(!arrayLen(fnMeta) || fnMeta[1].access NEQ "public"){
            throw("Unknown action: #actionName#");
        }

        var args = duplicate(arguments);
        structDelete(args, "action");

        var callArgs = {};
        for(var p in fnMeta[1].parameters){
            if(structKeyExists(args, p.name)){
                callArgs[p.name] = args[p.name];
            }
        }

        return invoke(this, actionName, callArgs);
    }

    /**
     * Shared Bitbucket client factory.
     */
    private any function createClient(
        
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string authUser=getEnv("BITBUCKET_AUTH_USER", "")
    ){

        // If we don't have the required params, get it from the env, and if we still don't have it show a proper error message
        return new BitbucketClient(
            repoSlug = Len(arguments.repoSlug) ? arguments.repoSlug : getEnv("BITBUCKET_REPO_SLUG", ""),
            workspace = Len(arguments.workspace) ? arguments.workspace : getEnv("BITBUCKET_WORKSPACE", ""),
            authToken = Len(arguments.authToken) ? arguments.authToken : getEnv("BITBUCKET_AUTH_TOKEN", ""),
            authUser = Len(arguments.authUser) ? arguments.authUser : getEnv("BITBUCKET_AUTH_USER", "")
        );
    }

    /**
     * Read JSON from a file and return the native CFML struct/array.
     */
    private any function readJsonFile(required string filePath){
        if(!Len(arguments.filePath)){
            throw("filePath is required");
        }

        var absPath = getAbsolutePath(variables.cwd, arguments.filePath);
        if(!fileExists(absPath)){
            throw("JSON file not found: #absPath#");
        }

        return deserializeJson(fileRead(absPath));
    }

    /**
     * Decorated helper: validate and normalize repository context.
     * Accepts repoSlug as either "<repoSlug>" or "<workspace>/<repoSlug>".
     * Returns the resolved context without making a Bitbucket API call.
     */
    public any function contexts_validate(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string authUser=getEnv("BITBUCKET_AUTH_USER", "")
    ){
        var bb = createClient(
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken,
            authUser=arguments.authUser
        );
        return bb.getRepositoryContext();
    }

    // --- Reports (API group: /reports) ---

    /**
     * List reports for a commit.
     * Maps to GET /repositories/{workspace}/{repo_slug}/commit/{commit}/reports
     */
    public any function reports(
        required string commit,
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format=""
    ){
        var res = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listReports(
                commit=arguments.commit,
                page=Int(arguments.page),
                pagelen=Int(arguments.pagelen)
            );

        if(lCase(arguments.format) EQ "json" OR lCase(arguments.format) EQ "json-compact"){
            if(isSimpleValue(res) AND isJSON(res)){
                return res;
            }
            return serializeJson(res, lCase(arguments.format) EQ "json-compact");
        }

        return res;
    }

    /**
     * Get a report by id.
     * Maps to GET /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}
     */
    public any function reports_get(
        required string commit,
        required string reportId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getReport(
                commit=arguments.commit,
                reportId=arguments.reportId
            );
    }

    /**
     * Create a report.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}
     */
    public any function reports_create(
        required string commit,
        required string dataFile,
        string reportId="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        
        var reportData = readJsonFile(arguments.dataFile);
        var reportIdToUse = arguments.reportId;
        if(!Len(reportIdToUse) AND isStruct(reportData) AND structKeyExists(reportData, "title") AND Len(reportData.title)){
            reportIdToUse = lCase(replace(reportData.title, " ", "_", "all"));
        }

        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createReport(
                reportData=reportData,
                commit=arguments.commit,
                reportId=reportIdToUse
            );
    }

    /**
     * Delete a report by id.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}
     */
    public any function reports_delete(
        required string commit,
        required string reportId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deleteReport(
                commit=arguments.commit,
                reportId=arguments.reportId
            );
    }

    /**
     * List report annotations.
     * Maps to GET /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations
     */
    public any function reports_annotations(
        required string commit,
        required string reportId,
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format=""
    ){
        var res = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listReportAnnotations(
                commit=arguments.commit,
                reportId=arguments.reportId,
                page=Int(arguments.page),
                pagelen=Int(arguments.pagelen)
            );

        if(lCase(arguments.format) EQ "json" OR lCase(arguments.format) EQ "json-compact"){
            if(isSimpleValue(res) AND isJSON(res)){
                return res;
            }
            return serializeJson(res, lCase(arguments.format) EQ "json-compact");
        }

        return res;
    }

    /**
     * Get a report annotation by id.
     * Maps to GET /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}
     */
    public any function reports_annotations_get(
        required string commit,
        required string reportId,
        required string annotationId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getReportAnnotation(
                commit=arguments.commit,
                reportId=arguments.reportId,
                annotationId=arguments.annotationId
            );
    }

    /**
     * Create report annotations.
     * Maps to POST /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations
     */
    public any function reports_annotations_post(
        required string commit,
        required string dataFile,
        required string reportId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var payload = readJsonFile(arguments.dataFile);
        var annotations = [];
        if(isArray(payload)){
            annotations = payload;
        }
        else if(isStruct(payload) AND structKeyExists(payload, "annotations")){
            annotations = payload.annotations;
        }

        if(!isArray(annotations)){
            throw("No annotations array found in file: #arguments.dataFile#");
        }

        // Empty annotations are a valid no-op input (e.g. filtered result with no matches).
        if(arrayLen(annotations) EQ 0){
            return [];
        }

        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createAnnotations(
                annotations=annotations,
                commit=arguments.commit,
                reportId=arguments.reportId
            );
    }

    /**
     * Alias wrapper for report annotations creation.
     * Keeps endpoint-style naming compatibility with other command groups.
     */
    public any function reports_annotations_create(
        required string commit,
        required string dataFile,
        required string reportId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return reports_annotations_post(
            commit=arguments.commit,
            dataFile=arguments.dataFile,
            reportId=arguments.reportId,
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken
        );
    }

    /**
     * Upsert a report annotation by id.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}
     */
    public any function reports_annotations_put(
        required string commit,
        required string reportId,
        required string annotationId,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .putReportAnnotation(
                commit=arguments.commit,
                reportId=arguments.reportId,
                annotationId=arguments.annotationId,
                annotationData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete a report annotation by id.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/commit/{commit}/reports/{reportId}/annotations/{annotationId}
     */
    public any function reports_annotations_delete(
        required string commit,
        required string reportId,
        required string annotationId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deleteReportAnnotation(
                commit=arguments.commit,
                reportId=arguments.reportId,
                annotationId=arguments.annotationId
            );
    }

    /**
     * DEPRECATED: use reports_create + reports_annotations_post.
     * Backward-compatible wrapper for reports.
     */
    public any function createReport(
        required string commit,
        required string file,
        string reportId="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var reportResponse = reports_create(
            commit=arguments.commit,
            dataFile=arguments.file,
            reportId=arguments.reportId,
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken
        );

        var reportData = readJsonFile(arguments.file);
        var reportIdToUse = arguments.reportId;
        if(!Len(reportIdToUse) AND isStruct(reportData) AND structKeyExists(reportData, "title") AND Len(reportData.title)){
            reportIdToUse = lCase(replace(reportData.title, " ", "_", "all"));
        }

        var result = {
            report = reportResponse
        };

        // Legacy behavior: if the report JSON has embedded annotations, post them too.
        if(isStruct(reportData) AND structKeyExists(reportData, "annotations") AND isArray(reportData.annotations) AND arrayLen(reportData.annotations) GT 0){
            var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);
            result.annotations = bb.createAnnotations(
                annotations=reportData.annotations,
                commit=arguments.commit,
                reportId=reportIdToUse
            );
        }

        return result;
    }

    /**
     * DEPRECATED: use reports_annotations_post.
     * Backward-compatible wrapper for report annotations.
     */
    public any function createAnnotations(
        required string commit,
        required string file,
        required string reportId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return reports_annotations_post(
            commit=arguments.commit,
            dataFile=arguments.file,
            reportId=arguments.reportId,
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken
        );
    }

    // --- Pull Requests (API group: /pullrequests) ---

    /**
     * List pull requests for the repo.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests
     */
    public any function pullrequests(
        string state="",
        string q="",
        string sort="",
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format=""
    ){
        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);
        var res = bb.listPullRequests(
            state=arguments.state,
            q=arguments.q,
            sort=arguments.sort,
            page=Int(arguments.page),
            pagelen=Int(arguments.pagelen)
        );

        // Backward-compat: if older callers still pass --format=json, avoid double-serializing
        // now that the client returns JSON as a string.
        if(lCase(arguments.format) EQ "json" OR lCase(arguments.format) EQ "json-compact"){
            if(isSimpleValue(res) AND isJSON(res)){
                return res;
            }
            // Fallback (if some call path still returns native CFML)
            return serializeJson(res, lCase(arguments.format) EQ "json-compact");
        }

        return res;
    }

    /**
     * Get a single pull request by id.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}
     */
    public any function pullrequests_get(
        required numeric pullRequestId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequest(pullRequestId=arguments.pullRequestId);
    }

    /**
     * Create a pull request.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests
     */
    public any function pullrequests_create(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPullRequest(
                pullRequestData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Update a pull request.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}
     */
    public any function pullrequests_update(
        required numeric pullRequestId,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePullRequest(
                pullRequestId=arguments.pullRequestId,
                pullRequestData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Decline a pull request.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/decline
     */
    public any function pullrequests_decline(
        required numeric pullRequestId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .declinePullRequest(pullRequestId=arguments.pullRequestId);
    }

    /**
     * Merge a pull request.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge
     */
    public any function pullrequests_merge(
        required numeric pullRequestId,
        string dataFile="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var mergeData = {};
        if(Len(arguments.dataFile)){
            mergeData = readJsonFile(arguments.dataFile);
        }
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .mergePullRequest(
                pullRequestId=arguments.pullRequestId,
                mergeData=mergeData
            );
    }

    /**
     * Get the merge task status.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/merge/task-status/{task_id}
     */
    public any function pullrequests_merge_task_status(
        required numeric pullRequestId,
        required string taskId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestMergeTaskStatus(
                pullRequestId=arguments.pullRequestId,
                taskId=arguments.taskId
            );
    }

    /**
     * Get the diffstat for a pull request.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/diffstat
     */
    public any function pullrequests_diffstat(
        required numeric pullRequestId,
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestDiffStat(
                pullRequestId=arguments.pullRequestId,
                page=Int(arguments.page),
                pagelen=Int(arguments.pagelen)
            );
    }

    /**
     * Get the diff for a pull request.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/diff
     */
    public any function pullrequests_diff(
        required numeric pullRequestId,
        string outputPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var diffContent = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestDiff(pullRequestId=arguments.pullRequestId);

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, diffContent);
        }

        return diffContent;
    }

    /**
     * Get the patch for a pull request.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/patch
     */
    public any function pullrequests_patch(
        required numeric pullRequestId,
        string outputPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var patchContent = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestPatch(pullRequestId=arguments.pullRequestId);

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, patchContent);
        }

        return patchContent;
    }

    /**
     * Approve a pull request.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve
     */
    public any function pullrequests_approve(
        required numeric pullRequestId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .approvePullRequest(pullRequestId=arguments.pullRequestId);
    }

    /**
     * Unapprove a pull request.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/approve
     */
    public any function pullrequests_unapprove(
        required numeric pullRequestId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .unapprovePullRequest(pullRequestId=arguments.pullRequestId);
    }

    /**
     * Request changes on a pull request.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/request-changes
     */
    public any function pullrequests_request_changes(
        required numeric pullRequestId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .requestChangesPullRequest(pullRequestId=arguments.pullRequestId);
    }

    /**
     * Remove change request on a pull request.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/request-changes
     */
    public any function pullrequests_remove_request_changes(
        required numeric pullRequestId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .removeRequestChangesPullRequest(pullRequestId=arguments.pullRequestId);
    }

    /**
     * List PR activity.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/activity
     */
    public any function pullrequests_activity(
        required numeric pullRequestId,
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPullRequestActivity(
                pullRequestId=arguments.pullRequestId,
                page=arguments.page,
                pagelen=arguments.pagelen
            );
    }

    /**
     * List PR commits.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/commits
     */
    public any function pullrequests_commits(
        required numeric pullRequestId,
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPullRequestCommits(
                pullRequestId=arguments.pullRequestId,
                page=arguments.page,
                pagelen=arguments.pagelen
            );
    }

    /**
     * List PR comments.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments
     */
    public any function pullrequests_comments(
        required numeric pullRequestId,
        string q="",
        string sort="",
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPullRequestComments(
                pullRequestId=arguments.pullRequestId,
                q=arguments.q,
                sort=arguments.sort,
                page=arguments.page,
                pagelen=arguments.pagelen
            );
    }

    /**
     * Create a PR comment.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments
     * see: https://developer.atlassian.com/cloud/bitbucket/rest/api-group-pullrequests/#api-repositories-workspace-repo-slug-pullrequests-pull-request-id-comments-post
     */
    public any function pullrequests_comments_create(
        required numeric pullRequestId,
        string comment="",
        string commentFile="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){

        var finalComment = "";
        if(Len(arguments.comment)){
            finalComment = arguments.comment;
        }
        else if(Len(arguments.commentFile)){
            var absCommentFile = getAbsolutePath(variables.cwd, arguments.commentFile);
            if(!fileExists(absCommentFile)){
                throw("Comment file not found: #absCommentFile#");
            }
            finalComment = fileRead(absCommentFile);
        }
        else {
            throw("Either comment or commentFile is required");
        }
        
        var commentData = {
            "content" = {
                "raw" = finalComment
            }
        };

        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPullRequestComment(
                pullRequestId=arguments.pullRequestId,
                commentData=commentData
            );
    }

    /**
     * Get a PR comment.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id}
     */
    public any function pullrequests_comments_get(
        required numeric pullRequestId,
        required numeric commentId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestComment(
                pullRequestId=arguments.pullRequestId,
                commentId=arguments.commentId
            );
    }

    /**
     * Update a PR comment.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id}
     */
    public any function pullrequests_comments_update(
        required numeric pullRequestId,
        required numeric commentId,
        string comment="",
        string commentFile="",
        string dataFile="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var commentData = {};
        if(Len(arguments.comment)){
            commentData = {
                "content" = {
                    "raw" = arguments.comment
                }
            };
        }
        else if(Len(arguments.commentFile)){
            var absCommentFile = getAbsolutePath(variables.cwd, arguments.commentFile);
            if(!fileExists(absCommentFile)){
                throw("Comment file not found: #absCommentFile#");
            }
            commentData = {
                "content" = {
                    "raw" = fileRead(absCommentFile)
                }
            };
        }
        else if(Len(arguments.dataFile)){
            commentData = readJsonFile(arguments.dataFile);
        }
        else {
            throw("One of comment, commentFile, or dataFile is required");
        }
        if(!isStruct(commentData)){
            throw("Comment payload must be a JSON object");
        }
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePullRequestComment(
                pullRequestId=arguments.pullRequestId,
                commentId=arguments.commentId,
                commentData=commentData
            );
    }
    /**
     * Decorated helper: save a PR comment by optional id.
     * If commentId is provided (>0), updates the existing comment.
     * If commentId is not provided (or <=0), optionally looks up an existing
     * marker comment and updates it; otherwise creates a new comment.
     */
    public any function pullrequests_comments_save(
        required numeric pullRequestId,
        numeric commentId=0,
        string comment="",
        string commentFile="",
        string dataFile="",
        string marker="",
        numeric scanPageLen=100,
        numeric maxScanPages=20,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var commentData = {};
        if(Len(arguments.comment)){
            commentData = {
                "content" = {
                    "raw" = arguments.comment
                }
            };
        }
        else if(Len(arguments.commentFile)){
            var absCommentFile = getAbsolutePath(variables.cwd, arguments.commentFile);
            if(!fileExists(absCommentFile)){
                throw("Comment file not found: #absCommentFile#");
            }
            commentData = {
                "content" = {
                    "raw" = fileRead(absCommentFile)
                }
            };
        }
        else if(Len(arguments.dataFile)){
            commentData = readJsonFile(arguments.dataFile);
        }
        else {
            throw("One of comment, commentFile, or dataFile is required");
        }
        var markerValue = Trim(arguments.marker & "");
        if(compareNoCase(markerValue, "true") EQ 0 OR compareNoCase(markerValue, "false") EQ 0){
            throw("marker must be a marker string, not a boolean; use marker=statler_and_waldorf or quote your HTML marker.");
        }
        var legacyMarkerValue = "";
        if(Len(markerValue) AND findNoCase("<!--", markerValue) EQ 0){
            legacyMarkerValue = "<!-- #markerValue# -->";
        }
        if(!structKeyExists(commentData, "content") OR !isStruct(commentData.content)){
            commentData.content = {};
        }
        if(!structKeyExists(commentData.content, "raw")){
            commentData.content.raw = "";
        }
        var rawContent = commentData.content.raw & "";
        if(Len(markerValue)){
            var hasPlainMarker = findNoCase(markerValue, rawContent) GT 0;
            var hasLegacyMarker = Len(legacyMarkerValue) AND findNoCase(legacyMarkerValue, rawContent) GT 0;
            if(!hasPlainMarker AND !hasLegacyMarker){
                if(Len(rawContent)){
                    rawContent = rawContent & chr(10) & chr(10) & markerValue;
                }
                else {
                    rawContent = markerValue;
                }
            }
        }
        commentData.content.raw = rawContent;

        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);

        if(Int(arguments.commentId) GT 0){
            return bb.updatePullRequestComment(
                pullRequestId=arguments.pullRequestId,
                commentId=Int(arguments.commentId),
                commentData=commentData
            );
        }
        if(Len(markerValue)){
            var pageLen = Int(arguments.scanPageLen);
            if(pageLen LTE 0){
                pageLen = 100;
            }
            var pageLimit = Int(arguments.maxScanPages);
            if(pageLimit LTE 0){
                pageLimit = 20;
            }

            var foundCommentId = 0;
            var pageNum = 1;
            while(pageNum LTE pageLimit){
                var listRaw = bb.listPullRequestComments(
                    pullRequestId=arguments.pullRequestId,
                    sort="-created_on",
                    page=pageNum,
                    pagelen=pageLen
                );
                if(!isSimpleValue(listRaw) OR !isJSON(listRaw)){
                    break;
                }

                var listPayload = deserializeJson(listRaw);
                if(
                    !isStruct(listPayload) OR
                    !structKeyExists(listPayload, "values") OR
                    !isArray(listPayload.values) OR
                    arrayLen(listPayload.values) EQ 0
                ){
                    break;
                }

                for(var c in listPayload.values){
                    var existingRaw = c.content?.raw ?: "";
                    var hasMarker = findNoCase(markerValue, existingRaw) GT 0;
                    if(!hasMarker AND Len(legacyMarkerValue)){
                        hasMarker = findNoCase(legacyMarkerValue, existingRaw) GT 0;
                    }
                    if(hasMarker){
                        foundCommentId = Int(c.id ?: 0);
                        break;
                    }
                }

                if(foundCommentId GT 0){
                    break;
                }
                if(!structKeyExists(listPayload, "next")){
                    break;
                }
                pageNum++;
            }

            if(foundCommentId GT 0){
                return bb.updatePullRequestComment(
                    pullRequestId=arguments.pullRequestId,
                    commentId=foundCommentId,
                    commentData=commentData
                );
            }
        }

        return bb.createPullRequestComment(
            pullRequestId=arguments.pullRequestId,
            commentData=commentData
        );
    }

    /**
     * Delete a PR comment.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/comments/{comment_id}
     */
    public any function pullrequests_comments_delete(
        required numeric pullRequestId,
        required numeric commentId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePullRequestComment(
                pullRequestId=arguments.pullRequestId,
                commentId=arguments.commentId
            );
    }

    /**
     * List PR tasks.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/tasks
     */
    public any function pullrequests_tasks(
        required numeric pullRequestId,
        string q="",
        string sort="",
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPullRequestTasks(
                pullRequestId=arguments.pullRequestId,
                q=arguments.q,
                sort=arguments.sort,
                page=arguments.page,
                pagelen=arguments.pagelen
            );
    }

    /**
     * Create a PR task.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/tasks
     */
    public any function pullrequests_tasks_create(
        required numeric pullRequestId,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPullRequestTask(
                pullRequestId=arguments.pullRequestId,
                taskData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Get a PR task.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/tasks/{task_id}
     */
    public any function pullrequests_tasks_get(
        required numeric pullRequestId,
        required numeric taskId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestTask(
                pullRequestId=arguments.pullRequestId,
                taskId=arguments.taskId
            );
    }

    /**
     * Update a PR task.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/tasks/{task_id}
     */
    public any function pullrequests_tasks_update(
        required numeric pullRequestId,
        required numeric taskId,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePullRequestTask(
                pullRequestId=arguments.pullRequestId,
                taskId=arguments.taskId,
                taskData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete a PR task.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}/tasks/{task_id}
     */
    public any function pullrequests_tasks_delete(
        required numeric pullRequestId,
        required numeric taskId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePullRequestTask(
                pullRequestId=arguments.pullRequestId,
                taskId=arguments.taskId
            );
    }

    /**
     * List pull requests for a commit.
     * Maps to GET /repositories/{workspace}/{repo_slug}/commit/{commit}/pullrequests
     */
    public any function pullrequests_for_commit(
        required string commit,
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPullRequestsForCommit(
                commit=arguments.commit,
                page=arguments.page,
                pagelen=arguments.pagelen
            );
    }

    // --- Pipelines (API group: /pipelines) ---

    /**
     * List pipelines for the repo.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines
     */
    public any function pipelines(
        string creatorUuid="",
        string targetRefType="",
        string targetRefName="",
        string targetBranch="",
        string targetCommitHash="",
        string targetSelectorPattern="",
        string targetSelectorType="",
        string createdOn="",
        string triggerType="",
        string status="",
        string sort="",
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format=""
    ){
        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);
        var res = bb.listPipelines(
            creatorUuid=arguments.creatorUuid,
            targetRefType=arguments.targetRefType,
            targetRefName=arguments.targetRefName,
            targetBranch=arguments.targetBranch,
            targetCommitHash=arguments.targetCommitHash,
            targetSelectorPattern=arguments.targetSelectorPattern,
            targetSelectorType=arguments.targetSelectorType,
            createdOn=arguments.createdOn,
            triggerType=arguments.triggerType,
            status=arguments.status,
            sort=arguments.sort,
            page=Int(arguments.page),
            pagelen=Int(arguments.pagelen)
        );

        if(lCase(arguments.format) EQ "json" OR lCase(arguments.format) EQ "json-compact"){
            if(isSimpleValue(res) AND isJSON(res)){
                return res;
            }
            return serializeJson(res, lCase(arguments.format) EQ "json-compact");
        }

        return res;
    }

    /**
     * Run a pipeline.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pipelines
     */
    public any function pipelines_create(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .runPipeline(
                pipelineData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Alias wrapper for running a pipeline.
     */
    public any function pipelines_run(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return pipelines_create(
            dataFile=arguments.dataFile,
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken
        );
    }

    /**
     * Get a pipeline by uuid.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}
     */
    public any function pipelines_get(
        required string pipelineUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipeline(
                pipelineUuid=arguments.pipelineUuid
            );
    }

    /**
     * Stop a pipeline.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/stopPipeline
     */
    public any function pipelines_stop(
        required string pipelineUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .stopPipeline(
                pipelineUuid=arguments.pipelineUuid
            );
    }

    /**
     * List steps for a pipeline.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps
     */
    public any function pipelines_steps(
        required string pipelineUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineSteps(
                pipelineUuid=arguments.pipelineUuid
            );
    }

    /**
     * Get a step of a pipeline.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}
     */
    public any function pipelines_steps_get(
        required string pipelineUuid,
        required string stepUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineStep(
                pipelineUuid=arguments.pipelineUuid,
                stepUuid=arguments.stepUuid
            );
    }

    /**
     * Get the log file for a step.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/log
     */
    public any function pipelines_steps_log(
        required string pipelineUuid,
        required string stepUuid,
        string outputPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var logContent = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineStepLog(
                pipelineUuid=arguments.pipelineUuid,
                stepUuid=arguments.stepUuid
            );

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, logContent);
        }

        return logContent;
    }

    /**
     * Get container logs for a pipeline step.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/logs/{log_uuid}
     */
    public any function pipelines_steps_logs_get(
        required string pipelineUuid,
        required string stepUuid,
        required string logUuid,
        string outputPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var logContent = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineStepLogs(
                pipelineUuid=arguments.pipelineUuid,
                stepUuid=arguments.stepUuid,
                logUuid=arguments.logUuid
            );

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, logContent);
        }

        return logContent;
    }

    /**
     * Get summary test reports for a pipeline step.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/test_reports
     */
    public any function pipelines_steps_test_reports(
        required string pipelineUuid,
        required string stepUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineStepTestReports(
                pipelineUuid=arguments.pipelineUuid,
                stepUuid=arguments.stepUuid
            );
    }

    /**
     * Get test cases for a pipeline step.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/test_reports/test_cases
     */
    public any function pipelines_steps_test_reports_test_cases(
        required string pipelineUuid,
        required string stepUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineStepTestCases(
                pipelineUuid=arguments.pipelineUuid,
                stepUuid=arguments.stepUuid
            );
    }

    /**
     * Get test case reasons for a pipeline step test case.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines/{pipeline_uuid}/steps/{step_uuid}/test_reports/test_cases/{test_case_uuid}/test_case_reasons
     */
    public any function pipelines_steps_test_reports_test_cases_reasons(
        required string pipelineUuid,
        required string stepUuid,
        required string testCaseUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineStepTestCaseReasons(
                pipelineUuid=arguments.pipelineUuid,
                stepUuid=arguments.stepUuid,
                testCaseUuid=arguments.testCaseUuid
            );
    }

    /**
     * List pipeline caches.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines-config/caches
     */
    public any function pipelines_config_caches(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineCaches();
    }

    /**
     * Delete pipeline caches (optionally by cache name).
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines-config/caches
     */
    public any function pipelines_config_caches_delete(
        string name="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineCaches(
                name=arguments.name
            );
    }

    /**
     * Delete a specific pipeline cache by uuid.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines-config/caches/{cache_uuid}
     */
    public any function pipelines_config_caches_delete_cache(
        required string cacheUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineCache(
                cacheUuid=arguments.cacheUuid
            );
    }

    /**
     * Get cache content URI for a cache uuid.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines-config/caches/{cache_uuid}/content-uri
     */
    public any function pipelines_config_caches_content_uri(
        required string cacheUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineCacheContentUri(
                cacheUuid=arguments.cacheUuid
            );
    }

    /**
     * List repository pipeline runners.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines-config/runners
     */
    public any function pipelines_config_runners(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineRunners();
    }

    /**
     * Create a repository pipeline runner.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pipelines-config/runners
     */
    public any function pipelines_config_runners_create(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPipelineRunner();
    }

    /**
     * Get a repository pipeline runner.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines-config/runners/{runner_uuid}
     */
    public any function pipelines_config_runners_get(
        required string runnerUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineRunner(
                runnerUuid=arguments.runnerUuid
            );
    }

    /**
     * Update a repository pipeline runner.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines-config/runners/{runner_uuid}
     */
    public any function pipelines_config_runners_update(
        required string runnerUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelineRunner(
                runnerUuid=arguments.runnerUuid
            );
    }

    /**
     * Delete a repository pipeline runner.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines-config/runners/{runner_uuid}
     */
    public any function pipelines_config_runners_delete(
        required string runnerUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineRunner(
                runnerUuid=arguments.runnerUuid
            );
    }

    /**
     * Get pipelines configuration.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config
     */
    public any function pipelines_config(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelinesConfig();
    }

    /**
     * Update pipelines configuration.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines_config
     */
    public any function pipelines_config_update(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelinesConfig(
                configData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Update next pipelines build number.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines_config/build_number
     */
    public any function pipelines_config_build_number_update(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelinesBuildNumber(
                buildNumberData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * List pipeline schedules.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/schedules
     */
    public any function pipelines_config_schedules(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineSchedules();
    }

    /**
     * Create a pipeline schedule.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pipelines_config/schedules
     */
    public any function pipelines_config_schedules_create(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPipelineSchedule(
                scheduleData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Get a pipeline schedule.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/schedules/{schedule_uuid}
     */
    public any function pipelines_config_schedules_get(
        required string scheduleUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineSchedule(
                scheduleUuid=arguments.scheduleUuid
            );
    }

    /**
     * Update a pipeline schedule.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines_config/schedules/{schedule_uuid}
     */
    public any function pipelines_config_schedules_update(
        required string scheduleUuid,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelineSchedule(
                scheduleUuid=arguments.scheduleUuid,
                scheduleData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete a pipeline schedule.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines_config/schedules/{schedule_uuid}
     */
    public any function pipelines_config_schedules_delete(
        required string scheduleUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineSchedule(
                scheduleUuid=arguments.scheduleUuid
            );
    }

    /**
     * List executions of a schedule.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/schedules/{schedule_uuid}/executions
     */
    public any function pipelines_config_schedules_executions(
        required string scheduleUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineScheduleExecutions(
                scheduleUuid=arguments.scheduleUuid
            );
    }

    /**
     * Get pipelines SSH key pair.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/key_pair
     */
    public any function pipelines_config_ssh_key_pair(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineSshKeyPair();
    }

    /**
     * Update pipelines SSH key pair.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/key_pair
     */
    public any function pipelines_config_ssh_key_pair_update(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelineSshKeyPair(
                keyPairData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete pipelines SSH key pair.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/key_pair
     */
    public any function pipelines_config_ssh_key_pair_delete(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineSshKeyPair();
    }

    /**
     * List pipelines known hosts.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/known_hosts
     */
    public any function pipelines_config_ssh_known_hosts(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineKnownHosts();
    }

    /**
     * Create pipelines known host.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/known_hosts
     */
    public any function pipelines_config_ssh_known_hosts_create(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPipelineKnownHost(
                knownHostData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Get pipelines known host by uuid.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/known_hosts/{known_host_uuid}
     */
    public any function pipelines_config_ssh_known_hosts_get(
        required string knownHostUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineKnownHost(
                knownHostUuid=arguments.knownHostUuid
            );
    }

    /**
     * Update pipelines known host.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/known_hosts/{known_host_uuid}
     */
    public any function pipelines_config_ssh_known_hosts_update(
        required string knownHostUuid,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelineKnownHost(
                knownHostUuid=arguments.knownHostUuid,
                knownHostData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete pipelines known host.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines_config/ssh/known_hosts/{known_host_uuid}
     */
    public any function pipelines_config_ssh_known_hosts_delete(
        required string knownHostUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineKnownHost(
                knownHostUuid=arguments.knownHostUuid
            );
    }

    /**
     * List pipelines repository variables.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/variables
     */
    public any function pipelines_config_variables(
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineVariables();
    }

    /**
     * Create pipelines repository variable.
     * Maps to POST /repositories/{workspace}/{repo_slug}/pipelines_config/variables
     */
    public any function pipelines_config_variables_create(
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPipelineVariable(
                variableData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Get pipelines repository variable by uuid.
     * Maps to GET /repositories/{workspace}/{repo_slug}/pipelines_config/variables/{variable_uuid}
     */
    public any function pipelines_config_variables_get(
        required string variableUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPipelineVariable(
                variableUuid=arguments.variableUuid
            );
    }

    /**
     * Update pipelines repository variable.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/pipelines_config/variables/{variable_uuid}
     */
    public any function pipelines_config_variables_update(
        required string variableUuid,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelineVariable(
                variableUuid=arguments.variableUuid,
                variableData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete pipelines repository variable.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/pipelines_config/variables/{variable_uuid}
     */
    public any function pipelines_config_variables_delete(
        required string variableUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineVariable(
                variableUuid=arguments.variableUuid
            );
    }

    /**
     * List variables for an environment.
     * Maps to GET /repositories/{workspace}/{repo_slug}/deployments_config/environments/{environment_uuid}/variables
     */
    public any function pipelines_environments_variables(
        required string environmentUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listPipelineEnvironmentVariables(
                environmentUuid=arguments.environmentUuid
            );
    }

    /**
     * Create a variable for an environment.
     * Maps to POST /repositories/{workspace}/{repo_slug}/deployments_config/environments/{environment_uuid}/variables
     */
    public any function pipelines_environments_variables_create(
        required string environmentUuid,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .createPipelineEnvironmentVariable(
                environmentUuid=arguments.environmentUuid,
                variableData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Update a variable for an environment.
     * Maps to PUT /repositories/{workspace}/{repo_slug}/deployments_config/environments/{environment_uuid}/variables/{variable_uuid}
     */
    public any function pipelines_environments_variables_update(
        required string environmentUuid,
        required string variableUuid,
        required string dataFile,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePipelineEnvironmentVariable(
                environmentUuid=arguments.environmentUuid,
                variableUuid=arguments.variableUuid,
                variableData=readJsonFile(arguments.dataFile)
            );
    }

    /**
     * Delete a variable for an environment.
     * Maps to DELETE /repositories/{workspace}/{repo_slug}/deployments_config/environments/{environment_uuid}/variables/{variable_uuid}
     */
    public any function pipelines_environments_variables_delete(
        required string environmentUuid,
        required string variableUuid,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .deletePipelineEnvironmentVariable(
                environmentUuid=arguments.environmentUuid,
                variableUuid=arguments.variableUuid
            );
    }
    // --- Refs (API group: /refs) ---

    /**
     * List tags.
     * Maps to GET /repositories/{workspace}/{repo_slug}/refs/tags
     */
    public any function refs_tags(
        string q="",
        string sort="",
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format=""
    ){
        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);
        var res = bb.listTags(
            q=arguments.q,
            sort=arguments.sort,
            page=Int(arguments.page),
            pagelen=Int(arguments.pagelen)
        );

        if(lCase(arguments.format) EQ "json" OR lCase(arguments.format) EQ "json-compact"){
            if(isSimpleValue(res) AND isJSON(res)){
                return res;
            }
            return serializeJson(res, lCase(arguments.format) EQ "json-compact");
        }

        return res;
    }

    // --- Decorated helpers (not 1:1 REST endpoints) ---

    /**
     * Build a weekly "merged to main" release context without requiring a git clone.
     *
     * This is intended to feed an AI summarizer (e.g. Oz/Warp) or to be rendered into a human report.
     *
     * Strategy:
     * - List MERGED PRs into the destination branch (default: main)
     * - Filter locally by merged timestamp (prefers closed_on)
     * - Optionally fetch diff/diffstat/commits per PR and compute aggregates
     */
    public any function weeklyReleaseContext(
        string branch="main",
        string sinceISO="",
        string untilISO="",
        boolean includeDiffstat=true,
        boolean includeDiff=false,
        boolean includeCommits=false,
        string mode="detailed",
        boolean includeBaseHead=false,
        numeric maxPRs=200,
        numeric prPageLen=50,
        numeric childPageLen=100,
        numeric maxFilesPerPR=500,
        numeric maxCommitsPerPR=200,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format="json",
        string outputPath=""
    ){
        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);
        var modeNorm = lCase(trim(arguments.mode));
        if(modeNorm NEQ "fast" AND modeNorm NEQ "detailed"){
            modeNorm = "detailed";
        }
        var shouldIncludeDiffstat = arguments.includeDiffstat;
        var shouldIncludeDiff = arguments.includeDiff;
        var shouldIncludeCommits = arguments.includeCommits;
        if(modeNorm EQ "fast"){
            shouldIncludeDiffstat = false;
            shouldIncludeDiff = false;
            shouldIncludeCommits = false;
        }

        // Robust ISO8601 parsing.
        // Primary: Lucee/CFML's parseDateTime(), which typically handles `...Z` and `...+00:00`.
        // Fallbacks: java.time parsers.
        var instant = createObject("java", "java.time.Instant");
        var odt = createObject("java", "java.time.OffsetDateTime");

        function isoToEpochMillis(required string iso){
            try {
                var d = parseDateTime(arguments.iso);
                return d.getTime();
            } catch(any e0){
                // ignore
            }
            try {
                return instant.parse(arguments.iso).toEpochMilli();
            } catch(any e1){
                // ignore
            }
            try {
                return odt.parse(arguments.iso).toInstant().toEpochMilli();
            } catch(any e2){
                return 0;
            }
        }

        // Defaults: last 7 days, UTC
        var nowUtc = dateConvert("local2utc", now());
        if(!Len(arguments.untilISO)){
            arguments.untilISO = dateTimeFormat(nowUtc, "yyyy-mm-dd'T'HH:nn:ss") & "Z";
        }
        if(!Len(arguments.sinceISO)){
            var sinceUtc = dateAdd("d", -7, nowUtc);
            arguments.sinceISO = dateTimeFormat(sinceUtc, "yyyy-mm-dd'T'HH:nn:ss") & "Z";
        }

        var sinceMs = isoToEpochMillis(arguments.sinceISO);
        var untilMs = isoToEpochMillis(arguments.untilISO);
        if(sinceMs EQ 0 OR untilMs EQ 0){
            throw("sinceISO/untilISO must be ISO8601 (e.g. 2026-03-01T00:00:00Z). Got sinceISO='#arguments.sinceISO#' untilISO='#arguments.untilISO#'.");
        }
        if(untilMs LT sinceMs){
            throw("untilISO must be >= sinceISO. Got sinceISO='#arguments.sinceISO#' untilISO='#arguments.untilISO#'.");
        }

        var headSha = "";
        var baseSha = "";

        // Optional, disabled by default for PR-window reporting performance.
        if(arguments.includeBaseHead){
            try {
                var brStr = bb.getBranchRef(branch=arguments.branch);
                if(isSimpleValue(brStr) AND isJSON(brStr)){
                    var br = deserializeJson(brStr);
                    headSha = br.target?.hash ?: "";
                }
            } catch(any e){
                // ignore; we'll leave head/base blank if unavailable
            }

            if(Len(headSha)){
                var cPage = 1;
                var maxPages = 25; // safety
                while(cPage LTE maxPages AND !Len(baseSha)){
                    var cStr = bb.listCommits(revision=arguments.branch, page=cPage, pagelen=100);
                    if(!isSimpleValue(cStr) OR !isJSON(cStr)){
                        break;
                    }
                    var cs = deserializeJson(cStr);
                    if(!isStruct(cs) OR !structKeyExists(cs, "values") OR !isArray(cs.values) OR arrayLen(cs.values) EQ 0){
                        break;
                    }

                    for(var cv in cs.values){
                        var dStr = cv.date ?: "";
                        var dMs = Len(dStr) ? isoToEpochMillis(dStr) : 0;
                        if(dMs GT 0 AND dMs LT sinceMs){
                            baseSha = cv.hash ?: "";
                            break;
                        }
                    }

                    if(Len(baseSha) OR !structKeyExists(cs, "next")){
                        break;
                    }
                    cPage++;
                }
            }
        }

        var qFilter = 'destination.branch.name="' & arguments.branch & '" AND closed_on >= "' & arguments.sinceISO & '" AND closed_on <= "' & arguments.untilISO & '"';
        var prFields = "next,values.id,values.title,values.state,values.closed_on,values.updated_on,values.author.display_name,values.source.branch.name,values.destination.branch.name,values.merge_commit.hash,values.links.html.href,values.summary.raw,values.description";
        var diffstatFields = "next,values.lines_added,values.lines_removed,values.new.path,values.old.path";
        var commitFields = "next,values.hash,values.date,values.message,values.author.user.display_name,values.author.raw";

        var collected = [];
        var page = 1;
        while(arrayLen(collected) LT Int(arguments.maxPRs)){
            var resStr = bb.listPullRequests(
                state="MERGED",
                q=qFilter,
                sort="-closed_on",
                page=page,
                pagelen=Int(arguments.prPageLen),
                fields=prFields
            );

            if(!isSimpleValue(resStr) OR !isJSON(resStr)){
                throw("Expected JSON string from listPullRequests()");
            }

            var res = deserializeJson(resStr);
            if(!isStruct(res) OR !structKeyExists(res, "values") OR !isArray(res.values) OR arrayLen(res.values) EQ 0){
                break;
            }

            for(var pr in res.values){
                var mergedOn = pr.closed_on ?: pr.updated_on;
                var mergedMs = Len(mergedOn) ? isoToEpochMillis(mergedOn) : 0;
                if(mergedMs EQ 0 OR mergedMs LT sinceMs OR mergedMs GT untilMs){
                    continue;
                }

                arrayAppend(collected, pr);
                if(arrayLen(collected) GTE Int(arguments.maxPRs)){
                    break;
                }
            }

            if(!structKeyExists(res, "next")){
                break;
            }
            page++;
        }

        var prContexts = [];
        var totals = {
            pr_count = arrayLen(collected),
            unique_authors = {},
            files_changed = 0,
            lines_added = 0,
            lines_removed = 0,
            top_level_paths = {}
        };

        for(var pr in collected){
            var prCtx = {
                id = pr.id,
                title = pr.title,
                state = pr.state,
                merged_on = pr.closed_on ?: pr.updated_on,
                author = pr.author?.display_name ?: "",
                source_branch = pr.source?.branch?.name ?: "",
                destination_branch = pr.destination?.branch?.name ?: "",
                merge_commit = pr.merge_commit?.hash ?: "",
                link = pr.links?.html?.href ?: "",
                summary = pr.summary?.raw ?: pr.description ?: ""
            };

            if(Len(prCtx.author)){
                totals.unique_authors[prCtx.author] = true;
            }
            if(shouldIncludeDiff){
                prCtx.diff = "";
                try {
                    prCtx.diff = bb.getPullRequestDiff(
                        pullRequestId=pr.id
                    );
                } catch(any e){
                    // Keep payload stable even if diff fetch fails for one PR.
                    prCtx.diff = "";
                }
            }

            if(shouldIncludeDiffstat){
                var diffValues = [];
                var dsPage = 1;

                while(arrayLen(diffValues) LT Int(arguments.maxFilesPerPR)){
                    var dsStr = bb.getPullRequestDiffStat(
                        pullRequestId=pr.id,
                        page=dsPage,
                        pagelen=Int(arguments.childPageLen),
                        fields=diffstatFields
                    );
                    if(!isSimpleValue(dsStr) OR !isJSON(dsStr)){
                        break;
                    }
                    var ds = deserializeJson(dsStr);
                    if(!isStruct(ds) OR !structKeyExists(ds, "values") OR !isArray(ds.values) OR arrayLen(ds.values) EQ 0){
                        break;
                    }

                    for(var v in ds.values){
                        arrayAppend(diffValues, v);
                        if(arrayLen(diffValues) GTE Int(arguments.maxFilesPerPR)){
                            break;
                        }
                    }
                    if(!structKeyExists(ds, "next")){
                        break;
                    }
                    dsPage++;
                }

                var prStats = {
                    files_changed = arrayLen(diffValues),
                    lines_added = 0,
                    lines_removed = 0,
                    top_level_paths = {},
                    sample_paths = []
                };

                for(var dv in diffValues){
                    if(structKeyExists(dv, "lines_added")){
                        prStats.lines_added += Int(dv.lines_added);
                    }
                    if(structKeyExists(dv, "lines_removed")){
                        prStats.lines_removed += Int(dv.lines_removed);
                    }

                    var p = dv.new?.path ?: dv.old?.path ?: "";
                    if(Len(p)){
                        if(arrayLen(prStats.sample_paths) LT 50){
                            arrayAppend(prStats.sample_paths, p);
                        }
                        var top = listFirst(p, "/");
                        prStats.top_level_paths[top] = (prStats.top_level_paths[top] ?: 0) + 1;
                    }
                }

                prCtx.diffstat = prStats;
                totals.files_changed += prStats.files_changed;
                totals.lines_added += prStats.lines_added;
                totals.lines_removed += prStats.lines_removed;

                for(var k in prStats.top_level_paths){
                    totals.top_level_paths[k] = (totals.top_level_paths[k] ?: 0) + prStats.top_level_paths[k];
                }
            }

            if(shouldIncludeCommits){
                var commitValues = [];
                var cPage = 1;

                while(arrayLen(commitValues) LT Int(arguments.maxCommitsPerPR)){
                    var cStr = bb.listPullRequestCommits(
                        pullRequestId=pr.id,
                        page=cPage,
                        pagelen=Int(arguments.childPageLen),
                        fields=commitFields
                    );
                    if(!isSimpleValue(cStr) OR !isJSON(cStr)){
                        break;
                    }
                    var cs = deserializeJson(cStr);
                    if(!isStruct(cs) OR !structKeyExists(cs, "values") OR !isArray(cs.values) OR arrayLen(cs.values) EQ 0){
                        break;
                    }

                    for(var cv in cs.values){
                        arrayAppend(commitValues, {
                            hash = cv.hash ?: "",
                            date = cv.date ?: "",
                            message = cv.message ?: "",
                            author = cv.author?.user?.display_name ?: cv.author?.raw ?: ""
                        });
                        if(arrayLen(commitValues) GTE Int(arguments.maxCommitsPerPR)){
                            break;
                        }
                    }

                    if(!structKeyExists(cs, "next")){
                        break;
                    }
                    cPage++;
                }

                prCtx.commits = commitValues;
                prCtx.commit_count = arrayLen(commitValues);
            }

            arrayAppend(prContexts, prCtx);
        }

        var result = {
            workspace = Len(arguments.workspace) ? arguments.workspace : getEnv("BITBUCKET_WORKSPACE", ""),
            repoSlug = Len(arguments.repoSlug) ? arguments.repoSlug : getEnv("BITBUCKET_REPO_SLUG", ""),
            branch = arguments.branch,
            since = arguments.sinceISO,
            until = arguments.untilISO,
            mode = modeNorm,
            base = baseSha,
            head = headSha,
            totals = {
                pr_count = totals.pr_count,
                author_count = structCount(totals.unique_authors),
                files_changed = totals.files_changed,
                lines_added = totals.lines_added,
                lines_removed = totals.lines_removed,
                top_level_paths = totals.top_level_paths
            },
            pullrequests = prContexts
        };

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, serializeJson(result, lCase(arguments.format) EQ "json-compact"));
            return "Written output to #absOutputPath#";
        }
        if(lCase(arguments.format) EQ "json-compact"){
            return serializeJson(result, true);
        }
        return serializeJson(result, false);
    }

    /**
     * List default reviewers.
     * Maps to GET /repositories/{workspace}/{repo_slug}/default-reviewers
     */
    public any function pullrequests_default_reviewers(
        numeric page=0,
        numeric pagelen=0,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .listDefaultReviewers(
                page=arguments.page,
                pagelen=arguments.pagelen
            );
    }

    /**
     * Decorated helper: add reviewers to an existing pull request.
     * Updates PR reviewers via PUT /repositories/{workspace}/{repo_slug}/pullrequests/{pull_request_id}
     */
    public any function addReviewers(
        required numeric pullRequestId,
        required string reviewerUuids,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var reviewerUuidList = listToArray(arguments.reviewerUuids, ",");
        var normalizedReviewerUuids = [];
        
        for(var reviewerUuid in reviewerUuidList){
            var uuidValue = trim(reviewerUuid & "");
            if(!Len(uuidValue)){
                continue;
            }
            if(left(uuidValue, 1) NEQ "{"){
                uuidValue = "{#uuidValue#";
            }
            if(right(uuidValue, 1) NEQ "}"){
                uuidValue = "#uuidValue#}";
            }
            arrayAppend(normalizedReviewerUuids, uuidValue);
        }

        if(!arrayLen(normalizedReviewerUuids)){
            throw("reviewerUuids must contain at least one UUID");
        }

        return createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .updatePullRequestReviewers(
                pullRequestId=arguments.pullRequestId,
                reviewerUuids=normalizedReviewerUuids
            );
    }

    /**
     * Return one combined payload for a single pull request:
     * - PR metadata
     * - Diffstat (auto-paginated)
     * - Raw unified diff text
     */
    public any function getPullRequestContext(
        numeric pullRequestId=0,
        numeric diffstatPageLen=100,
        numeric maxDiffstatPages=100,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", ""),
        string format="json",
        string outputPath=""
    ){
        var prId = Int(arguments.pullRequestId ?: getEnv("BITBUCKET_PR_ID", "0"));
        if(prId LTE 0){
            throw("pullRequestId is required (or set BITBUCKET_PR_ID).");
        }

        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);

        var prRaw = bb.getPullRequest(pullRequestId=prId);
        var prData = prRaw;
        if(isSimpleValue(prRaw) AND isJSON(prRaw)){
            prData = deserializeJson(prRaw);
        }

        var diffstatValues = [];
        var diffstatMeta = {};
        var diffstatRawFallback = "";
        var hasDiffstatRawFallback = false;

        var dsPageLen = Int(arguments.diffstatPageLen);
        if(dsPageLen LTE 0){
            dsPageLen = 100;
        }
        var dsMaxPages = Int(arguments.maxDiffstatPages);
        if(dsMaxPages LTE 0){
            dsMaxPages = 1;
        }

        var dsPage = 1;
        while(dsPage LTE dsMaxPages){
            var dsRaw = bb.getPullRequestDiffStat(
                pullRequestId=prId,
                page=dsPage,
                pagelen=dsPageLen
            );

            if(!isSimpleValue(dsRaw) OR !isJSON(dsRaw)){
                diffstatRawFallback = dsRaw;
                hasDiffstatRawFallback = true;
                break;
            }

            var ds = deserializeJson(dsRaw);
            if(!isStruct(ds)){
                diffstatRawFallback = dsRaw;
                hasDiffstatRawFallback = true;
                break;
            }

            for(var k in ds){
                if(k NEQ "values" AND k NEQ "next"){
                    diffstatMeta[k] = ds[k];
                }
            }

            if(structKeyExists(ds, "values") AND isArray(ds.values)){
                for(var v in ds.values){
                    arrayAppend(diffstatValues, v);
                }
            }

            if(!structKeyExists(ds, "next")){
                break;
            }

            dsPage++;
        }

        var diffstatData = {};
        if(hasDiffstatRawFallback){
            diffstatData = diffstatRawFallback;
        }
        else{
            diffstatData = duplicate(diffstatMeta);
            diffstatData.values = diffstatValues;
            diffstatData.page = 1;
            diffstatData.pagelen = dsPageLen;
            diffstatData.size = arrayLen(diffstatValues);
            if(dsPage GT dsMaxPages){
                diffstatData.truncated = true;
                diffstatData.truncated_reason = "maxDiffstatPages reached";
            }
        }

        var diffContent = bb.getPullRequestDiff(pullRequestId=prId);

        var result = {
            workspace = Len(arguments.workspace) ? arguments.workspace : getEnv("BITBUCKET_WORKSPACE", ""),
            repoSlug = Len(arguments.repoSlug) ? arguments.repoSlug : getEnv("BITBUCKET_REPO_SLUG", ""),
            pullRequestId = prId,
            pr = prData,
            diffstat = diffstatData,
            diff = diffContent
        };
         if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, serializeJson(result, lCase(arguments.format) EQ "json-compact"));
            return "Written output to #absOutputPath#";
        }
        if(lCase(arguments.format) EQ "json-compact"){
            return serializeJson(result, true);
        }
        return serializeJson(result, false);
    }


    /**
     * Returns the Diff text of a pull request
     *
     * @pullRequestId The id of the pull request
     */
    public any function getPullRequestDiff(
        numeric pullRequestId = 0,
        string outputPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        // For this function we need a pull request id
        var prId = arguments.pullRequestId ?: getEnv("BITBUCKET_PR_ID", "");

        var diffContent = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken)
            .getPullRequestDiff(
                pullRequestId = prId
            );

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            if(isStruct(diffContent) OR isArray(diffContent)){
                fileWrite(absOutputPath, serializeJson(diffContent));
            }
            else{
                fileWrite(absOutputPath, diffContent);
            }
        }

        return diffContent;
    }
    
    /*
        Filter annotations using a diff file to only include those that are in the diff
        @reportPath string Path to the Pull Request report file
        @diffFilePath string Path to the diff file
        @rootPath string Root path to strip from annotation paths
    */
    function filterAnnotationsInDiff(string reportPath, string diffFilePath, string rootPath="", string outputPath="") {
        var filtered = [];
        var reportData = deserializeJson(fileRead(reportPath));
        var diffStruct = parseDiffSimple(diffFilePath)
        var changedLinesByFile = {};
        
       

        for(var filePath in diffStruct){
            changedLinesByFile[filePath] = [];
            changedLinesByFile[filePath] = diffStruct[filePath].map(
                function(lineDiff){
                    return lineDiff.line;
                }
            );
        }
        // out(changedLinesByFile);
        
        var foundAnnotations = []
        
        // Note: making the assumption that the changedLinesByFile are sequential. Kinda important.

        for(var filePath in changedLinesByFile){
            // dump(var=filePath, label="Processing file: " & filePath);
            for(var lineNum in changedLinesByFile[filePath]){
                // dump(var=lineNum, label="Changed line: " & lineNum);
                // Now loop through all the annotations to see if they match
                for(var annotation in reportData.annotations){
                    // out("Annotation real path: " & annotation.path);
                    var annotationRealPath = Right((annotation.path), Len(annotation.path) - Len(rootPath));
                    // out("Annotation real path: " & annotationRealPath);
                    if(annotationRealPath NEQ filePath){
                        continue;
                    }
                    // dump(var=annotation, label="Checking annotation " & annotationRealPath & ":" & annotation.line);
                    // If we have an end_line, check the range
                    if( structKeyExists(annotation, "end_line") ){
                        if( lineNum GTE annotation.line AND lineNum LTE annotation.end_line ){
                            // dump(var=annotation, label="FOUND annotation in range " & annotationRealPath & ":" & annotation.line & "-" & annotation.end_line);
                            if(!arrayContains(foundAnnotations, annotation)){
                                annotation.path = annotationRealPath;
                                arrayAppend(foundAnnotations, annotation);
                            }
                        }
                    } else {
                        if( lineNum EQ annotation.line ){
                            // dump(var=annotation, label="FOUND annotation at line " & annotationRealPath & ":" & annotation.line);
                            if(!arrayContains(foundAnnotations, annotation)){
                                annotation.path = annotationRealPath;
                                arrayAppend(foundAnnotations, annotation);
                            }
                        }
                    }
                }
            }
            
        }
        if(Len(arguments.outputPath)){
                // Save to file
                var absOutputPath = getAbsolutePath(variables.cwd, outputPath);
                fileWrite(absOutputPath, serializeJson(foundAnnotations));
                return foundAnnotations;
        }

        return foundAnnotations;
    }

    /**
     * Simple helper to convert a YAML file to native CFML data.
     * Optionally writes JSON output to disk.
     */
    public any function convertYamlToJson(
        required string filePath,
        string outputPath=""
    ){
        var absInputPath = getAbsolutePath(variables.cwd, arguments.filePath);
        if(!fileExists(absInputPath)){
            throw("YAML file not found: #absInputPath#");
        }

        var yamlReader = new YAML2CFML();
        var yamlData = yamlReader.read(absInputPath);

        if(Len(arguments.outputPath)){
            var absOutputPath = getAbsolutePath(variables.cwd, arguments.outputPath);
            fileWrite(absOutputPath, serializeJson(yamlData, true));
        }

        return yamlData;
    }



    /**
     * Backward-compatible shortcut to download a file from a Bitbucket API URL.
     */
    public any function downloadFile(
        required string fileURL,
        required string destinationPath,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ){
        var bb = createClient(
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken
        );

        var absDownloadPath = getAbsolutePath(variables.cwd, arguments.destinationPath);
         bb.downloadFile(
            fileURL=arguments.fileURL,
            destinationPath=absDownloadPath
        );

      
        
        return "Downloaded file from #arguments.fileURL# to #absDownloadPath#";
    }

    public any function downloadPRFiles(
        numeric pullRequestId = 0,
        string downloadPath="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ) {
        var prId = arguments.pullRequestId ?: getEnv("BITBUCKET_PR_ID", "");
        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);

        var prFiles = bb.getPullRequestDiffStat(
            pullRequestId = prId,
            page = 1,
            pagelen = 100
        );

        // When BitbucketClient returns "bare JSON" (string), we need to deserialize
        // here because this helper iterates the diffstat response.
        if(isSimpleValue(prFiles) AND isJSON(prFiles)){
            prFiles = deserializeJson(prFiles);
        }

        if(!isStruct(prFiles) OR !structKeyExists(prFiles, "values") OR !isArray(prFiles.values)){
            throw("Unexpected diffstat response; expected JSON object with a 'values' array.");
        }

        var absDownloadPath = getAbsolutePath(variables.cwd, arguments.downloadPath);
       
        // Create download path if it doesn't exist
        if(!directoryExists(absDownloadPath)){
            directoryCreate(absDownloadPath, true);
        }

        var result = {
            downloaded = [],
            skipped = [],
            errors = []
        };

        for(var fileInfo in prFiles.values){

            var fileURL = fileInfo.new?.links?.self?.href ?: "";
            var filePath =  fileInfo?.new?.path ?: fileInfo?.old?.path ?: "";

            if(fileInfo.status EQ "removed"){
                arrayAppend(result.skipped, {
                    reason = "removed",
                    file = filePath,
                    url = fileURL
                });
                continue;
            }

            if(!Len(fileURL) OR !Len(filePath)){
                arrayAppend(result.skipped, {
                    reason = "missing url or path",
                    file = filePath,
                    url = fileURL,
                    info = fileInfo
                });
                continue;
            }
          
            try{
                bb.downloadFile(
                    fileURL = fileURL,
                    destinationPath = absDownloadPath & "/" & filePath
                );

                arrayAppend(result.downloaded, {
                    file = filePath,
                    url = fileURL,
                    path = absDownloadPath & "/" & filePath
                });
                
            }
            catch (any ex) {
                arrayAppend(result.errors, {
                    file = filePath,
                    url = fileURL,
                    message = ex.message
                });
            }
            
        }

        result.summary = "Downloaded " & arrayLen(result.downloaded) & " files to " & absDownloadPath;
        return result;
    }


    /**
     * DEPRECATED: use reports_create.
     * posts a report to bitbucket from a report formatted json file
     *
     * @commit the commit
     * @reportPath the path to the bitbucket report json file
     * @reportTitle the title of the report (optional) If not provided, will use the title from the report file
     */
    public any function postReport(
        required string commit, 
        required string reportPath, 
        required string reportId, 
        string title="",
        string details="",
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ) {

        // lucli bitbucket postReport commit="${BITBUCKET_COMMIT}" reportPath="${REPORT_PATH}" reportId="${reportTitle}" title="Linting Report" details="Automated linting report"
        // echo(arguments.repoSlug);
        if(!Len(arguments.title) AND !Len(arguments.details)){
            return reports_create(
                commit=arguments.commit,
                dataFile=arguments.reportPath,
                reportId=arguments.reportID,
                workspace=arguments.workspace,
                repoSlug=arguments.repoSlug,
                authToken=arguments.authToken
            );
        }
        var bb = createClient(workspace=arguments.workspace, repoSlug=arguments.repoSlug, authToken=arguments.authToken);

        var absReportPath = getAbsolutePath(variables.cwd, arguments.reportPath);
        var reportData = deserializeJson(fileRead(absReportPath));
        if(Len(title)){
            reportData.title = title;
        }
        if(Len(details)){
            reportData.details = details;
        }

        var response = bb.createReport(
            reportData = reportData,
            commit = commit,
            reportID = reportID
        );

        return response;

    }
   
    /**
     * DEPRECATED: use reports_annotations_post.
     * adds annotations to a report
     *
     * @commit the commit
     * @annotationFile the path to the annotation file with a JSON array of annotations
     * @reportTitle the title of the report to add the annotations to
     */

    public any function postReportAnnotations(
        required string commit,
        required string annotationFile,
        required string reportId,
        string workspace=getEnv("BITBUCKET_WORKSPACE", ""),
        string repoSlug=getEnv("BITBUCKET_REPO_SLUG", ""),
        string authToken=getEnv("BITBUCKET_AUTH_TOKEN", "")
    ) {
        return reports_annotations_post(
            commit=arguments.commit,
            dataFile=arguments.annotationFile,
            reportId=arguments.reportId,
            workspace=arguments.workspace,
            repoSlug=arguments.repoSlug,
            authToken=arguments.authToken
        );
    }



    /**
     * Function to parse a diff file to extract the file and changed lines
     *
     * @diffFilePath the path to the diff text file (not the diffstat)
     */
    private function parseDiffSimple(diffFilePath) {
        var result = {};
        var diffContent = fileRead(diffFilePath);
        var lines = listToArray(diffContent, chr(10));
        
        var currentFile = "";
        var currentLineNum = 0;
        var lastWasRemoved = false;
        var lastRemovedLine = 0;
        
        for (var line in lines) {
           
            // Extract file path from diff header
            if (reFindNoCase("^diff --git", line)) {
                var pathMatch = reMatch("b/(.+?)(\s|$)", line);
               
                if (arrayLen(pathMatch) > 0) {
                    currentFile = pathMatch[1].substring(2);
                    if (!structKeyExists(result, currentFile)) {
                        result[currentFile] = [];
                    }
                }
                lastWasRemoved = false;
            }
            
            // Extract line number from hunk header
            if (reFindNoCase("^@@", line)) {
                var hunkMatch = reMatch("\+(\d+)(?:,(\d+))?", line);
                if (arrayLen(hunkMatch) > 0) {
                    currentLineNum = val(hunkMatch[1]);
                }
                lastWasRemoved = false;
            }
            
            // Track added lines
            if (left(line, 1) == "+" && !reFindNoCase("^\+\+\+", line)) {
                var action = "added";
                
                // If last line was removed, mark as changed instead
                // if (lastWasRemoved) {
                //     action = "changed";
                //     // Update the last removed entry to changed
                //     var lastEntry = result[currentFile][arrayLen(result[currentFile])];
                    
                // }
                
                if (currentFile != "") {
                    arrayAppend(result[currentFile], {
                        line: currentLineNum,
                        action: action
                    });
                }
                currentLineNum++;
                lastWasRemoved = false;
            }
            // Track removed lines
            else if (left(line, 1) == "-" && !reFindNoCase("^---", line)) {
                if (currentFile != "") {
                    arrayAppend(result[currentFile], {
                        line: currentLineNum,
                        action: "removed"
                    });
                }
                lastWasRemoved = true;
                lastRemovedLine = currentLineNum;
            }
            // Context lines increment line counter
            else if (left(line, 1) == " ") {
                currentLineNum++;
                lastWasRemoved = false;
            }
        }
        
        return result;
    }

}