@pecot/visual-mcp 0.0.0-stage → 1.0.0

package/cli/dist/infra/slidev-theme/store.js

@@ -0,0 +1,430 @@
+// テーマの置き場（ThemeStore）への取得。
+//
+// git kind は `${storeRoot}/<hash>/<tag>/` に、取得物（`package/`）と `stamp.json` を置く。
+// 手順は git でタグだけを解決し、pnpm で依存を入れ、patch を当て、stamp を書いて rename で置く。
+// 途中で失敗したものは一時ディレクトリごと消すので、半端な置き場は残らない。
+// file kind は置き場に取り込まず、作り手のディレクトリの実体を指す。
+//
+// 置き場の形・stamp・失敗の分類は domain/slidev-theme/store-layout.ts にある。
+// ここは外部 I/O（git・pnpm・patch-package の子プロセスとファイル）を担う。
+//
+// 子プロセスは runner（spawnPromise と同じ signature）で起こす。テストは呼び出しを数えるために差し替える。
+// 読み書きするのは呼び出し元が渡す storeRoot と baseDirectory の配下だけ。
+// そのため本ファイル全体で security/detect-non-literal-fs-filename を disable する。
+/* eslint-disable security/detect-non-literal-fs-filename */
+import { existsSync } from 'node:fs';
+import { mkdir, mkdtemp, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { compareStrings } from '../../domain/_shared/compare-strings.js';
+import { isRecord } from '../../domain/_shared/json.js';
+import { classifyGitFailure, computeInputsHash, gitFailureAdvice, parseThemeStamp, ThemeFetchError, themeStoreDirectory, } from '../../domain/slidev-theme/store-layout.js';
+import { resolveDependency } from '../_shared/dependency-root.js';
+import { LOCK_CONFLICT_EXIT_CODE, withFlock } from '../_shared/flock.js';
+import { applyPatches, scanPatchDigests } from '../_shared/patch-apply.js';
+import { resolvePluginRoot } from '../_shared/plugin-root.js';
+import { resolvePnpmCommand } from '../_shared/pnpm.js';
+import { spawnPromise } from '../_shared/process.js';
+/**
+子プロセス 1 本あたりの上限時間 (ms)。実行時依存の取得（631MB で 37 秒）に合わせた余裕を取る。
+*/
+const FETCH_TIMEOUT_MS = 600_000;
+/**
+クラッシュで残った一時ディレクトリとみなす経過時間 (ms)。
+他プロセスが取得中の一時ディレクトリを消さないよう、子プロセスの上限より十分長く取る。
+*/
+const STALE_TEMPORARY_AGE_MS = 60 * 60 * 1000;
+const PNPM_INSTALL_ARGUMENTS = [
+    'install',
+    '--prod',
+    '--ignore-scripts',
+    '--ignore-workspace',
+    '--config.auto-install-peers=false',
+    '--config.node-linker=hoisted',
+    '--config.pm-on-fail=ignore',
+    // CI=true では pnpm が frozen-lockfile を既定にする。同梱の lock がずれていても、置き場の中で更新して通す。
+    '--config.frozen-lockfile=false',
+    // 既定の hard link では、patch が pnpm の store（と file: の元ディレクトリ）の実体を書き換える。コピーで入れる。
+    '--config.package-import-method=copy',
+];
+const GIT_ENVIRONMENT_REMOVED = ['GIT_DIR', 'GIT_WORK_TREE', 'GIT_INDEX_FILE'];
+/**
+テーマを置き場へ取得する。取得済みで中身が合えば再利用する。
+*/
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- AbortSignal と関数を持つ
+export async function fetchTheme(spec, options) {
+    return spec.kind === 'file' ? referenceLocalTheme(spec.path, options) : fetchGitTheme(spec, options);
+}
+// npm のパッケージ名の 1 区間の規則。先頭に . と _ は使えない。
+const PACKAGE_NAME_SEGMENT = /^[a-z0-9~-][a-z0-9._~-]*$/u;
+/**
+npm のパッケージ名か。/ は `@scope/name` の 1 個だけ許す。
+*/
+function isPackageName(name) {
+    const segments = name.startsWith('@') ? name.slice(1).split('/') : [name];
+    const expected = name.startsWith('@') ? 2 : 1;
+    return segments.length === expected && segments.every(segment => PACKAGE_NAME_SEGMENT.test(segment));
+}
+function parseManifest(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(text);
+    }
+    catch {
+        parsed = undefined;
+    }
+    if (!isRecord(parsed))
+        return { name: undefined, dependencyNames: [] };
+    const dependencies = parsed['dependencies'];
+    return {
+        name: typeof parsed['name'] === 'string' && parsed['name'] !== '' ? parsed['name'] : undefined,
+        dependencyNames: isRecord(dependencies) ? Object.keys(dependencies) : [],
+    };
+}
+function requireName(manifest, directory) {
+    if (manifest.name === undefined) {
+        throw new ThemeFetchError(`テーマの package.json に name がありません (${directory})`, 'unknown');
+    }
+    if (!isPackageName(manifest.name)) {
+        throw new ThemeFetchError(`テーマの package.json の name がパッケージ名として使えません (${manifest.name})`, 'unknown');
+    }
+    return manifest.name;
+}
+/**
+file kind。置き場に取り込まず、実体を指す。install はしない（作り手の node_modules を壊さない）。
+*/
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- AbortSignal と関数を持つ
+async function referenceLocalTheme(themePath, options) {
+    const directory = path.resolve(options.baseDirectory, themePath);
+    let text;
+    try {
+        text = await readFile(path.join(directory, 'package.json'), 'utf8');
+    }
+    catch {
+        throw new ThemeFetchError(`テーマのディレクトリに package.json がありません (${directory})`, 'unknown');
+    }
+    const manifest = parseManifest(text);
+    if (manifest.dependencyNames.length > 0 && !existsSync(path.join(directory, 'node_modules'))) {
+        throw new ThemeFetchError(`テーマのディレクトリで install を実行してください (${directory} に node_modules がありません)`, 'install');
+    }
+    return { name: requireName(manifest, directory), directory, reused: false };
+}
+/**
+置き場が取得済みとして使えるか。使えるなら name を返す。
+
+stamp の spec が一致し、置き場の実体から再計算した inputsHash が一致するときだけ使う。
+dependencies を持つときは `package/node_modules/.modules.yaml` の存在も見る。
+利用者が node_modules だけ消した置き場を、取得済みにしないため。
+*/
+async function reusableName(directory, spec) {
+    let stamp;
+    let manifestText;
+    try {
+        stamp = parseThemeStamp(await readFile(path.join(directory, 'stamp.json'), 'utf8'));
+        manifestText = await readFile(path.join(directory, 'package', 'package.json'), 'utf8');
+    }
+    catch {
+        return undefined;
+    }
+    if (stamp?.spec.url !== spec.url || stamp.spec.tag !== spec.tag)
+        return undefined;
+    const scan = scanPatchDigests(path.join(directory, 'package', 'patches'));
+    if (scan.error !== undefined || computeInputsHash(manifestText, scan.digests) !== stamp.inputsHash)
+        return undefined;
+    const manifest = parseManifest(manifestText);
+    return manifest.dependencyNames.length > 0 && !existsSync(path.join(directory, 'package', 'node_modules', '.modules.yaml')) ? undefined : manifest.name;
+}
+function gitEnvironment() {
+    const environment = { ...process.env, LC_ALL: 'C', GIT_TERMINAL_PROMPT: '0' };
+    for (const name of GIT_ENVIRONMENT_REMOVED)
+        Reflect.deleteProperty(environment, name);
+    return environment;
+}
+/**
+git kind。
+*/
+async function fetchGitTheme(spec, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- AbortSignal と関数を持つ
+options) {
+    const storeSpec = { url: spec.url, tag: spec.tag };
+    const directory = themeStoreDirectory(options.storeRoot, storeSpec);
+    const hashDirectory = path.dirname(directory);
+    await mkdir(hashDirectory, { recursive: true });
+    const cached = await reusableName(directory, storeSpec);
+    if (cached !== undefined)
+        return reusedTheme(directory, cached);
+    await removeStaleTemporaries(hashDirectory, spec.tag);
+    // 使えない置き場（途中で止まった、書き換えられた）は、place が rename の行き先を空けて置き直す。
+    const temporary = await mkdtemp(path.join(hashDirectory, `.${spec.tag}.tmp-`));
+    try {
+        const populated = await populate({
+            storeSpec,
+            directory,
+            temporary,
+            lockPath: path.join(hashDirectory, `.${spec.tag}.lock`),
+            pluginRoot: resolvePluginRoot(),
+        }, options);
+        if (populated.adopted) {
+            await rm(temporary, { recursive: true, force: true });
+            return reusedTheme(directory, populated.name);
+        }
+        return await place(temporary, directory, storeSpec, populated.name);
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true });
+        await removeEmptyHashDirectory(hashDirectory);
+        throw error;
+    }
+}
+function reusedTheme(directory, name) {
+    return { name, directory: path.join(directory, 'package'), reused: true };
+}
+/**
+取得物を一時ディレクトリの中に作る。成功したら name を返す。
+時間のかかる pnpm と patch の前に行き先を確かめ、別プロセスが先に置いていれば、そこで打ち切って既存を使う。
+*/
+async function populate(context, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- AbortSignal と関数を持つ
+options) {
+    const { storeSpec, directory, temporary, lockPath, pluginRoot } = context;
+    const packageDirectory = path.join(temporary, 'package');
+    await mkdir(packageDirectory);
+    const run = async (command, commandArguments, environment) => {
+        const locked = withFlock(lockPath, command, commandArguments);
+        return (options.runner ?? spawnPromise)(locked.command, locked.commandArguments, {
+            cwd: packageDirectory,
+            env: environment,
+            timeoutMs: FETCH_TIMEOUT_MS,
+            signal: options.signal,
+        });
+    };
+    const placedElsewhere = async () => {
+        const existing = await reusableName(directory, storeSpec);
+        return existing === undefined ? undefined : { name: existing, adopted: true };
+    };
+    await fetchTag(storeSpec, packageDirectory, run);
+    // pnpm は package.json が無いと自分の言葉で失敗する。先に読んで、原因をそのまま伝える。
+    const manifestText = await readManifestText(packageDirectory);
+    // 名前が使えないテーマは、依存を入れる前に止める。
+    const name = requireName(parseManifest(manifestText), packageDirectory);
+    const beforePnpm = await placedElsewhere();
+    if (beforePnpm !== undefined)
+        return beforePnpm;
+    const pnpm = resolvePnpmCommand(pluginRoot);
+    // cwd がテーマ側のため、テーマの packageManager で corepack が止まらないようにする。
+    const installed = await run(pnpm.command, [...pnpm.commandArguments, ...PNPM_INSTALL_ARGUMENTS], { ...process.env, COREPACK_ENABLE_STRICT: '0' });
+    assertStarted(installed, 'pnpm', 'install');
+    if (installed.exitCode !== 0)
+        throw installFailure('テーマの依存を pnpm で取得できませんでした', installed);
+    const patchesDirectory = path.join(packageDirectory, 'patches');
+    const scan = scanPatchDigests(patchesDirectory);
+    if (scan.error !== undefined)
+        throw new ThemeFetchError(scan.error, 'install');
+    const beforePatch = await placedElsewhere();
+    if (beforePatch !== undefined)
+        return beforePatch;
+    await applyThemePatches(packageDirectory, patchesDirectory, scan.digests, lockPath, options);
+    await warnSameNameDependencies(parseManifest(manifestText).dependencyNames, options);
+    const stamp = {
+        spec: storeSpec,
+        fetchedAt: new Date().toISOString(),
+        inputsHash: computeInputsHash(manifestText, scan.digests),
+    };
+    await writeFile(path.join(temporary, 'stamp.json'), `${JSON.stringify(stamp, undefined, 2)}\n`, 'utf8');
+    return { name, adopted: false };
+}
+/**
+git でタグだけを解決する。`git clone --branch` は同名のブランチを優先するため使わない。
+annotated tag でも FETCH_HEAD はコミットへ剥がれる。
+*/
+async function fetchTag(spec, packageDirectory, run) {
+    const environment = gitEnvironment();
+    const steps = [
+        ['init', '-q'],
+        ['-c', 'advice.detachedHead=false', 'fetch', '-q', '--depth', '1', spec.url, `refs/tags/${spec.tag}`],
+        ['-c', 'advice.detachedHead=false', 'checkout', '-q', '--detach', 'FETCH_HEAD'],
+    ];
+    for (const step of steps) {
+        const result = await run('git', step, environment);
+        assertStarted(result, 'git', 'connection');
+        if (result.exitCode === 0)
+            continue;
+        const kind = classifyGitFailure(result.stderr);
+        throw new ThemeFetchError(`${gitFailureAdvice(kind, spec)}\n${result.stderr.trim()}`, kind);
+    }
+    // 取得物に .git は要らない。置き場の中身を取得物だけにする。
+    await rm(path.join(packageDirectory, '.git'), { recursive: true, force: true });
+}
+async function readManifestText(packageDirectory) {
+    try {
+        return await readFile(path.join(packageDirectory, 'package.json'), 'utf8');
+    }
+    catch {
+        throw new ThemeFetchError('テーマのリポジトリ直下に package.json がありません', 'install');
+    }
+}
+function installFailure(summary, result) {
+    return new ThemeFetchError(`${summary}\n${result.stderr.trim()}`, 'install');
+}
+/**
+終了コードの文言で分ける前に、ロック待ちの超過・時間切れ・起動失敗を、対処付きの失敗にする。
+timedOutReason は時間切れの分類。git は接続の待ちなので connection、それ以外は install。
+*/
+function assertStarted(result, tool, timedOutReason) {
+    if (result.exitCode === LOCK_CONFLICT_EXIT_CODE) {
+        throw new ThemeFetchError('別のプロセスが同じテーマを取得中です。完了を待って再実行してください', 'install');
+    }
+    if (result.timedOut) {
+        throw new ThemeFetchError(`${tool} が時間切れで中断しました。ネットワークを確認して再実行してください`, timedOutReason);
+    }
+    if (result.exitCode !== null)
+        return;
+    const detail = result.stderr.trim();
+    throw new ThemeFetchError(`${tool} を起動できません。導入を確認してください${detail === '' ? '' : `\n${detail}`}`, 'install');
+}
+/**
+package/patches/ のパッチを当てる。パッチが無ければ何もしない。
+patch-package の実体は本体の依存から解決する。解決できなければ install の失敗として返す。
+*/
+async function applyThemePatches(packageDirectory, patchesDirectory, patches, lockPath, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- AbortSignal と関数を持つ
+options) {
+    if (patches.length === 0)
+        return;
+    const manifestPath = resolveDependency('patch-package/package.json', import.meta.url);
+    /* c8 ignore start -- 本体の依存に patch-package を同梱しているため、テストでは再現できない防御網 */
+    if (manifestPath === undefined) {
+        throw new ThemeFetchError('patch-package を本体の依存から解決できないため、テーマの patch を当てられません', 'install');
+    }
+    /* c8 ignore stop */
+    const result = await applyPatches({
+        root: packageDirectory,
+        patchesDirectory,
+        patches,
+        patchPackageEntry: path.join(path.dirname(manifestPath), 'index.js'),
+        lockPath,
+        runner: options.runner,
+        signal: options.signal,
+    });
+    if (result !== undefined)
+        assertStarted(result, 'patch-package', 'install');
+    if (result !== undefined && result.exitCode !== 0)
+        throw installFailure('テーマの patch を当てられませんでした', result);
+}
+/**
+node_modules 直下のパッケージ名。`@scope` は配下の名前まで展開し、`.` 始まりの項目は数えない。
+*/
+async function packageNames(nodeModules) {
+    const names = new Set();
+    let entries;
+    try {
+        entries = await readdir(nodeModules);
+    }
+    catch {
+        return names;
+    }
+    for (const entry of entries) {
+        if (entry.startsWith('.'))
+            continue;
+        if (!entry.startsWith('@')) {
+            names.add(entry);
+            continue;
+        }
+        try {
+            const children = await readdir(path.join(nodeModules, entry));
+            for (const child of children)
+                names.add(`${entry}/${child}`);
+        }
+        catch {
+            // scope ディレクトリを読めなければ、その配下は数えない。
+        }
+    }
+    return names;
+}
+/**
+テーマが dependencies に宣言した名前が本体の依存と重なるとき、peerDependencies への移動を促す。
+推移依存は利用者が移せないため、宣言した名前だけを比べる。
+peer にすれば、生成する vite.config.ts の resolve.dedupe で本体の 1 つに寄る。拒まないのは移行の途中を通すため。
+*/
+async function warnSameNameDependencies(declared, 
+// eslint-disable-next-line @typescript-eslint/prefer-readonly-parameter-types -- AbortSignal と関数を持つ
+options) {
+    if (options.warn === undefined)
+        return;
+    const base = await packageNames(path.join(options.dependencyRoot, 'node_modules'));
+    const overlapping = declared.filter(name => base.has(name)).toSorted((left, right) => compareStrings(left, right));
+    if (overlapping.length === 0)
+        return;
+    options.warn(`テーマの dependencies に本体と同名のパッケージがあります: ${overlapping.join(', ')}。`
+        + '本体の 1 つに寄せるには、テーマの package.json で peerDependencies へ移してください。');
+}
+/**
+一時ディレクトリを `<tag>/` へ置く。
+rename が ENOTEMPTY か EEXIST なら、行き先に先客がいる。
+先客が有効な置き場なら、自分の分を消して再利用として返す。
+無効（途中で止まった、書き換えられた）なら、先客を消して置き直す。
+*/
+async function place(temporary, directory, storeSpec, name) {
+    try {
+        await rename(temporary, directory);
+    }
+    catch (error) {
+        if (!isRecord(error) || (error['code'] !== 'ENOTEMPTY' && error['code'] !== 'EEXIST'))
+            throw error;
+        const existing = await reusableName(directory, storeSpec);
+        if (existing !== undefined) {
+            await rm(temporary, { recursive: true, force: true });
+            return reusedTheme(directory, existing);
+        }
+        await rm(directory, { recursive: true, force: true });
+        try {
+            await rename(temporary, directory);
+        }
+        /* c8 ignore start -- 消した直後に別プロセスが置く競合で、テストでは再現できない */
+        catch {
+            // 消した直後に別プロセスが置いた。読めない置き場として止め、利用者の再実行に任せる。
+            throw new ThemeFetchError(`テーマの置き場を置き直せません。${directory} を削除してやり直してください`, 'unknown');
+        }
+        /* c8 ignore stop */
+    }
+    return { name, directory: path.join(directory, 'package'), reused: false };
+}
+/**
+取得に失敗したあと、`<hash>/` に `.lock` しか残っていなければ、それらと空の `<hash>/` を消す。
+`<tag>/` や他の一時ディレクトリが残っていれば、取得済みか取得中の別プロセスがいるため何もしない。
+*/
+async function removeEmptyHashDirectory(hashDirectory) {
+    try {
+        const entries = await readdir(hashDirectory);
+        if (entries.some(entry => !entry.endsWith('.lock')))
+            return;
+        await Promise.all(entries.map(async (entry) => rm(path.join(hashDirectory, entry), { force: true })));
+        // 空でなければ ENOTEMPTY で止まる。別プロセスが何かを置いた場合は消さない。
+        await rmdir(hashDirectory);
+    }
+    catch {
+        // 別プロセスが先に消した、または何かを置いた。
+    }
+}
+/**
+クラッシュで残った `.<tag>.tmp-*` を消す。
+他プロセスが取得中のものを消さないよう、十分古いものだけを対象にする。
+*/
+async function removeStaleTemporaries(hashDirectory, tag) {
+    const prefix = `.${tag}.tmp-`;
+    const entries = await readdir(hashDirectory);
+    for (const entry of entries) {
+        if (!entry.startsWith(prefix))
+            continue;
+        const target = path.join(hashDirectory, entry);
+        try {
+            const { mtimeMs } = await stat(target);
+            if (Date.now() - mtimeMs > STALE_TEMPORARY_AGE_MS) {
+                await rm(target, { recursive: true, force: true });
+            }
+        }
+        catch {
+            // 別プロセスが先に消した。
+        }
+    }
+}
+//# sourceMappingURL=store.js.map

package/cli/dist/infra/slidev-to-pptx/cache-store.d.ts

@@ -0,0 +1,205 @@
+import { type CacheManifest, type LetterSpacingEntry, type SlideCacheEntry } from '../../domain/slidev-to-pptx/cache-manifest.js';
+import { type ExportToPptxOptions } from '../../domain/slidev-to-pptx/config.js';
+/**
+cache-store の依存注入。既定は node:fs/promises の実装で、テストでは rename を
+失敗させる等の注入に使う（PipelineDependencies と同じ形）。
+*/
+export interface CacheStoreDeps {
+    readonly renameImpl?: (oldPath: string, newPath: string) => Promise<void>;
+    readonly copyFileImpl?: (source: string, destination: string) => Promise<void>;
+    readonly writeFileImpl?: (filePath: string, data: string) => Promise<void>;
+}
+/**
+デッキ環境ハッシュ / スライドハッシュの算出に必要な入力。
+*/
+export interface DeckCacheKeyOptions {
+    /**
+    slides.md を含むプレゼンプロジェクトのルート（talk-dir）
+    */
+    readonly projectDirectory: string;
+    /**
+    slides.md の絶対パス
+    */
+    readonly slidesPath: string;
+    /**
+    解決済み dom-to-pptx.bundle.js の絶対パス。実体の内容ハッシュだけを取る
+    */
+    readonly domToPptxBundlePath: string;
+    readonly chromiumVersion: string;
+    readonly pluginVersion: string;
+    /**
+    envHash の材料に加えるビルドオプション（`--theme` 等）。cache-key.ts の EnvHashInput 参照。
+    */
+    readonly buildOptions: Readonly<Record<string, unknown>>;
+    /**
+    exportToPptx へ渡す変換オプション。同じ slides.md・同じ bundle でも値が違えば出力が変わるため
+    envHash の材料に入れる（入れないと疑似要素やフォント埋め込みの設定を変えても旧出力がヒットする）。
+    */
+    readonly exportOptions: Readonly<ExportToPptxOptions>;
+    /**
+    変換方式。1 パス方式（print ルートを 1 回開く）と現行方式（ステップごとにページを開く）は
+    成果物が細部で異なり得るため envHash の材料に入れ、方式を切り替えたら全変換にする。
+    並列度は出力を変えないため入れない。
+  
+    値は実際に通った方式でなく、要求した方式で決める。1 パス方式の run 内で現行 worker に回した
+    ステップや、print ルートが無く run 全体を現行方式で変換した run も `'single-pass'` で保存される。
+    そのため未同期の deck で `--no-single-pass` に切り替えると、成果物が同じでも全変換になる。
+    */
+    readonly route: 'single-pass' | 'per-step';
+}
+export interface DeckCacheKeys {
+    readonly envHash: string;
+    /**
+    slideNumber（1 始まり）→ slideHash
+    */
+    readonly slideHashes: ReadonlyMap<number, string>;
+}
+/**
+キー算出に失敗した理由。呼び出し側（#896）が R4 の警告ログに使う。
+
+- `slides-load-failed`: slides.md を読めない / パーサが例外を投げた。
+- `slides-has-errors`: load() が errors を記録した（src 先の不在等でスライドが欠落し得る）。
+- `bundle-unreadable`: dom-to-pptx.bundle.js の実体を読めない。
+- `invalid-environment`: Chromium / プラグインのバージョン文字列が空。
+*/
+export type DeckCacheKeyFailure = 'slides-load-failed' | 'slides-has-errors' | 'bundle-unreadable' | 'invalid-environment';
+/**
+キー算出の結果。失敗は例外にせず ok:false で返す（キャッシュ由来のエラーで変換自体を
+失敗させない R4 / SC-004 の方針）。`message` は警告ログにそのまま出せる文言。
+*/
+export type DeckCacheKeyResult = {
+    readonly ok: true;
+    readonly keys: DeckCacheKeys;
+} | {
+    readonly ok: false;
+    readonly failure: DeckCacheKeyFailure;
+    readonly message: string;
+};
+/**
+デッキ全体のスキャン結果であることを呼び出し側に明示させるための型。
+`--only` / `--onlySteps` の部分結果で prune すると、キャッシュがほぼ全消去される。
+そのため `fullScan: true` を書かないと、`pruneCache` を呼べない形にしている。
+*/
+export interface FullScanSteps {
+    readonly fullScan: true;
+    readonly stepIndexes: readonly number[];
+}
+/**
+materialize が返す、集約ループにそのまま流せるスライド別マップ断片。
+*/
+export interface MaterializedSlide {
+    readonly letterSpacingMap: Readonly<Record<string, LetterSpacingEntry>>;
+    readonly hrefMap: Readonly<Record<string, string>>;
+    /**
+    当該ステップのスライドが明示指定のアニメーションを持つか（#1070）
+    */
+    readonly hasExplicitAnimation: boolean;
+}
+export interface MaterializeOptions {
+    readonly cacheDirectory: string;
+    readonly slidesDirectory: string;
+    readonly stepIndex: number;
+    /**
+    当該実行の slidePrefix。宛先ファイル名は `${slidePrefix}${stepIndex}.pptx`
+    */
+    readonly slidePrefix: string;
+}
+export interface SaveOptions {
+    readonly cacheDirectory: string;
+    readonly slidesDirectory: string;
+    readonly stepIndex: number;
+    readonly slidePrefix: string;
+    readonly slideHash: string;
+    readonly slideNumber: number;
+    readonly clickStep: number | null;
+    readonly letterSpacingMap: Readonly<Record<string, LetterSpacingEntry>>;
+    readonly hrefMap: Readonly<Record<string, string>>;
+    readonly hasExplicitAnimation: boolean;
+}
+/**
+キャッシュストアの配置。staging の `<outDir>/slides` と対称に `<outDir>/cache` を使う。
+*/
+export declare function cacheDirectoryOf(outputDirectory: string): string;
+/**
+slides.md を分解して envHash と全スライドの slideHash を求める。
+分解に失敗した場合、変換エンジン実体が読めない場合、環境情報が欠けている場合は、ok:false を返す。
+呼び出し側は、キャッシュ全無視（全変換）へフォールバックする。
+*/
+export declare function computeDeckCacheKeys(options: Readonly<DeckCacheKeyOptions>): Promise<DeckCacheKeyResult>;
+/**
+manifest.json の読み取り結果。呼び出し側は「まだ無い」と「あるが使えない」を区別して
+無効化の種別（`none` / `all:manifest`）を報告する必要があるため、undefined にまとめない。
+
+「使えない」は破損（`invalid`）とスキーマ版の不一致（`outdated`）に分かれる。後者は
+プラグインを更新した直後の初回 run で必ず起きる正常事象で、破損と同じ文言で報告すると
+利用者がキャッシュの破損を想定する。
+*/
+export type CacheManifestRead = {
+    readonly status: 'missing';
+} | {
+    readonly status: 'invalid';
+} | {
+    readonly status: 'outdated';
+    readonly schemaVersion: number;
+} | {
+    readonly status: 'ok';
+    readonly manifest: CacheManifest;
+};
+/**
+manifest.json を読む。
+結果は 3 種ある。
+`missing` は不在、`outdated` はスキーマ版の不一致、`invalid` は破損・読み取り失敗。
+いずれも全 miss になる点は同じで、違うのは報告される無効化の種別と文言だけ。
+*/
+export declare function readCacheManifest(cacheDirectory: string): Promise<CacheManifestRead>;
+/**
+manifest.json を一時ファイル + rename で原子的に書き換える。
+
+Phase 1 は並列実行されるため、ステップごとに read-modify-write すると last-write-wins で
+エントリが欠落する。本関数は変換完了後の終端 1 回だけ呼び、全体を書き換える。
+一時ファイルは rename が同一 filesystem 内で完結するよう cache/ 直下に作る。
+*/
+export declare function writeCacheManifest(cacheDirectory: string, manifest: Readonly<CacheManifest>, dependencies?: Readonly<CacheStoreDeps>): Promise<void>;
+/**
+キャッシュ済み成果物を staging（slides/）へ複製する。
+エントリの指す実体が 1 つでも欠けている / 0 バイトなら、undefined を返してミス扱いにする。
+
+prerender 画像は、連番の最初の欠番で走査が打ち切られる（domain/pptx-ooxml の findPrerenderImages）。
+そのため部分復元は、通知なしの差し替え抜けとなる。
+よって複製途中で失敗した場合は、書いた分をすべて撤去してから undefined を返す。
+事前の存在確認と複製の間に実体が消える競合も、この流れに合流してミス扱いになる。
+*/
+export declare function materializeCacheEntry(options: Readonly<MaterializeOptions>, entry: Readonly<SlideCacheEntry>, dependencies?: Readonly<CacheStoreDeps>): Promise<MaterializedSlide | undefined>;
+/**
+変換成功したステップの成果物を cache/ へ保存し、エントリを作る。manifest は触らない
+（並列実行中の書き換えを避けるため、manifest は終端 1 回で書く）。
+
+prerender ファイルの列挙は変換結果からの導出ではなくディレクトリ走査で行う。
+boundingBox が null の要素では PNG だけを書き、meta.json は作らない。この状態は正常に発生するため。
+
+保存に失敗した場合は、書きかけを撤去して undefined を返す。
+エントリが作られないだけで、変換自体は成功のまま進む。
+各ファイルの複製は temp + rename で行うため、中断しても正規名に途中サイズのファイルは現れない。
+*/
+export declare function saveSlideToCache(options: Readonly<SaveOptions>, dependencies?: Readonly<CacheStoreDeps>): Promise<SlideCacheEntry | undefined>;
+/**
+manifest.json が破損して読めない（invalid）場合に、既知パターンの成果物ファイルを cache/ から一括で消す。
+manifest が読めないと、「前回どのエントリが生きていたか」を prune / removeUnreferencedArtifacts が判定できない。
+その結果、削除済みスライドの成果物が `pptx/cache/` に恒久残留する（FR-010）。
+本関数はその救済として、manifest が使えない状態そのものを起点に既知パターンを掃除する。
+今回の run で改めて保存されるため、生存分は saveSlideToCache が復元する。
+*/
+export declare function clearOrphanedCacheArtifacts(cacheDirectory: string): Promise<void>;
+/**
+今回のスキャン結果に無いエントリの成果物を消し、prune 済み manifest を返す
+（書き込みは呼び出し側が writeCacheManifest で行う）。
+
+引数が `FullScanSteps`（`fullScan: true` 必須）なのは契約の担保のため。`--only` /
+`--onlySteps` の部分スキャン結果をそのまま渡すとキャッシュがほぼ全消去されるので、
+呼び出し側に「これは全走査の結果である」と明示させる。部分実行時は本関数を呼ばない。
+
+manifest に載っていない孤児ファイルは v1 では削除しない。cache/ 直下の未知ファイルを
+消す責務を持たせると、並行実行中の別プロセスが書いた一時ファイルまで巻き込むため。
+*/
+export declare function pruneCache(cacheDirectory: string, manifest: Readonly<CacheManifest>, liveSteps: Readonly<FullScanSteps>): Promise<CacheManifest>;
+//# sourceMappingURL=cache-store.d.ts.map