diff --git a/ARCHITECTURE.adoc b/ARCHITECTURE.adoc new file mode 100644 index 0000000..1c0a7a6 --- /dev/null +++ b/ARCHITECTURE.adoc @@ -0,0 +1,48 @@ +== Architecture + +=== Overview + +This repository follows a modular, maintainable architecture designed +for clarity, scalability, and long-term sustainability. + +=== Directory Structure + +.... +. +├── src/ # Source code +├── tests/ # Test suites +├── docs/ # Documentation +├── scripts/ # Utility scripts +├── config/ # Configuration files +├── LICENSE # License file +├── LICENSES/ # Full license texts +└── README.adoc # Project documentation +.... + +=== Design Principles + +* *Separation of Concerns*: Each module has a single responsibility +* *Testability*: Code is written to be easily testable +* *Documentation*: All public APIs are documented +* *Configuration*: Environment-specific settings are externalized + +=== Dependencies + +* External dependencies are minimized and clearly declared +* Version pinning is used for reproducibility + +=== Security Considerations + +* Sensitive data is never committed to the repository +* Secrets are managed through environment variables or secure vaults +* Regular dependency audits are performed + +=== Maintainability + +* Code follows consistent style guidelines +* Pull requests require review and CI checks +* Issues and discussions are tracked transparently + +''''' + +_Last updated: 2026-07-18_ diff --git a/ARCHITECTURE.md b/ARCHITECTURE.md deleted file mode 100644 index 607e3d8..0000000 --- a/ARCHITECTURE.md +++ /dev/null @@ -1,47 +0,0 @@ -# Architecture - -## Overview - -This repository follows a modular, maintainable architecture designed for clarity, scalability, and long-term sustainability. - -## Directory Structure - -``` -. -├── src/ # Source code -├── tests/ # Test suites -├── docs/ # Documentation -├── scripts/ # Utility scripts -├── config/ # Configuration files -├── LICENSE # License file -├── LICENSES/ # Full license texts -└── README.adoc # Project documentation -``` - -## Design Principles - -- **Separation of Concerns**: Each module has a single responsibility -- **Testability**: Code is written to be easily testable -- **Documentation**: All public APIs are documented -- **Configuration**: Environment-specific settings are externalized - -## Dependencies - -- External dependencies are minimized and clearly declared -- Version pinning is used for reproducibility - -## Security Considerations - -- Sensitive data is never committed to the repository -- Secrets are managed through environment variables or secure vaults -- Regular dependency audits are performed - -## Maintainability - -- Code follows consistent style guidelines -- Pull requests require review and CI checks -- Issues and discussions are tracked transparently - ---- - -*Last updated: 2026-07-18* diff --git a/BUILD_ADA.adoc b/BUILD_ADA.adoc new file mode 100644 index 0000000..3a7b708 --- /dev/null +++ b/BUILD_ADA.adoc @@ -0,0 +1,216 @@ +== Building Network Ambulance Ada/SPARK TUI + +=== Prerequisites + +==== Install GNAT and SPARK + +*Fedora:* + +[source,bash] +---- +sudo dnf install gcc-gnat gprbuild gnat-llvm gnatprove +---- + +*Ubuntu/Debian:* + +[source,bash] +---- +sudo apt install gnat gprbuild gnatprove +---- + +*Arch:* + +[source,bash] +---- +sudo pacman -S gcc-ada gprbuild spark +---- + +*Or use Alire (Ada package manager):* + +[source,bash] +---- +curl -LO https://github.com/alire-project/alire/releases/latest/download/alr-x86_64-linux.zip +unzip alr-x86_64-linux.zip +sudo mv bin/alr /usr/local/bin/ +alr toolchain --select +---- + +=== Building + +==== Debug build (default): + +[source,bash] +---- +gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=debug +---- + +==== Release build (optimized): + +[source,bash] +---- +gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=release +---- + +==== Prove mode (SPARK verification): + +[source,bash] +---- +gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=prove +gnatprove -P network_ambulance_tui.gpr --level=2 +---- + +=== Running + +[source,bash] +---- +# After building, binary is in bin/ +./bin/network_ambulance_tui + +# Or with Alire: +alr run +---- + +=== SPARK Verification + +The TUI includes formally verified state machine logic in +`+network_state.ads/adb+`. + +==== Run SPARK proofs: + +[source,bash] +---- +gnatprove -P network_ambulance_tui.gpr --level=2 --prover=cvc5,z3 +---- + +==== Proof levels: + +* `+--level=0+`: Fast, basic checks +* `+--level=1+`: Standard checks +* `+--level=2+`: More thorough (recommended) +* `+--level=3+`: Maximum effort +* `+--level=4+`: Ultra paranoid (slow) + +==== View proof results: + +[source,bash] +---- +gnatprove -P network_ambulance_tui.gpr --output=brief +---- + +=== Features + +==== SPARK Verified Components + +* *State Machine* (`+network_state.ads/adb+`): +** Formally proven state transitions +** Preconditions and postconditions on all operations +** Proof that repair attempts never exceed maximum +** Proof that terminal states are correctly identified + +==== TUI Features + +* *Dashboard View*: Status overview with color-coded indicators +* *Diagnostics View*: Detailed network diagnostic results +* *Repairs View*: Available repair actions +* *Help View*: Keyboard commands and about info + +==== Keyboard Commands + +* `+d+` - Run diagnostics +* `+r+` - Attempt repair +* `+1+` - Dashboard view +* `+2+` - Diagnostics view +* `+3+` - Repairs view +* `+h+` - Help +* `+q+` - Quit + +=== Integration with D Backend + +The Ada TUI can call the D backend for real diagnostics: + +[source,bash] +---- +# Run D diagnostics and parse JSON +./bin/network-ambulance-d diagnose --json | jq + +# Run D repairs and parse JSON +sudo ./bin/network-ambulance-d repair all --json | jq +---- + +The TUI currently simulates diagnostics. To integrate with real backend: +1. Use `+Ada.Processes+` (Ada 2022) to spawn `+network-ambulance-d+` 2. +Parse JSON output using a JSON library (e.g., `+gnatcoll-json+`) 3. +Update `+Context_Type+` with real diagnostic data + +=== Project Structure + +.... +src/ada/ +├── core/ +│ ├── network_state.ads # SPARK state machine spec +│ └── network_state.adb # SPARK state machine impl +└── tui/ + ├── tui_display.ads # TUI display interface + ├── tui_display.adb # TUI display impl + └── network_ambulance_tui.adb # Main program +.... + +=== Troubleshooting + +*Error: `+gnatprove: command not found+`* - Install SPARK tools: +`+sudo dnf install gnatprove+` + +*Error: `+gprbuild: invalid value for -XBUILD_MODE+`* - Valid values: +`+debug+`, `+release+`, `+prove+` + +*Error: Cannot prove all checks* - Some properties may require manual +proof or additional contracts - Use `+--prover=cvc5,z3,altergo+` for +multiple provers - Increase timeout: `+--timeout=60+` + +*SPARK errors in terminal I/O:* - `+TUI_Display+` is marked +`+SPARK_Mode => Off+` because terminal I/O is not provable - Only +`+Network_State+` is formally verified + +=== Development + +==== Add new SPARK contracts: + +[source,ada] +---- +procedure My_Procedure (X : in out Integer) +with + Pre => X >= 0, + Post => X > X'Old and X < 100; +---- + +==== Run SPARK flow analysis: + +[source,bash] +---- +gnatprove -P network_ambulance_tui.gpr --mode=flow +---- + +==== Generate counterexamples for failed proofs: + +[source,bash] +---- +gnatprove -P network_ambulance_tui.gpr --counterexamples=on +---- + +=== Safety Properties Proven + +The SPARK state machine proves: 1. ✓ State transitions are always valid +2. ✓ Repair attempts never exceed `+Max_Repair_Attempts+` 3. ✓ Terminal +states are correctly identified 4. ✓ Previous state is always preserved +5. ✓ Reset correctly reinitializes all fields 6. ✓ No runtime errors (no +exceptions, no overflows) + +=== Future Enhancements + +* [ ] Real integration with D backend via `+Ada.Processes+` +* [ ] JSON parsing for diagnostic results +* [ ] ncurses-based UI with real terminal control +* [ ] Mouse support +* [ ] Configuration file support +* [ ] Logging to file +* [ ] Network interface selection diff --git a/BUILD_ADA.md b/BUILD_ADA.md deleted file mode 100644 index 0491178..0000000 --- a/BUILD_ADA.md +++ /dev/null @@ -1,188 +0,0 @@ -# Building Network Ambulance Ada/SPARK TUI - -## Prerequisites - -### Install GNAT and SPARK - -**Fedora:** -```bash -sudo dnf install gcc-gnat gprbuild gnat-llvm gnatprove -``` - -**Ubuntu/Debian:** -```bash -sudo apt install gnat gprbuild gnatprove -``` - -**Arch:** -```bash -sudo pacman -S gcc-ada gprbuild spark -``` - -**Or use Alire (Ada package manager):** -```bash -curl -LO https://github.com/alire-project/alire/releases/latest/download/alr-x86_64-linux.zip -unzip alr-x86_64-linux.zip -sudo mv bin/alr /usr/local/bin/ -alr toolchain --select -``` - -## Building - -### Debug build (default): -```bash -gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=debug -``` - -### Release build (optimized): -```bash -gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=release -``` - -### Prove mode (SPARK verification): -```bash -gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=prove -gnatprove -P network_ambulance_tui.gpr --level=2 -``` - -## Running - -```bash -# After building, binary is in bin/ -./bin/network_ambulance_tui - -# Or with Alire: -alr run -``` - -## SPARK Verification - -The TUI includes formally verified state machine logic in `network_state.ads/adb`. - -### Run SPARK proofs: -```bash -gnatprove -P network_ambulance_tui.gpr --level=2 --prover=cvc5,z3 -``` - -### Proof levels: -- `--level=0`: Fast, basic checks -- `--level=1`: Standard checks -- `--level=2`: More thorough (recommended) -- `--level=3`: Maximum effort -- `--level=4`: Ultra paranoid (slow) - -### View proof results: -```bash -gnatprove -P network_ambulance_tui.gpr --output=brief -``` - -## Features - -### SPARK Verified Components -- **State Machine** (`network_state.ads/adb`): - - Formally proven state transitions - - Preconditions and postconditions on all operations - - Proof that repair attempts never exceed maximum - - Proof that terminal states are correctly identified - -### TUI Features -- **Dashboard View**: Status overview with color-coded indicators -- **Diagnostics View**: Detailed network diagnostic results -- **Repairs View**: Available repair actions -- **Help View**: Keyboard commands and about info - -### Keyboard Commands -- `d` - Run diagnostics -- `r` - Attempt repair -- `1` - Dashboard view -- `2` - Diagnostics view -- `3` - Repairs view -- `h` - Help -- `q` - Quit - -## Integration with D Backend - -The Ada TUI can call the D backend for real diagnostics: - -```bash -# Run D diagnostics and parse JSON -./bin/network-ambulance-d diagnose --json | jq - -# Run D repairs and parse JSON -sudo ./bin/network-ambulance-d repair all --json | jq -``` - -The TUI currently simulates diagnostics. To integrate with real backend: -1. Use `Ada.Processes` (Ada 2022) to spawn `network-ambulance-d` -2. Parse JSON output using a JSON library (e.g., `gnatcoll-json`) -3. Update `Context_Type` with real diagnostic data - -## Project Structure - -``` -src/ada/ -├── core/ -│ ├── network_state.ads # SPARK state machine spec -│ └── network_state.adb # SPARK state machine impl -└── tui/ - ├── tui_display.ads # TUI display interface - ├── tui_display.adb # TUI display impl - └── network_ambulance_tui.adb # Main program -``` - -## Troubleshooting - -**Error: `gnatprove: command not found`** -- Install SPARK tools: `sudo dnf install gnatprove` - -**Error: `gprbuild: invalid value for -XBUILD_MODE`** -- Valid values: `debug`, `release`, `prove` - -**Error: Cannot prove all checks** -- Some properties may require manual proof or additional contracts -- Use `--prover=cvc5,z3,altergo` for multiple provers -- Increase timeout: `--timeout=60` - -**SPARK errors in terminal I/O:** -- `TUI_Display` is marked `SPARK_Mode => Off` because terminal I/O is not provable -- Only `Network_State` is formally verified - -## Development - -### Add new SPARK contracts: -```ada -procedure My_Procedure (X : in out Integer) -with - Pre => X >= 0, - Post => X > X'Old and X < 100; -``` - -### Run SPARK flow analysis: -```bash -gnatprove -P network_ambulance_tui.gpr --mode=flow -``` - -### Generate counterexamples for failed proofs: -```bash -gnatprove -P network_ambulance_tui.gpr --counterexamples=on -``` - -## Safety Properties Proven - -The SPARK state machine proves: -1. ✓ State transitions are always valid -2. ✓ Repair attempts never exceed `Max_Repair_Attempts` -3. ✓ Terminal states are correctly identified -4. ✓ Previous state is always preserved -5. ✓ Reset correctly reinitializes all fields -6. ✓ No runtime errors (no exceptions, no overflows) - -## Future Enhancements - -- [ ] Real integration with D backend via `Ada.Processes` -- [ ] JSON parsing for diagnostic results -- [ ] ncurses-based UI with real terminal control -- [ ] Mouse support -- [ ] Configuration file support -- [ ] Logging to file -- [ ] Network interface selection diff --git a/BUILD_D.adoc b/BUILD_D.adoc new file mode 100644 index 0000000..c000f13 --- /dev/null +++ b/BUILD_D.adoc @@ -0,0 +1,154 @@ +== Building Network Ambulance D Implementation + +=== Prerequisites + +==== Install D compiler (DMD or LDC) + +*Fedora:* + +[source,bash] +---- +sudo dnf install dmd dub +---- + +*Ubuntu/Debian:* + +[source,bash] +---- +curl -fsS https://dlang.org/install.sh | bash -s dmd +source ~/dlang/dmd-*/activate +---- + +*Arch:* + +[source,bash] +---- +sudo pacman -S dlang dub +---- + +*Or use official installer:* + +[source,bash] +---- +curl https://dlang.org/install.sh | bash -s +source ~/dlang/dmd-*/activate +---- + +=== Building + +==== Debug build (default): + +[source,bash] +---- +dub build +---- + +==== Release build (optimized): + +[source,bash] +---- +dub build --build=release +---- + +==== Safe mode build (extra safety checks): + +[source,bash] +---- +dub build --build=safe +---- + +=== Running + +[source,bash] +---- +# After building, binary is in bin/ +./bin/network-ambulance-d diagnose + +# Or run directly with dub (slower, recompiles): +dub run -- diagnose + +# Quick status: +./bin/network-ambulance-d status + +# Verbose diagnostics: +./bin/network-ambulance-d diagnose --verbose + +# Version: +./bin/network-ambulance-d version +---- + +=== Testing + +[source,bash] +---- +# Run built-in tests: +dub test + +# Run with verbose output: +dub run -- diagnose -v +---- + +=== Installation + +[source,bash] +---- +# Install to system: +dub build --build=release +sudo install -m 755 bin/network-ambulance-d /usr/local/bin/ +---- + +=== Development + +[source,bash] +---- +# Clean build artifacts: +dub clean + +# Show dependencies: +dub describe + +# Lint code: +dub lint + +# Generate documentation: +dub build --build=docs +---- + +=== Platform-Specific Notes + +==== Linux + +* Full feature set available +* Requires `+ip+`, `+ping+`, `+dig+` commands +* Some operations require root/sudo + +==== macOS + +* Basic diagnostics available +* Requires `+networksetup+`, `+route+`, `+ping+`, `+dig+` +* Limited repair capabilities + +==== BSD + +* Similar to Linux +* Uses BSD-specific commands where needed + +==== Windows + +* Limited support +* Requires WSL2 for full functionality + +=== Troubleshooting + +*Error: `+dub: command not found+`* - Install D compiler and Dub package +manager + +*Error: `+ip: command not found+`* - Install iproute2: +`+sudo dnf install iproute+` or `+sudo apt install iproute2+` + +*Permission denied errors:* - Run with sudo for operations that modify +network configuration: +`+bash sudo ./bin/network-ambulance-d diagnose+` + +*Import errors:* - Make sure you’re in the network-ambulance directory - +Check that all source files are present in `+src/d/+` diff --git a/BUILD_D.md b/BUILD_D.md deleted file mode 100644 index b177030..0000000 --- a/BUILD_D.md +++ /dev/null @@ -1,135 +0,0 @@ -# Building Network Ambulance D Implementation - -## Prerequisites - -### Install D compiler (DMD or LDC) - -**Fedora:** -```bash -sudo dnf install dmd dub -``` - -**Ubuntu/Debian:** -```bash -curl -fsS https://dlang.org/install.sh | bash -s dmd -source ~/dlang/dmd-*/activate -``` - -**Arch:** -```bash -sudo pacman -S dlang dub -``` - -**Or use official installer:** -```bash -curl https://dlang.org/install.sh | bash -s -source ~/dlang/dmd-*/activate -``` - -## Building - -### Debug build (default): -```bash -dub build -``` - -### Release build (optimized): -```bash -dub build --build=release -``` - -### Safe mode build (extra safety checks): -```bash -dub build --build=safe -``` - -## Running - -```bash -# After building, binary is in bin/ -./bin/network-ambulance-d diagnose - -# Or run directly with dub (slower, recompiles): -dub run -- diagnose - -# Quick status: -./bin/network-ambulance-d status - -# Verbose diagnostics: -./bin/network-ambulance-d diagnose --verbose - -# Version: -./bin/network-ambulance-d version -``` - -## Testing - -```bash -# Run built-in tests: -dub test - -# Run with verbose output: -dub run -- diagnose -v -``` - -## Installation - -```bash -# Install to system: -dub build --build=release -sudo install -m 755 bin/network-ambulance-d /usr/local/bin/ -``` - -## Development - -```bash -# Clean build artifacts: -dub clean - -# Show dependencies: -dub describe - -# Lint code: -dub lint - -# Generate documentation: -dub build --build=docs -``` - -## Platform-Specific Notes - -### Linux -- Full feature set available -- Requires `ip`, `ping`, `dig` commands -- Some operations require root/sudo - -### macOS -- Basic diagnostics available -- Requires `networksetup`, `route`, `ping`, `dig` -- Limited repair capabilities - -### BSD -- Similar to Linux -- Uses BSD-specific commands where needed - -### Windows -- Limited support -- Requires WSL2 for full functionality - -## Troubleshooting - -**Error: `dub: command not found`** -- Install D compiler and Dub package manager - -**Error: `ip: command not found`** -- Install iproute2: `sudo dnf install iproute` or `sudo apt install iproute2` - -**Permission denied errors:** -- Run with sudo for operations that modify network configuration: - ```bash - sudo ./bin/network-ambulance-d diagnose - ``` - -**Import errors:** -- Make sure you're in the network-ambulance directory -- Check that all source files are present in `src/d/` diff --git a/BUILD_TAURI.md b/BUILD_TAURI.adoc similarity index 50% rename from BUILD_TAURI.md rename to BUILD_TAURI.adoc index 0ea06a1..3427187 100644 --- a/BUILD_TAURI.md +++ b/BUILD_TAURI.adoc @@ -1,17 +1,21 @@ -# Building Network Ambulance Tauri GUI +== Building Network Ambulance Tauri GUI -## Prerequisites +=== Prerequisites -### Required Tools -- **Rust** (1.70+): `curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh` -- **Deno** (1.40+): `curl -fsSL https://deno.land/install.sh | sh` -- **ReScript** (11.0+): Managed via Deno tasks -- **D Compiler** (for backend): See BUILD_D.md +==== Required Tools -### Platform-Specific Requirements +* *Rust* (1.70+): +`+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh+` +* *Deno* (1.40+): `+curl -fsSL https://deno.land/install.sh | sh+` +* *ReScript* (11.0+): Managed via Deno tasks +* *D Compiler* (for backend): See BUILD_D.md -**Linux:** -```bash +==== Platform-Specific Requirements + +*Linux:* + +[source,bash] +---- # Fedora sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file \ libappindicator-gtk3-devel librsvg2-devel @@ -19,80 +23,92 @@ sudo dnf install webkit2gtk4.1-devel openssl-devel curl wget file \ # Ubuntu/Debian sudo apt install libwebkit2gtk-4.1-dev build-essential curl wget file \ libxdo-dev libssl-dev libayatana-appindicator3-dev librsvg2-dev -``` +---- + +*macOS:* -**macOS:** -```bash +[source,bash] +---- # Xcode Command Line Tools xcode-select --install # Homebrew dependencies (if needed) brew install openssl -``` +---- -**Windows:** -- Install Visual Studio 2022 with C++ tools -- Install WebView2: https://developer.microsoft.com/microsoft-edge/webview2/ +*Windows:* - Install Visual Studio 2022 with C++ tools - Install +WebView2: https://developer.microsoft.com/microsoft-edge/webview2/ -## Development +=== Development -### First-time setup: -```bash +==== First-time setup: + +[source,bash] +---- # Install ReScript compiler deno task rescript build # Build D backend first dub build --build=release -``` +---- + +==== Run in development mode: -### Run in development mode: -```bash +[source,bash] +---- # Start dev server (hot reload) deno task tauri:dev -``` +---- -This will: -1. Start Vite dev server on localhost:5173 -2. Compile ReScript in watch mode -3. Launch Tauri app with dev tools +This will: 1. Start Vite dev server on localhost:5173 2. Compile +ReScript in watch mode 3. Launch Tauri app with dev tools -### Build for production: -```bash +==== Build for production: + +[source,bash] +---- # Build optimized release deno task tauri:build -``` +---- + +Outputs: - *Linux*: `+src-tauri/target/release/bundle/deb/*.deb+` - +*Linux*: `+src-tauri/target/release/bundle/appimage/*.AppImage+` - +*macOS*: `+src-tauri/target/release/bundle/dmg/*.dmg+` - *Windows*: +`+src-tauri/target/release/bundle/nsis/*.exe+` -Outputs: -- **Linux**: `src-tauri/target/release/bundle/deb/*.deb` -- **Linux**: `src-tauri/target/release/bundle/appimage/*.AppImage` -- **macOS**: `src-tauri/target/release/bundle/dmg/*.dmg` -- **Windows**: `src-tauri/target/release/bundle/nsis/*.exe` +=== Cross-Platform Builds -## Cross-Platform Builds +==== Windows (from Linux with cross-compilation): -### Windows (from Linux with cross-compilation): -```bash +[source,bash] +---- rustup target add x86_64-pc-windows-msvc cargo tauri build --target x86_64-pc-windows-msvc -``` +---- -### macOS (from macOS only): -```bash +==== macOS (from macOS only): + +[source,bash] +---- # Universal binary (Intel + Apple Silicon) rustup target add x86_64-apple-darwin aarch64-apple-darwin cargo tauri build --target universal-apple-darwin -``` +---- + +==== Linux ARM (Raspberry Pi, etc.): -### Linux ARM (Raspberry Pi, etc.): -```bash +[source,bash] +---- rustup target add aarch64-unknown-linux-gnu cargo tauri build --target aarch64-unknown-linux-gnu -``` +---- -## Mobile Builds +=== Mobile Builds -### Android: -```bash +==== Android: + +[source,bash] +---- # Add Android targets rustup target add aarch64-linux-android armv7-linux-androideabi @@ -104,10 +120,12 @@ cargo tauri android init # Build APK cargo tauri android build -``` +---- + +==== iOS (macOS only): -### iOS (macOS only): -```bash +[source,bash] +---- # Add iOS targets rustup target add aarch64-apple-ios x86_64-apple-ios @@ -116,28 +134,28 @@ cargo tauri ios init # Build for iOS cargo tauri ios build -``` +---- + +=== MINIX Support -## MINIX Support +*Tauri does not support MINIX* due to: - Rust limited support on MINIX +3.x - No WebView available - Modern GUI frameworks require newer +syscalls -**Tauri does not support MINIX** due to: -- Rust limited support on MINIX 3.x -- No WebView available -- Modern GUI frameworks require newer syscalls +*Fallback for MINIX:* Use the D CLI or Ada TUI instead: -**Fallback for MINIX:** -Use the D CLI or Ada TUI instead: -```bash +[source,bash] +---- # On MINIX, use command-line tools ./bin/network-ambulance-d diagnose ./bin/network-ambulance-tui -``` +---- See MINIX_BUILD.md for details on building D/Ada on MINIX. -## Project Structure +=== Project Structure -``` +.... network-ambulance/ ├── src/ │ └── rescript/ # ReScript frontend @@ -158,11 +176,12 @@ network-ambulance/ ├── vite.config.js # Vite bundler config ├── rescript.json # ReScript config └── deno.json # Deno tasks and imports -``` +.... -## Development Commands +=== Development Commands -```bash +[source,bash] +---- # ReScript compilation (watch mode) deno task rescript build -w @@ -183,76 +202,83 @@ deno task format # Lint Rust code cd src-tauri && cargo clippy -``` +---- + +=== Debugging + +==== Enable Tauri DevTools: -## Debugging +* Development mode automatically opens DevTools +* Or press `+Ctrl+Shift+I+` / `+Cmd+Option+I+` -### Enable Tauri DevTools: -- Development mode automatically opens DevTools -- Or press `Ctrl+Shift+I` / `Cmd+Option+I` +==== View Tauri logs: -### View Tauri logs: -```bash +[source,bash] +---- # Console logs from Rust RUST_LOG=debug cargo tauri dev # Full verbose logging RUST_LOG=trace cargo tauri dev -``` +---- -### Debug ReScript: -- ReScript compiles to readable JS -- Check `src/rescript/*.res.js` for compiled output -- Use browser DevTools to debug +==== Debug ReScript: -## Performance Optimization +* ReScript compiles to readable JS +* Check `+src/rescript/*.res.js+` for compiled output +* Use browser DevTools to debug -### Reduce Bundle Size: -```bash +=== Performance Optimization + +==== Reduce Bundle Size: + +[source,bash] +---- # Strip debug symbols cargo tauri build --config '{"bundle":{"windows":{"webviewInstallMode":{"type":"embedBootstrapper"}}}}' # Optimize ReScript output deno task rescript build -release -``` +---- -### Profile Performance: -```bash +==== Profile Performance: + +[source,bash] +---- # Rust profiling cargo tauri build --profile release-with-debug samply record ./target/release/network-ambulance # Frontend profiling # Use Chrome DevTools Performance tab -``` +---- + +=== Troubleshooting -## Troubleshooting +*Error: `+webkit2gtk not found+`* - Install WebKitGTK: +`+sudo dnf install webkit2gtk4.1-devel+` -**Error: `webkit2gtk not found`** -- Install WebKitGTK: `sudo dnf install webkit2gtk4.1-devel` +*Error: `+failed to run custom build command for 'tauri-build'+`* - +Update Rust: `+rustup update+` - Clean and rebuild: +`+cargo clean && cargo build+` -**Error: `failed to run custom build command for 'tauri-build'`** -- Update Rust: `rustup update` -- Clean and rebuild: `cargo clean && cargo build` +*Error: `+ReScript compilation failed+`* - Check rescript.json syntax - +Ensure `+@rescript/core+` is installed - Run +`+deno task rescript clean+` and retry -**Error: `ReScript compilation failed`** -- Check rescript.json syntax -- Ensure `@rescript/core` is installed -- Run `deno task rescript clean` and retry +*Error: `+D backend not found+`* - Build D backend first: +`+dub build --build=release+` - Ensure `+bin/network-ambulance-d+` +exists -**Error: `D backend not found`** -- Build D backend first: `dub build --build=release` -- Ensure `bin/network-ambulance-d` exists +*Mobile build fails:* - Verify Android SDK/NDK paths - Check Xcode +installation on macOS - Ensure mobile targets are installed -**Mobile build fails:** -- Verify Android SDK/NDK paths -- Check Xcode installation on macOS -- Ensure mobile targets are installed +=== CI/CD -## CI/CD +==== GitHub Actions (example): -### GitHub Actions (example): -```yaml +[source,yaml] +---- name: Build Tauri App on: [push] jobs: @@ -269,24 +295,22 @@ jobs: run: dub build --build=release - name: Build Tauri run: deno task tauri:build -``` - -## Platform Support Matrix - -| Platform | Architecture | Tauri Support | D Backend | Status | -|----------|-------------|---------------|-----------|--------| -| Linux | x86_64 | ✅ Full | ✅ Yes | ✅ Tested | -| Linux | ARM64 | ✅ Full | ✅ Yes | 🔄 Partial | -| macOS | Intel | ✅ Full | ✅ Yes | ⚠️ Untested | -| macOS | ARM (M1+) | ✅ Full | ✅ Yes | ⚠️ Untested | -| Windows | x86_64 | ✅ Full | ⚠️ Limited | ⚠️ Untested | -| Android | ARM64 | ✅ Tauri 2.0+ | ❌ CLI only | 🔄 In Progress | -| iOS | ARM64 | ✅ Tauri 2.0+ | ❌ CLI only | 🔄 In Progress | -| MINIX | x86 | ❌ No GUI | ✅ Yes | 📝 CLI/TUI only | - -Legend: -- ✅ Full support -- ⚠️ Limited/untested -- 🔄 Partial/in progress -- ❌ Not supported -- 📝 Documentation provided +---- + +=== Platform Support Matrix + +[width="100%",cols="19%,22%,26%,19%,14%",options="header",] +|=== +|Platform |Architecture |Tauri Support |D Backend |Status +|Linux |x86_64 |✅ Full |✅ Yes |✅ Tested +|Linux |ARM64 |✅ Full |✅ Yes |🔄 Partial +|macOS |Intel |✅ Full |✅ Yes |⚠️ Untested +|macOS |ARM (M1+) |✅ Full |✅ Yes |⚠️ Untested +|Windows |x86_64 |✅ Full |⚠️ Limited |⚠️ Untested +|Android |ARM64 |✅ Tauri 2.0+ |❌ CLI only |🔄 In Progress +|iOS |ARM64 |✅ Tauri 2.0+ |❌ CLI only |🔄 In Progress +|MINIX |x86 |❌ No GUI |✅ Yes |📝 CLI/TUI only +|=== + +Legend: - ✅ Full support - ⚠️ Limited/untested - 🔄 Partial/in progress +- ❌ Not supported - 📝 Documentation provided diff --git a/CHANGELOG.adoc b/CHANGELOG.adoc index 2d858f1..b656be1 100644 --- a/CHANGELOG.adoc +++ b/CHANGELOG.adoc @@ -1,86 +1,71 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Changelog +== Changelog -All notable changes to this project will be documented in this file. +All notable changes to `+network-ambulance+` will be documented in this +file. -The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), -and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +This file is generated from conventional commits by the +https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml[`+changelog-reusable.yml+`] +workflow (`+hyperpolymath/standards#206+`). Adopt the workflow in this +repo’s CI to keep this file in sync automatically — see +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+templates/cliff.toml+`] +for the canonical config. -== [Unreleased] +The format follows https://keepachangelog.com/en/1.1.0/[Keep a +Changelog]; this project aims to follow +https://semver.org/spec/v2.0.0.html[Semantic Versioning]. -=== Planned -- IPv6 connectivity diagnostics and repairs -- Wireless-specific diagnostics (signal strength, channel interference) -- VPN and proxy detection and diagnostics -- Web-based dashboard interface -- Package repository releases (apt, yum, AUR) +=== [Unreleased] -== [1.0.0] - 2025-01-22 +==== Added -=== Added -- Initial release -- Complete diagnostic suite: - - DNS configuration and resolution diagnostics - - Network interface status diagnostics - - Routing table diagnostics - - Internet connectivity testing - - Firewall configuration analysis - - NetworkManager status checking -- Automated repair procedures: - - DNS configuration repair - - Network interface management (bring up, DHCP renewal) - - Routing table repair - - NetworkManager reconnection -- Multiple operation modes: - - CLI mode for quick diagnostics - - Interactive guided mode - - Auto-repair mode - - Dry-run mode -- Core utility functions: - - Colored logging system - - Privilege checking and elevation - - Automatic file backup - - System detection (distribution, network manager) -- Safety features: - - Automatic backups before modifications - - Dry-run preview mode - - Detailed logging - - Root privilege checking -- Installation script -- Comprehensive test suite -- Multi-distribution support: - - Ubuntu/Debian family - - Fedora/RHEL family - - Arch Linux family -- Documentation: - - User README - - Contributing guidelines - - AI development guide (CLAUDE.md) - - Usage examples +* feat: add AI Gatekeeper Protocol manifest +* feat(ipv6): comprehensive IPv4/IPv6 dual-stack diagnostics and +monitoring +* feat(tauri+rescript): add cross-platform GUI with Tauri 2.0 + ReScript +* feat(ada): add Ada 2022 + SPARK TUI prototype +* feat(d): add JSON output mode for diagnostics and repairs +* feat(d): add routing repair module +* feat(d): add interface repair module +* feat(d): add DNS repair module and CLI repair command +* feat(d): add routing and connectivity diagnostics +* feat: initial D lang core engine implementation (prototype) -=== Security -- Input sanitization to prevent command injection -- Privilege escalation only when necessary -- File permission checks -- Backup of configuration files before modification +==== Fixed -== [0.1.0] - Development +* fix(ci): build Hypatia escript from repo root (estate dogfood drift) +* fix(ci): Phase-2 fleet submission must not fail the security gate (#5) +* fix(ci): hypatia-scan workdir ($\{\{ env.HOME }} resolves empty) (#4) +* fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#3) +* fix(ci): hypatia-scan.yml – pass GITHUB_TOKEN, use –exit-zero +(hyperpolymath/hypatia#213) (#2) +* fix: remove duplicate SCM files from root +* fix(security): update editorconfig SHA and CodeQL language +* fix: SHA-pin checkout action, add SPDX header and permissions +* fix: SHA-pin checkout action, add SPDX header and permissions +* fix: SHA-pin checkout action, add SPDX header and permissions -=== Added -- Initial project structure -- Basic diagnostic framework -- Proof of concept implementations +==== Documentation ---- +* docs: update SCM files with project information +* docs: add CONTRIBUTING.md +* docs: add checkpoint files for state tracking +* docs(ipv6): add comprehensive transition mechanism and monitoring +guides +* docs(minix): add comprehensive MINIX 3.x build documentation +* docs: add D lang core architecture and Ada/SPARK TUI design +* docs: add comprehensive network problem mapping by scope +* docs: update license from AGPL to PMPL -== Version History Summary +==== CI -=== Version 1.0.0 -- First stable release -- Production-ready diagnostic and repair tools -- Complete documentation -- Multi-distribution support +* ci: bump actions/upload-artifact SHA to current v4 (#1) -[Unreleased]: https://github.com/yourusername/complete-linux-internet-repair/compare/v1.0.0...HEAD -[1.0.0]: https://github.com/yourusername/complete-linux-internet-repair/releases/tag/v1.0.0 -[0.1.0]: https://github.com/yourusername/complete-linux-internet-repair/releases/tag/v0.1.0 +=== Pre-history + +Prior commits to this file’s introduction are recorded in git history +but not formally classified into Keep-a-Changelog sections. To backfill, +run `+git cliff -o CHANGELOG.md+` locally using the canonical +https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml[`+cliff.toml+`] +— this is one-shot mechanical work. + +''''' diff --git a/CHANGELOG.md b/CHANGELOG.md deleted file mode 100644 index bd2f7f1..0000000 --- a/CHANGELOG.md +++ /dev/null @@ -1,68 +0,0 @@ - - -# Changelog - -All notable changes to `network-ambulance` will be documented in this file. - -This file is generated from conventional commits by the -[`changelog-reusable.yml`](https://github.com/hyperpolymath/standards/blob/main/.github/workflows/changelog-reusable.yml) -workflow (`hyperpolymath/standards#206`). Adopt the workflow in this repo's CI to keep this file in sync automatically — see -[`templates/cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) -for the canonical config. - -The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/); -this project aims to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). - -## [Unreleased] - -### Added - -- feat: add AI Gatekeeper Protocol manifest -- feat(ipv6): comprehensive IPv4/IPv6 dual-stack diagnostics and monitoring -- feat(tauri+rescript): add cross-platform GUI with Tauri 2.0 + ReScript -- feat(ada): add Ada 2022 + SPARK TUI prototype -- feat(d): add JSON output mode for diagnostics and repairs -- feat(d): add routing repair module -- feat(d): add interface repair module -- feat(d): add DNS repair module and CLI repair command -- feat(d): add routing and connectivity diagnostics -- feat: initial D lang core engine implementation (prototype) - -### Fixed - -- fix(ci): build Hypatia escript from repo root (estate dogfood drift) -- fix(ci): Phase-2 fleet submission must not fail the security gate (#5) -- fix(ci): hypatia-scan workdir (${{ env.HOME }} resolves empty) (#4) -- fix(ci): bump erlef/setup-beam SHA for ubuntu24 runner support (#3) -- fix(ci): hypatia-scan.yml -- pass GITHUB_TOKEN, use --exit-zero (hyperpolymath/hypatia#213) (#2) -- fix: remove duplicate SCM files from root -- fix(security): update editorconfig SHA and CodeQL language -- fix: SHA-pin checkout action, add SPDX header and permissions -- fix: SHA-pin checkout action, add SPDX header and permissions -- fix: SHA-pin checkout action, add SPDX header and permissions - -### Documentation - -- docs: update SCM files with project information -- docs: add CONTRIBUTING.md -- docs: add checkpoint files for state tracking -- docs(ipv6): add comprehensive transition mechanism and monitoring guides -- docs(minix): add comprehensive MINIX 3.x build documentation -- docs: add D lang core architecture and Ada/SPARK TUI design -- docs: add comprehensive network problem mapping by scope -- docs: update license from AGPL to PMPL - -### CI - -- ci: bump actions/upload-artifact SHA to current v4 (#1) - -## Pre-history - -Prior commits to this file's introduction are recorded in git history but not formally classified into Keep-a-Changelog sections. To backfill, run `git cliff -o CHANGELOG.md` locally using the canonical [`cliff.toml`](https://github.com/hyperpolymath/standards/blob/main/templates/cliff.toml) — this is one-shot mechanical work. - ---- - - diff --git a/CODE_OF_CONDUCT.adoc b/CODE_OF_CONDUCT.adoc new file mode 100644 index 0000000..44a7f64 --- /dev/null +++ b/CODE_OF_CONDUCT.adoc @@ -0,0 +1,194 @@ +== Contributor Covenant Code of Conduct + +=== Our Pledge + +We as members, contributors, and leaders pledge to make participation in +our community a harassment-free experience for everyone, regardless of +age, body size, visible or invisible disability, ethnicity, sex +characteristics, gender identity and expression, level of experience, +education, socio-economic status, nationality, personal appearance, +race, caste, color, religion, or sexual identity and orientation. + +We pledge to act and interact in ways that contribute to an open, +welcoming, diverse, inclusive, and healthy community. + +=== Our Standards + +Examples of behavior that contributes to a positive environment for our +community include: + +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our +mistakes, and learning from the experience +* Focusing on what is best not just for us as individuals, but for the +overall community +* Using welcoming and inclusive language +* Being patient with newcomers and those learning +* Celebrating the contributions of all community members + +Examples of unacceptable behavior include: + +* The use of sexualized language or imagery, and sexual attention or +advances of any kind +* Trolling, insulting or derogatory comments, and personal or political +attacks +* Public or private harassment +* Publishing others’ private information, such as a physical or email +address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a +professional setting +* Dismissing or attacking inclusion-focused requests or concerns +* Sustained disruption of community discussions or events + +=== Emotional Safety + +In addition to the standard Contributor Covenant, we emphasize +*emotional safety*: + +* *Assume Good Intent*: Approach disagreements with curiosity, not +judgment +* *Right to Pause*: Anyone can request a pause in heated discussions +* *No Shaming*: Mistakes are learning opportunities, not ammunition +* *Reversibility*: Changes can be undone - experiment freely +* *Anxiety Awareness*: Be mindful that technical changes can cause +anxiety +* *Celebrate Trying*: Value attempts and experiments, not just successes + +These principles align with our TPCF framework’s emphasis on graduated +trust and psychological safety in open source contribution. + +=== Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our +standards of acceptable behavior and will take appropriate and fair +corrective action in response to any behavior that they deem +inappropriate, threatening, offensive, or harmful. + +Community leaders have the right and responsibility to remove, edit, or +reject comments, commits, code, wiki edits, issues, and other +contributions that are not aligned to this Code of Conduct, and will +communicate reasons for moderation decisions when appropriate. + +=== Scope + +This Code of Conduct applies within all community spaces, and also +applies when an individual is officially representing the community in +public spaces. Examples of representing our community include using an +official e-mail address, posting via an official social media account, +or acting as an appointed representative at an online or offline event. + +=== Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may +be reported to the community leaders responsible for enforcement at: + +*[INSERT CONTACT EMAIL]* + +All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security +of the reporter of any incident. + +=== Enforcement Guidelines + +Community leaders will follow these Community Impact Guidelines in +determining the consequences for any action they deem in violation of +this Code of Conduct: + +==== 1. Correction + +*Community Impact*: Use of inappropriate language or other behavior +deemed unprofessional or unwelcome in the community. + +*Consequence*: A private, written warning from community leaders, +providing clarity around the nature of the violation and an explanation +of why the behavior was inappropriate. A public apology may be +requested. + +==== 2. Warning + +*Community Impact*: A violation through a single incident or series of +actions. + +*Consequence*: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, for a specified period of +time. This includes avoiding interactions in community spaces as well as +external channels like social media. Violating these terms may lead to a +temporary or permanent ban. + +==== 3. Temporary Ban + +*Community Impact*: A serious violation of community standards, +including sustained inappropriate behavior. + +*Consequence*: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No +public or private interaction with the people involved, including +unsolicited interaction with those enforcing the Code of Conduct, is +allowed during this period. Violating these terms may lead to a +permanent ban. + +==== 4. Permanent Ban + +*Community Impact*: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of +individuals. + +*Consequence*: A permanent ban from any sort of public interaction +within the community. + +=== TPCF Integration + +This Code of Conduct integrates with our Tri-Perimeter Contribution +Framework (TPCF): + +* *Perimeter 3 (Community Sandbox)*: All contributors start here with +full CoC protections +* *Perimeter 2 (Trusted Contributors)*: Demonstrated alignment with CoC +values +* *Perimeter 1 (Maintainers)*: Responsible for CoC enforcement and +modeling + +See `+TPCF.md+` for details on how contributions are graduated based on +trust and demonstrated community values. + +=== Attribution + +This Code of Conduct is adapted from the +https://www.contributor-covenant.org[Contributor Covenant], version 2.1, +available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html. + +Community Impact Guidelines were inspired by +https://github.com/mozilla/diversity[Mozilla’s code of conduct +enforcement ladder]. + +For answers to common questions about this code of conduct, see the FAQ +at https://www.contributor-covenant.org/faq. Translations are available +at https://www.contributor-covenant.org/translations. + +=== Emotional Safety Addendum + +We recognize that open source contribution can be anxiety-inducing. To +support emotional safety: + +[arabic] +. *Reversibility Over Perfection*: All changes are reversible. Try +things! +. *No Shame Culture*: Mistakes are data, not failures +. *Explicit Consent*: Ask before major refactors or direction changes +. *Psychological Safety*: It’s safe to ask "`Why?`" and challenge +assumptions +. *Celebrate Experiments*: We value learning, even from failed +experiments + +These principles are inspired by the Emotional Temperature research in +the RSR framework. + +''''' + +*Version*: 2.1 + Emotional Safety Addendum *Last Updated*: 2025-01-22 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md deleted file mode 100644 index 597fa9e..0000000 --- a/CODE_OF_CONDUCT.md +++ /dev/null @@ -1,182 +0,0 @@ -# Contributor Covenant Code of Conduct - -## Our Pledge - -We as members, contributors, and leaders pledge to make participation in our -community a harassment-free experience for everyone, regardless of age, body -size, visible or invisible disability, ethnicity, sex characteristics, gender -identity and expression, level of experience, education, socio-economic status, -nationality, personal appearance, race, caste, color, religion, or sexual -identity and orientation. - -We pledge to act and interact in ways that contribute to an open, welcoming, -diverse, inclusive, and healthy community. - -## Our Standards - -Examples of behavior that contributes to a positive environment for our -community include: - -* Demonstrating empathy and kindness toward other people -* Being respectful of differing opinions, viewpoints, and experiences -* Giving and gracefully accepting constructive feedback -* Accepting responsibility and apologizing to those affected by our mistakes, - and learning from the experience -* Focusing on what is best not just for us as individuals, but for the overall - community -* Using welcoming and inclusive language -* Being patient with newcomers and those learning -* Celebrating the contributions of all community members - -Examples of unacceptable behavior include: - -* The use of sexualized language or imagery, and sexual attention or advances of - any kind -* Trolling, insulting or derogatory comments, and personal or political attacks -* Public or private harassment -* Publishing others' private information, such as a physical or email address, - without their explicit permission -* Other conduct which could reasonably be considered inappropriate in a - professional setting -* Dismissing or attacking inclusion-focused requests or concerns -* Sustained disruption of community discussions or events - -## Emotional Safety - -In addition to the standard Contributor Covenant, we emphasize **emotional safety**: - -* **Assume Good Intent**: Approach disagreements with curiosity, not judgment -* **Right to Pause**: Anyone can request a pause in heated discussions -* **No Shaming**: Mistakes are learning opportunities, not ammunition -* **Reversibility**: Changes can be undone - experiment freely -* **Anxiety Awareness**: Be mindful that technical changes can cause anxiety -* **Celebrate Trying**: Value attempts and experiments, not just successes - -These principles align with our TPCF framework's emphasis on graduated trust and -psychological safety in open source contribution. - -## Enforcement Responsibilities - -Community leaders are responsible for clarifying and enforcing our standards of -acceptable behavior and will take appropriate and fair corrective action in -response to any behavior that they deem inappropriate, threatening, offensive, -or harmful. - -Community leaders have the right and responsibility to remove, edit, or reject -comments, commits, code, wiki edits, issues, and other contributions that are -not aligned to this Code of Conduct, and will communicate reasons for moderation -decisions when appropriate. - -## Scope - -This Code of Conduct applies within all community spaces, and also applies when -an individual is officially representing the community in public spaces. -Examples of representing our community include using an official e-mail address, -posting via an official social media account, or acting as an appointed -representative at an online or offline event. - -## Enforcement - -Instances of abusive, harassing, or otherwise unacceptable behavior may be -reported to the community leaders responsible for enforcement at: - -**[INSERT CONTACT EMAIL]** - -All complaints will be reviewed and investigated promptly and fairly. - -All community leaders are obligated to respect the privacy and security of the -reporter of any incident. - -## Enforcement Guidelines - -Community leaders will follow these Community Impact Guidelines in determining -the consequences for any action they deem in violation of this Code of Conduct: - -### 1. Correction - -**Community Impact**: Use of inappropriate language or other behavior deemed -unprofessional or unwelcome in the community. - -**Consequence**: A private, written warning from community leaders, providing -clarity around the nature of the violation and an explanation of why the -behavior was inappropriate. A public apology may be requested. - -### 2. Warning - -**Community Impact**: A violation through a single incident or series of -actions. - -**Consequence**: A warning with consequences for continued behavior. No -interaction with the people involved, including unsolicited interaction with -those enforcing the Code of Conduct, for a specified period of time. This -includes avoiding interactions in community spaces as well as external channels -like social media. Violating these terms may lead to a temporary or permanent -ban. - -### 3. Temporary Ban - -**Community Impact**: A serious violation of community standards, including -sustained inappropriate behavior. - -**Consequence**: A temporary ban from any sort of interaction or public -communication with the community for a specified period of time. No public or -private interaction with the people involved, including unsolicited interaction -with those enforcing the Code of Conduct, is allowed during this period. -Violating these terms may lead to a permanent ban. - -### 4. Permanent Ban - -**Community Impact**: Demonstrating a pattern of violation of community -standards, including sustained inappropriate behavior, harassment of an -individual, or aggression toward or disparagement of classes of individuals. - -**Consequence**: A permanent ban from any sort of public interaction within the -community. - -## TPCF Integration - -This Code of Conduct integrates with our Tri-Perimeter Contribution Framework (TPCF): - -* **Perimeter 3 (Community Sandbox)**: All contributors start here with full CoC protections -* **Perimeter 2 (Trusted Contributors)**: Demonstrated alignment with CoC values -* **Perimeter 1 (Maintainers)**: Responsible for CoC enforcement and modeling - -See `TPCF.md` for details on how contributions are graduated based on trust and -demonstrated community values. - -## Attribution - -This Code of Conduct is adapted from the [Contributor Covenant][homepage], -version 2.1, available at -[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1]. - -Community Impact Guidelines were inspired by -[Mozilla's code of conduct enforcement ladder][Mozilla CoC]. - -For answers to common questions about this code of conduct, see the FAQ at -[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at -[https://www.contributor-covenant.org/translations][translations]. - -[homepage]: https://www.contributor-covenant.org -[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html -[Mozilla CoC]: https://github.com/mozilla/diversity -[FAQ]: https://www.contributor-covenant.org/faq -[translations]: https://www.contributor-covenant.org/translations - -## Emotional Safety Addendum - -We recognize that open source contribution can be anxiety-inducing. To support -emotional safety: - -1. **Reversibility Over Perfection**: All changes are reversible. Try things! -2. **No Shame Culture**: Mistakes are data, not failures -3. **Explicit Consent**: Ask before major refactors or direction changes -4. **Psychological Safety**: It's safe to ask "Why?" and challenge assumptions -5. **Celebrate Experiments**: We value learning, even from failed experiments - -These principles are inspired by the Emotional Temperature research in the RSR framework. - ---- - -**Version**: 2.1 + Emotional Safety Addendum -**Last Updated**: 2025-01-22 diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index eb045d6..59b4c30 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -1,20 +1,109 @@ -// SPDX-License-Identifier: CC-BY-SA-4.0 -= Contributing Guide +== Clone the repository -== Getting Started +git clone https://github.com/hyperpolymath/network-ambulance.git cd +network-ambulance -1. Fork the repository -2. Create a feature branch from `main` -3. Sign off commits (`git commit -s`) -4. Submit a pull request +== Using Nix (recommended for reproducibility) -== Commit Guidelines +nix develop -* Conventional commits: `type(scope): description` -* Sign all commits (DCO required) -* Atomic, focused commits +== Or using toolbox/distrobox -== License +toolbox create network-ambulance-dev toolbox enter network-ambulance-dev +# Install dependencies manually -Contributions licensed under project license. +== Verify setup +just check # or: cargo check / mix compile / etc. just test # Run test +suite + +.... + +### Repository Structure +.... + +network-ambulance/ ├── src/ # Source code (Perimeter 1-2) ├── lib/ # +Library code (Perimeter 1-2) ├── extensions/ # Extensions (Perimeter 2) +├── plugins/ # Plugins (Perimeter 2) ├── tools/ # Tooling (Perimeter 2) +├── docs/ # Documentation (Perimeter 3) │ ├── architecture/ # ADRs, +specs (Perimeter 2) │ └── proposals/ # RFCs (Perimeter 3) ├── examples/ +# Examples (Perimeter 3) ├── spec/ # Spec tests (Perimeter 3) ├── tests/ +# Test suite (Perimeter 2-3) ├── .well-known/ # Protocol files +(Perimeter 1-3) ├── .github/ # GitHub config (Perimeter 1) │ ├── +ISSUE_TEMPLATE/ │ └── workflows/ ├── CHANGELOG.md ├── CODE_OF_CONDUCT.md +├── CONTRIBUTING.md # This file ├── GOVERNANCE.md ├── LICENSE ├── +MAINTAINERS.md ├── README.adoc ├── SECURITY.md ├── flake.nix # Nix flake +(Perimeter 1) └── Justfile # Task runner (Perimeter 1) + +.... + +--- + +## How to Contribute + +### Reporting Bugs + +**Before reporting**: +1. Search existing issues +2. Check if it's already fixed in `main` +3. Determine which perimeter the bug affects + +**When reporting**: + +Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: + +- Clear, descriptive title +- Environment details (OS, versions, toolchain) +- Steps to reproduce +- Expected vs actual behaviour +- Logs, screenshots, or minimal reproduction + +### Suggesting Features + +**Before suggesting**: +1. Check the [roadmap](ROADMAP.md) if available +2. Search existing issues and discussions +3. Consider which perimeter the feature belongs to + +**When suggesting**: + +Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: + +- Problem statement (what pain point does this solve?) +- Proposed solution +- Alternatives considered +- Which perimeter this affects + +### Your First Contribution + +Look for issues labelled: + +- [`good first issue`](https://github.com/hyperpolymath/network-ambulance/labels/good%20first%20issue) — Simple Perimeter 3 tasks +- [`help wanted`](https://github.com/hyperpolymath/network-ambulance/labels/help%20wanted) — Community help needed +- [`documentation`](https://github.com/hyperpolymath/network-ambulance/labels/documentation) — Docs improvements +- [`perimeter-3`](https://github.com/hyperpolymath/network-ambulance/labels/perimeter-3) — Community sandbox scope + +--- + +## Development Workflow + +### Branch Naming +.... + +docs/short-description # Documentation (P3) test/what-added # Test +additions (P3) feat/short-description # New features (P2) +fix/issue-number-description # Bug fixes (P2) refactor/what-changed # +Code improvements (P2) security/what-fixed # Security fixes (P1-2) + +.... + +### Commit Messages + +We follow [Conventional Commits](https://www.conventionalcommits.org/): +.... + +(): + +{empty}[optional body] + +{empty}[optional footer] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md deleted file mode 100644 index f31799a..0000000 --- a/CONTRIBUTING.md +++ /dev/null @@ -1,116 +0,0 @@ -# Clone the repository -git clone https://github.com/hyperpolymath/network-ambulance.git -cd network-ambulance - -# Using Nix (recommended for reproducibility) -nix develop - -# Or using toolbox/distrobox -toolbox create network-ambulance-dev -toolbox enter network-ambulance-dev -# Install dependencies manually - -# Verify setup -just check # or: cargo check / mix compile / etc. -just test # Run test suite -``` - -### Repository Structure -``` -network-ambulance/ -├── src/ # Source code (Perimeter 1-2) -├── lib/ # Library code (Perimeter 1-2) -├── extensions/ # Extensions (Perimeter 2) -├── plugins/ # Plugins (Perimeter 2) -├── tools/ # Tooling (Perimeter 2) -├── docs/ # Documentation (Perimeter 3) -│ ├── architecture/ # ADRs, specs (Perimeter 2) -│ └── proposals/ # RFCs (Perimeter 3) -├── examples/ # Examples (Perimeter 3) -├── spec/ # Spec tests (Perimeter 3) -├── tests/ # Test suite (Perimeter 2-3) -├── .well-known/ # Protocol files (Perimeter 1-3) -├── .github/ # GitHub config (Perimeter 1) -│ ├── ISSUE_TEMPLATE/ -│ └── workflows/ -├── CHANGELOG.md -├── CODE_OF_CONDUCT.md -├── CONTRIBUTING.md # This file -├── GOVERNANCE.md -├── LICENSE -├── MAINTAINERS.md -├── README.adoc -├── SECURITY.md -├── flake.nix # Nix flake (Perimeter 1) -└── Justfile # Task runner (Perimeter 1) -``` - ---- - -## How to Contribute - -### Reporting Bugs - -**Before reporting**: -1. Search existing issues -2. Check if it's already fixed in `main` -3. Determine which perimeter the bug affects - -**When reporting**: - -Use the [bug report template](.github/ISSUE_TEMPLATE/bug_report.md) and include: - -- Clear, descriptive title -- Environment details (OS, versions, toolchain) -- Steps to reproduce -- Expected vs actual behaviour -- Logs, screenshots, or minimal reproduction - -### Suggesting Features - -**Before suggesting**: -1. Check the [roadmap](ROADMAP.md) if available -2. Search existing issues and discussions -3. Consider which perimeter the feature belongs to - -**When suggesting**: - -Use the [feature request template](.github/ISSUE_TEMPLATE/feature_request.md) and include: - -- Problem statement (what pain point does this solve?) -- Proposed solution -- Alternatives considered -- Which perimeter this affects - -### Your First Contribution - -Look for issues labelled: - -- [`good first issue`](https://github.com/hyperpolymath/network-ambulance/labels/good%20first%20issue) — Simple Perimeter 3 tasks -- [`help wanted`](https://github.com/hyperpolymath/network-ambulance/labels/help%20wanted) — Community help needed -- [`documentation`](https://github.com/hyperpolymath/network-ambulance/labels/documentation) — Docs improvements -- [`perimeter-3`](https://github.com/hyperpolymath/network-ambulance/labels/perimeter-3) — Community sandbox scope - ---- - -## Development Workflow - -### Branch Naming -``` -docs/short-description # Documentation (P3) -test/what-added # Test additions (P3) -feat/short-description # New features (P2) -fix/issue-number-description # Bug fixes (P2) -refactor/what-changed # Code improvements (P2) -security/what-fixed # Security fixes (P1-2) -``` - -### Commit Messages - -We follow [Conventional Commits](https://www.conventionalcommits.org/): -``` -(): - -[optional body] - -[optional footer] diff --git a/GOVERNANCE.adoc b/GOVERNANCE.adoc new file mode 100644 index 0000000..9b836fb --- /dev/null +++ b/GOVERNANCE.adoc @@ -0,0 +1,60 @@ +== Governance + +=== Overview + +This project is governed by the following principles and structures to +ensure transparent, inclusive, and effective decision-making. + +=== Roles and Responsibilities + +==== Maintainers + +Maintainers are responsible for: - Reviewing and merging pull requests - +Managing releases and versioning - Ensuring code quality and standards - +Triaging issues and bug reports - Community engagement and support + +==== Contributors + +Contributors are expected to: - Follow the code of conduct - Submit +well-documented pull requests - Write tests for new functionality - +Maintain existing tests - Update documentation as needed + +=== Decision Making + +==== Minor Changes + +* Can be made by any maintainer +* Include bug fixes, documentation updates, dependency updates + +==== Major Changes + +* Require discussion in issues or pull requests +* Include new features, architectural changes, API changes +* Need approval from at least 2 maintainers + +==== Breaking Changes + +* Require RFC (Request for Comments) process +* Need approval from majority of maintainers +* Must include migration guide + +=== Code of Conduct + +All participants are expected to follow our Code of Conduct. Violations +can be reported to the maintainers. + +=== Communication + +* *Issues*: For bug reports and feature requests +* *Discussions*: For questions and general discussion +* *Pull Requests*: For code contributions + +=== Licensing + +All contributions are made under the terms of the repository’s LICENSE +file. By submitting a pull request, you agree to license your +contributions accordingly. + +''''' + +_Last updated: 2026-07-18_ diff --git a/GOVERNANCE.md b/GOVERNANCE.md deleted file mode 100644 index e27364c..0000000 --- a/GOVERNANCE.md +++ /dev/null @@ -1,60 +0,0 @@ -# Governance - -## Overview - -This project is governed by the following principles and structures to ensure transparent, inclusive, and effective decision-making. - -## Roles and Responsibilities - -### Maintainers - -Maintainers are responsible for: -- Reviewing and merging pull requests -- Managing releases and versioning -- Ensuring code quality and standards -- Triaging issues and bug reports -- Community engagement and support - -### Contributors - -Contributors are expected to: -- Follow the code of conduct -- Submit well-documented pull requests -- Write tests for new functionality -- Maintain existing tests -- Update documentation as needed - -## Decision Making - -### Minor Changes -- Can be made by any maintainer -- Include bug fixes, documentation updates, dependency updates - -### Major Changes -- Require discussion in issues or pull requests -- Include new features, architectural changes, API changes -- Need approval from at least 2 maintainers - -### Breaking Changes -- Require RFC (Request for Comments) process -- Need approval from majority of maintainers -- Must include migration guide - -## Code of Conduct - -All participants are expected to follow our Code of Conduct. Violations can be reported to the maintainers. - -## Communication - -- **Issues**: For bug reports and feature requests -- **Discussions**: For questions and general discussion -- **Pull Requests**: For code contributions - -## Licensing - -All contributions are made under the terms of the repository's LICENSE file. -By submitting a pull request, you agree to license your contributions accordingly. - ---- - -*Last updated: 2026-07-18* diff --git a/MAINTAINERS.adoc b/MAINTAINERS.adoc new file mode 100644 index 0000000..df0e159 --- /dev/null +++ b/MAINTAINERS.adoc @@ -0,0 +1,181 @@ +== Maintainers + +This document lists the maintainers of the Complete Linux Internet +Repair Tool project. + +=== Active Maintainers + +==== Project Lead + +*[Your Name]* (@[your-github-username]) - *Role*: Project Lead, Primary +Maintainer - *Responsibilities*: - Overall project direction and vision +- Architecture decisions - Release management - Security response +coordination - Final decision authority on contentious issues - *Focus +Areas*: All - *Contact*: [your-email@example.com] - *Timezone*: [Your +Timezone] - *Since*: 2025-01-22 + +=== Maintainer Responsibilities + +Maintainers are responsible for: + +[arabic] +. *Code Review*: Review and merge pull requests +. *Issue Triage*: Label, prioritize, and respond to issues +. *Security*: Respond to security reports and coordinate fixes +. *Releases*: Tag and publish releases +. *Community*: Enforce Code of Conduct, welcome newcomers +. *Documentation*: Keep docs up-to-date +. *Testing*: Ensure test quality and coverage +. *Communication*: Regular status updates to community + +=== Maintainer Levels + +==== L1: Core Maintainer (Currently: 1) + +* Full commit access to main branch +* Can merge PRs and manage releases +* Security incident response authority +* Voting rights on project direction + +==== L2: Module Maintainer (Currently: 0) + +* Expert in specific module (diagnostics, repairs, etc.) +* Review authority for their module +* Can approve PRs in their domain +* Recommended for promotion to L1 + +==== L3: Reviewer (Currently: 0) + +* Trusted community member +* Can review and approve PRs +* No direct commit access +* In training for L2 + +=== Becoming a Maintainer + +We follow the TPCF (Tri-Perimeter Contribution Framework) for trust +progression: + +==== Path to L3 Reviewer + +* *Requirements*: +** 10+ substantial contributions (PRs, issues, reviews) +** Demonstrated code quality and testing practices +** Positive community interactions +** Understanding of project architecture +** 3+ months of consistent participation +* *Nomination*: Current maintainers nominate, consensus required +* *Perimeter*: Promotion from TPCF Perimeter 3 to Perimeter 2 + +==== Path to L2 Module Maintainer + +* *Requirements*: +** Expert knowledge in specific module +** 25+ contributions, including major features +** Consistent high-quality code reviews +** Documentation contributions +** 6+ months as L3 Reviewer +* *Nomination*: L1 maintainers nominate, consensus required +* *Perimeter*: Perimeter 2 with expanded privileges + +==== Path to L1 Core Maintainer + +* *Requirements*: +** Deep understanding of entire codebase +** Security awareness and response capability +** Demonstrated leadership and community building +** Release management experience +** 50+ contributions across all areas +** 12+ months as L2 Module Maintainer +* *Nomination*: Existing L1 maintainers vote, unanimous required +* *Perimeter*: Promotion to TPCF Perimeter 1 + +=== Maintainer Meetings + +* *Frequency*: Monthly (or as needed) +* *Format*: Async-first (GitHub Discussions), sync if needed +* *Agenda*: Project roadmap, security issues, community health +* *Notes*: Published in `+docs/meetings/+` directory + +=== Decision Making + +==== Consensus Model + +We use *lazy consensus* for most decisions: + +[arabic] +. *Proposal*: Anyone can propose via issue/PR +. *Discussion*: Minimum 72 hours for feedback +. *Objections*: If no objections, proposal accepted +. *Disagreement*: If objections, discuss to consensus +. *Escalation*: If no consensus, maintainer vote (simple majority) +. *Final Call*: Project Lead can make final decision if needed + +==== Voting + +When voting is required: + +* *Quorum*: 50%+ of L1 maintainers must participate +* *Threshold*: Simple majority (>50%) for most issues +* *Supermajority*: 2/3+ for: +** Adding/removing maintainers +** Major architecture changes +** License changes +** Code of Conduct changes + +=== Emeritus Maintainers + +Maintainers who have stepped down but contributed significantly: + +_None yet - founding project_ + +=== Adding/Removing Maintainers + +==== Adding + +[arabic] +. Nomination by current L1 maintainer +. Review of contributions and community engagement +. Vote by L1 maintainers (supermajority required) +. Update MAINTAINERS.md and repository permissions +. Announcement to community + +==== Removing + +Maintainers may be removed for: - *Inactivity*: No activity for 6+ +months (emeritus status offered) - *Code of Conduct violation*: Serious +or repeated violations - *Abandonment*: Announced departure from project +- *Request*: Maintainer requests to step down + +Process: 1. Discussion among L1 maintainers 2. Attempt to contact +maintainer (if inactive) 3. Vote (supermajority required for CoC +violations) 4. Update MAINTAINERS.md and revoke access 5. Announcement +with gratitude for contributions + +=== Contact + +* *General*: Open an issue on GitHub +* *Security*: See SECURITY.md for reporting vulnerabilities +* *Private*: [maintainers@project-domain.com] (if available) +* *Code of Conduct*: See CODE_OF_CONDUCT.md for reporting + +=== Maintainer Emeritus + +When maintainers step down, they are honored here with emeritus status: + +[cols=",,,,",options="header",] +|=== +|Name |GitHub |Role |Active Period |Notable Contributions +|_Awaiting first emeritus maintainer_ | | | | +|=== + +=== Recognition + +We thank all maintainers for their service to the community. +Maintainership is a responsibility, not a privilege, and we honor those +who take it on. + +''''' + +*Last Updated*: 2025-01-22 *Governance Model*: TPCF + Lazy Consensus +*Version*: 1.0 diff --git a/MAINTAINERS.md b/MAINTAINERS.md deleted file mode 100644 index 85c9055..0000000 --- a/MAINTAINERS.md +++ /dev/null @@ -1,175 +0,0 @@ -# Maintainers - -This document lists the maintainers of the Complete Linux Internet Repair Tool project. - -## Active Maintainers - -### Project Lead - -**[Your Name]** (@[your-github-username]) -- **Role**: Project Lead, Primary Maintainer -- **Responsibilities**: - - Overall project direction and vision - - Architecture decisions - - Release management - - Security response coordination - - Final decision authority on contentious issues -- **Focus Areas**: All -- **Contact**: [your-email@example.com] -- **Timezone**: [Your Timezone] -- **Since**: 2025-01-22 - -## Maintainer Responsibilities - -Maintainers are responsible for: - -1. **Code Review**: Review and merge pull requests -2. **Issue Triage**: Label, prioritize, and respond to issues -3. **Security**: Respond to security reports and coordinate fixes -4. **Releases**: Tag and publish releases -5. **Community**: Enforce Code of Conduct, welcome newcomers -6. **Documentation**: Keep docs up-to-date -7. **Testing**: Ensure test quality and coverage -8. **Communication**: Regular status updates to community - -## Maintainer Levels - -### L1: Core Maintainer (Currently: 1) -- Full commit access to main branch -- Can merge PRs and manage releases -- Security incident response authority -- Voting rights on project direction - -### L2: Module Maintainer (Currently: 0) -- Expert in specific module (diagnostics, repairs, etc.) -- Review authority for their module -- Can approve PRs in their domain -- Recommended for promotion to L1 - -### L3: Reviewer (Currently: 0) -- Trusted community member -- Can review and approve PRs -- No direct commit access -- In training for L2 - -## Becoming a Maintainer - -We follow the TPCF (Tri-Perimeter Contribution Framework) for trust progression: - -### Path to L3 Reviewer -- **Requirements**: - - 10+ substantial contributions (PRs, issues, reviews) - - Demonstrated code quality and testing practices - - Positive community interactions - - Understanding of project architecture - - 3+ months of consistent participation -- **Nomination**: Current maintainers nominate, consensus required -- **Perimeter**: Promotion from TPCF Perimeter 3 to Perimeter 2 - -### Path to L2 Module Maintainer -- **Requirements**: - - Expert knowledge in specific module - - 25+ contributions, including major features - - Consistent high-quality code reviews - - Documentation contributions - - 6+ months as L3 Reviewer -- **Nomination**: L1 maintainers nominate, consensus required -- **Perimeter**: Perimeter 2 with expanded privileges - -### Path to L1 Core Maintainer -- **Requirements**: - - Deep understanding of entire codebase - - Security awareness and response capability - - Demonstrated leadership and community building - - Release management experience - - 50+ contributions across all areas - - 12+ months as L2 Module Maintainer -- **Nomination**: Existing L1 maintainers vote, unanimous required -- **Perimeter**: Promotion to TPCF Perimeter 1 - -## Maintainer Meetings - -- **Frequency**: Monthly (or as needed) -- **Format**: Async-first (GitHub Discussions), sync if needed -- **Agenda**: Project roadmap, security issues, community health -- **Notes**: Published in `docs/meetings/` directory - -## Decision Making - -### Consensus Model - -We use **lazy consensus** for most decisions: - -1. **Proposal**: Anyone can propose via issue/PR -2. **Discussion**: Minimum 72 hours for feedback -3. **Objections**: If no objections, proposal accepted -4. **Disagreement**: If objections, discuss to consensus -5. **Escalation**: If no consensus, maintainer vote (simple majority) -6. **Final Call**: Project Lead can make final decision if needed - -### Voting - -When voting is required: - -- **Quorum**: 50%+ of L1 maintainers must participate -- **Threshold**: Simple majority (>50%) for most issues -- **Supermajority**: 2/3+ for: - - Adding/removing maintainers - - Major architecture changes - - License changes - - Code of Conduct changes - -## Emeritus Maintainers - -Maintainers who have stepped down but contributed significantly: - -*None yet - founding project* - -## Adding/Removing Maintainers - -### Adding -1. Nomination by current L1 maintainer -2. Review of contributions and community engagement -3. Vote by L1 maintainers (supermajority required) -4. Update MAINTAINERS.md and repository permissions -5. Announcement to community - -### Removing -Maintainers may be removed for: -- **Inactivity**: No activity for 6+ months (emeritus status offered) -- **Code of Conduct violation**: Serious or repeated violations -- **Abandonment**: Announced departure from project -- **Request**: Maintainer requests to step down - -Process: -1. Discussion among L1 maintainers -2. Attempt to contact maintainer (if inactive) -3. Vote (supermajority required for CoC violations) -4. Update MAINTAINERS.md and revoke access -5. Announcement with gratitude for contributions - -## Contact - -- **General**: Open an issue on GitHub -- **Security**: See SECURITY.md for reporting vulnerabilities -- **Private**: [maintainers@project-domain.com] (if available) -- **Code of Conduct**: See CODE_OF_CONDUCT.md for reporting - -## Maintainer Emeritus - -When maintainers step down, they are honored here with emeritus status: - -| Name | GitHub | Role | Active Period | Notable Contributions | -|------|--------|------|---------------|----------------------| -| *Awaiting first emeritus maintainer* | | | | | - -## Recognition - -We thank all maintainers for their service to the community. Maintainership is -a responsibility, not a privilege, and we honor those who take it on. - ---- - -**Last Updated**: 2025-01-22 -**Governance Model**: TPCF + Lazy Consensus -**Version**: 1.0 diff --git a/MINIX_BUILD.adoc b/MINIX_BUILD.adoc new file mode 100644 index 0000000..811cd1b --- /dev/null +++ b/MINIX_BUILD.adoc @@ -0,0 +1,318 @@ +== Building Network Ambulance on MINIX + +=== Overview + +MINIX 3.x support is *limited to command-line tools* (D CLI and Ada TUI) +due to: - *No Tauri GUI*: Rust std support incomplete, no +WebView2/WebKitGTK - *Limited modern toolchain*: C++17/20 features +unavailable - *No ReScript/Deno*: V8 engine not available + +*Supported on MINIX:* - ✅ D CLI (`+network-ambulance-d+`) - ✅ Ada TUI +(`+network_ambulance_tui+`) - ✅ Shell scripts (legacy Bash +implementation) + +*NOT Supported on MINIX:* - ❌ Tauri + ReScript GUI - ❌ Mobile builds - +❌ Modern web technologies + +=== Prerequisites + +==== MINIX 3.4.0+ Required + +[source,bash] +---- +# Check MINIX version +uname -a +# Should show: MINIX 3.4.0 or later +---- + +==== Install pkgin Package Manager + +[source,bash] +---- +# Update pkgin +pkgin update + +# Install build tools +pkgin install gmake gcc binutils +---- + +=== Building D CLI on MINIX + +==== Install DMD (D Compiler) + +*Option 1: From Binary (Recommended)* + +[source,bash] +---- +# Download DMD for NetBSD (MINIX uses NetBSD pkgsrc) +cd /tmp +curl -LO https://downloads.dlang.org/releases/2.x/2.110.0/dmd.2.110.0.netbsd-x86.tar.xz +tar xf dmd.2.110.0.netbsd-x86.tar.xz +sudo cp -r dmd2/* /usr/local/ + +# Verify +dmd --version +---- + +*Option 2: From pkgsrc* + +[source,bash] +---- +# If available in pkgsrc +pkgin search dmd +pkgin install dmd dub +---- + +==== Build Network Ambulance D CLI + +[source,bash] +---- +cd ~/network-ambulance + +# Build release binary +dub build --build=release + +# Test +./bin/network-ambulance-d version +./bin/network-ambulance-d diagnose +---- + +==== MINIX-Specific Notes + +*Network Commands:* - MINIX uses older `+ifconfig+` instead of `+ip+` +(Linux) - Some diagnostics may require root: `+su+` then run commands - +`+dig+` may not be available - use `+nslookup+` fallback + +*Expected Limitations:* - No systemd (uses rc scripts) - Limited +wireless support - IPv6 may be incomplete - Some repair operations +unavailable + +=== Building Ada TUI on MINIX + +==== Install GNAT (Ada Compiler) + +[source,bash] +---- +# GNAT from pkgsrc (if available) +pkgin search gnat +pkgin install gcc-ada gprbuild + +# Or build from source (advanced) +# Download GNAT from https://gcc.gnu.org/ +---- + +==== Build Network Ambulance Ada TUI + +[source,bash] +---- +cd ~/network-ambulance + +# Build Ada TUI +gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=release + +# Test +./bin/network_ambulance_tui +---- + +==== Terminal Requirements + +The Ada TUI uses ANSI escape codes and requires: - VT100-compatible +terminal - UTF-8 support (optional, uses ASCII fallback) + +On MINIX console: + +[source,bash] +---- +# Set TERM if needed +export TERM=vt100 + +# Run TUI +./bin/network_ambulance_tui +---- + +=== Platform Abstraction for MINIX + +The D platform code needs MINIX-specific implementation: + +==== Create `+src/d/platform/minix.d+`: + +[source,d] +---- +// MINIX platform implementation +module platform.minix; + +import platform.iface; +import platform.types; + +class MinixPlatform : NetworkPlatform { + // Uses ifconfig instead of ip command + override InterfaceInfo[] getInterfaces() @trusted { + import std.process : execute; + auto result = execute(["ifconfig", "-a"]); + // Parse ifconfig output (BSD-style) + // ... + } + + // MINIX-specific implementations + // ... +} + +NetworkPlatform getPlatform() @safe { + return new MinixPlatform(); +} +---- + +==== Modify `+src/d/platform/package.d+`: + +[source,d] +---- +version(MINIX) { + public import platform.minix; +} else version(linux) { + public import platform.linux; +} else // ... +---- + +==== Build with MINIX Support: + +[source,d] +---- +dub build --build=release -d MINIX +---- + +=== Shell Script Fallback + +If D/Ada compilation fails, use the legacy Bash implementation: + +[source,bash] +---- +# The original Bash version works on MINIX +cd ~/network-ambulance +chmod +x network-ambulance.sh + +# Run diagnostics +./network-ambulance.sh diagnose + +# Run repairs (requires root) +su +./network-ambulance.sh repair +---- + +=== Cross-Compilation to MINIX + +==== From Linux to MINIX: + +[source,bash] +---- +# Install MINIX cross-compiler +# (Not commonly available, build from source) + +# Cross-compile D +dmd -m32 -od=obj-minix -of=bin/network-ambulance-d-minix src/d/**/*.d + +# Transfer to MINIX +scp bin/network-ambulance-d-minix user@minix-host:/usr/local/bin/ +---- + +=== Troubleshooting + +==== Error: `+dmd: command not found+` + +* Install DMD from NetBSD packages or binary download +* Add to PATH: `+export PATH=$PATH:/usr/local/dmd2/bin+` + +==== Error: `+ip: command not found+` + +* Expected on MINIX - D code should detect and use `+ifconfig+` +* Implement MINIX platform abstraction (see above) + +==== Error: `+gprbuild: command not found+` + +* Install GNAT/gprbuild from pkgsrc +* Or skip Ada TUI and use D CLI only + +==== Network commands fail: + +* Run with root: `+su+` or `+sudo+` (if configured) +* Check if interface names differ (e.g., `+re0+` instead of `+eth0+`) + +==== Terminal rendering issues: + +[source,bash] +---- +# Set basic terminal +export TERM=vt100 + +# Disable UTF-8 if garbled +export LC_ALL=C +---- + +=== Performance Considerations + +MINIX is designed for reliability over performance: - D CLI: Fast, +lightweight (~2-5MB binary) - Ada TUI: Slightly larger (~300KB), but +still efficient - Expect slower execution than Linux/BSD - Network +operations may take longer + +=== Feature Matrix: MINIX vs Other Platforms + +[cols=",,,,",options="header",] +|=== +|Feature |MINIX |Linux |macOS |Windows +|D CLI |✅ |✅ |✅ |⚠️ Limited +|Ada TUI |✅ |✅ |✅ |⚠️ Limited +|Tauri GUI |❌ |✅ |✅ |✅ +|Mobile GUI |❌ |❌ |✅ iOS |✅ Android +|DNS Diagnostics |✅ |✅ |✅ |✅ +|Routing Diagnostics |⚠️ Basic |✅ Full |✅ Full |⚠️ Limited +|Interface Diagnostics |✅ |✅ |✅ |⚠️ Limited +|Automated Repairs |⚠️ Limited |✅ Full |⚠️ Limited |❌ +|JSON Output |✅ |✅ |✅ |✅ +|SPARK Verification |✅ |✅ |✅ |✅ +|=== + +Legend: - ✅ Fully supported - ⚠️ Partially supported / limited - ❌ Not +supported + +=== Recommended Configuration for MINIX + +Use the *D CLI* for MINIX deployments: + +[source,bash] +---- +# Install D CLI +dub build --build=release + +# Create alias for convenience +echo 'alias netamb="/usr/local/bin/network-ambulance-d"' >> ~/.profile + +# Run diagnostics +netamb diagnose + +# Get JSON output for scripting +netamb diagnose --json | json_pp +---- + +For interactive use, the *Ada TUI* provides a better experience than raw +CLI. + +=== Future MINIX Support + +Potential improvements: - [ ] Complete MINIX platform abstraction in D - +[ ] Port more repair operations to MINIX - [ ] MINIX-specific test suite +- [ ] pkgsrc package for easy installation - [ ] MINIX 4.x support when +available + +=== References + +* MINIX 3 Official: https://www.minix3.org/ +* pkgin Documentation: https://pkgin.net/ +* D Language on BSD: https://dlang.org/download.html#bsd +* GNAT on NetBSD: https://www.netbsd.org/docs/pkgsrc/ + +=== Support + +For MINIX-specific issues: - Check if feature exists on target platform +- Use D CLI instead of GUI for maximum compatibility - Report MINIX bugs +with `+uname -a+` output - Test on MINIX 3.4.0+ (earlier versions +untested) diff --git a/MINIX_BUILD.md b/MINIX_BUILD.md deleted file mode 100644 index d49996c..0000000 --- a/MINIX_BUILD.md +++ /dev/null @@ -1,305 +0,0 @@ -# Building Network Ambulance on MINIX - -## Overview - -MINIX 3.x support is **limited to command-line tools** (D CLI and Ada TUI) due to: -- **No Tauri GUI**: Rust std support incomplete, no WebView2/WebKitGTK -- **Limited modern toolchain**: C++17/20 features unavailable -- **No ReScript/Deno**: V8 engine not available - -**Supported on MINIX:** -- ✅ D CLI (`network-ambulance-d`) -- ✅ Ada TUI (`network_ambulance_tui`) -- ✅ Shell scripts (legacy Bash implementation) - -**NOT Supported on MINIX:** -- ❌ Tauri + ReScript GUI -- ❌ Mobile builds -- ❌ Modern web technologies - -## Prerequisites - -### MINIX 3.4.0+ Required - -```bash -# Check MINIX version -uname -a -# Should show: MINIX 3.4.0 or later -``` - -### Install pkgin Package Manager - -```bash -# Update pkgin -pkgin update - -# Install build tools -pkgin install gmake gcc binutils -``` - -## Building D CLI on MINIX - -### Install DMD (D Compiler) - -**Option 1: From Binary (Recommended)** -```bash -# Download DMD for NetBSD (MINIX uses NetBSD pkgsrc) -cd /tmp -curl -LO https://downloads.dlang.org/releases/2.x/2.110.0/dmd.2.110.0.netbsd-x86.tar.xz -tar xf dmd.2.110.0.netbsd-x86.tar.xz -sudo cp -r dmd2/* /usr/local/ - -# Verify -dmd --version -``` - -**Option 2: From pkgsrc** -```bash -# If available in pkgsrc -pkgin search dmd -pkgin install dmd dub -``` - -### Build Network Ambulance D CLI - -```bash -cd ~/network-ambulance - -# Build release binary -dub build --build=release - -# Test -./bin/network-ambulance-d version -./bin/network-ambulance-d diagnose -``` - -### MINIX-Specific Notes - -**Network Commands:** -- MINIX uses older `ifconfig` instead of `ip` (Linux) -- Some diagnostics may require root: `su` then run commands -- `dig` may not be available - use `nslookup` fallback - -**Expected Limitations:** -- No systemd (uses rc scripts) -- Limited wireless support -- IPv6 may be incomplete -- Some repair operations unavailable - -## Building Ada TUI on MINIX - -### Install GNAT (Ada Compiler) - -```bash -# GNAT from pkgsrc (if available) -pkgin search gnat -pkgin install gcc-ada gprbuild - -# Or build from source (advanced) -# Download GNAT from https://gcc.gnu.org/ -``` - -### Build Network Ambulance Ada TUI - -```bash -cd ~/network-ambulance - -# Build Ada TUI -gprbuild -P network_ambulance_tui.gpr -XBUILD_MODE=release - -# Test -./bin/network_ambulance_tui -``` - -### Terminal Requirements - -The Ada TUI uses ANSI escape codes and requires: -- VT100-compatible terminal -- UTF-8 support (optional, uses ASCII fallback) - -On MINIX console: -```bash -# Set TERM if needed -export TERM=vt100 - -# Run TUI -./bin/network_ambulance_tui -``` - -## Platform Abstraction for MINIX - -The D platform code needs MINIX-specific implementation: - -### Create `src/d/platform/minix.d`: - -```d -// MINIX platform implementation -module platform.minix; - -import platform.iface; -import platform.types; - -class MinixPlatform : NetworkPlatform { - // Uses ifconfig instead of ip command - override InterfaceInfo[] getInterfaces() @trusted { - import std.process : execute; - auto result = execute(["ifconfig", "-a"]); - // Parse ifconfig output (BSD-style) - // ... - } - - // MINIX-specific implementations - // ... -} - -NetworkPlatform getPlatform() @safe { - return new MinixPlatform(); -} -``` - -### Modify `src/d/platform/package.d`: - -```d -version(MINIX) { - public import platform.minix; -} else version(linux) { - public import platform.linux; -} else // ... -``` - -### Build with MINIX Support: - -```d -dub build --build=release -d MINIX -``` - -## Shell Script Fallback - -If D/Ada compilation fails, use the legacy Bash implementation: - -```bash -# The original Bash version works on MINIX -cd ~/network-ambulance -chmod +x network-ambulance.sh - -# Run diagnostics -./network-ambulance.sh diagnose - -# Run repairs (requires root) -su -./network-ambulance.sh repair -``` - -## Cross-Compilation to MINIX - -### From Linux to MINIX: - -```bash -# Install MINIX cross-compiler -# (Not commonly available, build from source) - -# Cross-compile D -dmd -m32 -od=obj-minix -of=bin/network-ambulance-d-minix src/d/**/*.d - -# Transfer to MINIX -scp bin/network-ambulance-d-minix user@minix-host:/usr/local/bin/ -``` - -## Troubleshooting - -### Error: `dmd: command not found` -- Install DMD from NetBSD packages or binary download -- Add to PATH: `export PATH=$PATH:/usr/local/dmd2/bin` - -### Error: `ip: command not found` -- Expected on MINIX - D code should detect and use `ifconfig` -- Implement MINIX platform abstraction (see above) - -### Error: `gprbuild: command not found` -- Install GNAT/gprbuild from pkgsrc -- Or skip Ada TUI and use D CLI only - -### Network commands fail: -- Run with root: `su` or `sudo` (if configured) -- Check if interface names differ (e.g., `re0` instead of `eth0`) - -### Terminal rendering issues: -```bash -# Set basic terminal -export TERM=vt100 - -# Disable UTF-8 if garbled -export LC_ALL=C -``` - -## Performance Considerations - -MINIX is designed for reliability over performance: -- D CLI: Fast, lightweight (~2-5MB binary) -- Ada TUI: Slightly larger (~300KB), but still efficient -- Expect slower execution than Linux/BSD -- Network operations may take longer - -## Feature Matrix: MINIX vs Other Platforms - -| Feature | MINIX | Linux | macOS | Windows | -|---------|-------|-------|-------|---------| -| D CLI | ✅ | ✅ | ✅ | ⚠️ Limited | -| Ada TUI | ✅ | ✅ | ✅ | ⚠️ Limited | -| Tauri GUI | ❌ | ✅ | ✅ | ✅ | -| Mobile GUI | ❌ | ❌ | ✅ iOS | ✅ Android | -| DNS Diagnostics | ✅ | ✅ | ✅ | ✅ | -| Routing Diagnostics | ⚠️ Basic | ✅ Full | ✅ Full | ⚠️ Limited | -| Interface Diagnostics | ✅ | ✅ | ✅ | ⚠️ Limited | -| Automated Repairs | ⚠️ Limited | ✅ Full | ⚠️ Limited | ❌ | -| JSON Output | ✅ | ✅ | ✅ | ✅ | -| SPARK Verification | ✅ | ✅ | ✅ | ✅ | - -Legend: -- ✅ Fully supported -- ⚠️ Partially supported / limited -- ❌ Not supported - -## Recommended Configuration for MINIX - -Use the **D CLI** for MINIX deployments: - -```bash -# Install D CLI -dub build --build=release - -# Create alias for convenience -echo 'alias netamb="/usr/local/bin/network-ambulance-d"' >> ~/.profile - -# Run diagnostics -netamb diagnose - -# Get JSON output for scripting -netamb diagnose --json | json_pp -``` - -For interactive use, the **Ada TUI** provides a better experience than raw CLI. - -## Future MINIX Support - -Potential improvements: -- [ ] Complete MINIX platform abstraction in D -- [ ] Port more repair operations to MINIX -- [ ] MINIX-specific test suite -- [ ] pkgsrc package for easy installation -- [ ] MINIX 4.x support when available - -## References - -- MINIX 3 Official: https://www.minix3.org/ -- pkgin Documentation: https://pkgin.net/ -- D Language on BSD: https://dlang.org/download.html#bsd -- GNAT on NetBSD: https://www.netbsd.org/docs/pkgsrc/ - -## Support - -For MINIX-specific issues: -- Check if feature exists on target platform -- Use D CLI instead of GUI for maximum compatibility -- Report MINIX bugs with `uname -a` output -- Test on MINIX 3.4.0+ (earlier versions untested) diff --git a/RSR-COMPLIANCE.adoc b/RSR-COMPLIANCE.adoc new file mode 100644 index 0000000..9f46bff --- /dev/null +++ b/RSR-COMPLIANCE.adoc @@ -0,0 +1,209 @@ +== RSR Compliance Assessment + +=== Current Compliance Level: *Bronze* → Targeting *Silver* + +==== ✅ Bronze Level Requirements (COMPLETE) + +[arabic] +. *Documentation* +* ✅ README.md - Comprehensive user guide +* ✅ LICENSE - MIT License +* ✅ Basic usage documentation +* ✅ Installation instructions +. *Build System* +* ✅ Installation script (install.sh) +* ✅ Executable wrapper (network-repair) +* ✅ Configuration system +. *Version Control* +* ✅ Git repository +* ✅ CHANGELOG.md +* ✅ Proper .gitignore +. *Testing* +* ✅ Test suite (tests/run-tests.sh) +* ✅ Unit tests (tests/test-utils.sh) +. *Community* +* ✅ CONTRIBUTING.md + +''''' + +==== 🔨 Silver Level Requirements (IN PROGRESS) + +[arabic] +. *Security* (0/4 complete) +* ❌ SECURITY.md - *ADDING* +* ❌ .well-known/security.txt (RFC 9116) - *ADDING* +* ❌ Vulnerability disclosure policy - *ADDING* +* ❌ Security audit documentation - *ADDING* +. *Community Governance* (1/3 complete) +* ✅ CONTRIBUTING.md +* ❌ CODE_OF_CONDUCT.md - *ADDING* +* ❌ MAINTAINERS.md - *ADDING* +. *Metadata* (0/3 complete) +* ❌ .well-known/humans.txt - *ADDING* +* ❌ .well-known/ai.txt - *ADDING* +* ❌ RSR compliance badge - *ADDING* +. *CI/CD* (2/3 complete) +* ✅ GitHub Actions workflows +* ✅ Automated testing +* ❌ 100% test pass rate verification - *IMPROVING* +. *Build Automation* (1/3 complete) +* ✅ Shell scripts +* ❌ Justfile for task running - *ADDING* +* ❌ Reproducible builds - *DOCUMENTING* +. *TPCF (Tri-Perimeter Contribution Framework)* (0/1 complete) +* ❌ TPCF.md documentation - *ADDING* + +''''' + +==== 🏆 Gold Level Requirements (ASPIRATIONAL) + +[arabic] +. *Type Safety* - N/A (Bash project, inherent limitation) +. *Memory Safety* - ✅ Shell scripting is memory-safe +. *Offline-First* - ✅ Core diagnostics work offline (only connectivity +tests require network) +. *Zero Dependencies* - ⚠️ Requires system tools (ip, ping, etc.) - +acceptable for system utility +. *Formal Verification* - N/A (Not applicable to Bash) +. *Multi-Language Support* - N/A (Single language appropriate for this +project) + +''''' + +=== RSR 11-Category Checklist + +==== 1. Documentation ✅ (90%) + +* ✅ README.md +* ✅ CONTRIBUTING.md +* ✅ CHANGELOG.md +* ✅ Architecture docs +* ✅ Troubleshooting guide +* ✅ Usage examples +* ❌ API documentation (N/A - CLI tool) + +==== 2. Security ❌ (25%) + +* ✅ Input sanitization +* ✅ Privilege checking +* ❌ SECURITY.md +* ❌ security.txt +* ❌ Vulnerability disclosure process + +==== 3. Build System ✅ (80%) + +* ✅ Installation script +* ✅ Uninstall support +* ✅ Dependency checking +* ❌ Justfile automation + +==== 4. Testing ✅ (70%) + +* ✅ Test suite +* ✅ Unit tests +* ✅ Syntax validation +* ❌ Integration tests +* ❌ Coverage reporting + +==== 5. Licensing ✅ (100%) + +* ✅ LICENSE file (MIT) +* ✅ Copyright notices +* ✅ Clear licensing terms + +==== 6. Community ⚠️ (50%) + +* ✅ CONTRIBUTING.md +* ❌ CODE_OF_CONDUCT.md +* ❌ MAINTAINERS.md +* ❌ Issue templates +* ❌ PR templates + +==== 7. Version Control ✅ (100%) + +* ✅ Git repository +* ✅ CHANGELOG.md +* ✅ Semantic versioning +* ✅ Tagged releases + +==== 8. Distribution ✅ (80%) + +* ✅ Installation script +* ✅ Release workflow +* ✅ Distribution packages (planned) +* ❌ Package repository integration + +==== 9. Accessibility ❌ (30%) + +* ✅ Terminal color detection +* ✅ No-color mode +* ❌ Screen reader compatibility docs +* ❌ Accessibility statement + +==== 10. Localization ❌ (10%) + +* ❌ i18n framework +* ❌ Language files +* ❌ Translation guide + +==== 11. Ethics ✅ (60%) + +* ✅ Open source license +* ✅ Inclusive language +* ❌ CODE_OF_CONDUCT.md +* ❌ Ethical AI policies (ai.txt) + +''''' + +=== Overall RSR Score: *Bronze (65%)* + +*Target: Silver (85%)* + +==== Priority Actions for Silver: + +[arabic] +. ✅ Add SECURITY.md +. ✅ Add CODE_OF_CONDUCT.md +. ✅ Add MAINTAINERS.md +. ✅ Create .well-known/ directory +. ✅ Add security.txt +. ✅ Add ai.txt +. ✅ Add humans.txt +. ✅ Add TPCF.md +. ✅ Add Justfile +. ✅ Enhance tests to 100% pass rate + +==== Timeline: + +* *Immediate*: Security and governance files (Items 1-8) +* *Next*: Build automation and testing (Items 9-10) +* *Future*: Accessibility, localization, package distribution + +''''' + +=== Implementation Plan + +==== Phase 1: Security & Governance (Today) + +* SECURITY.md with vulnerability disclosure policy +* CODE_OF_CONDUCT.md (Contributor Covenant 2.1) +* MAINTAINERS.md with project stewards +* .well-known/security.txt (RFC 9116 compliant) +* .well-known/ai.txt (AI training policies) +* .well-known/humans.txt (attribution) + +==== Phase 2: TPCF & Build Automation (Today) + +* TPCF.md (Tri-Perimeter Contribution Framework) +* Justfile with common tasks +* Enhanced test suite +* RSR compliance verification script + +==== Phase 3: Polish & Documentation (Today) + +* Update README with RSR badge +* Add accessibility documentation +* Add localization guide +* Update CI/CD for full verification + +*Expected Final Level: Silver (85-90% compliance)* diff --git a/RSR-COMPLIANCE.md b/RSR-COMPLIANCE.md deleted file mode 100644 index 9673088..0000000 --- a/RSR-COMPLIANCE.md +++ /dev/null @@ -1,195 +0,0 @@ -# RSR Compliance Assessment - -## Current Compliance Level: **Bronze** → Targeting **Silver** - -### ✅ Bronze Level Requirements (COMPLETE) - -1. **Documentation** - - ✅ README.md - Comprehensive user guide - - ✅ LICENSE - MIT License - - ✅ Basic usage documentation - - ✅ Installation instructions - -2. **Build System** - - ✅ Installation script (install.sh) - - ✅ Executable wrapper (network-repair) - - ✅ Configuration system - -3. **Version Control** - - ✅ Git repository - - ✅ CHANGELOG.md - - ✅ Proper .gitignore - -4. **Testing** - - ✅ Test suite (tests/run-tests.sh) - - ✅ Unit tests (tests/test-utils.sh) - -5. **Community** - - ✅ CONTRIBUTING.md - ---- - -### 🔨 Silver Level Requirements (IN PROGRESS) - -1. **Security** (0/4 complete) - - ❌ SECURITY.md - **ADDING** - - ❌ .well-known/security.txt (RFC 9116) - **ADDING** - - ❌ Vulnerability disclosure policy - **ADDING** - - ❌ Security audit documentation - **ADDING** - -2. **Community Governance** (1/3 complete) - - ✅ CONTRIBUTING.md - - ❌ CODE_OF_CONDUCT.md - **ADDING** - - ❌ MAINTAINERS.md - **ADDING** - -3. **Metadata** (0/3 complete) - - ❌ .well-known/humans.txt - **ADDING** - - ❌ .well-known/ai.txt - **ADDING** - - ❌ RSR compliance badge - **ADDING** - -4. **CI/CD** (2/3 complete) - - ✅ GitHub Actions workflows - - ✅ Automated testing - - ❌ 100% test pass rate verification - **IMPROVING** - -5. **Build Automation** (1/3 complete) - - ✅ Shell scripts - - ❌ Justfile for task running - **ADDING** - - ❌ Reproducible builds - **DOCUMENTING** - -6. **TPCF (Tri-Perimeter Contribution Framework)** (0/1 complete) - - ❌ TPCF.md documentation - **ADDING** - ---- - -### 🏆 Gold Level Requirements (ASPIRATIONAL) - -1. **Type Safety** - N/A (Bash project, inherent limitation) -2. **Memory Safety** - ✅ Shell scripting is memory-safe -3. **Offline-First** - ✅ Core diagnostics work offline (only connectivity tests require network) -4. **Zero Dependencies** - ⚠️ Requires system tools (ip, ping, etc.) - acceptable for system utility -5. **Formal Verification** - N/A (Not applicable to Bash) -6. **Multi-Language Support** - N/A (Single language appropriate for this project) - ---- - -## RSR 11-Category Checklist - -### 1. Documentation ✅ (90%) -- ✅ README.md -- ✅ CONTRIBUTING.md -- ✅ CHANGELOG.md -- ✅ Architecture docs -- ✅ Troubleshooting guide -- ✅ Usage examples -- ❌ API documentation (N/A - CLI tool) - -### 2. Security ❌ (25%) -- ✅ Input sanitization -- ✅ Privilege checking -- ❌ SECURITY.md -- ❌ security.txt -- ❌ Vulnerability disclosure process - -### 3. Build System ✅ (80%) -- ✅ Installation script -- ✅ Uninstall support -- ✅ Dependency checking -- ❌ Justfile automation - -### 4. Testing ✅ (70%) -- ✅ Test suite -- ✅ Unit tests -- ✅ Syntax validation -- ❌ Integration tests -- ❌ Coverage reporting - -### 5. Licensing ✅ (100%) -- ✅ LICENSE file (MIT) -- ✅ Copyright notices -- ✅ Clear licensing terms - -### 6. Community ⚠️ (50%) -- ✅ CONTRIBUTING.md -- ❌ CODE_OF_CONDUCT.md -- ❌ MAINTAINERS.md -- ❌ Issue templates -- ❌ PR templates - -### 7. Version Control ✅ (100%) -- ✅ Git repository -- ✅ CHANGELOG.md -- ✅ Semantic versioning -- ✅ Tagged releases - -### 8. Distribution ✅ (80%) -- ✅ Installation script -- ✅ Release workflow -- ✅ Distribution packages (planned) -- ❌ Package repository integration - -### 9. Accessibility ❌ (30%) -- ✅ Terminal color detection -- ✅ No-color mode -- ❌ Screen reader compatibility docs -- ❌ Accessibility statement - -### 10. Localization ❌ (10%) -- ❌ i18n framework -- ❌ Language files -- ❌ Translation guide - -### 11. Ethics ✅ (60%) -- ✅ Open source license -- ✅ Inclusive language -- ❌ CODE_OF_CONDUCT.md -- ❌ Ethical AI policies (ai.txt) - ---- - -## Overall RSR Score: **Bronze (65%)** - -**Target: Silver (85%)** - -### Priority Actions for Silver: -1. ✅ Add SECURITY.md -2. ✅ Add CODE_OF_CONDUCT.md -3. ✅ Add MAINTAINERS.md -4. ✅ Create .well-known/ directory -5. ✅ Add security.txt -6. ✅ Add ai.txt -7. ✅ Add humans.txt -8. ✅ Add TPCF.md -9. ✅ Add Justfile -10. ✅ Enhance tests to 100% pass rate - -### Timeline: -- **Immediate**: Security and governance files (Items 1-8) -- **Next**: Build automation and testing (Items 9-10) -- **Future**: Accessibility, localization, package distribution - ---- - -## Implementation Plan - -### Phase 1: Security & Governance (Today) -- SECURITY.md with vulnerability disclosure policy -- CODE_OF_CONDUCT.md (Contributor Covenant 2.1) -- MAINTAINERS.md with project stewards -- .well-known/security.txt (RFC 9116 compliant) -- .well-known/ai.txt (AI training policies) -- .well-known/humans.txt (attribution) - -### Phase 2: TPCF & Build Automation (Today) -- TPCF.md (Tri-Perimeter Contribution Framework) -- Justfile with common tasks -- Enhanced test suite -- RSR compliance verification script - -### Phase 3: Polish & Documentation (Today) -- Update README with RSR badge -- Add accessibility documentation -- Add localization guide -- Update CI/CD for full verification - -**Expected Final Level: Silver (85-90% compliance)** diff --git a/SECURITY.adoc b/SECURITY.adoc new file mode 100644 index 0000000..aefc3c7 --- /dev/null +++ b/SECURITY.adoc @@ -0,0 +1,301 @@ +== Security Policy + +=== Supported Versions + +We release patches for security vulnerabilities. Currently supported +versions: + +[cols=",",options="header",] +|=== +|Version |Supported +|1.0.x |:white_check_mark: +|< 1.0 |:x: +|=== + +=== Security Considerations + +==== This Tool Requires Root Privileges + +The Complete Linux Internet Repair Tool performs network configuration +changes that require root/sudo access. This is by design and necessary +for: + +* Modifying `+/etc/resolv.conf+` and other network configuration files +* Bringing network interfaces up/down +* Modifying routing tables +* Restarting system services (NetworkManager, systemd-resolved, etc.) +* Running privileged network commands (`+ip+`, `+iptables+`, etc.) + +==== Security Measures Implemented + +[arabic] +. *Privilege Checking* +* Explicit privilege checks before operations +* Clear user notification when sudo is required +* Sudo keep-alive only for duration of operations +* No unnecessary privilege escalation +. *Input Sanitization* +* All user inputs are sanitized to prevent command injection +* Interface names validated against system interfaces +* File paths validated before access +* No arbitrary command execution from user input +. *File Safety* +* Automatic backups before modifying configuration files +* Backups stored in user’s home directory +(`+~/.network-repair-backups/+`) +* File permission preservation +* Atomic file operations where possible +. *Code Safety* +* Bash strict mode (`+set -euo pipefail+`) where appropriate +* Proper error handling and validation +* No use of `+eval+` or dangerous constructs +* Shell script best practices followed +. *Transparency* +* Detailed logging of all operations +* Dry-run mode to preview changes +* Verbose mode for debugging +* Clear error messages + +=== Reporting a Vulnerability + +We take security seriously. If you discover a security vulnerability, +please follow responsible disclosure practices: + +==== Where to Report + +*DO NOT* open a public GitHub issue for security vulnerabilities. + +Instead, please report security issues via: + +[arabic] +. *Email*: security@[project-domain] (if project domain exists) +. *Private vulnerability report*: Use GitHub’s private vulnerability +reporting feature (if enabled) +. *Encrypted email*: PGP key available in `+.well-known/security.txt+` + +==== What to Include + +Please include: + +* *Description*: Clear description of the vulnerability +* *Impact*: Potential impact and attack scenarios +* *Reproduction*: Step-by-step instructions to reproduce +* *Affected versions*: Which versions are affected +* *Suggested fix*: If you have one (optional but helpful) +* *Your details*: How you’d like to be credited (optional) + +==== Example Report + +.... +Subject: [SECURITY] Command Injection in Interface Name Handling + +Description: +The interface name parameter in repair_interfaces() does not properly +sanitize input, allowing command injection via crafted interface names. + +Impact: +An attacker with local access could execute arbitrary commands with +root privileges by providing a malicious interface name. + +Reproduction: +1. Run: sudo ./network-repair repair-network "eth0; rm -rf /" +2. Observe arbitrary command execution + +Affected Versions: 1.0.0 and earlier + +Suggested Fix: +Add proper input validation in src/utils/system.sh:sanitize_input() +to only allow alphanumeric characters, dash, and underscore. +.... + +=== Response Timeline + +* *Acknowledgment*: Within 48 hours +* *Initial assessment*: Within 5 business days +* *Status updates*: Every 7 days until resolution +* *Fix timeline*: Critical issues within 7 days, others within 30 days +* *Public disclosure*: After fix is released and deployed + +=== Security Disclosure Process + +[arabic] +. *Report received* → We acknowledge receipt within 48 hours +. *Assessment* → We verify and assess severity (using CVSS v3.1) +. *Development* → We develop and test a fix +. *Private notification* → We notify affected users privately +. *Public release* → We release patched version +. *CVE assignment* → We request CVE if applicable +. *Public disclosure* → We publish security advisory (coordinated with +reporter) +. *Credit* → We credit reporter in CHANGELOG and security advisory + +=== Severity Levels + +We use CVSS v3.1 for severity assessment: + +* *Critical (9.0-10.0)*: Fix within 24-48 hours +* *High (7.0-8.9)*: Fix within 7 days +* *Medium (4.0-6.9)*: Fix within 30 days +* *Low (0.1-3.9)*: Fix in next regular release + +=== Security Best Practices for Users + +==== Before Running + +[arabic] +. *Verify integrity*: ++ +[source,bash] +---- +# Check SHA256 checksums if provided +sha256sum -c checksums.txt +---- +. *Review code*: ++ +[source,bash] +---- +# All code is open source - review before running with root +less src/main.sh +---- +. *Use dry-run mode first*: ++ +[source,bash] +---- +# Preview changes without making them +sudo ./network-repair --dry-run repair +---- + +==== During Use + +[arabic] +. *Understand what it does*: +* Read the documentation +* Use verbose mode to see what’s happening +* Check backups before and after +. *Limit exposure*: +* Don’t run on production systems without testing first +* Use virtual machines for testing +* Have a recovery plan +. *Monitor changes*: ++ +[source,bash] +---- +# Check what was backed up +ls -la ~/.network-repair-backups/ + +# View logs +tail -f /var/log/network-repair.log # if LOG_TO_FILE=true +---- + +==== After Use + +[arabic] +. *Verify system state*: ++ +[source,bash] +---- +# Check network is working +ping -c 3 google.com + +# Verify DNS +dig google.com + +# Check interfaces +ip addr show +---- +. *Review changes*: ++ +[source,bash] +---- +# Compare before/after +diff ~/.network-repair-backups/resolv.conf.20250122_143052 /etc/resolv.conf +---- + +=== Known Security Considerations + +==== By Design + +These are intentional design decisions, not vulnerabilities: + +[arabic] +. *Requires Root*: Many network operations require root privileges. This +is necessary and expected. +. *Modifies System Files*: The tool modifies `+/etc/resolv.conf+`, +routing tables, etc. This is its purpose. +. *Restarts Services*: May restart NetworkManager, systemd-resolved, +etc. Required for repairs to take effect. +. *No Authentication*: Local tool assumes user has physical/SSH access. +Not designed for remote/untrusted use. + +==== Out of Scope + +The following are out of scope for security reports: + +* Theoretical attacks requiring physical access to an +already-compromised system +* Social engineering attacks +* Attacks requiring user to intentionally run malicious code +* Issues in third-party tools we depend on (report to those projects) +* Denial of service via resource exhaustion (local tool, single-user) + +=== Security Changelog + +==== Version 1.0.0 (2025-01-22) + +* Initial release with security-focused design +* Input sanitization for all user-provided values +* Automatic backups before file modifications +* Privilege checking and safe elevation +* No use of dangerous bash constructs (eval, etc.) +* Dry-run mode for safe preview + +=== Security Tooling + +==== Static Analysis + +We welcome security-focused static analysis: + +[source,bash] +---- +# ShellCheck (for bash) +shellcheck src/**/*.sh + +# Syntax validation +find . -name "*.sh" -exec bash -n {} \; +---- + +==== Fuzzing + +If you want to fuzz-test the tool: + +[source,bash] +---- +# Example: Test with random interface names +for i in {1..1000}; do + random_input=$(head -c 20 /dev/urandom | base64 | tr -d '+/=') + echo "Testing: $random_input" + ./network-repair diagnose-network "$random_input" 2>&1 | grep -i "error\|crash\|segfault" || true +done +---- + +=== Security Contacts + +* *Security Email*: security@[project-domain] +* *Security.txt*: `+.well-known/security.txt+` (RFC 9116) +* *PGP Key*: See `+.well-known/security.txt+` for current key + +=== Hall of Fame + +We maintain a security hall of fame to thank researchers who help +improve security: + +_No vulnerabilities reported yet. Be the first!_ + +=== License + +This security policy is licensed under CC0 1.0 Universal (Public +Domain). + +''''' + +*Last Updated*: 2025-01-22 *Version*: 1.0.0 diff --git a/SECURITY.md b/SECURITY.md deleted file mode 100644 index 5eaa316..0000000 --- a/SECURITY.md +++ /dev/null @@ -1,277 +0,0 @@ -# Security Policy - -## Supported Versions - -We release patches for security vulnerabilities. Currently supported versions: - -| Version | Supported | -| ------- | ------------------ | -| 1.0.x | :white_check_mark: | -| < 1.0 | :x: | - -## Security Considerations - -### This Tool Requires Root Privileges - -The Complete Linux Internet Repair Tool performs network configuration changes that require root/sudo access. This is by design and necessary for: - -- Modifying `/etc/resolv.conf` and other network configuration files -- Bringing network interfaces up/down -- Modifying routing tables -- Restarting system services (NetworkManager, systemd-resolved, etc.) -- Running privileged network commands (`ip`, `iptables`, etc.) - -### Security Measures Implemented - -1. **Privilege Checking** - - Explicit privilege checks before operations - - Clear user notification when sudo is required - - Sudo keep-alive only for duration of operations - - No unnecessary privilege escalation - -2. **Input Sanitization** - - All user inputs are sanitized to prevent command injection - - Interface names validated against system interfaces - - File paths validated before access - - No arbitrary command execution from user input - -3. **File Safety** - - Automatic backups before modifying configuration files - - Backups stored in user's home directory (`~/.network-repair-backups/`) - - File permission preservation - - Atomic file operations where possible - -4. **Code Safety** - - Bash strict mode (`set -euo pipefail`) where appropriate - - Proper error handling and validation - - No use of `eval` or dangerous constructs - - Shell script best practices followed - -5. **Transparency** - - Detailed logging of all operations - - Dry-run mode to preview changes - - Verbose mode for debugging - - Clear error messages - -## Reporting a Vulnerability - -We take security seriously. If you discover a security vulnerability, please follow responsible disclosure practices: - -### Where to Report - -**DO NOT** open a public GitHub issue for security vulnerabilities. - -Instead, please report security issues via: - -1. **Email**: security@[project-domain] (if project domain exists) -2. **Private vulnerability report**: Use GitHub's private vulnerability reporting feature (if enabled) -3. **Encrypted email**: PGP key available in `.well-known/security.txt` - -### What to Include - -Please include: - -- **Description**: Clear description of the vulnerability -- **Impact**: Potential impact and attack scenarios -- **Reproduction**: Step-by-step instructions to reproduce -- **Affected versions**: Which versions are affected -- **Suggested fix**: If you have one (optional but helpful) -- **Your details**: How you'd like to be credited (optional) - -### Example Report - -``` -Subject: [SECURITY] Command Injection in Interface Name Handling - -Description: -The interface name parameter in repair_interfaces() does not properly -sanitize input, allowing command injection via crafted interface names. - -Impact: -An attacker with local access could execute arbitrary commands with -root privileges by providing a malicious interface name. - -Reproduction: -1. Run: sudo ./network-repair repair-network "eth0; rm -rf /" -2. Observe arbitrary command execution - -Affected Versions: 1.0.0 and earlier - -Suggested Fix: -Add proper input validation in src/utils/system.sh:sanitize_input() -to only allow alphanumeric characters, dash, and underscore. -``` - -## Response Timeline - -- **Acknowledgment**: Within 48 hours -- **Initial assessment**: Within 5 business days -- **Status updates**: Every 7 days until resolution -- **Fix timeline**: Critical issues within 7 days, others within 30 days -- **Public disclosure**: After fix is released and deployed - -## Security Disclosure Process - -1. **Report received** → We acknowledge receipt within 48 hours -2. **Assessment** → We verify and assess severity (using CVSS v3.1) -3. **Development** → We develop and test a fix -4. **Private notification** → We notify affected users privately -5. **Public release** → We release patched version -6. **CVE assignment** → We request CVE if applicable -7. **Public disclosure** → We publish security advisory (coordinated with reporter) -8. **Credit** → We credit reporter in CHANGELOG and security advisory - -## Severity Levels - -We use CVSS v3.1 for severity assessment: - -- **Critical (9.0-10.0)**: Fix within 24-48 hours -- **High (7.0-8.9)**: Fix within 7 days -- **Medium (4.0-6.9)**: Fix within 30 days -- **Low (0.1-3.9)**: Fix in next regular release - -## Security Best Practices for Users - -### Before Running - -1. **Verify integrity**: - ```bash - # Check SHA256 checksums if provided - sha256sum -c checksums.txt - ``` - -2. **Review code**: - ```bash - # All code is open source - review before running with root - less src/main.sh - ``` - -3. **Use dry-run mode first**: - ```bash - # Preview changes without making them - sudo ./network-repair --dry-run repair - ``` - -### During Use - -1. **Understand what it does**: - - Read the documentation - - Use verbose mode to see what's happening - - Check backups before and after - -2. **Limit exposure**: - - Don't run on production systems without testing first - - Use virtual machines for testing - - Have a recovery plan - -3. **Monitor changes**: - ```bash - # Check what was backed up - ls -la ~/.network-repair-backups/ - - # View logs - tail -f /var/log/network-repair.log # if LOG_TO_FILE=true - ``` - -### After Use - -1. **Verify system state**: - ```bash - # Check network is working - ping -c 3 google.com - - # Verify DNS - dig google.com - - # Check interfaces - ip addr show - ``` - -2. **Review changes**: - ```bash - # Compare before/after - diff ~/.network-repair-backups/resolv.conf.20250122_143052 /etc/resolv.conf - ``` - -## Known Security Considerations - -### By Design - -These are intentional design decisions, not vulnerabilities: - -1. **Requires Root**: Many network operations require root privileges. This is necessary and expected. - -2. **Modifies System Files**: The tool modifies `/etc/resolv.conf`, routing tables, etc. This is its purpose. - -3. **Restarts Services**: May restart NetworkManager, systemd-resolved, etc. Required for repairs to take effect. - -4. **No Authentication**: Local tool assumes user has physical/SSH access. Not designed for remote/untrusted use. - -### Out of Scope - -The following are out of scope for security reports: - -- Theoretical attacks requiring physical access to an already-compromised system -- Social engineering attacks -- Attacks requiring user to intentionally run malicious code -- Issues in third-party tools we depend on (report to those projects) -- Denial of service via resource exhaustion (local tool, single-user) - -## Security Changelog - -### Version 1.0.0 (2025-01-22) - -- Initial release with security-focused design -- Input sanitization for all user-provided values -- Automatic backups before file modifications -- Privilege checking and safe elevation -- No use of dangerous bash constructs (eval, etc.) -- Dry-run mode for safe preview - -## Security Tooling - -### Static Analysis - -We welcome security-focused static analysis: - -```bash -# ShellCheck (for bash) -shellcheck src/**/*.sh - -# Syntax validation -find . -name "*.sh" -exec bash -n {} \; -``` - -### Fuzzing - -If you want to fuzz-test the tool: - -```bash -# Example: Test with random interface names -for i in {1..1000}; do - random_input=$(head -c 20 /dev/urandom | base64 | tr -d '+/=') - echo "Testing: $random_input" - ./network-repair diagnose-network "$random_input" 2>&1 | grep -i "error\|crash\|segfault" || true -done -``` - -## Security Contacts - -- **Security Email**: security@[project-domain] -- **Security.txt**: `.well-known/security.txt` (RFC 9116) -- **PGP Key**: See `.well-known/security.txt` for current key - -## Hall of Fame - -We maintain a security hall of fame to thank researchers who help improve security: - -*No vulnerabilities reported yet. Be the first!* - -## License - -This security policy is licensed under CC0 1.0 Universal (Public Domain). - ---- - -**Last Updated**: 2025-01-22 -**Version**: 1.0.0 diff --git a/TPCF.adoc b/TPCF.adoc new file mode 100644 index 0000000..43f4b28 --- /dev/null +++ b/TPCF.adoc @@ -0,0 +1,304 @@ +== TPCF: Tri-Perimeter Contribution Framework + +=== Overview + +The Complete Linux Internet Repair Tool uses the *Tri-Perimeter +Contribution Framework (TPCF)* for graduated trust and contribution +management. TPCF recognizes that not all contributions carry equal risk, +and contributors earn trust over time through demonstrated competence +and community alignment. + +=== The Three Perimeters + +.... +┌─────────────────────────────────────────────────────────┐ +│ PERIMETER 1 │ +│ Maintainer Core │ +│ (Highest Trust, Full Access) │ +│ │ +│ ┌───────────────────────────────────────────────────┐ │ +│ │ PERIMETER 2 │ │ +│ │ Trusted Contributors │ │ +│ │ (Elevated Trust, Expanded Access) │ │ +│ │ │ │ +│ │ ┌─────────────────────────────────────────────┐ │ │ +│ │ │ PERIMETER 3 │ │ │ +│ │ │ Community Sandbox │ │ │ +│ │ │ (Open Access, Protected Environment) │ │ │ +│ │ │ │ │ │ +│ │ │ All Contributors Start Here! │ │ │ +│ │ │ │ │ │ +│ │ └─────────────────────────────────────────────┘ │ │ +│ └───────────────────────────────────────────────────┘ │ +└─────────────────────────────────────────────────────────┘ +.... + +=== Perimeter 3: Community Sandbox + +*Who*: All new contributors, anyone can join *Trust Level*: Public trust +(assume good intent, verify actions) *Access*: Full read, pull requests +for write + +==== What You Can Do + +* ✅ Fork the repository +* ✅ Submit pull requests (docs, code, tests) +* ✅ Open issues and feature requests +* ✅ Comment on issues and PRs +* ✅ Participate in discussions +* ✅ Run and test the tool +* ✅ Report bugs and security issues +* ✅ Improve documentation +* ✅ Add examples and tutorials +* ✅ Translate documentation (i18n/l10n) + +==== What Happens to Your Contributions + +[arabic] +. *Automatic*: CI/CD runs tests on your PR +. *Review*: Perimeter 2/1 contributors review +. *Feedback*: Get constructive feedback +. *Iteration*: Make requested changes +. *Approval*: At least one P2/P1 approval required +. *Merge*: P1 maintainer merges after approvals + +==== Safety Mechanisms + +* PRs cannot be merged without approval +* Automated tests must pass +* Code review by trusted contributors +* Reversible changes (git revert available) +* No direct access to main branch +* Security scans on all PRs + +==== Progression to Perimeter 2 + +Demonstrated through: - *Quality*: 10+ meaningful contributions - +*Consistency*: 3+ months of participation - *Community*: Positive +interactions, CoC alignment - *Technical*: Understanding of codebase +architecture - *Trust*: Pattern of helpful, correct contributions + +=== Perimeter 2: Trusted Contributors + +*Who*: Contributors with demonstrated competence and trust *Trust +Level*: Elevated trust (trusted but verified) *Access*: Review/approve +PRs, issue triage, some commit access + +==== What You Can Do (In Addition to P3) + +* ✅ Review and approve pull requests +* ✅ Triage and label issues +* ✅ Close duplicate/invalid issues +* ✅ Mentor new contributors (P3) +* ✅ Participate in roadmap discussions +* ✅ Make non-breaking changes with review +* ✅ Update documentation directly +* ✅ Manage project boards +* ✅ Run release candidates testing + +==== Responsibilities + +* Code review for quality, security, style +* Mentoring P3 contributors +* Upholding Code of Conduct +* Testing pre-release versions +* Documentation maintenance +* Community engagement + +==== Limitations + +* Cannot merge own PRs (requires P1) +* Cannot make breaking changes alone +* Cannot modify security-critical code without P1 +* Cannot publish releases +* Cannot change repository settings + +==== Progression to Perimeter 1 + +Demonstrated through: - *Expertise*: Deep knowledge of entire codebase - +*Leadership*: Mentoring others, driving features - *Reliability*: 12+ +months of consistent contribution - *Security*: Understanding of +security implications - *Community*: Positive force in community health +- *Judgment*: Sound technical decision-making - *Nomination*: Unanimous +vote by existing P1 members + +=== Perimeter 1: Maintainer Core + +*Who*: Core maintainers with full authority *Trust Level*: Full trust +(trusted, verified, accountable) *Access*: Full commit access, release +authority, security + +==== What You Can Do (In Addition to P2) + +* ✅ Merge pull requests to main +* ✅ Create and publish releases +* ✅ Respond to security reports +* ✅ Modify repository settings +* ✅ Add/remove collaborators +* ✅ Make breaking changes (with consensus) +* ✅ Final decision authority on contentious issues +* ✅ Enforce Code of Conduct +* ✅ Manage secrets and credentials + +==== Responsibilities + +* Project vision and direction +* Release management +* Security incident response +* Final code review and approval +* Community health and CoC enforcement +* Maintainer meetings and coordination +* Sustainable project stewardship + +==== Accountability + +* Transparent decision-making +* Regular communication with community +* Following project governance +* Leading by example +* Mentoring P2 and P3 contributors +* Managing conflicts of interest + +=== TPCF Benefits + +==== For Contributors + +[arabic] +. *Clear Path*: Know what’s needed to progress +. *Safety*: Experiment freely in P3 sandbox +. *Recognition*: Formal recognition of trust +. *Growth*: Develop skills through mentorship +. *Ownership*: Earn real responsibility + +==== For Maintainers + +[arabic] +. *Risk Management*: Graduated access = reduced risk +. *Sustainability*: Grow maintainer pool over time +. *Quality*: Multiple review layers ensure quality +. *Community*: Healthy pipeline of contributors +. *Transparency*: Clear roles and expectations + +==== For the Project + +[arabic] +. *Security*: Defense in depth through layers +. *Velocity*: More trusted reviewers = faster merges +. *Resilience*: Bus factor > 1 through P1 growth +. *Quality*: Peer review at every level +. *Inclusivity*: Clear, fair path for all + +=== Examples + +==== P3 Contribution Flow + +.... +1. Fork repository +2. Create feature branch +3. Make changes (add dry-run mode flag) +4. Run tests locally: ./tests/run-tests.sh +5. Push and open PR +6. CI runs tests automatically +7. P2 reviewer provides feedback +8. Address feedback, push changes +9. P2 approves PR +10. P1 maintainer merges +.... + +==== P2 Contribution Flow + +.... +1. Create feature branch in main repo +2. Make changes (refactor logging) +3. Self-review first +4. Open PR, tag P1 for review +5. P1 reviews, approves +6. P1 merges (or P2 merges after approval) +7. Monitor for issues +.... + +==== P1 Contribution Flow + +.... +1. Create feature branch or commit directly +2. Make changes (security fix) +3. Review own code carefully +4. Merge to main (if urgent) or PR for non-urgent +5. Tag and release if needed +6. Announce to community +7. Monitor for issues +.... + +=== Special Cases + +==== Security Issues + +* P3: Report via SECURITY.md, do not publicize +* P2: May be consulted on fixes, under NDA +* P1: Full access to reports, coordinate response + +==== Breaking Changes + +* P3: Propose in issue first, get buy-in +* P2: Discuss with P1, requires approval +* P1: Can approve, but seek consensus + +==== Documentation + +* P3: PR for any docs +* P2: Can commit directly to docs/ +* P1: Can commit anywhere + +==== Tests + +* P3: Add tests with code +* P2: Can improve test infrastructure +* P1: Can modify test framework + +=== TPCF and Code of Conduct + +TPCF enforcement of Code of Conduct: + +* *P3 violations*: Warning → temporary ban → permanent ban +* *P2 violations*: Same, but may lose P2 status +* *P1 violations*: Same, plus immediate P1 revocation + +Trust is earned, and can be lost. We prioritize community health over +individual contributor access at all levels. + +=== TPCF Evolution + +This TPCF policy can be amended by: + +[arabic] +. Proposal by any contributor (issue/PR) +. Discussion period (minimum 2 weeks) +. P1 vote (supermajority 2/3+ required) +. Update this document +. Announce to community + +=== Current Status + +*Perimeter 1 Maintainers*: 1 (founding maintainer) *Perimeter 2 +Contributors*: 0 (new project) *Perimeter 3 Contributors*: All are +welcome! + +=== Join Us! + +We’re actively looking for contributors at all levels. Start in +Perimeter 3 today by: + +[arabic] +. Opening an issue with questions or ideas +. Improving documentation +. Adding tests +. Fixing bugs +. Adding features + +See CONTRIBUTING.md for detailed contribution guide. + +''''' + +*TPCF Version*: 1.0 *Last Updated*: 2025-01-22 *Governance*: See +MAINTAINERS.md *Related*: CODE_OF_CONDUCT.md, CONTRIBUTING.md, +SECURITY.md diff --git a/TPCF.md b/TPCF.md deleted file mode 100644 index 87b509c..0000000 --- a/TPCF.md +++ /dev/null @@ -1,299 +0,0 @@ -# TPCF: Tri-Perimeter Contribution Framework - -## Overview - -The Complete Linux Internet Repair Tool uses the **Tri-Perimeter Contribution Framework (TPCF)** for graduated trust and contribution management. TPCF recognizes that not all contributions carry equal risk, and contributors earn trust over time through demonstrated competence and community alignment. - -## The Three Perimeters - -``` -┌─────────────────────────────────────────────────────────┐ -│ PERIMETER 1 │ -│ Maintainer Core │ -│ (Highest Trust, Full Access) │ -│ │ -│ ┌───────────────────────────────────────────────────┐ │ -│ │ PERIMETER 2 │ │ -│ │ Trusted Contributors │ │ -│ │ (Elevated Trust, Expanded Access) │ │ -│ │ │ │ -│ │ ┌─────────────────────────────────────────────┐ │ │ -│ │ │ PERIMETER 3 │ │ │ -│ │ │ Community Sandbox │ │ │ -│ │ │ (Open Access, Protected Environment) │ │ │ -│ │ │ │ │ │ -│ │ │ All Contributors Start Here! │ │ │ -│ │ │ │ │ │ -│ │ └─────────────────────────────────────────────┘ │ │ -│ └───────────────────────────────────────────────────┘ │ -└─────────────────────────────────────────────────────────┘ -``` - -## Perimeter 3: Community Sandbox - -**Who**: All new contributors, anyone can join -**Trust Level**: Public trust (assume good intent, verify actions) -**Access**: Full read, pull requests for write - -### What You Can Do - -- ✅ Fork the repository -- ✅ Submit pull requests (docs, code, tests) -- ✅ Open issues and feature requests -- ✅ Comment on issues and PRs -- ✅ Participate in discussions -- ✅ Run and test the tool -- ✅ Report bugs and security issues -- ✅ Improve documentation -- ✅ Add examples and tutorials -- ✅ Translate documentation (i18n/l10n) - -### What Happens to Your Contributions - -1. **Automatic**: CI/CD runs tests on your PR -2. **Review**: Perimeter 2/1 contributors review -3. **Feedback**: Get constructive feedback -4. **Iteration**: Make requested changes -5. **Approval**: At least one P2/P1 approval required -6. **Merge**: P1 maintainer merges after approvals - -### Safety Mechanisms - -- PRs cannot be merged without approval -- Automated tests must pass -- Code review by trusted contributors -- Reversible changes (git revert available) -- No direct access to main branch -- Security scans on all PRs - -### Progression to Perimeter 2 - -Demonstrated through: -- **Quality**: 10+ meaningful contributions -- **Consistency**: 3+ months of participation -- **Community**: Positive interactions, CoC alignment -- **Technical**: Understanding of codebase architecture -- **Trust**: Pattern of helpful, correct contributions - -## Perimeter 2: Trusted Contributors - -**Who**: Contributors with demonstrated competence and trust -**Trust Level**: Elevated trust (trusted but verified) -**Access**: Review/approve PRs, issue triage, some commit access - -### What You Can Do (In Addition to P3) - -- ✅ Review and approve pull requests -- ✅ Triage and label issues -- ✅ Close duplicate/invalid issues -- ✅ Mentor new contributors (P3) -- ✅ Participate in roadmap discussions -- ✅ Make non-breaking changes with review -- ✅ Update documentation directly -- ✅ Manage project boards -- ✅ Run release candidates testing - -### Responsibilities - -- Code review for quality, security, style -- Mentoring P3 contributors -- Upholding Code of Conduct -- Testing pre-release versions -- Documentation maintenance -- Community engagement - -### Limitations - -- Cannot merge own PRs (requires P1) -- Cannot make breaking changes alone -- Cannot modify security-critical code without P1 -- Cannot publish releases -- Cannot change repository settings - -### Progression to Perimeter 1 - -Demonstrated through: -- **Expertise**: Deep knowledge of entire codebase -- **Leadership**: Mentoring others, driving features -- **Reliability**: 12+ months of consistent contribution -- **Security**: Understanding of security implications -- **Community**: Positive force in community health -- **Judgment**: Sound technical decision-making -- **Nomination**: Unanimous vote by existing P1 members - -## Perimeter 1: Maintainer Core - -**Who**: Core maintainers with full authority -**Trust Level**: Full trust (trusted, verified, accountable) -**Access**: Full commit access, release authority, security - -### What You Can Do (In Addition to P2) - -- ✅ Merge pull requests to main -- ✅ Create and publish releases -- ✅ Respond to security reports -- ✅ Modify repository settings -- ✅ Add/remove collaborators -- ✅ Make breaking changes (with consensus) -- ✅ Final decision authority on contentious issues -- ✅ Enforce Code of Conduct -- ✅ Manage secrets and credentials - -### Responsibilities - -- Project vision and direction -- Release management -- Security incident response -- Final code review and approval -- Community health and CoC enforcement -- Maintainer meetings and coordination -- Sustainable project stewardship - -### Accountability - -- Transparent decision-making -- Regular communication with community -- Following project governance -- Leading by example -- Mentoring P2 and P3 contributors -- Managing conflicts of interest - -## TPCF Benefits - -### For Contributors - -1. **Clear Path**: Know what's needed to progress -2. **Safety**: Experiment freely in P3 sandbox -3. **Recognition**: Formal recognition of trust -4. **Growth**: Develop skills through mentorship -5. **Ownership**: Earn real responsibility - -### For Maintainers - -1. **Risk Management**: Graduated access = reduced risk -2. **Sustainability**: Grow maintainer pool over time -3. **Quality**: Multiple review layers ensure quality -4. **Community**: Healthy pipeline of contributors -5. **Transparency**: Clear roles and expectations - -### For the Project - -1. **Security**: Defense in depth through layers -2. **Velocity**: More trusted reviewers = faster merges -3. **Resilience**: Bus factor > 1 through P1 growth -4. **Quality**: Peer review at every level -5. **Inclusivity**: Clear, fair path for all - -## Examples - -### P3 Contribution Flow - -``` -1. Fork repository -2. Create feature branch -3. Make changes (add dry-run mode flag) -4. Run tests locally: ./tests/run-tests.sh -5. Push and open PR -6. CI runs tests automatically -7. P2 reviewer provides feedback -8. Address feedback, push changes -9. P2 approves PR -10. P1 maintainer merges -``` - -### P2 Contribution Flow - -``` -1. Create feature branch in main repo -2. Make changes (refactor logging) -3. Self-review first -4. Open PR, tag P1 for review -5. P1 reviews, approves -6. P1 merges (or P2 merges after approval) -7. Monitor for issues -``` - -### P1 Contribution Flow - -``` -1. Create feature branch or commit directly -2. Make changes (security fix) -3. Review own code carefully -4. Merge to main (if urgent) or PR for non-urgent -5. Tag and release if needed -6. Announce to community -7. Monitor for issues -``` - -## Special Cases - -### Security Issues - -- P3: Report via SECURITY.md, do not publicize -- P2: May be consulted on fixes, under NDA -- P1: Full access to reports, coordinate response - -### Breaking Changes - -- P3: Propose in issue first, get buy-in -- P2: Discuss with P1, requires approval -- P1: Can approve, but seek consensus - -### Documentation - -- P3: PR for any docs -- P2: Can commit directly to docs/ -- P1: Can commit anywhere - -### Tests - -- P3: Add tests with code -- P2: Can improve test infrastructure -- P1: Can modify test framework - -## TPCF and Code of Conduct - -TPCF enforcement of Code of Conduct: - -- **P3 violations**: Warning → temporary ban → permanent ban -- **P2 violations**: Same, but may lose P2 status -- **P1 violations**: Same, plus immediate P1 revocation - -Trust is earned, and can be lost. We prioritize community health over -individual contributor access at all levels. - -## TPCF Evolution - -This TPCF policy can be amended by: - -1. Proposal by any contributor (issue/PR) -2. Discussion period (minimum 2 weeks) -3. P1 vote (supermajority 2/3+ required) -4. Update this document -5. Announce to community - -## Current Status - -**Perimeter 1 Maintainers**: 1 (founding maintainer) -**Perimeter 2 Contributors**: 0 (new project) -**Perimeter 3 Contributors**: All are welcome! - -## Join Us! - -We're actively looking for contributors at all levels. Start in Perimeter 3 -today by: - -1. Opening an issue with questions or ideas -2. Improving documentation -3. Adding tests -4. Fixing bugs -5. Adding features - -See CONTRIBUTING.md for detailed contribution guide. - ---- - -**TPCF Version**: 1.0 -**Last Updated**: 2025-01-22 -**Governance**: See MAINTAINERS.md -**Related**: CODE_OF_CONDUCT.md, CONTRIBUTING.md, SECURITY.md diff --git a/docs/ACCESSIBILITY.adoc b/docs/ACCESSIBILITY.adoc new file mode 100644 index 0000000..3e66c56 --- /dev/null +++ b/docs/ACCESSIBILITY.adoc @@ -0,0 +1,338 @@ +== Accessibility + +=== Commitment to Accessibility + +The Complete Linux Internet Repair Tool is committed to being accessible +to all users, including those with disabilities. As a command-line tool, +we follow terminal accessibility best practices. + +=== Current Accessibility Features + +==== Color and Visual + +[arabic] +. *Color Detection* +* Automatic detection of terminal color capabilities +* Graceful degradation when colors not supported +* `+--no-color+` flag to disable all color output +. *High Contrast* +* Careful selection of ANSI colors for readability +* Green (success), Yellow (warning), Red (error), Blue (info) +* Works with both light and dark terminal backgrounds +. *Screen Reader Compatible* +* Plain text output that screen readers can parse +* No ASCII art or complex formatting +* Structured output with clear headers and sections + +==== Output Clarity + +[arabic] +. *Clear Status Indicators* +* ✅ (success), ⚠️ (warning), ❌ (error), → (action) +* Text equivalents: [✓], [WARN], [ERROR], [INFO] +* Both visual and textual indicators provided +. *Verbose Mode* +* `+--verbose+` flag for detailed output +* Explains what the tool is doing at each step +* Helpful for users who need more context +. *Quiet Mode* +* `+--quiet+` flag for minimal output +* Only errors are shown +* Reduces cognitive load + +==== Interactive Mode + +[arabic] +. *Keyboard-Only Navigation* +* Menu-driven interface +* Number keys for selection +* No mouse required +. *Clear Prompts* +* Unambiguous question text +* Default options indicated +* Confirmation for destructive actions +. *Timeout-Free* +* No time limits on user input +* Users can take their time reading options +* Pauses wait indefinitely for user response + +=== Accessibility Guidelines Followed + +==== WCAG 2.1 Principles (Adapted for CLI) + +[arabic] +. *Perceivable* +* ✅ Text alternatives for visual indicators +* ✅ Color is not the only means of conveying information +* ✅ Content can be presented in different ways +. *Operable* +* ✅ All functionality available from keyboard +* ✅ No timing constraints on user input +* ✅ Clear navigation through menus +. *Understandable* +* ✅ Readable error messages +* ✅ Predictable operation +* ✅ Input assistance (hints and examples) +. *Robust* +* ✅ Works with standard terminal emulators +* ✅ Compatible with screen readers (orca, NVDA via SSH) +* ✅ POSIX-compliant where possible + +=== Screen Reader Support + +==== Tested With + +* *Orca* (Linux): Works with terminal output +* *NVDA* (Windows via WSL): Compatible +* *VoiceOver* (macOS): Compatible with Terminal.app + +==== Best Practices for Screen Reader Users + +[source,bash] +---- +# Use verbose mode for more context +network-repair --verbose diagnose + +# Disable colors for cleaner screen reader output +network-repair --no-color diagnose + +# Save output to file for review +network-repair diagnose > /tmp/diag.txt 2>&1 +less /tmp/diag.txt +---- + +=== Visual Impairment Considerations + +==== Low Vision + +[arabic] +. *Large Text Terminals* +* Tool respects terminal font size settings +* No fixed-width assumptions +* Works with zoomed terminals +. *High Contrast Themes* +* Works with high-contrast terminal themes +* ANSI colors adapt to theme +* No hardcoded color codes + +==== Color Blindness + +[arabic] +. *Not Relying on Color Alone* +* Status indicated by text symbols: ✓, ✗, ⚠ +* Text labels: [INFO], [WARN], [ERROR], [SUCCESS] +* Position and structure convey meaning +. *Protanopia/Deuteranopia (Red-Green)* +* Errors use text labels, not just red color +* Success uses text labels, not just green color +* Icons supplement color +. *Tritanopia (Blue-Yellow)* +* Info messages use text labels +* Warnings use text labels + +=== Cognitive Accessibility + +==== Clear Language + +[arabic] +. *Plain Language* +* Avoid jargon where possible +* Explain technical terms when used +* Short, clear sentences +. *Consistent Terminology* +* Same terms for same concepts +* No synonyms for technical terms +* Glossary in documentation +. *Progressive Disclosure* +* Basic mode: Simple output +* Verbose mode: Detailed explanation +* Help text available at any time + +==== Error Messages + +[arabic] +. *Actionable Errors* +* What went wrong +* Why it happened +* How to fix it + +Example: + +.... +❌ [ERROR] No default route found! + This means your computer doesn't know how to reach the internet. + Run: sudo network-repair repair-routing +.... + +==== Predictable Behavior + +[arabic] +. *Dry-Run Mode* +* Preview changes before applying +* Reduces anxiety about mistakes +* `+--dry-run+` flag available +. *Reversibility* +* All changes are backed up +* Backups stored in `+~/.network-repair-backups/+` +* Easy to undo mistakes + +=== Physical Accessibility + +==== Motor Impairments + +[arabic] +. *Minimal Typing* +* Single-letter menu choices (y/n, 1-6) +* Tab completion for file paths +* Default options reduce typing +. *Error Tolerance* +* Forgiving input parsing +* Clear error messages for invalid input +* No case sensitivity for y/n prompts +. *Alternative Input Methods* +* Works with voice input (Dragon, speech recognition) +* Compatible with adaptive keyboards +* No mouse required + +=== Auditory Accessibility + +==== No Audio Requirements + +* All information presented visually as text +* No audio cues or warnings +* No sound effects +* Silent operation + +=== Language and Localization + +==== Current Status + +* *Primary Language*: English (US) +* *Future Plans*: i18n support (see docs/I18N.md) + +==== Clear English + +* Simple vocabulary +* Short sentences +* Active voice preferred +* Technical terms explained + +=== Testing + +==== Accessibility Testing Checklist + +* [ ] Works with `+--no-color+` flag +* [ ] Output readable with screen reader +* [ ] Menu navigation keyboard-only +* [ ] No time limits on input +* [ ] Error messages actionable +* [ ] Works in high-contrast mode +* [ ] Tab completion functional +* [ ] Help text comprehensive + +==== Test Commands + +[source,bash] +---- +# Test without colors +network-repair --no-color diagnose + +# Test with screen reader +orca & +network-repair diagnose + +# Test verbose output +network-repair --verbose diagnose | less + +# Test interactive mode +sudo network-repair interactive +---- + +=== Known Limitations + +[arabic] +. *Terminal-Only* +* No GUI alternative (planned for future) +* Requires terminal emulator +* Command-line knowledge helpful +. *English-Only* +* Currently only English (US) +* i18n planned for future versions +* See docs/I18N.md for roadmap +. *Root Required for Repairs* +* Many operations need sudo/root +* Diagnostics work without root +* Clear prompts when sudo needed + +=== Reporting Accessibility Issues + +If you encounter accessibility barriers: + +[arabic] +. *Open an Issue* +* Tag with `+accessibility+` label +* Describe the barrier +* Include your setup (OS, terminal, assistive tech) +. *Suggest Improvements* +* We welcome accessibility enhancement PRs +* See CONTRIBUTING.md +* Ask questions first +. *Contact* +* Email: accessibility@example.com +* GitHub: Open issue with link:#accessibility[ACCESSIBILITY] tag + +=== Accessibility Roadmap + +==== Short Term (v1.1) + +* [ ] Improve screen reader testing +* [ ] Add more text-only output options +* [ ] Enhanced `+--no-color+` mode +* [ ] Accessibility testing in CI + +==== Medium Term (v1.2-1.3) + +* [ ] i18n support (see I18N.md) +* [ ] GUI mode (Electron or web-based) +* [ ] Better error message formatting +* [ ] Audio output option (TTS) + +==== Long Term (v2.0+) + +* [ ] Full WCAG 2.1 AA compliance audit +* [ ] Multiple UI modes (CLI, TUI, GUI) +* [ ] Braille display support +* [ ] Switch access support + +=== Resources + +==== Standards + +* https://www.w3.org/WAI/WCAG21/quickref/[WCAG 2.1] +* https://www.section508.gov/[Section 508] +* https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf[EN +301 549] + +==== Tools + +* https://pa11y.org/[Pa11y] - Accessibility testing +* https://www.deque.com/axe/[axe DevTools] - Accessibility checker +* https://www.nvaccess.org/[NVDA] - Windows screen reader +* https://help.gnome.org/users/orca/stable/[Orca] - Linux screen reader + +==== Community + +* https://www.a11yproject.com/[A11y Project] +* https://webaim.org/[WebAIM] +* https://inclusivedesignprinciples.org/[Inclusive Design Principles] + +=== Acknowledgments + +We thank the accessibility community for ongoing guidance and feedback. +Special thanks to users who test with assistive technology and report +issues. + +''''' + +*Last Updated*: 2025-01-22 *Version*: 1.0 *Contact*: +accessibility@example.com diff --git a/docs/ACCESSIBILITY.md b/docs/ACCESSIBILITY.md deleted file mode 100644 index d527bda..0000000 --- a/docs/ACCESSIBILITY.md +++ /dev/null @@ -1,340 +0,0 @@ -# Accessibility - -## Commitment to Accessibility - -The Complete Linux Internet Repair Tool is committed to being accessible to all users, including those with disabilities. As a command-line tool, we follow terminal accessibility best practices. - -## Current Accessibility Features - -### Color and Visual - -1. **Color Detection** - - Automatic detection of terminal color capabilities - - Graceful degradation when colors not supported - - `--no-color` flag to disable all color output - -2. **High Contrast** - - Careful selection of ANSI colors for readability - - Green (success), Yellow (warning), Red (error), Blue (info) - - Works with both light and dark terminal backgrounds - -3. **Screen Reader Compatible** - - Plain text output that screen readers can parse - - No ASCII art or complex formatting - - Structured output with clear headers and sections - -### Output Clarity - -1. **Clear Status Indicators** - - ✅ (success), ⚠️ (warning), ❌ (error), → (action) - - Text equivalents: [✓], [WARN], [ERROR], [INFO] - - Both visual and textual indicators provided - -2. **Verbose Mode** - - `--verbose` flag for detailed output - - Explains what the tool is doing at each step - - Helpful for users who need more context - -3. **Quiet Mode** - - `--quiet` flag for minimal output - - Only errors are shown - - Reduces cognitive load - -### Interactive Mode - -1. **Keyboard-Only Navigation** - - Menu-driven interface - - Number keys for selection - - No mouse required - -2. **Clear Prompts** - - Unambiguous question text - - Default options indicated - - Confirmation for destructive actions - -3. **Timeout-Free** - - No time limits on user input - - Users can take their time reading options - - Pauses wait indefinitely for user response - -## Accessibility Guidelines Followed - -### WCAG 2.1 Principles (Adapted for CLI) - -1. **Perceivable** - - ✅ Text alternatives for visual indicators - - ✅ Color is not the only means of conveying information - - ✅ Content can be presented in different ways - -2. **Operable** - - ✅ All functionality available from keyboard - - ✅ No timing constraints on user input - - ✅ Clear navigation through menus - -3. **Understandable** - - ✅ Readable error messages - - ✅ Predictable operation - - ✅ Input assistance (hints and examples) - -4. **Robust** - - ✅ Works with standard terminal emulators - - ✅ Compatible with screen readers (orca, NVDA via SSH) - - ✅ POSIX-compliant where possible - -## Screen Reader Support - -### Tested With - -- **Orca** (Linux): Works with terminal output -- **NVDA** (Windows via WSL): Compatible -- **VoiceOver** (macOS): Compatible with Terminal.app - -### Best Practices for Screen Reader Users - -```bash -# Use verbose mode for more context -network-repair --verbose diagnose - -# Disable colors for cleaner screen reader output -network-repair --no-color diagnose - -# Save output to file for review -network-repair diagnose > /tmp/diag.txt 2>&1 -less /tmp/diag.txt -``` - -## Visual Impairment Considerations - -### Low Vision - -1. **Large Text Terminals** - - Tool respects terminal font size settings - - No fixed-width assumptions - - Works with zoomed terminals - -2. **High Contrast Themes** - - Works with high-contrast terminal themes - - ANSI colors adapt to theme - - No hardcoded color codes - -### Color Blindness - -1. **Not Relying on Color Alone** - - Status indicated by text symbols: ✓, ✗, ⚠ - - Text labels: [INFO], [WARN], [ERROR], [SUCCESS] - - Position and structure convey meaning - -2. **Protanopia/Deuteranopia (Red-Green)** - - Errors use text labels, not just red color - - Success uses text labels, not just green color - - Icons supplement color - -3. **Tritanopia (Blue-Yellow)** - - Info messages use text labels - - Warnings use text labels - -## Cognitive Accessibility - -### Clear Language - -1. **Plain Language** - - Avoid jargon where possible - - Explain technical terms when used - - Short, clear sentences - -2. **Consistent Terminology** - - Same terms for same concepts - - No synonyms for technical terms - - Glossary in documentation - -3. **Progressive Disclosure** - - Basic mode: Simple output - - Verbose mode: Detailed explanation - - Help text available at any time - -### Error Messages - -1. **Actionable Errors** - - What went wrong - - Why it happened - - How to fix it - -Example: -``` -❌ [ERROR] No default route found! - This means your computer doesn't know how to reach the internet. - Run: sudo network-repair repair-routing -``` - -### Predictable Behavior - -1. **Dry-Run Mode** - - Preview changes before applying - - Reduces anxiety about mistakes - - `--dry-run` flag available - -2. **Reversibility** - - All changes are backed up - - Backups stored in `~/.network-repair-backups/` - - Easy to undo mistakes - -## Physical Accessibility - -### Motor Impairments - -1. **Minimal Typing** - - Single-letter menu choices (y/n, 1-6) - - Tab completion for file paths - - Default options reduce typing - -2. **Error Tolerance** - - Forgiving input parsing - - Clear error messages for invalid input - - No case sensitivity for y/n prompts - -3. **Alternative Input Methods** - - Works with voice input (Dragon, speech recognition) - - Compatible with adaptive keyboards - - No mouse required - -## Auditory Accessibility - -### No Audio Requirements - -- All information presented visually as text -- No audio cues or warnings -- No sound effects -- Silent operation - -## Language and Localization - -### Current Status - -- **Primary Language**: English (US) -- **Future Plans**: i18n support (see docs/I18N.md) - -### Clear English - -- Simple vocabulary -- Short sentences -- Active voice preferred -- Technical terms explained - -## Testing - -### Accessibility Testing Checklist - -- [ ] Works with `--no-color` flag -- [ ] Output readable with screen reader -- [ ] Menu navigation keyboard-only -- [ ] No time limits on input -- [ ] Error messages actionable -- [ ] Works in high-contrast mode -- [ ] Tab completion functional -- [ ] Help text comprehensive - -### Test Commands - -```bash -# Test without colors -network-repair --no-color diagnose - -# Test with screen reader -orca & -network-repair diagnose - -# Test verbose output -network-repair --verbose diagnose | less - -# Test interactive mode -sudo network-repair interactive -``` - -## Known Limitations - -1. **Terminal-Only** - - No GUI alternative (planned for future) - - Requires terminal emulator - - Command-line knowledge helpful - -2. **English-Only** - - Currently only English (US) - - i18n planned for future versions - - See docs/I18N.md for roadmap - -3. **Root Required for Repairs** - - Many operations need sudo/root - - Diagnostics work without root - - Clear prompts when sudo needed - -## Reporting Accessibility Issues - -If you encounter accessibility barriers: - -1. **Open an Issue** - - Tag with `accessibility` label - - Describe the barrier - - Include your setup (OS, terminal, assistive tech) - -2. **Suggest Improvements** - - We welcome accessibility enhancement PRs - - See CONTRIBUTING.md - - Ask questions first - -3. **Contact** - - Email: accessibility@example.com - - GitHub: Open issue with [ACCESSIBILITY] tag - -## Accessibility Roadmap - -### Short Term (v1.1) - -- [ ] Improve screen reader testing -- [ ] Add more text-only output options -- [ ] Enhanced `--no-color` mode -- [ ] Accessibility testing in CI - -### Medium Term (v1.2-1.3) - -- [ ] i18n support (see I18N.md) -- [ ] GUI mode (Electron or web-based) -- [ ] Better error message formatting -- [ ] Audio output option (TTS) - -### Long Term (v2.0+) - -- [ ] Full WCAG 2.1 AA compliance audit -- [ ] Multiple UI modes (CLI, TUI, GUI) -- [ ] Braille display support -- [ ] Switch access support - -## Resources - -### Standards - -- [WCAG 2.1](https://www.w3.org/WAI/WCAG21/quickref/) -- [Section 508](https://www.section508.gov/) -- [EN 301 549](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/03.02.01_60/en_301549v030201p.pdf) - -### Tools - -- [Pa11y](https://pa11y.org/) - Accessibility testing -- [axe DevTools](https://www.deque.com/axe/) - Accessibility checker -- [NVDA](https://www.nvaccess.org/) - Windows screen reader -- [Orca](https://help.gnome.org/users/orca/stable/) - Linux screen reader - -### Community - -- [A11y Project](https://www.a11yproject.com/) -- [WebAIM](https://webaim.org/) -- [Inclusive Design Principles](https://inclusivedesignprinciples.org/) - -## Acknowledgments - -We thank the accessibility community for ongoing guidance and feedback. Special thanks to users who test with assistive technology and report issues. - ---- - -**Last Updated**: 2025-01-22 -**Version**: 1.0 -**Contact**: accessibility@example.com diff --git a/docs/ARCHITECTURE.adoc b/docs/ARCHITECTURE.adoc new file mode 100644 index 0000000..57be0cc --- /dev/null +++ b/docs/ARCHITECTURE.adoc @@ -0,0 +1,397 @@ +== Architecture Documentation + +=== Overview + +The Complete Linux Internet Repair Tool is designed as a modular +bash-based system for diagnosing and repairing network connectivity +issues on Linux systems. + +=== Design Principles + +[arabic] +. *Modularity*: Each diagnostic and repair function is self-contained +. *Safety*: Always backup before modifications, support dry-run mode +. *Portability*: Works across multiple Linux distributions +. *Transparency*: Detailed logging of all operations +. *Fail-safe*: Graceful degradation if optional tools are missing + +=== Component Architecture + +.... +┌─────────────────────────────────────────────────┐ +│ Main Entry Point (main.sh) │ +│ - Argument parsing │ +│ - Mode selection (CLI/Interactive) │ +│ - Orchestrates diagnostic and repair flows │ +└────────────┬────────────────────────────────────┘ + │ + ┌────────┴────────┐ + │ │ +┌───▼────────┐ ┌───▼────────┐ +│Diagnostics │ │ Repairs │ +│ Modules │ │ Modules │ +└───┬────────┘ └───┬────────┘ + │ │ + │ ┌────────────┴────────────┐ + │ │ │ + │ │ Utility Layer │ + │ │ - Logging │ + │ │ - Colors │ + │ │ - Privileges │ + │ │ - Backup │ + │ │ - System Detection │ + │ │ │ + │ └─────────────────────────┘ + │ +┌───▼──────────────────────────────────┐ +│ Linux System Interface │ +│ - ip/iproute2 │ +│ - systemctl │ +│ - NetworkManager │ +│ - DNS tools │ +└──────────────────────────────────────┘ +.... + +=== Module Descriptions + +==== Utility Modules + +Located in `+src/utils/+` + +===== colors.sh + +* Provides terminal color support +* Auto-detects color capability +* Exports color variables for use in other modules + +===== logging.sh + +* Centralized logging system +* Multiple log levels (DEBUG, INFO, WARN, ERROR, FATAL) +* File and console output +* Colored output support + +===== privileges.sh + +* Root privilege detection +* Sudo access management +* Safe privilege elevation + +===== backup.sh + +* Automatic file backup before modifications +* Timestamped backups +* Backup retention policies +* Restore functionality + +===== system.sh + +* Distribution detection +* Network manager detection +* Interface management functions +* DNS testing utilities + +==== Diagnostic Modules + +Located in `+src/diagnostics/+` + +Each diagnostic module: - Sources required utilities - Implements +specific checks - Returns exit code: 0 (no issues) or 1 (issues found) - +Logs findings using logging utility + +===== dns.sh + +*Checks:* - `+/etc/resolv.conf+` configuration - systemd-resolved status +- NetworkManager DNS settings - DNS resolution functionality - DNS +server responsiveness + +*Functions:* - `+check_dns_config()+` - Validates DNS configuration +files - `+test_dns_resolution()+` - Tests actual DNS resolution - +`+test_dns_servers()+` - Tests individual DNS servers - +`+diagnose_dns()+` - Main diagnostic function + +===== interfaces.sh + +*Checks:* - Interface existence and status - IP address assignment - MAC +addresses - Link status - Driver information - Interface statistics + +*Functions:* - `+check_interfaces()+` - Lists and checks all interfaces +- `+check_primary_interface()+` - Validates primary interface - +`+check_interface_stats()+` - Checks for errors/drops - +`+diagnose_interfaces()+` - Main diagnostic function + +===== routing.sh + +*Checks:* - Default route existence - Gateway reachability - IPv6 +routing - Route metrics - ARP table + +*Functions:* - `+check_routing_table()+` - Validates routing table - +`+check_ipv6_routing()+` - IPv6 route checks - `+test_internet_route()+` +- Tests routes to internet - `+diagnose_routing()+` - Main diagnostic +function + +===== connectivity.sh + +*Checks:* - Basic ping connectivity - DNS-based connectivity - +HTTP/HTTPS connectivity - Port connectivity - MTU - Latency + +*Functions:* - `+test_basic_connectivity()+` - Ping tests - +`+test_dns_connectivity()+` - DNS + ping tests - +`+test_http_connectivity()+` - Web connectivity - `+test_mtu()+` - MTU +discovery - `+diagnose_connectivity()+` - Main diagnostic function + +===== firewall.sh + +*Checks:* - iptables rules - nftables rules - UFW status - firewalld +status + +*Functions:* - `+check_iptables()+` - Examines iptables rules - +`+check_ufw()+` - UFW configuration - `+check_firewalld()+` - firewalld +configuration - `+diagnose_firewall()+` - Main diagnostic function + +===== networkmanager.sh + +*Checks:* - NetworkManager service status - Active connections - Device +status - Connectivity state - Configuration - Conflicts with other +network managers + +*Functions:* - `+check_nm_status()+` - Service status - +`+check_nm_connections()+` - Connection status - +`+check_nm_conflicts()+` - Detect conflicts - +`+diagnose_networkmanager()+` - Main diagnostic function + +==== Repair Modules + +Located in `+src/repairs/+` + +Each repair module: - Requires root privileges (checked) - Creates +backups before modifications - Implements fixes for common issues - +Verifies repairs succeeded - Returns exit code: 0 (success) or 1 +(failure) + +===== dns.sh + +*Repairs:* - Creates missing `+/etc/resolv.conf+` - Adds working DNS +servers - Resets DNS to known-good defaults - Restarts systemd-resolved +- Flushes DNS cache - Configures NetworkManager DNS + +*Functions:* - `+repair_dns_config()+` - Fix DNS configuration - +`+reset_dns_to_defaults()+` - Complete DNS reset - +`+restart_systemd_resolved()+` - Restart DNS service - +`+flush_dns_cache()+` - Clear cached entries - `+repair_dns()+` - Main +repair function + +===== interfaces.sh + +*Repairs:* - Brings up down interfaces - Restarts problematic interfaces +- Renews DHCP leases - Resets interface to DHCP - Configures primary +interface + +*Functions:* - `+interface_up()+` - Bring interface up - +`+restart_interface()+` - Restart interface - `+renew_dhcp()+` - Renew +DHCP lease - `+repair_interfaces()+` - Main repair function + +===== routing.sh + +*Repairs:* - Adds missing default route - Removes duplicate routes - +Repairs gateway configuration - Flushes and rebuilds routing table + +*Functions:* - `+add_default_route()+` - Add default route - +`+remove_duplicate_routes()+` - Clean routing table - +`+repair_default_route()+` - Fix default route - `+repair_routing()+` - +Main repair function + +===== networkmanager.sh + +*Repairs:* - Restarts NetworkManager service - Reconnects connections - +Enables management on interfaces - Repairs conflicts - Resets +connections + +*Functions:* - `+restart_networkmanager()+` - Restart service - +`+reconnect_nm_connection()+` - Reconnect - `+repair_nm_conflicts()+` - +Fix conflicts - `+repair_networkmanager()+` - Main repair function + +=== Data Flow + +==== Diagnostic Flow + +.... +User → main.sh → parse_args() + ↓ + run_all_diagnostics() + ↓ + ┌─────────┴─────────┐ + │ │ +diagnose_dns() diagnose_interfaces() + │ │ + └─────────┬─────────┘ + ↓ + Aggregate Results + ↓ + Display Summary + ↓ + Offer to Repair (if issues found) +.... + +==== Repair Flow + +.... +User → main.sh → parse_args() + ↓ + require_root() + ↓ + run_all_repairs() + ↓ + ┌─────────┴─────────┐ + │ │ +repair_dns() repair_interfaces() + │ │ + ├─ backup_file() ├─ interface_up() + ├─ modify_config() ├─ renew_dhcp() + └─ verify_fix() └─ verify_fix() + │ + └─────────┬───────── + ↓ + Final Connectivity Test + ↓ + Display Summary +.... + +=== Error Handling + +==== Philosophy + +[arabic] +. *Fail gracefully*: Continue with other checks if one fails +. *Report clearly*: Detailed error messages +. *Provide context*: Suggest next steps +. *Preserve state*: Backup before destructive operations + +==== Implementation + +[source,bash] +---- +# Check exit codes +if ! some_command; then + log_error "Command failed: some_command" + return 1 +fi + +# Aggregate errors +local total_issues=0 +check_something +total_issues=$((total_issues + $?)) + +# Always verify +if verify_fix; then + log_success "Fix successful" +else + log_error "Fix failed, restoring backup" + restore_backup +fi +---- + +=== Security Considerations + +==== Privilege Escalation + +* Only request root when necessary +* Clear indication when sudo is needed +* Keep sudo alive for batch operations +* No arbitrary command execution + +==== Input Validation + +[source,bash] +---- +# Sanitize all user inputs +interface=$(sanitize_input "${interface}") + +# Validate before use +if ! interface_exists "${interface}"; then + log_error "Invalid interface" + return 1 +fi +---- + +==== File Operations + +* Backup before modification +* Verify file permissions +* Use temporary files for complex operations +* Clean up temporary files + +==== Command Injection Prevention + +* Quote all variables +* Use arrays for command construction +* Sanitize inputs +* Avoid eval + +=== Testing Strategy + +==== Unit Tests + +* Test individual functions +* Mock system commands +* Test error conditions + +==== Integration Tests + +* Test full workflows +* Test on multiple distributions +* Test with various network configurations + +==== Syntax Validation + +* Bash syntax checking (`+bash -n+`) +* ShellCheck linting +* Style guide compliance + +=== Extension Points + +==== Adding New Diagnostics + +[arabic] +. Create file in `+src/diagnostics/+` +. Implement `+diagnose_modulename()+` function +. Source in `+main.sh+` +. Add to `+run_all_diagnostics()+` +. Add tests +. Update documentation + +==== Adding New Repairs + +[arabic] +. Create file in `+src/repairs/+` +. Implement `+repair_modulename()+` function +. Source in `+main.sh+` +. Add to `+run_all_repairs()+` +. Add tests +. Update documentation + +==== Adding New Utilities + +[arabic] +. Create file in `+src/utils/+` +. Implement utility functions +. Source in modules that need it +. Add tests +. Document in CLAUDE.md + +=== Performance Considerations + +* Parallel execution where possible (using background jobs) +* Minimize external command calls +* Cache expensive operations +* Use built-in bash features over external commands + +=== Future Architecture Improvements + +[arabic] +. *Plugin System*: Dynamic module loading +. *Configuration Management*: Per-distribution configs +. *Remote Execution*: SSH-based remote diagnostics +. *API Layer*: JSON output for programmatic use +. *Database*: Store diagnostic history +. *Web Interface*: Browser-based management diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md deleted file mode 100644 index fbfbc74..0000000 --- a/docs/ARCHITECTURE.md +++ /dev/null @@ -1,427 +0,0 @@ -# Architecture Documentation - -## Overview - -The Complete Linux Internet Repair Tool is designed as a modular bash-based system for diagnosing and repairing network connectivity issues on Linux systems. - -## Design Principles - -1. **Modularity**: Each diagnostic and repair function is self-contained -2. **Safety**: Always backup before modifications, support dry-run mode -3. **Portability**: Works across multiple Linux distributions -4. **Transparency**: Detailed logging of all operations -5. **Fail-safe**: Graceful degradation if optional tools are missing - -## Component Architecture - -``` -┌─────────────────────────────────────────────────┐ -│ Main Entry Point (main.sh) │ -│ - Argument parsing │ -│ - Mode selection (CLI/Interactive) │ -│ - Orchestrates diagnostic and repair flows │ -└────────────┬────────────────────────────────────┘ - │ - ┌────────┴────────┐ - │ │ -┌───▼────────┐ ┌───▼────────┐ -│Diagnostics │ │ Repairs │ -│ Modules │ │ Modules │ -└───┬────────┘ └───┬────────┘ - │ │ - │ ┌────────────┴────────────┐ - │ │ │ - │ │ Utility Layer │ - │ │ - Logging │ - │ │ - Colors │ - │ │ - Privileges │ - │ │ - Backup │ - │ │ - System Detection │ - │ │ │ - │ └─────────────────────────┘ - │ -┌───▼──────────────────────────────────┐ -│ Linux System Interface │ -│ - ip/iproute2 │ -│ - systemctl │ -│ - NetworkManager │ -│ - DNS tools │ -└──────────────────────────────────────┘ -``` - -## Module Descriptions - -### Utility Modules - -Located in `src/utils/` - -#### colors.sh -- Provides terminal color support -- Auto-detects color capability -- Exports color variables for use in other modules - -#### logging.sh -- Centralized logging system -- Multiple log levels (DEBUG, INFO, WARN, ERROR, FATAL) -- File and console output -- Colored output support - -#### privileges.sh -- Root privilege detection -- Sudo access management -- Safe privilege elevation - -#### backup.sh -- Automatic file backup before modifications -- Timestamped backups -- Backup retention policies -- Restore functionality - -#### system.sh -- Distribution detection -- Network manager detection -- Interface management functions -- DNS testing utilities - -### Diagnostic Modules - -Located in `src/diagnostics/` - -Each diagnostic module: -- Sources required utilities -- Implements specific checks -- Returns exit code: 0 (no issues) or 1 (issues found) -- Logs findings using logging utility - -#### dns.sh -**Checks:** -- `/etc/resolv.conf` configuration -- systemd-resolved status -- NetworkManager DNS settings -- DNS resolution functionality -- DNS server responsiveness - -**Functions:** -- `check_dns_config()` - Validates DNS configuration files -- `test_dns_resolution()` - Tests actual DNS resolution -- `test_dns_servers()` - Tests individual DNS servers -- `diagnose_dns()` - Main diagnostic function - -#### interfaces.sh -**Checks:** -- Interface existence and status -- IP address assignment -- MAC addresses -- Link status -- Driver information -- Interface statistics - -**Functions:** -- `check_interfaces()` - Lists and checks all interfaces -- `check_primary_interface()` - Validates primary interface -- `check_interface_stats()` - Checks for errors/drops -- `diagnose_interfaces()` - Main diagnostic function - -#### routing.sh -**Checks:** -- Default route existence -- Gateway reachability -- IPv6 routing -- Route metrics -- ARP table - -**Functions:** -- `check_routing_table()` - Validates routing table -- `check_ipv6_routing()` - IPv6 route checks -- `test_internet_route()` - Tests routes to internet -- `diagnose_routing()` - Main diagnostic function - -#### connectivity.sh -**Checks:** -- Basic ping connectivity -- DNS-based connectivity -- HTTP/HTTPS connectivity -- Port connectivity -- MTU -- Latency - -**Functions:** -- `test_basic_connectivity()` - Ping tests -- `test_dns_connectivity()` - DNS + ping tests -- `test_http_connectivity()` - Web connectivity -- `test_mtu()` - MTU discovery -- `diagnose_connectivity()` - Main diagnostic function - -#### firewall.sh -**Checks:** -- iptables rules -- nftables rules -- UFW status -- firewalld status - -**Functions:** -- `check_iptables()` - Examines iptables rules -- `check_ufw()` - UFW configuration -- `check_firewalld()` - firewalld configuration -- `diagnose_firewall()` - Main diagnostic function - -#### networkmanager.sh -**Checks:** -- NetworkManager service status -- Active connections -- Device status -- Connectivity state -- Configuration -- Conflicts with other network managers - -**Functions:** -- `check_nm_status()` - Service status -- `check_nm_connections()` - Connection status -- `check_nm_conflicts()` - Detect conflicts -- `diagnose_networkmanager()` - Main diagnostic function - -### Repair Modules - -Located in `src/repairs/` - -Each repair module: -- Requires root privileges (checked) -- Creates backups before modifications -- Implements fixes for common issues -- Verifies repairs succeeded -- Returns exit code: 0 (success) or 1 (failure) - -#### dns.sh -**Repairs:** -- Creates missing `/etc/resolv.conf` -- Adds working DNS servers -- Resets DNS to known-good defaults -- Restarts systemd-resolved -- Flushes DNS cache -- Configures NetworkManager DNS - -**Functions:** -- `repair_dns_config()` - Fix DNS configuration -- `reset_dns_to_defaults()` - Complete DNS reset -- `restart_systemd_resolved()` - Restart DNS service -- `flush_dns_cache()` - Clear cached entries -- `repair_dns()` - Main repair function - -#### interfaces.sh -**Repairs:** -- Brings up down interfaces -- Restarts problematic interfaces -- Renews DHCP leases -- Resets interface to DHCP -- Configures primary interface - -**Functions:** -- `interface_up()` - Bring interface up -- `restart_interface()` - Restart interface -- `renew_dhcp()` - Renew DHCP lease -- `repair_interfaces()` - Main repair function - -#### routing.sh -**Repairs:** -- Adds missing default route -- Removes duplicate routes -- Repairs gateway configuration -- Flushes and rebuilds routing table - -**Functions:** -- `add_default_route()` - Add default route -- `remove_duplicate_routes()` - Clean routing table -- `repair_default_route()` - Fix default route -- `repair_routing()` - Main repair function - -#### networkmanager.sh -**Repairs:** -- Restarts NetworkManager service -- Reconnects connections -- Enables management on interfaces -- Repairs conflicts -- Resets connections - -**Functions:** -- `restart_networkmanager()` - Restart service -- `reconnect_nm_connection()` - Reconnect -- `repair_nm_conflicts()` - Fix conflicts -- `repair_networkmanager()` - Main repair function - -## Data Flow - -### Diagnostic Flow - -``` -User → main.sh → parse_args() - ↓ - run_all_diagnostics() - ↓ - ┌─────────┴─────────┐ - │ │ -diagnose_dns() diagnose_interfaces() - │ │ - └─────────┬─────────┘ - ↓ - Aggregate Results - ↓ - Display Summary - ↓ - Offer to Repair (if issues found) -``` - -### Repair Flow - -``` -User → main.sh → parse_args() - ↓ - require_root() - ↓ - run_all_repairs() - ↓ - ┌─────────┴─────────┐ - │ │ -repair_dns() repair_interfaces() - │ │ - ├─ backup_file() ├─ interface_up() - ├─ modify_config() ├─ renew_dhcp() - └─ verify_fix() └─ verify_fix() - │ - └─────────┬───────── - ↓ - Final Connectivity Test - ↓ - Display Summary -``` - -## Error Handling - -### Philosophy - -1. **Fail gracefully**: Continue with other checks if one fails -2. **Report clearly**: Detailed error messages -3. **Provide context**: Suggest next steps -4. **Preserve state**: Backup before destructive operations - -### Implementation - -```bash -# Check exit codes -if ! some_command; then - log_error "Command failed: some_command" - return 1 -fi - -# Aggregate errors -local total_issues=0 -check_something -total_issues=$((total_issues + $?)) - -# Always verify -if verify_fix; then - log_success "Fix successful" -else - log_error "Fix failed, restoring backup" - restore_backup -fi -``` - -## Security Considerations - -### Privilege Escalation - -- Only request root when necessary -- Clear indication when sudo is needed -- Keep sudo alive for batch operations -- No arbitrary command execution - -### Input Validation - -```bash -# Sanitize all user inputs -interface=$(sanitize_input "${interface}") - -# Validate before use -if ! interface_exists "${interface}"; then - log_error "Invalid interface" - return 1 -fi -``` - -### File Operations - -- Backup before modification -- Verify file permissions -- Use temporary files for complex operations -- Clean up temporary files - -### Command Injection Prevention - -- Quote all variables -- Use arrays for command construction -- Sanitize inputs -- Avoid eval - -## Testing Strategy - -### Unit Tests - -- Test individual functions -- Mock system commands -- Test error conditions - -### Integration Tests - -- Test full workflows -- Test on multiple distributions -- Test with various network configurations - -### Syntax Validation - -- Bash syntax checking (`bash -n`) -- ShellCheck linting -- Style guide compliance - -## Extension Points - -### Adding New Diagnostics - -1. Create file in `src/diagnostics/` -2. Implement `diagnose_modulename()` function -3. Source in `main.sh` -4. Add to `run_all_diagnostics()` -5. Add tests -6. Update documentation - -### Adding New Repairs - -1. Create file in `src/repairs/` -2. Implement `repair_modulename()` function -3. Source in `main.sh` -4. Add to `run_all_repairs()` -5. Add tests -6. Update documentation - -### Adding New Utilities - -1. Create file in `src/utils/` -2. Implement utility functions -3. Source in modules that need it -4. Add tests -5. Document in CLAUDE.md - -## Performance Considerations - -- Parallel execution where possible (using background jobs) -- Minimize external command calls -- Cache expensive operations -- Use built-in bash features over external commands - -## Future Architecture Improvements - -1. **Plugin System**: Dynamic module loading -2. **Configuration Management**: Per-distribution configs -3. **Remote Execution**: SSH-based remote diagnostics -4. **API Layer**: JSON output for programmatic use -5. **Database**: Store diagnostic history -6. **Web Interface**: Browser-based management diff --git a/docs/I18N.adoc b/docs/I18N.adoc new file mode 100644 index 0000000..fa80a58 --- /dev/null +++ b/docs/I18N.adoc @@ -0,0 +1,481 @@ +== Internationalization (i18n) and Localization (l10n) + +=== Current Status + +*Version 1.0*: English (US) only *Planned*: v1.2+ will include i18n +framework + +=== Why i18n Matters + +Linux is used worldwide. Network issues don’t respect language barriers. +We want this tool to be accessible to: + +* Non-English speakers +* Multilingual teams +* Global system administrators +* International open source contributors + +=== Goals + +[arabic] +. *Complete Translation*: All user-facing text +. *Cultural Adaptation*: Date formats, examples, terminology +. *Maintained Quality*: Keep translations up-to-date +. *Easy Contribution*: Low barrier for translators + +=== Architecture Plan + +==== Message Catalog System + +[source,bash] +---- +# Directory structure (planned for v1.2) +locales/ +├── en_US/ +│ ├── LC_MESSAGES/ +│ │ ├── common.po +│ │ ├── diagnostics.po +│ │ ├── repairs.po +│ │ └── interactive.po +│ └── metadata.json +├── es_ES/ +│ ├── LC_MESSAGES/ +│ │ ├── common.po +│ │ ├── diagnostics.po +│ │ ├── repairs.po +│ │ └── interactive.po +│ └── metadata.json +├── fr_FR/ +├── de_DE/ +├── ja_JP/ +├── zh_CN/ +└── pt_BR/ +---- + +==== Translation Function + +[source,bash] +---- +# Planned implementation +t() { + local key="$1" + local locale="${LANG:-en_US}" + local catalog="${2:-common}" + + # Look up translation + local translation + translation=$(get_translation "${locale}" "${catalog}" "${key}") + + # Fallback to English + if [[ -z "${translation}" ]]; then + translation=$(get_translation "en_US" "${catalog}" "${key}") + fi + + # Fallback to key + echo "${translation:-${key}}" +} + +# Usage +log_info "$(t 'msg.network.checking')" +log_error "$(t 'error.no_interface' 'diagnostics')" +---- + +=== Translation Priority + +==== Phase 1: Core Messages (v1.2) + +*Priority*: Critical user-facing text + +* Error messages +* Warning messages +* Success messages +* Interactive prompts (y/n, menu choices) +* Help text (`+--help+` output) + +==== Phase 2: Documentation (v1.3) + +*Priority*: High + +* README.md +* CONTRIBUTING.md +* Troubleshooting guide +* Basic usage examples + +==== Phase 3: Extended Content (v1.4+) + +*Priority*: Medium + +* Advanced examples +* Architecture documentation +* Code comments (optional) + +=== Target Languages + +==== Initial Launch Languages (v1.2) + +Based on Linux usage statistics and contributor availability: + +[arabic] +. *Spanish (es_ES, es_MX)* - 400M+ speakers +. *French (fr_FR)* - 275M+ speakers +. *German (de_DE)* - 130M+ speakers +. *Portuguese (pt_BR, pt_PT)* - 250M+ speakers +. *Japanese (ja_JP)* - 125M+ speakers +. *Chinese Simplified (zh_CN)* - 1B+ speakers +. *Russian (ru_RU)* - 260M+ speakers + +==== Future Languages (v1.4+) + +Community-driven: + +* Italian (it_IT) +* Korean (ko_KR) +* Arabic (ar) +* Hindi (hi_IN) +* Dutch (nl_NL) +* Polish (pl_PL) +* Turkish (tr_TR) + +=== Technical Considerations + +==== Challenges in Bash + +[arabic] +. *No Native i18n* +* Bash doesn’t have built-in gettext support +* Need custom implementation +* Consider external tool (gettext, envsubst) +. *String Concatenation* +* Bash strings concatenate easily, but translations need placeholders +* Solution: Use printf-style formatting +. *File Size* +* Loading all translations increases script size +* Solution: Lazy loading, separate files + +==== Solution Approaches + +===== Option 1: gettext (Traditional) + +[source,bash] +---- +# Use GNU gettext +source gettext.sh +export TEXTDOMAIN="network-repair" +export TEXTDOMAINDIR="/usr/share/locale" + +# Usage +echo "$(gettext "Checking network interfaces...")" +echo "$(eval_gettext "Found \$count interfaces")" +---- + +*Pros*: Industry standard, tool support *Cons*: External dependency, +slower + +===== Option 2: Custom PO Files + +[source,bash] +---- +# Parse .po files in bash +load_translations() { + local locale="$1" + local po_file="locales/${locale}/LC_MESSAGES/common.po" + + # Parse and cache + while IFS= read -r line; do + # msgid "key" + # msgstr "translation" + # ... + done < "${po_file}" +} +---- + +*Pros*: No external dependencies *Cons*: Custom parser, more maintenance + +===== Option 3: JSON Messages + +[source,bash] +---- +# Use jq for JSON parsing +t() { + local key="$1" + local locale="${LANG:-en_US}" + + jq -r ".${key} // \"${key}\"" \ + "locales/${locale}/messages.json" +} +---- + +*Pros*: Easy to parse, readable format *Cons*: Requires jq dependency + +==== Recommended Approach + +*Hybrid*: JSON for simplicity, with gettext compatibility + +[source,bash] +---- +# messages.json +{ + "network.check.start": "Checking network configuration...", + "network.check.dns": "Checking DNS servers", + "error.no_interface": "No network interfaces found", + "prompt.continue": "Continue? (y/n)" +} +---- + +=== Translation Workflow + +==== For Translators + +[arabic] +. *Join Translation Team* +* Open issue: "`Translation: [Language]`" +* Get added to translators team +. *Clone Repository* ++ +[source,bash] +---- +git clone https://github.com/Hyperpolymath/complete-linux-internet-repair +cd complete-linux-internet-repair +---- +. *Create Language Directory* ++ +[source,bash] +---- +mkdir -p locales/es_ES/LC_MESSAGES +cp locales/en_US/LC_MESSAGES/*.po locales/es_ES/LC_MESSAGES/ +---- +. *Translate* +* Edit .po files with Poedit or text editor +* Test translations: `+LANG=es_ES ./network-repair diagnose+` +* Submit PR +. *Maintenance* +* Watch for new strings (CI notifies) +* Update translations in follow-up PRs + +==== For Developers + +[arabic] +. *Extract Strings* ++ +[source,bash] +---- +# Run extraction tool (planned) +just extract-strings + +# Updates locales/en_US/LC_MESSAGES/*.pot (template) +---- +. *Mark Translatable Strings* ++ +[source,bash] +---- +# Instead of: +echo "Checking DNS..." + +# Use: +echo "$(t 'dns.check.start')" +---- +. *Test Translations* ++ +[source,bash] +---- +# Test Spanish +LANG=es_ES ./network-repair diagnose + +# Test French +LANG=fr_FR ./network-repair --help +---- + +=== Cultural Considerations + +==== Date and Time + +[source,bash] +---- +# Locale-aware date formatting +format_date() { + local timestamp="$1" + local locale="${LANG:-en_US}" + + case "${locale}" in + en_US) + date -d "@${timestamp}" "+%m/%d/%Y %I:%M %p" + ;; + en_GB) + date -d "@${timestamp}" "+%d/%m/%Y %H:%M" + ;; + ja_JP) + date -d "@${timestamp}" "+%Y年%m月%d日 %H:%M" + ;; + *) + date -d "@${timestamp}" "+%Y-%m-%d %H:%M" + ;; + esac +} +---- + +==== Network Examples + +[source,bash] +---- +# Different countries use different private IP ranges +get_example_ip() { + local locale="${LANG:-en_US}" + + case "${locale}" in + en_US) + echo "192.168.1.100" + ;; + ja_JP) + echo "192.168.0.100" # More common in Japan + ;; + *) + echo "192.168.1.100" + ;; + esac +} +---- + +==== Terminology + +[width="100%",cols="24%,21%,19%,19%,17%",options="header",] +|=== +|English |Spanish |French |German |Notes +|Network Interface |Interfaz de Red |Interface Réseau +|Netzwerkschnittstelle |- + +|Gateway |Puerta de Enlace |Passerelle |Gateway |German uses English + +|DNS Server |Servidor DNS |Serveur DNS |DNS-Server |- + +|Routing Table |Tabla de Enrutamiento |Table de Routage |Routing-Tabelle +|- +|=== + +=== Testing Translations + +==== Manual Testing + +[source,bash] +---- +# Test each language +for lang in en_US es_ES fr_FR de_DE; do + echo "Testing ${lang}..." + LANG=${lang} ./network-repair diagnose +done +---- + +==== Automated Testing + +[source,bash] +---- +# Planned: Translation completeness check +just check-translations + +# Output: +# en_US: 100% (245/245) +# es_ES: 98% (240/245) - 5 missing +# fr_FR: 85% (208/245) - 37 missing +---- + +=== Translation Style Guide + +==== Tone + +* *Professional but friendly* +* *Clear and direct* +* *Avoid idioms* (don’t translate directly) +* *Technical accuracy* over literal translation + +==== Format + +* *Preserve placeholders*: `+%s+`, `+${var}+`, `+$count+` +* *Maintain line breaks*: Keep `+\n+` where they appear +* *Keep punctuation*: Match source language style +* *Preserve formatting*: `+*bold*+`, `+_italic_+`, etc. + +==== Examples + +*Good Translation*: + +[source,po] +---- +msgid "Checking network interface %s" +msgstr "Comprobando interfaz de red %s" +---- + +*Bad Translation*: + +[source,po] +---- +msgid "Checking network interface %s" +msgstr "Comprobando %s interfaz de red" # Wrong placeholder order +---- + +=== Contribution Recognition + +==== Translation Credits + +Translators will be credited in: + +[arabic] +. *humans.txt*: Translator section +. *CHANGELOG.md*: Translation additions +. *GitHub contributors*: Automatic via commits +. *Language metadata.json*: Translator names per language + +==== Translation Teams + +[cols=",,,",options="header",] +|=== +|Language |Lead Translator |Contributors |Status +|en_US |Project Team |- |Complete +|es_ES |_Seeking_ |- |Planned +|fr_FR |_Seeking_ |- |Planned +|de_DE |_Seeking_ |- |Planned +|=== + +=== Resources + +==== Tools + +* *Poedit*: https://poedit.net/ (PO file editor) +* *Lokalize*: https://apps.kde.org/lokalize/ (KDE translator) +* *Weblate*: https://weblate.org/ (Web-based translation) +* *Transifex*: https://www.transifex.com/ (Translation platform) + +==== References + +* *GNU gettext*: https://www.gnu.org/software/gettext/ +* *Bash i18n*: https://mywiki.wooledge.org/BashFAQ/098 +* *POSIX locale*: +https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html + +=== Timeline + +[cols=",,",options="header",] +|=== +|Version |Milestone |Target Date +|v1.0 |English only |2025-01 ✅ +|v1.1 |i18n framework |2025-03 +|v1.2 |3 languages (es, fr, de) |2025-06 +|v1.3 |7 languages (+ pt, ja, zh, ru) |2025-09 +|v1.4 |Community languages |2025-12 +|=== + +=== Get Involved + +Want to help translate? + +[arabic] +. *Check existing translations*: See what’s needed +. *Open an issue*: "`Translation: [Your Language]`" +. *Join the team*: We’ll add you to translators +. *Start translating*: Follow workflow above +. *Submit PR*: We review and merge + +All translation contributors welcome, regardless of skill level! + +''''' + +*Last Updated*: 2025-01-22 *Version*: 1.0 (planning document) *Contact*: +i18n@example.com diff --git a/docs/I18N.md b/docs/I18N.md deleted file mode 100644 index 2e6c615..0000000 --- a/docs/I18N.md +++ /dev/null @@ -1,448 +0,0 @@ -# Internationalization (i18n) and Localization (l10n) - -## Current Status - -**Version 1.0**: English (US) only -**Planned**: v1.2+ will include i18n framework - -## Why i18n Matters - -Linux is used worldwide. Network issues don't respect language barriers. We want this tool to be accessible to: - -- Non-English speakers -- Multilingual teams -- Global system administrators -- International open source contributors - -## Goals - -1. **Complete Translation**: All user-facing text -2. **Cultural Adaptation**: Date formats, examples, terminology -3. **Maintained Quality**: Keep translations up-to-date -4. **Easy Contribution**: Low barrier for translators - -## Architecture Plan - -### Message Catalog System - -```bash -# Directory structure (planned for v1.2) -locales/ -├── en_US/ -│ ├── LC_MESSAGES/ -│ │ ├── common.po -│ │ ├── diagnostics.po -│ │ ├── repairs.po -│ │ └── interactive.po -│ └── metadata.json -├── es_ES/ -│ ├── LC_MESSAGES/ -│ │ ├── common.po -│ │ ├── diagnostics.po -│ │ ├── repairs.po -│ │ └── interactive.po -│ └── metadata.json -├── fr_FR/ -├── de_DE/ -├── ja_JP/ -├── zh_CN/ -└── pt_BR/ -``` - -### Translation Function - -```bash -# Planned implementation -t() { - local key="$1" - local locale="${LANG:-en_US}" - local catalog="${2:-common}" - - # Look up translation - local translation - translation=$(get_translation "${locale}" "${catalog}" "${key}") - - # Fallback to English - if [[ -z "${translation}" ]]; then - translation=$(get_translation "en_US" "${catalog}" "${key}") - fi - - # Fallback to key - echo "${translation:-${key}}" -} - -# Usage -log_info "$(t 'msg.network.checking')" -log_error "$(t 'error.no_interface' 'diagnostics')" -``` - -## Translation Priority - -### Phase 1: Core Messages (v1.2) - -**Priority**: Critical user-facing text - -- Error messages -- Warning messages -- Success messages -- Interactive prompts (y/n, menu choices) -- Help text (`--help` output) - -### Phase 2: Documentation (v1.3) - -**Priority**: High - -- README.md -- CONTRIBUTING.md -- Troubleshooting guide -- Basic usage examples - -### Phase 3: Extended Content (v1.4+) - -**Priority**: Medium - -- Advanced examples -- Architecture documentation -- Code comments (optional) - -## Target Languages - -### Initial Launch Languages (v1.2) - -Based on Linux usage statistics and contributor availability: - -1. **Spanish (es_ES, es_MX)** - 400M+ speakers -2. **French (fr_FR)** - 275M+ speakers -3. **German (de_DE)** - 130M+ speakers -4. **Portuguese (pt_BR, pt_PT)** - 250M+ speakers -5. **Japanese (ja_JP)** - 125M+ speakers -6. **Chinese Simplified (zh_CN)** - 1B+ speakers -7. **Russian (ru_RU)** - 260M+ speakers - -### Future Languages (v1.4+) - -Community-driven: - -- Italian (it_IT) -- Korean (ko_KR) -- Arabic (ar) -- Hindi (hi_IN) -- Dutch (nl_NL) -- Polish (pl_PL) -- Turkish (tr_TR) - -## Technical Considerations - -### Challenges in Bash - -1. **No Native i18n** - - Bash doesn't have built-in gettext support - - Need custom implementation - - Consider external tool (gettext, envsubst) - -2. **String Concatenation** - - Bash strings concatenate easily, but translations need placeholders - - Solution: Use printf-style formatting - -3. **File Size** - - Loading all translations increases script size - - Solution: Lazy loading, separate files - -### Solution Approaches - -#### Option 1: gettext (Traditional) - -```bash -# Use GNU gettext -source gettext.sh -export TEXTDOMAIN="network-repair" -export TEXTDOMAINDIR="/usr/share/locale" - -# Usage -echo "$(gettext "Checking network interfaces...")" -echo "$(eval_gettext "Found \$count interfaces")" -``` - -**Pros**: Industry standard, tool support -**Cons**: External dependency, slower - -#### Option 2: Custom PO Files - -```bash -# Parse .po files in bash -load_translations() { - local locale="$1" - local po_file="locales/${locale}/LC_MESSAGES/common.po" - - # Parse and cache - while IFS= read -r line; do - # msgid "key" - # msgstr "translation" - # ... - done < "${po_file}" -} -``` - -**Pros**: No external dependencies -**Cons**: Custom parser, more maintenance - -#### Option 3: JSON Messages - -```bash -# Use jq for JSON parsing -t() { - local key="$1" - local locale="${LANG:-en_US}" - - jq -r ".${key} // \"${key}\"" \ - "locales/${locale}/messages.json" -} -``` - -**Pros**: Easy to parse, readable format -**Cons**: Requires jq dependency - -### Recommended Approach - -**Hybrid**: JSON for simplicity, with gettext compatibility - -```bash -# messages.json -{ - "network.check.start": "Checking network configuration...", - "network.check.dns": "Checking DNS servers", - "error.no_interface": "No network interfaces found", - "prompt.continue": "Continue? (y/n)" -} -``` - -## Translation Workflow - -### For Translators - -1. **Join Translation Team** - - Open issue: "Translation: [Language]" - - Get added to translators team - -2. **Clone Repository** - ```bash - git clone https://github.com/Hyperpolymath/complete-linux-internet-repair - cd complete-linux-internet-repair - ``` - -3. **Create Language Directory** - ```bash - mkdir -p locales/es_ES/LC_MESSAGES - cp locales/en_US/LC_MESSAGES/*.po locales/es_ES/LC_MESSAGES/ - ``` - -4. **Translate** - - Edit .po files with Poedit or text editor - - Test translations: `LANG=es_ES ./network-repair diagnose` - - Submit PR - -5. **Maintenance** - - Watch for new strings (CI notifies) - - Update translations in follow-up PRs - -### For Developers - -1. **Extract Strings** - ```bash - # Run extraction tool (planned) - just extract-strings - - # Updates locales/en_US/LC_MESSAGES/*.pot (template) - ``` - -2. **Mark Translatable Strings** - ```bash - # Instead of: - echo "Checking DNS..." - - # Use: - echo "$(t 'dns.check.start')" - ``` - -3. **Test Translations** - ```bash - # Test Spanish - LANG=es_ES ./network-repair diagnose - - # Test French - LANG=fr_FR ./network-repair --help - ``` - -## Cultural Considerations - -### Date and Time - -```bash -# Locale-aware date formatting -format_date() { - local timestamp="$1" - local locale="${LANG:-en_US}" - - case "${locale}" in - en_US) - date -d "@${timestamp}" "+%m/%d/%Y %I:%M %p" - ;; - en_GB) - date -d "@${timestamp}" "+%d/%m/%Y %H:%M" - ;; - ja_JP) - date -d "@${timestamp}" "+%Y年%m月%d日 %H:%M" - ;; - *) - date -d "@${timestamp}" "+%Y-%m-%d %H:%M" - ;; - esac -} -``` - -### Network Examples - -```bash -# Different countries use different private IP ranges -get_example_ip() { - local locale="${LANG:-en_US}" - - case "${locale}" in - en_US) - echo "192.168.1.100" - ;; - ja_JP) - echo "192.168.0.100" # More common in Japan - ;; - *) - echo "192.168.1.100" - ;; - esac -} -``` - -### Terminology - -| English | Spanish | French | German | Notes | -|---------|---------|--------|--------|-------| -| Network Interface | Interfaz de Red | Interface Réseau | Netzwerkschnittstelle | - | -| Gateway | Puerta de Enlace | Passerelle | Gateway | German uses English | -| DNS Server | Servidor DNS | Serveur DNS | DNS-Server | - | -| Routing Table | Tabla de Enrutamiento | Table de Routage | Routing-Tabelle | - | - -## Testing Translations - -### Manual Testing - -```bash -# Test each language -for lang in en_US es_ES fr_FR de_DE; do - echo "Testing ${lang}..." - LANG=${lang} ./network-repair diagnose -done -``` - -### Automated Testing - -```bash -# Planned: Translation completeness check -just check-translations - -# Output: -# en_US: 100% (245/245) -# es_ES: 98% (240/245) - 5 missing -# fr_FR: 85% (208/245) - 37 missing -``` - -## Translation Style Guide - -### Tone - -- **Professional but friendly** -- **Clear and direct** -- **Avoid idioms** (don't translate directly) -- **Technical accuracy** over literal translation - -### Format - -- **Preserve placeholders**: `%s`, `${var}`, `$count` -- **Maintain line breaks**: Keep `\n` where they appear -- **Keep punctuation**: Match source language style -- **Preserve formatting**: `*bold*`, `_italic_`, etc. - -### Examples - -**Good Translation**: -```po -msgid "Checking network interface %s" -msgstr "Comprobando interfaz de red %s" -``` - -**Bad Translation**: -```po -msgid "Checking network interface %s" -msgstr "Comprobando %s interfaz de red" # Wrong placeholder order -``` - -## Contribution Recognition - -### Translation Credits - -Translators will be credited in: - -1. **humans.txt**: Translator section -2. **CHANGELOG.md**: Translation additions -3. **GitHub contributors**: Automatic via commits -4. **Language metadata.json**: Translator names per language - -### Translation Teams - -| Language | Lead Translator | Contributors | Status | -|----------|----------------|--------------|--------| -| en_US | Project Team | - | Complete | -| es_ES | *Seeking* | - | Planned | -| fr_FR | *Seeking* | - | Planned | -| de_DE | *Seeking* | - | Planned | - -## Resources - -### Tools - -- **Poedit**: https://poedit.net/ (PO file editor) -- **Lokalize**: https://apps.kde.org/lokalize/ (KDE translator) -- **Weblate**: https://weblate.org/ (Web-based translation) -- **Transifex**: https://www.transifex.com/ (Translation platform) - -### References - -- **GNU gettext**: https://www.gnu.org/software/gettext/ -- **Bash i18n**: https://mywiki.wooledge.org/BashFAQ/098 -- **POSIX locale**: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/V1_chap07.html - -## Timeline - -| Version | Milestone | Target Date | -|---------|-----------|-------------| -| v1.0 | English only | 2025-01 ✅ | -| v1.1 | i18n framework | 2025-03 | -| v1.2 | 3 languages (es, fr, de) | 2025-06 | -| v1.3 | 7 languages (+ pt, ja, zh, ru) | 2025-09 | -| v1.4 | Community languages | 2025-12 | - -## Get Involved - -Want to help translate? - -1. **Check existing translations**: See what's needed -2. **Open an issue**: "Translation: [Your Language]" -3. **Join the team**: We'll add you to translators -4. **Start translating**: Follow workflow above -5. **Submit PR**: We review and merge - -All translation contributors welcome, regardless of skill level! - ---- - -**Last Updated**: 2025-01-22 -**Version**: 1.0 (planning document) -**Contact**: i18n@example.com diff --git a/docs/tech-debt-2026-05-26.adoc b/docs/tech-debt-2026-05-26.adoc new file mode 100644 index 0000000..8c19095 --- /dev/null +++ b/docs/tech-debt-2026-05-26.adoc @@ -0,0 +1,71 @@ +== Tech-Debt Audit — network-ambulance — 2026-05-26 + +*Source:* estate-wide automated scan 2026-05-26. *Companion:* +https://github.com/hyperpolymath/standards/tree/main/docs/audits[`+hyperpolymath/standards+` +2026-05-26-estate-*-debt audits]. *Combined severity:* `+LOW+`. + +This file records the _raw findings_ — it does not by itself fix the +debt. Each section ends with a '`Recommended next move`' line; closing +the debt is follow-up work. + +=== 1. Proof debt + +No proof-bearing files (`+*.v+`, `+*.lean+`, `+*.agda+`, `+*.idr+`, +`+*.idr2+`, `+*.fst+`, `+*.dfy+`, `+*.tla+`, `+*.ads+`, `+*.adb+`) found +in this repo. + +*Recommended next move:* none. + +=== 2. Licence debt + +[cols=",",options="header",] +|=== +|Field |Value +|LICENSE file |`+LICENSE+` +|SPDX header |`+MPL-2.0+` +|Manifest licence |`+NONE+` +|Body classifier |`+MPL-some+` +|Severity |`+ok+` +|=== + +*Recommended next move:* none for licence. + +=== 3. Documentation debt + +[cols=",",options="header",] +|=== +|Field |Value +|README lines |674 +|`+docs/+` files |12 +|`+docs/+` LoC |8678 +|CHANGELOG.md |N +|CONTRIBUTING.md |Y +|CODE_OF_CONDUCT.md |Y +|SECURITY.md |Y +|Severity |`+LOW+` +|=== + +*Recommended next move:* `+docs/+` has only 12 file(s). Aim for ≥10 +organised docs (architecture, usage, contributing-guide, +troubleshooting, design-decisions). The user’s bar for a +"`heavily-developed and well-organised wiki`" is ≥10 files with topical +organisation. + +Additionally: *CHANGELOG.md is missing.* 65% of estate repos lack one — +adopting a CHANGELOG (or auto-generating via `+git-cliff+`) is a +recommended estate-wide follow-up. + +=== Cross-references + +* Estate proof-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md+` +* Estate licence-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md+` +* Estate documentation-debt audit: +`+hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md+` + +''''' + +🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). +This file is informational — closing the debt is follow-up work owned by +the maintainer. diff --git a/docs/tech-debt-2026-05-26.md b/docs/tech-debt-2026-05-26.md deleted file mode 100644 index d6ff271..0000000 --- a/docs/tech-debt-2026-05-26.md +++ /dev/null @@ -1,57 +0,0 @@ - - -# Tech-Debt Audit — network-ambulance — 2026-05-26 - -**Source:** estate-wide automated scan 2026-05-26. -**Companion:** [`hyperpolymath/standards` 2026-05-26-estate-*-debt audits](https://github.com/hyperpolymath/standards/tree/main/docs/audits). -**Combined severity:** `LOW`. - -This file records the *raw findings* — it does not by itself fix the debt. Each section ends with a 'Recommended next move' line; closing the debt is follow-up work. - -## 1. Proof debt - -No proof-bearing files (`*.v`, `*.lean`, `*.agda`, `*.idr`, `*.idr2`, `*.fst`, `*.dfy`, `*.tla`, `*.ads`, `*.adb`) found in this repo. - -**Recommended next move:** none. - -## 2. Licence debt - -| Field | Value | -|---|---| -| LICENSE file | `LICENSE` | -| SPDX header | `MPL-2.0` | -| Manifest licence | `NONE` | -| Body classifier | `MPL-some` | -| Severity | `ok` | - -**Recommended next move:** none for licence. - -## 3. Documentation debt - -| Field | Value | -|---|---| -| README lines | 674 | -| `docs/` files | 12 | -| `docs/` LoC | 8678 | -| CHANGELOG.md | N | -| CONTRIBUTING.md | Y | -| CODE_OF_CONDUCT.md | Y | -| SECURITY.md | Y | -| Severity | `LOW` | - -**Recommended next move:** `docs/` has only 12 file(s). Aim for ≥10 organised docs (architecture, usage, contributing-guide, troubleshooting, design-decisions). The user's bar for a "heavily-developed and well-organised wiki" is ≥10 files with topical organisation. - -Additionally: **CHANGELOG.md is missing.** 65% of estate repos lack one — adopting a CHANGELOG (or auto-generating via `git-cliff`) is a recommended estate-wide follow-up. - -## Cross-references - -- Estate proof-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-proof-debt.md` -- Estate licence-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-licence-debt.md` -- Estate documentation-debt audit: `hyperpolymath/standards/docs/audits/2026-05-26-estate-documentation-debt.md` - ---- - -🤖 Generated by Claude Code estate-wide tech-debt scan (2026-05-26). This file is informational — closing the debt is follow-up work owned by the maintainer. diff --git a/docs/troubleshooting.md b/docs/troubleshooting.adoc similarity index 55% rename from docs/troubleshooting.md rename to docs/troubleshooting.adoc index 6612012..828a652 100644 --- a/docs/troubleshooting.md +++ b/docs/troubleshooting.adoc @@ -1,30 +1,35 @@ -# Troubleshooting Guide +== Troubleshooting Guide -This guide helps you troubleshoot issues with the Complete Linux Internet Repair Tool itself, as well as common network problems. +This guide helps you troubleshoot issues with the Complete Linux +Internet Repair Tool itself, as well as common network problems. -## Tool Issues +=== Tool Issues -### Installation Problems +==== Installation Problems -#### Permission Denied During Installation +===== Permission Denied During Installation -**Problem:** `install.sh` fails with permission errors +*Problem:* `+install.sh+` fails with permission errors -**Solution:** -```bash +*Solution:* + +[source,bash] +---- # Make sure you're running with sudo sudo ./install.sh # Check that install.sh is executable chmod +x install.sh -``` +---- + +===== Command Not Found After Installation -#### Command Not Found After Installation +*Problem:* `+network-repair: command not found+` -**Problem:** `network-repair: command not found` +*Solution:* -**Solution:** -```bash +[source,bash] +---- # Check if symlink was created ls -l /usr/local/bin/network-repair @@ -33,16 +38,18 @@ sudo ln -sf /opt/network-repair/network-repair /usr/local/bin/network-repair # Or run directly /opt/network-repair/network-repair diagnose -``` +---- + +==== Runtime Issues -### Runtime Issues +===== Script Syntax Errors -#### Script Syntax Errors +*Problem:* `+bash: syntax error near unexpected token+` -**Problem:** `bash: syntax error near unexpected token` +*Solution:* -**Solution:** -```bash +[source,bash] +---- # Ensure you're using Bash 4.0+ bash --version @@ -52,32 +59,36 @@ sudo apt-get update && sudo apt-get install bash # RHEL/Fedora: sudo dnf upgrade bash -``` +---- -#### Module Not Found +===== Module Not Found -**Problem:** `source: file not found` +*Problem:* `+source: file not found+` -**Solution:** -```bash +*Solution:* + +[source,bash] +---- # Check installation directory structure ls -R /opt/network-repair/ # Reinstall if files are missing cd /path/to/source sudo ./install.sh -``` +---- + +=== Network Issues -## Network Issues +==== DNS Problems -### DNS Problems +===== DNS Resolution Fails After Repair -#### DNS Resolution Fails After Repair +*Problem:* DNS still not working after running `+repair-dns+` -**Problem:** DNS still not working after running `repair-dns` +*Diagnosis:* -**Diagnosis:** -```bash +[source,bash] +---- # Check resolv.conf cat /etc/resolv.conf @@ -86,46 +97,58 @@ dig @8.8.8.8 google.com # Check if systemd-resolved is interfering systemctl status systemd-resolved -``` +---- -**Solutions:** +*Solutions:* -1. **Manually set DNS:** -```bash +[arabic] +. *Manually set DNS:* + +[source,bash] +---- # Edit resolv.conf sudo nano /etc/resolv.conf # Add these lines: nameserver 8.8.8.8 nameserver 8.8.4.4 -``` +---- + +[arabic, start=2] +. *Restart DNS services:* -2. **Restart DNS services:** -```bash +[source,bash] +---- # Restart systemd-resolved sudo systemctl restart systemd-resolved # Flush DNS cache sudo resolvectl flush-caches -``` +---- + +[arabic, start=3] +. *Check if resolv.conf is immutable:* -3. **Check if resolv.conf is immutable:** -```bash +[source,bash] +---- # Check attributes lsattr /etc/resolv.conf # Remove immutable flag if set sudo chattr -i /etc/resolv.conf -``` +---- -#### Resolv.conf Keeps Getting Overwritten +===== Resolv.conf Keeps Getting Overwritten -**Problem:** DNS configuration reverts after reboot +*Problem:* DNS configuration reverts after reboot -**Solutions:** +*Solutions:* -1. **For systemd-resolved:** -```bash +[arabic] +. *For systemd-resolved:* + +[source,bash] +---- # Configure systemd-resolved sudo mkdir -p /etc/systemd/resolved.conf.d sudo nano /etc/systemd/resolved.conf.d/dns.conf @@ -137,10 +160,13 @@ FallbackDNS=1.1.1.1 1.0.0.1 # Restart sudo systemctl restart systemd-resolved -``` +---- + +[arabic, start=2] +. *For NetworkManager:* -2. **For NetworkManager:** -```bash +[source,bash] +---- # Get connection name nmcli connection show @@ -148,22 +174,27 @@ nmcli connection show sudo nmcli connection modify "Your-Connection" ipv4.dns "8.8.8.8 8.8.4.4" sudo nmcli connection modify "Your-Connection" ipv4.ignore-auto-dns yes sudo nmcli connection up "Your-Connection" -``` +---- -3. **Make resolv.conf immutable:** -```bash +[arabic, start=3] +. *Make resolv.conf immutable:* + +[source,bash] +---- # After setting correct DNS sudo chattr +i /etc/resolv.conf -``` +---- + +==== Interface Problems -### Interface Problems +===== Interface Won’t Come Up -#### Interface Won't Come Up +*Problem:* `+repair-network+` fails to bring up interface -**Problem:** `repair-network` fails to bring up interface +*Diagnosis:* -**Diagnosis:** -```bash +[source,bash] +---- # Check if interface exists ip link show @@ -172,12 +203,15 @@ dmesg | grep -i network # Check if driver is loaded lsmod | grep -i network -``` +---- + +*Solutions:* -**Solutions:** +[arabic] +. *Load network driver:* -1. **Load network driver:** -```bash +[source,bash] +---- # Find your network card lspci | grep -i network @@ -186,96 +220,121 @@ sudo modprobe e1000 # Make permanent echo "e1000" | sudo tee -a /etc/modules -``` +---- -2. **Check for hardware issues:** -```bash +[arabic, start=2] +. *Check for hardware issues:* + +[source,bash] +---- # Test with ethtool sudo ethtool eth0 # Check link status cat /sys/class/net/eth0/carrier -``` +---- + +[arabic, start=3] +. *Reset interface:* -3. **Reset interface:** -```bash +[source,bash] +---- # Complete reset sudo ip link set eth0 down sudo ip addr flush dev eth0 sudo ip link set eth0 up sudo dhclient eth0 -``` +---- -#### No IP Address Assigned +===== No IP Address Assigned -**Problem:** Interface is up but has no IP +*Problem:* Interface is up but has no IP -**Diagnosis:** -```bash +*Diagnosis:* + +[source,bash] +---- # Check DHCP client ps aux | grep dhclient # Check DHCP logs sudo journalctl -u NetworkManager | grep -i dhcp -``` +---- + +*Solutions:* -**Solutions:** +[arabic] +. *Manually request DHCP:* -1. **Manually request DHCP:** -```bash +[source,bash] +---- # Release current lease sudo dhclient -r eth0 # Request new lease sudo dhclient -v eth0 -``` +---- + +[arabic, start=2] +. *Try different DHCP client:* -2. **Try different DHCP client:** -```bash +[source,bash] +---- # Install dhcpcd sudo apt-get install dhcpcd5 # Use it sudo dhcpcd eth0 -``` +---- -3. **Static IP (if DHCP fails):** -```bash +[arabic, start=3] +. *Static IP (if DHCP fails):* + +[source,bash] +---- # Add static IP temporarily sudo ip addr add 192.168.1.100/24 dev eth0 sudo ip route add default via 192.168.1.1 -``` +---- + +==== Routing Problems -### Routing Problems +===== No Default Gateway -#### No Default Gateway +*Problem:* No route to internet -**Problem:** No route to internet +*Diagnosis:* -**Diagnosis:** -```bash +[source,bash] +---- # Check routing table ip route show # Check if gateway is reachable ping -c 3 192.168.1.1 # Replace with your gateway -``` +---- -**Solutions:** +*Solutions:* -1. **Add default route manually:** -```bash +[arabic] +. *Add default route manually:* + +[source,bash] +---- # Find your gateway ip route | grep default # Add default route sudo ip route add default via 192.168.1.1 dev eth0 -``` +---- -2. **Make it permanent:** +[arabic, start=2] +. *Make it permanent:* For Ubuntu with Netplan: -```yaml + +[source,yaml] +---- # /etc/netplan/01-netcfg.yaml network: version: 2 @@ -286,19 +345,23 @@ network: gateway4: 192.168.1.1 nameservers: addresses: [8.8.8.8, 8.8.4.4] -``` +---- Apply: -```bash + +[source,bash] +---- sudo netplan apply -``` +---- -#### Multiple Default Routes +===== Multiple Default Routes -**Problem:** Conflicting default routes +*Problem:* Conflicting default routes -**Solution:** -```bash +*Solution:* + +[source,bash] +---- # List all default routes ip route show default @@ -307,40 +370,46 @@ sudo ip route del default via 192.168.1.1 dev eth0 # Keep only the correct one sudo ip route add default via 192.168.1.1 dev eth1 metric 100 -``` +---- + +==== Connectivity Problems -### Connectivity Problems +===== Can Ping IP but Not Domain Names -#### Can Ping IP but Not Domain Names +*Problem:* `+ping 8.8.8.8+` works but `+ping google.com+` fails -**Problem:** `ping 8.8.8.8` works but `ping google.com` fails +*This is a DNS issue.* -**This is a DNS issue.** +*Solution:* -**Solution:** -```bash +[source,bash] +---- # Repair DNS sudo network-repair repair-dns # Or manually fix echo "nameserver 8.8.8.8" | sudo tee /etc/resolv.conf -``` +---- -#### Can Reach Gateway but Not Internet +===== Can Reach Gateway but Not Internet -**Problem:** `ping 192.168.1.1` works but `ping 8.8.8.8` fails +*Problem:* `+ping 192.168.1.1+` works but `+ping 8.8.8.8+` fails -**Diagnosis:** -```bash +*Diagnosis:* + +[source,bash] +---- # Trace route traceroute 8.8.8.8 # Check if NAT/firewall is blocking sudo iptables -L -n -v -``` +---- + +*Solution:* -**Solution:** -```bash +[source,bash] +---- # May be ISP issue, check with router/modem # Or firewall issue sudo network-repair diagnose-firewall @@ -349,14 +418,16 @@ sudo network-repair diagnose-firewall sudo ufw disable # or sudo iptables -F -``` +---- + +===== High Latency/Packet Loss -#### High Latency/Packet Loss +*Problem:* Network is slow or unreliable -**Problem:** Network is slow or unreliable +*Diagnosis:* -**Diagnosis:** -```bash +[source,bash] +---- # Check latency ping -c 10 8.8.8.8 @@ -365,72 +436,89 @@ ip -s link show eth0 # Check for duplex mismatch sudo ethtool eth0 | grep -i duplex -``` +---- -**Solutions:** +*Solutions:* -1. **Check MTU:** -```bash +[arabic] +. *Check MTU:* + +[source,bash] +---- # Test MTU ping -M do -s 1472 8.8.8.8 # Adjust MTU if needed sudo ip link set eth0 mtu 1400 -``` +---- + +[arabic, start=2] +. *Check for interference (wireless):* -2. **Check for interference (wireless):** -```bash +[source,bash] +---- # Scan for networks sudo iwlist wlan0 scan | grep -i channel # Change channel sudo iwconfig wlan0 channel 6 -``` +---- -### NetworkManager Issues +==== NetworkManager Issues -#### NetworkManager Not Starting +===== NetworkManager Not Starting -**Problem:** `systemctl status NetworkManager` shows failed +*Problem:* `+systemctl status NetworkManager+` shows failed -**Diagnosis:** -```bash +*Diagnosis:* + +[source,bash] +---- # Check logs sudo journalctl -u NetworkManager -n 50 # Check configuration sudo NetworkManager --print-config -``` +---- + +*Solutions:* -**Solutions:** +[arabic] +. *Fix configuration:* -1. **Fix configuration:** -```bash +[source,bash] +---- # Check config syntax sudo nano /etc/NetworkManager/NetworkManager.conf # Restart sudo systemctl restart NetworkManager -``` +---- + +[arabic, start=2] +. *Conflict with other network managers:* -2. **Conflict with other network managers:** -```bash +[source,bash] +---- # Stop conflicting services sudo systemctl stop systemd-networkd sudo systemctl disable systemd-networkd # Restart NetworkManager sudo systemctl restart NetworkManager -``` +---- -#### Connection Keeps Disconnecting +===== Connection Keeps Disconnecting -**Problem:** NetworkManager connection drops frequently +*Problem:* NetworkManager connection drops frequently -**Solutions:** +*Solutions:* -1. **Disable power management (for wireless):** -```bash +[arabic] +. *Disable power management (for wireless):* + +[source,bash] +---- # Check power management iwconfig wlan0 | grep "Power Management" @@ -441,35 +529,43 @@ sudo iwconfig wlan0 power off echo "#!/bin/bash" | sudo tee /etc/pm/power.d/wireless echo "iwconfig wlan0 power off" | sudo tee -a /etc/pm/power.d/wireless sudo chmod +x /etc/pm/power.d/wireless -``` +---- + +[arabic, start=2] +. *Increase connection timeout:* -2. **Increase connection timeout:** -```bash +[source,bash] +---- # Edit connection nmcli connection modify "Your-Connection" connection.auth-retries 5 nmcli connection modify "Your-Connection" ipv4.dhcp-timeout 90 -``` +---- -## Firewall Issues +=== Firewall Issues -### Tool Can't Check Firewall +==== Tool Can’t Check Firewall -**Problem:** Permission denied when checking firewall +*Problem:* Permission denied when checking firewall -**Solution:** -```bash +*Solution:* + +[source,bash] +---- # Run with sudo sudo network-repair diagnose-firewall -``` +---- + +==== Firewall Blocking Internet -### Firewall Blocking Internet +*Problem:* Firewall rules blocking legitimate traffic -**Problem:** Firewall rules blocking legitimate traffic +*Solutions:* -**Solutions:** +[arabic] +. *Check UFW:* -1. **Check UFW:** -```bash +[source,bash] +---- # Check status sudo ufw status verbose @@ -478,10 +574,13 @@ sudo ufw default allow outgoing # Or disable temporarily sudo ufw disable -``` +---- + +[arabic, start=2] +. *Check iptables:* -2. **Check iptables:** -```bash +[source,bash] +---- # List rules sudo iptables -L -n -v @@ -490,15 +589,16 @@ sudo iptables -P OUTPUT ACCEPT # Or flush all rules (CAUTION!) sudo iptables -F -``` +---- -## Recovery +=== Recovery -### Restore from Backup +==== Restore from Backup If repairs made things worse: -```bash +[source,bash] +---- # List backups ls -lt ~/.network-repair-backups/ @@ -507,13 +607,14 @@ sudo cp ~/.network-repair-backups/resolv.conf.TIMESTAMP /etc/resolv.conf # Restart networking sudo systemctl restart NetworkManager -``` +---- -### Complete Network Reset +==== Complete Network Reset Last resort: -```bash +[source,bash] +---- # Stop all network services sudo systemctl stop NetworkManager sudo systemctl stop systemd-networkd @@ -526,61 +627,67 @@ sudo iptables -F # Start fresh sudo systemctl start NetworkManager sudo network-repair --auto-repair repair -``` +---- -## Getting Help +=== Getting Help If problems persist: -1. **Gather information:** -```bash +[arabic] +. *Gather information:* + +[source,bash] +---- # Create diagnostic report network-repair --verbose diagnose > /tmp/network-report.txt 2>&1 # Add system info uname -a >> /tmp/network-report.txt cat /etc/os-release >> /tmp/network-report.txt -``` +---- + +[arabic, start=2] +. *Check logs:* -2. **Check logs:** -```bash +[source,bash] +---- # NetworkManager logs sudo journalctl -u NetworkManager -n 100 # System logs sudo journalctl -xe -``` +---- -3. **Open an issue:** - - Include the diagnostic report - - Describe what you were trying to do - - Mention your distribution and version - - Share any error messages +[arabic, start=3] +. *Open an issue:* +* Include the diagnostic report +* Describe what you were trying to do +* Mention your distribution and version +* Share any error messages -## Common Error Messages +=== Common Error Messages -### "No primary interface found" +==== "`No primary interface found`" -**Cause:** No network interface has a default route +*Cause:* No network interface has a default route -**Fix:** `sudo network-repair repair-network` +*Fix:* `+sudo network-repair repair-network+` -### "DNS resolution is not working" +==== "`DNS resolution is not working`" -**Cause:** DNS servers not configured or not responding +*Cause:* DNS servers not configured or not responding -**Fix:** `sudo network-repair repair-dns` +*Fix:* `+sudo network-repair repair-dns+` -### "Gateway is not reachable" +==== "`Gateway is not reachable`" -**Cause:** Routing issue or disconnected network +*Cause:* Routing issue or disconnected network -**Fix:** -1. Check physical connection -2. `sudo network-repair repair-routing` +*Fix:* 1. Check physical connection 2. +`+sudo network-repair repair-routing+` -### "NetworkManager is not active" +==== "`NetworkManager is not active`" -**Cause:** NetworkManager service not running +*Cause:* NetworkManager service not running -**Fix:** `sudo systemctl start NetworkManager` +*Fix:* `+sudo systemctl start NetworkManager+` diff --git a/examples/advanced-usage.md b/examples/advanced-usage.adoc similarity index 85% rename from examples/advanced-usage.md rename to examples/advanced-usage.adoc index 5d89590..e73a3f8 100644 --- a/examples/advanced-usage.md +++ b/examples/advanced-usage.adoc @@ -1,22 +1,25 @@ -# Advanced Usage Examples +== Advanced Usage Examples -This document provides advanced usage examples and integration scenarios. +This document provides advanced usage examples and integration +scenarios. -## Custom Diagnostic Workflows +=== Custom Diagnostic Workflows -### Selective Diagnostics +==== Selective Diagnostics -```bash +[source,bash] +---- #!/bin/bash # Run only network-related diagnostics network-repair diagnose-network network-repair diagnose-routing -``` +---- -### Conditional Repairs +==== Conditional Repairs -```bash +[source,bash] +---- #!/bin/bash # Repair based on specific conditions @@ -31,13 +34,14 @@ if ! ping -c 3 8.8.8.8 >/dev/null 2>&1; then echo "Connectivity issues detected" sudo network-repair repair-all fi -``` +---- -## Integration Examples +=== Integration Examples -### Pre-deployment Network Check +==== Pre-deployment Network Check -```bash +[source,bash] +---- #!/bin/bash # Ensure network is working before deployment @@ -67,11 +71,12 @@ fi echo "Network is healthy. Proceeding with deployment..." # Continue with deployment -``` +---- -### Monitoring Script +==== Monitoring Script -```bash +[source,bash] +---- #!/bin/bash # Continuous network monitoring with repair @@ -100,11 +105,12 @@ while true; do sleep ${CHECK_INTERVAL} done -``` +---- -### Docker Container Network Repair +==== Docker Container Network Repair -```dockerfile +[source,dockerfile] +---- # Dockerfile FROM ubuntu:22.04 @@ -120,19 +126,21 @@ RUN chmod +x /opt/network-repair/network-repair ENTRYPOINT ["/opt/network-repair/network-repair"] CMD ["diagnose"] -``` +---- -```bash +[source,bash] +---- # Build and run docker build -t network-repair . docker run --rm --network host --cap-add=NET_ADMIN network-repair diagnose -``` +---- -## Custom DNS Configuration +=== Custom DNS Configuration -### Using Specific DNS Servers +==== Using Specific DNS Servers -```bash +[source,bash] +---- #!/bin/bash # Configure custom DNS servers @@ -147,11 +155,12 @@ DEFAULT_DNS_SERVERS="9.9.9.9 149.112.112.112" sudo network-repair repair-dns # Use multiple providers DEFAULT_DNS_SERVERS="8.8.8.8 1.1.1.1 9.9.9.9" sudo network-repair repair-dns -``` +---- -### Corporate Network DNS +==== Corporate Network DNS -```bash +[source,bash] +---- #!/bin/bash # Use corporate DNS servers @@ -163,13 +172,14 @@ sudo -E network-repair repair-dns # Verify dig @10.0.0.1 internal.corp.example.com -``` +---- -## Multi-Interface Scenarios +=== Multi-Interface Scenarios -### Prioritize Specific Interface +==== Prioritize Specific Interface -```bash +[source,bash] +---- #!/bin/bash # Ensure specific interface is primary @@ -187,11 +197,12 @@ sudo ip route add default via "${GATEWAY}" dev "${PRIMARY_INTERFACE}" # Verify network-repair diagnose-routing -``` +---- -### Bonding/Teaming Setup Check +==== Bonding/Teaming Setup Check -```bash +[source,bash] +---- #!/bin/bash # Verify bonded interface configuration @@ -209,13 +220,14 @@ cat /proc/net/bonding/"${BOND_INTERFACE}" # Run diagnostics network-repair diagnose-network network-repair diagnose-routing -``` +---- -## VPN Integration +=== VPN Integration -### Pre-VPN Connection Check +==== Pre-VPN Connection Check -```bash +[source,bash] +---- #!/bin/bash # Ensure network is working before VPN connection @@ -229,11 +241,12 @@ fi # Connect to VPN echo "Connecting to VPN..." sudo openvpn --config /etc/openvpn/client.conf -``` +---- -### Post-VPN Diagnostics +==== Post-VPN Diagnostics -```bash +[source,bash] +---- #!/bin/bash # Verify network after VPN connection @@ -256,13 +269,14 @@ else sudo killall openvpn sudo network-repair repair-all fi -``` +---- -## Ansible Integration +=== Ansible Integration -### Playbook Example +==== Playbook Example -```yaml +[source,yaml] +---- --- - name: Ensure network connectivity hosts: all @@ -289,13 +303,14 @@ fi command: ping -c 3 8.8.8.8 register: ping_result failed_when: ping_result.rc != 0 -``` +---- -## Systemd Integration +=== Systemd Integration -### Network Repair Service +==== Network Repair Service -```ini +[source,ini] +---- # /etc/systemd/system/network-repair.service [Unit] Description=Network Repair Service @@ -312,11 +327,12 @@ StandardError=journal [Install] WantedBy=multi-user.target -``` +---- -### Network Repair Timer +==== Network Repair Timer -```ini +[source,ini] +---- # /etc/systemd/system/network-repair.timer [Unit] Description=Network Repair Timer @@ -329,20 +345,23 @@ AccuracySec=1min [Install] WantedBy=timers.target -``` +---- Enable: -```bash + +[source,bash] +---- sudo systemctl enable network-repair.timer sudo systemctl start network-repair.timer sudo systemctl status network-repair.timer -``` +---- -## Logging and Alerting +=== Logging and Alerting -### Advanced Logging +==== Advanced Logging -```bash +[source,bash] +---- #!/bin/bash # Comprehensive logging setup @@ -360,11 +379,12 @@ sudo -E network-repair diagnose 2>&1 | tee -a "${LOG_FILE}" # Rotate logs find /var/log/network-repair -name "repair-*.log" -mtime +30 -delete -``` +---- -### Email Alerts +==== Email Alerts -```bash +[source,bash] +---- #!/bin/bash # Email alerts on network issues @@ -384,11 +404,12 @@ if ! network-repair diagnose > /tmp/network-diag.txt 2>&1; then fi rm -f /tmp/network-diag.txt /tmp/network-repair.txt -``` +---- -### Slack/Discord Notifications +==== Slack/Discord Notifications -```bash +[source,bash] +---- #!/bin/bash # Send notifications to Slack @@ -411,13 +432,14 @@ if ! network-repair diagnose; then send_slack_message "❌ Failed to repair network on $(hostname)" fi fi -``` +---- -## Testing and Development +=== Testing and Development -### Test in Virtual Machine +==== Test in Virtual Machine -```bash +[source,bash] +---- #!/bin/bash # Create test environment in VM @@ -430,11 +452,12 @@ sudo network-repair --auto-repair repair # Verify fix ping -c 3 google.com -``` +---- -### Simulate Network Issues +==== Simulate Network Issues -```bash +[source,bash] +---- #!/bin/bash # Test script - simulates various network issues @@ -458,6 +481,8 @@ sudo network-repair repair-routing # Cleanup echo "Test complete" -``` +---- -This advanced usage guide demonstrates the flexibility and power of the Complete Linux Internet Repair Tool in various scenarios and environments. +This advanced usage guide demonstrates the flexibility and power of the +Complete Linux Internet Repair Tool in various scenarios and +environments. diff --git a/examples/basic-usage.md b/examples/basic-usage.adoc similarity index 73% rename from examples/basic-usage.md rename to examples/basic-usage.adoc index c7764ef..6026af4 100644 --- a/examples/basic-usage.md +++ b/examples/basic-usage.adoc @@ -1,18 +1,21 @@ -# Basic Usage Examples +== Basic Usage Examples -This document provides common usage examples for the Complete Linux Internet Repair Tool. +This document provides common usage examples for the Complete Linux +Internet Repair Tool. -## Quick Diagnostics +=== Quick Diagnostics -### Check All Network Issues +==== Check All Network Issues -```bash +[source,bash] +---- # Run complete diagnostics network-repair diagnose -``` +---- Output example: -``` + +.... === Network Interface Check === → Available network interfaces eth0 @@ -28,11 +31,12 @@ Output example: === DNS Configuration Check === → Checking /etc/resolv.conf ✓ Found 2 nameserver(s) -``` +.... -### Check Specific Issues +==== Check Specific Issues -```bash +[source,bash] +---- # Check DNS only network-repair diagnose-dns @@ -41,20 +45,22 @@ network-repair diagnose-network # Check routing only network-repair diagnose-routing -``` +---- -## Basic Repairs +=== Basic Repairs -### Auto-Repair All Issues +==== Auto-Repair All Issues -```bash +[source,bash] +---- # Diagnose and automatically repair sudo network-repair --auto-repair diagnose -``` +---- -### Repair Specific Issues +==== Repair Specific Issues -```bash +[source,bash] +---- # Fix DNS problems sudo network-repair repair-dns @@ -63,19 +69,21 @@ sudo network-repair repair-network # Fix routing problems sudo network-repair repair-routing -``` +---- -## Interactive Mode +=== Interactive Mode -### Guided Troubleshooting +==== Guided Troubleshooting -```bash +[source,bash] +---- # Launch interactive mode sudo network-repair interactive -``` +---- This provides a menu: -``` + +.... ╔═══════════════════════════════════════════════════════════╗ ║ Complete Linux Internet Repair Tool ║ ║ Interactive Guided Mode ║ @@ -91,65 +99,72 @@ What would you like to do? 6) Exit Enter choice [1-6]: -``` +.... -## Advanced Usage +=== Advanced Usage -### Verbose Output +==== Verbose Output -```bash +[source,bash] +---- # See detailed diagnostic information network-repair --verbose diagnose -``` +---- -### Dry Run +==== Dry Run -```bash +[source,bash] +---- # See what would be changed without making changes sudo network-repair --dry-run repair -``` +---- Output example: -``` + +.... [WARN] DRY RUN MODE - No changes will be made === DNS Configuration Repair === → Would add DNS servers to /etc/resolv.conf → Would restart systemd-resolved -``` +.... -### Logging to File +==== Logging to File -```bash +[source,bash] +---- # Save detailed logs network-repair --log-file /tmp/network-repair.log diagnose # View the log cat /tmp/network-repair.log -``` +---- -### Quiet Mode +==== Quiet Mode -```bash +[source,bash] +---- # Show only errors network-repair --quiet diagnose -``` +---- -## Common Scenarios +=== Common Scenarios -### Scenario 1: No Internet After System Update +==== Scenario 1: No Internet After System Update -```bash +[source,bash] +---- # Step 1: Diagnose the issue network-repair diagnose # Step 2: If DNS or routing issues found, auto-repair sudo network-repair --auto-repair diagnose -``` +---- -### Scenario 2: DNS Not Resolving +==== Scenario 2: DNS Not Resolving -```bash +[source,bash] +---- # Check DNS network-repair diagnose-dns @@ -158,11 +173,12 @@ sudo network-repair repair-dns # Verify fix ping google.com -``` +---- -### Scenario 3: Interface is Down +==== Scenario 3: Interface is Down -```bash +[source,bash] +---- # Check interfaces network-repair diagnose-network @@ -171,11 +187,12 @@ sudo network-repair repair-network # Verify ip addr show -``` +---- -### Scenario 4: No Default Route +==== Scenario 4: No Default Route -```bash +[source,bash] +---- # Check routing network-repair diagnose-routing @@ -184,11 +201,12 @@ sudo network-repair repair-routing # Verify ip route show -``` +---- -### Scenario 5: NetworkManager Issues +==== Scenario 5: NetworkManager Issues -```bash +[source,bash] +---- # Check NetworkManager network-repair diagnose-all @@ -197,29 +215,32 @@ sudo network-repair repair-all # Or use interactive mode for guided repair sudo network-repair interactive -``` +---- -## Working with Backups +=== Working with Backups -### View Backups +==== View Backups -```bash +[source,bash] +---- # List all backups ls -lh ~/.network-repair-backups/ -``` +---- -### Restore from Backup +==== Restore from Backup -```bash +[source,bash] +---- # Manually restore a backup sudo cp ~/.network-repair-backups/resolv.conf.20250122_143052 /etc/resolv.conf -``` +---- -## Configuration +=== Configuration -### Using Environment Variables +==== Using Environment Variables -```bash +[source,bash] +---- # Enable verbose mode VERBOSE=true network-repair diagnose @@ -231,13 +252,14 @@ DEFAULT_DNS_SERVERS="8.8.8.8 1.1.1.1" sudo network-repair repair-dns # Change backup directory BACKUP_DIR=/tmp/backups sudo network-repair repair -``` +---- -### Using Configuration File +==== Using Configuration File -Edit `/opt/network-repair/config/defaults.conf` (after installation): +Edit `+/opt/network-repair/config/defaults.conf+` (after installation): -```bash +[source,bash] +---- # Enable logging to file LOG_TO_FILE=true LOG_FILE=/var/log/network-repair.log @@ -247,45 +269,49 @@ VERBOSE=true # Always run in interactive mode INTERACTIVE=true -``` +---- -## Troubleshooting the Tool +=== Troubleshooting the Tool -### Permission Denied +==== Permission Denied -```bash +[source,bash] +---- # Make sure you're using sudo for repairs sudo network-repair repair # Check file permissions ls -l /opt/network-repair/ -``` +---- -### Command Not Found +==== Command Not Found -```bash +[source,bash] +---- # If not installed, run directly ./network-repair diagnose # Or install it sudo ./install.sh -``` +---- -### Getting Help +==== Getting Help -```bash +[source,bash] +---- # View help network-repair --help # View version network-repair --version -``` +---- -## Integration with Other Tools +=== Integration with Other Tools -### Using in Scripts +==== Using in Scripts -```bash +[source,bash] +---- #!/bin/bash # Example: Check network before running backup @@ -296,20 +322,22 @@ fi # Proceed with backup ./backup.sh -``` +---- -### Cron Job for Monitoring +==== Cron Job for Monitoring -```bash +[source,bash] +---- # Add to crontab: Check network every hour 0 * * * * /usr/local/bin/network-repair diagnose --quiet || /usr/local/bin/network-repair --auto-repair repair -``` +---- -### Systemd Service +==== Systemd Service -Create `/etc/systemd/system/network-repair-monitor.service`: +Create `+/etc/systemd/system/network-repair-monitor.service+`: -```ini +[source,ini] +---- [Unit] Description=Network Repair Monitor After=network-online.target @@ -321,10 +349,12 @@ ExecStartPost=/bin/sh -c 'if [ $? -ne 0 ]; then /usr/local/bin/network-repair -- [Install] WantedBy=multi-user.target -``` +---- Enable: -```bash + +[source,bash] +---- sudo systemctl enable network-repair-monitor.service sudo systemctl start network-repair-monitor.service -``` +----