moose-inventory 2.0 → 2.1

data/examples/ansible/inventory_plugins/moose_inventory.py

@@ -0,0 +1,100 @@
+# -*- coding: utf-8 -*-
+# Copyright: (c) Russell Davies
+# MIT License
+
+from __future__ import annotations
+
+import json
+import subprocess
+
+from ansible.errors import AnsibleParserError
+from ansible.plugins.inventory import BaseInventoryPlugin
+
+DOCUMENTATION = r'''
+    name: moose_inventory
+    plugin_type: inventory
+    short_description: Moose Inventory plugin
+    description:
+        - Loads inventory from the C(moose-inventory) command line tool.
+        - Keeps Moose Inventory configuration and environment selection in YAML instead of a shell shim.
+    options:
+        plugin:
+            description: Token that ensures this is a source file for this plugin.
+            required: true
+            choices: ['moose_inventory']
+        executable:
+            description: Moose Inventory executable path.
+            required: false
+            default: moose-inventory
+        config:
+            description: Moose Inventory config file passed to C(--config).
+            required: false
+        env:
+            description: Moose Inventory environment section passed to C(--env).
+            required: false
+'''
+
+EXAMPLES = r'''
+plugin: moose_inventory
+executable: moose-inventory
+config: ./example.conf
+env: dev
+'''
+
+
+class InventoryModule(BaseInventoryPlugin):
+    NAME = 'moose_inventory'
+
+    def verify_file(self, path):
+        return super().verify_file(path) and path.endswith(('moose_inventory.yml', 'moose_inventory.yaml'))
+
+    def parse(self, inventory, loader, path, cache=True):
+        super().parse(inventory, loader, path, cache=cache)
+        config = self._read_config_data(path)
+        executable = config.get('executable', 'moose-inventory')
+        moose_config = config.get('config')
+        env = config.get('env')
+
+        groups = self._run_moose(executable, moose_config, env, ['--ansible', 'group', 'list'])
+        hosts = self._run_moose(executable, moose_config, env, ['host', 'list'])
+
+        self._apply_groups(groups)
+        self._apply_hosts(hosts)
+
+    def _run_moose(self, executable, config, env, args):
+        command = [executable]
+        if config:
+            command.extend(['--config', config])
+        if env:
+            command.extend(['--env', env])
+        command.extend(args)
+
+        try:
+            completed = subprocess.run(command, check=True, capture_output=True, text=True)
+        except (OSError, subprocess.CalledProcessError) as error:
+            raise AnsibleParserError('moose-inventory command failed: %s' % error) from error
+
+        try:
+            return json.loads(completed.stdout or '{}')
+        except json.JSONDecodeError as error:
+            raise AnsibleParserError('moose-inventory returned invalid JSON: %s' % error) from error
+
+    def _apply_groups(self, groups):
+        for group_name, payload in groups.items():
+            self.inventory.add_group(group_name)
+            for host_name in payload.get('hosts', []):
+                self.inventory.add_host(host_name, group=group_name)
+            for child_name in payload.get('children', []):
+                self.inventory.add_group(child_name)
+                self.inventory.add_child(group_name, child_name)
+            for key, value in payload.get('vars', {}).items():
+                self.inventory.set_variable(group_name, key, value)
+
+    def _apply_hosts(self, hosts):
+        for host_name, payload in hosts.items():
+            self.inventory.add_host(host_name)
+            for group_name in payload.get('groups', []):
+                self.inventory.add_group(group_name)
+                self.inventory.add_host(host_name, group=group_name)
+            for key, value in payload.get('hostvars', {}).items():
+                self.inventory.set_variable(host_name, key, value)

data/examples/ci/README.md

@@ -0,0 +1,16 @@
+# Moose Inventory CI/CD Examples
+
+These examples show how to validate an inventory snapshot in CI without using production database credentials.
+
+- `inventory/example-snapshot.yml` is a small review snapshot fixture.
+- `scripts/validate-inventory-snapshot.sh` imports a snapshot into a temporary SQLite database, runs `doctor`, exports a canonical snapshot, lists hosts, and produces an Ansible-compatible inventory artifact.
+- `github-actions/inventory-review.yml` is a copy/paste GitHub Actions workflow example. It is intentionally stored under `examples/` rather than `.github/workflows/` so projects can adapt it before enabling it.
+
+The example writes artifacts to `tmp/inventory-ci-artifacts` by default:
+
+- `doctor.txt`
+- `inventory.yml`
+- `hosts.json`
+- `ansible-inventory.json`
+
+Use this pattern for pull-request review gates before applying inventory changes to a shared or production Moose Inventory database.

data/examples/ci/github-actions/inventory-review.yml

@@ -0,0 +1,38 @@
+name: Inventory review example
+
+on:
+  workflow_dispatch:
+  pull_request:
+    paths:
+      - 'inventory/**'
+      - 'examples/ci/inventory/**'
+
+permissions:
+  contents: read
+
+jobs:
+  validate-inventory:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v5
+
+      - name: Set up Ruby
+        uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: '3.4'
+          bundler-cache: true
+
+      - name: Validate proposed inventory snapshot
+        env:
+          MOOSE_INVENTORY_CMD: bundle exec ruby -Ilib bin/moose-inventory
+        run: |
+          examples/ci/scripts/validate-inventory-snapshot.sh \
+            examples/ci/inventory/example-snapshot.yml \
+            tmp/inventory-ci-artifacts
+
+      - name: Upload inventory review artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: inventory-review
+          path: tmp/inventory-ci-artifacts

data/examples/ci/inventory/example-snapshot.yml

@@ -0,0 +1,19 @@
+---
+version: 1
+hosts:
+  web01:
+    groups:
+      - web
+    tags:
+      - prod
+      - public-edge
+    vars:
+      os: fedora
+      owner: platform
+groups:
+  web:
+    children: []
+    tags:
+      - frontend
+    vars:
+      role: frontend

data/examples/ci/scripts/validate-inventory-snapshot.sh

@@ -0,0 +1,30 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+snapshot="${1:-examples/ci/inventory/example-snapshot.yml}"
+artifact_dir="${2:-tmp/inventory-ci-artifacts}"
+moose_cmd="${MOOSE_INVENTORY_CMD:-moose-inventory}"
+work_dir="$(mktemp -d)"
+trap 'rm -rf "$work_dir"' EXIT
+
+mkdir -p "$artifact_dir"
+config_file="$work_dir/moose-inventory-ci.yml"
+db_file="$work_dir/inventory.db"
+
+cat > "$config_file" <<YAML
+---
+general:
+  defaultenv: ci
+ci:
+  db:
+    adapter: sqlite3
+    file: "$db_file"
+YAML
+
+$moose_cmd --config "$config_file" --env ci import "$snapshot"
+$moose_cmd --config "$config_file" --env ci doctor > "$artifact_dir/doctor.txt"
+$moose_cmd --config "$config_file" --env ci --format yaml export "$artifact_dir/inventory.yml"
+$moose_cmd --config "$config_file" --env ci --format pjson host list > "$artifact_dir/hosts.json"
+$moose_cmd --config "$config_file" --env ci --ansible group list > "$artifact_dir/ansible-inventory.json"
+
+echo "Inventory CI artifacts written to $artifact_dir"

data/lib/moose_inventory/cli/application.rb

@@ -1,20 +1,93 @@
+# frozen_string_literal: true
+
+require 'json'
 require 'thor'
-require_relative '../version.rb'
-require_relative '../config/config.rb'
-require_relative './group.rb'
-require_relative './host.rb'
+require_relative '../version'
+require 'yaml'
+
+require_relative '../config/config'
+require_relative '../operations/import_inventory_snapshot'
+require_relative '../operations/inventory_doctor'
+require_relative '../operations/inventory_snapshot'
+require_relative 'formatter'
+require_relative 'helpers'
+require_relative 'audit'
+require_relative 'console'
+require_relative 'db'
+require_relative 'group'
+require_relative 'host'
 
 module Moose
   module Inventory
     module Cli
       ##
-      # TODO: Documentation
+      # Top-level Thor application for moose-inventory.
+      # rubocop:disable Metrics/ClassLength
       class Application < Thor
+        include Moose::Inventory::Cli::Helpers
+
         desc 'version', 'Get the code version'
         def version
           puts "Version #{Moose::Inventory::VERSION}"
         end
 
+        desc 'doctor', 'Run inventory health checks'
+        option :format, type: :string, desc: 'Emit doctor report as yaml|json|pjson'
+        def doctor
+          report = build_operation(Moose::Inventory::Operations::InventoryDoctor).call
+          render_doctor_report(report)
+          exit(1) unless report[:ok]
+        end
+
+        desc 'export [FILE]', 'Export a canonical inventory snapshot'
+        def export(file = nil)
+          snapshot = build_operation(Moose::Inventory::Operations::InventorySnapshot).export
+          output = serialize_snapshot(snapshot)
+
+          if file.nil?
+            puts output
+          else
+            File.write(file, output)
+            puts "Exported inventory snapshot to #{file}."
+          end
+        end
+
+        desc 'import FILE', 'Import and validate an inventory snapshot'
+        option :preview, type: :boolean, desc: 'Preview snapshot import changes without writing'
+        option :preview_format, type: :string, desc: 'Emit preview as yaml|json|pjson'
+        def import(file)
+          snapshot = YAML.safe_load_file(file, aliases: false)
+          operation = build_operation(Moose::Inventory::Operations::ImportInventorySnapshot)
+          return render_import_preview(operation.preview(snapshot: snapshot)) if options[:preview]
+
+          abort('ERROR: --preview-format requires --preview.') if options[:preview_format]
+
+          result = operation.call(snapshot: snapshot)
+          record_audit({ command: 'import', action: 'import', entity_type: 'inventory',
+                         entity_names: file }, result: result)
+          puts "Imported inventory snapshot from #{file}."
+          puts "Created hosts: #{result.created_hosts}"
+          puts "Created groups: #{result.created_groups}"
+          puts "Variables changed: #{result.updated_variables}"
+          puts "Associations added: #{result.associations}"
+        rescue Psych::SyntaxError => e
+          abort("ERROR: Could not parse inventory snapshot '#{file}': #{e.message}")
+        rescue db.exceptions[:moose] => e
+          abort("ERROR: #{e.message}")
+        end
+
+        map 'db' => :database
+        desc 'audit ACTION', 'Inspect append-only inventory change history'
+        subcommand 'audit', Moose::Inventory::Cli::Audit
+
+        desc 'database ACTION', 'Inspect and manage database lifecycle state'
+        subcommand 'database', Moose::Inventory::Cli::Db
+
+        desc 'console', 'Open a small read-only inventory browsing console'
+        def console
+          Moose::Inventory::Cli::Console.new(context: inventory_context).run
+        end
+
         desc 'group ACTION',
              'Manipulate groups in the inventory. ' \
              'ACTION can be add, rm, get, list, addhost, rmhost, addchild, rmchild, addvar, rmvar'
@@ -24,7 +97,62 @@ module Moose
              'Manipulate hosts in the inventory. ' \
              'ACTION can be add, rm, get, list, addgroup, rmgroup, addvar, rmvar'
         subcommand 'host', Moose::Inventory::Cli::Host
+
+        private
+
+        def render_doctor_report(report)
+          if options[:format]
+            puts serialize_data(report, options[:format].downcase)
+          else
+            render_human_doctor_report(report)
+          end
+        end
+
+        def render_human_doctor_report(report)
+          if report[:ok]
+            puts 'Inventory doctor found no issues.'
+            return
+          end
+
+          puts "Inventory doctor found #{report[:issue_count]} issue(s):"
+          report[:issues].each do |entry|
+            puts "- [#{entry[:severity]}] #{entry[:id]}: #{entry[:message]}"
+          end
+        end
+
+        def render_import_preview(preview)
+          if options[:preview_format]
+            puts serialize_data(preview, options[:preview_format].downcase)
+          else
+            render_human_import_preview(preview)
+          end
+        end
+
+        def render_human_import_preview(preview)
+          puts 'Snapshot import preview. No changes applied.'
+          preview.fetch('summary').each do |key, value|
+            puts "#{key.tr('_', ' ').capitalize}: #{value}"
+          end
+        end
+
+        def serialize_snapshot(snapshot)
+          serialize_data(snapshot, output_format)
+        end
+
+        def serialize_data(data, format)
+          case format
+          when 'yaml', 'y'
+            data.to_yaml
+          when 'prettyjson', 'pjson', 'p'
+            JSON.pretty_generate(data)
+          when 'json', 'j'
+            data.to_json
+          else
+            abort("Output format '#{format}' is not yet supported.")
+          end
+        end
       end
+      # rubocop:enable Metrics/ClassLength
     end
   end
 end

data/lib/moose_inventory/cli/association_rendering.rb

@@ -0,0 +1,74 @@
+# frozen_string_literal: true
+
+require_relative 'association_rendering_support'
+
+module Moose
+  module Inventory
+    module Cli
+      # Shared rendering helpers for host/group association commands.
+      module AssociationRendering
+        include Moose::Inventory::Cli::AssociationRenderingSupport
+
+        private
+
+        def host_group_association_addition_emitter(perspective:)
+          lambda do |event|
+            render_host_group_association_addition_event(event, perspective:)
+          end
+        end
+
+        def host_group_association_removal_emitter(perspective:)
+          lambda do |event|
+            render_host_group_association_removal_event(event, perspective:)
+          end
+        end
+
+        def render_host_group_association_addition_event(event, perspective:)
+          payload = event.payload
+
+          return render_addition_warning(event.type, payload, perspective:) if addition_warning_event?(event.type)
+          return render_addition_existing(payload, perspective:) if event.type == :already_exists_skipping
+          return render_association_dry_run_summary if event.type == :dry_run_summary
+
+          render_addition_action_event(event.type, payload, perspective:)
+        end
+
+        def render_addition_action_event(type, payload, perspective:)
+          case type
+          when :adding_host_group_association, :adding_group_host_association
+            fmt.puts 2, "- #{verb_for(:add, perspective)} association #{association_label(payload, perspective:)}..."
+          when :group_creating_now, :host_creating_now
+            fmt.puts 4, "- #{missing_entity_label(perspective)} does not exist, creating now..."
+          when :removing_automatic_group
+            label = automatic_group_label(payload[:host], perspective:)
+            fmt.puts 2, "- #{verb_for(:remove, perspective)} automatic association #{label}..."
+          when :ok
+            fmt.puts payload[:indent], '- OK'
+          end
+        end
+
+        def render_association_dry_run_summary
+          puts 'Dry run complete. No changes applied.'
+        end
+
+        def render_host_group_association_removal_event(event, perspective:)
+          payload = event.payload
+
+          return render_removal_warning(payload, perspective:) if removal_warning_event?(event.type)
+          return render_removal_missing(payload, perspective:) if event.type == :missing_skipping
+          return render_association_dry_run_summary if event.type == :dry_run_summary
+
+          case event.type
+          when :removing_host_group_association, :removing_group_host_association
+            fmt.puts 2, "- #{verb_for(:remove, perspective)} association #{association_label(payload, perspective:)}..."
+          when :adding_automatic_group
+            label = automatic_group_label(payload[:host], perspective:)
+            fmt.puts 2, "- #{verb_for(:add, perspective)} automatic association #{label}..."
+          when :ok
+            fmt.puts payload[:indent], '- OK'
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/cli/association_rendering_support.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+module Moose
+  module Inventory
+    module Cli
+      # Shared string helpers for host/group association commands.
+      module AssociationRenderingSupport
+        private
+
+        def addition_warning_event?(type)
+          %i[
+            host_group_association_exists
+            group_host_association_exists
+            group_missing_created
+            host_missing_created
+          ].include?(type)
+        end
+
+        def removal_warning_event?(type)
+          %i[host_group_association_missing group_host_association_missing].include?(type)
+        end
+
+        def render_addition_warning(type, payload, perspective:)
+          if %i[host_group_association_exists group_host_association_exists].include?(type)
+            fmt.warn warning_text(
+              "Association #{association_label(payload, perspective:)} already exists, skipping.",
+              perspective:
+            )
+          else
+            fmt.warn warning_text(
+              "#{missing_entity_label(perspective).capitalize} '#{payload[:name]}' does not exist and will be created.",
+              perspective:
+            )
+          end
+        end
+
+        def render_addition_existing(payload, perspective:)
+          fmt.puts payload[:indent], "- #{existing_status_text(perspective)}"
+        end
+
+        def render_removal_warning(payload, perspective:)
+          fmt.warn "Association #{association_label(payload, perspective:)} doesn't exist, skipping.\n"
+        end
+
+        def render_removal_missing(payload, perspective:)
+          fmt.puts payload[:indent], "- #{missing_status_text(perspective)}"
+        end
+
+        def association_label(payload, perspective:)
+          if perspective == :host
+            "{host:#{payload[:host]} <-> group:#{payload[:group]}}"
+          else
+            "{group:#{payload[:group]} <-> host:#{payload[:host]}}"
+          end
+        end
+
+        def automatic_group_label(host, perspective:)
+          if perspective == :host
+            "{host:#{host} <-> group:ungrouped}"
+          else
+            "{group:ungrouped <-> host:#{host}}"
+          end
+        end
+
+        def verb_for(action, perspective)
+          return action.to_s.capitalize if perspective == :host
+
+          action.to_s
+        end
+
+        def missing_entity_label(perspective)
+          perspective == :host ? 'Group' : 'host'
+        end
+
+        def existing_status_text(perspective)
+          perspective == :host ? 'Already exists, skipping.' : 'already exists, skipping.'
+        end
+
+        def missing_status_text(perspective)
+          perspective == :host ? "Doesn't exist, skipping." : "doesn't exist, skipping."
+        end
+
+        def warning_text(text, perspective:)
+          perspective == :host ? text : "#{text}\n"
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/cli/audit.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'thor'
+
+module Moose
+  module Inventory
+    module Cli
+      # Audit log inspection commands.
+      class Audit < Thor
+        include Moose::Inventory::Cli::Helpers
+
+        desc 'list', 'List recent append-only audit events'
+        option :limit, type: :numeric, default: 20
+        option :format, type: :string, desc: 'Emit audit events as yaml|json|pjson'
+        def list
+          events = inventory_context.audit_events(limit: options[:limit]).map { |event| serialize_event(event) }
+          if options[:format]
+            fmt.dump(events, options[:format].downcase)
+          else
+            render_human_events(events)
+          end
+        end
+
+        private
+
+        def serialize_event(event)
+          {
+            id: event.id,
+            created_at: event.created_at,
+            actor: event.actor,
+            command: event.command,
+            action: event.action,
+            entity_type: event.entity_type,
+            entity_name: event.entity_name,
+            details: parse_details(event.details)
+          }
+        end
+
+        def parse_details(details)
+          return nil if details.nil? || details.empty?
+
+          JSON.parse(details)
+        rescue JSON::ParserError
+          details
+        end
+
+        def render_human_events(events)
+          if events.empty?
+            puts 'No audit events recorded.'
+            return
+          end
+
+          events.each do |event|
+            puts "#{event[:id]} #{event[:created_at]} #{event[:command]} " \
+                 "#{event[:entity_type]}=#{event[:entity_name]} action=#{event[:action]}"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moose_inventory/cli/audit_recording.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+require 'json'
+
+module Moose
+  module Inventory
+    module Cli
+      # Shared append-only audit recording helpers for mutating CLI commands.
+      module AuditRecording
+        private
+
+        def record_audit(metadata, result:, dry_run: false)
+          return if dry_run
+
+          inventory_context.record_audit_event(
+            command: metadata.fetch(:command),
+            action: metadata.fetch(:action),
+            actor: ENV.fetch('USER', nil),
+            entity_type: metadata.fetch(:entity_type),
+            entity_name: Array(metadata.fetch(:entity_names)).join(','),
+            details: audit_details(result)
+          )
+        end
+
+        def audit_details(result)
+          JSON.generate(
+            warning_count: result.respond_to?(:warning_count) ? result.warning_count : 0,
+            events: audit_events_from_result(result)
+          )
+        end
+
+        def audit_events_from_result(result)
+          return [] unless result.respond_to?(:events)
+
+          result.events.map { |event| { type: event.type, payload: event.payload } }
+        end
+      end
+    end
+  end
+end