ric 0.14.6 → 0.15.0

data/bin/septober

@@ -1,384 +1,650 @@
-#!/usr/bin/env ruby 
-
-=begin
-  ############################################################
-  @author:    Riccardo Carlesso
-  @email:     riccardo.carlesso@gmail.com
-  @url:       http://github.com/palladius/septober
-  @script:    septober
-  @maturity:  development
-  @language:  Ruby
-	@tags:      development, rcarlesso
-  @synopsis:  This connects to septober websites. For more info, look here
-  @description:
-    septober.heroku.com client to add and list todos!
-   
-    TODO
-    - add --context|-x : to change context (--local => --context 'local' , default: "septober" )
-   
-    API: add actions (done, toggle, ..., due <today|tomorrow|monday> )
-  ###########################################################
-=end
-
-$PROG_VER = '1.0.2'
-=begin
-  @history:
-    1.0.1 2022-01-06 Fixing bug 
-    1.0.0 ????
-    0.9.8 2011-02-10 Added timeout (works) and a broken prototype for :edit
-    0.9.7 2011-02-09 mini banner WITH version (not to get nuts again thru versions!). --conf now works!
-    0.9.6 2011-02-09 CLI supports --conf now. Tags working!
-    0.9.5 2011-02-08 more concise 'add'
-    0.9.4 2011-02-04 added 'done' action (and 'delete' ?)    
-    0.9.3 2011-02-04 better 'list'    
-    0.9.2 2011-02-04 'add' operation succefully added!   
-    0.9.1 2011-01-18 First version
-=end
-  
-
-  require 'optparse'       
-  require 'rubygems'
-  require 'ric'
-  #require 'active_resource'    # not needed anymore, after ric gem v0.12.0
-  require 'active_resource'    # restored since i can then debug without installing the gem
-  require 'socket'
-  gem 'psych', '=4.0.3'
-  require 'psych' 
-  
-  include RubyClasses::Array 
-  
-  $DEBUG    = false
-  
-  $opts = {
-    :app_name            => 'septober client',
-    :hello               => 'Welcome to this terrific application',
-    :septober_url        => 'http://septober.heroku.com/' , 
-    :dflt_config_file    => '~/.septober.yml' , 
-    :local               => false ,
-    :timeout             => 15 ,
-    :subconf             => nil , # if nil it goes to septober/septober_local
-  }
-  
-  def init
-    $opts[:config_file] = $opts[:dflt_config_file]
-    $optparse = OptionParser.new do |opts|
-      opts.on( '-c', '--config <FILE>', 'uses a different configfile from: '+$opts[:dflt_config_file] ) {|arg_file|  
-        puts "Importing file different from default: #{yellow arg_file}"
-        $opts[:config_file] = arg_file
-      }
-      opts.on( '-d', '--debug',     'enables debug (DFLT=false)' )  {  $opts[:debug] = true ; $debug = true ; debug_on('Debug enabled from ARGV')}
-      opts.on( '-h', '--help',      'Display this screen' )          {  puts(opts); exit 1 }
-      opts.on( '-n', '--no-colors', 'Deactives colors (onta e disonore!)' ) { $colors_active = false }
-      opts.on( '-l', '--local',     'uses "septober_local" instead of septober in YAML' )    {  $opts[:local] = true }
-      opts.on( '-s', '--subconf SUBCONF',   'uses different subconf in YAML file (dflt: "septober"/"local")') {|subconf|
-        $opts[:subconf] = subconf 
-      }
-      opts.on( '-t', '--timeout TIMEOUT',   "Sets timeout (default =#{$opts[:timeout]}s)" ) {|new_timeout| 
-        $opts[:timeout] = new_timeout.to_i rescue 5
-        RemoteTodo.timeout = new_timeout.to_i rescue 5
-      }
-      opts.on( '-v', '--verbose',   'Output more information' )   { $opts[:verbose] = true}
-
-      opts.banner = <<-API_OPTIONS
-#{$0} v.#{$PROG_VER}
-Usage: #{File.basename $0} [options] [add|list|done|del] [args]
-
-  API Actions (T stands for ToBeDoneYet ):
-    add <FREE TEXT>            # adds new task in free text with some magic..
-    delete <ID>                # T delete ticket.ID (DONT USE IF U CAN!)
-    done <ID>                  # T posts ticket.ID :done (resolved)
-    edit <ID> [ACTION1:ARG1] [ACT2:ARG2]# T posts generic action for ticket.ID /edit.xml?due=tomorrow&ACT2=ARG2
-    list                       # shows a list of your todos yet to complete
-    mail <ID>                  # T mail to yourself ticket.ID !!!
-    show <ID>                  # shows details about todo with id=ID
-    procrastinate <ID> <NDAYS> # T mail to yourself ticket.ID !!!
-    sleep <ID> <NDAYS>         # T mail to yourself ticket.ID !!!
-    
-  Examples:
-    septober --local edit 110 due:tomorrow
-    septober list
-    septober show 1
-    septober add 'This is a ticket with priority 4 and a simple @example tag!'
-    
-  Options:    
-      API_OPTIONS
-    end
-    $optparse.parse! 
-    RemoteTodo.import_config()
-  end
-  
-  #################################################################################################################################################
-  class RemoteTodo < ActiveResource::Base
-    # With a singleton u can define the accessors of the class (attr accessor for self!)
-    #class << self
-    #  attr_accessor :description  # = '-'
-    #end
-    self.site         = "http://septober.example.com/" # uninitialized
-    self.element_name = 'todo'
-    self.timeout      = $opts[:timeout] rescue 6
-    #self.priority     = 3 # default
-    
-    @@sample_yml_config = <<-SAMPLE_YML_CONFIG 
-local: &DEVEL_LOCAL
-  # YAML file with septober configuration. For more info: http://septober.heroku.com/
-  site: "http://localhost:3000/api/"   # or http://septober.heroku.com/api/
-  user: guest
-  password: guest
-  description: My Rails 3 development (guest//guest shuld work for real This is NOT a random thing)
-remote:
-  site: http://your_server.example.com/api/
-  user: USERNAME
-  pass: V3ry_D1ff1cul1
-  description: you can use your own server. this is open source. Just remember to say Riccardo you think hes a genius. I dont want money, just fame.
-#########################################################################################################
-
-#########################################################################################################
-# YAML file with septober configuration. For more info: http://septober.heroku.com/
-# You just change here:
-#remote:
-#  <<: *RICCARDO_HEROKU
-#local:
-#  <<: *DEVEL_LOCAL       
-# IMPORTANT! It looks like psych gem doesnt expand these magic &HEROKU/*HEROKU so better remove them and simplify with dereferencing :/
-SAMPLE_YML_CONFIG
-      
-    # self.ssl_options = {:cert         => OpenSSL::X509::Certificate.new(File.open(pem_file))
-    #                        :key          => OpenSSL::PKey::RSA.new(File.open(pem_file)),
-    #                        :ca_path      => "/path/to/OpenSSL/formatted/CA_Certs",
-    #                        :verify_mode  => OpenSSL::SSL::VERIFY_PEER}
-    
-    def self.import_config(file=nil)
-      file ||= $opts[:config_file]
-      real_file = File.expand_path file
-      deb "Importing config from #{file}.."
-      if File.exists?(real_file)
-        #puts "TODO import from #{file} (local=#{$opts[:local]})"
-        whole_hash = YAML.load_file(real_file) # rescue { :error => $! }
-        
-        sub_conf = $opts[:subconf].nil? ? 
-          ($opts[:local] ? 'local' : 'remote' ) : 
-          $opts[:subconf]
-        if not whole_hash.keys.include?(sub_conf) 
-          puts "SubConf non existing: #{red(sub_conf.to_s)}. Available sub_confs: #{yellow whole_hash.keys.join(', ')}. Note that 'remote' is the default, 'local' comes from '-l 'and you can set anything with '-s whatevs' :)"
-          raise "SubConf not existing: #{(sub_conf)}"
-        end
-        puts "SubConf: #{yellow(sub_conf.to_s)}. Available sub_confs (you can enforce them with -s new as of 2022!): #{yellow whole_hash.keys.join(', ')}"
-        conf_hash = whole_hash[sub_conf] rescue nil
-        self.site = conf_hash['site']
-        self.user = conf_hash['user']
-        self.password = conf_hash['password']
-        self.description = conf_hash['description'] rescue '-'
-        deb "Conf imported successuflly: #{blue self.user}@#{self.site}"
-      else
-        pred "Missing file: #{file} !!! Try to do the following:"
-        puts "cat > #{file}\n#{@@sample_yml_config rescue "Err#{$!}" }"
-        exit 79
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+# If Ruby < 3.4 is first in PATH (e.g. system Ruby 3.3 on Linux), re-exec into rbenv Ruby 3.4.5+ if available
+if RUBY_VERSION < "3.4.0"
+  rbenv_ruby = File.expand_path("~/.rbenv/versions/3.4.5/bin/ruby")
+  exec(rbenv_ruby, $PROGRAM_NAME, *ARGV) if File.executable?(rbenv_ruby)
+end
+
+require "optparse"
+require "net/http"
+require "uri"
+require "json"
+require "yaml"
+require "socket"
+require "base64"
+require "date"
+require "time"
+
+PROG_VER = "2.6.1"
+
+# Optional ric gem support; built-in ANSI fallback so CLI is 100% zero-dependency on Ruby 3.4.5+
+$colors_active = $stdout.tty?
+def colorize(code, str)
+  return str.to_s unless $colors_active
+  "\e[#{code}m#{str}\e[0m"
+end
+def red(s)    = colorize(31, s)
+def green(s)  = colorize(32, s)
+def yellow(s) = colorize(33, s)
+def blue(s)   = colorize(34, s)
+def purple(s) = colorize(35, s)
+def cyan(s)   = colorize(36, s)
+def gray(s)   = colorize(90, s)
+def bold(s)   = colorize(1, s)
+
+CONFIG_PATH       = File.expand_path("~/.septober.yml")
+LOCAL_CONFIG_PATH = File.expand_path("~/.septober.local.yml")
+
+AGENT_ICONS = {
+  "ermete"   => "🚛",
+  "lobby"    => "🦞",
+  "pux"      => "🐾",
+  "freevola" => "🧚‍♀️",
+  "derek"    => "🖥️"
+}.freeze
+
+AGENT_ENV_FILES = {
+  "lobby"    => "~/.openclaw/.env",
+  "ermete"   => "~/.hermes/.env",
+  "pux"      => "~/.openclaw/.env",
+  "freevola" => "~/.hermes-freevola/.env"
+}.freeze
+
+def parse_dotenv_file(path)
+  res = {}
+  expanded = File.expand_path(path.to_s)
+  return res unless File.file?(expanded)
+
+  File.readlines(expanded, chomp: true).each do |line|
+    stripped = line.strip
+    next if stripped.empty? || stripped.start_with?("#")
+    next unless stripped.include?("=")
+
+    k, v = stripped.split("=", 2)
+    res[k.strip] = v.strip.gsub(/\A['"]|['"]\z/, "")
+  end
+  res
+rescue StandardError
+  res
+end
+
+def load_config(conf_path: nil, target_env: nil, target_agent: nil, cli_user: nil, cli_password: nil)
+  resolved_path = conf_path
+  if resolved_path.nil? || resolved_path.empty?
+    candidates = [
+      ENV["SEPTOBER_CONFIG"],
+      LOCAL_CONFIG_PATH,
+      CONFIG_PATH,
+      File.expand_path("~/git/gic/.septober.yml"),
+      File.expand_path("~/git/gic25/.septober.yml"),
+      File.expand_path("../.septober.yml", __dir__)
+    ].compact
+    resolved_path = candidates.find { |p| File.file?(p) }
+  else
+    resolved_path = File.expand_path(resolved_path)
+  end
+
+  unless resolved_path && File.file?(resolved_path)
+    warn red("Error: Config file not found (checked #{LOCAL_CONFIG_PATH}, #{CONFIG_PATH})")
+    exit 1
+  end
+
+  begin
+    raw_yaml = File.read(resolved_path)
+    data = YAML.safe_load(raw_yaml, aliases: true, permitted_classes: [Symbol, Date, Time]) || {}
+  rescue StandardError => e
+    warn red("Error reading YAML config #{resolved_path}: #{e.message}")
+    exit 1
+  end
+
+  env_name = target_env || ENV["SEPTOBER_ENV"]
+  if env_name.nil? || env_name.empty?
+    %w[septober production remote local septober_local].each do |cand|
+      if data[cand].is_a?(Hash)
+        env_name = cand
+        break
       end
     end
-    
-    def to_s
-      "RemoteTodo('#{self.name}', P#{priority ? priority : '?'})"
-    end
-    
-    def self.description
-      @@description ||= '-'
+  end
+
+  if (env_name.nil? || !data[env_name].is_a?(Hash)) && target_env == "local" && data["septober_local"].is_a?(Hash)
+    env_name = "septober_local"
+  end
+
+  if env_name.nil? || !data[env_name].is_a?(Hash)
+    pair = data.find { |_k, v| v.is_a?(Hash) && (v["site"] || v[:site]) }
+    env_name = pair[0] if pair
+  end
+
+  unless env_name && data[env_name].is_a?(Hash)
+    warn red("Error: Could not find valid environment '#{target_env || 'septober'}' in #{resolved_path}")
+    warn "Available environments: #{data.keys.join(', ')}"
+    exit 1
+  end
+
+  cfg = data[env_name]
+  site = ENV["SEPTOBER_SITE"] || cfg["site"] || cfg[:site] || "http://localhost:8080/api/"
+  site = "#{site.to_s.sub(%r{/+\z}, '')}/"
+  user = cli_user || ENV["SEPTOBER_USER"] || cfg["user"] || cfg[:user] || "guest"
+  password = cli_password || ENV["SEPTOBER_PASSWORD"] || (cfg["password"] || cfg[:password] || "guest").to_s
+  agent_icon = nil
+
+  # Resolve agent profile
+  agent_name = target_agent || ENV["SEPTOBER_AGENT"]
+  if (agent_name.nil? || agent_name.empty?) && ENV["SEPTOBER_USER"].nil? && cli_user.nil?
+    if ENV["HARNESS_NAME"] == "Hermes" || ENV["HARNESS_NICKNAME"] == "Ermete Bottazzi"
+      agent_name = "ermete"
+    elsif ENV["HARNESS_NAME"] == "Lobby" || ENV["HARNESS_NICKNAME"] == "Lobby"
+      agent_name = "lobby"
+    elsif ENV["OPENCLAW_AGENT"] && !ENV["OPENCLAW_AGENT"].empty?
+      agent_name = ENV["OPENCLAW_AGENT"]
+    elsif Dir.pwd.include?(".openclaw")
+      agent_name = "lobby"
+    elsif Dir.pwd.include?(".hermes")
+      agent_name = "ermete"
     end
-    
-    def self.description=(desc)
-      @@description = desc
+  end
+
+  if agent_name && !agent_name.empty?
+    agent_icon = AGENT_ICONS[agent_name]
+    yaml_agents = data["agents"].is_a?(Hash) ? data["agents"][agent_name] : nil
+    env_file = AGENT_ENV_FILES[agent_name] ? File.expand_path(AGENT_ENV_FILES[agent_name]) : nil
+
+    agent_user = nil
+    agent_pass = nil
+
+    if ENV["SEPTOBER_AGENT"] == agent_name && ENV["SEPTOBER_USER"] && ENV["SEPTOBER_PASSWORD"]
+      agent_user = ENV["SEPTOBER_USER"]
+      agent_pass = ENV["SEPTOBER_PASSWORD"]
+    elsif env_file && File.file?(env_file)
+      dotenv = parse_dotenv_file(env_file)
+      agent_user = dotenv["SEPTOBER_USER"]
+      agent_pass = dotenv["SEPTOBER_PASSWORD"]
+    elsif yaml_agents.is_a?(Hash)
+      agent_user = yaml_agents["user"] || yaml_agents[:user]
+      agent_pass = (yaml_agents["password"] || yaml_agents[:password]).to_s
+      agent_icon ||= yaml_agents["icon"] || yaml_agents[:icon]
     end
 
-    attr_accessor :priority
-    
-    def colored_project_name()
-      colora(project.color || :grey ,project.name)
+    if agent_user && agent_pass && !agent_user.empty? && !agent_pass.empty?
+      user = agent_user
+      password = agent_pass
+    else
+      hint_file = env_file || "~/.#{agent_name}/.env"
+      warn "\n❌ Error: ENV credentials missing for agent '#{agent_name}'!"
+      warn "   Configure SEPTOBER_USER, SEPTOBER_PASSWORD, SEPTOBER_AGENT in #{hint_file} or environment."
+      exit 1
     end
-    
-    # TODO put this into todo.rb model and add it to the controller like "cli_colored_string" and "cli_neutral_string"
-    def colored_due_explaination(override_explaination=nil)
-      mycolor = case due_explaination
-        when 'overdue' ; :red 
-        when 'close' ;   :yellow 
-        when 'far' ;     :green 
-        else ; :gray
-        #default ; :gray
-      end
-      return colora(mycolor, override_explaination || due_explaination)
+  end
+
+  {
+    "env"         => env_name,
+    "site"        => site,
+    "user"        => user,
+    "password"    => password,
+    "agent"       => agent_name,
+    "agent_icon"  => agent_icon,
+    "description" => cfg["description"] || "",
+    "config_path" => resolved_path
+  }
+end
+
+def make_request(cfg, endpoint, method: "GET", body: nil, timeout: 25)
+  base_uri = URI.join(cfg["site"], endpoint.to_s.sub(%r{\A/+}, ""))
+  http = Net::HTTP.new(base_uri.host, base_uri.port)
+  http.use_ssl = (base_uri.scheme == "https")
+  http.open_timeout = timeout
+  http.read_timeout = timeout
+
+  req_class = case method.to_s.upcase
+              when "GET"    then Net::HTTP::Get
+              when "POST"   then Net::HTTP::Post
+              when "PUT"    then Net::HTTP::Put
+              when "DELETE" then Net::HTTP::Delete
+              else raise "Unsupported HTTP method: #{method}"
+              end
+
+  req = req_class.new(base_uri.request_uri)
+  req.basic_auth(cfg["user"].to_s, cfg["password"].to_s)
+  req["Accept"] = "application/json"
+  req["User-Agent"] = "septober-cli/#{PROG_VER} (Ruby/#{RUBY_VERSION})"
+
+  if body
+    req["Content-Type"] = "application/json"
+    req.body = JSON.generate(body)
+  end
+
+  resp = http.request(req)
+  code = resp.code.to_i
+  raw_body = resp.body.to_s
+
+  if code >= 200 && code < 300
+    return { "status" => code, "data" => nil } if raw_body.strip.empty?
+    parsed = begin
+      JSON.parse(raw_body)
+    rescue StandardError
+      raw_body
     end
-    
-    def priority_str(priority)
-      case priority.to_s
-        when '1'; return '--'
-        when '2'; return '-'
-        when '3'; return ' '
-        when '4'; return '!'
-        when '5'; return '!!'
-      end
-      return "'?' #{priority}"
+    { "status" => code, "data" => parsed }
+  else
+    parsed_err = begin
+      JSON.parse(raw_body)
+    rescue StandardError
+      raw_body
     end
+    { "status" => code, "error" => parsed_err }
+  end
+rescue StandardError => e
+  { "status" => 0, "error" => e.message }
+end
+
+def format_priority(prio)
+  case prio.to_i
+  when 5 then "🔴 P0/Urgent"
+  when 4 then "🟠 P1/High"
+  when 3 then "🟡 P2/Med"
+  when 2 then "🟢 P3/Low"
+  when 1 then "⚪️ P4/Backlog"
+  else "P#{prio}"
+  end
+end
+
+def extract_todo_id(raw_arg)
+  str = raw_arg.to_s.strip
+  if str =~ %r{/todos/(\d+)}
+    Regexp.last_match(1).to_i
+  elsif str =~ /\A#?(\d+)\z/
+    Regexp.last_match(1).to_i
+  else
+    warn red("Error: Invalid Todo ID or URL '#{raw_arg}'. Expected an integer ID (e.g. 235) or URL (.../todos/235).")
+    exit 1
+  end
+end
+
+def local_hostname
+  Socket.gethostname.split(".").first
+rescue StandardError
+  "unknown-host"
+end
 
-    def show_entry(opts={})
-      mywhere = where ? azure( " @#{where}") : ''
-      mytags = (tag_list != [] ? 
-        ' '+tag_list.map{|tag| orange("@#{tag}")}.join(' ') : 
-        '' 
-      ) rescue ''
-      return sprintf "%-3d %-30s %2s %s %s%s",
-        id, colored_project_name , priority_str(priority), colored_due_explaination(due), name, mywhere+mytags
+def harness_co_author(agent_name = nil)
+  return ENV["CARLESSIAN_HARNESS_CO_AUTHOR"] if ENV["CARLESSIAN_HARNESS_CO_AUTHOR"]
+
+  env_file = AGENT_ENV_FILES[agent_name]
+  if env_file
+    dotenv = parse_dotenv_file(env_file)
+    return dotenv["CARLESSIAN_HARNESS_CO_AUTHOR"] if dotenv["CARLESSIAN_HARNESS_CO_AUTHOR"]
+  end
+
+  case agent_name
+  when "ermete"   then "Ermete Bottazzi <ermete.bottazzi@romagnatrucking.it>"
+  when "lobby"    then "Lobby <lobby@openclaw.local>"
+  when "pux"      then "Pux <pux@openclaw.local>"
+  when "freevola" then "Freevola <freevola@pupurabbux.local>"
+  end
+end
+
+def harness_nickname(agent_name = nil)
+  return ENV["HARNESS_NICKNAME"] if ENV["HARNESS_NICKNAME"]
+  return ENV["HARNESS_NAME"] if ENV["HARNESS_NAME"]
+
+  env_file = AGENT_ENV_FILES[agent_name]
+  if env_file
+    dotenv = parse_dotenv_file(env_file)
+    return dotenv["HARNESS_NICKNAME"] || dotenv["HARNESS_NAME"] if dotenv["HARNESS_NICKNAME"] || dotenv["HARNESS_NAME"]
+  end
+
+  case agent_name
+  when "ermete"   then "Ermete Bottazzi"
+  when "lobby"    then "Lobby"
+  when "pux"      then "Pux"
+  when "freevola" then "Freevola"
+  end
+end
+
+def format_agent_badge(todo)
+  u = todo["user"]
+  if u.is_a?(Hash) && u["is_agent"]
+    icon = u["agent_icon"]
+    uname = u["username"].to_s
+    agent_key = uname.include?(".") ? uname.split(".").last.downcase : uname.downcase
+    icon = AGENT_ICONS.fetch(agent_key, "🤖") if icon.nil? || icon.empty? || icon == "?"
+    short_name = agent_key.capitalize
+    return " [#{icon} #{short_name}]"
+  elsif todo["source"].to_s.include?("cli-26/")
+    s = todo["source"].to_s
+    agent_part = s.split("cli-26/", 2)[1].to_s.split("@").first.to_s
+    icon = agent_part.include?("Ermete") ? "🚛" : "🤖"
+    return " [#{icon} #{agent_part}]" unless agent_part.empty?
+  end
+  ""
+end
+
+def cmd_list(opts, cfg)
+  res = make_request(cfg, "todos.json", timeout: opts[:timeout])
+  if res["error"]
+    warn red("Error (#{res['status']}): #{res['error']}")
+    exit 1
+  end
+
+  todos = res["data"] || []
+  if opts[:json]
+    puts JSON.pretty_generate(todos)
+    return
+  end
+
+  puts "\n#{bold("🚛 Septober [#{cfg['env']}]")} (#{cyan(cfg['site'])}) - User: #{yellow(cfg['user'])} #{gray("[Ruby #{RUBY_VERSION}]")}"
+  puts "=" * 75
+
+  shown = 0
+  todos.each do |raw_t|
+    t = raw_t.is_a?(Hash) && raw_t["todo"].is_a?(Hash) ? raw_t["todo"] : raw_t
+    next unless t.is_a?(Hash)
+
+    active = t.key?("active") ? t["active"] : true
+    next if !opts[:all] && !active
+
+    tags = Array(t["tag_list"])
+    if opts[:tag]
+      wanted = opts[:tag].to_s.sub(/\A[@#]/, "").downcase
+      next unless tags.map { |x| x.to_s.downcase }.include?(wanted)
     end
-    
-    def tags_comma_separated_list
-      orange(tag_list.join(', '))
+
+    badge = format_agent_badge(t)
+    if opts[:filter_agent]
+      fa = opts[:filter_agent].to_s.downcase
+      uname = t.dig("user", "username").to_s.downcase
+      src = t["source"].to_s.downcase
+      next if !uname.include?(fa) && !src.include?(fa) && !badge.downcase.include?(fa)
     end
-    
-    def colored_name()
-      white(name)
+
+    tid   = t["id"]
+    name  = t["name"] || "Untitled"
+    prio  = format_priority(t["priority"] || 3)
+    due   = t["due"] || "No date"
+    where = t["where"]
+    url   = t["url"]
+    desc  = t["description"].to_s.strip
+    state_icon = active ? "⏳" : "✅"
+
+    puts "#{state_icon} [#{bold("##{tid}")}] #{prio} | Due: #{due}#{badge}"
+    puts "   #{bold('Title:')} #{name}"
+    puts "   #{bold('Where:')} #{where}" if where && !where.to_s.empty?
+    puts "   #{bold('URL:')}   #{cyan(url)}" if url && !url.to_s.empty?
+    puts "   #{bold('Tags:')}  #{tags.map { |tg| "##{tg}" }.join(' ')}" unless tags.empty?
+    if !desc.empty?
+      first_line = desc.lines.first.to_s.strip
+      snippet = first_line.length > 90 ? "#{first_line[0..87]}..." : first_line
+      puts "   #{bold('Ctx:')}   #{gray(snippet)}"
     end
-    
-    def show_full_entry(opts={})
-      attributes = %w{
-        colored_name id 
-        due hide_until   
-        active depends_on_id 
-        photo_url progress_status 
-        source tags_comma_separated_list 
-        url where
-      }
-      key_vals = attributes.map{|attr| [attr,send(attr)] } # array of [key, val]
-      key_vals << ['ProjectName', "#{project.name} (#{send(project.color,project.color ) rescue white(project.color) })" ]
-      key_vals.map{|k,v| [k,v] }.select{|k,v| v.to_s != ''}.sort{|x,y| x.first <=> y.first }.map{ |k,v| "#{k}: #{v}" }.join("\n") +
-        "\n--\n#{description}"
+    puts "-" * 75
+
+    shown += 1
+    break if opts[:limit] && shown >= opts[:limit]
+  end
+
+  puts "No matching todos found." if shown == 0
+end
+
+def cmd_show(id_arg, opts, cfg)
+  todo_id = extract_todo_id(id_arg)
+  res = make_request(cfg, "todos/#{todo_id}.json", timeout: opts[:timeout])
+  if res["error"]
+    warn red("Error fetching todo ##{todo_id} (#{res['status']}): #{res['error']}")
+    exit 1
+  end
+
+  raw_t = res["data"]
+  t = raw_t.is_a?(Hash) && raw_t["todo"].is_a?(Hash) ? raw_t["todo"] : raw_t
+  if t.nil? || !t.is_a?(Hash) || t["id"].nil?
+    warn red("❌ Error: Todo ##{todo_id} not found (or not visible to user '#{cfg['user']}' on #{cfg['site']}).")
+    exit 1
+  end
+
+  if opts[:json]
+    puts JSON.pretty_generate(t)
+    return
+  end
+
+  u = t["user"]
+  agent_str = ""
+  if u.is_a?(Hash) && u["is_agent"]
+    icon = u["agent_icon"]
+    uname = u["username"].to_s
+    agent_key = uname.include?(".") ? uname.split(".").last.downcase : uname.downcase
+    icon = AGENT_ICONS.fetch(agent_key, "🤖") if icon.nil? || icon.empty? || icon == "?"
+    agent_str = "\nAgent:    #{icon} #{uname} (host: #{u['agent_host'] || 'unknown'})"
+  end
+
+  web_base = cfg["site"].to_s.sub(%r{/api/?\z}, "")
+  web_link = "#{web_base}/todos/#{t['id']}"
+
+  puts "\n📋 #{bold("Todo ##{t['id']} - #{t['name']}")}\n" + ("=" * 60)
+  puts "Status:   #{t['active'] ? green('Active') : gray('Done')}"
+  puts "Priority: #{format_priority(t['priority'] || 3)}"
+  puts "Project:  #{t.dig('project', 'name') || t['project_id']}" if t["project"] || t["project_id"]
+  puts "Due:      #{t['due'] || 'None'}"
+  puts "Where:    #{t['where'] || 'None'}"
+  puts "URL:      #{t['url'] || 'None'}"
+  puts "Web Link: #{cyan(web_link)}"
+  puts "Tags:     #{Array(t['tag_list']).inspect}#{agent_str}"
+  puts "\n#{bold('Context / Description:')}\n#{t['description'] || 'None'}\n"
+  puts "-" * 60
+  if t["active"]
+    puts "💡 #{bold('Mark done:')}    #{green("septober-cli done #{t['id']}")}"
+  else
+    puts "💡 #{bold('Reopen todo:')}  #{yellow("septober-cli undone #{t['id']}")}"
+  end
+  puts "💡 #{bold('Toggle state:')} #{cyan("septober-cli toggle #{t['id']}")}"
+  puts "💡 #{bold('Delete todo:')}  #{red("septober-cli delete #{t['id']}")}\n\n"
+end
+
+def cmd_add(positional_args, opts, cfg)
+  title = opts[:title] || positional_args.join(" ").strip
+  if title.nil? || title.empty?
+    warn red("Error: Todo title is required (pass --title '...' or positional text).")
+    exit 1
+  end
+
+  hostname = local_hostname
+  agent_id = cfg["agent"]
+  co_author = harness_co_author(agent_id)
+  harness_nick = harness_nickname(agent_id)
+
+  where_val = opts[:where] || hostname
+  source_val = harness_nick ? "cli-26/#{harness_nick}@#{hostname}" : "cli-26@#{hostname}"
+
+  desc = opts[:description]
+  if co_author && (desc.nil? || !desc.include?("Co-authored-by"))
+    co_note = "Collected via CLI on #{hostname} (Co-authored-by: #{co_author})"
+    desc = desc && !desc.empty? ? "#{desc}\n\n#{co_note}" : co_note
+  end
+
+  proj = opts[:project] || "septober"
+  todo_payload = {
+    "name"     => title,
+    "priority" => opts[:priority] || 3,
+    "source"   => source_val,
+    "project"  => proj,
+    "where"    => where_val
+  }
+  todo_payload["description"] = desc if desc && !desc.empty?
+  todo_payload["url"]         = opts[:url] if opts[:url]
+  todo_payload["due"]         = opts[:due] if opts[:due]
+
+  if opts[:tags] && !opts[:tags].empty?
+    tag_items = opts[:tags].split(",").map { |x| x.strip.sub(/\A[#@]+/, "") }.reject(&:empty?)
+    unless tag_items.empty?
+      todo_payload["tags"] = tag_items
+      todo_payload["name"] = "#{title} #{tag_items.map { |t| "@#{t}" }.join(' ')}"
     end
-  end # /RemoteTodo
-  #################################################################################################################################################
-  
-  #############################
-  # Program start..
-  
-  # header
-  def bannerino(desc)
-    "#septober v#{$PROG_VER} #{white desc.to_s} (#{green RemoteTodo.user} @ #{cyan RemoteTodo.site.to_s.split('/')[2] }, timeout=#{RemoteTodo.timeout})" + 
-      (RemoteTodo.description.length > 2 ? " # #{gray RemoteTodo.description}" : '')
-  end
-
-  def todo_list(opts={})
-    show_only_active = opts.fetch :only_active, true
-    puts bannerino( "Index" )
-    all = RemoteTodo.find(:all)
-    all.each{|todo|
-      puts( todo.show_entry ) unless( show_only_active && ! todo.active )
-      #deb "Full ToString for #{white todo}:\n\t#{todo.inspect}"
-    } if all
-  end
-  
-=begin
-  Adds a todo with just the subject, the server takes it and parses and does the magic
-  to assing the correct ptoject and stuff..
-=end
-  def todo_add(words_from_argv)
-    puts bannerino( "Todo.Add('#{words_from_argv}')" )
-    # TODO put this into begin/end/catch !!!
-    t = RemoteTodo.create( 
-      :name => words_from_argv, 
-      :description => "sent by CLI #{$0} v.#{$PROG_VER}, due tomorrow by test", 
-      #:due => Date.tomorrow, 
-      :where => Socket.gethostname,
-      :source => "CLI v.#{$PROG_VER}"
-      #:project_id => 5,
-      #:priority => 4 
-    )
-    #deb "DEB todo: #{t}"
-    
-    puts "Trying to save TODO at all costs: #{t}"
-    ret = t.save
-
-    #pred t.errors.full_messages if t.errors
-    puts "Some errors: '#{red t.errors.full_messages.to_s}'" if t.errors # and t.errors.full_messages.to_s != ''
-    
-    if ret
-      puts "Todo created successfully: ##{green t.id.to_s}" # just provides the Id 
-      puts "ret: #{ret}" 
-    else
-      pred "Some error saving todo: #{t.inspect}"
+  end
+
+  res = make_request(cfg, "todos.json", method: "POST", body: todo_payload, timeout: opts[:timeout])
+  if res["error"]
+    warn red("Error creating todo (#{res['status']}): #{res['error']}")
+    exit 1
+  end
+
+  raw_data = res["data"]
+  new_id = if raw_data.is_a?(Hash)
+             (raw_data["todo"] || raw_data)["id"] || "?"
+           elsif raw_data.to_s =~ /\A\d+\z/
+             raw_data.to_s
+           else
+             "new"
+           end
+
+  web_base = cfg["site"].to_s.sub(%r{/api/?\z}, "")
+  puts "✅ #{green("Todo ##{new_id} created successfully!")}"
+  puts "   Title:    #{title}"
+  puts "   Priority: #{format_priority(opts[:priority] || 3)}"
+  puts "   Where:    📍 #{where_val}" if where_val
+  puts "   URL:      #{opts[:url]}" if opts[:url]
+  puts "   Web Link: #{cyan("#{web_base}/todos/#{new_id}")}" if new_id.to_s =~ /\A\d+\z/
+  puts "   Context:  #{desc}" if desc
+end
+
+def cmd_action(action_name, id_arg, opts, cfg)
+  todo_id = extract_todo_id(id_arg)
+  endpoint = "todos/#{todo_id}/#{action_name}.json"
+  res = make_request(cfg, endpoint, method: "PUT", timeout: opts[:timeout])
+  if res["error"]
+    warn red("Error running '#{action_name}' on todo ##{todo_id} (#{res['status']}): #{res['error']}")
+    exit 1
+  end
+  puts "✅ #{green("Todo ##{todo_id}: #{action_name.upcase} completed!")}"
+end
+
+def main(argv = ARGV)
+  opts = {
+    conf:         nil,
+    env:          nil,
+    agent:        nil,
+    local:        false,
+    timeout:      25,
+    all:          false,
+    limit:        20,
+    tag:          nil,
+    json:         false,
+    title:        nil,
+    description:  nil,
+    url:          nil,
+    where:        nil,
+    priority:     3,
+    project:      "septober",
+    due:          nil,
+    tags:         nil,
+    user:         nil,
+    password:     nil,
+    verbose:      false,
+    debug:        false
+  }
+
+  parser = OptionParser.new do |o|
+    o.banner = <<~BANNER
+      🚛 Septober CLI v#{PROG_VER} (Ruby #{RUBY_VERSION})
+      Usage:
+        #{File.basename($PROGRAM_NAME)} [options] list [--all] [--limit N] [--tag TAG] [--json]
+        #{File.basename($PROGRAM_NAME)} [options] show <ID_OR_URL> [--json]
+        #{File.basename($PROGRAM_NAME)} [options] add <TITLE> [--description "..."] [--priority 1-5] [--where "..."] [--url "..."] [--tags t1,t2]
+        #{File.basename($PROGRAM_NAME)} [options] done <ID_OR_URL>
+        #{File.basename($PROGRAM_NAME)} [options] toggle <ID_OR_URL>
+        #{File.basename($PROGRAM_NAME)} [options] delete <ID_OR_URL>
+
+      Options:
+    BANNER
+
+    o.on("-c", "--conf FILE", "--config FILE", "Path to .septober.yml") { |v| opts[:conf] = v }
+    o.on("-e", "-s", "--env ENV", "--subconf ENV", "Target environment (e.g. septober, local)") { |v| opts[:env] = v }
+    o.on("--agent AGENT", "Agent profile (e.g. ermete, lobby, pux)") { |v| opts[:agent] = v; opts[:filter_agent] = v }
+    o.on("-l", "--local", "Force local environment") { opts[:local] = true }
+    o.on("-u", "--user USER", "Override Septober username/email") { |v| opts[:user] = v }
+    o.on("-p", "--password PASS", "Override Septober password") { |v| opts[:password] = v }
+    o.on("-t", "--timeout SEC", Integer, "HTTP timeout in seconds (default: 25)") { |v| opts[:timeout] = v }
+    o.on("-n", "--no-colors", "Disable ANSI colors") { $colors_active = false }
+    o.on("-a", "--all", "Include completed todos in list") { opts[:all] = true }
+    o.on("--limit N", Integer, "Max todos to show in list (default: 20)") { |v| opts[:limit] = v }
+    o.on("--tag TAG", "Filter list by tag") { |v| opts[:tag] = v }
+    o.on("--json", "Output raw JSON") { opts[:json] = true }
+    o.on("--title TITLE", "Todo title for add") { |v| opts[:title] = v }
+    o.on("--description DESC", "--desc DESC", "Rich narrative context for add") { |v| opts[:description] = v }
+    o.on("--url URL", "Primary reference URL for add") { |v| opts[:url] = v }
+    o.on("--where WHERE", "Location/event anchor for add") { |v| opts[:where] = v }
+    o.on("--priority PRIO", Integer, "Priority 1 (low) to 5 (urgent)") { |v| opts[:priority] = v }
+    o.on("--project PROJ", "Project name (default: septober)") { |v| opts[:project] = v }
+    o.on("--due DUE", "Due date (YYYY-MM-DD or today/tomorrow)") { |v| opts[:due] = v }
+    o.on("--tags TAGS", "Comma-separated tags (e.g. lavoro,google,tech)") { |v| opts[:tags] = v }
+    o.on("-d", "--debug", "Enable debug output") { opts[:debug] = true }
+    o.on("-v", "--verbose", "Enable verbose output") { opts[:verbose] = true }
+    o.on("-V", "--version", "Show version") do
+      puts "septober-cli v#{PROG_VER} (ruby #{RUBY_VERSION})"
+      exit 0
     end
-    pgray "TODO get meaningful explaination from api/todos_controller!"
-    #puts "errors: #{ret.errors}"
-  end
-  
-  def todo_show(id)
-    todo = RemoteTodo.find(id)
-    puts bannerino("Show(#{id})")
-    puts( todo.show_full_entry )
-  end
-  
-  def todo_done(id,done_or_undone=true)
-    todo_generic_put(id,:done)
-  end
-  def todo_toggle(id,done_or_undone=true)
-    todo_generic_put(id,:toggle)
-  end
-  
-  def todo_generic_put(id,action,opts={})
-    puts bannerino("GenericAction(#{action},#{id})")
-    begin
-      todo = RemoteTodo.find(id)
-      puts "Todo.#{id} ok #{green action}: #{yellow( todo.to_s )}"
-      put_options = {
-        :my_action => action, 
-        :from_cli_in_test_ric => Socket.gethostname
-      }.merge( opts.fetch( :additional_args, {:nis => :bah } ) ) # if there are ,m good. Otherwise, "nisba" :)
-      deb "todo_generic_put(id=#{id},#{purple action}, #{gray opts.inspect})"
-      todo.put(action, put_options ) # test stuff
-      #todo.put(action, :my_action => action, :from_cli_in_test_ric => Socket.gethostname , additional_args) # test stuff
-    rescue ActiveResource::ResourceNotFound
-      puts "Sorry ResourceNotFound: #{red $!}" 
-      exit 11
-    rescue   ActiveResource::ServerError
-      puts "Sorry ServerError: #{red $!}" 
-      exit 12
+    o.on("-h", "--help", "Show this help") do
+      puts o
+      exit 0
     end
-    # todo is good
-    #todo.put(:generic_action, :my_action => action)
-  end
-  
-  def todo_search(q)
-    puts "# Todo.Search('#{q}') (user: #{blue RemoteTodo.user})"
-    pred "To Be implemented Yet"
-  end
-  
-  def usage(explaination=nil)
-    puts $optparse
-    pred(explaination) if explaination
-    exit 85
-  end
-  
-
-  def main()
-    #YAML::ENGINE.yamler = 'syck'
-    init()
-      # Maybe you may want to check on ARGV
-    #unless ARGV.size > 0
-    #  usage "Give me at least 1 argument" # Maybe default to list?!? 
-    #end
-    all_args = ARGV[1..-1].join(' ') rescue ''
-    case ARGV[0].to_s
-      when 'list'  ;    todo_list()
-      when 'show'  ;    todo_show(ARGV[1])
-      when 'done'  ;    todo_done(ARGV[1],true)
-      when 'add'   ;    todo_add(all_args) # all except last one
-      when 'toggle';    todo_toggle(ARGV[1]) # all except last one
-      when 'delete';    todo_generic_put(ARGV[1], :delete , :additional_args => {:test_foo => 'test deletion string, with whole DELETE' }) 
-      when 'del';       todo_generic_put(ARGV[1], :delete , :additional_args => {:test_foo => 'test deletion string, with just DEL' }) 
-      when 'edit';      todo_generic_put(ARGV[1], :edit,    :additional_args => ARGV.map{|arg| k,v=arg.split(':') } )
-          # TODO transform [ [act1, arg1], [act2,arg2]] into {:act1 => arg1, :act2 => arg2 }
-      when 'tag'   ;    todo_generic_put(ARGV[1], :additional_args => {:tag_with => all_args.join(',') }) # all except last one
-      when 'help'  ;    usage 'Explicitly called help..'
-      when ''      ;    todo_list()
-      else            
-        usage "Unrecognized command: '#{ARGV[0]}'"
+  end
+
+  remaining = parser.parse(argv.dup)
+  subcommand = remaining.shift
+
+  if subcommand.nil?
+    puts parser
+    exit 0
+  end
+
+  # Support passing a bare ID or Septober URL directly (e.g. `septober-cli 235` or `septober-cli https://.../todos/235`)
+  if subcommand =~ /\A#?\d+\z/ || subcommand =~ %r{/todos/\d+}
+    remaining.unshift(subcommand)
+    subcommand = "show"
+  end
+
+  target_env = opts[:local] ? "local" : opts[:env]
+  # For `list`, `--agent` filters by agent unless SEPTOBER_AGENT is explicitly set; for write/show commands, `--agent` selects credentials
+  cred_agent = (subcommand == "list") ? ENV["SEPTOBER_AGENT"] : opts[:agent]
+  cfg = load_config(
+    conf_path: opts[:conf],
+    target_env: target_env,
+    target_agent: cred_agent,
+    cli_user: opts[:user],
+    cli_password: opts[:password]
+  )
+
+  case subcommand.downcase
+  when "list", "ls"
+    cmd_list(opts, cfg)
+  when "show", "get", "view"
+    id_arg = remaining.first
+    if id_arg.nil?
+      warn red("Error: 'show' requires a Todo ID or URL.")
+      exit 1
     end
+    cmd_show(id_arg, opts, cfg)
+  when "add", "create", "new"
+    cmd_add(remaining, opts, cfg)
+  when "done", "complete"
+    id_arg = remaining.first || abort(red("Error: 'done' requires a Todo ID."))
+    cmd_action("done", id_arg, opts, cfg)
+  when "undone"
+    id_arg = remaining.first || abort(red("Error: 'undone' requires a Todo ID."))
+    cmd_action("undone", id_arg, opts, cfg)
+  when "toggle"
+    id_arg = remaining.first || abort(red("Error: 'toggle' requires a Todo ID."))
+    cmd_action("toggle", id_arg, opts, cfg)
+  when "delete", "del", "rm"
+    id_arg = remaining.first || abort(red("Error: 'delete' requires a Todo ID."))
+    cmd_action("delete", id_arg, opts, cfg)
+  when "version"
+    puts "septober-cli v#{PROG_VER} (ruby #{RUBY_VERSION})"
+  else
+    warn red("Unknown subcommand: '#{subcommand}'")
+    puts parser
+    exit 1
   end
+end
 
-#########################################################
-# real program...
-main()
+main(ARGV) unless ENV["SEPTOBER_CLI_NO_AUTORUN"] == "1"