hubspot-cms-sync 0.1.0 → 0.3.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026
+Copyright (c) 2026 Seventh Sense
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -3,10 +3,16 @@
 Git-backed bidirectional HubSpot CMS sync for themes, site pages, page module
 content, blogs, forms, and assets.
 
-The package provides the `hubspot-cms-sync` CLI plus the short `hcms` alias.
-It reads account and site settings from `hubspot-cms-sync.config.mjs`, stores
-per-account identity in a gitignored `.sync-state/` directory, and refuses to
-push to configured read-only portal ids.
+The package provides the `hcms` CLI. The long binary name
+`hubspot-cms-sync` is also installed, but examples use `hcms` for consistency.
+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
 
@@ -24,21 +30,55 @@ npm install --save-dev ../hubspot-cms-sync
 
 ```bash
 hcms doctor
-hubspot-cms-sync pull prod
-hubspot-cms-sync preflight dev
-hubspot-cms-sync push dev --publish
+hcms pull dev
+hcms preflight dev
 hcms push dev --dry-run
-hubspot-cms-sync republish dev --all --blog
-hubspot-cms-sync corpus
+hcms push dev --publish
+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 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.
+
 ## Configuration
 
 Copy `examples/hubspot-cms-sync.config.mjs` into the consuming repo, then set
-the theme name, manifest path, read-only portal ids, and account registry path.
-Account keys live outside git at `$HUBSPOT_KEY_DIR/<portalId>.key` or
-`~/.hubspot/<portalId>.key`.
+the theme name, manifest path, redirect spec path, read-only portal ids, and
+account registry path. Account keys live outside git at
+`$HUBSPOT_KEY_DIR/<portalId>.key` or `~/.hubspot/<portalId>.key`.
+
+```js
+export default {
+  accountsFile: 'sync/accounts.json',
+  contentDir: 'content',
+  manifestPath: 'site.manifest.json',
+  redirectsFile: 'content/redirects.csv',
+  readOnlyPortalIds: ['529456'],
+  theme: {
+    name: 'seventh-sense-theme',
+    dirs: ['templates', 'modules', 'css', 'js', 'images'],
+    files: ['theme.json', 'fields.json']
+  }
+};
+```
+
+CSV redirects need at least these columns:
+
+```csv
+routePrefix,destination,redirectStyle
+/old-page,/new-page,301
+```
+
+Optional columns accepted by the HubSpot URL Redirects API include
+`isOnlyAfterNotFound`, `isMatchFullUrl`, `isMatchQueryString`, `isPattern`,
+`isProtocolAgnostic`, `isTrailingSlashOptional`, and `precedence`.
 
 ## Tests
 

package/bin/hubspot-cms-sync.mjs

@@ -1,39 +1,15 @@
 #!/usr/bin/env node
 
 import { spawn } from 'node:child_process';
+import { Command } from 'commander';
+
 import { loadConfig } from '../src/config.mjs';
 import { pull } from '../src/pull.mjs';
-import { push } from '../src/push.mjs';
+import { push, preflightRefs } from '../src/push.mjs';
 import { main as preflightMain } from '../src/preflight.mjs';
 import { main as republishMain } from '../src/republish.mjs';
 import { main as manifestMain } from '../src/manifest.mjs';
-
-function usage() {
-  console.log(`usage: hcms [--root <path>] <command> [args]
-
-commands:
-  pull <account>
-  push <account> [--publish] [--dry-run]
-  preflight <account>
-  republish <account|portalId> [--all] [--blog] [slugs...]
-  corpus [paths...]
-  manifest [args...]
-  doctor
-`);
-}
-
-function parseGlobal(argv) {
-  const out = { root: process.cwd(), args: [] };
-  for (let i = 0; i < argv.length; i += 1) {
-    const a = argv[i];
-    if (a === '--root') {
-      out.root = argv[++i];
-    } else {
-      out.args.push(a);
-    }
-  }
-  return out;
-}
+import { renderRedirectReport, syncRedirects } from '../src/redirects.mjs';
 
 function runNodeScript(script, args, { cwd }) {
   return new Promise((resolve) => {
@@ -42,74 +18,127 @@ function runNodeScript(script, args, { cwd }) {
   });
 }
 
-async function main(argv = process.argv.slice(2)) {
-  const { root, args } = parseGlobal(argv);
-  const [cmd, ...rest] = args;
-  if (!cmd || cmd === '-h' || cmd === '--help') {
-    usage();
-    return cmd ? 0 : 2;
-  }
-
-  const config = await loadConfig({ root });
-
-  if (cmd === 'doctor') {
-    console.log(`root: ${config.root}`);
-    console.log(`accounts: ${config.accountsPath}`);
-    console.log(`content: ${config.contentDirPath}`);
-    console.log(`manifest: ${config.manifestFilePath}`);
-    console.log(`sync state: ${config.syncStateDirPath}`);
-    console.log(`theme: ${config.theme.name}`);
-    return 0;
-  }
-
-  if (cmd === 'pull') {
-    const account = rest[0];
-    if (!account) throw new Error('pull requires <account>');
-    await pull(account, { config });
-    return 0;
-  }
-
-  if (cmd === 'push') {
-    const publish = rest.includes('--publish');
-    const dryRun = rest.includes('--dry-run');
-    const account = rest.find((a) => !a.startsWith('--'));
-    if (!account) throw new Error('push requires <account>');
-    if (dryRun) {
-      // Current engine preflight is the no-write plan surface. A future plan command
-      // can add per-adapter write summaries.
-      const { preflightRefs } = await import('../src/push.mjs');
-      preflightRefs(config.contentDirPath);
-      console.log(`dry-run push preflight passed for ${account}`);
-      return 0;
-    }
-    await push(account, { publish, config });
-    return 0;
-  }
-
-  if (cmd === 'preflight') {
-    return preflightMain(rest, { config });
-  }
-
-  if (cmd === 'republish') {
-    return republishMain(rest, { config });
-  }
-
-  if (cmd === 'manifest') {
-    return manifestMain(rest, { config });
-  }
-
-  if (cmd === 'corpus') {
-    const script = new URL('../src/corpus-scan.mjs', import.meta.url).pathname;
-    return runNodeScript(script, rest, { cwd: config.root });
-  }
-
-  usage();
-  return 2;
+async function withConfig(opts) {
+  return loadConfig({ root: opts.root });
+}
+
+async function main(argv = process.argv) {
+  const program = new Command();
+
+  program
+    .name('hcms')
+    .description('Git-backed HubSpot CMS sync')
+    .option('--root <path>', 'repo root', process.cwd())
+    .showHelpAfterError();
+
+  program
+    .command('doctor')
+    .description('print resolved configuration')
+    .action(async () => {
+      const config = await withConfig(program.opts());
+      console.log(`root: ${config.root}`);
+      console.log(`accounts: ${config.accountsPath}`);
+      console.log(`content: ${config.contentDirPath}`);
+      console.log(`manifest: ${config.manifestFilePath}`);
+      console.log(`redirects: ${config.redirectsFilePath || '(none)'}`);
+      console.log(`sync state: ${config.syncStateDirPath}`);
+      console.log(`theme: ${config.theme.name}`);
+    });
+
+  program
+    .command('pull')
+    .description('pull HubSpot content into the repo')
+    .argument('<account>')
+    .action(async (account) => {
+      const config = await withConfig(program.opts());
+      await pull(account, { config });
+    });
+
+  program
+    .command('push')
+    .description('push repo content to HubSpot')
+    .argument('<account>')
+    .option('--publish', 'publish/schedule pushed content')
+    .option('--dry-run', 'run local push preflight only')
+    .action(async (account, options) => {
+      const config = await withConfig(program.opts());
+      if (options.dryRun) {
+        preflightRefs(config.contentDirPath);
+        console.log(`dry-run push preflight passed for ${account}`);
+        return;
+      }
+      await push(account, { publish: !!options.publish, config });
+    });
+
+  program
+    .command('preflight')
+    .description('check account readiness before a push')
+    .argument('<account>')
+    .option('--allow-repairable', 'allow source-repairable portal drift before the push')
+    .action(async (account, options) => {
+      const config = await withConfig(program.opts());
+      const args = [account];
+      if (options.allowRepairable) args.push('--allow-repairable');
+      const code = await preflightMain(args, { config });
+      if (code) process.exitCode = code;
+    });
+
+  program
+    .command('redirects')
+    .description('plan or apply managed URL redirects')
+    .argument('<account>')
+    .option('--file <path>', 'redirect spec CSV or JSON; defaults to config.redirectsFile')
+    .option('--apply', 'write creates/updates to HubSpot')
+    .action(async (account, options) => {
+      const config = await withConfig(program.opts());
+      const result = await syncRedirects(account, {
+        file: options.file,
+        apply: !!options.apply,
+        config,
+      });
+      console.log(renderRedirectReport(result));
+    });
+
+  program
+    .command('republish')
+    .description('republish live pages and/or blog posts')
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .argument('[args...]')
+    .action(async (args) => {
+      const config = await withConfig(program.opts());
+      const code = await republishMain(args, { config });
+      if (code) process.exitCode = code;
+    });
+
+  program
+    .command('corpus')
+    .description('scan repo content for unsafe refs and HubSpot artifacts')
+    .allowUnknownOption()
+    .argument('[paths...]')
+    .action(async (paths) => {
+      const config = await withConfig(program.opts());
+      const script = new URL('../src/corpus-scan.mjs', import.meta.url).pathname;
+      const code = await runNodeScript(script, paths, { cwd: config.root });
+      if (code) process.exitCode = code;
+    });
+
+  program
+    .command('manifest')
+    .description('manifest utilities')
+    .allowUnknownOption()
+    .allowExcessArguments()
+    .argument('[args...]')
+    .action(async (args) => {
+      const config = await withConfig(program.opts());
+      const code = await manifestMain(args, { config });
+      if (code) process.exitCode = code;
+    });
+
+  await program.parseAsync(argv);
 }
 
-main().then((code) => {
-  process.exitCode = code;
-}).catch((e) => {
+main().catch((e) => {
   console.error(`hcms failed: ${e.message}`);
   process.exitCode = 1;
 });

package/docs/CONFIGURATION.md

@@ -12,6 +12,7 @@ export default {
   contentDir: 'content',
   syncStateDir: '.sync-state',
   manifestPath: 'site.manifest.json',
+  redirectsFile: 'content/redirects.csv',
   readOnlyPortalIds: ['529456'],
   knownPortalIds: ['529456', '246389711'],
   assetHosts: {
@@ -63,8 +64,12 @@ export default {
 - The config loader validates shape and prints remediation, not stack traces.
 - `site.manifest.json` remains the deploy surface for content, pages, forms, and
   blog.
+- Repo-stored redirects are a separate deploy surface. `redirectsFile` points to
+  a CSV or JSON spec consumed by `hcms redirects <account> [--apply]`.
 - `hubspot-cms-sync.config.mjs` controls environment policy and filesystem
   layout.
+- Managed redirects default to `isOnlyAfterNotFound: false`, so a release can
+  intentionally redirect an old live page path without a manual archive step.
 
 ## Open Config Questions
 

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/docs/HUBSPOT-SYNC-NOTES.md

@@ -0,0 +1,123 @@
+# HubSpot Sync — Gotchas & Operational Notes
+
+_HubSpot CMS API gotchas hit while building the [seventh-sense](https://github.com/telepathdata/7thsense-website) reference site with this engine. Examples reference that site; the behaviors are general._
+
+Hard-won notes from migrating the Seventh Sense site/blog onto a CMS sandbox.
+**Read this before pointing `sync/*` at production.** Every item here cost real
+debugging time; they are the difference between a sync script that works and one
+that silently does the wrong thing.
+
+---
+
+## 1. Credentials & scopes — the #1 time sink
+
+There are three credential types and they are **not** interchangeable:
+
+| Type | Looks like | Use it for | Gotcha |
+|---|---|---|---|
+| **Personal Access Key (PAK)** | `CiRu…` (base64) or surfaced as a long token | the `hs` CLI (theme upload) | **Cannot grant the `content` scope** — so PAKs *cannot* create CMS pages/blog posts. PAK scopes are also **immutable**: "editing" = generating a new key. |
+| **Service Key** (BETA) | `pat-na2-…` | our `sync/*` scripts (direct Bearer) | **Editable** scopes (no regen), but scope changes have **propagation lag** (~30–60s) — a call can still 401 right after you save. Retry before assuming failure. |
+| **Private App token** | `pat-na1-…` | alternative to service key | Also grants `content`; heavier to manage. |
+
+- Use service keys as `Authorization: Bearer <key>` directly — **no exchange**. (A `CiRu…` value is a PAK refresh token; it 401s as a Bearer and must be exchanged at `POST /localdevauth/v1/auth/refresh`.)
+- **Read vs write are separate scopes.** `crm.schemas.contacts.write` does **not** include `.read`. The forms adapter must work write-only, so it create-or-patches instead of relying on list-then-decide behavior. Design sync scripts to not *require* the read scope.
+- Per-operation scopes we actually needed:
+  - Pages create/publish: **`content`**
+  - Blog posts create/publish: **`content`**
+  - File Manager (image re-host / recovery): **`files`**
+  - Create HubSpot forms: **`forms`** (`forms-write`)
+  - Create/patch custom contact properties: **`crm.schemas.contacts.write`**
+  - Domains / business-units reads: a domains scope we never got on the sandbox key (blog-create needs it; see §4).
+
+## 2. Account types — not all can host content
+
+- **`DEVELOPER_TEST`** accounts (created from an app-developer account) include Design Manager (theme dev) but **cannot host CMS pages** — the `content`/`cms.pages.site_pages.write` scope is not grantable. Theme upload works, page creation never will.
+- A **free CMS Developer Sandbox** (`accountType: STANDARD`, signup at `app.hubspot.com/signup-hubspot/cms-developers`) **can** host pages/blog. This is the right target for a staging mirror.
+- Check `accountType` (via the PAK token exchange response `accountType`, or `/account-info/v3/details`) before assuming a portal can take content.
+
+## 3. Publishing — the two big quirks
+
+- **`POST …/draft/push-live` silently no-ops on first publish.** It returns `204` but the content stays `DRAFT`. **Use the schedule endpoint with a near-future date instead:**
+  `POST /cms/v3/pages/site-pages/schedule` (and `/cms/v3/blogs/posts/schedule`) with `{"id", "publishDate": <now + 90s>}`. It fires ~75–90s later and the page goes live.
+- **`publishDate` must be in the future** — "now" is rejected with `publishDate must be in the future`.
+- **Pages/posts require a non-empty title** to publish (`CONTENT_TITLE_MISSING`). Set `htmlTitle`/`name` before scheduling.
+- **Template changes do not re-render already-published content.** After editing a template, you must **re-publish every affected page/post** (schedule them again) to pick up the new template. This is why a dynamic blog-post template still showed old hardcoded content until all 68 posts were re-scheduled.
+- **⚠️ Re-scheduling a post resets its `publishDate` to the scheduled time** — bulk re-scheduling 68 posts clobbered their original 2017–2026 dates to "today," wrecking chronological order. Fix: `PATCH /cms/v3/blogs/posts/{id}` with the original `publishDate` (keeps it `PUBLISHED`, restores the date). The blog adapter always sends `publishDate` from the snapshot so a re-push restores dates.
+- **Invalidate a cached *blog listing*** by re-PUTting the blog (`PUT /content/api/v2/blogs/{id}`) — that flips the edge-cache tag from the old listing page (`CT-…`) to the blog (`B-…`) and serves the current `listing_template_path`.
+- **Edge cache is aggressive:** blog listing/pages serve with `s-maxage=36000` (10h). Cache-busting query params do **not** bypass it. Publishing invalidates by `edge-cache-tag`; otherwise expect lag.
+
+## 4. Blog specifics
+
+- **Creating a blog is UI-gated.** `POST /content/api/v2/blogs` fails with `BLOG_HS_SITE_DOMAIN_WRITE_SCOPE_MISSING` ("publish blog on domain ''") even with `content` + a domain in the body — binding a blog to the `hs-sites` system domain needs UI-level permission a service key can't get. **Create the blog once in Settings → Website → Blog**, then automate everything else.
+- **Updating a blog DOES work via API:** `PUT /content/api/v2/blogs/{id}` — use it to fix `slug`, `item_template_path`, `listing_template_path` after the UI creates it with wrong defaults (it defaults to `@hubspot/elevate` templates and a `seventh-sense-blog` slug).
+- **`listing_page_id` overrides `listing_template_path`.** A blog auto-creates a listing *page* that renders `/blog` with its own (default) template, ignoring `listing_template_path`. That listing page is **not** reachable via the site-pages or legacy-pages API (404). **Fix that worked:** `PUT /content/api/v2/blogs/{id}` with `{"listing_page_id": 0}` to clear the override, then re-PUT the blog to bust the edge cache → `/blog` then renders `listing_template_path`.
+- **Post slugs are full paths** (e.g. `blog/spf-dkim-…`), not relative to the blog root. Push them as-is.
+- The legacy CMS blogs API can have a **stale "Old" blog** + many `DRAFT`/`SCHEDULED`/`-temporary-slug-` junk posts. Filter to `state == PUBLISHED`, non-`Old` blog, real slug, body length > 500 before migrating (see `blog-sync` pruning).
+
+## 5. Images & File Manager
+
+- Blog bodies reference images on **legacy hosts** (`cdn2.hubspot.net`, `f.hubspotusercontent00.net`) whose public URLs are often **404 / dead** — these images were deleted years ago and 404 on the live prod blog too. Don't expect 100% recovery (we got 50/172).
+- Recover what's live via the current host; for dead URLs, fall back to **File Manager search** (`GET /files/v3/files/search?name=<stem>`) — needs the **`files`** scope.
+- On push, **re-host** each image to the target File Manager (`POST /files/v3/files`, multipart, `options.access=PUBLIC_INDEXABLE`) and **rewrite** body/featured URLs to the new hosted URL. Never leave prod hotlinks.
+
+## 6. Forms
+
+- All redesign forms shipped as **static mockups** (`onsubmit="preventDefault(); alert(...)"`). Fix = keep the styled markup, POST to the **Forms Submission API**: `POST https://api.hsforms.com/submissions/v3/integration/submit/{portalId}/{formGuid}` (shared `js/hs-forms.js`). Don't use `{% form %}` embeds — they replace the custom design.
+- **The submission API enforces the form's `required` fields.** A lighter entry point (e.g. the audit-cta email-only form) submitting to a fuller form gets `REQUIRED_FIELD` errors. Pattern: make forms **email-only-required at the API layer**, enforce richer UX with per-page HTML5 `required`. One form can then back multiple entry points.
+- Custom fields must exist as **contact properties** first, and be on the form. The forms adapter upserts both.
+
+## 7. Module fields & repeater defaults (refactor blocker)
+
+- A field's **`name` cannot be a reserved word**: `name`, `label`, `id`, `type`, `body`, `children`, `default`, `required`, `locked`, etc. Upload fails with `field name cannot be 'X'`. Rename (e.g. `label`→`caption`, `name`→`title`, `body`→`body_html`) and update the `{{ item.X }}` HubL refs.
+- **Theme deploys are per-file (Source Code API PUT), not transactional across files** — a mid-deploy failure (e.g. a bad field name) leaves some module files updated and others not, so a republish renders a *mixed/broken* page. Always re-run `sync:push` to completion (and re-verify fidelity) after fixing.
+- **⚠️ HubSpot does NOT render repeater (group + `occurrence`) field DEFAULTS for `{% module %}` instances in coded templates** — neither for existing pages nor newly-created ones. Simple field defaults (text/richtext) render; **repeater loops come up empty**, so a page that relied on the repeater default loses all its repeated content (stats, cards, FAQ, pricing rows). This broke home-page fidelity in the Phase-2 module refactor.
+  - **Fixes:** (a) write the content as **field VALUES on the page instance** via the Pages API `widgets` map (the correct content/theme model — content lives on the page, template is generic); or (b) pass the content as **template-level tag params** `{% module "x" path=… group=[{…}] %}` (HubSpot honors these at render, unlike `fields.json` repeater defaults); or (c) a conditional `{% if module.items %}…{% else %}<orig>{% endif %}` fallback. Do **not** rely on repeater `default` arrays alone.
+  - **⚠️ Tag-param serialization (b) only works for SIMPLE content.** It worked for `big-stats` (`stats=[{"num":"+44%","caption":"…"}]`) but **broke for rich content** — repeater items containing inline SVG (`width="24"`) or quoted phrases (`"who's getting what"`) fail HubL param parsing (`Error parsing … encountered '24'`), because HubL string quoting in tag params doesn't cleanly accept JSON-escaped `\"`/apostrophes. **For rich/HTML repeater content, use the `widgets` API (page-instance JSON values), not tag params.** Pattern A is fine for plain-text repeaters; the `widgets` API is the universal path.
+
+## 8. Transport / tooling environment
+
+- **No CLI.** The entire sync runs on the HubSpot REST API via `fetch` with a service-key Bearer token (`~/.hubspot/<portalId>.key`). The theme uses the **CMS Source Code v3 API** (`GET/PUT /cms/v3/source-code/published/{metadata,content}/<theme>/<path>`); pages/blog/forms/content use their respective v3 APIs.
+- We previously used the `hs` CLI for theme pull/push and **dropped it**: the whole-tree `hs cms upload` silently no-op'd (it mis-named the theme after the build dir), the per-dir form was unreliable, and the CLI dragged in `rollup` (which periodically broke on the npm optional-dependency bug). The per-file Source Code API PUT is deterministic and idempotent (create-or-replace by path).
+- The CLI had **no page/blog content commands** anyway — content was always API-only; `hs cms` only managed theme assets. So every adapter is now uniform: one transport, one auth model.
+
+## 9. Operational checklist for the unified sync
+
+Production is currently read-only. The supported deployment target is the dev
+sandbox `246389711`; the production portal `529456` is hard-blocked in `hcms push`.
+
+1. Create service keys with the needed scopes:
+   - Prod pull key at `~/.hubspot/529456.key` (`content` plus read scopes needed for the resources you pull).
+   - Dev push key at `~/.hubspot/246389711.key` (`content`, `files`, `forms`, `crm.schemas.contacts.write`).
+2. Confirm the target portal can host CMS content (§2).
+3. Create the UI-gated resources once (§4): blog container, homepage designation,
+   domain setup, theme setting values, and native menus.
+4. Pull production into git:
+   ```sh
+   hcms pull -- prod
+   ```
+5. Review the diff and prove portability:
+   ```sh
+   git diff
+   hcms corpus
+   ```
+6. Preflight the dev sandbox:
+   ```sh
+   hcms preflight -- dev
+   ```
+7. Push and publish to dev:
+   ```sh
+   hcms push -- dev --publish
+   ```
+8. Re-publish live pages/posts after template changes (§3):
+   ```sh
+   hcms republish --portal 246389711 --all
+   hcms republish --portal 246389711 --all --blog
+   ```
+9. Verify the rendered site:
+   ```sh
+   npm test
+   ```
+
+For the complete operator flow and GitHub Actions deployment path, use
+[`sync-runbook.md`](./sync-runbook.md). For the architectural rationale, use
+[`deployment-architecture.md`](./deployment-architecture.md).

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

@@ -4,6 +4,7 @@ export default {
   contentDir: 'content',
   syncStateDir: '.sync-state',
   manifestPath: 'site.manifest.json',
+  redirectsFile: 'content/redirects.csv',
   readOnlyPortalIds: [],
   knownPortalIds: [],
   assetHosts: {

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>