hazo_blog 0.3.3 → 0.4.0

package/CHANGE_LOG.md

@@ -3,6 +3,44 @@
 All notable changes are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 0.4.0 — 2026-07-14
+
+**`validatePost()` — pre-publish content-quality gate (new, `hazo_blog/lib`)**
+
+Encodes the SEO lessons a stale Bing report surfaced late on a consumer site, so they're caught
+before a post goes live rather than months after. `validatePost(input, opts?)` returns
+`{ ok, errors, warnings, issues, wordCount }`:
+
+- **Blocking errors:** thin content (`< minWords`, default 300), missing meta description, and a
+  second page heading in the body — an `# ` markdown H1 or a `<h1>` (the post title is already the
+  page H1). Code samples in fenced blocks are ignored so a `#` comment doesn't false-positive.
+- **Advisory warnings:** meta-description length outside 150–160, composed SEO title over
+  `titleLengthLimit` (default 60, *including* the `titleSuffix` — same suffix-aware fix shipped in
+  hazo_seo 0.5.0), missing excerpt, missing FAQ, and no subheadings.
+
+Consumers wire this into their create/update/publish path (e.g. gotimer's `PATCH /api/blog/manage`)
+and reject on `!result.ok`. Pure + server-safe; reuses the existing `mdxToPlainText`/`countWords`/
+`extractToc` helpers, no new dependencies. Reachable from the main `hazo_blog` entry and the
+`hazo_blog/lib` subpath.
+
+**`hazo_blog/lib` subpath export (new)** — the `./lib` subpath (advertised in the README for the
+text utilities but previously absent from `package.json` `exports`) is now a real entry, so
+`sanitizeMdx`/`mdxToPlainText`/`slugify`/`extractToc`/`validatePost` etc. import directly from
+`hazo_blog/lib` as documented (they were only reachable via the main `hazo_blog` entry before).
+
+**Internal (test tooling)**
+- Fixed `repository.integration.test.ts` failing to run: the CJS-transformed `hazo_connect` adapter
+  graph does `require()` of ESM-only hazo packages (`hazo_core`, and transitively
+  `hazo_secure/crypto`), which jest's vm-modules loader can't `require()` on Node < 24.9 ("Must use
+  import to load ES Module"). Fix: plain-**CJS** mocks — `__mocks__/hazo_core.cjs` (functional error
+  classes + `safeJsonParse` etc.) and `__mocks__/hazo_secure_crypto.cjs` (passthrough field-crypto
+  stub) — mapped via `moduleNameMapper`, plus a `transformIgnorePatterns` exception for
+  `hazo_connect`/`hazo_core`. `.cjs` isn't matched by the `tsx` transform, so it loads raw as
+  CommonJS and the real `hazo_connect` adapter resolves against it. The integration test now runs
+  against real `hazo_connect` + real SQLite on the Node 22 the workspace pins for better-sqlite3.
+  (An earlier `.ts` ESM mock silently did **not** fix this on Node 22 — a CJS `require()` still can't
+  load an ESM `.ts`.)
+
 ## 0.3.3 — 2026-07-06
 
 **`sanitizeMdx` hardened against raw WordPress HTML**

package/README.md

@@ -224,7 +224,7 @@ pipelines.
 | `hazo_blog` | server: `createBlogService`, `createBlogRepository`, SEO builders, **route-handler factories** (React-free), types |
 | `hazo_blog/client` | client components: `PostCard`, `PostHero`, `AuthorBio`, `FaqSection`, `TableOfContents`, `RelatedPosts`, `BlogSearch`, `PostForm`, MDX components, `trackBlogEvent` |
 | `hazo_blog/next` | sealed page factories: public (`createBlogIndexPage`, `createBlogPostPage`, `createBlogTagPage`) + admin (`createBlogAdminListPage`, `createBlogAdminNewPage`, `createBlogAdminEditPage`) + `BlogContent` + `MdxErrorBoundary` |
-| `hazo_blog/lib` | pure text utilities: `sanitizeMdx`, `mdxToPlainText`, `buildExcerpt`, `slugify`, `calculateReadingTime`, `extractToc` |
+| `hazo_blog/lib` | pure text utilities: `sanitizeMdx`, `mdxToPlainText`, `buildExcerpt`, `slugify`, `calculateReadingTime`, `extractToc` + `validatePost` (pre-publish content-quality gate) |
 | `hazo_blog/seo` | `buildBlogPostingJsonLd`, `buildBreadcrumbJsonLd`, `buildFaqJsonLd`, `getBlogSitemapEntries`, `getBlogRobotsRules`, `getBlogRssXml` |
 | `hazo_blog/config` | `BlogConfig` types + `resolveConfig` |
 
@@ -244,6 +244,28 @@ searchApiPath: "/api/blog/search", // default
 See `SETUP_CHECKLIST.md` for a step-by-step integration list. A runnable demo
 lives in `test-app/`.
 
+## Pre-publish validation
+
+`validatePost` is a pure, server-safe content-quality gate. Wire it into your
+create/update/publish path and reject on `!result.ok`:
+
+```ts
+import { validatePost } from "hazo_blog"; // also on the `hazo_blog/lib` subpath
+
+const result = validatePost(
+  { title, content, meta_description, excerpt, faq },
+  { titleSuffix: " | GoTimer" }, // options are optional
+);
+
+if (!result.ok) {
+  return fail(result.errors); // blocking: thin content, missing meta description, a second <h1>
+}
+logWarnings(result.warnings);   // advisory: meta length, over-long title, missing excerpt/FAQ, no subheadings
+```
+
+Options: `minWords` (default 300), `titleLengthLimit` (default 60, suffix-aware),
+`titleSuffix`, `descriptionRange` (default `[150, 160]`).
+
 ## License
 
 MIT

package/SETUP_CHECKLIST.md

@@ -36,6 +36,7 @@ for full code samples.
 - [ ] `app/api/blog/feed/route.ts` → `createBlogFeedRoute`
 - [ ] `app/api/admin/blog/route.ts` + `[id]/route.ts` → `createBlogAdminRoutes`
 - [ ] (optional) `app/api/blog/manage/route.ts` → `createBlogManageRoutes`
+- [ ] (optional) call `validatePost(input, opts)` in your create/update/publish path and reject on `!result.ok` (pre-publish content-quality gate)
 - [ ] Merge `getBlogSitemapEntries()` into root `app/sitemap.ts` and `getBlogRobotsRules()` into `app/robots.ts`
 
 ### Admin UI pages (sealed, recommended)

package/dist/lib/index.d.ts

@@ -1,2 +1,3 @@
 export * from "./text.js";
+export * from "./validate.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/index.ts"],"names":[],"mappings":"AACA,cAAc,WAAW,CAAC;AAC1B,cAAc,eAAe,CAAC"}

package/dist/lib/index.js

@@ -1,2 +1,3 @@
 // hazo_blog/src/lib/index.ts — core library exports (server-safe).
 export * from "./text.js";
+export * from "./validate.js";

package/dist/lib/validate.d.ts

@@ -0,0 +1,48 @@
+import type { FaqItem, PostStatus } from '../types/index.js';
+export interface ValidatePostInput {
+    title: string;
+    /** Raw MDX body. */
+    content: string;
+    meta_title?: string;
+    meta_description?: string;
+    excerpt?: string | null;
+    faq?: FaqItem[];
+    status?: PostStatus;
+}
+export interface PostValidationOptions {
+    /** Minimum body word count before content is flagged as thin. Default 300. */
+    minWords?: number;
+    /**
+     * Max length of the *composed* SEO title (title + `titleSuffix`) before a
+     * warning. Default 60 (Google's practical display limit).
+     */
+    titleLengthLimit?: number;
+    /** Brand/site suffix appended to titles at render time, e.g. " | GoTimer". Default "". */
+    titleSuffix?: string;
+    /** [min, max] ideal meta-description length. Default [150, 160]. */
+    descriptionRange?: [number, number];
+}
+export type ValidationSeverity = 'error' | 'warning';
+export interface ValidationIssue {
+    code: string;
+    severity: ValidationSeverity;
+    message: string;
+}
+export interface PostValidationResult {
+    /** True when there are no `error`-severity issues. */
+    ok: boolean;
+    errors: ValidationIssue[];
+    warnings: ValidationIssue[];
+    /** All issues (errors + warnings), in the order produced. */
+    issues: ValidationIssue[];
+    /** Body word count (plain text), exposed for logging/telemetry. */
+    wordCount: number;
+}
+/**
+ * Validate a post before publishing. Blocking issues land in `errors`
+ * (thin content, missing meta description, a second page <h1> in the body);
+ * advisory issues land in `warnings` (meta-description length, over-long title,
+ * missing excerpt/FAQ, no subheadings). `ok` is true iff there are no errors.
+ */
+export declare function validatePost(input: ValidatePostInput, opts?: PostValidationOptions): PostValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/lib/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../../src/lib/validate.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG7D,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,MAAM,CAAC;IACd,oBAAoB;IACpB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,GAAG,CAAC,EAAE,OAAO,EAAE,CAAC;IAChB,MAAM,CAAC,EAAE,UAAU,CAAC;CACrB;AAED,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;OAGG;IACH,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,0FAA0F;IAC1F,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oEAAoE;IACpE,gBAAgB,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,MAAM,kBAAkB,GAAG,OAAO,GAAG,SAAS,CAAC;AAErD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,oBAAoB;IACnC,sDAAsD;IACtD,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,6DAA6D;IAC7D,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,mEAAmE;IACnE,SAAS,EAAE,MAAM,CAAC;CACnB;AAOD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,KAAK,EAAE,iBAAiB,EACxB,IAAI,GAAE,qBAA0B,GAC/B,oBAAoB,CAyDtB"}

package/dist/lib/validate.js

@@ -0,0 +1,68 @@
+// hazo_blog/lib — validatePost(): a pre-publish content-quality gate.
+//
+// Encodes the SEO lessons that a stale Bing report surfaced late on a consumer
+// site: thin content, missing/oversized meta, and multiple <h1> per page. A
+// post's <h1> is its *title* — an `# ` (or <h1>) inside the body creates a
+// second page heading. Consumers call this before persisting/publishing and
+// reject on `errors` (blocking) while surfacing `warnings` (advisory).
+//
+// Pure + server-safe; reuses the existing text helpers, no new deps.
+import { mdxToPlainText, countWords, extractToc } from './text.js';
+/** Strip fenced code so a `#` in a code sample isn't mistaken for a heading. */
+function stripFencedCode(mdx) {
+    return mdx.replace(/```[\s\S]*?```/g, ' ');
+}
+/**
+ * Validate a post before publishing. Blocking issues land in `errors`
+ * (thin content, missing meta description, a second page <h1> in the body);
+ * advisory issues land in `warnings` (meta-description length, over-long title,
+ * missing excerpt/FAQ, no subheadings). `ok` is true iff there are no errors.
+ */
+export function validatePost(input, opts = {}) {
+    const minWords = opts.minWords ?? 300;
+    const titleLimit = opts.titleLengthLimit ?? 60;
+    const titleSuffix = opts.titleSuffix ?? '';
+    const [descMin, descMax] = opts.descriptionRange ?? [150, 160];
+    const errors = [];
+    const warnings = [];
+    const add = (severity, code, message) => (severity === 'error' ? errors : warnings).push({ code, severity, message });
+    // --- Thin content ---
+    const wordCount = countWords(mdxToPlainText(input.content));
+    if (wordCount < minWords) {
+        add('error', 'THIN_CONTENT', `Body is ${wordCount} words (<${minWords}). Expand before publishing.`);
+    }
+    // --- Second page <h1> in the body (the post title is the page <h1>) ---
+    const body = stripFencedCode(input.content);
+    const hasMarkdownH1 = /(^|\n)#\s+\S/.test(body);
+    const hasJsxH1 = /<h1[\s>]/i.test(body);
+    if (hasMarkdownH1 || hasJsxH1) {
+        add('error', 'BODY_H1', 'Body contains an H1 ("# " or <h1>). The post title is already the page H1 — demote body headings to ## or lower.');
+    }
+    // --- Meta description ---
+    const desc = input.meta_description?.trim();
+    if (!desc) {
+        add('error', 'MISSING_META_DESCRIPTION', 'Missing meta description.');
+    }
+    else if (desc.length < descMin) {
+        add('warning', 'META_DESCRIPTION_SHORT', `Meta description is ${desc.length} chars (<${descMin}). The ${descMin}–${descMax} band maximises snippet size.`);
+    }
+    else if (desc.length > descMax) {
+        add('warning', 'META_DESCRIPTION_LONG', `Meta description is ${desc.length} chars (>${descMax}) and will be truncated in SERPs.`);
+    }
+    // --- Composed title length ---
+    const seoTitle = (input.meta_title?.trim() || input.title.trim()) + titleSuffix;
+    if (seoTitle.length > titleLimit) {
+        add('warning', 'TITLE_TOO_LONG', `Rendered title "${seoTitle}" is ${seoTitle.length} chars (>${titleLimit}, incl. suffix). Google truncates ~60 and Bing flags >70.`);
+    }
+    // --- Softer structural advisories ---
+    if (!input.excerpt?.trim()) {
+        add('warning', 'MISSING_EXCERPT', 'No excerpt set — one will be auto-generated, but a hand-written excerpt reads better in listings.');
+    }
+    if (!input.faq || input.faq.length === 0) {
+        add('warning', 'NO_FAQ', 'No FAQ items. An FAQ section adds long-tail coverage (and is used across the site).');
+    }
+    if (extractToc(input.content).length === 0 && wordCount >= minWords) {
+        add('warning', 'NO_SUBHEADINGS', 'No subheadings (##) found. Long posts need structure for readers and for heading-based SERP features.');
+    }
+    return { ok: errors.length === 0, errors, warnings, issues: [...errors, ...warnings], wordCount };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hazo_blog",
-  "version": "0.3.3",
+  "version": "0.4.0",
   "description": "SEO-optimized blogging package: posts, categories, tags, MDX content, and GA4/GSC/Bing-ready SEO.",
   "type": "module",
   "module": "./dist/index.js",
@@ -14,6 +14,10 @@
       "types": "./dist/index.client.d.ts",
       "import": "./dist/index.client.js"
     },
+    "./lib": {
+      "types": "./dist/lib/index.d.ts",
+      "import": "./dist/lib/index.js"
+    },
     "./seo": {
       "types": "./dist/seo/index.d.ts",
       "import": "./dist/seo/index.js"
@@ -45,13 +49,14 @@
   },
   "peerDependencies": {
     "hazo_core": "^1.2.1",
-    "hazo_connect": "^3.9.0",
+    "hazo_connect": "^3.9.2",
     "hazo_api": "^2.5.1",
     "hazo_files": "^3.1.1",
-    "hazo_ui": "^4.8.0",
-    "hazo_images": "^1.7.0",
-    "hazo_jobs": "^0.14.0",
-    "hazo_auth": "^10.5.0",
+    "hazo_theme": "^1.0.1",
+    "hazo_ui": "^6.0.0",
+    "hazo_images": "^1.8.1",
+    "hazo_jobs": "^0.15.0",
+    "hazo_auth": "^10.8.2",
     "react": "^18.0.0 || ^19.0.0",
     "react-dom": "^18.0.0 || ^19.0.0",
     "next": "^14.0.0 || ^16.0.0"
@@ -65,6 +70,9 @@
     },
     "hazo_auth": {
       "optional": true
+    },
+    "hazo_theme": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -84,10 +92,10 @@
     "react-dom": "^19.0.0",
     "next": "^16.0.10",
     "hazo_core": "^1.2.1",
-    "hazo_connect": "^3.9.0",
+    "hazo_connect": "^3.9.2",
     "hazo_api": "^2.5.1",
     "hazo_files": "^3.1.1",
-    "hazo_ui": "^4.8.0",
+    "hazo_ui": "^6.0.0",
     "tailwindcss": "^4.2.4",
     "@tailwindcss/postcss": "^4.2.4",
     "postcss": "^8.4.49"