elasticdash-sdk 0.2.0

package/src/cli.ts

@@ -0,0 +1,811 @@
+#!/usr/bin/env node
+import 'dotenv/config'
+import { Command } from 'commander'
+import fg from 'fast-glob'
+import path from 'node:path'
+import { pathToFileURL, fileURLToPath } from 'node:url'
+import { existsSync, copyFileSync, mkdirSync, readFileSync, appendFileSync } from 'node:fs'
+
+import { registerMatchers } from './matchers/index.js'
+import { installAIInterceptor } from './interceptors/ai-interceptor.js'
+import { runFiles } from './runner.js'
+import { reportResults } from './reporter.js'
+import { startBrowserUiServer, type UiEvent } from './browser-ui.js'
+import { startDashboardServer } from './dashboard-server.js'
+import { initObservability, shutdownObservability } from './observability.js'
+import { startPortalServer } from './portal-server.js'
+import { resolveRuntimeModule, scanTools, buildToolArgs, runToolInSubprocess } from './execution/tool-runner.js'
+
+/** Brief, single-line preview of any value for trace event tables. */
+function previewify(value: unknown, maxLen = 200): string {
+  if (value === null || value === undefined) return ''
+  let str: string
+  try {
+    str = typeof value === 'string' ? value : JSON.stringify(value)
+  } catch {
+    str = String(value)
+  }
+  str = str.replace(/\n/g, ' ').trim()
+  return str.length > maxLen ? str.slice(0, maxLen) + '...' : str
+}
+
+function stripAnsi(input?: string): string | undefined {
+  if (!input) return input
+  return input.replace(/\u001b\[[0-9;]*m/g, '')
+}
+
+// --- Config loading (optional) ---
+interface ElasticDashConfig {
+  testMatch?: string[]
+  traceMode?: 'local' | 'remote'
+}
+
+async function loadConfig(cwd: string): Promise<ElasticDashConfig> {
+  const configPath = path.join(cwd, 'elasticdash.config.ts')
+  const configPathJs = path.join(cwd, 'elasticdash.config.js')
+
+  for (const p of [configPath, configPathJs]) {
+    if (existsSync(p)) {
+      try {
+        const mod = await import(pathToFileURL(p).href)
+        return (mod.default ?? {}) as ElasticDashConfig
+      } catch (error) {
+        // Skip this config file if it can't be imported (e.g., .ts when running from built dist)
+        continue
+      }
+    }
+  }
+  return {}
+}
+
+// --- File discovery ---
+async function discoverTestFiles(patterns: string[], cwd: string): Promise<string[]> {
+  const files = await fg(patterns, { cwd, absolute: true })
+  return files.sort()
+}
+
+// --- Validate repository directory ---
+function validateRepoDirectory(cwd: string): boolean {
+  const validFiles = [
+    'elasticdash.config.ts',
+    'elasticdash.config.js',
+    'ed_workflows.ts',
+    'ed_workflows.js',
+    'ed_tools.ts',
+    'ed_tools.js',
+  ]
+  return validFiles.some(file => existsSync(path.join(cwd, file)))
+}
+
+// --- Bootstrap ---
+async function bootstrap(): Promise<void> {
+
+  const cwd = process.cwd()
+  const isInitGuide = process.argv.includes('init-guide')
+
+  // Skip matchers/interceptors for commands that don't need them
+  if (!isInitGuide) {
+    registerMatchers()
+    installAIInterceptor()
+  }
+  if (!isInitGuide && !validateRepoDirectory(cwd)) {
+    console.error(
+      `[elasticdash] Error: elasticdash command must be run from the elasticdash-sdk SDK repository directory.\n` +
+      `Current directory: ${cwd}\n` +
+      `Expected: A directory containing one of: elasticdash.config.ts, elasticdash.config.js, ed_workflows.ts, ed_workflows.js`
+    )
+    process.exit(1)
+  }
+  const config = await loadConfig(cwd)
+  const defaultPattern = config.testMatch ?? ['**/*.ai.test.ts', '**/*.ai.test.js']
+
+  // Read version from package.json
+  // Use require for CJS compatibility, fallback to import if needed
+  // This path is relative to the compiled dist directory
+  let version = 'unknown'
+  try {
+    // @ts-ignore
+    version = (await import(pathToFileURL(path.join(cwd, 'package.json')).href, { with: { type: 'json' } })).default.version
+  } catch (e) {
+    try {
+      version = require(path.join(cwd, 'package.json')).version
+    } catch {}
+  }
+
+
+  const program = new Command()
+
+  program
+    .name('elasticdash')
+    .description('AI-native test runner for ElasticDash workflow testing')
+    .version(version)
+
+  // elasticdash test [dir]
+  program
+    .command('test [dir]')
+    .description('Discover and run all AI test files')
+    .option('--no-browser-ui', 'Disable browser progress UI')
+    .option('--browser-ui-port <port>', 'Port for browser UI', (v) => Number(v), undefined)
+    .action(async (dir?: string, cmd?: any) => {
+      const searchBase = dir ? path.resolve(cwd, dir) : cwd
+      console.log('[elasticdash] Test discovery pattern:', defaultPattern)
+      console.log('[elasticdash] Test search base:', searchBase)
+      const files = await discoverTestFiles(defaultPattern, searchBase)
+      console.log('[elasticdash] Discovered test files:', files)
+
+      if (files.length === 0) {
+        console.error(`No test files found matching: ${defaultPattern.join(', ')}`)
+        process.exit(1)
+      }
+
+      const useBrowserUiEnv = process.env.ELASTICDASH_BROWSER_UI !== '0'
+      const useBrowserUiFlag = cmd?.browserUi !== false
+      const enableBrowserUi = useBrowserUiEnv && useBrowserUiFlag
+
+      const ui = enableBrowserUi
+        ? await startBrowserUiServer({ port: cmd?.browserUiPort, autoOpen: true })
+        : undefined
+
+      if (ui) {
+        ui.send({ type: 'run-start', payload: { files } })
+      }
+
+      const startedAt = Date.now()
+
+      const results = await runFiles(files, {
+        hooks: {
+          onTestStart(name) {
+            ui?.send({ type: 'test-start', payload: { name } })
+          },
+          onTestFinish(name, passed, durationMs, error) {
+            ui?.send({
+              type: 'test-finish',
+              payload: { name, passed, durationMs, errorMessage: stripAnsi(error?.message) },
+            })
+          },
+        },
+      })
+
+      // Log registered tests
+      const { getRegistry } = await import('./core/registry.js')
+      const registry = getRegistry()
+      console.log('[elasticdash] Tests registered:', registry.tests.map(t => t.name))
+      reportResults(results)
+
+      const anyFailed = results.some((fr) => fr.results.some((r) => !r.passed))
+
+      let uiDelayMs = 0
+      if (ui) {
+        const durationMs = Date.now() - startedAt
+        const failures: Array<{ name: string; errorMessage?: string }> = []
+        let totalTests = 0
+        let passedCount = 0
+        for (const fr of results) {
+          for (const r of fr.results) {
+            totalTests += 1
+            if (r.passed) passedCount += 1
+            else failures.push({ name: r.name, errorMessage: stripAnsi(r.error?.message) })
+          }
+        }
+        ui.send({
+          type: 'run-summary',
+          payload: {
+            passed: passedCount,
+            failed: failures.length,
+            total: totalTests,
+            durationMs,
+            failures,
+          },
+        })
+        uiDelayMs = 60000
+      }
+
+      if (uiDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, uiDelayMs))
+        ui?.close()
+      }
+
+      process.exit(anyFailed ? 1 : 0)
+    })
+
+  // elasticdash run <file>
+  program
+    .command('run <file>')
+    .description('Run a single AI test file')
+    .option('--no-browser-ui', 'Disable browser progress UI')
+    .option('--browser-ui-port <port>', 'Port for browser UI', (v) => Number(v), undefined)
+    .action(async (file: string, cmd?: any) => {
+      const absFile = pathToFileURL(path.resolve(cwd, file)).href
+
+      const useBrowserUiEnv = process.env.ELASTICDASH_BROWSER_UI !== '0'
+      const useBrowserUiFlag = cmd?.browserUi !== false
+      const enableBrowserUi = useBrowserUiEnv && useBrowserUiFlag
+      const ui = enableBrowserUi
+        ? await startBrowserUiServer({ port: cmd?.browserUiPort, autoOpen: true })
+        : undefined
+
+      if (ui) {
+        ui.send({ type: 'run-start', payload: { files: [absFile] } })
+      }
+
+      const startedAt = Date.now()
+
+      const results = await runFiles([absFile], {
+        hooks: {
+          onTestStart(name) {
+            ui?.send({ type: 'test-start', payload: { name } })
+          },
+          onTestFinish(name, passed, durationMs, error) {
+            ui?.send({
+              type: 'test-finish',
+              payload: { name, passed, durationMs, errorMessage: stripAnsi(error?.message) },
+            })
+          },
+        },
+      })
+      reportResults(results)
+
+      const anyFailed = results.some((fr) => fr.results.some((r) => !r.passed))
+      let uiDelayMs = 0
+      if (ui) {
+        const durationMs = Date.now() - startedAt
+        const failures: Array<{ name: string; errorMessage?: string }> = []
+        let totalTests = 0
+        let passedCount = 0
+        for (const fr of results) {
+          for (const r of fr.results) {
+            totalTests += 1
+            if (r.passed) passedCount += 1
+            else failures.push({ name: r.name, errorMessage: stripAnsi(r.error?.message) })
+          }
+        }
+        ui.send({
+          type: 'run-summary',
+          payload: {
+            passed: passedCount,
+            failed: failures.length,
+            total: totalTests,
+            durationMs,
+            failures,
+          },
+        })
+        uiDelayMs = 60000
+      }
+
+      if (uiDelayMs > 0) {
+        await new Promise((resolve) => setTimeout(resolve, uiDelayMs))
+        ui?.close()
+      }
+
+      process.exit(anyFailed ? 1 : 0)
+    })
+
+  // elasticdash dashboard
+  program
+    .command('dashboard')
+    .description('Browse and search workflow functions')
+    .option('--port <port>', 'Dashboard server port', (v) => Number(v), process.env.ELASTICDASH_PORT ? Number(process.env.ELASTICDASH_PORT) : 4573)
+    .option('--no-open', 'Skip auto-opening browser')
+    .action(async (options: { port: number; open: boolean }) => {
+      console.log('[elasticdash] Starting dashboard server...')
+      
+      const server = await startDashboardServer(cwd, {
+        port: options.port,
+        autoOpen: options.open,
+      })
+      
+      console.log(`[elasticdash] Dashboard running at ${server.url}`)
+      console.log('[elasticdash] Press Ctrl+C to stop')
+      
+      // Keep the process running with proper cleanup
+      let isShuttingDown = false
+      
+      const cleanup = async () => {
+        if (isShuttingDown) {
+          // Force exit on second Ctrl+C
+          console.log('\n[elasticdash] Force exiting...')
+          process.exit(1)
+        }
+        
+        isShuttingDown = true
+        console.log('\n[elasticdash] Shutting down dashboard server...')
+        
+        try {
+          await Promise.race([
+            server.close(),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('Timeout')), 5000))
+          ])
+          process.exit(0)
+        } catch (error) {
+          console.error('[elasticdash] Error during shutdown:', error)
+          process.exit(1)
+        }
+      }
+      
+      process.once('SIGINT', cleanup)
+      process.once('SIGTERM', cleanup)
+    })
+
+  // elasticdash observe
+  program
+    .command('observe')
+    .description('Start observability mode — stream trace events to ElasticDash backend')
+    .option('--server <url>', 'ElasticDash backend API URL', process.env.ELASTICDASH_API_URL)
+    .option('--api-key <key>', 'Project API key', process.env.ELASTICDASH_API_KEY)
+    .action(async (options: { server?: string; apiKey?: string }) => {
+      const serverUrl = options.server
+      if (!serverUrl) {
+        console.error('[elasticdash] Error: --server or ELASTICDASH_API_URL is required')
+        process.exit(1)
+      }
+
+      const handle = initObservability({
+        serverUrl,
+        apiKey: options.apiKey,
+      })
+
+      console.log(`[elasticdash] Observability active`)
+      console.log(`  Session ID : ${handle.sessionId}`)
+      console.log(`  Server     : ${serverUrl}`)
+      console.log(`[elasticdash] Press Ctrl+C to stop`)
+
+      let isShuttingDown = false
+      const cleanup = async () => {
+        if (isShuttingDown) {
+          process.exit(1)
+        }
+        isShuttingDown = true
+        console.log('\n[elasticdash] Shutting down observability...')
+        await shutdownObservability()
+        process.exit(0)
+      }
+
+      process.once('SIGINT', cleanup)
+      process.once('SIGTERM', cleanup)
+    })
+
+  // elasticdash ed-test — Phase 3 fixture-based CI testing
+  program
+    .command('ed-test')
+    .description('Run ed_tests benchmarks against recorded fixtures')
+    .option('--cwd <path>', 'Root for test discovery')
+    .option('--no-upload', 'Skip uploading results to backend')
+    .option('--filter <pattern>', 'Only run tests matching glob pattern')
+    .option('--reporter <name>', 'Output format: default, json, junit', 'default')
+    .option('--fail-fast', 'Stop after first failing test')
+    .option('--runs <count>', 'Number of times to run each test (passes if any run succeeds)', (v) => Number(v), 1)
+    .action(async (options: {
+      cwd?: string
+      upload?: boolean
+      filter?: string
+      reporter?: string
+      failFast?: boolean
+      runs?: number
+    }) => {
+      // Auto-register tsx loader so .ts test files can be imported.
+      // tsx exposes a register() API for programmatic use.
+      try {
+        const { register } = await import('node:module')
+        register('tsx/esm', import.meta.url)
+      } catch {
+        // tsx or module.register not available — .ts files will fail with a clear error
+      }
+
+      const { runEdTests } = await import('./ci/ed-runner.js')
+      const { createReporter } = await import('./ci/reporters/index.js')
+      const { buildUploadPayload, uploadResults, persistFailedUpload } = await import('./ci/upload-client.js')
+
+      const reporter = createReporter((options.reporter as 'default' | 'json' | 'junit') || 'default')
+      const testCwd = options.cwd ? path.resolve(cwd, options.cwd) : cwd
+
+      let runResult
+      try {
+        runResult = await runEdTests({
+          cwd: testCwd,
+          filter: options.filter,
+          failFast: options.failFast,
+          noUpload: options.upload === false,
+          reporter: (options.reporter as 'default' | 'json' | 'junit') || 'default',
+          runs: options.runs,
+        })
+      } catch (err) {
+        console.error(`[elasticdash] Configuration error: ${err instanceof Error ? err.message : String(err)}`)
+        process.exit(3)
+      }
+
+      if (runResult.results.length === 0) {
+        console.error('[elasticdash] No tests found.')
+        process.exit(3)
+      }
+
+      // Report results
+      for (const r of runResult.results) {
+        reporter.onTestStart(r.testName)
+        reporter.onTestResult(r)
+      }
+
+      // Upload if enabled
+      let uploadUrl: string | undefined
+      const shouldUpload = options.upload !== false
+      const apiKey = process.env.ELASTICDASH_API_KEY
+      const serverUrl = process.env.ELASTICDASH_API_URL
+
+      if (shouldUpload && apiKey && serverUrl) {
+        const payload = buildUploadPayload(runResult)
+        try {
+          const response = await uploadResults(payload, { serverUrl, apiKey })
+          uploadUrl = `${serverUrl.replace(/\/+$/, '')}/runs/${response.runId}`
+        } catch (err) {
+          const errorMsg = err instanceof Error ? err.message : String(err)
+          console.warn(`[elasticdash] Upload failed: ${errorMsg}`)
+          await persistFailedUpload(buildUploadPayload(runResult), errorMsg, testCwd)
+
+          // Exit 4 only if tests themselves passed
+          const hasFailed = runResult.results.some(r => r.status === 'fail')
+          if (!hasFailed) {
+            reporter.onRunComplete(runResult)
+            process.exit(4)
+          }
+        }
+      } else if (shouldUpload && !apiKey) {
+        // In CI, warn about missing API key
+        const isCI = !!(process.env.CI || process.env.GITHUB_ACTIONS || process.env.GITLAB_CI || process.env.CIRCLECI || process.env.BUILDKITE)
+        if (isCI) {
+          console.warn('[elasticdash] Warning: ELASTICDASH_API_KEY not set — skipping upload')
+        }
+      }
+
+      reporter.onRunComplete(runResult, uploadUrl)
+
+      const hasFailed = runResult.results.some(r => r.status === 'fail')
+      process.exit(hasFailed ? 1 : 0)
+    })
+
+  // elasticdash ci
+  program
+    .command('ci')
+    .description('Run CI/CD tests — fetch test groups from backend, execute tests, submit results')
+    .option('--server <url>', 'ElasticDash backend API URL', process.env.ELASTICDASH_API_URL)
+    .option('--api-key <key>', 'Project API key', process.env.ELASTICDASH_API_KEY)
+    .option('--workflow <name>', 'Filter test groups by workflow name')
+    .option('--tags <tags>', 'Filter test groups by tags (comma-separated)')
+    .option('--triggered-by <source>', 'Trigger source', 'ci')
+    .option('--git-branch <branch>', 'Git branch name')
+    .option('--git-commit <sha>', 'Git commit SHA')
+    .option('--git-commit-message <msg>', 'Git commit message')
+    .option('--git-pr-number <number>', 'Pull request number', (v) => Number(v))
+    .option('--git-pr-url <url>', 'Pull request URL')
+    .action(async (options: {
+      server?: string
+      apiKey?: string
+      workflow?: string
+      tags?: string
+      triggeredBy?: string
+      gitBranch?: string
+      gitCommit?: string
+      gitCommitMessage?: string
+      gitPrNumber?: number
+      gitPrUrl?: string
+    }) => {
+      const serverUrl = options.server
+      if (!serverUrl) {
+        console.error('[elasticdash] Error: --server or ELASTICDASH_API_URL is required')
+        process.exit(1)
+      }
+
+      const apiKey = options.apiKey
+      if (!apiKey) {
+        console.error('[elasticdash] Error: --api-key or ELASTICDASH_API_KEY is required')
+        process.exit(1)
+      }
+
+      const { runCI } = await import('./ci/runner.js')
+      const summary = await runCI({
+        serverUrl,
+        apiKey,
+        workflowName: options.workflow,
+        tags: options.tags ? options.tags.split(',').map(s => s.trim()).filter(Boolean) : undefined,
+        triggeredBy: (options.triggeredBy as 'ci' | 'api') || 'ci',
+        gitBranch: options.gitBranch,
+        gitCommit: options.gitCommit,
+        gitCommitMessage: options.gitCommitMessage,
+        gitPrNumber: options.gitPrNumber,
+        gitPrUrl: options.gitPrUrl,
+      })
+
+      process.exit(summary.failed > 0 ? 1 : 0)
+    })
+
+  // elasticdash portal
+  program
+    .command('portal')
+    .description('Start a portal server to receive and execute rerun tasks from ElasticDash backend')
+    .option('--server <url>', 'ElasticDash backend API URL to POST results to', process.env.ELASTICDASH_API_URL)
+    .option('--api-key <key>', 'Project API key', process.env.ELASTICDASH_API_KEY)
+    .option('--port <port>', 'Portal server port', (v) => Number(v), process.env.ELASTICDASH_PORTAL_PORT ? Number(process.env.ELASTICDASH_PORTAL_PORT) : 4574)
+    .option('--allowed-origins <origins>', 'Comma-separated list of additional allowed origin domains', process.env.ELASTICDASH_ALLOWED_ORIGINS)
+    .action(async (options: { server?: string; apiKey?: string; port: number; allowedOrigins?: string }) => {
+      const backendUrl = options.server
+      if (!backendUrl) {
+        console.error('[elasticdash] Error: --server or ELASTICDASH_API_URL is required')
+        process.exit(1)
+      }
+
+      const allowedOrigins = options.allowedOrigins
+        ? options.allowedOrigins.split(',').map(s => s.trim()).filter(Boolean)
+        : undefined
+
+      const handle = await startPortalServer({
+        port: options.port,
+        backendUrl,
+        apiKey: options.apiKey,
+        cwd,
+        allowedOrigins,
+      })
+
+      console.log(`[elasticdash] Portal server running`)
+      console.log(`  URL     : ${handle.url}`)
+      console.log(`  Backend : ${backendUrl}`)
+      console.log(`  Port    : ${handle.port}`)
+      console.log(`[elasticdash] Waiting for tasks from backend... Press Ctrl+C to stop`)
+
+      // Register with backend
+      try {
+        const headers: Record<string, string> = { 'Content-Type': 'application/json' }
+        if (options.apiKey) headers['Authorization'] = `Bearer ${options.apiKey}`
+        const res = await fetch(`${backendUrl}/api/portal/register`, {
+          method: 'POST',
+          headers,
+          body: JSON.stringify({ portalUrl: handle.url }),
+        })
+        if (res.ok) {
+          console.log(`[elasticdash] Registered with backend`)
+        } else {
+          console.warn(`[elasticdash] Backend registration returned ${res.status} — portal will still accept tasks directly`)
+        }
+      } catch {
+        console.warn(`[elasticdash] Could not register with backend — portal will still accept tasks directly`)
+      }
+
+      let isShuttingDown = false
+      const cleanup = async () => {
+        if (isShuttingDown) {
+          process.exit(1)
+        }
+        isShuttingDown = true
+        console.log('\n[elasticdash] Shutting down portal...')
+        await handle.close()
+        process.exit(0)
+      }
+
+      process.once('SIGINT', cleanup)
+      process.once('SIGTERM', cleanup)
+    })
+
+  // elasticdash run-tool <name>
+  program
+    .command('run-tool <name>')
+    .description('Run a single tool by name with given input. Used for rerun validation (e.g. ElasticDash MCP).')
+    .option('--input <json>', 'JSON input to pass to the tool')
+    .option('--input-file <path>', 'Path to JSON file with input')
+    .action(async (name: string, options: { input?: string; inputFile?: string }) => {
+      const toolsModulePath = resolveRuntimeModule(cwd, 'ed_tools')
+      if (!toolsModulePath) {
+        console.error(`[elasticdash] Error: Could not find ed_tools.ts or ed_tools.js in ${cwd}`)
+        process.exit(1)
+      }
+
+      let toolInput: unknown = undefined
+      try {
+        if (options.inputFile) {
+          toolInput = JSON.parse(readFileSync(path.resolve(cwd, options.inputFile), 'utf-8'))
+        } else if (options.input) {
+          toolInput = JSON.parse(options.input)
+        }
+      } catch (err) {
+        console.error(`[elasticdash] Error: Failed to parse input JSON: ${err instanceof Error ? err.message : String(err)}`)
+        process.exit(1)
+      }
+
+      // File-scan is used to compute a positional-arg signature when present,
+      // but a missing scan hit is not fatal: tools defined via edTool() live
+      // in the runtime registry and only resolve once the worker imports the
+      // module. The worker handles "not found" with a clear error.
+      const tools = scanTools(cwd)
+      const tool = tools.find(t => t.name === name)
+
+      const args = buildToolArgs(toolInput, tool)
+      const result = await runToolInSubprocess(toolsModulePath, name, args)
+
+      if (!result.ok) {
+        console.error(`[elasticdash] ${result.error ?? 'Tool execution failed'}`)
+        process.exit(1)
+      }
+
+      const payload = {
+        tool: name,
+        output: result.currentOutput,
+        duration_ms: result.currentDurationMs,
+      }
+      process.stdout.write(JSON.stringify(payload, null, 2) + '\n')
+      // Sentinel line so machine consumers (e.g. ElasticDash MCP) can extract the
+      // result envelope even when project code prints to stdout before us.
+      process.stdout.write('__ED_RUN_TOOL_RESULT__:' + JSON.stringify(payload) + '\n')
+      process.exit(0)
+    })
+
+  // elasticdash run-workflow <name>
+  program
+    .command('run-workflow <name>')
+    .description('Run a single workflow by name with given input. Used for trace-less rerun (e.g. ElasticDash MCP).')
+    .option('--input <json>', 'JSON input to pass to the workflow')
+    .option('--input-file <path>', 'Path to JSON file with input')
+    .option('--timeout-seconds <n>', 'Hard cap on a single run in seconds', (v) => Number(v), 300)
+    .action(async (name: string, options: { input?: string; inputFile?: string; timeoutSeconds: number }) => {
+      const workflowsModulePath = resolveRuntimeModule(cwd, 'ed_workflows')
+      if (!workflowsModulePath) {
+        console.error(`[elasticdash] Error: Could not find ed_workflows.ts or ed_workflows.js in ${cwd}`)
+        process.exit(1)
+      }
+
+      // tsx's in-process `register('tsx/esm', ...)` produces a data:text/javascript URL
+      // that newer Node versions reject as unresolvable. To load TS reliably, re-spawn
+      // ourselves once with `--import tsx` in NODE_OPTIONS so tsx is installed at
+      // process startup (the same approach `runToolInSubprocess` uses for ed_tools.ts).
+      const isTs = workflowsModulePath.endsWith('.ts') || workflowsModulePath.endsWith('.tsx')
+      const nodeOptions = process.env.NODE_OPTIONS ?? ''
+      const tsxAlreadyLoaded = nodeOptions.includes('tsx') || nodeOptions.includes('--import')
+      if (isTs && !tsxAlreadyLoaded) {
+        const { spawn } = await import('node:child_process')
+        const child = spawn(process.execPath, process.argv.slice(1), {
+          env: { ...process.env, NODE_OPTIONS: `${nodeOptions} --import tsx`.trim() },
+          cwd,
+          stdio: 'inherit',
+        })
+        const exitCode: number = await new Promise(resolve => {
+          child.on('exit', code => resolve(code ?? 0))
+          child.on('error', () => resolve(1))
+        })
+        process.exit(exitCode)
+      }
+
+      let workflowInput: unknown = undefined
+      try {
+        if (options.inputFile) {
+          workflowInput = JSON.parse(readFileSync(path.resolve(cwd, options.inputFile), 'utf-8'))
+        } else if (options.input) {
+          workflowInput = JSON.parse(options.input)
+        }
+      } catch (err) {
+        console.error(`[elasticdash] Error: Failed to parse input JSON: ${err instanceof Error ? err.message : String(err)}`)
+        process.exit(1)
+      }
+
+      let mod: Record<string, unknown>
+      try {
+        mod = await import(pathToFileURL(workflowsModulePath).href) as Record<string, unknown>
+      } catch (err) {
+        console.error(`[elasticdash] Error: Failed to import ${workflowsModulePath}: ${err instanceof Error ? err.message : String(err)}`)
+        process.exit(1)
+      }
+
+      const workflowFn = mod[name] as ((input?: unknown) => unknown) | undefined
+      if (typeof workflowFn !== 'function') {
+        console.error(`[elasticdash] Error: Workflow '${name}' not found or not a function in ${workflowsModulePath}`)
+        process.exit(1)
+      }
+
+      const { runWorkflow } = await import('./workflow-runner.js')
+
+      const startedAt = Date.now()
+      let runError: string | undefined
+      let timedOut = false
+      let traceId: string | null = null
+      let output: unknown = null
+      let events: Array<Record<string, unknown>> = []
+
+      try {
+        const runPromise = runWorkflow(async () => workflowFn(workflowInput))
+        const timeoutPromise = new Promise((_, reject) => {
+          setTimeout(() => {
+            timedOut = true
+            reject(new Error(`workflow '${name}' timed out after ${options.timeoutSeconds}s`))
+          }, options.timeoutSeconds * 1000)
+        })
+        const runResult = await Promise.race([runPromise, timeoutPromise]) as { result: unknown; trace: { traceId: string; events: Array<{ id: number; type: string; name: string; input: unknown; output: unknown; durationMs: number }> } }
+        output = runResult.result
+        traceId = runResult.trace?.traceId ?? null
+        events = (runResult.trace?.events ?? []).map((e) => {
+          const out = e.output as Record<string, unknown> | null | undefined
+          const hasError = out !== null && typeof out === 'object' && out !== null && 'error' in out
+          return {
+            id: e.id,
+            type: e.type,
+            name: e.name,
+            duration_ms: e.durationMs,
+            has_error: hasError,
+            input_preview: previewify(e.input),
+            output_preview: previewify(e.output),
+          }
+        })
+      } catch (err) {
+        runError = err instanceof Error ? err.message : String(err)
+      }
+      const endedAt = Date.now()
+
+      const envelope = {
+        workflow: name,
+        trace_id: traceId,
+        output,
+        duration_ms: endedAt - startedAt,
+        started_at: startedAt,
+        ended_at: endedAt,
+        events,
+        status: runError ? (timedOut ? 'timed_out' : 'failed') : 'completed',
+        ...(runError ? { error: runError } : {}),
+      }
+
+      process.stdout.write(JSON.stringify(envelope, null, 2) + '\n')
+      process.stdout.write('__ED_RUN_WORKFLOW_RESULT__:' + JSON.stringify(envelope) + '\n')
+      process.exit(runError ? 1 : 0)
+    })
+
+  // elasticdash init-guide
+  program
+    .command('init-guide')
+    .description('Copy the ElasticDash agent coding instructions into your project')
+    .option('--target <path>', 'Destination file path', 'AGENTS.md')
+    .option('--force', 'Overwrite the file instead of appending')
+    .action(async (cmd: { target: string; force?: boolean }) => {
+      const targetPath = path.resolve(cwd, cmd.target)
+
+      // Resolve docs from the SDK's own docs/ directory
+      const thisFile = fileURLToPath(import.meta.url)
+      const docsDir = path.resolve(path.dirname(thisFile), '..', 'docs')
+      const instructionsSrc = path.resolve(docsDir, 'agent-coding-instructions.md')
+
+      if (!existsSync(instructionsSrc)) {
+        console.error(`[elasticdash] Could not find agent coding instructions at ${instructionsSrc}`)
+        process.exit(1)
+      }
+
+      // Ensure target directory exists
+      const targetDir = path.dirname(targetPath)
+      if (!existsSync(targetDir)) {
+        mkdirSync(targetDir, { recursive: true })
+      }
+
+      const guideContent = readFileSync(instructionsSrc, 'utf-8')
+
+      if (existsSync(targetPath) && !cmd.force) {
+        // Check if instructions are already appended
+        const existing = readFileSync(targetPath, 'utf-8')
+        if (existing.includes('ElasticDash SDK — AI Coding Agent Instructions')) {
+          console.log(`[elasticdash] ${cmd.target} already contains the ElasticDash agent instructions. Use --force to replace the file.`)
+          process.exit(0)
+        }
+
+        // Append to existing file
+        appendFileSync(targetPath, '\n\n---\n\n' + guideContent)
+        console.log(`[elasticdash] ElasticDash agent instructions appended to ${cmd.target}`)
+      } else {
+        // Create new file or overwrite with --force
+        copyFileSync(instructionsSrc, targetPath)
+        console.log(`[elasticdash] Agent coding instructions written to ${cmd.target}`)
+      }
+
+      console.log()
+      console.log(`  Tell your coding agent:`)
+      console.log()
+      console.log(`    Read ${cmd.target} and follow it to integrate elasticdash-sdk into this project.`)
+      console.log()
+      process.exit(0)
+    })
+
+  await program.parseAsync(process.argv)
+}
+
+bootstrap().catch((err) => {
+  console.error(err)
+  process.exit(1)
+})