hubspot-cms-sync 0.1.0 → 0.3.0

package/src/lib/render.mjs

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

package/src/preflight.mjs

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

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));
+}