From 99d99dc3983a9d3453d01e117a3a05b535063aa1 Mon Sep 17 00:00:00 2001 From: Mick F Date: Fri, 23 Jan 2026 22:35:03 +0100 Subject: [PATCH 1/6] docs: add AI coding agent instructions Add AGENTS.md with build commands and architecture overview for coding agents. Add CLAUDE.md that references AGENTS.md. Update .gitignore to exclude Claude Code local settings. Co-Authored-By: Claude Opus 4.5 --- .gitignore | 3 +++ AGENTS.md | 55 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ CLAUDE.md | 1 + 3 files changed, 59 insertions(+) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/.gitignore b/.gitignore index d2eb1a0..37041fb 100644 --- a/.gitignore +++ b/.gitignore @@ -11,3 +11,6 @@ xcuserdata/ # Build I/O .env pkg/ + +# Claude Code +.claude/settings.local.json \ No newline at end of file diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..77e53fa --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,55 @@ +# AGENTS.md + +This file provides guidance to coding agents when working with code in this repository. + +## Build Commands + +```bash +# Install/update dependencies +make install + +# Build debug +make build + +# Build and run a quick test (5 second pomodoro) +make run-test + +# Build release and install to /usr/local/bin +make deploy + +# Run tests +swift test + +# Run a single test +swift test --filter TimeIntervalFormatterTests + +# Format code +make format + +# Lint code +make lint +``` + +## Architecture + +This is a Swift CLI tool built with Swift Package Manager. The executable is `pomodoro-cli`. + +**Target structure:** + +- `PomodoroCLI` - Executable target with `RootCommand.swift` (entry point using swift-argument-parser) +- `Pomodoro` - Library target with core logic +- `PomodoroTests` - Test target + +**Key components in the Pomodoro library:** + +- `TimerViewCLI` - Main CLI view that manages the timer display, progress bar, interrupt handling, and coordinates hooks/logging +- `TimerViewModel` - Tracks timer state (start date, duration, progress) +- `Hook` - Executes shell scripts at pomodoro lifecycle events (didStart/didFinish) from `~/.pomodoro-cli/` +- `LogWriter` - Writes completed pomodoros to `~/.pomodoro-cli/journal.yml` +- `PomodoroDescription` - Value type holding pomodoro data (duration, message, start/end dates) +- `InterruptHandler` - Handles Ctrl+C signals for graceful interruption + +**Dependencies:** + +- `swift-argument-parser` - CLI argument parsing +- `swift-blocks` (dirtyhenry/swift-blocks) - Utility library (provides `CLIUtils`, `Blocks`) diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md From a93d10ace4d63ad17d8287d99310b1a56be0baf5 Mon Sep 17 00:00:00 2001 From: Mick F Date: Fri, 23 Jan 2026 22:41:13 +0100 Subject: [PATCH 2/6] fix: escape single quotes in message for SQL insertion Prevents SQL syntax errors when pomodoro messages contain apostrophes (e.g., "Ed's questions") by escaping single quotes before insertion. Co-Authored-By: Claude Opus 4.5 --- Resources/SampleHooks/mickf-pomodoro-finish.sh | 10 ++++++---- Resources/SampleHooks/mickf-pomodoro-start.sh | 6 +++--- Resources/SampleHooks/sample-pomodoro-finish.sh | 6 +++--- Resources/SampleHooks/sample-pomodoro-start.sh | 6 +++--- 4 files changed, 15 insertions(+), 13 deletions(-) diff --git a/Resources/SampleHooks/mickf-pomodoro-finish.sh b/Resources/SampleHooks/mickf-pomodoro-finish.sh index c270c3f..5fad5a8 100755 --- a/Resources/SampleHooks/mickf-pomodoro-finish.sh +++ b/Resources/SampleHooks/mickf-pomodoro-finish.sh @@ -1,11 +1,11 @@ -#!/usr/bin/env bash +#!/usr/bin/env bash set -e # Check if exactly 4 arguments are provided if [ "$#" -ne 4 ]; then - echo "Usage: $0 arg1 arg2 arg3 arg4" - exit 1 + echo "Usage: $0 arg1 arg2 arg3 arg4" + exit 1 fi # This would stop focus. @@ -26,9 +26,11 @@ CREATE TABLE IF NOT EXISTS $TABLE ( EOF # Insert the 4 arguments into the table +# Escape single quotes for SQL (replace ' with '') +SAFE_MESSAGE="${4//\'/\'\'}" sqlite3 "$DATABASE" < Date: Fri, 23 Jan 2026 22:50:32 +0100 Subject: [PATCH 3/6] fix: correct single quote escaping in bash parameter expansion The previous escaping pattern `${4//\'/\'\'}` doesn't work inside double quotes because `\'` is not a valid escape sequence - bash preserves the backslash literally. Using a variable to hold the single quote character ensures proper matching and replacement. Co-Authored-By: Claude Opus 4.5 --- .github/workflows/linter.yml | 1 + AGENTS.md | 2 +- Resources/SampleHooks/mickf-pomodoro-finish.sh | 7 ++++--- Resources/SampleHooks/mickf-pomodoro-start.sh | 4 ++-- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml index 4fa4ef0..6dd67b2 100644 --- a/.github/workflows/linter.yml +++ b/.github/workflows/linter.yml @@ -40,3 +40,4 @@ jobs: VALIDATE_ALL_CODEBASE: false DEFAULT_BRANCH: main GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + FILTER_REGEX_EXCLUDE: CLAUDE\.md diff --git a/AGENTS.md b/AGENTS.md index 77e53fa..262e442 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -32,7 +32,7 @@ make lint ## Architecture -This is a Swift CLI tool built with Swift Package Manager. The executable is `pomodoro-cli`. +This is a Swift command-line tool built with Swift Package Manager. The executable is `pomodoro-cli`. **Target structure:** diff --git a/Resources/SampleHooks/mickf-pomodoro-finish.sh b/Resources/SampleHooks/mickf-pomodoro-finish.sh index 5fad5a8..19d576f 100755 --- a/Resources/SampleHooks/mickf-pomodoro-finish.sh +++ b/Resources/SampleHooks/mickf-pomodoro-finish.sh @@ -4,8 +4,8 @@ set -e # Check if exactly 4 arguments are provided if [ "$#" -ne 4 ]; then - echo "Usage: $0 arg1 arg2 arg3 arg4" - exit 1 + echo "Usage: $0 arg1 arg2 arg3 arg4" + exit 1 fi # This would stop focus. @@ -27,7 +27,8 @@ EOF # Insert the 4 arguments into the table # Escape single quotes for SQL (replace ' with '') -SAFE_MESSAGE="${4//\'/\'\'}" +SQ="'" +SAFE_MESSAGE="${4//$SQ/$SQ$SQ}" sqlite3 "$DATABASE" < Date: Mon, 9 Feb 2026 19:03:11 +0100 Subject: [PATCH 4/6] style: format code --- Sources/Pomodoro/TimerViewModel.swift | 9 +++++++-- Tests/LinuxMain.swift | 3 +-- 2 files changed, 8 insertions(+), 4 deletions(-) diff --git a/Sources/Pomodoro/TimerViewModel.swift b/Sources/Pomodoro/TimerViewModel.swift index 8aa6693..5ecec17 100644 --- a/Sources/Pomodoro/TimerViewModel.swift +++ b/Sources/Pomodoro/TimerViewModel.swift @@ -35,6 +35,11 @@ class TimerViewModel: TimerViewModelType, TimerViewModelInputs, TimerViewModelOu // MARK: - Define inputs & outputs - var inputs: TimerViewModelInputs { self } - var outputs: TimerViewModelOutputs { self } + var inputs: TimerViewModelInputs { + self + } + + var outputs: TimerViewModelOutputs { + self + } } diff --git a/Tests/LinuxMain.swift b/Tests/LinuxMain.swift index 54f8bd9..1190020 100644 --- a/Tests/LinuxMain.swift +++ b/Tests/LinuxMain.swift @@ -1,6 +1,5 @@ -import XCTest - import pomodoroTests +import XCTest var tests = [XCTestCaseEntry]() tests += pomodoroTests.allTests() From 931197cf1e95e165def904acdfcb65ff23e65585 Mon Sep 17 00:00:00 2001 From: Mick F Date: Mon, 9 Feb 2026 19:09:12 +0100 Subject: [PATCH 5/6] ci: remove super-linter workflow The maintenance overhead outweighs the benefits for this project. Existing make lint/format commands provide sufficient linting. Co-Authored-By: Claude Opus 4.5 --- .github/workflows/linter.yml | 43 ------------------------------------ 1 file changed, 43 deletions(-) delete mode 100644 .github/workflows/linter.yml diff --git a/.github/workflows/linter.yml b/.github/workflows/linter.yml deleted file mode 100644 index 6dd67b2..0000000 --- a/.github/workflows/linter.yml +++ /dev/null @@ -1,43 +0,0 @@ ---- -name: Lint Code Base - -on: - pull_request: - branches: [main] - -############################################ -# Grant status permission for MULTI_STATUS # -############################################ -permissions: - contents: read - packages: read - statuses: write - -jobs: - build: - name: Lint Code Base - runs-on: ubuntu-latest - - ################## - # Load all steps # - ################## - steps: - ########################## - # Checkout the code base # - ########################## - - name: Checkout Code - uses: actions/checkout@v4 - with: - # Full git history is needed to get a proper list of changed files within `super-linter` - fetch-depth: 0 - - ################################ - # Run Linter against code base # - ################################ - - name: Lint Code Base - uses: super-linter/super-linter@v6 - env: - VALIDATE_ALL_CODEBASE: false - DEFAULT_BRANCH: main - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - FILTER_REGEX_EXCLUDE: CLAUDE\.md From 78da6db19d9a5eff99a5a4b3fa659dbd3dac5c9e Mon Sep 17 00:00:00 2001 From: Mick F Date: Mon, 9 Feb 2026 19:11:34 +0100 Subject: [PATCH 6/6] style: fix shell script formatting for shfmt Use tabs for indentation and remove trailing whitespace. Co-Authored-By: Claude Opus 4.5 --- Resources/SampleHooks/sample-pomodoro-finish.sh | 6 +++--- Resources/SampleHooks/sample-pomodoro-start.sh | 4 ++-- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/Resources/SampleHooks/sample-pomodoro-finish.sh b/Resources/SampleHooks/sample-pomodoro-finish.sh index 79c8a72..68d0063 100755 --- a/Resources/SampleHooks/sample-pomodoro-finish.sh +++ b/Resources/SampleHooks/sample-pomodoro-finish.sh @@ -4,8 +4,8 @@ set -e # Check if exactly 4 arguments are provided if [ "$#" -ne 4 ]; then - echo "Usage: $0 arg1 arg2 arg3 arg4" - exit 1 + echo "Usage: $0 arg1 arg2 arg3 arg4" + exit 1 fi # This would stop focus. @@ -31,7 +31,7 @@ fi # VALUES ('$1', '$2', '$4'); # EOF -# Say with an Italian accent that the Pomodoro finished. +# Say with an Italian accent that the Pomodoro finished. /usr/bin/say --voice=Alice "Il pomodoro รจ finito." # Turn off the display after a 10 seconds delay. diff --git a/Resources/SampleHooks/sample-pomodoro-start.sh b/Resources/SampleHooks/sample-pomodoro-start.sh index 3c6fc22..58cd394 100755 --- a/Resources/SampleHooks/sample-pomodoro-start.sh +++ b/Resources/SampleHooks/sample-pomodoro-start.sh @@ -4,8 +4,8 @@ set -e # Check if exactly 4 arguments are provided if [ "$#" -ne 4 ]; then - echo "Usage: $0 arg1 arg2 arg3 arg4" - exit 1 + echo "Usage: $0 arg1 arg2 arg3 arg4" + exit 1 fi # This would start focus