meanwhile-cli 0.1.0__py3-none-any.whl

meanwhile/cli.py

@@ -0,0 +1,223 @@
+"""Command line entry point: `meanwhile` plays, `meanwhile validate` checks a pool."""
+
+from __future__ import annotations
+
+import argparse
+import subprocess
+import sys
+from pathlib import Path
+
+from . import repo, state, strings
+from .pool import POOL_RELPATH, PoolError, load_pool
+
+
+def launch_dir(start: str | Path) -> Path:
+    """The directory the pane was launched in.
+
+    This — not the git root — is the state-file key: hooks/meanwhile-state.sh
+    keys on CLAUDE_PROJECT_DIR, which Claude Code sets to the directory the
+    session was started in. Keying the TUI on the git root instead would
+    silently never meet the hook whenever Claude Code is launched below it
+    (a monorepo package, `backend/`, ...).
+    """
+    return Path(start).resolve()
+
+
+def repo_root(start: str | Path) -> Path:
+    """The git root of `start`, or `start` itself when it is not a repo."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"],
+            cwd=str(start),
+            capture_output=True,
+            text=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return Path(start)
+    if result.returncode != 0:
+        return Path(start)
+    return Path(result.stdout.strip())
+
+
+def staleness_banner(
+    repo_dir: str | Path, head_sha: str, language: str = strings.DEFAULT_LANGUAGE
+) -> str:
+    behind = repo.commits_behind(repo_dir, head_sha)
+    if behind is None or behind < repo.STALE_THRESHOLD:
+        return ""
+    return strings.text(language, "stale", behind=behind)
+
+
+def build_prompt(language: str, repo_name: str) -> str:
+    """The packaged build instructions, with `{language}` and `{repo}` filled in.
+
+    Plain `str.replace`, not `str.format`: the file is a worked JSON example
+    full of braces that `.format` would try (and fail) to parse as fields.
+    This is the one copy — `commands/meanwhile-build.md` points at it instead
+    of duplicating it, and `tests/test_plugin_files.py` pins its example to
+    `meanwhile.pool.load_pool`.
+    """
+    source = Path(__file__).with_name("build_prompt.md").read_text(encoding="utf-8")
+    return source.replace("{language}", language).replace("{repo}", repo_name)
+
+
+def validate(repo_dir: str | Path) -> tuple[int, list[str]]:
+    root = Path(repo_dir)
+    try:
+        pool = load_pool(root / POOL_RELPATH)
+    except PoolError as exc:
+        return 1, [str(exc)]
+
+    missing = sorted({item.source for item in pool.items if not (root / item.source).exists()})
+    if missing:
+        return 1, [f"source file does not exist: {path}" for path in missing]
+    return 0, [f"pool is valid: {len(pool.items)} item(s)"]
+
+
+def main(argv: list[str] | None = None) -> int:
+    if argv is None:
+        argv = sys.argv[1:]
+    # `hooks` takes the rest of the line for its own parser, so `meanwhile
+    # hooks install --agent codex` does not have to share flags with `play`.
+    if argv and argv[0] == "hooks":
+        return run_hooks(argv[1:])
+
+    # No prog=: argparse takes it from sys.argv[0], so `meanwhile --help` and
+    # `meanwhile-cli --help` each print the name they were invoked by.
+    parser = argparse.ArgumentParser()
+    parser.add_argument(
+        "command", nargs="?", default="play", choices=["play", "validate", "build-prompt"]
+    )
+    parser.add_argument("--repo", default=".", help="project directory (default: current)")
+    parser.add_argument(
+        "--lang",
+        default=None,
+        # Spells out that this is a code and names the two, because nothing
+        # else on the documented path does: a user who reads "language" and
+        # passes "Turkish" gets an English interface and no complaint.
+        help=(
+            "short language code, e.g. tr or en (default: the pool's own). "
+            "tr and en are the two the interface speaks; any other code leaves "
+            "the interface in English, and on build-prompt still writes the "
+            "cards in it"
+        ),
+    )
+    args = parser.parse_args(argv)
+
+    launch = launch_dir(args.repo)  # keys the busy/idle state file
+    root = repo_root(launch)  # holds .meanwhile/pool.json and scores.json
+
+    if args.command == "build-prompt":
+        # No pool exists yet — the point of this command is to build one —
+        # so there is no pool.language to fall back to, unlike `play`.
+        language = args.lang or strings.DEFAULT_LANGUAGE
+        print(build_prompt(language=language, repo_name=root.name), end="")
+        return 0
+
+    if args.command == "validate":
+        code, messages = validate(root)
+        for message in messages:
+            print(message)
+        return code
+
+    try:
+        pool = load_pool(root / POOL_RELPATH)
+    except PoolError as exc:
+        # Both routes, not just the slash command: a Codex or Cursor user who
+        # opens the pane before building a pool is the likeliest first run on
+        # the new paths, and /meanwhile-build does not exist for them.
+        print(
+            f"{exc}\n\nRun /meanwhile-build inside Claude Code, or "
+            "`meanwhile build-prompt` with any other agent, to create one."
+        )
+        return 1
+
+    language = args.lang or pool.language
+    return _run_app(
+        pool=pool,
+        repo_dir=root,
+        status_source=lambda: state.read_state(launch)["status"],
+        banner=staleness_banner(root, pool.head_sha, language=language),
+        language=language,
+        agent_source=lambda: state.read_state(launch)["agent"],
+    )
+
+
+def _run_app(**kwargs) -> int:
+    from .app import MeanwhileApp  # imported late so `validate` needs no terminal
+
+    MeanwhileApp(**kwargs).run()
+    return 0
+
+
+def run_hooks(argv: list[str]) -> int:
+    """`meanwhile hooks install|status|uninstall` — register the busy/idle hooks.
+
+    Claude Code and Codex users can get these from the plugin; this is for
+    Cursor, OpenCode, and either of those two without it.
+    """
+    from . import hooks_cli
+    from .agents import AGENTS, agent_by_slug
+
+    parser = argparse.ArgumentParser(
+        prog=f"{Path(sys.argv[0]).name} hooks",
+        description="register meanwhile's busy/idle hooks with a coding agent",
+    )
+    parser.add_argument("action", choices=["install", "status", "uninstall"])
+    parser.add_argument(
+        "--agent",
+        default="auto",
+        choices=[agent.slug for agent in AGENTS] + ["auto"],
+        help="which agent (default: auto — every agent already configured here)",
+    )
+    parser.add_argument(
+        "--user",
+        action="store_true",
+        help="register for every project of this user, not just this one",
+    )
+    parser.add_argument("--repo", default=".", help="project directory (default: current)")
+    args = parser.parse_args(argv)
+
+    home = Path.home()
+    repo_dir = Path(args.repo).resolve()
+
+    if args.action == "status":
+        for line in hooks_cli.status(repo=repo_dir, home=home):
+            print(line)
+        return 0
+
+    if args.agent == "auto":
+        targets = []
+        for agent in AGENTS:
+            # An agent's own directory is the only evidence that it is in use
+            # here; `auto` never conjures one up from nothing.
+            if not hooks_cli.agent_dir(agent, repo_dir, home, args.user).is_dir():
+                continue
+            if args.user and not agent.supports_user_scope:
+                print(f"{agent.label}: skipped, it cannot be hooked at the user level")
+                continue
+            targets.append(agent)
+        if not targets:
+            scope = "under your home directory" if args.user else f"in {repo_dir}"
+            print(
+                f"no agent config directory found {scope} — name one with --agent",
+                file=sys.stderr,
+            )
+            return 1
+    else:
+        targets = [agent_by_slug(args.agent)]
+
+    act = hooks_cli.install if args.action == "install" else hooks_cli.uninstall
+    failed = False
+    for agent in targets:
+        try:
+            print(act(agent, repo=repo_dir, home=home, user=args.user))
+        except (hooks_cli.HooksError, OSError) as exc:
+            # OSError too: a read-only .codex/hooks.json is a thing that
+            # happens, and it is a message, not a traceback out of main().
+            # Not prefixed with the label: every HooksError already names the
+            # agent, by label or by the path it refused to touch.
+            print(str(exc), file=sys.stderr)
+            failed = True
+    return 1 if failed else 0

meanwhile/game.py

@@ -0,0 +1,70 @@
+"""Scoring rules. No I/O here — the TUI renders what these functions return."""
+
+from __future__ import annotations
+
+import random
+from dataclasses import dataclass, field
+
+from .pool import Pool
+
+
+class GameError(Exception):
+    """The caller drove the session into an impossible state."""
+
+
+@dataclass(frozen=True)
+class Verdict:
+    correct: bool
+    explanation: str
+
+
+@dataclass
+class Session:
+    items: list
+    index: int = 0
+    correct: int = 0
+    answered: int = 0
+    streak: int = 0
+    best_streak: int = 0
+    # Bookkeeping, not part of the session's identity: keep it out of
+    # __init__, __repr__ and __eq__.
+    _answered_index: int = field(default=-1, init=False, repr=False, compare=False)
+
+
+def start_session(pool: Pool, rng: random.Random | None = None) -> Session:
+    items = list(pool.items)
+    (rng or random.Random()).shuffle(items)
+    return Session(items=items)
+
+
+def finished(session: Session) -> bool:
+    return session.index >= len(session.items)
+
+
+def current(session: Session):
+    if finished(session):
+        return None
+    return session.items[session.index]
+
+
+def advance(session: Session) -> None:
+    session.index += 1
+
+
+def answer(session: Session, response: int) -> Verdict:
+    item = current(session)
+    if item is None:
+        raise GameError("session is finished")
+    if session._answered_index == session.index:
+        raise GameError("this item has already been answered; call advance() first")
+
+    session._answered_index = session.index
+    session.answered += 1
+    correct = response == item.answer
+    if correct:
+        session.correct += 1
+        session.streak += 1
+        session.best_streak = max(session.best_streak, session.streak)
+    else:
+        session.streak = 0
+    return Verdict(correct=correct, explanation=item.why)

meanwhile/hooks_cli.py

@@ -0,0 +1,308 @@
+"""Register meanwhile's busy/idle hooks with an agent, without its plugin system.
+
+Claude Code and Codex can get these two hooks from the plugin; Cursor has no
+plugin mechanism, and OpenCode's is a JavaScript file somebody has to put in
+place, so the registration has to be written by hand. This module does it.
+
+Every failure mode here is silent: a registration written to the wrong path,
+naming the wrong event, or pointing at a script that has moved raises nothing
+at all — the pane simply never wakes, and nothing anywhere says why. So this
+module refuses rather than guesses. A config file it cannot parse is an error
+instead of something to overwrite, and a scope an agent cannot honour is an
+error carrying its reason.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from .agents import AGENTS, MARKER, Agent, merge, plugin_source, registered_commands, unmerge
+
+SCRIPT_NAME = "meanwhile-state.sh"
+
+#: Agents whose project-scope config file has no gitignored sibling to move to,
+#: so the registration we write there is one the user is likely to commit.
+#: Claude Code is absent on purpose: its project registration goes to
+#: `.claude/settings.local.json`, which is the gitignored one already.
+_COMMITTED_PROJECT_CONFIG = ("codex", "cursor", "opencode")
+
+#: What `uninstall` reads as "the file held nothing but ours": an empty
+#: document, or the bare "version" key `merge` adds for Cursor.
+_EMPTY_DOCUMENTS = ({}, {"version": 1})
+
+#: Appended to an agent's "not installed" line. `status` reads the
+#: registration files this module writes and nothing else, so a Claude Code
+#: plugin install — which registers the same two hooks through its own
+#: hooks.json — is invisible here. Detecting it would mean reading Claude
+#: Code's internal install state, so the line says what it can and cannot see
+#: instead, so nobody reads `not installed` and adds a redundant second copy.
+_NOT_INSTALLED_NOTES = {"claude": " (the plugin registers its own hooks separately)"}
+
+
+class HooksError(Exception):
+    """A registration that could not work, refused with its reason."""
+
+
+def packaged_script() -> Path:
+    """The copy of the hook script that ships inside the wheel.
+
+    A second copy lives at `hooks/meanwhile-state.sh` for the plugin, which can
+    only name its own file through ${CLAUDE_PLUGIN_ROOT}. The two are held
+    byte-identical by a test.
+    """
+    return Path(__file__).resolve().parent / SCRIPT_NAME
+
+
+def installed_script(home: str | Path | None = None) -> Path:
+    """Where the registrations point — a copy under the user's home.
+
+    Never the packaged file itself: under `uvx` the package lives in a cache
+    directory that can be reclaimed at any time, and a registration pointing
+    there would quietly stop writing the state file.
+    """
+    base = Path.home() if home is None else Path(home)
+    return base / ".meanwhile" / SCRIPT_NAME
+
+
+#: The default of `installed_script`, spelled out for callers that only need
+#: the one path (each function takes `home` so tests can point it elsewhere).
+INSTALLED_SCRIPT = installed_script()
+
+
+def install_script(dest: str | Path) -> Path:
+    """Copy the packaged script to `dest`, executable. Returns `dest`."""
+    dest = Path(dest)
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(packaged_script(), dest)
+    dest.chmod(0o755)
+    return dest
+
+
+def config_path(agent: Agent, repo: str | Path, home: str | Path, user: bool = False) -> Path:
+    """The config file this agent reads its hooks from, in the given scope."""
+    if user:
+        return Path(home) / agent.user_relpath
+    return Path(repo) / agent.project_relpath
+
+
+def agent_dir(agent: Agent, repo: str | Path, home: str | Path, user: bool = False) -> Path:
+    """The directory whose existence says this agent is in use in that scope.
+
+    Normally the one the config file sits in. OpenCode's plugin file sits one
+    level further down, in a `plugins/` directory most projects do not have
+    until something is installed into it.
+    """
+    parent = config_path(agent, repo, home, user).parent
+    return parent.parent if agent.shape == "opencode" else parent
+
+
+def _is_plugin_file(agent: Agent) -> bool:
+    """Whether the registration is a whole file of ours rather than entries
+    merged into somebody else's JSON."""
+    return agent.shape == "opencode"
+
+
+def _read_plugin(path: Path) -> str | None:
+    """Our plugin file's text, `None` when there is no file.
+
+    A file at that path we did not write is a `HooksError`, for the same
+    reason an unparseable config is: it is somebody's own plugin, and writing
+    or deleting over it would take their work with it.
+    """
+    if not path.exists():
+        return None
+    try:
+        text = path.read_text(encoding="utf-8")
+    except (OSError, ValueError) as exc:
+        raise HooksError(f"{path} cannot be read ({exc}); fix it and run this again") from exc
+    if MARKER not in text:
+        raise HooksError(f"{path} exists and was not written by meanwhile; move it and run this again")
+    return text
+
+
+def _write_text(path: Path, text: str) -> None:
+    """Write `text` to `path`, atomically. See `_write_document`."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.meanwhile.tmp")
+    try:
+        tmp.write_text(text, encoding="utf-8")
+        os.replace(tmp, path)
+    except OSError:
+        tmp.unlink(missing_ok=True)
+        raise
+
+
+def _read_document(path: Path) -> dict:
+    """The JSON object at `path`, `{}` when there is no file.
+
+    A file we cannot parse is a `HooksError`: it is somebody's hand-edited
+    config, and overwriting it with ours would take their settings with it.
+    """
+    if not path.exists():
+        return {}
+    try:
+        text = path.read_text(encoding="utf-8")
+        if not text.strip():
+            # A zero-byte (or whitespace-only) file has nothing to lose, so
+            # leniency here costs none of the safety the strictness buys.
+            return {}
+        document = json.loads(text)
+    except (OSError, ValueError) as exc:
+        raise HooksError(f"{path} is not valid JSON ({exc}); fix it and run this again") from exc
+    if not isinstance(document, dict):
+        raise HooksError(f"{path} does not hold a JSON object; fix it and run this again")
+    return document
+
+
+def _write_document(path: Path, document: dict) -> None:
+    """Write `document` to `path`, atomically.
+
+    `write_text` truncates before it writes, so a crash or a full disk between
+    the two would destroy somebody's settings file — from the one function
+    whose whole job is not losing a config. Temp file beside the target (same
+    filesystem, so `os.replace` is a rename) and then one atomic swap, exactly
+    as the hook script next door writes the state file.
+    """
+    _write_text(path, json.dumps(document, indent=2) + "\n")
+
+
+def _tracked_by_git(path: Path) -> bool:
+    """Whether `path` is in a git index. Advice only — never a reason to fail.
+
+    Any trouble running git at all (not installed, not a repo, a timeout) reads
+    as "not tracked": the worst outcome of getting this wrong is a note the
+    user does not see.
+    """
+    try:
+        result = subprocess.run(
+            ["git", "ls-files", "--error-unmatch", "--", path.name],
+            cwd=str(path.parent),
+            capture_output=True,
+            timeout=5,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return False
+    return result.returncode == 0
+
+
+def _tracked_note(path: Path, agent: Agent, user: bool) -> str:
+    """The warning for a registration that is about to be committed.
+
+    The command we write carries an absolute path to this machine's copy of the
+    script. Codex and Cursor have no gitignored sibling to move to, and their
+    hooks.json is commonly committed, so all we can do is say so.
+
+    Already tracked is the rare case. The dominant one is the opposite: this
+    very install creates `.codex/hooks.json` from nothing and the user commits
+    it afterwards, when git tracks nothing yet — so the note goes out for every
+    project-scope install of theirs, tracked or not, only worded differently.
+    """
+    if _tracked_by_git(path):
+        return (
+            f"\nnote: {path} is tracked by git, and the path recorded in it is specific to "
+            "this machine.\n      Teammates who commit it will run a script that does not "
+            "exist for them."
+        )
+    if user or agent.slug not in _COMMITTED_PROJECT_CONFIG:
+        return ""
+    return (
+        f"\nnote: the path recorded in {path} is specific to this machine.\n"
+        "      Commit it and teammates will run a script that does not exist for them."
+    )
+
+
+def install(agent: Agent, repo: str | Path, home: str | Path, user: bool = False) -> str:
+    """Register our two hooks for `agent`, and report what was written."""
+    if user and not agent.supports_user_scope:
+        raise HooksError(
+            f"{agent.label} runs user-level hooks from ~/{Path(agent.user_relpath).parts[0]}/, "
+            "but the script keys the state file on its working directory — a user-level "
+            "registration would key the wrong directory and never wake the pane. "
+            f"Install it per project instead: meanwhile hooks install --agent {agent.slug}"
+        )
+    # Read and validate before copying anything: a refused install must leave
+    # no trace, and the script copy is a write like any other.
+    path = config_path(agent, repo, home, user)
+    if _is_plugin_file(agent):
+        _read_plugin(path)
+        script = install_script(installed_script(home))
+        _write_text(path, plugin_source(str(script), agent))
+        return f"{agent.label}: plugin written to {path}{_tracked_note(path, agent, user)}"
+    document = _read_document(path)
+    script = install_script(installed_script(home))
+    _write_document(path, merge(document, agent, str(script)))
+    return f"{agent.label}: hooks registered in {path}{_tracked_note(path, agent, user)}"
+
+
+def uninstall(agent: Agent, repo: str | Path, home: str | Path, user: bool = False) -> str:
+    """Take our two hooks — and only ours — back out, and report what changed."""
+    path = config_path(agent, repo, home, user)
+    if not path.exists():
+        return f"{agent.label}: nothing to remove, {path} does not exist"
+    if _is_plugin_file(agent):
+        _read_plugin(path)
+        path.unlink()
+        return f"{agent.label}: plugin removed, {path} deleted"
+    remaining = unmerge(_read_document(path), agent)
+    if remaining in _EMPTY_DOCUMENTS:
+        # The file held nothing but our registration, so leave no husk behind.
+        path.unlink()
+        return f"{agent.label}: hooks removed, {path} deleted"
+    _write_document(path, remaining)
+    return f"{agent.label}: hooks removed from {path}"
+
+
+def _script_note(home: str | Path) -> str:
+    """How the installed copy of the script compares to the packaged one.
+
+    A registration keeps working after an upgrade only because it points at
+    this copy — which also means an upgrade cannot refresh it. Nothing else
+    would report the difference.
+    """
+    script = installed_script(home)
+    if not script.exists():
+        return " (stale: the script copy is missing — reinstall)"
+    if script.read_bytes() != packaged_script().read_bytes():
+        return " (stale: script copy differs from the packaged one — reinstall)"
+    return ""
+
+
+def status(repo: str | Path, home: str | Path) -> list[str]:
+    """One line per agent: whether our hooks are registered, and where."""
+    note = _script_note(home)
+    lines = []
+    for agent in AGENTS:
+        scopes, unreadable = [], []
+        for scope, user in (("project", False), ("user", True)):
+            if user and not agent.supports_user_scope:
+                continue
+            path = config_path(agent, repo, home, user)
+            try:
+                if _is_plugin_file(agent):
+                    registered = _read_plugin(path) is not None
+                else:
+                    registered = bool(registered_commands(_read_document(path), agent))
+            except HooksError:
+                unreadable.append(str(path))
+                continue
+            if registered:
+                scopes.append(scope)
+        if scopes:
+            line = f"{agent.slug} ({agent.label}): installed ({', '.join(scopes)}){note}"
+            if unreadable:
+                line += f", unreadable config: {', '.join(unreadable)}"
+        elif unreadable:
+            # Not "not installed": we do not know, and saying so would be a
+            # guess in the one direction the user cannot check.
+            line = f"{agent.slug} ({agent.label}): unreadable config: {', '.join(unreadable)}"
+        else:
+            line = (
+                f"{agent.slug} ({agent.label}): not installed"
+                f"{_NOT_INSTALLED_NOTES.get(agent.slug, '')}"
+            )
+        lines.append(line)
+    return lines