@getvitops/cli 3.0.0 → 4.1.0

package/CHANGELOG.md

@@ -1,5 +1,275 @@
 # @getvitops/cli
 
+## 4.1.0
+
+### Minor Changes
+
+- 2c890c0: Link a site to its ad properties: `site.ads`, `vitops ads`, and `<Ads />`.
+
+  `vitops search` covers the whole Search Console relationship. Nothing covered the equivalent one
+  with ad platforms, and a site's ad accounts had nowhere to live — so a Meta pixel pasted into a
+  template was invisible to the rest of the toolchain. It set `_fbp` on a site whose generated cookie
+  notice never mentioned it, whose consent gate never cleared it on revoke, and — for LinkedIn and
+  Pinterest — whose attribution never captured the click ID at all, so every conversion from those
+  platforms arrived indistinguishable from organic traffic.
+
+  **New `site.ads` block**, keyed by platform (`google`, `meta`, `linkedin`, `reddit`, `tiktok`,
+  `microsoft`, `pinterest`, `snapchat`):
+
+  ```jsonc
+  {
+    "site": {
+      "ads": {
+        "meta": { "pixelId": "123456789", "domainVerification": "abc123" },
+        "google": {
+          "accountId": "123-456-7890",
+          "pixelId": "AW-987654321",
+          "conversionLabel": "xyz",
+        },
+      },
+    },
+  }
+  ```
+
+  **`vitops ads setup`** ensures each platform's domain-verification DNS record. Only four platforms
+  verify a domain at all — Meta, TikTok, Pinterest and Snapchat, by apex DNS TXT — and that record is
+  the one thing created 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: 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 an approved
+  developer token with your own account on the line — so the final "Verify" click is surfaced as a
+  reminder. `--dry` prints the plan, `--check` reports drift and exits non-zero.
+
+  **It asks for what the config is missing.** A verification token does not exist until someone
+  fetches it from the platform UI, so a first run prompts for it, naming the exact UI path, folds the
+  answer into the plan and writes it to your config. The token is not a secret — it is published in
+  DNS, and the platform fetching it back is the ownership proof, exactly like the IndexNow key.
+  Prompting requires a TTY: with `--dry`, `--check`, `--no-prompt`, or in CI, you get a named error
+  instead and the run never hangs. `--no-write` keeps the answer out of the config.
+
+  **`vitops ads tags`** 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 Bricks, WordPress, Eleventy: any stack without the Astro integration.
+
+  **`vitops ads lint`** reports the gaps that are invisible at runtime: a click ID the platform stamps
+  that attribution does not capture, a pixel while `site.tracking` is off, a property with no tag id.
+
+  **`<Ads />` in `@getvitops/astro`**, a sibling of `<Analytics />` rather than part of it — ad
+  properties come from the site config, state their own consent category (`marketing` by default,
+  rather than being derived), and switch per environment on their own
+  (`environments.<env>.ads`, defaulting to `analytics`, then true, so a preview deployment can send
+  pageviews without firing conversion pixels). Both components now render through one `<GatedTags />`,
+  so the inert markup has a single implementation.
+
+  **Your cookie notice now discloses every configured pixel** — name, cookies and opt-out — from the
+  same table that writes `data-consent-cookies`, so the notice and the revoke cannot disagree. If you
+  add `site.ads` to a config whose privacy policy or cookie notice you have already published,
+  re-generate and re-read them.
+
+  `li_fat_id` (LinkedIn) and `epik` (Pinterest) join the click-ID capture vocabulary; a site running
+  either platform starts attributing conversions it previously recorded as organic.
+
+- e764090: Separate where a processor stores information from whose law can reach it.
+
+  A processor carried one optional `country`, and the privacy policy flat-deduped it into a single
+  sentence. That conflated two facts a disclosure has to keep apart — **where the data rests** and
+  **which jurisdiction can compel access** — and privacy law turns on the second: the OPC's concern
+  is foreign _access_, not merely foreign storage.
+
+  Ordinary arrangements were inexpressible. Azure is data-resident in Canada and US-controlled;
+  Zoho can serve mail from a Canadian datacentre and telemetry from the US while being headquartered
+  in India; a Microsoft 365 tenant can be Canadian with its identity data in the US. For all of
+  them every available option was wrong: `country: "Canada"` rendered the incoherent _"outside of
+  Canada, including Canada"_, naming the operator's country asserted storage that wasn't happening,
+  and omitting it dropped the processor from the disclosure **silently**.
+
+  **New on a processor:**
+
+  ```jsonc
+  {
+    "name": "Zoho",
+    "purpose": "receiving and storing email sent to us",
+    "storage": [
+      { "country": "Canada", "scope": "mail and productivity data" },
+      { "country": "the United States", "scope": "analytics and telemetry" },
+    ],
+    "operatorCountry": "India",
+  }
+  ```
+
+  - `storage[]` — where information rests, each entry optionally `scope`d to a category. The scope
+    is what makes "Canadian tenant, identity data in the US" sayable.
+  - `operatorCountry` — the jurisdiction that can compel the provider to produce it. Gets its own
+    sentence: _"…established in, or controlled from, jurisdictions outside of Canada, including
+    India. Personal information those providers handle on our behalf may be subject to the laws of
+    those jurisdictions even when it is stored in Canada."_
+  - `country` still works, as shorthand asserting **both** facts — which is what it always
+    asserted, since the sentence it fed claimed storage and legal reach in one breath.
+
+  **Combining `country` with either explicit field is rejected** by `vitops validate`. Whether the
+  shorthand narrows the explicit fact or adds to it are two readings that make contradictory legal
+  claims, so neither is guessed.
+
+  A country in the policy's own jurisdiction is no longer treated as a transfer, which is the
+  `country: "Canada"` fix. Comparison ignores case and a leading "the".
+
+  ### This changes text you have already published
+
+  **Cloudflare, Cloudflare Turnstile, Vercel and Netlify now assert operator jurisdiction and no
+  storage.** They previously claimed `the United States` into a sentence saying "stored or processed
+  in" — a claim about the wrong fact. Cloudflare is anycast: a request from Toronto is answered from
+  a Toronto PoP, and Workers/R2 have residency controls the config cannot see.
+
+  So a site whose only foreign element is its host or Turnstile **stops claiming foreign storage**
+  and instead discloses foreign legal reach. That is a retraction in the direction of accuracy, and
+  it deserves a re-read. **If you pin a US region, say so** — declare a processor with
+  `storage: [{ country: "the United States" }]`. This generalises the rule the provider table
+  already applied to Matomo: "we don't know" is a fact.
+
+  **Everything else renders identically.** Google Analytics, Tag Manager, Clarity, Plausible,
+  Matomo Cloud and any processor you declared with `country` produce the same words as before,
+  because the shorthand expands to both facts and the operator sentence is suppressed when it would
+  only restate a country already disclosed as storage. The one cosmetic change: the closing
+  "subject to access requests…" sentence is now its own paragraph, since it is shared by both
+  clauses.
+
+  **A processor with no location at all is now reported** on stderr by `vitops legal`, naming the
+  document it will be missing from. It cannot appear in a transfer disclosure — there is nothing
+  true to say — but it used to vanish in silence, which is the failure that looks tidy. It is not a
+  validation error: a bare `{ name, purpose }` is still valid.
+
+  New exports from `@getvitops/generator`: `processorsMissingLocation`, `JURISDICTION_COUNTRIES`,
+  and the `ProcessorStorage` type. `PolicyVars` gains `jurisdictionCountry`, `storageCountries`,
+  `scopedStorage` and `operatorCountries`; `countries` is **deprecated but retained**, and still
+  names every country it ever named, so a custom template keeps rendering what it rendered.
+
+### Patch Changes
+
+- Updated dependencies [2c890c0]
+- Updated dependencies [e764090]
+  - @getvitops/generator@4.1.0
+  - @getvitops/utils@4.1.0
+
+## 4.0.0
+
+### Major Changes
+
+- f7bc0a0: Add `vitops search setup` — onboard domains into Google Search Console as domain properties.
+
+  **Breaking:** the `vitops indexing` command has been renamed to **`vitops search notify`**. There is
+  no alias — update any scripts or CI that call `vitops indexing` to `vitops search notify` (same flags,
+  same behaviour).
+
+  **New: `vitops search setup`.** For each domain in a site config's new `site.searchConsole` block
+  (a record keyed by bare hostname), it:
+  - ensures the apex verification TXT record in Cloudflare,
+  - verifies ownership via the Site Verification API (DNS_TXT), retried with exponential backoff while
+    DNS propagates — a still-unverified domain is reported **PENDING**, not failed,
+  - adds the `sc-domain:` property via the Search Console API,
+  - adds any `delegatedOwners` to the verified Site Verification web resource.
+
+  It is idempotent (a re-run of an onboarded domain is a no-op), supports `--check` (report drift, exit
+  non-zero, mutate nothing) and `--dry` (print the plan, change nothing), and `--domain <name>` to
+  scope to one entry. DNS records are only ever created, never edited or deleted.
+
+  Credentials come from the environment, never the config: `CLOUDFLARE_API_TOKEN` (a `Zone:DNS:Edit`
+  token) and a Google **user OAuth refresh token** as `VITOPS_GOOGLE_CLIENT_ID` /
+  `VITOPS_GOOGLE_CLIENT_SECRET` / `VITOPS_GOOGLE_REFRESH_TOKEN` (scoped to `siteverification` +
+  `webmasters`). Granting a Google Group **Full-User** access has no Search Console API and is surfaced
+  as a reminder in the summary rather than automated.
+
+- ceed51f: `vitops search notify` now accepts either Google credential, so most sites need only one.
+
+  The two halves of `vitops search` each demanded a different, unrelated Google setup — five environment variables between them. `search setup` requires a user OAuth credential (verifying a site makes the caller an **owner** of the property, and that should be a person, not a project robot), while `search notify` accepted only a service account. Search Console does not care which identity calls it, so a consumer who had already run `search setup` was being made to create a second credential for the other half of the same command.
+
+  `search notify` now takes whichever you have, preferring the service account when both are set — it runs on every deploy, in CI, and a service account does not expire, whereas a refresh token can be revoked and expires after 7 days for an OAuth client still in _Testing_ publishing status. `search setup` is unchanged and still requires user OAuth.
+
+  **Breaking — two renamed exports.** Both did the same job under the same name from different subpaths, which forced an alias at every call site:
+  - `@getvitops/utils/indexing`: `getAccessToken` → **`serviceAccountToken`**
+  - `@getvitops/utils/onboarding`: `getAccessToken` → **`refreshTokenGrant`**
+
+  New: `googleAccessToken(credential)` from `@getvitops/utils/indexing` takes a `GoogleCredential` union and is what both wrappers now call. If you were importing either `getAccessToken`, switch to the specific name, or to `googleAccessToken` if you want to accept either identity.
+
+  Internally the exchange is now one function. The two grants send different form bodies; everything after that — endpoint, content-type, error handling, `access_token` extraction — was duplicated verbatim in two modules. The service-account JWT signing had no test at all, because it was only reachable over the network; it now does, including the literal-`\n`-in-a-PEM case that secret stores produce.
+
+### Minor Changes
+
+- 14813fa: Document which tier provides each pattern — `vitops docs components`.
+
+  The toolkit ships four tiers that compose: CSS framework classes, `<wc-*>` web components, Astro
+  components, Bricks elements. Nothing said so. The class reference listed pattern names, the
+  elements reference listed Bricks controls, and the fact that `tree` is _also_ a web component
+  _and_ an Astro component existed only in the source layout. The cost is silent: you hand-write
+  the markup a component already emits, or you wrap a component that already emits its own tag.
+
+  `TIERS` in `@getvitops/generator` is the new manifest — per pattern, its CSS partial and
+  representative classes, its `wc-*` tag and which bundle that ships in, its Astro component(s),
+  its Bricks element, and one line saying what to actually write. `tierPatterns(tier)` projects one
+  tier. `vitops docs components` renders all four in one document, and the reference sections it
+  feeds render the same data per tier.
+
+  It is **authored rather than derived, and drift-guarded** instead. Naming convention carries most
+  of it and breaks exactly where it matters — `splitter.css` hosts two components, `tag.css` serves
+  three config patterns, `anchor-link.css` provides `.link`, `layout.css` provides `.split` and
+  `.centered` — so a derivation would need an exceptions table longer than the rule, and a rename
+  would silently drop a link. Instead, tests fail the build when a hand-written CSS partial, a
+  `customElements.define`, an exported Astro component or a Bricks element isn't accounted for.
+
+  Four things the manifest records that cannot be inferred, each a real failure mode:
+  - **Whether an Astro component wraps a web component.** `Tree` and `CookieConsent` emit the
+    `<wc-*>` tag with the fallback inside; `Details`, `Drawer`, `Popover`, `NavShell` and `Subgrid`
+    emit tier-1 markup with no web component at all. Reading the first group as the second gives
+    `<wc-tree><Tree /></wc-tree>` — two elements on one tree, which renders and misbehaves.
+  - **Where each element ships.** `elements.js` for the registered set, its own bundle for
+    `<wc-consent>` and `<wc-theme-editor>`, and **no bundle at all** for the four editor-v2 tags —
+    which are registered, importable-looking and inert in a consumer project. The guard checks this
+    against what `js/elements.ts` imports, so it can't claim an element ships when it doesn't.
+  - **Whether a pattern is config-authored.** `patterns.items` patterns get the token cascade,
+    states, role variants and override hooks; a structural partial gets none of them. The docs also
+    now say when a config-authored pattern is **absent from your config**, because naming its
+    classes while your build emits none of them is worse than omitting it.
+  - **The import specifier, verbatim.** These are published as the line to copy, so they are checked
+    against `@getvitops/astro`'s `exports`. That guard immediately caught
+    `@getvitops/astro/components/../CookieConsent.astro` — plausible-looking, right basename, not an
+    importable path (`CookieConsent.astro` ships from the package root).
+
+- 14813fa: Document the consent, conversion-tracking, search and legal subsystems for agents.
+
+  `vitops docs` gains four topics — `consent`, `tracking`, `search`, `legal` — and the docs
+  bundle gains the matching concept docs under `concepts/`. Until now these subsystems were
+  described only by their generated config-schema field descriptions, so an agent working in a
+  consumer project had no account of the rules that make them work, and every one of those rules
+  fails **silently** when broken:
+  - a gated tag given a live `src` instead of `type="text/plain"` fetches the third party anyway,
+    so the gate becomes decorative;
+  - a caller using `granted()` instead of `require()` never raises the banner, so on a site where
+    nothing else demands that category the permission is never offered, never granted, and the
+    write never happens;
+  - an absent `window.vitopsConsent` read as "denied" rather than "this site has no gate";
+  - a consent patch widened to every category records consent nobody gave;
+  - a sitemap with no `<lastmod>` makes edited pages undetectable, so `search notify` looks
+    healthy while never resubmitting anything;
+  - a stale IndexNow key file returns `202` and is then discarded;
+  - Google's Indexing API accepts ordinary URLs, discards them, and violates its own terms.
+
+  The packaged agent skill now covers consent and conversion tracking, and its description names
+  these subsystems so it is actually surfaced when they are the task.
+
+  Also fixed: the icons concept doc still called the Astro integration `getvitops()`, renamed to
+  `vitops()` in 3.0.
+
+### Patch Changes
+
+- Updated dependencies [14813fa]
+- Updated dependencies [c6b99e7]
+- Updated dependencies [c6b99e7]
+- Updated dependencies [f7bc0a0]
+- Updated dependencies [ceed51f]
+- Updated dependencies [14813fa]
+- Updated dependencies [14813fa]
+  - @getvitops/generator@4.0.0
+  - @getvitops/utils@4.0.0
+
 ## 3.0.0
 
 ### Major Changes

package/README.md

@@ -25,7 +25,7 @@ npx vitops generate --format bricks,css --out dist
 | `vitops favicon -i <svg\|png> -o <dir>`            | generate a favicon set from a source image      |
 | `vitops agents [-o AGENTS.md] [--docs-dir <dir>]`  | link the agent skill + AGENTS.md pointer        |
 | `vitops docs [topic] [--all]`                      | print live reference docs to stdout             |
-| `vitops indexing [--dry] [--check]`                | tell search engines about a deploy              |
+| `vitops search notify [--dry] [--check]`           | tell search engines about a deploy              |
 | `vitops media [--raw <dir>] [-o <dir>]`            | encode raw video to WebM + MP4 + poster         |
 
 Every `--input` takes a `design-system.json` **or** the larger site config that embeds one