truemap-cli 0.3.0 → 0.5.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.
package/kit/truemap.css CHANGED
@@ -1,58 +1,61 @@
1
1
  /* truemap page kit. truemap serves this file to every page in .truemap/ (assets/truemap.css).
2
2
  To match a project's own look, put token overrides in .truemap/assets/theme.css – truemap appends it here. */
3
3
 
4
- @font-face { font-family: "IBM Plex Sans"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/ibm-plex-sans-latin-400-normal.woff2") format("woff2"); }
5
- @font-face { font-family: "IBM Plex Sans"; font-weight: 500; font-display: swap; src: url("/__truemap/fonts/ibm-plex-sans-latin-500-normal.woff2") format("woff2"); }
6
- @font-face { font-family: "IBM Plex Sans"; font-weight: 600; font-display: swap; src: url("/__truemap/fonts/ibm-plex-sans-latin-600-normal.woff2") format("woff2"); }
7
- @font-face { font-family: "IBM Plex Mono"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/ibm-plex-mono-latin-400-normal.woff2") format("woff2"); }
8
- @font-face { font-family: "IBM Plex Mono"; font-weight: 500; font-display: swap; src: url("/__truemap/fonts/ibm-plex-mono-latin-500-normal.woff2") format("woff2"); }
4
+ @font-face { font-family: "Instrument Sans"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-400-normal.woff2") format("woff2"); }
5
+ @font-face { font-family: "Instrument Sans"; font-weight: 500; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-500-normal.woff2") format("woff2"); }
6
+ @font-face { font-family: "Instrument Sans"; font-weight: 600; font-display: swap; src: url("/__truemap/fonts/instrument-sans-latin-600-normal.woff2") format("woff2"); }
7
+ @font-face { font-family: "Commit Mono"; font-weight: 400; font-display: swap; src: url("/__truemap/fonts/commit-mono-latin-400-normal.woff2") format("woff2"); }
9
8
 
9
+ /* One fixed system. Neutrals and ink carry structure; --tm-accent (ink unless the project has its own
10
+ colour) marks the primary action; a highlighter marks what the agent points at; status colours mean
11
+ status only. */
10
12
  :root {
11
- --tm-paper: #f6f7f4; /* page background */
13
+ --tm-paper: #ffffff; /* page background */
12
14
  --tm-sheet: #ffffff; /* boxes on the map */
13
- --tm-wash: #eef0ec; /* quiet fills */
14
- --tm-ink: #17202b; /* titles */
15
- --tm-text: #2a3441; /* body text */
16
- --tm-graphite: #5b6573; /* secondary text */
17
- --tm-pencil: #8a939e; /* paths, hints */
18
- --tm-rule: #dde1db;
19
- --tm-rule-strong: #c2c8c1;
20
- --tm-route: #2453c4; /* the one emphasis: the key path, links, decisions */
21
- --tm-route-ink: #1b3f96;
22
- --tm-route-wash: #e9eefb;
23
- --tm-action: #2453c4; /* filled buttons */
24
- --tm-changed: #a2690a;
25
- --tm-changed-wash: #fbf2e0;
26
- --tm-broken: #b03a2e;
27
- --tm-broken-wash: #fbeae7;
28
- --tm-fine: #2c7550;
29
- --tm-fine-wash: #e5f1e9;
30
- --tm-radius: 6px;
31
- --tm-font: "IBM Plex Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
32
- --tm-code: "IBM Plex Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
15
+ --tm-wash: #f2f2ef; /* quiet fills, groups */
16
+ --tm-ink: #141413; /* titles, the main path, selection */
17
+ --tm-text: #2b2b28; /* body text */
18
+ --tm-graphite: #6c6c65; /* secondary text */
19
+ --tm-pencil: #9a9a92; /* hints */
20
+ --tm-rule: #e6e6e1;
21
+ --tm-rule-strong: #d2d2cb;
22
+ --tm-accent: #141413; /* the primary action; the project's own colour when truemap finds one */
23
+ --tm-mark: #ffe27a; /* the agent points here */
24
+ --tm-route: var(--tm-ink); /* v0.4 name for the key path and links */
25
+ --tm-route-ink: var(--tm-ink);
26
+ --tm-route-wash: #f2f2ef;
27
+ --tm-action: var(--tm-accent);
28
+ --tm-changed: #a35f00;
29
+ --tm-changed-wash: #fbf1df;
30
+ --tm-broken: #c0392b;
31
+ --tm-broken-wash: #fbe9e6;
32
+ --tm-fine: #2f7a4f;
33
+ --tm-fine-wash: #e6f1ea;
34
+ --tm-radius: 8px;
35
+ --tm-font: "Instrument Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
36
+ --tm-code: "Commit Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
33
37
  color-scheme: light dark;
34
38
  }
35
39
 
36
40
  @media (prefers-color-scheme: dark) {
37
41
  :root {
38
- --tm-paper: #121519;
39
- --tm-sheet: #191d23;
40
- --tm-wash: #1f242b;
41
- --tm-ink: #edf0f3;
42
- --tm-text: #d0d6dd;
43
- --tm-graphite: #9ba4af;
44
- --tm-pencil: #707a86;
45
- --tm-rule: #2a3039;
46
- --tm-rule-strong: #3d4651;
47
- --tm-route: #7ea3ff;
48
- --tm-route-ink: #a9c0ff;
49
- --tm-route-wash: #1b2440;
50
- --tm-action: #3a66d6;
51
- --tm-changed: #d9a54a;
42
+ --tm-paper: #161615;
43
+ --tm-sheet: #161615;
44
+ --tm-wash: #222220;
45
+ --tm-ink: #f2f2ee;
46
+ --tm-text: #dadad4;
47
+ --tm-graphite: #a0a098;
48
+ --tm-pencil: #75756e;
49
+ --tm-rule: #2f2f2c;
50
+ --tm-rule-strong: #44443f;
51
+ --tm-accent: #f2f2ee;
52
+ --tm-mark: #6b5a12;
53
+ --tm-route-wash: #222220;
54
+ --tm-changed: #e0a548;
52
55
  --tm-changed-wash: #2c2414;
53
- --tm-broken: #ec8170;
56
+ --tm-broken: #ef8574;
54
57
  --tm-broken-wash: #321b18;
55
- --tm-fine: #73bd95;
58
+ --tm-fine: #7cc49c;
56
59
  --tm-fine-wash: #16271e;
57
60
  }
58
61
  }
@@ -65,7 +68,7 @@ body {
65
68
  overflow-x: clip;
66
69
  background: var(--tm-paper);
67
70
  color: var(--tm-text);
68
- font: 16px/1.62 var(--tm-font);
71
+ font: 15px/1.6 var(--tm-font);
69
72
  font-feature-settings: "kern", "liga";
70
73
  -webkit-font-smoothing: antialiased;
71
74
  text-rendering: optimizeLegibility;
@@ -77,7 +80,7 @@ strong, b { color: var(--tm-ink); font-weight: 600; }
77
80
  a { color: var(--tm-route); text-decoration-line: underline; text-decoration-thickness: 1px; text-underline-offset: 3px; text-decoration-color: color-mix(in oklab, var(--tm-route) 40%, transparent); }
78
81
  a:hover { text-decoration-color: var(--tm-route); }
79
82
  :focus-visible { outline: 2px solid var(--tm-route); outline-offset: 2px; }
80
- ::selection { background: var(--tm-route-wash); color: var(--tm-ink); }
83
+ ::selection { background: var(--tm-mark); color: var(--tm-ink); }
81
84
  h1, h2, h3, h4 { color: var(--tm-ink); font-weight: 600; text-wrap: balance; }
82
85
  ul, ol { padding-left: 1.3em; max-width: 68ch; }
83
86
  li { margin: 0.2em 0; }
@@ -85,19 +88,19 @@ li::marker { color: var(--tm-pencil); }
85
88
  hr { border: 0; border-top: 1px solid var(--tm-rule); margin: 40px 0; }
86
89
 
87
90
  /* ---------- page ---------- */
88
- .tm-page { max-width: 960px; margin: 0 auto; padding: 48px 48px 112px; }
91
+ .tm-page { max-width: 960px; margin: 0 auto; padding: 36px 48px 96px; }
89
92
  .tm-header { margin-bottom: 8px; }
90
93
  .tm-crumb, .tm-eyebrow { font-size: 13.5px; color: var(--tm-graphite); margin: 0 0 14px; }
91
94
  .tm-crumb a { color: var(--tm-graphite); text-decoration-color: var(--tm-rule-strong); }
92
95
  .tm-crumb a:hover { color: var(--tm-route); }
93
- .tm-title { font-size: 36px; line-height: 1.15; letter-spacing: -0.018em; margin: 0 0 14px; max-width: 22ch; }
94
- .tm-lede { font-size: 18.5px; line-height: 1.55; color: var(--tm-graphite); margin: 0; max-width: 60ch; }
96
+ .tm-title { font-size: 28px; line-height: 1.2; letter-spacing: -0.02em; margin: 0 0 8px; max-width: 24ch; }
97
+ .tm-lede { font-size: 17px; line-height: 1.55; color: var(--tm-graphite); margin: 0; max-width: 60ch; }
95
98
  .tm-lede strong { color: var(--tm-text); font-weight: 500; }
96
99
 
97
100
  .tm-section { margin-top: 64px; }
98
- .tm-section > h2, .tm-h2 { font-size: 22px; line-height: 1.3; letter-spacing: -0.01em; margin: 0 0 8px; }
101
+ .tm-section > h2, .tm-h2 { font-size: 20px; line-height: 1.3; letter-spacing: -0.01em; margin: 0 0 8px; }
99
102
  .tm-section > h2 + p { color: var(--tm-graphite); }
100
- .tm-section h3 { font-size: 16.5px; line-height: 1.35; margin: 32px 0 8px; }
103
+ .tm-section h3 { font-size: 15px; line-height: 1.35; margin: 32px 0 8px; }
101
104
  .tm-section > :last-child { margin-bottom: 0; }
102
105
  .tm-muted { color: var(--tm-graphite); }
103
106
  .tm-small { font-size: 13.5px; }
@@ -124,25 +127,19 @@ html[style*="--tm-vw"] .tm-map, html[style*="--tm-vw"] .tm-blueprint { width: ca
124
127
  .tm-node, .tm-step {
125
128
  position: relative; z-index: 1;
126
129
  display: flex; flex-direction: column; flex: 0 1 216px; min-width: 156px; max-width: 280px;
127
- padding: 11px 26px 12px 14px;
130
+ padding: 11px 14px 12px;
128
131
  background: var(--tm-sheet); color: var(--tm-text);
129
132
  border: 1px solid var(--tm-rule-strong); border-radius: var(--tm-radius);
130
133
  text-decoration: none; line-height: 1.4;
131
134
  transition: border-color 120ms ease, box-shadow 120ms ease;
132
135
  }
133
- a.tm-node:hover, a.tm-step:hover { border-color: var(--tm-graphite); }
136
+ /* Every box opens (its code, its connections, its page), so every box answers the pointer. */
137
+ .tm-node:hover, .tm-step:hover { border-color: var(--tm-graphite); }
134
138
  .tm-node-title, .tm-step > b, .tm-step > strong { font-size: 15px; font-weight: 600; color: var(--tm-ink); }
135
139
  .tm-node-sub { font-family: var(--tm-code); font-size: 12px; color: var(--tm-pencil); margin-top: 2px; overflow-wrap: break-word; }
136
140
  .tm-node-desc { font-size: 13.5px; line-height: 1.45; color: var(--tm-graphite); margin-top: 7px; }
137
141
 
138
- /* The survey mark: a box pinned to real code (data-src) carries a small triangle. */
139
- .tm-node[data-src]::after, .tm-step[data-src]::after, .tm-card[data-src]::after {
140
- content: ""; position: absolute; top: 11px; right: 11px; width: 8px; height: 7px;
141
- background: var(--tm-pencil); clip-path: polygon(50% 0, 100% 100%, 0 100%);
142
- }
143
- .tm-node.is-key, .tm-step.is-key { border-color: var(--tm-route); box-shadow: inset 0 0 0 1px var(--tm-route); }
144
- .tm-node.is-key .tm-node-title, .tm-step.is-key > b, .tm-step.is-key > strong { color: var(--tm-route-ink); }
145
- .tm-node.is-key::after, .tm-step.is-key::after { background: var(--tm-route); }
142
+ /* .is-key marks the main path. The boxes stay plain; the path shows as the blue wire between them. */
146
143
  .tm-node.is-ext, .tm-step.is-ext { background: transparent; border-style: dashed; }
147
144
  .tm-node.is-ext .tm-node-title, .tm-step.is-ext > b { color: var(--tm-graphite); font-weight: 500; }
148
145
  .tm-node.is-new, .tm-step.is-new { border-color: var(--tm-fine); }
@@ -150,12 +147,35 @@ a.tm-node:hover, a.tm-step:hover { border-color: var(--tm-graphite); }
150
147
 
151
148
  /* Wires (drawn by truemap into svg.tm-wires) */
152
149
  .tm-wires { position: absolute; top: 0; left: 0; max-width: none; pointer-events: none; overflow: visible; z-index: 0; }
153
- .tm-wire { fill: none; stroke: var(--tm-rule-strong); stroke-width: 1.5; }
150
+ /* Quiet by default: the main path is the only strong line. Hover a box and its own wires come forward. */
151
+ .tm-wire { fill: none; stroke: var(--tm-rule-strong); stroke-width: 1.25; }
154
152
  .tm-wire.is-key { stroke: var(--tm-route); stroke-width: 2; }
155
153
  .tm-wire.is-ext { stroke-dasharray: 4 4; }
156
154
  .tm-wire-head { fill: var(--tm-rule-strong); }
157
155
  .tm-wire-head.is-key { fill: var(--tm-route); }
158
- .tm-wire-label { font: 500 11.5px var(--tm-font); fill: var(--tm-graphite); paint-order: stroke; stroke: var(--tm-paper); stroke-width: 4px; stroke-linejoin: round; }
156
+ /* Labels: the main path's always show; any other wire's label shows when its box is hovered or its path is lit. */
157
+ .tm-wire-label { font: 500 11.5px var(--tm-font); fill: var(--tm-pencil); paint-order: stroke; stroke: var(--tm-paper); stroke-width: 6px; stroke-linejoin: round; opacity: 0; transition: opacity .15s ease; }
158
+ .tm-wire-label.is-key, .tm-wire-label.is-hot, .tm-wire-label.is-focus { opacity: 1; }
159
+ .tm-wire-plate { fill: var(--tm-paper); opacity: 0; }
160
+ .tm-wire-plate.is-key, .tm-wire-plate.is-hot, .tm-wire-plate.is-focus { opacity: 1; }
161
+ html[data-tm-focusing] .tm-wire-plate:not(.is-focus) { opacity: 0; }
162
+ /* A lit path (a flow, or the agent pointing): everything else steps back. */
163
+ html[data-tm-focusing] .tm-node:not([data-tm-focus]), html[data-tm-focusing] .tm-step:not([data-tm-focus]) { opacity: .34; }
164
+ html[data-tm-focusing] .tm-wire:not(.is-focus), html[data-tm-focusing] .tm-wire-head:not(.is-focus) { opacity: .16; }
165
+ html[data-tm-focusing] .tm-wire-label:not(.is-focus) { opacity: 0; }
166
+ .tm-wire.is-hot { stroke: var(--tm-ink); stroke-width: 1.75; }
167
+ .tm-wire-head.is-hot { fill: var(--tm-ink); }
168
+ .tm-wire-label.is-hot { fill: var(--tm-ink); }
169
+ .tm-wire.is-focus { stroke: var(--tm-route); stroke-width: 2.5; }
170
+ .tm-wire-head.is-focus { fill: var(--tm-route); }
171
+ .tm-wire-label.is-focus { fill: var(--tm-route-ink); }
172
+
173
+ /* Paths through the map: one click lights a path up (data-tm-flow="id id id"). */
174
+ .tm-flows { display: flex; flex-wrap: wrap; align-items: center; gap: 8px; margin: 18px 0 0; }
175
+ .tm-flows > span { font-size: 13px; color: var(--tm-graphite); margin-right: 2px; }
176
+ .tm-flows button, .tm-flow-btn { font: 500 13px/1.2 var(--tm-font); color: var(--tm-text); background: var(--tm-sheet); border: 1px solid var(--tm-rule-strong); border-radius: var(--tm-radius); padding: 6px 10px; cursor: pointer; }
177
+ .tm-flows button:hover, .tm-flow-btn:hover { border-color: var(--tm-graphite); }
178
+ .tm-flows button[aria-pressed="true"], .tm-flow-btn[aria-pressed="true"] { border-color: var(--tm-route); background: var(--tm-route-wash); color: var(--tm-route-ink); }
159
179
 
160
180
  /* Legend under a map */
161
181
  .tm-legend { display: flex; flex-wrap: wrap; gap: 6px 22px; margin: 22px 0 0 132px; font-size: 13px; color: var(--tm-graphite); }
@@ -163,7 +183,7 @@ a.tm-node:hover, a.tm-step:hover { border-color: var(--tm-graphite); }
163
183
  .tm-legend i { display: inline-block; width: 22px; height: 0; border-top: 2px solid var(--tm-route); }
164
184
  .tm-legend i.is-wire { border-top: 1.5px solid var(--tm-rule-strong); }
165
185
  .tm-legend i.is-ext { border-top: 1.5px dashed var(--tm-rule-strong); }
166
- .tm-legend i.is-mark { width: 8px; height: 7px; border: 0; background: var(--tm-pencil); clip-path: polygon(50% 0, 100% 100%, 0 100%); }
186
+ .tm-legend span:has(> i.is-mark) { display: none; } /* older pages: the corner mark is gone */
167
187
 
168
188
  /* ---------- flow: a real sequence ---------- */
169
189
  .tm-flow { display: flex; align-items: stretch; gap: 30px; margin: 24px 0 8px; overflow-x: auto; padding: 2px 2px 6px; }
@@ -290,3 +310,100 @@ pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background
290
310
  body { background: #fff; }
291
311
  .tm-page { padding: 0; }
292
312
  }
313
+
314
+ /* ===================== diagrams (v0.5): small nodes in groups, laid out left to right ===================== */
315
+ .tm-diagram {
316
+ --dg-bg: var(--tm-paper); --dg-surface: var(--tm-wash); --dg-line: var(--tm-rule); --dg-line-strong: var(--tm-rule-strong);
317
+ --dg-muted: var(--tm-graphite); --dg-text: var(--tm-text); --dg-ink: var(--tm-ink); --dg-mark: var(--tm-mark);
318
+ --dg-font: var(--tm-font); --dg-code: var(--tm-code);
319
+ position: relative; margin: 20px 0 8px; font-family: var(--dg-font);
320
+ overflow-x: hidden; overflow-y: hidden; padding: 0 0 8px;
321
+ }
322
+ .tm-dg-stage { position: relative; transform-origin: 0 0; }
323
+ .tm-diagram.is-wide { overflow-x: auto; }
324
+ .tm-dg-edges { position: absolute; inset: 0; overflow: visible; pointer-events: none; z-index: 1; }
325
+ .tm-dg-group { position: absolute; z-index: 0; background: var(--dg-surface); border-radius: 12px; }
326
+ .tm-dg-glabel { position: absolute; top: 8px; left: 12px; line-height: 16px; font-size: 12px; font-weight: 500; color: var(--dg-muted); white-space: nowrap; }
327
+ .tm-diagram .tm-node {
328
+ position: absolute; z-index: 2; display: block; box-sizing: border-box; max-width: 190px; min-width: 0; flex: none;
329
+ padding: 8px 12px 9px; background: var(--dg-bg); color: var(--dg-ink);
330
+ border: 1px solid var(--dg-line-strong); border-radius: 8px; box-shadow: none; text-decoration: none; cursor: pointer;
331
+ transition: border-color .12s ease, color .12s ease;
332
+ }
333
+ .tm-diagram .tm-node::after { display: none; }
334
+ .tm-diagram .tm-node:hover { border-color: var(--dg-ink); }
335
+ .tm-dg-face { display: grid; gap: 1px; }
336
+ .tm-dg-name { font-size: 13.5px; font-weight: 500; line-height: 1.3; white-space: nowrap; }
337
+ .tm-dg-tag { font-family: var(--dg-code); font-size: 11px; line-height: 1.35; color: var(--dg-muted); white-space: nowrap; }
338
+ .tm-diagram .tm-node.is-ext { background: var(--dg-bg); border-style: dashed; border-color: var(--dg-line-strong); }
339
+ .tm-diagram .tm-node.is-ext .tm-dg-name { color: var(--dg-muted); }
340
+ .tm-diagram .tm-detail { display: none; }
341
+ .tm-dg-edge { fill: none; stroke: var(--dg-line-strong); stroke-width: 1.25; }
342
+ .tm-dg-edge.is-main { stroke: var(--dg-ink); stroke-width: 1.6; }
343
+ .tm-dg-edge.is-ext { stroke-dasharray: 3 4; }
344
+ .tm-dg-head { fill: var(--dg-line-strong); }
345
+ .tm-dg-head.is-main { fill: var(--dg-ink); }
346
+ .tm-dg-edge.is-hot, .tm-dg-edge.is-flow { stroke: var(--dg-ink); stroke-width: 1.75; }
347
+ .tm-dg-head.is-hot, .tm-dg-head.is-flow { fill: var(--dg-ink); }
348
+ .tm-dg-label { position: absolute; z-index: 3; transform: translate(-50%, -50%); font: 400 11px/1.3 var(--dg-code); color: var(--dg-muted); background: var(--dg-bg); padding: 1px 4px; border-radius: 4px; white-space: nowrap; pointer-events: none; }
349
+ .tm-dg-group ~ .tm-dg-label { background: var(--dg-bg); }
350
+ .tm-dg-label.is-hot, .tm-dg-label.is-flow { color: var(--dg-ink); }
351
+ /* at rest only the main path says its verbs; a hovered or selected box, a lit path or a flow shows the rest */
352
+ .tm-dg-label:not(.is-main):not(.is-hot):not(.is-flow):not(.is-focus):not(.is-sel), .tm-dg-label.is-dup:not(.is-flow):not(.is-focus), .tm-dg-label.is-crowded:not(.is-hot):not(.is-flow):not(.is-focus):not(.is-sel) { visibility: hidden; }
353
+ .tm-dg-edge.is-sel { stroke: var(--dg-ink); stroke-width: 1.75; }
354
+ .tm-dg-head.is-sel { fill: var(--dg-ink); }
355
+ .tm-dg-label.is-sel { color: var(--dg-ink); }
356
+ /* the agent (or an answer) points at boxes: they get the highlighter, the rest go quiet without fading */
357
+ html[data-tm-focusing] .tm-diagram .tm-node:not([data-tm-focus]) { opacity: 1; border-color: var(--dg-line); }
358
+ html[data-tm-focusing] .tm-diagram .tm-node:not([data-tm-focus]) .tm-dg-name, html[data-tm-focusing] .tm-diagram .tm-node:not([data-tm-focus]) .tm-dg-tag { color: var(--dg-line-strong); }
359
+ html[data-tm-focusing] .tm-dg-edge:not(.is-focus) { stroke: var(--dg-line); }
360
+ html[data-tm-focusing] .tm-dg-head:not(.is-focus) { fill: var(--dg-line); }
361
+ html[data-tm-focusing] .tm-dg-label:not(.is-focus) { color: var(--dg-line-strong); }
362
+ .tm-dg-edge.is-focus { stroke: var(--dg-ink); stroke-width: 1.75; }
363
+ .tm-dg-head.is-focus { fill: var(--dg-ink); }
364
+ .tm-dg-label.is-focus { color: var(--dg-ink); }
365
+ /* reviewing changes: changed boxes carry their lines, the rest go quiet */
366
+ html[data-tm-changes] .tm-diagram:not([data-flow]) .tm-node:not([data-tm-change]):not([data-tm-unbuilt]) { border-color: var(--dg-line); }
367
+ html[data-tm-changes] .tm-diagram:not([data-flow]) .tm-node:not([data-tm-change]):not([data-tm-unbuilt]) .tm-dg-name, html[data-tm-changes] .tm-diagram:not([data-flow]) .tm-node:not([data-tm-change]):not([data-tm-unbuilt]) .tm-dg-tag { color: var(--dg-line-strong); }
368
+ html[data-tm-changes] .tm-diagram .tm-node[data-tm-unbuilt] { border: 1.5px dashed var(--tm-changed); }
369
+ html[data-tm-changes] .tm-diagram .tm-node[data-tm-unbuilt]:not([data-tm-delta])::after { display: block; content: "Planned, not built"; position: absolute; top: -9px; right: -8px; font: 500 10.5px/14px var(--dg-font); padding: 0 6px; border-radius: 8px; background: var(--dg-bg); color: var(--tm-changed); border: 1px solid var(--tm-changed); white-space: nowrap; pointer-events: none; }
370
+ html[data-tm-changes] .tm-diagram .tm-node[data-tm-change] { border-color: var(--dg-ink); }
371
+ html[data-tm-changes] .tm-dg-edge:not(.is-hot):not(.is-flow) { stroke: var(--dg-line); stroke-width: 1.25; }
372
+ html[data-tm-changes] .tm-dg-head:not(.is-hot):not(.is-flow) { fill: var(--dg-line); }
373
+ html[data-tm-changes] .tm-dg-label:not(.is-hot):not(.is-flow) { color: var(--dg-line-strong); }
374
+ .tm-diagram .tm-node[data-tm-delta]::after { display: block; content: attr(data-tm-delta); position: absolute; top: -9px; right: -8px; font: 10.5px/16px var(--dg-code); padding: 0 6px; border-radius: 8px; background: var(--dg-ink); color: var(--dg-bg); white-space: nowrap; pointer-events: none; }
375
+ html[data-tm-changes] .tm-node[data-tm-change]:not(.tm-diagram .tm-node) { outline: 2px solid var(--tm-ink); outline-offset: 2px; }
376
+ /* a plan on the map: new boxes dashed, touched boxes outlined, a small word on each */
377
+ .tm-diagram .tm-node[data-plan="new"] { border: 1.5px dashed var(--dg-ink); }
378
+ .tm-diagram .tm-node[data-plan="change"] { border-color: var(--dg-ink); box-shadow: 0 0 0 1px var(--dg-ink); }
379
+ .tm-diagram .tm-node[data-plan="remove"] .tm-dg-name { text-decoration: line-through; }
380
+ .tm-diagram .tm-node[data-plan]:not([data-tm-delta])::after { display: block; position: absolute; top: -9px; right: -8px; font: 500 12px/17px var(--dg-font); padding: 0 8px; border-radius: 9px; background: var(--dg-bg); color: var(--dg-ink); border: 1px solid var(--dg-ink); white-space: nowrap; pointer-events: none; }
381
+ .tm-diagram .tm-node[data-plan="new"]:not([data-tm-delta])::after { content: "Plan: new"; }
382
+ .tm-diagram .tm-node[data-plan="change"]:not([data-tm-delta])::after { content: "Plan: edit"; }
383
+ .tm-diagram .tm-node[data-plan="change"][data-plan-revised]:not([data-tm-delta])::after { content: "Plan: edit, revised"; background: var(--dg-mark); }
384
+ .tm-diagram .tm-node[data-plan="new"][data-plan-revised]:not([data-tm-delta])::after { content: "Plan: new, revised"; background: var(--dg-mark); }
385
+ .tm-dg-label[data-step]::before { content: attr(data-step); display: inline-block; width: 15px; height: 15px; margin: 0 5px 0 -2px; border-radius: 50%; background: var(--dg-ink); color: var(--dg-bg); font: 600 10px/15px var(--dg-font); text-align: center; vertical-align: 1px; }
386
+ .tm-diagram .tm-node[data-plan="remove"]:not([data-tm-delta])::after { content: "Plan: remove"; }
387
+ html[data-tm-changes] .tm-diagram .tm-node[data-plan]:not([data-tm-delta])::after { display: none; }
388
+ html[data-tm-changes] .tm-diagram .tm-node[data-plan="change"]:not([data-tm-change]) { box-shadow: none; }
389
+ html[data-tm-plan]:not([data-tm-changes]) .tm-diagram .tm-node:not([data-plan]) .tm-dg-name { color: var(--dg-muted); }
390
+ .tm-dg-edge.is-plan { stroke: var(--dg-ink); stroke-dasharray: 4 3; }
391
+ .tm-dg-head.is-plan { fill: var(--dg-ink); }
392
+ /* the box whose inspector is open */
393
+ .tm-diagram .tm-node[data-tm-selected] { border-color: var(--dg-ink); box-shadow: 0 0 0 3px var(--dg-bg), 0 0 0 5px var(--dg-ink); }
394
+ .tm-dg-probe { position: absolute; visibility: hidden; transform: none; }
395
+ /* flows: tabs, a one-line note, numbered steps */
396
+ .tm-dg-tabs { display: flex; flex-wrap: wrap; gap: 4px; margin: 0 0 12px; }
397
+ .tm-dg-tab { font: 500 13px/1 var(--dg-font); color: var(--dg-muted); background: none; border: 0; border-radius: 6px; padding: 7px 10px; cursor: pointer; }
398
+ .tm-dg-tab:hover { color: var(--dg-ink); background: var(--dg-surface); }
399
+ .tm-dg-tab[aria-selected="true"] { color: var(--dg-bg); background: var(--dg-ink); }
400
+ .tm-dg-tab[aria-selected="true"]::after { content: "×"; margin-left: 8px; font-weight: 400; opacity: .75; }
401
+ .tm-dg-note { margin: -4px 0 10px; font-size: 14px; color: var(--dg-text); max-width: 72ch; }
402
+ .tm-diagram[data-flow] .tm-node:not([data-in-flow]) .tm-dg-name, .tm-diagram[data-flow] .tm-node:not([data-in-flow]) .tm-dg-tag { color: var(--dg-line-strong); }
403
+ .tm-diagram[data-flow] .tm-node[data-in-flow] { border-color: var(--dg-ink); }
404
+ .tm-diagram[data-flow] .tm-dg-edge:not(.is-flow) { stroke: var(--dg-line); }
405
+ .tm-diagram[data-flow] .tm-dg-head:not(.is-flow) { fill: var(--dg-line); }
406
+ .tm-diagram[data-flow] .tm-dg-label:not(.is-flow) { color: var(--dg-line-strong); }
407
+ .tm-dg-step { position: absolute; z-index: 4; transform: translate(-50%, -50%); width: 18px; height: 18px; border-radius: 50%; background: var(--dg-ink); color: var(--dg-bg); font: 600 10.5px/18px var(--dg-font); text-align: center; }
408
+ /* the agent points here: a highlighter, not a colour code */
409
+ .tm-diagram .tm-node[data-tm-focus] { background: var(--dg-mark); border-color: var(--dg-ink); }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "truemap-cli",
3
- "version": "0.3.0",
3
+ "version": "0.5.0",
4
4
  "description": "Agents explain your project with living HTML pages that stay true to the code. Click, ask, and decide right on the page.",
5
5
  "repository": {
6
6
  "type": "git",
@@ -1,21 +1,25 @@
1
1
  ---
2
2
  name: truemap
3
- description: Explain a codebase with a living map in HTML that the user can comment on, ask about, and decide on. Use when explaining architecture, a module, a flow, or a data model; when comparing options or needing the user to decide; when asked "how does X work" or "show me the project"; and whenever a .truemap/ folder exists and you are about to explain something it may already cover. Not for one-line answers.
3
+ description: Review what you plan and what you changed on a living map of the codebase that stays true to the code. Use before a change that touches 3+ parts or adds one (show the plan, wait for approval), after editing code (show what changed, by box), when explaining architecture, a module or a flow, when asked "how does X work" or "show me the project", and whenever a .truemap/ folder exists and you are about to explain something it may already cover. Not for one-line answers.
4
4
  allowed-tools: Bash(npx -y truemap-cli:*), Bash(npx truemap-cli:*), Bash(truemap:*)
5
5
  license: MIT
6
6
  ---
7
7
 
8
8
  # truemap
9
9
 
10
- Pages live in `.truemap/` at the repo root (`index.html` is the project blueprint). They stay with the project and are checked against the code.
10
+ Pages live in `.truemap/` at the repo root (`index.html` is the project map). They stay with the project and are checked against the code.
11
11
 
12
12
  Current instructions live in the CLI – this file stays short so it never goes stale:
13
13
 
14
14
  - `npx -y truemap-cli --help` – commands and the chat loop
15
- - `npx -y truemap-cli outline` – a fast repo outline for the first blueprint
16
- - `npx -y truemap-cli guide` – how to write pages: the map, `data-src` anchors, page kit, decision forms
15
+ - `npx -y truemap-cli outline` – a fast repo outline for the first map
16
+ - `npx -y truemap-cli guide` – how to write maps, plans and anchors
17
+
18
+ Flow:
19
+ - Explaining: look in `.truemap/` first, update or write the page, run `npx -y truemap-cli <page>`, then follow the `next_step` it prints.
20
+ - Before a larger change: `npx -y truemap-cli plan --file plan.json`, wait for the approval.
21
+ - After editing code: `npx -y truemap-cli changes`.
17
22
 
18
- Flow: look in `.truemap/` first, update or write the page, run `npx -y truemap-cli <page>` (add `--annotate` when you want the user's review), then follow the `next_step` it prints.
19
23
  Always also give the user a 1–3 line answer in the terminal.
20
24
 
21
25
  ## Request
package/src/changes.js ADDED
@@ -0,0 +1,155 @@
1
+ // Change review: what changed since a base, attributed to the boxes on the pages.
2
+ // Attribution is by file: a box owns the file (or folder) its data-src names. Two boxes on one file
3
+ // both show that file's change, and say so.
4
+ //
5
+ // Bases:
6
+ // turn – the working tree when the agent last picked up a message (its turn began)
7
+ // plan – the working tree when the user approved the agent's plan
8
+ // head – the last commit (uncommitted changes)
9
+ // main – where this branch left the default branch
10
+ // Snapshots are git tree objects written through a throwaway copy of the index, so the user's staging
11
+ // area is never touched. Files under .truemap/ are pages, not code, and are left out.
12
+ import { execFile } from 'node:child_process';
13
+ import { copyFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
14
+ import { tmpdir } from 'node:os';
15
+ import { join } from 'node:path';
16
+ import { FOLDER, gitExe } from './common.js';
17
+ import { extractAnchors, listPages, parseAnchor } from './check.js';
18
+
19
+ function git(root, args, env) {
20
+ const exe = gitExe();
21
+ if (!exe) return Promise.resolve(null);
22
+ return new Promise((ok) => {
23
+ execFile(exe, args, { cwd: root, env: env || process.env, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true }, (err, out) => ok(err ? null : out));
24
+ });
25
+ }
26
+
27
+ /** A tree object for the working tree as it is now (tracked and untracked files, .gitignore honoured). */
28
+ export async function snapshotTree(root) {
29
+ const dir = mkdtempSync(join(tmpdir(), 'truemap-idx-'));
30
+ const index = join(dir, 'index');
31
+ const env = { ...process.env, GIT_INDEX_FILE: index };
32
+ try {
33
+ // Start from a copy of the real index: its stat cache means only changed files are hashed again.
34
+ const real = (await git(root, ['rev-parse', '--path-format=absolute', '--git-path', 'index']))?.trim();
35
+ try { if (real) copyFileSync(real, index); } catch { /* a repo without an index yet */ }
36
+ if (await git(root, ['add', '-A', '--', '.', `:(exclude)${FOLDER}`], env) === null) return null;
37
+ return (await git(root, ['write-tree'], env))?.trim() || null;
38
+ } finally { rmSync(dir, { recursive: true, force: true }); }
39
+ }
40
+
41
+ /** The default branch this branch started from, as a commit. */
42
+ async function mainBase(root) {
43
+ const head = (await git(root, ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD']))?.trim();
44
+ const candidates = [head, 'origin/main', 'origin/master', 'main', 'master'].filter(Boolean);
45
+ for (const ref of candidates) {
46
+ const mb = (await git(root, ['merge-base', 'HEAD', ref]))?.trim();
47
+ if (mb) return { commit: mb, ref: ref.replace(/^origin\//, '') };
48
+ }
49
+ return null;
50
+ }
51
+
52
+ export async function resolveBase(root, kind, snapshots = {}) {
53
+ const want = kind && kind !== 'auto' ? kind : snapshots.plan ? 'plan' : snapshots.turn ? 'turn' : 'head';
54
+ if (want === 'plan' && snapshots.plan) {
55
+ const end = snapshots.planEnd?.slug === snapshots.plan.slug ? snapshots.planEnd : null;
56
+ return { kind: 'plan', tree: snapshots.plan.tree, to: end?.tree, at: snapshots.plan.at, label: end ? 'What was done for the plan' : 'Since you approved the plan' };
57
+ }
58
+ if (want === 'turn' && snapshots.turn) return { kind: 'turn', tree: snapshots.turn.tree, at: snapshots.turn.at, label: 'Since the agent’s last turn began' };
59
+ if (want === 'main') {
60
+ const m = await mainBase(root);
61
+ if (m) return { kind: 'main', tree: `${m.commit}^{tree}`, label: `This branch vs ${m.ref}` };
62
+ }
63
+ const head = (await git(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{tree}']))?.trim();
64
+ return head ? { kind: 'head', tree: head, label: 'Uncommitted changes' } : null;
65
+ }
66
+
67
+ /** Changed files between two trees: [{ path, add, del, status }] (binary files have add/del null). */
68
+ async function diffFiles(root, from, to) {
69
+ const num = await git(root, ['diff', '--no-renames', '--numstat', '-z', from, to, '--', '.', `:(exclude)${FOLDER}`]);
70
+ const names = await git(root, ['diff', '--no-renames', '--name-status', '-z', from, to, '--', '.', `:(exclude)${FOLDER}`]);
71
+ if (num === null || names === null) return null;
72
+ const status = new Map();
73
+ const ns = names.split('\0');
74
+ for (let i = 0; i + 1 < ns.length; i += 2) if (ns[i]) status.set(ns[i + 1], ns[i][0]);
75
+ const out = [];
76
+ for (const rec of num.split('\0')) {
77
+ const m = rec.match(/^(-|\d+)\t(-|\d+)\t(.+)$/s);
78
+ if (!m) continue;
79
+ out.push({ path: m[3], add: m[1] === '-' ? null : +m[1], del: m[2] === '-' ? null : +m[2], status: status.get(m[3]) || 'M' });
80
+ }
81
+ return out;
82
+ }
83
+
84
+ const anchorCovers = (anchorPath, file) => {
85
+ const a = anchorPath.replace(/\/+$/, '');
86
+ return file === a || file.startsWith(`${a}/`);
87
+ };
88
+
89
+ /** Boxes (by data-src) that cover each changed file, per page; files no page covers, grouped by folder. */
90
+ export function attribute(root, files) {
91
+ const pages = listPages(root);
92
+ const anchors = []; // { page, src, path }
93
+ for (const { page } of pages) {
94
+ let html = '';
95
+ try { html = readFileSync(join(root, FOLDER, page), 'utf8'); } catch { continue; }
96
+ for (const src of extractAnchors(html)) {
97
+ const { path } = parseAnchor(src);
98
+ if (path) anchors.push({ page, src, path, own: true });
99
+ }
100
+ // data-also="server/db.ts server/hub.ts": more files a box owns (its migration, its wiring)
101
+ for (const m of html.matchAll(/<[^>]*\sdata-src\s*=\s*["']([^"']+)["'][^>]*>/gi)) {
102
+ const also = m[0].match(/\sdata-also\s*=\s*["']([^"']*)["']/i)?.[1];
103
+ for (const p of (also || '').split(/[\s,]+/).filter(Boolean)) anchors.push({ page, src: m[1], path: p.replace(/^\.?\//, '') });
104
+ }
105
+ }
106
+ const boxes = new Map(); // src -> { src, pages:Set, files:[] }
107
+ const unmapped = [];
108
+ for (const f of files) {
109
+ const hits = anchors.filter((a) => anchorCovers(a.path, f.path));
110
+ if (!hits.length) { unmapped.push(f); continue; }
111
+ const srcs = [...new Set(hits.map((h) => h.src))];
112
+ for (const h of hits) {
113
+ if (!boxes.has(h.src)) boxes.set(h.src, { src: h.src, pages: new Set(), files: [] });
114
+ const b = boxes.get(h.src); b.pages.add(h.page);
115
+ if (!b.files.some((x) => x.path === f.path)) b.files.push({ ...f, shared: srcs.length - 1, own: !!h.own || hits.some((x) => x.src === h.src && x.own) });
116
+ }
117
+ }
118
+ const sum = (list, k) => list.reduce((n, f) => n + (f[k] || 0), 0);
119
+ const boxList = [...boxes.values()].map((b) => ({ src: b.src, pages: [...b.pages], files: b.files, add: sum(b.files, 'add'), del: sum(b.files, 'del') }))
120
+ .sort((a, b) => (b.add + b.del) - (a.add + a.del));
121
+ const folders = new Map();
122
+ const dirOf = (p) => p.replace(/\/?[^/]*$/, '');
123
+ for (const f of unmapped) {
124
+ // a file in the same folder as a box's file is probably part of it: say so
125
+ const near = [...new Set(anchors.filter((a) => dirOf(a.path) === dirOf(f.path) && a.path.includes('.')).map((a) => a.src))];
126
+ if (near.length && near.length <= 2) f.near = near; // in a flat folder every box is a neighbour: no hint
127
+ const parts = f.path.split('/');
128
+ const key = parts.length > 2 ? `${parts.slice(0, 2).join('/')}/` : parts.length === 2 ? `${parts[0]}/` : '(top level)';
129
+ if (!folders.has(key)) folders.set(key, []);
130
+ folders.get(key).push(f);
131
+ }
132
+ return { boxes: boxList, unmapped: [...folders.entries()].map(([folder, list]) => ({ folder, files: list })), pagesWithAnchors: pages.length };
133
+ }
134
+
135
+ /** Everything the Changes view needs. */
136
+ export async function changes(root, kind, snapshots) {
137
+ const base = await resolveBase(root, kind, snapshots);
138
+ if (!base) return { error: 'not a git repository, or no commits yet' };
139
+ const now = base.to || await snapshotTree(root);
140
+ if (!now) return { error: 'could not read the working tree' };
141
+ const files = await diffFiles(root, base.tree, now);
142
+ if (!files) return { error: 'git diff failed' };
143
+ const bases = [snapshots.plan && 'plan', snapshots.turn && 'turn', 'head', 'main'].filter(Boolean);
144
+ return { base: { kind: base.kind, label: base.label, at: base.at || null }, bases, files_list: files.map((x) => ({ path: x.path })), files: files.length, add: files.reduce((n, f) => n + (f.add || 0), 0), del: files.reduce((n, f) => n + (f.del || 0), 0), ...attribute(root, files), now };
145
+ }
146
+
147
+ /** The unified diff of one file against the base (cut at 200 KB). */
148
+ export async function fileDiff(root, kind, snapshots, path) {
149
+ const base = await resolveBase(root, kind, snapshots);
150
+ if (!base) return { error: 'no base' };
151
+ const now = base.to || await snapshotTree(root);
152
+ const text = await git(root, ['diff', '--no-renames', '--no-color', '-U3', base.tree, now, '--', path]);
153
+ if (text === null) return { error: 'git diff failed' };
154
+ return { path, text: text.length > 200_000 ? `${text.slice(0, 200_000)}\n… (cut)` : text };
155
+ }