@invisibleloop/pulse 0.20.10 → 0.20.19

package/src/cli/stamp.js

@@ -0,0 +1,102 @@
+/**
+ * Pulse — verification stamp (shared logic)
+ *
+ * Writes .pulse-verified to clear the stop-hook verification gate. Used by
+ * both pulse_stamp (MCP tool, for an agent) and `pulse stamp` (CLI command,
+ * for a human). Neither wraps the other — both call writeStamp().
+ *
+ * In full mode (route + mode: 'full'), refuses to stamp unless a Lighthouse
+ * report was actually saved via `pulse save-report` in the last 10 minutes
+ * — a real Lighthouse run that passed the score bar but was never saved
+ * leaves nothing for `pulse report-server` or a dashboard to show. This is
+ * a mechanized version of a check that used to be prose-only in verify.md
+ * and was found (via a real user report) to be silently skipped: /verify
+ * completed and reported scores in the conversation, but nothing ever
+ * landed in .pulse/reports/.
+ */
+
+import fs   from 'fs'
+import path from 'path'
+import { urlToSlug }       from './report.js'
+import { resolveEntries }  from './diagnose.js'
+
+const STAMP_REPORT_WINDOW_MS = 10 * 60 * 1000 // a report older than this wasn't from this /verify run
+
+/**
+ * @param {string} root
+ * @param {{ route?: string, mode?: 'full'|'quick' }} [opts]
+ * @returns {{ stamped: boolean, refused: boolean, reason: string|null, resolvedCount: number, ts: string|null }}
+ *   stamped: whether .pulse-verified was actually written
+ *   refused: true if this was a policy refusal (missing report) — false if a real write error
+ *   reason: why it didn't stamp, when stamped is false (null otherwise)
+ *   resolvedCount: error-journal entries auto-resolved for `route` (0 if no route passed)
+ *   ts: the stamp's unix-seconds timestamp, when stamped is true (null otherwise)
+ */
+export function writeStamp(root, { route, mode } = {}) {
+  if (route && mode === 'full') {
+    const slug = urlToSlug(route)
+    const reportDir = path.join(root, '.pulse', 'reports', slug)
+    let recentReport = false
+    try {
+      const files = fs.readdirSync(reportDir).filter(f => f.endsWith('.json'))
+      recentReport = files.some(f => {
+        const stat = fs.statSync(path.join(reportDir, f))
+        return Date.now() - stat.mtimeMs < STAMP_REPORT_WINDOW_MS
+      })
+    } catch { /* reportDir doesn't exist — recentReport stays false */ }
+
+    if (!recentReport) {
+      return {
+        stamped: false,
+        refused: true,
+        reason: `No Lighthouse report saved for "${route}" in the last 10 minutes. Full /verify requires ` +
+          `pulse save-report --url "http://localhost:3001${route}" --data '{"scores":{...},"metrics":{...}}' ` +
+          `(run from the project root) for BOTH the desktop and mobile Lighthouse runs before stamping.`,
+        resolvedCount: 0,
+        ts: null,
+      }
+    }
+  }
+
+  const stampPath = path.join(root, '.pulse-verified')
+  const ts = String(Math.floor(Date.now() / 1000))
+  try {
+    fs.writeFileSync(stampPath, ts, 'utf8')
+  } catch (err) {
+    return {
+      stamped: false,
+      refused: false,
+      reason: `Error writing .pulse-verified: ${err.message}. Fallback: run \`date +%s > .pulse-verified\` in Bash.`,
+      resolvedCount: 0,
+      ts: null,
+    }
+  }
+
+  let resolvedCount = 0
+  if (route) {
+    const { count } = resolveEntries(root, { route })
+    resolvedCount = count
+  }
+
+  return { stamped: true, refused: false, reason: null, resolvedCount, ts }
+}
+
+/**
+ * Format a writeStamp() result as human-readable text.
+ * @param {ReturnType<typeof writeStamp>} result
+ * @param {{ agentFacing?: boolean }} [opts]
+ */
+export function formatStampResult(result, { agentFacing = true } = {}) {
+  if (!result.stamped) {
+    const prefix = result.refused ? 'Refusing to stamp' : 'Failed to stamp'
+    return agentFacing && result.refused
+      ? `${prefix}: ${result.reason}\n\nRun it now with the real numbers from your Lighthouse results, then call pulse_stamp again.`
+      : `${prefix}: ${result.reason}`
+  }
+  const resolvedNote = result.resolvedCount > 0
+    ? ` ${result.resolvedCount} error-journal entr${result.resolvedCount === 1 ? 'y' : 'ies'} marked resolved.`
+    : ''
+  return agentFacing
+    ? `✓ .pulse-verified written (${result.ts}). Stop hook cleared — session can end.${resolvedNote}`
+    : `✓ .pulse-verified written (${result.ts}).${resolvedNote}`
+}

package/src/cli/stamp.test.js

@@ -0,0 +1,149 @@
+/**
+ * Pulse — stamp.js tests
+ * run: node src/cli/stamp.test.js
+ *
+ * Shared logic behind pulse_stamp (MCP tool) and `pulse stamp` (CLI
+ * command). Regression coverage: a real Lighthouse run that passed the
+ * score bar in a /verify session was found to be silently never saved via
+ * `pulse save-report` — prose-only documentation for that step wasn't
+ * enough, so full-mode pulse_stamp now refuses to write the stamp unless
+ * it finds real evidence a report was saved.
+ */
+
+import { test }   from 'node:test'
+import assert     from 'node:assert/strict'
+import fs         from 'node:fs'
+import os         from 'node:os'
+import path       from 'node:path'
+import { writeStamp, formatStampResult } from './stamp.js'
+
+function tmpProject() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-stamp-test-'))
+}
+
+function writeReport(root, slug, { ageMs = 0 } = {}) {
+  const dir = path.join(root, '.pulse', 'reports', slug)
+  fs.mkdirSync(dir, { recursive: true })
+  const file = path.join(dir, `${Date.now()}.json`)
+  fs.writeFileSync(file, JSON.stringify({ timestamp: new Date().toISOString(), scores: {} }))
+  if (ageMs > 0) {
+    const past = new Date(Date.now() - ageMs)
+    fs.utimesSync(file, past, past)
+  }
+  return file
+}
+
+// ── Quick mode / no route ───────────────────────────────────────────────
+
+test('writeStamp with no route stamps unconditionally', () => {
+  const root = tmpProject()
+  const result = writeStamp(root)
+  assert.equal(result.stamped, true)
+  assert.equal(fs.existsSync(path.join(root, '.pulse-verified')), true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('writeStamp in quick mode stamps even with no saved report', () => {
+  const root = tmpProject()
+  const result = writeStamp(root, { route: '/dashboard', mode: 'quick' })
+  assert.equal(result.stamped, true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+// ── Full mode — the actual regression this fixes ────────────────────────
+
+test('writeStamp in full mode refuses when no report was ever saved for the route', () => {
+  const root = tmpProject()
+  const result = writeStamp(root, { route: '/dashboard', mode: 'full' })
+  assert.equal(result.stamped, false)
+  assert.equal(result.refused, true)
+  assert.match(result.reason, /No Lighthouse report saved/)
+  assert.equal(fs.existsSync(path.join(root, '.pulse-verified')), false, 'must not write the stamp file at all')
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('writeStamp in full mode refuses when the only report is older than the window', () => {
+  const root = tmpProject()
+  writeReport(root, 'dashboard', { ageMs: 20 * 60 * 1000 }) // 20 min old
+  const result = writeStamp(root, { route: '/dashboard', mode: 'full' })
+  assert.equal(result.stamped, false)
+  assert.equal(result.refused, true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('writeStamp in full mode stamps when a recent report exists for the route', () => {
+  const root = tmpProject()
+  writeReport(root, 'dashboard')
+  const result = writeStamp(root, { route: '/dashboard', mode: 'full' })
+  assert.equal(result.stamped, true)
+  assert.equal(result.refused, false)
+  assert.equal(fs.existsSync(path.join(root, '.pulse-verified')), true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('writeStamp full mode checks the same slug pulse save-report would use for this route', () => {
+  const root = tmpProject()
+  // Root route '/' slugs to 'home' — same as report.js's urlToSlug.
+  writeReport(root, 'home')
+  const result = writeStamp(root, { route: '/', mode: 'full' })
+  assert.equal(result.stamped, true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('a report saved for a different route does not satisfy the check', () => {
+  const root = tmpProject()
+  writeReport(root, 'about') // saved for /about, not /dashboard
+  const result = writeStamp(root, { route: '/dashboard', mode: 'full' })
+  assert.equal(result.stamped, false)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+// ── Error-journal auto-resolve ───────────────────────────────────────────
+
+test('writeStamp with a route marks unresolved error-journal entries for that route resolved', () => {
+  const root = tmpProject()
+  fs.mkdirSync(path.join(root, '.pulse'), { recursive: true })
+  fs.writeFileSync(path.join(root, '.pulse', 'errors.json'), JSON.stringify([
+    { id: '1', ts: '2026-01-01T00:00:00.000Z', route: '/dashboard', phase: 'view', message: 'x', stack: '', resolved: false },
+    { id: '2', ts: '2026-01-01T00:00:00.000Z', route: '/other',     phase: 'view', message: 'y', stack: '', resolved: false },
+  ]))
+
+  const result = writeStamp(root, { route: '/dashboard' })
+  assert.equal(result.stamped, true)
+  assert.equal(result.resolvedCount, 1)
+
+  const entries = JSON.parse(fs.readFileSync(path.join(root, '.pulse', 'errors.json'), 'utf8'))
+  assert.equal(entries.find(e => e.id === '1').resolved, true)
+  assert.equal(entries.find(e => e.id === '2').resolved, false, 'must not resolve entries for a different route')
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+// ── formatStampResult ────────────────────────────────────────────────────
+
+test('formatStampResult agentFacing:true on refusal tells the agent to retry pulse_stamp', () => {
+  const output = formatStampResult({ stamped: false, refused: true, reason: 'no report', resolvedCount: 0, ts: null }, { agentFacing: true })
+  assert.match(output, /Refusing to stamp/)
+  assert.match(output, /call pulse_stamp again/)
+})
+
+test('formatStampResult agentFacing:false (CLI) omits the pulse_stamp-specific retry phrasing', () => {
+  const output = formatStampResult({ stamped: false, refused: true, reason: 'no report', resolvedCount: 0, ts: null }, { agentFacing: false })
+  assert.match(output, /Refusing to stamp/)
+  assert.doesNotMatch(output, /pulse_stamp/, 'CLI output must not reference the MCP tool name pulse_stamp')
+})
+
+test('formatStampResult distinguishes a real write failure from a policy refusal', () => {
+  const output = formatStampResult({ stamped: false, refused: false, reason: 'disk full', resolvedCount: 0, ts: null }, { agentFacing: true })
+  assert.match(output, /Failed to stamp/)
+  assert.doesNotMatch(output, /Refusing to stamp/)
+})
+
+test('formatStampResult on success reports resolved count when nonzero', () => {
+  const output = formatStampResult({ stamped: true, refused: false, reason: null, resolvedCount: 2, ts: '123' }, { agentFacing: true })
+  assert.match(output, /2 error-journal entries marked resolved/)
+})
+
+test('formatStampResult on success says nothing about resolving when count is zero', () => {
+  const output = formatStampResult({ stamped: true, refused: false, reason: null, resolvedCount: 0, ts: '123' }, { agentFacing: true })
+  assert.doesNotMatch(output, /marked resolved/)
+})

package/src/cli/start.js

@@ -43,6 +43,7 @@ if (!fs.existsSync(manifestPath)) {
 
 let port         = portArg !== -1 ? parseInt(args[portArg + 1], 10) : null
 let defaultCache = null
+let staticCache  = null
 let csp          = null
 let passthrough  = {}
 
@@ -55,6 +56,7 @@ if (fs.existsSync(configPath)) {
     const mod    = await import(configPath)
     port         = port || mod.default?.port || null
     defaultCache = mod.default?.defaultCache ?? null
+    staticCache  = mod.default?.staticCache ?? null
     csp          = mod.default?.csp ?? null
     for (const key of PASSTHROUGH_OPTIONS) {
       if (mod.default?.[key] !== undefined) passthrough[key] = mod.default[key]
@@ -62,8 +64,18 @@ if (fs.existsSync(configPath)) {
   } catch { /* ignore */ }
 }
 
-// Render (and other PaaS platforms) inject PORT — always takes precedence
-port = parseInt(process.env.PORT, 10) || port || 3000
+// Render (and other PaaS platforms) inject PORT — always takes precedence, even
+// over an explicit --port flag. This is correct for real deployment, but it also
+// means a PORT env var set on a local dev machine for unrelated reasons (common
+// in sandboxes, CI runners, some shell profiles) silently overrides the local
+// convention of `pulse start --port 3001` documented for /verify — with no error,
+// just a server on a port nobody asked for. Surface it instead of staying silent.
+const requestedPort = port
+const envPort       = parseInt(process.env.PORT, 10) || null
+port = envPort || port || 3000
+if (envPort && requestedPort && envPort !== requestedPort) {
+  console.error(`⚠  PORT=${envPort} in the environment overrides --port ${requestedPort} — starting on ${envPort} instead.\n   Unset PORT, or don't rely on --port locally while it's set.\n`)
+}
 
 // ---------------------------------------------------------------------------
 // Start
@@ -84,6 +96,7 @@ createServer(specs, {
   stream:       true,
   staticDir:    PUBLIC_DIR,
   defaultCache,
+  staticCache,
   ...(store ? { store } : {}),
   ...(csp ? { csp } : {}),
   ...passthrough,

package/src/cli/validate.js

@@ -0,0 +1,184 @@
+/**
+ * Pulse — Spec validation (shared logic)
+ *
+ * The single source of truth for validating a Pulse spec's content. Used by
+ * both pulse_validate (the MCP tool, for an agent) and `pulse validate` (the
+ * CLI command, for a human running it directly). Neither wraps the other —
+ * they both call validateContent() here, so the two paths can never drift
+ * the way the checklist/workflow docs did before this file existed.
+ *
+ * Returns plain data — { valid, output, sourceWarnings } — with no MCP
+ * protocol coupling (no text()-wrapping) and no audience-specific framing
+ * (no "ask the user for design approval" — that's for the MCP tool's own
+ * wrapper to add, since a human at the terminal doesn't need it phrased at
+ * them that way).
+ */
+
+import fs   from 'fs'
+import path from 'path'
+import { execFileSync } from 'child_process'
+
+const PROP_ALIASES = [
+  { component: 'nav()',    wrong: 'brand',       correct: 'logo',    note: 'The nav logo is set with the `logo` prop, not `brand`.' },
+  { component: 'nav()',    wrong: 'actions',     correct: 'action',  note: 'nav() takes a single `action` string (HTML), not an array.' },
+  { component: 'footer()', wrong: 'items',       correct: 'links',   note: 'footer() top-level links use `links: [{ label, href }]`, not `items`.' },
+  { component: 'footer()', wrong: 'nav',         correct: 'links',   note: 'footer() links prop is `links`, not `nav`.' },
+  { component: 'input()',  wrong: 'autocomplete', correct: 'attrs: { autocomplete }', note: 'HTML attributes not in the component API (autocomplete, min, max, step, pattern, inputmode, etc.) go inside the `attrs` object: input({ attrs: { autocomplete: "email" } }).' },
+  { component: 'input()',  wrong: 'maxlength',   correct: 'attrs: { maxlength }',     note: 'HTML attributes go inside `attrs`: input({ attrs: { maxlength: "100" } }).' },
+  { component: 'input()',  wrong: 'minlength',   correct: 'attrs: { minlength }',     note: 'HTML attributes go inside `attrs`: input({ attrs: { minlength: "2" } }).' },
+  { component: 'input()',  wrong: 'pattern',     correct: 'attrs: { pattern }',       note: 'HTML attributes go inside `attrs`: input({ attrs: { pattern: "[0-9]+" } }).' },
+]
+
+const EXTERNAL_IMG_HOSTS = [
+  {
+    pattern: /https?:\/\/images\.unsplash\.com/,
+    host:    'images.unsplash.com',
+    entry:   'https://images.unsplash.com',
+    cookieWarning: true,
+    name: 'Unsplash',
+  },
+  {
+    pattern: /https?:\/\/(?:fastly\.)?picsum\.photos/,
+    host:    'picsum.photos',
+    entry:   'https://picsum.photos https://fastly.picsum.photos',
+    cookieWarning: false,
+    name: 'picsum',
+  },
+  {
+    pattern: /https?:\/\/res\.cloudinary\.com/,
+    host:    'res.cloudinary.com',
+    entry:   'https://res.cloudinary.com',
+    cookieWarning: true,
+    name: 'Cloudinary',
+  },
+  {
+    pattern: /https?:\/\/cdn\.shopify\.com/,
+    host:    'cdn.shopify.com',
+    entry:   'https://cdn.shopify.com',
+    cookieWarning: false,
+    name: 'Shopify CDN',
+  },
+]
+
+/**
+ * Validate spec source content against the schema plus a set of source-level
+ * structural checks (wrong component prop names, un-CSP'd external image hosts).
+ *
+ * @param {string} content - the spec file's source text
+ * @param {string} root - project root, used to find pulse.config.js
+ * @param {string} [tmpDir] - directory to write the temp validation file into,
+ *   so relative imports in the spec resolve correctly. Defaults to <root>/src/pages.
+ * @returns {Promise<{ valid: boolean, timedOut: boolean, schemaOutput: string, sourceWarnings: string[] }>}
+ */
+export async function validateContent(content, root, tmpDir = null) {
+  tmpDir = tmpDir || path.join(root, 'src', 'pages')
+
+  const sourceWarnings = []
+
+  // Component prop alias checks — flag known wrong prop names
+  for (const { component, wrong, correct, note } of PROP_ALIASES) {
+    const fnName = component.replace('()', '')
+    const re = new RegExp(`${fnName}\\s*\\(\\s*\\{([^}]*)\\b${wrong}\\s*:`, 'g')
+    let m
+    while ((m = re.exec(content)) !== null) {
+      // attrs: { … } is the correct placement for HTML attributes — a match
+      // that falls inside an open attrs block is the recommended pattern,
+      // not a mistake.
+      if (/attrs\s*:\s*\{[^}]*$/.test(m[1])) continue
+      sourceWarnings.push(`"${wrong}" is not a recognised prop for ${component} — did you mean "${correct}"? ${note}`)
+      break
+    }
+  }
+
+  // External image URL check — warn if the spec references an external image
+  // host not whitelisted in pulse.config.js's CSP img-src.
+  const configPath = path.join(root, 'pulse.config.js')
+  let configImgSrc = ''
+  if (fs.existsSync(configPath)) {
+    try { configImgSrc = fs.readFileSync(configPath, 'utf8') } catch { /* ignore */ }
+  }
+  for (const { pattern, host, entry, cookieWarning, name } of EXTERNAL_IMG_HOSTS) {
+    // Config match is by HOST, not full URL — CSP sources are valid without a
+    // scheme, so requiring https?:// in the config caused false positives.
+    if (pattern.test(content) && !configImgSrc.includes(host)) {
+      const cookieNote = cookieWarning
+        ? `\n  ⚠ ${name} sets tracking cookies that fail Lighthouse Best Practices regardless of CSP. For production, download images to public/images/ instead of linking to ${name} directly.`
+        : ''
+      sourceWarnings.push(
+        `External image host detected (${name}). Add it to csp.img-src in pulse.config.js before running Lighthouse:\n` +
+        `    csp: { 'img-src': ['${entry}'] }\n` +
+        `  Without this, images will be blocked and Lighthouse Best Practices will fail.${cookieNote}`
+      )
+    }
+  }
+
+  fs.mkdirSync(tmpDir, { recursive: true })
+  const tmpFile = path.join(tmpDir, `.pulse-validate-${Date.now()}.mjs`)
+  try {
+    fs.writeFileSync(tmpFile, content, 'utf8')
+
+    const validatorScript = new URL('../mcp/validate-worker.js', import.meta.url).pathname
+    let schemaOutput
+    let timedOut = false
+    try {
+      schemaOutput = execFileSync(process.execPath, [validatorScript, tmpFile], {
+        timeout: 10_000,
+        encoding: 'utf8',
+      }).trim()
+    } catch (err) {
+      timedOut = err.killed || err.signal === 'SIGTERM'
+      schemaOutput = timedOut
+        ? 'Invalid: validation timed out — spec may have a hanging import or infinite loop'
+        : `Invalid: could not parse — ${err.stdout || err.message}`
+    }
+
+    const valid = schemaOutput.startsWith('Valid ✓') && !schemaOutput.includes('Invalid')
+
+    return { valid, timedOut, schemaOutput, sourceWarnings }
+  } finally {
+    try { fs.unlinkSync(tmpFile) } catch { /* ignore */ }
+  }
+}
+
+/**
+ * Validate a spec by file path — reads the file, validates from its own
+ * directory so relative imports resolve correctly for pages in subdirectories.
+ *
+ * @param {string} file - absolute path to the spec file
+ * @param {string} root - project root
+ * @returns {Promise<{ valid: boolean, timedOut: boolean, schemaOutput: string, sourceWarnings: string[] } | { error: string }>}
+ */
+export async function validateFile(file, root) {
+  if (!fs.existsSync(file)) {
+    return { error: `File not found: ${file}` }
+  }
+  const content = fs.readFileSync(file, 'utf8')
+  return validateContent(content, root, path.dirname(file))
+}
+
+/**
+ * Format a validation result as human-readable text — shared rendering for
+ * both the CLI (printed to stdout) and the MCP tool (wrapped in text()).
+ * `nextSteps`, when true, appends the agent-facing browser-check reminder;
+ * a human running this from the terminal doesn't need that, so the CLI
+ * command omits it.
+ */
+export function formatValidationResult(result, { nextSteps = false } = {}) {
+  if (result.error) return result.error
+
+  let output = result.schemaOutput
+  if (result.sourceWarnings.length > 0) {
+    const propNotes = result.sourceWarnings.map(w => `  ⚠ ${w}`).join('\n')
+    if (output.startsWith('Valid ✓')) {
+      output = output.replace('Valid ✓', 'Valid ✓ — but fix these issues:') + '\n' + propNotes
+    } else {
+      output = output + '\n' + propNotes
+    }
+  }
+
+  if (nextSteps && result.valid && result.sourceWarnings.length === 0) {
+    output += '\n\n---\n**Next: browser check sequence** (do not skip)\n1. `pulse_fetch_page` → screenshot\n2. **New build?** Show screenshot to user and ask for design approval before continuing\n3. Once approved (or edit/fix): `pulse_design_review` (if intake ran) → `pulse_layout_review <url>` → `/verify`\nDo not run Lighthouse before the user approves the design. Do not report done until `/verify` passes.'
+  }
+
+  return output
+}

package/src/cli/validate.test.js

@@ -0,0 +1,153 @@
+/**
+ * Pulse — validate.js tests
+ * run: node src/cli/validate.test.js
+ *
+ * This is the shared logic behind both pulse_validate (MCP tool) and
+ * `pulse validate` (CLI command) — a real end-to-end test here is the
+ * guarantee that a human running the CLI gets the exact same check an
+ * agent gets, since both call into this same module.
+ */
+
+import { test }   from 'node:test'
+import assert     from 'node:assert/strict'
+import fs         from 'node:fs'
+import os         from 'node:os'
+import path       from 'node:path'
+import { validateContent, validateFile, formatValidationResult } from './validate.js'
+
+function tmpProject() {
+  const root = fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-validate-test-'))
+  fs.mkdirSync(path.join(root, 'src', 'pages'), { recursive: true })
+  return root
+}
+
+test('a valid spec with no meta.theme passes with a warning', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  meta: { title: 't', description: 'd' },\n  view: () => '<main id="main-content">x</main>',\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.valid, true)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('an invalid route (no leading slash) fails validation', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: 'no-slash',\n  view: () => '',\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.valid, false)
+  assert.match(result.schemaOutput, /must start with "\/"/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('prop-alias check flags nav({ brand }) and suggests logo', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  view: () => nav({ brand: 'Site', links: [] }),\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.sourceWarnings.length, 1)
+  assert.match(result.sourceWarnings[0], /"brand" is not a recognised prop for nav\(\)/)
+  assert.match(result.sourceWarnings[0], /did you mean "logo"/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('prop-alias check does NOT flag autocomplete correctly placed inside attrs', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  view: () => input({ attrs: { autocomplete: 'email' } }),\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.sourceWarnings.length, 0,
+    `Expected no warnings for the recommended attrs pattern, got: ${JSON.stringify(result.sourceWarnings)}`)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('external image host warning fires when unlisted in pulse.config.js CSP', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  view: () => \`<img src="https://images.unsplash.com/photo-1">\`,\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.sourceWarnings.length, 1)
+  assert.match(result.sourceWarnings[0], /External image host detected \(Unsplash\)/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('external image host warning is suppressed when the bare host is in pulse.config.js', async () => {
+  const root = tmpProject()
+  fs.writeFileSync(path.join(root, 'pulse.config.js'),
+    `export default { csp: { 'img-src': ['images.unsplash.com'] } }`)
+  const content = `export default {\n  route: '/x',\n  view: () => \`<img src="https://images.unsplash.com/photo-1">\`,\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.sourceWarnings.length, 0,
+    `Expected no warning when the bare host is already configured, got: ${JSON.stringify(result.sourceWarnings)}`)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('inline <script> warning does NOT fire for external scripts with a src', async () => {
+  const root = tmpProject()
+  const view = [
+    '<script src="/menu.js" defer></script>',
+    '<script defer src="/a.js"></script>',
+    '<script type="module" src=\'/b.js\'></script>',
+  ].join('')
+  const content = `export default {\n  route: '/x',\n  view: () => \`<main id="main-content">${view}</main>\`,\n}`
+  const result = await validateContent(content, root)
+  assert.equal(result.valid, true)
+  assert.doesNotMatch(result.schemaOutput, /Inline <script>/,
+    `Expected no inline-script warning for external scripts, got: ${result.schemaOutput}`)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('inline <script> warning still fires for real inline scripts', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  view: () => \`<main id="main-content"><script>alert(1)</script></main>\`,\n}`
+  const result = await validateContent(content, root)
+  assert.match(result.schemaOutput, /Inline <script> block detected/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('inline <script> warning still fires when only data-src is present', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  view: () => \`<main id="main-content"><script data-src="/a.js">alert(1)</script></main>\`,\n}`
+  const result = await validateContent(content, root)
+  assert.match(result.schemaOutput, /Inline <script> block detected/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('validateFile resolves relative imports from the spec\'s own directory', async () => {
+  const root = tmpProject()
+  fs.mkdirSync(path.join(root, 'src', 'components'), { recursive: true })
+  fs.mkdirSync(path.join(root, 'src', 'pages', 'news'), { recursive: true })
+  fs.writeFileSync(path.join(root, 'src', 'components', 'layout.js'),
+    `export const layout = ({ content }) => content`)
+  const specPath = path.join(root, 'src', 'pages', 'news', 'index.js')
+  fs.writeFileSync(specPath,
+    `import { layout } from '../../components/layout.js'\nexport default {\n  route: '/news',\n  meta: { title: 't', description: 'd' },\n  view: () => layout({ content: '<main id="main-content">news</main>' }),\n}`)
+  const result = await validateFile(specPath, root)
+  assert.equal(result.valid, true,
+    `Expected relative import to resolve from the spec's own directory, got: ${JSON.stringify(result)}`)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('validateFile returns an error object for a missing file', async () => {
+  const root = tmpProject()
+  const result = await validateFile(path.join(root, 'does-not-exist.js'), root)
+  assert.match(result.error, /File not found/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatValidationResult with nextSteps: true appends the agent browser-check reminder', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  meta: { title: 't', description: 'd', theme: 'dark' },\n  view: () => '<main id="main-content">x</main>',\n}`
+  const result = await validateContent(content, root)
+  const withNextSteps = formatValidationResult(result, { nextSteps: true })
+  const without = formatValidationResult(result, { nextSteps: false })
+  assert.match(withNextSteps, /browser check sequence/)
+  assert.doesNotMatch(without, /browser check sequence/,
+    'CLI output (nextSteps: false, the default) must not carry agent-only framing like "ask the user for design approval"')
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatValidationResult merges source warnings into a clean schema pass', async () => {
+  const root = tmpProject()
+  const content = `export default {\n  route: '/x',\n  meta: { title: 't', description: 'd', theme: 'dark' },\n  view: () => nav({ brand: 'x', links: [] }),\n}`
+  const result = await validateContent(content, root)
+  const output = formatValidationResult(result)
+  assert.match(output, /Valid ✓ — but fix these issues:/)
+  assert.match(output, /did you mean "logo"/)
+  fs.rmSync(root, { recursive: true, force: true })
+})