@invisibleloop/pulse 0.20.37 → 0.20.39

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.20.37",
+  "version": "0.20.39",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -61,7 +61,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node src/mcp/mcp.test.js && node src/mcp/guards.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root ../../docs --port 4000",
     "docs:start": "node ../../docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.37
+0.20.39

package/src/mcp/guards.js

@@ -0,0 +1,94 @@
+/**
+ * Input guards for MCP tools.
+ *
+ * The MCP server runs locally, but its tool arguments are chosen by an AI agent
+ * that may have read untrusted content (a fetched page, a pasted brief). These
+ * helpers keep a steered tool call inside the project and off internal networks.
+ */
+
+import fs   from 'fs'
+import path from 'path'
+import net  from 'net'
+import dns  from 'dns/promises'
+
+/**
+ * Resolve a caller-supplied file path and require it to live inside `root`.
+ * Relative paths resolve against `root`. Symlinks are followed before the check
+ * so a link inside the project cannot point outside it.
+ *
+ * @returns {string} absolute path inside root
+ * @throws  {Error}  when the path escapes root
+ */
+export function resolveInRoot(root, file) {
+  const rootReal = fs.realpathSync(root)
+  const abs      = path.resolve(root, file)
+
+  // realpath the deepest existing ancestor so not-yet-created files are still checked
+  let probe = abs
+  while (!fs.existsSync(probe)) {
+    const parent = path.dirname(probe)
+    if (parent === probe) break
+    probe = parent
+  }
+  const real = path.join(fs.realpathSync(probe), path.relative(probe, abs))
+
+  const rel = path.relative(rootReal, real)
+  if (rel === '' || rel.startsWith('..') || path.isAbsolute(rel)) {
+    throw new Error(`path must be inside the project (${root}): ${file}`)
+  }
+  return abs
+}
+
+/** True for http(s) URLs that point at this machine (localhost / 127.0.0.0/8 / ::1). */
+export function isLoopbackUrl(rawUrl) {
+  let u
+  try { u = new URL(rawUrl) } catch { return false }
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') return false
+  const host = u.hostname.replace(/^\[|\]$/g, '').toLowerCase()
+  return host === 'localhost' || host.endsWith('.localhost') || host === '::1' || /^127\./.test(host)
+}
+
+/** True when an IP literal is loopback, private, link-local, CGNAT, multicast or otherwise non-public. */
+export function isPrivateAddress(ip) {
+  if (net.isIPv4(ip)) {
+    const [a, b] = ip.split('.').map(Number)
+    return a === 0 || a === 10 || a === 127 ||
+      (a === 100 && b >= 64 && b <= 127) ||
+      (a === 169 && b === 254) ||
+      (a === 172 && b >= 16 && b <= 31) ||
+      (a === 192 && b === 168) ||
+      a >= 224
+  }
+  if (net.isIPv6(ip)) {
+    const v = ip.toLowerCase()
+    const mapped = v.match(/^::ffff:(\d+\.\d+\.\d+\.\d+)$/)
+    if (mapped) return isPrivateAddress(mapped[1])
+    return v === '::' || v === '::1' ||
+      /^f[cd]/.test(v) ||            // fc00::/7 unique local
+      /^fe[89ab]/.test(v) ||         // fe80::/10 link-local
+      /^ff/.test(v)                  // multicast
+  }
+  return true // not an IP — treat as unsafe
+}
+
+/**
+ * Require a URL to be http(s) and resolve only to public addresses.
+ * Call before every request, including each redirect hop.
+ *
+ * @throws {Error} when the URL is not http(s) or resolves to a non-public address
+ */
+export async function assertPublicUrl(rawUrl) {
+  const u = rawUrl instanceof URL ? rawUrl : new URL(rawUrl)
+  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
+    throw new Error(`only http(s) URLs are allowed (got ${u.protocol})`)
+  }
+  const host = u.hostname.replace(/^\[|\]$/g, '')
+  if (net.isIP(host)) {
+    if (isPrivateAddress(host)) throw new Error(`${host} is not a public address`)
+    return
+  }
+  const addrs = await dns.lookup(host, { all: true })
+  if (!addrs.length || addrs.some(a => isPrivateAddress(a.address))) {
+    throw new Error(`${host} resolves to a non-public address`)
+  }
+}

package/src/mcp/server.js

@@ -36,9 +36,11 @@ import { z }                   from 'zod'
 import path                      from 'path'
 import fs                        from 'fs'
 import http                      from 'http'
+import https                     from 'https'
 import { spawn, spawnSync } from 'child_process'
 
 import { loadPages } from '../cli/discover.js'
+import { resolveInRoot, isLoopbackUrl, assertPublicUrl } from './guards.js'
 import { validateContent, validateFile, formatValidationResult } from '../cli/validate.js'
 import { readJournal, formatJournal, resolveEntries, formatResolveResult } from '../cli/diagnose.js'
 import { writeStamp, formatStampResult } from '../cli/stamp.js'
@@ -821,6 +823,9 @@ server.registerTool(
       return text('Error: provide only one of content or file, not both')
     }
 
+    if (file) {
+      try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
+    }
     const result = file ? await validateFile(file, ROOT) : await validateContent(content, ROOT)
     return text(formatValidationResult(result, { nextSteps: true }))
   }
@@ -1045,6 +1050,10 @@ The generated file uses @invisibleloop/pulse/testing (renderSync / render). Do N
     },
   },
   async ({ file }) => {
+    try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
+    if (!file.endsWith('.js') || file.endsWith('.test.js')) {
+      return text('Error: file must be a spec .js file (not a .test.js file)')
+    }
     if (!fs.existsSync(file)) {
       return text(`File not found: ${file}`)
     }
@@ -1207,6 +1216,9 @@ server.registerTool(
     inputSchema: { url: z.string().describe('Full URL, e.g. http://localhost:3000/about') },
   },
   ({ url }) => new Promise(resolve => {
+    if (!isLoopbackUrl(url) || !url.startsWith('http:')) {
+      return resolve(text('Error: pulse_fetch_page only fetches the local dev server (http://localhost:PORT/...)'))
+    }
     const req = http.get(url, { timeout: 10_000 }, res => {
       const chunks = []
       res.on('data', d => chunks.push(d))
@@ -1399,7 +1411,7 @@ any feature build.
 
     let source = content
     if (file) {
-      if (!path.isAbsolute(file)) file = path.resolve(process.cwd(), file)
+      try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
       if (!fs.existsSync(file)) return text(`File not found: ${file}`)
       source = fs.readFileSync(file, 'utf8')
     }
@@ -1575,12 +1587,15 @@ server.registerTool(
     const inSync       = installed === staticAsset
 
     // Fetch latest from npm registry
-    const req = http.get('http://registry.npmjs.org/@invisibleloop/pulse/latest', { timeout: 5000 }, res => {
+    const req = https.get('https://registry.npmjs.org/@invisibleloop/pulse/latest', { timeout: 5000 }, res => {
       const chunks = []
       res.on('data', d => chunks.push(d))
       res.on('end', () => {
         let latest = 'unknown'
-        try { latest = JSON.parse(Buffer.concat(chunks).toString()).version } catch { /* ignore */ }
+        try {
+          const v = JSON.parse(Buffer.concat(chunks).toString()).version
+          if (/^\d+\.\d+\.\d+(-[\w.]+)?$/.test(v)) latest = v   // never echo an unvalidated string
+        } catch { /* ignore */ }
 
         const lines = [
           `Installed package : v${installed}`,
@@ -3351,9 +3366,11 @@ Call it with the external URLs you plan to use, before your first Lighthouse run
       let blocked = null
       try {
         for (let hop = 0; hop < MAX_HOPS; hop++) {
+          await assertPublicUrl(url)   // every hop: block internal/metadata addresses
           const res = await fetch(url, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(5000) })
           if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
             url = new URL(res.headers.get('location'), url)
+            await assertPublicUrl(url)
             chain.push(url.origin)
             continue
           }
@@ -3362,6 +3379,7 @@ Call it with the external URLs you plan to use, before your first Lighthouse run
             const get = await fetch(url, { method: 'GET', redirect: 'manual', headers: { Range: 'bytes=0-0' }, signal: AbortSignal.timeout(5000) })
             if (get.status >= 300 && get.status < 400 && get.headers.get('location')) {
               url = new URL(get.headers.get('location'), url)
+              await assertPublicUrl(url)
               chain.push(url.origin)
               continue
             }
@@ -3413,6 +3431,7 @@ Run this immediately after writing a theme file — before production build and
     let source = css || ''
 
     if (!source && file) {
+      try { file = resolveInRoot(ROOT, file) } catch (e) { return text(`Error: ${e.message}`) }
       if (!fs.existsSync(file)) return text(`File not found: ${file}`)
       source = fs.readFileSync(file, 'utf8')
     }

package/src/runtime/ssr.js

@@ -148,7 +148,7 @@ export function renderToStream(spec, ctx = {}, nonce = '') {
       const mergedAllState = applyCtxExtras(mergeStoreKeys(spec, allServerState, ctx.store), ctx)
       if (spec.hydrate && Object.keys(mergedAllState).length > 0) {
         controller.enqueue(encode(
-          `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(mergedAllState)};</script>`
+          `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${safeJson(mergedAllState)};</script>`
         ))
       }
 
@@ -275,7 +275,7 @@ export function buildStoreScript(spec, storeState, nonce, livePath = '') {
   // mount() connects only when the page actually subscribes to store keys.
   const liveFlag = livePath ? `window.__PULSE_LIVE__='${livePath}';` : ''
   if (storeState && Object.keys(storeState).length > 0) {
-    return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}window.__PULSE_STORE__=${JSON.stringify(storeState)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
+    return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}window.__PULSE_STORE__=${safeJson(storeState)};window.__updatePulseStore__=function(s){window.__PULSE_STORE__=Object.assign(window.__PULSE_STORE__||{},s);};</script>`
   }
   return `<script nonce="${nonce}">window.__PULSE_NONCE__='${nonce}';${liveFlag}</script>`
 }
@@ -373,7 +373,7 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
   const deferredStyleLinks = (meta.deferredStyles || []).length > 0
     ? `<script nonce="${nonce}">(function(){${
         (meta.deferredStyles || []).map(href =>
-          `var l=document.createElement('link');l.rel='stylesheet';l.href='${esc(href)}';document.head.appendChild(l);`
+          `var l=document.createElement('link');l.rel='stylesheet';l.href=${safeJson(href)};document.head.appendChild(l);`
         ).join('')
       }})();</script>`
     : ''
@@ -383,14 +383,14 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
     .join('\n  ')
 
   const schemaScript = meta.schema
-    ? `<script type="application/ld+json">${JSON.stringify(meta.schema)}</script>`
+    ? `<script type="application/ld+json">${safeJson(meta.schema)}</script>`
     : ''
 
   // Serialise server state into the page so the client runtime can read it
   // without making a second request. Only needed when the page is hydrated —
   // purely server-rendered pages have no JS to read it.
   const serverStateScript = spec.hydrate && Object.keys(serverState).length > 0
-    ? `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${JSON.stringify(serverState)};</script>`
+    ? `<script nonce="${nonce}">window.__PULSE_SERVER__ = ${safeJson(serverState)};</script>`
     : ''
 
   const storeStateScript = buildStoreScript(spec, storeState, nonce, livePath)
@@ -677,6 +677,22 @@ function isBundle(hydratePath) {
   return typeof hydratePath === 'string' && hydratePath.startsWith('/dist/')
 }
 
+/**
+ * JSON.stringify for embedding inside an inline <script>. Plain JSON.stringify
+ * leaves `<`, `>` and `&` alone, so a value containing "</script>" (or "<!--")
+ * ends the script element early and the rest is parsed as HTML. Escaping those
+ * as \uXXXX keeps the output valid JS/JSON with the same parsed value. U+2028/9
+ * are escaped too (line terminators in JS string literals before ES2019).
+ */
+export function safeJson(value) {
+  return JSON.stringify(value)
+    ?.replace(/</g, '\\u003c')
+    .replace(/>/g, '\\u003e')
+    .replace(/&/g, '\\u0026')
+    .replace(/\u2028/g, '\\u2028')
+    .replace(/\u2029/g, '\\u2029')
+}
+
 /**
  * Escape HTML special characters for safe attribute insertion.
  */

package/src/server/index.js

@@ -21,7 +21,7 @@ import { createRequire } from 'module'
 
 const _require = createRequire(import.meta.url)
 export const version = _require('../../package.json').version
-import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript, buildStylePreconnects } from '../runtime/ssr.js'
+import { renderToString, renderToStream, renderToNavStream, wrapDocument, resolveServerState, buildStoreScript, buildHydrateScript, buildStylePreconnects, safeJson } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'
 
@@ -1422,7 +1422,7 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
           ).join('')
         }})();</script>`
       : '',
-    meta.schema ? `  <script type="application/ld+json">${JSON.stringify(meta.schema)}</script>` : '',
+    meta.schema ? `  <script type="application/ld+json">${safeJson(meta.schema)}</script>` : '',
   ].filter(Boolean).join('\n')
 
   const bodyAttr = [

package/scripts/css-purge.test.js

@@ -1,147 +0,0 @@
-/**
- * CSS purge/minify tests — run with: node scripts/css-purge.test.js
- *
- * Regression focus: @import URLs containing `;` and `&` in their query string
- * (Google Fonts) were truncated by the production build — the block parser
- * split the statement at the `;` inside the quoted URL, silently breaking the
- * theme in production while dev (which serves CSS unprocessed) looked fine.
- */
-
-import { test } from 'node:test'
-import assert   from 'node:assert/strict'
-import { parseCssBlocks, purgeCss, minifyCss, extractUsedClasses, selectorUsed } from './css-purge.js'
-
-const FONT_IMPORT = `@import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap');`
-
-// ---------------------------------------------------------------------------
-// The @import regression
-// ---------------------------------------------------------------------------
-
-test('parseCssBlocks: does not split @import at a ; inside a quoted URL', () => {
-  const css = `${FONT_IMPORT}\n:root { --accent: #e25; }`
-  const blocks = parseCssBlocks(css)
-  assert.equal(blocks.length, 2, `Expected 2 blocks, got ${blocks.length}: ${JSON.stringify(blocks.map(b => b.raw))}`)
-  assert.equal(blocks[0].type, 'at-simple')
-  assert.equal(blocks[0].raw, FONT_IMPORT)
-})
-
-test('parseCssBlocks: handles double-quoted URLs and escapes', () => {
-  const css = `@import url("https://example.com/a;b&c=d");\n.x { color: red; }`
-  const blocks = parseCssBlocks(css)
-  assert.equal(blocks[0].raw, `@import url("https://example.com/a;b&c=d");`)
-})
-
-test('purgeCss + minifyCss: Google Fonts @import survives the full pipeline intact', () => {
-  const css = `${FONT_IMPORT}\n:root { --font: 'Inter', sans-serif; }\n.unused { color: red; }`
-  const out = minifyCss(purgeCss(css, new Set([])))
-  assert.ok(
-    out.includes(`url('https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap')`),
-    `@import URL was mangled by the build pipeline. Output: ${out}`
-  )
-})
-
-test('minifyCss: quoted strings are untouched by punctuation collapsing', () => {
-  const css = `.x { content: "a ; b : c , d" ; }`
-  const out = minifyCss(css)
-  assert.ok(out.includes(`"a ; b : c , d"`), `Quoted string was altered: ${out}`)
-})
-
-// ---------------------------------------------------------------------------
-// Behaviour preserved through the extraction refactor
-// ---------------------------------------------------------------------------
-
-test('purgeCss: drops unused class rules, keeps used ones', () => {
-  const css = `.used { color: red; }\n.unused { color: blue; }`
-  const out = purgeCss(css, new Set(['used']))
-  assert.ok(out.includes('.used'))
-  assert.ok(!out.includes('.unused'))
-})
-
-test('purgeCss: element and :root rules are always kept', () => {
-  const css = `:root { --x: 1; }\nbody { margin: 0; }`
-  const out = purgeCss(css, new Set([]))
-  assert.ok(out.includes(':root'))
-  assert.ok(out.includes('body'))
-})
-
-test('purgeCss: recurses into @media and keeps @font-face', () => {
-  const css = `@media (min-width: 600px) { .used { color: red; } .unused { color: blue; } }\n@font-face { font-family: X; src: url('/x.woff2'); }`
-  const out = purgeCss(css, new Set(['used']))
-  assert.ok(out.includes('.used'))
-  assert.ok(!out.includes('.unused'))
-  assert.ok(out.includes('@font-face'))
-})
-
-test('selectorUsed: rightmost class is the subject', () => {
-  assert.equal(selectorUsed('.nav .link', new Set(['link'])), true)
-  assert.equal(selectorUsed('.nav .link', new Set(['nav'])), false)
-  assert.equal(selectorUsed('.btn:hover', new Set(['btn'])), true)
-})
-
-test('extractUsedClasses: finds class attributes and hyphenated JS strings', () => {
-  const used = extractUsedClasses(
-    ['<div class="hero card">'],
-    [`el.classList.add('ui-btn--active')`]
-  )
-  assert.ok(used.has('hero'))
-  assert.ok(used.has('card'))
-  assert.ok(used.has('ui-btn--active'))
-})
-
-test('minifyCss: calc() expressions keep their operator spacing', () => {
-  const out = minifyCss(`.x { width: calc(100% - 2rem); }`)
-  assert.ok(out.includes('calc(100% - 2rem)'), `calc broken: ${out}`)
-})
-
-// ---------------------------------------------------------------------------
-// Runtime state classes — classList arguments
-// ---------------------------------------------------------------------------
-// Regression: the JS string scan only keeps hyphenated names (to avoid keeping
-// every English word), so runtime state classes like classList.add('open') were
-// never collected — and selectorUsed checks the rightmost class token, so
-// `.docs-sidebar.open { … }` was purged from production CSS. The mobile docs
-// hamburger toggled the class, but the rule that slides the sidebar in was gone.
-
-test('classList method arguments are collected regardless of hyphens', () => {
-  const used = extractUsedClasses([], [
-    `sidebar.classList.add('open')`,
-    `overlay.classList.remove("visible")`,
-    `el.classList.toggle('active', isOn)`,
-    `el.classList.replace('open', 'closed')`,
-  ])
-  for (const cls of ['open', 'visible', 'active', 'closed']) {
-    assert.ok(used.has(cls), `Expected classList arg "${cls}" to be collected`)
-  }
-})
-
-test('multiple classList arguments in one call are all collected', () => {
-  const used = extractUsedClasses([], [`el.classList.add('one', 'two-x', 'three')`])
-  for (const cls of ['one', 'two-x', 'three']) assert.ok(used.has(cls), cls)
-})
-
-// Regression: class name immediately followed by ${ (no space before the expression)
-// was not extracted — "saved-palette${...}" yielded "saved-palette${expanded" as a
-// single token, so the rule was silently purged in prod while dev (no purging) looked fine.
-test('class name immediately before ${ is extracted correctly', () => {
-  const js = [
-    // No space before ${ — the broken pattern
-    `const v = \`<div class="saved-palette\${expanded ? ' saved-palette--expanded' : ''}"></div>\``,
-    // Multiple static classes, last one butts into ${
-    `const v = \`<button class="btn btn--primary\${loading ? ' btn--loading' : ''}"></button>\``,
-  ]
-  const used = extractUsedClasses([], js)
-  for (const cls of ['saved-palette', 'btn', 'btn--primary']) {
-    assert.ok(used.has(cls), `Expected "${cls}" to be extracted but it was missing`)
-  }
-})
-
-test('runtime-toggled compound rule survives the purge', () => {
-  const css = `.docs-sidebar { transform: translateX(-100%); }\n.docs-sidebar.open { transform: translateX(0); }\n.unused { color: red; }`
-  const used = extractUsedClasses(
-    [`<aside class="docs-sidebar">`],
-    [`document.querySelector('.docs-sidebar').classList.add('open')`]
-  )
-  const out = purgeCss(css, used)
-  assert.ok(out.includes('.docs-sidebar.open'), `Compound state rule was purged: ${out}`)
-  assert.ok(!out.includes('.unused'), 'Unused rule should still be purged')
-})