memory-toast-make-card 0.5.0 → 0.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memory-toast-make-card",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Claude Code skill to build Memory Toast flashcard decks (卡包) — with optional AI image generation using your own OpenAI/Gemini key — and upload, update, or publish them to your Memory Toast account.",
   "bin": {
     "memory-toast-make-card": "bin/install.js"

package/references/pack-format.md

@@ -73,7 +73,7 @@ pack.zip
 
 Rules:
 
-- `id` is always a UUID v4; `position` starts at 0 and increments by array order.
+- `id` is a UUID v4. **On re-upload of the same deck, `upload_pack.py` matches each card against the previous build (`build/pack.zip`) by content and reuses the existing id for unchanged cards** (including back-only edits, e.g. adding an example) — only new cards or cards whose front text changed get a fresh UUID. This keeps the user's study progress across deck updates (the app keys study progress by card id and prunes orphaned progress on pull). `position` starts at 0 and increments by array order.
 - For `storageKind: local`, `storageRef` must be `media/{sectionId}.{ext}` and the ZIP must
   contain the matching file.
 - `storageKind: external` is for YouTube/Vimeo and similar links; `storageRef` is the full URL.
@@ -261,7 +261,7 @@ with the local one and offers the pull when the server is newer and no local edi
 
 | Item | Limit |
 |------|-------|
-| ZIP size | ≤ 200 MB |
+| ZIP size | ≤ 300 MB |
 | title | 1–200 characters |
 | description | ≤ 1000 characters |
 | tags | ≤ 10 |

package/scripts/test_upload_pack.py

@@ -242,6 +242,101 @@ def test_empty_check_uses_plain_text():
             raise AssertionError("expected validation failure for empty stripped front")
 
 
+# ---------------------------------------------------------------------------
+# Stable card ids across rebuilds — so updating a deck preserves the user's
+# study progress. The app keys study progress by card id and prunes orphans on
+# pull, so a re-upload that re-mints ids would wipe progress. Mirrors the Dart
+# content match in features/decks/data/services/progress_remap.dart.
+# ---------------------------------------------------------------------------
+
+def _build_in(deck_dir, cards):
+    """Build a pack inside a PERSISTENT dir, so a second build can reuse ids
+    from the first build's pack.zip. Returns the built cards.json list."""
+    deck = {"title": "T", "description": "", "tags": [], "cards": cards}
+    (deck_dir / "deck.json").write_text(json.dumps(deck))
+    info = up.build_pack(deck_dir)
+    import zipfile
+
+    with zipfile.ZipFile(info["zip_path"]) as zf:
+        return json.loads(zf.read("cards.json"))["cards"]
+
+
+def test_assign_stable_ids_reuses_unchanged_card_ids():
+    prior = [
+        {"id": "id-A", "frontContent": "apple", "backContent": "def-A"},
+        {"id": "id-B", "frontContent": "banana", "backContent": "def-B"},
+    ]
+    new = [
+        {"frontContent": "banana", "backContent": "def-B"},
+        {"frontContent": "apple", "backContent": "def-A"},
+    ]
+    up.assign_stable_ids(new, prior)
+    assert new[0]["id"] == "id-B"  # matched by content, order-independent
+    assert new[1]["id"] == "id-A"
+
+
+def test_assign_stable_ids_back_edit_keeps_id():
+    prior = [{"id": "id-A", "frontContent": "apple", "backContent": "one"}]
+    new = [{"frontContent": "apple", "backContent": "one; two"}]
+    up.assign_stable_ids(new, prior)
+    assert new[0]["id"] == "id-A"  # front-stable match survives a back edit
+
+
+def test_assign_stable_ids_new_card_gets_fresh_id():
+    prior = [{"id": "id-A", "frontContent": "apple", "backContent": "def-A"}]
+    new = [
+        {"frontContent": "apple", "backContent": "def-A"},
+        {"frontContent": "cherry", "backContent": "def-C"},
+    ]
+    up.assign_stable_ids(new, prior)
+    assert new[0]["id"] == "id-A"
+    assert new[1]["id"] and new[1]["id"] != "id-A"
+    assert len(new[1]["id"]) >= 32  # a real uuid, not a placeholder
+
+
+def test_assign_stable_ids_front_change_gets_fresh_id():
+    prior = [{"id": "id-A", "frontContent": "apple", "backContent": "same"}]
+    new = [{"frontContent": "orange", "backContent": "same"}]
+    up.assign_stable_ids(new, prior)
+    assert new[0]["id"] != "id-A"
+
+
+def test_assign_stable_ids_duplicate_front_disambiguated_by_back():
+    prior = [
+        {"id": "id-1", "frontContent": "dup", "backContent": "b1"},
+        {"id": "id-2", "frontContent": "dup", "backContent": "b2"},
+    ]
+    new = [
+        {"frontContent": "dup", "backContent": "b2"},
+        {"frontContent": "dup", "backContent": "b1"},
+    ]
+    up.assign_stable_ids(new, prior)
+    assert new[0]["id"] == "id-2"
+    assert new[1]["id"] == "id-1"
+
+
+def test_build_pack_keeps_card_ids_stable_across_rebuilds():
+    with tempfile.TemporaryDirectory() as d:
+        deck_dir = Path(d)
+        v1 = _build_in(deck_dir, [
+            {"frontContent": "apple", "backContent": "a fruit"},
+            {"frontContent": "banana", "backContent": "yellow"},
+        ])
+        ids_v1 = {c["frontContent"]: c["id"] for c in v1}
+
+        # Rebuild: edit banana's back, append cherry; apple untouched.
+        v2 = _build_in(deck_dir, [
+            {"frontContent": "apple", "backContent": "a fruit"},
+            {"frontContent": "banana", "backContent": "yellow; a fruit"},
+            {"frontContent": "cherry", "backContent": "red"},
+        ])
+        ids_v2 = {c["frontContent"]: c["id"] for c in v2}
+
+        assert ids_v2["apple"] == ids_v1["apple"], "unchanged card kept its id"
+        assert ids_v2["banana"] == ids_v1["banana"], "back-edit kept the id"
+        assert ids_v2["cherry"] not in ids_v1.values(), "new card got a fresh id"
+
+
 def main():
     tests = [v for k, v in sorted(globals().items()) if k.startswith("test_") and callable(v)]
     passed = 0

package/scripts/upload_pack.py

@@ -41,7 +41,7 @@ from pathlib import Path
 
 from _mt_auth import api_call, fail, get_access_token, resolve_api_url
 
-MAX_ZIP_BYTES = 200 * 1024 * 1024  # server-side limit in validators/sync.ts
+MAX_ZIP_BYTES = 300 * 1024 * 1024  # server-side limit in validators/sync.ts
 DECK_RECORD = ".memory-toast.json"  # per-deck AI state file (deckId, version, libraryPackId, …)
 
 ALLOWED_EXTS = {
@@ -521,6 +521,68 @@ def normalize_blocks(blocks: list, deck_dir: Path, where: str, errors: list, med
     return blocks_out, plain, html, sections
 
 
+def _read_prior_cards(deck_dir):
+    """Cards from the previous local build (deck_dir/build/pack.zip), used to
+    reuse card ids on rebuild. Empty when there's no prior pack or it can't be
+    read — the app's pull-time content match is the backstop in that case."""
+    zip_path = Path(deck_dir) / "build" / "pack.zip"
+    if not zip_path.exists():
+        return []
+    try:
+        with zipfile.ZipFile(zip_path) as zf:
+            data = json.loads(zf.read("cards.json").decode("utf-8"))
+    except Exception:
+        return []
+    return [
+        {
+            "id": c.get("id"),
+            "frontContent": c.get("frontContent", ""),
+            "backContent": c.get("backContent", ""),
+        }
+        for c in data.get("cards", [])
+    ]
+
+
+def assign_stable_ids(new_cards, prior_cards):
+    """Assign each new card an id, reusing the prior build's id when the card is
+    'the same', so a re-upload preserves study progress (the app keys progress
+    by card id). Tiered, consuming match against the prior build:
+      1. exact (frontContent, backContent)
+      2. frontContent alone (survives back-side edits, e.g. adding an example)
+    A card is reused only when its key is UNIQUE on both sides; ambiguous or
+    unmatched new cards get a fresh uuid4. Mirrors computeProgressRemap() in the
+    Flutter app. Mutates `new_cards` in place; returns it."""
+    matched = {}  # new index -> reused prior id
+    rem_old = list(range(len(prior_cards)))
+    rem_new = list(range(len(new_cards)))
+
+    def run_pass(key_of):
+        old_keys, new_keys = {}, {}
+        for oi in rem_old:
+            old_keys.setdefault(key_of(prior_cards[oi]), []).append(oi)
+        for ni in rem_new:
+            new_keys.setdefault(key_of(new_cards[ni]), []).append(ni)
+        used_old, used_new = set(), set()
+        for ni in rem_new:
+            key = key_of(new_cards[ni])
+            olds, news = old_keys.get(key, []), new_keys.get(key, [])
+            if len(olds) == 1 and len(news) == 1:
+                matched[ni] = prior_cards[olds[0]].get("id")
+                used_old.add(olds[0])
+                used_new.add(ni)
+        rem_old[:] = [i for i in rem_old if i not in used_old]
+        rem_new[:] = [i for i in rem_new if i not in used_new]
+
+    if prior_cards:
+        run_pass(lambda c: (c.get("frontContent", ""), c.get("backContent", "")))
+        run_pass(lambda c: c.get("frontContent", ""))
+
+    for ni, card in enumerate(new_cards):
+        reused = matched.get(ni)
+        card["id"] = reused if reused else str(uuid.uuid4())
+    return new_cards
+
+
 def build_pack(deck_dir: Path) -> dict:
     deck_json_path = deck_dir / "deck.json"
     if not deck_json_path.is_file():
@@ -591,7 +653,10 @@ def build_pack(deck_dir: Path) -> dict:
         if not back and not back_secs:
             errors.append(f"{where}: card back is empty (no text, no sections)")
         card_out = {
-            "id": str(uuid.uuid4()),
+            # Assigned after the loop by assign_stable_ids(): reused from the
+            # previous build when the card is unchanged, so a re-upload keeps
+            # the user's study progress.
+            "id": None,
             "position": i,
             "frontContent": front,
             "backContent": back,
@@ -611,6 +676,12 @@ def build_pack(deck_dir: Path) -> dict:
     if errors:
         fail("deck.json validation failed:\n  - " + "\n  - ".join(errors))
 
+    # Reuse card ids from the previous build for unchanged cards (and cards
+    # whose front is unchanged) so a re-upload preserves the user's study
+    # progress — the app keys progress by card id and prunes orphans on pull.
+    # New / changed-front cards get a fresh uuid.
+    assign_stable_ids(cards_out, _read_prior_cards(deck_dir))
+
     manifest = {
         "schemaVersion": 1,
         "deckTitle": title,