emdash-emit 0.1.13 → 0.1.15

package/dist/sync/media/companions.js

@@ -0,0 +1,111 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { toRootRelativeMediaUrl } from '../../client/media.js';
+import { MEDIA_FILE_ROUTE_PREFIX } from '../../utils/media-refs.js';
+export function buildMediaMetaDoc(item, origin, existingMeta) {
+    const storageKey = (typeof item.storageKey === 'string' && item.storageKey ? item.storageKey : undefined) ??
+        (typeof existingMeta?.storageKey === 'string' && existingMeta.storageKey
+            ? existingMeta.storageKey
+            : '');
+    const canonicalUrl = item.url ||
+        (storageKey
+            ? `${MEDIA_FILE_ROUTE_PREFIX}${storageKey}`
+            : typeof existingMeta?.url === 'string'
+                ? existingMeta.url
+                : '');
+    const rootRelativeUrl = canonicalUrl
+        ? toRootRelativeMediaUrl(canonicalUrl, storageKey, origin)
+        : '';
+    const resolvedAlt = item.alt !== undefined && item.alt !== null && item.alt !== ''
+        ? item.alt
+        : typeof existingMeta?.alt === 'string'
+            ? existingMeta.alt
+            : '';
+    const resolvedCaption = item.caption !== undefined && item.caption !== null && item.caption !== ''
+        ? item.caption
+        : typeof existingMeta?.caption === 'string'
+            ? existingMeta.caption
+            : '';
+    const resolvedContentHash = typeof item.contentHash === 'string' && item.contentHash
+        ? item.contentHash
+        : typeof existingMeta?.contentHash === 'string' && existingMeta.contentHash
+            ? existingMeta.contentHash
+            : null;
+    return {
+        id: item.id,
+        filename: item.filename,
+        mimeType: item.mimeType,
+        size: item.size,
+        width: item.width ?? (typeof existingMeta?.width === 'number' ? existingMeta.width : null),
+        height: item.height ?? (typeof existingMeta?.height === 'number' ? existingMeta.height : null),
+        alt: resolvedAlt,
+        caption: resolvedCaption,
+        storageKey,
+        contentHash: resolvedContentHash,
+        status: item.status ?? (typeof existingMeta?.status === 'string' ? existingMeta.status : 'ready'),
+        url: rootRelativeUrl,
+        createdAt: item.createdAt || (typeof existingMeta?.createdAt === 'string' ? existingMeta.createdAt : ''),
+    };
+}
+/**
+ * Recovers the storageKey a companion YAML actually refers to. Older mirrors — most visibly the ones
+ * written before Emit persisted the field — carry no `storageKey:` key at all, yet their `url:` is the
+ * canonical `/_emdash/api/media/file/<storageKey>` route, which is confirmed metadata written from the
+ * server response and not an inference from a body reference. Absolute and root-relative forms are both
+ * accepted because either can appear depending on how the record was mirrored. `legacy_*` residue is
+ * never read here: it backs no real record, so it must not serve as verification evidence.
+ */
+export function storageKeyFromMediaMeta(doc) {
+    if (typeof doc.storageKey === 'string' && doc.storageKey.trim()) {
+        return doc.storageKey.trim();
+    }
+    if (typeof doc.url !== 'string' || !doc.url.trim())
+        return undefined;
+    const match = doc.url.match(/(?:^|\/)media\/file\/([^?#]+)/);
+    return match ? match[1] : undefined;
+}
+/**
+ * Indexes every locally mirrored media asset (`media/<markdownRef>.yaml`, plus legacy companion names) so a body
+ * storageKey that the canonical id lookup failed to resolve can be re-checked against confirmed local
+ * metadata instead of being declared missing. Leftover `legacy_*` residue is skipped because it backs
+ * no real record. The result maps each ULID found in a mirror (record id or storageKey) to its entry,
+ * which is what lets Emit tell "the record exists under a different id" apart from "no record exists".
+ */
+export function collectLocalMediaMirrorCandidates(mediaDir) {
+    const byUlid = new Map();
+    if (!fs.existsSync(mediaDir))
+        return byUlid;
+    for (const file of fs.readdirSync(mediaDir)) {
+        if (!file.endsWith('.yaml') || file.startsWith('legacy_'))
+            continue;
+        let doc = null;
+        try {
+            doc = yaml.load(fs.readFileSync(path.join(mediaDir, file), 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!doc)
+            continue;
+        const storageKey = storageKeyFromMediaMeta(doc);
+        const stem = file.replace(/\.yaml$/, '');
+        const idMatch = stem.replace(/^\d{8}_/, '').match(/^([0-9A-HJ-NP-Z]{26})/i);
+        const docId = typeof doc.id === 'string' && /^[0-9A-HJ-NP-Z]{26}$/i.test(doc.id.trim())
+            ? doc.id.trim().toUpperCase()
+            : undefined;
+        const mediaId = docId || (idMatch ? idMatch[1].toUpperCase() : '');
+        if (!mediaId)
+            continue;
+        const candidate = { mediaId, storageKey, metaFile: file };
+        if (!byUlid.has(mediaId))
+            byUlid.set(mediaId, candidate);
+        for (const ulid of storageKey?.matchAll(/[0-9A-HJ-NP-Z]{26}/gi) ?? []) {
+            const key = ulid[0].toUpperCase();
+            if (!byUlid.has(key))
+                byUlid.set(key, candidate);
+        }
+    }
+    return byUlid;
+}
+//# sourceMappingURL=companions.js.map

package/dist/sync/media/companions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"companions.js","sourceRoot":"","sources":["../../../src/sync/media/companions.ts"],"names":[],"mappings":"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"}

package/dist/sync/media/index.d.ts

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './naming_mirror.js';
+export * from './companions.js';
+export * from './body_scan.js';
+export * from './mirror_item.js';
+export * from './pull_article.js';
+export * from './pull_library.js';
+export * from './remote_index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/sync/media/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/sync/media/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/sync/media/index.js

@@ -0,0 +1,9 @@
+export * from './types.js';
+export * from './naming_mirror.js';
+export * from './companions.js';
+export * from './body_scan.js';
+export * from './mirror_item.js';
+export * from './pull_article.js';
+export * from './pull_library.js';
+export * from './remote_index.js';
+//# sourceMappingURL=index.js.map

package/dist/sync/media/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/sync/media/index.ts"],"names":[],"mappings":"AAAA,cAAc,YAAY,CAAC;AAC3B,cAAc,oBAAoB,CAAC;AACnC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,kBAAkB,CAAC;AACjC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/sync/media/mirror_item.d.ts

@@ -0,0 +1,27 @@
+import type { CacheDatabase } from '../../db/cache.js';
+import type { EmDashMediaItem, PromoteDraftMediaOptions, PromotedMediaFile } from './types.js';
+/**
+ * Persists YAML companion metadata and downloads the binary file for a single media item.
+ */
+export declare function syncSingleMediaItem(options: {
+    item: EmDashMediaItem;
+    mediaDir: string;
+    origin: string;
+    token: string;
+    downloadFiles: boolean;
+    fetchFn: typeof fetch;
+    cache?: CacheDatabase;
+}): Promise<{
+    downloaded: boolean;
+    skipped: boolean;
+    baseName: string;
+}>;
+/**
+ * Promotes a local draft image from media/drafts/<name> into the canonical
+ * media/<markdownRef>.<ext> location alongside its matching media/<markdownRef>.yaml companion, where
+ * markdownRef is derived from the storageKey the article body will reference. Returns both the workspace-relative
+ * path of the promoted binary and the shared `media/<markdownRef>` stem, so the caller can record the mirror in
+ * `media_state.markdown_ref`.
+ */
+export declare function promoteDraftMediaFile(options: PromoteDraftMediaOptions): PromotedMediaFile;
+//# sourceMappingURL=mirror_item.d.ts.map

package/dist/sync/media/mirror_item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror_item.d.ts","sourceRoot":"","sources":["../../../src/sync/media/mirror_item.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAQvD,OAAO,KAAK,EAAE,eAAe,EAAE,wBAAwB,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAE/F;;GAEG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE;IACjD,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;IACvB,OAAO,EAAE,OAAO,KAAK,CAAC;IACtB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC;IAAE,UAAU,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,OAAO,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAmKvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,wBAAwB,GAAG,iBAAiB,CAyD1F"}

package/dist/sync/media/mirror_item.js

@@ -0,0 +1,207 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { MEDIA_FILE_ROUTE_PREFIX } from '../../utils/media-refs.js';
+import { buildMediaMetaDoc } from './companions.js';
+import { cleanupDuplicateMediaFilesForId, mediaMirrorNames, moveFileSafe, } from './naming_mirror.js';
+/**
+ * Persists YAML companion metadata and downloads the binary file for a single media item.
+ */
+export async function syncSingleMediaItem(options) {
+    const { item, mediaDir, origin, token, downloadFiles, fetchFn, cache } = options;
+    const names = mediaMirrorNames(item, mediaDir);
+    const baseName = names.markdownRef;
+    const yamlPath = path.join(mediaDir, `${baseName}.yaml`);
+    // Read any existing companion for this record id first, whatever stem it currently occupies. The
+    // storageKey-named companion is the expected location; the legacy stems are where an older workspace still
+    // holds the same asset. `legacy_<storageKey>.yaml` is skipped unconditionally: it carries a matching ULID
+    // but fabricates its metadata from a file route, so it must never seed a real record.
+    let existingMeta = null;
+    let existingMetaPath = null;
+    const mediaFiles = fs.readdirSync(mediaDir);
+    const companionCandidates = [yamlPath];
+    for (const legacy of names.legacyBaseNames) {
+        companionCandidates.push(path.join(mediaDir, `${legacy}.yaml`));
+    }
+    for (const candidate of companionCandidates) {
+        if (!fs.existsSync(candidate))
+            continue;
+        try {
+            existingMeta = yaml.load(fs.readFileSync(candidate, 'utf8'));
+            existingMetaPath = candidate;
+            break;
+        }
+        catch {
+            existingMeta = null;
+        }
+    }
+    if (!existingMeta) {
+        const matchingYaml = mediaFiles.find((f) => f.endsWith('.yaml') &&
+            !f.startsWith('legacy_') &&
+            f !== path.basename(yamlPath) &&
+            (f.includes(`_${item.id}-`) || f.startsWith(`${item.id}-`)));
+        if (matchingYaml) {
+            try {
+                existingMeta = yaml.load(fs.readFileSync(path.join(mediaDir, matchingYaml), 'utf8'));
+                existingMetaPath = path.join(mediaDir, matchingYaml);
+            }
+            catch {
+                existingMeta = null;
+            }
+        }
+    }
+    // 1. Write YAML metadata under the storageKey-derived stem
+    const metaDoc = buildMediaMetaDoc(item, origin, existingMeta);
+    fs.writeFileSync(yamlPath, yaml.dump(metaDoc, { indent: 2, quotingType: '"', forceQuotes: false, lineWidth: -1 }), 'utf8');
+    let downloaded = false;
+    let skipped = false;
+    // 2. Download binary file if enabled and url is present
+    const canonicalDownloadPath = item.url || (item.storageKey ? `${MEDIA_FILE_ROUTE_PREFIX}${item.storageKey}` : '');
+    const fileExt = names.ext || (item.mimeType.includes('png') ? '.png' : '.jpg');
+    const targetFilePath = path.join(mediaDir, `${baseName}${fileExt}`);
+    // Rename an existing mirror into the new name before considering a download, so migrating a workspace
+    // costs no bandwidth. Size must match: a same-stem file of a different size is not this asset.
+    if (!fs.existsSync(targetFilePath)) {
+        const candidates = names.legacyBaseNames
+            .map((legacy) => path.join(mediaDir, `${legacy}${fileExt}`))
+            .concat(mediaFiles
+            .filter((f) => !f.endsWith('.yaml') &&
+            !f.startsWith('legacy_') &&
+            (f.includes(`_${item.id}-`) || f.startsWith(`${item.id}-`)))
+            .map((f) => path.join(mediaDir, f)));
+        for (const candidate of candidates) {
+            if (candidate === targetFilePath || !fs.existsSync(candidate))
+                continue;
+            try {
+                const stat = fs.statSync(candidate);
+                if (stat.size === item.size) {
+                    moveFileSafe(candidate, targetFilePath);
+                    break;
+                }
+            }
+            catch { }
+        }
+    }
+    if (downloadFiles && canonicalDownloadPath) {
+        let shouldDownload = true;
+        if (fs.existsSync(targetFilePath)) {
+            const stat = fs.statSync(targetFilePath);
+            if (stat.size === item.size) {
+                shouldDownload = false;
+                skipped = true;
+            }
+        }
+        if (shouldDownload) {
+            try {
+                const downloadUrl = new URL(canonicalDownloadPath, origin).toString();
+                const fileRes = await fetchFn(downloadUrl, {
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                    },
+                });
+                if (fileRes.ok) {
+                    const buffer = Buffer.from(await fileRes.arrayBuffer());
+                    fs.writeFileSync(targetFilePath, buffer);
+                    downloaded = true;
+                }
+            }
+            catch {
+                // Ignore individual download failures
+            }
+        }
+    }
+    // Register the mirrored asset in media_state. Before storageKey naming, only the push/upload path wrote
+    // this table, so a pulled workspace had no index at all and every lookup fell back to scanning YAML. With
+    // the mirror name no longer carrying the record id, that index is what makes a body reference resolvable
+    // without re-reading thousands of companions.
+    if (cache && item.storageKey) {
+        const mirrorUrl = typeof metaDoc.url === 'string' && metaDoc.url
+            ? metaDoc.url
+            : `${MEDIA_FILE_ROUTE_PREFIX}${item.storageKey}`;
+        cache.saveMediaState({
+            localHash: `media-record:${item.id}`,
+            mediaId: item.id,
+            storageKey: item.storageKey,
+            url: mirrorUrl,
+            workspacePath: path.posix.join('media', `${baseName}${fileExt}`),
+            markdownRef: path.posix.join('media', baseName),
+            status: 'ready',
+        });
+    }
+    // Drop the companion this asset occupied under a legacy stem. Done after the binary rename so an
+    // interrupted run never leaves a record whose metadata and bytes disagree about the name.
+    if (existingMetaPath && existingMetaPath !== yamlPath && fs.existsSync(existingMetaPath)) {
+        try {
+            fs.unlinkSync(existingMetaPath);
+        }
+        catch { }
+    }
+    for (const legacy of names.legacyBaseNames) {
+        const legacyYaml = path.join(mediaDir, `${legacy}.yaml`);
+        if (legacyYaml !== yamlPath && fs.existsSync(legacyYaml)) {
+            try {
+                fs.unlinkSync(legacyYaml);
+            }
+            catch { }
+        }
+    }
+    // Clean up any duplicate files with the same media ID but a different datePrefix/baseName
+    cleanupDuplicateMediaFilesForId(mediaDir, item.id, baseName);
+    return { downloaded, skipped, baseName };
+}
+/**
+ * Promotes a local draft image from media/drafts/<name> into the canonical
+ * media/<markdownRef>.<ext> location alongside its matching media/<markdownRef>.yaml companion, where
+ * markdownRef is derived from the storageKey the article body will reference. Returns both the workspace-relative
+ * path of the promoted binary and the shared `media/<markdownRef>` stem, so the caller can record the mirror in
+ * `media_state.markdown_ref`.
+ */
+export function promoteDraftMediaFile(options) {
+    const { workspaceRoot, origin, draftAbsPath, item, removeDraft = true } = options;
+    const mediaDir = path.join(workspaceRoot, 'media');
+    fs.mkdirSync(mediaDir, { recursive: true });
+    const ext = path.extname(item.filename) ||
+        path.extname(draftAbsPath) ||
+        (item.mimeType.includes('png') ? '.png' : '.jpg');
+    const names = mediaMirrorNames({ ...item, filename: item.filename || path.basename(draftAbsPath) }, mediaDir);
+    const baseName = names.markdownRef;
+    const yamlPath = path.join(mediaDir, `${baseName}.yaml`);
+    let existingMeta = null;
+    if (fs.existsSync(yamlPath)) {
+        try {
+            existingMeta = yaml.load(fs.readFileSync(yamlPath, 'utf8'));
+        }
+        catch {
+            existingMeta = null;
+        }
+    }
+    const metaDoc = buildMediaMetaDoc(item, origin, existingMeta);
+    fs.writeFileSync(yamlPath, yaml.dump(metaDoc, { indent: 2, quotingType: '"', forceQuotes: false, lineWidth: -1 }), 'utf8');
+    const targetFilePath = path.join(mediaDir, `${baseName}${ext}`);
+    if (fs.existsSync(draftAbsPath)) {
+        if (removeDraft) {
+            moveFileSafe(draftAbsPath, targetFilePath);
+        }
+        else {
+            fs.copyFileSync(draftAbsPath, targetFilePath);
+        }
+    }
+    // Retire any earlier id-named mirror of the same record so one asset never occupies two names.
+    for (const legacy of names.legacyBaseNames) {
+        for (const suffix of [ext, '.yaml']) {
+            const legacyPath = path.join(mediaDir, `${legacy}${suffix}`);
+            if (legacyPath !== yamlPath && legacyPath !== targetFilePath && fs.existsSync(legacyPath)) {
+                try {
+                    fs.unlinkSync(legacyPath);
+                }
+                catch { }
+            }
+        }
+    }
+    cleanupDuplicateMediaFilesForId(mediaDir, item.id, baseName);
+    return {
+        filePath: path.posix.join('media', `${baseName}${ext}`),
+        markdownRef: path.posix.join('media', baseName),
+    };
+}
+//# sourceMappingURL=mirror_item.js.map

package/dist/sync/media/mirror_item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror_item.js","sourceRoot":"","sources":["../../../src/sync/media/mirror_item.ts"],"names":[],"mappings":"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"}

package/dist/sync/media/naming_mirror.d.ts

@@ -0,0 +1,36 @@
+import { type EmDashMediaItem, type MediaMirrorNames } from './types.js';
+/**
+ * Moves a file from src to dest, falling back to copy + unlink when src and dest
+ * reside on different filesystems (`EXDEV`).
+ */
+export declare function moveFileSafe(src: string, dest: string): void;
+/**
+ * Reads the media record id a mirror belongs to from its companion YAML, accepting both the storageKey-named
+ * stem and the legacy `<yyyyMMdd>_<id>-<name>` form. Returns `null` when no companion exists or it names no
+ * valid ULID, which is how Emit refuses to prune a file it cannot attribute to a record. A companion whose
+ * id is explicitly null (or any non-ULID value) proves the mirror backs no real record, so the stem's own
+ * leading characters are never trusted as an id — that fallback would let fabricated fixture ids reach
+ * record-keyed logic.
+ */
+export declare function mediaRecordIdForStem(mediaDir: string, stem: string): string | null;
+/**
+ * Removes any stale duplicate files in `media/` that belong to the same 26-char `mediaId` but sit under a
+ * different stem — a leftover date-prefixed name from an earlier local promotion, for instance. Ownership is
+ * read from each file's companion YAML rather than from the filename, because a storageKey-named mirror
+ * carries no record id at all and must never be matched (or deleted) by a coincidental ULID prefix.
+ */
+export declare function cleanupDuplicateMediaFilesForId(mediaDir: string, mediaId: string, canonicalBaseName: string): void;
+/**
+ * Resolves the storageKey-derived stem against the names already taken in `media/`. Two distinct keys can
+ * sanitize to the same basename — `a/sample.png` and `b/sample.png` both yield `sample` — and a second asset
+ * must never overwrite the first. A name already owned by this same record is reused as-is, so re-pulling is
+ * idempotent; any other collision gets the deterministic `<stem>--<mediaId>` suffix.
+ */
+export declare function resolveMarkdownRefCollision(mediaDir: string, baseRef: string, item: EmDashMediaItem): string;
+/**
+ * Computes the canonical mirror name for one remote media item. Falls back to the record-id based stem only
+ * when the storageKey carries no usable basename, so a malformed migrated key cannot produce an unnameable
+ * file. Pass `mediaDir` to resolve a stem collision against the mirrors already on disk.
+ */
+export declare function mediaMirrorNames(item: EmDashMediaItem, mediaDir?: string): MediaMirrorNames;
+//# sourceMappingURL=naming_mirror.d.ts.map

package/dist/sync/media/naming_mirror.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming_mirror.d.ts","sourceRoot":"","sources":["../../../src/sync/media/naming_mirror.ts"],"names":[],"mappings":"AASA,OAAO,EAA2B,KAAK,eAAe,EAAE,KAAK,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAElG;;;GAGG;AACH,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,IAAI,CAW5D;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAmBlF;AAED;;;;;GAKG;AACH,wBAAgB,+BAA+B,CAC7C,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,iBAAiB,EAAE,MAAM,GACxB,IAAI,CAwBN;AAED;;;;;GAKG;AACH,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,eAAe,GACpB,MAAM,CAgBR;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,eAAe,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,gBAAgB,CAkB3F"}

package/dist/sync/media/naming_mirror.js

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import yaml from 'js-yaml';
+import { formatDatePrefix, sanitizeTitleForFilename, storageKeyToMarkdownRef, collisionSuffixedMarkdownRef, } from '../../utils/frontmatter.js';
+import { MEDIA_BINARY_EXTENSIONS } from './types.js';
+/**
+ * Moves a file from src to dest, falling back to copy + unlink when src and dest
+ * reside on different filesystems (`EXDEV`).
+ */
+export function moveFileSafe(src, dest) {
+    try {
+        fs.renameSync(src, dest);
+    }
+    catch (err) {
+        if (err?.code === 'EXDEV') {
+            fs.copyFileSync(src, dest);
+            fs.unlinkSync(src);
+        }
+        else {
+            throw err;
+        }
+    }
+}
+/**
+ * Reads the media record id a mirror belongs to from its companion YAML, accepting both the storageKey-named
+ * stem and the legacy `<yyyyMMdd>_<id>-<name>` form. Returns `null` when no companion exists or it names no
+ * valid ULID, which is how Emit refuses to prune a file it cannot attribute to a record. A companion whose
+ * id is explicitly null (or any non-ULID value) proves the mirror backs no real record, so the stem's own
+ * leading characters are never trusted as an id — that fallback would let fabricated fixture ids reach
+ * record-keyed logic.
+ */
+export function mediaRecordIdForStem(mediaDir, stem) {
+    const candidates = [`${stem}.yaml`, `${stem.replace(/^\d{8}_/, '')}.yaml`];
+    for (const name of candidates) {
+        const candidatePath = path.join(mediaDir, name);
+        if (!fs.existsSync(candidatePath))
+            continue;
+        let doc = null;
+        try {
+            doc = yaml.load(fs.readFileSync(candidatePath, 'utf8'));
+        }
+        catch {
+            continue;
+        }
+        if (!doc)
+            continue;
+        const rawId = typeof doc.id === 'string' ? doc.id.trim() : '';
+        if (/^[0-9A-Za-z_-]{26}$/.test(rawId)) {
+            return rawId.toUpperCase();
+        }
+        return null;
+    }
+    return null;
+}
+/**
+ * Removes any stale duplicate files in `media/` that belong to the same 26-char `mediaId` but sit under a
+ * different stem — a leftover date-prefixed name from an earlier local promotion, for instance. Ownership is
+ * read from each file's companion YAML rather than from the filename, because a storageKey-named mirror
+ * carries no record id at all and must never be matched (or deleted) by a coincidental ULID prefix.
+ */
+export function cleanupDuplicateMediaFilesForId(mediaDir, mediaId, canonicalBaseName) {
+    if (!fs.existsSync(mediaDir))
+        return;
+    const wanted = mediaId.toUpperCase();
+    for (const entry of fs.readdirSync(mediaDir)) {
+        if (entry.startsWith('legacy_'))
+            continue;
+        const entryBase = entry.replace(/\.yaml$/, '').replace(/\.[^.]+$/, '');
+        if (entryBase === canonicalBaseName)
+            continue;
+        // Only a companion-backed mirror can be attributed, and only when the companion itself is being
+        // retired together with its binary.
+        if (!entry.endsWith('.yaml'))
+            continue;
+        if (mediaRecordIdForStem(mediaDir, entryBase) !== wanted)
+            continue;
+        for (const orphan of [
+            `${entryBase}.yaml`,
+            ...MEDIA_BINARY_EXTENSIONS.map((e) => `${entryBase}${e}`),
+        ]) {
+            const orphanPath = path.join(mediaDir, orphan);
+            if (orphan === `${canonicalBaseName}.yaml`)
+                continue;
+            try {
+                if (fs.existsSync(orphanPath))
+                    fs.unlinkSync(orphanPath);
+            }
+            catch {
+                // Ignore cleanup errors
+            }
+        }
+    }
+}
+/**
+ * Resolves the storageKey-derived stem against the names already taken in `media/`. Two distinct keys can
+ * sanitize to the same basename — `a/sample.png` and `b/sample.png` both yield `sample` — and a second asset
+ * must never overwrite the first. A name already owned by this same record is reused as-is, so re-pulling is
+ * idempotent; any other collision gets the deterministic `<stem>--<mediaId>` suffix.
+ */
+export function resolveMarkdownRefCollision(mediaDir, baseRef, item) {
+    const suffixed = collisionSuffixedMarkdownRef(baseRef, item.id);
+    const takenByOther = (stem) => {
+        for (const suffix of ['.yaml', ...MEDIA_BINARY_EXTENSIONS]) {
+            const candidatePath = path.join(mediaDir, `${stem}${suffix}`);
+            if (!fs.existsSync(candidatePath))
+                continue;
+            const ownerId = mediaRecordIdForStem(mediaDir, stem);
+            if (ownerId && ownerId !== item.id.toUpperCase())
+                return true;
+        }
+        return false;
+    };
+    if (!takenByOther(baseRef))
+        return baseRef;
+    if (!takenByOther(suffixed))
+        return suffixed;
+    // Both taken and both owned by this record: the suffixed form is already this asset's, so keep it.
+    return suffixed;
+}
+/**
+ * Computes the canonical mirror name for one remote media item. Falls back to the record-id based stem only
+ * when the storageKey carries no usable basename, so a malformed migrated key cannot produce an unnameable
+ * file. Pass `mediaDir` to resolve a stem collision against the mirrors already on disk.
+ */
+export function mediaMirrorNames(item, mediaDir) {
+    const ext = path.extname(item.filename) || '';
+    const sanitizedBase = sanitizeTitleForFilename(path.basename(item.filename, ext));
+    const legacyBaseNames = [
+        `${item.id}-${sanitizedBase}`,
+        `${formatDatePrefix(item.createdAt)}${item.id}-${sanitizedBase}`,
+    ];
+    const fromKey = item.storageKey ? storageKeyToMarkdownRef(item.storageKey) : null;
+    if (fromKey) {
+        const markdownRef = mediaDir ? resolveMarkdownRefCollision(mediaDir, fromKey, item) : fromKey;
+        return { markdownRef, ext, legacyBaseNames };
+    }
+    return {
+        markdownRef: `${formatDatePrefix(item.createdAt)}${item.id}-${sanitizedBase}`,
+        ext,
+        legacyBaseNames,
+    };
+}
+//# sourceMappingURL=naming_mirror.js.map

package/dist/sync/media/naming_mirror.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"naming_mirror.js","sourceRoot":"","sources":["../../../src/sync/media/naming_mirror.ts"],"names":[],"mappings":"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"}

package/dist/sync/media/pull_article.d.ts

@@ -0,0 +1,37 @@
+import type { CacheDatabase } from '../../db/cache.js';
+import type { MirroredAssetResult, PullMediaResult, RemoteStorageKeyIndex } from './types.js';
+/**
+ * Pulls media referenced by a specific article (by ULID or file path).
+ */
+export declare function pullArticleMedia(options: {
+    workspaceRoot: string;
+    origin: string;
+    token: string;
+    refreshToken?: string;
+    article: string;
+    collection?: string;
+    downloadFiles?: boolean;
+    fetchFn?: typeof fetch;
+    cache?: CacheDatabase;
+}): Promise<PullMediaResult>;
+/**
+ * Mirrors only the assets a batch of pulled articles actually references, reusing the records the lightweight
+ * index walk already fetched instead of paying for a per-asset `GET /_emdash/api/media/{id}`.
+ *
+ * This is the mirror half of the default-ON local-first pull: the walk phase builds `RemoteStorageKeyIndex`
+ * (JSON only, no binaries), and this phase downloads the binary + companion YAML for exactly the storageKeys
+ * found in article bodies. A key the walk did not report is NOT proof of a missing record — the record can
+ * exist under a different primary key while the body carries an R2 storageKey — so it is re-checked against
+ * confirmed evidence only (a walked record resolved under that exact ULID, or local mirror metadata) and what
+ * still fails is reported as `orphanStorageKeys`. Emit never fetches such an asset and never registers one.
+ */
+export declare function mirrorReferencedAssetsFromIndex(referencedStorageKeys: Iterable<string>, index: RemoteStorageKeyIndex, options: {
+    workspaceRoot: string;
+    origin: string;
+    token: string;
+    refreshToken?: string;
+    downloadFiles?: boolean;
+    fetchFn?: typeof fetch;
+    cache?: CacheDatabase;
+}): Promise<MirroredAssetResult>;
+//# sourceMappingURL=pull_article.d.ts.map

package/dist/sync/media/pull_article.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pull_article.d.ts","sourceRoot":"","sources":["../../../src/sync/media/pull_article.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC;AAKvD,OAAO,KAAK,EAEV,mBAAmB,EAEnB,eAAe,EACf,qBAAqB,EACtB,MAAM,YAAY,CAAC;AAEpB;;GAEG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE;IAC9C,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GAAG,OAAO,CAAC,eAAe,CAAC,CA6L3B;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,+BAA+B,CACnD,qBAAqB,EAAE,QAAQ,CAAC,MAAM,CAAC,EACvC,KAAK,EAAE,qBAAqB,EAC5B,OAAO,EAAE;IACP,aAAa,EAAE,MAAM,CAAC;IACtB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,OAAO,KAAK,CAAC;IACvB,KAAK,CAAC,EAAE,aAAa,CAAC;CACvB,GACA,OAAO,CAAC,mBAAmB,CAAC,CAuE9B"}