live-cmd 0.1.0__py3-none-any.whl

live/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

live/cli.py

@@ -0,0 +1,250 @@
+"""Top-level CLI dispatch: `live <verb> ...`."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+from . import verbs
+
+
+def _count_or_cursor(prefix: str):
+    """Build a parser for `N` (count) or `<prefix>N` (cursor) on `-n` / `-c`.
+
+    `tail` uses `+N` (lines `n >= N`, Unix); `head` uses `-N` (drop last N,
+    GNU). The opposite sign is accepted but treated as a plain count.
+    """
+
+    def parse(value: str) -> tuple[str, int]:
+        if value.startswith(prefix):
+            rest = value[1:]
+            if rest.isdigit():
+                return ("cursor", int(rest))
+        elif value.startswith(("+", "-")) and value[1:].isdigit():
+            return ("count", int(value[1:]))
+        elif value.isdigit():
+            return ("count", int(value))
+        raise argparse.ArgumentTypeError(f"expected N or {prefix}N (got {value!r})")
+
+    return parse
+
+
+def _make_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(
+        prog="live",
+        description="Stream long-lived command output to coding agents.",
+        add_help=True,
+    )
+    p.add_argument("--version", action="version", version=f"live {__version__}")
+    sub = p.add_subparsers(dest="verb", metavar="<verb>")
+
+    # run
+    run_p = sub.add_parser("run", help="Run <cmd> under a PTY; record.")
+    run_p.add_argument(
+        "-n", "--name", default=None, help="Session name."
+    )
+    run_p.add_argument(
+        "cmd",
+        nargs=argparse.REMAINDER,
+        help="Command to run; `--` for flag-starting commands.",
+    )
+    run_p.set_defaults(func=verbs.cmd_run)
+
+    # ls
+    ls_p = sub.add_parser("ls", help="List sessions in scope.")
+    ls_p.add_argument("-a", "--all", action="store_true", help="Include exited.")
+    ls_p.add_argument(
+        "-g",
+        "--global",
+        action="store_true",
+        dest="global_",
+        help="Global scope.",
+    )
+    ls_p.add_argument("--json", action="store_true", help="Emit NDJSON.")
+    ls_p.add_argument(
+        "selector", nargs="?", default=None, help="NAME or UUID-prefix filter."
+    )
+    ls_p.set_defaults(func=verbs.cmd_ls)
+
+    # cat
+    cat_p = sub.add_parser("cat", help="Concatenate session.")
+    cat_p.add_argument("-v", "--verbose", action="store_true", help="Verbose output.")
+    cat_p.add_argument(
+        "-g",
+        "--global",
+        action="store_true",
+        dest="global_",
+        help="Global scope.",
+    )
+    ag = cat_p.add_mutually_exclusive_group()
+    ag.add_argument(
+        "--strip-ansi",
+        action="store_true",
+        dest="strip_ansi",
+        help="Strip ANSI.",
+    )
+    ag.add_argument("--raw", action="store_true", dest="raw", help="Keep ANSI.")
+    cat_p.add_argument("selector", help="NAME or UUID-prefix.")
+    cat_p.set_defaults(func=verbs.cmd_cat)
+
+    # head
+    head_p = sub.add_parser("head", help="Head session.")
+    head_p.add_argument("-v", "--verbose", action="store_true", help="Verbose output.")
+    head_p.add_argument(
+        "-g",
+        "--global",
+        action="store_true",
+        dest="global_",
+        help="Global scope.",
+    )
+    ag = head_p.add_mutually_exclusive_group()
+    ag.add_argument(
+        "--strip-ansi",
+        action="store_true",
+        dest="strip_ansi",
+        help="Strip ANSI.",
+    )
+    ag.add_argument("--raw", action="store_true", dest="raw", help="Keep ANSI.")
+    mode = head_p.add_mutually_exclusive_group()
+    mode.add_argument(
+        "-n",
+        "--lines",
+        type=_count_or_cursor("-"),
+        default=None,
+        help="First N lines (default 10); -N drops last N.",
+    )
+    mode.add_argument(
+        "-c",
+        "--bytes",
+        dest="bytes_",
+        metavar="BYTES",
+        type=_count_or_cursor("-"),
+        default=None,
+        help="First K bytes; -K drops last K.",
+    )
+    mode.add_argument(
+        "-t",
+        "--time",
+        type=float,
+        default=None,
+        help="Lines with idx t <= T (epoch).",
+    )
+    head_p.add_argument("selector", help="NAME or UUID-prefix.")
+    head_p.set_defaults(func=verbs.cmd_head)
+
+    # tail
+    tail_p = sub.add_parser("tail", help="Tail session.")
+    tail_p.add_argument(
+        "-f", "--follow", action="store_true", help="Follow until exit."
+    )
+    tail_p.add_argument("-v", "--verbose", action="store_true", help="Verbose output.")
+    tail_p.add_argument(
+        "-g",
+        "--global",
+        action="store_true",
+        dest="global_",
+        help="Global scope.",
+    )
+    ag = tail_p.add_mutually_exclusive_group()
+    ag.add_argument(
+        "--strip-ansi",
+        action="store_true",
+        dest="strip_ansi",
+        help="Strip ANSI.",
+    )
+    ag.add_argument("--raw", action="store_true", dest="raw", help="Keep ANSI.")
+    mode = tail_p.add_mutually_exclusive_group()
+    mode.add_argument(
+        "-n",
+        "--lines",
+        type=_count_or_cursor("+"),
+        default=None,
+        help="Last N lines (default 10); +N for lines n >= N.",
+    )
+    mode.add_argument(
+        "-c",
+        "--bytes",
+        dest="bytes_",
+        metavar="BYTES",
+        type=_count_or_cursor("+"),
+        default=None,
+        help="Last K bytes; +K for bytes after offset K.",
+    )
+    mode.add_argument(
+        "-t",
+        "--time",
+        type=float,
+        default=None,
+        help="Lines with idx t > T (epoch).",
+    )
+    tail_p.add_argument("selector", help="NAME or UUID-prefix.")
+    tail_p.set_defaults(func=verbs.cmd_tail)
+
+    # rm
+    rm_p = sub.add_parser("rm", help="Delete sessions.")
+    rm_p.add_argument(
+        "-f",
+        "--force",
+        action="store_true",
+        help="SIGTERM live runs; ignore missing.",
+    )
+    rm_p.add_argument(
+        "-g",
+        "--global",
+        action="store_true",
+        dest="global_",
+        help="Global scope.",
+    )
+    rm_p.add_argument(
+        "--all-exited",
+        action="store_true",
+        dest="all_exited",
+        help="Remove all dead sessions.",
+    )
+    rm_p.add_argument(
+        "selectors", nargs="*", help="NAME(s) or UUID-prefix(es)."
+    )
+    rm_p.set_defaults(func=verbs.cmd_rm)
+
+    # llms.txt
+    llms_p = sub.add_parser("llms.txt", help="Print agent guide.")
+    llms_p.set_defaults(func=verbs.cmd_llms_txt)
+
+    # completion
+    comp_p = sub.add_parser("completion", help="Print shell completion script.")
+    comp_p.add_argument("shell", choices=["bash", "zsh", "fish"])
+    comp_p.set_defaults(func=verbs.cmd_completion)
+
+    # update-shell
+    up_p = sub.add_parser(
+        "update-shell", help="Install completion for the current shell."
+    )
+    up_p.add_argument(
+        "shell",
+        nargs="?",
+        choices=["bash", "zsh", "fish"],
+        default=None,
+        help="Target shell (default: $SHELL).",
+    )
+    up_p.set_defaults(func=verbs.cmd_update_shell)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = argv if argv is not None else sys.argv[1:]
+    parser = _make_parser()
+
+    parsed = parser.parse_args(args)
+    if not getattr(parsed, "verb", None):
+        parser.print_help()
+        return 0
+    try:
+        return parsed.func(parsed)
+    except KeyboardInterrupt:
+        return 130
+
+
+if __name__ == "__main__":
+    sys.exit(main())

live/completion.py

@@ -0,0 +1,312 @@
+"""Shell completion script payloads, returned by `live completion <shell>`.
+
+Each script offers verb completion, per-verb flag completion, selector
+completion (NAME or UUID via `live ls --json`), and `live run <TAB>` handoff
+to the wrapped command's completion. The selector helper mirrors the verb's
+scope flags: `ls` only suggests active sessions unless `-a` was typed;
+`cat`/`tail`/`rm` always pass `-a` since exited sessions remain valid
+targets. `-g` is honored when present in the command line.
+"""
+
+from __future__ import annotations
+
+
+BASH = r"""# bash completion for live
+_live_complete() {
+    local cur prev words cword
+    _init_completion -n : 2>/dev/null || {
+        cur="${COMP_WORDS[COMP_CWORD]}"
+        words=("${COMP_WORDS[@]}")
+        cword=$COMP_CWORD
+    }
+
+    # Find the verb (first non-flag token after `live`).
+    local verb verb_idx
+    for ((i=1; i<cword; i++)); do
+        case "${words[i]}" in
+            -*) continue ;;
+            *) verb="${words[i]}"; verb_idx=$i; break ;;
+        esac
+    done
+
+    if [ -z "$verb" ]; then
+        COMPREPLY=( $(compgen -W "run ls cat head tail rm llms.txt completion update-shell" -- "$cur") )
+        return
+    fi
+
+    case "$verb" in
+        run)
+            # If the user has typed a non-flag arg after `run`, hand off to the wrapped
+            # command's completion via _command_offset.
+            local seen_cmd=0
+            for ((i=verb_idx+1; i<cword; i++)); do
+                case "${words[i]}" in
+                    --) seen_cmd=$((i+1)); break ;;
+                    -n) i=$((i+1)) ;;
+                    -*) ;;
+                    *) seen_cmd=$i; break ;;
+                esac
+            done
+            if [ "$seen_cmd" -gt 0 ] && type _command_offset >/dev/null 2>&1; then
+                _command_offset $seen_cmd
+                return
+            fi
+            COMPREPLY=( $(compgen -W "-n --" -- "$cur") )
+            ;;
+        ls)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "-a --all -g --global --json" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "$(_live_selectors $(_live_all_flag) $(_live_global_flag))" -- "$cur") )
+            fi
+            ;;
+        cat)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "-v --verbose -g --global --strip-ansi --raw" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "$(_live_selectors -a $(_live_global_flag))" -- "$cur") )
+            fi
+            ;;
+        head)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "-v --verbose -g --global --strip-ansi --raw -n --lines -c --bytes -t --time" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "$(_live_selectors -a $(_live_global_flag))" -- "$cur") )
+            fi
+            ;;
+        tail)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "-v --verbose -f --follow -g --global --strip-ansi --raw -n --lines -c --bytes -t --time" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "$(_live_selectors -a $(_live_global_flag))" -- "$cur") )
+            fi
+            ;;
+        rm)
+            if [[ "$cur" == -* ]]; then
+                COMPREPLY=( $(compgen -W "-f --force -g --global --all-exited" -- "$cur") )
+            else
+                COMPREPLY=( $(compgen -W "$(_live_selectors -a $(_live_global_flag))" -- "$cur") )
+            fi
+            ;;
+        completion|update-shell)
+            COMPREPLY=( $(compgen -W "bash zsh fish" -- "$cur") )
+            ;;
+    esac
+}
+
+_live_all_flag() {
+    local w
+    for w in "${words[@]:1}"; do
+        case "$w" in -a|--all) echo -a; return ;; esac
+    done
+}
+
+_live_global_flag() {
+    local w
+    for w in "${words[@]:1}"; do
+        case "$w" in -g|--global) echo -g; return ;; esac
+    done
+}
+
+_live_selectors() {
+    live ls "$@" --json 2>/dev/null \
+        | awk -F'"' '{ for (i=1;i<=NF;i++) if ($i=="id"||$i=="name") print $(i+2) }' \
+        | sort -u
+}
+
+complete -F _live_complete live
+"""
+
+
+ZSH = r"""#compdef live
+
+_live() {
+    local context state line
+    typeset -A opt_args
+
+    _arguments -C \
+        '1: :_live_verbs' \
+        '*::arg:->args' \
+        && return 0
+
+    case $state in
+        args)
+            case $words[1] in
+                run)
+                    # Complete our flag before the wrapped command; any non-flag
+                    # word triggers `_normal` against the wrapped command.
+                    _arguments -S \
+                        '-n+[session name]:name:' \
+                        '*::command:_normal'
+                    ;;
+                ls)
+                    _arguments \
+                        '(-a --all)'{-a,--all} \
+                        '(-g --global)'{-g,--global} \
+                        '--json' \
+                        '1:selector:_live_selectors'
+                    ;;
+                cat)
+                    _arguments \
+                        '(-v --verbose)'{-v,--verbose} \
+                        '(-g --global)'{-g,--global} \
+                        '(--strip-ansi --raw)--strip-ansi' \
+                        '(--strip-ansi --raw)--raw' \
+                        '1:selector:_live_selectors'
+                    ;;
+                head)
+                    _arguments \
+                        '(-v --verbose)'{-v,--verbose} \
+                        '(-g --global)'{-g,--global} \
+                        '(--strip-ansi --raw)--strip-ansi' \
+                        '(--strip-ansi --raw)--raw' \
+                        '(-n --lines)'{-n+,--lines=}':lines:' \
+                        '(-c --bytes)'{-c+,--bytes=}':bytes:' \
+                        '(-t --time)'{-t+,--time=}':epoch-seconds:' \
+                        '1:selector:_live_selectors'
+                    ;;
+                tail)
+                    _arguments \
+                        '(-v --verbose)'{-v,--verbose} \
+                        '(-f --follow)'{-f,--follow} \
+                        '(-g --global)'{-g,--global} \
+                        '(--strip-ansi --raw)--strip-ansi' \
+                        '(--strip-ansi --raw)--raw' \
+                        '(-n --lines)'{-n+,--lines=}':lines:' \
+                        '(-c --bytes)'{-c+,--bytes=}':bytes:' \
+                        '(-t --time)'{-t+,--time=}':epoch-seconds:' \
+                        '1:selector:_live_selectors'
+                    ;;
+                rm)
+                    _arguments \
+                        '(-f --force)'{-f,--force} \
+                        '(-g --global)'{-g,--global} \
+                        '--all-exited' \
+                        '*:selector:_live_selectors'
+                    ;;
+                completion|update-shell)
+                    _arguments '1:shell:(bash zsh fish)'
+                    ;;
+            esac
+            ;;
+    esac
+}
+
+_live_verbs() {
+    local -a verbs
+    verbs=(
+        'run:Wrap <cmd> under a PTY and record'
+        'ls:List sessions in scope'
+        'cat:Concatenate stream.*.log for a session'
+        'head:Head first lines of a session'
+        'tail:Tail a session'
+        'rm:Delete sessions'
+        'llms.txt:Print a token-minimal agent guide'
+        'completion:Print shell completion script'
+        'update-shell:Install completion for the current shell'
+    )
+    _describe -t verbs 'verb' verbs
+}
+
+# Selector completion. For `live ls`, only suggest active sessions unless -a
+# was typed; for other verbs, always include exited (still valid targets).
+# Honors -g/--global when present in the command line.
+_live_selectors() {
+    local -a sel_args names
+    local w want_all=0 want_global=0
+    for w in $words[@]; do
+        case $w in
+            -a|--all) want_all=1 ;;
+            -g|--global) want_global=1 ;;
+        esac
+    done
+    if [[ $words[1] != ls ]] || (( want_all )); then
+        sel_args+=(-a)
+    fi
+    (( want_global )) && sel_args+=(-g)
+    names=( ${(f)"$(live ls $sel_args --json 2>/dev/null | awk -F'"' '{ for (i=1;i<=NF;i++) if ($i=="id"||$i=="name") print $(i+2) }' | sort -u)"} )
+    (( $#names )) && _values 'selector' "${names[@]}"
+}
+
+_live "$@"
+"""
+
+
+FISH = r"""# fish completion for live
+
+function __live_selectors
+    set -l toks (commandline -opc)
+    set -l verb $toks[2]
+    set -l args
+    if test "$verb" != "ls"; or contains -- -a $toks; or contains -- --all $toks
+        set -a args -a
+    end
+    if contains -- -g $toks; or contains -- --global $toks
+        set -a args -g
+    end
+    live ls $args --json 2>/dev/null | string match -rga '"(?:id|name)":"([^"]+)"' | sort -u
+end
+
+set -l verbs run ls cat head tail rm llms.txt completion update-shell
+
+complete -c live -f
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a run -d 'Wrap <cmd> under a PTY'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a ls -d 'List sessions'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a cat -d 'Concatenate stream.*.log'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a head -d 'Head first lines of a session'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a tail -d 'Tail a session'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a rm -d 'Delete sessions'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a llms.txt -d 'Print agent guide'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a completion -d 'Print completion script'
+complete -c live -n "not __fish_seen_subcommand_from $verbs" -a update-shell -d 'Install completion for current shell'
+
+# Selector completion for ls / cat / head / tail / rm.
+complete -c live -n "__fish_seen_subcommand_from ls cat head tail rm" -a "(__live_selectors)"
+
+# ls
+complete -c live -n "__fish_seen_subcommand_from ls" -s a -l all -d 'Include exited sessions'
+complete -c live -n "__fish_seen_subcommand_from ls" -s g -l global -d 'Show sessions from all directories'
+complete -c live -n "__fish_seen_subcommand_from ls" -l json -d 'Emit NDJSON'
+
+# cat
+complete -c live -n "__fish_seen_subcommand_from cat" -s v -l verbose -d 'Add stderr metadata'
+complete -c live -n "__fish_seen_subcommand_from cat" -s g -l global -d 'Resolve selector globally'
+complete -c live -n "__fish_seen_subcommand_from cat" -l strip-ansi -d 'Remove ANSI escapes'
+complete -c live -n "__fish_seen_subcommand_from cat" -l raw -d 'Keep ANSI escapes'
+
+# head
+complete -c live -n "__fish_seen_subcommand_from head" -s v -l verbose
+complete -c live -n "__fish_seen_subcommand_from head" -s g -l global -d 'Resolve selector globally'
+complete -c live -n "__fish_seen_subcommand_from head" -l strip-ansi
+complete -c live -n "__fish_seen_subcommand_from head" -l raw
+complete -c live -n "__fish_seen_subcommand_from head" -s n -l lines -r -d 'First N lines (default 10)'
+complete -c live -n "__fish_seen_subcommand_from head" -s c -l bytes -r -d 'First K bytes'
+complete -c live -n "__fish_seen_subcommand_from head" -s t -l time -r -d 'Lines with t <= T (epoch seconds)'
+
+# tail
+complete -c live -n "__fish_seen_subcommand_from tail" -s v -l verbose
+complete -c live -n "__fish_seen_subcommand_from tail" -s f -l follow -d 'Follow new lines'
+complete -c live -n "__fish_seen_subcommand_from tail" -s g -l global -d 'Resolve selector globally'
+complete -c live -n "__fish_seen_subcommand_from tail" -l strip-ansi
+complete -c live -n "__fish_seen_subcommand_from tail" -l raw
+complete -c live -n "__fish_seen_subcommand_from tail" -s n -l lines -r -d 'Last N lines'
+complete -c live -n "__fish_seen_subcommand_from tail" -s c -l bytes -r -d 'Last K bytes'
+complete -c live -n "__fish_seen_subcommand_from tail" -s t -l time -r -d 'Time cursor (epoch seconds)'
+
+# rm
+complete -c live -n "__fish_seen_subcommand_from rm" -s f -l force -d 'Kill running recorders'
+complete -c live -n "__fish_seen_subcommand_from rm" -s g -l global -d 'Resolve selectors globally'
+complete -c live -n "__fish_seen_subcommand_from rm" -l all-exited -d 'Remove every dead session'
+
+# run -- hand off after first non-flag token.
+complete -c live -n "__fish_seen_subcommand_from run" -s n -r -d 'Session name'
+complete -c live -n "__fish_seen_subcommand_from run; and __fish_complete_subcommand --skip 2" \
+    -a "(__fish_complete_subcommand --skip 2)"
+
+# completion / update-shell
+complete -c live -n "__fish_seen_subcommand_from completion update-shell" -a "bash zsh fish"
+"""
+
+
+def script_for(shell: str) -> str | None:
+    return {"bash": BASH, "zsh": ZSH, "fish": FISH}.get(shell)

live/config.py

@@ -0,0 +1,80 @@
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+from .paths import config_path
+
+
+DEFAULTS = {
+    "ttlDays": 7,
+    "maxKb": 512,
+    "segmentKb": 64,
+    "heartbeatSec": 30,
+}
+
+
+_VALIDATORS = {
+    "ttlDays": lambda v: isinstance(v, int) and not isinstance(v, bool) and v >= 0,
+    "maxKb": lambda v: isinstance(v, int) and not isinstance(v, bool) and v > 0,
+    "segmentKb": lambda v: isinstance(v, int) and not isinstance(v, bool) and v > 0,
+    "heartbeatSec": lambda v: isinstance(v, int) and not isinstance(v, bool) and v > 0,
+}
+
+
+@dataclass(frozen=True)
+class Config:
+    ttl_days: int
+    max_kb: int
+    segment_kb: int
+    heartbeat_sec: int
+
+    @property
+    def max_bytes(self) -> int:
+        return self.max_kb * 1024
+
+    @property
+    def segment_bytes(self) -> int:
+        return self.segment_kb * 1024
+
+
+def _load_file(path: Path) -> dict[str, int]:
+    """Read config; return {} for missing/malformed (warns on malformed)."""
+    if not path.exists():
+        return {}
+    try:
+        with path.open("r", encoding="utf-8") as f:
+            raw = json.load(f)
+    except (OSError, ValueError) as e:
+        print(f"live: malformed config at {path}: {e} — falling back to defaults",
+              file=sys.stderr)
+        return {}
+    if not isinstance(raw, dict):
+        return {}
+    out: dict[str, int] = {}
+    for key, val in raw.items():
+        validator = _VALIDATORS.get(key)
+        if validator is None:
+            continue
+        if validator(val):
+            out[key] = val
+    return out
+
+
+def load_config() -> Config:
+    """Read `~/.live/config.json`, falling back per-field to compiled defaults."""
+    cfg_path = config_path()
+    if not cfg_path.exists():
+        try:
+            cfg_path.write_text(json.dumps(DEFAULTS) + "\n")
+        except OSError:
+            pass
+    merged = {**DEFAULTS, **_load_file(cfg_path)}
+    return Config(
+        ttl_days=int(merged["ttlDays"]),
+        max_kb=int(merged["maxKb"]),
+        segment_kb=int(merged["segmentKb"]),
+        heartbeat_sec=int(merged["heartbeatSec"]),
+    )