studio-engine 0.95.0 → 0.96.0

data/lib/studio/knowledge_transcript.rb

@@ -0,0 +1,185 @@
+# frozen_string_literal: true
+
+module Studio
+  # Turns a meeting transcript's text into CUES: (seconds, speaker, text), in
+  # the order they appear. The knowledge layer's player seeks to a cue's
+  # seconds when its line is clicked.
+  #
+  # Loaded on first use (`require "studio/knowledge_transcript"`), not by
+  # `require "studio"`.
+  #
+  # Two layouts are read, line by line, and may be mixed in one text:
+  #
+  #   A. the stamp, a dash, then the speaker; the text indented below
+  #        0:02 - Jordan Example (Example Co)
+  #          Good morning, everyone.
+  #
+  #   B. the speaker, a bullet, then the stamp; the text on the lines below
+  #        Jordan Example • 0:02
+  #        Good morning, everyone.
+  #
+  # A stamp is M:SS or H:MM:SS. Lines before the first cue (a title, a "VIEW
+  # RECORDING" line, a rule) belong to no cue and are dropped. Text that is not
+  # a transcript has no cue lines and answers no cues. Nothing here raises on
+  # any String, whatever its bytes or encoding; a non-String answers no cues.
+  #
+  # A layout A cue line starts in the FIRST COLUMN. That is what keeps an
+  # indented line of speech such as "  10:30 - we agreed to meet" text.
+  #
+  # THE BOUNDS, each a constant below. There is one loop, over the lines of at
+  # most MAX_TEXT_BYTES of text, and every step in it is linear in the line:
+  #   MAX_TEXT_BYTES      2 MB of text read; the rest is ignored
+  #   MAX_CUES            5,000 cues; reading stops at the next one
+  #   MAX_CUE_LINE_BYTES  512 bytes: a longer line is never a cue line, so no
+  #                       pattern is ever run against a long line
+  #   MAX_STAMP_BYTES     10 bytes: the longest stamp, "999:59:59" and one spare
+  #   MAX_SPEAKER_CHARS   120 characters; a longer "speaker" is a line of text
+  #   MAX_CUE_TEXT_BYTES  8 KB of text kept for one cue; the rest is dropped
+  #
+  # The one pattern, STAMP, is anchored at both ends, has no nested or
+  # unbounded quantifier, and only ever sees a token of MAX_STAMP_BYTES or
+  # fewer. Everything else is `strip`, `index`, `rindex` and `start_with?`.
+  module KnowledgeTranscript
+    MAX_TEXT_BYTES = 2 * 1024 * 1024
+    MAX_CUES = 5_000
+    MAX_CUE_LINE_BYTES = 512
+    MAX_STAMP_BYTES = 10
+    MAX_SPEAKER_CHARS = 120
+    MAX_CUE_TEXT_BYTES = 8 * 1024
+
+    STAMP = /\A(?:(\d{1,3}):)?(\d{1,3}):(\d{2})\z/
+    # Layout A: what may stand between the stamp and the speaker.
+    DASHES = ["- ", "– ", "— "].freeze
+    # Layout B: what stands between the speaker and the stamp.
+    BULLET = "•"
+
+    Cue = Struct.new(:seconds, :speaker, :text)
+
+    # `cues` is frozen. `truncated` is true when a bound cut the reading short
+    # (text past MAX_TEXT_BYTES, cues past MAX_CUES, or a cue's text past
+    # MAX_CUE_TEXT_BYTES), so a page can say the transcript is incomplete.
+    Result = Struct.new(:cues, :truncated) do
+      def truncated? = truncated
+    end
+
+    class << self
+      # The cues in `text`, as an Array of Cue. Empty when there are none.
+      def parse(text)
+        read(text).cues
+      end
+
+      # The same reading, with whether a bound cut it short.
+      def read(text)
+        return Result.new([].freeze, false) unless text.is_a?(String)
+
+        truncated = text.bytesize > MAX_TEXT_BYTES
+        cues = []
+        current = nil
+
+        # Bounded: at most MAX_TEXT_BYTES of text, so at most that many lines.
+        utf8(truncated ? text.byteslice(0, MAX_TEXT_BYTES) : text).each_line do |line|
+          opening = cue_line(line)
+          if opening
+            if cues.size >= MAX_CUES
+              truncated = true
+              break
+            end
+            current = Cue.new(opening[0], opening[1], +"")
+            cues << current
+          elsif current
+            truncated = true unless append(current.text, line)
+          end
+        end
+
+        cues.each { |cue| cue.text.freeze }
+        Result.new(cues.freeze, truncated)
+      end
+
+      # Seconds for "M:SS" or "H:MM:SS", or nil when `token` is not a stamp.
+      def seconds_of(token)
+        return nil if token.bytesize > MAX_STAMP_BYTES
+
+        match = STAMP.match(token)
+        return nil unless match
+
+        hours, minutes, seconds = match[1], match[2].to_i, match[3].to_i
+        return nil if seconds > 59
+        return minutes * 60 + seconds if hours.nil?
+        return nil if minutes > 59
+
+        hours.to_i * 3600 + minutes * 60 + seconds
+      end
+
+      private
+
+      # Valid UTF-8 whatever came in. Bytes with no encoding claim (binary,
+      # ASCII) are read as UTF-8; another encoding is converted; whatever is
+      # invalid either way becomes U+FFFD.
+      def utf8(text)
+        claimed = text.encoding
+        if [Encoding::UTF_8, Encoding::BINARY, Encoding::US_ASCII].include?(claimed)
+          return text.dup.force_encoding(Encoding::UTF_8).scrub("�")
+        end
+
+        text.encode(Encoding::UTF_8, invalid: :replace, undef: :replace, replace: "�")
+      rescue EncodingError
+        text.dup.force_encoding(Encoding::UTF_8).scrub("�")
+      end
+
+      # [seconds, speaker] when `line` opens a cue, else nil.
+      def cue_line(line)
+        return nil if line.bytesize > MAX_CUE_LINE_BYTES
+
+        layout_a(line) || layout_b(line)
+      end
+
+      # "0:02 - Jordan Example (Example Co)", starting in the first column.
+      def layout_a(line)
+        gap = line.index(" ")
+        return nil if gap.nil? || gap.zero? || gap > MAX_STAMP_BYTES
+
+        seconds = seconds_of(line[0, gap])
+        return nil if seconds.nil?
+
+        rest = line[gap..].lstrip
+        return nil unless rest.start_with?(*DASHES)
+
+        speaker = speaker_of(rest[2..])
+        speaker && [seconds, speaker]
+      end
+
+      # "Jordan Example • 0:02": the LAST bullet, so a bullet in a name is kept.
+      def layout_b(line)
+        at = line.rindex(BULLET)
+        return nil if at.nil?
+
+        seconds = seconds_of(line[(at + 1)..].strip)
+        return nil if seconds.nil?
+
+        speaker = speaker_of(line[0, at])
+        speaker && [seconds, speaker]
+      end
+
+      def speaker_of(text)
+        speaker = text.strip
+        speaker.empty? || speaker.size > MAX_SPEAKER_CHARS ? nil : speaker
+      end
+
+      # Adds one line of speech to a cue's text. Answers false when the cue's
+      # text was already full or this line had to be cut to fit.
+      def append(text, line)
+        piece = line.strip
+        return true if piece.empty?
+
+        room = MAX_CUE_TEXT_BYTES - text.bytesize - (text.empty? ? 0 : 1)
+        return false if room <= 0
+
+        fits = piece.bytesize <= room
+        piece = piece.byteslice(0, room).scrub("") unless fits
+        text << "\n" unless text.empty?
+        text << piece
+        fits
+      end
+    end
+  end
+end

data/lib/studio/s3/multipart.rb

@@ -0,0 +1,193 @@
+# frozen_string_literal: true
+
+require_relative "../s3"
+
+module Studio
+  module S3
+    # Uploads a LOCAL FILE of any size without holding it in memory: an S3
+    # multipart upload, one part read and sent at a time. Studio::S3.upload
+    # takes a String and suits a document; a recording is hundreds of megabytes.
+    #
+    # Loaded on first use (`require "studio/s3/multipart"`), not by
+    # `require "studio"`.
+    #
+    # THE BOUNDS, all enforced in `upload_file`:
+    #   memory   one part (PART_SIZE, 16 MB) at a time, sent sequentially
+    #   parts    MAX_PARTS (10,000, the S3 limit); the loop is `1.upto(MAX_PARTS)`
+    #            and the first short read ends it
+    #   bytes    `max_bytes:`, counted as parts are read, so a file that grows
+    #            under the upload stops there
+    #   time     UPLOAD_DEADLINE (2 hours), read before each part. One request
+    #            is bounded by the SDK client's own timeouts and retries
+    #            (http_open_timeout 15 s, http_read_timeout 60 s, 3 retries;
+    #            the suite pins those defaults), not by this deadline.
+    #
+    # WHAT A FAILURE LEAVES IN THE BUCKET:
+    #   before completion   nothing: the multipart upload is aborted on ANY
+    #                       way out, a signal (SIGTERM, Ctrl-C) included
+    #   after completion    nothing: an object whose size cannot be confirmed
+    #                       is deleted before the error is raised
+    #   SIGKILL, power      the parts sent so far, invisible to listings, until
+    #                       the bucket's abort-incomplete-multipart lifecycle
+    #                       rule removes them (R2's default rule: 7 days). No
+    #                       process can clean up after its own SIGKILL.
+    #
+    # CHECKSUMS AND R2. aws-sdk-s3 from 1.178 adds a CRC32 to uploads by default
+    # (`request_checksum_calculation: when_supported`), and R2 has refused some
+    # of the combinations that produces (the Active Storage rule in the hub's
+    # object-storage module). This uploader therefore uses its OWN client, built
+    # from Studio::S3.client_options plus `when_required` for both checksum
+    # settings, and sends a Content-MD5 with every part, which S3 and R2 both
+    # verify. The shared Studio::S3.client is untouched.
+    #
+    # UNPROVEN: every test of this file runs against a stubbed client. The
+    # request shape (no x-amz-checksum headers, Content-MD5 on each part) is
+    # asserted; that a live R2 bucket accepts it is not.
+    module Multipart
+      # 16 MB. R2 requires every part but the last to be the same size, and S3
+      # requires at least 5 MB; 16 MB puts a 1 GB recording in 64 parts.
+      PART_SIZE = 16 * 1024 * 1024
+      MIN_PART_SIZE = 5 * 1024 * 1024
+      # The S3 limit on parts in one upload.
+      MAX_PARTS = 10_000
+      # Seconds for the whole upload, read before each part. A 4 GB file is
+      # 256 parts; two hours allows about 28 s a part.
+      UPLOAD_DEADLINE = 7_200
+
+      # What an upload answers.
+      Uploaded = Struct.new(:key, :byte_size, :parts, keyword_init: true)
+
+      class << self
+        # Streams the file at `path` to `key` (a LOGICAL key, like every
+        # Studio::S3 call) and answers an Uploaded. Raises Studio::S3::Error on
+        # an empty file, a file over `max_bytes`, an upload past `deadline`
+        # seconds, or an object whose stored size does not match what was
+        # sent. See WHAT A FAILURE LEAVES IN THE BUCKET above.
+        def upload_file(key:, path:, content_type:, max_bytes:, part_size: PART_SIZE, deadline: UPLOAD_DEADLINE,
+                        client: self.client)
+          unless max_bytes.is_a?(Integer) && max_bytes.positive?
+            raise ArgumentError, "max_bytes must be a positive Integer, got #{max_bytes.inspect}"
+          end
+          unless part_size.is_a?(Integer) && part_size >= MIN_PART_SIZE
+            raise ArgumentError, "part_size must be an Integer of at least #{MIN_PART_SIZE} bytes, got #{part_size.inspect}"
+          end
+
+          bucket = Studio::S3.bucket
+          target = { bucket: bucket, key: Studio::S3.full_key(key) }
+          stop_at = Process.clock_gettime(Process::CLOCK_MONOTONIC) + deadline
+
+          File.open(path.to_s, "rb") do |file|
+            size = file.size
+            raise Error, "refusing to upload an empty file: #{path}" if size.zero?
+            raise Error, "#{path} is #{size} bytes, over the #{max_bytes}-byte cap" if size > max_bytes
+
+            upload_id = client.create_multipart_upload(**target, content_type: content_type).upload_id
+            completed = false
+            begin
+              parts, sent = send_parts(client, target, upload_id, file, part_size, max_bytes, stop_at)
+              raise Error, "#{path} changed during the upload: #{size} bytes at open, #{sent} sent" unless sent == size
+
+              client.complete_multipart_upload(**target, upload_id: upload_id, multipart_upload: { parts: parts })
+              completed = true
+            ensure
+              # `ensure`, not `rescue StandardError`: a SIGTERM or Ctrl-C is
+              # not a StandardError, and parts left behind are privileged
+              # bytes no listing shows.
+              abort_quietly(client, target, upload_id) unless completed
+            end
+
+            verify_stored_size!(client, target, sent)
+            Uploaded.new(key: key, byte_size: sent, parts: parts.size)
+          end
+        end
+
+        # A client for multipart uploads: Studio::S3's own options, with both
+        # checksum settings at when_required (see CHECKSUMS AND R2 above).
+        def client
+          @client ||= begin
+            require "aws-sdk-s3"
+            Aws::S3::Client.new(**client_options)
+          end
+        end
+
+        def client_options
+          Studio::S3.client_options.merge(
+            request_checksum_calculation: "when_required",
+            response_checksum_validation: "when_required"
+          )
+        end
+
+        def reset!
+          @client = nil
+        end
+
+        private
+
+        # Reads and sends one part at a time. Bounded four ways: the loop runs
+        # at most MAX_PARTS times, each read is at most part_size bytes, the
+        # running total may not pass max_bytes, and the first short read ends it.
+        def send_parts(client, target, upload_id, file, part_size, max_bytes, stop_at)
+          require "digest/md5"
+          parts = []
+          sent = 0
+          1.upto(MAX_PARTS) do |number|
+            if Process.clock_gettime(Process::CLOCK_MONOTONIC) > stop_at
+              raise Error, "the upload passed its deadline after #{parts.size} part(s)"
+            end
+
+            chunk = file.read(part_size)
+            return [parts, sent] if chunk.nil? || chunk.empty?
+
+            sent += chunk.bytesize
+            raise Error, "upload passed the #{max_bytes}-byte cap while reading" if sent > max_bytes
+
+            part = client.upload_part(**target, upload_id: upload_id, part_number: number, body: chunk,
+                                      content_md5: Digest::MD5.base64digest(chunk))
+            parts << { etag: part.etag, part_number: number }
+            # A short read is the end of the file, and the last part. Reading
+            # on would chase a file that is still being appended to, and every
+            # part but the last must be part_size (R2 refuses otherwise).
+            return [parts, sent] if chunk.bytesize < part_size
+          end
+          raise Error, "file needs more than #{MAX_PARTS} parts of #{part_size} bytes" unless file.eof?
+
+          [parts, sent]
+        end
+
+        # The object is asked for after the upload, so a store that answered
+        # 200 to the completion and kept something else fails here, loudly.
+        # The upload is COMPLETE by now, so every way out of here that is not
+        # success removes the object first: a size that differs, a head_object
+        # that raises, or a signal. Otherwise a whole recording would sit in
+        # the bucket with no row pointing at it.
+        def verify_stored_size!(client, target, sent)
+          confirmed = false
+          stored = client.head_object(**target).content_length
+          confirmed = stored == sent
+          return if confirmed
+
+          raise Error, "#{target[:key]} stored #{stored.inspect} bytes of #{sent} sent; the object was removed"
+        ensure
+          remove_quietly(client, target) unless confirmed
+        end
+
+        # A new object nothing references: a hard delete, behind the same
+        # production-bucket guard as every delete. A failure here must not
+        # hide the error that caused it.
+        def remove_quietly(client, target)
+          Studio::S3.guard_production_bucket!(target[:bucket])
+          client.delete_object(**target)
+        rescue StandardError
+          nil
+        end
+
+        # An abort that fails must not hide the error that caused it.
+        def abort_quietly(client, target, upload_id)
+          client.abort_multipart_upload(**target, upload_id: upload_id)
+        rescue StandardError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/studio/theme_resolver.rb

@@ -111,12 +111,10 @@ module Studio
         #
         # The warning and success inks are the same contract for the other two
         # status roles: their default colours fail AA as text on the light
-        # surfaces too. They are found by #status_ink, which also counts the
-        # role's own tint as a surface, because they are read inside tinted
-        # badges. Danger text is not: it belongs on a theme surface, never on a
-        # danger tint (see #status_ink for why that is a rule, not an accident).
-        "--color-danger-ink"     => contrast_ink(danger, direction: :lighten, start: 0.0, target: 4.5,
-                                                 against: surfaces),
+        # surfaces too. All three are found by #status_ink, which also counts
+        # the role's own tint as a surface, because they are read inside tinted
+        # badges.
+        "--color-danger-ink"     => status_ink(danger, surfaces, direction: :lighten),
         "--color-warning-ink"    => status_ink(warning, surfaces, direction: :lighten),
         "--color-success-ink"    => status_ink(success, surfaces, direction: :lighten),
         "--color-accent"         => colors[:accent] || "#F72585"
@@ -168,20 +166,12 @@ module Studio
     # `bg-<role>/10 text-<role>-ink` badge and flash-panel pattern.
     STATUS_TINT = 0.10
 
-    # The warning and success inks land on the page surfaces AND on their own
-    # role's tint over each of them (the `bg-warning/10 text-warning-ink`
-    # badge). The tint is darker than a light surface and lighter than a dark
-    # one, so an ink tuned to the bare surfaces alone came out below AA inside
-    # its own badge (default theme: warning 3.91:1 dark, success 4.00:1 dark).
-    # Counting the tints as surfaces closes that.
-    #
-    # --color-danger-ink does NOT go through here, and danger text must not sit
-    # on a danger tint: tuned to bare surfaces it measures 4.10:1 (light) and
-    # 4.18:1 (dark) on its own 10% tint. Consumers already build on that rule (turf-monster's error
-    # contrast guard keeps a control that fails the day danger-ink clears a red
-    # tint), so retuning danger-ink is a sequenced change, not a drive-by one.
-    # test/views/engine_class_vocabulary_test.rb refuses danger-ink on a danger
-    # tint in any engine view.
+    # A status ink lands on the page surfaces AND on its own role's tint over
+    # each of them (the `bg-warning/10 text-warning-ink` badge). The tint is
+    # darker than a light surface and lighter than a dark one, so an ink tuned
+    # to the bare surfaces alone comes out below AA inside its own badge
+    # (default theme: warning 3.91:1 dark, success 4.00:1 dark, danger 4.10:1
+    # light and 4.18:1 dark). Counting the tints as surfaces closes that.
     def status_ink(role, surfaces, direction:)
       tints = surfaces.map { |bg| ColorScale.blend(role, bg, STATUS_TINT) }
       contrast_ink(role, direction: direction, start: 0.0, target: 4.5, against: surfaces + tints)
@@ -314,8 +304,7 @@ module Studio
         #
         # The warning and success inks are the same contract for the other two
         # status roles (see the dark-mode note).
-        "--color-danger-ink"     => contrast_ink(danger, direction: :darken, start: 0.0, target: 4.5,
-                                                 against: surfaces),
+        "--color-danger-ink"     => status_ink(danger, surfaces, direction: :darken),
         "--color-warning-ink"    => status_ink(warning, surfaces, direction: :darken),
         "--color-success-ink"    => status_ink(success, surfaces, direction: :darken),
         "--color-accent"         => colors[:accent] || "#F72585"

data/lib/studio/version.rb

@@ -1,3 +1,3 @@
 module Studio
-  VERSION = "0.95.0"
+  VERSION = "0.96.0"
 end

data/lib/studio.rb

@@ -48,6 +48,7 @@ require "studio/link_resolution"
 require "studio/session_fingerprint"
 require "studio/session_state"
 require "studio/email"
+require "studio/email_image_generator"
 require "studio/email_smoke"
 require "studio/mail_transport"
 require "studio/redis"
@@ -383,6 +384,36 @@ module Studio
   # resolution are always on, so an app sends branded email either way.
   mattr_accessor :draw_admin_emails_routes, default: false
 
+  # The "Email image generator" link at the top of /admin/emails: where this
+  # app's operator makes a new banner. nil (the default) or blank draws no link,
+  # and the page renders as it always has. A String must be an absolute http(s)
+  # URL (anything else raises here, at boot); a callable receives the request and
+  # returns one, and an unusable answer draws no link. The label and the line
+  # under it are optional; blank means the engine's generic wording.
+  # See Studio::EmailImageGenerator.
+  #
+  #   config.email_manager_generator_url         = "https://example.com/email-art"
+  #   config.email_manager_generator_label       = "Header generator"
+  #   config.email_manager_generator_description = "Open it, copy the prompt, paste it into Claude Code."
+  mattr_reader :email_manager_generator_url, default: nil
+  mattr_accessor :email_manager_generator_label, default: nil
+  mattr_accessor :email_manager_generator_description, default: nil
+
+  def self.email_manager_generator_url=(value)
+    @@email_manager_generator_url = EmailImageGenerator.normalize_url(value)
+  end
+
+  # The link /admin/emails renders for this request, or nil for none.
+  def self.email_manager_generator_link(request = nil)
+    EmailImageGenerator.link(
+      url: email_manager_generator_url,
+      label: email_manager_generator_label,
+      description: email_manager_generator_description,
+      app_name: app_name,
+      request: request
+    )
+  end
+
   # Draw the shared first-name onboarding endpoints
   # (Studio::OnboardingController#first_name / #skip_first_name). OFF by default,
   # and for the same hard reason as draw_admin_emails_routes above:
@@ -705,7 +736,8 @@ module Studio
   # and this is development or test, or production with the flag.
   def self.lookbook_mounted?
     ComponentGallery.mounted?(env: Rails.env, in_production: lookbook_in_production,
-                              lookbook_loaded: ComponentGallery.lookbook_loaded?)
+                              lookbook_loaded: ComponentGallery.lookbook_loaded?,
+                              load_order_ok: ComponentGallery.load_order_ok?)
   end
 
   # WHERE THE APP'S OWN BOOKING PAGE LIVES, for an app that renders

data/lib/tasks/studio_knowledge.rake

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+# Attach a meeting's recording to a knowledge document, from a one-off dyno or
+# a laptop. The recording is COPIED into the app's private bucket beside the
+# document.
+#
+#   bin/rails studio:knowledge:attach_recording ID=42 FILE=/tmp/standup.mp4
+#   bin/rails studio:knowledge:attach_recording ID=42 URL=https://files.example.com/standup.mp4
+#   echo "$DOWNLOAD_URL" | bin/rails studio:knowledge:attach_recording ID=42 URL=-
+#
+# ID is the document's id. Give exactly one of FILE (a local path) or URL (an
+# https download, fetched through the engine's SSRF guard). Optional: NAME, a
+# file name for the object (a fetched recording is otherwise "recording"), and
+# SOURCE_URL, the external page the recording came from, kept on the row as a
+# link.
+#
+# URL=- READS THE URL FROM STANDARD INPUT. A download URL carries a credential,
+# and a command line is logged (a platform's "starting process" line, shell
+# history, `ps`). The URL is never stored and never printed, whichever way it
+# arrives; a failure names its host only.
+#
+# The arguments are environment variables, not rake's [a,b] form, because a
+# URL may hold a comma and rake splits on them.
+#
+# Only audio and video are stored: MP4, M4V, MOV, M4A, WebM, MP3, WAV and Ogg,
+# judged by the file's first bytes (Studio::KnowledgeRecording), up to 4 GB.
+# Anything else is refused and nothing is written. Replacing a recording moves
+# the old object to trash/ for three days (studio:trash:restore).
+#
+# WHAT IT PRINTS: the document's id, the bucket, the key, the type and the
+# size. Not the title and not the link: a document's title is content of the
+# layer, and this output goes to a log.
+#
+# Logic lives in Studio::KnowledgeDoc#attach_recording! and
+# #attach_recording_from_url! (unit-tested); this task only reads its
+# arguments and prints.
+# Guarded like studio_trash.rake: an app that also loads this file must not
+# register a second copy of the action.
+unless Rake::Task.task_defined?("studio:knowledge:attach_recording")
+  namespace :studio do
+    namespace :knowledge do
+      desc "Attach a recording to knowledge document ID from FILE=<path> or URL=<https url> (SOURCE_URL=<page> optional)"
+      task attach_recording: :environment do
+        require "studio/knowledge_recording"
+        usage = "usage: studio:knowledge:attach_recording ID=<document id> (FILE=<path> | URL=<https url, or - for stdin>) " \
+                "[NAME=<file name>] [SOURCE_URL=<page>]"
+        id = ENV["ID"].to_s.strip
+        file = ENV["FILE"].to_s.strip
+        url = ENV["URL"].to_s.strip
+        name = ENV["NAME"].to_s.strip
+        source_url = ENV["SOURCE_URL"].to_s.strip
+        abort usage unless id.match?(/\A\d{1,18}\z/)
+        abort "#{usage}\ngive FILE or URL, not both" unless file.empty? ^ url.empty?
+
+        # One line, read with a limit: a URL over the cap is refused by the
+        # fetch, so there is no reason to read more of it than that.
+        url = $stdin.gets(Studio::KnowledgeRecording::MAX_URL_BYTES + 2).to_s.strip if url == "-"
+        abort "#{usage}\nURL=- was given and standard input held no URL" if file.empty? && url.empty?
+
+        doc = Studio::KnowledgeDoc.find_by(id: id.to_i)
+        abort "studio:knowledge:attach_recording: no knowledge document with id #{id}" if doc.nil?
+
+        replaced = doc.recording? ? doc.recording_key : nil
+        options = {}
+        options[:source_url] = source_url unless source_url.empty?
+        options[:filename] = name unless name.empty?
+        begin
+          if file.empty?
+            doc.attach_recording_from_url!(url, **options)
+          else
+            doc.attach_recording!(file, **options)
+          end
+        rescue StandardError => error
+          # Every failure is reported the same way, a storage or database
+          # error included: its class and message, no backtrace. No message
+          # raised on this path carries the download URL.
+          abort "studio:knowledge:attach_recording: #{error.class}: #{error.message.to_s[0, 500]}"
+        end
+
+        puts "Attached a recording to knowledge document #{doc.id}"
+        puts "  bucket: #{Studio::S3.bucket}"
+        puts "  key:    #{doc.recording_key}"
+        puts "  type:   #{doc.recording_mime_type}"
+        puts "  size:   #{doc.recording_byte_size} bytes"
+        puts "  replaced #{replaced} (moved to trash/ for three days)" if replaced && replaced != doc.recording_key
+      end
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: studio-engine
 version: !ruby/object:Gem::Version
-  version: 0.95.0
+  version: 0.96.0
 platform: ruby
 authors:
 - Alex McRitchie
@@ -412,9 +412,11 @@ files:
 - app/javascript/studio/alpine_shims.js
 - app/javascript/studio/alpine_stores.js
 - app/javascript/studio/application.js
+- app/javascript/studio/controllers/modal_host_controller.js
 - app/javascript/studio/controllers/nav_collapse_controller.js
 - app/javascript/studio/head_chrome.js
 - app/javascript/studio/local_path.js
+- app/javascript/studio/modal_host.js
 - app/javascript/studio/nav_collapse.js
 - app/javascript/studio/pinned_stack.js
 - app/javascript/studio/vendor/stimulus.js
@@ -435,6 +437,7 @@ files:
 - app/models/studio/enumeral.rb
 - app/models/studio/geo_setting.rb
 - app/models/studio/knowledge_doc.rb
+- app/models/studio/knowledge_doc/recording.rb
 - app/models/studio/knowledge_expectation.rb
 - app/models/studio/link.rb
 - app/models/studio/model_page.rb
@@ -651,6 +654,7 @@ files:
 - db/migrate/20261006120001_ensure_error_logs_table.rb
 - db/migrate/20261006120002_ensure_theme_settings_table.rb
 - db/migrate/20261006120003_ensure_image_caches_table.rb
+- db/migrate/20261008120000_add_recording_to_studio_knowledge_docs.rb
 - docs/BOOKING.md
 - docs/SITE_FOOTER.md
 - lib/active_storage/service/studio_trash_s3_service.rb
@@ -663,6 +667,7 @@ files:
 - lib/studio/color_scale.rb
 - lib/studio/component_gallery.rb
 - lib/studio/email.rb
+- lib/studio/email_image_generator.rb
 - lib/studio/email_smoke.rb
 - lib/studio/engine.rb
 - lib/studio/environment_banner.rb
@@ -674,6 +679,8 @@ files:
 - lib/studio/ip_locations.rb
 - lib/studio/js_identifier.rb
 - lib/studio/js_literal.rb
+- lib/studio/knowledge_recording.rb
+- lib/studio/knowledge_transcript.rb
 - lib/studio/link_preview.rb
 - lib/studio/link_resolution.rb
 - lib/studio/link_token.rb
@@ -691,6 +698,7 @@ files:
 - lib/studio/public_user.rb
 - lib/studio/redis.rb
 - lib/studio/s3.rb
+- lib/studio/s3/multipart.rb
 - lib/studio/s3/trash.rb
 - lib/studio/session_fingerprint.rb
 - lib/studio/session_state.rb
@@ -704,6 +712,7 @@ files:
 - lib/studio/username_generator.rb
 - lib/studio/version.rb
 - lib/tasks/studio_email.rake
+- lib/tasks/studio_knowledge.rake
 - lib/tasks/studio_ses.rake
 - lib/tasks/studio_trash.rake
 - studio-engine.gemspec