~bsprague/logseq-ui

A tool for querying specific information from Logseq and displaying it elsewhere.
Open tracked packages with `xdg-open`
Add build status badge
Attempt to add a build manifest

refs

main
browse  log 

clone

read-only
https://git.sr.ht/~bsprague/logseq-ui
read/write
git@git.sr.ht:~bsprague/logseq-ui

You can also use your local clone with git send-email.

#Logseq UI

builds.sr.ht status

A tool for querying specific information from Logseq and displaying it in a simple terminal UI modelled on k9s.

Current functionality:

  • Viewing and filtering by areas
  • Viewing projects
  • Viewing the inbox/next/someday/scheduled/focus lists items
  • Viewing tracked shipments
    • Kind of an oddball, but shows how you can add arbitrary metadata in Logseq via properties and query on it

#Usage

go run ./cmd/logseq-ui --api_key=$APIKEY

#Running Tests

There are two types of tests: normal unit tests, and bigger integration tests against a live Logseq (these are read-only!). The live integration tests require an --api_key and optionally a --logseq_api_endpoint if not running locally at :12315/api

To run normal unit tests: go test -v ./...

To run integration tests: TEST_LIVE_LOGSEQ=true go test -v ./cmd/backend-test/ --api_key=$APIKEY

To run (only) benchmarks: TEST_LIVE_LOGSEQ=true go test -bench=. -run='^$' -v ./cmd/backend-test/ --api_key=$(pass show logseq/api)

#Keybindings

  • Anywhere
    • : to open the command list
      • Things like `project/area/inbox/next/tracking
    • [Not yet implemented] / to filter current list
  • On a list of items
    • j/k/<Up>/<Down>/<Tab> to navigate items in the list
    • h to go over to the Actions + Projects panes
    • <Space> to toggle TODO/DONE state
    • f to toggle focused
    • t to toggle triage/next
    • o to open the task/block in Logseq
    • x to toggle cancelled
    • s to toggle to someday/maybe
    • [Not functional yet] e to edit the item in $EDITOR and apply the changes
  • On a list of packages/tracked items
    • o to open the task/block in Logseq
    • r to mark as received
    • n to open "New Task" page
      • This doesn't actually work yet

#Debugging

The tool has a debug mode that logs Logseq response bodies (and assorted errors) to stderr, which is useful for adding/testing new queries.

go run . --api_key=$APIKEY --debug 2> debug.log

# In a new terminal
tail -f debug.log

#Loading Data from Logseq

There are currently two backends for loading data from Logseq. They both use the HTTP API and Datalog queries to access data. You choose which one you want by setting --backend=datalog or --backend=mem at start up.

  • datalog - The Datalog backend issues live queries to Logseq whenever data is queried (i.e. when changing views, areas, etc). The benefit of this is that the data is always fresh. The downside is that it might be slower (especially since my queries might not be optimal)
  • mem - The in-memory backend issues a single giant fetch for all tasks on boot, and does subsequent filtering in memory/Go. The benefit is that subsequent queries (and even the initial one) are pretty fast. The downside is that it polls (by default every 10 seconds) for updates to data, meaning that things can be stale for ~10 seconds.

The mem backend was introduced because the Datalog queries were getting hard to reason about and slow, but between some help on the forums (thanks mentaloid!) and a parity-checking integration test suite, both backends should now return identical data and be similarly fast.

Some caveats about the mem backend:

  • Make sure to set :feature/enable-block-timestamps? true in config.edn
    • Otherwise the periodic/polling fetch won't pick up changes and data will get stale
  • If you delete a block, it won't pick up on it
    • This is fairly minor, but I'm not sure if there's an easy-ish and performant-ish way to handle this within Logseq's current API.

#TODO

  • Basic support for creating items in a given context (project, area, inbox, etc)
    • In-progress, press n to open non-functional modal
  • Implement ?, a way to pull up a list of keys
    • Currently using ? for debugging
  • Add support for showing non-active projects
    • Should generally be part of filtering what items we're looking at, like Viewing: {All, Active, Waiting, Done, etc}
  • Finish implementing key bindings for the task view page
  • Add basic support for reordering blocks
    • Will need to think about it more, but maybe just a sort-top: <timestamp> property is enough for our needs, and can hide it in Logseq config
  • Implement some kind of fuzzy search
    • The / opens a search...but it does nothing
  • Indicate if a note has contents (i.e. children), and allow selecting an item to view details
    • In-progress - Can view note, but no indication if a note has children
    • See taskView for more of the shape of this.
  • Surface errors as a modal instead of a log to stderr/use both
  • Implement a Logseq search, like /, but actually searches all tasks (in area) in Logseq directly
  • Persist last state (area, filters) to a config file or similar

#Done

  • Should be able to open a page by pressing o on a project.
  • Finish implementing $EDITOR stuff
  • Update Focus to include items with soon due deadlines and scheduled things
  • Implement Scheduled
  • Improve queries to be more exact
    • Things like "checking for parents with markers more consistently" and "using consistent queries for properties"
  • Other item editing, e.g. triaging, focusing, etc
  • Implement Waiting and Someday/Maybe
  • Mark items done with <Space>
  • Have selecting a project open a list of its items