[github] Add CODEOWNERS sync support (#67) (#127)

* [github] Add CODEOWNERS sync support (#67)

* [github] Refine CODEOWNERS inference rules (#67)

* [github] Rename CODEOWNERS template resource (#67)

* [github] Record project CODEOWNERS metadata (#67)

* [github] Normalize CODEOWNERS template formatting (#67)

* [github] Normalize CODEOWNERS command syntax (#67)

* Update wiki submodule pointer for PR #127

---------

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

Author: coisa

.github/CODEOWNERS

@@ -0,0 +1,12 @@
+# Generated by fast-forward/dev-tools
+#
+# Review the generated owners before committing this file.
+#
+# When no GitHub owners can be inferred automatically, replace the placeholder
+# example below with the usernames, teams, or emails that should review
+# changes in the consumer repository.
+#
+# Example:
+# * @your-github-user @your-org/platform-team
+
+* @php-fast-forward @coisa

.github/wiki

@@ -7,6 +7,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Add CODEOWNERS generation and sync support for consumer repositories (#67)
+
 ## [1.13.0] - 2026-04-19
 
 ### Added

CHANGELOG.md

@@ -27,6 +27,8 @@ across Fast Forward libraries.
   version inference, release promotion, and release-note rendering commands
 - Ships shared workflow stubs, `.editorconfig`, Dependabot configuration, and
   other onboarding defaults for consumer repositories
+- Generates `.github/CODEOWNERS` files from local project metadata instead of
+  shipping repository-specific owners into consumers
 - Synchronizes packaged agent skills into consumer `.agents/skills`
   directories using safe link-based updates
 - Works both as a Composer plugin and as a local binary
@@ -111,6 +113,10 @@ composer skills
 composer funding
 composer funding --dry-run
 
+# Generate .github/CODEOWNERS from composer.json metadata
+composer codeowners
+composer codeowners --interactive
+
 # Merges and synchronizes .gitignore files
 composer gitignore
 
@@ -163,6 +169,11 @@ 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 `codeowners` command generates `.github/CODEOWNERS` from local
+`composer.json` metadata. It prefers explicit GitHub profile URLs from author
+metadata, falls back to commented suggestions from support metadata, and can
+prompt for owners when `--interactive` is used in a terminal.
+
 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
@@ -203,8 +214,9 @@ source of truth.
 | `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 codeowners` | Generates managed `.github/CODEOWNERS` content from local repository metadata. |
 | `composer gitattributes` | Manages export-ignore rules in `.gitattributes`. |
-| `composer dev-tools:sync` | Updates scripts, funding metadata, workflow stubs, `.editorconfig`, `.gitignore`, `.gitattributes`, wiki setup, and packaged skills. |
+| `composer dev-tools:sync` | Updates scripts, CODEOWNERS, funding metadata, workflow stubs, `.editorconfig`, `.gitignore`, `.gitattributes`, wiki setup, and packaged skills. |
 
 ## 🔌 Integration
 
@@ -228,9 +240,9 @@ so agents can discover the packaged skills shipped with this repository.
   orchestration commands such as `standards` dispatch other commands through
   the console application itself.
 - `Consumer Sync Pipeline` - `dev-tools:sync` refreshes `composer.json`,
-  funding metadata, workflow stubs, repository defaults, git metadata files,
-  packaged Git hooks, and, in normal mode, the wiki submodule plus packaged
-  skills.
+  CODEOWNERS, funding metadata, workflow stubs, repository defaults, git
+  metadata files, packaged Git hooks, and, in normal mode, the wiki submodule
+  plus packaged skills.
 
 ## 🤝 Contributing
 

README.md

@@ -16,7 +16,9 @@
     "authors": [
         {
             "name": "Felipe Sayão Lobato Abreu",
-            "email": "github@mentordosnerds.com"
+            "email": "github@mentordosnerds.com",
+            "homepage": "https://github.com/coisa",
+            "role": "Maintainer"
         }
     ],
     "homepage": "https://github.com/php-fast-forward/",

composer.json

@@ -66,6 +66,9 @@ subprocess execution is needed.
    * - ``FastForward\DevTools\Console\Command\FundingCommand``
      - ``funding``
      - Synchronizes managed funding metadata between Composer and GitHub files.
+   * - ``FastForward\DevTools\Console\Command\CodeOwnersCommand``
+     - ``codeowners``
+     - Generates managed ``.github/CODEOWNERS`` content from project metadata.
    * - ``FastForward\DevTools\Console\Command\SyncCommand``
      - ``dev-tools:sync``
      - Synchronizes consumer-facing scripts, automation assets, and packaged

docs/api/commands.rst

@@ -0,0 +1,81 @@
+codeowners
+==========
+
+Generates ``.github/CODEOWNERS`` from local repository metadata.
+
+Description
+-----------
+
+The ``codeowners`` command creates or refreshes a managed ``CODEOWNERS`` file
+for the current repository. It prefers explicit GitHub profile URLs from
+``composer.json`` authors metadata, falls back to commented suggestions from
+``composer.json`` support metadata, and can prompt for owners when interactive
+input is enabled.
+
+Usage
+-----
+
+.. code-block:: bash
+
+   composer codeowners
+   composer codeowners [options]
+
+Options
+-------
+
+``--file``
+   Target path to manage. Defaults to ``.github/CODEOWNERS``.
+
+``--overwrite, -o``
+   Replace an existing CODEOWNERS file instead of preserving it.
+
+``--dry-run``
+   Preview managed-file drift without writing changes.
+
+``--check``
+   Report managed-file drift and exit with code ``1`` when CODEOWNERS needs an
+   update.
+
+``--interactive``
+   Prompt for owners when metadata inference is insufficient and confirm before
+   replacing an existing file.
+
+Examples
+--------
+
+Generate CODEOWNERS from the current repository metadata:
+
+.. code-block:: bash
+
+   composer codeowners
+
+Preview drift without writing:
+
+.. code-block:: bash
+
+   composer codeowners --dry-run
+
+Fail in CI when CODEOWNERS needs an update:
+
+.. code-block:: bash
+
+   composer codeowners --check
+
+Prompt for explicit owners when metadata is incomplete:
+
+.. code-block:: bash
+
+   composer codeowners --interactive
+
+Behavior
+--------
+
+- It reads author homepages from ``composer.json`` and converts GitHub profile
+  URLs into ``@owner`` handles.
+- When direct owners cannot be inferred, it uses ``composer.json`` support
+  metadata to add a commented suggestion instead of writing someone else's
+  ownership rules into the consumer repository.
+- In interactive terminals, ``--interactive`` lets maintainers provide
+  space-separated owners for the catch-all ``*`` rule before writing the file.
+- By default, an existing ``.github/CODEOWNERS`` file is preserved unless
+  ``--overwrite``, ``--dry-run``, ``--check``, or ``--interactive`` is used.

docs/commands/codeowners.rst

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

docs/commands/index.rst

@@ -12,13 +12,14 @@ The ``dev-tools:sync`` command synchronizes consumer-facing automation and defau
 2. ``copy-resource`` - copies GitHub Actions workflows, including changelog automation
 3. ``copy-resource`` - copies .editorconfig
 4. ``copy-resource`` - copies dependabot.yml
-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
+5. ``codeowners`` - generates ``.github/CODEOWNERS`` from local metadata
+6. ``funding`` - synchronizes ``composer.json`` funding metadata with ``.github/FUNDING.yml``
+7. ``wiki --init`` - initializes wiki as submodule
+8. ``gitignore`` - merges .gitignore files
+9. ``gitattributes`` - manages export-ignore rules
+10. ``skills`` - synchronizes packaged skills
+11. ``license`` - generates LICENSE file
+12. ``git-hooks`` - installs Git hooks
 
 Usage
 -----
@@ -27,7 +28,6 @@ Usage
 
    composer dev-tools:sync
    composer dev-tools:sync [options]
-   vendor/bin/dev-tools dev-tools:sync [options]
 
 Options
 -------
@@ -90,17 +90,20 @@ Exit Codes
 Behavior
 ---------
 
-- Updates ``composer.json`` scripts, extra configuration, and managed funding
-  metadata.
+- Updates ``composer.json`` scripts, extra configuration, managed funding
+  metadata, and managed ``.github/CODEOWNERS`` content.
 - Copies missing workflow stubs, including tests, reports, wiki, and changelog
   automation, plus ``.editorconfig`` and ``dependabot.yml``.
+- Generates ``.github/CODEOWNERS`` from local metadata and preserves existing
+  ownership rules by default unless ``--overwrite`` or an explicit preview
+  mode is used.
 - 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``,
-  funding metadata, copied resources, ``.gitignore``, ``.gitattributes``,
-  ``LICENSE``, and Git hooks.
+  ``.github/CODEOWNERS``, 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

@@ -239,6 +239,28 @@ Important details:
 - it supports ``--dry-run``, ``--check``, and ``--interactive`` so funding
   drift can be surfaced in CI and reviewed locally.
 
+``codeowners``
+--------------
+
+Generates managed CODEOWNERS files from repository metadata.
+
+.. code-block:: bash
+
+   composer codeowners
+   composer codeowners --dry-run
+   composer codeowners --interactive
+
+Important details:
+
+- it inspects ``composer.json`` author homepages to infer GitHub handles for
+  ``.github/CODEOWNERS``;
+- when direct ownership cannot be inferred, it renders a commented fallback
+  instead of copying hard-coded owners into the consumer repository;
+- ``--interactive`` lets maintainers provide explicit owners before writing the
+  catch-all ``*`` rule;
+- ``dev-tools:sync`` runs ``codeowners`` automatically alongside the other
+  consumer bootstrap steps.
+
 ``dev-tools:sync``
 ------------------
 
@@ -255,6 +277,8 @@ Important details:
 - 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 calls ``codeowners`` to generate ``.github/CODEOWNERS`` from local
+  metadata;
 - it creates ``.github/wiki`` as a git submodule when the directory is
   missing.
 - it calls ``gitignore`` to merge the canonical .gitignore with the project's