feat: pearl — manage Linear issues from org-mode

Pearl fetches Linear issues into an org file and syncs edits back. It covers list / custom views / saved queries, per-issue and bulk rendering with comments inline, conflict-aware sync of descriptions, titles, and comments, field commands for priority / state / assignee / labels, and a transient dispatch menu. The render folds to a scannable outline and nests issues under a sortable parent.

Based on and inspired by Gael Blanchemain's linear-emacs.

1 files changed, 65 insertions, 0 deletions

diff --git a/docs/issue-sort-order-spec.org b/docs/issue-sort-order-spec.org
new file mode 100644
index 0000000..f49e869
--- /dev/null
+++ b/docs/issue-sort-order-spec.org
@@ -0,0 +1,65 @@
+#+TITLE: pearl — Interactive Sort/Order Spec
+#+AUTHOR: Craig Jennings
+#+DATE: 2026-05-24
+#+STARTUP: showall
+
+* Status
+
+*DRAFT — design proposal; nothing in =pearl.el= has changed.* Open questions for Craig at the end.
+
+Companion to [[file:issue-query-spec.org][issue-query-spec.org]], which defines the =:sort= / =:order= the saved-query layer already supports. This doc covers changing the order of the *current* view interactively, without hand-editing a saved query.
+
+* Problem
+
+v1 supports =:sort= (=updated= / =priority= / =title=) and =:order= (=asc= / =desc=) on saved queries. But to change how the active file is ordered, the user has to edit =pearl-saved-queries= (or the source plist) by hand and re-run. There's no "sort this view by priority, descending" command. For a view you're actually looking at, that's the natural thing to want.
+
+* Current state
+
+- =pearl--sort-issues= (query spec) applies =:sort= / =:order= client-side at the render boundary, so a refresh always lays headings out the same way.
+- =:sort= = =priority= / =title= are client-side; =created= / =updated= map to the server =orderBy= (the only fields Linear's API orders on). The query spec documents this split.
+- The active file's =#+LINEAR-SOURCE:= header records the source plist, including any =:sort= / =:order=, so =refresh-current-view= reproduces the ordering.
+
+* Proposed design
+
+** The command
+
+=pearl-set-sort= (interactive), run in the active file:
+
+1. =completing-read= the sort key: =updated=, =created=, =priority=, =title=.
+2. =completing-read= (or a toggle) the order: =asc= / =desc=.
+3. Update the =:sort= / =:order= in the active file's recorded =#+LINEAR-SOURCE:=.
+4. Re-order the view (see below).
+
+A =pearl-toggle-sort-order= convenience command just flips =asc=/=desc= on the current sort and re-orders. Both go on the transient menu (a small "Sort" group, or under View).
+
+** Re-order in place vs refetch
+
+The split matters for whether a sort change needs the network:
+
+- *Client-side sorts* (=priority=, =title=): the issues are already in the buffer. Re-sort in place — reparse the issue subtrees, reorder them, rewrite. No refetch. Fast, works offline.
+- *Server-side sorts* (=created=, =updated=): the ordering comes from the server =orderBy=, and the fetch may have been truncated at the page cap, so the correct order needs a refetch with the new =orderBy=. Re-run the source (the =refresh-current-view= path) with the updated sort.
+
+So =set-sort= decides: client-side key → re-sort the buffer; server-side key → refetch. The command reports which it did.
+
+** Persistence
+
+The change updates the active file's =#+LINEAR-SOURCE:= so a later =refresh-current-view= keeps the new order. Whether it also writes back to a named saved query in =pearl-saved-queries= is open question 3 — my lean is no by default (the active file is the scratch view; saved queries are the durable definitions), with an explicit "save this ordering to the query" as a separate step.
+
+* Proposed v1 decisions (this feature)
+
+1. =pearl-set-sort= + =pearl-toggle-sort-order=, both on the transient menu.
+2. Client-side keys re-sort the buffer in place; server-side keys refetch.
+3. The change updates the active file's recorded source so refresh preserves it.
+4. Completion is over the known keys/orders, never free text.
+
+* vNext / out of scope
+
+- Multi-key sort (e.g. priority then updated).
+- Per-heading manual reordering that sticks across refresh.
+- Exposing the full Linear =orderBy= surface if the API later un-gates the =[INTERNAL]= per-field sort.
+
+* Open questions for Craig
+
+1. *Command vs transient-only*: a plain =M-x pearl-set-sort= with two completing-reads, or a dedicated transient sub-menu with one-key sort toggles (=p= priority, =u= updated, =t= title, =o= flip order)? The transient reads faster for a frequent action.
+2. *In-place re-sort fidelity*: re-sorting client-side means reparsing and rewriting issue subtrees in the buffer. Acceptable, or prefer always-refetch for simplicity even when a client-side sort wouldn't need it?
+3. *Write-back*: should changing the sort offer to persist it to the originating saved query, or only ever update the active file's header?