@pecot/visual-mcp 0.0.0-stage → 1.0.0

package/cli/dist/infra/playwright/chromium.js

@@ -0,0 +1,175 @@
+// Playwright Chromium の取得状態の判定と、取得の実行。
+//
+// `pecotv mcp` は、MCP クライアントの接続タイムアウトに収めるため、起動時に Chromium を取得しない。
+// 接続タイムアウトは、Claude Code の MCP_TIMEOUT が既定 30000ms。
+// 取得は `setup` ツールを明示的に呼んだとき、または PECOTV_AUTO_INSTALL_BROWSER=1 のときにだけ動く。
+//
+// 通常の CLI 実行 (`pecotv drawio url` 等) の取得手段は bin/pecotv 側にあり、本モジュールは通らない。
+// 両者の「取得済みか」の判定基準は、Playwright が完了時に置く INSTALLATION_COMPLETE マーカーで揃える。
+import { existsSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { stateFileDirectory } from '../_shared/dependency-root.js';
+import { withFlock } from '../_shared/flock.js';
+import { spawnPromise } from '../_shared/process.js';
+/**
+Chromium 取得の上限時間 (ms)。
+
+真 cold の計測は 33 秒 (Chrome for Testing / FFmpeg / Headless Shell の 3 本)。
+この上限は同時に「MCP の直列実行キューを 1 件が専有してよい上限」でもある
+(tools/call は FIFO で直列化され、取得中は他ツールが待たされる)。計測の 9 倍まで
+待って返らないなら、待ち続けるより理由付きで失敗させて再実行させる方が早い。
+*/
+const INSTALL_TIMEOUT_MS = 300_000;
+/**
+取得を自動で行ってよいかを示す opt-in の環境変数。
+*/
+export const AUTO_INSTALL_ENV = 'PECOTV_AUTO_INSTALL_BROWSER';
+/**
+Playwright が取得完了時にブラウザディレクトリ直下へ置くマーカー。
+*/
+const INSTALLATION_COMPLETE = 'INSTALLATION_COMPLETE';
+/**
+Playwright がブラウザを置くディレクトリ。判定できないときは undefined。
+
+取得済みかの判定には使わない (判定は Playwright 自身の解決に寄せる。
+chromiumBrowserDirectory を参照)。ここで求めるのは「どこに期待しているか」を
+利用者へ示すための表示用の場所で、PLAYWRIGHT_BROWSERS_PATH を尊重する。
+`0` はパッケージ同梱位置を指す特殊値で場所を特定できないため undefined を返す。
+*/
+export function browsersRoot() {
+    const override = process.env['PLAYWRIGHT_BROWSERS_PATH'];
+    if (override === '0')
+        return undefined;
+    if (override !== undefined && override !== '')
+        return override;
+    const home = process.env['HOME'];
+    return home === undefined || home === '' ? undefined : path.join(home, '.cache', 'ms-playwright');
+}
+/**
+Playwright が「今の playwright 版で使う」Chromium を置くディレクトリ。
+
+解決は Playwright 自身に任せる。
+`chromium.executablePath()` は `<browsers root>/chromium-<revision>/<platform 依存のパス>` を返す。
+そのため、`chromium-` で始まる祖先ディレクトリまで遡れば、ブラウザディレクトリが得られる。
+platform ごとに実行ファイルの深さが違うので、固定の段数では遡らない。
+
+自前で `chromium-*` を走査しない理由は 2 つある。
+- Playwright を上げた直後は、「古い chromium-<旧 rev> は残っているが、必要な chromium-<新 rev> は無い」状態になる。
+  前方一致では取得済みと誤判定する。
+- PLAYWRIGHT_BROWSERS_PATH=0 (パッケージ同梱位置) を、自前では解決できない。
+*/
+export async function chromiumBrowserDirectory() {
+    const { chromium } = await import('playwright');
+    let directory = path.dirname(chromium.executablePath());
+    while (!path.basename(directory).startsWith('chromium-')) {
+        const parent = path.dirname(directory);
+        /* c8 ignore next -- executablePath は必ず chromium-<rev> 配下を返すため到達しない防御網 */
+        if (parent === directory)
+            return undefined;
+        directory = parent;
+    }
+    return directory;
+}
+/**
+Chromium バイナリが取得済みかを判定する。
+
+見るのは、Playwright が取得完了時に置く INSTALLATION_COMPLETE マーカー。
+これは playwright-core の browserFetcher が完了判定に使うのと同じもの。
+ディレクトリの存在だけでは、展開先が先に作られるダウンロード途中の状態を、取得済みと誤判定する。
+bin/pecotv の bootstrap も同じマーカーを見る。
+
+判定に失敗したとき (playwright を解決できない・当該 platform 非対応) は、取得済み扱いで通す。
+誤検知で使える機能を塞ぐより、実際の起動失敗を各コマンドのエラーとして返す。その方が害は小さい。
+*/
+export async function isChromiumInstalled() {
+    let directory;
+    try {
+        directory = await chromiumBrowserDirectory();
+    }
+    catch {
+        return true;
+    }
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- Playwright 解決済みの dir のみ
+    return directory === undefined || existsSync(path.join(directory, INSTALLATION_COMPLETE));
+}
+/**
+PECOTV_AUTO_INSTALL_BROWSER による自動取得が有効か。
+*/
+export function isAutoInstallEnabled() {
+    // eslint-disable-next-line security/detect-object-injection -- キーは本モジュールの定数
+    return process.env[AUTO_INSTALL_ENV] === '1';
+}
+/**
+`playwright` パッケージの CLI エントリの絶対パス。
+
+`playwright/cli.js` は package.json の exports に載っていないため直接は解決できない。
+exports に載っている `playwright/package.json` からパッケージ root を求めて join する。
+node_modules が破損している / playwright が未 install の環境では同期 throw する。
+*/
+export function resolvePlaywrightCli() {
+    const require_ = createRequire(import.meta.url);
+    return path.join(path.dirname(require_.resolve('playwright/package.json')), 'cli.js');
+}
+/**
+bin/pecotv がバックグラウンド取得に使う専有ロックのパス。
+
+PECOTV_AUTO_INSTALL_BROWSER=1 の環境では、起動時のバックグラウンド取得とツール実行時の
+取得が同時に動き得る。同じロックファイルを同じ primitive (flock(2)) で取ることで、
+2 本目は 1 本目の完了を待ってから動く (待ったあとは Playwright 側が冪等に skip する)。
+
+置き場所は `${データ置き場}/runtime`（bin/pecotv と同じ場所。runtimeStateDirectory）。
+実行用ミラーを経ない形態（開発・単体配布）では、従来どおり依存ルートの node_modules
+(infra/_shared/dependency-root.ts)。
+実在するディレクトリが 1 つも無ければ undefined を返し、ロックなしで動く。
+flock(1) は親ディレクトリが無いとロックファイルを作れず exit 66 で終わる。
+そのため、場所が決まらないときにパスを組み立てて渡すと、取得そのものが必ず失敗する。
+*/
+export function installLockPath() {
+    const stateDirectory = stateFileDirectory();
+    return stateDirectory === undefined ? undefined : path.join(stateDirectory, '.pecotv-chromium-install.lock');
+}
+/**
+`playwright install chromium` を実行する。
+
+既に取得済みでも Playwright 側が冪等に skip するため、呼び出し前の存在確認は不要。
+取得済み判定は、ダウンロード途中を弾く目的でのみ使う。
+
+flock(1) が使える環境では、bin/pecotv と同じロックファイル越しに実行する。
+これは、起動時のバックグラウンド取得との二重ダウンロードを避けるため。
+包み方と待ち方は infra/_shared/flock.ts に置き、実行時依存の取得と揃える。
+
+env は利用者環境のものを引き継ぐ。
+PLAYWRIGHT_DOWNLOAD_HOST や HTTPS_PROXY といった取得先・通信の指定は、利用者環境の変数で行われる。
+そのため、絞り込むと取得できなくなる。
+プロキシの CA は利用者が `NODE_EXTRA_CA_CERTS` で渡す。
+Playwright の実ダウンロードは子 node を fork して動く。
+fork は親の env を継承するので、利用者の指定は子にも届く。
+*/
+export async function installChromium(options = {}) {
+    let cli;
+    try {
+        cli = (options.resolveCli ?? resolvePlaywrightCli)();
+    }
+    catch (error) {
+        // ここで throw すると MCP ハンドラの外へ例外が出て、SDK が structuredContent 無しのエラーへまとめる。
+        // ToolResult 契約 (reason と `setup` 誘導) を保つため、起動失敗として返す。
+        const detail = error instanceof Error ? error.message : String(error);
+        return {
+            // eslint-disable-next-line unicorn/no-null -- SpawnResult は起動失敗を exitCode: null で表す
+            exitCode: null,
+            // eslint-disable-next-line unicorn/no-null -- 同上
+            signal: null,
+            stdout: '',
+            stderr: `playwright パッケージを解決できません: ${detail}`,
+            timedOut: false,
+        };
+    }
+    const locked = withFlock(installLockPath(), process.execPath, [cli, 'install', 'chromium']);
+    return await spawnPromise(locked.command, locked.commandArguments, {
+        env: process.env,
+        timeoutMs: INSTALL_TIMEOUT_MS,
+        signal: options.signal,
+    });
+}
+//# sourceMappingURL=chromium.js.map

package/cli/dist/infra/playwright/host-dependencies.d.ts

@@ -0,0 +1,114 @@
+import type { SpawnResult } from '../../domain/_shared/spawn-result.js';
+/**
+確認の結果を記録する印のファイル名。`${データ置き場}/runtime` 直下（bin/pecotv と同じ場所）に置く。
+実行用ミラーを経ない形態（開発・単体配布）では、従来どおり依存ルートの node_modules 直下。
+
+中身は 1 行 `<chromium のリビジョン> <ok|missing|launch-failed> <記録時の epoch 秒>`。
+bin/pecotv は、リビジョンが一致し、かつ ok か (失敗系なら) 記録から 1 日以内であれば
+確認を飛ばす。リビジョンを含めるので、Playwright を上げて Chromium が変わったときは
+改めて確認が動く。失敗も記録するのは、確認に通らない環境で起動のたびに確認と警告が
+動き続けないため。
+*/
+export declare const HOST_DEPS_STAMP = ".pecotv-chromium-host-deps";
+export type HostDependenciesStampStatus = 'ok' | 'missing' | 'launch-failed';
+/**
+Chromium の起動失敗メッセージから、読み込めなかった共有ライブラリ名を取り出す。
+
+形式は 2 つある。
+1 つは、実行ファイルが落ちたときの `error while loading shared libraries: <名前>:`。
+もう 1 つは、Playwright が起動前にチェックして投げる枠付きの `Missing libraries:` 以下の `<名前>` の列。
+*/
+export declare function missingSharedLibraries(message: string): string[];
+/**
+起動失敗が OS のライブラリ不足によるものか。
+
+ライブラリ名を取り出せなくても、Playwright の起動前チェックが出す `Host system is missing dependencies` は、
+ライブラリ不足を指す。
+パッケージ名の案内だけで、ライブラリ名の列を含まない形がある。
+*/
+export declare function isMissingHostDependencies(message: string): boolean;
+/**
+`playwright install-deps --dry-run chromium` の出力から、入れるべきパッケージを取り出す。
+
+出力は「Missing system dependencies (N):」の見出しに続けて 1 行 1 パッケージを字下げして
+並べる形。フォントと X サーバは除く (冒頭のコメントを参照)。
+*/
+export declare function hostPackagesFromDryRun(output: string): string[];
+/**
+利用者へ示す導入コマンド。
+*/
+export declare function aptInstallCommand(packages: readonly string[]): string;
+export type HostDependenciesOutcome = {
+    readonly status: 'ok';
+}
+/**
+足りなかったライブラリを入れ、起動できるようになった。
+*/
+ | {
+    readonly status: 'installed';
+    readonly packages: readonly string[];
+}
+/**
+足りないが入れられなかった。案内を detail に載せる。libraries は名前を取り出せなければ空。
+*/
+ | {
+    readonly status: 'missing';
+    readonly libraries: readonly string[];
+    readonly packages: readonly string[];
+    readonly detail: string;
+}
+/**
+起動できないが、原因は OS ライブラリではない (実行ファイル未取得等)。
+*/
+ | {
+    readonly status: 'launch-failed';
+    readonly detail: string;
+};
+export interface HostDependencies {
+    readonly platform: NodeJS.Platform;
+    /**
+    root で動いているか。root なら sudo を介さず apt-get を叩く。
+    */
+    readonly isRoot: boolean;
+    /**
+    headless Chromium を起動して閉じる。起動できなければエラーメッセージを返す。
+    */
+    readonly probe: () => Promise<string | undefined>;
+    readonly run: (command: string, arguments_: readonly string[], timeoutMs: number, signal?: AbortSignal) => Promise<SpawnResult>;
+    readonly playwrightCli: () => string;
+    readonly nodePath: string;
+    /**
+    確認の結果を記録する (recordHostDependenciesResult)。
+    */
+    readonly record: (status: HostDependenciesStampStatus) => void;
+    /**
+    apt-get を始める前に、何をなぜ入れるかを利用者へ伝える。数分かかり得るため、通知なしで止まって
+    見えないようにする。stdout を JSON-RPC に使う MCP 経由では何も出さない既定のままにする。
+    */
+    readonly notify: (message: string) => void;
+}
+export declare function hostDependenciesDefaultDependencies(): HostDependencies;
+/**
+Chromium が起動できる状態にする。
+
+起動を試し、OS ライブラリ不足で落ちたときだけ不足パッケージを割り出して入れ、もう一度
+起動を試す。Linux 以外は Playwright がブラウザ側に依存を同梱するため確認しない。
+
+不足パッケージの割り出し (install-deps --dry-run) は apt の一覧に頼る。一覧が空の
+イメージでは失敗するので、権限があるときは apt-get update をしてやり直す。update の
+失敗 (無関係な第三者リポの署名切れ等) は install の失敗の手掛かりとして残すだけで、
+install まで進む。
+*/
+export declare function ensureChromiumHostDependencies(dependencies: HostDependencies, signal?: AbortSignal): Promise<HostDependenciesOutcome>;
+/**
+今の Playwright が使う Chromium のリビジョン。解決できないときは undefined。
+*/
+export declare function chromiumRevision(): string | undefined;
+/**
+確認の結果を印の置き場に記録する (置き場と印の形式は HOST_DEPS_STAMP を参照)。
+
+記録できなくても (置き場が無い・リビジョンを解決できない・書き込めない) 失敗にはしない。
+次回の起動で確認がもう一度動くだけで、結果は変わらない。
+*/
+export declare function recordHostDependenciesResult(status: HostDependenciesStampStatus, nowMs?: number): void;
+//# sourceMappingURL=host-dependencies.d.ts.map

package/cli/dist/infra/playwright/host-dependencies.js

@@ -0,0 +1,265 @@
+// Playwright Chromium が起動するのに要る OS の共有ライブラリの確認と導入 (#1217)。
+//
+// Chromium の実行ファイルは `playwright install chromium` で取得できるが、それが読み込む
+// libatk / libpango 等の OS ライブラリは入らない。利用環境に無ければ drawio export / url の
+// PNG 出力と slide convert が起動時に失敗する。利用者に手作業をさせないため、bootstrap と
+// MCP の `setup` ツールがここを通り、足りなければ自分で入れる。
+//
+// 入れるのは共有ライブラリだけにする。
+// `playwright install-deps` は、フォント (fonts-wqy-zenhei 等) と headed 用の X サーバ (xvfb 等) も入れる。
+// フォントは Chromium の日本語の fallback を変え、PPTX / PNG の見た目を変える。
+// X サーバは headless では使わない。
+// そのため install-deps には不足パッケージの割り出し (--dry-run) だけを任せ、導入は apt-get で絞って行う。
+// 絞るのはパッケージ名でだけで、除いたパッケージの推移依存 (libxfont2 / xkb-data 等) は、
+// dry-run の一覧に載っていれば入る。
+// 依存閉包で正確に除こうとすると、Chromium 側にも要るライブラリを落として、起動できなくなる恐れがある。
+// 推移依存は小さな共有ライブラリとデータで、描画を変えない (フォント本体は --no-install-recommends で入らない)。
+// このため、名前での除外に留める。
+//
+// root 権限が無い環境では、OS ライブラリはどの手段でも入れられない。
+// その場合だけ、足りないライブラリと入れるコマンドをそのまま案内する。
+import { readFileSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+import { stateFileDirectory } from '../_shared/dependency-root.js';
+import { spawnPromise } from '../_shared/process.js';
+import { resolvePlaywrightCli } from './chromium.js';
+/**
+apt-get update / install の上限時間 (ms)。パッケージ 15 個前後の取得と展開に十分な値。
+*/
+const APT_TIMEOUT_MS = 600_000;
+/**
+sudo -n / dry-run 等の短い子プロセスの上限時間 (ms)。
+*/
+const SHORT_TIMEOUT_MS = 60_000;
+/**
+apt-get が dpkg / apt のロックを待つ秒数。並行起動した apt-get (unattended-upgrades 等) に
+即失敗せず、APT_TIMEOUT_MS に収まる範囲で待つ。update と install のそれぞれに付ける。
+*/
+const APT_LOCK_TIMEOUT_SECONDS = 120;
+/**
+確認の結果を記録する印のファイル名。`${データ置き場}/runtime` 直下（bin/pecotv と同じ場所）に置く。
+実行用ミラーを経ない形態（開発・単体配布）では、従来どおり依存ルートの node_modules 直下。
+
+中身は 1 行 `<chromium のリビジョン> <ok|missing|launch-failed> <記録時の epoch 秒>`。
+bin/pecotv は、リビジョンが一致し、かつ ok か (失敗系なら) 記録から 1 日以内であれば
+確認を飛ばす。リビジョンを含めるので、Playwright を上げて Chromium が変わったときは
+改めて確認が動く。失敗も記録するのは、確認に通らない環境で起動のたびに確認と警告が
+動き続けないため。
+*/
+export const HOST_DEPS_STAMP = '.pecotv-chromium-host-deps';
+/**
+共有ライブラリではないため入れないパッケージ (フォント・headed 用の X サーバ)。
+*/
+const EXCLUDED_PACKAGES = new Set(['xvfb', 'xserver-common', 'xauth', 'x11-xkb-utils']);
+/**
+起動前の依存チェック (Playwright が枠付きで出す) で、ライブラリ名が `libxxx.so.N` で並ぶ形か。
+*/
+function isSharedLibraryName(line) {
+    return !/\s/.test(line) && /\.so(?:\.|$)/.test(line);
+}
+/**
+Chromium の起動失敗メッセージから、読み込めなかった共有ライブラリ名を取り出す。
+
+形式は 2 つある。
+1 つは、実行ファイルが落ちたときの `error while loading shared libraries: <名前>:`。
+もう 1 つは、Playwright が起動前にチェックして投げる枠付きの `Missing libraries:` 以下の `<名前>` の列。
+*/
+export function missingSharedLibraries(message) {
+    const libraries = new Set();
+    for (const match of message.matchAll(/error while loading shared libraries: ([^:\s]+)/g)) {
+        const library = match[1];
+        if (library !== undefined)
+            libraries.add(library);
+    }
+    const lines = message.split('\n').map(line => line.replaceAll('║', '').trim());
+    const start = lines.indexOf('Missing libraries:');
+    if (start !== -1) {
+        const followingLines = lines.slice(start + 1);
+        for (const line of followingLines) {
+            if (!isSharedLibraryName(line))
+                break;
+            libraries.add(line);
+        }
+    }
+    return [...libraries];
+}
+/**
+起動失敗が OS のライブラリ不足によるものか。
+
+ライブラリ名を取り出せなくても、Playwright の起動前チェックが出す `Host system is missing dependencies` は、
+ライブラリ不足を指す。
+パッケージ名の案内だけで、ライブラリ名の列を含まない形がある。
+*/
+export function isMissingHostDependencies(message) {
+    return missingSharedLibraries(message).length > 0 || message.includes('Host system is missing dependencies');
+}
+/**
+`playwright install-deps --dry-run chromium` の出力から、入れるべきパッケージを取り出す。
+
+出力は「Missing system dependencies (N):」の見出しに続けて 1 行 1 パッケージを字下げして
+並べる形。フォントと X サーバは除く (冒頭のコメントを参照)。
+*/
+export function hostPackagesFromDryRun(output) {
+    const lines = output.split('\n');
+    const start = lines.findIndex(line => line.startsWith('Missing system dependencies'));
+    if (start === -1)
+        return [];
+    const packages = [];
+    const followingLines = lines.slice(start + 1);
+    for (const line of followingLines) {
+        const name = line.trim();
+        if (name === '' || !/^\s+\S+$/.test(line))
+            break;
+        if (name.startsWith('fonts-') || name.startsWith('xfonts-') || EXCLUDED_PACKAGES.has(name))
+            continue;
+        packages.push(name);
+    }
+    return packages;
+}
+/**
+利用者へ示す導入コマンド。
+*/
+export function aptInstallCommand(packages) {
+    return `sudo apt-get install -y --no-install-recommends ${packages.join(' ')}`;
+}
+async function probeLaunch() {
+    try {
+        const { chromium } = await import('playwright');
+        const browser = await chromium.launch({ headless: true });
+        await browser.close();
+        return undefined;
+    }
+    catch (error) {
+        return error instanceof Error ? error.message : String(error);
+    }
+}
+export function hostDependenciesDefaultDependencies() {
+    return {
+        platform: process.platform,
+        isRoot: process.getuid?.() === 0,
+        probe: probeLaunch,
+        run: async (command, arguments_, timeoutMs, signal) => await spawnPromise(command, arguments_, { timeoutMs, signal }),
+        playwrightCli: resolvePlaywrightCli,
+        nodePath: process.execPath,
+        record: recordHostDependenciesResult,
+        notify: () => {
+            // デフォルトでは通知しない。stderr へ出す呼び出し元 (pecotv chromium host-deps) が差し替える。
+        },
+    };
+}
+function spawnDetail(result) {
+    const output = `${result.stderr}\n${result.stdout}`.trim();
+    return result.timedOut ? `時間内に終わりませんでした: ${output}` : output;
+}
+/**
+Chromium が起動できる状態にする。
+
+起動を試し、OS ライブラリ不足で落ちたときだけ不足パッケージを割り出して入れ、もう一度
+起動を試す。Linux 以外は Playwright がブラウザ側に依存を同梱するため確認しない。
+
+不足パッケージの割り出し (install-deps --dry-run) は apt の一覧に頼る。一覧が空の
+イメージでは失敗するので、権限があるときは apt-get update をしてやり直す。update の
+失敗 (無関係な第三者リポの署名切れ等) は install の失敗の手掛かりとして残すだけで、
+install まで進む。
+*/
+export async function ensureChromiumHostDependencies(dependencies, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- signal は mutable 型
+signal) {
+    if (dependencies.platform !== 'linux')
+        return { status: 'ok' };
+    const failure = await dependencies.probe();
+    if (failure === undefined)
+        return { status: 'ok' };
+    if (!isMissingHostDependencies(failure))
+        return { status: 'launch-failed', detail: failure };
+    const libraries = missingSharedLibraries(failure);
+    const libraryList = libraries.length > 0 ? ` (${libraries.join(', ')})` : '';
+    const missing = (packages, reason) => ({
+        status: 'missing',
+        libraries,
+        packages,
+        detail: `Chromium の起動に要る OS のライブラリが足りません${libraryList}。${reason}`,
+    });
+    // -n: パスワードを求めずに使えるときだけ通す (devcontainer 等)。対話で止めない。
+    const sudo = dependencies.isRoot ? undefined : await dependencies.run('sudo', ['-n', 'true'], SHORT_TIMEOUT_MS, signal);
+    const canElevate = sudo === undefined || sudo.exitCode === 0;
+    // sudo はデフォルトで環境変数を引き継がないため、apt-get の非対話化は env で渡し直す。
+    const command = dependencies.isRoot ? 'env' : 'sudo';
+    const aptGet = [
+        ...(dependencies.isRoot ? [] : ['-n', 'env']),
+        'DEBIAN_FRONTEND=noninteractive',
+        'apt-get',
+        '-o',
+        `DPkg::Lock::Timeout=${String(APT_LOCK_TIMEOUT_SECONDS)}`,
+    ];
+    const update = { done: false, failure: undefined };
+    const runUpdate = async () => {
+        if (!update.done)
+            dependencies.notify('Chromium の起動に要る OS のライブラリが足りないため、apt-get で入れます (数分かかることがあります)。');
+        update.done = true;
+        const result = await dependencies.run(command, [...aptGet, 'update'], APT_TIMEOUT_MS, signal);
+        update.failure = result.exitCode === 0 ? undefined : `apt-get update が失敗しました: ${spawnDetail(result)}`;
+    };
+    const dryRun = async () => {
+        const result = await dependencies.run(dependencies.nodePath, [dependencies.playwrightCli(), 'install-deps', '--dry-run', 'chromium'], SHORT_TIMEOUT_MS, signal);
+        return { result, packages: hostPackagesFromDryRun(result.stdout) };
+    };
+    let found = await dryRun();
+    if (canElevate && found.packages.length === 0) {
+        await runUpdate();
+        found = await dryRun();
+    }
+    const { packages } = found;
+    if (packages.length === 0) {
+        const reasons = [spawnDetail(found.result), update.failure].filter(text => text !== undefined && text !== '').join('\n');
+        return missing([], `この OS では入れるパッケージを割り出せませんでした。OS のパッケージ管理で上記のライブラリを入れてください: ${reasons}`);
+    }
+    if (!canElevate) {
+        return missing(packages, `root 権限が無いため自動では入れられません。次を実行してください: ${aptInstallCommand(packages)}`);
+    }
+    if (!update.done)
+        await runUpdate();
+    const install = await dependencies.run(command, [...aptGet, 'install', '-y', '--no-install-recommends', ...packages], APT_TIMEOUT_MS, signal);
+    if (install.exitCode !== 0) {
+        const reasons = [spawnDetail(install), update.failure].filter(text => text !== undefined && text !== '').join('\n');
+        return missing(packages, `apt-get install に失敗しました。ネットワークとプロキシ設定を確認し、次を実行してください: ${aptInstallCommand(packages)}\n${reasons}`);
+    }
+    const retry = await dependencies.probe();
+    if (retry === undefined)
+        return { status: 'installed', packages };
+    if (!isMissingHostDependencies(retry))
+        return { status: 'launch-failed', detail: retry };
+    return missing(packages, `${packages.join(' ')} を入れましたが、まだ起動できません: ${retry}`);
+}
+/**
+今の Playwright が使う Chromium のリビジョン。解決できないときは undefined。
+*/
+export function chromiumRevision() {
+    const require_ = createRequire(import.meta.url);
+    const core = createRequire(require_.resolve('playwright/package.json')).resolve('playwright-core/package.json');
+    // eslint-disable-next-line security/detect-non-literal-fs-filename -- 読むのは browsers.json のみ
+    const manifest = readFileSync(path.join(path.dirname(core), 'browsers.json'), 'utf8');
+    // browsers[] は name の直後に revision が並ぶ固定の書式 (utils/roll_browser.js の生成物)。
+    return /"name":\s*"chromium",\s*"revision":\s*"(\d+)"/.exec(manifest)?.[1];
+}
+/**
+確認の結果を印の置き場に記録する (置き場と印の形式は HOST_DEPS_STAMP を参照)。
+
+記録できなくても (置き場が無い・リビジョンを解決できない・書き込めない) 失敗にはしない。
+次回の起動で確認がもう一度動くだけで、結果は変わらない。
+*/
+export function recordHostDependenciesResult(status, nowMs = Date.now()) {
+    try {
+        const stateDirectory = stateFileDirectory();
+        const revision = chromiumRevision();
+        if (stateDirectory === undefined || revision === undefined)
+            return;
+        // eslint-disable-next-line security/detect-non-literal-fs-filename -- 書くのは印の置き場直下の固定名の印のみ
+        writeFileSync(path.join(stateDirectory, HOST_DEPS_STAMP), `${revision} ${status} ${String(Math.floor(nowMs / 1000))}\n`);
+    }
+    catch {
+        // 上のコメントのとおり握りつぶす。
+    }
+}
+//# sourceMappingURL=host-dependencies.js.map

package/cli/dist/infra/playwright/launch.d.ts

@@ -0,0 +1,14 @@
+import { type Browser } from 'playwright';
+/**
+Chromium の起動失敗を、利用者が次に取る手順を添えたエラーへ包み直す。
+手順を示せない失敗 (Chromium と無関係な例外) は undefined を返し、呼び出し元がそのまま投げる。
+
+OS のライブラリ不足は実行ファイルの再取得では直らないため、取得の案内とは分ける (#1217)。
+*/
+export declare function chromiumLaunchError(message: string, cause: unknown): Error | undefined;
+/**
+headless Chromium を起動する。実行ファイルが無い・OS のライブラリが足りない等で
+起動できないときは、次の手順を添えたエラーへ包み直す。
+*/
+export declare function launchChromium(): Promise<Browser>;
+//# sourceMappingURL=launch.d.ts.map

package/cli/dist/infra/playwright/launch.js

@@ -0,0 +1,40 @@
+// headless Chromium の起動と、起動できないときの取得手順の案内。
+//
+// 利用者を同じ文言で誘導するための共有点。
+// 使うのは draw.io の embed export (infra/drawio/screenshot.ts)。
+// SVG → PDF 変換 (infra/drawio/pdf.ts) と slidev-to-pptx の pipeline も使う。
+import { chromium } from 'playwright';
+import { isMissingHostDependencies, missingSharedLibraries } from './host-dependencies.js';
+/**
+Chromium の起動失敗を、利用者が次に取る手順を添えたエラーへ包み直す。
+手順を示せない失敗 (Chromium と無関係な例外) は undefined を返し、呼び出し元がそのまま投げる。
+
+OS のライブラリ不足は実行ファイルの再取得では直らないため、取得の案内とは分ける (#1217)。
+*/
+export function chromiumLaunchError(message, cause) {
+    if (isMissingHostDependencies(message)) {
+        const libraries = missingSharedLibraries(message);
+        const libraryList = libraries.length > 0 ? ` (${libraries.join(', ')})` : '';
+        return new Error(`Playwright Chromium の起動に要る OS のライブラリが足りません${libraryList}: ${message}\n`
+            + '  pecotv の setup (plugins/pecot-visual/setup.sh、MCP では setup ツール) を実行すると、sudo を使える環境では自動で入ります。'
+            + ' sudo を使えない環境では、setup が示すコマンドを管理者に実行してもらってください。', { cause });
+    }
+    return /Executable doesn't exist|browserType\.launch|playwright\S*chromium/i.test(message)
+        ? new Error(`Playwright Chromium が起動できません: ${message}\n`
+            + '  pnpm --filter @pecot/pecotv-cli exec playwright install chromium を実行してください。', { cause })
+        : undefined;
+}
+/**
+headless Chromium を起動する。実行ファイルが無い・OS のライブラリが足りない等で
+起動できないときは、次の手順を添えたエラーへ包み直す。
+*/
+export async function launchChromium() {
+    try {
+        return await chromium.launch({ headless: true });
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw chromiumLaunchError(message, error) ?? error;
+    }
+}
+//# sourceMappingURL=launch.js.map

package/cli/dist/infra/pptx-ooxml/archive.d.ts

@@ -0,0 +1,6 @@
+import type { PptxArchive, PptxReader, PptxWriter } from '../../domain/_shared/ports.js';
+export declare class YauzlYazlPptxArchive implements PptxArchive {
+    read(path: string): Promise<PptxReader>;
+    write(): PptxWriter;
+}
+//# sourceMappingURL=archive.d.ts.map