space-architect 9.1.1 → 9.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 154e74a35cc7d14274f2f6fec65f40400727adbf3ce4bcf69000c2f00405a07e
-  data.tar.gz: 2d6407b32a61f8c056e866e12dceab65b6a0b35f281ec6b1721c73233517da49
+  metadata.gz: ec005bf012468954875cbbd74a2c3d3a4d2fbc2468523f42ec425777a6e9344a
+  data.tar.gz: c93720a06c24e62ed03352c243d78a9895c1d98311547b9860e0ad549eea382f
 SHA512:
-  metadata.gz: db472c7ffcff0c4228f9c6bda1baad0c00cb0283defa3a686924267d51d252b9f24e3cdf65a8d50076f0354f5af1894ff6ff9799c2b783069a8bf52567206c2b
-  data.tar.gz: 444e06a1bbcbefe3f827a065cefba6383d04606215abf0ab016069f7b254a8c61d2343aa91a648a3a2be92ae1a47c97b18dbcdc63bb62a92d23c63b3b8b10e6f
+  metadata.gz: 416269e2e0d4a3fab56cfd8a3cf5f8afdc63db75ad0b49982e98724fb0eaca66f85970f9c86f07901a543eb198405840c460464e5cb1491fd9d1eaafb9b3624b
+  data.tar.gz: 1ba4e232aeb7bdea2670fce2864bf4db7484cc60940ec4f242d3744f393f1082592adab9ac422ef39d6f870bcedd7c6cc89c78770d6409ebf9676f1ea01fa120

data/lib/space_architect/architect_project.rb

@@ -560,25 +560,24 @@ module Space::Architect
       gates = parse_gates(text)
       raise Space::Core::Error, "no gate commands found in the frozen Acceptance Criteria of #{rel}" if gates.empty?
 
-      lanes = entry["lanes"] || []
-      repo_root = nil
-      base_dir =
-        if lane
-          le = lanes.find { |l| l["name"] == lane }
-          raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless le
-          le = ensure_lane_materialized(iteration, lane)
-          repo_root = le["repo"] ? space.path.join("repos", le["repo"]) : nil
-          space.path.join(le["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt")
-        else
-          repo = lanes.first&.dig("repo")
-          raise Space::Core::Error, "No lane/repo recorded for '#{iteration}' — cannot resolve a directory to run gates in" unless repo
-          space.path.join("repos", repo)
-        end
+      entry, base_dir, repo = resolve_gate_run(iteration, lane)
+      repo_root = lane && repo ? space.path.join("repos", repo) : nil
       raise Space::Core::Error, "directory does not exist: #{base_dir}" unless base_dir.exist?
 
       execute_gates(gates, base_dir: base_dir, lane: lane, repo_root: repo_root)
     end
 
+    # I07: the gate-side transcript — one durable file under build/gate/ per
+    # gate run, so a judge reading whole gates never depends on a terminal tail
+    # (agent runners read the last lines; the file is the record read whole).
+    # Re-slices the entry itself and re-resolves the run directory exactly as
+    # #run_gates does — a no-op when the Gate CLI composes it right after
+    # #run_gates, the only intended caller shape. Returns the path.
+    def gate_transcript(iteration, gate_results, lane: nil, now: Time.now)
+      entry, base_dir, repo = resolve_gate_run(iteration, lane)
+      write_transcript(:gate, entry, repo, base_dir, lane, gate_results, nil, now)
+    end
+
     # Rehearse the DRAFTED gates in the WORKING-TREE iteration file — before the
     # freeze, while they can still be fixed — through the identical execution
     # path #run_gates uses at judge time (#execute_gates). space.yaml records no
@@ -1270,22 +1269,40 @@ module Space::Architect
       end
     end
 
-    # I01: the durable, unbounded counterpart to the CLI's bounded terminal
-    # report — one file per non-EMPTY rehearsal under build/rehearse/, holding
-    # every gate's full command, dir, exit code, verdict, reason, and complete
-    # stdout+stderr, plus the scope-asymmetry findings. The CLI prints this
-    # path so a rerun is never needed just to see output the terminal trimmed.
+    # I01 + I07: the durable, unbounded counterpart to the CLI's bounded terminal
+    # report — one file per run under build/rehearse/ (rehearse) or build/gate/
+    # (gate), holding every gate's full command, dir, exit code, verdict, reason,
+    # and complete stdout+stderr. ONE writer, parameterized by kind: rehearse
+    # additionally carries the scope-asymmetry findings and its RED/GREEN/BROKEN
+    # verdict; gate carries the mechanical PASS/FAIL and no scope section — but
+    # the per-gate emission is shared code, so the two transcripts can never drift.
+    TRANSCRIPT_KINDS = {
+      rehearse: { subdir: "rehearse", header: "Rehearsal transcript" },
+      gate:     { subdir: "gate",     header: "Gate transcript" }
+    }.freeze
+
     def write_rehearsal_transcript(entry, repo, base_dir, gate_results, scope_report, now)
-      dir  = space.path.join("build", "rehearse")
+      write_transcript(:rehearse, entry, repo, base_dir, nil, gate_results, scope_report, now)
+    end
+
+    def write_transcript(kind, entry, repo, base_dir, lane, gate_results, scope_report, now)
+      spec = TRANSCRIPT_KINDS.fetch(kind)
+      dir  = space.path.join("build", spec[:subdir])
       FileUtils.mkdir_p(dir)
       path = dir.join("#{iteration_id(entry)}-#{now.strftime('%Y%m%dT%H%M%S.%6N')}.md")
 
-      lines = ["# Rehearsal transcript — #{entry['name']} — #{now.iso8601}"]
-      lines << (repo ? "Repo: #{repo} (#{base_dir})" : "Each gate ran in its own declared cwd")
+      lines = ["# #{spec[:header]} — #{entry['name']} — #{now.iso8601}"]
+      lines << if lane
+                 "Lane: #{lane} (#{base_dir})"
+               elsif repo
+                 "Repo: #{repo} (#{base_dir})"
+               else
+                 "Each gate ran in its own declared cwd"
+               end
 
       gate_results.each do |g|
         lines << ""
-        lines << "## #{g[:ac].empty? ? "(gate)" : g[:ac]} #{g[:id]} — #{g[:rehearsal].to_s.upcase} (exit #{g[:exit_code].inspect})"
+        lines << "## #{g[:ac].empty? ? "(gate)" : g[:ac]} #{g[:id]} — #{transcript_verdict(kind, g)} (exit #{g[:exit_code].inspect})"
         lines << "cmd: #{g[:cmd]}"
         lines << "dir: #{g[:dir]}"
         lines << "reason: #{g[:reason]}" unless g[:reason].to_s.empty?
@@ -1315,6 +1332,37 @@ module Space::Architect
       path
     end
 
+    # rehearse reports the RED/GREEN/BROKEN discrimination verdict per gate;
+    # gate reports the mechanical PASS/FAIL.
+    def transcript_verdict(kind, g)
+      if kind == :rehearse
+        g[:rehearsal].to_s.upcase
+      else
+        g[:status] == :pass ? "PASS" : "FAIL"
+      end
+    end
+
+    # WHERE gates run for an iteration — shared by #run_gates and
+    # #gate_transcript so the two can never disagree about it: the lane worktree
+    # when a lane is given (materialized on demand), else the integration repo
+    # checkout. Returns [entry, base_dir, repo_name] — repo_name is the run's
+    # repo (the lane's declared repo, else the first recorded lane's), nil only
+    # for a lane run in a repo-less lane.
+    def resolve_gate_run(iteration, lane)
+      entry = slice_entry(iteration)
+      lanes = entry["lanes"] || []
+      if lane
+        le = lanes.find { |l| l["name"] == lane }
+        raise Space::Core::Error, "No lane '#{lane}' recorded for iteration '#{iteration}'" unless le
+        le = ensure_lane_materialized(iteration, lane)
+        [entry, space.path.join(le["worktree"] || "build/#{iteration_id(entry)}-#{lane}/wt"), le["repo"]]
+      else
+        repo = lanes.first&.dig("repo")
+        raise Space::Core::Error, "No lane/repo recorded for '#{iteration}' — cannot resolve a directory to run gates in" unless repo
+        [entry, space.path.join("repos", repo), repo]
+      end
+    end
+
     # I09/AC4, #90/AC5-AC6: resolve the repo to default for gates that declare no
     # `cwd` of their own — only those gates need one, and only they are ambiguous
     # when the drafted ```lanes``` block names more than one repo. A gate with its

data/lib/space_architect/cli/architect.rb

@@ -6,6 +6,10 @@ require_relative "../jobs_client"
 require_relative "../conversations_client"
 require_relative "../loop_cost"
 require_relative "../session_sync"
+require_relative "../runlog"
+require_relative "../looplog"
+require_relative "../extension_installer"
+require_relative "../space_push"
 
 module Space::Architect
   module CLI
@@ -211,6 +215,41 @@ module Space::Architect
         end
       end
 
+      class Push < BaseCommand
+        desc "Pack the current space and push it to a space-server for import"
+        phase 53, "Project"
+        argument :space, required: false, desc: "Space identifier (default: $PWD)"
+        option :host,  required: true, desc: "Base URL of the space-server"
+        option :token, required: true, desc: "Bearer token for authorization"
+
+        def call(space: nil, host: nil, token: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            raise Space::Core::Error, "--host is required" unless host
+            raise Space::Core::Error, "--token is required" unless token
+
+            render(store.find(space)) do |sp|
+              bundle = SpacePush::Packer.new(sp.path).pack
+              begin
+                terminal.say "Packed #{sp.id}: #{format_bytes(File.size(bundle))}"
+                summary = SpacePush.new(host, token).push(bundle)
+                terminal.say "Imported: #{summary['slug']} (id #{summary['id']}) — " \
+                  "#{summary['iterations']} iterations, #{summary['artifacts']} artifacts, #{summary['runs']} runs"
+                CLI.record_outcome(Outcome.new(exit_code: 0))
+              ensure
+                File.delete(bundle)
+              end
+            end
+          end
+        end
+
+        private
+
+        def format_bytes(size)
+          format("%.1f MiB", size.to_f / (1024 * 1024))
+        end
+      end
+
       class Sync < BaseCommand
         desc "Sync tracked repo clones with their remotes (fast-forward only, no rebase/reset)"
         phase 53, "Project"
@@ -230,7 +269,57 @@ module Space::Architect
         end
       end
 
+      # I07: the bounded per-gate terminal report, shared byte-for-byte by
+      # rehearse and gate — one identity line per gate, at most
+      # OUTPUT_LINE_CAP lines of tail output, and a pointer at the transcript
+      # that holds the rest (the same one-instrument discipline as
+      # #execute_gates below the CLI). The verdict label, the reason
+      # visibility, and any verdict-specific advisory are hooks; everything
+      # else — identity line shape, dir line, output elision — is shared so the
+      # two commands can never drift.
+      module GateRendering
+        # Identity (AC label, gate id, verdict, exit code) always lands on one
+        # stdout line, however many lines `cmd` spans — the command itself is
+        # shown as at most its first line, truncated; the full command lives
+        # in the transcript.
+        CMD_LINE_MAX    = 100
+        OUTPUT_LINE_CAP = 20
+
+        def render_gate(g, transcript_path)
+          terminal.say ""
+          terminal.say "── #{g[:ac].empty? ? "(gate)" : g[:ac]} #{g[:id]}: #{truncated_cmd(g[:cmd])}  (exit #{g[:exit_code].inspect})  [#{gate_verdict(g)}]"
+          terminal.say "   dir: #{terminal.path(g[:dir])}"
+          terminal.say "   reason: #{g[:reason]}" if gate_reason_visible?(g) && !g[:reason].to_s.empty?
+          if g[:shared_with]&.any?
+            terminal.say "   shared execution with: #{g[:shared_with].join(', ')} (identical cmd+dir, captured once)"
+          end
+          render_gate_extras(g)
+          render_gate_output(g, transcript_path)
+        end
+
+        def truncated_cmd(cmd)
+          first, *rest = cmd.to_s.each_line.map(&:chomp)
+          clipped = first.length > CMD_LINE_MAX ? "#{first[0, CMD_LINE_MAX]}…" : first
+          rest.any? || clipped != first ? "#{clipped} …" : clipped
+        end
+
+        def render_gate_output(g, transcript_path)
+          combined = [g[:stdout], g[:stderr]].map { |s| s.to_s.rstrip }.reject(&:empty?).join("\n")
+          return if combined.empty?
+
+          lines = combined.lines(chomp: true)
+          if lines.size > OUTPUT_LINE_CAP
+            terminal.say lines.last(OUTPUT_LINE_CAP).join("\n")
+            terminal.say "   … #{lines.size - OUTPUT_LINE_CAP} more line(s) elided — full output in #{terminal.path(transcript_path)}"
+          else
+            terminal.say lines.join("\n")
+          end
+        end
+      end
+
       class Rehearse < BaseCommand
+        include GateRendering
+
         desc "Rehearse the DRAFTED (unfrozen, working-tree) gates against the repo checkout and report RED/GREEN/BROKEN/EMPTY — runs and reports, never judges"
         phase 12, "Spec"
         argument :iteration, required: true,  desc: "Iteration name"
@@ -283,6 +372,20 @@ module Space::Architect
           "Discrimination report only — this runs and reports; it never judges whether these gates are good, bad, or ready."
         end
 
+        # GateRendering hooks: rehearse renders the RED/GREEN/BROKEN verdict,
+        # shows a gate's reason whenever one exists, and adds the BROKEN
+        # advisory — everything else comes from the shared concern.
+        def gate_verdict(g) = g[:rehearsal].to_s.upcase
+
+        def gate_reason_visible?(g) = true
+
+        def render_gate_extras(g)
+          return unless g[:rehearsal] == :broken
+
+          terminal.say "   BROKEN is advisory, not certain — a correct RED can look broken (e.g. a file the lane " \
+            "hasn't written yet). Confirm before treating it as a defect."
+        end
+
         # #90/AC7: with a single defaultable repo, name it as before; a cross-repo
         # run (or one where every gate declares its own `cwd`) has no one repo to
         # name — each gate's own "dir:" line (below) already says where it ran.
@@ -294,47 +397,6 @@ module Space::Architect
           end
         end
 
-        # I01/AC "bounded terminal report": identity (AC label, gate id, verdict,
-        # exit code) always lands on one stdout line, however many lines `cmd`
-        # spans — the command itself is shown as at most its first line,
-        # truncated; the full command lives in the transcript.
-        CMD_LINE_MAX    = 100
-        OUTPUT_LINE_CAP = 20
-
-        def render_gate(g, transcript_path)
-          terminal.say ""
-          terminal.say "── #{g[:ac].empty? ? "(gate)" : g[:ac]} #{g[:id]}: #{truncated_cmd(g[:cmd])}  (exit #{g[:exit_code].inspect})  [#{g[:rehearsal].to_s.upcase}]"
-          terminal.say "   dir: #{terminal.path(g[:dir])}"
-          terminal.say "   reason: #{g[:reason]}" unless g[:reason].to_s.empty?
-          if g[:shared_with]&.any?
-            terminal.say "   shared execution with: #{g[:shared_with].join(', ')} (identical cmd+dir, captured once)"
-          end
-          if g[:rehearsal] == :broken
-            terminal.say "   BROKEN is advisory, not certain — a correct RED can look broken (e.g. a file the lane " \
-              "hasn't written yet). Confirm before treating it as a defect."
-          end
-          render_gate_output(g, transcript_path)
-        end
-
-        def truncated_cmd(cmd)
-          first, *rest = cmd.to_s.each_line.map(&:chomp)
-          clipped = first.length > CMD_LINE_MAX ? "#{first[0, CMD_LINE_MAX]}…" : first
-          rest.any? || clipped != first ? "#{clipped} …" : clipped
-        end
-
-        def render_gate_output(g, transcript_path)
-          combined = [g[:stdout], g[:stderr]].map { |s| s.to_s.rstrip }.reject(&:empty?).join("\n")
-          return if combined.empty?
-
-          lines = combined.lines(chomp: true)
-          if lines.size > OUTPUT_LINE_CAP
-            terminal.say lines.last(OUTPUT_LINE_CAP).join("\n")
-            terminal.say "   … #{lines.size - OUTPUT_LINE_CAP} more line(s) elided — full output in #{terminal.path(transcript_path)}"
-          else
-            terminal.say lines.join("\n")
-          end
-        end
-
         # I12/AC3-AC4: reports scope asymmetry only — never affects RED/GREEN/
         # BROKEN, rehearse's exit code, or the stamp. A file outside every
         # declared lane's touch set is flagged loudest: it's the one no lane
@@ -759,6 +821,8 @@ module Space::Architect
       end
 
       class Gate < BaseCommand
+        include GateRendering
+
         desc "Run the frozen Acceptance Criteria gate commands and report PASS/FAIL"
         phase 32, "Judge"
         argument :iteration, required: true,  desc: "Iteration name"
@@ -771,22 +835,29 @@ module Space::Architect
             render(store.find(space)) do |sp|
               project = ArchitectProject.new(space: sp)
               results = project.run_gates(iteration, lane: lane)
-              results.each do |r|
-                marker = r[:status] == :pass ? "PASS" : "FAIL"
-                terminal.say ""
-                terminal.say "── #{r[:ac].empty? ? "(gate)" : r[:ac]}: #{r[:cmd]}  (exit #{r[:exit_code]})  [#{marker}]"
-                terminal.say "   dir: #{terminal.path(r[:dir])}"
-                terminal.say "   reason: #{r[:reason]}" if r[:status] == :fail && !r[:reason].to_s.empty?
-                terminal.say r[:stdout].rstrip unless r[:stdout].strip.empty?
-                terminal.say r[:stderr].rstrip unless r[:stderr].strip.empty?
-              end
+              # I07: the Gate CLI composes run_gates + gate_transcript — the
+              # transcript is the durable record a judge reads whole, so the
+              # bounded terminal output can always point at it.
+              transcript = project.gate_transcript(iteration, results, lane: lane)
+              results.each { |r| render_gate(r, transcript) }
               terminal.say ""
               terminal.say "Mechanical gate results above; the Acceptance-Criteria verdict — necessary, not sufficient — remains the architect's."
+              terminal.say "transcript: #{terminal.path(transcript)}"
               any_fail = results.any? { |r| r[:status] == :fail }
               CLI.record_outcome(Outcome.new(exit_code: any_fail ? 1 : 0))
             end
           end
         end
+
+        private
+
+        # GateRendering hooks: gate renders the mechanical verdict, shows the
+        # reason only on a fail, and adds no advisory of its own.
+        def gate_verdict(g) = g[:status] == :pass ? "PASS" : "FAIL"
+
+        def gate_reason_visible?(g) = g[:status] == :fail
+
+        def render_gate_extras(g) = nil
       end
 
       class BugReport < BaseCommand
@@ -819,6 +890,56 @@ module Space::Architect
         end
       end
 
+      # Pretty-print a pi agent run.jsonl as it streams — the ported runlog
+      # printer. No space resolution: the stream is the whole input.
+      class Runlog < BaseCommand
+        desc "Pretty-print a pi agent run.jsonl as it streams (thinking dim, tool calls one-lined)"
+        phase 54, "Project"
+        argument :file, required: false, desc: "run.jsonl to read (default: stdin)"
+
+        def call(file: nil, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            if file
+              begin
+                File.open(file) { |f| Space::Architect::Runlog.stream(input: f, io: out, env: project_config.env) }
+              rescue Errno::ENOENT
+                raise Space::Core::Error, "file not found: #{file}"
+              end
+            else
+              Space::Architect::Runlog.stream(input: $stdin, io: out, env: project_config.env)
+            end
+            CLI.record_outcome(Outcome.new(exit_code: 0))
+          end
+        end
+      end
+
+      # Follow every active pi-subagents run transcript in a space, live — the
+      # ported looplog follower. BLOCKS until ctrl+c (quiet exit).
+      class Looplog < BaseCommand
+        desc "Follow every active pi-subagents run in this space, live (--list inventories only)"
+        phase 54, "Project"
+        argument :space, required: false, desc: "Space identifier (default: nearest ancestor with space.yaml)"
+        option :list,   type: :flag, default: false, desc: "Inventory only — one line per run (active/age/size/agent/task), no follow"
+        option :replay, type: :flag, default: false, desc: "Print existing history on adoption, then follow"
+        option :all,    type: :flag, default: false, desc: "Adopt every transcript, however stale (default: only within LOOPLOG_WINDOW seconds)"
+
+        def call(space: nil, list: false, replay: false, all: false, **opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            render(store.find(space)) do |sp|
+              if list
+                Space::Architect::Looplog.list(space: sp.path.to_s, io: out, env: project_config.env)
+              else
+                Space::Architect::Looplog.follow(space: sp.path.to_s, io: out, env: project_config.env,
+                                                 replay: replay, all: all)
+              end
+              CLI.record_outcome(Outcome.new(exit_code: 0))
+            end
+          end
+        end
+      end
+
       # Read-only loop accounting: spend and speed from the pi session
       # artifacts already on disk (run metas + interactive/runner session
       # files), stdout only. All view math lives in LoopCost; this class only
@@ -1001,6 +1122,24 @@ module Space::Architect
         end
       end
 
+      # I07: install the architect-loop pi extension package via pi's own
+      # mechanics — the gem owns the standing declaration (PACKAGE_SOURCE), pi
+      # owns settings.json. No space resolution: a machine-level operation.
+      class InstallExtensions < BaseCommand
+        desc "Install the architect-loop pi extension package via pi (idempotent by pi's semantics)"
+        phase 53, "Project"
+
+        def call(**opts)
+          setup_terminal(**opts.slice(:color, :colors))
+          handle_errors do
+            result = ExtensionInstaller.install(env: project_config.env)
+            result[:steps].each { |s| terminal.say "  #{s[:cmd]} (exit #{s[:exit_code]})" }
+            terminal.say "Extensions source: #{result[:source]}"
+            CLI.record_outcome(Outcome.new(exit_code: 0))
+          end
+        end
+      end
+
       module Worktree
         class Add < BaseCommand
           desc "Create a worktree for a lane"
@@ -1444,6 +1583,7 @@ Space::Architect::CLI::Registry.register "init",   Space::Architect::CLI::Archit
 Space::Architect::CLI::Registry.register "ground", Space::Architect::CLI::Architect::Ground
 Space::Architect::CLI::Registry.register "new",    Space::Architect::CLI::Architect::New
 Space::Architect::CLI::Registry.register "status", Space::Architect::CLI::Architect::Status
+Space::Architect::CLI::Registry.register "push",   Space::Architect::CLI::Architect::Push
 Space::Architect::CLI::Registry.register "sync",   Space::Architect::CLI::Architect::Sync
 Space::Architect::CLI::Registry.register "rehearse", Space::Architect::CLI::Architect::Rehearse
 Space::Architect::CLI::Registry.register "freeze", Space::Architect::CLI::Architect::Freeze
@@ -1457,6 +1597,9 @@ Space::Architect::CLI::Registry.register "merge",     Space::Architect::CLI::Arc
 Space::Architect::CLI::Registry.register "integrate", Space::Architect::CLI::Architect::Integrate
 Space::Architect::CLI::Registry.register "gate",      Space::Architect::CLI::Architect::Gate
 Space::Architect::CLI::Registry.register "install-skills", Space::Architect::CLI::Architect::InstallSkills
+Space::Architect::CLI::Registry.register "install-extensions", Space::Architect::CLI::Architect::InstallExtensions
+Space::Architect::CLI::Registry.register "runlog",          Space::Architect::CLI::Architect::Runlog
+Space::Architect::CLI::Registry.register "looplog",         Space::Architect::CLI::Architect::Looplog
 Space::Architect::CLI::Registry.register "bug-report",     Space::Architect::CLI::Architect::BugReport
 Space::Architect::CLI::Registry.register "cost",           Space::Architect::CLI::Architect::Cost
 Space::Architect::CLI::Registry.register "brief" do |b|

data/lib/space_architect/extension_installer.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "open3"
+
+module Space
+  module Architect
+    # Installs the architect-loop pi extension package through pi's own
+    # mechanics. The gem owns the standing declaration (PACKAGE_SOURCE) and the
+    # two-step sequence; pi owns settings.json and the rest — idempotent by
+    # pi's semantics, safe to re-run.
+    module ExtensionInstaller
+      PACKAGE_SOURCE = "git:git@github.com:jetpks/pi-extensions.git"
+
+      class << self
+        # Runs `<pi_bin> install PACKAGE_SOURCE` then
+        # `<pi_bin> update --extension PACKAGE_SOURCE`, in order, aborting on
+        # the first failure. --extension (singular) on purpose: the gem
+        # reconciles exactly the package it declares — not the operator's other
+        # packages. Returns { source:, steps: [{cmd:, exit_code:, output:}] }.
+        def install(pi_bin: "pi", env: ENV)
+          steps = [
+            run_step(pi_bin, ["install", PACKAGE_SOURCE], env),
+            run_step(pi_bin, ["update", "--extension", PACKAGE_SOURCE], env)
+          ]
+          { source: PACKAGE_SOURCE, steps: steps }
+        end
+
+        private
+
+        def run_step(pi_bin, args, env)
+          cmd = [pi_bin, *args].join(" ")
+          out, err, status = Open3.capture3(env, pi_bin, *args)
+          output = out + err
+          raise Space::Core::Error, "#{cmd} failed (exit #{status.exitstatus}):\n#{output}" unless status.success?
+
+          { cmd: cmd, exit_code: status.exitstatus, output: output }
+        rescue Errno::ENOENT
+          raise Space::Core::Error,
+            "#{pi_bin}: command not found — '#{cmd}' could not run. Install pi or check your PATH."
+        end
+      end
+    end
+  end
+end