🐞 Bug Report: package install/update breaks when release artifacts.package is a single object instead of an array

[kasparsd]

Detailed Description

The FAIR plugin appears to handle the release artifacts.package field inconsistently.

According to the FAIR protocol specification, artifact type values may be either:

• a single object
• a list of objects

In practice, some repositories publish artifacts.package as a single object when there is only one package artifact, while others publish it as a one-item array. Both forms appear to be valid per spec.

The plugin currently works with one form in some code paths and assumes the array form in others. This causes warnings and failed package handling when a repository returns artifacts.package as an object.

Expected Behavior

The plugin should accept both valid FAIR protocol shapes for artifacts.package:

• a single object
• an array of objects

Package install, update checks, and download handling should work regardless of which valid shape the repository returns.

Current Behavior

When a repository returns artifacts.package as an object, the plugin attempts to access it as an array and triggers PHP warnings similar to:

Uncaught Error: Cannot use object of type stdClass as array
in /wp-content/plugins/fair-plugin/inc/packages/namespace.php on line 750

Call stack:

    FAIR\Packages\get_package_data()
    wp-content/plugins/fair-plugin/inc/updater/class-updater.php:276
    FAIR\Updater\Updater::update_site_transient()
    wp-content/plugins/fair-plugin/inc/updater/class-updater.php:230
    FAIR\Updater\Updater::handle_update_plugins_transient()
    wp-includes/class-wp-hook.php:343
    WP_Hook::apply_filters()
    wp-includes/plugin.php:205
    apply_filters()
    wp-includes/option.php:2622
    get_site_transient()
    wp-includes/update.php:946
    wp_get_update_data()
    wp-admin/menu.php:38
    require('/var/www/vhosts/kons...ic/wp-admin/menu.php')
    wp-admin/admin.php:163
    require_once('/var/www/vhosts/kons...c/wp-admin/admin.php')
    wp-admin/index.php:10

The logged metadata shows two valid but different structures from real repositories:

Array form:

"package": [
  {
    "id": "main",
    "url": "https://github.com/fairpm/fair-plugin/releases/download/1.4.0/fair-plugin-1.4.0.zip",
    "content-type": "application/zip",
    "signature": "...",
    "checksum": "sha256:..."
  }
]

Object form:

"package": {
  "url": "https://updates.wpelevator.com/wp-json/update-pilot/v1/download/wpelevator/update-pilot?version=0.5.2",
  "content-type": "application/zip",
  "signature": "...",
  "checksum": "sha256:..."
}

Steps to Reproduce

1. Install FAIR plugin on a WordPress site.
2. Add or query a FAIR package whose metadata returns releases[].artifacts.package as a single object instead of an array.
3. Trigger package lookup, install, or update flow.
4. Observe PHP warnings and/or broken handling of the package artifact.

Context (Environment)

This affects interoperability with FAIR repositories that publish a spec-valid singleton object for artifacts.package.

In this case, the issue was observed with metadata from:

• https://updates.wpelevator.com/wp-json/update-pilot/v1/fair/package/did:plc:etmyqc6vq2ruw7eltvpapvjk
• https://github.com/fairpm/fair-plugin/releases/latest/download/fair-metadata.json

The first returns package as an object, while the second returns it as an array.

This makes FAIR plugin behavior depend on repository serialization style rather than the protocol rules.

Possible Solution

Normalize artifacts.package internally before use so the rest of the code can operate on a single consistent shape.

For example:

• if package is an object, wrap it in a one-element array
• if package is already an array, leave it unchanged

Alternatively, all call sites could explicitly handle both forms, but normalization at parse time is likely safer and less error-prone.

Possible Implementation

Update metadata/release parsing so artifact values that are allowed by spec as “object or list of objects” are normalized when constructing the internal document model.

This would likely be best done once during release document parsing rather than at each consumer site.

It would also be useful to add regression tests covering:

• artifacts.package as a single object
• artifacts.package as a one-item array
• any locale-specific/multi-artifact array cases already supported by the plugin