path: root/todo.org

#+TITLE: ArchSetup Tasks
#+AUTHOR: Craig Jennings
#+DATE: 2026-02-14

* Archsetup Open Work

** TODO [#A] Prepare for GitHub open-source release
Remove personal info, credentials, and code quality issues before publishing.

*** TODO [#A] Remove credentials and secrets from dotfiles
- =.config/.tidal-dl.token.json= — active Tidal API token with userId
- =.config/calibre/smtp.py.json= — hex-encoded relay password, personal email mappings (family Kindle accounts)
- =.config/transmission/settings.json= — bcrypt-hashed RPC password
- =.msmtprc= — mail server credentials (gpg password references)
- =.mbsyncrc= — ProtonBridge IMAP credentials
Add all to =.gitignore=, remove from git tracking, create =.example= templates where appropriate.

*** TODO [#A] Remove/template personal information from scripts
- =archsetup= lines 2-3: personal email and website in header
- =archsetup= lines 141-146: hardcoded =git.cjennings.net= repository URLs — make configurable via conf
- =scripts/post-install.sh=: personal git repos (finances, documents, danneel-*, nextjob, etc.)
- =scripts/gitrepos.sh=: personal server URLs
- =init= line 8: hardcoded password =welcome=

*** TODO [#A] Remove/template personal info from dotfiles
- =.gitconfig=: hardcoded name, email, GitHub username
- =.config/musicpd.conf=: hardcoded =~cjennings/= paths (use =~/= instead)
- =.ssh/config=: personal host configuration
- =.config/yt-dlp/config=: personal domain reference
- =hyprland.conf= line 3: personal attribution

*** TODO [#A] Scrub git history of secrets (or start fresh)
Even after removing files, secrets remain in git history.
Options: =git filter-repo= to rewrite history, or start a fresh repo for the GitHub remote.
Recommend: fresh repo for GitHub (keep cjennings.net remote with full history).

*** TODO [#B] Remove device-specific configuration
=archsetup= lines 1458-1463: Logitech BRIO webcam udev rule — move to optional/configurable section.

*** DONE [#B] Fix unsafe sed patterns with user input
CLOSED: [2026-02-23 Sun]
Quoted =$username= in sed replacement, switched locale and wireless-regdom sed
patterns to pipe delimiter to avoid conflicts with path/encoding characters.

*** DONE [#B] Fix unsafe heredoc variable expansion
CLOSED: [2026-02-23 Sun]
Quoted =UDEVEOF= heredoc and used placeholder + sed replacement pattern (same as hyprpm hook).

*** TODO [#B] Add README.md for GitHub
Project description, features, requirements, installation instructions,
configuration guide (archsetup.conf), security considerations,
contributing guidelines (or separate CONTRIBUTING.md), and license.

*** TODO [#B] Add LICENSE file
Currently no license — must choose one before open-source release.

*** TODO [#B] Remove binary font files from repo
PragmataPro and Apple Color Emoji fonts in =dotfiles/common/.local/share/fonts/=.
Add to =.gitignore=, document font installation separately.
May have licensing issues for redistribution.

*** TODO [#B] Make claude-code installation optional
Line 1781: =curl | sh= from claude.ai — should be behind a config flag.
Not all users want AI tooling; curl-pipe-bash is a red flag for reviewers.

*** TODO [#B] Add input validation for username and paths
Variables like ~$username~, ~$source_dir~, and paths are not validated.
Special characters or malicious input could break the script or cause security issues.
Should validate inputs match expected patterns (alphanumeric, valid paths, etc.).

*** TODO [#B] Bulk shellcheck cleanup
Reviewed 2026-01-24: ~128 warnings, mostly acceptable patterns or low-priority style issues.
- SC2024 (sudo redirects) - acceptable, script runs as root
- SC2174 (mkdir -p -m) - reviewed, not a practical issue
- Various quoting warnings - high-priority ones already fixed
Focus on warnings that matter for public code review.

*** TODO [#B] Document testing process in README
Help future maintainers and contributors understand and modify test infrastructure.

*** TODO [#C] Add guard for rm -rf on constructed paths
Lines 236, 466, 905: validate directory exists and is in expected location before =rm -rf=.

*** DONE [#C] Add mountpoint check before ramdisk mount
CLOSED: [2026-02-23 Sun]
Added =mountpoint -q= guard before mount; skips with info message if already mounted.

*** TODO [#C] Improve error handling in chained commands
Line 820: three operations chained with =&&= reported as single failure.
Break into separate error-handled steps.

*** DONE [#C] Add comments on complex logic
CLOSED: [2026-02-23 Sun]
Added comments explaining wireless region locale-to-ISO3166 mapping and
archsetup clone strategy (why symlinks need user-owned repo).

*** TODO [#C] Standardize boolean comparison style
Mixed =[ "$var" = "true" ]= vs =$var= evaluation — pick one pattern.

*** TODO [#D] Replace eval with safer alternatives
Line 434: =eval "$cmd"= — use arrays or direct execution.

*** DONE [#D] Validate reserved usernames
CLOSED: [2026-02-23 Sun]
Added check against list of reserved system usernames (root, bin, daemon, sys, etc.).

** TODO [#A] Ensure sleep/suspend works on laptops
Critical functionality for laptop use - current battery drain unacceptable
**NOTE:** This applies to Framework Laptop (velox), not Framework Desktop (ratio)
Add kernel parameter: ~rtc_cmos.use_acpi_alarm=1~ (will become systemd default)
Consider: ~acpi_mask_gpe=0x1A~ for battery drain, suspend-then-hibernate config
See Framework community notes on logind.conf and sleep.conf settings

** TODO [#A] Build CI/CD pipeline that runs archsetup on every commit
Core automation infrastructure - enables continuous validation

*** TODO [#B] Investigate rlwrap not installed after archsetup run
rlwrap is declared in archsetup (Emacs Dependencies section, line 1779) but was not installed on this machine after archsetup ran. Manually installed 2026-02-06. When CI/CD is running, verify that all packages in the Emacs Dependencies section are actually installed after a full test run. May indicate a broader issue with packages being skipped silently.

** TODO [#A] Generate recovery scripts from test failures
Auto-create post-install fix scripts for failed packages - makes failures actionable

** TODO [#A] Create package inventory system
*** TODO [#A] List all packages archsetup would install (including dependencies)
*** TODO [#A] List all packages currently installed on live system
*** TODO [#A] Generate diff showing what's in archsetup vs what's on system

** TODO [#A] Establish monthly review workflow
*** TODO [#A] For packages in archsetup but not on system: determine if still needed
*** TODO [#A] For packages on system but not in archsetup: decide add or remove
*** TODO [#A] Schedule monthly package diff review

** TODO [#A] Automate the inventory comparison
Make package diff a runnable script instead of manual process

** TODO [#A] Complete security education within 3 months
Read recommended resources to make informed security decisions (see metrics for Claude suggestions)

** TODO [#A] Prevent X termination and VT switching (security risk)
If someone grabs laptop at cafe and hits ctrl+alt+backspace, they kill screensaver/X and get console access
Need to disable: ctrl+alt+backspace (zap X) and ctrl+alt+F# (VT switching)
Previous attempts to configure in xorg.conf.d failed - need to investigate what's overriding the settings
Tried: /etc/X11/xorg.conf.d/00-no-vt-or-zap.conf with DontVTSwitch and DontZap options
Removed conflicting setxkbmap statements, gdm, and keyd configs - still didn't work

** TODO [#B] All error messages should be actionable with recovery steps
Currently just reports errors without guidance on how to fix them


** TODO [#B] Enable TLP power management for laptops
TLP manages power-saving modes for Wi-Fi, USB, PCIe, Bluetooth, CPU scheduler
Install tlp, enable service, add custom Framework 13 config to /etc/tlp.d/01-custom.conf
Improves battery life and prevents power-related issues during install/post-install

** TODO [#B] Improve logging consistency
Some operations log to ~$logfile~, others don't - standardize logging
All package installs should log, all system modifications should log, all errors should log with context
Makes debugging failed installations easier

** TODO [#B] Add backup before system file modifications
Safety net for /etc/X11/xorg.conf.d and other system file edits
Files like ~/etc/sudoers~, ~/etc/pacman.conf~, ~/etc/default/grub~ modified without backup
If modifications fail or are incorrect, difficult to recover - should backup files to ~.backup~ before modifying

** TODO [#B] Implement Testinfra test suite for archsetup
Create comprehensive integration tests using Testinfra (Python + pytest) to validate archsetup installations

See complete documentation: [[file:docs/testing-strategy.org::*Test Automation Framework][Testing Strategy - Test Automation Framework]]

Tests should cover:
- Smoke tests: user created, key packages installed, dotfiles present
- Integration tests: services running, configs valid, X11 starts, apps launch
- End-to-end tests: login as user, startx, open terminal, run emacs, verify workflows

Framework: Testinfra with pytest (SSH-native, built-in modules for files/packages/services/commands)
Location: scripts/testing/tests/ directory
Integration: Run via pytest against test VMs after archsetup completes
Benefits: Expressive Python tests, excellent reporting, can test interactive scenarios

The testing-strategy.org document includes:
- Complete example test suite (test_integration.py)
- Tiered testing strategy (smoke/integration/end-to-end)
- How to run tests and integrate with run-test.sh
- Comparison with alternatives (Goss)

** TODO [#B] Set up automated test schedule
Weekly full run to catch deprecated packages even without commits

** TODO [#B] Implement manual test trigger capability
Allow on-demand test runs when automation is toggled off

** TODO [#B] Create test results dashboard/reporting
Make test outcomes visible and actionable

** TODO [#B] Block merges to main if tests fail
Enforce quality gate - broken changes don't enter main branch

** TODO [#B] Add network failure testing to test suite
Simulate network disconnect mid-install to verify resilience

** TODO [#B] Keep container base images up to date
Regular updates to Arch base image with review process and schedule

** TODO [#B] Persist test logs for historical analysis
Archive logs with review process and schedule to identify failure patterns and trends

** TODO [#B] Implement automated deprecation detection
Parse package warnings and repo metadata to catch upcoming deprecations proactively

** TODO [#B] Audit dotfiles/common directory
*** TODO [#B] Review all 50+ scripts in ~/.local/bin - remove unused scripts
*** TODO [#B] Check dotfiles for uninstalled packages - remove orphaned configs
*** TODO [#B] Verify all stowed files are actually used

** TODO [#B] Remove unnecessary linux-firmware packages (velox only)
Remove firmware packages for hardware not present on Framework laptop.
**NOTE:** This applies to Framework Laptop (velox), not Framework Desktop (ratio)

Only needed:
- linux-firmware-intel (CPU/GPU/Audio)
- linux-firmware-atheros (WiFi)

Can remove:
- linux-firmware (meta-package)
- linux-firmware-amdgpu
- linux-firmware-broadcom
- linux-firmware-cirrus
- linux-firmware-mediatek
- linux-firmware-nvidia
- linux-firmware-other
- linux-firmware-radeon
- linux-firmware-realtek

Disk space savings: ~600 MB

See [[file:docs/firmware-cleanup.org][docs/firmware-cleanup.org]] for full analysis and removal commands.

After removal, update archsetup script to install only needed firmware packages.

** TODO [#B] Identify and replace packages no longer in repos
Systematic check for availability issues

** TODO [#B] Verify package origin for all packages
Ensure packages are installed from correct source (official repos vs AUR) - prevent installing from wrong place

** TODO [#B] Automate script usage tracking
Parse shell history files for ~/.local/bin script names to identify last usage date and unused scripts

** TODO [#B] Automate dotfile validation
Parse config files for binary/command references and verify those binaries exist - catch orphaned references

** TODO [#B] Test security + functionality together
*** DONE [#B] Verify SSH to remote server works
CLOSED: [2026-02-02 Mon]
Tested 2026-02-02: ssh cjennings.net returns "connected" successfully.
SSH key authentication working, no password required.
*** DONE [#B] Verify Proton Mail Bridge retrieves email
CLOSED: [2026-02-02 Mon]
Verified 2026-02-02: Proton Mail Bridge running, ports 1143 (IMAP) and 1025 (SMTP)
listening on 127.0.0.1. mu4e email retrieval functional.
*** TODO [#B] Verify no unexpected open ports or services

** TODO [#B] Security audit tooling
*** TODO [#B] Implement port scanning check
*** TODO [#B] Create security posture verification script
*** TODO [#B] Set up intrusion detection monitoring

** TODO [#B] Document threat model and mitigations within 6 months
Identify attack vectors, what's mitigated, what remains

** TODO [#B] Verify package signature verification not bypassed by --noconfirm
Packages installed with ~--noconfirm~ may skip signature checks
AUR had issues previously requiring --noconfirm workaround - verify this doesn't compromise security
Ensure package signatures are still verified despite --noconfirm flag

** TODO [#B] Document evaluation criteria and trade-offs
Establish clear process for tool evaluation decisions

** TODO [#B] Test each modernization thoroughly before replacing
Ensure new tools integrate with DWM environment and don't break workflow

** TODO [#B] Add Rust installation via rustup instead of pacman package
The =rust= package has been removed from archsetup. Need to add Rust installation using =rustup= (the official Rust toolchain manager) instead of the Arch package.

Steps:
- Install rustup: =pacman -S rustup=
- Initialize default toolchain: =rustup default stable=
- Consider adding to archsetup or post-install script

Reference: Removed from archsetup on 2025-11-15

** TODO [#B] Add NVIDIA preflight check for Hyprland
Detect NVIDIA GPU and warn user about potential Wayland issues:
- Require driver version 535+ or abort
- Document required env vars (LIBVA_DRIVER_NAME, GBM_BACKEND, etc.)
- Prompt to continue or abort if NVIDIA detected


** TODO [#B] Add org-capture popup frame on keyboard shortcut
Set up a quick-capture popup using emacsclient that opens a small floating
org-capture frame, with Hyprland window rules to float, size, and center it.
Frame should auto-close on finalize (C-c C-c) or abort (C-c C-k).

Implementation:
1. Create =~/.local/bin/quick-capture= script:
   - =emacsclient -c -F '((name . "org-capture") (width . 80) (height . 20))' -e '(org-capture)'=
   - Requires Emacs daemon running (already configured via systemd)
2. Add Hyprland window rules to =hyprland.conf=:
   - =windowrulev2 = float, title:^(org-capture)$=
   - =windowrulev2 = size 800 400, title:^(org-capture)$=
   - =windowrulev2 = center, title:^(org-capture)$=
   - =windowrulev2 = stayfocused, title:^(org-capture)$=
3. Add keybind in =hyprland.conf= (choose available key combo)
4. Add Elisp hook to auto-delete the frame after capture:
   =(defun my/org-capture-delete-frame ()
     (when (equal (frame-parameter nil 'name) "org-capture")
       (delete-frame)))
   (add-hook 'org-capture-after-finalize-hook #'my/org-capture-delete-frame)=
5. Notes go directly into existing org capture templates — zero new infrastructure

Reference: Protesilaos Stavrou's popup frame pattern for emacsclient.

** TODO Check linux-lts version until 6.18+
SCHEDULED: <2026-02-23 Mon +3w>
Run =topgrade= and check =pacman -Q linux-lts=. Once 6.18+, remove =/etc/modprobe.d/amdgpu.conf= and mark this DONE.
Background: AMD Strix Halo VPE power gating bug causes system freeze. Workaround disables power gating. Fix is in kernel 6.15+.

** TODO [#C] Review theme config architecture for dunst/fuzzel
The active dunst config is stowed from dotfiles/common/ but theme templates
live in dotfiles/hyprland/.config/themes/. set-theme copies the templates to
the stowed locations at runtime, so edits to the common file get overwritten
on theme switch. This split between stowed configs and theme templates is
error-prone — changes must be made in both places. Consider:
- Having set-theme be the single source of truth (remove common dunstrc from stow)
- Or symlinking the stowed config to a theme-managed location
- Same situation applies to fuzzel.ini
The goal is a single place to edit each config, not two.

** TODO [#C] Create Chrome theme with dupre colors
Create a Chrome browser theme using the dupre color palette. Plan saved in [[file:docs/PLAN-browser-themes.org][docs/PLAN-browser-themes.org]].

** TODO [#C] Monitor and optimize test execution time
Keep test runs performant as installs and post-install tests grow (target < 2 hours)

** TODO [#C] Set up alerts for deprecated packages
Proactive monitoring integrated with testing

** TODO [#C] Fix VM cloning machine-ID conflicts for parallel testing
Currently using snapshot-based testing which works but limits to sequential test runs
Cloned VMs fail to get DHCP/network even with machine-ID manipulation (truncate/remove)
Root cause: Truncating /etc/machine-id breaks systemd/NetworkManager startup
Need to investigate proper machine-ID regeneration that doesn't break networking
Would enable parallel test execution in CI/CD
Priority C because snapshot-based testing meets current needs

** TODO [#C] Create security checklist for cafe/public wifi scenarios
Practical guidelines for working in public spaces

** TODO [#C] Build security dashboard command
Single command shows: encryption status, firewall status, open ports, running services

** TODO [#C] Evaluate modern CLI tool replacements
bat, eza, zoxide, dust, ripgrep-all - only adopt if clear friction reduction

** TODO [#C] Consider paru instead of yay
Evaluate if paru offers meaningful improvements for AUR management

** TODO [#C] Evaluate terminal emulator alternatives
ghostty for ligature support - addresses known deficiency

** TODO [#C] Review file manager options for Wayland
Ranger image previews don't work in foot terminal (Wayland). Ranger's kitty graphics
method checks TERM for "kitty" string, and foot's kitty protocol implementation
has subtle incompatibilities that cause hangs. ueberzug is X11-only.

Tried yazi (2026-02) - theming/icon color customization was problematic.
Revisit later when yazi matures or try lf with custom preview scripts.

Keep ranger for DWM/X11 where ueberzug works fine.

** TODO [#C] Review current tool pain points annually
Once-yearly systematic inventory of known deficiencies and friction points in current toolset

** TODO [#C] Install Zoxide integration into Ranger
https://github.com/jchook/ranger-zoxide - enables zoxide jumping within ranger file manager

** TODO [#D] Find or create a monocle layout for Hyprland
Both existing monocle plugins (zakk4223/hyprlandMonocle, pianocomposer321/hyprland-monocle) are
abandoned and broken against current Hyprland. Options: fork and fix hyprlandMonocle (more features),
script a pseudo-monocle using fullscreen 1, or wait for a maintained plugin. Lower priority since
stash-window ($mod+O / $mod+Shift+O) covers the main use case. More important for laptop installs.

** TODO [#D] Consider Customizing Hyprland Animations
Current: windows pop in, scratchpads slide from bottom.

Customizable animations:
- windows / windowsOut / windowsMove - window open/close/move
- fade - opacity changes
- border / borderangle - border color and gradient angle
- workspaces - workspace switching
- specialWorkspace - scratchpads (currently slidevert)
- layers - waybar, notifications, etc.

Styles: slide, slidevert, popin X%, fade
Parameters: animation = NAME, ON/OFF, SPEED, BEZIER, STYLE
Speed: lower = faster (1-10 typical)

Example tweaks:
#+begin_src conf
animation = windows, 1, 2, myBezier, popin 80%
animation = workspaces, 1, 4, default, slide
animation = fade, 1, 2, default
animation = layers, 1, 2, default, fade
#+end_src

** VERIFY [#D] Test wlogout menu on laptop
Test wlogout exit menu on laptop to verify sizing works on different display.
Current config uses fixed pixel margins - may need adjustment for laptop screen.

** TODO [#D] Parse and improve AUR error reporting
Parse yay errors and provide specific, actionable fixes instead of generic error messages

** TODO [#D] Improve progress indicators throughout install
Enhance existing indicators to show what's happening in real-time

** TODO [#D] Add retry logic to git_install function
pacman_install and aur_install have retry logic, but git_install doesn't

** TODO [#D] Add cpupower installation and enabling to archsetup
cpupower service configures the default CPU scheduler (powersave or performance)
Install cpupower, configure /etc/default/cpupower, enable service: ~systemctl enable --now cpupower.service~

* Archsetup Resolved

** DONE [#B] Full install logs should contain timestamps
CLOSED: [2026-02-23 Sun]
Log filename includes timestamp via =date +'%Y-%m-%d-%H-%M-%S'=.
Functions =error_warn()=, =error_fatal()=, and =display()= all output timestamps via =date +'%T'=.

** DONE [#B] Validate DESKTOP_ENV default behavior
CLOSED: [2026-02-23 Sun]
Defaults to =hyprland= silently via =desktop_env="${desktop_env:-hyprland}"=.
Overridable via config file or =DESKTOP_ENV= environment variable.

** DONE [#B] Test archsetup username/password prompts
CLOSED: [2026-02-23 Sun]
Username prompt with regex validation (lines 320-332) and password prompt
with confirmation (lines 339-353) implemented and functional.