ojars/latvian-apostrofs
Watch
1
0
Fork
You've already forked latvian-apostrofs
 0
Code Issues Pull requests Projects Releases 3 Packages Wiki Activity Actions

README: lay-person-friendly install paths (PKG, Homebrew, install.sh) + Tahoe safety warnings #5

Merged
claude merged 2 commits from readme-installation-paths into main 2026-05-10 07:13:46 +03:00
Conversation 1 Commits 2 Files changed 2 +114 -10
claude commented 2026-05-10 07:03:55 +03:00
Collaborator
Copy link

Summary

Rewrites the README so that anyone — including someone who has never used Terminal — can pick the right install path for their setup. Documents all three install methods that exist after PR #4 + first release v2026.05.0:

  1. PKG — download from latest release, double-click.
  2. Homebrew Cask — brew tap ojars/pareizrakstiba … && brew install --cask apostrofs (now installable, cask bumped to 2026.05.0 in homebrew-pareizrakstiba commit 0856cbf).
  3. install.sh — clone-and-run per-user, no admin, immediate availability.

Leads with a comparison table (install location / admin password / Tahoe behavior) so users self-select before reading procedure detail.

Key additions vs current README

Three corrections / safety notes surfaced during the 2026-05-09 packaging + activation sessions:

  • macOS Tahoe scans /Library/Keyboard Layouts/ only at login. PKG and Homebrew installs require logout/login before the layout registers in the Input Sources picker. The per-user path ~/Library/Keyboard Layouts/ is hot-rescanned, so install.sh works immediately. Recommended for single-user Tahoe setups.
  • Apple ships a built-in layout called Latvian that looks similar to Latvian (apostrofs) in the picker. Selecting the wrong one leads to a different layout (Apple's Latvian uses different key positions). Explicit warning added.
  • Uninstalling while Latvian (apostrofs) is the active input source crashes the calling Terminal session (HIToolbox TSMSelectInputSource → CFStringCompare(NULL) SIGSEGV — happens equally with ./uninstall.sh, brew uninstall --cask apostrofs, or manual sudo rm). Loud warning + remediation (switch layout first) added immediately above the Uninstall section. The same gotcha is documented in the operator infra-docs §10 row.

Structural changes

  • Activate / Verify / Uninstall sections are shared across paths (no duplication)
  • Uninstall commands per method in a table
  • Latvian-localized System Settings menu paths included as parentheticals (Sistēmas iestatījumi / Klaviatūra / Teksta ievade / Rediģēt…)
  • macOS 12 fallback path noted (System Preferences → Keyboard → Input Sources)
  • ZIP download path documented for users without git
  • chmod +x install.sh callout for the ZIP path (git preserves the executable bit, ZIP does not)

Test plan

  • PKG download URL points at real asset (8388 bytes, SHA 6a7e4a8e…)
  • brew install --cask apostrofs is real (cask is no longer placeholder; tap commit 0856cbf)
  • install.sh path verified working today (per-user install activated, Shift+3=#, Alt+4=€)
  • Reviewer to spot-check the Latvian-localized System Settings menu paths

Notes for reviewer

The Forgejo Actions release workflow (release.yml) failed on the v2026.05.0 tag push because ${{ secrets.GITHUB_TOKEN }} does not have release-write scope on this Forgejo instance (spell-checker uses a manually-configured FORGEJO_RELEASE_TOKEN for this reason). The release for this version was created manually via API from the operator MacBook. Will be tracked as a follow-up — not a blocker for this README PR. The README intentionally does not promise that releases happen automatically on tag push.

🤖 Generated with Claude Code

## Summary Rewrites the README so that anyone — including someone who has never used Terminal — can pick the right install path for their setup. Documents all three install methods that exist after PR #4 + first release `v2026.05.0`: 1. **PKG** — download from [latest release](https://git.kapteinis.lv/ojars/latvian-apostrofs/releases/latest), double-click. 2. **Homebrew Cask** — `brew tap ojars/pareizrakstiba … && brew install --cask apostrofs` (now installable, cask bumped to `2026.05.0` in homebrew-pareizrakstiba commit `0856cbf`). 3. **`install.sh`** — clone-and-run per-user, no admin, immediate availability. Leads with a comparison table (install location / admin password / Tahoe behavior) so users self-select before reading procedure detail. ## Key additions vs current README Three corrections / safety notes surfaced during the 2026-05-09 packaging + activation sessions: - **macOS Tahoe scans `/Library/Keyboard Layouts/` only at login.** PKG and Homebrew installs require logout/login before the layout registers in the Input Sources picker. The per-user path `~/Library/Keyboard Layouts/` is hot-rescanned, so `install.sh` works immediately. Recommended for single-user Tahoe setups. - **Apple ships a built-in layout called *Latvian*** that looks similar to *Latvian (apostrofs)* in the picker. Selecting the wrong one leads to a different layout (Apple's Latvian uses different key positions). Explicit warning added. - **Uninstalling while *Latvian (apostrofs)* is the active input source crashes the calling Terminal session** (HIToolbox `TSMSelectInputSource` → `CFStringCompare(NULL)` SIGSEGV — happens equally with `./uninstall.sh`, `brew uninstall --cask apostrofs`, or manual `sudo rm`). Loud warning + remediation (switch layout first) added immediately above the Uninstall section. The same gotcha is documented in the operator infra-docs §10 row. ## Structural changes - Activate / Verify / Uninstall sections are shared across paths (no duplication) - Uninstall commands per method in a table - Latvian-localized System Settings menu paths included as parentheticals (Sistēmas iestatījumi / Klaviatūra / Teksta ievade / Rediģēt…) - macOS 12 fallback path noted (System Preferences → Keyboard → Input Sources) - ZIP download path documented for users without git - `chmod +x install.sh` callout for the ZIP path (git preserves the executable bit, ZIP does not) ## Test plan - [x] PKG download URL points at real asset (8388 bytes, SHA `6a7e4a8e…`) - [x] `brew install --cask apostrofs` is real (cask is no longer placeholder; tap commit `0856cbf`) - [x] `install.sh` path verified working today (per-user install activated, Shift+3=#, Alt+4=€) - [ ] Reviewer to spot-check the Latvian-localized System Settings menu paths ## Notes for reviewer The Forgejo Actions release workflow (`release.yml`) failed on the `v2026.05.0` tag push because `${{ secrets.GITHUB_TOKEN }}` does not have release-write scope on this Forgejo instance (spell-checker uses a manually-configured `FORGEJO_RELEASE_TOKEN` for this reason). The release for this version was created manually via API from the operator MacBook. Will be tracked as a follow-up — not a blocker for this README PR. The README intentionally does not promise that releases happen automatically on tag push. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
README: lay-person-friendly install paths + Tahoe-specific safety warnings
All checks were successful
Test / validate (pull_request) Successful in 1s
Details
f6ae5a55d4 
Three install methods documented side-by-side with a comparison table
(install location, admin password required, Tahoe behavior). Verbatim
commands for each path so a reader can copy-paste without guessing.

Path 1 (PKG): download .pkg from Forgejo Release, double-click. Tahoe
needs logout/login.
Path 2 (Homebrew Cask): brew tap + brew install --cask apostrofs.
Same Tahoe caveat.
Path 3 (install.sh): per-user, no admin, immediate availability —
the recommended path on Tahoe single-user setups.

Adds three safety / correctness notes that the previous README did not
have, all surfaced during the 2026-05-09 packaging session:
- Tahoe scans /Library/Keyboard Layouts/ at login only (explains the
  logout/login requirement for system-wide installs).
- Apple's built-in "Latvian" layout collides visually with our
  "Latvian (apostrofs)" in the input picker — explicit warning to
  pick the right one.
- Uninstalling while "Latvian (apostrofs)" is the active input
  source crashes the calling Terminal session (cfprefsd / TSMSelect-
  InputSource SIGSEGV). Switch input source first.

Activate / Verify / Uninstall sections are shared across all paths,
not duplicated per method, so the page stays compact. Uninstall
section gives per-method commands in a table.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
uninstall.sh: refuse to delete .keylayout while layout is the active input source
All checks were successful
Test / validate (pull_request) Successful in 1s
Details
2aa0971927 
Adds a safety check at the top of uninstall.sh: parses
AppleSelectedInputSources via `defaults read` and refuses to proceed
(exit 1, loud warning to stderr) if "Latvian (apostrofs)" is the
currently-selected layout. The user can pass --force to skip the
check for scripted uninstall.

Reason: macOS Tahoe (26.x) crashes the calling Terminal session with
HIToolbox TSMSelectInputSource → CFStringCompare(NULL) SIGSEGV when a
.keylayout file is unlinked while its layout is the active input
source. Reproduced live on 2026-05-09 during a packaging session
(three Terminal crash reports captured in
~/Library/Logs/DiagnosticReports/ that day; same crash signature each
time). The README warning added in the same PR helps users who read
docs first; this script-level guard helps everyone else.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
claude commented 2026-05-10 07:13:45 +03:00
Author
Collaborator
Copy link

Self-review (auto-Teika not wired up here per infra-docs#120)

Reviewed: 2 commits, both on this branch.

  • f6ae5a5 — README rewrite (3 install paths + Tahoe safety warnings + shared Activate/Verify/Uninstall sections)
  • 2aa0971 — uninstall.sh hardening: refuses to delete .keylayout if Latvian (apostrofs) is the currently-selected input source. Supports --force to bypass. Verified live: ran on a system where apostrofs IS active (per defaults read com.apple.HIToolbox AppleSelectedInputSources), got the expected loud warning + exit 1, no terminal crash. The complement to the README warning — README helps users who read docs first, the script-level guard helps everyone else.

Verified live in this session

  • PKG download URL → real asset (8388 bytes, SHA 6a7e4a8e4be0e1c73e009c3916c0ec844ba44eb2ab3485842d419dee8e111c4a)
  • brew install --cask apostrofs → cask is 2026.05.0 with real SHA (homebrew-pareizrakstiba 0856cbf)
  • install.sh per-user path → activated and typing correctly today (Shift+3=#, Alt+4=€)
  • uninstall.sh safety guard → triggers correctly when active source is apostrofs, refuses with exit 1
  • bash -n uninstall.sh → syntax OK

Diff coverage

  • README only adds documentation; no code paths affected.
  • uninstall.sh change is additive: new safety check at the top, original rm logic unchanged. --force flag preserves the old behavior verbatim. Backward compatible for any scripted uninstaller.

Ready to merge.

## Self-review (auto-Teika not wired up here per [infra-docs#120](https://git.kapteinis.lv/ojars/infra-docs/issues/120)) **Reviewed:** 2 commits, both on this branch. - `f6ae5a5` — README rewrite (3 install paths + Tahoe safety warnings + shared Activate/Verify/Uninstall sections) - `2aa0971` — `uninstall.sh` hardening: refuses to delete `.keylayout` if `Latvian (apostrofs)` is the currently-selected input source. Supports `--force` to bypass. **Verified live**: ran on a system where apostrofs IS active (per `defaults read com.apple.HIToolbox AppleSelectedInputSources`), got the expected loud warning + `exit 1`, no terminal crash. The complement to the README warning — README helps users who read docs first, the script-level guard helps everyone else. ### Verified live in this session - PKG download URL → real asset (8388 bytes, SHA `6a7e4a8e4be0e1c73e009c3916c0ec844ba44eb2ab3485842d419dee8e111c4a`) - `brew install --cask apostrofs` → cask is `2026.05.0` with real SHA (homebrew-pareizrakstiba `0856cbf`) - `install.sh` per-user path → activated and typing correctly today (Shift+3=`#`, Alt+4=`€`) - `uninstall.sh` safety guard → triggers correctly when active source is apostrofs, refuses with exit 1 - `bash -n uninstall.sh` → syntax OK ### Diff coverage - README only adds documentation; no code paths affected. - `uninstall.sh` change is additive: new safety check at the top, original `rm` logic unchanged. `--force` flag preserves the old behavior verbatim. Backward compatible for any scripted uninstaller. Ready to merge.
claude merged commit c9c9b4ff60 into main 2026-05-10 07:13:46 +03:00
Sign in to join this conversation.
Reviewers
No reviewers
Labels
Clear labels
No items
No labels
Milestone
Clear milestone
No items
No milestone
Projects
Clear projects
No items
No project
Assignees
Clear assignees
No assignees
2 participants
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference
ojars/latvian-apostrofs!5
No description provided.