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 +1 -0
- package/kit/tokens.css +67 -0
- package/kit/truemap.css +23 -73
- package/package.json +1 -1
- package/skills/truemap/SKILL.md +2 -2
- package/src/changes.js +10 -8
- package/src/check.js +66 -8
- package/src/cli.js +41 -10
- package/src/contrast.js +93 -0
- package/src/export.js +12 -7
- package/src/guide.md +34 -9
- package/src/outline.js +7 -3
- package/src/server.js +81 -23
- package/src/theme.js +11 -10
- package/src/ui/diagram.js +139 -27
- package/src/ui/sdk.js +52 -55
- package/src/ui/workspace.css +19 -34
- package/src/ui/workspace.html +1 -0
- package/src/ui/workspace.js +61 -14
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
|
|
2
|
-
|
|
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:
|
|
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-
|
|
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-
|
|
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
|
|
352
|
-
|
|
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: -
|
|
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:
|
|
363
|
+
.tm-diagram .tm-node[data-tm-new][data-tm-delta]::after { background: var(--tm-fine); color: var(--tm-paper); }
|
package/package.json
CHANGED
package/skills/truemap/SKILL.md
CHANGED
|
@@ -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
|
|
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>"`,
|
|
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
|
-
|
|
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
|
|
102
|
-
const also =
|
|
103
|
-
for (const p of (also || '').split(/[\s,]+/).filter(Boolean)) anchors.push({ page, src
|
|
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
|
|
111
|
-
const nm =
|
|
112
|
-
if (nm && !names.has(
|
|
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(/&/g, '&').replace(/</g, '<').replace(/>/g, '>').replace(/"/g, '"').replace(/'/g, "'");
|
|
70
69
|
}
|
|
71
70
|
|
|
72
|
-
|
|
73
|
-
|
|
74
|
-
|
|
75
|
-
|
|
76
|
-
|
|
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 (<div data-src=…>): 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
|
|
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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) => ({ '&': '&', '<': '<', '>': '>', '"': '"' }[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
|
|
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
|
|
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;
|
|
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();
|