truemap-cli 0.3.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,15 +243,25 @@ 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, wires: checkWires(html), layout: checkLayout(html) };
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) };
227
265
  }
228
266
 
229
267
  /** Maps that are too big to read at a glance (the guide: at most 12 boxes per map, 4 per layer). */
@@ -233,12 +271,48 @@ export function checkLayout(html) {
233
271
  const maps = html.split(/class=["'][^"']*\btm-(?:map|blueprint)(?![-\w])/).slice(1);
234
272
  maps.forEach((body, i) => {
235
273
  const total = (body.match(NODE) || []).length;
236
- if (total > 12) notes.push(`map ${i + 1} has ${total} boxes; 12 or fewer reads at a glance, split the rest into a module page`);
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`);
237
275
  body.split(/class=["'][^"']*\btm-layer(?![-\w])/).slice(1).forEach((layer, j) => {
238
276
  const n = (layer.match(NODE) || []).length;
239
277
  if (n > 4) notes.push(`map ${i + 1}, layer ${j + 1} has ${n} boxes; keep it to 4`);
240
278
  });
241
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="…".');
242
316
  return notes;
243
317
  }
244
318
 
@@ -260,20 +334,37 @@ export function checkWires(html) {
260
334
  export function checkAll(root, pages) {
261
335
  const ctx = createContext(root);
262
336
  const list = pages ?? listPages(root).map((p) => p.page);
263
- 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 };
264
340
  }
265
341
 
266
342
  /** Stamps the page as reviewed now, which clears its "changed" marks. */
267
- export function markOk(root, page) {
343
+ export function markOk(root, page, boxes) {
268
344
  const rel = pageInFolder(root, page);
269
345
  if (!rel) return false;
270
346
  const file = join(root, FOLDER, rel);
271
347
  if (!existsSync(file)) return false;
272
348
  let html = readFileSync(file, 'utf8');
273
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
+ }
274
360
  if (META_RE.test(html)) html = html.replace(META_RE, tag);
275
361
  else if (/<head[^>]*>/i.test(html)) html = html.replace(/<head[^>]*>/i, (m) => `${m}\n${tag}`);
276
362
  else html = `${tag}\n${html}`;
277
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);
278
369
  return true;
279
370
  }
package/src/cli.js CHANGED
@@ -141,13 +141,13 @@ function agentLoopHint() {
141
141
 
142
142
  function printCheck(result, indent = '') {
143
143
  const bad = result.anchors.filter((a) => a.state !== 'ok');
144
- 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` : ''}`);
145
145
  for (const a of bad) out(`${indent} - ${a.state}: ${q(a.src)} # ${a.reason}`);
146
146
  for (const w of result.wires || []) out(`${indent} - wire not drawn: ${q(w.from)} -> ${q(w.to)} # ${w.reason}`);
147
147
  for (const l of result.layout || []) out(`${indent} - layout: ${l}`);
148
148
  }
149
149
 
150
- 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.`;
151
151
 
152
152
  // ---------- commands ----------
153
153
  async function cmdOpen(root, args, opts = {}) {
@@ -185,7 +185,7 @@ async function cmdOpen(root, args, opts = {}) {
185
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}`);
186
186
  }
187
187
  const steps = [];
188
- 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.`);
189
189
  else {
190
190
  const r = checkAll(root, [page]).results[0];
191
191
  if (r.counts.broken) steps.push('Fix the broken anchors first: update the page (or its data-src) to match the code.');
@@ -246,7 +246,7 @@ async function doListen(root, opts) {
246
246
  r = await call(state, 'POST', '/api/agent/listen', { timeoutMs, agent: detectAgent() });
247
247
  } catch {
248
248
  out('status: interrupted');
249
- 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.');
250
250
  return;
251
251
  }
252
252
  const b = r.body || {};
@@ -255,11 +255,33 @@ async function doListen(root, opts) {
255
255
  formatMessages(b.messages);
256
256
  const decided = b.messages.filter((m) => m.kind === 'answer' && m.from === 'user');
257
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
+ }
258
276
  block('next_step', [
259
- '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.',
260
280
  'If the answer changes the page (or the code it describes), update the page; the browser reloads by itself.',
261
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.`,
262
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.`);
263
285
  } else if (b.status === 'browser_closed') {
264
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.');
265
287
  } else if (b.status === 'ended') {
@@ -283,12 +305,138 @@ async function cmdReply(root, args, opts) {
283
305
  block('next_step', `truemap is not running. Give the answer in the terminal, or run \`${CMD}\` to reopen the page.`);
284
306
  return;
285
307
  }
286
- 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 } : {}) });
287
309
  if (r.status !== 200) throw new Error(`reply was rejected: ${r.body?.error || r.status}`);
288
- 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
+ }
289
318
  if (opts.listen) await doListen(root, opts);
290
319
  }
291
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
+
292
440
  async function cmdProgress(root, args) {
293
441
  const state = await liveState(root);
294
442
  if (!state) return out('status: no_server');
@@ -299,8 +447,8 @@ async function cmdProgress(root, args) {
299
447
  async function cmdCheck(root, args, opts) {
300
448
  if (opts.ok) {
301
449
  const page = resolvePage(root, opts.ok);
302
- if (!markOk(root, page)) throw new Error(`page not found: ${FOLDER}/${page}`);
303
- 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`);
304
452
  const state = await liveState(root);
305
453
  if (state) await call(state, 'POST', '/api/check', {}).catch(() => {});
306
454
  return;
@@ -320,7 +468,7 @@ async function cmdCheck(root, args, opts) {
320
468
  if (changed) steps.push(`Changed anchors: review the code. Update the page if needed, otherwise run \`${CMD} check --ok <page>\`.`);
321
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).');
322
470
  const layout = results.reduce((n, r) => n + (r.layout || []).length, 0);
323
- if (layout) steps.push('Layout notes: a map over 12 boxes (or a layer over 4) is hard to read. Keep the main parts on the map and move the detail to a module page.');
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).');
324
472
  if (!broken && !changed && !wires && !layout) steps.push('All pages match the code.');
325
473
  block('next_step', steps.join('\n'));
326
474
  }
@@ -352,7 +500,7 @@ function cmdOutline(root) {
352
500
  out('tree: # folder, files, approx lines, biggest files');
353
501
  for (const d of o.dirs) out(` - ${q(d.path)} files=${d.files} lines=${d.lines} ${d.top.join(', ')}`);
354
502
  if (o.entries.length) out(`likely_entry_points: ${o.entries.map(q).join(', ')}`);
355
- 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 with labels, data-src on every box that stands for code. 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.`);
356
504
  }
357
505
 
358
506
  function cmdGuide() {
@@ -364,7 +512,6 @@ function help() {
364
512
 
365
513
  usage:
366
514
  ${CMD} [page] open a page from ${FOLDER}/ (default: index.html) in the user's browser
367
- ${CMD} <page> --annotate open it with comment mode on (when you want the user's review)
368
515
  ${CMD} listen [--timeout s] wait for the user's next message from the page chat
369
516
  ${CMD} reply "<text>" [--listen] [--file path|-]
370
517
  show your answer in the page chat (--listen: then wait for the next message)
@@ -373,6 +520,15 @@ usage:
373
520
  ${CMD} outline a compact map of the repo (folders, sizes, entry points) for a fast first blueprint
374
521
  ${CMD} guide how to write pages: folder rules, data-src, page kit, decisions
375
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
376
532
  ${CMD} progress "<text>" show a short status line in the chat while you work
377
533
  ${CMD} stop stop the background server
378
534
 
@@ -395,6 +551,15 @@ function parseArgs(argv) {
395
551
  else if (a === '--file') opts.file = argv[++i];
396
552
  else if (a === '--ok') opts.ok = argv[++i];
397
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]);
398
563
  else if (a === '--help' || a === '-h') opts.help = true;
399
564
  else if (a === '--version' || a === '-v') opts.version = true;
400
565
  else args.push(a);
@@ -405,7 +570,7 @@ function parseArgs(argv) {
405
570
  export async function main(argv) {
406
571
  const { args, opts } = parseArgs(argv);
407
572
  if (opts.version) return out(VERSION);
408
- const commands = { listen: cmdListen, reply: cmdReply, check: cmdCheck, stop: cmdStop, guide: cmdGuide, progress: cmdProgress, outline: cmdOutline, export: cmdExport, 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 };
409
574
  const name = args[0] && commands[args[0]] ? args.shift() : null;
410
575
  if (opts.help || name === 'help') return help();
411
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 CHANGED
@@ -53,8 +53,8 @@ export function exportPage(root, page) {
53
53
  return f ? `${a}data:${type};base64,${readFileSync(f).toString('base64')}${b}` : m;
54
54
  });
55
55
 
56
- const wires = readFileSync(join(UI_DIR, 'wires.js'), 'utf8');
57
- const boot = `<script>\n${wires}\n(() => { const d = () => window.truemapWires.draw(); if (document.readyState === 'loading') document.addEventListener('DOMContentLoaded', d); else d(); addEventListener('resize', d); document.fonts && document.fonts.ready.then(d); })();\n</script>`;
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
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
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
60
  html = /<\/body>/i.test(html) ? html.replace(/<\/body>(?![\s\S]*<\/body>)/i, () => `${note}\n${boot}\n</body>`) : html + note + boot;