vishnu-standard-time 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 59b1b839f360e681af0cf1048575aca912a8590339723b3932dc63f9b2daa648
-  data.tar.gz: 177ad7aa34b141327d871b4e5ef5547375716c245e719af0ca0db1de56b91c57
+  metadata.gz: 0d5ea2d413b3c79dc848318ee7ade65820616e070a588631f53b864f089ee641
+  data.tar.gz: 8934cbc3b798a5f3cb0bcd0d5b8a5a512170ddde50b3c61c2c68350334ced248
 SHA512:
-  metadata.gz: a86aad8123fc755334d07e62442108fc6051a284b087c1e00492e10430c1f6459fdf8ad2fd8cc026b4b220f78a4fb188abcc43306f42d2ed58b38ea8d8eb59c6
-  data.tar.gz: dde90f5af4d50f7aa97030d15c88902bcd82c11842f962559074b0bba1eda2e5aa4f11f7bf4041cf15c197b44dec5c8df31249b40bae730675c8778bc11f303d
+  metadata.gz: 9652dcd10723ab882e09d8738bf5a3c4e2349b2783814d8786404f6bea3f310247c8daf3f9594c697d755f012a0d02541ddcda7919c729ac0a66d7930f06cbdf
+  data.tar.gz: 6c6c3635ceba78fcf3b24c3560b31fdc4e902fdee328f7bbcbbf95e785f595164264326e0deeab2dae99260b1a47ce896114b7c2d2f412f1650f5f123b4c7a82

data/README.md

@@ -1,6 +1,8 @@
 # vishnu-standard-time
 
-Ruby gem for **Vishnu Standard Time (VST)**.
+Ruby gem for **Vishnu Standard Time (VST)** — a flow-based clock and productivity layer.
+
+Official clock: https://time.vishnu.store
 
 ```bash
 gem install vishnu-standard-time
@@ -9,6 +11,83 @@ gem install vishnu-standard-time
 ```ruby
 require "vishnu/standard_time"
 
-parts = Vishnu::StandardTime.now
+parts = Vishnu::StandardTime.local_now
 puts Vishnu::StandardTime.format_vst(parts)
+puts Vishnu::StandardTime.format_flows_left(parts)
+puts Vishnu::StandardTime.standard_link
+```
+
+## Core idea
+
+```text
+1 day    = 259,200 flows
+1 second = 3 flows
+1 flow   = 333⅓ ms
+```
+
+No AM/PM. No timezone drama. Just day progress and flows.
+
+## Productivity helpers
+
+```ruby
+Vishnu::StandardTime.flows_for(minutes: 25) # => 4500
+Vishnu::StandardTime.minutes_for(flows: 900) # => 5.0
+Vishnu::StandardTime.flows_left_today
+Vishnu::StandardTime.percent_remaining
+```
+
+## Focus sessions
+
+```ruby
+session = Vishnu::StandardTime.focus(flows: 4_500, label: "write README")
+
+puts session.summary
+puts session.flows_remaining
+puts session.percent_complete
+```
+
+## Planning DSL
+
+```ruby
+plan = Vishnu::StandardTime.plan do
+  block "Build", flows: 18_000
+  block "Break", minutes: 5
+  block "Ship", flows: 9_000
+end
+
+puts plan.summary
+```
+
+## Stamps for logs
+
+```ruby
+puts Vishnu::StandardTime.stamp("started deploy")
+# [VST D+000189 · 123,458 / 259,200 flows · 47.63% OF DAY] started deploy
+```
+
+## CLI
+
+```bash
+vst now
+vst now --json
+vst percent
+vst flows-left
+vst stamp "published gem"
+vst convert 25m
+vst after 4500
+vst until 180000
+vst timer 4500 "break"
+vst focus 25m "deep work"
+vst prompt
+vst badge vst.svg
+vst link
+```
+
+## Rails helpers
+
+```ruby
+# In a Rails view after requiring the gem:
+<%= vst_clock %>
+<%= vst_badge %>
+<%= vst_flows_left %>
 ```

data/exe/vst

@@ -0,0 +1,7 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vishnu/standard_time/cli"
+
+status = Vishnu::StandardTime::CLI.call(ARGV)
+exit(status || 0)

data/exe/vst.bak

@@ -0,0 +1,6 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+require "vishnu/standard_time/cli"
+
+exit Vishnu::StandardTime::CLI.call(ARGV)

data/lib/vishnu/standard_time/cli.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require "json"
+require_relative "../standard_time"
+
+module Vishnu
+  module StandardTime
+    class CLI
+      def self.call(argv = ARGV, out = $stdout, err = $stderr)
+        status = new(argv, out, err).run
+        status.nil? ? 0 : Integer(status)
+      end
+
+      def initialize(argv, out, err)
+        @argv = argv.dup
+        @out = out
+        @err = err
+      end
+
+      def run
+        command = (@argv.shift || "now").to_s
+
+        case command
+        when "now"
+          now
+        when "percent"
+          percent
+        when "flows-left", "left"
+          flows_left
+        when "stamp"
+          stamp
+        when "convert"
+          convert
+        when "after"
+          after
+        when "until"
+          until_flow
+        when "timer"
+          timer(focus: false)
+        when "focus"
+          timer(focus: true)
+        when "prompt"
+          @out.puts Vishnu::StandardTime.format_prompt(Vishnu::StandardTime.local_now)
+        when "badge"
+          badge
+        when "link", "site"
+          @out.puts Vishnu::StandardTime.standard_link
+        when "help", "-h", "--help"
+          help
+        when "version", "-v", "--version"
+          @out.puts Vishnu::StandardTime::VERSION
+        else
+          @err.puts "Unknown command: #{command}"
+          help(@err)
+          1
+        end
+      rescue ArgumentError => e
+        @err.puts "vst: #{e.message}"
+        1
+      end
+
+      private
+
+      def json?
+        @argv.delete("--json")
+      end
+
+      def precise?
+        @argv.delete("--precise")
+      end
+
+      def now
+        parts = Vishnu::StandardTime.local_now
+        if json?
+          @out.puts JSON.pretty_generate(Vishnu::StandardTime.to_h(parts))
+        else
+          @out.puts(precise? ? Vishnu::StandardTime.format_vst_precise(parts) : Vishnu::StandardTime.format_vst(parts))
+        end
+        0
+      end
+
+      def percent
+        parts = Vishnu::StandardTime.local_now
+        @out.puts Vishnu::StandardTime.format_percent_of_day(parts)
+        @out.puts Vishnu::StandardTime.format_percent_remaining(parts)
+        0
+      end
+
+      def flows_left
+        parts = Vishnu::StandardTime.local_now
+        @out.puts Vishnu::StandardTime.format_flows_left(parts)
+        0
+      end
+
+      def stamp
+        message = @argv.join(" ")
+        @out.puts Vishnu::StandardTime.stamp(message)
+        0
+      end
+
+      def convert
+        input = @argv.shift || raise(ArgumentError, "usage: vst convert 25m")
+        duration = Vishnu::StandardTime.parse_duration(input)
+        if json?
+          @out.puts JSON.pretty_generate(duration.to_h)
+        else
+          @out.puts "#{Vishnu::StandardTime.format_number(duration.flows)} flows"
+          @out.puts "#{format('%.2f', duration.seconds)} seconds"
+          @out.puts "#{format('%.2f', duration.minutes)} minutes"
+        end
+        0
+      end
+
+      def after
+        input = @argv.shift || raise(ArgumentError, "usage: vst after 4500")
+        duration = Vishnu::StandardTime.parse_duration(input)
+        target = Vishnu::StandardTime.after(flows: duration.flows, from: Vishnu::StandardTime.local_now)
+        @out.puts Vishnu::StandardTime.format_vst(target)
+        0
+      end
+
+      def until_flow
+        input = @argv.shift || raise(ArgumentError, "usage: vst until 180000")
+        result = Vishnu::StandardTime.until_flow(Integer(input), from: Vishnu::StandardTime.local_now)
+        if json?
+          @out.puts JSON.pretty_generate(result.to_h)
+        else
+          @out.puts "#{Vishnu::StandardTime.format_number(result.flows)} flows until #{input}"
+          @out.puts Vishnu::StandardTime.format_vst(result.target)
+        end
+        0
+      end
+
+      def timer(focus:)
+        input = @argv.shift || raise(ArgumentError, "usage: vst #{focus ? 'focus' : 'timer'} 4500 [label]")
+        label = @argv.join(" ")
+        duration = Vishnu::StandardTime.parse_duration(input)
+        session = Vishnu::StandardTime.focus(flows: duration.flows, label: label.empty? ? (focus ? "focus" : "timer") : label)
+
+        @out.puts "#{focus ? 'FOCUS' : 'TIMER'} · #{session.label}"
+        @out.puts "Ends at: #{Vishnu::StandardTime.format_vst(session.ends_at)}"
+
+        interrupted = false
+        trap("INT") { interrupted = true }
+
+        until interrupted || session.complete?
+          remaining = session.flows_remaining
+          percent = session.percent_complete
+          @out.print "\r#{Vishnu::StandardTime.format_number(remaining)} flows left · #{format('%.2f%%', percent)} complete"
+          @out.flush
+          sleep 1
+        end
+
+        @out.puts
+        @out.puts(interrupted ? "Stopped." : "Done.")
+        interrupted ? 130 : 0
+      end
+
+      def badge
+        path = @argv.shift
+        svg = Vishnu::StandardTime.svg_badge(Vishnu::StandardTime.local_now)
+        if path
+          File.write(path, svg)
+          @out.puts path
+        else
+          @out.puts svg
+        end
+        0
+      end
+
+      def help(io = @out)
+        io.puts <<~HELP
+          Vishnu Standard Time CLI
+
+          Usage:
+            vst now [--json] [--precise]
+            vst percent
+            vst flows-left
+            vst stamp MESSAGE
+            vst convert 4500|25m|90s|1h [--json]
+            vst after 4500|25m|90s|1h
+            vst until FLOW [--json]
+            vst timer 4500|25m [label]
+            vst focus 4500|25m [label]
+            vst prompt
+            vst badge [file.svg]
+            vst link
+
+          #{Vishnu::StandardTime.standard_link}
+        HELP
+        0
+      end
+    end
+  end
+end

data/lib/vishnu/standard_time/rails_helpers.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+require "cgi"
+require_relative "../standard_time"
+
+module Vishnu
+  module StandardTime
+    module RailsHelpers
+      def vst_clock(parts = Vishnu::StandardTime.local_now)
+        html = %(<span class="vst-clock" data-vst-url="#{CGI.escapeHTML(Vishnu::StandardTime.website_url)}">#{CGI.escapeHTML(Vishnu::StandardTime.format_vst(parts))}</span>)
+        html.respond_to?(:html_safe) ? html.html_safe : html
+      end
+
+      def vst_badge(parts = Vishnu::StandardTime.local_now)
+        html = %(<a class="vst-badge" href="#{CGI.escapeHTML(Vishnu::StandardTime.website_url)}" target="_blank" rel="noopener">#{CGI.escapeHTML(Vishnu::StandardTime.format_prompt(parts))}</a>)
+        html.respond_to?(:html_safe) ? html.html_safe : html
+      end
+
+      def vst_flows_left(parts = Vishnu::StandardTime.local_now)
+        CGI.escapeHTML(Vishnu::StandardTime.format_flows_left(parts))
+      end
+    end
+  end
+end

data/lib/vishnu/standard_time/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require_relative "rails_helpers"
+
+if defined?(Rails::Railtie)
+  module Vishnu
+    module StandardTime
+      class Railtie < Rails::Railtie
+        initializer "vishnu_standard_time.view_helpers" do
+          ActiveSupport.on_load(:action_view) do
+            include Vishnu::StandardTime::RailsHelpers
+          end
+        end
+      end
+    end
+  end
+end

data/lib/vishnu/standard_time.rb

@@ -1,14 +1,25 @@
 # frozen_string_literal: true
 
+require "cgi"
+require "time"
+
 module Vishnu
   module StandardTime
-    VST_SPEC_VERSION = "0.1.0"
+    VERSION = "0.2.0"
+    VST_SPEC_VERSION = VERSION
+
+    STANDARD_NAME = "Vishnu Standard Time"
+    WEBSITE_URL = "https://time.vishnu.store"
+
     VST_EPOCH_UNIX_MS = 1_767_225_600_000
     MS_PER_DAY = 86_400_000
     FLOWS_PER_SECOND = 3
     FLOWS_PER_MINUTE = 180
+    FLOWS_PER_HOUR = 10_800
     FLOWS_PER_DAY = 259_200
     FLOW_LENGTH_MS_TEXT = "333⅓"
+
+    # Legacy/compat display units kept for interop with early VST builds.
     VICKS_PER_DAY = 100_000
     MS_PER_VICK = 864
 
@@ -26,8 +37,172 @@ module Vishnu
       keyword_init: true
     )
 
+    Duration = Struct.new(
+      :flows,
+      :milliseconds,
+      :seconds,
+      :target,
+      keyword_init: true
+    ) do
+      def minutes
+        seconds / 60.0
+      end
+
+      def hours
+        seconds / 3600.0
+      end
+
+      def to_h
+        {
+          flows: flows,
+          milliseconds: milliseconds,
+          seconds: seconds,
+          minutes: minutes,
+          hours: hours,
+          target: target && Vishnu::StandardTime.to_h(target)
+        }
+      end
+    end
+
+    class FocusSession
+      attr_reader :label, :total_flows, :started_at, :ends_at
+
+      def initialize(total_flows:, label: nil, started_at: Vishnu::StandardTime.local_now)
+        @total_flows = Integer(total_flows)
+        raise ArgumentError, "total_flows must be positive" unless @total_flows.positive?
+
+        @label = label.to_s.strip.empty? ? "focus" : label.to_s
+        @started_at = started_at
+        @ends_at = Vishnu::StandardTime.after(flows: @total_flows, from: @started_at)
+      end
+
+      def flows_elapsed(now_parts = Vishnu::StandardTime.local_now)
+        elapsed_ms = Vishnu::StandardTime.unix_ms_for(now_parts) - Vishnu::StandardTime.unix_ms_for(started_at)
+        flows = Vishnu::StandardTime.flows_for(milliseconds: elapsed_ms)
+        [[flows, 0].max, total_flows].min
+      end
+
+      def flows_remaining(now_parts = Vishnu::StandardTime.local_now)
+        [total_flows - flows_elapsed(now_parts), 0].max
+      end
+
+      def percent_complete(now_parts = Vishnu::StandardTime.local_now)
+        (flows_elapsed(now_parts).to_f / total_flows) * 100
+      end
+
+      def complete?(now_parts = Vishnu::StandardTime.local_now)
+        flows_remaining(now_parts).zero?
+      end
+
+      def to_h(now_parts = Vishnu::StandardTime.local_now)
+        {
+          label: label,
+          total_flows: total_flows,
+          flows_elapsed: flows_elapsed(now_parts),
+          flows_remaining: flows_remaining(now_parts),
+          percent_complete: percent_complete(now_parts).round(2),
+          started_at: Vishnu::StandardTime.to_h(started_at),
+          ends_at: Vishnu::StandardTime.to_h(ends_at),
+          complete: complete?(now_parts)
+        }
+      end
+
+      def summary(now_parts = Vishnu::StandardTime.local_now)
+        "%s · %s / %s flows · %.2f%% complete" % [
+          label,
+          Vishnu::StandardTime.format_number(flows_elapsed(now_parts)),
+          Vishnu::StandardTime.format_number(total_flows),
+          percent_complete(now_parts)
+        ]
+      end
+    end
+
+    class Plan
+      Block = Struct.new(:name, :flows, keyword_init: true) do
+        def minutes
+          Vishnu::StandardTime.minutes_for(flows: flows)
+        end
+
+        def percent_of_day
+          (flows.to_f / Vishnu::StandardTime::FLOWS_PER_DAY) * 100
+        end
+
+        def to_h
+          {
+            name: name,
+            flows: flows,
+            minutes: minutes,
+            percent_of_day: percent_of_day.round(4)
+          }
+        end
+      end
+
+      attr_reader :blocks
+
+      def initialize
+        @blocks = []
+      end
+
+      def block(name, flows: nil, seconds: nil, minutes: nil, hours: nil)
+        count = flows || Vishnu::StandardTime.flows_for(seconds: seconds, minutes: minutes, hours: hours)
+        count = Integer(count)
+        raise ArgumentError, "block flows must be positive" unless count.positive?
+
+        @blocks << Block.new(name: name.to_s, flows: count)
+      end
+
+      def total_flows
+        blocks.sum(&:flows)
+      end
+
+      def total_minutes
+        Vishnu::StandardTime.minutes_for(flows: total_flows)
+      end
+
+      def percent_of_day
+        (total_flows.to_f / Vishnu::StandardTime::FLOWS_PER_DAY) * 100
+      end
+
+      def to_h
+        {
+          blocks: blocks.map(&:to_h),
+          total_flows: total_flows,
+          total_minutes: total_minutes,
+          percent_of_day: percent_of_day.round(4)
+        }
+      end
+
+      def summary
+        width = [blocks.map { |b| b.name.length }.max || 4, 4].max
+        lines = blocks.map do |entry|
+          "%#{width}s  %9s flows  %7.2f min  %6.2f%%" % [
+            entry.name,
+            Vishnu::StandardTime.format_number(entry.flows),
+            entry.minutes,
+            entry.percent_of_day
+          ]
+        end
+        lines << ""
+        lines << "%#{width}s  %9s flows  %7.2f min  %6.2f%%" % [
+          "Total",
+          Vishnu::StandardTime.format_number(total_flows),
+          total_minutes,
+          percent_of_day
+        ]
+        lines.join("\n")
+      end
+    end
+
     module_function
 
+    def website_url
+      WEBSITE_URL
+    end
+
+    def standard_link
+      "#{STANDARD_NAME} — #{WEBSITE_URL}"
+    end
+
     def from_unix_ms(unix_ms)
       ms = Integer(unix_ms)
       day, day_ms = (ms - VST_EPOCH_UNIX_MS).divmod(MS_PER_DAY)
@@ -39,11 +214,12 @@ module Vishnu
     end
 
     def parts_from_day_ms(day, day_ms, unix_ms: nil, source: "standard")
+      day_ms = Integer(day_ms)
       raise ArgumentError, "day_ms must be from 0 through 86399999" if day_ms.negative? || day_ms >= MS_PER_DAY
 
       flow = (day_ms * FLOWS_PER_DAY) / MS_PER_DAY
       Parts.new(
-        day: day,
+        day: Integer(day),
         day_ms: day_ms,
         flow: flow,
         flow_of_minute: flow % FLOWS_PER_MINUTE,
@@ -68,8 +244,15 @@ module Vishnu
       parts_from_day_ms(day, day_ms, unix_ms: (time.to_f * 1000).floor, source: "local")
     end
 
+    def unix_ms_for(parts)
+      return Integer(parts) if parts.is_a?(Integer)
+      return Integer(parts.unix_ms) if parts.respond_to?(:unix_ms) && parts.unix_ms
+
+      to_unix_ms(parts)
+    end
+
     def to_unix_ms(parts)
-      VST_EPOCH_UNIX_MS + parts.day * MS_PER_DAY + parts.day_ms
+      VST_EPOCH_UNIX_MS + Integer(parts.day) * MS_PER_DAY + Integer(parts.day_ms)
     end
 
     def format_vst_day(parts)
@@ -77,13 +260,19 @@ module Vishnu
       "D#{sign}#{parts.day.abs.to_s.rjust(6, "0")}" 
     end
 
+    def format_number(value, pad: false)
+      s = Integer(value).abs.to_s
+      s = s.rjust(6, "0") if pad
+      grouped = s.reverse.gsub(/(\d{3})(?=\d)/, "\\1,").reverse
+      Integer(value).negative? ? "-#{grouped}" : grouped
+    end
+
     def comma6(value)
-      s = value.to_i.to_s.rjust(6, "0")
-      "#{s[0, 3]},#{s[3, 3]}"
+      format_number(value, pad: true)
     end
 
     def format_flow_count(parts)
-      "#{comma6(parts.flow)} / 259,200 flows"
+      "#{comma6(parts.flow)} / #{format_number(FLOWS_PER_DAY)} flows"
     end
 
     def format_flow_of_minute(parts)
@@ -94,6 +283,14 @@ module Vishnu
       "%0#{digits + 3}.#{digits}f%% OF DAY" % parts.percent_of_day
     end
 
+    def format_percent_remaining(parts, digits = 2)
+      "%0#{digits + 3}.#{digits}f%% DAY REMAINING" % percent_remaining(parts)
+    end
+
+    def format_flows_left(parts = local_now)
+      "#{format_number(flows_left_today(parts))} flows left today"
+    end
+
     def format_vst(parts)
       "VST #{format_vst_day(parts)} · #{format_flow_count(parts)} · #{format_percent_of_day(parts)}"
     end
@@ -102,6 +299,152 @@ module Vishnu
       "VST #{format_vst_day(parts)} · #{format_flow_of_minute(parts)} · #{format_flow_count(parts)} · #{format_percent_of_day(parts)}"
     end
 
+    def format_prompt(parts = local_now)
+      "VST #{comma6(parts.flow)}/#{format_number(FLOWS_PER_DAY)} #{format('%.2f%%', parts.percent_of_day)}"
+    end
+
+    def flows_elapsed_today(parts = local_now)
+      Integer(parts.flow)
+    end
+
+    def flows_left_today(parts = local_now)
+      [FLOWS_PER_DAY - flows_elapsed_today(parts), 0].max
+    end
+
+    def percent_remaining(parts = local_now)
+      [100.0 - parts.percent_of_day.to_f, 0.0].max
+    end
+
+    def flows_for(seconds: nil, minutes: nil, hours: nil, days: nil, milliseconds: nil)
+      total_seconds = 0.0
+      total_seconds += seconds.to_f if seconds
+      total_seconds += minutes.to_f * 60 if minutes
+      total_seconds += hours.to_f * 3600 if hours
+      total_seconds += days.to_f * 86_400 if days
+      total_seconds += milliseconds.to_f / 1000 if milliseconds
+      (total_seconds * FLOWS_PER_SECOND).round
+    end
+
+    def seconds_for(flows:)
+      flows.to_f / FLOWS_PER_SECOND
+    end
+
+    def minutes_for(flows:)
+      seconds_for(flows: flows) / 60.0
+    end
+
+    def hours_for(flows:)
+      seconds_for(flows: flows) / 3600.0
+    end
+
+    def duration_ms_for(flows: nil, seconds: nil, minutes: nil, hours: nil, days: nil, milliseconds: nil)
+      ms = 0.0
+      ms += flows.to_f * 1000.0 / FLOWS_PER_SECOND if flows
+      ms += seconds.to_f * 1000 if seconds
+      ms += minutes.to_f * 60_000 if minutes
+      ms += hours.to_f * 3_600_000 if hours
+      ms += days.to_f * MS_PER_DAY if days
+      ms += milliseconds.to_f if milliseconds
+      ms.positive? ? ms.ceil : ms.floor
+    end
+
+    def duration(flows: nil, seconds: nil, minutes: nil, hours: nil, days: nil, milliseconds: nil)
+      ms = duration_ms_for(
+        flows: flows,
+        seconds: seconds,
+        minutes: minutes,
+        hours: hours,
+        days: days,
+        milliseconds: milliseconds
+      )
+      Duration.new(
+        flows: flows || flows_for(milliseconds: ms),
+        milliseconds: ms,
+        seconds: ms / 1000.0
+      )
+    end
+
+    def parse_duration(input)
+      text = input.to_s.strip.downcase
+      raise ArgumentError, "duration is required" if text.empty?
+
+      case text
+      when /\A([+-]?\d+(?:\.\d+)?)\s*(f|flow|flows)?\z/
+        flows = Regexp.last_match(1).to_f
+        duration(flows: flows)
+      when /\A([+-]?\d+(?:\.\d+)?)\s*(ms|millisecond|milliseconds)\z/
+        duration(milliseconds: Regexp.last_match(1).to_f)
+      when /\A([+-]?\d+(?:\.\d+)?)\s*(s|sec|secs|second|seconds)\z/
+        duration(seconds: Regexp.last_match(1).to_f)
+      when /\A([+-]?\d+(?:\.\d+)?)\s*(m|min|mins|minute|minutes)\z/
+        duration(minutes: Regexp.last_match(1).to_f)
+      when /\A([+-]?\d+(?:\.\d+)?)\s*(h|hr|hrs|hour|hours)\z/
+        duration(hours: Regexp.last_match(1).to_f)
+      when /\A([+-]?\d+(?:\.\d+)?)\s*(d|day|days)\z/
+        duration(days: Regexp.last_match(1).to_f)
+      else
+        raise ArgumentError, "unknown duration '#{input}'. Try 4500, 4500f, 25m, 90s, 1h."
+      end
+    end
+
+    def after(flows: nil, seconds: nil, minutes: nil, hours: nil, days: nil, milliseconds: nil, from: local_now)
+      ms = unix_ms_for(from) + duration_ms_for(
+        flows: flows,
+        seconds: seconds,
+        minutes: minutes,
+        hours: hours,
+        days: days,
+        milliseconds: milliseconds
+      )
+
+      from.respond_to?(:source) && from.source == "local" ? local_now(Time.at(ms / 1000.0)) : from_unix_ms(ms)
+    end
+
+    def until_flow(target_flow, from: local_now)
+      target = Integer(target_flow)
+      raise ArgumentError, "target flow must be from 0 through #{FLOWS_PER_DAY - 1}" if target.negative? || target >= FLOWS_PER_DAY
+
+      current = Integer(from.flow)
+      flow_delta = target >= current ? target - current : FLOWS_PER_DAY - current + target
+      ms = duration_ms_for(flows: flow_delta)
+      Duration.new(
+        flows: flow_delta,
+        milliseconds: ms,
+        seconds: ms / 1000.0,
+        target: after(flows: flow_delta, from: from)
+      )
+    end
+
+    def focus(flows: nil, seconds: nil, minutes: nil, hours: nil, label: nil, started_at: local_now)
+      total = flows || flows_for(seconds: seconds, minutes: minutes, hours: hours)
+      FocusSession.new(total_flows: total, label: label, started_at: started_at)
+    end
+
+    def plan(&block)
+      p = Plan.new
+      p.instance_eval(&block) if block
+      p
+    end
+
+    def stamp(message = nil, parts = local_now)
+      suffix = message.to_s.strip
+      suffix.empty? ? "[#{format_vst(parts)}]" : "[#{format_vst(parts)}] #{suffix}"
+    end
+
+    def svg_badge(parts = local_now, width: 560, height: 32)
+      text = CGI.escapeHTML(format_vst(parts))
+      url = CGI.escapeHTML(WEBSITE_URL)
+      <<~SVG.strip
+        <svg xmlns="http://www.w3.org/2000/svg" width="#{Integer(width)}" height="#{Integer(height)}" role="img" aria-label="#{text}">
+          <title>#{text}</title>
+          <a href="#{url}" target="_blank">
+            <rect width="100%" height="100%" rx="6"/>
+            <text x="12" y="21" font-family="ui-monospace, SFMono-Regular, Menlo, Consolas, monospace" font-size="13" fill="white">#{text}</text>
+          </a>
+        </svg>
+      SVG
+    end
+
     def to_h(parts)
       {
         scale: "VST",
@@ -110,12 +453,23 @@ module Vishnu
         flow: parts.flow,
         flow_of_minute: parts.flow_of_minute,
         flows_per_day: FLOWS_PER_DAY,
+        flows_left_today: flows_left_today(parts),
         percent_of_day: parts.percent_of_day.round(6),
+        percent_remaining: percent_remaining(parts).round(6),
         text: format_vst(parts),
+        precise_text: format_vst_precise(parts),
         day_ms: parts.day_ms.to_s,
         vick: parts.vick,
-        pulse: parts.pulse
+        pulse: parts.pulse,
+        website_url: WEBSITE_URL,
+        standard_link: standard_link
       }
     end
   end
 end
+
+begin
+  require_relative "standard_time/railtie" if defined?(Rails)
+rescue LoadError
+  # Rails is optional.
+end

data/vishnu-standard-time.gemspec

@@ -1,16 +1,20 @@
 Gem::Specification.new do |spec|
   spec.name = "vishnu-standard-time"
-  spec.version = "0.1.0"
-  spec.summary = "Vishnu Standard Time (VST): 259,200 flows per day, no AM/PM."
+  spec.version = "0.2.0"
+  spec.summary = "Vishnu Standard Time (VST): flow-based time and productivity tools."
+  spec.description = "Vishnu Standard Time replaces AM/PM with 259,200 flows per day and ships helpers, a CLI, focus sessions, planning primitives, Rails helpers, and badges."
   spec.authors = ["Vishnu"]
   spec.license = "MIT"
   spec.required_ruby_version = ">= 3.0"
-  spec.files = Dir["lib/**/*.rb", "README.md", "LICENSE*", "*.gemspec"]
+  spec.files = Dir["lib/**/*.rb", "exe/*", "README.md", "LICENSE*", "*.gemspec"]
   spec.require_paths = ["lib"]
+  spec.bindir = "exe"
+  spec.executables = ["vst"]
   spec.homepage = "https://time.vishnu.store"
   spec.metadata = {
-    "source_code_uri" => "https://time.vishnu.store",
+    "homepage_uri" => "https://time.vishnu.store",
     "changelog_uri" => "https://time.vishnu.store/.well-known/vst.json"
   }
+
   spec.add_development_dependency "minitest", "~> 5.25"
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: vishnu-standard-time
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Vishnu
-bindir: bin
+bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies:
@@ -23,18 +23,26 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '5.25'
-executables: []
+description: Vishnu Standard Time replaces AM/PM with 259,200 flows per day and ships
+  helpers, a CLI, focus sessions, planning primitives, Rails helpers, and badges.
+executables:
+- vst
 extensions: []
 extra_rdoc_files: []
 files:
 - README.md
+- exe/vst
+- exe/vst.bak
 - lib/vishnu/standard_time.rb
+- lib/vishnu/standard_time/cli.rb
+- lib/vishnu/standard_time/rails_helpers.rb
+- lib/vishnu/standard_time/railtie.rb
 - vishnu-standard-time.gemspec
 homepage: https://time.vishnu.store
 licenses:
 - MIT
 metadata:
-  source_code_uri: https://time.vishnu.store
+  homepage_uri: https://time.vishnu.store
   changelog_uri: https://time.vishnu.store/.well-known/vst.json
 rdoc_options: []
 require_paths:
@@ -52,5 +60,5 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 3.6.9
 specification_version: 4
-summary: 'Vishnu Standard Time (VST): 259,200 flows per day, no AM/PM.'
+summary: 'Vishnu Standard Time (VST): flow-based time and productivity tools.'
 test_files: []