hubspot-cms-sync 0.1.0

package/src/corpus-scan.mjs

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+// scripts/corpus-scan.mjs — CORPUS SCAN: guards the committed canonical content tree
+// against NON-PORTABLE values that would break a push into a fresh HubSpot account.
+//
+// Stage 1-3 (sync/lib/refs.mjs) canonicalize per-account ids into LOGICAL tokens
+// (@form / @cta / @asset / @menu / @portal) on pull, and resolve() injects the target
+// account's ids on push — HARD-FAILING if a token has no target mapping. That round-trip
+// only holds if the committed tree contains tokens, not raw ids. This scanner is the
+// invariant check: it walks content/** (the canonical store) plus templates/, modules/
+// and js/ (which embed refs in hand-authored HubL/JS) and FLAGS every forbidden literal:
+//
+//   - literal portal ids            529456 (prod) / 246389711 (dev)
+//   - raw form GUIDs                "form_id": "<guid>"
+//   - hosted asset URLs             https://…/hubfs/<portal>/…  +  *.hubspotusercontent*
+//   - hbspt.cta.load(<portal>,…)    untokenized CTA loader
+//   - {{cta('<guid>')}}             untokenized CTA shortcode
+//   - bare CTA GUIDs                "guid":"<guid>", cta/redirect/…, pg=<guid>, hs-cta-<guid>
+//   - page / blog / module numeric ids   "id": <bigint>, contentId, etc.
+//
+// A line is CLEAN if the only refs on it are @logical tokens. The scan is PURE (string +
+// fs walk, no API) and exported as `scan(dir)` so the node:test suite can drive it over
+// deterministic fixtures rather than the live (still-dirty) tree.
+//
+//   node scripts/corpus-scan.mjs [dir...]   # default dirs: content templates modules js
+//   exit 0 = clean, 1 = forbidden values found
+//
+// NOTE: today's content/ still holds ~145 raw junk pages; running the CLI documents that
+// debt. The TEST uses fixtures (test/integration/corpus.test.mjs) so it stays deterministic.
+
+import { readdirSync, statSync, readFileSync } from 'node:fs';
+import { join, relative, extname } from 'node:path';
+
+import { KNOWN_PORTALS } from './lib/refs.mjs';
+
+const GUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const PORTALS = KNOWN_PORTALS.join('|'); // 529456|246389711
+
+export const DEFAULT_DIRS = ['content', 'templates', 'modules', 'js'];
+const SCAN_EXT = new Set(['.json', '.html', '.js', '.mjs', '.css', '.hubl', '.txt', '.md']);
+
+// ---------------------------------------------------------------------------
+// RULES — each has an id, a human label, and a `find(line)` that yields the
+// offending substring(s). Rules describe NON-PORTABLE shapes; anything that is
+// already an `@logical` token is, by construction, not matched by these.
+//
+// Ordering matters only for which rule "claims" a match in the report; a single
+// bad substring may satisfy several rules, which is fine — we de-dupe per line by
+// the matched text so a hosted-URL hit isn't double-counted as a bare-portal hit.
+// ---------------------------------------------------------------------------
+export const RULES = [
+  {
+    id: 'hosted-asset-url',
+    label: 'hosted hubfs/hubspotusercontent asset URL (use @asset:<path>)',
+    re: new RegExp(
+      // Any HubSpot file host path shape: /hubfs/<portal>/, /hub/<portal>/hubfs/,
+      // /hs-fs/hubfs/[<portal>/] (theseventhsense.com has NO portal segment), OR any
+      // hubspotusercontent host. Group is the whole URL up to a delimiter.
+      `https?://[a-z0-9.-]+/(?:hub/\\d{5,}/hubfs|hs-fs/hubfs(?:/\\d{5,})?|hubfs/\\d{5,})/[^"'\\\\\\s),]+` +
+        `|https?://[a-z0-9.-]*hubspotusercontent[a-z0-9.-]*/[^"'\\\\\\s),]+`,
+      'gi',
+    ),
+  },
+  {
+    id: 'googleusercontent-url',
+    label: 'foreign googleusercontent image URL (use @asset:googleusercontent/<blob>)',
+    re: new RegExp(`https?://lh[0-9]+\\.googleusercontent\\.com/[^"'\\\\\\s),]+`, 'gi'),
+  },
+  {
+    id: 'cta-load',
+    label: 'hbspt.cta.load(<portal>,…) (use hbspt.cta.load(@portal,\'@cta:key\'…))',
+    re: new RegExp(`hbspt\\.cta\\.load\\(\\s*\\d{5,}\\s*,\\s*['"]${GUID}['"]`, 'gi'),
+  },
+  {
+    id: 'cta-shortcode',
+    label: "untokenized {{cta('<guid>')}} / {{ cta(\"<guid>\") }} (use {{cta('@cta:key')}})",
+    re: new RegExp(`\\{\\{\\s*cta\\(\\s*['"]${GUID}['"]`, 'gi'),
+  },
+  {
+    id: 'form-guid',
+    label: 'raw form GUID in "form_id" (use @form:key)',
+    re: new RegExp(`"form_id"\\s*:\\s*"${GUID}"`, 'gi'),
+  },
+  {
+    id: 'cta-guid',
+    label: 'bare CTA GUID (use @cta:key)',
+    re: new RegExp(
+      `(?:"guid"\\s*:\\s*"|/cta/(?:redirect|default)/\\d{5,}/|[?&]pg=|hs-cta(?:-wrapper|-img|-ie-element|-node)?-|data-hs-img-pg=")${GUID}`,
+      'gi',
+    ),
+  },
+  {
+    id: 'portal-id',
+    label: 'literal portal id (use @portal)',
+    re: new RegExp(`\\b(?:${PORTALS})\\b`, 'g'),
+  },
+  {
+    id: 'numeric-content-id',
+    label: 'numeric page/blog/module id (canonical store must key by slug/path, not id)',
+    // Long numeric ids assigned to id-bearing JSON keys. HubSpot ids are >= 10 digits;
+    // we bound at 8+ to also catch shorter legacy ids while not biting small counts.
+    // Match only a COMPLETE numeric id value — a quoted run of digits with the
+    // closing quote right after (`"id": "4937909260"`), or an unquoted number at a
+    // value boundary (`"module_id": 1730194537`). The closing-quote/boundary
+    // requirement avoids false-positives on field-definition UUIDs whose all-decimal
+    // 8-hex prefix would otherwise match (`"id": "85836571-317e-..."`).
+    re: new RegExp(
+      `"(?:id|contentId|content_id|pageId|page_id|blogId|blog_id|moduleId|module_id|parentId|parent_id|portalId|portal_id|formId|menuId|themeId|groupId)"\\s*:\\s*"?(\\d{8,})"?(?![\\d-])`,
+      'g',
+    ),
+  },
+];
+
+// `@logical` token grammar (mirrors refs.mjs TOKEN_RE). A line carrying ONLY these
+// for its identity is portable and must NOT be flagged.
+const TOKEN_RE = /@(?:form|cta|menu):[A-Za-z0-9_-]+|@asset:[^\s"'\\)]+|@portal\b/g;
+
+// ---------------------------------------------------------------------------
+// scanText(text, file) -> [{ file, line, rule, match }]
+// Pure: runs each rule line-by-line. A match that is wholly inside an `@logical`
+// token span is ignored (defensive — tokens never contain raw ids, but e.g. an
+// @asset:path could in theory embed digits). Per (line, matchText) pairs are
+// de-duplicated, preferring the most specific rule (RULES order).
+// ---------------------------------------------------------------------------
+export function scanText(text, file = '<text>') {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const lines = text.split('\n');
+  const out = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (line.length === 0) continue;
+
+    // Spans covered by an @logical token — matches inside these are portable.
+    const tokenSpans = [];
+    for (const t of line.matchAll(TOKEN_RE)) tokenSpans.push([t.index, t.index + t[0].length]);
+    const inToken = (start, end) =>
+      tokenSpans.some(([s, e]) => start >= s && end <= e);
+
+    const seen = new Set(); // matchText already claimed on this line (most-specific wins)
+    for (const rule of RULES) {
+      for (const m of line.matchAll(rule.re)) {
+        const start = m.index;
+        const end = start + m[0].length;
+        if (inToken(start, end)) continue;
+        if (seen.has(m[0])) continue;
+        // For portal-id, skip a hit that is actually part of a longer match a more
+        // specific rule already claimed (e.g. the portal inside a hosted URL).
+        if (rule.id === 'portal-id' && [...seen].some((s) => s.includes(m[0]))) continue;
+        seen.add(m[0]);
+        out.push({ file, line: i + 1, rule: rule.id, label: rule.label, match: m[0] });
+      }
+    }
+  }
+  return out;
+}
+
+// ---------------------------------------------------------------------------
+// walk(dir) -> [absolute file paths] of scannable files. Skips dot-dirs,
+// node_modules, and the gitignored .sync-state. Pure-ish (fs reads only).
+// ---------------------------------------------------------------------------
+export function walk(dir) {
+  const files = [];
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return files; // missing dir is not an error — caller passes a default set
+  }
+  for (const name of entries) {
+    if (name.startsWith('.')) continue;
+    if (name === 'node_modules') continue;
+    const full = join(dir, name);
+    let st;
+    try {
+      st = statSync(full);
+    } catch {
+      continue;
+    }
+    if (st.isDirectory()) files.push(...walk(full));
+    else if (SCAN_EXT.has(extname(name))) files.push(full);
+  }
+  return files;
+}
+
+// ---------------------------------------------------------------------------
+// scan(dir | [dirs]) -> { findings, files, scanned }
+// Walks the given root(s), scans each file, returns all findings with paths
+// relative to the first root for stable, portable output. PURE wrt API (no network).
+// ---------------------------------------------------------------------------
+export function scan(dirs = DEFAULT_DIRS) {
+  const roots = Array.isArray(dirs) ? dirs : [dirs];
+  const base = roots[0];
+  const findings = [];
+  const files = [];
+  for (const root of roots) {
+    for (const f of walk(root)) {
+      files.push(f);
+      let text;
+      try {
+        text = readFileSync(f, 'utf8');
+      } catch {
+        continue;
+      }
+      const rel = relative(base, f) || f;
+      findings.push(...scanText(text, rel.startsWith('..') ? f : rel));
+    }
+  }
+  return { findings, files: findings.length ? [...new Set(findings.map((x) => x.file))] : [], scanned: files.length };
+}
+
+// ---------------------------------------------------------------------------
+// CLI
+// ---------------------------------------------------------------------------
+function main(argv) {
+  const dirs = argv.length ? argv : DEFAULT_DIRS;
+  const { findings, scanned } = scan(dirs);
+  if (!findings.length) {
+    console.log(`corpus-scan: clean — ${scanned} file(s) scanned, 0 non-portable values.`);
+    return 0;
+  }
+  // Group by file for a readable file:match list.
+  const byFile = new Map();
+  for (const f of findings) {
+    if (!byFile.has(f.file)) byFile.set(f.file, []);
+    byFile.get(f.file).push(f);
+  }
+  const byRule = new Map();
+  for (const f of findings) byRule.set(f.rule, (byRule.get(f.rule) || 0) + 1);
+
+  console.error(`corpus-scan: FAIL — ${findings.length} non-portable value(s) in ${byFile.size} file(s) (${scanned} scanned).\n`);
+  for (const [file, hits] of [...byFile.entries()].sort((a, b) => b[1].length - a[1].length)) {
+    console.error(`${file}  (${hits.length})`);
+    for (const h of hits.slice(0, 50)) {
+      console.error(`  L${h.line}  ${h.rule}: ${h.match}`);
+    }
+    if (hits.length > 50) console.error(`  …and ${hits.length - 50} more`);
+  }
+  console.error('\nby rule:');
+  for (const [rule, n] of [...byRule.entries()].sort((a, b) => b[1] - a[1])) {
+    console.error(`  ${rule}: ${n}`);
+  }
+  return 1;
+}
+
+// ESM entry guard.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  process.exit(main(process.argv.slice(2)));
+}

package/src/cta-inventory.mjs

@@ -0,0 +1,352 @@
+// sync/cta-inventory.mjs — READ-ONLY legacy-CTA inventory + resolution helpers.
+//
+// WHY (codex #3/#5, gap-closure "REVISED approach"): legacy HubSpot CTAs are NOT
+// portable. There is no working v3 CTA CRUD API (every documented list endpoint —
+// /cms/v3/cta, /content/api/v2/cta(-buttons), /calls-to-action/v2/buttons, … —
+// 404s on a real portal; the legacy CTA editor is sunset). The ONLY CTAs in this
+// corpus live in legacy blog/landing-page bodies as the classic embed block:
+//
+//   <!--HubSpot Call-to-Action Code --><span class="hs-cta-wrapper" id="hs-cta-wrapper-<GUID>">
+//     <span class="hs-cta-node hs-cta-<GUID>" id="hs-cta-<GUID>">
+//       <!--[if lte IE 8]><div id="hs-cta-ie-element"></div><![endif]-->
+//       <a href="https://cta-redirect.hubspot.com/cta/redirect/<PORTAL>/<GUID>" [target=…] >
+//         <img class="hs-cta-img" id="hs-cta-img-<GUID>" src="https://no-cache.hubspot.com/cta/default/<PORTAL>/<GUID>.png" alt="<NAME>"/>
+//       </a>
+//     </span>
+//     <script src="https://js.hscta.net/cta/current.js"></script>
+//     <script>hbspt.cta.load(<PORTAL>, '<GUID>', {});</script>
+//   </span><!-- end HubSpot Call-to-Action Code -->
+//
+// Those carry a per-account portal id + a CTA GUID — neither is portable, and
+// canonicalize() would turn them into `@cta:<guid-prefix>` tokens that NO adapter
+// can resolve (the push preflight then fails-closed). Blind link-conversion would
+// be silent fidelity loss (codex #5: analytics / redirect / styling).
+//
+// REVISED approach: build a one-time inventory mapping each CTA GUID to its
+// { destinationHref, renderedHtml, name, tracked } by RESOLVING the public
+// cta-redirect interstitial (the same URL the embed's own fallback <a> points at).
+// That interstitial is an HTML page whose body contains
+//   var redirectUrl = "<final destination>";
+// so we extract the real destination href without any private API. The blog
+// canonicalizer (blog.mjs) then rewrites each embed to a styled, portable
+// <a class="btn" href="<destination>">…</a> — NO @cta token, NO per-account GUID.
+//
+// PRODUCTION 529456 is READ-ONLY. This tool only READS (an outbound GET to the
+// public cta-redirect host + GETs against the account); it NEVER writes to any
+// account. Output is cached to the gitignored .sync-state/<portal>.cta-inventory.json.
+//
+// Usage:  node sync/cta-inventory.mjs <account> [--content content] [--refresh]
+//
+// Pure helpers (no I/O — unit-testable without network):
+//   ctaGuidsInText(text)          -> [guid, …]  (every CTA guid shape in a string)
+//   extractRedirectUrl(html)      -> destination href | null  (from the interstitial)
+//   ctaNameFromEmbed(html, guid)  -> alt-text name | null
+//   resolveCtaEmbeds(text, inv)   -> { text, unresolved:[guid…], notes:[…] }
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync, readdirSync, statSync } from 'node:fs';
+import { join, resolve as resolvePath } from 'node:path';
+
+import { account as realAccount } from './lib/hub.mjs';
+
+const GUID = '[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}';
+const CTA_REDIRECT_HOST = 'https://cta-redirect.hubspot.com';
+
+// ── pure: enumerate every CTA GUID shape in a string ────────────────────────────
+
+// Every place a legacy CTA GUID appears in an embed: the redirect <a href>, the
+// hbspt.cta.load() call, the wrapper/node/img ids, the data-hs-img-pg attr, and the
+// {{cta('guid')}} HubL shortcode. Deduped, source-order preserved.
+const GUID_SHAPES = [
+  new RegExp(`cta/redirect/\\d{5,}/(${GUID})`, 'g'),
+  new RegExp(`cta/default/\\d{5,}/(${GUID})`, 'g'),
+  new RegExp(`hbspt\\.cta\\.load\\(\\s*\\d{5,}\\s*,\\s*['"](${GUID})['"]`, 'g'),
+  new RegExp(`hs-cta(?:-wrapper|-node|-img|-ie-element)?-(${GUID})`, 'g'),
+  new RegExp(`data-hs-img-pg=["'](${GUID})["']`, 'g'),
+  new RegExp(`\\{\\{\\s*cta\\(\\s*['"](${GUID})['"]`, 'g'),
+];
+
+export function ctaGuidsInText(text) {
+  if (typeof text !== 'string' || text.length === 0) return [];
+  const seen = new Set();
+  const out = [];
+  for (const re of GUID_SHAPES) {
+    for (const m of text.matchAll(re)) {
+      const g = m[1].toLowerCase();
+      if (!seen.has(g)) {
+        seen.add(g);
+        out.push(g);
+      }
+    }
+  }
+  return out;
+}
+
+// ── pure: extract the destination href from a cta-redirect interstitial ──────────
+
+// The interstitial sets `var redirectUrl = "<dest>";` (and uses window.location).
+// Fall back to a plain meta-refresh / Location-style URL if the JS var is absent.
+export function extractRedirectUrl(html) {
+  if (typeof html !== 'string' || html.length === 0) return null;
+  const jsVar = html.match(/var\s+redirectUrl\s*=\s*["']([^"']+)["']/);
+  if (jsVar) return decodeHtml(jsVar[1]);
+  const meta = html.match(/<meta[^>]+http-equiv=["']refresh["'][^>]+url=([^"'>\s]+)/i);
+  if (meta) return decodeHtml(meta[1]);
+  const loc = html.match(/window\.location(?:\.href)?\s*=\s*["']([^"']+)["']/);
+  if (loc) return decodeHtml(loc[1]);
+  return null;
+}
+
+function decodeHtml(s) {
+  return String(s)
+    .replace(/&amp;/g, '&')
+    .replace(/&#x2F;/gi, '/')
+    .replace(/&#47;/g, '/')
+    .replace(/&quot;/g, '"');
+}
+
+// ── pure: best-effort human name from the embed (the image alt text) ─────────────
+
+export function ctaNameFromEmbed(html, guid) {
+  if (typeof html !== 'string') return null;
+  // Find the <img …id="hs-cta-img-<guid>"…alt="…"> for this guid and read its alt.
+  const re = new RegExp(
+    `hs-cta-img-${guid.replace(/[-]/g, '\\-')}[^>]*?\\balt=["']([^"']*)["']`,
+    'i',
+  );
+  const m = html.match(re);
+  if (m && m[1]) return m[1];
+  // Fallback: any alt on an hs-cta-img near this guid.
+  const any = html.match(/hs-cta-img[^>]*?\balt=["']([^"']+)["']/i);
+  return any ? any[1] : null;
+}
+
+// ── pure: rewrite CTA embeds in a body to portable styled <a> links ──────────────
+//
+// resolveCtaEmbeds(text, inventory) -> { text, unresolved, notes }
+//
+//   inventory: { [guid]: { destinationHref, name?, tracked? } }
+//
+// For each whole CTA embed block we find, look up its guid in the inventory:
+//   • known + has destinationHref + NOT still-tracked → replace the WHOLE block with
+//     <a class="btn" href="<dest>"[ target=_blank]>…label…</a>  (fully portable).
+//   • unknown guid, or flagged still-tracked, or no destination → PRESERVE the raw
+//     embed HTML verbatim and record a LOUD note + the guid in `unresolved` (never
+//     silently dropped — the operator/preflight must see it).
+//
+// Idempotent: a body with no embed block is returned unchanged; an already-resolved
+// <a class="btn"> is left alone (it carries no hs-cta markup to match).
+const CTA_BLOCK_RE =
+  /<!--\s*HubSpot Call-to-Action Code\s*-->[\s\S]*?<!--\s*end HubSpot Call-to-Action Code\s*-->/gi;
+
+export function resolveCtaEmbeds(text, inventory = {}) {
+  const notes = [];
+  const unresolved = [];
+  if (typeof text !== 'string' || text.length === 0) return { text, unresolved, notes };
+
+  const out = text.replace(CTA_BLOCK_RE, (block) => {
+    const guids = ctaGuidsInText(block);
+    const guid = guids[0];
+    if (!guid) {
+      notes.push('⚠ CTA embed found with no recognizable GUID — preserved raw HTML.');
+      return block;
+    }
+    const entry = inventory[guid];
+    if (!entry || !entry.destinationHref) {
+      unresolved.push(guid);
+      notes.push(
+        `⚠ CTA ${guid} not in inventory (or no destination) — preserved raw embed HTML. ` +
+          `Run \`node sync/cta-inventory.mjs <account>\` to resolve it.`,
+      );
+      return block;
+    }
+    if (entry.tracked === true) {
+      unresolved.push(guid);
+      notes.push(
+        `⚠ CTA ${guid} ("${entry.name || '?'}") is flagged STILL-TRACKED — preserved raw ` +
+          `embed HTML to avoid losing analytics/redirect behavior (codex #5). Resolve manually.`,
+      );
+      return block;
+    }
+    const label = ctaNameFromEmbed(block, guid) || entry.name || 'Learn more';
+    const targetBlank = /target=["']?_blank/i.test(block);
+    return buildResolvedLink(entry.destinationHref, label, { targetBlank });
+  });
+
+  return { text: out, unresolved, notes };
+}
+
+// Build the portable replacement anchor. A styled button link, no per-account ids.
+export function buildResolvedLink(href, label, { targetBlank = false } = {}) {
+  const safeHref = escapeAttr(href);
+  const safeLabel = escapeText(label);
+  const tgt = targetBlank ? ' target="_blank" rel="noopener"' : '';
+  return `<a class="btn cta-btn" href="${safeHref}"${tgt}>${safeLabel}</a>`;
+}
+
+function escapeAttr(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeText(s) {
+  return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+
+// ── inventory I/O (cache under the gitignored .sync-state) ───────────────────────
+
+export function inventoryPath(portalId) {
+  return join(resolvePath('.sync-state'), `${portalId}.cta-inventory.json`);
+}
+
+export function loadInventory(portalId) {
+  const p = inventoryPath(portalId);
+  if (!existsSync(p)) return {};
+  try {
+    return JSON.parse(readFileSync(p, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function saveInventory(portalId, inv) {
+  mkdirSync(resolvePath('.sync-state'), { recursive: true });
+  const ordered = {};
+  for (const k of Object.keys(inv).sort()) ordered[k] = inv[k];
+  writeFileSync(inventoryPath(portalId), JSON.stringify(ordered, null, 2) + '\n');
+}
+
+// ── scan committed content for CTA guids ─────────────────────────────────────────
+
+// Recursively collect every CTA GUID referenced under a content dir. Defaults to
+// the blog (CTAs are blog/landing-page-content-only per codex #3/#5) but accepts
+// any subtree so the operator can widen the scan.
+export function scanContentForCtaGuids(contentDir, sub = '') {
+  const root = join(resolvePath(contentDir), sub);
+  const guids = new Set();
+  if (!existsSync(root)) return [];
+  const walk = (dir) => {
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      const st = statSync(full);
+      if (st.isDirectory()) {
+        walk(full);
+      } else if (name.endsWith('.json')) {
+        for (const g of ctaGuidsInText(readFileSync(full, 'utf8'))) guids.add(g);
+      }
+    }
+  };
+  walk(root);
+  return [...guids].sort();
+}
+
+// ── resolution against the public cta-redirect interstitial ──────────────────────
+
+// Resolve one CTA GUID to { destinationHref, name, renderedHtml, tracked, status }.
+// READ-ONLY: a single outbound GET to the PUBLIC cta-redirect host (no account key,
+// no write). `tracked` is true when we could not extract a destination (the CTA may
+// still be live/tracked and must be preserved, not link-converted).
+export async function resolveCta(portalId, guid, { fetchFn = fetch } = {}) {
+  const redirectUrl = `${CTA_REDIRECT_HOST}/cta/redirect/${portalId}/${guid}`;
+  let html = '';
+  let status = 0;
+  try {
+    const res = await fetchFn(redirectUrl, { redirect: 'manual' });
+    status = res.status;
+    // A 3xx with a Location header is a clean destination; otherwise read the body.
+    const loc = res.headers?.get?.('location');
+    if (loc && /^https?:/i.test(loc)) {
+      return {
+        destinationHref: loc,
+        name: null,
+        renderedHtml: redirectUrl,
+        tracked: false,
+        status,
+      };
+    }
+    html = await res.text();
+  } catch (e) {
+    return { destinationHref: null, name: null, renderedHtml: redirectUrl, tracked: true, status, error: e.message };
+  }
+  const destinationHref = extractRedirectUrl(html);
+  return {
+    destinationHref,
+    name: ctaNameFromEmbed(html, guid),
+    renderedHtml: redirectUrl,
+    // If we could not extract a destination, treat as still-tracked/unknown so the
+    // canonicalizer PRESERVES the raw embed rather than dropping it.
+    tracked: destinationHref == null,
+    status,
+  };
+}
+
+// ── CLI ──────────────────────────────────────────────────────────────────────────
+
+export async function buildInventory(
+  name,
+  { contentDir = 'content', sub = 'blog', refresh = false, account = realAccount, resolveFn = resolveCta, log = console.log } = {},
+) {
+  const acct = account(name);
+  const guids = scanContentForCtaGuids(contentDir, sub);
+  log(`cta-inventory: account "${acct.name}" (portal ${acct.portalId}) — ${guids.length} CTA guid(s) found under ${join(contentDir, sub)}`);
+
+  const inv = refresh ? {} : loadInventory(acct.portalId);
+  let resolved = 0;
+  let stillTracked = 0;
+  for (const guid of guids) {
+    if (inv[guid] && inv[guid].destinationHref && !refresh) continue;
+    const r = await resolveFn(acct.portalId, guid);
+    inv[guid] = {
+      destinationHref: r.destinationHref || null,
+      name: r.name || null,
+      renderedHtml: r.renderedHtml || null,
+      tracked: r.tracked === true,
+    };
+    if (r.destinationHref) {
+      resolved++;
+      log(`  ✓ ${guid} -> ${r.destinationHref}${r.name ? `  (${r.name})` : ''}`);
+    } else {
+      stillTracked++;
+      log(`  ⚠ ${guid} -> UNRESOLVED (status ${r.status}) — preserved as still-tracked/unknown`);
+    }
+  }
+  saveInventory(acct.portalId, inv);
+  log(`cta-inventory: ${resolved} resolved, ${stillTracked} still-tracked/unknown, ${Object.keys(inv).length} total -> ${inventoryPath(acct.portalId)}`);
+  return inv;
+}
+
+async function main(argv) {
+  const args = argv.slice(2);
+  const name = args.find((a) => !a.startsWith('--'));
+  if (!name) {
+    console.error('Usage: node sync/cta-inventory.mjs <account> [--content <dir>] [--sub <subdir>] [--refresh]');
+    process.exit(2);
+  }
+  const contentDir = optVal(args, '--content') || 'content';
+  const sub = optVal(args, '--sub') ?? 'blog';
+  const refresh = args.includes('--refresh');
+  await buildInventory(name, { contentDir, sub, refresh });
+}
+
+function optVal(args, flag) {
+  const i = args.indexOf(flag);
+  return i >= 0 ? args[i + 1] : undefined;
+}
+
+// Run as CLI only when invoked directly.
+if (import.meta.url === `file://${process.argv[1]}`) {
+  main(process.argv).catch((e) => {
+    console.error(e.message || e);
+    process.exit(1);
+  });
+}
+
+export default {
+  ctaGuidsInText,
+  extractRedirectUrl,
+  ctaNameFromEmbed,
+  resolveCtaEmbeds,
+  buildResolvedLink,
+  loadInventory,
+  inventoryPath,
+  scanContentForCtaGuids,
+  resolveCta,
+  buildInventory,
+};

package/src/index.mjs

@@ -0,0 +1,3 @@
+export { loadConfig } from './config.mjs';
+export { pull } from './pull.mjs';
+export { push, preflightRefs } from './push.mjs';