@invisibleloop/pulse 0.12.3 → 0.14.1

package/src/cli/dev.js

@@ -57,7 +57,15 @@ const PUBLIC_DIR     = path.join(ROOT, 'public')
   const stampPath  = path.join(PUBLIC_DIR, '.pulse-ui-version')
   const stamp      = fs.existsSync(stampPath) ? fs.readFileSync(stampPath, 'utf8').trim() : null
 
-  if (stamp === pkgVersion) return
+  // Compare CSS byte-length so any content change triggers a re-copy, even
+  // within the same version (e.g. when iterating locally with npm link).
+  const srcCss    = path.join(pkgPublic, 'pulse-ui.css')
+  const dstCss    = path.join(PUBLIC_DIR, 'pulse-ui.css')
+  const srcSize   = fs.existsSync(srcCss) ? fs.statSync(srcCss).size : -1
+  const dstSize   = fs.existsSync(dstCss) ? fs.statSync(dstCss).size : -2
+  const cssStale  = srcSize !== dstSize
+
+  if (stamp === pkgVersion && !cssStale) return
 
   fs.mkdirSync(PUBLIC_DIR, { recursive: true })
   for (const asset of ['pulse-ui.css', 'pulse-ui.js']) {
@@ -135,16 +143,40 @@ process.on('SIGTERM', closeReloadClients)
 process.on('SIGINT',  closeReloadClients)
 
 let reloadTimer = null
-fs.watch(path.join(ROOT, 'src'), { recursive: true }, () => {
+let lastReload = 0
+
+async function triggerReload(label = 'File changed') {
   clearTimeout(reloadTimer)
   reloadTimer = setTimeout(async () => {
+    // Debounce rapid file changes (e.g. multiple Edit tool calls)
+    const now = Date.now()
+    if (now - lastReload < 100) return
+    lastReload = now
+    
+    console.log(`  ⟳ ${label}, reloading specs...`)
     try {
-      const fresh = await loadPages(ROOT, Date.now())
+      const fresh = await loadPages(ROOT, now)
       updateSpecs(fresh)
-    } catch { /* spec error — browser will show the old page, not crash */ }
+      console.log('  ✓ Specs reloaded')
+    } catch (err) {
+      console.error('  ✗ Spec reload failed:', err.message)
+      /* spec error — browser will show the old page, not crash */
+    }
     notifyReload()
-  }, 50)
-})
+  }, 200)
+}
+
+// Watch src/ for changes to existing files (spec edits, component edits)
+fs.watch(path.join(ROOT, 'src'), { recursive: true }, () => triggerReload('File changed'))
+
+// Also watch the pages directory explicitly so macOS reliably fires on new file creation.
+// On macOS, fs.watch with recursive=true watches subdirectory contents but may not fire
+// for the parent dir entry when a brand-new file is created. Watching the dir non-recursively
+// catches the "new entry added to this directory" event.
+const pagesDir = path.join(ROOT, 'src', 'pages')
+if (fs.existsSync(pagesDir)) {
+  fs.watch(pagesDir, { recursive: false }, () => triggerReload('New page detected'))
+}
 
 // Tiny script injected into every page — connects to SSE and reloads on change
 // Passed as a function so the server can inject the per-request CSP nonce
@@ -160,7 +192,7 @@ const reloadScript = (nonce) => `<script nonce="${nonce}">
   })();
 </script>`
 
-const { updateSpecs } = createServer(specs, {
+const { updateSpecs } = await createServer(specs, {
   port:      PORT,
   stream:    true,
   staticDir: fs.existsSync(PUBLIC_DIR) ? PUBLIC_DIR : null,

package/src/cli/fmt.js

@@ -0,0 +1,113 @@
+/**
+ * Pulse CLI — terminal formatting helpers
+ *
+ * Respects NO_COLOR and CI env vars — falls back to plain text automatically.
+ * Zero dependencies, Node built-ins only.
+ */
+
+const USE_COLOR = !process.env.NO_COLOR && !process.env.CI && process.stdout.isTTY
+
+// ANSI escape helpers — no-ops when colour is disabled
+const c = {
+  reset:  s => USE_COLOR ? `\x1b[0m${s}\x1b[0m`  : s,
+  bold:   s => USE_COLOR ? `\x1b[1m${s}\x1b[0m`   : s,
+  dim:    s => USE_COLOR ? `\x1b[2m${s}\x1b[0m`   : s,
+  green:  s => USE_COLOR ? `\x1b[32m${s}\x1b[0m`  : s,
+  yellow: s => USE_COLOR ? `\x1b[33m${s}\x1b[0m`  : s,
+  blue:   s => USE_COLOR ? `\x1b[34m${s}\x1b[0m`  : s,
+  cyan:   s => USE_COLOR ? `\x1b[36m${s}\x1b[0m`  : s,
+  white:  s => USE_COLOR ? `\x1b[97m${s}\x1b[0m`  : s,
+  red:    s => USE_COLOR ? `\x1b[31m${s}\x1b[0m`  : s,
+  purple: s => USE_COLOR ? `\x1b[35m${s}\x1b[0m`  : s,
+}
+
+// Strip ANSI codes to measure true visual width
+function visLen(s) {
+  // eslint-disable-next-line no-control-regex
+  return s.replace(/\x1b\[[0-9;]*m/g, '').length
+}
+
+// Pad a string to a visual width (accounting for ANSI codes)
+function pad(s, width, align = 'left') {
+  const len  = visLen(s)
+  const fill = Math.max(0, width - len)
+  return align === 'right' ? ' '.repeat(fill) + s : s + ' '.repeat(fill)
+}
+
+// ─── Box ─────────────────────────────────────────────────────────────────────
+
+export function box(lines, opts = {}) {
+  const { title = '', style = 'single' } = opts
+  const chars = style === 'double'
+    ? { tl: '╔', tr: '╗', bl: '╚', br: '╝', h: '═', v: '║' }
+    : { tl: '┌', tr: '┐', bl: '└', br: '┘', h: '─', v: '│' }
+
+  const inner = Array.isArray(lines) ? lines : [lines]
+  const maxW  = Math.max(...inner.map(visLen), title ? visLen(title) + 2 : 0)
+  const bar   = chars.h.repeat(maxW + 2)
+
+  const top = title
+    ? `${chars.tl}${chars.h} ${c.bold(title)} ${chars.h.repeat(maxW - visLen(title) - 1)}${chars.tr}`
+    : `${chars.tl}${bar}${chars.tr}`
+
+  const rows = inner.map(l => `${chars.v} ${pad(l, maxW)} ${chars.v}`)
+  return [top, ...rows, `${chars.bl}${bar}${chars.br}`].join('\n')
+}
+
+// ─── Header (branded section label) ──────────────────────────────────────────
+
+export function header(text) {
+  const line = `${c.purple('⚡')} ${c.bold(c.white(text))}`
+  return `\n${line}\n${c.dim('─'.repeat(visLen('⚡ ' + text) - (USE_COLOR ? 0 : 0)))}`
+}
+
+// ─── Table ───────────────────────────────────────────────────────────────────
+
+/**
+ * Render an aligned table.
+ * @param {string[]}   cols    - Column headers
+ * @param {string[][]} rows    - Data rows (array of arrays)
+ * @param {{align?: ('left'|'right')[]}} opts
+ */
+export function table(cols, rows, opts = {}) {
+  const aligns  = opts.align || cols.map(() => 'left')
+  const allRows = [cols, ...rows]
+  const widths  = cols.map((_, i) => Math.max(...allRows.map(r => visLen(r[i] ?? ''))))
+
+  const sep = '  '
+
+  const headerRow = cols.map((h, i) => pad(c.dim(h), widths[i], aligns[i])).join(sep)
+  const divider   = c.dim('─'.repeat(widths.reduce((s, w, i) => s + w + (i < widths.length - 1 ? sep.length : 0), 0)))
+  const body      = rows.map(row =>
+    row.map((cell, i) => pad(cell ?? '', widths[i], aligns[i])).join(sep)
+  )
+
+  return [headerRow, divider, ...body].join('\n')
+}
+
+// ─── Status line helpers ──────────────────────────────────────────────────────
+
+export const icon = {
+  ok:   () => c.green('✓'),
+  fail: () => c.red('✗'),
+  warn: () => c.yellow('⚠'),
+  info: () => c.cyan('·'),
+  run:  () => c.yellow('›'),
+  bolt: () => c.purple('⚡'),
+}
+
+export function ok(msg)   { return `  ${icon.ok()}  ${msg}` }
+export function fail(msg) { return `  ${icon.fail()}  ${c.red(msg)}` }
+export function warn(msg) { return `  ${icon.warn()}  ${c.yellow(msg)}` }
+export function info(msg) { return `  ${icon.info()}  ${c.dim(msg)}` }
+
+// ─── Timing ───────────────────────────────────────────────────────────────────
+
+export function elapsed(ms) {
+  if (ms < 1000) return `${Math.round(ms)}ms`
+  return `${(ms / 1000).toFixed(1)}s`
+}
+
+// ─── Exports ──────────────────────────────────────────────────────────────────
+
+export { c, pad, visLen }

package/src/cli/index.js

@@ -33,6 +33,13 @@ for (let i = 0; i < rawArgs.length; i++) {
 const command = args[0]
 const CWD     = process.cwd()
 
+// Parse --agent flag before routing to commands
+let agentFlag = null
+const agentIdx = args.indexOf('--agent')
+if (agentIdx !== -1 && args[agentIdx + 1]) {
+  agentFlag = args[agentIdx + 1]
+}
+
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -91,7 +98,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`)
 
@@ -343,7 +350,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 +370,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 +383,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 +420,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 +463,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 +521,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/scaffold.js

@@ -451,8 +451,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;')