moose-inventory 2.0 → 2.1.1

data/docs/ux/cli-workflow-notes.md

@@ -0,0 +1,287 @@
+# Moose Inventory CLI UX and Workflow Notes
+
+## Approval status
+
+Status: **Approved CLI UX/workflow baseline**
+
+Approval reference: `GOV-UX-001` in `docs/governance/approval-register.md` approves this document as the CLI UX/workflow baseline for Moose Inventory.
+
+Approved references:
+
+- `GOV-TAILOR-001`: Moose Inventory is approved as Class 4 with target profile Software Library / Package.
+- `GOV-PRODUCT-001`: `docs/product/product-brief.md` is approved as the product-framing baseline.
+- `GOV-REQ-001`: `docs/product/requirements-baseline.md` is approved as the requirements and acceptance criteria baseline.
+
+Scope limit: this approval covers command-line workflows and interaction conventions only. It is not architecture approval, security/privacy design approval, release approval, accepted-risk approval, public/compliance-claim approval, RubyGems publishing approval, or implementation approval for the UX follow-up backlog items.
+
+## UX posture
+
+Moose Inventory is a command-line tool and RubyGem, so its UX baseline is not wireframes or visual mockups. The appropriate UX artifact is a workflow and interaction convention baseline for CLI users, automation users, reviewers, and maintainers.
+
+Primary UX priorities:
+
+1. Make inventory-changing actions explicit, reviewable, and hard to mistake for read-only actions.
+2. Preserve existing command names, output shape, and wording where users or tests may depend on them.
+3. Keep machine-readable output parseable and stable enough for automation.
+4. Give clear, actionable error messages before any write occurs when inputs/options are invalid.
+5. Keep safety controls visible: transactions, dry-run, plan output, validation, doctor checks, and audit history.
+
+## User personas and interaction modes
+
+### CLI operator
+
+A human operator uses `moose-inventory` directly to inspect and change inventory state.
+
+UX needs:
+
+- discoverable help
+- predictable command families
+- readable progress output
+- clear success/failure states
+- safe review before mutation
+
+### Automation/review consumer
+
+A script, CI job, or reviewer consumes machine-readable output from list/get/doctor/export/dry-run plan commands.
+
+UX needs:
+
+- parseable YAML/JSON/pjson
+- non-zero status for failed checks/findings where documented
+- stable keys and event structure
+- no secret leakage in examples/output
+
+### Maintainer/release reviewer
+
+A maintainer checks behavior, documentation, release evidence, and compatibility.
+
+UX needs:
+
+- regression tests for output contracts
+- README examples matching supported behavior
+- clear approval boundaries for breaking changes
+- process evidence distinguishing checks from approval
+
+## Core workflows
+
+### 1. Discover commands
+
+Workflow:
+
+1. User runs top-level or nested help.
+2. CLI displays available commands/options.
+3. User chooses a command family such as `host`, `group`, `db`, `audit`, `doctor`, `import`, or `export`.
+
+UX expectations:
+
+- Help must be available at top-level and command-family levels.
+- Help examples should be accurate enough to copy/adapt.
+- New command families should follow existing README/help style.
+
+### 2. Select configuration and environment
+
+Workflow:
+
+1. User relies on config discovery or passes `--config <FILE>`.
+2. User relies on `general.defaultenv` or passes `--env <SECTION>`.
+3. CLI initializes the configured database context.
+
+UX expectations:
+
+- Missing config, missing environment, and invalid DB config errors should fail before mutation.
+- Error messages should name the missing/invalid element when practical.
+- Docs should steer users toward `password_env` rather than plaintext `password`.
+
+### 3. Inspect inventory
+
+Workflow:
+
+1. User runs list/get commands for hosts/groups/variables/tags.
+2. User optionally passes `--format yaml|json|pjson`.
+3. CLI returns current state without mutation.
+
+UX expectations:
+
+- Read-only commands should not create, repair, or migrate data implicitly unless explicitly documented.
+- Machine-readable formats should remain parseable and consistent.
+- Empty results should be explicit rather than misleading.
+
+### 4. Mutate inventory safely
+
+Workflow:
+
+1. User chooses a mutating command: add/remove hosts/groups, variables, tags, associations, or child relationships.
+2. User optionally previews with `--dry-run` or `--dry-run --plan-format`.
+3. CLI validates inputs/options before writes.
+4. Destructive removal commands require `--yes` before writing unless the user selected `--dry-run`.
+5. CLI applies changes transactionally when not dry-run.
+5. CLI reports progress, warnings, success/failure, and audit evidence where applicable.
+
+UX expectations:
+
+- Mutating commands must be visually distinguishable from read-only workflows through command naming, progress output, and documentation.
+- Invalid option combinations, such as `--plan-format` without `--dry-run`, fail before mutation.
+- Removal commands should fail closed without `--yes`, while still allowing dry-run preview without confirmation.
+- Dry-run output must not imply changes were applied.
+- Real mutation output should preserve existing output contracts unless a breaking change is approved.
+
+### 5. Review planned changes
+
+Workflow:
+
+1. User runs a mutating command with `--dry-run`.
+2. CLI renders planned progress and ends with `Dry run complete. No changes applied.`
+3. User optionally requests `--plan-format yaml|json|pjson` for automation review.
+
+UX expectations:
+
+- Dry-run should use the same conceptual progress path as a real mutation.
+- Dry-run should not write inventory, audit records, schema state, or automatic cleanup associations.
+- Plan output should include ordered event types and payloads suitable for review tools.
+- Human-readable dry-run output should remain easy to compare with real command output.
+
+### 6. Validate health
+
+Workflow:
+
+1. User runs `moose-inventory doctor`.
+2. CLI performs read-only checks.
+3. CLI reports no issues or lists findings with severity/check identifiers.
+4. CLI exits non-zero when findings are present.
+
+UX expectations:
+
+- Findings should be actionable and identify affected subject when practical.
+- Machine-readable doctor output should be suitable for CI gates.
+- Doctor should not silently fix inventory; repairs should remain explicit user actions.
+
+### 7. Import/export snapshots
+
+Workflow:
+
+1. User exports inventory for review, backup, migration, or automation.
+2. User previews a YAML/JSON snapshot with `import FILE --preview` or `--preview --preview-format yaml|json|pjson` when reviewing a proposed change.
+3. User imports a YAML/JSON snapshot.
+4. CLI validates before writing and applies additive/update-oriented changes only.
+
+UX expectations:
+
+- Export should be read-only.
+- Import preview should be read-only and distinct from command-level dry-run planning.
+- Preview output should show creates, variable updates, association additions, unchanged items, ignored existing records, and destructive-change count.
+- Import validation failures should avoid partial writes.
+- Additive import semantics must be documented clearly.
+- Destructive sync/restore semantics must not be introduced without separate requirements, UX, recovery, and approval records.
+
+### 8. Review audit history
+
+Workflow:
+
+1. User runs `audit list` with optional format/limit.
+2. CLI returns append-only evidence for successful mutating commands.
+
+UX expectations:
+
+- Audit output should help explain what changed, when, by whom/tooling, and against what target.
+- Audit output is accountability/debug evidence, not rollback by itself.
+- Dry-runs should not appear as mutation audit records.
+
+## Destructive and high-risk operations
+
+High-risk CLI areas include:
+
+- host/group removal
+- recursive group deletion
+- child-group cleanup with orphan deletion
+- variable removal
+- snapshot import into populated databases
+- schema migration
+- backup/restore-adjacent workflows
+- future destructive snapshot sync/restore features, if ever approved
+
+UX requirements for high-risk operations:
+
+1. The command name/options must make destructive intent visible.
+2. Documentation must describe mutation scope and notable cleanup behavior.
+3. `--dry-run` should be available for documented mutating workflows where supported.
+4. Invalid inputs/options must fail before writes.
+5. Real writes should be transactional where practical.
+6. Future destructive restore/sync behavior requires a separate UX design and approval record.
+
+## Error states and messaging
+
+Expected error behavior:
+
+- fail early before mutation when arguments/options/config are invalid
+- name the invalid option/value where practical
+- distinguish usage errors from database/runtime failures
+- preserve existing exact error strings where tests or downstream users rely on them
+- avoid exposing secrets in errors
+
+Known UX improvement area:
+
+- Read-only console parsing now uses shell-style quoting and command-specific validation for the current browsing commands. Future console changes should preserve the read-only boundary unless mutation flows add confirmation, dry-run, and audit behavior.
+
+## Accessibility and readability expectations
+
+For a CLI, accessibility/readability means:
+
+- plain text that works in ordinary terminals
+- no required color-only signal
+- stable indentation for progress output
+- concise severity/check IDs for doctor findings
+- machine-readable alternatives for automation and assistive tooling
+- examples that can be copied without hidden state or secrets
+- readable failure messages rather than stack traces for ordinary user errors
+
+## Machine-readable output conventions
+
+Machine-readable output is automation-facing UX and is governed by `CLI-OUTPUT-v1` in `docs/compatibility/cli-output-compatibility.md`.
+
+Expectations:
+
+- JSON/YAML/pjson structures should remain parseable.
+- Event/check keys should not be renamed casually.
+- New fields should prefer additive compatibility.
+- Breaking output changes require approval and migration/release notes.
+- Pretty JSON is for humans reviewing structured data; normal JSON/YAML are for scripts and CI.
+
+## Compatibility conventions
+
+Human-readable output is also a versioned compatibility surface under `CLI-OUTPUT-v1` when tests, docs, or scripts rely on exact wording.
+
+Expectations:
+
+- Preserve existing wording/newline behavior during refactors unless an intentional change is approved.
+- Tests should cover known legacy output contracts, especially around warnings and cleanup behavior.
+- README examples should not promise output that the CLI no longer emits.
+- Breaking human-readable output changes need backlog/approval evidence and release notes just like machine-readable breaking changes.
+
+## UX acceptance checklist
+
+A new or changed CLI workflow is UX-ready when:
+
+- The command path and option names are consistent with existing command families.
+- Read vs write behavior is obvious from command naming and docs.
+- Invalid inputs/options fail before mutation.
+- Mutating behavior is transactional where practical.
+- Dry-run/plan behavior exists where required by the requirements baseline.
+- Human-readable output is clear and compatible unless an approved breaking change exists.
+- Machine-readable output is parseable and compatibility-reviewed.
+- README/help examples are updated where user-facing behavior changed.
+- Tests cover success, failure, and safety boundaries.
+- Any unresolved UX risk is recorded as a backlog item or accepted risk.
+
+## UX decisions recorded from review
+
+These decisions were provided by Russ during review on 2026-05-28. They are captured here as product/UX direction for future implementation, but this draft UX baseline still requires explicit approval through `GOV-UX-001` before it becomes approved UX evidence.
+
+1. Destructive commands should eventually require explicit confirmation unless `--yes` or an equivalent non-interactive acknowledgement is provided.
+2. Human-readable output compatibility is formally versioned through `CLI-OUTPUT-v1`, alongside machine-readable output compatibility.
+3. Read-only console support for quoted names and richer validation through `Shellwords.split` should be prioritized before adding more CLI features.
+4. Audit history should remain evidence only; future rollback/change-set UX should not be introduced through audit history.
+5. Snapshot import should eventually offer a formal preview/diff mode distinct from command-level dry-run planning, but this is future work and does not block the current UX baseline.
+
+## Open UX questions
+
+No open UX questions remain in this draft. Future questions should be added here only when they are not already represented as a decision, backlog item, or accepted scope limit.

data/examples/ansible/ansible.cfg

@@ -0,0 +1,3 @@
+[defaults]
+inventory = inventory/moose_inventory.yml
+inventory_plugins = inventory_plugins

data/examples/ansible/inventory/moose_inventory.yml

@@ -0,0 +1,5 @@
+---
+plugin: moose_inventory
+executable: moose-inventory
+config: ./example.conf
+env: dev

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,95 @@
+# 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 Psych::Exception => e
+          abort("ERROR: Could not load 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 +99,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