wikifier 4.4.0__tar.gz → 4.5.1__tar.gz

{wikifier-4.4.0/wikifier.egg-info → wikifier-4.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.4.0
+Version: 4.5.1
 Summary: Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents.
 Author-email: Aron Amos <aron@example.com>
 Maintainer: Aron Amos
@@ -137,6 +137,10 @@ Works with Claude Desktop, Claude Code, Cursor, Cline, and any Model Context Pro
 
 ## The Human Layer (Secondary, by Design)
 
+![Wikifier human dashboard — the project file tree with agent-wiki descriptions, health pills, and one-click Run/Stop controls, served locally by wikifier serve](https://raw.githubusercontent.com/IronAdamant/wikifier/main/screenshot/front_page_review.png)
+
+*The dashboard served by `wikifier serve`: live file tree with wiki descriptions, health status pills, and action buttons that run `update-maps`/`check-changes` directly (localhost-only) — plus a Stop server button for when you're done.*
+
 `wikifier init` copies a single static `index.html` into your project: a dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. View it with **`wikifier serve`** (then open http://localhost:8787/index.html) — browsers block `file://` fetches, so a double-clicked index.html can't read the wiki files; the page detects that case and shows you the fix. When served by `wikifier serve`, the dashboard's buttons genuinely **run** `update-maps`/`check-changes` (whitelisted commands only, localhost-only) and a **Stop server** button shuts the process down when you're done; behind any plain static server the same buttons fall back to copy + auto-refresh. The agent-facing markdown files and tools remain the single source of truth.
 
 ## Intended Use: Strictly Agent-to-Agent

{wikifier-4.4.0 → wikifier-4.5.1}/README.md

@@ -105,6 +105,10 @@ Works with Claude Desktop, Claude Code, Cursor, Cline, and any Model Context Pro
 
 ## The Human Layer (Secondary, by Design)
 
+![Wikifier human dashboard — the project file tree with agent-wiki descriptions, health pills, and one-click Run/Stop controls, served locally by wikifier serve](https://raw.githubusercontent.com/IronAdamant/wikifier/main/screenshot/front_page_review.png)
+
+*The dashboard served by `wikifier serve`: live file tree with wiki descriptions, health status pills, and action buttons that run `update-maps`/`check-changes` directly (localhost-only) — plus a Stop server button for when you're done.*
+
 `wikifier init` copies a single static `index.html` into your project: a dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. View it with **`wikifier serve`** (then open http://localhost:8787/index.html) — browsers block `file://` fetches, so a double-clicked index.html can't read the wiki files; the page detects that case and shows you the fix. When served by `wikifier serve`, the dashboard's buttons genuinely **run** `update-maps`/`check-changes` (whitelisted commands only, localhost-only) and a **Stop server** button shuts the process down when you're done; behind any plain static server the same buttons fall back to copy + auto-refresh. The agent-facing markdown files and tools remain the single source of truth.
 
 ## Intended Use: Strictly Agent-to-Agent

{wikifier-4.4.0 → wikifier-4.5.1}/index.html

@@ -136,13 +136,34 @@
     .console.show { display: block; }
     .hint { font-size: 12px; color: var(--faint); margin-top: 8px; }
 
-    /* ---------- mermaid ---------- */
-    #map-wrap {
-        margin-top: 12px; padding: 10px; min-height: 160px;
+    /* ---------- file tree (primary structure view) ---------- */
+    #tree-pre {
+        margin: 12px 0 0; padding: 14px 16px; max-height: 520px; overflow: auto;
         background: var(--panel-2); border: 1px solid var(--border-soft);
-        border-radius: 12px; overflow: auto;
+        border-radius: 12px; font-family: var(--mono); font-size: 12.5px;
+        line-height: 1.5; color: #c4cedb; white-space: pre;
+    }
+
+    /* ---------- dependency graph (collapsible, pan/zoom) ---------- */
+    details.graph { margin-top: 14px; }
+    details.graph > summary {
+        cursor: pointer; font-size: 13px; font-weight: 600; color: var(--muted);
+        padding: 9px 12px; border: 1px solid var(--border); border-radius: 10px;
+        list-style: none; user-select: none;
+    }
+    details.graph > summary::before { content: '▸ '; color: var(--accent); }
+    details.graph[open] > summary::before { content: '▾ '; }
+    details.graph > summary:hover { background: #15202f; }
+    #graph-viewport {
+        margin-top: 10px; height: 460px; overflow: hidden; cursor: grab;
+        background: var(--panel-2); border: 1px solid var(--border-soft);
+        border-radius: 12px; position: relative;
     }
+    #graph-viewport.dragging { cursor: grabbing; }
+    #graph-canvas { transform-origin: 0 0; width: max-content; }
+    #map-wrap { padding: 10px; min-height: 120px; }
     #map-wrap svg { max-width: none; }
+    .graph-help { font-size: 11.5px; color: var(--faint); margin-top: 6px; }
     .errbox {
         font-size: 13px; padding: 14px; border: 1px solid #92600c;
         border-radius: 10px; background: #171207;
@@ -246,15 +267,23 @@
         <div class="hint" id="actions-hint"></div>
     </section>
 
-    <!-- ============ structure map ============ -->
+    <!-- ============ structure: file tree (primary) + dependency graph ============ -->
     <section class="card">
-        <h2>Code structure <span class="sub">imports &amp; dependencies, rebuilt from your code</span></h2>
-        <div id="map-wrap"><div class="hint">loading map…</div></div>
+        <h2>Code structure <span class="sub">file tree with wiki descriptions — rebuilt from your code</span></h2>
+        <pre id="tree-pre">loading…</pre>
         <div class="btnrow" style="margin-top:12px">
-            <button id="btn-copy-mermaid">⧉ Copy structure as text</button>
+            <button id="btn-copy-tree">⧉ Copy structure as text</button>
             <button id="btn-copy-snapshot">⧉ Copy full snapshot (tree + files + descriptions)</button>
-            <span class="hint" style="margin:0">Paste directly into docs or LLM chats.</span>
+            <span class="hint" style="margin:0">Clean, readable text — paste directly into docs or LLM chats.</span>
         </div>
+        <details class="graph" id="graph-details">
+            <summary>Dependency graph (drag to pan · scroll to zoom · double-click to reset)</summary>
+            <div id="graph-viewport"><div id="graph-canvas"><div id="map-wrap"><div class="hint" style="padding:10px">expand to render…</div></div></div></div>
+            <div class="btnrow" style="margin-top:8px">
+                <button id="btn-copy-mermaid">⧉ Copy diagram source (Mermaid)</button>
+                <span class="graph-help">Arrows: solid = high-confidence import · dashed = medium · “?” = low/unresolved.</span>
+            </div>
+        </details>
     </section>
 
     <!-- ============ files + folders ============ -->
@@ -281,8 +310,8 @@
 
 <div id="toast"></div>
 <div id="overlay"><div class="panel">
-    <h2>Server stopped</h2>
-    <p>The <code>wikifier serve</code> process has shut down and this page is now frozen.
+    <h2 id="overlay-title">Server stopped</h2>
+    <p id="overlay-msg">The <code>wikifier serve</code> process has shut down and this page is now frozen.
        To come back, run <code>wikifier serve</code> in the project folder again and reload.</p>
 </div></div>
 
@@ -303,7 +332,13 @@ const state = {
     jsonMissing: false,       // remember a file_health.json 404 — stop re-polling it
     running: false,
     liveWaitTimer: null,
+    pollTimer: null,
     lastDataSig: '',
+    failStreak: 0,            // consecutive artifact-fetch failures (server gone?)
+    halted: false,
+    graphRendered: false,     // dependency graph renders lazily on first expand
+    graphDirty: true,
+    panZoom: { scale: 1, x: 0, y: 0 },
 };
 
 const $ = id => document.getElementById(id);
@@ -316,12 +351,26 @@ async function safeFetch(path, fallbackText = '') {
         const res = await fetch(path, ctrl ? { signal: ctrl.signal, cache: 'no-store' } : { cache: 'no-store' });
         if (timer) clearTimeout(timer);
         if (!res.ok) throw new Error('HTTP ' + res.status);
+        state.failStreak = 0;
         return await res.text();
     } catch (e) {
+        // Network-level failures (server killed) count toward the halt
+        // threshold; HTTP errors (404 on optional files) do not.
+        if (!String(e.message || '').startsWith('HTTP ')) state.failStreak++;
         return fallbackText;
     }
 }
 
+function haltDashboard(title, msg) {
+    if (state.halted) return;
+    state.halted = true;
+    if (state.pollTimer) clearInterval(state.pollTimer);
+    if (state.liveWaitTimer) clearInterval(state.liveWaitTimer);
+    $('overlay-title').textContent = title;
+    $('overlay-msg').innerHTML = msg;
+    $('overlay').classList.add('show');
+}
+
 function toast(msg, ms = 2200) {
     const t = $('toast');
     t.textContent = msg;
@@ -383,12 +432,13 @@ async function detectServer() {
 async function stopServer() {
     if (!state.execMode) return;
     if (!confirm('Stop the wikifier serve process? The dashboard will go offline.')) return;
+    const done = () => haltDashboard('Server stopped',
+        'The <code>wikifier serve</code> process has shut down and this page is now frozen. ' +
+        'To come back, run <code>wikifier serve</code> in the project folder again and reload.');
     try {
         const res = await fetch('/__wikifier/shutdown', { method: 'POST' });
-        if (res.ok) { $('overlay').classList.add('show'); return; }
-    } catch (e) { /* connection may drop as it stops — that also means success */
-        $('overlay').classList.add('show'); return;
-    }
+        if (res.ok) { done(); return; }
+    } catch (e) { done(); return; }  // connection drop while stopping = success
     toast('Could not stop the server');
 }
 
@@ -581,20 +631,35 @@ function renderFolders() {
     }).join('') || '<div class="hint">No files tracked yet — run check-changes / update-maps.</div>';
 }
 
-// ---------- structure map ----------------------------------------------------
-async function loadMap() {
-    const wrap = $('map-wrap');
+// ---------- structure: file tree (primary) + lazy dependency graph -----------
+function treeText() {
+    const m = (state.libraryMd || '').match(/## File Tree[\s\S]*?```text\n([\s\S]*?)```/);
+    return m ? m[1].replace(/\s+$/, '') : '';
+}
+
+async function loadStructure() {
     const md = await safeFetch('library.md?cb=' + Date.now(), '');
     state.libraryMd = md;
+    const pre = $('tree-pre');
+    const tree = treeText();
     if (!md) {
-        wrap.innerHTML = `<div class="errbox"><b>No structure map yet.</b><br>
-            Click <i>Update map</i> above (or run <code>wikifier update-maps</code> in this folder), then refresh.</div>`;
-        return;
+        pre.textContent = 'No structure data yet — click “Update map” above (or run wikifier update-maps), then refresh.';
+    } else if (tree) {
+        pre.textContent = tree;
+    } else {
+        // Older library.md without the File Tree section: regenerating fixes it.
+        pre.textContent = 'This library.md predates the File Tree view — click “Update map” to regenerate it.';
     }
-    const match = md.match(/```mermaid\n([\s\S]*?)```/);
+    state.graphDirty = true;
+    if ($('graph-details').open) await renderGraph();
+}
+
+async function renderGraph() {
+    if (!state.graphDirty && state.graphRendered) return;
+    const wrap = $('map-wrap');
+    const match = (state.libraryMd || '').match(/```mermaid\n([\s\S]*?)```/);
     if (!match || !match[1].trim()) {
-        wrap.innerHTML = `<div class="errbox"><b>library.md has no diagram block.</b><br>
-            Run <code>wikifier update-maps</code> to regenerate it.</div>`;
+        wrap.innerHTML = '<div class="errbox" style="margin:10px"><b>No diagram block in library.md.</b> Run “Update map” to regenerate.</div>';
         return;
     }
     // textContent (never innerHTML) so the Mermaid source can't be parsed as HTML.
@@ -609,15 +674,58 @@ async function loadMap() {
         // re-read it per render; keep both maxEdges placements).
         mermaid.initialize({ startOnLoad: false, theme: 'dark', maxEdges: 1500, flowchart: { maxEdges: 1500 } });
         await mermaid.run({ nodes: [wrap.querySelector('.mermaid')] });
+        state.graphRendered = true;
+        state.graphDirty = false;
+        resetPanZoom();
     } catch (e) {
         // Never fail silently: show what broke + where the intact data lives.
         const msg = (e && (e.message || e.str)) || String(e);
-        wrap.innerHTML = `<div class="errbox"><b>Structure map could not be rendered</b><br>
+        wrap.innerHTML = `<div class="errbox"><b>Dependency graph could not be rendered</b><br>
             <code>${esc(String(msg)).slice(0, 300)}</code><br>
-            <span class="hint">The underlying map data in library.md is intact — use “Copy structure as text”.</span></div>`;
+            <span class="hint">The underlying data in library.md is intact — the File Tree above is unaffected.</span></div>`;
     }
 }
 
+// Zero-dep pan/zoom for the graph viewport: drag to pan, wheel to zoom
+// toward the cursor, double-click to reset.
+function applyPanZoom() {
+    const p = state.panZoom;
+    $('graph-canvas').style.transform = `translate(${p.x}px, ${p.y}px) scale(${p.scale})`;
+}
+function resetPanZoom() {
+    state.panZoom = { scale: 1, x: 0, y: 0 };
+    applyPanZoom();
+}
+function initPanZoom() {
+    const vp = $('graph-viewport');
+    let dragging = false, lastX = 0, lastY = 0;
+    vp.addEventListener('wheel', e => {
+        e.preventDefault();
+        const p = state.panZoom;
+        const factor = e.deltaY < 0 ? 1.15 : 1 / 1.15;
+        const ns = Math.min(8, Math.max(0.1, p.scale * factor));
+        const rect = vp.getBoundingClientRect();
+        const cx = e.clientX - rect.left, cy = e.clientY - rect.top;
+        p.x = cx - (cx - p.x) * (ns / p.scale);
+        p.y = cy - (cy - p.y) * (ns / p.scale);
+        p.scale = ns;
+        applyPanZoom();
+    }, { passive: false });
+    vp.addEventListener('mousedown', e => {
+        dragging = true; lastX = e.clientX; lastY = e.clientY;
+        vp.classList.add('dragging'); e.preventDefault();
+    });
+    window.addEventListener('mousemove', e => {
+        if (!dragging) return;
+        state.panZoom.x += e.clientX - lastX;
+        state.panZoom.y += e.clientY - lastY;
+        lastX = e.clientX; lastY = e.clientY;
+        applyPanZoom();
+    });
+    window.addEventListener('mouseup', () => { dragging = false; vp.classList.remove('dragging'); });
+    vp.addEventListener('dblclick', resetPanZoom);
+}
+
 // ---------- exports ----------------------------------------------------------
 function mermaidSource() {
     const m = (state.libraryMd || '').match(/```mermaid\n([\s\S]*?)```/);
@@ -636,12 +744,12 @@ function buildSnapshot() {
         const mark = { g: '🟢', y: '🟡', r: '🔴' }[r.status];
         lines.push(`- ${mark} ${r.file} — ${r.reason}`);
     });
-    const src = mermaidSource();
-    if (src) {
+    const tree = treeText();
+    if (tree) {
         lines.push('');
-        lines.push('## Structure (Mermaid)');
-        lines.push('```mermaid');
-        lines.push(src);
+        lines.push('## Structure');
+        lines.push('```text');
+        lines.push(tree);
         lines.push('```');
     }
     return lines.join('\n');
@@ -675,7 +783,7 @@ async function loadAll() {
     renderSummary();
     renderFiles();
     renderFolders();
-    await loadMap();
+    await loadStructure();
     state.lastDataSig = await dataSignature();
 }
 
@@ -683,11 +791,19 @@ function wire() {
     $('btn-refresh').onclick = () => { loadAll(); toast('Refreshed'); };
     $('btn-stop').onclick = stopServer;
     $('btn-copy-serve').onclick = e => copyText('wikifier serve', e.target);
+    $('btn-copy-tree').onclick = e => {
+        const tree = treeText();
+        copyText(tree || 'No structure yet — run wikifier update-maps first.', e.target);
+    };
     $('btn-copy-mermaid').onclick = e => {
         const src = mermaidSource();
-        copyText(src || 'No map yet — run wikifier update-maps first.', e.target);
+        copyText(src || 'No diagram yet — run wikifier update-maps first.', e.target);
     };
     $('btn-copy-snapshot').onclick = e => copyText(buildSnapshot(), e.target);
+    $('graph-details').addEventListener('toggle', () => {
+        if ($('graph-details').open) renderGraph();
+    });
+    initPanZoom();
     ['btn-update', 'btn-update-full', 'btn-check'].forEach(id => {
         $(id).onclick = ev => runCommand(ev.target.dataset.cmd, ev.target);
     });
@@ -706,8 +822,26 @@ async function boot() {
     wire();
     await detectServer();
     await loadAll();
-    // Gentle background poll so monitor/agent updates appear automatically.
-    setInterval(() => { if (!state.running) loadAll(); }, 32000);
+    // Gentle background poll so monitor/agent updates appear automatically —
+    // and halts with an overlay once the server is gone, instead of spamming
+    // connection-refused errors forever.
+    state.pollTimer = setInterval(async () => {
+        if (state.running || state.halted) return;
+        if (state.execMode) {
+            try { await fetch('/__wikifier/status?cb=' + Date.now(), { cache: 'no-store' }); }
+            catch (e) {
+                haltDashboard('Server offline',
+                    'The <code>wikifier serve</code> process is no longer reachable. ' +
+                    'Run <code>wikifier serve</code> in the project folder and reload this page.');
+                return;
+            }
+        }
+        await loadAll();
+        if (state.failStreak >= 6) {
+            haltDashboard('Connection lost',
+                'The server stopped responding. Restart it (e.g. <code>wikifier serve</code>) and reload this page.');
+        }
+    }, 32000);
 }
 
 window.onload = boot;

{wikifier-4.4.0 → wikifier-4.5.1}/wikifier/__init__.py

@@ -61,4 +61,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.4.0"
+__version__ = "4.5.1"

{wikifier-4.4.0 → wikifier-4.5.1}/wikifier/index.html

@@ -136,13 +136,34 @@
     .console.show { display: block; }
     .hint { font-size: 12px; color: var(--faint); margin-top: 8px; }
 
-    /* ---------- mermaid ---------- */
-    #map-wrap {
-        margin-top: 12px; padding: 10px; min-height: 160px;
+    /* ---------- file tree (primary structure view) ---------- */
+    #tree-pre {
+        margin: 12px 0 0; padding: 14px 16px; max-height: 520px; overflow: auto;
         background: var(--panel-2); border: 1px solid var(--border-soft);
-        border-radius: 12px; overflow: auto;
+        border-radius: 12px; font-family: var(--mono); font-size: 12.5px;
+        line-height: 1.5; color: #c4cedb; white-space: pre;
+    }
+
+    /* ---------- dependency graph (collapsible, pan/zoom) ---------- */
+    details.graph { margin-top: 14px; }
+    details.graph > summary {
+        cursor: pointer; font-size: 13px; font-weight: 600; color: var(--muted);
+        padding: 9px 12px; border: 1px solid var(--border); border-radius: 10px;
+        list-style: none; user-select: none;
+    }
+    details.graph > summary::before { content: '▸ '; color: var(--accent); }
+    details.graph[open] > summary::before { content: '▾ '; }
+    details.graph > summary:hover { background: #15202f; }
+    #graph-viewport {
+        margin-top: 10px; height: 460px; overflow: hidden; cursor: grab;
+        background: var(--panel-2); border: 1px solid var(--border-soft);
+        border-radius: 12px; position: relative;
     }
+    #graph-viewport.dragging { cursor: grabbing; }
+    #graph-canvas { transform-origin: 0 0; width: max-content; }
+    #map-wrap { padding: 10px; min-height: 120px; }
     #map-wrap svg { max-width: none; }
+    .graph-help { font-size: 11.5px; color: var(--faint); margin-top: 6px; }
     .errbox {
         font-size: 13px; padding: 14px; border: 1px solid #92600c;
         border-radius: 10px; background: #171207;
@@ -246,15 +267,23 @@
         <div class="hint" id="actions-hint"></div>
     </section>
 
-    <!-- ============ structure map ============ -->
+    <!-- ============ structure: file tree (primary) + dependency graph ============ -->
     <section class="card">
-        <h2>Code structure <span class="sub">imports &amp; dependencies, rebuilt from your code</span></h2>
-        <div id="map-wrap"><div class="hint">loading map…</div></div>
+        <h2>Code structure <span class="sub">file tree with wiki descriptions — rebuilt from your code</span></h2>
+        <pre id="tree-pre">loading…</pre>
         <div class="btnrow" style="margin-top:12px">
-            <button id="btn-copy-mermaid">⧉ Copy structure as text</button>
+            <button id="btn-copy-tree">⧉ Copy structure as text</button>
             <button id="btn-copy-snapshot">⧉ Copy full snapshot (tree + files + descriptions)</button>
-            <span class="hint" style="margin:0">Paste directly into docs or LLM chats.</span>
+            <span class="hint" style="margin:0">Clean, readable text — paste directly into docs or LLM chats.</span>
         </div>
+        <details class="graph" id="graph-details">
+            <summary>Dependency graph (drag to pan · scroll to zoom · double-click to reset)</summary>
+            <div id="graph-viewport"><div id="graph-canvas"><div id="map-wrap"><div class="hint" style="padding:10px">expand to render…</div></div></div></div>
+            <div class="btnrow" style="margin-top:8px">
+                <button id="btn-copy-mermaid">⧉ Copy diagram source (Mermaid)</button>
+                <span class="graph-help">Arrows: solid = high-confidence import · dashed = medium · “?” = low/unresolved.</span>
+            </div>
+        </details>
     </section>
 
     <!-- ============ files + folders ============ -->
@@ -281,8 +310,8 @@
 
 <div id="toast"></div>
 <div id="overlay"><div class="panel">
-    <h2>Server stopped</h2>
-    <p>The <code>wikifier serve</code> process has shut down and this page is now frozen.
+    <h2 id="overlay-title">Server stopped</h2>
+    <p id="overlay-msg">The <code>wikifier serve</code> process has shut down and this page is now frozen.
        To come back, run <code>wikifier serve</code> in the project folder again and reload.</p>
 </div></div>
 
@@ -303,7 +332,13 @@ const state = {
     jsonMissing: false,       // remember a file_health.json 404 — stop re-polling it
     running: false,
     liveWaitTimer: null,
+    pollTimer: null,
     lastDataSig: '',
+    failStreak: 0,            // consecutive artifact-fetch failures (server gone?)
+    halted: false,
+    graphRendered: false,     // dependency graph renders lazily on first expand
+    graphDirty: true,
+    panZoom: { scale: 1, x: 0, y: 0 },
 };
 
 const $ = id => document.getElementById(id);
@@ -316,12 +351,26 @@ async function safeFetch(path, fallbackText = '') {
         const res = await fetch(path, ctrl ? { signal: ctrl.signal, cache: 'no-store' } : { cache: 'no-store' });
         if (timer) clearTimeout(timer);
         if (!res.ok) throw new Error('HTTP ' + res.status);
+        state.failStreak = 0;
         return await res.text();
     } catch (e) {
+        // Network-level failures (server killed) count toward the halt
+        // threshold; HTTP errors (404 on optional files) do not.
+        if (!String(e.message || '').startsWith('HTTP ')) state.failStreak++;
         return fallbackText;
     }
 }
 
+function haltDashboard(title, msg) {
+    if (state.halted) return;
+    state.halted = true;
+    if (state.pollTimer) clearInterval(state.pollTimer);
+    if (state.liveWaitTimer) clearInterval(state.liveWaitTimer);
+    $('overlay-title').textContent = title;
+    $('overlay-msg').innerHTML = msg;
+    $('overlay').classList.add('show');
+}
+
 function toast(msg, ms = 2200) {
     const t = $('toast');
     t.textContent = msg;
@@ -383,12 +432,13 @@ async function detectServer() {
 async function stopServer() {
     if (!state.execMode) return;
     if (!confirm('Stop the wikifier serve process? The dashboard will go offline.')) return;
+    const done = () => haltDashboard('Server stopped',
+        'The <code>wikifier serve</code> process has shut down and this page is now frozen. ' +
+        'To come back, run <code>wikifier serve</code> in the project folder again and reload.');
     try {
         const res = await fetch('/__wikifier/shutdown', { method: 'POST' });
-        if (res.ok) { $('overlay').classList.add('show'); return; }
-    } catch (e) { /* connection may drop as it stops — that also means success */
-        $('overlay').classList.add('show'); return;
-    }
+        if (res.ok) { done(); return; }
+    } catch (e) { done(); return; }  // connection drop while stopping = success
     toast('Could not stop the server');
 }
 
@@ -581,20 +631,35 @@ function renderFolders() {
     }).join('') || '<div class="hint">No files tracked yet — run check-changes / update-maps.</div>';
 }
 
-// ---------- structure map ----------------------------------------------------
-async function loadMap() {
-    const wrap = $('map-wrap');
+// ---------- structure: file tree (primary) + lazy dependency graph -----------
+function treeText() {
+    const m = (state.libraryMd || '').match(/## File Tree[\s\S]*?```text\n([\s\S]*?)```/);
+    return m ? m[1].replace(/\s+$/, '') : '';
+}
+
+async function loadStructure() {
     const md = await safeFetch('library.md?cb=' + Date.now(), '');
     state.libraryMd = md;
+    const pre = $('tree-pre');
+    const tree = treeText();
     if (!md) {
-        wrap.innerHTML = `<div class="errbox"><b>No structure map yet.</b><br>
-            Click <i>Update map</i> above (or run <code>wikifier update-maps</code> in this folder), then refresh.</div>`;
-        return;
+        pre.textContent = 'No structure data yet — click “Update map” above (or run wikifier update-maps), then refresh.';
+    } else if (tree) {
+        pre.textContent = tree;
+    } else {
+        // Older library.md without the File Tree section: regenerating fixes it.
+        pre.textContent = 'This library.md predates the File Tree view — click “Update map” to regenerate it.';
     }
-    const match = md.match(/```mermaid\n([\s\S]*?)```/);
+    state.graphDirty = true;
+    if ($('graph-details').open) await renderGraph();
+}
+
+async function renderGraph() {
+    if (!state.graphDirty && state.graphRendered) return;
+    const wrap = $('map-wrap');
+    const match = (state.libraryMd || '').match(/```mermaid\n([\s\S]*?)```/);
     if (!match || !match[1].trim()) {
-        wrap.innerHTML = `<div class="errbox"><b>library.md has no diagram block.</b><br>
-            Run <code>wikifier update-maps</code> to regenerate it.</div>`;
+        wrap.innerHTML = '<div class="errbox" style="margin:10px"><b>No diagram block in library.md.</b> Run “Update map” to regenerate.</div>';
         return;
     }
     // textContent (never innerHTML) so the Mermaid source can't be parsed as HTML.
@@ -609,15 +674,58 @@ async function loadMap() {
         // re-read it per render; keep both maxEdges placements).
         mermaid.initialize({ startOnLoad: false, theme: 'dark', maxEdges: 1500, flowchart: { maxEdges: 1500 } });
         await mermaid.run({ nodes: [wrap.querySelector('.mermaid')] });
+        state.graphRendered = true;
+        state.graphDirty = false;
+        resetPanZoom();
     } catch (e) {
         // Never fail silently: show what broke + where the intact data lives.
         const msg = (e && (e.message || e.str)) || String(e);
-        wrap.innerHTML = `<div class="errbox"><b>Structure map could not be rendered</b><br>
+        wrap.innerHTML = `<div class="errbox"><b>Dependency graph could not be rendered</b><br>
             <code>${esc(String(msg)).slice(0, 300)}</code><br>
-            <span class="hint">The underlying map data in library.md is intact — use “Copy structure as text”.</span></div>`;
+            <span class="hint">The underlying data in library.md is intact — the File Tree above is unaffected.</span></div>`;
     }
 }
 
+// Zero-dep pan/zoom for the graph viewport: drag to pan, wheel to zoom
+// toward the cursor, double-click to reset.
+function applyPanZoom() {
+    const p = state.panZoom;
+    $('graph-canvas').style.transform = `translate(${p.x}px, ${p.y}px) scale(${p.scale})`;
+}
+function resetPanZoom() {
+    state.panZoom = { scale: 1, x: 0, y: 0 };
+    applyPanZoom();
+}
+function initPanZoom() {
+    const vp = $('graph-viewport');
+    let dragging = false, lastX = 0, lastY = 0;
+    vp.addEventListener('wheel', e => {
+        e.preventDefault();
+        const p = state.panZoom;
+        const factor = e.deltaY < 0 ? 1.15 : 1 / 1.15;
+        const ns = Math.min(8, Math.max(0.1, p.scale * factor));
+        const rect = vp.getBoundingClientRect();
+        const cx = e.clientX - rect.left, cy = e.clientY - rect.top;
+        p.x = cx - (cx - p.x) * (ns / p.scale);
+        p.y = cy - (cy - p.y) * (ns / p.scale);
+        p.scale = ns;
+        applyPanZoom();
+    }, { passive: false });
+    vp.addEventListener('mousedown', e => {
+        dragging = true; lastX = e.clientX; lastY = e.clientY;
+        vp.classList.add('dragging'); e.preventDefault();
+    });
+    window.addEventListener('mousemove', e => {
+        if (!dragging) return;
+        state.panZoom.x += e.clientX - lastX;
+        state.panZoom.y += e.clientY - lastY;
+        lastX = e.clientX; lastY = e.clientY;
+        applyPanZoom();
+    });
+    window.addEventListener('mouseup', () => { dragging = false; vp.classList.remove('dragging'); });
+    vp.addEventListener('dblclick', resetPanZoom);
+}
+
 // ---------- exports ----------------------------------------------------------
 function mermaidSource() {
     const m = (state.libraryMd || '').match(/```mermaid\n([\s\S]*?)```/);
@@ -636,12 +744,12 @@ function buildSnapshot() {
         const mark = { g: '🟢', y: '🟡', r: '🔴' }[r.status];
         lines.push(`- ${mark} ${r.file} — ${r.reason}`);
     });
-    const src = mermaidSource();
-    if (src) {
+    const tree = treeText();
+    if (tree) {
         lines.push('');
-        lines.push('## Structure (Mermaid)');
-        lines.push('```mermaid');
-        lines.push(src);
+        lines.push('## Structure');
+        lines.push('```text');
+        lines.push(tree);
         lines.push('```');
     }
     return lines.join('\n');
@@ -675,7 +783,7 @@ async function loadAll() {
     renderSummary();
     renderFiles();
     renderFolders();
-    await loadMap();
+    await loadStructure();
     state.lastDataSig = await dataSignature();
 }
 
@@ -683,11 +791,19 @@ function wire() {
     $('btn-refresh').onclick = () => { loadAll(); toast('Refreshed'); };
     $('btn-stop').onclick = stopServer;
     $('btn-copy-serve').onclick = e => copyText('wikifier serve', e.target);
+    $('btn-copy-tree').onclick = e => {
+        const tree = treeText();
+        copyText(tree || 'No structure yet — run wikifier update-maps first.', e.target);
+    };
     $('btn-copy-mermaid').onclick = e => {
         const src = mermaidSource();
-        copyText(src || 'No map yet — run wikifier update-maps first.', e.target);
+        copyText(src || 'No diagram yet — run wikifier update-maps first.', e.target);
     };
     $('btn-copy-snapshot').onclick = e => copyText(buildSnapshot(), e.target);
+    $('graph-details').addEventListener('toggle', () => {
+        if ($('graph-details').open) renderGraph();
+    });
+    initPanZoom();
     ['btn-update', 'btn-update-full', 'btn-check'].forEach(id => {
         $(id).onclick = ev => runCommand(ev.target.dataset.cmd, ev.target);
     });
@@ -706,8 +822,26 @@ async function boot() {
     wire();
     await detectServer();
     await loadAll();
-    // Gentle background poll so monitor/agent updates appear automatically.
-    setInterval(() => { if (!state.running) loadAll(); }, 32000);
+    // Gentle background poll so monitor/agent updates appear automatically —
+    // and halts with an overlay once the server is gone, instead of spamming
+    // connection-refused errors forever.
+    state.pollTimer = setInterval(async () => {
+        if (state.running || state.halted) return;
+        if (state.execMode) {
+            try { await fetch('/__wikifier/status?cb=' + Date.now(), { cache: 'no-store' }); }
+            catch (e) {
+                haltDashboard('Server offline',
+                    'The <code>wikifier serve</code> process is no longer reachable. ' +
+                    'Run <code>wikifier serve</code> in the project folder and reload this page.');
+                return;
+            }
+        }
+        await loadAll();
+        if (state.failStreak >= 6) {
+            haltDashboard('Connection lost',
+                'The server stopped responding. Restart it (e.g. <code>wikifier serve</code>) and reload this page.');
+        }
+    }, 32000);
 }
 
 window.onload = boot;

{wikifier-4.4.0 → wikifier-4.5.1}/wikifier/library.py

@@ -27,6 +27,7 @@ table (500-row cap), circular dependencies, ACS risk snapshot, reverse
 dependencies, barrel expansions, and conditional/dynamic intelligence.
 """
 
+import json
 import os
 import re
 from pathlib import Path
@@ -83,6 +84,10 @@ def _collect_edges(cache: Dict[str, Any]) -> List[Tuple[str, str, str, str, bool
         resolved = str(pair.get("resolved") or "").strip()
         if not raw and not resolved:
             continue
+        if "\n" in raw or "\n" in resolved:
+            # Parser artifact (e.g. comment/doc text captured as a dynamic
+            # specifier) — never let multi-line "modules" become graph nodes.
+            continue
         internal = bool(resolved)
         target = resolved if internal else raw
         conf = _pair_confidence(pair)
@@ -108,7 +113,10 @@ def _sanitize_node_id(name: str) -> str:
 
 def _node_label(path: str) -> str:
     base = os.path.basename(path.rstrip("/")) or path
-    return base.replace('"', "'")
+    # Labels must never carry newlines/quotes/brackets — garbage raw modules
+    # once leaked multi-line comment text into the rendered graph.
+    base = re.sub(r"\s+", " ", base).replace('"', "'").replace("[", "(").replace("]", ")")
+    return (base[:48] + "…") if len(base) > 49 else base
 
 
 def _top_level_group(path: str) -> str:
@@ -470,6 +478,147 @@ def _generate_conditional_dynamic_section(cache: Dict[str, Any]) -> List[str]:
 # Public API
 # ---------------------------------------------------------------------------
 
+# ---------------------------------------------------------------------------
+# File tree (the primary human/agent view of project shape)
+# ---------------------------------------------------------------------------
+
+def _clean_reason(reason: str) -> Optional[str]:
+    """Normalise a health reason into a short description, or None for
+    auto-yellow boilerplate (it describes the tracking system, not the file)."""
+    reason = re.sub(r"\s+", " ", str(reason or "")).strip()
+    if not reason or reason.startswith("mtime changed") or "auto-detected" in reason:
+        return None
+    return (reason[:90] + "…") if len(reason) > 91 else reason
+
+
+def _load_health_descriptions(root: Path) -> Dict[str, str]:
+    """file -> short description, from file_health.json or file_health.md.
+
+    Projects maintained through the shell workflow only have the .md table
+    (the JSON is written by the Python health module), so both are read.
+    """
+    desc: Dict[str, str] = {}
+    try:
+        with open(root / "file_health.json", "r", encoding="utf-8") as f:
+            data = json.load(f)
+        entries = data.get("entries", data) if isinstance(data, dict) else {}
+        for file, e in entries.items():
+            r = _clean_reason((e or {}).get("reason"))
+            if r:
+                desc[str(file)] = r
+    except Exception:
+        pass
+    if desc:
+        return desc
+    try:  # .md fallback: | File | Status | Last Updated | Reason / Intent |
+        with open(root / "file_health.md", "r", encoding="utf-8") as f:
+            for line in f:
+                line = line.strip()
+                if not line.startswith("|") or line.startswith("|--") or "| File | Status" in line:
+                    continue
+                parts = [p.strip() for p in line.split("|")]
+                if len(parts) >= 6 and parts[1]:
+                    r = _clean_reason(parts[4])
+                    if r:
+                        desc[parts[1]] = r
+    except Exception:
+        pass
+    return desc
+
+
+TREE_DIR_FILE_CAP = 40      # files listed per directory before "… +N more"
+TREE_TOTAL_LINE_CAP = 900   # hard ceiling so huge monorepos stay readable
+
+
+def _generate_tree_section(root: Path, cache: Dict[str, Any]) -> List[str]:
+    """Indented file tree of parsed + wiki-tracked files, with descriptions.
+
+    The Mermaid graph shows *dependencies* (which reads as soup at monorepo
+    scale); this tree is the readable answer to "what is in this project":
+
+        wikifier/
+        ├── parsers/
+        │   ├── bree.py — barrel & re-export chain engine
+        │   └── python.py
+        └── cli.py — entry point + full update pipeline
+    """
+    descriptions = _load_health_descriptions(root)
+    parsed = {k for k in cache.keys() if isinstance(k, str) and not k.startswith("_")}
+    # Health keys are free text (audit records may use whole sentences as the
+    # "file"; some entries point at directories): only real on-disk files —
+    # or parser-confirmed ones — belong in the tree.
+    tracked = set()
+    for k in descriptions:
+        k2 = k.rstrip("/")
+        if not k2 or k2 in parsed:
+            continue
+        try:
+            if (root / k2).is_file():
+                tracked.add(k2)
+        except OSError:
+            continue
+    files = sorted(parsed | tracked)
+    if not files:
+        return ["## File Tree", "", "```text",
+                "(no files parsed yet — run update-maps)", "```", ""]
+
+    # Nested {name: subtree}; directory keys end with '/', file leaves are None.
+    tree: Dict[str, Any] = {}
+    for path in files:
+        node = tree
+        parts = path.split("/")
+        for part in parts[:-1]:
+            node = node.setdefault(part + "/", {})
+        node[parts[-1]] = None
+
+    def count_leaves(node: Dict[str, Any]) -> int:
+        return sum(count_leaves(v) if isinstance(v, dict) else 1 for v in node.values())
+
+    out: List[str] = []
+    truncated = False
+
+    def render(node: Dict[str, Any], prefix: str, path_prefix: str) -> None:
+        nonlocal truncated
+        dirs = sorted(k for k in node if k.endswith("/"))
+        leaves = sorted(k for k in node if not k.endswith("/"))
+        shown = leaves[:TREE_DIR_FILE_CAP]
+        hidden = len(leaves) - len(shown)
+        items = dirs + shown + (["\x00more"] if hidden > 0 else [])
+        for i, name in enumerate(items):
+            if len(out) >= TREE_TOTAL_LINE_CAP:
+                truncated = True
+                return
+            last = i == len(items) - 1
+            connector = "└── " if last else "├── "
+            child_prefix = prefix + ("    " if last else "│   ")
+            if name == "\x00more":
+                out.append(prefix + connector + "… +{0} more files".format(hidden))
+            elif name.endswith("/"):
+                sub = node[name]
+                n = count_leaves(sub)
+                suffix = "  ({0} files)".format(n) if n > TREE_DIR_FILE_CAP else ""
+                out.append(prefix + connector + name + suffix)
+                render(sub, child_prefix, path_prefix + name)
+            else:
+                d = descriptions.get(path_prefix + name)
+                out.append(prefix + connector + name + ((" — " + d) if d else ""))
+
+    render(tree, "", "")
+
+    lines = [
+        "## File Tree", "",
+        "> Every parsed/tracked file, organised by folder. Descriptions come from",
+        "> the agent wiki (file_health). The dependency graph is further below.",
+        "", "```text",
+        "{0}/  ({1} files)".format(root.name, len(files)),
+    ]
+    lines.extend(out)
+    if truncated:
+        lines.append("… (tree capped at {0} lines — full file list lives in the import cache)".format(TREE_TOTAL_LINE_CAP))
+    lines.extend(["```", ""])
+    return lines
+
+
 def generate_library_md(root: Path, cache: Dict[str, Any]) -> str:
     """Render library.md content from an import cache (see module docstring)."""
     if not isinstance(cache, dict):
@@ -483,6 +632,7 @@ def generate_library_md(root: Path, cache: Dict[str, Any]) -> str:
         '> Run `wikifier record-change library.md "..."` if you need to annotate.',
         "",
     ]
+    lines.extend(_generate_tree_section(root, cache))
     lines.extend(_generate_mermaid_section(edges))
     lines.extend(_generate_table_section(edges))
     lines.extend(_generate_cycles_section(cache))

{wikifier-4.4.0 → wikifier-4.5.1}/wikifier/parsers/python.py

@@ -261,6 +261,40 @@ def _strip_docstrings(content: str) -> str:
     return content
 
 
+def _strip_comments(content: str) -> str:
+    """Blank out # comments (outside string literals), preserving line structure.
+
+    The dynamic-import scanner matches anywhere in the text (unlike the
+    line-anchored static patterns), so a comment like
+    `# importlib.import_module() now supported` produced a garbage dynamic
+    edge whose raw_module was the comment text — which then leaked into
+    library.md as a phantom graph node. Docstrings were already stripped;
+    comments were not.
+    """
+    out_lines = []
+    for line in content.split("\n"):
+        in_str = None
+        cut = None
+        i = 0
+        n = len(line)
+        while i < n:
+            c = line[i]
+            if in_str:
+                if c == "\\":
+                    i += 2
+                    continue
+                if c == in_str:
+                    in_str = None
+            elif c in ("'", '"'):
+                in_str = c
+            elif c == "#":
+                cut = i
+                break
+            i += 1
+        out_lines.append(line if cut is None else line[:cut])
+    return "\n".join(out_lines)
+
+
 def parse_python_imports(filepath: str) -> List[Dict[str, Any]]:
     """
     Parse a Python file and return structured import information.
@@ -295,8 +329,10 @@ def parse_python_imports(filepath: str) -> List[Dict[str, Any]]:
     except Exception:
         return []
 
-    # Remove docstrings to avoid matching imports inside documentation
+    # Remove docstrings + comments to avoid matching imports inside
+    # documentation (the dynamic scanner matches anywhere in the text).
     content = _strip_docstrings(content)
+    content = _strip_comments(content)
 
     imports: List[Dict[str, Any]] = []
 

{wikifier-4.4.0 → wikifier-4.5.1/wikifier.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.4.0
+Version: 4.5.1
 Summary: Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents.
 Author-email: Aron Amos <aron@example.com>
 Maintainer: Aron Amos
@@ -137,6 +137,10 @@ Works with Claude Desktop, Claude Code, Cursor, Cline, and any Model Context Pro
 
 ## The Human Layer (Secondary, by Design)
 
+![Wikifier human dashboard — the project file tree with agent-wiki descriptions, health pills, and one-click Run/Stop controls, served locally by wikifier serve](https://raw.githubusercontent.com/IronAdamant/wikifier/main/screenshot/front_page_review.png)
+
+*The dashboard served by `wikifier serve`: live file tree with wiki descriptions, health status pills, and action buttons that run `update-maps`/`check-changes` directly (localhost-only) — plus a Stop server button for when you're done.*
+
 `wikifier init` copies a single static `index.html` into your project: a dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. View it with **`wikifier serve`** (then open http://localhost:8787/index.html) — browsers block `file://` fetches, so a double-clicked index.html can't read the wiki files; the page detects that case and shows you the fix. When served by `wikifier serve`, the dashboard's buttons genuinely **run** `update-maps`/`check-changes` (whitelisted commands only, localhost-only) and a **Stop server** button shuts the process down when you're done; behind any plain static server the same buttons fall back to copy + auto-refresh. The agent-facing markdown files and tools remain the single source of truth.
 
 ## Intended Use: Strictly Agent-to-Agent