@invisibleloop/pulse 0.2.10 → 0.2.12

package/.claude/commands/verify.md

@@ -32,21 +32,41 @@ Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy
 
 **Same pass bar: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
 
-### 7. Console errors
+### 7. Performance
+
+Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+
+### 8. Console errors
 
 Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexpected warnings.
 
-### 8. Close the browser
+### 9. Code review
+
+Check the spec against the checklist in `.claude/pulse-checklist.md`. Work through every item. Fix anything that fails before proceeding to the next step.
+
+### 10. Close the browser
 
 Use `mcp__chrome-devtools__list_pages` to get all open pages, then call `mcp__chrome-devtools__close_page` for every page ID returned. This closes the entire browser, not just the tab. `pageId` must be a number, not a string.
 
-### 9. Report
+### 11. Write verification stamp
+
+Run:
+
+```bash
+date +%s > .pulse-verified
+```
+
+This records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+
+### 12. Report
 
 Summarise:
 - Validation: pass or fail (with errors if any)
 - Visual: what was visible in the screenshot
 - Lighthouse desktop: scores for all four categories
 - Lighthouse mobile: scores for all four categories
+- Performance: LCP and CLS values, any flagged insights
 - Console: any errors
+- Review: pass or issues found and fixed
 
-Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, and there are no console errors. Otherwise, fix and run `/verify` again.
+Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.

package/docs/src/pages/getting-started.js

@@ -78,7 +78,12 @@ Validate the email format before submitting."`, 'bash'))}
 ├── .claude/
 │   ├── CLAUDE.md            ← session instructions Claude reads on startup
 │   ├── settings.json        ← hooks: syntax checks, colour guards, package blocklist
-│   └── pulse-checklist.md   ← spec review checklist, kept in sync by Pulse
+│   ├── pulse-checklist.md   ← spec review checklist, kept in sync by Pulse
+│   └── commands/            ← slash commands available inside Claude
+│       ├── pulse-dev.md
+│       ├── pulse-stop.md
+│       ├── pulse-build.md
+│       └── pulse-start.md
 ├── package.json
 └── pulse.config.js          ← port and project settings`, 'bash'))}
       <p><code>src/pages/home.js</code> is a complete working spec — a counter with increment and decrement buttons. Open <a href="http://localhost:3000">localhost:3000</a> after running <code>/pulse-dev</code> to see it. Every new page you create goes into <code>src/pages/</code> and is discovered automatically.</p>
@@ -93,6 +98,18 @@ Validate the email format before submitting."`, 'bash'))}
 /pulse-report  # Lighthouse audit + performance report`, 'bash'))}
       <p>You can also skip the commands entirely — just describe what you want and the agent handles the rest, including starting the dev server when needed.</p>
 
+      ${section('update', 'Keeping up to date')}
+      <p>When a new version of Pulse is released, update the package and then run <code>pulse update</code> from your project root:</p>
+      ${codeBlock(highlight(`npm update @invisibleloop/pulse
+pulse update`, 'bash'))}
+      <p><code>pulse update</code> copies the latest UI assets and agent files into your project:</p>
+      <ul>
+        <li><code>public/pulse-ui.css</code> and <code>public/pulse-ui.js</code> — component library styles and behaviour</li>
+        <li><code>.claude/pulse-checklist.md</code> — spec review checklist</li>
+        <li><code>.claude/commands/</code> — slash commands</li>
+      </ul>
+      <p>Your own source files, <code>CLAUDE.md</code>, and <code>pulse.config.js</code> are never touched.</p>
+
       ${section('next-steps', 'Next steps')}
       <ul>
         <li><a href="/how-it-works">How It Works</a> — the MCP server, what the agent knows, and the full build cycle</li>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.2.10",
+  "version": "0.2.12",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.10
+0.2.12

package/src/agent/commands/verify.md

@@ -0,0 +1,72 @@
+# Verify
+
+Run the full verification loop on the current page or the page specified in $ARGUMENTS.
+
+## Steps
+
+### 1. Identify the target
+
+If $ARGUMENTS is provided, use it as the file path or route. Otherwise, identify the most recently edited spec file from context.
+
+### 2. Validate the spec
+
+Use `pulse_validate` with the spec file content. If validation fails, report every error clearly and stop — do not proceed to screenshot until the spec is valid.
+
+### 3. Check the dev server
+
+Use `pulse_fetch_page` to confirm the server is responding for the route. If it errors, use `pulse_restart_server` and retry once.
+
+### 4. Screenshot
+
+Use `mcp__chrome-devtools__navigate_page` to load the page route, then `mcp__chrome-devtools__take_screenshot` to capture the result. Describe what you see — layout, content, any obvious rendering issues.
+
+### 5. Lighthouse — desktop
+
+Run `mcp__chrome-devtools__lighthouse_audit` on the route with `{ "strategy": "desktop" }`.
+
+**Pass bar: Performance, Accessibility, Best Practices, and SEO must all be 100.** Report the actual scores. If any score is below 100, identify the failing audit(s), fix the issue, and restart from step 2.
+
+### 6. Lighthouse — mobile
+
+Run `mcp__chrome-devtools__lighthouse_audit` on the same route with `{ "strategy": "mobile" }`.
+
+**Same pass bar: all four categories must be 100.** Report the actual scores. If any score is below 100, fix and restart from step 2.
+
+### 7. Performance
+
+Navigate to the page route, then run `mcp__chrome-devtools__performance_start_trace` with `reload: true` and `autoStop: true`. Report LCP and CLS. Flag any LCP insight that suggests a fixable problem (render-blocking resources, large image load delay, etc.).
+
+### 8. Console errors
+
+Use `mcp__chrome-devtools__list_console_messages` — report any errors or unexpected warnings.
+
+### 9. Code review
+
+Check the spec against the checklist in `.claude/pulse-checklist.md`. Work through every item. Fix anything that fails before proceeding to the next step.
+
+### 10. Close the browser
+
+Use `mcp__chrome-devtools__list_pages` to get all open pages, then call `mcp__chrome-devtools__close_page` for every page ID returned. This closes the entire browser, not just the tab. `pageId` must be a number, not a string.
+
+### 11. Write verification stamp
+
+Run:
+
+```bash
+date +%s > .pulse-verified
+```
+
+This records that verify completed successfully. The stop hook checks this stamp — do not skip this step.
+
+### 12. Report
+
+Summarise:
+- Validation: pass or fail (with errors if any)
+- Visual: what was visible in the screenshot
+- Lighthouse desktop: scores for all four categories
+- Lighthouse mobile: scores for all four categories
+- Performance: LCP and CLS values, any flagged insights
+- Console: any errors
+- Review: pass or issues found and fixed
+
+Only confirm the page is good when validation passes, both Lighthouse runs are 100/100/100/100, CLS is 0.00, and there are no console errors. Otherwise, fix and run `/verify` again.

package/src/agent/coverage-check.js

@@ -35,7 +35,7 @@ try {
 // Parse the coverage report — look for lines with uncovered line numbers
 const lines = out.split('\n')
 let inReport = false
-const gaps = []
+const rawGaps = []
 
 for (const line of lines) {
   if (line.includes('start of coverage report')) { inReport = true; continue }
@@ -46,11 +46,72 @@ for (const line of lines) {
   if (m) {
     const uncov = m[2].trim()
     if (uncov && uncov !== 'uncovered lines') {
-      gaps.push(`  ${m[1].trim()} — uncovered lines: ${uncov}`)
+      rawGaps.push({ file: m[1].trim(), uncovered: uncov })
     }
   }
 }
 
+/**
+ * Returns true if all uncovered line numbers in the given file fall inside
+ * a `server:` property block or an action `run:` function — both of which
+ * call real external APIs and are explicitly exempt from coverage requirements.
+ */
+function allLinesExempt(filePath, uncoveredSpec) {
+  let src
+  try { src = fs.readFileSync(filePath, 'utf8') } catch { return false }
+  const srcLines = src.split('\n')
+
+  // Expand "30-36 50" → [30, 31, 32, 33, 34, 35, 36, 50]
+  const lineNums = []
+  for (const part of uncoveredSpec.split(/\s+/)) {
+    const range = part.match(/^(\d+)-(\d+)$/)
+    if (range) {
+      for (let i = parseInt(range[1]); i <= parseInt(range[2]); i++) lineNums.push(i)
+    } else if (/^\d+$/.test(part)) {
+      lineNums.push(parseInt(part))
+    }
+  }
+
+  // Build a set of exempt line numbers: lines inside `server:` blocks or action `run:` functions.
+  // Strategy: scan the source tracking brace depth relative to the start of each exempt block.
+  const exemptLines = new Set()
+  let i = 0
+  while (i < srcLines.length) {
+    const trimmed = srcLines[i].trimStart()
+    // Detect start of `server:` property or action `run:` function
+    const isExemptStart = /^server\s*:/.test(trimmed) || /^run\s*:/.test(trimmed) || /^run\s*\(/.test(trimmed)
+    if (isExemptStart) {
+      // Mark lines from here until the block closes (depth reaches 0 after opening)
+      let depth = 0
+      let started = false
+      const startLine = i
+      while (i < srcLines.length) {
+        exemptLines.add(i + 1) // 1-based
+        for (const ch of srcLines[i]) {
+          if (ch === '{' || ch === '(') { depth++; started = true }
+          if (ch === '}' || ch === ')') { depth-- }
+        }
+        if (started && depth <= 0) break
+        i++
+      }
+    }
+    i++
+  }
+
+  return lineNums.every(n => exemptLines.has(n))
+}
+
+const gaps = []
+for (const { file, uncovered } of rawGaps) {
+  // Try to resolve relative to cwd (coverage reports use relative paths)
+  const candidates = [file, `src/pages/${file}`, file.replace(/^.*src\/pages\//, 'src/pages/')]
+  const resolved   = candidates.find(p => fs.existsSync(p))
+
+  if (resolved && allLinesExempt(resolved, uncovered)) continue  // auto-exempt
+
+  gaps.push(`  ${file} — uncovered lines: ${uncovered}`)
+}
+
 if (gaps.length) {
   process.stdout.write(JSON.stringify({
     decision: 'block',

package/src/cli/dev.js

@@ -63,12 +63,18 @@ const PUBLIC_DIR     = path.join(ROOT, 'public')
   }
   fs.writeFileSync(stampPath, pkgVersion, 'utf8')
 
-  // Sync agent checklist into .claude/ so CLAUDE.md can import it
-  const checklistSrc = new URL('../agent/checklist.md', import.meta.url).pathname
-  const checklistDst = path.join(ROOT, '.claude', 'pulse-checklist.md')
-  if (fs.existsSync(checklistSrc)) {
-    fs.mkdirSync(path.dirname(checklistDst), { recursive: true })
-    fs.copyFileSync(checklistSrc, checklistDst)
+  // Sync agent files into .claude/
+  const agentFiles = [
+    ['../agent/checklist.md',      'pulse-checklist.md'],
+    ['../agent/coverage-check.js', 'coverage-check.js'],
+  ]
+  for (const [rel, dst] of agentFiles) {
+    const src = new URL(rel, import.meta.url).pathname
+    if (fs.existsSync(src)) {
+      const dstPath = path.join(ROOT, '.claude', dst)
+      fs.mkdirSync(path.dirname(dstPath), { recursive: true })
+      fs.copyFileSync(src, dstPath)
+    }
   }
 
   // Sync slash commands into .claude/commands/ so /pulse-dev etc. always exist

package/src/cli/index.js

@@ -292,13 +292,19 @@ async function runUpdate(root) {
     updated.push(`public/${asset}`)
   }
 
-  // Sync agent checklist into .claude/
-  const checklistSrc = new URL('../agent/checklist.md', import.meta.url).pathname
-  const checklistDst = path.join(root, '.claude', 'pulse-checklist.md')
-  if (fs.existsSync(checklistSrc)) {
-    fs.mkdirSync(path.dirname(checklistDst), { recursive: true })
-    fs.copyFileSync(checklistSrc, checklistDst)
-    updated.push('.claude/pulse-checklist.md')
+  // Sync agent files into .claude/
+  const agentFiles = [
+    ['../agent/checklist.md',      'pulse-checklist.md'],
+    ['../agent/coverage-check.js', 'coverage-check.js'],
+  ]
+  for (const [rel, dst] of agentFiles) {
+    const src = new URL(rel, import.meta.url).pathname
+    if (fs.existsSync(src)) {
+      const dstPath = path.join(root, '.claude', dst)
+      fs.mkdirSync(path.dirname(dstPath), { recursive: true })
+      fs.copyFileSync(src, dstPath)
+      updated.push(`.claude/${dst}`)
+    }
   }
 
   // Sync slash commands into .claude/commands/

package/src/cli/scaffold.js

@@ -168,6 +168,11 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
               type: 'command',
               command: `node .claude/coverage-check.js`,
               statusMessage: 'Checking test coverage...',
+            },
+            {
+              type: 'command',
+              command: `node -e "const fs=require('fs');const{execSync}=require('child_process');let specs=[];try{const out=execSync('git status --porcelain',{encoding:'utf8'});out.split('\\n').forEach(l=>{const f=l.slice(3).trim().split(' -> ').pop();if(f&&f.match(/^src\\/pages\\/.+\\.js$/)&&!f.endsWith('.test.js'))specs.push(f);});}catch{if(fs.existsSync('src/pages'))for(const f of fs.readdirSync('src/pages')){if(f.endsWith('.js')&&!f.endsWith('.test.js'))specs.push('src/pages/'+f);}}if(!specs.length)process.exit(0);const stamp='.pulse-verified';let stampMtime=0;try{stampMtime=fs.statSync(stamp).mtimeMs;}catch{}const stale=specs.filter(f=>{try{return fs.statSync(f).mtimeMs>stampMtime;}catch{return true;}});if(stale.length){process.stdout.write(JSON.stringify({decision:'block',reason:'VERIFY REQUIRED: These pages have not been verified since last edit:\\n'+stale.map(f=>'  '+f).join('\\n')+'\\n\\nRun /verify for each changed page. /verify runs Lighthouse (desktop + mobile), performance trace, console check, and code review — then writes the stamp that clears this check.'}));}"`,
+              statusMessage: 'Checking verification stamp...',
             }
           ]
         }