Find-DbaAgentJob - Add regex Pattern filtering

[potatoqualitee]

Summary

• remove unreachable equality branches while preserving Get-JobList's effective wildcard behavior
• mark JobName and StepName as wildcard-capable
• add regex Pattern filtering with OR semantics, combinable with existing name/step filters
• keep ExcludeJobName as an exact match

Root cause

The helper tested wildcard presence with a regex that matches every string, so it always used -Like/-NotLike and left misleading dead branches. The approved issue design also requested regex job-name matching.

Validation

• tests/Find-DbaAgentJob.Tests.ps1: 6 unit tests passed, 0 failed (Pester 5.7.1)
• coverage includes ?, character classes, escaped literal *, step wildcards, regex OR semantics, metadata, and exact exclusion
• PSScriptAnalyzer 1.18.2: no findings for both changed functions
• git diff --check origin/development...HEAD

Review status

Claude Opus/high review completed after merge with VERDICT: CLEAN.

Closes #9600

[potatoqualitee]

@claude previously we had a number of discussions about wild cards and specifically @niphlod made really good points about wildcards and names. Please research and align the code with his position which I agree with. I think it's that we offer Pattern instead

[claude]

Claude finished @potatoqualitee's task in 5m 55s —— View job

---

Summary

I researched this and agree with the direction — but I could not push a fix in this run because the execution environment blocked every write-capable tool (details below). Here's the analysis and the exact change needed, so it can be applied by hand or in a follow-up run.

What I found

I couldn't reach the #9600 issue thread directly (GitHub/web tools were unavailable this run — see below), so I can't quote @niphlod verbatim. But the position Chrissy describes — offer -Pattern instead of wildcards — is already the established convention elsewhere in this codebase, in Get-DbaDatabase:

• public/Get-DbaDatabase.ps1:220-222 — $Database / $ExcludeDatabase are plain [string[]], no [SupportsWildcards()]. Matching is exact ($_.name -in $Database, line ~368).
• -Pattern is a separate regex-only parameter (public/Get-DbaDatabase.ps1:222), matched via a small helper ($matchesPattern, line 358) with OR semantics across multiple patterns.
• .github/copilot-instructions.md:76-79 codifies this exact intent: "Added -Pattern parameter... for regex-based filtering... Users need to filter databases using regex patterns instead of simple wildcards."

This PR currently does the opposite of that pattern. It kept [SupportsWildcards()] on JobName and StepName (public/Find-DbaAgentJob.ps1:201-205) and bolted Pattern on top — i.e. it offers regex in addition to wildcards, not instead of them. Get-JobList.ps1 still filters with -Like/-NotLike. The scaffolding doc that generated this PR (docs/superpowers/plans/2026-07-13-issue-9600-agent-job-pattern.md) explicitly chose "mark JobName/StepName as wildcard-capable" as the design, without incorporating the wildcard-removal feedback — that's the gap to close.

Required change

public/Find-DbaAgentJob.ps1

• Remove [SupportsWildcards()] from $JobName (line 201) and $StepName (line 204) — make both exact-match only, same contract as ExcludeJobName.
• Update .PARAMETER JobName / .PARAMETER StepName help text to describe exact matching and point to -Pattern for pattern-based lookups.
• Update the two .EXAMPLE blocks using -JobName *backup* (lines 139, 190) to use -Pattern "backup".

private/functions/Get-JobList.ps1

• Replace the -Like/-NotLike loops (lines 74-90) with exact-match comparisons mirroring Get-DbaDatabase's -in/-notin style:

  if ($JobFilter) {
      if ($Not) { $job | Where-Object Name -NotIn $JobFilter }
      else { $job | Where-Object Name -In $JobFilter }
  }
  if ($StepFilter) {
      $stepFound = if ($Not) { $job.JobSteps | Where-Object Name -NotIn $StepFilter }
                   else { $job.JobSteps | Where-Object Name -In $StepFilter }
      if ($stepFound.Count -gt 0) { $job }
  }

• Update .PARAMETER/.EXAMPLE doc blocks that reference wildcard syntax ('*job*').

tests/Find-DbaAgentJob.Tests.ps1

• Rewrite the "Wildcard filtering" context (lines 34-66) as exact-match tests (arrays give OR semantics; Literal*Job matches literally, no escaping needed).
• Replace "marks JobName and StepName as wildcard-capable" (lines 86-91) with an assertion that SupportsWildcardsAttribute is absent.
• Update integration tests using -Job *dbatoolsci* (lines 138, 164, 188-191) to -Pattern "dbatoolsci" — including the #9572 regression test, which should move to -Pattern since -Job/JobName no longer takes wildcards.

Why I couldn't push this

Every mutating tool was blocked in this run:

• Bash/git — sandbox failed to initialize (Sandbox dependencies not available: socat not installed), on every retry including with sandbox disabled.
• Edit/Write — denied by the permission gate ("haven't granted it yet") on repeated attempts.
• WebFetch/WebSearch — also denied, so I couldn't pull the original Get-JobList Filter Non-asterisk Wildcard Character Handling #9600 comment thread for a direct citation.

Only read-only tools (Read, Grep, Glob) and this comment tool worked. Nothing in the working tree was modified.

Next step

Please re-trigger @claude on this PR (or retry the job) once the runner environment is healthy — I'll apply the diff above and push it. Alternatively, this is a small enough change that it can be applied directly by hand using the specifics above.

[potatoqualitee]

@claude then again when we created the find commands, they were supposed to be more flexible than Get

[claude]

Claude finished @potatoqualitee's task in 2m 10s —— View job

---

Tasks

• Read trigger comment and gather context
• Research Find-* command conventions re: wildcards vs Get-* commands
• Re-evaluate previous recommendation (remove [SupportsWildcards()] from JobName/StepName) in light of "Find commands should be more flexible than Get"
• Post analysis/recommendation

Analysis

I checked every other Find-Dba* command for SupportsWildcards():

public/Find-DbaDatabase.ps1        -> no wildcards, -Pattern (regex) only
public/Find-DbaStoredProcedure.ps1 -> no wildcards, -Pattern (regex) only
public/Find-DbaObject.ps1          -> no wildcards, -Pattern (regex) only
public/Find-DbaAgentJob.ps1        -> the only one with SupportsWildcards()

So taken narrowly, "Find commands are more flexible than Get" hasn't historically meant PowerShell wildcards — the rest of the Find-* family standardized on -Pattern/regex exactly like Get-DbaDatabase does. My previous comment leaned on that pattern and recommended stripping [SupportsWildcards()] from JobName/StepName.

But Find-DbaAgentJob has its own history that overrides that generalization: tests/Find-DbaAgentJob.Tests.ps1:188-191 is a regression test for issue #9572, which was specifically about -Job *dbatoolsci* wildcard matching breaking. Stripping wildcard support from JobName now would re-break #9572 and change behavior existing scripts already depend on (the .EXAMPLE blocks with -JobName *backup* go back to the original 2018 author).

Given that, I agree with reconsidering — keep the current design as-is:

• JobName/StepName stay wildcard-capable ([SupportsWildcards()]), preserving Get-JobList -JobFilter Doesn't Handle Multiple Wildcarded Items Correctly  #9572 and existing muscle-memory syntax.
• Pattern stays as the additive regex-OR narrowing filter for users who need full regex power.
• ExcludeJobName stays exact-match (no ambiguity there, nobody asked for wildcard excludes).

This isn't a case of Find-DbaAgentJob deviating from convention for no reason — it has a concrete backward-compat/regression requirement the other three Find-* commands don't have. No code change needed here; my earlier "strip the wildcards" suggestion should be dropped.

All 7 CI checks are currently green on this PR (unit + integration + ScriptAnalyzer), including the wildcard-metadata and Pattern tests, so the current implementation is in a good state as-is.
· branch codex/issue-9600-agent-job-pattern