Developer Utility Scripts

A collection of open-source command-line tools and shell scripts curated by Binary & Bus, Sys. for asset optimisation, static web building, and environment maintenance. Every script below is dependency-free, POSIX-compliant, and verified to run on modern Unix systems, legacy workstations, and embedded environments.

1-Bit Dither Pass (`dither-pass.sh`)

Automated ImageMagick wrapper script to convert 24-bit RGB assets into compressed Atkinson-dithered 1-bit PNGs. Accepts a directory of images and outputs optimised monochrome variants suitable for low-bandwidth delivery. Requires ImageMagick 6.x or later installed on the system PATH.

#!/bin/sh
# dither-pass.sh - Convert images to 1-bit Atkinson-dithered PNGs
# Requires: ImageMagick 6+ (convert command)
# Usage: ./dither-pass.sh <input_dir> <output_dir>

set -e

INPUT_DIR="${1:-.}"
OUTPUT_DIR="${2:-./dithered}"

if [ ! -d "$INPUT_DIR" ]; then
    echo "Error: Input directory '$INPUT_DIR' does not exist." >&2
    exit 1
fi

mkdir -p "$OUTPUT_DIR"

COUNT=0
TOTAL=$(find "$INPUT_DIR" -maxdepth 1 -type f \
    \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.bmp" \) | wc -l)

echo "dither-pass: processing $TOTAL files from $INPUT_DIR"

find "$INPUT_DIR" -maxdepth 1 -type f \
    \( -name "*.png" -o -name "*.jpg" -o -name "*.jpeg" -o -name "*.gif" -o -name "*.bmp" \) |
while read -r FILE; do
    BASENAME=$(basename "$FILE")
    NAME="${BASENAME%.*}"
    OUTFILE="$OUTPUT_DIR/${NAME}-1bit.png"

    # Step 1: Convert to greyscale
    # Step 2: Apply Atkinson dithering via remap to 2-value palette
    # Step 3: Output as indexed 1-bit PNG
    convert "$FILE" \
        -colorspace Gray \
        -dither Atkinson \
        -remap palette:2 \
        "$OUTFILE"

    ORIG_SIZE=$(wc -c < "$FILE" | tr -d ' ')
    NEW_SIZE=$(wc -c < "$OUTFILE" | tr -d ' ')
    echo "  $NAME: ${ORIG_SIZE}B -> ${NEW_SIZE}B"

    COUNT=$((COUNT + 1))
done

echo "dither-pass: complete. $TOTAL files written to $OUTPUT_DIR"

Usage: chmod +x dither-pass.sh && ./dither-pass.sh ./raw-images ./output

HTML 3.2 Lint & Size Check (`html32-check.py`)

Lightweight Python script to audit HTML 3.2 markup for structural correctness, required elements, and TCP payload budget compliance. Enforces the 14.6 KB initial packet limit defined in our System Load Time specification. Requires Python 3.6 or later with no external dependencies.

#!/usr/bin/env python3
"""html32-check.py - HTML 3.2 lint and TCP payload budget checker.

Validates HTML files for:
  - Correct DOCTYPE declaration (HTML 3.2)
  - UTF-8 charset meta tag
  - Viewport meta tag
  - lang attribute on html element
  - Required structural elements (header, nav, footer)
  - TCP payload budget (14.6 KB default)

Usage: python3 html32-check.py <file.html> [budget_kb]
"""

import sys
import re
from pathlib import Path


REQUIRED_ELEMENTS = [
    ("header", r"<header[\s>]"),
    ("nav", r"<nav[\s>]"),
    ("footer", r"<footer[\s>]"),
    ("meta charset", r'<meta charset="utf-8"[\s/]?>'),
    ("meta viewport", r'<meta name="viewport"'),
    ("DOCTYPE", r"<!DOCTYPE html>"),
    ("lang attribute", r'<html lang="'),
]

TCP_BUDGET_BYTES = 14_600


def check_file(filepath, budget_kb=None):
    path = Path(filepath)
    if not path.exists():
        print(f"ERROR: File not found: {filepath}")
        return False

    content = path.read_text(encoding="utf-8")
    file_size = path.stat().st_size
    budget = (budget_kb * 1024) if budget_kb else TCP_BUDGET_BYTES
    errors = []
    warnings = []

    # Check required elements
    for name, pattern in REQUIRED_ELEMENTS:
        if not re.search(pattern, content):
            errors.append(f"Missing required element: {name}")

    # Check file size against TCP budget
    if file_size > budget:
        errors.append(
            f"File size {file_size} bytes exceeds TCP budget of {budget} bytes"
        )
    else:
        pct = (file_size / budget) * 100
        print(f"  Payload: {file_size} / {budget} bytes ({pct:.1f}%)")

    # Check for deprecated HTML 3.2 attributes used as presentational hacks
    deprecated = [
        (r'bgcolor=', "bgcolor attribute (use CSS)"),
        (r'<font[\s>]', "font tag (use CSS)"),
        (r'<center[\s>]', "center tag (use CSS)"),
    ]
    for pattern, msg in deprecated:
        if re.search(pattern, content, re.IGNORECASE):
            warnings.append(f"Deprecated usage: {msg}")

    # Report
    print(f"Checking: {filepath}")
    print(f"  Size: {file_size} bytes")

    for w in warnings:
        print(f"  WARN: {w}")

    if errors:
        for e in errors:
            print(f"  FAIL: {e}")
        print("  RESULT: FAIL")
        return False
    else:
        print("  RESULT: PASS")
        return True


def main():
    if len(sys.argv) < 2:
        print("Usage: html32-check.py <file.html> [budget_kb]")
        sys.exit(1)

    filepath = sys.argv[1]
    budget_kb = float(sys.argv[2]) if len(sys.argv) > 2 else None

    ok = check_file(filepath, budget_kb)
    sys.exit(0 if ok else 1)


if __name__ == "__main__":
    main()

Usage: python3 html32-check.py index.html or python3 html32-check.py index.html 14.6

Static Index Generator (`mkindex.sh`)

POSIX shell script that scans a directory and generates a clean, unstyled plain-text HTML file listing for static web servers. Produces valid HTML 3.2 output with proper encoding, viewport, and semantic markup. Useful for building automatic directory indexes on servers without PHP or server-side index modules.

#!/bin/sh
# mkindex.sh - Generate a plain HTML 3.2 directory index
# Usage: ./mkindex.sh <directory> [output_file]

set -e

TARGET_DIR="${1:-.}"
OUTPUT="${2:-index.html}"

if [ ! -d "$TARGET_DIR" ]; then
    echo "Error: '$TARGET_DIR' is not a directory." >&2
    exit 1
fi

# Derive the directory name for the page title
DIR_NAME=$(basename "$(cd "$TARGET_DIR" && pwd)")

cat > "$OUTPUT" <<ENDOFFILE
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Index of ${DIR_NAME}</title>
</head>
<body>
<h1>Index of ${DIR_NAME}</h1>
<hr>
<ul>
ENDOFFILE

# List HTML files
find "$TARGET_DIR" -maxdepth 1 -type f -name "*.html" |
    sort |
while read -r FILE; do
    NAME=$(basename "$FILE")
    echo "<li><a href=\"${NAME}\">${NAME}</a></li>" >> "$OUTPUT"
done

# List other files
find "$TARGET_DIR" -maxdepth 1 -type f ! -name "*.html" |
    sort |
while read -r FILE; do
    NAME=$(basename "$FILE")
    SIZE=$(wc -c < "$FILE" | tr -d ' ')
    echo "<li>${NAME} (${SIZE} bytes)</li>" >> "$OUTPUT"
done

cat >> "$OUTPUT" <<ENDOFFILE
</ul>
<hr>
<footer>
<address>Generated by mkindex.sh</address>
</footer>
</body>
</html>
ENDOFFILE

echo "mkindex: wrote $OUTPUT ($(
    wc -c < "$OUTPUT" | tr -d ' '
) bytes)"

Usage: chmod +x mkindex.sh && ./mkindex.sh /var/www/html

Navigation & Repository Links:

Developer Utility Scripts

1-Bit Dither Pass (dither-pass.sh)

HTML 3.2 Lint & Size Check (html32-check.py)

Static Index Generator (mkindex.sh)

1-Bit Dither Pass (`dither-pass.sh`)

HTML 3.2 Lint & Size Check (`html32-check.py`)

Static Index Generator (`mkindex.sh`)