Implement StructKit Composite Action

[httpdss]

Overview

This PR transforms the struct-action repository from a stub into a fully functional composite GitHub Action for StructKit. The action provides a flexible step that workflows can use to validate or generate project structures.

What's Changed

Core Action (action.yml)

• ✅ Composite action with comprehensive input options
• ✅ Support for both validate and generate commands
• ✅ Dry-run and diff modes for drift detection
• ✅ Flexible StructKit installation (PyPI, git URL, or specific version)
• ✅ Custom structures repository support
• ✅ Actionable outputs for downstream steps
• ✅ Version-compatible flag handling

Documentation

• ✅ Comprehensive README with usage examples
• ✅ Multiple copy-paste workflow examples
• ✅ Clear comparison with reusable workflow
• ✅ Troubleshooting guide
• ✅ Compatibility notes for different StructKit versions

Testing

• ✅ Test workflow with multiple scenarios
• ✅ Validates action functionality in CI
• ✅ All tests passing ✨

Examples

• ✅ PR validation workflow
• ✅ Drift detection workflow
• ✅ Generate and commit workflow
• ✅ Scheduled checks workflow
• ✅ Custom structures workflow

Other

• ✅ MIT License
• ✅ .gitignore for common patterns
• ✅ No trailing whitespace
• ✅ Pinned action versions

Key Features

Inputs

• command: validate | generate
• struct_file: path to .struct.yaml (default: .struct.yaml)
• output_dir: output directory (default: .)
• dry_run: preview changes without writing
• diff: show detailed diff of changes
• fail_on_diff: fail if changes detected (drift detection)
• no_hooks: disable hooks (check version compatibility)
• non_interactive: non-interactive mode (check version compatibility)
• structkit_version: version to install (default: latest)
• structures_repository: external structures repo
• extra_args: additional CLI arguments

Outputs

• success: command completion status
• has_changes: whether changes were/would be made
• diff_file: path to diff output
• exit_code: command exit code

Usage Examples

Validate on PR

- uses: httpdss/struct-action@v1
  with:
    command: validate

Detect Drift

- uses: httpdss/struct-action@v1
  with:
    command: generate
    dry_run: true
    fail_on_diff: true

Generate Files

- uses: httpdss/struct-action@v1
  with:
    command: generate

Design Decisions

1. Composite vs JavaScript: Chose composite action for simplicity and transparency. The shell-based approach is easier to debug and doesn't require build steps.

2. No PR Creation: Following requirements, the action does NOT create PRs. Users control commit/PR workflow, allowing maximum flexibility.

3. Version Compatibility: The action adapts to different StructKit versions. Flags like --no-hooks, --non-interactive, --diff, and --dry-run are opt-in to support various StructKit versions.

4. Flexible Installation: Supports PyPI versions, git URLs, and "latest" to accommodate different deployment strategies.

5. Drift Detection: fail_on_diff input enables treating structure drift as a CI failure.

Testing

The action includes a test workflow (.github/workflows/test.yml) that validates:

• ✅ Validate command
• ✅ Generate with dry-run
• ✅ Real file generation with verification
• ✅ Custom version installation from git

All tests passing! 🎉

What's NOT Included

As per requirements:

• ❌ No built-in PR creation (users control this)
• ❌ No workflow-level orchestration (this is a step, not a job)

Marketplace Ready

This action is ready to be:

• Used via commit SHA: httpdss/struct-action@e00eeee
• Tagged and released for version-based usage
• Published to GitHub Marketplace

Checklist

• ✅ action.yml with all required inputs/outputs
• ✅ README with copy-paste examples
• ✅ Test workflow (all passing)
• ✅ Example workflows
• ✅ License file
• ✅ No trailing whitespace
• ✅ Pinned action versions
• ✅ Version compatibility handling
• ✅ No PR creation logic (by design)

Next Steps

After merge:

1. Tag the release (e.g., v1.0.0)
2. Create GitHub release
3. Optionally publish to Marketplace
4. Update README with specific version/SHA recommendations

---

Ready for review! Users can test with:

uses: httpdss/struct-action@e00eeee

  

[httpdss]

@cursoragent make sure actions/checkout uses v7 and not v4

[cursor]

Done! I've updated all actions/checkout references from v4 to v7 across the entire repository:

Updated files:

• ✅ .github/workflows/test.yml (4 occurrences)
• ✅ action.yml (1 occurrence)
• ✅ README.md (7 occurrences in examples)
• ✅ examples/validate-pr.yml (1 occurrence)
• ✅ examples/drift-detection.yml (1 occurrence)
• ✅ examples/generate-and-commit.yml (1 occurrence)
• ✅ examples/scheduled-check.yml (1 occurrence)
• ✅ examples/custom-structures.yml (1 occurrence)

Total: 17 occurrences updated from actions/checkout@v4 to actions/checkout@v7

The changes have been committed and pushed to the PR branch.