emdash-emit 0.1.13 → 0.1.15

package/dist/utils/media-body-refs.js

@@ -0,0 +1,240 @@
+/*
+ * 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.
+ */
+/**
+ * Local Markdown body image references vs the canonical remote form.
+ *
+ * A body image has two spellings of the same asset:
+ *
+ *   canonical  `![alt](/_emdash/api/media/file/<storageKey>)`  — what EmDash stores in Portable Text and
+ *                                                        what the live site serves
+ *   local      `![alt](../../media/<storageKey>)`             — a reference spelled from the article's own
+ *                                                        directory, resolving to the mirrored file under
+ *                                                        `media/` at the workspace root
+ *
+ * The local spelling exists so an editor preview (VS Code, Obsidian) renders the image from the mirror. It is
+ * only ever a disk form: `base_snapshots.bodyMarkdown` and every payload sent to EmDash keep the canonical
+ * URL, because the baseline must stay byte-identical to what a remote pull writes.
+ *
+ * The depth is derived from the article's own path (`mediaRefPrefixForArticle`), so an article under
+ * `<collection>/draft|published/` carries `../../` while one at the workspace root carries `../`. That makes
+ * the link resolvable from the file that contains it, which a depth-free reference is not. The older depth-free
+ * form (`media/<storageKey>`) is still accepted wherever a local reference is read — workspaces built with it
+ * are re-spelled on the next pull rather than reported as edits.
+ */
+import { storageKeyToMarkdownRef } from './naming.js';
+/** Canonical root-relative media route prefix EmDash writes into Portable Text image blocks. */
+export const MEDIA_FILE_ROUTE_PREFIX = '/_emdash/api/media/file/';
+/** Workspace-relative directory a mirrored asset lives in. */
+export const MEDIA_DIR_PREFIX = 'media/';
+const CANONICAL_MEDIA_URL_REGEX = /(?:^|\/)media\/file\/([^?#\s)]+)/;
+/** Image extensions a storageKey may carry, matching the mirror naming rule. */
+const STORAGE_KEY_EXTENSION = /\.(jpg|jpeg|png|gif|webp|avif|svg)$/i;
+/**
+ * A storageKey names its mirror outright: one path segment that is itself an image file. A reference may also
+ * carry the deterministic `<stem>--<mediaId>` collision suffix, which still names a real asset. An article may
+ * spell that mirror relative to its own directory (`../../media/<key>`), so leading `../` / `./` segments are
+ * part of the accepted shape — but nothing deeper than `media/` is: a staging draft (`media/drafts/x.png`) or
+ * an unrelated folder (`../../uploads/x.jpg`) is not a canonicalized local reference.
+ */
+const LOCAL_MEDIA_REF_REGEX = /^(?:\.\.\/|\.\/)*media\/([^/?#\s]+)$/;
+/** `storageKeyFromMirrorRef` needs no candidate list when the reference spells its storageKey outright. */
+const EMPTY_STORAGE_KEY_CANDIDATES = new Set();
+/** Extracts the storageKey from a canonical `/_emdash/api/media/file/<storageKey>` URL. */
+export function storageKeyFromCanonicalUrl(url) {
+    const match = url.match(CANONICAL_MEDIA_URL_REGEX);
+    if (!match)
+        return null;
+    const key = match[1].trim();
+    return key.length > 0 ? key : null;
+}
+/** Reports whether a Markdown image URL already carries the canonical EmDash media file route. */
+export function isCanonicalMediaUrl(url) {
+    return storageKeyFromCanonicalUrl(url) !== null;
+}
+/** The final path segment of a reference, or null when it carries no usable name. */
+function refBasename(url) {
+    const match = url.trim().match(LOCAL_MEDIA_REF_REGEX);
+    if (!match)
+        return null;
+    return match[1];
+}
+/**
+ * Reports whether a Markdown image URL is a reference into `media/` — either workspace-relative (`media/<key>`)
+ * or spelled from the article's own directory (`../../media/<key>`). Deliberately strict so an arbitrary
+ * hand-written path (`./hero.png`, `../uploads/x.jpg`) or a staging draft (`media/drafts/x.png`) is never
+ * mistaken for a canonicalized local reference.
+ */
+export function isLocalMediaRef(url) {
+    const name = refBasename(url);
+    return name !== null && STORAGE_KEY_EXTENSION.test(name);
+}
+/**
+ * Rewrites canonical body image URLs into local mirror references.
+ *
+ * Only a standalone Markdown image line whose URL is the canonical media route AND whose storageKey names an
+ * existing file under `media/` is rewritten. Anything else — an external `https://` src, a data URL, a
+ * reference whose asset is not mirrored, an inline image inside a paragraph, an opaque EmDash block fence —
+ * is left exactly as it arrived, so the transform never invents a broken local link and never rewrites a line
+ * Emit's push guards would refuse to restore.
+ *
+ * A line that already carries a local mirror reference is normalized rather than skipped: its storageKey is
+ * recovered through `storageKeyFromMirrorRef` and rewritten into this function's own spelling, so re-localizing
+ * a document is idempotent and a file written at another depth (a legacy workspace ref, or an article moved
+ * between `draft/` and `published/`) converges on the requested form instead of being reported as an edit.
+ *
+ * When `articleRelPath` is supplied the reference is spelled relative to that article's own directory
+ * (`../../media/<storageKey>` for `posts/draft/…`), which is what lets a Markdown preview resolve the mirror
+ * offline. Without it the reference stays workspace-relative (`media/<storageKey>`), the spelling older
+ * workspaces carry on disk.
+ */
+export function canonicalToLocalMediaRefs(body, options) {
+    const prefix = options.articleRelPath
+        ? `${mediaRefPrefixForArticle(options.articleRelPath)}${MEDIA_DIR_PREFIX}`
+        : MEDIA_DIR_PREFIX;
+    const lines = body.split('\n');
+    const standaloneRegex = /^(!\[([^\]]*)\]\()([^)]+)(\))$/;
+    return lines
+        .map((line) => {
+        const hasCr = line.endsWith('\r');
+        const trimmed = (hasCr ? line.slice(0, -1) : line).trim();
+        if (!trimmed)
+            return line;
+        // Opaque EmDash block fences carry remote JSON inside and are managed by Guard G9.
+        if (/^<!--ec:block\s/.test(trimmed))
+            return line;
+        const match = trimmed.match(standaloneRegex);
+        if (!match)
+            return line;
+        // A canonical route names its storageKey outright; an already-local reference names it through the mirror
+        // spelling, which `storageKeyFromMirrorRef` recovers without a candidate list because the key is written
+        // verbatim in the line. Either way the transform rewrites into `prefix`, never leaving a stale depth.
+        const storageKey = storageKeyFromCanonicalUrl(match[3]) ??
+            storageKeyFromMirrorRef(match[3], EMPTY_STORAGE_KEY_CANDIDATES);
+        if (!storageKey)
+            return line;
+        if (!options.fs.existsSync(`${options.mediaDir}/${storageKey}`))
+            return line;
+        const rewritten = `${match[1]}${prefix}${storageKey}${match[4]}`;
+        return hasCr ? `${rewritten}\r` : rewritten;
+    })
+        .join('\n');
+}
+/**
+ * Resolves a local mirror reference back to its storageKey.
+ *
+ * A reference that spells a storageKey outright (`media/<storageKey>` or the article-relative
+ * `../../media/<storageKey>`) is returned verbatim: the key names its own mirror, so no lookup is needed. Any
+ * other name — a `<stem>--<mediaId>` collision suffix or a truncated stem — is recovered by asking
+ * `candidateStorageKeys`, the storageKeys Emit has confirmed through `media_state` and companion YAML, which
+ * one sanitizes to that stem. A reference no confirmed mirror owns yields null, so a hand-written path still
+ * reaches the push guards instead of being silently rewritten.
+ */
+export function storageKeyFromMirrorRef(rawPath, candidateStorageKeys) {
+    const name = refBasename(rawPath);
+    if (!name)
+        return null;
+    // The reference may already be the storageKey itself. Confirming it against recorded metadata keeps an
+    // unmirrored key unresolved, but a bare storageKey needs no stem translation.
+    const confirmed = [...candidateStorageKeys];
+    if (confirmed.length === 0 && STORAGE_KEY_EXTENSION.test(name))
+        return name;
+    for (const key of confirmed) {
+        if (key === name)
+            return key;
+    }
+    const stem = name.replace(/\.[A-Za-z0-9]{1,11}$/, '');
+    if (!stem)
+        return null;
+    // A collision-suffixed mirror is named `<stem>--<mediaId>` by `collisionSuffixedMarkdownRef`, so the suffix
+    // must come off before the stem is matched against confirmed storageKeys.
+    const bareStem = stem.replace(/--[0-9A-HJ-NP-Z]{26}$/i, '');
+    for (const key of confirmed) {
+        const ref = storageKeyToMarkdownRef(key);
+        if (ref && (ref === stem || ref === bareStem))
+            return key;
+    }
+    return null;
+}
+/**
+ * Builds the `../../` depth an article at `articleRelPath` needs to reach `media/` from its own directory,
+ * matching the prefix the draft-image guards already accept.
+ */
+export function mediaRefPrefixForArticle(articleRelPath) {
+    const dir = articleRelPath.split('/').slice(0, -1).join('/');
+    const depth = dir ? dir.split('/').length : 0;
+    return '../'.repeat(Math.max(depth, 1));
+}
+/** True when every standalone image line already carries `prefix` plus a mirrored storageKey. */
+function isLocalizedIn(body, prefix, fs) {
+    let sawLocalRef = false;
+    const standaloneRegex = /^!?\[([^\]]*)\]\(([^)]+)\)$/;
+    for (const rawLine of body.split('\n')) {
+        const trimmed = (rawLine.endsWith('\r') ? rawLine.slice(0, -1) : rawLine).trim();
+        if (!trimmed || /^<!--ec:block\s/.test(trimmed))
+            continue;
+        const match = trimmed.match(standaloneRegex);
+        if (!match)
+            continue;
+        const ref = match[2].trim();
+        if (isCanonicalMediaUrl(ref))
+            continue; // An unmirrored reference carries no local spelling either way.
+        const name = refBasename(ref);
+        if (name === null || !STORAGE_KEY_EXTENSION.test(name))
+            return false;
+        if (!ref.startsWith(prefix))
+            return false;
+        sawLocalRef = true;
+    }
+    return sawLocalRef;
+}
+/**
+ * Chooses which local spelling a Markdown document should carry on disk.
+ *
+ * The canonical `/_emdash/api/media/file/<storageKey>` URL is what every baseline, cache hash and remote payload
+ * records; only the file an editor reads may be spelled locally. This helper decides that spelling from what
+ * the workspace already holds: a fresh write prefers the article-relative form (`../../media/<storageKey>`) so
+ * a Markdown preview resolves the mirror offline, while a document already written in the depth-free legacy form
+ * (`preferLegacyRef`, read back from disk) is reproduced in that same form. Reproducing the disk's own spelling
+ * is what keeps `sync_state.local_hash` and an unchanged article's diff honest — re-spelling a file the user
+ * never edited would report a media rewrite nobody made.
+ *
+ * A storageKey with no mirrored binary under `media/` stays canonical in every mode, so the transform can never
+ * invent a broken local link.
+ */
+export function localizeArticleMediaRefs(body, options) {
+    // The transform inspects `media/<storageKey>` existence itself, so the media directory must stay absolute.
+    const mediaDir = `${options.workspaceRoot.replace(/\/$/, '')}/media`;
+    const depthPrefix = `${mediaRefPrefixForArticle(options.articleRelPath)}${MEDIA_DIR_PREFIX}`;
+    // Already written in the requested spelling: leave it byte-identical so its hash stays stable.
+    const targetPrefix = options.preferLegacyRef ? MEDIA_DIR_PREFIX : depthPrefix;
+    if (isLocalizedIn(body, targetPrefix, options.fs))
+        return body;
+    // Otherwise localize from canonical form into the requested spelling. A disk file that already carries the
+    // other local spelling is normalized here too — a draft→published move changes the article's depth, and
+    // re-spelling in the new location keeps the written file honest about where its mirror lives.
+    return canonicalToLocalMediaRefs(body, {
+        mediaDir,
+        fs: options.fs,
+        articleRelPath: options.preferLegacyRef ? undefined : options.articleRelPath,
+    });
+}
+//# sourceMappingURL=media-body-refs.js.map

package/dist/utils/media-body-refs.js.map

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

package/dist/utils/media-refs.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Canonical media reference parsing and fence policy definitions.
+ *
+ * This module consolidates:
+ * 1. Root-relative media route prefix definition.
+ * 2. Fence handling policy (backtick-only for authoring guards, backtick-or-tilde for diagnostics).
+ * 3. Unified scanning of markdown and HTML image references across article bodies.
+ */
+import { MEDIA_FILE_ROUTE_PREFIX } from './media-body-refs.js';
+export { MEDIA_FILE_ROUTE_PREFIX };
+/**
+ * Valid storageKey format: dot-separated 26-char ULID segments with a supported image extension.
+ */
+export declare const VALID_MEDIA_FILE_KEY: RegExp;
+/**
+ * Fence policy declared explicitly:
+ * - guard: 'backtick-only' (G5/G11 preflight guards strictly exempt only backtick code fences).
+ * - diagnostic: 'backtick-or-tilde' (doctor diagnosis treats both ``` and ~~~ as code fences).
+ */
+export declare const FENCE_POLICY: {
+    readonly guard: 'backtick-only';
+    readonly diagnostic: 'backtick-or-tilde';
+};
+export type FencePolicyType = (typeof FENCE_POLICY)[keyof typeof FENCE_POLICY];
+/**
+ * Checks whether a trimmed line starts a code fence according to the specified policy.
+ * - 'backtick-only': recognizes runs of 3 or more backticks (```).
+ * - 'backtick-or-tilde': recognizes runs of 3 or more backticks (```) or tildes (~~~).
+ */
+export declare function isCodeFenceDelimiter(line: string, policy: FencePolicyType): string | null;
+export interface ParsedMediaRefMatch {
+    raw: string;
+    url: string;
+    isMarkdownImage: boolean;
+    isHtmlImage: boolean;
+    line: number;
+}
+/**
+ * Unified scanner for Markdown images (![alt](url)) and HTML <img> tags in content.
+ * Filters out references located inside code fences (according to fencePolicy)
+ * or inside opaque block fences (<!--ec:block ... -->).
+ */
+export declare function scanRawMediaReferences(bodyMarkdown: string, fencePolicy?: FencePolicyType): string[];
+//# sourceMappingURL=media-refs.d.ts.map

package/dist/utils/media-refs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"media-refs.d.ts","sourceRoot":"","sources":["../../src/utils/media-refs.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,OAAO,EAAE,uBAAuB,EAAE,CAAC;AAEnC;;GAEG;AACH,eAAO,MAAM,oBAAoB,QACiD,CAAC;AAEnF;;;;GAIG;AACH,eAAO,MAAM,YAAY;aACvB,KAAK,EAAE,eAAe;aACtB,UAAU,EAAE,mBAAmB;CACvB,CAAC;AAEX,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,YAAY,CAAC,CAAC,MAAM,OAAO,YAAY,CAAC,CAAC;AAE/E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,GAAG,MAAM,GAAG,IAAI,CAYzF;AAED,MAAM,WAAW,mBAAmB;IAClC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,eAAe,EAAE,OAAO,CAAC;IACzB,WAAW,EAAE,OAAO,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;GAIG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,MAAM,EACpB,WAAW,GAAE,eAAoC,GAChD,MAAM,EAAE,CAyDV"}

package/dist/utils/media-refs.js

@@ -0,0 +1,101 @@
+/**
+ * Canonical media reference parsing and fence policy definitions.
+ *
+ * This module consolidates:
+ * 1. Root-relative media route prefix definition.
+ * 2. Fence handling policy (backtick-only for authoring guards, backtick-or-tilde for diagnostics).
+ * 3. Unified scanning of markdown and HTML image references across article bodies.
+ */
+import { MEDIA_FILE_ROUTE_PREFIX } from './media-body-refs.js';
+export { MEDIA_FILE_ROUTE_PREFIX };
+/**
+ * Valid storageKey format: dot-separated 26-char ULID segments with a supported image extension.
+ */
+export const VALID_MEDIA_FILE_KEY = /^[0-9A-HJ-NP-Z]{26}(\.[0-9A-HJ-NP-Z]{26})*\.(jpg|jpeg|png|gif|webp|avif|svg)$/i;
+/**
+ * Fence policy declared explicitly:
+ * - guard: 'backtick-only' (G5/G11 preflight guards strictly exempt only backtick code fences).
+ * - diagnostic: 'backtick-or-tilde' (doctor diagnosis treats both ``` and ~~~ as code fences).
+ */
+export const FENCE_POLICY = {
+    guard: 'backtick-only',
+    diagnostic: 'backtick-or-tilde',
+};
+/**
+ * Checks whether a trimmed line starts a code fence according to the specified policy.
+ * - 'backtick-only': recognizes runs of 3 or more backticks (```).
+ * - 'backtick-or-tilde': recognizes runs of 3 or more backticks (```) or tildes (~~~).
+ */
+export function isCodeFenceDelimiter(line, policy) {
+    const trimmed = line.trim();
+    if (policy === FENCE_POLICY.diagnostic) {
+        if (trimmed.startsWith('```') || trimmed.startsWith('~~~')) {
+            return trimmed.slice(0, 3);
+        }
+        return null;
+    }
+    if (trimmed.startsWith('```')) {
+        return trimmed.slice(0, 3);
+    }
+    return null;
+}
+/**
+ * Unified scanner for Markdown images (![alt](url)) and HTML <img> tags in content.
+ * Filters out references located inside code fences (according to fencePolicy)
+ * or inside opaque block fences (<!--ec:block ... -->).
+ */
+export function scanRawMediaReferences(bodyMarkdown, fencePolicy = FENCE_POLICY.guard) {
+    const references = new Set();
+    const lines = bodyMarkdown.split('\n');
+    let inFence = false;
+    let fenceDelimiter = '';
+    let inOpaqueFence = false;
+    for (const rawLine of lines) {
+        const trimmed = rawLine.replace(/\r$/, '').trim();
+        // Check opaque fences (<!--ec:block ... -->)
+        if (/^<!--ec:block\s/.test(trimmed)) {
+            inOpaqueFence = !/^.*-->$/.test(trimmed);
+            continue;
+        }
+        if (inOpaqueFence) {
+            if (/^.*-->$/.test(trimmed)) {
+                inOpaqueFence = false;
+            }
+            continue;
+        }
+        // Check code fences
+        const delim = isCodeFenceDelimiter(trimmed, fencePolicy);
+        if (delim) {
+            if (!inFence) {
+                inFence = true;
+                fenceDelimiter = delim;
+                continue;
+            }
+            else if (trimmed.startsWith(fenceDelimiter)) {
+                inFence = false;
+                continue;
+            }
+        }
+        if (inFence)
+            continue;
+        // 1. Markdown image syntax: ![alt](url)
+        const mdRegex = /!\[.*?\]\(([^)\s]+)(?:\s+["'].*?["'])?\)/g;
+        let match;
+        while ((match = mdRegex.exec(trimmed)) !== null) {
+            const url = match[1].trim();
+            if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('data:')) {
+                references.add(url);
+            }
+        }
+        // 2. HTML <img> tags: <img src="...">
+        const htmlRegex = /<img[^>]+src=["']([^"']+)["']/gi;
+        while ((match = htmlRegex.exec(trimmed)) !== null) {
+            const url = match[1].trim();
+            if (!url.startsWith('http://') && !url.startsWith('https://') && !url.startsWith('data:')) {
+                references.add(url);
+            }
+        }
+    }
+    return Array.from(references).sort();
+}
+//# sourceMappingURL=media-refs.js.map

package/dist/utils/media-refs.js.map

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

package/dist/utils/naming.d.ts

@@ -27,6 +27,37 @@ export declare function extractDatePrefixFromPath(filePath: string): string | nu
  * Strips any leading yyyyMMdd_ date prefix from a filename or path.
  */
 export declare function stripDatePrefix(filenameOrPath: string): string;
+/**
+ * Maximum UTF-8 byte length for a mirrored media filename stem. Media mirrors keep the storageKey's
+ * own basename, which can be a long migrated path, so the stem is capped well below the 255-byte POSIX
+ * NAME_MAX to leave room for the extension and any collision suffix.
+ */
+export declare const DEFAULT_MAX_MEDIA_REF_BYTES = 180;
+/**
+ * Derives the canonical local mirror name (`markdownRef`) from an EmDash media `storageKey`.
+ *
+ * A mirror is named after the storageKey — the identifier the article body actually references — so a
+ * Markdown image URL resolves to a file of the same name on disk, and the binary plus its companion YAML
+ * form one visibly matching pair. The record id is deliberately NOT part of the name: migrated storageKeys
+ * are arbitrary paths rather than ULIDs, so an id can never be recovered from a filename, and Emit reads
+ * it from the companion YAML (`id:`) and `media_state.media_id` instead.
+ *
+ * Sanitizing rules (cross-platform, no symlinks):
+ * - Only the storageKey's basename is used; migrated keys such as `uploads/2026/11/sample.png` collapse
+ *   to their final path segment.
+ * - Filesystem-invalid characters and control characters are removed, whitespace collapses to `-`.
+ * - Multi-ULID keys (`<ulid1>.<ulid2>.jpg`) keep their dot separators so the key stays recognizable.
+ * - The storageKey's own trailing extension is stripped, because callers append the extension they write:
+ *   a storageKey already ends in one, and re-appending it would produce `<key>.jpg.jpg`.
+ * - The result is truncated on a UTF-8 code point boundary.
+ * Returns `null` when the storageKey carries no usable name at all.
+ */
+export declare function storageKeyToMarkdownRef(storageKey: string, maxBytes?: number): string | null;
+/**
+ * Disambiguates two storageKeys that sanitize to the same basename by appending the media record id.
+ * Deterministic: the same key and id always produce the same name, so re-running a pull never churns.
+ */
+export declare function collisionSuffixedMarkdownRef(markdownRef: string, mediaId: string): string;
 /**
  * Extracts the 26-character ULID from a filename or path, stripping any date prefix.
  * Returns null if no valid ULID is present.

package/dist/utils/naming.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/utils/naming.ts"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAgC,GACzC,MAAM,CA+BR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAmBzE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW7E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAC/B,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/E"}
+{"version":3,"file":"naming.d.ts","sourceRoot":"","sources":["../../src/utils/naming.ts"],"names":[],"mappings":"AAwBA;;;;GAIG;AACH,eAAO,MAAM,uBAAuB,MAAM,CAAC;AAE3C;;GAEG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,MAAM,CAYvE;AAED;;;;GAIG;AACH,wBAAgB,wBAAwB,CACtC,KAAK,EAAE,MAAM,EACb,QAAQ,GAAE,MAAgC,GACzC,MAAM,CA+BR;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAAG,MAAM,CAmBzE;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAIzE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,CAG9D;AAED;;;;GAIG;AACH,eAAO,MAAM,2BAA2B,MAAM,CAAC;AAE/C;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,uBAAuB,CACrC,UAAU,EAAE,MAAM,EAClB,QAAQ,GAAE,MAAoC,GAC7C,MAAM,GAAG,IAAI,CAyBf;AAED;;;GAGG;AACH,wBAAgB,4BAA4B,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAGzF;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,cAAc,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAW7E;AAED;;GAEG;AACH,wBAAgB,0BAA0B,CACxC,UAAU,EAAE,MAAM,EAClB,MAAM,EAAE,MAAM,EACd,EAAE,EAAE,MAAM,EACV,WAAW,EAAE,MAAM,EACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,IAAI,GAC/B,MAAM,CAIR;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAI/E"}

package/dist/utils/naming.js

@@ -110,6 +110,64 @@ export function stripDatePrefix(filenameOrPath) {
     const base = path.basename(filenameOrPath);
     return base.replace(/^\d{8}_/, '');
 }
+/**
+ * Maximum UTF-8 byte length for a mirrored media filename stem. Media mirrors keep the storageKey's
+ * own basename, which can be a long migrated path, so the stem is capped well below the 255-byte POSIX
+ * NAME_MAX to leave room for the extension and any collision suffix.
+ */
+export const DEFAULT_MAX_MEDIA_REF_BYTES = 180;
+/**
+ * Derives the canonical local mirror name (`markdownRef`) from an EmDash media `storageKey`.
+ *
+ * A mirror is named after the storageKey — the identifier the article body actually references — so a
+ * Markdown image URL resolves to a file of the same name on disk, and the binary plus its companion YAML
+ * form one visibly matching pair. The record id is deliberately NOT part of the name: migrated storageKeys
+ * are arbitrary paths rather than ULIDs, so an id can never be recovered from a filename, and Emit reads
+ * it from the companion YAML (`id:`) and `media_state.media_id` instead.
+ *
+ * Sanitizing rules (cross-platform, no symlinks):
+ * - Only the storageKey's basename is used; migrated keys such as `uploads/2026/11/sample.png` collapse
+ *   to their final path segment.
+ * - Filesystem-invalid characters and control characters are removed, whitespace collapses to `-`.
+ * - Multi-ULID keys (`<ulid1>.<ulid2>.jpg`) keep their dot separators so the key stays recognizable.
+ * - The storageKey's own trailing extension is stripped, because callers append the extension they write:
+ *   a storageKey already ends in one, and re-appending it would produce `<key>.jpg.jpg`.
+ * - The result is truncated on a UTF-8 code point boundary.
+ * Returns `null` when the storageKey carries no usable name at all.
+ */
+export function storageKeyToMarkdownRef(storageKey, maxBytes = DEFAULT_MAX_MEDIA_REF_BYTES) {
+    if (!storageKey || !storageKey.trim())
+        return null;
+    const basename = storageKey.replace(/\\/g, '/').split('/').pop() || '';
+    let clean = basename
+        .replace(/[<>:"/\\|?*\x00-\x1F]/g, '')
+        .replace(/\s+/g, '-')
+        .trim();
+    // A leading dot would create a hidden file (or `.` / `..`), which no mirror may be.
+    clean = clean.replace(/^\.+/, '');
+    if (!clean)
+        return null;
+    // Drop the storageKey's own extension: the stem is shared by the binary and its `.yaml` companion, so
+    // every caller appends the extension it actually writes and a key that already ends in one must not
+    // produce `<key>.jpg.jpg`.
+    clean = clean.replace(/\.[A-Za-z0-9]{1,11}$/, '');
+    if (!clean)
+        return null;
+    // Trailing whitespace collapses to hyphens before the extension is known, so trim what the removal leaves.
+    clean = clean.replace(/^[-.\s]+|[-.\s]+$/g, '');
+    if (!clean)
+        return null;
+    clean = truncateUtf8Bytes(clean, maxBytes).replace(/[.\s-]+$/, '');
+    return clean || null;
+}
+/**
+ * Disambiguates two storageKeys that sanitize to the same basename by appending the media record id.
+ * Deterministic: the same key and id always produce the same name, so re-running a pull never churns.
+ */
+export function collisionSuffixedMarkdownRef(markdownRef, mediaId) {
+    const id = mediaId.trim().toUpperCase();
+    return `${markdownRef}--${id}`;
+}
 /**
  * Extracts the 26-character ULID from a filename or path, stripping any date prefix.
  * Returns null if no valid ULID is present.

package/dist/utils/naming.js.map

@@ -1 +1 @@
-{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../src/utils/naming.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B;;;;GAIG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,GAAG,CAAC;AAE3C;;GAEG;AACH,MAAM,UAAU,iBAAiB,CAAC,GAAW,EAAE,QAAgB;IAC7D,IAAI,MAAM,CAAC,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,IAAI,QAAQ,EAAE,CAAC;QAC/C,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,MAAM,IAAI,IAAI,GAAG,EAAE,CAAC;QACvB,IAAI,MAAM,CAAC,UAAU,CAAC,MAAM,GAAG,IAAI,EAAE,MAAM,CAAC,GAAG,QAAQ,EAAE,CAAC;YACxD,MAAM;QACR,CAAC;QACD,MAAM,IAAI,IAAI,CAAC;IACjB,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,wBAAwB,CACtC,KAAa,EACb,QAAQ,GAAW,uBAAuB;IAE1C,IAAI,CAAC,KAAK,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,EAAE,CAAC;QAC5B,OAAO,UAAU,CAAC;IACpB,CAAC;IAED,0EAA0E;IAC1E,IAAI,KAAK,GAAG,KAAK;SACd,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,SAAS,EAAE,GAAG,CAAC;SACvB,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC;SACtB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC;SACxB,OAAO,CAAC,UAAU,EAAE,GAAG,CAAC,CAAC;IAE5B,8DAA8D;IAC9D,KAAK,GAAG,KAAK;SACV,OAAO,CAAC,wBAAwB,EAAE,EAAE,CAAC;SACrC,IAAI,EAAE;SACN,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAExB,iEAAiE;IACjE,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,OAAO,CAAC,UAAU,EAAE,EAAE,CAAC,CAAC;IAE7D,gDAAgD;IAChD,KAAK,GAAG,iBAAiB,CAAC,KAAK,EAAE,QAAQ,CAAC,CAAC;IAE3C,+CAA+C;IAC/C,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAEjC,OAAO,KAAK,IAAI,UAAU,CAAC;AAC7B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAgC;IAC/D,IAAI,CAAC,SAAS,EAAE,CAAC;QACf,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,OAAO,GAAG,GAAG,CAAC,WAAW,EAAE,GAAG,MAAM,CAAC,GAAG,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,MAAM,CAAC,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,GAAG,CAAC;IACxH,CAAC;IAED,IAAI,OAAO,SAAS,KAAK,QAAQ,EAAE,CAAC;QAClC,MAAM,KAAK,GAAG,SAAS,CAAC,KAAK,CAAC,2BAA2B,CAAC,CAAC;QAC3D,IAAI,KAAK,EAAE,CAAC;YACV,OAAO,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC;QAC9C,CAAC;IACH,CAAC;IAED,MAAM,CAAC,GAAG,SAAS,YAAY,IAAI,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,CAAC;IACtE,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IACtD,MAAM,IAAI,GAAG,SAAS,CAAC,WAAW,EAAE,CAAC;IACrC,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,QAAQ,EAAE,GAAG,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC7D,MAAM,EAAE,GAAG,MAAM,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IACxD,OAAO,GAAG,IAAI,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CAAC,QAAgB;IACxD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC,CAAC;IACtC,OAAO,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACvC,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,cAAsB;IACpD,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAC3C,OAAO,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;AACrC,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,uBAAuB,CAAC,cAAsB;IAC5D,MAAM,eAAe,GAAG,eAAe,CAAC,cAAc,CAAC,CAAC;IACxD,MAAM,KAAK,GAAG,eAAe,CAAC,KAAK,CAAC,gCAAgC,CAAC,CAAC;IACtE,IAAI,KAAK;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,CAAC;IAE3B,MAAM,WAAW,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IACjD,MAAM,SAAS,GAAG,WAAW,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,eAAe,CAAC;IAC/F,IAAI,SAAS,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,0BAA0B,CACxC,UAAkB,EAClB,MAAc,EACd,EAAU,EACV,WAAmB,EACnB,SAAgC;IAEhC,MAAM,MAAM,GAAG,gBAAgB,CAAC,SAAS,CAAC,CAAC;IAC3C,MAAM,SAAS,GAAG,wBAAwB,CAAC,WAAW,CAAC,CAAC;IACxD,OAAO,GAAG,UAAU,IAAI,MAAM,IAAI,MAAM,GAAG,EAAE,IAAI,SAAS,KAAK,CAAC;AAClE,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,0BAA0B,CAAC,KAAa,EAAE,KAAa;IACrE,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,MAAM,CAAC,GAAG,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC/B,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;AACpC,CAAC"}
+{"version":3,"file":"naming.js","sourceRoot":"","sources":["../../src/utils/naming.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "emdash-emit",
-  "version": "0.1.13",
+  "version": "0.1.15",
   "description": "AI-First Local Workspace & Sync Tool for EmDash (Cloudflare Workers + D1)",
   "author": "hiroaki <45134003+aroooy@users.noreply.github.com>",
   "license": "MIT",