samagotchi 0.8.1 → 0.10.0

data/lib/samagotchi/bundles/loop-guard/plugin.rb

@@ -187,13 +187,13 @@ end
 class Plugin
   DEFAULT_IGNORE = %w[task_wait task_get delegate_result list_sessions list_reminders].freeze
   # Built-in tools carry flat fields; plugin and unknown tools carry args:.
-  KEY_FIELDS = %i[content path start_line end_line cwd env scope].freeze
+  # An edit's text is its old_text/new_text.
+  KEY_FIELDS = %i[content path start_line end_line cwd env scope old_text new_text].freeze
   SHORT_CHARS = 60
   THOUGHT_CHARS = 80
   SOURCE = "bundle loop-guard"
 
   def initialize(settings = {})
-    settings = {} unless settings.is_a?(Hash)
     @deny_after = positive(settings["deny_after"]) || 2
     @stop_after = positive(settings["stop_after"]) || 4
     @ignore = settings.key?("ignore_tools") ? Array(settings["ignore_tools"]).map(&:to_s) : DEFAULT_IGNORE
@@ -234,16 +234,16 @@ class Plugin
       ctx.notify("thinking repeats itself (#{what})", level: :warn)
     when "retry"
       @thinking_loops += 1
-      return stop_thinking(event, ctx, found, what) if @thinking_loops > 1
+      return stop_thinking(ctx, found, what) if @thinking_loops > 1
 
-      ctx.notify("thinking repeats itself (#{what}): cut", level: :warn) if event[:stop_generation]&.call("its thinking kept repeating itself")
+      ctx.notify("thinking repeats itself (#{what}): cut", level: :warn) if ctx.stop_generation("its thinking kept repeating itself")
     else
-      stop_thinking(event, ctx, found, what)
+      stop_thinking(ctx, found, what)
     end
   end
 
-  def stop_thinking(event, ctx, found, what)
-    return unless event[:stop_turn]&.call("the model's thinking kept repeating itself (#{what})")
+  def stop_thinking(ctx, found, what)
+    return unless ctx.stop_turn("the model's thinking kept repeating itself (#{what})")
 
     lines = found.sentences.first(3).map { |sentence| "- \"#{cut(sentence, THOUGHT_CHARS)}\"" }
     ctx.card(title: "loop-guard stopped the turn",
@@ -288,7 +288,7 @@ class Plugin
     verdict.deny!("repeated call", source: SOURCE, advice: advice(key, times))
     warn(ctx, key, "repeated, denied")
     @denials += 1
-    stop(event, ctx) if @denials == @stop_after
+    stop(ctx) if @denials == @stop_after
   end
 
   # A call's result, paired with the before_tool_call that keyed it. A call
@@ -308,8 +308,8 @@ class Plugin
     @previews[key] = preview(output)
   end
 
-  def stop(event, ctx)
-    event[:stop_turn]&.call("the model kept repeating the same calls")
+  def stop(ctx)
+    ctx.stop_turn("the model kept repeating the same calls")
     repeated = @attempts.select { |key, n| n > 1 && @last_result[key] && @results[[key, @last_result[key]]] >= @deny_after }
     lines = repeated.map do |key, n|
       "- `#{short_key(key)}`: #{n} times, the same result each time (#{@previews[key]})"

data/lib/samagotchi/bundles/mcp/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: mcp
-version: 0.3.1
+version: 0.3.2
 scope: system
 description: "Tools from MCP servers (stdio): each server in config.yml bundles: mcp: servers: runs for the session, its tools are mcp_<server>_<tool>; /mcp lists them"
 trust_level: reviewed
 files: {}
 plugin:
   file: plugin.rb
-  sha256: sha256:f7bfcaae51863c0dc2b057b0d30f79b7bed7935891e817fa7373f787e5c4ca5e
-requires_chi: ">= 0.1.37"
+  sha256: sha256:61b195a5621ddf57ba69a505aff06d620d6459e836d736205343a251b0fecb71
+requires_chi: ">= 0.8.0"

data/lib/samagotchi/bundles/mcp/plugin.rb

@@ -421,10 +421,8 @@ class Plugin
 
   # Written aside and renamed: workers share the dir.
   def save_cache(server, ctx)
-    path = cache_path(server, ctx)
-    tmp = "#{path}.#{Process.pid}.#{Thread.current.object_id}.tmp"
-    File.write(tmp, JSON.generate({ digest: server.digest, saved_at: Time.now.utc.iso8601, tools: server.listed }))
-    File.rename(tmp, path)
+    Samagotchi::AtomicFile.write(cache_path(server, ctx),
+                                 JSON.generate({ digest: server.digest, saved_at: Time.now.utc.iso8601, tools: server.listed }))
   rescue SystemCallError => e
     ctx.log.warn("mcp_cache_not_written", server: server.name, msg: e.message)
   end

data/lib/samagotchi/bundles/skills/manifest.yml

@@ -1,10 +1,10 @@
 ---
 name: skills
-version: 0.1.0
+version: 0.1.3
 scope: system
 description: "Skills (skill_<name> memories, the steps of a task done together): /skill save, list, show and diff; older versions kept with a short diff line on every update; a nudge when a followed skill's step fails"
 trust_level: reviewed
 plugin:
   file: plugin.rb
-  sha256: sha256:76758d41e75db107e0a6f7ce35b9eac4944052746af16aeba30f38210cc436dc
-requires_chi: ">= 0.4.0"
+  sha256: sha256:4f32b3457ada3392009e4a32b690e577ef0bb05d46c6cfed9ae02640119620d8
+requires_chi: ">= 0.9.0"

data/lib/samagotchi/bundles/skills/plugin.rb

@@ -13,13 +13,20 @@
 # shows a line: "skill release updated (+2 −1): …" or "skill release saved
 # (project, 14 lines)".
 #
+# A skill read in this turn is also watched for changes made some other way
+# (an execute running sed, a script): after each other tool call, and at the
+# turn's end, its file is compared with the content last seen (at the read,
+# or after the last write above); a change keeps that content as a version,
+# shows the same line and counts as the skill updated.
+#
 # The nudge (nudge: true), for models that skip a failing step instead of
 # fixing the skill: in a turn that read a skill (memory_read of a skill_*
 # name, or a read of its file), the first failing tool call after it (an
 # execute with "exit: N", N ≠ 0, or with no exit line an Error: line near
 # the top; any tool's "[tool] Error: …") steers the model once to find out
-# why and fix the skill. At the turn's end, a failed step with no rewrite of
-# the skill gets a notice line.
+# why and fix the skill, unless a skill read was changed already (by any
+# tool, see above). At the turn's end, a failed step with no change to a
+# skill read gets a notice line.
 #
 # Settings (config.yml, bundles: skills:):
 #   history_keep: 20   older versions kept per skill
@@ -31,13 +38,11 @@ class Plugin
   WRITE_TOOLS = %w[memory_write write edit].freeze
   NOTICE_WIDTH = 60 # the changed line in an update's notice
   NUDGE = "A step of skill %s failed. Find out why before skipping it; if the skill is out of date, fix it now: " \
-          "memory_write the whole skill, its title and every section as they were, that step fixed, a Changelog " \
-          "line added."
+          "edit the step that changed in its file (or memory_write the whole skill) and add a Changelog line."
   NOT_FAILURES = %w[memory_read memory_write].freeze
   USAGE = "usage: /skill save [name] [--system] | list | show <name> | diff <name> [N]"
 
   def initialize(settings = {})
-    settings = {} unless settings.is_a?(Hash)
     @history_keep = positive(settings["history_keep"]) || 20
     @nudge = settings.key?("nudge") ? settings["nudge"] != false : true
     @stash = nil
@@ -79,16 +84,38 @@ class Plugin
   def after_tool_call(event, ctx)
     stash = @stash
     @stash = nil
-    step_failed(event) if @nudge && !@read.empty?
-    return unless stash && stash[:tool] == event[:tool].to_s
+    stash = nil unless stash && stash[:tool] == event[:tool].to_s
+    changed_elsewhere(ctx) unless stash
+    step_failed(event, ctx) if @nudge && !@read.empty?
+    return unless stash
 
     now = File.file?(stash[:path]) ? File.read(stash[:path]) : nil
     return if now.nil? || now == stash[:old]
 
-    @written << stash[:name]
+    @written |= [stash[:name]]
+    @seen[stash[:name]] = { path: stash[:path], scope: stash[:scope], content: now }
     ctx.notify(change_notice(stash, now))
   end
 
+  # A skill read this turn whose file differs from the content last seen was
+  # changed by something other than the write tools (an execute's sed, say):
+  # keep what was there as a version, show the change, count the skill as
+  # updated (any change counts, the user's own edit too). A file gone since
+  # is left alone.
+  def changed_elsewhere(ctx)
+    @seen.each do |name, seen|
+      now = File.file?(seen[:path]) ? File.read(seen[:path]) : nil
+      next if now.nil? || now == seen[:content]
+
+      keep_version(ctx, seen[:scope], name, seen[:content]) if seen[:content]
+      ctx.notify(change_notice({ name: name, scope: seen[:scope], old: seen[:content] }, now))
+      seen[:content] = now
+      @written |= [name]
+    end
+  rescue SystemCallError => e
+    ctx.log.warn(:watch_failed, error: e.class.name, msg: e.message)
+  end
+
   def change_notice(stash, now)
     name = stash[:name]
     return "skill #{name} saved (#{stash[:scope]}, #{now.lines.size} lines)" unless stash[:old]
@@ -105,31 +132,52 @@ class Plugin
 
   def reset_turn
     @read = []      # skills read this turn, in order
+    @seen = {}      # of those, name => {path:, scope:, content:} last seen
     @written = []   # skills changed this turn
     @failed = false # a step failed after a skill was read
     @nudged = false
   end
 
   def note_read(tool, event)
-    names = case tool
+    found = case tool
             when "memory_read"
+              scope = event.dig(:call, :scope).to_s.strip
+              scope = nil unless memory_dirs.key?(scope)
+              # A skill not written yet is watched where memory_write would
+              # put it by default: the read scope, else project.
               event.dig(:call, :content).to_s.split(",").map(&:strip).select { |entry| entry.start_with?("skill_") }
-                   .filter_map { |entry| skill_name(entry) }
+                   .filter_map do |entry|
+                     name = skill_name(entry) or next
+                     unwritten = File.join(memory_dirs[scope || "project"], "skill_#{name}.md")
+                     [name, skill_path(name, scope: scope) || unwritten]
+                   end
             when "read"
-              Array(event.dig(:targets, :paths)).filter_map { |path| skill_at(path)&.last }
+              Array(event.dig(:targets, :paths)).filter_map { |path| (at = skill_at(path)) && [at.last, path] }
             else []
             end
-    @read |= names
+    found.each { |name, path| watch(name, path) }
+    @read |= found.map(&:first)
+  end
+
+  # Remember a read skill's content (nil: not written yet) the first time in
+  # a turn: a later read mustn't hide a change made in between.
+  def watch(name, path)
+    return if @seen.key?(name) || path.nil?
+
+    content = File.file?(path) ? File.read(path) : nil
+    @seen[name] = { path: File.expand_path(path), scope: skill_at(path)&.first, content: content }
+  rescue SystemCallError
+    nil
   end
 
-  def step_failed(event)
+  def step_failed(event, ctx)
     tool = event[:tool].to_s
     return if NOT_FAILURES.include?(tool) || !failure?(tool, event[:output].to_s)
 
     @failed = true
-    return if @nudged
+    return if @nudged || @read.any? { |name| @written.include?(name) }
 
-    @nudged = !!event[:steer]&.call(format(NUDGE, @read.join(", ")))
+    @nudged = ctx.steer(format(NUDGE, @read.join(", ")))
   end
 
   # A tool error ("[x] Error: …" raised, "[x]\nError: …" returned), or an
@@ -146,6 +194,7 @@ class Plugin
   end
 
   def after_turn(ctx)
+    changed_elsewhere(ctx)
     return unless @nudge && @failed
 
     missed = @read - @written
@@ -166,8 +215,7 @@ class Plugin
 
     stamp = Time.now.utc.strftime("%Y%m%dT%H%M%S.%6NZ")
     path = File.join(dir, "#{stamp}.md")
-    File.write("#{path}.tmp", content)
-    File.rename("#{path}.tmp", path)
+    Samagotchi::AtomicFile.write(path, content)
     versions(dir).drop(@history_keep).each { |old| File.delete(old) }
   rescue SystemCallError => e
     ctx.log.warn(:history_failed, skill: name, error: e.class.name, msg: e.message)

data/lib/samagotchi/bundles/source-links/hooks/source_links.rb

@@ -92,7 +92,6 @@ class SourceLinks
   end
 
   def initialize(settings = {})
-    settings = {} unless settings.is_a?(Hash)
     @sources = compile_sources(settings["sources"])
     max = settings["max"].to_i
     @max = max.positive? ? max : DEFAULT_MAX

data/lib/samagotchi/bundles/source-links/manifest.yml

@@ -1,6 +1,6 @@
 ---
 name: source-links
-version: 0.3.0
+version: 0.3.1
 scope: system
 description: Links source refs (JIRA tickets, GitHub issues, …) in the model's answer — inline links in the web, and a one-line note after the turn (note false turns it off); sources are configured patterns
 trust_level: reviewed
@@ -8,7 +8,7 @@ files:
   source_links.md: sha256:aebd37f1e25491780994ecc4afc20ed6e8db32b724dc038302bb050177efada8
 hooks:
   source_links.rb:
-    sha256: sha256:0ee86a932efc90d81777855c81dea16510710d7371fe8b6b146a5a16b29794c2
+    sha256: sha256:574ea0c2b36f80dde410c4251753d70cbeea081d129f3f3547f41370e3990993
     event: after_turn
     on_error: log
     priority: 90

data/lib/samagotchi/bundles/system/config_modification_protocol.md

@@ -113,7 +113,7 @@ bundles:
 
 A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cover every MCP tool; see `docs/guardrails.md`. The mcp bundle saves each server's tool list in `$XDG_STATE_HOME/samagotchi/plugins/mcp/tools-<server>.json` (keyed by a digest of command/env/cwd): a changed server config is picked up by the next session start, which shows "Starting MCP server x (config changed, …)".
 
-**Preservation rule**: `ConfigFile.write_default_model!` and `ConfigFile.write_model_alias!` both load raw YAML (including nested sections and maps), mutate one key (`raw_data["default"]["model"] = ...` for new form), write atomically via `tmp`+`rename`. Never overwrite the file with only scalar keys — that would clobber `hooks:` / `model_aliases:` / `hosts:` / `recap:` / `guardrails:` / `bundles:`.
+**Preservation rule**: `ConfigFile.write_default_model!` and `ConfigFile.write_model_alias!` (`/model --default`, `/model --alias`) change one key on its own line of the text (`ConfigTextEdit`: the user's comments and layout stay; a new key goes at the end of its section, a missing section at the end of the file), check that the result parses to the old data plus that key (else they dump the whole file from it), and write through `AtomicFile` (a unique temp file renamed over config.yml, through a symlink, keeping its mode). Never overwrite the file with only scalar keys — that would clobber `hooks:` / `model_aliases:` / `hosts:` / `recap:` / `guardrails:` / `bundles:`.
 
 ## Workflow for any config edit
 
@@ -121,7 +121,7 @@ A guardrail rule's `tool:` may be a glob (`tool: "mcp_*"`, verdict `ask`) to cov
 2. `YAML.safe_load` (permitted_classes: [], aliases: false). If data nil or not Hash, treat as `{}` or raise with path.
 3. Mutate the intended **nested** key in the raw hash. Preserve all other keys byte-for-byte where possible. Example for default model: `raw_data["default"] ||= {}; raw_data["default"]["model"] = "new-model"`.
 4. **Validate** (see below) before writing. Also run `Samagotchi::Config.validate_yaml_sections` — it returns one `config: unknown key '…' (did you mean '…'?)` per key chi doesn't read (every config-exposed `Config::ENTRIES` key is known as written, including the section-less `max_tool_output_chars` and `skip_agent_md`; names under `hosts:`/`models:`/`model_aliases:`/`hooks:`/`bundles:`/`memories:` are free-form, host and model entries are checked against `Config::MAP_ENTRY_KEYS`). An empty list means no warning at start.
-5. **Write atomically**: `FileUtils.mkdir_p(File.dirname(path))`, `File.write("#{path}.tmp", YAML.dump(raw_data))`, `File.rename("#{path}.tmp", path)`.
+5. **Write**: change only the lines you mean to, with the edit tool, so the user's comments and layout stay; `YAML.dump` of the whole hash drops every comment, so rewrite the file only when it has none worth keeping. From Ruby, write atomically with `Samagotchi::AtomicFile.write(path, text)` (a unique temp file renamed over it), never through a fixed `"#{path}.tmp"` that another chi may be writing at the same time.
 6. Nothing else to update: config.yml values are never copied into `ENV`, and every `Config.get` reads the file again when it changed, so the next read (and every worker started after the write) sees the new value with origin `:file`. What a running worker set up at its start (`hosts:`, guardrail rules, bundle settings) waits for its restart. CLI overrides (`--model`, `--recap-model`, …) win over the file until the process exits; a worker gets its spawner's CLI settings through its env (`Config.cli_env`).
 
 ## Validations

data/lib/samagotchi/bundles/system/identity.md

@@ -8,6 +8,6 @@
 - **Skills**: a skill is a memory named `skill_<name>` holding the steps of a repeatable task we did together (sections Steps, Gotchas, Changelog; `memory_write description:` says when to use it).
   When the user asks to keep how we did something ("let's memorize this", "save this as a skill", `/skill save`), write it right away with `memory_write` (project scope; system only when the user asks or it isn't about this project), then show it briefly.
   Before a task that a `skill_*` in the memory index matches, read it and follow it.
-  When a step turned out different (a renamed command, an extra step, a gotcha), update the skill in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line.
+  When a step turned out different (a renamed command, an extra step, a gotcha), update the skill in the same turn: `edit` those steps in its file (memory_write only to rewrite it all), keep the rest as it was, add a dated Changelog line.
   When a skill's step fails or its file/command is missing, find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask.
   While following a skill, when anything looks unexpected (a check fails, output differs from what a step says, a warning the skill doesn't mention): stop, don't improvise a fix, tell the user what you saw and ask how to go on. Read each command's whole output, including warnings, before the next step.

data/lib/samagotchi/bundles/system/manifest.yml

@@ -1,11 +1,11 @@
 ---
 name: samagotchi-system
-version: 0.8.1
+version: 0.10.0
 scope: system
 description: Default system memories — identity, self map, config modification protocol, memory guide and the delegated-session rules
 files:
-  identity.md: sha256:d6f40d5e44096537d337c4ffda86823446f8b59eb8b8cc47014e97ec16f019c9
+  identity.md: sha256:29c2f7df9f6c5acbc5ec17000a4490741e55e426af15ca0d81c8706edd9bd027
   self_map.md: sha256:93c788fadaf98adeb8946b4a357d2372bd6ebb439042d7cef8dda8fb44187315
-  config_modification_protocol.md: sha256:24e95727488daa80ac3008e020d8be098c7a1882153b7a61aba35450f72b86b7
-  memory_guide.md: sha256:50c076fb6bda7ed010877ff664bb2e9e904418fe08b058ebaa911d4e82e9a683
+  config_modification_protocol.md: sha256:d8bdf062d5afce7430ead7f49439c1d1ed197a6261dc69a7c884f4b814266b12
+  memory_guide.md: sha256:81b911b9a015f0924c48162b3dc4b6376309e743765074419a99fab46e480858
   delegated.md: sha256:0a71d5dfa7127df2d51cb5f0e7214240ed88777e36559430a8724c796d7ae561

data/lib/samagotchi/bundles/system/memory_guide.md

@@ -6,7 +6,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 
 - Plain Markdown files (`*.md`) stored outside the repo so they persist.
 - Loaded at startup into your system prompt as **Project memories** and **System memories** indexes (blank-name `memory_read`).
-- You manage them via tools, not shell file ops. On write, `index.md` is auto-maintained — do not edit it manually.
+- You manage them via tools (`memory_write`, or `edit` on a memory's file for a small change), not shell file ops. `index.md` is auto-maintained on every write — do not edit it manually.
 
 ## Scopes — where files live
 
@@ -16,7 +16,7 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 | `project` | `<system dir>/projects/<basename>_<hash>/` (`MemoryPaths.project_dir`: `basename(root)` + 8-char `MD5(root)`, root = `MemoryPaths.project_root`) | Repo-specific conventions, workflow, stack decisions |
 
 - The project root is the git repository: its common git dir, which every linked worktree shares. All worktrees and subdirectories of one repository share one project folder; the system prompt shows the resolved root and folder. Outside a repository the root is the working directory. A separate clone is a different project.
-- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write`.
+- `index.md` lives in each scope dir and contains auto-managed lines like `- **name** · scope · date · bytes — description`. Your free-form sections in `index.md` are preserved but managed lines are owned by `memory_write` (and refreshed when `write`/`edit` change a memory's file).
 
 ## Tools you have
 
@@ -34,7 +34,8 @@ This memory teaches you (the agent) how to use Samagotchi memories — persisten
 - `name` is the entry name **without** `.md` (the tool adds it). Use `name`, **not** `path` — `path` belongs to the file tools and is ignored here. `name: "index"` is a verbatim write to `index.md` (no auto-index update) — rarely needed.
 - `scope` is **required** — never omit. Prefer `project` for repo conventions, `system` for user preferences.
 - `description` is appended to the managed `index.md` line (`— description`). Replaces previous description if given; otherwise preserves existing one.
-- On success returns `Memory 'name' saved to <scope> scope (N bytes). Index updated: …` — confirm `bytes` and `scope`.
+- For a small change to an existing memory (a step, a line), `edit` its file instead of rewriting it all: the path is in `memory_write`'s result and the scope dirs are in the prompt. Its index line is refreshed either way.
+- On success returns `Memory 'name' saved to <scope> scope (N bytes). File written: <path> Index line refreshed automatically.` — confirm `bytes` and `scope`; the index needs nothing from you.
 
 **When to write:**
 - After learning a durable preference (e.g. commit style, test command, coding guideline) that the user confirmed or you observed repeatedly — ask before overwriting existing entries where appropriate.
@@ -67,7 +68,7 @@ Shape (plain Markdown, no frontmatter):
 - **Scope**: `project` by default; `system` when the user asks, or when the skill is clearly not about this project.
 - **Saving**: on a request to keep how something was done ("let's memorize this", "save this as a skill", `/skill save`), write it at once, then show it briefly. On an ambiguous one ("I like how we did that") you may ask whether to save it.
 - **Following**: before a task a `skill_*` index line matches, `memory_read` it and follow its steps. A step that fails or names a missing file or command: find out why (look around, read nearby READMEs) before skipping it; a step that says stop means stop and ask. When anything looks unexpected (a check fails, output differs from what a step says, a warning the skill doesn't mention): stop, don't improvise a fix, tell the user what you saw and ask. Read each command's whole output, including warnings, before the next step.
-- **Updating**: when a step turned out different, rewrite the skill with `memory_write` in the same turn: fix those steps, keep the rest as it was, add a dated Changelog line. No confirmation needed.
+- **Updating**: when a step turned out different, update the skill in the same turn: `edit` those steps in its file (`<scope dir>/skill_<name>.md`), or rewrite it with `memory_write`; keep the rest as it was, add a dated Changelog line. No confirmation needed.
 - **The `skills` bundle** (`chi bundle install skills`, optional) adds `/skill save [name] [--system]`, `/skill list`, `/skill show <name>`, `/skill diff <name> [N]`; it keeps older versions and shows a short diff line after each update.
 
 ## Memory Bundles — shareable packs

data/lib/samagotchi/cli/command.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module CLI
+    # The usage side of a subcommand: its error lines, usage errors (exit 2)
+    # and help. The including class sets @stdout and @stderr and defines
+    # #command_name ("chi send"); its usage text is USAGE unless it
+    # overrides #usage_text.
+    module Command
+      USAGE_EXIT = 2
+      HELP_WORDS = %w[-h --help help].freeze
+
+      private
+
+      def usage_text = self.class::USAGE
+
+      # What follows a usage error's line: the usage, or nil for a short
+      # "(see chi … --help)" at the end of the line instead.
+      def usage_on_error = usage_text
+
+      # stderr isn't buffered, stdout is when it's a pipe: flush the lines
+      # already printed, so the output keeps the order of the ids given.
+      def error_line(text)
+        @stdout.flush
+        @stderr.puts(text)
+      end
+
+      # @return [Integer] the usage exit status
+      def usage_error(message)
+        usage = usage_on_error
+        error_line("#{command_name}: #{message}#{usage ? "" : " (see #{command_name} --help)"}")
+        @stderr.puts(usage) if usage
+        USAGE_EXIT
+      end
+
+      # +argv+ through +flags+ (a Flags), help and usage errors done.
+      # @return [Flags::Result, Integer] the result, or the exit status
+      #   after the help (0) or a usage error (2)
+      def parse_flags(flags, argv, defaults = {})
+        parsed = flags.parse(argv, defaults)
+        if parsed.help
+          @stdout.puts(usage_text)
+          return 0
+        end
+        return usage_error(parsed.error.message) if parsed.error
+
+        parsed
+      end
+    end
+  end
+end

data/lib/samagotchi/cli/flags.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Samagotchi
+  module CLI
+    # A subcommand's flags as a table (the subcommands bin/chi dispatches
+    # before OptionParser): each flag's names, whether it takes a value
+    # ("--flag V", or "--flag=V" for a long name) and whether it repeats.
+    # #parse walks argv once, in order, and stops at the first help word or
+    # error; what isn't a flag is a positional argument.
+    #
+    #   FLAGS = CLI::Flags.new(help: %w[-h --help help]) do |f|
+    #     f.value "-m", "--message"
+    #     f.value "--image", key: :images, repeat: true
+    #     f.switch "--new"
+    #   end
+    #   FLAGS.parse(argv, images: []) # => Result
+    class Flags
+      Flag = Struct.new(:key, :value, :repeat, :set, :refusal, keyword_init: true)
+
+      # kind :unknown (an undeclared flag, a switch given =V, or a
+      # positional where none are taken), :missing (a value flag with no
+      # value after it) or :refused (a flag declared with #refuse); +arg+ is
+      # the argument as given.
+      Error = Data.define(:kind, :arg, :refusal) do
+        def message
+          case kind
+          when :unknown then "unknown option #{arg}"
+          when :missing then "#{arg} needs a value"
+          else refusal
+          end
+        end
+      end
+
+      # +options+ by key, +args+ the positionals in order; +help+ true when
+      # a help word stopped the parse; +error+ nil or an Error.
+      Result = Data.define(:options, :args, :help, :error)
+
+      # @param help [Array<String>] words that stop the parse with help
+      #   (not when they are a flag's value)
+      # @param flag_pattern [Regexp] what an undeclared flag looks like (an
+      #   unknown option); other arguments are positionals
+      # @param dash_values [Boolean] false: a value flag followed by a
+      #   "--…" argument has no value
+      # @param args [Boolean] false: a positional is an unknown option
+      def initialize(help: [], flag_pattern: /\A-/, dash_values: true, args: true)
+        @help = help
+        @flag_pattern = flag_pattern
+        @dash_values = dash_values
+        @args = args
+        @flags = {}
+        yield self if block_given?
+      end
+
+      # A flag without a value: options[key] = +set+. The key defaults to
+      # the last name without its dashes, snake_cased.
+      def switch(*names, key: nil, set: true)
+        add(names, Flag.new(key: key, value: false, set: set))
+      end
+
+      # A flag with a value; +repeat+: options[key] collects them in an array.
+      def value(*names, key: nil, repeat: false)
+        add(names, Flag.new(key: key, value: true, repeat: repeat))
+      end
+
+      # A flag that is an error, with +message+ (a flag that doesn't exist
+      # on purpose).
+      def refuse(*names, message)
+        add(names, Flag.new(refusal: message))
+      end
+
+      # @param defaults [Hash] the options before any flag (not changed)
+      # @return [Result]
+      def parse(argv, defaults = {})
+        options = defaults.dup
+        args = []
+        rest = argv.dup
+        until rest.empty?
+          arg = rest.shift
+          return Result.new(options: options, args: args, help: true, error: nil) if @help.include?(arg)
+
+          name, inline = arg.start_with?("--") && arg.include?("=") ? arg.split("=", 2) : [arg, nil]
+          flag = @flags[name]
+          flag = nil if inline && !flag&.value
+          unless flag
+            return failure(options, args, :unknown, arg) if !@args || arg.match?(@flag_pattern)
+
+            args << arg
+            next
+          end
+          return failure(options, args, :refused, arg, flag.refusal) if flag.refusal
+          next options[flag.key] = flag.set unless flag.value
+
+          unless inline
+            return failure(options, args, :missing, arg) if rest.empty? || (!@dash_values && rest.first.start_with?("--"))
+
+            inline = rest.shift
+          end
+          options[flag.key] = flag.repeat ? [*options[flag.key], inline] : inline
+        end
+        Result.new(options: options, args: args, help: false, error: nil)
+      end
+
+      private
+
+      def add(names, flag)
+        flag.key ||= names.last.sub(/\A-+/, "").tr("-", "_").to_sym unless flag.refusal
+        names.each { |name| @flags[name] = flag }
+        self
+      end
+
+      def failure(options, args, kind, arg, refusal = nil)
+        Result.new(options: options, args: args, help: false, error: Error.new(kind: kind, arg: arg, refusal: refusal))
+      end
+    end
+  end
+end