Understanding the File Header Convention in ODS Installer Modules

All installer modules in the Osmantic/ODS repository follow a strict three-section header format consisting of Purpose, Expects, and Provides comments that declare the script's intent, required environment variables, and exported outputs.

The Osmantic/ODS (Open Dependability Stack) project maintains rigorous documentation standards for its Bash-based installer system. Understanding the file header convention in ODS installer modules is essential for contributors who need to create new phase scripts or library utilities that integrate with the automated installation harness. This convention ensures every module remains self-documenting and machine-readable without executing arbitrary code.

The Three-Section Header Format

Every installer-related Bash script in the Osmantic/ODS codebase—whether a phase script or library utility—begins with a standardized three-section comment header. According to the Osmantic/ODS source code, each field appears as a hash-prefixed comment (#) at the very top of the file, following the shebang line.

The header uses the following structure:

• Purpose: A concise sentence describing what the script accomplishes.
• Expects: A comma-separated list of environment variables, inputs, or prerequisites required for execution.
• Provides: The outputs, side-effects, or exported values made available after successful execution.

This minimal structure deliberately avoids decorative comments, keeping modules lightweight and parseable by the installer harness.

Implementation in Core ODS Files

The convention is consistently applied across the installer directory. In ods/installers/phases/01-preflight.sh, the header appears at lines 6–11, documenting the module's validation logic. Similarly, ods/installers/lib/ui.sh implements the same pattern at lines 6–12, declaring its user-interface helper functions.

These headers serve as explicit contracts: the Expects field tells the harness what variables must be populated before sourcing the file, while the Provides field indicates what state changes or variables the script guarantees on exit. This design enables the installer framework to validate inputs and outputs without executing the actual installation logic.

Practical Examples for New Modules

When authoring a new installer phase or library script, replicate this exact layout starting immediately after the shebang. The following examples demonstrate the standard format used in ods/installers/phases/01-preflight.sh and related utilities:

#!/usr/bin/env bash

# Purpose: Install Docker and Docker‑Compose on the host system.

# Expects: DRY_RUN, INTERACTIVE, LOG_FILE, SKIP_DOCKER

# Provides: DOCKER_CMD, DOCKER_COMPOSE_CMD

#

# (implementation follows...)

#!/usr/bin/env bash

# Purpose: Resolve the correct GPU‑specific docker‑compose overlay.

# Expects: SCRIPT_DIR, TIER, GPU_BACKEND, LOG_FILE

# Provides: COMPOSE_FILE, COMPOSE_FLAGS

#

# (implementation follows...)

Copy these templates directly when adding new phases to ods/installers/phases/ or utility scripts to ods/installers/lib/.

Machine Parsability and Automation

The strict file header convention in ODS installer modules exists primarily to support automated tooling. As implemented in Osmantic/ODS, the installer harness can source files and inspect these specific comment patterns to validate that all Expects variables are defined before execution and that all Provides values are generated afterward.

This machine-readable approach enables progress tracking, GUI integration, and static analysis without requiring static typing or complex manifest files. The convention ensures that ods/installers/phases/02-detection.sh, ods/installers/lib/tier-map.sh, and all other modules maintain a consistent, verifiable interface.

Summary

• ODS installer modules use a standardized three-section header: Purpose, Expects, and Provides.

• Headers appear immediately after the shebang, using simple hash-prefixed comments (# Field: value).

• Files like ods/installers/phases/01-preflight.sh (lines 6–11) and ods/installers/lib/ui.sh (lines 6–12) serve as canonical reference implementations.

• The convention enables the installer harness to validate inputs and outputs without executing scripts.

• New modules must follow this exact format to ensure compatibility with automated tooling and maintain consistency across the Osmantic/ODS codebase.

Frequently Asked Questions

What are the three required sections in an ODS installer header?

Every module must include Purpose (describing the script's function), Expects (listing required environment variables), and Provides (declaring exported outputs). These appear as the first three comments after the shebang line, as seen in ods/installers/phases/01-preflight.sh.

Can I add decorative comments or additional fields to the header?

No. The convention deliberately avoids extra decorative comments to keep headers minimal and machine-parsable. The installer harness specifically looks for the three standard fields; additional commentary may interfere with automated parsing.

How does the ODS installer harness use these headers?

The harness inspects the Expects and Provides fields to validate that all prerequisite environment variables are present before sourcing a script and to verify that declared outputs are generated after execution. This enables safe, non-executable validation of the installation contract.

Where can I find reference implementations of the header convention?

Examine ods/installers/phases/01-preflight.sh and ods/installers/lib/ui.sh in the Osmantic/ODS repository. These files demonstrate the standard layout at lines 6–11 and 6–12 respectively, providing working templates for new phase scripts and library utilities.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}