dataJAR-recipes copilot-instructions.md

AutoPkg Recipe Linter Suite - AI Coding Agent Instructions

Project Overview

This is a suite of Python linters for validating and fixing AutoPkg recipes. AutoPkg recipes are XML plist or YAML files that automate software packaging for macOS. Each linter is a standalone script in its own directory that detects and fixes specific issues in recipe files.

Architecture: Unified CLI runner (autopkg-linter.py) + 16 independent linter modules, each following the same pattern.

Critical Environment Requirement

⚠️ All scripts MUST run using AutoPkg's Python: /usr/local/autopkg/python

Every script includes verify_environment() that checks sys.executable.startswith('/usr/local/autopkg'). This is not optional - AutoPkg recipes require AutoPkg's Python environment with its specific dependencies (plistlib, etc.).

Linter Architecture Pattern

Each linter follows this structure:

LinterName/
├── LinterName.py          # Main script with main() function
├── README.md              # Detailed documentation
└── __pycache__/          # Python bytecode cache

Standard Linter Structure

Every linter script contains:

1. Shebang: #!/usr/local/autopkg/python
2. verify_environment(): Validates Python path
3. clean_path(): Handles drag-and-drop paths with escaped spaces
4. process_plist_recipe(): Logic for XML plist recipes
5. process_yaml_recipe(): Logic for YAML recipes (if applicable)
6. main(): Interactive prompt for recipe directory, then scans/processes files

Recipe Format Handling

• Plist recipes (.recipe): XML plist format using plistlib
• YAML recipes (.yaml): YAML format using yaml module
• Most linters support both formats with separate processing functions
• Some operations (e.g., XML escaping) only apply to plist format

Suite Runner Integration

autopkg-linter.py dynamically loads and runs linters:

1. get_available_linters(): Returns list of (number, name, directory, script, description) tuples
2. load_linter_module(): Uses importlib.util.spec_from_file_location() to load scripts
3. run_linter(): Temporarily overrides sys.argv and __builtins__.input to inject recipe directory and auto-answer prompts in bulk mode
4. Modes:
   • bulk: Auto-provides recipe directory + default answers to all prompts
   • interactive: Provides recipe directory, then allows user interaction