Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
Keep public explainer diagnostics portable and clarify finalization guarantees
tt-a1icf13329acd5c
diff --git a/archify.zip b/archify.zipindex 4111093b..ac22b7c4 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/explainer/patch.mjs b/archify/explainer/patch.mjsindex 8e432636..5b14ccb0 100644--- a/archify/explainer/patch.mjs+++ b/archify/explainer/patch.mjs@@ -69,7 +69,7 @@ export async function preparePanelPatch({artifactPath,panelId,replacementPath,re&& !(block.type==='image' && oldBlocks.get(block.id)?.path===block.path && previous.preparedSources?.assets?.[block.id])&& !(block.type==='chart' && block.data && JSON.stringify(oldBlocks.get(block.id)?.data)===JSON.stringify(block.data) && previous.preparedSources?.charts?.[block.id])).map(frozenDiagramInput)}],sources:parsed.document.sources.filter(source=>changedCodeIds.has(source.id))};- const common={repoRoot,baseDir:near(previous.baseDir) || path.dirname(draft.sourcePath || artifactPath),sourceMap:parsed.sourceMap,sourcePath:draft.sourcePath || artifactPath,quality:selectedQuality};+ const common={repoRoot,baseDir:previous.baseDir===null ? null : near(previous.baseDir) || path.dirname(draft.sourcePath || artifactPath),sourceMap:parsed.sourceMap,sourcePath:draft.sourcePath || artifactPath,quality:selectedQuality};const partialMap={...parsed.sourceMap};for(const [partialIndex,block] of partial.panels[0].blocks.entries()) {const originalIndex=parsed.document.panels[index].blocks.findIndex(entry=>entry.id===block.id);@@ -107,7 +107,7 @@ export async function preparePanelPatch({artifactPath,panelId,replacementPath,reconst dependencyKey=entry=>`${entry.kind}:${entry.id}`;const newDependencies=[...(newSources.dependencies||[]),...(newDiagrams.dependencies||[])];const preparedIds=new Set(newDependencies.map(dependencyKey));- const localDependency=(entry,baseDir)=>({...entry,...(entry.kind==='repository'||entry.inline?{}:{path:path.resolve(baseDir,entry.path)})});+ const localDependency=(entry,baseDir)=>({...entry,...(entry.kind==='repository'||entry.inline||!entry.path?{}:{path:path.resolve(baseDir,entry.path)})});const dependencies=[...(previous.dependencies||[]).filter(entry=>!preparedIds.has(dependencyKey(entry)) && (entry.kind!=='image'||imageIds.has(entry.id)) && (entry.kind!=='data'||dataChartIds.has(entry.id)) && (entry.kind!=='diagram-spec'||diagramIds.has(entry.id))).map(entry=>localDependency(entry,path.dirname(artifactPath))),...newDependencies.map(entry=>localDependency(entry,common.baseDir))];// Old dependencies are embedded immutable bytes. Only newly prepared resources are reread/verified.diff --git a/archify/explainer/render.mjs b/archify/explainer/render.mjsindex c3c6fab4..ba0f825f 100644--- a/archify/explainer/render.mjs+++ b/archify/explainer/render.mjs@@ -122,6 +122,7 @@ export function renderExplainer(document, options = {}) {if (!preparedBundle) bundle.digest = hash(JSON.stringify(bundle));if (bundle.sourceText !== sourceText || JSON.stringify(bundle.document) !== JSON.stringify(document)) throw new Error('Prepared bundle differs from rendered source or canonical document.');const page = portableBundle(bundle, pageDirectory || bundle.baseDir || (bundle.sourcePath && path.dirname(bundle.sourcePath)));+ manifest.diagnostics = page.diagnostics;manifest.dependencies = (page.dependencies || []).map(({contentBase64,...entry})=>entry);return `<!doctype html>\n<html lang="${escape(locale)}" data-style="${escape(document.meta.style || 'clean')}" data-archify-artifact="explainer" data-artifact="${escape(document.meta.id)}" data-revision="${revision}"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><meta name="color-scheme" content="light dark"><meta name="description" content="${escape(document.answer.summary)}"><title>${escape(document.meta.title)} · Archify</title><link rel="icon" type="image/svg+xml" href="${favicon}"><style>${css}</style></head><body><a class="skip-link" href="#board">${english?'Skip to content':'跳至正文'}</a><div class="shell"><header class="masthead"><h1>${escape(document.meta.title)}</h1><div class="tools interactive"><div class="theme-controls" role="group" aria-label="${english?'Theme':'主题'}">${['auto','light','dark'].map(theme=>`<button type="button" data-theme-choice="${theme}" aria-pressed="${theme === 'auto'}">${words[theme]}</button>`).join('')}</div><div class="tool-menu style-menu"><button type="button" class="tool-button" data-style-toggle aria-haspopup="menu" aria-expanded="false" aria-label="${words.style}"><span class="style-swatch" data-swatch="${escape(document.meta.style || 'clean')}"></span><span data-style-label>${words.styles[document.meta.style || 'clean']}</span>${icons.chevron}</button><div class="menu-options style-options" role="menu" aria-label="${words.style}" hidden>${['clean','editorial','product','swiss'].map(style=>`<button type="button" role="menuitemradio" aria-checked="${style === (document.meta.style || 'clean')}" data-style-choice="${style}" tabindex="-1"><span class="style-swatch" data-swatch="${style}"></span><span>${words.styles[style]}</span>${icons.check}</button>`).join('')}</div></div><div class="tool-menu export-menu"><button type="button" class="tool-button" data-export-toggle aria-haspopup="menu" aria-expanded="false">${icons.export}<span>${words.export}</span>${icons.chevron}</button><div class="menu-options" role="menu" aria-label="${words.export}" hidden><p class="menu-label" role="presentation">${words.image}</p>${[['png','PNG'],['webp','WebP'],['jpeg','JPG']].map(([format,label],index)=>`<button type="button" role="menuitem" tabindex="-1" data-export-image="${format}" aria-label="${words.image} ${label}">${icons.image}<span>${label}</span><small>${words.imageHints[index]}</small></button>`).join('')}<hr role="separator"><button type="button" role="menuitem" tabindex="-1" data-print>${icons.print}<span>${words.print}</span></button></div></div></div></header><main id="board"><div class="board">${panels}</div></main><footer>${footnotesHtml}<section class="sources"><h2>${words.sources}</h2><ol>${sourceList}</ol></section>${colophon}</footer></div><dialog class="viewer-dialog" id="diagram-dialog" aria-labelledby="diagram-dialog-title"><header><h2 id="diagram-dialog-title"></h2><button type="button" class="viewer-close" data-close-diagram>${icons.close}<span>${words.close}</span><kbd>Esc</kbd></button></header><p class="dialog-loading" role="status">${words.loading}</p></dialog><div id="toast" role="status" aria-live="polite"></div><script type="application/json" id="archify-explainer-prepared">${json(packPageBundle(page))}</script><script type="application/json" id="explainer-manifest">${json(manifest)}</script><script type="application/json" id="explainer-reader-words">${json(words)}</script><script>${js}</script></body></html>`;}@@ -137,7 +138,15 @@ function portableChecks(checks) {// path: the reader sees no author directories. `patch explainer` resolves them against the page again.function portableBundle(bundle, directory) {if (!directory) return bundle;- const local = value => typeof value === 'string' && path.isAbsolute(value) ? path.relative(directory, value) || '.' : value;+ const local = value => {+ if (typeof value !== 'string') return value;+ const paths = path.win32.isAbsolute(value) && !path.posix.isAbsolute(value) ? path.win32 : path;+ if (!paths.isAbsolute(value)) return value;+ const relative = paths.relative(directory, value);+ // Different Windows volumes have no relative path. Frozen content stays usable;+ // a missing origin must not be mistaken for the output directory during patching.+ return paths.isAbsolute(relative) ? null : relative || '.';+ };const subject = entry => entry?.subject ? {...entry,subject:{...entry.subject,...('input' in entry.subject ? {input:local(entry.subject.input)} : {}),...('output' in entry.subject ? {output:local(entry.subject.output)} : {})}} : entry;const page = {...bundle,sourcePath:local(bundle.sourcePath),...('inputPath' in bundle ? {inputPath:local(bundle.inputPath)} : {}),...('baseDir' in bundle ? {baseDir:local(bundle.baseDir)} : {}),preparedDiagrams:{...bundle.preparedDiagrams,diagrams:Object.fromEntries(Object.entries(bundle.preparedDiagrams?.diagrams || {}).map(([id,diagram])=>[id,{...diagram,checks:portableChecks(diagram.checks)}]))},diff --git a/test/explainer-patch.test.mjs b/test/explainer-patch.test.mjsindex a45f8143..dd739810 100644--- a/test/explainer-patch.test.mjs+++ b/test/explainer-patch.test.mjs@@ -5,7 +5,9 @@ import os from 'node:os';import path from 'node:path';import { spawnSync } from 'node:child_process';import { scanHtml } from '../archify/explainer/check.mjs';-import { unpackPageBundle } from '../archify/explainer/page-bundle.mjs';+import { createHash } from 'node:crypto';+import { preparePanelPatch } from '../archify/explainer/patch.mjs';+import { packPageBundle, unpackPageBundle } from '../archify/explainer/page-bundle.mjs';import { compileExplainerDiagram } from '../archify/explainer/diagrams.mjs';const cli=path.resolve('archify/bin/archify.mjs');const run=args=>spawnSync(process.execPath,[cli,...args],{encoding:'utf8',maxBuffer:64*1024*1024,env:{...process.env,ARCHIFY_UPDATE_CHECK_DISABLED:'1'}});@@ -117,3 +119,16 @@ test('panel patch across directories retains resource origins for subsequent edi}const checked=run(['check',output,'--json','--require-provenance']);assert.equal(checked.status,0,checked.stdout+checked.stderr);});+++test('a page without its source directory can patch prose but cannot read unrelated output-local assets',async t=>{+ const dir=temp(t),{artifact}=deliver(dir),bundle=read(artifact),replacementPath=path.join(dir,'replacement.json');+ bundle.sourcePath=null;bundle.baseDir=null;+ bundle.digest=createHash('sha256').update(JSON.stringify({...bundle,digest:undefined})).digest('hex');+ fs.writeFileSync(artifact,fs.readFileSync(artifact,'utf8').replace(/(<script type="application\/json" id="archify-explainer-prepared">)[\s\S]*?(<\/script>)/,(_,open,close)=>open+JSON.stringify(packPageBundle(bundle))+close));+ const panel={...fixture().panels[0],title:'Updated prose'};fs.writeFileSync(replacementPath,JSON.stringify(panel));+ const result=await preparePanelPatch({artifactPath:artifact,panelId:'first',replacementPath});assert.equal(result.bundle.baseDir,null);+ fs.writeFileSync(path.join(dir,'asset.png'),'An unrelated file beside the HTML');+ panel.blocks.push({id:'new-image',type:'image',path:'asset.png',alt:'New image'});fs.writeFileSync(replacementPath,JSON.stringify(panel));+ await assert.rejects(preparePanelPatch({artifactPath:artifact,panelId:'first',replacementPath}),{message:'Local images require an input directory.'});+});diff --git a/test/explainer-renderer.test.mjs b/test/explainer-renderer.test.mjsindex 869e7275..5080b389 100644--- a/test/explainer-renderer.test.mjs+++ b/test/explainer-renderer.test.mjs@@ -212,3 +212,20 @@ test('renderer: shared pages omit disposable native checker filenames but retain}assert.equal(prepared.preparedDiagrams.diagrams['native-diagram'].checks.check.file,check.file);});+++test('renderer: manifest warnings use the same portable locations as the prepared bundle',()=>{+ const diagnostics=[{code:'writing/test',severity:'warning',subject:{input:'/author/draft.md',output:'/published/page.html'}}];+ const tree=parse(renderExplainer(fixture(),{...resources(),diagnostics,sourcePath:'/author/draft.md',pageDirectory:'/published'}));+ const frozen=payload(tree,'archify-explainer-prepared'),manifest=JSON.parse(text(find(tree,'explainer-manifest')));+ assert.deepEqual(manifest.diagnostics,frozen.diagnostics);assert.equal(manifest.diagnostics[0].subject.input.replaceAll('\\','/'),'../author/draft.md');+});++test('renderer: Windows cross-volume source locations are omitted instead of exposed',()=>{+ const diagnostics=[{code:'writing/test',severity:'warning',subject:{input:'D:\\author\\draft.md'}}];+ const document=fixture(),sourceText=JSON.stringify(document),prepared=resources();+ const preparedBundle={...prepared,document,sourceText,diagnostics,sourcePath:'D:\\author\\draft.md',baseDir:'D:\\author',dependencies:[{kind:'image',id:'image',path:'D:\\author\\example.png'}]};+ const tree=parse(renderExplainer(document,{...prepared,sourceText,preparedBundle,diagnostics,pageDirectory:'C:\\published'}));+ const frozen=payload(tree,'archify-explainer-prepared'),manifest=JSON.parse(text(find(tree,'explainer-manifest')));+ assert.equal(frozen.sourcePath,null);assert.equal(frozen.baseDir,null);assert.equal(frozen.dependencies[0].path,null);assert.equal(manifest.diagnostics[0].subject.input,null);+});diff --git a/website/src/data/site-translations.mjs b/website/src/data/site-translations.mjsindex df3eaa8b..a15b4e16 100644--- a/website/src/data/site-translations.mjs+++ b/website/src/data/site-translations.mjs@@ -86,11 +86,11 @@ export const indexCopy = {'f13-h':'See what changed','f13-p':"<code>archify compare</code> draws an architecture's before and after as one delta diagram — added, removed and rerouted relationships — with a machine-readable receipt.",'label-trust':'Verified delivery','trust-h2':'Checked before <em>it reaches you.</em>',- 'trust-body':'Your agent does not hand you a draft. Every map and every page goes through four gates, and the file on disk is only replaced when all of them pass.',+ 'trust-body':'Finalization validates and delivers the artifact, then checks the delivered file. Diagrams also run a browser check; one-page answers run it when requested. Later check failures are reported and do not roll back the delivered file.','gate-1-h':'The source means what it says','gate-1-p':'Schema, IDs and references, then the layout itself: crossings, label clearance, corridors and legend room. A blank chart cell is an error, not a zero.',- 'gate-2-h':'Nothing half-written','gate-2-p':'Rendered in a staging copy beside the target and swapped in atomically. If any step fails, the last good file stays where it was.',+ 'gate-2-h':'Nothing half-written','gate-2-p':'Rendered in a staging copy beside the target and swapped in atomically after delivery checks pass. A failed render does not replace the existing file.','gate-3-h':'The file is the one that was checked','gate-3-p':'The delivered HTML is read back and checked again, and the receipt records the hashes of the source and of this exact file.',- 'gate-4-h':'Readable in a real browser','gate-4-p':'Chrome opens it at several desktop sizes: nothing overflows, the smallest text stays readable, and controls stay clear of the drawing.',+ 'gate-4-h':'Readable in a real browser','gate-4-p':'When run, Chrome checks the artifact at several desktop sizes for overflow, text readability and controls. Browser checks are opt-in for one-page answers.','sum-head':'From the receipt','sum-text':'smallest node text 7 px · required 6 px','label-palette':'Design system','palette-h2':'Color that <em>means something.</em>',@@ -206,11 +206,11 @@ export const indexCopy = {'f13-h':'看清改了什么','f13-p':'<code>archify compare</code> 把架构的前后两版画成一张差异图——新增、删除和改道的关系一目了然,并附机器可读的回执。','label-trust':'交付前校验','trust-h2':'交到你手里之前,<br><em>已经检查过了。</em>',- 'trust-body':'Agent 交给你的不是草稿。每张图、每一页都要过四道门,全部通过才会替换磁盘上的文件。',+ 'trust-body':'完成流程先校验并交付,再检查已交付的文件。图表还会执行浏览器检查,一页式解答按需开启。交付后的检查失败会报告,但不会回滚已交付文件。','gate-1-h':'内容说的就是它的意思','gate-1-p':'先查结构、ID 和引用,再查布局本身:连线交叉、标签避让、走线通道和图例空间。图表数据留空会报错,不会画成零。',- 'gate-2-h':'不会留下半成品','gate-2-p':'先在目标旁边的暂存副本里渲染,再原子替换。任何一步失败,上一个好文件原样保留。',+ 'gate-2-h':'不会留下半成品','gate-2-p':'先在目标旁边的暂存副本里渲染,交付检查通过后再原子替换。渲染失败不会覆盖已有文件。','gate-3-h':'交付的就是检查过的那个文件','gate-3-p':'把交付出来的 HTML 读回来再查一遍,回执里记下源文件和这个文件本身的哈希。',- 'gate-4-h':'真浏览器里读得清','gate-4-p':'用 Chrome 在几种桌面尺寸下打开:不溢出,最小的字也读得清,控件不会挡住图。',+ 'gate-4-h':'真浏览器里读得清','gate-4-p':'执行时,Chrome 会在几种桌面尺寸下检查溢出、文字可读性和控件。一页式解答的浏览器检查需要按需开启。','sum-head':'回执摘录','sum-text':'最小节点文字 7 px · 要求 6 px','label-palette':'设计系统','palette-h2':'每种颜色,<br><em>都有含义。</em>',diff --git a/website/src/pages/index.astro b/website/src/pages/index.astroindex ab6ec695..304a7468 100644--- a/website/src/pages/index.astro+++ b/website/src/pages/index.astro@@ -322,14 +322,14 @@ const { lang = 'en' } = Astro.props;<header class="section-head fade-up"><p class="section-label"><span>04</span><span data-i18n="label-trust">Verified delivery</span></p><h2 class="section-heading" data-i18n="trust-h2">Checked before <em>it reaches you.</em></h2>- <p class="section-body" data-i18n="trust-body">Your agent does not hand you a draft. Every map and every page goes through four gates, and the file on disk is only replaced when all of them pass.</p>+ <p class="section-body" data-i18n="trust-body">Finalization validates and delivers the artifact, then checks the delivered file. Diagrams also run a browser check; one-page answers run it when requested. Later check failures are reported and do not roll back the delivered file.</p></header><div class="trust-layout" id="trust-run"><ol class="gates"><li class="gate" style="--d:1.5s"><span class="gate-no">01</span><div><h3><code>validate</code><span data-i18n="gate-1-h">The source means what it says</span></h3><p data-i18n="gate-1-p">Schema, IDs and references, then the layout itself: crossings, label clearance, corridors and legend room. A blank chart cell is an error, not a zero.</p></div><span class="gate-pass">PASS</span></li>- <li class="gate" style="--d:2.3s"><span class="gate-no">02</span><div><h3><code>deliver</code><span data-i18n="gate-2-h">Nothing half-written</span></h3><p data-i18n="gate-2-p">Rendered in a staging copy beside the target and swapped in atomically. If any step fails, the last good file stays where it was.</p></div><span class="gate-pass">PASS</span></li>+ <li class="gate" style="--d:2.3s"><span class="gate-no">02</span><div><h3><code>deliver</code><span data-i18n="gate-2-h">Nothing half-written</span></h3><p data-i18n="gate-2-p">Rendered in a staging copy beside the target and swapped in atomically after delivery checks pass. A failed render does not replace the existing file.</p></div><span class="gate-pass">PASS</span></li><li class="gate" style="--d:2.9s"><span class="gate-no">03</span><div><h3><code>check</code><span data-i18n="gate-3-h">The file is the one that was checked</span></h3><p data-i18n="gate-3-p">The delivered HTML is read back and checked again, and the receipt records the hashes of the source and of this exact file.</p></div><span class="gate-pass">PASS</span></li>- <li class="gate" style="--d:3.6s"><span class="gate-no">04</span><div><h3><code>browser-check</code><span data-i18n="gate-4-h">Readable in a real browser</span></h3><p data-i18n="gate-4-p">Chrome opens it at several desktop sizes: nothing overflows, the smallest text stays readable, and controls stay clear of the drawing.</p></div><span class="gate-pass">PASS</span></li>+ <li class="gate" style="--d:3.6s"><span class="gate-no">04</span><div><h3><code>browser-check</code><span data-i18n="gate-4-h">Readable in a real browser</span></h3><p data-i18n="gate-4-p">When run, Chrome checks the artifact at several desktop sizes for overflow, text readability and controls. Browser checks are opt-in for one-page answers.</p></div><span class="gate-pass">PASS</span></li></ol><figure class="run"><div class="run-bar"><span class="window-dots" aria-hidden="true"><i></i><i></i><i></i></span><span class="run-title">finalize · cache-miss</span></div>