openwriter 0.29.1 → 0.29.2

package/dist/plugins/github/dist/blog-tools.d.ts

@@ -4,5 +4,62 @@
  * Auth: piggybacks on the user's existing `gh auth login`.
  * Persistence: blogSites in plugins['@openwriter/plugin-github'].blogSites.
  */
-import { type PluginMcpTool } from './helpers.js';
+import { type BlogSite, type PluginMcpTool } from './helpers.js';
+/**
+ * Derive the per-site image contract from sampled posts:
+ *  - `image_field`        — which frontmatter key holds the cover
+ *  - `image_path_style`   — do values carry a leading slash?
+ *  - `image_public_prefix`— the dominant directory the images live under
+ *                           (relative, no leading slash)
+ *  - `image_naming`       — `og-{slug}` vs `{slug}` filename convention
+ *                           (detected by the dominant basename shape)
+ * Conservative: only the dominant local-path field is analyzed; full URLs
+ * are ignored. Anything not confidently detected is left undefined so
+ * post_to_blog falls back to its documented defaults.
+ */
+export declare function inferImageConventions(samples: Array<{
+    fm: Record<string, string>;
+    slug: string;
+}>): {
+    image_field?: string;
+    image_path_style?: 'relative' | 'absolute';
+    image_public_prefix?: string;
+    image_naming?: string;
+};
+/** Site's effective path style. Absent ⇒ legacy "absolute". */
+export declare function pathStyleOf(site: Pick<BlogSite, 'image_path_style'>): 'relative' | 'absolute';
+/**
+ * Public reference for one image file under the site's prefix, honoring the
+ * site's path style. The prefix is normalized (leading + trailing slashes
+ * stripped) so storage is style-agnostic — `style` alone decides the leading
+ * slash, which makes the contract unambiguous regardless of how the prefix
+ * was saved (`/images/og` vs `images/og` both behave identically).
+ *   relative → "images/og/x.png"   absolute → "/images/og/x.png"
+ */
+export declare function imageRef(publicPrefix: string, file: string, style: 'relative' | 'absolute'): string;
+/**
+ * Resolve the deterministic cover filename from the site's naming template.
+ *   `{slug}` → post slug
+ *   `{ext}`  → source extension, no dot (preserved from the original)
+ * A template carrying a literal extension and no `{ext}` placeholder
+ * (e.g. `og-{slug}.png`) is respected as authored. Absent template ⇒
+ * `og-{slug}.{ext}`.
+ */
+export declare function coverFilename(template: string | undefined, slug: string, sourceExt: string): string;
+/**
+ * Build the YAML frontmatter from blogContext + site defaults.
+ *
+ * Order of precedence (low → high):
+ *   1. Site `frontmatter_defaults` (e.g. `layout`, `author`, `prerender`)
+ *   2. Generated `title` (from document title — always present)
+ *   3. blogContext fields (description, date, author, tags, slug, draft, coverImage)
+ *
+ * Field-name mapping: blogContext keys are renamed via `site.frontmatter_field_map`
+ * before emit (e.g. `date` → `publishedDate` for Astro sites).
+ *
+ * Top-level openwriter metadata (status, enrichmentStale, tags-as-content-type,
+ * etc.) is NEVER passed through. Frontmatter is built ONLY from blogContext +
+ * defaults — this is the design contract from server/blog-routes.ts.
+ */
+export declare function buildFrontmatter(title: string, blogCtx: Record<string, any>, site: BlogSite, coverImagePath?: string): string;
 export declare function blogTools(): PluginMcpTool[];

package/dist/plugins/github/dist/blog-tools.js

@@ -6,7 +6,7 @@
  */
 import { execFile } from 'child_process';
 import { existsSync, mkdirSync, readFileSync, copyFileSync, writeFileSync, readdirSync, statSync, rmSync } from 'fs';
-import { join, extname, dirname } from 'path';
+import { join, extname, dirname, basename } from 'path';
 import { randomUUID } from 'crypto';
 import { homedir } from 'os';
 import { getServerModules, listBlogSites, writeBlogSites, } from './helpers.js';
@@ -207,6 +207,121 @@ function inferFrontmatterShape(rawSamples) {
     }
     return { defaults, field_map, schema: schemaOrder };
 }
+// ---- Image-contract inference (inspect_blog_repo) ----
+// adr: adr/blog-image-contract.md
+const IMAGE_FIELD_CANDIDATES = [
+    'image', 'coverImage', 'cover', 'ogImage', 'heroImage', 'featuredImage', 'thumbnail', 'banner',
+];
+const IMAGE_VALUE_RE = /\.(png|jpe?g|webp|gif|avif|svg)\b/i;
+function unquoteScalar(s) {
+    const m = s.match(/^["'](.*)["']$/);
+    return m ? m[1] : s;
+}
+/**
+ * Pick the frontmatter key that holds the post's cover image. Prefers the
+ * conventional names in order; the value must look like a local image path
+ * (carries an image extension). Falls back to any field whose value does.
+ */
+function pickImageField(fm) {
+    for (const k of IMAGE_FIELD_CANDIDATES) {
+        const raw = fm[k];
+        if (!raw || raw === '<multiline>')
+            continue;
+        const v = unquoteScalar(raw);
+        if (IMAGE_VALUE_RE.test(v))
+            return { key: k, value: v };
+    }
+    for (const [k, raw] of Object.entries(fm)) {
+        if (raw === '<multiline>')
+            continue;
+        const v = unquoteScalar(raw);
+        if (IMAGE_VALUE_RE.test(v))
+            return { key: k, value: v };
+    }
+    return null;
+}
+/**
+ * Derive the per-site image contract from sampled posts:
+ *  - `image_field`        — which frontmatter key holds the cover
+ *  - `image_path_style`   — do values carry a leading slash?
+ *  - `image_public_prefix`— the dominant directory the images live under
+ *                           (relative, no leading slash)
+ *  - `image_naming`       — `og-{slug}` vs `{slug}` filename convention
+ *                           (detected by the dominant basename shape)
+ * Conservative: only the dominant local-path field is analyzed; full URLs
+ * are ignored. Anything not confidently detected is left undefined so
+ * post_to_blog falls back to its documented defaults.
+ */
+export function inferImageConventions(samples) {
+    const hits = [];
+    for (const s of samples) {
+        const pick = pickImageField(s.fm);
+        if (pick)
+            hits.push({ ...pick, slug: s.slug });
+    }
+    if (hits.length === 0)
+        return {};
+    // Dominant cover field name
+    const fieldCounts = new Map();
+    for (const h of hits)
+        fieldCounts.set(h.key, (fieldCounts.get(h.key) || 0) + 1);
+    const image_field = [...fieldCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    // Only local paths of the dominant field tell us about the path contract
+    const local = hits.filter((h) => h.key === image_field && !/^https?:\/\//i.test(h.value) && !h.value.startsWith('//'));
+    if (local.length === 0)
+        return { image_field };
+    // Path style: majority leading-slash ⇒ absolute
+    const abs = local.filter((h) => h.value.startsWith('/')).length;
+    const image_path_style = abs > local.length / 2 ? 'absolute' : 'relative';
+    // Public prefix: dominant directory portion (no leading/trailing slash)
+    const dirCounts = new Map();
+    for (const h of local) {
+        const noSlash = h.value.replace(/^\/+/, '');
+        const dir = noSlash.includes('/') ? noSlash.slice(0, noSlash.lastIndexOf('/')) : '';
+        dirCounts.set(dir, (dirCounts.get(dir) || 0) + 1);
+    }
+    const topDir = [...dirCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    const image_public_prefix = topDir || undefined;
+    // Naming convention by dominant basename shape + extension
+    let ogCount = 0;
+    let slugCount = 0;
+    const extCounts = new Map();
+    for (const h of local) {
+        const base = h.value.replace(/^.*\//, '');
+        const ext = (base.match(/\.([a-z0-9]+)$/i)?.[1] || 'png').toLowerCase();
+        extCounts.set(ext, (extCounts.get(ext) || 0) + 1);
+        const stem = base.replace(/\.[a-z0-9]+$/i, '');
+        if (stem === h.slug)
+            slugCount++;
+        else if (stem.startsWith('og-'))
+            ogCount++;
+    }
+    const dominantExt = [...extCounts.entries()].sort((a, b) => b[1] - a[1])[0][0];
+    let image_naming;
+    if (slugCount > local.length / 2)
+        image_naming = `{slug}.${dominantExt}`;
+    else if (ogCount > local.length / 2)
+        image_naming = `og-{slug}.${dominantExt}`;
+    // else: undefined ⇒ post_to_blog default (og-{slug}.{ext})
+    return { image_field, image_path_style, image_public_prefix, image_naming };
+}
+/**
+ * Map an inferred (relative) public image prefix to the on-disk image_dir
+ * for the framework's static-asset root.
+ */
+function imageDirForFramework(fw, prefix) {
+    switch (fw) {
+        case 'astro':
+        case 'next':
+            return `public/${prefix}`;
+        case 'hugo':
+            return `static/${prefix}`;
+        case 'jekyll':
+            return prefix; // served from repo root
+        default:
+            return `public/${prefix}`;
+    }
+}
 /**
  * Detect the site's public URL from common static-host conventions:
  *  - `CNAME` at repo root or `public/CNAME` (GitHub Pages / Cloudflare Pages / Netlify)
@@ -320,6 +435,49 @@ function formatDate(v) {
     const m = v.match(/^(\d{4}-\d{2}-\d{2})/);
     return m ? m[1] : v;
 }
+// ---- Per-site image contract (path style + cover naming) ----
+// adr: adr/blog-image-contract.md
+//
+// The image reference is a PER-SITE CONTRACT, not a global assumption. Two
+// dimensions, both stored on BlogSite and inferred by inspect_blog_repo:
+//   1. path style — does the value carry a leading slash, or does the site's
+//      template prepend one? (`image_path_style`)
+//   2. cover filename — deterministic `og-{slug}.{ext}`, never the raw
+//      `/_images/` name, so republish is idempotent and never orphans.
+//        (`image_naming`)
+// Absent keys ⇒ legacy behavior ("absolute", raw name) so already-correct
+// sites never regress.
+/** Site's effective path style. Absent ⇒ legacy "absolute". */
+export function pathStyleOf(site) {
+    return site.image_path_style === 'relative' ? 'relative' : 'absolute';
+}
+/**
+ * Public reference for one image file under the site's prefix, honoring the
+ * site's path style. The prefix is normalized (leading + trailing slashes
+ * stripped) so storage is style-agnostic — `style` alone decides the leading
+ * slash, which makes the contract unambiguous regardless of how the prefix
+ * was saved (`/images/og` vs `images/og` both behave identically).
+ *   relative → "images/og/x.png"   absolute → "/images/og/x.png"
+ */
+export function imageRef(publicPrefix, file, style) {
+    const seg = (publicPrefix || '').replace(/^\/+/, '').replace(/\/+$/, '');
+    const rel = seg ? `${seg}/${file}` : file;
+    return style === 'absolute' ? `/${rel}` : rel;
+}
+/**
+ * Resolve the deterministic cover filename from the site's naming template.
+ *   `{slug}` → post slug
+ *   `{ext}`  → source extension, no dot (preserved from the original)
+ * A template carrying a literal extension and no `{ext}` placeholder
+ * (e.g. `og-{slug}.png`) is respected as authored. Absent template ⇒
+ * `og-{slug}.{ext}`.
+ */
+export function coverFilename(template, slug, sourceExt) {
+    const ext = sourceExt.replace(/^\.+/, '');
+    return (template || 'og-{slug}.{ext}')
+        .replace(/\{slug\}/g, slug)
+        .replace(/\{ext\}/g, ext);
+}
 /**
  * Build the YAML frontmatter from blogContext + site defaults.
  *
@@ -335,7 +493,7 @@ function formatDate(v) {
  * etc.) is NEVER passed through. Frontmatter is built ONLY from blogContext +
  * defaults — this is the design contract from server/blog-routes.ts.
  */
-function buildFrontmatter(title, blogCtx, site, coverImagePath) {
+export function buildFrontmatter(title, blogCtx, site, coverImagePath) {
     const fm = {};
     const map = site.frontmatter_field_map || {};
     // 1. Site defaults (lowest priority — overridable below)
@@ -463,16 +621,35 @@ export function blogTools() {
                     return (detected ? rel.startsWith(detected + '/') : true) && /\.(md|mdx)$/i.test(rel);
                 })
                     .slice(0, 10);
-                const rawSamples = [];
+                const sampleData = [];
                 for (const f of sampleFiles) {
                     try {
-                        rawSamples.push(parseYamlFrontmatter(readFileSync(f, 'utf-8')));
+                        const fm = parseYamlFrontmatter(readFileSync(f, 'utf-8'));
+                        const slug = basename(f).replace(/\.(md|mdx)$/i, '');
+                        sampleData.push({ fm, slug });
                     }
                     catch { /* skip */ }
                 }
+                const rawSamples = sampleData.map((s) => s.fm);
                 const samplesAfterFilter = rawSamples.filter((s) => !looksLikeOpenwriterLeak(s));
                 const samplesSkipped = rawSamples.length - samplesAfterFilter.length;
                 const shape = inferFrontmatterShape(rawSamples);
+                // Per-site image contract — inferred from real posts (path style, the
+                // directory images live under, og-{slug} vs {slug} naming, and which
+                // frontmatter field holds the cover). Leak samples excluded so the
+                // old plugin's emit doesn't poison detection. adr: adr/blog-image-contract.md
+                const conv = inferImageConventions(sampleData.filter((s) => !looksLikeOpenwriterLeak(s.fm)));
+                const imagePublicPrefix = conv.image_public_prefix ?? defaults.image_public_prefix;
+                const imageDir = conv.image_public_prefix
+                    ? imageDirForFramework(framework, conv.image_public_prefix)
+                    : defaults.image_dir;
+                const imagePathStyle = conv.image_path_style ?? 'absolute';
+                const imageNaming = conv.image_naming ?? 'og-{slug}.{ext}';
+                // Cover field-name mapping (e.g. site uses `image:` not `coverImage:`)
+                const fieldMap = { ...shape.field_map };
+                if (conv.image_field && conv.image_field !== 'coverImage') {
+                    fieldMap.coverImage = conv.image_field;
+                }
                 const confidence = framework !== 'unknown' && detected ? 'high'
                     : detected ? 'medium'
                         : 'low';
@@ -482,11 +659,13 @@ export function blogTools() {
                     repo,
                     framework,
                     content_dir: defaults.content_dir,
-                    image_dir: defaults.image_dir,
-                    image_public_prefix: defaults.image_public_prefix,
+                    image_dir: imageDir,
+                    image_public_prefix: imagePublicPrefix,
+                    image_path_style: imagePathStyle,
+                    image_naming: imageNaming,
                     frontmatter_schema: shape.schema,
                     frontmatter_defaults: shape.defaults,
-                    frontmatter_field_map: shape.field_map,
+                    frontmatter_field_map: fieldMap,
                     // Always propose a pattern even when site_url is unknown so the user can fill in the URL
                     site_url: siteUrl,
                     blog_url_pattern: '/blog/{slug}/',
@@ -509,7 +688,9 @@ export function blogTools() {
                     branch: { type: 'string', description: 'Branch to push to (default: main)' },
                     content_dir: { type: 'string', description: 'Directory where post .md files live (e.g. "src/content/blog")' },
                     image_dir: { type: 'string', description: 'Directory where image files write (e.g. "public/blog-images")' },
-                    image_public_prefix: { type: 'string', description: 'URL prefix for images in markdown (e.g. "/blog-images")' },
+                    image_public_prefix: { type: 'string', description: 'Directory prefix images live under (e.g. "images/og" or "/blog-images"). The leading slash is governed by image_path_style, not by how this is stored.' },
+                    image_path_style: { type: 'string', enum: ['relative', 'absolute'], description: 'How image paths are written: "relative" = no leading slash (`images/og/x.png`; the template prepends one), "absolute" = leading slash (`/images/og/x.png`; used verbatim). inspect_blog_repo infers this from existing posts. Default: "absolute" (legacy).' },
+                    image_naming: { type: 'string', description: 'Cover filename template with `{slug}` + `{ext}` placeholders. Default "og-{slug}.{ext}". Deterministic: same doc+slug ⇒ same filename every republish (no orphaned covers).' },
                     framework: { type: 'string', enum: ['astro', 'next', 'jekyll', 'hugo', 'unknown'], description: 'Site framework' },
                     frontmatter_defaults: {
                         type: 'object',
@@ -553,6 +734,12 @@ export function blogTools() {
                 if (params.frontmatter_field_map && typeof params.frontmatter_field_map === 'object') {
                     site.frontmatter_field_map = params.frontmatter_field_map;
                 }
+                if (params.image_path_style === 'relative' || params.image_path_style === 'absolute') {
+                    site.image_path_style = params.image_path_style;
+                }
+                if (typeof params.image_naming === 'string' && params.image_naming.trim()) {
+                    site.image_naming = params.image_naming.trim();
+                }
                 if (Array.isArray(params.frontmatter_schema)) {
                     site.frontmatter_schema = params.frontmatter_schema.map(String);
                 }
@@ -685,24 +872,35 @@ export function blogTools() {
                 if (!slug)
                     return { error: 'Could not derive a slug from the title.' };
                 // Rewrite inline image refs in body, collect filenames
-                const imgPrefix = site.image_public_prefix.replace(/\/+$/, '');
+                // Per-site image contract: path style governs the leading slash on
+                // every emitted reference (cover + inline body). adr: adr/blog-image-contract.md
+                const style = pathStyleOf(site);
+                // Inline body images keep their source (hash) filenames — only the
+                // path style is normalized. Deterministic slug naming is scoped to the
+                // COVER for now (inline naming is a noted follow-up in the ADR).
                 const imageRefs = new Set();
                 const bodyRewritten = bodyMd.replace(/\/_images\/([^\s)"'<>]+)/g, (_m, fn) => {
                     imageRefs.add(fn);
-                    return `${imgPrefix}/${fn}`;
+                    return imageRef(site.image_public_prefix, fn, style);
                 });
-                // Handle cover image from blogContext
+                // Cover image from blogContext → deterministic `og-{slug}.{ext}` name.
+                // Same doc + slug ⇒ same filename every republish (idempotent
+                // overwrite, no orphaned cover). Source extension is preserved.
                 let coverImagePath;
+                let coverSrcFile;
+                let coverDestFile;
                 if (typeof blogCtx.coverImage === 'string' && blogCtx.coverImage) {
-                    const coverFile = blogCtx.coverImage.replace(/^\/_images\//, '');
-                    imageRefs.add(coverFile);
-                    coverImagePath = `${imgPrefix}/${coverFile}`;
+                    coverSrcFile = blogCtx.coverImage.replace(/^\/_images\//, '');
+                    const ext = extname(coverSrcFile) || '.png';
+                    coverDestFile = coverFilename(site.image_naming, slug, ext);
+                    coverImagePath = imageRef(site.image_public_prefix, coverDestFile, style);
                 }
                 // Copy images
                 const dataDir = srv.getDataDir();
                 const imageDirAbs = join(clonePath, site.image_dir);
                 mkdirSync(imageDirAbs, { recursive: true });
                 let imagesCopied = 0;
+                // Inline images — copied under their source filename
                 for (const fn of imageRefs) {
                     const src = join(dataDir, '_images', fn);
                     if (!existsSync(src))
@@ -712,6 +910,16 @@ export function blogTools() {
                     copyFileSync(src, dst);
                     imagesCopied++;
                 }
+                // Cover — copied under the deterministic slug-based name
+                if (coverSrcFile && coverDestFile) {
+                    const src = join(dataDir, '_images', coverSrcFile);
+                    if (existsSync(src)) {
+                        const dst = join(imageDirAbs, coverDestFile);
+                        mkdirSync(dirname(dst), { recursive: true });
+                        copyFileSync(src, dst);
+                        imagesCopied++;
+                    }
+                }
                 // Write the post file
                 const frontmatter = buildFrontmatter(title, blogCtx, site, coverImagePath);
                 const postRel = join(site.content_dir, `${slug}.md`);
@@ -780,6 +988,9 @@ export function blogTools() {
                     file: postRel.replace(/\\/g, '/'),
                     commit: shortHash,
                     images_committed: noChanges ? 0 : imagesCopied,
+                    // Transparency: the exact cover path written to frontmatter + the
+                    // filename it shipped as, so the agent/user sees what landed.
+                    ...(coverImagePath ? { image: coverImagePath, cover_file: coverDestFile } : {}),
                     live_url: liveUrl,
                     message: noChanges
                         ? 'No changes — file already up to date. Doc marked as sent.'

package/dist/plugins/github/dist/helpers.d.ts

@@ -79,6 +79,27 @@ export interface BlogSite {
      * Default: `/blog/{slug}/`. Used together with `site_url` to build the live URL.
      */
     blog_url_pattern?: string;
+    /**
+     * How image paths are written into frontmatter + body:
+     *   "relative" — no leading slash (`images/og/x.png`); the site's template
+     *                prepends the slash (e.g. Astro `<img src={`/${image}`}>`).
+     *   "absolute" — leading slash (`/images/og/x.png`); value used verbatim.
+     * Inferred by inspect_blog_repo from existing posts' image values. Absent ⇒
+     * "absolute" — the legacy behavior the plugin always had before this field.
+     * adr: adr/blog-image-contract.md
+     */
+    image_path_style?: 'relative' | 'absolute';
+    /**
+     * Filename template the published COVER image is copied under. Placeholders:
+     *   `{slug}` — the post slug
+     *   `{ext}`  — the source file's extension, no dot (preserved from the
+     *              `/_images/` original)
+     * Default `og-{slug}.{ext}`. Deterministic: same doc + same slug ⇒ same
+     * cover filename on every republish (idempotent overwrite, no orphaned
+     * cover files). Inferred by inspect_blog_repo from existing posts.
+     * adr: adr/blog-image-contract.md
+     */
+    image_naming?: string;
 }
 export declare function listBlogSites(): Promise<BlogSite[]>;
 export declare function writeBlogSites(sites: BlogSite[]): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.29.1",
+  "version": "0.29.2",
   "description": "The open-source writing surface for AI agents. Markdown-native editor with pending change review — your agent writes, you accept or reject.",
   "type": "module",
   "license": "MIT",