live-cmd 0.1.0__tar.gz

live_cmd-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.DS_Store
+__pycache__
+.pytest_cache/
+.venv/
+dist/
+build/
+*.egg-info/

live_cmd-0.1.0/DESIGN.md

@@ -0,0 +1,91 @@
+# `live` — design
+
+Stream long-lived command output to coding agents. `live run <cmd>` runs `<cmd>` under a PTY, mirrors output to the terminal, and records the bytes to disk under `~/.live/`. Agents read with `live cat`, `live tail`, or resumable `live tail -n +N`, piping to `grep`/`awk` as needed.
+
+The recorder is the sole writer per session and holds an exclusive `flock` on `process.lock` for its lifetime — that lock IS the liveness signal. Read verbs hold no per-process state and piggyback lifecycle sweeps. No daemon, no broker, no persistent server.
+
+Python 3.14+, POSIX-only (Linux, macOS, WSL). Zero runtime deps — PTY, flock, ioctl, signals, atomic rename, struct packing, JSON, UUIDv7, and the kqueue/inotify primitives that power `tail -f` are all stdlib. PyPI: `live-cmd`.
+
+## CLI
+
+| Verb                                                | Purpose                                                                                |
+| --------------------------------------------------- | -------------------------------------------------------------------------------------- |
+| `live run [-n NAME] [--] <cmd…>`                    | Run `<cmd>` under a PTY; record.                                                       |
+| `live ls [-a] [-g] [--json] [SELECTOR]`             | List sessions in scope; `SELECTOR` filters by NAME or UUID-prefix.                     |
+| `live cat [-v] [-g] [--strip-ansi\|--raw] <SEL>`    | Concatenate session.                                                                   |
+| `live head [-v] [-g] [-n N\|-c K\|-t T] <SEL>`      | `-n N` first N lines (default 10; `-N` drops last N), `-c K` first K bytes (`-K` drops last K), `-t T` lines with idx `t <= T`. |
+| `live tail [-f] [-v] [-g] [-n N\|-c K\|-t T] <SEL>` | `-n N` last N lines (default 10; `+N` for `n >= N`), `-c K` last K bytes (`+K` for bytes past offset K), `-t T` lines with idx `t > T`; `-f` follows. |
+| `live rm [-f] [-g] [--all-exited] <SEL…>`           | Delete sessions; `-f` SIGTERMs live runs.                                              |
+| `live llms.txt`                                     | Print agent guide.                                                                     |
+| `live completion <bash\|zsh\|fish>`                 | Print shell completion.                                                                |
+| `live update-shell [SHELL]`                         | Install completion for `$SHELL` (or override).                                         |
+
+`live <verb> -h` for full flag details. `-g` widens scope from cwd-and-below to all sessions. ANSI: default strips when stdout isn't a TTY; `--strip-ansi` / `--raw` override.
+
+Exit codes: `0` success; `1` runtime error; `2` usage error (bad flag, missing session, ambiguous selector).
+
+## Selectors
+
+A single positional token, resolved like a git ref:
+
+1. **NAME** match wins. `cat`/`head`/`tail` pick the most recent; `rm` operates on all matches.
+2. **UUID prefix** fallthrough. Unique match required; ambiguous → error.
+
+"Most recent" = UUIDv7 lex-descending sort. Use `--` to pass a token starting with `-`.
+
+## Verbose output
+
+With `-v`, stderr carries metadata; without it, stderr is silent on success. Errors are always printed. The trailing line of any verbose read is:
+
+```
+live: id=<uuid> at-line=<L> at-time=<T> at-byte=<B>
+```
+
+Agents using `tail -vn +N` pass `<L>+1` as the next cursor and reset to `0` when `<uuid>` changes. `<T>` (active stream mtime, partial-bytes-aware since heartbeats only touch idx) and `<B>` (cumulative byte cursor) are alternates for `tail -t T` / `tail -c +K`.
+
+Possible preceding lines, in order: `dropped <k> lines …` (gap), `since=<N> > at-line=<L>; check id` / `time=<T> > at-time=<T>; check id` / `bytes=<B> > at-byte=<B>; check id` (cursor ahead), `partial-line bytes=<k> age=<s>`, `status=hung last-activity=<s>`, `exit=inconsistent`, `exit-code=<N>`. The last two can co-appear if the recorder wrote meta before a sweeper observed a torn recording.
+
+## On-disk layout
+
+```
+~/.live/
+  config.json
+  sessions/
+    <uuid>/
+      meta.json         # session metadata; writer-only, replaced atomically
+      process.lock      # held by the recorder for its lifetime — liveness signal
+      deadAt            # post-mortem marker; mtime = TTL clock, content = verdict
+      stream.NNNN.log   # raw PTY bytes
+      lines.NNNN.idx    # binary line index: struct.pack(">Qd", n, t), one per line
+```
+
+The recorder appends to the highest-numbered pair; frozen segments are immutable until retention unlinks them. Session IDs are UUIDv7 (lex-monotonic = chronological).
+
+Scope is a filter on `meta.cwd`: read verbs default to cwd-or-descendant (symlinks resolved); `-g` widens.
+
+## Invariants
+
+- **Single writer, lock = liveness.** Recorder holds the `flock` for its lifetime. Probe with non-blocking `LOCK_EX`: success = recorder is gone.
+- **Prefix invariant.** Stream is always one complete line ahead of, or equal to, the index — never the inverse. Crash leaves an unindexed complete line; sweepers stamp it `inconsistent`.
+- **Absolute line numbers.** `n` is monotonic across the session's lifetime. Retention deletes but never renumbers; cursors past the oldest retained line get a `dropped` notice.
+- **Heartbeat.** Recorder advances the active idx mtime every `heartbeatSec`. Staleness past `3 × heartbeatSec` while the lock is held = `hung`.
+- **Sweep on every read.** Each verb that touches sessions stamps dead-but-unmarked ones (exclusive create of `deadAt`) and deletes those past `ttlDays`. Races are safe.
+- **Graceful exit ordering.** `meta.json` → `deadAt` → unlock, in that order, so no sweeper races in with a wrong verdict.
+- **Signals.** `SIGWINCH` propagates window size. `SIGTERM`/`SIGHUP` forward to the child. `SIGINT` forwards only when stdin isn't a TTY (otherwise line discipline routes ^C directly). `live run` exits with the child's code, or `128 + signum` if signal-killed.
+
+## Configuration
+
+`~/.live/config.json`, auto-created. Partial files valid; unknown keys ignored; malformed fields fall back to defaults with a stderr warning.
+
+```json
+{ "ttlDays": 7, "maxKb": 512, "segmentKb": 64, "heartbeatSec": 30 }
+```
+
+| Default      |                                                              |
+| ------------ | ------------------------------------------------------------ |
+| Store        | `~/.live/sessions/` (single global store)                    |
+| Scope        | cwd descendants by default; `-g` widens to all               |
+| TTL          | 7 days from `deadAt` mtime, dead sessions only               |
+| Segment size | 64 KB rotation threshold; lines never split                  |
+| Retention    | 512 KB total per session; oldest segments unlinked when over |
+| Heartbeat    | active idx mtime advanced every 30 s                         |

live_cmd-0.1.0/DEVELOPMENT.md

@@ -0,0 +1,64 @@
+# Development
+
+Install from source:
+
+```sh
+cd path/to/here
+uv venv --python ">=3.14"
+source .venv/bin/activate
+uv pip install -e .
+live --version
+```
+
+`live` is now on `$PATH` for the activated shell, and edits to `src/live/` take
+effect on the next invocation.
+
+## Tests
+
+```sh
+uv pip install pytest
+pytest
+```
+
+Some completion tests are skipped unless `bash`, `zsh`, and/or `fish` are on `$PATH`.
+
+## Release
+
+1. Bump `version` in [`pyproject.toml`](pyproject.toml).
+2. Commit and tag:
+
+    ```sh
+    git commit -am "release vX.Y.Z"
+    git tag vX.Y.Z
+    git push && git push --tags
+    ```
+
+3. Build sdist + wheel into `dist/`:
+
+    ```sh
+    rm -rf dist/
+    uv build
+    ```
+
+4. Sanity-check the wheel installs cleanly in a throwaway env:
+
+    ```sh
+    uv tool install --from dist/live_cmd-X.Y.Z-py3-none-any.whl live-cmd
+    live --version
+    uv tool uninstall live-cmd
+    ```
+
+5. Publish to TestPyPI first, install from it, smoke-test:
+
+    ```sh
+    uv publish --publish-url https://test.pypi.org/legacy/ --token "$TESTPYPI_TOKEN"
+    uv tool install --index https://test.pypi.org/simple/ live-cmd
+    ```
+
+6. Publish to PyPI:
+
+    ```sh
+    uv publish --token "$PYPI_TOKEN"
+    ```
+
+API tokens come from <https://pypi.org/manage/account/token/> (and the TestPyPI equivalent). Scope them to the `live-cmd` project once it's been registered.

live_cmd-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: live-cmd
+Version: 0.1.0
+Summary: Live stream command line output.
+Project-URL: Homepage, https://github.com/astralarium/live
+Author: Mara Kim
+License: MIT
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.14
+Description-Content-Type: text/markdown
+
+# live
+
+Live stream command line output.
+
+See [DESIGN.md](DESIGN.md) for the design spec and [DEVELOPMENT.md](DEVELOPMENT.md) for working on `live` itself.
+
+## Install
+
+```sh
+pipx install live-cmd
+# or
+uv tool install live-cmd
+```
+
+## Usage
+
+```sh
+live run -n dev npm run dev   # record under PTY, mirror to terminal
+live ls                       # list sessions started under cwd
+live ls -g                    # list all sessions
+live tail -vn +0 dev          # resumable polling for agents
+live cat dev                  # full output
+live rm dev                   # delete
+```
+
+Sessions are stored under `~/.live/sessions/`; `live ls`/`cat`/`head`/`tail`/`rm` filter to sessions started in the current directory. Pass `-g` / `--global` to search globally.
+
+## Shell completion
+
+```sh
+live update-shell        # detect $SHELL, install completion, reload your shell
+```
+
+Or print the script and place it yourself:
+
+```sh
+live completion bash > ~/.local/share/bash-completion/completions/live
+live completion zsh  > "${fpath[1]}/_live"
+live completion fish > ~/.config/fish/completions/live.fish
+```

live_cmd-0.1.0/README.md

@@ -0,0 +1,40 @@
+# live
+
+Live stream command line output.
+
+See [DESIGN.md](DESIGN.md) for the design spec and [DEVELOPMENT.md](DEVELOPMENT.md) for working on `live` itself.
+
+## Install
+
+```sh
+pipx install live-cmd
+# or
+uv tool install live-cmd
+```
+
+## Usage
+
+```sh
+live run -n dev npm run dev   # record under PTY, mirror to terminal
+live ls                       # list sessions started under cwd
+live ls -g                    # list all sessions
+live tail -vn +0 dev          # resumable polling for agents
+live cat dev                  # full output
+live rm dev                   # delete
+```
+
+Sessions are stored under `~/.live/sessions/`; `live ls`/`cat`/`head`/`tail`/`rm` filter to sessions started in the current directory. Pass `-g` / `--global` to search globally.
+
+## Shell completion
+
+```sh
+live update-shell        # detect $SHELL, install completion, reload your shell
+```
+
+Or print the script and place it yourself:
+
+```sh
+live completion bash > ~/.local/share/bash-completion/completions/live
+live completion zsh  > "${fpath[1]}/_live"
+live completion fish > ~/.config/fish/completions/live.fish
+```

live_cmd-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "live-cmd"
+version = "0.1.0"
+description = "Live stream command line output."
+readme = "README.md"
+requires-python = ">=3.14"
+license = { text = "MIT" }
+authors = [{ name = "Mara Kim" }]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Operating System :: POSIX",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.scripts]
+live = "live.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/astralarium/live"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/live"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]

live_cmd-0.1.0/src/live/__init__.py

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

live_cmd-0.1.0/src/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())