grails-cli 0.0.0-stage → 0.3.0

package/package.json

@@ -1,6 +1,47 @@
 {
   "name": "grails-cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.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/",
+  "keywords": [
+    "grails",
+    "design-system",
+    "design-tokens",
+    "dtcg",
+    "components",
+    "figma",
+    "react",
+    "tailwind",
+    "cli",
+    "code-sync"
+  ],
+  "packageManager": "pnpm@10.32.1",
+  "type": "module",
+  "bin": {
+    "grails-cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "templates"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "smoke": "node scripts/smoke.mjs",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
+  },
+  "dependencies": {
+    "typescript": "5.8.3"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "esbuild": "^0.27.7"
+  }
+}

package/templates/grails-cli-sync.yml

@@ -0,0 +1,56 @@
+# Grails Code Sync: on every push to the branch your team syncs from (a merge into it), read this repository's
+# design tokens and components and upload them to Grails, so the vault shows what the code actually holds.
+#
+# SETUP
+#   1. In Grails, create an API key with the write:code scope: Team Settings > Integrations > API Keys.
+#   2. Save it as a repository secret named GRAILS_API_KEY: Settings > Secrets and variables > Actions.
+#   3. Say in grails.code.json which branch syncs ("branch": "main", or "preview", …): `npx grails-cli init`
+#      proposes it. Put the SAME branch under `branches:` below.
+#   4. Commit this file as .github/workflows/grails-cli-sync.yml.
+#
+# THE KEY stays in the step's `env:`. It is never written into a `run:` line, never echoed, and never passed as
+# an argument: the CLI reads it from the environment and refuses it as a flag. Do not change that, and do not run
+# this on `pull_request`, where a fork's run has no secrets and no business syncing.
+#
+# WHAT LEAVES THE REPOSITORY: design tokens (names, types, values), component names, file paths, and each
+# component's spec (props, anatomy names, resolved style values). Never source code. `npx grails-cli tokens
+# --json` prints the exact token list. `sync --dry-run` stores nothing: with the key it asks Grails what would
+# change, without it it counts locally.
+#
+# EXIT CODES: 0 done · 1 the sync ended incomplete · 2 misconfigured (grails.code.json declares no branch, too) · 3
+# refused by the server (a CLI older than the minimum, too) · 4 the server could not be reached or failed. Only 4 is
+# worth retrying.
+#
+# THE BRANCH: the CLI uploads only from the branch grails.code.json declares. Run anywhere else it uploads nothing,
+# exits 0 so the job stays green, and says so: a notice on the run, the job summary, and the step output
+# `steps.grails.outputs.result` = `skipped-branch` (otherwise `synced`, `preview`, `offline` or `failed`).
+#
+# THE VERSION: `npx --yes grails-cli` fetches the latest release from npm on every run. To choose when a new release
+# reaches your pushes, pin a version (`grails-cli@<version>`) so a new release cannot change a push you did not look at.
+name: Grails Code Sync
+
+on:
+  push:
+    # The branch grails.code.json declares. Keep the two equal.
+    branches: [main]
+
+permissions:
+  contents: read
+
+jobs:
+  sync:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      # Needed when the library uses Tailwind (its tokens are read with the project's OWN tailwindcss; without the
+      # dependencies installed the run exits 2), and better in any case: with them the scanner reads the types the
+      # way the project does (the "typed" run). Use your package manager's command.
+      # - run: npm ci
+      - name: Sync the design tokens and the components to Grails
+        id: grails
+        env:
+          GRAILS_API_KEY: ${{ secrets.GRAILS_API_KEY }}
+        run: npx --yes grails-cli sync --trigger ci

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

@@ -0,0 +1,150 @@
+---
+name: grails-cli
+description: Use when working with the Grails CLI (`grails-cli`) in a component library's repository. That covers setting up `grails.code.json`, syncing components and design tokens to Grails from a terminal or from CI, writing DTCG token files that Grails accepts, starting a first DTCG version from the scanner's tokens, listing the token changes people asked for in Grails, and fixing a sync that failed. Triggers on grails-cli, grails.code.json, Grails Code Sync, GRAILS_API_KEY, DTCG upload, design tokens to Grails, tokens pending, tokens baseline.
+---
+
+# The Grails CLI
+
+Grails (grails.design) keeps a design system's Figma files and its code side by side. This CLI reads your
+component library's repository (its components and its design tokens) and syncs them to a Grails project.
+
+**It never changes your code.** It writes only the files you explicitly ask it to: `init --write` writes
+`grails.code.json`, `scan --out <file>` writes the manifest, and `tokens baseline --out <dir>` writes the scanner's
+tokens as DTCG files (both refuse a path inside the repository unless you pass `--in-repo`). When people in Grails ask
+for a token change, the CLI lists the change, and you or your build make it in your own source.
+
+## Install
+
+`npm i -D grails-cli` in the repository (Node 20 or newer), or run any command without installing it as
+`npx grails-cli <command>`. The commands below are written `grails-cli`. The GitHub workflow template the package
+ships (`templates/grails-cli-sync.yml`) runs `npx --yes grails-cli sync`: pin a version in it (`grails-cli@<version>`)
+to choose when a new release reaches your pushes.
+
+## Commands
+
+| command | what it does | sends anything? |
+|---|---|---|
+| `grails-cli init [root] [--write]` | proposes a `grails.code.json` from the code, with the evidence for each decision | no |
+| `grails-cli scan [root] [--out <file>]` | writes the component manifest Grails would receive | no |
+| `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 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 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.
+
+## `grails.code.json`
+
+```json
+{
+  "branch": "main",
+  "components": ["src/components/**/*.tsx"],
+  "exclude": ["**/*.stories.tsx"],
+  "dtcg": { "files": ["tokens/**/*.json"], "resolver": "tokens/resolver.json" }
+}
+```
+
+- **`branch`** is required for a real sync. It names the branch that IS this source in Grails: the one merges land
+  on. Run anywhere else, the sync uploads nothing and exits 0.
+- **`components`** and **`exclude`** are globs, relative to the root.
+- **`dtcg`** names your DTCG files. **When it is set, it is the only token source**: the scanner reads no token from
+  Tailwind or CSS, and `css` and `tokens` are ignored with a warning.
+  - `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.
+- **`css`** (CSS files whose custom properties are tokens) and **`tokens`** (TypeScript token objects) are for the
+  scanner, when there is no `dtcg`.
+
+## Tokens: two ways in
+
+1. **DTCG files (the recommended way).** Generate them with your tool of choice: a Style Dictionary build,
+   Tokens Studio's DTCG export, Specify, your own script. Declare them in `dtcg`, and `sync` uploads them as they are.
+   Grails reads them and answers with precise findings when it cannot.
+2. **The scanner (a convenience).** With no `dtcg`, the CLI reads a Tailwind 3 or 4 theme, the CSS custom properties
+   of the files in `css`, and the token objects in `tokens`. It is good for a first sync. Anything it does not
+   support should be exported to DTCG rather than worked around. To move to DTCG, run `tokens baseline --out <dir>`,
+   review the files, commit them and declare them in `dtcg`. From then on the files are yours and the scanner stops
+   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.
+
+## Writing DTCG that Grails accepts
+
+Grails reads the **DTCG format 2025.10** (designtokens.org) and validates every document against its schema.
+
+- **A token's path is its dotted name, and the first segment is its collection.** `color.brand.500` belongs to the
+  collection `color`. A token directly at the root (one segment) is refused.
+- **Types.** All 13 DTCG types are accepted: `color` (`{ "colorSpace", "components" }`), `dimension`
+  (`{ "value", "unit" }`), `number`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `strokeStyle`, `border`,
+  `transition`, `shadow` (one or a list, `inset` allowed), `gradient` and `typography`. A group's `$type` applies to
+  the tokens inside it.
+- **Aliases** are `{path}` references, at most 64 deep, with no cycles. A JSON Pointer `$ref` inside a value is
+  refused: use `{path}`.
+- **Modes.**
+  - With no resolver, each collection has one mode, `default`.
+  - With a resolver, its sets give every mode the same value, and a modifier's contexts become the collection's modes.
+  - Two or more modifiers give one mode per combination, named with `·` (`light·brand-a`), at most 50.
+  - A resolver's `$ref` names only a file of the same upload (or `#/sets/x`, `#/modifiers/x`). Nothing is fetched.
+- **Limits.**
+  - At most 500 files and 4 MiB in one upload.
+  - At most 20,000 values, 500 collections, 20 modifiers, 50 contexts per modifier, and groups 32 levels deep.
+  - The CLI checks the file count and the size before sending anything.
+- **Refused outright:**
+  - Tokens Studio's legacy format (`$themes`, `$metadata`, or `value` / `type` without `$`): export as DTCG (W3C).
+  - A `boolean` or object `$value` with no `$type`.
+
+**What DTCG cannot express.** The token stays valid DTCG, with a `$value` any tool can read, and the extra goes in
+`$extensions` under a `design.grails.*` key:
+
+- **Typography.** Use `design.grails.typography.extraProps`: `textCase`, `textDecoration`, `fontStyle`,
+  `paragraphSpacing`, `paragraphIndent`, `listSpacing`, `leadingTrim`.
+- **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": … }`.
+
+Grails keeps these extensions with each token. Interpreting them is still being built, so write them now, and nothing
+is lost when it lands.
+
+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.
+
+## 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.
+
+⚠️ 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.
+
+## In CI
+
+The package ships `templates/grails-cli-sync.yml`, a GitHub Actions workflow that runs `npx --yes grails-cli sync --trigger ci`
+on a push to the declared branch.
+
+- Store the key as the repository secret `GRAILS_API_KEY`. It reaches the step only through `env:`, never inside a
+  `run:` line.
+- Do not run it on `pull_request`.
+- The run writes a job summary, and the step output `result` is `synced`, `preview`, `offline`, `skipped-branch` or
+  `failed`.
+
+**Exit codes:**
+
+| code | meaning |
+|---|---|
+| 0 | done (synced, unchanged, or a dry run) |
+| 1 | the sync ended incomplete |
+| 2 | misconfigured: a flag, `grails.code.json` (no `branch`, a DTCG file that is not JSON or matches nothing), or the key |
+| 3 | refused by the server: the key, the plan, or the content (DTCG findings included) |
+| 4 | the server could not be reached or failed |
+
+Only 4 is worth retrying.