From f802039757d5da01a2b7cb7d1b15c692f137d91f Mon Sep 17 00:00:00 2001 From: Tommaso Negri Date: Wed, 14 Oct 2026 21:58:57 +0200 Subject: add tasks --- tasks/20261014-190252/TASK.md | 15 +++++++++++++++ tasks/20261014-191209/TASK.md | 15 +++++++++++++++ tasks/20261014-191342/TASK.md | 15 +++++++++++++++ tasks/20261014-191419/TASK.md | 15 +++++++++++++++ tasks/20261014-191457/TASK.md | 15 +++++++++++++++ tasks/20261014-191535/TASK.md | 15 +++++++++++++++ tasks/20261014-191606/TASK.md | 17 +++++++++++++++++ tasks/20261014-191642/TASK.md | 17 +++++++++++++++++ tasks/20261014-191711/TASK.md | 15 +++++++++++++++ tasks/20261014-191750/TASK.md | 15 +++++++++++++++ tasks/20261014-191827/TASK.md | 15 +++++++++++++++ tasks/20261014-191901/TASK.md | 15 +++++++++++++++ tasks/20261014-191932/TASK.md | 15 +++++++++++++++ tasks/20261014-192052/TASK.md | 15 +++++++++++++++ tasks/20261014-192147/TASK.md | 15 +++++++++++++++ tasks/20261014-192228/TASK.md | 15 +++++++++++++++ tasks/20261014-192305/TASK.md | 15 +++++++++++++++ tasks/20261014-192338/TASK.md | 15 +++++++++++++++ tasks/20261014-192419/TASK.md | 15 +++++++++++++++ 19 files changed, 289 insertions(+) create mode 100644 tasks/20261014-190252/TASK.md create mode 100644 tasks/20261014-191209/TASK.md create mode 100644 tasks/20261014-191342/TASK.md create mode 100644 tasks/20261014-191419/TASK.md create mode 100644 tasks/20261014-191457/TASK.md create mode 100644 tasks/20261014-191535/TASK.md create mode 100644 tasks/20261014-191606/TASK.md create mode 100644 tasks/20261014-191642/TASK.md create mode 100644 tasks/20261014-191711/TASK.md create mode 100644 tasks/20261014-191750/TASK.md create mode 100644 tasks/20261014-191827/TASK.md create mode 100644 tasks/20261014-191901/TASK.md create mode 100644 tasks/20261014-191932/TASK.md create mode 100644 tasks/20261014-192052/TASK.md create mode 100644 tasks/20261014-192147/TASK.md create mode 100644 tasks/20261014-192228/TASK.md create mode 100644 tasks/20261014-192305/TASK.md create mode 100644 tasks/20261014-192338/TASK.md create mode 100644 tasks/20261014-192419/TASK.md (limited to 'tasks') diff --git a/tasks/20261014-190252/TASK.md b/tasks/20261014-190252/TASK.md new file mode 100644 index 0000000..abbeb72 --- /dev/null +++ b/tasks/20261014-190252/TASK.md @@ -0,0 +1,15 @@ +# Drain command stdout and stderr concurrently + +- STATUS: OPEN +- PRIORITY: 10 +- TAGS: review, bug, core + +Files: Sources/bar/Models/Runner.swift, Tests/barTests/phbarTests.swift. + +Problem: Runner reads stdout to EOF before draining stderr. A child that fills the stderr pipe blocks on writing; Runner waits for stdout EOF, so a valid command can stall until timeout. + +Approach: Drain both pipes concurrently using a small, clearly owned implementation. Avoid moving blocking reads onto the main actor or filling Swift's cooperative executor with unbounded blocking work. Preserve /bin/sh -c, inherited environment, output whitespace, newline parsing, and ERROR cells on nonzero exit. Decide whether stderr should be forwarded on successful exits too; command.md currently promises forwarding without that qualification. + +Completion checks: A command writes substantially more than pipe capacity to stderr and then emits stdout; it finishes promptly and stdout is correct. Check simultaneous large stdout/stderr, normal empty output, and nonzero exit diagnostics. Add focused regression tests with an outer deadline so a failure cannot hang the test suite. Coordinate timeout ownership with the separate timeout task. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191209/TASK.md b/tasks/20261014-191209/TASK.md new file mode 100644 index 0000000..2509308 --- /dev/null +++ b/tasks/20261014-191209/TASK.md @@ -0,0 +1,15 @@ +# Make command timeout and process cleanup bounded + +- STATUS: OPEN +- PRIORITY: 20 +- TAGS: review,bug,core + +Files: Sources/bar/Models/Runner.swift and its tests. + +Problem: The 30-second timer calls Process.terminate(), which sends SIGTERM to the shell. A process can ignore it; descendants can retain stdout/stderr handles and prevent EOF even after the shell exits. The documented timeout is therefore not a reliable bound. + +Approach: First reproduce a SIGTERM-ignoring command and a shell with a descendant retaining pipe handles. Choose the smallest macOS-compatible process ownership mechanism that can terminate only this command's process tree, escalate after a short grace period, and finish pipe reads. Do not signal the bar's own process group or unrelated processes. Handle timer cancellation, PID lifetime, reader cleanup, and reaping on every exit path. Document any unavoidable limitation honestly. + +Completion checks: Normal commands complete without later signals. Both reproductions return ERROR within timeout plus documented grace, release readers, and leave no owned child running. Allow a short timeout in tests without adding a user-facing configuration system. Review together with concurrent pipe draining. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191342/TASK.md b/tasks/20261014-191342/TASK.md new file mode 100644 index 0000000..59f494c --- /dev/null +++ b/tasks/20261014-191342/TASK.md @@ -0,0 +1,15 @@ +# Serialize block commands and preserve gesture order + +- STATUS: OPEN +- PRIORITY: 30 +- TAGS: review,bug,core + +Files: Sources/bar/Models/Block.swift, Sources/bar/Views/BlockView.swift, and behavioral tests. + +Problem: Every timer tick, Darwin notification, click, and scroll starts a detached command. Earlier slow results can overwrite newer output; bursts can launch many processes and race script side effects. + +Approach: Give each block one running command. Coalesce ordinary refresh requests into at most one pending refresh, while retaining ordered gesture requests and their BUTTON/SCROLL/CELL environment snapshots. Explicitly review how pending gestures and refreshes interleave. A generation counter alone fixes stale display results but does not serialize side effects. Keep the implementation local to Block and readable; avoid introducing a generic scheduling framework. Consider what a large gesture burst should do without silently losing user actions. + +Completion checks: Controlled slow and fast commands cannot produce stale overwrites. A refresh burst has bounded pending refresh work. Click/scroll side effects execute in order, with correct environment values. Separate blocks can still run independently and main-actor UI remains responsive. Reuse Runner timeout behavior rather than duplicating process control. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191419/TASK.md b/tasks/20261014-191419/TASK.md new file mode 100644 index 0000000..5854777 --- /dev/null +++ b/tasks/20261014-191419/TASK.md @@ -0,0 +1,15 @@ +# Make block timer start and stop predictable + +- STATUS: OPEN +- PRIORITY: 40 +- TAGS: review,bug,core + +File: Sources/bar/Models/Block.swift; lifecycle caller: Sources/bar/Views/AppDelegate.swift. + +Problem: Calling start() twice creates another timer and overwrites tick without cancelling the old task. stop() only cancels the currently stored timer. This matters when users customize lifecycle behavior or apply patches. + +Approach: Choose and document idempotent start semantics or explicit restart semantics. Cancel an existing timer before replacing it where appropriate; clear stored state on stop. Preserve one initial refresh per intended start and no automatic timer for nil or nonpositive intervals. Clarify whether stop means only stop ticking or also stop queued/in-flight execution, coordinating with the execution-policy task. Do not imply Task cancellation terminates a Process unless implemented. + +Completion checks: Repeated start calls do not multiply periodic executions. Stop prevents later ticks, including after a sleeping timer resumes. Start-stop-start behaves consistently. Add a small meaningful lifecycle test using short controlled intervals or an execution seam. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191457/TASK.md b/tasks/20261014-191457/TASK.md new file mode 100644 index 0000000..82d5686 --- /dev/null +++ b/tasks/20261014-191457/TASK.md @@ -0,0 +1,15 @@ +# Use positional cell identity and current hover content + +- STATUS: OPEN +- PRIORITY: 50 +- TAGS: review,bug,ui + +Files: Sources/bar/Models/Cell.swift, Sources/bar/Models/Block.swift, Sources/bar/Views/BlockView.swift. + +Problem: Cell.id combines text and highlight. Identical lines, including repeated blank cells, have duplicate ForEach IDs. Content changes also replace view identity. hoveredCell stores a value snapshot that can become stale after a refresh. + +Approach: Use line position as identity because shell output is an ordered list with no semantic IDs. This can be supplied during parsing or through indexed rendering; choose the clearest small implementation. Track the hovered position and resolve its current cell when handling events. Reject a hover index that no longer exists. Update identity comments and check hover exit behavior when views disappear or output changes. + +Completion checks: Repeated identical text and blank lines render as distinct cells without duplicate-ID warnings. Text/highlight updates retain positional identity. Clicking after a refresh sends the current text in CELL; shrinking output or removing a hovered cell cannot trigger an unrelated or stale action. Manually check multiple bar windows and hover transitions. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191535/TASK.md b/tasks/20261014-191535/TASK.md new file mode 100644 index 0000000..06556ad --- /dev/null +++ b/tasks/20261014-191535/TASK.md @@ -0,0 +1,15 @@ +# Parse highlight prefixes without regex backtracking surprises + +- STATUS: OPEN +- PRIORITY: 60 +- TAGS: review,bug,core + +Files: Sources/bar/Models/Cell.swift, Sources/bar/bar.docc/highlighting.md, and parser tests. + +Reproduced behavior: "&!12" parses as highlight 1 plus text "2", because the optional digit capture backtracks to satisfy the required nonempty body. "&!1" remains literal text. Existing valid output such as "&!1 hello" must keep its leading space after the prefix. + +Approach: Define the contract for a prefix with no body, zero/out-of-range levels, malformed prefixes, integer overflow, and digit characters accepted. Recognize only a leading &!, consume its entire digit sequence, then parse the remaining text without trimming. Prefer a short explicit parser if it makes ownership and edge cases easier to understand. Decide whether invalid levels strip the prefix or preserve literal text, and document the choice. + +Completion checks: Cover ordinary text, valid levels, &!1, &!12, &!0 text, out-of-range and huge levels, malformed prefixes, embedded &!, empty text, and whitespace-only bodies. No partial level interpretation is possible. Preserve the existing one-based Config.highlights convention. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191606/TASK.md b/tasks/20261014-191606/TASK.md new file mode 100644 index 0000000..5c286a9 --- /dev/null +++ b/tasks/20261014-191606/TASK.md @@ -0,0 +1,17 @@ +# Run daemon event loops so registered callbacks are delivered + +- STATUS: OPEN +- PRIORITY: 70 +- TAGS: review,bug,deamons + +Files: daemons/batteryd.c, brightnessd.c, devicesd.c, networkd.c, focusd.c, nowplayingd.c; corresponding DocC daemon articles. + +Problem: Run-loop sources/observers are registered, but the main thread then waits in pause() instead of running its CFRunLoop. Adding a source does not process its events. Treat each daemon's delivery mechanism explicitly; do not assume the CoreAudio or socket daemons need the same fix. + +Approach: Use a small run-loop-based wait, with a shutdown strategy that responds to SIGINT/SIGTERM. For example, bounded CFRunLoopRunInMode iterations can check a volatile sig_atomic_t flag; account for absent sources and avoid a busy loop. Validate registration results and fail clearly if setup cannot work. Preserve the editable bar.touch. convention. + +Completion checks: Build with the compile commands in each source header. After setting an actual block name, trigger battery/network/device events and the relevant distributed notifications; observe posts using notifyutil or the bar. Confirm clean prompt shutdown and no idle spin. Record which hardware events were tested and which remain unverified. + +Reference: https://developer.apple.com/documentation/corefoundation/cfrunloopruninmode(_:_:_:). + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191642/TASK.md b/tasks/20261014-191642/TASK.md new file mode 100644 index 0000000..b6b2f5c --- /dev/null +++ b/tasks/20261014-191642/TASK.md @@ -0,0 +1,17 @@ +# Fix IOKit matching dictionary and iterator ownership + +- STATUS: OPEN +- PRIORITY: 80 +- TAGS: review,bug,deamons + +Files: daemons/devicesd.c and daemons/brightnessd.c. + +Problem: IOServiceAddMatchingNotification consumes a reference to the matching dictionary, but both files reuse that dictionary in a second registration without retaining it. They also overwrite the iterator variable, and the termination iterator is not initially drained to arm notification delivery. Return values and notification-port creation are unchecked. + +Approach: Give each registration a fresh matching dictionary or deliberately retain one reference per call. Store separate first-match and termination iterators, drain each initial result to arm it, and release owned iterators at shutdown. Check failure paths before using returned objects. In brightnessd, IOServiceMatching returning a dictionary does not prove a service exists, so review the claimed fallback behavior separately from ownership. + +Completion checks: Compile with warnings enabled. Confirm initial enumeration and subsequent connect/disconnect callbacks after the event-loop task is fixed. Exercise no-matching-device and failed-registration paths without invalid handles or use-after-free. Keep device discovery intentionally narrow and describe supported hardware accurately. + +Reference: https://developer.apple.com/documentation/iokit/1514362-ioserviceaddmatchingnotification. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191711/TASK.md b/tasks/20261014-191711/TASK.md new file mode 100644 index 0000000..4589793 --- /dev/null +++ b/tasks/20261014-191711/TASK.md @@ -0,0 +1,15 @@ +# Remove the exact CoreAudio listeners that volumed registers + +- STATUS: OPEN +- PRIORITY: 90 +- TAGS: review,bug,deamons + +File: daemons/volumed.c and Sources/bar/bar.docc/daemons/daemon-volumed.md. + +Problem: Registration selects the preferred output channel dynamically, but removal hardcodes channel 1. Mute listeners on old devices are never removed. Shutdown removes neither the mute listener nor the system default-device listener. Switching devices also does not directly refresh the block's display. + +Approach: Retain the exact registered property addresses and device ID, with registration success state. Remove both volume and mute listeners before changing devices and on shutdown; remove the system listener too. Check CoreAudio return values and handle devices without the expected volume property. Review callback concurrency when mutating shared registration state. Post a refresh when output-device changes so display catches up even without a volume event. + +Completion checks: Switch repeatedly between built-in output and available headphones/external devices. Confirm notifications follow only the active device and selected channel, mute updates work, no listener accumulates, unsupported properties produce useful diagnostics, and shutdown cleans up. Document actual hardware tested. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191750/TASK.md b/tasks/20261014-191750/TASK.md new file mode 100644 index 0000000..fb44496 --- /dev/null +++ b/tasks/20261014-191750/TASK.md @@ -0,0 +1,15 @@ +# Make spaced monitor Space changes rather than display changes + +- STATUS: OPEN +- PRIORITY: 100 +- TAGS: review,bug,deamons + +Files: daemons/spaced.c and Sources/bar/bar.docc/daemons/daemon-spaced.md. + +Problem: The daemon polls CGSCopyActiveMenuBarDisplayIdentifier and compares display identifiers. This does not establish that changing Spaces on the same display will be detected, despite the advertised purpose. The hardcoded private framework path/symbol also needs verification on supported macOS. + +Approach: Reproduce same-display Space switching before choosing a fix. Prefer a narrow public workspace-change notification if practical, even if the standalone daemon must be compiled as Objective-C with AppKit. Otherwise verify an actual Space identifier source and document private-API limits. Keep this functionality outside the Swift core. Remove unused pollCount if no longer needed and update compile instructions when the implementation language/framework changes. + +Completion checks: Switching Spaces on one display causes a refresh. Check multiple displays and display focus changes where available; distinguish these from Space changes. Startup or API loading failures report clearly. Verify shutdown and idle resource use. Record tested macOS version and avoid claiming untested hardware behavior. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191827/TASK.md b/tasks/20261014-191827/TASK.md new file mode 100644 index 0000000..ff2bdbf --- /dev/null +++ b/tasks/20261014-191827/TASK.md @@ -0,0 +1,15 @@ +# Repair and verify the background blur patch + +- STATUS: OPEN +- PRIORITY: 110 +- TAGS: review,bug,patches + +files: patches/patch-background_blur-20260811-10fed47.patch and sources/bar/bar.docc/patches/patch-background-blur.md. + +observed: git apply --check fails against the current checkout because config context has changed. more fundamentally, the patch constructs backgroundblurview but neither the patch nor the repository defines that type; backgroundblur has no supplied implementation consuming it. + +approach: choose a documented base revision, create an isolated checkout, implement the complete optional blur feature there, and regenerate the patch including any new source file. decide whether a controllable blur amount requires private apis or whether a public visual-effect view gives acceptable behavior; update the article to describe the actual implementation. keep the feature out of the core. update the filename date/base commit and every documentation link consistently. + +completion checks: on a clean documented base, git apply --check succeeds, applying succeeds, and swift build succeeds. changing config.backgroundblur has the advertised effect on screen. verify transparency and window sizing. publish a complete self-contained patch; no undefined backgroundblurview or missing prerequisite remains. + +design constraint: follow readme.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. this is a suggestion for individual review, not a deadline. findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191901/TASK.md b/tasks/20261014-191901/TASK.md new file mode 100644 index 0000000..e7e1176 --- /dev/null +++ b/tasks/20261014-191901/TASK.md @@ -0,0 +1,15 @@ +# Refresh the font offset patch against a documented base + +- STATUS: OPEN +- PRIORITY: 120 +- TAGS: review,bug,patches + +Files: patches/patch-font_offset-20260810-11d813c.patch and Sources/bar/bar.docc/patches/patch-font-offset.md. + +Observed: git apply --check fails on current CellView context, which now uses let cell rather than the older var cell. This optional appearance feature should remain a patch. + +Approach: Regenerate against the intended documented revision in an isolated checkout. Preserve Config.fontOffset semantics: negative moves text up, positive moves it down. Keep the cell background and hit area full height while moving only text. Review whether the added Group serves a purpose and choose the simplest view expression. Update filename date/base commit and all documentation URLs together. + +Completion checks: Patch checks and applies cleanly on the documented clean base; patched project builds. Test zero, positive, and negative offsets visually with highlighted cells and gestures. If compatibility with other appearance patches is claimed, test the combination or document the required order. Avoid unrelated core edits in the patch. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-191932/TASK.md b/tasks/20261014-191932/TASK.md new file mode 100644 index 0000000..9936035 --- /dev/null +++ b/tasks/20261014-191932/TASK.md @@ -0,0 +1,15 @@ +# Repair the screen hotplug patch and preserve visibility + +- STATUS: OPEN +- PRIORITY: 130 +- TAGS: review,bug,patches + +Files: patches/patch-screen_hotplug-20260810-f6805c9.patch, Sources/bar/Views/AppDelegate.swift, Sources/bar/bar.docc/patches/patch-screen-hotplug.md. + +Observed: The patch targets Sources/bar/Models/AppDelegate.swift, which no longer exists. Its rebuilding code calls orderFrontRegardless for every window, so review whether a previously hidden bar would be unexpectedly shown after a screen change. + +Approach: Regenerate the optional feature against a documented clean base using the current Views path. Rebuild windows for current display geometry, retain the shared blocks without restarting their timers, and explicitly preserve hide/show state. Verify Swift 6 actor isolation of the notification callback and remove its observer on termination. Ensure discarded windows and event monitors are released. Update filename date/base revision and documentation links. + +Completion checks: git apply --check and patched swift build pass. Connect/disconnect a display and change display arrangement/resolution; windows match current frames with no stale bar. Repeat while hidden: it stays hidden until bar.show. Confirm block execution does not multiply and gestures still work after rebuilding. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-192052/TASK.md b/tasks/20261014-192052/TASK.md new file mode 100644 index 0000000..8165a59 --- /dev/null +++ b/tasks/20261014-192052/TASK.md @@ -0,0 +1,15 @@ +# Replace the placeholder test with focused protocol tests + +- STATUS: OPEN +- PRIORITY: 140 +- TAGS: review,quality,tests + +Files: Tests/barTests/phbarTests.swift, Sources/bar/Models/Runner.swift, Sources/bar/Models/Cell.swift. + +Observed: swift test succeeds, but the sole example test contains no assertions. A small regression suite would protect the shell protocol users rely on without adding production abstractions just for coverage. + +Approach: Replace example() with named Swift Testing cases for Runner.parse: empty string -> [], one trailing newline removed, internal and additional trailing blank lines preserved, line order unchanged, and spaces not trimmed. Add highlight cases once the parsing contract is agreed. Cover repeated identical cells in the identity task. Process deadlock/timeout and execution-order regressions belong beside their respective fixes, rather than duplicating them here. Respect actor isolation for Config/UI-derived values. + +Completion checks: swift test executes meaningful assertions and all pass. Tests describe public behavioral contracts rather than copying implementation logic or relying on the user's scripts/hardware. Keep process fixtures bounded and deterministic. No screenshot suite, testing dependency, or general mock framework is required. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-192147/TASK.md b/tasks/20261014-192147/TASK.md new file mode 100644 index 0000000..6961419 --- /dev/null +++ b/tasks/20261014-192147/TASK.md @@ -0,0 +1,15 @@ +# Correct macOS build and installation commands + +- STATUS: OPEN +- PRIORITY: 150 +- TAGS: review,bug,build,docs + +Files: Makefile and Sources/bar/bar.docc/installation.md. + +Problem: make run uses swift run bar -c debug, which places options after the executable where they are treated as program arguments. The install target uses GNU-style install -Dm755 even though macOS install has different -D semantics. The documented PREFIX=/usr/local/bin produces /usr/local/bin/bin because the Makefile appends /bin. + +Approach: Use swift run -c debug bar. Keep install -d, followed by macOS-compatible install -m 755 with quoted source/destination paths. Quote PREFIX paths in uninstall too, so prefixes containing spaces work. Correct the example to PREFIX=/usr/local. In the manual-build instructions, create ~/.local/bin before copying. Preserve the simple Makefile and its existing prefix convention. + +Completion checks: Run make build and inspect/run make run on macOS. Install into a temporary writable prefix, including one with spaces; confirm executable location and permissions and exercise uninstall only in that temporary prefix. Check docs match the exact resulting paths. Do not overwrite the user's installed bar during verification. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-192228/TASK.md b/tasks/20261014-192228/TASK.md new file mode 100644 index 0000000..453663a --- /dev/null +++ b/tasks/20261014-192228/TASK.md @@ -0,0 +1,15 @@ +# Validate complete hex color input + +- STATUS: OPEN +- PRIORITY: 160 +- TAGS: review,bug,core + +File: Sources/bar/Models/HEX.swift; add small color/parser tests if useful. + +Problem: Scanner.scanHexInt64's result and final position are ignored. Partial valid prefixes can be accepted. Inputs with supported length but invalid characters can produce colors other than the documented opaque-black fallback, including transparency for RGBA forms. + +Approach: Validate every character and require complete successful conversion before component extraction. Consider UInt64(radix: 16) or checking Scanner success and exhaustion; retain only the small implementation needed. Preserve optional #, surrounding whitespace handling, case-insensitive hex, supported lengths 3/4/6/8, repeated short digits, and trailing alpha. Define malformed input consistently as opaque black. + +Completion checks: Valid short and long RGB/RGBA resolve correctly, including lowercase and alpha. Invalid characters at the start/middle/end, unsupported lengths, empty input, and partial scans all resolve to opaque black. Keep parsing independent of any new configuration framework and verify existing Config colors retain their appearance. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-192305/TASK.md b/tasks/20261014-192305/TASK.md new file mode 100644 index 0000000..6442a5a --- /dev/null +++ b/tasks/20261014-192305/TASK.md @@ -0,0 +1,15 @@ +# Review and remove unused HEX conversion surface + +- STATUS: OPEN +- PRIORITY: 170 +- TAGS: review,cleanup,core + +File: Sources/bar/Models/HEX.swift; references across Sources, Tests, documentation, and patches. + +Observation: The core uses Color.hex(String), while the HEX wrapper, Color.init(hex:), and Color.Resolved.hex reverse conversion appear unnecessary for current runtime behavior. They add concepts a reader must understand in a deliberately small project. + +Approach: Search all references first, including documentation and published patch expectations. Decide whether these helpers are intentionally useful to users customizing Swift source. If they have a concrete use, keep them and document it briefly; otherwise remove the unused wrapper/reverse-conversion surface and update Config comments/DocC references to the remaining helper. Treat removal as an optional design decision, not a correctness requirement. Preserve direct .hex("#...") convenience. + +Completion checks: swift build and swift test pass; no dangling HEX symbol links or references remain. Supported hex syntax and Config appearance are unchanged. Explain the kept/removed API choice in the change description so it can be reviewed separately from strict input validation. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-192338/TASK.md b/tasks/20261014-192338/TASK.md new file mode 100644 index 0000000..b649850 --- /dev/null +++ b/tasks/20261014-192338/TASK.md @@ -0,0 +1,15 @@ +# Align comments and documentation with actual guarantees + +- STATUS: OPEN +- PRIORITY: 180 +- TAGS: review,docs + +Files: README.md, Sources/bar/bar.docc/how-it-works.md, command.md, and comments in Cell.swift, Block.swift, Runner.swift, HEX.swift, and Config.swift. + +Problems to review: how-it-works claims all possible errors are caught at build time, but shell commands and malformed color strings are runtime concerns. Cell identity comments imply identity prevents redraws and describe content-derived identity as stable. Timeout comments currently promise more than process termination guarantees. README says exit 0 hides a block without specifying that stdout must be empty. + +Approach: Explain concrete contracts simply: source configuration catches Swift type/syntax errors; hiding requires successful execution with no output; SwiftUI identity distinguishes views and is separate from observed content updates. Once code fixes land, align timeout, stderr forwarding, invalid highlight behavior, and hex fallback descriptions with their implemented behavior. Review references after optional HEX removal. Preserve the friendly DIY tone and comments explaining why a choice exists; avoid adding a general architecture manual. + +Completion checks: Cross-check each claim against code and tests, build DocC with the project's documented workflow, and correct stale symbol links. This task can be revisited after related fixes; do not pre-document functionality that has not landed. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. diff --git a/tasks/20261014-192419/TASK.md b/tasks/20261014-192419/TASK.md new file mode 100644 index 0000000..c909da9 --- /dev/null +++ b/tasks/20261014-192419/TASK.md @@ -0,0 +1,15 @@ +# Resolve BlockView capture warning and clarify monitor lifetime + +- STATUS: OPEN +- PRIORITY: 190 +- TAGS: review,quality,ui + +File: Sources/bar/Views/BlockView.swift. + +Observed: swift test builds with an ImplicitStrongCapture warning at the inner [weak block] capture because onAppear implicitly captures block strongly. The monitor also captures self to access hover state, so the weak block capture alone does not establish weak ownership of all associated state. + +Approach: Inspect the actual closure ownership chain and choose explicit, intentional captures. Follow the compiler's outer capture-list guidance where appropriate, rather than suppressing the diagnostic. Keep monitor creation/removal paired across appearance/disappearance; guard against duplicate registrations if lifecycle behavior permits repeated onAppear calls. Coordinate hover storage changes with the positional-identity task. A small fix is preferable to a new event framework. + +Completion checks: A clean swift build/test has no warning from this capture. Click/scroll receives correct current hover data. Hide/show and any applied screen-rebuild patch do not accumulate monitors, duplicate command dispatch, or retain discarded views/windows. Manually verify lifecycle behavior before claiming leak prevention. + +Design constraint: Follow README.md: keep source-based configuration, no dependencies or plugin framework, and use the smallest readable change that makes the existing behavior reliable. This is a suggestion for individual review, not a deadline. Findings were recorded on 2026-10-14; re-check the current code before implementing. -- cgit v1.2.3