@specsage/cli 0.1.0

package/lib/cli.rb

@@ -0,0 +1,140 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# SpecSage CLI entry point for npm package
+# This file is spawned by the Node wrapper (bin/specsage.js)
+
+require 'optparse'
+require 'fileutils'
+
+# Set the package root directory
+SPECSAGE_HOME = File.expand_path('..', __dir__)
+
+# Add lib directory to load path
+$LOAD_PATH.unshift(File.join(SPECSAGE_HOME, 'lib'))
+
+require 'runner'
+require 'results_uploader'
+
+class SpecSageCLI
+  def initialize(args)
+    @args = args
+    @options = {
+      visible: false,
+      record: true,
+      server_url: nil,
+      ci_mode: false
+    }
+  end
+
+  def run
+    parse_options!
+
+    unless @options[:ci_mode]
+      puts "Error: --ci flag is required"
+      exit 1
+    end
+
+    run_ci_mode
+  end
+
+  private
+
+  def parse_options!
+    parser = OptionParser.new do |opts|
+      opts.banner = "Usage: specsage --ci [options]"
+
+      opts.on("--ci", "CI mode (required)") do
+        @options[:ci_mode] = true
+      end
+
+      opts.on("-v", "--visible", "Run browser in visible mode") do
+        @options[:visible] = true
+      end
+
+      opts.on("--no-record", "Disable video recording") do
+        @options[:record] = false
+      end
+
+      opts.on("-s", "--server URL", "Server URL") do |url|
+        @options[:server_url] = url
+      end
+
+      opts.on("-h", "--help", "Show help") do
+        puts opts
+        exit 0
+      end
+    end
+
+    parser.parse!(@args)
+  end
+
+  def run_ci_mode
+    website = ENV['TARGET_WEBSITE_SLUG']
+    api_key = ENV['SPEC_SAGE_API_KEY']
+
+    unless website
+      puts "Error: TARGET_WEBSITE_SLUG environment variable required"
+      exit 1
+    end
+
+    unless api_key
+      puts "Error: SPEC_SAGE_API_KEY environment variable required"
+      exit 1
+    end
+
+    puts "SpecSage CI Mode"
+    puts "=" * 50
+    puts "Website: #{website}"
+    puts ""
+
+    publisher = ResultsUploader.new(
+      base_url: @options[:server_url],
+      api_key: api_key
+    )
+
+    begin
+      ci_run = publisher.create_ci_run(website)
+    rescue ResultsUploader::UploadError => e
+      puts "Error: #{e.message}"
+      exit 1
+    end
+
+    server_run_id = ci_run['server_run_id']
+    base_url = ci_run['base_url']
+
+    puts "Server run ID: #{server_run_id}"
+    puts "Base URL: #{base_url}"
+    puts ""
+
+    runner = Runner.new(
+      { 'base_url' => base_url },
+      visible: @options[:visible],
+      record: @options[:record],
+      publisher: publisher,
+      server_run_id: server_run_id
+    )
+
+    verdict = runner.run
+
+    puts ""
+    puts "=" * 50
+    puts "SpecSage CI Run Complete"
+    puts "=" * 50
+    puts "Verdict: #{verdict}"
+    puts ""
+
+    case verdict
+    when 'PASS'
+      exit 0
+    when 'FAIL'
+      exit 1
+    else
+      exit 2
+    end
+  end
+end
+
+if __FILE__ == $PROGRAM_NAME
+  SpecSageCLI.new(ARGV).run
+end

package/lib/dialogs.js

@@ -0,0 +1,106 @@
+/**
+ * Dialog handling module for SpecSage browser automation.
+ * Captures JavaScript dialogs (alert, confirm, prompt) and exposes them
+ * to the AI agent via visual overlays and pseudo-elements.
+ */
+
+// Pending dialog state
+let pendingDialog = null;
+let page = null;
+
+/**
+ * Set up the dialog handler on a Playwright page.
+ * Captures dialogs without auto-resolving them.
+ *
+ * IMPORTANT: When a dialog is open, Playwright blocks all page interactions
+ * (evaluate, screenshot, etc.). The dialog must be accepted/dismissed first.
+ * We store the dialog info synchronously for the AI to see in the elements list.
+ */
+export function setupDialogHandler(playwrightPage) {
+  page = playwrightPage;
+
+  page.on('dialog', dialog => {
+    // Store dialog info synchronously - don't await anything here
+    // because the page is blocked until the dialog is resolved
+    pendingDialog = {
+      type: dialog.type(),
+      message: dialog.message(),
+      defaultValue: dialog.defaultValue(),
+      dialog: dialog
+    };
+    // Note: Cannot inject overlay while dialog is blocking the page
+  });
+}
+
+/**
+ * Check if a dialog is currently pending.
+ */
+export function hasDialog() {
+  return pendingDialog !== null;
+}
+
+/**
+ * Get the pending dialog message (for error messages).
+ */
+export function getDialogInfo() {
+  if (!pendingDialog) return null;
+  return { type: pendingDialog.type, message: pendingDialog.message };
+}
+
+/**
+ * Returns a pseudo-element representing the dialog for the elements list.
+ */
+export function getDialogPseudoElement() {
+  if (!pendingDialog) return null;
+
+  return {
+    id: 'DIALOG',
+    stable_key: 'dialog|pending',
+    type: 'dialog',
+    role: pendingDialog.type,
+    accessible_name: pendingDialog.message,
+    visible_text: pendingDialog.message,
+    disabled: false,
+    input_type: pendingDialog.type === 'prompt' ? 'text' : null,
+    default_value: pendingDialog.defaultValue || null,
+    bounding_box: { x: 390, y: 300, w: 500, h: 200 },
+    mechanism: 'browser',
+    source: 'javascript_dialog'
+  };
+}
+
+/**
+ * Accept the pending dialog.
+ * @param {string} [value] - Optional value for prompt dialogs
+ */
+export async function acceptDialog(value) {
+  if (!pendingDialog) {
+    throw new Error('No dialog to accept');
+  }
+
+  const dialog = pendingDialog.dialog;
+  pendingDialog = null;
+
+  // Accept resolves the dialog and unblocks the page
+  // Only pass value if it's a non-empty string (for prompt dialogs)
+  if (value && typeof value === 'string') {
+    await dialog.accept(value);
+  } else {
+    await dialog.accept();
+  }
+}
+
+/**
+ * Dismiss the pending dialog.
+ */
+export async function dismissDialog() {
+  if (!pendingDialog) {
+    throw new Error('No dialog to dismiss');
+  }
+
+  const dialog = pendingDialog.dialog;
+  pendingDialog = null;
+
+  // Dismiss resolves the dialog and unblocks the page
+  await dialog.dismiss();
+}

package/lib/results_uploader.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'uri'
+require 'json'
+
+class ResultsUploader
+  DEFAULT_BASE_URL = 'https://api.specsage.com'
+  VERSION = '0.1.0'
+
+  class UploadError < StandardError; end
+
+  attr_reader :base_url, :api_key
+
+  def initialize(base_url: nil, api_key: nil)
+    @base_url = base_url || DEFAULT_BASE_URL
+    @api_key = api_key || ENV['SPEC_SAGE_API_KEY']
+  end
+
+  # Fetch all scenario definitions from the server
+  # Returns array of scenario definition hashes
+  def fetch_scenario_definitions
+    response = get('/api/scenario_definitions')
+    response['scenario_definitions'] || []
+  end
+
+  # Fetch a single scenario definition by ID
+  # Returns scenario definition hash
+  def fetch_scenario_definition(id)
+    response = get("/api/scenario_definitions/#{id}")
+    response['scenario_definition']
+  end
+
+  # Create a new run on the server
+  # Returns server_run_id
+  def create_run
+    response = post('/api/runs', {
+      runner: {
+        os: RUBY_PLATFORM.split('-').last,
+        arch: RUBY_PLATFORM.split('-').first,
+        version: VERSION
+      }
+    })
+
+    response['server_run_id']
+  end
+
+  # Finalize a run on the server
+  def finalize_run(server_run_id)
+    post("/api/runs/#{server_run_id}/finalize", {})
+  end
+
+  # Create a CI run - server selects scenarios based on website's "ci" tag
+  # Returns hash with server_run_id and base_url
+  def create_ci_run(website_identifier)
+    post('/api/v1/ci/runs', { website: website_identifier })
+  end
+
+  private
+
+  def get(path)
+    uri = URI.parse("#{@base_url}#{path}")
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    http.open_timeout = 10
+    http.read_timeout = 30
+
+    request = Net::HTTP::Get.new(uri.request_uri)
+    request['Accept'] = 'application/json'
+    request['Authorization'] = "Bearer #{@api_key}" if @api_key
+
+    response = http.request(request)
+    handle_response(response, path)
+  rescue Errno::ECONNREFUSED
+    raise UploadError, "Could not connect to server at #{@base_url}"
+  end
+
+  def post(path, body)
+    uri = URI.parse("#{@base_url}#{path}")
+    http = Net::HTTP.new(uri.host, uri.port)
+    http.use_ssl = uri.scheme == 'https'
+    http.open_timeout = 10
+    http.read_timeout = 30
+
+    request = Net::HTTP::Post.new(uri.request_uri)
+    request['Content-Type'] = 'application/json'
+    request['Accept'] = 'application/json'
+    request['Authorization'] = "Bearer #{@api_key}" if @api_key
+    request.body = body.to_json
+
+    response = http.request(request)
+    handle_response(response, path)
+  rescue Errno::ECONNREFUSED
+    raise UploadError, "Could not connect to server at #{@base_url}"
+  end
+
+  def handle_response(response, path)
+    parsed = parse_response_body(response)
+
+    case response
+    when Net::HTTPSuccess
+      parsed
+    when Net::HTTPNotFound
+      raise UploadError, "Not found: #{parsed['error'] || path}"
+    when Net::HTTPConflict
+      raise UploadError, "Conflict: #{parsed['error']}"
+    when Net::HTTPUnprocessableEntity
+      errors = parsed['errors'] || parsed['details'] || [parsed['error']]
+      raise UploadError, "Validation failed: #{Array(errors).join(', ')}"
+    else
+      raise UploadError, "Server error #{response.code}: #{parsed['error'] || response.message}"
+    end
+  end
+
+  def parse_response_body(response)
+    body = response.body.to_s
+    content_type = response['Content-Type'].to_s
+
+    if body.empty?
+      return {}
+    end
+
+    unless content_type.include?('application/json')
+      snippet = body.length > 200 ? "#{body[0, 200]}..." : body
+      raise UploadError, "Expected JSON response but got #{content_type.inspect}: #{snippet}"
+    end
+
+    JSON.parse(body)
+  rescue JSON::ParserError => e
+    snippet = body.length > 200 ? "#{body[0, 200]}..." : body
+    raise UploadError, "Invalid JSON response from server: #{e.message}. Body: #{snippet}"
+  end
+end