// SPDX-License-Identifier: CC-BY-SA-4.0
// SPDX-FileCopyrightText: 2026 Jonathan D.A. Jewell (hyperpolymath)
= Dustfile Specification
:toc:
:toclevels: 3

== Overview

Dustfiles are **targeted, automated repair scripts** that embody the principles of
self-diagnostic, self-healing, fault-tolerant systems. They are inspired by
Microsoft's automated repair tools but designed for the hyperpolymath ecosystem.

== Core Principles

Dustfiles MUST:

1. **Detect Specific Problems** - Identify exact issues, not just symptoms
2. **Provide Targeted Fixes** - Offer precise, automated repairs
3. **Offer Clear Explanations** - Explain what's wrong and what's being fixed
4. **Integrate with Feedback** - Report usage and outcomes for continuous improvement
5. **Support Exhausted Users** - Provide escalation paths when automated repair fails

== Specification

=== Naming Convention

Dustfiles MUST be named according to the pattern:

[source,bash]
----
<app-name>-dustfile.sh
----

Where `<app-name>` matches the application's main executable or identifier.

=== Required Functions

Dustfiles MUST implement these core functions:

[source,bash]
----
--diagnose, -d    # Run diagnostics only (read-only, safe)
--repair, -r      # Attempt automated repair (may make changes)
--full-repair, -f  # Comprehensive repair (stops services, cleans up)
--help, -h        # Show help and usage
----

=== Diagnostic Capabilities

Dustfiles MUST check for these common issues:

1. **Process State** - Is the server/application running?
2. **Port Conflicts** - Is the required port available?
3. **Dependencies** - Are all required tools/libraries installed?
4. **Log Errors** - Are there errors in the application logs?
5. **Configuration** - Are configuration files valid?

=== Repair Capabilities

Dustfiles MUST provide automated fixes for detectable issues:

1. **Port Conflict Resolution** - Identify and optionally kill conflicting processes
2. **Dependency Installation** - Automatically install missing system dependencies
3. **Server Restart** - Attempt to restart failed services with verbose logging
4. **Log Rotation** - Clean up or archive excessive log files
5. **Configuration Repair** - Fix common configuration errors

=== User Experience Requirements

Dustfiles MUST provide:

1. **Clear Status Messages** - Color-coded output (✓ success, ✗ failure, ? unknown)
2. **Actionable Guidance** - Specific commands users can run
3. **Documentation Links** - References to relevant Dustfiles and documentation
4. **Escalation Paths** - Next steps when automated repair fails

=== Integration Requirements

Dustfiles MUST integrate with:

1. **Feedback-o-tron** - Report usage and outcomes for telemetry
2. **Hypatia** - Provide LLM-assisted troubleshooting
3. **Exhausted Support** - Escalation when users have tried everything

=== Feedback-o-tron Integration

Dustfiles MUST report events to feedback-o-tron (if available):

[source,bash]
----
# Report dustfile usage
feedback-o-tron --event "dustfile:used" \
  --app "$APP_NAME" \
  --mode "$MODE" \
  --success "$SUCCESS" \
  2>/dev/null || true

# Report specific repairs
feedback-o-tron --event "dustfile:repair_attempted" \
  --app "$APP_NAME" \
  --issue "port_conflict" \
  --success "$SUCCESS" \
  2>/dev/null || true
----

=== Hypatia Integration

Dustfiles MUST provide Hypatia integration points:

1. **Diagnostic Assistance**:
   [source,bash]
   ----
   hypatia diagnose --app $APP_NAME --log $LOG_FILE
   ----

2. **Exhausted Support**:
   [source,bash]
   ----
   hypatia exhausted --app $APP_NAME --log $LOG_FILE --dustfile $0
   ----

=== Telemetry and Learning

Dustfiles SHOULD collect anonymous telemetry for pattern analysis:

1. **Usage Patterns** - Which repair modes are most used
2. **Success Rates** - Which repairs succeed/fail
3. **Error Patterns** - Common issues across users
4. **Environment Data** - OS, dependencies, configurations

Telemetry MUST:
- Be opt-out (respect user privacy)
- Not include sensitive data
- Help identify common issues for script improvement
- Feed into continuous improvement loops

== Implementation Example

See link:dustfile-template.sh[dustfile-template.sh] for a complete reference implementation.

== Compliance

Applications in the hyperpolymath ecosystem:

- **MUST** provide a Dustfile for user-facing components
- **MUST** document Dustfile usage in README/ERROR messages
- **SHOULD** integrate Dustfile checks into launcher scripts
- **SHOULD** update Dustfiles when new issues are discovered

== Relationship to Other Standards

Dustfiles complement other standards:

- **E-Grade Launchers**: Dustfiles handle repair when launchers fail
- **Feedback-o-tron**: Dustfiles provide targeted telemetry
- **Hypatia Rules**: Dustfiles integrate LLM assistance
- **Consent-Aware HTTP**: Dustfiles respect privacy in telemetry

== Future Evolution

Dustfiles may evolve to include:

- **AI-Generated Repairs**: Hypatia suggesting new repair strategies
- **Pattern Learning**: Automatically updating from telemetry
- **Cross-Application**: Sharing repair patterns between apps
- **Predictive**: Anticipating issues before they occur

== See Also

- link:launcher-standard.adoc[Comprehensive Launcher Standard]
- link:https://github.com/metadatastician/consent-aware-web[Consent-Aware Web] ⇗
- link:../groove-protocol/[Groove Protocol]
- link:../hypatia-rules/[Hypatia Rules]