spiega 0.1.0 → 0.1.2

package/README.md

@@ -176,6 +176,54 @@ never built. `spiega doctor` finds it:
 It exits non-zero when something is wrong, so it can go in a shell prompt or a
 pre-flight check. It makes no network calls and changes nothing.
 
+### Developing on spiega, or just using it
+
+Installing the package changes the **command**. It does not change the **agent
+setup files**, and those are what an agent actually reads. The two move
+independently, which is the whole reason this section exists:
+
+| | set by | points at |
+|---|---|---|
+| the `spiega` command | `npm install -g` / `npm link` | whichever you ran last |
+| skills, MCP entries, `AGENTS.md` blocks | **`spiega install`** | wherever spiega was *when you ran it* |
+
+So `npm install -g spiega` on a machine that once had the repo linked leaves
+every agent still loading the working tree — uncommitted edits and all — while
+`spiega` on your own PATH runs the published copy. Nothing warns you: both work,
+and they are different code.
+
+`spiega doctor` is what tells you, and it names the path it found:
+
+```
+  ✗ claude skill   linked to ~/Documents/…/spiega/skills/spiega, not this install
+  ✗ claude MCP     points at ~/Documents/…/spiega/src/mcp/server.js
+```
+
+**To use the published version**, as anyone else would:
+
+```bash
+npm install -g spiega
+spiega install          # rewires skills and MCP to the installed copy, backing up what it replaces
+```
+
+**To go back to developing**, with agents reading your working tree:
+
+```bash
+cd spiega && npm link
+spiega install
+```
+
+Two things that bite:
+
+- **Restart your agent sessions.** A running MCP server holds the code it was
+  launched with, so until it restarts it keeps serving the old location
+  whatever the config now says. `doctor` counts these.
+- **Check `which -a spiega`, not `which spiega`.** An older install may have
+  left a launcher in `~/.local/bin` or `/opt/homebrew/bin` with an absolute
+  path baked in. Those shadow the npm copy or are shadowed by it depending on
+  PATH order — and an agent's non-interactive shell often has a different PATH
+  than yours.
+
 ### If you use herdr
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "spiega",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "A hand-drawn board an AI agent draws on while it explains software architecture.",
   "type": "module",
   "bin": {

package/src/doctor.js

@@ -47,11 +47,43 @@ const bad = (what, detail, fix) => ({ level: 'bad', what, detail, fix });
 
 const tilde = p => String(p).replace(HOME, '~');
 
+/* Most people meet spiega through `npm install -g`, where there is no
+   checkout and the word is simply wrong. Developers run it from a clone,
+   where "install" would be equally wrong. One word, decided once. */
+const THIS = () => (isCheckout() ? 'this checkout' : 'this install');
+
+/* Is ROOT itself a repository? `git -C` walks up, so containment is not
+   enough — see checkout() for what that cost. */
+let _isCheckout = null;
+function isCheckout() {
+  if (_isCheckout === null) {
+    const top = sh('git', ['-C', ROOT, 'rev-parse', '--show-toplevel']);
+    try {
+      _isCheckout = Boolean(top) && fs.existsSync(top) &&
+        fs.realpathSync(top) === fs.realpathSync(ROOT);
+    } catch { _isCheckout = false; }
+  }
+  return _isCheckout;
+}
+
 /* ---------- the checkout ---------- */
 
 function checkout(rows) {
-  const head = sh('git', ['-C', ROOT, 'rev-parse', '--short', 'HEAD']);
-  if (!head) { rows.push(warn('checkout', 'not a git checkout, so there is nothing to compare against')); return 0; }
+  /* `git -C <dir>` walks UP until it finds a repository, so asking it about a
+     directory that is not one answers about whatever encloses it. Installed
+     from npm under nvm — which is itself a git clone — that is nvm: doctor
+     reported nvm's HEAD as "this checkout", nvm's dirty file as uncommitted
+     work, and then measured every skill and MCP entry against it. A page of
+     red crosses, all meaningless, on the most ordinary install there is.
+
+     So the repository has to BE this directory, not merely contain it. */
+  const head = isCheckout() ? sh('git', ['-C', ROOT, 'rev-parse', '--short', 'HEAD']) : null;
+  if (!head) {
+    rows.push(warn('checkout', sh('git', ['-C', ROOT, 'rev-parse', '--show-toplevel'])
+      ? 'installed from npm, not a checkout — nothing to compare against'
+      : 'not a git checkout, so there is nothing to compare against'));
+    return 0;
+  }
 
   const when = Number(sh('git', ['-C', ROOT, 'log', '-1', '--format=%ct']) || 0) * 1000;
   const subject = sh('git', ['-C', ROOT, 'log', '-1', '--format=%s']) || '';
@@ -159,8 +191,8 @@ function invocation(rows) {
 
   const mine = [path.resolve(ROOT, 'bin', 'spiega'), path.resolve(ROOT, 'src', 'cli.js')];
   rows.push(mine.includes(real)
-    ? ok('spiega is this checkout', `${tilde(which)} → ${tilde(real)}`)
-    : bad('spiega is this checkout', `${tilde(which)} → ${tilde(real)}, which is NOT this checkout`,
+    ? ok(`spiega is ${THIS()}`, `${tilde(which)} → ${tilde(real)}`)
+    : bad(`spiega is ${THIS()}`, `${tilde(which)} → ${tilde(real)}, which is NOT ${THIS()}`,
         'spiega install'));
 
   const floor = nodeFloor();
@@ -212,8 +244,8 @@ function skills(rows) {
     if (st.isSymbolicLink()) {
       const to = fs.readlinkSync(dest);
       rows.push(to === SKILL_SRC
-        ? ok(`${name} skill`, 'linked — tracks the checkout')
-        : bad(`${name} skill`, `linked to ${tilde(to)}, not this checkout`, `spiega install ${name}`));
+        ? ok(`${name} skill`, isCheckout() ? 'linked — tracks the checkout' : 'linked')
+        : bad(`${name} skill`, `linked to ${tilde(to)}, not ${THIS()}`, `spiega install ${name}`));
       continue;
     }
     // a copy: current only until the source changes, so compare it
@@ -283,7 +315,7 @@ function registrations(rows) {
     const entry = pick(readJSON(file));
     if (!entry) { rows.push(warn(`${name} MCP`, 'not registered', `spiega install ${name}`)); continue; }
     rows.push(entry === MCP_ENTRY
-      ? ok(`${name} MCP`, 'points at this checkout')
+      ? ok(`${name} MCP`, `points at ${THIS()}`)
       : bad(`${name} MCP`, `points at ${tilde(entry)}`, `spiega install ${name}`));
   }
   // Codex keeps its servers in TOML
@@ -292,8 +324,8 @@ function registrations(rows) {
     const raw = fs.readFileSync(toml, 'utf8');
     const has = /^\s*\[mcp_servers\.spiega\]/m.test(raw);
     rows.push(has && raw.includes(MCP_ENTRY)
-      ? ok('codex MCP', 'points at this checkout')
-      : warn('codex MCP', has ? 'registered, but not at this checkout' : 'not registered', 'spiega install codex'));
+      ? ok('codex MCP', `points at ${THIS()}`)
+      : warn('codex MCP', has ? `registered, but not at ${THIS()}` : 'not registered', 'spiega install codex'));
   }
 }
 

package/src/render/edges.js

@@ -146,8 +146,94 @@ function edgeTag(at, step, label, { lit, seed }) {
   });
 }
 
-/* `state` is 'idle' | 'lit' | 'dim' — the board lights one path at a time. */
-export function drawEdge(r, { step = null, state = 'idle' } = {}) {
+/* Where one tag wants to sit, and how big it is, with no knowledge of the
+   others. On a short hop between neighbouring boxes the tag is wider than the
+   gap, so centring it on the line buries it under whatever is next door. Lift
+   it clear of both boxes instead — nudging it a few pixels is not enough,
+   since a box is far taller than the line is thick. `away` records which way
+   it was lifted, so that if it later has to move again it keeps going the way
+   it already went rather than back across the line it belongs to. */
+/**
+ * @param {any} r
+ * @param {number|null} step
+ */
+export function tagBox(r, step) {
+  const { e } = r;
+  const label = (step != null ? String(step) + '  ' : '') + (e.label || '');
+  const spot = tagSpot(r.pts);
+  const w = lettering(label).length * 6.51 + 20;
+  let at = spot.at, away = 0;
+  if (w > spot.len * 0.95) {
+    const { a, b } = r;
+    if (!spot.vertical) {
+      away = b.x >= a.x ? -1 : 1;
+      at = away < 0
+        ? [spot.at[0], Math.min(a.y, b.y) - 13]
+        : [spot.at[0], Math.max(a.y + a.h, b.y + b.h) + 13];
+    } else {
+      at = b.y >= a.y
+        ? [Math.max(a.x + a.w, b.x + b.w) + w / 2 + 10, spot.at[1]]
+        : [Math.min(a.x, b.x) - w / 2 - 10, spot.at[1]];
+    }
+  }
+  return { at, w, h: 19, away };
+}
+
+/* Tags are placed one edge at a time, which is exactly why they collide: a
+   node that fans out sends several edges through the same gutter, each lifts
+   its tag clear of the same box, and they all land on the same spot. Nothing
+   downstream can tell, because each pill draws itself happily on top of the
+   last. So resolve them together, once, before any of them is drawn.
+
+   Order matters for stability: left to right, then top to bottom, so adding an
+   edge on the right never reshuffles the tags on the left. A tag that was
+   lifted keeps being pushed the way it was lifted; one sitting on its own line
+   moves to whichever side is nearer, since either reads fine. */
+/**
+ * @param {any[]} planned
+ * @param {(r: any) => number|null} [stepFor]
+ * @returns {Map<string, number[]>}
+ */
+export function planTags(planned, stepFor = () => null) {
+  const PAD = 4;
+  const placed = [];
+  const out = new Map();
+  const items = planned
+    .map(r => ({ r, ...tagBox(r, stepFor(r)) }))
+    .filter(t => {
+      const { e } = t.r;
+      return e.label || stepFor(t.r) != null;
+    })
+    .sort((p, q) => (p.at[0] - q.at[0]) || (p.at[1] - q.at[1]));
+
+  const hits = (a, b) =>
+    Math.abs(a.at[0] - b.at[0]) < (a.w + b.w) / 2 + PAD &&
+    Math.abs(a.at[1] - b.at[1]) < (a.h + b.h) / 2 + PAD;
+
+  for (const t of items) {
+    // bounded: each pass moves clear of one neighbour, and there are finitely
+    // many. The cap stops a pathological spec from spinning here.
+    for (let guard = 0; guard < 40; guard++) {
+      const clash = placed.find(p => hits(p, t));
+      if (!clash) break;
+      const dir = t.away || (t.at[1] >= clash.at[1] ? 1 : -1);
+      t.at = [t.at[0], clash.at[1] + dir * ((t.h + clash.h) / 2 + PAD)];
+      t.away = dir;
+    }
+    placed.push(t);
+    out.set(t.r.key, t.at);
+  }
+  return out;
+}
+
+/* `state` is 'idle' | 'lit' | 'dim' — the board lights one path at a time.
+   `place` is the anchor planTags settled on; without one the tag places itself,
+   which is right for a lone edge and wrong for a fan. */
+/**
+ * @param {any} r
+ * @param {{step?: number|null, state?: string, place?: number[]|null}} [opts]
+ */
+export function drawEdge(r, { step = null, state = 'idle', place = null } = {}) {
   const { e, pts } = r;
   const seed = hashSeed(r.key) % 100000;
   const lit = state === 'lit', dim = state === 'dim';
@@ -170,21 +256,7 @@ export function drawEdge(r, { step = null, state = 'idle' } = {}) {
     // a box is far taller than the line is thick. A pair of edges running both
     // ways between the same two boxes splits above and below, so the two tags
     // do not then collide with each other.
-    const label = (step != null ? String(step) + '  ' : '') + (e.label || '');
-    const need = label.length * 6.5 + 20;
-    let at = spot.at;
-    if (need > spot.len * 0.95) {
-      const { a, b } = r;
-      if (!spot.vertical) {
-        at = b.x >= a.x
-          ? [spot.at[0], Math.min(a.y, b.y) - 13]
-          : [spot.at[0], Math.max(a.y + a.h, b.y + b.h) + 13];
-      } else {
-        at = b.y >= a.y
-          ? [Math.max(a.x + a.w, b.x + b.w) + need / 2 + 10, spot.at[1]]
-          : [Math.min(a.x, b.x) - need / 2 - 10, spot.at[1]];
-      }
-    }
+    const at = place || tagBox(r, step).at;
     out += `<g class="tag">${edgeTag(at, step, e.label, { lit, seed: seed + 5 })}</g>`;
   }
   return out + `</g>`;

package/src/render/render.js

@@ -10,7 +10,7 @@
 import { PAPER, INK, MUTED, ACCENT, PANEL, handFilter } from './theme.js';
 import { roughRect, stroke, fill, text, hashSeed } from './ink.js';
 import { drawNode, drawBoundary } from './glyphs.js';
-import { drawEdge, planEdges, edgeKey } from './edges.js';
+import { drawEdge, planEdges, planTags, edgeKey } from './edges.js';
 import { planCallouts, drawCallout } from './callout.js';
 import { assign, layout, boundaryBox } from './layout.js';
 
@@ -104,10 +104,14 @@ export function renderSVG(spec, { active, placed = null, margin = 0, hand = true
   }
 
   const planned = planEdges(edges, boxes);
+  /** @param {{e: any, key: string}} r */
+  const stepFor = r => (r.e.step != null ? r.e.step : (stepOf[r.key] ?? null));
+  // every tag resolved against every other before any is drawn, or two edges
+  // leaving the same box land their pills on the same spot
+  const tags = planTags(planned, stepFor);
   for (const r of planned) {
     const state = !focus ? 'idle' : focus.edges.has(r.key) ? 'lit' : 'dim';
-    const step = r.e.step != null ? r.e.step : (stepOf[r.key] ?? null);
-    body += drawEdge(r, { step, state });
+    body += drawEdge(r, { step: stepFor(r), state, place: tags.get(r.key) || null });
   }
 
   for (const n of nodes) {

package/test/smoke.mjs

@@ -656,6 +656,107 @@ test('colour and glyphs stay out of piped output', async () => {
   assert.ok(short.endsWith('spiega'), 'the end is what names it');
 });
 
+/* `git -C <dir>` walks UP until it finds a repository. npm's global prefix
+   under nvm sits inside nvm's own clone, so doctor answered about nvm:
+   reporting its HEAD as "this checkout", its dirty file as uncommitted work,
+   and then measuring every skill and MCP entry against it. The install is the
+   ordinary one — most people get Node from nvm — so the output almost nobody
+   should see was the output almost everybody got. */
+test('doctor does not mistake an enclosing repo for its own checkout', async () => {
+  const cp = await import('node:child_process');
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'spiega-enclosed-'));
+  try {
+    const git = (...a) => cp.execFileSync('git', ['-C', tmp, ...a],
+      { stdio: 'pipe', encoding: 'utf8' });
+    git('init', '-q');
+    fs.writeFileSync(path.join(tmp, 'f'), 'x');
+    git('add', '-A');
+    git('-c', 'user.email=t@t', '-c', 'user.name=t', '-c', 'commit.gpgsign=false',
+      'commit', '-qm', 'the enclosing repo, not spiega');
+    fs.writeFileSync(path.join(tmp, 'dirty'), 'uncommitted');
+
+    // the package, copied in with no .git of its own — an npm install
+    const pkg = path.join(tmp, 'lib', 'node_modules', 'spiega');
+    fs.mkdirSync(pkg, { recursive: true });
+    for (const d of ['src', 'bin', 'skills', 'integrations']) {
+      if (fs.existsSync(path.join(ROOT, d))) fs.cpSync(path.join(ROOT, d), path.join(pkg, d), { recursive: true });
+    }
+    fs.copyFileSync(path.join(ROOT, 'package.json'), path.join(pkg, 'package.json'));
+
+    const home = path.join(tmp, 'home');
+    fs.mkdirSync(home, { recursive: true });
+    // doctor exits non-zero whenever it finds anything to report, which here
+    // it will — the point is what it says, not what it returns
+    let out;
+    try {
+      out = cp.execFileSync(process.execPath, [path.join(pkg, 'src', 'cli.js'), 'doctor'], {
+        encoding: 'utf8',
+        env: { HOME: home, PATH: '/usr/bin:/bin', SPIEGA_ASCII: '1', NO_COLOR: '1' },
+      });
+    } catch (e) {
+      out = String(e.stdout || '');
+      assert.ok(out, `doctor produced no output: ${e.stderr || e.message}`);
+    }
+
+    const line = out.split('\n').find(l => /\bcheckout\b/.test(l)) || '';
+    assert.match(line, /not a checkout/,
+      `doctor claimed a checkout it does not have: ${line.trim()}`);
+    assert.ok(!/the enclosing repo/.test(out),
+      'the enclosing repo\'s commit must not appear anywhere in the report');
+    assert.ok(!/uncommitted changes/.test(out),
+      'nor its dirty working tree');
+  } finally {
+    fs.rmSync(tmp, { recursive: true, force: true });
+  }
+});
+
+/* A node that fans out sends several edges through the same gutter. Each tag
+   lifts itself clear of the same box, independently, and lands in the same
+   place — and nothing downstream notices, because each pill draws over the
+   last. The shipped example did exactly this: "4 CHARGE" sat under "5 INSERT",
+   which is the first picture anyone renders. Overlap is the assertion; a
+   screenshot is the only other way to see it, and tests do not look. */
+test('edge tags from the same box do not land on top of each other', async () => {
+  const { renderSVG } = await import('../src/render/render.js');
+
+  const tagRects = svg => [...svg.matchAll(/<g class="tag">([\s\S]*?)<\/g>/g)]
+    .map(m => {
+      const t = /<text[^>]*x="([-\d.]+)"[^>]*y="([-\d.]+)"[^>]*>([\s\S]*?)<\/text>/.exec(m[1]);
+      return t && { x: +t[1], y: +t[2], label: t[3], w: t[3].length * 6.51 + 20, h: 19 };
+    })
+    .filter(Boolean);
+
+  const overlaps = rs => {
+    const bad = [];
+    for (let i = 0; i < rs.length; i++)
+      for (let j = i + 1; j < rs.length; j++)
+        if (Math.abs(rs[i].x - rs[j].x) < (rs[i].w + rs[j].w) / 2 &&
+            Math.abs(rs[i].y - rs[j].y) < rs[i].h)
+          bad.push(`${rs[i].label} / ${rs[j].label}`);
+    return bad;
+  };
+
+  // the spec that ships, and the one that regressed
+  const example = JSON.parse(fs.readFileSync(path.join(ROOT, 'examples/order-flow.json'), 'utf8'));
+  const shipped = tagRects(renderSVG(example).svg);
+  assert.ok(shipped.length >= 7, `expected the example's tags, got ${shipped.length}`);
+  assert.deepEqual(overlaps(shipped), [], 'the example renders with its labels legible');
+
+  // a wider fan than the example has, so the resolver is tested past one clash
+  const fan = {
+    nodes: [{ id: 'hub', label: 'Hub' },
+      ...Array.from({ length: 6 }, (_, i) => ({ id: `n${i}`, label: `Target ${i}` }))],
+    edges: Array.from({ length: 6 }, (_, i) =>
+      ({ from: 'hub', to: `n${i}`, label: `a fairly long edge label ${i}` })),
+  };
+  const fanned = tagRects(renderSVG(fan).svg);
+  assert.equal(fanned.length, 6, 'every edge still gets its tag');
+  assert.deepEqual(overlaps(fanned), [], 'six tags out of one box all stay readable');
+
+  // and the resolver has to be stable: same spec, same answer
+  assert.equal(renderSVG(fan).svg, renderSVG(fan).svg, 'layout does not drift between renders');
+});
+
 test('the herdr plugin declares the actions it ships, and its scripts are runnable', () => {
   const dir = path.join(ROOT, 'integrations/herdr');
   const toml = fs.readFileSync(path.join(dir, 'herdr-plugin.toml'), 'utf8');