do_run 0.1.0

data/lib/do/config.rb

@@ -0,0 +1,163 @@
+require 'toml-rb'
+require_relative 'task'
+require_relative 'error'
+
+module Do
+  # Loads and represents the declarative TOML configuration.
+  #
+  # The TOML file is the source of truth. Everything else `do` produces is a
+  # derived artifact. This class only parses the file; validation is performed
+  # by {Validator}.
+  class Config
+    KNOWN_TASK_FIELDS = %w[
+      command schedule time day working_directory environment enabled
+    ].freeze
+
+    # Default location when no path is given.
+    def self.default_path
+      dir = ENV.fetch('XDG_CONFIG_HOME', nil)
+      dir = File.join(Dir.home, '.config') if dir.nil? || dir.empty?
+      File.join(dir, 'do', 'config.toml')
+    end
+
+    # @return [Array<String>] validation errors found while parsing.
+    def self.parse(raw_text, source: 'config.toml')
+      parsed = TomlRB.parse(raw_text)
+      new(parsed, source: source)
+    rescue TomlRB::ParseError, Psych::SyntaxError => e
+      raise ValidationError, ["Malformed TOML in #{source}: #{e.message}"]
+    rescue StandardError => e
+      raise ValidationError, ["Failed to parse #{source}: #{e.message}"]
+    end
+
+    def self.load(path = default_path)
+      raise Error, "Configuration file does not exist: #{path}" unless File.exist?(path)
+
+      raw = File.read(path)
+      config = parse(raw, source: path)
+      config.path = path
+      config
+    end
+
+    attr_reader :raw, :tasks
+    attr_accessor :path
+
+    def initialize(raw, source: nil)
+      @raw = raw || {}
+      @source = source
+      @tasks = build_tasks(@raw['tasks'])
+    end
+
+    def task(name)
+      @tasks.find { |t| t.name == name }
+    end
+
+    def [](key)
+      @raw[key]
+    end
+
+    # Edit a scalar field inside a task's table without re-serializing the
+    # whole file (preserving user comments/formatting elsewhere). Used by
+    # `enable`/`disable`.
+    def set_task_field(task_name, field, toml_value)
+      text = File.read(@path)
+      idx = block_start_index(text, task_name)
+      return edit_field_anywhere(text, task_name, field, toml_value) if idx.nil?
+
+      lines = text.lines
+      block_end = block_end_index(lines, idx)
+      match = (idx...block_end).find { |i| lines[i] =~ /\A#{Regexp.escape(field)}\s*=/ }
+      if match
+        lines[match] = "#{field} = #{toml_value}\n"
+      else
+        lines.insert(idx + 1, "#{field} = #{toml_value}\n")
+      end
+      File.write(@path, lines.join)
+    end
+
+    # Remove a task's table from the file. Used by `do remove`. Also removes
+    # any nested tables under the same task (e.g. `[tasks.name.environment]`).
+    def remove_task(task_name)
+      text = File.read(@path)
+      idx = block_start_index(text, task_name)
+      raise Error, "task '#{task_name}' not present in configuration" if idx.nil?
+
+      lines = text.lines
+      block_end = task_block_end(lines, idx, task_name)
+      removed = lines[0...idx] + lines[block_end..]
+      # Collapse leftover blank lines around the removed block (best effort).
+      File.write(@path, removed.join.gsub(/\n{3,}/, "\n\n"))
+    end
+
+    private
+
+    # Continue past nested tables that belong to the same task.
+    def task_block_end(lines, idx, task_name)
+      i = idx + 1
+      while i < lines.length
+        line = lines[i]
+        break if line.start_with?('[') && !line.start_with?("[tasks.#{task_name}.") &&
+                 !line.start_with?("[tasks.\"#{task_name}\".")
+
+        i += 1
+      end
+      i
+    end
+
+    def block_start_index(text, task_name)
+      re = /\[tasks\.#{Regexp.escape(task_name)}\]\s*\z|\[tasks\."#{Regexp.escape(task_name)}"\]\s*\z/
+      text.lines.index { |l| l.start_with?('[tasks.') && l =~ re }
+    end
+
+    def block_end_index(lines, idx)
+      i = idx + 1
+      i += 1 while i < lines.length && !lines[i].start_with?('[')
+      i
+    end
+
+    # Fallback: file may have been edited/scrambled; attempt a field swap
+    # outside a knowing block. Keeps commands non-destructive toward comments.
+    def edit_field_anywhere(text, task_name, field, toml_value)
+      header = "[tasks.#{task_name}]"
+      return unless text.include?(header)
+
+      _ = text
+      hmm = text.gsub(/^(\s*)#{Regexp.escape(field)}\s*=.*/, "  #{field} = #{toml_value}")
+      File.write(@path, hmm) if hmm != text
+    end
+
+    def build_tasks(raw_tasks)
+      return [] if raw_tasks.nil?
+
+      unless raw_tasks.is_a?(Hash)
+        raise ValidationError, ["'tasks' must be a table of task definitions in #{@source}"]
+      end
+
+      raw_tasks.map do |name, fields|
+        fields ||= {}
+        unless fields.is_a?(Hash)
+          raise ValidationError, ["task '#{name}' definitions must be tables in #{@source}"]
+        end
+
+        env = fields['environment']
+        unless env.nil? || env.is_a?(Hash)
+          raise ValidationError, ["environment for task '#{name}' must be a table in #{@source}"]
+        end
+
+        Task.new(
+          name: name.to_s,
+          command: fields['command'],
+          schedule: fields['schedule'],
+          time: fields['time'],
+          day: fields['day'],
+          working_directory: fields['working_directory'],
+          environment: env,
+          enabled: fields['enabled'],
+          raw: fields
+        )
+      end
+    rescue TypeError => e
+      raise ValidationError, ["Invalid configuration structure: #{e.message}"]
+    end
+  end
+end

data/lib/do/error.rb

@@ -0,0 +1,14 @@
+module Do
+  # Top-level error for all normal user-facing failures.
+  class Error < StandardError
+  end
+
+  class ValidationError < Error
+    attr_reader :errors
+
+    def initialize(errors)
+      @errors = Array(errors)
+      super(@errors.join("\n"))
+    end
+  end
+end

data/lib/do/executor.rb

@@ -0,0 +1,36 @@
+require 'shellwords'
+require_relative 'error'
+
+module Do
+  # Executes a task's command as an argument list, without a shell.
+  #
+  # The `command` string is split into argv tokens lexically (respecting
+  # quoting but performing no variable expansion, `~` expansion, or globbing).
+  # This is the safe, declarative default described in the spec. Tasks that
+  # genuinely need shell features must request them explicitly, e.g. by
+  # prefixing with `bash -lc '...'`.
+  class Executor
+    attr_reader :systemd
+
+    def initialize(systemd: Systemd.new)
+      @systemd = systemd
+    end
+
+    # Run the task immediately and return its exit status. The timer schedule
+    # is never altered by manual execution.
+    #
+    # @return [Integer] process exit status
+    def run(task)
+      argv = Shellwords.split(task.command)
+      raise Error, "task '#{task.name}' has an empty command" if argv.empty?
+
+      env_overrides = task.environment || {}
+      options = {}
+      options[:chdir] = File.expand_path(task.working_directory) if task.working_directory
+
+      pid = Process.spawn(env_overrides, *argv, options)
+      _pid, status = Process.wait2(pid)
+      status.exitstatus || 0
+    end
+  end
+end

data/lib/do/manager.rb

@@ -0,0 +1,114 @@
+require 'fileutils'
+require_relative 'systemd'
+require_relative 'validator'
+require_relative 'error'
+
+module Do
+  # Orchestrates the lifecycle of generated units against the systemd user
+  # manager. This is the layer that turns config into reality: writing unit
+  # files, detecting and removing stale `do`-managed units, reloading systemd,
+  # and enabling/disabling schedulers.
+  class Manager
+    attr_reader :systemd
+
+    def initialize(systemd: Systemd.new, config: nil)
+      @systemd = systemd
+      @config = config
+    end
+
+    attr_writer :config
+
+    # Apply the configuration to the user systemd manager.
+    #
+    # Never overwrites units without the `do` marker. Refuses to run when the
+    # configuration is invalid.
+    def reload(config = @config)
+      Validator.validate!(config)
+      dir = @systemd.unit_dir
+      FileUtils.mkdir_p(dir)
+
+      expected = {}
+      config.tasks.each do |task|
+        next unless task.scheduled?
+
+        expected[task.service_unit] =
+          UnitGenerator.service_content(task, source_path: config.path)
+        expected[task.timer_unit] = UnitGenerator.timer_content(task, source_path: config.path)
+      end
+
+      write_units(dir, expected)
+      remove_stale_units(dir, expected.keys)
+      @systemd.daemon_reload
+      apply_enabled(config)
+      :ok
+    end
+
+    # Remove a task's generated units (if any) and reload. Does not touch the
+    # TOML configuration.
+    def unschedule(task, _config = @config)
+      remove_units_for(task)
+      @systemd.daemon_reload
+      :ok
+    end
+
+    # Remove all units a task owns, regardless of whether the task is
+    # scheduled. Used by `do remove`.
+    def remove_units_for(task)
+      [task.service_unit, task.timer_unit].each do |unit|
+        path = File.join(@systemd.unit_dir, unit)
+        FileUtils.rm_f(path) if File.exist?(path) && managed?(path)
+        @systemd.disable(unit) if @systemd.exists?(unit)
+      end
+      @systemd.daemon_reload
+      :ok
+    end
+
+    private
+
+    def write_units(dir, expected)
+      expected.each do |unit, content|
+        path = File.join(dir, unit)
+        existing = File.exist?(path) ? File.read(path) : nil
+        File.write(path, content) if existing != content
+      end
+    end
+
+    # Remove `do`-managed units that are no longer expected (deleted task or
+    # a schedule was removed). Only files carrying the managed marker are
+    # considered; user-created units are never touched.
+    def remove_stale_units(dir, expected)
+      stale = Dir.glob(File.join(dir, 'do-*.{service,timer}')).select do |path|
+        basename = File.basename(path)
+        !expected.include?(basename) && managed?(path)
+      end
+      stale.each do |path|
+        FileUtils.rm_f(path)
+        disable_if_known(File.basename(path))
+      end
+    end
+
+    def disable_if_known(unit)
+      @systemd.disable(unit) if @systemd.exists?(unit)
+    end
+
+    def managed?(path)
+      File.read(path).lines.any? { |l| l.include?('Managed by do') }
+    rescue Errno::ENOENT
+      false
+    end
+
+    def apply_enabled(config)
+      config.tasks.each do |task|
+        next unless task.scheduled?
+
+        if task.enabled?
+          @systemd.enable(task.timer_unit)
+          @systemd.start(task.timer_unit)
+        else
+          @systemd.disable(task.timer_unit)
+          @systemd.stop(task.timer_unit) if @systemd.active?(task.timer_unit)
+        end
+      end
+    end
+  end
+end

data/lib/do/scheduler.rb

@@ -0,0 +1,93 @@
+require_relative 'error'
+
+module Do
+  # Translates a task's declarative schedule into a systemd calendar
+  # expression ({#on_calendar}) suitable for use in an `OnCalendar=` directive.
+  #
+  # `do` does not implement its own timer loop; it only maps a small, fixed set
+  # of schedule shapes onto systemd's native calendar syntax.
+  class Scheduler
+    TIME_RE = /\A([01]?\d|2[0-3]):([0-5]\d)\z/
+
+    # @return [String, nil] the systemd OnCalendar expression, or nil when the
+    #   task is manual-only.
+    def self.on_calendar(task)
+      case task.schedule
+      when nil, '' then nil
+      when 'once'   then once_calendar
+      when 'hourly' then hourly_calendar(task)
+      when 'daily'  then daily_calendar(task)
+      when 'weekly' then weekly_calendar(task)
+      when 'monthly' then monthly_calendar(task)
+      else
+        raise Error, "unsupported schedule '#{task.schedule}'"
+      end
+    end
+
+    def self.once_calendar
+      # OnActiveSec=0 fires the service exactly once, when the timer is
+      # activated. The reload/enable workflow activates the timer, so `once`
+      # means "run once now when scheduled", without repeating.
+      'OnActiveSec=0'
+    end
+
+    def self.hourly_calendar(task)
+      _, min = split_time(task, fallback: [0, 0])
+      "*-*-* *:#{pad(min)}:00"
+    end
+
+    def self.daily_calendar(task)
+      hour, min = split_time(task, fallback: [0, 0])
+      "*-*-* #{pad(hour)}:#{pad(min)}:00"
+    end
+
+    def self.weekly_calendar(task)
+      hour, min = split_time(task, fallback: [0, 0])
+      dow = weekday_short(task)
+      "#{dow} *-*-* #{pad(hour)}:#{pad(min)}:00"
+    end
+
+    def self.monthly_calendar(task)
+      hour, min = split_time(task, fallback: [0, 0])
+      dom = monthly_day(task)
+      "*-*-#{dom} #{pad(hour)}:#{pad(min)}:00"
+    end
+
+    def self.weekday_short(task)
+      day = task.day&.to_s&.downcase
+      Task::WEEKDAY_NUMBERS[day] or
+        raise Error, "invalid day '#{task.day}'; expected a day name like 'monday'"
+      day[0, 3].capitalize
+    end
+
+    def self.weekday_number(task)
+      day = task.day&.to_s&.downcase
+      Task::WEEKDAY_NUMBERS[day] or
+        raise Error, "invalid day '#{task.day}'; expected a day name like 'monday'"
+    end
+
+    def self.monthly_day(task)
+      day = task.day&.to_s
+      if day.nil? || day.empty?
+        '1'
+      elsif day =~ /\A([1-9]|[12]\d|3[01])\z/
+        day
+      else
+        raise Error, "invalid monthly day '#{task.day}'; expected a day-of-month 1-31"
+      end
+    end
+
+    def self.split_time(task, fallback:)
+      return fallback if task.time.nil? || task.time.empty?
+
+      m = TIME_RE.match(task.time.to_s)
+      raise Error, "invalid time '#{task.time}'; expected HH:MM" unless m
+
+      [m[1].to_i, m[2].to_i]
+    end
+
+    def self.pad(value)
+      value.to_s.rjust(2, '0')
+    end
+  end
+end

data/lib/do/systemd.rb

@@ -0,0 +1,214 @@
+require_relative 'error'
+require_relative 'scheduler'
+
+module Do
+  # Generates the systemd user unit files that `do` manages, and wraps the
+  # `systemctl --user` / `journalctl --user` commands used to control them.
+  #
+  # Generated unit files carry a clear "Managed by do" marker so they can be
+  # safely detected, updated, and removed later. Units not carrying this marker
+  # are never touched by `do`.
+  module UnitGenerator
+    MANAGED_MARKER = '# Managed by do. Do not edit by hand.'.freeze
+
+    module_function
+
+    def service_content(task, source_path: nil)
+      env_lines = task.environment.map { |k, v| "Environment=#{k}=#{v}" }
+      [
+        managed_header(source_path),
+        '',
+        '[Unit]',
+        "Description=do task: #{task.name}",
+        '',
+        '[Service]',
+        'Type=oneshot',
+        "ExecStart=#{task.command}"
+      ].concat(
+        if task.working_directory
+          ["WorkingDirectory=#{task.working_directory}"]
+        else
+          []
+        end
+      ).concat(
+        env_lines,
+        ['', '[Install]', 'WantedBy=default.target']
+      ).join("\n") + "\n"
+    end
+
+    def timer_content(task, source_path: nil)
+      on_calendar = Scheduler.on_calendar(task)
+      calendar_line =
+        if on_calendar&.start_with?('OnActiveSec=')
+          on_calendar
+        else
+          "OnCalendar=#{on_calendar}"
+        end
+      [
+        managed_header(source_path),
+        '',
+        '[Unit]',
+        "Description=do task: #{task.name} (timer)",
+        '',
+        '[Timer]',
+        calendar_line
+      ].concat(
+        if task.schedule == 'once'
+          []
+        else
+          ['Persistent=true']
+        end
+      ).push(
+        '', '[Install]', 'WantedBy=timers.target'
+      ).join("\n") + "\n"
+    end
+
+    def managed_header(source_path)
+      lines = [MANAGED_MARKER]
+      lines << "# Source: #{source_path}" if source_path
+      lines.join("\n")
+    end
+  end
+
+  # Wraps systemd user session commands. All calls run through the current
+  # user's systemd user manager; `do` never touches system-wide units.
+  class Systemd
+    attr_reader :systemctl_bin, :journalctl_bin
+
+    def initialize(systemctl_bin: ENV.fetch('SYSTEMCTL', 'systemctl'),
+                   journalctl_bin: ENV.fetch('JOURNALCTL', 'journalctl'))
+      @systemctl_bin = systemctl_bin
+      @journalctl_bin = journalctl_bin
+    end
+
+    def user_available?
+      shell_system([@systemctl_bin, '--user', 'is-system-running'],
+                   out: File::NULL, err: File::NULL)
+    end
+
+    def unit_dir
+      dir = ENV.fetch('XDG_CONFIG_HOME', nil)
+      dir = File.join(Dir.home, '.config') if dir.nil? || dir.empty?
+      File.join(dir, 'systemd', 'user')
+    end
+
+    def exists?(unit)
+      run(['show', '-p', 'Id', '--no-pager', unit]).success?
+    end
+
+    def enabled?(unit)
+      run(['is-enabled', '--no-pager', unit]).success?
+    end
+
+    def active?(unit)
+      run(['is-active', '--no-pager', unit]).success?
+    end
+
+    def enable(unit)
+      run(['enable', '--now', unit])
+    end
+
+    def disable(unit)
+      run(['disable', '--now', unit])
+    end
+
+    def start(unit)
+      run(['start', unit])
+    end
+
+    def stop(unit)
+      run(['stop', unit])
+    end
+
+    def daemon_reload
+      run(['daemon-reload'])
+    end
+
+    def status(unit, extra: '--no-pager')
+      run(['status', unit, extra])
+    end
+
+    # @return [Time, nil] formatted next-elapsed time from a timer unit.
+    def next_time(unit)
+      require 'time'
+      value = show_prop(unit, 'NextElapseUSecRealtime')
+      return nil if value.nil? || value.empty?
+
+      Time.parse(value).localtime
+    rescue ArgumentError
+      nil
+    end
+
+    # @return [Time, nil] when the service last transitioned to active.
+    def last_active(unit)
+      value = show_prop(unit, 'ActiveEnterTimestamp')
+      value.nil? || value.empty? ? nil : Time.parse(value).localtime
+    end
+
+    # @return [Integer, nil] exit status of the last run of a service.
+    def last_exit_status(unit)
+      value = show_prop(unit, 'ExecMainStatus')
+      value.nil? || value.empty? ? nil : value.to_i
+    end
+
+    def active_state(unit)
+      show_prop(unit, 'ActiveState')
+    end
+
+    # @return [String, nil] a whitespace-trimmed value for +prop+.
+    def show_prop(unit, prop)
+      require 'time'
+      out = run(['show', '-p', prop, '--no-pager', unit]).out
+      m = out.match(/^#{Regexp.escape(prop)}=(.+)$/)
+      m ? m[1].strip : nil
+    end
+
+    def logs(unit, follow: false, tail: nil)
+      args = ['-u', unit, '--no-pager']
+      args << '-f' if follow
+      args << "-n #{tail}" if tail
+      system(*[@journalctl_bin, '--user', *args].flatten)
+    end
+
+    # Run a systemctl --user command, returning an Open3 result-like struct
+    # exposing #success?, #out, #err, #exitstatus.
+    def run(args)
+      require 'open3'
+      @out, @err, @status = Open3.capture3(@systemctl_bin, '--user', *args)
+      OpenStructish.new(@status.exitstatus, @out, @err, @status.success?)
+    end
+
+    private
+
+    def shell_system(args, **opts)
+      SystemRaw.new(args, opts)
+    end
+
+    # Minimal result holder so tests and callers share one shape.
+    class OpenStructish
+      attr_reader :exitstatus, :out, :err
+
+      def initialize(exitstatus, out, err, success)
+        @exitstatus = exitstatus
+        @out = out
+        @err = err
+        @success = success
+      end
+
+      def success?
+        @success
+      end
+    end
+
+    class SystemRaw
+      def initialize(args, opts)
+        @args = args
+        @ok = system(*args, **opts)
+      end
+
+      def success?
+        @ok
+      end
+    end
+  end
+end

data/lib/do/task.rb

@@ -0,0 +1,53 @@
+module Do
+  # A single declared task parsed from the TOML configuration.
+  #
+  # Tasks are plain Ruby objects; the {Validator} is responsible for deciding
+  # whether their field values are acceptable. This class only carries data
+  # and exposes a few derived helpers.
+  class Task
+    SCHEDULES = %w[once hourly daily weekly monthly].freeze
+    WEEKDAY_NAMES = %w[monday tuesday wednesday thursday friday saturday sunday].freeze
+    WEEKDAY_NUMBERS = {
+      'monday' => 1, 'tuesday' => 2, 'wednesday' => 3, 'thursday' => 4,
+      'friday' => 5, 'saturday' => 6, 'sunday' => 7
+    }.freeze
+
+    attr_reader :name, :command, :schedule, :time, :day,
+                :working_directory, :environment, :raw
+
+    def initialize(name:, command:, schedule: nil, time: nil, day: nil,
+                   working_directory: nil, environment: {}, enabled: nil, raw: {})
+      @name = name
+      @command = command
+      @schedule = schedule
+      @time = time
+      @day = day
+      @working_directory = working_directory
+      @environment = environment || {}
+      @enabled = enabled
+      @raw = raw
+    end
+
+    # `enabled` is true by default for scheduled tasks and false for
+    # manual-only (unscheduled) tasks.
+    def enabled?
+      return scheduled? if @enabled.nil?
+      return @enabled == 'true' || @enabled == true if @enabled.is_a?(String)
+
+      !!@enabled
+    end
+
+    def scheduled?
+      !@schedule.nil? && @schedule != ''
+    end
+
+    # Return the service unit name systemd will use for this task.
+    def service_unit
+      "do-#{name}.service"
+    end
+
+    def timer_unit
+      "do-#{name}.timer"
+    end
+  end
+end