meanwhile-cli 0.1.0__py3-none-any.whl

meanwhile/__init__.py

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

meanwhile/agents.py

@@ -0,0 +1,314 @@
+"""Which agents meanwhile can hook into, and how each one registers hooks.
+
+The busy/idle signal is not Claude-specific: Codex, Cursor and OpenCode expose
+the same two moments under their own names, and the same bash script serves
+all four. Only the registration file and its shape differ, so that is all this
+module knows about.
+"""
+
+from __future__ import annotations
+
+import copy
+import json
+import re
+import shlex
+from dataclasses import dataclass
+
+#: How our entries are recognised inside somebody else's config file. Matching
+#: on the script name rather than on an exact command string is what lets
+#: `merge` replace an entry that points at an older copy of the script.
+MARKER = "meanwhile-state.sh"
+
+SLUG_PATTERN = re.compile(r"^[a-z][a-z-]{0,15}\Z")
+
+
+@dataclass(frozen=True)
+class Agent:
+    slug: str
+    label: str
+    busy_event: str
+    idle_event: str
+    #: Which config shape this agent's file uses: "claude" (a "hooks" map of
+    #: event -> [{"hooks": [{"type": "command", ...}]}], shared with Codex) or
+    #: "cursor" (a versioned "hooks" map of event -> [{"command": ...}]), or
+    #: "opencode" (no config entry at all: a whole JavaScript file of ours,
+    #: see `plugin_source`).
+    shape: str
+    project_relpath: str
+    user_relpath: str
+    supports_user_scope: bool
+
+
+AGENTS: tuple[Agent, ...] = (
+    Agent(
+        slug="claude",
+        label="Claude Code",
+        busy_event="UserPromptSubmit",
+        idle_event="Stop",
+        shape="claude",
+        # Not hooks.json: a standalone (non-plugin) Claude Code registration
+        # lives in a settings file alongside unrelated settings, which is why
+        # the merge only ever touches document["hooks"].
+        #
+        # settings.local.json, not settings.json, for the project scope:
+        # settings.json is the committed file, and the command we register
+        # carries an absolute path to this machine's copy of the script. A
+        # committed registration would make every teammate's Claude Code run a
+        # script that does not exist for them, on every prompt submit and every
+        # Stop. settings.local.json is the gitignored per-user sibling.
+        # Under $HOME there is no such split, and settings.json is personal
+        # already.
+        project_relpath=".claude/settings.local.json",
+        user_relpath=".claude/settings.json",
+        supports_user_scope=True,
+    ),
+    Agent(
+        slug="codex",
+        label="Codex",
+        busy_event="UserPromptSubmit",
+        idle_event="Stop",
+        shape="claude",
+        project_relpath=".codex/hooks.json",
+        user_relpath=".codex/hooks.json",
+        supports_user_scope=True,
+    ),
+    Agent(
+        slug="cursor",
+        label="Cursor",
+        busy_event="beforeSubmitPrompt",
+        idle_event="stop",
+        shape="cursor",
+        project_relpath=".cursor/hooks.json",
+        user_relpath=".cursor/hooks.json",
+        # Cursor runs user-level hooks from ~/.cursor/ rather than from the
+        # project root, and the script keys the state file on its working
+        # directory — so a user-level registration would key the wrong
+        # directory and the pane would simply never wake.
+        supports_user_scope=False,
+    ),
+    Agent(
+        slug="opencode",
+        label="OpenCode",
+        # One event for both moments: OpenCode has no shell hooks, only
+        # plugins, and a plugin hears `session.status` with the new status
+        # inside it.
+        busy_event="session.status",
+        idle_event="session.status",
+        shape="opencode",
+        project_relpath=".opencode/plugins/meanwhile.js",
+        user_relpath=".config/opencode/plugins/meanwhile.js",
+        # Unlike Cursor, a global plugin is still handed the project's own
+        # directory, so a user-level registration keys the right state file.
+        supports_user_scope=True,
+    ),
+)
+
+
+def agent_by_slug(slug: str) -> Agent | None:
+    for agent in AGENTS:
+        if agent.slug == slug:
+            return agent
+    return None
+
+
+def label_for(slug: str | None) -> str | None:
+    agent = agent_by_slug(slug) if slug else None
+    return agent.label if agent else None
+
+
+def command_for(script: str, agent: Agent, status: str) -> str:
+    """The shell command a registration runs.
+
+    `shlex.quote`, not a bare pair of double quotes: the path carries the
+    user's home directory, and a `"`, `$` or backtick in it would close the
+    quoting or be expanded by the shell — a hook pointing at a path that does
+    not exist, which is exactly the silent failure this module exists to avoid.
+    """
+    return f"{shlex.quote(script)} {status} {agent.slug}"
+
+
+_OPENCODE_PLUGIN = """\
+// Written by `meanwhile hooks install --agent __AGENT__`, and removed again by
+// `meanwhile hooks uninstall --agent __AGENT__`. Edits here are overwritten.
+const SCRIPT = __SCRIPT__
+
+export const Meanwhile = async ({ $, client, directory }) => {
+  // A subagent runs in a session of its own, which goes busy and idle while
+  // the session that spawned it is still working. Only a session without a
+  // parent is the one the user is waiting on.
+  const children = new Map()
+  const isChild = async (id) => {
+    if (!children.has(id)) {
+      let child = false
+      try {
+        const found = await client.session.get({ path: { id } })
+        child = Boolean(found?.data?.parentID)
+      } catch {}
+      children.set(id, child)
+    }
+    return children.get(id)
+  }
+
+  return {
+    event: async ({ event }) => {
+      if (event.type !== "session.status") return
+      const status = event.properties.status.type
+      // "retry" is the third one: still working, so nothing to write.
+      if (status !== "busy" && status !== "idle") return
+      if (await isChild(event.properties.sessionID)) return
+      // The script keys the state file on CLAUDE_PROJECT_DIR, then on its
+      // working directory. Set both to the directory OpenCode was started in.
+      await $`${SCRIPT} ${status} __AGENT__`
+        .cwd(directory)
+        .env({ ...process.env, CLAUDE_PROJECT_DIR: directory })
+        .quiet()
+        .nothrow()
+    },
+  }
+}
+"""
+
+
+def plugin_source(script: str, agent: Agent) -> str:
+    """The whole plugin file an "opencode"-shaped agent loads.
+
+    `json.dumps` for the path: a JSON string is a JavaScript string literal,
+    so a quote or backslash in the user's home directory cannot end it early.
+    The shell side needs no quoting of its own — Bun's `$` passes every
+    interpolated value as one argument.
+    """
+    return _OPENCODE_PLUGIN.replace("__SCRIPT__", json.dumps(script)).replace(
+        "__AGENT__", agent.slug
+    )
+
+
+def _entry(command: str, shape: str) -> dict:
+    if shape == "cursor":
+        return {"command": command}
+    return {"hooks": [{"type": "command", "command": command, "timeout": 5}]}
+
+
+def _commands_in(entry: dict) -> list[str]:
+    if "command" in entry:
+        return [entry["command"]]
+    return [h.get("command", "") for h in entry.get("hooks", []) if isinstance(h, dict)]
+
+
+def _is_ours(entry: dict) -> bool:
+    return any(MARKER in command for command in _commands_in(entry))
+
+
+def _filtered_entry(entry: dict, shape: str) -> dict | None:
+    """Filter out our hooks from an entry, returning the filtered entry or None if empty.
+
+    For cursor shape (one command per entry), return the entry or None.
+    For claude/codex shape (array of hooks), filter the inner hooks array and return
+    the entry only if it still has hooks.
+    """
+    if shape == "cursor":
+        # For cursor: entry has {"command": "..."}, drop it if it's ours
+        if _is_ours(entry):
+            return None
+        return entry
+
+    # For claude/codex: entry has {"hooks": [...], possibly "matcher": ...}
+    # Filter the inner hooks array, keeping only those without our marker
+    if "hooks" not in entry or not isinstance(entry["hooks"], list):
+        return entry
+
+    kept_hooks = [
+        h for h in entry["hooks"]
+        if isinstance(h, dict) and MARKER not in h.get("command", "")
+    ]
+
+    if not kept_hooks:
+        return None
+
+    # Reconstruct entry with filtered hooks, preserving other keys like "matcher"
+    filtered = {k: v for k, v in entry.items() if k != "hooks"}
+    filtered["hooks"] = kept_hooks
+    return filtered
+
+
+def _kept_entries(entries, shape: str) -> list:
+    """Everything in `entries` except our own hooks, in order.
+
+    A neighbour this module does not understand — a bare string in the event's
+    array, a number, anything that is not a hook entry — is carried through
+    untouched rather than dropped. The guarantee is "never destroys a foreign
+    hook", and it must not quietly mean "never destroys a well-formed one".
+    """
+    if not isinstance(entries, list):
+        # An event whose value is not an array is malformed for every agent we
+        # know, but it is still somebody's content: keep it as the one entry it
+        # is, so `merge` can append ours beside it instead of over it.
+        entries = [entries]
+    kept = []
+    for entry in entries:
+        if not isinstance(entry, dict):
+            kept.append(entry)
+            continue
+        filtered = _filtered_entry(entry, shape)
+        if filtered is not None:
+            kept.append(filtered)
+    return kept
+
+
+def merge(document: dict, agent: Agent, script: str) -> dict:
+    """Our two entries, folded into a copy of `document`.
+
+    Idempotent, and safe on a file that already holds other tools' hooks:
+    every hook that is not ours is carried through untouched (even if in an
+    entry with ours), and ours are rewritten rather than appended so a changed
+    script path replaces the old registration instead of doubling it.
+    """
+    out = copy.deepcopy(document)
+    if agent.shape == "cursor":
+        out.setdefault("version", 1)
+    hooks = out.setdefault("hooks", {})
+    for status, event in (("busy", agent.busy_event), ("idle", agent.idle_event)):
+        # Filter each entry: for claude/codex, this removes our inner hooks but
+        # keeps the entry if foreign hooks remain; for cursor, drops the entry if it's ours
+        kept = _kept_entries(hooks.get(event, []), agent.shape)
+        hooks[event] = kept + [_entry(command_for(script, agent, status), agent.shape)]
+    return out
+
+
+def unmerge(document: dict, agent: Agent) -> dict:
+    """A copy of `document` with our hooks — and only ours — taken out.
+
+    For claude/codex shape, removes our inner hooks but keeps entries that still
+    have foreign hooks. For cursor shape, removes entire entries that are ours.
+    """
+    out = copy.deepcopy(document)
+    hooks = out.get("hooks")
+    if not isinstance(hooks, dict):
+        return out
+    for event in (agent.busy_event, agent.idle_event):
+        entries = hooks.get(event)
+        if entries is not None and not isinstance(entries, list):
+            # Not a list, so nothing of ours can be in it (merge only ever
+            # writes a list). Leave the stranger exactly as we found it.
+            continue
+        # Filter each entry to remove our hooks, keeping entries if they still have foreign hooks
+        kept = _kept_entries(entries or [], agent.shape)
+        if kept:
+            hooks[event] = kept
+        else:
+            hooks.pop(event, None)
+    if not hooks:
+        out.pop("hooks", None)
+    return out
+
+
+def registered_commands(document: dict, agent: Agent) -> list[str]:
+    """Every command string of ours in `document`, in busy-then-idle order."""
+    found = []
+    hooks = document.get("hooks")
+    if not isinstance(hooks, dict):
+        return found
+    for event in (agent.busy_event, agent.idle_event):
+        for entry in hooks.get(event, []):
+            if isinstance(entry, dict) and _is_ours(entry):
+                found.extend(c for c in _commands_in(entry) if MARKER in c)
+    return found

meanwhile/app.py

@@ -0,0 +1,187 @@
+"""The terminal UI. Renders cards; all rules live in meanwhile.game."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Callable
+
+from textual.app import App, ComposeResult
+from textual.containers import Vertical
+from textual.widgets import Footer, Static
+
+from . import agents, game, scores, strings
+from .pool import Pool, QuizItem
+
+# Lifecycle phases. The pane is opened once and left open: it waits for the
+# agent to start, plays for exactly as long as it is busy, then waits again.
+WAITING = "waiting"
+PLAYING = "playing"
+DONE = "done"
+
+
+class MeanwhileApp(App):
+    CSS_PATH = "app.tcss"
+    TITLE = "meanwhile"
+
+    # Every key the game can ever offer is declared here, statically. Which of
+    # them the footer actually shows is decided per card by `check_action`.
+    BINDINGS = [
+        ("q", "quit", "Quit"),
+        ("space", "next", "Next card"),
+        *[(str(n), f"choose({n})", f"Choice {n}") for n in range(1, 10)],
+    ]
+
+    # The actions `check_action` gates; everything else is always available.
+    CARD_ACTIONS = ("choose",)
+
+    def __init__(
+        self,
+        pool: Pool,
+        repo_dir: Path,
+        status_source: Callable[[], str],
+        banner: str = "",
+        poll_seconds: float = 0.5,
+        language: str = "en",
+        agent_source: Callable[[], str | None] = lambda: None,
+    ) -> None:
+        super().__init__()
+        self.pool = pool
+        self.repo_dir = repo_dir
+        self.status_source = status_source
+        self.banner = banner
+        self.poll_seconds = poll_seconds
+        self.language = language
+        self.agent_source = agent_source
+        self.session = game.start_session(pool)
+        self.phase = WAITING
+        self._last_status = "idle"
+        self._answered = False
+
+    def _agent_name(self) -> str:
+        return agents.label_for(self.agent_source()) or strings.text(self.language, "agent")
+
+    # --- dynamic bindings -------------------------------------------------
+
+    def check_action(self, action: str, parameters: tuple[object, ...]) -> bool | None:
+        """Offer only the keys the card on screen can actually take.
+
+        A three-choice card should not fill a narrow pane's footer with
+        "Choice 4" .. "Choice 9". Returning False is what *removes* a binding:
+        verified on Textual 8.2.8, True shows it, None shows it greyed out,
+        and only False keeps it out of `Screen.active_bindings` — and so out
+        of the Footer — entirely.
+
+        This decides what the footer advertises and what a keypress may reach;
+        the guards in the action handlers stay the last line of defence.
+        """
+        if action not in self.CARD_ACTIONS:
+            return True
+        if self.phase != PLAYING:
+            return False
+        item = game.current(self.session)
+        return isinstance(item, QuizItem) and 1 <= int(parameters[0]) <= len(item.choices)
+
+    def compose(self) -> ComposeResult:
+        # markup=False: card/feedback text comes from an untrusted pool.json
+        # (see pool.py) and from literal "[space] next" hints — neither should
+        # be parsed as Textual console markup.
+        with Vertical():
+            yield Static(self.banner, id="banner", markup=False)
+            yield Static("", id="status", markup=False)
+            yield Static("", id="card", markup=False)
+            yield Static("", id="feedback", markup=False)
+            yield Static("", id="score", markup=False)
+        yield Footer()
+
+    def on_mount(self) -> None:
+        self.query_one("#banner").display = bool(self.banner)
+        self._render()
+        # Poll once up front so a pane opened while the agent is already busy
+        # joins that wait instead of sitting out until the first tick.
+        self._poll_status()
+        self.set_interval(self.poll_seconds, self._poll_status)
+
+    # --- status ---------------------------------------------------------
+
+    def _poll_status(self) -> None:
+        """Drive the lifecycle off the edges of the busy/idle state file."""
+        status = self.status_source()
+        if status == self._last_status:
+            return
+        self._last_status = status
+        if status == "busy":
+            self._start_playing()
+        else:
+            self._finish_playing()
+
+    def _start_playing(self) -> None:
+        self.phase = PLAYING
+        self.session = game.start_session(self.pool)  # re-shuffled: the cards come back
+        self._answered = False
+        self.query_one("#status").update("")
+        self.query_one("#feedback").update("")
+        self._render()
+
+    def _finish_playing(self) -> None:
+        if self.phase != PLAYING:
+            return
+        self.phase = DONE
+        self.refresh_bindings()  # DONE takes no input: the card keys leave the footer
+        self.query_one("#status").update(strings.text(self.language, "done", agent=self._agent_name()))
+        # Exactly once per session: the `phase != PLAYING` guard above is what
+        # guarantees it — the only way back into PLAYING is _start_playing,
+        # which deals a new session.
+        if self.repo_dir is not None and self.session.answered:
+            scores.record_session(self.repo_dir, self.session)
+
+    # --- actions --------------------------------------------------------
+
+    def action_choose(self, number: int) -> None:
+        item = game.current(self.session)
+        if self.phase != PLAYING or self._answered or not isinstance(item, QuizItem):
+            return
+        index = number - 1
+        if not 0 <= index < len(item.choices):
+            return
+        self._resolve(game.answer(self.session, index))
+
+    def action_next(self) -> None:
+        if self.phase != PLAYING or not self._answered:
+            return
+        game.advance(self.session)
+        self._answered = False
+        self.query_one("#feedback").update("")
+        self._render()
+
+    # --- rendering ------------------------------------------------------
+
+    def _resolve(self, verdict: game.Verdict) -> None:
+        self._answered = True
+        mark = strings.text(self.language, "correct" if verdict.correct else "wrong")
+        self.query_one("#feedback").update(f"{mark} — {verdict.explanation}   [space] next")
+        self._render_score()
+
+    def _render(self) -> None:
+        # The card (or the phase) has just changed, so the footer's answer for
+        # `check_action` has too.
+        self.refresh_bindings()
+        card = self.query_one("#card")
+        if self.phase == WAITING:
+            self.query_one("#status").update(strings.text(self.language, "waiting", agent=self._agent_name()))
+            card.update("")
+            self.query_one("#score").update("")
+            return
+
+        item = game.current(self.session)
+        if item is None:
+            card.update(strings.text(self.language, "exhausted"))
+        elif isinstance(item, QuizItem):
+            choices = "\n".join(f"  {n}. {text}" for n, text in enumerate(item.choices, start=1))
+            card.update(f"{item.q}\n\n{choices}\n\n({item.source})")
+        self._render_score()
+
+    def _render_score(self) -> None:
+        self.query_one("#score").update(
+            f"{self.session.correct}/{self.session.answered} correct   "
+            f"streak {self.session.streak} (best {self.session.best_streak})"
+        )

meanwhile/app.tcss

@@ -0,0 +1,6 @@
+Screen { background: $surface; }
+#banner { color: $warning; padding: 0 1; }
+#status { color: $success; padding: 0 1; }
+#card { padding: 1 2; }
+#feedback { padding: 0 2; color: $accent; }
+#score { padding: 0 2; color: $text-muted; }

meanwhile/build_prompt.md

@@ -0,0 +1,73 @@
+Build `.meanwhile/pool.json` for the current repository.
+
+## What to read
+
+Survey the repo to understand what it does and what is distinctive about it:
+
+- data models, schemas, and migrations
+- API routes, serializers, and their validation rules
+- the README, and any docs describing domain concepts
+- `CHANGELOG.md` if present
+- `git log --oneline -50` for recent direction
+
+Prefer the project's own domain terms over generic programming vocabulary. A
+good question could only be answered by someone who has read this repository.
+Write the questions in {language}. Record that language in the pool too, so
+the playing interface follows it.
+
+The language is given as a short language code, not a language name, and the
+pool's `language` field records exactly that code. `tr` and `en` are the two
+the playing interface itself speaks; any other code is still fine — the cards
+get written in that language and the interface stays English.
+
+## What to write
+
+Write `.meanwhile/pool.json` with 30-50 `quiz` items, using exactly this shape:
+
+    {
+      "builtAt": "<today, YYYY-MM-DD>",
+      "headSha": "<output of: git rev-parse --short HEAD>",
+      "repo": "{repo}",
+      "language": "{language}",
+      "items": [
+        {
+          "type": "quiz",
+          "q": "<question about this project's domain or behavior>",
+          "choices": ["<option>", "<option>", "<option>"],
+          "answer": <0-based index of the correct choice>,
+          "why": "<one sentence explaining the answer>",
+          "source": "<repo-relative path the question came from>"
+        }
+      ]
+    }
+
+Rules:
+
+- Never invent code. Every question must be grounded in a file that exists.
+- **Never take a question or an answer from a secret file.**
+  `.meanwhile/pool.json` is committed and shared with the whole team, so
+  anything copied into it is published. Skip `.env` and any `.env.*`,
+  credential/key/token/certificate files (`*.pem`, `*.key`, `id_rsa`,
+  `credentials*`, `secrets*`), fixtures holding real keys, and **any file
+  excluded by `.gitignore`** — check with `git check-ignore -q <path>`
+  before using a file. Draw only on files that are tracked in git.
+- Wrong quiz choices should be plausible to someone who half-remembers the
+  code, not obviously absurd.
+
+## Finish
+
+1. Ensure `.meanwhile/scores.json` is in `.gitignore`; add it if missing.
+2. Run `uvx meanwhile-cli validate --repo .` (during development, from a
+   checkout of this plugin: `uv run meanwhile validate --repo .`) and fix
+   anything it reports.
+3. Tell the user the item count and that `.meanwhile/pool.json` is ready to
+   commit so their team shares the pool.
+4. Tell the user how to play, in {language} — building the pool starts
+   nothing, and no other step says how. Give them the command itself, in a
+   code block they can copy:
+
+       uvx meanwhile-cli
+
+   and say where it goes: a second terminal pane beside this one, opened in
+   this same directory. The pane waits there, deals cards from their next
+   prompt on, and `q` quits it.