search

atuinsh / atuin

✨ Magical shell history
https://atuin.sh
MIT License
20.28k stars 550 forks source link

API or Database Guarantees? #1208

Open mentalisttraceur opened 1 year ago

mentalisttraceur commented 1 year ago

Question

Does Atuin provide any stable interface lower-level than the CLI?

Motivation

  1. Thinking how to get Atuin into more REPLs. Ideally into every REPL which I ever use.

  2. Thinking how we can let people customize the interactive UI/UX to Atuin. Since ideal UI/UX is a very personal thing, relative to the individual user.

Concrete Use-Cases

  1. A drop-in readline replacement which uses Atuin for history.

    Let's say we start with a fork of libreadline and start customizing its history mechanism: what's the API between that code and Atuin?

  2. In something like Emacs (v29+), where composable+programmable fuzzy search APIs/UIs are available (and SQLite3 support is built-in), the path of least resistance for iterative fuzzy history search (and more resistant to becoming intolerably slow with huge histories) might be to just access the database directly.

    If Atuin isn't consciously choosing to offer its database as an interface, we should probably provide a clear path that's at least almost as easy, before Hyrum's Law makes Atuin database schemas into unofficial API that too much users and code rely on.

    (In fact, people are already doing this.)

    If we're not providing a programmatic API, we should probably officially define aspects of the database which will be stable (for example, I would create a view named history1 which for now would just be a transparent passthrough select from the history table - but when the history table's schema changes, that view would do munging in its SELECT to keep the shape/schema stable).

mentalisttraceur commented 1 year ago

Oh, if the CLI is the only API, it would be nice to have some sort of support for search/list output in a format which keeps multiline commands unambiguously delimited (and for which most languages have out-of-the-box parsers... perhaps JSON).

conradludgate commented 12 months ago

Hey, I was away from the project for a little bit but I am back. I started working on a document for stable API but I haven't yet published it. I will review the document I started writing and share it soon.

That being said:

  1. The database is not stable (it's implementation detail)
  2. the atuin-client is semi-stable but currently updates as a major version every release
  3. the cli is stable.

I am actively working towards getting a stable client API formalised, but I want to do it right.

The atuin-client should always be backwards compatible, but forwards compatibility is not something we have figured out just yet. By that I mean if you update atuin cli but there's another application that has statically linked to an old atuin-client, that version of the client could be incompatible.

Shipping dynamic libs is not something I'm willing to consider just yet.

unphased commented 18 hours ago

I invented a mechanism I've been using for like 5 years, and dear lord is it bad.

It's a shell script that manages a git repo that my history dotfiles get copied into. I set the script to run with cron on most systems. The reason I use git is just for the history tracking when history files suddenly get culled (and on occasion totally cleared out, which happens rarely but frustrates me to such a degree that I built such an abomination). But you can imagine how unwieldy such a repo is (with 33k commits now and long ago became too large to host on bitbucket).

I would love to figure out if atuin can be adapted for supporting arbitrary histories for tools... but given that it isn't ready yet it seems like I should keep searching or take a second stab at it with better architecture.