grails-cli 0.3.0 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grails-cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Grails Code Sync from the command line: reads a component library's code and uploads its design tokens and component specs to Grails.",
   "license": "UNLICENSED",
   "homepage": "https://docs.grails.design/cli/overview/",

package/templates/skill/grails-cli/SKILL.md

@@ -29,16 +29,32 @@ to choose when a new release reaches your pushes.
 | `grails-cli tokens [root] [--json]` | the design tokens a sync would upload (with `dtcg`: the files, or the exact upload with `--json`) | no |
 | `grails-cli tokens baseline [root] --out <dir> [--in-repo]` | writes the scanner's tokens as DTCG files and a resolver, a first version to own | no |
 | `grails-cli sync [root] [--dry-run] [--json]` | uploads the tokens, then the components | yes (with `--dry-run`: asks what would change, stores nothing) |
-| `grails-cli tokens pending [root] [--json]` | the token changes people asked for in Grails, before → after | reads only |
+| `grails-cli tokens pending [root] [--collection <name>] [--request <id>] [--json]` | the token changes people asked for in Grails: type, before → after, and the id; the filters narrow it | reads only |
+| `grails-cli tokens discard <change-id> \| --all [--collection <name>] \| --request <id> --reason "<why>" [--dry-run]` | closes one change, or a set in one step, that your team will not carry, with the reason | yes (Grails keeps the changes, closed); `--dry-run` changes nothing |
 | `grails-cli rules [root] [--set code=figma]` | the naming rules that match code tokens to Figma ones | edits need `write:tokens` |
-| `grails-cli status` | the project's code sources and their last syncs | reads only |
+| `grails-cli connect [--prompt]` | keeps the API key in the operating system's keychain (checked against Grails first) so no command needs `GRAILS_API_KEY`; reads the clipboard and clears it, or with `--prompt` asks in a hidden prompt | reads only (one authenticated read to validate the key) |
+| `grails-cli disconnect` | removes the key `connect` stored (the key itself is not revoked) | no |
+| `grails-cli update [root]` | asks the npm registry now for the latest `grails-cli` and prints the command that updates it for the project's package manager; it does not run it | asks the npm registry only |
+| `grails-cli status` | the project's code sources, their last syncs, and how many changes asked for in Grails wait for each | reads only |
 | `grails-cli chi [root]` | the Component Health Index of every component | no |
 | `grails-cli check-classes [root]` | Tailwind classes that are probably misspelt | no |
 | `grails-cli skill` | prints this file | no |
 
-**The API key** is read from `GRAILS_API_KEY` and from nowhere else. Never pass it as a flag, and never print the
-environment. To create one, go to Team Settings › Integrations › API Keys in Grails and give it the `write:code`
-scope. `GRAILS_API_URL` points the CLI at another API.
+**The API key** is read from `GRAILS_API_KEY` in the environment (CI, and anyone who prefers it) and, when that is not
+set, from the operating system's keychain, where `grails-cli connect` put it; and from nowhere else. Never pass it as a
+flag or an argument, and never print the environment. To create one, go to Team Settings › Integrations › API Keys in
+Grails and give it the `write:code` scope. `GRAILS_API_URL` points the CLI at another API; the keychain keeps one key
+per API, by its host.
+
+**An agent does not run `connect` for the person.** `connect` takes the key from the person's clipboard or from a hidden
+prompt on their terminal; a key an agent was handed in a chat is already in a transcript, so it does not go to
+`connect --prompt` either. When there is no key, tell the person to run `grails-cli connect` in their own terminal (or to set
+`GRAILS_API_KEY`), and carry on with the commands that need none (`init`, `scan`, `tokens`, `sync --dry-run`).
+
+**Updates.** Once a day the CLI asks the npm registry for the latest version and, while it is behind, every run ends with
+one line on stderr naming the two versions and the update command. That line is not an error and does not change the
+exit code. `GRAILS_CLI_NO_UPDATE_CHECK=1` turns it off. `grails-cli update` prints the command and never runs it: update
+the version only when the person asks.
 
 ## `grails.code.json`
 
@@ -59,6 +75,9 @@ scope. `GRAILS_API_URL` points the CLI at another API.
   - `files` are globs of `.json` files.
   - `resolver` is optional, and is a DTCG resolver document. Its `$ref`s name the files relative to its own folder,
     so every file must sit in or below that folder.
+  - `cssVariables` is optional: how your CSS names the tokens, so Grails can tell which token a `var(--x)` is. It holds
+    the `prefix` of your build, the `exceptions` to the naming, and `ignore`, patterns for custom properties that are
+    not your tokens. See "Telling Grails which token a `var(--x)` is".
 - **`css`** (CSS files whose custom properties are tokens) and **`tokens`** (TypeScript token objects) are for the
   scanner, when there is no `dtcg`.
 
@@ -74,8 +93,119 @@ scope. `GRAILS_API_URL` points the CLI at another API.
    being the source. The command lists the values the scanner left out (they are not in the files), refuses to run while
    `dtcg` is set, and never writes into a folder that has files.
 
-With DTCG, a sync records which components each component renders, but **not which tokens it uses**: nothing tells
-Grails which DTCG token a style's `var(--x)` is. The sync says so in its output.
+With DTCG, a sync records which components each component renders, and which tokens it uses **only through a `var(--x)`
+that `cssVariables` ties to a token** (next section). Every `var(--x)` it cannot tie is listed, so you can fix it.
+
+## Telling Grails which token a `var(--x)` is
+
+*This section is written for a coding agent that is asked to set it up. Follow the steps in order, and never guess a
+name.*
+
+Your components write `var(--color-brand-500)`; your DTCG files say `color.brand.500`. With `dtcg` declared, the scanner
+reads no token, so the only thing that ties the two is how your build names a token's custom property. Grails assumes
+**Style Dictionary's default**, the `css` transform group (`name/kebab`):
+
+- the token's path segments, joined with `-`, lower case, behind two dashes: `color.brand.500` is `--color-brand-500`;
+- with the build's `prefix` first: `prefix: "ds"` makes it `--ds-color-brand-500`;
+- camelCase is split (`fontSize` → `font-size`, `h1Bold` → `h1-bold`), but **a digit stays with its letters** (`2xl`
+  stays `2xl`, `body2` stays `body2`);
+- anything that is not a letter or a digit is a separator (`Brand Primary`, `brand_primary` and `brand-primary` all give
+  `brand-primary`);
+- the name is **case-sensitive**: `var(--Color-Brand-500)` is no token, because the build writes lower case.
+
+Where a name does not follow that, you write an **exception**: the custom property and the token it is. A custom
+property that is **not your token at all** (a library's, the framework's) goes in **`ignore`**, as a pattern.
+
+```json
+{
+  "dtcg": {
+    "files": ["tokens/**/*.json"],
+    "resolver": "tokens/resolver.json",
+    "cssVariables": {
+      "prefix": "ds",
+      "exceptions": { "--brand": "color.brand.500", "--surface": "color.semantic.surface" },
+      "ignore": ["--radix-*", "--tw-*"]
+    }
+  }
+}
+```
+
+All three keys are optional. An exception's value is the token's dotted path in the files (the first segment is its
+collection). **An exception wins over the convention**, and one that names a path the files do not have is reported.
+
+**`ignore` is a list of patterns**: a name as `var()` writes it, two dashes first, with `*` for the part that varies
+(`*` is the only wildcard, and at most 200 patterns). A name an `ignore` pattern covers is not resolved, not counted,
+not listed and never sent, **even when the convention would have found a token of that name**; an exception for the same
+name wins over `ignore`. A pattern that covers nothing the components use is not an error: `--json` lists it in
+`css_variables.ignore_unused`, and the terminal line says how many were ignored (`· 14 ignored`), never which.
+
+**The steps:**
+
+1. **Look at how the repository builds its CSS from the DTCG files.** Find the Style Dictionary configuration
+   (`config.json`, `style-dictionary.config.*`, `sd.config.*`, or a script that calls it) and read, for the CSS platform,
+   its `prefix`, its `transformGroup` and its `transforms`. Then open the CSS it generates and look at a few real names:
+   a name in the output beats a reading of the configuration.
+   - `transformGroup: "css"` (or `name/kebab` in `transforms`), and no custom `name` transform: the convention applies.
+   - `name/camel`, `name/snake`, `name/constant`, `name/pascal` or a custom `name` transform: the names do not follow
+     the convention, and each one a component uses needs an exception.
+2. **Set the prefix**: `"cssVariables": { "prefix": "<the build's prefix>" }`, and leave it out when the build has none.
+3. **Run `grails-cli sync --dry-run`.** It needs no key and sends nothing (with a key it also asks Grails what
+   would change). `--json` adds a `css_variables` object with the same list. The line `css variables` counts the custom
+   properties your components use and how many resolve to a token.
+4. **Read the unresolved list** (the `!` lines under it), and decide each one:
+   - `var(--x) is no token of the DTCG files`: find where `--x` comes from, and choose by who owns it.
+     - **It is your token under another name**: generated from a DTCG token, or an alias of a generated one
+       (`--x: var(--ds-color-brand-500)`). Add it to **`exceptions`** with that token's path. An exception says what a
+       name IS.
+     - **It is not your token, and never will be**: a library's, the framework's, one the page sets at run time. Add a
+       pattern that covers the family to **`ignore`**, so the list holds only what a person still has to decide.
+       Examples that are common: Radix sets sizes for its popovers and menus
+       (`--radix-dropdown-menu-content-available-height`, `--radix-select-trigger-width`: pattern `--radix-*`);
+       Tailwind's own internals, which a component reads when it writes a ring or a shadow by hand
+       (`--tw-ring-color`, `--tw-ring-offset-color`: pattern `--tw-*`); a value the page sets from JavaScript (`--vh`,
+       `--scroll-y`). A custom property one component declares for itself (`--card-padding`) is also not a token: ignore
+       it, by name or by a prefix that component's team already uses.
+     - **You cannot tell which of the two it is**: do not ignore it and do not guess an exception. Leave it listed and
+       ask the person.
+   - `var(--x) is the name of N tokens`: two tokens spell the same CSS name (`brandPrimary` and `brand-primary`).
+     Read the generated CSS to see which one the build keeps (the last declaration wins), and add that one to
+     `exceptions`. Better, rename one of them in the DTCG files.
+   - `dtcg.cssVariables.exceptions: --x names color.y, which is not a token of the DTCG files`: the exception is
+     mistyped, or the token was renamed or removed. Fix its path (`grails-cli tokens --json` prints the files) or
+     delete the exception.
+   - `whose name has a "/"`: a level of that token's name contains a `/`, which a usage upload cannot spell. Rename the
+     level in the DTCG files.
+5. **Run step 3 again** until every remaining `!` line is one you decided to leave for the person. Then tell them what
+   you added to `exceptions` and to `ignore` and what you left, with the reason for each.
+6. **Prune** with `grails-cli sync --dry-run --json`: `css_variables.ignore_unused` lists the patterns that ignored
+   nothing (no component uses a name they cover, or an exception already names every such name). Delete those.
+
+**Keep `ignore` narrow.** A pattern beats the naming convention, so `--*-bg` would hide a real token that happens to end
+in `-bg`: the token would no longer be tied to the components that use it, and the line would not say so. Cover a family
+by its owner's prefix (`--radix-*`), not by a shape (`--*-width`). If a name the pattern covers IS a token, add an
+exception for it: that is the way to keep one inside a broad pattern.
+
+**What this reads, and what it does not.** The scanner reads a `var(--x)` a component can use in three places:
+
+- **the `style` of any element** in the component, every property (`margin`, `border`, `boxShadow`, …) and not only
+  colour, padding and size; also the props libraries use for styles (`contentContainerStyle`, `css`, `sx`), a constant or
+  style sheet the style refers to, and every branch of a condition or lookup;
+- **the stylesheet the component's file imports** (`.css`, CSS modules, `.scss`, `.less`), for every component that file
+  holds. A custom property a rule *declares* in `:root`, a theme selector or `@theme` is a definition, not a use, so a
+  tokens sheet imported by a layout does not make the layout "use" every token. `@import` inside a stylesheet is not
+  followed;
+- **Tailwind classes** in `className` and in `cn`, `clsx`, `classnames`, `cx`, `twMerge` and `cva` calls, variants
+  included: `bg-[var(--x)]` in either version, `bg-(--x)` in Tailwind 4, `bg-[--x]` in Tailwind 3. (Tailwind 4
+  compiles `bg-[--x]` to a literal `--x`, not a `var()`, so it is not read there.)
+
+It does **not** read a name a template assembles at run time (`` `var(--space-${n})` ``), a class helper it does not know
+(`tv()`), CSS-in-JS template literals (styled-components, Emotion's `css` tag), a component a file defines but does not
+export, or a property set from JavaScript. So a custom property missing from the list may still be used. A reference
+that is not a `var()` (a Tailwind theme class such as `bg-primary`, a TypeScript token object) is counted in a line ("N
+token reference(s)… are not linked") but not tied to a token. A run never fails for any of this.
+
+**Do not** edit the token files or the CSS to make a line disappear: an exception, or a pattern in `ignore`, is the
+team's statement of what a name is, or that it is not theirs.
 
 ## Writing DTCG that Grails accepts
 
@@ -110,21 +240,78 @@ Grails reads the **DTCG format 2025.10** (designtokens.org) and validates every
 - **Booleans, copy strings, blurs and layout grids.** Use no `$type`, a readable string `$value` (`"true"`,
   `"blur(4px)"`, `"12 columns, 24px gutter"`), and the real value in
   `design.grails.value: { "type": "boolean" | "string" | "blur" | "grid", "value": … }`.
+- **A colour built from a colour and an opacity token.** Keep the applied colour in `$value`, and name the parts in
+  `design.grails.composed: { "color": "{path}" or a DTCG colour, "opacity": "{path}" }`. The opacity token is read
+  as it is: a Figma opacity is 0–100, so divide by 100.
 
-Grails keeps these extensions with each token. Interpreting them is still being built, so write them now, and nothing
-is lost when it lands.
+**What Grails does with them.**
+- It reads a token with `design.grails.value` as that type and that value. The extension wins over `$value`, so a
+  `$value` like `"{brand}"` there is text, not a reference.
+- It validates the forms above. A malformed one (a boolean whose value is `"yes"`, a `textCase` of `"shout"`) refuses
+  the sync with `extension_invalid` and the pointer. A `{path}` inside them that names no token is `alias_unknown`.
+- What it does not know (a key a form does not have, a value type it has never seen) is kept as written, with the
+  warning `extension_not_interpreted`, so a document a newer tool wrote loses nothing.
 
 When a sync is refused, each finding names the file, the JSON pointer inside it and a code (`schema_invalid`,
-`token_at_root`, `legacy_format`, `alias_unknown`, `alias_cycle`, …). Fix the source and sync again.
+`token_at_root`, `legacy_format`, `alias_unknown`, `alias_cycle`, `extension_invalid`, …). Fix the source and sync
+again.
 
 ## Changes asked for in Grails
 
 Admins and editors can ask for token changes in Grails: a new value, a new token, collection or mode, or a removal.
-`grails-cli tokens pending` lists them by collection, as `before → after` in DTCG. Carry each one into your token
-source, or into the rules that generate it.
+**Grails never writes your repository, and neither does the CLI.** Closing the loop takes three steps, and the last one
+is automatic:
+
+1. `grails-cli tokens pending` lists the changes by collection: each with its **type**, `before → after` as DTCG, and
+   its **id**. The `before` is the value your repository holds now, resolved (an alias in your code shows as the colour
+   it resolves to). `--json` has every value exact.
+2. Carry each change into your token source, or into the rules that generate it, and merge it as any other change.
+3. The next `grails-cli sync` (in CI, on the declared branch) **marks the change applied** once your repository holds
+   its value, and prints how many. Grails compares the resolved value of the token in that mode, with the tolerance the
+   Diff uses for colours and sizes, so an alias that resolves to the asked value counts. A token you removed closes
+   its change; a created token, collection or mode closes when it exists.
+
+To see what the next sync would do **before** it runs, use `grails-cli sync --dry-run` (with the key): it prints how many
+changes it would mark applied, close because their token is gone, or leave open, with their ids, and stores nothing.
+`grails-cli status` shows how many changes wait for each source.
+
+**If the repository holds another value, the change is not closed.** Grails keeps proposing its value, checks again on
+every sync, and records what your code holds: running `tokens pending` again after a sync shows the real "before".
+
+**A change your team will not carry is closed with a reason, not ignored:**
+
+```sh
+grails-cli tokens discard <change-id> --reason "Handled in the design-tokens repo"
+```
+
+- The id is the one `tokens pending` prints beside the change. Never invent one.
+- `--reason` is required: 1 to 1000 characters on one line. Say why, in words a designer reads: Grails keeps it with the
+  change, with who discarded it (the owner of the API key) and that it came from code.
+- Discarding a collection takes its modes and tokens with it. One value of a token being created cannot be discarded
+  alone: discard the token.
+- Exit 3 means Grails has no open change with that id for this source, or it was already applied or discarded. Do not
+  retry; list again with `tokens pending`.
+- Do it only when the team decided not to carry the change. If it only has not been carried yet, leave it: the sync
+  closes it when it arrives.
+
+**Many at once.** Exactly one of three picks the changes (the reason is required, as above):
+
+```sh
+grails-cli tokens discard --all --dry-run                              # look first: nothing is changed
+grails-cli tokens discard --all --reason "Handled in the tokens repo"  # everything waiting for this repository
+grails-cli tokens discard --all --collection color --reason "…"        # one collection's
+grails-cli tokens discard --request <request-id> --reason "…"          # one change request's
+```
 
-⚠️ For now, a change you carried over still shows as pending in Grails. Marking it applied when a sync shows the
-repository says the same is designed but not built yet.
+- `--dry-run` lists the changes that would be discarded (id, token, before → after) and changes nothing. Run it first
+  and read the list: there is no `--yes`, and a discard cannot be undone from the CLI.
+- The set is closed all together or not at all, and at most 1000 at once. Past that the CLI says so and discards
+  nothing: narrow it with `--collection` or `--request`.
+- `tokens pending --collection <name>` and `--request <id>` list exactly what the same words would discard. The request
+  id is printed under the heading of `tokens pending`.
+- `--collection` goes with `--all` only. Naming a change id and `--all` together is refused.
+- The answer says how many were discarded; `--json` has the ids. Exit 3 means a request or source Grails does not hold
+  (nothing was discarded) or a set over the cap.
 
 ## In CI