@getvitops/cli 3.0.0 → 4.1.0

package/dist/cli.mjs

@@ -4,10 +4,14 @@ import { parseArgs } from "node:util";
 import { existsSync, lstatSync, mkdirSync, readFileSync, readlinkSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
 import { dirname, join, parse, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
-import { NUMERIC_STEPS, SCHEMA_URL, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
+import { JURISDICTION_COUNTRIES, NUMERIC_STEPS, SCHEMA_URL, buildIconSprite, defaultConfig, enabledDocs, expandPalette, functionalRole, generate, generateDocs, generateLegal, isConfig, processorsMissingLocation, resolveConfig, resolveInput, resolveTheme, roleColorUtilities, roleHue, roleKind, validate } from "@getvitops/generator";
 import { collectIconRefs, generateFavicons, generateIconInclude, resolveIcon, scanFiles } from "@getvitops/utils";
-import { SNAPSHOT_PATH, collectEntries, formatPlan, getAccessToken, inspectUrl, keyFileContents, newKey, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
-import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$1, processMedia } from "@getvitops/utils/media";
+import { SCOPES, SNAPSHOT_PATH, collectEntries, formatPlan, googleAccessToken, inspectUrl, keyFileContents, newKey, parseServiceAccount, plan, readSnapshot, resolveKeyLocation, resolveSitemapUrl, submitBatch, submitSitemap, toSnapshot, verifyKeyFile, writeSnapshot } from "@getvitops/utils/indexing";
+import { addSite, backoffSchedule, createApexTxt, findZoneId, formatPlan as formatPlan$1, formatSummary, getSite, getVerificationToken, getWebResource, hasDrift, listApexTxt, ownerUnion, plan as plan$1, refreshTokenGrant, siteUrlFor, updateOwners, verifyWebResource } from "@getvitops/utils/onboarding";
+import { AD_PLATFORMS, AD_PROVIDER_KEYS, formatPlan as formatPlan$2, formatSummary as formatSummary$1, hasDrift as hasDrift$1, isAdProvider, missingFields, plan as plan$2, renderTag, tagId } from "@getvitops/utils/ads";
+import { PLATFORM_PARAMS } from "@getvitops/utils/tracking";
+import { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$3, processMedia } from "@getvitops/utils/media";
+import { createInterface } from "node:readline/promises";
 
 //#region src/agents.ts
 /**
@@ -54,6 +58,26 @@ const TOPICS = {
 		path: "concepts/patterns.md",
 		summary: "pattern CSS: token cascade, override hooks, states, role variants"
 	},
+	components: {
+		path: "concepts/components.md",
+		summary: "which of the four tiers provides each pattern, and the call to make"
+	},
+	consent: {
+		path: "concepts/consent.md",
+		summary: "the consent gate: inert gated tags, demand-driven prompting, three-valued choices"
+	},
+	tracking: {
+		path: "concepts/tracking.md",
+		summary: "ad-click attribution, the `_ac` cookie, conversion notifications"
+	},
+	search: {
+		path: "concepts/search.md",
+		summary: "what search engines accept, Search Console onboarding, deploy notification"
+	},
+	legal: {
+		path: "concepts/legal.md",
+		summary: "privacy policy / terms / cookie notice derived from config facts"
+	},
 	elements: {
 		path: "bricks/elements.md",
 		summary: "Bricks Builder custom elements, controls, defaults"
@@ -105,6 +129,144 @@ function linkSkill(linkPath, targetDir) {
 	}
 }
 
+//#endregion
+//#region src/prompt.ts
+/**
+* Asking for the config values `vitops ads setup` cannot derive, and writing the
+* answers back.
+*
+* The realistic first run has no verification token in the config, because the
+* token does not exist until someone opens the platform UI and asks for one. That
+* makes a missing token a **question**, not an error — but only when there is
+* somebody there to answer it, which is why every decision about *whether* to ask
+* is made here and the planner stays pure.
+*
+* The split mirrors the rest of the toolchain: `questionFor` and `patchRaw` are
+* pure and tested; `ask` and `writeConfigPatch` are the I/O, and they decide
+* nothing.
+*
+* Two rules hold the whole file together:
+*
+*  - **A prompt must never hang a CI run.** Asking requires a TTY and an explicit
+*    absence of `--dry` / `--check` / `--no-prompt`; otherwise the caller gets the
+*    same named error it would have got before this file existed.
+*  - **A fact about the site goes in the config; a credential stays in the
+*    environment.** A verification token is published in DNS — the platform
+*    fetching it back is the ownership proof — so persisting it is right, and it is
+*    the only thing here that gets written. `CLOUDFLARE_API_TOKEN` may be typed at
+*    a prompt and lives only in the process.
+*/
+/**
+* What to ask for one gap, and where the operator finds it.
+*
+* The hints are the point. "meta.domainVerification is missing" is true and
+* useless; the UI path plus the console URL is the difference between a prompt
+* someone can answer now and one they abandon to go searching.
+*/
+function questionFor(provider, needs) {
+	const platform = AD_PLATFORMS[provider];
+	if (needs === "domainVerification") return {
+		provider,
+		needs,
+		title: `${platform.name} — domain verification token`,
+		hints: [...platform.verification.where ? [platform.verification.where] : [], platform.consoleUrl],
+		label: platform.verification.txtPrefix ?? "token"
+	};
+	const what = needs === "pixelId" ? provider === "google" ? "conversion ID (AW-…, not the customer ID)" : "pixel / tag ID" : "advertising account ID";
+	return {
+		provider,
+		needs,
+		title: `${platform.name} — ${what}`,
+		hints: [platform.consoleUrl],
+		label: needs
+	};
+}
+/** The error a non-interactive run gets instead of a prompt. */
+function missingFieldMessage(provider, needs) {
+	const q = questionFor(provider, needs);
+	return `site.ads.${provider}.${needs} is not set — ${q.title}.\n` + q.hints.map((h) => `  ${h}`).join("\n") + `\n  Run this interactively to be prompted for it, or add it to the config yourself.`;
+}
+/** Whether this run is allowed to ask. Everything that would hang CI is checked here. */
+function canPrompt(opts) {
+	if (opts.dry || opts.check || opts.noPrompt) return false;
+	return opts.isTty ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
+}
+/**
+* Ask one question. An empty answer means "skip this one" — reported as still
+* blocked rather than treated as a value, so nothing is written and nothing is
+* created on the strength of a stray Enter.
+*/
+async function ask(q) {
+	const rl = createInterface({
+		input: process.stdin,
+		output: process.stdout
+	});
+	try {
+		console.log(`\n${q.title}`);
+		for (const hint of q.hints) console.log(`  ${hint}`);
+		return (await rl.question(`  ${q.label} `)).trim() || void 0;
+	} finally {
+		rl.close();
+	}
+}
+/**
+* Merge one ad-property field into a **raw, on-disk** config object.
+*
+* Raw is load-bearing, and it is the rule `@getvitops/vite`'s `designSystemPath()`
+* already follows for the theme editor's save: `resolveConfig` normalises shorthand
+* shapes and resolves `extends` in memory, so writing from the resolved object
+* would grow keys beside the author's and silently edit a copy nothing builds from.
+* Everything outside `site.ads.<provider>.<field>` is left exactly as it was.
+*/
+function patchRaw(raw, provider, field, value) {
+	if (typeof raw !== "object" || raw == null || Array.isArray(raw)) throw new Error("config is not an object");
+	const root = raw;
+	const site = root["site"] ?? {};
+	const ads = site["ads"] ?? {};
+	const entry = ads[provider] ?? {};
+	return {
+		...root,
+		site: {
+			...site,
+			ads: {
+				...ads,
+				[provider]: {
+					...entry,
+					[field]: value
+				}
+			}
+		}
+	};
+}
+/** Indentation the file already uses, so a patch doesn't reformat the whole document. */
+function detectIndent(source) {
+	const match = /\n([ \t]+)"/.exec(source);
+	if (!match?.[1]) return 2;
+	return match[1].includes("	") ? "	" : match[1].length;
+}
+/**
+* Persist one answered field into the config file.
+*
+* JSON only: a `.js`/`.ts` config is code, and rewriting code to insert a value is
+* a different (and much worse) problem than merging an object — so the caller is
+* told to paste it instead. Returns whether it wrote.
+*/
+function writeConfigPatch(path, provider, field, value) {
+	if (!path.endsWith(".json")) return {
+		written: false,
+		reason: `${path} is a module, not JSON — add "${field}": "${value}" to site.ads.${provider} yourself`
+	};
+	if (!existsSync(path)) return {
+		written: false,
+		reason: `${path} no longer exists`
+	};
+	const source = readFileSync(path, "utf8");
+	const next = patchRaw(JSON.parse(source), provider, field, value);
+	const trailingNewline = source.endsWith("\n") ? "\n" : "";
+	writeFileSync(path, JSON.stringify(next, null, detectIndent(source)) + trailingNewline);
+	return { written: true };
+}
+
 //#endregion
 //#region src/css-scan.ts
 /** Strip comments, preserving newlines so line numbers survive. */
@@ -536,7 +698,8 @@ function lintSource(files, v, format) {
 *   vitops docs      [topic] [--input <json>] [--all]
 *   vitops lint      [--input <json>] [--format <fmt>] [--src <dir>]
 *   vitops legal     [--input <site.json>] [--doc <name>] [--format <md|html|portable-text>] [--out <dir>]
-*   vitops indexing  [--input <site.json>] [--dry] [--all] [--check]
+*   vitops search    setup [--domain <name>] [--dry] [--check]  |  notify [--dry] [--all] [--check]
+*   vitops ads       setup [--provider <name>] [--dry] [--check]  |  tags  |  lint
 *   vitops media     [--raw <dir>] [--out <dir>] [--force] [--dry]
 *
 * Thin wrapper over @getvitops/generator (generation) and @getvitops/utils (favicons).
@@ -580,7 +743,8 @@ Usage:
   vitops lint [options]         Report framework classes in your source that resolve to nothing
   vitops legal [options]        Render legal documents from a site config
   vitops icons [options]        Report which icons your source uses, and build the sprite
-  vitops indexing [options]    Tell search engines about a deploy (sitemap + IndexNow)
+  vitops search <sub> [opts]    Search Console: onboard domains (setup) + notify deploys (notify)
+  vitops ads <sub> [opts]       Ad properties: verify domains (setup) + emit pixels (tags) + lint
   vitops media [options]       Encode raw video into web-ready WebM + MP4 + poster
 
 Generate options:
@@ -654,7 +818,29 @@ Legal options:
   Generated from your config — a starting point, not legal advice. Review before
   publishing, and make sure the config describes what your site actually does.
 
-Indexing options:
+Search subcommands:
+  vitops search setup [opts]    Onboard site.searchConsole domains into GSC
+  vitops search notify [opts]   Tell search engines about a deploy (sitemap + IndexNow)
+
+Search setup options:
+  -i, --input <path>    Site config carrying site.searchConsole (default: ./site.json)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+      --domain <name>   Scope to a single site.searchConsole entry
+      --dry             Print the plan and exit. Changes nothing.
+      --check           Report drift and exit non-zero if any domain is not fully
+                        onboarded. Mutates nothing.
+
+  For each domain it ensures the apex verification TXT in Cloudflare, verifies
+  ownership (DNS_TXT, retried with backoff while DNS propagates — a still-
+  unverified domain is reported PENDING, not failed), adds the sc-domain: property,
+  and adds any delegatedOwners to the web resource. DNS is only ever created,
+  never edited or deleted. Credentials come from the environment:
+  CLOUDFLARE_API_TOKEN (Zone:DNS:Edit), and VITOPS_GOOGLE_CLIENT_ID /
+  VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN (a user OAuth token
+  scoped to siteverification + webmasters). Granting a Google Group Full-User
+  access has no API and is surfaced as a reminder.
+
+Search notify options:
   -i, --input <path>    Site config carrying seo.indexing (default: ./site.json)
       --site-env <env>  Environment to notify for (default: production). An
                         environment whose robots policy says noindex is refused.
@@ -671,13 +857,63 @@ Indexing options:
                         Persist it between runs (a CI cache) or every run submits
                         everything.
 
-  What this can and cannot do: Google exposes no "request indexing" API, and its
+  What notify can and cannot do: Google exposes no "request indexing" API, and its
   sitemap ping endpoint was removed in 2023 — so it resubmits your sitemap
   through the Search Console API and verifies the result with --check. IndexNow
   reaches Bing, Yandex, Naver, Seznam and Yep; Google does not participate.
-  Search Console needs a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
-  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), added as an owner of the
-  property.
+  Search Console takes either credential, whichever you already have, added as an
+  owner of the property: a service account in VITOPS_GSC_SERVICE_ACCOUNT (inline
+  JSON) or GOOGLE_APPLICATION_CREDENTIALS (a path), or the same user OAuth
+  credential "search setup" uses (VITOPS_GOOGLE_CLIENT_ID / _CLIENT_SECRET /
+  _REFRESH_TOKEN). The service account is preferred when both are set — this runs
+  on every deploy, and it does not expire.
+
+Ads subcommands:
+  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record
+  vitops ads tags [opts]        Print the consent-gated pixel snippets
+  vitops ads lint [opts]        Report ad properties the rest of the config can't see
+
+Ads setup options:
+  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
+      --site-env <env>  Environment whose A/B variant applies (default: production)
+      --provider <name> Scope to one site.ads entry (google | meta | linkedin |
+                        reddit | tiktok | microsoft | pinterest | snapchat)
+      --dry             Print the plan and exit. Creates nothing — but it does READ
+                        live DNS first, so it needs CLOUDFLARE_API_TOKEN.
+      --check           Report drift and exit non-zero if any property is not
+                        linked. Mutates nothing, prompts for nothing.
+      --no-prompt       Never ask for a missing token; fail with the field name
+                        instead (the default when stdin is not a TTY, e.g. in CI)
+      --no-write        Don't persist an answered token back into the config
+
+  Four platforms verify a domain by DNS TXT — Meta, TikTok, Pinterest, Snapchat —
+  and that record is the one thing this creates for you (in Cloudflare, via
+  CLOUDFLARE_API_TOKEN; created only, never edited or deleted). Google Ads,
+  LinkedIn, Reddit and Microsoft Ads have no domain verification at all: linking
+  there is the tag and the account ID, and the run says so rather than skipping in
+  silence. No platform Marketing API is called — Meta's needs a system-user token
+  and Google's needs an approved developer token, so the final "Verify" click stays
+  a reminder. The verification token is not a secret (it is published in DNS, which
+  is the ownership proof), so it lives in the config and is prompted for on the
+  first run.
+
+Ads tags options:
+  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
+      --provider <name> Print one platform's tag
+      --strategy <s>    idle | async | interaction (default: idle)
+
+  Prints each pixel as an INERT, consent-gated <script>: type="text/plain" with the
+  library URL on data-src, so an undecided visitor's page issues no third-party
+  request. For stacks with no Astro integration — Bricks, WordPress, Eleventy.
+  Paste into your template; @getvitops/core's consent runtime activates them.
+
+Ads lint options:
+  -i, --input <path>    Site config carrying site.ads (default: ./site.json)
+
+  Reports the gaps that are invisible at runtime: a click-ID parameter this
+  platform stamps that attribution doesn't capture, a pixel while site.tracking is
+  off (every conversion arrives unattributed), and a configured property with no
+  tag ID. Exits non-zero on a finding.
 
 Media options:
       --raw <dir>       Directory of unprocessed video, walked recursively
@@ -707,6 +943,21 @@ Media options:
 Common:
   -h, --help            Show this help
 `;
+const SEARCH_HELP = `vitops search — Google Search Console
+
+  vitops search setup [opts]    Onboard site.searchConsole domains as GSC domain properties
+  vitops search notify [opts]   Tell search engines a deploy happened (sitemap + IndexNow)
+
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
+const ADS_HELP = `vitops ads — link this site to its ad properties
+
+  vitops ads setup [opts]       Ensure each platform's domain-verification DNS record
+  vitops ads tags [opts]        Print the consent-gated pixel snippets
+  vitops ads lint [opts]        Report ad properties the rest of the config can't see
+
+Run \`vitops --help\` for the full option list for each subcommand.
+`;
 function fail(msg) {
 	console.error(`✖ ${msg}`);
 	process.exit(1);
@@ -959,7 +1210,7 @@ async function cmdMedia(argv) {
 			onProgress: (message) => console.error(`  … ${message}`)
 		});
 		if (values.dry) {
-			console.log(formatPlan$1(result.plan));
+			console.log(formatPlan$3(result.plan));
 			return;
 		}
 		console.log(`✓ media → ${values.out} (${result.written.length} written, ${result.skipped} unchanged)`);
@@ -1202,6 +1453,15 @@ async function cmdLegal(argv) {
 		docs,
 		output
 	});
+	/**
+	* A processor placed nowhere cannot appear in the cross-border disclosure — there
+	* is nothing true to say about it — so it drops out of that section silently,
+	* which is the failure that looks tidy. Reported here rather than in the document:
+	* a policy must not editorialise about its own gaps.
+	*
+	* On **stderr** because stdout is the document and gets piped or redirected.
+	*/
+	if (docs.includes("privacy")) for (const name of processorsMissingLocation(site)) console.error(`  ! ${name}: no country, storage or operatorCountry declared — it will not appear in the cross-border transfer disclosure. Add one, or state storage: [{ country: "${JURISDICTION_COUNTRIES[site.site.legal?.jurisdiction ?? "ca"]}" }] to say it does not leave the country.`);
 	if (!values.out) {
 		process.stdout.write(Object.values(files).join("\n"));
 		return;
@@ -1275,7 +1535,7 @@ const readSitemap = async (source) => {
 * The Indexing API is deliberately absent — see `@getvitops/utils/indexing`'s
 * `gsc.ts`.
 */
-async function cmdIndexing(argv) {
+async function cmdSearchNotify(argv) {
 	const { values } = parseArgs({
 		args: argv,
 		options: {
@@ -1318,7 +1578,7 @@ async function cmdIndexing(argv) {
 		const key = newKey();
 		console.log(key);
 		console.log(`\n  Add to your site config:\n    "seo": { "indexing": { "indexNow": { "key": "${key}" } } }`);
-		console.log(`  Then serve it at /${key}.txt — \`vitops indexing --write-key public\`.`);
+		console.log(`  Then serve it at /${key}.txt — \`vitops search notify --write-key public\`.`);
 		return;
 	}
 	const config = toIndexingConfig(await loadConfig(resolve(values.input), values["site-env"]), values["site-env"]);
@@ -1354,13 +1614,13 @@ async function cmdIndexing(argv) {
 		console.log("\n(--dry: nothing was submitted)");
 		return;
 	}
-	const account = loadServiceAccount();
+	const credential = loadSearchCredential();
 	let failed = false;
 	if (values.check) {
 		if (!p.searchConsole.siteUrl) fail("--check needs seo.indexing.searchConsole.siteUrl (the Search Console property)");
-		if (!account) fail("--check needs a Search Console service account in VITOPS_GSC_SERVICE_ACCOUNT or GOOGLE_APPLICATION_CREDENTIALS");
+		if (!credential) fail(`--check needs a Search Console credential — ${CREDENTIAL_HINT}`);
 		if (p.check.length === 0) fail("--check needs seo.indexing.priorityUrls — the pages whose indexing matters");
-		const token = await getAccessToken(account);
+		const token = await googleAccessToken(credential);
 		console.log(`\nInspecting ${p.check.length} priority URL(s):`);
 		for (const url of p.check) {
 			const r = await inspectUrl(token, p.searchConsole.siteUrl, url);
@@ -1384,7 +1644,7 @@ async function cmdIndexing(argv) {
 		const check = await verifyKeyFile(keyLocation, key);
 		if (!check.ok) {
 			console.error(`✖ IndexNow key file check failed — ${check.reason}`);
-			console.error(`  Write it with: vitops indexing --write-key <public dir>`);
+			console.error(`  Write it with: vitops search notify --write-key <public dir>`);
 			failed = true;
 		} else {
 			let sent = 0;
@@ -1400,9 +1660,9 @@ async function cmdIndexing(argv) {
 			if (!failed) console.log(`✓ IndexNow: ${sent} URL(s) submitted`);
 		}
 	}
-	if (p.searchConsole.enabled) if (!account) console.log("· Search Console: skipped — no VITOPS_GSC_SERVICE_ACCOUNT / GOOGLE_APPLICATION_CREDENTIALS");
+	if (p.searchConsole.enabled) if (!credential) console.log(`· Search Console: skipped — no credential (${CREDENTIAL_HINT})`);
 	else {
-		const r = await submitSitemap(await getAccessToken(account), p.searchConsole.siteUrl, sitemapUrl);
+		const r = await submitSitemap(await googleAccessToken(credential), p.searchConsole.siteUrl, sitemapUrl);
 		if (r.ok) console.log(`✓ Search Console: sitemap resubmitted`);
 		else {
 			console.error(`✖ Search Console: ${r.message}`);
@@ -1414,7 +1674,581 @@ async function cmdIndexing(argv) {
 		writeSnapshot(snapshotPath, toSnapshot(sitemapUrl, current, (/* @__PURE__ */ new Date()).toISOString()));
 		console.log(`  state → ${relative(process.cwd(), snapshotPath)}`);
 	}
-	if (p.check.length > 0) console.log(`\n  Indexing is not instant. Run \`vitops indexing --check\` in a day or two to see what Google actually did.`);
+	if (p.check.length > 0) console.log(`\n  Indexing is not instant. Run \`vitops search notify --check\` in a day or two to see what Google actually did.`);
+}
+/**
+* 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.
+*/
+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 } : {}
+	}));
+	if (domainFilter) {
+		const one = setups.find((s) => s.domain === domainFilter);
+		if (!one) fail(`--domain "${domainFilter}" is not in site.searchConsole (have: ${setups.map((s) => s.domain).join(", ") || "none"})`);
+		return [one];
+	}
+	return setups;
+}
+/**
+* The Cloudflare DNS credential. From the environment only — a `site.json` is
+* committed, and this is a real secret. A `Zone:DNS:Edit` token (the standard
+* "Edit zone DNS" template, which also carries `Zone:Read`).
+*/
+function loadCloudflareToken() {
+	return process.env.CLOUDFLARE_API_TOKEN || void 0;
+}
+/**
+* The Google user-OAuth credential (refresh-token flow), from the environment.
+*
+* A user token, not a service account: onboarding acts *as a person* who can own
+* the sites. All-or-nothing — a partial set is a misconfiguration worth naming
+* rather than a reason to run degraded.
+*/
+function loadGoogleOAuth() {
+	const clientId = process.env.VITOPS_GOOGLE_CLIENT_ID;
+	const clientSecret = process.env.VITOPS_GOOGLE_CLIENT_SECRET;
+	const refreshToken = process.env.VITOPS_GOOGLE_REFRESH_TOKEN;
+	if (!clientId && !clientSecret && !refreshToken) return void 0;
+	const missing = [
+		["VITOPS_GOOGLE_CLIENT_ID", clientId],
+		["VITOPS_GOOGLE_CLIENT_SECRET", clientSecret],
+		["VITOPS_GOOGLE_REFRESH_TOKEN", refreshToken]
+	].filter(([, v]) => !v).map(([k]) => k);
+	if (missing.length) fail(`incomplete Google OAuth credential — missing ${missing.join(", ")}`);
+	return {
+		clientId,
+		clientSecret,
+		refreshToken
+	};
+}
+/**
+* The Google identity for `search notify`, preferring a service account.
+*
+* Search Console accepts either, and the preference is about *where this command
+* runs*: it fires on every deploy, in CI, and a service account has no expiry,
+* while a refresh token can be revoked — and for an OAuth client still in
+* *Testing* publishing status Google expires it after 7 days, which is a bad
+* property for a deploy step. So the robot wins when it is available.
+*
+* The fallback is the point, though. `search setup` needs user OAuth (verifying
+* a site makes the caller an owner, which should be a person), so a consumer who
+* ran setup already has a Google credential. Demanding a second, unrelated one
+* for the other half of the same command bought nothing.
+*/
+function loadSearchCredential() {
+	const account = loadServiceAccount();
+	if (account) return {
+		kind: "service-account",
+		account,
+		scope: SCOPES.webmasters
+	};
+	const oauth = loadGoogleOAuth();
+	return oauth ? {
+		kind: "oauth",
+		oauth
+	} : void 0;
+}
+/** Both spellings, for an error that has to tell you what to actually set. */
+const CREDENTIAL_HINT = "a service account in VITOPS_GSC_SERVICE_ACCOUNT / GOOGLE_APPLICATION_CREDENTIALS, or a user OAuth credential in VITOPS_GOOGLE_CLIENT_ID / VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN";
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+* `vitops search` — everything that talks to search engines.
+*
+* Two subcommands, split by what they touch: `setup` onboards a domain into
+* Search Console (DNS + verification + property), `notify` tells the engines a
+* deploy happened (sitemap + IndexNow). `notify` is the former top-level
+* `vitops indexing`.
+*/
+async function cmdSearch(argv) {
+	const [sub, ...rest] = argv;
+	switch (sub) {
+		case "setup": return cmdSearchSetup(rest);
+		case "notify": return cmdSearchNotify(rest);
+		case void 0:
+		case "-h":
+		case "--help":
+			console.log(SEARCH_HELP);
+			return;
+		default: fail(`unknown "search" subcommand "${sub}" (expected: setup | notify). Try: vitops --help`);
+	}
+}
+/**
+* Onboard domains into Google Search Console as domain properties.
+*
+* Idempotent by construction: the planner decides each step from the domain's live
+* state, so a re-run of a fully-onboarded domain is all skips. `--check` reports
+* drift and exits non-zero without mutating; `--dry` prints the plan and stops.
+* DNS is only ever *created* — the verification TXT — never edited or removed.
+*
+* Search Console has no user/permission API, so granting a Google Group Full-User
+* access stays manual and is surfaced as a reminder, not attempted.
+*/
+async function cmdSearchSetup(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			domain: { type: "string" },
+			check: {
+				type: "boolean",
+				default: false
+			},
+			dry: {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: false
+	});
+	const domains = toSearchConsoleSetup(await loadConfig(resolve(values.input), values["site-env"]), values.domain);
+	if (domains.length === 0) fail("no domains in site.searchConsole — add domains to onboard (keyed by bare hostname)");
+	const cfToken = loadCloudflareToken();
+	const oauth = loadGoogleOAuth();
+	if (!cfToken) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token) — reading and writing DNS needs it");
+	if (!oauth) fail("set VITOPS_GOOGLE_CLIENT_ID / VITOPS_GOOGLE_CLIENT_SECRET / VITOPS_GOOGLE_REFRESH_TOKEN — a user OAuth token scoped to siteverification + webmasters");
+	const token = await refreshTokenGrant(oauth);
+	const states = /* @__PURE__ */ new Map();
+	const verifyTokens = /* @__PURE__ */ new Map();
+	const webIds = /* @__PURE__ */ new Map();
+	for (const d of domains) {
+		const zone = await findZoneId(cfToken, d.domain);
+		if (!zone.ok || !zone.zoneId) fail(`${d.domain}: ${zone.message}`);
+		const vt = await getVerificationToken(token, d.domain);
+		if (!vt.ok || !vt.token) fail(`${d.domain}: could not obtain a verification token — ${vt.message}`);
+		verifyTokens.set(d.domain, vt.token);
+		const txt = await listApexTxt(cfToken, zone.zoneId, d.domain);
+		if (!txt.ok) fail(`${d.domain}: ${txt.message}`);
+		const wr = await getWebResource(token, d.domain);
+		if (!wr.ok) fail(`${d.domain}: ${wr.message}`);
+		if (wr.id) webIds.set(d.domain, wr.id);
+		const site = await getSite(token, siteUrlFor(d.domain));
+		if (!site.ok) fail(`${d.domain}: ${site.message}`);
+		states.set(d.domain, {
+			zoneId: zone.zoneId,
+			txtPresent: txt.contents.includes(vt.token),
+			verified: wr.exists,
+			currentOwners: wr.owners,
+			propertyExists: site.exists
+		});
+	}
+	const p = plan$1({ domains }, states);
+	console.log(formatPlan$1(p));
+	if (values.check) {
+		if (hasDrift(p)) {
+			console.error("\n✖ drift — one or more domains are not fully onboarded");
+			process.exit(1);
+		}
+		console.log("\n✓ every domain is onboarded");
+		return;
+	}
+	if (values.dry) {
+		console.log("\n(--dry: nothing was changed)");
+		return;
+	}
+	const results = [];
+	let failed = false;
+	const delays = backoffSchedule();
+	for (const d of domains) {
+		const dp = p.domains.find((x) => x.domain === d.domain);
+		const state = states.get(d.domain);
+		const result = {
+			domain: d.domain,
+			txt: "—",
+			verified: "—",
+			property: "—",
+			reminders: dp.reminders
+		};
+		if (dp.txt.action === "skip") result.txt = "present";
+		else {
+			const r = await createApexTxt(cfToken, state.zoneId, d.domain, verifyTokens.get(d.domain));
+			if (!r.ok) {
+				console.error(`✖ ${d.domain} TXT: ${r.message}`);
+				result.txt = "failed";
+				failed = true;
+				results.push(result);
+				continue;
+			}
+			result.txt = "created";
+		}
+		let verified = state.verified;
+		if (verified) result.verified = "yes";
+		else {
+			for (let attempt = 0; attempt < delays.length; attempt++) {
+				const v = await verifyWebResource(token, d.domain);
+				if (v.ok) {
+					verified = true;
+					if (v.id) webIds.set(d.domain, v.id);
+					state.currentOwners = v.owners;
+					break;
+				}
+				if (attempt < delays.length - 1) {
+					const wait = delays[attempt];
+					console.log(`  … ${d.domain}: not verified yet (attempt ${attempt + 1}/${delays.length}); retrying in ${wait / 1e3}s`);
+					await sleep(wait);
+				}
+			}
+			result.verified = verified ? "yes" : "pending";
+		}
+		if (!verified) {
+			results.push(result);
+			continue;
+		}
+		if (dp.property.action === "skip") result.property = "present";
+		else {
+			const r = await addSite(token, dp.siteUrl);
+			if (!r.ok) {
+				console.error(`✖ ${d.domain} property: ${r.message}`);
+				result.property = "failed";
+				failed = true;
+			} else result.property = "added";
+		}
+		if (dp.owners.action === "update" && dp.ownersToAdd.length) {
+			const id = webIds.get(d.domain);
+			if (!id) {
+				console.error(`✖ ${d.domain} owners: no web-resource id (verify may be too fresh)`);
+				failed = true;
+			} else {
+				const r = await updateOwners(token, id, d.domain, ownerUnion(state.currentOwners, dp.ownersToAdd));
+				if (!r.ok) {
+					console.error(`✖ ${d.domain} owners: ${r.message}`);
+					failed = true;
+				} else console.log(`✓ ${d.domain}: added ${dp.ownersToAdd.length} owner(s)`);
+			}
+		}
+		results.push(result);
+	}
+	console.log(`\n${formatSummary(results)}`);
+	if (failed) process.exit(1);
+}
+/**
+* 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
+* `domains.canonical` answers it, and only an ad account verified against some
+* other host needs `site.ads.<provider>.domain` stated.
+*/
+function toAdProperties(cfg, providerFilter) {
+	const canonicalHost = (() => {
+		const url = cfg.site.domains?.canonical;
+		if (!url) return void 0;
+		try {
+			return new URL(url).hostname;
+		} catch {
+			return;
+		}
+	})();
+	const entries = cfg.site.ads ?? {};
+	const properties = AD_PROVIDER_KEYS.filter((p) => entries[p] != null).map((provider) => {
+		const e = entries[provider];
+		const domain = e.domain ?? canonicalHost;
+		return {
+			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 } : {}
+		};
+	});
+	if (providerFilter) {
+		if (!isAdProvider(providerFilter)) fail(`--provider "${providerFilter}" is not a known ad platform (expected: ${AD_PROVIDER_KEYS.join(" | ")})`);
+		const one = properties.find((p) => p.provider === providerFilter);
+		if (!one) fail(`--provider "${providerFilter}" is not in site.ads (have: ${properties.map((p) => p.provider).join(", ") || "none"})`);
+		return [one];
+	}
+	return properties;
+}
+/**
+* `vitops ads` — everything that links this site to an ad platform.
+*
+* Three subcommands, split by what they touch: `setup` writes DNS, `tags` writes
+* nothing and prints markup, `lint` reads and reports.
+*/
+async function cmdAds(argv) {
+	const [sub, ...rest] = argv;
+	switch (sub) {
+		case "setup": return cmdAdsSetup(rest);
+		case "tags": return cmdAdsTags(rest);
+		case "lint": return cmdAdsLint(rest);
+		case void 0:
+		case "-h":
+		case "--help":
+			console.log(ADS_HELP);
+			return;
+		default: fail(`unknown "ads" subcommand "${sub}" (expected: setup | tags | lint). Try: vitops --help`);
+	}
+}
+/**
+* Link each configured ad property: ensure the platform's domain-verification TXT,
+* report what only a human can finish.
+*
+* Idempotent by construction — the planner decides each step from live DNS, so a
+* re-run of a linked property is all skips. `--check` reports drift and exits
+* non-zero without mutating; `--dry` prints the plan and stops. Neither is offline:
+* the DNS observation runs before the planner either way.
+*
+* The one thing this does that `search setup` does not is **ask**. A first run has
+* no verification token, because the token doesn't exist until someone fetches it
+* from the platform UI — so a blocked step becomes a prompt, the answer is folded
+* into the setup, and the planner runs again on it. That re-plan matters: what gets
+* executed is always a plan the pure planner produced, never a special case built
+* out of an answer.
+*/
+async function cmdAdsSetup(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			provider: { type: "string" },
+			check: {
+				type: "boolean",
+				default: false
+			},
+			dry: {
+				type: "boolean",
+				default: false
+			},
+			"no-prompt": {
+				type: "boolean",
+				default: false
+			},
+			"no-write": {
+				type: "boolean",
+				default: false
+			}
+		},
+		allowPositionals: false
+	});
+	const input = resolve(values.input);
+	let properties = toAdProperties(await loadConfig(input, values["site-env"]), values.provider);
+	if (properties.length === 0) fail("no properties in site.ads — add the ad platforms this site is linked to");
+	const dry = values.dry;
+	const check = values.check;
+	const needsDns = properties.some((p) => AD_PLATFORMS[p.provider].verification.method === "dns-txt");
+	const cfToken = loadCloudflareToken();
+	if (needsDns && !cfToken) fail("set CLOUDFLARE_API_TOKEN (a Zone:DNS:Edit token) — reading and writing DNS needs it");
+	/** Observe live DNS per domain. Cached by domain: several platforms share one. */
+	const observe = async () => {
+		const states = /* @__PURE__ */ new Map();
+		if (!cfToken) return states;
+		for (const p of properties) {
+			const domain = p.domain;
+			if (!domain || states.has(domain)) continue;
+			if (AD_PLATFORMS[p.provider].verification.method !== "dns-txt") continue;
+			const zone = await findZoneId(cfToken, domain);
+			if (!zone.ok || !zone.zoneId) fail(`${domain}: ${zone.message}`);
+			const txt = await listApexTxt(cfToken, zone.zoneId, domain);
+			if (!txt.ok) fail(`${domain}: ${txt.message}`);
+			states.set(domain, {
+				zoneId: zone.zoneId,
+				txtContents: txt.contents
+			});
+		}
+		return states;
+	};
+	let states = await observe();
+	let adsPlan = plan$2({ properties }, states);
+	const interactive = canPrompt({
+		dry,
+		check,
+		noPrompt: values["no-prompt"]
+	});
+	const gaps = missingFields(adsPlan);
+	if (gaps.length && interactive) {
+		const answers = [];
+		for (const gap of gaps) {
+			const value = await ask(questionFor(gap.provider, gap.needs));
+			if (value) answers.push({
+				provider: gap.provider,
+				needs: gap.needs,
+				value
+			});
+		}
+		if (answers.length) {
+			properties = properties.map((p) => {
+				return answers.filter((a) => a.provider === p.provider).reduce((acc, a) => ({
+					...acc,
+					[a.needs]: a.value
+				}), p);
+			});
+			adsPlan = plan$2({ properties }, states);
+			if (!values["no-write"]) for (const a of answers) {
+				const res = writeConfigPatch(input, a.provider, a.needs, a.value);
+				if (res.written) console.log(`✓ wrote site.ads.${a.provider}.${a.needs} to ${input}`);
+				else console.error(`! ${res.reason}`);
+			}
+		}
+		states = await observe();
+		adsPlan = plan$2({ properties }, states);
+	} else if (gaps.length && !dry && !check) for (const gap of gaps) console.error(`! ${missingFieldMessage(gap.provider, gap.needs)}`);
+	if (dry || check) {
+		console.log(formatPlan$2(adsPlan));
+		if (check && hasDrift$1(adsPlan)) {
+			console.error("\n✖ ad properties are not fully linked");
+			process.exit(1);
+		}
+		return;
+	}
+	const results = [];
+	let failed = false;
+	for (const p of adsPlan.properties) {
+		const result = {
+			provider: p.provider,
+			domain: p.domain ?? "—",
+			txt: "n/a",
+			tag: p.tag.action === "skip" ? "ready" : "blocked",
+			reminders: p.reminders
+		};
+		if (p.txt.action === "blocked" || p.tag.action === "blocked") failed = true;
+		if (p.txt.action === "blocked") result.txt = "blocked";
+		else if (p.txt.action === "skip") result.txt = AD_PLATFORMS[p.provider].verification.method === "dns-txt" ? "present" : "n/a";
+		else {
+			const zoneId = p.domain ? states.get(p.domain)?.zoneId : void 0;
+			if (!cfToken || !zoneId || !p.domain || !p.txtContent) {
+				console.error(`✖ ${p.provider}: no Cloudflare zone for ${p.domain ?? "(no domain)"}`);
+				result.txt = "failed";
+				failed = true;
+			} else {
+				const r = await createApexTxt(cfToken, zoneId, p.domain, p.txtContent);
+				if (!r.ok) {
+					console.error(`✖ ${p.provider} TXT: ${r.message}`);
+					result.txt = "failed";
+					failed = true;
+				} else {
+					console.log(`✓ ${p.provider}: created TXT on ${p.domain}`);
+					result.txt = "created";
+				}
+			}
+		}
+		results.push(result);
+	}
+	console.log(`\n${formatSummary$1(results)}`);
+	if (results.some((r) => r.txt === "created")) console.log("\n  DNS takes minutes to propagate before a platform can see the record.");
+	if (results.some((r) => r.reminders.length)) console.log("  Finish the reminders above in the platform UI — no API covers those.");
+	if (failed) process.exit(1);
+}
+/**
+* Print each configured pixel as an inert, consent-gated `<script>`.
+*
+* The universal delivery path, the same reasoning as `vitops legal`: every consumer
+* has this CLI whatever their stack, so Bricks, WordPress and a hand-built site all
+* get the correct gated markup without integration code.
+*/
+async function cmdAdsTags(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			},
+			provider: { type: "string" },
+			strategy: {
+				type: "string",
+				default: "idle"
+			}
+		},
+		allowPositionals: false
+	});
+	const strategy = values.strategy;
+	if (![
+		"idle",
+		"async",
+		"interaction"
+	].includes(strategy)) fail(`--strategy "${strategy}" is not one of: idle | async | interaction`);
+	const properties = toAdProperties(await loadConfig(resolve(values.input), values["site-env"]), values.provider);
+	if (properties.length === 0) fail("no properties in site.ads — nothing to emit");
+	const out = [];
+	for (const p of properties) {
+		if (p.enabled === false) continue;
+		const tag = renderTag(p, strategy);
+		if (!tag) {
+			console.error(`! ${p.provider}: no ${AD_PLATFORMS[p.provider].tag.needs} — skipped (run \`vitops ads setup\` to be prompted for it)`);
+			continue;
+		}
+		out.push(tag);
+	}
+	if (out.length === 0) fail("no ad property has a tag id yet");
+	console.log(out.join("\n\n"));
+}
+/**
+* Report the ad-property gaps that are invisible at runtime.
+*
+* Each finding is a silent failure, which is the bar for being here at all: an
+* uncaptured click ID looks exactly like organic traffic, and a pixel on a site
+* with tracking off produces conversions no campaign gets credit for.
+*/
+async function cmdAdsLint(argv) {
+	const { values } = parseArgs({
+		args: argv,
+		options: {
+			input: {
+				type: "string",
+				short: "i",
+				default: "site.json"
+			},
+			"site-env": {
+				type: "string",
+				default: "production"
+			}
+		},
+		allowPositionals: false
+	});
+	const cfg = await loadConfig(resolve(values.input), values["site-env"]);
+	const properties = toAdProperties(cfg, void 0);
+	if (properties.length === 0) {
+		console.log("· no site.ads properties — nothing to check");
+		return;
+	}
+	const findings = [];
+	const trackingOn = cfg.site.tracking?.enabled === true;
+	for (const p of properties) {
+		const platform = AD_PLATFORMS[p.provider];
+		if (p.enabled === false) continue;
+		if (!tagId(p)) findings.push(`${p.provider}: no ${platform.tag.needs} — the property is on record but no tag can be emitted`);
+		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 (findings.length === 0) {
+		console.log(`✓ ${properties.length} ad propert${properties.length === 1 ? "y" : "ies"} check out`);
+		return;
+	}
+	for (const f of findings) console.error(`✖ ${f}`);
+	process.exit(1);
 }
 function cliVersion() {
 	try {
@@ -1641,9 +2475,10 @@ async function main() {
 		case "lint": return cmdLint(rest);
 		case "legal": return cmdLegal(rest);
 		case "icons": return cmdIcons(rest);
-		case "indexing": return cmdIndexing(rest);
+		case "search": return cmdSearch(rest);
+		case "ads": return cmdAds(rest);
 		case "media": return cmdMedia(rest);
-		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons | indexing | media). Try: vitops --help`);
+		default: fail(`unknown command "${command}" (expected: generate | init | validate | favicon | agents | docs | lint | legal | icons | search | ads | media). Try: vitops --help`);
 	}
 }
 main().catch((err) => fail(err.message));