mmm-mcp-server 0.1.2 → 0.2.0

package/README.en.md

@@ -11,7 +11,7 @@ A tool that lets you read and write your own maps in Matryoshka Mind Map (a mind
 
 This tool runs entirely on your computer, with no always-on server. It starts only when needed and accesses your own maps with your own login credentials (the developer cannot see your data).
 
-> **For users who installed via `git clone` before September 30, 2026**: Due to a data format migration in the app, older versions will fail when writing to maps. Please replace the registration in Step 5 below with `npx -y mmm-mcp-server` (you do not need to log in again). If you want to keep using your cloned copy, run `git pull && npm install && npm run build` in the `mmm_mcp` folder and restart your AI agent.
+> **For users who installed via `git clone` before September 30, 2026**: Due to a data format migration in the app, older versions will fail when writing to maps. Please replace the registration in Step 5 below with `npx -y mmm-mcp-server@latest` (you do not need to log in again). If you want to keep using your cloned copy, run `git pull && npm install && npm run build` in the `mmm_mcp` folder and restart your AI agent.
 
 > This guide walks you through every step, starting with how to open the terminal (the window where you type commands), so that you can follow along even if you are not used to working with a computer.
 >
@@ -66,7 +66,7 @@ Choose one of the following three options based on how you usually log in to the
 ### If you log in with Google
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login login --method google
+npx -y -p mmm-mcp-server@latest mmm-login login --method google
 ```
 
 Your browser opens automatically; log in with the Google account you usually use.
@@ -74,7 +74,7 @@ Your browser opens automatically; log in with the Google account you usually use
 ### If you log in with Apple
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login login --method apple
+npx -y -p mmm-mcp-server@latest mmm-login login --method apple
 ```
 
 Your browser opens automatically; log in with your Apple ID.
@@ -82,7 +82,7 @@ Your browser opens automatically; log in with your Apple ID.
 ### If you log in with an email address and password
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login login --method email
+npx -y -p mmm-mcp-server@latest mmm-login login --method email
 ```
 
 You will be asked for your email address and password (the password is not shown on screen).
@@ -92,23 +92,23 @@ You will be asked for your email address and password (the password is not shown
 Once you have logged in, you do not need to log in again each time (your credentials are stored only on your computer, in a form that only you can read).
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login status
+npx -y -p mmm-mcp-server@latest mmm-login status
 ```
 
 shows your login status. To log out:
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login logout
+npx -y -p mmm-mcp-server@latest mmm-login logout
 ```
 
 ## 5. Register It with Your AI Agent
 
-Below are the instructions for Claude Desktop and Claude Code, which have been tested. If you use another MCP-compatible client (e.g., Codex), in most cases you only need to register the server launch command (`npx -y mmm-mcp-server`) in that client's MCP server settings. See your client's documentation for the exact steps.
+Below are the instructions for Claude Desktop and Claude Code, which have been tested. If you use another MCP-compatible client (e.g., Codex), in most cases you only need to register the server launch command (`npx -y mmm-mcp-server@latest`) in that client's MCP server settings. See your client's documentation for the exact steps.
 
 ### Claude Code
 
 ```bash
-claude mcp add mmm -- npx -y mmm-mcp-server
+claude mcp add mmm -- npx -y mmm-mcp-server@latest
 ```
 
 ### Claude Desktop
@@ -120,7 +120,7 @@ Open the Claude Desktop configuration file (`claude_desktop_config.json`) and ad
   "mcpServers": {
     "mmm": {
       "command": "npx",
-      "args": ["-y", "mmm-mcp-server"]
+      "args": ["-y", "mmm-mcp-server@latest"]
     }
   }
 }
@@ -164,6 +164,38 @@ The reasons:
 - **Do not mix URLs with text**: A URL in the same element as other text is not treated as a link in the app, so tapping it does nothing.
 - **Chronological order**: Compared with ordering by task name, checking items off in order makes it easier to notice anything you missed.
 
+## Updating to the Latest Version
+
+If your registration in Step 5 uses `mmm-mcp-server@latest`, the latest version is used every time your AI agent starts, so there is nothing to do.
+
+If you registered with `npx -y mmm-mcp-server` (without `@latest`), you may still be running the old version that was downloaded the first time. Update the registration as follows (you do not need to log in again).
+
+### Claude Code
+
+Remove the registration, then register it again.
+
+```bash
+claude mcp remove mmm
+```
+
+```bash
+claude mcp add mmm -- npx -y mmm-mcp-server@latest
+```
+
+If you registered with `--scope user`, add `--scope user` to both commands.
+
+```bash
+claude mcp remove mmm --scope user
+```
+
+```bash
+claude mcp add mmm --scope user -- npx -y mmm-mcp-server@latest
+```
+
+### Claude Desktop
+
+Change `"args"` in `claude_desktop_config.json` to `["-y", "mmm-mcp-server@latest"]`, save it, and restart Claude Desktop.
+
 ## Troubleshooting
 
 | Symptom | Cause / Solution |
@@ -189,7 +221,7 @@ What follows is **just one example of how it can be used**. It is not a standard
 When registering with Claude Code in Step 5, the `mmm` tool is only available in the current folder by default. To use it no matter which folder you start `claude` in, register it with `--scope user`:
 
 ```bash
-claude mcp add mmm --scope user -- npx -y mmm-mcp-server
+claude mcp add mmm --scope user -- npx -y mmm-mcp-server@latest
 ```
 
 **(2) Write the workflow rules in your global CLAUDE.md (`~/.claude/CLAUDE.md`)**

package/README.md

@@ -20,7 +20,7 @@ Desktop・Claude Codeに限らず、MCPに対応したAIエージェントであ
 
 > **2026年9月30日より前に `git clone` で導入した方へ**: アプリ側のデータ形式の
 > 切り替えに伴い、古い版ではマップへの書き込みが失敗するようになります。下の手順5の
-> 登録を `npx -y mmm-mcp-server` に置き換えてください（ログインし直す必要はありません）。
+> 登録を `npx -y mmm-mcp-server@latest` に置き換えてください（ログインし直す必要はありません）。
 > clone したまま使い続ける場合は、`mmm_mcp` フォルダで `git pull && npm install && npm run build`
 > を実行してからAIエージェントを再起動してください。
 
@@ -98,7 +98,7 @@ Matryoshka Mind Mapアプリで普段どのログイン方法を使っている
 ### Googleでログインしている場合
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login login --method google
+npx -y -p mmm-mcp-server@latest mmm-login login --method google
 ```
 
 ブラウザが自動で開くので、いつも使っているGoogleアカウントでログインします。
@@ -106,7 +106,7 @@ npx -y -p mmm-mcp-server mmm-login login --method google
 ### Appleでログインしている場合
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login login --method apple
+npx -y -p mmm-mcp-server@latest mmm-login login --method apple
 ```
 
 こちらもブラウザが自動で開くので、Apple IDでログインします。
@@ -114,7 +114,7 @@ npx -y -p mmm-mcp-server mmm-login login --method apple
 ### メールアドレスとパスワードでログインしている場合
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login login --method email
+npx -y -p mmm-mcp-server@latest mmm-login login --method email
 ```
 
 メールアドレスとパスワードを聞かれるので入力してください（パスワードは
@@ -131,27 +131,27 @@ npx -y -p mmm-mcp-server mmm-login login --method email
 あなたのパソコンの中だけに、あなた以外読めない形で保存されます）。
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login status
+npx -y -p mmm-mcp-server@latest mmm-login status
 ```
 
 でログイン状態を確認できます。ログアウトしたい場合は次のコマンドです。
 
 ```bash
-npx -y -p mmm-mcp-server mmm-login logout
+npx -y -p mmm-mcp-server@latest mmm-login logout
 ```
 
 ## 5. AIエージェントにMatryoshkaを教える
 
 ここでは動作確認済みのClaude Desktop / Claude Codeへの登録方法を示します。
 他のMCP対応クライアント（例: Codexなど）を使っている場合も、多くは同じように
-「サーバーを起動するコマンド」（`npx -y mmm-mcp-server`）をそのクライアントの
+「サーバーを起動するコマンド」（`npx -y mmm-mcp-server@latest`）をそのクライアントの
 MCPサーバー設定に登録するだけで使えるはずです。具体的な登録方法はお使いの
 クライアントのドキュメントを確認してください。
 
 ### Claude Codeを使っている場合
 
 ```bash
-claude mcp add mmm -- npx -y mmm-mcp-server
+claude mcp add mmm -- npx -y mmm-mcp-server@latest
 ```
 
 ### Claude Desktopを使っている場合
@@ -164,7 +164,7 @@ Claude Desktopの設定ファイル（`claude_desktop_config.json`）を開き
   "mcpServers": {
     "mmm": {
       "command": "npx",
-      "args": ["-y", "mmm-mcp-server"]
+      "args": ["-y", "mmm-mcp-server@latest"]
     }
   }
 }
@@ -223,6 +223,42 @@ AIエージェントに任せると楽な反面、そのままだと読みにく
 - **時系列で並べる** … 作業の名前で並べるより、順に消していく形になるぶん、
   抜けに気づきやすくなります
 
+## 最新版にする
+
+手順5の登録が `mmm-mcp-server@latest` になっていれば、AIエージェントを起動するたびに
+最新版が使われるので、何もする必要はありません。
+
+`@latest` の付いていない `npx -y mmm-mcp-server` で登録した方は、最初に取得した古い版を
+使い続けていることがあります。次のように登録を書き換えてください（ログインし直す必要は
+ありません）。
+
+### Claude Codeを使っている場合
+
+登録を一度消してから、登録し直します。
+
+```bash
+claude mcp remove mmm
+```
+
+```bash
+claude mcp add mmm -- npx -y mmm-mcp-server@latest
+```
+
+`--scope user` で登録していた方は、消すときも登録するときも `--scope user` を付けます。
+
+```bash
+claude mcp remove mmm --scope user
+```
+
+```bash
+claude mcp add mmm --scope user -- npx -y mmm-mcp-server@latest
+```
+
+### Claude Desktopを使っている場合
+
+`claude_desktop_config.json` の `"args"` を `["-y", "mmm-mcp-server@latest"]` に書き換えて保存し、
+Claude Desktopを再起動してください。
+
 ## よくあるトラブル
 
 | 症状 | 原因・対処 |
@@ -257,7 +293,7 @@ AIエージェントに任せると楽な反面、そのままだと読みにく
 するには、`--scope user`を付けて登録します。
 
 ```bash
-claude mcp add mmm --scope user -- npx -y mmm-mcp-server
+claude mcp add mmm --scope user -- npx -y mmm-mcp-server@latest
 ```
 
 **(2) グローバルのCLAUDE.md（`~/.claude/CLAUDE.md`）に運用ルールを書く**

package/dist/src/auth/session.js

@@ -45,7 +45,7 @@ export class AuthSession {
 }
 export class NotSignedInError extends Error {
     constructor() {
-        super("サインインしていません。ターミナルで `npx -y -p mmm-mcp-server mmm-login login --method google` を実行してください(email / apple も選べます。git clone して使っている場合は、そのフォルダで `npm run login -- login --method google`)。");
+        super("サインインしていません。ターミナルで `npx -y -p mmm-mcp-server@latest mmm-login login --method google` を実行してください(email / apple も選べます。git clone して使っている場合は、そのフォルダで `npm run login -- login --method google`)。");
         this.name = "NotSignedInError";
     }
 }

package/dist/src/domain/appendForest.js

@@ -1,5 +1,4 @@
 import { newDocId } from "./idGen.js";
-import { lastChildOf } from "./body.js";
 /** ネストしたツリー入力を、ID採番済み・prev/next/parent/child関係を組んだ配列に変換する。 */
 export function buildForestFromTree(roots) {
     const all = [];
@@ -31,52 +30,3 @@ export function buildForestFromTree(roots) {
     build(roots, null);
     return all;
 }
-/**
- * 組み立てたforest(森)を、既存の要素の[targetParentId]配下の末尾に連結する
- * ためのFirestore書き込み一覧を作る。auto_structure_thought /
- * import_markdown_context の両方から共通で使う。
- *
- * `isTodo`がfalseのマップでは、doneは常にfalseとして書き込む
- * (MatryoshkaModel.importMarkdownと同じ挙動)。
- */
-export function buildAppendWrites(bodiesPath, existingBodies, forest, targetParentId, isTodo) {
-    const roots = forest.filter((n) => n.parentId === null);
-    const last = lastChildOf(existingBodies, targetParentId);
-    if (roots.length > 0) {
-        roots[0].prevId = last;
-    }
-    const writes = forest.map((node) => ({
-        path: `${bodiesPath}/${node.id}`,
-        fields: {
-            detail: node.detail,
-            parent: node.parentId ?? targetParentId,
-            prev: node.prevId,
-            next: node.nextId,
-            child: node.childId,
-            done: isTodo ? node.done : false,
-        },
-    }));
-    if (roots.length > 0) {
-        if (last !== null) {
-            // 末尾要素のnextを書き換える。読み取り後に他の操作(並行するappendや
-            // アプリ操作)がこの要素を書き換えていた場合、requireUpdateTimeにより
-            // FAILED_PRECONDITIONで失敗する(呼び出し側はrunOptimisticで読み取り
-            // からやり直す)。
-            const lastBody = existingBodies.find((b) => b.id === last);
-            writes.push({
-                path: `${bodiesPath}/${last}`,
-                fields: { next: roots[0].id },
-                requireUpdateTime: lastBody?.updateTime,
-            });
-        }
-        else if (targetParentId !== null) {
-            const parentBody = existingBodies.find((b) => b.id === targetParentId);
-            writes.push({
-                path: `${bodiesPath}/${targetParentId}`,
-                fields: { child: roots[0].id },
-                requireUpdateTime: parentBody?.updateTime,
-            });
-        }
-    }
-    return { writes, createdIds: forest.map((n) => n.id) };
-}

package/dist/src/domain/detailLimit.js

@@ -0,0 +1,18 @@
+/**
+ * 1要素の本文の上限(UTF-16の単位、JavaScriptのlength)。子の一覧は1ドキュメントに
+ * 入るため、巨大な書き込み1回でドキュメントの上限1MiBを超えないようにする。
+ * アプリの lib/domain/detail_limit.dart と同じ値にする。決めごとは docs/paid-plan.md §7。
+ */
+export const MAX_DETAIL_LENGTH = 5000;
+/** 上限を超えたときにClaudeへ返す説明。黙って切らず、分けて書き直してもらう。 */
+export function tooLongDetailMessage(length) {
+    return (`要素の本文が${length}文字あり、1要素の上限(${MAX_DETAIL_LENGTH}文字)を超えています。` +
+        `何も書き込んでいません。複数の要素に分けて書き直してください。`);
+}
+/** [details]のうち上限を超えるものがあれば、何も書かずに済むよう例外を投げる。 */
+export function assertDetailLengths(details) {
+    for (const detail of details) {
+        if (detail.length > MAX_DETAIL_LENGTH)
+            throw new Error(tooLongDetailMessage(detail.length));
+    }
+}

package/dist/src/domain/headerOrder.js

@@ -0,0 +1,40 @@
+/**
+ * 新しいマップを一覧の先頭に置くとき、既存の自分のマップの`order`を
+ * どう書き換えるかを計算する(Firestoreに触れない)。
+ * lib/header_list/header_order.dart の prependedHeaderOrders と同じ考え方。
+ *
+ * 新しいマップを1にし、既存はアプリの一覧と同じ並び(orderの昇順、
+ * 同値はドキュメントidの順)のまま2..n+1に振り直す。値が変わるものだけを返す。
+ * 欠番と重複もこの1回で解消する。
+ */
+export function prependedHeaderOrders(entries) {
+    const sorted = [...entries].sort((a, b) => a.order !== b.order ? a.order - b.order : a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    const updates = [];
+    sorted.forEach((entry, position) => {
+        if (entry.order !== position + 2)
+            updates.push({ id: entry.id, order: position + 2 });
+    });
+    return updates;
+}
+/**
+ * create_map の書き込み一式。既存の自分のマップを2..n+1に振り直し、新しいマップを
+ * order 1 で作る。order を持たないマップは一覧に出ないので触らない。
+ * 振り直しは読んだ時点の updateTime を前提条件にする(読んだ後に別の端末で消された
+ * マップを、order だけのドキュメントとして作り直さないため)。
+ */
+export function buildCreateMapWrites(headersPath, existing, headerId, title, isTodo) {
+    const updateTimes = new Map(existing.map((doc) => [doc.id, doc.updateTime]));
+    const shifts = prependedHeaderOrders(existing
+        .filter((doc) => typeof doc.data.order === "number")
+        .map((doc) => ({ id: doc.id, order: doc.data.order })));
+    const headerPath = `${headersPath}/${headerId}`;
+    return [
+        ...shifts.map((s) => ({
+            path: `${headersPath}/${s.id}`,
+            fields: { order: s.order },
+            requireUpdateTime: updateTimes.get(s.id),
+        })),
+        { path: headerPath, fields: { title, order: 1, isTodo, editors: [], viewers: [] } },
+        { path: `${headerPath}/levels/root`, fields: { children: [] } },
+    ];
+}

package/dist/src/domain/levels.js

@@ -3,21 +3,15 @@
 //
 //   levels/{levelId}
 //     children: [ { id, detail, done }, ... ]
+//     schedule: { 子のid: { due?: {at, allDay}, start?: {at, allDay} }, ... }
+//               (日付を持つ子だけ。docs/schedule.md §2)
+//     links:    { 子のid: [ { uid, headerId }, ... ], ... }
+//               (マップ間リンクを持つ子だけ。docs/map-links.md §8)
 //
 // levelIdはマップ最上位が'root'、それ以外はその要素自身のid。配列の並び順が
 // そのまま兄弟順。子を持つ要素だけドキュメントが存在する(無ければ葉)。
 //
-// MCPは「新形式のみ対応」(移行ロジックはDart側だけに持たせる)。levels/root
-// が無いマップに対する操作は、切替前(bodiesとlevelsの両方へ書く間)だけ、
-// アプリで一度開いてもらうよう案内して止める。切替後は空のマップとして扱う
-// (levelsMode.tsのreadLevelsSnapshot)。
-export class LevelsNotInitializedError extends Error {
-    constructor(title) {
-        super(`「${title}」はまだ新形式(levels)のデータがありません。` +
-            "お手数ですが、アプリでこのマップを一度開いてから、もう一度お試しください。");
-        this.name = "LevelsNotInitializedError";
-    }
-}
+// 書き込みは levelsOps.ts が行う。ここはデータ形状の解釈と読み取りだけを持つ。
 function toEntry(raw) {
     if (typeof raw !== "object" || raw === null)
         return null;
@@ -42,42 +36,64 @@ export function childrenOf(data) {
     }
     return result;
 }
-/** levels配下の全ドキュメントを読み、levelId -> children[] のMapにする。 */
-export async function readAllLevelDocs(client, levelsPath) {
-    const docs = await client.listDocuments(levelsPath);
+function toScheduleDate(raw) {
+    if (typeof raw !== "object" || raw === null)
+        return undefined;
+    const obj = raw;
+    if (!(obj.at instanceof Date) || typeof obj.allDay !== "boolean")
+        return undefined;
+    return { at: obj.at, allDay: obj.allDay };
+}
+/** levelsドキュメントの schedule を子のid -> 日付にする。形の崩れたもの・空のものは読み飛ばす。 */
+export function scheduleOf(data) {
     const result = new Map();
-    for (const doc of docs) {
-        result.set(doc.id, childrenOf(doc.data));
+    const raw = data.schedule;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return result;
+    for (const [id, value] of Object.entries(raw)) {
+        if (typeof value !== "object" || value === null)
+            continue;
+        const obj = value;
+        const entry = {};
+        const due = toScheduleDate(obj.due);
+        const start = toScheduleDate(obj.start);
+        if (due)
+            entry.due = due;
+        if (start)
+            entry.start = start;
+        if (due || start)
+            result.set(id, entry);
     }
     return result;
 }
-/** levels/rootが無ければ、アプリで開いてもらうよう案内して止める。 */
-export function assertLevelsInitialized(levelsById, mapTitle) {
-    if (!levelsById.has("root")) {
-        throw new LevelsNotInitializedError(mapTitle);
-    }
-}
-/**
- * [levelId]のlevelsドキュメントが存在するかだけを軽く確認する。
- * 「levels/rootが無ければ止める」ような存在チェックのためだけに
- * readAllLevelDocs(コレクション全体のページング読み取り)を使うのは、
- * 子を多く持つ大きなマップほど無駄が大きい。1件のgetDocumentで足りる
- * 場面(list_elementsのようにツリー全体が実際に必要な場合を除く)は
- * こちらを使うこと。
- */
-export async function levelsDocExists(client, levelsPath, levelId) {
-    return (await client.getDocument(`${levelsPath}/${levelId}`)) !== null;
-}
-/** [levelsDocExists]の結果を見て、levels/rootが無ければ止める。 */
-export function assertLevelsRootExists(rootExists, mapTitle) {
-    if (!rootExists) {
-        throw new LevelsNotInitializedError(mapTitle);
+/** levelsドキュメントの links を子のid -> リンク先にする。形の崩れたもの・空のもの・重複は読み飛ばす。 */
+export function linksOf(data) {
+    const result = new Map();
+    const raw = data.links;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw))
+        return result;
+    for (const [id, value] of Object.entries(raw)) {
+        if (!Array.isArray(value))
+            continue;
+        const targets = [];
+        for (const item of value) {
+            if (typeof item !== "object" || item === null)
+                continue;
+            const obj = item;
+            if (typeof obj.uid !== "string" || typeof obj.headerId !== "string")
+                continue;
+            if (targets.some((t) => t.uid === obj.uid && t.headerId === obj.headerId))
+                continue;
+            targets.push({ uid: obj.uid, headerId: obj.headerId });
+        }
+        if (targets.length > 0)
+            result.set(id, targets);
     }
+    return result;
 }
 /**
- * 'root'から再帰的にlevelsを展開してツリーを組み立てる(bodies版buildTreeの
- * levels版)。levelsは配列そのものが順序を表すため、連結リストの再構築や
- * 分断の復元は不要。循環参照だけは防御的に検出して打ち切る。
+ * 'root'から再帰的にlevelsを展開してツリーを組み立てる。levelsは配列そのものが
+ * 順序を表すため、並び順の再構築は不要。循環参照だけは防御的に検出して打ち切る。
  */
 export function buildTreeFromLevels(levelsById) {
     function walk(levelId, parentId, ancestry) {
@@ -97,148 +113,3 @@ export function buildTreeFromLevels(levelsById) {
     }
     return walk("root", null, new Set());
 }
-/**
- * forest(bodies用のbuildAppendWritesと同じ入力)から、levels側の書き込み
- * 一覧を組み立てる。forest内で子を持つノードごとに levels/{id} を新規作成し、
- * forestの最上位(ルート)群は挿入先(targetParentId ?? 'root')の既存配列へ
- * 追記する。[targetHasExistingChildren]は、bodies側でlastChildOfが返した
- * 値がnullでなかったか(＝挿入先が既に子を持っていたか)をそのまま渡すこと。
- */
-export function buildAppendLevelWrites(levelsPath, forest, targetParentId, targetHasExistingChildren, isTodo) {
-    const writes = [];
-    const byParent = new Map();
-    for (const node of forest) {
-        const list = byParent.get(node.parentId) ?? [];
-        list.push(node);
-        byParent.set(node.parentId, list);
-    }
-    const entryOf = (node) => ({
-        id: node.id,
-        detail: node.detail,
-        done: isTodo ? node.done : false,
-    });
-    // forest内で子を持つノードは全て新規作成なので、既存のlevels/{id}と
-    // 衝突することはない(既存ドキュメントは無いはず)。
-    for (const [parentId, children] of byParent) {
-        if (parentId === null)
-            continue; // ルート群は下で挿入先へ追記する
-        writes.push({
-            path: `${levelsPath}/${parentId}`,
-            fields: { children: children.map(entryOf) },
-        });
-    }
-    const roots = byParent.get(null) ?? [];
-    if (roots.length > 0) {
-        const targetLevelId = targetParentId ?? "root";
-        if (targetHasExistingChildren) {
-            writes.push({
-                path: `${levelsPath}/${targetLevelId}`,
-                arrayUnion: { field: "children", values: roots.map(entryOf) },
-            });
-        }
-        else {
-            writes.push({
-                path: `${levelsPath}/${targetLevelId}`,
-                fields: { children: roots.map(entryOf) },
-            });
-        }
-    }
-    return writes;
-}
-/**
- * [levelId]のlevelsドキュメントのchildren配列から、idが[removeIds]に含まれる
- * エントリを取り除くFirestoreWriteを1件返す。ドキュメントが無ければ何もしない
- * (levelsはbest-effortの書き込みで、bodiesと食い違っていても実害は無いため)。
- * requireUpdateTimeで楽観的ロックする(呼び出し側はrunOptimisticで使うこと)。
- */
-export async function buildRemoveChildrenWrite(client, levelsPath, levelId, removeIds) {
-    const doc = await client.getDocument(`${levelsPath}/${levelId}`);
-    if (!doc)
-        return null;
-    const children = childrenOf(doc.data).filter((c) => !removeIds.includes(c.id));
-    return { path: `${levelsPath}/${levelId}`, fields: { children }, requireUpdateTime: doc.updateTime };
-}
-/**
- * [levelId]のlevelsドキュメントのchildren配列の[afterId]の直後(nullなら先頭)に
- * [entry]を挿入するFirestoreWriteを1件返す。ドキュメントが無ければ新規作成する
- * (この場合はrequireUpdateTimeを付けない = 何も無い前提で作成する)。[afterId]が
- * 見つからない場合は末尾に足す(Dart版LevelsRepository.insertChildと同じ方針)。
- */
-/**
- * [levelId]のchildrenの中で[entry]を一度取り除いてから、[afterId]の直後
- * (nullなら先頭)へ入れ直す書き込みを作る。同じ親の中での並べ替え専用。
- *
- * **remove用とinsert用の書き込みを別々に作って両方commitしてはいけない。**
- * どちらも「元のchildren」を読んでから組み立てるため、同じドキュメントへの
- * 書き込みが2つできて後勝ちになり、要素が重複する。
- */
-export async function buildReorderChildWrite(client, levelsPath, levelId, entry, afterId) {
-    const doc = await client.getDocument(`${levelsPath}/${levelId}`);
-    const children = (doc ? childrenOf(doc.data) : []).filter((c) => c.id !== entry.id);
-    const insertIndex = afterId === null
-        ? 0
-        : (() => {
-            const found = children.findIndex((c) => c.id === afterId);
-            return found === -1 ? children.length : found + 1;
-        })();
-    children.splice(Math.min(Math.max(insertIndex, 0), children.length), 0, entry);
-    return {
-        path: `${levelsPath}/${levelId}`,
-        fields: { children },
-        requireUpdateTime: doc?.updateTime,
-    };
-}
-export async function buildInsertChildWrite(client, levelsPath, levelId, entry, afterId) {
-    const doc = await client.getDocument(`${levelsPath}/${levelId}`);
-    const children = doc ? childrenOf(doc.data) : [];
-    const insertIndex = afterId === null
-        ? 0
-        : (() => {
-            const found = children.findIndex((c) => c.id === afterId);
-            return found === -1 ? children.length : found + 1;
-        })();
-    children.splice(Math.min(Math.max(insertIndex, 0), children.length), 0, entry);
-    return {
-        path: `${levelsPath}/${levelId}`,
-        fields: { children },
-        requireUpdateTime: doc?.updateTime,
-    };
-}
-/**
- * update_task_status用。[updates]を親ごとにグループ化し、levelsドキュメントを
- * 親ごとに1回だけ読んで該当エントリを書き換えた配列を書き戻すFirestoreWrite[]
- * を組み立てる(Dart版LevelsRepository.updateChildと同じ「読んで置換」方式)。
- * 該当ドキュメントや該当エントリが見つからない場合は、その分だけ静かに
- * スキップする(levelsはbest-effortの書き込みで、失敗しても実害は無いため)。
- */
-export async function buildUpdateEntryWrites(client, levelsPath, updates) {
-    const byLevelId = new Map();
-    for (const update of updates) {
-        const levelId = update.parentId ?? "root";
-        const list = byLevelId.get(levelId) ?? [];
-        list.push({ elementId: update.elementId, patch: update.patch });
-        byLevelId.set(levelId, list);
-    }
-    const writes = [];
-    for (const [levelId, group] of byLevelId) {
-        const doc = await client.getDocument(`${levelsPath}/${levelId}`);
-        if (!doc)
-            continue;
-        const children = childrenOf(doc.data);
-        for (const { elementId, patch } of group) {
-            const index = children.findIndex((c) => c.id === elementId);
-            if (index === -1)
-                continue;
-            children[index] = { ...children[index], ...patch };
-        }
-        // requireUpdateTime: 読み取り後に他の操作がこのlevelsドキュメントを
-        // 書き換えていた場合、この書き込みはFAILED_PRECONDITIONで失敗する
-        // (呼び出し側はrunOptimisticで読み取りからやり直すこと)。
-        writes.push({
-            path: `${levelsPath}/${levelId}`,
-            fields: { children },
-            requireUpdateTime: doc.updateTime,
-        });
-    }
-    return writes;
-}