hubspot-cms-sync 0.1.0 → 0.2.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,11 @@
 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.
 
 ## Install
 
@@ -24,21 +25,54 @@ 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 --file content/redirects.csv
+hcms redirects dev --file content/redirects.csv --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
+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,124 @@ 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>')
+    .action(async (account) => {
+      const config = await withConfig(program.opts());
+      const code = await preflightMain([account], { 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/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/package.json

@@ -1,16 +1,24 @@
 {
   "name": "hubspot-cms-sync",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Git-backed bidirectional sync for HubSpot CMS themes, content, blogs, forms, and assets.",
   "type": "module",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/7thsense/hubspot-cms-sync.git"
+  },
+  "bugs": {
+    "url": "https://github.com/7thsense/hubspot-cms-sync/issues"
+  },
+  "homepage": "https://github.com/7thsense/hubspot-cms-sync#readme",
   "engines": {
     "node": ">=20.10.0",
     "npm": ">=10"
   },
   "bin": {
-    "hubspot-cms-sync": "./bin/hubspot-cms-sync.mjs",
-    "hcms": "./bin/hubspot-cms-sync.mjs"
+    "hubspot-cms-sync": "bin/hubspot-cms-sync.mjs",
+    "hcms": "bin/hubspot-cms-sync.mjs"
   },
   "exports": {
     ".": "./src/index.mjs",
@@ -18,6 +26,7 @@
     "./lib/*": "./src/lib/*.mjs",
     "./manifest": "./src/manifest.mjs",
     "./preflight": "./src/preflight.mjs",
+    "./redirects": "./src/redirects.mjs",
     "./cta-inventory": "./src/cta-inventory.mjs",
     "./corpus-scan": "./src/corpus-scan.mjs"
   },
@@ -37,5 +46,8 @@
     "lint": "node --check bin/hubspot-cms-sync.mjs && node bin/hubspot-cms-sync.mjs --help >/dev/null",
     "prepare": "npm run lint",
     "prepublishOnly": "npm test && npm run lint && npm pack --dry-run"
+  },
+  "dependencies": {
+    "commander": "^14.0.3"
   }
 }

package/src/config.mjs

@@ -14,6 +14,7 @@ export function defaultConfig(root = process.cwd()) {
     contentDir: 'content',
     syncStateDir: '.sync-state',
     manifestPath: 'site.manifest.json',
+    redirectsFile: null,
     readOnlyPortalIds: [],
     knownPortalIds: [],
     assetHosts: {
@@ -67,6 +68,7 @@ export function resolveConfigPaths(cfg) {
     contentDirPath: abs(cfg.contentDir),
     syncStateDirPath: abs(cfg.syncStateDir),
     manifestFilePath: abs(cfg.manifestPath),
+    redirectsFilePath: cfg.redirectsFile ? abs(cfg.redirectsFile) : null,
   };
 }
 
@@ -94,6 +96,9 @@ export function validateConfig(cfg) {
   if (!cfg.contentDir) errors.push('missing contentDir');
   if (!cfg.syncStateDir) errors.push('missing syncStateDir');
   if (!cfg.manifestPath) errors.push('missing manifestPath');
+  if (cfg.redirectsFile != null && typeof cfg.redirectsFile !== 'string') {
+    errors.push('redirectsFile must be a string when set');
+  }
   if (!Array.isArray(cfg.readOnlyPortalIds)) errors.push('readOnlyPortalIds must be an array');
   if (!Array.isArray(cfg.knownPortalIds)) errors.push('knownPortalIds must be an array');
   if (!cfg.theme?.name) errors.push('theme.name is required');

package/src/index.mjs

@@ -1,3 +1,4 @@
 export { loadConfig } from './config.mjs';
 export { pull } from './pull.mjs';
 export { push, preflightRefs } from './push.mjs';
+export { syncRedirects, planRedirects, parseRedirectCsv } from './redirects.mjs';

package/src/redirects.mjs

@@ -0,0 +1,283 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+
+import { account as realAccount, getAll as realGetAll, hub as realHub } from './lib/hub.mjs';
+import { READ_ONLY_PORTAL } from './push.mjs';
+
+const REQUIRED_FIELDS = ['routePrefix', 'destination'];
+const BOOLEAN_FIELDS = [
+  'isMatchFullUrl',
+  'isMatchQueryString',
+  'isOnlyAfterNotFound',
+  'isPattern',
+  'isProtocolAgnostic',
+  'isTrailingSlashOptional',
+];
+const INTEGER_FIELDS = ['redirectStyle', 'precedence'];
+
+function parseBool(value, field, rowNumber) {
+  const raw = String(value).trim().toLowerCase();
+  if (raw === 'true' || raw === '1' || raw === 'yes') return true;
+  if (raw === 'false' || raw === '0' || raw === 'no') return false;
+  throw new Error(`redirects row ${rowNumber}: ${field} must be true/false`);
+}
+
+function parseInteger(value, field, rowNumber) {
+  const n = Number.parseInt(String(value).trim(), 10);
+  if (!Number.isFinite(n)) throw new Error(`redirects row ${rowNumber}: ${field} must be an integer`);
+  return n;
+}
+
+export function parseCsv(text) {
+  const rows = [];
+  let row = [];
+  let field = '';
+  let inQuote = false;
+
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text[i];
+    if (inQuote) {
+      if (ch === '"' && text[i + 1] === '"') {
+        field += '"';
+        i += 1;
+      } else if (ch === '"') {
+        inQuote = false;
+      } else {
+        field += ch;
+      }
+      continue;
+    }
+    if (ch === '"') {
+      inQuote = true;
+    } else if (ch === ',') {
+      row.push(field);
+      field = '';
+    } else if (ch === '\n') {
+      row.push(field);
+      rows.push(row);
+      row = [];
+      field = '';
+    } else if (ch !== '\r') {
+      field += ch;
+    }
+  }
+  if (field !== '' || row.length > 0) {
+    row.push(field);
+    rows.push(row);
+  }
+  return rows.filter((r) => r.some((v) => String(v).trim() !== ''));
+}
+
+export function parseRedirectCsv(text) {
+  const rows = parseCsv(text);
+  if (rows.length === 0) return [];
+  const header = rows[0].map((h) => h.trim());
+  for (const field of REQUIRED_FIELDS) {
+    if (!header.includes(field)) throw new Error(`redirects CSV is missing required column "${field}"`);
+  }
+  return rows.slice(1).map((row, idx) => {
+    const record = {};
+    for (let i = 0; i < header.length; i += 1) record[header[i]] = row[i] ?? '';
+    return normalizeRedirect(record, idx + 2);
+  });
+}
+
+export function normalizeRedirect(input, rowNumber = 1) {
+  const out = {};
+  for (const field of REQUIRED_FIELDS) {
+    const value = String(input[field] ?? '').trim();
+    if (!value) throw new Error(`redirects row ${rowNumber}: ${field} is required`);
+    out[field] = value;
+  }
+
+  out.redirectStyle = input.redirectStyle === undefined || String(input.redirectStyle).trim() === ''
+    ? 301
+    : parseInteger(input.redirectStyle, 'redirectStyle', rowNumber);
+
+  // We intentionally set this by default so managed redirects can replace an
+  // existing live HubSpot page without a UI archive/move step.
+  out.isOnlyAfterNotFound = input.isOnlyAfterNotFound === undefined || String(input.isOnlyAfterNotFound).trim() === ''
+    ? false
+    : parseBool(input.isOnlyAfterNotFound, 'isOnlyAfterNotFound', rowNumber);
+
+  for (const field of BOOLEAN_FIELDS) {
+    if (field === 'isOnlyAfterNotFound') continue;
+    if (input[field] !== undefined && String(input[field]).trim() !== '') {
+      out[field] = parseBool(input[field], field, rowNumber);
+    }
+  }
+  for (const field of INTEGER_FIELDS) {
+    if (field === 'redirectStyle') continue;
+    if (input[field] !== undefined && String(input[field]).trim() !== '') {
+      out[field] = parseInteger(input[field], field, rowNumber);
+    }
+  }
+  return out;
+}
+
+export function readRedirectSpecs(file) {
+  const text = readFileSync(file, 'utf8');
+  if (file.endsWith('.json')) {
+    const raw = JSON.parse(text);
+    if (!Array.isArray(raw)) throw new Error('redirects JSON must be an array');
+    return raw.map((r, idx) => normalizeRedirect(r, idx + 1));
+  }
+  return parseRedirectCsv(text);
+}
+
+function payloadFor(spec) {
+  const out = {};
+  for (const field of ['routePrefix', 'destination', ...INTEGER_FIELDS, ...BOOLEAN_FIELDS]) {
+    if (spec[field] !== undefined) out[field] = spec[field];
+  }
+  return out;
+}
+
+export function planRedirects(specs, existing) {
+  const seenSpecs = new Set();
+  for (const spec of specs) {
+    if (seenSpecs.has(spec.routePrefix)) throw new Error(`duplicate managed redirect routePrefix "${spec.routePrefix}"`);
+    seenSpecs.add(spec.routePrefix);
+  }
+
+  const byRoute = new Map();
+  for (const redirect of existing) {
+    const route = String(redirect.routePrefix ?? '');
+    if (!route) continue;
+    if (byRoute.has(route)) throw new Error(`multiple existing HubSpot redirects share routePrefix "${route}"`);
+    byRoute.set(route, redirect);
+  }
+
+  return specs.map((spec) => {
+    const current = byRoute.get(spec.routePrefix);
+    if (!current) return { action: 'create', spec, body: payloadFor(spec) };
+
+    const body = payloadFor(spec);
+    const changes = {};
+    for (const [field, value] of Object.entries(body)) {
+      if (String(current[field]) !== String(value)) changes[field] = value;
+    }
+    if (Object.keys(changes).length === 0) {
+      return { action: 'unchanged', id: String(current.id), spec, current };
+    }
+    return {
+      action: 'update',
+      id: String(current.id),
+      spec,
+      current,
+      body: changes,
+      changedFields: Object.keys(changes),
+    };
+  });
+}
+
+function readOnlySet(config) {
+  return new Set((config?.readOnlyPortalIds?.length ? config.readOnlyPortalIds : [READ_ONLY_PORTAL]).map(String));
+}
+
+export async function syncRedirects(name, options = {}, deps = {}) {
+  const {
+    apply = false,
+    file,
+    config: optionConfig,
+  } = options;
+  const {
+    account = realAccount,
+    getAll = realGetAll,
+    hub = realHub,
+    readSpecs = readRedirectSpecs,
+  } = deps;
+  const config = deps.config || optionConfig;
+  const acct = account(name, config);
+
+  if (apply && readOnlySet(config).has(String(acct.portalId))) {
+    throw new Error(
+      `portal is read-only: account "${acct.name}" maps to portal ${acct.portalId}; redirects refuses to write`,
+    );
+  }
+
+  const sourceFile = file || config?.redirectsFilePath;
+  if (!sourceFile) {
+    throw new Error('redirects requires --file <path> or config.redirectsFile');
+  }
+  const specs = readSpecs(resolve(config?.root || process.cwd(), sourceFile));
+  const existing = await getAll(acct, '/cms/v3/url-redirects');
+  const plan = planRedirects(specs, existing);
+
+  if (apply) {
+    for (const item of plan) {
+      if (item.action === 'create') {
+        const r = await hub(acct, 'POST', '/cms/v3/url-redirects', item.body);
+        if (!r.ok) {
+          const msg = r.json?.message || r.json?.category || JSON.stringify(r.json).slice(0, 200);
+          throw new Error(`create redirect ${item.spec.routePrefix} -> ${r.status}: ${msg}`);
+        }
+        item.id = String(r.json?.id ?? '');
+      } else if (item.action === 'update') {
+        const r = await hub(acct, 'PATCH', `/cms/v3/url-redirects/${item.id}`, item.body);
+        if (!r.ok) {
+          const msg = r.json?.message || r.json?.category || JSON.stringify(r.json).slice(0, 200);
+          throw new Error(`update redirect ${item.spec.routePrefix} (${item.id}) -> ${r.status}: ${msg}`);
+        }
+      }
+    }
+  }
+
+  return {
+    account: acct.name,
+    portalId: acct.portalId,
+    file: sourceFile,
+    apply,
+    plan,
+    counts: {
+      create: plan.filter((x) => x.action === 'create').length,
+      update: plan.filter((x) => x.action === 'update').length,
+      unchanged: plan.filter((x) => x.action === 'unchanged').length,
+    },
+  };
+}
+
+export function renderRedirectReport(result) {
+  const mode = result.apply ? 'applied' : 'dry-run';
+  const lines = [];
+  lines.push(`redirects ${mode} -> account "${result.account}" (portal ${result.portalId})`);
+  lines.push(`source: ${result.file}`);
+  lines.push(
+    `summary: ${result.counts.create} create, ${result.counts.update} update, ${result.counts.unchanged} unchanged`,
+  );
+  for (const item of result.plan) {
+    const arrow = `${item.spec.routePrefix} -> ${item.spec.destination}`;
+    if (item.action === 'update') {
+      lines.push(`  [update] ${arrow} (${item.changedFields.join(', ')})`);
+    } else {
+      lines.push(`  [${item.action}] ${arrow}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+export async function main(argv = process.argv.slice(2), opts = {}) {
+  const accountName = argv.find((a) => !a.startsWith('--'));
+  if (!accountName) {
+    process.stderr.write('usage: node src/redirects.mjs <account> [--file <path>] [--apply]\n');
+    return 2;
+  }
+  let file;
+  let apply = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    if (argv[i] === '--apply') apply = true;
+    if (argv[i] === '--file') file = argv[++i];
+  }
+  try {
+    const result = await syncRedirects(accountName, { file, apply, config: opts.config }, opts.deps);
+    process.stdout.write(renderRedirectReport(result) + '\n');
+    return 0;
+  } catch (e) {
+    process.stderr.write(`redirects failed: ${e.message}\n`);
+    return 1;
+  }
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main().then((code) => process.exit(code));
+}