@crab-dev/wake 0.1.2 → 0.1.4

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.1.4
+
+- Added the opt-in Storybook-like documentation component workbench.
+- Fixed Yarn PnP packages that expose entries and subpaths through `package.json#exports`.
+- Expanded TypeScript and TSX parsing for optional arrow parameters, generic JSX, generic async arrows, and indexed type queries.
+- Added source module paths to build diagnostics and corrected `wake parse` source-type selection.
+
+## 0.1.3
+
+- Improved the npm development-server terminal panel with Rust CLI-aligned styling, startup timing, rebuild progress, diagnostics, and color controls.
+
 ## 0.1.2
 
 - Updated the npm release pipeline for private GitHub repositories while preserving immutable tarball audits.

package/bin/terminal.mjs

@@ -0,0 +1,459 @@
+const RESET = '\x1b[0m'
+const BOLD = '\x1b[1m'
+const DIM = '\x1b[2m'
+const MAX_ACTIVITY = 200
+const SPINNER = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧']
+
+export function supportsColor(stream = process.stderr, env = process.env) {
+  return stream.isTTY === true && !Object.hasOwn(env, 'NO_COLOR')
+}
+
+export function supportsTui(input = process.stdin, output = process.stderr, env = process.env) {
+  return input.isTTY === true
+    && output.isTTY === true
+    && String(env.TERM || '').toLowerCase() !== 'dumb'
+}
+
+export function createUi(color = supportsColor(), env = process.env) {
+  const trueColor = color && /^(truecolor|24bit)$/i.test(env.COLORTERM || '')
+  const wrap = (indexed, rgb, text) => {
+    if (!color) return String(text)
+    const code = trueColor
+      ? `\x1b[38;2;${rgb.join(';')}m`
+      : `\x1b[38;5;${indexed}m`
+    return `${code}${text}${RESET}`
+  }
+  return {
+    color,
+    accent: (text) => wrap(81, [34, 211, 238], text),
+    bold: (text) => color ? `${BOLD}${text}${RESET}` : String(text),
+    brand: (text) => color ? `${BOLD}${wrap(213, [217, 70, 239], text)}${RESET}` : String(text),
+    dim: (text) => color ? `${DIM}${text}${RESET}` : String(text),
+    error: (text) => wrap(204, [251, 113, 133], text),
+    ok: (text) => wrap(114, [74, 222, 128], text),
+    warn: (text) => wrap(214, [251, 191, 36], text),
+  }
+}
+
+export function humanDuration(durationMs) {
+  const milliseconds = Math.max(1, Number(durationMs) || 0)
+  if (milliseconds < 1_000) return `${milliseconds.toFixed(0)}ms`
+  if (milliseconds < 60_000) return `${(milliseconds / 1_000).toFixed(2)}s`
+  const seconds = milliseconds / 1_000
+  return `${Math.floor(seconds / 60)}m${(seconds % 60).toFixed(1)}s`
+}
+
+function moduleCount(count) {
+  return `${count} module${count === 1 ? '' : 's'}`
+}
+
+function cacheHitCount(count) {
+  return `${count} cache hit${count === 1 ? '' : 's'}`
+}
+
+export function humanRuntime(durationMs) {
+  const seconds = Math.max(0, Math.floor(durationMs / 1_000))
+  if (seconds < 60) return `${seconds}s`
+  if (seconds < 3_600) return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`
+  return `${Math.floor(seconds / 3_600)}h${String(Math.floor((seconds % 3_600) / 60)).padStart(2, '0')}m`
+}
+
+export function humanBytes(bytes) {
+  const value = Number(bytes) || 0
+  if (value >= 1024 * 1024) return `${(value / 1024 / 1024).toFixed(2)} MB`
+  if (value >= 1024) return `${(value / 1024).toFixed(1)} KB`
+  return `${value} B`
+}
+
+export function formatBanner(ui, command, currentVersion) {
+  return [
+    '',
+    `  ${ui.warn('⚡')} ${ui.brand('WAKE')} ${ui.dim('/')} ${ui.bold(command.toUpperCase())}  ${ui.dim(`v${currentVersion}`)}`,
+    '',
+  ]
+}
+
+export function formatBuildResult(ui, result, label = 'Built', extra = '') {
+  const bytes = (result.files || []).reduce((sum, file) => sum + Number(file.bytes || 0), 0)
+  const lines = [
+    `  ${ui.ok('✓')}  ${ui.bold(label)} ${ui.accent(`in ${humanDuration(result.durationMs)}`)}`,
+    `     ${ui.accent(`${result.moduleCount} modules`)} ${ui.dim('·')} ${(result.files || []).length} ${ui.dim('files')} ${ui.dim('·')} ${ui.accent(humanBytes(bytes))}${extra}`,
+  ]
+  if (result.outputDir) lines.push(`     ${ui.dim('Output')}  ${ui.accent(result.outputDir)}`)
+  for (const diagnostic of result.diagnostics || []) {
+    lines.push(`     ${ui.warn(String(diagnostic.severity || 'warning').toUpperCase())}  ${diagnostic.message}`)
+  }
+  lines.push('')
+  return lines
+}
+
+export function formatServerReady(ui, url, metrics) {
+  const lines = [
+    `  ${ui.ok('✓')}  ${ui.bold('Development server ready')}`,
+    `     ${ui.dim('Local')}  ${ui.accent(url)}`,
+  ]
+  if (metrics) {
+    lines.push(
+      `     ${ui.accent(`${metrics.modules} modules`)} ${ui.dim('·')} ${metrics.chunks} ${ui.dim('chunks')} ${ui.dim('·')} ${metrics.assets} ${ui.dim('assets')}`,
+    )
+  }
+  lines.push(`     ${ui.dim('Press Ctrl-C to stop')}`, '')
+  return lines
+}
+
+export function formatError(ui, error) {
+  const code = error?.code ? `[${error.code}]` : '[WAKE_INTERNAL]'
+  const lines = [
+    `  ${ui.error('✗')}  ${ui.bold('Wake failed')} ${ui.error(code)}`,
+    `     ${error?.message || error}`,
+  ]
+  if (error?.path) lines.push(`     ${ui.dim('Path')}  ${ui.accent(error.path)}`)
+  for (const diagnostic of error?.diagnostics || []) {
+    const diagnosticCode = diagnostic.code ? `[${diagnostic.code}] ` : ''
+    lines.push(
+      `     ${ui.warn(String(diagnostic.severity || 'error').toUpperCase())}  ${diagnosticCode}${diagnostic.message}`,
+    )
+    for (const note of diagnostic.notes || []) lines.push(`        ${ui.dim('·')} ${note}`)
+  }
+  lines.push('')
+  return lines
+}
+
+export function formatFinalSummary(ui, state, reason, label = 'Server stopped') {
+  const lines = [
+    '',
+    `  ${ui.dim('■')}  ${ui.bold(label)} ${ui.dim(`(${reason})`)}`,
+  ]
+  if (state.endpoint) {
+    lines.push(`     ${ui.dim(state.endpointLabel)}  ${ui.accent(state.endpoint)}`)
+  }
+  lines.push(
+    `     ${state.rebuilds} rebuilds ${ui.dim('·')} runtime ${ui.accent(humanRuntime(Date.now() - state.startedAt))}`,
+    '',
+  )
+  return lines
+}
+
+export function observeServer(server, ui, output = console) {
+  const onRebuildStart = (event) => {
+    const count = event.changedPaths?.length || 0
+    const detail = count === 1
+      ? 'Rebuilding after 1 file change…'
+      : count > 1
+        ? `Rebuilding after ${count} file changes…`
+        : 'Rebuilding…'
+    output.error(`  ${ui.warn('↻')}  ${ui.dim(detail)}`)
+  }
+  const onRebuilt = (event) => {
+    if (event.initial) return
+    output.error(
+      `  ${ui.ok('✓')}  ${ui.bold('Updated')}  ${ui.dim('·')}  ${ui.accent(moduleCount(event.updatedModules))}  ${ui.dim('·')}  ${ui.accent(cacheHitCount(event.cachedModules))}  ${ui.accent(humanDuration(event.durationMs))}`,
+    )
+  }
+  const onDiagnostic = (diagnostic) => {
+    const code = diagnostic.code ? `[${diagnostic.code}] ` : ''
+    output.error(`  ${ui.error('✗')}  ${ui.bold('Build failed')}  ${code}${diagnostic.message}`)
+  }
+
+  server.on('rebuildStart', onRebuildStart)
+  server.on('rebuilt', onRebuilt)
+  server.on('diagnostic', onDiagnostic)
+  return () => {
+    server.off('rebuildStart', onRebuildStart)
+    server.off('rebuilt', onRebuilt)
+    server.off('diagnostic', onDiagnostic)
+  }
+}
+
+function pushActivity(state, level, message) {
+  if (state.activity.length === MAX_ACTIVITY) state.activity.shift()
+  state.activity.push({
+    elapsedMs: Date.now() - state.startedAt,
+    level,
+    message: String(message),
+  })
+}
+
+export function createDashboardState({
+  command,
+  root = '.',
+  endpointLabel = 'LOCAL',
+  watchLabel = 'HMR · source maps · watching',
+}) {
+  const state = {
+    command,
+    root,
+    endpointLabel,
+    endpoint: '',
+    watchLabel,
+    status: 'starting',
+    metrics: undefined,
+    rebuilds: 0,
+    startedAt: Date.now(),
+    activity: [],
+    scrollFromBottom: 0,
+  }
+  pushActivity(state, 'info', 'Starting Wake…')
+  return state
+}
+
+export function applyDashboardEvent(state, event) {
+  if (event.type === 'rebuildStart') {
+    const count = event.changedPaths?.length || 0
+    state.status = 'rebuilding'
+    pushActivity(
+      state,
+      'warning',
+      count === 1
+        ? 'Rebuilding after 1 file change…'
+        : count > 1
+          ? `Rebuilding after ${count} file changes…`
+          : 'Rebuilding…',
+    )
+  } else if (event.type === 'rebuilt') {
+    state.status = 'ready'
+    state.metrics = {
+      modules: event.modules,
+      updatedModules: event.updatedModules,
+      cachedModules: event.cachedModules,
+      chunks: event.chunks,
+      assets: event.assets,
+      durationMs: event.durationMs,
+    }
+    if (!event.initial) state.rebuilds += 1
+    pushActivity(
+      state,
+      'success',
+      event.initial
+        ? `Initial build completed: ${event.modules} modules in ${humanDuration(event.durationMs)}`
+        : `Updated ${moduleCount(event.updatedModules)} · ${cacheHitCount(event.cachedModules)} in ${humanDuration(event.durationMs)}`,
+    )
+  } else if (event.type === 'diagnostic') {
+    state.status = 'error'
+    pushActivity(state, 'error', event.message)
+  } else if (event.type === 'closed') {
+    state.status = 'stopped'
+    pushActivity(state, 'info', 'Wake stopped')
+  }
+}
+
+export function setDashboardEndpoint(state, endpoint) {
+  state.endpoint = String(endpoint)
+}
+
+export function setDashboardStopping(state, reason) {
+  state.status = 'stopping'
+  pushActivity(state, 'info', `Stopping (${reason})…`)
+}
+
+export function setDashboardStopped(state) {
+  state.status = 'stopped'
+  pushActivity(state, 'info', 'Wake stopped')
+}
+
+function statusLabel(status) {
+  return {
+    starting: 'STARTING',
+    ready: 'READY',
+    rebuilding: 'REBUILDING',
+    error: 'ERROR',
+    stopping: 'STOPPING',
+    stopped: 'STOPPED',
+  }[status] || 'STARTING'
+}
+
+function statusSymbol(state) {
+  if (state.status === 'ready') return '✓'
+  if (state.status === 'error') return '✗'
+  if (state.status === 'stopping') return '◌'
+  if (state.status === 'stopped') return '■'
+  return SPINNER[Math.floor((Date.now() - state.startedAt) / 100) % SPINNER.length]
+}
+
+function elapsedStamp(durationMs) {
+  const seconds = Math.floor(durationMs / 1_000)
+  return `+${String(Math.floor(seconds / 60) % 100).padStart(2, '0')}:${String(seconds % 60).padStart(2, '0')}`
+}
+
+function charLength(text) {
+  return [...stripAnsi(String(text))].length
+}
+
+function truncate(text, width) {
+  const chars = [...String(text)]
+  if (chars.length <= width) return String(text)
+  if (width <= 1) return chars.slice(0, width).join('')
+  return `${chars.slice(0, width - 1).join('')}…`
+}
+
+function pad(text, width) {
+  const value = truncate(text, width)
+  return value + ' '.repeat(Math.max(0, width - charLength(value)))
+}
+
+function boxLine(text, width) {
+  if (width < 4) return pad(text, width)
+  return `│ ${pad(text, width - 4)} │`
+}
+
+function topBorder(state, width) {
+  const title = ` ⚡ WAKE / ${state.command.toUpperCase()}  v${state.version || ''} `
+  if (width < 4) return '─'.repeat(width)
+  const clipped = truncate(title, width - 2)
+  return `╭${clipped}${'─'.repeat(Math.max(0, width - 2 - charLength(clipped)))}╮`
+}
+
+function separator(width, title = '') {
+  if (width < 4) return '─'.repeat(width)
+  const center = title ? ` ${title} ` : ''
+  return `├${center}${'─'.repeat(Math.max(0, width - 2 - charLength(center)))}┤`
+}
+
+function bottomBorder(width) {
+  return width < 4 ? '─'.repeat(width) : `╰${'─'.repeat(width - 2)}╯`
+}
+
+function metricsText(state) {
+  const metrics = state.metrics
+  if (!metrics) return 'BUILD   waiting for metrics…'
+  return `BUILD   ${metrics.modules} modules · ${metrics.chunks} chunks · ${metrics.assets} assets · ${humanDuration(metrics.durationMs)}`
+}
+
+function activityRows(state, available) {
+  const end = Math.max(0, state.activity.length - state.scrollFromBottom)
+  const start = Math.max(0, end - Math.max(1, available))
+  return state.activity.slice(start, end).map((item) => {
+    const symbol = { info: '·', success: '✓', warning: '↻', error: '✗' }[item.level]
+    return `${elapsedStamp(item.elapsedMs)}  ${symbol} ${String(item.message).replaceAll('\n', ' ')}`
+  })
+}
+
+function plainFrame(state, width, height) {
+  width = Math.max(10, width || 80)
+  height = Math.max(6, height || 24)
+  const runtime = humanRuntime(Date.now() - state.startedAt)
+  const header = `${statusSymbol(state)} ${statusLabel(state.status)}   uptime ${runtime}   ${state.rebuilds} rebuilds`
+  const endpoint = state.endpoint || 'waiting…'
+  let fixed
+  let activityHeight
+
+  if (width < 60 || height < 14) {
+    fixed = [
+      topBorder(state, width),
+      boxLine(header, width),
+      boxLine(state.endpoint || state.watchLabel, width),
+      boxLine(state.activity.at(-1)?.message || 'Starting Wake…', width),
+      boxLine('Resize for details · q/Ctrl-C quit', width),
+    ]
+    activityHeight = 0
+  } else if (width < 80 || height < 20) {
+    fixed = [
+      topBorder(state, width),
+      boxLine(header, width),
+      boxLine(`${state.endpointLabel}  ${endpoint}`, width),
+      boxLine(metricsText(state), width),
+      separator(width, 'ACTIVITY'),
+    ]
+    activityHeight = Math.max(1, height - fixed.length - 2)
+  } else {
+    fixed = [
+      topBorder(state, width),
+      boxLine(header, width),
+      separator(width),
+      boxLine(`${state.endpointLabel.padEnd(7)} ${endpoint}`, width),
+      boxLine(`ROOT    ${state.root}`, width),
+      boxLine(`MODE    ${state.watchLabel}`, width),
+      separator(width),
+      boxLine(metricsText(state), width),
+      separator(width, 'ACTIVITY'),
+    ]
+    activityHeight = Math.max(1, height - fixed.length - 2)
+  }
+
+  for (const row of activityRows(state, activityHeight)) fixed.push(boxLine(row, width))
+  while (activityHeight > 0 && fixed.length < height - 2) fixed.push(boxLine('', width))
+  if (height >= 14) fixed.push(boxLine('↑↓/PgUp/PgDn scroll · End follow · c clear · q/Ctrl-C quit', width))
+  fixed.push(bottomBorder(width))
+  return fixed.slice(0, height)
+}
+
+function colorizeLine(line, ui) {
+  if (!ui.color) return line
+  let value = line
+  value = value.replace('WAKE', ui.brand('WAKE'))
+  value = value.replace(/(✓|■)/, (match) => ui.ok(match))
+  value = value.replace(/(✗)/, (match) => ui.error(match))
+  value = value.replace(/(↻|⠋|⠙|⠹|⠸|⠼|⠴|⠦|⠧|◌)/, (match) => ui.warn(match))
+  value = value.replace(/(https?:\/\/\S+)/, (match) => ui.accent(match))
+  return value
+}
+
+export function renderDashboard(state, width = 80, height = 24, ui = createUi(false)) {
+  return plainFrame(state, width, height).map((line) => colorizeLine(line, ui)).join('\n')
+}
+
+export function createDashboardSession(
+  state,
+  { input = process.stdin, output = process.stderr, ui = createUi() } = {},
+) {
+  let closed = false
+  let previousRaw = false
+  let resolveExit
+  const exit = new Promise((resolve) => { resolveExit = resolve })
+
+  const draw = () => {
+    if (closed) return
+    const width = output.columns || 80
+    const height = output.rows || 24
+    output.write(`\x1b[H${renderDashboard(state, width, height, ui)}\x1b[J`)
+  }
+  const requestExit = (reason) => {
+    if (!closed) resolveExit(reason)
+  }
+  const onData = (chunk) => {
+    const key = chunk.toString('utf8')
+    if (key === '\u0003') requestExit('SIGINT')
+    else if (key === 'q' || key === 'Q') requestExit('q')
+    else if (key === 'c' || key === 'C') {
+      state.activity.length = 0
+      state.scrollFromBottom = 0
+      draw()
+    } else if (key === '\x1b[A') state.scrollFromBottom = Math.max(0, Math.min(state.activity.length - 1, state.scrollFromBottom + 1))
+    else if (key === '\x1b[B') state.scrollFromBottom = Math.max(0, state.scrollFromBottom - 1)
+    else if (key === '\x1b[5~') state.scrollFromBottom = Math.max(0, Math.min(state.activity.length - 1, state.scrollFromBottom + 10))
+    else if (key === '\x1b[6~') state.scrollFromBottom = Math.max(0, state.scrollFromBottom - 10)
+    else if (key === '\x1b[F' || key === '\x1b[4~') state.scrollFromBottom = 0
+    draw()
+  }
+  const onResize = () => draw()
+
+  previousRaw = input.isRaw === true
+  if (typeof input.setRawMode === 'function') input.setRawMode(true)
+  input.resume?.()
+  input.on('data', onData)
+  output.on?.('resize', onResize)
+  output.write('\x1b[?1049h\x1b[?25l\x1b[2J')
+  const timer = setInterval(draw, 100)
+  timer.unref?.()
+  draw()
+
+  return {
+    draw,
+    exit,
+    requestExit,
+    close() {
+      if (closed) return
+      closed = true
+      clearInterval(timer)
+      input.off('data', onData)
+      output.off?.('resize', onResize)
+      if (typeof input.setRawMode === 'function') input.setRawMode(previousRaw)
+      if (!previousRaw) input.pause?.()
+      output.write('\x1b[?25h\x1b[?1049l')
+    },
+  }
+}
+
+export function stripAnsi(value) {
+  return String(value).replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, '')
+}

package/bin/wake.mjs

@@ -9,17 +9,40 @@ import {
   version,
 } from '../index.mjs'
 import { parse, tokenize } from '../experimental.mjs'
+import {
+  applyDashboardEvent,
+  createDashboardSession,
+  createDashboardState,
+  createUi,
+  formatBanner,
+  formatBuildResult,
+  formatError,
+  formatFinalSummary,
+  formatServerReady,
+  observeServer,
+  setDashboardEndpoint,
+  setDashboardStopped,
+  setDashboardStopping,
+  supportsColor,
+  supportsTui,
+} from './terminal.mjs'
 
 const HELP = `Wake ${version()}
 
 Usage:
+  wake [--ui auto|tui|plain] [--no-color] <command>
   wake build [entry] [--outdir DIR] [--cache] [--sourcemap]
   wake dev [root] [--entry FILE] [--host HOST] [--port PORT] [--open]
-  wake docs build [root] [--outdir DIR] [--base PATH]
-  wake docs dev [root] [--host HOST] [--port PORT] [--open]
-  wake parse <file>
-  wake tokenize <file>
+  wake docs build [root] [--mode site|components] [--outdir DIR] [--base PATH]
+  wake docs dev [root] [--mode site|components] [--host HOST] [--port PORT] [--open]
+  wake parse <file> [--format auto|human|json]
+  wake tokenize <file> [--format auto|human|json]
   wake --version
+
+Options:
+  --ui MODE   Terminal UI mode for long-running commands (default: auto)
+  --no-color  Disable terminal colors; also honors NO_COLOR
+  --format    Human or JSON output for parse/tokenize (default: auto)
 `
 
 function takeOption(args, name) {
@@ -44,37 +67,161 @@ function commonOptions(args) {
   }
 }
 
-function printResult(result) {
-  const files = result.files?.length || 0
-  console.log(
-    `wake: built ${result.moduleCount} modules and ${files} files in ${result.durationMs.toFixed(1)}ms`,
-  )
-  if (result.outputDir) console.log(`wake: output ${result.outputDir}`)
+function printLines(lines, output = console.error) {
+  for (const line of lines) output(line)
+}
+
+function validateChoice(value, name, choices) {
+  if (!choices.includes(value)) {
+    throw new Error(`${name} must be one of: ${choices.join(', ')}`)
+  }
+  return value
+}
+
+function ensureStaticMode(uiMode) {
+  if (uiMode === 'tui') {
+    throw new Error('--ui tui is only available for dev and docs dev')
+  }
+}
+
+function resolveTui(uiMode) {
+  const supported = supportsTui()
+  if (uiMode === 'plain') return false
+  if (uiMode === 'tui' && !supported) {
+    throw new Error('--ui tui requires interactive stdin and stderr and a capable terminal')
+  }
+  return supported
 }
 
-async function runServer(factory, options) {
+function resolveFormat(value) {
+  const format = validateChoice(value || 'auto', '--format', ['auto', 'human', 'json'])
+  return format === 'auto' ? (process.stdout.isTTY ? 'human' : 'json') : format
+}
+
+function printResult(ui, result, label, extra = '') {
+  printLines(formatBuildResult(ui, result, label, extra))
+}
+
+function metricsFromEvent(event) {
+  return {
+    modules: event.modules,
+    updatedModules: event.updatedModules,
+    cachedModules: event.cachedModules,
+    chunks: event.chunks,
+    assets: event.assets,
+    durationMs: event.durationMs,
+  }
+}
+
+async function runServer(factory, options, command, root, ui, uiMode) {
   const controller = new AbortController()
-  const server = await factory({ ...options, signal: controller.signal })
-  console.log(`wake: listening on ${server.url}`)
-
-  let stopping = false
-  const stop = async (signal) => {
-    if (stopping) return
-    stopping = true
-    controller.abort()
+  const useTui = resolveTui(uiMode)
+  const state = createDashboardState({
+    command,
+    root: root || '.',
+    watchLabel: command === 'docs dev'
+      ? 'MDX · HMR · search index · watching'
+      : command === 'docs components'
+        ? 'Demo · Controls · HMR · watching'
+        : 'HMR · source maps · watching',
+  })
+  state.version = version()
+  let dashboard
+  let server
+  let stopObserving = () => {}
+  let initialMetrics
+  let finalReason = 'server closed'
+
+  if (useTui) dashboard = createDashboardSession(state, { ui })
+  else printLines(formatBanner(ui, command, version()))
+
+  try {
+    server = await factory({ ...options, signal: controller.signal })
+    setDashboardEndpoint(state, server.url)
+
+    const onRebuildStart = (event) => {
+      applyDashboardEvent(state, event)
+      dashboard?.draw()
+    }
+    const onRebuilt = (event) => {
+      if (event.initial) initialMetrics = metricsFromEvent(event)
+      applyDashboardEvent(state, event)
+      dashboard?.draw()
+    }
+    const onDiagnostic = (diagnostic) => {
+      applyDashboardEvent(state, { type: 'diagnostic', message: diagnostic.message })
+      dashboard?.draw()
+    }
+    const onClosed = () => {
+      applyDashboardEvent(state, { type: 'closed' })
+      dashboard?.draw()
+    }
+    server.on('rebuildStart', onRebuildStart)
+    server.on('rebuilt', onRebuilt)
+    server.on('diagnostic', onDiagnostic)
+    server.on('closed', onClosed)
+
+    if (!useTui) stopObserving = observeServer(server, ui)
+    await new Promise((resolve) => setTimeout(resolve, 35))
+    if (!useTui) {
+      printLines(formatServerReady(ui, server.url, initialMetrics))
+    } else {
+      dashboard.draw()
+    }
+
+    let resolveSignal
+    const signalExit = new Promise((resolve) => { resolveSignal = resolve })
+    const onSigint = () => resolveSignal('SIGINT')
+    const onSigterm = () => resolveSignal('SIGTERM')
+    process.once('SIGINT', onSigint)
+    process.once('SIGTERM', onSigterm)
+
     try {
-      await server.close()
+      const closed = server.waitUntilClosed().then(() => 'closed')
+      const reason = await Promise.race([
+        closed,
+        signalExit,
+        dashboard ? dashboard.exit : new Promise(() => {}),
+      ])
+      if (reason !== 'closed') {
+        finalReason = reason
+        setDashboardStopping(state, reason === 'q' ? 'q' : reason)
+        dashboard?.draw()
+        controller.abort()
+        await server.close()
+        await closed
+      }
+      setDashboardStopped(state)
+      dashboard?.draw()
+      return reason
     } finally {
-      process.exitCode = signal === 'SIGINT' ? 130 : 143
+      process.off('SIGINT', onSigint)
+      process.off('SIGTERM', onSigterm)
+      server.off('rebuildStart', onRebuildStart)
+      server.off('rebuilt', onRebuilt)
+      server.off('diagnostic', onDiagnostic)
+      server.off('closed', onClosed)
+    }
+  } catch (error) {
+    if (dashboard) {
+      dashboard.close()
+      dashboard = undefined
+      printLines(formatBanner(ui, command, version()))
     }
+    throw error
+  } finally {
+    stopObserving()
+    dashboard?.close()
+    if (server) printLines(formatFinalSummary(ui, state, finalReason))
   }
-  process.once('SIGINT', () => void stop('SIGINT'))
-  process.once('SIGTERM', () => void stop('SIGTERM'))
-  await server.waitUntilClosed()
 }
 
 export async function runCli(argv = process.argv.slice(2)) {
   const args = [...argv]
+  const noColor = takeFlag(args, '--no-color')
+  const uiMode = validateChoice(takeOption(args, '--ui') || 'auto', '--ui', ['auto', 'tui', 'plain'])
+  const ui = createUi(!noColor && supportsColor())
+
   if (takeFlag(args, '--version') || takeFlag(args, '-V')) {
     console.log(version())
     return 0
@@ -86,13 +233,15 @@ export async function runCli(argv = process.argv.slice(2)) {
 
   const command = args.shift()
   if (command === 'build') {
+    ensureStaticMode(uiMode)
     const options = commonOptions(args)
     options.outdir = takeOption(args, '--outdir')
     options.cache = takeFlag(args, '--cache')
     options.sourceMap = takeFlag(args, '--sourcemap')
     if (args[0]) options.entry = args.shift()
     if (args.length) throw new Error(`unknown build arguments: ${args.join(' ')}`)
-    printResult(await build(options))
+    printLines(formatBanner(ui, 'build', version()))
+    printResult(ui, await build(options), 'Built')
     return 0
   }
 
@@ -105,8 +254,10 @@ export async function runCli(argv = process.argv.slice(2)) {
     options.open = takeFlag(args, '--open')
     if (args[0]) options.cwd = args.shift()
     if (args.length) throw new Error(`unknown dev arguments: ${args.join(' ')}`)
-    await runServer(startDevServer, options)
-    return process.exitCode || 0
+    const reason = await runServer(startDevServer, options, 'dev', options.cwd, ui, uiMode)
+    if (reason === 'SIGINT') return 130
+    if (reason === 'SIGTERM') return 143
+    return 0
   }
 
   if (command === 'docs') {
@@ -114,6 +265,7 @@ export async function runCli(argv = process.argv.slice(2)) {
     const options = commonOptions(args)
     options.outdir = takeOption(args, '--outdir')
     options.basePath = takeOption(args, '--base')
+    options.mode = validateChoice(takeOption(args, '--mode') || 'site', '--mode', ['site', 'components'])
     options.host = takeOption(args, '--host')
     const port = takeOption(args, '--port')
     if (port) options.port = Number(port)
@@ -121,33 +273,64 @@ export async function runCli(argv = process.argv.slice(2)) {
     if (args[0]) options.cwd = args.shift()
     if (args.length) throw new Error(`unknown docs arguments: ${args.join(' ')}`)
     if (action === 'build') {
-      printResult(await buildDocs(options))
+      ensureStaticMode(uiMode)
+      const components = options.mode === 'components'
+      printLines(formatBanner(ui, components ? 'docs components build' : 'docs build', version()))
+      const result = await buildDocs(options)
+      const count = components ? (result.demos || []).length : (result.routes || []).length
+      const noun = components ? 'demos' : 'routes'
+      printResult(ui, result, components ? 'Component workbench built' : 'Documentation built', `  ${ui.dim('·')} ${count} ${noun}`)
       return 0
     }
     if (action === 'dev') {
-      await runServer(startDocsDevServer, options)
-      return process.exitCode || 0
+      const commandName = options.mode === 'components' ? 'docs components' : 'docs dev'
+      const reason = await runServer(startDocsDevServer, options, commandName, options.cwd, ui, uiMode)
+      if (reason === 'SIGINT') return 130
+      if (reason === 'SIGTERM') return 143
+      return 0
     }
     throw new Error('docs requires build or dev')
   }
 
   if (command === 'parse' || command === 'tokenize') {
+    ensureStaticMode(uiMode)
+    const format = resolveFormat(takeOption(args, '--format'))
     const file = args.shift()
     if (!file || args.length) throw new Error(`${command} requires one source file`)
     const source = await readFile(file, 'utf8')
+    if (format === 'human') printLines(formatBanner(ui, command, version()))
+
     if (command === 'tokenize') {
-      console.log(JSON.stringify(tokenize(source), null, 2))
-    } else {
-      const module = parse(source, {
-        sourceType: file.endsWith('.cjs') ? 'script' : 'module',
-      })
-      try {
+      const result = tokenize(source)
+      if (format === 'json') {
+        console.log(JSON.stringify(result, null, 2))
+      } else {
+        console.log('  START..END    KIND               TEXT')
+        for (const token of result.tokens) {
+          const newline = token.newlineBefore ? ' ↵' : ''
+          console.log(
+            `  ${String(token.start).padStart(5)}..${String(token.end).padEnd(5)} ${String(token.kind).padEnd(18)} ${JSON.stringify(token.text)}${newline}`,
+          )
+        }
+      }
+      return result.diagnostics?.some((diagnostic) => diagnostic.severity === 'error') ? 1 : 0
+    }
+
+    const module = parse(source, {
+      sourceType: file.endsWith('.cjs') ? 'script' : 'module',
+    })
+    try {
+      if (format === 'json') {
         console.log(JSON.stringify(module.summary, null, 2))
-      } finally {
-        module.dispose()
+      } else {
+        console.log(`Parsed ${file}`)
+        console.log(`  Statements ${String(module.summary.statementCount).padEnd(8)} Dependencies ${module.summary.dependencies}`)
+        console.log(`  Source bytes ${module.summary.sourceBytes}`)
       }
+      return module.summary.diagnostics?.some((diagnostic) => diagnostic.severity === 'error') ? 1 : 0
+    } finally {
+      module.dispose()
     }
-    return 0
   }
 
   throw new Error(`unknown command: ${command}`)
@@ -156,10 +339,8 @@ export async function runCli(argv = process.argv.slice(2)) {
 try {
   process.exitCode = await runCli()
 } catch (error) {
-  const code = error?.code ? `[${error.code}] ` : ''
-  console.error(`wake: ${code}${error?.message || error}`)
-  for (const diagnostic of error?.diagnostics || []) {
-    console.error(`  ${diagnostic.severity}: ${diagnostic.message}`)
-  }
+  const noColor = process.argv.includes('--no-color')
+  const ui = createUi(!noColor && supportsColor())
+  printLines(formatError(ui, error))
   process.exitCode = 1
 }

package/index.d.ts

@@ -13,6 +13,7 @@ export interface Diagnostic {
   severity: 'error' | 'warning' | 'note' | 'help'
   code?: string
   message: string
+  path?: string
   start?: number
   end?: number
   notes?: string[]
@@ -47,6 +48,8 @@ export interface OutputFile {
 export interface BuildResult {
   success: true
   moduleCount: number
+  updatedModuleCount: number
+  cachedModuleCount: number
   durationMs: number
   outputDir?: string
   code?: string
@@ -59,6 +62,8 @@ export interface BundleResult extends BuildResult {
   outputDir?: undefined
 }
 
+export type DocsMode = 'site' | 'components'
+
 export interface DocsRoute {
   id: string
   file: string
@@ -72,14 +77,26 @@ export interface DocsRoute {
   draft: boolean
   headings: Array<{ depth: number; title: string; id: string }>
 }
+export interface DocsDemo {
+  id: string
+  title: string
+  group: string
+  component: string
+  order: number
+  controlCount: number
+  warnings: string[]
+}
 
 export interface DocsBuildOptions extends ProjectOptions {
   outdir?: string
   basePath?: string
+  mode?: DocsMode
 }
 
 export interface DocsBuildResult extends BuildResult {
   routes: DocsRoute[]
+  mode: DocsMode
+  demos: DocsDemo[]
 }
 
 export interface DevServerOptions extends ProjectOptions {
@@ -88,6 +105,9 @@ export interface DevServerOptions extends ProjectOptions {
   port?: number
   open?: boolean
 }
+export interface DocsDevServerOptions extends DevServerOptions {
+  mode?: DocsMode
+}
 
 export interface DevServerRebuildStartEvent {
   type: 'rebuildStart'
@@ -96,7 +116,12 @@ export interface DevServerRebuildStartEvent {
 
 export interface DevServerRebuiltEvent {
   type: 'rebuilt'
+  initial: boolean
   modules: number
+  updatedModules: number
+  cachedModules: number
+  chunks: number
+  assets: number
   durationMs: number
 }
 
@@ -126,7 +151,7 @@ export function build(options?: BuildOptions): Promise<BuildResult>
 export function createBuildContext(options?: BuildOptions): Promise<BuildContext>
 export function startDevServer(options?: DevServerOptions): Promise<DevServer>
 export function buildDocs(options?: DocsBuildOptions): Promise<DocsBuildResult>
-export function startDocsDevServer(options?: DevServerOptions): Promise<DevServer>
+export function startDocsDevServer(options?: DocsDevServerOptions): Promise<DevServer>
 
 declare const wake: {
   BuildContext: typeof BuildContext

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crab-dev/wake",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "description": "Wake native web build tools for Node.js",
   "license": "MIT OR Apache-2.0",
   "repository": {
@@ -45,11 +45,11 @@
     "node": ">=22.14 <27"
   },
   "optionalDependencies": {
-    "@crab-dev/wake-win32-x64-msvc": "0.1.2",
-    "@crab-dev/wake-linux-x64-gnu": "0.1.2",
-    "@crab-dev/wake-linux-arm64-gnu": "0.1.2",
-    "@crab-dev/wake-darwin-x64": "0.1.2",
-    "@crab-dev/wake-darwin-arm64": "0.1.2"
+    "@crab-dev/wake-darwin-arm64": "0.1.4",
+    "@crab-dev/wake-darwin-x64": "0.1.4",
+    "@crab-dev/wake-linux-arm64-gnu": "0.1.4",
+    "@crab-dev/wake-linux-x64-gnu": "0.1.4",
+    "@crab-dev/wake-win32-x64-msvc": "0.1.4"
   },
   "publishConfig": {
     "access": "public",