teems 0.3.1 → 0.3.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5932afeb278892c20e7e3fbb92980da31ff45cd9a528a3e2463de38ee7ea3f70
-  data.tar.gz: 331a38b48c8bb1d87ff770a0579e1846aa643b5d1d1daf5061c0bbf8f0589264
+  metadata.gz: bdc6ea71a9d23f39629fd24d240992925cca1482b53b69df377a84870d66367f
+  data.tar.gz: 1d563de02f05c8a120130e3e792b508bbf4d1b2467937951a63f2a3efbb19410
 SHA512:
-  metadata.gz: 5d750e3b09de3a6ce07612398e0e00a7eb5ac647aa9cd38d45023cd0605777625a9ec212aa81c111b69118d068ffd3b4bd946280d4194cc1ecd34f40708adf7f
-  data.tar.gz: 355288361bbfa4e21166b18b248793403a023411e3588be731e205c9fe4f6994684426ae7037a09cf009bdb699e9a17caf932572aea9ab1588449c3298224624
+  metadata.gz: 8c903fdae8e9946614e093ab4370e74abc03f7fab0d0a76509da02d07814e0083382f4a8f46e0e9131dd1eb3b16f0c36c5eeb96bb381778679bb92028574ad13
+  data.tar.gz: b3e6ff9fa9ec3adb9708a3ab97b30929d53a820e9d6239daaf4d359cee179c32448b306a7ac3ab26f336aa3c723402868a1206711637af791a974aa0e3f0e832

data/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## [0.3.2] - 2026-09-29
+
+### Added
+- `teems transcripts sync` discovers calendar Teams meetings and downloads available WebVTT transcripts into a private XDG data directory. The first run scans 30 days; subsequent runs scan seven, with an idempotent manifest and catch-up after time away. `--date`, `--since`, and `--dry-run` are supported. Recordings and audio are not downloaded.
+- Transcript sync writes speaker-turn Markdown copies to `~/.local/share/teems/transcripts-md/` for local search indexes such as qmd.
+- Transcript sync can run a `transcripts.post_sync_command` from `config.json` (for example, a qmd index refresh) after a sync that changed Markdown. The command gets the changed paths in `TEEMS_TRANSCRIPTS_*` environment variables, is bounded by `post_sync_timeout` (default 300 seconds), and warns rather than failing the sync. `--no-post-sync` skips it for one run.
+- Transcript sync keeps one transcript per recording, so meetings that were restarted mid-session no longer lose the later recording's transcript. Existing per-meeting downloads are reused when identical rather than duplicated.
+- `teems meeting --json` prints call events, recording links, and transcript markers as JSON (the option was documented but ignored).
+- `teems meeting --transcript --recording-url URL` downloads the transcript for a specific recording in the meeting instead of the first one.
+
 ## [0.3.1] - 2026-09-02
 
 ### Added

data/README.md

@@ -87,11 +87,48 @@ teems meeting <thread-id> --transcript -o ~/Downloads  # Download transcript (VT
 teems meeting <thread-id> --recording -o ~/Downloads   # Download recording (MP4)
 teems meeting <thread-id> --recording --transcript -o ~/Downloads  # Both, with embedded subtitles
 teems meeting <event-id>                           # By calendar event ID (AAMk...)
+teems meeting <event-id> --date 2026-09-29 --json  # Call events + recording links as JSON
+teems meeting <event-id> --date 2026-09-29 --transcript --recording-url <url>  # A specific recording
 teems meeting "https://teams.microsoft.com/..."    # By Teams URL or recap link
 ```
 
 Recording download requires `ffmpeg` (`brew install ffmpeg`) and downloads via DASH streaming with 5 parallel threads. No browser required.
 
+#### Transcript sync
+
+```bash
+teems transcripts sync --dry-run          # Preview meetings and recording counts
+teems transcripts sync                    # First run: 30 days; later: 7 days
+teems transcripts sync --date 2026-09-28  # Retry a specific day
+teems transcripts sync --since 30         # Explicit historical backfill
+teems transcripts sync --no-post-sync     # Skip the configured post-sync command once
+```
+
+This saves **only WebVTT transcripts** in `~/.local/share/teems/transcripts/` on the machine running the command, separate from live-caption `meeting-capture` files. Each sync also writes speaker-turn Markdown copies to `~/.local/share/teems/transcripts-md/` (regenerated when missing or older than the VTT) for local search tools such as [qmd](https://github.com/tobi/qmd). Each recording keeps its own transcript, so a meeting restarted mid-session yields one VTT per recording. A private manifest in `~/.local/state/teems/transcript-sync.json` makes repeats idempotent and catches up after time away (up to 30 days). Data and state directories are mode 0700; transcripts and the manifest are mode 0600. The calendar scan retries unavailable transcripts within the lookback window; errors return a nonzero exit code. To run every evening on a GFE, schedule `teems transcripts sync` there via launchd.
+
+Coverage is **calendar Teams meetings with a saved and accessible recording transcript**, not every meeting attended: ad-hoc calls, meetings with no saved transcript/recording, and inaccessible organizer-owned artifacts cannot be recovered by this route. No audio/video is downloaded, and nothing is copied to another machine.
+
+To search the Markdown locally with qmd, keep it in a dedicated index so refreshes don't re-scan other collections:
+
+```bash
+qmd --index teems-transcripts collection add ~/.local/share/teems/transcripts-md --name teems-transcripts --mask '**/*.md'
+qmd --index teems-transcripts update && qmd --index teems-transcripts embed
+qmd --index teems-transcripts query "what did we decide about monitoring?"
+```
+
+To refresh that index automatically, set a post-sync command in `~/.config/teems/config.json`:
+
+```json
+{
+  "transcripts": {
+    "post_sync_command": "qmd --index teems-transcripts update && qmd --index teems-transcripts embed",
+    "post_sync_timeout": 900
+  }
+}
+```
+
+The command runs via `sh -c` only after a sync writes or regenerates Markdown; not on `--dry-run`, when nothing changed, or with `--no-post-sync`. It receives `TEEMS_TRANSCRIPTS_CHANGED` (newline-separated Markdown paths), `TEEMS_TRANSCRIPTS_CHANGED_COUNT`, `TEEMS_TRANSCRIPTS_MARKDOWN_DIR`, and `TEEMS_TRANSCRIPTS_DIR`, and is killed after `post_sync_timeout` seconds (default 300). A failure or timeout prints a warning but does not change the sync's exit code.
+
 ### People
 
 ```bash

data/lib/teems/cli.rb

@@ -48,6 +48,7 @@ module Teems
       'channels' => Commands::Channels,
       'chats' => Commands::Chats,
       'meeting' => Commands::Meeting,
+      'transcripts' => Commands::Transcripts,
       'messages' => Commands::Messages,
       'sync' => Commands::Sync,
       'who' => Commands::Who,

data/lib/teems/commands/help.rb

@@ -9,6 +9,7 @@ module Teems
       ['channels', 'List joined teams and channels'],
       ['chats', 'List recent chats'],
       ['meeting', 'View meeting details, chat, transcripts, and recordings'],
+      ['transcripts', 'Sync saved meeting transcripts to this machine'],
       ['messages', 'Read messages from a channel or chat'],
       ['sync', 'Sync chat history locally'],
       ['who', "Look up a user's profile"],
@@ -83,6 +84,7 @@ module Teems
             teems channels                 List all channels
             teems chats                    List recent chats
             teems messages <channel-id>    Read messages from a channel
+            teems transcripts sync         Download recent meeting transcripts
             teems who                      Show your profile
             teems who john                 Search for a user
             teems org                      Show your org chart

data/lib/teems/commands/meeting.rb

@@ -24,10 +24,12 @@ module Teems
         --chat           Show meeting chat messages
         --date YYYY-MM-DD  Pick a single occurrence of a recurring meeting by date
                            (filters call events, recordings, and transcripts)
+        --recording-url URL  With --transcript, use this recording's transcript
+                             (a meeting restarted mid-session has several)
         -o, --output-dir Directory for downloads (default: current directory)
         -v, --verbose    Show debug output
         -q, --quiet      Suppress output
-        --json           Output as JSON
+        --json           Output meeting details (call events, recordings) as JSON
         -h, --help       Show this help
 
       EXAMPLES:
@@ -39,6 +41,7 @@ module Teems
         teems meeting 19:meeting_abc123@thread.v2 --recording -o ~/Downloads
         teems meeting 19:meeting_abc123@thread.v2 --recording --transcript -o ~/Downloads
         teems meeting "<recurring-url>" --date 2026-05-04 --audio --no-video --transcript
+        teems meeting AAMkAGVmMDEz... --date 2026-05-04 --json  # List recordings
         teems meeting AAMkAGVmMDEz...        # By calendar event ID
     HELP
 
@@ -51,6 +54,7 @@ module Teems
         '--no-video' => ->(opts, _args) { opts[:no_video] = true },
         '--chat' => ->(opts, _args) { opts[:chat] = true },
         '--date' => ->(opts, args) { opts[:date] = args.shift },
+        '--recording-url' => ->(opts, args) { opts[:recording_url] = args.shift },
         '-o' => ->(opts, args) { opts[:output_dir] = args.shift },
         '--output-dir' => ->(opts, args) { opts[:output_dir] = args.shift }
       }.freeze
@@ -604,11 +608,29 @@ module Teems
       end
     end
 
+    # Machine-readable meeting details; `teems transcripts sync` uses these to enumerate recordings.
+    module MeetingJsonSummary
+      private
+
+      def output_meeting_json(target, classified)
+        output_json(thread_id: target[:thread_id],
+                    call_events: classified[:call_events].map { |event| json_call_event(event) },
+                    recordings: classified[:recordings].map { |rec| rec.slice(:time, :url, :call_id) },
+                    transcripts: classified[:transcripts].map { |item| item.slice(:time) })
+        0
+      end
+
+      def json_call_event(event)
+        event.slice(:time, :call_id, :duration).merge(participants: event[:participants].map { |part| part[:name] })
+      end
+    end
+
     # View meeting details, chat, transcripts, and recordings
     class Meeting < Base
       include MeetingTargetResolver
       include MeetingMessageParser
       include MeetingDisplay
+      include MeetingJsonSummary
       include MeetingChatDisplay
       include MeetingCallFilter
       include MeetingDateFilter
@@ -691,6 +713,7 @@ module Teems
         media = media_output_spec
         return download_media_with_transcript(target, classified, media) if media
         return download_transcript(target, classified) || 0 if @options[:transcript]
+        return output_meeting_json(target, classified) if @options[:json]
 
         display_meeting_summary(target, classified)
         0

data/lib/teems/commands/meeting_transcript.rb

@@ -138,24 +138,39 @@ module Teems
       end
     end
 
+    # Chooses which recording's transcript to fetch (--recording-url, else the first link).
+    module MeetingRecordingSelection
+      private
+
+      def first_recording_url(classified)
+        @options[:recording_url] || recording_urls(classified).first
+      end
+
+      def unknown_recording_url?(classified)
+        requested = @options[:recording_url]
+        requested && !recording_urls(classified).include?(requested)
+      end
+
+      def recording_urls(classified) = classified[:recordings].filter_map { |rec| rec[:url] }
+    end
+
     # Downloads meeting transcripts via SharePoint API (no Safari required)
     module MeetingTranscript
+      include MeetingRecordingSelection
       include EmbedPageParser
       include MeetingFilename
 
       private
 
       def download_transcript(target, classified)
+        return error('--recording-url is not a recording in this meeting') if unknown_recording_url?(classified)
+
         sharing_url = target[:fileUrl] || first_recording_url(classified)
         return error('No recording sharing link found for transcript download') unless sharing_url
 
         execute_transcript_pipeline(sharing_url)
       end
 
-      def first_recording_url(classified)
-        classified[:recordings].filter_map { |rec| rec[:url] }.first
-      end
-
       def execute_transcript_pipeline(sharing_url)
         info('Fetching transcript via SharePoint...')
         embed_url = fetch_embed_url(sharing_url)

data/lib/teems/commands/transcripts.rb

@@ -0,0 +1,466 @@
+# frozen_string_literal: true
+
+require 'English'
+require 'date'
+require 'open3'
+require 'tmpdir'
+
+module Teems
+  module Commands
+    # Fetches saved Teams transcripts for calendar meetings. Transcript retrieval still
+    # goes through `teems meeting`, keeping its SharePoint/auth implementation in one place.
+    class Transcripts < Base
+      HELP = <<~HELP
+        teems transcripts - Sync saved meeting transcripts onto this machine
+
+        USAGE:
+          teems transcripts sync [--since DAYS | --date YYYY-MM-DD] [--dry-run] [--no-post-sync]
+
+        OPTIONS:
+          --since DAYS       Calendar lookback (default 7; first run 30)
+          --date YYYY-MM-DD  Only scan one calendar date
+          --dry-run          List meetings and recording counts without downloading
+          --no-post-sync     Skip the configured post-sync command for this run
+          -q, --quiet       Suppress progress (not errors)
+
+        WebVTTs: ~/.local/share/teems/transcripts/
+        Markdown (for local search, e.g. qmd): ~/.local/share/teems/transcripts-md/
+        Sync state: ~/.local/state/teems/transcript-sync.json
+        Only meetings on your Teams calendar with a saved, accessible recording
+        transcript can be retrieved; each recording's transcript is kept (a meeting
+        restarted mid-session has several). Does not alter meeting-capture files.
+
+        POST-SYNC COMMAND:
+        Set "transcripts": {"post_sync_command": "..."} in ~/.config/teems/config.json to
+        run a shell command (e.g. a qmd index refresh) after a sync that changed Markdown.
+        It receives TEEMS_TRANSCRIPTS_CHANGED (newline-separated Markdown paths),
+        TEEMS_TRANSCRIPTS_CHANGED_COUNT, TEEMS_TRANSCRIPTS_MARKDOWN_DIR, and
+        TEEMS_TRANSCRIPTS_DIR. "post_sync_timeout" (seconds, default 300) bounds it.
+        A failing or timed-out command is reported but does not fail the sync.
+      HELP
+
+      def execute
+        validation = validate_options
+        return validation if validation
+        unless positional_args == ['sync']
+          return error('Usage: teems transcripts sync [--since DAYS | --date YYYY-MM-DD]')
+        end
+        return error('--since must be between 1 and 366') unless (1..366).cover?(@options.fetch(:since, 7))
+        return error('Invalid --date (expected YYYY-MM-DD)') if @options[:invalid_date]
+
+        TranscriptSyncEngine.new(@options, output, hook: transcript_settings).run
+      end
+
+      protected
+
+      def handle_option(arg, pending)
+        case arg
+        when '--since' then @options[:since] = Integer(pending.shift, exception: false)
+        when '--date' then parse_date_option(pending.shift)
+        when '--dry-run' then @options[:dry_run] = true
+        when '--no-post-sync' then @options[:no_post_sync] = true
+        else super
+        end
+      end
+
+      def transcript_settings
+        settings = config['transcripts']
+        settings.is_a?(Hash) ? settings : {}
+      end
+
+      def parse_date_option(value)
+        @options[:date] = Date.iso8601(value)
+      rescue ArgumentError, TypeError
+        @options[:invalid_date] = true
+      end
+
+      def help_text = HELP
+    end
+
+    # Private on-disk storage, separate from meeting-capture.
+    module TranscriptSyncFiles
+      private
+
+      def prepare_private_directories
+        [@output_dir, @state_dir].each do |dir|
+          FileUtils.mkdir_p(dir, mode: 0o700)
+          File.chmod(0o700, dir)
+        end
+      end
+
+      def log_locked
+        log 'Another transcript sync is running; skipping.'
+        0
+      end
+
+      def load_manifest
+        File.file?(@manifest_path) ? JSON.parse(File.read(@manifest_path)) : { 'events' => {} }
+      end
+
+      def downloaded?(key, manifest)
+        prior = manifest.fetch('events', {})[key]
+        prior && valid_vtt?(File.join(@output_dir, File.basename(prior.fetch('file'))))
+      end
+
+      def persist_download(date, event, key, file, manifest)
+        adopted = adopt_legacy_download(date, event, file, manifest)
+        target_name = adopted || store_download(file, key)
+        manifest['events'][key] = { 'file' => target_name, 'downloaded_at' => Time.now.iso8601,
+                                    'date' => date.iso8601, 'subject' => event_name(event) }
+        save_manifest(manifest)
+        log "#{date}: #{adopted ? 'already had' : 'saved'} #{target_name}"
+      end
+
+      def store_download(file, key)
+        target_name = "#{File.basename(file, '.vtt')}--#{key[0, 10]}.vtt"
+        target = File.join(@output_dir, target_name)
+        File.rename(file, target) unless valid_vtt?(target)
+        File.chmod(0o600, target)
+        target_name
+      end
+
+      # Earlier syncs kept one transcript per event. Reuse that file when it is
+      # this recording's transcript instead of saving a duplicate.
+      def adopt_legacy_download(date, event, file, manifest)
+        key = legacy_key(date, event)
+        legacy = manifest['events'][key]
+        return unless legacy
+
+        existing = File.join(@output_dir, File.basename(legacy.fetch('file')))
+        return unless valid_vtt?(existing) && FileUtils.identical?(existing, file)
+
+        manifest['events'].delete(key)
+        File.basename(existing)
+      end
+
+      def valid_vtt?(file)
+        File.file?(file) && File.size(file) > 10 && File.open(file, 'rb') { |io| io.read(6) == 'WEBVTT' }
+      end
+
+      def valid_download?(status, files)
+        status.success? && files.length == 1 && valid_vtt?(files.first)
+      end
+
+      def save_manifest(manifest)
+        write_private(@manifest_path, "#{JSON.pretty_generate(manifest)}\n")
+      end
+
+      def write_private(path, content)
+        temp = "#{path}.tmp.#{$PROCESS_ID}"
+        File.open(temp, File::WRONLY | File::CREAT | File::TRUNC, 0o600) { |file| file.write(content) }
+        File.rename(temp, path)
+        File.chmod(0o600, path)
+      ensure
+        File.delete(temp) if temp && File.exist?(temp)
+      end
+    end
+
+    # Speaker-turn Markdown copies of each WebVTT, suitable for a local search index.
+    module TranscriptSyncMarkdown
+      private
+
+      def sync_markdown(manifest)
+        FileUtils.mkdir_p(@markdown_dir, mode: 0o700)
+        File.chmod(0o700, @markdown_dir)
+        results = manifest.fetch('events', {}).values.map { |entry| export_markdown(entry) }
+        written = results.count(:written)
+        log "Markdown: updated #{written} transcript(s)" if written.positive?
+        results
+      end
+
+      def export_markdown(entry)
+        vtt = File.join(@output_dir, File.basename(entry.fetch('file')))
+        return :missing unless valid_vtt?(vtt)
+
+        target = File.join(@markdown_dir, "#{File.basename(vtt, '.vtt')}.md")
+        return :current if markdown_current?(target, vtt)
+
+        write_private(target, markdown_for(vtt, entry))
+        @changed_markdown << target
+        :written
+      rescue StandardError => e
+        markdown_failure(entry, e)
+      end
+
+      def markdown_current?(target, vtt) = File.file?(target) && File.mtime(target) >= File.mtime(vtt)
+
+      def markdown_failure(entry, error)
+        failure "Markdown export failed for #{File.basename(entry['file'].to_s)} (#{error.class}: #{error.message})"
+        :failed
+      end
+
+      def markdown_for(vtt, entry)
+        stem = File.basename(vtt, '.vtt').sub(/--\h{10}\z/, '')
+        Formatters::TranscriptMarkdown.new(
+          File.read(vtt, encoding: 'bom|utf-8'),
+          title: entry['subject'] || stem.sub(/\A\d{4}-\d{2}-\d{2} - /, '').sub(/-\d{8}_\d{6}UTC\z/, ''),
+          date: entry['date'] || transcript_date(stem),
+          source: File.basename(vtt)
+        ).render
+      end
+
+      def transcript_date(stem)
+        return stem[0, 10] if stem.match?(/\A\d{4}-\d{2}-\d{2} - /)
+
+        stem.match(/-(\d{4})(\d{2})(\d{2})_\d{6}UTC\z/)&.captures&.join('-')
+      end
+    end
+
+    # Calendar discovery is intentionally limited to scheduled Teams meetings.
+    module TranscriptSyncCalendar
+      private
+
+      def calendar_events(date)
+        stdout, stderr, status = Open3.capture3(teems_executable, 'cal', '--date', date.iso8601, '--json')
+        raise "teems cal failed (exit #{status.exitstatus}): #{redacted_error(stderr)}" unless status.success?
+
+        return [] if stdout.strip == 'No events found'
+
+        events = JSON.parse(stdout)
+        raise 'teems cal returned a non-array response' unless events.is_a?(Array)
+
+        events.select { |event| teams_event?(event) }
+      end
+
+      def teams_event?(event)
+        return false unless event.is_a?(Hash)
+        return false if event['is_cancelled'] || event['is_all_day'] || event['response_status'] == 'declined'
+
+        event['id'].to_s.start_with?('AAMk') &&
+          event['online_meeting_url'].to_s.start_with?('https://teams.microsoft.com/')
+      end
+
+      def teems_executable = ENV.fetch('TEEMS_EXECUTABLE', 'teems')
+
+      def redacted_error(text)
+        lines = text.to_s.scrub.lines.map(&:strip).reject { |line| line.empty? || line.include?('warning:') }
+        message = lines.find { |line| line.start_with?('Error:') } || lines.first || 'unknown error'
+        message.gsub(%r{https?://\S+}, '[URL]').gsub(/Bearer\s+\S+/i, 'Bearer [REDACTED]')[0, 220]
+      end
+    end
+
+    # One transcript per recording: a meeting restarted mid-session has several.
+    module TranscriptSyncRecordings
+      NO_TRANSCRIPT = Regexp.union(/No recording sharing link found/i,
+                                   /No transcripts found for this recording/i,
+                                   /No meeting activity found for/i)
+
+      private
+
+      def sync_event(date, event, manifest)
+        urls = recording_urls(date, event)
+        return unavailable?(date, event) if urls.empty?
+        return preview_event?(date, event, urls, manifest) if @options[:dry_run]
+
+        urls.map { |url| sync_recording?(date, event, url, manifest) }.all?
+      rescue StandardError => e
+        failure "#{date}: failed: #{event_name(event)} (#{e.class}: #{e.message})"
+        false
+      end
+
+      def recording_urls(date, event)
+        stdout, stderr, status = Open3.capture3(teems_executable, 'meeting', event.fetch('id'),
+                                                '--date', date.iso8601, '--json')
+        return recordings_from(stdout) if status.success?
+        return [] if NO_TRANSCRIPT.match?("#{stderr} #{stdout}")
+
+        raise "teems meeting failed (exit #{status.exitstatus}): #{redacted_error("#{stderr} #{stdout}")}"
+      end
+
+      def recordings_from(json)
+        recordings = JSON.parse(json).fetch('recordings', [])
+        recordings.select { |rec| rec['url'] }.sort_by { |rec| rec['time'].to_s }.map { |rec| rec['url'] }.uniq
+      end
+
+      def recording_key(date, event, url) = Digest::SHA256.hexdigest("#{date.iso8601}:#{event.fetch('id')}:#{url}")
+
+      def legacy_key(date, event) = Digest::SHA256.hexdigest("#{date.iso8601}:#{event.fetch('id')}")
+
+      def sync_recording?(date, event, url, manifest)
+        key = recording_key(date, event, url)
+        downloaded?(key, manifest) || download_recording?(date, event, url, key, manifest)
+      end
+
+      def preview_event?(date, event, urls, manifest)
+        pending = urls.count { |url| !downloaded?(recording_key(date, event, url), manifest) }
+        pending -= 1 if pending.positive? && downloaded?(legacy_key(date, event), manifest)
+        log "#{date}: candidate: #{event_name(event)} (#{urls.length} recording(s), #{pending} not yet saved)"
+        true
+      end
+
+      def download_recording?(date, event, url, key, manifest)
+        Dir.mktmpdir('teems-transcript-', @output_dir) do |temp_dir|
+          stdout, stderr, status = Open3.capture3(teems_executable, 'meeting', event.fetch('id'),
+                                                  '--date', date.iso8601, '--transcript',
+                                                  '--recording-url', url, '-o', temp_dir)
+          files = Dir.glob(File.join(temp_dir, '*.vtt'))
+          return download_failure?(date, event, status, "#{stderr} #{stdout}") unless valid_download?(status, files)
+
+          persist_download(date, event, key, files.first, manifest)
+        end
+        true
+      end
+
+      def download_failure?(date, event, status, message)
+        return unavailable?(date, event) if NO_TRANSCRIPT.match?(message)
+
+        failure "#{date}: failed: #{event_name(event)} (exit #{status.exitstatus}; #{redacted_error(message)})"
+        false
+      end
+
+      def unavailable?(date, event)
+        log "#{date}: unavailable via teems: #{event_name(event)}"
+        true
+      end
+    end
+
+    # Optional user command run after a sync changes Markdown, e.g. to refresh a qmd index.
+    # A failing or slow command is reported but never fails the sync itself.
+    module TranscriptSyncHook
+      DEFAULT_HOOK_TIMEOUT = 300
+
+      private
+
+      def run_post_sync_hook
+        command = @hook['post_sync_command'].to_s.strip
+        return if command.empty? || @options[:no_post_sync] || @changed_markdown.empty?
+
+        log "Post-sync: running command for #{@changed_markdown.length} changed transcript(s)"
+        report_hook(*execute_hook(command))
+      rescue StandardError => e
+        @output.warn("Post-sync command could not run (#{e.class}: #{e.message})")
+      end
+
+      # Runs in its own process group so a timeout can stop the whole pipeline.
+      def execute_hook(command)
+        Open3.popen2e(hook_env, 'sh', '-c', command, pgroup: true) do |stdin, stdout, wait|
+          stdin.close
+          reader = Thread.new { stdout.read }
+          finished = wait.join(hook_timeout)
+          stop_hook(wait.pid) unless finished
+          [finished ? wait.value : nil, reader.value]
+        end
+      end
+
+      def stop_hook(pid)
+        Process.kill('KILL', -pid)
+      rescue Errno::ESRCH
+        nil
+      end
+
+      def hook_env
+        { 'TEEMS_TRANSCRIPTS_CHANGED' => @changed_markdown.join("\n"),
+          'TEEMS_TRANSCRIPTS_CHANGED_COUNT' => @changed_markdown.length.to_s,
+          'TEEMS_TRANSCRIPTS_MARKDOWN_DIR' => @markdown_dir,
+          'TEEMS_TRANSCRIPTS_DIR' => @output_dir }
+      end
+
+      def hook_timeout = [@hook['post_sync_timeout']].grep(Numeric).find(&:positive?) || DEFAULT_HOOK_TIMEOUT
+
+      def report_hook(status, hook_output)
+        return log('Post-sync: done') if status&.success?
+
+        reason = status ? "exit #{status.exitstatus}" : "timed out after #{hook_timeout}s"
+        @output.warn("Post-sync command failed (#{reason}): #{hook_tail(hook_output)}")
+      end
+
+      def hook_tail(text)
+        lines = text.to_s.scrub.lines.map(&:strip).reject(&:empty?).last(3)
+        lines.empty? ? 'no output' : lines.join(' | ')[0, 300]
+      end
+    end
+
+    # Local manifest and replay engine. Never transfers transcripts to another machine.
+    class TranscriptSyncEngine
+      include TranscriptSyncFiles
+      include TranscriptSyncCalendar
+      include TranscriptSyncMarkdown
+      include TranscriptSyncRecordings
+      include TranscriptSyncHook
+
+      DEFAULT_LOOKBACK = 7
+      INITIAL_LOOKBACK = 30
+
+      def initialize(options, output, hook: {})
+        @options = options
+        @output = output
+        @hook = hook
+        @changed_markdown = []
+        data_home = ENV.fetch('XDG_DATA_HOME', File.join(Dir.home, '.local', 'share'))
+        state_home = ENV.fetch('XDG_STATE_HOME', File.join(Dir.home, '.local', 'state'))
+        @output_dir = File.join(data_home, 'teems', 'transcripts')
+        @markdown_dir = File.join(data_home, 'teems', 'transcripts-md')
+        @state_dir = File.join(state_home, 'teems')
+        @manifest_path = File.join(@state_dir, 'transcript-sync.json')
+      end
+
+      def run
+        File.umask(0o077)
+        return scan(load_manifest) if @options[:dry_run]
+
+        prepare_private_directories
+        File.open(File.join(@state_dir, 'transcript-sync.lock'), File::RDWR | File::CREAT, 0o600) do |lock|
+          return log_locked unless lock.flock(File::LOCK_EX | File::LOCK_NB)
+
+          scan(load_manifest)
+        end
+      end
+
+      private
+
+      def log(message)
+        @output.puts(message) unless @options[:quiet]
+      end
+
+      def failure(message)
+        @output.error(message)
+      end
+
+      def dates_to_scan(manifest)
+        return [@options[:date]] if @options[:date]
+
+        days = lookback_days(manifest)
+        log "Scanning #{days} day(s) through #{Date.today} on this machine"
+        ((Date.today - days + 1)..Date.today).to_a
+      end
+
+      def lookback_days(manifest)
+        days = @options.fetch(:since, DEFAULT_LOOKBACK)
+        return days unless days == DEFAULT_LOOKBACK
+
+        previous = manifest['last_scan_date']
+        return INITIAL_LOOKBACK unless previous
+
+        # Catch up after time away, capped at the requested initial window.
+        (Date.today - Date.iso8601(previous) + 1).to_i.clamp(days, INITIAL_LOOKBACK)
+      end
+
+      def scan(manifest)
+        results = dates_to_scan(manifest).map { |date| scan_date(date, manifest) }
+        unless @options[:dry_run]
+          persist_scan(manifest, results.include?(nil))
+          results << !sync_markdown(manifest).include?(:failed)
+          run_post_sync_hook
+        end
+        results.all? ? 0 : 1
+      end
+
+      def scan_date(date, manifest)
+        results = calendar_events(date).map { |event| sync_event(date, event, manifest) }
+        results.all?
+      rescue StandardError => e
+        failure "#{date}: calendar error (#{e.class}: #{e.message})"
+        nil
+      end
+
+      def persist_scan(manifest, calendar_failed)
+        # Failed artifacts stay in the log and get seven-day retries. A calendar
+        # failure leaves the wider scan pending so historical days aren't lost.
+        manifest['last_scan_date'] = Date.today.iso8601 unless @options[:date] || calendar_failed
+        save_manifest(manifest)
+      end
+
+      def event_name(event) = event['subject'].to_s.gsub(/[\r\n]/, ' ')[0, 100]
+    end
+  end
+end

data/lib/teems/formatters/transcript_markdown.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Teems
+  module Formatters
+    # Converts Teams WebVTT transcripts into speaker-turn Markdown for local search indexes.
+    # Consecutive cues from the same speaker are merged so each paragraph carries context.
+    class TranscriptMarkdown
+      Cue = Data.define(:start, :speaker, :text)
+
+      TIMING = /\A(?<start>(?:\d+:)?\d{2}:\d{2}\.\d{3})\s+-->/
+      VOICE = /<v(?:\.[^\s>]+)?\s+([^>]+)>/
+      ENTITIES = {
+        '&amp;' => '&', '&lt;' => '<', '&gt;' => '>', '&quot;' => '"', '&#39;' => "'",
+        '&apos;' => "'", '&nbsp;' => ' ', '&lrm;' => '', '&rlm;' => ''
+      }.freeze
+      ENTITY_PATTERN = Regexp.union(ENTITIES.keys)
+      MAX_TURN_CHARS = 1500
+
+      def initialize(vtt, title:, date: nil, source: nil)
+        @vtt = vtt.to_s
+        @title = single_line(title).then { |value| value.empty? ? 'Teams transcript' : value }
+        @date = date
+        @source = source
+      end
+
+      def render
+        lines = front_matter + ["# #{@title}", '', ['Teams transcript', @date].compact.join(' · '), '']
+        turns.each { |turn| lines.push(format_turn(turn), '') }
+        "#{lines.join("\n").rstrip}\n"
+      end
+
+      def turns
+        cues.each_with_object([]) { |cue, turns| append_cue(turns, cue) }
+      end
+
+      private
+
+      def append_cue(turns, cue)
+        last = turns.last
+        if last && last[:speaker] == cue.speaker && last[:text].length < MAX_TURN_CHARS
+          last[:text] << ' ' << cue.text
+        else
+          turns << { start: cue.start, speaker: cue.speaker, text: +cue.text }
+        end
+      end
+
+      def cues
+        normalized = @vtt.scrub.delete_prefix("\uFEFF").gsub(/\r\n?/, "\n")
+        normalized.split(/\n{2,}/).filter_map { |block| parse_cue(block) }
+      end
+
+      def parse_cue(block)
+        lines = block.lines.map(&:chomp)
+        timing_index = lines.index { |line| TIMING.match?(line) }
+        return unless timing_index
+
+        build_cue(lines[timing_index][TIMING, :start], lines[(timing_index + 1)..].join(' '))
+      end
+
+      def build_cue(start, raw)
+        text = clean(raw)
+        return if text.empty?
+
+        Cue.new(start: start, speaker: raw[VOICE, 1]&.then { |name| clean(name) }, text: text)
+      end
+
+      def clean(text) = single_line(decode(text.gsub(/<[^>]*>/, '')))
+
+      def decode(text) = text.gsub(ENTITY_PATTERN, ENTITIES)
+
+      def single_line(text) = text.to_s.gsub(/\s+/, ' ').strip
+
+      def front_matter
+        [
+          '---',
+          "title: #{@title.to_json}",
+          ("date: #{@date}" if @date),
+          'source: teams-transcript',
+          ("vtt: #{@source.to_json}" if @source),
+          '---',
+          ''
+        ].compact
+      end
+
+      def format_turn(turn)
+        speaker = turn[:speaker] || 'Unknown speaker'
+        "**#{speaker}** (#{turn[:start].sub(/\.\d+\z/, '')}): #{turn[:text]}"
+      end
+    end
+  end
+end

data/lib/teems/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Teems
-  VERSION = '0.3.1'
+  VERSION = '0.3.2'
 end

data/lib/teems.rb

@@ -78,6 +78,7 @@ module Teems
     autoload :MessageFormatter, 'teems/formatters/message_formatter'
     autoload :MarkdownFormatter, 'teems/formatters/markdown_formatter'
     autoload :CalendarFormatter, 'teems/formatters/calendar_formatter'
+    autoload :TranscriptMarkdown, 'teems/formatters/transcript_markdown'
   end
 
   # CLI commands implementing user-facing functionality
@@ -95,6 +96,7 @@ module Teems
     autoload :Ooo, 'teems/commands/ooo'
     autoload :Org, 'teems/commands/org'
     autoload :Meeting, 'teems/commands/meeting'
+    autoload :Transcripts, 'teems/commands/transcripts'
     autoload :Status, 'teems/commands/status'
   end
 

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: teems
 version: !ruby/object:Gem::Version
-  version: 0.3.1
+  version: 0.3.2
 platform: ruby
 authors:
 - Eric Boehs
@@ -49,12 +49,14 @@ files:
 - lib/teems/commands/org.rb
 - lib/teems/commands/status.rb
 - lib/teems/commands/sync.rb
+- lib/teems/commands/transcripts.rb
 - lib/teems/commands/who.rb
 - lib/teems/formatters/calendar_formatter.rb
 - lib/teems/formatters/format_utils.rb
 - lib/teems/formatters/markdown_formatter.rb
 - lib/teems/formatters/message_formatter.rb
 - lib/teems/formatters/output.rb
+- lib/teems/formatters/transcript_markdown.rb
 - lib/teems/models/account.rb
 - lib/teems/models/channel.rb
 - lib/teems/models/chat.rb