truemap-cli 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 truemap contributors
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,68 @@
1
- # Temporary Holding Version
1
+ # truemap
2
+
3
+ **Agents explain your project with living HTML pages that stay true to the code.**
4
+ Click anything on a page to ask about it. Click an option to decide. The pages live in your repo and get checked against the code, so they never quietly lie.
5
+
6
+
7
+ ---
8
+
9
+ ## Why
10
+
11
+ Coding agents write code faster than anyone can read it. Their answers come back as walls of text, and the diagrams they draw are thrown away after one chat. truemap gives the agent a better way to talk to you:
12
+
13
+ - **Pages, not paragraphs.** The agent draws the architecture, a flow, or the options as an HTML page and opens it in your browser.
14
+ - **Point and ask.** Click a box on the page, ask in the chat panel next to it. The agent receives your question *and* the code that box points to. It is the same agent session you are already using, so there is no new login or extra app.
15
+ - **Click to decide.** When the agent needs your call, the page shows options. One click and the answer goes back to the agent.
16
+ - **Pages that stay true.** Every box carries a `data-src="path#name"` anchor. When the code moves on, truemap marks the box amber (changed) or red (gone), and the agent fixes the page.
17
+ - **It all stays in the repo.** Pages live in `.truemap/`, with `index.html` as the project blueprint. They are plain files you can commit, diff, and open anywhere.
18
+
19
+ ## Install
20
+
21
+ Install the skill once. That is all the setup there is.
22
+
23
+ ```sh
24
+ npx skills add TaoMachina/truemap --skill truemap
25
+ ```
26
+
27
+ Then just talk to your agent (Claude Code or Codex): *"How does payment work?"* or *"Show me the project."* The agent writes or updates a page and opens it. You can also ask for it directly: `/truemap show me the architecture`.
28
+
29
+ It also works with no skill installed. Tell the agent: *"use `npx -y truemap-cli --help`"*.
30
+
31
+ ## How it works
32
+
33
+ ```
34
+ your repo/
35
+ └── .truemap/
36
+ ├── index.html the blueprint: every module links to its page
37
+ ├── payments.html
38
+ ├── retry-decision.html
39
+ └── assets/truemap.css shared look (edit the tokens to match your brand)
40
+ ```
41
+
42
+ | Command (run by the agent) | What it does |
43
+ |---|---|
44
+ | `npx -y truemap-cli [page]` | Opens the workspace in your browser: page switcher on top, the page in the middle, chat on the right (collapsible) |
45
+ | `npx -y truemap-cli listen` | Waits for your next message from the chat panel |
46
+ | `npx -y truemap-cli reply "…" --listen` | Shows the agent's answer in the chat, then keeps listening |
47
+ | `npx -y truemap-cli check` | Checks every `data-src` anchor against the code |
48
+ | `npx -y truemap-cli guide` | The page-writing guide for agents: kit components, anchors, decision forms |
49
+
50
+ The checker doesn't depend on the programming language. It uses only git and a plain-text search:
51
+
52
+ - **✕ broken**: the path is gone, or `#name` no longer appears in the file (whole word, case-sensitive).
53
+ - **● changed**: the file changed after the page was last updated. The agent reviews it, then updates the page or runs `check --ok`.
54
+
55
+ Everything runs locally:
56
+
57
+ - The server listens on `127.0.0.1` only and needs a token for every request.
58
+ - Pages render in a sandboxed iframe on a separate origin, so page scripts can't reach the chat API.
59
+
60
+ ## Requirements
61
+
62
+ - Node.js 20 or newer
63
+ - git (optional; without it, only missing paths and names are checked)
64
+
65
+ ## License
66
+
67
+ MIT
2
68
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
package/bin/truemap.js ADDED
@@ -0,0 +1,7 @@
1
+ #!/usr/bin/env node
2
+ import { main } from '../src/cli.js';
3
+
4
+ main(process.argv.slice(2)).catch((err) => {
5
+ process.stdout.write(`status: error\nerror: ${JSON.stringify(String(err?.message || err))}\n`);
6
+ process.exit(1);
7
+ });
@@ -0,0 +1,230 @@
1
+ /* truemap page kit — shared by every page in .truemap/.
2
+ To match the project's own look, edit only the tokens in the first two blocks. */
3
+
4
+ :root {
5
+ --tm-paper: #f6f7f5;
6
+ --tm-sheet: #ffffff;
7
+ --tm-wash: #eef0ed;
8
+ --tm-ink: #1d2733;
9
+ --tm-graphite: #5a6472;
10
+ --tm-pencil: #8a929c;
11
+ --tm-rule: #d8dcd7;
12
+ --tm-rule-strong: #b9bfba;
13
+ --tm-route: #2c5a8c; /* the key path; links */
14
+ --tm-route-wash: #e6edf5;
15
+ --tm-changed: #9c6c12;
16
+ --tm-broken: #a23b2c;
17
+ --tm-fine: #2f6b4f;
18
+ --tm-radius: 4px;
19
+ --tm-font: system-ui, -apple-system, "Segoe UI", "Helvetica Neue", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Noto Sans CJK SC", sans-serif;
20
+ --tm-code: ui-monospace, "SF Mono", "Cascadia Mono", "JetBrains Mono", Consolas, monospace;
21
+ color-scheme: light dark;
22
+ }
23
+
24
+ @media (prefers-color-scheme: dark) {
25
+ :root {
26
+ --tm-paper: #14181d;
27
+ --tm-sheet: #1a1f25;
28
+ --tm-wash: #20262d;
29
+ --tm-ink: #e3e6e9;
30
+ --tm-graphite: #a2aab4;
31
+ --tm-pencil: #77808b;
32
+ --tm-rule: #2c333b;
33
+ --tm-rule-strong: #414a54;
34
+ --tm-route: #8db0dc;
35
+ --tm-route-wash: #1f2d3d;
36
+ --tm-changed: #d4a24a;
37
+ --tm-broken: #e07a66;
38
+ --tm-fine: #74b894;
39
+ }
40
+ }
41
+
42
+ /* ---------- base ---------- */
43
+ *, *::before, *::after { box-sizing: border-box; }
44
+ html { -webkit-text-size-adjust: 100%; }
45
+ body {
46
+ margin: 0;
47
+ background: var(--tm-paper);
48
+ color: var(--tm-ink);
49
+ font: 16px/1.6 var(--tm-font);
50
+ -webkit-font-smoothing: antialiased;
51
+ text-rendering: optimizeLegibility;
52
+ }
53
+ img, svg, video, canvas { max-width: 100%; }
54
+ p, li, td, th, h1, h2, h3, h4, dd { overflow-wrap: anywhere; }
55
+ p { margin: 0 0 1em; max-width: 70ch; }
56
+ a { color: var(--tm-route); text-decoration-thickness: 1px; text-underline-offset: 3px; }
57
+ a:hover { text-decoration-thickness: 2px; }
58
+ :focus-visible { outline: 2px solid var(--tm-route); outline-offset: 2px; }
59
+ ::selection { background: var(--tm-route-wash); }
60
+
61
+ .tm-page { max-width: 1040px; margin: 0 auto; padding: 56px 32px 112px; }
62
+ .tm-page.is-wide { max-width: 1320px; }
63
+
64
+ /* ---------- page head ---------- */
65
+ .tm-header { margin-bottom: 48px; }
66
+ .tm-crumb, .tm-eyebrow { display: block; font-size: 14px; color: var(--tm-graphite); margin-bottom: 10px; }
67
+ .tm-crumb a, .tm-eyebrow a { color: inherit; }
68
+ .tm-title { font-size: clamp(30px, 4.2vw, 40px); line-height: 1.12; letter-spacing: -.018em; font-weight: 650; margin: 0 0 14px; max-width: 24ch; }
69
+ .tm-lede { font-size: 19px; line-height: 1.55; color: var(--tm-graphite); margin: 0; max-width: 60ch; }
70
+
71
+ /* ---------- sections ---------- */
72
+ .tm-section { margin: 56px 0; }
73
+ .tm-section > h2, .tm-h2 { font-size: 22px; line-height: 1.25; letter-spacing: -.01em; font-weight: 640; margin: 0 0 8px; }
74
+ .tm-section > h2 + p, .tm-sub { color: var(--tm-graphite); margin-bottom: 20px; }
75
+ h3 { font-size: 17px; line-height: 1.35; font-weight: 640; margin: 0 0 6px; }
76
+ .tm-muted { color: var(--tm-graphite); }
77
+ .tm-faint { color: var(--tm-pencil); }
78
+ .tm-small { font-size: 14px; }
79
+ .tm-stack > * + * { margin-top: 12px; }
80
+
81
+ /* ---------- layout ---------- */
82
+ .tm-grid { display: grid; gap: 20px 28px; grid-template-columns: repeat(auto-fit, minmax(min(260px, 100%), 1fr)); }
83
+ .tm-grid-2 { display: grid; gap: 20px 28px; grid-template-columns: repeat(2, minmax(0, 1fr)); }
84
+ .tm-grid-3 { display: grid; gap: 20px 28px; grid-template-columns: repeat(3, minmax(0, 1fr)); }
85
+ @media (max-width: 760px) { .tm-grid-2, .tm-grid-3 { grid-template-columns: minmax(0, 1fr); } }
86
+ .tm-grid > *, .tm-grid-2 > *, .tm-grid-3 > * { min-width: 0; }
87
+
88
+ /* A panel is for content that belongs together, not a wrapper for every paragraph. */
89
+ .tm-card { background: var(--tm-sheet); border: 1px solid var(--tm-rule); border-radius: var(--tm-radius); padding: 18px 20px; }
90
+ .tm-card > :last-child { margin-bottom: 0; }
91
+ .tm-card.is-key { border-color: var(--tm-route); }
92
+
93
+ /* ---------- blueprint: layered structure ---------- */
94
+ .tm-blueprint { display: grid; gap: 0; border-top: 1px solid var(--tm-rule); }
95
+ .tm-layer { display: grid; grid-template-columns: 128px minmax(0, 1fr); gap: 20px; padding: 18px 0; border-bottom: 1px solid var(--tm-rule); }
96
+ .tm-layer-label { font-size: 14px; color: var(--tm-graphite); padding-top: 11px; }
97
+ .tm-layer-nodes { display: flex; flex-wrap: wrap; gap: 12px; }
98
+ @media (max-width: 640px) { .tm-layer { grid-template-columns: minmax(0, 1fr); gap: 8px; } .tm-layer-label { padding-top: 0; } }
99
+
100
+ /* ---------- nodes: modules, services, steps ---------- */
101
+ .tm-node, .tm-step {
102
+ position: relative; display: flex; flex-direction: column; gap: 3px;
103
+ min-width: 160px; flex: 1 1 160px; max-width: 300px;
104
+ padding: 11px 14px 12px; border-radius: var(--tm-radius);
105
+ background: var(--tm-sheet); border: 1px solid var(--tm-rule-strong);
106
+ color: inherit; text-decoration: none;
107
+ }
108
+ .tm-node-title { font-weight: 620; font-size: 15px; line-height: 1.3; }
109
+ .tm-node-sub { font: 12.5px/1.4 var(--tm-code); color: var(--tm-pencil); overflow-wrap: anywhere; }
110
+ .tm-node-desc { font-size: 14px; line-height: 1.45; color: var(--tm-graphite); margin-top: 3px; }
111
+ a.tm-node:hover .tm-node-title { text-decoration: underline; text-decoration-thickness: 1px; text-underline-offset: 3px; }
112
+ .tm-node.is-key, .tm-step.is-key { border: 1.5px solid var(--tm-route); }
113
+ .tm-node.is-new, .tm-step.is-new { border-color: var(--tm-fine); }
114
+ .tm-node.is-risk, .tm-step.is-risk { border-color: var(--tm-changed); }
115
+ .tm-node.is-ext, .tm-step.is-ext { border-style: dashed; background: transparent; }
116
+
117
+ /* The pin: anything anchored to code carries a small corner mark. This is truemap's signature. */
118
+ .tm-node[data-src], .tm-step[data-src], .tm-card[data-src] {
119
+ background-image: linear-gradient(225deg, var(--tm-route) 0 6px, transparent 6px);
120
+ background-repeat: no-repeat;
121
+ }
122
+
123
+ /* ---------- flows (a real sequence: step, then step) ---------- */
124
+ .tm-flow { display: flex; flex-wrap: wrap; align-items: stretch; row-gap: 14px; }
125
+ .tm-flow > .tm-node, .tm-flow > .tm-step { flex: 1 1 150px; max-width: none; }
126
+ .tm-flow > * + * { margin-left: 32px; }
127
+ .tm-flow > * + *::before { content: ""; position: absolute; left: -26px; top: 50%; width: 19px; height: 1px; background: var(--tm-graphite); }
128
+ .tm-flow > * + *::after {
129
+ content: ""; position: absolute; left: -9px; top: calc(50% - 4px);
130
+ border: 4px solid transparent; border-left: 6px solid var(--tm-graphite); border-right: 0;
131
+ }
132
+ .tm-flow.is-vertical { flex-direction: column; }
133
+ .tm-flow.is-vertical > * { flex: none; }
134
+ .tm-flow.is-vertical > * + * { margin: 24px 0 0; }
135
+ .tm-flow.is-vertical > * + *::before { left: 28px; top: -20px; width: 1px; height: 14px; }
136
+ .tm-flow.is-vertical > * + *::after { left: 24px; top: -9px; border: 4px solid transparent; border-top: 6px solid var(--tm-graphite); border-bottom: 0; }
137
+ @media (max-width: 640px) {
138
+ .tm-flow { flex-direction: column; }
139
+ .tm-flow > *, .tm-flow > .tm-node, .tm-flow > .tm-step { flex: none; }
140
+ .tm-flow > * + * { margin: 24px 0 0; }
141
+ .tm-flow > * + *::before { left: 28px; top: -20px; width: 1px; height: 14px; }
142
+ .tm-flow > * + *::after { left: 24px; top: -9px; border: 4px solid transparent; border-top: 6px solid var(--tm-graphite); border-bottom: 0; }
143
+ }
144
+
145
+ /* ---------- inline SVG diagrams ---------- */
146
+ .tm-svg { display: block; width: 100%; height: auto; color: var(--tm-ink); font-family: var(--tm-font); }
147
+ .tm-svg text { fill: currentColor; font-size: 13px; }
148
+ .tm-svg .tm-box { fill: var(--tm-sheet); stroke: var(--tm-rule-strong); stroke-width: 1; }
149
+ .tm-svg .tm-box.is-key { stroke: var(--tm-route); stroke-width: 1.6; }
150
+ .tm-svg .tm-edge { fill: none; stroke: var(--tm-graphite); stroke-width: 1.2; }
151
+ .tm-svg .tm-edge.is-key { stroke: var(--tm-route); stroke-width: 1.6; }
152
+ .tm-svg .tm-label { fill: var(--tm-graphite); font-size: 12px; }
153
+ .tm-figure { margin: 0; }
154
+ .tm-figure figcaption { margin-top: 10px; font-size: 14px; color: var(--tm-graphite); max-width: 70ch; }
155
+
156
+ /* ---------- page index (on the blueprint) ---------- */
157
+ .tm-links { list-style: none; margin: 0; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(min(300px, 100%), 1fr)); border-top: 1px solid var(--tm-rule); column-gap: 32px; }
158
+ .tm-link { display: block; padding: 14px 0; border-bottom: 1px solid var(--tm-rule); text-decoration: none; color: inherit; }
159
+ .tm-link strong { display: block; font-weight: 620; color: var(--tm-route); }
160
+ .tm-link:hover strong { text-decoration: underline; text-underline-offset: 3px; }
161
+ .tm-link span { display: block; margin-top: 2px; font-size: 14px; color: var(--tm-graphite); }
162
+
163
+ /* ---------- tags, code ---------- */
164
+ .tm-badge {
165
+ display: inline-block; padding: 0 6px; border-radius: 3px; vertical-align: 1px;
166
+ font-size: 12.5px; line-height: 20px; font-weight: 560; color: var(--tm-graphite); background: var(--tm-wash);
167
+ }
168
+ .tm-badge.is-accent { color: var(--tm-route); background: var(--tm-route-wash); }
169
+ .tm-badge.is-ok { color: var(--tm-fine); background: color-mix(in srgb, var(--tm-fine) 12%, transparent); }
170
+ .tm-badge.is-warn { color: var(--tm-changed); background: color-mix(in srgb, var(--tm-changed) 13%, transparent); }
171
+ .tm-badge.is-bad { color: var(--tm-broken); background: color-mix(in srgb, var(--tm-broken) 11%, transparent); }
172
+ .tm-path, code { font-family: var(--tm-code); font-size: .88em; padding: 1px 4px; border-radius: 3px; background: var(--tm-wash); overflow-wrap: anywhere; }
173
+ pre { margin: 14px 0; padding: 14px 16px; overflow: auto; border-radius: var(--tm-radius); font: 13.5px/1.6 var(--tm-code); background: var(--tm-wash); }
174
+ pre code { padding: 0; background: none; font-size: inherit; }
175
+
176
+ /* ---------- notes (risk, decision, fact) ---------- */
177
+ .tm-callout { margin: 16px 0; padding: 14px 16px; border-radius: var(--tm-radius); background: var(--tm-sheet); border: 1px solid var(--tm-rule); max-width: 76ch; }
178
+ .tm-callout > :first-child { margin-top: 0; } .tm-callout > :last-child { margin-bottom: 0; }
179
+ .tm-callout > b:first-child, .tm-callout > strong:first-child { color: var(--tm-ink); }
180
+ .tm-callout.is-accent { border-color: color-mix(in srgb, var(--tm-route) 40%, var(--tm-rule)); }
181
+ .tm-callout.is-accent > b:first-child, .tm-callout.is-accent > strong:first-child { color: var(--tm-route); }
182
+ .tm-callout.is-ok > b:first-child, .tm-callout.is-ok > strong:first-child { color: var(--tm-fine); }
183
+ .tm-callout.is-warn { border-color: color-mix(in srgb, var(--tm-changed) 40%, var(--tm-rule)); }
184
+ .tm-callout.is-warn > b:first-child, .tm-callout.is-warn > strong:first-child { color: var(--tm-changed); }
185
+ .tm-callout.is-bad { border-color: color-mix(in srgb, var(--tm-broken) 40%, var(--tm-rule)); }
186
+ .tm-callout.is-bad > b:first-child, .tm-callout.is-bad > strong:first-child { color: var(--tm-broken); }
187
+
188
+ /* ---------- tables & key-values ---------- */
189
+ .tm-table-wrap { overflow-x: auto; }
190
+ .tm-table { width: 100%; border-collapse: collapse; font-size: 15px; border-top: 1px solid var(--tm-rule-strong); }
191
+ .tm-table th, .tm-table td { text-align: left; vertical-align: top; padding: 10px 16px 10px 0; border-bottom: 1px solid var(--tm-rule); }
192
+ .tm-table th { font-size: 14px; font-weight: 600; color: var(--tm-graphite); }
193
+ .tm-kv { display: grid; grid-template-columns: max-content minmax(0, 1fr); gap: 8px 24px; margin: 0; }
194
+ .tm-kv dt { color: var(--tm-graphite); }
195
+ .tm-kv dd { margin: 0; }
196
+
197
+ /* ---------- ordered steps (only for real sequences) ---------- */
198
+ .tm-steps { padding-left: 1.6em; margin: 0; max-width: 70ch; }
199
+ .tm-steps > li { padding-left: .4em; margin: 0 0 10px; }
200
+ .tm-steps > li::marker { color: var(--tm-graphite); font-variant-numeric: tabular-nums; font-weight: 600; }
201
+
202
+ /* ---------- decisions (the user clicks, the agent receives the answer) ---------- */
203
+ .tm-ask { margin: 24px 0; padding: 22px 22px 20px; border-radius: var(--tm-radius); background: var(--tm-sheet); border: 1px solid var(--tm-rule-strong); max-width: 760px; }
204
+ .tm-ask > h3, .tm-ask > legend { font-size: 18px; margin: 0 0 6px; }
205
+ .tm-ask > p { color: var(--tm-graphite); font-size: 15px; margin-bottom: 16px; }
206
+ .tm-options { display: grid; gap: 8px; margin: 0 0 16px; }
207
+ .tm-option {
208
+ display: grid; grid-template-columns: auto minmax(0, 1fr); gap: 2px 12px; align-items: start; cursor: pointer;
209
+ padding: 11px 14px; border-radius: var(--tm-radius); border: 1px solid var(--tm-rule);
210
+ }
211
+ .tm-option:hover { border-color: var(--tm-rule-strong); }
212
+ .tm-option:has(input:checked) { border-color: var(--tm-route); background: var(--tm-route-wash); }
213
+ .tm-option input { margin: 4px 0 0; accent-color: var(--tm-route); width: 16px; height: 16px; }
214
+ .tm-option strong { font-weight: 600; }
215
+ .tm-option .tm-why { grid-column: 2; font-size: 14px; color: var(--tm-graphite); }
216
+ .tm-ask textarea {
217
+ width: 100%; min-height: 64px; resize: vertical; padding: 10px 12px; margin-bottom: 14px;
218
+ border-radius: var(--tm-radius); border: 1px solid var(--tm-rule); background: var(--tm-paper); color: inherit; font: inherit; font-size: 15px;
219
+ }
220
+ .tm-btn {
221
+ display: inline-block; padding: 9px 16px; border-radius: var(--tm-radius); border: 1px solid var(--tm-ink); cursor: pointer;
222
+ font: 600 15px/1.2 var(--tm-font); background: var(--tm-ink); color: var(--tm-paper);
223
+ }
224
+ .tm-btn:hover { background: color-mix(in srgb, var(--tm-ink) 86%, var(--tm-route)); }
225
+ .tm-btn.is-ghost { background: transparent; color: var(--tm-ink); border-color: var(--tm-rule-strong); }
226
+ .tm-ask[data-tm-sent] { border-color: var(--tm-fine); }
227
+ .tm-ask[data-tm-sent] .tm-btn { background: var(--tm-fine); border-color: var(--tm-fine); }
228
+
229
+ @media (prefers-reduced-motion: reduce) { * { transition: none !important; animation: none !important; } }
230
+ @media print { body { background: #fff; } .tm-page { padding: 0; } .tm-ask { break-inside: avoid; } }
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "truemap-cli",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
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
+ "repository": {
6
+ "type": "git",
7
+ "url": "git+https://github.com/TaoMachina/truemap.git"
8
+ },
9
+ "homepage": "https://github.com/TaoMachina/truemap#readme",
10
+ "bugs": {
11
+ "url": "https://github.com/TaoMachina/truemap/issues"
12
+ },
13
+ "type": "module",
14
+ "bin": {
15
+ "truemap": "bin/truemap.js"
16
+ },
17
+ "files": [
18
+ "bin/",
19
+ "src/",
20
+ "kit/",
21
+ "skills/",
22
+ "README.md",
23
+ "LICENSE"
24
+ ],
25
+ "engines": {
26
+ "node": ">=20"
27
+ },
28
+ "scripts": {
29
+ "test": "node --test"
30
+ },
31
+ "keywords": [
32
+ "agent",
33
+ "claude-code",
34
+ "codex",
35
+ "html",
36
+ "architecture",
37
+ "visualization",
38
+ "skill"
39
+ ],
40
+ "license": "MIT"
41
+ }
@@ -0,0 +1,22 @@
1
+ ---
2
+ name: truemap
3
+ description: Explain a codebase with living HTML pages the user can click, ask about, and decide on. Use when explaining architecture, a module, a flow, or a data model; when comparing options or needing the user to decide; when asked "how does X work" or "show me the project"; and whenever a .truemap/ folder exists and you are about to explain something it may already cover. Not for one-line answers.
4
+ allowed-tools: Bash(npx -y truemap-cli:*), Bash(npx truemap-cli:*), Bash(truemap:*)
5
+ license: MIT
6
+ ---
7
+
8
+ # truemap
9
+
10
+ Pages live in `.truemap/` at the repo root (`index.html` is the project blueprint). They stay with the project and are checked against the code.
11
+
12
+ Current instructions live in the CLI – this file stays short so it never goes stale:
13
+
14
+ - `npx -y truemap-cli --help` – commands and the chat loop
15
+ - `npx -y truemap-cli guide` – how to write pages: folder rules, `data-src` anchors, page kit, decision forms
16
+
17
+ Flow: look in `.truemap/` first → update or write the page → `npx -y truemap-cli <page>` → follow the `next_step` it prints.
18
+ Always also give the user a 1–3 line answer in the terminal.
19
+
20
+ ## Request
21
+
22
+ $ARGUMENTS
package/src/check.js ADDED
@@ -0,0 +1,248 @@
1
+ // The checker: a language-agnostic tripwire for data-src anchors.
2
+ // For each data-src="path#name":
3
+ // broken - path missing (exact case, relative to repo root) or name no longer present as a whole word
4
+ // changed - the anchored file/dir changed after the page was written (or last marked --ok)
5
+ // ok - otherwise
6
+ import { execFileSync } from 'node:child_process';
7
+ import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
8
+ import { join, relative, resolve, sep } from 'node:path';
9
+ import { FOLDER, gitExe } from './common.js';
10
+
11
+ const META_RE = /<meta\s+name=["']truemap-verified["']\s+content=["']([^"']*)["']\s*\/?>/i;
12
+ const ANCHOR_RE = /\bdata-src\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
13
+ const TITLE_RE = /<title[^>]*>([\s\S]*?)<\/title>/i;
14
+ const MAX_SCAN_BYTES = 4 * 1024 * 1024;
15
+
16
+ function git(root, args) {
17
+ const exe = gitExe();
18
+ if (!exe) return null;
19
+ try {
20
+ return execFileSync(exe, args, { cwd: root, stdio: ['ignore', 'pipe', 'ignore'], encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
21
+ } catch { return null; }
22
+ }
23
+
24
+ export function isGitRepo(root) {
25
+ return git(root, ['rev-parse', '--is-inside-work-tree'])?.trim() === 'true';
26
+ }
27
+
28
+ /** Resolves a page path given by a user/agent to a path inside .truemap, or null if it escapes. */
29
+ export function pageInFolder(root, page) {
30
+ const base = resolve(root, FOLDER);
31
+ const full = resolve(base, String(page || '').replace(/\\/g, '/'));
32
+ const rel = relative(base, full);
33
+ if (!rel || rel.startsWith('..') || resolve(base, rel) !== full) return null;
34
+ return rel.split(sep).join('/');
35
+ }
36
+
37
+ /** All HTML pages under .truemap (excluding assets/), index.html first. */
38
+ export function listPages(root) {
39
+ const base = join(root, FOLDER);
40
+ const out = [];
41
+ const walk = (dir) => {
42
+ let entries = [];
43
+ try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
44
+ for (const e of entries) {
45
+ if (e.name.startsWith('.')) continue;
46
+ const full = join(dir, e.name);
47
+ const rel = relative(base, full).split(sep).join('/');
48
+ if (e.isDirectory()) { if (rel !== 'assets') walk(full); continue; }
49
+ if (e.isFile() && /\.html?$/i.test(e.name)) out.push(rel);
50
+ }
51
+ };
52
+ walk(base);
53
+ out.sort((a, b) => (a === 'index.html' ? -1 : b === 'index.html' ? 1 : a.localeCompare(b)));
54
+ return out.map((page) => ({ page, title: readTitle(join(base, page)) || page.replace(/\.html?$/i, '') }));
55
+ }
56
+
57
+ function readTitle(file) {
58
+ try {
59
+ const m = readFileSync(file, 'utf8').match(TITLE_RE);
60
+ return m ? decodeEntities(m[1].trim()) : null;
61
+ } catch { return null; }
62
+ }
63
+
64
+ function decodeEntities(s) {
65
+ return s.replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&quot;/g, '"').replace(/&#39;/g, "'");
66
+ }
67
+
68
+ export function extractAnchors(html) {
69
+ const seen = new Set();
70
+ for (const m of html.matchAll(ANCHOR_RE)) {
71
+ const v = decodeEntities((m[1] ?? m[2] ?? '').trim());
72
+ if (v) seen.add(v);
73
+ }
74
+ return [...seen];
75
+ }
76
+
77
+ export function parseAnchor(raw) {
78
+ const i = raw.indexOf('#');
79
+ const path = (i === -1 ? raw : raw.slice(0, i)).replace(/\\/g, '/').replace(/^\.\//, '').replace(/^\/+/, '');
80
+ const name = i === -1 ? '' : raw.slice(i + 1).trim();
81
+ return { path, name };
82
+ }
83
+
84
+ // Last-commit times of clean paths don't change until HEAD moves: cache them across runs.
85
+ const logCache = new Map();
86
+
87
+ /** Builds a per-run context so repeated anchors don't re-run git. */
88
+ export function createContext(root) {
89
+ const gitRepo = isGitRepo(root);
90
+ let files = null; let dirty = new Set(); let head = '';
91
+ if (gitRepo) {
92
+ const tracked = git(root, ['ls-files', '-z']) ?? '';
93
+ const untracked = git(root, ['ls-files', '--others', '--exclude-standard', '-z']) ?? '';
94
+ files = new Set((tracked + untracked).split('\0').filter(Boolean));
95
+ head = (git(root, ['rev-parse', 'HEAD']) ?? '').trim();
96
+ // One status call per run; -z keeps paths unquoted. Renames carry the old path as an extra field.
97
+ const status = (git(root, ['status', '--porcelain', '-z', '--untracked-files=all']) ?? '').split('\0');
98
+ for (let i = 0; i < status.length; i++) {
99
+ const entry = status[i];
100
+ if (!entry) continue;
101
+ dirty.add(entry.slice(3));
102
+ if (entry[0] === 'R' || entry[0] === 'C') i++;
103
+ }
104
+ }
105
+ return { root, gitRepo, files, dirty, head, contents: new Map(), times: new Map() };
106
+ }
107
+
108
+ function onDisk(root, p) { try { statSync(join(root, p)); return true; } catch { return false; } }
109
+
110
+ function pathExists(ctx, p) {
111
+ if (!p) return { exists: false, isDir: false };
112
+ const clean = p.replace(/\/+$/, '');
113
+ if (ctx.files) {
114
+ if (ctx.files.has(clean)) return { exists: onDisk(ctx.root, clean), isDir: false };
115
+ const prefix = clean + '/';
116
+ for (const f of ctx.files) if (f.startsWith(prefix) && onDisk(ctx.root, f)) return { exists: true, isDir: true };
117
+ return { exists: false, isDir: false };
118
+ }
119
+ // No git: exact-case walk of each segment.
120
+ let dir = ctx.root;
121
+ for (const part of clean.split('/')) {
122
+ let names;
123
+ try { names = readdirSync(dir); } catch { return { exists: false, isDir: false }; }
124
+ if (!names.includes(part)) return { exists: false, isDir: false };
125
+ dir = join(dir, part);
126
+ }
127
+ try { return { exists: true, isDir: statSync(dir).isDirectory() }; } catch { return { exists: false, isDir: false }; }
128
+ }
129
+
130
+ function isDirty(ctx, p) {
131
+ if (ctx.dirty.has(p)) return true;
132
+ const prefix = p + '/';
133
+ for (const d of ctx.dirty) if (d.startsWith(prefix) || (d.endsWith('/') && p.startsWith(d))) return true;
134
+ return false;
135
+ }
136
+
137
+ function newestMtime(root, p) {
138
+ const full = join(root, p);
139
+ try {
140
+ const st = statSync(full);
141
+ if (!st.isDirectory()) return Math.floor(st.mtimeMs / 1000);
142
+ } catch { return Math.floor(Date.now() / 1000); }
143
+ let newest = 0;
144
+ const walk = (dir, depth) => {
145
+ if (depth > 6) return;
146
+ let entries = [];
147
+ try { entries = readdirSync(dir, { withFileTypes: true }); } catch { return; }
148
+ for (const e of entries) {
149
+ if (e.name === '.git' || e.name === 'node_modules') continue;
150
+ const f = join(dir, e.name);
151
+ if (e.isDirectory()) walk(f, depth + 1);
152
+ else { try { newest = Math.max(newest, statSync(f).mtimeMs); } catch { /* ignore */ } }
153
+ }
154
+ };
155
+ walk(full, 0);
156
+ return Math.floor(newest / 1000) || Math.floor(Date.now() / 1000);
157
+ }
158
+
159
+ /** Last-change time in seconds: mtime if dirty/untracked, else last commit time. Null without git. */
160
+ function changeTime(ctx, p) {
161
+ if (!ctx.gitRepo) return null;
162
+ if (ctx.times.has(p)) return ctx.times.get(p);
163
+ let t;
164
+ if (isDirty(ctx, p)) {
165
+ t = newestMtime(ctx.root, p);
166
+ } else {
167
+ const key = `${ctx.root}\0${ctx.head}\0${p}`;
168
+ if (logCache.has(key)) t = logCache.get(key);
169
+ else {
170
+ const n = parseInt((git(ctx.root, ['log', '-1', '--format=%ct', '--', p]) ?? '').trim(), 10);
171
+ t = Number.isFinite(n) ? n : Math.floor(Date.now() / 1000);
172
+ if (logCache.size > 20000) logCache.clear();
173
+ logCache.set(key, t);
174
+ }
175
+ }
176
+ ctx.times.set(p, t);
177
+ return t;
178
+ }
179
+
180
+ function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
181
+
182
+ /** True/false, or null when the file is too large to scan (then we don't call it broken). */
183
+ function hasWholeWord(ctx, p, name) {
184
+ let text = ctx.contents.get(p);
185
+ if (text === undefined) {
186
+ try {
187
+ const full = join(ctx.root, p);
188
+ text = statSync(full).size > MAX_SCAN_BYTES ? null : readFileSync(full, 'utf8');
189
+ } catch { text = ''; }
190
+ ctx.contents.set(p, text);
191
+ }
192
+ if (text === null) return null;
193
+ return new RegExp(`(?<![\\p{L}\\p{N}_$])${escapeRe(name)}(?![\\p{L}\\p{N}_$])`, 'u').test(text);
194
+ }
195
+
196
+ export function readVerified(html) {
197
+ const m = html.match(META_RE);
198
+ if (!m) return null;
199
+ const t = Date.parse(m[1]);
200
+ return Number.isFinite(t) ? Math.floor(t / 1000) : null;
201
+ }
202
+
203
+ /** Checks one page. Returns { page, anchors: [{src, path, name, state, reason}], counts }. */
204
+ export function checkPage(ctx, page) {
205
+ const file = join(ctx.root, FOLDER, page);
206
+ let html = '';
207
+ try { html = readFileSync(file, 'utf8'); } catch {
208
+ return { page, missing: true, anchors: [], counts: { ok: 0, changed: 0, broken: 0 } };
209
+ }
210
+ const pageTime = Math.max(changeTime(ctx, `${FOLDER}/${page}`) ?? 0, readVerified(html) ?? 0);
211
+ const anchors = extractAnchors(html).map((src) => {
212
+ const { path, name } = parseAnchor(src);
213
+ const { exists, isDir } = pathExists(ctx, path);
214
+ if (!exists) return { src, path, name, state: 'broken', reason: `path not found: ${path}` };
215
+ if (name && !isDir && hasWholeWord(ctx, path, name) === false) {
216
+ return { src, path, name, state: 'broken', reason: `"${name}" no longer appears in ${path}` };
217
+ }
218
+ const t = changeTime(ctx, path.replace(/\/+$/, ''));
219
+ if (t !== null && pageTime && t > pageTime) {
220
+ return { src, path, name, state: 'changed', reason: `${path} changed after this page was last updated` };
221
+ }
222
+ return { src, path, name, state: 'ok', reason: '' };
223
+ });
224
+ const counts = { ok: 0, changed: 0, broken: 0 };
225
+ for (const a of anchors) counts[a.state]++;
226
+ return { page, anchors, counts };
227
+ }
228
+
229
+ export function checkAll(root, pages) {
230
+ const ctx = createContext(root);
231
+ const list = pages ?? listPages(root).map((p) => p.page);
232
+ return { gitRepo: ctx.gitRepo, results: list.map((p) => checkPage(ctx, p)) };
233
+ }
234
+
235
+ /** Stamps the page as reviewed now, which clears its "changed" marks. */
236
+ export function markOk(root, page) {
237
+ const rel = pageInFolder(root, page);
238
+ if (!rel) return false;
239
+ const file = join(root, FOLDER, rel);
240
+ if (!existsSync(file)) return false;
241
+ let html = readFileSync(file, 'utf8');
242
+ const tag = `<meta name="truemap-verified" content="${new Date().toISOString()}">`;
243
+ if (META_RE.test(html)) html = html.replace(META_RE, tag);
244
+ else if (/<head[^>]*>/i.test(html)) html = html.replace(/<head[^>]*>/i, (m) => `${m}\n${tag}`);
245
+ else html = `${tag}\n${html}`;
246
+ writeFileSync(file, html);
247
+ return true;
248
+ }