@quolu/aishell 0.4.12 → 0.6.0

package/README.ja.md

@@ -21,19 +21,17 @@ state/schema migration、診断、復旧、更新、releaseを単独で所有し
 [dotagents](https://github.com/kitepon/dotagents)は公開contractを使って製品横断wireと
 互換性を統合しますが、AIShellの内部運用を制御しません。
 
-AIShellは許可root、file identity、filesystem照合state、直接起動したprocess、完全log、artifactを所有する。reasoning、thread、compaction、sub-agent、汎用terminalはAI hostの責務として残す。
+AIShellはfile identity、filesystem照合state、直接起動したprocess、完全log、artifactを所有する。reasoning、thread、compaction、sub-agent、汎用terminalはAI hostの責務として残す。
 
 ## 30秒で試す
 
 Apple Silicon Mac、macOS 15以降が必要。
 
 ```sh
-npm install -g @quolu/aishell
-aishell-open
-codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
+npm install -g @quolu/aishell && aishell-setup
 ```
 
-管理アプリでAIに許可するfolderを追加し、新しいCodex taskで次のように頼む。
+フォルダの事前登録は不要。新しいCodex taskで対象フォルダを指定して実行する。
 
 ```text
 初回workspace contextはworkspace_snapshotで取得して。focused testはrun_checkで実行し、
@@ -49,8 +47,8 @@ summaryから省略された証拠だけartifact_readで読んで。
 | `search_context` | 直接起動した`rg` workerによるbudget付き検索context |
 | `run_check` | 直接process実行、主要diagnostic、完全stdout/stderr artifact |
 | `artifact_read` | 保持artifactのrange、tail、pattern周辺read |
-| `runtime_status` | 未設定・停止中も含む許可root、停止、worktree、次操作の状態取得 |
-| `runtime_open_manager` | root追加またはAI操作再開のため管理アプリを開く |
+| `runtime_status` | 停止状態、相対パスの基準、次操作の状態取得 |
+| `runtime_open_manager` | AI操作の停止・再開のため管理アプリを開く |
 
 MCP serverへ`AISHELL_CAPABILITY_SET=expanded-v1`を設定すると、candidate surfaceへ明示opt-inできる。
 高密度development 9本と復旧control 2本を公開し、`run_observe`、`workspace_wait`、
@@ -60,7 +58,7 @@ semantic search、project profile、Git branch/worktree modeが加わる。
 Codexでは次のように登録する。
 
 ```sh
-codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
+aishell-setup --ai codex
 ```
 
 未知値または空の`AISHELL_CAPABILITY_SET`と`AISHELL_TOOL_PROFILE`はtyped errorでstartup停止し、
@@ -79,7 +77,7 @@ statelessな連携では、モデルがworkspaceを何度もscanし、command出
 | Context | budget・cursor付きstructured result | stdoutを手動または暗黙に切り詰める |
 | Execution | executable URL、引数、cwd、lifecycleを分離 | shellが1本のcommand文字列を評価 |
 | Evidence | 完全stdout/stderrを期限付きhandleで保持 | response truncation時に証拠が失われやすい |
-| Scope | 人が管理する許可rootと明示的stop状態 | 周囲のshellとhost policyに依存 |
+| Scope | macOSのアクセス権と明示的stop状態 | 周囲のshellとhost policyに依存 |
 
 AIShellはsandboxではなく、任意code実行を安全化しない。process railの目的はtyped executionと観測可能なlifecycleを維持することであり、改名binaryや許可workerが起動する子processを阻止することではない。
 
@@ -89,7 +87,7 @@ AIShellはsandboxではなく、任意code実行を安全化しない。process
 flowchart LR
     Host[AI host<br/>reasoning · threads · compaction] --> MCP[AIShellMCP<br/>MCP 2025-11-25]
     MCP --> Core[AIShellCore]
-    Core --> State[Allowed roots · file identity<br/>FSEvents + reconciliation]
+    Core --> State[File identity<br/>FSEvents + reconciliation]
     Core --> Process[Direct process lifecycle<br/>stdout · stderr · timeout]
     Core --> Evidence[Retained evidence<br/>artifacts · freshness]
     Process --> Workers[git · rg · compiler · tests]
@@ -101,16 +99,16 @@ flowchart LR
 
 ## npmからinstall
 
-global packageは`aishell-mcp`と`aishell-open`を`PATH`へ追加する。`aishell-open`は同梱された管理アプリをLaunchServicesで開く。install scriptは実行しない。
+global packageは`aishell-mcp`、`aishell-open`、`aishell-setup`を`PATH`へ追加する。npm install自体ではスクリプトも管理アプリも起動しない。
 
-upgradeは開いたままの管理アプリの足元でapp bundleを置き換えるため、その窓は壊れる。削除済みbundleを
-掴み続け、ファイル選択を伴う操作を無言で失う。窓自身がこれを検知してbannerで示す。新版が同じpathに
-在る場合はbannerの再起動1回で新版の窓へ移り、pathごと消えている場合は終了と`aishell-open`での開き直しを
-促す。実際の`npm install -g` upgradeで検証済みである。
+対象AIのCLI（`claude`、`codex`、`grok`、Cursorの`agent`）を先に導入する。setupは各CLIからの読戻しも確認する。
+
+`aishell-setup`は導入済みのClaude Code・Codex・Grok Build・Cursorを検出し、管理アプリ準備、MCP登録、設定の読戻し、実際のMCP操作まで確認する。登録はbare `aishell-mcp`＋`AISHELL_CAPABILITY_SET=expanded-v1`。利用者のenv、PATH、他の設定を保持する。`--ai`で対象を指定でき、`--check`は設定やアプリ起動を変更せず診断する。Windows/LinuxとIntel Macは対象外。詳細は[製品単体の導入契約](https://github.com/kitepon/aishell/blob/main/docs/setup.md)を参照。
+
+更新後も同じ`aishell-setup`を実行する。旧管理アプリを正常終了して導入済みのアプリを開き、登録保持・読戻し・MCP実操作まで確認する。接続済みのMCPは、hostで再接続すると新版へ切り替わる。
 
 ```sh
-npm install -g @quolu/aishell
-aishell-open
+npm install -g @quolu/aishell && aishell-setup
 ```
 
 現在の実験版はDeveloper ID署名・notarization前である。
@@ -127,16 +125,15 @@ open build/AIShell.app
 
 MCP実行ファイルは`build/AIShell.app/Contents/Helpers/aishell-mcp`へ同梱される。
 
-管理アプリの「許可rootを追加」でAIに操作させるfolderを選ぶ。許可済みGit repositoryの`.git/worktrees`へ正式登録され、双方の管理情報が一致するworktreeは自動的に実効rootへ加わる。
+フォルダ登録は不要。絶対パスは指定した場所を、相対パスと省略時はMCP起動ディレクトリを基準にする。Git worktreeも直接指定でき、旧設定の許可フォルダ一覧は無視される。
 
 ## 別のAI hostへ接続
 
 global npm install後は`PATH`上のcommand名とexpanded development surfaceを登録する。
 
 ```sh
-codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
-claude mcp add --scope user aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
-codex mcp get aishell
+aishell-setup --ai claude,codex,grok,cursor
+aishell-setup --check
 ```
 
 解除:
@@ -166,8 +163,8 @@ full profileにはfile一覧・read、SHA-256競合検出付きatomic update、c
 
 ## 現在の制限
 
-- stdio serverは1 requestずつ処理する。
-- MCP cancellationと並列run pollingは未実装。
+- stdio requestは復旧操作・読み取り・実行の3系統で処理する。読み取りと復旧操作は長時間の実行中も応答するが、実行系requestは直列化する。
+- MCPの`notifications/cancelled`を受け付ける。管理対象processの明示的な停止は`run_observe`の`cancel`で行う。
 - timeout時は直接所有するprocess treeを終了するが、終了までに許可workerがopen-worldな副作用を起こし得る。
 - 初回workspace entryはbounded previewで、後続deltaはcursor pageになる。
 - Developer ID署名とnotarizationは未設定。
@@ -177,11 +174,10 @@ full profileにはfile一覧・read、SHA-256競合検出付きatomic update、c
 単独installの更新は初回と同じ公式npm経路を使い、新版の管理アプリを開く。
 
 ```sh
-npm install -g @quolu/aishell@latest
-aishell-open
+npm install -g @quolu/aishell@latest && aishell-setup
 ```
 
-未設定・停止中の復旧入口は`runtime_status`と`runtime_open_manager`である。
+停止中の復旧入口は`runtime_status`と`runtime_open_manager`である。
 工場consumerは専用`AISHELL_TOOL_PROFILE=factory` MCP surfaceから
 `factory_diagnostics`を呼ぶ。schemaとprivacy境界は
 [製品側diagnostics contract](https://github.com/kitepon/aishell/blob/main/docs/factory-diagnostics.md)が正である。
@@ -194,13 +190,28 @@ npm test
 npm run test:package
 git fetch origin
 npm run verify:release-commit
-npm publish --access public
+npm whoami
+npm publish --access public --browser=false
 ```
 
 release gateはdirty treeと既定branchへ未着地のcommitを拒否する。publish後は対応する
 GitHub Releaseを作り、`@quolu/aishell@latest`を再installしてMCP initializeと
 `factory_diagnostics`をsmokeする。公開済みversionの正本はGitHub Releasesである。
 
+### 公開認証と導入確認
+
+`npm whoami`が認証エラーを返した場合は、対話端末で`npm login --registry=https://registry.npmjs.org/ --browser=false`を実行し、表示された新しいURLを利用するブラウザで開いて認証する。公開コマンドも対話端末で実行し、出力をファイルへリダイレクトしない。公開用の認証URLが表示された場合は、ログインとは別に認証する。URLが失効した場合はコマンドを再実行して新しいURLを使う。
+
+npmのログインsessionは2時間で失効し、公開時には二要素認証が適用される（[npm公式説明](https://github.blog/changelog/2025-12-09-npm-classic-tokens-revoked-session-based-auth-and-cli-token-management-now-available/)）。公開の成功後に、registryとグローバルインストールを確認する。
+
+```sh
+npm view @quolu/aishell dist-tags.latest
+npm install -g @quolu/aishell@latest
+npm ls -g @quolu/aishell --depth=0
+```
+
+MCPを再接続し、`initialize`のversion、`runtime_status`、事前登録のない対象フォルダの検索と実行を確認する。工場診断は別processを`AISHELL_TOOL_PROFILE=factory`で起動し、`AISHELL_CAPABILITY_SET`を設定せずに確認する。
+
 ## 開発検証
 
 ```sh

package/README.md

@@ -22,19 +22,17 @@ diagnostics, recovery, updates, and releases.
 for cross-product wiring and compatibility; it does not control AIShell's
 internal operation.
 
-AIShell owns the OS-facing state below the model: allowed roots, file identity, filesystem reconciliation, directly launched processes, complete logs, and retained artifacts. The AI host remains responsible for reasoning, threads, compaction, sub-agents, and general-purpose terminal work.
+AIShell owns the OS-facing state below the model: file identity, filesystem reconciliation, directly launched processes, complete logs, and retained artifacts. The AI host remains responsible for reasoning, threads, compaction, sub-agents, and general-purpose terminal work.
 
 ## Try it in 30 seconds
 
 Requires an Apple Silicon Mac running macOS 15 or later.
 
 ```sh
-npm install -g @quolu/aishell
-aishell-open
-codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
+npm install -g @quolu/aishell && aishell-setup
 ```
 
-In the manager app, add the folders the AI may access. Start a new Codex task and try:
+フォルダの事前登録は不要です。新しいCodex taskで対象フォルダを指定して実行します。
 
 ```text
 Use workspace_snapshot for the initial workspace context. Run the focused tests with
@@ -50,15 +48,15 @@ The default profile exposes five high-density development tools plus two always-
 | `search_context` | Budgeted lexical context from a directly launched `rg` worker, scoped to a directory or one regular file; the expanded capability also provides cursor-bound semantic definition/reference/symbol queries without lexical fallback |
 | `run_check` | Direct process execution, primary diagnostics, and complete stdout/stderr artifacts |
 | `artifact_read` | Range, tail, and pattern-centered reads from retained artifacts; the expanded capability also searches and compares finalized managed-run artifacts |
-| `runtime_status` | Allowed-root, pause, worktree, and next-action state, including while paused or unconfigured |
-| `runtime_open_manager` | Open the manager app to add roots or resume AI operations |
+| `runtime_status` | Pause, relative-path base, and next-action state |
+| `runtime_open_manager` | Open the manager app to pause or resume AI operations |
 
 Set `AISHELL_CAPABILITY_SET=expanded-v1` on the MCP server process to opt in to the candidate surface. It exposes nine high-density development tools plus the two recovery controls. The added tools are `run_observe`, `workspace_wait`, `change_impact`, and `apply_change_set`; existing tools gain closed managed-run, artifact query, semantic search, project-profile, and Git branch/worktree modes. Cross-run artifact operations require an explicit project path and reject live, expired, legacy-unbound, or different-project evidence instead of silently falling back to partial logs.
 
 For Codex, register the expanded surface explicitly:
 
 ```sh
-codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
+aishell-setup --ai codex
 ```
 
 Unknown or empty `AISHELL_CAPABILITY_SET` and `AISHELL_TOOL_PROFILE` values fail startup with typed errors; they never fall back to another profile.
@@ -77,7 +75,7 @@ Typical stateless integrations repeatedly ask the model to rediscover workspace
 | Context | Bounded, cursor-based structured results | Unbounded or manually truncated stdout |
 | Execution | Executable URL, arguments, working directory, and lifecycle remain separate | A shell evaluates one command string |
 | Evidence | Complete stdout/stderr retained behind expiring handles | Evidence often disappears when the response is truncated |
-| Scope | Human-managed allowed roots and explicit stop state | Depends on the surrounding shell and host policy |
+| Scope | macOS access permissions and explicit stop state | Depends on the surrounding shell and host policy |
 
 AIShell is not a sandbox and does not make arbitrary code execution safe. Its process rails exist to preserve typed execution and observable lifecycle—not to stop renamed binaries or child processes launched by an allowed worker.
 
@@ -87,7 +85,7 @@ AIShell is not a sandbox and does not make arbitrary code execution safe. Its pr
 flowchart LR
     Host[AI host<br/>reasoning · threads · compaction] --> MCP[AIShellMCP<br/>MCP 2025-11-25]
     MCP --> Core[AIShellCore]
-    Core --> State[Allowed roots · file identity<br/>FSEvents + reconciliation]
+    Core --> State[File identity<br/>FSEvents + reconciliation]
     Core --> Process[Direct process lifecycle<br/>stdout · stderr · timeout]
     Core --> Evidence[Retained evidence<br/>artifacts · freshness]
     Process --> Workers[git · rg · compiler · tests]
@@ -99,17 +97,16 @@ flowchart LR
 
 ## Install from npm
 
-The global package adds `aishell-mcp` and `aishell-open` to `PATH`. `aishell-open` opens the bundled manager app through LaunchServices. The package runs no install script.
+global packageは`aishell-mcp`、`aishell-open`、`aishell-setup`を`PATH`へ追加する。npm install自体ではスクリプトも管理アプリも起動しない。
 
-Upgrading replaces the app bundle underneath any manager window left open, which breaks that window —
-it keeps holding a deleted bundle and silently loses every operation that opens a file panel. The
-window detects this itself and says so with a banner. When the new version sits at the same path, the
-banner restarts the window into it in one click; otherwise it asks for a quit and a fresh
-`aishell-open`. Verified against real `npm install -g` upgrades, not only simulated ones.
+対象AIのCLI（`claude`、`codex`、`grok`、Cursorの`agent`）を先に導入する。setupは各CLIからの読戻しも確認する。
+
+`aishell-setup`は導入済みのClaude Code・Codex・Grok Build・Cursorを検出し、管理アプリ準備、MCP登録、設定の読戻し、実際のMCP操作まで確認する。登録はbare `aishell-mcp`＋`AISHELL_CAPABILITY_SET=expanded-v1`。利用者のenv、PATH、他の設定を保持する。`--ai`で対象を指定でき、`--check`は設定やアプリ起動を変更せず診断する。Windows/LinuxとIntel Macは対象外。詳細は[製品単体の導入契約](https://github.com/kitepon/aishell/blob/main/docs/setup.md)を参照。
+
+更新後も同じ`aishell-setup`を実行する。旧管理アプリを正常終了して導入済みのアプリを開き、登録保持・読戻し・MCP実操作まで確認する。接続済みのMCPは、hostで再接続すると新版へ切り替わる。
 
 ```sh
-npm install -g @quolu/aishell
-aishell-open
+npm install -g @quolu/aishell && aishell-setup
 ```
 
 The current experimental build is not yet Developer ID signed or notarized.
@@ -126,16 +123,15 @@ open build/AIShell.app
 
 The MCP executable is bundled at `build/AIShell.app/Contents/Helpers/aishell-mcp`.
 
-After opening the app, use **Add Allowed Root** to select the folders AIShell may access. A Git worktree registered under an allowed repository is recognized automatically when both sides of the worktree metadata agree.
+フォルダ登録は不要です。絶対パスは指定した場所を、相対パスと省略時はMCP起動ディレクトリを基準にします。Git worktreeも直接指定できます。旧設定の許可フォルダ一覧は無視されます。
 
 ## Connect another AI host
 
 For a global npm installation, register the executable name from `PATH` and the expanded development surface:
 
 ```sh
-codex mcp add aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
-claude mcp add --scope user aishell --env AISHELL_CAPABILITY_SET=expanded-v1 -- aishell-mcp
-codex mcp get aishell
+aishell-setup --ai claude,codex,grok,cursor
+aishell-setup --check
 ```
 
 Remove the registration with:
@@ -167,8 +163,8 @@ The full profile includes file listing and reads, atomic SHA-256-guarded updates
 
 ## Current limitations
 
-- The stdio server handles one request at a time.
-- MCP cancellation and concurrent run polling are not implemented.
+- stdio requestは復旧操作・読み取り・実行の3系統で処理する。読み取りと復旧操作は長時間の実行中も応答するが、実行系requestは直列化する。
+- MCPの`notifications/cancelled`を受け付ける。管理対象processの明示的な停止は`run_observe`の`cancel`で行う。
 - A timeout terminates the directly owned process tree, but an allowed worker remains capable of open-world side effects before termination.
 - Initial workspace entries are a bounded preview; later deltas are cursor-paged.
 - Developer ID signing and notarization are not yet configured.
@@ -176,15 +172,14 @@ The full profile includes file listing and reads, atomic SHA-256-guarded updates
 ## Operations, updates, and releases
 
 Upgrade a standalone installation through the same official npm path used for
-initial installation, then open the newly installed manager:
+initial installation, then run the explicit setup:
 
 ```sh
-npm install -g @quolu/aishell@latest
-aishell-open
+npm install -g @quolu/aishell@latest && aishell-setup
 ```
 
-`runtime_status` and `runtime_open_manager` are the recovery entrypoints for an
-unconfigured or paused runtime. Factory consumers call `factory_diagnostics`
+`runtime_status` and `runtime_open_manager` are the recovery entrypoints for a
+paused runtime. Factory consumers call `factory_diagnostics`
 through the dedicated `AISHELL_TOOL_PROFILE=factory` MCP surface; its schema and
 privacy boundary are owned by [the product contract](https://github.com/kitepon/aishell/blob/main/docs/factory-diagnostics.md).
 
@@ -196,14 +191,29 @@ npm test
 npm run test:package
 git fetch origin
 npm run verify:release-commit
-npm publish --access public
+npm whoami
+npm publish --access public --browser=false
 ```
 
 The release gate rejects a dirty tree or a commit that has not landed on the
 default branch. After publishing, create the matching GitHub Release, reinstall
-`@quolu/aishell@latest`, and smoke MCP initialize plus `factory_diagnostics`.
+`@quolu/aishell@latest`, run `aishell-setup` and `aishell-setup --check`, and separately smoke `factory_diagnostics`.
 GitHub Releases are the public record of shipped versions.
 
+### 公開認証と導入確認
+
+`npm whoami`が認証エラーを返した場合は、対話端末で`npm login --registry=https://registry.npmjs.org/ --browser=false`を実行し、表示された新しいURLを利用するブラウザで開いて認証する。公開コマンドも対話端末で実行し、出力をファイルへリダイレクトしない。公開用の認証URLが表示された場合は、ログインとは別に認証する。URLが失効した場合はコマンドを再実行して新しいURLを使う。
+
+npmのログインsessionは2時間で失効し、公開時には二要素認証が適用される（[npm公式説明](https://github.blog/changelog/2025-12-09-npm-classic-tokens-revoked-session-based-auth-and-cli-token-management-now-available/)）。公開の成功後に、registryとグローバルインストールを確認する。
+
+```sh
+npm view @quolu/aishell dist-tags.latest
+npm install -g @quolu/aishell@latest
+npm ls -g @quolu/aishell --depth=0
+```
+
+MCPを再接続し、`initialize`のversion、`runtime_status`、事前登録のない対象フォルダの検索と実行を確認する。工場診断は別processを`AISHELL_TOOL_PROFILE=factory`で起動し、`AISHELL_CAPABILITY_SET`を設定せずに確認する。
+
 ## Development
 
 ```sh

package/dist/AIShell.app/Contents/Info.plist

@@ -17,9 +17,9 @@
     <key>CFBundlePackageType</key>
     <string>APPL</string>
     <key>CFBundleShortVersionString</key>
-    <string>0.4.12</string>
+    <string>0.6.0</string>
     <key>CFBundleVersion</key>
-    <string>19</string>
+    <string>21</string>
     <key>LSApplicationCategoryType</key>
     <string>public.app-category.utilities</string>
     <key>LSMinimumSystemVersion</key>

package/dist/AIShell.app/Contents/_CodeSignature/CodeResources

@@ -10,19 +10,19 @@
 		<dict>
 			<key>cdhash</key>
 			<data>
-			uzkv8b/DrKQPJzoVL8NtTyIqqek=
+			UTk6ryOelBpibaQkQByLjOitg6Q=
 			</data>
 			<key>requirement</key>
-			<string>cdhash H"bb392ff1bfc3aca40f273a152fc36d4f222aa9e9"</string>
+			<string>cdhash H"51393aaf239e941a626da424401c8b8ce8ad83a4"</string>
 		</dict>
 		<key>Helpers/aishell-run-supervisor</key>
 		<dict>
 			<key>cdhash</key>
 			<data>
-			0V5WoY6tV3Zqijm+8J8Zv0B6/Pw=
+			JDIaGpdJLctZbPoDtu5xZihSiRM=
 			</data>
 			<key>requirement</key>
-			<string>cdhash H"d15e56a18ead57766a8a39bef09f19bf407afcfc"</string>
+			<string>cdhash H"24321a1a97492dcb596cfa03b6ee716628528913"</string>
 		</dict>
 	</dict>
 	<key>rules</key>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/aishell",
-  "version": "0.4.12",
+  "version": "0.6.0",
   "description": "A native macOS state runtime with high-density MCP tools for AI development",
   "license": "Apache-2.0",
   "author": {
@@ -30,17 +30,25 @@
   ],
   "bin": {
     "aishell-mcp": "dist/AIShell.app/Contents/Helpers/aishell-mcp",
-    "aishell-open": "scripts/aishell-open.mjs"
+    "aishell-open": "scripts/aishell-open.mjs",
+    "aishell-setup": "scripts/aishell-setup.mjs"
   },
   "files": [
     "dist/AIShell.app",
     "scripts/aishell-open.mjs",
+    "scripts/aishell-setup.mjs",
+    "scripts/setup/hosts.mjs",
+    "scripts/setup/host-cli.mjs",
+    "scripts/setup/setup.mjs",
+    "scripts/setup/mcp-client.mjs",
+    "scripts/setup/toml-registration.mjs",
     "README.md"
   ],
   "scripts": {
     "build:npm": "node scripts/prepare-npm-release.mjs",
     "prepack": "npm run build:npm",
-    "test": "swift test && npm run test:release-gate && npm run test:repository-contract",
+    "test": "swift test && npm run test:setup && npm run test:release-gate && npm run test:repository-contract",
+    "test:setup": "node --test scripts/setup/*.test.mjs",
     "test:release-gate": "node --test scripts/verify-release-commit.test.mjs",
     "test:repository-contract": "node --test scripts/repository-contract.test.mjs",
     "test:package": "npm run build:npm && node scripts/verify-npm-package.mjs",
@@ -59,5 +67,9 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "smol-toml": "1.8.0",
+    "toml-eslint-parser": "0.10.0"
   }
 }

package/scripts/aishell-setup.mjs

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { setup } from './setup/setup.mjs';
+import { SetupError } from './setup/mcp-client.mjs';
+import { aiNames } from './setup/hosts.mjs';
+
+try {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && ['--help', '-h'].includes(args[0])) {
+    console.log('aishell-setup [--ai claude,codex,grok,cursor] [--check]\n初回・再実行・更新後に管理アプリ準備、MCP登録、読戻し、実操作を確認します。\n省略時は導入済みAIを検出。--checkは設定変更と管理アプリ起動を行いません。');
+  } else {
+    const options = {};
+    for (let index = 0; index < args.length; index++) {
+      if (args[index] === '--check' && options.check === undefined) options.check = true;
+      else if (args[index] === '--ai' && options.ais === undefined) {
+        options.ais = (args[++index] ?? '').split(',');
+        if (options.ais.some(ai => !aiNames.includes(ai)) || new Set(options.ais).size !== options.ais.length) throw new SetupError('AI_UNSUPPORTED', '--aiにはclaude,codex,grok,cursorを重複なしで指定してください。');
+      } else throw new SetupError('ARGUMENT_INVALID', '引数を確認してください。aishell-setup --helpで使い方を表示できます。');
+    }
+    console.log(JSON.stringify(await setup(options)));
+  }
+} catch (error) {
+  console.error(JSON.stringify({ ...(error.report ?? { schemaVersion: 'aishell.setup.v1', status: 'failed' }), error: { code: error.code ?? 'SETUP_FAILED', message: error instanceof SetupError ? error.message : 'setup中の入出力処理に失敗しました。設定fileの権限と導入状態を確認してください。' } }));
+  process.exitCode = 1;
+}

package/scripts/setup/host-cli.mjs

@@ -0,0 +1,63 @@
+import { execFileSync } from 'node:child_process';
+import { lstat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { backupFiles } from './hosts.mjs';
+import { SetupError } from './mcp-client.mjs';
+
+export function runHostCLI(command, args, options) {
+  try { return execFileSync(command, args, { ...options, encoding: 'utf8', timeout: 45000, stdio: ['ignore', 'pipe', 'pipe'] }); }
+  catch (error) {
+    throw new SetupError(error.code === 'ENOENT' ? 'AI_CLI_NOT_FOUND' : 'AI_VERIFICATION_FAILED', `${command}によるMCP確認に失敗しました。AI本体の導入・接続・承認状態を確認してください。`);
+  }
+}
+
+async function present(file) {
+  try {
+    const info = await lstat(file);
+    if (!info.isFile()) throw new SetupError('CONFIG_PATH_UNSUPPORTED', 'Cursorの設定は通常fileである必要があります。');
+    return true;
+  } catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+}
+
+async function backupCursor(spec, backupDirectory) {
+  const files = [];
+  const config = path.join(spec.base, 'cli-config.json');
+  if (await present(config)) files.push(config);
+  const directory = path.join(spec.base, 'projects');
+  let entries;
+  try { entries = await readdir(directory, { withFileTypes: true }); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; entries = []; }
+  for (const entry of entries) if (entry.isDirectory()) {
+    const file = path.join(directory, entry.name, 'mcp-approvals.json');
+    if (await present(file)) files.push(file);
+  }
+  await backupFiles(files, backupDirectory, 'cursor-approval');
+}
+
+export async function verifyHostCLI(spec, registration, { check, env, cwd, backupDirectory, run = runHostCLI }) {
+  const options = { env: { ...env, NO_COLOR: '1', TERM: 'dumb' }, cwd };
+  let actual;
+  if (spec.ai === 'codex') {
+    const value = JSON.parse(run('codex', ['mcp', 'get', 'aishell', '--json'], options));
+    if (value.enabled !== true || value.transport?.type !== 'stdio') throw new SetupError('AI_REGISTRATION_MISMATCH', 'Codexの実効登録が有効なstdioではありません。');
+    actual = value.transport;
+  } else if (spec.ai === 'grok') {
+    const values = JSON.parse(run('grok', ['mcp', 'list', '--json'], options)).filter(item => item.name === 'aishell');
+    if (values.length !== 1 || values[0].enabled !== true) throw new SetupError('AI_REGISTRATION_MISMATCH', 'Grokの実効登録を一意に確認できません。');
+    actual = values[0];
+  } else if (spec.ai === 'claude') {
+    const output = run('claude', ['mcp', 'get', 'aishell'], options);
+    if (!/^\s*Command: aishell-mcp\s*$/m.test(output) || !output.includes('expanded-v1') || !/Status:.*Connected/.test(output)) throw new SetupError('AI_REGISTRATION_MISMATCH', 'Claudeの実効登録またはMCP接続が一致しません。');
+  } else {
+    if (!check) {
+      await backupCursor(spec, backupDirectory);
+      run('agent', ['mcp', 'enable', 'aishell'], options);
+    } else if (!await present(path.join(spec.base, 'cli-config.json'))) {
+      throw new SetupError('AI_VERIFICATION_FAILED', 'Cursor CLIが未準備です。aishell-setupを実行してください。');
+    }
+    const output = run('agent', ['mcp', 'list-tools', 'aishell'], options);
+    if (!['runtime_status', 'workspace_snapshot', 'apply_change_set'].every(name => output.includes(name))) throw new SetupError('AI_REGISTRATION_MISMATCH', 'Cursorからexpanded-v1のtoolを確認できません。');
+  }
+  if (actual && (actual.command !== registration.command || (actual.args ?? []).length !== 0 || actual.env?.AISHELL_CAPABILITY_SET !== 'expanded-v1')) throw new SetupError('AI_REGISTRATION_MISMATCH', `${spec.ai}の実効登録が製品登録と一致しません。project設定の上書きも確認してください。`);
+  return { hostVerified: true };
+}

package/scripts/setup/hosts.mjs

@@ -0,0 +1,115 @@
+import { readFile, lstat, mkdir, writeFile, rename, rm } from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { parse } from 'smol-toml';
+import { replaceTOMLRegistration, replaceTopLevelValue } from './toml-registration.mjs';
+import { SetupError } from './mcp-client.mjs';
+
+export const aiNames = ['claude', 'codex', 'grok', 'cursor'];
+export function hostSpec(ai, home, env) {
+  if (ai === 'cursor' && env.CURSOR_HOME && path.resolve(env.CURSOR_HOME) !== path.join(home, '.cursor')) {
+    throw new SetupError('AI_CONFIG_LOCATION_UNSUPPORTED', 'CursorはCURSOR_HOMEを読みません。通常の~/.cursorを使う環境でsetupを実行してください。');
+  }
+  const bases = {
+    claude: env.CLAUDE_CONFIG_DIR || path.join(home, '.claude'),
+    codex: env.CODEX_HOME || path.join(home, '.codex'),
+    grok: env.GROK_HOME || path.join(home, '.grok'),
+    cursor: path.join(home, '.cursor'),
+  };
+  if (!aiNames.includes(ai)) throw new SetupError('AI_UNSUPPORTED', `未対応のAIです: ${ai}`);
+  const base = path.resolve(bases[ai]);
+  return {
+    ai, base,
+    file: ai === 'claude' ? (env.CLAUDE_CONFIG_DIR ? path.join(base, '.claude.json') : path.join(home, '.claude.json'))
+      : path.join(base, ai === 'cursor' ? 'mcp.json' : 'config.toml'),
+    format: ['codex', 'grok'].includes(ai) ? 'toml' : 'json',
+    key: ['codex', 'grok'].includes(ai) ? 'mcp_servers' : 'mcpServers',
+  };
+}
+
+function object(value, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new SetupError('CONFIG_INVALID', `${label}はobjectである必要があります。`);
+  return value;
+}
+
+export function canonicalRegistration(current = {}, ai) {
+  object(current, 'AIShell設定');
+  const next = { ...current, command: 'aishell-mcp', args: [], env: { ...object(current.env ?? {}, 'AIShell env'), AISHELL_CAPABILITY_SET: 'expanded-v1' } };
+  if (Object.values(next.env).some(value => typeof value !== 'string')) throw new SetupError('CONFIG_INVALID', 'AIShell envの値は文字列である必要があります。');
+  // transportの旧値はAIShellが所有する。利用者のtimeout・許可tool等は保持する。
+  for (const key of ['url', 'http_headers', 'env_http_headers', 'bearer_token_env_var', 'headers']) delete next[key];
+  if (ai === 'claude' || ai === 'cursor') next.type = 'stdio';
+  else { delete next.type; next.enabled = true; }
+  if ('enabled' in next) next.enabled = true;
+  if ('disabled' in next) next.disabled = false;
+  return next;
+}
+
+export function decode(text, spec) {
+  try { return object(text.trim() ? (spec.format === 'toml' ? parse(text) : JSON.parse(text)) : {}, 'AI設定'); }
+  catch (error) {
+    if (error instanceof SetupError) throw error;
+    throw new SetupError('CONFIG_INVALID', `${spec.ai}の設定を解析できません。`);
+  }
+}
+
+export async function readHost(spec) {
+  let info;
+  try { info = await lstat(spec.file); }
+  catch (error) { if (error.code !== 'ENOENT') throw error; }
+  if (info && !info.isFile()) throw new SetupError('CONFIG_PATH_UNSUPPORTED', `${spec.ai}の設定は通常fileである必要があります。`);
+  const text = info ? await readFile(spec.file, 'utf8') : '';
+  const data = decode(text, spec);
+  const servers = object(data[spec.key] ?? {}, `${spec.ai} MCP設定`);
+  return { text, data, info, registration: servers.aishell };
+}
+
+export async function planHost(spec) {
+  const before = await readHost(spec);
+  const registration = canonicalRegistration(before.registration, spec.ai);
+  const data = { ...before.data, [spec.key]: { ...before.data[spec.key], aishell: registration } };
+  if (spec.ai === 'grok' && data.disabled_mcp_servers !== undefined) {
+    if (!Array.isArray(data.disabled_mcp_servers) || data.disabled_mcp_servers.some(name => typeof name !== 'string')) throw new SetupError('CONFIG_INVALID', 'Grokのdisabled_mcp_serversは文字列配列である必要があります。');
+    data.disabled_mcp_servers = data.disabled_mcp_servers.filter(name => name !== 'aishell');
+  }
+  const changed = !isDeepStrictEqual(before.data, data);
+  let text;
+  try { text = changed ? (spec.format === 'toml' ? replaceTOMLRegistration(before.text, registration) : JSON.stringify(data, null, 2) + '\n') : before.text; }
+  catch { throw new SetupError('CONFIG_INVALID', `${spec.ai}の設定形式を保持して更新できません。`); }
+  if (!isDeepStrictEqual(before.data.disabled_mcp_servers, data.disabled_mcp_servers)) text = replaceTopLevelValue(text, 'disabled_mcp_servers', data.disabled_mcp_servers);
+  // serializeで他の設定値が変わる形式は、書込み前に明示拒否する。
+  if (!isDeepStrictEqual(decode(text, spec), data)) throw new SetupError('CONFIG_SERIALIZATION_LOSS', `${spec.ai}の設定値を保持できません。`);
+  return { spec, before, text, data, registration, changed };
+}
+
+export async function backupFiles(files, backupDirectory, label) {
+  if (!files.length) return;
+  await mkdir(backupDirectory, { recursive: true, mode: 0o700 });
+  // 設定の原本をtarへ保存してから更新する。秘密を含み得るため作成時から0600に限定する。
+  const archive = path.join(backupDirectory, `${label}-${randomUUID()}.tar`);
+  await writeFile(archive, '', { flag: 'wx', mode: 0o600 });
+  execFileSync('/usr/bin/tar', ['-cf', archive, '-C', '/', ...files.map(file => file.slice(1))], { stdio: 'pipe' });
+}
+
+export async function writeHost(plan, backupDirectory) {
+  if (!plan.changed) return;
+  const { spec, before, text } = plan;
+  if (before.info) await backupFiles([spec.file], backupDirectory, spec.ai);
+  await mkdir(path.dirname(spec.file), { recursive: true, mode: 0o700 });
+  const temporary = path.join(path.dirname(spec.file), `.aishell-${randomUUID()}.tmp`);
+  try {
+    await writeFile(temporary, text, { flag: 'wx', mode: before.info ? before.info.mode & 0o777 : 0o600 });
+    const current = await readHost(spec);
+    if (current.text !== before.text || Boolean(current.info) !== Boolean(before.info)) throw new SetupError('CONFIG_CHANGED', `${spec.ai}の設定が同時に更新されました。再実行してください。`);
+    await rename(temporary, spec.file);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+export async function verifyHost(plan) {
+  const actual = await readHost(plan.spec);
+  if (!isDeepStrictEqual(actual.registration, plan.registration)) throw new SetupError('REGISTRATION_MISMATCH', `${plan.spec.ai}の登録読戻しが一致しません。`);
+  if (!isDeepStrictEqual(actual.data, plan.data)) throw new SetupError('CONFIG_CHANGED', `${plan.spec.ai}の他設定が変更されました。`);
+  return actual.registration;
+}

package/scripts/setup/mcp-client.mjs

@@ -0,0 +1,64 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+
+export class SetupError extends Error {
+  constructor(code, message) { super(message); this.code = code; }
+}
+
+// 読戻した登録をそのまま起動する。env値と子process出力は診断へ転載しない。
+export async function withMCP(registration, operation, { cwd, env = process.env, timeout = 30000 } = {}) {
+  const child = spawn(registration.command, registration.args ?? [], {
+    cwd, env: { ...env, ...registration.env }, stdio: ['pipe', 'pipe', 'pipe'],
+  });
+  const pending = new Map();
+  let sequence = 0;
+  let failure;
+  const fail = (error) => {
+    failure = error;
+    for (const item of pending.values()) item.reject(error);
+    pending.clear();
+  };
+  child.on('error', () => fail(new SetupError('MCP_START_FAILED', '登録されたMCPを起動できません。PATHと導入状態を確認してください。')));
+  child.stdin.on('error', () => fail(new SetupError('MCP_CLOSED', 'MCPの入力が閉じました。')));
+  child.stderr.resume();
+  const closed = new Promise(resolve => child.once('close', resolve));
+  child.once('close', () => fail(new SetupError('MCP_CLOSED', 'MCPが応答完了前に終了しました。')));
+  const lines = createInterface({ input: child.stdout });
+  lines.on('line', line => {
+    let response;
+    try { response = JSON.parse(line); }
+    catch { fail(new SetupError('MCP_PROTOCOL_INVALID', 'MCPがJSON以外を返しました。')); return; }
+    const item = pending.get(response.id);
+    if (!item) return;
+    pending.delete(response.id);
+    if (response.error || response.result?.isError) item.reject(new SetupError('MCP_OPERATION_FAILED', `${item.method}が失敗しました。`));
+    else item.resolve(response.result);
+  });
+  const timer = setTimeout(() => {
+    fail(new SetupError('MCP_TIMEOUT', 'MCP応答が制限時間を超えました。'));
+    child.kill('SIGTERM');
+  }, timeout);
+  const request = (method, params) => new Promise((resolve, reject) => {
+    if (failure) { reject(failure); return; }
+    const id = ++sequence;
+    pending.set(id, { resolve, reject, method });
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id, method, params }) + '\n');
+  });
+  try {
+    const initialized = await request('initialize', {
+      protocolVersion: '2025-11-25', capabilities: {},
+      clientInfo: { name: 'aishell-setup', version: '1' },
+    });
+    if (initialized?.protocolVersion !== '2025-11-25') throw new SetupError('MCP_PROTOCOL_INVALID', 'MCP protocol versionが一致しません。');
+    child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method: 'notifications/initialized' }) + '\n');
+    return await operation({ initialized, request, call: (name, args = {}) => request('tools/call', { name, arguments: args }) });
+  } finally {
+    clearTimeout(timer);
+    child.stdin.end();
+    const killTimer = setTimeout(() => child.kill('SIGKILL'), 1000);
+    child.kill('SIGTERM');
+    await closed;
+    clearTimeout(killTimer);
+    lines.close();
+  }
+}

package/scripts/setup/setup.mjs

@@ -0,0 +1,104 @@
+import { access, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { execFileSync } from 'node:child_process';
+import { homedir, tmpdir } from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { aiNames, hostSpec, planHost, verifyHost, writeHost } from './hosts.mjs';
+import { SetupError, withMCP } from './mcp-client.mjs';
+import { verifyHostCLI } from './host-cli.mjs';
+
+export const packageDirectory = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../..');
+
+export function supportedPlatform(platform, arch, macVersion) {
+  if (platform !== 'darwin' || arch !== 'arm64' || !/^\d+(\.\d+)*$/.test(macVersion ?? '') || Number(macVersion.split('.')[0]) < 15) {
+    throw new SetupError('PLATFORM_UNSUPPORTED', '対応環境はmacOS 15以降のApple Silicon（arm64）だけです。設定・processは作成しません。');
+  }
+}
+
+async function exists(file, mode) {
+  try { await access(file, mode); return true; }
+  catch (error) { if (['ENOENT', 'EACCES'].includes(error.code)) return false; throw error; }
+}
+
+async function installed(spec, env) {
+  if (await exists(spec.base) || await exists(spec.file)) return true;
+  const commands = spec.ai === 'cursor' ? ['cursor', 'agent'] : [spec.ai];
+  for (const directory of (env.PATH ?? '').split(path.delimiter)) {
+    if (!directory) continue;
+    for (const command of commands) if (await exists(path.join(directory, command), constants.X_OK)) return true;
+  }
+  return false;
+}
+
+export function prepareManager() {
+  const binary = path.join(packageDirectory, 'dist/AIShell.app/Contents/Helpers/aishell-mcp');
+  let value;
+  try { value = JSON.parse(execFileSync(binary, ['--prepare-manager'], { encoding: 'utf8', timeout: 30000, stdio: ['ignore', 'pipe', 'pipe'] })); }
+  catch { throw new SetupError('MANAGER_PREPARATION_FAILED', '管理アプリの準備に失敗しました。aishell-openで状態を確認してください。'); }
+  if (!Number.isInteger(value.processIdentifier) || value.processIdentifier <= 0) throw new SetupError('MANAGER_PREPARATION_FAILED', '管理アプリの実行確認が返りませんでした。');
+  return { ready: true, processIdentifier: value.processIdentifier };
+}
+
+export async function smoke(registration, expectedVersion, { env = process.env } = {}) {
+  const directory = await mkdtemp(path.join(tmpdir(), 'aishell-setup-smoke-'));
+  try {
+    await writeFile(path.join(directory, 'probe.txt'), 'AIShell setup smoke\n');
+    return await withMCP(registration, async ({ initialized, request, call }) => {
+      if (initialized?.serverInfo?.version !== expectedVersion) throw new SetupError('MCP_VERSION_MISMATCH', '登録先のMCP版が導入済みpackageと一致しません。PATHを確認してください。');
+      const list = await request('tools/list', {});
+      if (!list?.tools?.some(tool => tool.name === 'workspace_snapshot') || !list.tools.some(tool => tool.name === 'apply_change_set')) throw new SetupError('MCP_CAPABILITY_MISMATCH', 'expanded-v1の開発toolを利用できません。AISHELL_TOOL_PROFILEなどのenvを確認してください。');
+      const status = (await call('runtime_status')).structuredContent;
+      if (status?.isPaused !== false) throw new SetupError('RUNTIME_NOT_READY', 'AIShellが停止中か、状態を確認できません。管理アプリで再開してから再実行してください。');
+      const snapshot = (await call('workspace_snapshot', { path: directory, context_budget: 0, entry_limit: 10, project_profile: { mode: 'none' } })).structuredContent;
+      if (snapshot?.freshness !== 'fresh' || !snapshot.entries?.some(entry => entry.path === 'probe.txt' || entry.relativePath === 'probe.txt' || entry.path === path.join(directory, 'probe.txt'))) throw new SetupError('MCP_SMOKE_FAILED', '未登録フォルダの実fileをMCPで確認できません。');
+      return { version: initialized.serverInfo.version, toolCount: list.tools.length, operation: 'workspace_snapshot', ready: true };
+    }, { cwd: directory, env });
+  } finally { await rm(directory, { recursive: true, force: true }); }
+}
+
+export async function setup(options = {}, dependencies = {}) {
+  const env = dependencies.env ?? process.env;
+  const platform = dependencies.platform ?? process.platform;
+  const arch = dependencies.arch ?? process.arch;
+  // 対応外OSではmacOS commandを含めて一切の準備処理を実行しない。
+  const macVersion = platform === 'darwin' ? (dependencies.macVersion ?? execFileSync('/usr/bin/sw_vers', ['-productVersion'], { encoding: 'utf8' }).trim()) : null;
+  supportedPlatform(platform, arch, macVersion);
+  const home = dependencies.home ?? homedir();
+  const chosen = options.ais ? options.ais.map(ai => hostSpec(ai, home, env)) : [];
+  if (!options.ais) for (const ai of aiNames) {
+    const spec = hostSpec(ai, home, { ...env, CURSOR_HOME: undefined });
+    if (await installed(spec, env)) chosen.push(hostSpec(ai, home, env));
+  }
+  if (!chosen.length) throw new SetupError('AI_NOT_FOUND', '対応AIを検出できません。対象を--ai claude,codex,grok,cursorで指定してください。');
+  const report = { schemaVersion: 'aishell.setup.v1', mode: options.check ? 'diagnose' : 'setup', platform: { os: platform, arch, version: macVersion }, manager: null, hosts: [], skipped: aiNames.filter(ai => !chosen.some(spec => spec.ai === ai)) };
+  const version = dependencies.version ?? JSON.parse(await (await import('node:fs/promises')).readFile(path.join(packageDirectory, 'package.json'), 'utf8')).version;
+  const backupDirectory = path.join(home, 'Library/Application Support/AIShell/setup-backups');
+  let stage = 'preflight';
+  try {
+    // 全対象を先に解析する。壊れた設定があるままappや別AIを更新しない。
+    const plans = [];
+    for (const spec of chosen) plans.push(await planHost(spec));
+    if (!options.check) {
+      stage = 'prepare';
+      report.manager = await (dependencies.prepare ?? prepareManager)();
+    }
+    for (const plan of plans) {
+      stage = `register:${plan.spec.ai}`;
+      if (!options.check) await (dependencies.write ?? writeHost)(plan, backupDirectory);
+      else if (plan.changed) throw new SetupError('REGISTRATION_MISMATCH', `${plan.spec.ai}のAIShell登録が正規契約と一致しません。setupを実行してください。`);
+      const registration = await verifyHost(plan);
+      const host = { ai: plan.spec.ai, registration: options.check ? 'verified' : plan.changed ? 'updated' : 'unchanged', ready: false };
+      report.hosts.push(host);
+      stage = `host:${plan.spec.ai}`;
+      Object.assign(host, await (dependencies.verifyCLI ?? verifyHostCLI)(plan.spec, registration, { check: options.check, env, cwd: dependencies.cwd ?? process.cwd(), backupDirectory }));
+      stage = `smoke:${plan.spec.ai}`;
+      const result = await (dependencies.smoke ?? smoke)(registration, version, { env });
+      Object.assign(host, result);
+    }
+    return { ...report, status: 'ready' };
+  } catch (error) {
+    error.report = { ...report, status: 'failed', stage };
+    throw error;
+  }
+}

package/scripts/setup/toml-registration.mjs

@@ -0,0 +1,53 @@
+import { parseForESLint } from 'toml-eslint-parser';
+import { stringify } from 'smol-toml';
+
+const target = ['mcp_servers', 'aishell'];
+const prefix = (left, right) => left.every((key, index) => right[index] === key);
+const keyPath = node => node.keys.map(key => key.type === 'TOMLBare' ? key.name : key.value);
+
+export function replaceTopLevelValue(text, key, value) {
+  const { ast } = parseForESLint(text);
+  const node = ast.body[0].body.find(node => node.type === 'TOMLKeyValue' && keyPath(node.key).length === 1 && keyPath(node.key)[0] === key);
+  if (!node) throw new Error('トップレベルの設定値を特定できません。');
+  return text.slice(0, node.value.range[0]) + inline(value) + text.slice(node.value.range[1]);
+}
+
+function inline(value) {
+  if (Array.isArray(value)) return `[${value.map(inline).join(', ')}]`;
+  if (value && typeof value === 'object' && !(value instanceof Date)) return `{ ${Object.entries(value).map(([key, item]) => `${JSON.stringify(key)} = ${inline(item)}`).join(', ')} }`;
+  return stringify({ value }).slice('value = '.length).trim();
+}
+
+// 構文木の範囲だけを変更し、別server、コメント、float/date表記をそのまま残す。
+// 複数行文字列にある偽のtable headerを正規表現で誤認しない。
+export function replaceTOMLRegistration(text, registration) {
+  const { ast } = parseForESLint(text);
+  const edits = [];
+  let replaced = false;
+  function visitKeyValue(node, base) {
+    const keys = [...base, ...keyPath(node.key)];
+    if (keys.length === target.length && prefix(target, keys)) {
+      edits.push({ range: node.value.range, text: inline(registration) });
+      replaced = true;
+    } else if (prefix(target, keys)) {
+      edits.push({ range: node.range, text: '' });
+    } else if (prefix(keys, target) && node.value.type === 'TOMLInlineTable') {
+      for (const child of node.value.body) visitKeyValue(child, keys);
+      if (!replaced) {
+        const at = node.value.range[1] - 1;
+        edits.push({ range: [at, at], text: `${node.value.body.length ? ', ' : ''}${JSON.stringify(target.at(-1))} = ${inline(registration)}` });
+        replaced = true;
+      }
+    }
+  }
+  for (const node of ast.body[0].body) {
+    if (node.type === 'TOMLTable') {
+      if (prefix(target, node.resolvedKey)) edits.push({ range: node.range, text: '' });
+      else for (const child of node.body) visitKeyValue(child, node.resolvedKey);
+    } else visitKeyValue(node, []);
+  }
+  let result = text;
+  for (const edit of edits.sort((a, b) => b.range[0] - a.range[0])) result = result.slice(0, edit.range[0]) + edit.text + result.slice(edit.range[1]);
+  if (!replaced) result += `\n${stringify({ mcp_servers: { aishell: registration } })}`;
+  return result;
+}