testsAndMisc/docs/superpowers/evidence/install-pacman-wrapper-split-2026-08-17.json

{
  "intent": "Bring install_pacman_wrapper.sh under the 250-line cap by splitting its middle steps into a sibling lib/, without changing what the installer does to a machine and without relocating code the trace harness cannot execute.",
  "scope": [
    "linux_configuration/scripts/periodic_background/digital_wellbeing/pacman/install_pacman_wrapper.sh (316 -> 128 lines)",
    "New: pacman/lib/{managed_copy,install_files,integrity,protect_and_extras}.sh",
    "linux_configuration/tests/lib/pacman_wrapper_syntax.sh and pacman_wrapper_makepkg.sh (grep search path widened to include lib/)",
    "linux_configuration/tests/test_pacman_wrapper_security.sh (one grep repointed at lib/integrity.sh)",
    "Non-goal: any behaviour change; the trace is the assertion that there is none",
    "Non-goal: the pre-existing test_security_hardening.sh failure, which is block_compulsive_opening.sh's and fails identically at HEAD"
  ],
  "changes": [
    "Moved the managed-copy helpers, the /usr/local/bin install step, the integrity + drift-manifest step, and the immutability/LeechBlock/VirtualBox step into four sourced libs, each wrapped in a named function called in the original order.",
    "Kept the auto-sudo block, the root and wrapper-exists guards, the `if [ ! -L /usr/bin/pacman ]` backup branch, the sed -i, and everything from `ln -sf ... /usr/bin/pacman` onwards in the entry script. The harness cannot bind /usr/bin (doing so removes the directory bwrap needs to exec, killing the run), so those statements never execute under trace and a split that relocated them could not be verified.",
    "Kept the colors and all SOURCE_*/DEST_* definitions in the entry rather than a paths lib: a definitions-only lib assigns without referencing, which shellcheck reports as SC2034 on 36 variables, and the repo forbids suppressions. Libs that only REFERENCE globals are accepted, which is the shape used here. `export` would have silenced it but leaks ~40 variables into the environment of npm/sha256sum/sed/chattr children -- a behaviour change the trace cannot see.",
    "SOURCE_* vars keep `$(dirname \"$0\")` verbatim. In a sourced lib `$0` is still the entry script, but moving them to a lib and switching to ${BASH_SOURCE[0]} would have resolved into lib/ and broken HEAVY_LOCK_SOURCE's depth-sensitive ../../utils/ hop.",
    "Widened the installer source-text greps in the test libs from the entry script alone to the entry plus lib/ (grep -qr over both paths). Five assertions needed it (chattr +i, MAKEPKG_CAPPED, MKPKG, unlock_immutable_file_if_needed, and the literal sha256sum \"$LOCK_LIB_DEST\" which was repointed at lib/integrity.sh); INTEGRITY_FILE and VBOX_ENFORCE were widened too so the whole set is consistent rather than passing by coincidence of a name still appearing in the entry's path block. No assertion text or condition was weakened."
  ],
  "verification": [
    {
      "command": "meta/scripts/trace_shell_split.sh install_pacman_wrapper.sh --prefix <fresh> --bind-abs /usr/local/bin --bind-abs /usr/local/share/digital_wellbeing --bind-abs /usr/local/share/digital_wellbeing/virtualbox --bind-abs /var/lib/pacman-wrapper, run twice at HEAD",
      "result": "pass",
      "evidence": "Two consecutive HEAD runs produced byte-identical traces, establishing the baseline is deterministic: exit 1, one stubbed call (npm install), 16 files written."
    },
    {
      "command": "same trace after the split; diff against the HEAD baseline",
      "result": "pass",
      "evidence": "Empty diff. Same exit status 1 at the same ln -sf line, same stubbed call, all 16 content hashes unchanged including pacman_wrapper=548fc2b53ee4cea6 (proves sed -i still follows the copy) and source.sha256=4c928a499d437070."
    },
    {
      "command": "bash linux_configuration/tests/test_pacman_wrapper_security.sh, before and after",
      "result": "pass",
      "evidence": "Exit 0, output byte-identical to the pre-split run: all 19 numbered tests plus the lock-library and -U package-file checks. An intermediate run caught a real regression here -- TEST 9's `chattr +i` grep failed once that line moved into a lib -- which is why the search path was widened."
    },
    {
      "command": "bash linux_configuration/tests/test_security_hardening.sh, before and after",
      "result": "pass",
      "evidence": "Output byte-identical, exit 1 both times, with exactly one failure ('Compulsive block wrappers installed') that is present at HEAD and unrelated to this file."
    },
    {
      "command": "pre-commit run shellcheck --files <entry, 4 libs, 3 test files>",
      "result": "pass",
      "evidence": "Passed. This is the real gate: a bare `shellcheck -x` on the entry alone was already clean while the standalone paths lib had 36 SC2034 findings, so the entry-only check would have been a false pass."
    },
    {
      "command": "shfmt -w then shfmt -d on all touched files",
      "result": "pass",
      "evidence": "No diff. Formatting applied before verification so the tested state equals what the pre-commit hook produces."
    },
    {
      "command": "jscpd --pattern '**/*.sh' --min-lines 14 --threshold 2, at HEAD in a clean worktree and again with the split applied",
      "result": "pass",
      "evidence": "27 clones / 1.47% in both cases -- the split adds zero duplication."
    },
    {
      "command": "bash ~/utils/scripts/check_file_length.sh --all",
      "result": "pass",
      "evidence": "None of the five files appear. Entry 128, integrity 113, managed_copy 55, protect_and_extras 55, install_files 28."
    },
    {
      "command": "ls -la /usr/bin/pacman; pacman --version",
      "result": "pass",
      "evidence": "Still a symlink to /usr/local/bin/pacman_wrapper; pacman 7.1.0 responds. The harness denied the ln with EPERM, which is the positive proof the sandbox held."
    }
  ],
  "risks": [
    "Two blocks in the entry script are unproven by the trace: the `if [ ! -L /usr/bin/pacman ]` backup branch (the guard is false on this machine, since pacman is already our symlink) and everything from the ln -sf onwards. They were deliberately not moved, so the split does not change their risk, but a future split of this file must respect the same boundary.",
    "The chattr/relock helpers are proven callable, not proven correct: inside the prefix the copied files are not immutable, so is_immutable_file is false and RELock_FILES stays empty. The baseline's 'Could not make ... immutable' warnings are expected, not a defect.",
    "Eight assertions across two test libs grep the installer's source text. They now search entry+lib/, so moving a line between those files is safe, but renaming a lib or adding a second lib directory would need the same treatment."
  ],
  "rollback": [
    "git revert the commit; the entry returns to its 316-line form and pacman/lib/ disappears. The installed artifacts under /usr/local/bin are unaffected either way, since neither form was executed against the live system here.",
    "After reverting, re-run bash linux_configuration/tests/test_pacman_wrapper_security.sh -- it must print 'All Tests Passed!', since the revert restores both the moved lines and the original grep paths together."
  ]
}