npm - @ijfw/memory-server - Versions diffs - 1.4.3 → 1.5.0 - Mend

@ijfw/memory-server 1.4.3 → 1.5.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (233) hide show

package/src/dashboard-client-waves.html ADDED Viewed

@@ -0,0 +1,304 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>IJFW · Waves</title>
+<style>
+  :root { color-scheme: light dark; }
+  * { box-sizing: border-box; }
+  body { margin: 0; font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif; background: #fafafa; color: #222; }
+  header { padding: 12px 20px; border-bottom: 1px solid #ddd; background: #fff; }
+  header h1 { margin: 0; font-size: 18px; font-weight: 600; }
+  header .sub { color: #777; font-size: 12px; margin-top: 4px; }
+  main { padding: 20px; max-width: 1200px; margin: 0 auto; }
+  .layout { display: grid; grid-template-columns: 320px 1fr; gap: 20px; min-height: 500px; }
+  .sidebar { background: #fff; border: 1px solid #ddd; border-radius: 6px; overflow: hidden; }
+  .sidebar-header { padding: 10px 14px; font-weight: 600; border-bottom: 1px solid #eee; font-size: 13px; color: #555; }
+  .wave-list { max-height: 70vh; overflow-y: auto; }
+  .wave-row { padding: 10px 14px; border-bottom: 1px solid #f0f0f0; cursor: pointer; display: grid; grid-template-columns: 1fr auto; gap: 4px; }
+  .wave-row:hover { background: #f4f8ff; }
+  .wave-row.selected { background: #eaf3ff; }
+  .wave-row .id { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 13px; font-weight: 600; }
+  .wave-row .status { font-size: 11px; padding: 1px 6px; border-radius: 3px; background: #eee; color: #555; text-transform: uppercase; align-self: center; }
+  .wave-row.status-done .status { background: #d6f5d6; color: #1a6b1a; }
+  .wave-row.status-in_progress .status { background: #fff4cc; color: #7a5a00; }
+  .wave-row.status-blocked .status { background: #fbd5d5; color: #8a1a1a; }
+  .wave-row .ts { grid-column: 1 / -1; font-size: 11px; color: #888; }
+  .viewer { background: #fff; padding: 24px 28px; border: 1px solid #ddd; border-radius: 6px; min-height: 500px; }
+  .meta { font-size: 12px; color: #666; margin-bottom: 16px; padding-bottom: 10px; border-bottom: 1px solid #eee; }
+  .meta .meta-row { display: inline-block; margin-right: 16px; }
+  .meta strong { color: #333; }
+  .doc h1 { font-size: 22px; margin: 0 0 12px; }
+  .doc h2 { font-size: 18px; margin: 24px 0 10px; padding-bottom: 4px; border-bottom: 1px solid #eee; }
+  .doc h3 { font-size: 15px; margin: 20px 0 8px; }
+  .doc pre { background: #f4f4f4; padding: 12px; border-radius: 4px; overflow-x: auto; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc code { background: #f4f4f4; padding: 1px 4px; border-radius: 3px; font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: 12px; }
+  .doc pre code { background: transparent; padding: 0; }
+  .doc table { border-collapse: collapse; margin: 12px 0; }
+  .doc th, .doc td { border: 1px solid #ddd; padding: 6px 10px; text-align: left; font-size: 13px; }
+  .doc th { background: #f4f4f4; }
+  .doc blockquote { border-left: 3px solid #ccc; padding-left: 12px; color: #666; margin: 12px 0; }
+  .err { color: #c00; font-style: italic; }
+  .hint { color: #777; font-style: italic; }
+  @media (prefers-color-scheme: dark) {
+    body { background: #1a1a1a; color: #ddd; }
+    header, .sidebar, .viewer { background: #222; border-color: #333; }
+    .sidebar-header, .meta { border-color: #2e2e2e; color: #aaa; }
+    .wave-row { border-color: #2a2a2a; }
+    .wave-row:hover { background: #2a2f3a; }
+    .wave-row.selected { background: #2c3548; }
+    .wave-row .status { background: #333; color: #ccc; }
+    .doc pre, .doc code, .doc th { background: #2a2a2a; }
+  }
+</style>
+</head>
+<body>
+<header>
+  <h1>IJFW · Waves</h1>
+  <div class="sub">Live state of .ijfw/wave-*/STATE.md across the current project.</div>
+</header>
+<main>
+  <div class="layout">
+    <aside class="sidebar">
+      <div class="sidebar-header">Waves (newest first)</div>
+      <div class="wave-list" id="waveList"></div>
+    </aside>
+    <section class="viewer">
+      <div class="meta" id="waveMeta"></div>
+      <div id="doc" class="doc"></div>
+    </section>
+  </div>
+</main>
+<script>
+  // Reused markdown shim from /planning — produces a safe DOMFragment, no innerHTML.
+  // Handles headings, paragraphs, code blocks, inline code/bold/italic, links,
+  // lists, blockquotes, tables. Not full CommonMark.
+  function setText(el, text) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    el.appendChild(document.createTextNode(text));
+  }
+  function setStatus(el, text, cls) {
+    while (el.firstChild) el.removeChild(el.firstChild);
+    const div = document.createElement('div');
+    div.className = cls;
+    div.textContent = text;
+    el.appendChild(div);
+  }
+  function makeNode(tag, text) {
+    const el = document.createElement(tag);
+    if (text !== undefined) el.appendChild(document.createTextNode(text));
+    return el;
+  }
+  function renderInlineToNodes(s) {
+    const nodes = [];
+    let i = 0;
+    while (i < s.length) {
+      if (s[i] === '`') {
+        const end = s.indexOf('`', i + 1);
+        if (end !== -1) { nodes.push(makeNode('code', s.slice(i + 1, end))); i = end + 1; continue; }
+      }
+      if (s[i] === '*' && s[i + 1] === '*') {
+        const end = s.indexOf('**', i + 2);
+        if (end !== -1) { nodes.push(makeNode('strong', s.slice(i + 2, end))); i = end + 2; continue; }
+      }
+      if (s[i] === '*') {
+        const end = s.indexOf('*', i + 1);
+        if (end !== -1 && end - i > 1) { nodes.push(makeNode('em', s.slice(i + 1, end))); i = end + 1; continue; }
+      }
+      if (s[i] === '[') {
+        const close = s.indexOf(']', i + 1);
+        if (close !== -1 && s[close + 1] === '(') {
+          const urlEnd = s.indexOf(')', close + 2);
+          if (urlEnd !== -1) {
+            const a = document.createElement('a');
+            a.textContent = s.slice(i + 1, close);
+            // r13-L-01: tightened URL guard. ALLOW http/https + same-origin relative.
+            // BLOCK javascript:, data:, mailto:, vbscript:, file:, AND protocol-relative `//`.
+            const url = s.slice(close + 2, urlEnd);
+            const isAllowed = (
+              /^https?:\/\//.test(url) ||
+              (!url.startsWith('//') && !/^[^:/?#]+:/.test(url))
+            );
+            if (isAllowed) { a.href = url; a.target = '_blank'; a.rel = 'noopener'; }
+            nodes.push(a);
+            i = urlEnd + 1;
+            continue;
+          }
+        }
+      }
+      let j = i;
+      while (j < s.length && !'`*['.includes(s[j])) j++;
+      if (j === i) j = i + 1;
+      nodes.push(document.createTextNode(s.slice(i, j)));
+      i = j;
+    }
+    return nodes;
+  }
+  function renderMarkdownToFragment(md) {
+    const frag = document.createDocumentFragment();
+    const lines = md.split('\n');
+    let i = 0;
+    while (i < lines.length) {
+      const line = lines[i];
+      if (/^```/.test(line)) {
+        const buf = []; i++;
+        while (i < lines.length && !/^```/.test(lines[i])) { buf.push(lines[i]); i++; }
+        i++;
+        const pre = document.createElement('pre');
+        const code = document.createElement('code');
+        code.textContent = buf.join('\n');
+        pre.appendChild(code);
+        frag.appendChild(pre);
+        continue;
+      }
+      const h = line.match(/^(#{1,6})\s+(.*)$/);
+      if (h) {
+        const tag = 'h' + h[1].length;
+        const el = document.createElement(tag);
+        for (const n of renderInlineToNodes(h[2])) el.appendChild(n);
+        frag.appendChild(el); i++; continue;
+      }
+      if (/^\s*\|/.test(line) && i + 1 < lines.length && /^\s*\|?\s*-/.test(lines[i + 1])) {
+        const tbl = document.createElement('table');
+        const head = line.split('|').slice(1, -1).map((c) => c.trim());
+        const tr = document.createElement('tr');
+        for (const c of head) {
+          const th = document.createElement('th');
+          for (const n of renderInlineToNodes(c)) th.appendChild(n);
+          tr.appendChild(th);
+        }
+        tbl.appendChild(tr); i += 2;
+        while (i < lines.length && /^\s*\|/.test(lines[i])) {
+          const cells = lines[i].split('|').slice(1, -1).map((c) => c.trim());
+          const row = document.createElement('tr');
+          for (const c of cells) {
+            const td = document.createElement('td');
+            for (const n of renderInlineToNodes(c)) td.appendChild(n);
+            row.appendChild(td);
+          }
+          tbl.appendChild(row); i++;
+        }
+        frag.appendChild(tbl); continue;
+      }
+      if (/^\s*[-*]\s+/.test(line)) {
+        const ul = document.createElement('ul');
+        while (i < lines.length && /^\s*[-*]\s+/.test(lines[i])) {
+          const li = document.createElement('li');
+          for (const n of renderInlineToNodes(lines[i].replace(/^\s*[-*]\s+/, ''))) li.appendChild(n);
+          ul.appendChild(li); i++;
+        }
+        frag.appendChild(ul); continue;
+      }
+      if (/^>\s?/.test(line)) {
+        const bq = document.createElement('blockquote');
+        let first = true;
+        while (i < lines.length && /^>\s?/.test(lines[i])) {
+          if (!first) bq.appendChild(document.createElement('br'));
+          for (const n of renderInlineToNodes(lines[i].replace(/^>\s?/, ''))) bq.appendChild(n);
+          first = false; i++;
+        }
+        frag.appendChild(bq); continue;
+      }
+      if (line.trim() === '') { i++; continue; }
+      const p = document.createElement('p');
+      const buf = [line]; i++;
+      while (i < lines.length && lines[i].trim() !== '' && !/^(#{1,6}\s|```|>|\s*[-*]\s|\s*\|)/.test(lines[i])) {
+        buf.push(lines[i]); i++;
+      }
+      for (const n of renderInlineToNodes(buf.join(' '))) p.appendChild(n);
+      frag.appendChild(p);
+    }
+    return frag;
+  }
+  // ---------- wave list + viewer ----------
+  let selectedRow = null;
+  function renderMeta(w) {
+    const meta = document.getElementById('waveMeta');
+    while (meta.firstChild) meta.removeChild(meta.firstChild);
+    const fields = [
+      ['Wave', w.id],
+      ['Status', w.status],
+      ['Created', w.created_at ?? '—'],
+      ['Checkpoint', w.checkpoint_at ?? '—'],
+      ['Agents', String(w.agents_count ?? 0)],
+      ['Active claims', String(w.claims_active ?? 0)],
+      ['Open blockers', String(w.blockers_open ?? 0)],
+    ];
+    for (const [label, val] of fields) {
+      const row = document.createElement('span');
+      row.className = 'meta-row';
+      const lab = document.createElement('strong');
+      lab.textContent = label + ': ';
+      row.appendChild(lab);
+      row.appendChild(document.createTextNode(val));
+      meta.appendChild(row);
+    }
+  }
+  async function loadWaveState(w, row) {
+    if (selectedRow) selectedRow.classList.remove('selected');
+    if (row) { row.classList.add('selected'); selectedRow = row; }
+    renderMeta(w);
+    const doc = document.getElementById('doc');
+    setStatus(doc, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/planning?path=' + encodeURIComponent(w.path));
+      if (!r.ok) {
+        const err = await r.json().catch(() => ({ error: 'unknown' }));
+        setStatus(doc, r.status + ': ' + (err.error || 'failed'), 'err');
+        return;
+      }
+      const j = await r.json();
+      while (doc.firstChild) doc.removeChild(doc.firstChild);
+      doc.appendChild(renderMarkdownToFragment(j.body || ''));
+    } catch (e) {
+      setStatus(doc, e.message, 'err');
+    }
+  }
+  async function loadWaves() {
+    const list = document.getElementById('waveList');
+    setStatus(list, 'Loading…', 'hint');
+    try {
+      const r = await fetch('/api/waves');
+      const j = await r.json();
+      while (list.firstChild) list.removeChild(list.firstChild);
+      const waves = j.waves || [];
+      if (waves.length === 0) {
+        setStatus(list, 'No waves found in .ijfw/wave-*/', 'hint');
+        setStatus(document.getElementById('doc'),
+          'No wave-* directories exist yet. Dispatch a wave via /superpowers:subagent-driven-development to see live state here.',
+          'hint');
+        return;
+      }
+      for (const w of waves) {
+        const row = document.createElement('div');
+        row.className = 'wave-row status-' + (w.status || 'unknown');
+        const id = document.createElement('div'); id.className = 'id'; id.textContent = w.id;
+        const status = document.createElement('div'); status.className = 'status'; status.textContent = w.status || 'unknown';
+        const ts = document.createElement('div'); ts.className = 'ts'; ts.textContent = w.checkpoint_at ?? (w.created_at ?? '');
+        row.appendChild(id); row.appendChild(status); row.appendChild(ts);
+        row.addEventListener('click', () => loadWaveState(w, row));
+        list.appendChild(row);
+      }
+      // Auto-select first (newest) wave.
+      const first = list.firstChild;
+      if (first) loadWaveState(waves[0], first);
+    } catch (e) {
+      setStatus(list, e.message, 'err');
+    }
+  }
+  setStatus(document.getElementById('doc'), 'Select a wave from the list to view its STATE.md.', 'hint');
+  loadWaves();
+</script>
+</body>
+</html>

package/src/dashboard-client.html CHANGED Viewed

@@ -255,6 +255,10 @@ tr:hover td{background:var(--surface)}
     <div class="breadcrumb" id="breadcrumb"><span style="color:var(--fg-dim)">Overview</span> <b>Today</b></div>
     <div class="spacer"></div>
     <span class="tier-pill">MAX 20x</span>
+    <!-- v1.5.0 N4.obs M5: cross-link back to the operator dashboard (port
+         19747). Operators flip between MCP (wave/orchestrator views) and
+         operator (cost/memory views) so the link is reciprocal. -->
+    <a class="icon-btn" id="operatorDashLink" href="http://localhost:19747/" target="_blank" rel="noopener" title="Open operator dashboard (cost + memory views)">Operator dashboard</a>
     <button class="icon-btn" id="themeBtn" aria-label="Toggle theme">&#9790; Theme</button>
   </header>
@@ -275,7 +279,7 @@ tr:hover td{background:var(--surface)}
         <div class="hcard">
           <div class="hlabel"><span class="pulse"></span> Active Session</div>
           <div class="hval" style="font-size:20px;padding-top:6px">ijfw</div>
-          <div class="hsub">claude-opus-4-6 -- <b>current</b></div>
+          <div class="hsub">claude-opus-4-7 -- <b>current</b></div>
         </div>
         <div class="hcard">
           <div class="hlabel">Cache Efficiency</div>
@@ -1402,7 +1406,18 @@ async function loadExtensionActive() {
       permsEl.setAttribute('style', 'font-size:12px;color:var(--fg-dim)');
       var reads = (a.permissions.reads || []).join(', ') || 'none';
       var writes = (a.permissions.writes || []).join(', ') || 'none';
-      permsEl.innerHTML = '<b style="color:var(--fg)">reads:</b> ' + reads + ' &nbsp; <b style="color:var(--fg)">writes:</b> ' + writes;
+      var bReads = document.createElement('b');
+      bReads.setAttribute('style', 'color:var(--fg)');
+      bReads.textContent = 'reads:';
+      var textReads = document.createTextNode(' ' + reads + '\u00A0\u00A0');
+      var bWrites = document.createElement('b');
+      bWrites.setAttribute('style', 'color:var(--fg)');
+      bWrites.textContent = 'writes:';
+      var textWrites = document.createTextNode(' ' + writes);
+      permsEl.appendChild(bReads);
+      permsEl.appendChild(textReads);
+      permsEl.appendChild(bWrites);
+      permsEl.appendChild(textWrites);
       wrap.appendChild(permsEl);
     }
     el.appendChild(wrap);

package/src/dashboard-server.js CHANGED Viewed

@@ -434,6 +434,158 @@ export async function startServer(options = {}) {
       }));
     }],
+    // v1.4.4 N8 — Planning doc viewer. Same path-traversal guard as /api/memory/file,
+    // but allowed roots are .planning/, .ijfw/memory/, and .ijfw/wave-*/ all under REPO_ROOT.
+    ['/api/planning', (req, res, url) => {
+      const rawPath = url.searchParams.get('path') || '';
+      if (!rawPath) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'path query param required' }));
+        return;
+      }
+      if (isAbsolute(rawPath) || rawPath.split(/[\\/]/).some((seg) => seg === '..')) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'path traversal not allowed' }));
+        return;
+      }
+      const reqPath = resolve(REPO_ROOT, rawPath);
+      function canonOrNull(p) {
+        try { return realpathSync(p); } catch { return null; }
+      }
+      function isUnder(allowedRoot, canonChild) {
+        const canonRoot = canonOrNull(allowedRoot);
+        if (!canonRoot || !canonChild) return false;
+        const rel = relative(canonRoot, canonChild);
+        return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel);
+      }
+      function isUnderWaveRoot(canonChild) {
+        // r13-M-05: restrict to STATE.md / SUMMARY.md filenames within
+        // .ijfw/wave-*/ subdirs. Previously allowed ANY file in a wave dir;
+        // wave directories may contain .tmp, lock files, or partial blackboard
+        // data that shouldn't be browser-readable.
+        const ijfwDir = canonOrNull(join(REPO_ROOT, '.ijfw'));
+        if (!ijfwDir || !canonChild) return false;
+        const rel = relative(ijfwDir, canonChild);
+        if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) return false;
+        const first = rel.split(/[\\/]/)[0];
+        if (!first.startsWith('wave-') || first.length === 'wave-'.length) return false;
+        return rel.endsWith('STATE.md') || rel.endsWith('SUMMARY.md');
+      }
+      const canonPath = canonOrNull(reqPath);
+      if (!canonPath) {
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'file not found' }));
+        return;
+      }
+      const allowed = (
+        isUnder(join(REPO_ROOT, '.planning'), canonPath) ||
+        isUnder(join(REPO_ROOT, '.ijfw', 'memory'), canonPath) ||
+        isUnderWaveRoot(canonPath)
+      );
+      if (!allowed) {
+        res.writeHead(403, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'outside allowed planning roots' }));
+        return;
+      }
+      try {
+        const body = readFileSync(canonPath, 'utf8');
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ body: body.slice(0, 200000), path: rawPath }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message, endpoint: '/api/planning' }));
+      }
+    }],
+    // v1.4.4 N8 — Planning-docs viewer (HTML SPA).
+    ['/planning', async (req, res) => {
+      try {
+        const html = await readFile(join(__dirname, 'dashboard-client-planning.html'), 'utf8');
+        res.writeHead(200, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+          'Content-Security-Policy': "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'",
+        });
+        res.end(html);
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Planning viewer not found: ' + err.message);
+      }
+    }],
+    // v1.5.0 S10 — wave-state JSON list. Reads .ijfw/wave-*/STATE.md frontmatter.
+    // Sorted by checkpoint_at desc, capped at 50 (any project with >50 active
+    // waves has bigger problems). Same security pattern as /api/planning.
+    ['/api/waves', async (req, res) => {
+      try {
+        const ijfwDir = join(REPO_ROOT, '.ijfw');
+        if (!existsSync(ijfwDir)) {
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ waves: [] }));
+          return;
+        }
+        const entries = readdirSync(ijfwDir, { withFileTypes: true });
+        const { readWaveState } = await import('./orchestrator/wave-state.js');
+        const out = [];
+        for (const ent of entries) {
+          if (!ent.isDirectory() || !ent.name.startsWith('wave-')) continue;
+          const waveId = ent.name.slice('wave-'.length);
+          if (!waveId || !/^[A-Za-z0-9_-]+$/.test(waveId)) continue;
+          try {
+            const state = await readWaveState(waveId, REPO_ROOT);
+            if (!state) continue;
+            out.push({
+              id: waveId,
+              status: state.frontmatter.status ?? 'unknown',
+              created_at: state.frontmatter.created_at ?? null,
+              checkpoint_at: state.frontmatter.checkpoint_at ?? null,
+              claims_active: state.frontmatter.claims_active ?? 0,
+              agents_count: Array.isArray(state.frontmatter.agents) ? state.frontmatter.agents.length : 0,
+              path: `.ijfw/wave-${waveId}/STATE.md`,
+            });
+          } catch { /* skip malformed wave dirs */ }
+        }
+        out.sort((a, b) => String(b.checkpoint_at || '').localeCompare(String(a.checkpoint_at || '')));
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ waves: out.slice(0, 50) }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: err.message, endpoint: '/api/waves' }));
+      }
+    }],
+    // v1.5.0 S10 — wave-state viewer (HTML SPA). Same CSP as /planning.
+    ['/waves', async (req, res) => {
+      try {
+        const html = await readFile(join(__dirname, 'dashboard-client-waves.html'), 'utf8');
+        res.writeHead(200, {
+          'Content-Type': 'text/html; charset=utf-8',
+          'Cache-Control': 'no-store',
+          'Content-Security-Policy': "default-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline'; connect-src 'self'",
+        });
+        res.end(html);
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'text/plain' });
+        res.end('Waves viewer not found: ' + err.message);
+      }
+    }],
+    // v1.5.0 F4 — serve checkpoint-contract.md as plain text so operators can
+    // find the implementer-side checkpoint protocol from the dashboard.
+    ['/docs/checkpoint-contract', async (req, res) => {
+      try {
+        const md = await readFile(join(__dirname, 'orchestrator/checkpoint-contract.md'), 'utf8');
+        res.writeHead(200, {
+          'Content-Type': 'text/plain; charset=utf-8',
+          'Cache-Control': 'public, max-age=300',
+        });
+        res.end(md);
+      } catch (err) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Checkpoint contract not found: ' + err.message);
+      }
+    }],
     ['/api/memory/file', (req, res, url) => {
       const rawPath = url.searchParams.get('path') || '';
       if (!rawPath) {

package/src/deploy-alerts.js ADDED Viewed

@@ -0,0 +1,150 @@
+/**
+ * deploy-alerts.js — v1.5.0 audit-MED-update-M8 (F-REL-2).
+ *
+ * When `extension-installer.installExtension` exits with `deploy_partial: true`,
+ * the failure detail used to be returned in the install reply only — the next
+ * prelude had no way to surface "you have a half-deployed extension somewhere".
+ *
+ * This module persists each partial deploy to a jsonl tail at
+ * `~/.ijfw/state/deploy-failures.jsonl` so the memory prelude (handlePrelude in
+ * `server.js`) can read the last N entries and emit a "Deploy alerts" line.
+ *
+ * File contract:
+ *   - JSONL, one record per line.
+ *   - Each record:
+ *       {
+ *         ts: ISO8601,
+ *         extension: <manifest.name>,
+ *         scope: 'project' | 'org' | 'user',
+ *         failures: Array<{platform, skillName, error}>,
+ *       }
+ *   - Soft cap: 200 lines. Older lines drop off via a one-shot trim on write.
+ *   - Append-only and atomic in the common case (single writeFile call); the
+ *     trim path rewrites the whole tail under the same atomic shape.
+ *   - Failure to write is non-fatal — alert path is best-effort observability.
+ *
+ * The reader is bounded at N=10 by default — short-tail "what's wrong right
+ * now" surfacing, not an audit log.
+ */
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const ALERT_FILE_NAME = 'deploy-failures.jsonl';
+const MAX_LINES_ON_DISK = 200;
+const DEFAULT_READ_TAIL = 10;
+function statePath() {
+  return join(homedir(), '.ijfw', 'state');
+}
+export function deployFailuresPath() {
+  return join(statePath(), ALERT_FILE_NAME);
+}
+/**
+ * Record a partial-deploy event.
+ *
+ * @param {object} record
+ * @param {string} record.extension
+ * @param {'project'|'org'|'user'} record.scope
+ * @param {Array<{platform:string, skillName?:string, error:string}>} record.failures
+ * @returns {Promise<{ok:boolean, path?:string, error?:string}>}
+ */
+export async function recordDeployFailure(record) {
+  if (!record || typeof record !== 'object') {
+    return { ok: false, error: 'record must be an object' };
+  }
+  if (typeof record.extension !== 'string' || record.extension.length === 0) {
+    return { ok: false, error: 'extension is required' };
+  }
+  if (!Array.isArray(record.failures)) {
+    return { ok: false, error: 'failures must be an array' };
+  }
+  const entry = {
+    ts: new Date().toISOString(),
+    extension: record.extension,
+    scope: record.scope || 'project',
+    failures: record.failures.map((f) => ({
+      // v1.5.0 wire-W2.design-misc — was `typeof f && f.platform`, which is
+      // effectively `f.platform` because `typeof f` is always a truthy string
+      // (even for null/undefined). That meant a null entry in the failures
+      // array threw a TypeError instead of falling back to 'unknown'. The
+      // adjacent skillName + error fields already use the correct guard.
+      platform: f && f.platform ? String(f.platform) : 'unknown',
+      skillName: f && f.skillName ? String(f.skillName) : null,
+      error: f && f.error ? String(f.error).slice(0, 500) : 'unknown',
+    })),
+  };
+  const path = deployFailuresPath();
+  try {
+    await mkdir(statePath(), { recursive: true });
+    // Trim-on-overflow: if existing file already > cap, rewrite the tail.
+    let existing = '';
+    try {
+      existing = await readFile(path, 'utf8');
+    } catch {
+      existing = '';
+    }
+    const lines = existing ? existing.split('\n').filter((l) => l.trim()) : [];
+    lines.push(JSON.stringify(entry));
+    const trimmed = lines.slice(-MAX_LINES_ON_DISK);
+    await writeFile(path, trimmed.join('\n') + '\n', { encoding: 'utf8', mode: 0o600 });
+    return { ok: true, path };
+  } catch (err) {
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+}
+/**
+ * Read the last N deploy-failure records (default 10). Returns oldest-first.
+ *
+ * @param {{limit?:number}} [opts]
+ * @returns {Promise<Array>}
+ */
+export async function readDeployFailures(opts = {}) {
+  const limit = Number.isInteger(opts.limit) && opts.limit > 0 ? opts.limit : DEFAULT_READ_TAIL;
+  let raw;
+  try {
+    raw = await readFile(deployFailuresPath(), 'utf8');
+  } catch {
+    return [];
+  }
+  const lines = raw.split('\n').filter((l) => l.trim());
+  const tail = lines.slice(-limit);
+  const out = [];
+  for (const line of tail) {
+    try {
+      const parsed = JSON.parse(line);
+      if (parsed && typeof parsed === 'object') out.push(parsed);
+    } catch {
+      // skip malformed line — don't fail the read
+    }
+  }
+  return out;
+}
+/**
+ * Render the last N entries as terse prelude lines. Empty array → empty string.
+ *
+ * @param {{limit?:number}} [opts]
+ * @returns {Promise<string>}
+ */
+export async function renderDeployAlertsForPrelude(opts = {}) {
+  const entries = await readDeployFailures(opts);
+  if (entries.length === 0) return '';
+  const lines = ['## Deploy alerts'];
+  for (const e of entries) {
+    const fcount = Array.isArray(e.failures) ? e.failures.length : 0;
+    const platforms = Array.isArray(e.failures)
+      ? Array.from(new Set(e.failures.map((f) => f.platform).filter(Boolean))).join(',')
+      : '';
+    const head = `- ${e.ts} — ${e.extension} (scope=${e.scope || 'project'}): ${fcount} failure${fcount === 1 ? '' : 's'}${platforms ? ` [${platforms}]` : ''}`;
+    lines.push(head);
+  }
+  lines.push('');
+  return lines.join('\n');
+}