@getvitops/cli 4.0.0 → 4.1.0

package/dist/cli.mjs

@@ -4,11 +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 { 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 { MEDIA_MANIFEST_PATH, formatPlan as formatPlan$2, processMedia } from "@getvitops/utils/media";
+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
 /**
@@ -126,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. */
@@ -558,6 +699,7 @@ function lintSource(files, v, format) {
 *   vitops lint      [--input <json>] [--format <fmt>] [--src <dir>]
 *   vitops legal     [--input <site.json>] [--doc <name>] [--format <md|html|portable-text>] [--out <dir>]
 *   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).
@@ -602,6 +744,7 @@ Usage:
   vitops legal [options]        Render legal documents from a site config
   vitops icons [options]        Report which icons your source uses, and build the sprite
   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:
@@ -725,6 +868,53 @@ Search notify options:
   _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
                         (default: ./raw)
@@ -758,6 +948,14 @@ 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) {
@@ -1012,7 +1210,7 @@ async function cmdMedia(argv) {
 			onProgress: (message) => console.error(`  … ${message}`)
 		});
 		if (values.dry) {
-			console.log(formatPlan$2(result.plan));
+			console.log(formatPlan$3(result.plan));
 			return;
 		}
 		console.log(`✓ media → ${values.out} (${result.written.length} written, ${result.skipped} unchanged)`);
@@ -1255,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;
@@ -1729,6 +1936,320 @@ async function cmdSearchSetup(argv) {
 	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 {
 		return JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version ?? "0.0.0";
@@ -1955,8 +2476,9 @@ async function main() {
 		case "legal": return cmdLegal(rest);
 		case "icons": return cmdIcons(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 | search | 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));