hubspot-cms-sync 0.2.0 → 0.3.0

package/README.md

@@ -9,6 +9,11 @@ The tool reads account and site settings from `hubspot-cms-sync.config.mjs`,
 stores per-account identity in a gitignored `.sync-state/` directory, and
 refuses to write to configured read-only portal ids.
 
+See [`docs/CONTENT_LAYOUT.md`](docs/CONTENT_LAYOUT.md) for the repository
+layout, supported push surfaces, and a minimal example tree. A runnable fixture
+lives in [`examples/minimal-site/`](examples/minimal-site/) and is validated by
+the unit tests.
+
 ## Install
 
 ```bash
@@ -29,15 +34,16 @@ hcms pull dev
 hcms preflight dev
 hcms push dev --dry-run
 hcms push dev --publish
-hcms redirects dev --file content/redirects.csv
-hcms redirects dev --file content/redirects.csv --apply
+hcms redirects dev
+hcms redirects dev --apply
 hcms republish dev --all --blog
 hcms corpus
 hcms manifest validate
 ```
 
 `hcms redirects` is dry-run by default. Pass `--apply` to create or update
-HubSpot URL redirects from a repo-stored CSV or JSON spec. Managed redirects
+HubSpot URL redirects from the configured `redirectsFile`, or pass `--file` to
+use a specific repo-stored CSV or JSON spec. Managed redirects
 default to `301` and `isOnlyAfterNotFound: false`, so they can intentionally
 take precedence over an existing live HubSpot page during a cutover.
 

package/bin/hubspot-cms-sync.mjs

@@ -74,9 +74,12 @@ async function main(argv = process.argv) {
     .command('preflight')
     .description('check account readiness before a push')
     .argument('<account>')
-    .action(async (account) => {
+    .option('--allow-repairable', 'allow source-repairable portal drift before the push')
+    .action(async (account, options) => {
       const config = await withConfig(program.opts());
-      const code = await preflightMain([account], { config });
+      const args = [account];
+      if (options.allowRepairable) args.push('--allow-repairable');
+      const code = await preflightMain(args, { config });
       if (code) process.exitCode = code;
     });
 

package/docs/CONTENT_LAYOUT.md

@@ -0,0 +1,146 @@
+# Content Layout
+
+`hcms` syncs a normal repository tree into HubSpot CMS records. The exact paths
+are configurable in `hubspot-cms-sync.config.mjs`, but the default layout is:
+
+```text
+my-site/
+|-- hubspot-cms-sync.config.mjs
+|-- site.manifest.json
+|-- sync/
+|   |-- accounts.json
+|   `-- redirects.csv
+|-- content/
+|   |-- pages/
+|   |   |-- home.json
+|   |   |-- home.widgets.json
+|   |   `-- about.json
+|   |-- forms/
+|   |   |-- contact.json
+|   |   `-- properties.json
+|   |-- assets/
+|   |   `-- hero.svg
+|   `-- blog/
+|       |-- container.json
+|       `-- posts/
+|           `-- blog__hello-world.json
+|-- templates/
+|   |-- home.html
+|   |-- page.html
+|   |-- blog.html
+|   `-- blog-post.html
+|-- modules/
+|   `-- hero.module/
+|       |-- fields.json
+|       `-- module.html
+|-- css/
+|   `-- main.css
+|-- js/
+|   `-- hs-forms.js
+|-- theme.json
+`-- fields.json
+```
+
+A complete minimal fixture lives at [`examples/minimal-site/`](../examples/minimal-site/).
+The unit test suite loads that fixture, validates its manifest and redirects,
+runs the local push ref preflight, reads its canonical forms, and scans it with
+the corpus scanner.
+
+## What Can Be Pushed
+
+`hcms push <account>` writes the content surfaces below. It is idempotent by
+portable identity: page slug, form name/key, blog slug/post slug, theme path, and
+redirect route.
+
+| Surface | Repo source | HubSpot target |
+| --- | --- | --- |
+| Theme code | `templates/`, `modules/`, `css/`, `js/`, `images/`, `theme.json`, `fields.json` | CMS Source Code API |
+| Site pages | `content/pages/*.json` plus `site.manifest.json` | CMS Pages API |
+| Page module values | `content/pages/*.widgets.json` | CMS Pages draft widget carrier |
+| Forms | `content/forms/<key>.json` | Forms API |
+| Contact properties | `content/forms/properties.json` | CRM Properties API |
+| File assets | `content/assets/**` and `content/blog/assets/**` | File Manager API |
+| Blog container and posts | `content/blog/container.json`, `content/blog/posts/*.json` | Blog APIs |
+| URL redirects | `sync/redirects.csv` or configured `redirectsFile` | CMS URL Redirects API |
+
+## Deployment Surface
+
+`site.manifest.json` is the allowlist for pages, forms, blog, theme, and
+UI-gated prerequisites. A page file under `content/pages/` is not enough by
+itself; the page must also be listed in the manifest.
+
+```json
+{
+  "theme": { "name": "example-theme" },
+  "pages": [
+    {
+      "slug": "",
+      "templatePath": "example-theme/templates/home.html",
+      "desiredState": "publish"
+    },
+    {
+      "slug": "about",
+      "templatePath": "example-theme/templates/page.html",
+      "desiredState": "draft"
+    }
+  ],
+  "blog": {
+    "slug": "blog",
+    "itemTemplate": "example-theme/templates/blog-post.html",
+    "listingTemplate": "example-theme/templates/blog.html"
+  },
+  "forms": ["contact"],
+  "uiGated": ["blogContainerCreate", "domainConnect"]
+}
+```
+
+`desiredState` may be `publish`, `draft`, `archive`, or `ignore`.
+
+## Portable References
+
+Committed content should not contain raw portal IDs, form GUIDs, CTA GUIDs, or
+HubSpot-hosted asset URLs. Use logical refs instead:
+
+| Logical ref | Producer source |
+| --- | --- |
+| `@portal` | The target account's portal ID |
+| `@form:contact` | `content/forms/contact.json` or `content/forms/guids.json` |
+| `@asset:hero.svg` | `content/assets/hero.svg` or `content/blog/assets/hero.svg` |
+
+`hcms push` runs a local preflight before network writes. If content references
+`@form:contact`, the form producer source must exist. If content references
+`@asset:hero.png`, committed bytes must exist. `@cta:*` and `@menu:*` currently
+fail closed because there are no producer adapters for them yet.
+
+## Redirects
+
+Redirects are separate from the page manifest. Configure their path with
+`redirectsFile`, then run:
+
+```bash
+hcms redirects dev          # dry-run
+hcms redirects dev --apply  # create/update HubSpot redirects
+```
+
+CSV redirects need at least:
+
+```csv
+routePrefix,destination,redirectStyle,isOnlyAfterNotFound
+/old-about,/about,301,false
+```
+
+`isOnlyAfterNotFound=false` makes a redirect take precedence over an existing
+live page at the same route. Use it deliberately during cutovers.
+
+## Not Fully Automated
+
+Some portal state is still UI-gated or depends on HubSpot account setup:
+
+- connecting domains;
+- choosing system pages such as the default 404;
+- creating the initial blog container in some portals;
+- native menus until a menu producer exists;
+- theme settings values if the theme relies on HubSpot UI-managed settings.
+
+Track those prerequisites in `uiGated` and check them with
+`hcms preflight <account>` before writing content.

package/docs/GITHUB_ACTIONS.md

@@ -54,7 +54,9 @@ The examples prefer this sequence for write-capable operations:
 3. `hcms preflight <target>`
 4. `hcms push <target> --dry-run`
 5. `hcms push <target> --publish`
-6. `the consuming repo verification commands`
+6. `hcms redirects <target>`
+7. `hcms redirects <target> --apply`
+8. `the consuming repo verification commands`
 
 For read-only CI, omit write steps and keep production credentials unavailable.
 

package/examples/minimal-site/content/assets/hero.svg

@@ -0,0 +1,9 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="630" viewBox="0 0 1200 630" role="img" aria-labelledby="title desc">
+  <title id="title">Example hero image</title>
+  <desc id="desc">A simple placeholder image for the minimal hcms site.</desc>
+  <rect width="1200" height="630" fill="#f5f7fb"/>
+  <rect x="96" y="96" width="1008" height="438" rx="24" fill="#ffffff" stroke="#d8dee9"/>
+  <circle cx="210" cy="220" r="58" fill="#1f7a8c"/>
+  <path d="M320 190h520v34H320zM320 252h420v28H320zM320 310h600v22H320zM320 352h480v22H320z" fill="#233142"/>
+  <path d="M160 430h220v58H160z" fill="#f25f5c"/>
+</svg>

package/examples/minimal-site/content/blog/container.json

@@ -0,0 +1,6 @@
+{
+  "slug": "blog",
+  "name": "Example Blog",
+  "itemTemplatePath": "example-theme/templates/blog-post.html",
+  "listingTemplatePath": "example-theme/templates/blog.html"
+}

package/examples/minimal-site/content/blog/posts/blog__hello-world.json

@@ -0,0 +1,13 @@
+{
+  "slug": "blog/hello-world",
+  "blogSlug": "blog",
+  "name": "Hello World",
+  "htmlTitle": "Hello World",
+  "publishDate": "2026-01-01T12:00:00.000Z",
+  "postBody": "<p>Hello from git.</p><img src=\"@asset:hero.svg\" alt=\"Example\">",
+  "postSummary": "<p>A minimal post.</p>",
+  "authorSlug": null,
+  "authorName": null,
+  "tagSlugs": [],
+  "tagNames": []
+}

package/examples/minimal-site/content/forms/contact.json

@@ -0,0 +1,18 @@
+{
+  "key": "contact",
+  "name": "Website: Contact (general)",
+  "fields": [
+    {
+      "name": "firstname",
+      "label": "First name",
+      "fieldType": "text",
+      "required": false
+    },
+    {
+      "name": "email",
+      "label": "Work email",
+      "fieldType": "text",
+      "required": true
+    }
+  ]
+}

package/examples/minimal-site/content/forms/properties.json

@@ -0,0 +1,7 @@
+[
+  {
+    "name": "topic",
+    "label": "Inquiry topic",
+    "fieldType": "text"
+  }
+]

package/examples/minimal-site/content/pages/about.json

@@ -0,0 +1,9 @@
+{
+  "slug": "about",
+  "name": "About",
+  "htmlTitle": "About Example",
+  "metaDescription": "A minimal hcms about page.",
+  "language": "en",
+  "templatePath": "example-theme/templates/page.html",
+  "desiredState": "draft"
+}

package/examples/minimal-site/content/pages/home.json

@@ -0,0 +1,9 @@
+{
+  "slug": "",
+  "name": "Home",
+  "htmlTitle": "Example Home",
+  "metaDescription": "A minimal hcms homepage.",
+  "language": "en",
+  "templatePath": "example-theme/templates/home.html",
+  "desiredState": "publish"
+}

package/examples/minimal-site/content/pages/home.widgets.json

@@ -0,0 +1,17 @@
+{
+  "slug": "",
+  "widgets": {
+    "hero": {
+      "body": {
+        "headline": "Ship HubSpot CMS from git",
+        "image": "@asset:hero.svg",
+        "form_id": "@form:contact"
+      },
+      "name": "hero",
+      "type": "module",
+      "label": "Hero",
+      "css": {},
+      "child_css": {}
+    }
+  }
+}

package/examples/minimal-site/css/main.css

@@ -0,0 +1,3 @@
+.hero {
+  padding: 3rem 0;
+}

package/examples/minimal-site/fields.json

@@ -0,0 +1,11 @@
+[
+  {
+    "name": "brand_color",
+    "label": "Brand color",
+    "type": "color",
+    "default": {
+      "color": "#2f6fed",
+      "opacity": 100
+    }
+  }
+]

package/examples/minimal-site/hubspot-cms-sync.config.mjs

@@ -0,0 +1,27 @@
+export default {
+  accountsFile: 'sync/accounts.json',
+  keyDirEnv: 'HUBSPOT_KEY_DIR',
+  contentDir: 'content',
+  syncStateDir: '.sync-state',
+  manifestPath: 'site.manifest.json',
+  redirectsFile: 'sync/redirects.csv',
+  readOnlyPortalIds: ['999999'],
+  knownPortalIds: ['123456'],
+  theme: {
+    name: 'example-theme',
+    dirs: ['templates', 'modules', 'css', 'js', 'images'],
+    files: ['theme.json', 'fields.json']
+  },
+  blog: {
+    slug: 'blog',
+    itemTemplate: 'example-theme/templates/blog-post.html',
+    listingTemplate: 'example-theme/templates/blog.html'
+  },
+  uiGated: ['blogContainerCreate', 'domainConnect'],
+  verification: {
+    baseUrlEnv: 'SITE_BASE_URL',
+    commands: {
+      corpus: 'hcms corpus'
+    }
+  }
+};

package/examples/minimal-site/js/hs-forms.js

@@ -0,0 +1 @@
+window.EXAMPLE_PORTAL_ID = '@portal';

package/examples/minimal-site/modules/hero.module/fields.json

@@ -0,0 +1,14 @@
+[
+  {
+    "name": "headline",
+    "label": "Headline",
+    "type": "text",
+    "default": "Ship HubSpot CMS from git"
+  },
+  {
+    "name": "form_id",
+    "label": "Contact form",
+    "type": "form",
+    "default": "@form:contact"
+  }
+]

package/examples/minimal-site/modules/hero.module/module.html

@@ -0,0 +1,4 @@
+<section class="hero">
+  <h1>{{ module.headline }}</h1>
+  {% form form_to_use="{{ module.form_id }}" %}
+</section>

package/examples/minimal-site/site.manifest.json

@@ -0,0 +1,29 @@
+{
+  "theme": {
+    "name": "example-theme"
+  },
+  "pages": [
+    {
+      "slug": "",
+      "templatePath": "example-theme/templates/home.html",
+      "desiredState": "publish"
+    },
+    {
+      "slug": "about",
+      "templatePath": "example-theme/templates/page.html",
+      "desiredState": "draft"
+    }
+  ],
+  "blog": {
+    "slug": "blog",
+    "itemTemplate": "example-theme/templates/blog-post.html",
+    "listingTemplate": "example-theme/templates/blog.html"
+  },
+  "forms": [
+    "contact"
+  ],
+  "uiGated": [
+    "blogContainerCreate",
+    "domainConnect"
+  ]
+}

package/examples/minimal-site/sync/accounts.json

@@ -0,0 +1,10 @@
+{
+  "dev": {
+    "portalId": "123456",
+    "label": "example dev portal"
+  },
+  "prod": {
+    "portalId": "999999",
+    "label": "example production portal"
+  }
+}

package/examples/minimal-site/sync/redirects.csv

@@ -0,0 +1,2 @@
+routePrefix,destination,redirectStyle,isOnlyAfterNotFound
+/old-about,/about,301,false

package/examples/minimal-site/templates/blog-post.html

@@ -0,0 +1,8 @@
+<!--
+  templateType: blog_post
+  label: Example Blog Post
+-->
+<article>
+  <h1>{{ content.name }}</h1>
+  {{ content.post_body }}
+</article>

package/examples/minimal-site/templates/blog.html

@@ -0,0 +1,9 @@
+<!--
+  templateType: blog_listing
+  label: Example Blog Listing
+-->
+<main>
+  {% for content in contents %}
+    <article><a href="{{ content.absolute_url }}">{{ content.name }}</a></article>
+  {% endfor %}
+</main>

package/examples/minimal-site/templates/home.html

@@ -0,0 +1,5 @@
+<!--
+  templateType: page
+  label: Example Home
+-->
+{% module "hero" path="../modules/hero.module" %}

package/examples/minimal-site/templates/page.html

@@ -0,0 +1,7 @@
+<!--
+  templateType: page
+  label: Example Page
+-->
+<main>
+  <h1>{{ content.name }}</h1>
+</main>

package/examples/minimal-site/theme.json

@@ -0,0 +1,4 @@
+{
+  "label": "Example Theme",
+  "preview_path": "./templates/home.html"
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hubspot-cms-sync",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Git-backed bidirectional sync for HubSpot CMS themes, content, blogs, forms, and assets.",
   "type": "module",
   "license": "MIT",
@@ -48,6 +48,8 @@
     "prepublishOnly": "npm test && npm run lint && npm pack --dry-run"
   },
   "dependencies": {
-    "commander": "^14.0.3"
+    "commander": "^14.0.3",
+    "js-yaml": "^4.2.0",
+    "nunjucks": "^3.2.4"
   }
 }

package/skill/references/commands.md

@@ -35,11 +35,15 @@ hcms corpus
 hcms preflight <target>
 hcms push <target> --dry-run
 hcms push <target> --publish
+hcms redirects <target>
+hcms redirects <target> --apply
 the consuming repo verification commands
 ```
 
 Stop before `push` if preflight or plan output indicates a read-only portal,
 unresolved dependency, missing credential, or unexpected destructive change.
+Run `hcms redirects` without `--apply` first when redirects are part of the
+deployment surface.
 
 ## Republish
 

package/skill/references/config.md

@@ -9,6 +9,7 @@ Key fields:
 - `contentDir`: local CMS content directory.
 - `syncStateDir`: local sync state directory; do not edit by hand.
 - `manifestPath`: path to `site.manifest.json`.
+- `redirectsFile`: optional CSV or JSON file for repo-managed URL redirects.
 - `readOnlyPortalIds`: portals that must never receive writes.
 - `knownPortalIds`: expected portal allowlist.
 - `assetHosts`: host canonicalization policy for HubSpot assets.
@@ -19,7 +20,10 @@ Key fields:
 - `verification`: base URL environment variable and repo-specific test commands.
 
 `site.manifest.json` is the deployment surface for theme, blog, forms, pages,
-and UI-gated operations. If the manifest and config disagree, stop and ask for
-the intended source of truth.
+and UI-gated operations. Redirects are managed separately through
+`redirectsFile`. If the manifest and config disagree, stop and ask for the
+intended source of truth.
 
 Use paths relative to the repo root unless the config explicitly says otherwise.
+See `docs/CONTENT_LAYOUT.md` for the expected repository layout and minimal
+sample tree.

package/src/lib/content-view.mjs

@@ -0,0 +1,168 @@
+// src/lib/content-view.mjs — NEUTRAL content projection.
+//
+// THE BOUNDARY. The on-disk canonical store is HubSpot's CMS WIRE FORMAT: pages
+// carry `widgets.<name>.body.<field>` editor carriers (with load-bearing empty
+// `css`/`child_css`/`label` objects that HubSpot's replace-not-merge PATCH
+// requires — see lib/canonical.mjs), blog posts use HubSpot Blog API field names
+// (`postBody`, `useFeaturedImage`, `blogSlug`, `state:"PUBLISHED"`), and module
+// `fields.json` files carry server-assigned GUIDs and `content_types` enums.
+//
+// None of that belongs in a GENERIC publishing toolkit. This module projects the
+// wire format into a small, target-agnostic VIEW that the renderer and any future
+// non-HubSpot target consume. The renderer NEVER reaches into `.widgets.x.body`,
+// reads a field GUID, or knows the string "PUBLISHED" — it sees only this view.
+//
+// Identity portability (@asset:/@portal/@form: refs) was already solved by
+// lib/refs.mjs. This is the same idea extended to SCHEMA portability: the HubSpot
+// blob is one target's codec output, not the canonical truth. Today the view is
+// derived from the blob on read; later the view's shape could become the on-disk
+// format and a HubSpot codec could reconstruct the blob — the seam is the same.
+//
+// PURE except for the explicit fs reads in load*(). The project*() transforms are
+// pure functions over parsed JSON so they unit-test without a fixture tree.
+
+import { readFile, readdir } from 'node:fs/promises';
+import { join, basename } from 'node:path';
+
+// ---------------------------------------------------------------------------
+// Status vocabulary. HubSpot speaks `desiredState` (page) and `state` (post):
+// publish|draft|archive|ignore / PUBLISHED|DRAFT. The view speaks one neutral
+// enum so a target never branches on a HubSpot string.
+// ---------------------------------------------------------------------------
+const STATUS = { published: 'published', draft: 'draft', archived: 'archived' };
+
+function neutralStatus(raw) {
+  if (!raw) return STATUS.draft;
+  const s = String(raw).toLowerCase();
+  if (s === 'publish' || s === 'published') return STATUS.published;
+  if (s === 'archive' || s === 'archived' || s === 'ignore') return STATUS.archived;
+  return STATUS.draft;
+}
+
+// ---------------------------------------------------------------------------
+// projectPost(raw, authorsByName) -> neutral post view
+//
+// Maps HubSpot Blog API field names onto neutral names and JOINS the author
+// record by name. `body`/`summary` stay as raw HTML strings (still carrying
+// @asset: refs for the target to resolve). `featuredImage` is left as its
+// logical ref — ref resolution is the TARGET's job, not the view's.
+// ---------------------------------------------------------------------------
+export function projectPost(raw, authorsByName = {}) {
+  const author = authorsByName[raw.authorName] || (raw.authorName ? { name: raw.authorName } : null);
+  return {
+    kind: 'post',
+    // Routing: HubSpot stores `slug` as "blog/<slug>"; the route is absolute.
+    slug: raw.slug,
+    route: '/' + String(raw.slug || '').replace(/^\/+/, ''),
+    status: neutralStatus(raw.state),
+    title: raw.name,
+    htmlTitle: raw.htmlTitle || raw.name,
+    metaDescription: raw.metaDescription || '',
+    body: raw.postBody || '',
+    summary: raw.postSummary || '',
+    publishDate: raw.publishDate || null,
+    tags: Array.isArray(raw.tagNames) ? raw.tagNames.slice() : [],
+    author,
+    featuredImage: raw.useFeaturedImage ? raw.featuredImage || null : null,
+    featuredImageAlt: raw.featuredImageAltText || '',
+    blogSlug: raw.blogSlug || 'blog',
+  };
+}
+
+// ---------------------------------------------------------------------------
+// projectPage(raw) -> neutral page view
+//
+// The crux of the schema-portability argument. HubSpot nests per-module field
+// values under `widgets.<instanceName>.body.<field>`, wrapped in editor cruft
+// (`css`, `child_css`, `label`, `type:"module"`) that is inert at render time.
+// The view flattens each carrier to `modules[instanceName] = {<field>: value}`
+// and drops the cruft. The renderer keys modules by instance name; it never sees
+// `body` or the empty style objects the HubSpot target round-trips.
+// ---------------------------------------------------------------------------
+export function projectPage(raw) {
+  const modules = {};
+  const widgets = raw.widgets || {};
+  for (const [name, carrier] of Object.entries(widgets)) {
+    if (!carrier || carrier.type !== 'module') continue;
+    modules[name] = { ...(carrier.body || {}) };
+  }
+  // `templatePath` is "<theme>/templates/<file>.html"; the view keeps the file
+  // path relative to the theme so the renderer's loader resolves it.
+  const tpl = String(raw.templatePath || '');
+  const templateRel = tpl.replace(/^[^/]+\//, ''); // drop leading "<theme>/"
+  return {
+    kind: 'page',
+    slug: raw.slug ?? '',
+    route: '/' + String(raw.slug ?? '').replace(/^\/+/, ''),
+    status: neutralStatus(raw.desiredState),
+    title: raw.name,
+    htmlTitle: raw.htmlTitle || raw.name,
+    metaDescription: raw.metaDescription || '',
+    language: raw.language || 'en',
+    template: templateRel,
+    modules,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Loaders. The only I/O in this module.
+// ---------------------------------------------------------------------------
+async function readJson(file) {
+  return JSON.parse(await readFile(file, 'utf8'));
+}
+
+/** loadAuthors(blogDir) -> { [displayName|name]: neutralAuthor } */
+export async function loadAuthors(blogDir) {
+  const byName = {};
+  try {
+    const authors = await readJson(join(blogDir, 'authors.json'));
+    for (const a of authors) {
+      const neutral = {
+        name: a.displayName || a.fullName || a.name,
+        bio: a.bio || '',
+        avatar: a.avatar || null,
+        slug: a.slug || null,
+      };
+      for (const key of [a.displayName, a.fullName, a.name]) {
+        if (key) byName[key] = neutral;
+      }
+    }
+  } catch {
+    /* authors.json optional */
+  }
+  return byName;
+}
+
+/** loadPosts(contentDir) -> neutralPostView[] (newest first) */
+export async function loadPosts(contentDir) {
+  const blogDir = join(contentDir, 'blog');
+  const postsDir = join(blogDir, 'posts');
+  const authorsByName = await loadAuthors(blogDir);
+  const files = (await readdir(postsDir)).filter((f) => f.endsWith('.json'));
+  const posts = [];
+  for (const f of files.sort()) {
+    posts.push(projectPost(await readJson(join(postsDir, f)), authorsByName));
+  }
+  posts.sort((a, b) => String(b.publishDate || '').localeCompare(String(a.publishDate || '')));
+  return posts;
+}
+
+/** loadPages(contentDir) -> neutralPageView[] */
+export async function loadPages(contentDir) {
+  const pagesDir = join(contentDir, 'pages');
+  const files = (await readdir(pagesDir)).filter((f) => f.endsWith('.json'));
+  const pages = [];
+  for (const f of files.sort()) {
+    pages.push(projectPage(await readJson(join(pagesDir, f))));
+  }
+  return pages;
+}
+
+/** loadSite(siteDir) -> { posts, pages } against a theme repo root. */
+export async function loadSite(siteDir, { contentDir = 'content' } = {}) {
+  const cdir = join(siteDir, contentDir);
+  const [posts, pages] = await Promise.all([loadPosts(cdir), loadPages(cdir)]);
+  return { posts, pages };
+}
+
+export { basename, STATUS };

package/src/lib/posts-format.mjs

@@ -0,0 +1,90 @@
+// src/lib/posts-format.mjs — lossless codec between a blog post's HubSpot WIRE
+// JSON and a human-readable frontmatter+body FILE.
+//
+// HubSpot stays the PRIMARY target, so this reshaping must never lose a field the
+// blog push depends on. The contract is strict: fileToWire(wireToFile(x)) deep-
+// equals x for every post in the corpus (proven by scripts/posts-roundtrip.mjs and
+// the unit test). Losslessness is by CONSTRUCTION — known fields get pretty,
+// neutral names; every other field passes through verbatim, so nothing is ever
+// silently dropped. The pretty layer is cosmetic; the passthrough layer is the
+// safety net.
+//
+// Why frontmatter: every post in the corpus is flat scalars + one array + two HTML
+// blobs, the textbook frontmatter shape. The body becomes readable HTML; the diff
+// becomes prose instead of an escaped JSON string; and Git-CMS tools (Keystatic /
+// Tina / Decap) can later edit it directly. Templates and the page format are
+// untouched — this is the light-touch slice.
+//
+// YAML note: js-yaml's DEFAULT_SCHEMA coerces ISO timestamps to Date objects, which
+// would corrupt `publishDate` on round-trip. CORE_SCHEMA has no timestamp type, so
+// every scalar stays the string it was. lineWidth:-1 disables line folding so long
+// HTML/strings survive byte-for-byte.
+
+import yaml from 'js-yaml';
+
+const SCHEMA = yaml.CORE_SCHEMA;
+const DUMP_OPTS = { schema: SCHEMA, lineWidth: -1, noRefs: true, quotingType: '"' };
+
+// Wire field -> pretty frontmatter key (bijective). `state` and `postBody` are
+// handled specially (status transform / body extraction); everything NOT listed
+// here passes through under its own wire name, so the codec can never drop a field.
+const TO_PRETTY = {
+  name: 'title',
+  authorName: 'author',
+  tagNames: 'tags',
+  featuredImageAltText: 'featuredImageAlt',
+  postSummary: 'summary',
+};
+const TO_WIRE = Object.fromEntries(Object.entries(TO_PRETTY).map(([w, p]) => [p, w]));
+
+const STATE_TO_STATUS = { PUBLISHED: 'published', DRAFT: 'draft' };
+const STATUS_TO_STATE = Object.fromEntries(Object.entries(STATE_TO_STATUS).map(([s, t]) => [t, s]));
+
+// Frontmatter key order: authored fields first (readability), passthrough/sync
+// metadata last. Keys not listed keep insertion order after these.
+const KEY_ORDER = ['title', 'htmlTitle', 'slug', 'status', 'publishDate', 'author',
+  'tags', 'featuredImage', 'featuredImageAlt', 'useFeaturedImage', 'metaDescription', 'summary'];
+
+function orderKeys(obj) {
+  const out = {};
+  for (const k of KEY_ORDER) if (k in obj) out[k] = obj[k];
+  for (const k of Object.keys(obj)) if (!(k in out)) out[k] = obj[k];
+  return out;
+}
+
+/**
+ * wireToFile(post) -> string  (frontmatter + HTML body)
+ * `postBody` becomes the body; every other field becomes frontmatter, renamed to
+ * its pretty key when one exists, otherwise passed through verbatim.
+ */
+export function wireToFile(post) {
+  const fm = {};
+  let body = '';
+  for (const [k, v] of Object.entries(post)) {
+    if (k === 'postBody') { body = v ?? ''; continue; }
+    if (k === 'state') { fm.status = STATE_TO_STATUS[v] ?? v; continue; }
+    fm[TO_PRETTY[k] ?? k] = v;
+  }
+  const front = yaml.dump(orderKeys(fm), DUMP_OPTS);
+  return `---\n${front}---\n${body}`;
+}
+
+const FENCE_RE = /^---\n([\s\S]*?)\n---\n([\s\S]*)$/;
+
+/**
+ * fileToWire(str) -> post  (inverse of wireToFile)
+ * Restores `postBody` from the body and inverts the pretty renames / status map;
+ * passthrough keys return under their original wire names unchanged.
+ */
+export function fileToWire(str) {
+  const m = FENCE_RE.exec(str);
+  if (!m) throw new Error('posts-format: missing or malformed frontmatter fence');
+  const fm = yaml.load(m[1], { schema: SCHEMA }) || {};
+  const post = {};
+  for (const [k, v] of Object.entries(fm)) {
+    if (k === 'status') { post.state = STATUS_TO_STATE[v] ?? v; continue; }
+    post[TO_WIRE[k] ?? k] = v;
+  }
+  post.postBody = m[2];
+  return post;
+}

package/src/lib/render.mjs

@@ -0,0 +1,153 @@
+// src/lib/render.mjs — HubL -> HTML rendering for the STATIC target.
+//
+// This is the deliberately HubSpot-FLAVORED part of the toolkit. HubSpot renders
+// HubL server-side; a static target (Cloudflare Pages, plain dir) has no server,
+// so the toolkit must render the same templates itself at build time. The engine
+// is Nunjucks (Jinja2-flavored, like HubL) plus a small, finite compatibility
+// layer for the handful of constructs HubL has that Nunjucks does not.
+//
+// Inputs are NEUTRAL views from lib/content-view.mjs — the renderer never reads a
+// `widgets.x.body` carrier, a field GUID, or the string "PUBLISHED". It maps the
+// neutral view onto the snake_case `content.*` variable contract the HubL
+// templates reference (HubSpot exposes its model to HubL in snake_case), and
+// shims the HubL-only globals/filters/tags.
+//
+// HubL constructs handled:
+//   - {{ get_asset_url('../css/main.css') }}  -> root-relative "/css/main.css"
+//   - {% include "../templates/shared-nav.html" %}  (path normalized in loader)
+//   - blog_recent_posts(group, n)  -> recent neutral posts as content shims
+//   - standard_header_includes / standard_footer_includes  -> injected strings
+//   - x[:2] / x[1:] / x[1:3] Python-style slices  -> |hubslice() (preprocess)
+//   - {% module %}  -> see module-tag extension (added for page rendering)
+//
+// Pure except for the loader's synchronous template file reads.
+
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import nunjucks from 'nunjucks';
+
+// ---------------------------------------------------------------------------
+// HubL -> Nunjucks source preprocessing. Applied to every template the loader
+// serves. Currently: Python/Jinja slice subscripts, which HubL supports and
+// Nunjucks does not. `name[:2]` -> `name|hubslice(0,null)`-style rewrite. Only
+// dotted identifier targets are matched (covers the corpus: author name initials).
+// ---------------------------------------------------------------------------
+const SLICE_RE = /([A-Za-z_][\w.]*)\[(\d*):(\d*)\]/g;
+
+export function preprocessHubl(src) {
+  return src.replace(SLICE_RE, (_m, expr, a, b) => {
+    const start = a === '' ? '0' : a;
+    const end = b === '' ? 'null' : b;
+    return `${expr}|hubslice(${start},${end})`;
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Loader: resolves HubSpot-style template-relative include paths against the
+// theme root and preprocesses HubL source on the way out. "../templates/x.html"
+// and "templates/x.html" both resolve to <siteDir>/templates/x.html — every
+// include in the corpus is template-relative ("../templates/..."), so stripping
+// leading ./ .. segments yields the theme-root-relative path.
+// ---------------------------------------------------------------------------
+function makeLoader(siteDir) {
+  return {
+    async: false,
+    getSource(name) {
+      const rel = name.split('/').filter((p) => p && p !== '.' && p !== '..').join('/');
+      const full = join(siteDir, rel);
+      const raw = readFileSync(full, 'utf8');
+      return { src: preprocessHubl(raw), path: full, noCache: true };
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Static ref resolution. The HubSpot target resolves @asset:/@portal to portal
+// GUIDs + hosted hubfs URLs (lib/refs.mjs); the static target resolves them to
+// local paths under the deployed site. Minimal for the spike: @asset:NAME ->
+// /assets/NAME, applied to attribute values and rich-text bodies alike.
+// ---------------------------------------------------------------------------
+export function resolveStaticRefs(value, { assetBase = '/assets' } = {}) {
+  if (value == null) return value;
+  return String(value).replace(/@asset:([^\s"'<>)]+)/g, (_m, nameRef) => `${assetBase}/${nameRef}`);
+}
+
+// get_asset_url('../css/main.css') -> "/css/main.css". Theme assets live at the
+// repo root (css/ js/ images/); HubL refs them template-relative with leading ../.
+function assetUrl(path) {
+  return '/' + String(path).replace(/^(\.\.\/)+/, '').replace(/^\/+/, '');
+}
+
+const MONTHS = ['January', 'February', 'March', 'April', 'May', 'June',
+  'July', 'August', 'September', 'October', 'November', 'December'];
+
+function localizeDate(iso) {
+  if (!iso) return '';
+  const d = new Date(iso);
+  if (Number.isNaN(d.getTime())) return '';
+  return `${MONTHS[d.getUTCMonth()]} ${d.getUTCDate()}, ${d.getUTCFullYear()}`;
+}
+
+// ---------------------------------------------------------------------------
+// Neutral post view -> HubL `content` shim (snake_case, refs resolved for the
+// static target). Reused for the page being rendered AND for related-post cards
+// returned by blog_recent_posts().
+// ---------------------------------------------------------------------------
+function postContent(post, { baseUrl = '', assetBase = '/assets' } = {}) {
+  const author = post.author || null;
+  return {
+    name: post.title,
+    html_title: post.htmlTitle,
+    meta_description: post.metaDescription,
+    post_body: resolveStaticRefs(post.body, { assetBase }),
+    post_summary: resolveStaticRefs(post.summary, { assetBase }),
+    publish_date_localized: localizeDate(post.publishDate),
+    featured_image: post.featuredImage ? resolveStaticRefs(post.featuredImage, { assetBase }) : '',
+    featured_image_alt_text: post.featuredImageAlt,
+    tag_list: post.tags.map((t) => ({ name: t })),
+    blog_post_author: author ? { display_name: author.name, bio: resolveStaticRefs(author.bio, { assetBase }) } : null,
+    absolute_url: baseUrl + post.route,
+    canonical_url: baseUrl + post.route,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Environment factory. One env per render call keeps globals (blog_recent_posts
+// closure, header/footer includes) bound to the current site + options.
+// ---------------------------------------------------------------------------
+function makeEnv(siteDir, { site, opts }) {
+  const env = new nunjucks.Environment(makeLoader(siteDir), { autoescape: false, throwOnUndefined: false });
+
+  env.addFilter('hubslice', (str, start, end) =>
+    end === null || end === undefined ? String(str ?? '').slice(start) : String(str ?? '').slice(start, end));
+
+  env.addGlobal('get_asset_url', assetUrl);
+  env.addGlobal('html_lang', opts.lang || 'en');
+  env.addGlobal('html_lang_dir', '');
+  env.addGlobal('standard_header_includes', opts.headerIncludes || '');
+  env.addGlobal('standard_footer_includes', opts.footerIncludes || '');
+
+  // blog_recent_posts('default', n) — HubL's recent-posts query. Backed by the
+  // build-time neutral corpus, newest-first, projected to content shims.
+  env.addGlobal('blog_recent_posts', (_group, count) =>
+    (site?.posts || []).slice(0, count || 5).map((p) => postContent(p, opts)));
+
+  return env;
+}
+
+// ---------------------------------------------------------------------------
+// Public: render one neutral post view to an HTML string.
+// ---------------------------------------------------------------------------
+export function renderPost(post, { siteDir, site, baseUrl = '', assetBase = '/assets', lang = 'en',
+  headerIncludes = '', footerIncludes = '', template = 'templates/blog-post.html' } = {}) {
+  const opts = { baseUrl, assetBase, lang, headerIncludes, footerIncludes };
+  const env = makeEnv(siteDir, { site, opts });
+  const context = {
+    content: postContent(post, opts),
+    nav_active: null,
+    nav_hide_cta: false,
+  };
+  return env.render(template, context);
+}
+
+export { postContent, assetUrl, localizeDate, makeEnv };

package/src/preflight.mjs

@@ -86,6 +86,62 @@ export function manifestBlogSlug(repoRoot = REPO_ROOT) {
   return DEFAULT_BLOG_SLUG;
 }
 
+function readJsonIfPresent(path) {
+  if (!existsSync(path)) return null;
+  try {
+    return JSON.parse(readFileSync(path, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+function containerFileFor(slug) {
+  if (slug === 'blog' || !slug) return 'container.json';
+  return `container.${String(slug).replace(/\//g, '__')}.json`;
+}
+
+function pointsAtTheme(path, themeName) {
+  const p = String(path || '');
+  return p.includes(`${themeName}/`) || p.includes(`${themeName}\\`);
+}
+
+/**
+ * Inspect the local repo to decide which portal drift can be repaired by a
+ * normal push. This never claims HubSpot-created prerequisites are repairable:
+ * the blog container itself, service-key scopes, and domain connection remain
+ * external setup.
+ */
+export function sourceRepairability(repoRoot = REPO_ROOT, opts = {}) {
+  const themeName = opts.themeName ?? THEME_NAME;
+  const blogSlug = opts.blogSlug ?? manifestBlogSlug(repoRoot);
+  const contentDir = opts.contentDirPath || join(repoRoot, 'content');
+  const manifestPath = opts.manifestFilePath || join(repoRoot, 'site.manifest.json');
+
+  const container = readJsonIfPresent(join(contentDir, 'blog', containerFileFor(blogSlug)));
+  const itemTemplate = container?.itemTemplatePath || opts.blogItemTemplate || '';
+  const listingTemplate = container?.listingTemplatePath || opts.blogListingTemplate || '';
+  const blogTemplates =
+    !!container &&
+    String(container.slug ?? blogSlug) === String(blogSlug) &&
+    pointsAtTheme(itemTemplate, themeName) &&
+    pointsAtTheme(listingTemplate, themeName);
+
+  const manifest = readJsonIfPresent(manifestPath);
+  const rootEntry = (manifest?.pages || []).find((p) => String(p?.slug ?? '') === '');
+  const home = readJsonIfPresent(join(contentDir, 'pages', 'home.json'));
+  const manifestPublishesRoot = !!rootEntry && (rootEntry.desiredState || 'publish') === 'publish';
+  const homePublishesRoot =
+    !!home &&
+    String(home.slug ?? '') === '' &&
+    (home.desiredState || rootEntry?.desiredState || 'publish') === 'publish' &&
+    !!home.templatePath;
+
+  return {
+    blogTemplates,
+    homepage: manifestPublishesRoot && homePublishesRoot,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // gatherProbes(acct, { blogSlug, hub, getAll, resolveBlogBySlug, resolvePageBySlug })
 //   -> probes object consumed by evaluateReadiness.
@@ -181,6 +237,8 @@ export async function gatherProbes(acct, opts = {}) {
 export function evaluateReadiness(probes, opts = {}) {
   const blogSlug = opts.blogSlug ?? probes.blogSlug ?? DEFAULT_BLOG_SLUG;
   const themeName = opts.themeName ?? THEME_NAME;
+  const allowRepairable = !!opts.allowRepairable;
+  const repairable = opts.repairable || {};
   const checks = [];
 
   const add = (c) => checks.push({ reportOnly: false, ...c });
@@ -212,11 +270,22 @@ export function evaluateReadiness(probes, opts = {}) {
     // Container exists — confirm it points at the theme's blog templates.
     const item = blog.itemTemplatePath || '';
     const listing = blog.listingTemplatePath || '';
-    const pointsAtTheme = (p) => p.includes(`${themeName}/`) || p.includes(`${themeName}\\`);
-    const itemOk = pointsAtTheme(item);
-    const listingOk = pointsAtTheme(listing);
+    const itemOk = pointsAtTheme(item, themeName);
+    const listingOk = pointsAtTheme(listing, themeName);
     if (itemOk && listingOk) {
       add({ id: 'blog-container', ok: true, detail: `blog "${blogSlug}" exists and uses ${themeName} templates` });
+    } else if (allowRepairable && repairable.blogTemplates) {
+      const wrong = [];
+      if (!itemOk) wrong.push(`post/item template "${item || '(unset)'}"`);
+      if (!listingOk) wrong.push(`listing template "${listing || '(unset)'}"`);
+      add({
+        id: 'blog-templates',
+        ok: true,
+        repairable: true,
+        detail:
+          `blog "${blogSlug}" exists but ${wrong.join(' and ')} not under ${themeName}; ` +
+          `source push will set the committed blog templates`,
+      });
     } else {
       const wrong = [];
       if (!itemOk) wrong.push(`post/item template "${item || '(unset)'}"`);
@@ -241,6 +310,13 @@ export function evaluateReadiness(probes, opts = {}) {
       detail: `cannot list site pages (HTTP ${homepage.status}${homepage.message ? `: ${homepage.message}` : ''})`,
       remediation: `Grant the service key the "content" scope so the homepage can be confirmed.`,
     });
+  } else if (!homepage.found && allowRepairable && repairable.homepage) {
+    add({
+      id: 'homepage',
+      ok: true,
+      repairable: true,
+      detail: `no site page resolves at the root slug ''; source push will create and publish the committed root page`,
+    });
   } else if (!homepage.found) {
     add({
       id: 'homepage',
@@ -320,7 +396,7 @@ export function renderReport(evald, { account: acctName, portalId, blogSlug } =
   const lines = [];
   lines.push(`Bootstrap preflight — account "${acctName}" (portal ${portalId}), blog slug "${blogSlug}"`);
   for (const c of evald.checks) {
-    const mark = c.ok ? 'PASS' : c.reportOnly ? 'NOTE' : 'FAIL';
+    const mark = c.repairable ? 'WARN' : c.ok ? 'PASS' : c.reportOnly ? 'NOTE' : 'FAIL';
     lines.push(`  [${mark}] ${c.id}: ${c.detail}`);
     if (!c.ok && c.remediation) lines.push(`         -> ${c.remediation}`);
   }
@@ -338,9 +414,11 @@ export function renderReport(evald, { account: acctName, portalId, blogSlug } =
 // ---------------------------------------------------------------------------
 export async function main(argv = process.argv.slice(2), opts = {}) {
   const { config } = opts;
-  const acctName = argv[0];
+  const allowRepairable = argv.includes('--allow-repairable');
+  const args = argv.filter((a) => a !== '--allow-repairable');
+  const acctName = args[0];
   if (!acctName) {
-    process.stderr.write('usage: node sync/preflight.mjs <account>\n');
+    process.stderr.write('usage: node sync/preflight.mjs <account> [--allow-repairable]\n');
     return 2;
   }
 
@@ -371,7 +449,18 @@ export async function main(argv = process.argv.slice(2), opts = {}) {
     return 1;
   }
 
-  const evald = evaluateReadiness(probes, { blogSlug, themeName: config?.theme?.name || THEME_NAME });
+  const themeName = config?.theme?.name || THEME_NAME;
+  const repairable = allowRepairable
+    ? sourceRepairability(config?.root || REPO_ROOT, {
+        blogSlug,
+        themeName,
+        contentDirPath: config?.contentDirPath,
+        manifestFilePath: config?.manifestFilePath,
+        blogItemTemplate: config?.blog?.itemTemplate,
+        blogListingTemplate: config?.blog?.listingTemplate,
+      })
+    : {};
+  const evald = evaluateReadiness(probes, { blogSlug, themeName, allowRepairable, repairable });
   const report = renderReport(evald, { account: acctName, portalId: acct.portalId, blogSlug });
   process.stdout.write(report + '\n');
   return evald.ready ? 0 : 1;
@@ -382,4 +471,4 @@ if (import.meta.url === `file://${process.argv[1]}`) {
   main().then((code) => process.exit(code));
 }
 
-export default { main, gatherProbes, evaluateReadiness, manifestBlogSlug, renderReport };
+export default { main, gatherProbes, evaluateReadiness, manifestBlogSlug, sourceRepairability, renderReport };