@grum-os/cli 0.3.4 → 0.3.6
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -88
- package/brand.png +0 -0
- package/content.md5 +1 -1
- package/grum.mjs +176 -162
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -1,52 +1,76 @@
|
|
|
1
|
-
|
|
1
|
+
<img src="brand.png" alt="Grum" width="228" height="64" />
|
|
2
2
|
|
|
3
|
-
|
|
4
|
-
|
|
5
|
-
Grum reads the tokens the repository declares (CSS custom properties, a Tailwind v4 `@theme`, SCSS variables) and the button looks it defines. The team can add tokens in Grum before the code has them, and move others outside the contract. That reviewed set is what `grum` checks against. It does not invent a contract of its own, and it does not publish one.
|
|
3
|
+
# Grum
|
|
6
4
|
|
|
7
|
-
|
|
5
|
+
Keep a repository on the design contract your team reviewed in [Grum](https://app.grum.so).
|
|
8
6
|
|
|
9
|
-
|
|
7
|
+
Grum reads the tokens the repository declares (CSS custom properties, a Tailwind v4 `@theme`, SCSS variables) and the button looks it defines. The team can add tokens in Grum before the code has them, and move others outside the contract. That reviewed set is what `grum` checks against. It compares your working tree to the contract, lists only drift that is new on this branch, and can send a new item to the project's owners for review, with a picture of how it renders.
|
|
10
8
|
|
|
11
9
|
Requires Node.js 22 or newer.
|
|
12
10
|
|
|
13
|
-
##
|
|
11
|
+
## Quick start
|
|
12
|
+
|
|
13
|
+
Open a terminal in the repository, and run with no arguments:
|
|
14
14
|
|
|
15
15
|
```sh
|
|
16
|
-
|
|
16
|
+
npx @grum-os/cli
|
|
17
17
|
```
|
|
18
18
|
|
|
19
|
-
|
|
19
|
+
Grum opens a wizard. The arrow keys move, Enter selects, and 1, 2, or 3 jump straight to a row. `q` quits.
|
|
20
20
|
|
|
21
|
-
```
|
|
22
|
-
|
|
21
|
+
```text
|
|
22
|
+
1 check Check this repository against its design contract
|
|
23
|
+
2 setup Sign in, link this repository, set up Cursor
|
|
24
|
+
3 login Sign in to Grum
|
|
23
25
|
```
|
|
24
26
|
|
|
25
|
-
|
|
27
|
+
Choose **setup**. Grum walks through the rest:
|
|
26
28
|
|
|
27
|
-
|
|
29
|
+
1. **Sign in.** It prints a code and a link. Approve the code in the browser. The token stays in your home directory (`~/.config/grum/credentials/`), never in the repository. Grum's Settings page lists every computer that is signed in.
|
|
30
|
+
2. **Link this repository** to its project in Grum. If several workspaces use it, you pick one. If none does yet, Grum offers to create a workspace, asks for the live site, and waits while the first scan runs. A new workspace needs GitHub connected in Grum.
|
|
31
|
+
3. **Set up Cursor.** It asks `Setup for cursor agents?` Press Enter to accept. That writes the hooks, the tools, and the rule described below. `n` skips it. It then asks `Add a pre-commit check?` Enter skips that. `y` adds `grum check --staged` to the hook this repository already uses.
|
|
28
32
|
|
|
29
|
-
|
|
33
|
+
Then choose **check**. New drift is listed with a one-line fix, and Grum offers to send each item for review. You do not need to type a command for any of that.
|
|
30
34
|
|
|
31
|
-
|
|
32
|
-
grum setup
|
|
33
|
-
```
|
|
35
|
+
Once you are signed in, the third row is **logout**. Run `grum` again and choose **setup** to change the link or turn Cursor off. Enter keeps each current setting.
|
|
34
36
|
|
|
35
|
-
|
|
37
|
+
## Cursor
|
|
36
38
|
|
|
37
|
-
|
|
38
|
-
2. **Links the git remote to its Grum project.** If several workspaces use this repository, it asks which one. If none does yet, it offers to create a workspace, asks for the live site, and waits while Grum runs the first scan.
|
|
39
|
-
3. **Asks whether to set up Cursor.** That writes the hooks, the MCP server, the rule pointer, and a pre-commit check described below. Enter accepts. `n` skips it.
|
|
39
|
+
Accepting Cursor in the menu puts Grum inside the agent. The agent follows the same contract a person sees in Grum, and it can ask the owners to allow something the contract does not have.
|
|
40
40
|
|
|
41
|
-
|
|
41
|
+
**Before it writes UI**, it reads the contract: color, typography, spacing, and radius tokens, plus button components, each look, and the prop that selects it.
|
|
42
42
|
|
|
43
|
-
|
|
43
|
+
**Before it finishes**, it checks what it changed. Drift already on the default branch stays off the list. New drift comes back with a fix.
|
|
44
44
|
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
45
|
+
**When nothing in the contract fits**, it stops and asks you once:
|
|
46
|
+
|
|
47
|
+
1. Use an existing token or button.
|
|
48
|
+
2. Keep the new style and request review.
|
|
49
|
+
|
|
50
|
+
If you keep it, Grum captures how the element renders and sends the picture to the Review page. Owners approve or reject it there. A rejected style is not offered again: the agent changes the code to use the contract.
|
|
51
|
+
|
|
52
|
+
**While you edit**, Cursor hooks check the block that changed. They read the contract cached in `.grum/` and do not call the network, so an edit never waits on Grum. With [blocking](#fail-the-check) turned on, the agent is sent back while that drift stands (twice in one conversation), and `git commit` and `git push` from the agent are refused until it is resolved.
|
|
53
|
+
|
|
54
|
+
Reload the Cursor window once after setup, or turn **grum** on under Settings, Tools and MCP, so the agent sees the tools. Until then it reads `.grum/contract.json`.
|
|
48
55
|
|
|
49
|
-
|
|
56
|
+
These are the files setup writes. They merge into what is already there, and a second run changes nothing.
|
|
57
|
+
|
|
58
|
+
| File | What it does |
|
|
59
|
+
| ------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
60
|
+
| `.cursor/mcp.json` | Tools the agent calls: `grum_contract`, `grum_check`, `grum_request_review`, `grum_review_status`. |
|
|
61
|
+
| `.cursor/rules/grum.mdc` | Tells the agent to read the contract before writing UI and to check before it stops. The contract itself stays in Grum, so this file does not go stale. |
|
|
62
|
+
| `.cursor/hooks.json` | After an edit, checks that block. The stop hook sends the agent back on blocking drift. The shell hook can refuse `git commit` and `git push`. |
|
|
63
|
+
| pre-commit | Optional. When you say yes, adds `grum check --staged`. Husky's hook is committed with the repo. Git's own pre-commit hook stays on this computer. A lefthook repo gets the snippet to paste. |
|
|
64
|
+
|
|
65
|
+
`.grum/` is added to `.gitignore` the first time Grum writes there. Choose **setup** again and answer `n` to the Cursor question to remove what Grum added. Answer `n` to the pre-commit question to drop only that check.
|
|
66
|
+
|
|
67
|
+
`grum check --cursor` opens the findings in Cursor instead of walking through them in the terminal.
|
|
68
|
+
|
|
69
|
+
## What a check shows
|
|
70
|
+
|
|
71
|
+
Choosing **check** in the menu prints the same report as `grum check`.
|
|
72
|
+
|
|
73
|
+
New drift is grouped by file. Each line names the value, the kind of drift, whether anyone has asked for review, and a fix:
|
|
50
74
|
|
|
51
75
|
```text
|
|
52
76
|
src/pages/Hero.tsx
|
|
@@ -64,28 +88,9 @@ No new drift against Acme's contract (42 files checked). 3 known issues are on A
|
|
|
64
88
|
|
|
65
89
|
Using a known value in more places than the default branch does is new drift.
|
|
66
90
|
|
|
67
|
-
In
|
|
68
|
-
|
|
69
|
-
A request covers the branch it was asked on. It covers every branch once the change reaches the default branch and a scan counts the drift as existing. A full check also marks a rejected review **Addressed** when the drift is gone, and reopens it when the drift comes back.
|
|
70
|
-
|
|
71
|
-
### Flags
|
|
72
|
-
|
|
73
|
-
```sh
|
|
74
|
-
grum check --staged # drift in the blocks staged for commit
|
|
75
|
-
grum check --files src/Hero.tsx # only these paths
|
|
76
|
-
grum check --json # project, cache time, known count, findings
|
|
77
|
-
grum check --no-review # print the report and do not ask
|
|
78
|
-
grum check --cursor # open the findings in Cursor
|
|
79
|
-
grum check --offline # the cached contract, no network
|
|
80
|
-
grum check --root apps/web # the app lives in a subdirectory
|
|
81
|
-
grum check --report # also post this run to Grum
|
|
82
|
-
grum check --ci # fail on open or rejected drift, and post the run
|
|
83
|
-
grum check --strict # like --ci, and also fail while a review is pending
|
|
84
|
-
```
|
|
85
|
-
|
|
86
|
-
`--json` is what you want when another program needs the drift key. CI, JSON, staged, and agent runs never prompt and never open Cursor.
|
|
91
|
+
In the terminal, the check then offers each new item for review. A request covers the branch it was asked on, until the change reaches the default branch and a scan counts the drift as existing. A full check also marks a rejected review **Addressed** when the drift is gone, and reopens it when the drift comes back.
|
|
87
92
|
|
|
88
|
-
|
|
93
|
+
A check prints the report and exits 0, including when you are signed out, offline, or the repository has never been scanned. It fails the process only when you ask it to.
|
|
89
94
|
|
|
90
95
|
### What it looks for
|
|
91
96
|
|
|
@@ -97,9 +102,9 @@ grum check --strict # like --ci, and also fail while a review is
|
|
|
97
102
|
| Radius | A radius off the scale |
|
|
98
103
|
| Buttons | A look the contract does not have, a look whose state changed, a missing state, a raw `<button>` outside the button component, or a variant the component lacks |
|
|
99
104
|
|
|
100
|
-
##
|
|
105
|
+
## Review one item yourself
|
|
101
106
|
|
|
102
|
-
The
|
|
107
|
+
The menu's check already offers this. To send one finding directly, use its key (`grum check --json` prints it):
|
|
103
108
|
|
|
104
109
|
```sh
|
|
105
110
|
grum request "color:raw:#3C3C3C" \
|
|
@@ -107,7 +112,7 @@ grum request "color:raw:#3C3C3C" \
|
|
|
107
112
|
--url http://localhost:3000
|
|
108
113
|
```
|
|
109
114
|
|
|
110
|
-
`--url` is the page where the element renders
|
|
115
|
+
`--url` is the page where the element renders, or an HTML file in the repo (`./index.html`) when there is no dev server. A page behind a login is captured through the Grum Chrome extension, in your own browser session. `--browser chrome` or `--browser safari` picks the browser. `--no-capture` sends the request with no picture.
|
|
111
116
|
|
|
112
117
|
```sh
|
|
113
118
|
grum capture reset
|
|
@@ -121,32 +126,7 @@ Clears the capture-browser sign-in saved for this repository.
|
|
|
121
126
|
grum contract
|
|
122
127
|
```
|
|
123
128
|
|
|
124
|
-
Prints the packet
|
|
125
|
-
|
|
126
|
-
## Cursor
|
|
127
|
-
|
|
128
|
-
```sh
|
|
129
|
-
grum init cursor
|
|
130
|
-
```
|
|
131
|
-
|
|
132
|
-
Merges into files that already exist. Entries Grum did not write are left as they are, and a second run changes nothing. It writes:
|
|
133
|
-
|
|
134
|
-
| File | What it does |
|
|
135
|
-
| ------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
136
|
-
| `.cursor/hooks.json` | After an edit, checks the block that changed. The stop hook sends the agent back while blocking drift stands, at most twice a conversation. The shell hook can refuse `git commit` and `git push`. Hooks read the cache and do not call the network. |
|
|
137
|
-
| `.cursor/mcp.json` | Four tools: `grum_contract`, `grum_check`, `grum_request_review`, `grum_review_status`. |
|
|
138
|
-
| `.cursor/rules/grum.mdc` | Tells the agent to read the contract before writing UI and to check before it stops. The contract itself stays in Grum, so this file does not go stale on every scan. |
|
|
139
|
-
| pre-commit | Adds `grum check --staged`. Husky's hook is committed with the repo. Git's own pre-commit hook is local and is not shared. A lefthook repo gets the snippet to paste. |
|
|
140
|
-
|
|
141
|
-
`.grum/` is added to `.gitignore` the first time Grum writes there. The cached contract (`.grum/contract.json`) stays on this computer.
|
|
142
|
-
|
|
143
|
-
Reload the Cursor window after init (or turn **grum** on under Settings, Tools and MCP) so the agent sees the tools. Until then it follows `.grum/contract.json`.
|
|
144
|
-
|
|
145
|
-
```sh
|
|
146
|
-
grum init cursor --remove # deletes exactly what init added
|
|
147
|
-
grum init cursor --force # replaces a rule file Grum did not write
|
|
148
|
-
grum init cursor --local-only # hooks and the rule, without a linked project
|
|
149
|
-
```
|
|
129
|
+
Prints the packet the Cursor agent reads before writing styles: tokens by category (with a separate dark value when there is one), button components, each look and the prop that selects it, and the repository's written rules about those buttons.
|
|
150
130
|
|
|
151
131
|
## Fail the check
|
|
152
132
|
|
|
@@ -182,7 +162,7 @@ Grum adds `.grum/` to `.gitignore` the first time it writes there, so `config.js
|
|
|
182
162
|
|
|
183
163
|
## Continuous integration
|
|
184
164
|
|
|
185
|
-
Sign in once
|
|
165
|
+
Sign in once from the menu, then copy the `token` field from the credentials file for this Grum. For [app.grum.so](https://app.grum.so) that file is:
|
|
186
166
|
|
|
187
167
|
```text
|
|
188
168
|
~/.config/grum/credentials/https_app_grum_so.json
|
|
@@ -202,16 +182,33 @@ Store it as a secret. Do not commit it. The token acts as you, in every workspac
|
|
|
202
182
|
|
|
203
183
|
## Commands
|
|
204
184
|
|
|
205
|
-
|
|
206
|
-
|
|
207
|
-
|
|
|
208
|
-
|
|
|
209
|
-
| `grum
|
|
210
|
-
| `grum
|
|
211
|
-
| `grum
|
|
212
|
-
| `grum
|
|
213
|
-
| `grum
|
|
214
|
-
| `grum
|
|
185
|
+
The menu covers check, setup, and sign-in. These are the same actions as flags, for scripts and CI.
|
|
186
|
+
|
|
187
|
+
| Command | What it does |
|
|
188
|
+
| --------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
189
|
+
| `grum` | The menu. Check, setup (including Cursor), or sign in. |
|
|
190
|
+
| `grum login` / `grum logout` | Sign this computer in to Grum, or out. |
|
|
191
|
+
| `grum setup [--root <dir>]` | Sign in, link this repository, and ask about Cursor and the pre-commit check. |
|
|
192
|
+
| `grum check [flags]` | Check the working tree. See the flags below. |
|
|
193
|
+
| `grum request <key> [--reason "..."] [--url <page>] [--browser chrome | safari] [--no-capture]` | Ask the owners to allow one drift item. |
|
|
194
|
+
| `grum capture reset` | Clear this repository's saved capture-browser sign-ins. |
|
|
195
|
+
| `grum contract` | Print the contract packet. |
|
|
196
|
+
| `grum init cursor [--remove] [--force] [--local-only] [--pre-commit]` | Write or remove the Cursor files without the menu. `--pre-commit` adds the commit check. `--no-pre-commit` removes it. |
|
|
197
|
+
|
|
198
|
+
```sh
|
|
199
|
+
grum check --staged # drift in the blocks staged for commit
|
|
200
|
+
grum check --files src/Hero.tsx # only these paths
|
|
201
|
+
grum check --json # project, cache time, known count, findings
|
|
202
|
+
grum check --no-review # print the report and do not ask
|
|
203
|
+
grum check --cursor # open the findings in Cursor
|
|
204
|
+
grum check --offline # the cached contract, no network
|
|
205
|
+
grum check --root apps/web # the app lives in a subdirectory
|
|
206
|
+
grum check --report # also post this run to Grum
|
|
207
|
+
grum check --ci # fail on open or rejected drift, and post the run
|
|
208
|
+
grum check --strict # like --ci, and also fail while a review is pending
|
|
209
|
+
```
|
|
210
|
+
|
|
211
|
+
`--ci` and `--report` show up on the Drift page under Recent checks, one latest run per branch. CI, JSON, staged, and agent runs never open the menu and never prompt.
|
|
215
212
|
|
|
216
213
|
`grum hook` and `grum mcp` are the entry points Cursor runs. You do not call them yourself.
|
|
217
214
|
|
package/brand.png
ADDED
|
Binary file
|
package/content.md5
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
|
|
1
|
+
1be6dc915c30d3e9e12a7d5232bfe860
|