aias 0.1.0

data/lib/aias/cron_describer.rb

@@ -0,0 +1,142 @@
+# frozen_string_literal: true
+
+module Aias
+  # Converts a cron expression or @ keyword into a plain-English description.
+  # Returns the original expression unchanged for anything it cannot parse,
+  # so it is always safe to call.
+  #
+  # Usage:
+  #   CronDescriber.describe("0 8 * * *")         # => "every day at 8am"
+  #   CronDescriber.describe("0 8 * * 1-5")       # => "every weekday at 8am"
+  #   CronDescriber.display("0 8 * * *")           # => "every day at 8am (0 8 * * *)"
+  class CronDescriber
+    DAYS = %w[Sunday Monday Tuesday Wednesday Thursday Friday Saturday].freeze
+
+    MONTHS = [
+      nil, "January", "February", "March", "April", "May", "June",
+      "July", "August", "September", "October", "November", "December"
+    ].freeze
+
+    KEYWORDS = {
+      "@yearly"   => "every year",
+      "@annually" => "every year",
+      "@monthly"  => "every month",
+      "@weekly"   => "every Sunday at midnight",
+      "@daily"    => "every day at midnight",
+      "@midnight" => "every day at midnight",
+      "@hourly"   => "every hour"
+    }.freeze
+
+    # Returns "plain english (expr)".
+    def self.display(expr)
+      desc = describe(expr)
+      desc == expr ? expr : "#{desc} (#{expr})"
+    end
+
+    # Returns only the plain-English description (or the original expr on failure).
+    def self.describe(expr)
+      new(expr.to_s.strip).describe
+    end
+
+    def initialize(expr)
+      @expr = expr
+    end
+
+    def describe
+      return KEYWORDS[@expr] if KEYWORDS.key?(@expr)
+
+      parts = @expr.split
+      return @expr unless parts.size == 5
+
+      min, hour, dom, mon, dow = parts
+
+      # Fall back for step expressions (*/n) — we don't describe these.
+      return @expr if [min, hour, dom, mon, dow].any? { |f| f.include?("/") }
+
+      "#{describe_date(dom, mon, dow)}#{describe_time(min, hour)}"
+    rescue StandardError
+      @expr
+    end
+
+    private
+
+    # -------------------------------------------------------------------------
+    # Time
+    # -------------------------------------------------------------------------
+
+    def describe_time(min, hour)
+      return "" if hour == "*" && min == "*"
+      return " at every minute" if hour != "*" && min == "*"
+      return "" if hour == "*"
+
+      format_clock(hour.to_i, min.to_i)
+    end
+
+    def format_clock(hour, min)
+      ampm = hour < 12 ? "am" : "pm"
+      h    = hour % 12
+      h    = 12 if h == 0
+      m    = min.zero? ? "" : ":#{min.to_s.rjust(2, '0')}"
+      " at #{h}#{m}#{ampm}"
+    end
+
+    # -------------------------------------------------------------------------
+    # Date
+    # -------------------------------------------------------------------------
+
+    def describe_date(dom, mon, dow)
+      if dom == "*" && dow == "*"
+        mon == "*" ? "every day" : "every #{month_name(mon)}"
+      elsif dom != "*" && dow == "*"
+        suffix = mon == "*" ? "monthly" : "every #{month_name(mon)}"
+        "#{suffix} on the #{ordinal(dom.to_i)}"
+      else
+        # dow is specified (dom may also be set — cron ORs them, but dow wins here)
+        "every #{describe_dow(dow)}"
+      end
+    end
+
+    def describe_dow(dow)
+      case dow
+      when /^\d+$/
+        DAYS[dow.to_i % 7]
+      when /^(\d+)-(\d+)$/
+        a = Regexp.last_match(1).to_i % 7
+        b = Regexp.last_match(2).to_i % 7
+        return "weekday"   if a == 1 && b == 5
+        return "day"       if (a == 0 && b == 6) || (a == 0 && b == 7 % 7)
+
+        "#{DAYS[a]}\u2013#{DAYS[b]}"
+      when /^\d+(,\d+)+$/
+        days = dow.split(",").map { |d| d.to_i % 7 }
+        # Fugit normalises "1-5" (weekday range) to "1,2,3,4,5" — detect that.
+        return "weekday" if days == [1, 2, 3, 4, 5]
+
+        days.map { |d| DAYS[d] }.join(", ")
+      else
+        dow
+      end
+    end
+
+    def month_name(mon)
+      return mon unless mon.match?(/^\d+$/)
+
+      MONTHS[mon.to_i] || mon
+    end
+
+    def ordinal(n)
+      suffix =
+        case n % 100
+        when 11, 12, 13 then "th"
+        else
+          case n % 10
+          when 1 then "st"
+          when 2 then "nd"
+          when 3 then "rd"
+          else "th"
+          end
+        end
+      "#{n}#{suffix}"
+    end
+  end
+end

data/lib/aias/crontab_manager.rb

@@ -0,0 +1,140 @@
+# frozen_string_literal: true
+
+require "fileutils"
+require "open3"
+
+module Aias
+  class CrontabManager
+    include BlockParser
+    IDENTIFIER = "aias"
+
+    BLOCK_OPEN  = "# BEGIN aias"
+    BLOCK_CLOSE = "# END aias"
+
+    # Parses cron lines generated by JobBuilder.
+    # Current format (flags before prompt_id, single redirect):
+    #   <cron> <shell> -c 'source <env.sh> && <aia> [--prompts-dir <dir>] [--config <cfg>] <prompt_id> > <log> 2>&1'
+    # Legacy formats (with -l, inline env vars, flags after prompt_id, >>) are also
+    # matched for backward compatibility when reading older installed entries.
+    ENTRY_RE = /^(?<cron>[^\/\n]+)\s+\/\S+\s+(?:-l\s+)?-c\s+['"](?:source\s+\S+\s+&&\s+)?(?:\w+=\S+\s+)*(?:[^\s'"]*\/)?aia\s+(?:--prompts-dir\s+\S+\s+)?(?:--config(?:-file)?\s+\S+\s+)?(?<prompt_id>(?!--)\S+)(?:\s+--prompts-dir\s+\S+)?(?:\s+--config(?:-file)?\s+\S+)?\s+>>?\s+(?<log>\S+)\s+2>&1/
+
+    def initialize(crontab_command: "crontab", log_base: Paths::SCHEDULE_LOG)
+      @crontab_command = crontab_command
+      @log_base        = log_base
+    end
+
+    # Installs the given cron lines into the user's crontab, replacing any
+    # previously installed aias block. Creates the log base directory first.
+    # Raises Aias::Error if the crontab write fails.
+    def install(cron_lines)
+      FileUtils.mkdir_p(@log_base, mode: 0o700)
+      updated = replace_block(read_crontab, Array(cron_lines))
+      write_crontab(updated)
+    end
+
+    # Removes the aias-managed block from the crontab.
+    # Non-aias entries are not touched.
+    def clear
+      write_crontab(remove_block(read_crontab))
+    end
+
+    # Returns the cron lines as they would be written, without touching the
+    # crontab. Useful for `aias dry-run`.
+    def dry_run(cron_lines)
+      Array(cron_lines).join("\n")
+    end
+
+    # Returns the raw text of the aias-managed block currently in the crontab
+    # (markers excluded). Returns an empty string when no block exists.
+    def current_block
+      extract_block(read_crontab, BLOCK_OPEN, BLOCK_CLOSE)
+    end
+
+    # Returns an Array of Hashes describing each installed aias cron job.
+    # Each hash has :prompt_id, :cron_expr, and :log_path keys.
+    def installed_jobs
+      current_block.each_line.filter_map do |line|
+        line = line.strip
+        next if line.empty? || line.start_with?("#")
+
+        match = ENTRY_RE.match(line)
+        next unless match
+
+        {
+          prompt_id: match[:prompt_id],
+          cron_expr: match[:cron].strip,
+          log_path:  match[:log]
+        }
+      end
+    end
+
+    # Inserts or replaces a single cron job in the aias block (upsert).
+    # Any existing entry whose prompt_id matches is removed first, then the
+    # new line is appended. All other managed entries are left untouched.
+    # Raises Aias::Error if the crontab write fails.
+    def add_job(cron_line, prompt_id)
+      FileUtils.mkdir_p(@log_base, mode: 0o700)
+      current  = read_crontab
+      existing = extract_block(current, BLOCK_OPEN, BLOCK_CLOSE).each_line.map(&:chomp).reject(&:empty?)
+      updated  = existing.reject { |l| ENTRY_RE.match(l)&.[](:prompt_id) == prompt_id }
+      updated << cron_line
+      write_crontab(replace_block(current, updated))
+    end
+
+    # Removes a single cron job from the aias block by prompt_id.
+    # All other managed entries are left untouched.
+    # Raises Aias::Error if the prompt_id is not currently installed or
+    # if the crontab write fails.
+    def remove_job(prompt_id)
+      current  = read_crontab
+      existing = extract_block(current, BLOCK_OPEN, BLOCK_CLOSE).each_line.map(&:chomp).reject(&:empty?)
+      updated  = existing.reject { |l| ENTRY_RE.match(l)&.[](:prompt_id) == prompt_id }
+      raise Aias::Error, "'#{prompt_id}' is not currently installed" if updated.size == existing.size
+
+      write_crontab(replace_block(current, updated))
+    end
+
+    # Creates subdirectory structure under @log_base for each prompt_id.
+    # Called by CLI before install to ensure log dirs exist.
+    def ensure_log_directories(prompt_ids)
+      prompt_ids.each do |id|
+        FileUtils.mkdir_p(File.dirname(File.join(@log_base, "#{id}.log")), mode: 0o700)
+      end
+    end
+
+    private
+
+    # Reads the current crontab. Returns '' when no crontab exists.
+    # Raises Aias::Error for any other non-zero exit to prevent silently
+    # overwriting a crontab that could not be read.
+    def read_crontab
+      out, err, status = Open3.capture3(@crontab_command, "-l")
+      return out if status.success?
+      return "" if err.include?("no crontab for")
+      raise Aias::Error, "crontab -l failed: #{err.strip}"
+    end
+
+    # Writes content to the crontab via stdin.
+    # Raises Aias::Error if the crontab command exits non-zero.
+    def write_crontab(content)
+      Open3.popen2(@crontab_command, "-") do |stdin, _stdout, thr|
+        stdin.write(content)
+        stdin.close
+        raise Aias::Error, "failed to write crontab" unless thr.value.success?
+      end
+    end
+
+    # Removes the aias jobs block from content, leaving other lines intact.
+    def remove_block(content)
+      strip_block(content, BLOCK_OPEN, BLOCK_CLOSE)
+    end
+
+    # Removes any existing aias block then appends a fresh one.
+    def replace_block(content, cron_lines)
+      cleaned   = remove_block(content)
+      new_block = ([BLOCK_OPEN] + cron_lines + [BLOCK_CLOSE]).join("\n") + "\n"
+      cleaned.empty? ? new_block : cleaned.rstrip + "\n\n" + new_block
+    end
+
+  end
+end

data/lib/aias/env_file.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+require "fileutils"
+
+module Aias
+  # Manages a shell env file (~/.config/aia/schedule/env.sh) using a
+  # BEGIN/END block so user content above or below the block is preserved.
+  #
+  # The file is sourced by every cron entry before the aia command, giving
+  # scheduled jobs a controlled PATH and all necessary env vars (API keys,
+  # AIA_PROMPTS__DIR, etc.) without relying on crontab env vars or a login
+  # shell that would reset PATH via path_helper.
+  class EnvFile
+    include BlockParser
+    BLOCK_OPEN  = "# BEGIN aias-env"
+    BLOCK_CLOSE = "# END aias-env"
+
+    def initialize(path: Paths::SCHEDULE_ENV)
+      @path = path
+    end
+
+    # Writes env_vars into the managed block (merge — new values win on conflict).
+    # env_vars is a Hash of { "KEY" => "value" }.
+    # Chmod 0600 is applied by write so API keys are never world-readable.
+    def install(env_vars)
+      FileUtils.mkdir_p(File.dirname(@path), mode: 0o700)
+      merged = parse_block(current_block).merge(env_vars)
+      lines  = merged.map { |k, v| "export #{k}=\"#{v}\"" }
+      write(replace_block(read, lines))
+    end
+
+    # Removes the managed block from the file.
+    # Deletes the file entirely when no other content remains.
+    def uninstall
+      content = strip_block(read, BLOCK_OPEN, BLOCK_CLOSE)
+      if content.strip.empty?
+        File.delete(@path) if File.exist?(@path)
+      else
+        write(content)
+      end
+    end
+
+    # Returns the raw content of the managed block (markers excluded).
+    # Returns an empty string when no block exists.
+    def current_block
+      extract_block(read, BLOCK_OPEN, BLOCK_CLOSE)
+    end
+
+    private
+
+    def read
+      File.exist?(@path) ? File.read(@path) : ""
+    end
+
+    def write(content)
+      File.write(@path, content)
+      FileUtils.chmod(0o600, @path)
+    end
+
+    def replace_block(content, export_lines)
+      cleaned   = strip_block(content, BLOCK_OPEN, BLOCK_CLOSE)
+      new_block = ([BLOCK_OPEN] + export_lines + [BLOCK_CLOSE]).join("\n") + "\n"
+      cleaned.empty? ? new_block : new_block + "\n" + cleaned.lstrip
+    end
+
+    # Parses `export KEY="value"` lines into { "KEY" => "value" }.
+    def parse_block(block_content)
+      block_content.each_line.each_with_object({}) do |line, h|
+        if (m = line.chomp.match(/\Aexport\s+(\w+)="(.*)"\z/))
+          h[m[1]] = m[2]
+        end
+      end
+    end
+  end
+end

data/lib/aias/job_builder.rb

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+module Aias
+  class JobBuilder
+    def initialize(shell: ENV.fetch("SHELL", "/bin/bash"), aia_path: nil, env_file: nil, config_file: nil)
+      @shell       = shell
+      @aia_path    = aia_path || 'aia'
+      @env_file    = env_file || Paths::SCHEDULE_ENV
+      @config_file = config_file
+    end
+
+    # Returns a single cron line string for the given scanner result, e.g.:
+    #   0 8 * * * /bin/bash -c 'source ~/.config/aia/schedule/env.sh && /path/to/aia --prompts-dir /path --config ~/.config/aia/schedule/aia.yml daily_digest > ~/.config/aia/schedule/logs/daily_digest.log 2>&1'
+    #
+    # env.sh is sourced first to set PATH, API keys, etc. All flags come before
+    # the prompt ID. config_file selects the schedule-specific AIA config.
+    # prompts_dir sets the directory AIA searches for the prompt file.
+    def build(scanner_result, prompts_dir: nil)
+      cron_expr    = resolved_cron(scanner_result.schedule)
+      prompt_id    = scanner_result.prompt_id
+      log          = log_path_for(prompt_id)
+      prompts_flag = prompts_dir ? %( --prompts-dir "#{File.expand_path(prompts_dir)}") : ""
+      config_flag  = @config_file ? %( --config "#{@config_file}") : ""
+      cmd          = %(source "#{@env_file}" && #{@aia_path}#{prompts_flag}#{config_flag} #{prompt_id} > "#{log}" 2>&1)
+      "#{cron_expr} #{shell_binary} -c '#{cmd}'"
+    end
+
+    # Returns the log file path for a given prompt_id.
+    # Mirrors the subdirectory structure of the prompt_id.
+    # e.g. "reports/weekly" → "~/.config/aia/schedule/logs/reports/weekly.log"
+    def log_path_for(prompt_id)
+      File.join(Paths::SCHEDULE_LOG, "#{prompt_id}.log")
+    end
+
+    private
+
+    # Resolves the schedule string to a canonical 5-field cron expression
+    # via fugit. Accepts both raw cron expressions and natural language.
+    # Raises Aias::Error if the schedule cannot be resolved — this should
+    # not happen in practice since Validator rejects invalid schedules first.
+    def resolved_cron(schedule)
+      cron = Fugit.parse_cronish(schedule)
+      raise Aias::Error, "Cannot resolve schedule '#{schedule}' to a cron expression" unless cron
+
+      cron.to_cron_s
+    end
+
+    # Returns the shell binary path. Falls back to /bin/bash if SHELL is unset.
+    def shell_binary
+      return "/bin/bash" if @shell.nil? || @shell.strip.empty?
+
+      @shell.strip
+    end
+
+  end
+end

data/lib/aias/paths.rb

@@ -0,0 +1,14 @@
+# frozen_string_literal: true
+
+module Aias
+  # Single source of truth for all filesystem paths used by aias.
+  # Every class that needs a path should reference Aias::Paths rather than
+  # defining its own constant.
+  module Paths
+    AIA_CONFIG   = File.expand_path("~/.config/aia/aia.yml")
+    SCHEDULE_DIR = File.expand_path("~/.config/aia/schedule")
+    SCHEDULE_CFG = File.expand_path("~/.config/aia/schedule/aia.yml")
+    SCHEDULE_LOG = File.expand_path("~/.config/aia/schedule/logs")
+    SCHEDULE_ENV = File.expand_path("~/.config/aia/schedule/env.sh")
+  end
+end

data/lib/aias/prompt_scanner.rb

@@ -0,0 +1,111 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Aias
+  class PromptScanner
+    # Immutable value object representing one discovered scheduled prompt.
+    Result = Data.define(:prompt_id, :schedule, :metadata, :file_path)
+
+    PROMPTS_DIR_ENVVAR_NEW = "AIA_PROMPTS__DIR"
+    PROMPTS_DIR_ENVVAR_OLD = "AIA_PROMPTS_DIR"
+
+    def initialize(prompts_dir: nil)
+      @prompts_dir = (prompts_dir || ENV[PROMPTS_DIR_ENVVAR_NEW] || ENV[PROMPTS_DIR_ENVVAR_OLD]).to_s
+    end
+
+    # Returns Array<Result> of all prompts with a non-empty schedule: key.
+    # Raises Aias::Error if the prompts directory is missing or unreadable.
+    def scan
+      validate_prompts_dir!
+      candidate_files.filter_map { |path| build_result(path) }
+    end
+
+    # Parses a single prompt file by path (relative or absolute).
+    # Derives the prompt_id using the configured prompts_dir.
+    # Raises Aias::Error when the file is missing/unreadable, lies outside
+    # the prompts directory, or carries no schedule: in its frontmatter.
+    def scan_one(path)
+      absolute = File.expand_path(path)
+
+      raise Aias::Error, "Prompt file not found: #{absolute}"    unless File.exist?(absolute)
+      raise Aias::Error, "Prompt file not readable: #{absolute}" unless File.readable?(absolute)
+
+      validate_prompts_dir!
+
+      base = @prompts_dir.chomp("/")
+      unless absolute.start_with?("#{base}/")
+        raise Aias::Error, "'#{absolute}' is not inside the prompts directory '#{@prompts_dir}'"
+      end
+
+      parsed, schedule = begin
+        p = PM.parse(absolute)
+        [p, p.metadata&.schedule]
+      rescue => e
+        raise Aias::Error, "Failed to parse '#{prompt_id_for(absolute)}': #{e.message}"
+      end
+
+      if schedule.nil? || schedule.to_s.strip.empty?
+        raise Aias::Error, "'#{prompt_id_for(absolute)}' has no schedule: in its frontmatter"
+      end
+
+      Result.new(
+        prompt_id: prompt_id_for(absolute),
+        schedule:  schedule.to_s.strip,
+        metadata:  parsed.metadata,
+        file_path: absolute
+      )
+    end
+
+    private
+
+    def validate_prompts_dir!
+      if @prompts_dir.empty?
+        raise Aias::Error, "#{PROMPTS_DIR_ENVVAR_NEW} (or #{PROMPTS_DIR_ENVVAR_OLD}) is not set"
+      end
+      unless File.directory?(@prompts_dir)
+        raise Aias::Error, "AIA_PROMPTS_DIR '#{@prompts_dir}' does not exist"
+      end
+      unless File.readable?(@prompts_dir)
+        raise Aias::Error, "AIA_PROMPTS_DIR '#{@prompts_dir}' is not readable"
+      end
+    end
+
+    # Runs grep via Open3 to avoid shell injection.
+    # --include=*.md limits matches to prompt files; -m 1 stops after the first
+    # match per file (presence is all we need). Returns [] when nothing matches.
+    def candidate_files
+      out, _err, _status = Open3.capture3(
+        "grep", "-rl", "--include=*.md", "-m", "1", "schedule:", @prompts_dir
+      )
+      out.lines.map(&:chomp).reject(&:empty?)
+    end
+
+    # Strips the prompts_dir prefix and .md suffix to produce a prompt ID.
+    # e.g. "/home/user/.prompts/reports/weekly.md" → "reports/weekly"
+    def prompt_id_for(absolute_path)
+      base = @prompts_dir.chomp("/")
+      relative = absolute_path.delete_prefix("#{base}/")
+      relative.delete_suffix(".md")
+    end
+
+    # Parses the file via PM and returns a Result if schedule: is present.
+    # Returns nil (filter_map drops it) if schedule is absent or empty.
+    # Warns to stderr and returns nil if PM.parse raises.
+    def build_result(absolute_path)
+      parsed   = PM.parse(absolute_path)
+      schedule = parsed.metadata.schedule
+      return nil if schedule.nil? || schedule.to_s.strip.empty?
+
+      Result.new(
+        prompt_id: prompt_id_for(absolute_path),
+        schedule:  schedule.to_s.strip,
+        metadata:  parsed.metadata,
+        file_path: absolute_path
+      )
+    rescue => e
+      warn "aias: skipping #{absolute_path}: #{e.message}"
+      nil
+    end
+  end
+end

data/lib/aias/schedule_config.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Aias
+  # Manages ~/.config/aia/schedule/aia.yml — the AIA config file used by all
+  # scheduled cron jobs. Provides targeted updates without clobbering user
+  # settings already in the file.
+  class ScheduleConfig
+    def initialize(path: Paths::SCHEDULE_CFG)
+      @path = path
+    end
+
+    # Sets prompts.dir in the config file to +dir+ if it is not already that value.
+    # Returns true when the file was updated, false when already correct or file absent.
+    # Raises Aias::Error on YAML parse failure or write error.
+    def set_prompts_dir(dir)
+      return false unless File.exist?(@path)
+
+      config = YAML.safe_load_file(@path) || {}
+      return false if config.dig("prompts", "dir") == dir
+
+      config["prompts"]        ||= {}
+      config["prompts"]["dir"]   = dir
+      File.write(@path, config.to_yaml)
+      true
+    rescue Psych::Exception => e
+      raise Aias::Error, "could not update prompts.dir in #{@path}: #{e.message}"
+    end
+  end
+end

data/lib/aias/validator.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Aias
+  class Validator
+    # Immutable value object returned by #validate.
+    ValidationResult = Data.define(:valid?, :errors)
+
+    # Common locations where version managers install binary shims.
+    # Checked as a fallback when the login shell cannot find the binary.
+    BINARY_FALLBACK_DIRS = [
+      File.expand_path("~/.rbenv/shims"),
+      File.expand_path("~/.rbenv/bin"),
+      File.expand_path("~/.rvm/bin"),
+      File.expand_path("~/.asdf/shims"),
+      "/usr/local/bin",
+      "/usr/bin",
+      "/opt/homebrew/bin"
+    ].freeze
+
+    def initialize(
+      shell: ENV.fetch("SHELL", "/bin/bash"),
+      binary_to_check: "aia",
+      fallback_dirs: BINARY_FALLBACK_DIRS
+    )
+      @shell = shell
+      @binary_to_check = binary_to_check
+      @fallback_dirs = fallback_dirs
+    end
+
+    # Returns a ValidationResult for the given PromptScanner::Result.
+    def validate(scanner_result)
+      errors = []
+      errors.concat(check_schedule_syntax(scanner_result.schedule))
+      errors.concat(check_parameters(scanner_result.metadata))
+      errors.concat(aia_binary_errors)
+      ValidationResult.new(valid?: errors.empty?, errors: errors)
+    end
+
+    private
+
+    # Validates the schedule string using fugit, which accepts both raw cron
+    # expressions and natural language ("every weekday at 8am").
+    def check_schedule_syntax(schedule)
+      Fugit.parse_cronish(schedule) ? [] : ["Schedule '#{schedule}': not a valid cron expression or natural language schedule"]
+    end
+
+    # Validates that all parameter keys have non-nil, non-empty default values.
+    # Scheduled prompts run unattended — interactive input is impossible.
+    def check_parameters(metadata)
+      params = metadata.parameters
+      return [] if params.nil?
+
+      errors = []
+      params.each do |key, value|
+        if value.nil? || value.to_s.strip.empty?
+          errors << "Parameter '#{key}' has no default value (required for unattended cron execution)"
+        end
+      end
+      errors
+    end
+
+    # Checks that `aia` is locatable in the login-shell PATH or in a known
+    # version-manager shim directory. Results are cached per Validator instance
+    # (shell spawn is expensive).
+    #
+    # Two-tier check:
+    #   1. Spawn a login shell and run `which <binary>` — covers the normal case
+    #      where the shell profile properly initialises the version manager.
+    #   2. If that fails, scan fallback_dirs for an executable file with the
+    #      binary name — covers setups where rbenv/rvm/asdf shims are installed
+    #      but the login shell profile does not initialise the version manager.
+    def aia_binary_errors
+      return @aia_binary_errors if defined?(@aia_binary_errors)
+
+      shell_found = begin
+        _out, _err, status = Open3.capture3(@shell, "-l", "-c", "which #{@binary_to_check}")
+        status.success?
+      rescue Errno::ENOENT
+        false
+      end
+
+      @aia_binary_errors =
+        if shell_found || binary_in_fallback_location?
+          []
+        else
+          ["#{@binary_to_check} binary not found in #{@shell} login shell PATH or known version manager directories"]
+        end
+    end
+
+    # Returns true when an executable named @binary_to_check exists in any of
+    # the @fallback_dirs entries.
+    def binary_in_fallback_location?
+      @fallback_dirs.any? do |dir|
+        path = File.join(dir, @binary_to_check)
+        File.executable?(path)
+      end
+    end
+  end
+end

data/lib/aias/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Aias
+  VERSION = "0.1.0"
+end