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 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
- - **Review the change after the work.** Changed boxes carry their +/− lines; files no box covers are listed by folder. Click a box to see its diff. Measured from when the agent picked up your message, from when you approved the plan, or against your main branch.
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 any box.** What it does, what to know, why it is built that way, what it calls, and the real code (read live from your repo) when you want it.
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; opens the Changes view |
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. 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; }
@@ -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; }
@@ -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: -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; }
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
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "truemap-cli",
3
- "version": "0.5.0",
3
+ "version": "0.5.2",
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: Review what you plan and what you changed on a living map of the codebase that stays true to the code. Use before a change that touches 3+ parts or adds one (show the plan, wait for approval), after editing code (show what changed, by box), when explaining architecture, a module or a flow, when asked "how does X work" or "show me the project", and whenever a .truemap/ folder exists and you are about to explain something it may already cover. Not for one-line answers.
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: look in `.truemap/` first, update or write the page, run `npx -y truemap-cli <page>`, then follow the `next_step` it prints.
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) => ({ page, title: readTitle(join(base, page)) || page.replace(/\.html?$/i, '') }));
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
- try { await call(state, 'POST', '/api/agent/shutdown', {}, { timeoutMs: 1500 }); } catch { /* ignore */ }
63
- await sleep(200);
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 Changes view is open' : `no tab is open; run \`${CMD}\` to open the map`}`);
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 review it on the map: changed boxes show their lines; clicking one shows the diff.');
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) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[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`); }
@@ -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 page kit as served: a repo's own assets/truemap.css wins; assets/theme.css is appended. */
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 folder = join(root, FOLDER);
27
- const own = insideFile(folder, 'assets/truemap.css');
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) {