diff options
Diffstat (limited to '.ai/scripts')
| -rwxr-xr-x | .ai/scripts/capture-guard | 91 | ||||
| -rwxr-xr-x | .ai/scripts/flashcard-to-anki.py | 26 | ||||
| -rw-r--r-- | .ai/scripts/tests/capture-guard.bats | 130 | ||||
| -rw-r--r-- | .ai/scripts/tests/test_flashcard_to_anki.py | 31 |
4 files changed, 266 insertions, 12 deletions
diff --git a/.ai/scripts/capture-guard b/.ai/scripts/capture-guard new file mode 100755 index 0000000..6c01f2f --- /dev/null +++ b/.ai/scripts/capture-guard @@ -0,0 +1,91 @@ +#!/usr/bin/env bash +# capture-guard — detect live org-capture buffers visiting a target file +# before a workflow edits that file on disk. +# +# Editing a file on disk while Emacs has an indirect org-capture buffer +# cloned from it reverts the base buffer underneath the capture, wedging it: +# the capture can no longer finalize cleanly with C-c C-c, and a freshly-typed +# item can be lost or written back against post-edit content. inbox.org +# roam mode Phase D edits ~/org/roam/inbox.org, the file Craig captures into constantly, +# so it calls this guard first. See claude-rules/emacs.md. +# +# Usage: capture-guard [--wait[=SECONDS]] [TARGET_FILE] (default ~/org/roam/inbox.org) +# +# Single-shot (default): check once. +# exit 0 — safe to edit: no Emacs, daemon unreachable, or no capture buffer +# visits TARGET_FILE. +# exit 1 — a live capture buffer visits TARGET_FILE; its name(s) printed to +# stdout, comma-separated. +# +# --wait[=SECONDS]: poll until the capture clears or SECONDS elapse (default +# 30), re-checking every ~10s. Org captures are usually transient — a few +# seconds of mid-finalize state — so a short wait clears most false alarms +# before a caller has to surface or skip. Same exit codes: exit 0 the moment +# it's clear, exit 1 if still blocked at the deadline (last buffer list on +# stdout). The common case (nothing capturing) returns instantly without +# sleeping. +# +# Conservative by construction: any uncertainty (no Emacs, query failure) +# resolves to "safe," so the guard never blocks a workflow that would have +# been fine. It only stops the one case it can positively confirm. + +set -euo pipefail + +WAIT_TOTAL=0 +case "${1:-}" in + --wait) WAIT_TOTAL=30; shift ;; + --wait=*) WAIT_TOTAL="${1#--wait=}"; shift ;; +esac + +TARGET="${1:-$HOME/org/roam/inbox.org}" +INTERVAL=10 + +# Names of capture buffers whose base buffer visits TARGET. file-equal-p +# normalizes symlinks and ./.. so the match survives path spelling; it also +# returns nil when TARGET doesn't exist, which collapses to "safe" below. +lisp='(let ((target (expand-file-name "'"$TARGET"'"))) + (mapconcat (function buffer-name) + (seq-filter + (lambda (b) + (and (string-prefix-p "CAPTURE" (buffer-name b)) + (let* ((base (or (buffer-base-buffer b) b)) + (f (buffer-file-name base))) + (and f (file-equal-p f target))))) + (buffer-list)) + ","))' + +LAST_BUFS="" + +# detect — return 0 (safe) or 1 (blocked, name(s) in LAST_BUFS). Any +# uncertainty resolves to safe, matching the single-shot contract. +detect() { + command -v emacsclient >/dev/null 2>&1 || return 0 + emacsclient -e t >/dev/null 2>&1 || return 0 + local bufs + bufs="$(emacsclient -e "$lisp" 2>/dev/null)" || return 0 + bufs="${bufs#\"}" + bufs="${bufs%\"}" + if [ -n "$bufs" ]; then + LAST_BUFS="$bufs" + return 1 + fi + return 0 +} + +# Poll loop. With WAIT_TOTAL=0 (single-shot) it checks once and falls straight +# through to the exit-1 branch on a block, never sleeping. Each sleep is capped +# to the remaining budget so a short --wait never overshoots its deadline. +elapsed=0 +while :; do + if detect; then + exit 0 + fi + if [ "$elapsed" -ge "$WAIT_TOTAL" ]; then + echo "$LAST_BUFS" + exit 1 + fi + remaining=$((WAIT_TOTAL - elapsed)) + step=$((remaining < INTERVAL ? remaining : INTERVAL)) + sleep "$step" + elapsed=$((elapsed + step)) +done diff --git a/.ai/scripts/flashcard-to-anki.py b/.ai/scripts/flashcard-to-anki.py index 7227683..ca4c70b 100755 --- a/.ai/scripts/flashcard-to-anki.py +++ b/.ai/scripts/flashcard-to-anki.py @@ -13,9 +13,11 @@ Parses org-drill structure: text (sans :drill: tag). Back = entry body with newlines converted to <br>. -Deck name defaults to the input basename, case preserved. Deck and model -IDs are derived from the deck name via stable hash so re-importing the -same deck updates existing cards instead of duplicating them. +Deck name defaults to the org #+TITLE: (so the phone deck reads as the +curated title), falling back to the input basename when the source has +no #+TITLE. Deck and model IDs are derived from the deck name via stable +hash so re-importing the same deck updates existing cards instead of +duplicating them. Output defaults to ~/sync/phone/anki/<input-basename>.apkg. The .apkg is a mobile-Anki artifact the phone picks up from its sync dir, so it lands @@ -177,7 +179,19 @@ def build(cards: list[tuple[str, str, str]], deck_name: str) -> genanki.Deck: return deck -def default_deck_name(input_path: Path) -> str: +def default_deck_name(input_path: Path, org_text: str) -> str: + """Deck name defaults to the org #+TITLE:, falling back to the basename. + + The #+TITLE drives both the org-drill display in Emacs and the Anki + deck name on the phone, so the consumed deck reads as the curated + title ("Refutations") rather than the filename slug + ("refutation-drill"). Falls back to the input basename (case + preserved) when the source has no non-empty #+TITLE line. + """ + for line in org_text.splitlines(): + m = re.match(r"^#\+TITLE:\s*(.*\S)\s*$", line, re.IGNORECASE) + if m: + return m.group(1).strip() return input_path.stem @@ -197,7 +211,7 @@ def main() -> int: ) parser.add_argument( "--deck", - help="Deck name. Defaults to the input basename.", + help="Deck name. Defaults to the org #+TITLE, or the input basename.", ) parser.add_argument( "--output", @@ -213,7 +227,7 @@ def main() -> int: return 1 org_text = input_path.read_text(encoding="utf-8") - deck_name = args.deck or default_deck_name(input_path) + deck_name = args.deck or default_deck_name(input_path, org_text) output_path: Path = (args.output or default_output_path(input_path)).expanduser().resolve() output_path.parent.mkdir(parents=True, exist_ok=True) diff --git a/.ai/scripts/tests/capture-guard.bats b/.ai/scripts/tests/capture-guard.bats new file mode 100644 index 0000000..31632a4 --- /dev/null +++ b/.ai/scripts/tests/capture-guard.bats @@ -0,0 +1,130 @@ +#!/usr/bin/env bats +# +# Tests for claude-templates/.ai/scripts/capture-guard — detects live +# org-capture buffers visiting a target file before a workflow edits that +# file on disk (the roam inbox, in inbox.org roam mode Phase D). Editing the file +# underneath an indirect org-capture buffer wedges the capture (see emacs.md). +# +# Contract under test: +# capture-guard [TARGET_FILE] (default TARGET_FILE = ~/org/roam/inbox.org) +# exit 0 → safe to edit: emacsclient absent, daemon unreachable, or no +# capture buffer visits TARGET_FILE. +# exit 1 → a live capture buffer visits TARGET_FILE; its name(s) printed. +# +# Strategy: the emacsclient boundary is mocked with a PATH stub. The stub +# answers the reachability probe (`-e t`) per STUB_REACHABLE and returns a +# canned, real-emacsclient-shaped result (quoted string) for the buffer query +# per STUB_BUFS. The script's own quote-stripping and exit logic is the code +# under test; the file-equal-p precision is real-Emacs behavior we trust. + +SCRIPT="$(cd "$(dirname "$BATS_TEST_FILENAME")/.." && pwd)/capture-guard" +BASH_BIN="$(command -v bash)" + +setup() { + TEST_DIR="$(mktemp -d -t capture-guard-bats.XXXXXX)" + STUB_DIR="$TEST_DIR/bin" + mkdir -p "$STUB_DIR" + + cat > "$STUB_DIR/emacsclient" <<'STUB' +#!/usr/bin/env bash +# Mock emacsclient. `-e t` is the reachability probe; anything else is the +# buffer query, answered with the real-emacsclient-shaped quoted string. +expr="$2" +if [ "$expr" = "t" ]; then + [ "${STUB_REACHABLE:-1}" = "1" ] && { echo t; exit 0; } + exit 1 +fi +printf '%s\n' "${STUB_BUFS:-\"\"}" +exit 0 +STUB + chmod +x "$STUB_DIR/emacsclient" + + EMPTY_DIR="$TEST_DIR/empty" + mkdir -p "$EMPTY_DIR" +} + +teardown() { + rm -rf "$TEST_DIR" +} + +# ---- Safe-to-edit (exit 0) cases ------------------------------------ + +@test "capture-guard: emacsclient absent is safe (exit 0, no output)" { + run env PATH="$EMPTY_DIR" "$BASH_BIN" "$SCRIPT" + [ "$status" -eq 0 ] + [ -z "$output" ] +} + +@test "capture-guard: daemon unreachable is safe (exit 0)" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=0 "$BASH_BIN" "$SCRIPT" + [ "$status" -eq 0 ] + [ -z "$output" ] +} + +@test "capture-guard: reachable with no capture buffers is safe (exit 0)" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='""' "$BASH_BIN" "$SCRIPT" + [ "$status" -eq 0 ] + [ -z "$output" ] +} + +# ---- Blocked (exit 1) cases ----------------------------------------- + +@test "capture-guard: one live capture buffer blocks (exit 1, name printed)" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='"CAPTURE-inbox.org"' \ + "$BASH_BIN" "$SCRIPT" + [ "$status" -eq 1 ] + [[ "$output" == *"CAPTURE-inbox.org"* ]] +} + +@test "capture-guard: multiple live capture buffers all reported (exit 1)" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 \ + STUB_BUFS='"CAPTURE-inbox.org,CAPTURE-2-inbox.org"' \ + "$BASH_BIN" "$SCRIPT" + [ "$status" -eq 1 ] + [[ "$output" == *"CAPTURE-inbox.org"* ]] + [[ "$output" == *"CAPTURE-2-inbox.org"* ]] +} + +@test "capture-guard: blocked output does not contain stray surrounding quotes" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='"CAPTURE-inbox.org"' \ + "$BASH_BIN" "$SCRIPT" + [ "$status" -eq 1 ] + [[ "$output" != \"* ]] + [[ "$output" != *\" ]] +} + +# ---- Argument handling ---------------------------------------------- + +@test "capture-guard: accepts an explicit target-file argument" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='""' \ + "$BASH_BIN" "$SCRIPT" "$TEST_DIR/some-other-inbox.org" + [ "$status" -eq 0 ] + [ -z "$output" ] +} + +# ---- --wait poll mode ----------------------------------------------- + +@test "capture-guard --wait: returns 0 instantly when already safe (no sleep)" { + SECONDS=0 + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='""' \ + "$BASH_BIN" "$SCRIPT" --wait + [ "$status" -eq 0 ] + [ -z "$output" ] + [ "$SECONDS" -lt 2 ] # didn't poll-sleep +} + +@test "capture-guard --wait=1: times out to exit 1 when persistently blocked" { + # Stub always reports the buffer, so it never clears — the short budget + # forces a timeout. Capped sleep keeps this near 1s. + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='"CAPTURE-inbox.org"' \ + "$BASH_BIN" "$SCRIPT" --wait=1 + [ "$status" -eq 1 ] + [[ "$output" == *"CAPTURE-inbox.org"* ]] +} + +@test "capture-guard --wait=N accepts a target after the flag" { + run env PATH="$STUB_DIR:$PATH" STUB_REACHABLE=1 STUB_BUFS='""' \ + "$BASH_BIN" "$SCRIPT" --wait=1 "$TEST_DIR/some-other-inbox.org" + [ "$status" -eq 0 ] + [ -z "$output" ] +} diff --git a/.ai/scripts/tests/test_flashcard_to_anki.py b/.ai/scripts/tests/test_flashcard_to_anki.py index 058b0cd..87008a8 100644 --- a/.ai/scripts/tests/test_flashcard_to_anki.py +++ b/.ai/scripts/tests/test_flashcard_to_anki.py @@ -34,14 +34,33 @@ def test_default_output_path_targets_phone_anki_dir(drill): assert result == Path.home() / "sync" / "phone" / "anki" / "health-drill.apkg" -def test_default_deck_name_is_raw_basename(drill): - """Deck name is the input basename with case preserved; #+TITLE is ignored.""" - assert drill.default_deck_name(Path("/x/deepsat.org")) == "deepsat" +def test_default_deck_name_uses_org_title(drill): + """The #+TITLE drives the Anki deck name, not the filename slug.""" + org = "#+TITLE: Refutations\n* Section\n** Q? :drill:\na\n" + assert drill.default_deck_name(Path("/x/refutation-drill.org"), org) == "Refutations" -def test_default_deck_name_keeps_hyphens(drill): - """A hyphenated basename is kept verbatim rather than title-cased.""" - assert drill.default_deck_name(Path("/x/health-drill.org")) == "health-drill" +def test_default_deck_name_title_is_trimmed(drill): + """Surrounding whitespace on the #+TITLE value is stripped.""" + org = "#+TITLE: DeepSat Flashcards \n" + assert drill.default_deck_name(Path("/x/deepsat.org"), org) == "DeepSat Flashcards" + + +def test_default_deck_name_title_match_is_case_insensitive(drill): + """A lowercase #+title: keyword is still recognized.""" + org = "#+title: Health Flashcards\n" + assert drill.default_deck_name(Path("/x/health-drill.org"), org) == "Health Flashcards" + + +def test_default_deck_name_falls_back_to_basename_without_title(drill): + """No #+TITLE line falls back to the input basename, case preserved.""" + org = "* Section\n** Q? :drill:\na\n" + assert drill.default_deck_name(Path("/x/deepsat.org"), org) == "deepsat" + + +def test_default_deck_name_blank_title_falls_back_to_basename(drill): + """An empty #+TITLE value is ignored in favour of the basename.""" + assert drill.default_deck_name(Path("/x/health-drill.org"), "#+TITLE: \n") == "health-drill" # --- section_to_tag (pure) --- |