⚙️ [Maintenance]: Split module archetypes guidance

[Marius Storhaug (MariusStorhaug)]

Module archetype guidance now documents Integration and Data modules with flexible transport and Context patterns. The guidance clarifies design choices for exposing or hiding transport abstractions, Context functions for targeting environments, and the ConvertFrom/ConvertTo data flow directions.

New: Module archetype guidance

PSModule modules fall into two standardized archetypes. The new Module-Types.md page documents:

• Integration (API) modules: Wrap external services via REST or GraphQL. Commands map to resources and intents, not HTTP methods. Transport abstractions (REST/GraphQL functions) may be private, public, or combined with public Context depending on audience needs.
• Data modules: Convert between data format representations and PowerShell objects. Conversion always flows through PSCustomObject as the neutral pivot, with ConvertFrom and ConvertTo functions moving bidirectionally.

Changed: Transport abstraction is flexible, not prescriptive

Transport, REST methods, and GraphQL functions do not have to be private. Modules now document three strategies:

• Private transport (common): Keep REST/GraphQL helpers private. Public functions accept resolved inputs and typed objects. Follows Dependency Inversion at the network boundary.
• Public transport: Expose REST or GraphQL functions for power users or module composition.
• Public Context: Expose Context functions so users can configure and target specific contexts and environments directly.

Module authors choose the strategy that best serves their audience.

Changed: Context modules must expose functions and object types

The Context module provides on-disk storage for user data and secrets organized by context and environment. Modules must expose functions and object types so users can programmatically target specific contexts and environments. Users need to select which environment or context their functions operate against.

Improved: ConvertFrom/ConvertTo data flow clarity

The verb vocabulary table now explicitly shows data flow directions:

• ConvertFrom-: Format-specific input → PSCustomObject
• ConvertTo-: PSCustomObject → Format-specific output

Technical Details

• Added src/docs/Modules/Module-Types.md with Integration and Data archetype guidance.
• Updated src/docs/Modules/index.md with module section links.
• Added cross-link from Repository-Defaults.md to module types.
• Updated site navigation in src/zensical.toml.
• Split from PR Standardize module README + repository, agent, and module-type defaults #61 to isolate module archetype guidance from README policy and onboarding defaults.

[github-actions]

Super-linter summary

Language	Validation result
CHECKOV	Pass ✅
GITHUB_ACTIONS	Pass ✅
GITHUB_ACTIONS_ZIZMOR	Pass ✅
GITLEAKS	Pass ✅
GIT_MERGE_CONFLICT_MARKERS	Pass ✅
HTML	Pass ✅
JAVASCRIPT_ES	Pass ✅
JAVASCRIPT_PRETTIER	Pass ✅
MARKDOWN	Pass ✅
NATURAL_LANGUAGE	Pass ✅
POWERSHELL	Pass ✅
PRE_COMMIT	Pass ✅
SPELL_CODESPELL	Pass ✅
TRIVY	Pass ✅
YAML	Pass ✅

All files and directories linted successfully

For more information, see the GitHub Actions workflow run

Powered by Super-linter