ace-demo 0.18.1 → 0.23.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 52bcbe78edb6ed9c85b9aa166c0aeb6eddcc7f2c3abf2fc308c6948d11b10e2a
-  data.tar.gz: 0ffc6151eabe9b4a7cf758c5e16befd95795e9fccf798ba6314e4db502033ddb
+  metadata.gz: 5cc7670ccb96a23d9ca6e12d3e4678f9a6bbc91d18ff9ac88254365e68304547
+  data.tar.gz: ad71cad734a5660dfe3a1c8a888f10914eddd2c49c427628680aa5ee5d755d58
 SHA512:
-  metadata.gz: 3fbf0d84492ae0e797bfc18fafac44e0c3346c7ed68f73113452aa58cd388de3d0c1079df772bae8172fd81c980fce3a07ce7b03cc1e4fbbfb46742995cbeea3
-  data.tar.gz: 9bbebcb303c7fe7a5f46f41dc07c9c624b4461e320e56c67c91999355ceb0d32f29797fb9ccccae2bd2db6d8be1ed82471c46f972f80977b349f19f13d8422f2
+  metadata.gz: 6aae377964291267ddcee9d8b809306bd3a9cd7c46bb6c87660757f46554f00e1ce9ee9aef8619e998f68a8dc89ab2152c22951d9d19b7f3c15d88e9dd7ff79d
+  data.tar.gz: 3b9daed37bff26a8bb486baf96d59a839dcfdaaa0b4d6175a7044ffb476c0b98ddd21ff7c4abbbafc942fc09657d2de220da5c9d73ac88698aa7d6ce1c5b7b70

data/.ace-defaults/demo/config.yml

@@ -1,3 +1,8 @@
 vhs_bin: vhs
+asciinema_bin: asciinema
+agg_bin: agg
+agg_font_family: Hack Nerd Font Mono
 output_dir: .ace-local/demo
 sandbox_dir: .ace-local/demo/sandbox
+record:
+  backend: asciinema

data/CHANGELOG.md

@@ -7,6 +7,160 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.23.0] - 2026-03-28
+
+### Changed
+- Switched YAML asciinema tape recording to an interactive shell session so demo commands are recorded visibly in casts by default instead of only being inferred from compiled script execution.
+
+### Fixed
+- Wait for the initial shell prompt before sending the first tape command, preventing the first command from being dropped in interactive asciinema recordings.
+- Normalized invalid `0x0` cast terminal headers before AGG conversion so interactive asciinema recordings convert cleanly to GIF output.
+- Updated cast verification to recognize echoed interactive shell commands from the new default recording path.
+
+### Technical
+- Reworked asciinema execution to drive the recorded PTY directly, preserving command ordering and shell session state across YAML tape scenes.
+- Expanded recorder, executor, verifier, and command-builder coverage for the interactive YAML asciinema path.
+
+## [0.22.4] - 2026-03-27
+
+### Fixed
+- Corrected default `agg_font_family` from `CaskaydiaMono Nerd Font` to `Hack Nerd Font Mono` to match spike-validated font available in the environment.
+
+## [0.22.3] - 2026-03-27
+
+### Fixed
+- Validated asciinema tape `sleep` durations before script compilation to block malformed/injected values.
+
+### Changed
+- Added `agg_font_family` default/config plumbing through YAML parsing, recorder conversion, and cast attachment conversion.
+
+### Technical
+- Expanded parser/recorder/attacher/asciinema compiler test coverage for font-family wiring and sleep validation behavior.
+
+## [0.22.2] - 2026-03-27
+
+### Fixed
+- Cleaned up temporary GIF conversion artifacts generated from `.cast` attachments after upload/comment orchestration completes.
+
+### Changed
+- Centralized recording backend/format validation in `RecordOptionValidator` and reused it across planner, recorder, and CLI flows.
+
+### Technical
+- Added validator-focused atom tests and updated attacher tests to assert temporary artifact lifecycle behavior.
+
+## [0.22.1] - 2026-03-27
+
+### Fixed
+- Escaped asciinema `--command` script paths to handle spaces and shell metacharacters safely.
+- Updated `CastVerifier` to validate command-mode asciinema recordings by inspecting script commands from cast header metadata.
+- Prevented `.cast` conversion during `attach --dry-run` while preserving planned GIF naming in preview output.
+- Improved missing-binary errors for asciinema and agg executors to report configured executable names.
+
+### Changed
+- Simplified YAML record planner backend/format validation by removing a redundant unreachable guard.
+- Updated dry-run upload planning to allow planned artifact paths without requiring generated files.
+
+### Technical
+- Expanded atom/molecule/organism test coverage for escaped command generation, command-mode cast verification, dry-run cast attachment behavior, dry-run uploader planning, and configured binary error reporting.
+
+## [0.22.0] - 2026-03-27
+
+### Added
+- Added cast verification primitives (`CastFileParser`, `CastVerifier`, and cast/verification models) for asciinema recording validation.
+- Added `.cast` attachment support that converts recordings to GIF before PR upload/comment posting.
+
+### Changed
+- Updated asciinema record flow to run non-blocking command-presence verification and expose verification status in CLI output.
+- Updated `attach` command help and error handling to include `.cast` source files and agg conversion failures.
+- Updated usage documentation for automatic cast verification and `.cast -> .gif` attachment behavior.
+
+### Technical
+- Expanded atom, molecule, organism, and model test coverage for cast parsing, verification outcomes, recorder integration, and cast attachment conversion.
+
+## [0.21.0] - 2026-03-27
+
+### Added
+- Added backend selection support for `ace-demo record` with `--backend` and YAML `settings.backend`.
+- Added `RecordingResult` model to return structured recording output metadata (backend, visual path, optional cast path).
+
+### Changed
+- Switched YAML tape recording default backend to asciinema with cast capture and AGG conversion to GIF.
+- Updated YAML planning and CLI validation so backend/format constraints are enforced with actionable errors.
+- Updated usage documentation for backend defaults, cast output visibility, and compatibility formatting rules.
+
+### Technical
+- Expanded parser, recorder, and CLI test coverage for backend routing, format guards, and structured recorder output.
+
+## [0.20.0] - 2026-03-27
+
+### Added
+- Added asciinema-native recording support with command-building and execution pipeline components.
+- Added AGG post-processing support to compile asciinema recordings into final demo artifacts.
+
+### Changed
+- Updated demo recording orchestration to support multi-backend execution and asciinema-to-AGG compatibility flows.
+- Updated demo defaults/config to enable asciinema adapter behavior for task-driven recording workflows.
+
+### Technical
+- Added atom and molecule test coverage for asciinema/AGG command builders and executors.
+- Expanded smoke and pipeline tests for getting-started tape behavior under the new recording backend flow.
+
+## [0.19.4] - 2026-03-26
+
+### Added
+- Added `ace-demo-tapeyml-recording-options.tape.yml` demo tape with fixtures showing `playback_speed` and `output` settings in action.
+- Added `fixtures/sample-project/demo.tape.yml` fixture for demo sandbox recording.
+
+### Changed
+- Updated `ace-demo-getting-started.tape.yml` with `playback_speed` and `output` settings example.
+
+## [0.19.3] - 2026-03-26
+
+### Fixed
+- Unified YAML recording planning across dry-run preview and execution so unsupported `settings.format` values fail consistently.
+
+### Changed
+- Centralized YAML format/speed/output-path planning into a shared helper reused by both CLI context building and `DemoRecorder`.
+
+### Technical
+- Added dry-run regression coverage to assert YAML tapes with unsupported `settings.format` are rejected.
+
+## [0.19.2] - 2026-03-26
+
+### Fixed
+- Reject blank or whitespace-only YAML `settings.output` values during parsing to prevent unusable expanded output paths.
+
+### Changed
+- Updated tape record context resolution so live runs surface unresolved tape refs immediately while dry-run keeps preview fallback behavior.
+
+### Technical
+- Removed the obsolete `dry_run_preview_for_tape` path and expanded parser/CLI regression coverage for output validation and YAML tape routing.
+
+## [0.19.1] - 2026-03-26
+
+### Fixed
+- Honor CLI `--output` as the retime target when YAML defines `settings.playback_speed` but omits `settings.output`.
+
+### Changed
+- Align tape-mode precedence handoff by passing parsed YAML spec and resolved context from CLI to `DemoRecorder`.
+
+### Technical
+- Added regression coverage for YAML speed + CLI output precedence and pre-parsed YAML spec reuse in recorder tests.
+
+## [0.19.0] - 2026-03-26
+
+### Added
+- Added support for `settings.playback_speed` and `settings.output` in `.tape.yml` for self-contained `ace-demo record` execution.
+- Added parser contract tests for new YAML settings and invalid speed handling.
+
+### Changed
+- Updated YAML tape recording flow to support retime-only output mode when both speed and output are set (raw stays in `.ace-local/demo`, retimed output writes to the exact configured path).
+- Updated CLI tape-mode precedence so `--playback-speed` and `--output` override tape settings while preserving YAML defaults when flags are omitted.
+- Updated getting-started and usage documentation plus example demo tape to reflect tape-defined speed/output behavior.
+
+### Technical
+- Expanded recorder and CLI test coverage for speed-only, output-only, combined mode, dry-run preview messaging, and override precedence.
+
 ## [0.18.1] - 2026-03-23
 
 ### Fixed

data/README.md

@@ -3,7 +3,7 @@
 
   Record terminal sessions as proof-of-work evidence for pull requests.
 
-  <img src="https://raw.githubusercontent.com/cs3b/ace/main/docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
+  <img src="../docs/brand/AgenticCodingEnvironment.Logo.XS.jpg" alt="ACE Logo" width="480">
   <br><br>
 
   <a href="https://rubygems.org/gems/ace-demo"><img alt="Gem Version" src="https://img.shields.io/gem/v/ace-demo.svg" /></a>

data/lib/ace/demo/atoms/agg_command_builder.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+module Ace
+  module Demo
+    module Atoms
+      module AggCommandBuilder
+        module_function
+
+        def build(input_path:, output_path:, font_size: nil, theme: nil, font_family: nil, agg_bin: "agg")
+          cmd = [agg_bin]
+          cmd.concat(["--font-size", font_size.to_s]) unless font_size.nil?
+          cmd.concat(["--theme", theme.to_s]) if present?(theme)
+          cmd.concat(["--font-family", font_family.to_s]) if present?(font_family)
+          cmd.concat([input_path, output_path])
+          cmd
+        end
+
+        def present?(value)
+          !value.nil? && !value.to_s.strip.empty?
+        end
+        private_class_method :present?
+      end
+    end
+  end
+end

data/lib/ace/demo/atoms/asciinema_command_builder.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Ace
+  module Demo
+    module Atoms
+      module AsciinemaCommandBuilder
+        module_function
+
+        # cast_compatibility is accepted to keep the interface aligned with task
+        # requirements; v3 passthrough is currently the proven production path.
+        def build(output_path:, script_path: nil, shell_command: nil, tty_size: "80x24", cast_compatibility: :v2, asciinema_bin: "asciinema")
+          validate_cast_compatibility!(cast_compatibility)
+
+          command = shell_command.to_s.strip
+          if command.empty?
+            escaped_script_path = Shellwords.escape(script_path.to_s)
+            command = "bash #{escaped_script_path}"
+          end
+
+          cmd = [asciinema_bin, "rec", "--overwrite", "--command", command]
+          cmd.concat(tty_size_flags(tty_size))
+          cmd << output_path
+          cmd
+        end
+
+        def tty_size_flags(tty_size)
+          return [] if tty_size.nil? || tty_size.to_s.strip.empty?
+
+          cols, rows = tty_size.to_s.split("x", 2)
+          if cols.to_s.empty? || rows.to_s.empty? || cols !~ /\A\d+\z/ || rows !~ /\A\d+\z/
+            raise ArgumentError, "tty_size must be formatted as <cols>x<rows> (e.g. 80x24)"
+          end
+
+          ["--cols", cols, "--rows", rows]
+        end
+        private_class_method :tty_size_flags
+
+        def validate_cast_compatibility!(cast_compatibility)
+          return if %i[v2 v3 auto].include?(cast_compatibility)
+
+          raise ArgumentError, "cast_compatibility must be one of: :v2, :v3, :auto"
+        end
+        private_class_method :validate_cast_compatibility!
+      end
+    end
+  end
+end

data/lib/ace/demo/atoms/asciinema_tape_compiler.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require "shellwords"
+
+module Ace
+  module Demo
+    module Atoms
+      module AsciinemaTapeCompiler
+        module_function
+
+        def compile(spec:, default_timeout: "2s")
+          settings = spec["settings"] || {}
+          lines = [
+            "#!/usr/bin/env bash",
+            "set -euo pipefail",
+            ""
+          ]
+
+          env = settings["env"] || {}
+          env.each do |key, value|
+            lines << "export #{key}=#{Shellwords.escape(value.to_s)}"
+          end
+          lines << "" unless env.empty?
+
+          spec.fetch("scenes", []).each do |scene|
+            scene_name = scene["name"]
+            lines << "# Scene: #{scene_name}" unless scene_name.to_s.strip.empty?
+
+            scene.fetch("commands", []).each do |command|
+              lines << command.fetch("type")
+              sleep_value = validate_sleep!(command["sleep"] || default_timeout)
+              lines << "sleep #{sleep_value}"
+              lines << ""
+            end
+          end
+
+          lines.join("\n").rstrip + "\n"
+        end
+
+        def validate_sleep!(value)
+          sleep_value = value.to_s.strip
+          pattern = /\A\d+(?:\.\d+)?(?:ms|s|m|h)?\z/
+          return sleep_value if sleep_value.match?(pattern)
+
+          raise ArgumentError, "sleep must be a numeric duration (e.g. 0.5s, 250ms, 2)"
+        end
+        private_class_method :validate_sleep!
+      end
+    end
+  end
+end

data/lib/ace/demo/atoms/cast_file_parser.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Ace
+  module Demo
+    module Atoms
+      module CastFileParser
+        module_function
+
+        def parse(path)
+          raise CastParseError, "Cast file not found: #{path}" unless File.exist?(path)
+
+          header = nil
+          events = []
+
+          File.foreach(path).with_index(1) do |line, line_number|
+            stripped = line.strip
+            next if stripped.empty?
+
+            json = JSON.parse(stripped)
+            if header.nil?
+              header = parse_header(json, path: path)
+            else
+              events << parse_event(json, path: path, line_number: line_number)
+            end
+          rescue JSON::ParserError => e
+            raise CastParseError, "Invalid JSON in #{path}:#{line_number}: #{e.message}"
+          end
+
+          raise CastParseError, "Missing cast header in #{path}" if header.nil?
+
+          Models::CastRecording.new(header: header, events: events)
+        end
+
+        def parse_header(json, path:)
+          unless json.is_a?(Hash)
+            raise CastParseError, "Invalid cast header in #{path}: expected JSON object"
+          end
+
+          json
+        end
+        private_class_method :parse_header
+
+        def parse_event(json, path:, line_number:)
+          unless json.is_a?(Array) && json.length == 3
+            raise CastParseError,
+              "Invalid cast event in #{path}:#{line_number}: expected [timestamp, type, data]"
+          end
+
+          time, type, data = json
+          unless type.is_a?(String) && !type.empty?
+            raise CastParseError, "Invalid cast event type in #{path}:#{line_number}"
+          end
+
+          Models::CastEvent.new(time: time, type: type, data: data)
+        end
+        private_class_method :parse_event
+      end
+    end
+  end
+end

data/lib/ace/demo/atoms/demo_yaml_parser.rb

@@ -66,11 +66,42 @@ module Ace
           normalized["width"] = integer_or_nil(settings["width"], "settings.width", source_path)
           normalized["height"] = integer_or_nil(settings["height"], "settings.height", source_path)
           normalized["format"] = settings["format"]&.to_s
+          normalized["agg_font_family"] = settings["agg_font_family"]&.to_s if settings.key?("agg_font_family")
+          normalized["backend"] = normalize_backend(settings["backend"], source_path) if settings.key?("backend")
+          normalized["playback_speed"] = normalize_playback_speed(settings["playback_speed"], source_path) if settings.key?("playback_speed")
+          normalized["output"] = normalize_output_path(settings["output"], source_path) if settings.key?("output")
           normalized["env"] = normalize_env(settings["env"], source_path: source_path) if settings.key?("env")
           normalized
         end
         private_class_method :normalize_settings
 
+        def normalize_backend(value, source_path)
+          backend = value.to_s.strip.downcase
+          allowed = %w[asciinema vhs]
+          return backend if allowed.include?(backend)
+
+          raise DemoYamlParseError, "Unknown backend '#{backend}'. Valid: asciinema, vhs (#{source_path})"
+        end
+        private_class_method :normalize_backend
+
+        def normalize_playback_speed(value, source_path)
+          parsed = Atoms::PlaybackSpeedParser.parse(value)
+          parsed && parsed[:label]
+        rescue ArgumentError => e
+          raise DemoYamlParseError, "#{e.message} (#{source_path})"
+        end
+        private_class_method :normalize_playback_speed
+
+        def normalize_output_path(value, source_path)
+          normalized = value&.to_s
+          if normalized.nil? || normalized.strip.empty?
+            raise DemoYamlParseError, "settings.output must be a non-empty path in #{source_path}"
+          end
+
+          normalized
+        end
+        private_class_method :normalize_output_path
+
         def normalize_env(env, source_path:)
           return {} if env.nil?
           raise DemoYamlParseError, "settings.env must be a map in #{source_path}" unless env.is_a?(Hash)

data/lib/ace/demo/atoms/record_option_validator.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Ace
+  module Demo
+    module Atoms
+      module RecordOptionValidator
+        module_function
+
+        MP4_UNSUPPORTED_ERROR =
+          "Unsupported format: mp4. Use gif, or use --backend vhs --format webm for compatibility output."
+
+        def normalize_backend(value)
+          return nil if value.nil?
+
+          backend = value.to_s.strip.downcase
+          return backend if %w[asciinema vhs].include?(backend)
+
+          raise ArgumentError, "Unknown backend '#{backend}'. Valid: asciinema, vhs"
+        end
+
+        def normalize_format(value, supported_formats:, allow_nil: true)
+          return nil if value.nil? && allow_nil
+
+          format = value.to_s.downcase
+          raise ArgumentError, MP4_UNSUPPORTED_ERROR if format == "mp4"
+          raise ArgumentError, "Unsupported format: #{format}" unless supported_formats.include?(format)
+
+          format
+        end
+
+        def validate_yaml_backend_format!(backend:, format:)
+          return unless format == "webm" && backend != "vhs"
+
+          raise ArgumentError, "Format 'webm' requires --backend vhs when recording YAML tapes"
+        end
+
+        def validate_raw_tape_backend!(backend:)
+          return if backend.nil? || backend == "vhs"
+
+          raise ArgumentError, "Raw .tape recordings support backend 'vhs' only"
+        end
+      end
+    end
+  end
+end

data/lib/ace/demo/atoms/vhs_tape_compiler.rb

@@ -26,8 +26,12 @@ module Ace
             lines << "# Scene: #{scene_name}" unless scene_name.to_s.strip.empty?
 
             scene.fetch("commands", []).each do |command|
-              escaped = command.fetch("type").gsub("\\", "\\\\\\\\").gsub('"', '\\"')
-              lines << "Type \"#{escaped}\""
+              type_text = command.fetch("type")
+              if type_text.include?('"') || type_text.include?("$") || type_text.include?("\\")
+                lines << "Type `#{type_text}`"
+              else
+                lines << "Type \"#{type_text}\""
+              end
               lines << "Enter"
               lines << "Sleep #{command["sleep"] || default_timeout}"
               lines << ""

data/lib/ace/demo/atoms/yaml_record_planner.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+module Ace
+  module Demo
+    module Atoms
+      module YamlRecordPlanner
+        module_function
+
+        def plan(
+          tape_path:,
+          output:,
+          format:,
+          playback_speed:,
+          retime_output:,
+          yaml_spec:,
+          yaml_parser:,
+          supported_formats:,
+          default_output_path_builder:,
+          backend: nil,
+          default_backend: "asciinema"
+        )
+          spec = yaml_spec || yaml_parser.parse_file(tape_path)
+          settings = spec["settings"] || {}
+          selected_backend = RecordOptionValidator.normalize_backend(backend || settings["backend"] || default_backend)
+          selected_format = RecordOptionValidator.normalize_format(
+            format || settings["format"] || "gif",
+            supported_formats: supported_formats,
+            allow_nil: false
+          )
+          RecordOptionValidator.validate_yaml_backend_format!(backend: selected_backend, format: selected_format)
+
+          selected_speed = playback_speed.nil? ? settings["playback_speed"] : playback_speed
+          selected_speed = Atoms::PlaybackSpeedParser.parse(selected_speed)
+          selected_output = output.nil? ? settings["output"] : output
+          selected_retime_output = retime_output || selected_output
+
+          default_output_path = File.expand_path(default_output_path_builder.call(selected_format), Dir.pwd)
+          raw_output_path, retime_output_path = resolve_output_paths(
+            default_output_path: default_output_path,
+            output: selected_output,
+            speed: selected_speed,
+            retime_output: selected_retime_output
+          )
+
+          {
+            spec: spec,
+            backend: selected_backend,
+            format: selected_format,
+            speed: selected_speed,
+            selected_output: selected_output,
+            raw_output_path: raw_output_path,
+            retime_output_path: retime_output_path
+          }
+        end
+
+        def resolve_output_paths(default_output_path:, output:, speed:, retime_output:)
+          return [default_output_path, nil] if output.nil? && speed.nil?
+          return [File.expand_path(output, Dir.pwd), nil] if output && speed.nil?
+          return [default_output_path, File.expand_path(retime_output, Dir.pwd)] if retime_output
+          return [default_output_path, nil] if output.nil?
+
+          [default_output_path, File.expand_path(output, Dir.pwd)]
+        end
+        private_class_method :resolve_output_paths
+      end
+    end
+  end
+end

data/lib/ace/demo/cli/commands/attach.rb

@@ -12,7 +12,7 @@ module Ace
 
           desc "Attach an existing demo recording to a PR"
 
-          argument :file, required: true, desc: "Recording file path (GIF, MP4, or WebM)"
+          argument :file, required: true, desc: "Recording file path (GIF, MP4, WebM, or .cast)"
           option :pr, type: :string, desc: "PR number"
           option :dry_run, type: :boolean, aliases: ["-n"], default: false, desc: "Preview only"
 
@@ -23,7 +23,8 @@ module Ace
             attacher = Organisms::DemoAttacher.new
             result = attacher.attach(file: file, pr: pr, dry_run: options[:dry_run])
             Atoms::AttachOutputPrinter.print(result)
-          rescue ArgumentError, PrNotFoundError, GhAuthenticationError, GhUploadError, GhCommentError, GhCommandError => e
+          rescue ArgumentError, PrNotFoundError, GhAuthenticationError, GhUploadError, GhCommentError, GhCommandError,
+            AggNotFoundError, AggExecutionError => e
             raise Ace::Support::Cli::Error, e.message
           end
         end