@invisibleloop/pulse 0.20.11 → 0.20.20

package/src/cli/diagnose.test.js

@@ -0,0 +1,124 @@
+/**
+ * Pulse — diagnose.js tests
+ * run: node src/cli/diagnose.test.js
+ *
+ * Shared logic behind pulse_diagnose/pulse_resolve_error (MCP tools) and
+ * `pulse diagnose`/`pulse resolve-error` (CLI commands) — a human running
+ * the CLI must see the exact same journal an agent sees.
+ */
+
+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 { readJournal, formatJournal, resolveEntries, formatResolveResult } from './diagnose.js'
+
+function tmpProject() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'pulse-diagnose-test-'))
+}
+
+function writeJournal(root, entries) {
+  fs.mkdirSync(path.join(root, '.pulse'), { recursive: true })
+  fs.writeFileSync(path.join(root, '.pulse', 'errors.json'), JSON.stringify(entries, null, 2))
+}
+
+function sampleEntry(overrides = {}) {
+  return {
+    id: 'abc-123', ts: '2026-01-01T00:00:00.000Z', route: '/dashboard',
+    phase: 'view', message: 'boom', stack: 'Error: boom', resolved: false,
+    ...overrides,
+  }
+}
+
+test('readJournal reports exists:false when no journal file exists', () => {
+  const root = tmpProject()
+  const result = readJournal(root)
+  assert.equal(result.exists, false)
+  assert.deepEqual(result.entries, [])
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('readJournal returns unresolved entries by default', () => {
+  const root = tmpProject()
+  writeJournal(root, [sampleEntry({ id: 'a', resolved: false }), sampleEntry({ id: 'b', resolved: true })])
+  const result = readJournal(root)
+  assert.equal(result.entries.length, 1)
+  assert.equal(result.entries[0].id, 'a')
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('readJournal with includeResolved:true returns both', () => {
+  const root = tmpProject()
+  writeJournal(root, [sampleEntry({ id: 'a', resolved: false }), sampleEntry({ id: 'b', resolved: true })])
+  const result = readJournal(root, { includeResolved: true })
+  assert.equal(result.entries.length, 2)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('readJournal filters by route', () => {
+  const root = tmpProject()
+  writeJournal(root, [
+    sampleEntry({ id: 'a', route: '/dashboard' }),
+    sampleEntry({ id: 'b', route: '/other' }),
+  ])
+  const result = readJournal(root, { route: '/dashboard' })
+  assert.equal(result.entries.length, 1)
+  assert.equal(result.entries[0].id, 'a')
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatJournal reports a clean message when nothing is recorded', () => {
+  const root = tmpProject()
+  const result = readJournal(root)
+  assert.match(formatJournal(result), /does not exist/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatJournal includes the route, phase, message, and stack for each entry', () => {
+  const root = tmpProject()
+  writeJournal(root, [sampleEntry()])
+  const result = readJournal(root)
+  const output = formatJournal(result)
+  assert.match(output, /\/dashboard/)
+  assert.match(output, /view/)
+  assert.match(output, /boom/)
+  assert.match(output, /Error: boom/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('resolveEntries by id marks only the matching entry', () => {
+  const root = tmpProject()
+  writeJournal(root, [sampleEntry({ id: 'a' }), sampleEntry({ id: 'b' })])
+  const result = resolveEntries(root, { id: 'a' })
+  assert.equal(result.count, 1)
+  const after = JSON.parse(fs.readFileSync(path.join(root, '.pulse', 'errors.json'), 'utf8'))
+  assert.equal(after.find(e => e.id === 'a').resolved, true)
+  assert.equal(after.find(e => e.id === 'b').resolved, false)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('resolveEntries by route marks every unresolved entry on that route', () => {
+  const root = tmpProject()
+  writeJournal(root, [
+    sampleEntry({ id: 'a', route: '/x' }),
+    sampleEntry({ id: 'b', route: '/x' }),
+    sampleEntry({ id: 'c', route: '/y' }),
+  ])
+  const result = resolveEntries(root, { route: '/x' })
+  assert.equal(result.count, 2)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('resolveEntries with neither id nor route returns an error', () => {
+  const root = tmpProject()
+  const result = resolveEntries(root, {})
+  assert.match(result.error, /pass either id or route/)
+  fs.rmSync(root, { recursive: true, force: true })
+})
+
+test('formatResolveResult reports the count or "no matching entries"', () => {
+  assert.match(formatResolveResult({ count: 2, error: null }), /Resolved 2 entries/)
+  assert.match(formatResolveResult({ count: 1, error: null }), /Resolved 1 entry\./)
+  assert.match(formatResolveResult({ count: 0, error: null }), /No matching unresolved entries/)
+})

package/src/cli/discover.js

@@ -91,9 +91,16 @@ export async function loadPages(projectRoot, bust = 0) {
       }
 
       // Auto-set hydrate only for pages that need client-side JS.
-      // Purely SSR pages (no mutations, actions, persist) ship zero JS.
+      // Purely SSR pages (no mutations, actions, persist, store) ship zero JS.
       // spec.hydrate wins if explicitly provided.
-      const needsHydration = spec.hydrate || spec.mutations || spec.actions || spec.persist
+      //
+      // spec.store alone must count as a hydration need even with no local
+      // mutations/actions: mount() is what wires up data-store-event dispatch
+      // AND the live SSE store-push subscription (initLiveStore) — a
+      // store-only page with no client bundle would silently never receive
+      // pushStore() broadcasts and have a dead data-store-event button, with
+      // no error surfaced anywhere (server-rendered HTML looks correct).
+      const needsHydration = spec.hydrate || spec.mutations || spec.actions || spec.persist || spec.store?.length
       const hydrateUrl = needsHydration
         ? spec.hydrate || ('/src/pages/' + path.relative(
             path.join(projectRoot, 'src', 'pages'),

package/src/cli/index.js

@@ -7,6 +7,12 @@
  *   pulse dev          dev server only (no AI)
  *   pulse build        production build → public/dist/
  *   pulse start        production server (requires prior build)
+ *   pulse validate <file>  validate a spec — same check pulse_validate (MCP) runs, no agent needed
+ *   pulse diagnose [--route </path>] [--include-resolved]  read the dev-only error journal
+ *   pulse resolve-error --id <id> | --route </path>        mark error journal entries resolved
+ *   pulse stamp [--route </path>] [--full|--quick]          write .pulse-verified — same check pulse_stamp (MCP) runs
+ *   pulse check-bundles                                     inspect public/dist/ bundle contents (requires prior build)
+ *   pulse review <file> [--quick]                           run the mechanized review checklist — same check pulse_review (MCP) runs
  *   pulse update       re-copy pulse-ui.css/js from installed package → public/
  *   pulse --version    print installed version and exit
  *   pulse -v           alias for --version
@@ -18,6 +24,7 @@
 import path from 'path'
 import fs   from 'fs'
 import { scaffold } from './scaffold.js'
+import { killPulseServerOnPort } from './process-utils.js'
 
 // Extract --agent flag before routing, so it works alongside any subcommand
 const rawArgs   = process.argv.slice(2)
@@ -51,9 +58,11 @@ function isPulseProject(dir) {
 async function runDev(root) {
   const devScript  = new URL('./dev.js', import.meta.url).pathname
   const { spawn }  = await import('child_process')
+  // Forward any extra flags (e.g. --port 3002) to the dev script
+  const extraArgs  = args.slice(1)
   const proc = spawn(
     process.execPath,
-    [devScript, '--root', root],
+    [devScript, '--root', root, ...extraArgs],
     { stdio: 'inherit' }
   )
   proc.on('exit', code => process.exit(code ?? 0))
@@ -74,6 +83,124 @@ async function runBuild(root) {
   proc.on('exit', code => process.exit(code ?? 0))
 }
 
+// ---------------------------------------------------------------------------
+// pulse validate — the same check pulse_validate (MCP) runs, reachable
+// without an agent. Shares validate.js's logic exactly — never a second
+// implementation that can drift from what an agent sees.
+// ---------------------------------------------------------------------------
+
+async function runValidate(root, fileArg) {
+  const { validateFile, formatValidationResult } = await import('./validate.js')
+
+  if (!fileArg) {
+    console.error('Usage: pulse validate <file>\n  <file> is a path to a spec file, relative to the current directory or absolute.')
+    process.exit(1)
+  }
+
+  const file = path.isAbsolute(fileArg) ? fileArg : path.resolve(root, fileArg)
+  const result = await validateFile(file, root)
+  console.log(formatValidationResult(result))
+  process.exit(result.valid ? 0 : 1)
+}
+
+// ---------------------------------------------------------------------------
+// pulse diagnose / pulse resolve-error — the dev-only error journal, reachable
+// without an agent. Shares diagnose.js's logic exactly with pulse_diagnose
+// and pulse_resolve_error (MCP tools).
+// ---------------------------------------------------------------------------
+
+function flagValue(subArgs, name) {
+  const i = subArgs.indexOf(name)
+  return i !== -1 ? subArgs[i + 1] : undefined
+}
+
+async function runDiagnose(root, subArgs) {
+  const { readJournal, formatJournal } = await import('./diagnose.js')
+  const route           = flagValue(subArgs, '--route')
+  const includeResolved = subArgs.includes('--include-resolved')
+
+  const result = readJournal(root, { route, includeResolved })
+  console.log(formatJournal(result, { route, includeResolved }))
+  process.exit(result.error ? 1 : 0)
+}
+
+async function runResolveError(root, subArgs) {
+  const { resolveEntries, formatResolveResult } = await import('./diagnose.js')
+  const id    = flagValue(subArgs, '--id')
+  const route = flagValue(subArgs, '--route')
+
+  if (!id && !route) {
+    console.error('Usage: pulse resolve-error --id <id>\n   or: pulse resolve-error --route </path>')
+    process.exit(1)
+  }
+
+  const result = resolveEntries(root, { id, route })
+  console.log(formatResolveResult(result))
+  process.exit(result.error ? 1 : 0)
+}
+
+// ---------------------------------------------------------------------------
+// pulse stamp — write .pulse-verified, same check pulse_stamp (MCP) runs
+// ---------------------------------------------------------------------------
+
+async function runStamp(root, subArgs) {
+  const { writeStamp, formatStampResult } = await import('./stamp.js')
+  const route = flagValue(subArgs, '--route')
+  const mode  = subArgs.includes('--full') ? 'full' : subArgs.includes('--quick') ? 'quick' : undefined
+
+  const result = writeStamp(root, { route, mode })
+  console.log(formatStampResult(result, { agentFacing: false }))
+  process.exit(result.stamped ? 0 : 1)
+}
+
+// ---------------------------------------------------------------------------
+// pulse check-bundles — inspect production bundle contents (not just sizes),
+// reachable without an agent. Shares check-bundles.js's logic exactly with
+// pulse_check_bundles (MCP tool). Requires a prior `pulse build`.
+// ---------------------------------------------------------------------------
+
+async function runCheckBundles(root) {
+  const { checkBundles, formatBundleCheck } = await import('./check-bundles.js')
+  const result = checkBundles(root)
+  console.log(formatBundleCheck(result))
+  process.exit(result.error || result.issues.length > 0 ? 1 : 0)
+}
+
+// ---------------------------------------------------------------------------
+// pulse review — the same checklist pulse_review (MCP) runs, reachable
+// without an agent. Shares review.js's logic exactly — the report is
+// reformatted for a human reader (no "you are now a reviewer" framing,
+// no "continue to the verification workflow" — that's agent-only guidance).
+// ---------------------------------------------------------------------------
+
+async function runReview(root, subArgs) {
+  const quick = subArgs.includes('--quick')
+  const fileArg = subArgs.find(a => !a.startsWith('--'))
+
+  if (!fileArg) {
+    console.error('Usage: pulse review <file> [--quick]\n  <file> is a path to a spec file, relative to the current directory or absolute.')
+    process.exit(1)
+  }
+
+  const { runQuickReview, formatQuickReview, runFullReview, formatFullReview } = await import('./review.js')
+  const file = path.isAbsolute(fileArg) ? fileArg : path.resolve(root, fileArg)
+  if (!fs.existsSync(file)) {
+    console.error(`File not found: ${file}`)
+    process.exit(1)
+  }
+  const source = fs.readFileSync(file, 'utf8')
+
+  if (quick) {
+    const result = await runQuickReview(source, file)
+    console.log(formatQuickReview(result, { agentFacing: false }))
+    process.exit(result.issues.length > 0 ? 1 : 0)
+  } else {
+    const result = await runFullReview(source, file)
+    console.log(formatFullReview(result, { source, file, agentFacing: false }))
+    process.exit(result.validationResult.includes('✓') ? 0 : 1)
+  }
+}
+
 // ---------------------------------------------------------------------------
 // pulse (no subcommand) — scaffold or start AI session
 // ---------------------------------------------------------------------------
@@ -259,7 +386,6 @@ async function launchCopilotSession(root, mcpServerPath, spawn, os) {
 // ---------------------------------------------------------------------------
 
 async function runStop(root) {
-  const { execSync } = await import('child_process')
   let port = 3000
   const configPath = path.join(root, 'pulse.config.js')
   if (fs.existsSync(configPath)) {
@@ -268,13 +394,25 @@ async function runStop(root) {
       if (mod.default?.port) port = mod.default.port
     } catch { /* use default */ }
   }
-  try {
-    // Kill the dev server AND the local production server (dev port + 1) —
-    // pulse_build spawns the prod server detached, so without this it lingers
-    // after the session and blocks the next build's Lighthouse run.
-    execSync(`lsof -ti:${port} | xargs kill -9 2>/dev/null; lsof -ti:${port + 1} | xargs kill -9 2>/dev/null; true`, { stdio: 'inherit' })
-    console.log(`\n⚡ Servers on ports ${port} (dev) and ${port + 1} (prod) stopped.\n`)
-  } catch { /* nothing was running */ }
+  // Kill the dev server AND the local production server (dev port + 1) —
+  // pulse_build spawns the prod server detached, so without this it lingers
+  // after the session and blocks the next build's Lighthouse run. Only
+  // kills a process that's actually a Pulse server — see
+  // killPulseServerOnPort's doc comment for why: a blind lsof|kill on the
+  // port used to kill whatever else happened to be listening there.
+  const dev  = killPulseServerOnPort(port)
+  const prod = killPulseServerOnPort(port + 1)
+  const stopped = [
+    ...(dev.killed.length  ? [`${port} (dev)`]     : []),
+    ...(prod.killed.length ? [`${port + 1} (prod)`] : []),
+  ]
+  if (stopped.length > 0) console.log(`\n⚡ Server${stopped.length > 1 ? 's' : ''} on ${stopped.join(' and ')} stopped.\n`)
+  for (const skipped of [...dev.skipped, ...prod.skipped]) {
+    console.log(`⚠  Left PID ${skipped.pid} running — not a Pulse server: ${skipped.command}`)
+  }
+  if (stopped.length === 0 && dev.skipped.length === 0 && prod.skipped.length === 0) {
+    console.log('\nNothing running on those ports.\n')
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -475,6 +613,12 @@ switch (command) {
     ${c.cyan('dev')}              start the dev server
     ${c.cyan('build')}            production build  ${c.dim('→ public/dist/')}
     ${c.cyan('start')}            production server ${c.dim('(requires prior build)')}
+    ${c.cyan('validate')} ${c.dim('<file>')}   validate a spec — the same check an agent runs, without an agent
+    ${c.cyan('diagnose')}         read the dev-only error journal ${c.dim('(.pulse/errors.json)')}
+    ${c.cyan('resolve-error')}    mark error journal entries resolved
+    ${c.cyan('stamp')}            write .pulse-verified ${c.dim('[--route </path>] [--full|--quick]')}
+    ${c.cyan('check-bundles')}    inspect public/dist/ bundle contents ${c.dim('(requires prior build)')}
+    ${c.cyan('review')} ${c.dim('<file>')}     run the mechanized review checklist ${c.dim('[--quick]')}
     ${c.cyan('update')}           re-copy pulse-ui assets from installed package
 
   ${c.bold('Options:')}
@@ -503,6 +647,24 @@ switch (command) {
   case 'start':
     await runStart(CWD)
     break
+  case 'validate':
+    await runValidate(CWD, args[1])
+    break
+  case 'diagnose':
+    await runDiagnose(CWD, args.slice(1))
+    break
+  case 'resolve-error':
+    await runResolveError(CWD, args.slice(1))
+    break
+  case 'stamp':
+    await runStamp(CWD, args.slice(1))
+    break
+  case 'check-bundles':
+    await runCheckBundles(CWD)
+    break
+  case 'review':
+    await runReview(CWD, args.slice(1))
+    break
   case 'report-server':
     await runReportServer(CWD)
     break

package/src/cli/process-utils.js

@@ -0,0 +1,57 @@
+/**
+ * Pulse — process management helpers
+ *
+ * Shared between the MCP server (pulse_restart_server, pulse_build) and the
+ * CLI (`pulse stop`) — both need to free a port before starting a server,
+ * and both previously did it with a blind `lsof -ti:PORT | xargs kill -9`.
+ */
+
+import { execFileSync } from 'child_process'
+
+/** Command-line substrings that identify a process as a Pulse server. */
+export const PULSE_SERVER_MARKERS = ['cli/dev.js', 'cli/start.js', 'scripts/build.js']
+
+/**
+ * Kill only processes on `port` that are actually a Pulse dev/prod server —
+ * never an unconditional `lsof -ti:PORT | xargs kill -9`.
+ *
+ * That blind pattern used to be at every restart/build/stop call site: it
+ * kills whatever happens to be listening on the configured port, no
+ * ownership check at all. On a machine running other projects, a plain
+ * port collision (an unrelated Next.js/Vite/Rails dev server left running
+ * on 3000, say) means one Pulse command silently kills someone else's
+ * server. Found via a real user report: pulse_fetch_page returned a stale
+ * 500 from an unrelated project on port 3000, then the next
+ * pulse_restart_server call — which still ran the blind kill — coincided
+ * with the MCP connection itself dropping.
+ *
+ * Only kills a PID whose command line contains one of PULSE_SERVER_MARKERS
+ * — anything else on the port is left alone and reported back instead.
+ *
+ * @param {number} port
+ * @returns {{ killed: string[], skipped: { pid: string, command: string }[] }}
+ */
+export function killPulseServerOnPort(port) {
+  const result = { killed: [], skipped: [] }
+  let pids
+  try {
+    pids = execFileSync('sh', ['-c', `lsof -ti:${port} 2>/dev/null`], { encoding: 'utf8' })
+      .split('\n').map(s => s.trim()).filter(Boolean)
+  } catch {
+    return result // lsof found nothing — nothing to do
+  }
+  for (const pid of pids) {
+    let command = ''
+    try {
+      command = execFileSync('sh', ['-c', `ps -o command= -p ${pid} 2>/dev/null`], { encoding: 'utf8' }).trim()
+    } catch { continue } // process gone between lsof and ps — nothing to kill
+    if (!command) continue
+    if (PULSE_SERVER_MARKERS.some(marker => command.includes(marker))) {
+      try { execFileSync('sh', ['-c', `kill -9 ${pid} 2>/dev/null`]) } catch { /* already gone */ }
+      result.killed.push(pid)
+    } else {
+      result.skipped.push({ pid, command })
+    }
+  }
+  return result
+}

package/src/cli/process-utils.test.js

@@ -0,0 +1,114 @@
+/**
+ * Pulse — process-utils.js tests
+ * run: node src/cli/process-utils.test.js
+ *
+ * killPulseServerOnPort must never kill a process it didn't spawn as a
+ * Pulse dev/prod server — see its doc comment for the real user report
+ * (an unrelated Next.js dev server on port 3000 was at risk of being
+ * killed by a blind lsof|kill) this fixes.
+ */
+
+import { test }   from 'node:test'
+import assert     from 'node:assert/strict'
+import { spawn }  from 'node:child_process'
+import net        from 'node:net'
+import { killPulseServerOnPort } from './process-utils.js'
+
+/** Find a free TCP port by binding to port 0 and reading it back. */
+async function freePort() {
+  return new Promise((resolve, reject) => {
+    const srv = net.createServer()
+    srv.listen(0, () => {
+      const { port } = srv.address()
+      srv.close(() => resolve(port))
+    })
+    srv.on('error', reject)
+  })
+}
+
+/** Spawn a plain (non-Pulse) process holding a port open, for negative tests. */
+function spawnPlainListener(port) {
+  const proc = spawn(process.execPath, ['-e', `
+    const net = require('net')
+    net.createServer().listen(${port})
+    setInterval(() => {}, 1000) // keep the process alive
+  `])
+  return proc
+}
+
+async function waitUntilListening(port, maxMs = 3000) {
+  const deadline = Date.now() + maxMs
+  while (Date.now() < deadline) {
+    const alive = await new Promise(resolve => {
+      const sock = net.createConnection(port, '127.0.0.1')
+      sock.on('connect', () => { sock.destroy(); resolve(true) })
+      sock.on('error',   () => resolve(false))
+    })
+    if (alive) return true
+    await new Promise(r => setTimeout(r, 50))
+  }
+  return false
+}
+
+async function waitUntilFree(port, maxMs = 3000) {
+  const deadline = Date.now() + maxMs
+  while (Date.now() < deadline) {
+    const alive = await new Promise(resolve => {
+      const sock = net.createConnection(port, '127.0.0.1')
+      sock.on('connect', () => { sock.destroy(); resolve(true) })
+      sock.on('error',   () => resolve(false))
+    })
+    if (!alive) return true
+    await new Promise(r => setTimeout(r, 50))
+  }
+  return false
+}
+
+test('killPulseServerOnPort does not kill a process whose command line has no Pulse marker', async () => {
+  const port = await freePort()
+  const proc = spawnPlainListener(port)
+  try {
+    assert.equal(await waitUntilListening(port), true, 'test listener never came up')
+
+    const result = killPulseServerOnPort(port)
+
+    assert.equal(result.killed.length, 0, 'must not report the unrelated process as killed')
+    assert.equal(result.skipped.length, 1, 'must report exactly one skipped process')
+    assert.equal(result.skipped[0].pid, String(proc.pid))
+    // The process must actually still be alive — not just unreported as killed.
+    assert.equal(await waitUntilFree(port, 300), false, 'the unrelated process must still be listening')
+  } finally {
+    proc.kill('SIGKILL')
+  }
+})
+
+test('killPulseServerOnPort kills a process whose command line matches a Pulse marker', async () => {
+  const port = await freePort()
+  // Simulate a Pulse dev server by giving the child process's argv a marker
+  // substring (cli/dev.js) without actually running the real dev server —
+  // exercises the same ps-based matching path a real `node .../cli/dev.js`
+  // invocation would hit.
+  const proc = spawn(process.execPath, ['-e', `
+    const net = require('net')
+    net.createServer().listen(${port})
+    setInterval(() => {}, 1000)
+  `, '--', 'cli/dev.js'])
+  try {
+    assert.equal(await waitUntilListening(port), true, 'test listener never came up')
+
+    const result = killPulseServerOnPort(port)
+
+    assert.equal(result.skipped.length, 0, 'must not skip a process matching a Pulse marker')
+    assert.equal(result.killed.length, 1)
+    assert.equal(result.killed[0], String(proc.pid))
+    assert.equal(await waitUntilFree(port), true, 'the matched process must actually be killed')
+  } finally {
+    try { proc.kill('SIGKILL') } catch { /* already dead */ }
+  }
+})
+
+test('killPulseServerOnPort on a free port returns empty killed and skipped', async () => {
+  const port = await freePort()
+  const result = killPulseServerOnPort(port)
+  assert.deepEqual(result, { killed: [], skipped: [] })
+})