@whzxc/agent-design-gallery 0.14.0 → 0.15.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 (64) hide show
  1. package/README.md +26 -16
  2. package/package.json +1 -1
  3. package/public/access.css +15 -2
  4. package/public/app.js +708 -483
  5. package/public/arrangement-worker.js +7 -7
  6. package/public/arrangement.js +35 -30
  7. package/public/assets.js +60 -38
  8. package/public/auth.js +59 -4
  9. package/public/boards.js +124 -0
  10. package/public/comment-anchors.js +50 -0
  11. package/public/comments.css +400 -0
  12. package/public/comments.js +1106 -0
  13. package/public/context-menu.js +97 -0
  14. package/public/frame-identity.js +26 -2
  15. package/public/hub.css +25 -3
  16. package/public/hub.html +10 -2
  17. package/public/hub.js +127 -23
  18. package/public/icons.js +2 -0
  19. package/public/index.html +13 -9
  20. package/public/instance-actions.js +9 -2
  21. package/public/layout.js +156 -86
  22. package/public/selection.js +1 -1
  23. package/public/style.css +74 -152
  24. package/public/switcher.css +5 -4
  25. package/public/switcher.js +109 -34
  26. package/public/token-catalog.js +8 -3
  27. package/public/tokens.css +14 -1
  28. package/public/view-route.js +0 -1
  29. package/src/boards/board.mjs +30 -0
  30. package/src/boards/token-board.mjs +196 -0
  31. package/src/cli-output.mjs +8 -5
  32. package/src/cli.mjs +49 -29
  33. package/src/comments.mjs +293 -0
  34. package/src/http.mjs +2 -3
  35. package/src/hub/project-link.mjs +41 -0
  36. package/src/hub/registry.mjs +5 -0
  37. package/src/hub.mjs +14 -10
  38. package/src/link.mjs +13 -1
  39. package/src/server.mjs +57 -93
  40. package/src/service.mjs +46 -12
  41. package/src/toolkit/arch.mjs +3 -2
  42. package/src/toolkit/asset-rules.mjs +24 -1
  43. package/src/toolkit/build-worker.mjs +6 -2
  44. package/src/toolkit/build.mjs +4 -2
  45. package/src/toolkit/commands.mjs +12 -7
  46. package/{public/review.js → src/toolkit/diff-document.mjs} +137 -43
  47. package/src/toolkit/diff-inputs.mjs +66 -30
  48. package/src/toolkit/diff.mjs +181 -39
  49. package/src/toolkit/impact-selection.mjs +25 -10
  50. package/src/toolkit/impact.mjs +32 -12
  51. package/src/toolkit/move-pairing.mjs +140 -0
  52. package/src/toolkit/project-index.mjs +2 -2
  53. package/src/toolkit/results.mjs +1 -1
  54. package/src/toolkit/review-document.mjs +435 -0
  55. package/src/toolkit/review-groups.mjs +29 -0
  56. package/src/toolkit/review-observation.mjs +131 -0
  57. package/src/toolkit/review-sheet.mjs +117 -0
  58. package/src/toolkit/review-specimens.mjs +60 -0
  59. package/src/toolkit/review.mjs +140 -0
  60. package/src/toolkit/runtime.mjs +1 -1
  61. package/src/toolkit/theme.mjs +16 -0
  62. package/public/annotations.js +0 -816
  63. package/public/labels.js +0 -122
  64. package/src/annotations.mjs +0 -238
@@ -1,10 +1,15 @@
1
1
  import { icon } from './icons.js';
2
2
 
3
3
  const categories = [
4
- ['Colors', 'palette'], ['Typography', 'type'], ['Spacing & size', 'ruler'], ['Radii', 'corner-up-right'],
5
- ['Shadows', 'layers'], ['Motion', 'timer'], ['Other', 'list'],
4
+ ['Colors', 'palette', 'colour'], ['Typography', 'type', 'type'], ['Spacing & size', 'ruler', 'sizing'],
5
+ ['Radii', 'corner-up-right', 'shape'], ['Shadows', 'layers', 'elevation'], ['Motion', 'timer', 'motion'],
6
+ ['Other', 'list', null],
6
7
  ];
7
8
 
9
+ export function tokenBoardSection(category) {
10
+ return categories.find(([label]) => label === category)?.[2] ?? null;
11
+ }
12
+
8
13
  function resolveValue(name, values) {
9
14
  const seen = new Set();
10
15
  while (!seen.has(name)) {
@@ -90,7 +95,7 @@ function tokenName(name, onCopyError) {
90
95
  button.onclick = async () => {
91
96
  try {
92
97
  await navigator.clipboard.writeText(name);
93
- button.setAttribute('data-copied', '');
98
+ button.setAttribute('data-copied', 'true');
94
99
  button.setAttribute('aria-label', `Copied ${name}`);
95
100
  glyph.innerHTML = icon('check', 12);
96
101
  clearTimeout(timer);
package/public/tokens.css CHANGED
@@ -1,5 +1,6 @@
1
1
  /* Shared tokens for TSX design frames and the viewer. */
2
2
  :root {
3
+ /* Typography */
3
4
  --font-ui: -apple-system, BlinkMacSystemFont, "SF Pro Text", "PingFang SC", "Segoe UI", "Microsoft YaHei", Inter, "WenQuanYi Zen Hei", sans-serif;
4
5
  --font-mono: "SF Mono", ui-monospace, Menlo, Consolas, "JetBrains Mono", monospace;
5
6
  --text-title: 15px;
@@ -7,28 +8,36 @@
7
8
  --text-body: 13px;
8
9
  --text-meta: 12px;
9
10
  --text-caption: 11px;
11
+
12
+ /* Shape */
10
13
  --radius-dialog: 16px;
11
14
  --radius-panel: 14px;
12
15
  --radius-menu: 12px;
16
+ --radius-card: 12px;
13
17
  --radius-field: 9px;
14
18
  --radius-row: 8px;
15
19
  --radius-artboard: 6px;
16
20
  --radius-keycap: 6px;
21
+ --radius-pill: 999px;
22
+
23
+ /* Control sizing */
17
24
  --toolbar-height: 44px;
18
25
  --field-height: 32px;
19
26
  --row-height: 28px;
20
- --row-height-two-line: 44px;
21
27
  --menu-item-height: 30px;
22
28
  --menu-label-height: 24px;
23
29
  --control-size: 32px;
24
30
  --keycap-size: 22px;
25
31
 
32
+ /* Surfaces and borders */
26
33
  --canvas: #ecece9;
27
34
  --dot: #d2d2ce;
28
35
  --surface: #ffffff;
29
36
  --surface-section: #f5f5f3;
30
37
  --surface-sunken: #f1f1ee;
31
38
  --border: #e2e2de;
39
+
40
+ /* Text and accents */
32
41
  --text: #1c1c1a;
33
42
  --text-secondary: #5b5b57;
34
43
  --text-tertiary: #7c7c77;
@@ -37,6 +46,9 @@
37
46
  --danger: #c2453b;
38
47
  --tooltip: #1c1c1a;
39
48
  --on-tooltip: #ffffff;
49
+
50
+ /* Elevation */
51
+ --shadow-comment-pin: 0 2px 7px rgb(0 0 0 / 36%);
40
52
  --shadow-float: 0 1px 2px rgb(0 0 0 / 6%), 0 8px 24px rgb(0 0 0 / 8%);
41
53
  --shadow-menu: 0 2px 4px rgb(0 0 0 / 6%), 0 12px 32px rgb(0 0 0 / 14%);
42
54
  }
@@ -56,6 +68,7 @@
56
68
  --danger: #f08b80;
57
69
  --tooltip: #efefed;
58
70
  --on-tooltip: #1c1c1a;
71
+ --shadow-comment-pin: 0 2px 8px rgb(0 0 0 / 55%);
59
72
  --shadow-float: 0 1px 2px rgb(0 0 0 / 40%), 0 8px 24px rgb(0 0 0 / 45%);
60
73
  --shadow-menu: 0 2px 4px rgb(0 0 0 / 40%), 0 12px 32px rgb(0 0 0 / 55%);
61
74
  }
@@ -43,7 +43,6 @@ export function viewURL(base, scope, target = {}, { isolated = false, onlyFrame
43
43
  const url = new URL(base);
44
44
  url.pathname = viewerBase(url.pathname);
45
45
  for (const key of locatorKeys) url.searchParams.delete(key);
46
- if (scope === 'review') return url;
47
46
  const { path, group, form, element } = target;
48
47
  if (onlyFrame) {
49
48
  url.searchParams.set('asset', path);
@@ -0,0 +1,30 @@
1
+ import { escape } from '../toolkit/html.mjs';
2
+
3
+ export const boardWidth = 1680;
4
+ export const specimenWidth = 1184;
5
+ export const boardCss = `
6
+ [data-adg-board]{--adg-surface:var(--surface,#fff);--adg-canvas:var(--canvas,#f2f2f0);--adg-text:var(--text,#202020);--adg-muted:var(--text-tertiary,var(--text-secondary,#737373));--adg-border:var(--border,#dededb);box-sizing:border-box;width:1680px;padding:64px 80px 80px;background:var(--adg-surface);color:var(--adg-text);font:16px/normal var(--font-ui,system-ui,sans-serif)}
7
+ [data-adg-board] *,[data-adg-board] *::before,[data-adg-board] *::after{box-sizing:border-box}
8
+ [data-adg-header]{display:grid;grid-template-columns:1fr 440px;align-items:end;gap:64px;padding-bottom:56px}
9
+ [data-adg-header] h1{margin:16px 0 0;font-size:48px;line-height:56px;font-weight:600;letter-spacing:-.02em}
10
+ [data-adg-eyebrow]{display:flex;align-items:center;gap:12px;margin:0;font-size:var(--text-caption,11px);font-weight:600;letter-spacing:.16em;text-transform:uppercase;color:var(--adg-muted)}
11
+ [data-adg-number]{display:grid;place-items:center;min-width:28px;height:28px;padding:0 6px;border-radius:var(--radius-pill,999px);background:var(--action,var(--adg-text));color:var(--on-action,var(--surface,#fff));font-family:var(--font-mono,monospace);letter-spacing:0}
12
+ [data-adg-counts]{margin:0;font-size:var(--text-body,var(--text-small,13px));line-height:1.6;color:var(--text-secondary,#666)}
13
+ [data-adg-section]{display:grid;grid-template-columns:280px minmax(0,1fr);gap:56px;border-top:1px solid var(--adg-border);padding:48px 0}
14
+ [data-adg-section-label] h2{margin:0;font-size:22px;line-height:28px;font-weight:600;letter-spacing:-.01em;overflow-wrap:anywhere}
15
+ [data-adg-source]{display:flex;align-items:flex-start;gap:6px;margin-top:20px;color:var(--adg-muted);font:var(--text-caption,11px)/1.6 var(--font-mono,monospace);overflow-wrap:anywhere}
16
+ [data-adg-source] svg{flex-shrink:0;margin-top:2px}
17
+ [data-adg-section-content]{min-width:0}
18
+ [data-adg-specimens]{display:grid;grid-template-columns:repeat(12,minmax(0,1fr));gap:32px 24px;align-items:start}
19
+ [data-adg-specimens]>figure{margin:0;min-width:0;display:flex;flex-direction:column;gap:12px;grid-column:span var(--adg-span,12)}
20
+ [data-adg-well]{display:flex;align-items:center;justify-content:center;min-height:96px;padding:32px 24px;border-radius:var(--radius-card,var(--radius-menu,12px));background:var(--adg-canvas);overflow:hidden}
21
+ [data-adg-well]>[data-adg-frame]{flex-shrink:0}
22
+ [data-adg-specimens] figcaption{display:flex;flex-direction:column;gap:2px;font:var(--text-meta,12px)/17px var(--font-mono,monospace);overflow-wrap:anywhere}
23
+ [data-adg-specimens] figcaption small{font:var(--text-meta,12px)/17px var(--font-ui,system-ui,sans-serif);color:var(--adg-muted)}
24
+ `;
25
+ export function boardHeader({title, projectName, layer, number=1, sourceCount, frameCount, countLabel='frames'}) {
26
+ return `<header data-adg-header><div><p data-adg-eyebrow><span data-adg-number>${String(number).padStart(2,'0')}</span>${escape(projectName)} · ${escape(layer)}</p><h1>${escape(title)}</h1></div><p data-adg-counts>${sourceCount} ${sourceCount === 1 ? 'source' : 'sources'} · ${frameCount} ${countLabel}</p></header>`;
27
+ }
28
+ export function sectionMarkup({title, source, content}) {
29
+ return `<section data-adg-section="${escape(source)}"><div data-adg-section-label><h2>${escape(title)}</h2><div data-adg-source><svg width="12" height="12" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8zM14 2v6h6M9 13l-2 2 2 2m6-4 2 2-2 2"/></svg><span>${escape(source)}</span></div></div><div data-adg-section-content>${content}</div></section>`;
30
+ }
@@ -0,0 +1,196 @@
1
+ import { parseTokens, themeCss } from '../toolkit/tokens.mjs';
2
+ import { escape } from '../toolkit/html.mjs';
3
+ import { boardCss, boardHeader, sectionMarkup, boardWidth, specimenWidth } from './board.mjs';
4
+
5
+ const sizeTrackWidth = (specimenWidth - 32) / 2;
6
+
7
+ const tokenStyles = `
8
+ [data-adg-token-groups]{display:flex;flex-direction:column;gap:40px}
9
+ [data-adg-token-group]>h3{margin:0 0 16px;font-size:var(--text-body,13px);line-height:18px;font-weight:600}
10
+ [data-adg-token-grid]{display:grid;grid-template-columns:repeat(7,minmax(0,1fr));gap:32px 24px;align-items:start}
11
+ [data-adg-token]{min-width:0;margin:0}
12
+ [data-adg-token] code{display:block;font:var(--text-meta,12px)/17px var(--font-mono,ui-monospace,monospace);overflow-wrap:anywhere}
13
+ [data-adg-token] small{display:block;margin-top:2px;color:var(--text-tertiary,#777);font:var(--text-caption,11px)/16px var(--font-mono,ui-monospace,monospace);overflow-wrap:anywhere}
14
+ [data-adg-token-swatch]{display:flex;height:72px;margin-bottom:8px;overflow:hidden;border:1px solid var(--border,#deded9);border-radius:var(--radius-tile,var(--radius-row,8px))}
15
+ [data-adg-token-swatch]>span{flex:1;min-width:0}
16
+ [data-adg-type-scale]{display:flex;flex-direction:column}
17
+ [data-adg-type-row]{display:grid;grid-template-columns:160px minmax(0,1fr) 160px;align-items:baseline;gap:24px;padding:16px 0;border-bottom:1px solid var(--border,#deded9)}
18
+ [data-adg-type-row]>small{text-align:right}
19
+ [data-adg-family-grid]{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:24px}
20
+ [data-adg-family]{padding:16px 20px;border-radius:var(--radius-card,var(--radius-menu,12px));background:var(--canvas,#f0f0ee)}
21
+ [data-adg-family-sample]{margin-bottom:8px;font-size:18px;line-height:26px;overflow-wrap:anywhere}
22
+ [data-adg-shape-grid]{display:grid;grid-template-columns:repeat(auto-fit,minmax(88px,1fr));gap:24px 16px}
23
+ [data-adg-radius]{height:88px;width:88px;margin:0 auto 12px;border:1px solid var(--border-strong,var(--border,#ccc));background:var(--surface-subtle,var(--surface-section,#f5f5f2))}
24
+ [data-adg-shape-grid] [data-adg-token]{text-align:center}
25
+ [data-adg-shadow-grid]{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:32px;padding:40px;border-radius:var(--radius-card,var(--radius-menu,12px));background:var(--canvas,#f0f0ee)}
26
+ [data-adg-shadow]{height:120px;margin-bottom:16px;border-radius:var(--radius-card,var(--radius-menu,12px));background:var(--surface,#fff)}
27
+ [data-adg-size-list]{display:grid;grid-template-columns:repeat(2,minmax(0,1fr));gap:28px 32px;align-items:start}
28
+ [data-adg-size-group]{--adg-size-maximum:var(--adg-size-maximum-light);--adg-size-scale:calc(${sizeTrackWidth}px / var(--adg-size-maximum))}
29
+ [data-adg-size-track]{height:16px;margin-bottom:10px;background:var(--canvas,#f0f0ee)}
30
+ [data-adg-size]{--adg-size-length:var(--adg-size-length-light);width:calc(var(--adg-size-length) * var(--adg-size-scale));height:100%;background:var(--action,var(--accent,#333))}
31
+ :where([data-theme="dark"]) [data-adg-size-group],[data-adg-board][data-theme="dark"] [data-adg-size-group]{--adg-size-maximum:var(--adg-size-maximum-dark)}
32
+ :where([data-theme="dark"]) [data-adg-size],[data-adg-board][data-theme="dark"] [data-adg-size]{--adg-size-length:var(--adg-size-length-dark)}
33
+ [data-adg-size-scale]{font-size:clamp(0px,calc((1 - var(--adg-size-scale)) * 100000px),var(--text-body,13px));font-weight:400;counter-reset:adg-size-scale round(calc(var(--adg-size-scale) * 100))}
34
+ [data-adg-size-scale]::after{content:" · " counter(adg-size-scale) "%"}
35
+ [data-adg-motion-grid]{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:32px 24px;align-items:start}
36
+ [data-adg-easing]{display:block;width:100%;height:128px;margin-bottom:12px;border-radius:var(--radius-card,var(--radius-menu,12px));background:var(--canvas,#f0f0ee);color:var(--text,#20201e)}
37
+ [data-adg-duration-track]{height:12px;margin:24px 0 20px;border-radius:var(--radius-keycap,6px);background:var(--canvas,#f0f0ee);overflow:hidden}
38
+ [data-adg-duration]{height:100%;min-width:2px;border-radius:var(--radius-keycap,6px);background:var(--action,var(--accent,#333))}
39
+ [data-adg-type-extras]{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:20px 24px}
40
+ `;
41
+
42
+ function tokenHeadings(css) {
43
+ const root = /:root\s*\{([\s\S]*?)\}/.exec(css)?.[1] ?? '';
44
+ const headings = new Map();
45
+ let heading;
46
+ for (const line of root.split('\n')) {
47
+ const comment = /^\s*\/\*\s*(.*?)\s*\*\/\s*$/.exec(line);
48
+ if (comment) { heading = comment[1]; continue; }
49
+ const token = /^\s*(--[\w-]+)\s*:/.exec(line);
50
+ if (token && heading) headings.set(token[1], heading);
51
+ }
52
+ return headings;
53
+ }
54
+
55
+ function tokenGroups(headings, names) {
56
+ const groups = new Map();
57
+ for (const name of names) {
58
+ const title = headings.get(name) ?? name.slice(2).split('-')[0];
59
+ if (!groups.has(title)) groups.set(title, []);
60
+ groups.get(title).push(name);
61
+ }
62
+ return groups;
63
+ }
64
+
65
+ function resolvedValue(name, values, seen = new Set()) {
66
+ if (seen.has(name)) return values.get(name) ?? '';
67
+ const visited = new Set([...seen, name]);
68
+ return (values.get(name) ?? '').replace(/var\(\s*(--[\w-]+)\s*(?:,\s*([^()]+))?\)/g,
69
+ (match, reference, fallback) => values.has(reference) ? resolvedValue(reference, values, visited) : fallback ?? match);
70
+ }
71
+
72
+ function caption(name, light, dark) {
73
+ return `<code>${escape(name)}</code><small>Light: ${escape(light)}</small>${light !== dark ? `<small>Dark: ${escape(dark)}</small>` : ''}`;
74
+ }
75
+
76
+ function sizeLength(value) {
77
+ const match = /^(-?(?:\d+\.?\d*|\.\d+))(px|rem|em|vh|vw|%)?$/.exec(value);
78
+ if (!match || (!match[2] && Number(match[1]) !== 0)) return null;
79
+ const number = Math.max(0, Number(match[1]));
80
+ if (match[2] === '%') return `${number / 100 * sizeTrackWidth}px`;
81
+ if (match[2] === 'em') return `${number * 16}px`;
82
+ return `${number}${match[2] ?? 'px'}`;
83
+ }
84
+
85
+ function tokenCategory(name, value, colours) {
86
+ if (colours.has(name)) return 'colour';
87
+ if (/^--(?:font-size|text)-/.test(name) && /^[-.\d]+(?:px|rem|em)$/.test(value)) return 'type';
88
+ if (/^--(?:font|family)-/.test(name) && !/^--font-(?:size|weight|stretch|style|tracking|line)/.test(name)) return 'family';
89
+ if (/^--(?:radius|round)-/.test(name)) return 'radius';
90
+ if (/shadow/.test(name)) return 'shadow';
91
+ if (/^(?:cubic-bezier\(|steps\(|linear\(|ease(?:-in|-out|-in-out)?$|linear$)/.test(value)) return 'easing';
92
+ if (/^[\d.]+m?s$/.test(value)) return 'duration';
93
+ if (/^--(?:line|weight|tracking|font-weight|font-line|letter-spacing)/.test(name)) return 'type-extra';
94
+ return 'size';
95
+ }
96
+
97
+ function easingCurve(value) {
98
+ const points = /^cubic-bezier\(\s*([\d.+-]+)\s*,\s*([\d.+-]+)\s*,\s*([\d.+-]+)\s*,\s*([\d.+-]+)\s*\)$/.exec(value);
99
+ const presets = { ease: [.25,.1,.25,1], 'ease-in': [.42,0,1,1], 'ease-out': [0,0,.58,1], 'ease-in-out': [.42,0,.58,1] };
100
+ const p = points ? points.slice(1).map(Number) : presets[value];
101
+ let curve = 'M16 112 L112 16';
102
+ if (p) curve = `M16 112 C${16 + p[0] * 96} ${112 - p[1] * 96} ${16 + p[2] * 96} ${112 - p[3] * 96} 112 16`;
103
+ const steps = /^steps\(\s*(\d+)(?:\s*,\s*(start|end|jump-start|jump-end))?\s*\)$/.exec(value);
104
+ if (steps) {
105
+ const count = Math.min(100, Number(steps[1]));
106
+ const start = steps[2] === 'start' || steps[2] === 'jump-start';
107
+ curve = `M16 ${start ? 112 - 96 / count : 112}`;
108
+ for (let i = 1; i <= count; i++) curve += ` H${16 + i * 96 / count} V${112 - Math.min(count, i + (start ? 1 : 0)) * 96 / count}`;
109
+ }
110
+ return `<svg data-adg-easing viewBox="0 0 128 128" role="img" aria-label="${escape(value)}"><path d="M16 16 V112 H112" fill="none" stroke="currentColor" opacity=".18"/><path d="${curve}" fill="none" stroke="currentColor" stroke-width="2.5"/></svg>`;
111
+ }
112
+
113
+ export function tokenBoard(source, css, { projectName = 'Design library' } = {}) {
114
+ const tokens = parseTokens(css);
115
+ const darkValues = new Map([...tokens.light, ...tokens.dark]);
116
+ const themes = themeCss(tokens);
117
+ const colours = new Set([...tokens.light.keys()].filter(name => themes.includes(`--color-${name.slice(2)}:var(`)));
118
+ const categories = new Map();
119
+ for (const [name, value] of tokens.light) {
120
+ const category = tokenCategory(name, value, colours);
121
+ if (!categories.has(category)) categories.set(category, []);
122
+ categories.get(category).push(name);
123
+ }
124
+ const light = name => resolvedValue(name, tokens.light);
125
+ const dark = name => resolvedValue(name, darkValues);
126
+ const headings = tokenHeadings(css);
127
+ const groups = (names, render) => `<div data-adg-token-groups>${[...tokenGroups(headings, names)].map(([title, group]) =>
128
+ `<div data-adg-token-group><h3>${escape(title)}</h3>${render(group)}</div>`).join('')}</div>`;
129
+ const article = (name, content, attrs = '') => `<article data-adg-token data-specimen="${escape(`${source}#${name}`)}"${attrs}>${content}</article>`;
130
+ const label = name => caption(name, tokens.light.get(name), tokens.dark.get(name) ?? tokens.light.get(name));
131
+ const section = (title, content) => sectionMarkup({ title, source, content }).replace(
132
+ `data-adg-section="${escape(source)}"`, `data-adg-section="${escape(`${source}#${title.toLowerCase()}`)}"`);
133
+ const sections = [];
134
+ if (categories.has('colour')) {
135
+ sections.push(section('Colour', groups(categories.get('colour'), names => `<div data-adg-token-grid>${names.map(name => article(name,
136
+ `<div data-adg-token-swatch><span style="background:${escape(light(name))}"></span><span style="background:${escape(dark(name))}"></span></div>${label(name)}`)).join('')}</div>`)));
137
+ }
138
+ if (categories.has('type') || categories.has('family') || categories.has('type-extra')) {
139
+ const sizeRow = name => {
140
+ const role = name.replace(/^--(?:font-size|text)-/, '');
141
+ const line = [`--line-${role}`, `--line-height-${role}`, `--font-line-${role}`].find(key => tokens.light.has(key));
142
+ const weight = [`--weight-${role}`, `--font-weight-${role}`].find(key => tokens.light.has(key));
143
+ const style = `font-size:var(${name});line-height:${line ? `var(${line})` : '1.4'};font-weight:${weight ? `var(${weight})` : '400'}`;
144
+ const metrics = [name, line, weight].filter(Boolean).map(key => key === name ? escape(tokens.light.get(key)) : `<span data-specimen="${escape(`${source}#${key}`)}">${escape(tokens.light.get(key))}</span>`).join(' / ');
145
+ return article(name, `<code>${escape(name)}</code><span style="${escape(style)}">The quick brown fox</span><small>${metrics}</small>`, ' data-adg-type-row');
146
+ };
147
+ const paired = new Set((categories.get('type') ?? []).flatMap(name => {
148
+ const role = name.replace(/^--(?:font-size|text)-/, '');
149
+ return [`--line-${role}`, `--line-height-${role}`, `--font-line-${role}`, `--weight-${role}`, `--font-weight-${role}`];
150
+ }));
151
+ const extras = (categories.get('type-extra') ?? []).filter(name => !paired.has(name));
152
+ const names = [...tokens.light.keys()].filter(name => ['type', 'family'].includes(tokenCategory(name, tokens.light.get(name), colours)) || extras.includes(name));
153
+ sections.push(section('Type', groups(names, group => {
154
+ const sizes = group.filter(name => categories.get('type')?.includes(name)).map(sizeRow).join('');
155
+ const families = group.filter(name => categories.get('family')?.includes(name)).map(name => article(name,
156
+ `<div data-adg-family-sample style="font-family:var(${escape(name)})">Aa Bb 0123</div>${label(name)}`, ' data-adg-family')).join('');
157
+ const remaining = group.filter(name => extras.includes(name)).map(name => article(name, label(name))).join('');
158
+ return `${sizes ? `<div data-adg-type-scale>${sizes}</div>` : ''}${families ? `<div data-adg-family-grid>${families}</div>` : ''}${remaining ? `<div data-adg-type-extras>${remaining}</div>` : ''}`;
159
+ })));
160
+ }
161
+ if (categories.has('radius')) sections.push(section('Shape', groups(categories.get('radius'), names => `<div data-adg-shape-grid>${names.map(name => article(name, `<div data-adg-radius style="border-radius:var(${escape(name)})"></div>${label(name)}`)).join('')}</div>`)));
162
+ if (categories.has('shadow')) sections.push(section('Elevation', groups(categories.get('shadow'), names => `<div data-adg-shadow-grid>${names.map(name => article(name, `<div data-adg-shadow style="--hub-color:var(--accent,var(--text,#333));box-shadow:var(${escape(name)})"></div>${label(name)}`)).join('')}</div>`)));
163
+ if (categories.has('size')) {
164
+ const sizeGroups = [...tokenGroups(headings, categories.get('size'))].map(([title, names]) => {
165
+ const lengths = names.map(name => ({ name, light: sizeLength(light(name)), dark: sizeLength(dark(name)) }));
166
+ const maximum = (theme) => `max(${sizeTrackWidth}px,${lengths.map(length => length[theme]).filter(Boolean).join(',') || '0px'})`;
167
+ const scale = `--adg-size-maximum-light:${maximum('light')};--adg-size-maximum-dark:${maximum('dark')}`;
168
+ const bars = lengths.map(length => {
169
+ const preview = length.light === null ? '' : `<div data-adg-size-track><div data-adg-size style="--adg-size-length-light:${length.light};--adg-size-length-dark:${length.dark ?? length.light}"></div></div>`;
170
+ return article(length.name, preview + label(length.name));
171
+ }).join('');
172
+ return `<div data-adg-token-group data-adg-size-group style="${escape(scale)}"><h3>${escape(title)}<span data-adg-size-scale></span></h3><div data-adg-size-list>${bars}</div></div>`;
173
+ }).join('');
174
+ sections.push(section('Sizing', `<div data-adg-token-groups>${sizeGroups}</div>`));
175
+ }
176
+ if (categories.has('easing') || categories.has('duration')) {
177
+ const milliseconds = name => parseFloat(light(name)) * (light(name).endsWith('ms') ? 1 : 1000);
178
+ const names = [...tokens.light.keys()].filter(name => categories.get('easing')?.includes(name) || categories.get('duration')?.includes(name));
179
+ sections.push(section('Motion', groups(names, group => {
180
+ const maximum = Math.max(1, ...group.filter(name => categories.get('duration')?.includes(name)).map(milliseconds));
181
+ return `<div data-adg-motion-grid>${group.map(name => article(name, categories.get('easing')?.includes(name)
182
+ ? easingCurve(light(name)) + label(name)
183
+ : `<div data-adg-duration-track><div data-adg-duration style="width:${milliseconds(name) / maximum * 100}%"></div></div>${label(name)}`)).join('')}</div>`;
184
+ })));
185
+ }
186
+ const body = `<main data-adg-board>${boardHeader({ title: 'Tokens', projectName, layer: 'Tokens', number: 1, sourceCount: 1, frameCount: tokens.light.size, countLabel: 'tokens' })}${sections.join('')}</main>`;
187
+ // Scope project tokens to the board so a DOM overlay never changes viewer chrome.
188
+ const declarations = values => [...values].map(([name, value]) => `${name}:${value};`).join('\n');
189
+ const scopedTokens = `[data-adg-board]{${declarations(tokens.light)}}
190
+ :where([data-theme="dark"]) [data-adg-board], [data-adg-board][data-theme="dark"]{${declarations(tokens.dark)}}`;
191
+ return {
192
+ key: source, source, name: 'Tokens', layer: 'Tokens', kind: 'board',
193
+ width: boardWidth, height: null, sourceCount: 1, frameCount: tokens.light.size,
194
+ body, css: `${scopedTokens}\n${boardCss}\n${tokenStyles}`,
195
+ };
196
+ }
@@ -5,7 +5,7 @@ import { AsyncLocalStorage } from 'node:async_hooks';
5
5
  /** @typedef {{argv: string[], reason: string}} NextAction */
6
6
  /** @typedef {{code: string, message: string, next: NextAction[]}} Diagnostic */
7
7
  /** @typedef {keyof typeof errorCatalog} ErrorCode */
8
- /** @typedef {{schemaVersion: 1, command: string, ok: boolean, data: unknown, warnings: Diagnostic[], error: Diagnostic | null}} Envelope */
8
+ /** @typedef {{schemaVersion: 2, command: string, ok: boolean, data: unknown, warnings: Diagnostic[], error: Diagnostic | null}} Envelope */
9
9
  /** @typedef {{command?: string, project?: string, stateDirectory?: string, gitCause?: 'repository' | 'revision' | 'read', inspectCatalog?: boolean, inspectSources?: string[], positionals?: string[], values?: Record<string, string | string[] | boolean>, failureCode?: ErrorCode}} ErrorContext */
10
10
  /** @typedef {{json: boolean, command: string, revealKey?: boolean, stdout?: (text: string) => void, stderr?: (text: string) => void}} OutputOptions */
11
11
 
@@ -56,9 +56,10 @@ export const errorCatalog = {
56
56
  COMPARE_ADAPTER_FAILED: [2, 'compare', 'Retry after repairing the adapter callback.'],
57
57
  COMPARE_UNSETTLED: [2, 'compare', 'Retry after stabilizing fixture readiness.'],
58
58
  STATE_INVALID: [2, 'help', 'Inspect the reported state file before retrying.'],
59
+ COMMENT_NOT_FOUND: [2, 'comments', 'List open threads to choose an existing comment.'],
60
+ COMMENT_FORBIDDEN: [2, 'comments', 'Read the comment thread to check who authored the message.'],
59
61
  HUB_KEY_INVALID: [2, 'rotate', 'Replace the invalid key; existing access will expire.'],
60
62
  SERVICE_UNSUPPORTED: [2, 'serve-help', 'Use a foreground hub on this platform.'],
61
- SERVICE_ALREADY_INSTALLED: [2, 'status', 'Inspect the existing installation.'],
62
63
  SERVICE_FAILED: [2, 'logs', 'Inspect service diagnostics before retrying.'],
63
64
  WATCH_FAILED: [2, 'check', 'Inspect project inputs before reopening the viewer.'],
64
65
  SHUTDOWN_FAILED: [2, 'help', 'Inspect the reported resource before retrying.'],
@@ -83,7 +84,8 @@ export class CliError extends Error {
83
84
  }
84
85
 
85
86
  const canonicalCommands = new Set([
86
- 'annotations', 'open', 'link', 'serve', 'root', 'service', 'migrate', 'init', 'check', 'render', 'compare', 'diff', 'owner', 'impact', 'inspect',
87
+ 'comments', 'open', 'link', 'serve', 'root', 'service', 'migrate', 'init', 'check', 'render', 'compare', 'diff', 'owner', 'impact', 'inspect',
88
+ 'comments list', 'comments read', 'comments reply', 'comments resolve',
87
89
  'root add', 'root remove', 'root list', 'root scan',
88
90
  'service install', 'service uninstall', 'service status', 'service logs', 'service migrate',
89
91
  'help', 'version', 'adg',
@@ -167,6 +169,7 @@ export function nextActions(code, context = {}) {
167
169
  }
168
170
  case 'serve-help': argv = helpArgv('serve'); break;
169
171
  case 'roots': argv = ['adg', 'root', 'list', ...state, '--json']; break;
172
+ case 'comments': argv = ['adg', 'comments', ...state, '--json']; break;
170
173
  case 'rotate': argv = ['adg', 'serve', '--rotate-key', ...state, '--json']; break;
171
174
  case 'status': argv = ['adg', 'service', 'status', ...state, '--json']; break;
172
175
  case 'logs': argv = ['adg', 'service', 'logs', ...state, '--json']; break;
@@ -308,11 +311,11 @@ export function createOutput({ json, command, revealKey = false, stdout = text =
308
311
  /** @param {string} text */
309
312
  progress: text => stderr(`${sanitize(text)}\n`),
310
313
  /** @param {unknown} data @param {Diagnostic[]} [warnings] */
311
- success(data, warnings = []) { emit({ schemaVersion: 1, command, ok: true, data: data ?? null, warnings, error: null }); },
314
+ success(data, warnings = []) { emit({ schemaVersion: 2, command, ok: true, data: data ?? null, warnings, error: null }); },
312
315
  /** @param {unknown} cause @param {ErrorContext} [context] */
313
316
  failure(cause, context = {}) {
314
317
  const failure = classifyError(cause, { ...context, command });
315
- if (json) emit({ schemaVersion: 1, command, ok: false, data: failure.data, warnings: failure.warnings, error: failure.error });
318
+ if (json) emit({ schemaVersion: 2, command, ok: false, data: failure.data, warnings: failure.warnings, error: failure.error });
316
319
  else if (!(cause instanceof CliError && cause.humanReported)) stderr(`adg: ${failure.error.message}\n`);
317
320
  return failure.exitCode;
318
321
  },
package/src/cli.mjs CHANGED
@@ -6,34 +6,36 @@ import { realpathSync } from 'node:fs';
6
6
  import { VERSION, loadConfig } from './toolkit/config.mjs';
7
7
  import { CliError, createOutput, withHumanOutput } from './cli-output.mjs';
8
8
 
9
- export const commands = ['annotations', 'open', 'link', 'serve', 'root', 'service', 'migrate', 'init', 'check', 'render', 'compare', 'diff', 'owner', 'impact', 'inspect'];
9
+ export const commands = ['comments', 'open', 'link', 'serve', 'root', 'service', 'migrate', 'init', 'check', 'render', 'compare', 'diff', 'review', 'owner', 'impact', 'inspect'];
10
10
  const targetOptions = '[--asset=<path> [--frame=<name>] | --group=<name> | --layer=<name> | --tokens] [--mode=query|path] [--base=<rev>]';
11
11
  const usage = {
12
- annotations: '[list [--status=open|addressed|resolved|all] | read <id> | reply <id> --message=<text> | address <id> --message=<text> | resolve <id> | reopen <id>] [--state-dir=<path>] [--json]',
12
+ comments: '[[list] [--status=open|resolved|all] [--source=<path>] [--frame=<name>] | read <n> | reply <n> --author=<name> --message=<text> | resolve <n> --author=<name> [--message=<text>]] [--state-dir=<path>] [--json]',
13
13
  open: `[directory] [--port=<n>] [--no-open] [--state-dir=<path>] ${targetOptions}`,
14
- link: `<viewer-url> ${targetOptions}`,
14
+ link: `<viewer-url> [--comment=<n> | ${targetOptions}]`,
15
15
  serve: '[--port=4310] [--state-dir=<path>] [--print-key | --rotate-key]',
16
- service: 'install|uninstall|status|logs|migrate [--state-dir=<path>] [--port=4310]',
16
+ service: 'install|uninstall|status|logs|migrate [--state-dir=<path>] [--port=4310] [--public-origin=<origin>]',
17
17
  root: 'add <dir> [--depth=2] | remove <dir> | list | scan [dir] [--state-dir=<path>]',
18
- migrate: '[project]', init: '', check: '[source...] [--read-only] [--impacted --base=<rev> [--frame=<name>] [--theme=both|light|dark] [--state-dir=<path>] [--explain]]', render: '[source...] [--frame=<name>] [--theme=both|light|dark] [--scale=2] [--out-dir=<path>] [--json] [--base=<rev>] [--impacted [--state-dir=<path>] [--explain]]',
18
+ migrate: '[project]', init: '', check: '[source...] [--read-only] [--impacted --base=<rev> [--frame=<name>] [--theme=both|light|dark] [--state-dir=<path>] [--explain]]', render: '[source...] [--frame=<name>] [--theme=both|light|dark|system] [--scale=2] [--out-dir=<path>] [--json] [--base=<rev>] [--impacted [--state-dir=<path>] [--explain]]',
19
19
  compare: '<source> --frame=<name> [--fixture=<name>] [--region=<name> | --selector=<css> | --page] [--origin="<x> <y>"] [--click=<name>...] [--viewport=<w>x<h>] | --all',
20
- diff: '[source...] --base=<rev> [--frame=<name>] [--theme=both|light|dark] [--scale=2] [--out-dir=<path>] [--json] [--impacted [--state-dir=<path>] [--explain]]',
20
+ diff: '[source...] --base=<rev> [--frame=<name>] [--theme=both|light|dark|system] [--scale=2] [--out-dir=<path>] [--json] [--impacted [--state-dir=<path>] [--explain]]',
21
+ review: '--base=<rev> [--theme=system|light|dark] [--out=<file.html>] [--viewer-url=<project-url>] [--exact] [--json]',
21
22
  owner: '(--file=<path|directory|glob> [--line=<n>] [--symbol=<name>] | --text=<text> [--contains] [--locale=<tag>] | --color=<css> | --token=<name> | --part=<source>[#<Export>]) [--theme=both|light|dark] [--state-dir=<path>] [--json]',
22
23
  inspect: '[source] [--frame=<name>] [--theme=both|light|dark] [--part=<source>#<Export> | --element=<id> | --text=<text> [--contains]] [--depth=<n|all>] [--fields=<groups>] [--wrappers=semantic|all] [--expand] [--state-dir=<path>] [--json]',
23
24
  impact: '(--source=<path>... [--part=<name>] | --token=<name>... | --file=<path|directory|glob> [--line=<n>] [--symbol=<name>] | --base=<rev> [--head=<rev>]) [--theme=both|light|dark] [--explain] [--state-dir=<path>] [--json]',
24
25
  };
25
26
  const details = {
26
- annotations: 'List, read, reply to, address, resolve or reopen project annotations stored outside the repository. Run from the project directory.',
27
+ comments: 'List open project comment threads by default, or read, reply to or resolve a thread by number, #number or ID. Run from the project directory.',
27
28
  migrate: 'Rename a project configuration and runtime imports, update editor paths and ignore entries, remove old generated files and regenerate declarations. Refuses mixed config names; safe to run again.',
28
29
  serve: 'Run the resident multi-project hub on 127.0.0.1. Projects build on viewer access and idle viewers stop after five minutes. --print-key prints the key and exits; --rotate-key rotates the running hub key and exits. Forwarded data requests require a header or query key; direct-local requests are exempt.',
29
- service: 'Manage the macOS resident hub LaunchAgent. install starts it with RunAtLoad and KeepAlive, recording absolute Node/CLI paths. --port applies only to install. status prints JSON; logs prints the last 200 lines per log. Uninstall retains state and logs. migrate moves old hub state and replaces its LaunchAgent, then lists other agents referencing the old state path. --state-dir selects the migration destination. Other platforms are unsupported.',
30
+ service: 'Manage the macOS resident hub LaunchAgent. install creates or updates it with RunAtLoad and KeepAlive, recording absolute Node/CLI paths. --port and --public-origin apply only to install. Set --public-origin to an HTTP(S) origin for public comment links. Reinstalling keeps the port, state directory and public origin unless specified. status prints JSON; logs prints the last 200 lines per log. Uninstall retains state and logs. migrate moves old hub state and replaces its LaunchAgent, then lists other agents referencing the old state path. --state-dir selects the migration destination. Other platforms are unsupported.',
30
31
  root: 'Manage registered scan roots. add scans immediately. scan rescans registered roots only; depth is 0 through 3. Hidden directories, node_modules and Git worktrees are skipped.',
31
32
  open: 'Browse TSX, Mermaid architecture sources and legacy SVG designs on an independent random-port server.', init: 'Create design sources, tokens and editor configuration without overwriting files.',
32
- link: 'Print a clean ADG preview URL. --base=<rev> on a clean viewer URL opens the Git frame review page. Query mode isolates a target. Path mode locates it in the design hierarchy.',
33
- check: 'Check import direction and every selected frame in both themes. --read-only skips generated types and build files. --impacted --base=<rev> evaluates scheduled current rows; proven rows remain not_checked with partial coverage.', render: 'Render selected frames as PNG. Defaults to both themes at 2×. --impacted --base=<rev> captures scheduled plain current frames and reports deletions, with operation-local proofs for skipped rows. Ordinary architecture --base produces proposal overlays; --impacted never does. --json prints completed captures and impact coverage, including zero-job runs.',
33
+ link: 'Print a clean ADG preview URL. --comment=<n> opens a comment thread. --base=<rev> enables Git overlays for architecture diagrams. Query mode isolates a target. Path mode locates it in the design hierarchy.',
34
+ check: 'Check import direction and every selected frame in both themes. --read-only skips generated types and build files. --impacted --base=<rev> evaluates scheduled current rows; proven rows remain not_checked with partial coverage.', render: 'Render selected frames as PNG. Defaults to both themes at 2×. --theme=system resolves the current macOS appearance, otherwise light, and reports the resolved themes. --impacted --base=<rev> captures scheduled plain current frames and reports deletions, with operation-local proofs for skipped rows. Ordinary architecture --base produces proposal overlays; --impacted never does. --json prints completed captures and impact coverage, including zero-job runs.',
34
35
  compare: 'Compare fixture text positions. Flags override Frame fixture and capture. --all writes a summary for every fixture frame.',
35
- diff: 'Compare the Git base and working-tree source/frame union. Existing frames require exact pixels and CSS/device size; added Frame parent declarations enable structural part evidence under diff.thresholds. Defaults to both themes at 2× and <configured output>/diff, overwriting previous diff artifacts and writing a self-contained index.html review page, before/after/difference PNGs and report.json. --impacted captures only scheduled rows (both themes when either theme of a frame is impacted); unqualified both-theme runs count fresh proofs toward full coverage. Required parents/support always capture. A structural batch requires all existing frames in both themes; source/frame/theme restrictions report partial coverage. Exit 0 identical/structural, 1 changed, 2 incomplete.',
36
- owner: 'Find owning design sources, parts, frames and tokens from an implementation path, rendered text, absolute CSS color or token name. Paths resolve from the project root; quote globs. --part reverses the lookup from a design source or source#Export to implementation bindings with resolved files and symbol regions. --line returns the containing export/anchor region, including unmapped exports; non-exported helpers belong to the preceding export. Text is NFC/whitespace normalized and exact unless --contains; --locale filters exact Frame locale annotations without translation. Colors use 8-bit sRGB RGBA equality. Owner evidence is scoped to the query: mappings for files, text runs for text, computed paint for colors and authored references for tokens. Text authoredIn lists literal-search copy candidates; escaped or concatenated strings may be missed. Color evidence may include compact same-element/property references. Defaults to both themes. Broad color/token JSON can be around 100 KB; read owners first and narrow with --theme. Empty, stale and ambiguous results exit 0; invalid/incomplete requests exit 2.',
36
+ diff: 'Compare the Git base and working-tree source/frame union. Existing frames require exact pixels and CSS/device size; added Frame parent declarations enable structural part evidence under diff.thresholds. Defaults to both themes at 2× and <configured output>/diff, overwriting previous diff artifacts and writing a self-contained index.html review page, before/after/difference PNGs and report.json. --impacted also writes review-sheet.png with Added, Changed and Removed sections and up to 12 image cells at 2×. The sheet uses the explicit single theme or system appearance. --theme=system resolves the current macOS appearance, otherwise light. --impacted captures only scheduled rows (both themes when either theme of a frame is impacted); unqualified both-theme runs count fresh proofs toward full coverage. Required parents/support always capture. A structural batch requires all existing frames in both themes; source/frame/theme restrictions report partial coverage. Exit 0 identical/structural, 1 changed, 2 incomplete.',
37
+ review: 'Generate one self-contained HTML review of the Git base and working tree. Defaults to the system theme and <configured output>/review.html. Uses structural prefiltering with pixel comparison for the remaining frames. --exact uses pixel comparison for every frame scheduled by impact analysis. A registered hub supplies frame links, or set --viewer-url. Exit 0 when written, including changes, or 2 for incomplete generation.',
38
+ owner: 'Find owning design sources, parts, frames and tokens from an implementation path, rendered text, absolute CSS color or token name. Paths resolve from the project root; quote globs. --part reverses the lookup from a design source or source#Export to implementation bindings with resolved files and symbol regions. --line returns the containing export/anchor region, including unmapped exports; non-exported helpers belong to the preceding export. Text is NFC/whitespace normalized and exact unless --contains; --locale filters exact Frame locale tags without translation. Colors use 8-bit sRGB RGBA equality. Owner evidence is scoped to the query: mappings for files, text runs for text, computed paint for colors and authored references for tokens. Text authoredIn lists literal-search copy candidates; escaped or concatenated strings may be missed. Color evidence may include compact same-element/property references. Defaults to both themes. Broad color/token JSON can be around 100 KB; read owners first and narrow with --theme. Empty, stale and ambiguous results exit 0; invalid/incomplete requests exit 2.',
37
39
  inspect: 'Read TSX frame structure, text, CSS-pixel boxes, computed styles and token-reference evidence. Without a unique frame, return a catalog. Default: both themes, all fields, full depth. Field groups: structure,layout,typography,color,text. Shared styles, semantic wrappers, repeated subtrees and a sparse dark delta keep the default compact. --expand reconstructs ordinary element records for both themes. No consumer application or viewer is started. Exit 0 completed observation, 2 invalid/incomplete.',
38
40
  impact: 'Query direct/transitive candidates from sources, named parts, tokens or implementation mappings, or compare exact Git endpoints. --base includes staged, unstaged and untracked working files; --head selects another exact commit. Hypothetical selectors cannot prove skips; token candidates assume unchanged Tailwind classification. Git mode freshly executes both endpoint source sets and compares eligible materialized inputs. Closure or occurrence absence never proves safety. Groups merge equal theme and same-source frame records; noncandidate proofs remain counts. --explain samples witnesses/digests without splitting groups. No browser launch. Render/check/diff --impacted compute their own operation-local proofs. Exit 0 completed, including empty/stale mappings; 2 invalid/incomplete.',
39
41
  };
@@ -42,6 +44,7 @@ const helpExamples = {
42
44
  render: 'adg render --impacted --base=HEAD --json\nadg render arch/catalog.mmd --base=HEAD --json',
43
45
  check: 'adg check --impacted --base=HEAD --read-only --json\nadg check --read-only --json',
44
46
  diff: 'adg diff --base=HEAD --impacted --json',
47
+ review: 'adg review --base=HEAD --json',
45
48
  };
46
49
  export function help(command) {
47
50
  if (command) return `Usage: adg ${command} ${usage[command]}\n\n${details[command]}${helpExamples[command] ? `\n\nExamples:\n${helpExamples[command]}` : ''}\n\n-h, --help Show help\nExit codes: 0 success, 1 check/compare/diff problems, 2 usage/configuration/environment error.`;
@@ -53,8 +56,12 @@ export function parseCli(args) {
53
56
  const explicit = commands.includes(args[0]), command = explicit ? args[0] : 'open';
54
57
  const options = { help: { type: 'boolean', short: 'h' }, version: { type: 'boolean', short: 'v' }, json: { type: 'boolean' } };
55
58
  const locators = ['asset', 'frame', 'group', 'layer', 'mode', 'base'];
56
- const strings = { annotations: ['status', 'message', 'state-dir'], open: ['port', 'state-dir', ...locators], link: locators, serve: ['port', 'state-dir'], root: ['depth', 'state-dir'], service: ['port', 'state-dir'], check: ['base', 'frame', 'theme', 'state-dir'], render: ['scale', 'frame', 'theme', 'out-dir', 'base', 'state-dir'], diff: ['base', 'frame', 'theme', 'scale', 'out-dir', 'state-dir'], compare: ['frame', 'fixture', 'region', 'selector', 'viewport', 'origin'], owner: ['file', 'text', 'color', 'token', 'part', 'line', 'symbol', 'locale', 'theme', 'state-dir'], impact: ['source', 'part', 'token', 'file', 'line', 'symbol', 'base', 'head', 'theme', 'state-dir'], inspect: ['frame','theme','part','element','text','depth','fields','wrappers','state-dir'] };
59
+ const strings = { comments: ['status', 'source', 'frame', 'author', 'message', 'state-dir'], open: ['port', 'state-dir', ...locators], link: [...locators, 'comment'], serve: ['port', 'state-dir'], root: ['depth', 'state-dir'], service: ['port', 'state-dir', 'public-origin'], check: ['base', 'frame', 'theme', 'state-dir'], render: ['scale', 'frame', 'theme', 'out-dir', 'base', 'state-dir'], diff: ['base', 'frame', 'theme', 'scale', 'out-dir', 'state-dir'], compare: ['frame', 'fixture', 'region', 'selector', 'viewport', 'origin'], owner: ['file', 'text', 'color', 'token', 'part', 'line', 'symbol', 'locale', 'theme', 'state-dir'], impact: ['source', 'part', 'token', 'file', 'line', 'symbol', 'base', 'head', 'theme', 'state-dir'], inspect: ['frame','theme','part','element','text','depth','fields','wrappers','state-dir'] };
57
60
  for (const name of strings[command] ?? []) options[name] = { type: 'string' };
61
+ if (command === 'review') {
62
+ for (const name of ['base', 'theme', 'out', 'viewer-url']) options[name] = { type: 'string' };
63
+ options.exact = { type: 'boolean' };
64
+ }
58
65
  if (command === 'serve') for (const name of ['print-key', 'rotate-key']) options[name] = { type: 'boolean' };
59
66
  if (command === 'open') options['no-open'] = { type: 'boolean' };
60
67
  if (command === 'open' || command === 'link') options.tokens = { type: 'boolean' };
@@ -74,6 +81,11 @@ const strings = { annotations: ['status', 'message', 'state-dir'], open: ['port'
74
81
  const { values, positionals } = parsed;
75
82
  if (globalJson) values.json = true;
76
83
  if (!values.help && !values.version) {
84
+ if (command === 'review' && (positionals.length || !values.base?.trim() ||
85
+ (values.theme !== undefined && !['system', 'light', 'dark'].includes(values.theme)) ||
86
+ (values.out !== undefined && !/\.html$/i.test(values.out)) || values['viewer-url'] === '')) {
87
+ throw new CliError('USAGE_INVALID', 'Set --base=<rev>, choose one theme, and use an HTML path for --out; run adg review --help.');
88
+ }
77
89
  if (['render', 'check', 'diff'].includes(command)) {
78
90
  if (!values.impacted && (values.explain !== undefined || values['state-dir'] !== undefined)) throw new CliError('USAGE_INVALID', '--explain and --state-dir require --impacted --base=<rev>.');
79
91
  if (values.impacted && (typeof values.base !== 'string' || !values.base.trim())) throw new CliError('USAGE_INVALID', '--impacted requires --base=<rev>.');
@@ -121,19 +133,22 @@ const strings = { annotations: ['status', 'message', 'state-dir'], open: ['port'
121
133
  if (command === 'diff' && (typeof values.base !== 'string' || !values.base.trim())) throw new CliError('USAGE_INVALID', 'Set --base to a Git revision; run adg diff --help.');
122
134
  if ((command === 'init' && positionals.length) || (['open', 'migrate'].includes(command) && positionals.length > 1) || (command === 'compare' && (values.all ? positionals.length || values.frame : positionals.length !== 1 || !values.frame))) throw new CliError('USAGE_INVALID', `Invalid arguments; run adg ${command} --help`);
123
135
  if (command === 'link' && positionals.length !== 1) throw new CliError('USAGE_INVALID', 'Expected one viewer URL. Run adg link --help.');
124
- if (command === 'service' && (positionals.length !== 1 || !serviceActions.includes(positionals[0]) || (values.port !== undefined && positionals[0] !== 'install'))) throw new CliError('USAGE_INVALID', 'Invalid arguments; run adg service --help');
136
+ if (command === 'service' && (positionals.length !== 1 || !serviceActions.includes(positionals[0]) || (['port', 'public-origin'].some(name => values[name] !== undefined) && positionals[0] !== 'install'))) throw new CliError('USAGE_INVALID', 'Invalid arguments; run adg service --help');
125
137
  if (command === 'root') {
126
138
  const [action, directory, ...extra] = positionals;
127
139
  if (extra.length || !rootActions.includes(action) || (['add', 'remove'].includes(action) && !directory) || (action === 'list' && directory) || (values.depth !== undefined && action !== 'add')) throw new CliError('USAGE_INVALID', 'Invalid arguments; run adg root --help');
128
140
  }
129
- if (command === 'annotations') {
141
+ if (command === 'comments') {
130
142
  const [action = 'list', id, ...extra] = positionals;
131
- if (!['list', 'read', 'reply', 'address', 'resolve', 'reopen'].includes(action) || extra.length ||
132
- (action === 'list' ? id !== undefined || values.message !== undefined : !id || values.status !== undefined) ||
133
- (values.status !== undefined && !['open', 'addressed', 'resolved', 'all'].includes(values.status)) ||
134
- (['reply', 'address'].includes(action) ? typeof values.message !== 'string' || !values.message.trim() : values.message !== undefined) ||
135
- (values['state-dir'] !== undefined && !values['state-dir'].trim())) {
136
- throw new CliError('USAGE_INVALID', 'Use annotations list, read <id>, reply <id> --message=<text>, address <id> --message=<text>, resolve <id> or reopen <id>; run adg annotations --help.');
143
+ const write = action === 'reply' || action === 'resolve';
144
+ const hasFilter = ['status', 'source', 'frame'].some(key => values[key] !== undefined);
145
+ if (!commentActions.includes(action) || extra.length ||
146
+ (action === 'list' ? id !== undefined : !id?.trim() || hasFilter) ||
147
+ (write ? values.author === undefined : values.author !== undefined || values.message !== undefined) ||
148
+ (action === 'reply' && values.message === undefined) ||
149
+ strings.comments.some(key => values[key] !== undefined && !values[key].trim()) ||
150
+ (values.status !== undefined && !['open', 'resolved', 'all'].includes(values.status))) {
151
+ throw new CliError('USAGE_INVALID', 'Choose a comment action and its options. Run adg comments --help.');
137
152
  }
138
153
  }
139
154
  if (command === 'serve' && positionals.length) throw new CliError('USAGE_INVALID', 'Invalid arguments; run adg serve --help');
@@ -145,10 +160,12 @@ const strings = { annotations: ['status', 'message', 'state-dir'], open: ['port'
145
160
  }
146
161
  const rootActions = ['add', 'remove', 'list', 'scan'];
147
162
  const serviceActions = ['install', 'uninstall', 'status', 'logs', 'migrate'];
163
+ const commentActions = ['list', 'read', 'reply', 'resolve'];
148
164
 
149
- export function commandIdentity({ command, positionals = [] }) {
150
- const actions = command === 'root' ? rootActions : command === 'service' ? serviceActions : [];
151
- return actions.includes(positionals[0]) ? `${command} ${positionals[0]}` : command;
165
+ export function commandIdentity({ command, positionals = [], values }) {
166
+ const actions = command === 'root' ? rootActions : command === 'service' ? serviceActions : command === 'comments' ? commentActions : [];
167
+ const action = positionals[0] ?? (command === 'comments' && !values?.help ? 'list' : undefined);
168
+ return actions.includes(action) ? `${command} ${action}` : command;
152
169
  }
153
170
 
154
171
  export function jsonRequested(args) {
@@ -195,13 +212,15 @@ async function dispatch({ command, values, positionals }, cwd, output, serviceOp
195
212
  return {data:values['print-key'] ? {action:'print-key',stateDirectory,key} : {action:'rotate-key',stateDirectory,rotated:true}};
196
213
  }
197
214
  const config = await loadConfig(cwd);
198
- if (command === 'annotations') {
215
+ if (command === 'comments') {
199
216
  const [action = 'list', id] = positionals;
200
217
  const stateDir = values['state-dir'] ? path.resolve(cwd, values['state-dir']) : undefined;
201
- const mod = await import('./annotations.mjs');
202
- const data = action === 'read'
203
- ? await mod.readAnnotationContext(config, stateDir, id)
204
- : await mod.annotations(config.root, stateDir, action, { id, status: values.status ?? 'open', message: values.message, author: 'agent' });
218
+ const { changeComment, listComments, readCommentContext } = await import('./comments.mjs');
219
+ const data = action === 'list'
220
+ ? await listComments(config.root, stateDir, { status: values.status ?? 'open', source: values.source, frame: values.frame })
221
+ : action === 'read'
222
+ ? await readCommentContext(config, stateDir, id)
223
+ : await changeComment(config.root, stateDir, { action, id, message: values.message }, { author: values.author });
205
224
  if (!values.json) output.log(JSON.stringify(data, null, 2));
206
225
  return { data };
207
226
  }
@@ -211,6 +230,7 @@ async function dispatch({ command, values, positionals }, cwd, output, serviceOp
211
230
  if (command === 'init') return { data: (await import('./toolkit/project.mjs')).init(config, output.log) };
212
231
  if (command === 'compare') return (await import('./toolkit/compare.mjs')).compare(config, positionals, values, {log:output.log});
213
232
  if (command === 'diff') return (await import('./toolkit/diff.mjs')).diff(config, positionals, values, { log: output.log });
233
+ if (command === 'review') return (await import('./toolkit/review.mjs')).review(config, values, { log: output.log });
214
234
  const toolkit = await import('./toolkit/commands.mjs');
215
235
  return command === 'check' ? toolkit.check(config, positionals, values, output.log, output.progress) : toolkit.render(config, positionals, values, output.log);
216
236
  }