[sync] Synchronize funding metadata (#56) (#113)

* [sync] Synchronize funding metadata (#56)

* Update wiki submodule pointer for PR #113

* [funding] Normalize composer sync output (#56)

* Update wiki submodule pointer for PR #113

---------

Co-authored-by: github-actions <41898282+github-actions[bot]@users.noreply.github.com>

Author: coisa

.github/FUNDING.yml

@@ -1,3 +1,3 @@
 github: php-fast-forward
 custom:
-  - https://www.paypal.com/donate/?business=JLDAF45XZ8D84
+  - 'https://www.paypal.com/donate/?business=JLDAF45XZ8D84'

.github/wiki

@@ -84,6 +84,10 @@ composer reports --target=.dev-tools --coverage=.dev-tools/coverage
 # Synchronize packaged agent skills into .agents/skills
 composer skills
 
+# Synchronize Composer funding metadata with .github/FUNDING.yml
+composer funding
+composer funding --dry-run
+
 # Merges and synchronizes .gitignore files
 composer gitignore
 
@@ -117,6 +121,11 @@ The `metrics` command ships with `phpmetrics/phpmetrics` as a direct
 dependency of `fast-forward/dev-tools`, so consumer repositories can generate
 metrics reports without extra setup.
 
+The `funding` command keeps supported `composer.json` funding entries aligned
+with `.github/FUNDING.yml`, including GitHub Sponsors handles and `custom`
+URLs, while preserving unsupported providers in place and re-running
+`composer normalize` after manifest updates.
+
 The `skills` command keeps `.agents/skills` aligned with the packaged Fast
 Forward skill set. It creates missing links, repairs broken links, and
 preserves existing non-symlink directories. The `dev-tools:sync` command calls
@@ -138,8 +147,9 @@ source of truth.
 | `composer metrics` | Runs PhpMetrics for the current project and generates requested report artifacts. |
 | `composer docs` | Builds the HTML documentation site from PSR-4 code and `docs/`. |
 | `composer skills` | Creates or repairs packaged skill links in `.agents/skills`. |
+| `composer funding` | Synchronizes managed funding metadata between `composer.json` and `.github/FUNDING.yml`. |
 | `composer gitattributes` | Manages export-ignore rules in `.gitattributes`. |
-| `composer dev-tools:sync` | Updates scripts, workflow stubs, `.editorconfig`, `.gitignore`, `.gitattributes`, wiki setup, and packaged skills. |
+| `composer dev-tools:sync` | Updates scripts, funding metadata, workflow stubs, `.editorconfig`, `.gitignore`, `.gitattributes`, wiki setup, and packaged skills. |
 
 ## 🔌 Integration
 

README.md

@@ -26,6 +26,16 @@
         "source": "https://github.com/php-fast-forward/dev-tools",
         "docs": "https://php-fast-forward.github.io/dev-tools/"
     },
+    "funding": [
+        {
+            "type": "github",
+            "url": "https://github.com/sponsors/php-fast-forward"
+        },
+        {
+            "type": "custom",
+            "url": "https://www.paypal.com/donate/?business=JLDAF45XZ8D84"
+        }
+    ],
     "require": {
         "php": "^8.3",
         "composer-plugin-api": "^2.0",
@@ -65,6 +75,7 @@
         "symfony/process": "^7.4 || ^8.0",
         "symfony/var-dumper": "^7.4 || ^8.0",
         "symfony/var-exporter": "^7.4 || ^8.0",
+        "symfony/yaml": "^7.4 || ^8.0",
         "symplify/easy-coding-standard": "^13.0",
         "thecodingmachine/safe": "^3.4",
         "twig/twig": "^3.24"

composer.json

@@ -44,6 +44,9 @@ dependencies through constructor injection. The architecture uses
    * - ``FastForward\DevTools\Console\Command\SkillsCommand``
      - ``skills``
      - Synchronizes packaged agent skills into ``.agents/skills``.
+   * - ``FastForward\DevTools\Console\Command\FundingCommand``
+     - ``funding``
+     - Synchronizes managed funding metadata between Composer and GitHub files.
    * - ``FastForward\DevTools\Console\Command\SyncCommand``
      - ``dev-tools:sync``
      - Synchronizes consumer-facing scripts, automation assets, and packaged

docs/api/commands.rst

@@ -0,0 +1,107 @@
+funding
+=======
+
+Synchronizes funding metadata between ``composer.json`` and
+``.github/FUNDING.yml``.
+
+Description
+-----------
+
+The ``funding`` command merges supported funding metadata declared in Composer
+and GitHub formats so both files stay aligned:
+
+1. Composer ``funding`` entries with ``type=github`` are normalized to GitHub
+   Sponsors handles in ``.github/FUNDING.yml``.
+2. Composer ``funding`` entries with ``type=custom`` are normalized to
+   ``custom`` URLs in ``.github/FUNDING.yml``.
+3. Existing ``github`` and ``custom`` entries from ``.github/FUNDING.yml`` are
+   mirrored back into ``composer.json``.
+4. Unsupported providers are preserved in their original format.
+
+Usage
+-----
+
+.. code-block:: bash
+
+   composer funding
+   composer funding [options]
+   composer dev-tools funding -- [options]
+   vendor/bin/dev-tools funding [options]
+
+Options
+-------
+
+``--composer-file`` (optional)
+   Path to the Composer manifest to synchronize. Default:
+   ``Factory::getComposerFile()``.
+
+``--funding-file`` (optional)
+   Path to the GitHub funding file to synchronize. Default:
+   ``.github/FUNDING.yml``.
+
+``--dry-run``
+   Preview funding metadata drift without writing files.
+
+``--check``
+   Exit with code ``1`` when synchronized funding metadata would change either
+   file.
+
+``--interactive``
+   Prompt before writing drifted funding metadata files.
+
+Examples
+--------
+
+Synchronize the default files:
+
+.. code-block:: bash
+
+   composer funding
+
+Preview funding drift:
+
+.. code-block:: bash
+
+   composer funding --dry-run
+
+Validate funding metadata in CI:
+
+.. code-block:: bash
+
+   composer funding --check
+
+Use custom paths:
+
+.. code-block:: bash
+
+   composer funding --composer-file=packages/example/composer.json --funding-file=packages/example/.github/FUNDING.yml
+
+Exit Codes
+----------
+
+.. list-table::
+   :header-rows: 1
+
+   * - Code
+     - Meaning
+   * - 0
+     - Success. Funding metadata was already aligned or was updated
+       successfully.
+   * - 1
+     - Failure. ``--check`` detected drift or a write failed.
+
+Behavior
+--------
+
+- Supports GitHub Sponsors handles and ``custom`` URLs as synchronized managed
+  entries.
+- Preserves unsupported Composer funding providers and unsupported GitHub
+  funding YAML keys.
+- Normalizes ``composer.json`` with ``composer normalize`` after applying
+  funding metadata updates.
+- Creates ``.github/FUNDING.yml`` when Composer declares supported funding
+  metadata and the file is missing.
+- Skips writing ``.github/FUNDING.yml`` when neither side declares supported
+  funding metadata.
+- Renders a unified diff during ``--dry-run`` and ``--check`` so local runs and
+  CI logs show the managed changes clearly.

docs/commands/funding.rst

@@ -18,6 +18,7 @@ Detailed documentation for each dev-tools command.
    reports
    skills
    sync
+   funding
    gitignore
    gitattributes
    license

docs/commands/index.rst

@@ -12,12 +12,13 @@ The ``dev-tools:sync`` command synchronizes consumer-facing automation and defau
 2. ``copy-resource`` - copies GitHub Actions workflows
 3. ``copy-resource`` - copies .editorconfig
 4. ``copy-resource`` - copies dependabot.yml
-5. ``wiki --init`` - initializes wiki as submodule
-6. ``gitignore`` - merges .gitignore files
-7. ``gitattributes`` - manages export-ignore rules
-8. ``skills`` - synchronizes packaged skills
-9. ``license`` - generates LICENSE file
-10. ``git-hooks`` - installs Git hooks
+5. ``funding`` - synchronizes ``composer.json`` funding metadata with ``.github/FUNDING.yml``
+6. ``wiki --init`` - initializes wiki as submodule
+7. ``gitignore`` - merges .gitignore files
+8. ``gitattributes`` - manages export-ignore rules
+9. ``skills`` - synchronizes packaged skills
+10. ``license`` - generates LICENSE file
+11. ``git-hooks`` - installs Git hooks
 
 Usage
 -----
@@ -89,13 +90,16 @@ Exit Codes
 Behavior
 ---------
 
-- Updates ``composer.json`` scripts and extra configuration.
+- Updates ``composer.json`` scripts, extra configuration, and managed funding
+  metadata.
 - Copies missing workflow stubs, ``.editorconfig``, and ``dependabot.yml``.
+- Synchronizes supported funding metadata between ``composer.json`` and
+  ``.github/FUNDING.yml``.
 - When ``--overwrite`` is enabled, replaced text resources emit a unified diff
   so terminal sessions and CI logs show what changed.
 - ``--dry-run`` and ``--check`` verify managed-file drift for ``composer.json``,
-  copied resources, ``.gitignore``, ``.gitattributes``, ``LICENSE``, and Git
-  hooks.
+  funding metadata, copied resources, ``.gitignore``, ``.gitattributes``,
+  ``LICENSE``, and Git hooks.
 - ``--interactive`` prompts before replacing drifted managed files when the
   command is running in an interactive terminal.
 - Creates ``.github/wiki`` as a git submodule when missing.

docs/commands/sync.rst

@@ -193,6 +193,28 @@ Important details:
 - it creates missing symlinks and repairs broken ones;
 - it preserves an existing non-symlink directory instead of overwriting it.
 
+``funding``
+-----------
+
+Synchronizes supported funding metadata between Composer and GitHub formats.
+
+.. code-block:: bash
+
+   composer funding
+   composer funding --dry-run
+   composer funding --check
+
+Important details:
+
+- it keeps ``composer.json`` ``funding`` entries and ``.github/FUNDING.yml`` in
+  sync for GitHub Sponsors and ``custom`` URLs;
+- it preserves unsupported Composer funding providers and unsupported YAML
+  keys instead of rewriting them;
+- it creates ``.github/FUNDING.yml`` when Composer already declares supported
+  funding metadata;
+- it supports ``--dry-run``, ``--check``, and ``--interactive`` so funding
+  drift can be surfaced in CI and reviewed locally.
+
 ``dev-tools:sync``
 ------------------
 
@@ -206,6 +228,8 @@ Important details:
 
 - it updates ``composer.json`` scripts and
   ``extra.grumphp.config-default-path``;
+- it calls ``funding`` so supported funding metadata stays aligned between
+  ``composer.json`` and ``.github/FUNDING.yml``;
 - it copies missing workflow stubs, ``.editorconfig``, and ``dependabot.yml``;
 - it creates ``.github/wiki`` as a git submodule when the directory is
   missing.