meanwhile-cli 0.1.1__tar.gz → 0.1.2__tar.gz

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/.claude-plugin/marketplace.json

@@ -8,7 +8,7 @@
     {
       "name": "meanwhile",
       "source": ".",
-      "version": "0.1.1",
+      "version": "0.1.2",
       "description": "Play a quiz about your own repository while Claude Code is working, so your context stays loaded for the diff review that follows."
     }
   ]

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "meanwhile",
   "description": "Play a quiz about your own repository while Claude Code is working, so your context stays loaded for the diff review that follows.",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "author": {
     "name": "Ismail Bayram"
   },

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meanwhile-cli
-Version: 0.1.1
+Version: 0.1.2
 Summary: Play a quiz about your own repository while your coding agent works
 Project-URL: Homepage, https://github.com/ismailbayram/meanwhile
 Project-URL: Repository, https://github.com/ismailbayram/meanwhile
@@ -136,10 +136,17 @@ looks like this:
 - **Language:** `--lang` takes a language code, not a name. `tr` and `en` are
   the two the interface speaks; any other code (`de`, `fr`, …) writes the
   questions in that language and keeps the interface in English.
+- **Adding questions:** run the build step again. When a pool already
+  exists it keeps every question and adds 30 new ones. Ask your agent for
+  "a fresh pool" if you want to replace it instead.
 - **Refreshing:** when the repository is about 50 commits past the pool, the
   pane shows a banner. Run the build step again and commit the new file.
   Nothing is regenerated automatically.
-- Scores are kept in `.meanwhile/scores.json`, which is gitignored.
+- **Repeats:** within a round no question repeats. Across rounds, questions
+  you have not answered yet come first; once you have answered them all, it
+  starts over.
+- Scores and the answered-question list are kept in
+  `.meanwhile/scores.json`, which is gitignored.
 
 ## Commands
 

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/README.md

@@ -121,10 +121,17 @@ looks like this:
 - **Language:** `--lang` takes a language code, not a name. `tr` and `en` are
   the two the interface speaks; any other code (`de`, `fr`, …) writes the
   questions in that language and keeps the interface in English.
+- **Adding questions:** run the build step again. When a pool already
+  exists it keeps every question and adds 30 new ones. Ask your agent for
+  "a fresh pool" if you want to replace it instead.
 - **Refreshing:** when the repository is about 50 commits past the pool, the
   pane shows a banner. Run the build step again and commit the new file.
   Nothing is regenerated automatically.
-- Scores are kept in `.meanwhile/scores.json`, which is gitignored.
+- **Repeats:** within a round no question repeats. Across rounds, questions
+  you have not answered yet come first; once you have answered them all, it
+  starts over.
+- Scores and the answered-question list are kept in
+  `.meanwhile/scores.json`, which is gitignored.
 
 ## Commands
 

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "meanwhile",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Play a quiz about your own repository while Claude Code is working, so your context stays loaded for the diff review that follows.",
   "author": {
     "name": "Ismail Bayram"

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "meanwhile-cli"
-version = "0.1.1"
+version = "0.1.2"
 description = "Play a quiz about your own repository while your coding agent works"
 readme = "README.md"
 requires-python = ">=3.10"

meanwhile_cli-0.1.2/src/meanwhile/__init__.py

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

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/src/meanwhile/app.py

@@ -52,11 +52,16 @@ class MeanwhileApp(App):
         self.poll_seconds = poll_seconds
         self.language = language
         self.agent_source = agent_source
-        self.session = game.start_session(pool)
+        self.session = self._deal()
         self.phase = PLAYING
         self._last_status = "idle"
         self._answered = False
 
+    def _deal(self) -> game.Session:
+        """A fresh round, questions this player has not answered yet first."""
+        seen = scores.load_seen(self.repo_dir) if self.repo_dir is not None else set()
+        return game.start_session(self.pool, seen=seen)
+
     def _agent_name(self) -> str:
         return agents.label_for(self.agent_source()) or strings.text(self.language, "agent")
 
@@ -120,7 +125,7 @@ class MeanwhileApp(App):
             # card on screen rather than reshuffling under the player.
             return
         self.phase = PLAYING
-        self.session = game.start_session(self.pool)  # re-shuffled: the cards come back
+        self.session = self._deal()  # re-shuffled: the cards come back
         self._answered = False
         self.query_one("#status").update("")
         self.query_one("#feedback").update("")
@@ -158,6 +163,10 @@ class MeanwhileApp(App):
         if not 0 <= index < len(item.choices):
             return
         self._resolve(game.answer(self.session, index))
+        if self.repo_dir is not None:
+            scores.mark_seen(
+                self.repo_dir, game.item_key(item), {game.item_key(i) for i in self.pool.items}
+            )
 
     def action_next(self) -> None:
         if self.phase != PLAYING:
@@ -166,7 +175,7 @@ class MeanwhileApp(App):
             # Out of cards. Without hooks no busy edge will ever come to deal
             # another round, so `space` does it: bank this one, start afresh.
             self._record()
-            self.session = game.start_session(self.pool)
+            self.session = self._deal()
             self._answered = False
             self.query_one("#feedback").update("")
             self._render()

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/src/meanwhile/build_prompt.md

@@ -20,9 +20,26 @@ 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.
 
+## Extending an existing pool
+
+If `.meanwhile/pool.json` already exists, extend it rather than replacing it,
+unless the user asked for a fresh pool:
+
+- Keep every existing item exactly as it is — players' progress is keyed on
+  the question text, so a reworded question counts as a new one. Only drop
+  an item whose `source` file no longer exists.
+- Add 30 new items. None may ask what an existing item already asks; read
+  the existing questions first, and look for parts of the repository they
+  do not cover yet.
+- Keep the pool's own `language` — it wins over the language named above,
+  which is only a default — unless the user asked for another one.
+- Set `builtAt` and `headSha` to today and the current commit.
+
 ## What to write
 
-Write `.meanwhile/pool.json` with 30-50 `quiz` items, using exactly this shape:
+For a new pool, write `.meanwhile/pool.json` with 30-50 `quiz` items; when
+extending, keep the same envelope and append to `items`. Use exactly this
+shape:
 
     {
       "builtAt": "<today, YYYY-MM-DD>",
@@ -60,7 +77,8 @@ Rules:
 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
+3. Tell the user the item count — when extending, how many were added and
+   how many there are now — 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

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/src/meanwhile/game.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import hashlib
 import random
 from dataclasses import dataclass, field
 
@@ -31,10 +32,26 @@ class Session:
     _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 item_key(item) -> str:
+    """A stable name for a question, for remembering it was answered.
+
+    The question text, not the item's position: a rebuilt or extended pool
+    reorders items, and a question that survives a rebuild word for word is
+    the same question to the player.
+    """
+    return hashlib.sha256(item.q.encode("utf-8")).hexdigest()[:16]
+
+
+def start_session(
+    pool: Pool, rng: random.Random | None = None, seen: frozenset[str] | set[str] = frozenset()
+) -> Session:
+    """A shuffled round over the whole pool, questions not in `seen` first."""
+    rng = rng or random.Random()
+    fresh = [item for item in pool.items if item_key(item) not in seen]
+    repeats = [item for item in pool.items if item_key(item) in seen]
+    rng.shuffle(fresh)
+    rng.shuffle(repeats)
+    return Session(items=fresh + repeats)
 
 
 def finished(session: Session) -> bool:

meanwhile_cli-0.1.2/src/meanwhile/scores.py

@@ -0,0 +1,75 @@
+"""Per-developer running totals, and which questions this developer has
+answered. Gitignored: both are local, never shared."""
+
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+
+from .game import Session
+
+SCORES_RELPATH = ".meanwhile/scores.json"
+_ZERO = {"answered": 0, "correct": 0, "best_streak": 0}
+
+
+def _path(repo_dir: str | Path) -> Path:
+    return Path(repo_dir) / SCORES_RELPATH
+
+
+def _read(repo_dir: str | Path) -> dict:
+    try:
+        data = json.loads(_path(repo_dir).read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return {}
+    return data if isinstance(data, dict) else {}
+
+
+def _write(repo_dir: str | Path, totals: dict, seen: set[str]) -> None:
+    path = _path(repo_dir)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}")
+    tmp.write_text(json.dumps({**totals, "seen": sorted(seen)}, indent=2), encoding="utf-8")
+    tmp.replace(path)
+
+
+def load_scores(repo_dir: str | Path) -> dict:
+    data = _read(repo_dir)
+    out = dict(_ZERO)
+    for key in out:
+        value = data.get(key, 0)
+        out[key] = value if isinstance(value, int) and value >= 0 else 0
+    return out
+
+
+def record_session(repo_dir: str | Path, session: Session) -> dict:
+    totals = load_scores(repo_dir)
+    totals["answered"] += session.answered
+    totals["correct"] += session.correct
+    totals["best_streak"] = max(totals["best_streak"], session.best_streak)
+    _write(repo_dir, totals, load_seen(repo_dir))
+    return totals
+
+
+def load_seen(repo_dir: str | Path) -> set[str]:
+    """The keys (see `game.item_key`) of the questions answered so far."""
+    seen = _read(repo_dir).get("seen", [])
+    if not isinstance(seen, list):
+        return set()
+    return {key for key in seen if isinstance(key, str)}
+
+
+def mark_seen(repo_dir: str | Path, key: str, pool_keys: set[str]) -> set[str]:
+    """Remember one answered question, and return what is remembered now.
+
+    Written on every answer rather than at the end of a round: a pane closed
+    with its terminal never reaches the end of a round. Once every question in
+    the pool has been answered the list starts over, so the next rounds go
+    back to a plain shuffle instead of ordering by a list that covers it all.
+    Keys of questions no longer in the pool are dropped on the way.
+    """
+    seen = (load_seen(repo_dir) & pool_keys) | {key}
+    if pool_keys <= seen:
+        seen = set()
+    _write(repo_dir, load_scores(repo_dir), seen)
+    return seen

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/tests/test_app.py

@@ -325,6 +325,22 @@ async def test_space_on_an_exhausted_pool_deals_a_fresh_round(tmp_path):
     assert saved["answered"] == 1  # the finished round was banked, and only once
 
 
+async def test_an_answered_question_is_dealt_last_next_time(tmp_path):
+    """Remembered across panes, not just within one: a second pane opened on
+    the same repository leads with what the first one never got to."""
+    status = {"value": "idle"}
+    first = lifecycle_app([QUIZ, NARROW], status, tmp_path)
+    async with first.run_test() as pilot:
+        await pilot.pause()
+        answered = game.current(first.session)
+        first.action_choose(1)
+        await pilot.pause()
+
+    for _ in range(10):  # the shuffle must never put it first again
+        second = lifecycle_app([QUIZ, NARROW], status, tmp_path)
+        assert second.session.items[-1] is answered
+
+
 async def test_quitting_mid_session_banks_it(tmp_path):
     """Without hooks there is never an idle edge, so `q` is where a session ends."""
     status = {"value": "idle"}

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/tests/test_game.py

@@ -84,3 +84,15 @@ def test_answering_a_finished_session_is_rejected():
     assert game.finished(session) is True
     with pytest.raises(game.GameError):
         game.answer(session, 1)
+
+
+def test_unseen_questions_come_before_seen_ones():
+    seen = {game.item_key(QUIZ)}
+    for seed in range(20):  # whatever the shuffle, the seen one is last
+        session = game.start_session(make_pool([QUIZ, QUIZ_2]), rng=random.Random(seed), seen=seen)
+        assert session.items == [QUIZ_2, QUIZ]
+
+
+def test_the_item_key_follows_the_question_text_not_the_position():
+    assert game.item_key(QUIZ) == game.item_key(QuizItem(**{**QUIZ.__dict__, "source": "moved.py"}))
+    assert game.item_key(QUIZ) != game.item_key(QUIZ_2)

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/tests/test_plugin_files.py

@@ -102,6 +102,17 @@ def test_the_build_prompt_ends_by_telling_the_user_how_to_play():
     assert "same directory" in finish
 
 
+def test_the_build_prompt_extends_an_existing_pool_instead_of_replacing_it():
+    """Running the build again is how a player gets more questions. Replacing
+    the pool would throw away the questions the team already has, and with
+    them every player's record of which ones they answered."""
+    text = PROMPT_SOURCE.read_text(encoding="utf-8")
+    extend = text.split("## Extending an existing pool")[1].split("##")[0]
+    assert "Keep every existing item exactly as it is" in extend
+    assert "fresh pool" in extend
+    assert "`language`" in extend
+
+
 def test_the_slash_command_delegates_rather_than_duplicating():
     body = BUILD_COMMAND.read_text(encoding="utf-8")
     assert "build_prompt.md" in body

{meanwhile_cli-0.1.1 → meanwhile_cli-0.1.2}/tests/test_scores.py

@@ -30,3 +30,35 @@ def test_an_unplayed_session_writes_nothing_new(tmp_path):
     scores.record_session(tmp_path, Session(items=[], answered=2, correct=1, best_streak=1))
     unchanged = scores.record_session(tmp_path, Session(items=[]))
     assert unchanged == {"answered": 2, "correct": 1, "best_streak": 1}
+
+
+def test_seen_questions_are_remembered_across_loads(tmp_path):
+    scores.mark_seen(tmp_path, "a", {"a", "b", "c"})
+    scores.mark_seen(tmp_path, "b", {"a", "b", "c"})
+    assert scores.load_seen(tmp_path) == {"a", "b"}
+
+
+def test_seen_starts_over_once_the_whole_pool_is_answered(tmp_path):
+    scores.mark_seen(tmp_path, "a", {"a", "b"})
+    assert scores.mark_seen(tmp_path, "b", {"a", "b"}) == set()
+    assert scores.load_seen(tmp_path) == set()
+
+
+def test_seen_drops_questions_that_left_the_pool(tmp_path):
+    scores.mark_seen(tmp_path, "gone", {"gone", "x", "y"})
+    assert scores.mark_seen(tmp_path, "x", {"x", "y"}) == {"x"}
+
+
+def test_totals_and_seen_do_not_overwrite_each_other(tmp_path):
+    scores.mark_seen(tmp_path, "a", {"a", "b"})
+    scores.record_session(tmp_path, Session(items=[], answered=1, correct=1, best_streak=1))
+    assert scores.load_seen(tmp_path) == {"a"}
+    scores.mark_seen(tmp_path, "b", {"a", "b", "c"})
+    assert scores.load_scores(tmp_path) == {"answered": 1, "correct": 1, "best_streak": 1}
+
+
+def test_a_malformed_seen_list_reads_as_empty(tmp_path):
+    (tmp_path / ".meanwhile").mkdir()
+    (tmp_path / scores.SCORES_RELPATH).write_text('{"answered": 1, "seen": "nope"}')
+    assert scores.load_seen(tmp_path) == set()
+    assert scores.load_scores(tmp_path)["answered"] == 1

meanwhile_cli-0.1.1/src/meanwhile/__init__.py

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

meanwhile_cli-0.1.1/src/meanwhile/scores.py

@@ -1,44 +0,0 @@
-"""Per-developer running totals. Gitignored: scores are local, never shared."""
-
-from __future__ import annotations
-
-import json
-import os
-from pathlib import Path
-
-from .game import Session
-
-SCORES_RELPATH = ".meanwhile/scores.json"
-_ZERO = {"answered": 0, "correct": 0, "best_streak": 0}
-
-
-def _path(repo_dir: str | Path) -> Path:
-    return Path(repo_dir) / SCORES_RELPATH
-
-
-def load_scores(repo_dir: str | Path) -> dict:
-    try:
-        data = json.loads(_path(repo_dir).read_text(encoding="utf-8"))
-    except (OSError, json.JSONDecodeError):
-        return dict(_ZERO)
-    if not isinstance(data, dict):
-        return dict(_ZERO)
-    out = dict(_ZERO)
-    for key in out:
-        value = data.get(key, 0)
-        out[key] = value if isinstance(value, int) and value >= 0 else 0
-    return out
-
-
-def record_session(repo_dir: str | Path, session: Session) -> dict:
-    totals = load_scores(repo_dir)
-    totals["answered"] += session.answered
-    totals["correct"] += session.correct
-    totals["best_streak"] = max(totals["best_streak"], session.best_streak)
-
-    path = _path(repo_dir)
-    path.parent.mkdir(parents=True, exist_ok=True)
-    tmp = path.with_name(f"{path.name}.tmp.{os.getpid()}")
-    tmp.write_text(json.dumps(totals, indent=2), encoding="utf-8")
-    tmp.replace(path)
-    return totals