ace-lab 0.9.0 → 0.13.1

data/lib/ace/lab/cli/commands/prepare.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../organisms/prepare"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Prepare < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          # One shared section-namer map: the table renderer and the
+          # failure summary must name items identically.
+          SECTION_NAMERS = {
+            "accounts" => ->(item) { item["username"] },
+            "directories" => ->(item) { item["path"] },
+            "keys" => ->(item) { "#{item['account']}:#{item['path']}" },
+            "roles" => ->(item) { item["id"] },
+            "gems" => ->(item) { "#{item['name']} #{item['version']}" }
+          }.freeze
+
+          # "SHA256:" plus the first 20 base64 characters is enough to
+          # eyeball-match a key without ballooning the table row.
+          FINGERPRINT_WIDTH = 27
+
+          desc "Prepare accounts, directories, permissions, keys, roles and the declared " \
+            "gem set from the trusted install manifest"
+
+          example [
+            "--dry-run            # Predict all sections without mutating",
+            "--format json        # Machine-readable report"
+          ]
+
+          option :dry_run, type: :boolean, desc: "Predict changes without applying them"
+          option :format, type: :string, desc: "Output format (table, json; default: table)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(prepare: nil)
+            super()
+            @prepare = prepare
+          end
+
+          def call(**options)
+            format = options[:format] || "table"
+            unless %w[table json].include?(format)
+              raise Ace::Support::Cli::Error,
+                "--format \"#{format}\" is not supported; table or json"
+            end
+
+            organism = @prepare || Organisms::Prepare.new
+            report = organism.call(dry_run: options[:dry_run] || false)
+            render(report, format: format, quiet: options[:quiet])
+
+            # A wet run with failed items never exits 0: the report renders
+            # first, then the failure list names each item explicitly.
+            # Dry-run conflicts are predicted failures, not execution
+            # failures — exit 0 so callers can script a preview.
+            unless report["ok"] || report["dry_run"]
+              raise Ace::Support::Cli::Error, failure_summary(report)
+            end
+          rescue Ace::Lab::InvalidConfigurationError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def render(report, format:, quiet:)
+            return if quiet
+
+            puts format == "json" ? JSON.generate(report) : render_table(report)
+          end
+
+          def render_table(report)
+            lines = ["Machine: #{report['machine']}  manifest: #{report['manifest']}" \
+              "#{"  (dry run)" if report['dry_run']}"]
+            SECTION_NAMERS.each do |section, namer|
+              lines << "#{section.capitalize}:"
+              items = report[section]
+              if items.empty?
+                lines << "  (none declared)"
+              else
+                items.each do |item|
+                  detail = detail_for(section, item)
+                  lines << "  #{namer.call(item).to_s.ljust(34)} #{item['status']}#{detail}"
+                end
+              end
+            end
+            lines << "Result: #{report['ok'] ? 'ok' : 'FAILED'}"
+            lines.join("\n")
+          end
+
+          # Key rows render a truncated public fingerprint (never key
+          # material); everything else appends the message when present.
+          def detail_for(section, item)
+            parts = []
+            if section == "keys" && item["fingerprint"]
+              fingerprint = item["fingerprint"]
+              parts << (fingerprint.length <= FINGERPRINT_WIDTH ? fingerprint :
+                "#{fingerprint[0, FINGERPRINT_WIDTH]}…")
+            end
+            parts << item["message"] if item["message"]
+            parts.empty? ? "" : "  #{parts.join('  ')}"
+          end
+
+          def failure_summary(report)
+            failures = SECTION_NAMERS.flat_map do |section, namer|
+              report[section]
+                .select { |item| item["status"] == "failed" }
+                .map { |item| "#{section}/#{namer.call(item)}: #{item['message']}" }
+            end
+            "prepare failed (#{failures.size} item(s)): #{failures.join('; ')}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/project_add.rb

@@ -0,0 +1,101 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../organisms/project_add"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class ProjectAdd < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          SECTION_NAMERS = {
+            "repository" => ->(item) { item["path"] || item["location"] },
+            "overseer" => ->(item) { item["dir"] || item["location"] },
+            "registry" => ->(item) { item["path"] || item["location"] }
+          }.freeze
+
+          desc "Register a project and make it ready for team work " \
+            "(repository, private _overseer, lab config registry)"
+
+          example [
+            "atlas --path /Users/ace/lab/atlas --remote git@forge:atlas/atlas.git",
+            "atlas --path /Users/ace/lab/atlas --dry-run   # Predict without mutating",
+            "atlas --path /Users/ace/lab/atlas --format json"
+          ]
+
+          argument :id, type: :string, required: true, desc: "Project id (topology id)"
+
+          option :path, type: :string, required: true, desc: "Absolute project path"
+          option :remote, type: :string, desc: "Origin remote URL (git clone source)"
+          option :label, type: :string, desc: "Display label recorded in the registry"
+          option :dry_run, type: :boolean, desc: "Predict changes without applying them"
+          option :format, type: :string, desc: "Output format (table, json; default: table)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(project_add: nil)
+            super()
+            @project_add = project_add
+          end
+
+          def call(**options)
+            format = options[:format] || "table"
+            unless %w[table json].include?(format)
+              raise Ace::Support::Cli::Error,
+                "--format \"#{format}\" is not supported; table or json"
+            end
+
+            path = File.expand_path(options[:path])
+            organism = @project_add || Organisms::ProjectAdd.new
+            report = organism.call(
+              id: options[:id], path: path, remote: options[:remote],
+              label: options[:label], dry_run: options[:dry_run] || false
+            )
+            render(report, format: format, quiet: options[:quiet])
+
+            unless report["ok"] || report["dry_run"]
+              raise Ace::Support::Cli::Error, failure_summary(report)
+            end
+          rescue Ace::Lab::InvalidConfigurationError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def render(report, format:, quiet:)
+            return if quiet
+
+            puts format == "json" ? JSON.generate(report) : render_table(report)
+          end
+
+          def render_table(report)
+            lines = ["Project: #{report['project']}  path: #{report['path']}" \
+              "#{"  remote: #{report['remote']}" if report['remote']}" \
+              "#{"  (dry run)" if report['dry_run']}"]
+            SECTION_NAMERS.each do |section, namer|
+              lines << "#{section.capitalize}:"
+              item = report[section]
+              detail = item["message"] ? "  #{item['message']}" : ""
+              lines << "  #{namer.call(item).to_s.ljust(34)} #{item['status']}#{detail}"
+            end
+            lines << "Result: #{report['ok'] ? 'ok' : 'FAILED'}"
+            lines.join("\n")
+          end
+
+          def failure_summary(report)
+            failures = SECTION_NAMERS.map do |section, namer|
+              item = report[section]
+              next unless item["status"] == "failed"
+
+              "#{section}/#{namer.call(item)}: #{item['message']}"
+            end.compact
+            "project add failed (#{failures.size} step(s)): #{failures.join('; ')}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/status.rb

@@ -0,0 +1,109 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "support"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Status < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+          include Runtime
+
+          desc <<~DESC.strip
+            Show lab configuration and local file state (read-only)
+
+            Distinguishes a valid empty set, missing configuration, and a
+            source error. Reads files only: no services are started and no
+            installer is required. The enriched worktree view stays
+            ace-git-worktree list.
+          DESC
+
+          example ["--format json    # Full report as JSON"]
+
+          option :format, type: :string, default: "table", desc: "Output format: table or json"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(status_service: nil)
+            @status_service = status_service
+          end
+
+          def call(**options)
+            format = options[:format] || "table"
+            cli_error("Invalid format: #{format} (use table or json)") unless %w[table json].include?(format)
+
+            report = status_service.report
+            unless options[:quiet]
+              puts(format == "json" ? JSON.generate(report.to_h) : render_table(report))
+            end
+            # Full report first; source failures then fail the command
+            unless report.ok?
+              raise Ace::Support::Cli::Error, "lab status reported source errors: #{first_error(report)}"
+            end
+          end
+
+          private
+
+          def status_service
+            @status_service ||= Organisms::StatusService.from_config
+          end
+
+          def first_error(report)
+            report.config[:error] ||
+              report.runtime_config[:error] ||
+              report.state.find { |location| location[:state] == :error }&.dig(:note) ||
+              "unreadable state location"
+          end
+
+          def render_table(report)
+            [config_line(report), runtime_line(report), "Local state (root: #{report.root}):"]
+              .concat(report.state.map { |location| location_line(location) })
+              .join("\n")
+          end
+
+          def config_line(report)
+            config = report.config
+            case config[:state]
+            when :configured
+              "Lab configuration: configured — #{config[:source_path]} " \
+                "(topology: #{config[:topology][:projects]} project(s), " \
+                "#{config[:topology][:agents]} agent(s), #{config[:topology][:services]} service(s))"
+            when :defaults_only
+              "Lab configuration: missing (defaults only; no .ace/lab/config.yml or ~/.ace/lab/config.yml)"
+            else
+              "Lab configuration: invalid — #{config[:error]}"
+            end
+          end
+
+          def runtime_line(report)
+            runtime = report.runtime_config
+            case runtime[:state]
+            when :valid
+              origin = runtime[:path] || runtime[:source]
+              "Runtime configuration: #{runtime[:runtime] || '(value unset)'} (#{origin})"
+            when :invalid
+              "Runtime configuration: invalid — #{runtime[:error]}"
+            else
+              "Runtime configuration: none (no config file, ACE_RUNTIME unset)"
+            end
+          end
+
+          def location_line(location)
+            state =
+              case location[:state]
+              when :present then format("present (%s)", location[:entries])
+              when :prepared then "prepared"
+              when :error then "ERROR"
+              else "not present"
+              end
+            note = location[:note] ? " (#{location[:note]})" : ""
+            format("  %-12s %-16s %s%s", location[:key], state, location[:path], note)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli/commands/verify.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../organisms/verify"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Verify < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          SECTION_LABELS = {
+            "accounts" => "account", "directories" => "directory", "keys" => "account",
+            "roles" => "id", "repositories" => "project", "grants" => "principal",
+            "registry" => "project", "overseer" => "project",
+            "adapters" => "adapter", "tools" => "tool", "gems" => "gem"
+          }.freeze
+
+          desc "Verify the installed lab's readiness under the target accounts (read-only): " \
+            "accounts, directories, key pairs, role instructions, repository origins and " \
+            "target-executor access, grant-based project visibility, private _overseer " \
+            "folders, configured communication/HITL adapters, required tools, declared gem set"
+
+          example [
+            "--format json        # Machine-readable report for the overseer / next tool",
+            "                      # exit 0 only when every check passes or is unknown"
+          ]
+
+          option :format, type: :string, desc: "Output format (table, json; default: table)"
+          option :quiet, type: :boolean, aliases: %w[-q], desc: "Suppress output"
+
+          def initialize(verifier: nil)
+            super()
+            @verifier = verifier
+          end
+
+          def call(**options)
+            format = options[:format] || "table"
+            unless %w[table json].include?(format)
+              raise Ace::Support::Cli::Error,
+                "--format \"#{format}\" is not supported; table or json"
+            end
+
+            report = (@verifier || Organisms::Verify.new).call
+            render(report, format: format, quiet: options[:quiet])
+
+            # A not-ready lab never exits 0: the report renders first
+            # (failure beside healthy data — both visible), then the
+            # failure list names every failed check concretely.
+            unless report["ready"]
+              raise Ace::Support::Cli::Error, failure_summary(report)
+            end
+          rescue Ace::Lab::InvalidConfigurationError => e
+            raise Ace::Support::Cli::Error, e.message
+          end
+
+          private
+
+          def render(report, format:, quiet:)
+            return if quiet
+
+            puts format == "json" ? JSON.generate(report) : render_table(report)
+          end
+
+          def render_table(report)
+            counts = report["counts"]
+            lines = ["Machine: #{report['machine']}  manifest: #{report['manifest']}"]
+            report["checks"].each do |section, checks|
+              lines << "#{section.capitalize}:"
+              if checks.empty?
+                lines << "  (none declared)"
+                next
+              end
+              checks.each do |check|
+                label = check[SECTION_LABELS.fetch(section, "reason")] || check["path"] || section
+                detail = detail_of(check)
+                lines << "  #{label.to_s.ljust(34)} #{check['status'].upcase}#{detail}"
+                lines << "    #{check['reason']}" if check["reason"]
+              end
+            end
+            lines << "Checks: #{counts['pass']} pass, #{counts['fail']} failed, " \
+              "#{counts['unknown']} unknown"
+            lines << "Result: #{report['ready'] ? 'ready' : 'NOT READY'}"
+            lines.join("\n")
+          end
+
+          def detail_of(check)
+            parts = []
+            parts << "uid #{check['uid']}" if check.key?("uid")
+            parts << "shell #{check['shell']}" if check["shell"]
+            parts << "fingerprint #{check['fingerprint']}" if check["fingerprint"]
+            parts << "origin #{check['origin']}" if check["origin"]
+            parts << "projects #{check['projects'].join(', ')}" if check["projects"].is_a?(Array)
+            parts.empty? ? "" : " (#{parts.join(', ')})"
+          end
+
+          def failure_summary(report)
+            failures = report["checks"].flat_map do |section, checks|
+              checks.select { |check| check["status"] == "fail" }
+                .map { |check| "#{section}/#{check_name(check, section)}: #{check['reason']}" }
+            end
+            "lab is not ready (#{failures.size} failed check(s)): #{failures.join('; ')}"
+          end
+
+          def check_name(check, section)
+            check[SECTION_LABELS.fetch(section, "reason")] || check["path"] || section
+          end
+        end
+      end
+    end
+  end
+end

data/lib/ace/lab/cli.rb

@@ -8,10 +8,11 @@ require_relative "cli/commands/agents"
 require_relative "cli/commands/services"
 require_relative "cli/commands/resolve"
 require_relative "cli/commands/route"
-require_relative "cli/commands/service"
-require_relative "cli/commands/assignment"
-require_relative "cli/commands/command_execute"
-require_relative "cli/commands/run"
+require_relative "cli/commands/status"
+require_relative "cli/commands/prepare"
+require_relative "cli/commands/project_add"
+require_relative "cli/commands/install"
+require_relative "cli/commands/verify"
 
 module Ace
   module Lab
@@ -23,26 +24,28 @@ module Ace
 
       # Application commands with descriptions (for help output)
       REGISTERED_COMMANDS = [
-        ["run", "Run one explicitly authorized project command"],
-        ["run-status", "Inspect an original command execution without running it"],
         ["projects", "List lab projects visible to the verified caller"],
         ["agents", "List lab agents in a project by stable ID"],
         ["services", "List lab services in a project by stable ID"],
         ["resolve", "Resolve one lab entry by exact stable ID"],
         ["route", "Select a configured capable service in a project"],
-        ["service request", "Request one authorized service operation"],
-        ["service status", "Read a service request outcome"],
-        ["service listen", "Serve the ordinary fixed merge receiver on its configured socket"],
-        ["assignment prepare", "Retain reviewed task input for ordinary Assign registration"],
-        ["assignment drive", "Drive one original execution through the installed ordinary owner"],
-        ["assignment request", "Send one retained operation to the installed ordinary Assign owner"]
+        ["status", "Show lab configuration and local file state (read-only)"],
+        ["prepare", "Prepare accounts, directories, permissions, keys and roles from the trusted install manifest"],
+        ["project add", "Register a project and make it ready for team work (repository, _overseer, lab config)"],
+        ["install", "Perform the full new-lab installation from the trusted install manifest"],
+        ["verify", "Verify the installed lab's readiness under the target accounts (read-only)"]
       ].freeze
 
       HELP_EXAMPLES = [
         "ace-lab projects --format json",
         "ace-lab agents --project atlas --format json",
         "ace-lab resolve --id atlas-planner --format json",
-        "ace-lab route --project atlas --capability search --format json"
+        "ace-lab route --project atlas --capability search --format json",
+        "ace-lab status --format json",
+        "ace-lab prepare --dry-run",
+        "ace-lab project add atlas --path /Users/ace/lab/atlas --remote git@forge:atlas/atlas.git",
+        "ace-lab install --dry-run",
+        "ace-lab verify --format json"
       ].freeze
 
       # Start the CLI
@@ -50,7 +53,6 @@ module Ace
       # @param args [Array<String>] Command-line arguments
       # @return [Integer] Exit code (0 for success, non-zero for failure)
       def self.start(args)
-        return CLI::Commands::Run.invoke(args.drop(1)) if args.first == "run" && !(args.take(args.index("--") || args.size).include?("--help") || args.take(args.index("--") || args.size).include?("-h"))
         Ace::Support::Cli::Runner.new(self).call(args: args)
       end
 
@@ -60,15 +62,11 @@ module Ace
       register "services", CLI::Commands::Services.new
       register "resolve", CLI::Commands::Resolve.new
       register "route", CLI::Commands::Route.new
-      register "service request", CLI::Commands::Service::Request.new
-      register "service status", CLI::Commands::Service::Status.new
-      register "service listen", CLI::Commands::Service::Listen.new
-      register "run", CLI::Commands::Run.new
-      register "run-status", CLI::Commands::RunStatus.new
-      register "command execute", CLI::Commands::CommandExecute.new
-      register "assignment prepare", CLI::Commands::Assignment::Prepare.new
-      register "assignment drive", CLI::Commands::Assignment::Drive.new
-      register "assignment request", CLI::Commands::Assignment::Request.new
+      register "status", CLI::Commands::Status.new
+      register "prepare", CLI::Commands::Prepare.new
+      register "project add", CLI::Commands::ProjectAdd.new
+      register "install", CLI::Commands::Install.new
+      register "verify", CLI::Commands::Verify.new
 
       # Register version command
       version_cmd = Ace::Support::Cli::VersionCommand.build(

data/lib/ace/lab/install_manifest_path.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    # The trusted install manifest is a deployment document at a FIXED path
+    # — never in the caller-writable configuration cascade and never at a
+    # caller-selected location. It must be root-owned and not
+    # group/world-writable along its whole path, exactly like
+    # AUTHORIZATION_PATH; InstallManifestLoader verifies through
+    # GrantResolver.read_verified and fails closed. A caller-writable
+    # manifest could provision accounts, directories and keys, i.e.
+    # manufacture privileges.
+    INSTALL_MANIFEST_PATH = "/etc/lab/ace-lab/install.yml"
+
+    # Path of the trusted install manifest. A method (not a bare constant
+    # reference) so tests stub the seam without any caller-controllable
+    # production override; the CLI deliberately exposes no --manifest flag.
+    # @return [String]
+    def self.install_manifest_path
+      INSTALL_MANIFEST_PATH
+    end
+  end
+end

data/lib/ace/lab/models/status_report.rb

@@ -0,0 +1,38 @@
+# frozen_string_literal: true
+
+module Ace
+  module Lab
+    module Models
+      # Immutable value object carrying the assembled status report.
+      # ok? is false exactly when a configuration source is invalid or a
+      # state location failed to read — an empty-but-valid lab is ok.
+      class StatusReport
+        attr_reader :config, :runtime_config, :state, :root
+
+        def initialize(config:, runtime_config:, state:, root:)
+          @config = config.freeze
+          @runtime_config = runtime_config.freeze
+          @state = state.map(&:freeze).freeze
+          @root = root
+          freeze
+        end
+
+        def ok?
+          @config[:state] != :invalid &&
+            @runtime_config[:state] != :invalid &&
+            @state.none? { |location| location[:state] == :error }
+        end
+
+        def to_h
+          {
+            config: @config,
+            runtime_config: @runtime_config,
+            state: @state,
+            root: @root,
+            ok: ok?
+          }
+        end
+      end
+    end
+  end
+end