AUTO-GENERATED from .model-context/

DO NOT EDIT DIRECTLY

Last synced: 2025-10-25 10:34:16 UTC

OpenAI Codex Agent Instructions

https://github.com/openai/codex

homebrew-jdk26ea - Repository Context

Project Overview

Repository: https://github.com/Artagon/homebrew-jdk26ea Purpose: Homebrew tap providing automated distribution of OpenJDK 26 Early Access builds Current Version: JDK 26 EA Build 20 (Released: 2025-10-17) License: GPL-2.0 with Classpath Exception (matching OpenJDK)

This is a Homebrew tap that automates the distribution and updating of JDK 26 Early Access builds from jdk.java.net/26. It provides both a cask (native macOS app installation) and a formula (command-line package) for cross-platform support.

Architecture

Distribution Methods

Cask (Casks/jdk26ea.rb) - macOS only
- Installs to: /Library/Java/JavaVirtualMachines/jdk-26-ea.jdk
- Integrates with macOS Java management system
- Uses secure ditto command for installation
- Path validation to prevent directory traversal attacks
- Supports both ARM64 (Apple Silicon) and Intel x64
Formula (Formula/jdk26ea.rb) - macOS and Linux
- Creates symlinks in Homebrew bin directory
- Cross-platform (macOS ARM64/x64, Linux ARM64/x64)
- Used for scripting and server environments

Platform Support

Platform	Architecture	Cask	Formula	CI Tested
macOS 13	Intel x64	✅	✅	✅
macOS 14	Apple Silicon ARM64	✅	✅	✅
Linux (Ubuntu 22.04)	x64	❌	✅	✅
Linux (Ubuntu 24.04)	x64	❌	✅	✅
Linux	ARM64	❌	✅	❌

Key Technologies

Ruby - Homebrew DSL for formula/cask definitions
Bash/Shell - Update automation scripts
YAML - GitHub Actions workflows
GitHub Actions - CI/CD platform (5 active workflows)
Homebrew - Package manager and distribution platform

Directory Structure

homebrew-jdk26/
├── .github/
│   ├── workflows/           # GitHub Actions automation
│   │   ├── audit.yml        # Weekly syntax validation
│   │   ├── auto-update.yml  # Daily auto-update checks
│   │   ├── release.yml      # Automated GitHub releases
│   │   ├── validate.yml     # CI validation on push/PR
│   │   └── update.yml       # Manual update workflow
│   ├── ISSUE_TEMPLATE/      # Issue templates
│   └── pull_request_template.md
├── .githooks/               # Git commit message validation
│   └── commit-msg           # Semantic commit enforcement
├── Formula/
│   └── jdk26ea.rb          # Homebrew formula (cross-platform)
├── Casks/
│   └── jdk26ea.rb          # Homebrew cask (macOS only)
├── scripts/
│   └── update.sh           # Manual update script
├── README.md
└── .gitignore

Automated Workflows

1. Auto-Update (`auto-update.yml`)

Frequency: Daily at 6:00 AM UTC
Purpose: Check for new JDK 26 EA builds and create PRs automatically
Process:
1. Scrapes jdk.java.net/26 for latest build number
2. Downloads SHA256 checksums from official sources
3. Updates cask and formula with new version/checksums
4. Validates Ruby syntax
5. Creates PR with detailed changelog
6. Applies labels: automated, update

2. Release (`release.yml`)

Trigger: When Formula/Casks files change on main branch
Purpose: Create GitHub releases automatically
Process:
1. Audits cask before release
2. Extracts version and build number
3. Generates changelog from git commits
4. Updates README with new version/date
5. Creates GitHub pre-release
6. Documents platform support

3. Validate (`validate.yml`)

Trigger: Push to main, pull requests
Purpose: Comprehensive CI testing across platforms
Jobs:
- validate-syntax: Ruby syntax, brew style, brew audit
- test-install-macos: Tests on macOS 13 and 14
- test-install-linux: Tests on Ubuntu 22.04 and 24.04
Testing: Verifies installation, runs java -version, compiles HelloWorld.java

4. Audit (`audit.yml`)

Frequency: Weekly on Monday at 12:00 PM UTC
Purpose: Manual syntax validation checks
Can be triggered: Via workflow_dispatch

Coding Standards

Semantic Commits

Enforced via git hooks (.githooks/commit-msg)

Format: type(scope): description

Valid types:

feat - New feature
fix - Bug fix
docs - Documentation changes
style - Code style (formatting)
refactor - Code refactoring
perf - Performance improvements
test - Test changes
chore - Build process or tooling
ci - CI configuration changes

Valid scopes:

cask - Cask file changes
formula - Formula file changes
workflow - GitHub Actions changes
docs - Documentation changes
scripts - Script changes

Examples:

feat(cask): add support for JDK 26 EA Build 21
fix(formula): correct SHA256 checksum for Linux ARM64
docs: update README with new installation instructions
chore(workflow): update auto-update schedule

Breaking Changes:

feat(cask)!: rename from jdk26valhalla to jdk26ea

BREAKING CHANGE: Users must uninstall old cask and reinstall with new name

Ruby Style

Follows Homebrew's RuboCop rules
Enforced via brew style and brew audit
Stanza ordering in casks matters
Empty lines between stanza groups required
No logical operators in unless statements

Security Practices

Cask Installation Security

Path Validation
- Uses realpath to resolve symlinks
- Validates JDK bundle is within staging area
- Prevents directory traversal attacks
- Validates paths don't escape staging
Secure Copying
- Uses Apple's ditto instead of external rsync
- ditto is Apple-signed and part of macOS
- Better metadata preservation (ACLs, extended attributes)
- --noqtn flag prevents quarantine issues
Error Handling
- Uses system_command! for immediate error detection
- Uses odie for fatal errors (stops execution)
- Uses ohai for user-facing messages
- Validates source exists before operations

Download Verification

SHA256 checksums for all platform downloads
Downloaded from official .sha256 files on download.java.net
Verified by Homebrew during installation
Four platforms verified independently:
- macOS ARM64
- macOS x64
- Linux ARM64
- Linux x64

Version Management

Version Format

26-ea+{build_number}

Example: 26-ea+20

Update Process

Automated:

auto-update.yml runs daily
Scrapes jdk.java.net/26 for new builds
Downloads checksums
Updates both cask and formula
Creates PR for review

Manual:

./scripts/update.sh

Version Locations

Casks/jdk26ea.rb - Line 2: version "26-ea+20"
Formula/jdk26ea.rb - Line 4: version "26-ea+20"
README.md - Line 30: Current version display

Testing

CI Test Matrix

Job	OS	Architecture	Package Type
test-install-macos	macOS 13	Intel x64	Cask
test-install-macos	macOS 14	Apple Silicon ARM64	Cask
test-install-linux	Ubuntu 22.04	x64	Formula
test-install-linux	Ubuntu 24.04	x64	Formula

Test Coverage

Each test verifies:

Installation succeeds
java -version executes
javac -version executes (Linux only)
Can compile HelloWorld.java (Linux only)
Can run compiled Java programs (Linux only)
JAVA_HOME setup works (Linux only)

Local Testing

Cask:

brew install --cask Casks/jdk26ea.rb
java -version
brew uninstall --cask jdk26ea

Formula:

brew install Formula/jdk26ea.rb
java -version
brew uninstall jdk26ea

Common Tasks

Update to New JDK Build

Automated: Wait for auto-update.yml to create PR

Manual:

./scripts/update.sh
git add Formula/jdk26ea.rb Casks/jdk26ea.rb
git commit -m "feat: update to JDK 26 EA Build XX"

Fix RuboCop Violations

# Check style
brew style Casks/jdk26ea.rb
brew style Formula/jdk26ea.rb

# Audit
brew audit --cask Casks/jdk26ea.rb

# Validate syntax
ruby -c Casks/jdk26ea.rb
ruby -c Formula/jdk26ea.rb

Create Release

Releases are automated when version changes on main branch.

Manual trigger:

# Push version change to main
git push origin main

# Release workflow triggers automatically
# Creates GitHub release with pre-release flag

Important Files

Configuration Files

.gitignore - Excludes macOS, Homebrew, and temp files
.githooks/commit-msg - Semantic commit validation
CODEOWNERS - Code ownership (@you owns all)

Documentation

README.md - User-facing documentation
.github/ISSUE_TEMPLATE/ - Issue templates
.github/pull_request_template.md - PR template

Scripts

scripts/update.sh - Manual update automation
- Scrapes jdk.java.net/26
- Downloads SHA256 checksums
- Updates cask and formula
- Validates syntax
- Colored output

External Dependencies

Data Sources

https://jdk.java.net/26/ - Official JDK 26 EA page
https://download.java.net/java/early_access/jdk26/{build}/GPL/ - Binary downloads
Accompanying .sha256 files for checksums

GitHub Actions

actions/checkout@v4 - Checkout repository
Homebrew/actions/setup-homebrew@master - Setup Homebrew on Linux

Known Limitations

Linux ARM64 not tested in CI - Requires self-hosted runners
Early Access only - Not production-ready
Single maintainer - All owned by @you
Web scraping dependency - Relies on jdk.java.net page structure

Maintenance Notes

Branch Protection

main branch requires PR
Validate status check required
No force pushes allowed
Auto-delete merged branches

Git Configuration

This repository uses a dedicated SSH identity:

Host: github.com-artagon
User: trumpyla@gmail.com
Identity file: ~/.ssh/id_trumpyla@gmail.com

Recent Changes

Removed issue-commands.yml (security concern)
Removed CONTRIBUTING.md (simplified docs)
Replaced rsync with ditto (security)
Added comprehensive CI testing
Repository renamed from jdk26valhalla to jdk26ea

Troubleshooting

RuboCop Violations

Check stanza ordering (sha256 before url)
Ensure empty lines between stanza groups
Avoid logical operators in unless

Installation Failures

Verify SHA256 checksums match official sources
Check JDK bundle naming matches jdk-*.jdk pattern
Ensure sufficient permissions for /Library/Java/JavaVirtualMachines/

CI Failures

Check Ruby syntax: ruby -c Casks/jdk26ea.rb
Run brew audit: brew audit --cask Casks/jdk26ea.rb
Verify all platform URLs are accessible
Confirm checksums are correct

Project History

Originally homebrew-jdk26valhalla for Project Valhalla
Renamed to homebrew-jdk26ea for general EA builds
Build 20 current as of 2025-10-17
31 commits total
Active maintenance and improvements ongoing

AI Assistant Instructions for homebrew-jdk26ea

Domain-Specific Skills

This repository uses domain-organized skill files for specialized expertise. AI assistants should reference these files for detailed guidance in each area:

Core Skills

Homebrew Development - Formula and cask development, security patterns, validation
GitHub Workflows - Actions security, input validation, workflow patterns
Shell Scripting - Bash best practices, error handling, safe patterns
Security Practices - Input validation, path traversal prevention, cryptographic verification
Development Workflow - Git workflows, PR management, code review
Semantic Commits - Conventional commits, changelog generation

Project-Specific Requirements

Repository Context

Purpose: Homebrew tap for OpenJDK 26 Early Access builds
Platforms: macOS (ARM64, x64), Linux (ARM64, x64)
Automation: Daily auto-updates, automated releases, multi-platform CI testing

Commit Requirements

All commits MUST follow Conventional Commits format. See semantic-commits.md for details.

Quick Reference:

type(scope): description

Valid types: feat, fix, docs, style, refactor, perf, test, chore, ci
Valid scopes: cask, formula, workflow, docs, scripts

Examples:

feat(cask): add support for JDK 26 EA Build 21
fix(formula): correct SHA256 checksum for Linux ARM64
ci(workflow): pin action to commit SHA for security

File Structure

homebrew-jdk26/
├── Casks/jdk26ea.rb           # macOS cask
├── Formula/jdk26ea.rb         # Linux/macOS formula
├── .github/workflows/         # CI/CD automation
├── scripts/                   # Update and sync scripts
└── .model-context/            # AI configuration
    ├── skills/               # Domain-specific skills
    ├── shared/               # Shared context
    └── agents/               # Agent-specific overrides

Version Updates

When updating to a new JDK build:

Update version in both Casks/jdk26ea.rb and Formula/jdk26ea.rb
Download and verify checksums for all 4 platforms
Validate changes with brew style and brew audit
Commit with semantic message: feat: update to JDK 26 EA Build XX

Reference Skills:

Security Requirements

Critical Rules:

Pin ALL GitHub Actions to commit SHAs → github-workflows.md
Validate ALL external inputs → security.md
Verify checksums before use → security.md
Use realpath for path operations → homebrew.md
Quote all shell variables → shell-scripts.md

Testing Requirements

Before Committing:

# Syntax validation
ruby -c Casks/jdk26ea.rb
ruby -c Formula/jdk26ea.rb

# Style checking
brew style Casks/jdk26ea.rb Formula/jdk26ea.rb

# Audit
brew audit --cask Casks/jdk26ea.rb
brew audit --formula Formula/jdk26ea.rb

CI Testing:

macOS 13, 14 (cask installation)
Ubuntu 22.04, 24.04 (formula installation)
Syntax and style validation
Functional tests (java -version, compile HelloWorld)

Workflow Patterns

Feature Development:

# Create feature branch
git checkout -b feat/description

# Make changes with semantic commits
git commit -m "feat(cask): add support for new feature"

# Push and create PR
git push -u origin feat/description
gh pr create --title "feat: description" --body "..."

Reference:

Automation

Daily Auto-Updates (6 AM UTC):

Scrapes https://jdk.java.net/26/ for new builds
Downloads and verifies checksums
Creates PR if new build available

Automated Releases (on main branch push):

Validates syntax and style
Runs multi-platform tests
Creates GitHub release with changelog

Reference:

Quick Reference: Common Tasks

Task: Add New JDK Build

Run ./scripts/update.sh <build-number> or update manually
Verify checksums for all 4 platforms
Test: brew style and brew audit
Commit: feat: update to JDK 26 EA Build XX
Push and create PR

Skills: homebrew.md, security.md

Task: Fix Security Issue

Identify vulnerability
Create branch: fix/security-issue-name
Apply fix following security best practices
Add tests if applicable
Commit: fix(scope): description with security note
Create PR with security context

Skills: security.md, github-workflows.md

Task: Update GitHub Workflow

Validate YAML syntax
Pin all actions to commit SHAs
Validate inputs and add error handling
Test in fork if possible
Commit: ci(workflow): description
Monitor workflow runs after merge

Skills: github-workflows.md, security.md

Task: Write Shell Script

Start with strict mode: set -euo pipefail
Add input validation
Implement error handling (trap)
Quote all variables
Test with ShellCheck
Commit: chore(scripts): description

Skills: shell-scripts.md, security.md

Error Prevention

Common Mistakes

❌ Don't:

Skip brew style validation
Hardcode SHA256 checksums without verification
Use unpinned GitHub Actions
Commit without semantic format
Update README version manually (automated)
Use rsync in cask postflight (use ditto)

✅ Do:

Run validation before every commit
Download and verify checksums
Pin actions to commit SHAs with version comments
Follow Conventional Commits format
Let automation handle README updates
Use ditto (Apple-signed) for file operations

Emergency Procedures

If auto-update creates bad PR:

Close the PR
Fix issue locally
Let auto-update run again next day, or
Create manual PR with fix

If release fails:

Check workflow logs for errors
Fix validation/test failures
Re-push to main (triggers re-run)

If CI failing:

Check RuboCop violations
Verify SHA256 checksums
Test locally when possible
Review detailed workflow logs

Repository Operations

All repository operations should follow the guidelines in:

Development Workflow for Git operations
Semantic Commits for commit messages
GitHub Workflows for CI/CD changes

Summary

This repository values:

Security - Path validation, secure commands, checksum verification
Automation - Daily updates, automatic releases, comprehensive CI
Quality - RuboCop enforcement, semantic commits, multi-platform testing
Simplicity - Clear documentation, skill-based organization
Reliability - Early detection, rollback capabilities

When in doubt:

Consult relevant skill file for detailed guidance
Prioritize security over convenience
Let automation handle routine tasks
Follow semantic commit format
Test before committing

Security Guidelines for homebrew-jdk26ea

1. GitHub Actions Security

Pin Actions to Commit SHAs

NEVER use tags or branches (they're mutable)
ALWAYS use full commit SHA with version comment
Example: uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1

Token Security

Never expose tokens in curl commands
Use gh CLI for GitHub API calls
Pass secrets via environment variables only
Use minimal permissions (contents: read, pull-requests: write)

Input Validation

Validate ALL external inputs with regex
Build numbers: ^[0-9]{1,3}$ (range: 1-999)
URLs: Must match https://download.java.net/java/early_access/...
SHA256: ^[a-f0-9]{64}$
Reject invalid inputs immediately

Checksum Verification

Download files AND verify checksums (don't just fetch checksums)
Compare expected vs actual before using values
Fail workflow if verification fails

2. Cask/Formula Security

Path Validation

Use realpath to resolve all symlinks
Validate paths stay within staging area
Check: path.to_s.start_with?(staged_root.to_s)
Validate candidate count: odie if not exactly 1

Command Execution

Use system_command! (with !) to fail fast
Use ditto instead of rsync (Apple-signed)
Pass args as array (never string interpolation)
Use sudo only for system locations

Error Handling

Use odie for fatal errors (stops execution)
Use ohai for user messages
Use opoo for warnings (non-fatal)
Never silently continue on errors

3. Workflow Permissions

Minimal Permissions

# For auto-update PRs
permissions:
  contents: read
  pull-requests: write

# For releases
permissions:
  contents: write

Avoid Direct Commits

Create PRs instead of pushing to main
Exception: Documentation-only auto-updates with clear justification
Always respect branch protection rules

4. Common Vulnerabilities

Vulnerability	Fix
Unpinned actions	Pin to commit SHA
Token in curl	Use gh CLI
No input validation	Add regex validation
No checksum verify	Download and verify
Excessive permissions	Use minimal permissions
Direct commits to main	Create PRs

5. New Security Rule

Always validate API responses

Code Style Guide for homebrew-jdk26ea

Commit Messages

Format

type(scope): description

[optional body]

Valid Types

feat - New feature
fix - Bug fix
docs - Documentation only
style - Code formatting
refactor - Code refactoring
perf - Performance improvements
test - Adding/modifying tests
chore - Build process, dependencies
ci - CI configuration changes

Valid Scopes

cask - Changes to Casks/jdk26ea.rb
formula - Changes to Formula/jdk26ea.rb
workflow - GitHub Actions workflows
docs - Documentation changes
scripts - Script changes

Examples

feat(cask): add support for JDK 26 EA Build 21
fix(formula): correct SHA256 checksum for Linux ARM64
ci(workflow): pin action to commit SHA for security
docs: update README with installation instructions

Ruby/Homebrew Style

Before Committing

Validate syntax: ruby -c Casks/jdk26ea.rb
Check style: brew style Casks/jdk26ea.rb
Run audit: brew audit --cask Casks/jdk26ea.rb

Cask Stanza Ordering

arch declaration
version
sha256 (before url!)
url
name
desc
homepage
postflight
uninstall

Common Issues

Missing empty lines between stanza groups
SHA256 after URL (should be before)
Logical operators in unless (use if with negation)

Workflow Style

YAML Structure

Use consistent indentation (2 spaces)
Add comments for complex logic
Name all steps clearly
Group related steps

Security Annotations

# Pin to commit SHA with version comment
- uses: actions/checkout@a1b2c3d...  # v4.1.1

# Document why permissions are needed
permissions:
  contents: read      # Checkout repository
  pull-requests: write  # Create update PRs

Testing

Required Tests

Syntax validation (all files)
Style checks (brew style)
Audit checks (brew audit)
Installation tests (macOS 13, 14, Ubuntu 22.04, 24.04)
Functional tests (java -version, compile HelloWorld)

CI Expectations

All jobs must pass
No RuboCop violations
No audit failures
Successful installation on all platforms

OpenAI Codex Specific Instructions

Configuration

OpenAI Codex loads from AGENTS.md in project root (auto-generated from shared context)

Codex-Specific Features

Terminal-based coding agent
Multi-file editing capabilities
Git integration
Natural language to code translation
Inline code generation

Usage Patterns

When using OpenAI Codex:

Follow repository semantic commit conventions
Run validation scripts before committing
Use natural language for complex multi-file changes
Verify security guidelines for workflow changes
Check that all platforms have SHA256 checksums

Repository-Specific

Always use brew style before completing tasks
Validate commit messages match semantic format
Pin GitHub Actions to commit SHAs
Verify checksums for all platform downloads
Create PRs instead of direct commits to main

Uh oh!

FilesExpand file tree

AGENTS.md

Latest commit

History

AGENTS.md

File metadata and controls

AUTO-GENERATED from .model-context/

DO NOT EDIT DIRECTLY

Last synced: 2025-10-25 10:34:16 UTC

OpenAI Codex Agent Instructions

https://github.com/openai/codex

homebrew-jdk26ea - Repository Context

Project Overview

Architecture

Distribution Methods

Platform Support

Key Technologies

Directory Structure

Automated Workflows

1. Auto-Update (auto-update.yml)

2. Release (release.yml)

3. Validate (validate.yml)

4. Audit (audit.yml)

Coding Standards

Semantic Commits

Ruby Style

Security Practices

Cask Installation Security

Download Verification

Version Management

Version Format

Update Process

Version Locations

Testing

CI Test Matrix

Test Coverage

Local Testing

Common Tasks

Update to New JDK Build

Fix RuboCop Violations

Create Release

Important Files

Configuration Files

Documentation

Scripts

External Dependencies

Data Sources

GitHub Actions

Known Limitations

Maintenance Notes

Branch Protection

Git Configuration

Recent Changes

Troubleshooting

RuboCop Violations

Installation Failures

CI Failures

Project History

AI Assistant Instructions for homebrew-jdk26ea

Domain-Specific Skills

Core Skills

Project-Specific Requirements

Repository Context

Commit Requirements

File Structure

Version Updates

Security Requirements

Testing Requirements

Workflow Patterns

Automation

Quick Reference: Common Tasks

Task: Add New JDK Build

Task: Fix Security Issue

Task: Update GitHub Workflow

Task: Write Shell Script

Error Prevention

Common Mistakes

Emergency Procedures

Repository Operations

1. Auto-Update (`auto-update.yml`)

2. Release (`release.yml`)

3. Validate (`validate.yml`)

4. Audit (`audit.yml`)