kjump.py

#!/usr/bin/python3
"""
kjump — trigger a run-or-raise entry from the command line.

`kjump <entry>` does exactly what pressing the entry's global shortcut
does: raise a matching window if one is open, otherwise launch the
configured command. <entry> matches an entry's id or name
(case-insensitive), so it works from scripts (stable ids) or by hand
(friendly names). Useful for automation: bind it to a hardware key, wire
it into a KRunner alias, or call it from any shell script.

This is a thin D-Bus client for the kjumpd daemon (org.kjump.Daemon) —
the daemon does the actual raise/launch. If the daemon isn't running,
nothing happens and kjump says so.

Usage:
    kjump <entry>          trigger the entry by id or name
    kjump --list, -l       list configured entries (id and name)
    kjump --version, -V    print version
    kjump --help,  -h      this message

Exit status:
    0  entry triggered, or list printed
    1  no matching entry, daemon not running, or bad usage
"""

import json
import sys

import dbus

# Bump in lockstep with kjumpd.py and kjump-config.py — single-file scripts,
# no shared module to centralise it (see CLAUDE.md conventions).
__version__ = "0.1.0"

BUS_NAME = "org.kjump.Daemon"
OBJ_PATH = "/Daemon"

# D-Bus errors that mean "the daemon isn't there" as opposed to a genuine
# failure talking to a running daemon.
_DAEMON_DOWN = (
    "org.freedesktop.DBus.Error.ServiceUnknown",
    "org.freedesktop.DBus.Error.NameHasNoOwner",
)


def service():
    """Return a proxy to the running daemon, or exit with a helpful message
    if it isn't reachable."""
    try:
        obj = dbus.SessionBus().get_object(BUS_NAME, OBJ_PATH)
        return dbus.Interface(obj, BUS_NAME)
    except dbus.exceptions.DBusException as e:
        if e.get_dbus_name() in _DAEMON_DOWN:
            sys.exit("kjump: daemon not running "
                     "(start it with: systemctl --user start kjumpd)")
        sys.exit(f"kjump: cannot reach daemon: {e}")


def cmd_list(svc):
    entries = json.loads(str(svc.List()))
    if not entries:
        print("no entries configured (add some with kjump-config)")
        return 0
    width = max(len(e["id"]) for e in entries)
    for e in entries:
        print(f"{e['id']:<{width}}  {e['name']}")
    return 0


def cmd_trigger(svc, query):
    if not str(svc.Trigger(query)):
        print(f"kjump: no entry matching {query!r}", file=sys.stderr)
        print("      run `kjump --list` to see configured entries",
              file=sys.stderr)
        return 1
    return 0


def main():
    args = sys.argv[1:]

    if not args:
        print(__doc__.strip(), file=sys.stderr)
        return 1
    if args[0] in ("-h", "--help"):
        print(__doc__.strip())
        return 0
    if args[0] in ("-V", "--version"):
        print(f"kjump {__version__}")
        return 0
    if args[0] in ("-l", "--list"):
        return cmd_list(service())
    if len(args) > 1:
        print("kjump: expected a single entry name\n"
              "usage: kjump <entry> | kjump --list", file=sys.stderr)
        return 1

    return cmd_trigger(service(), args[0])


if __name__ == "__main__":
    sys.exit(main())