imageflow — Cursor Rules

This rule describes the Continuous Integration and Deployment (CI/CD) workflow for the Imageflow project, primarily defined in .github/workflows/ci.yml and utilizing helper scripts within the ci/ directory.

• Triggers: Runs on pushes to any branch, pull requests, manual dispatch (workflow_dispatch), and automatically deploys on new GitHub Releases (on.release.types: [published]). • Matrix Builds: Uses a comprehensive GitHub Actions matrix strategy (jobs.build.strategy.matrix) to build and test across various operating systems (Linux, macOS, Windows), architectures (x64, arm64, x86), and Rust targets (GNU, MSVC, MUSL), including cross-compilation via houseabsolute/actions-rust-cross. • Testing: • Executes cargo test for each matrix entry. • Includes GLIBC version compatibility checks using ci/check-glibc.sh for specific Linux builds (matrix.max-glibc). • Runs imageflow_tool diagnose for native (non-cross) builds. • Artifact Packaging: • Creates platform-specific archives (.zip/.tar.gz) containing binaries and licenses using ci/pack_artifacts.sh. Archives are stored in ./artifacts/github/ (for GitHub Releases) and ./artifacts/upload/ (for S3). • Generates NuGet packages (.nupkg) using scripts in ci/pack_nuget/: • pack.sh: Creates runtime-specific packages (Imageflow.NativeRuntime.{rid}, Imageflow.NativeTool.{rid}) for each build matrix entry (excluding static/MUSL builds). Output to ${REL_NUGET_OUTPUT_DIR} (artifacts/nuget/). Uploaded as GitHub artifacts (nuget-packages-{matrix.package-suffix}). • pack_meta.sh: Creates meta-packages (e.g., Imageflow.NativeRuntime.All, Imageflow.Net.All) in the separate nuget-meta-packages job. • Builds Docker images (imazen/imageflow_tool, imazen/imageflow_tool-arm64) for MUSL targets using docker/build-push-action. • Deployment (Triggered by GitHub Release): • The ALLOW_PUBLISH environment variable controls deployment steps (github.event_name == 'release'). • Uploads archives from ./artifacts/github/ to GitHub Releases. • Uploads archives and potentially NuGet packages from ./artifacts/upload/ to AWS S3 ($IMAGEFLOW_RELEASE_BUCKET). Includes verification checks. • Pushes Docker images to Docker Hub. • The nuget-meta-packages job downloads all .nupkg artifacts from the build job runs, builds meta-packages, and then: • Uploads all .nupkg files to S3 (nuget/{version}/). • Publishes all .nupkg files to NuGet.org (controlled by secrets.NUGET_UPLOAD_NUGET). • Publishes all .nupkg files to GitHub Packages (controlled by secrets.NUGET_UPLOAD_GITHUB). • Environment Variables: Relies heavily on environment variables, many set dynamically based on the build matrix (e.g., TARGET_DIR, TAG_SHA_SUFFIX, RUSTFLAGS, LIBIMAGEFLOW_DYNAMIC, ALLOW_PUBLISH). Secrets are used for deployment credentials. • Conditional Logic: Uses if: conditions extensively to control steps based on the matrix configuration (e.g., matrix.cross, matrix.static, matrix.max-glibc), event type (github.event_name == 'release'), and secrets.

• ci/check-glibc.sh: Checks compiled library against maximum allowed GLIBC version. • ci/pack_artifacts.sh: Packages binaries, licenses, etc., into .zip/.tar.gz archives for releases and S3. • ci/pack_nuget/pack.sh: Creates runtime-specific NuGet packages. • ci/pack_nuget/pack_meta.sh: Creates NuGet meta-packages. • ci/pack_nuget/upload_nuget.sh: Uploads NuGet packages to nuget.org, handling potential failures and deletions. • ci/pack_nuget/tests/run_all_tests.sh: Runs tests related to NuGet packaging early in the workflow. (Note: Other scripts exist within ci/ subdirectories like cloud/, nixtools/, wintools/, packaging_extras/ but are not directly called by the main steps in .github/workflows/ci.yml.)

| Directory | Purpose | Created By | Used By | | :----------------------------- | :----------------------------------------------------------------------------------------------------- | :------------------------------------------ | :---------------------------------------------------------------------------------------------- | | ./target/{target_triple}/ | Standard Cargo build output directory for a specific target. | cargo build/test, cross build/test | cargo, cross, check-glibc.sh, packaging scripts (REL_BINARIES_DIR depends on this) | | ./target/{target_triple}/{profile}/ | Contains the actual compiled binaries (e.g., release/). ($REL_BINARIES_DIR) | cargo build/test, cross build/test | check-glibc.sh, pack_artifacts.sh, pack_nuget/pack.sh, imageflow_tool diagnose, Docker copy | | ./artifacts/ | Root directory for storing intermediate and final packaged artifacts. | CI Steps (mkdir), Packaging scripts | Artifact upload/download steps | | ./artifacts/github/ | Contains .zip/.tar.gz archives intended for GitHub Releases. | pack_artifacts.sh | upload-to-github-release action | | ./artifacts/upload/ | Contains artifacts intended for S3 upload (archives, potentially NuGet). | pack_artifacts.sh, (REL_NUGET_ARCHIVE_DIR) | S3 upload action, Verification step | | ./artifacts/nuget/ | Contains generated .nupkg files. ($REL_NUGET_OUTPUT_DIR) | CI Step (mkdir), pack_nuget/*.sh | Artifact upload/download, upload_nuget.sh, GitHub Packages upload | | ./ci/ | Contains helper scripts for packaging, testing, and checks. | Repo | Various CI steps in .github/workflows/ci.yml | | ./docker/imageflow_tool/ | Contains Dockerfile and context (copied binary) for building the tool image. | Repo, CI Step (copy binary) | Docker build steps |