npm - openwriter - Versions diffs - 0.29.0 → 0.29.2 - Mend

openwriter 0.29.0 → 0.29.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (10) hide show

package/dist/client/assets/{index-SAoCjUU-.js → index-DHaZI7nA.js} +13 -13
package/dist/client/index.html +1 -1
package/dist/plugins/github/dist/blog-tools.d.ts +58 -1
package/dist/plugins/github/dist/blog-tools.js +225 -14
package/dist/plugins/github/dist/helpers.d.ts +21 -0
package/dist/server/content-type-meta.js +20 -0
package/dist/server/documents.js +72 -0
package/dist/server/index.js +20 -1
package/dist/server/mcp.js +1 -13
package/package.json +1 -1

package/dist/client/index.html CHANGED Viewed

@@ -10,7 +10,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Charter:ital,wght@0,400;0,700;1,400&family=Crimson+Pro:ital,wght@0,300;0,400;0,600;0,700;1,400&family=DM+Sans:ital,wght@0,400;0,500;0,600;0,700;1,400&family=DM+Serif+Display&family=IBM+Plex+Mono:wght@400;500;600&family=IBM+Plex+Sans:wght@400;500;600&family=Inter:wght@400;500;600;700&family=Libre+Baskerville:ital,wght@0,400;0,700;1,400&family=Literata:ital,opsz,wght@0,7..72,400;0,7..72,600;0,7..72,700;1,7..72,400&family=Newsreader:ital,opsz,wght@0,6..72,400;0,6..72,600;1,6..72,400&family=Playfair+Display:wght@400;600;700;900&family=Source+Serif+4:ital,opsz,wght@0,8..60,400;0,8..60,600;0,8..60,700;1,8..60,400&family=Space+Grotesk:wght@400;500;600;700&family=Space+Mono:wght@400;700&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-SAoCjUU-.js"></script>
+    <script type="module" crossorigin src="/assets/index-DHaZI7nA.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-Gdw1m46J.css">
   </head>
   <body>

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

@@ -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 CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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/dist/server/content-type-meta.js ADDED Viewed

@@ -0,0 +1,20 @@
+// Single source of truth for content-type scaffolding metadata. Maps a
+// content_type to the frontmatter it needs: the `content_type` field itself
+// (which owns the editor surface — adr: adr/browser-write-fidelity.md) plus the
+// type's context object (tweetContext / articleContext / blogContext / …).
+//
+// Used by both the MCP create_document handler and the HTTP POST /api/documents
+// endpoint (the "Create variant" path) so a typed empty doc is scaffolded the
+// same way regardless of who creates it. adr: docs/variants.md
+export function resolveTypeMeta(type, url) {
+    switch (type) {
+        case 'tweet': return { content_type: 'tweet', tweetContext: { mode: 'tweet' } };
+        case 'reply': return { content_type: 'reply', tweetContext: { mode: 'reply', ...(url ? { url } : {}) } };
+        case 'quote': return { content_type: 'quote', tweetContext: { mode: 'quote', ...(url ? { url } : {}) } };
+        case 'article': return { content_type: 'article', articleContext: { active: true } };
+        case 'linkedin': return { content_type: 'linkedin', linkedinContext: { active: true } };
+        case 'newsletter': return { content_type: 'newsletter', newsletterContext: { active: true } };
+        case 'blog': return { content_type: 'blog', blogContext: { active: true } };
+        default: return undefined;
+    }
+}

package/dist/server/documents.js CHANGED Viewed

@@ -8,6 +8,7 @@ import { join } from 'path';
 import matter from 'gray-matter';
 import trash from 'trash';
 import { tiptapToMarkdownChecked, markdownToTiptap } from './markdown.js';
+import { resolveTypeMeta } from './content-type-meta.js';
 import { parseMarkdownContent } from './compact.js';
 import { getDocument, getTitle, getFilePath, getIsTemp, getMetadata, save, cancelDebouncedSave, setActiveDocument, registerExternalDoc, unregisterExternalDoc, getExternalDocs, cacheActiveDocument, getCachedDocument, invalidateDocCache, removePendingCacheEntry, resetDocVersion, markAsAgentStub, unmarkAgentStub, isAgentStub, } from './state.js';
 import { getDataDir, TEMP_PREFIX, ensureDataDir, filePathForTitle, tempFilePath, generateNodeId, resolveDocPath, isExternalDoc, atomicWriteFileSync, canonicalizePath } from './helpers.js';
@@ -1148,6 +1149,77 @@ export function duplicateDocument(filename, variant) {
     const newFilename = filePath.split(/[/\\]/).pop();
     return { document: getDocument(), title: getTitle(), filename: newFilename };
 }
+// Content types that surface an editable title/headline above the body. For
+// these, the doc's frontmatter `title` IS content (blog headline, article title,
+// newsletter subject). For every other type the title is just a sidebar label
+// and the body carries everything. adr: docs/variants.md
+const TITLE_BEARING_TYPES = new Set(['blog', 'article', 'newsletter']);
+/**
+ * Create a variant of `masterFilename` retyped as `variantType`, nested under
+ * the master. Field-projection model (NOT a verbatim clone — that's
+ * duplicateDocument): port the fields the two types share.
+ *  - body: always ported.
+ *  - downcast (title-bearing master → body-only variant): the master's title is
+ *    folded into the body as its first paragraph so the headline isn't lost.
+ *  - the variant is scaffolded with the TARGET type's content_type + context;
+ *    the source's context objects (blogContext, tweetContext, …) are NOT
+ *    inherited — a variant is a new typed doc, not a surface clone.
+ * adr: docs/variants.md
+ */
+export function createVariant(masterFilename, opts) {
+    cancelDebouncedSave();
+    save();
+    const sourcePath = resolveDocPath(masterFilename);
+    if (!existsSync(sourcePath))
+        throw new Error(`Document not found: ${masterFilename}`);
+    const raw = readFileSync(sourcePath, 'utf-8');
+    const parsed = markdownToTiptap(raw);
+    const srcType = deriveContentType(parsed.metadata) || 'document';
+    const tgtType = opts.variantType;
+    const srcTitleBearing = TITLE_BEARING_TYPES.has(srcType);
+    const tgtTitleBearing = TITLE_BEARING_TYPES.has(tgtType);
+    // Body projection. Downcast (title-bearing → body-only): prepend the master's
+    // title as the first paragraph so the headline survives in a surface with no
+    // title field ("title becomes first line, body the next paragraph"). Otherwise
+    // the body ports unchanged.
+    let bodyContent = parsed.document.content || [];
+    if (srcTitleBearing && !tgtTitleBearing && parsed.title) {
+        bodyContent = [
+            { type: 'paragraph', content: [{ type: 'text', text: parsed.title }] },
+            ...bodyContent,
+        ];
+    }
+    const bodyDoc = { ...parsed.document, content: bodyContent };
+    // Title is always label-suffixed: it doubles as the filename + sidebar name,
+    // so it must stay unique vs the master (a raw duplicate title would collide).
+    // The title CONTENT still rides along for title-bearing targets — they render
+    // it as the headline and the user trims the suffix.
+    const Label = tgtType.charAt(0).toUpperCase() + tgtType.slice(1);
+    let newTitle = `${parsed.title} (${Label})`;
+    let filePath = filePathForTitle(newTitle);
+    if (existsSync(filePath)) {
+        let counter = 2;
+        while (existsSync(filePathForTitle(`${parsed.title} (${Label} ${counter})`)))
+            counter++;
+        newTitle = `${parsed.title} (${Label} ${counter})`;
+        filePath = filePathForTitle(newTitle);
+    }
+    // Fresh metadata: target type scaffold + variant relationship only. Source
+    // context objects are intentionally dropped (see header).
+    const metadata = {
+        title: newTitle,
+        docId: generateNodeId(),
+        ...(resolveTypeMeta(tgtType) || {}),
+        masterDocId: opts.masterDocId,
+        variantType: tgtType,
+    };
+    setActiveDocument(bodyDoc, newTitle, filePath, false, undefined, metadata);
+    const { markdown } = tiptapToMarkdownChecked(bodyDoc, newTitle, metadata);
+    ensureDataDir();
+    atomicWriteFileSync(filePath, markdown);
+    const newFilename = filePath.split(/[/\\]/).pop();
+    return { document: getDocument(), title: getTitle(), filename: newFilename };
+}
 export function getActiveFilename() {
     const filePath = getFilePath();
     // For external docs, return the full path as the identifier

package/dist/server/index.js CHANGED Viewed

@@ -14,7 +14,7 @@ import { zodToJsonSchema } from 'zod-to-json-schema';
 import { save, cancelDebouncedSave, load, getDocument, getTitle, getFilePath, getDocId, getMetadata, getStatus, updateDocument, setMetadata, applyTextEdits, isAgentLocked, getPendingDocInfo, getDocTagsByFilename, addDocTag, removeDocTag, markAllNodesAsPending, updatePendingCacheForActiveDoc, removePendingCacheEntry, clearAllCaches, stripPendingAttrs, stripPendingAttrsFromFile, setAutoAcceptOnFile, setSortRequestOnFile, clearSortRequestOnFile, bumpDocVersion, markAsAgentStub, extractText } from './state.js';
 import { syncPostHistory } from './post-sync.js';
 import { enrollManualPostForAutoplug } from './autoplug-enroll.js';
-import { listDocuments, switchDocument, createDocument, deleteDocument, duplicateDocument, reloadDocument, updateDocumentTitle, openFile, reorderDocs, searchDocuments, listArchivedDocuments, archiveDocument, unarchiveDocument, getActiveFilename, batchResolve, listPendingSorts } from './documents.js';
+import { listDocuments, switchDocument, createDocument, deleteDocument, duplicateDocument, createVariant, reloadDocument, updateDocumentTitle, openFile, reorderDocs, searchDocuments, listArchivedDocuments, archiveDocument, unarchiveDocument, getActiveFilename, batchResolve, listPendingSorts } from './documents.js';
 import { writePromptDebug, isPromptDebugEnabled } from './prompt-debug.js';
 import { createWorkspaceRouter } from './workspace-routes.js';
 import { createLinkRouter } from './link-routes.js';
@@ -638,6 +638,25 @@ export async function startHttpServer(options = {}) {
             res.status(400).json({ error: err.message });
         }
     });
+    // Create variant: a retyped derivative nested under the master. Field-projection
+    // (body always; title folds into body on downcast; target type scaffolded) —
+    // NOT a verbatim clone (that's /duplicate). adr: docs/variants.md
+    app.post('/api/documents/variant', (req, res) => {
+        try {
+            const { filename, masterDocId, variantType } = req.body;
+            if (!filename || !masterDocId || !variantType) {
+                res.status(400).json({ error: 'filename, masterDocId, and variantType are required' });
+                return;
+            }
+            const result = createVariant(filename, { masterDocId, variantType });
+            broadcastDocumentSwitched(result.document, result.title, result.filename);
+            broadcastDocumentsChanged();
+            res.json(result);
+        }
+        catch (err) {
+            res.status(400).json({ error: err.message });
+        }
+    });
     app.post('/api/documents/batch-resolve', (req, res) => {
         try {
             const { filenames, action } = req.body;

package/dist/server/mcp.js CHANGED Viewed

@@ -14,6 +14,7 @@ import { getDocument, getWordCount, getPendingChangeCount, getTitle, getStatus,
 import { tiptapToBlocks } from './node-blocks.js';
 import { outline, peek, searchInDoc, truncateRead } from './peek-outline.js';
 import { harvestSentenceHashes, harvestCharCount } from './enrichment.js';
+import { resolveTypeMeta } from './content-type-meta.js';
 import { listDocuments, switchDocument, createDocument, createDocumentFile, deleteDocument, openFile, getActiveFilename, promoteTempFile, archiveDocument, unarchiveDocument, resolveDocId, filenameByDocId, searchDocuments, listDirtyDocs, crawlDocs, enrichmentFooter, buildEnrichmentInstructions, listPendingSorts, sortFooter, buildSortInstructions, stagePendingTitle } from './documents.js';
 import { readFrontmatter, writeFrontmatter, computeBacklinksFor, invalidateBacklinksCache } from './backlinks.js';
 import { logger, generateRequestId, withRequestId } from './logger.js';
@@ -29,19 +30,6 @@ import { tiptapToMarkdown, splitFusedParagraphs } from './markdown.js';
 import { loadDocFromDisk } from './pending-overlay.js';
 import { getComments, getCommentCount, getGlobalCommentSummary, resolveComments } from './comments.js';
 import { readTasks, addTask, updateTask, removeTask } from './tasks.js';
-/** Map a content type string to its frontmatter metadata object. */
-function resolveTypeMeta(type, url) {
-    switch (type) {
-        case 'tweet': return { content_type: 'tweet', tweetContext: { mode: 'tweet' } };
-        case 'reply': return { content_type: 'reply', tweetContext: { mode: 'reply', ...(url ? { url } : {}) } };
-        case 'quote': return { content_type: 'quote', tweetContext: { mode: 'quote', ...(url ? { url } : {}) } };
-        case 'article': return { content_type: 'article', articleContext: { active: true } };
-        case 'linkedin': return { content_type: 'linkedin', linkedinContext: { active: true } };
-        case 'newsletter': return { content_type: 'newsletter', newsletterContext: { active: true } };
-        case 'blog': return { content_type: 'blog', blogContext: { active: true } };
-        default: return undefined;
-    }
-}
 /** Resolve a docId to a full document target. Fast path for active doc (zero I/O). */
 function resolveDocTarget(docId) {
     const filename = resolveDocId(docId);

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "openwriter",
-  "version": "0.29.0",
+  "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",