truemap-cli 0.2.0 → 0.5.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/src/check.js CHANGED
@@ -6,7 +6,8 @@
6
6
  import { execFileSync } from 'node:child_process';
7
7
  import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
8
8
  import { join, relative, resolve, sep } from 'node:path';
9
- import { FOLDER, gitExe } from './common.js';
9
+ import { createHash } from 'node:crypto';
10
+ import { FOLDER, gitExe, verifiedPath } from './common.js';
10
11
 
11
12
  const META_RE = /<meta\s+name=["']truemap-verified["']\s+content=["']([^"']*)["']\s*\/?>/i;
12
13
  const ANCHOR_RE = /\bdata-src\s*=\s*(?:"([^"]*)"|'([^']*)')/gi;
@@ -102,7 +103,9 @@ export function createContext(root) {
102
103
  if (entry[0] === 'R' || entry[0] === 'C') i++;
103
104
  }
104
105
  }
105
- return { root, gitRepo, files, dirty, head, contents: new Map(), times: new Map() };
106
+ let records = {};
107
+ try { records = JSON.parse(readFileSync(verifiedPath(root), 'utf8')); } catch { records = {}; }
108
+ return { root, gitRepo, files, dirty, head, contents: new Map(), times: new Map(), records, recordsDirty: false, prints: new Map() };
106
109
  }
107
110
 
108
111
  function onDisk(root, p) { try { statSync(join(root, p)); return true; } catch { return false; } }
@@ -177,6 +180,31 @@ function changeTime(ctx, p) {
177
180
  return t;
178
181
  }
179
182
 
183
+ // What an anchor's code looks like now: a hash of the file, or of a folder's file list with sizes and times.
184
+ // Drift is judged per anchor against the fingerprint taken when the box was last known to match, so editing
185
+ // the page (to add one box) does not quietly clear drift on the others.
186
+ function fingerprint(ctx, p) {
187
+ const clean = p.replace(/\/+$/, '');
188
+ if (ctx.prints.has(clean)) return ctx.prints.get(clean);
189
+ const h = createHash('sha1');
190
+ const full = join(ctx.root, clean);
191
+ try {
192
+ const st = statSync(full);
193
+ if (!st.isDirectory()) h.update(st.size > MAX_SCAN_BYTES ? `${st.size}:${st.mtimeMs}` : readFileSync(full));
194
+ else {
195
+ const list = ctx.files ? [...ctx.files].filter((x) => x.startsWith(`${clean}/`)).sort() : [];
196
+ for (const x of list) { try { const t = statSync(join(ctx.root, x)); h.update(`${x}\0${t.size}\0${Math.floor(t.mtimeMs)}\n`); } catch { /* gone */ } }
197
+ }
198
+ } catch { h.update('missing'); }
199
+ const out = h.digest('hex').slice(0, 16);
200
+ ctx.prints.set(clean, out);
201
+ return out;
202
+ }
203
+ function saveRecords(ctx) {
204
+ if (!ctx.recordsDirty) return;
205
+ try { writeFileSync(verifiedPath(ctx.root), JSON.stringify(ctx.records)); ctx.recordsDirty = false; } catch { /* ignore */ }
206
+ }
207
+
180
208
  function escapeRe(s) { return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&'); }
181
209
 
182
210
  /** True/false, or null when the file is too large to scan (then we don't call it broken). */
@@ -215,34 +243,128 @@ export function checkPage(ctx, page) {
215
243
  if (name && !isDir && hasWholeWord(ctx, path, name) === false) {
216
244
  return { src, path, name, state: 'broken', reason: `"${name}" no longer appears in ${path}` };
217
245
  }
246
+ const key = `${page}|${src}`;
247
+ const fp = fingerprint(ctx, path);
248
+ const rec = ctx.records[key];
249
+ const since = ctx.records[`@${key}`] || (pageTime ? new Date(pageTime * 1000).toISOString() : null);
250
+ if (rec !== undefined) {
251
+ return rec === fp ? { src, path, name, state: 'ok', reason: '' } : { src, path, name, state: 'changed', since, reason: `${path} changed since this box was last checked` };
252
+ }
253
+ // No fingerprint yet: fall back to times (code newer than the page), then remember the code as it is.
218
254
  const t = changeTime(ctx, path.replace(/\/+$/, ''));
219
255
  if (t !== null && pageTime && t > pageTime) {
220
- return { src, path, name, state: 'changed', reason: `${path} changed after this page was last updated` };
256
+ return { src, path, name, state: 'changed', since, reason: `${path} changed after this page was last updated` };
221
257
  }
258
+ ctx.records[key] = fp; ctx.records[`@${key}`] = new Date().toISOString(); ctx.recordsDirty = true;
222
259
  return { src, path, name, state: 'ok', reason: '' };
223
260
  });
224
261
  const counts = { ok: 0, changed: 0, broken: 0 };
225
262
  for (const a of anchors) counts[a.state]++;
226
- return { page, anchors, counts };
263
+ const wireCount = [...html.matchAll(/\sdata-to\s*=\s*["']([^"']*)["']/gi)].reduce((n, m) => n + m[1].split(/[\s,]+/).filter(Boolean).length, 0);
264
+ return { page, anchors, counts, wires: checkWires(html), wireCount, layout: checkLayout(html) };
265
+ }
266
+
267
+ /** Maps that are too big to read at a glance (the guide: at most 12 boxes per map, 4 per layer). */
268
+ export function checkLayout(html) {
269
+ const notes = [];
270
+ const NODE = /class=["'][^"']*\btm-node(?![-\w])/g;
271
+ const maps = html.split(/class=["'][^"']*\btm-(?:map|blueprint)(?![-\w])/).slice(1);
272
+ maps.forEach((body, i) => {
273
+ const total = (body.match(NODE) || []).length;
274
+ if (total > 16) notes.push(`map ${i + 1} has ${total} boxes; 16 is the most a map can carry, move the detail to a module page`);
275
+ body.split(/class=["'][^"']*\btm-layer(?![-\w])/).slice(1).forEach((layer, j) => {
276
+ const n = (layer.match(NODE) || []).length;
277
+ if (n > 4) notes.push(`map ${i + 1}, layer ${j + 1} has ${n} boxes; keep it to 4`);
278
+ });
279
+ });
280
+ return notes.concat(lintDiagrams(html));
281
+ }
282
+
283
+ /** The rules of a v0.5 map (figure.tm-diagram), checked so a page that breaks them is told why. */
284
+ export function lintDiagrams(html) {
285
+ const notes = [];
286
+ const attr = (tag, name) => { const m = tag.match(new RegExp(`\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)')`, 'i')); return m ? decodeEntities(m[1] ?? m[2] ?? '') : null; };
287
+ const figs = html.split(/<figure\b[^>]*class=["'][^"']*\btm-diagram\b[^"']*["'][^>]*>/i).slice(1).map((b) => b.split(/<\/figure>/i)[0]);
288
+ figs.forEach((body, i) => {
289
+ const where = figs.length > 1 ? `map ${i + 1}: ` : 'map: ';
290
+ const nodes = [...body.matchAll(/<(?:div|a)\b[^>]*class=["'][^"']*\btm-node\b[^"']*["'][^>]*>/gi)].map((m) => m[0]);
291
+ const ids = new Set(nodes.map((t) => attr(t, 'id')).filter(Boolean));
292
+ if (nodes.length > 16) notes.push(`${where}${nodes.length} boxes; 16 is the most a map can carry. Merge minor neighbours or give a part its own page.`);
293
+ const groups = (body.match(/<section\b[^>]*class=["'][^"']*\btm-group\b/gi) || []).length;
294
+ if (!groups && nodes.length > 4) notes.push(`${where}no groups. Put the boxes in <section class="tm-group" data-label="…"> by responsibility.`);
295
+ for (const sec of body.matchAll(/<section\b[^>]*class=["'][^"']*\btm-group\b[^>]*>([\s\S]*?)<\/section>/gi)) {
296
+ const n = (sec[1].match(/class=["'][^"']*\btm-node\b/gi) || []).length;
297
+ const label = sec[0].match(/data-label=["']([^"']+)/)?.[1] || 'a group';
298
+ if (n > 5) notes.push(`${where}group "${label}" has ${n} boxes; keep a group to 5 or fewer (split it by responsibility) so it reads as one row.`);
299
+ }
300
+ const outside = body.replace(/<section\b[^>]*class=["'][^"']*\btm-group\b[\s\S]*?<\/section>/gi, '');
301
+ const loose = (outside.match(/class=["'][^"']*\btm-node\b/gi) || []).length;
302
+ if (groups && loose) notes.push(`${where}${loose} box(es) outside any group; every box belongs to one group.`);
303
+ for (const t of nodes) {
304
+ const id = attr(t, 'id'); const name = attr(t, 'data-name'); const tag = attr(t, 'data-tag'); const label = name || id || '(a box)';
305
+ if (!id) notes.push(`${where}a box without an id ("${label}"); connections and flows need ids.`);
306
+ if (!name) notes.push(`${where}box "${id}" has no data-name.`);
307
+ else if (name.split(/\s+/).length > 4 || name.length > 28) notes.push(`${where}box name "${name}" is long; use 1-3 words from the code and put the rest in .tm-detail.`);
308
+ if (tag && (tag.split(/\s+/).length > 4 || tag.length > 32)) notes.push(`${where}tag "${tag}" on "${label}" is long; one short word or path fragment.`);
309
+ if (!attr(t, 'data-src') && !/\bis-ext\b/.test(attr(t, 'class') || '')) notes.push(`${where}box "${label}" has no data-src; anchor it to its code, or mark it is-ext if it is outside the code.`);
310
+ }
311
+ for (const m of body.matchAll(/<li\b[^>]*\sdata-path\s*=\s*["']([^"']*)["']/gi)) {
312
+ for (const id of m[1].split(/[\s,]+/).filter(Boolean)) if (!ids.has(id)) notes.push(`${where}flow step "${id}" is not a box id on this map.`);
313
+ }
314
+ });
315
+ if (figs.length && /<style\b|\sstyle\s*=\s*["'][^"']*(?:color|background|font|border)/i.test(html)) notes.push('page sets its own colours or fonts; the look is fixed so every map reads the same. Remove <style> and style="…".');
316
+ return notes;
317
+ }
318
+
319
+ /** Map wires whose data-to names an id that is not on the page (they would silently not be drawn). */
320
+ export function checkWires(html) {
321
+ const ID = /\sid\s*=\s*["']([^"']+)["']/i;
322
+ const ids = new Set([...html.matchAll(new RegExp(ID.source, 'gi'))].map((m) => m[1]));
323
+ const problems = [];
324
+ for (const m of html.matchAll(/<[^>]*\sdata-to\s*=\s*["']([^"']*)["'][^>]*>/gi)) {
325
+ const from = (m[0].match(ID) || [])[1] || '(a box without an id)';
326
+ for (const spec of m[1].split(/[\s,]+/).filter(Boolean)) {
327
+ const to = spec.split(':')[0];
328
+ if (!ids.has(to)) problems.push({ from, to, reason: `no element with id="${to}"` });
329
+ }
330
+ }
331
+ return problems;
227
332
  }
228
333
 
229
334
  export function checkAll(root, pages) {
230
335
  const ctx = createContext(root);
231
336
  const list = pages ?? listPages(root).map((p) => p.page);
232
- return { gitRepo: ctx.gitRepo, results: list.map((p) => checkPage(ctx, p)) };
337
+ const results = list.map((p) => checkPage(ctx, p));
338
+ saveRecords(ctx);
339
+ return { gitRepo: ctx.gitRepo, results };
233
340
  }
234
341
 
235
342
  /** Stamps the page as reviewed now, which clears its "changed" marks. */
236
- export function markOk(root, page) {
343
+ export function markOk(root, page, boxes) {
237
344
  const rel = pageInFolder(root, page);
238
345
  if (!rel) return false;
239
346
  const file = join(root, FOLDER, rel);
240
347
  if (!existsSync(file)) return false;
241
348
  let html = readFileSync(file, 'utf8');
242
349
  const tag = `<meta name="truemap-verified" content="${new Date().toISOString()}">`;
350
+ if (boxes?.length) { // one box: its fingerprint only
351
+ const ctx = createContext(root);
352
+ const only = new Set(boxes.flatMap((b) => { const t = html.match(new RegExp(`<[^>]*\\sid=["']${escapeRe(b)}["'][^>]*>`))?.[0]; return [b, t?.match(/data-src=["']([^"']+)/)?.[1]].filter(Boolean); }));
353
+ const anchors = extractAnchors(html);
354
+ const unknown = boxes.filter((b) => !anchors.includes(b) && !anchors.some((a) => only.has(a) && html.includes(`id="${b}"`)));
355
+ if (unknown.length) throw new Error(`no box with an anchor named ${unknown.join(', ')} on ${rel} (use a box id or its data-src)`);
356
+ for (const src of extractAnchors(html)) { if (!only.has(src)) continue; const { path } = parseAnchor(src); if (path) { ctx.records[`${rel}|${src}`] = fingerprint(ctx, path); ctx.records[`@${rel}|${src}`] = new Date().toISOString(); } }
357
+ ctx.recordsDirty = true; saveRecords(ctx);
358
+ return true;
359
+ }
243
360
  if (META_RE.test(html)) html = html.replace(META_RE, tag);
244
361
  else if (/<head[^>]*>/i.test(html)) html = html.replace(/<head[^>]*>/i, (m) => `${m}\n${tag}`);
245
362
  else html = `${tag}\n${html}`;
246
363
  writeFileSync(file, html);
364
+ // every box on the page matches its code as it is now
365
+ const ctx = createContext(root);
366
+ const only = boxes?.length ? new Set(boxes.flatMap((b) => { const tag = html.match(new RegExp(`<[^>]*\\sid=["']${escapeRe(b)}["'][^>]*>`))?.[0]; return [b, tag?.match(/data-src=["']([^"']+)/)?.[1]].filter(Boolean); })) : null;
367
+ for (const src of extractAnchors(html)) { if (only && !only.has(src)) continue; const { path } = parseAnchor(src); if (path) { ctx.records[`${rel}|${src}`] = fingerprint(ctx, path); ctx.records[`@${rel}|${src}`] = new Date().toISOString(); } }
368
+ ctx.recordsDirty = true; saveRecords(ctx);
247
369
  return true;
248
370
  }
package/src/cli.js CHANGED
@@ -9,6 +9,8 @@ import {
9
9
  } from './common.js';
10
10
  import { checkAll, listPages, markOk, pageInFolder } from './check.js';
11
11
  import { outline } from './outline.js';
12
+ import { exportPage } from './export.js';
13
+ import { writeFileSync } from 'node:fs';
12
14
 
13
15
  const CMD = process.env.TRUEMAP_CMD || 'npx -y truemap-cli';
14
16
 
@@ -139,11 +141,13 @@ function agentLoopHint() {
139
141
 
140
142
  function printCheck(result, indent = '') {
141
143
  const bad = result.anchors.filter((a) => a.state !== 'ok');
142
- out(`${indent}check: ${result.counts.ok} ok, ${result.counts.changed} changed, ${result.counts.broken} broken`);
144
+ out(`${indent}check: ${result.counts.ok} ok, ${result.counts.changed} changed, ${result.counts.broken} broken${result.wireCount ? `; wires: ${result.wireCount - (result.wires || []).length} of ${result.wireCount} drawn` : ''}`);
143
145
  for (const a of bad) out(`${indent} - ${a.state}: ${q(a.src)} # ${a.reason}`);
146
+ for (const w of result.wires || []) out(`${indent} - wire not drawn: ${q(w.from)} -> ${q(w.to)} # ${w.reason}`);
147
+ for (const l of result.layout || []) out(`${indent} - layout: ${l}`);
144
148
  }
145
149
 
146
- const SETUP_NOTE = `Visual explanations live in \`${FOLDER}/\` (index.html is the project blueprint). Before explaining architecture, a flow, or options: if a page covers it, update it and run \`${CMD} <page>\`. Create a new page only when the answer has 3+ interacting parts or needs a decision from the user. Always also give a 1-3 line answer in the terminal.`;
150
+ const SETUP_NOTE = `This project has a map in \`${FOLDER}/\` (index.html), checked against the code with truemap. Before a change that touches 3+ boxes on the map or adds one, show the plan first: \`${CMD} plan --file plan.json\`, and wait for approval. After editing code, run \`${CMD} changes\` so the user can review what changed, by box. Before explaining architecture or a flow, update the page that covers it and run \`${CMD} <page>\`. Run \`${CMD} guide\` for the details. Always also give a 1-3 line answer in the terminal.`;
147
151
 
148
152
  // ---------- commands ----------
149
153
  async function cmdOpen(root, args, opts = {}) {
@@ -164,7 +168,7 @@ async function cmdOpen(root, args, opts = {}) {
164
168
  await call(state, 'POST', '/api/agent/navigate', { page, agent: detectAgent(), ...(opts.annotate !== undefined ? { annotate: opts.annotate } : {}) });
165
169
  browser = 'reused the open tab';
166
170
  } else if (process.env.TRUEMAP_NO_OPEN || opts.noOpen) {
167
- browser = 'not opened (--no-open); give the user the url';
171
+ browser = 'not opened (--no-open or TRUEMAP_NO_OPEN); give the user the url';
168
172
  } else {
169
173
  openBrowser(url);
170
174
  browser = 'opened in the default browser (if no window appeared, give the user the url)';
@@ -181,13 +185,15 @@ async function cmdOpen(root, args, opts = {}) {
181
185
  block('setup_note', `Add this note to CLAUDE.md and AGENTS.md (create the section if missing) so future sessions use ${FOLDER}/:\n\n${SETUP_NOTE}`);
182
186
  }
183
187
  const steps = [];
184
- if (!page) steps.push(`No pages yet. Run \`${CMD} outline\` for a fast map of the repo and \`${CMD} guide\` for the page kit, write ${FOLDER}/index.html (the blueprint, 5-12 boxes), then run \`${CMD} index.html\`. Show a first blueprint within a few minutes; go deeper only when the user asks.`);
188
+ if (!page) steps.push(`No pages yet. Run \`${CMD} outline\` for a fast map of the repo and \`${CMD} guide\` for the format, write ${FOLDER}/index.html (one map, 7-12 boxes in groups), then run \`${CMD} index.html\`. Show a first map within a few minutes; go deeper only when the user asks.`);
185
189
  else {
186
190
  const r = checkAll(root, [page]).results[0];
187
191
  if (r.counts.broken) steps.push('Fix the broken anchors first: update the page (or its data-src) to match the code.');
188
192
  if (r.counts.changed) steps.push(`Review the changed anchors. If the page needs edits, update it; if it is still accurate, run \`${CMD} check --ok ${page}\`.`);
189
193
  }
190
- steps.push(agentLoopHint());
194
+ steps.push(detectAgent() === 'codex'
195
+ ? `If the user wants to talk about the page: ${agentLoopHint()} If they only wanted to see it, you are done.`
196
+ : agentLoopHint());
191
197
  steps.push('Also give the user a 1-3 line answer in the terminal.');
192
198
  block('next_step', steps.join('\n'));
193
199
  }
@@ -240,7 +246,7 @@ async function doListen(root, opts) {
240
246
  r = await call(state, 'POST', '/api/agent/listen', { timeoutMs, agent: detectAgent() });
241
247
  } catch {
242
248
  out('status: interrupted');
243
- block('next_step', `The connection dropped (the server restarted or stopped). Run \`${CMD}\` to reopen if needed, then \`${CMD} listen\` again.`);
249
+ block('next_step', 'The truemap server stopped (the user closed it, or `truemap stop` ran). Continue in the terminal. Do not reopen the page unless the user asks.');
244
250
  return;
245
251
  }
246
252
  const b = r.body || {};
@@ -249,13 +255,37 @@ async function doListen(root, opts) {
249
255
  formatMessages(b.messages);
250
256
  const decided = b.messages.filter((m) => m.kind === 'answer' && m.from === 'user');
251
257
  if (decided.length) block('decision_note', 'The user made a decision on the page. Act on it, and record it on the relevant page (what was chosen and why) so it stays with the project.');
258
+ const bg = detectAgent() === 'claude-code' ? ' with run_in_background' : '';
259
+ if (b.messages.some((m) => m.kind === 'approval')) {
260
+ block('next_step', [
261
+ 'The user APPROVED your plan. Build it now; changes are measured from this moment.',
262
+ `While you build, post short status lines with \`${CMD} progress "…"\`; no reply is needed to start.`,
263
+ `When done: put new boxes on the page for real (with data-src), run \`${CMD} plan --done\` and \`${CMD} changes\`, then \`${CMD} reply "<what you built, and anything you did not>" --listen\`${bg}.`,
264
+ ].join('\n'));
265
+ return;
266
+ }
267
+ if (b.messages.some((m) => m.kind === 'plan_changes')) {
268
+ block('next_step', [
269
+ 'The user asked for changes to your plan. Do not build yet.',
270
+ `1) Answer the comments in one short \`${CMD} reply "…"\` (without --listen).`,
271
+ `2) Write the revised plan (same title) and run \`${CMD} plan --file <plan.json>\`; it shows in the conversation by itself, with what changed.`,
272
+ `3) Then \`${CMD} listen\`${bg} for the approval. Only one listen runs at a time; a new one replaces the old.`,
273
+ ].join('\n'));
274
+ return;
275
+ }
252
276
  block('next_step', [
253
- 'Answer the user. Comments and selections carry a data-src: read that code before answering. Answer every numbered comment.',
277
+ b.messages.every((m) => m.kind === 'answer')
278
+ ? 'The user answered your question. Act on the choice now, and record the decision (what and why) on the relevant page.'
279
+ : 'Answer the user. Comments and selections carry a data-src: read that code before answering. Answer every numbered comment.',
254
280
  'If the answer changes the page (or the code it describes), update the page; the browser reloads by itself.',
255
281
  `Then run \`${CMD} reply "<answer>" --listen\`${detectAgent() === 'claude-code' ? ' with run_in_background' : ''}. Keep the reply short and concrete; use - lists and **bold** sparingly.`,
256
282
  ].join('\n'));
283
+ } else if (b.status === 'no_tab') {
284
+ block('next_step', `No truemap tab is open, so nobody can answer on the page. Open it with \`${CMD} <page>\` (the url it prints works too), then listen again; or continue in the terminal.`);
257
285
  } else if (b.status === 'browser_closed') {
258
286
  block('next_step', 'The user closed the truemap tab. Stop listening and continue in the terminal. Do not reopen the browser unless the user asks or something important needs their eyes.');
287
+ } else if (b.status === 'ended') {
288
+ block('next_step', 'The user ended the conversation on the page. Stop listening and continue in the terminal. Do not reopen or listen again unless the user asks.');
259
289
  } else if (b.status === 'replaced') {
260
290
  block('next_step', 'Another listen took over. Stop this one.');
261
291
  } else if (b.status === 'timeout') {
@@ -275,12 +305,138 @@ async function cmdReply(root, args, opts) {
275
305
  block('next_step', `truemap is not running. Give the answer in the terminal, or run \`${CMD}\` to reopen the page.`);
276
306
  return;
277
307
  }
278
- const r = await call(state, 'POST', '/api/agent/reply', { text, keepWorking: !!opts.working, willListen: !!opts.listen, agent: detectAgent() });
308
+ const r = await call(state, 'POST', '/api/agent/reply', { text, keepWorking: !!opts.working, willListen: !!opts.listen, agent: detectAgent(), focus: splitList(opts.focus), ...(opts.ask ? { ask: opts.ask } : {}) });
279
309
  if (r.status !== 200) throw new Error(`reply was rejected: ${r.body?.error || r.status}`);
280
- out(`reply: ${r.body?.browsers ? `shown in ${r.body.browsers} tab(s)` : 'saved (no tab open right now; the user sees it next time)'}`);
310
+ out(`${opts.ask ? 'asked' : 'reply'}: ${r.body?.browsers ? `shown in ${r.body.browsers} tab(s)` : 'saved (no tab open right now; the user sees it next time)'}`);
311
+ if (opts.listen && !r.body?.browsers) {
312
+ out('status: no_tab');
313
+ block('next_step', opts.ask
314
+ ? `Nobody has the page open, so the question waits there. Ask the same question in the terminal, or open the page (\`${CMD} <page>\`) and run \`${CMD} listen\`: the answer arrives through listen.`
315
+ : `Nobody has the page open; your reply waits there. Continue in the terminal, or open the page (\`${CMD} <page>\`) and run \`${CMD} listen\`.`);
316
+ return;
317
+ }
281
318
  if (opts.listen) await doListen(root, opts);
282
319
  }
283
320
 
321
+ const splitList = (v) => (v ? String(v).split(',').map((s) => s.trim()).filter(Boolean) : []);
322
+
323
+ async function cmdShow(root, args, opts) {
324
+ const state = await liveState(root);
325
+ if (!state) { out('status: no_server'); block('next_step', `truemap is not running. Run \`${CMD} <page>\` first.`); return; }
326
+ const page = args[0] ? resolvePage(root, args[0]) : '';
327
+ const r = await call(state, 'POST', '/api/agent/show', { page, focus: splitList(opts.focus), note: opts.note || '', clear: !!opts.clear, agent: detectAgent() });
328
+ out(`status: ${opts.clear ? 'cleared' : 'shown'}${r.body?.browsers ? '' : ' # no tab is open; nobody saw it'}`);
329
+ }
330
+
331
+ async function cmdAsk(root, args, opts) {
332
+ const question = args.join(' ').trim();
333
+ const options = (opts.option || []).map((o) => { const [label, ...why] = String(o).split('|'); return { label: label.trim(), why: why.join('|').trim() }; }).filter((o) => o.label);
334
+ if (!question || options.length < 2) throw new Error('ask needs a question and at least two --option "Label | why"');
335
+ opts.ask = { question, options };
336
+ opts.listen = true;
337
+ await cmdReply(root, [question], opts);
338
+ }
339
+
340
+ async function cmdChanges(root, args, opts) {
341
+ const state = (await liveState(root)) || await ensureServer(root);
342
+ const base = opts.base || 'auto';
343
+ const r = (await call(state, 'POST', '/api/agent/changes', { base, open: !opts.noOpen, agent: detectAgent() })).body || {};
344
+ if (r.error) { out('status: error'); out(`error: ${q(r.error)}`); return; }
345
+ out(`base: ${q(r.base.label)}`);
346
+ out(`files_changed: ${r.files} # +${r.add} -${r.del}`);
347
+ if (r.boxes.length) {
348
+ out('boxes: # boxes whose files changed (attribution is by file)');
349
+ for (const b of r.boxes) out(` - ${q(b.src)} +${b.add} -${b.del} files: ${b.files.map((f) => q(f.path)).join(', ')}`);
350
+ }
351
+ if (r.unmapped.length) {
352
+ out('not_on_the_map:');
353
+ for (const g of r.unmapped) out(` - ${q(g.folder)} ${g.files.map((f) => q(f.path) + (f.near ? ` (next to ${f.near.map(q).join(', ')}: if it belongs to that box, add it to its data-also)` : '')).join(', ')}`);
354
+ }
355
+ if (r.plan) {
356
+ const missing = r.plan.planned.filter((p) => !p.changed);
357
+ out(`plan: ${q(r.plan.title)} # ${r.plan.planned.length - missing.length} of ${r.plan.planned.length} planned boxes have changes (that is not proof they are done)`);
358
+ for (const p of r.plan.planned.filter((x) => x.changed)) out(` - planned, has changes: ${q(p.name || p.box)} files: ${p.files.map(q).join(', ')} # planned: ${q(p.what || '')}`);
359
+ for (const p of missing) out(` - planned, no changes: ${q(p.name || p.box)}${p.src ? '' : ' # no data-src on the page yet'} # planned: ${q(p.what || '')}`);
360
+ for (const u of r.plan.unplanned) out(` - changed but not in the plan: ${q(u)}`);
361
+ for (const st of r.plan.steps || []) {
362
+ const quiet = [...st.files.filter((x) => !x.changed).map((x) => x.path), ...st.boxes.filter((x) => !x.changed).map((x) => x.name)];
363
+ out(` - step ${st.n}${st.report ? ` (you reported: ${st.report.status})` : ''}: ${q(st.text)}${quiet.length ? ` # names ${quiet.map(q).join(', ')} with no changes` : ''}`);
364
+ if (st.conflict) out(` conflict: ${q(st.conflict)} # the user sees this at the top of the Changes view`);
365
+ if (st.rewritten) out(` report_history: ${q(st.rewritten)}`);
366
+ }
367
+ }
368
+ out(`browser: ${r.browsers ? 'the Changes view is open' : `no tab is open; run \`${CMD}\` to open the map`}`);
369
+ const steps = [];
370
+ 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
+ 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.');
373
+ 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
+ steps.push(agentLoopHint());
375
+ block('next_step', steps.join('\n'));
376
+ }
377
+
378
+ async function cmdPlan(root, args, opts) {
379
+ if (opts.approve || opts.done) {
380
+ const state = await liveState(root);
381
+ if (!state) { out('status: no_server'); return; }
382
+ const r = await call(state, 'POST', '/api/agent/plan', { status: opts.approve ? 'approved' : 'done', steps: opts.step || [], agent: detectAgent() });
383
+ if (r.status === 400 && r.body?.missing) {
384
+ out('status: report_needed');
385
+ out('steps: # say what happened to every step; the user sees your report beside the facts');
386
+ r.body.steps.forEach((st, i) => out(` ${i + 1}. ${q(st)}${r.body.missing.includes(i + 1) ? ' # not reported' : ''}`));
387
+ block('next_step', `Run \`${CMD} plan --done\` again with one --step per step: --step "1=done" --step "2=partly:the UI field is missing" --step "3=not_built:hub.ts does not start the watchdog yet". Statuses: done, partly, not_built, dropped (a note after a colon is required for all but done). Check each step against your diff first; be exact.`);
388
+ return;
389
+ }
390
+ if (r.status !== 200) throw new Error(r.body?.error || `plan update failed (${r.status})`);
391
+ out(`status: ${r.body.status}`);
392
+ out(`plan: ${q(r.body.plan)}`);
393
+ for (const st of r.body.check?.steps || []) {
394
+ if (st.conflict) out(`conflict: step ${st.n}: ${q(st.conflict)} # shown to the user in the conversation and the Changes view`);
395
+ if (st.rewritten) out(`report_history: step ${st.n}: ${q(st.rewritten)}`);
396
+ }
397
+ const missing = (r.body.check?.planned || []).filter((p) => !p.changed);
398
+ if (missing.length) {
399
+ out('warning: some planned boxes have no changes in their files # tell the user which parts of the plan are not built');
400
+ for (const p of missing) out(` - ${q(p.name || p.box)} # ${q(p.what || '')}`);
401
+ }
402
+ block('next_step', opts.approve
403
+ ? `The plan is approved; changes are measured from now. Build it. When you are done, put the new boxes on the page for real (with data-src), run \`${CMD} plan --done\`, then \`${CMD} changes\` so the user can review what you did.`
404
+ : `The plan is closed. Run \`${CMD} changes\` to show the user what changed.`);
405
+ return;
406
+ }
407
+ if (!opts.file) throw new Error(`plan needs --file plan.json (or --file - to read stdin); see \`${CMD} guide\` for the format`);
408
+ let raw;
409
+ try { raw = JSON.parse(opts.file === '-' ? readFileSync(0, 'utf8') : readFileSync(resolve(opts.file), 'utf8')); } catch (e) { throw new Error(`could not read the plan: ${e.message}`); }
410
+ ensureFolder(root);
411
+ const state = await ensureServer(root);
412
+ const r = await call(state, 'POST', '/api/agent/plan', { plan: raw, agent: detectAgent() });
413
+ if (r.status !== 200) throw new Error(`plan rejected: ${r.body?.error || r.status}`);
414
+ const url = `http://127.0.0.1:${state.port}/?t=${state.token}#page=${encodeURIComponent(r.body.page)}`;
415
+ if (!r.body.browsers && !process.env.TRUEMAP_NO_OPEN && !opts.noOpen) openBrowser(url);
416
+ let drawable = true;
417
+ try { drawable = /class=["'][^"']*\btm-diagram\b/.test(readFileSync(join(folderPath(root), r.body.page), 'utf8')); } catch { /* the server already checked the page */ }
418
+ if (!drawable) {
419
+ out('status: plan_not_drawn');
420
+ out(`page: ${q(r.body.page)} # an older .tm-map page: the plan shows in the conversation as text, not on the map`);
421
+ block('next_step', [
422
+ `Convert ${r.body.page} to the current map first: rewrite its <div class="tm-map"> as <figure class="tm-diagram">: each .tm-layer becomes a <section class="tm-group" data-label="…">, each box keeps its id, data-src and data-to and gets data-name / data-tag (see \`${CMD} guide\`, THE MAP). Run \`${CMD} check ${r.body.page}\`.`,
423
+ `Then run \`${CMD} plan --file <plan.json>\` again. Until then the user can only approve from the text.`,
424
+ ].join('\n'));
425
+ return;
426
+ }
427
+ out('status: plan_shown');
428
+ for (const w of r.body.warnings || []) out(`warning: ${w}`);
429
+ if ((r.body.warnings || []).length) out('# fix the plan and run plan --file again: entries that name nothing are not drawn');
430
+ out(`plan: ${q(r.body.slug)} # ${FOLDER}/plans/${r.body.slug}.json, revision ${r.body.revision}`);
431
+ out(`page: ${q(r.body.page)}`);
432
+ out(`url: ${url}`);
433
+ block('next_step', [
434
+ 'Tell the user in the terminal, in 1-3 lines, what the plan does and that they can review it on the map (or just say "go" here).',
435
+ `Do not start building yet. Wait for the review: ${agentLoopHint()}`,
436
+ `If the user says "go" in the terminal instead, run \`${CMD} plan --approve\` and start.`,
437
+ ].join('\n'));
438
+ }
439
+
284
440
  async function cmdProgress(root, args) {
285
441
  const state = await liveState(root);
286
442
  if (!state) return out('status: no_server');
@@ -291,8 +447,8 @@ async function cmdProgress(root, args) {
291
447
  async function cmdCheck(root, args, opts) {
292
448
  if (opts.ok) {
293
449
  const page = resolvePage(root, opts.ok);
294
- if (!markOk(root, page)) throw new Error(`page not found: ${FOLDER}/${page}`);
295
- out(`status: marked ${q(page)} as reviewed`);
450
+ if (!markOk(root, page, opts.box)) throw new Error(`page not found: ${FOLDER}/${page}`);
451
+ out(opts.box?.length ? `status: marked ${opts.box.map(q).join(', ')} on ${q(page)} as matching the code # other boxes keep their marks` : `status: marked every box on ${q(page)} as matching the code`);
296
452
  const state = await liveState(root);
297
453
  if (state) await call(state, 'POST', '/api/check', {}).catch(() => {});
298
454
  return;
@@ -300,17 +456,20 @@ async function cmdCheck(root, args, opts) {
300
456
  const pages = args.length ? args.map((a) => resolvePage(root, a)) : undefined;
301
457
  const { gitRepo, results } = checkAll(root, pages);
302
458
  out(`status: checked ${results.length} page(s)${gitRepo ? '' : ' (no git: only missing paths/names are checked)'}`);
303
- let changed = 0; let broken = 0;
459
+ let changed = 0; let broken = 0; let wires = 0;
304
460
  for (const r of results) {
305
461
  out(`- page: ${q(r.page)}`);
306
462
  if (r.missing) { out(' missing: true'); continue; }
307
463
  printCheck(r, ' ');
308
- changed += r.counts.changed; broken += r.counts.broken;
464
+ changed += r.counts.changed; broken += r.counts.broken; wires += (r.wires || []).length;
309
465
  }
310
466
  const steps = [];
311
467
  if (broken) steps.push('Broken anchors: the code moved or was removed. Update those pages (content and data-src).');
312
468
  if (changed) steps.push(`Changed anchors: review the code. Update the page if needed, otherwise run \`${CMD} check --ok <page>\`.`);
313
- if (!broken && !changed) steps.push('All pages match the code.');
469
+ 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
+ const layout = results.reduce((n, r) => n + (r.layout || []).length, 0);
471
+ if (layout) steps.push('Map notes: fix each one; they are what keeps a map readable at a glance (see `' + CMD + ' guide`, THE MAP).');
472
+ if (!broken && !changed && !wires && !layout) steps.push('All pages match the code.');
314
473
  block('next_step', steps.join('\n'));
315
474
  }
316
475
 
@@ -321,6 +480,17 @@ async function cmdStop(root) {
321
480
  out('status: stopped');
322
481
  }
323
482
 
483
+ function cmdExport(root, args, opts) {
484
+ const page = resolvePage(root, args[0] || 'index.html');
485
+ const html = exportPage(root, page);
486
+ const outPath = resolve(opts.out || `${page.split('/').pop().replace(/\.html?$/i, '')}-truemap.html`);
487
+ writeFileSync(outPath, html);
488
+ out(`status: exported`);
489
+ out(`file: ${q(outPath)}`);
490
+ out(`size_kb: ${Math.round(Buffer.byteLength(html) / 1024)}`);
491
+ block('next_step', 'One self-contained file: kit, fonts and wires are inside. Links to other pages only work next to the .truemap folder.');
492
+ }
493
+
324
494
  function cmdOutline(root) {
325
495
  const o = outline(root);
326
496
  out(`root: ${q(o.name)}`);
@@ -330,7 +500,7 @@ function cmdOutline(root) {
330
500
  out('tree: # folder, files, approx lines, biggest files');
331
501
  for (const d of o.dirs) out(` - ${q(d.path)} files=${d.files} lines=${d.lines} ${d.top.join(', ')}`);
332
502
  if (o.entries.length) out(`likely_entry_points: ${o.entries.map(q).join(', ')}`);
333
- block('next_step', `Read the manifests and entry points (not every file), then write ${FOLDER}/index.html: one layer per role (entry points, modules, storage, external), 5-12 boxes, data-to wires along the main path, data-src on every box. Run \`${CMD} guide\` for the kit if you have not.`);
503
+ 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.`);
334
504
  }
335
505
 
336
506
  function cmdGuide() {
@@ -342,7 +512,6 @@ function help() {
342
512
 
343
513
  usage:
344
514
  ${CMD} [page] open a page from ${FOLDER}/ (default: index.html) in the user's browser
345
- ${CMD} <page> --annotate open it with comment mode on (when you want the user's review)
346
515
  ${CMD} listen [--timeout s] wait for the user's next message from the page chat
347
516
  ${CMD} reply "<text>" [--listen] [--file path|-]
348
517
  show your answer in the page chat (--listen: then wait for the next message)
@@ -350,6 +519,16 @@ usage:
350
519
  ${CMD} check --ok <page> mark a page as reviewed after its code changed
351
520
  ${CMD} outline a compact map of the repo (folders, sizes, entry points) for a fast first blueprint
352
521
  ${CMD} guide how to write pages: folder rules, data-src, page kit, decisions
522
+ ${CMD} export <page> [--out f] write the page as one self-contained HTML file to share
523
+ ${CMD} show [page] --focus id,id [--note "…"]
524
+ point at the map while you explain: light up boxes (ids or data-src), add a note
525
+ ${CMD} reply "…" --focus id,id answer and light up the boxes the answer is about
526
+ ${CMD} ask "<question>" --option "A | why" --option "B | why"
527
+ ask the user to choose, only when you are blocked on a real trade-off
528
+ ${CMD} plan --file plan.json before a change that touches 3+ boxes or adds one: show the plan on the map for review
529
+ ${CMD} plan --approve|--done the user said "go" in the terminal / the plan is built
530
+ ${CMD} changes [--base turn|plan|head|main]
531
+ what changed, by box; opens the Changes view for the user
353
532
  ${CMD} progress "<text>" show a short status line in the chat while you work
354
533
  ${CMD} stop stop the background server
355
534
 
@@ -371,6 +550,16 @@ function parseArgs(argv) {
371
550
  else if (a === '--timeout') opts.timeout = argv[++i];
372
551
  else if (a === '--file') opts.file = argv[++i];
373
552
  else if (a === '--ok') opts.ok = argv[++i];
553
+ else if (a === '--out') opts.out = argv[++i];
554
+ else if (a === '--focus') opts.focus = argv[++i];
555
+ else if (a === '--note') opts.note = argv[++i];
556
+ else if (a === '--clear') opts.clear = true;
557
+ else if (a === '--base') opts.base = argv[++i];
558
+ else if (a === '--approve') opts.approve = true;
559
+ else if (a === '--done') opts.done = true;
560
+ else if (a === '--step') (opts.step ||= []).push(argv[++i]);
561
+ else if (a === '--box') (opts.box ||= []).push(argv[++i]);
562
+ else if (a === '--option') (opts.option ||= []).push(argv[++i]);
374
563
  else if (a === '--help' || a === '-h') opts.help = true;
375
564
  else if (a === '--version' || a === '-v') opts.version = true;
376
565
  else args.push(a);
@@ -381,7 +570,7 @@ function parseArgs(argv) {
381
570
  export async function main(argv) {
382
571
  const { args, opts } = parseArgs(argv);
383
572
  if (opts.version) return out(VERSION);
384
- const commands = { listen: cmdListen, reply: cmdReply, check: cmdCheck, stop: cmdStop, guide: cmdGuide, progress: cmdProgress, outline: cmdOutline, help };
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 };
385
574
  const name = args[0] && commands[args[0]] ? args.shift() : null;
386
575
  if (opts.help || name === 'help') return help();
387
576
  const root = findRoot();
package/src/common.js CHANGED
@@ -73,9 +73,12 @@ export function rootKey(root) {
73
73
  return createHash('sha1').update(CASE_INSENSITIVE_FS ? r.toLowerCase() : r).digest('hex').slice(0, 16);
74
74
  }
75
75
 
76
+ export function serversDir() { return stateSubdir('servers'); }
76
77
  export function serverStatePath(root) { return join(stateSubdir('servers'), `${rootKey(root)}.json`); }
77
78
  export function serverLockPath(root) { return join(stateSubdir('servers'), `${rootKey(root)}.lock`); }
78
79
  export function historyPath(root) { return join(stateSubdir('history'), `${rootKey(root)}.jsonl`); }
80
+ export function verifiedPath(root) { return join(stateSubdir('verified'), `${rootKey(root)}.json`); }
81
+ export function snapshotsPath(root) { return join(stateSubdir('snapshots'), `${rootKey(root)}.json`); }
79
82
 
80
83
  export function readJson(file) {
81
84
  try { return JSON.parse(readFileSync(file, 'utf8')); } catch { return null; }
package/src/export.js ADDED
@@ -0,0 +1,62 @@
1
+ // Turns a .truemap page into one self-contained HTML file: the kit, fonts, local images and the
2
+ // wire drawing are inlined, so it opens anywhere (email, a PR, a shared drive) without truemap running.
3
+ import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from 'node:fs';
4
+ import { dirname, extname, join, relative, resolve, sep } from 'node:path';
5
+ import { FOLDER, PKG_DIR, VERSION } from './common.js';
6
+
7
+ const KIT_DIR = join(PKG_DIR, 'kit');
8
+ const UI_DIR = join(PKG_DIR, 'src', 'ui');
9
+ const IMG = { '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml' };
10
+
11
+ /** A file inside dir, refusing traversal and symlinks that lead out. */
12
+ export function insideFile(dir, rel) {
13
+ try {
14
+ if (lstatSync(dir).isSymbolicLink()) return null;
15
+ const full = resolve(dir, '.' + sep + String(rel).replace(/\//g, sep));
16
+ if (full !== dir && !full.startsWith(dir + sep)) return null;
17
+ if (!existsSync(full)) return null;
18
+ const real = realpathSync(full); const realDir = realpathSync(dir);
19
+ if (!real.startsWith(realDir + sep) || statSync(real).isDirectory()) return null;
20
+ return real;
21
+ } catch { return null; }
22
+ }
23
+
24
+ /** The page kit as served: a repo's own assets/truemap.css wins; assets/theme.css is appended. */
25
+ 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;
32
+ }
33
+
34
+ export function exportPage(root, page) {
35
+ const folder = join(root, FOLDER);
36
+ const file = insideFile(folder, page);
37
+ if (!file) throw new Error(`page not found: ${FOLDER}/${page}`);
38
+ let html = readFileSync(file, 'utf8');
39
+ const pageDir = dirname(file);
40
+
41
+ // Fonts become data URIs so the export looks the same offline.
42
+ const css = kitCss(root).replace(/url\("\/__truemap\/fonts\/([\w.-]+\.woff2)"\)/g, (m, name) => {
43
+ const f = join(KIT_DIR, 'fonts', name);
44
+ return existsSync(f) ? `url("data:font/woff2;base64,${readFileSync(f).toString('base64')}")` : m;
45
+ });
46
+ const kitLink = /<link\b[^>]*href=["'](?:\.\.\/)*assets\/truemap\.css["'][^>]*>/i;
47
+ html = kitLink.test(html) ? html.replace(kitLink, () => `<style>\n${css}\n</style>`) : html.replace(/<\/head>/i, () => `<style>\n${css}\n</style>\n</head>`);
48
+
49
+ // Local images next to the page.
50
+ html = html.replace(/(<img\b[^>]*\bsrc=["'])([^"':]+?)(["'])/gi, (m, a, src, b) => {
51
+ const type = IMG[extname(src).toLowerCase()];
52
+ const f = type && insideFile(folder, relative(folder, join(pageDir, src)).split(sep).join('/'));
53
+ return f ? `${a}data:${type};base64,${readFileSync(f).toString('base64')}${b}` : m;
54
+ });
55
+
56
+ const wires = [join(UI_DIR, 'wires.js'), join(UI_DIR, 'diagram.js')].map((f) => readFileSync(f, 'utf8')).join('\n;\n');
57
+ const boot = `<script>\n${wires}\n(() => { const d = () => { window.truemapDiagram.draw(); window.truemapWires.draw(); window.truemapWires.mark && window.truemapWires.mark(); }; window.truemapWires.interact(); window.truemapDiagram.interact(); if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', d); else d(); addEventListener('resize', d); document.fonts && document.fonts.ready.then(d); })();\n</script>`;
58
+ const stamp = `<!-- Exported by truemap ${VERSION} from ${FOLDER}/${page} on ${new Date().toISOString().slice(0, 10)}. Links to other pages need the .truemap folder. -->`;
59
+ const note = `<p style="max-width:960px;margin:0 auto;padding:0 48px 40px;font:13px/1.5 var(--tm-font);color:var(--tm-pencil)">Exported from <code>${FOLDER}/${page}</code> with truemap. Links to other pages work inside the project's ${FOLDER} folder.</p>`;
60
+ html = /<\/body>/i.test(html) ? html.replace(/<\/body>(?![\s\S]*<\/body>)/i, () => `${note}\n${boot}\n</body>`) : html + note + boot;
61
+ return /<!doctype[^>]*>/i.test(html) ? html.replace(/<!doctype[^>]*>/i, (d) => `${d}\n${stamp}`) : `${stamp}\n${html}`;
62
+ }