docopslab-dev 0.1.0

data/docs/agent/skills/tests-running.md

@@ -0,0 +1,25 @@
+# Running Tests in DocOps Lab Projects
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+As an AI agent, you can help DocOps Lab developers run tests effectively using standard Rake tasks.
+
+All Ruby gem projects with tests should implement these standard Rake tasks in their `Rakefile`:
+
+**`bundle exec rake rspec`** :
+   Run RSpec test suite using the standard pattern matcher.
+
+**`bundle exec rake cli_test`** :
+   Validate command-line interface functionality. May test basic CLI loading, help output, version information.
+
+**`bundle exec rake yaml_test`** :
+   Validate YAML configuration files and data structures. Should test all project YAML files for syntax correctness.
+
+**`bundle exec rake pr_test`** :
+   Comprehensive test suite for pre-commit and pull request validation. Typically includes: RSpec tests, CLI tests, YAML validation.
+
+**`bundle exec rake install_local`** :
+   Build and install the project locally for testing.
+
+Note that non-gem projects may have some or all of these tasks, as applicable.
+

data/docs/agent/skills/tests-writing.md

@@ -0,0 +1,45 @@
+# Writing Tests for DocOps Lab Projects
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+As an AI agent, you can help DocOps Lab developers write comprehensive tests following established patterns and categories.
+
+Tests should be organized into these categories:
+
+**Unit Tests** :
+   - Module loading and initialization
+   - Class structure validation
+   - Basic functionality verification
+   - Individual method testing
+
+**Integration Tests** :
+   - Data processing workflows
+   - Template rendering operations
+   - Configuration loading scenarios
+   - API client functionality (where applicable)
+
+**Validation Tests** :
+   - File format compliance (YAML, JSON)
+   - Configuration schema validation
+   - Template syntax verification
+   - Command-line option parsing
+
+All Ruby gem projects with tests should implement these standard Rake tasks in their `Rakefile`:
+
+**`bundle exec rake rspec`** :
+   Run RSpec test suite using the standard pattern matcher.
+
+**`bundle exec rake cli_test`** :
+   Validate command-line interface functionality. May test basic CLI loading, help output, version information.
+
+**`bundle exec rake yaml_test`** :
+   Validate YAML configuration files and data structures. Should test all project YAML files for syntax correctness.
+
+**`bundle exec rake pr_test`** :
+   Comprehensive test suite for pre-commit and pull request validation. Typically includes: RSpec tests, CLI tests, YAML validation.
+
+**`bundle exec rake install_local`** :
+   Build and install the project locally for testing.
+
+Note that non-gem projects may have some or all of these tasks, as applicable.
+

data/docs/agent/skills/write-the-docs.md

@@ -0,0 +1,54 @@
+# Documenting Product Changes
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+Original sources for this document include:
+
+<!-- detect the origin url based on the slug (origin) -->
+- [Product Change Tracking and Documentation](/docs/product-change-docs/)
+
+Each contributor of product code or docs changes is responsible for preparing that change to be included in release documentation, _when applicable_.
+
+Table of Contents
+
+- GitHub Issues Labels
+- Change Documentation
+- Release Note Entry
+
+## GitHub Issues Labels
+
+GitHub Issues are use specific labels to indicate documentation expectations.
+
+**`needs:docs`** :
+   The issue requires documentation updates as part of its resolution. Documentation updates will likely be in a sub-issue with a `documentation` label.
+
+**`needs:note`** :
+   The issue requires a note in the release history when resolved. Release notes are appended to the description body under `## Release Note`.
+
+**`changelog`** :
+   The issue summary should be included in the changelog for the next release, even if no release note is included.
+
+Issues labeled `changelog` will automatically appear in the Changelog section of the Release History document. Release notes must be manually entered.
+
+## Change Documentation
+
+When a change to the product affects user-facing functionality, the documentation needs to change.
+
+For early product versions, most documentation appears in the root `README.adoc` file. When a product has a `docs/content/` path, documentation changes usually have a home in an AsciiDoc (`.adoc`) file in a subdirectory.
+
+Reference matter should be documented where it is defined, such as in `specs/data/*.yml` files.
+
+## Release Note Entry
+
+User-facing product changes that deserve explanation (not just notice) require a release note.
+
+Add a release note for a given issue by appending it to the issue body following a `## Release Note` heading.
+
+Example
+
+```markdown
+## Release Note
+
+The content of the release note goes here, in Markdown format. Try to keep it to one paragraph with minimal formatting.
+```
+

data/docs/agent/topics/common-project-paths.md

@@ -0,0 +1,117 @@
+# Overview of Common Paths/Files in DocOps Lab Projects
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+_If you are creating a new DocOPs Lab project_, use this guide to establish initial files. This also applies to adding major facilities or features to an existing project.
+
+_If you are just getting to know a DocOps Lab codebase_, favor the project’s `README.adoc` file over this guide.
+
+DocOps Lab projects tend to contain many of the same files across codebases. Documentation of these files in particular will be added when possible, but for now this basic guide will have to suffice.
+
+Table of Contents
+
+- Documentation Paths
+- Configuration
+- Containerization
+- Ruby Files
+- Automation Paths
+- Quality Assurance Paths
+- Generative AI Paths
+
+## Documentation Paths
+
+Only two files are required in _every_ DocOps Lab project, though most projects should contain most of these files, depending on the nature of the codebase. A `docs/` or `_docs/` directory is close to the third universal requirement, necessary by the time a project reaches version 1.0.0.
+
+**`README.adoc`** :
+   Project documentation in AsciiDoc format, providing an overview and instructions. DocOps Lab READMEs typically include single-sourcing data for the product as AsciiDoc attributes. See the Sourcerer project.
+
+**`LICENSE`** :
+   The project’s license file, specifying the terms under which the code can be used and distributed. Almost always **MIT License**.
+
+**`docs/` / `_docs/`** :
+   Directory for additional documentation, guides, and related materials. Typically `docs/` for product _user_ documentation, whereas `_docs/` is for (a) repos that are mainly for websites or (b) _internal engineering_ documentation files (more often found at `docs/_docs/`). Both might be present in the case of a website that hosts docs and _has its own_ docs.
+
+   A `docs/` directory will typically have its own `Gemfile`, configs, and assets for Jekyll, Yard, and other generators. A `_docs/` directory is usually a content-only subordinate to the main project and its content, and may not have separate configs or assets.
+
+## Configuration
+
+**`.config/`** :
+   Configuration files for tooling used in development, building, or QA/testing. Not always used.
+
+   **`.config/releasehx.yml`** :
+      Configuration file for ReleaseHx, a tool for generating release notes and changelogs.
+
+   **`.config/jekyll.yml`** :
+      Configuration file for Jekyll docs publication. For Jekyll extensions (themes and plugins), this file is typically `./_config.yml` to conform to Jekyll defaults.
+
+   **`.config/vale.ini`** :
+      Configuration file for Vale, a linter for prose, defining linting rules and styles.
+
+**`.config/.vendor/`** :
+   Directory for upstream configuration files, mostly or entirely managed by `docopsab-dev` gem. These files are not tracked in Git but are synced with upstream sources and maintained by DocOps Lab.
+
+## Containerization
+
+**`Dockerfile`** :
+   Dockerfile for building the project’s Docker image, defining the environment and dependencies.
+
+**`.dockerignore`** :
+   Specifies files and directories to ignore when building the Docker image.
+
+**`docker-compose.yml`** :
+   Defines and runs multi-container Docker applications, _if applicable_.
+
+## Ruby Files
+
+These files are common to Ruby-based DocOps Lab projects. The `Gemfile` and `Gemfile.lock` may be present in non-Ruby codebases that use Ruby development dependencies, such as ReleaseHx.
+
+**`Gemfile`** :
+   Ruby Bundler file, specifying gem dependencies for the project.
+
+**`Gemfile.lock`** :
+   Generated by Bundler, this file locks the gem versions used in the project.
+
+**`.ruby-version`** :
+   Specifies the Ruby version used in the project.
+
+**`<gemname>.gemspec`** :
+   Ruby gem specification file, defining the gem’s metadata and dependencies.
+
+## Automation Paths
+
+**`Rakefile`** :
+   Ruby Rakefile for defining tasks and automation scripts.
+
+**`scripts/`** :
+   Custom scripts for automating tasks related to development, testing, and deployment. See [scripts] below.
+
+**`.github/workflows/`** :
+   GitHub Actions workflows for CI/CD, defining automated build, test, and deployment processes.
+
+## Quality Assurance Paths
+
+Any files containing _requirements_, _specifications_, _definitions_, _schemas_, or _tests_ should be stored in the `specs/` directory, as detailed in [DocOps Lab Testing & Specifications](/docs/testing/).
+
+**`specs/`** :
+   General directory for content that specifies, defines, or tests elements of the product. See [DocOps Lab Testing & Specifications](/docs/testing/).
+
+   **`specs/data/`** :
+      Definition and schema files.
+
+   **`specs/tests/rspec/`** :
+      RSpec tests for Ruby codebases.
+
+   **`../<product-slug>-demo/`** :
+      Major products typically have a sibling repo that serves as a proving grounds and/or for demonstrative purposes.
+
+## Generative AI Paths
+
+**`.github/copilot-instructions.md`** :
+   Instructions for GitHub Copilot, providing guidance on how any cloud-based GH Copilot assistance should be oriented toward a given codebase.
+
+**`AGENTS.md`** :
+   General for _local_ coding agents. May duplicate `.github/copilot-instructions.md` or provide additional context.
+
+**`.agent/`** :
+   A directory for temporary/scratch files used by local coding agents.
+

data/docs/agent/topics/dev-tooling-usage.md

@@ -0,0 +1,202 @@
+# AI Agent Instructions for In-house Dev-Tooling Usage
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+This guide pertains to the `docopslab-dev` environment. For complete documentation, see the [project’s README](https://github.com/DocOps/lab/blob/main/gems/docopslab-dev/README.adoc).
+
+> **IMPORTANT:** The environment described and provided here is _not_ optimized for DocOps Lab _applications_ used in third-party projects. For your own applications of DocOps Labs products like ReleaseHx and Issuer, see [DocOps Box](https://github.com/DocOps/box) for a full-featured docs-focused workspace, runtime, and production environment.
+
+This gem mainly supplies rake tasks for performing common development operations across unified configurations and sub-libraries.
+
+Table of Contents
+
+- Standard Usage
+- Override Commands
+- More Example Commands
+- Tasks and Workflow
+- Typical Workflow
+- Customization
+- Local Overrides
+
+## Standard Usage
+
+Run all linters
+
+```
+bundle exec rake labdev:lint:all
+```
+
+Auto-fix safe issues
+
+```
+bundle exec rake labdev:heal
+```
+
+## Override Commands
+
+Most executions of the packaged tools are handled through Rake tasks, but you can always run them directly, especially to pass arguments not built into the tasks.
+
+**RuboCop** :
+   ```
+   bundle exec rubocop --config .config/rubocop.yml [options]
+   bundle exec rubocop --config .config/rubocop.yml --auto-correct-all
+   bundle exec rubocop --config .config/rubocop.yml --only Style/StringLiterals
+   ```
+
+**Vale** :
+   ```
+   vale --config=.config/vale.ini [options] [files]
+   vale --config=.config/vale.ini README.adoc
+   vale --config=.config/vale.ini --minAlertLevel=error .
+   ```
+
+**HTMLProofer** :
+   ```
+   bundle exec htmlproofer --ignore-urls "/www.github.com/,/foo.com/" ./_site
+   ```
+
+## More Example Commands
+
+Lint specific Ruby file with specific rule
+
+```
+bundle exec rake 'labdev:lint:ruby[lib/myfile.rb,Style/StringLiterals]'
+```
+
+Lint all AsciiDoc files for a specific Vale rule
+
+```
+bundle exec rake 'labdev:lint:adoc[,DocOpsLab-Authoring.ExNotEg]'
+```
+
+Lint specific shell script
+
+```
+bundle exec rake 'labdev:lint:bash[scripts/docksh]'
+```
+
+Lint specific file with Vale (text mode)
+
+```
+bundle exec rake 'labdev:lint:text[_docs/myfile.adoc]'
+```
+
+Show a specific lint rule profile
+
+```
+bundle exec rake 'labdev:show:rule[vale,RedHat]'
+```
+
+## Tasks and Workflow
+
+```
+bundle exec rake --tasks | grep labdev:
+```
+
+> **TIP:** To hide the `labdev:` tasks from the standard `rake --tasks` output for an integrated project, use:
+>
+>
+>
+>
+>
+> ```
+> bundle exec rake --tasks | grep -v labdev:
+> ```
+
+### Typical Workflow
+
+This tool is for working on DocOps Lab projects or possibly unrelated projects that wish to follow our methodology. A typical workflow might look as follows.
+
+Normal development
+
+```
+git add .
+git commit -m "Add new feature"
+```
+
++ This should yield warnings and errors if active linters find issues.
+
+1. Auto-fix what you can.
+
+```
+bundle exec rake labdev:heal
+```
+2. Review the changes.
+
+```
+git diff
+```
+3. Commit the fixes.
+
+```
+git add -A
+git commit -m "Auto-fix linting issues"
+```
+4. Handle any remaining manual fixes.
+
+```
+bundle exec rake labdev:lint:all
+```
+5. Fix remaining issues manually.
+
+```
+git add -A
+git commit -m "Fix remaining linting issues"
+```
+6. Try pushing.
+
+```
+git push
+```
+
+If all blocking issues are cleared, the push should succeed. Otherwise, more cleanup is needed.
+
+> **TIP:** Bypass the pre-push gates (usually to test or demo the failure at origin):
+>
+>
+>
+>
+>
+> ```
+> git push --no-verify
+> ```
+
+## Customization
+
+Override settings by editing the project configs:
+
+- `.config/docopslab-dev.yml`
+- `.config/rubocop.yml`
+- `.config/vale.ini`
+- `.config/htmlproofer.yml`
+- `.config/actionlint.yml`
+- `.config/shellcheckrc`
+
+Your configurations will inherit from the base configurations and source libraries as sourced in the Git-ignored `.config/.vendor/docopslab/` path.
+
+### Local Overrides
+
+Projects using `docopslab-dev` will have a configuration structure like the following:
+
+```tree
+config/
+├── docopslab-dev.yml # Project manifest (tracked)
+├── actionlint.yml # Project config (tracked; inherits from base)
+├── htmlproofer.local.yml # Project config (tracked; inherits from base)
+├── htmlproofer.yml # Generated config (untracked)
+├── rubocop.yml # Project config (tracked; inherits from base)
+├── shellcheckrc # ShellCheck config (tracked)
+├── vale.ini # Generated active config (untracked)
+├── vale.local.ini # Project config (tracked; inherits from base)
+├── .vendor/ # Base configs (untracked; synced)
+│ └── docopslab/
+│ ├── htmlproofer.yml # Centrally managed base
+│ ├── rubocop.yml # Centrally managed base
+│ └── vale.ini # Centrally managed base
+scripts/ # Project override scripts
+    └── .vendor/ # Centrally managed scripts
+.github/workflows/ # CI/CD workflows (tracked)
+env.docopslab # Environment variables (git tracked)
+env.private # Environment variables (git ignored)
+```
+

data/docs/agent/topics/devops-ci-cd.md

@@ -0,0 +1,55 @@
+# AI Agent Orientation to DocOps Lab DevOps/CI/CD Practices
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+DocOps Lab is in a very nascent stage of establishing shared (cross-repo) tools, workflows, and protocols to for automating development, integration, build, and deployment processes.
+
+DocOps Lab uses GitHub Actions and Docker as primary platforms for integration and deployment automation.
+
+For now you can get a good idea for getting started with automation by checking the standard paths in the current project (`Dockerfile`, `docker-compose.yml`, `.github/workflos/`, `Rakefile`, `scripts/`) as well as looking at similar DocOps Lab projects that have more established CI/CD workflows.
+
+The rest of this document is snippets from various relevant internal documentation.
+
+Table of Contents
+
+- Common Automation Scripts
+- Docker Usage
+- Application Dockerfiles and Images
+- See Also
+
+## Common Automation Scripts
+
+Some DocOps Lab projects include highly customized automation scripts, but most contain or employ some common scripts that are primarily stored in this repository and/or deployed as Docker images for universal access during development, testing, and deployment.
+
+These procedures can always be invoked by way of local scripts located in `scripts/`. These include:
+
+- `build.sh`
+- `publish.sh`
+
+Common scripts are managed through the lnk:/docs/lab-dev-setup/[`docopslab-dev` gem].
+
+Ruby projects will generally include a `Rakefile` (in the base directory), which automates various Ruby tasks.
+
+## Docker Usage
+
+DocOps Lab projects make extensive use of Docker.
+
+All runtime projects provide have their own Docker image hosted on Docker Hub and sourced in their own repo’s `Dockerfile`. This way a reliable executable is available across all platforms and environments.
+
+Some of our CI/CD pipelines will be “Dockerized” to provide consistent builds and tests across numerous repos.
+
+The DocOps Box project maintains an elaborate Dockerfile and image/container management script (`docksh`) that can help manage multiple environments. This is most advantageous for non-Ruby/non-programmer users building a complex documentation codebase in the Ruby/DocOps Lab ecosystem or using multiple DocOps Lab or similar tools across numerous multiple codebases.
+
+### Application Dockerfiles and Images
+
+Each runtime application project has its own `Dockerfile` in the root of its repository.
+
+This Dockerfile defines the image that will be built and pushed to Docker Hub for use by anyone needing to run the application.
+
+> **NOTE:** Some Dockerfiles combine multiple applications, such as the [issuer-rhx image](https://github.com/DocOps), which combines both the Issuer and ReleaseHx applications.
+
+## See Also
+
+- `./dev-tooling-usage.md`
+- `../skills/git.md`
+

data/docs/agent/topics/product-docs-deployment.md

@@ -0,0 +1,25 @@
+# Product Documentation Deployment
+
+This document is intended for AI agents operating within a DocOps Lab environment.
+
+Most DocOps Lab projects have their own documentation sites, also built with Jekyll and AsciiDoc, often including YARD for Ruby API reference generation.
+
+For less-formalized projects, documentation is restricted to `README.adoc` and other `*.adoc` files. These are hosted as GitHub Pages sites from their respective repositories, but using a consistent URL structure centered on the `docopslab.org` domain hosted here.
+
+The URL structure is as follows:
+
+**Project landing page** :
+   `https://<project>.docopslab.org/`
+
+   At a minimum, this should be a subset of the `README.adoc` file.
+
+**Product user docs** :
+   `https://<project>.docopslab.org/docs/`
+
+**Product developer docs** :
+   `https://<project>.docopslab.org/docs/api/(<apiname>/)`
+
+   The final `<apiname>` directory is only applicable when the product contains multiple distinct APIs.
+
+GH Pages configuration for these sites enables deployment by way of a clean `gh-pages` branch containing only generated documentation artifacts and the `CNAME` file.
+

data/lib/docopslab/dev/auto_fix_asciidoc.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+# File to be called by DocOpsLab::Dev to auto-fix AsciiDoc files
+module DocOpsLab
+  module Dev
+    module AutoFixAsciidoc
+      class << self
+        def fix_asciidoc_files _context, path: nil
+          # use the find_asciidoc_files method if no path is passed
+          adoc_files = if path
+                         if File.directory?(path)
+                           Dir.glob(File.join(path, '**', '*.adoc'))
+                         elsif File.file?(path) && File.extname(path) == '.adoc'
+                           [path]
+                         else
+                           puts "❌ Invalid path specified for AsciiDoc auto-fix: #{path}"
+                           return false
+                         end
+                       else
+                         Dev.find_asciidoc_files
+                       end
+
+          if adoc_files.empty?
+            puts '✅ No AsciiDoc files found for auto-fix'
+            return true
+          end
+
+          fixed_count = 0
+
+          adoc_files.each do |file_path|
+            File.read(file_path)
+            Dev.run_script('adoc_section_ids.rb', [file_path])
+          end
+
+          if fixed_count.positive?
+            puts "✅ AsciiDoc auto-fix complete; #{fixed_count} files modified"
+          else
+            puts '✅ All AsciiDoc files are already compliant'
+          end
+
+          true
+        end
+      end
+    end
+  end
+end

data/lib/docopslab/dev/checkers.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module DocOpsLab
+  module Dev
+    module Checkers
+      class << self
+        def lab_dev_mode?
+          # Detect if we are running inside the DocOps/lab monorepo
+          Dir.exist?('gems/docopslab-dev')
+        end
+
+        def gem_sourced_locally?
+          # Check if the gem is being used via a path dependency (development mode)
+          # This is true when running from issuer, releasehx, etc. with path: '../lab/gems/docopslab-dev'
+          # The GEM_ROOT will point to a local filesystem path rather than a gem installation
+          !GEM_ROOT.include?('/gems/') || GEM_ROOT.include?('/lab/gems/docopslab-dev')
+        end
+
+        def check_ruby_version
+          expected_version = RUBY_TARGET
+          current_version = RUBY_VERSION
+
+          puts "Ruby version: #{current_version}"
+
+          if current_version == expected_version
+            puts "✅ Ruby version matches DocOps Lab standard (#{expected_version})"
+          else
+            puts "⚠️  Ruby version differs from DocOps Lab standard (#{expected_version})"
+          end
+
+          if File.exist?('.ruby-version')
+            file_version = File.read('.ruby-version').strip
+            puts "📄 .ruby-version file specifies: #{file_version}"
+
+            if file_version == expected_version
+              puts '✅ .ruby-version matches DocOps Lab standard'
+            else
+              puts '⚠️  .ruby-version differs from DocOps Lab standard'
+            end
+          else
+            puts 'ℹ️  No .ruby-version file found'
+          end
+        end
+
+        def check_config_structure context
+          puts "\n📋 Configuration Status:"
+
+          manifest = context.load_manifest
+
+          if manifest
+            puts '✅ Manifest found: .config/docopslab-dev.yml'
+          else
+            puts "❌ No manifest found; run 'labdev:init:all' to create one"
+            return
+          end
+
+          # Check configs for each tool in manifest
+          manifest['tools']&.each do |tool_entry|
+            tool_slug = tool_entry['tool']
+            tool_meta = context.get_tool_metadata(tool_slug)
+            tool_name = tool_meta ? tool_meta['name'] : tool_slug
+            tool_enabled = tool_entry.fetch('enabled', true)
+
+            unless tool_enabled
+              puts "⏭️  #{tool_name}: disabled in manifest"
+              next
+            end
+
+            files = context.get_tool_files(tool_slug)
+
+            unless files[:project]
+              puts "⚠️  #{tool_name}: no project config defined in manifest"
+              next
+            end
+
+            project_path = files[:project][:local]
+            unless project_path && File.exist?(project_path)
+              puts "❌ No #{tool_name} project config found; run 'labdev:init:all' to create one"
+              next
+            end
+
+            # Check for base config if tool uses vendor base
+            if files[:base] && tool_meta && tool_meta['config']['uses_vendor_base']
+              base_status = File.exist?(files[:base][:local]) ? '✅' : '❌'
+              puts "✅ #{tool_name} project config: #{project_path} (base: #{base_status})"
+            else
+              puts "✅ #{tool_name} project config: #{project_path}"
+            end
+          end
+        end
+
+        def check_standard_rake_tasks
+          # Checks local Rakefile for presence of standard (non-labdev) tasks
+          standard_tasks = %w[rspec cli_test yaml_test pr_test install_local]
+          missing_tasks = []
+          standard_tasks.each do |task_name|
+            missing_tasks << task_name unless Rake::Task.task_defined?(task_name)
+          end
+          if missing_tasks.empty?
+            puts '✅ All standard Rake tasks are present'
+          else
+            puts "❌ Missing standard Rake tasks: #{missing_tasks.join(', ')}"
+          end
+        end
+      end
+    end
+  end
+end