Align the published Jwt module source with PSModule design principles

[MariusStorhaug]

Jwt is already published to the PowerShell Gallery as version 1.9.1. Consumers rely on the current exported commands and behavior, but the repository has only recently been split into individual function files and still reflects gallery-era conventions rather than the structure expected by Process-PSModule. As a result, the repository is not yet a trustworthy source of truth for the published module and routine maintenance risks introducing silent API drift.

Request

User impact

Maintainers need the repository source to represent the currently published module accurately so that fixes, documentation, linting, and future features can be built on top of a stable baseline. Without that alignment, small refactors can change command signatures, omit compatibility aliases, or diverge from gallery behavior without being caught early.

Current experience

The current source layout and function implementations are only partially aligned with PSModule design principles. The repository may preserve the rough feature set of the published module, but conventions around function structure, comment help, parameter declarations, alias preservation, pipeline handling, and validation are inconsistent, which makes automated Process-PSModule quality checks less reliable.

Desired experience

The repository should be the authoritative source for the published Jwt module. Public behavior from Jwt 1.9.1 should remain intact unless an intentional follow-up issue explicitly changes it, while the implementation, tests, and documentation align with PSModule design principles.

Acceptance criteria

• The repository source matches the exported command surface, aliases, and observable behavior of Jwt 1.9.1 unless a separate issue explicitly defines a breaking or behavioral change.
• Public function files under src/functions/public/ follow PSModule conventions for function structure, parameter declarations, help, output types, and pipeline support.
• The repository passes the configured Process-PSModule linting and local Pester validation from source.
• README.md usage and generated help content reflect the aligned source layout and supported command surface.
• Any remaining differences between the published module and the repository are called out in explicit follow-up issues instead of remaining undocumented.

---

Technical decisions

Compatibility baseline: Use the currently published PowerShell Gallery package as the behavioral baseline for this alignment work. This issue is about making the repository match the published module, not redefining the module surface.

Scope boundary: Preserve existing public command names, aliases, and default behaviors while aligning implementation details to PSModule conventions. Intentional new functionality or breaking cleanup belongs in separate issues such as #13.

Source layout: Keep the split source model in src/functions/public/ as the public entry point. Add private helpers only where duplication can be reduced without changing observable behavior.

Validation strategy: Treat Pester tests and configured linter rules in .github/PSModule.yml as the enforcement mechanism for parity and style. Tests should assert exported commands, compatibility aliases, and representative create, parse, and verify scenarios.

Documentation source of truth: Drive module documentation from in-source comment help and the repository README.md so the generated docs from Process-PSModule stay consistent with the shipped module.

Related work: This issue is not a duplicate of #13. #13 expands Jwt capabilities, while this issue establishes a PSModule-aligned baseline for the already published module.

---

Implementation plan

Baseline capture

• Inventory the exported commands, aliases, and representative behavior of Jwt 1.9.1 from the PowerShell Gallery.
• Compare that baseline with the current split source in src/functions/public/ and record any compatibility gaps that must be preserved or restored.

Source alignment

• Update public function files to follow PSModule conventions for CmdletBinding, parameter declarations, validation, help, output metadata, and pipeline blocks.
• Restore any missing compatibility aliases or parameter aliases required for parity with the published module.
• Introduce private helpers only where they reduce duplication without changing the external command surface.

Validation

• Expand tests/Jwt.Tests.ps1 to lock the exported command surface and representative encode, decode, create, and verify behaviors.
• Run the repository’s configured linting and Pester validation until the source passes cleanly from the repository state, not only from the installed gallery module.

Documentation and follow-up

• Update README.md examples and function references to match the aligned source and preserved public API.
• Create separate follow-up issues for any deliberate API cleanup, new JWT capabilities, or design changes that should not be bundled into compatibility alignment.