spiega 0.1.1 → 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.1",
+  "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/test/smoke.mjs

@@ -656,6 +656,60 @@ 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