@getvitops/cli 8.2.0-alpha.0 → 8.2.0

package/dist/cli.mjs

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { parseArgs } from "node:util";
+import { pathToFileURL } from "node:url";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, extname, join, parse, relative, resolve } from "node:path";
 import { CONFIG_SCHEMA_LOCAL_PATH, JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_LOCAL_PATH, buildIconSprite, defaultConfig, defaultSiteConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, movedTokens, processorsMissingLocation, renderRobotsTxt, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
@@ -9,9 +10,8 @@ import { SCOPES, SNAPSHOT_PATH, adcCredentialsPath, adcQuotaProject, collectEntr
 import { REVIEWS_CACHE_PATH, fetchReviews, formatPlan as formatPlan$1, mergeCache, plan as plan$1, readCache, selectReviews, toCache, writeCache } from "@getvitops/utils/reviews";
 import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$2, processMedia } from "@getvitops/utils/media";
 import { homedir } from "node:os";
-import { pathToFileURL } from "node:url";
 import { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan as formatPlan$3, formatSummary, getSite, getVerificationToken, getWebResource, hasDrift, listApexTxt, ownerUnion, plan as plan$2, refreshTokenGrant, siteUrlFor, updateOwners, verifyWebResource } from "@getvitops/utils/onboarding";
-import { AD_PLATFORMS, AD_PROVIDER_KEYS, formatPlan as formatPlan$4, formatSummary as formatSummary$1, hasDrift as hasDrift$1, isAdProvider, missingFields, plan as plan$3, renderTag, tagId } from "@getvitops/utils/ads";
+import { AD_PLATFORMS, AD_PROVIDER_KEYS, formatPlan as formatPlan$4, formatSummary as formatSummary$1, hasDrift as hasDrift$1, isAdProvider, missingFields, normalizeConversionActionIds, normalizeConversionLabels, plan as plan$3, renderTag, tagId } from "@getvitops/utils/ads";
 import { PLATFORM_PARAMS } from "@getvitops/utils/tracking";
 import { createInterface } from "node:readline/promises";
 import { zohoAccountsHost, zohoApiHost } from "@getvitops/utils/crm";
@@ -20,7 +20,7 @@ import { normalizeEmailChannel, resolveSender } from "@getvitops/utils/notify";
 import { execFileSync } from "node:child_process";
 import { adminCollaboratorIds, branches, createD1, createDevEnvironment, createProdEnvironment, createR2Bucket, createRepo, defaultBranch, environments, findD1, findR2Bucket, formatPlan as formatPlan$6, formatSummary as formatSummary$3, ghAuthed, mainProtected, originRemote, plan as plan$4, planDomainConsistency, protectMain, pushBranches, repoNwo, secretsPresent, setDefaultBranch, setSecret, wranglerWhoami } from "@getvitops/utils/hosting";
 
-//#region src/args.ts
+// src/args.ts
 /**
 * A typed wrapper around `node:util`'s `parseArgs`, used by every `vitops` subcommand.
 *
@@ -59,8 +59,7 @@ function msg(err) {
 	return err.message;
 }
 
-//#endregion
-//#region src/commands/shared.ts
+// src/commands/shared.ts
 /**
 * Helpers shared by the `vitops` subcommands that read a `Config` (site.json) —
 * `legal`, `robots`, `reviews`, `icons`, and the `search`/`ads` subcommand groups
@@ -158,8 +157,7 @@ function writeOut(path, contents) {
 	writeFileSync(path, contents);
 }
 
-//#endregion
-//#region src/credentials.ts
+// src/credentials.ts
 /**
 * Credential loaders shared by `search setup`, `search notify`, `ads setup` and
 * `reviews` — every command that talks to Google or Cloudflare. Never reads a
@@ -329,8 +327,7 @@ function loadZohoOAuth() {
 	};
 }
 
-//#endregion
-//#region src/help.ts
+// src/help.ts
 /**
 * The CLI's help text, and the addressing that lets every subcommand answer
 * `--help`.
@@ -852,11 +849,10 @@ const wantsHelp = (argv) => argv.includes("-h") || argv.includes("--help");
 /** The help text to print for `vitops <command> [sub] --help`. */
 function helpFor(command, argv) {
 	const sub = argv[0] && !argv[0].startsWith("-") ? argv[0] : void 0;
-	return (sub ? helpSection(command, sub) : void 0) ?? helpSection(command) ?? (command === "search" ? SEARCH_HELP : command === "ads" ? ADS_HELP : command === "crm" ? CRM_HELP : command === "setup" ? SETUP_HELP$1 : command === "email" ? EMAIL_HELP : void 0) ?? HELP;
+	return (sub ? helpSection(command, sub) : void 0) ?? helpSection(command) ?? (command === "search" ? "vitops search — Google Search Console\n\n  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties\n  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "ads" ? "vitops ads — link this site to its ad properties\n\n  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record\n  vitops ads tags [opts]        Print the consent-gated pixel snippets\n  vitops ads lint [opts]        Report ad properties the rest of the config can't see\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "crm" ? "vitops crm — push form submissions into a client CRM\n\n  vitops crm check [opts]       Compare site.crm's fieldMap/trackingFields against the live CRM\n  vitops crm setup [opts]       Create missing HubSpot properties (Bigin/Jobber have no such API)\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "setup" ? "vitops setup — the scripted path from an empty scaffold to a live site\n\n  vitops setup repo [opts]      GitHub repo + branch policy (main protected, dev open)\n  vitops setup hosting [opts]   Dev D1 + R2 + repo secrets (cloudflare) or a Node target\n  vitops setup domain [opts]    Plan/check the workers.dev-vs-custom-domain consistency\n                                 (never applies the cutover — see SETUP.html)\n  vitops setup search [opts]    Forwards to `vitops search setup`\n  vitops setup ads [opts]       Forwards to `vitops ads setup`\n  vitops setup all [opts]       Run repo, hosting, search, ads in order\n\nRun `vitops --help` for the full option list for each subcommand.\n" : command === "email" ? "vitops email — sender-domain onboarding checks\n\n  vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve\n  vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded\n\nRun `vitops --help` for the full option list for each subcommand.\n" : void 0) ?? "vitops — generate design-system outputs from a design-system.json\n\nAnywhere a command takes --input, that file may be a design-system.json OR the\nlarger site config that embeds one (company.json / site.json). The two are told\napart by shape, and a site config also supplies the site-level facts generation\nreads — its default colour scheme, its legal documents, its icon sprite.\n\nUsage:\n  vitops generate [options]     Generate platform output from a config\n  vitops init [options]         Scaffold a starter design-system.json\n  vitops validate <file>        Validate a config against the schema it says it is\n  vitops favicon [options]      Generate a favicon set from a source image\n  vitops agents [options]       Link the design-system agent skill + AGENTS.md pointer\n  vitops docs [topic]           Print live design-system reference docs to stdout\n  vitops lint [opts] [files]    Report classes that resolve to nothing + primitives you re-implemented\n  vitops legal [options]        Render legal documents from a site config\n  vitops robots [options]       Render robots.txt from a site config's environment\n  vitops reviews [options]      Fetch + cache Google Business Profile reviews\n  vitops icons [options]        Report which icons your source uses, and build the sprite\n  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)\n  vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint\n  vitops setup <sub> [opts]     Scripted onboarding: repo, hosting, domain, search, ads, all\n  vitops email <sub> [opts]     Sender-domain onboarding: check (setup) + deploy guard (check)\n  vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster\n\nGenerate options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n  -f, --format <list>   bricks | css | tailwind | design (comma-separated; default: bricks)\n                        design emits DESIGN.md only (the agent-facing brief) — pair it\n                        with --out . to write it beside AGENTS.md, or compose:\n                        --format css,design\n  -o, --out <dir>       Output directory (default: ./dist)\n      --theme <name>    Which designSystem.themes entry to build, when --input is\n                        a site config (default: its defaultTheme, else \"default\")\n      --site <path>     Site config, when it is a different file from --input.\n                        Emits legal/*.html into the output directory (see:\n                        vitops legal). Omitted with a plain design-system.json:\n                        no legal files.\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\nInit options:\n  -o, --out <path>      Where to write (default: ./design-system.json, or\n                        ./site.json with --site)\n      --force           Overwrite an existing file\n      --site            Write a site config (Config) instead of a bare\n                        design-system.json — embeds a starter design system at\n                        designSystem.themes.default, since a Config can't\n                        merely reference a sibling file\n      --name <name>     organization.name, when --site is set\n      --url <url>       site.environments.{production,dev}.url, when --site is set\n\nValidate options:\n  <file>                Config to check (default: ./design-system.json). Either\n                        kind — a design-system.json or the config that embeds one.\n  -i, --input <path>    Same, as a flag\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\n  Checks the schema, then the things a schema cannot: that every role points at a\n  palette hue that exists, that every var() an authored declaration references\n  resolves to a token this config emits, and that the colour grammar is current.\n\nFavicon options:\n  -i, --input <path>    Source SVG or PNG (required)\n  -o, --out <dir>       Output directory (default: ./public)\n      --low-res <path>  Optional simplified source for the 16px icon\n      --background <hex>  Background under the maskable icons, which must be\n                        opaque (default: #ffffff)\n\nAgents options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json;\n                        validated if present)\n      --theme <name>    Theme to read, when --input is a site config\n  -o, --out <path>      Doc file to update, idempotently (default: ./AGENTS.md)\n      --docs-dir <dir>  Legacy layout: write the docs bundle as files to this dir\n                        instead of linking the packaged skill\n\nDocs options:\n  <topic>               classes | authoring | formats | color | scales | patterns | elements\n                        (no topic: list topics with summaries)\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n      --theme <name>    Theme to render docs from, when --input is a site config\n      --all             Print every topic, concatenated\n\nIcons options:\n  -i, --input <path>    Site config carrying the \"icons\" block (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --src <dir>       Source to scan for icon usage (default: ./src)\n      --sprite          Also build the SVG sprite\n  -o, --out <dir>       Where to write icons.svg with --sprite (default: ./dist)\n      --json            Machine-readable report on stdout\n\nLint options:\n  -i, --input <path>    design-system.json or site config (default: ./design-system.json)\n      --theme <name>    Theme to judge classes against, when --input is a site config\n  -f, --format <fmt>    Format you build (bricks | css | tailwind; default: bricks).\n                        Responsive md-* classes are real in css/bricks, inert in tailwind.\n  -s, --src <dir>       Directory to scan (default: ./src)\n      --strict          Also fail on suggestions (reuse hints), not just on\n                        classes that resolve to nothing\n  [files...]            Lint these paths instead of scanning --src. Unreadable\n                        and non-source paths are skipped, so this can be wired\n                        into a pre-commit hook that appends the staged files.\n      --fix             Rewrite pre-1.0 colour-grammar token references\n                        (var(--<role>-<suffix>) → var(--color-<target>-<role>…))\n                        in CSS and <style> blocks. Applied in ONE pass, so the\n                        renames that rotate cannot compound. Nothing else is\n                        rewritten — every other finding is a judgement call.\n\n  Run this after a major bump: it is the migration tool for anything the\n  changelog says was renamed.\n\nLegal options:\n  -i, --input <path>    Site config: .json, or a .js/.ts module with a default\n                        export (default: ./site.json)\n  -d, --doc <name>      privacy | terms | cookies (repeatable; default: those\n                        enabled in the config)\n  -f, --format <fmt>    md | html | portable-text (default: md)\n                        html suits WordPress/Bricks and plain sites;\n                        portable-text suits EmDash\n  -o, --out <dir>       Write files here (default: print to stdout)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n\n  Generated from your config — a starting point, not legal advice. Review before\n  publishing, and make sure the config describes what your site actually does.\n\nRobots options:\n  -i, --input <path>    Site config: .json, or a .js/.ts module with a default\n                        export (default: ./site.json)\n  -o, --out <dir>       Write robots.txt here (default: print to stdout)\n      --site-env <env>  Which site.environments entry to render for (default: production)\n\n  Reads the resolved environment's robots directive (falling back to\n  site.seo.robots) — the same fact vitops search notify's noindex gate already\n  reads. A directive containing noindex disallows every user agent and emits\n  no Sitemap line; otherwise it allows everything and links\n  site.seo.indexing.sitemapUrl, or the derived <canonical>/sitemap-index.xml.\n\nReviews options:\n  -i, --input <path>    Site config carrying site.reviews (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --location <key>  Fetch only this site.reviews.locations key\n      --cache <path>    Where to read/write the cache (default: .vitops/reviews.json)\n      --out <dir>       Also write the selected reviews per location as JSON here\n      --dry             Print the plan and exit. Fetches nothing.\n      --check           Fetch and diff against the cache; exit non-zero on drift.\n                        Mutates nothing.\n\n  Reviews live only on the legacy Business Profile v4 API — there is no newer\n  replacement — and the calling GCP project must be allowlisted by Google before\n  any call succeeds (a one-time approval; a 403 says so rather than failing\n  opaquely). Auth is user OAuth, the same VITOPS_GOOGLE_CLIENT_ID /\n  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (or ADC login) that\n  vitops search setup uses, scoped to business.manage. The cache is meant to be\n  committed: reviews change slowly, and a build should not need a live Google\n  credential. Review JSON-LD is off by default (site.reviews.schema) — a business\n  marking up reviews of itself is not eligible for Google's rich results and\n  risks a manual action.\n\nSearch subcommands:\n  vitops search setup [opts]    Onboard site.searchConsole domains into GSC\n  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)\n\nSearch setup options:\n  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --domain <name>   Scope to a single site.searchConsole entry\n      --dry             Print the plan and exit. Changes nothing, and runs without\n                        credentials (planning from scratch, which it says).\n      --check           Report drift and exit non-zero if any domain is not fully\n                        onboarded. Mutates nothing, but does need credentials —\n                        drift is a comparison against live state.\n\n  For each domain it ensures the apex verification TXT in Cloudflare, verifies\n  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-\n  unverified domain is reported PENDING, not failed), adds the sc-domain: property,\n  and adds any delegatedOwners to the web resource. DNS is only ever created,\n  never edited or deleted. Credentials come from the environment:\n  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit + Zone:Read — the standard \"Edit zone DNS\"\n  template covers both; Zone:Read is what the zone-by-name lookup uses), and\n  VITOPS_GOOGLE_CLIENT_ID /\n  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token\n  scoped to siteverification + webmasters). Granting a Google Group Full-User\n  access has no API and is surfaced as a reminder.\n\n  Or just be logged in: with no VITOPS_GOOGLE_* set, an Application Default\n  Credentials login is used —\n    gcloud auth application-default login \\\n      --scopes=openid,https://www.googleapis.com/auth/siteverification,\\\n  https://www.googleapis.com/auth/webmasters,https://www.googleapis.com/auth/cloud-platform\n  ADC authenticates through a shared OAuth client that owns no project, so it also\n  needs site.google.project in the config (sent as x-goog-user-project), both APIs\n  enabled on that project, and serviceusage.services.use on it. One project per site\n  is what keeps each site's API usage and billing separate.\n\nSearch notify options:\n  -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)\n      --site-env <env>  Environment to notify for (default: production). An\n                        environment whose robots policy says noindex is refused.\n      --sitemap <src>   Sitemap URL or local path (default: from the config)\n      --urls <list>     Comma-separated URLs to submit, skipping the diff\n      --all             Submit every URL in the sitemap, not just what changed\n      --dry             Print the plan and exit. Makes no requests.\n      --check           Read-only: ask Google whether seo.indexing.priorityUrls\n                        are indexed. Exits non-zero if one is not.\n      --new-key         Print a fresh IndexNow key and exit\n      --write-key <dir> Write the IndexNow key file into <dir> (for stacks with\n                        no Astro integration to do it — Bricks, WordPress)\n      --snapshot <path> Changed-URL state file (default: .vitops/sitemap-snapshot.json).\n                        Persist it between runs (a CI cache) or every run submits\n                        everything.\n\n  What notify can and cannot do: Google exposes no \"request indexing\" API, and its\n  sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap\n  through the Search Console API and verifies the result with --check. IndexNow\n  reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.\n  Search Console takes either credential, whichever you already have, added as an\n  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline\n  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth\n  credential \"search setup\" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /\n  _REFRESH_TOKEN). The service account is preferred when both are set — this runs\n  on every deploy, and it does not expire.\n\nAds subcommands:\n  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record\n  vitops ads tags [opts]        Print the consent-gated pixel snippets\n  vitops ads lint [opts]        Report ad properties the rest of the config can't see\n\nAds setup options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --provider <name> Scope to one site.ads entry (google | meta | linkedin |\n                        reddit | tiktok | microsoft | pinterest | snapchat)\n      --dry             Print the plan and exit. Creates nothing. With\n                        CLOUDFLARE_API_TOKEN set it reads live DNS first, so the\n                        plan says what is already done; without one it plans from\n                        scratch and says so, rather than refusing to run.\n      --check           Report drift and exit non-zero if any property is not\n                        linked. Mutates nothing, prompts for nothing.\n      --no-prompt       Never ask for a missing token; fail with the field name\n                        instead (the default when stdin is not a TTY, e.g. in CI)\n      --no-write        Don't persist an answered token back into the config\n\n  Four platforms verify a domain by DNS TXT — Meta, TikTok, Pinterest, Snapchat —\n  and that record is the one thing this creates for you (in Cloudflare, via\n  CLOUDFLARE_API_TOKEN; created only, never edited or deleted). Google Ads,\n  LinkedIn, Reddit and Microsoft Ads have no domain verification at all: linking\n  there is the tag and the account ID, and the run says so rather than skipping in\n  silence. No platform Marketing API is called — Meta's needs a system-user token\n  and Google's needs an approved developer token, so the final \"Verify\" click stays\n  a reminder. The verification token is not a secret (it is published in DNS, which\n  is the ownership proof), so it lives in the config and is prompted for on the\n  first run.\n\nAds tags options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n      --provider <name> Print one platform's tag\n      --strategy <s>    idle | async | interaction (default: idle)\n\n  Prints each pixel as an INERT, consent-gated <script>: type=\"text/plain\" with the\n  library URL on data-src, so an undecided visitor's page issues no third-party\n  request. For stacks with no Astro integration — Bricks, WordPress, Eleventy.\n  Paste into your template; @getvitops/core's consent runtime activates them.\n\nAds lint options:\n  -i, --input <path>    Site config carrying site.ads (default: ./site.json)\n\n  Reports the gaps that are invisible at runtime: a click-ID parameter this\n  platform stamps that attribution doesn't capture, a pixel while site.tracking is\n  off (every conversion arrives unattributed), and a configured property with no\n  tag ID. Exits non-zero on a finding.\n\nCrm check options:\n  -i, --input <path>    Site config carrying site.crm (default: ./site.json)\n      --site-env <env>  Environment to resolve (default: production)\n\n  Fetches the live field/property list (HubSpot: crm/v3/properties/contacts;\n  Bigin: bigin/v2/settings/fields) and reports every fieldMap/trackingFields\n  target that doesn't exist there. HubSpot rejects a submission naming an\n  unrecognised property; Bigin silently ignores it — this is the only way to\n  see a broken mapping before a real submission finds it. Needs\n  VITOPS_HUBSPOT_ACCESS_TOKEN, VITOPS_ZOHO_CLIENT_ID/_CLIENT_SECRET/\n  _REFRESH_TOKEN, or (unused for now) VITOPS_JOBBER_CLIENT_ID/_CLIENT_SECRET/\n  _REFRESH_TOKEN, matching whichever provider site.crm names. Jobber currently\n  renders fieldMap/trackingFields as note-text lines rather than app-configured\n  custom fields, so there is nothing live to check there yet. Exits non-zero\n  on any missing target.\n\nCrm setup options:\n  -i, --input <path>    Site config carrying site.crm (default: ./site.json)\n      --site-env <env>  Environment to resolve (default: production)\n      --dry             Print what would be created and exit. Creates nothing.\n\n  HubSpot: creates missing contact properties named by fieldMap/trackingFields.\n  Bigin: no such API exists, so this always prints a manual reminder listing\n  the fields to add in Zoho Bigin's field editor, then re-run \"crm check\".\n  Jobber: app-configured custom fields aren't wired up yet, so this prints a\n  reminder instead of creating anything.\n\nSetup repo options:\n      --dry             Print the plan and exit\n      --check           Report drift/blocked steps and exit non-zero, mutating nothing\n      --public          Create the repo public (default: private)\n      --platform <p>    cloudflare (default) | node — shown for parity with the hosting stage's plan\n      --no-dev-resources  Same — this stage never provisions D1/R2 either way\n\n  Creates the GitHub repo (via `gh`), pushes main + dev, makes dev the default\n  branch, and requests main branch protection + the production/dev environments.\n  Idempotent — a re-run of a fully set-up repo is all skips. Branch protection and\n  environment reviewers 403 on a private repo without GitHub Pro/Team; that is\n  reported as blocked, with the manual Settings path, never as a failure.\n\nSetup hosting options:\n      --dry             Print the plan and exit\n      --check           Report drift/blocked steps and exit non-zero, mutating nothing\n      --platform <p>    cloudflare (default) | node\n      --no-dev-resources  Skip D1/R2 — a pure static Workers Assets project has\n                        nothing to provision, just the account id + token\n\n  Provisions the isolated dev D1 database + R2 bucket (cloudflare) and sets the\n  DEV_D1_ID / CLOUDFLARE_ACCOUNT_ID repo secrets, once `vitops setup repo` has run.\n  CLOUDFLARE_API_TOKEN is always reported as blocked — no API can create one; see\n  the printed dashboard link. Requires `npx wrangler login` first.\n\nSetup domain options:\n  -i, --input <path>    Site config (default: ./site.json)\n      --site-env <env>  Environment to check (default: production)\n      --dry             Print the plan and exit\n      --check           Exit non-zero if the domain state is inconsistent\n      --domain <apex>   Print the manual cutover steps for this apex\n\n  Plans and checks the consistency between wrangler.jsonc's workers.dev/custom-domain\n  state and site.json's environments/domains/robots — it NEVER edits wrangler.jsonc\n  or deploys. Cutover overwrites the zone's DNS record and can take an existing live\n  site down; that step is manual, on purpose. See SETUP.html's \"Domain strategy\" stage.\n\nSetup search options:\n  Forwards every option to `vitops search setup` unchanged — see \"Search setup\n  options:\" above.\n\nSetup ads options:\n  Forwards every option to `vitops ads setup` unchanged — see \"Ads setup options:\"\n  above.\n\nSetup all options:\n      --dry             Print every stage's plan and exit\n      --check           Report drift across every stage and exit non-zero\n      --public          Create the repo public, for the repo stage\n      --platform <p>    cloudflare (default) | node, for the repo + hosting stages\n      --no-dev-resources  Skip D1/R2 in the hosting stage (repo stage never provisions them)\n\n  Runs repo, hosting, search, ads in order. Stops at the first stage that fails;\n  a blocked step (the API token, GitHub Pro/Team gating) is reported, not fatal.\n\nEmail subcommands:\n  vitops email setup [domain]  Onboard a from-address domain, waiting for its DNS to resolve\n  vitops email check [opts]    Non-blocking deploy guard: warn if a from domain isn't onboarded\n\nEmail setup options:\n  -i, --input <path>    Site config carrying site.notifications.email (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n  [domain]              Onboard this exact name instead of deriving candidates from\n                        config + a source scan\n      --src <dir>       Source to scan for from: literals as a supplement to config\n                        (default: ./src)\n      --dry             Print the plan and exit. Needs no credential — plans from\n                        scratch and says so.\n      --check           Report drift and exit non-zero. Mutates nothing.\n      --no-prompt       Never ask before enabling a domain (the default when\n                        stdin is not a TTY, e.g. in CI — it just enables)\n      --timeout <s>     Cap on each DNS-propagation poll wait, in seconds (default: 5)\n\n  The onboarded entity is an EXACT name, and it is usually a subdomain\n  (send.example.com), never the apex a from address names. When the exact\n  domain is absent but a sibling in the same zone is already onboarded, this\n  is reported blocked rather than silently enabling the apex too — enabling\n  it rewrites _dmarc.<domain>, which can tighten policy on every OTHER mail\n  sent from that domain. Sending from the onboarded sibling is the\n  recommended fix. Needs CLOUDFLARE_API_TOKEN (Zone:Read + an Email Sending\n  scope — broader than the \"Edit zone DNS\" template other commands use).\n\nEmail check options:\n  -i, --input <path>    Site config carrying site.notifications.email (default: ./site.json)\n      --site-env <env>  Environment whose A/B variant applies (default: production)\n      --src <dir>       Source to scan for from: literals (default: ./src)\n      --strict          Exit non-zero on drift (the default just warns and exits 0)\n      --skip            Skip the check entirely (same as VITOPS_SKIP_EMAIL_CHECK)\n\n  Meant to run before a deploy. With no CLOUDFLARE_API_TOKEN it reports \"not\n  checked\" and exits 0, so a CI job without the secret never fails on the\n  check itself. Skip per-site with site.notifications.email.verifySender: false\n  when the scan can't see the real from address and the warning would be a\n  false positive.\n\nMedia options:\n      --raw <dir>       Directory of unprocessed video, walked recursively\n                        (default: ./raw)\n  -o, --out <dir>       Where the encoded outputs go (default: ./src/assets/processed).\n                        Subdirectories under --raw are preserved.\n      --max-width <px>  Cap the output width, keeping aspect ratio (default: 1920;\n                        0 disables scaling)\n      --crf <n>         Quality on VP9's scale, 0-63, lower is better (default: 32).\n                        The MP4 fallback uses the equivalent on H.264's scale.\n      --max-bitrate <r> Optional ceiling, e.g. 2M or 800k (default: none, which is\n                        constant quality rather than constrained)\n      --audio           Keep the audio track (default: dropped — the common case is\n                        a muted autoplay loop)\n      --poster-time <s> Timestamp the poster frame is taken from (default: 0, which\n                        is often black on a clip that fades in)\n      --outputs <list>  Comma-separated: webm | mp4 | poster (default: all three)\n      --manifest <path> Cache file (default: .vitops/media-manifest.json)\n      --force           Re-encode everything, ignoring the cache\n      --dry             Print the plan and exit. Encodes nothing.\n\n  Needs ffmpeg on PATH — it is an external tool, not an npm dependency, and this\n  command fails rather than quietly skipping. Commit the outputs and the manifest:\n  ffmpeg output is not reproducible across versions, so re-encoding in CI churns\n  the diff on every toolchain bump. Use --force when you mean to re-encode.\n\nCommon:\n  -h, --help            Show this help\n";
 }
 
-//#endregion
-//#region src/commands/search.ts
+// src/commands/search.ts
 /**
 * `vitops search` — everything that talks to search engines: `setup` onboards a
 * domain into Search Console (DNS + verification + property), `notify` tells the
@@ -866,10 +862,9 @@ function helpFor(command, argv) {
 /**
 * Adapt a `Config` to the indexing module's own option shape.
 *
-* A flat field map, as intended: `@getvitops/utils` cannot import from the
-* generator (the generator already depends on it), so `IndexingConfig` mirrors the
-* `seo.indexing` block rather than being it. The one piece of judgment here is the
-* origin — see below.
+* `IndexNowConfig` and `SearchConsoleConfig` are the schema's own types now, so those blocks pass
+* straight through. What this adapter still does is genuine resolution — the origin and the
+* robots policy come from the resolved environment, not from the `seo.indexing` block — see below.
 */
 function toIndexingConfig(cfg, siteEnv) {
 	const site = cfg.site;
@@ -888,16 +883,15 @@ function toIndexingConfig(cfg, siteEnv) {
 /**
 * Adapt a `Config` to the onboarding module's own option shape.
 *
-* The same flat field map as `toIndexingConfig`, and for the same reason — utils
-* cannot import the generator. `--domain` scopes to a single `site.searchConsole`
-* entry, and a name that isn't there is an error, not an empty run.
+* `DomainSetup` is the `site.searchConsole.<domain>` block plus its key, so this is a spread and a
+* filter. `--domain` scopes to a single entry, and a name that isn't there is an error, not an
+* empty run.
 */
 function toSearchConsoleSetup(cfg, domainFilter) {
 	const entries = cfg.site.searchConsole ?? {};
 	const setups = Object.entries(entries).map(([domain, e]) => ({
-		domain,
-		...e.delegatedOwners ? { delegatedOwners: e.delegatedOwners } : {},
-		...e.fullUserGroup ? { fullUserGroup: e.fullUserGroup } : {}
+		...e,
+		domain
 	}));
 	return pickOne(setups, domainFilter, (s) => s.domain, {
 		flag: "domain",
@@ -1258,8 +1252,7 @@ async function cmdSearch(argv) {
 	}
 }
 
-//#endregion
-//#region src/prompt.ts
+// src/prompt.ts
 /**
 * Asking for the config values `vitops ads setup` cannot derive, and writing the
 * answers back.
@@ -1396,8 +1389,7 @@ function writeConfigPatch(path, provider, field, value) {
 	return { written: true };
 }
 
-//#endregion
-//#region src/commands/ads.ts
+// src/commands/ads.ts
 /**
 * `vitops ads` — everything that links this site to an ad platform. Three
 * subcommands, split by what they touch: `setup` writes DNS, `tags` writes
@@ -1406,9 +1398,10 @@ function writeConfigPatch(path, provider, field, value) {
 /**
 * Adapt a `Config` to the ads module's own option shape.
 *
-* The same flat field map as `toSearchConsoleSetup` and `toIndexingConfig`, for the
-* same reason — utils cannot import the generator. The domain default is the one
-* derived value: a platform verifies the host the site is published at, so
+* `AdPropertySetup` is the `site.ads.<provider>` block plus its key, so this spreads the block.
+* (It used to copy a hand-picked subset of fields, which silently dropped `conversionActionId` and
+* `reporting` on the way to the planner.) The domain default is the one derived value: a platform
+* verifies the host the site is published at, so
 * `domains.canonical` answers it, and only an ad account verified against some
 * other host needs `site.ads.<provider>.domain` stated.
 */
@@ -1427,14 +1420,9 @@ function toAdProperties(cfg, providerFilter) {
 		const e = entries[provider];
 		const domain = e.domain ?? canonicalHost;
 		return {
+			...e,
 			provider,
-			...e.accountId ? { accountId: e.accountId } : {},
-			...e.pixelId ? { pixelId: e.pixelId } : {},
-			...e.conversionLabel ? { conversionLabel: e.conversionLabel } : {},
-			...domain ? { domain } : {},
-			...e.domainVerification ? { domainVerification: e.domainVerification } : {},
-			...e.category ? { category: e.category } : {},
-			...e.enabled != null ? { enabled: e.enabled } : {}
+			...domain ? { domain } : {}
 		};
 	});
 	if (providerFilter && !isAdProvider(providerFilter)) fail(`--provider "${providerFilter}" is not a known ad platform (expected: ${AD_PROVIDER_KEYS.join(" | ")})`);
@@ -1649,6 +1637,12 @@ async function cmdAdsLint(argv) {
 		const uncaptured = platform.clickIdParams.filter((param) => !(param in PLATFORM_PARAMS));
 		if (uncaptured.length) findings.push(`${p.provider}: click ID ${uncaptured.join(", ")} is not in the capture vocabulary — every conversion from this platform will arrive unattributed`);
 		if (!trackingOn) findings.push(`${p.provider}: site.tracking.enabled is not true, so ${platform.clickIdParams.join("/")} is never captured — conversions will be unattributed`);
+		if (p.provider === "google" && p.reporting === "server") {
+			const labels = normalizeConversionLabels(p.conversionLabel);
+			const actionIds = normalizeConversionActionIds(p.conversionActionId);
+			const configuredNoId = Object.keys(labels).filter((action) => labels[action] && !actionIds[action]);
+			if (configuredNoId.length) findings.push(`google: reporting is "server" but conversionActionId.${configuredNoId.join(", .")} is not set — ${configuredNoId.length === 1 ? "that action" : "those actions"} still fire client-side, not a failure but not what "server" asked for either`);
+		}
 	}
 	if (findings.length === 0) {
 		console.log(`✓ ${properties.length} ad propert${properties.length === 1 ? "y" : "ies"} check out`);
@@ -1672,8 +1666,7 @@ async function cmdAds(argv) {
 	}
 }
 
-//#endregion
-//#region src/commands/crm.ts
+// src/commands/crm.ts
 /**
 * `vitops crm` — the two things `site.crm` needs a human-in-the-loop for.
 *
@@ -1858,8 +1851,7 @@ async function cmdCrm(argv) {
 	}
 }
 
-//#endregion
-//#region src/commands/email.ts
+// src/commands/email.ts
 /**
 * `vitops email` — connect `site.notifications.email.from` to whether its domain
 * is actually onboarded onto an outbound email provider.
@@ -2172,8 +2164,7 @@ async function cmdEmail(argv) {
 	}
 }
 
-//#endregion
-//#region src/commands/setup.ts
+// src/commands/setup.ts
 /**
 * `vitops setup` — the scripted path from an empty scaffold to a live site.
 * Subcommands: `repo | hosting | domain | search | ads | all`.
@@ -2588,8 +2579,7 @@ async function cmdSetup(argv) {
 	}
 }
 
-//#endregion
-//#region src/agents.ts
+// src/agents.ts
 /**
 * Side-effect-free helpers for the `vitops agents` / `vitops docs` commands.
 * Kept out of cli.ts (which runs main() on import) so they are unit-testable.
@@ -2654,6 +2644,11 @@ const TOPICS = {
 		path: "concepts/legal.md",
 		summary: "privacy policy / terms / cookie notice derived from config facts"
 	},
+	blocks: {
+		path: "",
+		external: "emdash",
+		summary: "EmDash Portable Text blocks and every field (needs @getvitops/emdash installed)"
+	},
 	elements: {
 		path: "bricks/elements.md",
 		summary: "Bricks Builder custom elements, controls, defaults"
@@ -2705,8 +2700,7 @@ function linkSkill(linkPath, targetDir) {
 	}
 }
 
-//#endregion
-//#region src/css-scan.ts
+// src/css-scan.ts
 /** Strip comments, preserving newlines so line numbers survive. */
 function stripComments(css) {
 	return css.replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ""));
@@ -2808,8 +2802,7 @@ function extractStyleBlocks(src) {
 	return out;
 }
 
-//#endregion
-//#region src/lint-css.ts
+// src/lint-css.ts
 /**
 * The framework's own track widths. Declared in two places today
 * (`core/css/layout.css` and the tailwind emitter), so a rule keyed to the token
@@ -3024,8 +3017,7 @@ function lintCss(files, format) {
 	return findings;
 }
 
-//#endregion
-//#region src/lint-markup.ts
+// src/lint-markup.ts
 /**
 * The third linting direction: markup that lays out a repeated set of things
 * without the framework's pattern for it.
@@ -3247,8 +3239,7 @@ function lintMarkup(files) {
 	return findings;
 }
 
-//#endregion
-//#region src/lint-tokens.ts
+// src/lint-tokens.ts
 /**
 * Rewrite every old name in one pass.
 *
@@ -3304,8 +3295,7 @@ function lintTokens(files, renames) {
 	return findings;
 }
 
-//#endregion
-//#region src/lint.ts
+// src/lint.ts
 /**
 * `vitops lint` — find framework classes in consumer source that resolve to
 * nothing in the format being built.
@@ -3488,8 +3478,7 @@ function lintSource(files, v, format) {
 	return findings;
 }
 
-//#endregion
-//#region src/cli.ts
+// src/cli.ts
 /**
 * `vitops` — CLI for the Vitops design-system generator.
 *
@@ -4157,7 +4146,7 @@ function generatorAssetsDir() {
 const AGENTS_START = "<!-- vitops:start -->";
 const AGENTS_END = "<!-- vitops:end -->";
 /** Print a live reference doc (rendered from the project's config) to stdout. */
-function cmdDocs(argv) {
+async function cmdDocs(argv) {
 	const { values, positionals } = parseArgs({
 		args: argv,
 		options: {
@@ -4181,10 +4170,31 @@ function cmdDocs(argv) {
 		return;
 	}
 	if (topic && !TOPICS[topic]) fail(`unknown topic "${topic}". Valid topics:\n${topicList()}`);
-	const ds = loadDesignSystem(resolve(values.input), values.theme);
-	const docs = generateDocs(ds, generatorAssetsDir());
-	const paths = values.all ? Object.values(TOPICS).map((t) => t.path) : [TOPICS[topic].path];
-	process.stdout.write(paths.map((p) => docs[p]).join("\n"));
+	const names = values.all ? Object.keys(TOPICS) : [topic];
+	const docs = names.every((n) => TOPICS[n].external) ? {} : generateDocs(loadDesignSystem(resolve(values.input), values.theme), generatorAssetsDir());
+	const parts = [];
+	for (const name of names) {
+		const t = TOPICS[name];
+		if (!t.external) {
+			parts.push(docs[t.path]);
+			continue;
+		}
+		const doc = await externalDoc(t.external);
+		if (doc) parts.push(doc);
+		else if (!values.all) fail(`topic "${name}" needs @getvitops/${t.external} installed in this project`);
+	}
+	process.stdout.write(parts.join("\n"));
+}
+/** Render a topic owned by an optional package, resolved from the project, not from the CLI. */
+async function externalDoc(pkg) {
+	try {
+		const manifest = createRequire(join(process.cwd(), "package.json")).resolve(`@getvitops/${pkg}/package.json`);
+		const exp = JSON.parse(readFileSync(manifest, "utf8")).exports["."].import;
+		const entry = join(dirname(manifest), exp);
+		return (await import(pathToFileURL(entry).href)).renderBlocksDoc?.() ?? null;
+	} catch {
+		return null;
+	}
 }
 function cmdLint(argv) {
 	const { values, positionals } = parseArgs({
@@ -4471,6 +4481,5 @@ async function main() {
 }
 main().catch((err) => fail(msg(err)));
 
-//#endregion
 export {  };
 //# sourceMappingURL=cli.mjs.map