From c00167c64cbce7f67e2924a51a236c26d7f8d8f4 Mon Sep 17 00:00:00 2001 From: Craig Jennings Date: Sat, 16 May 2026 10:10:31 -0500 Subject: docs(design): network tools brainstorm + GPTel Tool Work hierarchy Adds docs/design/gptel-network-tools.org capturing the brainstorm output for the next gptel-tools batch -- net_diagnose, net_discover, net_services, network_status, dns_lookup -- with argv shapes, target-gating guardrails for nmap, and a ~47-test sketch. Restructures the GPTel Tool Work parent in todo.org with seven themed categories: Git, Org, messaging, file/buffer, filesystem, media / reading, and dev workflow. Each carries a body framing the design choice and stub child themes. Filesystem covers the pandoc / imagemagick / ffmpeg / ripgrep / fd / file+exiftool / jq+yq surface plus an eshell escape hatch. Per-theme spec lands in the task body once written. Implementation tasks join as siblings once the spec is approved. --- todo.org | 1129 +++++++++++++++++++++++++++++++++++++++++--------------------- 1 file changed, 744 insertions(+), 385 deletions(-) (limited to 'todo.org') diff --git a/todo.org b/todo.org index 8c04c955..646fdc37 100644 --- a/todo.org +++ b/todo.org @@ -36,10 +36,9 @@ Use tags to describe the work shape: Tags are additive. For example, a small wrong-behavior fix can be =:bug:quick:=, and a feature that requires internal restructuring can be =:feature:refactor:=. - * Emacs Open Work -** PROJECT [#A] Architecture review follow-up from 2026-05-03 :refactor:no-sync: +** PROJECT [#B] Architecture review follow-up from 2026-05-03 :refactor:no-sync: High-level pass over =init.el=, =early-init.el=, and all 104 files in =modules/=. The main theme: the config works, but load order, startup side @@ -399,126 +398,6 @@ Expected outcome: - Add a note to the local repository docs so future package failures do not lead to permanent insecure defaults. -** TODO [#B] Implement EMMS-free music-config architecture :refactor: -*** 2026-05-15 Fri @ 19:17:01 -0500 Specification -Implement the design in [[file:docs/design/music-config-without-emms.org][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. - -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. - -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. - -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. - -*** 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. - -Acceptance: structs defined, helpers callable in batch without EMMS loaded. - -Depends on: none (start here). - -*** TODO [#B] Backend protocol + fake test backend :refactor:tests: -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. - -*** TODO [#B] Read-side state API + characterization tests :tests: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. - -Acceptance: read-side helpers covered; characterization tests green against -the current EMMS-backed implementation. - -Depends on: backend protocol + fake test backend. - -*** 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. - -Acceptance: opening the playlist renders package state; reorder/shuffle/clear -go through state mutations and re-render; tests cover header + overlay -positioning. - -Depends on: read-side state API. - -*** 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=). - -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. - -Depends on: backend protocol + fake test backend. - -*** 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. - -Acceptance: full keymap functional end-to-end against the fake backend; -characterization tests still green; Dirvish =+= add path covered. - -Depends on: playlist major mode + mpv backend. - -*** TODO [#B] EMMS removal + parity walk :cleanup:tests: -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. - -Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity -walk recorded as a completion log entry under the parent task. - -Depends on: command + Dired/Dirvish rewire. - ** TODO [#B] Rework dev F-keys: compile+run (F4), test (F6), coverage (F7) :feature: *** 2026-05-15 Fri @ 19:16:08 -0500 Specification Consolidate the developer F-key block into a coherent sequence. F5 reserved for debug (separate ticket). Format bindings move off F6 to C-; f. @@ -646,279 +525,104 @@ module; coverage track is shipped before this lands. Depends on: the coverage-config track shipping; F4 and F6 sub-tasks above. -** TODO [#B] Review and rebind M-S- keybindings :refactor: +** DOING [#B] Module-by-module hardening :harden:no-sync: -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) +Review every file in =modules/= and capture concrete bugs, tests, refactors, +and design improvements as child tasks. This is intentionally separate from the +top-level architecture review: the architecture project tracks cross-cutting +load/startup/test structure, while this project tracks module-specific work. -** TODO [#B] Build cj/dev-setup-project helper (per docs/design/dev-setup-project.org) :feature: -*** 2026-05-15 Fri @ 19:17:37 -0500 Specification +Re-review pass 2026-05-15: +- Each of the six existing review tracks (foundation, custom editing, UI / + navigation, Org workflow, programming workflow, integrations and + applications) was re-walked as if it had not been reviewed before. +- 32 new sub-task findings filed across the tracks above (foundation 5, + custom editing 6, UI / navigation 9, Org workflow 3, programming 6, + integrations 2). Findings already covered by an existing sub-task were + dropped during consolidation. +- A separate =Review newly added modules= task lists the 24 modules that + were either added after the parent task was written (post-2026-04) or + fell outside the original scope lists. Each is routed to its target + track; module-specific findings are filed under the relevant track. -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. +Review protocol for each module: +- Read the module directly, not just the test names. +- Check runtime dependencies, top-level side effects, keybindings, timers, + external executable assumptions, secrets, host-specific paths, and user-data + writes. +- Check existing test coverage and whether tests protect the highest-risk + behavior. +- Promote larger findings into child =PROJECT= tasks with phases. Keep small + fixes as plain =TODO= tasks. -Design: [[file:../docs/design/dev-setup-project.org][docs/design/dev-setup-project.org]] +Priority scheme: use the top-level =Priority Scheme= section in this file. -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). +Suggested review order: +1. Foundation: =system-lib=, =user-constants=, =host-environment=, + =system-defaults=, =keybindings=, =config-utilities=, =early-init=, + =init=. +2. Custom editing utilities: =custom-*=, =external-open=, =media-utils=. +3. UI and navigation: =ui-*=, =font-config=, =modeline-config=, + =selection-framework=, =mousetrap-mode=, =popper-config=. +4. Org workflow: =org-*=, =calendar-sync=, =hugo-config=, =gloss-config=. +5. Programming workflow: =prog-*=, =dev-fkeys=, =test-runner=, + =coverage-*=, =vc-config=. +6. Integrations and applications: mail, Slack, ERC, Elfeed, EWW, Dirvish, + PDF, Calibre, music, recording/transcription, AI/rest tooling. -Deferred: -- Rust (Cargo.toml), Java (pom.xml), other language shapes. -- Project-wide override config file. -- Auto-detecting external run scripts in conventional locations. +*** DOING [#B] Harden foundation modules :harden: -Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable. +Scope: +- =system-lib.el= +- =user-constants.el= +- =host-environment.el= +- =system-defaults.el= +- =keybindings.el= +- =config-utilities.el= +- =early-init.el= +- =init.el= -*** 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) +Expected output: +- Add one child task for each actionable finding. +- Note "no action" only when the module has been reviewed and no task is + needed. +- Cross-reference existing architecture tasks instead of duplicating them. -Files: =modules/dev-setup-config.el= (new). No interactive surface, no I/O -beyond reading the named file. +Review progress: +- =system-lib.el=: reviewed 2026-05-03. No immediate action beyond the existing + [#B] system-lib extraction task. +- =host-environment.el=: reviewed 2026-05-03. See child tasks below. +- =user-constants.el=: reviewed 2026-05-03. See child tasks below. +- =system-defaults.el=: reviewed 2026-05-03. See child tasks below. +- =keybindings.el=: reviewed during architecture pass. No new module-specific + action beyond the load-order/keymap architecture tasks. +- =config-utilities.el=: reviewed 2026-05-03. No new module-specific action; + profiling extraction is already tracked by [#B] "Build debug-profiling.el + module". +- =early-init.el=: reviewed 2026-05-10. See child tasks below and the existing + [#B] "Split early startup from package bootstrap" task. +- =init.el=: reviewed 2026-05-10. See child tasks below and the existing + eager load-graph architecture tasks. -Acceptance: each helper callable in isolation with handcrafted fixtures; -no command yet. +Completion review 2026-05-15: +- Re-read the parent =Module-by-module review and hardening= context and the + adjacent architecture follow-up so this review stays module-specific. +- Re-checked all scoped files against the review protocol. Existing child + tasks below still cover the actionable module findings for + =user-constants.el=, =host-environment.el=, =system-defaults.el=, and + =early-init.el=. +- =system-lib.el=, =keybindings.el=, =config-utilities.el=, and =init.el= do + not need additional module-specific child tasks from this pass; remaining + concerns are already tracked by the utility-consolidation, keymap + registration, debug-profiling, and eager-load-graph architecture tasks. -Depends on: none -- start here. +**** PROJECT [#B] Split path constants from filesystem initialization in =user-constants.el= :refactor: -*** TODO [#B] ERT coverage for the pure helpers :feature:tests: -Normal/Boundary/Error tests for every helper from the prior sub-task, -matching the design's testing section. - -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=). - -Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green; -every helper has at least one Normal, one Boundary, one Error case. - -Depends on: pure detection + parsing helpers. - -*** 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. - -Files: =modules/dev-setup-config.el=. - -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. - -Depends on: pure detection + parsing helpers. - -*** 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 (=;; ==== -====[ ]==, gitignore special, Makefile special). - -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). - -Acceptance: round-trip -- render proposal -> parse buffer -> equal block -list. Mode keybindings smoke-tested. - -Depends on: starter-Makefile + .dir-locals.el proposal generator. - -*** 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. - -Files: =modules/dev-setup-config.el=, plus ERT cases for the diff + -idempotent-append logic against temp dirs. - -Acceptance: re-run on an unchanged project writes nothing; renaming a -Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay -untouched. - -Depends on: review-buffer major mode + parser. - -*** TODO [#B] Interactive command + smoke test :feature:tests: -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=. - -Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=. Add -=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator). - -Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review -buffer; =C-c C-c= writes the expected files. - -Depends on: writer + status diff + projectile cache reset. - -*** TODO [#B] Resolve open questions + design follow-ups :cleanup: -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. - -Body: park decisions inline in the design doc or run =arch-decide= if they -turn out load-bearing. - -Depends on: none, but easiest after the writer sub-task surfaces real -friction. - -** TODO [#B] Pick and wire a debug backend for F5 :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 - -*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals -Bind F5 globally to a debug entry point. Backend choice is the hard part: - -- 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. - -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) - -Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip. - -Do this after the F-key rework ticket ships so F5 is the only hole left. - -** TODO [#B] Build debug-profiling.el module :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. - -Design: [[file:../docs/design/debug-profiling.org][docs/design/debug-profiling.org]] - -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. - -** DOING [#B] Module-by-module hardening :harden:no-sync: - -Review every file in =modules/= and capture concrete bugs, tests, refactors, -and design improvements as child tasks. This is intentionally separate from the -top-level architecture review: the architecture project tracks cross-cutting -load/startup/test structure, while this project tracks module-specific work. - -Re-review pass 2026-05-15: -- Each of the six existing review tracks (foundation, custom editing, UI / - navigation, Org workflow, programming workflow, integrations and - applications) was re-walked as if it had not been reviewed before. -- 32 new sub-task findings filed across the tracks above (foundation 5, - custom editing 6, UI / navigation 9, Org workflow 3, programming 6, - integrations 2). Findings already covered by an existing sub-task were - dropped during consolidation. -- A separate =Review newly added modules= task lists the 24 modules that - were either added after the parent task was written (post-2026-04) or - fell outside the original scope lists. Each is routed to its target - track; module-specific findings are filed under the relevant track. - -Review protocol for each module: -- Read the module directly, not just the test names. -- Check runtime dependencies, top-level side effects, keybindings, timers, - external executable assumptions, secrets, host-specific paths, and user-data - writes. -- Check existing test coverage and whether tests protect the highest-risk - behavior. -- Promote larger findings into child =PROJECT= tasks with phases. Keep small - fixes as plain =TODO= tasks. - -Priority scheme: use the top-level =Priority Scheme= section in this file. - -Suggested review order: -1. Foundation: =system-lib=, =user-constants=, =host-environment=, - =system-defaults=, =keybindings=, =config-utilities=, =early-init=, - =init=. -2. Custom editing utilities: =custom-*=, =external-open=, =media-utils=. -3. UI and navigation: =ui-*=, =font-config=, =modeline-config=, - =selection-framework=, =mousetrap-mode=, =popper-config=. -4. Org workflow: =org-*=, =calendar-sync=, =hugo-config=, =gloss-config=. -5. Programming workflow: =prog-*=, =dev-fkeys=, =test-runner=, - =coverage-*=, =vc-config=. -6. Integrations and applications: mail, Slack, ERC, Elfeed, EWW, Dirvish, - PDF, Calibre, music, recording/transcription, AI/rest tooling. - -*** DOING [#B] Harden foundation modules :harden: - -Scope: -- =system-lib.el= -- =user-constants.el= -- =host-environment.el= -- =system-defaults.el= -- =keybindings.el= -- =config-utilities.el= -- =early-init.el= -- =init.el= - -Expected output: -- Add one child task for each actionable finding. -- Note "no action" only when the module has been reviewed and no task is - needed. -- Cross-reference existing architecture tasks instead of duplicating them. - -Review progress: -- =system-lib.el=: reviewed 2026-05-03. No immediate action beyond the existing - [#B] system-lib extraction task. -- =host-environment.el=: reviewed 2026-05-03. See child tasks below. -- =user-constants.el=: reviewed 2026-05-03. See child tasks below. -- =system-defaults.el=: reviewed 2026-05-03. See child tasks below. -- =keybindings.el=: reviewed during architecture pass. No new module-specific - action beyond the load-order/keymap architecture tasks. -- =config-utilities.el=: reviewed 2026-05-03. No new module-specific action; - profiling extraction is already tracked by [#B] "Build debug-profiling.el - module". -- =early-init.el=: reviewed 2026-05-10. See child tasks below and the existing - [#B] "Split early startup from package bootstrap" task. -- =init.el=: reviewed 2026-05-10. See child tasks below and the existing - eager load-graph architecture tasks. - -Completion review 2026-05-15: -- Re-read the parent =Module-by-module review and hardening= context and the - adjacent architecture follow-up so this review stays module-specific. -- Re-checked all scoped files against the review protocol. Existing child - tasks below still cover the actionable module findings for - =user-constants.el=, =host-environment.el=, =system-defaults.el=, and - =early-init.el=. -- =system-lib.el=, =keybindings.el=, =config-utilities.el=, and =init.el= do - not need additional module-specific child tasks from this pass; remaining - concerns are already tracked by the utility-consolidation, keymap - registration, debug-profiling, and eager-load-graph architecture tasks. - -**** PROJECT [#B] Split path constants from filesystem initialization in =user-constants.el= :refactor: - -=user-constants.el= defines paths and immediately creates directories/files at -module load time. That makes a simple =(require 'user-constants)= write to the -filesystem, including org files and calendar placeholder files. This is useful -for interactive startup but brittle for tests, batch tools, and future -autoloading. +=user-constants.el= defines paths and immediately creates directories/files at +module load time. That makes a simple =(require 'user-constants)= write to the +filesystem, including org files and calendar placeholder files. This is useful +for interactive startup but brittle for tests, batch tools, and future +autoloading. ***** TODO [#B] Extract pure path definitions from startup writes :refactor: @@ -2491,7 +2195,662 @@ configuration (=text-config=, =diff-config=, =ledger-config=, =games-config=, =mu4e-org-contacts-setup=, =telega-config=, =httpd-config=, =org-agenda-config-debug=). -** VERIFY [#B] Continue org-noter custom workflow implementation (IN PROGRESS) :feature:bug: +** TODO [#C] Implement EMMS-free music-config architecture :refactor: +*** 2026-05-15 Fri @ 19:17:01 -0500 Specification +Implement the design in [[file:docs/design/music-config-without-emms.org][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. + +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. + +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. + +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. + +*** 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. + +Acceptance: structs defined, helpers callable in batch without EMMS loaded. + +Depends on: none (start here). + +*** TODO [#B] Backend protocol + fake test backend :refactor:tests: +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. + +*** TODO [#B] Read-side state API + characterization tests :tests: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. + +Acceptance: read-side helpers covered; characterization tests green against +the current EMMS-backed implementation. + +Depends on: backend protocol + fake test backend. + +*** 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. + +Acceptance: opening the playlist renders package state; reorder/shuffle/clear +go through state mutations and re-render; tests cover header + overlay +positioning. + +Depends on: read-side state API. + +*** 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=). + +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. + +Depends on: backend protocol + fake test backend. + +*** 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. + +Acceptance: full keymap functional end-to-end against the fake backend; +characterization tests still green; Dirvish =+= add path covered. + +Depends on: playlist major mode + mpv backend. + +*** TODO [#B] EMMS removal + parity walk :cleanup:tests: +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. + +Acceptance: =init.el= loads cleanly without EMMS; =make test= passes; parity +walk recorded as a completion log entry under the parent task. + +Depends on: command + Dired/Dirvish rewire. + +** TODO [#C] GPTel Tool Work + +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 +[[file:docs/design/gptel-git-tools-magit-backend.org][gptel-git-tools-magit-backend.org]]. + +*** TODO [#B] Git Related Tools + +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 [#B] Section-aware git tools :feature: + +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 [#B] Commit intent workbench :feature: + +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. + +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 [#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. + +Makes "review my diff" less ephemeral and avoids losing useful findings +inside a chat transcript. + +**** TODO [#B] Rebase and conflict coach :feature: + +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. + +The agent explains the conflict in domain terms and proposes a +resolution patch; the actual edit and =git add= stay under explicit +user control. + +**** TODO [#B] Regression archaeology :feature: + +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. + +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. + +*** TODO [#B] Org Workflow Related Tools + +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 [#B] Agenda state tools :feature: + +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 [#B] Org-roam node tools :feature: + +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 [#B] Capture creation tools :feature: + +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 [#B] Org-drill review tools :feature: + +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 [#B] Messaging Related Tools + +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. + +**** TODO [#B] Mu4e thread and compose tools :feature: + +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=. + +**** TODO [#B] Slack thread and compose tools :feature: + +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 [#B] Telegram and IRC read tools :feature: + +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. + +**** TODO [#B] Contact resolution tools :feature: + +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. + +*** TODO [#B] File and Buffer Related Tools + +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 [#B] Buffer state tools :feature: + +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 [#B] Dirvish / Dired tools :feature: + +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. + +**** TODO [#B] Vterm session tools :feature: + +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. + +*Design tension to resolve before any of these ship: one tool per +utility, or one generic =run_shell_command=?* + +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. + +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: + +- 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. + +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)=. + +The =eshell_submit= entry at the end is the escape hatch for one- +off needs the wrappers don't cover -- =:confirm t= always. + +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 [#B] Document conversion (pandoc) :feature: + +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 [#B] Image manipulation (imagemagick) :feature: + +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 [#B] Audio / video processing (ffmpeg) :feature: + +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 [#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. + +*** TODO [#B] Media and Reading Related Tools + +Affordances over non-code content: feeds, PDFs, EPUBs, music. The +agent's job here is summarize / extract / queue, not produce. + +**** TODO [#B] Elfeed entry tools :feature: + +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. + +**** TODO [#B] PDF and EPUB text tools :feature: + +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 [#B] EMMS playback and queue tools :feature: + +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 [#B] Development Workflow Related Tools + +Affordances over the dev loop: compilation output, test invocation, +coverage / profile data, flycheck / flymake diagnostics. + +**** TODO [#B] Compilation buffer tools :feature: + +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 [#B] Project test invocation tools :feature: + +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 [#B] Coverage and profile tools :feature: + +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] Diagnostic tools (flycheck / flymake) :feature: + +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. + +** TODO [#C] Review and rebind M-S- keybindings :refactor: + +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 [#C] Build cj/dev-setup-project helper (per docs/design/dev-setup-project.org) :feature: +*** 2026-05-15 Fri @ 19:17:37 -0500 Specification + +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. + +Design: [[file:../docs/design/dev-setup-project.org][docs/design/dev-setup-project.org]] + +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). + +Deferred: +- Rust (Cargo.toml), Java (pom.xml), other language shapes. +- Project-wide override config file. +- Auto-detecting external run scripts in conventional locations. + +Do this after the F-key rework ticket ships; don't want to churn project configs before the keys are stable. + +*** 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) + +Files: =modules/dev-setup-config.el= (new). No interactive surface, no I/O +beyond reading the named file. + +Acceptance: each helper callable in isolation with handcrafted fixtures; +no command yet. + +Depends on: none -- start here. + +*** TODO [#B] ERT coverage for the pure helpers :feature:tests: +Normal/Boundary/Error tests for every helper from the prior sub-task, +matching the design's testing section. + +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=). + +Acceptance: =make test-file FILE=tests/test-dev-setup-config.el= green; +every helper has at least one Normal, one Boundary, one Error case. + +Depends on: pure detection + parsing helpers. + +*** 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. + +Files: =modules/dev-setup-config.el=. + +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. + +Depends on: pure detection + parsing helpers. + +*** 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 (=;; ==== +====[ ]==, gitignore special, Makefile special). + +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). + +Acceptance: round-trip -- render proposal -> parse buffer -> equal block +list. Mode keybindings smoke-tested. + +Depends on: starter-Makefile + .dir-locals.el proposal generator. + +*** 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. + +Files: =modules/dev-setup-config.el=, plus ERT cases for the diff + +idempotent-append logic against temp dirs. + +Acceptance: re-run on an unchanged project writes nothing; renaming a +Makefile target flips one block to =WILL UPDATE=; ignore-marked files stay +untouched. + +Depends on: review-buffer major mode + parser. + +*** TODO [#B] Interactive command + smoke test :feature:tests: +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=. + +Files: =modules/dev-setup-config.el=, =tests/test-dev-setup-config.el=. Add +=(require 'dev-setup-config)= to =init.el= (or the appropriate aggregator). + +Acceptance: =M-x cj/dev-setup-project= on a fixture project opens the review +buffer; =C-c C-c= writes the expected files. + +Depends on: writer + status diff + projectile cache reset. + +*** TODO [#B] Resolve open questions + design follow-ups :cleanup: +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. + +Body: park decisions inline in the design doc or run =arch-decide= if they +turn out load-bearing. + +Depends on: none, but easiest after the writer sub-task surfaces real +friction. + +** TODO [#C] Pick and wire a debug backend for F5 :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 + +*** 2026-05-15 Fri @ 19:19:21 -0500 Inital Goals +Bind F5 globally to a debug entry point. Backend choice is the hard part: + +- 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. + +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) + +Evaluate against these projects' languages: elisp (edebug already works), Python, Go, TS, shell. Shell debug is usually print-based; skip. + +Do this after the F-key rework ticket ships so F5 is the only hole left. + +** TODO [#C] Build debug-profiling.el module :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. + +Design: [[file:../docs/design/debug-profiling.org][docs/design/debug-profiling.org]] + +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. + +** VERIFY [#C] Continue org-noter custom workflow implementation (IN PROGRESS) :feature:bug: 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. @@ -2537,7 +2896,7 @@ The core functionality is implemented but needs debugging before it's production 3. Refine toggle behavior based on testing 4. Document the final keybindings and workflow -** VERIFY [#B] Test and review restclient.el implementation :tests: +** VERIFY [#C] Test and review restclient.el implementation :tests: Test the new REST API client integration in a running Emacs session. -- cgit v1.2.3