ace-lab 0.9.0 → 0.13.1

data/lib/ace/lab/atoms/install_schema.rb

@@ -0,0 +1,444 @@
+# frozen_string_literal: true
+
+require "rubygems/version"
+
+module Ace
+  module Lab
+    module Atoms
+      # Pure validation and normalization of the trusted install manifest
+      # (v1). The manifest is a deployment document read from a fixed
+      # root-owned path — never from the caller-writable cascade — so this
+      # atom only checks structure; it performs no IO and raises value-free
+      # messages naming the offending section (the caller cannot use schema
+      # errors to echo untrusted content back into diagnostics).
+      class InstallSchema
+        SCHEMA_VERSION = 1
+        TOP_LEVEL_KEYS =
+          %w[schema_version machine accounts directories keys roles projects grants
+             adapters tools gemset].freeze
+        ENTRY_KEYS = {
+          "accounts" => %w[username role create home],
+          "directories" => %w[path owner mode],
+          "keys" => %w[account type path],
+          "roles" => %w[id account instructions],
+          "projects" => %w[id path remote label],
+          "adapters" => %w[id kind command config]
+        }.freeze
+        USERNAME_PATTERN = /\A[a-z_][a-z0-9_-]{0,31}\z/
+        ROLE_ID_PATTERN = /\A[a-z][a-z0-9_-]{0,31}\z/
+        INSTRUCTION_PROTOCOLS = %w[wfi:// prompt:// tmpl://].freeze
+        ADAPTER_KINDS = %w[communication hitl].freeze
+        DEFAULT_MODE = "0755"
+        DEFAULT_KEY_TYPE = "ed25519"
+        KEY_TYPES = [DEFAULT_KEY_TYPE].freeze
+        GEMSET_KEYS = %w[gem_home gems].freeze
+        GEM_KEYS = %w[name version].freeze
+        GEM_NAME_PATTERN = /\A[A-Za-z0-9._-]+\z/
+
+        class << self
+          # @param document [Object] parsed YAML document
+          # @param platform [String, nil] "darwin" / "linux" (home defaults);
+          #   nil resolves through the Ace::Lab.host_platform seam
+          # @return [Hash] normalized manifest with defaults applied
+          # @raise [Ace::Lab::InvalidConfigurationError]
+          def normalize(document, platform: nil)
+            unless document.is_a?(Hash)
+              raise_invalid "manifest must be a mapping"
+            end
+
+            version = document["schema_version"]
+            unless version == SCHEMA_VERSION
+              raise_invalid "schema_version must be #{SCHEMA_VERSION}"
+            end
+
+            unknown = document.keys - TOP_LEVEL_KEYS
+            unless unknown.empty?
+              raise_invalid "unknown top-level key '#{unknown.sort.first}'"
+            end
+
+            machine = document["machine"]
+            unless machine.is_a?(String) && !machine.empty? && machine !~ /\s/
+              raise_invalid "machine must be a non-empty string without whitespace"
+            end
+
+            os = platform || Ace::Lab.host_platform
+            accounts = normalize_accounts(document["accounts"], os)
+            usernames = accounts.map { |account| account["username"] }
+            projects = normalize_projects(document["projects"])
+
+            {
+              "schema_version" => SCHEMA_VERSION,
+              "machine" => machine,
+              "accounts" => accounts,
+              "directories" => normalize_directories(document["directories"], usernames),
+              "keys" => normalize_keys(document["keys"], accounts),
+              "roles" => normalize_roles(document["roles"], usernames),
+              "projects" => projects,
+              "grants" => normalize_grants(document["grants"], projects.map { |p| p["id"] }),
+              "adapters" => normalize_adapters(document["adapters"]),
+              "tools" => normalize_tools(document["tools"]),
+              "gemset" => normalize_gemset(document["gemset"])
+            }
+          end
+
+          private
+
+          def raise_invalid(reason)
+            raise Ace::Lab::InvalidConfigurationError,
+              "invalid lab install manifest: #{reason}"
+          end
+
+          def raise_invalid_entry(section, reason)
+            raise_invalid "#{section} entry #{reason}"
+          end
+
+          def section(raw, name)
+            value = raw.nil? ? [] : raw
+            unless value.is_a?(Array)
+              raise_invalid "#{name} must be a list"
+            end
+            value.each_with_index do |entry, index|
+              unless entry.is_a?(Hash)
+                raise_invalid_entry(name, "##{index} must be a mapping")
+              end
+              next if ENTRY_KEYS[name].nil?
+
+              unknown = entry.keys - ENTRY_KEYS[name]
+              unless unknown.empty?
+                raise_invalid_entry(name, "##{index} has unknown key '#{unknown.sort.first}'")
+              end
+            end
+            value
+          end
+
+          def normalize_accounts(raw, platform)
+            section(raw, "accounts").map do |entry|
+              username = required_string(entry, "accounts", "username")
+              unless username =~ USERNAME_PATTERN
+                raise_invalid_entry("accounts", "username format is invalid")
+              end
+
+              role = required_string(entry, "accounts", "role")
+
+              create = entry.key?("create") ? entry["create"] : false
+              unless [true, false].include?(create)
+                raise_invalid_entry("accounts", "create must be a boolean")
+              end
+
+              home = entry["home"]
+              if home.nil?
+                home = default_home(username, platform)
+              elsif !home.is_a?(String) || !absolute_path?(home)
+                raise_invalid_entry("accounts", "home must be an absolute path")
+              end
+
+              {"username" => username, "role" => role, "create" => create, "home" => home}
+            end.tap do |accounts|
+              duplicates_of(accounts.map { |a| a["username"] }) do |_username|
+                raise_invalid_entry("accounts", "username is declared more than once")
+              end
+            end
+          end
+
+          def normalize_directories(raw, usernames)
+            section(raw, "directories").map do |entry|
+              path = required_string(entry, "directories", "path")
+              unless absolute_path?(path)
+                raise_invalid_entry("directories", "path must be an absolute path")
+              end
+
+              owner = entry["owner"]
+              if !owner.nil?
+                unless owner.is_a?(String) && usernames.include?(owner)
+                  raise_invalid_entry("directories", "owner must reference a declared account")
+                end
+              end
+
+              {"path" => path, "owner" => owner, "mode" => normalize_mode(entry["mode"])}
+            end
+          end
+
+          def normalize_keys(raw, accounts)
+            homes = accounts.to_h { |account| [account["username"], account["home"]] }
+            section(raw, "keys").map do |entry|
+              account = required_string(entry, "keys", "account")
+              home = homes[account]
+              unless home
+                raise_invalid_entry("keys", "account must reference a declared account")
+              end
+
+              type = entry.key?("type") ? entry["type"] : DEFAULT_KEY_TYPE
+              unless KEY_TYPES.include?(type)
+                raise_invalid_entry("keys", "type must be one of: #{KEY_TYPES.join(', ')}")
+              end
+
+              path = entry["path"]
+              if path.nil?
+                path = File.join(home, ".ssh", "id_#{type}")
+              elsif !path.is_a?(String) || !absolute_path?(path)
+                raise_invalid_entry("keys", "path must be an absolute path")
+              end
+
+              {"account" => account, "type" => type, "path" => path}
+            end.tap do |keys|
+              duplicates_of(keys.map { |key| key["path"] }) do |_path|
+                raise_invalid_entry("keys", "path is declared more than once")
+              end
+            end
+          end
+
+          def normalize_roles(raw, usernames)
+            section(raw, "roles").map do |entry|
+              id = required_string(entry, "roles", "id")
+              unless id =~ ROLE_ID_PATTERN
+                raise_invalid_entry("roles", "id format is invalid")
+              end
+
+              account = required_string(entry, "roles", "account")
+              unless usernames.include?(account)
+                raise_invalid_entry("roles", "account must reference a declared account")
+              end
+
+              instructions = required_string(entry, "roles", "instructions")
+              unless instruction_source?(instructions)
+                raise_invalid_entry("roles",
+                  "instructions must use a wfi://, prompt:// or tmpl:// prefix or be an absolute file path")
+              end
+
+              {"id" => id, "account" => account, "instructions" => instructions}
+            end.tap do |roles|
+              duplicates_of(roles.map { |role| role["id"] }) do |_id|
+                raise_invalid_entry("roles", "id is declared more than once")
+              end
+            end
+          end
+
+          def normalize_projects(raw)
+            section(raw, "projects").map do |entry|
+              id = required_string(entry, "projects", "id")
+              unless id =~ ROLE_ID_PATTERN
+                raise_invalid_entry("projects", "id format is invalid")
+              end
+
+              path = required_string(entry, "projects", "path")
+              unless absolute_path?(path)
+                raise_invalid_entry("projects", "path must be an absolute path")
+              end
+
+              remote = optional_string(entry, "projects", "remote")
+              label = optional_string(entry, "projects", "label")
+
+              {"id" => id, "path" => path, "remote" => remote, "label" => label}
+            end.tap do |projects|
+              duplicates_of(projects.map { |project| project["id"] }) do |_id|
+                raise_invalid_entry("projects", "id is declared more than once")
+              end
+              duplicates_of(projects.map { |project| project["path"] }) do |_path|
+                raise_invalid_entry("projects", "path is declared more than once")
+              end
+            end
+          end
+
+          def normalize_grants(raw, project_ids)
+            grants = raw.nil? ? {} : raw
+            unless grants.is_a?(Hash)
+              raise_invalid "grants must be a mapping of principal to project ids"
+            end
+
+            # Reject duplicates after strip, like the other duplicate
+            # checks (review r1): "admin" and " admin " would otherwise
+            # silently last-wins.
+            duplicates_of(grants.keys.filter_map { |key| key.strip if key.is_a?(String) }) do |_principal|
+              raise_invalid "grants principal name is declared more than once"
+            end
+
+            grants.to_h do |principal, projects|
+              unless principal.is_a?(String) && !principal.strip.empty?
+                raise_invalid "grants principal name must be a non-empty string"
+              end
+              unless projects.is_a?(Array) && !projects.empty? &&
+                projects.all? { |project| project.is_a?(String) && !project.strip.empty? }
+                raise_invalid "grants for principal '#{principal.strip}' must be a non-empty " \
+                  "list of project ids"
+              end
+              duplicates_of(projects.map(&:strip)) do |_project|
+                raise_invalid "grants for principal '#{principal.strip}' list a project more than once"
+              end
+              unknown = projects.map(&:strip) - project_ids
+              unless unknown.empty?
+                raise_invalid "grants for principal '#{principal.strip}' reference project " \
+                  "'#{unknown.sort.first}' which the manifest does not declare"
+              end
+
+              [principal.strip, projects.map(&:strip).uniq]
+            end
+          end
+
+          # Selected communication/HITL adapters (task 8xg.t.sbz.7.2):
+          # each declares an id, a kind, an optional local command that
+          # provides the adapter (probed for availability by verify) and
+          # an optional free-form configuration mapping. Real network
+          # traffic stays out of scope (L9) — this is the declaration
+          # surface install validates and verify probes.
+          def normalize_adapters(raw)
+            section(raw, "adapters").map do |entry|
+              id = required_string(entry, "adapters", "id")
+              unless id =~ ROLE_ID_PATTERN
+                raise_invalid_entry("adapters", "id format is invalid")
+              end
+
+              kind = required_string(entry, "adapters", "kind")
+              unless ADAPTER_KINDS.include?(kind)
+                raise_invalid_entry("adapters",
+                  "kind must be one of: #{ADAPTER_KINDS.join(', ')}")
+              end
+
+              command = optional_string(entry, "adapters", "command")
+
+              config = entry["config"].nil? ? {} : entry["config"]
+              unless config.is_a?(Hash)
+                raise_invalid_entry("adapters", "config must be a mapping when present")
+              end
+
+              {"id" => id, "kind" => kind, "command" => command, "config" => config}
+            end.tap do |adapters|
+              duplicates_of(adapters.map { |adapter| adapter["id"] }) do |_id|
+                raise_invalid_entry("adapters", "id is declared more than once")
+              end
+            end
+          end
+
+          # Required tools (task 8xg.t.sbz.7.4): names the lab needs on
+          # PATH for the target accounts; verify probes each one's
+          # presence (no execution, no network).
+          def normalize_tools(raw)
+            tools = raw.nil? ? [] : raw
+            unless tools.is_a?(Array) && tools.all? { |tool| tool.is_a?(String) && !tool.strip.empty? }
+              raise_invalid "tools must be a list of non-empty strings"
+            end
+
+            duplicates_of(tools.map(&:strip)) do |_tool|
+              raise_invalid "tools list a tool more than once"
+            end
+            tools.map(&:strip).uniq
+          end
+
+          # Target lab runtime and required gem set (gad.2 gap #1, owner
+          # spec 8xg.t.sbz.7): a sibling of `tools` declaring WHERE the
+          # lab's gems must live (`gem_home`, converged as GEM_HOME/
+          # GEM_PATH) and WHICH gems at WHICH exact versions. Absent =
+          # no runtime declared, behavior unchanged. Names must be real
+          # gem names; versions must parse as exact Gem versions (the
+          # same parser the runtime uses) — ranges and bare names are
+          # rejected so convergence is always exact-version.
+          def normalize_gemset(raw)
+            return {"gem_home" => nil, "gems" => []} if raw.nil?
+            unless raw.is_a?(Hash)
+              raise_invalid "gemset must be a mapping"
+            end
+
+            unknown = raw.keys - GEMSET_KEYS
+            unless unknown.empty?
+              raise_invalid "gemset has unknown key '#{unknown.sort.first}'"
+            end
+
+            gem_home = raw["gem_home"]
+            unless gem_home.is_a?(String) && !gem_home.strip.empty? && absolute_path?(gem_home.strip)
+              raise_invalid "gemset gem_home is required and must be an absolute path"
+            end
+
+            {"gem_home" => gem_home.strip, "gems" => normalize_gems(raw["gems"])}
+          end
+
+          def normalize_gems(raw)
+            gems = raw.nil? ? [] : raw
+            unless gems.is_a?(Array)
+              raise_invalid "gemset gems must be a list"
+            end
+            gems.each_with_index do |entry, index|
+              unless entry.is_a?(Hash)
+                raise_invalid "gemset gems entry ##{index} must be a mapping"
+              end
+              unknown = entry.keys - GEM_KEYS
+              unless unknown.empty?
+                raise_invalid "gemset gems entry ##{index} has unknown key '#{unknown.sort.first}'"
+              end
+            end
+
+            gems.map do |entry|
+              name = entry["name"]
+              unless name.is_a?(String) && name.strip =~ GEM_NAME_PATTERN
+                raise_invalid_entry("gemset gems", "name is required and must be a gem name")
+              end
+              version = entry["version"]
+              unless version.is_a?(String) && !version.strip.empty?
+                raise_invalid_entry("gemset gems", "version is required and must be an exact version")
+              end
+              begin
+                Gem::Version.new(version.strip)
+              rescue ArgumentError
+                raise_invalid_entry("gemset gems", "version must be an exact gem version")
+              end
+
+              {"name" => name.strip, "version" => version.strip}
+            end.tap do |gems|
+              duplicates_of(gems.map { |gem| gem["name"] }) do |_name|
+                raise_invalid_entry("gemset gems", "name is declared more than once")
+              end
+            end
+          end
+
+          def optional_string(entry, section_name, field)
+            value = entry[field]
+            if !value.nil? && (!value.is_a?(String) || value.strip.empty?)
+              raise_invalid_entry(section_name, "#{field} must be a non-empty string when present")
+            end
+            value.nil? ? nil : value.strip
+          end
+
+          def required_string(entry, section_name, field)
+            value = entry[field]
+            unless value.is_a?(String) && !value.strip.empty?
+              raise_invalid_entry(section_name, "#{field} is required and must be a non-empty string")
+            end
+            value
+          end
+
+          def normalize_mode(raw)
+            mode = raw.nil? ? DEFAULT_MODE : raw
+            unless mode.is_a?(String) && mode.match?(/\A[0-7]{3,4}\z/)
+              raise_invalid_entry("directories", "mode must be an octal string like \"0750\"")
+            end
+
+            format("%04o", mode.to_i(8))
+          end
+
+          def absolute_path?(path)
+            path.start_with?("/")
+          end
+
+          def instruction_source?(instructions)
+            INSTRUCTION_PROTOCOLS.any? { |protocol| instructions.start_with?(protocol) } ||
+              absolute_path?(instructions)
+          end
+
+          def default_home(username, platform)
+            prefix = platform == "darwin" ? "/Users" : "/home"
+            File.join(prefix, username)
+          end
+
+          def duplicates_of(values)
+            seen = {}
+            values.each do |value|
+              if seen[value]
+                yield value
+              else
+                seen[value] = true
+              end
+            end
+          end
+        end
+      end
+    end
+  end
+end

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

@@ -0,0 +1,161 @@
+# frozen_string_literal: true
+
+require "json"
+require "ace/support/cli"
+require "ace/core"
+require_relative "../../organisms/install"
+require_relative "verify"
+
+module Ace
+  module Lab
+    module CLI
+      module Commands
+        class Install < Ace::Support::Cli::Command
+          include Ace::Support::Cli::Base
+
+          # Step names inside a per-project report (ProjectAdd shape).
+          PROJECT_STEPS = %w[repository overseer registry owner].freeze
+
+          desc "Perform the full new-lab installation from the trusted install manifest " \
+            "(prepare, per-project project add, trusted-tier grants)"
+
+          example [
+            "--dry-run            # Predict every phase 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(install: nil)
+            super()
+            @install = install
+          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 = @install || Organisms::Install.new
+            report = organism.call(dry_run: options[:dry_run] || false)
+            render(report, format: format, quiet: options[:quiet])
+
+            # Same contract as prepare/project add: a wet run with
+            # failed steps never exits 0 — the report renders first,
+            # then the failure list names each step 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']}"]
+
+            lines << "Prepare: #{report['prepare']['ok'] ? 'ok' : 'FAILED'}"
+            prepare_failures(report['prepare']).each do |line|
+              lines << "  #{line}"
+            end
+
+            lines << "Projects:"
+            if report["projects"].empty?
+              lines << "  (none declared)"
+            else
+              report["projects"].each do |project|
+                steps = PROJECT_STEPS.map { |step| "#{step}: #{project[step]['status']}" }.join(", ")
+                lines << "  #{project['project'].to_s.ljust(34)} " \
+                  "#{project['ok'] ? 'ok' : 'FAILED'} (#{steps})"
+                PROJECT_STEPS.each do |step|
+                  lines << "    #{step}: #{project[step]['message']}" if project[step]["message"]
+                end
+              end
+            end
+
+            grants = report["grants"]
+            lines << "Grants (#{grants['path']}): #{grants['status']}"
+            grants["principals"].each do |principal, status|
+              lines << "  #{principal.to_s.ljust(34)} #{status}"
+            end
+            lines << "  #{grants['message']}" if grants["message"]
+
+            lines.concat(render_verify(report["verify"]))
+
+            lines << "Result: #{report['ok'] ? 'ok' : 'FAILED'}"
+            lines.join("\n")
+          end
+
+          # Final install verification stage: the readiness verdict with
+          # every failed check named (adapters and tools included).
+          def render_verify(verify_report)
+            return ["Verify: skipped (#{verify_report['message']})"] if verify_report["status"] == "skipped"
+
+            counts = verify_report["counts"] || {}
+            verdict = verify_report["ready"] ? "ready" : "NOT READY"
+            lines = ["Verify: #{verdict} (#{counts.fetch('pass', 0)} pass, " \
+              "#{counts.fetch('fail', 0)} failed, #{counts.fetch('unknown', 0)} unknown)"]
+            Ace::Lab::CLI::Commands::Verify::SECTION_LABELS.each do |section, label_key|
+              Array(verify_report.dig("checks", section)).each do |check|
+                next unless check["status"] == "fail"
+
+                name = check[label_key] || check["path"] || section
+                lines << "  #{section}/#{name}: #{check['reason']}"
+              end
+            end
+            lines
+          end
+
+          def prepare_failures(prepare_report)
+            Ace::Lab::CLI::Commands::Prepare::SECTION_NAMERS.flat_map do |section, namer|
+              prepare_report[section]
+                .select { |item| item["status"] == "failed" }
+                .map { |item| "#{section}/#{namer.call(item)}: #{item['message']}" }
+            end
+          end
+
+          def failure_summary(report)
+            failures = prepare_failures(report["prepare"])
+            report["projects"].each do |project|
+              PROJECT_STEPS.each do |step|
+                item = project[step]
+                failures << "projects/#{project['project']}/#{step}: #{item['message']}" \
+                  if item["status"] == "failed"
+              end
+            end
+            if report["grants"]["status"] == "failed"
+              failures << "grants: #{report['grants']['message']}"
+            end
+            verify_report = report["verify"]
+            if verify_report.is_a?(Hash) && verify_report["ready"] == false
+              Ace::Lab::CLI::Commands::Verify::SECTION_LABELS.each do |section, label_key|
+                Array(verify_report.dig("checks", section)).each do |check|
+                  next unless check["status"] == "fail"
+
+                  name = check[label_key] || check["path"] || section
+                  failures << "verify/#{section}/#{name}: #{check['reason']}"
+                end
+              end
+              failures << "verify: #{verify_report['message']}" if verify_report["message"]
+            end
+            "install failed (#{failures.size} step(s)): #{failures.join('; ')}"
+          end
+        end
+      end
+    end
+  end
+end