@greenharness/greenrack-cli 0.0.0-reserved → 7.0.0

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.
Files changed (125) hide show
  1. package/README.md +334 -1
  2. package/agents/design-system-lookup.md +59 -0
  3. package/dist/bin.d.ts +3 -0
  4. package/dist/bin.d.ts.map +1 -0
  5. package/dist/bin.js +145 -0
  6. package/dist/bin.js.map +1 -0
  7. package/dist/catalog.d.ts +13 -0
  8. package/dist/catalog.d.ts.map +1 -0
  9. package/dist/catalog.js +67 -0
  10. package/dist/catalog.js.map +1 -0
  11. package/dist/commands/context.d.ts +17 -0
  12. package/dist/commands/context.d.ts.map +1 -0
  13. package/dist/commands/context.js +110 -0
  14. package/dist/commands/context.js.map +1 -0
  15. package/dist/commands/doctor.d.ts +75 -0
  16. package/dist/commands/doctor.d.ts.map +1 -0
  17. package/dist/commands/doctor.js +1008 -0
  18. package/dist/commands/doctor.js.map +1 -0
  19. package/dist/commands/hook.d.ts +10 -0
  20. package/dist/commands/hook.d.ts.map +1 -0
  21. package/dist/commands/hook.js +323 -0
  22. package/dist/commands/hook.js.map +1 -0
  23. package/dist/commands/list.d.ts +4 -0
  24. package/dist/commands/list.d.ts.map +1 -0
  25. package/dist/commands/list.js +59 -0
  26. package/dist/commands/list.js.map +1 -0
  27. package/dist/commands/lookup.d.ts +13 -0
  28. package/dist/commands/lookup.d.ts.map +1 -0
  29. package/dist/commands/lookup.js +66 -0
  30. package/dist/commands/lookup.js.map +1 -0
  31. package/dist/commands/manifest.d.ts +5 -0
  32. package/dist/commands/manifest.d.ts.map +1 -0
  33. package/dist/commands/manifest.js +33 -0
  34. package/dist/commands/manifest.js.map +1 -0
  35. package/dist/commands/mcp.d.ts +159 -0
  36. package/dist/commands/mcp.d.ts.map +1 -0
  37. package/dist/commands/mcp.js +235 -0
  38. package/dist/commands/mcp.js.map +1 -0
  39. package/dist/commands/mockup.d.ts +80 -0
  40. package/dist/commands/mockup.d.ts.map +1 -0
  41. package/dist/commands/mockup.js +714 -0
  42. package/dist/commands/mockup.js.map +1 -0
  43. package/dist/commands/skill.d.ts +15 -0
  44. package/dist/commands/skill.d.ts.map +1 -0
  45. package/dist/commands/skill.js +398 -0
  46. package/dist/commands/skill.js.map +1 -0
  47. package/dist/disambiguation.d.ts +24 -0
  48. package/dist/disambiguation.d.ts.map +1 -0
  49. package/dist/disambiguation.js +56 -0
  50. package/dist/disambiguation.js.map +1 -0
  51. package/dist/extension-pointer.d.ts +7 -0
  52. package/dist/extension-pointer.d.ts.map +1 -0
  53. package/dist/extension-pointer.js +30 -0
  54. package/dist/extension-pointer.js.map +1 -0
  55. package/dist/format.d.ts +19 -0
  56. package/dist/format.d.ts.map +1 -0
  57. package/dist/format.js +213 -0
  58. package/dist/format.js.map +1 -0
  59. package/dist/hook-script.d.ts +73 -0
  60. package/dist/hook-script.d.ts.map +1 -0
  61. package/dist/hook-script.js +165 -0
  62. package/dist/hook-script.js.map +1 -0
  63. package/dist/index.d.ts +7 -0
  64. package/dist/index.d.ts.map +1 -0
  65. package/dist/index.js +6 -0
  66. package/dist/index.js.map +1 -0
  67. package/dist/legacy-names.d.ts +26 -0
  68. package/dist/legacy-names.d.ts.map +1 -0
  69. package/dist/legacy-names.js +26 -0
  70. package/dist/legacy-names.js.map +1 -0
  71. package/dist/manifest.d.ts +51 -0
  72. package/dist/manifest.d.ts.map +1 -0
  73. package/dist/manifest.js +229 -0
  74. package/dist/manifest.js.map +1 -0
  75. package/dist/registry-types.d.ts +106 -0
  76. package/dist/registry-types.d.ts.map +1 -0
  77. package/dist/registry-types.js +2 -0
  78. package/dist/registry-types.js.map +1 -0
  79. package/dist/registry.d.ts +52 -0
  80. package/dist/registry.d.ts.map +1 -0
  81. package/dist/registry.js +95 -0
  82. package/dist/registry.js.map +1 -0
  83. package/dist/scan.d.ts +19 -0
  84. package/dist/scan.d.ts.map +1 -0
  85. package/dist/scan.js +29 -0
  86. package/dist/scan.js.map +1 -0
  87. package/dist/search.d.ts +16 -0
  88. package/dist/search.d.ts.map +1 -0
  89. package/dist/search.js +75 -0
  90. package/dist/search.js.map +1 -0
  91. package/dist/skill-template.d.ts +24 -0
  92. package/dist/skill-template.d.ts.map +1 -0
  93. package/dist/skill-template.js +140 -0
  94. package/dist/skill-template.js.map +1 -0
  95. package/greenharness.toml +38 -0
  96. package/package.json +76 -4
  97. package/registry.json +12893 -0
  98. package/skills/colors/LICENSE +21 -0
  99. package/skills/colors/NOTICE.md +36 -0
  100. package/skills/colors/SKILL.md +101 -0
  101. package/skills/colors/color-formats.md +90 -0
  102. package/skills/colors/color-usage.md +109 -0
  103. package/skills/colors/contrast.md +70 -0
  104. package/skills/colors/palette-generation.md +108 -0
  105. package/skills/colors/palette-structure.md +72 -0
  106. package/skills/colors/token-naming.md +99 -0
  107. package/skills/greenrack-mockup/SKILL.md +115 -0
  108. package/skills/typography/LICENSE +21 -0
  109. package/skills/typography/NOTICE.md +36 -0
  110. package/skills/typography/SKILL.md +171 -0
  111. package/skills/typography/choosing-fonts.md +53 -0
  112. package/skills/typography/css-cheat-sheet.md +67 -0
  113. package/skills/typography/details-and-accessibility.md +84 -0
  114. package/skills/typography/spacing-and-sizing.md +87 -0
  115. package/skills/typography/variable-fonts-and-opentype.md +100 -0
  116. package/skills/typography/wrapping-and-punctuation.md +23 -0
  117. package/skills/ui/LICENSE +21 -0
  118. package/skills/ui/NOTICE.md +38 -0
  119. package/skills/ui/SKILL.md +141 -0
  120. package/skills/ui/animations.md +170 -0
  121. package/skills/ui/enter-exit.md +157 -0
  122. package/skills/ui/icon-transitions.md +72 -0
  123. package/skills/ui/icons.md +105 -0
  124. package/skills/ui/performance.md +63 -0
  125. package/skills/ui/surfaces.md +166 -0
@@ -0,0 +1,714 @@
1
+ import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync, } from 'node:fs';
2
+ import { dirname, join, relative, resolve } from 'node:path';
3
+ import { describeDropped, GROUP_ALIASES, kebab, REFUSED_GROUPS, THEMABLE_GROUPS, validateTokens, } from '@greenharness/greenrack-tokens/theme';
4
+ import { lookup } from '../registry.js';
5
+ import { suggestions } from '../search.js';
6
+ import { lineOf } from '../scan.js';
7
+ import { MOCKUP_SUBCOMMANDS } from '../manifest.js';
8
+ import { SCOPES, uiVersionSkew } from './doctor.js';
9
+ /*
10
+ * greenrack mockup — token-seeded artboards, and the check that makes one a
11
+ * handoff contract.
12
+ *
13
+ * A mockup drawn outside the token system has to be TRANSLATED into the
14
+ * design system when it is implemented, and every translation drifts (the
15
+ * gate-board mockup of 2026-09 used 158 hex literals, 15 of them in the
16
+ * palette). `seed` writes an artboard whose only design vocabulary is the
17
+ * resolved token block, so the artboard is written in token names from the
18
+ * first line; `check` refuses an artboard that reaches past them, and refuses
19
+ * one that does not say which design-system component each control is;
20
+ * `canvas` puts the directions side by side on one page for the person to
21
+ * pick from, and builds it only from artboards that pass `check`.
22
+ *
23
+ * What binds when a direction is chosen: layout, hierarchy, states, the
24
+ * data-gr component map and the token names — sizes and border widths
25
+ * included (ADR-0027). What does not: positions (top, left, inset,
26
+ * transform), which are the sketch and are not checked.
27
+ */
28
+ export const TOKENS_START = '/* greenrack:tokens start */';
29
+ export const TOKENS_END = '/* greenrack:tokens end */';
30
+ /** The artboard size, on the root element and in the review canvas's frames. */
31
+ export const ARTBOARD_WIDTH = 1120;
32
+ export const ARTBOARD_HEIGHT = 840;
33
+ export const MOCKUP_THEMES = ['dark', 'light', 'high-contrast'];
34
+ // ---------------------------------------------------------------------------
35
+ // seed
36
+ /**
37
+ * The artboard skeleton: support.js verbatim, one <x-dc>, one
38
+ * <helmet><style>. Everything a
39
+ * finished artboard adds goes inside the same style block and the root div.
40
+ */
41
+ export function seedArtboard(registry, name, theme, overrides) {
42
+ const themeAttr = theme === 'dark' ? '' : ` data-theme="${theme}"`;
43
+ const tokens = registry.tokens.mockupCss.trimEnd();
44
+ return `<!doctype html>
45
+ <html${themeAttr}>
46
+ <head>
47
+ <meta charset="utf-8">
48
+ <script src="./support.js"></script>
49
+ </head>
50
+ <body>
51
+ <x-dc>
52
+ <helmet>
53
+ <style>
54
+ ${TOKENS_START}
55
+ ${tokens}
56
+ /* The design canvas size: the board's coordinate space, not a design token. */
57
+ :root { --gr-mockup-canvas-width: ${ARTBOARD_WIDTH}px; --gr-mockup-canvas-height: ${ARTBOARD_HEIGHT}px; }${overrides && overridesBlock(overrides) ? `\n${overridesBlock(overrides)}` : ''}
58
+ ${TOKENS_END}
59
+
60
+ /*
61
+ * ${name} — a greenrack mockup artboard. GENERATED by \`greenrack mockup seed\`.
62
+ *
63
+ * Every colour, spacing, radius, font, shadow and duration below is a
64
+ * var(--gr-*) from the block above — never a literal. Geometry (widths,
65
+ * heights, positions) is free. Every element a person can act on carries
66
+ * data-gr="<Component>" or data-gr="<Component>.<Part>" naming the
67
+ * @greenharness/greenrack-ui component that will implement it (greenrack list components).
68
+ * \`greenrack mockup check ${name}.dc.html\` enforces both.
69
+ */
70
+ body {
71
+ margin: 0;
72
+ background: var(--gr-color-bg);
73
+ color: var(--gr-color-text);
74
+ font-family: var(--gr-typography-font-family);
75
+ font-size: var(--gr-typography-font-size-md);
76
+ line-height: var(--gr-typography-line-height);
77
+ }
78
+ .artboard {
79
+ width: var(--gr-mockup-canvas-width);
80
+ height: var(--gr-mockup-canvas-height);
81
+ overflow: hidden;
82
+ padding: var(--gr-spacing-lg);
83
+ box-sizing: border-box;
84
+ }
85
+ </style>
86
+ </helmet>
87
+ <div class="artboard">
88
+ <!--
89
+ Vocabulary (delete this comment when the artboard is authored):
90
+ <div data-gr="PageShell"> … </div>
91
+ <button data-gr="Button variant=primary">Save</button>
92
+ <div data-gr="Tabs"> <div data-gr="Tabs.List"> <div data-gr="Tabs.Tab">…</div> </div> </div>
93
+ <div data-gr="Table"> … </div>
94
+ <span data-gr="Badge variant=success">Granted</span>
95
+ Props after the name are notes for the implementer, not checked.
96
+ -->
97
+ </div>
98
+ </x-dc>
99
+ </body>
100
+ </html>
101
+ `;
102
+ }
103
+ /**
104
+ * The CSS variable a token publishes: `--gr-<alias>-<kebab key>`, named by
105
+ * the module ThemeProvider and the registry build use, so it matches what
106
+ * registry.tokens.mockupCss declares.
107
+ */
108
+ export function tokenVariableName(group, key) {
109
+ return `--gr-${GROUP_ALIASES[group]}-${kebab(key)}`;
110
+ }
111
+ /** The declarations of one selector, group by group in the table's order. */
112
+ function overrideDeclarations({ tokens }) {
113
+ return THEMABLE_GROUPS.flatMap((group) => Object.entries(tokens[group] ?? {}).map(([key, value]) => `${tokenVariableName(group, key)}: ${value};`)).join(' ');
114
+ }
115
+ /** The override rules, one per theme selector so they win whatever the theme. */
116
+ function overridesBlock(overrides) {
117
+ const declarations = overrideDeclarations(overrides);
118
+ if (declarations === '')
119
+ return '';
120
+ const comment = `/* Theme overrides from ${overrides.file.replace(/\*\//g, '* /')}: the same JSON as ThemeProvider's tokens. */`;
121
+ return [
122
+ comment,
123
+ `:root { ${declarations} }`,
124
+ `:root[data-theme="light"] { ${declarations} }`,
125
+ `:root[data-theme="high-contrast"] { ${declarations} }`,
126
+ ].join('\n');
127
+ }
128
+ const isObject = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
129
+ /** Whether a parsed file is the `tokens` shape; otherwise it is the flat map of colours. */
130
+ function isTokensShape(parsed) {
131
+ return Object.entries(parsed).some(([key, value]) => THEMABLE_GROUPS.includes(key) ||
132
+ key in REFUSED_GROUPS ||
133
+ isObject(value));
134
+ }
135
+ /** Read and validate an overrides file; a usage error text when it is not acceptable. */
136
+ function readOverrides(cwd, file) {
137
+ const fail = (problem, dropped = []) => ({
138
+ error: `greenrack mockup seed: --overrides ${file}: ${problem}`,
139
+ problems: dropped.map(({ group, key, reason }) => ({ group, key, reason })),
140
+ });
141
+ let source;
142
+ try {
143
+ source = readFileSync(resolve(cwd, file), 'utf8');
144
+ }
145
+ catch {
146
+ return fail('cannot read the file');
147
+ }
148
+ let parsed;
149
+ try {
150
+ parsed = JSON.parse(source);
151
+ }
152
+ catch {
153
+ return fail('not valid JSON');
154
+ }
155
+ if (!isObject(parsed)) {
156
+ return fail('expected a JSON object: the tokens shape ({colors?, typography?, radii?, sizes?, …}) or a flat map of colour token keys to colours');
157
+ }
158
+ const { kept, dropped } = validateTokens(isTokensShape(parsed) ? parsed : { colors: parsed });
159
+ if (dropped.length > 0)
160
+ return fail(dropped.map(describeDropped).join('\n'), dropped);
161
+ return { overrides: { file, tokens: kept } };
162
+ }
163
+ /** `1 colors, 4 radii`: only the groups that have entries. */
164
+ function describeApplied({ tokens }) {
165
+ return THEMABLE_GROUPS.flatMap((group) => {
166
+ const count = Object.keys(tokens[group] ?? {}).length;
167
+ return count > 0 ? [`${group} ${count}`] : [];
168
+ }).join(', ');
169
+ }
170
+ export function runMockupSeed(registry, options = {}) {
171
+ const cwd = options.cwd ?? process.cwd();
172
+ const name = options.name ?? 'Main';
173
+ if (!/^[A-Za-z][A-Za-z0-9-]*$/.test(name)) {
174
+ return usage(`greenrack mockup seed: --name must be a bare file stem, got "${name}"`);
175
+ }
176
+ const theme = (options.theme ?? 'dark');
177
+ if (!MOCKUP_THEMES.includes(theme)) {
178
+ return usage(`greenrack mockup seed: --theme must be one of ${MOCKUP_THEMES.join(' | ')}, got "${theme}"`);
179
+ }
180
+ let overrides;
181
+ if (options.overrides !== undefined) {
182
+ const read = readOverrides(cwd, options.overrides);
183
+ if ('error' in read)
184
+ return usage(read.error, { problems: read.problems });
185
+ overrides = read.overrides;
186
+ }
187
+ const dir = options.out ?? join('docs', 'mockups', name.toLowerCase());
188
+ const path = join(dir, `${name}.dc.html`);
189
+ const abs = resolve(cwd, path);
190
+ if (existsSync(abs)) {
191
+ return {
192
+ text: `greenrack mockup seed: ${path} exists — pick another --name or --out, or delete it`,
193
+ data: { kind: 'exists', path },
194
+ exitCode: 1,
195
+ };
196
+ }
197
+ mkdirSync(resolve(cwd, dir), { recursive: true });
198
+ const partial = `${abs}.tmp`;
199
+ writeFileSync(partial, seedArtboard(registry, name, theme, overrides), 'utf8');
200
+ renameSync(partial, abs);
201
+ const summary = overrides ? describeApplied(overrides) : '';
202
+ const applied = overrides
203
+ ? summary === ''
204
+ ? ` with no overrides from ${overrides.file}`
205
+ : ` with overrides from ${overrides.file}: ${summary}`
206
+ : '';
207
+ return {
208
+ text: [
209
+ `Seeded ${path} (${theme})${applied}.`,
210
+ 'Author it with var(--gr-*) values and data-gr component names only,',
211
+ `then: greenrack mockup check ${path} (an unauthored seed fails on no-component-map alone)`,
212
+ ].join('\n'),
213
+ data: { ok: true, path, theme },
214
+ };
215
+ }
216
+ // ---------------------------------------------------------------------------
217
+ // check
218
+ /** CSS properties whose values are design tokens in this system. */
219
+ const SPACING_PROPS = /^(padding|margin|gap|row-gap|column-gap|inset|padding-[a-z-]+|margin-[a-z-]+)$/;
220
+ const RADIUS_PROPS = /^border(-[a-z]+-[a-z]+)?-radius$/;
221
+ const TYPE_PROPS = /^(font-size|font-weight|font-family|font)$/;
222
+ const SHADOW_PROPS = /^box-shadow$/;
223
+ const SIZE_PROPS = /^((min|max)-)?(width|height|block-size|inline-size)$|^flex-basis$/;
224
+ // border-width and every side/logical variant, the border* shorthands (their
225
+ // width), outline, outline-width and outline-offset. Not border-radius/color/style.
226
+ const BORDER_WIDTH_PROPS = /^(border(-(top|right|bottom|left|block|inline)(-(start|end))?)?(-width)?|outline(-width|-offset)?)$/;
227
+ const PX_LITERAL = /(?<![\w.-])-?(\d*\.?\d+)px\b/;
228
+ const MOTION_PROPS = /^(transition|transition-duration|transition-timing-function|animation|animation-duration|animation-timing-function)$/;
229
+ const COLOR_LITERAL = /#[0-9a-fA-F]{3,8}\b|\b(?:rgba?|hsla?)\(/g;
230
+ const LENGTH_LITERAL = /(?<![\w.-])(\d*\.?\d+)(px|rem|em|ms|s)\b/g;
231
+ const WEIGHT_LITERAL = /(?<![\w.-])([1-9]00)\b/;
232
+ const BREAKPOINT_QUERY = /@(?:media|container)[^{]*?\(\s*(?:min|max)-(?:width|height)\s*:\s*(\d+)px\s*\)/g;
233
+ /** Native controls — a greenrack component exists for each; an artboard names it. */
234
+ const NATIVE_CONTROLS = new Set(['button', 'input', 'select', 'textarea', 'a', 'table', 'dialog']);
235
+ const VOID_ELEMENTS = new Set([
236
+ 'area',
237
+ 'base',
238
+ 'br',
239
+ 'col',
240
+ 'embed',
241
+ 'hr',
242
+ 'img',
243
+ 'input',
244
+ 'link',
245
+ 'meta',
246
+ 'source',
247
+ 'track',
248
+ 'wbr',
249
+ ]);
250
+ function usage(text, extra = {}) {
251
+ return { text, data: { kind: 'usage-error', ...extra }, exitCode: 2 };
252
+ }
253
+ /** Blank out the token block so its literals are never scanned, keeping offsets. */
254
+ function maskTokenBlock(source) {
255
+ const start = source.indexOf(TOKENS_START);
256
+ if (start < 0)
257
+ return source;
258
+ const end = source.indexOf(TOKENS_END, start);
259
+ if (end < 0)
260
+ return source;
261
+ const stop = end + TOKENS_END.length;
262
+ return (source.slice(0, start) + source.slice(start, stop).replace(/[^\n]/g, ' ') + source.slice(stop));
263
+ }
264
+ /** Blank out comments and var(...) references, keeping offsets. */
265
+ function maskInert(css) {
266
+ return css
267
+ .replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '))
268
+ .replace(/var\([^)]*\)/g, (m) => ' '.repeat(m.length));
269
+ }
270
+ /** Every `prop: value` in a CSS text, with file offsets. Braces are ignored. */
271
+ function declarations(css, base) {
272
+ const out = [];
273
+ const re = /([a-zA-Z-][a-zA-Z0-9-]*)\s*:\s*([^;{}]+)/g;
274
+ let m;
275
+ while ((m = re.exec(css))) {
276
+ const prop = m[1].toLowerCase();
277
+ // `a:hover`, `@media (min-width: …)` and URLs are not declarations, and a
278
+ // vendor-prefixed property (-webkit-…) is skipped; a custom property
279
+ // (--x) is kept, so a raw value cannot hide behind a variable.
280
+ const vendor = prop.startsWith('-') && !prop.startsWith('--');
281
+ if (vendor || (m.index > 0 && /[(@:]/.test(css[m.index - 1] ?? '')))
282
+ continue;
283
+ out.push({ prop, value: m[2], at: base + m.index + m[0].indexOf(m[2]) });
284
+ }
285
+ return out;
286
+ }
287
+ function scanCss(file, source, css, base, findings) {
288
+ const inert = maskInert(css);
289
+ // Colors: a literal is never right, on any property.
290
+ for (const m of inert.matchAll(COLOR_LITERAL)) {
291
+ findings.push({
292
+ file,
293
+ line: lineOf(source, base + (m.index ?? 0)),
294
+ rule: 'raw-color',
295
+ message: `'${m[0].replace(/\($/, '')}' is a raw colour — use a var(--gr-color-*) from the token block`,
296
+ });
297
+ }
298
+ // Breakpoints: media queries cannot read a variable, so a literal is
299
+ // allowed — but only one from the scale.
300
+ const scale = breakpointScale();
301
+ for (const m of inert.matchAll(BREAKPOINT_QUERY)) {
302
+ if (!scale.has(Number(m[1]))) {
303
+ findings.push({
304
+ file,
305
+ line: lineOf(source, base + (m.index ?? 0)),
306
+ rule: 'raw-breakpoint',
307
+ message: `${m[1]}px is not a breakpoint — the scale is ${[...scale].join(' / ')}px`,
308
+ });
309
+ }
310
+ }
311
+ for (const { prop, value, at } of declarations(inert, base)) {
312
+ // A custom property defined outside the token block (which is masked) is
313
+ // an author's own measure: a raw length or duration there is the same raw
314
+ // value one var() away. Colours are already caught on every line above.
315
+ if (prop.startsWith('--')) {
316
+ const raw = value
317
+ .match(LENGTH_LITERAL)
318
+ ?.find((l) => !/^0(px|rem|em|ms|s)$/.test(l) && /(px|ms|s)$/.test(l));
319
+ if (raw) {
320
+ findings.push({
321
+ file,
322
+ line: lineOf(source, at),
323
+ rule: 'raw-length',
324
+ message: `${raw} in custom property \`${prop}\` is a raw value — define it from a token: \`${prop}: var(--gr-*)\``,
325
+ });
326
+ }
327
+ continue;
328
+ }
329
+ // Sizes and border widths: only px is raw; %, vh, fr, rem and keywords are
330
+ // relative and allowed. The seed sizes the root through the canvas
331
+ // variables in the token block, so no geometry is exempt.
332
+ const measure = SIZE_PROPS.test(prop)
333
+ ? '--gr-size-*'
334
+ : BORDER_WIDTH_PROPS.test(prop) && !RADIUS_PROPS.test(prop)
335
+ ? '--gr-border-*'
336
+ : null;
337
+ if (measure) {
338
+ const px = value.match(PX_LITERAL);
339
+ if (px && Number(px[1]) !== 0) {
340
+ findings.push({
341
+ file,
342
+ line: lineOf(source, at),
343
+ rule: 'raw-length',
344
+ message: `${px[0]} on \`${prop}\` is a raw ${measure === '--gr-size-*' ? 'size' : 'border width'} — use a var(${measure}) token`,
345
+ });
346
+ }
347
+ continue;
348
+ }
349
+ const hint = SPACING_PROPS.test(prop)
350
+ ? '--gr-spacing-*'
351
+ : RADIUS_PROPS.test(prop)
352
+ ? '--gr-radius-*'
353
+ : TYPE_PROPS.test(prop)
354
+ ? '--gr-typography-* / --gr-type-scale-*'
355
+ : SHADOW_PROPS.test(prop)
356
+ ? '--gr-shadow-*'
357
+ : MOTION_PROPS.test(prop)
358
+ ? '--gr-duration-* / --gr-easing-*'
359
+ : null;
360
+ if (!hint)
361
+ continue;
362
+ const hit = value.match(LENGTH_LITERAL)?.find((l) => !/^0(px|rem|em|ms|s)$/.test(l));
363
+ const weight = prop === 'font-weight' || prop === 'font' ? value.match(WEIGHT_LITERAL)?.[1] : null;
364
+ const literal = hit ?? weight;
365
+ if (literal) {
366
+ findings.push({
367
+ file,
368
+ line: lineOf(source, at),
369
+ rule: 'raw-length',
370
+ message: `${literal} on \`${prop}\` is a raw value — use a var(${hint}) token`,
371
+ });
372
+ }
373
+ }
374
+ }
375
+ let cachedScale = null;
376
+ function breakpointScale() {
377
+ return (cachedScale ?? (cachedScale = new Set([480, 640, 768, 1024, 1280])));
378
+ }
379
+ function resolveComponent(registry, spec) {
380
+ // "Button variant=primary" → Button; "Tabs.Tab" → Tabs + part Tab.
381
+ const head = spec.trim().split(/\s+/)[0] ?? '';
382
+ const [name, part] = head.split('.');
383
+ const hit = lookup(registry, name);
384
+ if (!hit || (hit.kind !== 'component' && hit.kind !== 'recipe'))
385
+ return `unknown component "${name}"`;
386
+ if (part && hit.kind === 'component') {
387
+ const parts = hit.entry.parts;
388
+ if (!parts)
389
+ return `${hit.key} has no parts — drop ".${part}"`;
390
+ if (!parts[part])
391
+ return `${hit.key} has no part "${part}" (${Object.keys(parts).join(', ')})`;
392
+ }
393
+ return null;
394
+ }
395
+ function scanMarkup(file, source, findings, registry) {
396
+ // The markup is what is left once <style> blocks are blanked.
397
+ const blank = (m) => m.replace(/[^\n]/g, ' ');
398
+ const html = source
399
+ .replace(/<style\b[\s\S]*?<\/style>/gi, blank)
400
+ .replace(/<!--[\s\S]*?-->/g, blank);
401
+ const styleBlocks = [...source.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)];
402
+ // Classes whose rules read like a control, so a styled div that uses one
403
+ // has to be named. A control in a canvas artboard is rarely a <button>: it
404
+ // is a div with a pointer cursor, a hover state, or the padded rounded
405
+ // filled look of a button/chip/row. The signature is the UNION over every
406
+ // rule that mentions the class — `.btn{padding;border-radius}` and
407
+ // `.btn.pri{background}` together make `btn` a control.
408
+ const traits = new Map();
409
+ const trait = (cls, t) => {
410
+ const set = traits.get(cls) ?? new Set();
411
+ set.add(t);
412
+ traits.set(cls, set);
413
+ };
414
+ for (const block of styleBlocks) {
415
+ const css = maskInert(maskTokenBlock(block[1]));
416
+ for (const rule of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
417
+ const [, selector, body] = rule;
418
+ const classes = [...selector.matchAll(/\.([A-Za-z_][\w-]*)/g)].map((m) => m[1]);
419
+ for (const cls of classes) {
420
+ if (/cursor\s*:\s*pointer/.test(body))
421
+ trait(cls, 'pointer');
422
+ if (/:(hover|active|focus)/.test(selector))
423
+ trait(cls, 'state');
424
+ if (/border-radius\s*:/.test(body))
425
+ trait(cls, 'radius');
426
+ if (/padding(-[a-z]+)?\s*:/.test(body))
427
+ trait(cls, 'padding');
428
+ if (/background(-color)?\s*:/.test(body))
429
+ trait(cls, 'fill');
430
+ }
431
+ }
432
+ }
433
+ const controlClasses = new Set([...traits]
434
+ .filter(([, t]) => t.has('pointer') ||
435
+ t.has('state') ||
436
+ (t.has('radius') && t.has('padding') && t.has('fill')))
437
+ .map(([cls]) => cls));
438
+ const stack = [];
439
+ let annotatedCount = 0;
440
+ const tagRe = /<\/?([a-zA-Z][\w-]*)([^>]*)>/g;
441
+ let m;
442
+ while ((m = tagRe.exec(html))) {
443
+ const [whole, rawTag, attrs] = m;
444
+ const tag = rawTag.toLowerCase();
445
+ if (whole.startsWith('</')) {
446
+ // Pop to the matching open tag; tolerate stray closes.
447
+ const i = stack.map((t) => t.tag).lastIndexOf(tag);
448
+ if (i >= 0)
449
+ stack.length = i;
450
+ continue;
451
+ }
452
+ const dataGr = attrs.match(/\bdata-gr\s*=\s*"([^"]*)"|\bdata-gr\s*=\s*'([^']*)'/);
453
+ const spec = dataGr ? (dataGr[1] ?? dataGr[2] ?? '') : null;
454
+ const line = lineOf(source, m.index);
455
+ let annotated = false;
456
+ if (spec !== null) {
457
+ annotatedCount++;
458
+ annotated = true;
459
+ const problem = resolveComponent(registry, spec);
460
+ if (problem) {
461
+ const head = spec.trim().split(/[\s.]/)[0] ?? '';
462
+ const near = suggestions(registry, head).slice(0, 3);
463
+ findings.push({
464
+ file,
465
+ line,
466
+ rule: 'unknown-component',
467
+ message: `data-gr="${spec}": ${problem}${near.length ? ` — did you mean ${near.join(', ')}?` : ''}`,
468
+ });
469
+ }
470
+ }
471
+ const classes = attrs.match(/\bclass\s*=\s*"([^"]*)"|\bclass\s*=\s*'([^']*)'/);
472
+ const classList = (classes?.[1] ?? classes?.[2] ?? '').split(/\s+/).filter(Boolean);
473
+ const inline = attrs.match(/\bstyle\s*=\s*"([^"]*)"|\bstyle\s*=\s*'([^']*)'/);
474
+ const inlineCss = inline?.[1] ?? inline?.[2] ?? '';
475
+ if (inlineCss) {
476
+ const at = m.index + whole.indexOf(inlineCss);
477
+ scanCss(file, source, inlineCss, at, findings);
478
+ }
479
+ // A styled control must name itself: a named parent never covers a child
480
+ // that draws like a control, or naming the list once would excuse every
481
+ // row. The parent covers only a bare native control inside it (the ×
482
+ // button of a Tag, the input of a Combobox).
483
+ const styledControl = /\b(role|tabindex)\s*=/.test(attrs) ||
484
+ /cursor\s*:\s*pointer/.test(inlineCss) ||
485
+ classList.some((c) => controlClasses.has(c));
486
+ const parent = stack[stack.length - 1];
487
+ const unnamed = !annotated && (styledControl || (NATIVE_CONTROLS.has(tag) && !parent?.annotated));
488
+ if (unnamed) {
489
+ findings.push({
490
+ file,
491
+ line,
492
+ rule: 'unannotated-control',
493
+ message: `<${tag}${classList.length ? ` class="${classList.join(' ')}"` : ''}> reads as a control but names no design-system component — add data-gr="<Component>" (greenrack list components)`,
494
+ });
495
+ }
496
+ const selfClosing = VOID_ELEMENTS.has(tag) || whole.endsWith('/>');
497
+ if (!selfClosing)
498
+ stack.push({ tag, annotated });
499
+ }
500
+ if (annotatedCount === 0) {
501
+ findings.push({
502
+ file,
503
+ line: 1,
504
+ rule: 'no-component-map',
505
+ message: 'no data-gr attribute anywhere — an artboard names the design-system component behind every control, or it cannot be implemented from',
506
+ });
507
+ }
508
+ }
509
+ /** Every finding for one artboard's HTML. Exported for the MCP tool and tests. */
510
+ export function checkArtboard(registry, file, source) {
511
+ const findings = [];
512
+ const masked = maskTokenBlock(source);
513
+ for (const block of masked.matchAll(/<style\b[^>]*>([\s\S]*?)<\/style>/gi)) {
514
+ const at = (block.index ?? 0) + block[0].indexOf(block[1]);
515
+ scanCss(file, source, block[1], at, findings);
516
+ }
517
+ scanMarkup(file, masked, findings, registry);
518
+ findings.sort((a, b) => a.line - b.line || a.rule.localeCompare(b.rule));
519
+ return findings;
520
+ }
521
+ export function runMockupCheck(registry, files, options = {}) {
522
+ if (files.length === 0)
523
+ return usage('greenrack mockup check: give at least one <file.dc.html>');
524
+ const cwd = options.cwd ?? process.cwd();
525
+ const all = [];
526
+ for (const file of files) {
527
+ let source;
528
+ try {
529
+ source = readFileSync(resolve(cwd, file), 'utf8');
530
+ }
531
+ catch {
532
+ return {
533
+ text: `greenrack mockup check: cannot read ${file}`,
534
+ data: { kind: 'not-found', file },
535
+ exitCode: 2,
536
+ };
537
+ }
538
+ all.push(...checkArtboard(registry, file, source));
539
+ }
540
+ const lines = all.map(findingLine);
541
+ const skew = uiVersionSkew(cwd, SCOPES);
542
+ const note = skew ? `\n${skewNote(skew, `mockup check ${files.join(' ')}`)}` : '';
543
+ if (all.length === 0) {
544
+ return {
545
+ text: `greenrack mockup check: ${files.length} artboard(s) speak tokens and name their components${note}`,
546
+ data: { ok: true, files, findings: [], ...(skew && { skew }) },
547
+ };
548
+ }
549
+ return {
550
+ text: `greenrack mockup check: ${all.length} finding(s)\n${lines.join('\n')}${note}`,
551
+ data: { ok: false, files, findings: all, ...(skew && { skew }) },
552
+ exitCode: 1,
553
+ };
554
+ }
555
+ const findingLine = (f) => `${f.file}:${f.line} ${f.rule}: ${f.message}`;
556
+ /**
557
+ * doctor's version-skew finding, said where it explains a finding: a checker
558
+ * older than the app reports a component it has not heard of as unknown. npx
559
+ * keeps a cached CLI that satisfies a range, so this is not hypothetical.
560
+ */
561
+ function skewNote(skew, command) {
562
+ return `note: ${skew.ui} is ${skew.installed}, but this checker knows ${skew.own} — a component newer than the checker reads as unknown. Run: npx -y ${skew.cli}@${skew.installed} ${command}`;
563
+ }
564
+ // ---------------------------------------------------------------------------
565
+ // canvas
566
+ const ARTBOARD_SUFFIX = '.dc.html';
567
+ /** The artboard's own canvas size, from the seeded custom properties. */
568
+ function artboardSize(html) {
569
+ const width = /--gr-mockup-canvas-width:\s*(\d+)px/.exec(html);
570
+ const height = /--gr-mockup-canvas-height:\s*(\d+)px/.exec(html);
571
+ return {
572
+ width: width ? Number(width[1]) : ARTBOARD_WIDTH,
573
+ height: height ? Number(height[1]) : ARTBOARD_HEIGHT,
574
+ };
575
+ }
576
+ const escapeHtml = (text) => text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
577
+ /**
578
+ * An artboard as the page inlines it: without the seed's relative support.js,
579
+ * which a srcdoc frame cannot load and the page does not need.
580
+ */
581
+ const inlineable = (html) => html.replace(/<script src="\.\/support\.js"><\/script>\n?/g, '');
582
+ /** `Tree-Phone.dc.html` is direction `Tree`; `Main` sorts first, then by name. */
583
+ function directions(artboards) {
584
+ const stem = (a) => a.file.split('/').pop().replace(ARTBOARD_SUFFIX, '');
585
+ const groups = new Map();
586
+ for (const artboard of artboards) {
587
+ const key = stem(artboard).split('-')[0];
588
+ groups.set(key, [...(groups.get(key) ?? []), artboard]);
589
+ }
590
+ const rank = (key) => (key === 'Main' ? '' : key);
591
+ return [...groups.entries()]
592
+ .sort(([a], [b]) => rank(a).localeCompare(rank(b)))
593
+ .map(([key, group]) => [key, group.sort((a, b) => stem(a).localeCompare(stem(b)))]);
594
+ }
595
+ /**
596
+ * The review page: every direction side by side, each artboard inlined by
597
+ * srcdoc so the page is one file (an Artifact needs no supporting files, and
598
+ * a local copy opens from disk). The frames are sandboxed: an artboard is
599
+ * untrusted HTML (the MCP tool takes it from the caller) and needs no script. Nothing is built while an artboard fails the
600
+ * check: the person picks from contracts, not from sketches that drift.
601
+ */
602
+ export function buildCanvas(registry, artboards, options) {
603
+ const findings = artboards.flatMap((a) => checkArtboard(registry, a.file, a.html));
604
+ if (findings.length > 0)
605
+ return { html: null, findings };
606
+ const title = escapeHtml(options.title ?? 'Mockup directions');
607
+ const sections = directions(artboards).map(([key, group], index) => {
608
+ const letter = String.fromCharCode(65 + (index % 26));
609
+ const figures = group.map((artboard) => {
610
+ const { width, height } = artboardSize(artboard.html);
611
+ const name = escapeHtml(artboard.file.split('/').pop());
612
+ return `<figure>
613
+ <div class="frame" style="aspect-ratio: ${width} / ${height}"><iframe title="${name}" width="${width}" height="${height}" data-width="${width}" style="transform: scale(0.5)" sandbox="" srcdoc="${escapeHtml(inlineable(artboard.html))}"></iframe></div>
614
+ <figcaption>${name} · ${width}×${height}</figcaption>
615
+ </figure>`;
616
+ });
617
+ return `<section>\n<h2>${letter} · ${escapeHtml(key)}</h2>\n<div class="grid">\n${figures.join('\n')}\n</div>\n</section>`;
618
+ });
619
+ const html = `<!doctype html>
620
+ <html lang="en">
621
+ <head>
622
+ <meta charset="utf-8">
623
+ <meta name="viewport" content="width=device-width, initial-scale=1">
624
+ <title>${title}</title>
625
+ <!-- GENERATED by greenrack mockup canvas: regenerate it, never edit it. -->
626
+ <style>
627
+ /* The page's own chrome, not a greenrack surface: self-contained, themed by system colours. */
628
+ :root { color-scheme: light dark; --gap: 16px; }
629
+ body { margin: 0; padding: var(--gap); background: Canvas; color: CanvasText; font: 14px/1.5 system-ui, sans-serif; }
630
+ h1 { font-size: 20px; margin: 0 0 4px; }
631
+ h2 { font-size: 14px; margin: 32px 0 8px; text-transform: uppercase; letter-spacing: 0.04em; }
632
+ p { margin: 0; opacity: 0.75; }
633
+ .grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(min(100%, 420px), 1fr)); gap: var(--gap); }
634
+ figure { margin: 0; min-width: 0; }
635
+ .frame { position: relative; width: 100%; overflow: hidden; border: 1px solid GrayText; border-radius: 8px; }
636
+ .frame iframe { position: absolute; inset: 0 auto auto 0; border: 0; transform-origin: 0 0; }
637
+ figcaption { margin-top: 4px; font-size: 12px; opacity: 0.75; }
638
+ </style>
639
+ </head>
640
+ <body>
641
+ <h1>${title}</h1>
642
+ <p>Pick one direction by its letter. Sizes, colours and the component map are the contract; positions are a sketch.</p>
643
+ ${sections.join('\n')}
644
+ <script>
645
+ // Scale each artboard to its frame's width; 0.5 stands until this runs.
646
+ const fit = () => document.querySelectorAll('.frame iframe').forEach((f) => {
647
+ f.style.transform = 'scale(' + f.parentElement.clientWidth / Number(f.dataset.width) + ')'
648
+ })
649
+ new ResizeObserver(fit).observe(document.body)
650
+ fit()
651
+ </script>
652
+ </body>
653
+ </html>
654
+ `;
655
+ return { html, findings: [] };
656
+ }
657
+ export function runMockupCanvas(registry, dir, options = {}) {
658
+ if (!dir)
659
+ return usage('greenrack mockup canvas: give the directory holding the *.dc.html artboards');
660
+ const cwd = options.cwd ?? process.cwd();
661
+ const abs = resolve(cwd, dir);
662
+ if (!existsSync(abs) || !statSync(abs).isDirectory()) {
663
+ return usage(`greenrack mockup canvas: ${dir} is not a directory`);
664
+ }
665
+ const files = readdirSync(abs)
666
+ .filter((name) => name.endsWith(ARTBOARD_SUFFIX))
667
+ .sort();
668
+ if (files.length === 0)
669
+ return usage(`greenrack mockup canvas: no *${ARTBOARD_SUFFIX} in ${dir}`);
670
+ const artboards = files.map((name) => ({
671
+ file: join(dir, name),
672
+ html: readFileSync(join(abs, name), 'utf8'),
673
+ }));
674
+ const title = options.title ?? `${abs.split('/').pop()} directions`;
675
+ const { html, findings } = buildCanvas(registry, artboards, { title });
676
+ const skew = uiVersionSkew(cwd, SCOPES);
677
+ const note = skew ? `\n${skewNote(skew, `mockup canvas ${dir}`)}` : '';
678
+ if (html === null) {
679
+ return {
680
+ text: `greenrack mockup canvas: ${findings.length} finding(s) — fix them, then build the page\n${findings.map(findingLine).join('\n')}${note}`,
681
+ data: { ok: false, findings, ...(skew && { skew }) },
682
+ exitCode: 1,
683
+ };
684
+ }
685
+ const out = options.out ?? join(dir, 'canvas.html');
686
+ mkdirSync(dirname(resolve(cwd, out)), { recursive: true });
687
+ writeFileSync(resolve(cwd, out), html, 'utf8');
688
+ return {
689
+ text: `greenrack mockup canvas: ${relative(cwd, resolve(cwd, out))} — ${files.length} artboard(s). Publish it as the Artifact, or open it locally.${note}`,
690
+ data: {
691
+ ok: true,
692
+ path: relative(cwd, resolve(cwd, out)),
693
+ artboards: files.length,
694
+ ...(skew && { skew }),
695
+ },
696
+ };
697
+ }
698
+ export { MOCKUP_SUBCOMMANDS };
699
+ export function runMockup(registry, sub, rest, options) {
700
+ if (sub === 'seed') {
701
+ if (rest.length > 0)
702
+ return usage('greenrack mockup seed takes flags only (--out, --name, --theme, --overrides)');
703
+ return runMockupSeed(registry, options);
704
+ }
705
+ if (sub === 'check')
706
+ return runMockupCheck(registry, rest, options);
707
+ if (sub === 'canvas') {
708
+ if (rest.length > 1)
709
+ return usage('greenrack mockup canvas takes one directory');
710
+ return runMockupCanvas(registry, rest[0], options);
711
+ }
712
+ return usage(`greenrack mockup: unknown subcommand "${sub ?? ''}" — expected ${MOCKUP_SUBCOMMANDS.join(' | ')}`);
713
+ }
714
+ //# sourceMappingURL=mockup.js.map