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/README.md +31 -26
- package/kit/fonts/OFL-commit-mono.txt +90 -0
- package/kit/fonts/OFL-instrument-sans.txt +93 -0
- package/kit/fonts/commit-mono-latin-400-normal.woff2 +0 -0
- package/kit/fonts/instrument-sans-latin-400-normal.woff2 +0 -0
- package/kit/fonts/instrument-sans-latin-500-normal.woff2 +0 -0
- package/kit/fonts/instrument-sans-latin-600-normal.woff2 +0 -0
- package/kit/truemap.css +185 -66
- package/package.json +1 -1
- package/skills/truemap/SKILL.md +9 -5
- package/src/changes.js +155 -0
- package/src/check.js +128 -6
- package/src/cli.js +206 -17
- package/src/common.js +3 -0
- package/src/export.js +62 -0
- package/src/guide.md +128 -102
- package/src/plan.js +185 -0
- package/src/server.js +207 -17
- package/src/snippet.js +63 -0
- package/src/ui/diagram.js +598 -0
- package/src/ui/sdk.js +327 -132
- package/src/ui/wires.js +329 -0
- package/src/ui/workspace.css +340 -145
- package/src/ui/workspace.html +38 -14
- package/src/ui/workspace.js +539 -57
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 {
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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 = `
|
|
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
|
|
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(
|
|
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',
|
|
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
|
-
|
|
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(
|
|
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
|
|
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 (
|
|
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
|
|
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
|
+
}
|