ace-lab 0.8.0 → 0.13.0

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"
+          }.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"
+
+          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,8 +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/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
@@ -26,18 +29,23 @@ module Ace
         ["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 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
@@ -54,11 +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 "assignment prepare", CLI::Commands::Assignment::Prepare.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

data/lib/ace/lab/molecules/account_provisioner.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require_relative "../errors"
+require "open3"
+require "etc"
+require "securerandom"
+
+module Ace
+  module Lab
+    module Molecules
+      # Idempotently ensures a lab account exists, per the trusted install
+      # manifest. Existing accounts are reported with their uid; missing
+      # accounts either fail with an actionable message (create: false, or
+      # creation without administrator privileges) or are created through
+      # the platform's own account tooling (darwin dscl / linux useradd),
+      # always with argv arrays (ADR-031) — never a shell string. Every
+      # failure message names the account and the remedy; command failures
+      # surface only the exit status and the first stderr line, never file
+      # content.
+      class AccountProvisioner
+        DEFAULT_SHELL = "/bin/zsh"
+        DARWIN_PRIMARY_GROUP = 20
+
+        attr_reader :runner, :account_lookup, :privileged, :platform, :dry_run
+
+        def initialize(runner: nil, account_lookup: nil, privileged: nil, platform: nil, dry_run: false)
+          @runner = runner || method(:run_argv)
+          @account_lookup = account_lookup || method(:lookup_passwd)
+          @privileged = privileged || -> { Process.euid.zero? }
+          @platform = platform || Ace::Lab.host_platform
+          @dry_run = dry_run
+        end
+
+        # @param account [Hash] normalized manifest account entry
+        # @return [Hash] {username:, status:, uid:, message:}
+        def call(account:)
+          username = account["username"]
+          existing = account_lookup.call(username)
+          if existing
+            return {"username" => username, "status" => "exists", "uid" => existing.uid,
+              "message" => nil} if existing.dir == account["home"]
+
+            # Drift is reported, not repaired: the manifest home stays
+            # authoritative (key default paths derive from it).
+            {"username" => username, "status" => "exists", "uid" => existing.uid,
+             "message" => "account '#{username}' home is '#{existing.dir}' but the manifest " \
+              "declares '#{account["home"]}'; the manifest home is authoritative for key paths"}
+          else
+
+            unless account["create"]
+              return failure(username,
+                "account '#{username}' does not exist; create it manually (administrator action) " \
+                "or set create: true in the install manifest")
+            end
+
+            unless privileged.call
+              return failure(username,
+                "creating account '#{username}' requires administrator privileges; rerun ace-lab prepare " \
+                "with sudo or create the account manually")
+            end
+
+            # Platform support is classified BEFORE the dry-run
+            # prediction: --dry-run must predict the wet failure on an
+            # unsupported platform, not would_create.
+            creation = case platform
+                       when "darwin" then :create_darwin
+                       when "linux" then :create_linux
+                       end
+            if creation.nil?
+              return failure(username,
+                "unsupported platform '#{platform}' for account creation; create account '#{username}' " \
+                "manually and set create: false in the install manifest")
+            end
+
+            if dry_run
+              return {"username" => username, "status" => "would_create", "uid" => nil, "message" => nil}
+            end
+
+            send(creation, account)
+          end
+        end
+
+        private
+
+        def failure(username, message)
+          {"username" => username, "status" => "failed", "uid" => nil, "message" => message}
+        end
+
+        def created(username, uid)
+          {"username" => username, "status" => "created", "uid" => uid, "message" => nil}
+        end
+
+        def create_darwin(account)
+          username = account["username"]
+          listing = invoke(["dscl", ".", "-list", "/Users", "UniqueID"])
+          return failure(username, listing["message"]) unless listing["ok"]
+
+          uid = next_darwin_uid(listing["out"])
+          steps = [
+            ["dscl", ".", "-create", "/Users/#{username}", "RealName", username],
+            ["dscl", ".", "-create", "/Users/#{username}", "UniqueID", uid.to_s],
+            ["dscl", ".", "-create", "/Users/#{username}", "PrimaryGroupID", DARWIN_PRIMARY_GROUP.to_s],
+            ["dscl", ".", "-create", "/Users/#{username}", "UserShell", DEFAULT_SHELL],
+            ["dscl", ".", "-create", "/Users/#{username}", "NFSHomeDirectory", account["home"]],
+            ["dscl", ".", "-create", "/Users/#{username}", "GeneratedUID", SecureRandom.uuid],
+            ["dscl", ".", "-create", "/Users/#{username}", "Password", "*"],
+            ["createhomedir", "-c", "-u", username]
+          ]
+          steps.each do |argv|
+            result = invoke(argv)
+            return failure(username, result["message"]) unless result["ok"]
+          end
+
+          created(username, uid)
+        end
+
+        # Allocate the next free UniqueID above the current maximum,
+        # ignoring the reserved high sentinel values (darwin's `nobody`
+        # reports 4294967294). Parse only the trailing UniqueID column
+        # of each `dscl -list` line — digits inside account names such
+        # as `deploy-2026` must never be taken for a UID. Deliberately
+        # simple: dscl owns the directory; concurrent creation is
+        # reconciled by the idempotent re-run.
+        def next_darwin_uid(out)
+          ids = out.lines.filter_map { |line| line[/\s(\d+)\s*\z/, 1] }
+            .map(&:to_i).reject { |id| id >= 2**31 }
+          return 501 if ids.empty?
+
+          [ids.max + 1, 501].max
+        end
+
+        def create_linux(account)
+          username = account["username"]
+          result = invoke([
+            "useradd", "-m", "-s", DEFAULT_SHELL, "-d", account["home"], username
+          ])
+          return failure(username, result["message"]) unless result["ok"]
+
+          entry = account_lookup.call(username)
+          if entry
+            created(username, entry.uid)
+          else
+            {"username" => username, "status" => "created", "uid" => nil,
+             "message" => "account '#{username}' was created but its uid could not be " \
+               "resolved yet; rerun ace-lab prepare to report it"}
+          end
+        end
+
+        # @return [Hash] {ok:, out:, message:} — failure message carries
+        #   the exit status and the first stderr line only, never command
+        #   output bodies or file content.
+        def invoke(argv)
+          result = runner.call(argv)
+          if result["status"] == "ok"
+            {"ok" => true, "out" => result["out"], "message" => nil}
+          elsif result["status"] == "enoent"
+            {"ok" => false, "out" => result["out"],
+             "message" => "#{argv.first} not found in PATH; install it and rerun ace-lab prepare"}
+          elsif result["status"] == "exec_failed"
+            # Exec-level SystemCallError, not a subprocess exit status —
+            # render the errno class so the message never says "exit failed".
+            {"ok" => false, "out" => result["out"],
+             "message" => "command could not be executed (#{argv.first}, #{result['err']})"}
+          else
+            first_line = result["err"].to_s.lines.map(&:strip).reject(&:empty?).first
+            # Round 5 (C2): a signal-killed child has no exitstatus —
+            # the runner renders "signal <termsig>" instead of nil.
+            message = "command failed (#{argv.first}, #{exit_detail(result['status'])})"
+            message += ": #{first_line}" if first_line
+            {"ok" => false, "out" => result["out"], "message" => message}
+          end
+        end
+
+        def exit_detail(status)
+          status.is_a?(Integer) ? "exit #{status}" : status.to_s
+        end
+
+        def run_argv(argv)
+          out, err, status = Open3.capture3(*argv)
+          {"status" => status.success? ? "ok" : (status.exitstatus || "signal #{status.termsig}"),
+           "out" => out, "err" => err}
+        rescue Errno::ENOENT
+          {"status" => "enoent", "out" => "", "err" => ""}
+        rescue SystemCallError => e
+          {"status" => "exec_failed", "out" => "", "err" => e.class.name}
+        end
+
+        def lookup_passwd(username)
+          Etc.getpwnam(username)
+        rescue ArgumentError
+          nil
+        end
+      end
+    end
+  end
+end