truemap-cli 0.5.0 → 0.5.2
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 +4 -3
- package/kit/tokens.css +65 -0
- package/kit/truemap.css +9 -64
- package/package.json +1 -1
- package/skills/truemap/SKILL.md +3 -2
- package/src/changes.js +10 -1
- package/src/check.js +4 -1
- package/src/cli.js +90 -9
- package/src/common.js +12 -1
- package/src/contrast.js +93 -0
- package/src/export.js +12 -7
- package/src/guide.md +55 -8
- package/src/plan.js +1 -1
- package/src/server.js +124 -25
- package/src/theme.js +47 -0
- package/src/ui/sdk.js +152 -54
- package/src/ui/workspace.css +58 -34
- package/src/ui/workspace.html +9 -6
- package/src/ui/workspace.js +148 -48
package/README.md
CHANGED
|
@@ -13,13 +13,14 @@ Your agent keeps a map of the project in your repo: small boxes in groups, each
|
|
|
13
13
|
Coding agents write code faster than anyone can read it. Review is the bottleneck, and a wall of text or a 40-file diff is the wrong place to do it.
|
|
14
14
|
|
|
15
15
|
- **Review the plan before the work.** For a change that touches several parts, the agent draws what it will add and touch on the map. Click a box to comment, then approve or ask for changes. The agent waits.
|
|
16
|
-
- **
|
|
16
|
+
- **See the change after the work.** When the agent finishes a turn, a card in the conversation lists the boxes it changed (+/- lines) and files no box covers; the changed boxes carry their lines on the map. Click one to see its diff, next to what the plan said.
|
|
17
17
|
- **Ask, and the answer points.** Answers come as short steps; each step lights up the boxes it is about. Escape or a click on empty space brings back the plain map.
|
|
18
|
-
- **Click
|
|
18
|
+
- **Click a box to follow it; double-click to comment.** A click lights its connections. A double-click opens a small card right there with what it is and a comment field; Details shows the real code, read live from your repo.
|
|
19
19
|
- **A map that stays true.** Every box carries a `data-src="path#name"` anchor. When that code changes or disappears, the box is marked and the agent fixes the map.
|
|
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
|
|
|
@@ -48,7 +49,7 @@ your repo/
|
|
|
48
49
|
| `npx -y truemap-cli [page]` | Opens the workspace in your browser, or switches the tab you already have open |
|
|
49
50
|
| `npx -y truemap-cli outline` | A compact outline of the repo, so the first map takes minutes |
|
|
50
51
|
| `npx -y truemap-cli plan --file plan.json` | Draws a plan on the map for review; `--approve` / `--done` from the terminal |
|
|
51
|
-
| `npx -y truemap-cli changes [--base head\|main]` | What changed, by box;
|
|
52
|
+
| `npx -y truemap-cli changes [--base head\|main]` | What changed, by box; also posted to the conversation after each turn |
|
|
52
53
|
| `npx -y truemap-cli listen` | Waits for your next message, comments or approval |
|
|
53
54
|
| `npx -y truemap-cli reply "…" --listen` | Shows the answer in the panel, then keeps listening |
|
|
54
55
|
| `npx -y truemap-cli show [page] --focus ids --note "…"` | Points at the map while explaining |
|
package/kit/tokens.css
ADDED
|
@@ -0,0 +1,65 @@
|
|
|
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-accent: #141413; /* the primary action; the project's own colour when truemap finds one */
|
|
23
|
+
--tm-accent-text: #ffffff; /* text on the accent */
|
|
24
|
+
--tm-chrome: #fafaf9; /* the workspace bars and panel */
|
|
25
|
+
--tm-mark: #ffe27a; /* the agent points here */
|
|
26
|
+
--tm-route: var(--tm-ink); /* v0.4 name for the key path and links */
|
|
27
|
+
--tm-route-ink: var(--tm-ink);
|
|
28
|
+
--tm-route-wash: #f2f2ef;
|
|
29
|
+
--tm-action: var(--tm-accent);
|
|
30
|
+
--tm-changed: #a35f00;
|
|
31
|
+
--tm-changed-wash: #fbf1df;
|
|
32
|
+
--tm-broken: #c0392b;
|
|
33
|
+
--tm-broken-wash: #fbe9e6;
|
|
34
|
+
--tm-fine: #2f7a4f;
|
|
35
|
+
--tm-fine-wash: #e6f1ea;
|
|
36
|
+
--tm-radius: 8px;
|
|
37
|
+
--tm-font: "Instrument Sans", system-ui, -apple-system, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
|
|
38
|
+
--tm-code: "Commit Mono", ui-monospace, "SF Mono", "Cascadia Mono", Consolas, monospace;
|
|
39
|
+
color-scheme: light dark;
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
@media (prefers-color-scheme: dark) {
|
|
43
|
+
:root {
|
|
44
|
+
--tm-paper: #161615;
|
|
45
|
+
--tm-sheet: #161615;
|
|
46
|
+
--tm-wash: #222220;
|
|
47
|
+
--tm-ink: #f2f2ee;
|
|
48
|
+
--tm-text: #dadad4;
|
|
49
|
+
--tm-graphite: #a0a098;
|
|
50
|
+
--tm-pencil: #75756e;
|
|
51
|
+
--tm-rule: #2f2f2c;
|
|
52
|
+
--tm-rule-strong: #44443f;
|
|
53
|
+
--tm-accent: #f2f2ee;
|
|
54
|
+
--tm-accent-text: #141413;
|
|
55
|
+
--tm-chrome: #1b1b1a;
|
|
56
|
+
--tm-mark: #6b5a12;
|
|
57
|
+
--tm-route-wash: #222220;
|
|
58
|
+
--tm-changed: #e0a548;
|
|
59
|
+
--tm-changed-wash: #2c2414;
|
|
60
|
+
--tm-broken: #ef8574;
|
|
61
|
+
--tm-broken-wash: #321b18;
|
|
62
|
+
--tm-fine: #7cc49c;
|
|
63
|
+
--tm-fine-wash: #16271e;
|
|
64
|
+
}
|
|
65
|
+
}
|
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; }
|
|
@@ -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; }
|
|
@@ -377,8 +318,10 @@ html[data-tm-changes] .tm-node[data-tm-change]:not(.tm-diagram .tm-node) { outli
|
|
|
377
318
|
.tm-diagram .tm-node[data-plan="new"] { border: 1.5px dashed var(--dg-ink); }
|
|
378
319
|
.tm-diagram .tm-node[data-plan="change"] { border-color: var(--dg-ink); box-shadow: 0 0 0 1px var(--dg-ink); }
|
|
379
320
|
.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: -
|
|
321
|
+
.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
322
|
.tm-diagram .tm-node[data-plan="new"]:not([data-tm-delta])::after { content: "Plan: new"; }
|
|
323
|
+
/* a draft sketching an idea: a proposed box, not a plan under review */
|
|
324
|
+
.tm-diagram .tm-node[data-plan="new"]:not([data-ghost]):not([data-tm-delta])::after { content: "Proposed"; }
|
|
382
325
|
.tm-diagram .tm-node[data-plan="change"]:not([data-tm-delta])::after { content: "Plan: edit"; }
|
|
383
326
|
.tm-diagram .tm-node[data-plan="change"][data-plan-revised]:not([data-tm-delta])::after { content: "Plan: edit, revised"; background: var(--dg-mark); }
|
|
384
327
|
.tm-diagram .tm-node[data-plan="new"][data-plan-revised]:not([data-tm-delta])::after { content: "Plan: new, revised"; background: var(--dg-mark); }
|
|
@@ -407,3 +350,5 @@ html[data-tm-plan]:not([data-tm-changes]) .tm-diagram .tm-node:not([data-plan])
|
|
|
407
350
|
.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
351
|
/* the agent points here: a highlighter, not a colour code */
|
|
409
352
|
.tm-diagram .tm-node[data-tm-focus] { background: var(--dg-mark); border-color: var(--dg-ink); }
|
|
353
|
+
/* a box whose code was created this turn */
|
|
354
|
+
.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:
|
|
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,8 @@ 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
|
|
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
|
+
- 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.
|
|
20
21
|
- Before a larger change: `npx -y truemap-cli plan --file plan.json`, wait for the approval.
|
|
21
22
|
- After editing code: `npx -y truemap-cli changes`.
|
|
22
23
|
|
package/src/changes.js
CHANGED
|
@@ -103,6 +103,15 @@ export function attribute(root, files) {
|
|
|
103
103
|
for (const p of (also || '').split(/[\s,]+/).filter(Boolean)) anchors.push({ page, src: m[1], path: p.replace(/^\.?\//, '') });
|
|
104
104
|
}
|
|
105
105
|
}
|
|
106
|
+
const names = new Map();
|
|
107
|
+
for (const { page } of pages) {
|
|
108
|
+
let html = '';
|
|
109
|
+
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);
|
|
113
|
+
}
|
|
114
|
+
}
|
|
106
115
|
const boxes = new Map(); // src -> { src, pages:Set, files:[] }
|
|
107
116
|
const unmapped = [];
|
|
108
117
|
for (const f of files) {
|
|
@@ -116,7 +125,7 @@ export function attribute(root, files) {
|
|
|
116
125
|
}
|
|
117
126
|
}
|
|
118
127
|
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') }))
|
|
128
|
+
const boxList = [...boxes.values()].map((b) => ({ src: b.src, name: names.get(b.src) || '', pages: [...b.pages], files: b.files, isNew: b.files.length > 0 && b.files.every((x) => x.status === 'A'), add: sum(b.files, 'add'), del: sum(b.files, 'del') }))
|
|
120
129
|
.sort((a, b) => (b.add + b.del) - (a.add + a.del));
|
|
121
130
|
const folders = new Map();
|
|
122
131
|
const dirOf = (p) => p.replace(/\/?[^/]*$/, '');
|
package/src/check.js
CHANGED
|
@@ -52,7 +52,10 @@ export function listPages(root) {
|
|
|
52
52
|
};
|
|
53
53
|
walk(base);
|
|
54
54
|
out.sort((a, b) => (a === 'index.html' ? -1 : b === 'index.html' ? 1 : a.localeCompare(b)));
|
|
55
|
-
return out.map((page) =>
|
|
55
|
+
return out.map((page) => {
|
|
56
|
+
let at = 0; try { const st = statSync(join(base, page)); at = Math.round(st.birthtimeMs || st.mtimeMs); } catch { /* gone */ }
|
|
57
|
+
return { page, title: readTitle(join(base, page)) || page.replace(/\.html?$/i, ''), at };
|
|
58
|
+
});
|
|
56
59
|
}
|
|
57
60
|
|
|
58
61
|
function readTitle(file) {
|
package/src/cli.js
CHANGED
|
@@ -1,15 +1,16 @@
|
|
|
1
1
|
// truemap CLI. Output is plain YAML-ish text written for agents: what happened + next_step.
|
|
2
2
|
import { spawn } from 'node:child_process';
|
|
3
|
-
import { closeSync, existsSync, mkdirSync, openSync, readFileSync, rmSync, statSync } from 'node:fs';
|
|
3
|
+
import { closeSync, existsSync, mkdirSync, openSync, readFileSync, readdirSync, rmSync, statSync } from 'node:fs';
|
|
4
4
|
import { request as httpRequest } from 'node:http';
|
|
5
5
|
import { isAbsolute, join, relative, resolve, sep } from 'node:path';
|
|
6
6
|
import {
|
|
7
|
-
FOLDER, IS_WIN, PKG_DIR, VERSION, detectAgent, findRoot, folderPath, logUsage, readJson,
|
|
7
|
+
FOLDER, IS_WIN, PKG_DIR, VERSION, buildId, detectAgent, findRoot, folderPath, logUsage, readJson,
|
|
8
8
|
samePath, serverLockPath, serverStatePath,
|
|
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';
|
|
@@ -58,9 +59,10 @@ async function liveState(root) {
|
|
|
58
59
|
|
|
59
60
|
async function ensureServer(root) {
|
|
60
61
|
let state = await liveState(root);
|
|
61
|
-
if (state && state.version !== VERSION) {
|
|
62
|
-
|
|
63
|
-
await
|
|
62
|
+
if (state && (state.version !== VERSION || (state.build && state.build !== buildId()) || !state.build)) {
|
|
63
|
+
// Older code: restart on the same address; the open tab reconnects and reloads itself.
|
|
64
|
+
try { await call(state, 'POST', '/api/agent/shutdown', { restart: true }, { timeoutMs: 1500 }); } catch { /* ignore */ }
|
|
65
|
+
for (let i = 0; i < 30; i++) { await sleep(100); try { process.kill(state.pid, 0); } catch { break; } }
|
|
64
66
|
state = null;
|
|
65
67
|
}
|
|
66
68
|
if (state) return state;
|
|
@@ -122,6 +124,12 @@ function resolvePage(root, arg) {
|
|
|
122
124
|
else if (existsSync(join(dir, arg))) candidate = arg;
|
|
123
125
|
else if (existsSync(abs)) throw new Error(`${arg} is outside ${FOLDER}/. Save pages inside ${FOLDER}/ so they stay with the project.`);
|
|
124
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
|
+
}
|
|
125
133
|
const rel = pageInFolder(root, candidate);
|
|
126
134
|
if (!rel) throw new Error(`${arg} is outside ${FOLDER}/.`);
|
|
127
135
|
return rel;
|
|
@@ -264,6 +272,11 @@ async function doListen(root, opts) {
|
|
|
264
272
|
].join('\n'));
|
|
265
273
|
return;
|
|
266
274
|
}
|
|
275
|
+
if (b.messages.some((m) => m.kind === 'plan_rejected')) {
|
|
276
|
+
block('next_step', `The user REJECTED your plan. Do not build it. Ask in one short reply what they want instead (\`${CMD} reply "…" --listen\`${bg}).`);
|
|
277
|
+
return;
|
|
278
|
+
}
|
|
279
|
+
if (b.plan_waiting) block('plan_note', `Your plan "${b.plan_waiting}" is waiting for approval. If the user approves it in this message (approve, OK, go, yes, 同意, 可以, 开始), run \`${CMD} plan --approve\` first, then build. If they reject it, drop it.`);
|
|
267
280
|
if (b.messages.some((m) => m.kind === 'plan_changes')) {
|
|
268
281
|
block('next_step', [
|
|
269
282
|
'The user asked for changes to your plan. Do not build yet.',
|
|
@@ -365,11 +378,12 @@ async function cmdChanges(root, args, opts) {
|
|
|
365
378
|
if (st.rewritten) out(` report_history: ${q(st.rewritten)}`);
|
|
366
379
|
}
|
|
367
380
|
}
|
|
368
|
-
out(`browser: ${r.browsers ? 'the
|
|
381
|
+
out(`browser: ${r.browsers ? 'shown to the user as a card in the conversation; changed boxes carry their lines on the map' : `no tab is open; run \`${CMD}\` to open the map`}`);
|
|
369
382
|
const steps = [];
|
|
370
383
|
if (r.plan && r.plan.status !== 'done') steps.push(`When the plan is built, run \`${CMD} plan --done\`. If some steps are not built, say so in your reply (or add --step "3=not_built:why" so it shows beside the facts).`);
|
|
371
384
|
if (r.plan?.steps?.some((x) => x.conflict)) steps.push('Some steps you reported done name files with no changes: fix the work or correct your report (the user sees both, and the report history).');
|
|
372
|
-
if (r.files) steps.push('Tell the user in 1-3 lines what you changed and where, by box. They
|
|
385
|
+
if (r.files) steps.push('Tell the user in 1-3 lines what you changed and where, by box. They see it as a card in the conversation and on the map; a box opens its diff.');
|
|
386
|
+
if (r.boxes.length) steps.push(`Keep the map true: for each box you changed, fix its data-name, tag and detail if they no longer fit, then confirm it with \`${CMD} check --ok index.html --box <id>\` (otherwise the user sees "Map may be out of date").`);
|
|
373
387
|
if (r.unmapped.length) steps.push('Files that are not on the map: if they matter (a new module, a new route), add a box for them to the page.');
|
|
374
388
|
steps.push(agentLoopHint());
|
|
375
389
|
block('next_step', steps.join('\n'));
|
|
@@ -437,6 +451,49 @@ async function cmdPlan(root, args, opts) {
|
|
|
437
451
|
].join('\n'));
|
|
438
452
|
}
|
|
439
453
|
|
|
454
|
+
// A draft: a free-form page that explains one thing, numbered so the drafts read as a record.
|
|
455
|
+
function cmdDraft(root, args, opts) {
|
|
456
|
+
const hasMap = existsSync(join(root, FOLDER, 'index.html'));
|
|
457
|
+
const name = args.join(' ').trim();
|
|
458
|
+
if (!name) throw new Error('draft needs a name: truemap draft "how a message is routed"');
|
|
459
|
+
ensureFolder(root);
|
|
460
|
+
const dir = join(folderPath(root), 'drafts');
|
|
461
|
+
mkdirSync(dir, { recursive: true });
|
|
462
|
+
const nums = readdirSync(dir).map((x) => parseInt(x, 10)).filter(Number.isFinite);
|
|
463
|
+
const n = (nums.length ? Math.max(...nums) : 0) + 1;
|
|
464
|
+
const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'draft';
|
|
465
|
+
const file = `drafts/${String(n).padStart(3, '0')}-${slug}.html`;
|
|
466
|
+
const title = opts.title || name.replace(/^./, (c) => c.toUpperCase());
|
|
467
|
+
const esc = (t) => String(t).replace(/[&<>"]/g, (c) => ({ '&': '&', '<': '<', '>': '>', '"': '"' }[c]));
|
|
468
|
+
writeFileSync(join(folderPath(root), file), `<!doctype html>
|
|
469
|
+
<html lang="en">
|
|
470
|
+
<head>
|
|
471
|
+
<meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
|
|
472
|
+
<title>${esc(title)}</title>
|
|
473
|
+
<link rel="stylesheet" href="../assets/truemap.css">
|
|
474
|
+
</head>
|
|
475
|
+
<body><main class="tm-page">
|
|
476
|
+
<header class="tm-header">
|
|
477
|
+
<nav class="tm-crumb">${hasMap ? '<a href="../index.html">Map</a> / ' : ''}Draft ${n}</nav>
|
|
478
|
+
<h1 class="tm-title">${esc(title)}</h1>
|
|
479
|
+
<p class="tm-lede">One sentence: what this shows.</p>
|
|
480
|
+
</header>
|
|
481
|
+
<!-- Show it in the form that makes it obvious: a real example traced step by step, a drawing, a timeline,
|
|
482
|
+
options side by side, something to try, or the map component. Any HTML, inline SVG, <style>, <script>;
|
|
483
|
+
colours through var(--tm-…). Words only as captions. -->
|
|
484
|
+
<section class="tm-section">
|
|
485
|
+
</section>
|
|
486
|
+
</main></body>
|
|
487
|
+
</html>
|
|
488
|
+
`);
|
|
489
|
+
out('status: draft_created');
|
|
490
|
+
out(`draft: ${q(file)} # .truemap/${file}`);
|
|
491
|
+
block('next_step', [
|
|
492
|
+
`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>.' : ''}`,
|
|
493
|
+
`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.`,
|
|
494
|
+
].join('\n'));
|
|
495
|
+
}
|
|
496
|
+
|
|
440
497
|
async function cmdProgress(root, args) {
|
|
441
498
|
const state = await liveState(root);
|
|
442
499
|
if (!state) return out('status: no_server');
|
|
@@ -455,6 +512,8 @@ async function cmdCheck(root, args, opts) {
|
|
|
455
512
|
}
|
|
456
513
|
const pages = args.length ? args.map((a) => resolvePage(root, a)) : undefined;
|
|
457
514
|
const { gitRepo, results } = checkAll(root, pages);
|
|
515
|
+
const live = await liveState(root);
|
|
516
|
+
if (live) await call(live, 'POST', '/api/check', {}).catch(() => {});
|
|
458
517
|
out(`status: checked ${results.length} page(s)${gitRepo ? '' : ' (no git: only missing paths/names are checked)'}`);
|
|
459
518
|
let changed = 0; let broken = 0; let wires = 0;
|
|
460
519
|
for (const r of results) {
|
|
@@ -469,6 +528,9 @@ async function cmdCheck(root, args, opts) {
|
|
|
469
528
|
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).');
|
|
470
529
|
const layout = results.reduce((n, r) => n + (r.layout || []).length, 0);
|
|
471
530
|
if (layout) steps.push('Map notes: fix each one; they are what keeps a map readable at a glance (see `' + CMD + ' guide`, THE MAP).');
|
|
531
|
+
const faint = contrastNotes(tokensCss(root));
|
|
532
|
+
for (const n of faint) out(`hard to read: ${n}`);
|
|
533
|
+
if (faint.length) steps.push(`The theme has colours that are hard to read (above): fix .truemap/assets/theme.css, then \`${CMD} theme\`.`);
|
|
472
534
|
if (!broken && !changed && !wires && !layout) steps.push('All pages match the code.');
|
|
473
535
|
block('next_step', steps.join('\n'));
|
|
474
536
|
}
|
|
@@ -503,6 +565,22 @@ function cmdOutline(root) {
|
|
|
503
565
|
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.`);
|
|
504
566
|
}
|
|
505
567
|
|
|
568
|
+
// The user's look: colours and fonts for every page and the workspace, kept in .truemap/assets/theme.css.
|
|
569
|
+
function cmdTheme(root) {
|
|
570
|
+
const file = join(root, FOLDER, 'assets', 'theme.css');
|
|
571
|
+
const has = existsSync(file);
|
|
572
|
+
out(`theme: ${has ? `${FOLDER}/assets/theme.css` : 'none (truemap defaults)'}`);
|
|
573
|
+
const notes = contrastNotes(tokensCss(root));
|
|
574
|
+
for (const n of notes) out(`hard to read: ${n}`);
|
|
575
|
+
block('next_step', [
|
|
576
|
+
has ? 'Edit .truemap/assets/theme.css to change the look.' : 'To change the look, create .truemap/assets/theme.css.',
|
|
577
|
+
'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'),
|
|
578
|
+
'Colours and fonts only; never restyle components. Keep the three status colours (--tm-changed, --tm-broken, --tm-fine) easy to tell apart.',
|
|
579
|
+
'Every open page and the workspace update by themselves. Run this command again to check contrast.',
|
|
580
|
+
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.',
|
|
581
|
+
].join('\n'));
|
|
582
|
+
}
|
|
583
|
+
|
|
506
584
|
function cmdGuide() {
|
|
507
585
|
out(readFileSync(join(PKG_DIR, 'src', 'guide.md'), 'utf8').replaceAll('{{CMD}}', CMD));
|
|
508
586
|
}
|
|
@@ -525,6 +603,8 @@ usage:
|
|
|
525
603
|
${CMD} reply "…" --focus id,id answer and light up the boxes the answer is about
|
|
526
604
|
${CMD} ask "<question>" --option "A | why" --option "B | why"
|
|
527
605
|
ask the user to choose, only when you are blocked on a real trade-off
|
|
606
|
+
${CMD} draft "<name>" a new numbered draft page that explains one thing (then open it with truemap <file>)
|
|
607
|
+
${CMD} theme the user's colours and fonts (.truemap/assets/theme.css), with a contrast check
|
|
528
608
|
${CMD} plan --file plan.json before a change that touches 3+ boxes or adds one: show the plan on the map for review
|
|
529
609
|
${CMD} plan --approve|--done the user said "go" in the terminal / the plan is built
|
|
530
610
|
${CMD} changes [--base turn|plan|head|main]
|
|
@@ -558,6 +638,7 @@ function parseArgs(argv) {
|
|
|
558
638
|
else if (a === '--approve') opts.approve = true;
|
|
559
639
|
else if (a === '--done') opts.done = true;
|
|
560
640
|
else if (a === '--step') (opts.step ||= []).push(argv[++i]);
|
|
641
|
+
else if (a === '--title') opts.title = argv[++i];
|
|
561
642
|
else if (a === '--box') (opts.box ||= []).push(argv[++i]);
|
|
562
643
|
else if (a === '--option') (opts.option ||= []).push(argv[++i]);
|
|
563
644
|
else if (a === '--help' || a === '-h') opts.help = true;
|
|
@@ -570,7 +651,7 @@ function parseArgs(argv) {
|
|
|
570
651
|
export async function main(argv) {
|
|
571
652
|
const { args, opts } = parseArgs(argv);
|
|
572
653
|
if (opts.version) return out(VERSION);
|
|
573
|
-
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, help };
|
|
654
|
+
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 };
|
|
574
655
|
const name = args[0] && commands[args[0]] ? args.shift() : null;
|
|
575
656
|
if (opts.help || name === 'help') return help();
|
|
576
657
|
const root = findRoot();
|
package/src/common.js
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Shared helpers: repo root, state files, version, safe executable lookup.
|
|
2
2
|
import { execFileSync } from 'node:child_process';
|
|
3
3
|
import { createHash } from 'node:crypto';
|
|
4
|
-
import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
|
|
5
5
|
import { homedir } from 'node:os';
|
|
6
6
|
import { delimiter, dirname, isAbsolute, join, resolve } from 'node:path';
|
|
7
7
|
import { fileURLToPath } from 'node:url';
|
|
@@ -74,6 +74,17 @@ export function rootKey(root) {
|
|
|
74
74
|
}
|
|
75
75
|
|
|
76
76
|
export function serversDir() { return stateSubdir('servers'); }
|
|
77
|
+
/** The code a server runs: the version plus the newest edit to truemap's own files (catches local builds). */
|
|
78
|
+
export function buildId() {
|
|
79
|
+
let newest = 0;
|
|
80
|
+
for (const dir of ['src', 'src/ui', 'kit']) {
|
|
81
|
+
let names = []; try { names = readdirSync(join(PKG_DIR, dir)); } catch { /* not there */ }
|
|
82
|
+
for (const n of names) { try { const st = statSync(join(PKG_DIR, dir, n)); if (st.isFile()) newest = Math.max(newest, st.mtimeMs); } catch { /* gone */ } }
|
|
83
|
+
}
|
|
84
|
+
return `${VERSION}+${Math.round(newest)}`;
|
|
85
|
+
}
|
|
86
|
+
/** A project keeps the same ports and token across restarts, so an open tab and a bookmark keep working. */
|
|
87
|
+
export function addrPath(root) { return join(stateSubdir('addr'), `${rootKey(root)}.json`); }
|
|
77
88
|
export function serverStatePath(root) { return join(stateSubdir('servers'), `${rootKey(root)}.json`); }
|
|
78
89
|
export function serverLockPath(root) { return join(stateSubdir('servers'), `${rootKey(root)}.lock`); }
|
|
79
90
|
export function historyPath(root) { return join(stateSubdir('history'), `${rootKey(root)}.jsonl`); }
|
package/src/contrast.js
ADDED
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
// Can people read it? The colour tokens a project ends up with (kit + .truemap/assets/theme.css), light and
|
|
2
|
+
// dark, and the pairs that must stay readable.
|
|
3
|
+
|
|
4
|
+
const NAMED = {
|
|
5
|
+
black: '#000000', white: '#ffffff', gray: '#808080', grey: '#808080', silver: '#c0c0c0', lightgray: '#d3d3d3',
|
|
6
|
+
lightgrey: '#d3d3d3', darkgray: '#a9a9a9', darkgrey: '#a9a9a9', dimgray: '#696969', dimgrey: '#696969',
|
|
7
|
+
gainsboro: '#dcdcdc', whitesmoke: '#f5f5f5', snow: '#fffafa', ivory: '#fffff0', beige: '#f5f5dc', linen: '#faf0e6',
|
|
8
|
+
red: '#ff0000', darkred: '#8b0000', maroon: '#800000', crimson: '#dc143c', tomato: '#ff6347', coral: '#ff7f50',
|
|
9
|
+
orange: '#ffa500', darkorange: '#ff8c00', gold: '#ffd700', yellow: '#ffff00', khaki: '#f0e68c',
|
|
10
|
+
green: '#008000', darkgreen: '#006400', lime: '#00ff00', olive: '#808000', teal: '#008080', seagreen: '#2e8b57',
|
|
11
|
+
blue: '#0000ff', navy: '#000080', darkblue: '#00008b', royalblue: '#4169e1', steelblue: '#4682b4',
|
|
12
|
+
skyblue: '#87ceeb', lightblue: '#add8e6', dodgerblue: '#1e90ff', cyan: '#00ffff', aqua: '#00ffff',
|
|
13
|
+
purple: '#800080', indigo: '#4b0082', violet: '#ee82ee', magenta: '#ff00ff', fuchsia: '#ff00ff', pink: '#ffc0cb',
|
|
14
|
+
brown: '#a52a2a', chocolate: '#d2691e', tan: '#d2b48c', slategray: '#708090', slategrey: '#708090',
|
|
15
|
+
};
|
|
16
|
+
/** [r, g, b] 0-255 for hex, rgb(), hsl() and named colours; null when it can't be read. */
|
|
17
|
+
function hex(c) {
|
|
18
|
+
let v = String(c ?? '').trim().toLowerCase();
|
|
19
|
+
if (NAMED[v]) v = NAMED[v];
|
|
20
|
+
const m = v.match(/^#([0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/);
|
|
21
|
+
if (m) {
|
|
22
|
+
const h = m[1].length <= 4 ? [...m[1].slice(0, 3)].map((x) => x + x).join('') : m[1].slice(0, 6);
|
|
23
|
+
return [0, 2, 4].map((i) => parseInt(h.slice(i, i + 2), 16));
|
|
24
|
+
}
|
|
25
|
+
const num = (x, max) => (x.endsWith('%') ? (parseFloat(x) / 100) * max : parseFloat(x));
|
|
26
|
+
const r = v.match(/^rgba?\(\s*([\d.]+%?)[\s,]+([\d.]+%?)[\s,]+([\d.]+%?)/);
|
|
27
|
+
if (r) return [r[1], r[2], r[3]].map((x) => Math.round(Math.min(255, num(x, 255))));
|
|
28
|
+
const h = v.match(/^hsla?\(\s*([\d.]+)(?:deg)?[\s,]+([\d.]+)%[\s,]+([\d.]+)%/);
|
|
29
|
+
if (h) {
|
|
30
|
+
const H = (+h[1] % 360) / 360; const S = +h[2] / 100; const L = +h[3] / 100;
|
|
31
|
+
const q = L < 0.5 ? L * (1 + S) : L + S - L * S; const p = 2 * L - q;
|
|
32
|
+
const t = (x) => { x = (x + 1) % 1; return x < 1 / 6 ? p + (q - p) * 6 * x : x < 1 / 2 ? q : x < 2 / 3 ? p + (q - p) * (2 / 3 - x) * 6 : p; };
|
|
33
|
+
return [t(H + 1 / 3), t(H), t(H - 1 / 3)].map((x) => Math.round(x * 255));
|
|
34
|
+
}
|
|
35
|
+
return null;
|
|
36
|
+
}
|
|
37
|
+
const lum = (rgb) => {
|
|
38
|
+
const [r, g, b] = rgb.map((v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4; });
|
|
39
|
+
return 0.2126 * r + 0.7152 * g + 0.0722 * b;
|
|
40
|
+
};
|
|
41
|
+
export function ratio(a, b) {
|
|
42
|
+
const x = hex(a); const y = hex(b);
|
|
43
|
+
if (!x || !y) return null;
|
|
44
|
+
const [hi, lo] = [lum(x), lum(y)].sort((p, q) => q - p);
|
|
45
|
+
return (hi + 0.05) / (lo + 0.05);
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
/** The --tm-* values in effect, for light and for dark (later rules win, dark builds on light). */
|
|
49
|
+
export function tokens(css) {
|
|
50
|
+
const light = {}; const dark = {};
|
|
51
|
+
const take = (body, into) => { for (const m of body.matchAll(/(--tm-[\w-]+)\s*:\s*([^;}]+)/g)) into[m[1]] = m[2].trim(); };
|
|
52
|
+
const plain = css.replace(/\/\*[\s\S]*?\*\//g, '');
|
|
53
|
+
const re = /@media\s*\(\s*prefers-color-scheme\s*:\s*dark\s*\)\s*\{/g;
|
|
54
|
+
let at = 0; let m;
|
|
55
|
+
while ((m = re.exec(plain))) {
|
|
56
|
+
for (const r of plain.slice(at, m.index).matchAll(/:root[^{]*\{([^}]*)\}/g)) take(r[1], light);
|
|
57
|
+
let depth = 1; let i = re.lastIndex;
|
|
58
|
+
for (; i < plain.length && depth; i++) { if (plain[i] === '{') depth++; else if (plain[i] === '}') depth--; }
|
|
59
|
+
for (const r of plain.slice(re.lastIndex, i).matchAll(/:root[^{]*\{([^}]*)\}/g)) take(r[1], dark);
|
|
60
|
+
at = i; re.lastIndex = i;
|
|
61
|
+
}
|
|
62
|
+
for (const r of plain.slice(at).matchAll(/:root[^{]*\{([^}]*)\}/g)) take(r[1], light);
|
|
63
|
+
return { light, dark: { ...light, ...dark } };
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
const PAIRS = [
|
|
67
|
+
['--tm-text', '--tm-paper', 4.5, 'body text on the page'],
|
|
68
|
+
['--tm-ink', '--tm-sheet', 4.5, 'box titles'],
|
|
69
|
+
['--tm-ink', '--tm-mark', 4.5, 'text on the highlighter'],
|
|
70
|
+
['--tm-text', '--tm-wash', 4.5, 'text on quiet fills'],
|
|
71
|
+
['--tm-ink', '--tm-chrome', 4.5, 'the workspace bar'],
|
|
72
|
+
['--tm-graphite', '--tm-paper', 4.5, 'secondary text'],
|
|
73
|
+
['--tm-pencil', '--tm-paper', 2.5, 'hints'],
|
|
74
|
+
['--tm-accent-text', '--tm-accent', 4.5, 'text on the primary button'],
|
|
75
|
+
['--tm-changed', '--tm-paper', 3, '"changed" marks'],
|
|
76
|
+
['--tm-broken', '--tm-paper', 3, '"broken" marks'],
|
|
77
|
+
['--tm-fine', '--tm-paper', 3, '"fine" and "new" marks'],
|
|
78
|
+
['--tm-rule-strong', '--tm-paper', 1.3, 'box borders'],
|
|
79
|
+
];
|
|
80
|
+
|
|
81
|
+
/** Pairs that are too faint to read, as plain notes. */
|
|
82
|
+
export function contrastNotes(css) {
|
|
83
|
+
const t = tokens(css); const notes = [];
|
|
84
|
+
for (const [mode, vals] of [['light', t.light], ['dark', t.dark]]) {
|
|
85
|
+
const val = (k) => { let v = vals[k]; for (let n = 0; n < 4 && /^var\(/.test(v || ''); n++) v = vals[(v.match(/var\(\s*(--tm-[\w-]+)/) || [])[1]]; return v; };
|
|
86
|
+
for (const [fg, bg, min, what] of PAIRS) {
|
|
87
|
+
const r = ratio(val(fg), val(bg));
|
|
88
|
+
if (r == null) { notes.push(`${mode}: ${what}: can't read ${hex(val(fg)) ? bg + ' ' + val(bg) : fg + ' ' + val(fg)}; use hex, rgb() or hsl() so it can be checked`); continue; }
|
|
89
|
+
if (r < min) notes.push(`${mode}: ${what} (${fg} ${val(fg)} on ${bg} ${val(bg)}) contrast ${r.toFixed(1)}:1, needs ${min}:1`);
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
return notes;
|
|
93
|
+
}
|
package/src/export.js
CHANGED
|
@@ -21,14 +21,19 @@ export function insideFile(dir, rel) {
|
|
|
21
21
|
} catch { return null; }
|
|
22
22
|
}
|
|
23
23
|
|
|
24
|
-
/** The
|
|
24
|
+
/** The project's theme (.truemap/assets/theme.css), or nothing. */
|
|
25
|
+
export function themeCss(root) {
|
|
26
|
+
const theme = insideFile(join(root, FOLDER), 'assets/theme.css');
|
|
27
|
+
return theme ? `\n/* .truemap/assets/theme.css */\n${readFileSync(theme, 'utf8')}` : '';
|
|
28
|
+
}
|
|
29
|
+
/** Colours and fonts in effect: truemap's tokens, then the project's theme. The workspace uses these too. */
|
|
30
|
+
export function tokensCss(root) {
|
|
31
|
+
return readFileSync(join(KIT_DIR, 'tokens.css'), 'utf8') + themeCss(root);
|
|
32
|
+
}
|
|
33
|
+
/** The page kit as served: tokens, components, theme. A repo's own assets/truemap.css (older setups) replaces the first two. */
|
|
25
34
|
export function kitCss(root) {
|
|
26
|
-
const
|
|
27
|
-
|
|
28
|
-
let css = readFileSync(own || join(KIT_DIR, 'truemap.css'), 'utf8');
|
|
29
|
-
const theme = insideFile(folder, 'assets/theme.css');
|
|
30
|
-
if (theme) css += `\n/* .truemap/assets/theme.css */\n${readFileSync(theme, 'utf8')}`;
|
|
31
|
-
return css;
|
|
35
|
+
const own = insideFile(join(root, FOLDER), 'assets/truemap.css');
|
|
36
|
+
return (own ? readFileSync(own, 'utf8') : readFileSync(join(KIT_DIR, 'tokens.css'), 'utf8') + '\n' + readFileSync(join(KIT_DIR, 'truemap.css'), 'utf8')) + themeCss(root);
|
|
32
37
|
}
|
|
33
38
|
|
|
34
39
|
export function exportPage(root, page) {
|