From 079fd1eff74edc599a39205a94252db2894b0b78 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Tue, 23 Jun 2026 20:26:21 -0400 Subject: chore(todo): move gptel orphan tasks and API workspace to Someday/Maybe After archiving gptel, I moved its feature backlog (renamed to "GPTel orphan tasks and useful ideas") and the gptel-dependent Org-native API workspace design out of Open Work into Someday/Maybe, each with a note on what happened and why they're kept. Most of the child tool ideas are agent-tool concepts that would transfer to the ai-term agents or an MCP layer, so they're reference rather than active work. --- todo.org | 4222 +++++++++++++++++++++++++++++++------------------------------- 1 file changed, 2120 insertions(+), 2102 deletions(-) (limited to 'todo.org') diff --git a/todo.org b/todo.org index 164f797b8..16d0f3919 100644 --- a/todo.org +++ b/todo.org @@ -2315,2603 +2315,2621 @@ From the color-assignment guide work (2026-06-08): make the tool support the gui [[id:b70b37f2-37df-4c8e-ac2f-1f20d12e33dd][theme-studio-seeding-engine-spec-doing.org]] — role table + face→role maps for syntax/UI/org, OKLCH shade generation, reseed dupre-revised to the compact mapping. Codex-reviewed, Ready. Implementation tracked under the seeding-engine parent below. *** TODO Guide-support views and advisories spec Five optional surfaces, all dismissible and non-blocking, in one collapsible panel where they advise: (1) CVD-simulation toggle on previews (deuteranopia/protanopia/tritanopia); (2) squint/blur preview toggle; (3) lightness-ramp view + palette advisories (accent count over 6-8, roles separated only by red/green) — depends on the OKLCH/ΔE core; (4) definition-vs-call / weight advisories; (5) state-over-syntax preview (region/search/diff tint over real syntax-colored text). Sequence: rewritten guide reviewed → seeding-engine spec → this. Advisories (3, 4) layer on the perceptual-metrics feature. -** CANCELLED [#C] GPTel Feature Extension Brainstorm :feature: -CLOSED: [2026-06-23 Tue] -gptel archived 2026-06-23 to archive/gptel/ (rarely used); extension ideas are moot. Child design notes left below as reference. +** PROJECT [#C] Music Open Work +Parent grouping the open music / EMMS issues; close each child independently. +*** VERIFY [#C] music: extract faces for music config :refactor:quick:solo:next: +Needs from Craig: this is theme-side work, not a config edit — the music-config faces were already stripped (2026-06-14), so "extracting" them means DEFINING them in the theme (theme-studio JSON / build-theme) for playlist name, status, the per-button on/off pair, per-key symbol+text, and other labels. That needs the actual color choices and which theme(s) to add them to. Give me the palette intent (or say "pick sensible defaults in WIP") and I'll add the face definitions. +Pull the music-config faces out to the theme (the config no longer defines faces directly): playlist name, status (paused, etc.), two mode colors per "button" (on vs off), a per-key symbol+text color, and a color for all other labels. Pairs with the 2026-06-14 face-stripping work (music-config faces were removed there and are currently undefined until the theme defines them). From the roam inbox 2026-06-15. +*** TODO [#C] music: show song information in the modeline :feature: +Show basic song information in the modeline, with streaming-source support too. Write a spec for this one first. From the roam inbox 2026-06-15. +*** TODO [#C] Internet radio now-playing song :feature: :PROPERTIES: -:LAST_REVIEWED: 2026-06-01 +:LAST_REVIEWED: 2026-06-11 :END: +Show the currently-playing song while streaming an internet radio station. Lives in =modules/music-config.el= (EMMS + MPV backend, M3U radio stations). The track title comes from the stream's ICY metadata — EMMS exposes it via =emms-track-description= / =emms-playing-time= and updates it on the metadata-change hook; MPV reports the ICY title too. Add an option to show the song in the minibuffer (e.g. echo on track change, or an on-demand command). Consider also a mode-line indicator as a second surface. -Categories below thematize the agent affordances the design doc -[[file:docs/design/gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]] -points at -- Git, Org, messaging, file / buffer / workspace state, -media, and the dev loop. The shortlist's first-batch ADOPT tools -(git_status / git_log / git_diff / web_fetch) already shipped; the -themes below are next-tier work where the agent treats Emacs as a -structured workspace, not a text terminal. Per-theme spec lives in -the task body once written; implementation tasks land as siblings -of the spec heading once the spec is approved. The magit-backend -reimplementation of the shipped git tools is tracked separately in -[[id:bd47c9a8-aae1-4a3d-ad5b-b8767f2fd580][gptel-git-tools-magit-backend-spec.org]]. - -*** TODO [#C] Wire Up MCP.el so That GPTel Has Access to MCP Servers via GPTel Tools +*** VERIFY [#C] music-config option-combination audit + tests :test:next: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-06 +:END: +Deferred from the batch — this is a sizable test-writing audit (pairwise option combinations + new ERT coverage for music-config), better as its own focused /add-tests or /pairwise-tests session than crammed into a bug-fix sweep. No blocker; say the word and I'll run /pairwise-tests over the option space. -**** 2026-05-16 Sat @ 15:44:36 -0500 Spec +Two-part task surfaced 2026-05-28 during the Signel verify walk — generalized from the "are there combinations of options that we'd want to disallow together" question. -Design doc: [[id:b4c274c5-8572-4a7b-b657-d315712bd6af][docs/specs/mcp-el-gptel-integration-spec-doing.org]] +Part 1 — enumerate the configurable option surface of =modules/music-config.el=: every =defcustom=, every behavior toggle, every backend-selection variable, every cross-cutting flag (auto-play, repeat, shuffle, follow-cursor, side-window-height-fraction, etc.). Audit each option for valid value ranges. Capture the matrix in =docs/design/music-config-options.org= (or inline in the test file's header — judgment call when the matrix lands). -**** 2026-05-17 Sun @ 14:14:34 -0500 Landed ai-mcp.el pure-helper foundation +Part 2 — combinatorial test coverage. Use the =/pairwise-tests= skill: identify parameters, value partitions, and inter-parameter constraints, build a PICT model, generate the minimal test matrix that hits every 2-way combination. For each problematic combination the matrix surfaces, decide: (a) validate at config-load time with a =user-error= that names the conflict, (b) runtime guard in the affected command, or (c) doc-only warning in the option's docstring. Disallow only the genuinely-broken pairs; doc-warn the merely-confusing ones. -Commit =54d231be=. Sections 1 (constants + defcustoms) and 3 (pure helpers) of the seven-section outline. 41 ERT tests, all green. Refactor audit caught two duplications during Phase 4 and folded them into the same commit (=cj/mcp--get-server-entry= and =cj/mcp--name-matches-p=). Phase 1.5 (confirmation contract) is next. +The recent F10 side-window-height-fraction work and the EMMS-free refactor candidate ("Implement EMMS-free music-config architecture" above) are both natural near-term touchpoints — best to land this audit before the EMMS swap so the new architecture inherits a clean option spec. -**** TODO [#C] Phase 1.5 -- GPTel confirmation contract +*** TODO [#C] Implement EMMS-free music-config architecture :refactor: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +**** 2026-05-15 Fri @ 19:17:01 -0500 Specification +Implement the design in [[id:423bc355-18d3-4e39-9e7a-f768b865d95b][Design: music-config Without EMMS]]. -*Goal:* flip =gptel-confirm-tool-calls= to ='auto= and gate the existing local tools that need it. +The implementation should make =music-config.el= load without EMMS, introduce +package-owned playlist and track state, add a =cj/music-playlist-mode= view, +and route playback through a small backend protocol with an initial =mpv= +backend. Preserve the current F10 and =C-; m= user workflows where practical, +and keep M3U load/save/edit/reload plus radio station creation working. -*Entry:* Phase 1 module exists and helpers tested. +Complexity estimate: high. This is a module rewrite with a new internal data +model, package-owned playlist mode, backend protocol, mpv process management, +and migration of existing EMMS-backed commands/tests. -*DECISION (cj):* which of the existing local tools register with =:confirm t= once ='auto= is in effect? Reads (=read_buffer=, =read_text_file=, =list_directory_files=, =git_status=, =git_log=, =git_diff=) clearly stay =:confirm nil=. Judgment calls: -- =web_fetch= -- fetches arbitrary URLs the agent supplies. Spec recommends gating. -- =write_text_file= -- writes any path under =$HOME= with agent-supplied content. -- =update_text_file= -- modifies an existing file with an agent-supplied transform. -- =move_to_trash= -- moves a path to trash (reversible but disruptive). +Time estimate: 2-4 focused days for an EMMS-free v1 with play/stop/next/previous, +M3U persistence, playlist UI, and focused tests. Add another 1-2 days if v1 +must include full mpv IPC support for pause, seek, and volume parity. -*Deliverables:* -- =ai-mcp.el= setup section runs =(setq gptel-confirm-tool-calls 'auto)=. -- Remove =(setq gptel-confirm-tool-calls nil)= from =modules/ai-config.el:386= with a comment pointing at =ai-mcp.el=. -- For each tool the decision marks "gate," add =:confirm t= to its =gptel-make-tool= form. -- Tests in =tests/test-ai-mcp-confirm-contract.el= asserting: =gptel-confirm-tool-calls= is ='auto= after load; write-classified stub MCP tool with =:confirm t= triggers the confirm branch in =gptel-send='s dispatch (stub the prompt); read-classified MCP tool with =:confirm nil= does not; =git_log= (=:confirm nil=) still runs without prompting; each newly-gated local tool does prompt. +Acceptance checks: +- =music-config.el= can be required in batch with no EMMS package installed. +- Existing focused music tests pass without EMMS preload or EMMS stubs except + where a compatibility adapter is explicitly under test. +- New tests cover playlist state, backend command dispatch, M3U persistence, + and the EMMS-free load smoke path. -*Exit:* tests green. Manual smoke: open GPTel, call a gated tool, confirm prompt appears. Call =git_log=, no prompt. +**** TODO [#B] Pure helpers + state structs extraction :refactor: +Lift EMMS-free pure code into standalone form: file validation, recursive +collection, M3U parse/write, safe filenames, radio-station content, and +URL/file track typing. Introduce =cj/music-track= and =cj/music-playlist= +cl-structs plus state-mutation helpers (=cj/music-playlist-*= predicates and +setters). Files: =modules/music-config.el=, possibly a new +=modules/music-state.el= split. Existing pure-helper tests should pass +unchanged. -**** TODO [#B] Phase 2 -- Compat layer + registration pipeline (fake inventory) +Acceptance: structs defined, helpers callable in batch without EMMS loaded. -*Goal:* implement the mcp.el compat wrappers and the tool-registration pipeline against stubbed =mcp-server-connections=. +Depends on: none (start here). -*Entry:* Phase 1.5 proves gptel respects per-tool =:confirm= slot. +**** TODO [#B] Backend protocol + fake test backend :refactor:test: +Define the backend plist contract (=:available-p :play :pause :resume :stop +:seek :volume :status :metadata=) and =cj/music-current-backend=. Add +=cj/music-state-change-functions= abnormal hook with the v1 event set +(=started=, =paused=, =resumed=, =stopped=, =finished=, =error=, +=playlist-changed=, =mode-changed=). Create =tests/testutil-music-backend.el= +exposing =cj/test-music-fake-backend= with an event ledger. -*Deliverables:* -- Section 4 of =ai-mcp.el= (compat layer): =cj/mcp--server-status=, =cj/mcp--server-tools=, =cj/mcp--server-name=, =cj/mcp--assert-capabilities=. Each helper documents the upstream commit / file location it targets. -- Section 5 of =ai-mcp.el= (registration pipeline): =cj/mcp--register-tool=, =cj/mcp--register-server-tools=, =cj/mcp--deregister-server-tools=, =cj/mcp--rewrite-plist=, =cj/mcp--registered-tools= hash. -- All MCP tools register with =:async t=. -- Tests in =tests/test-ai-mcp-registration.el=. +Acceptance: fake backend installable in tests; ordered-event assertions work +against a no-op playback flow. -*Exit:* with a stubbed =mcp-server-connections=, registration produces correctly prefixed =mcp__SERVER__TOOL= entries in =gptel-tools=; closures call =mcp-call-tool SERVER REMOTE-NAME= (verified by stubbing =mcp-async-call-tool=); deregistration removes only MCP-owned tools and leaves a pre-populated local =git_log= entry intact; re-registration replaces function pointer without duplicating menu entries; confirm overrides win over patterns. +Depends on: pure helpers + state structs. -**** TODO [#B] Phase 3 -- Async state machine + timer-race timeout wrapper +**** TODO [#B] Read-side state API + characterization tests :test:refactor: +Implement =cj/music-playing-p=, =cj/music-paused-p=, =cj/music-current-track=, +=cj/music-playlist-state=, =cj/music-track-description=. Before rewriting +command bodies, add characterization tests against current behavior for +=cj/music-next=, =cj/music-previous=, =cj/music-toggle-consume=, +=cj/music-playlist-toggle=, =cj/music-playlist-load=, =cj/music-playlist-clear= +so the migration has a safety net. -*Goal:* implement the lifecycle state machine and the per-call timer-race timeout. +Acceptance: read-side helpers covered; characterization tests green against +the current EMMS-backed implementation. -*Entry:* Phase 2 registration works against stubs. +Depends on: backend protocol + fake test backend. -*Deliverables:* -- Section 6 of =ai-mcp.el= (async state machine): =cj/mcp--state=, =cj/mcp--server-status= alist, =cj/mcp--stall-timer=, =cj/mcp-ensure-started=, =cj/mcp--on-hub-callback=, =cj/mcp--poll-status=, =cj/mcp--start-stall-timer=, =cj/mcp--build-status-from-specs=. -- =cj/mcp--wrap-async-with-timeout= (timer/callback race; both branches set =done= before invoking gptel callback so late responses are ignored). -- Tests in =tests/test-ai-mcp-async.el=. +**** TODO [#B] Playlist major mode + render-from-state :feature: +Add =cj/music-playlist-mode= rendering the buffer as a view over +=cj/music-current-playlist=. Selected-track overlay + face, header reads +package state, full keymap from design Section "Playlist Buffer" (RET/p, SPC, +s, >/<, f/b, +/=/-, a, A, c/C, L/S/E/g, r/t/z/x, Z, i, o, q, S-up/down). +Preserve the active-window background highlight. -*Exit:* =cj/mcp-ensure-started= returns in <100 ms with delayed-callback stubs; stall timer fires for stuck servers; timer-race wrapper handles all three orderings (MCP-first, timer-first, late-MCP-after-timer); async error path (=:error-callback= without inited callback) reaches =failed= state via polling. +Acceptance: opening the playlist renders package state; reorder/shuffle/clear +go through state mutations and re-render; tests cover header + overlay +positioning. -**** TODO [#B] Phase 4 -- First real connection (drawio or slack-deepsat) +Depends on: read-side state API. -*Goal:* wire one real no-auth server end-to-end against actual mcp.el and prove the stubbed Phase 3 behavior matches reality. +**** TODO [#B] mpv backend implementation :feature: +Implement =cj/music-mpv-*= backend functions. Phase the work per migration +plan §5: (a) process spawn, UID/PID-stamped socket under +=temporary-file-directory=, stale-socket sweep, IPC connect via +=make-network-process :family 'local=, state-hook plumbing. (b) play/stop/ +next/previous + finished-track auto-advance with deliberate-stop tracking. +(c) pause/resume, seek, volume over JSON IPC. (d) metadata read on track +start. Add =cj/music-doctor= reporting platform capabilities; ship Windows +degraded mode (play/stop/next/previous only via stdin/=call-process=). -*Entry:* Phase 3 async works against stubs. +Acceptance: integration tests tagged =:slow= and skipped when =mpv= not on +PATH; on Linux/macOS pause/seek/volume parity works; clean socket lifecycle +across Emacs restart and exit. -*Deliverables:* -- Add =use-package mcp= to =ai-mcp.el= (MELPA active, =:load-path= for local checkout commented). -- =cj/mcp--assert-capabilities= called at load time; signals clearly if mcp.el is too old. -- Set =cj/mcp-enabled-servers= temporarily to =("drawio")= (or =("slack-deepsat")= if the local proxy is running). -- First real =cj/mcp-ensure-started= invocation from =cj/toggle-gptel=. +Depends on: backend protocol + fake test backend. -*Exit:* manual smoke -- =C-; a t= opens GPTel without blocking; within 30 s, drawio (or slack-deepsat) tools appear in =gptel-menu= grouped by category; calling a tool returns expected output; killing the subprocess externally surfaces as =failed= in =cj/mcp--server-status=. +**** TODO [#B] Command + Dired/Dirvish rewire :refactor: +Migrate user-facing commands (=cj/music-play=, =cj/music-pause=, +=cj/music-stop=, =cj/music-next=, =cj/music-previous=, seek/volume, +random/repeat/consume/shuffle toggles) to operate on package state and call +=cj/music-current-backend=. Update Dired/Dirvish =+= add routing, +M3U load/save/edit/reload, radio-station creation, F10 toggle, and =C-; m= +keymap entries to drop EMMS symbols. Migrate command-flow tests to the fake +backend. -**** TODO [#B] Phase 5 -- Status UX + commands + doctor (static) +Acceptance: full keymap functional end-to-end against the fake backend; +characterization tests still green; Dirvish =+= add path covered. -*Goal:* ship the full server-management UX so partial-availability and failures are visible. +Depends on: playlist major mode + mpv backend. -*Entry:* Phase 4 proves a real connection works. +**** TODO [#B] EMMS removal + parity walk :test: +Remove =cj/emms--setup=, the on-demand EMMS loader, and the =use-package emms= +block. Add the EMMS-free batch-load smoke test (=music-config.el= requires +clean without EMMS installed). Run the 22-step parity walk from design +§"Parity Walk" against the new implementation; record measurements against +the performance budget (1000-track load <500ms, reorder <50ms, IPC dispatch +<100ms, header refresh <16ms) and note any deviations. -*Deliverables:* -- Section 7 of =ai-mcp.el= (UI). -- Commands: =cj/mcp-status= (echo-area summary keyed off =cj/mcp--state=), =cj/mcp-list-tools= (tabulated buffer with failed servers at top in red face; keys =g r c RET q=), =cj/mcp-doctor= (static mode only -- capability, =npx=/=uvx=, Claude config, per-server env, local endpoints; output buffer keys =c r q=), =cj/mcp-wait-until-ready=, =cj/mcp-hub= (thin wrapper that ensures startup first), =cj/mcp-restart-failed=, =cj/mcp-restart-server=, =cj/mcp-stop-all=. -- Keymap: =C-; a C= subprefix bound in =ai-config.el='s autoload section. Keys =h s l r R S d w=. -- which-key labels for every binding. -- =kill-emacs-hook= registration for =cj/mcp-stop-all=. -- Investigation: does =gptel-menu= refresh after mid-call tool registration? Document the answer in =ai-mcp.el= commentary; if it requires close+reopen, add to known UX caveats. +Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity +walk recorded as a completion log entry under the parent task. -*Exit:* all keymap bindings work; audit buffer surfaces failed servers prominently; doctor identifies each scenario in the manual test matrix; status command shows the right state for each phase transition. +Depends on: command + Dired/Dirvish rewire. -**** TODO [#B] Phase 6 -- HTTP servers (linear, notion) +** PROJECT [#C] Calibre Open Work +:PROPERTIES: +:LAST_REVIEWED: 2026-06-06 +:END: +Parent grouping the open Calibre / ebook-workflow issues; close each child independently. The EPUB reading-width tasks were already resolved (2026-05-12/14). -*Goal:* add the two HTTP-transport servers with in-protocol OAuth. +*** 2026-06-12 Fri @ 07:34:05 -0500 Calibre bookmark naming ships "Author, Title" from the filename +When I hit m in calibre, I'm making my place in the book with a bookmark. +While sometimes, the books look fine: "The A.B.C. Murders - Agatha Christie.epub" +Sometimes they look not so good: Engines of Logic_ Mathematicians and the O - Martin Davis.pdf or Software Architecture_ The Hard Parts _ Mo - Neal Ford.pdf -*Entry:* Phase 5 UX shipped. +What I would like to do is to have the bookmarks be saved in the following format: -*Deliverables:* -- Add =linear= and =notion= back to =cj/mcp-enabled-servers=. -- Doctor gains live-auth-check mode (=C-u C-; a C d=): invokes a single safe read per auth class to verify OAuth tokens haven't silently expired. Static checks first; live probe only fires after static passes. -- OAuth recovery pattern matcher surfaces auth URLs in =cj/mcp-status= on first connect. +Author, Title [no extension]. Underscores should be stripped. -*Exit:* first connect surfaces the OAuth URL through the recovery pattern; after browser handshake completes, subsequent connects succeed without prompt; live-auth-check correctly identifies a deliberately revoked token; both servers appear ready in the audit buffer. +Root cause: in a nov buffer =m= is =bookmark-set= (rebound at calibredb-epub-config.el:311); nov's =nov-bookmark-make-record= names the record =(buffer-name)= -- the EPUB filename. -**** TODO [#B] Phase 7 -- Env-dependent stdio servers (figma, google-*) +Implemented 2026-06-06. Source decision: parse the *filename*, not the embedded EPUB metadata -- under Calibre's " - <Author>.epub" naming the filename is more complete (the embedded metadata had truncated titles, author-sort "Last, First" forms, and lost punctuation; see the separate metadata-cleanup task). A =:filter-return= advice on =nov-bookmark-make-record= rebuilds the name from the record's filename: split on the last " - " into title/author, restore the colon Calibre sanitized to "_ " (-> ": "), reorder to "Author, Title". Pure helpers =cj/--nov-clean-title= + =cj/--nov-bookmark-name-from-file= in =modules/calibredb-epub-config.el=; 10 ERT tests in =tests/test-calibredb-epub-config--bookmark-name.el=. Live in the daemon. -*Goal:* add the remaining five env-dependent servers. +Existing bookmarks: the 3 nov bookmarks in =~/sync/org/emacs_bookmarks= were renamed by hand (one-pass, in the daemon + saved; backup at =emacs_bookmarks.bak-2026-06-06=): "Edward Kanterian, Frege: A Guide for the Perplexed", "Agatha Christie, The A.B.C. Murders", "Edward Abbey, The Fool's Progress: An Honest Novel". -*Entry:* Phase 6 HTTP servers connect cleanly. +Manual verify filed under the Manual testing and validation parent. -*Deliverables:* -- Add =figma=, =google-calendar=, =google-docs-personal=, =google-docs-work=, =google-keep= to =cj/mcp-enabled-servers=. -- Verify env-merge from =~/.claude.json= for each (the mtime-cached reader from Phase 1). -- Verify figma's =:secret-args= splicing places the API key correctly without echoing it. -- Manual smoke: simulate token expiry on one Google server; recovery message points at "re-auth via Claude Code, then C-; a C r SERVER". +*** 2026-06-12 Fri @ 07:34:05 -0500 Curated Calibre keybinding menu + docked description shipped +Relocated from the global capture inbox 2026-06-06. Want a discoverable set of keybindings (visible in which-key) for the most frequent calibredb workflows: +- Switch to a library (e.g. Literature), sort by last name, scroll the list. +- Scope/filter the list in place, keeping the current library scope: + - by format (e.g. epubs only) + - by author last name (exact == or ^begins-with some text) + - sort by title, publication date, or group by format +- One key pops up the selected book's description in a bottom-30% buffer, dismissed with q (same display pattern as the signel chat dock). +- RET opens the book in the appropriate viewer. +Survey finding 2026-06-06: calibredb already binds almost all of this in calibredb-search-mode-map (S/L library, g filter [f format, a author, t tag, d date], o sort [t title, a author, p pubdate, f format], RET open) and even ships transient menus (? = calibredb-dispatch, g, o). The real problem was discoverability -- they are top-level single keys (which-key never pops up) and Craig didn't know ? opened a menu. calibredb-quick-look is macOS-only; the detail view (v -> *calibredb-entry*, q quits) is the description but opens full-window. -*Exit:* all 9 servers reach =ready= state on a clean machine. Sentinel-grep check across status / audit / hub / errors / audit-log shows zero secret leakage. Doctor's live-auth covers each auth class (oauth, token, args-token, in-protocol, local, none). +Implemented 2026-06-06 in =modules/calibredb-epub-config.el=: +- A curated transient =cj/calibredb-menu= (library switch; filter format/author/reset; sort author/title/pubdate/format; open; describe; H = full calibredb-dispatch) bound to =?= in calibredb-search-mode-map. calibredb's own full dispatch moved to =H=. Defined in the use-package =:config= (needs the elpa transient, which batch doesn't load) -- the "? brings up a curated help menu" convention. +- Bottom-30% description dock: =calibredb-show-entry-switch= -> =pop-to-buffer= + a =display-buffer-alist= rule for =*calibredb-entry*= (display-buffer-at-bottom, height 0.3); =cj/calibredb-describe-at-point= shows the entry without switching focus so q dismisses it. Same pattern as the signel chat dock. +1 ERT test (the describe command; the transient/bindings/dock need the elpa transient + live calibredb, verified in the daemon). Author "begins-with" is covered well enough by g a's completing-read over "Last, First"; a true regex filter was not built. Manual verify filed under the Manual testing and validation parent. -**** TODO [#B] Phase 8 -- Privacy + audit polish +*** TODO Embed Calibre DB metadata into the EPUB files +Surfaced 2026-06-06 while building the bookmark naming: the metadata embedded in the EPUB files' OPF is worse than Calibre's database metadata. nov reads the embedded OPF and got truncated titles ("Frege" vs the filename's "Frege: A Guide for the Perplexed"), author-sort "Last, First" forms ("Christie, Agatha"), and lost punctuation ("A.B.C." -> "A B C"). The filenames (from Calibre's curated DB) are the good copy. Fix on the Calibre side: select all (or by library), run "Edit metadata -> Embed metadata into book files" so the DB metadata is written into each EPUB's OPF. Consider auditing author vs author_sort first. After embedding, the in-file metadata matches the library and any tool reading the files (nov, other readers, re-imports) gets the good data. Not an Emacs task; Calibre-side bulk maintenance. -*Goal:* land the final UX polish and documentation. +** PROJECT [#C] 2026-06 full config audit — findings backlog :refactor: +Module-by-module review of all 121 modules + init/early-init, holistic passes (startup/perf, stability, UX consistency, package strategy), and spin-offs into pearl, chime, emacs-wttrin. Method: parallel read-only review agents per module group; key claims spot-verified (incl. against the live daemon) before filing. Run 2026-06-11/12, COMPLETE. Tally: ~165 module findings + ~40 holistic + 30 spin-off ≈ 235 total; 40 high-impact bugs filed as standalone tasks above this parent; the rest live in the group children below. Spin-off findings delivered as inbox handoffs to pearl, chime, and emacs-wttrin (2026-06-12-0057). Start with the synthesis child below for the recommended attack order. -*Entry:* all 9 servers working. +*** Synthesis: the overall picture and attack order +Six cross-cutting themes, then the order I'd work them. -*Deliverables:* -- Audit buffer privacy header: "Tool results land in =gptel-tools= responses; saved conversations persist them. Use =cj/gptel-autosave-toggle= per buffer to opt out." -- =cj/mcp-tool-audit-log-enabled= defcustom + log writer (=~/.emacs.d/data/mcp-tool-log/YYYY-MM-DD.log= -- metadata only, one line per call, daily rotation). -- =ai-mcp.el= commentary updated with the code-organization outline as a table of contents. -- Final pass on tests covering saved-conversation behavior (autosave persists MCP tool results; toggling off prevents persistence). +Themes: +1. Performance has one systemic lever, not many small ones: native-comp is accidentally OFF config-wide and GC sits at the stock 800KB ([#A] task). Daemon init itself is healthy (1.11s measured). Fix the lever before any micro-deferral work, and before burning time on the org-capture-perf debug. +2. A "dangerous defaults" safety cluster: yes-or-no-p fset (single-keystroke shutdown/file-destruction), the silently-failing Wayland lock screen, erc-yank's public gists, mu4e's broken trash/refile on the primary account. All four are [#A]/[#B] standalones; do these first — they're where the config can actually hurt you. +3. Calendar/agenda data correctness: calendar-sync's RFC trio (vanishing final occurrences, resurrected cancelled meetings, collapsed multi-day events) + agenda sources missing roam Projects. Meetings are missed over this. +4. Recurring mechanical defect classes worth sweeping as one commit each, config-wide: use-package :hook "-hook" suffix trap (org-babel, eshell, latex); eval-when-compile-only requires read at runtime (auth-config, keyboard-macros, erc-config); M-S-<letter> bindings vs uppercase events (4 dead keys + 1 asymmetry); raw C-; entries bypassing cj/register-prefix-map (8 modules); unreachable modules (prog-lsp, ledger-config, show-kill-ring, mu4e-org-contacts-setup); config for package versions long gone (mu4e 1.7 block, dashboard override, org timeline, checkdoc-arguments). +5. The test suite has a blind-spot class: characterization tests asserting BROKEN output (reverse-lines, heavy-box, undo-kill's explicit 0), unit tests hand-building data that hides integration mismatches (F7 coverage paths), and an integration gate that prints green over "Ran 0 tests" (chime). When fixing any standalone bug above, fix its test to assert correct behavior — and consider extending the architecture smoke test to mechanically pin the class-4 sweeps (hooks must be bound after load, no raw C-; binds, no M-S-<letter> specs, no eval-when-compile requires of runtime vars). +6. Consistency wants conventions, not patches: one notification facade (cj/notify — messenger spec addendum already covers the messenger half), one confirmation tier (the fset fix), one prefix-registration mechanism with labels, one buffer-naming shape. The messenger-unification registry mindset generalizes. -*Exit:* all 10 acceptance criteria from the spec pass. Manual matrix run end-to-end on a fresh Emacs. Working tree clean. +Attack order: (a) the three [#A]s + gptel-shadow (it's blocking the filed gptel-magit investigation); (b) the daily-data pair — mail trash/refile + calendar RFC trio; (c) the :quick:solo: standalone sweep — roughly 20 one-to-five-line fixes, a satisfying solo batch; (d) the class-4 mechanical sweeps, one commit per class, each with its smoke-test guard; (e) the consistency conventions, opportunistically as those modules get touched. -*** TODO [#C] Wrap the gh CLI as a GPTel tool +*** TODO Findings: foundation/system group +From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: +- [BUG] =keyboard-compat.el:121= — terminal arrow-key fix runs once on emacs-startup-hook; =input-decode-map= is terminal-local, so =emacsclient -t= frames under the daemon never get it. Register on =tty-setup-hook= (GUI half already uses =server-after-make-frame-hook=). +- [BUG] =config-utilities.el:142= — =cj/recompile-emacs-home=: =(boundp 'native-compile-async)= is always nil (it's a function — needs =fboundp=), so native compilation is never selected; and the helper deletes =<dir>/eln= when the real cache is =eln-cache/= (derive from =native-comp-eln-load-path=). Extend the existing test. +- [BUG] =system-utils.el:94= — success message args swapped: prints "Running notes.txt on mpv...". Trivial; wired into dirvish (O) and calibredb so it shows regularly. +- [REMOVE] =local-repository.el:51= — =localrepo-initialize=, its three defcustoms, and unprefixed =car-member= are dead; early-init owns archive setup with its own divergent path constant. Shrink to =cj/update-localrepo-repository= pointed at early-init's =localrepo-location=. +- [REMOVE] =keybindings.el:146-147= — C-x C-f unset/reset is a no-op (already find-file); comment wrong. Delete or retarget. +- [COVERAGE] =local-repository.el= — only module in the group with no test file. -**** 2026-05-16 Sat @ 16:20:00 -0500 Spec +*** TODO Findings: UI core group +From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: +- [BUG] =font-config.el:262= — emojify =:defer 1= means :config runs before any daemon GUI frame exists; =env-gui-p= picks ='unicode= permanently, GUI frames never get image emojis. Compute per-frame (=server-after-make-frame-hook=) or test =(daemonp)=. +- [BUG] =font-config.el:283= — =cj/display-available-fonts= errors on second invocation: first call's =special-mode= sets read-only; next call's erase/insert signals. Wrap in =inhibit-read-only=. (Also [COVERAGE]: untested — a call-twice test catches it.) +- [UX] =undead-buffers.el:82= — =cj/kill-other-window= in a single-window frame kills the buffer you're looking at (other-window no-ops; only delete-window is guarded). Add the sibling's =(user-error "No other window")= guard. +- [UX] =undead-buffers.el:48= — C-u C-x k silently marks a buffer undead (then it refuses to die with no explanation later). Undocumented mode-switch inside a core-command remap; document or split into its own command. +- [ENHANCE] =ui-theme.el:87= — theme persistence silently fails on a fresh machine until =persist/= exists; =make-directory= before the writability check. +- [REMOVE] =dashboard-config.el:32-58= — =dashboard-insert-bookmarks= override is dead code: the :demand t require lets upstream dashboard-widgets.el redefine it; behavior survives only because upstream natively honors the settings now. Delete. +- [REMOVE] =font-config.el:199-220= — all-the-icons stack (2 =:demand t= packages + unprompted network font install on fresh machines) likely redundant with nerd-icons everywhere; verify keyboard-compat's reference then drop. +- [REMOVE] =ui-config.el:185= — duplicate =(use-package nerd-icons :defer t)= stanza; nerd-icons-config owns it. Delete stanza + stale Commentary bullet. -Design doc: [[id:a124dd0f-1f40-4533-aeb8-595d93e20865][docs/specs/gptel-gh-tool-spec.org]] +*** TODO Findings: buffer/window libs group +From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: +- [REMOVE] =show-kill-ring.el= — loaded by nothing (init require deliberately removed in b785a19d), so its M-S-k binding is dead; =keyboard-compat.el:177= still installs the M-K → M-S-k translation whose only purpose was this module. Re-add or delete module + stale translation/comment (consult-yank-pop largely supersedes it). +- [UX] =selection-framework.el:38= — =vertico-sort-function= custom is dead config: =vertico-prescient-mode= (line 250) replaces sorting when it activates. Pick one policy (drop the custom, or =vertico-prescient-enable-sorting nil=). +- [BUG] =custom-buffer-file.el:486= — =cj/view-email-in-buffer= leaks MIME handles when no displayable part: =user-error= fires before =mm-destroy-parts=. unwind-protect. +- [ENHANCE] =custom-buffer-file.el:49= — eager =(require 'mm-decode)= at startup only for macro expansion; runtime require already exists at line 481. Make it =eval-when-compile=. +- [UX] =custom-buffer-file.el:221= — =cj/copy-link-to-buffer-file= is a silent no-op in non-file buffers while siblings signal =user-error=. Match them. -*** TODO [#C] GPTel should autosave regularly after a conversation is saved -*** TODO [#B] Org Workflow Related Tools +*** TODO Findings: editing helpers group +From agents 2026-06-11; spot-verified sample (jump-paren, sortable-time confirmed). Beyond the standalone heavy-box task: +- [BUG] =custom-misc.el:48= — jump-to-matching-paren with point ON a closer lands at the last inner sexp, not the opener (batch-verified). =(forward-char)= before =(backward-sexp)= in the char-after-closer case; the test only covers the after-closer position. +- [BUG] =custom-datetime.el:71= — "sortable" time format is 12-hour ="%I:%M:%S %p %Z"= — "01:00:00 PM" sorts before "09:00:00 AM". Should be ="%H:%M:%S"=. +- [BUG] =custom-comments.el:82= — =cj/comment-reformat= prints "No region was selected" even on success (message outside the if-else), and the fill-column shrink/restore isn't unwind-protected — an error leaves fill-column permanently -3. Use let-binding + =user-error=; also =mark-active= vs the config's usual =use-region-p=. +- [BUG] =custom-line-paragraph.el:52= — join-line-or-region without region inserts a spurious blank line mid-buffer (verified); only insert the newline at eobp. +- [BUG] =custom-line-paragraph.el:77= — duplicate-line-or-region splits a mid-line-ending region via open-line and duplicates an extra empty line when the region ends at bol. Normalize bounds to whole lines. +- [BUG] =custom-ordering.el:158= — reverse-lines and number-lines mishandle the trailing newline ("a\nb\n" → "\nb\na"); the trailing-newline test asserts the broken output. =cj/--arrayify= (line 43) has the correct pattern — apply it; fix the characterization test. +- [BUG] =custom-comments.el:152= — inline-border lines come out 2 chars short for even-length or empty text (parity computed from text length instead of remaining width); stacked dividers misalign. +- [UX] =custom-text-enclose.el:216= — indent-lines =(interactive "p\nP")= couples COUNT and USE-TABS to one prefix arg — multi-column space indent is impossible interactively; docstrings claim "default 4" but "p" defaults to 1 (same in dedent :256). +- [REMOVE] =custom-ordering.el:90= — =cj/arrayify-python= is byte-identical to =cj/arrayify-json= (two bindings, same output). Delete one or differentiate (single quotes for Python). +- [UX] =custom-case.el:66= — title-case contradicts its docstring: "is" is in word-skip despite "linking verbs are major words"; no sentence-restart capitalization after periods; no capitalize-last-word rule. Align list + docstring. -Affordances that expose the Org workspace -- agenda state, capture -targets, org-roam nodes and backlinks, dailies, drill review state -- -to the agent as structured context, not raw .org buffer text. +*** TODO Findings: text/prose tools group +From agents 2026-06-11. Beyond the standalone markdown/latex tasks: +- [BUG] =text-config.el:72= — "M-S-i" for edit-indirect-region is unreachable: Meta+Shift+i generates the event M-I, not M-S-i, so the keypress falls back to M-i tab-to-tab-stop. Rebind as "M-I" (the "was M-I" comment thought the rename was a no-op; it wasn't). +- [BUG] =keyboard-macros.el:46= — user-constants required only =eval-when-compile= but =macros-file= is read at runtime; works only because init.el loads user-constants first. Plain require (same trap as auth-config). +- [BUG] =keyboard-macros.el:137= — kill-emacs-hook fires =y-or-n-p= + an interactive name prompt whenever any last-kbd-macro exists — hazardous for daemon/systemd shutdown (no one to answer) and noisy for throwaway macros. Guard =(and last-kbd-macro (not noninteractive))= minimum; consider dropping the prompt (M-F3 already persists named macros). +- [BUG] =lorem-optimum.el:221= — empty Markov chain (missing assets/liber-primus.txt) makes =cj/lipsum-insert= do =(insert nil)= — cryptic wrong-type error far from cause. Signal =user-error= naming the fix; also Commentary advertises "M-x cj/lipsum" but it has no interactive spec. +- [UX] =flyspell-and-abbrev.el:230= — every C-' press re-runs =flyspell-buffer= over the whole buffer while flyspell-mode is off (the documented word-by-word workflow = O(buffer) per keypress in large files). Call =cj/flyspell-on-for-buffer-type= so the mode sticks and the scan runs once. +- [ENHANCE] =text-config.el:121= — accent is wired to the company backend (=accent-company=); the filed Company→Corfu migration task doesn't list it, so C-` breaks silently post-migration. Add to the migration scope or switch to =accent-menu= now. -**** TODO [#B] Agenda state tools :feature: +*** TODO Findings: org core group +From agents 2026-06-11; spot-verified sample (dailies head, babel hook, void bindings confirmed). Beyond the standalone tasks: +- [BUG] =org-babel-config.el:27= — =:hook (org-babel-after-execute-hook . org-redisplay-inline-images)= gets a second "-hook" appended (symbol unbound at expansion, doesn't end in -mode) → registers on nonexistent =org-babel-after-execute-hook-hook=; inline dot-graph images never refresh after C-c C-c. Write =(org-babel-after-execute . ...)= or add-hook in :config. +- [BUG] =org-roam-config.el:67,71= — C-c n p / C-c n w bound (and which-key-labeled) to =cj/org-roam-find-node-project= / =-webclip=, defined nowhere — keypress errors "autoloading failed to define function". Define via =cj/org-roam-find-node= (a project template exists) or drop bindings + labels. +- [BUG] =org-export-config.el:74-81= — ox-texinfo block can never run (=:defer t=, no trigger, excluded from line-47 dolist and =org-export-backends=); commentary still advertises Texinfo. Add to the dolist or delete; also commentary says "subtree default scope" vs actual ='buffer= (line 61). +- [UX] =org-roam-config.el:50-63= — two parallel template dirs drift: :custom templates read =~/.emacs.d/org-roam-templates/= while find-node-topic/recipe read =roam-dir/templates/= — overlapping recipe/topic/v2mom files, edits don't propagate. Pick one canonical dir. +- [REMOVE] =org-agenda-config.el:84= — dead =timeline= entry in org-agenda-prefix-format (removed in org 9.1). Also =org-config.el:47-48= — the TASK note claiming =org-indent-indentation-per-level= "doesn't exist" is wrong (real org-indent defcustom); restore the setq or fix the comment. +- [REMOVE] =org-babel-config.el:161= — =org-html-footnote-separator= is an ox-html setting parked in the babel module with a wrong comment; =org-roam-config.el:76= similarly hides =org-agenda-timegrid-use-ampm= in roam's :config (only takes effect after roam loads). Move both to their owning modules. +- [REMOVE] =org-roam-config.el:363-390= — 28-line commented consult-org-roam block on a TASK comment; its proposed C-c n l / C-c n r now collide with live bindings, so it can't ship as written. Decide + delete (git keeps the draft). +- [COVERAGE] =org-agenda-config.el:423= cj/add-timestamp-to-org-entry (defvar-inside-defun smell), =org-roam-config.el:115,185= node-insert-immediate + finalize-hook — untested. -Read scheduled / deadline / waiting tasks for a date range; query by -tag, priority, or TODO keyword; list what's blocking today. Lets the -agent answer "what's on the critical path this week" without me -pasting agenda output, and feeds the daily-prep / wrap-up workflows. +*** TODO Findings: org apps + calendar-sync group +From agents 2026-06-11/12; spot-verified sample (UNTIL comparisons, EXDATE regex, drill setq confirmed). Beyond the standalone tasks: +- [BUG] =org-reveal-config.el:241= — seven raw =global-set-key= "C-; p ..." calls carry a hidden load-order dependency on keybindings.el (signals "non-prefix key" otherwise); every sibling uses =defvar-keymap= + =cj/register-prefix-map=. Convert. +- [BUG] =org-drill-config.el:131= — =:load-path "~/code/org-drill"= dev checkout breaks drill on machines without it (velox already diverges per the gptel-magit task). Guard with =file-directory-p= fallback to :vc. +- [UX] =org-contacts-config.el:146= — =cj/org-contacts-find= visits the file BEFORE prompting (C-g strands you at point-min) and plain =search-forward= can match body text in another entry. Collect heading positions in org-map-entries, goto after prompt. +- [REMOVE] =calendar-sync.el:1240= — =calendar-sync--fetch-ics= (buffer-string variant) is dead; the sync path uses the temp-file variant exclusively. 30 lines of duplicate curl/sentinel logic that will drift. +- [REMOVE] =org-webclipper.el:216-241= dead commented keymap blocks; =org-contacts-config.el:118-124= commented duplicate capture template flagged "TASK: duplicate?!?". Delete both (git keeps drafts). +- [COVERAGE] =calendar-sync.el:1274= — fetch sentinel branches (curl failure, temp-file cleanup, signal exit) untested; dispatch tests stub above this layer. -**** TODO [#B] Org-roam node tools :feature: +*** TODO Findings: mail group +From agents 2026-06-12; spot-verified sample (cmail trash gap, no refile folders, gmail-first contexts confirmed). Beyond the standalone [#A] task: +- [BUG] =mail-config.el:392-407= — C-; e account nav lambdas call =mu4e-search=, not autoloaded — void-function before first mu4e launch. Add to :commands or require first. +- [BUG] =mail-config.el:481-484= — unconditional =org-msg-edit-mode= :after advice on replies defeats the =(reply-to-text . (text))= alternative at :459 and re-runs a major mode org-msg already set up. Gate or remove. +- [BUG] =mu4e-attachments.el:222= — the *mu4e attachments* selection buffer saves through stale MIME handles if the view changed before s — errors or saves the wrong message's parts. Check =buffer-live-p= per handle at save. +- [BUG] =mail-config.el:329= — "save attachment" in =mu4e-headers-actions= can't work from headers (MIME vars are view-buffer-local, nil in headers-mode). Drop it there. +- [BUG] =mail-config.el:282-305= — HTML view block sets variables obsolete since mu4e 1.7 (installed 1.14.1): =mu4e-view-prefer-html=, =mu4e-html2text-command= (also set twice: 186, 285), =mu4e-view-show-images=, =mu4e-view-image-max-width=. The pandoc/w3m selection never runs; shr renders regardless. Delete the dead block (image/privacy reconciliation already filed separately). +- [BUG] =mail-config.el:45-49,80-89= — top-level =(defvar message-send-mail-function nil)= pre-empts message.el's defcustom default; with msmtp absent the fallback leaves it nil → "invalid function: nil" on first send. Explicit =smtpmail-send-it= fallback or descriptive user-error. +- [UX] =mail-config.el:171,196-199= — =pick-first= + gmail listed first makes gmail the startup context though cmail reads as primary everywhere else — quiet wrong-account hazard for the first compose. Reorder contexts. +- [REMOVE] =mu4e-org-contacts-setup.el= — unreachable (nothing requires it; mail-config calls activation directly) and its featurep gate would be nil at init anyway. Delete or fold its two setqs into mail-config. +- [REMOVE] =mail-config.el:208,232= — =mu4e-starred-folder= isn't a mu4e variable (invented, no effect); =:174= =mu4e-maildir= is the obsolete alias of root-maildir set on the previous line. Drop all three. +- [REMOVE] =mu4e-org-contacts-integration.el:158,171-172= — hook surgery on =mu4e--compose-setup-completion= is a no-op on mu4e 1.14 (called directly, not via hook; already gated by the var activation sets). Delete both hook calls. +- [COVERAGE] =mu4e-attachments.el:101-105= — mid-batch save-failure path and stale-handle scenario untested. -Resolve a topic to its node; return body + backlinks; list nodes by -tag; surface dailies for a date range. Lets the agent reason over -the personal knowledge graph and write back into it via the capture -tools below. +*** TODO Findings: messengers group +From agents 2026-06-12. Beyond the standalone tasks; several feed the messenger-unification spec: +- [BUG] =signal-config.el:201= — contact cache docstring claims "cleared on signel-stop/restart"; nothing clears it (grep: fork never references it). Stale list after relink/reconnect. Advise =signel-stop= or clear on start. +- [BUG] =signal-config.el:298= — fetched-and-empty contact list is indistinguishable from cold cache (nil), so a zero-contact account re-runs the blocking fetch (up to fetch-timeout) on every C-; M m. Cache a sentinel. +- [UX] =slack-config.el:208= — =cj/slack-notify= lacks signel's hardening: no truncation (giant toasts), no sound gating, no notifications-notify fallback when the script is absent. Unification-relevant: extract a shared =cj/messenger-notify= (title prefix, truncation, sound flag, script-with-fallback) — noted in the unification spec. +- [ENHANCE] =telega-config.el:52= — telega has NO notification path (=telega-notifications-mode= not enabled); incoming Telegram messages invisible unless the buffer is on screen. Enable, or route through the shared notifier. Unification-relevant. +- [COVERAGE] — =cj/erc-join-channel-with-completion= (erc:148, four-way reconnect branching), =cj/erc-connected-servers= (would have caught the tautology), =cj/slack-notify= predicates, =cj/signel--ensure-started= branches — all untested. -**** TODO [#B] Capture creation tools :feature: +*** TODO Findings: programming group +From agents 2026-06-12; spot-verified sample (prog-lsp unreachable confirmed by grep). Beyond the standalone tasks: +- [BUG→FOLD] =prog-lsp.el= — the module is UNREACHABLE: nothing requires it, so its entire LSP policy (TRAMP guard, file-watch ignores, read-process-output-max, idle-delay 0.5) is dead while prog-general.el:388-416's older conflicting block wins (idle 0.1, lsp-ui-doc on). Fold this fact into the filed "Make prog-lsp.el the single owner of generic LSP policy" task — it doesn't currently record that prog-lsp never loads. +- [BUG] =flycheck-config.el:68-70= — =checkdoc-arguments= isn't a real variable (invented name + invented format); the intended checkdoc suppression has never worked. Use =flycheck-emacs-lisp-checkdoc-variables= or drop. +- [BUG] =prog-json.el:87-90= — C-c C-q → jq-interactively binding defers to eval-after-load of jq-mode, which nothing loads — dead key. Bind in =cj/json-setup= via local-set-key (jq-interactively IS autoloaded). +- [BUG] =prog-python.el:129-132= — lsp-pyright's :hook lambda calls =lsp-deferred= unguarded on the same hook as the guarded =cj/python-setup= — pyright-absent machines still get the LSP attach prompt the guard exists to prevent. Move the require into the guarded branch; delete the hook. +- [BUG] =prog-lisp.el:122-125= — =:after (flycheck package-lint)= waits for a manual M-x to load package-lint, so =flycheck-package-setup= effectively never runs. Hook on flycheck load + require inside. +- [UX] =prog-python.el:111-115=, =prog-go.el:111-114=, =prog-webdev.el:128-147= — setup hooks attach to ts-modes only (C/shell hook both variants); grammar-unavailable fallback to classic modes silently loses indent/keys/formatter/LSP. Add classic-mode hooks. +- [UX] =prog-webdev.el:165-173= — web-mode gets the format key but none of the promised setup (no company/flyspell/LSP in HTML buffers). Add to the setup hook or fix the Commentary. +- [ENHANCE] gopls, clangd, bash-language-server, shfmt, shellcheck lack the =cj/executable-find-or-warn= load-time warnings pyright/prettier have; prog-shell's =:if (executable-find ...)= evaluates once at startup and silently disables shfmt/flycheck setup forever. +- [REMOVE] =prog-training.el:36-37= — =(url-debug t)= turns on GLOBAL url.el debug logging once leetcode loads. Debugging leftover; delete. +- [REMOVE] =prog-webdev.el:85=, =prog-json.el:44=, =prog-yaml.el:39= — three byte-identical format-region helpers. Extract one shared tested helper (system-lib). -Drive =org-capture= from a template key + body string. Lets the -agent file inbox items, reading notes, journal entries, or roam -nodes without me leaving the chat. Tight pairing with the -=cj/org-capture= optimization task in todo.org. +*** TODO Findings: dev tooling group +From agents 2026-06-12; spot-verified sample. Beyond the standalone F7 task: +- [BUG] =vc-config.el:138-144= — =cj/goto-git-gutter-diff-hunks= (C-; v d) never did what it claims: consult-line over "^[+\\-]" matches source text, not gutter hunks. Build candidates from =git-gutter:diffinfos= or drop the binding (C-; v n/p covers it). +- [BUG] =dev-fkeys.el:116-122= — F4 compile+run one-shot hook installs on GLOBAL =compilation-finish-functions= before the prompt; C-g leaves it armed and the next unrelated compile triggers projectile-run-project. Use the buffer-local pattern the module already uses for cache-revert (same in =--f4-clean-rebuild-impl=:143). +- [BUG] =test-runner.el:84,222= — documented ~/.emacs.d/tests fallback doesn't exist (=cj/test-global-directory= defvar'd nil, never set); outside a project =(file-directory-p nil)= crashes in three commands. Initialize the defvar or guard with user-error. (Adds specifics to the open "Fix up test runner" task — fold.) +- [BUG] =test-runner.el:288= — focus-add prefix check lacks the trailing slash so =tests-scratch/= passes the "inside tests/" check; the correct helper =cj/test--file-in-directory-p= exists at :168 — use it. +- [BUG] =vc-config.el:217-219= — difftastic blame map binds D and S to the same command (show); D should be diff per the transient four lines down. +- [UX] =diff-config.el:37= — =ediff-diff-options "-w"= ignores ALL whitespace in every ediff session — indentation-only Python changes compare as identical. Drop the default; toggle per-session. +- [UX] =restclient-config.el:64-65= — raw global-set-key "C-; R n" hides a load-order dependency (header claims "Runtime requires: none"); use defvar-keymap + =cj/register-prefix-map= like siblings (same class as org-reveal, slack). +- [UX] =vc-config.el:196= — clipboard clone via synchronous =call-process= freezes every emacsclient frame for the whole clone. make-process + sentinel. +- [REMOVE] =vc-config.el:80-82= — phantom autoload =git-timemachine-show-selected-revision= (no such function in the package) appears in M-x and errors. Drop from :commands. +- [REMOVE] =httpd-config.el:19-30= — pointless =:defer 1= (impatient-mode loads simple-httpd on demand) + unprefixed eager globals =wwwdir=/=check-or-create-wwwdir= creating www/ on every startup. =:defer t=, prefix, or fold into markdown-config. +- [COVERAGE] — intersect/parse unit tests hand-build matching keys (the F7 bug's escape route); =--coverage-elisp-run='s compilation-finish wiring, goto-git-gutter-diff-hunks, timemachine candidate round-trip untested. F-key sweep clean: no collisions; F5 free for the debug-backend task. -**** TODO [#B] Org-drill review tools :feature: +*** TODO Findings: shell/term/files group +From agents 2026-06-12; spot-verified sample (eshell nested list confirmed). Beyond the standalone tasks: +- [BUG] =dirvish-config.el:37= — =cj/xdg-open= attributed to system-utils in the require-comment but defined in external-open.el; neither dirvish-config nor dwim-shell-config (caller at :876) requires it — "Direct test load: yes" headers are false. Require external-open (or move the fn into external-open-lib) + fix comment. +- [UX] =tramp-config.el:73= — =revert-without-query '(".*")= kills revert confirmation for EVERY file in Emacs, buried in the TRAMP module. Scope to =tramp-file-name-regexp= or move deliberately to an editing module. +- [UX] =dirvish-config.el:403= — quick-access entries lx (~/archive/lectures), phl (~/projects/homelab), pn (~/projects/nextjob) point at directories that don't exist on this machine. Prune or create. +- [REMOVE] =dwim-shell-config.el:474,507= — open-externally (raw xdg-open) and open-file-manager (thunar/nautilus probe chain) duplicate cj/xdg-open (dirvish o) and cj/dirvish-open-file-manager-here (f); ascii-art references jp2a, the module's only absent binary. Delete the two duplicates; install jp2a or drop ascii-art. +- [REMOVE] =tramp-config.el:115= — custom =sshfast= method referenced nowhere (everything uses sshx); =tramp-own-remote-path= added twice (:39,:128); =dirtrack-list= and =magit-git-executable "/usr/bin/git"= are unrelated globals hiding here. Prune/relocate. +- [COVERAGE] — eshell visual-commands/xterm-color wiring and the dirvish mark-all loop had no load-and-assert tests (both standalone bugs above); TRAMP perf settings look sound for the DUET latency concern (attr caching, no remote VC, direct-async + controlmaster). -Surface next-due drill cards in =drill-dir=; let the agent quiz on a -topic and report performance. Useful for prompted recall sessions -("ask me five medical-Spanish cards") and for "did this card stick" -analysis. +*** TODO Findings: AI group +From agents 2026-06-12; spot-verified sample (string-model setq confirmed). Beyond the standalone tasks: +- [BUG] =ai-term.el:875= — close derives the tmux session name from =default-directory=, which ghostel retargets via OSC 7; after a cd the kill-session misses (orphaned agent session) or name-collides with a different aiv- session. Derive from the buffer name's immutable basename. +- [UX] =ai-term.el:827= — multi-window F9 toggle-off unconditionally delete-windows, never restoring the displaced edge-window buffer the Commentary (:24) and reuse-edge docstring (:521) promise. Restore when quit-restore still matches, or fix the docs to describe delete-window reality. +- [UX] =ai-conversations-browser.el:191= — browser load stubs =y-or-n-p= to nil, silently discarding an unsaved in-progress conversation (the direct C-; a l path offers to save). Give ai-conversations a file-arg internal instead of puppeting the interactive command via cl-letf; also the =(caar cands)= fallback loads the newest conversation on a filename mismatch — fail loudly. +- [ENHANCE] =ai-quick-ask.el:103= — dismiss mid-stream kills the buffer without =gptel-abort= — request keeps streaming to a dead buffer (wasted tokens). +- [NOTE] =ai-mcp.el= — unreachable from init, consistent with the paused Phase 1.5; add a one-line Commentary note ("not wired until Phase 2") so future audits don't re-flag, and revisit =cj/mcp-enabled-servers= defaulting to all nine servers before wiring. +- [COVERAGE] — load/autosave lifecycle untested (fresh-session load, timer self-cancel, close-buffer session-name derivation). -*** TODO [#B] Git Related Tools +*** TODO Findings: media/reading group +From agents 2026-06-12; spot-verified sample (M-S- bindings, eww store split confirmed). Beyond the standalone tasks: +- [BUG] =music-config.el:585= — =cj/music-add-dired-selection= gates =dired-get-marked-files= on =(use-region-p)= — but dired marks aren't a region; marked files are ignored, + adds only file-at-point. Drop the conditional (the function already falls back correctly). Note for the EMMS-free rewrite: dirvish + shadows =dired-create-directory= — deliberate decision needed before carrying it over. +- [UX] =media-utils.el:195-204= — =cj/yt-dl-it= watches tsp (which enqueues and exits), so "Finished downloading" fires immediately while yt-dlp may fail later, silently; also affects elfeed d. Message "queued" honestly or watch the real job (tsp -f). +- [UX] =browser-config.el:34-47,171= — first-run fallback picks EWW (first, "always available") over installed real browsers; fresh machines get org links in a text browser until cj/choose-browser runs. Prefer the first external match. +- [REMOVE] =video-audio-recording.el:442-488= — =cj/recording-group-devices-by-hardware= is dead code (nothing calls it) carrying a hardcoded "Jabra SPEAK 510 USB" branch. Delete + its test file. +- [REMOVE] =calibredb-epub-config.el:198-212= — =set-auto-mode= :around advice for .epub is redundant with nov's :mode registration (auto-mode-alist wins before magic-fallback); overhead + failure surface on every file visit. Remove and verify. +- [COVERAGE] — eww interactive commands (switch-search-engine, bookmark-quick-add, copy-url) and =cj/nov-center-images= untested. -Affordances that expose magit's structured view of a repo -- sections, -staged-vs-unstaged, commit metadata, rebase / conflict state -- as -first-class tools rather than asking the model to reason over raw -diff text. +*** TODO Findings: apps/misc group +From agents 2026-06-12. Beyond the standalone tasks: +- [BUG] =hugo-config.el:49= — =cj/hugo-new-post= void-functions on =org-hugo-slug= in a fresh session (ox-hugo is :after ox, which loads on first export); =cj/hugo-export-post= already requires ox-hugo — do the same here. +- [BUG] =help-utils.el:73= — arch-wiki search signals raw file-missing when the docs dir is absent; the friendly install hint at :81 is unreachable. Guard with =file-directory-p= + user-error up front. +- [UX] =hugo-config.el:244= — eight raw global-set-key C-; h calls + hand-rolled which-key mutate cj/custom-keymap directly, against keybindings.el's own instruction. Convert to defvar-keymap + =cj/register-prefix-map= (same class as org-reveal, restclient, slack). +- [ENHANCE] =games-config.el:25= — =:defer 1= pulls malyon + 2048 into every session for nothing; use =:commands=. Also :config references =org-dir= without requiring user-constants (free-variable warning at byte-compile). +- [REMOVE] =wrap-up.el:29= — =elisp-compile-mode= doesn't exist (real mode emacs-lisp-compilation-mode derives from compilation-mode, already covered at :27); dead line. (The prior unguarded-timer fix is intact.) +- [REMOVE] =help-config.el:99-106= — stray empty :preface + dead commented Info-directory-list block. Delete. +- [NOTE] =duet-config.el= — orphaned BY DESIGN (Commentary documents pre-alpha staging; Stage 1 is the wire-in trigger). Audit record only. +- [COVERAGE] — help-config and help-utils have zero test files; the two broken paths above are exactly the untested branches. -**** TODO [#B] Section-aware git tools :feature: +*** TODO Findings: holistic — startup & performance +From the 2026-06-12 holistic pass; daemon init measured at 1.11s (healthy). Beyond the standalone [#A] native-comp/GC task: +- [BUG→FOLD] the eager-org chain: =org-config.el:352= org-appear has no defer trigger (only :custom) → requires all of org at init; org-agenda (=:after org :demand t=) cascades; chime's =:demand t= pulls it anyway. org-config is the most expensive require (0.229s of 1.11s). Decide fully-eager vs fully-deferred — and =init.el:146='s "calendar-sync must come after org-agenda" contract exists only as a comment (three uncoordinated writers of =org-agenda-files=). Both facts belong in the filed defer-modules task before that refactor starts. +- [PERF] =dirvish-config.el:385-387= — =:defer 0.5= defeated by :init calling autoloaded =dirvish-override-dired-mode= → dirvish fully loads at init (0.072s, third most expensive; trace-confirmed). Own the eager load or defer the override to a dired-mode-hook shim. +- [PERF] timed =:defer N= loads unused packages into every start: simple-httpd (:1s + startup mkdir despite the defer), malyon, 2048-game, emojify (may hit network), ligature. Convert to :commands/mode hooks. +- [UX] =early-init.el:235-256= — synchronous =package-refresh-contents= on the startup path when any archive cache is >7 days old (MELPA ~6MB) — multi-second network-bound start, fires in batch too. Make async post-startup or push into the localrepo update script (distinct from the filed bootstrap-relocation task). +- [PERF] =early-init.el:228= — no =package-quickstart= with 184 packages; activation walks every package dir each start (~0.3s of early-init). Free win; regenerate after package ops. +- [PERF] =prog-general.el:298= — =yas-reload-all= immediately before =yas-global-mode= scans snippet dirs twice per start (doubled "[yas] Prepared..." message). Delete the line. +- [REMOVE] cross-ref: the all-the-icons stack (already in UI core findings) is 2 of the :demand t packages plus a per-frame install-check hook. -Expose Magit sections as first-class GPTel tools: current section type, -heading, file, hunk range, and content; sibling sections under the same -file; staged / unstaged / untracked status; commit metadata around the -selected commit or branch; the exact staged patch that would be -committed. Lets prompts say "review the file section at point" or -"explain this hunk in the context of adjacent hunks" without manual -context-copying. +*** TODO Findings: holistic — daemon stability +From the 2026-06-12 holistic pass. Architecture-level verdict good (timers cancelled/guarded, calendar-sync async well-contained, advice mostly named + guarded). Residual: +- [STABILITY] =transcription-config.el:293= — sentinel chain has no unwind-protect; =--append-to-log='s =insert-file-contents= signals if the log is missing → process buffer leaks, entry stuck 'running in the modeline forever, no notification. Extends the filed transcription standalone — fix together. +- [STABILITY] =calendar-sync.el:1646= — hourly timer body: fetch/parse guarded but the timezone check and =--require-calendars= run bare — any signal repeats hourly forever (the exact class fixed in four modules once). Condition-case the body; demote the hourly echo-area message to the silent log. +- [STABILITY] =music-config.el:865= — four anonymous-lambda advice in :config stack per live reload (verified: lambdas don't dedupe) and can't be advice-removed. Name the function. +- [STABILITY] =system-defaults.el:69= — =display-warning= advice appends to comp-warnings-log with no condition-case (unwritable path → every async comp warning signals from inside display-warning) and the log grows unbounded. Guard + cap. +- [STABILITY] =media-utils.el:164= — playback sentinel assumes the process buffer is alive (user killed *player:...* → sentinel error, diagnostics lost); sibling yt-dl sentinel shares the kill-buffer gap. buffer-live-p guards. +- [ENHANCE] =system-commands.el:86= — =#'ignore= sentinel + output to /dev/null makes failing lock/suspend indistinguishable from success — the user walks away from an unlocked machine. Message on nonzero exit. (Compounds the [#A] slock task: the broken lock currently fails through exactly this silent path.) +- [ENHANCE] =ui-config.el:153= — post-command cursor hook unguarded: any future signal self-removes it silently (cursor stops signaling modified/read-only until restart); frame-hook lambda also accumulates per reload. with-demoted-errors + name it. +- (kill-emacs-hook y-or-n-p prompt independently re-found here — already filed in the text/prose child; convergence noted.) -**** TODO [#B] Commit intent workbench :feature: +*** TODO Findings: holistic — UX consistency +From the 2026-06-12 holistic pass. Verdict: more coherent than most 120-module configs (~85% prefix-helper adoption, M-S translation fully covers its 18 bindings, F-keys collision-free, DEF-arg prompts dominate). Beyond the standalone [#A] fset task: +- [BUG] notification env gate: =transcription-config.el:169-171= gates desktop notifications on =(getenv "DISPLAY")= — an X11 predicate that works only because XWayland exports it. Use =env-gui-p= (host-environment.el provides it). +- [UX] four notification stacks beyond the messenger split (notify script ± fallback, alert.el, raw notifications-notify, echo-only for calendar-sync/recording completions). Proposed: one cj/notify facade (transcription's =cj/--notify= is the right shape) — config-wide companion to the messenger-notify addendum in the unification spec. +- [UX] five more C-; entries bypass the register helpers or lack labels: =browser-config.el:182= (C-; B, no label), =org-babel-config.el:51= (C-; k, no label), =flycheck-config.el:62-64= (:bind into cj/custom-keymap), =pearl-config.el:43= (:bind-keymap C-; L, no label), =dev-fkeys.el:533= (helper but no label). Sweep onto cj/register-prefix-map with labels. +- [UX] user-error vs message inconsistent for "nothing to act on" config-wide (examples: =custom-whitespace.el:190=, =jumper.el:202=, =chrono-tools.el:99= message; =mu4e-attachments.el:112=, =ai-rewrite.el:79= user-error; =test-runner.el:392/394= mixes both 2 lines apart). Convention: user-error when the command can't proceed; message when it ran and found nothing. +- [ENHANCE] M-S translation layer: complete for GUI (18/18) but installs only on env-gui-p paths — terminal frames have no M-uppercase route; and =dwim-shell-config.el:932/934= binds M-S-d (dired) vs raw M-D (dirvish) asymmetrically. Feeds the filed M-S review task with the concrete map. +- [ENHANCE] which-key labels: register-helper's LABEL arg used by exactly 1 of 23 registrants (rest use separate with-eval-after-load blocks); label style drifts ("X menu" vs bare nouns). Adopt LABEL arg + one style. +- [ENHANCE] "?" curated-menu candidates (for the filed convention task): elfeed search/show, dirvish, signel chat/dashboard, music playlist, ai-conversations-browser, mu4e-attachments, transcription status, pearl. calibredb remains the model. +- [UX] ="(Cancel)"= pseudo-candidate in =music-config.el:253-256= vs C-g everywhere else (90+ prompts). Drop it. +- [UX] buffer-naming drifts across three conventions (*AI-Assistant* / *Kill Ring* / *dashboard*); pick Title Case + "*Name: param*", lowercase for process logs. +- [ENHANCE] C-; f formatter shadowing implemented 3 ways (:bind :map vs local-set-key in hooks); unify on :bind. Also =keybindings.el:21= commentary still says "C-c j" for the jump prefix the code binds at C-; j. +- [ENHANCE] initial-input anti-pattern at =dwim-shell-config.el:661,680= and =erc-config.el:176-177= against the config's DEF-arg norm. -Transient that builds a commit intentionally: -1. Agent reads unstaged + staged changes. -2. Agent proposes coherent commit groups. -3. User selects groups in a Magit-style buffer. -4. Agent stages those paths or hunks only after confirmation. -5. Agent generates a message reflecting the selected intent. +*** TODO Findings: holistic — package strategy +From the 2026-06-12 holistic pass (184 elpa dirs). Core stack modern (vertico/consult/embark/orderless, treesit-auto, built-in which-key, current magit/forge/telega/slack). Beyond the standalone gptel/prescient tasks: +- [REMOVE] true orphans, nothing references them: js2-mode, tide, json-mode (pre-treesit JS stack). package-delete + drop from .localrepo. +- [REMOVE] emojify: 2021 snapshot, dormant upstream, crashes in lui (slack disabled it), Emacs 30 renders emoji natively. Drop the use-package + hooks (=font-config.el:253=, =erc-config.el:211=); it stays on disk only as slack's declared dep. +- [BUG] legacy-mode hooks miss the ts modes: =prog-general.el:91-92= hooks =yaml-mode-hook=/=toml-mode-hook= but the config runs yaml-ts/toml-ts — general prog settings silently don't apply in YAML/TOML buffers. Rehook; delete toml-mode + eldoc-toml + yaml-mode packages (superseded by treesit). +- [RISK→FOLD] localrepo priority 200 is absolute, so package-upgrade silently no-ops on everything mirrored — the engine that fossilized emojify@2021/toml-mode@2016/js2@2023. The filed refresh-script task at [#D] deserves [#B] + a quarterly cadence, else every orphan finding regrows. +- [RISK] fork fleet sync-back stories: org-drill flip back to :vc when done (filed dev-checkout finding); auto-dim-other-buffers local checkout with :vc commented — decide its home; org-msg pins =:rev :newest= (unpinned moving target) — pin a known rev. signel/duet/pearl/wttrin/gloss/chime self-owned remotes are fine. +- [UPGRADE] wiki-summary (2018, dead upstream, predates Wikipedia's REST API; sole caller help-utils) — the audit's one write-your-own: ~30-line url-retrieve against the REST summary endpoint. Delete the package, inline the helper. +- [UPGRADE] xterm-color droppable in eshell on Emacs 30's native ansi-color (its only use; also doubly-broken per the eshell standalone task — fixing by deletion is an option). +- [ENHANCE] Python tier: poetry.el (sluggish) + pyvenv (2021) keep only if Poetry projects are still real; blacken fine until ruff-format (reformatter.el already installed). lsp-pyright current. +- [DECIDED] projectile, lsp-mode, dirvish: keep (wired into 10/7/many modules, maintained, migration cost > benefit). On the record so future audits don't relitigate. -Addresses the common case of two or three unrelated edits in one -working tree -- a single commit-message generator can't handle that -cleanly. +*** TODO Findings: spin-off repos (pearl, chime, emacs-wttrin) +Full findings delivered as handoffs to each repo's inbox/ (2026-06-12-0057-from-.emacs.d-handoff-*.org); each repo's next session files them through its own value gate. Highlights: +- pearl (10 findings; suite green, 66 ERT files): auth-source negative-cache trap in pearl-clear-cache (the 2026-06-01 incident class, unfixed); sync wrapper ignores pearl-request-timeout + async has no timeout; mutation errors discard Linear's GraphQL reason; no RATELIMITED handling; dead legacy API layer (~150 lines). +- chime (10 findings; suite green; the 2026-06-11 watchdog handoff VERIFIED landed in full): lookahead vars never injected into the async child (documented feature silently capped at 8 days — one-line fix); days-until-event nil crash on mixed timed/all-day events; stale-callback race after watchdog interrupt (generation counter needed); default test run prints green integration banner over "Ran 0 tests". +- emacs-wttrin (10 findings; ~56 ERT files, CI; the face-flood reminder VERIFIED resolved — test 8f3c770 + fix c5e5e1d, reminder cleared from notes.org): no network timeouts (wttr.in stalls hang the loading buffer); error-path response-buffer leak; non-favorite cache never expires; 17 unreleased commits incl. two features — tag v0.4.0. -**** TODO [#B] Patch narrative buffer :feature: +** PROJECT [#C] Build cj/dev-setup-project helper (per docs/specs/dev-setup-project-spec.org) :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +*** 2026-05-15 Fri @ 19:17:37 -0500 Specification -Generate an Org buffer that explains a change set as a reviewable -narrative: -- "What changed" by subsystem. -- "Why it appears to have changed" inferred from names, tests, and docs. -- "Risk areas" with links back to Magit file sections. -- "Suggested verification" using local Makefile targets when present. +Interactive command that opens a review buffer with proposed per-subdirectory .dir-locals.el contents (projectile compile/run/test + cj/coverage-backend), optional starter Makefile when none exists, and gitignore updates. User edits inline, C-c C-c writes all files. -Reusable artifact: paste into a PR description, save with an AI -session, or file into org-roam. +Design: [[id:596fce5d-1bab-46e7-8567-d4a2e0923091][docs/specs/dev-setup-project-spec.org]] -**** TODO [#B] Review-thread simulator :feature: +Scope of v1: +- modules/dev-setup-config.el (command + review-buffer major mode) +- Three-tier detection: existing Makefile, existing package.json/pyproject.toml scripts, fall-back starter Makefile generation. +- Project shapes supported: pure Elisp, pure Go, pure Python, pure Node/TS, Docker Compose polyglot. +- Re-run semantics: status banners (UNCHANGED / WILL UPDATE / WILL CREATE), idempotent gitignore append, never modifies an existing Makefile. +- ERT tests for the pure helpers (Makefile parser, package.json parser, shape detection, target-to-role mapping, review-buffer parser). -Before opening a PR, create a local review buffer with inline comments -attached to Magit diff positions. The agent writes comments as if -reviewing someone else's patch: -- Comments grouped by severity. -- Each comment links to file and line. -- Resolved comments check off in Org. -- Accepted suggestions apply through the existing text-update tools. +Deferred: +- Rust (Cargo.toml), Java (pom.xml), other language shapes. +- Project-wide override config file. +- Auto-detecting external run scripts in conventional locations. -Makes "review my diff" less ephemeral and avoids losing useful findings -inside a chat transcript. +Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable. -**** TODO [#B] Rebase and conflict coach :feature: +*** TODO [#B] Pure detection + parsing helpers :feature: +Implement the four pure helpers the rest of the command composes on: +- =cj/--dev-setup-parse-makefile-targets FILE= (.PHONY + bare target lines, skip pattern rules) +- =cj/--dev-setup-parse-package-json-scripts FILE= (scripts block, JSON) +- =cj/--dev-setup-detect-project-shape ROOT= (Elisp / Go / Python / Node-TS / Docker-Compose polyglot / unknown) +- =cj/--dev-setup-map-targets-to-roles TARGETS= (best-guess compile/run/test mapping per design § Detection) -When Magit enters a rebase, cherry-pick, merge, or conflict state, -expose an agent command that reads: -- Git operation state from =.git/=. -- Conflict markers in the worktree. -- Relevant commits from =git log --merge= or the rebase todo. -- The current Magit status sections. +Files: =modules/dev-setup-config.el= (new). No interactive surface, no I/O +beyond reading the named file. -The agent explains the conflict in domain terms and proposes a -resolution patch; the actual edit and =git add= stay under explicit -user control. +Acceptance: each helper callable in isolation with handcrafted fixtures; +no command yet. -**** TODO [#B] Regression archaeology :feature: +Depends on: none -- start here. -Magit transient that runs a bisect-like reasoning workflow: -- Ask for a symptom and a known-good / known-bad range. -- Summarize candidate commits in small batches. -- Use tests or user-provided repro commands when available. -- Maintain a bisect journal in an Org buffer. +*** TODO [#B] ERT coverage for the pure helpers :feature:test: +Normal/Boundary/Error tests for every helper from the prior sub-task, +matching the design's testing section. -Even when the agent can't run the whole bisect, it keeps the -investigation structured and preserves why each commit was judged -good or bad. +Files: =tests/test-dev-setup-config.el=, plus +=tests/testutil-dev-setup-config.el= for the temp-project fixture builder +(writes Makefile / package.json / compose stub into =make-temp-file ... 'dir=). -**** TODO [#B] Messaging Related Tools +Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green; +every helper has at least one Normal, one Boundary, one Error case. -Affordances over mu4e, Slack, Telegram, and ERC. Same shape across -protocols: read recent threads, search by sender / topic, compose a -draft from a prompt + thread context, leave the send under explicit -user control. +Depends on: pure detection + parsing helpers. -***** TODO [#B] Mu4e thread and compose tools :feature: +*** TODO [#B] Starter-Makefile + .dir-locals.el proposal generator :feature: +Pure function =cj/--dev-setup-build-proposal SHAPE ROOT= returning a +structured plist of proposed blocks: one per subproject =.dir-locals.el= +(projectile compile/run/test + =cj/coverage-backend=), the optional starter +Makefile (only when none exists, adapted per shape per design § Tier 3), +and the gitignore append lines. -Read the message at point and surrounding thread (with attachments -summarized); query the inbox by =from:= / =subject:= / date range; -compose a draft from a prompt + thread context using =org-msg=. -Pairs with the existing =mu4e-org-contacts-integration.el=. +Files: =modules/dev-setup-config.el=. -***** TODO [#B] Slack thread and compose tools :feature: +Acceptance: given a shape plist, returns deterministic block list ready for +the review buffer; ERT cases cover each shape (Elisp / Go / Python / Node-TS +/ polyglot) plus the Tier-1 "Makefile already exists, suppress Makefile +block" branch. -Read channel / DM / thread history through =emacs-slack=; search by -user or channel; compose a draft message but leave sending to me. -Mirrors the mu4e shape so the agent's interface is uniform across -messaging protocols. +Depends on: pure detection + parsing helpers. -***** TODO [#B] Telegram and IRC read tools :feature: +*** TODO [#B] Review-buffer major mode + parser :feature: +Define =cj/dev-setup-review-mode= (derived from =emacs-lisp-mode=) with =C-c +C-c= / =C-c C-k= bindings, plus the pure parser +=cj/--dev-setup-review-buffer-parse CONTENTS= that turns buffer text back +into a block list. Banner syntax per design § Review Buffer (=;; ==== <path> +====[ <status>]==, gitignore special, Makefile special). -Same shape as Slack for =telega= (Telegram) and =erc= (IRC): -recent-message reads, search, and draft compose. Bundled because -the API shape is identical even if the underlying clients differ. +Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el= +(parser cases: well-formed multi-block, single block, empty body, missing +banner, malformed elisp inside a dir-locals block). -***** TODO [#B] Contact resolution tools :feature: +Acceptance: round-trip -- render proposal -> parse buffer -> equal block +list. Mode keybindings smoke-tested. -Resolve a name to email / Slack ID / Telegram handle via -=org-contacts= and the configured address books. Removes the -"who's this person again" friction from the compose flows above. +Depends on: starter-Makefile + .dir-locals.el proposal generator. -**** TODO [#B] File and Buffer Related Tools +*** TODO [#B] Writer + status diff + projectile cache reset :feature: +Implement the =C-c C-c= writer: diff each parsed block against the on-disk +file to assign =UNCHANGED= / =WILL UPDATE= / =WILL CREATE=, write only the +non-UNCHANGED ones, append gitignore idempotently, never touch an existing +Makefile, honor the =;;; cj/dev-setup-project: ignore= escape hatch, clear +projectile's per-project command cache, print the summary line. -Affordances that expose the user's actual workspace -- open buffers, -narrowed regions, marked files, vterm / eshell sessions -- as -structured context. Stops the model from asking "what file are you -looking at" or "what region is selected." +Files: =modules/dev-setup-config.el=, plus ERT cases for the diff + +idempotent-append logic against temp dirs. -***** TODO [#B] Buffer state tools :feature: +Acceptance: re-run on an unchanged project writes nothing; renaming a +Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay +untouched. -List visible buffers with major-mode + file (when any); read the -narrowed region instead of the whole buffer; report point + mark -positions and the active region's text. The single most-asked -question between turns becomes a tool call. +Depends on: review-buffer major mode + parser. -***** TODO [#B] Dirvish / Dired tools :feature: +*** TODO [#B] Interactive command + smoke test :feature:test: +Thin =cj/dev-setup-project= interactive wrapper: resolve project root via +projectile, run detection, build proposal, render the review buffer, pop to +it. One smoke test against a prepared temp project asserting the expected +files exist after a simulated =C-c C-c=. -Read marked files, sort state, and filter state from a Dired or -Dirvish buffer. Lets the agent operate on "the files I just marked" -rather than "files in this directory" -- a real distinction in any -review or refactor workflow. +Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=. Add +=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator). -***** TODO [#B] Vterm session tools :feature: +Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review +buffer; =C-c C-c= writes the expected files. -Recent command output from a named vterm session; scroll-history -search. Pairs naturally with the =ai-vterm= design: the agent -running in one project's vterm can read another project's vterm -without leaving the chat. +Depends on: writer + status diff + projectile cache reset. -***** TODO [#B] Eshell session tools :feature: +*** TODO [#B] Resolve open questions + design follow-ups +Three design questions to close before / during implementation: (a) include +=make coverage= target in starter Makefile? (b) project-wide override file +=.cj-dev-setup.el=? (c) Cargo/pom detection. -Same shape as the vterm tools for =eshell= sessions -- last-command -output, history search, current directory. Most useful for -agent-driven inspection of long-running pipelines. +Body: park decisions inline in the design doc or run =arch-decide= if they +turn out load-bearing. -**** TODO [#B] Filesystem Related Tools +Depends on: none, but easiest after the writer sub-task surfaces real +friction. -Affordances that let the agent operate on actual files on disk and -run common CLI utilities -- pandoc, ffmpeg, imagemagick, ripgrep, -fd, jq -- rather than relying on me to paste content or run -commands by hand. +** PROJECT [#C] Localrepo Documentation :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-05 +:END: -*Design tension to resolve before any of these ship: one tool per -utility, or one generic =run_shell_command=?* +Audit on 2026-05-27 found the localrepo build half is shipped (=.localrepo/= holds 185 entries; =early-init.el= L135–165 wires the priority-200 pin above the local ELPA-mirror tier at 120–125 and the online fallback). The remaining "document limitations" half splits into one docs-set plus four gap-fix follow-ups that the docs cross-reference. -The shortlist's first pass DEFERRED a generic =run_shell_command=: -sandboxing to HOME + /tmp with a denylist for destructive ops is -straightforward, but the denylist can never be exhaustive, and -"confirmation for everything else" becomes click-fatigue. +Docs land in three artifacts. =docs/design/localrepo.org= carries the full architecture (tier model, install path, refresh story, all four limitations with pointers to the follow-up tasks). =.localrepo/README.org= sits next to the artifact as the user-facing entry — a short summary that survives even if =early-init.el= moves. =early-init.el= grows a commentary header that points at the README, not at the design doc — the README is what future-Craig hits first. -The children below take the other path -- *one gptel tool per -binary*, with a strictly-typed argv shape (e.g. -=pandoc_convert(input_path, output_format)=, not -=pandoc_convert(args_string)=). Each tool: +The four limitations the docs cover (each spun out below as its own task): +- Treesitter grammars (downloaded by =treesit-auto= on first use; not in the localrepo) +- Native-comp =.eln= cache (Emacs-version-specific; invalidated by version bumps) +- System-tool deps (=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, etc.; flagged at load by =cj/executable-find-or-warn=, not packageable via =package.el=) +- Refresh / update story (no dedicated script today; ad-hoc =cp= from the elpa mirrors) +*** TODO [#C] Design doc — docs/design/localrepo.org +Write the design doc: tier model, priorities, install path, refresh story, all four limitations with cross-links to the follow-up tasks below. +*** TODO [#C] README — .localrepo/README.org +Write the README at the artifact: short prose entry point summarizing the tier model, pointing at =docs/design/localrepo.org= for full detail. This is what =early-init.el='s commentary header links to. +*** TODO [#C] Commentary header in early-init.el +Add a Commentary-section header in =early-init.el= pointing at =.localrepo/README.org= for usage and =docs/design/localrepo.org= for architecture. Sits at the top of the localrepo block (around L130). +** PROJECT [#C] Migrate from Company to Corfu (with prescient integration) :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -- Validates its own paths (must be under HOME, outputs in a - sandboxed dir). -- Rejects dangerous flags explicitly (pandoc =--filter=, ffmpeg's - =-protocol_whitelist= chicanery, imagemagick's policy bypasses). -- Runs via =call-process= with an argv list -- no shell parsing, - no string-interpolation injection. -- Caps output and reports truncation inline. +Spec: [[id:68733ba2-37a7-4a7b-bfaa-b845d82ff1e7][docs/specs/company-to-corfu-migration-spec.org]] -The trade-off is breadth: every new CLI tool means a new gptel tool -file. Acceptable because (a) the list of utilities I actually need -agent access to is small (~8 below covers most of it), and (b) each -wrapper gets type-checked argv and a focused description the model -can reason over, which is genuinely better than a free-form -=run_shell_command(string)=. +*** TODO [#C] Install corfu-side packages +Add corfu, cape, kind-icon, corfu-prescient to the package list. corfu-popupinfo ships inside corfu. Spec step 1. -The =eshell_submit= entry at the end is the escape hatch for one- -off needs the wrappers don't cover -- =:confirm t= always. +*** TODO [#C] Rewrite selection-framework.el company block as corfu/cape stack +Replace the three company-* use-package blocks (lines 192-226) and company-prescient (240-243) with corfu / cape / corfu-popupinfo / kind-icon / corfu-prescient. Rename the section header Company → Corfu in the same change. Spec steps 2 + 8. -Adjacent categories: the existing =gptel-tools/= file CRUD -(=read_text_file=, =write_text_file=, =update_text_file=, -=list_directory_files=, =move_to_trash=) is the foundation this -category extends. =web_fetch= is the network-fetch counterpart. +*** TODO [#C] Swap mail-compose completion disable to corfu +Rewrite cj/disable-company-in-mu4e-compose to (corfu-mode -1) across mu4e-compose, org-msg-edit, and message modes (mail-config.el:319-333). Spec step 3. -***** TODO [#B] Document conversion (pandoc) :feature: +*** TODO [#C] Drop company-ledger for ledger's built-in capf +ledger-config.el: remove company-ledger; verify ledger-complete-at-point registers on completion-at-point-functions, add a ledger-mode-hook capf push only if it doesn't. Spec step 4. -Convert between markdown, org, html, pdf, docx, latex, epub, plain -text. Most common use: "extract this docx to markdown so I can -read it inline." Strict argv: input path, output format, optional -output path. Reject =--filter= and =--lua-filter= (arbitrary code -execution). Output written to a sandbox dir unless explicit -override. +*** TODO [#C] Drop company-auctex for AUCTeX capf + cape-tex +latex-config.el: remove company-auctex and (company-auctex-init); add cape-tex on TeX-mode-hook. Spec step 5. -***** TODO [#B] Image manipulation (imagemagick) :feature: +*** TODO [#C] Rewire eshell completion to pcomplete capf +eshell-config.el:163-171: drop company-shell and the company-mode activation; add cape-capf-buster around pcomplete-completions-at-point + corfu-mode. Spec step 6. -Resize, format-convert, get-metadata (=identify=), optionally crop / -rotate / annotate. Common use: "resize this PNG to a thumbnail" or -"convert these HEICs to JPEGs." Strict argv per operation. -Reject pre-validated dangerous formats (the historical EXR / SVG / -MVG CVE surface) unless explicitly enabled. ImageMagick's -=policy.xml= is the underlying defense; the wrapper enforces it at -the tool boundary too. +*** TODO [#C] Remove company-mode calls from prog-go/python/webdev +Delete (declare-function company-mode ...) and (company-mode) from the three mode hooks; global-corfu-mode covers them. Spec step 7. -***** TODO [#B] Audio / video processing (ffmpeg) :feature: +*** TODO [#C] Uninstall company packages + recompile +After the rewrite is green: package-delete company, -quickhelp, -box, -prescient, -ledger, -auctex, -shell; make clean && make compile. Spec step 9. -Trim, transcode, extract audio, get-metadata (=ffprobe=). Paths -under HOME only; reject network-protocol inputs (=http:= / =rtmp:= -/ =rtsp:=) so the model can't pull from arbitrary sources. Pairs -with the existing transcription module -- the same "extract audio -from video" path =cj/transcribe-media= uses internally. +*** TODO [#C] Tests: corfu activation, mail-disable, capf registration +New tests/test-selection-framework-corfu.el and tests/test-mail-config-corfu-disable.el; update ledger/latex tests to assert their capf registers. Spec Testing section. -***** TODO [#B] Content search (ripgrep) :feature: - -=rg= wrapper with path / glob filtering, result-count cap, optional -literal-vs-regex mode. Pure read. Was in the shortlist's ADOPT -bucket as =search_in_files=. Highest-leverage filesystem tool by -expected call frequency -- "where in this repo is X" is the -question I paste agent output for most often. - -***** TODO [#B] File discovery (fd) :feature: - -=fd= (or =find= fallback) wrapper, capped result count. Pure -read, lower stakes than =search_in_files= (filenames only, no -content). Common pairing: =find_file_by_name= then -=read_text_file=. - -***** TODO [#B] Metadata extraction (file / exiftool) :feature: - -=file= for MIME-type detection; =exiftool= for image / video / -audio metadata. Lets the agent answer "what is this file" or -"when was this photo taken" without me opening external tools. -Pure read. - -***** TODO [#B] Structured data processing (jq / yq) :feature: - -=jq= for JSON, =yq= for YAML / TOML. Filter / project / transform -structured data into a smaller, more focused view before reading. -Strictly read-only -- output goes to the chat, not to disk. The -agent often wants "the third element of .results" from a JSON file -and this is much cheaper than pasting the whole thing. - -***** TODO [#B] Eshell command submission :feature: - -Submit a single eshell command line, return output (capped). -=:confirm t= always -- this is the escape hatch where the -strictly-typed wrappers above don't fit, so each invocation needs -my eyeball. Eshell parses in-process (no /bin/sh fork) so the -security surface is narrower than a shell command runner, but it's -still effectively arbitrary execution -- treat it as such. +*** 2026-05-16 Sat @ 11:07:24 -0500 Goals +Drop-in replacement for the in-buffer completion stack: =company= → +=corfu=, =company-quickhelp= → =corfu-popupinfo=, =company-box= → +=kind-icon=, =company-prescient= → =corfu-prescient=, plus =cape= for +the file/keyword/dabbrev capfs that =company-files= / =company-keywords= +used to handle. Per-module fixups for ledger, AUCTeX, eshell, mu4e +compose, and the three =prog-*= modules. See the design doc for the +full translation table, migration steps, tests, and risks. -**** TODO [#B] Media and Reading Related Tools +** PROJECT [#C] Terminal GPG pinentry Completion :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-05 +:END: -Affordances over non-code content: feeds, PDFs, EPUBs, music. The -agent's job here is summarize / extract / queue, not produce. +Audit on 2026-05-27 found no trace of the =terminal-pinentry= branch on this machine: no local or remote ref, no reflog entry across 732 entries reaching back through January, no stash, no dangling commit, no sibling worktree. The 2026-01-24 session log says the branch was created that day, but the work either lived on another machine or was deleted before reaching here. The original task above (=Finish terminal GPG pinentry configuration=) is superseded by this one. -***** TODO [#B] Elfeed entry tools :feature: +Surviving footprint on this machine: one commented line at =modules/auth-config.el:83= (=;; (setq epa-pinentry-mode 'loopback)=). The hook point =env-terminal-p= exists in =modules/host-environment.el:97=. Everything else (terminal-vs-GUI branching in the epa =:config=, external pinentry wiring for GUI, =GPG_TTY= export, tests) is to be written fresh off main. -Read entry body; list unread by feed or tag; mark read after a -summary lands in a roam node or inbox. Enables "give me the -non-noise headlines from this week's feeds" flows. +Goal: in terminal Emacs, GPG passphrase prompts land in the minibuffer via loopback mode; in GUI Emacs, prompts go to the existing external pinentry. -***** TODO [#B] PDF and EPUB text tools :feature: +Open: confirm the GUI pinentry tool (2026-01-24 notes named =pinentry-dmenu=; current =auth-config.el= names no pinentry program, leaving it to =gpg-agent='s config). Also worth checking whether the =terminal-pinentry= branch survives on the laptop and should be pulled here rather than rewritten. -Extract plain text from a PDF page or page range (via =pdftotext=) -and from an EPUB (via the existing nov-mode pipeline). Lets the -agent summarize / quote a research paper or book chapter without -me pasting passages. +*** TODO [#C] env-terminal-p branch in epa :config :feature: +Inside the epa =use-package= =:config= in =modules/auth-config.el=, set =epa-pinentry-mode= to ='loopback= when =(env-terminal-p)=, else leave the external pinentry path active. Replace the lone commented line at =auth-config.el:83=. -***** TODO [#B] EMMS playback and queue tools :feature: +*** TODO [#C] GPG_TTY export for terminal sessions :feature: +When =(env-terminal-p)=, =(setenv "GPG_TTY" (shell-command-to-string "tty"))= so gpg-agent can target the controlling tty. Guard against a non-tty stdin. -Current track, queue contents, playback state; queue or play a -path; compose a playlist from a prompt ("play something focusing -that's not Nick Cave"). Light tools, but a frequent friction -point. +*** TODO [#C] gpg-agent updatestartuptty refresh in terminal :feature: +The current =call-process= to "gpg-connect-agent updatestartuptty /bye" runs unconditionally; keep it for GUI, and re-fire it on terminal entry so the agent re-binds to the current tty. -**** TODO [#B] Development Workflow Related Tools +*** TODO [#C] ERT tests for terminal vs GUI pinentry branching :test: +Test that with =env-terminal-p= stubbed t, =epa-pinentry-mode= resolves to ='loopback= after =auth-config= loads; with it stubbed nil, the loopback setting is not applied. Use =cl-letf= around =env-terminal-p=; cover normal, boundary (=epa= already loaded), error (=gpg-connect-agent= missing). -Affordances over the dev loop: compilation output, test invocation, -coverage / profile data, flycheck / flymake diagnostics. +*** TODO [#C] Minibuffer prompt in real terminal Emacs +=emacs -nw=, open an encrypted file or trigger an auth-source decrypt, confirm the passphrase prompt lands in the minibuffer rather than failing on missing pinentry. -***** TODO [#B] Compilation buffer tools :feature: +*** TODO [#C] External pinentry still fires in GUI Emacs +Restart the daemon, open a GUI frame, trigger an encrypted decrypt, confirm =pinentry-dmenu= (or whatever GUI pinentry is configured) still appears. -Read the most recent =compile= buffer output; parse error locations -to =file:line=; summarize what broke. Pairs with the F6 test-runner -flow -- "tell me what's failing" becomes a single agent turn -instead of paste + parse. +*** TODO [#C] Archive the original L3813 task +After this work lands, mark the original "Finish terminal GPG pinentry configuration" task DONE with a =CLOSED:= stamp and a one-line note pointing at this parent task. -***** TODO [#B] Project test invocation tools :feature: +** TODO [#A] Unified popup and messenger UX — placement, dismissal, one library :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-20 +:END: +Merged 2026-06-20 from the config-wide popup-policy task and the messenger-unification +task — they're the same policy at two scopes (the messenger windows are the first +concrete application of the general popup rules). Two parts: -Run =make test-file FILE=X= / =make test-name TEST=Y= / -project-equivalent and return results. Currently each agent guesses -the project convention; expose the canonical invocation explicitly -per project so the agent can run focused tests itself. +(A) Config-wide popup policy. All transient popups follow one set of principles. +Placement: when the Emacs frame is wider than tall, the popup rises from the right; +when square or taller, from the bottom — settle the aspect-ratio threshold and the +pop-out percentage. Dismissal: C-c C-c when there's an accept action, C-c C-k when +there's a cancel, otherwise =q= closes the window. Generalizes ai-term adaptive +placement (the aspect-ratio docking) and the messenger window/key rules below into +one config-wide policy. From the roam inbox. -***** TODO [#B] Coverage and profile tools :feature: +(B) Messenger unification (first application of the policy above). +Spec: [[file:docs/specs/messenger-unification-spec.org][messenger-unification-spec.org]] ([[id:4bfc2011-8ffc-4765-8886-91df12141171][by id]], Draft, 2026-06-11; keybinding-alphabet section + smoke-first parity added 2026-06-16). One library (=cj-messenger-lib.el=) gives every messenger the same shape: chat windows rise from the bottom (the signel rule, generalized), C-c C-c confirms, C-c C-k cancels, C-c C-a attaches — dispatched per backend through a registry + minor mode. Signel already conforms (reference backend); telega and slack join in phases 2-3; ERC later. All eight decisions settled 2026-06-11 (cancel closes an idle window; telega's filter-cancel shadow accepted; slack rooms join the bottom rule). Spec held open — Craig has more ideas to fold in before it's marked Ready. -Read the most recent SimpleCov JSON or profile dump. Lets the -agent answer "what's still uncovered after this push" or "what -function dominates startup time" against real measured data. +** TODO [#B] agenda sources: roam Projects missing, no existence filtering :bug:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-20 +:END: +From the 2026-06 config audit, =modules/org-agenda-config.el=: +- =:182-191= — commentary and docstrings promise org-roam nodes tagged "Project" as agenda sources, but =cj/--org-agenda-scan-files= never scans them, and files added by the roam finalize-hook are wiped on the next =cj/build-org-agenda-list= cache rebuild (≤1h). Add a roam Project pass (mirror =org-refile-config.el:101-109=) or correct the docs. +- =:186,456= — agenda file list built unconditionally (inbox/calendars may not exist on a fresh machine) and =org-agenda-skip-unavailable-files= is unset — the exact interactive-prompt class that once hung the chime daemon. Filter with =file-exists-p= + set the var as backstop. -***** TODO [#B] Diagnostic tools (flycheck / flymake) :feature: +** TODO [#B] Auto-dim: org headings, links, and tags do not dim in unfocused windows :bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-20 +:END: +auto-dim-other-buffers-affected-faces (auto-dim-config.el) remaps font-lock and a few org faces to the flat dim face, but not org-level-1..8, org-link, or org-tag, so headings, links (seen in daily-prep.org), and tags like :solo: stay lit when the window loses focus. Decide the dim approach: a flat-dim remap like font-lock (quick) versus dedicated -dim variants surfaced through org-faces / theme-studio (richer, matches the keyword work; Craig flagged org-tags may want the org-faces treatment). Consolidates three roam-inbox captures. +** TODO [#B] "? = curated help menu" convention across modes :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-20 +:END: +From the calibredb keybindings work 2026-06-06. The pattern that worked: in a modal/major-mode buffer (calibredb), bind =?= to a curated transient of the frequent workflows, and move the package's own full dispatch to =H=. It fixes the "I can't discover the keys" problem that which-key can't help with (which-key only pops up after a prefix, not for top-level single keys in a mode-map). -Surface current-buffer or project-wide errors and warnings. Useful -both as a "what's broken right now" check and as input to the -patch-narrative buffer / commit-intent workbench above. +Task: survey the modes/modules Craig works in and identify where a =?= -> curated-help-menu (transient) makes sense. Candidates: any major-mode buffer with single-key bindings and no good discovery affordance -- calibredb (done), nov, dirvish, mu4e, ghostel/term, signel, pearl/linear, ELFeed, etc. For each, note whether =?= is free or already a help dispatch, and whether a curated menu (vs the package's own) adds value. Establish it as a convention (and maybe a small helper/macro to define a curated =?= menu consistently). -**** CANCELLED [#B] gptel-magit activation fails on velox :bug:quick: +** TODO [#B] Dupre diff-changed / diff-refine-changed legibility :bug: :PROPERTIES: -:LAST_REVIEWED: 2026-06-01 +:LAST_REVIEWED: 2026-06-21 :END: -Surfaced 2026-05-25 while diagnosing an unrelated load failure over SSH. velox-specific — the workstation has a current gptel and does not show it. - -At startup (and reproducibly in batch) velox logs: "Unable to activate package `gptel-magit'. Required package `gptel-0.9.8' is unavailable." gptel-magit depends on gptel >= 0.9.8 and velox's installed gptel is older or missing, so it can't activate. A startup warning, not a blocker. +Surfaced 2026-06-07 from a pearl session designing its modified-ticket indicator (pearl marks a changed field by inheriting =diff-changed=). dupre's =diff-refine-changed= is bright gold (#ffd700) under near-white text (#f0fef0) -- WCAG contrast ~1.35, unreadable as a plain background. It only looks fine inside diff-mode because diff-mode overlays its own dark foreground. =diff-changed= (#875f00 amber) is ~5.49, readable but off the modus model. Every modus variant keeps both faces legible (contrast 9-16) by pairing a dark low-saturation background with a hue-matched foreground. -Reproduce: -: emacs --batch --no-site-file -L . -L modules --eval "(package-initialize)" --eval "(message \"done\")" 2>&1 | grep -i gptel +Ask: +1. Rework dupre's =diff-changed= and =diff-refine-changed= on modus lines: dark low-saturation background, legible foreground (plain default fg for simplicity, or hue-tinted per modus -- decide), and keep refine slightly stronger than changed (refine is the word-level emphasis inside a changed region; modus keeps them distinct). +2. While there, audit dupre's broader diff/palette faces against modus conventions (background/foreground tinting, contrast targets) and flag where it diverges. -Next step: check the installed gptel version (=(assq 'gptel package-alist)= or =M-x package-list-packages=), update gptel to >= 0.9.8, then re-evaluate gptel-magit activation. If gptel was pinned/held on velox, reconcile the pin against the gptel-magit dependency. +Reference values -- modus-vivendi: refine-changed bg #4a4a00 fg #efef80, changed bg #363300 fg #efef80. modus-operandi: refine-changed bg #fac090 fg #553d00, changed bg #ffdfa9 fg #553d00. -** PROJECT [#C] Music Open Work -Parent grouping the open music / EMMS issues; close each child independently. -*** VERIFY [#C] music: extract faces for music config :refactor:quick:solo:next: -Needs from Craig: this is theme-side work, not a config edit — the music-config faces were already stripped (2026-06-14), so "extracting" them means DEFINING them in the theme (theme-studio JSON / build-theme) for playlist name, status, the per-button on/off pair, per-key symbol+text, and other labels. That needs the actual color choices and which theme(s) to add them to. Give me the palette intent (or say "pick sensible defaults in WIP") and I'll add the face definitions. -Pull the music-config faces out to the theme (the config no longer defines faces directly): playlist name, status (paused, etc.), two mode colors per "button" (on vs off), a per-key symbol+text color, and a color for all other labels. Pairs with the 2026-06-14 face-stripping work (music-config faces were removed there and are currently undefined until the theme defines them). From the roam inbox 2026-06-15. -*** TODO [#C] music: show song information in the modeline :feature: -Show basic song information in the modeline, with streaming-source support too. Write a spec for this one first. From the roam inbox 2026-06-15. -*** TODO [#C] Internet radio now-playing song :feature: +Side-by-side legibility render: [[file:assets/2026-06-07-dupre-diff-face-legibility-compare.png][assets/2026-06-07-dupre-diff-face-legibility-compare.png]]. +** DONE [#B] F7 diff-aware coverage classifies every changed file "not tracked" :bug:solo: +CLOSED: [2026-06-22 Mon] :PROPERTIES: -:LAST_REVIEWED: 2026-06-11 +:LAST_REVIEWED: 2026-06-20 :END: -Show the currently-playing song while streaming an internet radio station. Lives in =modules/music-config.el= (EMMS + MPV backend, M3U radio stations). The track title comes from the stream's ICY metadata — EMMS exposes it via =emms-track-description= / =emms-playing-time= and updates it on the metadata-change hook; MPV reports the ICY title too. Add an option to show the song in the minibuffer (e.g. echo on track change, or an on-demand command). Consider also a mode-line indicator as a second surface. +Fixed 2026-06-22: simplecov keys are absolute, git-diff keys repo-relative, so the exact-key intersect never matched. Added =cj/--coverage-relativize-keys= and normalize both tables to repo-relative in =cj/--coverage-read-and-display= before the intersect; intersect unchanged. New =test-coverage-core--relativize-keys.el= (5 unit + 1 integration through the real parsers). Full suite green. +=modules/coverage-core.el:252= — =cj/--coverage-intersect= joins covered×changed by exact string key, but simplecov.json keys are ABSOLUTE paths while the git-diff parser returns repo-RELATIVE ones — zero matches ever, so working-tree/staged/branch scopes report ":tracked nil" for everything and F7's main feature is inert (whole-project scope works, same-source keys). Unit tests hand-build matching keys so they pass; add one integration test feeding a real undercover report + real diff. Normalize both sides to repo-relative. From the 2026-06 config audit. -*** VERIFY [#C] music-config option-combination audit + tests :test:next: +** TODO [#C] Migrate tests off mocking primitives (native-comp robustness) :test:refactor: :PROPERTIES: -:LAST_REVIEWED: 2026-06-06 +:LAST_REVIEWED: 2026-06-21 :END: -Deferred from the batch — this is a sizable test-writing audit (pairwise option combinations + new ERT coverage for music-config), better as its own focused /add-tests or /pairwise-tests session than crammed into a bug-fix sweep. No blocker; say the word and I'll run /pairwise-tests over the option space. - -Two-part task surfaced 2026-05-28 during the Signel verify walk — generalized from the "are there combinations of options that we'd want to disallow together" question. +Long-term test-quality work surfaced by re-enabling native-comp (2026-06-20). When a test redefines a C primitive or a native-compiled function (=cl-letf=/=fset=/=advice-add=), native-comp routes native callers through a trampoline, which interacts badly with mocks in three ways: trampoline-build failure under =--batch=, silent mock-bypass (native callers ignore the redefinition), and arity mismatch (the trampoline calls the mock with the primitive's max arity). -Part 1 — enumerate the configurable option surface of =modules/music-config.el=: every =defcustom=, every behavior toggle, every backend-selection variable, every cross-cutting flag (auto-play, repeat, shuffle, follow-cursor, side-window-height-fraction, etc.). Audit each option for valid value ranges. Capture the matrix in =docs/design/music-config-options.org= (or inline in the test file's header — judgment call when the matrix lands). +Done 2026-06-21 (the immediate fix): swept every arity-narrow subr mock to =(lambda (&rest _) ...)= (188 sites) and added =tests/test-meta-subr-mock-arity.el=, which fails =make test= on any arity-narrow subr mock. That kills the arity mode (the only one we've hit) and enforces it going forward. -Part 2 — combinatorial test coverage. Use the =/pairwise-tests= skill: identify parameters, value partitions, and inter-parameter constraints, build a PICT model, generate the minimal test matrix that hits every 2-way combination. For each problematic combination the matrix surfaces, decide: (a) validate at config-load time with a =user-error= that names the conflict, (b) runtime guard in the affected command, or (c) doc-only warning in the option's docstring. Disallow only the genuinely-broken pairs; doc-warn the merely-confusing ones. +This task is the durable fix the ecosystem and =elisp-testing.md= point to: restructure tests so they don't redefine primitives at all — inject dependencies, drive real state (temp-file fixtures, real buffers), or test pure helpers. That closes the two latent modes (build-failure, silent-bypass) the variadic sweep leaves open. Big, incremental, low-urgency. -The recent F10 side-window-height-fraction work and the EMMS-free refactor candidate ("Implement EMMS-free music-config architecture" above) are both natural near-term touchpoints — best to land this audit before the EMMS swap so the new architecture inherits a clean option spec. +Full mechanism, the three failure modes, the research (Emacs bug#51140, bug#61880, buttercup #230, Debian #1021842, the emacs-29 redefine-primitive warning, the manual on =native-comp-enable-subr-trampolines=), and the decision: [[file:docs/native-comp-subr-mocking.org][docs/native-comp-subr-mocking.org]]. -*** TODO [#C] Implement EMMS-free music-config architecture :refactor: +** TODO [#B] Fix up test runner :feature:refactor: :PROPERTIES: -:LAST_REVIEWED: 2026-06-01 +:LAST_REVIEWED: 2026-06-21 :END: -**** 2026-05-15 Fri @ 19:17:01 -0500 Specification -Implement the design in [[id:423bc355-18d3-4e39-9e7a-f768b865d95b][Design: music-config Without EMMS]]. - -The implementation should make =music-config.el= load without EMMS, introduce -package-owned playlist and track state, add a =cj/music-playlist-mode= view, -and route playback through a small backend protocol with an initial =mpv= -backend. Preserve the current F10 and =C-; m= user workflows where practical, -and keep M3U load/save/edit/reload plus radio station creation working. +*** 2026-05-16 Sat @ 11:15:51 -0500 Ideas +**** Current State +=modules/test-runner.el= is a solid first pass for an Emacs-config-specific ERT +workflow: +- project-scoped focus lists +- run all vs focused mode +- run ERT test at point +- load all test files +- clear ERT tests from other project roots +- keybindings under =C-; t= -Complexity estimate: high. This is a module rewrite with a new internal data -model, package-owned playlist mode, backend protocol, mpv process management, -and migration of existing EMMS-backed commands/tests. +The universal test-running direction is currently split across modules: +- =test-runner.el= owns ERT focus/state/UI. +- =dev-fkeys.el= owns F6 language detection and command generation for Elisp, + Python, Go, and partial TypeScript. -Time estimate: 2-4 focused days for an EMMS-free v1 with play/stop/next/previous, -M3U persistence, playlist UI, and focused tests. Add another 1-2 days if v1 -must include full mpv IPC support for pause, seek, and volume parity. +That split is the biggest architectural pressure point. The test runner should +eventually own runner discovery, scopes, command construction, result handling, +and UI. F6 should become a thin entry point into the runner. -Acceptance checks: -- =music-config.el= can be required in batch with no EMMS package installed. -- Existing focused music tests pass without EMMS preload or EMMS stubs except - where a compatibility adapter is explicitly under test. -- New tests cover playlist state, backend command dispatch, M3U persistence, - and the EMMS-free load smoke path. +**** Critical Design Issues +***** Too ERT-specific at the core +The current state model is named generically, but most operations assume: +- test files live in =test/= or =tests/= +- files match =test-*.el= +- tests are ERT forms +- individual tests can be selected by ERT selector regex +- loading tests into the current Emacs process is acceptable -**** TODO [#B] Pure helpers + state structs extraction :refactor: -Lift EMMS-free pure code into standalone form: file validation, recursive -collection, M3U parse/write, safe filenames, radio-station content, and -URL/file track typing. Introduce =cj/music-track= and =cj/music-playlist= -cl-structs plus state-mutation helpers (=cj/music-playlist-*= predicates and -setters). Files: =modules/music-config.el=, possibly a new -=modules/music-state.el= split. Existing pure-helper tests should pass -unchanged. +This makes the module hard to extend cleanly to pytest, Jest, Vitest, Go, Rust, +or shell test runners. The common abstraction should be "test run request" and +"test runner adapter", not "ERT file list". -Acceptance: structs defined, helpers callable in batch without EMMS loaded. +***** In-process ERT causes state contamination +=cj/test-load-all= and focused runs load test files into the current Emacs +session. This is fast and ergonomic, but it can leak: +- global variables +- advice +- loaded features +- overridden functions +- ERT test definitions +- load-path mutations -Depends on: none (start here). - -**** TODO [#B] Backend protocol + fake test backend :refactor:test: -Define the backend plist contract (=:available-p :play :pause :resume :stop -:seek :volume :status :metadata=) and =cj/music-current-backend=. Add -=cj/music-state-change-functions= abnormal hook with the v1 event set -(=started=, =paused=, =resumed=, =stopped=, =finished=, =error=, -=playlist-changed=, =mode-changed=). Create =tests/testutil-music-backend.el= -exposing =cj/test-music-fake-backend= with an event ledger. - -Acceptance: fake backend installable in tests; ordered-event assertions work -against a no-op playback flow. - -Depends on: pure helpers + state structs. +The runner should support two ERT execution modes: +- =interactive= / in-process for fast local TDD +- =isolated= / batch Emacs for reliable verification -**** TODO [#B] Read-side state API + characterization tests :test:refactor: -Implement =cj/music-playing-p=, =cj/music-paused-p=, =cj/music-current-track=, -=cj/music-playlist-state=, =cj/music-track-description=. Before rewriting -command bodies, add characterization tests against current behavior for -=cj/music-next=, =cj/music-previous=, =cj/music-toggle-consume=, -=cj/music-playlist-toggle=, =cj/music-playlist-load=, =cj/music-playlist-clear= -so the migration has a safety net. +The isolated path should be preferred for "before commit", CI parity, and +agent-driven verification. -Acceptance: read-side helpers covered; characterization tests green against -the current EMMS-backed implementation. +***** Test discovery is regex-based and fragile +=cj/test--extract-test-names= scans files with a regex for =ert-deftest=. +That misses or mishandles: +- macro-generated tests +- commented forms in unusual shapes +- multiline or reader-conditional forms +- non-ERT Elisp tests such as Buttercup +- stale ERT tests already loaded in the session -Depends on: backend protocol + fake test backend. +Better approach: +- for ERT in isolated mode, let ERT discover tests after loading files +- for source navigation, use syntax-aware forms where possible +- store discovered tests as structured records with file, line, name, framework, + tags, and runner -**** TODO [#B] Playlist major mode + render-from-state :feature: -Add =cj/music-playlist-mode= rendering the buffer as a view over -=cj/music-current-playlist=. Selected-track overlay + face, header reads -package state, full keymap from design Section "Playlist Buffer" (RET/p, SPC, -s, >/<, f/b, +/=/-, a, A, c/C, L/S/E/g, r/t/z/x, Z, i, o, q, S-up/down). -Preserve the active-window background highlight. +***** Path containment has at least one suspicious edge +=cj/test--do-focus-add-file= checks: -Acceptance: opening the playlist renders package state; reorder/shuffle/clear -go through state mutations and re-render; tests cover header + overlay -positioning. +#+begin_src elisp +(string-prefix-p (file-truename testdir) (file-truename filepath)) +#+end_src -Depends on: read-side state API. +That should use =cj/test--file-in-directory-p= or ensure the directory has a +trailing slash. Otherwise sibling paths with a shared prefix are a recurring +class of bug. -**** TODO [#B] mpv backend implementation :feature: -Implement =cj/music-mpv-*= backend functions. Phase the work per migration -plan §5: (a) process spawn, UID/PID-stamped socket under -=temporary-file-directory=, stale-socket sweep, IPC connect via -=make-network-process :family 'local=, state-hook plumbing. (b) play/stop/ -next/previous + finished-track auto-advance with deliberate-stop tracking. -(c) pause/resume, seek, volume over JSON IPC. (d) metadata read on track -start. Add =cj/music-doctor= reporting platform capabilities; ship Windows -degraded mode (play/stop/next/previous only via stdin/=call-process=). +***** Runner commands are shell strings too early +=cj/--f6-test-runner-cmd-for= returns shell command strings. That makes it +harder to: +- inspect command parts +- safely quote arguments +- offer command editing +- run via =make-process= / =compilation-start= without shell ambiguity +- attach metadata +- rerun exact invocations +- convert commands into UI labels -Acceptance: integration tests tagged =:slow= and skipped when =mpv= not on -PATH; on Linux/macOS pause/seek/volume parity works; clean socket lifecycle -across Emacs restart and exit. +Prefer a structured command object: -Depends on: backend protocol + fake test backend. +#+begin_src elisp +(:program "pytest" + :args ("tests/test_foo.py" "-q") + :default-directory "/project/" + :env (("PYTHONPATH" . "...")) + :runner pytest + :scope file) +#+end_src -**** TODO [#B] Command + Dired/Dirvish rewire :refactor: -Migrate user-facing commands (=cj/music-play=, =cj/music-pause=, -=cj/music-stop=, =cj/music-next=, =cj/music-previous=, seek/volume, -random/repeat/consume/shuffle toggles) to operate on package state and call -=cj/music-current-backend=. Update Dired/Dirvish =+= add routing, -M3U load/save/edit/reload, radio-station creation, F10 toggle, and =C-; m= -keymap entries to drop EMMS symbols. Migrate command-flow tests to the fake -backend. +Render to a shell string only at the final compilation boundary. -Acceptance: full keymap functional end-to-end against the fake backend; -characterization tests still green; Dirvish =+= add path covered. +***** F6 and =C-; t= workflows duplicate the same domain +F6 already handles "all tests" and "current file's tests" for multiple +languages. =C-; t= handles ERT-only focus and run state. These should converge +on one runner service: +- F6: quick entry point +- =C-; t=: full runner menu +- both call the same scope/adapter engine -Depends on: playlist major mode + mpv backend. +***** Test directory discovery is too narrow +Current discovery prefers =test/= then =tests/=, with a global fallback. Real +projects often need: +- Python: =tests/=, package-local =test_*.py=, =pytest.ini=, =pyproject.toml= +- JS/TS: =package.json= scripts, =vitest.config.*=, =jest.config.*=, + =*.test.ts=, =*.spec.ts= +- Go: package directories, =go.mod= +- Rust: =Cargo.toml=, integration tests under =tests/= +- Elisp packages: =Makefile=, =Eask=, =ert-runner=, Buttercup, =tests/= -**** TODO [#B] EMMS removal + parity walk :test: -Remove =cj/emms--setup=, the on-demand EMMS loader, and the =use-package emms= -block. Add the EMMS-free batch-load smoke test (=music-config.el= requires -clean without EMMS installed). Run the 22-step parity walk from design -§"Parity Walk" against the new implementation; record measurements against -the performance budget (1000-track load <500ms, reorder <50ms, IPC dispatch -<100ms, header refresh <16ms) and note any deviations. +Discovery should be adapter-specific and project-config-aware. -Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity -walk recorded as a completion log entry under the parent task. +***** No structured result model +=cj/test-last-results= exists but is not meaningfully populated. A powerful +runner needs a normalized result model: +- run id +- started/finished timestamps +- status: passed/failed/errored/cancelled/skipped/xfail/xpass +- command +- runner adapter +- scope +- exit code +- duration +- failed test records +- file/line locations +- raw output buffer +- coverage artifact paths -Depends on: command + Dired/Dirvish rewire. +This enables last-failed, failures-first, summaries, dashboards, and AI-assisted +failure explanation. -** PROJECT [#C] Calibre Open Work -:PROPERTIES: -:LAST_REVIEWED: 2026-06-06 -:END: -Parent grouping the open Calibre / ebook-workflow issues; close each child independently. The EPUB reading-width tasks were already resolved (2026-05-12/14). +***** No failure parser / navigation layer +Compilation buffers are useful, but the runner should parse common failure +formats and provide: +- next/previous failure +- jump to source line +- failure summary buffer +- copy failure context +- rerun failed test at point +- annotate failing tests in source buffers -*** 2026-06-12 Fri @ 07:34:05 -0500 Calibre bookmark naming ships "Author, Title" from the filename -When I hit m in calibre, I'm making my place in the book with a bookmark. -While sometimes, the books look fine: "The A.B.C. Murders - Agatha Christie.epub" -Sometimes they look not so good: Engines of Logic_ Mathematicians and the O - Martin Davis.pdf or Software Architecture_ The Hard Parts _ Mo - Neal Ford.pdf +Adapters can provide regexes/parsers for ERT, pytest, Jest/Vitest, Go, Rust, +and shell. -What I would like to do is to have the bookmarks be saved in the following format: +***** Missing watch/rerun modes +Modern test runners optimize the feedback loop: +- pytest supports selecting tests, markers, last-failed, failures-first, + stepwise, fixtures, xfail/skip, plugins, and cache state. +- Jest/Vitest support watch workflows, changed-file selection, coverage, + snapshots, and rich interactive filtering. Vitest also defaults to watch in + development and run mode in CI. +- Go and Rust runners commonly support package-level runs, regex selection, + race/coverage flags, and cached test behavior. -Author, Title [no extension]. Underscores should be stripped. +The Emacs runner should expose the subset that maps well to editor workflows: +- current test +- current file +- related test file +- focused set +- last failed +- failed first +- changed since git base +- watch current scope +- full project +- coverage for current scope -Root cause: in a nov buffer =m= is =bookmark-set= (rebound at calibredb-epub-config.el:311); nov's =nov-bookmark-make-record= names the record =(buffer-name)= -- the EPUB filename. +**** Proposed Architecture +***** Core Types +Use plain plists initially; promote to =cl-defstruct= only if helpful. -Implemented 2026-06-06. Source decision: parse the *filename*, not the embedded EPUB metadata -- under Calibre's "<Title> - <Author>.epub" naming the filename is more complete (the embedded metadata had truncated titles, author-sort "Last, First" forms, and lost punctuation; see the separate metadata-cleanup task). A =:filter-return= advice on =nov-bookmark-make-record= rebuilds the name from the record's filename: split on the last " - " into title/author, restore the colon Calibre sanitized to "_ " (-> ": "), reorder to "Author, Title". Pure helpers =cj/--nov-clean-title= + =cj/--nov-bookmark-name-from-file= in =modules/calibredb-epub-config.el=; 10 ERT tests in =tests/test-calibredb-epub-config--bookmark-name.el=. Live in the daemon. +#+begin_src elisp +;; Test runner adapter +(:id pytest + :name "pytest" + :languages (python) + :detect cj/test-pytest-detect + :discover cj/test-pytest-discover + :build-command cj/test-pytest-build-command + :parse-results cj/test-pytest-parse-results + :capabilities (:current-test :file :project :last-failed :coverage :watch)) -Existing bookmarks: the 3 nov bookmarks in =~/sync/org/emacs_bookmarks= were renamed by hand (one-pass, in the daemon + saved; backup at =emacs_bookmarks.bak-2026-06-06=): "Edward Kanterian, Frege: A Guide for the Perplexed", "Agatha Christie, The A.B.C. Murders", "Edward Abbey, The Fool's Progress: An Honest Novel". +;; Test run request +(:project-root "/repo/" + :language python + :framework pytest + :scope file + :file "/repo/tests/test_api.py" + :test-name "test_create_user" + :extra-args ("-q") + :profile default) -Manual verify filed under the Manual testing and validation parent. +;; Test run result +(:run-id "..." + :status failed + :exit-code 1 + :duration 2.14 + :failures (...) + :output-buffer "*test pytest*" + :artifacts (...)) +#+end_src -*** 2026-06-12 Fri @ 07:34:05 -0500 Curated Calibre keybinding menu + docked description shipped -Relocated from the global capture inbox 2026-06-06. Want a discoverable set of keybindings (visible in which-key) for the most frequent calibredb workflows: -- Switch to a library (e.g. Literature), sort by last name, scroll the list. -- Scope/filter the list in place, keeping the current library scope: - - by format (e.g. epubs only) - - by author last name (exact == or ^begins-with some text) - - sort by title, publication date, or group by format -- One key pops up the selected book's description in a bottom-30% buffer, dismissed with q (same display pattern as the signel chat dock). -- RET opens the book in the appropriate viewer. -Survey finding 2026-06-06: calibredb already binds almost all of this in calibredb-search-mode-map (S/L library, g filter [f format, a author, t tag, d date], o sort [t title, a author, p pubdate, f format], RET open) and even ships transient menus (? = calibredb-dispatch, g, o). The real problem was discoverability -- they are top-level single keys (which-key never pops up) and Craig didn't know ? opened a menu. calibredb-quick-look is macOS-only; the detail view (v -> *calibredb-entry*, q quits) is the description but opens full-window. +***** Adapter Registry +Create a registry like: -Implemented 2026-06-06 in =modules/calibredb-epub-config.el=: -- A curated transient =cj/calibredb-menu= (library switch; filter format/author/reset; sort author/title/pubdate/format; open; describe; H = full calibredb-dispatch) bound to =?= in calibredb-search-mode-map. calibredb's own full dispatch moved to =H=. Defined in the use-package =:config= (needs the elpa transient, which batch doesn't load) -- the "? brings up a curated help menu" convention. -- Bottom-30% description dock: =calibredb-show-entry-switch= -> =pop-to-buffer= + a =display-buffer-alist= rule for =*calibredb-entry*= (display-buffer-at-bottom, height 0.3); =cj/calibredb-describe-at-point= shows the entry without switching focus so q dismisses it. Same pattern as the signel chat dock. -1 ERT test (the describe command; the transient/bindings/dock need the elpa transient + live calibredb, verified in the daemon). Author "begins-with" is covered well enough by g a's completing-read over "Last, First"; a true regex filter was not built. Manual verify filed under the Manual testing and validation parent. +#+begin_src elisp +(defvar cj/test-runner-adapters nil) +(cj/test-register-adapter 'pytest ...) +(cj/test-register-adapter 'ert ...) +(cj/test-register-adapter 'vitest ...) +#+end_src -*** TODO Embed Calibre DB metadata into the EPUB files -Surfaced 2026-06-06 while building the bookmark naming: the metadata embedded in the EPUB files' OPF is worse than Calibre's database metadata. nov reads the embedded OPF and got truncated titles ("Frege" vs the filename's "Frege: A Guide for the Perplexed"), author-sort "Last, First" forms ("Christie, Agatha"), and lost punctuation ("A.B.C." -> "A B C"). The filenames (from Calibre's curated DB) are the good copy. Fix on the Calibre side: select all (or by library), run "Edit metadata -> Embed metadata into book files" so the DB metadata is written into each EPUB's OPF. Consider auditing author vs author_sort first. After embedding, the in-file metadata matches the library and any tool reading the files (nov, other readers, re-imports) gets the good data. Not an Emacs task; Calibre-side bulk maintenance. +Runner selection should consider: +- buffer file extension +- project files +- explicit user override +- available executables +- package manager scripts +- existing Makefile targets -** PROJECT [#C] 2026-06 full config audit — findings backlog :refactor: -Module-by-module review of all 121 modules + init/early-init, holistic passes (startup/perf, stability, UX consistency, package strategy), and spin-offs into pearl, chime, emacs-wttrin. Method: parallel read-only review agents per module group; key claims spot-verified (incl. against the live daemon) before filing. Run 2026-06-11/12, COMPLETE. Tally: ~165 module findings + ~40 holistic + 30 spin-off ≈ 235 total; 40 high-impact bugs filed as standalone tasks above this parent; the rest live in the group children below. Spin-off findings delivered as inbox handoffs to pearl, chime, and emacs-wttrin (2026-06-12-0057). Start with the synthesis child below for the recommended attack order. +***** Scope Model +Make scopes explicit and shared across languages: +- =test-at-point= +- =current-file= +- =related-file= +- =focused-files= +- =last-failed= +- =changed= +- =package/module= +- =project= +- =coverage= +- =watch= -*** Synthesis: the overall picture and attack order -Six cross-cutting themes, then the order I'd work them. +Each adapter can say which scopes it supports. Unsupported scopes should produce +clear user-errors with suggestions. -Themes: -1. Performance has one systemic lever, not many small ones: native-comp is accidentally OFF config-wide and GC sits at the stock 800KB ([#A] task). Daemon init itself is healthy (1.11s measured). Fix the lever before any micro-deferral work, and before burning time on the org-capture-perf debug. -2. A "dangerous defaults" safety cluster: yes-or-no-p fset (single-keystroke shutdown/file-destruction), the silently-failing Wayland lock screen, erc-yank's public gists, mu4e's broken trash/refile on the primary account. All four are [#A]/[#B] standalones; do these first — they're where the config can actually hurt you. -3. Calendar/agenda data correctness: calendar-sync's RFC trio (vanishing final occurrences, resurrected cancelled meetings, collapsed multi-day events) + agenda sources missing roam Projects. Meetings are missed over this. -4. Recurring mechanical defect classes worth sweeping as one commit each, config-wide: use-package :hook "-hook" suffix trap (org-babel, eshell, latex); eval-when-compile-only requires read at runtime (auth-config, keyboard-macros, erc-config); M-S-<letter> bindings vs uppercase events (4 dead keys + 1 asymmetry); raw C-; entries bypassing cj/register-prefix-map (8 modules); unreachable modules (prog-lsp, ledger-config, show-kill-ring, mu4e-org-contacts-setup); config for package versions long gone (mu4e 1.7 block, dashboard override, org timeline, checkdoc-arguments). -5. The test suite has a blind-spot class: characterization tests asserting BROKEN output (reverse-lines, heavy-box, undo-kill's explicit 0), unit tests hand-building data that hides integration mismatches (F7 coverage paths), and an integration gate that prints green over "Ran 0 tests" (chime). When fixing any standalone bug above, fix its test to assert correct behavior — and consider extending the architecture smoke test to mechanically pin the class-4 sweeps (hooks must be bound after load, no raw C-; binds, no M-S-<letter> specs, no eval-when-compile requires of runtime vars). -6. Consistency wants conventions, not patches: one notification facade (cj/notify — messenger spec addendum already covers the messenger half), one confirmation tier (the fset fix), one prefix-registration mechanism with labels, one buffer-naming shape. The messenger-unification registry mindset generalizes. +***** Command Builder Pipeline +1. Detect project. +2. Detect language/framework candidates. +3. Resolve user-requested scope. +4. Build structured command object. +5. Optionally let user edit command. +6. Run via =compilation-start= or =make-process=. +7. Parse output/result artifacts. +8. Store normalized result. +9. Update UI/modeline/messages/failure buffer. -Attack order: (a) the three [#A]s + gptel-shadow (it's blocking the filed gptel-magit investigation); (b) the daily-data pair — mail trash/refile + calendar RFC trio; (c) the :quick:solo: standalone sweep — roughly 20 one-to-five-line fixes, a satisfying solo batch; (d) the class-4 mechanical sweeps, one commit per class, each with its smoke-test guard; (e) the consistency conventions, opportunistically as those modules get touched. +***** Keep Makefile Support But Do Not Require It +For this Emacs config, =make test-file= and =make test-name= are useful and +should remain the default Elisp isolated path. But adapter detection should +support: +- direct =emacs --batch= ERT invocation +- =make test= +- =make test-file= +- =make test-name= +- Eask +- Buttercup -*** TODO Findings: foundation/system group -From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: -- [BUG] =keyboard-compat.el:121= — terminal arrow-key fix runs once on emacs-startup-hook; =input-decode-map= is terminal-local, so =emacsclient -t= frames under the daemon never get it. Register on =tty-setup-hook= (GUI half already uses =server-after-make-frame-hook=). -- [BUG] =config-utilities.el:142= — =cj/recompile-emacs-home=: =(boundp 'native-compile-async)= is always nil (it's a function — needs =fboundp=), so native compilation is never selected; and the helper deletes =<dir>/eln= when the real cache is =eln-cache/= (derive from =native-comp-eln-load-path=). Extend the existing test. -- [BUG] =system-utils.el:94= — success message args swapped: prints "Running notes.txt on mpv...". Trivial; wired into dirvish (O) and calibredb so it shows regularly. -- [REMOVE] =local-repository.el:51= — =localrepo-initialize=, its three defcustoms, and unprefixed =car-member= are dead; early-init owns archive setup with its own divergent path constant. Shrink to =cj/update-localrepo-repository= pointed at early-init's =localrepo-location=. -- [REMOVE] =keybindings.el:146-147= — C-x C-f unset/reset is a no-op (already find-file); comment wrong. Delete or retarget. -- [COVERAGE] =local-repository.el= — only module in the group with no test file. +**** Elisp-Specific Improvements +***** Add isolated ERT runs +Support batch commands for: +- all project tests +- one test file +- one test name +- focused files +- last failed, once result parsing exists -*** TODO Findings: UI core group -From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: -- [BUG] =font-config.el:262= — emojify =:defer 1= means :config runs before any daemon GUI frame exists; =env-gui-p= picks ='unicode= permanently, GUI frames never get image emojis. Compute per-frame (=server-after-make-frame-hook=) or test =(daemonp)=. -- [BUG] =font-config.el:283= — =cj/display-available-fonts= errors on second invocation: first call's =special-mode= sets read-only; next call's erase/insert signals. Wrap in =inhibit-read-only=. (Also [COVERAGE]: untested — a call-twice test catches it.) -- [UX] =undead-buffers.el:82= — =cj/kill-other-window= in a single-window frame kills the buffer you're looking at (other-window no-ops; only delete-window is guarded). Add the sibling's =(user-error "No other window")= guard. -- [UX] =undead-buffers.el:48= — C-u C-x k silently marks a buffer undead (then it refuses to die with no explanation later). Undocumented mode-switch inside a core-command remap; document or split into its own command. -- [ENHANCE] =ui-theme.el:87= — theme persistence silently fails on a fresh machine until =persist/= exists; =make-directory= before the writability check. -- [REMOVE] =dashboard-config.el:32-58= — =dashboard-insert-bookmarks= override is dead code: the :demand t require lets upstream dashboard-widgets.el redefine it; behavior survives only because upstream natively honors the settings now. Delete. -- [REMOVE] =font-config.el:199-220= — all-the-icons stack (2 =:demand t= packages + unprompted network font install on fresh machines) likely redundant with nerd-icons everywhere; verify keyboard-compat's reference then drop. -- [REMOVE] =ui-config.el:185= — duplicate =(use-package nerd-icons :defer t)= stanza; nerd-icons-config owns it. Delete stanza + stale Commentary bullet. +Use the same Makefile targets in this repo, but design the adapter so other +Elisp projects can run without this Makefile. -*** TODO Findings: buffer/window libs group -From agents 2026-06-11; spot-verified sample. Remaining findings beyond the standalone bug tasks: -- [REMOVE] =show-kill-ring.el= — loaded by nothing (init require deliberately removed in b785a19d), so its M-S-k binding is dead; =keyboard-compat.el:177= still installs the M-K → M-S-k translation whose only purpose was this module. Re-add or delete module + stale translation/comment (consult-yank-pop largely supersedes it). -- [UX] =selection-framework.el:38= — =vertico-sort-function= custom is dead config: =vertico-prescient-mode= (line 250) replaces sorting when it activates. Pick one policy (drop the custom, or =vertico-prescient-enable-sorting nil=). -- [BUG] =custom-buffer-file.el:486= — =cj/view-email-in-buffer= leaks MIME handles when no displayable part: =user-error= fires before =mm-destroy-parts=. unwind-protect. -- [ENHANCE] =custom-buffer-file.el:49= — eager =(require 'mm-decode)= at startup only for macro expansion; runtime require already exists at line 481. Make it =eval-when-compile=. -- [UX] =custom-buffer-file.el:221= — =cj/copy-link-to-buffer-file= is a silent no-op in non-file buffers while siblings signal =user-error=. Match them. +***** Support Buttercup/Eask Later +Buttercup uses BDD-style =describe= / =it= suites and is common in Elisp +package testing. Eask is often used to run package tests. Add adapter slots +for these instead of hard-coding ERT forever. -*** TODO Findings: editing helpers group -From agents 2026-06-11; spot-verified sample (jump-paren, sortable-time confirmed). Beyond the standalone heavy-box task: -- [BUG] =custom-misc.el:48= — jump-to-matching-paren with point ON a closer lands at the last inner sexp, not the opener (batch-verified). =(forward-char)= before =(backward-sexp)= in the char-after-closer case; the test only covers the after-closer position. -- [BUG] =custom-datetime.el:71= — "sortable" time format is 12-hour ="%I:%M:%S %p %Z"= — "01:00:00 PM" sorts before "09:00:00 AM". Should be ="%H:%M:%S"=. -- [BUG] =custom-comments.el:82= — =cj/comment-reformat= prints "No region was selected" even on success (message outside the if-else), and the fill-column shrink/restore isn't unwind-protected — an error leaves fill-column permanently -3. Use let-binding + =user-error=; also =mark-active= vs the config's usual =use-region-p=. -- [BUG] =custom-line-paragraph.el:52= — join-line-or-region without region inserts a spurious blank line mid-buffer (verified); only insert the newline at eobp. -- [BUG] =custom-line-paragraph.el:77= — duplicate-line-or-region splits a mid-line-ending region via open-line and duplicates an extra empty line when the region ends at bol. Normalize bounds to whole lines. -- [BUG] =custom-ordering.el:158= — reverse-lines and number-lines mishandle the trailing newline ("a\nb\n" → "\nb\na"); the trailing-newline test asserts the broken output. =cj/--arrayify= (line 43) has the correct pattern — apply it; fix the characterization test. -- [BUG] =custom-comments.el:152= — inline-border lines come out 2 chars short for even-length or empty text (parity computed from text length instead of remaining width); stacked dividers misalign. -- [UX] =custom-text-enclose.el:216= — indent-lines =(interactive "p\nP")= couples COUNT and USE-TABS to one prefix arg — multi-column space indent is impossible interactively; docstrings claim "default 4" but "p" defaults to 1 (same in dedent :256). -- [REMOVE] =custom-ordering.el:90= — =cj/arrayify-python= is byte-identical to =cj/arrayify-json= (two bindings, same output). Delete one or differentiate (single quotes for Python). -- [UX] =custom-case.el:66= — title-case contradicts its docstring: "is" is in word-skip despite "linking verbs are major words"; no sentence-restart capitalization after periods; no capitalize-last-word rule. Align list + docstring. +***** Avoid unnecessary global ERT deletion +=cj/ert-clear-tests= is a pragmatic fix for project contamination, but the +stronger long-term answer is isolated runs plus project-scoped discovery. Keep +the cleanup command, but do not make correctness depend on deleting global ERT +state. -*** TODO Findings: text/prose tools group -From agents 2026-06-11. Beyond the standalone markdown/latex tasks: -- [BUG] =text-config.el:72= — "M-S-i" for edit-indirect-region is unreachable: Meta+Shift+i generates the event M-I, not M-S-i, so the keypress falls back to M-i tab-to-tab-stop. Rebind as "M-I" (the "was M-I" comment thought the rename was a no-op; it wasn't). -- [BUG] =keyboard-macros.el:46= — user-constants required only =eval-when-compile= but =macros-file= is read at runtime; works only because init.el loads user-constants first. Plain require (same trap as auth-config). -- [BUG] =keyboard-macros.el:137= — kill-emacs-hook fires =y-or-n-p= + an interactive name prompt whenever any last-kbd-macro exists — hazardous for daemon/systemd shutdown (no one to answer) and noisy for throwaway macros. Guard =(and last-kbd-macro (not noninteractive))= minimum; consider dropping the prompt (M-F3 already persists named macros). -- [BUG] =lorem-optimum.el:221= — empty Markov chain (missing assets/liber-primus.txt) makes =cj/lipsum-insert= do =(insert nil)= — cryptic wrong-type error far from cause. Signal =user-error= naming the fix; also Commentary advertises "M-x cj/lipsum" but it has no interactive spec. -- [UX] =flyspell-and-abbrev.el:230= — every C-' press re-runs =flyspell-buffer= over the whole buffer while flyspell-mode is off (the documented word-by-word workflow = O(buffer) per keypress in large files). Call =cj/flyspell-on-for-buffer-type= so the mode sticks and the scan runs once. -- [ENHANCE] =text-config.el:121= — accent is wired to the company backend (=accent-company=); the filed Company→Corfu migration task doesn't list it, so C-` breaks silently post-migration. Add to the migration scope or switch to =accent-menu= now. +**** Python / pytest Ideas +- Detect pytest by =pyproject.toml=, =pytest.ini=, =tox.ini=, =setup.cfg=, or + presence of =tests/=. +- Build commands for: + - project: =pytest= + - file: =pytest path/to/test_file.py= + - test at point: =pytest path/to/test_file.py::test_name= + - class method: =pytest path::TestClass::test_method= + - marker: =pytest -m marker= + - last failed: =pytest --lf= + - failed first: =pytest --ff= + - stop after first: =pytest -x= + - coverage: =pytest --cov=...= +- Parse output for failing node ids and =file:line= references. +- Read pytest cache for last-failed where useful. +- Offer marker completion by parsing =pytest --markers= or config files. +- Surface xfail/skip separately from hard failures. -*** TODO Findings: org core group -From agents 2026-06-11; spot-verified sample (dailies head, babel hook, void bindings confirmed). Beyond the standalone tasks: -- [BUG] =org-babel-config.el:27= — =:hook (org-babel-after-execute-hook . org-redisplay-inline-images)= gets a second "-hook" appended (symbol unbound at expansion, doesn't end in -mode) → registers on nonexistent =org-babel-after-execute-hook-hook=; inline dot-graph images never refresh after C-c C-c. Write =(org-babel-after-execute . ...)= or add-hook in :config. -- [BUG] =org-roam-config.el:67,71= — C-c n p / C-c n w bound (and which-key-labeled) to =cj/org-roam-find-node-project= / =-webclip=, defined nowhere — keypress errors "autoloading failed to define function". Define via =cj/org-roam-find-node= (a project template exists) or drop bindings + labels. -- [BUG] =org-export-config.el:74-81= — ox-texinfo block can never run (=:defer t=, no trigger, excluded from line-47 dolist and =org-export-backends=); commentary still advertises Texinfo. Add to the dolist or delete; also commentary says "subtree default scope" vs actual ='buffer= (line 61). -- [UX] =org-roam-config.el:50-63= — two parallel template dirs drift: :custom templates read =~/.emacs.d/org-roam-templates/= while find-node-topic/recipe read =roam-dir/templates/= — overlapping recipe/topic/v2mom files, edits don't propagate. Pick one canonical dir. -- [REMOVE] =org-agenda-config.el:84= — dead =timeline= entry in org-agenda-prefix-format (removed in org 9.1). Also =org-config.el:47-48= — the TASK note claiming =org-indent-indentation-per-level= "doesn't exist" is wrong (real org-indent defcustom); restore the setq or fix the comment. -- [REMOVE] =org-babel-config.el:161= — =org-html-footnote-separator= is an ox-html setting parked in the babel module with a wrong comment; =org-roam-config.el:76= similarly hides =org-agenda-timegrid-use-ampm= in roam's :config (only takes effect after roam loads). Move both to their owning modules. -- [REMOVE] =org-roam-config.el:363-390= — 28-line commented consult-org-roam block on a TASK comment; its proposed C-c n l / C-c n r now collide with live bindings, so it can't ship as written. Decide + delete (git keeps the draft). -- [COVERAGE] =org-agenda-config.el:423= cj/add-timestamp-to-org-entry (defvar-inside-defun smell), =org-roam-config.el:115,185= node-insert-immediate + finalize-hook — untested. +**** TypeScript / JavaScript Ideas +***** Detection +Detect runner by project files and scripts: +- =vitest.config.ts/js/mts/mjs= +- =jest.config.ts/js/mjs/cjs= +- =package.json= scripts: =test=, =test:watch=, =vitest=, =jest= +- lockfile/package manager: =pnpm-lock.yaml=, =yarn.lock=, =package-lock.json=, + =bun.lockb= -*** TODO Findings: org apps + calendar-sync group -From agents 2026-06-11/12; spot-verified sample (UNTIL comparisons, EXDATE regex, drill setq confirmed). Beyond the standalone tasks: -- [BUG] =org-reveal-config.el:241= — seven raw =global-set-key= "C-; p ..." calls carry a hidden load-order dependency on keybindings.el (signals "non-prefix key" otherwise); every sibling uses =defvar-keymap= + =cj/register-prefix-map=. Convert. -- [BUG] =org-drill-config.el:131= — =:load-path "~/code/org-drill"= dev checkout breaks drill on machines without it (velox already diverges per the gptel-magit task). Guard with =file-directory-p= fallback to :vc. -- [UX] =org-contacts-config.el:146= — =cj/org-contacts-find= visits the file BEFORE prompting (C-g strands you at point-min) and plain =search-forward= can match body text in another entry. Collect heading positions in org-map-entries, goto after prompt. -- [REMOVE] =calendar-sync.el:1240= — =calendar-sync--fetch-ics= (buffer-string variant) is dead; the sync path uses the temp-file variant exclusively. 30 lines of duplicate curl/sentinel logic that will drift. -- [REMOVE] =org-webclipper.el:216-241= dead commented keymap blocks; =org-contacts-config.el:118-124= commented duplicate capture template flagged "TASK: duplicate?!?". Delete both (git keeps drafts). -- [COVERAGE] =calendar-sync.el:1274= — fetch sentinel branches (curl failure, temp-file cleanup, signal exit) untested; dispatch tests stub above this layer. +Prefer project scripts over raw =npx= when present: +- =pnpm test -- path= +- =npm test -- path= +- =yarn test path= +- =bun test path= -*** TODO Findings: mail group -From agents 2026-06-12; spot-verified sample (cmail trash gap, no refile folders, gmail-first contexts confirmed). Beyond the standalone [#A] task: -- [BUG] =mail-config.el:392-407= — C-; e account nav lambdas call =mu4e-search=, not autoloaded — void-function before first mu4e launch. Add to :commands or require first. -- [BUG] =mail-config.el:481-484= — unconditional =org-msg-edit-mode= :after advice on replies defeats the =(reply-to-text . (text))= alternative at :459 and re-runs a major mode org-msg already set up. Gate or remove. -- [BUG] =mu4e-attachments.el:222= — the *mu4e attachments* selection buffer saves through stale MIME handles if the view changed before s — errors or saves the wrong message's parts. Check =buffer-live-p= per handle at save. -- [BUG] =mail-config.el:329= — "save attachment" in =mu4e-headers-actions= can't work from headers (MIME vars are view-buffer-local, nil in headers-mode). Drop it there. -- [BUG] =mail-config.el:282-305= — HTML view block sets variables obsolete since mu4e 1.7 (installed 1.14.1): =mu4e-view-prefer-html=, =mu4e-html2text-command= (also set twice: 186, 285), =mu4e-view-show-images=, =mu4e-view-image-max-width=. The pandoc/w3m selection never runs; shr renders regardless. Delete the dead block (image/privacy reconciliation already filed separately). -- [BUG] =mail-config.el:45-49,80-89= — top-level =(defvar message-send-mail-function nil)= pre-empts message.el's defcustom default; with msmtp absent the fallback leaves it nil → "invalid function: nil" on first send. Explicit =smtpmail-send-it= fallback or descriptive user-error. -- [UX] =mail-config.el:171,196-199= — =pick-first= + gmail listed first makes gmail the startup context though cmail reads as primary everywhere else — quiet wrong-account hazard for the first compose. Reorder contexts. -- [REMOVE] =mu4e-org-contacts-setup.el= — unreachable (nothing requires it; mail-config calls activation directly) and its featurep gate would be nil at init anyway. Delete or fold its two setqs into mail-config. -- [REMOVE] =mail-config.el:208,232= — =mu4e-starred-folder= isn't a mu4e variable (invented, no effect); =:174= =mu4e-maildir= is the obsolete alias of root-maildir set on the previous line. Drop all three. -- [REMOVE] =mu4e-org-contacts-integration.el:158,171-172= — hook surgery on =mu4e--compose-setup-completion= is a no-op on mu4e 1.14 (called directly, not via hook; already gated by the var activation sets). Delete both hook calls. -- [COVERAGE] =mu4e-attachments.el:101-105= — mid-batch save-failure path and stale-handle scenario untested. +***** Scopes +- current file: =vitest run path= or =jest path= +- test at point: use nearest =it= / =test= / =describe= string and pass =-t= +- watch current file +- changed tests where runner supports it +- coverage current file/project +- update snapshots -*** TODO Findings: messengers group -From agents 2026-06-12. Beyond the standalone tasks; several feed the messenger-unification spec: -- [BUG] =signal-config.el:201= — contact cache docstring claims "cleared on signel-stop/restart"; nothing clears it (grep: fork never references it). Stale list after relink/reconnect. Advise =signel-stop= or clear on start. -- [BUG] =signal-config.el:298= — fetched-and-empty contact list is indistinguishable from cold cache (nil), so a zero-contact account re-runs the blocking fetch (up to fetch-timeout) on every C-; M m. Cache a sentinel. -- [UX] =slack-config.el:208= — =cj/slack-notify= lacks signel's hardening: no truncation (giant toasts), no sound gating, no notifications-notify fallback when the script is absent. Unification-relevant: extract a shared =cj/messenger-notify= (title prefix, truncation, sound flag, script-with-fallback) — noted in the unification spec. -- [ENHANCE] =telega-config.el:52= — telega has NO notification path (=telega-notifications-mode= not enabled); incoming Telegram messages invisible unless the buffer is on screen. Enable, or route through the shared notifier. Unification-relevant. -- [COVERAGE] — =cj/erc-join-channel-with-completion= (erc:148, four-way reconnect branching), =cj/erc-connected-servers= (would have caught the tautology), =cj/slack-notify= predicates, =cj/signel--ensure-started= branches — all untested. +***** Result Parsing +Parse: +- failing test names +- file paths and line numbers +- snapshot failures +- coverage summary -*** TODO Findings: programming group -From agents 2026-06-12; spot-verified sample (prog-lsp unreachable confirmed by grep). Beyond the standalone tasks: -- [BUG→FOLD] =prog-lsp.el= — the module is UNREACHABLE: nothing requires it, so its entire LSP policy (TRAMP guard, file-watch ignores, read-process-output-max, idle-delay 0.5) is dead while prog-general.el:388-416's older conflicting block wins (idle 0.1, lsp-ui-doc on). Fold this fact into the filed "Make prog-lsp.el the single owner of generic LSP policy" task — it doesn't currently record that prog-lsp never loads. -- [BUG] =flycheck-config.el:68-70= — =checkdoc-arguments= isn't a real variable (invented name + invented format); the intended checkdoc suppression has never worked. Use =flycheck-emacs-lisp-checkdoc-variables= or drop. -- [BUG] =prog-json.el:87-90= — C-c C-q → jq-interactively binding defers to eval-after-load of jq-mode, which nothing loads — dead key. Bind in =cj/json-setup= via local-set-key (jq-interactively IS autoloaded). -- [BUG] =prog-python.el:129-132= — lsp-pyright's :hook lambda calls =lsp-deferred= unguarded on the same hook as the guarded =cj/python-setup= — pyright-absent machines still get the LSP attach prompt the guard exists to prevent. Move the require into the guarded branch; delete the hook. -- [BUG] =prog-lisp.el:122-125= — =:after (flycheck package-lint)= waits for a manual M-x to load package-lint, so =flycheck-package-setup= effectively never runs. Hook on flycheck load + require inside. -- [UX] =prog-python.el:111-115=, =prog-go.el:111-114=, =prog-webdev.el:128-147= — setup hooks attach to ts-modes only (C/shell hook both variants); grammar-unavailable fallback to classic modes silently loses indent/keys/formatter/LSP. Add classic-mode hooks. -- [UX] =prog-webdev.el:165-173= — web-mode gets the format key but none of the promised setup (no company/flyspell/LSP in HTML buffers). Add to the setup hook or fix the Commentary. -- [ENHANCE] gopls, clangd, bash-language-server, shfmt, shellcheck lack the =cj/executable-find-or-warn= load-time warnings pyright/prettier have; prog-shell's =:if (executable-find ...)= evaluates once at startup and silently disables shfmt/flycheck setup forever. -- [REMOVE] =prog-training.el:36-37= — =(url-debug t)= turns on GLOBAL url.el debug logging once leetcode loads. Debugging leftover; delete. -- [REMOVE] =prog-webdev.el:85=, =prog-json.el:44=, =prog-yaml.el:39= — three byte-identical format-region helpers. Extract one shared tested helper (system-lib). +Treat snapshot updates as an explicit command, not an automatic side effect. -*** TODO Findings: dev tooling group -From agents 2026-06-12; spot-verified sample. Beyond the standalone F7 task: -- [BUG] =vc-config.el:138-144= — =cj/goto-git-gutter-diff-hunks= (C-; v d) never did what it claims: consult-line over "^[+\\-]" matches source text, not gutter hunks. Build candidates from =git-gutter:diffinfos= or drop the binding (C-; v n/p covers it). -- [BUG] =dev-fkeys.el:116-122= — F4 compile+run one-shot hook installs on GLOBAL =compilation-finish-functions= before the prompt; C-g leaves it armed and the next unrelated compile triggers projectile-run-project. Use the buffer-local pattern the module already uses for cache-revert (same in =--f4-clean-rebuild-impl=:143). -- [BUG] =test-runner.el:84,222= — documented ~/.emacs.d/tests fallback doesn't exist (=cj/test-global-directory= defvar'd nil, never set); outside a project =(file-directory-p nil)= crashes in three commands. Initialize the defvar or guard with user-error. (Adds specifics to the open "Fix up test runner" task — fold.) -- [BUG] =test-runner.el:288= — focus-add prefix check lacks the trailing slash so =tests-scratch/= passes the "inside tests/" check; the correct helper =cj/test--file-in-directory-p= exists at :168 — use it. -- [BUG] =vc-config.el:217-219= — difftastic blame map binds D and S to the same command (show); D should be diff per the transient four lines down. -- [UX] =diff-config.el:37= — =ediff-diff-options "-w"= ignores ALL whitespace in every ediff session — indentation-only Python changes compare as identical. Drop the default; toggle per-session. -- [UX] =restclient-config.el:64-65= — raw global-set-key "C-; R n" hides a load-order dependency (header claims "Runtime requires: none"); use defvar-keymap + =cj/register-prefix-map= like siblings (same class as org-reveal, slack). -- [UX] =vc-config.el:196= — clipboard clone via synchronous =call-process= freezes every emacsclient frame for the whole clone. make-process + sentinel. -- [REMOVE] =vc-config.el:80-82= — phantom autoload =git-timemachine-show-selected-revision= (no such function in the package) appears in M-x and errors. Drop from :commands. -- [REMOVE] =httpd-config.el:19-30= — pointless =:defer 1= (impatient-mode loads simple-httpd on demand) + unprefixed eager globals =wwwdir=/=check-or-create-wwwdir= creating www/ on every startup. =:defer t=, prefix, or fold into markdown-config. -- [COVERAGE] — intersect/parse unit tests hand-build matching keys (the F7 bug's escape route); =--coverage-elisp-run='s compilation-finish wiring, goto-git-gutter-diff-hunks, timemachine candidate round-trip untested. F-key sweep clean: no collisions; F5 free for the debug-backend task. +**** Go Ideas +- Detect =go.mod=. +- Current file/source: run package =go test ./pkg=. +- Test at point: nearest =func TestXxx= and run =go test ./pkg -run '^TestXxx$'=. +- Bench at point: nearest =BenchmarkXxx= and run =go test -bench '^BenchmarkXxx$'=. +- Add toggles for =-race=, =-cover=, =-count=1=, =-v=. +- Parse =file.go:line:= output and package failure summaries. -*** TODO Findings: shell/term/files group -From agents 2026-06-12; spot-verified sample (eshell nested list confirmed). Beyond the standalone tasks: -- [BUG] =dirvish-config.el:37= — =cj/xdg-open= attributed to system-utils in the require-comment but defined in external-open.el; neither dirvish-config nor dwim-shell-config (caller at :876) requires it — "Direct test load: yes" headers are false. Require external-open (or move the fn into external-open-lib) + fix comment. -- [UX] =tramp-config.el:73= — =revert-without-query '(".*")= kills revert confirmation for EVERY file in Emacs, buried in the TRAMP module. Scope to =tramp-file-name-regexp= or move deliberately to an editing module. -- [UX] =dirvish-config.el:403= — quick-access entries lx (~/archive/lectures), phl (~/projects/homelab), pn (~/projects/nextjob) point at directories that don't exist on this machine. Prune or create. -- [REMOVE] =dwim-shell-config.el:474,507= — open-externally (raw xdg-open) and open-file-manager (thunar/nautilus probe chain) duplicate cj/xdg-open (dirvish o) and cj/dirvish-open-file-manager-here (f); ascii-art references jp2a, the module's only absent binary. Delete the two duplicates; install jp2a or drop ascii-art. -- [REMOVE] =tramp-config.el:115= — custom =sshfast= method referenced nowhere (everything uses sshx); =tramp-own-remote-path= added twice (:39,:128); =dirtrack-list= and =magit-git-executable "/usr/bin/git"= are unrelated globals hiding here. Prune/relocate. -- [COVERAGE] — eshell visual-commands/xterm-color wiring and the dirvish mark-all loop had no load-and-assert tests (both standalone bugs above); TRAMP perf settings look sound for the DUET latency concern (attr caching, no remote VC, direct-async + controlmaster). +**** Rust Ideas +- Detect =Cargo.toml=. +- Use =cargo test= by default, optionally =cargo nextest run= when available. +- Current test at point: nearest =#[test]= function. +- Current file/module where possible. +- Integration test file: =cargo test --test name=. +- Support =-- --nocapture= toggle. +- Parse compiler/test failures and =file:line= links. -*** TODO Findings: AI group -From agents 2026-06-12; spot-verified sample (string-model setq confirmed). Beyond the standalone tasks: -- [BUG] =ai-term.el:875= — close derives the tmux session name from =default-directory=, which ghostel retargets via OSC 7; after a cd the kill-session misses (orphaned agent session) or name-collides with a different aiv- session. Derive from the buffer name's immutable basename. -- [UX] =ai-term.el:827= — multi-window F9 toggle-off unconditionally delete-windows, never restoring the displaced edge-window buffer the Commentary (:24) and reuse-edge docstring (:521) promise. Restore when quit-restore still matches, or fix the docs to describe delete-window reality. -- [UX] =ai-conversations-browser.el:191= — browser load stubs =y-or-n-p= to nil, silently discarding an unsaved in-progress conversation (the direct C-; a l path offers to save). Give ai-conversations a file-arg internal instead of puppeting the interactive command via cl-letf; also the =(caar cands)= fallback loads the newest conversation on a filename mismatch — fail loudly. -- [ENHANCE] =ai-quick-ask.el:103= — dismiss mid-stream kills the buffer without =gptel-abort= — request keeps streaming to a dead buffer (wasted tokens). -- [NOTE] =ai-mcp.el= — unreachable from init, consistent with the paused Phase 1.5; add a one-line Commentary note ("not wired until Phase 2") so future audits don't re-flag, and revisit =cj/mcp-enabled-servers= defaulting to all nine servers before wiring. -- [COVERAGE] — load/autosave lifecycle untested (fresh-session load, timer self-cancel, close-buffer session-name derivation). +**** Shell / Generic Ideas +- Adapter for Makefile targets: + - detect =make test=, =make check=, =make coverage= + - expose project-level commands even when language-specific detection fails +- Adapter for arbitrary project command configured in dir-locals or a project + config plist. +- Let users register custom command templates per project: -*** TODO Findings: media/reading group -From agents 2026-06-12; spot-verified sample (M-S- bindings, eww store split confirmed). Beyond the standalone tasks: -- [BUG] =music-config.el:585= — =cj/music-add-dired-selection= gates =dired-get-marked-files= on =(use-region-p)= — but dired marks aren't a region; marked files are ignored, + adds only file-at-point. Drop the conditional (the function already falls back correctly). Note for the EMMS-free rewrite: dirvish + shadows =dired-create-directory= — deliberate decision needed before carrying it over. -- [UX] =media-utils.el:195-204= — =cj/yt-dl-it= watches tsp (which enqueues and exits), so "Finished downloading" fires immediately while yt-dlp may fail later, silently; also affects elfeed d. Message "queued" honestly or watch the real job (tsp -f). -- [UX] =browser-config.el:34-47,171= — first-run fallback picks EWW (first, "always available") over installed real browsers; fresh machines get org links in a text browser until cj/choose-browser runs. Prefer the first external match. -- [REMOVE] =video-audio-recording.el:442-488= — =cj/recording-group-devices-by-hardware= is dead code (nothing calls it) carrying a hardcoded "Jabra SPEAK 510 USB" branch. Delete + its test file. -- [REMOVE] =calibredb-epub-config.el:198-212= — =set-auto-mode= :around advice for .epub is redundant with nov's :mode registration (auto-mode-alist wins before magic-fallback); overhead + failure surface on every file visit. Remove and verify. -- [COVERAGE] — eww interactive commands (switch-search-engine, bookmark-quick-add, copy-url) and =cj/nov-center-images= untested. +#+begin_src elisp +((:name "unit" + :command ("npm" "run" "test:unit" "--" "{file}")) + (:name "integration" + :command ("pytest" "tests/integration" "-q"))) +#+end_src -*** TODO Findings: apps/misc group -From agents 2026-06-12. Beyond the standalone tasks: -- [BUG] =hugo-config.el:49= — =cj/hugo-new-post= void-functions on =org-hugo-slug= in a fresh session (ox-hugo is :after ox, which loads on first export); =cj/hugo-export-post= already requires ox-hugo — do the same here. -- [BUG] =help-utils.el:73= — arch-wiki search signals raw file-missing when the docs dir is absent; the friendly install hint at :81 is unreachable. Guard with =file-directory-p= + user-error up front. -- [UX] =hugo-config.el:244= — eight raw global-set-key C-; h calls + hand-rolled which-key mutate cj/custom-keymap directly, against keybindings.el's own instruction. Convert to defvar-keymap + =cj/register-prefix-map= (same class as org-reveal, restclient, slack). -- [ENHANCE] =games-config.el:25= — =:defer 1= pulls malyon + 2048 into every session for nothing; use =:commands=. Also :config references =org-dir= without requiring user-constants (free-variable warning at byte-compile). -- [REMOVE] =wrap-up.el:29= — =elisp-compile-mode= doesn't exist (real mode emacs-lisp-compilation-mode derives from compilation-mode, already covered at :27); dead line. (The prior unguarded-timer fix is intact.) -- [REMOVE] =help-config.el:99-106= — stray empty :preface + dead commented Info-directory-list block. Delete. -- [NOTE] =duet-config.el= — orphaned BY DESIGN (Commentary documents pre-alpha staging; Stage 1 is the wire-in trigger). Audit record only. -- [COVERAGE] — help-config and help-utils have zero test files; the two broken paths above are exactly the untested branches. +**** UI Ideas +***** Transient Menu +Replace or complement the raw keymap with a =transient= menu: +- scope: current test/file/focused/last failed/project +- runner: auto/ert/pytest/vitest/jest/go/cargo/make +- toggles: watch, coverage, debug, fail-fast, verbose, update snapshots +- actions: run, rerun, edit command, show failures, open report + +***** Result Buffer +Create a normalized =*Test Results*= buffer: +- latest status per project +- command and duration +- pass/fail/skip counts +- failure list with clickable =file:line= +- actions to rerun failed/current/all +- links to coverage artifacts + +***** Modeline / Headerline Signal +Show the last run status for the current project: +- green passed +- red failed +- yellow running +- gray no run + +Keep it quiet and optional. + +***** History +Store recent run requests per project: +- rerun last +- rerun last failed +- choose previous command +- compare duration/status against previous run + +**** Configuration Ideas +- =cj/test-runner-default-scope= +- =cj/test-runner-prefer-isolated-elisp= +- =cj/test-runner-project-overrides= +- =cj/test-runner-known-adapters= +- =cj/test-runner-enable-watch= +- =cj/test-runner-result-retention= +- per-project override through =.dir-locals.el= + +Example: + +#+begin_src elisp +((nil . ((cj/test-runner-project-overrides + . (:adapter pytest + :default-args ("-q") + :coverage-args ("--cov=src")))))) +#+end_src + +**** Safety And Robustness +- Use structured commands until the final boundary. +- Quote only at render time. +- Avoid shell when =make-process= / =process-file= is sufficient. +- Keep command preview/editing available for surprising cases. +- Detect missing executables before running. +- Add timeouts/cancel commands for long-running or hung tests. +- Do not silently fall back from a missing runner to a different runner unless + the fallback is visible in the command preview. +- Avoid mutating global =load-path= permanently. +- Keep remote/TRAMP behavior explicit; do not accidentally run local commands + for remote projects. + +**** Coverage Integration +Tie this into the existing coverage work: +- run coverage for current file/scope +- open latest coverage report +- summarize uncovered lines for current file +- support Elisp SimpleCov/Undercover, pytest-cov, Vitest coverage, Go cover, + and Rust coverage later +- store coverage artifact paths in the normalized run result + +**** AI-Assisted Debugging Ideas +- Summarize failing tests from the parsed failure records and raw output. +- Include command, changed files, failure snippets, and relevant source/test + locations. +- Redact env vars, tokens, Authorization headers, and secrets before sending to + =gptel=. +- Add commands: + - =cj/test-runner-explain-failure= + - =cj/test-runner-suggest-related-tests= + - =cj/test-runner-summarize-coverage-gap= + +**** Migration Plan +***** Phase 1: Internal cleanup +- Fix the task typo and rename current ERT-specific functions or wrap them under + an ERT adapter. +- Move F6 language detection/command construction from =dev-fkeys.el= into + =test-runner.el= or a new =test-runner-core.el=. +- Replace shell-string command builders with structured command plists. +- Fix path containment in =cj/test--do-focus-add-file=. +- Make =cj/test-last-results= real for ERT runs. -*** TODO Findings: holistic — startup & performance -From the 2026-06-12 holistic pass; daemon init measured at 1.11s (healthy). Beyond the standalone [#A] native-comp/GC task: -- [BUG→FOLD] the eager-org chain: =org-config.el:352= org-appear has no defer trigger (only :custom) → requires all of org at init; org-agenda (=:after org :demand t=) cascades; chime's =:demand t= pulls it anyway. org-config is the most expensive require (0.229s of 1.11s). Decide fully-eager vs fully-deferred — and =init.el:146='s "calendar-sync must come after org-agenda" contract exists only as a comment (three uncoordinated writers of =org-agenda-files=). Both facts belong in the filed defer-modules task before that refactor starts. -- [PERF] =dirvish-config.el:385-387= — =:defer 0.5= defeated by :init calling autoloaded =dirvish-override-dired-mode= → dirvish fully loads at init (0.072s, third most expensive; trace-confirmed). Own the eager load or defer the override to a dired-mode-hook shim. -- [PERF] timed =:defer N= loads unused packages into every start: simple-httpd (:1s + startup mkdir despite the defer), malyon, 2048-game, emojify (may hit network), ligature. Convert to :commands/mode hooks. -- [UX] =early-init.el:235-256= — synchronous =package-refresh-contents= on the startup path when any archive cache is >7 days old (MELPA ~6MB) — multi-second network-bound start, fires in batch too. Make async post-startup or push into the localrepo update script (distinct from the filed bootstrap-relocation task). -- [PERF] =early-init.el:228= — no =package-quickstart= with 184 packages; activation walks every package dir each start (~0.3s of early-init). Free win; regenerate after package ops. -- [PERF] =prog-general.el:298= — =yas-reload-all= immediately before =yas-global-mode= scans snippet dirs twice per start (doubled "[yas] Prepared..." message). Delete the line. -- [REMOVE] cross-ref: the all-the-icons stack (already in UI core findings) is 2 of the :demand t packages plus a per-frame install-check hook. +***** Phase 2: ERT adapter +- Implement adapter registry. +- Add ERT adapter with in-process and isolated modes. +- Preserve all current keybindings by routing them through the adapter. +- Add failure/result normalization for ERT. +- Add "rerun last" and "rerun failed" for ERT. -*** TODO Findings: holistic — daemon stability -From the 2026-06-12 holistic pass. Architecture-level verdict good (timers cancelled/guarded, calendar-sync async well-contained, advice mostly named + guarded). Residual: -- [STABILITY] =transcription-config.el:293= — sentinel chain has no unwind-protect; =--append-to-log='s =insert-file-contents= signals if the log is missing → process buffer leaks, entry stuck 'running in the modeline forever, no notification. Extends the filed transcription standalone — fix together. -- [STABILITY] =calendar-sync.el:1646= — hourly timer body: fetch/parse guarded but the timezone check and =--require-calendars= run bare — any signal repeats hourly forever (the exact class fixed in four modules once). Condition-case the body; demote the hourly echo-area message to the silent log. -- [STABILITY] =music-config.el:865= — four anonymous-lambda advice in :config stack per live reload (verified: lambdas don't dedupe) and can't be advice-removed. Name the function. -- [STABILITY] =system-defaults.el:69= — =display-warning= advice appends to comp-warnings-log with no condition-case (unwritable path → every async comp warning signals from inside display-warning) and the log grows unbounded. Guard + cap. -- [STABILITY] =media-utils.el:164= — playback sentinel assumes the process buffer is alive (user killed *player:...* → sentinel error, diagnostics lost); sibling yt-dl sentinel shares the kill-buffer gap. buffer-live-p guards. -- [ENHANCE] =system-commands.el:86= — =#'ignore= sentinel + output to /dev/null makes failing lock/suspend indistinguishable from success — the user walks away from an unlocked machine. Message on nonzero exit. (Compounds the [#A] slock task: the broken lock currently fails through exactly this silent path.) -- [ENHANCE] =ui-config.el:153= — post-command cursor hook unguarded: any future signal self-removes it silently (cursor stops signaling modified/read-only until restart); frame-hook lambda also accumulates per reload. with-demoted-errors + name it. -- (kill-emacs-hook y-or-n-p prompt independently re-found here — already filed in the text/prose child; convergence noted.) +***** Phase 3: Python and JS/TS adapters +- Add pytest adapter. +- Add Vitest/Jest adapter with package-manager/script detection. +- Support current file and test-at-point for both. +- Add parser/navigation for common failures. -*** TODO Findings: holistic — UX consistency -From the 2026-06-12 holistic pass. Verdict: more coherent than most 120-module configs (~85% prefix-helper adoption, M-S translation fully covers its 18 bindings, F-keys collision-free, DEF-arg prompts dominate). Beyond the standalone [#A] fset task: -- [BUG] notification env gate: =transcription-config.el:169-171= gates desktop notifications on =(getenv "DISPLAY")= — an X11 predicate that works only because XWayland exports it. Use =env-gui-p= (host-environment.el provides it). -- [UX] four notification stacks beyond the messenger split (notify script ± fallback, alert.el, raw notifications-notify, echo-only for calendar-sync/recording completions). Proposed: one cj/notify facade (transcription's =cj/--notify= is the right shape) — config-wide companion to the messenger-notify addendum in the unification spec. -- [UX] five more C-; entries bypass the register helpers or lack labels: =browser-config.el:182= (C-; B, no label), =org-babel-config.el:51= (C-; k, no label), =flycheck-config.el:62-64= (:bind into cj/custom-keymap), =pearl-config.el:43= (:bind-keymap C-; L, no label), =dev-fkeys.el:533= (helper but no label). Sweep onto cj/register-prefix-map with labels. -- [UX] user-error vs message inconsistent for "nothing to act on" config-wide (examples: =custom-whitespace.el:190=, =jumper.el:202=, =chrono-tools.el:99= message; =mu4e-attachments.el:112=, =ai-rewrite.el:79= user-error; =test-runner.el:392/394= mixes both 2 lines apart). Convention: user-error when the command can't proceed; message when it ran and found nothing. -- [ENHANCE] M-S translation layer: complete for GUI (18/18) but installs only on env-gui-p paths — terminal frames have no M-uppercase route; and =dwim-shell-config.el:932/934= binds M-S-d (dired) vs raw M-D (dirvish) asymmetrically. Feeds the filed M-S review task with the concrete map. -- [ENHANCE] which-key labels: register-helper's LABEL arg used by exactly 1 of 23 registrants (rest use separate with-eval-after-load blocks); label style drifts ("X menu" vs bare nouns). Adopt LABEL arg + one style. -- [ENHANCE] "?" curated-menu candidates (for the filed convention task): elfeed search/show, dirvish, signel chat/dashboard, music playlist, ai-conversations-browser, mu4e-attachments, transcription status, pearl. calibredb remains the model. -- [UX] ="(Cancel)"= pseudo-candidate in =music-config.el:253-256= vs C-g everywhere else (90+ prompts). Drop it. -- [UX] buffer-naming drifts across three conventions (*AI-Assistant* / *Kill Ring* / *dashboard*); pick Title Case + "*Name: param*", lowercase for process logs. -- [ENHANCE] C-; f formatter shadowing implemented 3 ways (:bind :map vs local-set-key in hooks); unify on :bind. Also =keybindings.el:21= commentary still says "C-c j" for the jump prefix the code binds at C-; j. -- [ENHANCE] initial-input anti-pattern at =dwim-shell-config.el:661,680= and =erc-config.el:176-177= against the config's DEF-arg norm. +***** Phase 4: UI and watch modes +- Add transient menu. +- Add result buffer. +- Add cancellation and rerun history. +- Add watch commands where supported. -*** TODO Findings: holistic — package strategy -From the 2026-06-12 holistic pass (184 elpa dirs). Core stack modern (vertico/consult/embark/orderless, treesit-auto, built-in which-key, current magit/forge/telega/slack). Beyond the standalone gptel/prescient tasks: -- [REMOVE] true orphans, nothing references them: js2-mode, tide, json-mode (pre-treesit JS stack). package-delete + drop from .localrepo. -- [REMOVE] emojify: 2021 snapshot, dormant upstream, crashes in lui (slack disabled it), Emacs 30 renders emoji natively. Drop the use-package + hooks (=font-config.el:253=, =erc-config.el:211=); it stays on disk only as slack's declared dep. -- [BUG] legacy-mode hooks miss the ts modes: =prog-general.el:91-92= hooks =yaml-mode-hook=/=toml-mode-hook= but the config runs yaml-ts/toml-ts — general prog settings silently don't apply in YAML/TOML buffers. Rehook; delete toml-mode + eldoc-toml + yaml-mode packages (superseded by treesit). -- [RISK→FOLD] localrepo priority 200 is absolute, so package-upgrade silently no-ops on everything mirrored — the engine that fossilized emojify@2021/toml-mode@2016/js2@2023. The filed refresh-script task at [#D] deserves [#B] + a quarterly cadence, else every orphan finding regrows. -- [RISK] fork fleet sync-back stories: org-drill flip back to :vc when done (filed dev-checkout finding); auto-dim-other-buffers local checkout with :vc commented — decide its home; org-msg pins =:rev :newest= (unpinned moving target) — pin a known rev. signel/duet/pearl/wttrin/gloss/chime self-owned remotes are fine. -- [UPGRADE] wiki-summary (2018, dead upstream, predates Wikipedia's REST API; sole caller help-utils) — the audit's one write-your-own: ~30-line url-retrieve against the REST summary endpoint. Delete the package, inline the helper. -- [UPGRADE] xterm-color droppable in eshell on Emacs 30's native ansi-color (its only use; also doubly-broken per the eshell standalone task — fixing by deletion is an option). -- [ENHANCE] Python tier: poetry.el (sluggish) + pyvenv (2021) keep only if Poetry projects are still real; blacken fine until ruff-format (reformatter.el already installed). lsp-pyright current. -- [DECIDED] projectile, lsp-mode, dirvish: keep (wired into 10/7/many modules, maintained, migration cost > benefit). On the record so future audits don't relitigate. +***** Phase 5: Coverage and AI +- Connect coverage commands to adapter capabilities. +- Add failure summarization with redaction. +- Add coverage-gap summarization. -*** TODO Findings: spin-off repos (pearl, chime, emacs-wttrin) -Full findings delivered as handoffs to each repo's inbox/ (2026-06-12-0057-from-.emacs.d-handoff-*.org); each repo's next session files them through its own value gate. Highlights: -- pearl (10 findings; suite green, 66 ERT files): auth-source negative-cache trap in pearl-clear-cache (the 2026-06-01 incident class, unfixed); sync wrapper ignores pearl-request-timeout + async has no timeout; mutation errors discard Linear's GraphQL reason; no RATELIMITED handling; dead legacy API layer (~150 lines). -- chime (10 findings; suite green; the 2026-06-11 watchdog handoff VERIFIED landed in full): lookahead vars never injected into the async child (documented feature silently capped at 8 days — one-line fix); days-until-event nil crash on mixed timed/all-day events; stale-callback race after watchdog interrupt (generation counter needed); default test run prints green integration banner over "Ran 0 tests". -- emacs-wttrin (10 findings; ~56 ERT files, CI; the face-flood reminder VERIFIED resolved — test 8f3c770 + fix c5e5e1d, reminder cleared from notes.org): no network timeouts (wttr.in stalls hang the loading buffer); error-path response-buffer leak; non-favorite cache never expires; 17 unreleased commits incl. two features — tag v0.4.0. +**** Acceptance Criteria For First Fix-Up Pass +- Existing ERT workflow still works. +- F6 and =C-; t= use the same underlying runner API. +- Current-file test command generation is covered for Elisp, Python, Go, + TypeScript, and JavaScript. +- At least one isolated ERT command path exists. +- Path containment checks are robust against sibling-prefix paths and symlinks. +- Runner requests and results are represented as data, not only messages. +- Missing runner/tool errors are clear and actionable. +- Tests cover adapter detection, command building, scope resolution, result + storage, and key interactive paths. -** PROJECT [#C] Build cj/dev-setup-project helper (per docs/specs/dev-setup-project-spec.org) :feature: +** DONE [#B] jumper: register collisions and dead-marker errors :bug:solo: +CLOSED: [2026-06-22 Mon] :PROPERTIES: -:LAST_REVIEWED: 2026-06-01 +:LAST_REVIEWED: 2026-06-13 :END: -*** 2026-05-15 Fri @ 19:17:37 -0500 Specification +Fixed 2026-06-22: (1) store now allocates the first unused register char in the live slice (=jumper--first-free-register=) instead of by next-index, and removal clears the freed register, so a store after a removal no longer overwrites a surviving slot's marker; (2) =jumper--with-marker-at= guards =(buffer-live-p (marker-buffer marker))= so killed-buffer entries are skipped instead of signaling wrong-type errors; (3) the single-location toggle jumps back to the last-location register when set (returns =jumped-back=). New =test-jumper--register-hygiene.el= (8 tests); all 42 jumper tests green. Pre-existing unused-lexical =i= warning in =jumper--location-exists-p= left alone (separate nit). +Two related defects from the 2026-06 config audit: +- =modules/jumper.el:155= — removal shifts the vector without renumbering registers, so a later store allocates a register still held by a surviving location and silently overwrites it. Allocate the first free register char in the live slice; =set-register nil= on removal so freed markers don't pin buffers. +- =modules/jumper.el:117,132= — guards check =(markerp marker)= but not =(buffer-live-p (marker-buffer marker))=; after killing a buffer holding a location, M-SPC SPC and M-SPC j signal wrong-type errors. Treat dead entries as skippable/removable. +Also =jumper.el:178= — the promised single-location toggle never toggles back ('already-there branch should =jump-to-register= z when set). -Interactive command that opens a review buffer with proposed per-subdirectory .dir-locals.el contents (projectile compile/run/test + cj/coverage-backend), optional starter Makefile when none exists, and gitignore updates. User edits inline, C-c C-c writes all files. +** TODO [#B] Keymap consolidation — resolve decisions, run Phase 1-2 :feature:refactor:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-13 +:END: +Spec: [[id:540bf06b-16b8-46c6-b459-c40d1b9c795d][keybinding-console-safety-spec-doing.org]]. Phase 0 (revert 4a1ecf64) is done and pushed. Decisions D1-D5 are open TODOs in the spec; D2/D4/D5 gate the primary work (Phase 1 prune via Appendix D, Phase 2 consolidate + retire the translation block), while D1/D3 (the console-safe prefix) gate only the optional Phase 3 and can stay open indefinitely. Resolve D2/D4/D5, then run Phase 1-2. Appendix D is the keybinding pruning checklist. Add a =#+TODO: TODO | DONE SUPERSEDED CANCELLED= header line to the spec if adopting those decision keywords (rulesets convention update, 2026-06-12). -Design: [[id:596fce5d-1bab-46e7-8567-d4a2e0923091][docs/specs/dev-setup-project-spec.org]] +** TODO [#B] ledger-config is orphaned — ledger-mode never configured :bug:quick: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +Nothing requires =modules/ledger-config.el= (verified by grep), so .dat/.ledger/.journal open without ledger-mode, reports, or flycheck-ledger. The module looks finished, not staged (unlike duet-config, which documents its pre-alpha orphaning). Decide: wire into init.el (+ =cj/executable-find-or-warn= for the ledger binary) or delete. From the 2026-06 config audit. -Scope of v1: -- modules/dev-setup-config.el (command + review-buffer major mode) -- Three-tier detection: existing Makefile, existing package.json/pyproject.toml scripts, fall-back starter Makefile generation. -- Project shapes supported: pure Elisp, pure Go, pure Python, pure Node/TS, Docker Compose polyglot. -- Re-run semantics: status banners (UNCHANGED / WILL UPDATE / WILL CREATE), idempotent gitignore append, never modifies an existing Makefile. -- ERT tests for the pure helpers (Makefile parser, package.json parser, shape detection, target-to-role mapping, review-buffer parser). +** TODO [#C] buffer-differs save prompt: 4-way yes/no/diff/cancel :feature:next: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +The "buffer differs from file" confirmation currently gives only yes/no. Craig wants a 4-way choice with explicit consequences: yes (be explicit it overwrites), no (be explicit it discards this action and continues), diff (show a graphical difftastic diff, then return to this prompt), cancel (stop the action, leave the buffer untouched). Needs the exact prompt identified first (which save/overwrite path raises "buffer differs") and a design for the diff-then-return loop. difftastic + cj/diff-buffer-with-file infrastructure already exist. From the roam inbox 2026-06-16. +** TODO [#C] emacs: tag tasks by module name for sorting :refactor:studio: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +Replace topic tagging with single-word module tags: :studio: for everything under scripts/theme-studio/, module-named tags elsewhere, :multi: for cross-area work. Drop bug/enhancement-style tags since work should be chosen on other bases. This changes the current six-tag convention, so update the priority-scheme section to document it, rewrite the task-audit workflow to reconcile tasks against the module scheme, then run the audit. Queue for end of session. From the roam inbox. +** TODO [#C] Build debug-profiling.el module :feature:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: -Deferred: -- Rust (Cargo.toml), Java (pom.xml), other language shapes. -- Project-wide override config file. -- Auto-detecting external run scripts in conventional locations. +Reusable profiling infrastructure for targeted slow-command investigation. Consolidates scattered profiler bindings (currently in =modules/config-utilities.el=) and adds two pure-helper-backed entry points: "profile next command" and "time region or sexp." Designed via =/brainstorm= 2026-04-26. -Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable. +Design: [[id:c713b431-ae14-498d-aba9-b84d52f981b6][docs/specs/debug-profiling-spec.org]] -*** TODO [#B] Pure detection + parsing helpers :feature: -Implement the four pure helpers the rest of the command composes on: -- =cj/--dev-setup-parse-makefile-targets FILE= (.PHONY + bare target lines, skip pattern rules) -- =cj/--dev-setup-parse-package-json-scripts FILE= (scripts block, JSON) -- =cj/--dev-setup-detect-project-shape ROOT= (Elisp / Go / Python / Node-TS / Docker-Compose polyglot / unknown) -- =cj/--dev-setup-map-targets-to-roles TARGETS= (best-guess compile/run/test mapping per design § Detection) +Implement via =/start-work= against the design — branch =feat/debug-profiling=, commits decomposed along the test-first split-for-testability boundary. Once shipped, use it as the v1 exercise on the queued [#B] org-capture target-building investigation. -Files: =modules/dev-setup-config.el= (new). No interactive surface, no I/O -beyond reading the named file. +** TODO [#C] Evaluate jamescherti essential-emacs-packages list :quick:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +Review [[https://www.jamescherti.com/essential-emacs-packages/][James Cherti's essential Emacs packages]] for anything worth installing. Cross-check each candidate against what is already in the config (=modules/= + =init.el=), skip the ones already present, and shortlist the genuinely new ones with a one-line rationale. Future-installation research, not a commitment to install. -Acceptance: each helper callable in isolation with handcrafted fixtures; -no command yet. +** TODO [#C] Extend F2 "preview" convention across modes :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: -Depends on: none -- start here. +F2 is the universal preview key. Currently bound only in markdown-mode (markdown-preview, in =modules/markdown-config.el=). Org-reveal lives on =C-; o R= via =cj/org-map=, not F2. Extend F2 to other modes where a "preview" action is natural: -*** TODO [#B] ERT coverage for the pure helpers :feature:test: -Normal/Boundary/Error tests for every helper from the prior sub-task, -matching the design's testing section. +- Hugo blog (hugo-config.el) — preview the post in browser +- HTML / web-mode — open in browser +- Reveal presentations - preview in browser +- Any other mode with a natural "preview this" action -Files: =tests/test-dev-setup-config.el=, plus -=tests/testutil-dev-setup-config.el= for the temp-project fixture builder -(writes Makefile / package.json / compose stub into =make-temp-file ... 'dir=). +Keep the binding mode-local so F2 stays available as a global candidate where no preview makes sense. -Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green; -every helper has at least one Normal, one Boundary, one Error case. +** TODO [#C] face-diagnostic: face-name buttons + header allowlist :feature:quick:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +Two v1 follow-ups on the shipped face/font diagnostic: render the face names in the report as buttons that call describe-face (the spec's "For the user" buttons; v1 shows them as plain text), and add face-diagnostic to the module-header allowlist in tests/test-init-module-headers.el now that it's required in init.el. Spec: [[id:98f065cf-8bd5-46a0-ac24-da94d66855ad][face-font-diagnostic-popup-spec-implemented.org]]. +** TODO [#C] Gold text in auto-dimmed buffers :bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +Some auto-dimmed document buffers render text in gold; source unknown. Likely a face-remapping or overlay interaction with the theme. Blocked on the face/font diagnostic tool above for diagnosis. From the roam inbox. +** TODO [#C] Google Contacts ↔ org-contacts sync investigation :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +From the 2026-06-11 brainstorm. Goal: keep [[file:~/sync/org/contacts.org][contacts.org]] (real org-contacts: PROPERTIES drawers, mu4e completion, org-roam links) in sync with Google Contacts. Google side is solid — official People API (OAuth2, incremental syncToken) or CardDAV; no ToS risk. The hard parts are local: (1) identity — entries have no UID, so two-way needs a GOOGLE_ID property per entry plus a one-time fuzzy reconciliation of the two populated datasets (name/email/phone matching); (2) field mapping — space-separated multi-email in one property, free-text body notes, inconsistent phone formats (normalization decision); (3) conflict policy. First decision gates the rest: one-way Google→org read model (simple) vs true two-way. Candidate architectures: vdirsyncer (proven two-way engine w/ Google support; build only the vCard↔org translation, evaluate org-vcard fidelity) vs a direct People API script with sync state in org properties. Output: recommendation doc in docs/design/ naming direction + the normalization/conflict decisions for Craig. Not :solo: — the one-way-vs-two-way call and normalization policy are Craig's. -Depends on: pure detection + parsing helpers. +** TODO [#C] Google Voice in Emacs — SMS + dialer investigation :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +From the 2026-06-11 messenger-unification brainstorm. Google Voice has no official API; the viable routes ride the Matrix bridge ecosystem's reverse engineering (mautrix-gvoice). Research pass to establish the 2026 state of play: (1) is mautrix-gvoice healthy and what does its auth flow look like now; (2) any better-maintained alternative (CLI/daemon) for the signel-pattern architecture (external daemon + JSON-RPC + thin Emacs chat client); (3) does call initiation (ring-linked-phone-then-connect, Emacs as dialer) survive in the current protocol — two-way audio in Emacs is out of scope (WebRTC); (4) ToS/account-flag risk assessment for Craig's account. Output: a recommendation doc in docs/design/ naming the architecture (signel-pattern daemon vs Matrix bridge + ement.el) or a no-go with reasons. If go, GV becomes a registered backend under the messenger-unification convention (see the [#B] task below). -*** TODO [#B] Starter-Makefile + .dir-locals.el proposal generator :feature: -Pure function =cj/--dev-setup-build-proposal SHAPE ROOT= returning a -structured plist of proposed blocks: one per subproject =.dir-locals.el= -(projectile compile/run/test + =cj/coverage-backend=), the optional starter -Makefile (only when none exists, adapted per shape per design § Tier 3), -and the gitignore append lines. +** TODO [#C] latexmk workflow never activates (two breaks) :bug:quick:solo: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: +=modules/latex-config.el:66= — =:hook (TeX-mode-hook . ...)= gets use-package's =-hook= suffix appended (unbound symbol not ending in =-mode=), registering on nonexistent =TeX-mode-hook-hook=, so =TeX-command-default "latexmk"= is never set. Independently =:80= auctex-latexmk is =:defer t= with no trigger, so =auctex-latexmk-setup= never runs and "latexmk" isn't in TeX-command-list. Fix hook name to =TeX-mode=; change auctex-latexmk to =:after tex=. From the 2026-06 config audit. -Files: =modules/dev-setup-config.el=. +** TODO [#C] Org-noter custom workflow — fix and finish :feature:bug: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: -Acceptance: given a shape plist, returns deterministic block list ready for -the review buffer; ERT cases cover each shape (Elisp / Go / Python / Node-TS -/ polyglot) plus the Tier-1 "Makefile already exists, suppress Makefile -block" branch. +Continue debugging and testing the custom org-noter workflow from 2025-11-21 session. +This is partially implemented but has known issues that need fixing before it's usable. -Depends on: pure detection + parsing helpers. +*Last worked on:* 2025-11-21 +*Current status:* Implementation complete but has bugs, needs testing -*** TODO [#B] Review-buffer major mode + parser :feature: -Define =cj/dev-setup-review-mode= (derived from =emacs-lisp-mode=) with =C-c -C-c= / =C-c C-k= bindings, plus the pure parser -=cj/--dev-setup-review-buffer-parse CONTENTS= that turns buffer text back -into a block list. Banner syntax per design § Review Buffer (=;; ==== <path> -====[ <status>]==, gitignore special, Makefile special). +*Known issues to fix:* -Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el= -(parser cases: well-formed multi-block, single block, empty body, missing -banner, malformed elisp inside a dir-locals block). +1. /Double notes buffer appearing when pressing 'i' to insert note/ + - When user presses 'i' in document to insert a note, two notes buffers appear + - Expected: single notes buffer appears + - Need to debug why the insert-note function is creating duplicate buffers -Acceptance: round-trip -- render proposal -> parse buffer -> equal block -list. Mode keybindings smoke-tested. +2. /Toggle behavior refinement needed/ + - The toggle between document and notes needs refinement + - May have edge cases with window management + - Need to test various scenarios -Depends on: starter-Makefile + .dir-locals.el proposal generator. +*Testing needed:* -*** TODO [#B] Writer + status diff + projectile cache reset :feature: -Implement the =C-c C-c= writer: diff each parsed block against the on-disk -file to assign =UNCHANGED= / =WILL UPDATE= / =WILL CREATE=, write only the -non-UNCHANGED ones, append gitignore idempotently, never touch an existing -Makefile, honor the =;;; cj/dev-setup-project: ignore= escape hatch, clear -projectile's per-project command cache, print the summary line. +1. /EPUB files/ - Test with EPUB documents (primary use case) +2. /Reopening existing notes/ - Verify it works when notes file already exists +3. /Starting from notes file/ - Test opening document from an existing notes file +4. /PDF files/ - Verify compatibility with PDF workflow +5. /Edge cases:/ + - Multiple windows open + - Splitting behavior + - Window focus after operations -Files: =modules/dev-setup-config.el=, plus ERT cases for the diff + -idempotent-append logic against temp dirs. +*Implementation files:* +- =modules/org-noter-config.el= - Custom workflow implementation +- Contains custom functions for document/notes toggling and insertion -Acceptance: re-run on an unchanged project writes nothing; renaming a -Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay -untouched. +*Context:* +This custom workflow is designed to make org-noter more ergonomic for Craig's reading/annotation +workflow. It simplifies the toggle between document and notes, and streamlines note insertion. +The core functionality is implemented but needs debugging before it's production-ready. -Depends on: review-buffer major mode + parser. +**Next Steps:** +1. Debug the double buffer issue when pressing 'i' +2. Test all scenarios listed above +3. Refine toggle behavior based on testing +4. Document the final keybindings and workflow -*** TODO [#B] Interactive command + smoke test :feature:test: -Thin =cj/dev-setup-project= interactive wrapper: resolve project root via -projectile, run detection, build proposal, render the review buffer, pop to -it. One smoke test against a prepared temp project asserting the expected -files exist after a simulated =C-c C-c=. +** TODO [#C] Pick and wire a debug backend for F5 :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: -Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=. Add -=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator). +#+begin_src emacs-lisp + Give me an idea of the amount of work and complexity and what allows for a consistent UX across languages. +#+end_src -Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review -buffer; =C-c C-c= writes the expected files. +*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals +Bind F5 globally to a debug entry point. Backend choice is the hard part: -Depends on: writer + status diff + projectile cache reset. +- dape (Debug Adapter Protocol for Emacs) — modern, multi-language via DAP. Single UX across Python, Go, TS, Rust, etc. Less mature than DAP clients in other editors. +- realgud — wraps multiple debuggers (pdb, gdb, node --inspect, etc.). More mature; UX varies by backend. +- Language-specific stacks — dap-mode (python-mode + dap), delve for go, ts-node --inspect, etc. Best per-language UX; most config work. -*** TODO [#B] Resolve open questions + design follow-ups -Three design questions to close before / during implementation: (a) include -=make coverage= target in starter Makefile? (b) project-wide override file -=.cj-dev-setup.el=? (c) Cargo/pom detection. +F5 itself will be simple (start/resume debug). Likely modifier variants once the backend is picked: +- C-F5 toggle breakpoint at point +- M-F5 eval expression in debug context (or step-over shortcut) -Body: park decisions inline in the design doc or run =arch-decide= if they -turn out load-bearing. +Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip. -Depends on: none, but easiest after the writer sub-task surfaces real -friction. +Do this after the F-key rework ticket ships so F5 is the only hole left. -** PROJECT [#C] Localrepo Documentation :feature: +** TODO [#C] Review and rebind M-S- keybindings :refactor: :PROPERTIES: -:LAST_REVIEWED: 2026-06-05 +:LAST_REVIEWED: 2026-06-21 :END: -Audit on 2026-05-27 found the localrepo build half is shipped (=.localrepo/= holds 185 entries; =early-init.el= L135–165 wires the priority-200 pin above the local ELPA-mirror tier at 120–125 and the online fallback). The remaining "document limitations" half splits into one docs-set plus four gap-fix follow-ups that the docs cross-reference. - -Docs land in three artifacts. =docs/design/localrepo.org= carries the full architecture (tier model, install path, refresh story, all four limitations with pointers to the follow-up tasks). =.localrepo/README.org= sits next to the artifact as the user-facing entry — a short summary that survives even if =early-init.el= moves. =early-init.el= grows a commentary header that points at the README, not at the design doc — the README is what future-Craig hits first. +Changed from M-uppercase to M-S-lowercase for terminal compatibility. +These may override useful defaults - review and pick better bindings: +- M-S-b calibredb (was overriding backward-word) +- M-S-c time-zones (was overriding capitalize-word) +- M-S-d dwim-shell-menu (was overriding kill-word) +- M-S-e eww (was overriding forward-sentence) +- M-S-f fontaine (was overriding forward-word) +- M-S-h split-below +- M-S-i edit-indirect +- M-S-k show-kill-ring (was overriding kill-sentence) +- M-S-l switch-themes (was overriding downcase-word) +- M-S-m kill-all-buffers +- M-S-o kill-other-window +- M-S-r elfeed +- M-S-s window-swap +- M-S-t toggle-split (was overriding transpose-words) +- M-S-u winner-undo (was overriding upcase-word) +- M-S-v split-right (was overriding scroll-down) +- M-S-w wttrin (was overriding kill-ring-save) +- M-S-y yank-media (was overriding yank-pop) +- M-S-z undo-kill-buffer (was overriding zap-to-char) -The four limitations the docs cover (each spun out below as its own task): -- Treesitter grammars (downloaded by =treesit-auto= on first use; not in the localrepo) -- Native-comp =.eln= cache (Emacs-version-specific; invalidated by version bumps) -- System-tool deps (=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, etc.; flagged at load by =cj/executable-find-or-warn=, not packageable via =package.el=) -- Refresh / update story (no dedicated script today; ad-hoc =cp= from the elpa mirrors) -*** TODO [#C] Design doc — docs/design/localrepo.org -Write the design doc: tier model, priorities, install path, refresh story, all four limitations with cross-links to the follow-up tasks below. -*** TODO [#C] README — .localrepo/README.org -Write the README at the artifact: short prose entry point summarizing the tier model, pointing at =docs/design/localrepo.org= for full detail. This is what =early-init.el='s commentary header links to. -*** TODO [#C] Commentary header in early-init.el -Add a Commentary-section header in =early-init.el= pointing at =.localrepo/README.org= for usage and =docs/design/localrepo.org= for architecture. Sits at the top of the localrepo block (around L130). -** PROJECT [#C] Migrate from Company to Corfu (with prescient integration) :feature: +** TODO [#C] Slack message buffers in a reused popup window :quick: :PROPERTIES: -:LAST_REVIEWED: 2026-06-02 +:LAST_REVIEWED: 2026-06-21 :END: +Display slack.el message and thread buffers in a dedicated popup window (side or bottom) and reuse that one window instead of spawning a new window per buffer. Likely a =display-buffer-alist= rule (or popper integration) in =modules/slack-config.el=. -Spec: [[id:68733ba2-37a7-4a7b-bfaa-b845d82ff1e7][docs/specs/company-to-corfu-migration-spec.org]] - -*** TODO [#C] Install corfu-side packages -Add corfu, cape, kind-icon, corfu-prescient to the package list. corfu-popupinfo ships inside corfu. Spec step 1. - -*** TODO [#C] Rewrite selection-framework.el company block as corfu/cape stack -Replace the three company-* use-package blocks (lines 192-226) and company-prescient (240-243) with corfu / cape / corfu-popupinfo / kind-icon / corfu-prescient. Rename the section header Company → Corfu in the same change. Spec steps 2 + 8. +** CANCELLED [#C] the preview splits an already split window into 3 temporarily. :bug: +CLOSED: [2026-06-21 Sun] +looks strange. potentially problematic for ai-terms. -*** TODO [#C] Swap mail-compose completion disable to corfu -Rewrite cj/disable-company-in-mu4e-compose to (corfu-mode -1) across mu4e-compose, org-msg-edit, and message modes (mail-config.el:319-333). Spec step 3. +** CANCELLED [#C] TRAMP/dirvish "?" for remote dates — verify the fix per host :bug: +CLOSED: [2026-06-21 Sun] +:PROPERTIES: +:LAST_REVIEWED: 2026-06-02 +:END: -*** TODO [#C] Drop company-ledger for ledger's built-in capf -ledger-config.el: remove company-ledger; verify ledger-complete-at-point registers on completion-at-point-functions, add a ledger-mode-hook capf push only if it doesn't. Spec step 4. +Root cause is traced (see the dated investigation entry below). What's left needs a live remote: open each remote host in dirvish and run the three diagnostic evals to find which gate is closed, then close it. -*** TODO [#C] Drop company-auctex for AUCTeX capf + cape-tex -latex-config.el: remove company-auctex and (company-auctex-init); add cape-tex on TeX-mode-hook. Spec step 5. +Diagnostics (run with point in a remote dirvish buffer): +- =M-: (dirvish-prop :remote-async)= — nil means =tramp-direct-async-process-p= is failing for this method/host, so dirvish's remote attribute fetch never runs. +- =M-: (dirvish-prop :gnuls)= — nil means the remote has no GNU =ls= (the =ls --version= probe failed), so the parser gate stays shut. Likely on truenas (FreeBSD). +- =M-: (tramp-direct-async-process-p)= — confirms whether direct-async is actually active for the connection. -*** TODO [#C] Rewire eshell completion to pcomplete capf -eshell-config.el:163-171: drop company-shell and the company-mode activation; add cape-capf-buster around pcomplete-completions-at-point + corfu-mode. Spec step 6. +Likely fixes, by which gate is closed: +- =:gnuls= nil → install GNU coreutils on the remote (FreeBSD: =pkg install coreutils=) and make =ls= resolve to GNU on the TRAMP path, or accept "?" on that host. -*** TODO [#C] Remove company-mode calls from prog-go/python/webdev -Delete (declare-function company-mode ...) and (company-mode) from the three mode hooks; global-corfu-mode covers them. Spec step 7. + - Constraint: nothing gets installed on the remote host, so the =:gnuls= gate is resolved by accepting "?" on that host rather than installing coreutils. +- =:remote-async= nil → the scp/sshx method isn't advertising direct-async; switch to a method that supports it or check =tramp-direct-async-process= is taking effect for that protocol. -*** TODO [#C] Uninstall company packages + recompile -After the rewrite is green: package-delete company, -quickhelp, -box, -prescient, -ledger, -auctex, -shell; make clean && make compile. Spec step 9. +Files involved: =modules/tramp-config.el=, =modules/dirvish-config.el=. -*** TODO [#C] Tests: corfu activation, mail-disable, capf registration -New tests/test-selection-framework-corfu.el and tests/test-mail-config-corfu-disable.el; update ledger/latex tests to assert their capf registers. Spec Testing section. +*** 2026-05-22 Fri @ 20:24:44 -0500 Traced the root cause through dirvish source +Remote dates/sizes don't come from the dired =ls= listing or =dired-listing-switches=. They come from =dirvish-data-for-dir= (=dirvish-tramp.el:95=), which runs =ls -1lahi= on the remote and parses the columns into the attribute cache. That method only fires when both =(dirvish-prop :remote-async)= is a number and =(dirvish-prop :gnuls)= is a string. When either gate is shut, dirvish falls back to its default, which deliberately skips =(file-attributes f-name)= for remote files (=dirvish.el:904=, a perf guard) — leaving attrs nil, so the file-size and file-time widgets render "?" (=dirvish-widgets.el:216,247=). -*** 2026-05-16 Sat @ 11:07:24 -0500 Goals -Drop-in replacement for the in-buffer completion stack: =company= → -=corfu=, =company-quickhelp= → =corfu-popupinfo=, =company-box= → -=kind-icon=, =company-prescient= → =corfu-prescient=, plus =cape= for -the file/keyword/dabbrev capfs that =company-files= / =company-keywords= -used to handle. Per-module fixups for ledger, AUCTeX, eshell, mu4e -compose, and the three =prog-*= modules. See the design doc for the -full translation table, migration steps, tests, and risks. +That explains why every prior fix missed: dired-listing-switches feed a different code path entirely, and disabling =tramp-direct-async-process= shuts the =:remote-async= gate, which is the one path that populates remote attributes — exactly backwards. The config already enables direct-async for ssh/sshx (=tramp-config.el:79-88=), so the remaining closed gate is per-host: =:gnuls= (no GNU ls on FreeBSD-based truenas) or direct-async not taking effect for the method. Could not verify on a live remote from the work session — handed the per-host diagnostics up into the task body. -** PROJECT [#C] Terminal GPG pinentry Completion :feature: +** TODO [#D] Dashboard over-scroll: pin last line to window bottom :bug: :PROPERTIES: -:LAST_REVIEWED: 2026-06-05 +:LAST_REVIEWED: 2026-05-22 :END: +Triggered by: 2026-05-20 Dashboard buffer too long follow-up. -Audit on 2026-05-27 found no trace of the =terminal-pinentry= branch on this machine: no local or remote ref, no reflog entry across 732 entries reaching back through January, no stash, no dangling commit, no sibling worktree. The 2026-01-24 session log says the branch was created that day, but the work either lived on another machine or was deleted before reaching here. The original task above (=Finish terminal GPG pinentry configuration=) is superseded by this one. +After the opens-at-top fix (=4ac1b81=), the dashboard can still be +scrolled past its content: the banner image makes the buffer just over +one screenful, so the wheel / =C-v= / =M->= pull the last line up and +leave empty space below it. Craig wants scrolling to stop once the +trailing line reaches the window bottom (no void) while still allowing +scroll-down to reach content below the window. -Surviving footprint on this machine: one commented line at =modules/auth-config.el:83= (=;; (setq epa-pinentry-mode 'loopback)=). The hook point =env-terminal-p= exists in =modules/host-environment.el:97=. Everything else (terminal-vs-GUI branching in the epa =:config=, external pinentry wiring for GUI, =GPG_TTY= export, tests) is to be written fresh off main. +Findings from the 2026-05-20 investigation: +- =pixel-scroll-precision-mode= is off, so this is standard line-based + scroll overshoot (the tall banner image inflates the rendered height). +- A =window-start= clamp does not work: =window-start= only lands on + line boundaries, so it can't express a position partway into the + banner image — it either blocks all scrolling or leaves the void. +- A =recenter -1= pin on =post-command-hook= does not work: it fires on + every command, so it fights item navigation (the cursor can't reach + the projects / bookmarks / recents). +- Right design: clamp only on actual scroll commands — advise + =mwheel-scroll= / =scroll-up-command= / =scroll-down-command= / + =end-of-buffer= to =recenter -1= when over-scrolled, never on + navigation commands. +- Live experiment scratch file: =~/dashboard-overscroll-experiment.el=. -Goal: in terminal Emacs, GPG passphrase prompts land in the minibuffer via loopback mode; in GUI Emacs, prompts go to the existing external pinentry. +** TODO [#D] Emacs Packages — Curl-Friendly Web Service Wrappers +Ideas for new Emacs packages following the same pattern as wttrin: HTTP GET to a simple web service, render results in a buffer, optionally show summary in the mode-line. All of these share the async fetch + caching infrastructure already proven in wttrin. +Captured On: [2026-04-04 Sat] +*** TODO Stock Market / Finance Package (Finnhub or Alpha Vantage) +Build a stock watchlist and quote viewer for Emacs. User defines a list of symbols; package fetches quotes and renders a formatted table in a dedicated buffer. Optional mode-line ticker showing one or more symbols rotating on a timer. -Open: confirm the GUI pinentry tool (2026-01-24 notes named =pinentry-dmenu=; current =auth-config.el= names no pinentry program, leaving it to =gpg-agent='s config). Also worth checking whether the =terminal-pinentry= branch survives on the laptop and should be pulled here rather than rewritten. +**** Features +- Customizable watchlist: user defines a list of stock symbols in a defcustom; package fetches and displays all of them in a single buffer +- Formatted quote table: symbol, company name, current price, daily change (absolute and percent), volume — color-coded green/red for gains/losses +- ASCII sparkline charts: inline mini-charts showing intraday or multi-day price movement using Unicode block characters (▁▂▃▅▇ style) +- Mode-line ticker: rotating display of one or more symbols with price and change indicator, similar to wttrin's weather widget — click to open the full watchlist buffer +- Detail view: press RET on a symbol to see extended data — open/high/low/close, 52-week range, market cap, P/E ratio (data availability depends on backend) +- Auto-refresh with market awareness: background timer fetches new data during market hours; pauses on weekends and after-hours to conserve API calls +- Unit/currency preference: display prices in local currency if the backend supports it +- Cache layer: same pattern as wttrin — serve cached data instantly, refresh in background, show staleness indicator when data is old +- Interactive symbol lookup: ~M-x stock-add-symbol~ with completion against a symbol database or search endpoint -*** TODO [#C] env-terminal-p branch in epa :config :feature: -Inside the epa =use-package= =:config= in =modules/auth-config.el=, set =epa-pinentry-mode= to ='loopback= when =(env-terminal-p)=, else leave the external pinentry path active. Replace the lone commented line at =auth-config.el:83=. +**** What you'd learn +- JSON parsing in elisp (~json-parse-buffer~, ~json-read~) — these APIs return JSON, not plain text, so this is the main new skill vs. wttrin +- ASCII chart rendering — drawing sparklines or simple price charts with Unicode block characters in a buffer +- API key management in elisp — storing keys in ~auth-source~ or custom variables, passing them as query params -*** TODO [#C] GPG_TTY export for terminal sessions :feature: -When =(env-terminal-p)=, =(setenv "GPG_TTY" (shell-command-to-string "tty"))= so gpg-agent can target the controlling tty. Guard against a non-tty stdin. +**** Where the complexity lives +- Rendering: No pre-formatted ASCII comes back from the API. You'd build the table layout and any chart visualization yourself. This is the bulk of the work. +- Market hours awareness: Knowing when to fetch (pre-market, regular, after-hours, weekends) to avoid wasting API calls. +- Rate limiting: Free tiers are tight. Finnhub gives 60 calls/min which is generous; Alpha Vantage gives only 25/day on the free tier. Caching strategy matters more here than in wttrin. -*** TODO [#C] gpg-agent updatestartuptty refresh in terminal :feature: -The current =call-process= to "gpg-connect-agent updatestartuptty /bye" runs unconditionally; keep it for GUI, and re-fire it on terminal entry so the agent re-binds to the current tty. +**** Candidate backends +- Finnhub (finnhub.io): Free API key, 60 calls/min, real-time US quotes. JSON only. Best rate limit of the free options. +- Alpha Vantage (alphavantage.co): Free API key, 25 calls/day. Supports CSV output which is trivial to parse — no JSON needed. Good for daily summaries, bad for frequent polling. +- Twelve Data (twelvedata.com): Free key, 800 calls/day, 8/min. Covers stocks, forex, crypto, ETFs. JSON and CSV. -*** TODO [#C] ERT tests for terminal vs GUI pinentry branching :test: -Test that with =env-terminal-p= stubbed t, =epa-pinentry-mode= resolves to ='loopback= after =auth-config= loads; with it stubbed nil, the loopback setting is not applied. Use =cl-letf= around =env-terminal-p=; cover normal, boundary (=epa= already loaded), error (=gpg-connect-agent= missing). +**** Downsides +- API key requirement adds friction for users (signup, config). Not as frictionless as wttrin. +- Rate limits mean you can't poll aggressively. Stale data is the norm on free tiers. +- Financial APIs change or shut down. Yahoo Finance's unofficial API has broken repeatedly over the years. Even paid services deprecate endpoints. Expect maintenance. +- Finnhub and Alpha Vantage are US-market-centric. International coverage varies. -*** TODO [#C] Minibuffer prompt in real terminal Emacs -=emacs -nw=, open an encrypted file or trigger an auth-source decrypt, confirm the passphrase prompt lands in the minibuffer rather than failing on missing pinentry. +**** Effort: Medium-High +The fetch/cache layer is straightforward (reuse wttrin patterns). The rendering layer (tables, charts, color-coding gains/losses) is where most of the time goes. Expect this to be a real project, not a weekend hack. -*** TODO [#C] External pinentry still fires in GUI Emacs -Restart the daemon, open a GUI frame, trigger an encrypted decrypt, confirm =pinentry-dmenu= (or whatever GUI pinentry is configured) still appears. +**** Name candidates (backronyms) +Pick one. All are recursive (self-referential) in the style of CHIME. +- BULL — *BULL Updates Live Listings* +- MINT — *MINT Indexes Noteworthy Tickers* +- QUOTE — *QUOTE Updates Ongoing Ticker Estimates* +- ASSET — *ASSET Surfaces Stock Exchange Tickers* +- MOAT — *MOAT Monitors Active Tickers* +- TRADE — *TRADE Reveals Active Daily Equities* +- BELL — *BELL Exhibits Live Listings* +- CHART — *CHART Highlights Asset Rate Tickers* +- BOARD — *BOARD Oversees Asset Rate Data* +- VAULT — *VAULT Aggregates Underlying Listing Tickers* -*** TODO [#C] Archive the original L3813 task -After this work lands, mark the original "Finish terminal GPG pinentry configuration" task DONE with a =CLOSED:= stamp and a one-line note pointing at this parent task. +*** TODO rate.sx Wrapper — Cryptocurrency Rates +Wrap Igor Chubin's rate.sx service. This is the lowest-effort, highest-pattern-match option — rate.sx works exactly like wttr.in. Returns colored ASCII tables with sparkline charts. Same ~User-Agent: curl~ trick, same ANSI escape codes. -** TODO [#A] Unified popup and messenger UX — placement, dismissal, one library :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-20 -:END: -Merged 2026-06-20 from the config-wide popup-policy task and the messenger-unification -task — they're the same policy at two scopes (the messenger windows are the first -concrete application of the general popup rules). Two parts: +**** Features +- Full crypto dashboard: ~M-x rate-sx~ opens a buffer with a colored ASCII table of top cryptocurrencies — name, price, 24h change, market cap, and sparkline charts — all rendered by the service +- Single coin lookup: ~M-x rate-sx-coin~ prompts for a coin name (e.g., ~eth~, ~btc~) and displays its detailed view +- Plain price fetch: query ~rate.sx/1BTC~ to get a single numeric price — useful for mode-line display or programmatic use from other elisp +- Mode-line widget: show the price of one or more coins in the mode-line with periodic background refresh, similar to wttrin's weather indicator +- Customizable coin list: user picks which coins appear in the dashboard via a defcustom +- Currency base selection: rate.sx supports displaying prices in different fiat currencies +- ANSI color rendering: reuse wttrin's ~xterm-color~ pipeline to convert the service's colored ASCII output into Emacs faces +- Cache with background refresh: same timer-based pattern as wttrin — data stays warm, buffer opens instantly + +**** What you'd learn +- Very little new — this is almost a copy of wttrin with different URL construction. Good first project if you want to validate the pattern before tackling stocks. +- Could explore sharing infrastructure between wttrin and this package (common async fetch, caching, ANSI rendering). -(A) Config-wide popup policy. All transient popups follow one set of principles. -Placement: when the Emacs frame is wider than tall, the popup rises from the right; -when square or taller, from the bottom — settle the aspect-ratio threshold and the -pop-out percentage. Dismissal: C-c C-c when there's an accept action, C-c C-k when -there's a cancel, otherwise =q= closes the window. Generalizes ai-term adaptive -placement (the aspect-ratio docking) and the messenger window/key rules below into -one config-wide policy. From the roam inbox. +**** Where the complexity lives +- Minimal. The service does the formatting. Your job is URL construction, fetch, ANSI-to-faces conversion (already solved in wttrin via ~xterm-color~), and buffer display. +- Coin selection UX: letting users pick which coins to show, custom vs. top-N, etc. -(B) Messenger unification (first application of the policy above). -Spec: [[file:docs/specs/messenger-unification-spec.org][messenger-unification-spec.org]] ([[id:4bfc2011-8ffc-4765-8886-91df12141171][by id]], Draft, 2026-06-11; keybinding-alphabet section + smoke-first parity added 2026-06-16). One library (=cj-messenger-lib.el=) gives every messenger the same shape: chat windows rise from the bottom (the signel rule, generalized), C-c C-c confirms, C-c C-k cancels, C-c C-a attaches — dispatched per backend through a registry + minor mode. Signel already conforms (reference backend); telega and slack join in phases 2-3; ERC later. All eight decisions settled 2026-06-11 (cancel closes an idle window; telega's filter-cancel shadow accepted; slack rooms join the bottom rule). Spec held open — Craig has more ideas to fold in before it's marked Ready. +**** Downsides +- Single point of failure: rate.sx is one person's side project. If Chubin takes it down, the package is dead. No fallback. +- Crypto-only. No traditional stocks, forex, or commodities. +- Less useful than a stock package for most people. -** TODO [#B] agenda sources: roam Projects missing, no existence filtering :bug:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-20 -:END: -From the 2026-06 config audit, =modules/org-agenda-config.el=: -- =:182-191= — commentary and docstrings promise org-roam nodes tagged "Project" as agenda sources, but =cj/--org-agenda-scan-files= never scans them, and files added by the roam finalize-hook are wiped on the next =cj/build-org-agenda-list= cache rebuild (≤1h). Add a roam Project pass (mirror =org-refile-config.el:101-109=) or correct the docs. -- =:186,456= — agenda file list built unconditionally (inbox/calendars may not exist on a fresh machine) and =org-agenda-skip-unavailable-files= is unset — the exact interactive-prompt class that once hung the chime daemon. Filter with =file-exists-p= + set the var as backstop. +**** Effort: Low +Could reuse 70-80% of wttrin's code. A weekend project if you're focused. -** TODO [#B] Auto-dim: org headings, links, and tags do not dim in unfocused windows :bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-20 -:END: -auto-dim-other-buffers-affected-faces (auto-dim-config.el) remaps font-lock and a few org faces to the flat dim face, but not org-level-1..8, org-link, or org-tag, so headings, links (seen in daily-prep.org), and tags like :solo: stay lit when the window loses focus. Decide the dim approach: a flat-dim remap like font-lock (quick) versus dedicated -dim variants surfaced through org-faces / theme-studio (richer, matches the keyword work; Craig flagged org-tags may want the org-faces treatment). Consolidates three roam-inbox captures. -** TODO [#B] "? = curated help menu" convention across modes :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-20 -:END: -From the calibredb keybindings work 2026-06-06. The pattern that worked: in a modal/major-mode buffer (calibredb), bind =?= to a curated transient of the frequent workflows, and move the package's own full dispatch to =H=. It fixes the "I can't discover the keys" problem that which-key can't help with (which-key only pops up after a prefix, not for top-level single keys in a mode-map). +*** TODO Frankfurter Currency Exchange Package +Wrap the Frankfurter API (frankfurter.dev) for fiat currency conversion and historical rates. ECB data, open source, no API key. -Task: survey the modes/modules Craig works in and identify where a =?= -> curated-help-menu (transient) makes sense. Candidates: any major-mode buffer with single-key bindings and no good discovery affordance -- calibredb (done), nov, dirvish, mu4e, ghostel/term, signel, pearl/linear, ELFeed, etc. For each, note whether =?= is free or already a help dispatch, and whether a curated menu (vs the package's own) adds value. Establish it as a convention (and maybe a small helper/macro to define a curated =?= menu consistently). +**** Features +- Quick conversion: ~M-x currency-convert~ prompts for amount, base currency, and target currency — displays the result in the echo area (e.g., "100 USD = 91.34 EUR") +- Multi-target conversion table: convert one amount against several currencies at once, rendered as an aligned table in a dedicated buffer +- Historical rate lookup: query a specific date's exchange rate — useful for expense reports, invoicing, or curiosity +- Rate trend view: fetch a date range and display a table or ASCII sparkline showing how a currency pair moved over days/weeks/months +- Latest rates dashboard: ~M-x currency-latest~ shows today's rates for a user-defined set of currency pairs in a buffer +- Interactive currency selection: completing-read over the ~30 supported currencies with full names (e.g., "USD — United States Dollar") +- Mode-line rate display: optionally show one currency pair's rate in the mode-line with daily background refresh +- Cache layer: rates only update once per business day, so caching is especially effective — fetch once, serve all day -** TODO [#B] Dupre diff-changed / diff-refine-changed legibility :bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Surfaced 2026-06-07 from a pearl session designing its modified-ticket indicator (pearl marks a changed field by inheriting =diff-changed=). dupre's =diff-refine-changed= is bright gold (#ffd700) under near-white text (#f0fef0) -- WCAG contrast ~1.35, unreadable as a plain background. It only looks fine inside diff-mode because diff-mode overlays its own dark foreground. =diff-changed= (#875f00 amber) is ~5.49, readable but off the modus model. Every modus variant keeps both faces legible (contrast 9-16) by pairing a dark low-saturation background with a hue-matched foreground. +**** What you'd learn +- JSON parsing in elisp (the API returns JSON, not formatted text) +- Table rendering — building aligned currency tables with ~format~ and text properties +- Historical data display — the API supports date ranges, so you could show rate trends over time -Ask: -1. Rework dupre's =diff-changed= and =diff-refine-changed= on modus lines: dark low-saturation background, legible foreground (plain default fg for simplicity, or hue-tinted per modus -- decide), and keep refine slightly stronger than changed (refine is the word-level emphasis inside a changed region; modus keeps them distinct). -2. While there, audit dupre's broader diff/palette faces against modus conventions (background/foreground tinting, contrast targets) and flag where it diverges. +**** Where the complexity lives +- Rendering: You'd build the table and any trend visualization yourself. +- Date handling in elisp for historical queries (~encode-time~, ~format-time-string~, etc.). +- UX: interactive base/target currency selection with completion. -Reference values -- modus-vivendi: refine-changed bg #4a4a00 fg #efef80, changed bg #363300 fg #efef80. modus-operandi: refine-changed bg #fac090 fg #553d00, changed bg #ffdfa9 fg #553d00. +**** Downsides +- ECB data updates once per business day. No real-time rates — this is reference data, not trading data. +- Covers ~30 currencies (major fiats). No crypto, no exotic currencies. +- Frankfurter is open-source and self-hostable, which is good for longevity, but the public instance could still go away. -Side-by-side legibility render: [[file:assets/2026-06-07-dupre-diff-face-legibility-compare.png][assets/2026-06-07-dupre-diff-face-legibility-compare.png]]. -** DONE [#B] F7 diff-aware coverage classifies every changed file "not tracked" :bug:solo: -CLOSED: [2026-06-22 Mon] -:PROPERTIES: -:LAST_REVIEWED: 2026-06-20 -:END: -Fixed 2026-06-22: simplecov keys are absolute, git-diff keys repo-relative, so the exact-key intersect never matched. Added =cj/--coverage-relativize-keys= and normalize both tables to repo-relative in =cj/--coverage-read-and-display= before the intersect; intersect unchanged. New =test-coverage-core--relativize-keys.el= (5 unit + 1 integration through the real parsers). Full suite green. -=modules/coverage-core.el:252= — =cj/--coverage-intersect= joins covered×changed by exact string key, but simplecov.json keys are ABSOLUTE paths while the git-diff parser returns repo-RELATIVE ones — zero matches ever, so working-tree/staged/branch scopes report ":tracked nil" for everything and F7's main feature is inert (whole-project scope works, same-source keys). Unit tests hand-build matching keys so they pass; add one integration test feeding a real undercover report + real diff. Normalize both sides to repo-relative. From the 2026-06 config audit. +**** Effort: Low-Medium +JSON parsing adds a step vs. wttrin's plain text, but the API is clean and well-documented. Straightforward project. -** TODO [#C] Migrate tests off mocking primitives (native-comp robustness) :test:refactor: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Long-term test-quality work surfaced by re-enabling native-comp (2026-06-20). When a test redefines a C primitive or a native-compiled function (=cl-letf=/=fset=/=advice-add=), native-comp routes native callers through a trampoline, which interacts badly with mocks in three ways: trampoline-build failure under =--batch=, silent mock-bypass (native callers ignore the redefinition), and arity mismatch (the trampoline calls the mock with the primitive's max arity). +*** TODO ipinfo.io — IP and Geolocation Lookup +~curl ipinfo.io~ returns JSON with your public IP, city, region, country, ISP, and timezone. No auth needed for basic lookups (1000 requests/day unauthenticated). -Done 2026-06-21 (the immediate fix): swept every arity-narrow subr mock to =(lambda (&rest _) ...)= (188 sites) and added =tests/test-meta-subr-mock-arity.el=, which fails =make test= on any arity-narrow subr mock. That kills the arity mode (the only one we've hit) and enforces it going forward. +**** Features +- My IP: ~M-x ipinfo~ fetches your public IP and geolocation, displays a formatted summary in a buffer or the echo area — IP, city, region, country, ISP, timezone, coordinates +- Arbitrary IP lookup: ~M-x ipinfo-lookup~ prompts for an IP address and shows the same geolocation detail +- Copy IP to kill ring: one-keystroke convenience for grabbing your public IP +- Open in browser map: command to open the returned lat/long coordinates in OpenStreetMap or Google Maps via ~browse-url~ +- Hostname resolution: the API also returns the reverse DNS hostname for an IP +- Mode-line IP display: optionally show your current public IP in the mode-line (useful when switching between networks/VPNs) +- Org-mode integration: insert IP/geo info as an org property block or table row at point -This task is the durable fix the ecosystem and =elisp-testing.md= point to: restructure tests so they don't redefine primitives at all — inject dependencies, drive real state (temp-file fixtures, real buffers), or test pure helpers. That closes the two latent modes (build-failure, silent-bypass) the variadic sweep leaves open. Big, incremental, low-urgency. +**** What you'd learn +- Minimal new skills — simple JSON response, single fetch, render in buffer or echo area. +- Could add map integration (open coordinates in browser or an Emacs map package). -Full mechanism, the three failure modes, the research (Emacs bug#51140, bug#61880, buttercup #230, Debian #1021842, the emacs-29 redefine-primitive warning, the manual on =native-comp-enable-subr-trampolines=), and the decision: [[file:docs/native-comp-subr-mocking.org][docs/native-comp-subr-mocking.org]]. +**** Where the complexity lives +- Almost nowhere. This is the simplest possible package. Fetch JSON, format it, display it. +- If you want to look up arbitrary IPs (not just your own), add a prompt with completion history. -** TODO [#B] Fix up test runner :feature:refactor: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -*** 2026-05-16 Sat @ 11:15:51 -0500 Ideas -**** Current State -=modules/test-runner.el= is a solid first pass for an Emacs-config-specific ERT -workflow: -- project-scoped focus lists -- run all vs focused mode -- run ERT test at point -- load all test files -- clear ERT tests from other project roots -- keybindings under =C-; t= +**** Downsides +- Very niche utility. You look up your IP occasionally, not daily. +- Free tier is generous (1000/day) but authenticated lookups require a token for enriched data. +- Privacy-conscious users may not want to send their IP to a third party (though they already do by virtue of connecting). -The universal test-running direction is currently split across modules: -- =test-runner.el= owns ERT focus/state/UI. -- =dev-fkeys.el= owns F6 language detection and command generation for Elisp, - Python, Go, and partial TypeScript. +**** Effort: Very Low +An afternoon project. Good as a learning exercise for the fetch-parse-render pattern if you haven't done JSON APIs in elisp before. -That split is the biggest architectural pressure point. The test runner should -eventually own runner discovery, scopes, command construction, result handling, -and UI. F6 should become a thin entry point into the runner. +*** TODO icanhazdadjoke.com — Dad Jokes in Emacs +~curl -H "Accept: text/plain" https://icanhazdadjoke.com~ returns a single plain-text joke. No auth, no key, no rate limit concerns for casual use. -**** Critical Design Issues -***** Too ERT-specific at the core -The current state model is named generically, but most operations assume: -- test files live in =test/= or =tests/= -- files match =test-*.el= -- tests are ERT forms -- individual tests can be selected by ERT selector regex -- loading tests into the current Emacs process is acceptable +**** Features +- Random joke: ~M-x dad-joke~ fetches a random joke and displays it in the echo area — minimal disruption, maximum groan +- Joke buffer: ~M-x dad-joke-buffer~ opens a dedicated buffer with a joke, nicely formatted with a large font face. Press ~n~ for the next joke, ~q~ to quit +- Search jokes: ~M-x dad-joke-search~ prompts for a term (e.g., "cat") and displays matching jokes in a buffer — the API supports ~?term=~ search +- Startup joke: optional hook to display a dad joke in the echo area or scratch buffer on Emacs startup +- Org-mode insertion: ~M-x dad-joke-insert~ inserts a joke at point — for lightening up documentation or commit messages +- Kill ring: ~M-x dad-joke-yank~ fetches a joke and puts it directly in the kill ring for pasting elsewhere -This makes the module hard to extend cleanly to pytest, Jest, Vitest, Go, Rust, -or shell test runners. The common abstraction should be "test run request" and -"test runner adapter", not "ERT file list". +**** What you'd learn +- Nothing technically new — this is the simplest possible HTTP-GET-to-buffer pattern. +- Good excuse to experiment with fun presentation: display in echo area, dedicated buffer, or even as a startup message. -***** In-process ERT causes state contamination -=cj/test-load-all= and focused runs load test files into the current Emacs -session. This is fast and ergonomic, but it can leak: -- global variables -- advice -- loaded features -- overridden functions -- ERT test definitions -- load-path mutations +**** Where the complexity lives +- It doesn't. Fetch a string, display it. The API also supports search (~?term=dog~) if you want to add that. -The runner should support two ERT execution modes: -- =interactive= / in-process for fast local TDD -- =isolated= / batch Emacs for reliable verification +**** Downsides +- Toy project. Zero practical utility beyond morale. +- The joke quality is... dad jokes. -The isolated path should be preferred for "before commit", CI parity, and -agent-driven verification. +**** Effort: Trivial +An hour, maybe two if you add search and a nice buffer layout. Publishable on MELPA as a novelty package. -***** Test discovery is regex-based and fragile -=cj/test--extract-test-names= scans files with a regex for =ert-deftest=. -That misses or mishandles: -- macro-generated tests -- commented forms in unusual shapes -- multiline or reader-conditional forms -- non-ERT Elisp tests such as Buttercup -- stale ERT tests already loaded in the session +*** TODO qrenco.de — QR Code Generator +Chubin's QR code service. ~curl qrenco.de/hello~ returns a QR code rendered in Unicode block characters. Encodes arbitrary text, URLs, WiFi credentials, etc. -Better approach: -- for ERT in isolated mode, let ERT discover tests after loading files -- for source navigation, use syntax-aware forms where possible -- store discovered tests as structured records with file, line, name, framework, - tags, and runner +**** Features +- Encode text: ~M-x qr-encode~ prompts for a string and displays the QR code in a dedicated buffer using Unicode block characters +- Encode region: ~M-x qr-encode-region~ encodes the currently selected text — quick way to QR-ify a URL, password, or snippet +- Encode URL at point: ~M-x qr-encode-url~ detects the URL under point (via ~thing-at-point~) and generates a QR code for it +- WiFi QR codes: ~M-x qr-wifi~ prompts for SSID, password, and encryption type, then generates the standard WiFi QR format (~WIFI:T:WPA;S:MyNetwork;P:password;;~) — scan to join a network +- Buffer font management: automatically sets the buffer to a monospace font with consistent Unicode block rendering (same approach as wttrin's Liberation Mono override) +- Copy as text: yank the QR code's block characters to the kill ring for pasting into emails, READMEs, or chat +- Adjustable size: the service supports size parameters — expose this as a prefix argument or defcustom -***** Path containment has at least one suspicious edge -=cj/test--do-focus-add-file= checks: +**** What you'd learn +- Handling Unicode block character output (not ANSI colors this time, but character-level rendering) +- Interactive input patterns — prompting for text to encode, or encoding the current region/URL at point -#+begin_src elisp -(string-prefix-p (file-truename testdir) (file-truename filepath)) -#+end_src +**** Where the complexity lives +- Font and character width: QR codes require a monospace font where the block characters render at consistent widths. Some Emacs font configurations break this. You'd need to set the buffer font explicitly (like wttrin does). +- The service sometimes returns ANSI codes for inverted colors. May need ~xterm-color~ or manual processing. -That should use =cj/test--file-in-directory-p= or ensure the directory has a -trailing slash. Otherwise sibling paths with a shared prefix are a recurring -class of bug. +**** Downsides +- Same single-point-of-failure risk as rate.sx — one person's service. +- QR codes in a terminal/buffer are inherently lower resolution than image-based ones. Scanning reliability depends on terminal font size and screen. +- Niche use case. Most people generate QR codes infrequently. -***** Runner commands are shell strings too early -=cj/--f6-test-runner-cmd-for= returns shell command strings. That makes it -harder to: -- inspect command parts -- safely quote arguments -- offer command editing -- run via =make-process= / =compilation-start= without shell ambiguity -- attach metadata -- rerun exact invocations -- convert commands into UI labels +**** Effort: Low +Similar to rate.sx in scope. The fetch is trivial; font handling and display are the main considerations. -Prefer a structured command object: +*** TODO dns.toys — Multi-Tool Utility via DNS +dns.toys answers queries over DNS instead of HTTP. ~dig 100USD-EUR.fx @dns.toys~ returns currency conversion, ~dig mumbai.time @dns.toys~ returns world time, ~dig 42km-mi.unit @dns.toys~ does unit conversion. Also supports base conversion, math constants, and more. -#+begin_src elisp -(:program "pytest" - :args ("tests/test_foo.py" "-q") - :default-directory "/project/" - :env (("PYTHONPATH" . "...")) - :runner pytest - :scope file) -#+end_src +**** Features +- Currency conversion: ~M-x dns-toys-currency~ prompts for amount and currency pair (e.g., "100 USD to EUR"), displays result in echo area +- World time: ~M-x dns-toys-time~ prompts for a city name and shows the current local time — faster than searching online, no browser needed +- Unit conversion: ~M-x dns-toys-unit~ prompts for a value and unit pair (e.g., "42 km to mi"), returns the conversion +- Base conversion: ~M-x dns-toys-base~ converts between decimal, hex, octal, and binary (e.g., "100 dec to hex") +- Math constants: ~M-x dns-toys-constant~ looks up pi, e, tau, etc. — niche but handy in a calc session +- Unified command: ~M-x dns-toys~ with a smart prompt that detects query type from input format, dispatching to the right DNS query automatically +- Echo area results: all results display in the echo area by default for quick non-disruptive answers, with an optional dedicated buffer for history +- Async queries: use ~start-process~ with sentinels so ~dig~ calls don't block Emacs + +**** What you'd learn +- Calling external processes from elisp (~call-process~ or ~start-process~ to invoke ~dig~) instead of ~url-retrieve~. This is a meaningfully different integration pattern from wttrin. +- Parsing DNS TXT record output — dig returns structured but noisy output; you'd extract the answer section. +- Building a multi-function package — this one service covers currency, time, units, and base conversion, so the UX needs a dispatch mechanism (separate commands, or a unified prompt with type detection). + +**** Where the complexity lives +- Output parsing: ~dig~ output is not designed for human consumption. You'd parse the ANSWER SECTION, strip TTL/class/type fields, and extract the payload string. +- Latency: DNS queries are fast but ~call-process~ on ~dig~ has subprocess overhead. For interactive use this is fine; for mode-line updates you'd want async (~start-process~ with a sentinel). +- Feature breadth: The temptation is to wrap every dns.toys feature. Scoping to a focused set (currency + time + units) keeps it manageable. -Render to a shell string only at the final compilation boundary. +**** Downsides +- Requires ~dig~ installed (standard on Linux/macOS, not on Windows). Limits portability. +- dns.toys is a single maintainer's project. Same fragility concern as rate.sx and qrenco.de. +- DNS protocol means no rich formatting — just short text strings. The results are useful but visually plain. +- Some networks/firewalls block non-standard DNS queries, which would silently break the package. -***** F6 and =C-; t= workflows duplicate the same domain -F6 already handles "all tests" and "current file's tests" for multiple -languages. =C-; t= handles ERT-only focus and run state. These should converge -on one runner service: -- F6: quick entry point -- =C-; t=: full runner menu -- both call the same scope/adapter engine +**** Effort: Low-Medium +The individual queries are trivial. The interesting work is building a clean multi-function UX and handling the process-based (vs. HTTP-based) integration pattern. Good project for learning elisp process management. -***** Test directory discovery is too narrow -Current discovery prefers =test/= then =tests/=, with a global fallback. Real -projects often need: -- Python: =tests/=, package-local =test_*.py=, =pytest.ini=, =pyproject.toml= -- JS/TS: =package.json= scripts, =vitest.config.*=, =jest.config.*=, - =*.test.ts=, =*.spec.ts= -- Go: package directories, =go.mod= -- Rust: =Cargo.toml=, integration tests under =tests/= -- Elisp packages: =Makefile=, =Eask=, =ert-runner=, Buttercup, =tests/= +*** TODO cheat.sh Integration — Programming Cheat Sheets +~curl cheat.sh/tar~ returns a syntax-highlighted cheat sheet. Supports language-specific queries like ~cheat.sh/python/lambda~. Already has some Emacs integrations (cheat-sh.el exists) but could be worth a custom implementation if existing packages don't fit your workflow. -Discovery should be adapter-specific and project-config-aware. +**** Features +- Quick lookup: ~M-x cheat-sh~ prompts for a topic (e.g., "tar", "git/stash") and displays a syntax-highlighted cheat sheet in a dedicated buffer +- Language-scoped queries: ~M-x cheat-sh-lang~ prompts for language then topic (e.g., ~python/lambda~, ~go/goroutine~) with two-stage completion +- Context-aware lookup: detect the current buffer's major mode and scope the query to that language automatically — in a Python buffer, querying "lambda" goes to ~cheat.sh/python/lambda~ +- ANSI-to-faces rendering: convert the service's syntax-highlighted ANSI output to proper Emacs font-lock faces using ~xterm-color~ (same pipeline as wttrin) +- Navigation: browse related topics from within the buffer — follow-up queries without returning to the minibuffer. Previous/next topic history with ~p~ / ~n~ +- Completion against the topic list: fetch and cache ~cheat.sh/:list~ to provide completing-read over all available topics +- Offline cache: optionally cache previously viewed cheat sheets for offline access or instant re-display +- Region query: select a command or function name and look it up directly with ~M-x cheat-sh-region~ -***** No structured result model -=cj/test-last-results= exists but is not meaningfully populated. A powerful -runner needs a normalized result model: -- run id -- started/finished timestamps -- status: passed/failed/errored/cancelled/skipped/xfail/xpass -- command -- runner adapter -- scope -- exit code -- duration -- failed test records -- file/line locations -- raw output buffer -- coverage artifact paths +**** What you'd learn +- ANSI syntax highlighting → Emacs faces (same skill as wttrin) +- Deep completion support: cheat.sh has a massive topic tree. Building good interactive completion for ~cheat.sh/{language}/{topic}~ is a UX challenge. -This enables last-failed, failures-first, summaries, dashboards, and AI-assisted -failure explanation. +**** Where the complexity lives +- Completion and navigation: the value is in making it fast to find the right cheat sheet. ~cheat.sh/:list~ returns thousands of entries. +- Existing packages: ~cheat-sh.el~ already exists on MELPA. You'd need a reason to build your own (better caching, offline support, integration with your workflow). -***** No failure parser / navigation layer -Compilation buffers are useful, but the runner should parse common failure -formats and provide: -- next/previous failure -- jump to source line -- failure summary buffer -- copy failure context -- rerun failed test at point -- annotate failing tests in source buffers +**** Downsides +- Overlaps with existing Emacs packages. Check ~cheat-sh.el~ before building. +- The service aggregates from many sources. Quality is inconsistent across topics. -Adapters can provide regexes/parsers for ERT, pytest, Jest/Vitest, Go, Rust, -and shell. +**** Effort: Medium +If building from scratch. Low if extending or wrapping an existing package. The completion UX is where the effort goes. +** TODO [#D] Localrepo refresh / update script :feature: +No dedicated update path today — refreshing a pinned package means ad-hoc =cp= from the local elpa mirrors. Document the current shape and decide whether a =scripts/refresh-localrepo.sh= is worth writing. Cross-linked from =docs/design/localrepo.org=. -***** Missing watch/rerun modes -Modern test runners optimize the feedback loop: -- pytest supports selecting tests, markers, last-failed, failures-first, - stepwise, fixtures, xfail/skip, plugins, and cache state. -- Jest/Vitest support watch workflows, changed-file selection, coverage, - snapshots, and rich interactive filtering. Vitest also defaults to watch in - development and run mode in CI. -- Go and Rust runners commonly support package-level runs, regex selection, - race/coverage flags, and cached test behavior. +** TODO [#D] Native-comp .eln cache strategy :feature: +The native-comp =.eln= cache is Emacs-version-specific; an Emacs upgrade invalidates everything. Document the cache location, what an upgrade triggers, and whether a warm-the-cache script is worth shipping. Cross-linked from =docs/design/localrepo.org=. -The Emacs runner should expose the subset that maps well to editor workflows: -- current test -- current file -- related test file -- focused set -- last failed -- failed first -- changed since git base -- watch current scope -- full project -- coverage for current scope +** TODO [#D] Polish reveal.js presentation setup :feature: -**** Proposed Architecture -***** Core Types -Use plain plists initially; promote to =cl-defstruct= only if helpful. +Three small reveal.js improvements; collected into one task because each on its own is too small to track separately. -#+begin_src elisp -;; Test runner adapter -(:id pytest - :name "pytest" - :languages (python) - :detect cj/test-pytest-detect - :discover cj/test-pytest-discover - :build-command cj/test-pytest-build-command - :parse-results cj/test-pytest-parse-results - :capabilities (:current-test :file :project :last-failed :coverage :watch)) +1. *Image insertion helper.* Function to insert images with proper org-reveal attributes (sizing, background images, etc.) without having to remember the syntax. +2. *Default font sizing for slide elements.* Configure reveal.js font sizes for headings, body text, code blocks, etc. — better defaults via =org-reveal-head-preamble= CSS or a custom theme. +3. *Custom dupre reveal.js theme.* CSS theme using the colors from =themes/dupre-palette.el=. Install into =reveal.js/css/theme/= for use with =#+REVEAL_THEME: dupre=. -;; Test run request -(:project-root "/repo/" - :language python - :framework pytest - :scope file - :file "/repo/tests/test_api.py" - :test-name "test_create_user" - :extra-args ("-q") - :profile default) +** TODO [#D] System-tool dependency install script :feature: +=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, and other binaries that =cj/executable-find-or-warn= flags at module load are not in =package.el='s reach. Document the required-tool set and ship a setup script (or =pacman=/=apt= invocation set). Cross-linked from =docs/design/localrepo.org=. -;; Test run result -(:run-id "..." - :status failed - :exit-code 1 - :duration 2.14 - :failures (...) - :output-buffer "*test pytest*" - :artifacts (...)) -#+end_src +** TODO [#D] Treesitter grammar offline cache :feature: +Treesitter grammars are downloaded by =treesit-auto= on first use and live outside the localrepo. For true offline reproducibility, cache the grammars next to the localrepo (a =.localrepo/treesitter/= tier, or a separate mirror script). Cross-linked from =docs/design/localrepo.org=. +* Emacs Someday/Maybe -***** Adapter Registry -Create a registry like: +** TODO [#D] GPTel orphan tasks and useful ideas :feature: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: -#+begin_src elisp -(defvar cj/test-runner-adapters nil) -(cj/test-register-adapter 'pytest ...) -(cj/test-register-adapter 'ert ...) -(cj/test-register-adapter 'vitest ...) -#+end_src +On 2026-06-23 gptel was archived out of the live config (its modules, +tools, tests, and specs moved to archive/gptel/) because it sees little +use. This subtree was the gptel agentic-tool feature backlog. I kept it +here in Someday/Maybe instead of deleting it: most of the child ideas +below are agent-tool concepts that are not gptel-specific (org-roam node +tools, git section tools, ripgrep / pandoc / ffmpeg / jq wrappers, +messaging and buffer-state tools) and would carry over to the ai-term +Claude agents or an MCP tool layer if that path is taken. They are +reference, not active work. -Runner selection should consider: -- buffer file extension -- project files -- explicit user override -- available executables -- package manager scripts -- existing Makefile targets +Categories below thematize the agent affordances the design doc +[[file:docs/design/gptel-agentic-tool-ideas.org][gptel-agentic-tool-ideas.org]] +points at -- Git, Org, messaging, file / buffer / workspace state, +media, and the dev loop. The shortlist's first-batch ADOPT tools +(git_status / git_log / git_diff / web_fetch) already shipped; the +themes below are next-tier work where the agent treats Emacs as a +structured workspace, not a text terminal. Per-theme spec lives in +the task body once written; implementation tasks land as siblings +of the spec heading once the spec is approved. The magit-backend +reimplementation of the shipped git tools is tracked separately in +[[id:bd47c9a8-aae1-4a3d-ad5b-b8767f2fd580][gptel-git-tools-magit-backend-spec.org]]. -***** Scope Model -Make scopes explicit and shared across languages: -- =test-at-point= -- =current-file= -- =related-file= -- =focused-files= -- =last-failed= -- =changed= -- =package/module= -- =project= -- =coverage= -- =watch= +*** TODO [#C] Wire Up MCP.el so That GPTel Has Access to MCP Servers via GPTel Tools -Each adapter can say which scopes it supports. Unsupported scopes should produce -clear user-errors with suggestions. +**** 2026-05-16 Sat @ 15:44:36 -0500 Spec -***** Command Builder Pipeline -1. Detect project. -2. Detect language/framework candidates. -3. Resolve user-requested scope. -4. Build structured command object. -5. Optionally let user edit command. -6. Run via =compilation-start= or =make-process=. -7. Parse output/result artifacts. -8. Store normalized result. -9. Update UI/modeline/messages/failure buffer. +Design doc: [[id:b4c274c5-8572-4a7b-b657-d315712bd6af][docs/specs/mcp-el-gptel-integration-spec-doing.org]] -***** Keep Makefile Support But Do Not Require It -For this Emacs config, =make test-file= and =make test-name= are useful and -should remain the default Elisp isolated path. But adapter detection should -support: -- direct =emacs --batch= ERT invocation -- =make test= -- =make test-file= -- =make test-name= -- Eask -- Buttercup +**** 2026-05-17 Sun @ 14:14:34 -0500 Landed ai-mcp.el pure-helper foundation -**** Elisp-Specific Improvements -***** Add isolated ERT runs -Support batch commands for: -- all project tests -- one test file -- one test name -- focused files -- last failed, once result parsing exists +Commit =54d231be=. Sections 1 (constants + defcustoms) and 3 (pure helpers) of the seven-section outline. 41 ERT tests, all green. Refactor audit caught two duplications during Phase 4 and folded them into the same commit (=cj/mcp--get-server-entry= and =cj/mcp--name-matches-p=). Phase 1.5 (confirmation contract) is next. -Use the same Makefile targets in this repo, but design the adapter so other -Elisp projects can run without this Makefile. +**** TODO [#C] Phase 1.5 -- GPTel confirmation contract -***** Support Buttercup/Eask Later -Buttercup uses BDD-style =describe= / =it= suites and is common in Elisp -package testing. Eask is often used to run package tests. Add adapter slots -for these instead of hard-coding ERT forever. +*Goal:* flip =gptel-confirm-tool-calls= to ='auto= and gate the existing local tools that need it. -***** Avoid unnecessary global ERT deletion -=cj/ert-clear-tests= is a pragmatic fix for project contamination, but the -stronger long-term answer is isolated runs plus project-scoped discovery. Keep -the cleanup command, but do not make correctness depend on deleting global ERT -state. +*Entry:* Phase 1 module exists and helpers tested. -**** Python / pytest Ideas -- Detect pytest by =pyproject.toml=, =pytest.ini=, =tox.ini=, =setup.cfg=, or - presence of =tests/=. -- Build commands for: - - project: =pytest= - - file: =pytest path/to/test_file.py= - - test at point: =pytest path/to/test_file.py::test_name= - - class method: =pytest path::TestClass::test_method= - - marker: =pytest -m marker= - - last failed: =pytest --lf= - - failed first: =pytest --ff= - - stop after first: =pytest -x= - - coverage: =pytest --cov=...= -- Parse output for failing node ids and =file:line= references. -- Read pytest cache for last-failed where useful. -- Offer marker completion by parsing =pytest --markers= or config files. -- Surface xfail/skip separately from hard failures. +*DECISION (cj):* which of the existing local tools register with =:confirm t= once ='auto= is in effect? Reads (=read_buffer=, =read_text_file=, =list_directory_files=, =git_status=, =git_log=, =git_diff=) clearly stay =:confirm nil=. Judgment calls: +- =web_fetch= -- fetches arbitrary URLs the agent supplies. Spec recommends gating. +- =write_text_file= -- writes any path under =$HOME= with agent-supplied content. +- =update_text_file= -- modifies an existing file with an agent-supplied transform. +- =move_to_trash= -- moves a path to trash (reversible but disruptive). + +*Deliverables:* +- =ai-mcp.el= setup section runs =(setq gptel-confirm-tool-calls 'auto)=. +- Remove =(setq gptel-confirm-tool-calls nil)= from =modules/ai-config.el:386= with a comment pointing at =ai-mcp.el=. +- For each tool the decision marks "gate," add =:confirm t= to its =gptel-make-tool= form. +- Tests in =tests/test-ai-mcp-confirm-contract.el= asserting: =gptel-confirm-tool-calls= is ='auto= after load; write-classified stub MCP tool with =:confirm t= triggers the confirm branch in =gptel-send='s dispatch (stub the prompt); read-classified MCP tool with =:confirm nil= does not; =git_log= (=:confirm nil=) still runs without prompting; each newly-gated local tool does prompt. -**** TypeScript / JavaScript Ideas -***** Detection -Detect runner by project files and scripts: -- =vitest.config.ts/js/mts/mjs= -- =jest.config.ts/js/mjs/cjs= -- =package.json= scripts: =test=, =test:watch=, =vitest=, =jest= -- lockfile/package manager: =pnpm-lock.yaml=, =yarn.lock=, =package-lock.json=, - =bun.lockb= +*Exit:* tests green. Manual smoke: open GPTel, call a gated tool, confirm prompt appears. Call =git_log=, no prompt. -Prefer project scripts over raw =npx= when present: -- =pnpm test -- path= -- =npm test -- path= -- =yarn test path= -- =bun test path= +**** TODO [#B] Phase 2 -- Compat layer + registration pipeline (fake inventory) -***** Scopes -- current file: =vitest run path= or =jest path= -- test at point: use nearest =it= / =test= / =describe= string and pass =-t= -- watch current file -- changed tests where runner supports it -- coverage current file/project -- update snapshots +*Goal:* implement the mcp.el compat wrappers and the tool-registration pipeline against stubbed =mcp-server-connections=. -***** Result Parsing -Parse: -- failing test names -- file paths and line numbers -- snapshot failures -- coverage summary +*Entry:* Phase 1.5 proves gptel respects per-tool =:confirm= slot. -Treat snapshot updates as an explicit command, not an automatic side effect. +*Deliverables:* +- Section 4 of =ai-mcp.el= (compat layer): =cj/mcp--server-status=, =cj/mcp--server-tools=, =cj/mcp--server-name=, =cj/mcp--assert-capabilities=. Each helper documents the upstream commit / file location it targets. +- Section 5 of =ai-mcp.el= (registration pipeline): =cj/mcp--register-tool=, =cj/mcp--register-server-tools=, =cj/mcp--deregister-server-tools=, =cj/mcp--rewrite-plist=, =cj/mcp--registered-tools= hash. +- All MCP tools register with =:async t=. +- Tests in =tests/test-ai-mcp-registration.el=. -**** Go Ideas -- Detect =go.mod=. -- Current file/source: run package =go test ./pkg=. -- Test at point: nearest =func TestXxx= and run =go test ./pkg -run '^TestXxx$'=. -- Bench at point: nearest =BenchmarkXxx= and run =go test -bench '^BenchmarkXxx$'=. -- Add toggles for =-race=, =-cover=, =-count=1=, =-v=. -- Parse =file.go:line:= output and package failure summaries. +*Exit:* with a stubbed =mcp-server-connections=, registration produces correctly prefixed =mcp__SERVER__TOOL= entries in =gptel-tools=; closures call =mcp-call-tool SERVER REMOTE-NAME= (verified by stubbing =mcp-async-call-tool=); deregistration removes only MCP-owned tools and leaves a pre-populated local =git_log= entry intact; re-registration replaces function pointer without duplicating menu entries; confirm overrides win over patterns. -**** Rust Ideas -- Detect =Cargo.toml=. -- Use =cargo test= by default, optionally =cargo nextest run= when available. -- Current test at point: nearest =#[test]= function. -- Current file/module where possible. -- Integration test file: =cargo test --test name=. -- Support =-- --nocapture= toggle. -- Parse compiler/test failures and =file:line= links. +**** TODO [#B] Phase 3 -- Async state machine + timer-race timeout wrapper -**** Shell / Generic Ideas -- Adapter for Makefile targets: - - detect =make test=, =make check=, =make coverage= - - expose project-level commands even when language-specific detection fails -- Adapter for arbitrary project command configured in dir-locals or a project - config plist. -- Let users register custom command templates per project: +*Goal:* implement the lifecycle state machine and the per-call timer-race timeout. -#+begin_src elisp -((:name "unit" - :command ("npm" "run" "test:unit" "--" "{file}")) - (:name "integration" - :command ("pytest" "tests/integration" "-q"))) -#+end_src +*Entry:* Phase 2 registration works against stubs. -**** UI Ideas -***** Transient Menu -Replace or complement the raw keymap with a =transient= menu: -- scope: current test/file/focused/last failed/project -- runner: auto/ert/pytest/vitest/jest/go/cargo/make -- toggles: watch, coverage, debug, fail-fast, verbose, update snapshots -- actions: run, rerun, edit command, show failures, open report +*Deliverables:* +- Section 6 of =ai-mcp.el= (async state machine): =cj/mcp--state=, =cj/mcp--server-status= alist, =cj/mcp--stall-timer=, =cj/mcp-ensure-started=, =cj/mcp--on-hub-callback=, =cj/mcp--poll-status=, =cj/mcp--start-stall-timer=, =cj/mcp--build-status-from-specs=. +- =cj/mcp--wrap-async-with-timeout= (timer/callback race; both branches set =done= before invoking gptel callback so late responses are ignored). +- Tests in =tests/test-ai-mcp-async.el=. -***** Result Buffer -Create a normalized =*Test Results*= buffer: -- latest status per project -- command and duration -- pass/fail/skip counts -- failure list with clickable =file:line= -- actions to rerun failed/current/all -- links to coverage artifacts +*Exit:* =cj/mcp-ensure-started= returns in <100 ms with delayed-callback stubs; stall timer fires for stuck servers; timer-race wrapper handles all three orderings (MCP-first, timer-first, late-MCP-after-timer); async error path (=:error-callback= without inited callback) reaches =failed= state via polling. -***** Modeline / Headerline Signal -Show the last run status for the current project: -- green passed -- red failed -- yellow running -- gray no run +**** TODO [#B] Phase 4 -- First real connection (drawio or slack-deepsat) -Keep it quiet and optional. +*Goal:* wire one real no-auth server end-to-end against actual mcp.el and prove the stubbed Phase 3 behavior matches reality. -***** History -Store recent run requests per project: -- rerun last -- rerun last failed -- choose previous command -- compare duration/status against previous run +*Entry:* Phase 3 async works against stubs. -**** Configuration Ideas -- =cj/test-runner-default-scope= -- =cj/test-runner-prefer-isolated-elisp= -- =cj/test-runner-project-overrides= -- =cj/test-runner-known-adapters= -- =cj/test-runner-enable-watch= -- =cj/test-runner-result-retention= -- per-project override through =.dir-locals.el= +*Deliverables:* +- Add =use-package mcp= to =ai-mcp.el= (MELPA active, =:load-path= for local checkout commented). +- =cj/mcp--assert-capabilities= called at load time; signals clearly if mcp.el is too old. +- Set =cj/mcp-enabled-servers= temporarily to =("drawio")= (or =("slack-deepsat")= if the local proxy is running). +- First real =cj/mcp-ensure-started= invocation from =cj/toggle-gptel=. -Example: +*Exit:* manual smoke -- =C-; a t= opens GPTel without blocking; within 30 s, drawio (or slack-deepsat) tools appear in =gptel-menu= grouped by category; calling a tool returns expected output; killing the subprocess externally surfaces as =failed= in =cj/mcp--server-status=. -#+begin_src elisp -((nil . ((cj/test-runner-project-overrides - . (:adapter pytest - :default-args ("-q") - :coverage-args ("--cov=src")))))) -#+end_src +**** TODO [#B] Phase 5 -- Status UX + commands + doctor (static) -**** Safety And Robustness -- Use structured commands until the final boundary. -- Quote only at render time. -- Avoid shell when =make-process= / =process-file= is sufficient. -- Keep command preview/editing available for surprising cases. -- Detect missing executables before running. -- Add timeouts/cancel commands for long-running or hung tests. -- Do not silently fall back from a missing runner to a different runner unless - the fallback is visible in the command preview. -- Avoid mutating global =load-path= permanently. -- Keep remote/TRAMP behavior explicit; do not accidentally run local commands - for remote projects. +*Goal:* ship the full server-management UX so partial-availability and failures are visible. -**** Coverage Integration -Tie this into the existing coverage work: -- run coverage for current file/scope -- open latest coverage report -- summarize uncovered lines for current file -- support Elisp SimpleCov/Undercover, pytest-cov, Vitest coverage, Go cover, - and Rust coverage later -- store coverage artifact paths in the normalized run result +*Entry:* Phase 4 proves a real connection works. -**** AI-Assisted Debugging Ideas -- Summarize failing tests from the parsed failure records and raw output. -- Include command, changed files, failure snippets, and relevant source/test - locations. -- Redact env vars, tokens, Authorization headers, and secrets before sending to - =gptel=. -- Add commands: - - =cj/test-runner-explain-failure= - - =cj/test-runner-suggest-related-tests= - - =cj/test-runner-summarize-coverage-gap= +*Deliverables:* +- Section 7 of =ai-mcp.el= (UI). +- Commands: =cj/mcp-status= (echo-area summary keyed off =cj/mcp--state=), =cj/mcp-list-tools= (tabulated buffer with failed servers at top in red face; keys =g r c RET q=), =cj/mcp-doctor= (static mode only -- capability, =npx=/=uvx=, Claude config, per-server env, local endpoints; output buffer keys =c r q=), =cj/mcp-wait-until-ready=, =cj/mcp-hub= (thin wrapper that ensures startup first), =cj/mcp-restart-failed=, =cj/mcp-restart-server=, =cj/mcp-stop-all=. +- Keymap: =C-; a C= subprefix bound in =ai-config.el='s autoload section. Keys =h s l r R S d w=. +- which-key labels for every binding. +- =kill-emacs-hook= registration for =cj/mcp-stop-all=. +- Investigation: does =gptel-menu= refresh after mid-call tool registration? Document the answer in =ai-mcp.el= commentary; if it requires close+reopen, add to known UX caveats. -**** Migration Plan -***** Phase 1: Internal cleanup -- Fix the task typo and rename current ERT-specific functions or wrap them under - an ERT adapter. -- Move F6 language detection/command construction from =dev-fkeys.el= into - =test-runner.el= or a new =test-runner-core.el=. -- Replace shell-string command builders with structured command plists. -- Fix path containment in =cj/test--do-focus-add-file=. -- Make =cj/test-last-results= real for ERT runs. +*Exit:* all keymap bindings work; audit buffer surfaces failed servers prominently; doctor identifies each scenario in the manual test matrix; status command shows the right state for each phase transition. -***** Phase 2: ERT adapter -- Implement adapter registry. -- Add ERT adapter with in-process and isolated modes. -- Preserve all current keybindings by routing them through the adapter. -- Add failure/result normalization for ERT. -- Add "rerun last" and "rerun failed" for ERT. +**** TODO [#B] Phase 6 -- HTTP servers (linear, notion) -***** Phase 3: Python and JS/TS adapters -- Add pytest adapter. -- Add Vitest/Jest adapter with package-manager/script detection. -- Support current file and test-at-point for both. -- Add parser/navigation for common failures. +*Goal:* add the two HTTP-transport servers with in-protocol OAuth. -***** Phase 4: UI and watch modes -- Add transient menu. -- Add result buffer. -- Add cancellation and rerun history. -- Add watch commands where supported. +*Entry:* Phase 5 UX shipped. -***** Phase 5: Coverage and AI -- Connect coverage commands to adapter capabilities. -- Add failure summarization with redaction. -- Add coverage-gap summarization. +*Deliverables:* +- Add =linear= and =notion= back to =cj/mcp-enabled-servers=. +- Doctor gains live-auth-check mode (=C-u C-; a C d=): invokes a single safe read per auth class to verify OAuth tokens haven't silently expired. Static checks first; live probe only fires after static passes. +- OAuth recovery pattern matcher surfaces auth URLs in =cj/mcp-status= on first connect. -**** Acceptance Criteria For First Fix-Up Pass -- Existing ERT workflow still works. -- F6 and =C-; t= use the same underlying runner API. -- Current-file test command generation is covered for Elisp, Python, Go, - TypeScript, and JavaScript. -- At least one isolated ERT command path exists. -- Path containment checks are robust against sibling-prefix paths and symlinks. -- Runner requests and results are represented as data, not only messages. -- Missing runner/tool errors are clear and actionable. -- Tests cover adapter detection, command building, scope resolution, result - storage, and key interactive paths. +*Exit:* first connect surfaces the OAuth URL through the recovery pattern; after browser handshake completes, subsequent connects succeed without prompt; live-auth-check correctly identifies a deliberately revoked token; both servers appear ready in the audit buffer. -** DONE [#B] jumper: register collisions and dead-marker errors :bug:solo: -CLOSED: [2026-06-22 Mon] -:PROPERTIES: -:LAST_REVIEWED: 2026-06-13 -:END: -Fixed 2026-06-22: (1) store now allocates the first unused register char in the live slice (=jumper--first-free-register=) instead of by next-index, and removal clears the freed register, so a store after a removal no longer overwrites a surviving slot's marker; (2) =jumper--with-marker-at= guards =(buffer-live-p (marker-buffer marker))= so killed-buffer entries are skipped instead of signaling wrong-type errors; (3) the single-location toggle jumps back to the last-location register when set (returns =jumped-back=). New =test-jumper--register-hygiene.el= (8 tests); all 42 jumper tests green. Pre-existing unused-lexical =i= warning in =jumper--location-exists-p= left alone (separate nit). -Two related defects from the 2026-06 config audit: -- =modules/jumper.el:155= — removal shifts the vector without renumbering registers, so a later store allocates a register still held by a surviving location and silently overwrites it. Allocate the first free register char in the live slice; =set-register nil= on removal so freed markers don't pin buffers. -- =modules/jumper.el:117,132= — guards check =(markerp marker)= but not =(buffer-live-p (marker-buffer marker))=; after killing a buffer holding a location, M-SPC SPC and M-SPC j signal wrong-type errors. Treat dead entries as skippable/removable. -Also =jumper.el:178= — the promised single-location toggle never toggles back ('already-there branch should =jump-to-register= z when set). +**** TODO [#B] Phase 7 -- Env-dependent stdio servers (figma, google-*) -** TODO [#B] Keymap consolidation — resolve decisions, run Phase 1-2 :feature:refactor:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-13 -:END: -Spec: [[id:540bf06b-16b8-46c6-b459-c40d1b9c795d][keybinding-console-safety-spec-doing.org]]. Phase 0 (revert 4a1ecf64) is done and pushed. Decisions D1-D5 are open TODOs in the spec; D2/D4/D5 gate the primary work (Phase 1 prune via Appendix D, Phase 2 consolidate + retire the translation block), while D1/D3 (the console-safe prefix) gate only the optional Phase 3 and can stay open indefinitely. Resolve D2/D4/D5, then run Phase 1-2. Appendix D is the keybinding pruning checklist. Add a =#+TODO: TODO | DONE SUPERSEDED CANCELLED= header line to the spec if adopting those decision keywords (rulesets convention update, 2026-06-12). +*Goal:* add the remaining five env-dependent servers. -** TODO [#B] ledger-config is orphaned — ledger-mode never configured :bug:quick: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Nothing requires =modules/ledger-config.el= (verified by grep), so .dat/.ledger/.journal open without ledger-mode, reports, or flycheck-ledger. The module looks finished, not staged (unlike duet-config, which documents its pre-alpha orphaning). Decide: wire into init.el (+ =cj/executable-find-or-warn= for the ledger binary) or delete. From the 2026-06 config audit. +*Entry:* Phase 6 HTTP servers connect cleanly. -** TODO [#C] buffer-differs save prompt: 4-way yes/no/diff/cancel :feature:next: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -The "buffer differs from file" confirmation currently gives only yes/no. Craig wants a 4-way choice with explicit consequences: yes (be explicit it overwrites), no (be explicit it discards this action and continues), diff (show a graphical difftastic diff, then return to this prompt), cancel (stop the action, leave the buffer untouched). Needs the exact prompt identified first (which save/overwrite path raises "buffer differs") and a design for the diff-then-return loop. difftastic + cj/diff-buffer-with-file infrastructure already exist. From the roam inbox 2026-06-16. -** TODO [#C] emacs: tag tasks by module name for sorting :refactor:studio: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Replace topic tagging with single-word module tags: :studio: for everything under scripts/theme-studio/, module-named tags elsewhere, :multi: for cross-area work. Drop bug/enhancement-style tags since work should be chosen on other bases. This changes the current six-tag convention, so update the priority-scheme section to document it, rewrite the task-audit workflow to reconcile tasks against the module scheme, then run the audit. Queue for end of session. From the roam inbox. -** TODO [#C] Build an Org-native API workspace :feature:test: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: +*Deliverables:* +- Add =figma=, =google-calendar=, =google-docs-personal=, =google-docs-work=, =google-keep= to =cj/mcp-enabled-servers=. +- Verify env-merge from =~/.claude.json= for each (the mtime-cached reader from Phase 1). +- Verify figma's =:secret-args= splicing places the API key correctly without echoing it. +- Manual smoke: simulate token expiry on one Google server; recovery message points at "re-auth via Claude Code, then C-; a C r SERVER". -Build an Emacs-native API workspace layer that keeps =restclient.el= useful for -lightweight request execution while adding OpenAPI import, Org notebooks, -response capture, inline images, and =gptel=-assisted API documentation. +*Exit:* all 9 servers reach =ready= state on a clean machine. Sentinel-grep check across status / audit / hub / errors / audit-log shows zero secret leakage. Doctor's live-auth covers each auth class (oauth, token, args-token, in-protocol, local, none). -*** Spec +**** TODO [#B] Phase 8 -- Privacy + audit polish -**** Summary -Build a small Emacs API-workspace layer that keeps =restclient.el= as the -plain-text request executor, while adding higher-level discovery, generation, -Org notebook, response handling, and =gptel=-assisted documentation workflows. +*Goal:* land the final UX polish and documentation. -The intended result is not a Postman clone. It should feel like an -Emacs-native API lab: -- generate request collections from OpenAPI/Swagger specs -- browse and execute requests from =.rest= files or Org notebooks -- save useful responses back into Org -- display image responses inline -- use =gptel= to explain APIs, endpoints, request bodies, and responses -- leave room for =verb.el= or Hurl where they are a better fit +*Entry:* all 9 servers working. -**** Goals -- Preserve the current lightweight =restclient.el= workflow for ad-hoc calls. -- Add an OpenAPI importer that can generate useful first-draft request files. -- Add an Org workspace format for API notes, executable request blocks, results, - response links, and generated summaries. -- Add response post-processing helpers for JSON, binary/image data, and model - summaries. -- Make common auth flows easy to scaffold without storing secrets in generated - files. -- Keep generated artifacts readable and editable by hand. -- Keep implementation modular enough that =verb.el= can be evaluated as a richer - Org-native frontend. +*Deliverables:* +- Audit buffer privacy header: "Tool results land in =gptel-tools= responses; saved conversations persist them. Use =cj/gptel-autosave-toggle= per buffer to opt out." +- =cj/mcp-tool-audit-log-enabled= defcustom + log writer (=~/.emacs.d/data/mcp-tool-log/YYYY-MM-DD.log= -- metadata only, one line per call, daily rotation). +- =ai-mcp.el= commentary updated with the code-organization outline as a table of contents. +- Final pass on tests covering saved-conversation behavior (autosave persists MCP tool results; toggling off prevents persistence). -**** Non-Goals -- Do not build a full graphical API client. -- Do not store secrets directly in Org or =.rest= files. -- Do not attempt complete OpenAPI 3.1 schema synthesis in the first pass. -- Do not require =gptel= for ordinary request execution. -- Do not make Hurl a runtime dependency for the restclient workflow. +*Exit:* all 10 acceptance criteria from the spec pass. Manual matrix run end-to-end on a fresh Emacs. Working tree clean. -**** Primary User Flows -***** Import An API -1. User runs =cj/restclient-import-openapi=. -2. Command prompts for a URL or local OpenAPI/Swagger file. -3. Command parses the spec into normalized endpoint records. -4. Command prompts for output format: - - =restclient= request collection - - Org API workspace - - both -5. Command writes generated files under a project/API workspace directory. -6. Generated file includes host variables, auth placeholders, request examples, - and a short summary of how to start using the collection. +*** TODO [#C] Wrap the gh CLI as a GPTel tool -***** Describe An API -1. User runs =cj/restclient-describe-api= from a generated workspace or spec file. -2. Command extracts API metadata, paths, operations, schemas, auth, and tags. -3. Command sends a bounded summary payload to =gptel=. -4. Result is inserted under an Org =Overview= subtree. +**** 2026-05-16 Sat @ 16:20:00 -0500 Spec -***** Execute And Capture A Request -1. User executes a request via =restclient.el= or =ob-restclient=. -2. Command captures response status, headers, content type, body, and timestamp - when available. -3. JSON/XML responses can be inserted as source blocks or summarized. -4. Image responses are saved to an assets directory and linked inline in Org. -5. Binary responses that are not image-like are saved as file links. +Design doc: [[id:a124dd0f-1f40-4533-aeb8-595d93e20865][docs/specs/gptel-gh-tool-spec.org]] -***** Iterate On A Response -1. User runs helper commands against the last response: - - pretty-print JSON/XML - - run =jq= - - summarize with =gptel= - - extract a value into a restclient variable - - save body to a file -2. The result is inserted near the endpoint subtree or shown in a temporary - buffer depending on command prefix/options. +*** TODO [#C] GPTel should autosave regularly after a conversation is saved +*** TODO [#B] Org Workflow Related Tools -**** Proposed Modules -***** =modules/restclient-workspace.el= -Main configuration and user-facing commands. Owns keybindings, workspace -creation, dispatch commands, and integration with existing restclient config. +Affordances that expose the Org workspace -- agenda state, capture +targets, org-roam nodes and backlinks, dailies, drill review state -- +to the agent as structured context, not raw .org buffer text. -***** =modules/restclient-openapi.el= -OpenAPI/Swagger loading and normalization: -- fetch URL or read file -- parse JSON/YAML where available -- normalize servers, paths, methods, parameters, request bodies, auth schemes, - tags, operation IDs, and examples -- expose pure helper functions suitable for unit tests +**** TODO [#B] Agenda state tools :feature: -***** =modules/restclient-generate.el= -Generation layer: -- render =.rest= / =.http= request collections -- render Org workspaces -- synthesize simple JSON request bodies from schemas/examples -- generate variables and auth placeholders +Read scheduled / deadline / waiting tasks for a date range; query by +tag, priority, or TODO keyword; list what's blocking today. Lets the +agent answer "what's on the critical path this week" without me +pasting agenda output, and feeds the daily-prep / wrap-up workflows. -***** =modules/restclient-response.el= -Response helpers: -- identify content type -- save binary/image bodies -- insert Org links -- display inline images -- route JSON/XML/text handling -- track last response metadata +**** TODO [#B] Org-roam node tools :feature: -***** =modules/restclient-ai.el= -=gptel= integration: -- summarize API specs -- explain endpoint behavior -- generate example payload notes -- summarize responses -- keep prompts bounded and avoid sending secrets +Resolve a topic to its node; return body + backlinks; list nodes by +tag; surface dailies for a date range. Lets the agent reason over +the personal knowledge graph and write back into it via the capture +tools below. -**** File And Workspace Layout -Default generated workspace: +**** TODO [#B] Capture creation tools :feature: -#+begin_src text -data/apis/<api-slug>/ - <api-slug>.rest - <api-slug>.org - openapi.json - assets/ - responses/ -#+end_src +Drive =org-capture= from a template key + body string. Lets the +agent file inbox items, reading notes, journal entries, or roam +nodes without me leaving the chat. Tight pairing with the +=cj/org-capture= optimization task in todo.org. -The exact root should be configurable, defaulting to the existing REST data -directory if one is already present in the config. +**** TODO [#B] Org-drill review tools :feature: -**** Org Workspace Shape -#+begin_example -,* API Name -:PROPERTIES: -:OPENAPI_SOURCE: https://example.com/openapi.json -:BASE_URL: https://api.example.com -:END: +Surface next-due drill cards in =drill-dir=; let the agent quiz on a +topic and report performance. Useful for prompted recall sessions +("ask me five medical-Spanish cards") and for "did this card stick" +analysis. -,** Overview -Generated or user-written API notes. +*** TODO [#B] Git Related Tools -,** Auth -Token acquisition notes and placeholders. No secrets stored here. +Affordances that expose magit's structured view of a repo -- sections, +staged-vs-unstaged, commit metadata, rebase / conflict state -- as +first-class tools rather than asking the model to reason over raw +diff text. -,** Endpoints -,*** GET /users -:PROPERTIES: -:OPERATION_ID: listUsers -:METHOD: GET -:PATH: /users -:END: +**** TODO [#B] Section-aware git tools :feature: -#+begin_src restclient :results raw -GET :host/users -Authorization: Bearer :token -Accept: application/json -#+end_src +Expose Magit sections as first-class GPTel tools: current section type, +heading, file, hunk range, and content; sibling sections under the same +file; staged / unstaged / untracked status; commit metadata around the +selected commit or branch; the exact staged patch that would be +committed. Lets prompts say "review the file section at point" or +"explain this hunk in the context of adjacent hunks" without manual +context-copying. -,**** Notes -,**** Responses -#+end_example +**** TODO [#B] Commit intent workbench :feature: -**** Commands -- =cj/restclient-new-scratch= :: open a scratch =restclient-mode= buffer. -- =cj/restclient-open-file= :: open a REST file from the configured API data dir. -- =cj/restclient-import-openapi= :: generate a workspace from OpenAPI/Swagger. -- =cj/restclient-describe-api= :: insert a =gptel=-generated API overview. -- =cj/restclient-describe-endpoint= :: explain the endpoint at point. -- =cj/restclient-generate-example-body= :: generate or refresh sample JSON body. -- =cj/restclient-save-last-response= :: save response body and metadata. -- =cj/restclient-insert-last-response-org= :: insert response under Org subtree. -- =cj/restclient-display-image-response= :: save and display image response. -- =cj/restclient-response-jq= :: run =jq= against the last JSON response. -- =cj/restclient-copy-curl= :: copy the request at point as curl if supported. +Transient that builds a commit intentionally: +1. Agent reads unstaged + staged changes. +2. Agent proposes coherent commit groups. +3. User selects groups in a Magit-style buffer. +4. Agent stages those paths or hunks only after confirmation. +5. Agent generates a message reflecting the selected intent. -**** Keybindings -Keep the existing prefix shape under =C-; R=: -- =C-; R n= :: new scratch request buffer -- =C-; R o= :: open REST file -- =C-; R i= :: import OpenAPI/Swagger -- =C-; R d= :: describe API or endpoint -- =C-; R s= :: save/capture last response -- =C-; R j= :: run =jq= on last response -- =C-; R m= :: transient menu for workspace commands +Addresses the common case of two or three unrelated edits in one +working tree -- a single commit-message generator can't handle that +cleanly. -**** OpenAPI Import Details -Minimum first-pass support: -- OpenAPI 3.x JSON -- Swagger 2.0 JSON if easy to normalize -- YAML via available Emacs YAML library or external converter if already present -- =servers= / =host= + =basePath= -- path-level and operation-level parameters -- query/path/header parameters -- JSON request bodies -- examples and default schema values -- security schemes: - - HTTP bearer - - basic - - API key header - - API key query +**** TODO [#B] Patch narrative buffer :feature: + +Generate an Org buffer that explains a change set as a reviewable +narrative: +- "What changed" by subsystem. +- "Why it appears to have changed" inferred from names, tests, and docs. +- "Risk areas" with links back to Magit file sections. +- "Suggested verification" using local Makefile targets when present. + +Reusable artifact: paste into a PR description, save with an AI +session, or file into org-roam. + +**** TODO [#B] Review-thread simulator :feature: + +Before opening a PR, create a local review buffer with inline comments +attached to Magit diff positions. The agent writes comments as if +reviewing someone else's patch: +- Comments grouped by severity. +- Each comment links to file and line. +- Resolved comments check off in Org. +- Accepted suggestions apply through the existing text-update tools. -First pass can skip or mark as unsupported: -- polymorphic schemas beyond simple =oneOf= / =anyOf= note generation -- multipart body generation -- full OAuth flows -- callbacks/webhooks -- complete response schema rendering +Makes "review my diff" less ephemeral and avoids losing useful findings +inside a chat transcript. -**** Secret Handling -- Generated files must use placeholders like =:token=, =:api-key=, or - =:basic-auth=. -- Do not write tokens into generated files. -- Prefer variables loaded from auth-source, environment variables, or manually - entered restclient variables. -- =gptel= prompts must strip obvious auth headers and secret-like values from - request/response payloads before sending context. +**** TODO [#B] Rebase and conflict coach :feature: -**** Response Handling -- Text JSON/XML/HTML/plain responses may be inserted into Org as source blocks. -- JSON responses should support optional =jq= filters. -- Image responses should be saved under =assets/responses/= and inserted as Org - file links. -- After inserting image links, call =org-display-inline-images= when in Org. -- Large responses should be saved as files and linked rather than inserted. -- Binary non-image responses should be saved and linked with content type notes. +When Magit enters a rebase, cherry-pick, merge, or conflict state, +expose an agent command that reads: +- Git operation state from =.git/=. +- Conflict markers in the worktree. +- Relevant commits from =git log --merge= or the rebase todo. +- The current Magit status sections. -**** Integration Choices To Evaluate -- =restclient.el= remains the default executor for =.rest= files. -- =ob-restclient= powers executable Org source blocks. -- =verb.el= should be evaluated as an alternate frontend for Org-native API - workspaces because it already has tree inheritance, embedded Elisp, and image - response display. -- Hurl should be evaluated as an export/test target, especially for chained - request tests and CI assertions. +The agent explains the conflict in domain terms and proposes a +resolution patch; the actual edit and =git add= stay under explicit +user control. -**** Testing Strategy -- Unit-test OpenAPI normalization with small fixture specs. -- Unit-test request generation for GET, POST, auth, query params, path params, - and request-body examples. -- Unit-test secret redaction before =gptel= calls. -- Unit-test response classification and Org insertion helpers. -- Integration-test generated =.rest= files for representative APIs. -- Integration-test generated Org workspaces with =ob-restclient= where feasible. -- Avoid live network tests by default; use fixtures/stubs unless explicitly - tagged =:network=. +**** TODO [#B] Regression archaeology :feature: -**** First Milestone -1. Keep/verify existing restclient scratch/open commands. -2. Add a tiny OpenAPI JSON parser/normalizer for a fixture spec. -3. Generate a readable =.rest= collection with variables and examples. -4. Generate a matching Org workspace. -5. Add response save/link helpers for JSON and images. -6. Add a =gptel= API-summary command with secret redaction. -7. Add focused unit tests and one sample fixture. +Magit transient that runs a bisect-like reasoning workflow: +- Ask for a symptom and a known-good / known-bad range. +- Summarize candidate commits in small batches. +- Use tests or user-provided repro commands when available. +- Maintain a bisect journal in an Org buffer. -**** Open Questions -- Should the canonical workspace be =.rest= first, Org first, or generated in - both formats by default? -- Is =verb.el= a better primary target than =ob-restclient= for the Org notebook - experience? -- Which YAML parser should be used if no YAML package is already configured? -- Where should API workspaces live by default: =data/=, =docs/=, or project root? -- Should response capture hook into restclient internals, or should capture be a - separate explicit command operating on response buffers? -- How much schema synthesis is useful before it becomes noisy? +Even when the agent can't run the whole bisect, it keeps the +investigation structured and preserves why each commit was judged +good or bad. -*** Ideas -- Treat =restclient.el= as the lightweight request scratchpad, and layer richer workflow commands around it instead of trying to turn it into Postman. -- Add an OpenAPI/Swagger importer: - - prompt for a spec URL or local file - - parse paths, methods, auth schemes, request bodies, and examples - - generate a =.http= / =.rest= request collection - - optionally generate an Org notebook with one subtree per endpoint -- Add an API description command using =gptel=: - - summarize the API from an OpenAPI spec - - explain each endpoint, auth requirement, parameters, and response shape - - write the summary into the generated Org workspace -- Generate example requests automatically: - - =GET= examples with query params - - =POST= / =PUT= / =PATCH= examples with sample JSON bodies - - =DELETE= examples with safe placeholder IDs - - shared variables like =:host=, =:token=, =:api-version=, =:tenant= -- Add auth helpers: - - bearer token insertion - - basic auth - - API key header/query param - - OAuth token fetch request template -- Improve Org integration: - - use =ob-restclient= for executable API notebooks - - support =:jq= filters for clean JSON results - - save response bodies under endpoint subtrees - - capture request/response metadata as Org properties -- Handle images and binary responses: - - detect image =Content-Type= - - save response data into an assets directory - - insert =[[file:...]]= links into Org - - call =org-display-inline-images= after execution -- Add response-processing commands: - - pretty-print JSON/XML - - run =jq= against the last response - - summarize response with =gptel= - - extract fields into restclient variables for follow-up calls -- Add request collection ergonomics: - - imenu/consult navigation by endpoint - - transient menu for send/copy curl/jq/save response - - templates for common headers - - per-project API workspace discovery -- Investigate =verb.el= as the richer Org-native frontend: - - Org tree inheritance for host/header/auth defaults - - embedded Elisp in request specs - - built-in display of image/PDF/SVG responses - - likely better base for a notebook-style API client -- Investigate Hurl for repeatable API tests: - - request chaining - - captures - - assertions - - CI-friendly execution - - possible export target from generated API workspaces +**** TODO [#B] Messaging Related Tools -*** Original Goals -**** Keybindings to test -- C-; R n — new scratch *restclient* buffer (should open in restclient-mode) -- C-; R o — open .rest file (should default to data/ directory) +Affordances over mu4e, Slack, Telegram, and ERC. Same shape across +protocols: read recent threads, search by sender / topic, compose a +draft from a prompt + thread context, leave the send under explicit +user control. -**** Functional tests -1. Open tutorial-api.rest, run JSONPlaceholder GET (C-c C-c) — verify response inline -2. Run POST example — verify 201 response with fake ID -3. Run httpbin header echo — verify custom headers echoed back -4. Navigate between requests with C-c C-n / C-c C-p -5. Test jq filtering (requires jq installed): restclient-jq loaded? -6. Open scratch buffer (C-; R n), type a request manually, execute -7. which-key shows "REST client" menu under C-; R - -** TODO [#C] Build debug-profiling.el module :feature:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: +***** TODO [#B] Mu4e thread and compose tools :feature: -Reusable profiling infrastructure for targeted slow-command investigation. Consolidates scattered profiler bindings (currently in =modules/config-utilities.el=) and adds two pure-helper-backed entry points: "profile next command" and "time region or sexp." Designed via =/brainstorm= 2026-04-26. +Read the message at point and surrounding thread (with attachments +summarized); query the inbox by =from:= / =subject:= / date range; +compose a draft from a prompt + thread context using =org-msg=. +Pairs with the existing =mu4e-org-contacts-integration.el=. -Design: [[id:c713b431-ae14-498d-aba9-b84d52f981b6][docs/specs/debug-profiling-spec.org]] +***** TODO [#B] Slack thread and compose tools :feature: -Implement via =/start-work= against the design — branch =feat/debug-profiling=, commits decomposed along the test-first split-for-testability boundary. Once shipped, use it as the v1 exercise on the queued [#B] org-capture target-building investigation. +Read channel / DM / thread history through =emacs-slack=; search by +user or channel; compose a draft message but leave sending to me. +Mirrors the mu4e shape so the agent's interface is uniform across +messaging protocols. -** TODO [#C] Evaluate jamescherti essential-emacs-packages list :quick:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Review [[https://www.jamescherti.com/essential-emacs-packages/][James Cherti's essential Emacs packages]] for anything worth installing. Cross-check each candidate against what is already in the config (=modules/= + =init.el=), skip the ones already present, and shortlist the genuinely new ones with a one-line rationale. Future-installation research, not a commitment to install. +***** TODO [#B] Telegram and IRC read tools :feature: -** TODO [#C] Extend F2 "preview" convention across modes :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: +Same shape as Slack for =telega= (Telegram) and =erc= (IRC): +recent-message reads, search, and draft compose. Bundled because +the API shape is identical even if the underlying clients differ. -F2 is the universal preview key. Currently bound only in markdown-mode (markdown-preview, in =modules/markdown-config.el=). Org-reveal lives on =C-; o R= via =cj/org-map=, not F2. Extend F2 to other modes where a "preview" action is natural: +***** TODO [#B] Contact resolution tools :feature: -- Hugo blog (hugo-config.el) — preview the post in browser -- HTML / web-mode — open in browser -- Reveal presentations - preview in browser -- Any other mode with a natural "preview this" action +Resolve a name to email / Slack ID / Telegram handle via +=org-contacts= and the configured address books. Removes the +"who's this person again" friction from the compose flows above. -Keep the binding mode-local so F2 stays available as a global candidate where no preview makes sense. +**** TODO [#B] File and Buffer Related Tools -** TODO [#C] face-diagnostic: face-name buttons + header allowlist :feature:quick:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Two v1 follow-ups on the shipped face/font diagnostic: render the face names in the report as buttons that call describe-face (the spec's "For the user" buttons; v1 shows them as plain text), and add face-diagnostic to the module-header allowlist in tests/test-init-module-headers.el now that it's required in init.el. Spec: [[id:98f065cf-8bd5-46a0-ac24-da94d66855ad][face-font-diagnostic-popup-spec-implemented.org]]. -** TODO [#C] Gold text in auto-dimmed buffers :bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Some auto-dimmed document buffers render text in gold; source unknown. Likely a face-remapping or overlay interaction with the theme. Blocked on the face/font diagnostic tool above for diagnosis. From the roam inbox. -** TODO [#C] Google Contacts ↔ org-contacts sync investigation :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -From the 2026-06-11 brainstorm. Goal: keep [[file:~/sync/org/contacts.org][contacts.org]] (real org-contacts: PROPERTIES drawers, mu4e completion, org-roam links) in sync with Google Contacts. Google side is solid — official People API (OAuth2, incremental syncToken) or CardDAV; no ToS risk. The hard parts are local: (1) identity — entries have no UID, so two-way needs a GOOGLE_ID property per entry plus a one-time fuzzy reconciliation of the two populated datasets (name/email/phone matching); (2) field mapping — space-separated multi-email in one property, free-text body notes, inconsistent phone formats (normalization decision); (3) conflict policy. First decision gates the rest: one-way Google→org read model (simple) vs true two-way. Candidate architectures: vdirsyncer (proven two-way engine w/ Google support; build only the vCard↔org translation, evaluate org-vcard fidelity) vs a direct People API script with sync state in org properties. Output: recommendation doc in docs/design/ naming direction + the normalization/conflict decisions for Craig. Not :solo: — the one-way-vs-two-way call and normalization policy are Craig's. +Affordances that expose the user's actual workspace -- open buffers, +narrowed regions, marked files, vterm / eshell sessions -- as +structured context. Stops the model from asking "what file are you +looking at" or "what region is selected." -** TODO [#C] Google Voice in Emacs — SMS + dialer investigation :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -From the 2026-06-11 messenger-unification brainstorm. Google Voice has no official API; the viable routes ride the Matrix bridge ecosystem's reverse engineering (mautrix-gvoice). Research pass to establish the 2026 state of play: (1) is mautrix-gvoice healthy and what does its auth flow look like now; (2) any better-maintained alternative (CLI/daemon) for the signel-pattern architecture (external daemon + JSON-RPC + thin Emacs chat client); (3) does call initiation (ring-linked-phone-then-connect, Emacs as dialer) survive in the current protocol — two-way audio in Emacs is out of scope (WebRTC); (4) ToS/account-flag risk assessment for Craig's account. Output: a recommendation doc in docs/design/ naming the architecture (signel-pattern daemon vs Matrix bridge + ement.el) or a no-go with reasons. If go, GV becomes a registered backend under the messenger-unification convention (see the [#B] task below). +***** TODO [#B] Buffer state tools :feature: -** TODO [#C] latexmk workflow never activates (two breaks) :bug:quick:solo: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -=modules/latex-config.el:66= — =:hook (TeX-mode-hook . ...)= gets use-package's =-hook= suffix appended (unbound symbol not ending in =-mode=), registering on nonexistent =TeX-mode-hook-hook=, so =TeX-command-default "latexmk"= is never set. Independently =:80= auctex-latexmk is =:defer t= with no trigger, so =auctex-latexmk-setup= never runs and "latexmk" isn't in TeX-command-list. Fix hook name to =TeX-mode=; change auctex-latexmk to =:after tex=. From the 2026-06 config audit. +List visible buffers with major-mode + file (when any); read the +narrowed region instead of the whole buffer; report point + mark +positions and the active region's text. The single most-asked +question between turns becomes a tool call. -** TODO [#C] Org-noter custom workflow — fix and finish :feature:bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: +***** TODO [#B] Dirvish / Dired tools :feature: -Continue debugging and testing the custom org-noter workflow from 2025-11-21 session. -This is partially implemented but has known issues that need fixing before it's usable. +Read marked files, sort state, and filter state from a Dired or +Dirvish buffer. Lets the agent operate on "the files I just marked" +rather than "files in this directory" -- a real distinction in any +review or refactor workflow. -*Last worked on:* 2025-11-21 -*Current status:* Implementation complete but has bugs, needs testing +***** TODO [#B] Vterm session tools :feature: -*Known issues to fix:* +Recent command output from a named vterm session; scroll-history +search. Pairs naturally with the =ai-vterm= design: the agent +running in one project's vterm can read another project's vterm +without leaving the chat. + +***** TODO [#B] Eshell session tools :feature: + +Same shape as the vterm tools for =eshell= sessions -- last-command +output, history search, current directory. Most useful for +agent-driven inspection of long-running pipelines. + +**** TODO [#B] Filesystem Related Tools + +Affordances that let the agent operate on actual files on disk and +run common CLI utilities -- pandoc, ffmpeg, imagemagick, ripgrep, +fd, jq -- rather than relying on me to paste content or run +commands by hand. -1. /Double notes buffer appearing when pressing 'i' to insert note/ - - When user presses 'i' in document to insert a note, two notes buffers appear - - Expected: single notes buffer appears - - Need to debug why the insert-note function is creating duplicate buffers +*Design tension to resolve before any of these ship: one tool per +utility, or one generic =run_shell_command=?* -2. /Toggle behavior refinement needed/ - - The toggle between document and notes needs refinement - - May have edge cases with window management - - Need to test various scenarios +The shortlist's first pass DEFERRED a generic =run_shell_command=: +sandboxing to HOME + /tmp with a denylist for destructive ops is +straightforward, but the denylist can never be exhaustive, and +"confirmation for everything else" becomes click-fatigue. -*Testing needed:* +The children below take the other path -- *one gptel tool per +binary*, with a strictly-typed argv shape (e.g. +=pandoc_convert(input_path, output_format)=, not +=pandoc_convert(args_string)=). Each tool: -1. /EPUB files/ - Test with EPUB documents (primary use case) -2. /Reopening existing notes/ - Verify it works when notes file already exists -3. /Starting from notes file/ - Test opening document from an existing notes file -4. /PDF files/ - Verify compatibility with PDF workflow -5. /Edge cases:/ - - Multiple windows open - - Splitting behavior - - Window focus after operations +- Validates its own paths (must be under HOME, outputs in a + sandboxed dir). +- Rejects dangerous flags explicitly (pandoc =--filter=, ffmpeg's + =-protocol_whitelist= chicanery, imagemagick's policy bypasses). +- Runs via =call-process= with an argv list -- no shell parsing, + no string-interpolation injection. +- Caps output and reports truncation inline. -*Implementation files:* -- =modules/org-noter-config.el= - Custom workflow implementation -- Contains custom functions for document/notes toggling and insertion +The trade-off is breadth: every new CLI tool means a new gptel tool +file. Acceptable because (a) the list of utilities I actually need +agent access to is small (~8 below covers most of it), and (b) each +wrapper gets type-checked argv and a focused description the model +can reason over, which is genuinely better than a free-form +=run_shell_command(string)=. -*Context:* -This custom workflow is designed to make org-noter more ergonomic for Craig's reading/annotation -workflow. It simplifies the toggle between document and notes, and streamlines note insertion. -The core functionality is implemented but needs debugging before it's production-ready. +The =eshell_submit= entry at the end is the escape hatch for one- +off needs the wrappers don't cover -- =:confirm t= always. -**Next Steps:** -1. Debug the double buffer issue when pressing 'i' -2. Test all scenarios listed above -3. Refine toggle behavior based on testing -4. Document the final keybindings and workflow +Adjacent categories: the existing =gptel-tools/= file CRUD +(=read_text_file=, =write_text_file=, =update_text_file=, +=list_directory_files=, =move_to_trash=) is the foundation this +category extends. =web_fetch= is the network-fetch counterpart. -** TODO [#C] Pick and wire a debug backend for F5 :feature: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: +***** TODO [#B] Document conversion (pandoc) :feature: -#+begin_src emacs-lisp - Give me an idea of the amount of work and complexity and what allows for a consistent UX across languages. -#+end_src +Convert between markdown, org, html, pdf, docx, latex, epub, plain +text. Most common use: "extract this docx to markdown so I can +read it inline." Strict argv: input path, output format, optional +output path. Reject =--filter= and =--lua-filter= (arbitrary code +execution). Output written to a sandbox dir unless explicit +override. -*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals -Bind F5 globally to a debug entry point. Backend choice is the hard part: +***** TODO [#B] Image manipulation (imagemagick) :feature: -- dape (Debug Adapter Protocol for Emacs) — modern, multi-language via DAP. Single UX across Python, Go, TS, Rust, etc. Less mature than DAP clients in other editors. -- realgud — wraps multiple debuggers (pdb, gdb, node --inspect, etc.). More mature; UX varies by backend. -- Language-specific stacks — dap-mode (python-mode + dap), delve for go, ts-node --inspect, etc. Best per-language UX; most config work. +Resize, format-convert, get-metadata (=identify=), optionally crop / +rotate / annotate. Common use: "resize this PNG to a thumbnail" or +"convert these HEICs to JPEGs." Strict argv per operation. +Reject pre-validated dangerous formats (the historical EXR / SVG / +MVG CVE surface) unless explicitly enabled. ImageMagick's +=policy.xml= is the underlying defense; the wrapper enforces it at +the tool boundary too. -F5 itself will be simple (start/resume debug). Likely modifier variants once the backend is picked: -- C-F5 toggle breakpoint at point -- M-F5 eval expression in debug context (or step-over shortcut) +***** TODO [#B] Audio / video processing (ffmpeg) :feature: -Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip. +Trim, transcode, extract audio, get-metadata (=ffprobe=). Paths +under HOME only; reject network-protocol inputs (=http:= / =rtmp:= +/ =rtsp:=) so the model can't pull from arbitrary sources. Pairs +with the existing transcription module -- the same "extract audio +from video" path =cj/transcribe-media= uses internally. -Do this after the F-key rework ticket ships so F5 is the only hole left. +***** TODO [#B] Content search (ripgrep) :feature: -** TODO [#C] Review and rebind M-S- keybindings :refactor: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: +=rg= wrapper with path / glob filtering, result-count cap, optional +literal-vs-regex mode. Pure read. Was in the shortlist's ADOPT +bucket as =search_in_files=. Highest-leverage filesystem tool by +expected call frequency -- "where in this repo is X" is the +question I paste agent output for most often. -Changed from M-uppercase to M-S-lowercase for terminal compatibility. -These may override useful defaults - review and pick better bindings: -- M-S-b calibredb (was overriding backward-word) -- M-S-c time-zones (was overriding capitalize-word) -- M-S-d dwim-shell-menu (was overriding kill-word) -- M-S-e eww (was overriding forward-sentence) -- M-S-f fontaine (was overriding forward-word) -- M-S-h split-below -- M-S-i edit-indirect -- M-S-k show-kill-ring (was overriding kill-sentence) -- M-S-l switch-themes (was overriding downcase-word) -- M-S-m kill-all-buffers -- M-S-o kill-other-window -- M-S-r elfeed -- M-S-s window-swap -- M-S-t toggle-split (was overriding transpose-words) -- M-S-u winner-undo (was overriding upcase-word) -- M-S-v split-right (was overriding scroll-down) -- M-S-w wttrin (was overriding kill-ring-save) -- M-S-y yank-media (was overriding yank-pop) -- M-S-z undo-kill-buffer (was overriding zap-to-char) +***** TODO [#B] File discovery (fd) :feature: -** TODO [#C] Slack message buffers in a reused popup window :quick: -:PROPERTIES: -:LAST_REVIEWED: 2026-06-21 -:END: -Display slack.el message and thread buffers in a dedicated popup window (side or bottom) and reuse that one window instead of spawning a new window per buffer. Likely a =display-buffer-alist= rule (or popper integration) in =modules/slack-config.el=. +=fd= (or =find= fallback) wrapper, capped result count. Pure +read, lower stakes than =search_in_files= (filenames only, no +content). Common pairing: =find_file_by_name= then +=read_text_file=. -** CANCELLED [#C] the preview splits an already split window into 3 temporarily. :bug: -CLOSED: [2026-06-21 Sun] -looks strange. potentially problematic for ai-terms. +***** TODO [#B] Metadata extraction (file / exiftool) :feature: -** CANCELLED [#C] TRAMP/dirvish "?" for remote dates — verify the fix per host :bug: -CLOSED: [2026-06-21 Sun] -:PROPERTIES: -:LAST_REVIEWED: 2026-06-02 -:END: +=file= for MIME-type detection; =exiftool= for image / video / +audio metadata. Lets the agent answer "what is this file" or +"when was this photo taken" without me opening external tools. +Pure read. -Root cause is traced (see the dated investigation entry below). What's left needs a live remote: open each remote host in dirvish and run the three diagnostic evals to find which gate is closed, then close it. +***** TODO [#B] Structured data processing (jq / yq) :feature: -Diagnostics (run with point in a remote dirvish buffer): -- =M-: (dirvish-prop :remote-async)= — nil means =tramp-direct-async-process-p= is failing for this method/host, so dirvish's remote attribute fetch never runs. -- =M-: (dirvish-prop :gnuls)= — nil means the remote has no GNU =ls= (the =ls --version= probe failed), so the parser gate stays shut. Likely on truenas (FreeBSD). -- =M-: (tramp-direct-async-process-p)= — confirms whether direct-async is actually active for the connection. +=jq= for JSON, =yq= for YAML / TOML. Filter / project / transform +structured data into a smaller, more focused view before reading. +Strictly read-only -- output goes to the chat, not to disk. The +agent often wants "the third element of .results" from a JSON file +and this is much cheaper than pasting the whole thing. -Likely fixes, by which gate is closed: -- =:gnuls= nil → install GNU coreutils on the remote (FreeBSD: =pkg install coreutils=) and make =ls= resolve to GNU on the TRAMP path, or accept "?" on that host. +***** TODO [#B] Eshell command submission :feature: - - Constraint: nothing gets installed on the remote host, so the =:gnuls= gate is resolved by accepting "?" on that host rather than installing coreutils. -- =:remote-async= nil → the scp/sshx method isn't advertising direct-async; switch to a method that supports it or check =tramp-direct-async-process= is taking effect for that protocol. +Submit a single eshell command line, return output (capped). +=:confirm t= always -- this is the escape hatch where the +strictly-typed wrappers above don't fit, so each invocation needs +my eyeball. Eshell parses in-process (no /bin/sh fork) so the +security surface is narrower than a shell command runner, but it's +still effectively arbitrary execution -- treat it as such. -Files involved: =modules/tramp-config.el=, =modules/dirvish-config.el=. +**** TODO [#B] Media and Reading Related Tools -*** 2026-05-22 Fri @ 20:24:44 -0500 Traced the root cause through dirvish source -Remote dates/sizes don't come from the dired =ls= listing or =dired-listing-switches=. They come from =dirvish-data-for-dir= (=dirvish-tramp.el:95=), which runs =ls -1lahi= on the remote and parses the columns into the attribute cache. That method only fires when both =(dirvish-prop :remote-async)= is a number and =(dirvish-prop :gnuls)= is a string. When either gate is shut, dirvish falls back to its default, which deliberately skips =(file-attributes f-name)= for remote files (=dirvish.el:904=, a perf guard) — leaving attrs nil, so the file-size and file-time widgets render "?" (=dirvish-widgets.el:216,247=). +Affordances over non-code content: feeds, PDFs, EPUBs, music. The +agent's job here is summarize / extract / queue, not produce. -That explains why every prior fix missed: dired-listing-switches feed a different code path entirely, and disabling =tramp-direct-async-process= shuts the =:remote-async= gate, which is the one path that populates remote attributes — exactly backwards. The config already enables direct-async for ssh/sshx (=tramp-config.el:79-88=), so the remaining closed gate is per-host: =:gnuls= (no GNU ls on FreeBSD-based truenas) or direct-async not taking effect for the method. Could not verify on a live remote from the work session — handed the per-host diagnostics up into the task body. +***** TODO [#B] Elfeed entry tools :feature: -** TODO [#D] Dashboard over-scroll: pin last line to window bottom :bug: -:PROPERTIES: -:LAST_REVIEWED: 2026-05-22 -:END: -Triggered by: 2026-05-20 Dashboard buffer too long follow-up. +Read entry body; list unread by feed or tag; mark read after a +summary lands in a roam node or inbox. Enables "give me the +non-noise headlines from this week's feeds" flows. -After the opens-at-top fix (=4ac1b81=), the dashboard can still be -scrolled past its content: the banner image makes the buffer just over -one screenful, so the wheel / =C-v= / =M->= pull the last line up and -leave empty space below it. Craig wants scrolling to stop once the -trailing line reaches the window bottom (no void) while still allowing -scroll-down to reach content below the window. +***** TODO [#B] PDF and EPUB text tools :feature: -Findings from the 2026-05-20 investigation: -- =pixel-scroll-precision-mode= is off, so this is standard line-based - scroll overshoot (the tall banner image inflates the rendered height). -- A =window-start= clamp does not work: =window-start= only lands on - line boundaries, so it can't express a position partway into the - banner image — it either blocks all scrolling or leaves the void. -- A =recenter -1= pin on =post-command-hook= does not work: it fires on - every command, so it fights item navigation (the cursor can't reach - the projects / bookmarks / recents). -- Right design: clamp only on actual scroll commands — advise - =mwheel-scroll= / =scroll-up-command= / =scroll-down-command= / - =end-of-buffer= to =recenter -1= when over-scrolled, never on - navigation commands. -- Live experiment scratch file: =~/dashboard-overscroll-experiment.el=. +Extract plain text from a PDF page or page range (via =pdftotext=) +and from an EPUB (via the existing nov-mode pipeline). Lets the +agent summarize / quote a research paper or book chapter without +me pasting passages. -** TODO [#D] Emacs Packages — Curl-Friendly Web Service Wrappers -Ideas for new Emacs packages following the same pattern as wttrin: HTTP GET to a simple web service, render results in a buffer, optionally show summary in the mode-line. All of these share the async fetch + caching infrastructure already proven in wttrin. -Captured On: [2026-04-04 Sat] -*** TODO Stock Market / Finance Package (Finnhub or Alpha Vantage) -Build a stock watchlist and quote viewer for Emacs. User defines a list of symbols; package fetches quotes and renders a formatted table in a dedicated buffer. Optional mode-line ticker showing one or more symbols rotating on a timer. +***** TODO [#B] EMMS playback and queue tools :feature: -**** Features -- Customizable watchlist: user defines a list of stock symbols in a defcustom; package fetches and displays all of them in a single buffer -- Formatted quote table: symbol, company name, current price, daily change (absolute and percent), volume — color-coded green/red for gains/losses -- ASCII sparkline charts: inline mini-charts showing intraday or multi-day price movement using Unicode block characters (▁▂▃▅▇ style) -- Mode-line ticker: rotating display of one or more symbols with price and change indicator, similar to wttrin's weather widget — click to open the full watchlist buffer -- Detail view: press RET on a symbol to see extended data — open/high/low/close, 52-week range, market cap, P/E ratio (data availability depends on backend) -- Auto-refresh with market awareness: background timer fetches new data during market hours; pauses on weekends and after-hours to conserve API calls -- Unit/currency preference: display prices in local currency if the backend supports it -- Cache layer: same pattern as wttrin — serve cached data instantly, refresh in background, show staleness indicator when data is old -- Interactive symbol lookup: ~M-x stock-add-symbol~ with completion against a symbol database or search endpoint +Current track, queue contents, playback state; queue or play a +path; compose a playlist from a prompt ("play something focusing +that's not Nick Cave"). Light tools, but a frequent friction +point. -**** What you'd learn -- JSON parsing in elisp (~json-parse-buffer~, ~json-read~) — these APIs return JSON, not plain text, so this is the main new skill vs. wttrin -- ASCII chart rendering — drawing sparklines or simple price charts with Unicode block characters in a buffer -- API key management in elisp — storing keys in ~auth-source~ or custom variables, passing them as query params +**** TODO [#B] Development Workflow Related Tools -**** Where the complexity lives -- Rendering: No pre-formatted ASCII comes back from the API. You'd build the table layout and any chart visualization yourself. This is the bulk of the work. -- Market hours awareness: Knowing when to fetch (pre-market, regular, after-hours, weekends) to avoid wasting API calls. -- Rate limiting: Free tiers are tight. Finnhub gives 60 calls/min which is generous; Alpha Vantage gives only 25/day on the free tier. Caching strategy matters more here than in wttrin. +Affordances over the dev loop: compilation output, test invocation, +coverage / profile data, flycheck / flymake diagnostics. -**** Candidate backends -- Finnhub (finnhub.io): Free API key, 60 calls/min, real-time US quotes. JSON only. Best rate limit of the free options. -- Alpha Vantage (alphavantage.co): Free API key, 25 calls/day. Supports CSV output which is trivial to parse — no JSON needed. Good for daily summaries, bad for frequent polling. -- Twelve Data (twelvedata.com): Free key, 800 calls/day, 8/min. Covers stocks, forex, crypto, ETFs. JSON and CSV. +***** TODO [#B] Compilation buffer tools :feature: -**** Downsides -- API key requirement adds friction for users (signup, config). Not as frictionless as wttrin. -- Rate limits mean you can't poll aggressively. Stale data is the norm on free tiers. -- Financial APIs change or shut down. Yahoo Finance's unofficial API has broken repeatedly over the years. Even paid services deprecate endpoints. Expect maintenance. -- Finnhub and Alpha Vantage are US-market-centric. International coverage varies. +Read the most recent =compile= buffer output; parse error locations +to =file:line=; summarize what broke. Pairs with the F6 test-runner +flow -- "tell me what's failing" becomes a single agent turn +instead of paste + parse. -**** Effort: Medium-High -The fetch/cache layer is straightforward (reuse wttrin patterns). The rendering layer (tables, charts, color-coding gains/losses) is where most of the time goes. Expect this to be a real project, not a weekend hack. +***** TODO [#B] Project test invocation tools :feature: -**** Name candidates (backronyms) -Pick one. All are recursive (self-referential) in the style of CHIME. -- BULL — *BULL Updates Live Listings* -- MINT — *MINT Indexes Noteworthy Tickers* -- QUOTE — *QUOTE Updates Ongoing Ticker Estimates* -- ASSET — *ASSET Surfaces Stock Exchange Tickers* -- MOAT — *MOAT Monitors Active Tickers* -- TRADE — *TRADE Reveals Active Daily Equities* -- BELL — *BELL Exhibits Live Listings* -- CHART — *CHART Highlights Asset Rate Tickers* -- BOARD — *BOARD Oversees Asset Rate Data* -- VAULT — *VAULT Aggregates Underlying Listing Tickers* +Run =make test-file FILE=X= / =make test-name TEST=Y= / +project-equivalent and return results. Currently each agent guesses +the project convention; expose the canonical invocation explicitly +per project so the agent can run focused tests itself. -*** TODO rate.sx Wrapper — Cryptocurrency Rates -Wrap Igor Chubin's rate.sx service. This is the lowest-effort, highest-pattern-match option — rate.sx works exactly like wttr.in. Returns colored ASCII tables with sparkline charts. Same ~User-Agent: curl~ trick, same ANSI escape codes. +***** TODO [#B] Coverage and profile tools :feature: -**** Features -- Full crypto dashboard: ~M-x rate-sx~ opens a buffer with a colored ASCII table of top cryptocurrencies — name, price, 24h change, market cap, and sparkline charts — all rendered by the service -- Single coin lookup: ~M-x rate-sx-coin~ prompts for a coin name (e.g., ~eth~, ~btc~) and displays its detailed view -- Plain price fetch: query ~rate.sx/1BTC~ to get a single numeric price — useful for mode-line display or programmatic use from other elisp -- Mode-line widget: show the price of one or more coins in the mode-line with periodic background refresh, similar to wttrin's weather indicator -- Customizable coin list: user picks which coins appear in the dashboard via a defcustom -- Currency base selection: rate.sx supports displaying prices in different fiat currencies -- ANSI color rendering: reuse wttrin's ~xterm-color~ pipeline to convert the service's colored ASCII output into Emacs faces -- Cache with background refresh: same timer-based pattern as wttrin — data stays warm, buffer opens instantly +Read the most recent SimpleCov JSON or profile dump. Lets the +agent answer "what's still uncovered after this push" or "what +function dominates startup time" against real measured data. -**** What you'd learn -- Very little new — this is almost a copy of wttrin with different URL construction. Good first project if you want to validate the pattern before tackling stocks. -- Could explore sharing infrastructure between wttrin and this package (common async fetch, caching, ANSI rendering). +***** TODO [#B] Diagnostic tools (flycheck / flymake) :feature: -**** Where the complexity lives -- Minimal. The service does the formatting. Your job is URL construction, fetch, ANSI-to-faces conversion (already solved in wttrin via ~xterm-color~), and buffer display. -- Coin selection UX: letting users pick which coins to show, custom vs. top-N, etc. +Surface current-buffer or project-wide errors and warnings. Useful +both as a "what's broken right now" check and as input to the +patch-narrative buffer / commit-intent workbench above. -**** Downsides -- Single point of failure: rate.sx is one person's side project. If Chubin takes it down, the package is dead. No fallback. -- Crypto-only. No traditional stocks, forex, or commodities. -- Less useful than a stock package for most people. +**** CANCELLED [#B] gptel-magit activation fails on velox :bug:quick: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-01 +:END: +Surfaced 2026-05-25 while diagnosing an unrelated load failure over SSH. velox-specific — the workstation has a current gptel and does not show it. -**** Effort: Low -Could reuse 70-80% of wttrin's code. A weekend project if you're focused. +At startup (and reproducibly in batch) velox logs: "Unable to activate package `gptel-magit'. Required package `gptel-0.9.8' is unavailable." gptel-magit depends on gptel >= 0.9.8 and velox's installed gptel is older or missing, so it can't activate. A startup warning, not a blocker. -*** TODO Frankfurter Currency Exchange Package -Wrap the Frankfurter API (frankfurter.dev) for fiat currency conversion and historical rates. ECB data, open source, no API key. +Reproduce: +: emacs --batch --no-site-file -L . -L modules --eval "(package-initialize)" --eval "(message \"done\")" 2>&1 | grep -i gptel -**** Features -- Quick conversion: ~M-x currency-convert~ prompts for amount, base currency, and target currency — displays the result in the echo area (e.g., "100 USD = 91.34 EUR") -- Multi-target conversion table: convert one amount against several currencies at once, rendered as an aligned table in a dedicated buffer -- Historical rate lookup: query a specific date's exchange rate — useful for expense reports, invoicing, or curiosity -- Rate trend view: fetch a date range and display a table or ASCII sparkline showing how a currency pair moved over days/weeks/months -- Latest rates dashboard: ~M-x currency-latest~ shows today's rates for a user-defined set of currency pairs in a buffer -- Interactive currency selection: completing-read over the ~30 supported currencies with full names (e.g., "USD — United States Dollar") -- Mode-line rate display: optionally show one currency pair's rate in the mode-line with daily background refresh -- Cache layer: rates only update once per business day, so caching is especially effective — fetch once, serve all day +Next step: check the installed gptel version (=(assq 'gptel package-alist)= or =M-x package-list-packages=), update gptel to >= 0.9.8, then re-evaluate gptel-magit activation. If gptel was pinned/held on velox, reconcile the pin against the gptel-magit dependency. -**** What you'd learn -- JSON parsing in elisp (the API returns JSON, not formatted text) -- Table rendering — building aligned currency tables with ~format~ and text properties -- Historical data display — the API supports date ranges, so you could show rate trends over time -**** Where the complexity lives -- Rendering: You'd build the table and any trend visualization yourself. -- Date handling in elisp for historical queries (~encode-time~, ~format-time-string~, etc.). -- UX: interactive base/target currency selection with completion. +** TODO [#C] Build an Org-native API workspace :feature:test: +:PROPERTIES: +:LAST_REVIEWED: 2026-06-21 +:END: -**** Downsides -- ECB data updates once per business day. No real-time rates — this is reference data, not trading data. -- Covers ~30 currencies (major fiats). No crypto, no exotic currencies. -- Frankfurter is open-source and self-hostable, which is good for longevity, but the public instance could still go away. +Moved to Someday/Maybe on 2026-06-23 when gptel was archived. This +design used gptel for its AI-assisted parts (restclient-ai.el, API +summaries, the AI-debugging ideas); with gptel archived those modules +are orphaned. The non-AI parts (OpenAPI import, request execution, +response capture) still stand on their own, so I shelved the whole design +here rather than dropping it. Pull it back to Open Work if the non-AI +core is worth building. -**** Effort: Low-Medium -JSON parsing adds a step vs. wttrin's plain text, but the API is clean and well-documented. Straightforward project. +Build an Emacs-native API workspace layer that keeps =restclient.el= useful for +lightweight request execution while adding OpenAPI import, Org notebooks, +response capture, inline images, and =gptel=-assisted API documentation. -*** TODO ipinfo.io — IP and Geolocation Lookup -~curl ipinfo.io~ returns JSON with your public IP, city, region, country, ISP, and timezone. No auth needed for basic lookups (1000 requests/day unauthenticated). +*** Spec -**** Features -- My IP: ~M-x ipinfo~ fetches your public IP and geolocation, displays a formatted summary in a buffer or the echo area — IP, city, region, country, ISP, timezone, coordinates -- Arbitrary IP lookup: ~M-x ipinfo-lookup~ prompts for an IP address and shows the same geolocation detail -- Copy IP to kill ring: one-keystroke convenience for grabbing your public IP -- Open in browser map: command to open the returned lat/long coordinates in OpenStreetMap or Google Maps via ~browse-url~ -- Hostname resolution: the API also returns the reverse DNS hostname for an IP -- Mode-line IP display: optionally show your current public IP in the mode-line (useful when switching between networks/VPNs) -- Org-mode integration: insert IP/geo info as an org property block or table row at point +**** Summary +Build a small Emacs API-workspace layer that keeps =restclient.el= as the +plain-text request executor, while adding higher-level discovery, generation, +Org notebook, response handling, and =gptel=-assisted documentation workflows. -**** What you'd learn -- Minimal new skills — simple JSON response, single fetch, render in buffer or echo area. -- Could add map integration (open coordinates in browser or an Emacs map package). +The intended result is not a Postman clone. It should feel like an +Emacs-native API lab: +- generate request collections from OpenAPI/Swagger specs +- browse and execute requests from =.rest= files or Org notebooks +- save useful responses back into Org +- display image responses inline +- use =gptel= to explain APIs, endpoints, request bodies, and responses +- leave room for =verb.el= or Hurl where they are a better fit -**** Where the complexity lives -- Almost nowhere. This is the simplest possible package. Fetch JSON, format it, display it. -- If you want to look up arbitrary IPs (not just your own), add a prompt with completion history. +**** Goals +- Preserve the current lightweight =restclient.el= workflow for ad-hoc calls. +- Add an OpenAPI importer that can generate useful first-draft request files. +- Add an Org workspace format for API notes, executable request blocks, results, + response links, and generated summaries. +- Add response post-processing helpers for JSON, binary/image data, and model + summaries. +- Make common auth flows easy to scaffold without storing secrets in generated + files. +- Keep generated artifacts readable and editable by hand. +- Keep implementation modular enough that =verb.el= can be evaluated as a richer + Org-native frontend. -**** Downsides -- Very niche utility. You look up your IP occasionally, not daily. -- Free tier is generous (1000/day) but authenticated lookups require a token for enriched data. -- Privacy-conscious users may not want to send their IP to a third party (though they already do by virtue of connecting). +**** Non-Goals +- Do not build a full graphical API client. +- Do not store secrets directly in Org or =.rest= files. +- Do not attempt complete OpenAPI 3.1 schema synthesis in the first pass. +- Do not require =gptel= for ordinary request execution. +- Do not make Hurl a runtime dependency for the restclient workflow. -**** Effort: Very Low -An afternoon project. Good as a learning exercise for the fetch-parse-render pattern if you haven't done JSON APIs in elisp before. +**** Primary User Flows +***** Import An API +1. User runs =cj/restclient-import-openapi=. +2. Command prompts for a URL or local OpenAPI/Swagger file. +3. Command parses the spec into normalized endpoint records. +4. Command prompts for output format: + - =restclient= request collection + - Org API workspace + - both +5. Command writes generated files under a project/API workspace directory. +6. Generated file includes host variables, auth placeholders, request examples, + and a short summary of how to start using the collection. -*** TODO icanhazdadjoke.com — Dad Jokes in Emacs -~curl -H "Accept: text/plain" https://icanhazdadjoke.com~ returns a single plain-text joke. No auth, no key, no rate limit concerns for casual use. +***** Describe An API +1. User runs =cj/restclient-describe-api= from a generated workspace or spec file. +2. Command extracts API metadata, paths, operations, schemas, auth, and tags. +3. Command sends a bounded summary payload to =gptel=. +4. Result is inserted under an Org =Overview= subtree. -**** Features -- Random joke: ~M-x dad-joke~ fetches a random joke and displays it in the echo area — minimal disruption, maximum groan -- Joke buffer: ~M-x dad-joke-buffer~ opens a dedicated buffer with a joke, nicely formatted with a large font face. Press ~n~ for the next joke, ~q~ to quit -- Search jokes: ~M-x dad-joke-search~ prompts for a term (e.g., "cat") and displays matching jokes in a buffer — the API supports ~?term=~ search -- Startup joke: optional hook to display a dad joke in the echo area or scratch buffer on Emacs startup -- Org-mode insertion: ~M-x dad-joke-insert~ inserts a joke at point — for lightening up documentation or commit messages -- Kill ring: ~M-x dad-joke-yank~ fetches a joke and puts it directly in the kill ring for pasting elsewhere +***** Execute And Capture A Request +1. User executes a request via =restclient.el= or =ob-restclient=. +2. Command captures response status, headers, content type, body, and timestamp + when available. +3. JSON/XML responses can be inserted as source blocks or summarized. +4. Image responses are saved to an assets directory and linked inline in Org. +5. Binary responses that are not image-like are saved as file links. -**** What you'd learn -- Nothing technically new — this is the simplest possible HTTP-GET-to-buffer pattern. -- Good excuse to experiment with fun presentation: display in echo area, dedicated buffer, or even as a startup message. +***** Iterate On A Response +1. User runs helper commands against the last response: + - pretty-print JSON/XML + - run =jq= + - summarize with =gptel= + - extract a value into a restclient variable + - save body to a file +2. The result is inserted near the endpoint subtree or shown in a temporary + buffer depending on command prefix/options. -**** Where the complexity lives -- It doesn't. Fetch a string, display it. The API also supports search (~?term=dog~) if you want to add that. +**** Proposed Modules +***** =modules/restclient-workspace.el= +Main configuration and user-facing commands. Owns keybindings, workspace +creation, dispatch commands, and integration with existing restclient config. -**** Downsides -- Toy project. Zero practical utility beyond morale. -- The joke quality is... dad jokes. +***** =modules/restclient-openapi.el= +OpenAPI/Swagger loading and normalization: +- fetch URL or read file +- parse JSON/YAML where available +- normalize servers, paths, methods, parameters, request bodies, auth schemes, + tags, operation IDs, and examples +- expose pure helper functions suitable for unit tests -**** Effort: Trivial -An hour, maybe two if you add search and a nice buffer layout. Publishable on MELPA as a novelty package. +***** =modules/restclient-generate.el= +Generation layer: +- render =.rest= / =.http= request collections +- render Org workspaces +- synthesize simple JSON request bodies from schemas/examples +- generate variables and auth placeholders -*** TODO qrenco.de — QR Code Generator -Chubin's QR code service. ~curl qrenco.de/hello~ returns a QR code rendered in Unicode block characters. Encodes arbitrary text, URLs, WiFi credentials, etc. +***** =modules/restclient-response.el= +Response helpers: +- identify content type +- save binary/image bodies +- insert Org links +- display inline images +- route JSON/XML/text handling +- track last response metadata -**** Features -- Encode text: ~M-x qr-encode~ prompts for a string and displays the QR code in a dedicated buffer using Unicode block characters -- Encode region: ~M-x qr-encode-region~ encodes the currently selected text — quick way to QR-ify a URL, password, or snippet -- Encode URL at point: ~M-x qr-encode-url~ detects the URL under point (via ~thing-at-point~) and generates a QR code for it -- WiFi QR codes: ~M-x qr-wifi~ prompts for SSID, password, and encryption type, then generates the standard WiFi QR format (~WIFI:T:WPA;S:MyNetwork;P:password;;~) — scan to join a network -- Buffer font management: automatically sets the buffer to a monospace font with consistent Unicode block rendering (same approach as wttrin's Liberation Mono override) -- Copy as text: yank the QR code's block characters to the kill ring for pasting into emails, READMEs, or chat -- Adjustable size: the service supports size parameters — expose this as a prefix argument or defcustom +***** =modules/restclient-ai.el= +=gptel= integration: +- summarize API specs +- explain endpoint behavior +- generate example payload notes +- summarize responses +- keep prompts bounded and avoid sending secrets -**** What you'd learn -- Handling Unicode block character output (not ANSI colors this time, but character-level rendering) -- Interactive input patterns — prompting for text to encode, or encoding the current region/URL at point +**** File And Workspace Layout +Default generated workspace: -**** Where the complexity lives -- Font and character width: QR codes require a monospace font where the block characters render at consistent widths. Some Emacs font configurations break this. You'd need to set the buffer font explicitly (like wttrin does). -- The service sometimes returns ANSI codes for inverted colors. May need ~xterm-color~ or manual processing. +#+begin_src text +data/apis/<api-slug>/ + <api-slug>.rest + <api-slug>.org + openapi.json + assets/ + responses/ +#+end_src -**** Downsides -- Same single-point-of-failure risk as rate.sx — one person's service. -- QR codes in a terminal/buffer are inherently lower resolution than image-based ones. Scanning reliability depends on terminal font size and screen. -- Niche use case. Most people generate QR codes infrequently. +The exact root should be configurable, defaulting to the existing REST data +directory if one is already present in the config. -**** Effort: Low -Similar to rate.sx in scope. The fetch is trivial; font handling and display are the main considerations. +**** Org Workspace Shape +#+begin_example +,* API Name +:PROPERTIES: +:OPENAPI_SOURCE: https://example.com/openapi.json +:BASE_URL: https://api.example.com +:END: -*** TODO dns.toys — Multi-Tool Utility via DNS -dns.toys answers queries over DNS instead of HTTP. ~dig 100USD-EUR.fx @dns.toys~ returns currency conversion, ~dig mumbai.time @dns.toys~ returns world time, ~dig 42km-mi.unit @dns.toys~ does unit conversion. Also supports base conversion, math constants, and more. +,** Overview +Generated or user-written API notes. -**** Features -- Currency conversion: ~M-x dns-toys-currency~ prompts for amount and currency pair (e.g., "100 USD to EUR"), displays result in echo area -- World time: ~M-x dns-toys-time~ prompts for a city name and shows the current local time — faster than searching online, no browser needed -- Unit conversion: ~M-x dns-toys-unit~ prompts for a value and unit pair (e.g., "42 km to mi"), returns the conversion -- Base conversion: ~M-x dns-toys-base~ converts between decimal, hex, octal, and binary (e.g., "100 dec to hex") -- Math constants: ~M-x dns-toys-constant~ looks up pi, e, tau, etc. — niche but handy in a calc session -- Unified command: ~M-x dns-toys~ with a smart prompt that detects query type from input format, dispatching to the right DNS query automatically -- Echo area results: all results display in the echo area by default for quick non-disruptive answers, with an optional dedicated buffer for history -- Async queries: use ~start-process~ with sentinels so ~dig~ calls don't block Emacs +,** Auth +Token acquisition notes and placeholders. No secrets stored here. -**** What you'd learn -- Calling external processes from elisp (~call-process~ or ~start-process~ to invoke ~dig~) instead of ~url-retrieve~. This is a meaningfully different integration pattern from wttrin. -- Parsing DNS TXT record output — dig returns structured but noisy output; you'd extract the answer section. -- Building a multi-function package — this one service covers currency, time, units, and base conversion, so the UX needs a dispatch mechanism (separate commands, or a unified prompt with type detection). +,** Endpoints +,*** GET /users +:PROPERTIES: +:OPERATION_ID: listUsers +:METHOD: GET +:PATH: /users +:END: -**** Where the complexity lives -- Output parsing: ~dig~ output is not designed for human consumption. You'd parse the ANSWER SECTION, strip TTL/class/type fields, and extract the payload string. -- Latency: DNS queries are fast but ~call-process~ on ~dig~ has subprocess overhead. For interactive use this is fine; for mode-line updates you'd want async (~start-process~ with a sentinel). -- Feature breadth: The temptation is to wrap every dns.toys feature. Scoping to a focused set (currency + time + units) keeps it manageable. +#+begin_src restclient :results raw +GET :host/users +Authorization: Bearer :token +Accept: application/json +#+end_src -**** Downsides -- Requires ~dig~ installed (standard on Linux/macOS, not on Windows). Limits portability. -- dns.toys is a single maintainer's project. Same fragility concern as rate.sx and qrenco.de. -- DNS protocol means no rich formatting — just short text strings. The results are useful but visually plain. -- Some networks/firewalls block non-standard DNS queries, which would silently break the package. +,**** Notes +,**** Responses +#+end_example -**** Effort: Low-Medium -The individual queries are trivial. The interesting work is building a clean multi-function UX and handling the process-based (vs. HTTP-based) integration pattern. Good project for learning elisp process management. +**** Commands +- =cj/restclient-new-scratch= :: open a scratch =restclient-mode= buffer. +- =cj/restclient-open-file= :: open a REST file from the configured API data dir. +- =cj/restclient-import-openapi= :: generate a workspace from OpenAPI/Swagger. +- =cj/restclient-describe-api= :: insert a =gptel=-generated API overview. +- =cj/restclient-describe-endpoint= :: explain the endpoint at point. +- =cj/restclient-generate-example-body= :: generate or refresh sample JSON body. +- =cj/restclient-save-last-response= :: save response body and metadata. +- =cj/restclient-insert-last-response-org= :: insert response under Org subtree. +- =cj/restclient-display-image-response= :: save and display image response. +- =cj/restclient-response-jq= :: run =jq= against the last JSON response. +- =cj/restclient-copy-curl= :: copy the request at point as curl if supported. -*** TODO cheat.sh Integration — Programming Cheat Sheets -~curl cheat.sh/tar~ returns a syntax-highlighted cheat sheet. Supports language-specific queries like ~cheat.sh/python/lambda~. Already has some Emacs integrations (cheat-sh.el exists) but could be worth a custom implementation if existing packages don't fit your workflow. +**** Keybindings +Keep the existing prefix shape under =C-; R=: +- =C-; R n= :: new scratch request buffer +- =C-; R o= :: open REST file +- =C-; R i= :: import OpenAPI/Swagger +- =C-; R d= :: describe API or endpoint +- =C-; R s= :: save/capture last response +- =C-; R j= :: run =jq= on last response +- =C-; R m= :: transient menu for workspace commands -**** Features -- Quick lookup: ~M-x cheat-sh~ prompts for a topic (e.g., "tar", "git/stash") and displays a syntax-highlighted cheat sheet in a dedicated buffer -- Language-scoped queries: ~M-x cheat-sh-lang~ prompts for language then topic (e.g., ~python/lambda~, ~go/goroutine~) with two-stage completion -- Context-aware lookup: detect the current buffer's major mode and scope the query to that language automatically — in a Python buffer, querying "lambda" goes to ~cheat.sh/python/lambda~ -- ANSI-to-faces rendering: convert the service's syntax-highlighted ANSI output to proper Emacs font-lock faces using ~xterm-color~ (same pipeline as wttrin) -- Navigation: browse related topics from within the buffer — follow-up queries without returning to the minibuffer. Previous/next topic history with ~p~ / ~n~ -- Completion against the topic list: fetch and cache ~cheat.sh/:list~ to provide completing-read over all available topics -- Offline cache: optionally cache previously viewed cheat sheets for offline access or instant re-display -- Region query: select a command or function name and look it up directly with ~M-x cheat-sh-region~ +**** OpenAPI Import Details +Minimum first-pass support: +- OpenAPI 3.x JSON +- Swagger 2.0 JSON if easy to normalize +- YAML via available Emacs YAML library or external converter if already present +- =servers= / =host= + =basePath= +- path-level and operation-level parameters +- query/path/header parameters +- JSON request bodies +- examples and default schema values +- security schemes: + - HTTP bearer + - basic + - API key header + - API key query -**** What you'd learn -- ANSI syntax highlighting → Emacs faces (same skill as wttrin) -- Deep completion support: cheat.sh has a massive topic tree. Building good interactive completion for ~cheat.sh/{language}/{topic}~ is a UX challenge. +First pass can skip or mark as unsupported: +- polymorphic schemas beyond simple =oneOf= / =anyOf= note generation +- multipart body generation +- full OAuth flows +- callbacks/webhooks +- complete response schema rendering -**** Where the complexity lives -- Completion and navigation: the value is in making it fast to find the right cheat sheet. ~cheat.sh/:list~ returns thousands of entries. -- Existing packages: ~cheat-sh.el~ already exists on MELPA. You'd need a reason to build your own (better caching, offline support, integration with your workflow). +**** Secret Handling +- Generated files must use placeholders like =:token=, =:api-key=, or + =:basic-auth=. +- Do not write tokens into generated files. +- Prefer variables loaded from auth-source, environment variables, or manually + entered restclient variables. +- =gptel= prompts must strip obvious auth headers and secret-like values from + request/response payloads before sending context. -**** Downsides -- Overlaps with existing Emacs packages. Check ~cheat-sh.el~ before building. -- The service aggregates from many sources. Quality is inconsistent across topics. +**** Response Handling +- Text JSON/XML/HTML/plain responses may be inserted into Org as source blocks. +- JSON responses should support optional =jq= filters. +- Image responses should be saved under =assets/responses/= and inserted as Org + file links. +- After inserting image links, call =org-display-inline-images= when in Org. +- Large responses should be saved as files and linked rather than inserted. +- Binary non-image responses should be saved and linked with content type notes. -**** Effort: Medium -If building from scratch. Low if extending or wrapping an existing package. The completion UX is where the effort goes. -** TODO [#D] Localrepo refresh / update script :feature: -No dedicated update path today — refreshing a pinned package means ad-hoc =cp= from the local elpa mirrors. Document the current shape and decide whether a =scripts/refresh-localrepo.sh= is worth writing. Cross-linked from =docs/design/localrepo.org=. +**** Integration Choices To Evaluate +- =restclient.el= remains the default executor for =.rest= files. +- =ob-restclient= powers executable Org source blocks. +- =verb.el= should be evaluated as an alternate frontend for Org-native API + workspaces because it already has tree inheritance, embedded Elisp, and image + response display. +- Hurl should be evaluated as an export/test target, especially for chained + request tests and CI assertions. -** TODO [#D] Native-comp .eln cache strategy :feature: -The native-comp =.eln= cache is Emacs-version-specific; an Emacs upgrade invalidates everything. Document the cache location, what an upgrade triggers, and whether a warm-the-cache script is worth shipping. Cross-linked from =docs/design/localrepo.org=. +**** Testing Strategy +- Unit-test OpenAPI normalization with small fixture specs. +- Unit-test request generation for GET, POST, auth, query params, path params, + and request-body examples. +- Unit-test secret redaction before =gptel= calls. +- Unit-test response classification and Org insertion helpers. +- Integration-test generated =.rest= files for representative APIs. +- Integration-test generated Org workspaces with =ob-restclient= where feasible. +- Avoid live network tests by default; use fixtures/stubs unless explicitly + tagged =:network=. -** TODO [#D] Polish reveal.js presentation setup :feature: +**** First Milestone +1. Keep/verify existing restclient scratch/open commands. +2. Add a tiny OpenAPI JSON parser/normalizer for a fixture spec. +3. Generate a readable =.rest= collection with variables and examples. +4. Generate a matching Org workspace. +5. Add response save/link helpers for JSON and images. +6. Add a =gptel= API-summary command with secret redaction. +7. Add focused unit tests and one sample fixture. -Three small reveal.js improvements; collected into one task because each on its own is too small to track separately. +**** Open Questions +- Should the canonical workspace be =.rest= first, Org first, or generated in + both formats by default? +- Is =verb.el= a better primary target than =ob-restclient= for the Org notebook + experience? +- Which YAML parser should be used if no YAML package is already configured? +- Where should API workspaces live by default: =data/=, =docs/=, or project root? +- Should response capture hook into restclient internals, or should capture be a + separate explicit command operating on response buffers? +- How much schema synthesis is useful before it becomes noisy? -1. *Image insertion helper.* Function to insert images with proper org-reveal attributes (sizing, background images, etc.) without having to remember the syntax. -2. *Default font sizing for slide elements.* Configure reveal.js font sizes for headings, body text, code blocks, etc. — better defaults via =org-reveal-head-preamble= CSS or a custom theme. -3. *Custom dupre reveal.js theme.* CSS theme using the colors from =themes/dupre-palette.el=. Install into =reveal.js/css/theme/= for use with =#+REVEAL_THEME: dupre=. +*** Ideas +- Treat =restclient.el= as the lightweight request scratchpad, and layer richer workflow commands around it instead of trying to turn it into Postman. +- Add an OpenAPI/Swagger importer: + - prompt for a spec URL or local file + - parse paths, methods, auth schemes, request bodies, and examples + - generate a =.http= / =.rest= request collection + - optionally generate an Org notebook with one subtree per endpoint +- Add an API description command using =gptel=: + - summarize the API from an OpenAPI spec + - explain each endpoint, auth requirement, parameters, and response shape + - write the summary into the generated Org workspace +- Generate example requests automatically: + - =GET= examples with query params + - =POST= / =PUT= / =PATCH= examples with sample JSON bodies + - =DELETE= examples with safe placeholder IDs + - shared variables like =:host=, =:token=, =:api-version=, =:tenant= +- Add auth helpers: + - bearer token insertion + - basic auth + - API key header/query param + - OAuth token fetch request template +- Improve Org integration: + - use =ob-restclient= for executable API notebooks + - support =:jq= filters for clean JSON results + - save response bodies under endpoint subtrees + - capture request/response metadata as Org properties +- Handle images and binary responses: + - detect image =Content-Type= + - save response data into an assets directory + - insert =[[file:...]]= links into Org + - call =org-display-inline-images= after execution +- Add response-processing commands: + - pretty-print JSON/XML + - run =jq= against the last response + - summarize response with =gptel= + - extract fields into restclient variables for follow-up calls +- Add request collection ergonomics: + - imenu/consult navigation by endpoint + - transient menu for send/copy curl/jq/save response + - templates for common headers + - per-project API workspace discovery +- Investigate =verb.el= as the richer Org-native frontend: + - Org tree inheritance for host/header/auth defaults + - embedded Elisp in request specs + - built-in display of image/PDF/SVG responses + - likely better base for a notebook-style API client +- Investigate Hurl for repeatable API tests: + - request chaining + - captures + - assertions + - CI-friendly execution + - possible export target from generated API workspaces -** TODO [#D] System-tool dependency install script :feature: -=ripgrep=, =fd=, =pandoc=, =prettier=, =pyright=, and other binaries that =cj/executable-find-or-warn= flags at module load are not in =package.el='s reach. Document the required-tool set and ship a setup script (or =pacman=/=apt= invocation set). Cross-linked from =docs/design/localrepo.org=. +*** Original Goals +**** Keybindings to test +- C-; R n — new scratch *restclient* buffer (should open in restclient-mode) +- C-; R o — open .rest file (should default to data/ directory) -** TODO [#D] Treesitter grammar offline cache :feature: -Treesitter grammars are downloaded by =treesit-auto= on first use and live outside the localrepo. For true offline reproducibility, cache the grammars next to the localrepo (a =.localrepo/treesitter/= tier, or a separate mirror script). Cross-linked from =docs/design/localrepo.org=. -* Emacs Someday/Maybe +**** Functional tests +1. Open tutorial-api.rest, run JSONPlaceholder GET (C-c C-c) — verify response inline +2. Run POST example — verify 201 response with fake ID +3. Run httpbin header echo — verify custom headers echoed back +4. Navigate between requests with C-c C-n / C-c C-p +5. Test jq filtering (requires jq installed): restclient-jq loaded? +6. Open scratch buffer (C-; R n), type a request manually, execute +7. which-key shows "REST client" menu under C-; R + * Emacs Resolved ** DONE [#B] Fix likely =elpa-mirror-location= path bug :bug:quick: CLOSED: [2026-05-03 Sun] -- cgit v1.2.3