stream_weaver 0.3.0

data/lib/stream_weaver/canvas/gist_store.rb

@@ -0,0 +1,135 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'time'
+require 'fileutils'
+require 'securerandom'
+
+module StreamWeaver
+  module Canvas
+    # Persistent record of gists StreamWeaver has published on the user's
+    # behalf, so a later session can find "the gist for this doc" without
+    # keeping any in-memory session state.
+    #
+    # Unlike DocStore (one file per doc, resolved via a 3-tier git-aware
+    # path), GistStore is a single flat JSON file holding every recorded
+    # gist, keyed by doc base name. There is no git-root behavior here --
+    # gist publication has no repo-relative meaning, so the path is just
+    # ENV override or DEFAULT_PATH.
+    #
+    # This is an index, not a source of truth -- every entry in it can be
+    # rebuilt by re-publishing. Two deliberate concessions follow from that:
+    # a corrupt or empty file degrades to empty rather than raising
+    # (raising would also break the calls you'd use to repair it), and two
+    # processes recording at once is last-writer-wins -- the atomic write
+    # below buys readers a whole file, not writers a serialized one.
+    #
+    # Resolved path priority:
+    #   1. ENV['STREAMWEAVER_GIST_STORE']  (test/override hook)
+    #   2. ~/.streamweaver/canvas/gists.json
+    module GistStore
+      DEFAULT_PATH = File.expand_path('~/.streamweaver/canvas/gists.json')
+
+      module_function
+
+      # Resolves the store file path. Read fresh on every call (not memoized)
+      # so an ENV override flips behavior mid-process -- specs rely on this,
+      # same rationale as DocStore#path.
+      def path
+        env = ENV['STREAMWEAVER_GIST_STORE']
+        return env if env && !env.empty?
+
+        DEFAULT_PATH
+      end
+
+      # Returns the full store: name => {"id" =>, "url" =>, "revisions" =>,
+      # "created_at" =>, "updated_at" =>}. Empty hash for a missing, empty,
+      # or corrupt file -- see the module comment for why this degrades
+      # instead of raising.
+      def all
+        file = path
+        return {} unless File.exist?(file)
+
+        content = File.read(file)
+        return {} if content.strip.empty?
+
+        JSON.parse(content)
+      rescue JSON::ParserError
+        {}
+      end
+
+      # Returns the entry for `name`, or nil if it has never been recorded.
+      def lookup(name)
+        all[name.to_s]
+      end
+
+      # Upserts the entry for `name`: id/url/revisions are overwritten,
+      # created_at is set once and preserved across later calls, updated_at
+      # always advances to now. Returns the resulting entry hash.
+      def record(name, id:, url:, revisions:)
+        name = name.to_s
+        store = all
+        now = timestamp
+
+        entry = {
+          'id' => id,
+          'url' => url,
+          'revisions' => revisions,
+          'created_at' => store.dig(name, 'created_at') || now,
+          'updated_at' => now
+        }
+        store[name] = entry
+        persist(store)
+        entry
+      end
+
+      # Among recorded names starting with `prefix`, returns the entry with
+      # the most recent updated_at -- how a caller with only a doc-name
+      # prefix (e.g. a canvas session name) finds "the gist for this
+      # session" with no session state of its own. nil if nothing matches.
+      def latest_for_prefix(prefix)
+        prefix = prefix.to_s
+        match = all.select { |name, _| name.start_with?(prefix) }.max_by { |_, entry| entry['updated_at'] }
+        match&.last
+      end
+
+      # Removes the entry for `name` if present. No-op if it was never
+      # recorded.
+      def forget(name)
+        store = all
+        persist(store) if store.delete(name.to_s)
+      end
+
+      # Millisecond precision, not the 1-second default: two gists published
+      # within the same second are ordinary, and latest_for_prefix has to
+      # break that tie correctly rather than by hash insertion order.
+      def timestamp
+        Time.now.utc.iso8601(3)
+      end
+      private_class_method :timestamp
+
+      # Writes `store` to `path` atomically: JSON goes to a temp file in the
+      # SAME directory (so the rename is on one filesystem, where POSIX
+      # guarantees it is atomic) and is then renamed over the target. A plain
+      # File.write truncates first, which would let a concurrent reader
+      # observe an empty or half-written file; the temp file is removed if
+      # the write or rename fails so a failure never leaves stray files
+      # behind.
+      def persist(store)
+        file = path
+        dir = File.dirname(file)
+        FileUtils.mkdir_p(dir)
+
+        tmp = File.join(dir, ".#{File.basename(file)}.#{Process.pid}.#{SecureRandom.hex(4)}.tmp")
+        begin
+          File.write(tmp, JSON.generate(store))
+          File.rename(tmp, file)
+        rescue StandardError
+          FileUtils.rm_f(tmp)
+          raise
+        end
+      end
+      private_class_method :persist
+    end
+  end
+end

data/lib/stream_weaver/canvas/helpers.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+module StreamWeaver
+  module Canvas
+    # High-level helper methods for common canvas patterns.
+    # Generates DSL code and parses results for pick, confirm, and form operations.
+    module Helpers
+      module_function
+
+      # Generate DSL for a single-choice picker
+      # @param title [String] The title/prompt
+      # @param choices [Array<String>] Available choices
+      # @return [String] DSL code
+      def pick_dsl(title, choices)
+        choices_str = choices.map { |c| "\"#{c}\"" }.join(", ")
+
+        <<~DSL
+          header1 "#{title}"
+          radio_group :choice, [#{choices_str}]
+          button "Select", id: "btn_submit"
+        DSL
+      end
+
+      # Generate DSL for a confirmation dialog
+      # @param message [String] The confirmation message
+      # @param yes_label [String] Label for confirm button (default: "Confirm")
+      # @param no_label [String] Label for cancel button (default: "Cancel")
+      # @return [String] DSL code
+      def confirm_dsl(message, yes_label: "Confirm", no_label: "Cancel")
+        <<~DSL
+          header1 "#{message}"
+          hstack do
+            button "#{no_label}", id: "btn_cancel", style: :secondary
+            button "#{yes_label}", id: "btn_confirm"
+          end
+        DSL
+      end
+
+      # Generate DSL for a form with specified fields
+      # @param title [String] The form title
+      # @param fields [Hash] Field definitions { name: { type: :text, ... }, ... }
+      # @return [String] DSL code
+      def form_dsl(title, fields)
+        field_dsl = fields.map do |name, config|
+          case config[:type]
+          when :text
+            placeholder = config[:placeholder] ? ", placeholder: \"#{config[:placeholder]}\"" : ""
+            "text_field :#{name}#{placeholder}"
+          when :textarea
+            placeholder = config[:placeholder] ? ", placeholder: \"#{config[:placeholder]}\"" : ""
+            rows = config[:rows] ? ", rows: #{config[:rows]}" : ""
+            "text_area :#{name}#{placeholder}#{rows}"
+          when :radio
+            choices_str = config[:choices].map { |c| "\"#{c}\"" }.join(", ")
+            "radio_group :#{name}, [#{choices_str}]"
+          when :select
+            choices_str = config[:choices].map { |c| "\"#{c}\"" }.join(", ")
+            "select :#{name}, [#{choices_str}]"
+          when :checkbox
+            label = config[:label] || name.to_s.capitalize
+            "checkbox :#{name}, \"#{label}\""
+          else
+            "text_field :#{name}"
+          end
+        end.join("\n")
+
+        <<~DSL
+          header1 "#{title}"
+          #{field_dsl}
+          button "Submit", id: "btn_submit"
+        DSL
+      end
+
+      # Parse pick result from event data
+      # @param event_data [Hash] Event data from browser
+      # @return [String, nil] Selected choice
+      def parse_pick_result(event_data)
+        # Choice is nested in state from the browser event
+        state = event_data[:state] || event_data["state"] || {}
+        state[:choice] || state["choice"] || event_data[:choice] || event_data["choice"]
+      end
+
+      # Parse confirm result from event data
+      # @param event_data [Hash] Event data from browser
+      # @return [Boolean] true if confirmed, false if cancelled
+      def parse_confirm_result(event_data)
+        # Button ID is in :button from the browser event
+        button = event_data[:button] || event_data["button"] ||
+                 event_data[:_button] || event_data["_button"] || ""
+        button.to_s.include?("confirm")
+      end
+
+      # Parse form result from event data
+      # @param event_data [Hash] Event data from browser
+      # @param field_names [Array<Symbol>] Expected field names
+      # @return [Hash] Form field values
+      def parse_form_result(event_data, field_names)
+        # Form values are in state from the browser event
+        state = event_data[:state] || event_data["state"] || event_data
+        result = {}
+        field_names.each do |name|
+          key = name.to_sym
+          result[key] = state[key] || state[name.to_s]
+        end
+        result
+      end
+    end
+  end
+end

data/lib/stream_weaver/canvas/history.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+require 'fileutils'
+
+module StreamWeaver
+  module Canvas
+    # Tier 1 (off-repo) history of canvas-push DSL snapshots.
+    #
+    # Snapshots live at <root>/<session>/<YYYYMMDD_HHMMSS>.rb where <root> is
+    # ENV['STREAMWEAVER_HISTORY_ROOT'] || ~/.streamweaver/history. The env-var
+    # override exists so specs (and ad-hoc tooling) can redirect writes away
+    # from the user's real home directory.
+    #
+    # Session names are validated against an allowlist (alnum + . _ -, must
+    # start with alnum) and an explicit '..'-substring check. Bad names raise
+    # ArgumentError -- raising rather than sanitizing keeps the contract
+    # explicit and avoids silently storing under an unexpected directory.
+    module History
+      MAX_AGE_DAYS    = 7
+      MAX_AGE_SECONDS = MAX_AGE_DAYS * 86_400
+      DEFAULT_ROOT    = File.expand_path('~/.streamweaver/history')
+      VALID_NAME      = /\A[A-Za-z0-9][A-Za-z0-9._-]*\z/
+
+      module_function
+
+      def root
+        env = ENV['STREAMWEAVER_HISTORY_ROOT']
+        return env if env && !env.empty?
+
+        DEFAULT_ROOT
+      end
+
+      # Writes dsl to <root>/<session>/<timestamp>.rb and returns the path.
+      # Appends a numeric suffix on collision so back-to-back writes within
+      # the same second don't clobber each other. Paths are claimed atomically
+      # (File::EXCL), so concurrent callers get distinct files instead of
+      # racing between an exist? check and the write.
+      def record(session, dsl)
+        validate_session!(session)
+        dir = File.join(root, session)
+        FileUtils.mkdir_p(dir)
+
+        stamp = Time.now.strftime('%Y%m%d_%H%M%S')
+        write_unique(dir, stamp, dsl)
+      end
+
+      # Deletes snapshot files older than MAX_AGE_DAYS and prunes any
+      # session directory left empty afterwards. No-op if root is missing.
+      def cleanup
+        base = root
+        return unless Dir.exist?(base)
+
+        cutoff = Time.now - MAX_AGE_SECONDS
+
+        Dir.children(base).each do |session|
+          session_dir = File.join(base, session)
+          next unless File.directory?(session_dir)
+
+          Dir.glob(File.join(session_dir, '*.rb')).each do |file|
+            File.delete(file) if File.mtime(file) < cutoff
+          end
+
+          Dir.rmdir(session_dir) if Dir.children(session_dir).empty?
+        end
+      end
+
+      def validate_session!(session)
+        return if session.is_a?(String) && session.match?(VALID_NAME) && !session.include?('..')
+
+        raise ArgumentError, "invalid session name: #{session.inspect}"
+      end
+      private_class_method :validate_session!
+
+      def write_unique(dir, stamp, dsl)
+        suffix = nil
+        loop do
+          name = suffix ? "#{stamp}_#{suffix}.rb" : "#{stamp}.rb"
+          path = File.join(dir, name)
+          begin
+            File.open(path, File::WRONLY | File::CREAT | File::EXCL) { |f| f.write(dsl) }
+            return path
+          rescue Errno::EEXIST
+            suffix = (suffix || 0) + 1
+          end
+        end
+      end
+      private_class_method :write_unique
+    end
+  end
+end

data/lib/stream_weaver/canvas/protocol.rb

@@ -0,0 +1,86 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module StreamWeaver
+  module Canvas
+    # Protocol for Unix socket IPC between Claude Code and Canvas Bridge.
+    # Uses newline-delimited JSON.
+    module Protocol
+      # Encode a message hash to newline-delimited JSON
+      # @param message [Hash] Message to encode
+      # @return [String] JSON string with trailing newline
+      def self.encode(message)
+        JSON.generate(message) + "\n"
+      end
+
+      # Decode a JSON string to a message hash
+      # @param json [String] JSON string
+      # @return [Hash, nil] Decoded message with symbol keys, or nil if invalid
+      def self.decode(json)
+        JSON.parse(json, symbolize_names: true)
+      rescue JSON::ParserError
+        nil
+      end
+
+      # Parse a buffer containing potentially multiple messages
+      # @param buffer [String] Buffer with newline-delimited JSON
+      # @return [Array<Array<Hash>, String>] [messages, remaining_buffer]
+      def self.parse_buffer(buffer)
+        lines = buffer.split("\n", -1)
+        remaining = lines.pop || ''
+
+        messages = lines.filter_map do |line|
+          decode(line) unless line.empty?
+        end
+
+        [messages, remaining]
+      end
+
+      # Message factory methods
+      module Messages
+        # Claude → Bridge: Create a new session
+        def self.create(name, layout: :fluid, theme: :default)
+          { type: 'create', name: name, layout: layout, theme: theme }
+        end
+
+        # Claude → Bridge: Push DSL content to session
+        # @param source_dir [String, nil] Git root of the pushing side's cwd
+        #   (DocStore.git_root(Dir.pwd) computed by the caller), or nil
+        #   outside a repo. Not the bridge's own cwd -- see Session#source_dir.
+        def self.push(name, dsl, source_dir: nil)
+          { type: 'push', name: name, dsl: dsl, source_dir: source_dir }
+        end
+
+        # Claude → Bridge: Close a session
+        def self.close(name)
+          { type: 'close', name: name }
+        end
+
+        # Claude → Bridge: Fetch a session's current raw DSL + theme/layout
+        # (canvas-snapshot, stream_weaver-ps84) -- the live in-memory source
+        # of truth, not the ephemeral ~/.streamweaver/history/ trail, which
+        # expires after 7 days and isn't written by every code path that can
+        # populate a session's DSL.
+        def self.get_dsl(name)
+          { type: 'get_dsl', name: name }
+        end
+
+        # Claude → Bridge: Set iTerm pane ID for a session
+        def self.set_pane_id(name, pane_id)
+          { type: 'set_pane_id', name: name, pane_id: pane_id }
+        end
+
+        # Bridge → Claude: Session is ready
+        def self.ready(name, url)
+          { type: 'ready', name: name, url: url }
+        end
+
+        # Bridge → Claude: User interaction event
+        def self.event(name, event_type, data)
+          { type: 'event', name: name, event: event_type, data: data }
+        end
+      end
+    end
+  end
+end