@pecot/visual-mcp 0.0.0-stage → 1.0.0

package/cli/dist/infra/drawio/screenshot.js

@@ -0,0 +1,281 @@
+// draw.io の図を画像にする I/O 層。PNG は commands/drawio/url.ts、SVG は commands/drawio/export.ts
+// から DI 経由で注入される。
+//
+// PNG（capturePng）は、スライドが図を描くのと同じ diagrams.net の viewer で描いて撮る。
+// 描くページには、テーマの宣言の書体（呼び出し側が渡す）を Google Fonts から読み込む。
+// 作図エージェントは PNG を見て崩れを直すので、PNG がスライドと違う書体で描かれると、
+// 収まっていない図を収まっていると判断してしまう。撮った PNG には XML を tEXt チャンク
+// `mxfile` として埋め込み、draw.io で開けば再編集できる形（draw.io 公式の XML 埋め込み PNG）にする。
+//
+// SVG（exportViaEmbed）は draw.io editor の post message embed API（`embed.diagrams.net`）に
+// 送って export させる。公式 post message protocol の event 名 `init` / `load` / `export` に
+// 依存しており、editor 側 API が変わると破損する。event 名は本ファイル内の文字列定数として grep test 対象。
+//
+// どちらも外部 CDN（viewer.diagrams.net / embed.diagrams.net / fonts.googleapis.com）へ、
+// XML か描画要求を送る。
+// 機密 XML を扱う場合は、--no-png オプションで PNG 生成を抑止できる。
+// PNG は tEXt チャンクに XML ソースをそのまま内包するため、PNG 単体の配布でもソースが漏れる。
+// ラスター画像のみを配布したい場合は、--no-png が必須。
+//
+// 環境変数 PECOTV_FORCE_PNG_FAIL=1 / PECOTV_FORCE_SVG_FAIL=1 を指定すると、
+// Playwright 起動より前に意図的に reject する。
+// chromium 未インストール環境でも失敗パスを検証できるようにするため。
+/* eslint-disable security/detect-non-literal-fs-filename -- outputPath は信頼境界内のパス */
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { crc32 } from 'node:zlib';
+import { launchChromium } from '../playwright/launch.js';
+import { ignoreRejection } from '../../domain/_shared/ignore-rejection.js';
+import { webFontsFor } from '../../domain/drawio/web-fonts.js';
+const EMBED_URL = 'https://embed.diagrams.net/?embed=1&proto=json';
+const EVENT_INIT = 'init';
+const EVENT_LOAD = 'load';
+const EVENT_EXPORT = 'export';
+const EXPORT_TIMEOUT_MS = 60_000;
+const VIEWPORT = { width: 1280, height: 800 };
+// format ごとの失敗注入 env。PNG は既存 CUJ が参照する名前を温存し、SVG は同形の別名を持つ。
+const FORCE_FAIL_ENV = {
+    xmlpng: 'PECOTV_FORCE_PNG_FAIL',
+    svg: 'PECOTV_FORCE_SVG_FAIL',
+};
+/**
+viewer で `xmlString` を描いて `outputPath` に PNG を書く。
+fonts は読み込む書体名（テーマの宣言の本文の書体と和文の書体）。総称の書体だけなら Web フォントを読み込まない。
+*/
+export async function capturePng(xmlString, outputPath, fonts) {
+    if (process.env[FORCE_FAIL_ENV.xmlpng] === '1') {
+        throw new Error(`forced XMLPNG failure (${FORCE_FAIL_ENV.xmlpng}=1)`);
+    }
+    // mkdir は描画成功後に置く。失敗パスで先にディレクトリを掘ると、PNG の無い
+    // 空ディレクトリが残る。
+    const rendered = await renderWithThemeFonts(xmlString, webFontsFor(fonts));
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, embedXmlChunk(rendered, xmlString));
+}
+const VIEWER_SCRIPT_URL = 'https://viewer.diagrams.net/js/viewer-static.min.js';
+/**
+viewer で `xmlString` を描き、図の範囲を撮った PNG のバイト列を返す。
+描く前に、渡された Web フォントを読み込む。読み込む書体が無ければ @import を作らない。
+*/
+async function renderWithThemeFonts(xmlString, fonts) {
+    // url('...') の引用符を壊さないよう、URL の ' は %27 にしてある（webFontsFor）。
+    const fontCss = fonts.stylesheetUrl === undefined ? '' : `@import url('${fonts.stylesheetUrl}');`;
+    const browser = await launchChromium();
+    try {
+        const page = await browser.newPage({ viewport: VIEWPORT, deviceScaleFactor: 1 });
+        await page.setContent(`<!doctype html><html><head><meta charset="utf-8"><style>${fontCss}body{margin:0;background:#FFFFFF}</style></head>`
+            + '<body><div class="mxgraph" id="d"></div></body></html>', { waitUntil: 'load', timeout: EXPORT_TIMEOUT_MS });
+        await page.evaluate(preloadFonts, [...fonts.preload]);
+        await page.evaluate(mountViewerConfig, xmlString);
+        await page.addScriptTag({ url: VIEWER_SCRIPT_URL });
+        await page.evaluate(processViewerElements);
+        const diagram = page.locator('#d svg').first();
+        await diagram.waitFor({ state: 'visible', timeout: EXPORT_TIMEOUT_MS });
+        await page.evaluate(waitFontsReady);
+        return await diagram.screenshot({ timeout: EXPORT_TIMEOUT_MS });
+    }
+    finally {
+        await browser.close();
+    }
+}
+// ブラウザ context で実行される関数群。page.evaluate で注入される。
+async function preloadFonts(fonts) {
+    await Promise.all(fonts.map(async (font) => {
+        try {
+            await document.fonts.load(font);
+        }
+        catch {
+            // 読めない書体は代替書体で描く。読み込みの失敗で PNG 全体を落とさない
+        }
+    }));
+}
+function mountViewerConfig(xml) {
+    const element = document.querySelector('#d');
+    if (element === null)
+        throw new Error('viewer element not mounted');
+    element.dataset['mxgraph'] = JSON.stringify({
+        xml, 'highlight': 'none', 'nav': false, 'resize': false, 'toolbar': '', 'border': 0, 'check-visible-state': false,
+    });
+}
+function processViewerElements() {
+    // eslint-disable-next-line no-restricted-syntax -- viewer-static が window に生やす GraphViewer を narrowing
+    const viewer = globalThis.GraphViewer;
+    if (viewer === undefined)
+        throw new Error('GraphViewer が読み込まれていません');
+    viewer.processElements();
+}
+async function waitFontsReady() {
+    await document.fonts.ready;
+}
+/**
+PNG の IHDR の直後に tEXt チャンク `mxfile` を差し込む。値は draw.io の XML 埋め込み PNG と同じく
+encodeURIComponent した XML で、draw.io で開くと再編集できる。
+*/
+function embedXmlChunk(png, xmlString) {
+    const IHDR_END = 8 + 4 + 4 + 13 + 4;
+    const body = Buffer.concat([Buffer.from('tEXt', 'latin1'), Buffer.from(`mxfile\0${encodeURIComponent(xmlString)}`, 'latin1')]);
+    const length = Buffer.alloc(4);
+    length.writeUInt32BE(body.length - 4);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(body));
+    return Buffer.concat([png.subarray(0, IHDR_END), length, body, crc, png.subarray(IHDR_END)]);
+}
+/**
+embed API で `xmlString` を `format` に export し、decode 済のバイト列を返す。
+data URI の base64 部分のみを扱う（editor は png / svg いずれも base64 で返す）。
+*/
+export async function exportViaEmbed(xmlString, options) {
+    const failFlagName = FORCE_FAIL_ENV[options.format];
+    // eslint-disable-next-line security/detect-object-injection -- key は EmbedExportFormat union で本ファイル内固定
+    if (process.env[failFlagName] === '1') {
+        throw new Error(`forced ${options.format.toUpperCase()} failure (${failFlagName}=1)`);
+    }
+    const browser = await launchChromium();
+    try {
+        const page = await browser.newPage({ userAgent: await headedUserAgent(browser) });
+        await page.setViewportSize({ width: VIEWPORT.width, height: VIEWPORT.height });
+        // closure 経由で export の応答を外部から resolve できる形に分離。
+        // exposeFunction を await することで listener install 完了を保証してから setContent に進む。
+        const { promise: dataUriPromise, resolve: resolveExport } = Promise.withResolvers();
+        // 時間切れの診断用に、どこまで進んだかを控える。
+        // 時間切れの原因は、init 未着・load/export 未着・setContent の遅延のいずれか。
+        // これが無いと、原因を区別できない。
+        const startedAt = performance.now();
+        const elapsedSeconds = () => (performance.now() - startedAt) / 1000;
+        const progress = [];
+        let contentLoadSeconds;
+        let handshakeSeconds;
+        // 完了した段だけ「<動詞> <秒>s」と書く。未完了の段は単位を付けない。
+        const describeStage = (name, done, seconds) => (seconds === undefined ? `${name} 未完了` : `${name} ${done} ${seconds.toFixed(1)}s`);
+        // 時間切れは export の応答待ちだけでなく、setContent / evaluate などの各段も打ち切る。
+        // `expired` は reject 専用で、各段と Promise.race で競わせる。
+        // race が各 promise に handler を付けるので、負けた段が後から reject しても unhandled rejection にならない。
+        // 生成直後に catch を付けるのは、どの段も race していない間の時間切れへ備えるため。
+        // 例えば exposeFunction の await 中。
+        const { promise: expired, reject: expire } = Promise.withResolvers();
+        // 呼び出し側へは race 経由で届く。ここは unhandled rejection を避けるだけ。
+        void ignoreRejection(expired);
+        const withinDeadline = async (stage) => await Promise.race([stage, expired]);
+        const timer = setTimeout(() => {
+            const last = progress.at(-1) ?? 'なし';
+            expire(new Error(`embed protocol timeout (${(EXPORT_TIMEOUT_MS / 1000).toString()}s)`
+                + `: 最後に受けたイベント=${last}`
+                + ` (${describeStage('setContent', '完了', contentLoadSeconds)} / ${describeStage('handshake', '設置', handshakeSeconds)}`
+                + ` / 受信 ${progress.join(' → ') || 'なし'})`));
+        }, EXPORT_TIMEOUT_MS);
+        try {
+            await withinDeadline(page.exposeFunction('__pecotvOnExport', (data) => {
+                clearTimeout(timer);
+                resolveExport(data);
+            }));
+            await withinDeadline(page.exposeFunction('__pecotvOnProgress', (event) => {
+                progress.push(`${event}@${elapsedSeconds().toFixed(1)}s`);
+            }));
+            // about:blank を base にして iframe で embed.diagrams.net をロードする。
+            // top-level navigation で `embed.diagrams.net` を開くと、editor が iframe 専用 protocol を起動しない。
+            // そのため init event が来ない。iframe 経由なら、draw.io 公式 embed.html の前提と一致する。
+            // iframe はここでは src 無しで載せる。
+            // embed の URL は、handshake の中で message の listener を付けた後に設定する。
+            // embed は init を再送しない。読み込みを先に始めて listener が後になると、その間に届いた init を取りこぼす。
+            // その場合は 60 秒待つことになる（実 embed では init が約 3 秒後に届く）。
+            await withinDeadline(page.setContent(`<!doctype html><html><body style="margin:0">`
+                + `<iframe id="d" style="width:${VIEWPORT.width.toString()}px;height:${VIEWPORT.height.toString()}px;border:0"></iframe>`
+                + `</body></html>`, { waitUntil: 'domcontentloaded', timeout: EXPORT_TIMEOUT_MS }));
+            contentLoadSeconds = elapsedSeconds();
+            const payload = {
+                xml: xmlString,
+                format: options.format,
+                events: { init: EVENT_INIT, load: EVENT_LOAD, exportEvent: EVENT_EXPORT },
+                embedUrl: EMBED_URL,
+            };
+            await withinDeadline(page.evaluate(installEmbedHandshake, payload));
+            handshakeSeconds = elapsedSeconds();
+            const dataUri = await withinDeadline(dataUriPromise);
+            return decodeExportDataUri(dataUri);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    finally {
+        await browser.close();
+    }
+}
+// embed.diagrams.net（Cloudflare 配下）は、User-Agent に `HeadlessChrome` を含む要求を 403 で拒否する。
+// 拒否は 2026-10-07〜10-13 の間に始まった（#1166）。
+// 起動した Chromium が名乗る User-Agent の `HeadlessChrome` だけを `Chrome` に置き換える。
+// 版の数字は、起動した Chromium のものをそのまま使う。
+async function headedUserAgent(browser) {
+    const session = await browser.newBrowserCDPSession();
+    try {
+        const { userAgent } = await session.send('Browser.getVersion');
+        return userAgent.replace('HeadlessChrome', 'Chrome');
+    }
+    finally {
+        await session.detach();
+    }
+}
+// `data:<mime>;base64,<payload>` を decode する。
+// prefix が想定外の形なら、空ファイルを通知なしに書き出さず、明示エラーにする。
+function decodeExportDataUri(dataUri) {
+    const match = /^data:[^;,]+;base64,(?<payload>.*)$/s.exec(dataUri);
+    if (match?.groups?.['payload'] === undefined) {
+        throw new Error(`embed export の応答が base64 data URI ではありません: ${dataUri.slice(0, 60)}`);
+    }
+    return Buffer.from(match.groups['payload'], 'base64');
+}
+// ブラウザ context で実行される handshake installer。Node 側からは page.evaluate で注入される。
+// Node 側で実行されないため、ここで使う globalThis / document は page 内のものに解決される。
+//
+// embed は init を再送しないため、message の listener を付けてから iframe の src を設定する（順序が要る）。
+function installEmbedHandshake(payload) {
+    const { xml, format, events, embedUrl } = payload;
+    const iframe = document.querySelector('#d');
+    if (!iframe?.contentWindow) {
+        throw new Error('embed iframe not mounted');
+    }
+    const target = iframe.contentWindow;
+    // exposeFunction で page 側に install された host bridge。
+    // eslint-disable-next-line no-restricted-syntax -- exposeFunction で動的注入された関数を ExportBridge に narrowing
+    const bridge = globalThis;
+    // 診断用の通知。失敗しても本処理（postMessage / export の受け渡し）を止めないよう、本処理の後に呼んで握りつぶす。
+    const report = (event) => {
+        try {
+            bridge.__pecotvOnProgress(event);
+        }
+        catch {
+            // 診断の失敗で書き出しを落とさない
+        }
+    };
+    // eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- MessageEvent は標準型
+    globalThis.addEventListener('message', (event) => {
+        // 応答するのは embed の iframe からの message だけ。
+        // 他の window からの message では、load / export を送らない。
+        if (event.source !== target)
+            return;
+        let message;
+        try {
+            // eslint-disable-next-line no-restricted-syntax -- JSON.parse 戻りを PostMessage に narrowing
+            message = JSON.parse(String(event.data));
+        }
+        catch {
+            return;
+        }
+        if (message.event === events.init) {
+            target.postMessage(JSON.stringify({ action: 'load', xml }), '*');
+            report(events.init);
+        }
+        else if (message.event === events.load) {
+            target.postMessage(JSON.stringify({ action: 'export', format, scale: 1, border: 0 }), '*');
+            report(events.load);
+        }
+        else if (message.event === events.exportEvent && typeof message.data === 'string') {
+            bridge.__pecotvOnExport(message.data);
+            report(events.exportEvent);
+        }
+    });
+    // listener を付けた後に読み込みを始める。
+    iframe.src = embedUrl;
+}
+/* eslint-enable security/detect-non-literal-fs-filename */
+//# sourceMappingURL=screenshot.js.map

package/cli/dist/infra/evidence-xlsx/workbook-writer.d.ts

@@ -0,0 +1,38 @@
+import type { NormalizedEvidenceSpec } from '../../domain/evidence-xlsx/spec-schema.js';
+/**
+除外理由。contracts/evidence-cli.md §1 の skip 語彙。
+*/
+export type EvidenceSkipReason = 'not-found' | 'unsupported-format' | 'unreadable';
+/**
+生成を中断する理由。CLI が --json の `reason` にそのまま載せる。
+*/
+export type EvidenceWorkbookErrorReason = 'no-valid-images' | 'output-write-failed';
+export interface EvidenceSkippedImage {
+    readonly path: string;
+    readonly reason: EvidenceSkipReason;
+}
+export interface EvidenceWriteResult {
+    /**
+    書き出した xlsx のパス (絶対パス化は command 層の責務)。
+    */
+    readonly outPath: string;
+    /**
+    配置した項目数 = 有効画像数。
+    */
+    readonly items: number;
+    /**
+    配置した注記数。除外画像に付いていた注記は数えない。
+    */
+    readonly annotations: number;
+    readonly skipped: readonly EvidenceSkippedImage[];
+}
+export declare class EvidenceWorkbookError extends Error {
+    readonly reason: EvidenceWorkbookErrorReason;
+    constructor(message: string, reason: EvidenceWorkbookErrorReason);
+}
+/**
+有効画像を配置した xlsx を outPath へ書き出す。有効画像が 1 件も無ければ
+`EvidenceWorkbookError('no-valid-images')` で失敗し、出力ファイルには触れない。
+*/
+export declare function writeEvidenceWorkbook(spec: Readonly<NormalizedEvidenceSpec>, outPath: string): Promise<EvidenceWriteResult>;
+//# sourceMappingURL=workbook-writer.d.ts.map

package/cli/dist/infra/evidence-xlsx/workbook-writer.js

@@ -0,0 +1,140 @@
+// EvidenceSpec から xlsx を書き出す infra 層のエントリポイント。
+//
+// 受け取るのは parseEvidenceSpec が正規化済みの spec。省略可能フィールドが
+// 埋まっているので、ここから下流は `?? []` の防御を書かない。
+//
+// 処理順は「全画像を読んで skip 分類 → 有効 0 件なら書き出しに触れずエラー →
+// XML 生成 → zip 組立 → 上書き書出」。
+// 有効 0 件で出力を開かないのは、既存の `--out` を truncate しないため (data-model §4: 部分生成物を残さない)。
+//
+// yazl のラッパは pptx 側の YazlPptxWriter を流用せず、finish の Promise 化だけを書き写している。
+// evidence は media を無圧縮でそのまま入れる / entry 順を固定する、といった要求を持つ。
+// これが pptx ポートの契約と別で、ポートを共有すると双方の制約が混在するため。
+// yazl の ZipFile は内部状態を持つ mutable オブジェクトで、readonly 化できない。
+// そのため prefer-readonly-parameter-types を本ファイル全体で無効化する (archive.ts と同流儀)。
+/* eslint-disable security/detect-non-literal-fs-filename -- path は CLI 引数由来で信頼境界外を受理する */
+/* eslint-disable @typescript-eslint/prefer-readonly-parameter-types -- yazl ZipFile は mutable */
+import { createWriteStream } from 'node:fs';
+import { readFile } from 'node:fs/promises';
+import { ZipFile } from 'yazl';
+import { readImageDimensions } from '../../domain/evidence-xlsx/image-dimensions.js';
+import { buildEvidenceLayout } from '../../domain/evidence-xlsx/layout.js';
+import { buildContentTypesXml, buildDrawingRelsXml, buildDrawingXml, buildRootRelsXml, buildSheetRelsXml, buildSheetXml, buildStylesXml, buildWorkbookRelsXml, buildWorkbookXml, mediaPartName, PART_CONTENT_TYPES, PART_DRAWING, PART_DRAWING_RELS, PART_ROOT_RELS, PART_SHEET, PART_SHEET_RELS, PART_STYLES, PART_WORKBOOK, PART_WORKBOOK_RELS, } from '../../domain/evidence-xlsx/ooxml.js';
+export class EvidenceWorkbookError extends Error {
+    reason;
+    constructor(message, reason) {
+        super(message);
+        this.reason = reason;
+        this.name = 'EvidenceWorkbookError';
+    }
+}
+/**
+有効画像を配置した xlsx を outPath へ書き出す。有効画像が 1 件も無ければ
+`EvidenceWorkbookError('no-valid-images')` で失敗し、出力ファイルには触れない。
+*/
+export async function writeEvidenceWorkbook(spec, outPath) {
+    const loaded = [];
+    const skipped = [];
+    // 逐次読み込み。連番と skip 一覧を items の配列順どおりに決めるため並行化しない。
+    for (const item of spec.items) {
+        const read = await readImageFile(item.imagePath);
+        if (!read.ok) {
+            skipped.push({ path: item.imagePath, reason: read.reason });
+            continue;
+        }
+        const dimensions = readImageDimensions(read.bytes);
+        if (!dimensions.ok) {
+            skipped.push({ path: item.imagePath, reason: dimensions.reason });
+            continue;
+        }
+        loaded.push({
+            item,
+            bytes: read.bytes,
+            format: dimensions.format,
+            width: dimensions.width,
+            height: dimensions.height,
+        });
+    }
+    if (loaded.length === 0) {
+        throw new EvidenceWorkbookError(`配置できる画像がありません (${spec.items.length.toString()} 件すべて除外)`, 'no-valid-images');
+    }
+    // media 名と No.<n> は、「有効画像だけの連番」で振り直す (contracts §3: 欠番なし)。
+    const media = loaded.map((image, offset) => ({
+        part: mediaPartName(offset + 1, image.format),
+        bytes: image.bytes,
+    }));
+    const layout = buildEvidenceLayout({
+        title: spec.title,
+        createdDate: spec.createdDate,
+        extraHeaders: spec.extraHeaders,
+        images: loaded,
+    });
+    const zip = new ZipFile();
+    // [Content_Types].xml を先頭エントリに置く (OPC の慣行。一部リーダが先頭前提で読む)。
+    addText(zip, PART_CONTENT_TYPES, buildContentTypesXml(loaded.map(image => image.format)));
+    addText(zip, PART_ROOT_RELS, buildRootRelsXml());
+    addText(zip, PART_WORKBOOK, buildWorkbookXml(layout.sheetName));
+    addText(zip, PART_WORKBOOK_RELS, buildWorkbookRelsXml());
+    addText(zip, PART_SHEET, buildSheetXml(layout));
+    addText(zip, PART_SHEET_RELS, buildSheetRelsXml());
+    addText(zip, PART_STYLES, buildStylesXml());
+    addText(zip, PART_DRAWING, buildDrawingXml(layout.placements));
+    addText(zip, PART_DRAWING_RELS, buildDrawingRelsXml(media.map(entry => entry.part)));
+    for (const entry of media) {
+        // 入力画像は無加工コピー (FR-005)。PNG / JPEG は既に圧縮済みで deflate が働かないため、
+        // 時間と出力サイズを無駄にしないよう compress: false で格納する。
+        zip.addBuffer(entry.bytes, entry.part, { compress: false });
+    }
+    try {
+        await finishZip(zip, outPath);
+    }
+    catch (error) {
+        throw new EvidenceWorkbookError(`xlsx を書き出せません: ${outPath} (${formatError(error)})`, 'output-write-failed');
+    }
+    return {
+        outPath,
+        items: loaded.length,
+        // layout が導出した図形を数える。除外画像は placements に入らないので自然に外れる。
+        annotations: layout.placements.flatMap(placement => placement.annotationShapes).length,
+        skipped,
+    };
+}
+/**
+画像を読む。ENOENT だけを not-found とする。
+EACCES / EISDIR 等の「存在するが読めない」は unreadable に寄せる (contracts §1 の skip 語彙は 3 種のみ)。
+*/
+async function readImageFile(imagePath) {
+    try {
+        return { ok: true, bytes: await readFile(imagePath) };
+    }
+    catch (error) {
+        return { ok: false, reason: errnoCode(error) === 'ENOENT' ? 'not-found' : 'unreadable' };
+    }
+}
+function errnoCode(error) {
+    /* c8 ignore next -- fs.readFile の reject は常に code つき Error のため到達不能、防御網のみ */
+    return error instanceof Error && 'code' in error && typeof error.code === 'string' ? error.code : undefined;
+}
+function addText(zip, part, xml) {
+    zip.addBuffer(Buffer.from(xml, 'utf8'), part);
+}
+/**
+yazl の outputStream をファイルへ流し切るまで待つ。
+*/
+function finishZip(zip, outPath) {
+    return new Promise((resolve, reject) => {
+        const writeStream = createWriteStream(outPath);
+        writeStream.on('error', reject);
+        writeStream.on('finish', resolve);
+        /* c8 ignore next -- outputStream 側の error は組立済み Buffer のみを流すため再現不能 */
+        zip.outputStream.on('error', reject);
+        zip.outputStream.pipe(writeStream);
+        zip.end();
+    });
+}
+/* c8 ignore start -- 非 Error 例外 (string throw 等) は fs / stream 経由では発生しない、防御網のみ */
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+/* c8 ignore stop */
+//# sourceMappingURL=workbook-writer.js.map

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

@@ -0,0 +1,96 @@
+import type { SpawnResult } from '../../domain/_shared/spawn-result.js';
+/**
+取得を自動で行ってよいかを示す opt-in の環境変数。
+*/
+export declare const AUTO_INSTALL_ENV = "PECOTV_AUTO_INSTALL_BROWSER";
+/**
+Playwright がブラウザを置くディレクトリ。判定できないときは undefined。
+
+取得済みかの判定には使わない (判定は Playwright 自身の解決に寄せる。
+chromiumBrowserDirectory を参照)。ここで求めるのは「どこに期待しているか」を
+利用者へ示すための表示用の場所で、PLAYWRIGHT_BROWSERS_PATH を尊重する。
+`0` はパッケージ同梱位置を指す特殊値で場所を特定できないため undefined を返す。
+*/
+export declare function browsersRoot(): string | undefined;
+/**
+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 declare function chromiumBrowserDirectory(): Promise<string | undefined>;
+/**
+Chromium バイナリが取得済みかを判定する。
+
+見るのは、Playwright が取得完了時に置く INSTALLATION_COMPLETE マーカー。
+これは playwright-core の browserFetcher が完了判定に使うのと同じもの。
+ディレクトリの存在だけでは、展開先が先に作られるダウンロード途中の状態を、取得済みと誤判定する。
+bin/pecotv の bootstrap も同じマーカーを見る。
+
+判定に失敗したとき (playwright を解決できない・当該 platform 非対応) は、取得済み扱いで通す。
+誤検知で使える機能を塞ぐより、実際の起動失敗を各コマンドのエラーとして返す。その方が害は小さい。
+*/
+export declare function isChromiumInstalled(): Promise<boolean>;
+/**
+PECOTV_AUTO_INSTALL_BROWSER による自動取得が有効か。
+*/
+export declare function isAutoInstallEnabled(): boolean;
+/**
+`playwright` パッケージの CLI エントリの絶対パス。
+
+`playwright/cli.js` は package.json の exports に載っていないため直接は解決できない。
+exports に載っている `playwright/package.json` からパッケージ root を求めて join する。
+node_modules が破損している / playwright が未 install の環境では同期 throw する。
+*/
+export declare function resolvePlaywrightCli(): string;
+/**
+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 declare function installLockPath(): string | undefined;
+export interface InstallChromiumOptions {
+    /**
+    呼び出し元 (MCP の tools/call) がキャンセルされたら取得も打ち切る。
+    */
+    readonly signal?: AbortSignal | undefined;
+    /**
+    playwright CLI の解決口。既定は resolvePlaywrightCli で、テストが解決失敗を差し込む。
+    */
+    readonly resolveCli?: (() => string) | undefined;
+}
+/**
+`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 declare function installChromium(options?: InstallChromiumOptions): Promise<SpawnResult>;
+//# sourceMappingURL=chromium.d.ts.map