@stacksjs/defaults 0.75.361 → 0.75.366

package/ai/skills/stacks-technical-diagrams/explainer/diff.mjs

@@ -0,0 +1,124 @@
+import { containsExplainerSecret } from './sources.mjs';
+
+const EXAMPLE = '@@ -1,2 +1,2 @@\n unchanged\n-old value\n+new value';
+
+function sourceLines(text) {
+  const result=[];
+  for (const match of text.matchAll(/([^\n]*)(\n|$)/gu)) {
+    if (!match[0]) continue;
+    const crlf=match[2] && match[1].endsWith('\r');
+    result.push({raw:crlf?match[1].slice(0,-1):match[1],ending:crlf?'\r\n':match[2]});
+  }
+  return result;
+}
+
+function fileName(value) {
+  let name=value.split('\t')[0];
+  if (name.startsWith('"') && name.endsWith('"')) {
+    try { name=JSON.parse(name); } catch { name=name.slice(1,-1); }
+  }
+  if (name==='/dev/null') return null;
+  return name.replace(/^[ab]\//u,'');
+}
+
+/** Parse unified diff without rewriting its literal bytes. Fragment line numbers stay null.
+ * File paths identify credential syntax only; this parser performs no filesystem reads.
+ */
+export function parseExplainerDiff(text, {line=1,component='diff',input,panelId,path} = {}) {
+  if (typeof text!=='string') throw new TypeError('Diff input must be a string');
+  const rows=[],diagnostics=[],counts={added:0,removed:0,context:0,hunks:0,files:0};
+  let hunk=null,oldPath=null,newPath=null,fileIndex=-1,oldHeader=false,newHeader=false,oldHeaderLine=line,lastBody=null,markerFor=null;
+  let format='fragment';
+  const groups=new Map();
+  function fail(code,sourceLine,reason,example=EXAMPLE) {
+    diagnostics.push({code:`explainer/diff-${code}`,severity:'error',message:reason,
+      subject:{line:sourceLine,column:1,component,...(input?{input}:{}),...(panelId?{panelId}:{}),...(path?{path}:{})},
+      evidence:{reason,example},supportedFixes:[`Use a valid unified diff, for example:\n${example}`]});
+  }
+  function finishHunk() {
+    if (!hunk) return;
+    if (hunk.usedOld!==hunk.oldCount || hunk.usedNew!==hunk.newCount) fail('hunk-count',hunk.sourceLine,
+      `Hunk declares ${hunk.oldCount} old and ${hunk.newCount} new lines, but contains ${hunk.usedOld} old and ${hunk.usedNew} new lines.`);
+    hunk=null;
+  }
+  function startFile() {
+    if(oldHeader&&!newHeader)fail('header-order',oldHeaderLine,'An old-file header needs its matching new-file header.','--- a/file.txt\n+++ b/file.txt\n'+EXAMPLE);
+    finishHunk();fileIndex++;counts.files++;oldPath=null;newPath=null;oldHeader=false;newHeader=false;lastBody=null;markerFor=null;format='unified';
+  }
+  function row(kind,value,index,extra={}) {
+    const entry={kind,raw:value.raw,text:value.raw,ending:value.ending,sourceLine:line+index,oldLine:null,newLine:null,...extra};
+    const knownPath=kind==='removed' ? oldPath||newPath : newPath||oldPath;
+    if (knownPath) entry.filePath=knownPath;
+    if (kind==='header'||kind==='hunk') {lastBody=null;markerFor=null;}
+    rows.push(entry);return entry;
+  }
+  const values=sourceLines(text);
+  for (const [index,value] of values.entries()) {
+    const raw=value.raw,sourceLine=line+index;
+    if (/^(?:diff --(?:cc|combined)\b|@@@)/u.test(raw)) {finishHunk();fail('combined',sourceLine,'Combined merge diffs are unsupported. Provide a two-way unified diff.');row('header',value,index);continue;}
+    if (/^(?:GIT binary patch|Binary files .+ differ|literal \d+$|delta \d+$)/u.test(raw)) {finishHunk();fail('binary',sourceLine,'Binary patches are unsupported. Describe the binary change separately.');row('header',value,index);continue;}
+    if (raw.startsWith('diff --git ')) {
+      if(!/^diff --git .+ .+$/u.test(raw))fail('header',sourceLine,'A git diff header must identify old and new paths.','diff --git a/file.txt b/file.txt\n--- a/file.txt\n+++ b/file.txt\n'+EXAMPLE);
+      startFile();row('header',value,index);continue;
+    }
+    if (raw.startsWith('@@')) {
+      finishHunk();format='unified';
+      const match=raw.match(/^@@ -(\d+)(?:,(\d+))? \+(\d+)(?:,(\d+))? @@(?:[ \t].*)?$/u);
+      if (!match) {fail('hunk-header',sourceLine,'A hunk header requires old and new start/count ranges.');row('hunk',value,index);continue;}
+      const [oldStart,oldCount,newStart,newCount]=[match[1],match[2]??'1',match[3],match[4]??'1'].map(Number);
+      const valid=[oldStart,oldCount,newStart,newCount].every(Number.isSafeInteger)
+        && Number.isSafeInteger(oldStart+oldCount)&&Number.isSafeInteger(newStart+newCount)
+        && (oldCount===0||oldStart>=1)&&(newCount===0||newStart>=1);
+      if(!valid){fail('hunk-range',sourceLine,'Hunk ranges must use safe nonnegative integers; a nonempty range starts at line 1 or later.');row('hunk',value,index);continue;}
+      counts.hunks++;hunk={oldStart,oldCount,newStart,newCount,usedOld:0,usedNew:0,sourceLine};lastBody=null;markerFor=null;
+      row('hunk',value,index,{oldStart,oldCount,newStart,newCount});continue;
+    }
+    // Once the declared hunk is complete, a file header belongs to the next file.
+    // Within an unfinished hunk, +++/--- remain ordinary additions/removals.
+    const within=hunk&&(hunk.usedOld<hunk.oldCount||hunk.usedNew<hunk.newCount);
+    if(!within && /^--- /u.test(raw)) {
+      finishHunk();if(oldHeader&&newHeader)startFile();else if(fileIndex<0)startFile();
+      oldPath=fileName(raw.slice(4));oldHeader=true;oldHeaderLine=sourceLine;newHeader=false;row('header',value,index);continue;
+    }
+    if(!within && /^\+\+\+ /u.test(raw)) {
+      finishHunk();format='unified';if(!oldHeader)fail('header-order',sourceLine,'A new-file header needs its preceding old-file header.','--- a/file.txt\n+++ b/file.txt\n'+EXAMPLE);
+      newPath=fileName(raw.slice(4));newHeader=true;row('header',value,index);continue;
+    }
+    if (/^(?:index |(?:new file|deleted file|old|new) mode |(?:similarity|dissimilarity) index |(?:rename|copy) (?:from|to) )/u.test(raw)) {
+      finishHunk();format='unified';
+      const valid=/^index [a-fA-F0-9]{1,64}\.\.[a-fA-F0-9]{1,64}(?: [0-7]{6})?$/u.test(raw)
+        ||/^(?:new file|deleted file|old|new) mode [0-7]{6}$/u.test(raw)
+        ||/^(?:rename|copy) (?:from|to) .+$/u.test(raw)
+        ||(/^(?:similarity|dissimilarity) index (\d+)%$/u.test(raw)&&Number(raw.match(/(\d+)%$/u)[1])<=100);
+      if(!valid)fail('header',sourceLine,'This git metadata header is malformed.','diff --git a/file.txt b/file.txt\nindex 1234567..abcdef0 100644\n--- a/file.txt\n+++ b/file.txt\n'+EXAMPLE);
+      row('header',value,index);lastBody=null;markerFor=null;continue;
+    }
+    if(raw==='\') {
+      if(!lastBody||markerFor===lastBody)fail('newline-marker',sourceLine,'A no-newline marker must immediately follow one content row and cannot repeat for that row.','@@ -1 +1 @@\n-old\n\\n+new\n\');
+      row('no-newline',value,index,{...(lastBody?{forLine:lastBody.sourceLine}:{})});markerFor=lastBody;continue;
+    }
+    const kind=raw.startsWith('+')?'added':raw.startsWith('-')?'removed':raw.startsWith(' ')?'context':null;
+    if(!kind) {fail('row',sourceLine,'Diff content rows must start with a space, + or -.');row('header',value,index);lastBody=null;markerFor=null;continue;}
+    const entry=row(kind,value,index,{text:raw.slice(1)});counts[kind]++;
+    if(hunk) {
+      if(kind!=='added')entry.oldLine=hunk.oldStart+hunk.usedOld++;
+      if(kind!=='removed')entry.newLine=hunk.newStart+hunk.usedNew++;
+    }
+    lastBody=entry;markerFor=null;
+    if(!groups.has(fileIndex))groups.set(fileIndex,[]);groups.get(fileIndex).push(entry);
+  }
+  finishHunk();
+  if(oldHeader&&!newHeader)fail('header-order',rows.at(-1)?.sourceLine||line,'An old-file header needs its matching new-file header.','--- a/file.txt\n+++ b/file.txt\n'+EXAMPLE);
+  if(!rows.length)fail('empty',line,'A diff must contain content or a standard git metadata change.');
+  // Scan the whole authored content and pinpoint a matching row when possible.
+  // The shared scanner owns credential rules; diagnostics never quote rejected bytes.
+  for(const group of groups.values()) {
+    const knownPaths=[...new Set(group.map(entry=>entry.filePath).filter(Boolean))];
+    const combined=group.map(entry=>entry.text).join('\n');
+    if((knownPaths.length?knownPaths:[undefined]).some(knownPath=>containsExplainerSecret(combined,knownPath))) {
+      const matched=group.find(entry=>containsExplainerSecret(entry.text,entry.filePath));
+      fail('secret',matched?.sourceLine||group[0].sourceLine,'The diff contains a credential or sensitive secret value. Remove or redact it before rendering.','-const timeout = 100;\n+const timeout = 200;');
+    }
+  }
+  return {rows,counts,diagnostics,format};
+}

package/ai/skills/stacks-technical-diagrams/explainer/inline.mjs

@@ -0,0 +1,155 @@
+/** The explainer's deliberately small inline language; never an HTML escape hatch. */
+export const escapeHtml = value => String(value ?? '').replace(/[&<>"']/g, c => ({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
+
+const identifier = /^[\p{L}\p{N}_-]+$/u;
+const targetIdentifier = /^[\p{L}\p{N}_.:-]+$/u;
+
+function referenceFor(href) {
+  if (/^https?:\/\//i.test(href)) {
+    try {
+      const url = new URL(href);
+      if (url.username || url.password || /[\u0000-\u0020\u007f]/u.test(href)) return null;
+      return {kind:'web',url:href};
+    } catch { return null; }
+  }
+  if (href.startsWith('source:') && identifier.test(href.slice(7))) return {kind:'source',id:href.slice(7)};
+  if (href.startsWith('block:') && identifier.test(href.slice(6))) return {kind:'block',id:href.slice(6)};
+  if (href.startsWith('#') && identifier.test(href.slice(1))) return {kind:'block',id:href.slice(1)};
+  if (href.startsWith('typical:') && href.slice(8).trim()) return {kind:'typical',text:href.slice(8).trim()};
+  if (href.startsWith('node:') || href.startsWith('route:')) {
+    const kind = href.startsWith('node:') ? 'node' : 'route';
+    const value = href.slice(kind.length + 1);
+    const split = value.indexOf('.');
+    if (split < 1 || !identifier.test(value.slice(0,split))) return null;
+    const diagram = value.slice(0,split), target = value.slice(split+1);
+    if (kind === 'node' && targetIdentifier.test(target)) return {kind,diagram,node:target};
+    const route = target.split('~');
+    if (kind === 'route' && route.length === 2 && route.every(id => targetIdentifier.test(id))) return {kind,diagram,from:route[0],to:route[1]};
+  }
+  return null;
+}
+
+/** Returns tokens and references, with offsets for validation and actionable diagnostics. */
+export function parseInline(value, options = {}) {
+  const text = String(value ?? '');
+  const references = [], diagnostics = [];
+  function problem(code, index, reason, example) {
+    const before = text.slice(0,index), lastBreak = before.lastIndexOf('\n');
+    diagnostics.push({code:`explainer/inline-${code}`,severity:'error',message:reason,
+      subject:{line:(Number.isInteger(options.line) ? options.line : 1) + (before.match(/\n/g)?.length || 0),column:index-lastBreak,
+        component:options.component || 'inline',...(options.panelId ? {panelId:options.panelId} : {}),...(options.input ? {input:options.input} : {})},
+      evidence:{reason,example},supportedFixes:[`Use the supported form: ${example}`]});
+  }
+  function segment(start, end, depth = 0) {
+    const tokens = [];
+    const literal = value => {
+      if (!value) return;
+      const previous = tokens[tokens.length-1];
+      if (previous?.type === 'text') previous.value += value;
+      else tokens.push({type:'text',value});
+    };
+    for (let i=start;i<end;) {
+      const c=text[i];
+      if (c === '\\' && i+1 < end && /[\\`*_[\]()!<>~|]/u.test(text[i+1])) { literal(text[i+1]);i+=2;continue; }
+      if (c === '`') {
+        const close=text.indexOf('`',i+1);
+        if (close === -1 || close >= end || text.slice(i+1,close).includes('\n')) {
+          problem('code',i,'Inline code must have one closing backtick on the same line.','`cache.get(key)`');literal(c);i++;continue;
+        }
+        tokens.push({type:'code',value:text.slice(i+1,close)});i=close+1;continue;
+      }
+      if (c === '<' && /^(?:<\/?[A-Za-z][^>]*>|<!--)/u.test(text.slice(i,end))) {
+        problem('html',i,'Raw HTML is not part of the explainer inline language.','**Important** or `[literal <tag>]`');
+        literal(c);i++;continue;
+      }
+      if (text.startsWith('![',i)) {
+        problem('image',i,'Inline Markdown images are unsupported. Use a contained image block.','@image path=diagram.png alt="Request path"');
+        literal('!');i++;continue;
+      }
+      if (text.startsWith('~~',i)) { problem('decoration',i,'Strikethrough is unsupported; use a diff or an explicit change block.','Changed: **new behavior**');literal('~~');i+=2;continue; }
+      if (c === '*') {
+        const marker=text.startsWith('**',i) ? '**' : '*';
+        let close=text.indexOf(marker,i+marker.length);
+        const escaped = index => {
+          let slashes=0;
+          while (index > start && text[--index] === '\\') slashes++;
+          return slashes % 2 === 1;
+        };
+        while (close > -1 && escaped(close)) close=text.indexOf(marker,close+marker.length);
+        if (close < 0 || close >= end || close === i+marker.length || depth >= 6) {
+          problem('emphasis',i,'Emphasis needs matching nonempty delimiters. Escape a literal asterisk.','**important** or \\*');literal(marker);i+=marker.length;continue;
+        }
+        tokens.push({type:marker.length===2?'strong':'em',children:segment(i+marker.length,close,depth+1)});i=close+marker.length;continue;
+      }
+      if (c === '[') {
+        const labelEnd=text.indexOf(']',i+1);
+        if (labelEnd > -1 && labelEnd < end && text[labelEnd+1] === '(') {
+          let close=labelEnd+2, nesting=1;
+          for (;close<end;close++) {
+            if (text[close] === '\\') { close++;continue; }
+            if (text[close] === '(') nesting++;
+            if (text[close] === ')' && --nesting === 0) break;
+          }
+          if (close >= end || nesting !== 0) {
+            problem('link',i,'The link destination is not closed.','[Evidence](source:cache-read)');literal(c);i++;continue;
+          }
+          const label=text.slice(i+1,labelEnd), href=text.slice(labelEnd+2,close).replace(/\\([()\\])/g,'$1');
+          const reference=referenceFor(href);
+          if ((!label.trim() && reference?.kind !== 'source') || !reference) {
+            problem('target',i,'Use a nonempty label and an HTTP(S), source, block, node, route or typical destination.','[Redis](node:read-path.redis)');
+            literal(text.slice(i,close+1));
+          } else {
+            const entry={...reference,offset:i,end:close+1};references.push(entry);
+            tokens.push({type:'link',label,href,reference:entry});
+          }
+          i=close+1;continue;
+        }
+        if (text[i+1] === '^') problem('footnote',i,'Arbitrary Markdown footnotes are unsupported. Use a source or typical-value reference.','[Claim](source:trace)');
+      }
+      literal(c);i++;
+    }
+    return tokens;
+  }
+  const tokens=segment(0,text.length);
+  return {tokens,references,diagnostics};
+}
+
+function inlineError(diagnostics) {
+  const error=new Error(diagnostics[0].message);
+  error.archifyDiagnostics=diagnostics;
+  error.diagnostics=diagnostics;
+  return error;
+}
+
+/** Safely render the same parsed language used by semantic validation. */
+export function renderInline(value, context = {}) {
+  const parsed=parseInline(value,context);
+  if (parsed.diagnostics.length) throw inlineError(parsed.diagnostics);
+  const render = tokens => tokens.map(token => {
+    if (token.type === 'text') return escapeHtml(token.value);
+    if (token.type === 'code') return `<code>${escapeHtml(token.value)}</code>`;
+    if (token.type === 'strong' || token.type === 'em') return `<${token.type}>${render(token.children)}</${token.type}>`;
+    const label=escapeHtml(token.label), ref=token.reference;
+    if (ref.kind === 'web') return `<a href="${escapeHtml(ref.url)}" target="_blank" rel="noopener noreferrer">${label}</a>`;
+    if (ref.kind === 'source') {
+      const citations = context.citations || (context.citations = new Map());
+      if (!citations.has(ref.id)) citations.set(ref.id,citations.size + 1);
+      return `${label}<sup class="cite"><a href="#source-${escapeHtml(ref.id)}">${citations.get(ref.id)}</a></sup>`;
+    }
+    if (ref.kind === 'block') return `<a href="#${escapeHtml(ref.id)}" data-block-ref="${escapeHtml(ref.id)}">${label}</a>`;
+    if (ref.kind === 'node' || ref.kind === 'route') {
+      const hash=ref.kind==='node' ? `focus=${encodeURIComponent(ref.node)}` : `route=${encodeURIComponent(ref.from)}~${encodeURIComponent(ref.to)}`;
+      return `<a class="diagram-link" href="#${escapeHtml(ref.diagram)}" data-diagram-link="${escapeHtml(ref.diagram)}" data-diagram-hash="${escapeHtml(hash)}">${label}</a>`;
+    }
+    if (ref.kind === 'typical') {
+      if (Array.isArray(context.footnotes)) {
+        const index=context.footnotes.length+1,id=`explainer-typical-${index}`;
+        context.footnotes.push({id,index,text:ref.text,label:token.label});
+        return `<span class="typical" title="${escapeHtml(ref.text)}">${label}<sup><a href="#${id}" role="doc-noteref" class="typical-ref">[${index}]</a></sup></span>`;
+      }
+      return `<span class="typical">${label}<small class="typical-note"> (${escapeHtml(ref.text)})</small></span>`;
+    }
+    return label;
+  }).join('');
+  return render(parsed.tokens);
+}

package/ai/skills/stacks-technical-diagrams/explainer/layout.mjs

@@ -0,0 +1,35 @@
+/** Order-preserving twelve-column packing. Explicit spans never change.
+ * A panel may shrink from its preferred width to its minimum to finish the current row,
+ * so a wide panel does not strand the conclusion on a row of its own.
+ */
+export function layoutExplainerPanels(document, diagrams = {}) {
+  const contentSize = value => typeof value === 'string' ? Array.from(value).length : Array.isArray(value) ? value.reduce((n,v)=>n+contentSize(v),0) : value && typeof value === 'object' ? Object.entries(value).filter(([key])=>!['id','type','span','target','source','diagramType','path','url','revision'].includes(key)).reduce((n,[,v])=>n+contentSize(v),0) : 0;
+  const widths = block => {
+    if (block.type === 'comparison') return block.columns.length + 1 > 3 ? [8,7] : [7,6];
+    if (['code','diff'].includes(block.type)) return [8,7];
+    if (block.type === 'chart') return [6,5];
+    if (block.type === 'snippet') { const longest = Math.max(...block.text.split('\n').map(line => line.length)); return longest > 72 ? [8,7] : longest > 48 ? [6,6] : [5,4]; }
+    if (block.type === 'diagram') {
+      const diagram=diagrams[block.id], viewBox=diagram?.svg?.match(/viewBox=["']([^"']+)["']/)?.[1].split(/[ ,]+/).map(Number);
+      return (viewBox?.[2] || diagram?.spec?.meta?.canvas?.width || 0) > 1000 ? [12,12] : [8,8];
+    }
+    return [4,4];
+  };
+  const sized = panel => panel.blocks.map(widths).reduce((best,next)=>next[0]>best[0]?next:best,[4,4]);
+  const items=[{id:'answer',span:5,min:4,weight:contentSize(document.answer),answer:true},...document.panels.map(panel=>{const [span,min]=sized(panel);return{id:panel.id,span:panel.span ?? span,min:panel.span ?? min,explicit:panel.span!==undefined,weight:contentSize(panel),panel};})];
+  const rows=[];let row=[],used=0;
+  function finish(){if(!row.length)return;const remaining=12-used;const flexible=row.filter(item=>!item.explicit).sort((a,b)=>b.weight-a.weight);if(remaining&&flexible.length)flexible[0].span+=remaining;else if(remaining)row.push({spacer:true,span:remaining});rows.push(row);row=[];used=0;}
+  for(const item of items){
+    if(used+item.span>12){
+      if(row.length&&row.reduce((n,x)=>n+x.min,0)+item.min<=12){
+        let deficit=used+item.span-12;
+        const cut=x=>{const d=Math.min(deficit,x.span-x.min);x.span-=d;deficit-=d;};
+        cut(item);for(const x of [...row].sort((a,b)=>(b.span-b.min)-(a.span-a.min)))cut(x);
+        used=row.reduce((n,x)=>n+x.span,0);
+      } else finish();
+    }
+    row.push(item);used+=item.span;if(used===12)finish();
+  }
+  finish();
+  return rows;
+}

package/ai/skills/stacks-technical-diagrams/explainer/page-bundle.mjs

@@ -0,0 +1,16 @@
+import { gzipSync, gunzipSync } from 'node:zlib';
+
+// The native Viewer HTML is needed only when a reader opens "Explore", so the page stores it
+// gzip-compressed and the reader inflates it on demand. Keys keep their order, so the prepared
+// bundle digest is computed and verified over the same unpacked JSON.
+const swap = (bundle, from, to, convert) => {
+  const diagrams = bundle?.preparedDiagrams?.diagrams;
+  if (!diagrams || typeof diagrams !== 'object') return bundle;
+  return { ...bundle, preparedDiagrams: { ...bundle.preparedDiagrams, diagrams: Object.fromEntries(Object.entries(diagrams).map(([id, child]) =>
+    [id, child && typeof child[from] === 'string' ? Object.fromEntries(Object.entries(child).map(([key, value]) => key === from ? [to, convert(value)] : [key, value])) : child])) } };
+};
+
+export const packPageBundle = bundle => swap(bundle, 'html', 'htmlGzip', html => gzipSync(html, { level: 9 }).toString('base64'));
+
+/** Accepts packed and older unpacked pages alike. */
+export const unpackPageBundle = bundle => swap(bundle, 'htmlGzip', 'html', data => gunzipSync(Buffer.from(data, 'base64')).toString('utf8'));