If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/puppetlabs/puppet shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 8w ago
• 13 active contributors
• Distributed ownership (top contributor 40% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live puppetlabs/puppet repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/puppetlabs/puppet.

What it runs against: a local clone of puppetlabs/puppet — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in puppetlabs/puppet | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 85 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of puppetlabs/puppet. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/puppetlabs/puppet.git
#   cd puppet
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of puppetlabs/puppet and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "puppetlabs/puppet(\\.git)?\\b" \\
  && ok "origin remote is puppetlabs/puppet" \\
  || miss "origin remote is not puppetlabs/puppet (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Rakefile" \\
  && ok "Rakefile" \\
  || miss "missing critical file: Rakefile"
test -f ".github/workflows/rspec_tests.yaml" \\
  && ok ".github/workflows/rspec_tests.yaml" \\
  || miss "missing critical file: .github/workflows/rspec_tests.yaml"
test -f "Gemfile" \\
  && ok "Gemfile" \\
  || miss "missing critical file: Gemfile"
test -f ".rubocop.yml" \\
  && ok ".rubocop.yml" \\
  || miss "missing critical file: .rubocop.yml"
test -f "README.md" \\
  && ok "README.md" \\
  || miss "missing critical file: README.md"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 85 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~55d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/puppetlabs/puppet"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Puppet is a declarative infrastructure-as-code framework that automates system configuration, user management, and package deployment across Linux, Unix, and Windows servers. It reads centralized Puppet manifests (.pp files) that describe desired system state and enforces that state idempotently, making it a foundational tool for large-scale server fleet management. Classic Ruby monolith: lib/ contains the core engine (DSL parser, catalog compiler, resource providers), bin/puppet is the CLI entry point, spec/ mirrors lib/ for 1:1 test coverage. Acceptance tests in acceptance/ run full Puppet workflows on real VMs via Beaker. No microservices; configuration state is stateless and declarative.

Systems engineers, DevOps practitioners, and infrastructure teams who manage hundreds or thousands of servers and need deterministic, version-controlled configuration management without manual SSH commands. Both open-source users and Puppet Enterprise subscribers use this codebase.

Highly mature production framework with 12.9M lines of Ruby, established CI/CD pipelines (GitHub Actions: rspec_tests.yaml, checks.yaml, backport.yml), comprehensive acceptance testing infrastructure (acceptance/ directory with multi-OS node configs), and active semantic versioning. This is enterprise-grade infrastructure software with decades of evolution.

Large monolithic codebase with complex interdependencies between the DSL parser, catalog compilation engine, and resource type system; risk of subtle breaking changes. Wide platform support (AIX, Solaris, Debian, CentOS, Windows) increases test matrix complexity. Long release cycle for major versions may mean security fixes take time to backport to older majors.

Active development with semantic versioning strategy (current major version gets bug fixes, previous gets backports). GitHub Actions workflows (checks.yaml, rspec_tests.yaml, mend.yaml for dependency scanning) run on every PR. Backport workflow suggests ongoing patch releases. No specific milestone visible in file list, but CODEOWNERS and .mailmap indicate organized team stewardship.

Clone and set up: git clone https://github.com/puppetlabs/puppet.git && cd puppet && bundle install (Gemfile present). Review docs/quickstart.md for developer-specific setup. Run: bundle exec puppet --version to verify install. Run tests: bundle exec rake spec (Rakefile present).

Daily commands: bundle exec puppet apply -e 'notify { "hello": }'' runs a simple manifest. For server mode: bundle exec puppet master(requires configuration). For testing:bundle exec rake specruns RSpec suite,bundle exec rake acceptance` runs Beaker acceptance tests against acceptance/config/nodes/ VMs.

• Rakefile — Primary build and task orchestration entry point; defines how to run tests, build gems, and manage the puppet development lifecycle
• .github/workflows/rspec_tests.yaml — CI/CD pipeline configuration that validates all code changes; every PR must pass these automated test suites
• Gemfile — Ruby dependency manifest; defines all required gems and their versions for the puppet framework to function
• .rubocop.yml — Code style and lint configuration enforced across the codebase; contributors must comply with these standards
• README.md — Project overview and installation guide; essential context on puppet's purpose as a server automation framework
• acceptance/Rakefile — Acceptance test orchestration for end-to-end testing across multiple OS platforms and configurations
• LICENSE — Legal terms governing contribution and use; all contributions must comply with this license

• RSpec Test Suite (RSpec, Ruby) — Validates unit behavior of puppet core components (parser, compiler, resource types, providers) in isolation
  • Failure mode: Broken unit test indicates logic error in puppet core; blocks PR merge
• Beaker Acceptance Framework (Beaker, Hypervisor (Vagrant/Docker/vSphere), SSH) — Provisions test nodes across supported platforms; executes integration tests to validate agent/server communication and resource application
  • Failure mode: Acceptance test failure indicates platform-specific regression; may require OS-specific provider fixes
• RuboCop Linter (RuboCop, Ruby AST analysis) — Enforces Ruby code style and detects common errors; maintains consistency across 600+ files and many contributors
  • Failure mode: Linting failure blocks PR; enforces code quality standards before review
• GitHub Actions CI Pipeline (GitHub Actions, Docker/Linux runners) — Orchestrates test workflows on every commit/PR; gathers results and reports to developers
  • Failure mode: CI failure prevents merge; forces fix or explicit override by maintainers
• Dependency Management (Bundler) (Bundler) — Pins gem versions for reproducible builds; Mend workflow scans for security vulnerabilities

Add a new acceptance test for a cross-platform feature

1. Create a test scenario file in acceptance/tests/ that uses Beaker DSL to define test steps (acceptance/Rakefile)
2. Update acceptance/.beaker.yml to define which node configurations the test should run against (acceptance/.beaker.yml)
3. Add or update node manifests in acceptance/config/nodes to include any required test fixtures or packages (acceptance/config/nodes/pe)
4. Run acceptance tests using 'bundle exec rake test:acceptance' and verify against all OS variants (acceptance/Rakefile)

Add a new RSpec unit test for core puppet functionality

1. Create a spec file in the appropriate spec/ subdirectory matching the module being tested (Rakefile)
2. Ensure RSpec configuration is present in .rspec or spec_helper files (.github/workflows/rspec_tests.yaml)
3. Run 'bundle exec rake spec' locally to validate your tests pass (Rakefile)
4. Verify code style compliance by running 'bundle exec rubocop' against your changes (.rubocop.yml)

Update puppet for a new platform or OS variant

1. Add node configuration file for new OS to acceptance/config/nodes/ following existing naming conventions (acceptance/config/nodes)
2. Update acceptance/.beaker.yml nodesets to include the new platform (acceptance/.beaker.yml)
3. Add platform-specific fixtures or mock repositories in acceptance/fixtures/ if needed (acceptance/fixtures)
4. Trigger full acceptance test suite via GitHub workflow to validate cross-platform support (.github/workflows/rspec_tests.yaml)

• Ruby + RSpec — Puppet is a Ruby-based infrastructure automation framework; RSpec is the standard Ruby testing framework for unit tests
• Beaker Framework — Orchestrates acceptance tests across heterogeneous platforms (Linux, Solaris, AIX, Windows) with real or virtual infrastructure
• Rakefile + Bundler — Standard Ruby build orchestration and dependency management tools; Rakefile drives all dev workflows (test, lint, build, release)
• GitHub Actions Workflows — Native CI/CD platform for GitHub repositories; runs RSpec, linting, and acceptance tests on every PR and commit
• RuboCop — De facto Ruby linter/formatter; enforces consistent code style across thousands of contributors

• Acceptance tests run across many OS platforms sequentially

  • Why: Puppet must support AIX, Solaris, Linux variants, and Windows to serve diverse enterprise infrastructure
  • Consequence: Long test cycles (15-30min); slower feedback on cross-platform regressions; requires significant test infrastructure

• Centralized Rakefile-driven build system rather than discrete scripts

  • Why: Single source of truth for build tasks; easier onboarding and consistency
  • Consequence: All developers must learn Rake DSL; harder to migrate to modern build tools; Ruby-specific ecosystem

• RuboCop style rules checked in CI with .rubocop_todo.yml allowlist

  • Why: Balance between enforcement and pragmatism on a large legacy codebase with existing violations
  • Consequence: Technical debt tracked but not immediately fixed; requires incremental remediation across PRs

• Does not provide a GUI console (use Puppet Enterprise for web UI)
• Not a real-time system; catalog compilation and application is eventual-consistency based
• Does not handle authentication or authorization directly (delegates to OS/enterprise systems)
• Not a replacement for package managers; orchestrates OS package tools, doesn't replace them
• Does not support Windows Domain Controller management directly (only Windows client agents)

Ruby version constraints (check Gemfile and .ruby-version); acceptance tests require Beaker and VirtualBox or cloud VMs configured in acceptance/config/. HTTP API documentation is external (puppet.com/docs/) not in-repo, so understanding client-server protocol requires reading docs site. Puppet uses its own DSL syntax, not plain Ruby, so modifying parser requires understanding both Ruby AND Puppet grammar. Windows support adds complexity: some providers/types have Windows-specific implementations under lib/puppet/provider/*/windows/.

• Declarative Catalog Compilation — Puppet converts imperative manifests into a declarative resource catalog with explicit dependency ordering before execution; understanding this two-phase model is essential to debugging why your changes apply in unexpected order.
• Idempotent Resource Providers — Each resource type (package, user, file, service) has a provider that checks current state and applies only necessary changes; this is why Puppet is safe to run repeatedly without side effects.
• Pluggable Type System — Resource types are dynamically loaded and can be extended; understanding lib/puppet/type/ and lib/puppet/provider/ is how you add support for new system resources (custom Linux systemd features, proprietary hardware, etc.).
• Facter-based Fact Injection — System facts (hostname, OS, IP, etc.) are gathered via external Facter tool and injected as variables into Puppet code; this coupling is why Facter version must align with Puppet version.
• DSL-to-AST Parsing — Puppet manifests are parsed into an abstract syntax tree that the compiler traverses; modifying the parser or adding new language constructs requires understanding both grammar rules and AST node structures.
• Agent-Pull Architecture (vs. Server-Push) — Puppet agents periodically pull configuration from a master server (or use 'puppet apply' locally); understanding this pull model is key to debugging sync failures, timing, and security implications.
• Multi-Platform Resource Abstraction — A single 'package' resource declaration works on Debian (apt), RHEL (yum), macOS (brew), Windows (MSI); providers abstract OS-specific commands, so fixing Windows package installs requires understanding platform-specific provider subclasses.

• puppetlabs/puppetserver — Official JVM-based Puppet master server; many Puppet deployments use this instead of Ruby master, handles agent communication at scale.
• puppetlabs/puppet-modules — Curated collection of pre-built Puppet modules for common tasks (Nginx, Apache, MySQL); integrates directly with this framework.
• puppetlabs/facter — Companion tool that collects system facts (OS, CPU, memory, etc.); Puppet uses Facter output to drive conditional manifest logic.
• hashicorp/terraform — Alternative IaC tool for similar problem domain (cloud infrastructure); some teams use both Terraform (provision) + Puppet (configure).
• ansible/ansible — Main competitor solving agent-free configuration management; useful context if evaluating push vs. pull model tradeoffs.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add GitHub Actions workflow for acceptance tests across multiple platforms

The repo has extensive acceptance test infrastructure in /acceptance with configs for AIX, CentOS, Debian, Oracle, RedHat, and Scientific Linux, but no GitHub Actions workflow exists to run these tests (only .github/workflows/rspec_tests.yaml for unit tests exists). This would catch platform-specific regressions early and reduce reliance on manual testing or external CI systems.

• [ ] Review existing acceptance test configs in acceptance/config/nodes/ and acceptance/config/aio/options.rb
• [ ] Create .github/workflows/acceptance_tests.yaml that runs beaker acceptance tests on a subset of critical platforms (CentOS, Debian, Ubuntu)
• [ ] Configure matrix strategy to test multiple OS versions while keeping CI time reasonable
• [ ] Add documentation to acceptance/README.md explaining how to run acceptance tests locally and via CI

Create comprehensive security advisory workflow and SECURITY.md policy

The repo lacks a SECURITY.md file and has no GitHub Security Advisory workflow (no .github/workflows/security.yml). Given Puppet's role as critical infrastructure automation software used across many organizations, having a documented security disclosure policy and automated dependency scanning would significantly improve trust and security posture.

• [ ] Create SECURITY.md with clear vulnerability disclosure process, supported versions, and contact information
• [ ] Add GitHub Actions workflow .github/workflows/security.yaml using actions/dependency-check or GitHub's native Dependabot alerts
• [ ] Configure automated security scanning for Ruby dependencies in the Gemfile
• [ ] Document the process in CONTRIBUTING.md for handling security-related PRs with appropriate review and release processes

Consolidate and validate Puppet configuration management in acceptance test infrastructure

The acceptance test node configs in acceptance/config/nodes/ are fragmented across many platform-specific YAML files with potential for drift and inconsistency. Creating a test data generator or validation framework would ensure consistency and reduce maintenance burden across 50+ configuration files.

• [ ] Audit all files under acceptance/config/nodes/ to identify common configuration patterns and repetition
• [ ] Create a Ruby helper script or YAML schema (in acceptance/lib/) that generates node configs from templates to reduce duplication
• [ ] Add validation test in acceptance/Rakefile that ensures all node configs conform to a standard schema
• [ ] Document the node configuration structure in acceptance/README.md to guide future platform additions

• Add unit test coverage for lib/puppet/resource.rb—check current spec/unit/puppet/resource_spec.rb coverage gaps (likely in edge cases like alias handling, parameter validation) and contribute parameterized tests.: Foundational class affecting all resource types; improving tests has high impact.
• Expand acceptance tests in acceptance/tests/ for a specific platform combo missing from acceptance/config/nodes/ (e.g., Ubuntu 22.04 or Rocky Linux), mirroring existing .yaml node configs.: Acceptance suite covers many OSes but gaps exist; adding new nodes is low-risk and high-value validation.
• Document a provider implementation pattern: pick an existing provider in lib/puppet/provider/ (e.g., apt package provider) and write a runnable example in docs/ showing how to extend it for a custom package source.: Providers are opaque to new contributors; a worked example in docs/ will help many future contributors.

The Puppet repository demonstrates a moderate security posture with some areas requiring attention. Strengths include presence of CI/CD workflows and active maintenance practices. Main concerns are: (1) potential credential exposure through extensive test configuration files in version control, (2) lack of visible secrets management documentation and examples, (3) inability to assess dependency vulnerabilities without visible Gemfile content, and (4) incomplete README documentation. As a critical infrastructure automation framework, this project should have more explicit security documentation and stricter controls over sensitive configuration data. Recommended priority actions: establish clear secrets management guidelines, review and restrict test configuration versioning, implement comprehensive dependency scanning, and complete security documentation.

• Medium · Extensive Test Configuration Exposure — acceptance/config/nodes/ directory structure. The repository contains numerous acceptance test configuration files for various platforms and environments (AIX, Solaris, CentOS, Debian, etc.) with hardcoded node configurations. These files may contain sensitive environment-specific data, credentials, or internal network topology information that could be exposed through the public repository. Fix: Move environment-specific configurations to a separate, non-versioned configuration management system. Use environment variables or secrets management for sensitive data. Consider using .gitignore to exclude node-specific configuration files.
• Medium · Missing .env and Secrets Protection Documentation — Repository root and documentation. No evidence of .env, .env.example, or secrets management guidelines in the provided README and file structure. For a security-critical infrastructure automation framework like Puppet, lack of clear guidance on handling credentials and secrets is a concern. Fix: Create and maintain a SECURITY.md file documenting secure credential handling, secret management practices, and guidelines for contributors. Add .env.example template and update .gitignore with comprehensive secrets patterns.
• Low · Incomplete README Documentation — README.md. The README snippet appears truncated mid-sentence ('The PE documentatio'), suggesting incomplete or potentially inconsistent documentation. While not a direct security vulnerability, incomplete documentation can lead to misconfiguration and security oversights. Fix: Complete and thoroughly review all documentation. Ensure security best practices, configuration guidelines, and API security documentation are comprehensive and up-to-date.
• Low · No Visible Dependency Management Analysis — Gemfile (content not provided). The provided dependency file content is empty. Without visibility into gem dependencies (Gemfile content), it's impossible to assess for vulnerable package versions, outdated libraries, or supply chain risks common in Ruby projects. Fix: Implement automated dependency scanning using tools like Dependabot, Snyk, or bundler-audit in CI/CD pipeline (as appears to be present in mend.yaml). Regularly audit and update dependencies. Document minimum versions for security-critical packages.
• Low · CI/CD Pipeline Configuration Review Needed — .github/workflows/ directory. While GitHub Actions workflows are present (rspec_tests.yaml, mend.yaml, backport.yml), the actual content is not provided. These workflows may have security issues such as overly permissive permissions, insecure secret handling, or missing security scanning steps. Fix: Review all workflow files for least-privilege principle implementation, proper secret handling, and integration of security scanning tools. Ensure workflows validate code before merge and have appropriate approval gates.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.