@invisibleloop/pulse 0.12.3 → 0.14.2

package/src/cli/index.js

@@ -91,7 +91,7 @@ function isDirEmpty(dir) {
   return fs.readdirSync(dir).length === 0
 }
 
-async function runDefault(root) {
+async function runDefault(root, agentFlag = null) {
   if (!isPulseProject(root)) {
     console.log(`\n⚡ No Pulse project found here.\n`)
 
@@ -169,13 +169,14 @@ async function launchSession(root, agentOverride = null) {
     }
   }
 
-  console.log(`\n⚡ Pulse project: ${root}`)
-  console.log(`   Use /pulse-dev to start the dev server, /pulse-stop to stop it, /pulse-build to build, /pulse-start to run production.`)
-  console.log(`   Tell me what you'd like to build — a new page, a component, a form, or anything else.\n`)
+  console.log(`\n  ⚡ Pulse  →  ${root}`)
+  console.log(`  ${agent === 'copilot' ? '● Copilot' : '● Claude'} agent starting — tell me what you'd like to build.\n`)
 
   if (agent === 'copilot') {
+    process.env.PULSE_AGENT_MODE = '1'
     await launchCopilotSession(root, mcpServerPath, spawn, os.default)
   } else {
+    process.env.PULSE_AGENT_MODE = '1'
     await launchClaudeSession(root, mcpConfig, spawn, os.default)
   }
 }
@@ -343,7 +344,11 @@ async function runUpdate(root) {
     process.exit(1)
   }
 
+  // Copy assets from the package this CLI binary lives in (import.meta.url).
+  // When globally npm-linked to the dev repo, this resolves to dev source.
+  // When installed normally, this resolves to the installed version.
   const pkgPublic = new URL('../../public', import.meta.url).pathname
+  const pkgSrc    = new URL('..', import.meta.url).pathname
   const assets    = ['pulse-ui.css', 'pulse-ui.js', '.pulse-ui-version']
   const publicDir = path.join(root, 'public')
   const updated   = []
@@ -359,11 +364,10 @@ async function runUpdate(root) {
 
   // Sync agent files into .claude/
   const agentFiles = [
-    ['../agent/checklist.md',      'pulse-checklist.md'],
-    ['../agent/coverage-check.js', 'coverage-check.js'],
+    [path.join(pkgSrc, 'agent', 'checklist.md'),      'pulse-checklist.md'],
+    [path.join(pkgSrc, 'agent', 'coverage-check.js'), 'coverage-check.js'],
   ]
-  for (const [rel, dst] of agentFiles) {
-    const src = new URL(rel, import.meta.url).pathname
+  for (const [src, dst] of agentFiles) {
     if (fs.existsSync(src)) {
       const dstPath = path.join(root, '.claude', dst)
       fs.mkdirSync(path.dirname(dstPath), { recursive: true })
@@ -373,7 +377,7 @@ async function runUpdate(root) {
   }
 
   // Sync slash commands into .claude/commands/
-  const commandsSrc = new URL('../agent/commands', import.meta.url).pathname
+  const commandsSrc = path.join(pkgSrc, 'agent', 'commands')
   const commandsDst = path.join(root, '.claude', 'commands')
   if (fs.existsSync(commandsSrc)) {
     fs.mkdirSync(commandsDst, { recursive: true })
@@ -410,9 +414,16 @@ async function runUpdate(root) {
   const versionFile = path.join(publicDir, '.pulse-ui-version')
   const version     = fs.existsSync(versionFile) ? fs.readFileSync(versionFile, 'utf8').trim() : '?'
 
-  console.log(`\n⚡ Pulse updated to ${version}\n`)
-  for (const f of updated) console.log(`  ✓ ${f}`)
-  for (const f of missing) console.log(`  ✗ ${f} not found in package`)
+  const { c, ok: fmtOk, fail: fmtFail, icon } = await import('./fmt.js').catch(() => ({
+    c: { dim: s => s, bold: s => s },
+    ok: s => `  ✓ ${s}`,
+    fail: s => `  ✗ ${s}`,
+    icon: { bolt: () => '⚡' },
+  }))
+
+  console.log(`\n  ${icon.bolt()} ${c.bold('Pulse')} updated to ${c.bold(version)}\n`)
+  for (const f of updated) console.log(fmtOk(f))
+  for (const f of missing) console.log(fmtFail(`${f} not found in package`))
   console.log()
 }
 
@@ -446,29 +457,37 @@ switch (command) {
     process.exit(0)
   }
   case '--help':
-  case '-h':
+  case '-h': {
+    const { c, icon } = await import('./fmt.js').catch(() => ({
+      c: { bold: s => s, dim: s => s, cyan: s => s, purple: s => s, white: s => s },
+      icon: { bolt: () => '⚡' },
+    }))
     console.log(`
-  ⚡ Pulse — spec-first frontend framework
-
-  Usage: pulse [command] [options]
-
-  Commands:
-    (none)      detect project or start scaffold wizard
-    dev         start dev server
-    build       production build → public/dist/
-    start       production server (requires prior build)
-    update      re-copy pulse-ui assets from installed package → public/
-
-  Options:
-    --agent <name>  AI agent to use: claude (default) or copilot
-    -v, --version   print version and exit
-    -h, --help      show this help
-
-  Examples:
-    pulse                    start with Claude (default)
-    pulse --agent copilot    start with GitHub Copilot CLI
+  ${icon.bolt()} ${c.bold('Pulse')}  ${c.dim('— spec-first frontend framework')}
+
+  ${c.bold('Usage:')}  pulse ${c.dim('[command] [options]')}
+
+  ${c.bold('Commands:')}
+    ${c.cyan('(none)')}           detect project, or launch the scaffold wizard
+    ${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('update')}           re-copy pulse-ui assets from installed package
+
+  ${c.bold('Options:')}
+    ${c.cyan('--agent')} ${c.dim('<name>')}     use specific agent ${c.dim('(claude | copilot)')}
+    ${c.cyan('-v')}, ${c.cyan('--version')}      print version and exit
+    ${c.cyan('-h')}, ${c.cyan('--help')}         show this help
+
+  ${c.bold('Examples:')}
+    ${c.dim('pulse                      # new project wizard')}
+    ${c.dim('pulse --agent copilot      # launch with GitHub Copilot CLI')}
+    ${c.dim('pulse dev                  # dev server')}
+    ${c.dim('pulse build                # bundle for production')}
+    ${c.dim('pulse start                # serve production build')}
 `)
     process.exit(0)
+  }
   case 'dev':
     await runDev(CWD)
     break
@@ -496,6 +515,14 @@ switch (command) {
   case 'update':
     await runUpdate(CWD)
     break
+  case 'link': {
+    // DEV-ONLY: npm link the local dev repo into this project, then pulse update.
+    const { execSync } = await import('child_process')
+    console.log('\n  Linking @invisibleloop/pulse from dev repo…\n')
+    execSync('npm link @invisibleloop/pulse', { cwd: CWD, stdio: 'inherit' })
+    await runUpdate(CWD)
+    break
+  }
   default:
-    await runDefault(CWD)
+    await runDefault(CWD, agentFlag)
 }

package/src/cli/logger.js

@@ -0,0 +1,145 @@
+/**
+ * Pulse CLI — structured terminal logger
+ *
+ * Single module that owns all terminal output. Produces clean, scannable
+ * output: one-time startup banner, then a timestamped scrolling log.
+ *
+ * Rules:
+ *  - Static asset requests (JS, CSS, images, fonts) are dimmed and collapsed
+ *  - Errors always stand out (red ✗ prefix)
+ *  - Agent activity gets a distinct indicator
+ *  - Respects NO_COLOR and CI env vars
+ */
+
+import { c, icon, elapsed, visLen } from './fmt.js'
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const STATIC_EXT = /\.(js|css|map|ico|png|jpg|jpeg|gif|svg|woff2?|ttf|eot|webp|avif|json)$/i
+const STATIC_PATH = /^\/(dist|fonts|images|public)\//
+
+function isStatic(pathname) {
+  return STATIC_EXT.test(pathname) || STATIC_PATH.test(pathname)
+}
+
+function timestamp() {
+  return c.dim(new Date().toLocaleTimeString('en-GB', { hour: '2-digit', minute: '2-digit', second: '2-digit' }))
+}
+
+function statusColor(code) {
+  if (code >= 500) return c.red(String(code))
+  if (code >= 400) return c.yellow(String(code))
+  if (code >= 300) return c.cyan(String(code))
+  return c.dim(String(code))
+}
+
+function methodColor(method) {
+  if (method === 'POST' || method === 'PUT' || method === 'PATCH') return c.yellow(method.padEnd(4))
+  if (method === 'DELETE') return c.red(method.padEnd(4))
+  return c.dim(method.padEnd(4))
+}
+
+// ---------------------------------------------------------------------------
+// Banner — printed once at startup
+// ---------------------------------------------------------------------------
+
+/**
+ * Print the startup banner.
+ * @param {{ url: string, version: string, specs: Array<{route:string, method?:string, hydrate?:string}>, agentMode?: boolean }} opts
+ */
+export function banner({ url, version, specs = [], agentMode = false }) {
+  const agentLabel = agentMode ? `  ${c.cyan('●')} ${c.dim('Agent active')}` : ''
+
+  process.stdout.write('\n')
+  process.stdout.write(`  ${icon.bolt()} ${c.bold('Pulse')}  ${c.dim(`v${version}`)}  ${c.dim('→')}  ${c.cyan(url)}${agentLabel}\n`)
+  process.stdout.write('\n')
+
+  if (specs.length > 0) {
+    // Column widths
+    const routeW  = Math.max(5, ...specs.map(s => (s.route || '?').length))
+    const methodW = 6
+
+    const header = `  ${c.dim('Route'.padEnd(routeW))}  ${c.dim('Method'.padEnd(methodW))}  ${c.dim('JS')}`
+    const divider = `  ${c.dim('─'.repeat(routeW + methodW + 8))}`
+
+    process.stdout.write(header + '\n')
+    process.stdout.write(divider + '\n')
+
+    for (const s of specs) {
+      const route   = (s.route || '?').padEnd(routeW)
+      const method  = (s.method?.toUpperCase() || 'GET').padEnd(methodW)
+      const hydrate = s.hydrate ? c.green('✓ hydrated') : c.dim('— static')
+      process.stdout.write(`  ${c.cyan(route)}  ${c.dim(method)}  ${hydrate}\n`)
+    }
+
+    process.stdout.write('\n')
+  }
+
+  process.stdout.write(c.dim('  Ready. Watching for changes…\n'))
+  process.stdout.write(c.dim('  ' + '─'.repeat(48) + '\n'))
+  process.stdout.write('\n')
+}
+
+// ---------------------------------------------------------------------------
+// Request log — one line per request
+// ---------------------------------------------------------------------------
+
+/**
+ * Log a completed HTTP request.
+ * @param {{ method: string, pathname: string, status: number, ms: number }} opts
+ */
+export function request({ method, pathname, status, ms }) {
+  const isAsset = isStatic(pathname)
+
+  // Skip health check noise
+  if (pathname === '/healthz' || pathname === '/_pulse/health') return
+
+  const ts     = timestamp()
+  const m      = methodColor(method)
+  const p      = isAsset ? c.dim(pathname) : pathname
+  const s      = statusColor(status)
+  const t      = c.dim(elapsed(ms))
+
+  if (isAsset) {
+    // Static assets — dim the whole line, no leading symbol
+    process.stdout.write(`${ts}  ${c.dim(method.padEnd(4))}  ${p}  ${c.dim(String(status))}  ${t}\n`)
+  } else if (status >= 500) {
+    process.stdout.write(`${ts}  ${icon.fail()}  ${m}  ${c.red(pathname)}  ${s}  ${t}\n`)
+  } else if (status >= 400) {
+    process.stdout.write(`${ts}  ${icon.warn()}  ${m}  ${c.yellow(pathname)}  ${s}  ${t}\n`)
+  } else {
+    process.stdout.write(`${ts}  ${icon.info()}  ${m}  ${p}  ${s}  ${t}\n`)
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Named events — server lifecycle
+// ---------------------------------------------------------------------------
+
+export function ready(url) {
+  process.stdout.write(`${timestamp()}  ${icon.ok()}  ${c.dim('Server ready')}  ${c.dim(url)}\n`)
+}
+
+export function shutdown(forced = false) {
+  process.stdout.write('\n')
+  if (forced) {
+    process.stdout.write(`  ${icon.fail()}  ${c.red('Force-exiting after shutdown timeout')}\n`)
+  } else {
+    process.stdout.write(`  ${icon.info()}  ${c.dim('Shutting down gracefully…')}\n`)
+  }
+}
+
+export function error(msg, err) {
+  process.stdout.write(`${timestamp()}  ${icon.fail()}  ${c.red(msg)}\n`)
+  if (err?.stack) process.stdout.write(c.dim(err.stack.split('\n').slice(1, 4).map(l => '    ' + l).join('\n')) + '\n')
+}
+
+export function info(msg) {
+  process.stdout.write(`${timestamp()}  ${icon.info()}  ${c.dim(msg)}\n`)
+}
+
+export function warn(msg) {
+  process.stdout.write(`${timestamp()}  ${icon.warn()}  ${c.yellow(msg)}\n`)
+}

package/src/cli/scaffold.js

@@ -27,6 +27,7 @@ export async function scaffold(targetDir, options = {}) {
   fs.mkdirSync(path.join(targetDir, 'src', 'pages'),      { recursive: true })
   fs.mkdirSync(path.join(targetDir, 'src', 'components'), { recursive: true })
   fs.mkdirSync(path.join(targetDir, 'public'),             { recursive: true })
+  fs.mkdirSync(path.join(targetDir, 'public', 'intake'),   { recursive: true })
 
   // package.json
   write(targetDir, 'package.json', JSON.stringify({
@@ -62,6 +63,9 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
   write(targetDir, 'public/theme.css', themeCSS())
   write(targetDir, 'public/app.css',   baseCSS())
 
+  // Intake directory — drop inspiration images here before running pulse_intake
+  write(targetDir, 'public/intake/README.md', intakeReadme())
+
   // Copy pulse-ui assets from the package into public/ so they're served immediately
   const pkgPublic = new URL('../../public', import.meta.url).pathname
   for (const asset of ['pulse-ui.css', 'pulse-ui.js']) {
@@ -124,13 +128,18 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
           hooks: [
             {
               type: 'command',
-              command: `node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:'START OF SESSION: Before doing anything else — (1) run pulse_list_structure to see the current project structure, (2) read pulse://guide from MCP for the complete Pulse reference. Both are mandatory. Do not skip them.'}}))"`,
+              command: `node -e "process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:'START OF SESSION: Before doing anything else — (1) run pulse_list_structure to see the current project structure, (2) read pulse://guide from MCP for the complete Pulse reference. Both are mandatory. Do not skip them.\\n\\nBUILD RULE — ALWAYS ASK BEFORE PLANNING: If the user is requesting a new page or site, your FIRST action must be to ask: \\'Do you have any design inspiration — a site you love, a screenshot, a mood board image? Drop images into public/intake/ or paste a URL and I will extract the design intent before we start.\\' Do not present a plan or write any code until you have asked this question and received an answer. This question is not optional and cannot be skipped.'}}))"`,
               statusMessage: 'Loading Pulse session...',
             },
             {
               type: 'command',
               command: `node -e "const{execSync}=require('child_process');let out='';let ok=true;try{out=execSync('npm test 2>&1',{encoding:'utf8',timeout:60000});}catch(e){ok=false;out=e.stdout||e.message;}const lines=out.trim().split('\\n');const summary=lines[lines.length-1]||'';const msg=ok?'TEST BASELINE — all tests passing: '+summary+'. Note this result. If tests fail after your changes, you introduced the regression.':'PRE-EXISTING TEST FAILURES detected before you wrote any code:\\n'+out.slice(-2000)+'\\nDo not treat these as regressions you caused. Fix them first if they are related to your task, otherwise note them and proceed.';process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:msg}}))"`,
               statusMessage: 'Running test baseline...',
+            },
+            {
+              type: 'command',
+              command: `node -e "const fs=require('fs');const path=require('path');const intakeDir='public/intake';let images=[];try{images=fs.readdirSync(intakeDir).filter(f=>/\\.(jpe?g|png|gif|webp|avif)$/i.test(f));}catch{}if(!images.length){process.exit(0);}const list=images.map(f=>'  • '+f).join('\\n');process.stdout.write(JSON.stringify({hookSpecificOutput:{hookEventName:'SessionStart',additionalContext:'DESIGN REFERENCES FOUND in public/intake/:\\n'+list+'\\n\\nBefore running pulse_intake, call pulse_extract_inspiration on each image to extract palette, vibe, layout density, and type signals. This gives the design much more precision than text descriptions alone.\\n\\nWorkflow: pulse_extract_inspiration(image) → fill in the template using your vision → feed results into pulse_intake(inspiration: \\'...\\')'}}));"`,
+              statusMessage: 'Checking for design references...',
             }
           ]
         }
@@ -209,6 +218,13 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}${agent && agent !== 'claude' ? `  a
     'public/dist',
     '.pulse-build',
     '.DS_Store',
+    '# Intake images — local design references, not committed',
+    'public/intake/*.jpg',
+    'public/intake/*.jpeg',
+    'public/intake/*.png',
+    'public/intake/*.gif',
+    'public/intake/*.webp',
+    'public/intake/*.avif',
   ].join('\n') + '\n')
 
   console.log('  ✓ Project files created')
@@ -349,6 +365,42 @@ function themeCSS() {
 `
 }
 
+function intakeReadme() {
+  return `\
+# Design References
+
+Drop inspiration images here before starting a new build.
+
+The session start hook will detect them and remind the agent to run
+\`pulse_extract_inspiration\` on each one before \`pulse_intake\`.
+
+## What to put here
+
+- Screenshots of sites whose design you admire
+- Your brand mood board or style guide
+- Product photography that anchors the visual direction
+- Competitor sites you want to differentiate from
+- Any image that captures the feeling you're going for
+
+## How the agent uses them
+
+1. \`pulse_extract_inspiration(image)\` — reads the image and extracts palette,
+   type weight, spacing density, radius signals, and layout intent
+2. The extracted values feed into \`pulse_intake\` as concrete constraints
+3. \`pulse_sketch\` uses them to generate layout directions matched to the actual
+   visual reference, not just a text description of a vibe
+
+## File formats
+
+JPEG, PNG, WebP, AVIF, GIF — any image the model can read.
+
+## Note
+
+These files are listed in .gitignore and will not be committed.
+Only this README is tracked.
+`
+}
+
 function baseCSS() {
   return `\
 *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -377,12 +429,14 @@ src/pages/        ← one .js file per page, auto-discovered
 src/components/   ← shared view fragments (JS functions returning HTML strings)
 public/theme.css  ← token definitions (hex values, colour overrides) — hex allowed here only
 public/app.css    ← layout and component overrides — var() references only, no hex
+public/intake/    ← drop design reference images here before starting (not committed to git)
 \`\`\`
 
 ## Start of every session
 
 1. Run \`pulse_list_structure\` to see what already exists
 2. Read \`pulse://guide\` from MCP — the complete reference for spec format, components, verification workflow, CSS rules, and patterns
+3. If images are present in \`public/intake/\`, call \`pulse_extract_inspiration\` on each before \`pulse_intake\` — the session hook will remind you if you forget
 
 The MCP guide is the single source of truth. Follow it for all technical decisions, component usage, and the mandatory verification workflow.
 
@@ -451,8 +505,8 @@ const fallback = spec.onViewError(new Error('boom'), {}, {})
 assert(fallback.includes('main-content'))
 \`\`\`
 
-**Selector support:** \`tag\`, \`.class\`, \`#id\`, \`[attr]\`, \`[attr="value"]\`, and combinations (\`button.primary[disabled]\`).
-Descendant selectors (\`tbody tr\`, \`ul li\`) are NOT supported — use \`r.count('tr')\` not \`r.count('tbody tr')\`.
+**Selector support:** \`tag\`, \`.class\`, \`#id\`, \`[attr]\`, \`[attr="value"]\`, combinations (\`button.primary[disabled]\`), and **descendant combinators** (\`r.count('tbody tr')\`, \`r.find('.card h2')\`).
+Descendant selectors match the rightmost token within the ancestor context — \`r.count('.foo span')\` counts spans that are descendants of \`.foo\` elements.
 
 @.claude/pulse-checklist.md
 `

package/src/html.js

@@ -6,13 +6,18 @@
 /**
  * Escape HTML special characters. Use this in view functions whenever
  * rendering untrusted user data into HTML attributes or text content.
+ * 
+ * Preserves HTML entities (·,  , ©, etc) so component
+ * labels can use them without double-escaping.
  *
  * @param {unknown} str
  * @returns {string}
  */
 export function escHtml(str) {
   return String(str)
-    .replace(/&/g, '&')
+    // Replace & only if not already part of an HTML entity
+    // Matches &<word>; or &#<digits>; or &#x<hex>;
+    .replace(/&(?![a-zA-Z]+;|#\d+;|#x[0-9a-fA-F]+;)/g, '&amp;')
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')