@quolu/aishell 0.5.0 → 0.6.0

package/README.ja.md

@@ -28,9 +28,7 @@ AIShellはfile identity、filesystem照合state、直接起動したprocess、
 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
 ```
 
 フォルダの事前登録は不要。新しいCodex taskで対象フォルダを指定して実行する。
@@ -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停止し、
@@ -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前である。
@@ -134,9 +132,8 @@ MCP実行ファイルは`build/AIShell.app/Contents/Helpers/aishell-mcp`へ同
 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,8 +174,7 @@ 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`である。
@@ -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

@@ -29,9 +29,7 @@ AIShell owns the OS-facing state below the model: file identity, filesystem reco
 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
 ```
 
 フォルダの事前登録は不要です。新しいCodex taskで対象フォルダを指定して実行します。
@@ -58,7 +56,7 @@ Set `AISHELL_CAPABILITY_SET=expanded-v1` on the MCP server process to opt in to
 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.
@@ -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.
@@ -133,9 +130,8 @@ The MCP executable is bundled at `build/AIShell.app/Contents/Helpers/aishell-mcp
 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,14 +172,13 @@ 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
+`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.5.0</string>
+    <string>0.6.0</string>
     <key>CFBundleVersion</key>
-    <string>20</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>
-			YtRYGFYE+Yh3gPk+NxMYVUyUi6M=
+			UTk6ryOelBpibaQkQByLjOitg6Q=
 			</data>
 			<key>requirement</key>
-			<string>cdhash H"62d458185604f9887780f93e371318554c948ba3"</string>
+			<string>cdhash H"51393aaf239e941a626da424401c8b8ce8ad83a4"</string>
 		</dict>
 		<key>Helpers/aishell-run-supervisor</key>
 		<dict>
 			<key>cdhash</key>
 			<data>
-			TcWgD4ePO0zxS53P4eI9iGT41LE=
+			JDIaGpdJLctZbPoDtu5xZihSiRM=
 			</data>
 			<key>requirement</key>
-			<string>cdhash H"4dc5a00f878f3b4cf14b9dcfe1e23d8864f8d4b1"</string>
+			<string>cdhash H"24321a1a97492dcb596cfa03b6ee716628528913"</string>
 		</dict>
 	</dict>
 	<key>rules</key>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@quolu/aishell",
-  "version": "0.5.0",
+  "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;
+}