Skip to main content

Template System Requirements Analysis

Last Updated: 2026-02-15
Status: Active

1. Executive Summary​

This document explains why DistroNexus needs a template system and defines the business and engineering requirements that justify its existence.

DistroNexus solves WSL lifecycle management, but lifecycle operations alone do not solve environment standardization. A template system is required to bridge the gap between instance provisioning and ready-to-use development environments.

2. Problem Statement​

Without templates, teams repeatedly perform the same post-install setup tasks:

  • language/runtime installation,
  • package manager bootstrapping,
  • tooling initialization,
  • and per-project version pinning.

This creates five recurring issues:

  1. High onboarding cost: new contributors spend hours reproducing local setup.
  2. Configuration drift: each machine diverges over time.
  3. Low reproducibility: CI-like behavior is hard to reproduce locally.
  4. Operational risk: manual steps introduce inconsistent outcomes.
  5. Poor auditability: setup actions are not centrally described or validated.

3. Why DistroNexus Needs a Template System​

The template system is required because it provides a first-class, explicit contract for environment bootstrap:

  • Declarative metadata (config/templates.json) for discoverability and governance.
  • Scripted execution for real setup actions in WSL instances.
  • Version/channel controls to support modern multi-SDK workflows.
  • Preflight checks for capability-gated scenarios (GPU/systemd/container modes).
  • Automation runner for repeatable validation and evidence generation.

In short: lifecycle management creates instances; templates create usable environments.

4. Stakeholders and Primary Use Cases​

4.1 Stakeholders​

  • Individual developers using WSL for daily development.
  • Team leads requiring consistent onboarding outcomes.
  • QA/release engineers validating setup reproducibility.
  • Maintainers evolving template catalog and scripts.

4.2 Primary Use Cases​

  1. Apply one built-in template after installing a distro instance.
  2. Select language channel/version (for example .NET channel, Node LTS/current).
  3. Apply environment-specific options via variable overrides.
  4. Validate one or many templates after changes.
  5. Run full-catalog dry run / execution and archive evidence.

5. Functional Requirements​

5.1 Catalog and Discovery​

  • Templates shall be discoverable from config/templates.json.
  • Each template shall define ID, category, description, compatibility, and scripts.
  • Search/filter shall support at least ID and category.

5.2 Execution and Orchestration​

  • System shall apply templates to target WSL instances.
  • Scripts shall execute in defined order.
  • Script timeout and continue-on-error behavior shall be configurable.
  • Progress and status shall be reportable during execution.

5.3 Version-Aware Setup​

  • Version-aware templates shall support VersionOptions and DefaultSelections.
  • Runtime variable overrides shall be supported for template application.

5.4 Preflight and Capability Gating​

  • Preflight checks shall run before script execution.
  • Required checks shall fail fast.
  • Optional checks shall warn and continue.
  • Capability-gated scenarios shall support blocked classification in automation runs.

5.5 History and Traceability​

  • Template application history shall be persisted.
  • Automation execution shall produce machine-readable and markdown artifacts.

6. Non-Functional Requirements​

6.1 Safety​

  • Absolute script paths must be rejected.
  • Path traversal must be blocked.
  • Script resolution must stay within allowed roots.

6.2 Reliability​

  • Scripts should be idempotent where practical.
  • Cancellation and timeout handling should be supported.

6.3 Reproducibility​

  • Template metadata and execution behavior must be deterministic for same inputs.
  • Validation outputs must be persistable and auditable.

6.4 Local-First Validation​

  • Automation suite is local-first and WSL2-targeted.
  • CI execution is guarded and opt-in override only.

7. Scope Boundaries​

7.1 In Scope​

  • Built-in template catalog and metadata model.
  • Template apply workflow in desktop + PowerShell surface.
  • Local automation validation runner and artifacts.

7.2 Out of Scope​

  • Cloud provisioning orchestration.
  • Third-party online template marketplace.
  • Full CI mandatory execution of local runtime templates.

8. Current State Summary​

  • Built-in catalog currently contains 15 templates.
  • Implemented categories: Development, Platform, CloudNative, Database, DataAndAI.
  • DevOps is a target category in expansion requirements but is not currently represented as a dedicated built-in category.

9. Success Criteria​

A template-system release is considered successful when:

  1. Catalog is valid and loadable.
  2. Apply pipeline works with deterministic progress and history.
  3. Security guardrails are enforced.
  4. Desktop and PowerShell entry points remain consistent.
  5. Automation evidence exists for selected and full-catalog validation paths.
  • docs/development/template-system-comprehensive-guide.md
  • docs/specs/template-system-requirements.md
  • docs/specs/built-in-template-expansion-requirements.md
  • docs/specs/built-in-template-automation-test-suite-requirements.md