yoru-cli 0.1.0__tar.gz

yoru_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,6 @@
+{
+  "enabledMcpjsonServers": [
+    "context7",
+    "agent-relay"
+  ]
+}

yoru_cli-0.1.0/.gitignore

@@ -0,0 +1,71 @@
+# overnight-saas root .gitignore
+
+# Python
+__pycache__/
+*.py[cod]
+*.pyc
+*.pyo
+*.egg-info/
+.Python
+.venv/
+venv/
+env/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+*.cover
+
+# Node / frontend
+node_modules/
+dist/
+build/
+.vite/
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+
+# uv / pip
+uv.lock.tmp
+pip-wheel-metadata/
+
+# Env / secrets (NEVER commit)
+.env
+.env.*
+!.env.example
+!.env.template
+
+# Editors / OS
+.DS_Store
+Thumbs.db
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Docker local data
+docker/.data/
+
+# Receipt v0 local SQLite
+backend/data/*.db
+backend/data/*.db-*
+backend/data/backups/*.db
+backend/data/backups/*.db-*
+
+# Agent / vault ephemeral
+vault/STOP_NIGHT.off
+vault/*.off
+
+# Agent worktrees
+.worktrees/
+
+# Skill / agent working files — not code
+.agents/
+
+# Stray SQLite at backend root (dev-time artifact, real DB lives at backend/data/)
+backend/receipt.db
+
+# Runtime caches populated by pricing warmup etc.
+backend/data/*.json

yoru_cli-0.1.0/LICENSE

@@ -0,0 +1,31 @@
+MIT License
+
+Copyright (c) 2026 Yoru authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+─────────────────────────────────────────────────────────────────────────
+
+SCOPE: The Yoru CLI — everything inside the `yoru-cli/` directory in
+the Yoru monorepo. The CLI is intentionally MIT so it can be freely
+embedded in proprietary dev environments, CI pipelines, internal tooling,
+and closed-source forks without viral license obligations.
+
+The SERVER (backend + dashboard + marketing + infra) is AGPL-3.0 — see the
+`LICENSE` file at the repository root and `LICENSING.md` for the rationale.

yoru_cli-0.1.0/PKG-INFO

@@ -0,0 +1,61 @@
+Metadata-Version: 2.4
+Name: yoru-cli
+Version: 0.1.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
+Project-URL: Repository, https://github.com/helios-code/overnight-saas
+Project-URL: Issues, https://github.com/helios-code/overnight-saas/issues
+Author-email: Yoru authors <hello@opentruth.ch>
+License: MIT
+License-File: LICENSE
+Keywords: ai-agents,aider,audit,claude-code,cursor,observability
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.27
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# yoru-cli
+
+Yoru — audit-grade session receipts for autonomous AI coding agents.
+
+One command installs a Claude Code hook that streams every tool call into the Yoru backend; the dashboard turns that feed into a signed session receipt.
+
+## Install
+
+```bash
+pip install -e .          # from the monorepo
+# or once published:
+# pip install yoru-cli
+```
+
+Requires Python 3.10+. Only runtime dep is `httpx`.
+
+## Usage
+
+```bash
+yoru init                         # writes ~/.claude/hooks/yoru.sh + ~/.config/yoru/config.json (0600)
+yoru init --server http://localhost:8002 --user you@example.com    # non-interactive (CI/smoke)
+yoru init --server http://localhost:8002 --token rcpt_xxx --force
+
+yoru tail                         # reads JSON events on stdin, POSTs them as a batch (dev/debug)
+echo '{"session_id":"s1","user":"dev","kind":"tool_use","tool":"Bash"}' | yoru tail
+
+receipt --version                    # receipt 0.1.0
+receipt --help
+```
+
+Exit codes: `0` ok, `1` already installed without `--force`, `2` auth failed, `3` 4xx, `4` 5xx/network.
+
+## Spec
+
+Frozen design doc: `vault/CLI-V0-DESIGN.md` in the monorepo (§1 layout, §2 pyproject, §3 subcommands, §4 hook shape, §5 auth, §7 event schema).

yoru_cli-0.1.0/README.md

@@ -0,0 +1,35 @@
+# yoru-cli
+
+Yoru — audit-grade session receipts for autonomous AI coding agents.
+
+One command installs a Claude Code hook that streams every tool call into the Yoru backend; the dashboard turns that feed into a signed session receipt.
+
+## Install
+
+```bash
+pip install -e .          # from the monorepo
+# or once published:
+# pip install yoru-cli
+```
+
+Requires Python 3.10+. Only runtime dep is `httpx`.
+
+## Usage
+
+```bash
+yoru init                         # writes ~/.claude/hooks/yoru.sh + ~/.config/yoru/config.json (0600)
+yoru init --server http://localhost:8002 --user you@example.com    # non-interactive (CI/smoke)
+yoru init --server http://localhost:8002 --token rcpt_xxx --force
+
+yoru tail                         # reads JSON events on stdin, POSTs them as a batch (dev/debug)
+echo '{"session_id":"s1","user":"dev","kind":"tool_use","tool":"Bash"}' | yoru tail
+
+receipt --version                    # receipt 0.1.0
+receipt --help
+```
+
+Exit codes: `0` ok, `1` already installed without `--force`, `2` auth failed, `3` 4xx, `4` 5xx/network.
+
+## Spec
+
+Frozen design doc: `vault/CLI-V0-DESIGN.md` in the monorepo (§1 layout, §2 pyproject, §3 subcommands, §4 hook shape, §5 auth, §7 event schema).

yoru_cli-0.1.0/pyproject.toml

@@ -0,0 +1,44 @@
+[project]
+name = "yoru-cli"
+version = "0.1.0"
+description = "Yoru — audit-grade session receipts for autonomous AI coding agents."
+license = { text = "MIT" }
+license-files = ["LICENSE"]
+readme = "README.md"
+authors = [{ name = "Yoru authors", email = "hello@opentruth.ch" }]
+keywords = ["claude-code", "cursor", "aider", "ai-agents", "observability", "audit"]
+classifiers = [
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+]
+requires-python = ">=3.10"
+dependencies = ["httpx>=0.27"]
+
+[project.urls]
+Homepage = "https://yoru.sh"
+Documentation = "https://yoru.sh/docs"
+Repository = "https://github.com/helios-code/overnight-saas"
+Issues = "https://github.com/helios-code/overnight-saas/issues"
+
+[project.scripts]
+yoru = "yoru_cli.cli:main"
+
+[project.optional-dependencies]
+dev = ["pytest>=7"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yoru_cli"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

yoru_cli-0.1.0/src/yoru_cli/__init__.py

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

yoru_cli-0.1.0/src/yoru_cli/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

yoru_cli-0.1.0/src/yoru_cli/api.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from typing import Any
+
+import httpx
+
+
+class ReceiptClient:
+    def __init__(self, base_url: str, token: str | None = None) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+
+    def start_device_code(self, label: str | None = None) -> dict[str, Any]:
+        """Begin the device-pairing handshake — no auth needed."""
+        r = httpx.post(
+            f"{self.base_url}/api/v1/auth/device-code",
+            json={"label": label} if label else {},
+            timeout=5.0,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def poll_device_code(self, device_code: str) -> dict[str, Any]:
+        """Poll for approval — returns {status, token?}."""
+        r = httpx.post(
+            f"{self.base_url}/api/v1/auth/device-code/poll",
+            json={"device_code": device_code},
+            timeout=10.0,
+        )
+        r.raise_for_status()
+        return r.json()
+
+    def post_events(self, events: list[dict[str, Any]]) -> httpx.Response:
+        headers = {"Authorization": f"Bearer {self.token}"} if self.token else {}
+        return httpx.post(
+            f"{self.base_url}/api/v1/sessions/events",
+            json={"events": events},
+            headers=headers,
+            timeout=5.0,
+        )

yoru_cli-0.1.0/src/yoru_cli/cli.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+import argparse
+
+from . import __version__
+from . import config, doctor_cmd, init_cmd, tail_cmd
+
+DEFAULT_SERVER = "https://api.yoru.sh"
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="yoru",
+        description="Yoru — audit-grade session receipts for autonomous AI coding agents.",
+    )
+    parser.add_argument(
+        "--version",
+        action="version",
+        version=f"yoru {__version__}",
+    )
+
+    subparsers = parser.add_subparsers(dest="cmd", required=True, metavar="{init,tail,doctor}")
+
+    p_init = subparsers.add_parser(
+        "init",
+        help="Install the Claude Code hook and write ~/.config/yoru/config.json.",
+    )
+    p_init.add_argument("--server", default=DEFAULT_SERVER, help=f"Backend URL (default: {DEFAULT_SERVER})")
+    p_init.add_argument(
+        "--token",
+        default=None,
+        help="Pre-minted hook token (rcpt_...) — for headless/CI/server setups. "
+             "Also read from $YORU_TOKEN. Without this, yoru init launches "
+             "interactive device pairing.",
+    )
+    p_init.add_argument(
+        "--label",
+        default=None,
+        help="Human-readable machine label shown in the dashboard "
+             "(default: <hostname> · <os>).",
+    )
+    p_init.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Don't try to auto-open the pairing URL in a browser.",
+    )
+    p_init.add_argument("--force", action="store_true", help="Overwrite an existing install.")
+
+    p_tail = subparsers.add_parser(
+        "tail",
+        help="Read JSON events from stdin and POST them as a batch (dev/debug).",
+    )
+    p_tail.add_argument(
+        "--server",
+        default=None,
+        help=f"Backend URL (default: value from config, else {DEFAULT_SERVER}).",
+    )
+    p_tail.add_argument("--session-id", default=None, help="Session id to stamp on events missing one.")
+
+    subparsers.add_parser(
+        "doctor",
+        help="Diagnose the install: config, backend, token, hook.",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.cmd == "tail" and args.server is None:
+        cfg = config.load() or {}
+        args.server = cfg.get("server", DEFAULT_SERVER)
+
+    if args.cmd == "init":
+        return init_cmd.run(args)
+    if args.cmd == "tail":
+        return tail_cmd.run(args)
+    if args.cmd == "doctor":
+        return doctor_cmd.run(args)
+
+    parser.error(f"unknown command: {args.cmd!r}")
+    return 2

yoru_cli-0.1.0/src/yoru_cli/config.py

@@ -0,0 +1,43 @@
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+
+def _config_dir() -> Path:
+    return Path.home() / ".config" / "yoru"
+
+
+def _config_file() -> Path:
+    return _config_dir() / "config.json"
+
+
+CONFIG_DIR: Path = _config_dir()
+CONFIG_FILE: Path = _config_file()
+
+
+def exists() -> bool:
+    return _config_file().is_file()
+
+
+def load() -> dict[str, Any] | None:
+    path = _config_file()
+    if not path.is_file():
+        return None
+    with path.open("r", encoding="utf-8") as f:
+        return json.load(f)
+
+
+def save(data: dict[str, Any]) -> None:
+    dir_path = _config_dir()
+    file_path = _config_file()
+    os.makedirs(dir_path, mode=0o700, exist_ok=True)
+    payload = dict(data)
+    payload.setdefault("created_at", datetime.now(timezone.utc).isoformat())
+    fd = os.open(file_path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        json.dump(payload, f, indent=2, sort_keys=True)
+        f.write("\n")

yoru_cli-0.1.0/src/yoru_cli/doctor_cmd.py

@@ -0,0 +1,92 @@
+"""`yoru doctor` — diagnostic subcommand.
+
+Read-only check of the install:
+  1. config.json present                   → else exit 1
+  2. backend /health/ready reachable       → else exit 2
+  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.
+"""
+from __future__ import annotations
+
+import argparse
+import os
+import stat
+import sys
+from pathlib import Path
+
+import httpx
+
+from . import config
+
+
+def _token_suffix(token: str) -> str:
+    tail = token[-4:] if len(token) >= 4 else token
+    return f"rcpt_...{tail}"
+
+
+def _hook_path() -> Path:
+    return Path.home() / ".claude" / "hooks" / "yoru.sh"
+
+
+def run(args: argparse.Namespace) -> int:  # noqa: ARG001 — argparse hands args, unused for now
+    # 1. config
+    cfg = config.load()
+    if cfg is None:
+        print("yoru init not run", file=sys.stderr)
+        return 1
+    server = (cfg.get("server") or "").rstrip("/")
+    token = cfg.get("token") or ""
+    if not server or not token:
+        print("yoru init not run", file=sys.stderr)
+        return 1
+
+    # 2. backend /health/ready
+    try:
+        r = httpx.get(f"{server}/health/ready", timeout=5.0)
+    except httpx.HTTPError:
+        print(f"backend unreachable at {server}", file=sys.stderr)
+        return 2
+    if r.status_code != 200:
+        print(f"backend unreachable at {server}", file=sys.stderr)
+        return 2
+
+    # 3. hook-token validity
+    try:
+        r = httpx.get(
+            f"{server}/api/v1/auth/hook-tokens",
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=5.0,
+        )
+    except httpx.HTTPError:
+        print(f"backend unreachable at {server}", file=sys.stderr)
+        return 2
+    if r.status_code == 401:
+        print("token revoked or expired", file=sys.stderr)
+        return 3
+    if r.status_code != 200:
+        print(
+            f"hook-token check failed: HTTP {r.status_code}",
+            file=sys.stderr,
+        )
+        return 3
+
+    # 4. hook file + perms
+    hook = _hook_path()
+    if not hook.is_file():
+        print("hook file missing or not 0755", file=sys.stderr)
+        return 4
+    mode = stat.S_IMODE(hook.stat().st_mode)
+    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.0/src/yoru_cli/hook_template.py

@@ -0,0 +1,119 @@
+"""Bundled Claude Code hook script — written verbatim by `yoru init`.
+
+Shape is frozen in vault/CLI-V0-DESIGN.md §4. Bash (not Python) for fast startup;
+`curl --max-time 2 || true` keeps the hook from ever blocking the agent.
+v0 posts one event per tool call — batching is a v1 optimization.
+
+Subscribed hook events (configured in ~/.claude/settings.json):
+  - SessionStart        → kind=session_start
+  - UserPromptSubmit    → kind=message (prompt text captured)
+  - PostToolUse         → kind inferred (tool_use | file_change)
+  - Notification        → kind=message (permission/input prompts)
+  - Stop                → kind=session_end
+  - SubagentStop        → kind=message (lightweight, doesn't close session)
+
+PreToolUse is NOT subscribed — PostToolUse carries the same tool_input plus
+tool_response, so subscribing to both doubles traffic for no gain.
+"""
+
+HOOK_SCRIPT: str = """#!/usr/bin/env bash
+# Claude Code hook — Receipt ingest. Handles all subscribed hook events.
+set -euo pipefail
+# Skip events when AGENT_RELAY_CHILD=1 (agent-relay-spawned children — prevents dashboard noise)
+[ "${AGENT_RELAY_CHILD:-0}" = "1" ] && exit 0
+CFG="${HOME}/.config/yoru/config.json"
+[ -r "$CFG" ] || exit 0          # silent no-op if uninstalled
+SERVER=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.config/yoru/config.json")))["server"])')
+TOKEN=$(python3 -c 'import json,os;print(json.load(open(os.path.expanduser("~/.config/yoru/config.json")))["token"])')
+# Claude Code pipes the hook event as JSON on stdin. We parse the original
+# payload, attach it verbatim to `raw` (so the backend sees tool_input /
+# tool_response — Pydantic drops unknown top-level fields otherwise), then
+# mutate the top-level envelope with `kind` + extracted `content` for the
+# renderer-friendly shape.
+#
+# Routing context (Phase C): hook detects cwd + git remote/branch and ships
+# them with every event so the server can route the session to the right
+# workspace. `git` calls are cached per-session in $TMPDIR to keep the hook
+# fast on hot PostToolUse paths.
+BODY=$(python3 -c 'import sys,json,os,subprocess
+original=json.loads(sys.stdin.read())
+e=dict(original)
+e["raw"]=original
+
+# Routing context — cwd from Claude payload (reliable), git info cached.
+cwd = original.get("cwd")
+if isinstance(cwd, str) and cwd:
+    e["cwd"] = cwd
+
+sess_id = original.get("session_id") or original.get("sessionId") or ""
+cache_dir = os.environ.get("TMPDIR", "/tmp")
+cache = os.path.join(cache_dir, f".receipt-ctx-{sess_id}.env") if sess_id else None
+git_remote = None
+git_branch = None
+if cache and os.path.exists(cache):
+    try:
+        for line in open(cache, encoding="utf-8"):
+            k,_,v = line.strip().partition("=")
+            if k == "git_remote": git_remote = v or None
+            elif k == "git_branch": git_branch = v or None
+    except Exception:
+        pass
+if (git_remote is None or git_branch is None) and isinstance(cwd, str) and cwd:
+    def _run(args):
+        try:
+            return subprocess.check_output(args, cwd=cwd, stderr=subprocess.DEVNULL, timeout=1).decode().strip() or None
+        except Exception:
+            return None
+    if git_remote is None:
+        git_remote = _run(["git","remote","get-url","origin"])
+    if git_branch is None:
+        git_branch = _run(["git","rev-parse","--abbrev-ref","HEAD"])
+    if cache:
+        try:
+            with open(cache, "w", encoding="utf-8") as f:
+                if git_remote: f.write(f"git_remote={git_remote}\\n")
+                if git_branch: f.write(f"git_branch={git_branch}\\n")
+        except Exception:
+            pass
+if git_remote: e["git_remote"] = git_remote
+if git_branch: e["git_branch"] = git_branch
+
+hen=e.get("hook_event_name")
+if hen=="SessionStart":
+    e["kind"]="session_start"
+elif hen=="UserPromptSubmit":
+    e["kind"]="message"
+    e["tool"]="user"
+    p=e.get("prompt")
+    if isinstance(p,str) and p: e["content"]=p[:2000]
+elif hen=="Notification":
+    e["kind"]="message"
+    e["tool"]="notification"
+    m=e.get("message")
+    if isinstance(m,str) and m: e["content"]=m[:2000]
+elif hen=="SubagentStop":
+    e["kind"]="message"
+    e["tool"]="subagent"
+    e["content"]="subagent stopped"
+elif hen=="Stop":
+    e["kind"]="session_end"
+# PostToolUse / PreToolUse: leave kind unset → backend _infer_kind() from tool
+print(json.dumps({"events":[e]}))')
+curl -sS --max-time 2 -X POST "${SERVER}/api/v1/sessions/events" \\
+  -H "Authorization: Bearer ${TOKEN}" \\
+  -H "Content-Type: application/json" \\
+  -d "${BODY}" >/dev/null 2>&1 || true   # never block the agent
+"""
+
+
+# Hook subscriptions to write into ~/.claude/settings.json.
+# Each entry is a (hook_event_name, description) pair; the installer writes a
+# single `matcher:"*"` entry per event pointing at ~/.claude/hooks/yoru.sh.
+HOOK_SUBSCRIPTIONS: list[tuple[str, str]] = [
+    ("SessionStart",     "capture session boundary"),
+    ("UserPromptSubmit", "capture user prompts (message events)"),
+    ("PostToolUse",      "capture tool_use + file_change"),
+    ("Notification",     "capture permission/input prompts"),
+    ("Stop",             "capture session close"),
+    ("SubagentStop",     "capture subagent lifecycle"),
+]