Tools#
The tools come in two kinds. Plugin scripts ship in bb-hubspot's scripts/ folder and serve every site: they
read the site's constants from hubspot-site.json (Site config), so nothing in them names a client.
Site tools depend on one theme's markup, so each site writes its own in its repo's tools/ folder, starting
from an existing site's versions.
In the commands on these pages, $BBH stands for the bb-hubspot folder. Inside Claude Code the skills use the
plugin's own path. Run every script from inside the site repo, because that's how it finds hubspot-site.json. Each
script's docstring holds its full usage.
Plugin scripts#
| Script | What it does |
|---|---|
publish-page.py <slug…> [--draft-only] [--account live] |
Annotations → layoutSections. Creates or patches the page; publishes on dev, draft-only on live. Refuses accounts not in the config and checks the sentinel page first. |
qa-draft.py [slug…] |
Copy coverage, links, placeholders and structure → reports/qa/. Exits 1 on missing copy. Drafts with no copy doc (showcases, live clones) are skipped and listed. |
build-drafts-index.py |
drafts/index.html: every draft with its sections, gaps and QA numbers. |
build-catalog.py |
MODULES.md + module-catalog.json from the theme, catalog-annotations.json and the crawl. |
lint-style-tab.py [module…] |
Checks Style tabs against the convention. Exits 1 on drift. |
copydoc-to-docx.py <campaign> <slug…> |
A Word copy of a copy doc for review in Google Docs. |
serve-drafts.py [port] |
Static server for the repo root (default 8815). |
visual-regression.py snapshot/compare |
The live-upload gate: normalised HTML plus screenshots of every live page, before and after. |
verify-live.py <url> --width … |
Overflow, wide elements, console errors, failed requests, empty gaps, WCAG AA contrast, section screenshots. |
shoot.py shots/thumbs/probe |
Headless Chrome over CDP with its own temporary profile. Falls back to Google Chrome --headless=new when no headless shell is installed. |
clone-live-page.py <live> <dev> [--replace …] [--dry-run] |
Mirrors a live page's real layout onto dev, optionally swapping modules. |
patch-live-draft.py <live> [--staging id] --replace/--set-field/--insert-before … [--apply] |
Edits an existing live page's draft or staging copy. Dry run by default. |
stage-landing-page.py <dev id> <live id> |
Copies a dev page's layout into a Content Staging landing page. |
hubspot_site.py |
The shared module: config loading, account guards, hs api and service-key calls, asset URL rewriting, draft annotations, the page registry. |
Site tools#
These are written for each site because they depend on one theme's markup.
| Tool | What it does | What changes from site to site |
|---|---|---|
tools/crawl-site.py |
Live pages → sections and modules → reports/site-crawl.{json,md} |
The module matcher (root CSS classes) and the page-type classifier |
tools/export-copydocs.py |
One copy doc per crawled page → imports/live/ |
Text extraction follows the module markup |
tools/build-previews.py |
One preview page per module, rendered from the real module.html |
The module_page(...) examples; the HubL shims mostly carry over |
tools/build-page.py |
Copy doc → annotated draft, plus a gap report | Archetype assemblers, copy-shape mapping, house settings |
tools/build-showcase.py |
A module's variants as a page for the dev portal | The variant lists |
tools/make-hero.py (optional) |
Hero backgrounds in the house style | The house style |
Site tools write the same formats the plugin scripts read: @section annotations in drafts/<slug>.html, entries
in pages.json, and reports/site-crawl.json.