Impeccable

8 steps · start to finish.

1. 1
   Step 1

   Environment Setup

   ▶

   Ensure Node ≥ 24, resolve the impeccable CLI, and resolve the target.

   set -e
   mkdir -p {{results_dir}}
   
   # --- Node ≥ 24 ---
   NODE_MAJOR=$(node -v 2>/dev/null | sed -E 's/^v([0-9]+).*/\1/' || echo 0)
   if [ "${NODE_MAJOR:-0}" -lt 24 ]; then
     echo "Node ${NODE_MAJOR} < 24 — installing Node 24"
     curl -fsSL https://deb.nodesource.com/setup_24.x | bash - >/dev/null 2>&1 && apt-get install -y nodejs >/dev/null 2>&1 \
       || (curl -fsSL https://fnm.vercel.app/install | bash && export PATH="$HOME/.local/share/fnm:$PATH" && eval "$(fnm env)" && fnm install 24 && fnm use 24)
   fi
   echo "node: $(node -v)"
   
   # --- Resolve the impeccable detector ---
   # Primary: run straight from npm. Verify it answers before relying on it.
   if npx --yes impeccable@latest detect --help >/dev/null 2>&1; then
     IMPECCABLE="npx --yes impeccable@latest detect"
   else
     # Fallback: clone the repo pinned to a known-good SHA and run the bundled CLI.
     git clone --depth 1 https://github.com/pbakaus/impeccable /tmp/impeccable
     git -C /tmp/impeccable fetch --depth 1 origin 1aedbcf538e3fa6694ccbf00294cc18e59ba1f21 2>/dev/null || true
     IMPECCABLE="node /tmp/impeccable/cli/bin/cli.js detect"
   fi
   echo "detector: $IMPECCABLE"
   echo "$IMPECCABLE" > {{results_dir}}/.impeccable_cmd   # reused by later steps
   

   Resolve the target ({{target}}):

   # Uploaded files land in /app/assets/. Prefer an explicit {{target}}; otherwise
   # pick the first HTML-ish asset.
   TARGET="{{target}}"
   case "$TARGET" in
     http://*|https://*) : ;;                                  # URL — scanned in browser mode
     "" )                                                       # nothing passed — discover an upload
       TARGET=$(ls /app/assets/*.html /app/assets/*.htm 2>/dev/null | head -1)
       [ -z "$TARGET" ] && TARGET=$(ls /app/assets/*.{css,jsx,tsx,vue,svelte} 2>/dev/null | head -1) ;;
     /*) : ;;                                                   # absolute path
     *) [ -e "/app/assets/$TARGET" ] && TARGET="/app/assets/$TARGET" ;;
   esac
   [ -z "$TARGET" ] && { echo "ERROR: no target resolved (pass a file, dir, or URL)"; exit 1; }
   echo "$TARGET" > {{results_dir}}/.target
   echo "target: $TARGET"
   

   If no target can be resolved, fail fast and write validation_report.json with stages[0].passed=false naming the missing input.

   ---

2. 2
   Step 2

   Baseline Scan (every operation)

   ▶

   Run the detector once and capture both the findings JSON and the exit code — impeccable detect exits 2 when anti-patterns are present and 0 when the target is clean. That exit code is the ground…

3. 3
   Step 3

   Execute the Operation

   ▶

   Group the findings by rule and category, then emit the two reports.

4. 4
   Step 4

   Iterate on Errors (max 3 rounds)

   ▶

   If a step raised an error, the detector failed to run, or polish did not reach a clean re-scan:

5. 5
   Step 5

   Validate Outputs (programmatic)

   ▶

   The detector is the grader. Assemble stages and decide overall_passed:

6. 6
   Step 6

   Write Executive Summary

   ▶

   Write {{results_dir}}/summary.md with the operation, target, before/after counts, the rules resolved (polish) or found (audit), the detector exit codes, and any caveats. End with a Provenance block…

7. 7
   Step 7

   Write Validation Report

   ▶

   Write {{results_dir}}/validation_report.json:

8. 8
   Step 8

   Final Checklist (MANDATORY — do not skip)

   ▶

   echo "=== FINAL OUTPUT VERIFICATION ===" RESULTS_DIR="{{results_dir}}" OP="{{operation}}"; OP="${OP:-audit}"