pocketshell 0.3.2__tar.gz → 0.3.6__tar.gz

{pocketshell-0.3.2 → pocketshell-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pocketshell
-Version: 0.3.2
+Version: 0.3.6
 Summary: Unified server-side Python utility for the PocketShell Android client.
 Project-URL: Homepage, https://github.com/alexeygrigorev/pocketshell
 Project-URL: Issues, https://github.com/alexeygrigorev/pocketshell/issues
@@ -173,6 +173,75 @@ Requires the optional `qr` extra (see [Optional extras](#optional-extras)).
 Without it, the command exits 127 with the install hint and every other
 subcommand keeps working.
 
+#### Running from a repo clone (no install)
+
+To run `qr-share` straight from a checkout without installing the tool,
+use `uv run` from `tools/pocketshell` and include the `qr` extra:
+
+```bash
+cd tools/pocketshell
+uv run --extra qr pocketshell qr-share prod
+```
+
+The first run creates `.venv` and installs the QR dependency; later runs
+are instant. Run it in an interactive terminal so stdout is a TTY and the
+QR renders inline — otherwise it falls back to writing PNGs (add
+`--png --out-dir ./qr` to force PNGs). Omitting `--extra qr` makes the
+command exit 127 with the install hint.
+
+### `pocketshell hooks`
+
+Installs agent **stop / idle-detection** hooks across Claude Code,
+Codex, and OpenCode and normalizes their events into a single
+append-only JSONL bus the app can read back. Server-side only;
+integration only — no "tell the agent to continue" action yet (deferred;
+see issue #267 and locked decision **D26** in `docs/decisions.md`).
+
+```bash
+pocketshell hooks install [--engine claude|codex|opencode|all]   # default: all
+pocketshell hooks status  [--engine ...] [--json] [--last N]
+pocketshell hooks events  [--since ISO8601] [--limit N] [--json]
+pocketshell hooks uninstall [--engine ...]
+```
+
+`install` is **non-destructive — it merges, it never clobbers**:
+
+- **Claude Code** — adds a `{type: "command", command: "python3 <handler>"}`
+  entry under the `Stop`, `SubagentStop`, and `Notification` hook events
+  in `~/.claude/settings.json`, only when absent. All other top-level
+  keys and any pre-existing user hooks are preserved.
+- **Codex** — sets the top-level `notify` program in `~/.codex/config.toml`
+  to our handler (Codex hooks do not fire under `codex exec`, so `notify`
+  is the headless-safe signal). If `notify` is already set to something
+  else, it warns and **skips** rather than overwriting. The rest of the
+  TOML is preserved.
+- **OpenCode** — drops a `pocketshell-idle-signal.js` plugin into
+  `~/.config/opencode/plugin/` without disturbing other plugins.
+
+`install` is idempotent (running twice adds nothing new). Handler scripts
+and the event bus live under `~/.cache/pocketshell/hooks/` (override with
+`$POCKETSHELL_HOOKS_DIR`); each handler appends a normalized record
+`{ts, engine, state, source, session_id, cwd, ...}` to
+`events.jsonl`.
+
+**Per-engine uninstall** (`pocketshell hooks uninstall`) removes only what
+we added and is idempotent:
+
+- **Claude Code** — drops our command group from each hook event; an
+  event key (and the top-level `hooks` object) is deleted only if we
+  created it and it ends up empty. A user's pre-existing hooks always
+  survive, so a pre-populated `settings.json` comes back
+  byte-equivalent for the unrelated parts.
+- **Codex** — removes the top-level `notify` line only when it still
+  points at our handler. A `notify` the user pointed elsewhere is left
+  alone.
+- **OpenCode** — deletes our plugin file; other plugins and the dir
+  itself are left in place.
+
+The event bus (`events.jsonl`) is preserved on uninstall so
+already-emitted records stay readable; only the generated handler
+scripts are cleaned up.
+
 ## Development
 
 ```bash
@@ -297,10 +366,13 @@ as a permanent fallback.
 
 The PocketShell app previously probed for two binaries (`quse`,
 `tmuxctl`) on every host. That meant two installs to keep up to date,
-two probes to surface failures from, and two PATH-discovery edge cases
-(see [issue #41](https://github.com/alexeygrigorev/pocketshell/issues/41)).
+two probes to surface failures from, and two PATH-discovery edge cases.
 A single `pocketshell` binary collapses those into one install, one
-probe, one bootstrap row. The app keeps detecting `quse` and `tmuxctl`
-as a parallel path while `pocketshell` ramps up to feature parity; once
-parity is reached, the legacy probes are removed in a hard-cut follow-up
-(no compat shim — see decision D22 in `docs/decisions.md`).
+probe, one bootstrap row. The Android bootstrap probe now derives PATH
+from the user's shell rc and prepends `$HOME/.local/bin`, `$HOME/bin`,
+and `$HOME/.cargo/bin` before probing, so cloned-repo or venv installs
+can be discovered without a manual app-side PATH field. The app keeps
+detecting `quse` and `tmuxctl` as a parallel path while `pocketshell`
+ramps up to feature parity; once parity is reached, the legacy probes
+are removed in a hard-cut follow-up (no compat shim — see decision D22
+in `docs/decisions.md`).

{pocketshell-0.3.2 → pocketshell-0.3.6}/README.md

@@ -145,6 +145,75 @@ Requires the optional `qr` extra (see [Optional extras](#optional-extras)).
 Without it, the command exits 127 with the install hint and every other
 subcommand keeps working.
 
+#### Running from a repo clone (no install)
+
+To run `qr-share` straight from a checkout without installing the tool,
+use `uv run` from `tools/pocketshell` and include the `qr` extra:
+
+```bash
+cd tools/pocketshell
+uv run --extra qr pocketshell qr-share prod
+```
+
+The first run creates `.venv` and installs the QR dependency; later runs
+are instant. Run it in an interactive terminal so stdout is a TTY and the
+QR renders inline — otherwise it falls back to writing PNGs (add
+`--png --out-dir ./qr` to force PNGs). Omitting `--extra qr` makes the
+command exit 127 with the install hint.
+
+### `pocketshell hooks`
+
+Installs agent **stop / idle-detection** hooks across Claude Code,
+Codex, and OpenCode and normalizes their events into a single
+append-only JSONL bus the app can read back. Server-side only;
+integration only — no "tell the agent to continue" action yet (deferred;
+see issue #267 and locked decision **D26** in `docs/decisions.md`).
+
+```bash
+pocketshell hooks install [--engine claude|codex|opencode|all]   # default: all
+pocketshell hooks status  [--engine ...] [--json] [--last N]
+pocketshell hooks events  [--since ISO8601] [--limit N] [--json]
+pocketshell hooks uninstall [--engine ...]
+```
+
+`install` is **non-destructive — it merges, it never clobbers**:
+
+- **Claude Code** — adds a `{type: "command", command: "python3 <handler>"}`
+  entry under the `Stop`, `SubagentStop`, and `Notification` hook events
+  in `~/.claude/settings.json`, only when absent. All other top-level
+  keys and any pre-existing user hooks are preserved.
+- **Codex** — sets the top-level `notify` program in `~/.codex/config.toml`
+  to our handler (Codex hooks do not fire under `codex exec`, so `notify`
+  is the headless-safe signal). If `notify` is already set to something
+  else, it warns and **skips** rather than overwriting. The rest of the
+  TOML is preserved.
+- **OpenCode** — drops a `pocketshell-idle-signal.js` plugin into
+  `~/.config/opencode/plugin/` without disturbing other plugins.
+
+`install` is idempotent (running twice adds nothing new). Handler scripts
+and the event bus live under `~/.cache/pocketshell/hooks/` (override with
+`$POCKETSHELL_HOOKS_DIR`); each handler appends a normalized record
+`{ts, engine, state, source, session_id, cwd, ...}` to
+`events.jsonl`.
+
+**Per-engine uninstall** (`pocketshell hooks uninstall`) removes only what
+we added and is idempotent:
+
+- **Claude Code** — drops our command group from each hook event; an
+  event key (and the top-level `hooks` object) is deleted only if we
+  created it and it ends up empty. A user's pre-existing hooks always
+  survive, so a pre-populated `settings.json` comes back
+  byte-equivalent for the unrelated parts.
+- **Codex** — removes the top-level `notify` line only when it still
+  points at our handler. A `notify` the user pointed elsewhere is left
+  alone.
+- **OpenCode** — deletes our plugin file; other plugins and the dir
+  itself are left in place.
+
+The event bus (`events.jsonl`) is preserved on uninstall so
+already-emitted records stay readable; only the generated handler
+scripts are cleaned up.
+
 ## Development
 
 ```bash
@@ -269,10 +338,13 @@ as a permanent fallback.
 
 The PocketShell app previously probed for two binaries (`quse`,
 `tmuxctl`) on every host. That meant two installs to keep up to date,
-two probes to surface failures from, and two PATH-discovery edge cases
-(see [issue #41](https://github.com/alexeygrigorev/pocketshell/issues/41)).
+two probes to surface failures from, and two PATH-discovery edge cases.
 A single `pocketshell` binary collapses those into one install, one
-probe, one bootstrap row. The app keeps detecting `quse` and `tmuxctl`
-as a parallel path while `pocketshell` ramps up to feature parity; once
-parity is reached, the legacy probes are removed in a hard-cut follow-up
-(no compat shim — see decision D22 in `docs/decisions.md`).
+probe, one bootstrap row. The Android bootstrap probe now derives PATH
+from the user's shell rc and prepends `$HOME/.local/bin`, `$HOME/bin`,
+and `$HOME/.cargo/bin` before probing, so cloned-repo or venv installs
+can be discovered without a manual app-side PATH field. The app keeps
+detecting `quse` and `tmuxctl` as a parallel path while `pocketshell`
+ramps up to feature parity; once parity is reached, the legacy probes
+are removed in a hard-cut follow-up (no compat shim — see decision D22
+in `docs/decisions.md`).

{pocketshell-0.3.2 → pocketshell-0.3.6}/pyproject.toml

@@ -8,7 +8,7 @@ name = "pocketshell"
 # scripts/check-pypi-version.sh enforces this; .github/workflows/build.yml
 # runs that check before publishing to PyPI. See
 # tools/pocketshell/README.md ("Release flow") for the bump procedure.
-version = "0.3.2"
+version = "0.3.6"
 description = "Unified server-side Python utility for the PocketShell Android client."
 readme = "README.md"
 requires-python = ">=3.11"

{pocketshell-0.3.2 → pocketshell-0.3.6}/src/pocketshell/__init__.py

@@ -11,4 +11,4 @@ See https://github.com/alexeygrigorev/pocketshell/issues/170.
 from __future__ import annotations
 
 __all__ = ["__version__"]
-__version__ = "0.1.0"
+__version__ = "0.3.6"

{pocketshell-0.3.2 → pocketshell-0.3.6}/src/pocketshell/cli.py

@@ -23,7 +23,10 @@ import click
 
 from pocketshell import __version__
 from pocketshell.agent_log import agent_log_command
+from pocketshell.env import env_group
+from pocketshell.hooks import hooks_group
 from pocketshell.jobs import jobs_group
+from pocketshell.logs import logs_group
 from pocketshell.qr_share import qr_share_command
 from pocketshell.repos import repos_group
 from pocketshell.sessions import sessions_group
@@ -50,6 +53,9 @@ cli.add_command(jobs_group, name="jobs")
 cli.add_command(sessions_group, name="sessions")
 cli.add_command(agent_log_command, name="agent-log")
 cli.add_command(repos_group, name="repos")
+cli.add_command(env_group, name="env")
+cli.add_command(hooks_group, name="hooks")
+cli.add_command(logs_group, name="logs")
 cli.add_command(qr_share_command, name="qr-share")