small-scripts/memory/log/2026-03-13.111440.md

Session Log — 2026-03-13

Summary

Created the small-scripts project — a spec-driven utility script collection with dryrun support and automated testing. Implemented the first script git-status-report which recursively scans directories for git repos and reports uncommitted changes with character-level diffs and remote sync status.

Decisions

• Decision: Use OpenSpec format for all script specifications — Rationale: Testing agent-driven development; specs define purpose, usage, behaviour, dryrun behaviour, edge cases, and examples
• Decision: Every script must support --dryrun / -n — Rationale: Enables testing via dryrun without side effects; tests validate spec compliance through dryrun output
• Decision: Removed set -e from git-status-report, kept set -uo pipefail — Rationale: set -e caused silent failures in complex pipeline/subshell chains; for a reporting tool, explicit error handling is safer than errexit
• Decision: "No remotes" and "detached HEAD" don't count as dirty — Rationale: These are informational states, not divergences; "(no remotes)" only shown when repo already has local changes
• Decision: Project hosted under skynet org on Gitea — Rationale: AI-focused project (agent-driven development testbed)

Gotchas Discovered

• [bash] Symptom: set -euo pipefail caused silent script termination with no output during complex loops with command substitutions and subshell calls — Fix: Removed set -e, kept set -uo pipefail. Reporting tools don't need errexit; explicit error handling is more predictable.
• [bash] Symptom: grep -qF "$expected" interpreted --dryrun as a grep flag — Fix: Use grep -qF -- "$expected" to prevent option-like strings from being parsed as flags
• [bash] Symptom: local keyword used outside a function in main loop body caused local: can only be used in a function error — Fix: Remove local qualifier for variables in the main script body
• [bash] Symptom: set -e in test script killed execution when capturing output from commands expected to exit non-zero (output=$(cmd) where cmd exits 1) — Fix: Use output=$(cmd) && rc=$? || rc=$? or output=$(cmd) || true pattern
• [bash] Symptom: file command on shell scripts returns "executable" which matched the binary detection grep binary\|executable\|image\|archive — Fix: Changed to grep -qP "binary|image|archive" with additional ! grep -q "text" check to avoid false positives on text executables

Key Context

• Project structure: specs/ (OpenSpec), scripts/ (implementations), tests/ (test scripts using dryrun)
• Scripts symlinked to ~/sbin for PATH availability
• Test runner at tests/run-all.sh with colour pass/fail output
• First script git-status-report has 26 test assertions covering: help, no repos, dryrun, clean/dirty repos, untracked/deleted files, no remotes, ahead of remote, mixed repos, nested repo filtering, permission denied

Process Notes

• The set -e debugging consumed significant time — the script worked in isolated tests but failed silently on real repos. Future scripts should start without set -e for reporting/read-only tools.
• Test development caught real bugs (grep flag parsing, local keyword misuse) — the spec-driven approach with comprehensive tests works well.
• The file command for binary detection is unreliable for scripts; need a better heuristic (maybe git diff --numstat which shows - for binary files).