realitydiff 0.4.0__tar.gz → 0.4.1__tar.gz

realitydiff-0.4.1/.github/workflows/ci.yml

@@ -0,0 +1,32 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install bun (used by the UI tests)
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+
+      - name: Run tests
+        run: uv run --extra dev pytest -q

realitydiff-0.4.1/.github/workflows/pypi-publish.yml

@@ -0,0 +1,99 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    name: Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.11"
+
+      - name: Install bun (used by the UI tests)
+        uses: oven-sh/setup-bun@0c5077e51419868618aeaa5fe8019c62421857d6 # v2.2.0
+
+      - name: Run tests
+        run: uv run --extra dev pytest -q
+
+  build:
+    name: Build distribution
+    needs: test
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e # v10.3.2
+        with:
+          python-version: "3.11"
+
+      - name: Check release tag matches pyproject version
+        env:
+          TAG: ${{ github.event.release.tag_name }}
+        run: |
+          version=$(python3 -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "$TAG" != "v$version" ]; then
+            echo "Release tag $TAG does not match pyproject version v$version" >&2
+            exit 1
+          fi
+
+      - name: Build package
+        run: uv build
+
+      - name: Check package contents
+        run: |
+          for whl in dist/*.whl; do
+            bad=$(unzip -Z1 "$whl" | grep -v -E '^(realitydiff/|realitydiff-[^/]*\.dist-info/)' || true)
+            if [ -n "$bad" ]; then
+              echo "Unexpected files in wheel:" >&2
+              echo "$bad" >&2
+              exit 1
+            fi
+          done
+          secrets=$( { unzip -Z1 dist/*.whl; tar tzf dist/*.tar.gz; } | grep -E '(^|/)(\.env[^/]*|[^/]*\.(pem|key))$' || true)
+          if [ -n "$secrets" ]; then
+            echo "Secret-looking files in the package:" >&2
+            echo "$secrets" >&2
+            exit 1
+          fi
+
+      - name: Upload distribution
+        uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2
+        with:
+          name: python-package-distributions
+          path: dist/
+          if-no-files-found: error
+
+  publish:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/p/realitydiff
+    permissions:
+      id-token: write
+      attestations: write
+      contents: read
+      actions: read
+    steps:
+      - name: Download distribution
+        uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333 # v8.0.2
+        with:
+          name: python-package-distributions
+          path: dist/
+
+      - name: Publish package distributions to PyPI
+        uses: pypa/gh-action-pypi-publish@7245906fb61fa33a13554f9d5fb856fe61758086 # v1.14.3

realitydiff-0.4.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: realitydiff
+Version: 0.4.1
+Summary: Git for beliefs — living claims that watch the internet and version confidence.
+Project-URL: Homepage, https://github.com/kavin0x/RealityDiff
+Project-URL: Source, https://github.com/kavin0x/RealityDiff
+Project-URL: Issues, https://github.com/kavin0x/RealityDiff/issues
+Author: Kavin Shah
+License: MIT License
+        
+        Copyright (c) 2026 Reality Diff contributors
+        
+        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.
+License-File: LICENSE
+Keywords: beliefs,claims,fact-checking,grok,xai
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Python: >=3.11
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: pydantic>=2.10.0
+Requires-Dist: uvicorn[standard]>=0.34.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
+Requires-Dist: pytest>=8.3.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Reality Diff
+
+Git for beliefs — a version history of a claim: evidence, confidence, and why that number moved. For people tracking a story that is still unfolding (products, policy, markets) who want a trail, not a vibe.
+
+## Why I built this
+
+News feeds overwrite your memory. Last week’s confidence on a rumor disappears under today’s take. I wanted git-style operations on a belief: commit when evidence actually moves, diff two weeks, blame a confidence jump, browse the claim as of a SHA, or revert a panic. So I built Reality Diff.
+
+## News feed vs this
+
+| | Typical news / search | Reality Diff |
+| --- | --- | --- |
+| Memory | Overwritten | Versioned history per claim |
+| Confidence | Vibes / headlines | Explicit score + reason when it moves |
+| Compare | Manual screenshots | `diff` between commits |
+| Undo | None | `revert` to an earlier belief state |
+
+## Features
+
+**Claims**
+
+- Open a claim (e.g. “Apple is going to replace Siri with an LLM”)
+- Living object: evidence for/against, unknowns, predictions, confidence
+- Commits only when **meaningful** new evidence appears (cosmetic rewrites dropped)
+
+**Git-style ops**
+
+- `commit` · `diff` · `blame` · `revert` · `watch` · `log`
+- Browse the belief as of any SHA
+- Background watch via OS timer (macOS LaunchAgent / Linux systemd / Windows task) or the UI interval picker
+
+**Surfaces**
+
+- Local web UI (`realitydiff serve` → <http://localhost:8000>)
+- CLI for agents and scripts
+- REST API for the same actions
+
+## Install
+
+From PyPI (needs Python 3.11+). `uv` and `pipx` each give it its own isolated environment, so use one of them first:
+
+```bash
+uv tool install realitydiff     # or: pipx install realitydiff
+realitydiff                     # first run walks you through setup
+```
+
+Plain `pip install realitydiff` works inside a virtualenv. On macOS and many Linux setups, system-wide `pip` refuses with an "externally-managed-environment" error, which is why I lead with `uv`/`pipx`.
+
+The first time you run `realitydiff` in a terminal (or any time you run `realitydiff setup`), it does what the old installer did: checks the install, offers to save your `XAI_API_KEY` to `~/.config/realitydiff/env` (permissions 600, typing is hidden), and tells you if the command isn't on your PATH. `realitydiff setup --yes` never prompts, and `--no-key` skips the key.
+
+Prefer a script that also installs `uv` for you (macOS or Linux, no sudo)?
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh
+```
+
+Read it first if you like: download `install.sh`, then run `sh install.sh --help`. Options go after `sh -s --`: `--yes`, `--ref <tag-or-commit>`, `--uninstall`.
+
+Want the latest unreleased code instead of PyPI?
+
+```bash
+uv tool install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
+```
+
+Then:
+
+```bash
+realitydiff serve                       # binds to 127.0.0.1 only; open http://127.0.0.1:8000
+```
+
+The installed CLI keeps claims in `~/.local/share/realitydiff/` (set `REALITYDIFF_DB` to change it). Inside a checkout it still uses `data/`.
+
+## Try it (from a checkout)
+
+```bash
+export XAI_API_KEY=...
+uv sync --extra dev
+uv run realitydiff serve
+# open http://localhost:8000
+```
+
+```bash
+uv run realitydiff open "Apple is going to replace Siri with an LLM."
+uv run realitydiff watch <claim_id>
+uv run realitydiff log <claim_id>
+uv run realitydiff diff <claim_id> <sha_a> <sha_b>
+```
+
+```bash
+uv run realitydiff service install --interval 300
+uv run pytest
+```
+
+## Stack
+
+Python 3.11+ · uv · local web UI + REST · xAI Responses API (web + X search) · MIT
+
+## License
+
+[MIT](LICENSE)

{realitydiff-0.4.0 → realitydiff-0.4.1}/README.md

@@ -37,35 +37,35 @@ News feeds overwrite your memory. Last week’s confidence on a rumor disappears
 
 ## Install
 
-One line (macOS or Linux, no sudo):
+From PyPI (needs Python 3.11+). `uv` and `pipx` each give it its own isolated environment, so use one of them first:
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh
+uv tool install realitydiff     # or: pipx install realitydiff
+realitydiff                     # first run walks you through setup
 ```
 
-It installs [uv](https://docs.astral.sh/uv/) into `~/.local/bin` if you don't have it, installs `realitydiff` as an isolated uv tool, and can save your `XAI_API_KEY` to `~/.config/realitydiff/env` (permissions 600). It never uses sudo and only touches your shell rc if you say yes.
+Plain `pip install realitydiff` works inside a virtualenv. On macOS and many Linux setups, system-wide `pip` refuses with an "externally-managed-environment" error, which is why I lead with `uv`/`pipx`.
+
+The first time you run `realitydiff` in a terminal (or any time you run `realitydiff setup`), it does what the old installer did: checks the install, offers to save your `XAI_API_KEY` to `~/.config/realitydiff/env` (permissions 600, typing is hidden), and tells you if the command isn't on your PATH. `realitydiff setup --yes` never prompts, and `--no-key` skips the key.
+
+Prefer a script that also installs `uv` for you (macOS or Linux, no sudo)?
 
 ```bash
-# options go after `sh -s --`
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --yes          # no prompts
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --ref <tag-or-commit>
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --uninstall
+curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh
 ```
 
-Prefer to read it first? Download `install.sh`, look it over, then run `sh install.sh --help`.
+Read it first if you like: download `install.sh`, then run `sh install.sh --help`. Options go after `sh -s --`: `--yes`, `--ref <tag-or-commit>`, `--uninstall`.
 
-Or install by hand:
+Want the latest unreleased code instead of PyPI?
 
 ```bash
 uv tool install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
-# or
-pipx install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
 ```
 
 Then:
 
 ```bash
-realitydiff serve --host 127.0.0.1   # open http://127.0.0.1:8000
+realitydiff serve                       # binds to 127.0.0.1 only; open http://127.0.0.1:8000
 ```
 
 The installed CLI keeps claims in `~/.local/share/realitydiff/` (set `REALITYDIFF_DB` to change it). Inside a checkout it still uses `data/`.

{realitydiff-0.4.0 → realitydiff-0.4.1}/pyproject.toml

@@ -1,9 +1,21 @@
 [project]
 name = "realitydiff"
-version = "0.4.0"
+version = "0.4.1"
 description = "Git for beliefs — living claims that watch the internet and version confidence."
 readme = "README.md"
 requires-python = ">=3.11"
+license = { file = "LICENSE" }
+authors = [{ name = "Kavin Shah" }]
+keywords = ["claims", "beliefs", "fact-checking", "xai", "grok"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
 dependencies = [
     "fastapi>=0.115.0",
     "httpx>=0.28.0",
@@ -11,6 +23,11 @@ dependencies = [
     "uvicorn[standard]>=0.34.0",
 ]
 
+[project.urls]
+Homepage = "https://github.com/kavin0x/RealityDiff"
+Source = "https://github.com/kavin0x/RealityDiff"
+Issues = "https://github.com/kavin0x/RealityDiff/issues"
+
 [project.optional-dependencies]
 dev = [
     "pytest>=8.3.0",

{realitydiff-0.4.0 → realitydiff-0.4.1}/src/realitydiff/__init__.py

@@ -5,4 +5,4 @@ from realitydiff.models import ClaimState, Commit
 from realitydiff.service import RealityDiff
 
 __all__ = ["Claim", "ClaimState", "Commit", "RealityDiff"]
-__version__ = "0.4.0"
+__version__ = "0.4.1"

{realitydiff-0.4.0 → realitydiff-0.4.1}/src/realitydiff/cli.py

@@ -2,11 +2,13 @@ from __future__ import annotations
 
 import argparse
 import json
+import os
 import sys
 from pathlib import Path
 
 from realitydiff import __version__
 from realitydiff.config import config_file, default_db, load_env
+from realitydiff.setup import needs_first_run, run_setup
 from realitydiff.service import RealityDiff
 from realitydiff.xai import XAIError
 
@@ -29,10 +31,32 @@ def _print(data) -> None:
         print(json.dumps(data, indent=2, default=str))
 
 
+def _ensure_key() -> bool:
+    """True when an xAI key is available. Offers first-run setup to a person at a terminal."""
+    if os.environ.get("XAI_API_KEY"):
+        return True
+    if needs_first_run():
+        print("realitydiff: first run, so let's set up.\n", file=sys.stderr)
+        run_setup()
+        print()
+        load_env()
+        if os.environ.get("XAI_API_KEY"):
+            return True
+    print(
+        f"realitydiff: XAI_API_KEY is not set. Run `realitydiff setup`, export it, or save it in {config_file()}",
+        file=sys.stderr,
+    )
+    return False
+
+
 def main(argv: list[str] | None = None) -> int:
     parser = argparse.ArgumentParser(prog="realitydiff", description="Git for beliefs")
     parser.add_argument("--version", action="version", version=f"realitydiff {__version__}")
-    sub = parser.add_subparsers(dest="cmd", required=True)
+    sub = parser.add_subparsers(dest="cmd")
+
+    setup_p = sub.add_parser("setup", help="Guided setup: save your xAI key and check your PATH")
+    setup_p.add_argument("-y", "--yes", action="store_true", help="Non-interactive: accept defaults, never prompt")
+    setup_p.add_argument("--no-key", action="store_true", help="Skip the XAI_API_KEY prompt")
 
     open_p = sub.add_parser("open", help="Create a living claim and survey the internet")
     open_p.add_argument("statement")
@@ -67,7 +91,7 @@ def main(argv: list[str] | None = None) -> int:
     ls_p = sub.add_parser("ls", help="List claims")
 
     serve_p = sub.add_parser("serve", help="Run the web UI")
-    serve_p.add_argument("--host", default="0.0.0.0")
+    serve_p.add_argument("--host", default="127.0.0.1", help="Bind address. Use 0.0.0.0 only if you want other machines to reach it")
     serve_p.add_argument("--port", type=int, default=8000)
 
     svc = sub.add_parser("service", help="Install a background timer that runs claim.watch()")
@@ -78,7 +102,16 @@ def main(argv: list[str] | None = None) -> int:
     svc_sub.add_parser("status", help="Show whether the service is installed")
 
     args = parser.parse_args(argv)
+    if args.cmd is None:
+        if needs_first_run():
+            return run_setup()
+        parser.print_help()
+        return 0
+    if args.cmd == "setup":
+        return run_setup(assume_yes=args.yes, skip_key=args.no_key)
     if args.cmd == "serve":
+        if not _ensure_key():
+            return 2
         import uvicorn
 
         print(f"realitydiff: database {_db_path()}", file=sys.stderr)
@@ -97,10 +130,12 @@ def main(argv: list[str] | None = None) -> int:
         _print({**status(), "db": _db_path()})
         return 0
 
+    if not _ensure_key():
+        return 2
     try:
         engine = _engine()
     except XAIError as exc:
-        print(f"realitydiff: {exc}. Export it or save it in {config_file()}", file=sys.stderr)
+        print(f"realitydiff: {exc}", file=sys.stderr)
         return 2
     if args.cmd == "watch-all":
         _print([item.model_dump(mode="json") for item in engine.watch_due()])

{realitydiff-0.4.0 → realitydiff-0.4.1}/src/realitydiff/config.py

@@ -64,3 +64,70 @@ def default_db() -> str:
         return "data/realitydiff.sqlite"
     base = os.environ.get("XDG_DATA_HOME") or str(Path.home() / ".local" / "share")
     return str(Path(base) / "realitydiff" / "realitydiff.sqlite")
+
+
+_KEY_OK = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789._-")
+
+
+def valid_secret(value: str) -> bool:
+    """Same rule as install.sh: no spaces, quotes or newlines."""
+    return bool(value) and all(ch in _KEY_OK for ch in value)
+
+
+def config_has(key: str, path: Path | None = None) -> bool:
+    path = path or config_file()
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return False
+    for raw in text.splitlines():
+        line = raw.strip()
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        name, sep, value = line.partition("=")
+        if sep and name.strip() == key and value.strip():
+            return True
+    return False
+
+
+def set_config(key: str, value: str, path: Path | None = None) -> Path:
+    """Write KEY=VALUE to the config file (mode 600), keeping other lines."""
+    path = path or config_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        path.parent.chmod(0o700)
+    except OSError:
+        pass
+    kept: list[str] = []
+    try:
+        existing = path.read_text(encoding="utf-8").splitlines()
+    except OSError:
+        existing = ["# Reality Diff settings (read by the realitydiff CLI). Keep private."]
+    for raw in existing:
+        line = raw.strip()
+        if line.startswith("export "):
+            line = line[len("export ") :].strip()
+        if line.partition("=")[0].strip() == key and "=" in line:
+            continue
+        kept.append(raw)
+    kept.append(f"{key}={value}")
+    tmp = path.with_name(path.name + f".tmp{os.getpid()}")
+    fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as handle:
+            handle.write("\n".join(kept) + "\n")
+        os.replace(tmp, path)
+    finally:
+        try:
+            tmp.unlink()
+        except FileNotFoundError:
+            pass
+    try:
+        path.chmod(0o600)
+    except OSError:
+        pass
+    return path
+
+
+def setup_marker() -> Path:
+    return config_file().with_name("setup-done")

realitydiff-0.4.1/src/realitydiff/setup.py

@@ -0,0 +1,198 @@
+"""Interactive first-run setup: the same flow install.sh gives, for pip/pipx/uv installs."""
+
+from __future__ import annotations
+
+import getpass
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+
+from realitydiff import __version__
+from realitydiff.config import (
+    config_file,
+    config_has,
+    default_db,
+    set_config,
+    setup_marker,
+    valid_secret,
+)
+
+ART = r"""
+  ___          _ _ _        ___  _  __  __
+ | _ \___ __ _| (_) |_ _  _|   \(_)/ _|/ _|
+ |   / -_) _` | | |  _| || | |) | |  _|  _|
+ |_|_\___\__,_|_|_|\__|\_, |___/|_|_| |_|
+                       |__/
+"""
+
+
+class _Style:
+    def __init__(self, out) -> None:
+        fancy = out.isatty() and not os.environ.get("NO_COLOR") and os.environ.get("TERM", "dumb") != "dumb"
+        self.fancy = fancy
+        esc = "\033["
+        self.bold = f"{esc}1m" if fancy else ""
+        self.dim = f"{esc}2m" if fancy else ""
+        self.red = f"{esc}31m" if fancy else ""
+        self.green = f"{esc}32m" if fancy else ""
+        self.yellow = f"{esc}33m" if fancy else ""
+        self.cyan = f"{esc}36m" if fancy else ""
+        self.reset = f"{esc}0m" if fancy else ""
+        self.ok_mark = "✓" if fancy else "[ok]"
+
+
+def _tilde(path: str | Path) -> str:
+    text = str(path)
+    home = str(Path.home())
+    return "~" + text[len(home) :] if text.startswith(home + os.sep) else text
+
+
+def is_interactive() -> bool:
+    return sys.stdin.isatty() and sys.stdout.isatty()
+
+
+def needs_first_run() -> bool:
+    """True when nothing has configured this install yet and a person is at the keyboard."""
+    if not is_interactive():
+        return False
+    if os.environ.get("XAI_API_KEY") or config_has("XAI_API_KEY"):
+        return False
+    return not setup_marker().exists()
+
+
+def _confirm(question: str, default: bool, style: _Style, assume_yes: bool, interactive: bool, ask) -> bool:
+    if assume_yes or not interactive:
+        return default
+    hint = "[Y/n]" if default else "[y/N]"
+    answer = ask(f"  {style.cyan}?{style.reset} {question} {hint} ").strip().lower()
+    if answer in {"y", "yes"}:
+        return True
+    if answer in {"n", "no"}:
+        return False
+    return default
+
+
+def _bin_dir() -> Path | None:
+    exe = shutil.which("realitydiff")
+    if exe:
+        return Path(exe).parent
+    script = Path(sys.argv[0]).resolve() if sys.argv and sys.argv[0] else None
+    if script and script.name.startswith("realitydiff"):
+        return script.parent
+    return None
+
+
+def run_setup(
+    *,
+    assume_yes: bool = False,
+    skip_key: bool = False,
+    out=None,
+    ask=input,
+    ask_secret=getpass.getpass,
+    interactive: bool | None = None,
+) -> int:
+    out = out or sys.stdout
+    style = _Style(out)
+    interactive = is_interactive() if interactive is None else interactive
+    if assume_yes:
+        interactive = False
+    config = config_file()
+
+    def say(text: str = "") -> None:
+        print(text, file=out)
+
+    def ok(text: str) -> None:
+        say(f"  {style.green}{style.ok_mark}{style.reset} {text}")
+
+    def info(text: str) -> None:
+        say(f"  {style.dim}{text}{style.reset}")
+
+    def warn(text: str) -> None:
+        say(f"  {style.yellow}!{style.reset} {text}")
+
+    def step(n: int, total: int, title: str) -> None:
+        say(f"{style.dim}[{n}/{total}]{style.reset} {style.bold}{title}{style.reset}")
+
+    if style.fancy:
+        say(f"{style.bold}{style.cyan}{ART}{style.reset}  {style.dim}git for beliefs{style.reset}\n")
+    else:
+        say("Reality Diff setup")
+        say()
+
+    step(1, 3, "Checking the install")
+    ok(f"realitydiff {__version__} on Python {sys.version_info.major}.{sys.version_info.minor}")
+    info(f"data   {_tilde(default_db())}")
+    info(f"config {_tilde(config)}")
+
+    step(2, 3, "xAI API key")
+    saved = False
+    if skip_key:
+        info("skipped (--no-key)")
+    else:
+        have_file = config_has("XAI_API_KEY")
+        env_key = os.environ.get("XAI_API_KEY", "")
+        new_key = ""
+        if have_file:
+            ok(f"already saved in {_tilde(config)}")
+            if interactive and _confirm("Replace the saved key?", False, style, assume_yes, interactive, ask):
+                new_key = ask_secret("  ? New XAI_API_KEY (input hidden): ").strip()
+        elif interactive:
+            if env_key:
+                info("XAI_API_KEY is set in this shell")
+                if _confirm(
+                    f"Save it to {_tilde(config)} so realitydiff always finds it?", False, style, assume_yes, interactive, ask
+                ):
+                    new_key = env_key
+            elif _confirm(
+                "Save an XAI_API_KEY now? (get one at https://console.x.ai)", True, style, assume_yes, interactive, ask
+            ):
+                new_key = ask_secret("  ? XAI_API_KEY (input hidden): ").strip()
+        else:
+            info("not saved (non-interactive). Export XAI_API_KEY or run `realitydiff setup`.")
+        if new_key:
+            if valid_secret(new_key):
+                set_config("XAI_API_KEY", new_key, config)
+                ok(f"saved to {_tilde(config)} (permissions 600)")
+                saved = True
+            else:
+                warn("that key has unexpected characters (spaces, quotes or newlines?); not saved")
+        elif not have_file and interactive:
+            info("skipped. Run `realitydiff setup` any time, or export XAI_API_KEY.")
+
+    step(3, 3, "PATH")
+    bin_dir = _bin_dir()
+    on_path = bool(shutil.which("realitydiff"))
+    if on_path:
+        ok(f"`realitydiff` is on your PATH ({_tilde(bin_dir) if bin_dir else 'found'})")
+    elif bin_dir is not None:
+        warn(f"{_tilde(bin_dir)} is not on your PATH")
+        uv = shutil.which("uv")
+        if uv and interactive and _confirm(
+            "Add it to your shell config (runs 'uv tool update-shell')?", False, style, assume_yes, interactive, ask
+        ):
+            subprocess.run([uv, "tool", "update-shell"], check=False)
+            info("open a new terminal for it to take effect")
+        else:
+            info(f'add this to your shell rc:  export PATH="{bin_dir}:$PATH"')
+    else:
+        info("could not tell where the realitydiff command lives; that is fine if it already runs")
+
+    try:
+        marker = setup_marker()
+        marker.parent.mkdir(parents=True, exist_ok=True)
+        marker.write_text(f"{__version__}\n", encoding="utf-8")
+    except OSError:
+        pass
+
+    say()
+    say(f"{style.green}{style.bold}Reality Diff is set up.{style.reset}")
+    say()
+    say("  Next:")
+    say(f"    {style.bold}realitydiff serve --host 127.0.0.1{style.reset}")
+    say(f"    {style.dim}then open http://127.0.0.1:8000{style.reset}")
+    say(f'    {style.bold}realitydiff open "Apple will replace Siri with an LLM"{style.reset}')
+    say()
+    say(f"  {style.dim}Uninstall: pipx uninstall realitydiff  |  uv tool uninstall realitydiff  |  pip uninstall realitydiff{style.reset}")
+    return 0

realitydiff-0.4.1/tests/test_pypi_publish_workflow.py

@@ -0,0 +1,36 @@
+import re
+from pathlib import Path
+
+WORKFLOWS = Path(__file__).resolve().parents[1] / ".github" / "workflows"
+PUBLISH = WORKFLOWS / "pypi-publish.yml"
+
+PINNED_ACTIONS = {
+    "actions/checkout": "3d3c42e5aac5ba805825da76410c181273ba90b1",
+    "astral-sh/setup-uv": "07a047e608db84b3d8c06cd9a7c7dcc9c355c18e",
+    "actions/upload-artifact": "cf430e030ddbb5b0abf93d22962f4752f3646cd9",
+    "actions/download-artifact": "9000827ccba6bdab643e8b6fd33ac0654aef8333",
+    "oven-sh/setup-bun": "0c5077e51419868618aeaa5fe8019c62421857d6",
+    "pypa/gh-action-pypi-publish": "7245906fb61fa33a13554f9d5fb856fe61758086",
+}
+
+
+def test_pypi_publish_workflow_uses_pypi_environment():
+    text = PUBLISH.read_text()
+    assert "name: pypi" in text
+    assert "https://pypi.org/p/realitydiff" in text
+
+
+def test_pypi_publish_runs_tests_and_checks_before_publish():
+    text = PUBLISH.read_text()
+    assert "needs: test" in text
+    assert "needs: build" in text
+    assert "pytest" in text
+    assert "does not match pyproject version" in text
+    assert "Check package contents" in text
+
+
+def test_all_workflow_actions_are_pinned_to_commit_shas():
+    for workflow in WORKFLOWS.glob("*.yml"):
+        for action, ref in re.findall(r"uses:\s*([\w./-]+)@(\S+)", workflow.read_text()):
+            assert re.fullmatch(r"[0-9a-f]{40}", ref), f"{workflow.name}: {action}@{ref} is not a commit SHA"
+            assert PINNED_ACTIONS.get(action) == ref, f"{workflow.name}: unexpected pin for {action}"

realitydiff-0.4.1/tests/test_setup.py

@@ -0,0 +1,141 @@
+import io
+import os
+import stat
+
+import pytest
+
+from realitydiff import cli, config, setup
+
+
+@pytest.fixture(autouse=True)
+def isolated(tmp_path, monkeypatch):
+    monkeypatch.setenv("REALITYDIFF_CONFIG", str(tmp_path / "cfg" / "env"))
+    monkeypatch.delenv("XAI_API_KEY", raising=False)
+    monkeypatch.setenv("NO_COLOR", "1")
+    return tmp_path
+
+
+def run(**kw):
+    out = io.StringIO()
+    code = setup.run_setup(out=out, **kw)
+    return code, out.getvalue()
+
+
+def test_saves_key_with_600_and_never_prints_it(isolated):
+    code, text = run(
+        interactive=True,
+        ask=lambda _p: "y",
+        ask_secret=lambda _p: "xai-abc_123.DEF",
+    )
+    assert code == 0
+    cfg = isolated / "cfg" / "env"
+    assert "XAI_API_KEY=xai-abc_123.DEF" in cfg.read_text()
+    assert stat.S_IMODE(cfg.stat().st_mode) == 0o600
+    assert "xai-abc_123" not in text
+    assert "realitydiff serve" in text
+    assert config.setup_marker().exists()
+
+
+def test_declining_key_still_finishes_and_marks_done(isolated):
+    code, text = run(interactive=True, ask=lambda _p: "n", ask_secret=lambda _p: pytest.fail("asked"))
+    assert code == 0
+    assert not (isolated / "cfg" / "env").exists()
+    assert "skipped" in text
+    assert config.setup_marker().exists()
+
+
+def test_yes_mode_never_prompts(isolated):
+    code, text = run(assume_yes=True, ask=lambda _p: pytest.fail("prompted"), ask_secret=lambda _p: pytest.fail("prompted"))
+    assert code == 0
+    assert "non-interactive" in text
+
+
+def test_no_key_flag_skips(isolated):
+    _, text = run(interactive=True, skip_key=True, ask=lambda _p: pytest.fail("prompted"))
+    assert "skipped (--no-key)" in text
+
+
+def test_rejects_key_with_bad_characters(isolated):
+    _, text = run(interactive=True, ask=lambda _p: "y", ask_secret=lambda _p: 'bad key"')
+    assert "not saved" in text
+    assert not (isolated / "cfg" / "env").exists()
+
+
+def test_set_config_keeps_other_lines(isolated):
+    path = isolated / "cfg" / "env"
+    config.set_config("REALITYDIFF_DB", "/x.sqlite", path)
+    config.set_config("XAI_API_KEY", "one", path)
+    config.set_config("XAI_API_KEY", "two", path)
+    lines = path.read_text().splitlines()
+    assert "REALITYDIFF_DB=/x.sqlite" in lines
+    assert lines.count("XAI_API_KEY=two") == 1
+    assert "XAI_API_KEY=one" not in lines
+
+
+def test_needs_first_run_only_on_a_fresh_terminal(isolated, monkeypatch):
+    monkeypatch.setattr(setup, "is_interactive", lambda: True)
+    assert setup.needs_first_run()
+    config.set_config("XAI_API_KEY", "k", isolated / "cfg" / "env")
+    assert not setup.needs_first_run()
+    monkeypatch.setattr(setup, "is_interactive", lambda: False)
+    (isolated / "cfg" / "env").unlink()
+    assert not setup.needs_first_run()
+
+
+def test_serve_without_key_prints_a_clean_error_not_a_traceback(isolated, monkeypatch, capsys):
+    monkeypatch.setattr(setup, "is_interactive", lambda: False)
+    assert cli.main(["serve"]) == 2
+    err = capsys.readouterr().err
+    assert "XAI_API_KEY is not set" in err
+    assert "realitydiff setup" in err
+    assert "Traceback" not in err
+
+
+def test_bare_command_runs_setup_first_time_then_help(isolated, monkeypatch, capsys):
+    monkeypatch.setattr(cli, "needs_first_run", lambda: True)
+    called = []
+    monkeypatch.setattr(cli, "run_setup", lambda **kw: called.append(1) or 0)
+    assert cli.main([]) == 0 and called
+    monkeypatch.setattr(cli, "needs_first_run", lambda: False)
+    assert cli.main([]) == 0
+    assert "usage: realitydiff" in capsys.readouterr().out
+
+
+def test_serve_binds_to_localhost_by_default():
+    import argparse
+
+    seen = {}
+    import uvicorn
+
+    parser_calls = {}
+
+    def fake_run(app, host, port, **kw):
+        parser_calls["host"] = host
+
+    import pytest as _p
+
+    with _p.MonkeyPatch.context() as mp:
+        mp.setattr(uvicorn, "run", fake_run)
+        mp.setenv("XAI_API_KEY", "k")
+        cli.main(["serve"])
+    assert parser_calls["host"] == "127.0.0.1"
+
+
+def test_set_config_leaves_no_temp_file_when_write_fails(isolated, monkeypatch):
+    path = isolated / "cfg" / "env"
+
+    def boom(*a, **k):
+        raise OSError("disk full")
+
+    monkeypatch.setattr(os, "replace", boom)
+    with pytest.raises(OSError):
+        config.set_config("XAI_API_KEY", "secret", path)
+    assert not [p for p in path.parent.iterdir() if ".tmp" in p.name]
+
+
+def test_env_key_offer_defaults_to_no(isolated, monkeypatch):
+    monkeypatch.setenv("XAI_API_KEY", "xai-fromenv")
+    answers = []
+    code, _ = run(interactive=True, ask=lambda _p: answers.append(_p) or "", ask_secret=lambda _p: "")
+    assert code == 0
+    assert not (isolated / "cfg" / "env").exists()

{realitydiff-0.4.0 → realitydiff-0.4.1}/uv.lock

@@ -416,7 +416,7 @@ wheels = [
 
 [[package]]
 name = "realitydiff"
-version = "0.4.0"
+version = "0.4.1"
 source = { editable = "." }
 dependencies = [
     { name = "fastapi" },

realitydiff-0.4.0/.github/workflows/pypi-publish.yml

@@ -1,53 +0,0 @@
-name: Publish to PyPI
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  build:
-    name: Build distribution
-    runs-on: ubuntu-latest
-    steps:
-      - name: Check out repository
-        uses: actions/checkout@v7.0.1
-
-      - name: Install uv
-        uses: astral-sh/setup-uv@v10.3.2
-        with:
-          python-version: "3.11"
-
-      - name: Build package
-        run: uv build
-
-      - name: Upload distribution
-        uses: actions/upload-artifact@v7.0.2
-        with:
-          name: python-package-distributions
-          path: dist/
-          if-no-files-found: error
-
-  publish:
-    name: Publish to PyPI
-    needs: build
-    runs-on: ubuntu-latest
-    environment:
-      name: pypi
-      url: https://pypi.org/p/realitydiff
-    permissions:
-      id-token: write
-      attestations: write
-      contents: read
-      actions: read
-    steps:
-      - name: Download distribution
-        uses: actions/download-artifact@v8.0.2
-        with:
-          name: python-package-distributions
-          path: dist/
-
-      - name: Publish package distributions to PyPI
-        uses: pypa/gh-action-pypi-publish@v1.14.3

realitydiff-0.4.0/PKG-INFO

@@ -1,115 +0,0 @@
-Metadata-Version: 2.5
-Name: realitydiff
-Version: 0.4.0
-Summary: Git for beliefs — living claims that watch the internet and version confidence.
-License-File: LICENSE
-Requires-Python: >=3.11
-Requires-Dist: fastapi>=0.115.0
-Requires-Dist: httpx>=0.28.0
-Requires-Dist: pydantic>=2.10.0
-Requires-Dist: uvicorn[standard]>=0.34.0
-Provides-Extra: dev
-Requires-Dist: pytest-asyncio>=0.25.0; extra == 'dev'
-Requires-Dist: pytest>=8.3.0; extra == 'dev'
-Description-Content-Type: text/markdown
-
-# Reality Diff
-
-Git for beliefs — a version history of a claim: evidence, confidence, and why that number moved. For people tracking a story that is still unfolding (products, policy, markets) who want a trail, not a vibe.
-
-## Why I built this
-
-News feeds overwrite your memory. Last week’s confidence on a rumor disappears under today’s take. I wanted git-style operations on a belief: commit when evidence actually moves, diff two weeks, blame a confidence jump, browse the claim as of a SHA, or revert a panic. So I built Reality Diff.
-
-## News feed vs this
-
-| | Typical news / search | Reality Diff |
-| --- | --- | --- |
-| Memory | Overwritten | Versioned history per claim |
-| Confidence | Vibes / headlines | Explicit score + reason when it moves |
-| Compare | Manual screenshots | `diff` between commits |
-| Undo | None | `revert` to an earlier belief state |
-
-## Features
-
-**Claims**
-
-- Open a claim (e.g. “Apple is going to replace Siri with an LLM”)
-- Living object: evidence for/against, unknowns, predictions, confidence
-- Commits only when **meaningful** new evidence appears (cosmetic rewrites dropped)
-
-**Git-style ops**
-
-- `commit` · `diff` · `blame` · `revert` · `watch` · `log`
-- Browse the belief as of any SHA
-- Background watch via OS timer (macOS LaunchAgent / Linux systemd / Windows task) or the UI interval picker
-
-**Surfaces**
-
-- Local web UI (`realitydiff serve` → <http://localhost:8000>)
-- CLI for agents and scripts
-- REST API for the same actions
-
-## Install
-
-One line (macOS or Linux, no sudo):
-
-```bash
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh
-```
-
-It installs [uv](https://docs.astral.sh/uv/) into `~/.local/bin` if you don't have it, installs `realitydiff` as an isolated uv tool, and can save your `XAI_API_KEY` to `~/.config/realitydiff/env` (permissions 600). It never uses sudo and only touches your shell rc if you say yes.
-
-```bash
-# options go after `sh -s --`
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --yes          # no prompts
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --ref <tag-or-commit>
-curl -fsSL https://raw.githubusercontent.com/kavin0x/RealityDiff/main/install.sh | sh -s -- --uninstall
-```
-
-Prefer to read it first? Download `install.sh`, look it over, then run `sh install.sh --help`.
-
-Or install by hand:
-
-```bash
-uv tool install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
-# or
-pipx install "realitydiff @ https://github.com/kavin0x/RealityDiff/archive/main.tar.gz"
-```
-
-Then:
-
-```bash
-realitydiff serve --host 127.0.0.1   # open http://127.0.0.1:8000
-```
-
-The installed CLI keeps claims in `~/.local/share/realitydiff/` (set `REALITYDIFF_DB` to change it). Inside a checkout it still uses `data/`.
-
-## Try it (from a checkout)
-
-```bash
-export XAI_API_KEY=...
-uv sync --extra dev
-uv run realitydiff serve
-# open http://localhost:8000
-```
-
-```bash
-uv run realitydiff open "Apple is going to replace Siri with an LLM."
-uv run realitydiff watch <claim_id>
-uv run realitydiff log <claim_id>
-uv run realitydiff diff <claim_id> <sha_a> <sha_b>
-```
-
-```bash
-uv run realitydiff service install --interval 300
-uv run pytest
-```
-
-## Stack
-
-Python 3.11+ · uv · local web UI + REST · xAI Responses API (web + X search) · MIT
-
-## License
-
-[MIT](LICENSE)

realitydiff-0.4.0/tests/test_pypi_publish_workflow.py

@@ -1,19 +0,0 @@
-from pathlib import Path
-
-WORKFLOW = Path(__file__).resolve().parents[1] / ".github" / "workflows" / "pypi-publish.yml"
-
-LATEST_ACTIONS = {
-    "actions/checkout": "v7.0.1",
-    "astral-sh/setup-uv": "v10.3.2",
-    "actions/upload-artifact": "v7.0.2",
-    "actions/download-artifact": "v8.0.2",
-    "pypa/gh-action-pypi-publish": "v1.14.3",
-}
-
-
-def test_pypi_publish_workflow_uses_pypi_environment_and_latest_actions():
-    text = WORKFLOW.read_text()
-    assert "name: pypi" in text
-    assert "https://pypi.org/p/realitydiff" in text
-    for action, version in LATEST_ACTIONS.items():
-        assert f"uses: {action}@{version}" in text