Skip to content

DUSTFILE-SPECIFICATION.adoc

Latest commit

 

History

History
173 lines (123 loc) · 5.26 KB

DUSTFILE-SPECIFICATION.adoc

File metadata and controls

173 lines (123 loc) · 5.26 KB
Raw

Dustfile Specification

Table of Contents

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:

<app-name>-dustfile.sh

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

Required Functions

Dustfiles MUST implement these core functions:

--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):

# 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 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