openwriter 0.25.0 → 0.27.0

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

@@ -0,0 +1,792 @@
+/**
+ * Blog publishing MCP tools — local git ops, no Worker, no PAT.
+ *
+ * Auth: piggybacks on the user's existing `gh auth login`.
+ * Persistence: blogSites in plugins['@openwriter/plugin-github'].blogSites.
+ */
+import { execFile } from 'child_process';
+import { existsSync, mkdirSync, readFileSync, copyFileSync, writeFileSync, readdirSync, statSync, rmSync } from 'fs';
+import { join, extname, dirname } from 'path';
+import { randomUUID } from 'crypto';
+import { homedir } from 'os';
+import { getServerModules, listBlogSites, writeBlogSites, } from './helpers.js';
+const NETWORK_TIMEOUT = 60000;
+function exec(cmd, args, cwd, timeout = NETWORK_TIMEOUT) {
+    const safeArgs = args.map(a => a.includes(' ') ? `"${a}"` : a);
+    return new Promise((resolve, reject) => {
+        execFile(cmd, safeArgs, { cwd, shell: true, timeout, maxBuffer: 16 * 1024 * 1024 }, (err, stdout, stderr) => {
+            if (err)
+                reject(new Error(stderr?.trim() || err.message));
+            else
+                resolve(stdout.trim());
+        });
+    });
+}
+async function ghAuthOk(cwd) {
+    try {
+        await exec('gh', ['auth', 'status'], cwd);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function slugify(s) {
+    return s.toLowerCase().replace(/['"]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 80);
+}
+function owRoot() {
+    return join(homedir(), '.openwriter');
+}
+// ---- inspect_blog_repo helpers ----
+function walkDir(root, max = 5000) {
+    const out = [];
+    const queue = [root];
+    while (queue.length && out.length < max) {
+        const dir = queue.shift();
+        let entries;
+        try {
+            entries = readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        for (const name of entries) {
+            if (name === '.git' || name === 'node_modules')
+                continue;
+            const full = join(dir, name);
+            let st;
+            try {
+                st = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (st.isDirectory())
+                queue.push(full);
+            else
+                out.push(full);
+        }
+    }
+    return out;
+}
+function dirOfMostMarkdown(files, cloneRoot) {
+    const counts = new Map();
+    for (const f of files) {
+        if (extname(f).toLowerCase() !== '.md' && extname(f).toLowerCase() !== '.mdx')
+            continue;
+        const rel = f.slice(cloneRoot.length + 1).replace(/\\/g, '/');
+        const dir = rel.includes('/') ? rel.slice(0, rel.lastIndexOf('/')) : '';
+        // Skip README.md at root, etc.
+        if (!dir)
+            continue;
+        counts.set(dir, (counts.get(dir) || 0) + 1);
+    }
+    let best = null;
+    for (const [dir, count] of counts) {
+        if (!best || count > best.count)
+            best = { dir, count };
+    }
+    return best;
+}
+/**
+ * Parse one frontmatter block into key→raw-string-value pairs.
+ * Top-level only — array-on-next-line and nested objects are returned as
+ * "<multiline>" sentinel so they're treated as varying.
+ */
+function parseYamlFrontmatter(raw) {
+    const m = raw.match(/^---\s*\n([\s\S]*?)\n---/);
+    if (!m)
+        return {};
+    const out = {};
+    const lines = m[1].split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const kv = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+        if (!kv)
+            continue;
+        const [, key, rest] = kv;
+        const trimmed = rest.trim();
+        if (trimmed === '' || trimmed === '|' || trimmed === '>') {
+            // Multi-line scalar / list-on-next-line — mark as variable
+            out[key] = '<multiline>';
+            continue;
+        }
+        out[key] = trimmed;
+    }
+    return out;
+}
+/**
+ * Detect frontmatter that was clearly written by an older version of the
+ * openwriter github plugin (and therefore leaks openwriter-internal fields).
+ * Those files would otherwise pollute the constant-detection across samples,
+ * so the inspector excludes them.
+ *
+ * Fingerprint markers (any one is sufficient):
+ *   - `enrichmentStale` field present (openwriter-only)
+ *   - `status: draft` + `slug` + `date:` with ISO-with-time (old plugin's emit)
+ *   - top-level `tags` set to a single openwriter content-type token
+ *     (e.g. `tags: [blog]`)
+ */
+function looksLikeOpenwriterLeak(fm) {
+    if ('enrichmentStale' in fm)
+        return true;
+    if (fm.status === 'draft' && 'slug' in fm && fm.date && /T\d{2}:\d{2}/.test(fm.date)) {
+        return true;
+    }
+    const t = fm.tags;
+    if (t && /^\[\s*["']?(blog|tweet|article|linkedin|newsletter)["']?\s*\]$/i.test(t.trim())) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Inspect multiple sample post frontmatters and propose:
+ *  - `frontmatter_defaults`: fields with the SAME value across all posts
+ *  - `frontmatter_field_map`: rename map from openwriter standard names
+ *    to whatever the site actually uses (e.g. `date` → `publishedDate`)
+ *  - `frontmatter_schema`: union of all keys seen
+ *
+ * Files that look like openwriter-leak frontmatter (the OLD plugin's
+ * output) are excluded from analysis so they don't poison the constants.
+ *
+ * The detection is conservative — only fields present in ≥2 samples with
+ * an identical value become defaults. Single-sample fields are skipped
+ * to avoid baking per-post variations in.
+ */
+function inferFrontmatterShape(rawSamples) {
+    // Filter out openwriter-leak files so they don't pollute defaults detection
+    const samples = rawSamples.filter((s) => !looksLikeOpenwriterLeak(s));
+    if (samples.length === 0)
+        return { defaults: {}, field_map: {}, schema: [] };
+    // Schema = union of all keys (preserve insertion order from first sample)
+    const schemaOrder = [];
+    const seen = new Set();
+    for (const s of samples) {
+        for (const k of Object.keys(s)) {
+            if (!seen.has(k)) {
+                seen.add(k);
+                schemaOrder.push(k);
+            }
+        }
+    }
+    // Defaults: key present in ALL samples with identical, non-empty,
+    // non-multiline value
+    const defaults = {};
+    for (const k of schemaOrder) {
+        const values = samples.map((s) => s[k]);
+        if (values.some((v) => v === undefined))
+            continue;
+        if (values.some((v) => v === '<multiline>'))
+            continue;
+        const first = values[0];
+        if (!first)
+            continue;
+        if (!values.every((v) => v === first))
+            continue;
+        // Skip per-post fields that are NEVER constants in practice
+        if (['title', 'description', 'slug', 'date', 'publishedDate', 'pubDate', 'coverImage', 'coverImageAlt', 'tags', 'category', 'categories'].includes(k))
+            continue;
+        // Unquote double-quoted strings
+        const unq = first.match(/^"(.*)"$/);
+        let parsed = unq ? unq[1] : first;
+        if (parsed === 'true')
+            parsed = true;
+        else if (parsed === 'false')
+            parsed = false;
+        else if (/^-?\d+$/.test(parsed))
+            parsed = Number(parsed);
+        defaults[k] = parsed;
+    }
+    // Field map: detect which date field the site uses
+    const field_map = {};
+    if (seen.has('publishedDate') && !seen.has('date')) {
+        field_map.date = 'publishedDate';
+    }
+    else if (seen.has('pubDate') && !seen.has('date')) {
+        field_map.date = 'pubDate';
+    }
+    return { defaults, field_map, schema: schemaOrder };
+}
+/**
+ * Detect the site's public URL from common static-host conventions:
+ *  - `CNAME` at repo root or `public/CNAME` (GitHub Pages / Cloudflare Pages / Netlify)
+ *  - `wrangler.toml` `routes` (Cloudflare Workers)
+ *  - `netlify.toml` `[[redirects]]` to= field with a full URL
+ *  - GitHub Pages default `<owner>.github.io/<repo>/` is NOT proposed — too often wrong
+ *    when a custom domain is in play; user can fill in if they want it.
+ */
+function inferSiteUrl(cloneRoot) {
+    const tryRead = (rel) => {
+        const p = join(cloneRoot, rel);
+        if (!existsSync(p))
+            return undefined;
+        try {
+            return readFileSync(p, 'utf-8').trim();
+        }
+        catch {
+            return undefined;
+        }
+    };
+    // CNAME files (single line with domain, no scheme)
+    for (const rel of ['CNAME', 'public/CNAME', 'static/CNAME', 'src/CNAME']) {
+        const v = tryRead(rel);
+        if (v) {
+            const host = v.split('\n')[0].trim().replace(/^https?:\/\//, '').replace(/\/+$/, '');
+            if (/^[a-z0-9.-]+\.[a-z]{2,}$/i.test(host))
+                return `https://${host}`;
+        }
+    }
+    // wrangler.toml — look for `routes = ["https://..."]` or `route = "..."`
+    const wrangler = tryRead('wrangler.toml');
+    if (wrangler) {
+        const m = wrangler.match(/route[s]?\s*=\s*\[?\s*["']https?:\/\/([^"'/*]+)/);
+        if (m)
+            return `https://${m[1].replace(/\/$/, '')}`;
+    }
+    return undefined;
+}
+function inferFramework(cloneRoot, files) {
+    const has = (rel) => existsSync(join(cloneRoot, rel));
+    if (has('astro.config.mjs') || has('astro.config.ts') || has('astro.config.js') ||
+        files.some(f => /astro\.config\.(mjs|ts|js)$/.test(f)))
+        return 'astro';
+    if (has('next.config.js') || has('next.config.mjs') || has('next.config.ts'))
+        return 'next';
+    if (has('_config.yml'))
+        return 'jekyll';
+    if (has('hugo.toml') || has('config.toml') || has('hugo.yaml') || has('config.yaml'))
+        return 'hugo';
+    return 'unknown';
+}
+function defaultDirsForFramework(fw, detectedContentDir) {
+    switch (fw) {
+        case 'astro':
+            return {
+                content_dir: detectedContentDir || 'src/content/blog',
+                image_dir: 'public/blog-images',
+                image_public_prefix: '/blog-images',
+            };
+        case 'next':
+            return {
+                content_dir: detectedContentDir || 'posts',
+                image_dir: 'public/blog-images',
+                image_public_prefix: '/blog-images',
+            };
+        case 'jekyll':
+            return {
+                content_dir: '_posts',
+                image_dir: 'assets/images',
+                image_public_prefix: '/assets/images',
+            };
+        case 'hugo':
+            return {
+                content_dir: detectedContentDir || 'content/posts',
+                image_dir: 'static/images',
+                image_public_prefix: '/images',
+            };
+        default:
+            return {
+                content_dir: detectedContentDir || 'posts',
+                image_dir: 'public/images',
+                image_public_prefix: '/images',
+            };
+    }
+}
+// ---- post_to_blog helpers ----
+/**
+ * Strict double-quoted YAML emission for scalars — matches the style of
+ * caloriebot's existing posts. Arrays are inline-square-bracket JSON for
+ * compactness. Booleans + numbers emit bare.
+ */
+function yamlValue(v) {
+    if (v == null)
+        return '""';
+    if (typeof v === 'boolean' || typeof v === 'number')
+        return String(v);
+    if (Array.isArray(v))
+        return '[' + v.map((x) => yamlValue(x)).join(', ') + ']';
+    if (typeof v === 'object')
+        return JSON.stringify(v);
+    return JSON.stringify(String(v));
+}
+/**
+ * Format a date for frontmatter. If the value already matches YYYY-MM-DD,
+ * pass through; if it's an ISO string with time, slice to date only;
+ * otherwise return as-is.
+ */
+function formatDate(v) {
+    if (typeof v !== 'string')
+        return String(v ?? '');
+    const m = v.match(/^(\d{4}-\d{2}-\d{2})/);
+    return m ? m[1] : v;
+}
+/**
+ * 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.
+ */
+function buildFrontmatter(title, blogCtx, site, coverImagePath) {
+    const fm = {};
+    const map = site.frontmatter_field_map || {};
+    // 1. Site defaults (lowest priority — overridable below)
+    if (site.frontmatter_defaults) {
+        for (const [k, v] of Object.entries(site.frontmatter_defaults)) {
+            fm[k] = v;
+        }
+    }
+    // 2. Title (always)
+    fm.title = title;
+    // 3. blogContext fields — apply field_map rename, skip empty values
+    const passthrough = [
+        { src: 'description' },
+        { src: 'date', format: formatDate },
+        { src: 'author' },
+        { src: 'tags' },
+        { src: 'category' },
+        { src: 'slug' },
+        { src: 'draft' },
+        { src: 'subtitle' },
+        { src: 'excerpt' },
+        { src: 'coverImageAlt' },
+    ];
+    for (const { src, format } of passthrough) {
+        const v = blogCtx[src];
+        if (v == null || v === '' || (Array.isArray(v) && v.length === 0))
+            continue;
+        const dest = map[src] || src;
+        fm[dest] = format ? format(v) : v;
+    }
+    // 4. Cover image: rewritten path takes priority over blogContext.coverImage
+    if (coverImagePath) {
+        const dest = map.coverImage || 'coverImage';
+        fm[dest] = coverImagePath;
+    }
+    // Ensure date field exists if site expects one — derive from today
+    const dateDest = map.date || 'date';
+    const publishedDateDest = map.publishedDate || (map.date === 'publishedDate' ? 'publishedDate' : null);
+    if (!fm[dateDest] && !(publishedDateDest && fm[publishedDateDest])) {
+        fm[dateDest] = new Date().toISOString().slice(0, 10);
+    }
+    // Emit in stable order: defaults first (in their declared order),
+    // then title, then any new keys we added
+    const lines = [];
+    const written = new Set();
+    if (site.frontmatter_defaults) {
+        for (const k of Object.keys(site.frontmatter_defaults)) {
+            if (k in fm) {
+                lines.push(`${k}: ${yamlValue(fm[k])}`);
+                written.add(k);
+            }
+        }
+    }
+    if (!written.has('title')) {
+        lines.push(`title: ${yamlValue(fm.title)}`);
+        written.add('title');
+    }
+    for (const [k, v] of Object.entries(fm)) {
+        if (written.has(k))
+            continue;
+        lines.push(`${k}: ${yamlValue(v)}`);
+        written.add(k);
+    }
+    return `---\n${lines.join('\n')}\n---\n\n`;
+}
+function stripFrontmatter(md) {
+    return md.replace(/^---\n[\s\S]*?\n---\n+/, '').replace(/^\s*<!--\s*-->\s*$/gm, '').trim();
+}
+// ---- Tools ----
+export function blogTools() {
+    return [
+        {
+            name: 'inspect_blog_repo',
+            description: 'Clone a GitHub blog repo (shallow) to a local cache and infer its framework, content directory, image directory, and frontmatter schema. Read-only — produces a config preview you can feed to add_blog_site.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    repo_url: { type: 'string', description: 'GitHub repo URL or owner/repo shorthand (e.g. "https://github.com/user/blog" or "user/blog")' },
+                },
+                required: ['repo_url'],
+            },
+            handler: async (params) => {
+                const repoUrl = String(params.repo_url || '').trim();
+                if (!repoUrl)
+                    return { error: 'repo_url is required' };
+                // Normalize to owner/repo
+                let ownerRepo = repoUrl
+                    .replace(/^https?:\/\/github\.com\//, '')
+                    .replace(/\.git$/, '')
+                    .replace(/^github:/, '');
+                const parts = ownerRepo.split('/').filter(Boolean);
+                if (parts.length < 2)
+                    return { error: 'Could not parse owner/repo from repo_url' };
+                const owner = parts[0];
+                const repo = parts[1];
+                const cacheRoot = join(owRoot(), '_blog-inspect-cache');
+                mkdirSync(cacheRoot, { recursive: true });
+                const cloneDir = join(cacheRoot, `${owner}-${repo}`);
+                if (!(await ghAuthOk(cacheRoot))) {
+                    return { error: 'gh CLI not authenticated. Run `gh auth login` first.' };
+                }
+                // Refresh: remove existing then clone shallow
+                if (existsSync(cloneDir)) {
+                    try {
+                        rmSync(cloneDir, { recursive: true, force: true });
+                    }
+                    catch { /* ignore */ }
+                }
+                try {
+                    await exec('gh', ['repo', 'clone', `${owner}/${repo}`, cloneDir, '--', '--depth', '1'], cacheRoot);
+                }
+                catch (err) {
+                    return { error: `Clone failed: ${err.message}` };
+                }
+                const files = walkDir(cloneDir);
+                const framework = inferFramework(cloneDir, files);
+                const mdBest = dirOfMostMarkdown(files, cloneDir);
+                const detected = mdBest?.dir || '';
+                const defaults = defaultDirsForFramework(framework, detected);
+                // Collect multiple sample post frontmatters so we can detect constants.
+                // Up to 10 samples to avoid pathological loops on huge repos.
+                const sampleFiles = files
+                    .filter((f) => {
+                    const rel = f.slice(cloneDir.length + 1).replace(/\\/g, '/');
+                    return (detected ? rel.startsWith(detected + '/') : true) && /\.(md|mdx)$/i.test(rel);
+                })
+                    .slice(0, 10);
+                const rawSamples = [];
+                for (const f of sampleFiles) {
+                    try {
+                        rawSamples.push(parseYamlFrontmatter(readFileSync(f, 'utf-8')));
+                    }
+                    catch { /* skip */ }
+                }
+                const samplesAfterFilter = rawSamples.filter((s) => !looksLikeOpenwriterLeak(s));
+                const samplesSkipped = rawSamples.length - samplesAfterFilter.length;
+                const shape = inferFrontmatterShape(rawSamples);
+                const confidence = framework !== 'unknown' && detected ? 'high'
+                    : detected ? 'medium'
+                        : 'low';
+                const siteUrl = inferSiteUrl(cloneDir);
+                return {
+                    owner,
+                    repo,
+                    framework,
+                    content_dir: defaults.content_dir,
+                    image_dir: defaults.image_dir,
+                    image_public_prefix: defaults.image_public_prefix,
+                    frontmatter_schema: shape.schema,
+                    frontmatter_defaults: shape.defaults,
+                    frontmatter_field_map: shape.field_map,
+                    // 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}/',
+                    samples_analyzed: samplesAfterFilter.length,
+                    samples_skipped_openwriter_leak: samplesSkipped,
+                    markdown_files_found: mdBest?.count ?? 0,
+                    confidence,
+                };
+            },
+        },
+        {
+            name: 'add_blog_site',
+            description: 'Register a GitHub blog repo as a publishing target. Use inspect_blog_repo first to discover sensible defaults — including the frontmatter_defaults and frontmatter_field_map it proposes, which match what the site\'s existing posts use.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    label: { type: 'string', description: 'User-facing name (e.g. "Personal blog")' },
+                    owner: { type: 'string', description: 'GitHub owner/user/org' },
+                    repo: { type: 'string', description: 'Repo name' },
+                    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")' },
+                    framework: { type: 'string', enum: ['astro', 'next', 'jekyll', 'hugo', 'unknown'], description: 'Site framework' },
+                    frontmatter_defaults: {
+                        type: 'object',
+                        description: 'Constants applied to every post\'s frontmatter (e.g. `{ "layout": "../../layouts/BlogPost.astro", "author": "...", "prerender": true }`). Detected by inspect_blog_repo as fields with constant values across existing posts.',
+                    },
+                    frontmatter_field_map: {
+                        type: 'object',
+                        description: 'Rename map: openwriter blogContext key → site frontmatter key (e.g. `{ "date": "publishedDate" }` for Astro-style sites that use `publishedDate`).',
+                    },
+                    frontmatter_schema: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'List of frontmatter keys the site uses (from inspection). Stored for reference / future UI.',
+                    },
+                    site_url: {
+                        type: 'string',
+                        description: 'Public base URL of the site (e.g. "https://example.com"). Used to construct the live URL surfaced after publish. inspect_blog_repo proposes this from CNAME / wrangler.toml when found.',
+                    },
+                    blog_url_pattern: {
+                        type: 'string',
+                        description: 'URL path pattern for a blog post with `{slug}` placeholder (e.g. "/blog/{slug}/"). Default: "/blog/{slug}/". Combined with site_url to build the live URL stored on the doc after publish.',
+                    },
+                },
+                required: ['label', 'owner', 'repo', 'content_dir', 'image_dir', 'image_public_prefix', 'framework'],
+            },
+            handler: async (params) => {
+                const site = {
+                    id: randomUUID(),
+                    label: String(params.label),
+                    owner: String(params.owner),
+                    repo: String(params.repo),
+                    branch: String(params.branch || 'main'),
+                    content_dir: String(params.content_dir),
+                    image_dir: String(params.image_dir),
+                    image_public_prefix: String(params.image_public_prefix),
+                    framework: params.framework || 'unknown',
+                };
+                if (params.frontmatter_defaults && typeof params.frontmatter_defaults === 'object') {
+                    site.frontmatter_defaults = params.frontmatter_defaults;
+                }
+                if (params.frontmatter_field_map && typeof params.frontmatter_field_map === 'object') {
+                    site.frontmatter_field_map = params.frontmatter_field_map;
+                }
+                if (Array.isArray(params.frontmatter_schema)) {
+                    site.frontmatter_schema = params.frontmatter_schema.map(String);
+                }
+                if (typeof params.site_url === 'string' && params.site_url.trim()) {
+                    site.site_url = params.site_url.trim().replace(/\/+$/, '');
+                }
+                if (typeof params.blog_url_pattern === 'string' && params.blog_url_pattern.trim()) {
+                    site.blog_url_pattern = params.blog_url_pattern.trim();
+                }
+                const sites = await listBlogSites();
+                sites.push(site);
+                await writeBlogSites(sites);
+                return { success: true, site };
+            },
+        },
+        {
+            name: 'list_blog_sites',
+            description: 'List all registered GitHub blog sites.',
+            inputSchema: { type: 'object', properties: {} },
+            handler: async () => {
+                const sites = await listBlogSites();
+                return { sites };
+            },
+        },
+        {
+            name: 'remove_blog_site',
+            description: 'Remove a registered blog site by id.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    id: { type: 'string', description: 'Blog site id (from list_blog_sites)' },
+                },
+                required: ['id'],
+            },
+            handler: async (params) => {
+                const id = String(params.id);
+                const sites = await listBlogSites();
+                const next = sites.filter(s => s.id !== id);
+                if (next.length === sites.length)
+                    return { error: `No blog site with id ${id}` };
+                await writeBlogSites(next);
+                return { success: true, removed: id };
+            },
+        },
+        {
+            name: 'post_to_blog',
+            description: 'Publish the active OpenWriter document to a registered GitHub blog site via local git ops (clone-or-pull, write file + images, commit, push). Auth uses your existing `gh auth login`.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    site_id: { type: 'string', description: 'Blog site id (from list_blog_sites)' },
+                    slug: { type: 'string', description: 'Filename slug (without .md). Default: slugified document title.' },
+                    commit_message: { type: 'string', description: 'Git commit message. Default: "blog: {title}".' },
+                },
+                required: ['site_id'],
+            },
+            handler: async (params) => {
+                const siteId = String(params.site_id);
+                const sites = await listBlogSites();
+                const site = sites.find(s => s.id === siteId);
+                if (!site)
+                    return { error: `No blog site with id ${siteId}` };
+                const srv = await getServerModules();
+                // Flush any pending writes so we read fresh state
+                try {
+                    srv.cancelDebouncedSave();
+                    srv.save();
+                }
+                catch { /* ignore */ }
+                const doc = srv.getDocument();
+                const title = srv.getTitle();
+                const metadata = srv.getMetadata() || {};
+                if (!doc || !doc.content)
+                    return { error: 'No active document. Switch to a document first.' };
+                if (!title)
+                    return { error: 'Document has no title. Set a title before publishing.' };
+                const contentType = metadata.content_type ||
+                    (metadata.tweetContext ? 'tweet'
+                        : metadata.articleContext ? 'article'
+                            : metadata.linkedinContext ? 'linkedin'
+                                : metadata.newsletterContext ? 'newsletter'
+                                    : metadata.blogContext ? 'blog'
+                                        : undefined);
+                if (contentType !== 'blog') {
+                    return {
+                        error: `Active document is content_type "${contentType || 'untyped'}", not "blog". post_to_blog only publishes blog docs. Create a blog doc (sidebar → "+ New" → Blog) and switch to it before posting.`,
+                    };
+                }
+                const blogCtx = metadata.blogContext || {};
+                const cloneRoot = join(owRoot(), '_blog-clones');
+                mkdirSync(cloneRoot, { recursive: true });
+                const clonePath = join(cloneRoot, site.id);
+                if (!(await ghAuthOk(cloneRoot))) {
+                    return { error: 'gh CLI not authenticated. Run `gh auth login` first.' };
+                }
+                // Clone or refresh
+                if (!existsSync(join(clonePath, '.git'))) {
+                    if (existsSync(clonePath)) {
+                        try {
+                            rmSync(clonePath, { recursive: true, force: true });
+                        }
+                        catch { /* ignore */ }
+                    }
+                    try {
+                        await exec('gh', ['repo', 'clone', `${site.owner}/${site.repo}`, clonePath], cloneRoot);
+                    }
+                    catch (err) {
+                        return { error: `Clone failed: ${err.message}` };
+                    }
+                    try {
+                        await exec('git', ['checkout', site.branch], clonePath);
+                    }
+                    catch { /* may already be on it */ }
+                }
+                else {
+                    try {
+                        await exec('git', ['fetch', 'origin', site.branch], clonePath);
+                        await exec('git', ['checkout', site.branch], clonePath);
+                        await exec('git', ['reset', '--hard', `origin/${site.branch}`], clonePath);
+                    }
+                    catch (err) {
+                        return { error: `Failed to refresh clone: ${err.message}` };
+                    }
+                }
+                // Build markdown body
+                const rawMd = srv.tiptapToMarkdown(doc, title, metadata);
+                const bodyMd = stripFrontmatter(rawMd);
+                // Slug priority: explicit param > blogContext.slug > slugified title
+                const slug = String(params.slug || blogCtx.slug || slugify(title));
+                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(/\/+$/, '');
+                const imageRefs = new Set();
+                const bodyRewritten = bodyMd.replace(/\/_images\/([^\s)"'<>]+)/g, (_m, fn) => {
+                    imageRefs.add(fn);
+                    return `${imgPrefix}/${fn}`;
+                });
+                // Handle cover image from blogContext
+                let coverImagePath;
+                if (typeof blogCtx.coverImage === 'string' && blogCtx.coverImage) {
+                    const coverFile = blogCtx.coverImage.replace(/^\/_images\//, '');
+                    imageRefs.add(coverFile);
+                    coverImagePath = `${imgPrefix}/${coverFile}`;
+                }
+                // Copy images
+                const dataDir = srv.getDataDir();
+                const imageDirAbs = join(clonePath, site.image_dir);
+                mkdirSync(imageDirAbs, { recursive: true });
+                let imagesCopied = 0;
+                for (const fn of imageRefs) {
+                    const src = join(dataDir, '_images', fn);
+                    if (!existsSync(src))
+                        continue;
+                    const dst = join(imageDirAbs, fn);
+                    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`);
+                const postAbs = join(clonePath, postRel);
+                mkdirSync(dirname(postAbs), { recursive: true });
+                writeFileSync(postAbs, frontmatter + bodyRewritten + '\n', 'utf-8');
+                // Commit + push (no-op is fine — still counts as a publish for the writeback)
+                const commitMessage = String(params.commit_message || `blog: ${title}`);
+                let noChanges = false;
+                try {
+                    await exec('git', ['add', '-A'], clonePath);
+                    const status = await exec('git', ['status', '--porcelain'], clonePath);
+                    if (!status) {
+                        noChanges = true;
+                    }
+                    else {
+                        await exec('git', ['commit', '-m', commitMessage], clonePath);
+                        await exec('git', ['push', 'origin', site.branch], clonePath);
+                    }
+                }
+                catch (err) {
+                    return { error: `Git op failed: ${err.message}` };
+                }
+                let shortHash = '';
+                try {
+                    shortHash = await exec('git', ['rev-parse', '--short', 'HEAD'], clonePath);
+                }
+                catch { /* ignore */ }
+                // Construct the live URL when the site has site_url configured.
+                // Pattern defaults to /blog/{slug}/ — matches the convention proposed by inspect_blog_repo.
+                let liveUrl;
+                if (site.site_url) {
+                    const pattern = site.blog_url_pattern || '/blog/{slug}/';
+                    const path = pattern.replace('{slug}', slug);
+                    liveUrl = site.site_url.replace(/\/+$/, '') + (path.startsWith('/') ? path : '/' + path);
+                }
+                // Mark the doc as sent so the file-tree right-click menu surfaces
+                // "View Post" with a live link. This mirrors the tweetContext.lastPost /
+                // articleContext.lastPost / newsletterContext.lastSend pattern. Runs
+                // even on no-op publishes — the doc is still "on the site as of now".
+                // adr: adr/plugin-slot-nested-data.md (writes through setMetadata which deep-merges blogContext)
+                let writebackWarning;
+                try {
+                    srv.setMetadata({
+                        blogContext: {
+                            lastPublish: {
+                                publishedAt: new Date().toISOString(),
+                                ...(liveUrl ? { publishedUrl: liveUrl } : {}),
+                                ...(shortHash ? { commit: shortHash } : {}),
+                                file: postRel.replace(/\\/g, '/'),
+                            },
+                        },
+                    });
+                    // setMetadata doesn't bump docVersion on its own — without an explicit
+                    // bump, save()→writeToDisk hits the no-op gate (docVersion === lastSavedDocVersion
+                    // when there's no body change) and the lastPublish writeback never lands on disk.
+                    // Same convention mcp.ts:1112 uses for active-doc metadata writes.
+                    srv.bumpDocVersion();
+                    srv.save();
+                }
+                catch (err) {
+                    writebackWarning = `Published successfully, but failed to mark doc as sent: ${err.message}`;
+                }
+                return {
+                    success: true,
+                    file: postRel.replace(/\\/g, '/'),
+                    commit: shortHash,
+                    images_committed: noChanges ? 0 : imagesCopied,
+                    live_url: liveUrl,
+                    message: noChanges
+                        ? 'No changes — file already up to date. Doc marked as sent.'
+                        : `Pushed to ${site.owner}/${site.repo}@${site.branch}`,
+                    ...(writebackWarning ? { warning: writebackWarning } : {}),
+                };
+            },
+        },
+    ];
+}