sequenceDiagram
    actor Developer
    participant GitHubActions as GitHub_Actions_Workflow
    participant Job as Publish_Binary_Job
    participant Shell as Publish_Step_Shell
    participant FS as Filesystem_Artifacts
    participant Script as publish_mjs
    participant NPM as NPM_Registry

    Developer->>GitHubActions: Push tag / trigger release
    GitHubActions->>Job: Start matrix job (os, arch, tool)
    Job->>Shell: Run Publish_${os}-${arch}_Binary step

    Shell->>Shell: Set TOOL, PLATFORM, ARCH from matrix
    Shell->>Shell: Validate TOOL value (allowed chars)
    Shell->>Shell: Validate PLATFORM value (allowed chars)
    Shell->>Shell: Validate ARCH value (allowed chars)
    alt Invalid matrix value
        Shell-->>Job: Exit 1 (invalid TOOL/PLATFORM/ARCH)
        Job-->>GitHubActions: Mark job as failed
        GitHubActions-->>Developer: Report workflow failure
    else Matrix values valid
        Shell->>Shell: Compute PACKAGE_DIR
        Shell->>FS: Check PACKAGE_DIR exists and is directory
        alt PACKAGE_DIR missing
            Shell-->>Job: Exit 1 (missing PACKAGE_DIR)
            Job-->>GitHubActions: Mark job as failed
        else PACKAGE_DIR exists
            Shell->>FS: Resolve ABS_PACKAGE_DIR via realpath
            Shell->>FS: Resolve ABS_EXPECTED_ROOT for ./@foundry-rs
            Shell->>Shell: Verify ABS_PACKAGE_DIR prefix is ABS_EXPECTED_ROOT
            alt PACKAGE_DIR outside expected root
                Shell-->>Job: Exit 1 (path traversal detected)
                Job-->>GitHubActions: Mark job as failed
            else PACKAGE_DIR within expected root
                Shell->>FS: List contents of PACKAGE_DIR
                Shell->>FS: Check PACKAGE_DIR/package.json exists
                alt package.json missing
                    Shell-->>Job: Exit 1 (sanity check failed)
                    Job-->>GitHubActions: Mark job as failed
                else package.json present
                    Shell->>Script: bun ./scripts/publish.mjs PACKAGE_DIR
                    Script->>NPM: Publish package
                    NPM-->>Script: Publish result
                    Script-->>Shell: Exit status
                    Shell-->>Job: Complete step
                    Job-->>GitHubActions: Job successful
                    GitHubActions-->>Developer: Report publish success
                end
            end
        end
    end

flowchart TD
    A[Start Publish Binary step] --> B[Set TOOL from matrix.tool]
    B --> C[Set PLATFORM from matrix.os]
    C --> D[Set ARCH from matrix.arch]

    D --> E{TOOL only has a-z A-Z 0-9 _ - and not empty}
    E -->|No| Z1[Fail workflow: invalid TOOL] --> Z[End]
    E -->|Yes| F{PLATFORM only has a-z A-Z 0-9 _ - and not empty}
    F -->|No| Z2[Fail workflow: invalid PLATFORM] --> Z
    F -->|Yes| G{ARCH only has a-z A-Z 0-9 _ - and not empty}
    G -->|No| Z3[Fail workflow: invalid ARCH] --> Z
    G -->|Yes| H[Compute PACKAGE_DIR = ./@foundry-rs/TOOL-PLATFORM-ARCH]

    H --> I{PACKAGE_DIR exists and is directory}
    I -->|No| Z4[Fail workflow: package directory does not exist] --> Z
    I -->|Yes| J[ABS_PACKAGE_DIR = realpath PACKAGE_DIR]

    J --> K[ABS_EXPECTED_ROOT = realpath ./@foundry-rs]
    K --> L{ABS_PACKAGE_DIR starts with ABS_EXPECTED_ROOT/}
    L -->|No| Z5[Fail workflow: directory outside expected root] --> Z
    L -->|Yes| M[List PACKAGE_DIR contents with ls -la]

    M --> N{PACKAGE_DIR/package.json exists}
    N -->|No| Z6[Fail workflow: package.json missing] --> Z
    N -->|Yes| O[Run bun ./scripts/publish.mjs PACKAGE_DIR]
    O --> P[Echo Published @foundry-rs/TOOL-PLATFORM-ARCH]
    P --> Z[End]