Building a Reusable Provider📋

The missing operation is git worktree list. It belongs in an independent provider so the parser can be tested, versioned and reused by future tasks.

Define the contract before the parser📋

The question determines which facts must survive reduction. For this capability, the provider's .Data has the following contract:

The common envelope carries the native outcome, error, retry advice and explicit omissions. A bounded Items preview can coexist with an exact WorktreeCount; an interrupted or malformed stream cannot certify that total. The task can therefore decide whether the count answers its question or whether it needs a narrower request or a corrected provider.

Read the relevant manual, local help or source to establish the supported format. Preserve that knowledge in documentation and fixtures. Future requests can reuse the verified capability; format changes and new options require checking its assumptions again.

Domain parsing, normalization and calculations shared by callers belong in the provider. Selecting a few properties and combining them with Git status or ripgrep belongs in the task. This keeps a general worktree capability reusable across questions instead of generating a new parser for each requested projection.

Generate the project📋

Choose an absent or empty destination. The generator creates the manifest, module loader, streaming starter, contribution script, catalogue, documentation and test folders.

$scaffold = New-OPumperModule -Name GitWorktrees -Executable git -Path $destination
if ($scaffold.Outcome -ne 'Success') { throw 'Provider scaffold failed.' }

The completed FrenchExDev.OPumper.GitWorktrees.PoSh example is the deliverable used by the walkthrough. Its exported function is Invoke-PumpGitWorktrees; its provider identifier is gitworktrees; its route identifier is gitworktrees.list.

Scaffolding supplies the project structure. The agent still has to implement the contract, verify the field semantics with fixtures, validate the documentation and activate the route. Successful generation or registration alone does not establish parser correctness.

Start from the machine format📋

Git documents worktree list --porcelain -z as a machine-readable format. The parser consumes NUL-delimited attributes, including paths and state fields, instead of splitting a formatted table. This preserves spaces and embedded newlines. Git worktree manual↗ (ouvre dans une nouvelle fenêtre).

The provider requests that format itself. The agent writes Pump-Me git -NativeArguments @('worktree','list'), with no need to restate format flags. Extra native arguments are rejected by this deliberately narrow route.

Invoke-PumpGitWorktrees.ps1 delegates execution to the engine:

$state = New-WorktreeState -MaxItems $MaxItems
Invoke-OutputPumpNative -Executable git -ArgumentList @('worktree','list','--porcelain','-z') -WorkingDirectory $WorkingDirectory -MaxItems $MaxItems -MaxOutputBytes $MaxOutputBytes -TimeoutSeconds $TimeoutSeconds -RecordDelimiter ([char]0) -State $state -Summary 'Git worktrees: count, paths, HEAD, branch and state.' -OnRecord {
    param($record,$state)
    if ($record.Stream -eq 'stdout' -and !$record.Truncated) {
        Add-WorktreeRecord $record.Text $state
    }
} -Parse {
    param($state,$capture)
    Complete-WorktreeState $state $capture
}

The private domain reducer maintains a count, a limited list and one current worktree. It rejects malformed HEAD values, duplicate attributes, conflicting flags and incomplete records. Bare worktrees do not require HEAD or branch; detached worktrees carry HEAD without a branch.

The completed data has WorktreeCount, ObservedWorktreeCount, Complete and bounded Items. Each item carries Path, Head, Branch, Detached, Bare, Locked, Prunable, LockReason and PruneReason. A complete stream can yield an exact count even when most items are omitted. An incomplete run yields a null exact count.

Keep the provider self-contained📋

The contribution script executes inside the provider module and captures the command reference with .GetNewClosure(). The handler receives an invocation context and forwards its parameters to that command. Registration performs no native work.

Validate documentation, then activate behavior📋

After implementing and testing the function, validate the descriptor against its exported parameters:

$descriptor = Import-PowerShellDataFile "$providerRoot/resources/descriptor.psd1"
$documented = Register-OutputPump -Descriptor $descriptor -LibraryRoot $providerRoot
if ($documented.Outcome -ne 'Success') { throw 'Documentary validation failed.' }
& ./scripts/Write-EnglishProviderDocs.ps1 -ProviderRoot $providerRoot
$activated = Setup-OutputPumps -ConfigurationPath $configuration -InventoryPath $inventory
if ($activated.Outcome -ne 'Success') { throw 'Provider activation failed.' }
Get-OutputPump -Id gitworktrees.list

Documentary registration regenerates the provider's catalogue, software sheet and index. It validates exports, parameter names and HTTPS source links. The example's documentation helper renders the generated sheet in English and selects the provider's own caller in its index. Registration does not activate routes. Setup discovers the provider from a configured root and contributes its routes to the session.

Commit the complete provider directory and the relevant configuration to user-controlled Git storage. Do not put a one-off task script into the reusable catalogue.

Prove the useful fields📋

The provider suite exercises the reducer and isolated registration. The example runner checks real linked, detached and bare worktrees, a locked Unicode path with spaces, invalid repositories and unsupported arguments. Synthetic fixtures cover embedded newlines and prunable metadata without depending on platform filename restrictions.

The tests check counts, paths, HEAD, branch, flags and completion. Exit code zero alone would not establish that this provider answers the intended question.

Previous: Setup and Optional DevPoSh · Next: Objects, Streaming and Task Budgets