emdash-emit 0.1.18 → 0.1.30

package/dist/sync/pull/media_stage.d.ts

@@ -0,0 +1,67 @@
+import type { CacheDatabase } from '../../db/cache.js';
+import { type LocalMediaMirrorCandidate, type RemoteStorageKeyIndex } from '../media.js';
+import type { MediaMirrorSession, PullArticleMediaSummary, PullOptions } from './types.js';
+export interface MediaMirrorSessionOptions {
+    workspaceRoot: string;
+    origin: string;
+    token: string;
+    refreshToken?: string;
+    cache?: CacheDatabase;
+    fetchFn?: typeof fetch;
+    downloadFiles?: boolean;
+    isSharedSession?: boolean;
+    /** Bounds the shared library walk. Defaults to `mediaSyncLimit`; `all: true` removes the bound. */
+    limit?: number;
+    all?: boolean;
+}
+export declare class MediaMirrorSessionImpl implements MediaMirrorSession {
+    private readonly options;
+    private readonly mediaDir;
+    private readonly isSharedSession;
+    private remoteIndexPromise;
+    private localCandidatesMap;
+    private readonly inFlightAssets;
+    private readonly sessionMirroredStorageKeys;
+    private readonly sessionVerifiedStorageKeys;
+    private readonly sessionOrphanStorageKeys;
+    private sessionDownloaded;
+    private sessionSkipped;
+    constructor(options: MediaMirrorSessionOptions);
+    /**
+     * The shared library walk, bounded by `maxItems` (default `mediaSyncLimit`, unlimited for `--all`) exactly
+     * like the library pass. A batch pull against a fleet-scale library must never pay for an unbounded scan on
+     * behalf of a handful of articles; a key that lands outside the window is reported as unresolved rather than
+     * asserted absent, and `complete === false` keeps every per-record lookup available downstream.
+     */
+    getRemoteIndex(): Promise<RemoteStorageKeyIndex>;
+    getLocalCandidates(): Map<string, LocalMediaMirrorCandidate>;
+    /**
+     * Mirrors media referenced by an article (both body storageKeys and frontmatter featuredImage).
+     */
+    mirrorArticleReferencedMedia(params: {
+        canonicalMarkdown: string;
+        featuredImage?: string | null;
+    }): Promise<PullArticleMediaSummary | undefined>;
+    /**
+     * Finalizes media statistics for pullBatch.
+     */
+    finalizeBatchMediaResult(): Promise<{
+        walkedCount: number;
+        remoteTotalCount: number | null;
+        complete: boolean;
+        downloaded: number;
+        skipped: number;
+        mirroredStorageKeys: string[];
+        verifiedStorageKeys: string[];
+        orphanStorageKeys: string[];
+    }>;
+}
+/**
+ * Creates a shared MediaMirrorSession.
+ */
+export declare function createMediaMirrorSession(options: MediaMirrorSessionOptions): MediaMirrorSession;
+/**
+ * Convenience helper to mirror referenced media for a single article.
+ */
+export declare function mirrorArticleReferencedMedia(options: PullOptions, canonicalMarkdown: string, featuredImage?: string | null): Promise<PullArticleMediaSummary | undefined>;
+//# sourceMappingURL=media_stage.d.ts.map

package/dist/sync/pull/media_stage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media_stage.d.ts","sourceRoot":"","sources":["../../../src/sync/pull/media_stage.ts"],"names":[],"mappings":"AA8BA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAUvD,OAAO,EAQL,KAAK,yBAAyB,EAC9B,KAAK,qBAAqB,EAC3B,MAAM,aAAa,CAAC;AACrB,OAAO,KAAK,EAAE,kBAAkB,EAAE,uBAAuB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE3F,MAAM,WAAW,yBAAyB;IACxC,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;IACtB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B,mGAAmG;IACnG,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,GAAG,CAAC,EAAE,OAAO,CAAC;CACf;AAqGD,qBAAa,sBAAuB,YAAW,kBAAkB;IAC/D,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA4B;IACpD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;IAC1C,OAAO,CAAC,kBAAkB,CAA+C;IACzE,OAAO,CAAC,kBAAkB,CAAuD;IACjF,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAkD;IAGjF,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAqB;IAChE,OAAO,CAAC,QAAQ,CAAC,0BAA0B,CAAqB;IAChE,OAAO,CAAC,QAAQ,CAAC,wBAAwB,CAAqB;IAC9D,OAAO,CAAC,iBAAiB,CAAK;IAC9B,OAAO,CAAC,cAAc,CAAK;IAE3B,YAAY,OAAO,EAAE,yBAAyB,EAI7C;IAED;;;;;OAKG;IACI,cAAc,IAAI,OAAO,CAAC,qBAAqB,CAAC,CAetD;IAEM,kBAAkB,IAAI,GAAG,CAAC,MAAM,EAAE,yBAAyB,CAAC,CAKlE;IAED;;OAEG;IACU,4BAA4B,CAAC,MAAM,EAAE;QAChD,iBAAiB,EAAE,MAAM,CAAC;QAC1B,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC/B,GAAG,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CA0a/C;IAED;;OAEG;IACU,wBAAwB,IAAI,OAAO,CAAC;QAC/C,WAAW,EAAE,MAAM,CAAC;QACpB,gBAAgB,EAAE,MAAM,GAAG,IAAI,CAAC;QAChC,QAAQ,EAAE,OAAO,CAAC;QAClB,UAAU,EAAE,MAAM,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAC9B,mBAAmB,EAAE,MAAM,EAAE,CAAC;QAC9B,iBAAiB,EAAE,MAAM,EAAE,CAAC;KAC7B,CAAC,CAYD;CACF;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CAAC,OAAO,EAAE,yBAAyB,GAAG,kBAAkB,CAE/F;AAED;;GAEG;AACH,wBAAsB,4BAA4B,CAChD,OAAO,EAAE,WAAW,EACpB,iBAAiB,EAAE,MAAM,EACzB,aAAa,CAAC,EAAE,MAAM,GAAG,IAAI,GAC5B,OAAO,CAAC,uBAAuB,GAAG,SAAS,CAAC,CAkB9C"}

package/dist/sync/pull/media_stage.js

@@ -0,0 +1,599 @@
+/*
+ * Copyright (C) 2026 SPORT-SERVICE RS★R
+ *
+ * Permission is hereby granted, free of charge, to any person obtaining a copy
+ * of this software and associated documentation files (the "Software"), to deal
+ * in the Software without restriction, including without limitation the rights
+ * to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+ * copies of the Software, and to permit persons to whom the Software is
+ * furnished to do so, subject to the following conditions:
+ *
+ * The above copyright notice and this permission notice shall be included in all
+ * copies or substantial portions of the Software.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+ * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+ * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+ * OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+ * SOFTWARE.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import yaml from 'js-yaml';
+import { createAuthedFetch } from '../../client/http.js';
+import { unwrapEnvelope } from '../../client/api.js';
+import { mediaDetailEndpoint } from '../../client/endpoints.js';
+import { extractMediaUlid } from '../../client/mapper.js';
+import { DEFAULT_CONFIG } from '../../utils/config.js';
+import { toMediaRecordId, asMediaRecordId, toStorageKey, asStorageKey, } from '../../utils/media-id.js';
+import { MEDIA_FILE_ROUTE_PREFIX } from '../../utils/media-refs.js';
+import { storageKeyToMarkdownRef } from '../../utils/naming.js';
+import { collectArticleStorageKeys, collectRemoteStorageKeys, collectLocalMediaMirrorCandidates, syncSingleMediaItem, mediaRecordIdForStem, MEDIA_BINARY_EXTENSIONS, } from '../media.js';
+function computeFileSha256(filePath) {
+    const buffer = fs.readFileSync(filePath);
+    return crypto.createHash('sha256').update(buffer).digest('hex');
+}
+/**
+ * Finds a local binary file matching a storageKey, using media_state workspacePath if available,
+ * or searching media/ directory for markdownRef.<ext>.
+ */
+function findLocalBinaryForStorageKey(mediaDir, storageKey, cache, workspaceRoot) {
+    if (cache && workspaceRoot) {
+        const state = cache.getMediaStateByStorageKey(storageKey);
+        if (state?.workspacePath) {
+            const full = path.join(workspaceRoot, state.workspacePath);
+            if (fs.existsSync(full)) {
+                const ext = path.extname(state.workspacePath);
+                const stem = path.basename(state.markdownRef || state.workspacePath, ext);
+                return { binaryPath: full, stem };
+            }
+        }
+    }
+    if (!fs.existsSync(mediaDir))
+        return null;
+    const ref = storageKeyToMarkdownRef(storageKey) || storageKey;
+    const ext = path.extname(storageKey);
+    if (ext) {
+        const candidate = path.join(mediaDir, `${ref}${ext}`);
+        if (fs.existsSync(candidate))
+            return { binaryPath: candidate, stem: ref };
+    }
+    for (const bExt of MEDIA_BINARY_EXTENSIONS) {
+        const candidate = path.join(mediaDir, `${ref}${bExt}`);
+        if (fs.existsSync(candidate))
+            return { binaryPath: candidate, stem: ref };
+    }
+    for (const file of fs.readdirSync(mediaDir)) {
+        if (file.endsWith('.yaml') || file.startsWith('legacy_'))
+            continue;
+        const fileStem = file.replace(/\.[^.]+$/, '');
+        if (fileStem === ref) {
+            return { binaryPath: path.join(mediaDir, file), stem: ref };
+        }
+    }
+    return null;
+}
+/**
+ * Finds a local binary matching a mediaId ULID (used for featuredImage).
+ */
+function findLocalBinaryForMediaId(mediaDir, mediaId, cache, workspaceRoot) {
+    const wanted = mediaId.toUpperCase();
+    if (cache && workspaceRoot) {
+        const state = cache.getMediaStateByMediaId(wanted);
+        if (state?.workspacePath) {
+            const full = path.join(workspaceRoot, state.workspacePath);
+            if (fs.existsSync(full)) {
+                const ext = path.extname(state.workspacePath);
+                const stem = path.basename(state.markdownRef || state.workspacePath, ext);
+                return { binaryPath: full, stem, storageKey: state.storageKey || undefined };
+            }
+        }
+    }
+    if (!fs.existsSync(mediaDir))
+        return null;
+    for (const file of fs.readdirSync(mediaDir)) {
+        if (!file.endsWith('.yaml') || file.startsWith('legacy_'))
+            continue;
+        const stem = file.replace(/\.yaml$/, '');
+        if (mediaRecordIdForStem(mediaDir, stem) === wanted) {
+            for (const ext of MEDIA_BINARY_EXTENSIONS) {
+                const candidate = path.join(mediaDir, `${stem}${ext}`);
+                if (fs.existsSync(candidate)) {
+                    return { binaryPath: candidate, stem };
+                }
+            }
+        }
+    }
+    return null;
+}
+export class MediaMirrorSessionImpl {
+    options;
+    mediaDir;
+    isSharedSession;
+    remoteIndexPromise = null;
+    localCandidatesMap = null;
+    inFlightAssets = new Map();
+    // Aggregate session statistics (for pullBatch)
+    sessionMirroredStorageKeys = new Set();
+    sessionVerifiedStorageKeys = new Set();
+    sessionOrphanStorageKeys = new Set();
+    sessionDownloaded = 0;
+    sessionSkipped = 0;
+    constructor(options) {
+        this.options = options;
+        this.mediaDir = path.join(options.workspaceRoot, 'media');
+        this.isSharedSession = options.isSharedSession === true;
+    }
+    /**
+     * The shared library walk, bounded by `maxItems` (default `mediaSyncLimit`, unlimited for `--all`) exactly
+     * like the library pass. A batch pull against a fleet-scale library must never pay for an unbounded scan on
+     * behalf of a handful of articles; a key that lands outside the window is reported as unresolved rather than
+     * asserted absent, and `complete === false` keeps every per-record lookup available downstream.
+     */
+    getRemoteIndex() {
+        if (!this.remoteIndexPromise) {
+            this.remoteIndexPromise = collectRemoteStorageKeys({
+                workspaceRoot: this.options.workspaceRoot,
+                origin: this.options.origin,
+                token: this.options.token,
+                refreshToken: this.options.refreshToken,
+                maxItems: this.options.all === true || typeof this.options.limit === 'number'
+                    ? this.options.limit
+                    : DEFAULT_CONFIG.mediaSyncLimit,
+                fetchFn: this.options.fetchFn,
+            });
+        }
+        return this.remoteIndexPromise;
+    }
+    getLocalCandidates() {
+        if (!this.localCandidatesMap) {
+            this.localCandidatesMap = collectLocalMediaMirrorCandidates(this.mediaDir);
+        }
+        return this.localCandidatesMap;
+    }
+    /**
+     * Mirrors media referenced by an article (both body storageKeys and frontmatter featuredImage).
+     */
+    async mirrorArticleReferencedMedia(params) {
+        const { canonicalMarkdown, featuredImage } = params;
+        // Step 1: Extract references
+        const bodyDescriptors = collectArticleStorageKeys(canonicalMarkdown);
+        const bodyStorageKeys = Array.from(new Set(bodyDescriptors.map((d) => d.storageKey)));
+        const featuredUlid = featuredImage ? extractMediaUlid(featuredImage) : null;
+        const featuredMediaId = featuredUlid ? featuredUlid.toUpperCase() : null;
+        if (bodyStorageKeys.length === 0 && !featuredMediaId) {
+            return undefined;
+        }
+        const { workspaceRoot, origin, token, cache, downloadFiles } = this.options;
+        const fetchFn = createAuthedFetch(this.options);
+        const shouldDownload = downloadFiles !== false;
+        // Step 2: 0-HTTP short-circuit inspection (when no remote index is needed yet)
+        // Check if all referenced assets are fully mirrored locally.
+        const isAssetFullyMirrored = (keyOrId, isFeatured) => {
+            if (isFeatured) {
+                const found = findLocalBinaryForMediaId(this.mediaDir, keyOrId, cache, workspaceRoot);
+                if (!found)
+                    return { fullyMirrored: false };
+                const yamlPath = path.join(this.mediaDir, `${found.stem}.yaml`);
+                let doc = null;
+                if (fs.existsSync(yamlPath)) {
+                    try {
+                        doc = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+                    }
+                    catch { }
+                }
+                if (typeof doc?.size === 'number') {
+                    try {
+                        if (fs.statSync(found.binaryPath).size !== doc.size)
+                            return { fullyMirrored: false };
+                    }
+                    catch {
+                        return { fullyMirrored: false };
+                    }
+                }
+                const state = cache?.getMediaStateByMediaId(keyOrId);
+                const companionUlid = mediaRecordIdForStem(this.mediaDir, found.stem);
+                if (!state && !companionUlid)
+                    return { fullyMirrored: false };
+                const resolvedMediaId = state?.mediaId || companionUlid;
+                const resolvedStorageKey = found.storageKey ||
+                    state?.storageKey ||
+                    (typeof doc?.storageKey === 'string' ? doc.storageKey : undefined);
+                return {
+                    fullyMirrored: true,
+                    binaryPath: found.binaryPath,
+                    stem: found.stem,
+                    mediaId: resolvedMediaId,
+                    storageKey: resolvedStorageKey,
+                };
+            }
+            else {
+                const found = findLocalBinaryForStorageKey(this.mediaDir, keyOrId, cache, workspaceRoot);
+                if (!found)
+                    return { fullyMirrored: false };
+                const yamlPath = path.join(this.mediaDir, `${found.stem}.yaml`);
+                let doc = null;
+                if (fs.existsSync(yamlPath)) {
+                    try {
+                        doc = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+                    }
+                    catch { }
+                }
+                if (typeof doc?.size === 'number') {
+                    try {
+                        if (fs.statSync(found.binaryPath).size !== doc.size)
+                            return { fullyMirrored: false };
+                    }
+                    catch {
+                        return { fullyMirrored: false };
+                    }
+                }
+                const state = cache?.getMediaStateByStorageKey(keyOrId);
+                const companionUlid = mediaRecordIdForStem(this.mediaDir, found.stem);
+                if (!state && !companionUlid)
+                    return { fullyMirrored: false };
+                const resolvedMediaId = state?.mediaId || companionUlid;
+                return {
+                    fullyMirrored: true,
+                    binaryPath: found.binaryPath,
+                    stem: found.stem,
+                    mediaId: resolvedMediaId,
+                    storageKey: keyOrId,
+                };
+            }
+        };
+        const bodyCheck = bodyStorageKeys.map((k) => ({
+            key: k,
+            ...isAssetFullyMirrored(k, false),
+        }));
+        const featuredCheck = featuredMediaId
+            ? { id: featuredMediaId, ...isAssetFullyMirrored(featuredMediaId, true) }
+            : null;
+        const allFullyMirrored = bodyCheck.every((b) => b.fullyMirrored) && (!featuredCheck || featuredCheck.fullyMirrored);
+        if (allFullyMirrored) {
+            // 0-HTTP short-circuit: all referenced assets already exist locally.
+            // Upsert media_state for any entries missing localContentHash or unrecorded in DB.
+            if (cache) {
+                const allItems = [...bodyCheck];
+                if (featuredCheck) {
+                    allItems.push({
+                        key: featuredCheck.id,
+                        fullyMirrored: true,
+                        binaryPath: featuredCheck.binaryPath,
+                        stem: featuredCheck.stem,
+                        mediaId: featuredCheck.mediaId,
+                        storageKey: featuredCheck.storageKey,
+                    });
+                }
+                for (const item of allItems) {
+                    if (!item.binaryPath || !item.stem || !item.mediaId)
+                        continue;
+                    const targetKey = item.storageKey || item.key;
+                    const brandedStorageKey = toStorageKey(targetKey) ?? asStorageKey(targetKey);
+                    const existingState = cache.getMediaStateByStorageKey(brandedStorageKey);
+                    let currentContentHash = existingState?.localContentHash;
+                    if (!existingState || !currentContentHash) {
+                        try {
+                            currentContentHash = computeFileSha256(item.binaryPath);
+                        }
+                        catch {
+                            continue;
+                        }
+                    }
+                    const confirmedMediaId = existingState?.mediaId || item.mediaId;
+                    const ext = path.extname(item.binaryPath);
+                    cache.saveMediaState({
+                        localHash: `media-record:${confirmedMediaId}`,
+                        localContentHash: currentContentHash,
+                        mediaId: toMediaRecordId(confirmedMediaId) ?? asMediaRecordId(confirmedMediaId),
+                        storageKey: brandedStorageKey,
+                        url: `${MEDIA_FILE_ROUTE_PREFIX}${targetKey}`,
+                        workspacePath: path.posix.join('media', `${item.stem}${ext}`),
+                        markdownRef: path.posix.join('media', item.stem),
+                        status: 'ready',
+                        remoteRecordRef: `media-record:${confirmedMediaId}`,
+                    });
+                }
+            }
+            const totalCount = bodyStorageKeys.length + (featuredMediaId ? 1 : 0);
+            for (const k of bodyStorageKeys) {
+                this.sessionVerifiedStorageKeys.add(k);
+            }
+            this.sessionSkipped += totalCount;
+            return {
+                total: totalCount,
+                downloaded: 0,
+                skipped: totalCount,
+                mirroredStorageKeys: [],
+                verifiedStorageKeys: [...bodyStorageKeys],
+                orphanStorageKeys: [],
+            };
+        }
+        // Step 3: Remote resolution with in-flight deduplication and fallback handling
+        fs.mkdirSync(this.mediaDir, { recursive: true });
+        let downloadedCount = 0;
+        let skippedCount = 0;
+        const articleMirrored = new Set();
+        const articleVerified = new Set();
+        const articleOrphans = new Set();
+        let unresolvedFeaturedImageId = undefined;
+        let mediaFetchFailed = false;
+        // Helper to mirror an asset through in-flight deduplication
+        const runOrJoinInFlight = (assetKey, operation) => {
+            let inflight = this.inFlightAssets.get(assetKey);
+            if (!inflight) {
+                inflight = operation().then((outcome) => {
+                    if (outcome.downloaded) {
+                        this.sessionDownloaded++;
+                    }
+                    else if (outcome.skipped) {
+                        this.sessionSkipped++;
+                    }
+                    return outcome;
+                });
+                this.inFlightAssets.set(assetKey, inflight);
+            }
+            return inflight;
+        };
+        // Case B: Single-article pull (not shared session) with no body storageKeys and only featuredImage is missing
+        if (!this.isSharedSession && bodyStorageKeys.length === 0 && featuredMediaId) {
+            const outcome = await runOrJoinInFlight(`featured:${featuredMediaId}`, async () => {
+                try {
+                    const detailUrl = mediaDetailEndpoint(origin, featuredMediaId);
+                    const res = await fetchFn(detailUrl, {
+                        headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                    });
+                    if (!res.ok) {
+                        return { downloaded: false, skipped: false, failed: true };
+                    }
+                    const json = await res.json();
+                    const envelope = unwrapEnvelope(json);
+                    const item = (envelope.item || envelope);
+                    const syncRes = await syncSingleMediaItem({
+                        item,
+                        mediaDir: this.mediaDir,
+                        origin,
+                        token,
+                        downloadFiles: shouldDownload,
+                        fetchFn,
+                        cache,
+                    });
+                    return {
+                        downloaded: syncRes.downloaded,
+                        skipped: syncRes.skipped,
+                        failed: false,
+                        storageKey: item.storageKey,
+                    };
+                }
+                catch {
+                    return { downloaded: false, skipped: false, failed: true };
+                }
+            });
+            if (outcome.downloaded) {
+                downloadedCount++;
+            }
+            else if (outcome.skipped) {
+                skippedCount++;
+            }
+            if (outcome.failed) {
+                mediaFetchFailed = true;
+                // Non-destructive fallback check: if binary already exists locally, don't mark as unresolved
+                const localCheck = isAssetFullyMirrored(featuredMediaId, true);
+                if (!localCheck.fullyMirrored) {
+                    unresolvedFeaturedImageId = featuredMediaId;
+                }
+            }
+            else if (outcome.storageKey) {
+                articleMirrored.add(outcome.storageKey);
+                this.sessionMirroredStorageKeys.add(outcome.storageKey);
+            }
+            return {
+                total: 1,
+                downloaded: downloadedCount,
+                skipped: skippedCount,
+                mirroredStorageKeys: Array.from(articleMirrored),
+                verifiedStorageKeys: [],
+                orphanStorageKeys: [],
+                unresolvedFeaturedImageId,
+                mediaFetchFailed: mediaFetchFailed ? true : undefined,
+            };
+        }
+        // Case A: Body storageKeys present (or shared batch session)
+        let remoteIndex = null;
+        try {
+            remoteIndex = await this.getRemoteIndex();
+        }
+        catch {
+            mediaFetchFailed = true;
+        }
+        const localCandidates = this.getLocalCandidates();
+        // 1. Process body storageKeys
+        for (const key of bodyStorageKeys) {
+            const outcome = await runOrJoinInFlight(`storageKey:${key}`, async () => {
+                let item = remoteIndex?.recordsByStorageKey.get(key);
+                if (!item && remoteIndex) {
+                    const ulids = (key.match(/[0-9A-HJ-NP-Z]{26}/gi) ?? []).map((u) => u.toUpperCase());
+                    for (const ulid of ulids) {
+                        const byId = remoteIndex.recordsById.get(ulid);
+                        if (byId) {
+                            item = byId;
+                            break;
+                        }
+                    }
+                }
+                if (item) {
+                    try {
+                        const syncRes = await syncSingleMediaItem({
+                            item,
+                            mediaDir: this.mediaDir,
+                            origin,
+                            token,
+                            downloadFiles: shouldDownload,
+                            fetchFn,
+                            cache,
+                        });
+                        return {
+                            downloaded: syncRes.downloaded,
+                            skipped: syncRes.skipped,
+                            failed: false,
+                            storageKey: item.storageKey || key,
+                        };
+                    }
+                    catch {
+                        return { downloaded: false, skipped: false, failed: true, storageKey: key };
+                    }
+                }
+                return { downloaded: false, skipped: false, failed: true, storageKey: key };
+            });
+            if (outcome.downloaded) {
+                downloadedCount++;
+            }
+            else if (outcome.skipped) {
+                skippedCount++;
+            }
+            if (!outcome.failed) {
+                if (outcome.storageKey) {
+                    articleMirrored.add(outcome.storageKey);
+                    this.sessionMirroredStorageKeys.add(outcome.storageKey);
+                }
+                articleMirrored.add(key);
+                this.sessionMirroredStorageKeys.add(key);
+            }
+            else {
+                // Fallback evaluation: does local binary exist or is it confirmed in candidates/index?
+                const ulids = (key.match(/[0-9A-HJ-NP-Z]{26}/gi) ?? []).map((u) => u.toUpperCase());
+                const hasBinary = findLocalBinaryForStorageKey(this.mediaDir, key, cache, workspaceRoot) !== null;
+                const confirmed = hasBinary ||
+                    (remoteIndex && remoteIndex.storageKeys.has(key)) ||
+                    ulids.some((u) => remoteIndex?.recordsById.has(u) || localCandidates.has(u));
+                if (confirmed) {
+                    articleVerified.add(key);
+                    this.sessionVerifiedStorageKeys.add(key);
+                }
+                else {
+                    articleOrphans.add(key);
+                    this.sessionOrphanStorageKeys.add(key);
+                    mediaFetchFailed = true;
+                }
+            }
+        }
+        // 2. Process featuredImage if present
+        if (featuredMediaId) {
+            const outcome = await runOrJoinInFlight(`featured:${featuredMediaId}`, async () => {
+                let item = remoteIndex?.recordsById.get(featuredMediaId);
+                // Only attempt individual GET if the full remote walk didn't already exhaustively cover the library
+                if (!item && (!remoteIndex || !remoteIndex.complete)) {
+                    try {
+                        const detailUrl = mediaDetailEndpoint(origin, featuredMediaId);
+                        const res = await fetchFn(detailUrl, {
+                            headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
+                        });
+                        if (res.ok) {
+                            const json = await res.json();
+                            const envelope = unwrapEnvelope(json);
+                            item = (envelope.item || envelope);
+                        }
+                    }
+                    catch { }
+                }
+                if (item) {
+                    try {
+                        const syncRes = await syncSingleMediaItem({
+                            item,
+                            mediaDir: this.mediaDir,
+                            origin,
+                            token,
+                            downloadFiles: shouldDownload,
+                            fetchFn,
+                            cache,
+                        });
+                        return {
+                            downloaded: syncRes.downloaded,
+                            skipped: syncRes.skipped,
+                            failed: false,
+                            storageKey: item.storageKey,
+                        };
+                    }
+                    catch {
+                        return { downloaded: false, skipped: false, failed: true };
+                    }
+                }
+                return { downloaded: false, skipped: false, failed: true };
+            });
+            if (outcome.downloaded) {
+                downloadedCount++;
+            }
+            else if (outcome.skipped) {
+                skippedCount++;
+            }
+            if (outcome.failed) {
+                const localCheck = isAssetFullyMirrored(featuredMediaId, true);
+                if (!localCheck.fullyMirrored) {
+                    unresolvedFeaturedImageId = featuredMediaId;
+                    mediaFetchFailed = true;
+                }
+            }
+            else if (outcome.storageKey) {
+                articleMirrored.add(outcome.storageKey);
+                this.sessionMirroredStorageKeys.add(outcome.storageKey);
+            }
+        }
+        const totalProcessed = bodyStorageKeys.length + (featuredMediaId ? 1 : 0);
+        return {
+            total: totalProcessed,
+            downloaded: downloadedCount,
+            skipped: skippedCount,
+            mirroredStorageKeys: Array.from(articleMirrored),
+            verifiedStorageKeys: Array.from(articleVerified),
+            orphanStorageKeys: Array.from(articleOrphans),
+            unresolvedFeaturedImageId,
+            mediaFetchFailed: mediaFetchFailed ? true : undefined,
+        };
+    }
+    /**
+     * Finalizes media statistics for pullBatch.
+     */
+    async finalizeBatchMediaResult() {
+        const remoteIndex = await this.getRemoteIndex();
+        return {
+            walkedCount: remoteIndex.scannedCount,
+            remoteTotalCount: remoteIndex.totalCount,
+            complete: remoteIndex.complete,
+            downloaded: this.sessionDownloaded,
+            skipped: this.sessionSkipped,
+            mirroredStorageKeys: Array.from(this.sessionMirroredStorageKeys),
+            verifiedStorageKeys: Array.from(this.sessionVerifiedStorageKeys),
+            orphanStorageKeys: Array.from(this.sessionOrphanStorageKeys),
+        };
+    }
+}
+/**
+ * Creates a shared MediaMirrorSession.
+ */
+export function createMediaMirrorSession(options) {
+    return new MediaMirrorSessionImpl(options);
+}
+/**
+ * Convenience helper to mirror referenced media for a single article.
+ */
+export async function mirrorArticleReferencedMedia(options, canonicalMarkdown, featuredImage) {
+    const session = options.mediaSession ??
+        createMediaMirrorSession({
+            workspaceRoot: options.workspaceRoot,
+            origin: options.origin,
+            token: options.token,
+            refreshToken: options.refreshToken,
+            cache: options.cache,
+            fetchFn: options.fetchFn,
+            downloadFiles: true,
+            limit: options.mediaSyncLimit,
+        });
+    return session.mirrorArticleReferencedMedia({
+        canonicalMarkdown,
+        featuredImage,
+    });
+}
+//# sourceMappingURL=media_stage.js.map