truemap-cli 0.5.1 → 0.5.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -20,6 +20,7 @@ Coding agents write code faster than anyone can read it. Review is the bottlenec
20
20
  - **Many projects.** Every project with truemap running is one click away, and the tab tells you when another one needs you (a plan to review, a new reply).
21
21
  - **Any agent.** Claude Code, Codex, OpenCode, Cursor CLI, or agents inside hosts such as T3 Code: anything that can run a shell command.
22
22
  - **It stays in the repo.** Maps live in `.truemap/`. Plain HTML files you commit, diff and share.
23
+ - **Your look.** Light, dark or follow the system. Ask the agent for other colours or fonts ("a blue accent", "like our brand"): it writes `.truemap/assets/theme.css`, every page and the workspace follow, and `truemap theme` checks that everything stays readable.
23
24
 
24
25
  ## Install
25
26
 
package/kit/tokens.css ADDED
@@ -0,0 +1,67 @@
1
+ /* truemap tokens: every colour and font the pages and the workspace use. truemap serves them first, then
2
+ .truemap/assets/theme.css, so a project (or its user) can restyle everything by overriding these. */
3
+
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"); }
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. */
12
+ :root {
13
+ --tm-paper: #ffffff; /* page background */
14
+ --tm-sheet: #ffffff; /* boxes on the map */
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-wire: #989892; /* wires at rest: about 2.6:1 on a group, 2.9:1 on the page; the main path is ink */
23
+ --tm-accent: #141413; /* the primary action; the project's own colour when truemap finds one */
24
+ --tm-accent-text: #ffffff; /* text on the accent */
25
+ --tm-chrome: #fafaf9; /* the workspace bars and panel */
26
+ --tm-mark: #ffe27a; /* the agent points here */
27
+ --tm-route: var(--tm-ink); /* v0.4 name for the key path and links */
28
+ --tm-route-ink: var(--tm-ink);
29
+ --tm-route-wash: #f2f2ef;
30
+ --tm-action: var(--tm-accent);
31
+ --tm-changed: #a35f00;
32
+ --tm-changed-wash: #fbf1df;
33
+ --tm-broken: #c0392b;
34
+ --tm-broken-wash: #fbe9e6;
35
+ --tm-fine: #2f7a4f;
36
+ --tm-fine-wash: #e6f1ea;
37
+ --tm-radius: 8px;
38
+ --tm-font: "Instrument Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
39
+ --tm-code: "Commit Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
40
+ color-scheme: light dark;
41
+ }
42
+
43
+ @media (prefers-color-scheme: dark) {
44
+ :root {
45
+ --tm-paper: #161615;
46
+ --tm-sheet: #161615;
47
+ --tm-wash: #222220;
48
+ --tm-ink: #f2f2ee;
49
+ --tm-text: #dadad4;
50
+ --tm-graphite: #a0a098;
51
+ --tm-pencil: #75756e;
52
+ --tm-rule: #2f2f2c;
53
+ --tm-rule-strong: #44443f;
54
+ --tm-wire: #62625c;
55
+ --tm-accent: #f2f2ee;
56
+ --tm-accent-text: #141413;
57
+ --tm-chrome: #1b1b1a;
58
+ --tm-mark: #6b5a12;
59
+ --tm-route-wash: #222220;
60
+ --tm-changed: #e0a548;
61
+ --tm-changed-wash: #2c2414;
62
+ --tm-broken: #ef8574;
63
+ --tm-broken-wash: #321b18;
64
+ --tm-fine: #7cc49c;
65
+ --tm-fine-wash: #16271e;
66
+ }
67
+ }
package/kit/truemap.css CHANGED
@@ -1,64 +1,5 @@
1
- /* truemap page kit. truemap serves this file to every page in .truemap/ (assets/truemap.css).
2
- To match a project's own look, put token overrides in .truemap/assets/theme.css – truemap appends it here. */
3
-
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"); }
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. */
12
- :root {
13
- --tm-paper: #ffffff; /* page background */
14
- --tm-sheet: #ffffff; /* boxes on the map */
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;
37
- color-scheme: light dark;
38
- }
39
-
40
- @media (prefers-color-scheme: dark) {
41
- :root {
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;
55
- --tm-changed-wash: #2c2414;
56
- --tm-broken: #ef8574;
57
- --tm-broken-wash: #321b18;
58
- --tm-fine: #7cc49c;
59
- --tm-fine-wash: #16271e;
60
- }
61
- }
1
+ /* truemap page kit: the components. Colours and fonts come from kit/tokens.css (served first) and
2
+ .truemap/assets/theme.css (served last). */
62
3
 
63
4
  /* ---------- base ---------- */
64
5
  *, *::before, *::after { box-sizing: border-box; }
@@ -148,10 +89,10 @@ html[style*="--tm-vw"] .tm-map, html[style*="--tm-vw"] .tm-blueprint { width: ca
148
89
  /* Wires (drawn by truemap into svg.tm-wires) */
149
90
  .tm-wires { position: absolute; top: 0; left: 0; max-width: none; pointer-events: none; overflow: visible; z-index: 0; }
150
91
  /* 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; }
92
+ .tm-wire { fill: none; stroke: var(--tm-wire, var(--tm-rule-strong)); stroke-width: 1.25; }
152
93
  .tm-wire.is-key { stroke: var(--tm-route); stroke-width: 2; }
153
94
  .tm-wire.is-ext { stroke-dasharray: 4 4; }
154
- .tm-wire-head { fill: var(--tm-rule-strong); }
95
+ .tm-wire-head { fill: var(--tm-wire, var(--tm-rule-strong)); }
155
96
  .tm-wire-head.is-key { fill: var(--tm-route); }
156
97
  /* Labels: the main path's always show; any other wire's label shows when its box is hovered or its path is lit. */
157
98
  .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; }
@@ -181,8 +122,8 @@ html[data-tm-focusing] .tm-wire-label:not(.is-focus) { opacity: 0; }
181
122
  .tm-legend { display: flex; flex-wrap: wrap; gap: 6px 22px; margin: 22px 0 0 132px; font-size: 13px; color: var(--tm-graphite); }
182
123
  .tm-legend span { display: inline-flex; align-items: center; gap: 8px; }
183
124
  .tm-legend i { display: inline-block; width: 22px; height: 0; border-top: 2px solid var(--tm-route); }
184
- .tm-legend i.is-wire { border-top: 1.5px solid var(--tm-rule-strong); }
185
- .tm-legend i.is-ext { border-top: 1.5px dashed var(--tm-rule-strong); }
125
+ .tm-legend i.is-wire { border-top: 1.5px solid var(--tm-wire, var(--tm-rule-strong)); }
126
+ .tm-legend i.is-ext { border-top: 1.5px dashed var(--tm-wire, var(--tm-rule-strong)); }
186
127
  .tm-legend span:has(> i.is-mark) { display: none; } /* older pages: the corner mark is gone */
187
128
 
188
129
  /* ---------- flow: a real sequence ---------- */
@@ -238,7 +179,7 @@ html[data-tm-focusing] .tm-wire-label:not(.is-focus) { opacity: 0; }
238
179
  .tm-badge.is-bad { background: var(--tm-broken-wash); color: var(--tm-broken); }
239
180
 
240
181
  code, kbd, samp { font-family: var(--tm-code); font-size: 0.88em; }
241
- :not(pre) > code { background: var(--tm-wash); color: var(--tm-ink); padding: 1px 5px; border-radius: 4px; }
182
+ :not(pre) > code { background: var(--tm-wash); color: var(--tm-ink); padding: 1px 5px; border-radius: 4px; overflow-wrap: anywhere; }
242
183
  pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background: var(--tm-sheet); color: var(--tm-text); border: 1px solid var(--tm-rule); border-radius: var(--tm-radius); padding: 14px 16px; overflow-x: auto; margin: 18px 0; max-width: 100%; }
243
184
  .tm-path { font-family: var(--tm-code); font-size: 12.5px; color: var(--tm-graphite); }
244
185
 
@@ -282,7 +223,7 @@ pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background
282
223
  .tm-option:has(input:checked) { border-color: var(--tm-route); background: var(--tm-route-wash); }
283
224
  .tm-ask textarea { width: 100%; min-height: 64px; resize: vertical; font: 14.5px/1.5 var(--tm-font); color: var(--tm-text); background: var(--tm-paper); border: 1px solid var(--tm-rule); border-radius: var(--tm-radius); padding: 10px 12px; }
284
225
  .tm-ask textarea:focus { outline: none; border-color: var(--tm-route); }
285
- .tm-btn { display: inline-flex; align-items: center; gap: 8px; margin-top: 14px; font: 500 14.5px/1 var(--tm-font); padding: 11px 18px; border-radius: var(--tm-radius); border: 1px solid var(--tm-action); background: var(--tm-action); color: #fff; cursor: pointer; }
226
+ .tm-btn { display: inline-flex; align-items: center; gap: 8px; margin-top: 14px; font: 500 14.5px/1 var(--tm-font); padding: 11px 18px; border-radius: var(--tm-radius); border: 1px solid var(--tm-action); background: var(--tm-action); color: var(--tm-accent-text); cursor: pointer; }
286
227
  .tm-btn:hover { filter: brightness(0.92); }
287
228
  .tm-btn.is-quiet { background: transparent; color: var(--tm-route); }
288
229
  [data-tm-sent] .tm-btn { background: var(--tm-wash); border-color: var(--tm-rule); color: var(--tm-graphite); cursor: default; }
@@ -314,6 +255,7 @@ pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background
314
255
  /* ===================== diagrams (v0.5): small nodes in groups, laid out left to right ===================== */
315
256
  .tm-diagram {
316
257
  --dg-bg: var(--tm-paper); --dg-surface: var(--tm-wash); --dg-line: var(--tm-rule); --dg-line-strong: var(--tm-rule-strong);
258
+ --dg-wire: var(--tm-wire, var(--tm-rule-strong));
317
259
  --dg-muted: var(--tm-graphite); --dg-text: var(--tm-text); --dg-ink: var(--tm-ink); --dg-mark: var(--tm-mark);
318
260
  --dg-font: var(--tm-font); --dg-code: var(--tm-code);
319
261
  position: relative; margin: 20px 0 8px; font-family: var(--dg-font);
@@ -338,18 +280,26 @@ pre { font-family: var(--tm-code); font-size: 13px; line-height: 1.6; background
338
280
  .tm-diagram .tm-node.is-ext { background: var(--dg-bg); border-style: dashed; border-color: var(--dg-line-strong); }
339
281
  .tm-diagram .tm-node.is-ext .tm-dg-name { color: var(--dg-muted); }
340
282
  .tm-diagram .tm-detail { display: none; }
341
- .tm-dg-edge { fill: none; stroke: var(--dg-line-strong); stroke-width: 1.25; }
283
+ .tm-dg-edge { fill: none; stroke: var(--dg-wire); stroke-width: 1.25; }
342
284
  .tm-dg-edge.is-main { stroke: var(--dg-ink); stroke-width: 1.6; }
343
285
  .tm-dg-edge.is-ext { stroke-dasharray: 3 4; }
344
- .tm-dg-head { fill: var(--dg-line-strong); }
286
+ .tm-dg-head { fill: var(--dg-wire); }
345
287
  .tm-dg-head.is-main { fill: var(--dg-ink); }
346
288
  .tm-dg-edge.is-hot, .tm-dg-edge.is-flow { stroke: var(--dg-ink); stroke-width: 1.75; }
347
289
  .tm-dg-head.is-hot, .tm-dg-head.is-flow { fill: var(--dg-ink); }
348
290
  .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
291
  .tm-dg-group ~ .tm-dg-label { background: var(--dg-bg); }
350
292
  .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; }
293
+ /* at rest the main path says its verbs, and so does any other line whose label found a clean spot (is-rest);
294
+ a hovered or selected box, a lit path or a flow shows the rest, and then only its own lines speak */
295
+ .tm-dg-label:not(.is-main):not(.is-rest):not(.is-hot):not(.is-flow):not(.is-focus):not(.is-sel),
296
+ .tm-diagram[data-flow] .tm-dg-label.is-rest:not(.is-flow):not(.is-sel):not(.is-hot), html[data-tm-focusing] .tm-dg-label.is-rest:not(.is-focus):not(.is-sel):not(.is-hot),
297
+ html[data-tm-changes] .tm-dg-label.is-rest:not(.is-hot):not(.is-flow):not(.is-sel), .tm-dg-label.is-dup:not(.is-flow):not(.is-focus):not(.is-sel), .tm-dg-label.is-crowded:not(.is-hot):not(.is-flow):not(.is-focus):not(.is-sel) { visibility: hidden; }
298
+ /* own rule: a browser without :has() drops only this one */
299
+ .tm-diagram:has([data-tm-selected]) .tm-dg-label.is-rest:not(.is-sel):not(.is-hot) { visibility: hidden; }
300
+ /* one word said once for several edges carries a count at rest; a lit edge says only its own word */
301
+ .tm-dg-label[data-many]::after { content: attr(data-many); margin-left: .4em; }
302
+ .tm-dg-label.is-sel[data-many]::after, .tm-dg-label.is-flow[data-many]::after, .tm-dg-label.is-focus[data-many]::after { content: none; }
353
303
  .tm-dg-edge.is-sel { stroke: var(--dg-ink); stroke-width: 1.75; }
354
304
  .tm-dg-head.is-sel { fill: var(--dg-ink); }
355
305
  .tm-dg-label.is-sel { color: var(--dg-ink); }
@@ -377,7 +327,7 @@ html[data-tm-changes] .tm-node[data-tm-change]:not(.tm-diagram .tm-node) { outli
377
327
  .tm-diagram .tm-node[data-plan="new"] { border: 1.5px dashed var(--dg-ink); }
378
328
  .tm-diagram .tm-node[data-plan="change"] { border-color: var(--dg-ink); box-shadow: 0 0 0 1px var(--dg-ink); }
379
329
  .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; }
330
+ .tm-diagram .tm-node[data-plan]:not([data-tm-delta])::after { display: block; position: absolute; top: -14px; 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
331
  .tm-diagram .tm-node[data-plan="new"]:not([data-tm-delta])::after { content: "Plan: new"; }
382
332
  /* a draft sketching an idea: a proposed box, not a plan under review */
383
333
  .tm-diagram .tm-node[data-plan="new"]:not([data-ghost]):not([data-tm-delta])::after { content: "Proposed"; }
@@ -410,4 +360,4 @@ html[data-tm-plan]:not([data-tm-changes]) .tm-diagram .tm-node:not([data-plan])
410
360
  /* the agent points here: a highlighter, not a colour code */
411
361
  .tm-diagram .tm-node[data-tm-focus] { background: var(--dg-mark); border-color: var(--dg-ink); }
412
362
  /* a box whose code was created this turn */
413
- .tm-diagram .tm-node[data-tm-new][data-tm-delta]::after { background: var(--tm-fine); color: #fff; }
363
+ .tm-diagram .tm-node[data-tm-new][data-tm-delta]::after { background: var(--tm-fine); color: var(--tm-paper); }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "truemap-cli",
3
- "version": "0.5.1",
3
+ "version": "0.5.3",
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,6 +1,6 @@
1
1
  ---
2
2
  name: truemap
3
- description: Explain code on a page that opens in the user's browser instead of answering only in the terminal. Use this whenever the user asks you to explain, walk through or make clear any code, in any language ("how does X work", "explain X to me", "I don't get X"), even a single function or file; no project map is needed. Also use it before a change that touches 3+ parts (show the plan, wait for approval), after editing code (show what changed), and when asked to show the project. Skip it only for short factual answers (which file, which flag, yes or no).
3
+ description: Explain code on a page that opens in the user's browser instead of answering only in the terminal. Use this whenever the user asks you to explain or make clear any code, however it is phrased and in any language ("explain this", "can you just explain this", "how does X work", "what does this do", "walk me through", "break it down", "I don't get X"), even a single function or file; no project map is needed. Also use it before a change that touches 3+ parts (show the plan, wait for approval), after editing code (show what changed), and when asked to show the project. A question about what code does or how it works is a request to explain, not a short factual question. Skip it only for lookups (which file, which flag, yes or no).
4
4
  allowed-tools: Bash(npx -y truemap-cli:*), Bash(npx truemap-cli:*), Bash(truemap:*)
5
5
  license: MIT
6
6
  ---
@@ -16,7 +16,7 @@ Current instructions live in the CLI – this file stays short so it never goes
16
16
  - `npx -y truemap-cli guide` – how to write maps, plans and anchors
17
17
 
18
18
  Flow:
19
- - Explaining something, big or small (how X works, "explain this function", "I don't get this", an idea): `npx -y truemap-cli draft "<name>"`, write the page, open it with `npx -y truemap-cli drafts/<file>`; keep the chat answer to a line or two. No map is needed first, and don't build one unless asked.
19
+ - Explaining something, big or small (how X works, "explain this function", "I don't get this", an idea): `npx -y truemap-cli draft "<name>"`, show it in the form that makes it obvious (a traced example, a drawing, a timeline, a side-by-side, something to try; not necessarily a diagram, never a wall of text), open it with `npx -y truemap-cli drafts/<file>`; keep the chat answer to a line or two. No map is needed first, and don't build one unless asked.
20
20
  - The project map: `.truemap/index.html`; update it when the structure changes, run `npx -y truemap-cli <page>`, then follow the `next_step` it prints.
21
21
  - Before a larger change: `npx -y truemap-cli plan --file plan.json`, wait for the approval.
22
22
  - After editing code: `npx -y truemap-cli changes`.
package/src/changes.js CHANGED
@@ -14,7 +14,7 @@ import { copyFileSync, mkdtempSync, readFileSync, rmSync } from 'node:fs';
14
14
  import { tmpdir } from 'node:os';
15
15
  import { join } from 'node:path';
16
16
  import { FOLDER, gitExe } from './common.js';
17
- import { extractAnchors, listPages, parseAnchor } from './check.js';
17
+ import { anchorTags, attrOf, extractAnchors, listPages, parseAnchor } from './check.js';
18
18
 
19
19
  function git(root, args, env) {
20
20
  const exe = gitExe();
@@ -50,7 +50,9 @@ async function mainBase(root) {
50
50
  }
51
51
 
52
52
  export async function resolveBase(root, kind, snapshots = {}) {
53
- const want = kind && kind !== 'auto' ? kind : snapshots.plan ? 'plan' : snapshots.turn ? 'turn' : 'head';
53
+ // auto: the plan while it is being built and in the turn that closed it; after that, the turn
54
+ const closedEarlier = snapshots.plan && snapshots.planEnd?.slug === snapshots.plan.slug && snapshots.turn && snapshots.planEnd.at < snapshots.turn.at;
55
+ const want = kind && kind !== 'auto' ? kind : snapshots.plan && !closedEarlier ? 'plan' : snapshots.turn ? 'turn' : 'head';
54
56
  if (want === 'plan' && snapshots.plan) {
55
57
  const end = snapshots.planEnd?.slug === snapshots.plan.slug ? snapshots.planEnd : null;
56
58
  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' };
@@ -98,18 +100,18 @@ export function attribute(root, files) {
98
100
  if (path) anchors.push({ page, src, path, own: true });
99
101
  }
100
102
  // 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(/^\.?\//, '') });
103
+ for (const { tag, src } of anchorTags(html)) {
104
+ const also = attrOf(tag, 'data-also');
105
+ for (const p of (also || '').split(/[\s,]+/).filter(Boolean)) anchors.push({ page, src, path: p.replace(/^\.?\//, '') });
104
106
  }
105
107
  }
106
108
  const names = new Map();
107
109
  for (const { page } of pages) {
108
110
  let html = '';
109
111
  try { html = readFileSync(join(root, FOLDER, page), 'utf8'); } catch { continue; }
110
- for (const m of html.matchAll(/<[^>]*\sdata-src\s*=\s*["']([^"']+)["'][^>]*>/gi)) {
111
- const nm = m[0].match(/\sdata-name\s*=\s*["']([^"']+)["']/i)?.[1];
112
- if (nm && !names.has(m[1])) names.set(m[1], nm);
112
+ for (const { tag, src } of anchorTags(html)) {
113
+ const nm = attrOf(tag, 'data-name');
114
+ if (nm && !names.has(src)) names.set(src, nm);
113
115
  }
114
116
  }
115
117
  const boxes = new Map(); // src -> { src, pages:Set, files:[] }
package/src/check.js CHANGED
@@ -10,7 +10,6 @@ import { createHash } from 'node:crypto';
10
10
  import { FOLDER, gitExe, verifiedPath } from './common.js';
11
11
 
12
12
  const META_RE = /<meta\s+name=["']truemap-verified["']\s+content=["']([^"']*)["']\s*\/?>/i;
13
- const ANCHOR_RE = /\bdata-src\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
14
13
  const TITLE_RE = /<title[^>]*>([\s\S]*?)<\/title>/i;
15
14
  const MAX_SCAN_BYTES = 4 * 1024 * 1024;
16
15
 
@@ -69,13 +68,35 @@ function decodeEntities(s) {
69
68
  return s.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
70
69
  }
71
70
 
72
- export function extractAnchors(html) {
73
- const seen = new Set();
74
- for (const m of html.matchAll(ANCHOR_RE)) {
75
- const v = decodeEntities((m[1] ?? m[2] ?? '').trim());
76
- if (v) seen.add(v);
71
+ // Start tags of real elements only. Comments, raw text (script, style, textarea, title) and what is inside
72
+ // <pre> and <code> are text, and so is an escaped sample (&lt;div data-src=…&gt;): a draft that shows
73
+ // `data-src="src/server.js#start"` as an example must not be checked as an anchor.
74
+ const TAG_RE = /<[a-zA-Z][\w:-]*(?:[^>"']|"[^"]*"|'[^']*')*>/g;
75
+ const ATTR_RE = /\s([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
76
+ function elementTags(html) {
77
+ const text = html
78
+ .replace(/<!--[\s\S]*?(?:-->|$)/g, ' ')
79
+ .replace(/<(script|style|textarea|title|pre|code)\b((?:[^>"']|"[^"]*"|'[^']*')*)>[\s\S]*?<\/\1\s*>/gi, (_m, t, a) => `<${t}${a}>`);
80
+ return text.match(TAG_RE) || [];
81
+ }
82
+ export function attrOf(tag, name) {
83
+ const body = tag.replace(/^<[a-zA-Z][\w:-]*/, '');
84
+ for (const m of body.matchAll(ATTR_RE)) if (m[1].toLowerCase() === name) return decodeEntities(m[2] ?? m[3] ?? m[4] ?? '');
85
+ return null;
86
+ }
87
+
88
+ /** The start tags that carry a data-src, with that value: { tag, src }. */
89
+ export function anchorTags(html) {
90
+ const out = [];
91
+ for (const tag of elementTags(html)) {
92
+ const v = attrOf(tag, 'data-src');
93
+ if (v !== null && v.trim()) out.push({ tag, src: v.trim() });
77
94
  }
78
- return [...seen];
95
+ return out;
96
+ }
97
+
98
+ export function extractAnchors(html) {
99
+ return [...new Set(anchorTags(html).map((a) => a.src))];
79
100
  }
80
101
 
81
102
  export function parseAnchor(raw) {
@@ -283,6 +304,11 @@ export function checkLayout(html) {
283
304
  return notes.concat(lintDiagrams(html));
284
305
  }
285
306
 
307
+ // Most boxes one box may wire to. A map has 7-12 boxes; 5 targets is already half of a 10-box map and
308
+ // as many as a full group (5) holds. Past that the wires leave one side of the box together, their curves
309
+ // overlap into one bundle and their labels collide, so no single connection can be followed.
310
+ const MAX_FANOUT = 5;
311
+
286
312
  /** The rules of a v0.5 map (figure.tm-diagram), checked so a page that breaks them is told why. */
287
313
  export function lintDiagrams(html) {
288
314
  const notes = [];
@@ -300,6 +326,28 @@ export function lintDiagrams(html) {
300
326
  const label = sec[0].match(/data-label=["']([^"']+)/)?.[1] || 'a group';
301
327
  if (n > 5) notes.push(`${where}group "${label}" has ${n} boxes; keep a group to 5 or fewer (split it by responsibility) so it reads as one row.`);
302
328
  }
329
+ if (groups > 5) notes.push(`${where}${groups} groups; 3-5 read at a glance. Merge a small group into the neighbour with the same responsibility, or give a part its own page.`);
330
+ // Connections as the map draws them: data-to on a box, to another box on this map, once per pair.
331
+ const out = new Map(); const wired = new Set();
332
+ for (const t of nodes) {
333
+ const from = attr(t, 'id');
334
+ if (!from) continue;
335
+ const to = new Set((attr(t, 'data-to') || '').split(/[\s,]+/).filter(Boolean).map((s) => s.split(':')[0]).filter((x) => x !== from && ids.has(x)));
336
+ out.set(from, to);
337
+ if (to.size) wired.add(from);
338
+ for (const x of to) wired.add(x);
339
+ }
340
+ if (nodes.length > 1 && !wired.size) notes.push(`${where}no connections. Give each box data-to="id:verb" for what it calls or feeds.`);
341
+ else {
342
+ for (const t of nodes) {
343
+ const id = attr(t, 'id');
344
+ if (!id) continue;
345
+ const label = attr(t, 'data-name') || id;
346
+ if (!wired.has(id)) notes.push(`${where}box "${label}" has no connections, so it reads as clutter. Connect it (data-to on it or on what calls it), or fold it into a neighbour's .tm-detail.`);
347
+ const n = out.get(id)?.size || 0;
348
+ if (n > MAX_FANOUT) notes.push(`${where}box "${label}" has ${n} outgoing connections; past ${MAX_FANOUT} they merge into one bundle of lines. Keep the ones on the main paths and name the rest in its .tm-detail, or split the box by responsibility.`);
349
+ }
350
+ }
303
351
  const outside = body.replace(/<section\b[^>]*class=["'][^"']*\btm-group\b[\s\S]*?<\/section>/gi, '');
304
352
  const loose = (outside.match(/class=["'][^"']*\btm-node\b/gi) || []).length;
305
353
  if (groups && loose) notes.push(`${where}${loose} box(es) outside any group; every box belongs to one group.`);
@@ -312,7 +360,17 @@ export function lintDiagrams(html) {
312
360
  if (!attr(t, 'data-src') && !/\bis-ext\b/.test(attr(t, 'class') || '')) notes.push(`${where}box "${label}" has no data-src; anchor it to its code, or mark it is-ext if it is outside the code.`);
313
361
  }
314
362
  for (const m of body.matchAll(/<li\b[^>]*\sdata-path\s*=\s*["']([^"']*)["']/gi)) {
315
- for (const id of m[1].split(/[\s,]+/).filter(Boolean)) if (!ids.has(id)) notes.push(`${where}flow step "${id}" is not a box id on this map.`);
363
+ const path = m[1].split(/[\s,]+/).filter(Boolean);
364
+ for (const id of path) if (!ids.has(id)) notes.push(`${where}flow step "${id}" is not a box id on this map.`);
365
+ // A lit flow numbers the wire from each step to the next, in that direction only (diagram.js markFlow):
366
+ // a pair with no such wire shows no number and no line, and the flow reads as missing a step.
367
+ const name = body.slice(m.index + m[0].length).split(/<\/li>|<li\b/i)[0].replace(/^[^>]*>/, '').replace(/<[^>]+>/g, '').trim() || m[1];
368
+ path.forEach((a, i) => {
369
+ const b = path[i + 1];
370
+ if (!b || a === b || !ids.has(a) || !ids.has(b) || out.get(a)?.has(b)) return;
371
+ const back = out.get(b)?.has(a);
372
+ notes.push(`${where}flow "${name}": no wire from "${a}" to "${b}"${back ? ` (the wire goes from "${b}" to "${a}")` : ''}, so step ${i + 1} is not drawn. List the steps in the direction the wires point${back ? '' : `, or add data-to="${b}:…" on "${a}"`}.`);
373
+ });
316
374
  }
317
375
  });
318
376
  if (figs.length && /<style\b|\sstyle\s*=\s*["'][^"']*(?:color|background|font|border)/i.test(html)) notes.push('page sets its own colours or fonts; the look is fixed so every map reads the same. Remove <style> and style="…".');
package/src/cli.js CHANGED
@@ -9,7 +9,8 @@ import {
9
9
  } from './common.js';
10
10
  import { checkAll, listPages, markOk, pageInFolder } from './check.js';
11
11
  import { outline } from './outline.js';
12
- import { exportPage } from './export.js';
12
+ import { exportPage, tokensCss } from './export.js';
13
+ import { contrastNotes } from './contrast.js';
13
14
  import { writeFileSync } from 'node:fs';
14
15
 
15
16
  const CMD = process.env.TRUEMAP_CMD || 'npx -y truemap-cli';
@@ -123,6 +124,12 @@ function resolvePage(root, arg) {
123
124
  else if (existsSync(join(dir, arg))) candidate = arg;
124
125
  else if (existsSync(abs)) throw new Error(`${arg} is outside ${FOLDER}/. Save pages inside ${FOLDER}/ so they stay with the project.`);
125
126
  else candidate = arg.replace(new RegExp(`^${FOLDER}[\\\\/]`), '');
127
+ const byNum = candidate.match(/^drafts[\\/](\d{1,3})$/);
128
+ if (byNum) {
129
+ const want = byNum[1].padStart(3, '0');
130
+ const hit = (existsSync(join(dir, 'drafts')) ? readdirSync(join(dir, 'drafts')) : []).find((x) => x.startsWith(want + '-') && x.endsWith('.html'));
131
+ if (hit) candidate = `drafts/${hit}`;
132
+ }
126
133
  const rel = pageInFolder(root, candidate);
127
134
  if (!rel) throw new Error(`${arg} is outside ${FOLDER}/.`);
128
135
  return rel;
@@ -367,7 +374,7 @@ async function cmdChanges(root, args, opts) {
367
374
  for (const st of r.plan.steps || []) {
368
375
  const quiet = [...st.files.filter((x) => !x.changed).map((x) => x.path), ...st.boxes.filter((x) => !x.changed).map((x) => x.name)];
369
376
  out(` - step ${st.n}${st.report ? ` (you reported: ${st.report.status})` : ''}: ${q(st.text)}${quiet.length ? ` # names ${quiet.map(q).join(', ')} with no changes` : ''}`);
370
- if (st.conflict) out(` conflict: ${q(st.conflict)} # the user sees this at the top of the Changes view`);
377
+ if (st.conflict) out(` conflict: ${q(st.conflict)} # the user sees this in the conversation when the plan is closed`);
371
378
  if (st.rewritten) out(` report_history: ${q(st.rewritten)}`);
372
379
  }
373
380
  }
@@ -398,7 +405,7 @@ async function cmdPlan(root, args, opts) {
398
405
  out(`status: ${r.body.status}`);
399
406
  out(`plan: ${q(r.body.plan)}`);
400
407
  for (const st of r.body.check?.steps || []) {
401
- if (st.conflict) out(`conflict: step ${st.n}: ${q(st.conflict)} # shown to the user in the conversation and the Changes view`);
408
+ if (st.conflict) out(`conflict: step ${st.n}: ${q(st.conflict)} # shown to the user in the conversation`);
402
409
  if (st.rewritten) out(`report_history: step ${st.n}: ${q(st.rewritten)}`);
403
410
  }
404
411
  const missing = (r.body.check?.planned || []).filter((p) => !p.changed);
@@ -454,7 +461,8 @@ function cmdDraft(root, args, opts) {
454
461
  mkdirSync(dir, { recursive: true });
455
462
  const nums = readdirSync(dir).map((x) => parseInt(x, 10)).filter(Number.isFinite);
456
463
  const n = (nums.length ? Math.max(...nums) : 0) + 1;
457
- const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'draft';
464
+ // Letters and digits of any script, so a title in Japanese, Russian or Arabic still names its file.
465
+ const slug = [...name.normalize('NFC').toLowerCase().replace(/[^\p{L}\p{M}\p{N}]+/gu, '-').replace(/^-+|-+$/g, '')].slice(0, 48).join('').replace(/-+$/, '') || 'draft';
458
466
  const file = `drafts/${String(n).padStart(3, '0')}-${slug}.html`;
459
467
  const title = opts.title || name.replace(/^./, (c) => c.toUpperCase());
460
468
  const esc = (t) => String(t).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
@@ -469,11 +477,12 @@ function cmdDraft(root, args, opts) {
469
477
  <header class="tm-header">
470
478
  <nav class="tm-crumb">${hasMap ? '<a href="../index.html">Map</a> / ' : ''}Draft ${n}</nav>
471
479
  <h1 class="tm-title">${esc(title)}</h1>
472
- <p class="tm-lede">One or two sentences: what this draft explains or proposes.</p>
480
+ <p class="tm-lede">One sentence: what this shows.</p>
473
481
  </header>
482
+ <!-- Show it in the form that makes it obvious: a real example traced step by step, a drawing, a timeline,
483
+ options side by side, something to try, or the map component. Any HTML, inline SVG, <style>, <script>;
484
+ colours through var(--tm-…). Words only as captions. Write in the user's language and set <html lang> to match. -->
474
485
  <section class="tm-section">
475
- <h2>…</h2>
476
- <p>…</p>
477
486
  </section>
478
487
  </main></body>
479
488
  </html>
@@ -481,7 +490,7 @@ function cmdDraft(root, args, opts) {
481
490
  out('status: draft_created');
482
491
  out(`draft: ${q(file)} # .truemap/${file}`);
483
492
  block('next_step', [
484
- `Write the draft: replace the placeholder sections in .truemap/${file}. Free form: any mix of short text, a <figure class="tm-diagram"> (data-plan="new" draws a proposed box dashed), steps, a comparison table, a small interactive bit, or an <iframe> of the running dev server.${hasMap ? ' Link boxes on the map as <a href="../index.html#runs">Runs</a>.' : ' No map is needed for this.'}`,
493
+ `Write the draft in .truemap/${file}. Show it, don't write it: ask what would make this obvious at a glance and build that, in any form (a real input traced to its output, a drawing, a timeline, options side by side, something to try, the map component). No fixed sections; words only as captions. See \`${CMD} guide\`, DRAFTS.${hasMap ? ' Link boxes on the map as <a href="../index.html#runs">Runs</a>.' : ''}`,
485
494
  `Then show it: \`${CMD} ${file}\` (the user's tab switches to it and it is added to their drafts), and answer in one or two lines with \`${CMD} reply "…" --listen\` pointing to it.`,
486
495
  ].join('\n'));
487
496
  }
@@ -504,6 +513,8 @@ async function cmdCheck(root, args, opts) {
504
513
  }
505
514
  const pages = args.length ? args.map((a) => resolvePage(root, a)) : undefined;
506
515
  const { gitRepo, results } = checkAll(root, pages);
516
+ const live = await liveState(root);
517
+ if (live) await call(live, 'POST', '/api/check', {}).catch(() => {});
507
518
  out(`status: checked ${results.length} page(s)${gitRepo ? '' : ' (no git: only missing paths/names are checked)'}`);
508
519
  let changed = 0; let broken = 0; let wires = 0;
509
520
  for (const r of results) {
@@ -518,6 +529,9 @@ async function cmdCheck(root, args, opts) {
518
529
  if (wires) steps.push('Some map wires point at ids that are not on the page, so they are not drawn. Fix the data-to values (ids separated by spaces).');
519
530
  const layout = results.reduce((n, r) => n + (r.layout || []).length, 0);
520
531
  if (layout) steps.push('Map notes: fix each one; they are what keeps a map readable at a glance (see `' + CMD + ' guide`, THE MAP).');
532
+ const faint = contrastNotes(tokensCss(root));
533
+ for (const n of faint) out(`hard to read: ${n}`);
534
+ if (faint.length) steps.push(`The theme has colours that are hard to read (above): fix .truemap/assets/theme.css, then \`${CMD} theme\`.`);
521
535
  if (!broken && !changed && !wires && !layout) steps.push('All pages match the code.');
522
536
  block('next_step', steps.join('\n'));
523
537
  }
@@ -552,6 +566,22 @@ function cmdOutline(root) {
552
566
  block('next_step', `Read the manifests and entry points (not every file), then write ${FOLDER}/index.html with one <figure class="tm-diagram">: 3-5 groups by responsibility in the order a request travels, 7-12 small boxes (data-name, data-tag, data-src), data-to connections with a verb, 1-3 flows. Run \`${CMD} guide\` for the format if you have not.`);
553
567
  }
554
568
 
569
+ // The user's look: colours and fonts for every page and the workspace, kept in .truemap/assets/theme.css.
570
+ function cmdTheme(root) {
571
+ const file = join(root, FOLDER, 'assets', 'theme.css');
572
+ const has = existsSync(file);
573
+ out(`theme: ${has ? `${FOLDER}/assets/theme.css` : 'none (truemap defaults)'}`);
574
+ const notes = contrastNotes(tokensCss(root));
575
+ for (const n of notes) out(`hard to read: ${n}`);
576
+ block('next_step', [
577
+ has ? 'Edit .truemap/assets/theme.css to change the look.' : 'To change the look, create .truemap/assets/theme.css.',
578
+ 'Override --tm-* tokens in :root for light, and again inside @media (prefers-color-scheme: dark) { :root { … } } for dark. The tokens and their defaults: ' + join(PKG_DIR, 'kit', 'tokens.css'),
579
+ 'Colours and fonts only; never restyle components. Keep the three status colours (--tm-changed, --tm-broken, --tm-fine) easy to tell apart.',
580
+ 'Every open page and the workspace update by themselves. Run this command again to check contrast.',
581
+ notes.length ? 'Some colours are hard to read (above). Fix them, or tell the user which ones and let them decide.' : 'Contrast is fine in light and dark.',
582
+ ].join('\n'));
583
+ }
584
+
555
585
  function cmdGuide() {
556
586
  out(readFileSync(join(PKG_DIR, 'src', 'guide.md'), 'utf8').replaceAll('{{CMD}}', CMD));
557
587
  }
@@ -575,10 +605,11 @@ usage:
575
605
  ${CMD} ask "<question>" --option "A | why" --option "B | why"
576
606
  ask the user to choose, only when you are blocked on a real trade-off
577
607
  ${CMD} draft "<name>" a new numbered draft page that explains one thing (then open it with truemap <file>)
608
+ ${CMD} theme the user's colours and fonts (.truemap/assets/theme.css), with a contrast check
578
609
  ${CMD} plan --file plan.json before a change that touches 3+ boxes or adds one: show the plan on the map for review
579
610
  ${CMD} plan --approve|--done the user said "go" in the terminal / the plan is built
580
611
  ${CMD} changes [--base turn|plan|head|main]
581
- what changed, by box; opens the Changes view for the user
612
+ what changed, by box; one card per turn in the conversation
582
613
  ${CMD} progress "<text>" show a short status line in the chat while you work
583
614
  ${CMD} stop stop the background server
584
615
 
@@ -621,7 +652,7 @@ function parseArgs(argv) {
621
652
  export async function main(argv) {
622
653
  const { args, opts } = parseArgs(argv);
623
654
  if (opts.version) return out(VERSION);
624
- const commands = { listen: cmdListen, reply: cmdReply, check: cmdCheck, stop: cmdStop, guide: cmdGuide, progress: cmdProgress, outline: cmdOutline, export: cmdExport, show: cmdShow, ask: cmdAsk, changes: cmdChanges, plan: cmdPlan, draft: cmdDraft, help };
655
+ const commands = { listen: cmdListen, reply: cmdReply, check: cmdCheck, stop: cmdStop, guide: cmdGuide, progress: cmdProgress, outline: cmdOutline, export: cmdExport, show: cmdShow, ask: cmdAsk, changes: cmdChanges, plan: cmdPlan, draft: cmdDraft, theme: cmdTheme, help };
625
656
  const name = args[0] && commands[args[0]] ? args.shift() : null;
626
657
  if (opts.help || name === 'help') return help();
627
658
  const root = findRoot();