yoru-cli 0.1.3__tar.gz → 0.2.0__tar.gz

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/.gitignore

@@ -77,3 +77,6 @@ backend/data/.auth_jwt_secret
 # Embedding cache (trovex / fastembed)
 .fastembed_cache/
 .vercel
+
+# install-smoke pre-release wheel (transient)
+install-smoke/_wheel/

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: yoru-cli
-Version: 0.1.3
+Version: 0.2.0
 Summary: Yoru — audit-grade session receipts for autonomous AI coding agents.
 Project-URL: Homepage, https://yoru.sh
 Project-URL: Documentation, https://yoru.sh/docs
@@ -34,10 +34,14 @@ The Claude Code hook installer for Yoru. One command installs a `PostToolUse` ho
 ## Install
 
 ```bash
-pip install yoru-cli
+pipx install yoru-cli                       # or: uv tool install yoru-cli
 yoru init --server https://yoru.acme.com
 ```
 
+Use `pipx`/`uv` — a bare `pip install yoru-cli` fails on Homebrew/Debian Python with
+`error: externally-managed-environment` (PEP 668). No pipx? A venv works too:
+`python3 -m venv .venv && .venv/bin/pip install yoru-cli`.
+
 Yoru is **self-hosted** — point the CLI at your own backend with `--server`. `yoru init` opens a pairing URL in your browser, writes `~/.claude/hooks/yoru.sh`, and registers the hook in `~/.claude/settings.json`. Don't have a server yet? [Stand one up](https://github.com/TsukumoHQ/yoru) — `docker-compose up`.
 
 Requires Python 3.10+. One runtime dep: `httpx`.

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/README.md

@@ -8,10 +8,14 @@ The Claude Code hook installer for Yoru. One command installs a `PostToolUse` ho
 ## Install
 
 ```bash
-pip install yoru-cli
+pipx install yoru-cli                       # or: uv tool install yoru-cli
 yoru init --server https://yoru.acme.com
 ```
 
+Use `pipx`/`uv` — a bare `pip install yoru-cli` fails on Homebrew/Debian Python with
+`error: externally-managed-environment` (PEP 668). No pipx? A venv works too:
+`python3 -m venv .venv && .venv/bin/pip install yoru-cli`.
+
 Yoru is **self-hosted** — point the CLI at your own backend with `--server`. `yoru init` opens a pairing URL in your browser, writes `~/.claude/hooks/yoru.sh`, and registers the hook in `~/.claude/settings.json`. Don't have a server yet? [Stand one up](https://github.com/TsukumoHQ/yoru) — `docker-compose up`.
 
 Requires Python 3.10+. One runtime dep: `httpx`.

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "yoru-cli"
-version = "0.1.3"
+version = "0.2.0"
 description = "Yoru — audit-grade session receipts for autonomous AI coding agents."
 license = { text = "MIT" }
 license-files = ["LICENSE"]

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/src/yoru_cli/doctor_cmd.py

@@ -6,13 +6,14 @@ Read-only check of the install:
   3. hook-token valid (GET /hook-tokens)   → else exit 3 on 401
   4. ~/.claude/hooks/yoru.sh is 0755    → else exit 4
 
-Prints ✓ lines to stdout on success (exit 0). Failures go to stderr with a
-short human-readable reason. No fixes attempted.
+Prints a ✓ line to stdout as each stage passes, so a failure leaves a visible
+trail of what already worked (✓ config / ✓ backend / token revoked → the break
+is obvious). Failures go to stderr with a short human-readable reason, then a
+non-zero exit. No fixes attempted.
 """
 from __future__ import annotations
 
 import argparse
-import os
 import stat
 import sys
 from pathlib import Path
@@ -42,6 +43,9 @@ def run(args: argparse.Namespace) -> int:  # noqa: ARG001 — argparse hands arg
     if not server or not token:
         print("yoru init not run", file=sys.stderr)
         return 1
+    # Each stage prints its check the moment it passes, so a later failure
+    # leaves a visible trail of what DID work.
+    print(f"✓ config at ~/.config/yoru/config.json (token {_token_suffix(token)})")
 
     # 2. backend /health/ready
     try:
@@ -52,6 +56,7 @@ def run(args: argparse.Namespace) -> int:  # noqa: ARG001 — argparse hands arg
     if r.status_code != 200:
         print(f"backend unreachable at {server}", file=sys.stderr)
         return 2
+    print(f"✓ backend {server} reachable")
 
     # 3. hook-token validity
     try:
@@ -72,6 +77,8 @@ def run(args: argparse.Namespace) -> int:  # noqa: ARG001 — argparse hands arg
             file=sys.stderr,
         )
         return 3
+    user = cfg.get("user") or "authenticated"
+    print(f"✓ hook-token valid (user: {user})")
 
     # 4. hook file + perms
     hook = _hook_path()
@@ -82,11 +89,5 @@ def run(args: argparse.Namespace) -> int:  # noqa: ARG001 — argparse hands arg
     if mode != 0o755:
         print("hook file missing or not 0755", file=sys.stderr)
         return 4
-
-    # all green
-    user = cfg.get("user") or "authenticated"
-    print(f"\u2713 config at ~/.config/yoru/config.json (token {_token_suffix(token)})")
-    print(f"\u2713 backend {server} reachable")
-    print(f"\u2713 hook-token valid (user: {user})")
     print("\u2713 hook installed at ~/.claude/hooks/yoru.sh")
     return 0

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/src/yoru_cli/init_cmd.py

@@ -16,6 +16,7 @@ import httpx
 from . import config
 from .api import ReceiptClient
 from .hook_template import HOOK_SCRIPT
+from .skill_template import SKILL_MD, SKILL_NAME
 
 
 def _default_label() -> str:
@@ -106,7 +107,7 @@ def _pair_device(server: str, label: str, *, no_browser: bool) -> str | None:
     interval = int(start.get("interval", 2))
 
     print()
-    print(f"  Pair this device with your Yoru account:")
+    print("  Pair this device with your Yoru account:")
     print(f"    1. Open  {verify_uri}")
     print(f"    2. Enter {user_code}")
     print()
@@ -143,11 +144,22 @@ def _pair_device(server: str, label: str, *, no_browser: bool) -> str | None:
     return None
 
 
-def refresh_hook_assets() -> tuple[Path, Path]:
-    """(Re)write the Claude Code hook script and (re)register it in
-    settings.json. Idempotent — used by `init` (first install) and `update`
-    (refresh the hook to the new version + repair the settings wiring). Returns
-    (hook_path, settings_path). Does NOT touch config (server/token)."""
+def _install_skill() -> Path:
+    """(Re)write the PUBLIC end-user yoru Claude Code skill so a fresh Claude
+    session can drive setup + usage. Lands at ~/.claude/skills/yoru/SKILL.md,
+    where Claude Code resolves user-level skills. Idempotent."""
+    skill_dir = Path.home() / ".claude" / "skills" / SKILL_NAME
+    os.makedirs(skill_dir, exist_ok=True)
+    skill_path = skill_dir / "SKILL.md"
+    skill_path.write_text(SKILL_MD, encoding="utf-8")
+    return skill_path
+
+
+def refresh_hook_assets() -> tuple[Path, Path, Path]:
+    """(Re)write the Claude Code hook script + the public yoru skill, and
+    (re)register the hook in settings.json. Idempotent — used by `init` (first
+    install) and `update` (refresh to the new version + repair the wiring).
+    Returns (hook_path, settings_path, skill_path). Does NOT touch config."""
     hook_dir = Path.home() / ".claude" / "hooks"
     hook_path = hook_dir / "yoru.sh"
     os.makedirs(hook_dir, exist_ok=True)
@@ -156,7 +168,9 @@ def refresh_hook_assets() -> tuple[Path, Path]:
 
     settings_path = Path.home() / ".claude" / "settings.json"
     _merge_settings_json(settings_path, hook_path)
-    return hook_path, settings_path
+
+    skill_path = _install_skill()
+    return hook_path, settings_path, skill_path
 
 
 def run(args: argparse.Namespace) -> int:
@@ -188,5 +202,6 @@ def run(args: argparse.Namespace) -> int:
     print("\u2713 config   \u2192 ~/.config/yoru/config.json")
     print("\u2713 hook     \u2192 ~/.claude/hooks/yoru.sh")
     print("\u2713 settings \u2192 ~/.claude/settings.json (hook registered)")
+    print("\u2713 skill    \u2192 ~/.claude/skills/yoru/SKILL.md (Claude can drive setup + usage)")
     print("Next: run Claude Code normally; first event streams to /sessions/events.")
     return 0

yoru_cli-0.2.0/src/yoru_cli/skill_template.py

@@ -0,0 +1,149 @@
+"""Bundled PUBLIC end-user Claude Code skill — written verbatim by `yoru init`
+to ``~/.claude/skills/yoru/SKILL.md`` (and refreshed by `yoru update`).
+
+This is the PUBLIC "how to self-host + use yoru" skill, NOT the private
+yoru-dev maintainer persona. It teaches a fresh Claude Code session to drive
+yoru setup + usage for the user ("tout copier à Claude Code, il fait tout").
+
+Hard rails baked into the copy (keep them true if you edit):
+  - yoru is SELF-HOSTED ONLY — no hosted/cloud/sign-up. `--server` is required.
+  - No private paths / internal fleet references (public/AGPL split).
+  - Public sessions are opt-in (`yoru share`) and PII-redacted — stay honest
+    about the confidentiality model.
+"""
+
+SKILL_NAME = "yoru"
+
+SKILL_MD: str = """---
+name: yoru
+description: >-
+  Set up and use yoru — self-hosted, audit-grade session receipts for Claude
+  Code and other autonomous coding agents. Use when the user wants to install
+  or configure yoru, stand up / start their own yoru backend, verify the
+  install, record a coding session, share a public session receipt (/s/:id),
+  replay a session, or understand the redaction / privacy model. yoru is
+  self-hosted only — there is no hosted service or sign-up.
+---
+
+# yoru — self-hosted session receipts
+
+yoru turns every Claude Code session into an audit-grade receipt: every tool
+call, file edit, prompt, and red-flag event streams to a dashboard the user
+runs themselves, plus a per-session A–F grade (Throughput / Reliability /
+Safety). It is **self-hosted only** — the user runs the backend on their own
+box. There is no hosted yoru, no cloud, no sign-up. Never tell the user to
+"sign up" or point them at a managed service.
+
+Two pieces:
+- **`yoru` CLI** (PyPI `yoru-cli`, MIT) — installs a Claude Code hook that
+  forwards events to a backend.
+- **the backend + dashboard** (AGPL, `github.com/TsukumoHQ/yoru`) — the user
+  stands this up themselves; it ingests events, scores sessions, and serves the
+  public session pages at `/s/:id`.
+
+When this skill is active, drive the user through whichever part they need.
+Run real commands, read their output, and fix problems — don't just narrate.
+
+## 1. Is the CLI installed?
+
+```bash
+yoru --version
+```
+
+If `yoru` is not found, install it (needs Python ≥ 3.10):
+
+```bash
+pipx install yoru-cli        # or: uv tool install yoru-cli
+```
+
+Use `pipx`/`uv`, not a bare `pip install` — on Homebrew/Debian Python the
+latter fails with `error: externally-managed-environment` (PEP 668). If the
+user has neither, a venv works: `python3 -m venv .venv && .venv/bin/pip install
+yoru-cli`.
+
+## 2. Does the user have a backend to point at?
+
+yoru needs a backend URL — there is **no default server**. Ask the user for
+their yoru server URL (e.g. `https://yoru.example.com`, or
+`http://localhost:8002` for a local one).
+
+If they don't have one yet, help them stand it up from the AGPL server repo:
+
+```bash
+git clone https://github.com/TsukumoHQ/yoru && cd yoru
+cp backend/.env.example backend/.env   # keyless self-host defaults work as-is
+make dev                               # API on :8002, dashboard on :5173
+```
+
+First run shows a wizard (or `make setup` headless) to create an admin account
+and pick a database. Defaults are local-first: SQLite + local auth, zero
+external services. Postgres / SMTP / OAuth are all optional.
+
+## 3. Pair this machine + install the hook
+
+```bash
+yoru init --server <THEIR_SERVER_URL>
+```
+
+`--server` is required. `yoru init`:
+- writes `~/.config/yoru/config.json` (server + a paired device token),
+- writes the hook to `~/.claude/hooks/yoru.sh`,
+- registers it in `~/.claude/settings.json` (PostToolUse / SessionStart / Stop).
+
+It opens a browser pairing page; the user approves the device there. For a
+headless box, pass a token instead: `yoru init --server <url> --token <token>`
+(or set `YORU_TOKEN`). Re-running is safe — add `--force` to repoint.
+
+## 4. Verify
+
+```bash
+yoru doctor
+```
+
+It prints a ✓ per stage (config → backend reachable → token valid → hook
+installed). If a stage fails, the line just before the error tells you what
+already worked — fix that stage:
+- *yoru init not run* → run step 3.
+- *backend unreachable* → is the server URL right and the backend up?
+- *token revoked or expired* → re-run `yoru init --force`.
+- *hook file missing* → re-run `yoru init` (or `yoru update`).
+
+## 5. Record a session
+
+Nothing extra to do — just use Claude Code normally. The hook streams each
+event to the backend, and the session appears in the dashboard automatically
+with its A–F grade. To refresh the hook after a CLI upgrade: `yoru update`.
+
+yoru flags six kinds of red-flag events at ingest, so the user can audit them:
+`secret` (leaked keys), `env` (writes to `.env*`), `shell` (`rm`/`dd`/`mkfs`),
+`db` (`DROP`/`TRUNCATE`/unscoped `DELETE`), `migration` (edits under
+`migrations/`), `ci` (edits under `.github/workflows/`, Dockerfile, etc.).
+
+## 6. Share a session (and the privacy model)
+
+By default every session is **private** — `/s/:id` returns 404 on purpose.
+Sharing is explicit and per-session:
+
+```bash
+yoru share <SESSION_ID> --server <THEIR_SERVER_URL>
+```
+
+This flips that one session public and gives a shareable URL (on the user's own
+host, e.g. `https://yoru.example.com/s/<id>`). The public page is the session
+trail + grade, with a replay view of the event timeline.
+
+Be honest with the user about what sharing exposes: a public session is
+**PII-redacted on the wire** — the viewer sees a session id, not the user's
+email — but it DOES show the tool calls, file paths, and any flagged content
+captured in that session. Only share sessions that are safe to make public, and
+only ones the user explicitly chooses. Sharing is opt-in and reversible from the
+dashboard.
+
+## Honesty rails
+
+- Self-hosted only. Never promise hosting, "sign up", "managed", "free
+  forever", or cloud pricing.
+- `--server` is always required; there is no default.
+- Don't overstate redaction — emails are stripped, but shared trails still
+  contain whatever the agent did. Say so.
+"""

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/src/yoru_cli/update_cmd.py

@@ -141,7 +141,7 @@ def run(args: argparse.Namespace) -> int:
     # --- refresh side-assets (best-effort; never fails the binary update) ----
     try:
         init_cmd.refresh_hook_assets()
-        print("✓ hook + settings refreshed")
+        print("✓ hook + settings + skill refreshed")
     except Exception as e:  # noqa: BLE001 — side-asset failure must not fail update
         print(f"note: could not refresh the hook assets ({e}); run `yoru init --force`.")
 

yoru_cli-0.2.0/tests/test_doctor.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+import argparse
+
+
+def _args() -> argparse.Namespace:
+    return argparse.Namespace(cmd="doctor")
+
+
+def test_doctor_exits_1_when_config_missing(monkeypatch, tmp_path, capsys):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    from yoru_cli import config, doctor_cmd
+
+    assert config.exists() is False
+    rc = doctor_cmd.run(_args())
+    assert rc == 1
+    err = capsys.readouterr().err
+    assert "yoru init not run" in err
+
+
+def test_doctor_prints_passed_stages_before_a_failure(monkeypatch, tmp_path, capsys):
+    """A later-stage failure still shows the ✓ trail of what already worked."""
+    monkeypatch.setenv("HOME", str(tmp_path))
+    monkeypatch.setenv("XDG_CONFIG_HOME", str(tmp_path / ".config"))
+    from yoru_cli import config, doctor_cmd
+
+    # config stage passes; backend stage fails (nothing is listening).
+    config.save({"server": "http://127.0.0.1:1", "token": "rcpt_test_abcd"})
+
+    rc = doctor_cmd.run(_args())
+    out = capsys.readouterr()
+    assert rc == 2  # failed at the backend stage
+    assert "✓ config" in out.out  # but the passed stage was reported first
+    assert "backend unreachable" in out.err

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/tests/test_init.py

@@ -42,6 +42,30 @@ def test_init_writes_config_and_hook(monkeypatch, tmp_path):
     assert "rcpt_ABC" in cfg_path.read_text()
 
 
+def test_init_lands_public_skill(monkeypatch, tmp_path):
+    monkeypatch.setenv("HOME", str(tmp_path))
+    from yoru_cli import init_cmd
+
+    rc = init_cmd.run(_args(server="http://fake", token="rcpt_ABC"))
+    assert rc == 0
+
+    skill = tmp_path / ".claude" / "skills" / "yoru" / "SKILL.md"
+    assert skill.is_file()
+    body = skill.read_text()
+    # Valid Claude Code skill frontmatter + the public name it resolves by.
+    assert body.startswith("---\n")
+    assert "name: yoru" in body
+    assert "description:" in body
+    # Honesty rails baked in (self-hosted only; --server has no default).
+    assert "self-hosted" in body.lower()
+    assert "--server" in body
+    # Public/AGPL split — the shipped skill must not leak private fleet paths
+    # or the private maintainer persona.
+    assert ".worktrees" not in body
+    assert "yoru-dev" not in body
+    assert "agent-relay" not in body
+
+
 def test_init_already_installed_without_force(monkeypatch, tmp_path, capsys):
     monkeypatch.setenv("HOME", str(tmp_path))
     from yoru_cli import init_cmd

{yoru_cli-0.1.3 → yoru_cli-0.2.0}/tests/test_update.py

@@ -24,7 +24,7 @@ def calls(monkeypatch):
     monkeypatch.setattr(update_cmd, "_pip_install", lambda v: rec["pip"].append(v) or 0)
     monkeypatch.setattr(
         init_cmd, "refresh_hook_assets",
-        lambda: rec.__setitem__("refresh", rec["refresh"] + 1) or (None, None),
+        lambda: rec.__setitem__("refresh", rec["refresh"] + 1) or (None, None, None),
     )
     monkeypatch.setattr(update_cmd, "_fetch_latest_tag", lambda **_: "v0.1.3")
     return rec

yoru_cli-0.1.3/tests/test_doctor.py

@@ -1,18 +0,0 @@
-from __future__ import annotations
-
-import argparse
-
-
-def _args() -> argparse.Namespace:
-    return argparse.Namespace(cmd="doctor")
-
-
-def test_doctor_exits_1_when_config_missing(monkeypatch, tmp_path, capsys):
-    monkeypatch.setenv("HOME", str(tmp_path))
-    from yoru_cli import config, doctor_cmd
-
-    assert config.exists() is False
-    rc = doctor_cmd.run(_args())
-    assert rc == 1
-    err = capsys.readouterr().err
-    assert "yoru init not run" in err