AGENTS.md

Project Guidelines

Architecture

• This repo has two main testing domains:
  • Ruby tooling code in lib/ with tests in test/ (Minitest).
  • Dev Container Features in features/src/* with integration tests in features/test/* (devcontainer CLI + shell scripts/scenarios).
• Entry-point scripts in bin/ usually orchestrate updates that must be validated by Ruby tests and feature tests.

Build and Test

• Prefer running the smallest relevant test set first, then broader suites.

Ruby tests (root)

• Install deps: bundle install
• Run all Ruby tests: bundle exec rake test
• Equivalent: rake test

Feature tests (from repo root)

• Install Node deps (if needed): npm install
• Run all feature tests via package script: npm test
• Preferred shortcut via Rake: rake features:test

Feature tests (targeted, from repo root)

• Prerequisite: install project deps from repo root (npm install) to get the devcontainer CLI from package.json.
• Autogenerated tests for one feature:
  • rake features:autogenerated FEATURE=ruby IMAGE=ubuntu:latest
• Scenario tests for one feature:
  • rake features:scenarios FEATURE=ruby
• Direct CLI equivalents (run from features/):
  • npx devcontainer features test --skip-scenarios -f ruby -i ubuntu:latest .
  • npx devcontainer features test -f ruby --skip-autogenerated --skip-duplicated .

Shell script linting (from features/)

• find . -name "*.sh" -type f -exec shellcheck {} +

Conventions

• Keep tests close to the affected area:
  • lib/** changes should include/adjust test/**/*_test.rb.
  • features/src/<name>/** changes should include/adjust features/test/<name>/**.
• Preserve current patterns in existing tests:
  • Ruby tests use Minitest style and temp-directory isolation.
  • Feature tests use dev-container-features-test-lib assertions (check, reportResults) and scenario matrices in scenarios.json.