remindrun 0.5.0__tar.gz

remindrun-0.5.0/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: remindrun
+Version: 0.5.0
+Summary: Run commands with Reminder monitoring and expose their status to the Android app.
+Author: Reminder
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Reminder
+
+Reminder is a minimal prototype for monitoring Linux command runs from an Android app.
+
+The first version has two parts:
+
+- `remindrun`: a Python command wrapper. Put `remindrun` before a command to record its status, output tail, exit code, and timestamps.
+- Android app: a small native app that polls the `remindrun` HTTP API, lists runs, and posts a local notification when a run changes from running to finished.
+
+## Python monitor
+
+Install the local package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+Or install the built wheel:
+
+```bash
+.venv/bin/python -m pip install dist/remindrun-0.5.0-py3-none-any.whl
+```
+
+Start the status server on the Linux machine:
+
+```bash
+remindrun server --host 0.0.0.0 --port 8765 --token change-this-token
+```
+
+Run commands through Reminder:
+
+```bash
+remindrun sleep 5
+remindrun run -- bash -lc 'echo hello && sleep 2 && echo done'
+remindrun status
+```
+
+You can use the shorter `rrun` command for the same actions:
+
+```bash
+rrun sleep 5
+rrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+The server exposes:
+
+- `GET /health`
+- `GET /api/runs?limit=50`
+- `GET /api/runs/{id}`
+- `GET /api/events?since=<updatedAt>`
+
+By default the SQLite database lives at `~/.reminder/reminder.db`. Set `REMINDER_HOME=/path/to/dir` to change that location.
+
+## Public access
+
+If you do not have a public IP, use a Cloudflare quick tunnel:
+
+```bash
+remindrun public
+```
+
+This starts the local server and runs `cloudflared tunnel --url http://127.0.0.1:8765`. It prints a public `https://*.trycloudflare.com` URL and a token. Enter both in the Android app:
+
+```text
+Server: https://example.trycloudflare.com
+Token:  generated-token
+```
+
+If `cloudflared` is missing, install it first:
+
+```bash
+brew install cloudflared
+```
+
+Cloudflare quick tunnel URLs are random. If you need the same URL every time and do not own a domain, use ngrok's free Dev Domain:
+
+```bash
+brew install ngrok/ngrok/ngrok
+ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>
+remindrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+In the Android app:
+
+```text
+Server: https://<YOUR_DEV_DOMAIN>.ngrok-free.dev
+Token:  generated-token
+```
+
+If the Android app needs to connect to a server that already has a public IP or a public domain:
+
+```bash
+remindrun server --host 0.0.0.0 --port 8765 --token a-long-random-token
+```
+
+Then open TCP port `8765` in the cloud security group or firewall.
+
+In the Android app:
+
+```text
+Server: http://<public-ip>:8765
+Token:  a-long-random-token
+```
+
+For real public use, prefer HTTPS through a reverse proxy or tunnel. Plain `http://<public-ip>:8765` works for testing, but the token can be observed on an untrusted network.
+
+## Android app
+
+Open the `android/` directory in Android Studio.
+
+For an emulator, the default server URL is:
+
+```text
+http://10.0.2.2:8765
+```
+
+For a physical phone, start the server with `--host 0.0.0.0`, put the phone on the same network, then set the app server URL to:
+
+```text
+http://<linux-machine-ip>:8765
+```
+
+If the server was started with `--token`, enter the same token in the app's Token field.
+
+This prototype polls every 5 seconds while the app process is alive. A later version should move polling into a foreground service or push channel if you want reliable notifications while the app is fully backgrounded.

remindrun-0.5.0/README.md

@@ -0,0 +1,126 @@
+# Reminder
+
+Reminder is a minimal prototype for monitoring Linux command runs from an Android app.
+
+The first version has two parts:
+
+- `remindrun`: a Python command wrapper. Put `remindrun` before a command to record its status, output tail, exit code, and timestamps.
+- Android app: a small native app that polls the `remindrun` HTTP API, lists runs, and posts a local notification when a run changes from running to finished.
+
+## Python monitor
+
+Install the local package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+Or install the built wheel:
+
+```bash
+.venv/bin/python -m pip install dist/remindrun-0.5.0-py3-none-any.whl
+```
+
+Start the status server on the Linux machine:
+
+```bash
+remindrun server --host 0.0.0.0 --port 8765 --token change-this-token
+```
+
+Run commands through Reminder:
+
+```bash
+remindrun sleep 5
+remindrun run -- bash -lc 'echo hello && sleep 2 && echo done'
+remindrun status
+```
+
+You can use the shorter `rrun` command for the same actions:
+
+```bash
+rrun sleep 5
+rrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+The server exposes:
+
+- `GET /health`
+- `GET /api/runs?limit=50`
+- `GET /api/runs/{id}`
+- `GET /api/events?since=<updatedAt>`
+
+By default the SQLite database lives at `~/.reminder/reminder.db`. Set `REMINDER_HOME=/path/to/dir` to change that location.
+
+## Public access
+
+If you do not have a public IP, use a Cloudflare quick tunnel:
+
+```bash
+remindrun public
+```
+
+This starts the local server and runs `cloudflared tunnel --url http://127.0.0.1:8765`. It prints a public `https://*.trycloudflare.com` URL and a token. Enter both in the Android app:
+
+```text
+Server: https://example.trycloudflare.com
+Token:  generated-token
+```
+
+If `cloudflared` is missing, install it first:
+
+```bash
+brew install cloudflared
+```
+
+Cloudflare quick tunnel URLs are random. If you need the same URL every time and do not own a domain, use ngrok's free Dev Domain:
+
+```bash
+brew install ngrok/ngrok/ngrok
+ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>
+remindrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+In the Android app:
+
+```text
+Server: https://<YOUR_DEV_DOMAIN>.ngrok-free.dev
+Token:  generated-token
+```
+
+If the Android app needs to connect to a server that already has a public IP or a public domain:
+
+```bash
+remindrun server --host 0.0.0.0 --port 8765 --token a-long-random-token
+```
+
+Then open TCP port `8765` in the cloud security group or firewall.
+
+In the Android app:
+
+```text
+Server: http://<public-ip>:8765
+Token:  a-long-random-token
+```
+
+For real public use, prefer HTTPS through a reverse proxy or tunnel. Plain `http://<public-ip>:8765` works for testing, but the token can be observed on an untrusted network.
+
+## Android app
+
+Open the `android/` directory in Android Studio.
+
+For an emulator, the default server URL is:
+
+```text
+http://10.0.2.2:8765
+```
+
+For a physical phone, start the server with `--host 0.0.0.0`, put the phone on the same network, then set the app server URL to:
+
+```text
+http://<linux-machine-ip>:8765
+```
+
+If the server was started with `--token`, enter the same token in the app's Token field.
+
+This prototype polls every 5 seconds while the app process is alive. A later version should move polling into a foreground service or push channel if you want reliable notifications while the app is fully backgrounded.

remindrun-0.5.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "remindrun"
+version = "0.5.0"
+description = "Run commands with Reminder monitoring and expose their status to the Android app."
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Reminder" }]
+dependencies = []
+
+[project.scripts]
+remindrun = "remindrun.cli:main"
+rrun = "remindrun.cli:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]

remindrun-0.5.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

remindrun-0.5.0/src/remindrun/__init__.py

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

remindrun-0.5.0/src/remindrun/__main__.py

@@ -0,0 +1,6 @@
+from .cli import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())
+

remindrun-0.5.0/src/remindrun/cli.py

@@ -0,0 +1,311 @@
+from __future__ import annotations
+
+import argparse
+import os
+import re
+import secrets
+import shlex
+import signal
+import shutil
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from collections.abc import Sequence
+
+from .server import serve
+from .store import RunStore
+
+
+RESERVED_COMMANDS = {"run", "server", "status", "public", "ngrok"}
+PUBLIC_URL_RE = re.compile(r"https://[a-zA-Z0-9.-]+\.trycloudflare\.com")
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    args = list(sys.argv[1:] if argv is None else argv)
+    if not args:
+        print_help()
+        return 2
+
+    first = args[0]
+    if first in {"-h", "--help"}:
+        print_help()
+        return 0
+    if first == "server":
+        return server_command(args[1:])
+    if first == "public":
+        return public_command(args[1:])
+    if first == "ngrok":
+        return ngrok_command(args[1:])
+    if first == "status":
+        return status_command(args[1:])
+    if first == "run":
+        command = args[1:]
+        if command and command[0] == "--":
+            command = command[1:]
+        return run_command(command)
+
+    return run_command(args)
+
+
+def server_command(argv: Sequence[str]) -> int:
+    parser = argparse.ArgumentParser(prog="remindrun server")
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument(
+        "--token",
+        default=None,
+        help="Bearer token required by /api/* endpoints. Can also use REMINDRUN_TOKEN.",
+    )
+    ns = parser.parse_args(argv)
+    serve(ns.host, ns.port, token=ns.token)
+    return 0
+
+
+def public_command(argv: Sequence[str]) -> int:
+    parser = argparse.ArgumentParser(prog="remindrun public")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--token", default=None)
+    parser.add_argument("--cloudflared", default="cloudflared")
+    ns = parser.parse_args(argv)
+
+    cloudflared = shutil.which(ns.cloudflared) if ns.cloudflared == "cloudflared" else ns.cloudflared
+    if not cloudflared:
+        print(
+            "remindrun: cloudflared is required for public tunnels.\n"
+            "Install it with: brew install cloudflared\n"
+            "Linux: https://developers.cloudflare.com/cloudflare-one/connections/connect-networks/downloads/",
+            file=sys.stderr,
+        )
+        return 127
+
+    token = ns.token or os.environ.get("REMINDRUN_TOKEN") or secrets.token_urlsafe(24)
+    local_url = f"http://{ns.host}:{ns.port}"
+
+    print("Starting Reminder local server...")
+    print(f"Local:  {local_url}")
+    print(f"Token:  {token}")
+    print("Starting Cloudflare quick tunnel...")
+
+    server_thread = threading.Thread(
+        target=serve,
+        args=(ns.host, ns.port),
+        kwargs={"token": token},
+        daemon=True,
+    )
+    server_thread.start()
+    time.sleep(0.5)
+
+    proc = subprocess.Popen(
+        [cloudflared, "tunnel", "--url", local_url],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+
+    public_url_seen = threading.Event()
+
+    def stream_tunnel_output() -> None:
+        if proc.stdout is None:
+            return
+        for line in proc.stdout:
+            sys.stdout.write(line)
+            sys.stdout.flush()
+            match = PUBLIC_URL_RE.search(line)
+            if match and not public_url_seen.is_set():
+                public_url_seen.set()
+                print()
+                print("Use this in the Android app:")
+                print(f"Server: {match.group(0)}")
+                print(f"Token:  {token}")
+                print()
+
+    output_thread = threading.Thread(target=stream_tunnel_output, daemon=True)
+    output_thread.start()
+
+    try:
+        return proc.wait()
+    except KeyboardInterrupt:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+        return 130
+
+
+def ngrok_command(argv: Sequence[str]) -> int:
+    parser = argparse.ArgumentParser(prog="remindrun ngrok")
+    parser.add_argument("--domain", required=True, help="Your fixed ngrok dev domain, like abc.ngrok-free.dev.")
+    parser.add_argument("--port", type=int, default=8765)
+    parser.add_argument("--host", default="127.0.0.1")
+    parser.add_argument("--token", default=None)
+    parser.add_argument("--ngrok", default="ngrok")
+    ns = parser.parse_args(argv)
+
+    ngrok = shutil.which(ns.ngrok) if ns.ngrok == "ngrok" else ns.ngrok
+    if not ngrok:
+        print(
+            "remindrun: ngrok is required for fixed free dev domains.\n"
+            "Install it with: brew install ngrok/ngrok/ngrok\n"
+            "Then run: ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>",
+            file=sys.stderr,
+        )
+        return 127
+
+    token = ns.token or os.environ.get("REMINDRUN_TOKEN") or secrets.token_urlsafe(24)
+    local_url = f"http://{ns.host}:{ns.port}"
+    public_url = f"https://{ns.domain.removeprefix('https://').removeprefix('http://').rstrip('/')}"
+
+    print("Starting Reminder local server...")
+    print(f"Local:  {local_url}")
+    print(f"Server: {public_url}")
+    print(f"Token:  {token}")
+    print("Starting ngrok fixed dev domain tunnel...")
+
+    server_thread = threading.Thread(
+        target=serve,
+        args=(ns.host, ns.port),
+        kwargs={"token": token},
+        daemon=True,
+    )
+    server_thread.start()
+    time.sleep(0.5)
+
+    proc = subprocess.Popen(
+        [ngrok, "http", str(ns.port), "--url", ns.domain.removeprefix("https://").removeprefix("http://").rstrip("/")],
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        bufsize=1,
+    )
+
+    print()
+    print("Use this in the Android app:")
+    print(f"Server: {public_url}")
+    print(f"Token:  {token}")
+    print()
+
+    try:
+        if proc.stdout is not None:
+            for line in proc.stdout:
+                sys.stdout.write(line)
+                sys.stdout.flush()
+        return proc.wait()
+    except KeyboardInterrupt:
+        proc.terminate()
+        try:
+            proc.wait(timeout=5)
+        except subprocess.TimeoutExpired:
+            proc.kill()
+        return 130
+
+
+def status_command(argv: Sequence[str]) -> int:
+    parser = argparse.ArgumentParser(prog="remindrun status")
+    parser.add_argument("--limit", type=int, default=10)
+    ns = parser.parse_args(argv)
+    runs = RunStore().list_runs(limit=ns.limit)
+    if not runs:
+        print("No runs yet.")
+        return 0
+    for run in runs:
+        exit_code = "" if run.exit_code is None else f" exit={run.exit_code}"
+        print(f"{run.id[:8]} {run.status:9} {run.started_at} {run.commandText}{exit_code}")
+    return 0
+
+
+def run_command(command: Sequence[str]) -> int:
+    if not command:
+        print("remindrun: missing command to run", file=sys.stderr)
+        return 2
+
+    run_id = str(uuid.uuid4())
+    store = RunStore()
+    store.create_run(run_id=run_id, command=list(command), cwd=os.getcwd())
+
+    print(f"Reminder run: {run_id}")
+    print(f"Command: {shlex.join(command)}")
+
+    try:
+        proc = subprocess.Popen(
+            list(command),
+            stdout=subprocess.PIPE,
+            stderr=subprocess.PIPE,
+            text=True,
+            bufsize=1,
+        )
+    except FileNotFoundError:
+        store.append_output(run_id, "stderr_tail", f"command not found: {command[0]}\n")
+        store.finish_run(run_id, 127)
+        print(f"remindrun: command not found: {command[0]}", file=sys.stderr)
+        return 127
+
+    store.mark_running(run_id, proc.pid)
+
+    stop_forwarding = threading.Event()
+
+    def forward_signal(signum: int, _frame: object) -> None:
+        if proc.poll() is None:
+            proc.send_signal(signum)
+
+    previous_sigint = signal.signal(signal.SIGINT, forward_signal)
+    previous_sigterm = signal.signal(signal.SIGTERM, forward_signal)
+
+    try:
+        threads = [
+            threading.Thread(
+                target=stream_output,
+                args=(proc.stdout, sys.stdout, store, run_id, "stdout_tail", stop_forwarding),
+                daemon=True,
+            ),
+            threading.Thread(
+                target=stream_output,
+                args=(proc.stderr, sys.stderr, store, run_id, "stderr_tail", stop_forwarding),
+                daemon=True,
+            ),
+        ]
+        for thread in threads:
+            thread.start()
+
+        exit_code = proc.wait()
+        stop_forwarding.set()
+        for thread in threads:
+            thread.join(timeout=2)
+    finally:
+        signal.signal(signal.SIGINT, previous_sigint)
+        signal.signal(signal.SIGTERM, previous_sigterm)
+
+    store.finish_run(run_id, exit_code)
+    print(f"Reminder finished: {run_id} exit={exit_code}")
+    return exit_code
+
+
+def stream_output(pipe, target, store: RunStore, run_id: str, stream_name: str, stop: threading.Event) -> None:
+    if pipe is None:
+        return
+    while not stop.is_set():
+        chunk = pipe.readline()
+        if chunk == "":
+            break
+        target.write(chunk)
+        target.flush()
+        store.append_output(run_id, stream_name, chunk)
+
+
+def print_help() -> None:
+    print(
+        """Reminder command runner
+
+Usage:
+  remindrun server [--host 0.0.0.0] [--port 8765] [--token TOKEN]
+  remindrun public [--port 8765] [--token TOKEN]
+  remindrun ngrok --domain YOUR_DOMAIN.ngrok-free.dev [--token TOKEN]
+  remindrun status [--limit 10]
+  remindrun run -- <command> [args...]
+  remindrun <command> [args...]
+"""
+    )

remindrun-0.5.0/src/remindrun/server.py

@@ -0,0 +1,115 @@
+from __future__ import annotations
+
+import json
+import os
+import secrets
+from http import HTTPStatus
+from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
+from urllib.parse import parse_qs, urlparse
+
+from .store import RunStore
+
+
+class ReminderServer(ThreadingHTTPServer):
+    def __init__(self, server_address: tuple[str, int], store: RunStore, token: str | None = None) -> None:
+        super().__init__(server_address, ReminderRequestHandler)
+        self.store = store
+        self.token = token
+
+
+class ReminderRequestHandler(BaseHTTPRequestHandler):
+    server: ReminderServer
+
+    def do_GET(self) -> None:
+        parsed = urlparse(self.path)
+        if parsed.path == "/health":
+            self.send_json({"ok": True})
+            return
+
+        if parsed.path.startswith("/api/") and not self.is_authorized():
+            self.send_json({"error": "unauthorized"}, status=HTTPStatus.UNAUTHORIZED)
+            return
+
+        if parsed.path == "/api/runs":
+            query = parse_qs(parsed.query)
+            limit = parse_limit(query.get("limit", ["100"])[0])
+            runs = [run.to_dict() for run in self.server.store.list_runs(limit=limit)]
+            self.send_json({"runs": runs})
+            return
+
+        if parsed.path.startswith("/api/runs/"):
+            run_id = parsed.path.removeprefix("/api/runs/")
+            run = self.server.store.get_run(run_id)
+            if run is None:
+                self.send_json({"error": "run not found"}, status=HTTPStatus.NOT_FOUND)
+                return
+            self.send_json({"run": run.to_dict()})
+            return
+
+        if parsed.path == "/api/events":
+            query = parse_qs(parsed.query)
+            since = query.get("since", [None])[0]
+            limit = parse_limit(query.get("limit", ["100"])[0])
+            runs = [
+                run.to_dict()
+                for run in self.server.store.list_updated_since(since=since, limit=limit)
+            ]
+            latest = max((run["updatedAt"] for run in runs), default=since)
+            self.send_json({"events": runs, "latest": latest})
+            return
+
+        self.send_json({"error": "not found"}, status=HTTPStatus.NOT_FOUND)
+
+    def do_OPTIONS(self) -> None:
+        self.send_response(HTTPStatus.NO_CONTENT)
+        self.send_cors_headers()
+        self.end_headers()
+
+    def send_json(self, payload: dict, status: HTTPStatus = HTTPStatus.OK) -> None:
+        body = json.dumps(payload, ensure_ascii=False).encode("utf-8")
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json; charset=utf-8")
+        self.send_header("Content-Length", str(len(body)))
+        self.send_cors_headers()
+        self.end_headers()
+        self.wfile.write(body)
+
+    def send_cors_headers(self) -> None:
+        self.send_header("Access-Control-Allow-Origin", "*")
+        self.send_header("Access-Control-Allow-Methods", "GET, OPTIONS")
+        self.send_header("Access-Control-Allow-Headers", "Authorization, Content-Type, X-Reminder-Token")
+
+    def is_authorized(self) -> bool:
+        token = self.server.token
+        if not token:
+            return True
+
+        auth = self.headers.get("Authorization", "")
+        if auth.startswith("Bearer "):
+            return secrets.compare_digest(auth.removeprefix("Bearer ").strip(), token)
+
+        header_token = self.headers.get("X-Reminder-Token", "")
+        return bool(header_token) and secrets.compare_digest(header_token, token)
+
+    def log_message(self, fmt: str, *args: object) -> None:
+        print(f"[remindrun server] {self.address_string()} - {fmt % args}")
+
+
+def parse_limit(raw: str) -> int:
+    try:
+        return max(1, min(int(raw), 500))
+    except ValueError:
+        return 100
+
+
+def serve(host: str, port: int, store: RunStore | None = None, token: str | None = None) -> None:
+    actual_store = store or RunStore()
+    actual_token = token or os.environ.get("REMINDRUN_TOKEN")
+    httpd = ReminderServer((host, port), actual_store, actual_token)
+    print(f"Reminder server listening on http://{host}:{port}")
+    print(f"Database: {actual_store.db_path}")
+    if actual_token:
+        print("Auth: enabled")
+    elif host in {"0.0.0.0", "::"}:
+        print("WARNING: server is listening publicly without a token.")
+    httpd.serve_forever()

remindrun-0.5.0/src/remindrun/store.py

@@ -0,0 +1,199 @@
+from __future__ import annotations
+
+import json
+import os
+import shlex
+import sqlite3
+from dataclasses import dataclass
+from datetime import UTC, datetime
+from pathlib import Path
+from typing import Any
+
+
+TERMINAL_STATUSES = {"succeeded", "failed", "cancelled"}
+
+
+def utc_now() -> str:
+    return datetime.now(UTC).isoformat(timespec="seconds")
+
+
+def default_data_dir() -> Path:
+    configured = os.environ.get("REMINDER_HOME")
+    if configured:
+        return Path(configured).expanduser()
+    return Path.home() / ".reminder"
+
+
+def default_db_path() -> Path:
+    return default_data_dir() / "reminder.db"
+
+
+@dataclass(frozen=True)
+class RunRecord:
+    id: str
+    command: list[str]
+    cwd: str
+    status: str
+    pid: int | None
+    exit_code: int | None
+    started_at: str
+    ended_at: str | None
+    updated_at: str
+    stdout_tail: str
+    stderr_tail: str
+
+    @property
+    def commandText(self) -> str:
+        return shlex.join(self.command)
+
+    @classmethod
+    def from_row(cls, row: sqlite3.Row) -> "RunRecord":
+        return cls(
+            id=row["id"],
+            command=json.loads(row["command"]),
+            cwd=row["cwd"],
+            status=row["status"],
+            pid=row["pid"],
+            exit_code=row["exit_code"],
+            started_at=row["started_at"],
+            ended_at=row["ended_at"],
+            updated_at=row["updated_at"],
+            stdout_tail=row["stdout_tail"] or "",
+            stderr_tail=row["stderr_tail"] or "",
+        )
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "id": self.id,
+            "command": self.command,
+            "commandText": self.commandText,
+            "cwd": self.cwd,
+            "status": self.status,
+            "pid": self.pid,
+            "exitCode": self.exit_code,
+            "startedAt": self.started_at,
+            "endedAt": self.ended_at,
+            "updatedAt": self.updated_at,
+            "stdoutTail": self.stdout_tail,
+            "stderrTail": self.stderr_tail,
+        }
+
+
+class RunStore:
+    def __init__(self, db_path: Path | str | None = None) -> None:
+        self.db_path = Path(db_path) if db_path else default_db_path()
+        self.db_path.parent.mkdir(parents=True, exist_ok=True)
+        self.init_db()
+
+    def connect(self) -> sqlite3.Connection:
+        conn = sqlite3.connect(self.db_path)
+        conn.row_factory = sqlite3.Row
+        return conn
+
+    def init_db(self) -> None:
+        with self.connect() as conn:
+            conn.execute(
+                """
+                CREATE TABLE IF NOT EXISTS runs (
+                    id TEXT PRIMARY KEY,
+                    command TEXT NOT NULL,
+                    cwd TEXT NOT NULL,
+                    status TEXT NOT NULL,
+                    pid INTEGER,
+                    exit_code INTEGER,
+                    started_at TEXT NOT NULL,
+                    ended_at TEXT,
+                    updated_at TEXT NOT NULL,
+                    stdout_tail TEXT NOT NULL DEFAULT '',
+                    stderr_tail TEXT NOT NULL DEFAULT ''
+                )
+                """
+            )
+            conn.execute(
+                "CREATE INDEX IF NOT EXISTS idx_runs_updated_at ON runs(updated_at DESC)"
+            )
+
+    def create_run(self, run_id: str, command: list[str], cwd: str) -> None:
+        now = utc_now()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                INSERT INTO runs (
+                    id, command, cwd, status, pid, exit_code, started_at,
+                    ended_at, updated_at, stdout_tail, stderr_tail
+                ) VALUES (?, ?, ?, 'created', NULL, NULL, ?, NULL, ?, '', '')
+                """,
+                (run_id, json.dumps(command), cwd, now, now),
+            )
+
+    def mark_running(self, run_id: str, pid: int) -> None:
+        self._update(run_id, {"status": "running", "pid": pid})
+
+    def append_output(self, run_id: str, stream: str, text: str, max_chars: int = 12000) -> None:
+        if stream not in {"stdout_tail", "stderr_tail"}:
+            raise ValueError(f"unsupported stream: {stream}")
+        with self.connect() as conn:
+            row = conn.execute(
+                f"SELECT {stream} FROM runs WHERE id = ?", (run_id,)
+            ).fetchone()
+            if row is None:
+                return
+            updated = ((row[stream] or "") + text)[-max_chars:]
+            conn.execute(
+                f"UPDATE runs SET {stream} = ?, updated_at = ? WHERE id = ?",
+                (updated, utc_now(), run_id),
+            )
+
+    def finish_run(self, run_id: str, exit_code: int) -> None:
+        status = "succeeded" if exit_code == 0 else "failed"
+        now = utc_now()
+        with self.connect() as conn:
+            conn.execute(
+                """
+                UPDATE runs
+                SET status = ?, exit_code = ?, ended_at = ?, updated_at = ?
+                WHERE id = ?
+                """,
+                (status, exit_code, now, now, run_id),
+            )
+
+    def get_run(self, run_id: str) -> RunRecord | None:
+        with self.connect() as conn:
+            row = conn.execute("SELECT * FROM runs WHERE id = ?", (run_id,)).fetchone()
+        return RunRecord.from_row(row) if row else None
+
+    def list_runs(self, limit: int = 100) -> list[RunRecord]:
+        with self.connect() as conn:
+            rows = conn.execute(
+                "SELECT * FROM runs ORDER BY started_at DESC LIMIT ?",
+                (limit,),
+            ).fetchall()
+        return [RunRecord.from_row(row) for row in rows]
+
+    def list_updated_since(self, since: str | None, limit: int = 100) -> list[RunRecord]:
+        with self.connect() as conn:
+            if since:
+                rows = conn.execute(
+                    """
+                    SELECT * FROM runs
+                    WHERE updated_at > ?
+                    ORDER BY updated_at ASC
+                    LIMIT ?
+                    """,
+                    (since, limit),
+                ).fetchall()
+            else:
+                rows = conn.execute(
+                    "SELECT * FROM runs ORDER BY updated_at ASC LIMIT ?",
+                    (limit,),
+                ).fetchall()
+        return [RunRecord.from_row(row) for row in rows]
+
+    def _update(self, run_id: str, fields: dict[str, Any]) -> None:
+        if not fields:
+            return
+        fields["updated_at"] = utc_now()
+        assignments = ", ".join(f"{name} = ?" for name in fields)
+        values = list(fields.values()) + [run_id]
+        with self.connect() as conn:
+            conn.execute(f"UPDATE runs SET {assignments} WHERE id = ?", values)

remindrun-0.5.0/src/remindrun.egg-info/PKG-INFO

@@ -0,0 +1,134 @@
+Metadata-Version: 2.4
+Name: remindrun
+Version: 0.5.0
+Summary: Run commands with Reminder monitoring and expose their status to the Android app.
+Author: Reminder
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# Reminder
+
+Reminder is a minimal prototype for monitoring Linux command runs from an Android app.
+
+The first version has two parts:
+
+- `remindrun`: a Python command wrapper. Put `remindrun` before a command to record its status, output tail, exit code, and timestamps.
+- Android app: a small native app that polls the `remindrun` HTTP API, lists runs, and posts a local notification when a run changes from running to finished.
+
+## Python monitor
+
+Install the local package in a virtual environment:
+
+```bash
+python3 -m venv .venv
+.venv/bin/python -m pip install -e .
+```
+
+Or install the built wheel:
+
+```bash
+.venv/bin/python -m pip install dist/remindrun-0.5.0-py3-none-any.whl
+```
+
+Start the status server on the Linux machine:
+
+```bash
+remindrun server --host 0.0.0.0 --port 8765 --token change-this-token
+```
+
+Run commands through Reminder:
+
+```bash
+remindrun sleep 5
+remindrun run -- bash -lc 'echo hello && sleep 2 && echo done'
+remindrun status
+```
+
+You can use the shorter `rrun` command for the same actions:
+
+```bash
+rrun sleep 5
+rrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+The server exposes:
+
+- `GET /health`
+- `GET /api/runs?limit=50`
+- `GET /api/runs/{id}`
+- `GET /api/events?since=<updatedAt>`
+
+By default the SQLite database lives at `~/.reminder/reminder.db`. Set `REMINDER_HOME=/path/to/dir` to change that location.
+
+## Public access
+
+If you do not have a public IP, use a Cloudflare quick tunnel:
+
+```bash
+remindrun public
+```
+
+This starts the local server and runs `cloudflared tunnel --url http://127.0.0.1:8765`. It prints a public `https://*.trycloudflare.com` URL and a token. Enter both in the Android app:
+
+```text
+Server: https://example.trycloudflare.com
+Token:  generated-token
+```
+
+If `cloudflared` is missing, install it first:
+
+```bash
+brew install cloudflared
+```
+
+Cloudflare quick tunnel URLs are random. If you need the same URL every time and do not own a domain, use ngrok's free Dev Domain:
+
+```bash
+brew install ngrok/ngrok/ngrok
+ngrok config add-authtoken <YOUR_NGROK_AUTHTOKEN>
+remindrun ngrok --domain <YOUR_DEV_DOMAIN>.ngrok-free.dev
+```
+
+In the Android app:
+
+```text
+Server: https://<YOUR_DEV_DOMAIN>.ngrok-free.dev
+Token:  generated-token
+```
+
+If the Android app needs to connect to a server that already has a public IP or a public domain:
+
+```bash
+remindrun server --host 0.0.0.0 --port 8765 --token a-long-random-token
+```
+
+Then open TCP port `8765` in the cloud security group or firewall.
+
+In the Android app:
+
+```text
+Server: http://<public-ip>:8765
+Token:  a-long-random-token
+```
+
+For real public use, prefer HTTPS through a reverse proxy or tunnel. Plain `http://<public-ip>:8765` works for testing, but the token can be observed on an untrusted network.
+
+## Android app
+
+Open the `android/` directory in Android Studio.
+
+For an emulator, the default server URL is:
+
+```text
+http://10.0.2.2:8765
+```
+
+For a physical phone, start the server with `--host 0.0.0.0`, put the phone on the same network, then set the app server URL to:
+
+```text
+http://<linux-machine-ip>:8765
+```
+
+If the server was started with `--token`, enter the same token in the app's Token field.
+
+This prototype polls every 5 seconds while the app process is alive. A later version should move polling into a foreground service or push channel if you want reliable notifications while the app is fully backgrounded.

remindrun-0.5.0/src/remindrun.egg-info/SOURCES.txt

@@ -0,0 +1,13 @@
+README.md
+pyproject.toml
+src/remindrun/__init__.py
+src/remindrun/__main__.py
+src/remindrun/cli.py
+src/remindrun/server.py
+src/remindrun/store.py
+src/remindrun.egg-info/PKG-INFO
+src/remindrun.egg-info/SOURCES.txt
+src/remindrun.egg-info/dependency_links.txt
+src/remindrun.egg-info/entry_points.txt
+src/remindrun.egg-info/top_level.txt
+tests/test_store.py

remindrun-0.5.0/src/remindrun.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

remindrun-0.5.0/src/remindrun.egg-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+remindrun = remindrun.cli:main
+rrun = remindrun.cli:main

remindrun-0.5.0/src/remindrun.egg-info/top_level.txt

@@ -0,0 +1 @@
+remindrun

remindrun-0.5.0/tests/test_store.py

@@ -0,0 +1,41 @@
+import tempfile
+import unittest
+from pathlib import Path
+
+from remindrun.store import RunStore
+
+
+class RunStoreTest(unittest.TestCase):
+    def test_run_lifecycle(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            store = RunStore(Path(tmp) / "runs.db")
+
+            store.create_run("run-1", ["echo", "hello"], "/tmp")
+            store.mark_running("run-1", 123)
+            store.append_output("run-1", "stdout_tail", "hello\n")
+            store.finish_run("run-1", 0)
+
+            run = store.get_run("run-1")
+
+            self.assertIsNotNone(run)
+            self.assertEqual(run.status, "succeeded")
+            self.assertEqual(run.exit_code, 0)
+            self.assertEqual(run.stdout_tail, "hello\n")
+            self.assertEqual(run.commandText, "echo hello")
+
+    def test_failed_run(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            store = RunStore(Path(tmp) / "runs.db")
+
+            store.create_run("run-2", ["false"], "/tmp")
+            store.finish_run("run-2", 1)
+
+            run = store.get_run("run-2")
+
+            self.assertIsNotNone(run)
+            self.assertEqual(run.status, "failed")
+            self.assertEqual(run.exit_code, 1)
+
+
+if __name__ == "__main__":
+    unittest.main()