akari-video 0.1.23 → 0.1.25

package/README.md

@@ -52,6 +52,20 @@ DL・sha256 検証・適用まで実行。それ以外（npm グローバル / g
 `packages/asset-resolver` の CLI への薄い委譲で、カタログ合成・entitlements 判定・
 sha256 検証・fail-closed は resolver 側の責務のまま。`src/assets-command.mjs`）。
 
+### Chrome の導入
+
+動画の書き出しに使う Chrome for Testing は、次のコマンドで導入できる。
+
+```sh
+akari chrome install
+akari chrome install --cache-dir /path/to/cache
+akari chrome install --build-id 150.0.7339.16
+```
+
+保存先の既定は `~/.cache/puppeteer`。`--cache-dir` で保存先、`--build-id` で導入する
+buildId を指定できる。実行環境から `@puppeteer/browsers` を解決できる必要があり、
+AKARI Video アプリの配布物には必要なモジュールが同梱されている。
+
 `akari` に渡した引数はそのまま `opencode` に転送する（例: `akari --continue` は
 `opencode --continue` を起動する）。
 

package/bin/akari.mjs

@@ -11,6 +11,8 @@ import { runCapabilityCommand } from '../src/capability-command.mjs';
 import { runStoreCommand } from '../src/store-command.mjs';
 import { runAssetsCommand } from '../src/assets-command.mjs';
 import { runMigrateCommand } from '../src/migrate-command.mjs';
+import { runDoctorCommand } from '../src/doctor-command.mjs';
+import { resolveRuntimePaths } from '../src/runtime-diagnostics.mjs';
 import { maybeApplyPendingUpdateOnLaunch, resolveInstalledVersionInfo } from '../src/update-check.mjs';
 import { describeCliHelp, describeInstalledVersions } from '../src/messages.mjs';
 
@@ -21,7 +23,7 @@ async function printVersion() {
   const versionInfo = resolveInstalledVersionInfo({ env: process.env });
   // 1 行目は update / rollback の既存機械観測契約として CLI 版だけを維持する。
   console.log(`v${versionInfo.cliVersion}`);
-  for (const line of describeInstalledVersions(versionInfo)) {
+  for (const line of describeInstalledVersions(versionInfo, resolveRuntimePaths({ env: process.env }))) {
     console.log(line);
   }
   return { exitCode: 0 };
@@ -47,13 +49,14 @@ async function printCliHelp() {
 // 読み直せば新版の内容を観測できる — 同一 argv での re-exec はしない設計判断
 // （理由は report.md 参照）)。失敗は他の起動時副作用と同じく握りつぶし、
 // claude/opencode 起動やサブコマンド実行を止めない。
+const argv = process.argv.slice(2);
+const doctorJson = argv[0] === 'doctor' && argv.includes('--json');
 try {
-  maybeApplyPendingUpdateOnLaunch({ env: process.env, log: (line) => console.log(line) });
+  maybeApplyPendingUpdateOnLaunch({ env: process.env, log: doctorJson ? () => {} : (line) => console.log(line) });
 } catch (error) {
   console.error(`自動更新の適用確認でエラーが発生しました（続行します）: ${error instanceof Error ? error.message : String(error)}`);
 }
 
-const argv = process.argv.slice(2);
 // `akari update` / `akari init` / `akari new` / `akari narration` / `akari internal` /
 // `akari sounds` / `akari status` / `akari accept` / `akari capability` / `akari store` /
 // `akari assets` は claude へ転送せず、専用のサブコマンドとして扱う（契約 §4-1 /
@@ -62,6 +65,7 @@ const argv = process.argv.slice(2);
 // それ以外の引数はすべて従来どおり claude へ転送する。
 const invoke = (argv[0] === '--version' || argv[0] === '-v') ? printVersion()
   : (argv[0] === '--help' || argv[0] === '-h') ? printCliHelp()
+  : argv[0] === 'doctor' ? runDoctorCommand(argv.slice(1))
   : argv[0] === 'update' ? runUpdateCommand(argv.slice(1))
   : argv[0] === 'init' ? runInitCommand(argv.slice(1))
   : argv[0] === 'new' ? runNewCommand(argv.slice(1))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "akari-video",
-  "version": "0.1.23",
+  "version": "0.1.25",
   "description": "AKARI Video launcher CLI — start an AI-edited video project from any directory: scaffold, connection check, then hand over to Claude Code (or opencode). AKARI Video を opencode や Claude Code で、どのディレクトリからでも始めるための `akari` ランチャー CLI。接続確認（doctor）→ 未セットアップならプロジェクト雛形を作成 → AI エージェントを起動する。外部 npm 依存ゼロ（Node.js 組み込みモジュールのみ）。",
   "type": "module",
   "bin": {

package/src/chrome-command.mjs

@@ -0,0 +1,100 @@
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const usage = [
+  '使い方: akari chrome install [options]',
+  '',
+  'オプション:',
+  '  --cache-dir <dir>  Chrome の保存先（既定: ~/.cache/puppeteer）',
+  '  --build-id <id>    導入する Chrome の buildId（既定: stable の最新版）',
+  '  -h, --help         このヘルプを表示',
+].join('\n');
+
+class PublicError extends Error {
+  constructor(message, exitCode = 1) {
+    super(message);
+    this.exitCode = exitCode;
+  }
+}
+
+export function resolveChromeCacheDir(homeDirectory = homedir(), cacheDir) {
+  return cacheDir ? resolve(cacheDir) : join(homeDirectory, '.cache', 'puppeteer');
+}
+
+function parseInstallArguments(argv, homeDirectory) {
+  const parsed = {
+    cacheDir: resolveChromeCacheDir(homeDirectory),
+    buildId: undefined,
+  };
+  for (let index = 1; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument !== '--cache-dir' && argument !== '--build-id') {
+      throw new PublicError(`不明な引数です: ${argument}`, 2);
+    }
+    const value = argv[index + 1];
+    if (value === undefined || value.startsWith('--')) {
+      throw new PublicError(`${argument} の値がありません`, 2);
+    }
+    index += 1;
+    if (argument === '--cache-dir') parsed.cacheDir = resolveChromeCacheDir(homeDirectory, value);
+    else parsed.buildId = value;
+  }
+  return parsed;
+}
+
+export async function runChromeCommand(argv, options = {}) {
+  const log = options.log ?? ((line) => console.log(line));
+  const error = options.error ?? ((line) => console.error(line));
+  const loadBrowsers = options.loadBrowsers ?? (() => import('@puppeteer/browsers'));
+  const homeDirectory = options.homeDirectory ?? homedir();
+
+  if (argv.length === 0 || argv[0] === '--help' || argv[0] === '-h'
+      || (argv[0] === 'install' && (argv.includes('--help') || argv.includes('-h')))) {
+    log(usage);
+    return { exitCode: 0 };
+  }
+  if (argv[0] !== 'install') {
+    error(`不明なサブコマンドです: ${argv[0]}\n${usage}`);
+    return { exitCode: 2 };
+  }
+
+  let parsed;
+  try {
+    parsed = parseInstallArguments(argv, homeDirectory);
+  } catch (cause) {
+    error(`${cause instanceof Error ? cause.message : String(cause)}\n${usage}`);
+    return { exitCode: cause instanceof PublicError ? cause.exitCode : 1 };
+  }
+
+  let browsers;
+  try {
+    browsers = await loadBrowsers();
+  } catch (cause) {
+    error([
+      `@puppeteer/browsers を読み込めないため Chrome を導入できません: ${cause instanceof Error ? cause.message : String(cause)}`,
+      'システムの node がある場合は `npx puppeteer browsers install chrome` でも導入できます。',
+    ].join('\n'));
+    return { exitCode: 1 };
+  }
+
+  try {
+    const platform = browsers.detectBrowserPlatform();
+    const buildId = parsed.buildId
+      ?? await browsers.resolveBuildId('chrome', platform, 'stable');
+    const installed = await browsers.install({
+      browser: 'chrome',
+      buildId,
+      cacheDir: parsed.cacheDir,
+      downloadProgressCallback: 'default',
+    });
+    if (typeof installed?.executablePath !== 'string' || installed.executablePath.length === 0) {
+      throw new Error('導入後の実行ファイルを特定できませんでした。');
+    }
+    log(`buildId: ${buildId}`);
+    log(`実行ファイル: ${resolve(installed.executablePath)}`);
+    return { exitCode: 0 };
+  } catch (cause) {
+    error(`Chrome の導入に失敗しました: ${cause instanceof Error ? cause.message : String(cause)}`);
+    return { exitCode: 1 };
+  }
+}

package/src/cli.mjs

@@ -4,7 +4,7 @@ import { pathToFileURL } from 'node:url';
 
 import { resolveLauncherAssets } from './repo-assets.mjs';
 import { detectProjectState } from './project-state.mjs';
-import { findClaudeExecutable, findOpencodeExecutable } from './path-lookup.mjs';
+import { findClaudeExecutable, findExecutable, findOpencodeExecutable } from './path-lookup.mjs';
 import { loadTaskLabels } from './task-labels.mjs';
 import { describeForceReinstall, describeInstalledVersions, describeIntake, claudeMissingGuidance, opencodeMissingGuidance, describeUpdateCacheFallback, describeUpdateCommand, describeVersionStatus, formatUpdateNotice } from './messages.mjs';
 import { resolveEffectiveProjectRoot } from './first-run.mjs';
@@ -22,6 +22,8 @@ import {
   triggerBackgroundRefresh
 } from './update-check.mjs';
 import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self-update.mjs';
+import { runChromeCommand } from './chrome-command.mjs';
+import { resolveRuntimePaths } from './runtime-diagnostics.mjs';
 
 /**
  * `akari` ランチャーの本体。3 入口契約（ターミナル `akari` / セッション内 `/akari` /
@@ -33,6 +35,8 @@ import { applySelfUpdate, isRunningFromAppDir, rollbackSelfUpdate } from './self
  * options 経由で差し替え可能にしてあり、node --test から実プロセスを起動せずに分岐を検証できる。
  */
 export async function run(args, options = {}) {
+  if (args[0] === 'chrome') return runChromeCommand(args.slice(1), options);
+
   const log = options.log ?? ((line) => console.log(line));
   const assets = options.assets ?? resolveLauncherAssets();
   const scaffold = options.scaffold ?? defaultScaffold;
@@ -95,7 +99,8 @@ export async function run(args, options = {}) {
     } catch (error) {
       log(`接続確認でエラーが発生しました（続行します）: ${error instanceof Error ? error.message : String(error)}`);
     }
-    log(describeVersionStatus(versionInfo, readCacheSync(resolveCachePath(env))));
+    const runtimeDiagnostics = options.runtimeDiagnostics ?? resolveRuntimePaths({ ...options, env, platform });
+    log(describeVersionStatus(versionInfo, readCacheSync(resolveCachePath(env)), runtimeDiagnostics));
   }
 
   // 新版通知（契約 §4-1）: キャッシュの読み比較のみ・ネットワークには一切触れない
@@ -201,6 +206,11 @@ export async function runUpdateCommand(args, options = {}) {
   const dismissRequested = args.includes('--dismiss');
   const rollbackRequested = args.includes('--rollback');
   const forceRequested = args.includes('--force');
+  const runtimeDiagnostics = options.runtimeDiagnostics ?? resolveRuntimePaths({ ...options, env });
+  const pathEnv = Object.hasOwn(env, 'PATH') ? (env.PATH ?? '') : (process.env.PATH ?? '');
+  const npmAvailable = options.npmAvailable
+    ?? !!(options.findExecutable ?? findExecutable)('npm', pathEnv, options.platform ?? process.platform, env.PATHEXT);
+  const describeOptions = { runtimeDiagnostics, npmAvailable };
   let usingCachedFeed = false;
 
   if (rollbackRequested) {
@@ -214,7 +224,7 @@ export async function runUpdateCommand(args, options = {}) {
       dismissed = true;
     }
     const finalCache = dismissed ? readCacheSync(cachePath) : cache;
-    for (const line of describeUpdateCommand({ currentVersion, versionInfo, cache: finalCache, dismissed })) {
+    for (const line of describeUpdateCommand({ currentVersion, versionInfo, cache: finalCache, dismissed, ...describeOptions })) {
       log(line);
     }
     return { exitCode: 0 };
@@ -238,16 +248,22 @@ export async function runUpdateCommand(args, options = {}) {
     && (hasManagedApp || (options.isRunningFromAppDir ?? isRunningFromAppDir)({ env, launcherRoot: options.launcherRoot }));
 
   if (!selfUpdateEligible) {
-    for (const line of describeUpdateCommand({ currentVersion, versionInfo, cache, dismissed: false, usingCachedFeed })) {
+    for (const line of describeUpdateCommand({ currentVersion, versionInfo, cache, dismissed: false, usingCachedFeed, ...describeOptions })) {
       log(line);
     }
+    if (forceRequested
+        && versionInfo.installRefStatus === 'missing'
+        && runtimeDiagnostics.render_cut.origin !== 'monorepo') {
+      log('この CLI からは install.sh 経路の本体を入れ直せません。');
+      log('導入するには `curl -fsSL https://raw.githubusercontent.com/AkariLabs/akari-video/main/install.sh | bash` を実行してください（デスクトップ版だけで使う場合は不要です）。');
+    }
     return { exitCode: 0 };
   }
 
   if (usingCachedFeed) {
     log(describeUpdateCacheFallback(cache));
   }
-  for (const line of describeInstalledVersions(versionInfo)) {
+  for (const line of describeInstalledVersions(versionInfo, runtimeDiagnostics)) {
     log(line);
   }
   log(`最新バージョン: v${feed.product}`);
@@ -265,6 +281,7 @@ export async function runUpdateCommand(args, options = {}) {
 }
 
 function resolveCommandVersionInfo(options, env) {
+  if (options.versionInfo) return options.versionInfo;
   // 既存テスト/埋め込み利用の currentVersion 注入は CLI 版注入としても扱う。
   const cliVersion = options.cliVersion ?? options.currentVersion ?? readOwnVersion();
   if (options.currentVersion !== undefined) {

package/src/doctor-command.mjs

@@ -0,0 +1,65 @@
+import { doctorExitCode, resolveDoctorReport } from './runtime-diagnostics.mjs';
+
+const usage = [
+  '使い方: akari doctor [--json]',
+  '',
+  '必須部品の実在、解決元、PATH を確認します。',
+  '  --json  機械可読な診断結果を 1 オブジェクトで出力',
+].join('\n');
+
+export async function runDoctorCommand(argv, options = {}) {
+  const log = options.log ?? ((line) => process.stdout.write(`${line}\n`));
+  const error = options.error ?? ((line) => process.stderr.write(`${line}\n`));
+  if (argv.includes('--help') || argv.includes('-h')) {
+    log(usage);
+    return { exitCode: 0 };
+  }
+  const unknown = argv.find((argument) => argument !== '--json');
+  if (unknown) {
+    error(`不明な doctor オプションです: ${unknown}\n${usage}`);
+    return { exitCode: 2 };
+  }
+
+  const report = options.report ?? await (options.resolveReport ?? resolveDoctorReport)(options);
+  if (argv.includes('--json')) log(JSON.stringify(report));
+  else log(formatDoctorReport(report));
+  return { exitCode: doctorExitCode(report.verdict), report };
+}
+
+export function formatDoctorReport(report) {
+  const rows = [
+    ['cli', 'ok', `v${report.cli.version} — ${report.cli.entry_path}`],
+    ['app_managed', report.app_managed.status, detail(report.app_managed.path, report.app_managed.version)],
+    ['app_bundle', report.app_bundle.found ? 'found' : 'missing', detail(report.app_bundle.path, report.app_bundle.version)],
+    ['render_cut', report.render_cut.origin, report.render_cut.path ?? '見つかりません'],
+    ['edit_lint', report.edit_lint.origin, report.edit_lint.path ?? '見つかりません'],
+    ['ffmpeg', report.ffmpeg.origin, report.ffmpeg.path ?? '見つかりません'],
+    ['ffprobe', report.ffprobe.origin, report.ffprobe.path ?? '見つかりません'],
+    ['chrome', report.chrome.found ? 'found' : 'missing', report.chrome.path ?? report.chrome.cache_dir],
+    ['gpu_export', report.gpu_export?.available ? 'ok' : 'unavailable', report.gpu_export?.reason ?? '診断情報がありません'],
+    ['path', report.path.on_path ? 'ok' : 'missing', report.path.cli_shim_dir],
+  ];
+  const widths = [
+    Math.max('項目'.length, ...rows.map((row) => row[0].length)),
+    Math.max('状態'.length, ...rows.map((row) => row[1].length)),
+  ];
+  const lines = [
+    'AKARI Video doctor',
+    '',
+    `${'項目'.padEnd(widths[0])}  ${'状態'.padEnd(widths[1])}  詳細`,
+    `${'-'.repeat(widths[0])}  ${'-'.repeat(widths[1])}  ${'-'.repeat(20)}`,
+    ...rows.map((row) => `${row[0].padEnd(widths[0])}  ${row[1].padEnd(widths[1])}  ${row[2]}`),
+    '',
+    `判定: ${report.verdict}`,
+  ];
+  if (report.next_steps.length > 0) {
+    lines.push('次の手順:');
+    lines.push(...report.next_steps.map((step) => `  - ${step}`));
+  }
+  return lines.join('\n');
+}
+
+function detail(path, version) {
+  const location = path ?? '見つかりません';
+  return version ? `v${version} — ${location}` : location;
+}

package/src/messages.mjs

@@ -71,7 +71,7 @@ export function formatUpdateNotice(status) {
 }
 
 /** `akari doctor` 系出力に足す 1 行（現在版 + フィード取得状態）。 */
-export function describeVersionStatus(versionOrInfo, cache) {
+export function describeVersionStatus(versionOrInfo, cache, runtimeDiagnostics) {
   if (typeof versionOrInfo === 'string') {
     if (!cache?.feed) {
       return `バージョン: v${versionOrInfo}（更新フィード: 未取得）`;
@@ -80,7 +80,7 @@ export function describeVersionStatus(versionOrInfo, cache) {
     return `バージョン: v${versionOrInfo}（更新フィード: 取得済み・${fetchedAt} 時点）`;
   }
   const info = normalizeVersionInfo(versionOrInfo);
-  const installed = describeInstalledVersions(info).join(' / ');
+  const installed = describeInstalledVersions(info, runtimeDiagnostics).join(' / ');
   if (!cache?.feed) {
     return `${installed}（更新フィード: 未取得）`;
   }
@@ -88,7 +88,7 @@ export function describeVersionStatus(versionOrInfo, cache) {
   return `${installed}（更新フィード: 取得済み・${fetchedAt} 時点）`;
 }
 
-export function describeInstalledVersions(versionOrInfo) {
+export function describeInstalledVersions(versionOrInfo, runtimeDiagnostics) {
   const info = normalizeVersionInfo(versionOrInfo);
   if (info.installRefNeedsRepair) {
     const installRefPath = info.installRefPath ?? '~/.akari/app/.akari-install-ref';
@@ -99,6 +99,21 @@ export function describeInstalledVersions(versionOrInfo) {
     ];
   }
   if (!info.appVersion) {
+    if (info.installRefStatus === 'missing' && runtimeDiagnostics?.render_cut) {
+      const renderCut = runtimeDiagnostics.render_cut;
+      const availability = renderCut.origin === 'none'
+        ? 'render-cut が見つからないため書き出しできません'
+        : `書き出しは ${humanRenderOrigin(renderCut.origin)} の render-cut を使います`;
+      const lines = [
+        `現在のバージョン: v${info.currentVersion}`,
+        `CLI バージョン: v${info.cliVersion}`,
+        `install.sh 経路の本体は未導入（${availability}。詳細: \`akari doctor\`）`,
+      ];
+      if (renderCut.origin === 'none') {
+        lines.push('復旧するにはデスクトップ版を導入するか、install.sh 経路の本体を導入してください。');
+      }
+      return lines;
+    }
     return [
       `現在のバージョン: v${info.currentVersion}`,
       `CLI バージョン: v${info.cliVersion}`,
@@ -112,11 +127,15 @@ export function describeInstalledVersions(versionOrInfo) {
   return lines;
 }
 
+function humanRenderOrigin(origin) {
+  return origin === 'monorepo' ? '開発リポジトリ' : origin;
+}
+
 export function describeForceReinstall(versionOrInfo, targetVersion) {
   const info = normalizeVersionInfo(versionOrInfo);
   return info.installRefNeedsRepair
-    ? `--force: 版を判定できない本体 → v${targetVersion} を入れ直します。`
-    : `--force: 本体 v${info.currentVersion} → v${targetVersion} を入れ直します。`;
+    ? `--force: 版を判定できない install.sh 経路の本体 → v${targetVersion} を入れ直します。`
+    : `--force: install.sh 経路の本体 v${info.currentVersion} → v${targetVersion} を入れ直します。`;
 }
 
 function normalizeVersionInfo(value) {
@@ -172,9 +191,9 @@ export function creatorRootPromptText(defaultPath) {
  * `akari update` の出力本文（複数行）。フィード未取得・最新・新版ありで案内が変わる。
  * `dismissed` は今回の実行で dismiss 記録を書いたかどうか（表示文言の切り替えのみに使う）。
  */
-export function describeUpdateCommand({ currentVersion, versionInfo, cache, dismissed, usingCachedFeed = false }) {
+export function describeUpdateCommand({ currentVersion, versionInfo, cache, dismissed, usingCachedFeed = false, runtimeDiagnostics, npmAvailable = true }) {
   const info = versionInfo ?? normalizeVersionInfo(currentVersion);
-  const lines = versionInfo ? describeInstalledVersions(info) : [`現在のバージョン: v${currentVersion}`];
+  const lines = versionInfo ? describeInstalledVersions(info, runtimeDiagnostics) : [`現在のバージョン: v${currentVersion}`];
   const feed = cache?.feed;
   if (!feed) {
     lines.push('最新情報をまだ取得できていません（オフライン、または初回起動直後の可能性があります）。');
@@ -202,8 +221,12 @@ export function describeUpdateCommand({ currentVersion, versionInfo, cache, dism
   }
 
   const tarballUrl = feed.components?.cli?.tarball?.url;
-  lines.push('更新するには、次のコマンドを実行してください（自動実行はしません）:');
-  lines.push(tarballUrl ? `  npm i -g ${tarballUrl}` : '  npm i -g akari-video@latest');
+  if (npmAvailable) {
+    lines.push('CLI を更新するには、次のコマンドを実行してください（自動実行はしません）:');
+    lines.push(tarballUrl ? `  npm i -g ${tarballUrl}` : '  npm i -g akari-video@latest');
+  } else {
+    lines.push('npm が PATH に無いため、CLI の npm 更新コマンドは表示しません。');
+  }
   lines.push(
     dismissed
       ? `この版（v${feed.product}）の通知は今後表示しません。`
@@ -303,7 +326,9 @@ export function describeCliHelp() {
     '  (引数なし)              プロジェクトを開いて AI エージェントを起動（未作成なら自動作成）',
     '  store connect          アカウント連携（無料の素材パックと購入済み素材が使えるようになる）',
     '  sounds                 公式音源ライブラリを一括ダウンロード（無料）',
-    '  update [--force]       更新を確認する（--force で本体を入れ直す）',
+    '  chrome install         動画書き出しに使う Chrome をダウンロードして導入する',
+    '  doctor [--json]        必須部品の実在と解決元を診断する',
+    '  update [--force]       更新を確認する（--force で install.sh 経路の本体を入れ直す）',
     '  status                 接続状態を確認する',
     '  migrate [dir]          古い edit.json を退避バックアップ付きで v2 へ変換',
     '',

package/src/path-lookup.mjs

@@ -27,33 +27,23 @@ function resolveWindowsExtensions(pathExt) {
  * を判定するため、拡張子なしファイル（npm の POSIX シムなど）は直接 spawn できない。
  */
 export function findClaudeExecutable(pathEnv = process.env.PATH ?? '', platform = process.platform, pathExt = process.env.PATHEXT) {
-  const directories = pathEnv.split(path.delimiter).filter(Boolean);
-  const candidateNames = platform === 'win32'
-    ? resolveWindowsExtensions(pathExt).map((extension) => `claude${extension.toLowerCase()}`)
-    : ['claude'];
-
-  for (const directory of directories) {
-    for (const name of candidateNames) {
-      const candidate = path.join(directory, name);
-      try {
-        accessSync(candidate, fsConstants.X_OK);
-        return candidate;
-      } catch {
-        // このディレクトリには無い。次を探す。
-      }
-    }
-  }
-  return null;
+  return findExecutable('claude', pathEnv, platform, pathExt);
 }
 
 /**
  * PATH 上に `opencode` 実行ファイルがあるかを探す。`findClaudeExecutable` と同じ規約。
  */
 export function findOpencodeExecutable(pathEnv = process.env.PATH ?? '', platform = process.platform, pathExt = process.env.PATHEXT) {
-  const directories = pathEnv.split(path.delimiter).filter(Boolean);
+  return findExecutable('opencode', pathEnv, platform, pathExt);
+}
+
+/** PATH 上の任意のコマンドを探索する共有ヘルパー。doctor / update も同じ判定を使う。 */
+export function findExecutable(command, pathEnv = process.env.PATH ?? '', platform = process.platform, pathExt = process.env.PATHEXT) {
+  const delimiter = platform === 'win32' ? ';' : path.delimiter;
+  const directories = pathEnv.split(delimiter).filter(Boolean);
   const candidateNames = platform === 'win32'
-    ? resolveWindowsExtensions(pathExt).map((extension) => `opencode${extension.toLowerCase()}`)
-    : ['opencode'];
+    ? resolveWindowsExtensions(pathExt).map((extension) => `${command}${extension.toLowerCase()}`)
+    : [command];
 
   for (const directory of directories) {
     for (const name of candidateNames) {