Jira and Confluence tool examples added

[luchezarno]

Jira and Confluence tool examples added in Examples folder
Feel free to use it as you wish

[Copilot]

Pull request overview

This PR adds PowerShell example scripts for interacting with Jira and Confluence APIs, providing developers with ready-to-use functions for common operations like retrieving task information, searching pages, and managing Confluence content.

Key Changes:

• Added Get-JiraTaskInfo function for retrieving Jira task details via REST API
• Added 8 Confluence functions covering space navigation, page search, content management, and CRUD operations

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 10 comments.

File	Description
examples/Get-JiraTaskInfo.ps1	Implements function to retrieve Jira task information using PAT authentication
examples/Find-InConfluence.ps1	Implements comprehensive Confluence API wrapper functions for searching, reading, and managing pages and spaces

---

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

[Copilot]

Error messages should be more descriptive. The generic message "Failed to retrieve Jira task information" doesn't provide context about what might have gone wrong (e.g., authentication failure, task not found, network error). Consider making the error message more specific or including the HTTP status code if available.

Suggested change

	@{
	"Error" = "Failed to retrieve Jira task information"
	"ErrorMessage" = $_.Exception.Message
	"TaskCode" = $JiraTaskCode
	# Try to extract HTTP status information from the exception, if available
	$statusCode = $null
	$statusDescription = $null
	if ($_.Exception.Response -and $_.Exception.Response.StatusCode) {
	$statusCode = $_.Exception.Response.StatusCode.value__
	$statusDescription = $_.Exception.Response.StatusDescription
	}
	$errorText = "Failed to retrieve Jira task information"
	if ($statusCode) {
	$errorText += " (HTTP Status: $statusCode"
	if ($statusDescription) {
	$errorText += " $statusDescription"
	}
	$errorText += ")"
	}
	@{
	"Error" = $errorText
	"ErrorMessage" = $_.Exception.Message
	"TaskCode" = $JiraTaskCode
	"StatusCode" = $statusCode
	"StatusDescription" = $statusDescription
	"ApiUrl" = $apiUrl

[Copilot]

The search position logic may not work correctly for case-insensitive searches. The CQL query text~'$searchText' performs a fuzzy/case-insensitive search, but IndexOf is case-sensitive by default. This could result in "No match found" (HasMatch = false) even when the CQL search returned the page. Consider using IndexOf with StringComparison.OrdinalIgnoreCase for consistency.

[Copilot]

The CQL query string in Get-PageIdByTitleInConfluence is built by concatenating unescaped user-controlled values ($title, $spaceKey) directly into the CQL expression, which allows CQL injection if these parameters contain quotes or operators. An attacker who can influence title could break out of the quoted literal (e.g. by including ' OR ...) and alter the query to bypass intended space scoping or search constraints, potentially reading unintended content under the privileges of the PAT used. You should properly escape or parameterize user input in the CQL string (e.g. safely encoding quotes and special characters inside the CQL literal) before sending it to Confluence.

Suggested change

	# create CQL
	if ($spaceKey) {
	$cql = "type=page AND title='$title' AND space='$spaceKey'"
	} else {
	$cql = "type=page AND text='$title'"
	# escape user-controlled values for safe use in CQL string literals
	$escapedTitle = $title -replace '\\', '\\\\'
	$escapedTitle = $escapedTitle -replace "'", "\'"
	$escapedSpaceKey = $spaceKey
	if ($escapedSpaceKey) {
	$escapedSpaceKey = $escapedSpaceKey -replace '\\', '\\\\'
	$escapedSpaceKey = $escapedSpaceKey -replace "'", "\'"
	}
	# create CQL
	if ($spaceKey) {
	$cql = "type=page AND title='$escapedTitle' AND space='$escapedSpaceKey'"
	} else {
	$cql = "type=page AND text='$escapedTitle'"

[luchezarno]

Could you please rerun Copilot?

[dfinke]

@luchezarno Excellent work on your first PRs. Thanks for jumping through the hoops to tighten it up.

I need to update the changelog/readme and psd1 version. Then I can publish.

Like I mentioned, I wish I had access to the subsytems so I could try some things.

PowerShell functions like this can be used in an MCP setup, as standalone agents and in my new feature as skills (ported the new Claude CLI skills pattern).

They each have their pros and cons. Plus, always good to have options.

[luchezarno]

@dfinke
BTW, somewhere in YouTube I found this neat Assistent Promt for PowerShell Assistent. Works like a charm for me - makes very solid PS code descriptions.
Maybe could be useful to put in somewhere in PSAI

Code Analysis and Educational Enhancement Guide

Purpose

This document provides a comprehensive framework for analyzing and enhancing code readability while maintaining original functionality. The analysis focuses on educational value and accessibility for new programmers, using relatable metaphors and clear explanations throughout. Analysis Framework

Initial Documentation The analysis should begin with a header block that includes:
A clear explanation of the script's purpose and requirements All required modules or prerequisites Input and output expectations A real-world analogy for the script's function (e.g., "This script works like a mail sorting system...")

Educational Comments and Explanations Why Comments (Block Comments) Block comments should:
Explain each section's purpose using real-world metaphors Connect technical concepts to everyday experiences Provide reasoning behind the chosen approach

How Comments (Inline) Inline comments should:

Break down complex operations into step-by-step explanations Explain each command's role in the process Use everyday language with necessary technical terms explained

Learning Opportunity Markers Throughout the code, identify:

Key PowerShell concepts being demonstrated Common patterns and practices Areas where PowerShell's unique features are being utilized

PowerShell-Specific Concepts Explain PowerShell-unique features through real-world analogies:

Pipeline concepts ("Think of a pipeline like an assembly line...") Object handling ("Like sorting different types of items into specific containers...") Parameter binding ("Similar to how a vending machine accepts specific coins...") Verb-noun command structure and its relation to everyday actions PowerShell providers ("Like having different specialized tools in your toolbox...")

Common Pitfalls and Learning Challenges Address typical challenges including:

Variable scope issues ("Think of scope like rooms in a house...") Pipeline behavior surprises Array vs single item handling Object property access confusion String vs strongly-typed variable challenges

Add "Remember!" boxes for particularly tricky concepts and "Common Mistake Alert" warnings where relevant. 3. Code Clarity Enhancements Improve readability by:

Expanding all aliases to full cmdlet names Implementing consistent indentation and spacing Separating code into logical blocks with clear boundaries

For each variable:

Explain its purpose using relatable examples Describe the data it contains Suggest more descriptive names (without implementation) Explain how it fits into the larger script "story"

Process Breakdown For complex operations:
Break down pipeline operations into individual steps Use metaphors to explain each step Explain data flow through the script Identify common PowerShell scripting patterns

Best Practices and Considerations Note (without implementation):
Security considerations with real-world impact examples Error handling opportunities Logging recommendations Performance considerations Potential compatibility issues

Alternative Approaches Include educational discussion of:
Other ways to accomplish the same task Pros and cons of each approach Scenarios where different approaches might be more appropriate Real-world examples where different approaches excel

Post-Analysis Summary Provide a comprehensive review including:
Plain-language explanation of script operation List of key PowerShell concepts demonstrated Learning resources for introduced concepts Security and best practice considerations Suggested improvements (noting original functionality must be maintained) Common scripting patterns demonstrated List of identified potential pitfalls and how to avoid them PowerShell-specific patterns and their real-world equivalents Common error messages and their meaning Debugging tips specific to the script's functionality

PowerShell Concept Guide Explain PowerShell-specific elements:
How PowerShell differs from other scripting languages The "PowerShell way" of solving problems Object pipeline benefits and behavior PowerShell's relationship with .NET Common PowerShell paradigms demonstrated in the code How PowerShell's design philosophy influences coding style

Usage Instructions

Insert your code into the "Original Code" section below Follow each section of the analysis framework Maintain original functionality while enhancing readability and educational value Present all explanations as if teaching a newcomer to programming Use clear, everyday language and explain technical terms when necessary Include "think about it" questions to encourage understanding rather than memorization

ORIGINAL CODE

The code I would like you to analyze is this

[dfinke]

@luchezarno That looks very useful. Need to think about where to host it. Thank you!