@allansantos-dev/smart-tool 0.0.0-stage → 0.9.0

package/project_maps_ui.py

@@ -0,0 +1,96 @@
+"""Interface dos três mapas reais por projeto; sem bibliotecas de UI externas."""
+
+STYLE = r'''
+.maps{--map-blue-fill:#bfdbfe;--map-blue-stroke:#1d4ed8;--map-blue-ink:#172554;--map-teal-fill:#99f6e4;--map-teal-stroke:#0f766e;--map-teal-ink:#042f2e;--map-violet-fill:#ddd6fe;--map-violet-stroke:#6d28d9;--map-violet-ink:#2e1065;--map-amber-fill:#fde68a;--map-amber-stroke:#a16207;--map-amber-ink:#422006;--map-rose-fill:#fecdd3;--map-rose-stroke:#be123c;--map-rose-ink:#4c0519;--map-sky-fill:#bae6fd;--map-sky-stroke:#0369a1;--map-sky-ink:#082f49;--map-orange-fill:#fed7aa;--map-orange-stroke:#c2410c;--map-orange-ink:#431407;--map-green-fill:#bbf7d0;--map-green-stroke:#15803d;--map-green-ink:#052e16}
+@media(prefers-color-scheme:dark){.maps{--map-blue-fill:#1e3a8a;--map-blue-stroke:#93c5fd;--map-blue-ink:#eff6ff;--map-teal-fill:#134e4a;--map-teal-stroke:#5eead4;--map-teal-ink:#f0fdfa;--map-violet-fill:#4c1d95;--map-violet-stroke:#c4b5fd;--map-violet-ink:#f5f3ff;--map-amber-fill:#713f12;--map-amber-stroke:#fcd34d;--map-amber-ink:#fffbeb;--map-rose-fill:#881337;--map-rose-stroke:#fda4af;--map-rose-ink:#fff1f2;--map-sky-fill:#0c4a6e;--map-sky-stroke:#7dd3fc;--map-sky-ink:#f0f9ff;--map-orange-fill:#7c2d12;--map-orange-stroke:#fdba74;--map-orange-ink:#fff7ed;--map-green-fill:#14532d;--map-green-stroke:#86efac;--map-green-ink:#f0fdf4}}
+.maps-color-legend{padding:10px 20px;display:flex;align-items:center;gap:8px 16px;flex-wrap:wrap;max-height:115px;overflow:auto;font-size:12px;color:var(--muted);border-top:1px solid var(--border)}.maps-color-legend>span{display:inline-flex;align-items:center;gap:6px;max-width:100%;overflow-wrap:anywhere}.maps-swatch{display:inline-block;width:13px;height:13px;flex:0 0 13px;border-radius:3px;background:var(--swatch-fill);border:1px solid var(--swatch-stroke)}.maps-node.pending circle,.maps-node.pending rect,.maps-node.missing circle,.maps-node.missing rect{stroke-dasharray:6 3}
+.maps-inspector{max-height:none!important;overflow:visible!important;background:var(--surface)}
+.maps{margin:18px 0;border:1px solid var(--border);border-radius:10px;background:var(--surface);overflow:hidden}.maps>summary{padding:18px 20px}.maps[open]>summary{border-bottom:1px solid var(--border)}.maps-tabs{display:flex;gap:6px;flex-wrap:wrap;padding:16px 20px 0}.maps-tabs button[aria-selected=true]{background:var(--selected);border-color:var(--accent)}.maps-toolbar{padding:14px 20px;display:flex;gap:10px;align-items:end;flex-wrap:wrap}.maps-toolbar label{font-size:12px;margin:0 0 4px}.maps-toolbar input,.maps-toolbar select{min-height:40px;max-width:100%;margin:0}.maps-search{flex:1;min-width:150px}.maps-view{max-width:280px}.maps-status{padding:0 20px;font-size:13px;color:var(--muted);overflow-wrap:anywhere}.maps-workspace{display:grid;grid-template-columns:minmax(0,1fr) 245px;border-block:1px solid var(--border);margin-top:14px}.maps-canvas{min-width:0;background:var(--bg)}.maps-tools{display:flex;gap:6px;padding:10px 14px;align-items:center;flex-wrap:wrap;border-bottom:1px solid var(--border)}.maps-tools button{font-size:12px;padding:6px 10px;min-height:36px}.maps-tools span{margin-left:auto;font-size:12px;color:var(--muted)}#maps-svg{display:block;width:100%;height:480px;touch-action:none;user-select:none;cursor:grab}#maps-svg:active{cursor:grabbing}.maps-edge{stroke:var(--edge-color,var(--border));stroke-width:1.6;fill:none;opacity:.85}.maps-edge.active{stroke:var(--edge-color,var(--accent));stroke-width:2.8;opacity:1}.maps-node{cursor:pointer}.maps-node circle,.maps-node rect{fill:var(--node-fill,var(--surface));stroke:var(--node-stroke,var(--muted));stroke-width:2}.maps-node text{fill:var(--ink);font:12px 'Segoe UI',sans-serif;pointer-events:none}.maps-node .on-node,.maps-node .secondary{fill:var(--node-ink,var(--ink))}.maps-node .secondary{font-size:11px}.maps-node.active circle,.maps-node.active rect{fill:var(--node-fill,var(--selected));stroke:var(--ink)!important;stroke-width:4}.maps-node:focus-visible{outline:none}.maps-node:focus-visible circle,.maps-node:focus-visible rect{stroke:var(--ink)!important;stroke-width:4}.maps-folder-label{fill:var(--muted);font:600 12px 'Segoe UI',sans-serif}.maps-inspector{border-left:1px solid var(--border);padding:18px;min-width:0}.maps-inspector h3{overflow-wrap:anywhere}.maps-inspector code{display:block;overflow-wrap:anywhere;color:var(--muted);margin:8px 0}.maps-inspector p{font-size:13px}.maps-relations{padding:0;list-style:none;max-height:180px;overflow:auto}.maps-relations button{padding:5px 0;min-height:28px;border:0;font-size:12px;text-align:left;color:var(--accent);overflow-wrap:anywhere}.maps-relations button:hover{text-decoration:underline;background:transparent}.maps-bottom{padding:12px 20px;display:flex;justify-content:space-between;gap:12px;flex-wrap:wrap;font-size:12px;color:var(--muted)}.maps-legend{display:flex;gap:14px;flex-wrap:wrap}.maps-legend span{display:flex;gap:6px;align-items:center}.maps-dot{width:9px;height:9px;border-radius:50%;background:var(--good)}.maps-dot.pending{background:var(--warn)}.maps-dot.stored{background:var(--muted)}#map-files{padding:0 20px;max-height:220px;overflow:auto}#map-chunks{padding:0 20px 14px}#map-chunks pre{white-space:pre-wrap;overflow-wrap:anywhere;font:12px/1.65 Consolas,monospace}#maps-diagnostics{margin:0 20px}#maps-diagnostic-list{max-height:260px;overflow:auto;font-size:13px;overflow-wrap:anywhere}.maps:fullscreen{background:var(--surface);border:0;border-radius:0;overflow:auto;padding:12px;margin:0}.maps:fullscreen #maps-svg{height:calc(100vh - 350px);min-height:400px}.maps:fullscreen .maps-workspace{grid-template-columns:minmax(0,1fr) 300px}.maps-placeholder{padding:30px 20px;font-size:13px;color:var(--muted)}#maps-symbol-picker{max-width:100%;width:100%;margin:8px 0}
+@media(max-width:1050px){.maps-workspace{grid-template-columns:1fr}.maps-inspector{border-left:0;border-top:1px solid var(--border)}#maps-svg{height:460px}.maps-view{max-width:100%;flex:1}}
+@media(max-width:600px){.maps-tabs,.maps-toolbar{padding-inline:12px}.maps-toolbar>div{max-width:100%}.maps-view{width:100%;flex-basis:100%}.maps-toolbar select{width:100%}.maps-tabs button{flex:1;padding:8px;font-size:13px}#maps-svg{height:420px}.maps:fullscreen .maps-workspace{grid-template-columns:1fr}.maps-bottom{padding-inline:12px}#map-files,#map-chunks{padding-inline:12px}}
+'''
+
+HTML = r'''
+<details id="map-details" class="maps">
+<summary>Project maps and stored views</summary>
+<div class="maps-tabs" role="tablist" aria-label="Project maps">
+ <button type="button" role="tab" data-map-mode="network" id="map-tab-network" aria-controls="maps-panel" aria-selected="true">A · Files</button>
+ <button type="button" role="tab" data-map-mode="coverage" id="map-tab-coverage" aria-controls="maps-panel" aria-selected="false" tabindex="-1">B · Coverage</button>
+ <button type="button" role="tab" data-map-mode="calls" id="map-tab-calls" aria-controls="maps-panel" aria-selected="false" tabindex="-1">C · Functions</button>
+</div>
+<div id="maps-panel" role="tabpanel" aria-labelledby="map-tab-network">
+<div class="maps-toolbar">
+ <div class="maps-view"><label for="map-view">Stored view</label><select id="map-view"><option value="">Current view or available legacy</option></select></div>
+ <div class="maps-search"><label for="maps-search">Find file or function</label><input id="maps-search" type="text" placeholder="Name or path" autocomplete="off"></div>
+ <div><label for="maps-folder">Folder</label><select id="maps-folder"><option value="">All</option></select></div>
+ <div><label for="maps-color-mode">Color by</label><select id="maps-color-mode"><option value="module">Module / folder</option><option value="status">Index status</option></select></div>
+ <button type="button" id="load-map">Load maps</button>
+</div>
+<p class="maps-status" id="map-info" role="status" aria-live="polite">Local analysis of already indexed content, with no new embeddings.</p>
+<p class="maps-status" id="maps-description">Arrows link the importing file to its resolved internal dependency.</p>
+<div id="maps-color-legend" class="maps-color-legend" aria-label="Color legend"></div>
+<div class="maps-workspace">
+ <div class="maps-canvas" id="map-graph"><div class="maps-tools"><button id="maps-minus" aria-label="Zoom out">−</button><button id="maps-plus" aria-label="Zoom in">+</button><button id="maps-fit">Fit</button><button id="maps-all">Show all</button><button id="maps-expand">Full screen</button><button id="maps-new-window">New window</button><a id="maps-popup-link" hidden target="_blank" rel="noopener noreferrer">Open map separately</a><label for="maps-limit">Nodes</label><select id="maps-limit" aria-label="Visible node limit"><option value="60">60</option><option value="120" selected>120</option><option value="250">250</option></select><span id="maps-count"></span></div>
+ <svg id="maps-svg" viewBox="0 0 1000 650" role="group" aria-label="Interactive project map"><defs><marker id="maps-arrow" markerWidth="8" markerHeight="8" refX="7" refY="4" orient="auto" markerUnits="userSpaceOnUse"><path d="M0 0 L8 4 L0 8" fill="var(--accent)"></path></marker></defs><g id="maps-world"></g></svg>
+ <div id="maps-empty" class="maps-placeholder">Load a view to explore the three maps.</div></div>
+ <aside class="maps-inspector"><h3 id="maps-selected">Select an element</h3><code id="maps-path"></code><p id="maps-state"></p><p id="maps-facts"></p><label for="maps-symbol-picker">Open element by name</label><select id="maps-symbol-picker"><option value="">Select…</option></select><h3 id="maps-relation-title">Relations</h3><ul id="maps-relations" class="maps-relations"></ul><button id="maps-read" disabled>View file chunks</button></aside>
+</div>
+<div class="maps-bottom"><span id="maps-color-note">Color by module/folder · dashed border means changed or missing.</span><span>Drag nodes or the background; zoom in to read the details.</span></div>
+<details id="maps-diagnostics"><summary>Analysis coverage and unresolved relations</summary><div id="maps-diagnostic-list"></div></details>
+<div id="map-files"></div><div id="map-chunks"></div>
+</div></details>
+'''
+
+SCRIPT = r'''
+window.SmartMaps=(()=>{
+ const byId=id=>document.getElementById(id),ns='http://www.w3.org/2000/svg';
+ let data=null,project=null,mode='network',selectedNode=null,focus=false,positions=new Map(),zoom=1,panX=0,panY=0,drag=null,requestId=0,aborter=null;
+ let currentNodes=[],currentEdges=[],shown=[],shownEdges=[],globalLookup=new Map();
+ const description={network:'Arrows represent resolved local references: imports, Java types, templates, styles and document links. External targets are listed in the details.',coverage:'Area proportional to the lines stored in the index. Grouped by folder. The map covers the files present in this view.',calls:'Arrows represent resolved static calls between functions, methods and classes. They do not represent an execution trace.'};
+ const statusLabel={indexed:'Local metadata checked',pending:'File changed since indexing',missing:'File not found in the current directory',stored:'Content stored; local state not compared'};
+ const palette=['blue','teal','violet','amber','rose','sky','orange','green'];
+ const statePalette={indexed:'green',pending:'amber',missing:'rose',stored:'blue'};
+ function moduleKey(node){const file=node.file||node,path=file.path||node.path||'',folder=file.group||'(root)';if(folder==='(root)')return path.split('/').pop()||'(root)';const parts=folder.split('/');return parts.slice(0,parts[0]==='src'?2:1).join('/')}
+ function moduleColor(key){let hash=2166136261;for(const ch of key)hash=Math.imul(hash^ch.codePointAt(0),16777619);return palette[(hash>>>0)%palette.length]}
+ function paint(node){return byId('maps-color-mode').value==='status'?(statePalette[node.file?.status||node.status]||'blue'):moduleColor(moduleKey(node))}
+ function decorateNode(group,node){const shade=paint(node);for(const role of ['fill','stroke','ink'])group.style.setProperty('--node-'+role,`var(--map-${shade}-${role})`);group.classList.add(node.file?.status||node.status||'stored')}
+ function edgeElement(tag,attrs,edge){const shade=paint(globalLookup.get(edge.source)||{}),node=element(tag,{...attrs,'marker-end':`url(#maps-arrow-${shade})`});node.style.setProperty('--edge-color',`var(--map-${shade}-stroke)`);return node}
+ function renderLegend(){const host=byId('maps-color-legend'),byState=byId('maps-color-mode').value==='status',groups=new Map();host.replaceChildren();const intro=document.createElement('strong');intro.textContent=byState?'Index status:':'Modules / folders:';host.append(intro);for(const node of shown){const key=byState?(node.file?.status||node.status||'stored'):moduleKey(node);if(!groups.has(key))groups.set(key,{count:0,shade:paint(node)});groups.get(key).count++}for(const [key,item] of [...groups].sort((a,b)=>a[0].localeCompare(b[0]))){const label=document.createElement('span'),swatch=document.createElement('i');swatch.className='maps-swatch';swatch.setAttribute('aria-hidden','true');swatch.style.setProperty('--swatch-fill',`var(--map-${item.shade}-fill)`);swatch.style.setProperty('--swatch-stroke',`var(--map-${item.shade}-stroke)`);label.append(swatch,document.createTextNode((byState?statusLabel[key]:key)+' ('+item.count+')'));host.append(label)}byId('maps-color-note').textContent=byState?'Fill by status · dashed border means changed or missing.':'Fill by module/folder · dashed border means changed or missing.'}
+ function element(tag,attrs={},text){const node=document.createElementNS(ns,tag);for(const [k,v] of Object.entries(attrs))node.setAttribute(k,String(v));if(text!==undefined)node.textContent=text;return node}
+ function plainList(host,rows){host.replaceChildren();for(const text of rows){const p=document.createElement('p');p.textContent=text;host.append(p)}}
+ function clearSelection(){byId('maps-selected').textContent='Select an element';for(const id of ['maps-path','maps-state','maps-facts'])byId(id).textContent='';byId('maps-relation-title').textContent=mode==='calls'?'Static calls':'File dependencies';byId('maps-relations').replaceChildren();byId('maps-read').disabled=true}
+ function reset(){++requestId;aborter?.abort();data=null;project=null;selectedNode=null;positions.clear();currentNodes=[];currentEdges=[];shown=[];shownEdges=[];globalLookup.clear();byId('maps-world').replaceChildren();byId('maps-color-legend').replaceChildren();byId('map-files').replaceChildren();byId('map-chunks').replaceChildren();byId('maps-diagnostic-list').replaceChildren();byId('map-view').replaceChildren(new Option('Current view or available legacy',''));byId('maps-folder').replaceChildren(new Option('All',''));byId('maps-symbol-picker').replaceChildren(new Option('Select…',''));byId('maps-search').value='';byId('map-info').textContent='Load the maps of this project. The analysis is local and creates no embeddings.';byId('maps-count').textContent='';byId('maps-empty').hidden=false;byId('maps-empty').textContent='Load a view to explore the three maps.';byId('load-map').disabled=false;byId('maps-popup-link').hidden=true;byId('maps-popup-link').removeAttribute('href');clearSelection()}
+ async function load(view,restore=null){const key=selected,id=++requestId;aborter?.abort();aborter=new AbortController();byId('load-map').disabled=true;byId('map-info').textContent='Reading the snapshot and analyzing imports and calls…';try{const response=await fetch('/setup/projects',{method:'POST',headers:{'Content-Type':'application/json','X-Setup-Token':token},body:JSON.stringify({action:'graph',project_id:key,...(view?{view_id:view}:{})}),signal:aborter.signal});const result=await response.json();if(!response.ok)throw Error(result.error||'Could not load the maps.');if(id!==requestId||key!==selected)return;data=result;project=key;selectedNode=null;focus=false;positions.clear();byId('map-view').replaceChildren(...data.views.map(v=>new Option(v.label+(v.current?' (active)':'')+' · '+v.files+' files',v.view_id)));if(data.selected)byId('map-view').value=data.selected.view_id;byId('map-info').textContent=data.selected?`${data.selected.label} · ${data.counts.files} files · ${data.counts.parsed_files} analyzed. ${data.selected.current?'Indexed content; local changes may be pending.':'Stored snapshot. Current view: '+(data.current_view?.label||'not identified')+'.'}`:data.message;byId('maps-folder').replaceChildren(new Option('All',''),...Array.from(new Set(data.files.map(f=>f.group))).sort().map(f=>new Option(f,f)));byId('map-chunks').replaceChildren();renderDiagnostics();if(restore){byId('maps-search').value=restore.q||'';if([...byId('maps-folder').options].some(o=>o.value===restore.folder))byId('maps-folder').value=restore.folder;if(['60','120','250'].includes(restore.limit))byId('maps-limit').value=restore.limit;if(['module','status'].includes(restore.colors))byId('maps-color-mode').value=restore.colors}refreshGraph(true);if(restore?.node&&globalLookup.has(restore.node)){selectedNode=restore.node;focus=restore.focus==='1';refreshGraph(true)}}catch(e){if(e.name!=='AbortError'&&id===requestId){byId('map-info').textContent=e.message+' Use Load maps to try again.';message(e.message,true)}}finally{if(id===requestId)byId('load-map').disabled=false}}
+ function renderDiagnostics(){const c=data.counts||{},lines=[`Local analysis of Java, Angular, Python, JavaScript/TypeScript, HTML/CSS and Markdown links. TXT and DOCX show up in coverage and in text search. ${c.parsed_files||0} of ${c.files||0} files were analyzed. Other languages and incomplete snapshots remain available in coverage.`,`${c.resolved_imports||0} resolved internal references; ${c.external_imports||0} external references; ${c.calls||0} call relations. Unresolved targets are a limited sample (${c.unresolved_calls||0} records in the analysis).`];if(data.truncated)lines.push('The analysis limits were reached. Filter by folder to explore the available part.');lines.push(...(data.diagnostics||[]).slice(0,60).map(d=>d.path+': '+d.reason));lines.push(...(data.unresolved||[]).slice(0,40).map(u=>u.path+':'+u.line+' · '+u.expression+' — '+u.reason));plainList(byId('maps-diagnostic-list'),lines)}
+ function prepare(){const files=new Map((data?.files||[]).map(f=>[f.path,f]));currentNodes=mode==='calls'?(data?.symbols||[]).map(s=>({...s,file:files.get(s.path),label:s.name==='callback'?'callback :'+s.start_line:s.name})): (data?.files||[]).map(f=>({...f,file:f,label:/^(index|styles|__init__)\./.test(f.path.split('/').pop())?f.path.split('/').slice(-2).join('/'):f.path.split('/').pop()}));globalLookup=new Map(currentNodes.map(n=>[n.id,n]));currentEdges=(mode==='calls'?data?.calls:data?.dependencies)||[];currentEdges=currentEdges.filter(e=>e.target&&globalLookup.has(e.source)&&globalLookup.has(e.target));}
+ function chooseVisible(){const term=byId('maps-search').value.trim().toLocaleLowerCase(),folder=byId('maps-folder').value,limit=Number(byId('maps-limit').value);const degree=new Map();for(const e of currentEdges){degree.set(e.source,(degree.get(e.source)||0)+1);degree.set(e.target,(degree.get(e.target)||0)+1)}let list=currentNodes.filter(n=>(!folder||n.file?.group===folder)&&(!term||(n.path+' '+n.label).toLocaleLowerCase().includes(term)));if(focus&&selectedNode){const near=new Set([selectedNode]);for(const e of currentEdges){if(e.source===selectedNode)near.add(e.target);if(e.target===selectedNode)near.add(e.source)}list=currentNodes.filter(n=>near.has(n.id))}list.sort((a,b)=>mode==='coverage'?(b.lines||0)-(a.lines||0):((degree.get(b.id)||0)-(degree.get(a.id)||0)||a.path.localeCompare(b.path)));if(selectedNode&&globalLookup.has(selectedNode)&&list.some(n=>n.id===selectedNode))list=[globalLookup.get(selectedNode),...list.filter(n=>n.id!==selectedNode)];shown=list.slice(0,limit);const ids=new Set(shown.map(n=>n.id));shownEdges=currentEdges.filter(e=>ids.has(e.source)&&ids.has(e.target)).slice(0,1000);byId('maps-count').textContent=mode==='coverage'?`${shown.length} of ${list.length} files · area by lines`:`${shown.length} of ${list.length} nodes · ${shownEdges.length} visible relations${focus?' · selected neighborhood':''}`;byId('maps-empty').hidden=!!shown.length;byId('maps-empty').textContent=mode==='calls'?'No resolved functions in this selection. Check the diagnostics or choose another folder/view.':'No files match the filter.';byId('maps-symbol-picker').replaceChildren(new Option('Select…',''),...list.slice(0,1000).map(n=>new Option(n.label+' · '+n.path,n.id)));if(selectedNode)byId('maps-symbol-picker').value=selectedNode;}
+ function layout(){const groups=new Map();for(const n of shown){const pathGroup=n.file?.group||'(root)',parts=pathGroup.split('/'),g=parts.slice(0,parts[0]==='src'?2:1).join('/');if(!groups.has(g))groups.set(g,[]);groups.get(g).push(n)}const sorted=[...groups].sort((a,b)=>b[1].length-a[1].length);const cols=Math.max(1,Math.ceil(Math.sqrt(sorted.length*1.4)));let i=0;for(const [group,nodes] of sorted){const step=mode==='calls'?580:440,cx=210+(i%cols)*step,cy=210+Math.floor(i/cols)*step;nodes.forEach((n,j)=>{if(!positions.has(n.id)){const ring=Math.floor(Math.sqrt(j)),angle=j*2.399963,rad=nodes.length===1?0:mode==='calls'?90+ring*105:50+ring*65;positions.set(n.id,{x:cx+Math.cos(angle)*rad,y:cy+Math.sin(angle)*rad})}});i++}}
+ function bounds(){const points=shown.map(n=>positions.get(n.id)).filter(Boolean);if(!points.length)return {x:0,y:0,w:1000,h:650};const xs=points.map(p=>p.x),ys=points.map(p=>p.y);return {x:Math.min(...xs)-100,y:Math.min(...ys)-60,w:Math.max(...xs)-Math.min(...xs)+200,h:Math.max(...ys)-Math.min(...ys)+120}}
+ function transform(){byId('maps-world').setAttribute('transform',`translate(${panX} ${panY}) scale(${zoom})`)}
+ function fit(){if(mode==='coverage'){zoom=1;panX=panY=0}else{const b=bounds();zoom=Math.min(2.4,900/b.w,560/b.h);panX=500-(b.x+b.w/2)*zoom;panY=325-(b.y+b.h/2)*zoom}transform()}
+ function color(node){return ['pending','missing'].includes(node.file?.status)?'var(--warn)':node.file?.status==='indexed'?'var(--good)':'var(--muted)'}
+ function wire(group,node){decorateNode(group,node);group.dataset.graphNode=node.id;group.setAttribute('role','button');group.setAttribute('tabindex','0');group.setAttribute('aria-label',node.label+' — '+node.path);group.addEventListener('keydown',e=>{if(e.key==='Enter'||e.key===' '){e.preventDefault();selectNode(node.id,true)}})}
+ function render(){renderLegend();const world=byId('maps-world');world.replaceChildren();if(mode==='coverage'){coverage(world);transform();return}for(const edge of shownEdges){const a=positions.get(edge.source),b=positions.get(edge.target);if(!a||!b)continue;if(edge.source===edge.target){const r=mode==='calls'?70:35;world.append(edgeElement('path',{d:`M${a.x+r/2} ${a.y-20} C${a.x+r*2} ${a.y-r*2},${a.x-r*2} ${a.y-r*2},${a.x-r/2} ${a.y-20}`,class:'maps-edge'+(edge.source===selectedNode?' active':''),'marker-end':'url(#maps-arrow)'},edge));continue}const dx=b.x-a.x,dy=b.y-a.y,len=Math.hypot(dx,dy)||1,r=mode==='calls'?Math.min(65/(Math.abs(dx)/len||.0001),20/(Math.abs(dy)/len||.0001))+8:22+Math.min(12,Math.sqrt(globalLookup.get(edge.target)?.chunks||1));world.append(edgeElement('line',{x1:a.x,y1:a.y,x2:b.x-dx/len*r,y2:b.y-dy/len*r,class:'maps-edge'+([edge.source,edge.target].includes(selectedNode)?' active':''),'marker-end':'url(#maps-arrow)'},edge))}for(const n of shown){const p=positions.get(n.id),g=element('g',{class:'maps-node'+(n.id===selectedNode?' active':'')});if(mode==='calls'){g.append(element('rect',{x:p.x-65,y:p.y-20,width:130,height:40,rx:6,stroke:color(n)}));g.append(element('text',{x:p.x,y:p.y+4,'text-anchor':'middle',class:'on-node'},n.label.length>18?n.label.slice(0,16)+'…':n.label))}else{g.append(element('circle',{cx:p.x,cy:p.y,r:14+Math.min(12,Math.sqrt(n.chunks||1)),stroke:color(n),'stroke-dasharray':['pending','missing'].includes(n.status)?'4 3':'none'}));g.append(element('text',{x:p.x,y:p.y+4,'text-anchor':'middle',class:'on-node'},String(n.chunks||0)));g.append(element('text',{x:p.x,y:p.y+39,'text-anchor':'middle'},n.label.length>24?n.label.slice(0,22)+'…':n.label))}g.append(element('title',{},n.path+' · '+n.label));wire(g,n);world.append(g)}transform()}
+ function partition(items,x,y,w,h,weight,paint){if(!items.length)return;if(items.length===1){paint(items[0],x,y,w,h);return}const total=items.reduce((s,n)=>s+weight(n),0);let sum=0,cut=1;for(let i=0;i<items.length-1;i++){sum+=weight(items[i]);cut=i+1;if(sum>=total/2)break}const r=sum/total;if(w>=h){partition(items.slice(0,cut),x,y,w*r,h,weight,paint);partition(items.slice(cut),x+w*r,y,w*(1-r),h,weight,paint)}else{partition(items.slice(0,cut),x,y,w,h*r,weight,paint);partition(items.slice(cut),x,y+h*r,w,h*(1-r),weight,paint)}}
+ function coverage(world){const groups=new Map();for(const n of shown){const key=n.file?.group||'(root)';if(!groups.has(key))groups.set(key,[]);groups.get(key).push(n)}const weight=n=>Math.max(n.lines||n.file?.lines||1,1);partition([...groups],10,10,980,620,g=>g[1].reduce((s,n)=>s+weight(n),0),(entry,x,y,w,h)=>{world.append(element('rect',{x:x+2,y:y+2,width:Math.max(w-4,1),height:Math.max(h-4,1),fill:'var(--surface)',stroke:'var(--border)',rx:5}));const title=entry[0];if(w>60&&h>35)world.append(element('text',{x:x+10,y:y+18,class:'maps-folder-label'},title.length>Math.floor(w/7)?title.slice(0,Math.floor(w/7)-2)+'…':title));partition(entry[1],x+5,y+25,Math.max(w-10,1),Math.max(h-30,1),weight,(n,fx,fy,fw,fh)=>{const g=element('g',{class:'maps-node'+(n.id===selectedNode?' active':'')});g.append(element('rect',{x:fx+2,y:fy+2,width:Math.max(fw-4,1),height:Math.max(fh-4,1),rx:3,stroke:color(n),'stroke-dasharray':['pending','missing'].includes(n.status)?'4 3':'none'}));if(fw>50&&fh>30){const max=Math.max(4,Math.floor((fw-16)/7));g.append(element('text',{x:fx+8,y:fy+20,class:'on-node'},n.label.length>max?n.label.slice(0,max-1)+'…':n.label));if(fh>50&&fw>100){const detail=`${n.lines} lines · ${n.chunks} chunks`;g.append(element('text',{x:fx+8,y:fy+39,class:'secondary'},detail.length>max?detail.slice(0,max-1)+'…':detail))}}g.append(element('title',{},n.path));wire(g,n);world.append(g)})})}
+ function inspector(){const n=globalLookup.get(selectedNode);if(!n){clearSelection();return}byId('maps-selected').textContent=n.label;byId('maps-path').textContent=n.path;byId('maps-state').textContent=statusLabel[n.file?.status]||'Indexed snapshot';byId('maps-facts').textContent=mode==='calls'?`${n.kind} · lines ${n.start_line}–${n.end_line} · ${n.language}`:`${n.lines||0} ${n.file?.location_kind==='extracted_text_line'?'extracted lines':'lines'} · ${n.chunks||0} chunks · ${n.size==null||n.size<0?'size not recorded':n.size+' bytes'}`;byId('maps-read').disabled=false;byId('maps-relations').replaceChildren();byId('maps-relation-title').textContent=mode==='calls'?'Static calls':'File dependencies';const edges=currentEdges.filter(e=>e.source===selectedNode||e.target===selectedNode);for(const e of edges.slice(0,40)){const id=e.source===selectedNode?e.target:e.source,node=globalLookup.get(id),li=document.createElement('li'),button=document.createElement('button');button.textContent=(e.source===selectedNode?'→ ':'← ')+(node?.label||id)+(e.count>1?' ('+e.count+' sites)':'');button.onclick=()=>selectNode(id);li.append(button);byId('maps-relations').append(li)}if(mode!=='calls')for(const e of (data.dependencies||[]).filter(e=>e.source===n.path&&!e.target).slice(0,15)){const li=document.createElement('li');li.textContent=e.specifier+' · '+(e.resolution==='external'?'external':'unresolved');byId('maps-relations').append(li)}if(!byId('maps-relations').children.length){const li=document.createElement('li');li.textContent='No resolved internal relations in this selection.';byId('maps-relations').append(li)}}
+ function renderFiles(){const term=byId('maps-search').value.trim().toLocaleLowerCase(),folder=byId('maps-folder').value;const files=(data?.files||[]).filter(f=>(!folder||f.group===folder)&&(!term||f.path.toLocaleLowerCase().includes(term))).slice(0,150);byId('map-files').innerHTML='<p class="muted">Files in the selection · up to 150 items. Filter by path to find others.</p>'+files.map(f=>`<button class="project-item" data-file="${esc(f.path)}"><strong>${esc(f.path)}</strong><small>${f.chunks} chunks · ${esc(statusLabel[f.status]||'Snapshot')}</small></button>`).join('')}
+ function publishWindowState(){if(document.body.classList.contains('map-window')&&data?.selected){const state=windowState();history.replaceState(null,'','/maps#'+state.toString())}}
+ function refreshGraph(reframe=false){prepare();chooseVisible();if(reframe)positions.clear();layout();render();if(reframe)fit();inspector();renderFiles();byId('maps-description').textContent=description[mode];publishWindowState()}
+ function selectNode(id,keyboard=false){selectedNode=id;focus=mode!=='coverage';refreshGraph(true);if(keyboard)byId('maps-world').querySelector('[data-graph-node="'+CSS.escape(id)+'"]')?.focus()}
+ async function readFile(path){if(!data?.selected||project!==selected)return;const key=selected,view=data.selected.view_id,request=requestId;try{const detail=await api({action:'inspect',project_id:key,view_id:view,file_path:path});if(key!==selected||request!==requestId)return;byId('map-chunks').innerHTML='<h3>'+esc(path)+'</h3><p class="muted">Text of the stored view; up to 100 chunks. May differ from the current file.</p>'+detail.chunks.map(c=>`<details><summary>${c.location_kind==='extracted_text_line'?'Extracted text lines':'Lines'} ${c.start_line}–${c.end_line} · ${c.dimensions} dimensions</summary><pre>${esc(c.text)}</pre></details>`).join('');byId('map-chunks').scrollIntoView({block:'nearest',behavior:'auto'})}catch(e){message(e.message,true)}}
+ function switchMode(value){mode=value;focus=false;selectedNode=null;positions.clear();for(const b of document.querySelectorAll('[data-map-mode]')){const active=b.dataset.mapMode===mode;b.setAttribute('aria-selected',String(active));b.tabIndex=active?0:-1}byId('maps-panel').setAttribute('aria-labelledby','map-tab-'+mode);if(data)refreshGraph(true);else byId('maps-description').textContent=description[mode];publishWindowState()}
+ document.querySelectorAll('[data-map-mode]').forEach(b=>{b.onclick=()=>switchMode(b.dataset.mapMode);b.onkeydown=e=>{if(['ArrowLeft','ArrowRight','Home','End'].includes(e.key)){e.preventDefault();const tabs=[...document.querySelectorAll('[data-map-mode]')],i=tabs.indexOf(b),j=e.key==='Home'?0:e.key==='End'?2:(i+(e.key==='ArrowRight'?1:2))%3;tabs[j].focus();switchMode(tabs[j].dataset.mapMode)}}});
+ byId('load-map').onclick=()=>load(byId('map-view').value||undefined);byId('map-view').onchange=()=>load(byId('map-view').value);byId('maps-search').oninput=()=>{focus=false;selectedNode=null;refreshGraph(true)};byId('maps-folder').onchange=()=>{focus=false;selectedNode=null;positions.clear();refreshGraph(true)};byId('maps-limit').onchange=()=>refreshGraph(true);byId('maps-all').onclick=()=>{focus=false;selectedNode=null;refreshGraph(true)};byId('maps-symbol-picker').onchange=()=>{if(byId('maps-symbol-picker').value)selectNode(byId('maps-symbol-picker').value)};byId('maps-read').onclick=()=>{const n=globalLookup.get(selectedNode);if(n)readFile(n.path)};byId('map-files').onclick=e=>{const b=e.target.closest('[data-file]');if(b)readFile(b.dataset.file)};
+ function point(e){const p=byId('maps-svg').createSVGPoint();p.x=e.clientX;p.y=e.clientY;return p.matrixTransform(byId('maps-svg').getScreenCTM().inverse())}
+ function scale(factor,p={x:500,y:325}){const next=Math.min(8,Math.max(.15,zoom*factor));panX=p.x-(p.x-panX)*next/zoom;panY=p.y-(p.y-panY)*next/zoom;zoom=next;transform()}
+ byId('maps-plus').onclick=()=>scale(1.3);byId('maps-minus').onclick=()=>scale(1/1.3);byId('maps-fit').onclick=fit;byId('maps-expand').onclick=async()=>{try{if(document.fullscreenElement)await document.exitFullscreen();else await byId('map-details').requestFullscreen()}catch{message('The browser did not open full screen; the map is still available on the page.',true)}};
+ const svg=byId('maps-svg');for(const shade of palette){const marker=element('marker',{id:'maps-arrow-'+shade,markerWidth:8,markerHeight:8,refX:7,refY:4,orient:'auto',markerUnits:'userSpaceOnUse'});marker.append(element('path',{d:'M0 0 L8 4 L0 8',fill:`var(--map-${shade}-stroke)`}));svg.querySelector('defs').append(marker)}svg.addEventListener('wheel',e=>{e.preventDefault();scale(e.deltaY<0?1.1:1/1.1,point(e))},{passive:false});svg.addEventListener('pointerdown',e=>{if(e.button!==0)return;const p=point(e),node=e.target.closest('[data-graph-node]');drag={id:node?.dataset.graphNode||null,start:p,last:p,moved:false};svg.setPointerCapture(e.pointerId)});svg.addEventListener('pointermove',e=>{if(!drag)return;const p=point(e),dx=p.x-drag.last.x,dy=p.y-drag.last.y;if(Math.abs(p.x-drag.start.x)+Math.abs(p.y-drag.start.y)>5)drag.moved=true;if(drag.moved){if(drag.id&&mode!=='coverage'){const pos=positions.get(drag.id);if(pos){pos.x+=dx/zoom;pos.y+=dy/zoom;render()}}else{panX+=dx;panY+=dy;transform()}}drag.last=p});svg.addEventListener('pointerup',e=>{const previous=drag;drag=null;if(previous&&!previous.moved&&previous.id)selectNode(previous.id);if(svg.hasPointerCapture(e.pointerId))svg.releasePointerCapture(e.pointerId)});svg.addEventListener('pointercancel',()=>drag=null);
+ function windowState(){return new URLSearchParams({project:selected,view:data?.selected?.view_id||byId('map-view').value||'',mode,q:byId('maps-search').value,folder:byId('maps-folder').value,limit:byId('maps-limit').value,colors:byId('maps-color-mode').value,node:selectedNode||'',focus:focus?'1':'0'})}
+ function openWindow(){const url=new URL('/maps',location.origin);url.hash=windowState().toString();byId('maps-popup-link').hidden=true;const popup=window.open('','_blank','popup,width=1440,height=960,resizable=yes,scrollbars=yes');if(popup){popup.opener=null;popup.location.replace(url.href)}else{const link=byId('maps-popup-link');link.href=url.href;link.hidden=false;message('The browser blocked the window. Use the Open map separately link.',true)}}
+ byId('maps-new-window').onclick=openWindow;
+ byId('maps-color-mode').onchange=()=>{render();publishWindowState()};
+ async function restore(state){if(['network','coverage','calls'].includes(state.mode))switchMode(state.mode);await load(state.view||undefined,state)}
+ return {reset,load,restore,openWindow};
+})();
+'''

package/project_monitor.py

@@ -0,0 +1,204 @@
+"""Eventos Windows + reconciliação: fila apenas para projetos habilitados pelo usuário."""
+import os
+import threading
+import time
+
+import config
+import directory_watch
+import indexer
+import local_embedder
+import index_scope
+import project_store
+import index_views
+
+DEBOUNCE_S = 5
+RECONCILE_S = 180
+FULL_CHECK_S = 86400
+MAX_EVENT_PATHS = 1000
+
+
+def relevant_path(path):
+    parts = path.replace("\\", "/").strip("/").split("/")
+    return bool(parts and all(part not in ("", ".", "..") and not part.startswith(".")
+                              and not index_scope.always_excluded(part) for part in parts))
+
+
+def snapshot(root, scope):
+    result = {}
+    for rel in index_scope.resolve_included_files(root, scope):
+        stat, _reason = indexer._stat_candidate(root, rel)
+        if stat is not None:
+            result[rel] = stat
+    return result
+
+
+
+def index_model(current=None):
+    return local_embedder.resolve(config.load_config().get("embedding_model"), current)
+
+
+def needs_model_rebuild(meta, configured_model):
+    return meta.get("model_id") != configured_model or not meta.get("exists")
+
+class ProjectMonitor:
+    def __init__(self, enqueue, watcher_factory=directory_watch.DirectoryWatcher):
+        self.enqueue = enqueue
+        self.watcher_factory = watcher_factory
+        self._watchers = {}
+        self._retry_watch = {}
+        self._checked = {}
+        self._git_seen = {}
+        self._git_checked = {}
+        self._pending = {}
+        self._lock = threading.RLock()
+        self._stop = threading.Event()
+        self._thread = None
+
+    def start(self):
+        self._thread = threading.Thread(target=self._run, name="project-monitor", daemon=True)
+        self._thread.start()
+
+    def stop(self):
+        self._stop.set()
+        if self._thread:
+            self._thread.join(timeout=3)
+        with self._lock:
+            watchers = list(self._watchers.values())
+            self._watchers.clear()
+        for watcher in watchers:
+            watcher.stop()
+
+    def refresh(self):
+        self._checked.clear()
+
+    def events(self, project_id, rows, overflow=False):
+        project = project_store.get(project_id)
+        if not project or project.get("paused") or not project.get("watch") or not project.get("enabled"):
+            return
+        paths = {row["path"] for row in rows if relevant_path(row.get("path", ""))}
+        if not paths and not overflow:
+            return
+        # Um diretório existente também recebe MODIFIED ao mudar um arquivo filho.
+        # Só uma estrutura nova ou documentação da raiz exige reavaliar o escopo.
+        scope = index_scope.load_scope(project["root"]) or {}
+        known_dirs = {p.casefold() for p in scope.get("structure", [])}
+        docs = {name.casefold() for name in index_scope._ROOT_DOC_NAMES}
+        force_scope = any(path.casefold() in docs for path in paths) or any(
+            row.get("action") in (1, 5) and row.get("path") in paths
+            and row["path"].casefold() not in known_dirs
+            and os.path.isdir(os.path.join(project["root"], row["path"])) for row in rows)
+        force_scope = force_scope and not scope.get("manual", False)
+        with self._lock:
+            first = project_id not in self._pending
+            state = self._pending.setdefault(project_id, {"paths": set(), "full": False, "force_scope": False, "revision": 0})
+            state["revision"] = state.get("revision", 0) + 1
+            state["paths"].update(paths)
+            state["last"] = time.monotonic()
+            state["full"] |= overflow or len(state["paths"]) > MAX_EVENT_PATHS
+            state["force_scope"] |= force_scope
+            if state["full"]:
+                state["paths"].clear()
+        project_store.mark_dirty(project_id, "Changes detected by the monitor.")
+        project_store.record_changes(project_id, paths, full=overflow, scope=force_scope)
+
+    def _watch_error(self, project_id, message):
+        project_store.update(project_id, watch_backend="reconciliation", watch_error=message[:300])
+        self._retry_watch[project_id] = time.monotonic() + RECONCILE_S
+        self.events(project_id, [], overflow=True)
+
+    def _sync_watchers(self, projects, now):
+        wanted = {p["id"]: p for p in projects if p.get("watch") and p.get("enabled")
+                  and not p.get("paused") and os.path.isdir(p["root"])}
+        for key in list(self._watchers):
+            if key not in wanted:
+                watcher = self._watchers.pop(key)
+                watcher.stop()
+                project_store.update(key, watch_backend="off")
+        for key, project in wanted.items():
+            current = self._watchers.get(key)
+            if current and current.alive:
+                continue
+            if now < self._retry_watch.get(key, 0):
+                continue
+            watcher = self.watcher_factory(
+                project["root"], lambda rows, overflow, k=key: self.events(k, rows, overflow),
+                lambda error, k=key: self._watch_error(k, error),
+            )
+            self._watchers[key] = watcher
+            project_store.update(key, watch_backend="windows_events", watch_error="")
+            watcher.start()
+
+    def tick(self):
+        now = time.monotonic()
+        projects = project_store.all_projects()
+        self._sync_watchers(projects, now)
+        for project in projects:
+            key = project["id"]
+            if not project.get("watch") or not project.get("enabled") or project.get("paused"):
+                continue
+            if not os.path.isdir(project["root"]):
+                project_store.update(key, status="unavailable", last_error="The folder is not accessible.")
+                continue
+            if any(job.get("status") == "pending" for job in project_store.jobs(key, limit=50)):
+                continue  # Não planejar outra geração com metadados de uma ainda em curso.
+            if now - self._git_checked.get(key, -5) >= 5:
+                view = index_views.describe(project['root'], fresh=True)
+                signature = (view['view_id'], view.get('commit'))
+                if key in self._git_seen and signature != self._git_seen[key]:
+                    self.events(key, [], overflow=True)
+                self._git_seen[key] = signature
+                self._git_checked[key] = now
+            if now - self._checked.get(key, -RECONCILE_S) >= RECONCILE_S:
+                self._checked[key] = now
+                scope = index_scope.load_scope(project["root"])
+                meta = indexer.info(project["root"])
+                rescope = scope is None or index_scope.needs_rescan(project["root"], scope)
+                changed = rescope
+                if scope is not None:
+                    changed |= snapshot(project["root"], scope) != indexer.manifest_snapshot(project["root"])
+                full = time.time() - meta.get("full_scan_at", 0) >= FULL_CHECK_S
+                changed |= needs_model_rebuild(meta, index_model(meta.get("model_id")))
+                project_store.update(key, last_checked=time.time())
+                if changed or full or project.get("dirty_seq", 0) > project.get("indexed_seq", 0):
+                    with self._lock:
+                        first = key not in self._pending
+                        state = self._pending.setdefault(key, {"paths": set(), "last": now - DEBOUNCE_S,
+                                                               "full": False, "force_scope": False, "revision": 0})
+                        state["full"] |= full
+                        state["force_scope"] |= rescope
+                    if first:
+                        project_store.mark_dirty(key, "Reconciliation found a pending update.")
+                    project_store.record_changes(key, full=full, scope=rescope)
+            # Monitoramento local é independente do gasto com o modelo. O padrão
+            # somente registra pendência; a próxima busca executa o diff e embeddings.
+            if project.get('update_mode', 'on_search') != 'eager':
+                with self._lock:
+                    self._pending.pop(key, None)
+                continue
+            with self._lock:
+                pending = self._pending.get(key)
+                if not pending or now - pending["last"] < DEBOUNCE_S:
+                    continue
+                options = {"changed_paths": sorted(pending["paths"]), "full_check": pending["full"],
+                           "force_scope": pending["force_scope"]}
+                revision = pending.get("revision", 0)
+            current = project_store.get(key)
+            if time.time() < current.get("next_retry_at", 0):
+                continue
+            try:
+                self.enqueue(key, **options)
+            except Exception as exc:
+                project_store.update(key, status="error", last_error=str(exc)[:300], next_retry_at=time.time() + 60)
+                continue
+            with self._lock:
+                # Um evento recebido durante o submit continua pendente para a próxima geração.
+                if self._pending.get(key) is pending and pending.get("revision", 0) == revision:
+                    self._pending.pop(key, None)
+
+    def _run(self):
+        while not self._stop.is_set():
+            try:
+                self.tick()
+            except Exception:
+                pass  # Falha opcional do monitor não derruba o daemon MCP.
+            self._stop.wait(1)

package/project_scheduler.py

@@ -0,0 +1,61 @@
+"""Fila justa entre raízes; jobs aguardando a mesma pasta não ocupam workers."""
+import collections
+import concurrent.futures
+import threading
+
+import project_identity
+
+
+class ProjectScheduler:
+    def __init__(self, workers=3):
+        self.workers = workers
+        self._pool = concurrent.futures.ThreadPoolExecutor(max_workers=workers, thread_name_prefix="project")
+        self._lock = threading.RLock()
+        self._queues = collections.OrderedDict()
+        self._running = set()
+        self._closed = False
+
+    def submit(self, root, function, *args):
+        key = project_identity.canonical_root(root)
+        future = concurrent.futures.Future()
+        with self._lock:
+            if self._closed:
+                raise RuntimeError("Project queue closed.")
+            self._queues.setdefault(key, collections.deque()).append((future, function, args))
+            self._dispatch()
+        return future
+
+    def _dispatch(self):
+        while len(self._running) < self.workers:
+            key = next((root for root in self._queues if root not in self._running), None)
+            if key is None:
+                break
+            task = self._queues[key].popleft()
+            if not self._queues[key]:
+                self._queues.pop(key)
+            else:
+                self._queues.move_to_end(key)
+            self._running.add(key)
+            self._pool.submit(self._run, key, task)
+
+    def _run(self, key, task):
+        future, function, args = task
+        try:
+            if future.set_running_or_notify_cancel():
+                try:
+                    future.set_result(function(*args))
+                except BaseException as exc:
+                    future.set_exception(exc)
+        finally:
+            with self._lock:
+                self._running.discard(key)
+                self._dispatch()
+
+    def shutdown(self, wait=True):
+        with self._lock:
+            self._closed = True
+            for queue in self._queues.values():
+                for future, _fn, _args in queue:
+                    future.cancel()
+            self._queues.clear()
+        self._pool.shutdown(wait=wait, cancel_futures=True)

package/project_storage.py

@@ -0,0 +1,165 @@
+"""Prévia e limpeza seletiva de visões locais; raiz ativa e fixadas são protegidas."""
+import contextlib
+import hashlib
+import json
+import os
+import re
+import secrets
+import sqlite3
+import time
+from pathlib import Path
+
+import code_graph
+import embedding_cache
+import index_inventory
+import index_scope
+import indexer
+import index_views
+import project_identity
+import project_store
+
+_PLANS={}
+
+
+def _assets(root):
+    files={}
+    for key in dict.fromkeys([project_identity.project_id(root),*project_identity.legacy_ids(root)]):
+        pattern=re.compile(re.escape(key)+r'(?:\.v-[a-f0-9]{16})?(?:\.previous|\.building-[a-f0-9]+|\.vectors)?\.sqlite3$')
+        for path in Path(indexer.INDEX_DIR).glob(key+'*.sqlite3'):
+            if pattern.fullmatch(path.name):files[path.name]=str(path)
+    return files
+
+
+def _stamp(path):
+    stat=os.stat(path);return [stat.st_size,stat.st_mtime_ns,stat.st_ino]
+
+
+def inventory(project):
+    root=project['root'];views=index_inventory.views(root);assets=_assets(root)
+    active=indexer.existing_db_path(root)
+    for view in views:view['current']=bool(active and os.path.normcase(view['path'])==os.path.normcase(active))
+    pins=project.get('pinned_views',[])
+    fallback=None if any(v['current'] for v in views) else (max(views,key=lambda v:v.get('updated_at') or 0)['path'] if views else None)
+    rows=[]
+    for view in views:
+        row={**view,'storage_id':Path(view['path']).name,'pinned':view['view_id'] in pins}
+        row['protected_reason']='Active view' if view['current'] else 'Pinned view' if row['pinned'] else 'Last available view; the active branch has no index' if view['path']==fallback else ''
+        row['protected']=bool(row['protected_reason']);rows.append(row)
+    total=sum(os.path.getsize(path) for path in assets.values())
+    cache_path=Path(indexer.INDEX_DIR)/(project_identity.project_id(root)+'.vectors.sqlite3')
+    return {'views':rows,'total_bytes':total,'cache_bytes':cache_path.stat().st_size if cache_path.exists() else 0,
+            'auxiliary_bytes':max(0,total-sum(v['bytes'] for v in rows)-(cache_path.stat().st_size if cache_path.exists() else 0)),
+            'cleanup':'manual','source_files_untouched':True}
+
+
+def pin(project,storage_id,pinned):
+    if type(pinned) is not bool:raise ValueError('pinned must be true or false.')
+    row=next((v for v in inventory(project)['views'] if v['storage_id']==storage_id),None)
+    if row is None:raise ValueError('View not found in this project.')
+    pins=set(project.get('pinned_views',[]))
+    if pinned:pins.add(row['view_id'])
+    else:pins.discard(row['view_id'])
+    project_store.update(project['id'],pinned_views=sorted(pins))
+    return inventory(project_store.get(project['id']))
+
+
+def _cache_unused(root,assets,removed):
+    cache=Path(indexer.INDEX_DIR)/(project_identity.project_id(root)+'.vectors.sqlite3')
+    if not cache.exists():return [],0,''
+    keep=set()
+    for name,path in assets.items():
+        if path in removed or name.endswith('.vectors.sqlite3'):continue
+        with contextlib.closing(indexer._readonly(path)) as db:
+            meta=indexer._metadata(db)
+            if not all(meta.get(k) for k in ('model_id','dimensions','chunker_version','chunk_lines')):
+                return [],0,'Cache kept: a generation without a known model contract exists.'
+            contract={'model':meta['model_id'],'dimensions':meta['dimensions'],'chunker':meta['chunker_version'],'chunk_lines':meta['chunk_lines'],'preprocessing':1}
+            prefix=json.dumps(contract,sort_keys=True,ensure_ascii=False)+'\0'
+            for text, in db.execute('SELECT text FROM chunks'):
+                keep.add(hashlib.sha256((prefix+text).encode('utf-8')).hexdigest())
+                if len(keep)>1000000:return [],0,'Cache kept: reference check limit reached.'
+    with contextlib.closing(indexer._readonly(str(cache))) as db:
+        unused=[(key,size) for key,size in db.execute('SELECT key,length(vector) FROM vectors') if key not in keep]
+    return [key for key,_ in unused],sum(size for _,size in unused),''
+
+
+def preview(project,storage_ids,clear_cache=True):
+    if not isinstance(storage_ids,list) or any(not isinstance(x,str) for x in storage_ids) or len(storage_ids)>200:
+        raise ValueError('Choose up to 200 views of this project.')
+    storage_ids=sorted(set(storage_ids))
+    if type(clear_cache) is not bool:raise ValueError('clear_cache must be true or false.')
+    current=inventory(project);lookup={v['storage_id']:v for v in current['views']}
+    assets=_assets(project['root']);removed=[];selected=[]
+    for storage_id in set(storage_ids):
+        row=lookup.get(storage_id)
+        if not row:raise ValueError('A selected view no longer belongs to the project.')
+        if row['protected']:raise ValueError(row['label']+': '+row['protected_reason']+'.')
+        selected.append(row)
+        stem=storage_id[:-8]
+        removed.extend(path for name,path in assets.items() if name==storage_id or re.fullmatch(re.escape(stem)+r'(?:\.previous|\.building-[a-f0-9]+)\.sqlite3',name))
+        if '.v-' in stem:
+            scope=Path(index_scope.SCOPE_DIR)/(stem+'.scope.json')
+            if scope.is_file():removed.append(str(scope))
+    if not selected:raise ValueError('Select at least one unprotected view.')
+    for path in removed:project_identity.state_path(path,indexer.INDEX_DIR)
+    keys,vector_bytes,note=_cache_unused(project['root'],assets,set(removed)) if clear_cache else ([],0,'Shared cache kept by user choice.')
+    signature={path:_stamp(path) for path in set(assets.values())|set(removed)}
+    token=secrets.token_urlsafe(24)
+    for old,value in list(_PLANS.items()):
+        if value['expires']<time.time():_PLANS.pop(old,None)
+    while len(_PLANS)>=8:_PLANS.pop(next(iter(_PLANS)))
+    result={'plan_id':token,'views':[{'storage_id':v['storage_id'],'label':v['label']} for v in selected],
+            'index_bytes':sum(os.path.getsize(p) for p in removed),'unused_vectors':len(keys),
+            'vector_bytes':vector_bytes,'note':note,'expires_in_s':900,'source_files_untouched':True}
+    _PLANS[token]={'project_id':project['id'],'expires':time.time()+900,'paths':removed,'signatures':signature,
+                   'keys':keys,'storage_ids':storage_ids,'clear_cache':clear_cache,'result':result}
+    return result
+
+
+def commit(project,plan_id):
+    plan=_PLANS.pop(plan_id,None)
+    if not plan or plan['project_id']!=project['id'] or plan['expires']<time.time():
+        raise ValueError('Preview expired or invalid. Generate a new cleanup preview.')
+    # Atualiza a identidade antes de conferir proteções: um checkout recente não
+    # pode usar a visão anterior mantida pelo cache de descoberta durante 1 s.
+    view=index_views.describe(project['root'],fresh=True)
+    current={v['storage_id']:v for v in inventory(project)['views']}
+    index_views.assert_current(view)
+    for key in plan['storage_ids']:
+        if key not in current or current[key]['protected']:raise ValueError('View protection changed. Generate another preview.')
+    assets=_assets(project['root'])
+    if set(assets.values())!=set(p for p in plan['signatures'] if p.endswith('.sqlite3')):
+        raise ValueError('The set of indexes changed. Generate another preview.')
+    if any(not os.path.exists(path) or _stamp(path)!=stamp for path,stamp in plan['signatures'].items()):
+        raise ValueError('An index changed since the preview. Generate another preview.')
+    moved=[];warnings=[]
+    try:
+        for source in plan['paths']:
+            index_views.assert_current(view)
+            safe=project_identity.state_path(source,indexer.INDEX_DIR)
+            target=project_identity.state_path(source+'.cleanup-'+secrets.token_hex(6),indexer.INDEX_DIR)
+            os.replace(safe,target);moved.append((safe,target))
+        index_views.assert_current(view)
+    except (OSError,index_views.ViewChanged) as exc:
+        for source,target in reversed(moved):os.replace(target,source)
+        if isinstance(exc,index_views.ViewChanged):raise
+        raise RuntimeError('An index is open in another process. Close the external reader and generate a new preview.') from exc
+    cache=Path(indexer.INDEX_DIR)/(project_identity.project_id(project['root'])+'.vectors.sqlite3')
+    deleted_vectors=0
+    if plan['keys'] and cache.exists():
+        try:
+            with contextlib.closing(sqlite3.connect(cache,timeout=5)) as db:
+                db.execute('PRAGMA secure_delete=ON')
+                with db:db.executemany('DELETE FROM vectors WHERE key=?',[(key,) for key in plan['keys']])
+                deleted_vectors=len(plan['keys'])
+                try:db.execute('VACUUM')
+                except sqlite3.Error:warnings.append('Vectors removed; SQLite could not compact the cache right now.')
+        except sqlite3.Error:warnings.append('The views were removed; the cache in use by another process was kept.')
+    for _,path in moved:os.remove(project_identity.state_path(path,indexer.INDEX_DIR))
+    indexer.invalidate_cache(project['root'])
+    with code_graph._LOCK:
+        for key in list(code_graph._CACHE):
+            if key[0] in plan['paths']:code_graph._CACHE.pop(key,None)
+    return {'removed_views':len(plan['storage_ids']),'removed_index_bytes':plan['result']['index_bytes'],
+            'removed_vectors':deleted_vectors,'warnings':warnings,'source_files_untouched':True,
+            'storage':inventory(project_store.get(project['id']))}