Skip to content

Add Write-xJobProgress: mirror background job progress - #2

Merged
exactmike merged 4 commits into
mainfrom
feature/job-progress
Sep 6, 2026
Merged

Add Write-xJobProgress: mirror background job progress#2
exactmike merged 4 commits into
mainfrom
feature/job-progress

Conversation

@exactmike

@exactmike exactmike commented Sep 6, 2026

Copy link
Copy Markdown
Contributor

Summary

  • Adds Write-xJobProgress, graduating the WIP/JobProgress.ps1 stub into a real exported function that mirrors Write-Progress calls made inside a Start-Job/Invoke-Command -AsJob scriptblock into the caller's session.
  • Tracks the latest progress record per distinct ActivityId across all ChildJobs (not just ChildJobs[0]), preserving ParentActivityId nesting, and falls back to the job's own .Progress for job types with no child jobs.
  • Assigns stable, collision-free Write-Progress -Id values by drawing from the same counter New-xProgress already uses, keyed internally by Job.InstanceId (not the recyclable .Id) so a reused job id can never inherit a stale mapping.
  • Auto-completes and retires mirrored bars once a job leaves Running, and never reprocesses a retired job's leftover progress records on a later call.
  • v1 is intentionally a lightweight write-only passthrough — no $script:ProgressTracker registration, no throttling/timer semantics. A -xParentIdentity parameter to nest job progress under a caller's own xProgress instance is flagged as a fast-follow in AGENTS.md/README (the internal id map is already independent of the tracker, so this is additive later).
  • Updates xProgress.psd1 (exports, version bump to 1.1.0, release notes), README.md, en-us/about_xProgress.help.txt, and AGENTS.md to document the new function and retire the stale WIP note.

Test plan

  • Invoke-ScriptAnalyzer -Path *.psm1 -Recurse — no new findings (only the 3 pre-existing ShouldProcess warnings)
  • Invoke-Pester -Path ./Tests -Output Detailed — 134/134 passing, including 8 new tests in Tests/Write-xJobProgress.Tests.ps1 using real Start-Job/Wait-Job (parameter shape, single activity, stable id across calls, concurrent/nested activities, zero-ChildJobs fallback, empty progress, completion cleanup, id-collision isolation from live xProgress instances)
  • Manual smoke test: two concurrent background jobs polled to completion via Write-xJobProgress, no exceptions, both jobs completed cleanly

exactmike and others added 4 commits September 5, 2026 21:34
Graduates the WIP/JobProgress.ps1 stub into a real, tested function:
mirrors Write-Progress calls happening inside a Start-Job scriptblock
into the caller's session, tracking the latest record per distinct
ActivityId (not just the last record overall) across all ChildJobs,
preserving ParentActivityId nesting, and assigning collision-free
Write-Progress ids from the same counter New-xProgress uses. It's a
lightweight write-only passthrough for now, with an -xParentIdentity
nesting fast-follow noted for later.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EMneU2siSsontUQczn8wGt
…ogress

Every existing test mocked Write-Progress, so the module's real integration
with the built-in cmdlet was never exercised (only Write-xJobProgress.Tests.ps1
used real background jobs). Add IntegrationTests-tagged coverage that runs the
real functions inside real Start-Job jobs over a real temp file-tree fixture
and asserts on the job's real, unmocked ProgressRecord output.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01EMneU2siSsontUQczn8wGt
@exactmike
exactmike merged commit 154335d into main Sep 6, 2026
4 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant