13. Extending and Maintaining a Wrapper📋

Adding an integration means supplying tool-specific evidence and interpretation around shared machinery. It is not necessary to duplicate process execution, version workers or Roslyn command emission.

The workflow should make command syntax, output semantics, environment encoding and packaging independently reviewable.

Begin with the four-project boundary📋

The current scaffolder creates Contracts, runtime, Design and xUnit projects, a solution, configuration and a README. It uses the checkout's project references and central package versions.

This existing preview command can be run from Net/FrenchExDev with PowerShell 7. It demonstrates scaffolding parameters; this documentation update does not execute it.

./BinaryWrapper/scripts/New-BinaryWrapperSolution.ps1 MyTool -CommandName my-tool -Parser cobra -WhatIf

The script refuses an existing destination and does not invoke dotnet or scrape the binary. Its documented behavior includes copying the source dotenv file when present, separately from generating declarations.

The scaffold is a starting point. It cannot infer a supported output schema for an unknown tool.

Establish command acquisition first📋

Choose the authoritative version collector and normalize tags deliberately. Select an image plan or installed-binary path. Supply the help format, flag conventions and a replay pipeline.

Collect bounded evidence, preserve raw help and inspect the tree. Verify representative commands: root/parent invocations where needed, optional-value syntax, variadic arguments and paths with spaces.

A generated API that compiles can still omit a positional argument or infer an inaccurate type. Use an explicit adapter only when its behavior is justified, and document that gap in the implementation study.

Add Environment from declarations📋

Declare variable names, C# types, converters and availability in the catalogue. Connect its concrete record through EnvironmentType. Supply the catalogue as an analyzer input to Contracts and verify the generated serializer.

Test unassigned values, assigned defaults, record copies and incompatible versions. Include a converter's exact wire representation and a final process-environment check.

A field's presence in the catalogue does not prove its effect reached a specialized help callback. Verify Design propagation as well as application execution.

Establish output contracts from emitters📋

Inspect authoritative emitter source or protocol specifications for a pinned version. Record command context, format switch, channel, fields, buffering and terminal behavior. Preserve source-shaped examples.

Implement records in Contracts and parsing in the implementation. A profile's semantic projection should expose only facts justified by that evidence. Unknown fields or messages retain their full wire or raw evidence.

For Vagrant, catalogue regeneration also requires the pinned checkout and reviewed dynamic bindings. Deterministic output and unchanged-file behavior are part of its tooling. Ordinary builds do not perform this extraction.

Validation layers📋

Tests should say which boundary they exercise.

Fake process tests can verify the real executor and parsers without installing packages, launching VMs or starting containers. Business tests can instead inject a runner double to verify policy.

Output scenarios worth maintaining📋

Important regression scenarios include:

• A readiness or success-looking milestone followed by nonzero process exit.
• A supported-looking row on the wrong process channel.
• Multi-line JSON completed later, malformed, incomplete or over the retained-text limit.
• Null or unmatched version selecting raw fallback.
• Prereleases around the upper boundary and build metadata inside a stable profile.
• Two executions creating separate parser state.
• Command-format selection preserving arbitrary application output.
• Explicit false, empty and null environment effects surviving the executor boundary.

These checks protect semantic meaning. Tests that merely assert a class exists or duplicate a trivial assignment do not establish the operational contract.

Run checks with attribution📋

Use the repository-selected SDK and one build worker when suites share referenced projects. For an already-restored checkout:

dotnet test ./Vagrant/test/FrenchExDev.Net.Vagrant.Tests/FrenchExDev.Net.Vagrant.Tests.csproj --no-restore -m:1

A fake transport pass should be reported as such. A skipped container test means its infrastructure condition was not exercised. Compilation, discovery and execution are separate facts; SDK or host-policy failures should not be reclassified as parser defects.

The local migration guide records a dated validation snapshot. Its counts belong to that snapshot and are not evidence that this editorial run repeated those suites.

Updating versions without erasing uncertainty📋

Update recipes and help samples when invocation evidence changes. Update output profiles when protocol evidence changes. Update Environment when variable availability or conversion changes. Those tasks may occur independently.

Keep help coverage and output intervals separate. Broadening a profile requires evidence, not simply a desire to avoid raw fallback.

Compile complete published snippets against the current assemblies and label declaration fragments or proposed models. Link public source only when it corresponds to the inspected implementation, especially while contracts and generators remain local changes.

Source snapshot📋

Source inspection: 2 October 2026. These implementation paths are relative to Net/FrenchExDev in the local ecosystem checkout. The v2 changes are largely uncommitted; these paths identify inspected code, without claiming that public branch links contain it.

• BinaryWrapper/scripts/New-BinaryWrapperSolution.ps1
• BinaryWrapper/scripts/Test-NewBinaryWrapperSolution.ps1
• BinaryWrapper/doc/SCRIPTS.md
• BinaryWrapper/doc/CONSUMER-MIGRATION.md
• Vagrant/test/FrenchExDev.Net.Vagrant.Tests/VagrantTypedOutputTests.cs

Previous · Series index · Next