samagotchi 0.157.0 → 0.159.0

data/lib/samagotchi/prompt_files.rb

@@ -19,9 +19,10 @@ module Samagotchi
     module_function
 
     # The AGENTS.md files a session in +cwd+ loads, as absolute paths,
-    # outermost first: inside a git work tree every one from its top (a
-    # linked worktree's own checkout) down to the cwd; outside a repository
-    # only the cwd's ([] with none).
+    # outermost first: inside a project every one from its top
+    # (MemoryPaths.project_top: a git work tree's, a linked worktree's own
+    # checkout, or a folder marked by `chi project init`) down to the cwd;
+    # outside a project only the cwd's ([] with none).
     # @param cwd [String] where the prompt is built (Dir.pwd, not the
     #   session's working directory: /tmp vs /private/tmp would change the
     #   prompt bytes)
@@ -33,10 +34,10 @@ module Samagotchi
     # The sections of the AGENTS.md chain (#agents_paths) with text: the
     # first keeps the plain header (a one-file session's prompt is as it
     # always was), each further one names its directory relative to the
-    # work tree top ("Project specific description for pkg/:").
+    # project's top ("Project specific description for pkg/:").
     # @return [Array<Section>]
     def agents_sections(cwd)
-      top = MemoryPaths.work_tree_root(cwd)
+      top = MemoryPaths.project_top(cwd)
       sections = []
       agents_paths(cwd).each do |path|
         dir = File.dirname(path)
@@ -47,10 +48,12 @@ module Samagotchi
       sections
     end
 
-    # The directories whose AGENTS.md a session in +cwd+ reads, outermost first.
+    # The directories whose AGENTS.md a session in +cwd+ reads, outermost
+    # first: from its project's top (the work tree's, or the marked root)
+    # down to +cwd+.
     def chain_dirs(cwd)
       cwd = File.expand_path(cwd)
-      top = MemoryPaths.work_tree_root(cwd)
+      top = MemoryPaths.project_top(cwd)
       return [cwd] unless top
 
       rel = relative_dir(cwd, top)

data/lib/samagotchi/recap_place.rb

@@ -1,14 +1,13 @@
 # frozen_string_literal: true
 
 require_relative "steer"
-require_relative "bridge/card_places"
 
 module Samagotchi
   # Where a saved recap sits among the turns a page draws: after the last
   # turn opening it covers (Steer.turn_opening?, the rule its turns_since
   # count goes by). Its stamp is that opening's id, as a card's is
-  # (Bridge::CardPlaces.stamp: a prompt's turn_id, a wake note's, a
-  # /continue no reason line's opening_id), so the page finds the bubble by
+  # (Steer.opening_stamp: a prompt's turn_id, a wake note's, a /continue no
+  # reason line's opening_id), so the page finds the bubble by
   # id, not by counting back (a rollback or a check-in could make the count
   # land a turn off). Read at read time from recap.json's `covered`: the file
   # is unchanged, an old one gets a stamp too. Pure.
@@ -21,7 +20,7 @@ module Samagotchi
     #   messages; nil for none, or one with no id (a line an older chi wrote)
     def opening_id(messages, covered)
       opening = Array(messages).first([covered.to_i, 0].max).reverse_each.find { |message| Steer.turn_opening?(message) }
-      opening && Bridge::CardPlaces.stamp(opening)
+      opening && Steer.opening_stamp(opening)
     end
   end
 end

data/lib/samagotchi/run_options.rb

@@ -213,6 +213,8 @@ module Samagotchi
                  chi desktop <install|upgrade|uninstall|status>   macOS "Send to chi" helper
                  chi models [--format json] [TEXT]   the models --model takes, from every host
                  chi home [set [--ruby PATH] | doctor]   the Ruby every chi launch boots
+                 chi project [init [DIR]]         this folder's project; init makes a folder in no git repository one
+                 chi schedule <add|list|show|tick|run-now|enable|disable|cancel>   durable schedules that outlive every worker
                  chi remote <add|ls|rm>           other machines' chi web, for chi --remote NAME
                  chi --remote NAME <send|answer|note|context|sessions|share|review> …   those commands on that machine (or CHI_REMOTE=NAME)
                  chi --remote NAME --attach ID | --resume ID | --dir DIR [-p TEXT]   a session on that machine, in this terminal

data/lib/samagotchi/schedule_command.rb

@@ -0,0 +1,252 @@
+# frozen_string_literal: true
+
+require "json"
+require "time"
+
+require_relative "cli/command"
+require_relative "cli/exit"
+require_relative "cli/flags"
+require_relative "schedules"
+require_relative "session"
+
+module Samagotchi
+  # `chi schedule`: durable schedules that outlive every worker (docs/scheduling.md).
+  # A tick run by cron, systemd or chi web's hub (`chi schedule tick`) fires the
+  # entries whose time has come against a session: the next link of its chain
+  # (the default), or a queued turn in the session itself.
+  # bin/chi dispatches here before OptionParser; this machine only.
+  class ScheduleCommand
+    include CLI::Command
+
+    USAGE = <<~TEXT
+      Usage: chi schedule <add|list|show|tick|run-now|enable|disable|cancel> [flags]
+
+        add --session ID (--continues ID) (-m|--message|--prompt TEXT) [--title TEXT]
+            one of: --every 30m | --weekday 1 --time 09:00 | --date 2026-11-20T09:00
+            [--mode chain|same] [--catch-up once|none] [--keep-links N] [--max-failures N] [--max-skips N]
+        list [--all] [--format text|json]
+        show ID
+        tick [--dry-run] [--format text|json]
+        run-now ID
+        enable ID | disable ID | cancel ID
+
+      Recurrence: --every 45m / 2h / 1d (UTC interval math: an `every 1d` schedule drifts
+      an hour across a DST change — use --weekday for a wall-clock time);
+      --weekday 1..7 (1=Mon) with --time HH:MM in the machine's local zone;
+      --date one local moment.
+      Modes: chain (default) runs the prompt as the next link of the session's chain;
+      same queues it as a turn in the session itself.
+      A busy target is skipped and retried at the next tick; after max_skips skips
+      (default 12) or max_failures failures (default 3) the schedule is disabled.
+    TEXT
+
+    SUBCOMMANDS = %w[add list show tick run-now enable disable cancel].freeze
+
+    # A usage error names the subcommand it was given (CLI::Command's
+    # usage_error builds its line from this).
+    def command_name = SUBCOMMANDS.include?(@argv.first.to_s) ? "chi schedule #{@argv.first}" : "chi schedule"
+
+    FLAGS = {
+      "add" => CLI::Flags.new(args: true) do |f|
+        f.value "--session", "--continues", key: :target
+        f.value "-m", "--message", "--prompt", key: :prompt
+        f.value "--title"
+        f.value "--every"
+        f.value "--weekday"
+        f.value "--time"
+        f.value "--date"
+        f.value "--mode"
+        f.value "--catch-up"
+        f.value "--keep-links"
+        f.value "--max-failures"
+        f.value "--max-skips"
+      end,
+      "list" => CLI::Flags.new(args: false) do |f|
+        f.switch "--all", key: :include_disabled
+        f.value "--format"
+      end,
+      "show" => CLI::Flags.new(args: true),
+      "tick" => CLI::Flags.new(args: false) do |f|
+        f.switch "--dry-run"
+        f.value "--format"
+      end,
+      "run-now" => CLI::Flags.new(args: true),
+      "enable" => CLI::Flags.new(args: true),
+      "disable" => CLI::Flags.new(args: true),
+      "cancel" => CLI::Flags.new(args: true)
+    }.freeze
+
+    # @param argv [Array<String>] the arguments after "schedule"
+    # @param schedules [Schedules, nil] the store; default this machine's
+    def initialize(argv, stdout: $stdout, stderr: $stderr, schedules: nil)
+      @argv = argv.dup
+      @stdout = stdout
+      @stderr = stderr
+      @schedules = schedules || Schedules.new
+    end
+
+    # @return [Integer] exit status: 0 ok, 1 a missing session or schedule,
+    #   2 a usage error
+    def run
+      sub = @argv[0]
+      if sub.nil? || HELP_WORDS.include?(sub)
+        @stdout.puts(USAGE)
+        return 0
+      end
+      return usage_error("unknown subcommand #{sub}") unless SUBCOMMANDS.include?(sub)
+
+      parsed = parse_flags(FLAGS.fetch(sub), @argv[1..])
+      return parsed if parsed.is_a?(Integer)
+
+      @opts = parsed.options
+      @args = parsed.args
+
+      case sub
+      when "add" then add
+      when "list" then list
+      when "show" then show
+      when "tick" then tick
+      when "run-now" then act { |id| @schedules.run_now(id) }
+      when "enable" then act { |id| @schedules.enable(id) }
+      when "disable" then act { |id| @schedules.disable(id) }
+      when "cancel" then act { |id| @schedules.cancel(id) }
+      end
+    end
+
+    private
+
+    def add
+      if @opts[:target].to_s.strip.empty? && !@args.empty?
+        return usage_error("add takes the session with --session ID, not #{@args.map { |arg| arg.inspect }.join(" ")}")
+      end
+      return usage_error("add needs --session ID (the session the schedule runs against)") if @opts[:target].to_s.strip.empty?
+      return usage_error("add needs a prompt: -m \"...\"") if @opts[:prompt].to_s.strip.empty?
+
+      begin
+        recurrence = Schedules.recurrence(every: @opts[:every], weekday: @opts[:weekday], time: @opts[:time], date: @opts[:date])
+        entry = @schedules.add(target: @opts[:target], prompt: @opts[:prompt], recurrence: recurrence,
+                               title: @opts[:title], mode: @opts[:mode] || Schedules::CHAIN,
+                               catch_up: @opts[:catch_up], keep_links: @opts[:keep_links],
+                               max_failures: @opts[:max_failures], max_skips: @opts[:max_skips])
+      rescue Schedules::Usage => e
+        return usage_error(e.message)
+      rescue Session::AmbiguousId => e
+        return failed("which session? #{e.message}")
+      rescue Session::NotFound
+        return failed("no session #{@opts[:target]}")
+      end
+
+      @stdout.puts("#{entry.id} added: #{entry.target_words} · #{entry.recurrence_words} · next #{clock(entry.next_due)}")
+      CLI::Exit::OK
+    end
+
+    def list
+      entries = @schedules.entries(include_disabled: @opts[:include_disabled] ? true : false)
+      if @opts[:format] == "json"
+        @stdout.puts(JSON.pretty_generate(entries.map { |entry| entry_line_json(entry) }))
+        return CLI::Exit::OK
+      end
+      if entries.empty?
+        @stdout.puts("no schedules")
+        return CLI::Exit::OK
+      end
+      entries.each { |entry| @stdout.puts(entry_line(entry)) }
+      CLI::Exit::OK
+    end
+
+    def show
+      id = @args.first || @opts[:id]
+      return usage_error("show needs a schedule id") if id.to_s.strip.empty?
+
+      entry = @schedules.lookup(id)
+      return failed("no schedule #{id}") if entry.nil?
+
+      @stdout.puts("#{entry.id}  #{entry.title || "(untitled)"}")
+      @stdout.puts("  anchor: #{entry.anchor}  head: #{entry.head}  mode: #{entry.mode}")
+      @stdout.puts("  recurrence: #{entry.recurrence_words}  next due: #{clock(entry.next_due)}")
+      @stdout.puts("  last fired: #{clock(entry.last_fired)}  last result: #{entry.last_result || "-"}")
+      @stdout.puts("  skips: #{entry.skips} of #{entry.max_skips}  failures: #{entry.failures} of #{entry.max_failures}")
+      @stdout.puts("  keep_links: #{entry.keep_links}  enabled: #{entry.enabled}")
+      @stdout.puts("  prompt: #{entry.prompt}")
+      CLI::Exit::OK
+    rescue Schedules::Usage => e
+      usage_error(e.message)
+    end
+
+    def tick
+      result = @schedules.tick(dry_run: @opts[:dry_run] ? true : false)
+      if @opts[:format] == "json"
+        @stdout.puts(JSON.pretty_generate({ "locked" => result.locked, "outcomes" => result.outcomes.map { |outcome| { "id" => outcome.id, "status" => outcome.status, "detail" => outcome.detail } } }))
+        return CLI::Exit::OK
+      end
+
+      if result.locked
+        @stdout.puts("no schedules due (another tick holds the lock)")
+        return CLI::Exit::OK
+      end
+      if result.outcomes.empty?
+        @stdout.puts("no schedules due")
+        return CLI::Exit::OK
+      end
+
+      result.outcomes.each do |outcome|
+        word = outcome.status == "dry" ? "would fire" : outcome.status
+        @stdout.puts("#{outcome.id}  #{word}  #{outcome.detail}")
+      end
+      CLI::Exit::OK
+    end
+
+    def act
+      id = @args.first
+      return usage_error("#{@argv[0]} needs a schedule id") if id.to_s.strip.empty?
+
+      result = yield(id)
+      return failed("no schedule #{id}") if result.nil?
+
+      if result.is_a?(Schedules::Outcome)
+        @stdout.puts("#{id}: #{result.status} · #{result.detail}")
+        return result.status == "failed" ? CLI::Exit::FAILED : CLI::Exit::OK
+      end
+
+      @stdout.puts("#{id} #{@argv[0]}: ok")
+      CLI::Exit::OK
+    rescue Schedules::Usage => e
+      usage_error(e.message)
+    end
+
+    def failed(message)
+      error_line(message)
+      CLI::Exit::FAILED
+    end
+
+    def clock(iso)
+      return "-" if iso.nil? || iso.to_s.empty?
+
+      Time.iso8601(iso.to_s).localtime.strftime("%Y-%m-%d %H:%M")
+    rescue ArgumentError
+      iso.to_s
+    end
+
+    def entry_line(entry)
+      note = ""
+      note += " skips #{entry.skips} of #{entry.max_skips} (#{skip_window(entry)})" if entry.skips.positive?
+      note += " disabled after #{entry.failures} failures" unless entry.enabled
+      "#{entry.id}  #{entry.mode}  #{entry.recurrence_words}  #{clock(entry.next_due)}  #{entry.head[0, 8]}#{note}"
+    end
+
+    # A skip budget as a time window: 3 of 12 at a 5 minute tick is about 1 hour
+    # of patience, which is what the count really measures.
+    def skip_window(entry)
+      minutes = entry.max_skips * Schedules.tick_interval_minutes
+      hours = minutes / 60.0
+      hours >= 1 ? "≈#{(hours * 10).round / 10} h at a #{Schedules.tick_interval_minutes} min tick" : "≈#{minutes} min"
+    end
+
+    def entry_line_json(entry)
+      entry.to_h.transform_keys(&:to_s).merge(
+        "recurrence_words" => entry.recurrence_words,
+        "skip_window" => skip_window(entry)
+      )
+    end
+  end
+end