@getvitops/cli 1.0.0 → 2.1.0

package/CHANGELOG.md

@@ -1,5 +1,340 @@
 # @getvitops/cli
 
+## 2.1.0
+
+### Minor Changes
+
+- 20e518e: Add `vitops indexing` — tell search engines about a deploy, instead of opening Search Console by hand.
+
+  Configure it in your site config under `seo.indexing`, then run it after deploying:
+
+  ```jsonc
+  "seo": {
+    "indexing": {
+      "indexNow": { "key": "…" },
+      "searchConsole": { "siteUrl": "sc-domain:acme.ca" },
+      "priorityUrls": ["https://acme.ca/", "https://acme.ca/services"]
+    }
+  }
+  ```
+
+  ```
+  vitops indexing --dry     # print the plan, make no requests
+  vitops indexing           # submit
+  vitops indexing --check   # a day or two later: did Google actually index them?
+  ```
+
+  It reads your sitemap, diffs it against the previous run, and submits only what changed —
+  pinging **IndexNow** and re-submitting your sitemap through the **Search Console API**.
+  `--check` inspects `priorityUrls` and exits non-zero on a page Google hasn't indexed, so a
+  scheduled CI job can catch a page that quietly fell out of the index.
+
+  **Be clear-eyed about what this can do.** Google exposes no API that requests indexing — the
+  button in Search Console isn't available anywhere, URL Inspection is read-only, and the sitemap
+  ping endpoint was removed in 2023. IndexNow reaches Bing, Yandex, Naver, Seznam and Yep; Google
+  doesn't participate. So this automates every sanctioned step and then verifies the outcome; it
+  does not make Google re-index on demand, and nothing can. Google's Indexing API is deliberately
+  not wired: it's scoped to job postings and livestreams, and using it for ordinary pages violates
+  its terms.
+
+  Also new, and worth wiring at the same time — **`gitLastmod()` for real sitemap dates**:
+
+  ```js
+  import vitops, { gitLastmod } from '@getvitops/astro';
+  vitops({ sitemap: { serialize: await gitLastmod() } });
+  ```
+
+  `@astrojs/sitemap` emits no `<lastmod>` by default, which means a crawler is told your pages
+  exist but never that one changed — and it's what lets `vitops indexing` submit a handful of URLs instead
+  of all of them. `gitLastmod()` derives each date from the source file's last commit, and leaves a
+  page alone rather than guessing (dynamic routes, ambiguous slugs, shallow clones): an inaccurate
+  `lastmod` is worse than none, because Google stops trusting the field site-wide.
+
+  Requires `fetch-depth: 0` in CI — the default shallow clone has no history to read, and it warns
+  when that's the case.
+
+  **Credentials.** IndexNow's key is public by design (it's served at `/<key>.txt` as the ownership
+  proof), so it lives in your config, and the Astro integration writes the file into `public/` for
+  you — `vitops indexing --new-key` generates one, `--write-key <dir>` writes it for non-Astro stacks.
+  Search Console needs a service account in `VITOPS_GSC_SERVICE_ACCOUNT` or
+  `GOOGLE_APPLICATION_CREDENTIALS`, added as an owner of the property; it's never read from the
+  config file.
+
+  Persist `.vitops/` between runs (a CI cache) — that's the changed-URL state, and without it every
+  run submits everything.
+
+  An environment whose `robots` policy says `noindex` is refused outright, so pointing this at
+  staging can't publish it to a search engine.
+
+- 9bf975a: Add `vitops media` — encode raw video into web-ready outputs, instead of hand-rolling an ffmpeg
+  script per project.
+
+  Keep unprocessed video in a `raw/` directory and run:
+
+  ```
+  vitops media --raw raw --out src/assets/processed
+  ```
+
+  Each source becomes three files: **VP9/WebM**, an **H.264/MP4** fallback, and a **JPG poster**.
+  Import them like any other asset, so your bundler content-hashes them:
+
+  ```astro
+  ---
+  import hero from '../assets/processed/hero.webm';
+  import poster from '../assets/processed/hero.jpg';
+  ---
+  <video poster={poster.src} autoplay muted loop playsinline>
+    <source src={hero} type="video/webm" />
+  </video>
+  ```
+
+  In Astro it's an integration option — `vitops({ css, media: { raw: 'raw', out: 'src/assets/processed' } })`
+  — and it runs in the same pass that generates your CSS. `@getvitops/vite` gains a matching `media`
+  option, and `@getvitops/utils/media` exports `processMedia()` for anything else.
+
+  Defaults: capped at 1920px wide, CRF 32, audio dropped (the common case is a muted autoplay loop),
+  poster from frame 0. All of them are flags. `--dry` prints exactly what a run would do.
+
+  **Runs are cached**, on source content plus encode settings, in `.vitops/media-manifest.json` — a
+  24 MB clip that took 88 seconds the first time takes 0.14 seconds the second. A missing output
+  re-encodes; a corrupt manifest re-encodes everything. Neither ever reads as "already done", because
+  that failure is silent and no rebuild would fix it.
+
+  **Commit the outputs and the manifest.** A fresh CI clone has neither and would re-encode from
+  scratch; committing both means CI never needs ffmpeg. It also keeps your history clean — ffmpeg
+  output isn't byte-reproducible across versions, so a CI re-encode would rewrite every video on any
+  toolchain bump. Use `--force` when you mean to re-encode.
+
+  **`ffmpeg` is an external tool, not an npm dependency** — install it yourself (`brew install
+ffmpeg`, `apt install ffmpeg`, `winget install Gyan.FFmpeg`). The command fails without it rather
+  than skipping: a page referencing a video that was never encoded is broken, not degraded.
+
+  Two defaults worth knowing about. The MP4 exists because older iOS and the in-app webviews inside
+  social apps still don't decode VP9, and it's written with `+faststart` — without which a browser
+  downloads the whole file before showing frame one. And a poster taken from frame 0 is often black
+  on a clip that fades in; that's `--poster-time`, not a bug.
+
+### Patch Changes
+
+- Updated dependencies [20e518e]
+- Updated dependencies [9bf975a]
+  - @getvitops/generator@2.1.0
+  - @getvitops/utils@2.1.0
+
+## 2.0.0
+
+### Minor Changes
+
+- bf453b0: Anywhere the toolchain takes a config, that file may now be a `design-system.json` **or** the larger
+  site config that embeds one.
+
+  If you keep your tokens inside a `company.json` / `site.json`, you had to maintain a second file for
+  the tooling's sake — or duplicate your whole token set, because a site config must carry a complete
+  `designSystem`. Now you point the same option at the file you already have:
+
+  ```js
+  // astro.config.mjs
+  getvitops({ css: { input: 'company.json', format: 'css' } });
+  ```
+
+  ```
+  vitops generate --input company.json --format css --out dist
+  vitops lint --input company.json --src src
+  ```
+
+  The design system is taken from `designSystem.themes[theme]` with its `extends` chain resolved —
+  `defaultTheme`, else `default`, else whatever `--theme` / the `theme` option names. Nothing changes
+  for a plain `design-system.json`; the two are told apart by shape, not by filename, so you can call
+  the file anything.
+
+  **A site config also supplies the site-level facts generation reads**, so the path is declared once
+  rather than per option:
+  - `designSystem.defaultColorScheme: "system"` — emits the `prefers-color-scheme` block, which is
+    what makes `<color-scheme-toggle>`'s System position do anything.
+  - `legal.*.enabled` — renders the documents. `legal: {}` is now the whole declaration; `legal.input`
+    is optional.
+  - `icons.sprite` — builds `icons.svg`.
+  - `fonts` — `fonts: true` reads the families from it.
+
+  Each of those is already gated on a field in that config, so nothing new appears unless the config
+  asks for it. An explicit `site` option still wins when the two are genuinely different files.
+
+  Also:
+  - **`vitops validate` routes on the file's shape.** Pointed at a site config it used to report a
+    single `unrecognized_keys` for `designSystem` and nothing about the file's actual contents — a
+    wrong answer that reads like a right one. It now validates a site config as one, including the
+    cross-field integrity JSON Schema can't express, and checks every theme resolves to a complete
+    design system (`validateSite` only checked that the `extends` chain resolved, not what it resolved
+    to).
+  - **`generate()` gained `theme` and `siteEnv`.** The A/B variant for `siteEnv` is applied before the
+    theme is selected, so a variant can override tokens.
+  - **The theme editor's Save to source follows the design system into a site config.** Its patch is
+    design-system-relative, so the dev server merges into that subtree and writes only the surrounding
+    file whole. It locates the subtree in the raw on-disk object rather than the normalised one, so an
+    author who wrote either `designSystem` shorthand still gets their own keys edited.
+
+- 04a51d8: Icons: one semantic vocabulary across icon sets, with the bundle derived from your source.
+
+  Name icons by meaning — `<Icon name="menu" />` resolves to `fa7-solid:bars`, `ph:list` or
+  `lucide:menu` depending on the set you configure, so swapping sets is a config edit rather than a
+  find-and-replace. A name containing `:` still passes through untouched, which is the escape hatch
+  for a set-specific glyph.
+
+  **New `icons` option on `getvitops()`.** Configures the sets once per site and, under
+  `output: 'server'`, derives astro-icon's `include` map by scanning your source — the list most
+  projects end up maintaining by hand. On a static build no `include` is passed at all, because
+  astro-icon is already zero-config there and a list could only drop a glyph the scan couldn't see.
+  Names you declare that don't resolve fail the build; names only the scan found just warn; names
+  computed at runtime are reported with file and line so you can declare them.
+
+  **New `<Icon />` component**, and a real fix with it: `Popover`, `Details` and `Drawer` imported
+  `astro-icon/components` at module scope, so the _optional_ peer was resolved whether or not an icon
+  ever rendered — hard-failing anyone who hadn't installed it. Engines now load dynamically. The
+  per-component `iconResolver` prop still works but is deprecated in favour of the integration option.
+
+  **New SVG sprite** (`icons.sprite: true` in your site config) for consumers that can't run an icon
+  integration — Bricks/WordPress, EmDash renderers, plain HTML. `<use href="…/icons.svg#ph--list">`,
+  no JavaScript and no icon-API request. Every semantic name also gets a set-independent `icon-<name>`
+  alias, so sprite markup survives an icon-set change. WordPress gets `vitops_icon()`, a
+  `[vitops_icon]` shortcode and a **Vitops → Icon** Bricks element.
+
+  **New `vitops icons`** command: reports which icons your source uses, which names couldn't be
+  resolved, and which are computed at runtime; `--sprite` builds the sprite, `--json` for CI.
+
+  **Renamed, and completed to all four directions.** Chevrons and arrows are the
+  one family whose _meaning is_ its direction, and that direction is physical, not
+  logical — a chevron in a details marker points down in every writing mode. So they
+  are named for where they point: `expand-more`/`expand-less` →
+  `chevron-down`/`chevron-up`, and `arrow-forward`/`arrow-back` →
+  `arrow-right`/`arrow-left`. `chevron-left`/`chevron-right` keep their names.
+  `arrow-up`/`arrow-down` are new, so both families now cover all four directions.
+  `lightning` is new.
+
+  If you passed any of the old names to `<Icon />`, `resolveIcon` or an `icons`
+  config, update them. They fail loudly rather than silently: an unresolvable
+  declared name throws, and `vitops icons` reports scanned ones.
+
+  **Fixed three Font Awesome mappings that named no real glyph** and so rendered an
+  empty box: `login`/`logout` were mapped to `login`/`logout` (Font Awesome calls
+  them `right-to-bracket`/`right-from-bracket`) and `backup` to `backup`
+  (`cloud-arrow-up`). Every value in all four UI sets is now checked against the
+  installed collection.
+
+  **Phosphor (`ph`) joins the semantic map**, with all 83 names verified against the real icon set.
+  Phosphor keeps every weight in one collection and varies the name (`list`, `list-bold`), unlike Font
+  Awesome's per-weight collections, so `resolveIcon` and `generateIconInclude` gained a `weight`
+  option for sets shaped that way.
+
+  Fixes: `site.icons` was a closed object, so any icon collection not in its hand-written key list was
+  silently dropped during validation — your config passed and the icons never bundled. It accepts any
+  collection name now.
+
+- bf453b0: `vitops lint` now catches hand-written CSS that re-implements a framework primitive.
+
+  The existing linter finds classes that resolve to nothing — you named something and it isn't there.
+  This is the costlier inverse, where the code **works**: a centred container written by hand, a
+  two-column split behind a media query, a flex row. Nothing is broken, so nothing ever surfaces it,
+  and the design system quietly stops being where those decisions live.
+
+  Three rules to start, each requiring the combination that makes the intent unambiguous
+  (`margin-inline: auto` alone is not a centred track):
+
+  | Found                                                       | Suggested                                                                 |
+  | ----------------------------------------------------------- | ------------------------------------------------------------------------- |
+  | `max-inline-size: var(--width-*)` + `margin-inline: auto`   | `.centered`, widening a child with `breakout` / `spotlight` / `fullbleed` |
+  | `grid-template-columns: 1fr 2fr` inside a `min-width` query | `md-split-1-2` — or `@md:split-1-2` in the tailwind format                |
+  | `display: flex` + `align-items: center`                     | `flex items-center`, or `.cluster-start`                                  |
+
+  **Findings now carry a severity, and suggestions do not fail the command.** These are judgement
+  calls, and a reuse hint that broke CI on the day it shipped would be a worse defect than the drift it
+  reports. `--strict` promotes them for anyone who wants the ratchet. Everything the linter reported
+  before is an `error` and still exits 1.
+
+  `.css` files and `<style>` blocks are now read (the class linter only ever looked at markup). The
+  generated stylesheet is skipped by its `GENERATED … do not edit by hand` banner rather than by path —
+  the `css` format writes `styles.css` into `src/styles`, squarely inside what `--src` scans, and
+  linting it made the framework report `.split` as reinventing `.split`.
+
+  Two other gaps closed:
+  - **The format-spelling check ran in one direction only.** `md-split-1-2` in a tailwind project was
+    caught; `@md:split-1-2` in a css/bricks project was not, because variant stripping removed the
+    `@md:` regardless of format and left a bare class that matched nothing. The same silent no-op, in
+    the other direction, unreported. Stripping is format-aware now.
+  - **`grid-auto` and the whole `m-*` rhythm family were missing from the tailwind format entirely** —
+    not dropped via `TW_CLASH`, just never re-emitted when `layout.css` is skipped and a subset
+    re-emitted in its place. Unlike the `<bp>-` classes they have no Tailwind equivalent, and unlike a
+    misspelt class the linter cannot flag them, because they aren't anchored to your config. They emit
+    as `@utility` definitions now, keyed to the same `--rhythm-*` variables as the css format.
+
+  Run against this repo's own docs site, the rules found one real instance on the first pass; it is
+  fixed in the same change.
+
+- bf453b0: Maskable favicons are now opaque, so they stop rendering as a logo in a black box.
+
+  `icon-mask.png` is declared `purpose: "maskable"` and `apple-touch-icon.png` is linked on every
+  page. Both sit a deliberately-inset logo on a larger canvas — that inset **is** the maskable safe
+  zone and was always correct — but the canvas was filled with `alpha: 0`. From any transparent
+  source that left 36% of `icon-mask.png` and 40% of `apple-touch-icon.png` transparent, on two files
+  whose entire contract is full bleed: the OS crops them to its own shape and composites the rest onto
+  whatever it likes, usually black. iOS discards alpha on the apple-touch-icon outright.
+
+  `backgroundColor` was already the obvious input for this and already plumbed — as far as the web
+  manifest, and no further. So the raster and the manifest disagreed about the very colour meant to
+  sit behind the icon.
+
+  Now:
+  - those two outputs are composited onto `backgroundColor`, defaulting to `#ffffff` — the same
+    default the manifest's `background_color` already used;
+  - `favicon.svg`, `icon-{16,32,192,512}.png` and `favicon.ico` keep the source's transparency, since
+    none of them is maskable;
+  - a transparent source with no `backgroundColor` set now warns, rather than silently inheriting
+    white — a dark logo would lose against it;
+  - `icon-192`/`icon-512` declare `purpose: "any"` explicitly. Omitting it was legal (unset means
+    "any"), but with a maskable present and nothing claiming "any", some launchers picked the maskable
+    — the one with the safe-zone inset — for slots that wanted a plain icon.
+
+  `vitops favicon` gained `--background <hex>`; it previously had no way to set this at all.
+  `getvitops({ favicon })` and the Vite plugin now forward the option they were already accepting.
+
+### Patch Changes
+
+- bf453b0: Say plainly that `fonts` in `design-system.json` is stacks only and loads nothing.
+
+  The field's description was complete and self-consistent — "raw font stacks by name, emitted as
+  `--font-<name>` tokens" — and told you nothing about where the `@font-face` comes from. Following
+  it literally leads to installing a `@fontsource*` package and importing its CSS in a layout, which
+  renders correctly and silently gives up subsetting, preload, and the `size-adjust` /
+  `ascent-override` fallback metrics: a CLS regression that looks like a working setup.
+
+  The field is unchanged. What changed is that four surfaces now name the boundary and point at the
+  fix — declare the family in Astro's `fonts:` config and point the token at its `cssVariable`:
+  - the `fonts` description in the JSON Schema, and therefore `vitops docs authoring`
+  - `SKILL.md`, which previously never mentioned fonts at all
+  - the generated `tailwind.css` header and its `@theme` fonts comment
+  - the generated `type-tokens.css` header (css format)
+
+- Updated dependencies [4756788]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [04a51d8]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+- Updated dependencies [bf453b0]
+  - @getvitops/generator@2.0.0
+  - @getvitops/utils@2.0.0
+
 ## 1.0.0
 
 ### Major Changes

package/README.md

@@ -25,6 +25,13 @@ 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 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
+(`company.json` / `site.json`) — told apart by shape, so name the file whatever you like. Add
+`--theme <name>` to build a `designSystem.themes` entry other than the default. `vitops validate`
+routes the same way and checks a site config as a site config.
 
 ## Using the output
 
@@ -93,6 +100,51 @@ vitops generate --input design-system.json --format design --out .
 whenever your stylesheet goes somewhere other than the repo root. Regenerate it with your CSS; it's
 derived from the same config, so it can't drift from what the browser gets.
 
+## Video (`vitops media`)
+
+Keep unprocessed video in a `raw/` directory and encode it into web-ready outputs:
+
+```sh
+vitops media --raw raw --out src/assets/processed
+```
+
+Each source becomes three files — VP9/WebM, an H.264/MP4 fallback, and a JPG poster frame:
+
+```astro
+---
+import hero from '../assets/processed/hero.webm';
+import poster from '../assets/processed/hero.jpg';
+---
+<video poster={poster.src} autoplay muted loop playsinline>
+  <source src={hero} type="video/webm" />
+</video>
+```
+
+Outputs land under `src/` so your bundler content-hashes them and they can be served immutable,
+while the raw sources stay outside anything it scans.
+
+Defaults: capped at 1920px wide, CRF 32, audio dropped (the common case is a muted autoplay loop),
+poster taken from frame 0. Every one is a flag — `--max-width`, `--crf`, `--audio`,
+`--poster-time`, `--max-bitrate`, `--outputs`. `vitops media --dry` prints exactly what a run
+would do without encoding anything.
+
+**Needs `ffmpeg` on `PATH`.** It's an external tool, not an npm dependency — install it yourself
+(`brew install ffmpeg`, `apt install ffmpeg`, `winget install Gyan.FFmpeg`). The command fails
+rather than skipping: a page referencing a video that was never encoded is broken, not degraded.
+
+**Commit the outputs and `.vitops/media-manifest.json`.** Runs are cached on source content plus
+encode settings, so a second run costs a hash per file instead of minutes — but a fresh CI clone
+has neither, and would re-encode everything. Committing both means CI never needs ffmpeg at all.
+It also keeps your history clean: ffmpeg output isn't reproducible across versions, so a CI
+re-encode would rewrite every video on any toolchain bump. Use `--force` when you mean to
+re-encode, and commit the result.
+
+Two things worth knowing before you conclude something is broken:
+
+- **Frame 0 is often black** on a clip that fades in. That's `--poster-time`, not a bug.
+- **A missing output re-encodes, a corrupt manifest re-encodes everything.** Neither ever reads as
+  "already done" — the failure that would cause is silent, and a rebuild would never fix it.
+
 ## Teaching AI agents (`vitops agents` + `vitops docs`)
 
 This package **ships an agent skill** (`skill/SKILL.md`, the [Agent Skills](https://code.claude.com/docs/en/skills)