openwriter 0.33.1 → 0.34.0

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

@@ -1038,6 +1038,59 @@ export function blogTools() {
                 const postAbs = join(clonePath, postRel);
                 mkdirSync(dirname(postAbs), { recursive: true });
                 writeFileSync(postAbs, frontmatter + bodyRewritten + '\n', 'utf-8');
+                // ── PRE-COMMIT SCHEMA GATE ──────────────────────────────────────────
+                // Validate the built frontmatter against the TARGET SITE's own content
+                // schema BEFORE anything is committed. A value outside the site's
+                // z.enum (e.g. category "Updates" when the schema allows only
+                // 'Product Updates' | 'Guides' | …) otherwise sails straight to a red
+                // Astro build + a silent 404 — the exact failure that motivated this
+                // gate (live incident 2026-06-09). The schema is read from the cloned
+                // repo's LIVE config every publish, never a mirrored snapshot, so it
+                // can't drift from the site. adr: adr/blog-publish-schema-gate.md
+                const gate = await srv.validateBlogFrontmatter({
+                    repoRoot: clonePath,
+                    contentDir: site.content_dir,
+                    frontmatter,
+                });
+                if (!gate.ok) {
+                    // ABORT before commit/push. Nothing was committed; this working-tree
+                    // edit stays local and is wiped by the next publish's reset --hard.
+                    const friendly = gate.summary
+                        || (gate.issues || []).map((i) => i.message).join('; ')
+                        || 'frontmatter does not match the site schema';
+                    // Human surface: a toast fires for whoever clicked Publish, over the
+                    // existing WS path, routed to the canonical showToast() primitive.
+                    try {
+                        srv.broadcastToast(`Blog publish blocked: ${friendly}`, 'error');
+                    }
+                    catch { /* best-effort */ }
+                    // MCP surface: structured error so the calling agent sees exactly
+                    // what to fix and can republish.
+                    return {
+                        error: `Publish blocked — ${friendly}`,
+                        validation_failed: true,
+                        issues: gate.issues || [],
+                        ...(gate.configPath ? { schema_config: gate.configPath } : {}),
+                        ...(gate.collection ? { collection: gate.collection } : {}),
+                        hint: "Fix the frontmatter to match the site's content schema, then republish. Nothing was committed or pushed.",
+                    };
+                }
+                // Validation could not run faithfully (non-Astro repo, unparseable
+                // config, or a schemaless collection). NEVER a silent skip — surface
+                // it. For an Astro site this is a real gap (loud error); for other
+                // frameworks there's simply no Astro schema to check (quiet info). The
+                // reason always rides back on the MCP response either way.
+                let validationWarning;
+                if (gate.skipped) {
+                    validationWarning = `Published WITHOUT schema validation — ${gate.reason}.`;
+                    const astroExpected = site.framework === 'astro';
+                    try {
+                        srv.broadcastToast(astroExpected
+                            ? `Blog published without schema check — ${gate.reason}`
+                            : `Blog published (no Astro schema to check on this ${site.framework} site)`, astroExpected ? 'error' : 'info');
+                    }
+                    catch { /* best-effort */ }
+                }
                 // 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;
@@ -1113,9 +1166,15 @@ export function blogTools() {
                     // filename it shipped as, so the agent/user sees what landed.
                     ...(coverImagePath ? { image: coverImagePath, cover_file: coverDestFile } : {}),
                     live_url: liveUrl,
+                    // Transparency on the happy path: the schema gate ran and passed (or
+                    // was loudly skipped). adr: adr/blog-publish-schema-gate.md
+                    validated: !gate.skipped,
+                    ...(gate.configPath ? { schema_config: gate.configPath } : {}),
+                    ...(gate.collection ? { schema_collection: gate.collection } : {}),
                     message: noChanges
                         ? 'No changes — file already up to date. Doc marked as sent.'
                         : `Pushed to ${site.owner}/${site.repo}@${site.branch}`,
+                    ...(validationWarning ? { validation_warning: validationWarning } : {}),
                     ...(writebackWarning ? { warning: writebackWarning } : {}),
                 };
             },

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

@@ -17,7 +17,27 @@ export interface ServerModules {
     broadcastSyncStatus: (status: any) => void;
     broadcastMetadataChanged: (metadata: Record<string, any>) => void;
     broadcastDocumentsChanged: () => void;
+    broadcastToast: (message: string, kind?: 'info' | 'error', durationMs?: number) => void;
     tiptapToMarkdown: (doc: any, title: string, metadata?: Record<string, any>) => string;
+    validateBlogFrontmatter: (opts: {
+        repoRoot: string;
+        contentDir: string;
+        frontmatter: string;
+    }) => Promise<BlogFrontmatterValidation>;
+}
+/** Result of the pre-commit schema gate. Mirrors server/blog-schema-gate.ts. */
+export interface BlogFrontmatterValidation {
+    ok: boolean;
+    skipped?: boolean;
+    reason?: string;
+    configPath?: string;
+    collection?: string;
+    issues?: Array<{
+        field: string;
+        code: string;
+        message: string;
+    }>;
+    summary?: string;
 }
 export declare function getServerModules(): Promise<ServerModules>;
 export interface PluginConfigField {

package/dist/plugins/github/dist/helpers.js

@@ -8,23 +8,24 @@ const npmBase = new URL('../../../server/', import.meta.url).href;
 const monoBase = new URL('../../../packages/openwriter/dist/server/', import.meta.url).href;
 let _cached = null;
 async function tryImport(base) {
-    const [helpers, state, ws, markdown] = await Promise.all([
+    const [helpers, state, ws, markdown, schemaGate] = await Promise.all([
         import(base + 'helpers.js'),
         import(base + 'state.js'),
         import(base + 'ws.js'),
         import(base + 'markdown.js'),
+        import(base + 'blog-schema-gate.js'),
     ]);
-    return { helpers, state, ws, markdown };
+    return { helpers, state, ws, markdown, schemaGate };
 }
 export async function getServerModules() {
     if (_cached)
         return _cached;
-    let helpers, state, ws, markdown;
+    let helpers, state, ws, markdown, schemaGate;
     try {
-        ({ helpers, state, ws, markdown } = await tryImport(npmBase));
+        ({ helpers, state, ws, markdown, schemaGate } = await tryImport(npmBase));
     }
     catch {
-        ({ helpers, state, ws, markdown } = await tryImport(monoBase));
+        ({ helpers, state, ws, markdown, schemaGate } = await tryImport(monoBase));
     }
     _cached = {
         getDataDir: helpers.getDataDir,
@@ -41,7 +42,9 @@ export async function getServerModules() {
         broadcastSyncStatus: ws.broadcastSyncStatus,
         broadcastMetadataChanged: ws.broadcastMetadataChanged,
         broadcastDocumentsChanged: ws.broadcastDocumentsChanged,
+        broadcastToast: ws.broadcastToast,
         tiptapToMarkdown: markdown.tiptapToMarkdown,
+        validateBlogFrontmatter: schemaGate.validateBlogFrontmatter,
     };
     return _cached;
 }

package/dist/server/blog-schema-gate.js

@@ -0,0 +1,318 @@
+/**
+ * Blog publish schema gate — validate a post's frontmatter against the TARGET
+ * SITE's live Astro content schema BEFORE the github plugin commits/pushes.
+ *
+ * Why this exists
+ * ───────────────
+ * `post_to_blog` builds frontmatter from a doc's metadata + the site's
+ * `frontmatter_defaults`, then commits and pushes. Nothing checked that the
+ * result satisfies the site's `src/content/config.ts` Zod schema. A bad value
+ * (e.g. `category: "Updates"` when the schema is
+ * `z.enum(['Product Updates','Guides','Discord Tips','Tutorials'])`) sailed
+ * straight to a red Astro build — Netlify never shipped the page, and the only
+ * signal was a manually-discovered 404. (Live incident, 2026-06-09.)
+ *
+ * Single source of truth
+ * ──────────────────────
+ * The schema is read from the cloned repo's OWN config every publish — never a
+ * snapshot mirrored in OpenWriter's blog-site registry. A mirror drifts the
+ * moment the site changes its schema; the repo's `config.ts` cannot.
+ * adr: adr/blog-publish-schema-gate.md
+ *
+ * How it loads an Astro config outside Astro
+ * ──────────────────────────────────────────
+ * `src/content/config.ts` does `import { z, defineCollection } from 'astro:content'`,
+ * which only resolves inside the Astro runtime. We:
+ *   1. transpile the TS to ESM JS (esbuild when present — it ships with Vite),
+ *   2. strip the `astro:content` / `astro/loaders` imports and prepend a tiny
+ *      shim header: `z` → the real `zod` (by absolute file URL so it resolves
+ *      from any temp location), `defineCollection` → identity (preserves
+ *      `.schema`), `reference`/`glob`/`file` → harmless stubs,
+ *   3. write the result to a temp `.mjs` and dynamic-import it,
+ *   4. read `collections[<dir>]`, resolve its `.schema` (calling the
+ *      `({ image }) => z.object(...)` function form with an `image()` stub),
+ *   5. `schema.safeParse(grayMatterData)` — gray-matter yields the SAME typed
+ *      object Astro feeds its schema (unquoted dates → real `Date`), so
+ *      `z.date()` / `z.coerce.date()` behave identically here and at build time.
+ *
+ * Anything that prevents a faithful parse (no config, exotic imports, transpile
+ * failure, no matching collection, no schema) is reported as `skipped` with a
+ * reason — NEVER a silent pass. The caller surfaces that loudly.
+ */
+import { existsSync, readFileSync, writeFileSync, mkdtempSync, rmSync } from 'fs';
+import { join, basename } from 'path';
+import { tmpdir } from 'os';
+import { pathToFileURL } from 'url';
+import { createRequire } from 'module';
+import matter from 'gray-matter';
+import { z } from 'zod';
+const require = createRequire(import.meta.url);
+// Config filenames Astro recognizes (v2–v4 `src/content/config.*`, v5
+// `src/content.config.*`), TS + already-ESM variants.
+const CONFIG_CANDIDATES = [
+    'src/content/config.ts',
+    'src/content/config.mts',
+    'src/content/config.js',
+    'src/content/config.mjs',
+    'src/content.config.ts',
+    'src/content.config.mts',
+    'src/content.config.js',
+    'src/content.config.mjs',
+];
+function findContentConfig(repoRoot) {
+    for (const rel of CONFIG_CANDIDATES) {
+        const abs = join(repoRoot, rel);
+        if (existsSync(abs))
+            return abs;
+    }
+    return null;
+}
+/** `a`/`an` for a type word, so "must be a boolean" / "must be an array" read right. */
+function article(word) {
+    return /^[aeiou]/i.test(word) ? 'an' : 'a';
+}
+/**
+ * Map one Zod issue to a plain-language sentence. NEITHER the MCP error nor the
+ * browser toast ever shows raw Zod text — this is the only place that touches
+ * the issue shape. Covers the codes a content schema actually produces; the
+ * default keeps everything else human ("<field> is invalid").
+ */
+export function friendlyZodIssue(issue) {
+    const field = Array.isArray(issue?.path) && issue.path.length ? issue.path.join('.') : 'frontmatter';
+    const code = String(issue?.code || 'invalid');
+    let message;
+    switch (code) {
+        case 'invalid_enum_value': {
+            const opts = Array.isArray(issue.options) ? issue.options.join(', ') : '';
+            message = `${field} "${issue.received}" isn't allowed — pick one of: ${opts}`;
+            break;
+        }
+        case 'invalid_type': {
+            // Zod reports a missing required field as invalid_type with received "undefined".
+            if (issue.received === 'undefined' || issue.received === 'null') {
+                message = `${field} is missing`;
+            }
+            else if (issue.expected === 'date') {
+                message = `${field} must be a date`;
+            }
+            else {
+                message = `${field} must be ${article(String(issue.expected))} ${issue.expected}`;
+            }
+            break;
+        }
+        case 'invalid_string': {
+            if (issue.validation === 'url')
+                message = `${field} must be a valid URL`;
+            else if (issue.validation === 'email')
+                message = `${field} must be a valid email`;
+            else if (issue.validation === 'datetime')
+                message = `${field} must be a valid date-time`;
+            else if (issue.validation === 'uuid')
+                message = `${field} must be a valid UUID`;
+            else
+                message = `${field} has an invalid format`;
+            break;
+        }
+        case 'invalid_date':
+            message = `${field} must be a valid date`;
+            break;
+        case 'too_small': {
+            const t = issue.type;
+            const n = issue.minimum;
+            if (t === 'string')
+                message = `${field} is too short (minimum ${n} characters)`;
+            else if (t === 'array')
+                message = `${field} needs at least ${n} item${n === 1 ? '' : 's'}`;
+            else if (t === 'number')
+                message = `${field} must be at least ${n}`;
+            else
+                message = `${field} is too small`;
+            break;
+        }
+        case 'too_big': {
+            const t = issue.type;
+            const n = issue.maximum;
+            if (t === 'string')
+                message = `${field} is too long (maximum ${n} characters)`;
+            else if (t === 'array')
+                message = `${field} allows at most ${n} item${n === 1 ? '' : 's'}`;
+            else if (t === 'number')
+                message = `${field} must be at most ${n}`;
+            else
+                message = `${field} is too big`;
+            break;
+        }
+        case 'unrecognized_keys': {
+            const keys = Array.isArray(issue.keys) ? issue.keys.join(', ') : '';
+            message = `unexpected field${issue.keys?.length === 1 ? '' : 's'}: ${keys}`;
+            break;
+        }
+        default:
+            message = `${field} is invalid`;
+            break;
+    }
+    return { field, code, message };
+}
+/** esbuild ships with Vite (dev/build installs). Production npm installs may
+ *  lack it — in that case we fall back to importing the source verbatim, which
+ *  works for already-ESM configs and TS configs free of type-only syntax; a
+ *  failure there surfaces as a `skipped` reason, never a silent pass.
+ *  The specifier is held in a variable so tsc/bundlers don't hard-require it. */
+async function loadEsbuild() {
+    try {
+        const spec = 'esbuild';
+        return await import(spec);
+    }
+    catch {
+        return null;
+    }
+}
+async function toEsmJs(src, isTypeScript) {
+    if (!isTypeScript)
+        return src;
+    const esbuild = await loadEsbuild();
+    if (esbuild?.transform) {
+        const out = await esbuild.transform(src, { loader: 'ts', format: 'esm' });
+        return out.code;
+    }
+    // Best-effort: a config with no TS-only syntax is valid JS once imports are
+    // rewritten. If it isn't, the dynamic import throws and we report `skipped`.
+    return src;
+}
+/**
+ * Build the self-contained ESM module text: shim header (real zod by absolute
+ * URL + identity/stub helpers) followed by the config with its astro imports
+ * stripped. `[^;]*?` spans newlines so multi-line import statements are removed
+ * too, stopping at the statement's terminating `;`.
+ */
+function buildModuleSource(esmJs) {
+    const zodUrl = pathToFileURL(require.resolve('zod')).href;
+    const stripped = esmJs
+        .replace(/import\s+[^;]*?from\s*["']astro:content["']\s*;?/g, '')
+        .replace(/import\s+[^;]*?from\s*["']astro\/loaders["']\s*;?/g, '');
+    const header = [
+        `import * as __ow_zod from ${JSON.stringify(zodUrl)};`,
+        `const z = __ow_zod.z ?? __ow_zod.default?.z ?? __ow_zod.default;`,
+        `const defineCollection = (c) => c;`,
+        `const reference = () => z.string();`,
+        `const glob = () => ({});`,
+        `const file = () => ({});`,
+        ``,
+    ].join('\n');
+    return header + stripped;
+}
+/**
+ * Load the site's content collections and return the Zod schema for the
+ * collection that backs `contentDir`. Throws on any failure (caller converts
+ * to a `skipped` result). Returns `{ schema: null }` when the collection has
+ * no schema declared (Astro doesn't validate those — nothing to gate on).
+ */
+async function loadCollectionSchema(configPath, contentDir) {
+    const isTs = /\.m?ts$/.test(configPath);
+    const src = readFileSync(configPath, 'utf-8');
+    const esmJs = await toEsmJs(src, isTs);
+    const modSrc = buildModuleSource(esmJs);
+    const dir = mkdtempSync(join(tmpdir(), 'ow-blog-gate-'));
+    const modPath = join(dir, 'content-config.mjs');
+    try {
+        writeFileSync(modPath, modSrc, 'utf-8');
+        const mod = await import(pathToFileURL(modPath).href);
+        const collections = mod?.collections;
+        if (!collections || typeof collections !== 'object') {
+            throw new Error('config has no `collections` export');
+        }
+        // Resolve the collection by the content dir's last segment
+        // (src/content/blog → "blog"); fall back to the sole collection.
+        const key = basename(contentDir.replace(/\\/g, '/').replace(/\/+$/, ''));
+        let collection = null;
+        let col = undefined;
+        if (key && collections[key]) {
+            collection = key;
+            col = collections[key];
+        }
+        else {
+            const keys = Object.keys(collections);
+            if (keys.length === 1) {
+                collection = keys[0];
+                col = collections[keys[0]];
+            }
+        }
+        if (!col) {
+            throw new Error(`no "${key}" collection in config (have: ${Object.keys(collections).join(', ') || 'none'})`);
+        }
+        let schema = col.schema;
+        // Astro's function form: schema: ({ image }) => z.object({...}). Call it
+        // with an image() stub that returns a string schema — a cover path is a
+        // string at the frontmatter level, which is all we validate.
+        if (typeof schema === 'function') {
+            schema = schema({ image: () => z.string() });
+        }
+        if (!schema || typeof schema.safeParse !== 'function') {
+            return { schema: null, collection };
+        }
+        return { schema, collection };
+    }
+    finally {
+        try {
+            rmSync(dir, { recursive: true, force: true });
+        }
+        catch { /* best-effort */ }
+    }
+}
+/**
+ * Validate a post's built frontmatter against the target site's live content
+ * schema. `frontmatter` is the YAML block the plugin is about to write (with or
+ * without `---` fences, with or without the body appended — gray-matter handles
+ * all three). `repoRoot` is the cloned site repo; `contentDir` is the site's
+ * post directory (e.g. `src/content/blog`).
+ *
+ * Returns `ok:true` on a clean parse, `ok:false` + friendly `issues` on a
+ * schema violation, or `ok:true, skipped:true` + a `reason` when validation
+ * could not run faithfully (no config / unparseable / no schema). It NEVER
+ * throws — every failure mode resolves to a result the caller can act on.
+ */
+export async function validateBlogFrontmatter(opts) {
+    let data;
+    try {
+        // gray-matter parses the same way Astro's content layer does (js-yaml
+        // default schema → unquoted ISO dates become real Date objects).
+        const parsed = matter(opts.frontmatter.startsWith('---') ? opts.frontmatter : `---\n${opts.frontmatter}\n---\n`);
+        data = parsed.data || {};
+    }
+    catch (err) {
+        return { ok: true, skipped: true, reason: `could not parse built frontmatter: ${err?.message || err}` };
+    }
+    const configPath = findContentConfig(opts.repoRoot);
+    if (!configPath) {
+        return { ok: true, skipped: true, reason: 'no Astro content config found (src/content/config.* or src/content.config.*)' };
+    }
+    const configRel = configPath.slice(opts.repoRoot.length + 1).replace(/\\/g, '/');
+    let loaded;
+    try {
+        loaded = await loadCollectionSchema(configPath, opts.contentDir);
+    }
+    catch (err) {
+        return { ok: true, skipped: true, reason: `could not load ${configRel}: ${err?.message || err}`, configPath: configRel };
+    }
+    if (!loaded.schema) {
+        return {
+            ok: true,
+            skipped: true,
+            reason: `${loaded.collection ? `collection "${loaded.collection}"` : 'matched collection'} has no schema to validate against`,
+            configPath: configRel,
+            collection: loaded.collection || undefined,
+        };
+    }
+    const result = loaded.schema.safeParse(data);
+    if (result.success) {
+        return { ok: true, configPath: configRel, collection: loaded.collection || undefined };
+    }
+    const issues = (result.error?.issues || []).map(friendlyZodIssue);
+    return {
+        ok: false,
+        configPath: configRel,
+        collection: loaded.collection || undefined,
+        issues,
+        summary: issues.map((i) => i.message).join('; '),
+    };
+}

package/dist/server/ws.js

@@ -564,6 +564,21 @@ export function broadcastWorkspacesChanged() {
             ws.send(msg);
     }
 }
+/**
+ * Fire a transient toast in every connected browser. Server-originated feedback
+ * for actions the human triggers indirectly (e.g. an MCP-side publish that the
+ * UI kicked off) — the client routes this straight to the canonical showToast()
+ * primitive, so it looks identical to any in-app toast. Used by post_to_blog to
+ * surface a schema-gate rejection to whoever clicked Publish, regardless of
+ * which surface (modal, compose view, or a bare agent call) started it.
+ */
+export function broadcastToast(message, kind = 'info', durationMs) {
+    const msg = JSON.stringify({ type: 'toast', message, kind, ...(durationMs ? { durationMs } : {}) });
+    for (const ws of clients) {
+        if (ws.readyState === WebSocket.OPEN)
+            ws.send(msg);
+    }
+}
 export function broadcastTitleChanged(title) {
     const msg = JSON.stringify({ type: 'title-changed', title });
     for (const ws of clients) {

package/package.json

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