haltija 1.1.0

package/bin/format-test.mjs

@@ -0,0 +1,183 @@
+/**
+ * Text formatter for Haltija test results
+ *
+ * Flat step list, agent-scannable and human-readable.
+ *
+ *   ok Login flow 2340ms 7/7
+ *     1 ok navigate /login 120ms
+ *     2 ok type #email "user@example.com" 85ms
+ *     3 ok click button[type=submit] 200ms
+ *     4 FAIL wait .dashboard 5000ms timeout
+ *       > element not found, page shows: [.error-message]
+ *     5 skip assert url /dashboard
+ *   patience 4/5 remaining streak=1 timeout=7000ms
+ *   ---
+ *   hj test-run --json
+ */
+
+/**
+ * Format a single test result
+ * @param {object} result - TestRunResult from POST /test/run
+ * @returns {string} formatted text output with footer
+ */
+export function formatTestResult(result) {
+  if (!result) return '(no result)\n---\nhj test-run --json'
+
+  const lines = []
+  const status = result.passed ? 'ok' : 'FAIL'
+  const name = result.test || 'unnamed'
+  const duration = result.duration ? `${result.duration}ms` : ''
+  const counts = result.summary
+    ? `${result.summary.passed}/${result.summary.total}`
+    : ''
+
+  // Header
+  lines.push([status, name, duration, counts].filter(Boolean).join(' '))
+
+  // Steps
+  if (result.steps) {
+    for (const step of result.steps) {
+      const stepStatus = step.passed ? 'ok' : (step.error === 'skipped' ? 'skip' : 'FAIL')
+      const desc = formatStepDescription(step)
+      const dur = step.duration ? `${step.duration}ms` : ''
+      const err = (!step.passed && step.error && step.error !== 'skipped')
+        ? step.error
+        : ''
+
+      lines.push(`  ${step.index + 1} ${[stepStatus, desc, dur, err].filter(Boolean).join(' ')}`)
+
+      // Failure context detail
+      if (!step.passed && step.context) {
+        const detail = formatFailureContext(step.context)
+        if (detail) lines.push(`    > ${detail}`)
+      }
+    }
+  }
+
+  // Patience stats
+  if (result.patience) {
+    const p = result.patience
+    lines.push(`  patience ${p.remaining}/${p.allowed} remaining streak=${p.consecutiveFailures}/${p.streak} timeout=${p.finalTimeoutMs}ms`)
+  }
+
+  // Footer
+  lines.push('---')
+  lines.push('hj test-run --json')
+
+  return lines.join('\n')
+}
+
+/**
+ * Format a suite result
+ * @param {object} result - SuiteRunResult from POST /test/suite
+ * @returns {string} formatted text output with footer
+ */
+export function formatSuiteResult(result) {
+  if (!result) return '(no result)\n---\nhj test-run --json'
+
+  const lines = []
+  const status = result.summary?.failed === 0 ? 'ok' : 'FAIL'
+  const duration = result.duration ? `${result.duration}ms` : ''
+  const counts = result.summary
+    ? `${result.summary.passed}/${result.summary.total} tests`
+    : ''
+
+  // Header
+  lines.push([status, 'suite', duration, counts].filter(Boolean).join(' '))
+
+  // Per-test summary lines
+  if (result.results) {
+    for (const testResult of result.results) {
+      const tStatus = testResult.passed ? 'ok' : 'FAIL'
+      const name = testResult.test || 'unnamed'
+      const dur = testResult.duration ? `${testResult.duration}ms` : ''
+      const tCounts = testResult.summary
+        ? `${testResult.summary.passed}/${testResult.summary.total}`
+        : ''
+      lines.push(`  ${[tStatus, name, dur, tCounts].filter(Boolean).join(' ')}`)
+
+      // Show first failure for failed tests
+      if (!testResult.passed && testResult.steps) {
+        const failed = testResult.steps.find(s => !s.passed)
+        if (failed) {
+          const desc = formatStepDescription(failed)
+          const err = failed.error || ''
+          lines.push(`    step ${failed.index + 1}: ${[desc, err].filter(Boolean).join(' ')}`)
+          if (failed.context) {
+            const detail = formatFailureContext(failed.context)
+            if (detail) lines.push(`    > ${detail}`)
+          }
+        }
+      }
+    }
+  }
+
+  // Footer
+  lines.push('---')
+  lines.push('hj test-run --json')
+
+  return lines.join('\n')
+}
+
+/**
+ * Extract action + key identifier from a step
+ */
+function formatStepDescription(step) {
+  const s = step.step || step
+  const action = s.action || step.description || ''
+
+  switch (action) {
+    case 'navigate':
+      return `navigate ${s.url || ''}`
+    case 'click':
+      return `click ${s.selector || s.ref || ''}`
+    case 'type':
+      return `type ${s.selector || s.ref || ''} "${truncate(s.text || '', 30)}"`
+    case 'key':
+      return `key ${s.key || ''}`
+    case 'wait':
+      return `wait ${s.selector || s.duration + 'ms' || ''}`
+    case 'assert': {
+      const a = s.assertion || {}
+      const sel = a.selector || ''
+      const val = a.text || a.value || a.pattern || ''
+      return `assert ${a.type || ''} ${sel} ${val ? '"' + truncate(val, 30) + '"' : ''}`.trim()
+    }
+    case 'eval':
+      return `eval ${truncate(s.code || '', 40)}`
+    case 'verify':
+      return `verify ${truncate(s.eval || '', 40)}`
+    default:
+      return step.description || action || 'unknown'
+  }
+}
+
+/**
+ * Format failure context into a single line
+ */
+function formatFailureContext(context) {
+  const parts = []
+
+  if (context.reason) {
+    parts.push(context.reason)
+  }
+
+  if (context.buttonsOnPage?.length) {
+    parts.push(`page shows: [${context.buttonsOnPage.join(', ')}]`)
+  }
+
+  if (context.actual !== undefined && context.expected !== undefined) {
+    parts.push(`expected "${context.expected}" got "${context.actual}"`)
+  }
+
+  if (context.suggestion) {
+    parts.push(context.suggestion)
+  }
+
+  return parts.join(', ')
+}
+
+function truncate(str, max) {
+  if (!str || str.length <= max) return str
+  return str.slice(0, max - 1) + '…'
+}

package/bin/format-tree.mjs

@@ -0,0 +1,165 @@
+/**
+ * Text formatter for Haltija tree output
+ * 
+ * Push/pop paren encoding: hierarchy for agents, indentation for humans.
+ *
+ *   1 body
+ *   ( 2 div.header
+ *     3 button#submit "Submit" interactive
+ *     4 input#email interactive value="user@example.com"
+ *   )
+ *   ( 5 div.content
+ *     ( 6 ul.nav
+ *       7 li "Home"
+ *       8 li "About"
+ *     )
+ *     9 p "Welcome back"
+ *   )
+ *   ---
+ *   hj tree --json
+ */
+
+const MAX_TEXT_LEN = 80
+
+/**
+ * Format a DomTreeNode tree as agent+human readable text
+ * @param {object} node - DomTreeNode from server response
+ * @param {number} indent - current indentation level (internal)
+ * @returns {string} formatted text output with footer
+ */
+export function formatTree(node, indent = 0) {
+  if (!node) return ''
+
+  const lines = []
+  formatNode(node, indent, lines)
+
+  // Footer: JSON escape hatch
+  lines.push('---')
+  lines.push('hj tree --json')
+
+  return lines.join('\n')
+}
+
+/**
+ * Recursively format a node and its children
+ */
+function formatNode(node, indent, lines) {
+  if (!node) return
+
+  // Skip the haltija widget entirely
+  if (node.tag === 'haltija-dev') return
+
+  const prefix = ' '.repeat(indent)
+  const hasChildren = (node.children && node.children.length > 0) ||
+    (node.shadowChildren && node.shadowChildren.length > 0)
+
+  const line = buildLine(node)
+
+  if (hasChildren) {
+    // Push: ( before children
+    lines.push(`${prefix}( ${line}`)
+
+    // Recurse children
+    if (node.children) {
+      for (const child of node.children) {
+        formatNode(child, indent + 2, lines)
+      }
+    }
+    if (node.shadowChildren) {
+      for (const child of node.shadowChildren) {
+        if (child.classes && child.classes.includes('widget')) continue
+        formatNode(child, indent + 2, lines)
+      }
+    }
+
+    // Pop: )
+    lines.push(`${prefix})`)
+  } else {
+    // Leaf node: just the line
+    lines.push(`${prefix}${line}`)
+  }
+}
+
+/**
+ * Build a single node's description line (without prefix/indent)
+ */
+function buildLine(node) {
+  const parts = []
+
+  // Ref number (bare, no colon)
+  parts.push(node.ref || '?')
+
+  // Tag with id and classes
+  let tagPart = node.tag || '?'
+  if (node.id) tagPart += `#${node.id}`
+  if (node.classes && node.classes.length) {
+    tagPart += '.' + node.classes.join('.')
+  }
+  parts.push(tagPart)
+
+  // Attributes (key=value, quote values with spaces)
+  if (node.attrs) {
+    for (const [key, val] of Object.entries(node.attrs)) {
+      if (val === '' || val === 'true') {
+        parts.push(key)
+      } else if (/\s/.test(val) || val.length > 40) {
+        parts.push(`${key}="${truncate(val, 40)}"`)
+      } else {
+        parts.push(`${key}=${val}`)
+      }
+    }
+  }
+
+  // Form value (for inputs)
+  if (node.value !== undefined && node.value !== '') {
+    parts.push(`value="${truncate(node.value, 30)}"`)
+  }
+  if (node.checked !== undefined) {
+    parts.push(node.checked ? 'checked' : 'unchecked')
+  }
+
+  // Flags (bare words, no brackets)
+  const flags = formatFlags(node.flags)
+  if (flags) parts.push(flags)
+
+  // Text content (quoted, at end)
+  if (node.text) {
+    parts.push(`"${truncate(node.text, MAX_TEXT_LEN)}"`)
+  }
+
+  // Truncation indicator
+  if (node.truncated && node.childCount) {
+    parts.push(`(${node.childCount} children)`)
+  }
+
+  return parts.join(' ')
+}
+
+/** Format flags as bare space-separated words */
+function formatFlags(flags) {
+  if (!flags) return ''
+  const parts = []
+
+  if (flags.interactive) parts.push('interactive')
+  if (flags.disabled) parts.push('disabled')
+  if (flags.required) parts.push('required')
+  if (flags.readOnly) parts.push('readonly')
+  if (flags.focused) parts.push('focused')
+  if (flags.hidden && flags.hiddenReason) {
+    parts.push(`hidden:${flags.hiddenReason}`)
+  } else if (flags.hidden) {
+    parts.push('hidden')
+  }
+  if (flags.offScreen && !flags.hidden) parts.push('offscreen')
+  if (flags.customElement) parts.push('custom')
+  if (flags.hasAria) parts.push('aria')
+
+  return parts.join(' ')
+}
+
+/** Truncate a string with ellipsis */
+function truncate(str, max) {
+  if (!str) return ''
+  if (str.length <= max) return str
+  return str.slice(0, max - 1) + '…'
+}

package/bin/hj.mjs

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+/**
+ * hj - Short alias for haltija CLI subcommands
+ * 
+ * Usage:
+ *   hj tree              # DOM tree
+ *   hj click @42         # Click by ref
+ *   hj type @10 hello    # Type text
+ *   hj eval 1+1          # Eval JS
+ *   hj status            # Server status
+ */
+
+import { runSubcommand, isSubcommand, getSuggestion, listSubcommands } from './cli-subcommand.mjs'
+
+const args = process.argv.slice(2)
+
+if (!args.length || args.includes('--help') || args.includes('-h')) {
+  const bold = (s) => `\x1b[1m${s}\x1b[0m`
+  const dim = (s) => `\x1b[2m${s}\x1b[0m`
+  console.log(`
+${bold('hj')} - Haltija command-line interface
+
+Usage: hj <command> [args...]
+${listSubcommands()}
+Run ${dim('hj --help')} for this help.
+Run ${dim('haltija --help')} for server/app options.
+`)
+  process.exit(0)
+}
+
+// Parse --port option
+let port = process.env.DEV_CHANNEL_PORT || '8700'
+const portIdx = args.indexOf('--port')
+if (portIdx !== -1 && args[portIdx + 1]) {
+  port = args[portIdx + 1]
+  args.splice(portIdx, 2)
+}
+
+const subcommand = args[0]
+const subArgs = args.slice(1).filter(a => a !== '--window' || true) // keep all args
+
+if (!isSubcommand(subcommand)) {
+  const suggestion = getSuggestion(subcommand)
+  if (suggestion === '--help') {
+    console.log(listSubcommands())
+    process.exit(0)
+  }
+  
+  let msg = `Unknown command: '${subcommand}'`
+  if (suggestion) {
+    msg += ` — did you mean '${suggestion}'?`
+  }
+  console.error(msg)
+  console.error(`\nExamples: hj tree, hj navigate <url>, hj click @42`)
+  console.error(`Run 'hj' for docs.`)
+  process.exit(1)
+} else {
+  runSubcommand(subcommand, subArgs, port)
+}

package/bin/mcp-setup.mjs

@@ -0,0 +1,288 @@
+#!/usr/bin/env node
+/**
+ * haltija-mcp-setup - Configure Claude Code to use Haltija
+ *
+ * Usage:
+ *   npx haltija-mcp-setup          # Create .mcp.json in current directory
+ *   npx haltija-mcp-setup --global # Add to user's Claude Code config
+ *   npx haltija-mcp-setup --check  # Check if Haltija MCP is configured
+ *   npx haltija-mcp-setup --help   # Show help
+ */
+
+import { existsSync, readFileSync, writeFileSync, unlinkSync } from 'fs'
+import { homedir } from 'os'
+import { join, dirname } from 'path'
+import { fileURLToPath } from 'url'
+import { execSync, spawnSync } from 'child_process'
+
+const __dirname = dirname(fileURLToPath(import.meta.url))
+const args = process.argv.slice(2)
+
+// Colors for terminal output
+const green = (s) => `\x1b[32m${s}\x1b[0m`
+const yellow = (s) => `\x1b[33m${s}\x1b[0m`
+const red = (s) => `\x1b[31m${s}\x1b[0m`
+const bold = (s) => `\x1b[1m${s}\x1b[0m`
+const dim = (s) => `\x1b[2m${s}\x1b[0m`
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+${bold('haltija-mcp-setup')} - Configure Claude Code to use Haltija
+
+${bold('Usage:')}
+  npx haltija-mcp-setup          Create .mcp.json in current directory (recommended)
+  npx haltija-mcp-setup --global Add to user's global Claude Code config
+  npx haltija-mcp-setup --check  Check current MCP configuration status
+  npx haltija-mcp-setup --remove Remove Haltija from MCP configuration
+  npx haltija-mcp-setup --help   Show this help
+
+${bold('What this does:')}
+  Configures Claude Code to connect to the Haltija server, giving Claude
+  native tools for browser control: click, type, query DOM, take screenshots, etc.
+
+${bold('Prerequisites:')}
+  1. Haltija server running: ${dim('bunx haltija')}
+  2. Claude Code installed
+
+${bold('After setup:')}
+  Restart Claude Code to load the new MCP server.
+`)
+  process.exit(0)
+}
+
+// Find the MCP server path
+function findMcpServerPath() {
+  // Check if we're in the haltija package
+  const localPath = join(__dirname, '../apps/mcp/build/index.js')
+  if (existsSync(localPath)) {
+    return localPath
+  }
+
+  // Check for globally installed package
+  try {
+    const result = spawnSync('npm', ['root', '-g'], { encoding: 'utf8' })
+    if (result.status === 0) {
+      const globalPath = join(result.stdout.trim(), 'tosijs-dev/apps/mcp/build/index.js')
+      if (existsSync(globalPath)) {
+        return globalPath
+      }
+    }
+  } catch {}
+
+  // Check node_modules in current directory
+  const nodeModulesPath = join(process.cwd(), 'node_modules/tosijs-dev/apps/mcp/build/index.js')
+  if (existsSync(nodeModulesPath)) {
+    return nodeModulesPath
+  }
+
+  return null
+}
+
+// Check if Claude Code is installed
+function isClaudeCodeInstalled() {
+  const claudeJsonPath = join(homedir(), '.claude.json')
+  return existsSync(claudeJsonPath)
+}
+
+// Get project-level .mcp.json path
+function getProjectMcpPath() {
+  return join(process.cwd(), '.mcp.json')
+}
+
+// Get user-level claude.json path
+function getClaudeJsonPath() {
+  return join(homedir(), '.claude.json')
+}
+
+// Check current configuration
+function checkConfig() {
+  console.log(bold('\nHaltija MCP Configuration Status\n'))
+
+  // Check Claude Code installation
+  if (isClaudeCodeInstalled()) {
+    console.log(green('✓') + ' Claude Code is installed')
+  } else {
+    console.log(red('✗') + ' Claude Code not detected (~/.claude.json missing)')
+    console.log(dim('  Install Claude Code from: https://claude.ai/code'))
+  }
+
+  // Check project-level config
+  const projectMcpPath = getProjectMcpPath()
+  if (existsSync(projectMcpPath)) {
+    try {
+      const config = JSON.parse(readFileSync(projectMcpPath, 'utf8'))
+      if (config.mcpServers?.haltija) {
+        console.log(green('✓') + ` Project .mcp.json has Haltija configured`)
+        console.log(dim(`  Path: ${projectMcpPath}`))
+      } else {
+        console.log(yellow('○') + ' Project .mcp.json exists but Haltija not configured')
+      }
+    } catch {
+      console.log(red('✗') + ' Project .mcp.json exists but is invalid JSON')
+    }
+  } else {
+    console.log(dim('○') + ' No project-level .mcp.json')
+  }
+
+  // Check MCP server build
+  const mcpPath = findMcpServerPath()
+  if (mcpPath) {
+    console.log(green('✓') + ' MCP server found')
+    console.log(dim(`  Path: ${mcpPath}`))
+  } else {
+    console.log(red('✗') + ' MCP server not found')
+    console.log(dim('  Run from haltija directory or install globally'))
+  }
+
+  // Check if Haltija server is running
+  try {
+    execSync('curl -s http://localhost:8700/status', { encoding: 'utf8', timeout: 2000 })
+    console.log(green('✓') + ' Haltija server is running on port 8700')
+  } catch {
+    console.log(yellow('○') + ' Haltija server not running')
+    console.log(dim('  Start with: bunx haltija'))
+  }
+
+  console.log('')
+}
+
+// Create or update .mcp.json
+function setupProjectConfig() {
+  const mcpPath = findMcpServerPath()
+  if (!mcpPath) {
+    console.log(red('Error:') + ' Could not find Haltija MCP server.')
+    console.log('Make sure you run this from the haltija directory or have it installed.')
+    process.exit(1)
+  }
+
+  const projectMcpPath = getProjectMcpPath()
+  let config = { mcpServers: {} }
+
+  // Read existing config if present
+  if (existsSync(projectMcpPath)) {
+    try {
+      config = JSON.parse(readFileSync(projectMcpPath, 'utf8'))
+      if (!config.mcpServers) {
+        config.mcpServers = {}
+      }
+    } catch {
+      console.log(yellow('Warning:') + ' Existing .mcp.json is invalid, creating new one')
+      config = { mcpServers: {} }
+    }
+  }
+
+  // Check if already configured
+  if (config.mcpServers.haltija) {
+    console.log(yellow('Haltija is already configured in .mcp.json'))
+    console.log(dim('Use --remove to remove it, or delete .mcp.json manually'))
+    process.exit(0)
+  }
+
+  // Add Haltija configuration
+  config.mcpServers.haltija = {
+    command: 'node',
+    args: [mcpPath]
+  }
+
+  writeFileSync(projectMcpPath, JSON.stringify(config, null, 2) + '\n')
+
+  console.log(green('✓') + ' Created .mcp.json with Haltija configuration')
+  console.log(dim(`  Path: ${projectMcpPath}`))
+  console.log('')
+  console.log(bold('Next steps:'))
+  console.log('  1. Restart Claude Code to load the MCP server')
+  console.log('  2. Start Haltija if not running: ' + dim('bunx haltija'))
+  console.log('  3. Haltija tools (click, type, query, etc.) will be available in Claude')
+  console.log('')
+}
+
+// Add to global Claude Code config
+function setupGlobalConfig() {
+  const mcpPath = findMcpServerPath()
+  if (!mcpPath) {
+    console.log(red('Error:') + ' Could not find Haltija MCP server.')
+    process.exit(1)
+  }
+
+  // Try using claude CLI first
+  try {
+    execSync(`claude mcp add haltija node "${mcpPath}" --scope user`, {
+      encoding: 'utf8',
+      stdio: 'inherit'
+    })
+    console.log('')
+    console.log(green('✓') + ' Added Haltija to global Claude Code configuration')
+    console.log('')
+    console.log(bold('Next steps:'))
+    console.log('  1. Restart Claude Code to load the MCP server')
+    console.log('  2. Start Haltija if not running: ' + dim('bunx haltija'))
+    console.log('')
+    return
+  } catch {
+    // Fall back to manual config
+  }
+
+  // Manual fallback
+  const claudeJsonPath = getClaudeJsonPath()
+  if (!existsSync(claudeJsonPath)) {
+    console.log(red('Error:') + ' Claude Code config not found at ~/.claude.json')
+    console.log('Make sure Claude Code is installed.')
+    process.exit(1)
+  }
+
+  console.log(yellow('Note:') + ' Could not use claude CLI, please add manually:')
+  console.log('')
+  console.log('Run: ' + bold(`claude mcp add haltija node "${mcpPath}" --scope user`))
+  console.log('')
+  console.log('Or add to ~/.claude.json under your project\'s mcpServers:')
+  console.log(dim(JSON.stringify({ haltija: { command: 'node', args: [mcpPath] } }, null, 2)))
+  console.log('')
+}
+
+// Remove Haltija configuration
+function removeConfig() {
+  const projectMcpPath = getProjectMcpPath()
+
+  if (!existsSync(projectMcpPath)) {
+    console.log('No .mcp.json found in current directory')
+    process.exit(0)
+  }
+
+  try {
+    const config = JSON.parse(readFileSync(projectMcpPath, 'utf8'))
+    if (config.mcpServers?.haltija) {
+      delete config.mcpServers.haltija
+
+      // Remove file if no other servers, otherwise update
+      if (Object.keys(config.mcpServers).length === 0) {
+        unlinkSync(projectMcpPath)
+        console.log(green('✓') + ' Removed .mcp.json (no other MCP servers configured)')
+      } else {
+        writeFileSync(projectMcpPath, JSON.stringify(config, null, 2) + '\n')
+        console.log(green('✓') + ' Removed Haltija from .mcp.json')
+      }
+    } else {
+      console.log('Haltija is not configured in .mcp.json')
+    }
+  } catch (err) {
+    console.log(red('Error:') + ' Failed to parse .mcp.json')
+    process.exit(1)
+  }
+}
+
+// Main
+if (args.includes('--check')) {
+  checkConfig()
+} else if (args.includes('--global')) {
+  setupGlobalConfig()
+} else if (args.includes('--remove')) {
+  removeConfig()
+} else {
+  // Default: project-level setup
+  if (!isClaudeCodeInstalled()) {
+    console.log(yellow('Warning:') + ' Claude Code not detected (~/.claude.json missing)')
+    console.log('This setup configures Haltija for Claude Code.')
+    console.log('')
+  }
+  setupProjectConfig()
+}

package/bin/server.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env bun
+/**
+ * Dev Channel Server CLI
+ * 
+ * Run with: bun run packages/tosijs-dev/bin/server.ts
+ * Or after install: tosijs-dev
+ */
+
+import '../src/server'